blockworks-foundation
/
solana
mirror of https://github.com/blockworks-foundation/solana.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs cleanup (#16964) 

* Run lint:fix on docs

* Update dependencies

* Run prettier

* Run lint
This commit is contained in:
Justin Starry 2021-04-30 16:20:56 +08:00 committed by GitHub
parent 3d98321b38
commit 545e037e38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
53 changed files with 23895 additions and 5418 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/.eslintignore Normal file
View File

@ -0,0 +1,8 @@
node_modules
build
static
html
# FIXME
src/pages/index.js
src/theme/Footer/index.js

7
docs/.prettierignore Normal file
View File

@ -0,0 +1,7 @@
.docusaurus
build
html
static
# prettier interferes with the json response too much
src/developing/clients/jsonrpc-api.md

7
docs/README.md
View File

@ -29,12 +29,13 @@ $ docs/build.sh
```
### CI Build Flow
The docs are built and published in Travis CI with the `docs/build.sh` script.
On each PR, the docs are built, but not published.
In each post-commit build, docs are built and published using `vercel` to their
respective domain depending on the build branch.
- Master branch docs are published to `edge.docs.solana.com`
- Beta branch docs are published to `beta.docs.solana.com`
- Latest release tag docs are published to `docs.solana.com`
- Master branch docs are published to `edge.docs.solana.com`
- Beta branch docs are published to `beta.docs.solana.com`
- Latest release tag docs are published to `docs.solana.com`

260
docs/docusaurus.config.js
View File

@ -1,135 +1,135 @@
const math = require('remark-math');
const katex = require('rehype-katex');
const math = require("remark-math");
const katex = require("rehype-katex");
module.exports = {
title: "Solana Docs",
tagline:
title: "Solana Docs",
tagline:
"Solana is an open source project implementing a new, high-performance, permissionless blockchain.",
url: "https://docs.solana.com",
baseUrl: "/",
favicon: "img/favicon.ico",
organizationName: "solana-labs", // Usually your GitHub org/user name.
projectName: "solana", // Usually your repo name.
onBrokenLinks: 'throw',
stylesheets: [
{
href: '/katex/katex.min.css',
type: 'text/css',
integrity:
'sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X',
crossorigin: 'anonymous',
},
],
themeConfig: {
navbar: {
logo: {
alt: "Solana Logo",
src: "img/logo-horizontal.svg",
srcDark: "img/logo-horizontal-dark.svg",
},
items: [
{
href: "https://spl.solana.com",
label: "Program Library »",
position: "left",
},
{
to: "developing/programming-model/overview",
label: "Develop",
position: "left",
},
{
to: "running-validator",
label: "Validate",
position: "left",
},
{
to: "integrations/exchange",
label: "Integrate",
position: "left",
},
{
to: "cluster/overview",
label: "Learn",
position: "left",
},
{
href: "https://discordapp.com/invite/pquxPsq",
label: "Chat",
position: "right",
},
{
href: "https://github.com/solana-labs/solana",
label: "GitHub",
position: "right",
},
],
},
algolia: {
// This API key is "search-only" and safe to be published
apiKey: "d58e0d68c875346d52645d68b13f3ac0",
indexName: "solana",
},
footer: {
style: "dark",
links: [
{
title: "Docs",
items: [
{
label: "Introduction",
to: "introduction",
},
{
label: "Tour de SOL",
to: "tour-de-sol",
},
],
},
{
title: "Community",
items: [
{
label: "Discord",
href: "https://discordapp.com/invite/pquxPsq",
},
{
label: "Twitter",
href: "https://twitter.com/solana",
},
{
label: "Forums",
href: "https://forums.solana.com",
},
],
},
{
title: "More",
items: [
{
label: "GitHub",
href: "https://github.com/solana-labs/solana",
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} Solana Foundation`,
},
url: "https://docs.solana.com",
baseUrl: "/",
favicon: "img/favicon.ico",
organizationName: "solana-labs", // Usually your GitHub org/user name.
projectName: "solana", // Usually your repo name.
onBrokenLinks: "throw",
stylesheets: [
{
href: "/katex/katex.min.css",
type: "text/css",
integrity:
"sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X",
crossorigin: "anonymous",
},
presets: [
[
"@docusaurus/preset-classic",
{
docs: {
path: "src",
routeBasePath: "/",
sidebarPath: require.resolve("./sidebars.js"),
remarkPlugins: [math],
rehypePlugins: [katex],
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
},
},
],
],
themeConfig: {
navbar: {
logo: {
alt: "Solana Logo",
src: "img/logo-horizontal.svg",
srcDark: "img/logo-horizontal-dark.svg",
},
items: [
{
href: "https://spl.solana.com",
label: "Program Library »",
position: "left",
},
{
to: "developing/programming-model/overview",
label: "Develop",
position: "left",
},
{
to: "running-validator",
label: "Validate",
position: "left",
},
{
to: "integrations/exchange",
label: "Integrate",
position: "left",
},
{
to: "cluster/overview",
label: "Learn",
position: "left",
},
{
href: "https://discordapp.com/invite/pquxPsq",
label: "Chat",
position: "right",
},
{
href: "https://github.com/solana-labs/solana",
label: "GitHub",
position: "right",
},
],
},
algolia: {
// This API key is "search-only" and safe to be published
apiKey: "d58e0d68c875346d52645d68b13f3ac0",
indexName: "solana",
},
footer: {
style: "dark",
links: [
{
title: "Docs",
items: [
{
label: "Introduction",
to: "introduction",
},
{
label: "Tour de SOL",
to: "tour-de-sol",
},
],
},
{
title: "Community",
items: [
{
label: "Discord",
href: "https://discordapp.com/invite/pquxPsq",
},
{
label: "Twitter",
href: "https://twitter.com/solana",
},
{
label: "Forums",
href: "https://forums.solana.com",
},
],
},
{
title: "More",
items: [
{
label: "GitHub",
href: "https://github.com/solana-labs/solana",
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} Solana Foundation`,
},
},
presets: [
[
"@docusaurus/preset-classic",
{
docs: {
path: "src",
routeBasePath: "/",
sidebarPath: require.resolve("./sidebars.js"),
remarkPlugins: [math],
rehypePlugins: [katex],
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
},
},
],
],
};

27501
docs/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

8
docs/package.json
View File

@ -15,13 +15,15 @@
"lint:fix": "npm run lint -- --fix"
},
"dependencies": {
"@docusaurus/core": "^2.0.0-alpha.65",
"@docusaurus/preset-classic": "^2.0.0-alpha.65",
"@docusaurus/theme-search-algolia": "^2.0.0-alpha.32",
"@docusaurus/core": "^2.0.0-alpha.74",
"@docusaurus/preset-classic": "^2.0.0-alpha.74",
"@docusaurus/theme-search-algolia": "^2.0.0-alpha.74",
"babel-eslint": "^10.1.0",
"clsx": "^1.1.1",
"eslint": "^7.3.1",
"eslint-plugin-react": "^7.20.0",
"postcss": "^8.2.13",
"postcss-loader": "^4.2.0",
"prettier": "^2.0.5",
"react": "^16.8.4",
"react-dom": "^16.8.4",

478
docs/sidebars.js
View File

@ -1,247 +1,235 @@
module.exports = {
docs: {
"About": [
"introduction",
"terminology",
"history",
],
"Wallets": [
"wallet-guide",
"wallet-guide/apps",
{
type: "category",
label: "Web Wallets",
items: [
"wallet-guide/web-wallets",
"wallet-guide/solflare",
],
},
{
type: "category",
label: "Hardware Wallets",
items: [
"wallet-guide/ledger-live",
],
},
{
type: "category",
label: "Command-line Wallets",
items: [
"wallet-guide/cli",
"wallet-guide/paper-wallet",
{
type: "category",
label: "Hardware Wallets",
items: [
"wallet-guide/hardware-wallets",
"wallet-guide/hardware-wallets/ledger",
],
},
"wallet-guide/file-system-wallet",
],
},
"wallet-guide/support",
],
"Staking": [
"staking",
"staking/stake-accounts",
],
"Command Line": [
"cli",
"cli/install-solana-cli-tools",
"cli/conventions",
"cli/choose-a-cluster",
"cli/transfer-tokens",
"cli/delegate-stake",
"cli/manage-stake-accounts",
"cli/deploy-a-program",
"offline-signing",
"offline-signing/durable-nonce",
"cli/usage",
],
"Developing": [
{
type: "category",
label: "Programming Model",
items: [
"developing/programming-model/overview",
"developing/programming-model/transactions",
"developing/programming-model/accounts",
"developing/programming-model/runtime",
"developing/programming-model/calling-between-programs",
],
},
{
type: "category",
label: "Clients",
items: [
"developing/clients/jsonrpc-api",
"developing/clients/javascript-api",
"developing/clients/rust-api",
],
},
{
type: "category",
label: "Runtime Facilities",
items: [
"developing/runtime-facilities/programs",
"developing/runtime-facilities/sysvars",
],
},
{
type: "category",
label: "On-chain Programs",
items: [
"developing/on-chain-programs/overview",
"developing/on-chain-programs/developing-rust",
"developing/on-chain-programs/developing-c",
"developing/on-chain-programs/deploying",
"developing/on-chain-programs/debugging",
"developing/on-chain-programs/examples",
"developing/on-chain-programs/faq",
],
},
"developing/backwards-compatibility",
],
"Integrating": ["integrations/exchange"],
"Validating": [
"running-validator",
"running-validator/validator-reqs",
"running-validator/validator-start",
"running-validator/vote-accounts",
"running-validator/validator-stake",
"running-validator/validator-monitor",
"running-validator/validator-info",
{
type: "category",
label: "Incenvitized Testnet",
items: [
"tour-de-sol",
{
type: "category",
label: "Registration",
items: [
"tour-de-sol/registration/how-to-register",
"tour-de-sol/registration/terms-of-participation",
"tour-de-sol/registration/rewards",
"tour-de-sol/registration/confidentiality",
"tour-de-sol/registration/validator-registration-and-rewards-faq",
],
},
{
type: "category",
label: "Participation",
items: [
"tour-de-sol/participation/validator-technical-requirements",
"tour-de-sol/participation/validator-public-key-registration",
"tour-de-sol/participation/steps-to-create-a-validator",
],
},
"tour-de-sol/useful-links",
"tour-de-sol/submitting-bugs",
],
},
"running-validator/validator-troubleshoot",
],
"Clusters": [
"clusters",
"cluster/rpc-endpoints",
"cluster/bench-tps",
"cluster/performance-metrics"
],
"Architecture": [
{
type: "category",
label: "Cluster",
items: [
"cluster/overview",
"cluster/synchronization",
"cluster/leader-rotation",
"cluster/fork-generation",
"cluster/managing-forks",
"cluster/turbine-block-propagation",
"cluster/vote-signing",
"cluster/stake-delegation-and-rewards",
],
},
{
type: "category",
label: "Validator",
items: [
"validator/anatomy",
"validator/tpu",
"validator/tvu",
"validator/blockstore",
"validator/gossip",
"validator/runtime",
],
},
],
"Economics": [
"economics_overview",
{
type: "category",
label: "Inflation Design",
items: [
"inflation/terminology",
"inflation/inflation_schedule",
"inflation/adjusted_staking_yield",
],
},
"transaction_fees",
"storage_rent_economics"
],
"Design Proposals": [
{
type: "category",
label: "Implemented",
items: [
"implemented-proposals/implemented-proposals",
"implemented-proposals/abi-management",
"implemented-proposals/bank-timestamp-correction",
"implemented-proposals/commitment",
"implemented-proposals/durable-tx-nonces",
"implemented-proposals/installer",
"implemented-proposals/instruction_introspection",
"implemented-proposals/leader-leader-transition",
"implemented-proposals/leader-validator-transition",
"implemented-proposals/persistent-account-storage",
"implemented-proposals/readonly-accounts",
"implemented-proposals/reliable-vote-transmission",
"implemented-proposals/rent",
"implemented-proposals/repair-service",
"implemented-proposals/rpc-transaction-history",
"implemented-proposals/snapshot-verification",
"implemented-proposals/staking-rewards",
"implemented-proposals/testing-programs",
"implemented-proposals/tower-bft",
"implemented-proposals/transaction-fees",
"implemented-proposals/validator-timestamp-oracle",
],
},
{
type: "category",
label: "Accepted",
items: [
"proposals/accepted-design-proposals",
"proposals/ledger-replication-to-implement",
"proposals/optimistic-confirmation-and-slashing",
"proposals/vote-signing-to-implement",
"proposals/cluster-test-framework",
"proposals/validator-proposal",
"proposals/simple-payment-and-state-verification",
"proposals/interchain-transaction-verification",
"proposals/snapshot-verification",
"proposals/bankless-leader",
"proposals/slashing",
"proposals/tick-verification",
"proposals/block-confirmation",
"proposals/rust-clients",
"proposals/optimistic_confirmation",
"proposals/embedding-move",
"proposals/rip-curl",
]
},
],
},
docs: {
About: ["introduction", "terminology", "history"],
Wallets: [
"wallet-guide",
"wallet-guide/apps",
{
type: "category",
label: "Web Wallets",
items: ["wallet-guide/web-wallets", "wallet-guide/solflare"],
},
{
type: "category",
label: "Hardware Wallets",
items: ["wallet-guide/ledger-live"],
},
{
type: "category",
label: "Command-line Wallets",
items: [
"wallet-guide/cli",
"wallet-guide/paper-wallet",
{
type: "category",
label: "Hardware Wallets",
items: [
"wallet-guide/hardware-wallets",
"wallet-guide/hardware-wallets/ledger",
],
},
"wallet-guide/file-system-wallet",
],
},
"wallet-guide/support",
],
Staking: ["staking", "staking/stake-accounts"],
"Command Line": [
"cli",
"cli/install-solana-cli-tools",
"cli/conventions",
"cli/choose-a-cluster",
"cli/transfer-tokens",
"cli/delegate-stake",
"cli/manage-stake-accounts",
"cli/deploy-a-program",
"offline-signing",
"offline-signing/durable-nonce",
"cli/usage",
],
Developing: [
{
type: "category",
label: "Programming Model",
items: [
"developing/programming-model/overview",
"developing/programming-model/transactions",
"developing/programming-model/accounts",
"developing/programming-model/runtime",
"developing/programming-model/calling-between-programs",
],
},
{
type: "category",
label: "Clients",
items: [
"developing/clients/jsonrpc-api",
"developing/clients/javascript-api",
"developing/clients/rust-api",
],
},
{
type: "category",
label: "Runtime Facilities",
items: [
"developing/runtime-facilities/programs",
"developing/runtime-facilities/sysvars",
],
},
{
type: "category",
label: "On-chain Programs",
items: [
"developing/on-chain-programs/overview",
"developing/on-chain-programs/developing-rust",
"developing/on-chain-programs/developing-c",
"developing/on-chain-programs/deploying",
"developing/on-chain-programs/debugging",
"developing/on-chain-programs/examples",
"developing/on-chain-programs/faq",
],
},
"developing/backwards-compatibility",
],
Integrating: ["integrations/exchange"],
Validating: [
"running-validator",
"running-validator/validator-reqs",
"running-validator/validator-start",
"running-validator/vote-accounts",
"running-validator/validator-stake",
"running-validator/validator-monitor",
"running-validator/validator-info",
{
type: "category",
label: "Incenvitized Testnet",
items: [
"tour-de-sol",
{
type: "category",
label: "Registration",
items: [
"tour-de-sol/registration/how-to-register",
"tour-de-sol/registration/terms-of-participation",
"tour-de-sol/registration/rewards",
"tour-de-sol/registration/confidentiality",
"tour-de-sol/registration/validator-registration-and-rewards-faq",
],
},
{
type: "category",
label: "Participation",
items: [
"tour-de-sol/participation/validator-technical-requirements",
"tour-de-sol/participation/validator-public-key-registration",
"tour-de-sol/participation/steps-to-create-a-validator",
],
},
"tour-de-sol/useful-links",
"tour-de-sol/submitting-bugs",
],
},
"running-validator/validator-troubleshoot",
],
Clusters: [
"clusters",
"cluster/rpc-endpoints",
"cluster/bench-tps",
"cluster/performance-metrics",
],
Architecture: [
{
type: "category",
label: "Cluster",
items: [
"cluster/overview",
"cluster/synchronization",
"cluster/leader-rotation",
"cluster/fork-generation",
"cluster/managing-forks",
"cluster/turbine-block-propagation",
"cluster/vote-signing",
"cluster/stake-delegation-and-rewards",
],
},
{
type: "category",
label: "Validator",
items: [
"validator/anatomy",
"validator/tpu",
"validator/tvu",
"validator/blockstore",
"validator/gossip",
"validator/runtime",
],
},
],
Economics: [
"economics_overview",
{
type: "category",
label: "Inflation Design",
items: [
"inflation/terminology",
"inflation/inflation_schedule",
"inflation/adjusted_staking_yield",
],
},
"transaction_fees",
"storage_rent_economics",
],
"Design Proposals": [
{
type: "category",
label: "Implemented",
items: [
"implemented-proposals/implemented-proposals",
"implemented-proposals/abi-management",
"implemented-proposals/bank-timestamp-correction",
"implemented-proposals/commitment",
"implemented-proposals/durable-tx-nonces",
"implemented-proposals/installer",
"implemented-proposals/instruction_introspection",
"implemented-proposals/leader-leader-transition",
"implemented-proposals/leader-validator-transition",
"implemented-proposals/persistent-account-storage",
"implemented-proposals/readonly-accounts",
"implemented-proposals/reliable-vote-transmission",
"implemented-proposals/rent",
"implemented-proposals/repair-service",
"implemented-proposals/rpc-transaction-history",
"implemented-proposals/snapshot-verification",
"implemented-proposals/staking-rewards",
"implemented-proposals/testing-programs",
"implemented-proposals/tower-bft",
"implemented-proposals/transaction-fees",
"implemented-proposals/validator-timestamp-oracle",
],
},
{
type: "category",
label: "Accepted",
items: [
"proposals/accepted-design-proposals",
"proposals/ledger-replication-to-implement",
"proposals/optimistic-confirmation-and-slashing",
"proposals/vote-signing-to-implement",
"proposals/cluster-test-framework",
"proposals/validator-proposal",
"proposals/simple-payment-and-state-verification",
"proposals/interchain-transaction-verification",
"proposals/snapshot-verification",
"proposals/bankless-leader",
"proposals/slashing",
"proposals/tick-verification",
"proposals/block-confirmation",
"proposals/rust-clients",
"proposals/optimistic_confirmation",
"proposals/embedding-move",
"proposals/rip-curl",
],
},
],
},
};

26
docs/src/cli/deploy-a-program.md
View File

@ -83,13 +83,13 @@ Data Length: 5216 (0x1460) bytes
holds the program's data (shared object).
- `Authority` is the program's upgrade authority.
- `Last Deployed In Slot` is the slot in which the program was last deployed.
- `Data Length` is the size of the space reserved for deployments. The actual
- `Data Length` is the size of the space reserved for deployments. The actual
space used by the currently deployed program may be less.
### Redeploy a program
A program can be redeployed to the same address to facilitate rapid development,
bug fixes, or upgrades. Matching keypair files are generated once so that
bug fixes, or upgrades. Matching keypair files are generated once so that
redeployments will be to the same program address.
The command looks the same as the deployment command:
@ -99,10 +99,10 @@ solana program deploy <PROGRAM_FILEPATH>
```
By default, programs are deployed to accounts that are twice the size of the
original deployment. Doing so leaves room for program growth in future
redeployments. But, if the initially deployed program is very small (like a
original deployment. Doing so leaves room for program growth in future
redeployments. But, if the initially deployed program is very small (like a
simple helloworld program) and then later grows substantially, the redeployment
may fail. To avoid this, specify a `max_len` that is at least the size (in
may fail. To avoid this, specify a `max_len` that is at least the size (in
bytes) that the program is expected to become (plus some wiggle room).
```bash
@ -117,7 +117,7 @@ is locked up permanently.
### Resuming a failed deploy
If program deployment fails, there will be a hanging intermediate buffer account
that contains a non-zero balance. In order to recoup that balance you may
that contains a non-zero balance. In order to recoup that balance you may
resume a failed deployment by providing the same intermediate buffer to a new
call to `deploy`.
@ -156,8 +156,8 @@ solana program deploy --buffer <KEYPAIR_PATH> <PROGRAM_FILEPATH>
### Closing buffer accounts and reclaiming their lamports
If deployment fails there will be a left over buffer account that holds
lamports. The buffer account can either be used to [resume a
deploy](#resuming-a-failed-deploy) or closed. When closed, the full balance of
lamports. The buffer account can either be used to [resume a
deploy](#resuming-a-failed-deploy) or closed. When closed, the full balance of
the buffer account will be transferred to the recipient's account.
The buffer account's authority must be present to close a buffer account, to
@ -205,9 +205,9 @@ solana program show --buffers --all
### Set a program's upgrade authority
The program's upgrade authority must to be present to deploy a program. If no
The program's upgrade authority must to be present to deploy a program. If no
authority is specified during program deployment, the default keypair is used as
the authority. This is why redeploying a program in the steps above didn't
the authority. This is why redeploying a program in the steps above didn't
require an authority to be explicitly specified.
The authority can be specified during deployment:
@ -262,11 +262,11 @@ solana program dump <ACCOUNT_ADDRESS> <OUTPUT_FILEPATH>
```
The dumped file will be in the same as what was deployed, so in the case of a
shared object, the dumped file will be a fully functional shared object. Note
shared object, the dumped file will be a fully functional shared object. Note
that the `dump` command dumps the entire data space, which means the output file
will have trailing zeros after the shared object's data up to `max_len`.
Sometimes it is useful to dump and compare a program to ensure it matches a
known program binary. The original program file can be zero-extended, hashed,
known program binary. The original program file can be zero-extended, hashed,
and compared to the hash of the dumped file.
```bash
@ -279,7 +279,7 @@ $ sha256sum extended.so dump.so
### Using an intermediary Buffer account
Instead of deploying directly to the program account, the program can be written
to an intermediary buffer account. Intermediary accounts can useful for things
to an intermediary buffer account. Intermediary accounts can useful for things
like multi-entity governed programs where the governing members fist verify the
intermediary buffer contents and then vote to allow an upgrade using it.

4
docs/src/cluster/bench-tps.md
View File

@ -96,13 +96,13 @@ For example
- To enable `info` everywhere and `debug` only in the solana::banking_stage module:
```bash
export RUST_LOG=solana=info,solana::banking_stage=debug
export RUST_LOG=solana=info,solana::banking_stage=debug
```
- To enable BPF program logging:
```bash
export RUST_LOG=solana_bpf_loader=trace
export RUST_LOG=solana_bpf_loader=trace
```
Generally we are using `debug` for infrequent debug messages, `trace` for potentially frequent messages and `info` for performance-related logging.

20
docs/src/cluster/vote-signing.md
View File

@ -24,19 +24,19 @@ The vote signing service consists of a JSON RPC server and a request processor.
1. Register a new validator node
- The request must contain validator's identity \(public key\)
- The request must be signed with the validator's private key
- The service drops the request if signature of the request cannot be verified
- The service creates a new voting asymmetric key for the validator, and returns the public key as a response
- If a validator tries to register again, the service returns the public key from the pre-existing keypair
- The request must contain validator's identity \(public key\)
- The request must be signed with the validator's private key
- The service drops the request if signature of the request cannot be verified
- The service creates a new voting asymmetric key for the validator, and returns the public key as a response
- If a validator tries to register again, the service returns the public key from the pre-existing keypair
2. Sign a vote
- The request must contain a voting transaction and all verification data
- The request must be signed with the validator's private key
- The service drops the request if signature of the request cannot be verified
- The service verifies the voting data
- The service returns a signature for the transaction
- The request must contain a voting transaction and all verification data
- The request must be signed with the validator's private key
- The service drops the request if signature of the request cannot be verified
- The service verifies the voting data
- The service returns a signature for the transaction
## Validator voting

6
docs/src/clusters.md
View File

@ -25,9 +25,11 @@ Explorers:
- Devnet typically runs a newer software version than Mainnet Beta
- Gossip entrypoint for Devnet: `entrypoint.devnet.solana.com:8001`
- Metrics environment variable for Devnet:
```bash
export SOLANA_METRICS_CONFIG="host=https://metrics.solana.com:8086,db=devnet,u=scratch_writer,p=topsecret"
```
- RPC URL for Devnet: `https://devnet.solana.com`
##### Example `solana` command-line configuration
@ -70,9 +72,11 @@ The `--trusted-validator`s is operated by Solana
Mainnet Beta
- Gossip entrypoint for Testnet: `entrypoint.testnet.solana.com:8001`
- Metrics environment variable for Testnet:
```bash
export SOLANA_METRICS_CONFIG="host=https://metrics.solana.com:8086,db=tds,u=testnet_write,p=c4fa841aa918bf8274e3e2a44d77568d9861b3ea"
```
- RPC URL for Testnet: `https://testnet.solana.com`
##### Example `solana` command-line configuration
@ -121,9 +125,11 @@ Currently, rewards and inflation are disabled.
the wallet will always be connecting to Mainnet Beta.
- Gossip entrypoint for Mainnet Beta: `entrypoint.mainnet-beta.solana.com:8001`
- Metrics environment variable for Mainnet Beta:
```bash
export SOLANA_METRICS_CONFIG="host=https://metrics.solana.com:8086,db=mainnet-beta,u=mainnet-beta_write,p=password"
```
- RPC URL for Mainnet Beta: `https://api.mainnet-beta.solana.com`
##### Example `solana` command-line configuration

21
docs/src/developing/backwards-compatibility.md
View File

@ -19,7 +19,7 @@ and so this document attempts to clarify and codify the process for new releases
1. In any `PATCH` or `MINOR` release, a feature, API, endpoint, etc. could be marked as deprecated.
2. According to code upgrade difficulty, some features will be remain deprecated for a few release
cycles.
cycles.
3. In a future `MAJOR` release, deprecated features will be removed in an incompatible way.
### Release Cadence
@ -57,46 +57,55 @@ release channels.
### RPC API
Patch releases:
- Bug fixes
- Security fixes
- Endpoint / feature deprecation
Minor releases:
- New RPC endpoints and features
Major releases:
- Removal of deprecated features
### Rust Crates
* [`solana-sdk`](https://docs.rs/solana-sdk/) - Rust SDK for creating transactions and parsing account state
* [`solana-program`](https://docs.rs/solana-program/) - Rust SDK for writing programs
* [`solana-client`](https://docs.rs/solana-client/) - Rust client for connecting to RPC API
* [`solana-cli-config`](https://docs.rs/solana-cli-config/) - Rust client for managing Solana CLI config files
- [`solana-sdk`](https://docs.rs/solana-sdk/) - Rust SDK for creating transactions and parsing account state
- [`solana-program`](https://docs.rs/solana-program/) - Rust SDK for writing programs
- [`solana-client`](https://docs.rs/solana-client/) - Rust client for connecting to RPC API
- [`solana-cli-config`](https://docs.rs/solana-cli-config/) - Rust client for managing Solana CLI config files
Patch releases:
- Bug fixes
- Security fixes
- Performance improvements
Minor releases:
- New APIs
Major releases
- Removal of deprecated APIs
- Backwards incompatible behavior changes
### CLI Tools
Patch releases:
- Bug and security fixes
- Performance improvements
- Subcommand / argument deprecation
Minor releases:
- New subcommands
Major releases:
- Switch to new RPC API endpoints / configuration introduced in the previous major version.
- Removal of deprecated features
@ -111,7 +120,7 @@ The release process is as follows:
1. New runtime feature is included in a new release, deactivated by default
2. Once sufficient staked validators upgrade to the new release, the runtime feature switch
is activated manually with an instruction
is activated manually with an instruction
3. The feature takes effect at the beginning of the next epoch
### Infrastructure Changes

28
docs/src/developing/on-chain-programs/debugging.md
View File

@ -19,17 +19,17 @@ messages.
For information about how to log from a program see the language specific
documentation:
- [Logging from a Rust program](developing-rust.md#logging)
- [Logging from a C program](developing-c.md#logging)
When running a local cluster the logs are written to stdout as long as they are
enabled via the `RUST_LOG` log mask. From the perspective of program
enabled via the `RUST_LOG` log mask. From the perspective of program
development it is helpful to focus on just the runtime and program logs and not
the rest of the cluster logs. To focus in on program specific information the
the rest of the cluster logs. To focus in on program specific information the
following log mask is recommended:
`export
RUST_LOG=solana_runtime::system_instruction_processor=trace,solana_runtime::message_processor=info,solana_bpf_loader=debug,solana_rbpf=debug`
`export RUST_LOG=solana_runtime::system_instruction_processor=trace,solana_runtime::message_processor=info,solana_bpf_loader=debug,solana_rbpf=debug`
Log messages coming directly from the program (not the runtime) will be
displayed in the form:
@ -39,24 +39,25 @@ displayed in the form:
## Error Handling
The amount of information that can be communicated via a transaction error is
limited but there are many points of possible failures. The following are
limited but there are many points of possible failures. The following are
possible failure points and information about what errors to expect and where to
get more information:
- The BPF loader may fail to parse the program, this should not happen since the
loader has already _finalized_ the program's account data.
- `InstructionError::InvalidAccountData` will be returned as part of the
transaction error.
- The BPF loader may fail to setup the program's execution environment
- `InstructionError::Custom(0x0b9f_0001)` will be returned as part of the
transaction error. "0x0b9f_0001" is the hexadecimal representation of
transaction error. "0x0b9f_0001" is the hexadecimal representation of
[`VirtualMachineCreationFailed`](https://github.com/solana-labs/solana/blob/bc7133d7526a041d1aaee807b80922baa89b6f90/programs/bpf_loader/src/lib.rs#L44).
- The BPF loader may have detected a fatal error during program executions
(things like panics, memory violations, system call errors, etc...)
- `InstructionError::Custom(0x0b9f_0002)` will be returned as part of the
transaction error. "0x0b9f_0002" is the hexadecimal representation of
[`VirtualMachineFailedToRunProgram`](https://github.com/solana-labs/solana/blob/bc7133d7526a041d1aaee807b80922baa89b6f90/programs/bpf_loader/src/lib.rs#L46).
transaction error. "0x0b9f_0002" is the hexadecimal representation of
[`VirtualMachineFailedToRunProgram`](https://github.com/solana-labs/solana/blob/bc7133d7526a041d1aaee807b80922baa89b6f90/programs/bpf_loader/src/lib.rs#L46).
- The program itself may return an error
- `InstructionError::Custom(<user defined value>)` will be returned. The
- `InstructionError::Custom(<user defined value>)` will be returned. The
"user defined value" must not conflict with any of the [builtin runtime
program
errors](https://github.com/solana-labs/solana/blob/bc7133d7526a041d1aaee807b80922baa89b6f90/sdk/program/src/program_error.rs#L87).
@ -70,13 +71,12 @@ logs](debugging.md#logging).
For example, an access violation involving the stack will look something like
this:
`BPF program 4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM failed: out of bounds
memory store (insn #615), addr 0x200001e38/8 `
`BPF program 4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM failed: out of bounds memory store (insn #615), addr 0x200001e38/8`
## Monitoring Compute Budget Consumption
The program can log the remaining number of compute units it will be allowed
before program execution is halted. Programs can use these logs to wrap
before program execution is halted. Programs can use these logs to wrap
operations they wish to profile.
- [Log the remaining compute units from a Rust
@ -99,13 +99,13 @@ insight into a program's composition and what it may be doing at runtime.
## Instruction Tracing
During execution the runtime BPF interpreter can be configured to log a trace
message for each BPF instruction executed. This can be very helpful for things
message for each BPF instruction executed. This can be very helpful for things
like pin-pointing the runtime context leading up to a memory access violation.
The trace logs together with the [ELF dump](#elf-dump) can provide a lot of
insight (though the traces produce a lot of information).
To turn on BPF interpreter trace messages in a local cluster configure the
`solana_rbpf` level in `RUST_LOG` to `trace`. For example:
`solana_rbpf` level in `RUST_LOG` to `trace`. For example:
`export RUST_LOG=solana_rbpf=trace`

2
docs/src/developing/on-chain-programs/deploying.md
View File

@ -11,7 +11,7 @@ clients via a _program ID_. The program ID is an _address_ specified when
deploying and is used to reference the program in subsequent transactions.
Upon a successful deployment the account that holds the program is marked
executable and its account data become permanently immutable. If any changes
executable and its account data become permanently immutable. If any changes
are required to the program (features, patches, etc...) the new program must be
deployed to a new program ID.

38
docs/src/developing/on-chain-programs/developing-c.md
View File

@ -31,11 +31,13 @@ for an example of a C program.
## How to Build
First setup the environment:
- Install the latest Rust stable from https://rustup.rs
- Install the latest Solana command-line tools from
https://docs.solana.com/cli/install-solana-cli-tools
Then build using make:
```bash
make -C <program directory>
```
@ -46,8 +48,7 @@ Solana uses the [Criterion](https://github.com/Snaipe/Criterion) test framework
and tests are executed each time the program is built [How to
Build](#how-to-build)].
To add tests, create a new file next to your source file named `test_<program
name>.c` and populate it with criterion test cases. For an example see the
To add tests, create a new file next to your source file named `test_<program name>.c` and populate it with criterion test cases. For an example see the
[helloworld C
tests](https://github.com/solana-labs/example-helloworld/blob/master/src/program-c/src/helloworld/test_helloworld.c)
or the [Criterion docs](https://criterion.readthedocs.io/en/master) for
@ -56,9 +57,9 @@ information on how to write a test case.
## Program Entrypoint
Programs export a known entrypoint symbol which the Solana runtime looks up and
calls when invoking a program. Solana supports multiple [versions of the BPF
calls when invoking a program. Solana supports multiple [versions of the BPF
loader](overview.md#versions) and the entrypoints may vary between them.
Programs must be written for and deployed to the same loader. For more details
Programs must be written for and deployed to the same loader. For more details
see the [overview](overview#loaders).
Currently there are two supported loaders [BPF
@ -74,7 +75,7 @@ extern uint64_t entrypoint(const uint8_t *input)
```
This entrypoint takes a generic byte array which contains the serialized program
parameters (program id, accounts, instruction data, etc...). To deserialize the
parameters (program id, accounts, instruction data, etc...). To deserialize the
parameters each loader contains its own [helper function](#Serialization).
Refer to [helloworld's use of the
@ -88,6 +89,7 @@ function](https://github.com/solana-labs/example-helloworld/blob/bc0b25c0ccebeff
Each loader provides a helper function that deserializes the program's input
parameters into C types:
- [BPF Loader
deserialization](https://github.com/solana-labs/solana/blob/d2ee9db2143859fa5dc26b15ee6da9c25cc0429c/sdk/bpf/c/inc/solana_sdk.h#L304)
- [BPF Loader deprecated
@ -97,8 +99,8 @@ Some programs may want to perform deserialzaiton themselves and they can by
providing their own implementation of the [raw entrypoint](#program-entrypoint).
Take note that the provided deserialization functions retain references back to
the serialized byte array for variables that the program is allowed to modify
(lamports, account data). The reason for this is that upon return the loader
will read those modifications so they may be committed. If a program implements
(lamports, account data). The reason for this is that upon return the loader
will read those modifications so they may be committed. If a program implements
their own deserialization function they need to ensure that any modifications
the program wishes to commit must be written back into the input byte array.
@ -128,18 +130,18 @@ typedef struct {
'ka' is an ordered array of the accounts referenced by the instruction and
represented as a
[SolAccountInfo](https://github.com/solana-labs/solana/blob/8415c22b593f164020adc7afe782e8041d756ddf/sdk/bpf/c/inc/solana_sdk.h#L173)
structures. An account's place in the array signifies its meaning, for example,
structures. An account's place in the array signifies its meaning, for example,
when transferring lamports an instruction may define the first account as the
source and the second as the destination.
The members of the `SolAccountInfo` structure are read-only except for
`lamports` and `data`. Both may be modified by the program in accordance with
`lamports` and `data`. Both may be modified by the program in accordance with
the [runtime enforcement
policy](developing/programming-model/accounts.md#policy). When an instruction
policy](developing/programming-model/accounts.md#policy). When an instruction
reference the same account multiple times there may be duplicate
`SolAccountInfo` entries in the array but they both point back to the original
input byte array. A program should handle these case delicately to avoid
overlapping read/writes to the same buffer. If a program implements their own
input byte array. A program should handle these case delicately to avoid
overlapping read/writes to the same buffer. If a program implements their own
deserialization function care should be taken to handle duplicate accounts
appropriately.
@ -154,7 +156,7 @@ processed.
C programs can allocate memory via the system call
[`calloc`](https://github.com/solana-labs/solana/blob/c3d2d2134c93001566e1e56f691582f379b5ae55/sdk/bpf/c/inc/solana_sdk.h#L245)
or implement their own heap on top of the 32KB heap region starting at virtual
address x300000000. The heap region is also used by `calloc` so if a program
address x300000000. The heap region is also used by `calloc` so if a program
implements their own heap it should not also call `calloc`.
## Logging
@ -162,10 +164,8 @@ implements their own heap it should not also call `calloc`.
The runtime provides two system calls that take data and log it to the program
logs.
- [`sol_log(const
char*)`](https://github.com/solana-labs/solana/blob/d2ee9db2143859fa5dc26b15ee6da9c25cc0429c/sdk/bpf/c/inc/solana_sdk.h#L128)
- [`sol_log_64(uint64_t, uint64_t, uint64_t, uint64_t,
uint64_t)`](https://github.com/solana-labs/solana/blob/d2ee9db2143859fa5dc26b15ee6da9c25cc0429c/sdk/bpf/c/inc/solana_sdk.h#L134)
- [`sol_log(const char*)`](https://github.com/solana-labs/solana/blob/d2ee9db2143859fa5dc26b15ee6da9c25cc0429c/sdk/bpf/c/inc/solana_sdk.h#L128)
- [`sol_log_64(uint64_t, uint64_t, uint64_t, uint64_t, uint64_t)`](https://github.com/solana-labs/solana/blob/d2ee9db2143859fa5dc26b15ee6da9c25cc0429c/sdk/bpf/c/inc/solana_sdk.h#L134)
The [debugging](debugging.md#logging) section has more information about working
with program logs.
@ -184,9 +184,9 @@ for more information.
## ELF Dump
The BPF shared object internals can be dumped to a text file to gain more
insight into a program's composition and what it may be doing at runtime. The
insight into a program's composition and what it may be doing at runtime. The
dump will contain both the ELF information as well as a list of all the symbols
and the instructions that implement them. Some of the BPF loader's error log
and the instructions that implement them. Some of the BPF loader's error log
messages will reference specific instruction numbers where the error occurred.
These references can be looked up in the ELF dump to identify the offending
instruction and its context.

60
docs/src/developing/on-chain-programs/developing-rust.md
View File

@ -17,10 +17,13 @@ layout](https://doc.rust-lang.org/cargo/guide/project-layout.html):
```
But must also include:
```
/Xargo.toml
```
Which must contain:
```
[target.bpfel-unknown-unknown.dependencies.std]
features = []
@ -30,7 +33,7 @@ Solana Rust programs may depend directly on each other in order to gain access
to instruction helpers when making [cross-program
invocations](developing/../../programming-model/calling-between-programs.md#cross-program-invocations).
When doing so it's important to not pull in the dependent program's entrypoint
symbols because they may conflict with the program's own. To avoid this,
symbols because they may conflict with the program's own. To avoid this,
programs should define an `exclude_entrypoint` feature in `Cargo.toml` and use
to exclude the entrypoint.
@ -41,6 +44,7 @@ to exclude the entrypoint.
Then when other programs include this program as a dependency, they should do so
using the `exclude_entrypoint` feature.
- [Include without
entrypoint](https://github.com/solana-labs/solana-program-library/blob/a5babd6cbea0d3f29d8c57d2ecbbd2a2bd59c8a9/token-swap/program/Cargo.toml#L19)
@ -53,19 +57,21 @@ Solana BPF programs have some [restrictions](#restrictions) that may prevent the
inclusion of some crates as dependencies or require special handling.
For example:
- Crates that require the architecture be a subset of the ones supported by the
official toolchain. There is no workaround for this unless that crate is
official toolchain. There is no workaround for this unless that crate is
forked and BPF added to that those architecture checks.
- Crates may depend on `rand` which is not supported in Solana's deterministic
program environment. To include a `rand` dependent crate refer to [Depending
program environment. To include a `rand` dependent crate refer to [Depending
on Rand](#depending-on-rand).
- Crates may overflow the stack even if the stack overflowing code isn't
included in the program itself. For more information refer to
included in the program itself. For more information refer to
[Stack](overview.md#stack).
## How to Build
First setup the environment:
- Install the latest Rust stable from https://rustup.rs/
- Install the latest Solana command-line tools from
https://docs.solana.com/cli/install-solana-cli-tools
@ -92,7 +98,7 @@ exercising program functions directly.
To help facilitate testing in an environment that more closely matches a live
cluster, developers can use the
[`program-test`](https://crates.io/crates/solana-program-test) crate. The
[`program-test`](https://crates.io/crates/solana-program-test) crate. The
`program-test` crate starts up a local instance of the runtime and allows tests
to send multiple transactions while keeping state for the duration of the test.
@ -104,9 +110,9 @@ program.
## Program Entrypoint
Programs export a known entrypoint symbol which the Solana runtime looks up and
calls when invoking a program. Solana supports multiple [versions of the BPF
calls when invoking a program. Solana supports multiple [versions of the BPF
loader](overview.md#versions) and the entrypoints may vary between them.
Programs must be written for and deployed to the same loader. For more details
Programs must be written for and deployed to the same loader. For more details
see the [overview](overview#loaders).
Currently there are two supported loaders [BPF
@ -123,12 +129,13 @@ pub unsafe extern "C" fn entrypoint(input: *mut u8) -> u64;
```
This entrypoint takes a generic byte array which contains the serialized program
parameters (program id, accounts, instruction data, etc...). To deserialize the
parameters (program id, accounts, instruction data, etc...). To deserialize the
parameters each loader contains its own wrapper macro that exports the raw
entrypoint, deserializes the parameters, calls a user defined instruction
processing function, and returns the results.
You can find the entrypoint macros here:
- [BPF Loader's entrypoint
macro](https://github.com/solana-labs/solana/blob/7ddf10e602d2ed87a9e3737aa8c32f1db9f909d8/sdk/program/src/entrypoint.rs#L46)
- [BPF Loader deprecated's entrypoint
@ -149,8 +156,9 @@ as an example of how things fit together.
### Parameter Deserialization
Each loader provides a helper function that deserializes the program's input
parameters into Rust types. The entrypoint macros automatically calls the
parameters into Rust types. The entrypoint macros automatically calls the
deserialization helper:
- [BPF Loader
deserialization](https://github.com/solana-labs/solana/blob/7ddf10e602d2ed87a9e3737aa8c32f1db9f909d8/sdk/program/src/entrypoint.rs#L104)
- [BPF Loader deprecated
@ -160,8 +168,8 @@ Some programs may want to perform deserialization themselves and they can by
providing their own implementation of the [raw entrypoint](#program-entrypoint).
Take note that the provided deserialization functions retain references back to
the serialized byte array for variables that the program is allowed to modify
(lamports, account data). The reason for this is that upon return the loader
will read those modifications so they may be committed. If a program implements
(lamports, account data). The reason for this is that upon return the loader
will read those modifications so they may be committed. If a program implements
their own deserialization function they need to ensure that any modifications
the program wishes to commit be written back into the input byte array.
@ -184,19 +192,19 @@ The program id is the public key of the currently executing program.
The accounts is an ordered slice of the accounts referenced by the instruction
and represented as an
[AccountInfo](https://github.com/solana-labs/solana/blob/7ddf10e602d2ed87a9e3737aa8c32f1db9f909d8/sdk/program/src/account_info.rs#L10)
structures. An account's place in the array signifies its meaning, for example,
structures. An account's place in the array signifies its meaning, for example,
when transferring lamports an instruction may define the first account as the
source and the second as the destination.
The members of the `AccountInfo` structure are read-only except for `lamports`
and `data`. Both may be modified by the program in accordance with the [runtime
enforcement policy](developing/programming-model/accounts.md#policy). Both of
and `data`. Both may be modified by the program in accordance with the [runtime
enforcement policy](developing/programming-model/accounts.md#policy). Both of
these members are protected by the Rust `RefCell` construct, so they must be
borrowed to read or write to them. The reason for this is they both point back
borrowed to read or write to them. The reason for this is they both point back
to the original input byte array, but there may be multiple entries in the
accounts slice that point to the same account. Using `RefCell` ensures that the
accounts slice that point to the same account. Using `RefCell` ensures that the
program does not accidentally perform overlapping read/writes to the same
underlying data via multiple `AccountInfo` structures. If a program implements
underlying data via multiple `AccountInfo` structures. If a program implements
their own deserialization function care should be taken to handle duplicate
accounts appropriately.
@ -242,7 +250,7 @@ single-threaded environment, and must be deterministic:
- No support for `println!`, `print!`, the Solana [logging helpers](#logging)
should be used instead.
- The runtime enforces a limit on the number of instructions a program can
execute during the processing of one instruction. See [computation
execute during the processing of one instruction. See [computation
budget](developing/programming-model/runtime.md#compute-budget) for more
information.
@ -274,7 +282,7 @@ getrandom = { version = "0.1.14", features = ["dummy"] }
## Logging
Rust's `println!` macro is computationally expensive and not supported. Instead
Rust's `println!` macro is computationally expensive and not supported. Instead
the helper macro
[`msg!`](https://github.com/solana-labs/solana/blob/6705b5a98c076ac08f3991bb8a6f9fcb280bf51e/sdk/program/src/log.rs#L33)
is provided.
@ -284,12 +292,14 @@ is provided.
```rust
msg!("A string");
```
or
```rust
msg!(0_64, 1_64, 2_64, 3_64, 4_64);
```
Both forms output the results to the program logs. If a program so wishes they
Both forms output the results to the program logs. If a program so wishes they
can emulate `println!` by using `format!`:
```rust
@ -343,10 +353,10 @@ replace that with something that better suits their needs.
One of the side effects of supporting full panic messages by default is that
programs incur the cost of pulling in more of Rust's `libstd` implementation
into program's shared object. Typical programs will already be pulling in a
into program's shared object. Typical programs will already be pulling in a
fair amount of `libstd` and may not notice much of an increase in the shared
object size. But programs that explicitly attempt to be very small by avoiding
`libstd` may take a significant impact (~25kb). To eliminate that impact,
object size. But programs that explicitly attempt to be very small by avoiding
`libstd` may take a significant impact (~25kb). To eliminate that impact,
programs can provide their own custom panic handler with an empty
implementation.
@ -372,9 +382,9 @@ for more information.
## ELF Dump
The BPF shared object internals can be dumped to a text file to gain more
insight into a program's composition and what it may be doing at runtime. The
insight into a program's composition and what it may be doing at runtime. The
dump will contain both the ELF information as well as a list of all the symbols
and the instructions that implement them. Some of the BPF loader's error log
and the instructions that implement them. Some of the BPF loader's error log
messages will reference specific instruction numbers where the error occurred.
These references can be looked up in the ELF dump to identify the offending
instruction and its context.

9
docs/src/developing/on-chain-programs/examples.md
View File

@ -2,7 +2,6 @@
title: "Examples"
---
## Helloworld
Hello World is a project that demonstrates how to use the Solana Javascript API
@ -10,9 +9,10 @@ and both Rust and C programs to build, deploy, and interact with programs on the
Solana blockchain.
The project comprises of:
- An on-chain hello world program
- A client that can send a "hello" to an account and get back the number of
times "hello" has been sent
- An on-chain hello world program
- A client that can send a "hello" to an account and get back the number of
times "hello" has been sent
### Build and Run
@ -26,7 +26,6 @@ $ cd example-helloworld
Next, follow the steps in the git repository's
[README](https://github.com/solana-labs/example-helloworld/blob/master/README.md).
## Break
[Break](https://break.solana.com/) is a React app that gives users a visceral

2
docs/src/developing/on-chain-programs/faq.md
View File

@ -78,4 +78,4 @@ See [Rust restrictions](developing-rust.md#restrictions)
## Stack size
See [stack](overview.md#stack)
See [stack](overview.md#stack)

33
docs/src/developing/on-chain-programs/overview.md
View File

@ -35,7 +35,7 @@ as follows
- Program input parameters start at 0x400000000
The above virtual addresses are start addresses but programs are given access to
a subset of the memory map. The program will panic if it attempts to read or
a subset of the memory map. The program will panic if it attempts to read or
write to a virtual address that it was not granted access to, and an
`AccessViolation` error will be returned that contains the address and size of
the attempted violation.
@ -48,14 +48,11 @@ BPF uses stack frames instead of a variable stack pointer. Each stack frame is
If a program violates that stack frame size, the compiler will report the
overrun as a warning.
For example: `Error: Function
_ZN16curve25519_dalek7edwards21EdwardsBasepointTable6create17h178b3d2411f7f082E
Stack offset of -30728 exceeded max offset of -4096 by 26632 bytes, please
minimize large stack variables`
For example: `Error: Function _ZN16curve25519_dalek7edwards21EdwardsBasepointTable6create17h178b3d2411f7f082E Stack offset of -30728 exceeded max offset of -4096 by 26632 bytes, please minimize large stack variables`
The message identifies which symbol is exceeding its stack frame but the name
might be mangled if it is a Rust or C++ symbol. To demangle a Rust symbol use
[rustfilt](https://github.com/luser/rustfilt). The above warning came from a
might be mangled if it is a Rust or C++ symbol. To demangle a Rust symbol use
[rustfilt](https://github.com/luser/rustfilt). The above warning came from a
Rust program, so the demangled symbol name is:
```bash
@ -97,8 +94,8 @@ attempts to use a float operation that is not supported, the runtime will report
an unresolved symbol error.
Float operations are performed via software libraries, specifically LLVM's float
builtins. Due to be software emulated they consume more compute units than
integer operations. In general, fixed point operations are recommended where
builtins. Due to be software emulated they consume more compute units than
integer operations. In general, fixed point operations are recommended where
possible.
The Solana Program Library math tests will report the performance of some math
@ -110,7 +107,7 @@ To run the test, sync the repo, and run:
`$ cargo test-bpf -- --nocapture --test-threads=1`
Recent results show the float operations take more instructions compared to
integers equivalents. Fixed point implementations may vary but will also be
integers equivalents. Fixed point implementations may vary but will also be
less then the float equivalents:
```
@ -121,7 +118,7 @@ Divide 9 219
## Static Writable Data
Program shared objects do not support writable shared data. Programs are shared
Program shared objects do not support writable shared data. Programs are shared
between multiple parallel executions using the same shared read-only code and
data. This means that developers should not include any static writable or
global variables in programs. In the future a copy-on-write mechanism could be
@ -142,7 +139,7 @@ and [BPF loader
deprecated](https://github.com/solana-labs/solana/blob/7ddf10e602d2ed87a9e3737aa8c32f1db9f909d8/sdk/program/src/bpf_loader_deprecated.rs#L14)
Loaders may support different application binary interfaces so developers must
write their programs for and deploy them to the same loader. If a program
write their programs for and deploy them to the same loader. If a program
written for one loader is deployed to a different one the result is usually a
`AccessViolation` error due to mismatched deserialization of the program's input
parameters.
@ -153,20 +150,21 @@ and the javascript APIs.
For language specific information about implementing a program for a particular
loader see:
- [Rust program entrypoints](developing-rust.md#program-entrypoint)
- [C program entrypoints](developing-c.md#program-entrypoint)
### Deployment
BPF program deployment is the process of uploading a BPF shared object into a
program account's data and marking the account executable. A client breaks the
program account's data and marking the account executable. A client breaks the
BPF shared object into smaller pieces and sends them as the instruction data of
[`Write`](https://github.com/solana-labs/solana/blob/bc7133d7526a041d1aaee807b80922baa89b6f90/sdk/program/src/loader_instruction.rs#L13)
instructions to the loader where loader writes that data into the program's
account data. Once all the pieces are received the client sends a
account data. Once all the pieces are received the client sends a
[`Finalize`](https://github.com/solana-labs/solana/blob/bc7133d7526a041d1aaee807b80922baa89b6f90/sdk/program/src/loader_instruction.rs#L30)
instruction to the loader, the loader then validates that the BPF data is valid
and marks the program account as _executable_. Once the program account is
and marks the program account as _executable_. Once the program account is
marked executable, subsequent transactions may issue instructions for that
program to process.
@ -180,13 +178,14 @@ For further information see [deploying](deploying.md)
BPF loaders serialize the program input parameters into a byte array that is
then passed to the program's entrypoint, where the program is responsible for
deserializing it on-chain. One of the changes between the deprecated loader and
deserializing it on-chain. One of the changes between the deprecated loader and
the current loader is that the input parameters are serialized in a way that
results in various parameters falling on aligned offsets within the aligned byte
array. This allows deserialization implementations to directly reference the
array. This allows deserialization implementations to directly reference the
byte array and provide aligned pointers to the program.
For language specific information about serialization see:
- [Rust program parameter
deserialization](developing-rust.md#parameter-deserialization)
- [C program parameter

21
docs/src/developing/programming-model/accounts.md
View File

@ -14,7 +14,7 @@ Unlike a file, the account includes metadata for the lifetime of the file. That
lifetime is expressed in "tokens", which is a number of fractional native
tokens, called _lamports_. Accounts are held in validator memory and pay
["rent"](#rent) to stay there. Each validator periodically scans all accounts
and collects rent. Any account that drops to zero lamports is purged. Accounts
and collects rent. Any account that drops to zero lamports is purged. Accounts
can also be marked [rent-exempt](#rent-exemption) if they contain a sufficient
number of lamports.
@ -45,9 +45,9 @@ If an account is marked "executable" in its metadata then it is considered a
program which can be executed by including the account's public key an
instruction's [program id](transactions.md#program-id). Accounts are marked as
executable during a successful program deployment process by the loader that
owns the account. For example, during BPF program deployment, once the loader
owns the account. For example, during BPF program deployment, once the loader
has determined that the BPF bytecode in the account's data is valid, the loader
permanently marks the program account as executable. Once executable, the
permanently marks the program account as executable. Once executable, the
runtime enforces that the account's data (the program) is immutable.
## Creating
@ -90,23 +90,23 @@ For security purposes, it is recommended that programs check the validity of any
account it reads but does not modify.
The security model enforces that an account's data can only be modified by the
account's `Owner` program. Doing so allows the program to trust that the data
passed to them via accounts they own will be in a known and valid state. The
account's `Owner` program. Doing so allows the program to trust that the data
passed to them via accounts they own will be in a known and valid state. The
runtime enforces this by rejecting any transaction containing a program that
attempts to write to an account it does not own. But, there are also cases
attempts to write to an account it does not own. But, there are also cases
where a program may merely read an account they think they own and assume the
data has only been written by themselves and thus is valid. But anyone can
data has only been written by themselves and thus is valid. But anyone can
issues instructions to a program, and the runtime does not know that those
accounts are expected to be owned by the program. Therefore a malicious user
accounts are expected to be owned by the program. Therefore a malicious user
could create accounts with arbitrary data and then pass these accounts to the
program in the place of a valid account. The arbitrary data could be crafted in
program in the place of a valid account. The arbitrary data could be crafted in
a way that leads to unexpected or harmful program behavior.
To check an account's validity, the program should either check the account's
address against a known value or check that the account is indeed owned
correctly (usually owned by the program itself).
One example is when programs read a sysvar. Unless the program checks the
One example is when programs read a sysvar. Unless the program checks the
address or owner, it's impossible to be sure whether it's a real and valid
sysvar merely by successful deserialization. Accordingly, the Solana SDK [checks
the sysvar's validity during
@ -169,7 +169,6 @@ For example, an account is created with the initial transfer of 10,000 lamports
and no additional data. Rent is immediately debited from it on creation,
resulting in a balance of 7,561 lamports:
```text
Rent: 2,439 = 19.055441478439427 (rent rate) * 128 bytes (minimum account size) * 1 (epoch)
Account Balance: 7,561 = 10,000 (transfered lamports) - 2,439 (this account's rent fee for an epoch)

14
docs/src/developing/programming-model/calling-between-programs.md
View File

@ -5,8 +5,8 @@ title: Calling Between Programs
## Cross-Program Invocations
The Solana runtime allows programs to call each other via a mechanism called
cross-program invocation. Calling between programs is achieved by one program
invoking an instruction of the other. The invoking program is halted until the
cross-program invocation. Calling between programs is achieved by one program
invoking an instruction of the other. The invoking program is halted until the
invoked program finishes processing the instruction.
For example, a client could create a transaction that modifies two accounts,
@ -57,7 +57,7 @@ given instruction to the `token` program via the instruction's `program_id`
field.
Note that `invoke` requires the caller to pass all the accounts required by the
instruction being invoked. This means that both the executable account (the
instruction being invoked. This means that both the executable account (the
ones that matches the instruction's program id) and the accounts passed to the
instruction procesor.
@ -166,17 +166,17 @@ authority elsewhere at its discretion.
A Program address does not lie on the ed25519 curve and therefore has no valid
private key associated with it, and thus generating a signature for it is
impossible. While it has no private key of its own, it can be used by a program
impossible. While it has no private key of its own, it can be used by a program
to issue an instruction that includes the Program address as a signer.
### Hash-based generated program addresses
Program addresses are deterministically derived from a collection of seeds and a
program id using a 256-bit pre-image resistant hash function. Program address
program id using a 256-bit pre-image resistant hash function. Program address
must not lie on the ed25519 curve to ensure there is no associated private key.
During generation an error will be returned if the address is found to lie on
the curve. There is about a 50/50 change of this happening for a given
collection of seeds and program id. If this occurs a different set of seeds or
the curve. There is about a 50/50 change of this happening for a given
collection of seeds and program id. If this occurs a different set of seeds or
a seed bump (additional 8 bit seed) can be used to find a valid program address
off the curve.

23
docs/src/developing/programming-model/runtime.md
View File

@ -28,6 +28,7 @@ program only performed operations it was permitted to, and that the results
adhere to the runtime policy.
The policy is as follows:
- Only the owner of the account may change owner.
- And only if the account is writable.
- And only if the account is not executable
@ -45,12 +46,13 @@ The policy is as follows:
## Compute Budget
To prevent a program from abusing computation resources each instruction in a
transaction is given a compute budget. The budget consists of computation units
transaction is given a compute budget. The budget consists of computation units
that are consumed as the program performs various operations and bounds that the
program may not exceed. When the program consumes its entire budget or exceeds
program may not exceed. When the program consumes its entire budget or exceeds
a bound then the runtime halts the program and returns an error.
The following operations incur a compute cost:
- Executing BPF instructions
- Calling system calls
- logging
@ -59,7 +61,7 @@ The following operations incur a compute cost:
- ...
For cross-program invocations the programs invoked inherit the budget of their
parent. If an invoked program consume the budget or exceeds a bound the entire
parent. If an invoked program consume the budget or exceeds a bound the entire
invocation chain and the parent are halted.
The current [compute
@ -81,6 +83,7 @@ log_pubkey_units: 100,
```
Then the program
- Could execute 200,000 BPF instructions if it does nothing else
- Could log 2,000 log messages
- Can not exceed 4k of stack usage
@ -91,28 +94,28 @@ Since the compute budget is consumed incrementally as the program executes the
total budget consumption will be a combination of the various costs of the
operations it performs.
At runtime a program may log how much of the compute budget remains. See
At runtime a program may log how much of the compute budget remains. See
[debugging](developing/on-chain-programs/debugging.md#monitoring-compute-budget-consumption)
for more information.
The budget values are conditional on feature enablement, take a look the compute
budget's
[new](https://github.com/solana-labs/solana/blob/d3a3a7548c857f26ec2cb10e270da72d373020ec/sdk/src/process_instruction.rs#L97)
function to find out how the budget is constructed. An understanding of how
function to find out how the budget is constructed. An understanding of how
[features](runtime.md#features) work and what features are enabled on the
cluster being used are required to determine the current budget's values.
## New Features
As Solana evolves, new features or patches may be introduced that changes the
behavior of the cluster and how programs run. Changes in behavior must be
behavior of the cluster and how programs run. Changes in behavior must be
coordinated between the various nodes of the cluster, if nodes do not coordinate
then these changes can result in a break-down of consensus. Solana supports a
then these changes can result in a break-down of consensus. Solana supports a
mechanism called runtime features to facilitate the smooth adoption of changes.
Runtime features are epoch coordinated events where one or more behavior changes
to the cluster will occur. New changes to Solana that will change behavior are
wrapped with feature gates and disabled by default. The Solana tools are then
to the cluster will occur. New changes to Solana that will change behavior are
wrapped with feature gates and disabled by default. The Solana tools are then
used to activate a feature, which marks it pending, once marked pending the
feature will be activated at the next epoch.
@ -124,5 +127,5 @@ solana feature status
```
If you encounter problems first ensure that the Solana tools version you are
using match the version returned by `solana cluster-version`. If they do not
using match the version returned by `solana cluster-version`. If they do not
match [install the correct tool suite](cli/install-solana-cli-tools.md).

16
docs/src/developing/programming-model/transactions.md
View File

@ -134,12 +134,11 @@ which loader should be used to load and execute the program and the data
contains information about how the runtime should execute the program.
In the case of [on-chain BPF programs](developing/on-chain-programs/overview.md),
the owner is the BPF Loader and the account data holds the BPF bytecode. Program
the owner is the BPF Loader and the account data holds the BPF bytecode. Program
accounts are permanently marked as executable by the loader once they are
successfully deployed. The runtime will reject transactions that specify programs
that are not executable.
Unlike on-chain programs, [Native Programs](/developing/runtime-facilities/programs)
are handled differently in that they are built directly into the Solana runtime.
@ -173,21 +172,21 @@ token account states.
### Multiple instructions in a single transaction
A transaction can contain instructions in any order. This means a malicious
A transaction can contain instructions in any order. This means a malicious
user could craft transactions that may pose instructions in an order that the
program has not been protected against. Programs should be hardened to properly
program has not been protected against. Programs should be hardened to properly
and safely handle any possible instruction sequence.
One not so obvious example is account deinitialization. Some programs may
One not so obvious example is account deinitialization. Some programs may
attempt to deinitialize an account by setting its lamports to zero, with the
assumption that the runtime will delete the account. This assumption may be
assumption that the runtime will delete the account. This assumption may be
valid between transactions, but it is not between instructions or cross-program
invocations. To harden against this, the program should also explicitly zero out the
invocations. To harden against this, the program should also explicitly zero out the
account's data.
An example of where this could be a problem is if a token program, upon
transferring the token out of an account, sets the account's lamports to zero,
assuming it will be deleted by the runtime. If the program does not zero out the
assuming it will be deleted by the runtime. If the program does not zero out the
account's data, a malicious user could trail this instruction with another that
transfers the tokens a second time.
@ -201,7 +200,6 @@ authorization to permit debiting the account or modifying its data. More
information about how the authorization is communicated to a program can be
found in [Accounts](accounts.md#signers)
## Recent Blockhash
A transaction includes a recent [blockhash](terminology.md#blockhash) to prevent

1
docs/src/developing/runtime-facilities/programs.md
View File

@ -88,6 +88,7 @@ struct Secp256k1SignatureOffsets {
```
Pseudo code of the operation:
```
process_instruction() {
for i in 0..count {

6
docs/src/developing/runtime-facilities/sysvars.md
View File

@ -12,7 +12,7 @@ and outlined below.
To include sysvar data in program operations, pass the sysvar account address in
the list of accounts in a transaction. The account can be read in your
instruction processor like any other account. Access to sysvars accounts ßis
always *readonly*.
always _readonly_.
## Clock
@ -22,6 +22,7 @@ epoch, and estimated wall-clock Unix timestamp. It is updated every slot.
- Address: `SysvarC1ock11111111111111111111111111111111`
- Layout: [Clock](https://docs.rs/solana-program/VERSION_FOR_DOCS_RS/solana_program/clock/struct.Clock.html)
- Fields:
- `slot`: the current slot
- `epoch_start_timestamp`: the Unix timestamp of the first slot in this epoch. In the first slot of an epoch, this timestamp is identical to the `unix_timestamp` (below).
- `epoch`: the current epoch
@ -48,8 +49,7 @@ epoch, and estimated wall-clock Unix timestamp. It is updated every slot.
The EpochSchedule sysvar contains epoch scheduling constants that are set in
genesis, and enables calculating the number of slots in a given epoch, the epoch
for a given slot, etc. (Note: the epoch schedule is distinct from the [`leader
schedule`](terminology.md#leader-schedule))
for a given slot, etc. (Note: the epoch schedule is distinct from the [`leader schedule`](terminology.md#leader-schedule))
- Address: `SysvarEpochSchedu1e111111111111111111111111`
- Layout:

2
docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_overview.md
View File

@ -4,6 +4,6 @@ title: Validation-client Economics
**Subject to change. Follow most recent economic discussions in the Solana forums: https://forums.solana.com**
Validator-clients are eligible to charge commission on inflationary rewards distributed to staked tokens. This compensation is for providing compute \(CPU+GPU\) resources to validate and vote on a given PoH state. These protocol-based rewards are determined through an algorithmic disinflationary schedule as a function of total token supply. The network is expected to launch with an annual inflation rate around 8%, set to decrease by 15% per year until a long-term stable rate of 1.5% is reached, however these parameters are yet to be finalized by the community. These issuances are to be split and distributed to participating validators, with around 95% of the issued tokens allocated for validator rewards initiall (the remaining 5% reserved for Foundation operating expenses). Because the network will be distributing a fixed amount of inflation rewards across the stake-weighted validator set, the yield observed for staked tokens will be primarily a function of the amount of staked tokens in relation to the total token supply.
Validator-clients are eligible to charge commission on inflationary rewards distributed to staked tokens. This compensation is for providing compute \(CPU+GPU\) resources to validate and vote on a given PoH state. These protocol-based rewards are determined through an algorithmic disinflationary schedule as a function of total token supply. The network is expected to launch with an annual inflation rate around 8%, set to decrease by 15% per year until a long-term stable rate of 1.5% is reached, however these parameters are yet to be finalized by the community. These issuances are to be split and distributed to participating validators, with around 95% of the issued tokens allocated for validator rewards initiall (the remaining 5% reserved for Foundation operating expenses). Because the network will be distributing a fixed amount of inflation rewards across the stake-weighted validator set, the yield observed for staked tokens will be primarily a function of the amount of staked tokens in relation to the total token supply.
Additionally, validator clients may earn revenue through fees via state-validation transactions. For clarity, we separately describe the design and motivation of these revenue distributions for validation-clients below: state-validation protocol-based rewards and state-validation transaction fees and rent.

30
docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md
View File

@ -20,45 +20,43 @@ The effective protocol-based annual staking yield \(%\) per epoch received by va
The first factor is a function of protocol parameters only \(i.e. independent of validator behavior in a given epoch\) and results in an inflation schedule designed to incentivize early participation, provide clear monetary stability and provide optimal security in the network.
As a first step to understanding the impact of the *Inflation Schedule* on the Solana economy, we’ve simulated the upper and lower ranges of what token issuance over time might look like given the current ranges of Inflation Schedule parameters under study.
As a first step to understanding the impact of the _Inflation Schedule_ on the Solana economy, we’ve simulated the upper and lower ranges of what token issuance over time might look like given the current ranges of Inflation Schedule parameters under study.
Specifically:
- *Initial Inflation Rate*: 7-9%
- *Dis-inflation Rate*: -14-16%
- *Long-term Inflation Rate*: 1-2%
- _Initial Inflation Rate_: 7-9%
- _Dis-inflation Rate_: -14-16%
- _Long-term Inflation Rate_: 1-2%
Using these ranges to simulate a number of possible Inflation Schedules, we can explore inflation over time:
![](/img/p_inflation_schedule_ranges_w_comments.png)
In the above graph, the average values of the range are identified to illustrate the contribution of each parameter.
From these simulated *Inflation Schedules*, we can also project ranges for token issuance over time.
From these simulated _Inflation Schedules_, we can also project ranges for token issuance over time.
![](/img/p_total_supply_ranges.png)
Finally we can estimate the *Staked Yield* on staked SOL, if we introduce an additional parameter, previously discussed, *% of Staked SOL*:
Finally we can estimate the _Staked Yield_ on staked SOL, if we introduce an additional parameter, previously discussed, _% of Staked SOL_:
%~\text{SOL Staked} = \frac{\text{Total SOL Staked}}{\text{Total Current Supply}}
In this case, because _% of Staked SOL_ is a parameter that must be estimated (unlike the _Inflation Schedule_ parameters), it is easier to use specific _Inflation Schedule_ parameters and explore a range of _% of Staked SOL_. For the below example, we’ve chosen the middle of the parameter ranges explored above:
In this case, because *% of Staked SOL* is a parameter that must be estimated (unlike the *Inflation Schedule* parameters), it is easier to use specific *Inflation Schedule* parameters and explore a range of *% of Staked SOL*. For the below example, we’ve chosen the middle of the parameter ranges explored above:
- _Initial Inflation Rate_: 8%
- _Dis-inflation Rate_: -15%
- _Long-term Inflation Rate_: 1.5%
- *Initial Inflation Rate*: 8%
- *Dis-inflation Rate*: -15%
- *Long-term Inflation Rate*: 1.5%
The values of *% of Staked SOL* range from 60% - 90%, which we feel covers the likely range we expect to observe, based on feedback from the investor and validator communities as well as what is observed on comparable Proof-of-Stake protocols.
The values of _% of Staked SOL_ range from 60% - 90%, which we feel covers the likely range we expect to observe, based on feedback from the investor and validator communities as well as what is observed on comparable Proof-of-Stake protocols.
![](/img/p_ex_staked_yields.png)
Again, the above shows an example *Staked Yield* that a staker might expect over time on the Solana network with the *Inflation Schedule* as specified. This is an idealized *Staked Yield* as it neglects validator uptime impact on rewards, validator commissions, potential yield throttling and potential slashing incidents. It additionally ignores that *% of Staked SOL* is dynamic by design - the economic incentives set up by this *Inflation Schedule*.
Again, the above shows an example _Staked Yield_ that a staker might expect over time on the Solana network with the _Inflation Schedule_ as specified. This is an idealized _Staked Yield_ as it neglects validator uptime impact on rewards, validator commissions, potential yield throttling and potential slashing incidents. It additionally ignores that _% of Staked SOL_ is dynamic by design - the economic incentives set up by this _Inflation Schedule_.
### Adjusted Staking Yield
A complete appraisal of earning potential from staking tokens should take into account staked *Token Dilution* and its impact on staking yield. For this, we define *adjusted staking yield* as the change in fractional token supply ownership of staked tokens due to the distribution of inflation issuance. I.e. the positive dilutive effects of inflation.
A complete appraisal of earning potential from staking tokens should take into account staked _Token Dilution_ and its impact on staking yield. For this, we define _adjusted staking yield_ as the change in fractional token supply ownership of staked tokens due to the distribution of inflation issuance. I.e. the positive dilutive effects of inflation.
We can examine the *adjusted staking yield* as a function of the inflation rate and the percent of staked tokens on the network. We can see this plotted for various staking fractions here:
We can examine the _adjusted staking yield_ as a function of the inflation rate and the percent of staked tokens on the network. We can see this plotted for various staking fractions here:
![](/img/p_ex_staked_dilution.png)

2
docs/src/implemented-proposals/implemented-proposals.md
View File

@ -3,7 +3,7 @@ title: Implemented Design Proposals
---
The following architectural proposals have been accepted and implemented
by the Solana team. Any designs that may be subject to future change are noted
by the Solana team. Any designs that may be subject to future change are noted
in the specific proposal page.
Design proposals that have been accepted but not yet implemented are found in
[Accepted Proposals](../proposals/accepted-design-proposals.md).

2
docs/src/implemented-proposals/instruction_introspection.md
View File

@ -6,7 +6,7 @@ title: instruction introspection
Some smart contract programs may want to verify that another Instruction is present in a
given Message since that Instruction could be be performing a verification of certain data,
in a precompiled function. (See secp256k1\_instruction for an example).
in a precompiled function. (See secp256k1_instruction for an example).
## Solution

54
docs/src/implemented-proposals/rpc-transaction-history.md
View File

@ -1,69 +1,75 @@
# Long term RPC Transaction History
There's a need for RPC to serve at least 6 months of transaction history. The
There's a need for RPC to serve at least 6 months of transaction history. The
current history, on the order of days, is insufficient for downstream users.
6 months of transaction data cannot be stored practically in a validator's
rocksdb ledger so an external data store is necessary. The validator's
rocksdb ledger so an external data store is necessary. The validator's
rocksdb ledger will continue to serve as the primary data source, and then will
fall back to the external data store.
The affected RPC endpoints are:
* [getFirstAvailableBlock](developing/clients/jsonrpc-api.md#getfirstavailableblock)
* [getConfirmedBlock](developing/clients/jsonrpc-api.md#getconfirmedblock)
* [getConfirmedBlocks](developing/clients/jsonrpc-api.md#getconfirmedblocks)
* [getConfirmedSignaturesForAddress](developing/clients/jsonrpc-api.md#getconfirmedsignaturesforaddress)
* [getConfirmedTransaction](developing/clients/jsonrpc-api.md#getconfirmedtransaction)
* [getSignatureStatuses](developing/clients/jsonrpc-api.md#getsignaturestatuses)
- [getFirstAvailableBlock](developing/clients/jsonrpc-api.md#getfirstavailableblock)
- [getConfirmedBlock](developing/clients/jsonrpc-api.md#getconfirmedblock)
- [getConfirmedBlocks](developing/clients/jsonrpc-api.md#getconfirmedblocks)
- [getConfirmedSignaturesForAddress](developing/clients/jsonrpc-api.md#getconfirmedsignaturesforaddress)
- [getConfirmedTransaction](developing/clients/jsonrpc-api.md#getconfirmedtransaction)
- [getSignatureStatuses](developing/clients/jsonrpc-api.md#getsignaturestatuses)
Note that [getBlockTime](developing/clients/jsonrpc-api.md#getblocktime)
is not supported, as once https://github.com/solana-labs/solana/issues/10089 is
fixed then `getBlockTime` can be removed.
Some system design constraints:
* The volume of data to store and search can quickly jump into the terabytes,
- The volume of data to store and search can quickly jump into the terabytes,
and is immutable.
* The system should be as light as possible for SREs. For example an SQL
- The system should be as light as possible for SREs. For example an SQL
database cluster that requires an SRE to continually monitor and rebalance
nodes is undesirable.
* Data must be searchable in real time - batched queries that take minutes or
- Data must be searchable in real time - batched queries that take minutes or
hours to run are unacceptable.
* Easy to replicate the data worldwide to co-locate it with the RPC endpoints
- Easy to replicate the data worldwide to co-locate it with the RPC endpoints
that will utilize it.
* Interfacing with the external data store should be easy and not require
- Interfacing with the external data store should be easy and not require
depending on risky lightly-used community-supported code libraries
Based on these constraints, Google's BigTable product is selected as the data
store.
## Table Schema
A BigTable instance is used to hold all transaction data, broken up into
different tables for quick searching.
New data may be copied into the instance at anytime without affecting the existing
data, and all data is immutable. Generally the expectation is that new data
data, and all data is immutable. Generally the expectation is that new data
will be uploaded once an current epoch completes but there is no limitation on
the frequency of data dumps.
Cleanup of old data is automatic by configuring the data retention policy of the
instance tables appropriately, it just disappears. Therefore the order of when data is
added becomes important. For example if data from epoch N-1 is added after data
from epoch N, the older epoch data will outlive the newer data. However beyond
instance tables appropriately, it just disappears. Therefore the order of when data is
added becomes important. For example if data from epoch N-1 is added after data
from epoch N, the older epoch data will outlive the newer data. However beyond
producing _holes_ in query results, this kind of unordered deletion will
have no ill effect. Note that this method of cleanup effectively allows for an
have no ill effect. Note that this method of cleanup effectively allows for an
unlimited amount of transaction data to be stored, restricted only by the
monetary costs of doing so.
The table layout s supports the existing RPC endpoints only. New RPC endpoints
The table layout s supports the existing RPC endpoints only. New RPC endpoints
in the future may require additions to the schema and potentially iterating over
all transactions to build up the necessary metadata.
## Accessing BigTable
BigTable has a gRPC endpoint that can be accessed using the
[tonic](https://crates.io/crates/crate)] and the raw protobuf API, as currently no
higher-level Rust crate for BigTable exists. Practically this makes parsing the
higher-level Rust crate for BigTable exists. Practically this makes parsing the
results of BigTable queries more complicated but is not a significant issue.
## Data Population
The ongoing population of instance data will occur on an epoch cadence through the
use of a new `solana-ledger-tool` command that will convert rocksdb data for a
given slot range into the instance schema.
@ -77,25 +83,23 @@ This table contains the compressed block data for a given slot.
The row key is generated by taking the 16 digit lower case hexadecimal
representation of the slot, to ensure that the oldest slot with a confirmed
block will always be first when the rows are listed. eg, The row key for slot
block will always be first when the rows are listed. eg, The row key for slot
42 would be 000000000000002a.
The row data is a compressed `StoredConfirmedBlock` struct.
### Account Address Transaction Signature Lookup Table: `tx-by-addr`
This table contains the transactions that affect a given address.
The row key is `<base58
address>/<slot-id-one's-compliment-hex-slot-0-prefixed-to-16-digits>`. The row
The row key is `<base58 address>/<slot-id-one's-compliment-hex-slot-0-prefixed-to-16-digits>`. The row
data is a compressed `TransactionByAddrInfo` struct.
Taking the one's compliment of the slot allows for listing of slots ensures that
the newest slot with transactions that affect an address will always
be listed first.
Sysvar addresses are not indexed. However frequently used programs such as
Sysvar addresses are not indexed. However frequently used programs such as
Vote or System are, and will likely have a row for every confirmed slot.
### Transaction Signature Lookup Table: `tx`

28
docs/src/inflation/adjusted_staking_yield.md
View File

@ -2,20 +2,19 @@
title: Adjusted Staking Yield
---
### Token Dilution
Similarly we can look at the expected *Staked Dilution* (i.e. *Adjusted Staking Yield*) and *Un-staked Dilution* as previously defined. Again, *dilution* in this context is defined as the change in fractional representation (i.e. ownership) of a set of tokens within a larger set. In this sense, dilution can be a positive value: an increase in fractional ownership (staked dilution / *Adjusted Staking Yield*), or a negative value: a decrease in fractional ownership (un-staked dilution).
Similarly we can look at the expected _Staked Dilution_ (i.e. _Adjusted Staking Yield_) and _Un-staked Dilution_ as previously defined. Again, _dilution_ in this context is defined as the change in fractional representation (i.e. ownership) of a set of tokens within a larger set. In this sense, dilution can be a positive value: an increase in fractional ownership (staked dilution / _Adjusted Staking Yield_), or a negative value: a decrease in fractional ownership (un-staked dilution).
We are interested in the relative change in ownership of staked vs un-staked tokens as the overall token pool increases with inflation issuance. As discussed, this issuance is distributed only to staked token holders, increasing the staked token fractional representation of the *Total Current Supply*.
We are interested in the relative change in ownership of staked vs un-staked tokens as the overall token pool increases with inflation issuance. As discussed, this issuance is distributed only to staked token holders, increasing the staked token fractional representation of the _Total Current Supply_.
Continuing with the same *Inflation Schedule* parameters as above, we see the fraction of staked supply grow as shown below.
Continuing with the same _Inflation Schedule_ parameters as above, we see the fraction of staked supply grow as shown below.
![](/img/p_ex_staked_supply_w_range_initial_stake.png)
Due to this relative change in representation, the proportion of stake of any token holder will also change as a function of the *Inflation Schedule* and the proportion of all tokens that are staked.
Due to this relative change in representation, the proportion of stake of any token holder will also change as a function of the _Inflation Schedule_ and the proportion of all tokens that are staked.
Of initial interest, however, is the *dilution of **un-staked** tokens*, or $D_{us}$. In the case of un-staked tokens, token dilution is only a function of the *Inflation Schedule* because the amount of un-staked tokens doesn't change over time.
Of initial interest, however, is the _dilution of **un-staked** tokens_, or $D_{us}$. In the case of un-staked tokens, token dilution is only a function of the _Inflation Schedule_ because the amount of un-staked tokens doesn't change over time.
This can be seen by explicitly calculating un-staked dilution as $D_{us}$. The un-staked proportion of the token pool at time $t$ is $P_{us}(t_{N})$ and $I_{t}$ is the incremental inflation rate applied between any two consecutive time points. $SOL_{us}(t)$ and $SOL_{total}(t)$ is the amount of un-staked and total SOL on the network, respectively, at time $t$. Therefore $P_{us}(t) = SOL_{us}(t)/SOL_{total}(t)$.
@ -34,7 +33,6 @@ $$
SOL_{us}(t_2) &= SOL_{us}(t_1)\\
SOL_{total}(t_2) &= SOL_{total}(t_1)\times (1 + I_{t_1})\\
\end{aligned}
$$
So $D_{us}$ becomes:
@ -52,17 +50,15 @@ $$
D_{us} = -\frac{I}{I + 1} \\
$$
So as guessed, this dilution is independent of the total proportion of staked tokens and only depends on inflation rate. This can be seen with our example *Inflation Schedule* here:
So as guessed, this dilution is independent of the total proportion of staked tokens and only depends on inflation rate. This can be seen with our example _Inflation Schedule_ here:
![p_ex_unstaked_dilution](/img/p_ex_unstaked_dilution.png)
### Estimated Adjusted Staked Yield
We can do a similar calculation to determine the *dilution* of staked token holders, or as we've defined here as the ***Adjusted Staked Yield***, keeping in mind that dilution in this context is an *increase* in proportional ownership over time. We'll use the terminology *Adjusted Staked Yield* to avoid confusion going forward.
We can do a similar calculation to determine the _dilution_ of staked token holders, or as we've defined here as the **_Adjusted Staked Yield_**, keeping in mind that dilution in this context is an _increase_ in proportional ownership over time. We'll use the terminology _Adjusted Staked Yield_ to avoid confusion going forward.
To see the functional form, we calculate, $Y_{adj}$, or the *Adjusted Staked Yield* (to be compared to *D_{us}* the dilution of un-staked tokens above), where $P_{s}(t)$ is the staked proportion of token pool at time $t$ and $I_{t}$ is the incremental inflation rate applied between any two consecutive time points. The definition of $Y_{adj}$ is therefore:
To see the functional form, we calculate, $Y_{adj}$, or the _Adjusted Staked Yield_ (to be compared to _D\_{us}_ the dilution of un-staked tokens above), where $P_{s}(t)$ is the staked proportion of token pool at time $t$ and $I_{t}$ is the incremental inflation rate applied between any two consecutive time points. The definition of $Y_{adj}$ is therefore:
$$
Y_{adj} = \frac{P_s(t_2) - P_s(t_1)}{P_s(t_1)}\\
@ -89,13 +85,11 @@ $$
Y_{adj} = \frac{ 1 + I(t)/P_s(t) }{ 1 + I(t) } - 1\\
$$
So we see that the *Adjusted Staked Yield* a function of the inflation rate and the percent of staked tokens on the network. We can see this plotted for various staking fractions here:
So we see that the _Adjusted Staked Yield_ a function of the inflation rate and the percent of staked tokens on the network. We can see this plotted for various staking fractions here:
![p_ex_adjusted_staked_yields](/img/p_ex_adjusted_staked_yields.png)
It is also clear that in all cases, dilution of un-staked tokens $>$ adjusted staked yield (i.e. dilution of staked tokens). Explicitly we can look at the *relative dilution of un-staked tokens to staked tokens:* $D_{us}/Y_{adj}$. Here the relationship to inflation drops out and the relative dilution, i.e. the impact of staking tokens vs not staking tokens, is purely a function of the % of the total token supply staked. From above
It is also clear that in all cases, dilution of un-staked tokens $>$ adjusted staked yield (i.e. dilution of staked tokens). Explicitly we can look at the _relative dilution of un-staked tokens to staked tokens:_ $D_{us}/Y_{adj}$. Here the relationship to inflation drops out and the relative dilution, i.e. the impact of staking tokens vs not staking tokens, is purely a function of the % of the total token supply staked. From above
$$
\begin{aligned}
@ -121,4 +115,4 @@ Where we can see a primary dependence of the relative dilution of un-staked toke
As might be intuitive, as the total fraction of staked tokens increases the relative dilution of un-staked tokens grows dramatically. E.g. with $80\%$ of the network tokens staked, an un-staked token holder will experience ~$400\%$ more dilution than a staked holder.
Again, this represents the change in fractional change in ownership of staked tokens and illustrates the built-in incentive for token holder to stake their tokens to earn *Staked Yield* and avoid *Un-staked Dilution*.
Again, this represents the change in fractional change in ownership of staked tokens and illustrates the built-in incentive for token holder to stake their tokens to earn _Staked Yield_ and avoid _Un-staked Dilution_.

18
docs/src/inflation/inflation_schedule.md
View File

@ -2,11 +2,11 @@
title: Solana's Proposed Inflation Schedule
---
As mentioned above, the network's *Inflation Schedule* is uniquely described by three parameters: *Initial Inflation Rate*, *Dis-inflation Rate* and *Long-term Inflation Rate*. When considering these numbers, there are many factors to take into account:
As mentioned above, the network's _Inflation Schedule_ is uniquely described by three parameters: _Initial Inflation Rate_, _Dis-inflation Rate_ and _Long-term Inflation Rate_. When considering these numbers, there are many factors to take into account:
- A large portion of the SOL issued via inflation will be distributed to stake-holders in proportion to the SOL they have staked. We want to ensure that the *Inflation Schedule* design results in reasonable *Staking Yields* for token holders who delegate SOL and for validation service providers (via commissions taken from *Staking Yields*).
- The primary driver of *Staked Yield* is the amount of SOL staked divided by the total amount of SOL (% of total SOL staked). Therefore the distribution and delegation of tokens across validators are important factors to understand when determining initial inflation parameters.
- [Yield throttling](https://forums.solana.com/t/validator-yield-throttling-proposal-discussion/855/5) is a current area or research that would impact *staking-yields*. This is not taken into consideration in the discussion here or the modeling below.
- A large portion of the SOL issued via inflation will be distributed to stake-holders in proportion to the SOL they have staked. We want to ensure that the _Inflation Schedule_ design results in reasonable _Staking Yields_ for token holders who delegate SOL and for validation service providers (via commissions taken from _Staking Yields_).
- The primary driver of _Staked Yield_ is the amount of SOL staked divided by the total amount of SOL (% of total SOL staked). Therefore the distribution and delegation of tokens across validators are important factors to understand when determining initial inflation parameters.
- [Yield throttling](https://forums.solana.com/t/validator-yield-throttling-proposal-discussion/855/5) is a current area or research that would impact _staking-yields_. This is not taken into consideration in the discussion here or the modeling below.
- Overall token issuance - i.e. what do we expect the Current Total Supply to be in 10 years, or 20 years?
- Long-term, steady-state inflation is an important consideration not only for sustainable support for the validator ecosystem and the Solana Foundation grant programs, but also should be tuned in consideration with expected token losses and burning over time.
- The rate at which we expect network usage to grow, as a consideration to the dis-inflationary rate. Over time, we plan for inflation to drop and expect that usage will grow.
@ -17,7 +17,7 @@ Based on these considerations and the community discussions following the initia
- Dis-inflation Rate: $-15\%$
- Long-term Inflation Rate: $1.5\%$
These parameters define the proposed *Inflation Schedule*. Below we show implications of these parameters. These plots only show the impact of inflation issuances given the Inflation Schedule as parameterized above. They *do not account* for other factors that may impact the Total Supply such as fee/rent burning, slashing or other unforeseen future token destruction events. Therefore, what is presented here is an **upper limit** on the amount of SOL issued via inflation.
These parameters define the proposed _Inflation Schedule_. Below we show implications of these parameters. These plots only show the impact of inflation issuances given the Inflation Schedule as parameterized above. They _do not account_ for other factors that may impact the Total Supply such as fee/rent burning, slashing or other unforeseen future token destruction events. Therefore, what is presented here is an **upper limit** on the amount of SOL issued via inflation.
![](/img/p_inflation_schedule.png)
@ -25,16 +25,16 @@ In the above graph we see the annual inflation rate [$\%$] over time, given the
![](/img/p_total_supply.png)
Similarly, here we see the *Total Current Supply* of SOL [MM] over time, assuming an initial *Total Current Supply* of `488,587,349 SOL` (i.e. for this example, taking the *Total Current Supply* as of `2020-01-25` and simulating inflation starting from that day).
Similarly, here we see the _Total Current Supply_ of SOL [MM] over time, assuming an initial _Total Current Supply_ of `488,587,349 SOL` (i.e. for this example, taking the _Total Current Supply_ as of `2020-01-25` and simulating inflation starting from that day).
Setting aside validator uptime and commissions, the expected Staking Yield and Adjusted Staking Yield metrics are then primarily a function of the % of total SOL staked on the network. Therefore we can we can model *Staking Yield*, if we introduce an additional parameter *% of Staked SOL*:
Setting aside validator uptime and commissions, the expected Staking Yield and Adjusted Staking Yield metrics are then primarily a function of the % of total SOL staked on the network. Therefore we can we can model _Staking Yield_, if we introduce an additional parameter _% of Staked SOL_:
$$
\%~\text{SOL Staked} = \frac{\text{Total SOL Staked}}{\text{Total Current Supply}}
$$
This parameter must be estimated because it is a dynamic property of the token holders and staking incentives. The values of *% of Staked SOL* presented here range from $60\% - 90\%$, which we feel covers the likely range we expect to observe, based on feedback from the investor and validator communities as well as what is observed on comparable Proof-of-Stake protocols.
This parameter must be estimated because it is a dynamic property of the token holders and staking incentives. The values of _% of Staked SOL_ presented here range from $60\% - 90\%$, which we feel covers the likely range we expect to observe, based on feedback from the investor and validator communities as well as what is observed on comparable Proof-of-Stake protocols.
![](/img/p_ex_staked_yields.png)
Again, the above shows an example *Staked Yield* that a staker might expect over time on the Solana network with the *Inflation Schedule* as specified. This is an idealized *Staked Yield* as it neglects validator uptime impact on rewards, validator commissions, potential yield throttling and potential slashing incidents. It additionally ignores that *% of Staked SOL* is dynamic by design - the economic incentives set up by this *Inflation Schedule* are more clearly seen when *Token Dilution* is taken into account (see the **Adjusted Staking Yield** section below).
Again, the above shows an example _Staked Yield_ that a staker might expect over time on the Solana network with the _Inflation Schedule_ as specified. This is an idealized _Staked Yield_ as it neglects validator uptime impact on rewards, validator commissions, potential yield throttling and potential slashing incidents. It additionally ignores that _% of Staked SOL_ is dynamic by design - the economic incentives set up by this _Inflation Schedule_ are more clearly seen when _Token Dilution_ is taken into account (see the **Adjusted Staking Yield** section below).

35
docs/src/inflation/terminology.md
View File

@ -2,39 +2,39 @@
title: Terminology
---
Many terms are thrown around when discussing inflation and the related components (e.g. rewards/yield/interest), we try to define and clarify some commonly used concept here:
### Total Current Supply [SOL]
The total amount of tokens (locked or unlocked) that have been generated (via genesis block or protocol inflation) minus any tokens that have been burnt (via transaction fees or other mechanism) or slashed. At network launch, 500,000,000 SOL were instantiated in the genesis block. Since then the Total Current Supply has been reduced by the burning of transaction fees and a planned token reduction event. Solana’s *Total Current Supply* can be found at https://explorer.solana.com/supply
The total amount of tokens (locked or unlocked) that have been generated (via genesis block or protocol inflation) minus any tokens that have been burnt (via transaction fees or other mechanism) or slashed. At network launch, 500,000,000 SOL were instantiated in the genesis block. Since then the Total Current Supply has been reduced by the burning of transaction fees and a planned token reduction event. Solana’s _Total Current Supply_ can be found at https://explorer.solana.com/supply
### Inflation Rate [%]
The Solana protocol will automatically create new tokens on a predetermined inflation schedule (discussed below). The *Inflation Rate [%]* is the annualized growth rate of the *Total Current Supply* at any point in time.
The Solana protocol will automatically create new tokens on a predetermined inflation schedule (discussed below). The _Inflation Rate [%]_ is the annualized growth rate of the _Total Current Supply_ at any point in time.
### Inflation Schedule
A deterministic description of token issuance over time. The Solana Foundation is proposing a dis-inflationary *Inflation Schedule*. I.e. Inflation starts at its highest value, the rate reduces over time until stabilizing at a predetermined long-term inflation rate (see discussion below). This schedule is completely and uniquely parameterized by three numbers:
- **Initial Inflation Rate [%]**: The starting *Inflation Rate* for when inflation is first enabled. Token issuance rate can only decrease from this point.
- **Dis-inflation Rate [%]**: The rate at which the *Inflation Rate* is reduced.
- **Long-term Inflation Rate [%]**: The stable, long-term *Inflation Rate* to be expected.
A deterministic description of token issuance over time. The Solana Foundation is proposing a dis-inflationary _Inflation Schedule_. I.e. Inflation starts at its highest value, the rate reduces over time until stabilizing at a predetermined long-term inflation rate (see discussion below). This schedule is completely and uniquely parameterized by three numbers:
- **Initial Inflation Rate [%]**: The starting _Inflation Rate_ for when inflation is first enabled. Token issuance rate can only decrease from this point.
- **Dis-inflation Rate [%]**: The rate at which the _Inflation Rate_ is reduced.
- **Long-term Inflation Rate [%]**: The stable, long-term _Inflation Rate_ to be expected.
### Effective Inflation Rate [%]
The inflation rate actually observed on the Solana network after accounting for other factors that might decrease the *Total Current Supply*. Note that it is not possible for tokens to be created outside of what is described by the *Inflation Schedule*.
The inflation rate actually observed on the Solana network after accounting for other factors that might decrease the _Total Current Supply_. Note that it is not possible for tokens to be created outside of what is described by the _Inflation Schedule_.
- While the *Inflation Schedule* determines how the protocol issues SOL, this neglects the concurrent elimination of tokens in the ecosystem due to various factors. The primary token burning mechanism is the burning of a portion of each transaction fee. While $100\%$ of each transaction fee is currently being destroyed, it is planned on reducing this burn rate to $50\%$ of each transaction fee, with the remaining fee to be retained by the validator that processes the transaction.
- Additional factors such as loss of private keys and slashing events should also be considered in a holistic analysis of the *Effective Inflation Rate*. For example, it’s estimated that $10-20\%$ of all BTC have been lost and are unrecoverable and that networks may experience similar yearly losses at the rate of $1-2\%$.
- While the _Inflation Schedule_ determines how the protocol issues SOL, this neglects the concurrent elimination of tokens in the ecosystem due to various factors. The primary token burning mechanism is the burning of a portion of each transaction fee. While $100\%$ of each transaction fee is currently being destroyed, it is planned on reducing this burn rate to $50\%$ of each transaction fee, with the remaining fee to be retained by the validator that processes the transaction.
- Additional factors such as loss of private keys and slashing events should also be considered in a holistic analysis of the _Effective Inflation Rate_. For example, it’s estimated that $10-20\%$ of all BTC have been lost and are unrecoverable and that networks may experience similar yearly losses at the rate of $1-2\%$.
### Staking Yield [%]
The rate of return (aka *interest*) earned on SOL staked on the network. It is often quoted as an annualized rate (e.g. "the network *staking yield* is currently $10\%$ per year").
- *Staking yield* is of great interest to validators and token-holders holders who wish to delegate their tokens to avoid token dilution due to inflation (the extent of which is discussed below).
The rate of return (aka _interest_) earned on SOL staked on the network. It is often quoted as an annualized rate (e.g. "the network _staking yield_ is currently $10\%$ per year").
- _Staking yield_ is of great interest to validators and token-holders holders who wish to delegate their tokens to avoid token dilution due to inflation (the extent of which is discussed below).
- $100\%$ of inflationary issuances are to be distributed to staked token-holders in proportion to their staked SOL and to validators who charge a commission on the rewards earned by their delegated SOL..
- There may be future consideration for an additional split of inflation issuance with the introduction of *Archivers* into the economy. *Archivers* are network participants who provide a decentralized storage service and should also be incentivized with token distribution from inflation issuances for this service.
- Similarly, early designs specified a fixed percentage of inflationary issuance to be delivered to the Foundation treasury for operational expenses and future grants. However, inflation will be launching without any portion allocated to the Foundation.
- *Staking yield* can be calculated from the *Inflation Schedule* along with the fraction of the *Total Current Supply* that is staked at any given time. The explicit relationship is given by:
- There may be future consideration for an additional split of inflation issuance with the introduction of _Archivers_ into the economy. _Archivers_ are network participants who provide a decentralized storage service and should also be incentivized with token distribution from inflation issuances for this service. - Similarly, early designs specified a fixed percentage of inflationary issuance to be delivered to the Foundation treasury for operational expenses and future grants. However, inflation will be launching without any portion allocated to the Foundation.
- _Staking yield_ can be calculated from the _Inflation Schedule_ along with the fraction of the _Total Current Supply_ that is staked at any given time. The explicit relationship is given by:
$$
\begin{aligned}
@ -45,11 +45,10 @@ $$
\end{aligned}
$$
### Token Dilution [%]
Dilution is defined here as the change in proportional representation of a set of tokens within a larger set due to the introduction of new tokens. In practical terms, we discuss the dilution of staked or un-staked tokens due to the introduction and distribution of inflation issuance across the network. As will be shown below, while dilution impacts every token holder, the *relative* dilution between staked and un-staked tokens should be the primary concern to un-staked token holders. Staking tokens, which will receive their proportional distribution of inflation issuance, should assuage any dilution concerns for staked token holders. I.e. dilution from 'inflation' is offset by the distribution of new tokens to staked token holders, nullifying the 'dilutive' effects of the inflation for that group.
Dilution is defined here as the change in proportional representation of a set of tokens within a larger set due to the introduction of new tokens. In practical terms, we discuss the dilution of staked or un-staked tokens due to the introduction and distribution of inflation issuance across the network. As will be shown below, while dilution impacts every token holder, the _relative_ dilution between staked and un-staked tokens should be the primary concern to un-staked token holders. Staking tokens, which will receive their proportional distribution of inflation issuance, should assuage any dilution concerns for staked token holders. I.e. dilution from 'inflation' is offset by the distribution of new tokens to staked token holders, nullifying the 'dilutive' effects of the inflation for that group.
### Adjusted Staking Yield [%]
A complete appraisal of earning potential from staking tokens should take into account staked *Token Dilution* and its impact on the *Staking Yield*. For this, we define the *Adjusted Staking Yield* as the change in fractional token supply ownership of staked tokens due to the distribution of inflation issuance. I.e. the positive dilutive effects of inflation.
A complete appraisal of earning potential from staking tokens should take into account staked _Token Dilution_ and its impact on the _Staking Yield_. For this, we define the _Adjusted Staking Yield_ as the change in fractional token supply ownership of staked tokens due to the distribution of inflation issuance. I.e. the positive dilutive effects of inflation.

78
docs/src/integrations/exchange.md
View File

@ -12,13 +12,14 @@ instances, upgrading to newer versions promptly, and keeping an eye on service
operations with a bundled monitoring tool.
This setup enables you:
- to have a trusted gateway to the Solana mainnet-beta cluster to get data and
submit withdrawal transactions
- to have full control over how much historical block data is retained
- to maintain your service availability even if one node fails
Solana nodes demand relatively high computing power to handle our fast blocks
and high TPS. For specific requirements, please see
and high TPS. For specific requirements, please see
[hardware recommendations](../running-validator/validator-reqs.md).
To run an api node:
@ -47,10 +48,10 @@ The `--entrypoint` and `--expected-genesis-hash` parameters are all specific to
The `--limit-ledger-size` parameter allows you to specify how many ledger
[shreds](../terminology.md#shred) your node retains on disk. If you do not
include this parameter, the validator will keep the entire ledger until it runs
out of disk space. The default value attempts to keep the ledger disk usage
under 500GB. More or less disk usage may be requested by adding an argument to
out of disk space. The default value attempts to keep the ledger disk usage
under 500GB. More or less disk usage may be requested by adding an argument to
`--limit-ledger-size` if desired. Check `solana-validator --help` for the
default limit value used by `--limit-ledger-size`. More information about
default limit value used by `--limit-ledger-size`. More information about
selecting a custom limit value is [available
here](https://github.com/solana-labs/solana/blob/583cec922b6107e0f85c7e14cb5e642bc7dfb340/core/src/ledger_cleanup_service.rs#L15-L26).
@ -103,46 +104,45 @@ order to prevent this issue, add the `--no-snapshot-fetch` parameter to your
snapshot.
Do not pass the `--no-snapshot-fetch` parameter on your initial boot as it's not
possible to boot the node all the way from the genesis block. Instead boot from
possible to boot the node all the way from the genesis block. Instead boot from
a snapshot first and then add the `--no-snapshot-fetch` parameter for reboots.
It is important to note that the amount of historical ledger available to your
nodes from the rest of the network is limited at any point in time. Once
nodes from the rest of the network is limited at any point in time. Once
operational if your validators experience significant downtime they may not be
able to catch up to the network and will need to download a new snapshot from a
trusted validator. In doing so your validators will now have a gap in its
trusted validator. In doing so your validators will now have a gap in its
historical ledger data that cannot be filled.
### Minimizing Validator Port Exposure
The validator requires that various UDP and TCP ports be open for inbound
traffic from all other Solana validators. While this is the most efficient mode of
traffic from all other Solana validators. While this is the most efficient mode of
operation, and is strongly recommended, it is possible to restrict the
validator to only require inbound traffic from one other Solana validator.
First add the `--restricted-repair-only-mode` argument. This will cause the
First add the `--restricted-repair-only-mode` argument. This will cause the
validator to operate in a restricted mode where it will not receive pushes from
the rest of the validators, and instead will need to continually poll other
validators for blocks. The validator will only transmit UDP packets to other
validators using the *Gossip* and *ServeR* ("serve repair") ports, and only
receive UDP packets on its *Gossip* and *Repair* ports.
validators for blocks. The validator will only transmit UDP packets to other
validators using the _Gossip_ and _ServeR_ ("serve repair") ports, and only
receive UDP packets on its _Gossip_ and _Repair_ ports.
The *Gossip* port is bi-directional and allows your validator to remain in
contact with the rest of the cluster. Your validator transmits on the *ServeR*
The _Gossip_ port is bi-directional and allows your validator to remain in
contact with the rest of the cluster. Your validator transmits on the _ServeR_
to make repair requests to obtaining new blocks from the rest of the network,
since Turbine is now disabled. Your validator will then receive repair
responses on the *Repair* port from other validators.
since Turbine is now disabled. Your validator will then receive repair
responses on the _Repair_ port from other validators.
To further restrict the validator to only requesting blocks from one or more
validators, first determine the identity pubkey for that validator and add the
`--gossip-pull-validator PUBKEY --repair-validator PUBKEY` arguments for each
PUBKEY. This will cause your validator to be a resource drain on each validator
PUBKEY. This will cause your validator to be a resource drain on each validator
that you add, so please do this sparingly and only after consulting with the
target validator.
Your validator should now only be communicating with the explicitly listed
validators and only on the *Gossip*, *Repair* and *ServeR* ports.
validators and only on the _Gossip_, _Repair_ and _ServeR_ ports.
## Setting up Deposit Accounts
@ -274,7 +274,7 @@ can request the block from RPC in binary format, and parse it using either our
### Address History
You can also query the transaction history of a specific address. This is
generally *not* a viable method for tracking all your deposit addresses over all
generally _not_ a viable method for tracking all your deposit addresses over all
slots, but may be useful for examining a few accounts for a specific period of
time.
@ -484,9 +484,11 @@ prevent accidental loss of user funds.
Solana addresses a 32-byte array, encoded with the bitcoin base58 alphabet. This
results in an ASCII text string matching the following regular expression:
```
[1-9A-HJ-NP-Za-km-z]{32,44}
```
This check is insufficient on its own as Solana addresses are not checksummed, so
typos cannot be detected. To further validate the user's input, the string can be
decoded and the resulting byte array's length confirmed to be 32. However, there
@ -574,9 +576,9 @@ few differences which will be discussed in this section.
### Token Mints
Each *type* of SPL Token is declared by creating a *mint* account. This account
Each _type_ of SPL Token is declared by creating a _mint_ account. This account
stores metadata describing token features like the supply, number of decimals, and
various authorities with control over the mint. Each SPL Token account references
various authorities with control over the mint. Each SPL Token account references
its associated mint and may only interact with SPL Tokens of that type.
### Installing the `spl-token` CLI Tool
@ -612,16 +614,18 @@ SPL Token accounts carry additional requirements that native System Program
accounts do not:
1. SPL Token accounts must be created before an amount of tokens can be
deposited. Token accounts can be created explicitly with the
`spl-token create-account` command, or implicitly by the
`spl-token transfer --fund-recipient ...` command.
deposited. Token accounts can be created explicitly with the
`spl-token create-account` command, or implicitly by the
`spl-token transfer --fund-recipient ...` command.
1. SPL Token accounts must remain [rent-exempt](developing/programming-model/accounts.md#rent-exemption)
for the duration of their existence and therefore require a small amount of
native SOL tokens be deposited at account creation. For SPL Token v2 accounts,
this amount is 0.00203928 SOL (2,039,280 lamports).
for the duration of their existence and therefore require a small amount of
native SOL tokens be deposited at account creation. For SPL Token v2 accounts,
this amount is 0.00203928 SOL (2,039,280 lamports).
#### Command Line
To create an SPL Token account with the following properties:
1. Associated with the given mint
1. Owned by the funding account's keypair
@ -630,6 +634,7 @@ spl-token create-account <TOKEN_MINT_ADDRESS>
```
#### Example
```
$ spl-token create-account AkUFCWTXb3w9nY2n6SFJvBV6VwvFUCe4KBMCcgLsa2ir
Creating account 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV
@ -637,6 +642,7 @@ Signature: 4JsqZEPra2eDTHtHpB4FMWSfk3UgcCVmkKkP7zESZeMrKmFFkDkNd91pKP3vPVVZZPiu5
```
Or to create an SPL Token account with a specific keypair:
```
$ solana-keygen new -o token-account.json
$ spl-token create-account AkUFCWTXb3w9nY2n6SFJvBV6VwvFUCe4KBMCcgLsa2ir token-account.json
@ -647,11 +653,13 @@ Signature: 4JsqZEPra2eDTHtHpB4FMWSfk3UgcCVmkKkP7zESZeMrKmFFkDkNd91pKP3vPVVZZPiu5
### Checking an Account's Balance
#### Command Line
```
spl-token balance <TOKEN_ACCOUNT_ADDRESS>
```
#### Example
```
$ solana balance 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV
0
@ -662,17 +670,19 @@ $ solana balance 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV
The source account for a transfer is the actual token account that contains the
amount.
The recipient address however can be a normal wallet account. If an associated
The recipient address however can be a normal wallet account. If an associated
token account for the given mint does not yet exist for that wallet, the
transfer will create it provided that the `--fund-recipient` argument as
provided.
#### Command Line
```
spl-token transfer <SENDER_ACCOUNT_ADDRESS> <AMOUNT> <RECIPIENT_WALLET_ADDRESS> --fund-recipient
```
#### Example
```
$ spl-token transfer 6B199xxzw3PkAm25hGJpjj3Wj3WNYNHzDAnt1tEqg5BN 1 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV
Transfer 1 tokens
@ -682,6 +692,7 @@ Signature: 3R6tsog17QM8KfzbcbdP4aoMfwgo6hBggJDVy7dZPVmH2xbCWjEj31JKD53NzMrf25ChF
```
### Depositing
Since each `(user, mint)` pair requires a separate account on chain, it is
recommended that an exchange create batches of token accounts in advance and assign them
to users on request. These accounts should all be owned by exchange-controlled
@ -700,6 +711,7 @@ made to exend the `preBalance` and `postBalance` transaction status metadata
fields to include SPL Token balance transfers.
### Withdrawing
The withdrawal address a user provides should be the same address used for
regular SOL withdrawal.
@ -708,13 +720,14 @@ the exchange should check the address as
[described above](#validating-user-supplied-account-addresses-for-withdrawals).
From the withdrawal address, the associated token account for the correct mint
determined and the transfer issued to that account. Note that it's possible
determined and the transfer issued to that account. Note that it's possible
that the associated token account does not yet exist, at which point the
exchange should fund the account on behalf of the user. For SPL Token v2
exchange should fund the account on behalf of the user. For SPL Token v2
accounts, funding the withdrawal account will require 0.00203928 SOL (2,039,280
lamports).
Template `spl-token transfer` command for a withdrawal:
```
$ spl-token transfer --fund-recipient <exchange token account> <withdrawal amount> <withdrawal address>
```
@ -722,9 +735,10 @@ $ spl-token transfer --fund-recipient <exchange token account> <withdrawal amoun
### Other Considerations
#### Freeze Authority
For regulatory compliance reasons, an SPL Token issuing entity may optionally
choose to hold "Freeze Authority" over all accounts created in association with
its mint. This allows them to [freeze](https://spl.solana.com/token#freezing-accounts)
its mint. This allows them to [freeze](https://spl.solana.com/token#freezing-accounts)
the assets in a given account at will, rendering the account unusable until thawed.
If this feature is in use, the freeze authority's pubkey will be registered in
the SPL Token's mint account.

4
docs/src/pages/index.js
View File

@ -105,7 +105,7 @@ function Home() {
{features && features.length > 0 && (
<section className={styles.features}>
<div className="row cards__container">
<div class="alert alert--primary" role="alert">
<div className="alert alert--primary" role="alert">
<b>Announcing the Solana Season Hackathon</b>
<br />
Jumpstart your next project on Solana & join the fastest growing
@ -116,7 +116,7 @@ function Home() {
rel="noopener noreferrer"
target="_blank"
>
<button class="button button--outline button--secondary">
<button className="button button--outline button--secondary">
Register Now
</button>
</a>

40
docs/src/proposals/program-instruction-macro.md
View File

@ -3,7 +3,7 @@
## Problem
Currently, inspecting an on-chain transaction requires depending on a
client-side, language-specific decoding library to parse the instruction. If
client-side, language-specific decoding library to parse the instruction. If
rpc methods could return decoded instruction details, these custom solutions
would be unnecessary.
@ -56,6 +56,7 @@ pub enum TestInstruction {
```
An example of the generated TestInstruction with docs:
```rust,ignore
pub enum TestInstruction {
/// Transfer lamports
@ -85,6 +86,7 @@ pub enum TestInstruction {
```
Generated constructors:
```rust,ignore
/// Transfer lamports
///
@ -203,22 +205,22 @@ impl TestInstructionVerbose {
## Considerations
1. **Named fields** - Since the resulting Verbose enum constructs variants with
named fields, any unnamed fields in the original Instruction variant will need
to have names generated. As such, it would be considerably more straightforward
if all Instruction enum fields are converted to named types, instead of unnamed
tuples. This seems worth doing anyway, adding more precision to the variants and
enabling real documentation (so developers don't have to do
[this](https://github.com/solana-labs/solana/blob/3aab13a1679ba2b7846d9ba39b04a52f2017d3e0/sdk/src/system_instruction.rs#L140)
This will cause a little churn in our current code base, but not a lot.
named fields, any unnamed fields in the original Instruction variant will need
to have names generated. As such, it would be considerably more straightforward
if all Instruction enum fields are converted to named types, instead of unnamed
tuples. This seems worth doing anyway, adding more precision to the variants and
enabling real documentation (so developers don't have to do
[this](https://github.com/solana-labs/solana/blob/3aab13a1679ba2b7846d9ba39b04a52f2017d3e0/sdk/src/system_instruction.rs#L140)
This will cause a little churn in our current code base, but not a lot.
2. **Variable account lists** - This approach offers a couple options for
variable account lists. First, optional accounts may be added and tagged with
the `optional` keyword. However, currently only one optional account is
supported per instruction. Additional data will need to be added to the
instruction to support multiples, enabling identification of which accounts are
present when some but not all are included. Second, accounts that share the same
features may be added as a set, tagged with the `multiple` keyword. Like
optional accounts, only one multiple account set is supported per instruction
(and optional and multiple may not coexist). More complex instructions that
cannot be accommodated by `optional` or `multiple`, requiring logic to figure
out account order/representation, should probably be made into separate
instructions.
variable account lists. First, optional accounts may be added and tagged with
the `optional` keyword. However, currently only one optional account is
supported per instruction. Additional data will need to be added to the
instruction to support multiples, enabling identification of which accounts are
present when some but not all are included. Second, accounts that share the same
features may be added as a set, tagged with the `multiple` keyword. Like
optional accounts, only one multiple account set is supported per instruction
(and optional and multiple may not coexist). More complex instructions that
cannot be accommodated by `optional` or `multiple`, requiring logic to figure
out account order/representation, should probably be made into separate
instructions.

12
docs/src/proposals/rip-curl.md
View File

@ -27,18 +27,18 @@ validator's ReplayStage.
Improved client experience:
* Support connections directly from WebAssembly apps.
* Clients can be notified of confirmation progress in real-time, including votes
- Support connections directly from WebAssembly apps.
- Clients can be notified of confirmation progress in real-time, including votes
and voter stake weight.
* Clients can be notified when the heaviest fork changes, if it affects the
- Clients can be notified when the heaviest fork changes, if it affects the
transactions confirmation count.
Easier for validators to support:
* Each validator supports some number of concurrent connections and otherwise
- Each validator supports some number of concurrent connections and otherwise
has no significant resource constraints.
* Transaction status is never stored in memory and cannot be polled for.
* Signatures are only stored in memory until the desired commitment level or
- Transaction status is never stored in memory and cannot be polled for.
- Signatures are only stored in memory until the desired commitment level or
until the blockhash expires, which ever is later.
How it works:

1
docs/src/proposals/simple-payment-and-state-verification.md
View File

@ -94,6 +94,7 @@ in the block. Ideally this Block-Merkle would be implmented, as the alternative
is very inefficient.
#### Block Headers
In order to verify transaction inclusion proofs, light clients need to be able
to infer the topology of the forks in the network

15
docs/src/running-validator/restart-cluster.md
View File

@ -2,11 +2,10 @@
### Step 1. Identify the slot that the cluster will be restarted at
The highest optimistically confirmed slot is the best slot to start from, which
can be found by looking for
[this](https://github.com/solana-labs/solana/blob/0264147d42d506fb888f5c4c021a998e231a3e74/core/src/optimistic_confirmation_verifier.rs#L71)
metrics datapoint. Otherwise use the last root.
metrics datapoint. Otherwise use the last root.
Call this slot `SLOT_X`
@ -22,7 +21,7 @@ $ solana-ledger-tool -l ledger create-snapshot SLOT_X ledger --hard-fork SLOT_X
The ledger directory should now contain the new snapshot.
`solana-ledger-tool create-snapshot` will also output the new shred version, and bank hash value,
call this NEW\_SHRED\_VERSION and NEW\_BANK\_HASH respectively.
call this NEW_SHRED_VERSION and NEW_BANK_HASH respectively.
Adjust your validator's arguments:
@ -44,9 +43,9 @@ Post something like the following to #announcements (adjusting the text as appro
> We've released v1.1.12 and are ready to get testnet back up again.
>
> Steps:
>
> 1. Install the v1.1.12 release: https://github.com/solana-labs/solana/releases/tag/v1.1.12
> 2.
> a. Preferred method, start from your local ledger with:
> 2. a. Preferred method, start from your local ledger with:
>
> ```bash
> solana-validator
@ -61,7 +60,9 @@ Post something like the following to #announcements (adjusting the text as appro
> --limit-ledger-size
> ... # <-- your other --identity/--vote-account/etc arguments
> ```
> b. If your validator doesn't have ledger up to slot SLOT_X or if you have deleted your ledger, have it instead download a snapshot with:
>
> b. If your validator doesn't have ledger up to slot SLOT_X or if you have deleted your ledger, have it instead download a snapshot with:
>
> ```bash
> solana-validator
> --wait-for-supermajority SLOT_X # <-- NEW! IMPORTANT! REMOVE AFTER THIS RESTART
@ -80,7 +81,7 @@ Post something like the following to #announcements (adjusting the text as appro
>
> To confirm your restarted validator is correctly waiting for the 80%:
> a. Look for `N% of active stake visible in gossip` log messages
> b. Ask it over RPC what slot it's on: `solana --url http://127.0.0.1:8899 slot`. It should return `SLOT_X` until we get to 80% stake
> b. Ask it over RPC what slot it's on: `solana --url http://127.0.0.1:8899 slot`. It should return `SLOT_X` until we get to 80% stake
>
> Thanks!

8
docs/src/running-validator/validator-reqs.md
View File

@ -17,7 +17,7 @@ transaction for each block the validator agrees with, which can cost up to
- 12 cores / 24 threads, or more
- 2.8GHz, or faster
- AVX2 instruction support (to use official release binaries, self-compile
otherwise)
otherwise)
- Support for AVX512f and/or SHA-NI instructions is helpful
- The AMD Threadripper Zen3 series is popular with the validator community
- RAM
@ -29,14 +29,14 @@ otherwise)
- Ledger: 1TB or larger. High TBW suggested
- OS: (Optional) 500GB, or larger. SATA OK
- The OS may be installed on the ledger disk, though testing has shown better
performance with the ledger on its own disk
performance with the ledger on its own disk
- Accounts and ledger _can_ be stored on the same disk, however due to high
IOPS, this is not recommended
IOPS, this is not recommended
- The Samsung 970 and 980 Pro series SSDs are popular with the validator community
- GPUs
- Not strictly necessary at this time
- Motherboard and power supply speced to add one or more high-end GPUs in the
future suggested
future suggested
## Virtual machines on Cloud Platforms

54
docs/src/running-validator/validator-start.md
View File

@ -47,12 +47,14 @@ that CUDA is enabled: `"[<timestamp> solana::validator] CUDA is enabled"`
## System Tuning
### Linux
#### Automatic
The solana repo includes a daemon to adjust system settings to optimize performance
(namely by increasing the OS UDP buffer and file mapping limits).
The daemon (`solana-sys-tuner`) is included in the solana binary release. Restart
it, *before* restarting your validator, after each software upgrade to ensure that
it, _before_ restarting your validator, after each software upgrade to ensure that
the latest recommended settings are applied.
To run it:
@ -62,10 +64,12 @@ sudo solana-sys-tuner --user $(whoami) > sys-tuner.log 2>&1 &
```
#### Manual
If you would prefer to manage system settings on your own, you may do so with
the following commands.
##### **Increase UDP buffers**
```bash
sudo bash -c "cat >/etc/sysctl.d/20-solana-udp-buffers.conf <<EOF
# Increase UDP buffer size
@ -75,39 +79,50 @@ net.core.wmem_default = 134217728
net.core.wmem_max = 134217728
EOF"
```
```bash
sudo sysctl -p /etc/sysctl.d/20-solana-udp-buffers.conf
```
##### **Increased memory mapped files limit**
```bash
sudo bash -c "cat >/etc/sysctl.d/20-solana-mmaps.conf <<EOF
# Increase memory mapped files limit
vm.max_map_count = 700000
EOF"
```
```bash
sudo sysctl -p /etc/sysctl.d/20-solana-mmaps.conf
```
Add
```
LimitNOFILE=700000
```
to the `[Service]` section of your systemd service file, if you use one,
otherwise add
```
DefaultLimitNOFILE=700000
```
to the `[Manager]` section of `/etc/systemd/system.conf`.
```bash
sudo systemctl daemon-reload
```
```bash
sudo bash -c "cat >/etc/security/limits.d/90-solana-nofiles.conf <<EOF
# Increase process file descriptor count limit
* - nofile 700000
EOF"
```
```bash
### Close all open sessions (log out then, in again) ###
```
@ -299,24 +314,27 @@ example, `solana-validator --dynamic-port-range 11000-11010 ...` will restrict
the validator to ports 11000-11010.
### Limiting ledger size to conserve disk space
The `--limit-ledger-size` parameter allows you to specify how many ledger
[shreds](../terminology.md#shred) your node retains on disk. If you do not
include this parameter, the validator will keep the entire ledger until it runs
out of disk space.
The default value attempts to keep the ledger disk usage under 500GB. More or
The default value attempts to keep the ledger disk usage under 500GB. More or
less disk usage may be requested by adding an argument to `--limit-ledger-size`
if desired. Check `solana-validator --help` for the default limit value used by
`--limit-ledger-size`. More information about
`--limit-ledger-size`. More information about
selecting a custom limit value is [available
here](https://github.com/solana-labs/solana/blob/583cec922b6107e0f85c7e14cb5e642bc7dfb340/core/src/ledger_cleanup_service.rs#L15-L26).
### Systemd Unit
Running the validator as a systemd unit is one easy way to manage running in the
background.
Assuming you have a user called `sol` on your machine, create the file `/etc/systemd/system/sol.service` with
the following:
```
[Unit]
Description=Solana Validator
@ -339,15 +357,17 @@ WantedBy=multi-user.target
```
Now create `/home/sol/bin/validator.sh` to include the desired `solana-validator`
command-line. Ensure that running `/home/sol/bin/validator.sh` manually starts
command-line. Ensure that running `/home/sol/bin/validator.sh` manually starts
the validator as expected. Don't forget to mark it executable with `chmod +x /home/sol/bin/validator.sh`
Start the service with:
```bash
$ sudo systemctl enable --now sol
```
### Logging
#### Log output tuning
The messages that a validator emits to the log can be controlled by the `RUST_LOG`
@ -376,6 +396,7 @@ instead of the validator's, which will kill them both.
An example setup for the `logrotate`, which assumes that the validator is
running as a systemd service called `sol.service` and writes a log file at
/home/sol/solana-validator.log:
```bash
# Setup log rotation
@ -394,11 +415,13 @@ systemctl restart logrotate.service
```
### Disable port checks to speed up restarts
Once your validator is operating normally, you can reduce the time it takes to
restart your validator by adding the `--no-port-check` flag to your
`solana-validator` command-line.
### Disable snapshot compression to reduce CPU usage
If you are not serving snapshots to other validators, snapshot compression can
be disabled to reduce CPU load at the expense of slightly more disk usage for
local snapshot storage.
@ -407,6 +430,7 @@ Add the `--snapshot-compression none` argument to your `solana-validator`
command-line arguments and restart the validator.
### Using a ramdisk with spill-over into swap for the accounts database to reduce SSD wear
If your machine has plenty of RAM, a tmpfs ramdisk
([tmpfs](https://man7.org/linux/man-pages/man5/tmpfs.5.html)) may be used to hold
the accounts database
@ -418,18 +442,20 @@ A 300GB tmpfs partition is recommended, with an accompanying 250GB swap
partition.
Example configuration:
1. `sudo mkdir /mnt/solana-accounts`
2. Add a 300GB tmpfs parition by adding a new line containing `tmpfs
/mnt/solana-accounts tmpfs rw,size=300G,user=sol 0 0` to `/etc/fstab`
(assuming your validator is running under the user "sol"). **CAREFUL: If you
2. Add a 300GB tmpfs parition by adding a new line containing `tmpfs /mnt/solana-accounts tmpfs rw,size=300G,user=sol 0 0` to `/etc/fstab`
(assuming your validator is running under the user "sol"). **CAREFUL: If you
incorrectly edit /etc/fstab your machine may no longer boot**
3. Create at least 250GB of swap space
- Choose a device to use in place of `SWAPDEV` for the remainder of these instructions.
Ideally select a free disk partition of 250GB or greater on a fast disk. If one is not
available, create a swap file with `sudo dd if=/dev/zero of=/swapfile bs=1MiB count=250KiB`,
set its permissions with `sudo chmod 0600 /swapfile` and use `/swapfile` as `SWAPDEV` for
the remainder of these instructions
- Format the device for usage as swap with `sudo mkswap SWAPDEV`
- Choose a device to use in place of `SWAPDEV` for the remainder of these instructions.
Ideally select a free disk partition of 250GB or greater on a fast disk. If one is not
available, create a swap file with `sudo dd if=/dev/zero of=/swapfile bs=1MiB count=250KiB`,
set its permissions with `sudo chmod 0600 /swapfile` and use `/swapfile` as `SWAPDEV` for
the remainder of these instructions
- Format the device for usage as swap with `sudo mkswap SWAPDEV`
4. Add the swap file to `/etc/fstab` with a new line containing `SWAPDEV swap swap defaults 0 0`
5. Enable swap with `sudo swapon -a` and mount the tmpfs with `sudo mount /mnt/solana-accounts/`
6. Confirm swap is active with `free -g` and the tmpfs is mounted with `mount`
@ -440,7 +466,7 @@ command-line arguments and restart the validator.
### Account indexing
As the number of populated accounts on the cluster grows, account-data RPC
requests that scan the entire account set -- like
requests that scan the entire account set -- like
[`getProgramAccounts`](developing/clients/jsonrpc-api.md#getprogramaccounts) and
[SPL-token-specific requests](developing/clients/jsonrpc-api.md#gettokenaccountsbydelegate) --
may perform poorly. If your validator needs to support any of these requests,

67
docs/src/running-validator/vote-accounts.md
View File

@ -2,30 +2,33 @@
title: Vote Account Management
---
This page describes how to set up an on-chain _vote account_. Creating a vote
This page describes how to set up an on-chain _vote account_. Creating a vote
account is needed if you plan to run a validator node on Solana.
## Create a Vote Account
A vote account can be created with the
[create-vote-account](../cli/usage.md#solana-create-vote-account) command.
The vote account can be configured when first created or after the validator is
running. All aspects of the vote account can be changed except for the
running. All aspects of the vote account can be changed except for the
[vote account address](#vote-account-address), which is fixed for the lifetime
of the account.
### Configure an Existing Vote Account
- To change the [validator identity](#validator-identity), use
[vote-update-validator](../cli/usage.md#solana-vote-update-validator).
- To change the [vote authority](#vote-authority), use
[vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter).
- To change the [withdraw authority](#withdraw-authority), use
[vote-authorize-withdrawer](../cli/usage.md#solana-vote-authorize-withdrawer).
- To change the [commission](#commission), use
[vote-update-commission](../cli/usage.md#solana-vote-update-commission).
- To change the [validator identity](#validator-identity), use
[vote-update-validator](../cli/usage.md#solana-vote-update-validator).
- To change the [vote authority](#vote-authority), use
[vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter).
- To change the [withdraw authority](#withdraw-authority), use
[vote-authorize-withdrawer](../cli/usage.md#solana-vote-authorize-withdrawer).
- To change the [commission](#commission), use
[vote-update-commission](../cli/usage.md#solana-vote-update-commission).
## Vote Account Structure
### Vote Account Address
A vote account is created at an address that is either the public key of a
keypair file, or at a derived address based on a keypair file's public key and
a seed string.
@ -44,14 +47,14 @@ vote transaction fees submitted to the vote account.
Because the validator is expected to vote on most valid blocks it receives,
the validator identity account is frequently
(potentially multiple times per second) signing transactions and
paying fees. For this reason the validator identity keypair must be
paying fees. For this reason the validator identity keypair must be
stored as a "hot wallet" in a keypair file on the same system the validator
process is running.
Because a hot wallet is generally less secure than an offline or "cold" wallet,
the validator operator may choose to store only enough SOL on the identity
account to cover voting fees for a limited amount of time, such as a few weeks
or months. The validator identity account could be periodically topped off
or months. The validator identity account could be periodically topped off
from a more secure wallet.
This practice can reduce the risk of loss of funds if the validator node's
@ -64,8 +67,8 @@ the [vote-update-validator](../cli/usage.md#solana-vote-update-validator) comman
### Vote Authority
The _vote authority_ keypair is used to sign each vote transaction the validator
node wants to submit to the cluster. This doesn't necessarily have to be unique
from the validator identity, as you will see later in this document. Because
node wants to submit to the cluster. This doesn't necessarily have to be unique
from the validator identity, as you will see later in this document. Because
the vote authority, like the validator identity, is signing transactions
frequently, this also must be a hot keypair on the same file system as the
validator process.
@ -73,22 +76,22 @@ validator process.
The vote authority can be set to the same address as the validator identity.
If the validator identity is also the vote authority, only one
signature per vote transaction is needed in order to both sign the vote and pay
the transaction fee. Because transaction fees on Solana are assessed
the transaction fee. Because transaction fees on Solana are assessed
per-signature, having one signer instead of two will result in half the transaction
fee paid compared to setting the vote authority and validator identity to two
different accounts.
The vote authority can be set when the vote account is created. If it is not
The vote authority can be set when the vote account is created. If it is not
provided, the default behavior is to assign it the same as the validator identity.
The vote authority can be changed later with the
[vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter) command.
The vote authority can be changed at most once per epoch. If the authority is
The vote authority can be changed at most once per epoch. If the authority is
changed with [vote-authorize-voter](../cli/usage.md#solana-vote-authorize-voter),
this will not take effect until the beginning of the next epoch.
To support a smooth transition of the vote signing,
`solana-validator` allows the `--authorized-voter` argument to be specified
multiple times. This allows the validator process to keep voting successfully
multiple times. This allows the validator process to keep voting successfully
when the network reaches an epoch boundary at which the validator's vote
authority account changes.
@ -96,7 +99,7 @@ authority account changes.
The _withdraw authority_ keypair is used to withdraw funds from a vote account
using the [withdraw-from-vote-account](../cli/usage.md#solana-withdraw-from-vote-account)
command. Any network rewards a validator earns are deposited into the vote
command. Any network rewards a validator earns are deposited into the vote
account and are only retrievable by signing with the withdraw authority keypair.
The withdraw authority is also required to sign any transaction to change
@ -108,7 +111,7 @@ the withdraw authority keypair in an offline/cold wallet, as it is
not needed to sign frequent transactions.
The withdraw authority can be set at vote account creation with the
`--authorized-withdrawer` option. If this is not provided, the validator
`--authorized-withdrawer` option. If this is not provided, the validator
identity will be set as the withdraw authority by default.
The withdraw authority can be changed later with the
@ -118,7 +121,7 @@ command.
### Commission
_Commission_ is the percent of network rewards earned by a validator that are
deposited into the validator's vote account. The remainder of the rewards
deposited into the validator's vote account. The remainder of the rewards
are distributed to all of the stake accounts delegated to that vote account,
proportional to the active stake weight of each stake account.
@ -129,7 +132,7 @@ will be deposited into delegated stake accounts as immediately active stake.
A validator may choose to set a low commission to try to attract more stake
delegations as a lower commission results in a larger percentage of rewards
passed along to the delegator. As there are costs associated with setting up
passed along to the delegator. As there are costs associated with setting up
and operating a validator node, a validator would ideally set a high enough
commission to at least cover their expenses.
@ -146,13 +149,14 @@ The integer represents the number of percentage points for the commission, so
creating an account with `--commission 10` will set a 10% commission.
## Key Rotation
Rotating the vote account authority keys require special handling when dealing
with a live validator.
### Vote Account Validator Identity
You will need access to the _withdraw authority_ keypair for the vote account to
change the validator identity. The follow steps assume that
change the validator identity. The follow steps assume that
`~/withdraw-authority.json` is that keypair.
1. Create the new validator identity keypair, `solana-keygen new -o ~/new-validator-keypair.json`.
@ -162,28 +166,27 @@ change the validator identity. The follow steps assume that
4. Restart your validator with the new identity keypair for the `--identity` argument
### Vote Account Authorized Voter
The _vote authority_ keypair may only be changed at epoch boundaries and
requires some additional arguments to `solana-validator` for a seamless
migration.
1. Run `solana epoch-info`. If there is not much time remaining time in the
1. Run `solana epoch-info`. If there is not much time remaining time in the
current epoch, consider waiting for the next epoch to allow your validator
plenty of time to restart and catch up.
2. Create the new vote authority keypair, `solana-keygen new -o ~/new-vote-authority.json`.
3. Determine the current _vote authority_ keypair by running `solana
vote-account ~/vote-account-keypair.json`. It may be validator's
identity account (the default) or some other keypair. The following steps
assume that ` ~/validator-keypair.json` is that keypair.
3. Determine the current _vote authority_ keypair by running `solana vote-account ~/vote-account-keypair.json`. It may be validator's
identity account (the default) or some other keypair. The following steps
assume that `~/validator-keypair.json` is that keypair.
4. Run `solana vote-authorize-voter ~/vote-account-keypair.json ~/validator-keypair.json ~/new-vote-authority.json`.
The new vote authority is scheduled to become active starting at the next epoch.
5. `solana-validator` now needs to be restarted with the old and new vote
authority keypairs, so that it can smoothly transition at the next epoch. Add
the two arguments on restart: `--authorized-voter ~/validator-keypair.json
--authorized-voter ~/new-vote-authority.json`
the two arguments on restart: `--authorized-voter ~/validator-keypair.json --authorized-voter ~/new-vote-authority.json`
6. After the cluster reaches the next epoch, remove the
`--authorized-voter ~/validator-keypair.json` argument and restart
`solana-validator`, as the old vote authority keypair is no longer required.
### Vote Account Authorized Withdrawer
No special handling is required. Use the `solana vote-authorize-withdrawer` command as needed.
No special handling is required. Use the `solana vote-authorize-withdrawer` command as needed.

51
docs/src/staking.md
View File

@ -2,9 +2,9 @@
title: Staking on Solana
---
*Note before reading: All references to increases in values are in absolute
_Note before reading: All references to increases in values are in absolute
terms with regards to balance of SOL.
This document makes no suggestion as to the monetary value of SOL at any time.*
This document makes no suggestion as to the monetary value of SOL at any time._
Staking your SOL tokens on Solana is the best way you can help secure the world's
highest-performing blockchain network, and
@ -20,7 +20,7 @@ This is achieved by aligning the financial incentives of the token-holders
(delegators) and the validators to whom they delegate.
The more stake a validator has delegated to them, the more often this validator
is chosen to write new transactions to the ledger. The more transactions
is chosen to write new transactions to the ledger. The more transactions
the validator writes, the more rewards they and their delegators earn.
Validators who configure their systems to be able to process more transactions
at a time not only earn proportionally more rewards for doing so, they also
@ -28,21 +28,21 @@ keep the network running as fast and as smoothly as possible.
Validators incur costs by running and maintaining their systems, and this is
passed on to delegators in the form of a fee collected as a percentage of
rewards earned. This fee is known as a *commission*. As validators earn more
rewards earned. This fee is known as a _commission_. As validators earn more
rewards the more stake is delegated to them, they may compete with one another
to offer the lowest commission for their services, in order to attract more
delegated stake.
There is a risk of loss of tokens when staking, through a process known as
*slashing*. Slashing involves the removal and destruction of a portion of a
_slashing_. Slashing involves the removal and destruction of a portion of a
validator's delegated stake in response to intentional malicious behavior,
such as creating invalid transactions or censoring certain types of transactions
or network participants.
If a validator is slashed, all token holders who have delegated stake to that
validator will lose a portion of their delegation. While this means an immediate
validator will lose a portion of their delegation. While this means an immediate
loss for the token holder, it also is a loss of future rewards for the validator
due to their reduced total delegation. More details on the slashing roadmap can
due to their reduced total delegation. More details on the slashing roadmap can
be found
[here](proposals/optimistic-confirmation-and-slashing.md#slashing-roadmap).
@ -51,6 +51,7 @@ and token holders' financial incentives, which in turn help keeps the network
secure, robust and performing at its best.
## How do I stake my SOL tokens?
In order to stake tokens on Solana, you first will need to transfer some SOL
into a wallet that supports staking, then follow the steps or instructions
provided by the wallet to create a stake account and delegate your stake.
@ -58,55 +59,63 @@ Different wallets will vary slightly in their process for this but the general
description is below.
#### Supported Wallets
Staking operations are supported by the following wallet solutions:
- SolFlare.com in conjunction with a keystore file or a Ledger Nano.
Check out our [guide to using SolFlare](wallet-guide/solflare.md) for details.
- SolFlare.com in conjunction with a keystore file or a Ledger Nano.
Check out our [guide to using SolFlare](wallet-guide/solflare.md) for details.
- Solana command line tools can perform all stake operations in conjunction
with a CLI-generated keypair file wallet, a paper wallet, or with a connected
Ledger Nano.
[Staking commands using the Solana Command Line Tools](cli/delegate-stake.md).
- Solana command line tools can perform all stake operations in conjunction
with a CLI-generated keypair file wallet, a paper wallet, or with a connected
Ledger Nano.
[Staking commands using the Solana Command Line Tools](cli/delegate-stake.md).
#### Create a Stake Account
A stake account is a different type of account from a wallet address
that is used to simply send and receive SOL tokens to other addresses. If you
have received SOL in a wallet address you control, you can use some of
these tokens to create and fund a new stake account, which will have a different
address than the wallet you used to create it.
Depending on which wallet you are using the steps to create a stake account
may vary slightly. Not all wallets support stake accounts, see
may vary slightly. Not all wallets support stake accounts, see
[Supported Wallets](#supported-wallets).
#### Select a Validator
After a stake account is created, you will likely want to delegate the SOL
to a validator node. Below are a few places where you can get information about
to a validator node. Below are a few places where you can get information about
the validators who are currently participating in running the network.
The Solana Labs team and the Solana Foundation do not recommend any particular
validator.
The Mainnet Beta validators introduce themselves and their services on this
Solana Forum thread:
- https://forums.solana.com/t/validator-information-thread
- https://forums.solana.com/t/validator-information-thread
The site solanabeach.io is built and maintained by one of our validators,
Staking Facilities. It provides a some high-level graphical information about
Staking Facilities. It provides a some high-level graphical information about
the network as a whole, as well as a list of each validator and some recent
performance statistics about each one.
- https://solanabeach.io
- https://solanabeach.io
To view block production statistics, use the Solana command-line tools:
- `solana validators`
- `solana block-production`
- `solana validators`
- `solana block-production`
The Solana team does not make recommendations on how to interpret this
information. Potential delegators should do their own due diligence.
information. Potential delegators should do their own due diligence.
#### Delegate your Stake
Once you have decided to which validator or validators you will delegate, use
a supported wallet to delegate your stake account to the validator's vote
account address.
## Stake Account Details
For more information about the operations and permissions associated with a
stake account, please see [Stake Accounts](staking/stake-accounts.md)

65
docs/src/staking/stake-accounts.md
View File

@ -5,20 +5,21 @@ title: Stake Account Structure
A stake account on Solana can be used to delegate tokens to validators on
the network to potentially earn rewards for the owner of the stake account.
Stake accounts are created and managed differently than a traditional wallet
address, known as a *system account*. A system account is only able to send and
address, known as a _system account_. A system account is only able to send and
receive SOL from other accounts on the network, whereas a stake account supports
more complex operations needed to manage a delegation of tokens.
Stake accounts on Solana also work differently than those of other Proof-of-Stake
blockchain networks that you may be familiar with. This document describes the
blockchain networks that you may be familiar with. This document describes the
high-level structure and functions of a Solana stake account.
#### Account Address
Each stake account has a unique address which can be used to look up the account
information in the command line or in any network explorer tools. However,
information in the command line or in any network explorer tools. However,
unlike a wallet address in which the holder of the address's keypair controls
the wallet, the keypair associated with a stake account address does not necessarily have
any control over the account. In fact, a keypair or private key may not even
any control over the account. In fact, a keypair or private key may not even
exist for a stake account's address.
The only time a stake account's address has a keypair file is when [creating
@ -27,27 +28,30 @@ a new keypair file is created first only to ensure that the stake account's
address is new and unique.
#### Understanding Account Authorities
Certain types of accounts may have one or more *signing authorities*
Certain types of accounts may have one or more _signing authorities_
associated with a given account. An account authority is used to sign certain
transactions for the account it controls. This is different from
transactions for the account it controls. This is different from
some other blockchain networks where the holder of the keypair associated with
the account's address controls all of the account's activity.
Each stake account has two signing authorities specified by their respective address,
each of which is authorized to perform certain operations on the stake account.
The *stake authority* is used to sign transactions for the following operations:
- Delegating stake
- Deactivating the stake delegation
- Splitting the stake account, creating a new stake account with a portion of the
funds in the first account
- Merging two stake accounts into one
- Setting a new stake authority
The _stake authority_ is used to sign transactions for the following operations:
The *withdraw authority* signs transactions for the following:
- Withdrawing un-delegated stake into a wallet address
- Setting a new withdraw authority
- Setting a new stake authority
- Delegating stake
- Deactivating the stake delegation
- Splitting the stake account, creating a new stake account with a portion of the
funds in the first account
- Merging two stake accounts into one
- Setting a new stake authority
The _withdraw authority_ signs transactions for the following:
- Withdrawing un-delegated stake into a wallet address
- Setting a new withdraw authority
- Setting a new stake authority
The stake authority and withdraw authority are set when the stake account is
created, and they can be changed to authorize a new signing address at any time.
@ -62,9 +66,10 @@ Securing the withdraw authority against loss or theft is of utmost importance
when managing a stake account.
#### Multiple Delegations
Each stake account may only be used to delegate to one validator at a time.
All of the tokens in the account are either delegated or un-delegated, or in the
process of becoming delegated or un-delegated. To delegate a fraction of your
process of becoming delegated or un-delegated. To delegate a fraction of your
tokens to a validator, or to delegate to multiple validators, you must create
multiple stake accounts.
@ -77,22 +82,24 @@ The same stake and withdraw authorities can be assigned to multiple
stake accounts.
#### Merging stake accounts
Two stake accounts that have the same authorities and lockup can be merged into
a single resulting stake account. A merge is possible between two stakes in the
following states with no additional conditions:
* two deactivated stakes
* an inactive stake into an activating stake during its activation epoch
- two deactivated stakes
- an inactive stake into an activating stake during its activation epoch
For the following cases, the voter pubkey and vote credits observed must match:
* two activated stakes
* two activating accounts that share an activation epoch, during the activation epoch
- two activated stakes
- two activating accounts that share an activation epoch, during the activation epoch
All other combinations of stake states will fail to merge, including all "transient"
states, where a stake is activating or deactivating with a non-zero effective stake.
#### Delegation Warmup and Cooldown
When a stake account is delegated, or a delegation is deactivated, the operation
does not take effect immediately.
@ -109,24 +116,28 @@ Details on the warmup and cooldown timing can be found
[here](../cluster/stake-delegation-and-rewards.md#stake-warmup-cooldown-withdrawal).
#### Lockups
Stake accounts can have a lockup which prevents the tokens they hold from being
withdrawn before a particular date or epoch has been
reached. While locked up, the stake account can still be delegated, un-delegated,
or split, and its stake and withdraw authorities can be changed as normal. Only
reached. While locked up, the stake account can still be delegated, un-delegated,
or split, and its stake and withdraw authorities can be changed as normal. Only
withdrawal into a wallet address is not allowed.
A lockup can only be added when a stake account is first created, but it can be
modified later, by the *lockup authority* or *custodian*, the address of which
modified later, by the _lockup authority_ or _custodian_, the address of which
is also set when the account is created.
#### Destroying a Stake Account
Like other types of accounts on the Solana network, a stake account that has a
balance of 0 SOL is no longer tracked. If a stake account is not delegated
balance of 0 SOL is no longer tracked. If a stake account is not delegated
and all of the tokens it contains are withdrawn to a wallet address, the account
at that address is effectively destroyed, and will need to be manually
re-created for the address to be used again.
#### Viewing Stake Accounts
Stake account details can be viewed on the Solana Explorer by copying and pasting
an account address into the search bar.
- http://explorer.solana.com/accounts
- http://explorer.solana.com/accounts

2
docs/src/staking/stake-programming.md
View File

@ -8,12 +8,14 @@ and community have developed several on-chain and off-chain programs to make
stakes easier to manage.
#### Stake-o-matic aka Auto-delegation Bots
This off-chain program manages a large population of validators staked by a
central authority. The Solana Foundation uses an auto-delegation bot to regularly delegate its
stake to "non-delinquent" validators that meet specified performance requirements. More information can be found on the
[official announcement](https://forums.solana.com/t/stake-o-matic-delegation-matching-program/790).
#### Stake Pools
This on-chain program pools together SOL to be staked by a manager, allowing SOL
holders to stake and earn rewards without managing stakes.
Users deposit SOL in exchange for SPL tokens (staking derivatives) that represent their ownership in the stake pool. The pool

3
docs/src/tour-de-sol/registration/rewards.md
View File

@ -3,11 +3,13 @@ title: Compensation
---
## Compensation Calculation
Compensation will be calculated according to the compensation design described in [this forum post](https://forums.solana.com/t/tour-de-sol-updates-to-tour-de-sol-and-bug-bounty-compensation-structure/1132).
Please also see section “2\(f\) Tour de Sol Details” of the [TOUR DE SOL PARTICIPATION TERMS](https://drive.google.com/file/d/15ueLG6VJoQ5Hx4rnpjFeuL3pG5DbrBbE/view) for additional compensation details.
## Requirements to Receive Rewards
Participants must have signed the Tour de SOL participation agreement,
passed KYC/AML , as well as filled out the W-8 BEN or W-9 tax form
\(depending on your residency\) prior to participating in the Tour.
@ -17,6 +19,7 @@ complete registration. The final registrations dates will be announced
publicly on a stage-by-stage basis.
## Tax Implications
Participants are entering into a service agreement with Solana with discretionary compensation associated with the services. They are not considered to be a full-time employee of the company and therefore Solana is collecting W-9 and W-8 BEN forms in order to support tax reporting obligations, if applicable. Solana recommends participants consult with a tax accountant to understand any potential tax implications.
Also, as stated in Sections 2i, 2k and 10c of the [TOUR DE SOL PARTICIPATION TERMS](https://drive.google.com/file/d/15ueLG6VJoQ5Hx4rnpjFeuL3pG5DbrBbE/view):

4
docs/src/tour-de-sol/useful-links.md
View File

@ -10,6 +10,6 @@ description: Where to go after you've read this guide
### Validator Discussions
The Solana Discord server is where all the action happens. Join the server by
The Solana Discord server is where all the action happens. Join the server by
visiting https://solana.com/discord. Check out the "Testnet (Tour de SOL)" channel
group.
group.

2
docs/src/transaction_fees.md
View File

@ -14,7 +14,7 @@ Network consensus votes are sent as normal system transfers, which means that va
Many current blockchain economies \(e.g. Bitcoin, Ethereum\), rely on protocol-based rewards to support the economy in the short term, with the assumption that the revenue generated through transaction fees will support the economy in the long term, when the protocol derived rewards expire. In an attempt to create a sustainable economy through protocol-based rewards and transaction fees, a fixed portion (initially 50%) of each transaction fee is destroyed, with the remaining fee going to the current leader processing the transaction. A scheduled global inflation rate provides a source for rewards distributed to validation-clients, through the process described above.
Transaction fees are set by the network cluster based on recent historical throughput, see [Congestion Driven Fees](implemented-proposals/transaction-fees.md#congestion-driven-fees). This minimum portion of each transaction fee can be dynamically adjusted depending on historical *signatures-per-slot*. In this way, the protocol can use the minimum fee to target a desired hardware utilization. By monitoring a protocol specified *signatures-per-slot* with respect to a desired, target usage amount, the minimum fee can be raised/lowered which should, in turn, lower/raise the actual *signature-per-slot* per block until it reaches the target amount. This adjustment process can be thought of as similar to the difficulty adjustment algorithm in the Bitcoin protocol, however in this case it is adjusting the minimum transaction fee to guide the transaction processing hardware usage to a desired level.
Transaction fees are set by the network cluster based on recent historical throughput, see [Congestion Driven Fees](implemented-proposals/transaction-fees.md#congestion-driven-fees). This minimum portion of each transaction fee can be dynamically adjusted depending on historical _signatures-per-slot_. In this way, the protocol can use the minimum fee to target a desired hardware utilization. By monitoring a protocol specified _signatures-per-slot_ with respect to a desired, target usage amount, the minimum fee can be raised/lowered which should, in turn, lower/raise the actual _signature-per-slot_ per block until it reaches the target amount. This adjustment process can be thought of as similar to the difficulty adjustment algorithm in the Bitcoin protocol, however in this case it is adjusting the minimum transaction fee to guide the transaction processing hardware usage to a desired level.
As mentioned, a fixed-proportion of each transaction fee is to be destroyed. The intent of this design is to retain leader incentive to include as many transactions as possible within the leader-slot time, while providing an inflation limiting mechanism that protects against "tax evasion" attacks \(i.e. side-channel fee payments\).

7
docs/src/wallet-guide/apps.md
View File

@ -6,6 +6,7 @@ Solana is supported by multiple third-party apps which should provide a familiar
experience for most people who are new or experienced with using crypto wallets.
## Exodus
Send, receive & exchange cryptocurrency with ease on the world's leading Desktop, Mobile and Hardware crypto wallets.
Download [Exodus](https://exodus.com/) to easily and securely manage your Solana tokens.
@ -13,10 +14,11 @@ Download [Exodus](https://exodus.com/) to easily and securely manage your Solana
Exodus includes live charts, a built-in exchange, and 24/7 human support.
## Trust Wallet
[Trust Wallet](https://trustwallet.com/) is an app available for iOS and Android
and can be used to send and receive SOL tokens.
*Note: Trust Wallet does not support stake accounts or staking operations*
_Note: Trust Wallet does not support stake accounts or staking operations_
### Trust Wallet Security
@ -39,7 +41,8 @@ viewed at any later time in the app by following these steps:
- Under the Options menu for a particular wallet tap "Show Recovery Phrase"
## Coin98
[Coin98](https://coin98.app/) is an app available for iOS and Android and can
be used to send and receive SOL tokens.
*Note: Coin98 does not support stake accounts or staking operations*
_Note: Coin98 does not support stake accounts or staking operations_

6
docs/src/wallet-guide/hardware-wallets/ledger.md
View File

@ -3,7 +3,7 @@ title: Ledger Nano
---
This page describes how to use a Ledger Nano S or Nano X to interact with Solana
using the command line tools. To see other solutions to interact with Solana with
using the command line tools. To see other solutions to interact with Solana with
your Nano, [click here](../ledger-live.md#interact-with-the-solana-network).
## Before You Begin
@ -55,8 +55,8 @@ solana-keygen pubkey usb://ledger?key=1
solana-keygen pubkey usb://ledger?key=2
```
* NOTE: keypair url parameters are ignored in **zsh**
&nbsp;[see troubleshooting for more info](#troubleshooting)
- NOTE: keypair url parameters are ignored in **zsh**
&nbsp;[see troubleshooting for more info](#troubleshooting)
You can use other values for the number after `key=` as well.
Any of the addresses displayed by these commands are valid Solana wallet

36
docs/src/wallet-guide/ledger-live.md
View File

@ -14,15 +14,15 @@ on your Nano device, users have several options of how to
## Getting Started
- Order a [Nano S](https://shop.ledger.com/products/ledger-nano-s) or
[Nano X](https://shop.ledger.com/pages/ledger-nano-x) from Ledger.
[Nano X](https://shop.ledger.com/pages/ledger-nano-x) from Ledger.
- Follow the instructions for device setup included in the package,
or [Ledger's Start page](https://www.ledger.com/start/)
- Install [Ledger Live desktop software](https://www.ledger.com/ledger-live/)
- If you already have Ledger Live installed, please update to the latest
version of Ledger Live, which enables the newest firmware and app updates.
version of Ledger Live, which enables the newest firmware and app updates.
- Connect your Nano to your computer and follow the on-screen instructions.
- Update the firmware on your new Nano. This is needed to ensure you are able
to install the latest version of the Solana App.
- Update the firmware on your new Nano. This is needed to ensure you are able
to install the latest version of the Solana App.
- [Update Nano S Firmware](https://support.ledger.com/hc/en-us/articles/360002731113-Update-Ledger-Nano-S-firmware)
- [Update Nano X Firmware](https://support.ledger.com/hc/en-us/articles/360013349800)
@ -30,7 +30,7 @@ to install the latest version of the Solana App.
- Open Ledger Live
- Click on "Manager" in the left pane on the app and search for "Solana" in the
App Catalog, then click "Install".
App Catalog, then click "Install".
- Make sure your device is plugged in via USB and is unlocked with its PIN
- You may be prompted on the Nano to confirm the install of Solana App
- "Solana" should now show as "Installed" in the Ledger Live Manager
@ -42,14 +42,14 @@ of the Solana App, please upgrade to version `v1.0.1` by following these steps.
- Make sure you have Ledger Live version 2.10.0 or later.
- To check your version of Ledger Live, click on the Settings button in the
upper-right corner, then click "About". If a newer version of Ledger Live is
available, you should see a banner prompting you to upgrade when you first open
Ledger Live.
upper-right corner, then click "About". If a newer version of Ledger Live is
available, you should see a banner prompting you to upgrade when you first open
Ledger Live.
- Update the firmware on your Nano
- [Update Nano S Firmware](https://support.ledger.com/hc/en-us/articles/360002731113-Update-Ledger-Nano-S-firmware)
- [Update Nano X Firmware](https://support.ledger.com/hc/en-us/articles/360013349800)
- After a successful firmware update, the Solana app should automatically get
re-installed with the latest version of the app.
- After a successful firmware update, the Solana app should automatically get
re-installed with the latest version of the app.
## Interact with the Solana network
@ -57,20 +57,20 @@ Users can use any of the following options to use their Nano to interact with
Solana:
- [SolFlare.com](https://solflare.com/) is a non-custodial web wallet built
specifically for Solana and supports basic transfers and staking operations
with the Ledger device.
Check out our guide for [using a Nano with SolFlare](solflare.md).
specifically for Solana and supports basic transfers and staking operations
with the Ledger device.
Check out our guide for [using a Nano with SolFlare](solflare.md).
- Developers and advanced users may
[use a Nano with the Solana command line tools](hardware-wallets/ledger.md).
New wallet features are almost always supported in the native command line tools
before being supported by third-party wallets.
[use a Nano with the Solana command line tools](hardware-wallets/ledger.md).
New wallet features are almost always supported in the native command line tools
before being supported by third-party wallets.
## Known Issues
- Nano X sometimes cannot connect to web wallets using the Windows operating
system. This is likely to affect any browser-based wallets that use WebUSB.
The Ledger team is working to resolve this.
system. This is likely to affect any browser-based wallets that use WebUSB.
The Ledger team is working to resolve this.
## Support

80
docs/src/wallet-guide/solflare.md
View File

@ -20,21 +20,22 @@ receive SOL tokens, and how to create and manage a stake account.
## Getting Started
Go to https://www.solflare.com in a supported browser. Most popular web browsers
Go to https://www.solflare.com in a supported browser. Most popular web browsers
should work when interacting with a Keystore File, but currently only
Chrome and Brave are supported when interacting with a Ledger Nano.
### Using a Keystore File
#### Create a new Keystore File
To create a wallet with a Keystore file, click on "Create a Wallet" and select
"Using Keystore File". Follow the prompts to create a password which will be
"Using Keystore File". Follow the prompts to create a password which will be
used to encrypt your Keystore file, and then to download the new file to your
computer. You will be prompted to then upload the Keystore file back to the site
computer. You will be prompted to then upload the Keystore file back to the site
to verify that the download was saved correctly.
**NOTE: If you lose your Keystore file or the password used to encrypt it, any
funds in that wallet will be lost permanently. Neither the Solana team nor the
funds in that wallet will be lost permanently. Neither the Solana team nor the
SolFlare developers can help you recover lost keys.**
You may want to consider saving a backup copy of your Keystore file on an
@ -42,34 +43,37 @@ external drive separate from your main computer, and storing your password in a
separate location.
#### Access your wallet with a Keystore File
To use SolFlare with a previously created Keystore file, click on
"Access a Wallet" and select "Using Keystore File". If you just created a new
"Access a Wallet" and select "Using Keystore File". If you just created a new
Keystore file, you will be taken to the Access page directly.
You will be prompted to enter the password and upload your Keystore file,
then you will be taken to the wallet interface main page.
### Using a Ledger Nano hardware wallet
*NOTE: Please see [known issues](ledger-live.md#known-issues) for any current
limitations in using the Nano.*
_NOTE: Please see [known issues](ledger-live.md#known-issues) for any current
limitations in using the Nano._
#### Initial Device Setup
To use a Ledger Nano with SolFlare, first ensure you have
[set up your Nano](ledger-live.md) and have [installed the latest version of
the Solana app](ledger-live.md#upgrade-to-the-latest-version-of-the-solana-app)
on your device.
#### Select a Ledger address to access
Plug in your Nano and open the Solana app so the device screen displays
"Application is Ready".
From the SolFlare home page, click "Access a Wallet" then select "Using Ledger
Nano S | Ledger Nano X". Under "Select derivation path", select the only option:
Nano S | Ledger Nano X". Under "Select derivation path", select the only option:
```Solana - 44`/501`/```
`` Solana - 44`/501`/ ``
Note: Your browser may prompt you to ask if SolFlare may communicate with your
Ledger device. Click to allow this.
Ledger device. Click to allow this.
Select an address to interact with from the lower drop down box then click "Access".
@ -79,15 +83,15 @@ number of different accounts from the same device.
If you deposit funds to an address derived from your Ledger device,
make sure to access the same address when using SolFlare to be able to access
those funds. If you connect to the incorrect address,
those funds. If you connect to the incorrect address,
simply click Logout and re-connect with the correct address.
## Select a Network
Solana maintains [three distinct networks](../clusters), each of which has
its own purpose in supporting the Solana ecosystem. Mainnet Beta is selected by
its own purpose in supporting the Solana ecosystem. Mainnet Beta is selected by
default on SolFlare, as this is the permanent network where exchanges and other
production apps are deployed. To select a different network, click on the name
production apps are deployed. To select a different network, click on the name
of the currently selected network at the top of the wallet dashboard, either
Mainnet, Testnet or Devnet, then click on the name of the network you wish to be
using.
@ -95,34 +99,38 @@ using.
## Sending and Receiving SOL Tokens
### Receiving
To receive tokens into your wallet, someone must transfer some to your wallet's
address. The address is displayed at the top-left on the screen, and you can
address. The address is displayed at the top-left on the screen, and you can
click the Copy icon to copy the address and provide it to whoever is sending you
tokens. If you hold tokens in a different wallet or on an exchange, you can
withdraw to this address as well. Once the transfer is made, the balance shown
tokens. If you hold tokens in a different wallet or on an exchange, you can
withdraw to this address as well. Once the transfer is made, the balance shown
on SolFlare should update within a few seconds.
### Sending
Once you have some tokens at your wallet address, you can send them to any other
wallet address or an exchange deposit address by clicking "Transfer SOL" in the
upper-right corner. Enter the recipient address and the amount of SOL to
transfer and click "Submit". You will be prompted to confirm the details of the
upper-right corner. Enter the recipient address and the amount of SOL to
transfer and click "Submit". You will be prompted to confirm the details of the
transaction before you [use your key to sign the transaction](#signing-a-transaction)
and then it will be submitted to the network.
## Staking SOL Tokens
SolFlare supports creating and managing stake accounts and delegations. To learn
SolFlare supports creating and managing stake accounts and delegations. To learn
about how staking on Solana works in general, check out our
[Staking Guide](../staking).
### Create a Stake Account
You can use some of the SOL tokens in your wallet to create a new stake account.
From the wallet main page click "Staking" at the top of the page. In the upper-
right, click "Create Account". Enter the amount of SOL you want to use to
fund your new stake account. This amount will be withdrawn from your wallet
and transfered to the stake account. Do not transfer your entire wallet balance
From the wallet main page click "Staking" at the top of the page. In the upper-
right, click "Create Account". Enter the amount of SOL you want to use to
fund your new stake account. This amount will be withdrawn from your wallet
and transfered to the stake account. Do not transfer your entire wallet balance
to a stake account, as the wallet is still used to pay any transaction fees
associated with your stake account. Consider leaving at least 1 SOL in your
associated with your stake account. Consider leaving at least 1 SOL in your
wallet account.
After you submit and [sign the transaction](#signing-a-transaction) you will see
@ -134,8 +142,9 @@ for your new account, which gives your wallet's key the authority to sign
for any transactions related to the new stake account.
### View your Stake Accounts
On the main Wallet dashboard page or on the Staking dashboard page, your stake
accounts will be visible in the "Your Staking Accounts" box. Stake accounts
accounts will be visible in the "Your Staking Accounts" box. Stake accounts
exist at a different address from your wallet.
SolFlare will locate any display all stake accounts on the
@ -147,41 +156,46 @@ can be managed as long as the wallet you logged in with is assigned as the stake
authority.
### Delegate tokens in a Stake Account
Once you have [selected a validator](../staking#select-a-validator), you may
delegate the tokens in one of your stake accounts to them. From the Staking
delegate the tokens in one of your stake accounts to them. From the Staking
dashboard, click "Delegate" at the right side of a displayed stake account.
Select the validator you wish to delegate to from the drop down list and click
Delegate.
To un-delegate your staked tokens (also called deactivating your stake), the
process is similar. On the Staking page, at the right side of a delegated stake
process is similar. On the Staking page, at the right side of a delegated stake
account, click the "Undelegate" button and follow the prompts.
### Split a Stake Account
You may split an existing stake account into two stake accounts. Click on the
You may split an existing stake account into two stake accounts. Click on the
address of a stake account controlled by your wallet, and under the Actions bar,
click "Split". Specify the amount of SOL tokens you want to split. This will be
click "Split". Specify the amount of SOL tokens you want to split. This will be
the amount of tokens in your new stake account and your existing stake account
balance will be reduced by the same amount. Splitting your stake account
balance will be reduced by the same amount. Splitting your stake account
allows you to delegate to multiple different validators with different amounts
of tokens. You may split a stake account as many times as you want, to create
as many stake accounts as you want.
## Signing a Transaction
Any time you submit a transaction such as sending tokens to another wallet or
delegating stake, you need to use your private key to sign the transaction so
it will be accepted by the network.
### Using a Keystore File
If you accessed your wallet using a Keystore file, you will be prompted to enter
your password any time the key is needed to sign a transaction.
### Using a Ledger Nano
If you accessed your wallet with a Ledger Nano, you will be prompted to
confirm the pending transaction details on your device whenever the key is needed
to sign. On the Nano, use the left and right buttons to view and confirm all of the
transaction details. If everything looks correct, keep clicking the right button
until the screen shows "Approve". Click both buttons to approve the transaction.
transaction details. If everything looks correct, keep clicking the right button
until the screen shows "Approve". Click both buttons to approve the transaction.
If something looks incorrect, press the right button once more so the screen shows
"Reject" and press both buttons to reject the transaction. After you approve
"Reject" and press both buttons to reject the transaction. After you approve
or reject a transaction, you will see this reflected on the SolFlare page.

8
docs/src/wallet-guide/web-wallets.md
View File

@ -3,16 +3,18 @@ title: Web Wallets
---
## SolFlare
[SolFlare.com](https://solflare.com/) is a community-created non-custodial
web wallet that was built specifically for Solana. SolFlare supports the creation
web wallet that was built specifically for Solana. SolFlare supports the creation
and management of stake accounts, and gives users the ability to send and receive
any SPL Token.
Check out our [guide for using SolFlare](solflare.md).
## Sollet
[sollet.io](https://www.sollet.io/) is a non-custodial web wallet created by the
[Project Serum](https://projectserum.com/) team. sollet.io can be used to send
[Project Serum](https://projectserum.com/) team. sollet.io can be used to send
and receive SOL and any SPL Token.
## MathWallet
@ -21,4 +23,4 @@ and receive SOL and any SPL Token.
addresses for sending and receiving SOL and SPL Tokens through its
browser extension and web wallet interface.
*Note: The MathWallet iOS and Android app do not yet support SOL and SPL Tokens*
_Note: The MathWallet iOS and Android app do not yet support SOL and SPL Tokens_