diff --git a/docs/advanced/index.md b/docs/advanced/index.md new file mode 100644 index 000000000..c0c86871b --- /dev/null +++ b/docs/advanced/index.md @@ -0,0 +1,5 @@ +--- +metaOnly: true +title: Advanced Concepts +# sidebarSortOrder: 3 +--- diff --git a/docs/developing/lookup-tables.md b/docs/advanced/lookup-tables.md similarity index 91% rename from docs/developing/lookup-tables.md rename to docs/advanced/lookup-tables.md index 9c2a79e59..9382e948c 100644 --- a/docs/developing/lookup-tables.md +++ b/docs/advanced/lookup-tables.md @@ -10,8 +10,8 @@ efficiently load more addresses in a single transaction. Since each transaction on the Solana blockchain requires a listing of every address that is interacted with as part of the transaction, this listing would effectively be capped at 32 addresses per transaction. With the help of -[Address Lookup Tables](./lookup-tables.md), a transaction would now be able to -raise that limit to 256 addresses per transaction. +[Address Lookup Tables](/docs/advanced/lookup-tables.md), a transaction would +now be able to raise that limit to 256 addresses per transaction. ## Compressing on chain addresses @@ -27,7 +27,7 @@ table for use inside any given transaction. To utilize an Address Lookup Table inside a transaction, developers must use v0 transactions that were introduced with the new -[Versioned Transaction format](./versioned-transactions.md). +[Versioned Transaction format](/docs/core/transactions/versions.md). ## How to create an address lookup table @@ -65,7 +65,7 @@ console.log("lookup table address:", lookupTableAddress.toBase58()); > NOTE: Address lookup tables can be **created** with either a `v0` transaction > or a `legacy` transaction. But the Solana runtime can only retrieve and handle > the additional addresses within a lookup table while using -> [v0 Versioned Transactions](./versioned-transactions.md#current-transaction-versions). +> [v0 Versioned Transactions](/docs/core/transactions/versions.md#current-transaction-versions). ## Add addresses to a lookup table @@ -141,9 +141,9 @@ chain (via extending the lookup table), you can create a `v0` transaction to utilize the on chain lookup capabilities. Just like older `legacy` transactions, you can create all the -[instructions](./../terminology.md#instruction) your transaction will execute on -chain. You can then provide an array of these instructions to the -[Message](./../terminology.md#message) used in the `v0 transaction. +[instructions](/docs/terminology.md#instruction) your transaction will execute +on chain. You can then provide an array of these instructions to the +[Message](/docs/terminology.md#message) used in the `v0 transaction. > NOTE: The instructions used inside a `v0` transaction can be constructed using > the same methods and functions used to create the instructions in the past. @@ -183,6 +183,7 @@ console.log( ## More Resources -- Read the [proposal](./../proposals/versioned-transactions.md) for Address - Lookup Tables and Versioned transactions +- Read the + [proposal](https://docs.solanalabs.com/proposals/versioned-transactions) for + Address Lookup Tables and Versioned transactions - [Example Rust program using Address Lookup Tables](https://github.com/TeamRaccoons/address-lookup-table-multi-swap) diff --git a/docs/learn/state-compression.md b/docs/advanced/state-compression.md similarity index 92% rename from docs/learn/state-compression.md rename to docs/advanced/state-compression.md index 5bb865e9e..b234b3f7f 100644 --- a/docs/learn/state-compression.md +++ b/docs/advanced/state-compression.md @@ -6,15 +6,15 @@ description: accounts.' --- -On Solana, [State Compression](./state-compression.md) is the method of creating -a "fingerprint" (or hash) of off-chain data and storing this fingerprint -on-chain for secure verification. Effectively using the security of the Solana -ledger to securely validate off-chain data, verifying it has not been tampered -with. +On Solana, [State Compression](/docs/advanced/state-compression.md) is the +method of creating a "fingerprint" (or hash) of off-chain data and storing this +fingerprint on-chain for secure verification. Effectively using the security of +the Solana ledger to securely validate off-chain data, verifying it has not been +tampered with. This method of "compression" allows Solana programs and dApps to use cheap -blockchain [ledger](./../terminology.md#ledger) space, instead of the more -expensive [account](./../terminology.md#account) space, to securely store data. +blockchain [ledger](/docs/terminology.md#ledger) space, instead of the more +expensive [account](/docs/terminology.md#account) space, to securely store data. This is accomplished by using a special binary tree structure, known as a [concurrent merkle tree](#what-is-a-concurrent-merkle-tree), to create a hash of @@ -82,19 +82,15 @@ and effectively invalidates the previous root hash and previous proof. Therefore, each change to these _traditional merkle trees_ are required to be performed in series. -:::info - -This process of changing leaf data, and computing a new root hash can be a -**very common** thing when using merkle trees! While it is one of the design -points of the tree, it can result in one of the most notable drawbacks: rapid -changes. - -::: +> This process of changing leaf data, and computing a new root hash can be a +> **very common** thing when using merkle trees! While it is one of the design +> points of the tree, it can result in one of the most notable drawbacks: rapid +> changes. ### What is a Concurrent merkle tree? In high throughput applications, like within the -[Solana runtime](/src/validator/runtime.md), requests to change an on-chain +[Solana runtime](/docs/core/runtime.md), requests to change an on-chain _traditional merkle tree_ could be received by validators in relatively rapid succession (e.g. within the same slot). Each leaf data change would still be required to performed in series. Resulting in each subsequent request for change @@ -136,7 +132,7 @@ Therefore, the `maxDepth` of a tree is used to determine the maximum number of nodes (aka pieces of data or `leafs`) to store within the tree using a simple calculation: -``` +```text nodes_count = 2 ^ maxDepth ``` @@ -149,7 +145,7 @@ above, you can determine the lowest `maxDepth` to store your data. If you wanted to create a tree to store 100 compressed nfts, we will need a minimum of "100 leafs" or "100 nodes". -``` +```text // maxDepth=6 -> 64 nodes 2^6 = 64 @@ -164,7 +160,7 @@ We must use a `maxDepth` of `7` to ensure we can store all of our data. If you wanted to create a tree to store 15000 compressed nfts, we will need a minimum of "15000 leafs" or "15000 nodes". -``` +```text // maxDepth=13 -> 8192 nodes 2^13 = 8192 @@ -257,7 +253,7 @@ used to calculate the on-chain storage (in bytes) required for a tree to exist on chain. Once the required space (in bytes) has been calculated, and using the -[`getMinimumBalanceForRentExemption`](/api/http#getminimumbalanceforrentexemption) +[`getMinimumBalanceForRentExemption`](/docs/rpc/http/getminimumbalanceforrentexemption) RPC method, request the cost (in lamports) to allocate this amount of bytes on-chain. @@ -325,9 +321,6 @@ Compressed NFTs are one of the most popular use cases for State Compression on Solana. With compression, a one million NFT collection could be minted for `~50 SOL`, vice `~12,000 SOL` for its uncompressed equivalent collection. -:::info Developer Guide - -Read our developer guide for -[minting and transferring compressed NFTs](./../developing/guides/compressed-nfts). - -::: +If you are interested in creating compressed NFTs yourself, read our developer +guide for +[minting and transferring compressed NFTs](/content/guides/javascript/compressed-nfts.md). diff --git a/docs/clients/index.md b/docs/clients/index.md new file mode 100644 index 000000000..e24dd3aa1 --- /dev/null +++ b/docs/clients/index.md @@ -0,0 +1,5 @@ +--- +metaOnly: true +title: Solana Clients +# sidebarSortOrder: 3 +--- diff --git a/docs/developing/clients/javascript-reference.md b/docs/clients/javascript-reference.md similarity index 94% rename from docs/developing/clients/javascript-reference.md rename to docs/clients/javascript-reference.md index ce9ff6c6a..c07b49dea 100644 --- a/docs/developing/clients/javascript-reference.md +++ b/docs/clients/javascript-reference.md @@ -1,11 +1,11 @@ --- -title: Web3 API Reference +title: Web3.js API Examples --- ## Web3 API Reference Guide The `@solana/web3.js` library is a package that has coverage over the -[Solana JSON RPC API](/api). +[Solana JSON RPC API](/docs/rpc). You can find the full documentation for the `@solana/web3.js` library [here](https://solana-labs.github.io/solana-web3.js/). @@ -16,8 +16,8 @@ You can find the full documentation for the `@solana/web3.js` library [Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/Connection.html) -Connection is used to interact with the [Solana JSON RPC](/api). You can use -Connection to confirm transactions, get account info, and more. +Connection is used to interact with the [Solana JSON RPC](/docs/rpc). You can +use Connection to confirm transactions, get account info, and more. You create a connection by defining the JSON RPC cluster endpoint and the desired commitment. Once this is complete, you can use this connection object to @@ -64,7 +64,7 @@ for the full list. ### Transaction -[SourceDocumentation](https://solana-labs.github.io/solana-web3.js/classes/Transaction.html) +[Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/Transaction.html) A transaction is used to interact with programs on the Solana blockchain. These transactions are constructed with TransactionInstructions, containing all the @@ -257,7 +257,7 @@ console.log(`Valid Program Address: ${validProgramAddress}`); ### SystemProgram -[SourceDocumentation](https://solana-labs.github.io/solana-web3.js/classes/SystemProgram.html) +[Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/SystemProgram.html) The SystemProgram grants the ability to create accounts, allocate account data, assign an account to programs, work with nonce accounts, and transfer lamports. @@ -422,8 +422,8 @@ await web3.sendAndConfirmTransaction(connection, transaction, [fromPublicKey]); Message is used as another way to construct transactions. You can construct a message using the accounts, header, instructions, and recentBlockhash that are a -part of a transaction. A [Transaction](javascript-api.md#Transaction) is a -Message plus the list of required signatures required to execute the +part of a transaction. A [Transaction](/docs/clients/javascript.md#Transaction) +is a Message plus the list of required signatures required to execute the transaction. #### Example Usage @@ -484,7 +484,7 @@ await web3.sendAndConfirmTransaction(connection, transaction, [fromPublicKey]); ### Struct -[SourceDocumentation](https://solana-labs.github.io/solana-web3.js/classes/Struct.html) +[Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/Struct.html) The struct class is used to create Rust compatible structs in javascript. This class is only compatible with Borsh encoded Rust structs. @@ -519,8 +519,8 @@ export class Fee extends Struct { The Enum class is used to represent a Rust compatible Enum in javascript. The enum will just be a string representation if logged but can be properly encoded/decoded when used in conjunction with -[Struct](javascript-api.md#Struct). This class is only compatible with Borsh -encoded Rust enumerations. +[Struct](/docs/clients/javascript.md#Struct). This class is only compatible with +Borsh encoded Rust enumerations. #### Example Usage @@ -634,7 +634,7 @@ offline with the nonce in place of the `recentBlockhash`. ### VoteAccount -[SourceDocumentation](https://solana-labs.github.io/solana-web3.js/classes/VoteAccount.html) +[Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/VoteAccount.html) Vote account is an object that grants the capability of decoding vote accounts from the native vote account program on the network. @@ -708,7 +708,7 @@ VoteAccount { ### StakeProgram -[SourceDocumentation](https://solana-labs.github.io/solana-web3.js/classes/StakeProgram.html) +[Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/StakeProgram.html) The StakeProgram facilitates staking SOL and delegating them to any validators on the network. You can use StakeProgram to create a stake account, stake some @@ -815,17 +815,17 @@ within Solana. You can designate a `staker` and `withdrawer` separately, allowing for a different account to withdraw other than the staker. You can find more usage of the `Authorized` object under -[`StakeProgram`](javascript-api.md#StakeProgram) +[`StakeProgram`](/docs/clients/javascript.md#StakeProgram) ### Lockup [Source Documentation](https://solana-labs.github.io/solana-web3.js/classes/Lockup.html) Lockup is used in conjunction with the -[StakeProgram](javascript-api.md#StakeProgram) to create an account. The Lockup -is used to determine how long the stake will be locked, or unable to be -retrieved. If the Lockup is set to 0 for both epoch and the Unix timestamp, the -lockup will be disabled for the stake account. +[StakeProgram](/docs/clients/javascript.md#StakeProgram) to create an account. +The Lockup is used to determine how long the stake will be locked, or unable to +be retrieved. If the Lockup is set to 0 for both epoch and the Unix timestamp, +the lockup will be disabled for the stake account. #### Example Usage @@ -855,4 +855,4 @@ The above code creates a `createStakeAccountInstruction` to be used when creating an account with the `StakeProgram`. The Lockup is set to 0 for both the epoch and Unix timestamp, disabling lockup for the account. -See [StakeProgram](javascript-api.md#StakeProgram) for more. +See [StakeProgram](/docs/clients/javascript.md#StakeProgram) for more. diff --git a/docs/developing/clients/javascript-api.md b/docs/clients/javascript.md similarity index 96% rename from docs/developing/clients/javascript-api.md rename to docs/clients/javascript.md index 59e6d1a5e..7a27bd05b 100644 --- a/docs/developing/clients/javascript-api.md +++ b/docs/clients/javascript.md @@ -1,11 +1,13 @@ --- -title: Web3 JavaScript API +sidebarLabel: JavaScript / TypeScript +title: JavaScript Client for Solana +sidebarSortOrder: 2 --- ## What is Solana-Web3.js? The Solana-Web3.js library aims to provide complete coverage of Solana. The -library was built on top of the [Solana JSON RPC API](/api). +library was built on top of the [Solana JSON RPC API](/docs/rpc). You can find the full documentation for the `@solana/web3.js` library [here](https://solana-labs.github.io/solana-web3.js/). @@ -19,7 +21,7 @@ You can find the full documentation for the `@solana/web3.js` library | Transaction | One or more instructions signed by the client using one or more Keypairs and executed atomically with only two possible outcomes: success or failure. | For the full list of terms, see -[Solana terminology](../../terminology#cross-program-invocation) +[Solana terminology](/docs/terminology.md#cross-program-invocation-cpi) ## Getting Started @@ -28,13 +30,13 @@ For the full list of terms, see #### yarn ```bash -$ yarn add @solana/web3.js +yarn add @solana/web3.js ``` #### npm ```bash -$ npm install --save @solana/web3.js +npm install --save @solana/web3.js ``` #### Bundle @@ -125,8 +127,8 @@ order that instructions exist in a transaction determines the order they are executed. A transaction in Solana-Web3.js is created using the -[`Transaction`](javascript-api.md#Transaction) object and adding desired -messages, addresses, or instructions. +[`Transaction`](/docs/clients/javascript.md#Transaction) object and adding +desired messages, addresses, or instructions. Take the example of a transfer transaction: diff --git a/docs/developing/clients/rust-api.md b/docs/clients/rust.md similarity index 93% rename from docs/developing/clients/rust-api.md rename to docs/clients/rust.md index 68ab93773..17fb6dfe6 100644 --- a/docs/developing/clients/rust-api.md +++ b/docs/clients/rust.md @@ -1,5 +1,7 @@ --- -title: Rust API +sidebarLabel: Rust +title: Rust Client for Solana +sidebarSortOrder: 1 --- Solana's Rust crates are [published to crates.io][crates.io] and can be found @@ -19,7 +21,7 @@ Some important crates: that do not run on-chain will import this. - [`solana-client`] — For interacting with a Solana node via the - [JSON RPC API](/api). + [JSON RPC API](/docs/rpc). - [`solana-cli-config`] — Loading and saving the Solana CLI configuration file. diff --git a/docs/clusters.md b/docs/clusters.md deleted file mode 100644 index df0f774ff..000000000 --- a/docs/clusters.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Solana Clusters ---- - -Solana maintains several different clusters with different purposes. - -Before you begin make sure you have first -[installed the Solana command line tools](cli/install-solana-cli-tools.md) - -Explorers: - -- [http://explorer.solana.com/](https://explorer.solana.com/). -- [http://solanabeach.io/](http://solanabeach.io/). - -## Devnet - -- Devnet serves as a playground for anyone who wants to take Solana for a test - drive, as a user, token holder, app developer, or validator. -- Application developers should target Devnet. -- Potential validators should first target Devnet. -- Key differences between Devnet and Mainnet Beta: - - Devnet tokens are **not real** - - Devnet includes a token faucet for airdrops for application testing - - Devnet may be subject to ledger resets - - Devnet typically runs the same software release branch version as Mainnet - Beta, but may run a newer minor release 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://api.devnet.solana.com` - -##### Example `solana` command-line configuration - -```bash -solana config set --url https://api.devnet.solana.com -``` - -##### Example `solana-validator` command-line - -```bash -$ solana-validator \ - --identity validator-keypair.json \ - --vote-account vote-account-keypair.json \ - --known-validator dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92 \ - --known-validator dv2eQHeP4RFrJZ6UeiZWoc3XTtmtZCUKxxCApCDcRNV \ - --known-validator dv4ACNkpYPcE3aKmYDqZm9G5EB3J4MRoeE7WNDRBVJB \ - --known-validator dv3qDFk1DTF36Z62bNvrCXe9sKATA6xvVy6A798xxAS \ - --only-known-rpc \ - --ledger ledger \ - --rpc-port 8899 \ - --dynamic-port-range 8000-8020 \ - --entrypoint entrypoint.devnet.solana.com:8001 \ - --entrypoint entrypoint2.devnet.solana.com:8001 \ - --entrypoint entrypoint3.devnet.solana.com:8001 \ - --entrypoint entrypoint4.devnet.solana.com:8001 \ - --entrypoint entrypoint5.devnet.solana.com:8001 \ - --expected-genesis-hash EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG \ - --wal-recovery-mode skip_any_corrupted_record \ - --limit-ledger-size -``` - -The -[`--known-validator`s](running-validator/validator-start.md#known-validators) -are operated by Solana Labs - -## Testnet - -- Testnet is where the Solana core contributors stress test recent release - features on a live cluster, particularly focused on network performance, - stability and validator behavior. -- Testnet tokens are **not real** -- Testnet may be subject to ledger resets. -- Testnet includes a token faucet for airdrops for application testing -- Testnet typically runs a newer software release branch than both Devnet and - 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://api.testnet.solana.com` - -##### Example `solana` command-line configuration - -```bash -solana config set --url https://api.testnet.solana.com -``` - -##### Example `solana-validator` command-line - -```bash -$ solana-validator \ - --identity validator-keypair.json \ - --vote-account vote-account-keypair.json \ - --known-validator 5D1fNXzvv5NjV1ysLjirC4WY92RNsVH18vjmcszZd8on \ - --known-validator dDzy5SR3AXdYWVqbDEkVFdvSPCtS9ihF5kJkHCtXoFs \ - --known-validator Ft5fbkqNa76vnsjYNwjDZUXoTWpP7VYm3mtsaQckQADN \ - --known-validator eoKpUABi59aT4rR9HGS3LcMecfut9x7zJyodWWP43YQ \ - --known-validator 9QxCLckBiJc783jnMvXZubK4wH86Eqqvashtrwvcsgkv \ - --only-known-rpc \ - --ledger ledger \ - --rpc-port 8899 \ - --dynamic-port-range 8000-8020 \ - --entrypoint entrypoint.testnet.solana.com:8001 \ - --entrypoint entrypoint2.testnet.solana.com:8001 \ - --entrypoint entrypoint3.testnet.solana.com:8001 \ - --expected-genesis-hash 4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY \ - --wal-recovery-mode skip_any_corrupted_record \ - --limit-ledger-size -``` - -The identities of the -[`--known-validator`s](running-validator/validator-start.md#known-validators) -are: - -- `5D1fNXzvv5NjV1ysLjirC4WY92RNsVH18vjmcszZd8on` - Solana Labs -- `dDzy5SR3AXdYWVqbDEkVFdvSPCtS9ihF5kJkHCtXoFs` - MonkeDAO -- `Ft5fbkqNa76vnsjYNwjDZUXoTWpP7VYm3mtsaQckQADN` - Certus One -- `eoKpUABi59aT4rR9HGS3LcMecfut9x7zJyodWWP43YQ` - SerGo -- `9QxCLckBiJc783jnMvXZubK4wH86Eqqvashtrwvcsgkv` - Algo|Stake - -## Mainnet Beta - -A permissionless, persistent cluster for Solana users, builders, validators and -token holders. - -- Tokens that are issued on Mainnet Beta are **real** SOL -- 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 - -```bash -solana config set --url https://api.mainnet-beta.solana.com -``` - -##### Example `solana-validator` command-line - -```bash -$ solana-validator \ - --identity ~/validator-keypair.json \ - --vote-account ~/vote-account-keypair.json \ - --known-validator 7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2 \ - --known-validator GdnSyH3YtwcxFvQrVVJMm1JhTS4QVX7MFsX56uJLUfiZ \ - --known-validator DE1bawNcRJB9rVm3buyMVfr8mBEoyyu73NBovf2oXJsJ \ - --known-validator CakcnaRDHka2gXyfbEd2d3xsvkJkqsLw2akB3zsN1D2S \ - --only-known-rpc \ - --ledger ledger \ - --rpc-port 8899 \ - --private-rpc \ - --dynamic-port-range 8000-8020 \ - --entrypoint entrypoint.mainnet-beta.solana.com:8001 \ - --entrypoint entrypoint2.mainnet-beta.solana.com:8001 \ - --entrypoint entrypoint3.mainnet-beta.solana.com:8001 \ - --entrypoint entrypoint4.mainnet-beta.solana.com:8001 \ - --entrypoint entrypoint5.mainnet-beta.solana.com:8001 \ - --expected-genesis-hash 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d \ - --wal-recovery-mode skip_any_corrupted_record \ - --limit-ledger-size -``` - -All four -[`--known-validator`s](running-validator/validator-start.md#known-validators) -are operated by Solana Labs diff --git a/docs/clusters/rpc-endpoints.md b/docs/clusters/rpc-endpoints.md deleted file mode 100644 index a2bd93d9d..000000000 --- a/docs/clusters/rpc-endpoints.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Solana Cluster RPC Endpoints ---- - -Solana maintains dedicated api nodes to fulfill [JSON-RPC](/api) requests for -each public cluster, and third parties may as well. Here are the public RPC -endpoints currently available and recommended for each public cluster: - -## Devnet - -#### Endpoint - -- `https://api.devnet.solana.com` - single Solana-hosted api node; rate-limited - -#### Rate Limits - -- Maximum number of requests per 10 seconds per IP: 100 -- Maximum number of requests per 10 seconds per IP for a single RPC: 40 -- Maximum concurrent connections per IP: 40 -- Maximum connection rate per 10 seconds per IP: 40 -- Maximum amount of data per 30 second: 100 MB - -## Testnet - -#### Endpoint - -- `https://api.testnet.solana.com` - single Solana-hosted api node; rate-limited - -#### Rate Limits - -- Maximum number of requests per 10 seconds per IP: 100 -- Maximum number of requests per 10 seconds per IP for a single RPC: 40 -- Maximum concurrent connections per IP: 40 -- Maximum connection rate per 10 seconds per IP: 40 -- Maximum amount of data per 30 second: 100 MB - -## Mainnet Beta - -#### Endpoints\* - -- `https://api.mainnet-beta.solana.com` - Solana-hosted api node cluster, backed - by a load balancer; rate-limited - -#### Rate Limits - -- Maximum number of requests per 10 seconds per IP: 100 -- Maximum number of requests per 10 seconds per IP for a single RPC: 40 -- Maximum concurrent connections per IP: 40 -- Maximum connection rate per 10 seconds per IP: 40 -- Maximum amount of data per 30 second: 100 MB - -\*The public RPC endpoints are not intended for production applications. Please -use dedicated/private RPC servers when you launch your application, drop NFTs, -etc. The public services are subject to abuse and rate limits may change without -prior notice. Likewise, high-traffic websites may be blocked without prior -notice. - -## Common HTTP Error Codes - -- 403 -- Your IP address or website has been blocked. It is time to run your own - RPC server(s) or find a private service. -- 429 -- Your IP address is exceeding the rate limits. Slow down! Use the - [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) - HTTP response header to determine how long to wait before making another - request. diff --git a/docs/developing/programming-model/accounts.md b/docs/core/accounts.md similarity index 78% rename from docs/developing/programming-model/accounts.md rename to docs/core/accounts.md index d5aa73a6f..f8fb1263b 100644 --- a/docs/developing/programming-model/accounts.md +++ b/docs/core/accounts.md @@ -1,5 +1,7 @@ --- -title: "Accounts" +sidebarLabel: Accounts +sidebarSortOrder: 1 +title: Accounts and Storing State --- ## Storing State between Transactions @@ -22,32 +24,33 @@ uses an _address_ to look up an account. The address is a 256-bit public key. ## Signers -Transactions include one or more digital [signatures](terminology.md#signature) -each corresponding to an account address referenced by the transaction. Each of -these addresses must be the public key of an ed25519 keypair, and the signature -signifies that the holder of the matching private key signed, and thus, -"authorized" the transaction. In this case, the account is referred to as a -_signer_. Whether an account is a signer or not is communicated to the program -as part of the account's metadata. Programs can then use that information to -make authority decisions. +Transactions include one or more digital +[signatures](/docs/terminology.md#signature) each corresponding to an account +address referenced by the transaction. Each of these addresses must be the +public key of an ed25519 keypair, and the signature signifies that the holder of +the matching private key signed, and thus, "authorized" the transaction. In this +case, the account is referred to as a _signer_. Whether an account is a signer +or not is communicated to the program as part of the account's metadata. +Programs can then use that information to make authority decisions. ## Read-only -Transactions can [indicate](transactions.md#message-header-format) that some of -the accounts it references be treated as _read-only accounts_ in order to enable -parallel account processing between transactions. The runtime permits read-only -accounts to be read concurrently by multiple programs. If a program attempts to -modify a read-only account, the transaction is rejected by the runtime. +Transactions can [indicate](/docs/core/transactions.md#message-header-format) +that some of the accounts it references be treated as _read-only accounts_ in +order to enable parallel account processing between transactions. The runtime +permits read-only accounts to be read concurrently by multiple programs. If a +program attempts to modify a read-only account, the transaction is rejected by +the runtime. ## Executable 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 in 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. When a program is deployed to the execution engine (SBF -deployment), the loader determines that the bytecode in the account's data is -valid. If so, the loader permanently marks the program account as executable. +instruction's [program id](/docs/core/transactions.md#program-id). Accounts are +marked as executable during a successful program deployment process by the +loader that owns the account. When a program is deployed to the execution engine +(SBF deployment), the loader determines that the bytecode in the account's data +is valid. If so, the loader permanently marks the program account as executable. If a program is marked as final (non-upgradeable), the runtime enforces that the account's data (the program) is immutable. Through the upgradeable loader, it is @@ -65,7 +68,7 @@ and per instruction. An account address can be any arbitrary 256 bit value, and there are mechanisms for advanced users to create derived addresses (`SystemProgram::CreateAccountWithSeed`, -[`Pubkey::CreateProgramAddress`](calling-between-programs.md#program-derived-addresses)). +[`Pubkey::CreateProgramAddress`](/docs/core/cpi.md#program-derived-addresses)). Accounts that have never been created via the system program can also be passed to programs. When an instruction references an account that hasn't been @@ -147,10 +150,10 @@ that would reduce the balance to below the minimum amount will fail. Program executable accounts are required by the runtime to be rent-exempt to avoid being purged. -:::info Use the -[`getMinimumBalanceForRentExemption`](../../api/http#getminimumbalanceforrentexemption) -RPC endpoint to calculate the minimum balance for a particular account size. The -following calculation is illustrative only. ::: +> Note: Use the +> [`getMinimumBalanceForRentExemption`](/docs/rpc/http/getMinimumBalanceForRentExemption.mdx) +> RPC endpoint to calculate the minimum balance for a particular account size. +> The following calculation is illustrative only. For example, a program executable with the size of 15,000 bytes requires a balance of 105,290,880 lamports (=~ 0.105 SOL) to be rent-exempt: @@ -160,7 +163,7 @@ balance of 105,290,880 lamports (=~ 0.105 SOL) to be rent-exempt: ``` Rent can also be estimated via the -[`solana rent` CLI subcommand](cli/usage.md#solana-rent) +[`solana rent` CLI subcommand](https://docs.solanalabs.com/cli/usage#solana-rent) ```text $ solana rent 15000 diff --git a/docs/core/clusters.md b/docs/core/clusters.md new file mode 100644 index 000000000..b764f7340 --- /dev/null +++ b/docs/core/clusters.md @@ -0,0 +1,148 @@ +--- +sidebarLabel: Clusters & Endpoints +title: Clusters and Public RPC Endpoints +--- + +The Solana blockchain has several different groups of validators, known as +[Clusters](/docs/core/clusters.md). Each serving different purposes within the +overall ecosystem and containing dedicated api nodes to fulfill +[JSON-RPC](/docs/rpc) requests for their respective Cluster. + +The individual nodes within a Cluster are owned and operated by third parties, +with a public endpoint available for each. + +## Solana public RPC endpoints + +The Solana Labs organization operates a public RPC endpoint for each Cluster. +Each of these public endpoints are subject to rate limits, but are available for +users and developers to interact with the Solana blockchain. + +> > Note: Public endpoint rate limits are subject to change. The specific rate +> > limits listed on this document are not guaranteed to be the most up-to-date. + +### Using explorers with different Clusters + +Many of the popular Solana blockchain explorers support selecting any of the +Clusters, often allowing advanced users to add a custom/private RPC endpoint as +well. + +An example of some of these Solana blockchain explorers include: + +- [http://explorer.solana.com/](https://explorer.solana.com/). +- [http://solana.fm/](https://solana.fm/). +- [http://solscan.io/](https://solscan.io/). +- [http://solanabeach.io/](http://solanabeach.io/). +- [http://validators.app/](http://validators.app/). + +## Devnet + +Devnet serves as a playground for anyone who wants to take Solana for a test +drive, as a user, token holder, app developer, or validator. + +- Application developers should target Devnet. +- Potential validators should first target Devnet. +- Key differences between Devnet and Mainnet Beta: + - Devnet tokens are **not real** + - Devnet includes a token faucet for airdrops for application testing + - Devnet may be subject to ledger resets + - Devnet typically runs the same software release branch version as Mainnet + Beta, but may run a newer minor release version than Mainnet Beta. +- Gossip entrypoint for Devnet: `entrypoint.devnet.solana.com:8001` + +### Devnet endpoint + +- `https://api.devnet.solana.com` - single Solana Labs hosted api node; + rate-limited + +#### Example `solana` command-line configuration + +To connect to the `devnet` Cluster using the Solana CLI: + +```bash +solana config set --url https://api.devnet.solana.com +``` + +### Devnet rate limits + +- Maximum number of requests per 10 seconds per IP: 100 +- Maximum number of requests per 10 seconds per IP for a single RPC: 40 +- Maximum concurrent connections per IP: 40 +- Maximum connection rate per 10 seconds per IP: 40 +- Maximum amount of data per 30 second: 100 MB + +## Testnet + +Testnet is where the Solana core contributors stress test recent release +features on a live cluster, particularly focused on network performance, +stability and validator behavior. + +- Testnet tokens are **not real** +- Testnet may be subject to ledger resets. +- Testnet includes a token faucet for airdrops for application testing +- Testnet typically runs a newer software release branch than both Devnet and + Mainnet Beta +- Gossip entrypoint for Testnet: `entrypoint.testnet.solana.com:8001` + +### Testnet endpoint + +- `https://api.testnet.solana.com` - single Solana Labs api node; rate-limited + +#### Example `solana` command-line configuration + +To connect to the `testnet` Cluster using the Solana CLI: + +```bash +solana config set --url https://api.testnet.solana.com +``` + +### Testnet rate limits + +- Maximum number of requests per 10 seconds per IP: 100 +- Maximum number of requests per 10 seconds per IP for a single RPC: 40 +- Maximum concurrent connections per IP: 40 +- Maximum connection rate per 10 seconds per IP: 40 +- Maximum amount of data per 30 second: 100 MB + +## Mainnet beta + +A permissionless, persistent cluster for Solana users, builders, validators and +token holders. + +- Tokens that are issued on Mainnet Beta are **real** SOL +- Gossip entrypoint for Mainnet Beta: `entrypoint.mainnet-beta.solana.com:8001` + +### Mainnet beta endpoint + +- `https://api.mainnet-beta.solana.com` - Solana Labs hosted api node cluster, + backed by a load balancer; rate-limited + +#### Example `solana` command-line configuration + +To connect to the `mainnet-beta` Cluster using the Solana CLI: + +```bash +solana config set --url https://api.mainnet-beta.solana.com +``` + +### Mainnet beta rate limits + +- Maximum number of requests per 10 seconds per IP: 100 +- Maximum number of requests per 10 seconds per IP for a single RPC: 40 +- Maximum concurrent connections per IP: 40 +- Maximum connection rate per 10 seconds per IP: 40 +- Maximum amount of data per 30 second: 100 MB + +> The public RPC endpoints are not intended for production applications. Please +> use dedicated/private RPC servers when you launch your application, drop NFTs, +> etc. The public services are subject to abuse and rate limits may change +> without prior notice. Likewise, high-traffic websites may be blocked without +> prior notice. + +## Common HTTP Error Codes + +- 403 -- Your IP address or website has been blocked. It is time to run your own + RPC server(s) or find a private service. +- 429 -- Your IP address is exceeding the rate limits. Slow down! Use the + [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) + HTTP response header to determine how long to wait before making another + request. diff --git a/docs/developing/programming-model/calling-between-programs.md b/docs/core/cpi.md similarity index 92% rename from docs/developing/programming-model/calling-between-programs.md rename to docs/core/cpi.md index 0d6ce4290..d403eb102 100644 --- a/docs/developing/programming-model/calling-between-programs.md +++ b/docs/core/cpi.md @@ -1,18 +1,19 @@ --- -title: Calling Between Programs +sidebarLabel: CPI +# sidebarSortOrder: 5 +title: Cross-program Invocation (aka CPI) --- -## 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 -invoked program finishes processing the instruction. +"[cross-program invocation](/docs/core/cpi.md)", or `cpi` for short. 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, each owned by separate on-chain programs: -```rust,ignore +```rust let message = Message::new(vec![ token_instruction::pay(&alice_pubkey), acme_instruction::launch_missiles(&bob_pubkey), @@ -23,7 +24,7 @@ client.send_and_confirm_message(&[&alice_keypair, &bob_keypair], &message); A client may instead allow the `acme` program to conveniently invoke `token` instructions on the client's behalf: -```rust,ignore +```rust let message = Message::new(vec![ acme_instruction::pay_and_launch_missiles(&alice_pubkey, &bob_pubkey), ]); @@ -35,7 +36,7 @@ Given two on-chain programs, `token` and `acme`, each implementing instructions call to a function defined in the `token` module by issuing a cross-program invocation: -```rust,ignore +```rust mod acme { use token_instruction; @@ -101,7 +102,7 @@ signed in the original transaction by using To sign an account with program derived addresses, a program may `invoke_signed()`. -```rust,ignore +```rust invoke_signed( &instruction, accounts, @@ -126,7 +127,7 @@ point that it gets called back. ## Program Derived Addresses Program derived addresses allow programmatically generated signatures to be used -when [calling between programs](#cross-program-invocations). +when [calling between programs](/docs/core/cpi.md). Using a program derived address, a program may be given the authority over an account and later transfer that authority to another. This is possible because @@ -158,7 +159,7 @@ Program derived address: 2. Allow programs to programmatically sign for program addresses that are present in instructions invoked via - [Cross-Program Invocations](#cross-program-invocations). + [Cross-Program Invocations](/docs/core/cpi.md). Given the two conditions, users can securely transfer or assign the authority of on-chain assets to program addresses, and the program can then assign that @@ -188,7 +189,7 @@ implemented with `Pubkey::create_with_seed`. For reference, that implementation is as follows: -```rust,ignore +```rust pub fn create_with_seed( base: &Pubkey, seed: &str, @@ -209,7 +210,7 @@ These seeds can symbolically identify how the addresses are used. From `Pubkey`:: -```rust,ignore +```rust /// Generate a derived program address /// * seeds, symbolic keywords used to derive the key /// * program_id, program that the address is derived for @@ -255,7 +256,7 @@ address. In this example, we assume that `create_program_address(&[&["escrow"]], &escrow_program_id)` generates a valid program address that is off the curve. -```rust,ignore +```rust // deterministically derive the escrow key let escrow_pubkey = create_program_address(&[&["escrow"]], &escrow_program_id); @@ -272,7 +273,7 @@ Programs can use the same function to generate the same address. In the function below the program issues a `token_instruction::transfer` from a program address as if it had the private key to sign the transaction. -```rust,ignore +```rust fn transfer_one_token_from_escrow( program_id: &Pubkey, accounts: &[AccountInfo], @@ -302,7 +303,7 @@ To generate a valid program address using `"escrow2"` as a seed, use `find_program_address`, iterating through possible bump seeds until a valid combination is found. The preceding example becomes: -```rust,ignore +```rust // find the escrow key and valid bump seed let (escrow_pubkey2, escrow_bump_seed) = find_program_address(&[&["escrow2"]], &escrow_program_id); @@ -317,7 +318,7 @@ client.send_and_confirm_message(&[&alice_keypair], &message); Within the program, this becomes: -```rust,ignore +```rust fn transfer_one_token_from_escrow2( program_id: &Pubkey, accounts: &[AccountInfo], @@ -338,9 +339,9 @@ fn transfer_one_token_from_escrow2( Since `find_program_address` requires iterating over a number of calls to `create_program_address`, it may use more -[compute budget](developing/programming-model/runtime.md#compute-budget) when -used on-chain. To reduce the compute cost, use `find_program_address` off-chain -and pass the resulting bump seed to the program. +[compute budget](/docs/core/runtime.md#compute-budget) when used on-chain. To +reduce the compute cost, use `find_program_address` off-chain and pass the +resulting bump seed to the program. ### Instructions that require signers @@ -354,8 +355,6 @@ result against the addresses supplied in the instruction. ## Examples -Refer to -[Developing with Rust](developing/on-chain-programs/../../../on-chain-programs/developing-rust.md#examples) -and -[Developing with C](developing/on-chain-programs/../../../on-chain-programs/developing-c.md#examples) -for examples of how to use cross-program invocation. +Refer to [Developing with Rust](/docs/programs/lang-rust.md#examples) and +[Developing with C](/docs/programs/lang-c.md#examples) for examples of how to +use cross-program invocation. diff --git a/docs/core/index.md b/docs/core/index.md new file mode 100644 index 000000000..519926a25 --- /dev/null +++ b/docs/core/index.md @@ -0,0 +1,5 @@ +--- +metaOnly: true +title: Core Concepts +sidebarSortOrder: 2 +--- diff --git a/docs/developing/intro/programs.md b/docs/core/programs.md similarity index 79% rename from docs/developing/intro/programs.md rename to docs/core/programs.md index 886723a2d..a31c044c7 100644 --- a/docs/developing/intro/programs.md +++ b/docs/core/programs.md @@ -1,4 +1,6 @@ --- +sidebarLabel: Programs +sidebarSortOrder: 2 title: What are Solana Programs? description: "A Solana Program, aka smart contract, is the executable code that interprets @@ -20,8 +22,8 @@ transactions speeds of the blockchain. ## Key points -- Programs are essentially special type of - [Accounts](../programming-model/accounts.md) that is marked as "_executable_" +- Programs are essentially special type of [Accounts](/docs/core/accounts.md) + that is marked as "_executable_" - Programs can own other Accounts - Programs can only _change the data_ or _debit_ accounts they own - Any program can _read_ or _credit_ another account @@ -58,22 +60,23 @@ Solana blockchain. Similar to other "on chain" programs in Solana, native programs can be called by any other program/user. However, they can only be upgraded as part of the core blockchain and cluster updates. These native program upgrades are controlled via -the releases to the [different clusters](../../cluster/overview.md). +the releases to the [different clusters](/docs/core/clusters.md). #### Examples of native programs include: -- [System Program](../runtime-facilities/programs.md#system-program): Create new - accounts, transfer tokens, and more -- [BPF Loader Program](../runtime-facilities/programs.md#bpf-loader): Deploys, - upgrades, and executes programs on chain -- [Vote program](../runtime-facilities/programs.md#vote-program): Create and - manage accounts that track validator voting state and rewards. +- [System Program](https://docs.solanalabs.com/runtime/programs#system-program): + Create new accounts, transfer tokens, and more +- [BPF Loader Program](https://docs.solanalabs.com/runtime/programs#bpf-loader): + Deploys, upgrades, and executes programs on chain +- [Vote program](https://docs.solanalabs.com/runtime/programs#vote-program): + Create and manage accounts that track validator voting state and rewards. ## Executable When a Solana program is deployed onto the network, it is marked as "executable" -by the [BPF Loader Program](../runtime-facilities/programs.md#bpf-loader). This -allows the Solana runtime to efficiently and properly execute the compiled +by the +[BPF Loader Program](https://docs.solanalabs.com/runtime/programs#bpf-loader). +This allows the Solana runtime to efficiently and properly execute the compiled program code. ## Upgradable diff --git a/docs/developing/intro/rent.md b/docs/core/rent.md similarity index 71% rename from docs/developing/intro/rent.md rename to docs/core/rent.md index b0802f569..cdb2a25fa 100644 --- a/docs/developing/intro/rent.md +++ b/docs/core/rent.md @@ -1,4 +1,6 @@ --- +sidebarLabel: Rent +sidebarSortOrder: 3 title: What is rent? description: "Rent: the small fee Solana accounts incur to store data on the blockchain. @@ -9,7 +11,7 @@ description: The fee for every Solana Account to store data on the blockchain is called "_rent_". This _time and space_ based fee is required to keep an account, and therefore its data, alive on the blockchain since -[clusters](../../cluster/overview.md) must actively maintain this data. +[Clusters](/docs/core/clusters.md) must actively maintain this data. All Solana Accounts (and therefore Programs) are required to maintain a high enough LAMPORT balance to become [rent exempt](#rent-exempt) and remain on the @@ -20,11 +22,10 @@ removed from the network in a process known as [Garbage Collection](#garbage-collection). > **Note:** Rent is different from -> [transactions fees](../../transaction_fees.md). Rent is paid (or held in an -> Account) to keep data stored on the Solana blockchain. Whereas transaction +> [transactions fees](/docs/core/transactions/fees.md). Rent is paid (or held in +> an Account) to keep data stored on the Solana blockchain. Whereas transaction > fees are paid to process -> [instructions](../developing/../programming-model/transactions.md#instructions) -> on the network. +> [instructions](/docs/core/transactions.md#instructions) on the network. ### Rent rate @@ -32,7 +33,7 @@ The Solana rent rate is set on a network wide basis, primarily based on the set LAMPORTS _per_ byte _per_ year. Currently, the rent rate is a static amount and stored in the -[Rent sysvar](../runtime-facilities/sysvars.md#rent). +[Rent sysvar](https://docs.solanalabs.com/runtime/sysvars#rent). ## Rent exempt @@ -43,7 +44,7 @@ collection. > At the time of writing this, new Accounts and Programs **are required** to be > initialized with enough LAMPORTS to become rent-exempt. The RPC endpoints have > the ability to calculate this -> [estimated rent exempt balance](../../api/http#getminimumbalanceforrentexemption) +> [estimated rent exempt balance](/docs/rpc/http/getMinimumBalanceForRentExemption.mdx) > and is recommended to be used. Every time an account's balance is reduced, a check is performed to see if the @@ -58,7 +59,7 @@ collection_. This process is done to help reduce the network wide storage of no longer used/maintained data. You can learn more about -[garbage collection here](../../implemented-proposals/persistent-account-storage.md#garbage-collection) +[garbage collection here](https://docs.solanalabs.com/implemented-proposals/persistent-account-storage#garbage-collection) in this implemented proposal. ## Learn more about Rent @@ -66,5 +67,5 @@ in this implemented proposal. You can learn more about Solana Rent with the following articles and documentation: -- [Implemented Proposals - Rent](../../implemented-proposals/rent.md) -- [Implemented Proposals - Account Storage](../../implemented-proposals/persistent-account-storage.md) +- [Implemented Proposals - Rent](https://docs.solanalabs.com/implemented-proposals/rent) +- [Implemented Proposals - Account Storage](https://docs.solanalabs.com/implemented-proposals/persistent-account-storage) diff --git a/docs/developing/programming-model/runtime.md b/docs/core/runtime.md similarity index 92% rename from docs/developing/programming-model/runtime.md rename to docs/core/runtime.md index 1ef245451..39dc1dff9 100644 --- a/docs/developing/programming-model/runtime.md +++ b/docs/core/runtime.md @@ -1,5 +1,7 @@ --- -title: "Runtime" +sidebarLabel: Runtime +title: "Overview of the Solana Runtime" +# sidebarSortOrder: 6 --- ## Capability of Programs @@ -113,23 +115,23 @@ Then any transaction: > the various costs of the operations it performs. 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) +[debugging](/docs/programs/debugging.md#monitoring-compute-budget-consumption) for more information. ### Prioritization fees As part of the Compute Budget, the runtime supports transactions including an **optional** fee to prioritize itself against others known as a -[prioritization fee](./../../transaction_fees.md#prioritization-fee). +[prioritization fee](/docs/intro/transaction_fees.md#prioritization-fee). This _prioritization fee_ is calculated by multiplying the number of _compute units_ by the _compute unit price_ (measured in micro-lamports). These values may be set via the Compute Budget instructions `SetComputeUnitLimit` and `SetComputeUnitPrice` once per transaction. -:::info You can learn more of the specifics of _how_ and _when_ to set a -prioritization fee on the -[transaction fees](./../../transaction_fees.md#prioritization-fee) page. ::: +> You can learn more of the specifics of _how_ and _when_ to set a +> prioritization fee on the +> [transaction fees](/docs/intro/transaction_fees.md#prioritization-fee) page. ### Accounts data size limit @@ -162,7 +164,7 @@ used to activate a feature, which marks it pending, once marked pending the feature will be activated at the next epoch. To determine which features are activated use the -[Solana command-line tools](cli/install-solana-cli-tools.md): +[Solana command-line tools](https://docs.solanalabs.com/cli/install): ```bash solana feature status @@ -170,4 +172,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 -match, [install the correct tool suite](cli/install-solana-cli-tools.md). +match, +[install the correct tool suite](https://docs.solanalabs.com/cli/install). diff --git a/docs/developing/programming-model/transactions.md b/docs/core/transactions.md similarity index 81% rename from docs/developing/programming-model/transactions.md rename to docs/core/transactions.md index 23ea794df..bc62a3347 100644 --- a/docs/developing/programming-model/transactions.md +++ b/docs/core/transactions.md @@ -1,17 +1,17 @@ --- title: "Transactions" +sidebarSortOrder: 4 description: "A Solana transaction consists of one or more instructions, an array of accounts to read and write data from, and one or more signatures." --- On the Solana blockchain, program execution begins with a -[transaction](./../../terminology.md#transaction) being submitted to the -cluster. With each transaction consisting of one or many -[instructions](./../../terminology.md#instruction), the runtime will process -each of the instructions contained within the transaction, in order, and -atomically. If any part of an instruction fails, then the entire transaction -will fail. +[transaction](/docs/terminology.md#transaction) being submitted to the cluster. +With each transaction consisting of one or many +[instructions](/docs/terminology.md#instruction), the runtime will process each +of the instructions contained within the transaction, in order, and atomically. +If any part of an instruction fails, then the entire transaction will fail. ## Overview of a Transaction @@ -24,16 +24,16 @@ This transaction consists of three parts: - an array of accounts to read or write from - one or more signatures -An [instruction](./../../terminology.md#instruction) is the smallest execution +An [instruction](/docs/terminology.md#instruction) is the smallest execution logic on Solana. Instructions are basically a call to update the global Solana state. Instructions invoke programs that make calls to the Solana runtime to update the state (for example, calling the token program to transfer tokens from your account to another account). -[Programs](./../intro/programs.md) on Solana don’t store data/state; rather, +[Programs](/docs/core/programs.md) on Solana don’t store data/state; rather, data/state is stored in accounts. -[Signatures](./../../terminology.md#signature) verify that we have the authority +[Signatures](/docs/terminology.md#signature) verify that we have the authority to read or write data to the accounts that we list. ## Anatomy of a Transaction @@ -113,9 +113,9 @@ keypair. ## Instructions -Each [instruction](terminology.md#instruction) specifies a single program, a -subset of the transaction's accounts that should be passed to the program, and a -data byte array that is passed to the program. The program interprets the data +Each [instruction](/docs/terminology.md#instruction) specifies a single program, +a subset of the transaction's accounts that should be passed to the program, and +a data byte array that is passed to the program. The program interprets the data array and operates on the accounts specified by the instructions. The program can return successfully, or with an error code. An error return causes the entire transaction to fail immediately. @@ -150,31 +150,28 @@ pub fn create_account( } ``` -Which can be found here: - -https://github.com/solana-labs/solana/blob/6606590b8132e56dab9e60b3f7d20ba7412a736c/sdk/program/src/system_instruction.rs#L220 - ### Program Id -The instruction's [program id](./../../terminology.md#program-id) specifies -which program will process this instruction. The program's account's owner -specifies which loader should be used to load and execute the program, and the -data contains information about how the runtime should execute the program. +The instruction's [program id](/docs/terminology.md#program-id) specifies which +program will process this instruction. The program's account's owner specifies +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 SBF programs](./../on-chain-programs/overview.md), the -owner is the SBF 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. +In the case of [on-chain SBF programs](/docs/programs.md), the owner is the SBF +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](../runtime-facilities/programs.md) -are handled differently in that they are built directly into the Solana runtime. +Unlike on-chain programs, +[Native Programs](https://docs.solanalabs.com/runtime/programs) are handled +differently in that they are built directly into the Solana runtime. ### Accounts The accounts referenced by an instruction represent on-chain state and serve as both the inputs and outputs of a program. More information about accounts can be -found in the [Accounts](./accounts.md) section. +found in the [Accounts](/docs/core/accounts.md) section. ### Instruction data @@ -226,11 +223,11 @@ by a transaction signature. Those signatures signal on-chain programs that the account holder has authorized the transaction. Typically, the program uses the 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) +found in [Accounts](/docs/core/accounts.md#signers) ## Recent Blockhash -A transaction includes a recent [blockhash](../../terminology.md#blockhash) to +A transaction includes a recent [blockhash](/docs/terminology.md#blockhash) to prevent duplication and to give transactions lifetimes. Any transaction that is completely identical to a previous one is rejected, so adding a newer blockhash allows multiple transactions to repeat the exact same action. Transactions also diff --git a/docs/developing/transaction_confirmation.md b/docs/core/transactions/confirmation.md similarity index 87% rename from docs/developing/transaction_confirmation.md rename to docs/core/transactions/confirmation.md index 28f2e7c47..d2c8bef7c 100644 --- a/docs/developing/transaction_confirmation.md +++ b/docs/core/transactions/confirmation.md @@ -3,7 +3,7 @@ title: "Transaction Confirmation" --- Problems relating to -[transaction confirmation](./../terminology.md#transaction-confirmations) are +[transaction confirmation](/docs/terminology.md#transaction-confirmations) are common with many newer developers while building applications. This article aims to boost the overall understanding of the confirmation mechanism used on the Solana blockchain, including some recommended best practices. @@ -15,18 +15,18 @@ things... ### What is a transaction? -Transactions consist of two components: a [message](./../terminology.md#message) -and a [list of signatures](./../terminology.md#signature). The transaction -message is where the magic happens and at a high level it consists of three -components: +Transactions consist of two components: a +[message](/docs/terminology.md#message) and a +[list of signatures](/docs/terminology.md#signature). The transaction message is +where the magic happens and at a high level it consists of three components: - a **list of instructions** to invoke, - a **list of accounts** to load, and - a **“recent blockhash.”** In this article, we’re going to be focusing a lot on a transaction’s -[recent blockhash](./../terminology.md#blockhash) because it plays a big role in -transaction confirmation. +[recent blockhash](/docs/terminology.md#blockhash) because it plays a big role +in transaction confirmation. ### Transaction lifecycle refresher @@ -47,10 +47,10 @@ touch on everything except steps 1 and 4. ## What is a Blockhash? -A [“blockhash”](./../terminology.md#blockhash) refers to the last Proof of -History (PoH) hash for a [“slot”](./../terminology.md#slot) (description below). -Since Solana uses PoH as a trusted clock, a transaction’s recent blockhash can -be thought of as a **timestamp**. +A [“blockhash”](/docs/terminology.md#blockhash) refers to the last Proof of +History (PoH) hash for a [“slot”](/docs/terminology.md#slot) (description +below). Since Solana uses PoH as a trusted clock, a transaction’s recent +blockhash can be thought of as a **timestamp**. ### Proof of History refresher @@ -195,18 +195,18 @@ Given the short expiration time frame, it’s imperative that clients help users create transactions with blockhash that is as recent as possible. When fetching blockhashes, the current recommended RPC API is called -[`getLatestBlockhash`](/api/http#getlatestblockhash). By default, this API uses -the `"finalized"` commitment level to return the most recently finalized block’s -blockhash. However, you can override this behavior by -[setting the `commitment` parameter](/api/http#configuring-state-commitment) to -a different commitment level. +[`getLatestBlockhash`](/docs/rpc/http/getLatestBlockhash.mdx). By default, this +API uses the `"finalized"` commitment level to return the most recently +finalized block’s blockhash. However, you can override this behavior by +[setting the `commitment` parameter](/docs/rpc/index.mdx#configuring-state-commitment) +to a different commitment level. **Recommendation** The `"confirmed"` commitment level should almost always be used for RPC requests because it’s usually only a few slots behind the `"processed"` commitment and has a very low chance of belonging to a dropped -[fork](./../cluster/fork-generation.md). +[fork](https://docs.solanalabs.com/consensus/fork-generation). But feel free to consider the other options: @@ -268,9 +268,9 @@ behind the cluster, it will eventually catch up and detect your transaction’s expiration properly. For `simulateTransaction` requests, clients should use the -[`replaceRecentBlockhash`](/api/http#simulatetransaction) parameter to tell the -RPC node to replace the simulated transaction’s blockhash with a blockhash that -will always be valid for simulation. +[`replaceRecentBlockhash`](/docs/rpc/http/simulateTransaction.mdx) parameter to +tell the RPC node to replace the simulated transaction’s blockhash with a +blockhash that will always be valid for simulation. ### Avoid reusing stale blockhashes @@ -312,28 +312,28 @@ Monitor the health of your RPC nodes to ensure that they have an up-to-date view of the cluster state with one of the following methods: 1. Fetch your RPC node’s highest processed slot by using the - [`getSlot`](/api/http#getslot) RPC API with the `"processed"` commitment - level and then call the - [`getMaxShredInsertSlot](/api/http#getmaxshredinsertslot) RPC API to get the - highest slot that your RPC node has received a “shred” of a block for. If the - difference between these responses is very large, the cluster is producing - blocks far ahead of what the RPC node has processed. + [`getSlot`](/docs/rpc/http/getSlot.mdx) RPC API with the `"processed"` + commitment level and then call the + [`getMaxShredInsertSlot](/docs/rpc/http/getMaxShredInsertSlot.mdx) RPC API to + get the highest slot that your RPC node has received a “shred” of a block + for. If the difference between these responses is very large, the cluster is + producing blocks far ahead of what the RPC node has processed. 2. Call the `getLatestBlockhash` RPC API with the `"confirmed"` commitment level on a few different RPC API nodes and use the blockhash from the node that returns the highest slot for its - [context slot](/api/http#rpcresponse-structure). + [context slot](/docs/rpc/index.mdx#rpcresponse-structure). ### Wait long enough for expiration **Recommendation** -When calling [`getLatestBlockhash`](/api/http#getlatestblockhash) RPC API to get -a recent blockhash for your transaction, take note of the +When calling [`getLatestBlockhash`](/docs/rpc/http/getLatestBlockhash.mdx) RPC +API to get a recent blockhash for your transaction, take note of the `"lastValidBlockHeight"` in the response. -Then, poll the [`getBlockHeight`](/api/http#getblockheight) RPC API with the -“confirmed” commitment level until it returns a block height greater than the -previously returned last valid block height. +Then, poll the [`getBlockHeight`](/docs/rpc/http/getBlockHeight.mdx) RPC API +with the “confirmed” commitment level until it returns a block height greater +than the previously returned last valid block height. ### Consider using “durable” transactions @@ -369,6 +369,6 @@ Here’s how these transactions are processed by the Solana runtime: processed again For more details about how these durable transactions work, you can read the -[original proposal](./../implemented-proposals/durable-tx-nonces.md) and -[check out an example](./clients/javascript-reference#nonceaccount) in the -Solana docs. +[original proposal](https://docs.solanalabs.com/implemented-proposals/durable-tx-nonces) +and [check out an example](/docs/clients/javascript-reference.md#nonceaccount) +in the Solana docs. diff --git a/docs/developing/intro/transaction_fees.md b/docs/core/transactions/fees.md similarity index 95% rename from docs/developing/intro/transaction_fees.md rename to docs/core/transactions/fees.md index d32bbf653..4409d9a29 100644 --- a/docs/developing/intro/transaction_fees.md +++ b/docs/core/transactions/fees.md @@ -15,9 +15,8 @@ keywords: - affordable blockchain --- -The small fees paid to process -[instructions](./../../terminology.md#instruction) on the Solana blockchain are -known as "_transaction fees_". +The small fees paid to process [instructions](/docs/terminology.md#instruction) +on the Solana blockchain are known as "_transaction fees_". As each transaction (which contains one or more instructions) is sent through the network, it gets processed by the current leader validation-client. Once @@ -25,7 +24,7 @@ confirmed as a global state transaction, this _transaction fee_ is paid to the network to help support the economic design of the Solana blockchain. > NOTE: Transactions fees are different from the blockchain's data storage fee -> called [rent](./rent.md) +> called [rent](/docs/core/rent.md) ### Transaction Fee Calculation @@ -55,8 +54,11 @@ directly as well: $ curl http://api.mainnet-beta.solana.com -H "Content-Type: application/json" -d ' {"jsonrpc":"2.0","id":1, "method":"getFees"} ' +``` + +Result: (lastValidSlot removed since it's inaccurate) -# RESULT (lastValidSlot removed since it's inaccurate) +```js { "jsonrpc": "2.0", "result": { diff --git a/docs/integrations/retrying-transactions.md b/docs/core/transactions/retry.md similarity index 85% rename from docs/integrations/retrying-transactions.md rename to docs/core/transactions/retry.md index 4676a8070..401bb5991 100644 --- a/docs/integrations/retrying-transactions.md +++ b/docs/core/transactions/retry.md @@ -7,14 +7,12 @@ title: Retrying Transactions On some occasions, a seemingly valid transaction may be dropped before it is included in a block. This most often occurs during periods of network congestion, when an RPC node fails to rebroadcast the transaction to the -[leader](../terminology#leader). To an end-user, it may appear as if their +[leader](/docs/terminology.md#leader). To an end-user, it may appear as if their transaction disappears entirely. While RPC nodes are equipped with a generic rebroadcasting algorithm, application developers are also capable of developing their own custom rebroadcasting logic. -## Facts - -:::note Fact Sheet +## TLDR; - RPC nodes will attempt to rebroadcast transactions using a generic algorithm - Application developers can implement their own custom rebroadcasting logic @@ -25,8 +23,6 @@ their own custom rebroadcasting logic. - Before re-signing any transaction, it is **very important** to ensure that the initial transaction’s blockhash has expired -::: - ## The Journey of a Transaction ### How Clients Submit Transactions @@ -37,9 +33,9 @@ so that they can be processed into a block. There are two main ways in which a transaction can be sent to leaders: 1. By proxy via an RPC server and the - [sendTransaction](../api/http#sendtransaction) JSON-RPC method + [sendTransaction](/docs/rpc/http/sendTransaction.mdx) JSON-RPC method 2. Directly to leaders via a - [TPU Client](https://docs.rs/solana-client/1.7.3/solana_client/tpu_client/index.html) + [TPU Client](https://docs.rs/solana-client/latest/solana_client/tpu_client/index.html) The vast majority of end-users will submit transactions via an RPC server. When a client submits a transaction, the receiving RPC node will in turn attempt to @@ -49,9 +45,7 @@ outside of what the client and the relaying RPC nodes are aware of. In the case of a TPU client, rebroadcast and leader forwarding is handled entirely by the client software. -![Transaction Journey](../../static/img/rt-tx-journey.png) - - +![Overview of a transactions journey, from client to leader](/assets/docs/rt-tx-journey.png) ### How RPC Nodes Broadcast Transactions @@ -63,7 +57,7 @@ communicate with one another, but does not provide any guarantees regarding transaction delivery. Because Solana’s leader schedule is known in advance of every -[epoch](../terminology#epoch) (~2 days), an RPC node will broadcast its +[epoch](/docs/terminology.md#epoch) (~2 days), an RPC node will broadcast its transaction directly to the current and next leaders. This is in contrast to other gossip protocols such as Ethereum that propagate transactions randomly and broadly across the entire network. By default, RPC nodes will try to forward @@ -88,7 +82,7 @@ The TPU processes transactions in five distinct phases: - [Proof of History Service](https://github.com/solana-labs/solana/blob/cd6f931223181d5a1d47cba64e857785a175a760/poh/src/poh_service.rs) - [Broadcast Stage](https://github.com/solana-labs/solana/blob/cd6f931223181d5a1d47cba64e857785a175a760/core/src/tpu.rs#L136) -![TPU Overview](../../static/img/rt-tpu-jito-labs.png) +![Overview of the Transaction Processing Unit (TPU)](/assets/docs/rt-tpu-jito-labs.png) Of these five phases, the Fetch Stage is responsible for receiving transactions. Within the Fetch Stage, validators will categorize incoming transactions @@ -131,14 +125,14 @@ it is processed. The first scenario involves transactions that are submitted via an RPC pool. Occasionally, part of the RPC pool can be sufficiently ahead of the rest of the pool. This can cause issues when nodes within the pool are required to work together. In this example, the transaction’s -[recentBlockhash](../developing/programming-model/transactions#recent-blockhash) -is queried from the advanced part of the pool (Backend A). When the transaction -is submitted to the lagging part of the pool (Backend B), the nodes will not -recognize the advanced blockhash and will drop the transaction. This can be -detected upon transaction submission if developers enable -[preflight checks](../api/http#sendtransaction) on `sendTransaction`. +[recentBlockhash](/docs/core/transactions.md#recent-blockhash) is queried from +the advanced part of the pool (Backend A). When the transaction is submitted to +the lagging part of the pool (Backend B), the nodes will not recognize the +advanced blockhash and will drop the transaction. This can be detected upon +transaction submission if developers enable +[preflight checks](/docs/rpc/http/sendTransaction.mdx) on `sendTransaction`. -![Dropped via RPC Pool](../../static/img/rt-dropped-via-rpc-pool.png) +![Transaction dropped via an RPC Pool](/assets/docs/rt-dropped-via-rpc-pool.png) Temporarily network forks can also result in dropped transactions. If a validator is slow to replay its blocks within the Banking Stage, it may end up @@ -148,7 +142,7 @@ minority fork. After the transaction is submitted, the cluster can then switch away from its minority fork before the transaction is processed. In this scenario, the transaction is dropped due to the blockhash not being found. -![Dropped due to Minority Fork (Before Processed)](../../static/img/rt-dropped-minority-fork-pre-process.png) +![Transaction dropped due to minority fork (before processed)](/assets/docs/rt-dropped-minority-fork-pre-process.png) ### After a transaction is processed and before it is finalized @@ -160,7 +154,7 @@ would fail to reach consensus with the majority of validators that do not recognize the minority fork. At this time, the transaction would be dropped before it could be finalized. -![Dropped due to Minority Fork (After Processed)](../../static/img/rt-dropped-minority-fork-post-process.png) +![Transaction dropped due to minority fork (after processed)](/assets/docs/rt-dropped-minority-fork-post-process.png) ## Handling Dropped Transactions @@ -178,8 +172,6 @@ the transaction, `sendTransaction` will return the transaction id that can be used to track the transaction. A successful response does not indicate whether the transaction will be processed or finalized by the cluster. -:::note - ### Request Parameters - `transaction`: `string` - fully-signed Transaction, as encoded string @@ -187,8 +179,8 @@ the transaction will be processed or finalized by the cluster. - `skipPreflight`: `boolean` - if true, skip the preflight transaction checks (default: false) - (optional) `preflightCommitment`: `string` - - [Commitment](../api/http#configuring-state-commitment) level to use for - preflight simulations against the bank slot (default: "finalized"). + [Commitment](/docs/rpc/index.mdx#configuring-state-commitment) level to use + for preflight simulations against the bank slot (default: "finalized"). - (optional) `encoding`: `string` - Encoding used for the transaction data. Either "base58" (slow), or "base64". (default: "base58"). - (optional) `maxRetries`: `usize` - Maximum number of times for the RPC node @@ -196,14 +188,12 @@ the transaction will be processed or finalized by the cluster. provided, the RPC node will retry the transaction until it is finalized or until the blockhash expires. -Response +**Response:** - `transaction id`: `string` - First transaction signature embedded in the transaction, as base-58 encoded string. This transaction id can be used with - [`getSignatureStatuses`](../api/http#getsignaturestatuses) to poll for status - updates. - -::: + [`getSignatureStatuses`](/docs/rpc/http/getSignatureStatuses.mdx) to poll for + status updates. ## Customizing Rebroadcast Logic @@ -215,12 +205,12 @@ developers to manually control the retry process A common pattern for manually retrying transactions involves temporarily storing the `lastValidBlockHeight` that comes from -[getLatestBlockhash](../api/http#getlatestblockhash). Once stashed, an +[getLatestBlockhash](/docs/rpc/http/getLatestBlockhash.mdx). Once stashed, an application can then -[poll the cluster’s blockheight](../api/http#getblockheight) and manually retry -the transaction at an appropriate interval. In times of network congestion, it’s -advantageous to set `maxRetries` to 0 and manually rebroadcast via a custom -algorithm. While some applications may employ an +[poll the cluster’s blockheight](/docs/rpc/http/getBlockHeight.mdx) and manually +retry the transaction at an appropriate interval. In times of network +congestion, it’s advantageous to set `maxRetries` to 0 and manually rebroadcast +via a custom algorithm. While some applications may employ an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) algorithm, others such as [Mango](https://www.mango.markets/) opt to [continuously resubmit](https://github.com/blockworks-foundation/mango-ui/blob/b6abfc6c13b71fc17ebbe766f50b8215fa1ec54f/src/utils/send.tsx#L713) @@ -284,8 +274,8 @@ const sleep = async (ms: number) => { ``` When polling via `getLatestBlockhash`, applications should specify their -intended [commitment](../api/http#configuring-state-commitment) level. By -setting its commitment to `confirmed` (voted on) or `finalized` (~30 blocks +intended [commitment](/docs/rpc/index.mdx#configuring-state-commitment) level. +By setting its commitment to `confirmed` (voted on) or `finalized` (~30 blocks after `confirmed`), an application can avoid polling a blockhash from a minority fork. @@ -325,6 +315,7 @@ if they unintentionally sent the same transaction twice. In Solana, a dropped transaction can be safely discarded once the blockhash it references is older than the `lastValidBlockHeight` received from `getLatestBlockhash`. Developers should keep track of this -`lastValidBlockHeight` by querying [`getEpochInfo`](../api/http#getepochinfo) -and comparing with `blockHeight` in the response. Once a blockhash is -invalidated, clients may re-sign with a newly-queried blockhash. +`lastValidBlockHeight` by querying +[`getEpochInfo`](/docs/rpc/http/getEpochInfo.mdx) and comparing with +`blockHeight` in the response. Once a blockhash is invalidated, clients may +re-sign with a newly-queried blockhash. diff --git a/docs/developing/versioned-transactions.md b/docs/core/transactions/versions.md similarity index 82% rename from docs/developing/versioned-transactions.md rename to docs/core/transactions/versions.md index e74b58558..6bfd01254 100644 --- a/docs/developing/versioned-transactions.md +++ b/docs/core/transactions/versions.md @@ -3,14 +3,14 @@ title: Versioned Transactions description: "" --- -[Versioned Transactions](./versioned-transactions.md) are the new transaction -format that allow for additional functionality in the Solana runtime, including -[Address Lookup Tables](./lookup-tables.md). - -While changes to [on chain](./on-chain-programs/overview.md) programs are -**NOT** required to support the new functionality of versioned transactions (or -for backwards compatibility), developers **WILL** need update their client side -code to prevent +[Versioned Transactions](/docs/core/transactions/versions.md) are the new +transaction format that allow for additional functionality in the Solana +runtime, including [Address Lookup Tables](/docs/advanced/lookup-tables.md). + +While changes to [on chain](/docs/programs/index.md) programs are **NOT** +required to support the new functionality of versioned transactions (or for +backwards compatibility), developers **WILL** need update their client side code +to prevent [errors due to different transaction versions](#max-supported-transaction-version). ## Current Transaction Versions @@ -18,19 +18,20 @@ code to prevent The Solana runtime supports two transaction versions: - `legacy` - older transaction format with no additional benefit -- `0` - added support for [Address Lookup Tables](./lookup-tables.md) +- `0` - added support for + [Address Lookup Tables](/docs/advanced/lookup-tables.md) ## Max supported transaction version All RPC requests that return a transaction **_should_** specify the highest version of transactions they will support in their application using the `maxSupportedTransactionVersion` option, including -[`getBlock`](../api/http#getblock) and -[`getTransaction`](../api/http#gettransaction). +[`getBlock`](/docs/rpc/http/getBlock.mdx) and +[`getTransaction`](/docs/rpc/http/getTransaction.mdx). An RPC request will fail if a -[Versioned Transaction](./versioned-transactions.md) is returned that is higher -than the set `maxSupportedTransactionVersion`. (i.e. if a version `0` +[Versioned Transaction](/docs/core/transactions/versions.md) is returned that is +higher than the set `maxSupportedTransactionVersion`. (i.e. if a version `0` transaction is returned when `legacy` is selected) > WARNING: If no `maxSupportedTransactionVersion` value is set, then only @@ -118,7 +119,7 @@ transaction. In this example below, we are creating a simple SOL transfer instruction: ```js -// create an array with your desires `instructions` +// create an array with your desired `instructions` const instructions = [ web3.SystemProgram.transfer({ fromPubkey: payer.publicKey, @@ -176,9 +177,10 @@ console.log(`https://explorer.solana.com/tx/${txid}?cluster=devnet`); ## More Resources - using - [Versioned Transactions for Address Lookup Tables](./lookup-tables.md#how-to-create-an-address-lookup-table) + [Versioned Transactions for Address Lookup Tables](/docs/advanced/lookup-tables.md#how-to-create-an-address-lookup-table) - view an [example of a v0 transaction](https://explorer.solana.com/tx/3jpoANiFeVGisWRY5UP648xRXs3iQasCHABPWRWnoEjeA93nc79WrnGgpgazjq4K9m8g2NJoyKoWBV1Kx5VmtwHQ/?cluster=devnet) on Solana Explorer -- read the [accepted proposal](./../proposals/versioned-transactions.md) for - Versioned Transaction and Address Lookup Tables +- read the + [accepted proposal](https://docs.solanalabs.com/proposals/versioned-transactions) + for Versioned Transaction and Address Lookup Tables diff --git a/docs/developing/guides/compressed-nfts.md b/docs/developing/guides/compressed-nfts.md deleted file mode 100644 index 3dd613dfa..000000000 --- a/docs/developing/guides/compressed-nfts.md +++ /dev/null @@ -1,862 +0,0 @@ ---- -title: Creating Compressed NFTs with JavaScript -description: - "Compressed NFTs use the Bubblegum program from Metaplex to cheaply and - securely store NFT metadata using State Compression on Solana." -keywords: - - compression - - merkle tree - - read api - - metaplex ---- - -Compressed NFTs on Solana use the -[Bubblegum](https://docs.metaplex.com/programs/compression/) program from -Metaplex to cheaply and securely store NFT metadata using -[State Compression](../../learn/state-compression.md). - -This developer guide will use JavaScript/TypeScript to demonstrate: - -- [how to create a tree for compressed NFTs](#create-a-tree), -- [how to mint compressed NFTs into a tree](#mint-compressed-nfts), -- [how to get compressed NFT metadata from the Read API](#reading-compressed-nfts-metadata), - and -- [how to transfer compressed NFTs](#transfer-compressed-nfts) - -## Intro to Compressed NFTs - -Compressed NFTs use [State Compression](../../learn/state-compression.md) and -[merkle trees](../../learn/state-compression.md#what-is-a-merkle-tree) to -drastically reduce the storage cost for NFTs. Instead of storing an NFT's -metadata in a typical Solana account, compressed NFTs store the metadata within -the ledger. This allows compressed NFTs to still inherit the security and speed -of the Solana blockchain, while at the same time reducing the overall storage -costs. - -Even though the on-chain data storage mechanism is different than their -uncompressed counterparts, compressed NFTs still follow the exact same -[Metadata](https://docs.metaplex.com/programs/token-metadata/accounts#metadata) -schema/structure. Allowing you to define your Collection and NFT in an identical -way. - -However, the process to mint and transfer compressed NFTs is different from -uncompressed NFTs. Aside from using a different on-chain program, compressed -NFTs are minting into a merkle tree and require verification of a "proof" to -transfer. More on this below. - -### Compressed NFTs and indexers - -Since compressed NFTs store all of their metadata in the -[ledger](../../terminology.md#ledger), instead of in traditional -[accounts](../../terminology.md#account) like uncompressed NFTs, we will need to -help of indexing services to quickly fetch our compressed NFT's metadata. - -Supporting RPC providers are using the Digital Asset Standard Read API (or "Read -API" for short) to add additional RPC methods that developers can call. These -additional, NFT oriented methods, are loaded with all the information about -particular NFTs. Including support for **BOTH** compressed NFTs **AND** -uncompressed NFTs. - -:::caution Metadata is secured by the ledger and cached by indexers - -Since validators do not keep a very long history of the recent ledger data, -these indexers effectively "cache" the compressed NFT metadata passed through -the Solana ledger. Quickly serving it back on request to improve speed and user -experience of applications. - -However, since the metadata was already secured by the ledger when minting the -compressed NFT, anyone could re-index the metadata directly from the secure -ledger. Allowing for independent verification of the data, should the need or -desire arise. - -::: - -These indexing services are already available from some of the common RPC -providers, with more rolling out support in the near future. To name a few of -the RPC providers that already support the Read API: - -- Helius -- Triton -- SimpleHash - -### How to mint compressed NFTs - -The process to create or mint compressed NFTs on Solana is similar to creating a -"traditional NFT collection", with a few differences. The mint process will -happen in 3 primary steps: - -- create an NFT collection (or use an existing one) -- create a - [concurrent merkle tree](../../learn/state-compression.md#what-is-a-concurrent-merkle-tree) - (using the `@solana/spl-account-compression` SDK) -- mint compressed NFTs into your tree (to any owner's address you want) - -### How to transfer a compressed NFT - -Once your compressed NFT exists on the Solana blockchain, the process to -transfer ownership of a compressed NFT happens in a few broad steps: - -1. get the NFT "asset" information (from the indexer) -2. get the NFT's "proof" (from the indexer) -3. get the Merkle tree account (from the Solana blockchain) -4. prepare the asset proof (by parsing and formatting it) -5. build and send the transfer instruction - -The first three steps primarily involve gathering specific pieces of information -(the `proof` and the tree's canopy depth) for the NFT to be transferred. These -pieces of information are needed to correctly parse/format the `proof` to -actually be sent within the transfer instruction itself. - -## Getting started - -For this guide, we are going to make a few assumptions about the compressed NFT -collection we are going to create: - -- we are going to use TypeScript and NodeJS for this example -- we will use a single, **new** Metaplex collection - -### Project Setup - -Before we start creating our compressed NFT collection, we need to install a few -packages: - -- [`@solana/web3.js`](https://www.npmjs.com/package/@solana/web3.js) - the base - Solana JS SDK for interacting with the blockchain, including making our RPC - connection and sending transactions -- [`@solana/spl-token`](https://www.npmjs.com/package/@solana/spl-token) - used - in creating our collection and mint on-chain -- [`@solana/spl-account-compression`](https://www.npmjs.com/package/@solana/spl-account-compression) - - used to create the on-chain tree to store our compressed NFTs -- [`@metaplex-foundation/mpl-bubblegum`](https://www.npmjs.com/package/@metaplex-foundation/mpl-bubblegum) - - used to get the types and helper functions for minting and transferring - compressed NFTs on-chain -- [`@metaplex-foundation/mpl-token-metadata`](https://www.npmjs.com/package/@metaplex-foundation/mpl-token-metadata) - -used to get the types and helper functions for our NFT's metadata - - -Using your preferred package manager (e.g. npm, yarn, pnpm, etc), install these -packages into your project: - -```sh -yarn add @solana/web3.js @solana/spl-token @solana/spl-account-compression -``` - -```sh -yarn add @metaplex-foundation/mpl-bubblegum @metaplex-foundation/mpl-token-metadata -``` - -## Create a Collection - -NFTs are normally grouped together into a -[Collection](https://docs.metaplex.com/programs/token-metadata/certified-collections#collection-nfts) -using the Metaplex standard. This is true for **BOTH** traditional NFTs **AND** -compressed NFTs. The NFT Collection will store all the broad metadata for our -NFT grouping, such as the collection image and name that will appear in wallets -and explorers. - -Under the hood, an NFT collection acts similar to any other token on Solana. -More specifically, a Collection is effectively a uncompressed NFT. So we -actually create them following the same process of creating an -[SPL token](https://spl.solana.com/token): - -- create a new token "mint" -- create a associated token account (`ata`) for our token mint -- actually mint a single token -- store the collection's metadata in an Account on-chain - -Since NFT Collections having nothing special to do with -[State Compression](../../learn/state-compression.md) or -[compressed NFTs](./compressed-nfts.md), we will not cover creating one in this -guide. - -### Collection addresses - -Even though this guide does not cover creating one, we will need the many of the -various addresses for your Collection, including: - -- `collectionAuthority` - this may be your `payer` but it also might not be -- `collectionMint` - the collection's mint address -- `collectionMetadata` - the collection's metadata account -- `editionAccount` - for example, the `masterEditionAccount` created for your - collection - -## Create a tree - -One of the most important decisions to make when creating compressed NFTs is -[how to setup your tree](../../learn/state-compression.md#sizing-a-concurrent-merkle-tree). -Especially since the values used to size your tree will determine the overall -cost of creation, and **CANNOT** be changed after creation. - -:::caution - -A tree is **NOT** the same thing as a collection. A single collection can use -_any_ number of trees. In fact, this is usually recommended for larger -collections due to smaller trees having greater composability. - -Conversely, even though a tree **could** be used in multiple collections, it is -generally considered an anti-pattern and is not recommended. - -::: - -Using the helper functions provided by the -[`@solana/spl-account-compression`](https://www.npmjs.com/package/@solana/spl-account-compression) -SDK, we can create our tree in the following steps: - -- decide on our tree size -- generate a new Keypair and allocated space for the tree on-chain -- actually create the tree (making it owned by the Bubblegum program) - -### Size your tree - -Your tree size is set by 3 values, each serving a very specific purpose: - -1. `maxDepth` - used to determine how many NFTs we can have in the tree -2. `maxBufferSize` - used to determine how many updates to your tree are - possible in the same block -3. `canopyDepth` - used to store a portion of the proof on chain, and as such is - a large of cost and composability of your compressed NFT collection - -:::info - -Read more about the details about -[State Compression](../../learn/state-compression.md), including -[how to size a tree](../../learn/state-compression.md#sizing-a-concurrent-merkle-tree) -and potential composability concerns. - -::: - -Let's assume we are going to create a compressed NFT collection with 10k NFTs in -it. And since our collection is relatively small, we only need a single smaller -tree to store all the NFTs: - -```ts -// define the depth and buffer size of our tree to be created -const maxDepthSizePair: ValidDepthSizePair = { - // max=16,384 nodes (for a `maxDepth` of 14) - maxDepth: 14, - maxBufferSize: 64, -}; - -// define the canopy depth of our tree to be created -const canopyDepth = 10; -``` - -Setting a `maxDepth` of `14` will allow our tree to hold up to `16,384` -compressed NFTs, more than exceeding our `10k` collection size. - -Since only specific -[`ValidDepthSizePair`](https://solana-labs.github.io/solana-program-library/account-compression/sdk/docs/modules/index.html#ValidDepthSizePair) -pairs are allowed, simply set the `maxBufferSize` to the corresponding value -tied to your desired `maxDepth`. - -Next, setting `canopyDepth` of `10` tells our tree to store `10` of our "proof -node hashes" on-chain. Thus requiring us to always include `4` proof node values -(i.e. `maxDepth - canopyDepth`) in every compressed NFT transfer instruction. - -### Generate addresses for the tree - -When creating a new tree, we need to generate a new -[Keypair](../../terminology.md#keypair) address for the tree to have: - -```ts -const treeKeypair = Keypair.generate(); -``` - -Since our tree will be used for compressed NFTs, we will also need to derive an -Account with authority that is owned by the Bubblegum program (i.e. PDA): - -```ts -// derive the tree's authority (PDA), owned by Bubblegum -const [treeAuthority, _bump] = PublicKey.findProgramAddressSync( - [treeKeypair.publicKey.toBuffer()], - BUBBLEGUM_PROGRAM_ID, -); -``` - -### Build the tree creation instructions - -With our tree size values defined, and our addresses generated, we need to build -two related instructions: - -1. allocate enough space on-chain for our tree -2. actually create the tree, owned by the Bubblegum program - -Using the -[`createAllocTreeIx`](https://solana-labs.github.io/solana-program-library/account-compression/sdk/docs/modules/index.html#createAllocTreeIx) -helper function, we allocate enough space on-chain for our tree. - -```ts -// allocate the tree's account on chain with the `space` -const allocTreeIx = await createAllocTreeIx( - connection, - treeKeypair.publicKey, - payer.publicKey, - maxDepthSizePair, - canopyDepth, -); -``` - -Then using the -[`createCreateTreeInstruction`](https://metaplex-foundation.github.io/metaplex-program-library/docs/bubblegum/functions/createCreateTreeInstruction.html) -from the Bubblegum SDK, we actually create the tree on-chain. Making it owned by -the Bubblegum program. - -```ts -// create the instruction to actually create the tree -const createTreeIx = createCreateTreeInstruction( - { - payer: payer.publicKey, - treeCreator: payer.publicKey, - treeAuthority, - merkleTree: treeKeypair.publicKey, - compressionProgram: SPL_ACCOUNT_COMPRESSION_PROGRAM_ID, - // NOTE: this is used for some on chain logging - logWrapper: SPL_NOOP_PROGRAM_ID, - }, - { - maxBufferSize: maxDepthSizePair.maxBufferSize, - maxDepth: maxDepthSizePair.maxDepth, - public: false, - }, - BUBBLEGUM_PROGRAM_ID, -); -``` - -### Build and send the transaction - -With our two instructions built, we can add them into a transaction and send -them to the blockchain, making sure both the `payer` and generated `treeKeypair` -sign the transaction: - -```ts -// build the transaction -const tx = new Transaction().add(allocTreeIx).add(createTreeIx); -tx.feePayer = payer.publicKey; - -// send the transaction -const txSignature = await sendAndConfirmTransaction( - connection, - tx, - // ensuring the `treeKeypair` PDA and the `payer` are BOTH signers - [treeKeypair, payer], - { - commitment: "confirmed", - skipPreflight: true, - }, -); -``` - -After a few short moments, and once the transaction is confirmed, we are ready -to start minting compressed NFTs into our tree. - -## Mint compressed NFTs - -Since compressed NFTs follow the same Metaplex -[metadata standards](https://docs.metaplex.com/programs/token-metadata/accounts#metadata) -as traditional NFTs, we can define our actual NFTs data the same way. - -The primary difference is that with compressed NFTs the metadata is actually -stored in the ledger (unlike traditional NFTs that store them in accounts). The -metadata gets "hashed" and stored in our tree, and by association, secured by -the Solana ledger. - -Allowing us to cryptographically verify that our original metadata has not -changed (unless we want it to). - -:::info - -Learn more about how State Compression uses -[concurrent merkle trees](../../learn/state-compression.md#what-is-a-concurrent-merkle-tree) -to cryptographically secure off-chain data using the Solana ledger. - -::: - -### Define our NFT's metadata - -We can define the specific metadata for the single NFT we are about to mint: - -```ts -const compressedNFTMetadata: MetadataArgs = { - name: "NFT Name", - symbol: "ANY", - // specific json metadata for each NFT - uri: "https://supersweetcollection.notarealurl/token.json", - creators: null, - editionNonce: 0, - uses: null, - collection: null, - primarySaleHappened: false, - sellerFeeBasisPoints: 0, - isMutable: false, - // these values are taken from the Bubblegum package - tokenProgramVersion: TokenProgramVersion.Original, - tokenStandard: TokenStandard.NonFungible, -}; -``` - -In this demo, the key pieces of our NFT's metadata to note are: - -- `name` - this is the actual name of our NFT that will be displayed in wallets - and on explorers. -- `uri` - this is the address for your NFTs metadata JSON file. -- `creators` - for this example, we are not storing a list of creators. If you - want your NFTs to have royalties, you will need to store actual data here. You - can checkout the Metaplex docs for more info on it. - -### Derive the Bubblegum signer - -When minting new compressed NFTs, the Bubblegum program needs a PDA to perform a -[cross-program invocation](../programming-model/calling-between-programs#cross-program-invocations) -(`cpi`) to the SPL compression program. - -:::caution - -This `bubblegumSigner` PDA is derived using a hard coded seed string of -`collection_cpi` and owned by the Bubblegum program. If this hard coded value is -not provided correctly, your compressed NFT minting will fail. - -::: - -Below, we derive this PDA using the **required** hard coded seed string of -`collection_cpi`: - -```ts -// derive a PDA (owned by Bubblegum) to act as the signer of the compressed minting -const [bubblegumSigner, _bump2] = PublicKey.findProgramAddressSync( - // `collection_cpi` is a custom prefix required by the Bubblegum program - [Buffer.from("collection_cpi", "utf8")], - BUBBLEGUM_PROGRAM_ID, -); -``` - -### Create the mint instruction - -Now we should have all the information we need to actually mint our compressed -NFT. - -Using the `createMintToCollectionV1Instruction` helper function provided in the -Bubblegum SDK, we can craft the instruction to actually mint our compressed NFT -directly into our collection. - -If you have minted traditional NFTs on Solana, this will look fairly similar. We -are creating a new instruction, giving several of the account addresses you -might expect (e.g. the `payer`, `tokenMetadataProgram`, and various collection -addresses), and then some tree specific addresses. - -The addresses to pay special attention to are: - -- `leafOwner` - this will be the owner of the compressed NFT. You can either - mint it your self (i.e. the `payer`), or airdrop to any other Solana address -- `leafDelegate` - this is the delegated authority of this specific NFT we are - about to mint. If you do not want to have a delegated authority for the NFT we - are about to mint, then this value should be set to the same address of - `leafOwner`. - -```ts -const compressedMintIx = createMintToCollectionV1Instruction( - { - payer: payer.publicKey, - - merkleTree: treeAddress, - treeAuthority, - treeDelegate: payer.publicKey, - - // set the receiver of the NFT - leafOwner: receiverAddress || payer.publicKey, - // set a delegated authority over this NFT - leafDelegate: payer.publicKey, - - // collection details - collectionAuthority: payer.publicKey, - collectionAuthorityRecordPda: BUBBLEGUM_PROGRAM_ID, - collectionMint: collectionMint, - collectionMetadata: collectionMetadata, - editionAccount: collectionMasterEditionAccount, - - // other accounts - bubblegumSigner: bubblegumSigner, - compressionProgram: SPL_ACCOUNT_COMPRESSION_PROGRAM_ID, - logWrapper: SPL_NOOP_PROGRAM_ID, - tokenMetadataProgram: TOKEN_METADATA_PROGRAM_ID, - }, - { - metadataArgs: Object.assign(compressedNFTMetadata, { - collection: { key: collectionMint, verified: false }, - }), - }, -); -``` - -Some of the other tree specific addresses are: - -- `merkleTree` - the address of our tree we created -- `treeAuthority` - the authority of the tree -- `treeDelegate` - the delegated authority of the entire tree - -Then we also have all of our NFT collection's addresses, including the mint -address, metadata account, and edition account. These addresses are also -standard to pass in when minting uncompressed NFTs. - -#### Sign and send the transaction - -Once our compressed mint instruction has been created, we can add it to a -transaction and send it to the Solana network: - -```ts -const tx = new Transaction().add(compressedMintIx); -tx.feePayer = payer.publicKey; - -// send the transaction to the cluster -const txSignature = await sendAndConfirmTransaction(connection, tx, [payer], { - commitment: "confirmed", - skipPreflight: true, -}); -``` - -## Reading compressed NFTs metadata - -With the help of a supporting RPC provider, developers can use the Digital Asset -Standard Read API (or "Read API" for short) to fetch the metadata of NFTs. - -:::info - -The Read API supports both compressed NFTs and traditional/uncompressed NFTs. -You can use the same RPC endpoints to retrieve all the assorted information for -both types of NFTs, including auto-fetching the NFTs' JSON URI. - -::: - -### Using the Read API - -When working with the Read API and a supporting RPC provider, developers can -make `POST` requests to the RPC endpoint using your preferred method of making -such requests (e.g. `curl`, JavaScript `fetch()`, etc). - -:::warning Asset ID - -Within the Read API, digital assets (i.e. NFTs) are indexed by their `id`. This -asset `id` value differs slightly between traditional NFTs and compressed NFTs: - -- for traditional/uncompressed NFTs: this is the token's address for the actual - Account on-chain that stores the metadata for the asset. -- for compressed NFTs: this is the `id` of the compressed NFT within the tree - and is **NOT** an actual on-chain Account address. While a compressed NFT's - `assetId` resembles a traditional Solana Account address, it is not. - -::: - -### Common Read API Methods - -While the Read API supports more than these listed below, the most commonly used -methods are: - -- `getAsset` - get a specific NFT asset by its `id` -- `getAssetProof` - returns the merkle proof that is required to transfer a - compressed NFT, by its asset `id` -- `getAssetsByOwner` - get the assets owned by a specific address -- `getAssetsByGroup` - get the assets by a specific grouping (i.e. a collection) - -:::info Read API Methods, Schema, and Specification - -Explore all the additional RPC methods added by Digital Asset Standard Read API -on [Metaplex's RPC Playground](https://metaplex-read-api.surge.sh/). Here you -will also find the expected inputs and response schema for each supported RPC -method. - -::: - -### Example Read API Request - -For demonstration, below is an example request for the `getAsset` method using -the -[JavaScript Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), -which is built into modern JavaScript runtimes: - -```ts -// make a POST request to the RPC using the JavaScript `fetch` api -const response = await fetch(rpcEndpointUrl, { - method: "POST", - headers: { - "Content-Type": "application/json", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "rpd-op-123", - method: "getAsset", - params: { - id: "5q7qQ4FWYyj4vnFrivRBe6beo6p88X8HTkkyVPjPkQmF", - }, - }), -}); -``` - -### Example Read API Response - -With a successful response from the RPC, you should seem similar data to this: - -```ts -{ - interface: 'V1_NFT', - id: '5q7qQ4FWYyj4vnFrivRBe6beo6p88X8HTkkyVPjPkQmF', - content: [Object], - authorities: [Array], - compression: [Object], - grouping: [], - royalty: [Object], - creators: [], - ownership: [Object], - supply: [Object], - mutable: false -} -``` - -The response fields to pay special attention to are: - -- `id` - this is your asset's `id` -- `grouping` - can tell you the collection address that the NFT belongs to. The - collection address will be the `group_value`. -- `metadata` - contains the actual metadata for the NFT, including the auto - fetched JSON uri set when the NFT was minted -- `ownership` - gives you the NFT owner's address (and also if the NFT has - delegated authority to another address) -- `compression` - tells you if this NFT is actually using compression or not. - For compressed NFTs, this will also give you the tree address that is storing - the compressed NFT on chain. - -:::caution - -Some of the returned values may be empty if the NFT is **not** a compressed NFT, -such as many of the `compression` fields. This is expected. - -::: - -## Transfer compressed NFTs - -Transferring compressed NFTs is different from transferring uncompressed NFTs. -Aside from using a different on-chain program, compressed NFTs require the use -of a asset's "merkle proof" (or `proof` for short) to actually change ownership. - -:::info What is a merkle proof? - -An asset's "merkle proof" is a listing of all the "adjacent hashes" within the -tree that are required to validate a specific leaf within said tree. - -These proof hashes themselves, and the specific asset's leaf data, are hashed -together in a deterministic way to compute the "root hash". Therefore, allowing -for cryptographic validation of an asset within the merkle tree. - -**NOTE:** While each of these hash values resemble a Solana Account's -[address/public key](../../terminology.md#public-key-pubkey), they are not -addresses. - -::: - -Transferring ownership of a compressed NFT happens in 5 broad steps: - -1. get the NFT's "asset" data (from the indexer) -2. get the NFT's proof (from the indexer) -3. get the Merkle tree account (directly from the Solana blockchain) -4. prepare the asset proof -5. build and send the transfer instruction - -The first three steps primarily involve gathering specific pieces of information -(the `proof` and the tree's canopy depth) for the NFT to be transferred. These -pieces of information are needed to correctly parse/format the `proof` to -actually be sent within the transfer instruction itself. - -### Get the asset - -To perform the transfer of our compressed NFT, we will need to retrieve a few -pieces of information about the NFT. - -For starters, we will need to get some the asset's information in order to allow -the on-chain compression program to correctly perform validation and security -checks. - -We can use the `getAsset` RPC method to retrieve two important pieces of -information for the compressed NFT: the `data_hash` and `creator_hash`. - -#### Example response from the `getAsset` method - -Below is an example response from the `getAsset` method: - -```ts -compression: { - eligible: false, - compressed: true, - data_hash: 'D57LAefACeaJesajt6VPAxY4QFXhHjPyZbjq9efrt3jP', - creator_hash: '6Q7xtKPmmLihpHGVBA6u1ENE351YKoyqd3ssHACfmXbn', - asset_hash: 'F3oDH1mJ47Z7tNBHvrpN5UFf4VAeQSwTtxZeJmn7q3Fh', - tree: 'BBUkS4LZQ7mU8iZXYLVGNUjSxCYnB3x44UuPVHVXS9Fo', - seq: 3, - leaf_id: 0 -} -``` - -### Get the asset proof - -The next step in preparing your compressed NFT transfer instruction, is to get a -**valid** asset `proof` to perform the transfer. This proof is required by the -on-chain compression program to validate on-chain information. - -We can use the `getAssetProof` RPC method to retrieve two important pieces of -information: - -- `proof` - the "full proof" that is required to perform the transfer (more on - this below) -- `tree_id` - the on-chain address of the compressed NFTs tree - -:::info Full proof is returned - -The `getAssetProof` RPC method returns the complete listing of "proof hashes" -that are used to perform the compressed NFT transfer. Since this "full proof" is -returned from the RPC, we will need to remove the portion of the "full proof" -that is stored on-chain via the tree's `canopy`. - -::: - -#### Example response from the `getAssetProof` method - -Below is an example response from the `getAssetProof` method: - -```ts -{ - root: '7dy5bzgaRcUnNH2KMExwNXXNaCJnf7wQqxc2VrGXy9qr', - proof: [ - 'HdvzZ4hrPEdEarJfEzAavNJEZcCS1YU1fg2uBvQGwAAb', - ... - '3e2oBSLfSDVdUdS7jRGFKa8nreJUA9sFPEELrHaQyd4J' - ], - node_index: 131072, - leaf: 'F3oDH1mJ47Z7tNBHvrpN5UFf4VAeQSwTtxZeJmn7q3Fh', - tree_id: 'BBUkS4LZQ7mU8iZXYLVGNUjSxCYnB3x44UuPVHVXS9Fo' -} -``` - -### Get the Merkle tree account - -Since the `getAssetProof` will always return the "full proof", we will have to -reduce it down in order to remove the proof hashes that are stored on-chain in -the tree's canopy. But in order to remove the correct number of proof addresses, -we need to know the tree's `canopyDepth`. - -Once we have our compressed NFT's tree address (the `tree_id` value from -`getAssetProof`), we can use the -[`ConcurrentMerkleTreeAccount`](https://solana-labs.github.io/solana-program-library/account-compression/sdk/docs/classes/index.ConcurrentMerkleTreeAccount.html) -class, from the `@solana/spl-account-compression` SDK: - -```ts -// retrieve the merkle tree's account from the blockchain -const treeAccount = await ConcurrentMerkleTreeAccount.fromAccountAddress( - connection, - treeAddress, -); - -// extract the needed values for our transfer instruction -const treeAuthority = treeAccount.getAuthority(); -const canopyDepth = treeAccount.getCanopyDepth(); -``` - -For the transfer instruction, we will also need the current `treeAuthority` -address which we can also get via the `treeAccount`. - -### Prepare the asset proof - -With our "full proof" and `canopyDepth` values on hand, we can correctly format -the `proof` to be submitted within the transfer instruction itself. - -Since we will use the `createTransferInstruction` helper function from the -Bubblegum SDK to actually build our transfer instruction, we need to: - -- remove the proof values that are already stored on-chain in the - [tree's canopy](../../learn/state-compression.md#canopy-depth), and -- convert the remaining proof values into the valid `AccountMeta` structure that - the instruction builder function accepts - -```ts -// parse the list of proof addresses into a valid AccountMeta[] -const proof: AccountMeta[] = assetProof.proof - .slice(0, assetProof.proof.length - (!!canopyDepth ? canopyDepth : 0)) - .map((node: string) => ({ - pubkey: new PublicKey(node), - isSigner: false, - isWritable: false, - })); -``` - -In the TypeScript code example above, we are first taking a `slice` of our "full -proof", starting at the beginning of the array, and ensuring we only have -`proof.length - canopyDepth` number of proof values. This will remove the -portion of the proof that is already stored on-chain in the tree's canopy. - -Then we are structuring each of the remaining proof values as a valid -`AccountMeta`, since the proof is submitted on-chain in the form of "extra -accounts" within the transfer instruction. - -### Build the transfer instruction - -Finally, with all the required pieces of data about our tree and compressed -NFTs, and a correctly formatted proof, we are ready to actually create the -transfer instruction. - -Build your transfer instruction using the -[`createTransferInstruction`](https://metaplex-foundation.github.io/metaplex-program-library/docs/bubblegum/functions/createTransferInstruction.html) -helper function from the Bubblegum SDK: - -```ts -// create the NFT transfer instruction (via the Bubblegum package) -const transferIx = createTransferInstruction( - { - merkleTree: treeAddress, - treeAuthority, - leafOwner, - leafDelegate, - newLeafOwner, - logWrapper: SPL_NOOP_PROGRAM_ID, - compressionProgram: SPL_ACCOUNT_COMPRESSION_PROGRAM_ID, - anchorRemainingAccounts: proof, - }, - { - root: [...new PublicKey(assetProof.root.trim()).toBytes()], - dataHash: [...new PublicKey(asset.compression.data_hash.trim()).toBytes()], - creatorHash: [ - ...new PublicKey(asset.compression.creator_hash.trim()).toBytes(), - ], - nonce: asset.compression.leaf_id, - index: asset.compression.leaf_id, - }, - BUBBLEGUM_PROGRAM_ID, -); -``` - -Aside from passing in our assorted Account addresses and the asset's proof, we -are converting the string values of our `data_hash`, `creator_hash`, `root` hash -into an array of bytes that is accepted by the `createTransferInstruction` -helper function. - -Since each of these hash values resemble and are formatted similar to -PublicKeys, we can use the -[`PublicKey`](https://solana-labs.github.io/solana-web3.js/classes/PublicKey.html) -class in web3.js to convert them into a accepted byte array format. - -#### Send the transaction - -With our transfer instructions built, we can add it into a transaction and send -it to the blockchain similar to before. Making sure either the current -`leafOwner` or the `leafDelegate` signs the transaction. - -:::note - -After each successful transfer of a compressed NFT, the `leafDelegate` should -reset to an empty value. Meaning the specific asset will not have delegated -authority to an address other than its owner. - -::: - -And once confirmed by the cluster, we will have successfully transferred a -compressed NFT. - -## Example code repository - -You can find an example code repository for this developer guide on the Solana -Developers GitHub: https://github.com/solana-developers/compressed-nfts diff --git a/docs/developing/programming-model/overview.md b/docs/developing/programming-model/overview.md deleted file mode 100644 index 43375b529..000000000 --- a/docs/developing/programming-model/overview.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Overview" ---- - -An [app](terminology.md#app) interacts with a Solana cluster by sending it -[transactions](transactions.md) with one or more -[instructions](transactions.md#instructions). The Solana [runtime](runtime.md) -passes those instructions to [programs](terminology.md#program) deployed by app -developers beforehand. An instruction might, for example, tell a program to -transfer [lamports](terminology.md#lamport) from one [account](accounts.md) to -another or create an interactive contract that governs how lamports are -transferred. Instructions are executed sequentially and atomically for each -transaction. If any instruction is invalid, all account changes in the -transaction are discarded. - -To start developing immediately you can build, deploy, and run one of the -[examples](developing/on-chain-programs/examples.md). diff --git a/docs/inflation/adjusted_staking_yield.md b/docs/economics/inflation/_adjusted_staking_yield.md similarity index 93% rename from docs/inflation/adjusted_staking_yield.md rename to docs/economics/inflation/_adjusted_staking_yield.md index 77103ddf2..56925bf4a 100644 --- a/docs/inflation/adjusted_staking_yield.md +++ b/docs/economics/inflation/_adjusted_staking_yield.md @@ -20,7 +20,7 @@ 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. -![](/img/p_ex_staked_supply_w_range_initial_stake.png) +![Graph of example growth of staked supply](/assets/docs/economics/example_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 @@ -76,7 +76,7 @@ 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) +![Graph of an example dilution of unstaked SOL](/assets/docs/economics/example_unstaked_dilution.png) ### Estimated Adjusted Staked Yield @@ -125,7 +125,7 @@ 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) +![Graph of example adjusted staking yields](/assets/docs/economics/example_adjusted_staking_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 @@ -158,7 +158,7 @@ staked. As shown above, the proportion of total tokens staked changes over time (i.e. $P_s = P_s(t)$ due to the re-staking of inflation issuance thus we see relative dilution grow over time as: -![p_ex_relative_dilution](/img/p_ex_relative_dilution.png) +![Graph of example relative un-staked vs staked SOL dilution](/assets/docs/economics/example_relative_dilution.png) 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 diff --git a/docs/inflation/inflation_schedule.md b/docs/economics/inflation/inflation_schedule.md similarity index 85% rename from docs/inflation/inflation_schedule.md rename to docs/economics/inflation/inflation_schedule.md index 1e4d97892..d71ef731e 100644 --- a/docs/inflation/inflation_schedule.md +++ b/docs/economics/inflation/inflation_schedule.md @@ -1,5 +1,6 @@ --- -title: Solana's Proposed Inflation Schedule +sidebarLabel: Proposed Inflation Schedule +title: Proposed Inflation Schedule --- As mentioned above, the network's _Inflation Schedule_ is uniquely described by @@ -33,9 +34,9 @@ Based on these considerations and the community discussions following the initial design, the Solana Foundation proposes the following Inflation Schedule parameters: -- Initial Inflation Rate: $8\%$ -- Disinflation Rate: $-15\%$ -- Long-term Inflation Rate: $1.5\%$ +- Initial Inflation Rate: 8% +- Disinflation 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 @@ -45,12 +46,12 @@ 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) +![Example proposed inflation schedule graph](/assets/docs/economics/proposed_inflation_schedule.png) -In the above graph we see the annual inflation rate [$\%$] over time, given the -inflation parameters proposed above. +In the above graph we see the annual inflation rate percentage over time, given +the inflation parameters proposed above. -![](/img/p_total_supply.png) +![Example proposed total supply graph](/assets/docs/economics/proposed_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 @@ -62,17 +63,17 @@ 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_: -$$ + 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 +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) +![Example staked yields graph](/assets/docs/economics/example_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 diff --git a/docs/inflation/terminology.md b/docs/economics/inflation/terminology.md similarity index 98% rename from docs/inflation/terminology.md rename to docs/economics/inflation/terminology.md index 24ffb19dc..56b1c8154 100644 --- a/docs/inflation/terminology.md +++ b/docs/economics/inflation/terminology.md @@ -1,5 +1,6 @@ --- -title: Terminology +sidebarLabel: Inflation Terminology +title: Inflation Related Terminology --- Many terms are thrown around when discussing inflation and the related @@ -79,14 +80,14 @@ currently $10\%$ per year"). fraction of the _Total Current Supply_ that is staked at any given time. The explicit relationship is given by: -$$ + ### Token Dilution [%] diff --git a/docs/staking.md b/docs/economics/staking/index.md similarity index 90% rename from docs/staking.md rename to docs/economics/staking/index.md index 003c9252b..394dd08df 100644 --- a/docs/staking.md +++ b/docs/economics/staking/index.md @@ -1,4 +1,5 @@ --- +sidebarLabel: Staking title: Staking on Solana --- @@ -7,7 +8,8 @@ terms with regards to balance of SOL. This document makes no suggestion as to the monetary value of SOL at any time._ By staking your SOL tokens, you help secure the network and -[earn rewards](implemented-proposals/staking-rewards.md) while doing so. +[earn rewards](https://docs.solanalabs.com/implemented-proposals/staking-rewards) +while doing so. You can stake by delegating your tokens to validators who process transactions and run the network. @@ -41,7 +43,7 @@ validator 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 be found -[here](proposals/optimistic-confirmation-and-slashing.md#slashing-roadmap). +[here](https://docs.solanalabs.com/proposals/optimistic-confirmation-and-slashing#slashing-roadmap). Rewards and slashing align validator and token holder interests which helps keep the network secure, robust and performant. @@ -61,7 +63,7 @@ your favorite wallet's maintainers regarding status - 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). + [Staking commands using the Solana Command Line Tools](https://docs.solanalabs.com/cli/examples/delegate-stake). #### Create a Stake Account @@ -96,4 +98,5 @@ Follow the wallet's instructions for delegating your to your chosen validator. ## Stake Account Details For more information about the operations and permissions associated with a -stake account, please see [Stake Accounts](staking/stake-accounts.md) +stake account, please see +[Stake Accounts](/docs/economics/staking/stake-accounts.md) diff --git a/docs/staking/stake-accounts.md b/docs/economics/staking/stake-accounts.md similarity index 91% rename from docs/staking/stake-accounts.md rename to docs/economics/staking/stake-accounts.md index 48b7ba854..1e8d9d5cc 100644 --- a/docs/staking/stake-accounts.md +++ b/docs/economics/staking/stake-accounts.md @@ -1,5 +1,6 @@ --- -title: Stake Account Structure +sidebarLabel: Stake Accounts +title: Stake Accounts --- A stake account on Solana can be used to delegate tokens to validators on the @@ -23,7 +24,7 @@ necessarily have 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 a stake account using the command line tools](../cli/delegate-stake.md#create-a-stake-account). +[creating a stake account using the command line tools](https://docs.solanalabs.com/cli/examples/delegate-stake#create-a-stake-account). A new keypair file is created first only to ensure that the stake account's address is new and unique. @@ -106,9 +107,9 @@ effective stake. When a stake account is delegated, or a delegation is deactivated, the operation does not take effect immediately. -A delegation or deactivation takes several [epochs](../terminology.md#epoch) to -complete, with a fraction of the delegation becoming active or inactive at each -epoch boundary after the transaction containing the instructions has been +A delegation or deactivation takes several [epochs](/docs/terminology.md#epoch) +to complete, with a fraction of the delegation becoming active or inactive at +each epoch boundary after the transaction containing the instructions has been submitted to the cluster. There is also a limit on how much total stake can become delegated or @@ -116,7 +117,7 @@ deactivated in a single epoch, to prevent large sudden changes in stake across the network as a whole. Since warmup and cooldown are dependent on the behavior of other network participants, their exact duration is difficult to predict. Details on the warmup and cooldown timing can be found -[here](../cluster/stake-delegation-and-rewards.md#stake-warmup-cooldown-withdrawal). +[here](https://docs.solanalabs.com/consensus/stake-delegation-and-rewards#stake-warmup-cooldown-withdrawal). #### Lockups diff --git a/docs/staking/stake-programming.md b/docs/economics/staking/stake-programming.md similarity index 100% rename from docs/staking/stake-programming.md rename to docs/economics/staking/stake-programming.md diff --git a/docs/getstarted/hello-world.md b/docs/getstarted/hello-world.md deleted file mode 100644 index a11855717..000000000 --- a/docs/getstarted/hello-world.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: "Hello World Quickstart Guide" -description: - 'This "hello world" quickstart guide will demonstrate how to setup, build, and - deploy your first Solana program in your browser with Solana Playground.' -keywords: - - playground - - solana pg - - on chain - - rust - - native program - - tutorial - - intro to solana development - - blockchain developer - - blockchain tutorial - - web3 developer ---- - -For this "hello world" quickstart guide, we will use -[Solana Playground](https://beta.solpg.io), a browser based IDE to develop and -deploy our Solana program. To use it, you do **NOT** have to install any -software on your computer. Simply open Solana Playground in your browser of -choice, and you are ready to write and deploy Solana programs. - -## What you will learn - -- How to get started with Solana Playground -- How to create a Solana wallet on Playground -- How to program a basic Solana program in Rust -- How to build and deploy a Solana Rust program -- How to interact with your on chain program using JavaScript - -## Using Solana Playground - -[Solana Playground](https://beta.solpg.io) is browser based application that -will let you write, build, and deploy on chain Solana programs. All from your -browser. No installation needed. - -It is a great developer resource for getting started with Solana development, -especially on Windows. - -### Import our example project - -In a new tab in your browser, open our example "_Hello World_" -[project on Solana Playground](https://beta.solpg.io/6314a69688a7fca897ad7d1d). - -Next, import the project into your local workspace by clicking the "**Import**" -icon and naming your project `hello_world`. - -![Import the get started Solana program on Solana Playground](/img/quickstarts/solana-get-started-import-on-playground.png) - -> If you do **not** import the program into **your** Solana Playground, then you -> will **not** be able to make changes to the code. But you **will** still be -> able to build and deploy the code to a Solana cluster. - -### Create a Playground wallet - -Normally with [local development](./local.md), you will need to create a file -system wallet for use with the Solana CLI. But with the Solana Playground, you -only need to click a few buttons to create a browser based wallet. - -:::caution Your _Playground Wallet_ will be saved in your browser's local -storage. Clearing your browser cache will remove your saved wallet. When -creating a new wallet, you will have the option to save a local copy of your -wallet's keypair file. ::: - -Click on the red status indicator button at the bottom left of the screen, -(optionally) save your wallet's keypair file to your computer for backup, then -click "**Continue**". - -After your Playground Wallet is created, you will notice the bottom of the -window now states your wallet's address, your SOL balance, and the Solana -cluster you are connected to (Devnet is usually the default/recommended, but a -"localhost" [test validator](./local.md) is also acceptable). - -## Create a Solana program - -The code for your Rust based Solana program will live in your `src/lib.rs` file. -Inside `src/lib.rs` you will be able to import your Rust crates and define your -logic. Open your `src/lib.rs` file within Solana Playground. - -### Import the `solana_program` crate - -At the top of `lib.rs`, we import the `solana-program` crate and bring our -needed items into the local namespace: - -```rust -use solana_program::{ - account_info::AccountInfo, - entrypoint, - entrypoint::ProgramResult, - pubkey::Pubkey, - msg, -}; -``` - -### Write your program logic - -Every Solana program must define an `entrypoint` that tells the Solana runtime -where to start executing your on chain code. Your program's -[entrypoint](../developing/on-chain-programs/developing-rust#program-entrypoint) -should provide a public function named `process_instruction`: - -```rust -// declare and export the program's entrypoint -entrypoint!(process_instruction); - -// program entrypoint's implementation -pub fn process_instruction( - program_id: &Pubkey, - accounts: &[AccountInfo], - instruction_data: &[u8] -) -> ProgramResult { - // log a message to the blockchain - msg!("Hello, world!"); - - // gracefully exit the program - Ok(()) -} -``` - -Every on chain program should return the `Ok` -[result enum](https://doc.rust-lang.org/std/result/) with a value of `()`. This -tells the Solana runtime that your program executed successfully without errors. - -Our program above will simply -[log a message](../developing/on-chain-programs/debugging#logging) of "_Hello, -world!_" to the blockchain cluster, then gracefully exit with `Ok(())`. - -### Build your program - -On the left sidebar, select the "**Build & Deploy**" tab. Next, click the -"Build" button. - -If you look at the Playground's terminal, you should see your Solana program -begin to compile. Once complete, you will see a success message. - -![Viewing a successful build of your Rust based program](/img/quickstarts/solana-get-started-successful-build.png) - -:::caution You may receive _warning_ when your program is compiled due to unused -variables. Don't worry, these warning will not affect your build. They are due -to our very simple program not using all the variables we declared in the -`process_instruction` function. ::: - -### Deploy your program - -You can click the "Deploy" button to deploy your first program to the Solana -blockchain. Specifically to your selected cluster (e.g. Devnet, Testnet, etc). - -After each deployment, you will see your Playground Wallet balance change. By -default, Solana Playground will automatically request SOL airdrops on your -behalf to ensure your wallet has enough SOL to cover the cost of deployment. - -> Note: If you need more SOL, you can airdrop more by typing airdrop command in -> the playground terminal: - -```sh -solana airdrop 2 -``` - -![Build and deploy your Solana program to the blockchain](/img/quickstarts/solana-get-started-build-and-deploy.png) - -### Find your program id - -When executing a program using -[web3.js](../developing/clients/javascript-reference.md) or from -[another Solana program](../developing/programming-model/calling-between-programs.md), -you will need to provide the `program id` (aka public address of your program). - -Inside Solana Playground's **Build & Deploy** sidebar, you can find your -`program id` under the **Program Credentials** dropdown. - -#### Congratulations! - -You have successfully setup, built, and deployed a Solana program using the Rust -language directly in your browser. Next, we will demonstrate how to interact -with your on chain program. - -## Interact with your on chain program - -Once you have successfully deployed a Solana program to the blockchain, you will -want to be able to interact with that program. - -Like most developers creating dApps and websites, we will interact with our on -chain program using JavaScript. Specifically, will use the open source -[NPM package](https://www.npmjs.com/package/@solana/web3.js) `@solana/web3.js` -to aid in our client application. - -:::info This web3.js package is an abstraction layer on top of the -[JSON RPC API](/api) that reduced the need for rewriting common boilerplate, -helping to simplify your client side application code. ::: - -### Initialize client - -We will be using Solana Playground for the client generation. Create a client -folder by running `run` command in the playground terminal: - -```bash -run -``` - -We have created `client` folder and a default `client.ts`. This is where we will -work for the rest of our `hello world` program. - -### Playground globals - -In playground, there are many utilities that are globally available for us to -use without installing or setting up anything. Most important ones for our -`hello world` program are `web3` for `@solana/web3.js` and `pg` for Solana -Playground utilities. - -:::info You can go over all of the available globals by pressing `CTRL+SPACE` -(or `CMD+SPACE` on macOS) inside the editor. ::: - -### Call the program - -To execute your on chain program, you must send a -[transaction](../developing/programming-model/transactions.md) to it. Each -transaction submitted to the Solana blockchain contains a listing of -instructions (and the program's that instruction will interact with). - -Here we create a new transaction and add a single `instruction` to it: - -```js -// create an empty transaction -const transaction = new web3.Transaction(); - -// add a hello world program instruction to the transaction -transaction.add( - new web3.TransactionInstruction({ - keys: [], - programId: new web3.PublicKey(pg.PROGRAM_ID), - }), -); -``` - -Each `instruction` must include all the keys involved in the operation and the -program ID we want to execute. In this example `keys` is empty because our -program only logs `hello world` and doesn't need any accounts. - -With our transaction created, we can submit it to the cluster: - -```js -// send the transaction to the Solana cluster -console.log("Sending transaction..."); -const txHash = await web3.sendAndConfirmTransaction( - pg.connection, - transaction, - [pg.wallet.keypair], -); -console.log("Transaction sent with hash:", txHash); -``` - -:::info The first signer in the signers array is the transaction fee payer by -default. We are signing with our keypair `pg.wallet.keypair`. ::: - -### Run the application - -With the client application written, you can run the code via the same `run` -command. - -Once your application completes, you will see output similar to this: - -```sh -Running client... - client.ts: - My address: GkxZRRNPfaUfL9XdYVfKF3rWjMcj5md6b6mpRoWpURwP - My balance: 5.7254472 SOL - Sending transaction... - Transaction sent with hash: 2Ra7D9JoqeNsax9HmNq6MB4qWtKPGcLwoqQ27mPYsPFh3h8wignvKB2mWZVvdzCyTnp7CEZhfg2cEpbavib9mCcq -``` - -### Get transaction logs - -We will be using `solana-cli` directly in playground to get the information -about any transaction: - -```sh -solana confirm -v -``` - -Change `` with the hash you received from calling -`hello world` program. - -You should see `Hello, world!` in the **Log Messages** section of the output. 🎉 - -#### Congratulations!!! - -You have now written a client application for your on chain program. You are now -a Solana developer! - -PS: Try to update your program's message then re-build, re-deploy, and -re-execute your program. - -## Next steps - -See the links below to learn more about writing Solana programs: - -- [Setup your local development environment](./local.md) -- [Overview of writing Solana programs](../developing/on-chain-programs/overview) -- [Learn more about developing Solana programs with Rust](../developing/on-chain-programs/developing-Rust) -- [Debugging on chain programs](../developing/on-chain-programs/debugging) diff --git a/docs/getstarted/local.md b/docs/getstarted/local.md deleted file mode 100644 index 006ce572f..000000000 --- a/docs/getstarted/local.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: "Local Development Quickstart" -description: - "This quickstart guide will demonstrate how to quickly install and setup your - local Solana development environment." -keywords: - - rust - - cargo - - toml - - program - - tutorial - - intro to solana development - - blockchain developer - - blockchain tutorial - - web3 developer ---- - -This quickstart guide will demonstrate how to quickly install and setup your -local development environment, getting you ready to start developing and -deploying Solana programs to the blockchain. - -## What you will learn - -- How to install the Solana CLI locally -- How to setup a localhost Solana cluster/validator -- How to create a Solana wallet for developing -- How to airdrop SOL tokens for your wallet - -## Install the Solana CLI - -To interact with the Solana network from your terminal, you will need to install -the [Solana CLI tool suite](./../cli/install-solana-cli-tools) on your local -system. - -
-macOS / Linux / Windows Subsystem for Linux (WSL) -Open your favourite terminal application and install the CLI by running: - -```bash -sh -c "$(curl -sSfL https://release.solana.com/stable/install)" -``` - -Depending on your system, the end of the installer messaging may prompt you to - -```bash -Please update your PATH environment variable to include the solana programs: -``` - -If you get the above message, copy and paste the recommended command below it to -update `PATH` - -Confirm you have the desired version of `solana` installed by running: - -```bash -solana --version -``` - -After a successful install, `solana-install update` may be used to easily update -the Solana software to a newer version at any time. - -
- -
-Windows - -:::caution [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) is the -recommended environment for Windows users. ::: - -- Open a Command Prompt (`cmd.exe`) as an Administrator - - - Search for Command Prompt in the Windows search bar. When the Command Prompt - app appears, right-click and select “Open as Administrator”. If you are - prompted by a pop-up window asking “Do you want to allow this app to make - changes to your device?”, click Yes. - -- Copy and paste the following command, then press Enter to download the Solana - installer into a temporary directory: - -```bash -cmd /c "curl https://release.solana.com/stable/solana-install-init-x86_64-pc-windows-msvc.exe --output C:\solana-install-tmp\solana-install-init.exe --create-dirs" -``` - -- Copy and paste the following command, then press Enter to install the latest - version of Solana. If you see a security pop-up by your system, please select - to allow the program to run. - -```bash -C:\solana-install-tmp\solana-install-init.exe stable -``` - -- When the installer is finished, press Enter. - -- Close the command prompt window and re-open a new command prompt window as a - normal user -- Confirm you have the desired version of `solana` installed by entering: - -```bash -solana --version -``` - -After a successful install, `solana-install update` may be used to easily update -the Solana software to a newer version at any time. - -
- -## Setup a localhost blockchain cluster - -The Solana CLI comes with the -[test validator](./../developing/test-validator.md) built in. This command line -tool will allow you to run a full blockchain cluster on your machine. - -```bash -solana-test-validator -``` - -> **PRO TIP:** Run the Solana test validator in a new/separate terminal window -> that will remain open. The command line program must remain running for your -> localhost cluster to remain online and ready for action. - -Configure your Solana CLI to use your localhost validator for all your future -terminal commands: - -```bash -solana config set --url localhost -``` - -At any time, you can view your current Solana CLI configuration settings: - -```bash -solana config get -``` - -## Create a file system wallet - -To deploy a program with Solana CLI, you will need a Solana wallet with SOL -tokens to pay for the cost of transactions. - -Let's create a simple file system wallet for testing: - -```bash -solana-keygen new -``` - -By default, the `solana-keygen` command will create a new file system wallet -located at `~/.config/solana/id.json`. You can manually specify the output file -location using the `--outfile /path` option. - -> **NOTE:** If you already have a file system wallet saved at the default -> location, this command will **NOT** override it (unless you explicitly force -> override using the `--force` flag). - -### Set your new wallet as default - -With your new file system wallet created, you must tell the Solana CLI to use -this wallet to deploy and take ownership of your on chain program: - -```bash -solana config set -k ~/.config/solana/id.json -``` - -## Airdrop SOL tokens to your wallet - -Once your new wallet is set as the default, you can request a free airdrop of -SOL tokens to it: - -```bash -solana airdrop 2 -``` - -> **NOTE:** The `solana airdrop` command has a limit of how many SOL tokens can -> be requested _per airdrop_ for each cluster (localhost, testnet, or devent). -> If your airdrop transaction fails, lower your airdrop request quantity and try -> again. - -You can check your current wallet's SOL balance any time: - -```bash -solana balance -``` - -## Next steps - -See the links below to learn more about writing Rust based Solana programs: - -- [Create and deploy a Solana Rust program](./rust.md) -- [Overview of writing Solana programs](../developing/on-chain-programs/overview) diff --git a/docs/getstarted/rust.md b/docs/getstarted/rust.md deleted file mode 100644 index c4dd23159..000000000 --- a/docs/getstarted/rust.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: "Rust Program Quickstart" -description: - "This quickstart guide will demonstrate how to quickly setup, build, and - deploy your first Rust based Solana program to the blockchain." -keywords: - - rust - - cargo - - toml - - program - - tutorial - - intro to solana development - - blockchain developer - - blockchain tutorial - - web3 developer ---- - -Rust is the most common programming language to write Solana programs with. This -quickstart guide will demonstrate how to quickly setup, build, and deploy your -first Rust based Solana program to the blockchain. - -> **NOTE: ** This guide uses the Solana CLI and assumes you have setup your -> local development environment. Checkout our -> [local development quickstart guide](./local.md) here to quickly get setup. - -## What you will learn - -- How to install the Rust language locally -- How to initialize a new Solana Rust program -- How to code a basic Solana program in Rust -- How to build and deploy your Rust program - -## Install Rust and Cargo - -To be able to compile Rust based Solana programs, install the Rust language and -Cargo (the Rust package manager) using [Rustup](https://rustup.rs/): - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -## Run your localhost validator - -The Solana CLI comes with the [test validator](../developing/test-validator.md) -built in. This command line tool will allow you to run a full blockchain cluster -on your machine. - -```bash -solana-test-validator -``` - -> **PRO TIP:** Run the Solana test validator in a new/separate terminal window -> that will remain open. This command line program must remain running for your -> localhost validator to remain online and ready for action. - -Configure your Solana CLI to use your localhost validator for all your future -terminal commands and Solana program deployment: - -```bash -solana config set --url localhost -``` - -## Create a new Rust library with Cargo - -Solana programs written in Rust are _libraries_ which are compiled to -[BPF bytecode](../developing/on-chain-programs/faq.md#berkeley-packet-filter-bpf) -and saved in the `.so` format. - -Initialize a new Rust library named `hello_world` via the Cargo command line: - -```bash -cargo init hello_world --lib -cd hello_world -``` - -Add the `solana-program` crate to your new Rust library: - -```bash -cargo add solana-program -``` - -Open your `Cargo.toml` file and add these required Rust library configuration -settings, updating your project name as appropriate: - -```toml -[lib] -name = "hello_world" -crate-type = ["cdylib", "lib"] -``` - -## Create your first Solana program - -The code for your Rust based Solana program will live in your `src/lib.rs` file. -Inside `src/lib.rs` you will be able to import your Rust crates and define your -logic. Open your `src/lib.rs` file in your favorite editor. - -At the top of `lib.rs`, import the `solana-program` crate and bring our needed -items into the local namespace: - -```rust -use solana_program::{ - account_info::AccountInfo, - entrypoint, - entrypoint::ProgramResult, - pubkey::Pubkey, - msg, -}; -``` - -Every Solana program must define an `entrypoint` that tells the Solana runtime -where to start executing your on chain code. Your program's -[entrypoint](../developing/on-chain-programs/developing-rust#program-entrypoint) -should provide a public function named `process_instruction`: - -```rust -// declare and export the program's entrypoint -entrypoint!(process_instruction); - -// program entrypoint's implementation -pub fn process_instruction( - program_id: &Pubkey, - accounts: &[AccountInfo], - instruction_data: &[u8] -) -> ProgramResult { - // log a message to the blockchain - msg!("Hello, world!"); - - // gracefully exit the program - Ok(()) -} -``` - -Every on chain program should return the `Ok` -[result enum](https://doc.rust-lang.org/std/result/) with a value of `()`. This -tells the Solana runtime that your program executed successfully without errors. - -This program above will simply -[log a message](../developing/on-chain-programs/debugging#logging) of "_Hello, -world!_" to the blockchain cluster, then gracefully exit with `Ok(())`. - -## Build your Rust program - -Inside a terminal window, you can build your Solana Rust program by running in -the root of your project (i.e. the directory with your `Cargo.toml` file): - -```bash -cargo build-bpf -``` - -> **NOTE:** After each time you build your Solana program, the above command -> will output the build path of your compiled program's `.so` file and the -> default keyfile that will be used for the program's address. `cargo build-bpf` -> installs the toolchain from the currently installed solana CLI tools. You may -> need to upgrade those tools if you encounter any version incompatibilities. - -## Deploy your Solana program - -Using the Solana CLI, you can deploy your program to your currently selected -cluster: - -```bash -solana program deploy ./target/deploy/hello_world.so -``` - -Once your Solana program has been deployed (and the transaction -[finalized](../cluster/commitments.md)), the above command will output your -program's public address (aka its "program id"). - -```bash -# example output -Program Id: EFH95fWg49vkFNbAdw9vy75tM7sWZ2hQbTTUmuACGip3 -``` - -#### Congratulations! - -You have successfully setup, built, and deployed a Solana program using the Rust -language. - -> PS: Check your Solana wallet's balance again after you deployed. See how much -> SOL it cost to deploy your simple program? - -## Next steps - -See the links below to learn more about writing Rust based Solana programs: - -- [Overview of writing Solana programs](../developing/on-chain-programs/overview) -- [Learn more about developing Solana programs with Rust](../developing/on-chain-programs/developing-Rust) -- [Debugging on chain programs](../developing/on-chain-programs/debugging) diff --git a/docs/index.md b/docs/index.md index fc8949ec1..c86f83b12 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,12 @@ --- -title: Home -sidebarLabel: Home +sidebarSortOrder: 0 +title: Solana Documentation +seoTitle: Learn how the Solana blockchain works description: "Solana is a high performance network that is utilized for a range of use cases, \ including finance, NFTs, payments, and gaming." -# displayed_sidebar: introductionSidebar --- -# Solana Documentation - Solana is a blockchain built for mass adoption. It's a high performance network that is utilized for a range of use cases, including finance, NFTs, payments, and gaming. Solana operates as a single global state machine, and is open, @@ -18,48 +16,42 @@ interoperable and decentralized. Dive right into Solana to start building or setup your tooling. -- [Setup local environment](/cli) - Install the Solana CLI to get your local - development environment setup -- [Hello World in your browser](getstarted/hello-world) - Build and deploy your - first on-chain Solana program, directly in your browser using Solana - Playground +- [Setup local environment](/content/guides/getstarted/setup-local-development.md) - + Install the Solana CLI to get your local development environment setup +- [Hello World in your browser](/content/guides/getstarted/hello-world-in-your-browser.md) - + Build and deploy your first on-chain Solana program, directly in your browser + using Solana Playground ## Start learning Build a strong understanding of the core concepts that make Solana different from other blockchains. -- [Transactions](./developing/programming-model/transactions) - Collection of - instructions for the blockchain to execute -- [Accounts](./developing/programming-model/accounts) - Data and state storage - mechanism for Solana -- [Programs](./developing/intro/programs) - The executable code used to perform +- [Transactions](/docs/core/transactions.md) - Collection of instructions for + the blockchain to execute +- [Accounts](/docs/core/accounts.md) - Data and state storage mechanism for + Solana +- [Programs](/docs/core/programs.md) - The executable code used to perform actions on the blockchain -- [Cross-Program Invocation](./developing/programming-model/calling-between-programs) - - Core of the "composability" of Solana, this is how programs can "call" each - other. +- [Cross-Program Invocation](/docs/core/cpi.md) - Core of the "composability" of + Solana, this is how programs can "call" each other. ## Understanding the architecture Get to know the underlying architecture of how the proof-of-stake blockchain works. -- [Validators](./validator/anatomy) - the individual nodes that are the backbone - of the network -- [Clusters](./cluster/overview) - a collection of validators that work together - for consensus +- [Validators](https://docs.solanalabs.com/validator/anatomy) - the individual + nodes that are the backbone of the network +- [Clusters](https://docs.solanalabs.com/clusters/overview) - a collection of + validators that work together for consensus ## Running a validator Explore what it takes to operate a Solana validator and help secure the network. -- [System requirements](./running-validator/validator-reqs) - Recommended - hardware requirements and expected SOL needed to operate a validator -- [Quick start guide](./validator/get-started/setup-a-validator) - Setup a - validator and get connected to a cluster for the first time - -## Learn more - -import HomeCtaLinks from "../components/HomeCtaLinks"; - - +- [System requirements](https://docs.solanalabs.com/operations/requirements) - + Recommended hardware requirements and expected SOL needed to operate a + validator +- [Quick start guide](https://docs.solanalabs.com/operations/setup-a-validator) - + Setup a validator and get connected to a cluster for the first time diff --git a/docs/getstarted/overview.md b/docs/intro/dev.md similarity index 84% rename from docs/getstarted/overview.md rename to docs/intro/dev.md index ddc0aa94f..8c2f031d8 100644 --- a/docs/getstarted/overview.md +++ b/docs/intro/dev.md @@ -1,7 +1,10 @@ --- +sidebarLabel: Intro to Development title: "Introduction to Solana Development" description: "Learn about the basic development concepts of the Solana blockchain." +# sort order is set really high to ensure this doc is listed last +sidebarSortOrder: 9999 keywords: - accounts - transactions @@ -41,7 +44,7 @@ Here's a high level representation of this. It’s important to note that this i an oversimplification of the Solana network for the purposes of learning in an easy-to-understand way. -![Solana developer workflows program-client model](/img/quickstarts/solana-overview-client-program.png) +![Solana developer workflows program-client model](/assets/docs/quickstarts/solana-overview-client-program.png) ### Program development @@ -50,8 +53,8 @@ and C++ programs directly to the blockchain. Once these programs are deployed, anyone who knows how to communicate with them can use them. You can communicate with these programs by writing dApps with any of the -available client SDKs (or the [CLI](../cli.md)), all of which use the -[JSON RPC API](../api) under the hood. +available client SDKs (or the [CLI](https://docs.solanalabs.com/cli)), all of +which use the [JSON RPC API](/docs/rpc/index.mdx) under the hood. ### Client development @@ -60,7 +63,7 @@ communicate with deployed programs. Your apps can submit transactions with instructions to these programs via a client SDK to create a wide variety of applications such as wallets, exchanges and more. The most popular apps are browser extension wallets and web apps, but you can build mobile/desktop apps or -anything that can communicate with the JSON RPC API. +anything that can communicate with the [JSON RPC API](/docs/rpc/index.mdx). These two pieces work together to create a network of dApps and programs that can communicate with each other to update the state and query the blockchain. @@ -87,7 +90,7 @@ them and update the state of the blockchain. Think of it like a write command that can be rejected if certain conditions aren't met. Here's a visual representation of what a transaction contains: -![Visual layout of a transaction](/img/transaction.svg) +![Visual layout of a transaction](/assets/docs/transaction.svg) - Signatures: An array of digital signatures from the transaction's signers. - Message: The actual instructions that the transaction is issuing to the @@ -104,8 +107,7 @@ Here's a visual representation of what a transaction contains: Transactions can be created and signed using clients via SDKs, or even on-chain programs. -You can learn more about transactions -[here](../developing/programming-model/transactions.md). +You can learn more about transactions [here](/docs/core/transactions.md). ### Instructions @@ -123,7 +125,7 @@ Here's what an instruction looks like: | `Data` | Input data provided to the program as additional information or parameters in the format of a byte array | You can read more about instructions -[here](../developing/programming-model/transactions#instructions). +[here](/docs/core/transactions.md#instructions). ### Transaction Fees @@ -138,12 +140,13 @@ Transactions fees are calculated based on two main parts: - a statically set base fee per signature, and - the computational resources used during the transaction, measured in - "[_compute units_](../terminology.md#compute-units)" + "[_compute units_](/docs/terminology.md#compute-units)" The more work a transaction requires, the more compute units it will use, and the more it will cost. -You can read more about transaction fees [here](../transaction_fees.md). +You can read more about transaction fees +[here](/docs/core/transactions/fees.md). ## Accounts @@ -170,8 +173,7 @@ account doesn't have enough tokens to cover the rent, it will be removed. However, if the account does hold enough tokens to cover the rent for two years, it's considered "rent-exempt" and won't be deleted. -You can read more about accounts -[here](../developing/programming-model/accounts.md). +You can read more about accounts [here](/docs/core/accounts.md). ## Programs @@ -184,7 +186,7 @@ programs are stateless: any data they interact with is stored in separate accounts that are passed in via instructions. There are two sets of programs that are maintained by the Solana Labs team: -[Native Programs](../developing/runtime-facilities/programs.md) and the +[Native Programs](https://docs.solanalabs.com/runtime/programs) and the [Solana Program Library (SPL)](https://spl.solana.com/). These serve as core building blocks for on-chain interactions. Native programs are used for core blockchain functionality like creating new accounts, assigning ownership, @@ -202,7 +204,7 @@ Developers most commonly write programs in Rust using frameworks such as Anchor. However, programs can be written in any language that compiles to BPF, including C++ and Move. -You can learn more about programs [here](../developing/intro/programs.md). +You can learn more about programs [here](/docs/core/programs.md). ## Testing and developing environments @@ -212,9 +214,10 @@ The easiest and quickest way to get started is the [Solana Playground](https://beta.solpg.io) - a browser based IDE that allows you to write, deploy, and test programs. -The most popular setup is [local development](local.md) with a local validator -that you run on your machine - this allows you to test your programs locally -before deploying them to any network. +The most popular setup is +[local development](/content/guides/getstarted/setup-local-development.md) with +a local validator that you run on your machine - this allows you to test your +programs locally before deploying them to any network. In each environment, you'll be using one of three networks: @@ -228,13 +231,14 @@ In each environment, you'll be using one of three networks: Devnet has a faucet that allows you to get free SOL to test with. It costs $0 to do development on Solana. -Check out the [clusters page](../clusters.md) for more information on these. +Check out the [clusters page](/docs/core/clusters.md) for more information on +these. ## Next steps You're now ready to get started building on Solana! -- [Deploy your first Solana program in the browser](./hello-world.md) -- [Setup your local development environment](./local.md) -- [Get started building programs locally with Rust](./rust.md) -- [Overview of writing Solana programs](../developing/on-chain-programs/overview) +- [Deploy your first Solana program in the browser](/content/guides/getstarted/hello-world-in-your-browser.md) +- [Setup your local development environment](/content/guides/getstarted/setup-local-development.md) +- [Get started building programs locally with Rust](/content/guides/getstarted/local-rust-hello-world.md) +- [Overview of writing Solana programs](/docs/programs/index.md) diff --git a/docs/economics_overview.md b/docs/intro/economics.md similarity index 68% rename from docs/economics_overview.md rename to docs/intro/economics.md index 90e002a37..4f8bf7d04 100644 --- a/docs/economics_overview.md +++ b/docs/intro/economics.md @@ -1,4 +1,5 @@ --- +sidebarLabel: Economics title: Solana Economics Overview --- @@ -32,16 +33,17 @@ protection through partial burning of each transaction fee is also discussed below. First, an overview of the inflation design is presented. This section starts -with defining and clarifying [Terminology](inflation/terminology.md) commonly -used subsequently in the discussion of inflation and the related components. +with defining and clarifying +[Terminology](/docs/economics/inflation/terminology.md) commonly used +subsequently in the discussion of inflation and the related components. Following that, we outline Solana's proposed -[Inflation Schedule](inflation/inflation_schedule.md), i.e. the specific -parameters that uniquely parameterize the protocol-driven inflationary issuance -over time. Next is a brief section on -[Adjusted Staking Yield](inflation/adjusted_staking_yield.md), and how token -dilution might influence staking behavior. +[Inflation Schedule](/docs/economics/inflation/inflation_schedule.md), i.e. the +specific parameters that uniquely parameterize the protocol-driven inflationary +issuance over time. Next is a brief section on +[Adjusted Staking Yield](/docs/economics/inflation/_adjusted_staking_yield.md), +and how token dilution might influence staking behavior. -An overview of [Transaction Fees](transaction_fees.md) on Solana is followed by -a discussion of [Storage Rent Economics](storage_rent_economics.md) in which we -describe an implementation of storage rent to account for the externality costs -of maintaining the active state of the ledger. +An overview of [Transaction Fees](/docs/core/transactions/fees.md) on Solana is +followed by a discussion of [Storage Rent Economics](/docs/intro/economics.md) +in which we describe an implementation of storage rent to account for the +externality costs of maintaining the active state of the ledger. diff --git a/docs/history.md b/docs/intro/history.md similarity index 96% rename from docs/history.md rename to docs/intro/history.md index a08c70f5d..6ab645fa6 100644 --- a/docs/history.md +++ b/docs/intro/history.md @@ -1,5 +1,6 @@ --- -title: History +sidebarLabel: History +title: Brief History of Solana --- In November of 2017, Anatoly Yakovenko published a whitepaper describing Proof @@ -33,7 +34,7 @@ Anatoly called the project Loom. On February 13th of 2018, Greg began prototyping the first open source implementation of Anatoly's whitepaper. The project was published to GitHub -under the name Silk in the loomprotocol organization. On February 28th, Greg +under the name Silk in the `loomprotocol` organization. On February 28th, Greg made his first release, demonstrating 10 thousand signed transactions could be verified and processed in just over half a second. Shortly after, another former Qualcomm cohort, Stephen Akridge, demonstrated throughput could be massively diff --git a/docs/introduction.md b/docs/intro/index.md similarity index 93% rename from docs/introduction.md rename to docs/intro/index.md index 486075686..57aebcf02 100644 --- a/docs/introduction.md +++ b/docs/intro/index.md @@ -1,5 +1,6 @@ --- title: Introduction +sidebarSortOrder: 1 --- ## What is Solana? @@ -46,10 +47,10 @@ blockchain! Furthermore, and much to our surprise, it can be implemented using a mechanism that has existed in Bitcoin since day one. The Bitcoin feature is called -nLocktime and it can be used to postdate transactions using block height instead -of a timestamp. As a Bitcoin client, you would use block height instead of a -timestamp if you don't rely upon the network. Block height turns out to be an -instance of what's being called a Verifiable Delay Function in cryptography +`nLocktime` and it can be used to postdate transactions using block height +instead of a timestamp. As a Bitcoin client, you would use block height instead +of a timestamp if you don't rely upon the network. Block height turns out to be +an instance of what's being called a Verifiable Delay Function in cryptography circles. It's a cryptographically secure way to say time has passed. In Solana, we use a far more granular verifiable delay function, a SHA 256 hash chain, to checkpoint the ledger and coordinate consensus. With it, we implement Optimistic @@ -94,7 +95,7 @@ launched it. A SOL is the name of Solana's native token, which can be passed to nodes in a Solana cluster in exchange for running an on-chain program or validating its -output. The system may perform micropayments of fractional SOLs, which are +output. The system may perform micro-payments of fractional SOLs, which are called _lamports_. They are named in honor of Solana's biggest technical influence, [Leslie Lamport](https://en.wikipedia.org/wiki/Leslie_Lamport). A lamport has a value of 0.000000001 SOL. diff --git a/docs/storage_rent_economics.md b/docs/intro/rent.md similarity index 95% rename from docs/storage_rent_economics.md rename to docs/intro/rent.md index eac4b8314..690dbfc3e 100644 --- a/docs/storage_rent_economics.md +++ b/docs/intro/rent.md @@ -1,4 +1,5 @@ --- +sidebarLabel: Rent title: Storage Rent Economics --- @@ -28,7 +29,7 @@ charges rent on a per-epoch basis, in credit for the next epoch. This rent is deducted at a rate specified in genesis, in lamports per kilobyte-year. For information on the technical implementation details of this design, see the -[Rent](implemented-proposals/rent.md) section. +[Rent](https://docs.solanalabs.com/implemented-proposals/rent) section. **Note:** New accounts now **are required** to be initialized with enough lamports to be rent exempt. Additionally, transactions that leave an account's diff --git a/docs/transaction_fees.md b/docs/intro/transaction_fees.md similarity index 81% rename from docs/transaction_fees.md rename to docs/intro/transaction_fees.md index e3a65fb93..1109e4b82 100644 --- a/docs/transaction_fees.md +++ b/docs/intro/transaction_fees.md @@ -15,8 +15,8 @@ keywords: - affordable blockchain --- -The small fees paid to process [instructions](./terminology.md#instruction) on -the Solana blockchain are known as "_transaction fees_". +The small fees paid to process [instructions](/docs/terminology.md#instruction) +on the Solana blockchain are known as "_transaction fees_". As each transaction (which contains one or more instructions) is sent through the network, it gets processed by the current leader validation-client. Once @@ -25,12 +25,10 @@ network to help support the [economic design](#economic-design) of the Solana blockchain. > **NOTE:** Transaction fees are different from -> [account rent](./terminology.md#rent)! While transaction fees are paid to +> [account rent](/docs/terminology.md#rent)! While transaction fees are paid to > process instructions on the Solana network, rent is paid to store data on the -> blockchain. - -> You can learn more about rent here: -> [What is rent?](./developing/intro/rent.md) +> blockchain. You can learn more about rent here: +> [What is rent?](/docs/core/rent.md) ## Why pay transaction fees? @@ -57,10 +55,10 @@ The same is true on Solana. Specifically: - A fixed proportion (initially 50%) of each transaction fee is _burned_ (destroyed), with the remaining going to the current - [leader](./terminology.md#leader) processing the transaction. + [leader](/docs/terminology.md#leader) processing the transaction. - A scheduled global inflation rate provides a source for - [rewards](./implemented-proposals/staking-rewards.md) distributed to - [Solana Validators](../src/running-validator.md). + [rewards](https://docs.solanalabs.com/implemented-proposals/staking-rewards) + distributed to [Solana Validators](https://docs.solanalabs.com/operations). ### Why burn some fees? @@ -71,12 +69,13 @@ completely burned, leaders are still incentivized to include as many transactions as possible in their slots. Burnt fees can also help prevent malicious validators from censoring -transactions by being considered in [fork](./terminology.md#fork) selection. +transactions by being considered in [fork](/docs/terminology.md#fork) selection. #### Example of an attack: -In the case of a [Proof of History (PoH)](./terminology.md#proof-of-history-poh) -fork with a malicious, censoring leader: +In the case of a +[Proof of History (PoH)](/docs/terminology.md#proof-of-history-poh) fork with a +malicious, censoring leader: - due to the fees lost from censoring, we would expect the total fees burned to be **_less than_** a comparable honest fork @@ -90,11 +89,11 @@ Transactions fees are calculated based on two main parts: - a statically set base fee per signature, and - the computational resources used during the transaction, measured in - "[_compute units_](./terminology.md#compute-units)" + "[_compute units_](/docs/terminology.md#compute-units)" Since each transaction may require a different amount of computational resources, they are alloted a maximum number of _compute units_ per transaction -known as the "[_compute budget_](./terminology.md#compute-budget)". +known as the "[_compute budget_](/docs/terminology.md#compute-budget)". The execution of each instruction within a transaction consumes a different number of _compute units_. After the maximum number of _compute units_ has been @@ -102,21 +101,20 @@ consumed (aka compute budget exhaustion), the runtime will halt the transaction and return an error. This results in a failed transaction. > **Learn more:** compute units and the -> [Compute Budget](./developing/programming-model/runtime#compute-budget) in the -> Runtime and [requesting a fee estimate](../api/http#getfeeformessage) from the -> RPC. +> [Compute Budget](/docs/core/runtime.md#compute-budget) in the Runtime and +> [requesting a fee estimate](/docs/rpc/http/getFeeForMessage.mdx) from the RPC. ## Prioritization fee A Solana transaction can include an **optional** fee to prioritize itself against others known as a -"_[prioritization fee](./terminology.md#prioritization-fee)_". Paying this +"_[prioritization fee](/docs/terminology.md#prioritization-fee)_". Paying this additional fee helps boost how a transaction is prioritized against others, resulting in faster execution times. ### How the prioritization fee is calculated -A transaction's [prioritization fee](./terminology.md#prioritization-fee) is +A transaction's [prioritization fee](/docs/terminology.md#prioritization-fee) is calculated by multiplying the maximum number of **_compute units_** by the **_compute unit price_** (measured in _micro-lamports_). @@ -124,9 +122,9 @@ Each transaction can set the maximum number of compute units it is allowed to consume and the compute unit price by including a `SetComputeUnitLimit` and `SetComputeUnitPrice` compute budget instruction respectively. -:::info -[Compute Budget instructions](https://github.com/solana-labs/solana/blob/master/sdk/src/compute_budget.rs) -do **not** require any accounts. ::: +> Note: Unlike other instructions inside a Solana transaction, +> [Compute Budget instructions](https://github.com/solana-labs/solana/blob/master/sdk/src/compute_budget.rs) +> do **NOT** require any accounts. If no `SetComputeUnitLimit` instruction is provided, the limit will be calculated as the product of the number of instructions in the transaction and @@ -148,10 +146,10 @@ functions. Each of these instructions can then be included in the transaction and sent to the cluster like normal. See also the [best practices](#prioritization-fee-best-practices) below. -:::caution Transactions can only contain **one of each type** of compute budget -instruction. Duplicate types will result in an -[`TransactionError::DuplicateInstruction`](https://github.com/solana-labs/solana/blob/master/sdk/src/transaction/error.rs#L144-145) -error, and ultimately transaction failure. ::: +> Caution: Transactions can only contain **one of each type** of compute budget +> instruction. Duplicate types will result in an +> [`TransactionError::DuplicateInstruction`](https://github.com/solana-labs/solana/blob/master/sdk/src/transaction/error.rs#L144-145) +> error, and ultimately transaction failure. #### Rust @@ -199,9 +197,9 @@ by an executed transaction. #### Get recent prioritization fees Prior to sending a transaction to the cluster, you can use the -[`getRecentPrioritizationFees`](/api/http#getrecentprioritizationfees) RPC -method to get a list of the recent paid prioritization fees within the recent -blocks processed by the node. +[`getRecentPrioritizationFees`](/docs/rpc/http/getRecentPrioritizationFees.mdx) +RPC method to get a list of the recent paid prioritization fees within the +recent blocks processed by the node. You could then use this data to estimate an appropriate prioritization fee for your transaction to both (a) better ensure it gets processed by the cluster and diff --git a/docs/wallet-guide.md b/docs/intro/wallets.md similarity index 72% rename from docs/wallet-guide.md rename to docs/intro/wallets.md index 40eea6861..4fc381220 100644 --- a/docs/wallet-guide.md +++ b/docs/intro/wallets.md @@ -1,4 +1,5 @@ --- +sidebarLabel: Wallets title: Solana Wallet Guide --- @@ -15,8 +16,8 @@ file system, a piece of paper, or a specialized device called a _hardware wallet_. There are also various smartphone apps and computer programs that provide a user-friendly way to create and manage wallets. -A _keypair_ is a securely generated _private key_ and its -cryptographically-derived _public key_. A private key and its corresponding +A _keypair_ is a securely generated _secret key_ and its +cryptographically-derived _public key_. A secret key and its corresponding public key are together known as a _keypair_. A wallet contains a collection of one or more keypairs and provides some means to interact with them. @@ -28,16 +29,16 @@ Depending on a blockchain's implementation, the address can also be used to view certain information about a wallet, such as viewing the balance, but has no ability to change anything about the wallet or withdraw any tokens. -The _private key_ is required to digitally sign any transactions to send +The _secret key_ is required to digitally sign any transactions to send cryptocurrencies to another address or to make any changes to the wallet. The -private key **must never be shared**. If someone gains access to the private key -to a wallet, they can withdraw all the tokens it contains. If the private key -for a wallet is lost, any tokens that have been sent to that wallet's address -are **permanently lost**. +secret key **must never be shared**. If someone gains access to the secret key +to a wallet, they can withdraw all the tokens it contains. If the secret key for +a wallet is lost, any tokens that have been sent to that wallet's address are +**permanently lost**. Different wallet solutions offer different approaches to keypair security, interacting with the keypair, and signing transactions to use/spend the tokens. -Some are easier to use than others. Some store and back up private keys more +Some are easier to use than others. Some store and back up secret keys more securely. Solana supports multiple types of wallets so you can choose the right balance of security and convenience. @@ -46,11 +47,11 @@ first will need to create a wallet.** ## Supported Wallets -Several browser and mobile app based wallets support Solana. Find the right one -for you on the +Several browser and mobile app based wallets support Solana. Find some options +that might be right for you on the [Solana Ecosystem](https://solana.com/ecosystem/explore?categories=wallet) page. For advanced users or developers, the -[command-line wallets](wallet-guide/cli.md) may be more appropriate, as new -features on the Solana blockchain will always be supported on the command line -first before being integrated into third-party solutions. +[command-line wallets](https://docs.solanalabs.com/cli/wallets) may be more +appropriate, as new features on the Solana blockchain will always be supported +on the command line first before being integrated into third-party solutions. diff --git a/docs/integrations/exchange.md b/docs/more/exchange.md similarity index 90% rename from docs/integrations/exchange.md rename to docs/more/exchange.md index 08f7016bf..e47e0037a 100644 --- a/docs/integrations/exchange.md +++ b/docs/more/exchange.md @@ -20,11 +20,11 @@ This setup enables you: Solana nodes demand relatively high computing power to handle our fast blocks and high TPS. For specific requirements, please see -[hardware recommendations](../running-validator/validator-reqs.md). +[hardware recommendations](https://docs.solanalabs.com/operations/requirements). To run an api node: -1. [Install the Solana command-line tool suite](../cli/install-solana-cli-tools.md) +1. [Install the Solana command-line tool suite](https://docs.solanalabs.com/cli/install) 2. Start the validator with at least the following parameters: ```bash @@ -46,10 +46,10 @@ to the port you want to expose. The `--entrypoint` and `--expected-genesis-hash` parameters are all specific to the cluster you are joining. -[Current parameters for Mainnet Beta](../clusters.md#example-solana-validator-command-line-2) +[Current parameters for Mainnet Beta](https://docs.solanalabs.com/clusters/available#example-solana-validator-command-line-2) 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 +[shreds](/docs/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 @@ -60,7 +60,7 @@ selecting a custom limit value is Specifying one or more `--known-validator` parameters can protect you from booting from a malicious snapshot. -[More on the value of booting with known validators](../running-validator/validator-start.md#known-validators) +[More on the value of booting with known validators](https://docs.solanalabs.com/operations/guides/validator-start#known-validators) Optional parameters to consider: @@ -86,7 +86,7 @@ solana-watchtower --validator-identity ``` > You can find more information about the -> [best practices for Solana Watchtower](../validator/best-practices/monitoring.md#solana-watchtower) +> [best practices for Solana Watchtower](https://docs.solanalabs.com/operations/best-practices/monitoring#solana-watchtower) > here in the docs. #### New Software Release Announcements @@ -159,14 +159,14 @@ validators and only on the _Gossip_, _Repair_ and _ServeR_ ports. Solana accounts do not require any on-chain initialization; once they contain some SOL, they exist. To set up a deposit account for your exchange, simply generate a Solana keypair using any of our -[wallet tools](../wallet-guide/cli.md). +[wallet tools](https://docs.solanalabs.com/cli/wallets). We recommend using a unique deposit account for each of your users. Solana accounts must be made rent-exempt by containing 2-years worth of -[rent](developing/programming-model/accounts.md#rent) in SOL. In order to find -the minimum rent-exempt balance for your deposit accounts, query the -[`getMinimumBalanceForRentExemption` endpoint](../api/http#getminimumbalanceforrentexemption): +[rent](/docs/core/accounts.md#rent) in SOL. In order to find the minimum +rent-exempt balance for your deposit accounts, query the +[`getMinimumBalanceForRentExemption` endpoint](/docs/rpc/http/getMinimumBalanceForRentExemption.mdx): ```bash curl localhost:8899 -X POST -H "Content-Type: application/json" -d '{ @@ -184,7 +184,7 @@ curl localhost:8899 -X POST -H "Content-Type: application/json" -d '{ You may wish to keep the keys for one or more collection accounts offline for greater security. If so, you will need to move SOL to hot accounts using our -[offline methods](../offline-signing.md). +[offline methods](https://docs.solanalabs.com/cli/examples/offline-signing). ## Listening for Deposits @@ -229,8 +229,8 @@ block and inspect for addresses of interest, using the JSON-RPC service of your Solana API node. - To identify which blocks are available, send a - [`getBlocks`](../api/http#getblocks) request, passing the last block you have - already processed as the start-slot parameter: + [`getBlocks`](/docs/rpc/http/getBlocks.mdx) request, passing the last block + you have already processed as the start-slot parameter: ```bash curl https://api.devnet.solana.com -X POST -H "Content-Type: application/json" -d '{ @@ -247,8 +247,8 @@ curl https://api.devnet.solana.com -X POST -H "Content-Type: application/json" - Not every slot produces a block, so there may be gaps in the sequence of integers. -- For each block, request its contents with a [`getBlock`](../api/http#getblock) - request: +- For each block, request its contents with a + [`getBlock`](/docs/rpc/http/getBlock.mdx) request: ### Block Fetching Tips @@ -348,7 +348,7 @@ curl https://api.devnet.solana.com -X POST -H 'Content-Type: application/json' - The `preBalances` and `postBalances` fields allow you to track the balance changes in every account without having to parse the entire transaction. They list the starting and ending balances of each account in -[lamports](../terminology.md#lamport), indexed to the `accountKeys` list. For +[lamports](/docs/terminology.md#lamport), indexed to the `accountKeys` list. For example, if the deposit address of interest is `G1wZ113tiUHdSpQEBcid8n1x8BAvcWZoZgxPKxgE5B7o`, this transaction represents a transfer of 1040000000 - 1030000000 = 10,000,000 lamports = 0.01 SOL @@ -365,7 +365,7 @@ 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. -- Send a [`getSignaturesForAddress`](../api/http#getsignaturesforaddress) +- Send a [`getSignaturesForAddress`](/docs/rpc/http/getSignaturesForAddress.mdx) request to the api node: ```bash @@ -415,7 +415,7 @@ curl localhost:8899 -X POST -H "Content-Type: application/json" -d '{ ``` - For each signature returned, get the transaction details by sending a - [`getTransaction`](../api/http#gettransaction) request: + [`getTransaction`](/docs/rpc/http/getTransaction.mdx) request: ```bash curl https://api.devnet.solana.com -X POST -H 'Content-Type: application/json' -d '{ @@ -551,14 +551,14 @@ these cases, it is your responsibility to verify that the transaction succeeded and was finalized by the cluster. **Note:** Each transaction contains a -[recent blockhash](developing/programming-model/transactions.md#blockhash-format) -to indicate its liveness. It is **critical** to wait until this blockhash -expires before retrying a withdrawal transfer that does not appear to have been -confirmed or finalized by the cluster. Otherwise, you risk a double spend. See -more on [blockhash expiration](#blockhash-expiration) below. +[recent blockhash](/docs/core/transactions.md#blockhash-format) to indicate its +liveness. It is **critical** to wait until this blockhash expires before +retrying a withdrawal transfer that does not appear to have been confirmed or +finalized by the cluster. Otherwise, you risk a double spend. See more on +[blockhash expiration](#blockhash-expiration) below. -First, get a recent blockhash using the [`getFees`](../api/http#getfees) -endpoint or the CLI command: +First, get a recent blockhash using the +[`getFees`](/docs/rpc/deprecated/getFees.mdx) endpoint or the CLI command: ```bash solana fees --url http://localhost:8899 @@ -574,16 +574,16 @@ solana transfer --no-wait --allow-unfunded-recipient --b You can also build, sign, and serialize the transaction manually, and fire it off to the cluster using the JSON-RPC -[`sendTransaction`](../api/http#sendtransaction) endpoint. +[`sendTransaction`](/docs/rpc/http/sendTransaction.mdx) endpoint. #### Transaction Confirmations & Finality Get the status of a batch of transactions using the -[`getSignatureStatuses`](../api/http#getsignaturestatuses) JSON-RPC endpoint. -The `confirmations` field reports how many -[confirmed blocks](../terminology.md#confirmed-block) have elapsed since the +[`getSignatureStatuses`](/docs/rpc/http/getSignatureStatuses.mdx) JSON-RPC +endpoint. The `confirmations` field reports how many +[confirmed blocks](/docs/terminology.md#confirmed-block) have elapsed since the transaction was processed. If `confirmations: null`, it is -[finalized](../terminology.md#finality). +[finalized](/docs/terminology.md#finality). ```bash curl localhost:8899 -X POST -H "Content-Type: application/json" -d '{ @@ -631,7 +631,7 @@ curl localhost:8899 -X POST -H "Content-Type: application/json" -d '{ #### Blockhash Expiration You can check whether a particular blockhash is still valid by sending a -[`getFeeCalculatorForBlockhash`](../api/http#getfeecalculatorforblockhash) +[`getFeeCalculatorForBlockhash`](/docs/rpc/deprecated/getFeeCalculatorForBlockhash.mdx) request with the blockhash as a parameter. If the response value is `null`, the blockhash is expired, and the withdrawal transaction using that blockhash should never succeed. @@ -647,7 +647,7 @@ 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: -``` +```text [1-9A-HJ-NP-Za-km-z]{32,44} ``` @@ -776,13 +776,13 @@ line utility. The latest version of `cargo` can be installed using a handy one-liner for your platform at [rustup.rs](https://rustup.rs). Once `cargo` is installed, `spl-token` can be obtained with the following command: -``` +```bash cargo install spl-token-cli ``` You can then check the installed version to verify -``` +```bash spl-token --version ``` @@ -802,10 +802,10 @@ accounts do not: `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). + [rent-exempt](/docs/core/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). #### Command Line @@ -814,13 +814,13 @@ To create an SPL Token account with the following properties: 1. Associated with the given mint 1. Owned by the funding account's keypair -``` +```bash spl-token create-account ``` #### Example -``` +```bash $ spl-token create-account AkUFCWTXb3w9nY2n6SFJvBV6VwvFUCe4KBMCcgLsa2ir Creating account 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV Signature: 4JsqZEPra2eDTHtHpB4FMWSfk3UgcCVmkKkP7zESZeMrKmFFkDkNd91pKP3vPVVZZPiu5XxyJwS73Vi5WsZL88D7 @@ -828,7 +828,7 @@ Signature: 4JsqZEPra2eDTHtHpB4FMWSfk3UgcCVmkKkP7zESZeMrKmFFkDkNd91pKP3vPVVZZPiu5 Or to create an SPL Token account with a specific keypair: -``` +```bash $ solana-keygen new -o token-account.json $ spl-token create-account AkUFCWTXb3w9nY2n6SFJvBV6VwvFUCe4KBMCcgLsa2ir token-account.json Creating account 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV @@ -839,13 +839,13 @@ Signature: 4JsqZEPra2eDTHtHpB4FMWSfk3UgcCVmkKkP7zESZeMrKmFFkDkNd91pKP3vPVVZZPiu5 #### Command Line -``` +```bash spl-token balance ``` #### Example -``` +```bash $ solana balance 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV 0 ``` @@ -862,13 +862,13 @@ provided. #### Command Line -``` +```bash spl-token transfer --fund-recipient ``` #### Example -``` +```bash $ spl-token transfer 6B199xxzw3PkAm25hGJpjj3Wj3WNYNHzDAnt1tEqg5BN 1 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV Transfer 1 tokens Sender: 6B199xxzw3PkAm25hGJpjj3Wj3WNYNHzDAnt1tEqg5BN @@ -920,7 +920,7 @@ SOL (2,039,280 lamports). Template `spl-token transfer` command for a withdrawal: -``` +```bash $ spl-token transfer --fund-recipient ``` @@ -939,8 +939,8 @@ account. ## Testing the Integration Be sure to test your complete workflow on Solana devnet and testnet -[clusters](../clusters.md) before moving to production on mainnet-beta. Devnet -is the most open and flexible, and ideal for initial development, while testnet -offers more realistic cluster configuration. Both devnet and testnet support a -faucet, run `solana airdrop 1` to obtain some devnet or testnet SOL for -development and testing. +[clusters](/docs/core/clusters.md) before moving to production on mainnet-beta. +Devnet is the most open and flexible, and ideal for initial development, while +testnet offers more realistic cluster configuration. Both devnet and testnet +support a faucet, run `solana airdrop 1` to obtain some devnet or testnet SOL +for development and testing. diff --git a/docs/more/index.md b/docs/more/index.md new file mode 100644 index 000000000..0c7f22484 --- /dev/null +++ b/docs/more/index.md @@ -0,0 +1,6 @@ +--- +metaOnly: true +title: More Information +# note: sort order is set to a really high number so this section is at the bottom of the sidebar +sidebarSortOrder: 9999 +--- diff --git a/docs/developing/on-chain-programs/debugging.md b/docs/programs/debugging.md similarity index 81% rename from docs/developing/on-chain-programs/debugging.md rename to docs/programs/debugging.md index 3a8d684c1..46e752bc2 100644 --- a/docs/developing/on-chain-programs/debugging.md +++ b/docs/programs/debugging.md @@ -9,8 +9,8 @@ that will allow RPC clients to interact with their program. ## Running unit tests -- [Testing with Rust](developing-rust.md#how-to-test) -- [Testing with C](developing-c.md#how-to-test) +- [Testing with Rust](/docs/programs/lang-rust.md#how-to-test) +- [Testing with C](/docs/programs/lang-c.md#how-to-test) ## Logging @@ -20,8 +20,8 @@ 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) +- [Logging from a Rust program](/docs/programs/lang-rust.md#logging) +- [Logging from a C program](/docs/programs/lang-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 development @@ -29,7 +29,9 @@ 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 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` +```bash +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: @@ -65,12 +67,14 @@ get more information: In the case of `VirtualMachineFailedToRunProgram` errors, more information about the specifics of what failed are written to the -[program's execution logs](debugging.md#logging). +[program's execution logs](/docs/programs/debugging.md#logging). For example, an access violation involving the stack will look something like this: -`SBF program 4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM failed: out of bounds memory store (insn #615), addr 0x200001e38/8` +```text +SBF program 4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM failed: out of bounds memory store (insn #615), addr 0x200001e38/8 +``` ## Monitoring Compute Budget Consumption @@ -78,19 +82,18 @@ 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 operations they wish to profile. -- [Log the remaining compute units from a Rust program](developing-rust.md#compute-budget) -- [Log the remaining compute units from a C program](developing-c.md#compute-budget) +- [Log the remaining compute units from a Rust program](/docs/programs/lang-rust.md#compute-budget) +- [Log the remaining compute units from a C program](/docs/programs/lang-c.md#compute-budget) -See [compute budget](developing/programming-model/runtime.md#compute-budget) for -more information. +See [compute budget](/docs/core/runtime.md#compute-budget) for more information. ## ELF Dump The SBF 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. -- [Create a dump file of a Rust program](developing-rust.md#elf-dump) -- [Create a dump file of a C program](developing-c.md#elf-dump) +- [Create a dump file of a Rust program](/docs/programs/lang-rust.md#elf-dump) +- [Create a dump file of a C program](/docs/programs/lang-c.md#elf-dump) ## Instruction Tracing @@ -134,7 +137,7 @@ should be three files in that directory - helloworld.so -- an executable file loadable into the virtual machine. The command line for running `solana-ledger-tool` would be something like this -``` +```bash solana-ledger-tool program run -l test-ledger -e debugger target/deploy/helloworld.so ``` @@ -147,43 +150,43 @@ a ledger in `test-ledger` subdirectory. In debugger mode `solana-ledger-tool program run` loads an `.so` file and starts listening for an incoming connection from a debugger -``` +```text Waiting for a Debugger connection on "127.0.0.1:9001"... ``` To connect to `solana-ledger-tool` and execute the program, run lldb. For debugging rust programs it may be beneficial to run solana-lldb wrapper to lldb, i.e. at a new shell prompt (other than the one used to start -`solana-ledger-tool`) run the command +`solana-ledger-tool`) run the command: -``` +```bash solana-lldb ``` This script is installed in platform-tools path. If that path is not added to `PATH` environment variable, it may be necessary to specify the full path, e.g. -``` +```text ~/.cache/solana/v1.35/platform-tools/llvm/bin/solana-lldb ``` After starting the debugger, load the .debug file by entering the following command at the debugger prompt -``` +```text (lldb) file target/deploy/helloworld.debug ``` If the debugger finds the file, it will print something like this -``` +```text Current executable set to '/path/helloworld.debug' (bpf). ``` Now, connect to the gdb server that `solana-ledger-tool` implements, and debug the program as usual. Enter the following command at lldb prompt -``` +```text (lldb) gdb-remote 127.0.0.1:9001 ``` @@ -203,9 +206,9 @@ For example on Linux a possible path to Solana customized lldb can be `` is your Linux system username. This can also be added directly to `~/.config/Code/User/settings.json` file, e.g. -``` +```json { - "lldb.library": "/home//.cache/solana/v1.35/platform-tools/llvm/lib/liblldb.so" + "lldb.library": "/home//.cache/solana/v1.35/platform-tools/llvm/lib/liblldb.so" } ``` @@ -213,26 +216,26 @@ In `.vscode` subdirectory of your on-chain project, create two files First file is `tasks.json` with the following content -``` +```json { - "version": "2.0.0", - "tasks": [ - { - "label": "build", - "type": "shell", - "command": "cargo build-sbf --debug", - "problemMatcher": [], - "group": { - "kind": "build", - "isDefault": true - } - }, - { - "label": "solana-debugger", - "type": "shell", - "command": "solana-ledger-tool program run -l test-ledger -e debugger ${workspaceFolder}/target/deploy/helloworld.so" - } - ] + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "type": "shell", + "command": "cargo build-sbf --debug", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + }, + { + "label": "solana-debugger", + "type": "shell", + "command": "solana-ledger-tool program run -l test-ledger -e debugger ${workspaceFolder}/target/deploy/helloworld.so" + } + ] } ``` @@ -241,18 +244,20 @@ The second task is to run `solana-ledger-tool program run` in debugger mode. Another file is `launch.json` with the following content -``` +```json { - "version": "0.2.0", - "configurations": [ - { - "type": "lldb", - "request": "custom", - "name": "Debug", - "targetCreateCommands": ["target create ${workspaceFolder}/target/deploy/helloworld.debug"], - "processCreateCommands": ["gdb-remote 127.0.0.1:9001"] - } - ] + "version": "0.2.0", + "configurations": [ + { + "type": "lldb", + "request": "custom", + "name": "Debug", + "targetCreateCommands": [ + "target create ${workspaceFolder}/target/deploy/helloworld.debug" + ], + "processCreateCommands": ["gdb-remote 127.0.0.1:9001"] + } + ] } ``` diff --git a/docs/developing/on-chain-programs/deploying.md b/docs/programs/deploying.md similarity index 97% rename from docs/developing/on-chain-programs/deploying.md rename to docs/programs/deploying.md index f75570627..a4bb5ace8 100644 --- a/docs/developing/on-chain-programs/deploying.md +++ b/docs/programs/deploying.md @@ -114,15 +114,15 @@ following 3 phases: ## Reclaim rent from program accounts The storage of data on the Solana blockchain requires the payment of -[rent](./../intro/rent.md), including for the byte-code for on-chain programs. +[rent](/docs/core/rent.md), including for the byte-code for on-chain programs. Therefore as you deploy more or larger programs, the amount of rent paid to remain rent-exempt will also become larger. Using the current rent cost model configuration, a rent-exempt account requires a deposit of ~0.7 SOL per 100KB stored. These costs can have an outsized impact on developers who deploy their own programs since -[program accounts](./../programming-model/accounts.md#executable) are among the -largest we typically see on Solana. +[program accounts](/docs/core/accounts.md#executable) are among the largest we +typically see on Solana. #### Example of how much data is used for programs @@ -137,10 +137,6 @@ below is the distribution of the largest accounts (at least 100KB) at slot 5. **BPF Program Loader v2**: 191 accounts 6. **BPF Program Loader v1**: 150 accounts -> _Note: this data was pulled with a modified `solana-ledger-tool` built from -> this branch: -> [https://github.com/jstarry/solana/tree/large-account-stats](https://github.com/jstarry/solana/tree/large-account-stats)_ - ### Reclaiming buffer accounts Buffer accounts are used by the Upgradeable BPF loader to temporarily store diff --git a/docs/developing/on-chain-programs/examples.md b/docs/programs/examples.md similarity index 82% rename from docs/developing/on-chain-programs/examples.md rename to docs/programs/examples.md index 1aaf154c7..7c65bf6c9 100644 --- a/docs/developing/on-chain-programs/examples.md +++ b/docs/programs/examples.md @@ -29,9 +29,11 @@ $ cd break ``` Next, follow the steps in the git repository's -[README](https://github.com/solana-labs/break/blob/master/README.md). +[README](https://github.com/solana-labs/break/blob/main/README.md). ## Language Specific -- [Rust](developing-rust.md#examples) -- [C](developing-c.md#examples) +You can find some language specific example programs at the following locations: + +- [Rust](/docs/programs/lang-rust.md#examples) +- [C](/docs/programs/lang-c.md#examples) diff --git a/docs/developing/on-chain-programs/faq.md b/docs/programs/faq.md similarity index 89% rename from docs/developing/on-chain-programs/faq.md rename to docs/programs/faq.md index 7496173bb..dfc5f4cd8 100644 --- a/docs/developing/on-chain-programs/faq.md +++ b/docs/programs/faq.md @@ -16,7 +16,8 @@ Developing programs on the Solana blockchain have some inherent limitation associated with them. Below is a list of common limitation that you may run into. -See [Limitations of developing programs](./limitations.md) for more details +See [limitations of developing programs](/docs/programs/limitations.md) for more +details ## Berkeley Packet Filter (BPF) @@ -68,9 +69,7 @@ This program error can occur while trying to deserialize the instruction, check that the structure passed in matches exactly the instruction. There may be some padding between fields. If the program implements the Rust `Pack` trait then try packing and unpacking the instruction type `T` to determine the exact encoding -the program expects: - -https://github.com/solana-labs/solana/blob/v1.4/sdk/program/src/program_pack.rs +the program expects. ## MissingRequiredSignature @@ -79,18 +78,18 @@ an account is expected to be signed but is not. An implementation of a program might also cause this error when performing a cross-program invocation that requires a signed program address, but the passed -signer seeds passed to -[`invoke_signed`](developing/programming-model/calling-between-programs.md) -don't match the signer seeds used to create the program address -[`create_program_address`](developing/programming-model/calling-between-programs.md#program-derived-addresses). +signer seeds passed to [`invoke_signed`](/docs/core/cpi.md) don't match the +signer seeds used to create the program address +[`create_program_address`](/docs/core/cpi.md#program-derived-addresses). ## `rand` Rust dependency causes compilation failure -See [Rust Project Dependencies](developing-rust.md#project-dependencies) +See +[Rust Project Dependencies](/docs/programs/lang-rust.md#project-dependencies) ## Rust restrictions -See [Rust restrictions](developing-rust.md#restrictions) +See [Rust restrictions](/docs/programs/lang-rust.md#restrictions) ## Stack @@ -102,7 +101,7 @@ overrun as a warning. For example: -``` +```text Error: Function _ZN16curve25519_dalek7edwards21EdwardsBasepointTable6create17h178b3d2411f7f082E Stack offset of -30728 exceeded max offset of -4096 by 26632 bytes, please minimize large stack variables ``` @@ -137,8 +136,8 @@ Internally, programs have access to the 32KB memory region starting at virtual address 0x300000000 and may implement a custom heap based on the program's specific needs. -- [Rust program heap usage](developing-rust.md#heap) -- [C program heap usage](developing-c.md#heap) +- [Rust program heap usage](/docs/programs/lang-rust.md#heap) +- [C program heap usage](/docs/programs/lang-c.md#heap) ## Loaders @@ -161,8 +160,8 @@ 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) +- [Rust program entrypoints](/docs/programs/lang-rust.md#program-entrypoint) +- [C program entrypoints](/docs/programs/lang-c.md#program-entrypoint) ### Deployment @@ -182,7 +181,7 @@ When an instruction is directed at an executable SBF program the loader configures the program's execution environment, serializes the program's input parameters, calls the program's entrypoint, and reports any errors encountered. -For further information see [deploying](deploying.md) +For further information, see [deploying programs](/docs/programs/deploying.md). ### Input Parameter Serialization @@ -196,8 +195,8 @@ 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 deserialization](developing-c.md#parameter-deserialization) +- [Rust program parameter deserialization](/docs/programs/lang-rust.md#parameter-deserialization) +- [C program parameter deserialization](/docs/programs/lang-c.md#parameter-deserialization) The latest loader serializes the program input parameters as follows (all encoding is little endian): diff --git a/docs/developing/on-chain-programs/overview.md b/docs/programs/index.md similarity index 63% rename from docs/developing/on-chain-programs/overview.md rename to docs/programs/index.md index 939438077..680e54b82 100644 --- a/docs/developing/on-chain-programs/overview.md +++ b/docs/programs/index.md @@ -1,13 +1,13 @@ --- -title: "Overview of Writing Programs" -sidebarLabel: "Overview" +title: Developing on-chain programs +sidebarLabel: Developing Programs --- Developers can write and deploy their own programs to the Solana blockchain. While developing these "on-chain" programs can seem cumbersome, the entire process can be broadly summarized into a few key steps. -## Solana Development Lifecycle +## On-chain program development lifecycle 1. Setup your development environment 2. Write your program @@ -18,7 +18,7 @@ process can be broadly summarized into a few key steps. ### 1. Setup your development environment The most robust way of getting started with Solana development, is -[installing the Solana CLI](./../../cli/install-solana-cli-tools.md) tools on +[installing the Solana CLI](https://docs.solanalabs.com/cli/install) tools on your local computer. This will allow you to have the most powerful development environment. @@ -38,17 +38,17 @@ Rust programs are effectively the same as creating a traditional ### 3. Compile the program Once the program is written, it must be complied down to -[Berkley Packet Filter](./faq.md#berkeley-packet-filter-bpf) byte-code that will -then be deployed to the blockchain. +[Berkley Packet Filter](/docs/programs/faq.md#berkeley-packet-filter-bpf) +byte-code that will then be deployed to the blockchain. ### 4. Generate the program's public address -Using the [Solana CLI](./../../cli/install-solana-cli-tools.md), the developer -will generate a new unique [Keypair](./../../terminology.md#keypair) for the new +Using the [Solana CLI](https://docs.solanalabs.com/cli/install), the developer +will generate a new unique [Keypair](/docs/terminology.md#keypair) for the new program. The public address (aka -[Pubkey](./../../terminology.md#public-key-pubkey)) from this Keypair will be -used on-chain as the program's public address (aka -[`programId`](./../../terminology.md#program-id)). +[Pubkey](/docs/terminology.md#public-key-pubkey)) from this Keypair will be used +on-chain as the program's public address (aka +[`programId`](/docs/terminology.md#program-id)). ### 5. Deploying the program @@ -61,34 +61,34 @@ manner. Once the entire program has been sent to the blockchain, a final transaction is sent to write all of the buffered byte-code to the program's data account. This either mark the new program as -[`executable`](./../programming-model/accounts.md#executable), or complete the -process to upgrade an existing program (if it already existed). +[`executable`](/docs/core/accounts.md#executable), or complete the process to +upgrade an existing program (if it already existed). ## Support languages Solana programs are typically written in the -[Rust language](./developing-rust.md), but [C/C++](./developing-c.md) are also -supported. +[Rust language](/docs/programs/lang-rust.md), but +[C/C++](/docs/programs/lang-c.md) are also supported. There are also various community driven efforts to enable writing on-chain programs using other languages, including: -- Python via [Seahorse](https://seahorse-lang.org/) (that acts as a wrapper the - Rust based Anchor framework) +- Python via [Seahorse](https://seahorse.dev/) (that acts as a wrapper the Rust + based Anchor framework) ## Example programs -You can also explore the [Program Examples](./examples.md) for examples of -on-chain programs. +You can also explore the [Program Examples](/docs/programs/examples.md) for +examples of on-chain programs. ## Limitations As you dive deeper into program development, it is important to understand some of the important limitations associated with on-chain programs. -Read more details on the [Limitations](./limitations.md) page +Read more details on the [Limitations](/docs/programs/limitations.md) page ## Frequently asked questions -Discover many of the [frequently asked questions](./faq.md) other developers -have about writing/understanding Solana programs. +Discover many of the [frequently asked questions](/docs/programs/faq.md) other +developers have about writing/understanding Solana programs. diff --git a/docs/developing/on-chain-programs/developing-c.md b/docs/programs/lang-c.md similarity index 86% rename from docs/developing/on-chain-programs/developing-c.md rename to docs/programs/lang-c.md index d5e74f898..d8b745d7b 100644 --- a/docs/developing/on-chain-programs/developing-c.md +++ b/docs/programs/lang-c.md @@ -9,7 +9,7 @@ languages. C projects are laid out as follows: -``` +```text /src/ /makefile ``` @@ -30,7 +30,7 @@ First setup the environment: - Install the latest Rust stable from https://rustup.rs - Install the latest - [Solana command-line tools](../../cli/install-solana-cli-tools.md) + [Solana command-line tools](https://docs.solanalabs.com/cli/install) Then build using make: @@ -55,7 +55,7 @@ Programs export a known entrypoint symbol which the Solana runtime looks up and calls when invoking a program. Solana supports multiple versions of the SBF loader and the entrypoints may vary between them. Programs must be written for and deployed to the same loader. For more details see the -[FAQ section on Loaders](./faq.md#loaders). +[FAQ section on Loaders](/docs/programs/faq.md#loaders). Currently there are two supported loaders [SBF Loader](https://github.com/solana-labs/solana/blob/7ddf10e602d2ed87a9e3737aa8c32f1db9f909d8/sdk/program/src/bpf_loader.rs#L17) @@ -71,7 +71,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 each loader contains its own [helper function](#Serialization). +parameters each loader contains its own [helper function](#serialization). ### Serialization @@ -91,7 +91,8 @@ 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. Details on how the loader serializes the program inputs can be found in the -[Input Parameter Serialization](./faq.md#input-parameter-serialization) docs. +[Input Parameter Serialization/docs/programs/faq#input-parameter-serialization) +docs. ## Data Types @@ -122,17 +123,16 @@ 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 -the -[runtime enforcement 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 cases 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 +the [runtime enforcement policy](/docs/core/runtime.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 cases 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. `data` is the general purpose byte array from the -[instruction's instruction data](developing/programming-model/transactions.md#instruction-data) +[instruction's instruction data](/docs/core/transactions.md#instruction-data) being processed. `program_id` is the public key of the currently executing program. @@ -153,8 +153,8 @@ logs. - [`sol_log(const char*)`](https://github.com/solana-labs/solana/blob/d2ee9db2143859fa5dc26b15ee6da9c25cc0429c/sdk/sbf/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/sbf/c/inc/solana_sdk.h#L134) -The [debugging](debugging.md#logging) section has more information about working -with program logs. +The [debugging](/docs/programs/debugging.md#logging) section has more +information about working with program logs. ## Compute Budget @@ -166,8 +166,7 @@ Use the system call to log a message containing the remaining number of compute units the program may consume before execution is halted -See [compute budget](developing/programming-model/runtime.md#compute-budget) for -more information. +See [compute budget](/docs/core/runtime.md#compute-budget) for more information. ## ELF Dump diff --git a/docs/developing/on-chain-programs/developing-rust.md b/docs/programs/lang-rust.md similarity index 87% rename from docs/developing/on-chain-programs/developing-rust.md rename to docs/programs/lang-rust.md index 263ec25e5..a5e02fcf6 100644 --- a/docs/developing/on-chain-programs/developing-rust.md +++ b/docs/programs/lang-rust.md @@ -10,7 +10,7 @@ Solana supports writing on-chain programs using the Solana Rust programs follow the typical [Rust project layout](https://doc.rust-lang.org/cargo/guide/project-layout.html): -``` +```text /inc/ /src/ /Cargo.toml @@ -18,11 +18,10 @@ Solana Rust programs follow the typical 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, -programs should define an `no-entrypoint` feature in `Cargo.toml` and use to -exclude the entrypoint. +[cross-program invocations](/docs/core/cpi.md). 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, programs should define an `no-entrypoint` +feature in `Cargo.toml` and use to exclude the entrypoint. - [Define the feature](https://github.com/solana-labs/solana-program-library/blob/fca9836a2c8e18fc7e3595287484e9acd60a8f64/token/program/Cargo.toml#L12) - [Exclude the entrypoint](https://github.com/solana-labs/solana-program-library/blob/fca9836a2c8e18fc7e3595287484e9acd60a8f64/token/program/src/lib.rs#L12) @@ -50,7 +49,7 @@ For example: [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 - [Stack](./faq.md#stack). + [Stack](/docs/programs/faq.md#stack). ## How to Build @@ -58,7 +57,7 @@ First setup the environment: - Install the latest Rust stable from https://rustup.rs/ - Install the latest - [Solana command-line tools](../../cli/install-solana-cli-tools.md) + [Solana command-line tools](https://docs.solanalabs.com/cli/install) The normal cargo build is available for building programs against your host machine which can be used for unit testing: @@ -97,7 +96,7 @@ 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 loader and the entrypoints may vary between them. Programs must be written for and deployed to the same loader. For more details see the -[FAQ section on Loaders](./faq.md#loaders). +[FAQ section on Loaders](/docs/programs/faq.md#loaders). Currently there are two supported loaders [BPF Loader](https://github.com/solana-labs/solana/blob/d9b0fc0e3eec67dfe4a97d9298b15969b2804fab/sdk/program/src/bpf_loader.rs#L17) @@ -150,7 +149,8 @@ their own deserialization function they need to ensure that any modifications the program wishes to commit be written back into the input byte array. Details on how the loader serializes the program inputs can be found in the -[Input Parameter Serialization](./faq.md#input-parameter-serialization) docs. +[Input Parameter Serialization](/docs/programs/faq.md#input-parameter-serialization) +docs. ### Data Types @@ -174,18 +174,18 @@ 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 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 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 program does not accidentally perform overlapping read/writes to the -same underlying data via multiple `AccountInfo` structures. If a program -implements their own deserialization function care should be taken to handle -duplicate accounts appropriately. +[runtime enforcement policy](/docs/core/runtime.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 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 program +does not accidentally perform overlapping read/writes to the same underlying +data via multiple `AccountInfo` structures. If a program implements their own +deserialization function care should be taken to handle duplicate accounts +appropriately. The instruction data is the general purpose byte array from the -[instruction's instruction data](developing/programming-model/transactions.md#instruction-data) +[instruction's instruction data](/docs/core/transactions.md#instruction-data) being processed. ## Heap @@ -225,8 +225,8 @@ single-threaded environment, as well as being deterministic: 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 budget](developing/programming-model/runtime.md#compute-budget) - for more information. + [computation budget](/docs/core/runtime.md#compute-budget) for more + information. ## Depending on Rand @@ -236,7 +236,7 @@ available. Sometimes a program may depend on a crate that depends itself on If a program depends on `rand`, the compilation will fail because there is no `get-random` support for Solana. The error will typically look like this: -``` +```bash error: target is not supported, for more information see: https://docs.rs/getrandom/#unsupported-targets --> /Users/jack/.cargo/registry/src/github.com-1ecc6299db9ec823/getrandom-0.1.14/src/lib.rs:257:9 | @@ -250,13 +250,13 @@ error: target is not supported, for more information see: https://docs.rs/getran To work around this dependency issue, add the following dependency to the program's `Cargo.toml`: -``` +```rust getrandom = { version = "0.1.14", features = ["dummy"] } ``` or if the dependency is on getrandom v0.2 add: -``` +```rust getrandom = { version = "0.2.2", features = ["custom"] } ``` @@ -286,15 +286,16 @@ can emulate `println!` by using `format!`: msg!("Some variable: {:?}", variable); ``` -The [debugging](debugging.md#logging) section has more information about working -with program logs the [Rust examples](#examples) contains a logging example. +The [debugging](/docs/programs/debugging.md#logging) section has more +information about working with program logs the [Rust examples](#examples) +contains a logging example. ## Panicking Rust's `panic!`, `assert!`, and internal panic results are printed to the -[program logs](debugging.md#logging) by default. +[program logs](/docs/programs/debugging.md#logging) by default. -``` +```bash INFO solana_runtime::message_processor] Finalized account CGLhHSuWsp1gT4B7MY2KACqp9RUwQRhcUFfVSuxpSajZ INFO solana_runtime::message_processor] Call SBF program CGLhHSuWsp1gT4B7MY2KACqp9RUwQRhcUFfVSuxpSajZ INFO solana_runtime::message_processor] Program log: Panicked at: 'assertion failed: `(left == right)` @@ -311,7 +312,7 @@ implementation. First define the `custom-panic` feature in the program's `Cargo.toml` -```toml +```rust [features] default = ["custom-panic"] custom-panic = [] @@ -357,8 +358,7 @@ Use the system call to log a message containing the remaining number of compute units the program may consume before execution is halted -See [compute budget](developing/programming-model/runtime.md#compute-budget) for -more information. +See [compute budget](/docs/core/runtime.md#compute-budget) for more information. ## ELF Dump @@ -380,5 +380,10 @@ $ cargo build-bpf --dump ## Examples The -[Solana Program Library github](https://github.com/solana-labs/solana-program-library/tree/master/examples/rust) +[Solana Program Library GitHub](https://github.com/solana-labs/solana-program-library/tree/master/examples/rust) repo contains a collection of Rust examples. + +The +[Solana Developers Program Examples GitHub](https://github.com/solana-developers/program-examples) +repo also contains a collection of beginner to intermediate Rust program +examples. diff --git a/docs/developing/on-chain-programs/limitations.md b/docs/programs/limitations.md similarity index 75% rename from docs/developing/on-chain-programs/limitations.md rename to docs/programs/limitations.md index c17c5be97..54c830b38 100644 --- a/docs/developing/on-chain-programs/limitations.md +++ b/docs/programs/limitations.md @@ -12,17 +12,18 @@ Since Rust based on-chain programs must run be deterministic while running in a resource-constrained, single-threaded environment, they have some limitations on various libraries. -See [Developing with Rust - Restrictions](./developing-rust.md#restrictions) for -a detailed breakdown these restrictions and limitations. +See +[Developing with Rust - Restrictions](/docs/programs/lang-rust.md#restrictions) +for a detailed breakdown these restrictions and limitations. ## Compute budget To prevent abuse of the blockchain's computational resources, each transaction -is allocated a [compute budget](./../../terminology.md#compute-budget). -Exceeding this compute budget will result in the transaction failing. +is allocated a [compute budget](/docs/terminology.md#compute-budget). Exceeding +this compute budget will result in the transaction failing. -See [computational constraints](../programming-model/runtime.md#compute-budget) -in the Runtime for more specific details. +See [computational constraints](/docs/core/runtime.md#compute-budget) in the +Runtime for more specific details. ## Call stack depth - `CallDepthExceeded` error @@ -38,8 +39,8 @@ Cross-program invocations allow programs to invoke other programs directly, but the depth is constrained currently to `4`. When a program exceeds the allowed -[cross-program invocation call depth](../programming-model/calling-between-programs.md#call-depth), -it will receive a `CallDepth` error +[cross-program invocation call depth](/docs/core/cpi.md#call-depth), it will +receive a `CallDepth` error ## Float Rust types support @@ -52,11 +53,10 @@ built-ins. Due to the 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 -operations: -https://github.com/solana-labs/solana-program-library/tree/master/libraries/math - -To run the test: sync the repo and run: +The +[Solana Program Library math](https://github.com/solana-labs/solana-program-library/tree/master/libraries/math) +tests will report the performance of some math operations. To run the test, sync +the repo and run: ```sh cargo test-sbf -- --nocapture --test-threads=1 @@ -66,7 +66,7 @@ Recent results show the float operations take more instructions compared to integers equivalents. Fixed point implementations may vary but will also be less than the float equivalents: -``` +```text u64 f32 Multiply 8 176 Divide 9 219 diff --git a/docs/rpc.md b/docs/rpc.md new file mode 100644 index 000000000..75a50157f --- /dev/null +++ b/docs/rpc.md @@ -0,0 +1,10 @@ +--- +title: JSON RPC Methods +sidebarSortOrder: 0 +--- + +This file should not be edited since it is not intended to be displayed. This +file only exist to create a link within the master documentation sidebar. + +The Solana JSON RPC documentation is available within the +[`rpc` directory](./rpc/) diff --git a/docs/rpc/deprecated/getConfirmedBlock.mdx b/docs/rpc/deprecated/getConfirmedBlock.mdx new file mode 100644 index 000000000..7ce3c57e4 --- /dev/null +++ b/docs/rpc/deprecated/getConfirmedBlock.mdx @@ -0,0 +1,201 @@ +--- +sidebarLabel: getConfirmedBlock +title: getConfirmedBlock RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getConfirmedBlock +--- + +Returns identity and transaction information about a confirmed block in the +ledger + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getBlock](/docs/rpc/http/getBlock) instead. + + + + + + +### Parameters + + + slot number, as u64 integer + + + + +Configuration object containing the following fields: + + + + + level of transaction detail to return, either "full", "signatures", or "none" + + + + whether to populate the `rewards` array. + + + + +Encoding format for Account data + + + +
+ +- `jsonParsed` encoding attempts to use program-specific instruction parsers to + return more human-readable and explicit data in the + `transaction.message.instructions` list. +- If `jsonParsed` is requested but a parser cannot be found, the instruction + falls back to regular JSON encoding (`accounts`, `data`, and `programIdIndex` + fields). + +
+ + + + + +### Result + +The result field will be an object with the following fields: + +- `` - if specified block is not confirmed +- `` - if block is confirmed, an object with the following fields: + - `blockhash: ` - the blockhash of this block, as base-58 encoded + string + - `previousBlockhash: ` - the blockhash of this block's parent, as + base-58 encoded string; if the parent block is not available due to ledger + cleanup, this field will return "11111111111111111111111111111111" + - `parentSlot: ` - the slot index of this block's parent + - `transactions: ` - present if "full" transaction details are + requested; an array of JSON objects containing: + - `transaction: ` - + [Transaction](/docs/rpc/json-structures#transactions) object, either in + JSON format or encoded binary data, depending on encoding parameter + - `meta: ` - transaction status metadata object, containing `null` + or: + - `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) + - `fee: ` - fee this transaction was charged, as u64 integer + - `preBalances: ` - array of u64 account balances from before the + transaction was processed + - `postBalances: ` - array of u64 account balances after the + transaction was processed + - `innerInstructions: ` - List of + [inner instructions](/docs/rpc/json-structures#inner-instructions) or + `null` if inner instruction recording was not enabled during this + transaction + - `preTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from before + the transaction was processed or omitted if token balance recording was + not yet enabled during this transaction + - `postTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from after + the transaction was processed or omitted if token balance recording was + not yet enabled during this transaction + - `logMessages: ` - array of string log messages or `null` if + log message recording was not enabled during this transaction + - DEPRECATED: `status: ` - Transaction status + - `"Ok": ` - Transaction was successful + - `"Err": ` - Transaction failed with TransactionError + - `signatures: ` - present if "signatures" are requested for + transaction details; an array of signatures strings, corresponding to the + transaction order in the block + - `rewards: ` - present if rewards are requested; an array of JSON + objects containing: + - `pubkey: ` - The public key, as base-58 encoded string, of the + account that received the reward + - `lamports: `- number of reward lamports credited or debited by the + account, as a i64 + - `postBalance: ` - account balance in lamports after the reward was + applied + - `rewardType: ` - type of reward: "fee", "rent", + "voting", "staking" + - `commission: ` - vote account commission when the reward was + credited, only present for voting and staking rewards + - `blockTime: ` - estimated production time, as Unix timestamp + (seconds since the Unix epoch). null if not available + +#### For more details on returned data: + +- [Transaction Structure](/docs/rpc/json-structures#transactions) +- [Inner Instructions Structure](/docs/rpc/json-structures#inner-instructions) +- [Token Balances Structure](/docs/rpc/json-structures#token-balances) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getConfirmedBlock", + "params": [430, "base64"] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "blockTime": null, + "blockhash": "3Eq21vXNB5s86c62bVuUfTeaMif1N2kUqRPBmGRJhyTA", + "parentSlot": 429, + "previousBlockhash": "mfcyqEXB3DnHXki6KjjmZck6YjmZLvpAByy2fj4nh6B", + "rewards": [], + "transactions": [ + { + "meta": { + "err": null, + "fee": 5000, + "innerInstructions": [], + "logMessages": [], + "postBalances": [499998932500, 26858640, 1, 1, 1], + "postTokenBalances": [], + "preBalances": [499998937500, 26858640, 1, 1, 1], + "preTokenBalances": [], + "status": { + "Ok": null + } + }, + "transaction": [ + "AVj7dxHlQ9IrvdYVIjuiRFs1jLaDMHixgrv+qtHBwz51L4/ImLZhszwiyEJDIp7xeBSpm/TX5B7mYzxa+fPOMw0BAAMFJMJVqLw+hJYheizSoYlLm53KzgT82cDVmazarqQKG2GQsLgiqktA+a+FDR4/7xnDX7rsusMwryYVUdixfz1B1Qan1RcZLwqvxvJl4/t3zHragsUp0L47E24tAFUgAAAABqfVFxjHdMkoVmOYaR1etoteuKObS21cc1VbIQAAAAAHYUgdNXR0u3xNdiTr072z2DVec9EQQ/wNo1OAAAAAAAtxOUhPBp2WSjUNJEgfvy70BbxI00fZyEPvFHNfxrtEAQQEAQIDADUCAAAAAQAAAAAAAACtAQAAAAAAAAdUE18R96XTJCe+YfRfUp6WP+YKCy/72ucOL8AoBFSpAA==", + "base64" + ] + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getConfirmedBlocks.mdx b/docs/rpc/deprecated/getConfirmedBlocks.mdx new file mode 100644 index 000000000..767eaea33 --- /dev/null +++ b/docs/rpc/deprecated/getConfirmedBlocks.mdx @@ -0,0 +1,64 @@ +--- +sidebarLabel: getConfirmedBlocks +title: getConfirmedBlocks RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getConfirmedBlocks +--- + +Returns a list of confirmed blocks between two slots + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getBlocks](/docs/rpc/http/getblocks) instead. + + + + + + +### Parameters + + + start_slot, as u64 integer + + + + +Configuration object containing the following fields: + + + + + +### Result + +The result field will be an array of u64 integers listing confirmed blocks +between `start_slot` and either `end_slot` - if provided, or latest confirmed +block, inclusive. Max range allowed is 500,000 slots. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc": "2.0","id":1,"method":"getConfirmedBlocks","params":[5, 10]} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": [5, 6, 7, 8, 9, 10], "id": 1 } +``` + + + diff --git a/docs/rpc/deprecated/getConfirmedBlocksWithLimit.mdx b/docs/rpc/deprecated/getConfirmedBlocksWithLimit.mdx new file mode 100644 index 000000000..8a46687f8 --- /dev/null +++ b/docs/rpc/deprecated/getConfirmedBlocksWithLimit.mdx @@ -0,0 +1,71 @@ +--- +sidebarLabel: getConfirmedBlocksWithLimit +title: getConfirmedBlocksWithLimit RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getConfirmedBlocksWithLimit +--- + +Returns a list of confirmed blocks starting at the given slot + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getBlocksWithLimit](/docs/rpc/http/getblockswithlimit) instead. + + + + + + +### Parameters + + + start_slot, as u64 integer + + + + limit, as u64 integer + + + + +Configuration object containing the following fields: + + + + + +### Result + +The result field will be an array of u64 integers listing confirmed blocks +starting at `start_slot` for up to `limit` blocks, inclusive. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getConfirmedBlocksWithLimit", + "params": [5, 3] + } +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": [5, 6, 7], "id": 1 } +``` + + + diff --git a/docs/rpc/deprecated/getConfirmedSignaturesForAddress2.mdx b/docs/rpc/deprecated/getConfirmedSignaturesForAddress2.mdx new file mode 100644 index 000000000..4efde28dd --- /dev/null +++ b/docs/rpc/deprecated/getConfirmedSignaturesForAddress2.mdx @@ -0,0 +1,113 @@ +--- +sidebarLabel: getConfirmedSignaturesForAddress2 +title: getConfirmedSignaturesForAddress2 RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getConfirmedSignaturesForAddress2 +--- + +Returns signatures for confirmed transactions that include the given address in +their `accountKeys` list. Returns signatures backwards in time from the provided +signature or most recent confirmed block + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getSignaturesForAddress](/docs/rpc/http/getSignaturesForAddress) instead. + + + + + + +### Parameters + + + account address, as base-58 encoded string + + + +Configuration object containing the following fields: + + + + + maximum transaction signatures to return (between 1 and 1,000, default: + 1,000). + + + + start searching backwards from this transaction signature. (If not provided + the search starts from the top of the highest max confirmed block.) + + + + search until this transaction signature, if found before limit reached. + + + + +### Result + +The result field will be an array of ``, ordered from newest to oldest +transaction, containing transaction signature information with the following +fields: + +- `signature: ` - transaction signature as base-58 encoded string +- `slot: ` - The slot that contains the block with the transaction +- `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) +- `memo: ` - Memo associated with the transaction, null if no memo + is present +- `blockTime: ` - estimated production time, as Unix timestamp + (seconds since the Unix epoch) of when transaction was processed. null if not + available. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getConfirmedSignaturesForAddress2", + "params": [ + "Vote111111111111111111111111111111111111111", + { + "limit": 1 + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "err": null, + "memo": null, + "signature": "5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv", + "slot": 114, + "blockTime": null + } + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getConfirmedTransaction.mdx b/docs/rpc/deprecated/getConfirmedTransaction.mdx new file mode 100644 index 000000000..c850bb375 --- /dev/null +++ b/docs/rpc/deprecated/getConfirmedTransaction.mdx @@ -0,0 +1,152 @@ +--- +sidebarLabel: getConfirmedTransaction +title: getConfirmedTransaction RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getConfirmedTransaction +--- + +Returns transaction details for a confirmed transaction + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getTransaction](/docs/rpc/http/getTransaction) instead. + + + + + + +### Parameters + + + transaction signature, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +Encoding format for Account data + + + +
+ +- `base58` is slow and limited to less than 129 bytes of Account data. +- `jsonParsed` encoding attempts to use program-specific instruction parsers to + return more human-readable and explicit data in the + `transaction.message.instructions` list. +- If `jsonParsed` is requested but a parser cannot be found, the instruction + falls back to regular `json` encoding (`accounts`, `data`, and + `programIdIndex` fields). + +
+ + + + + +### Result + +- `` - if transaction is not found or not confirmed +- `` - if transaction is confirmed, an object with the following fields: + - `slot: ` - the slot this transaction was processed in + - `transaction: ` - + [Transaction](/docs/rpc/json-structures#transactions) object, either in JSON + format or encoded binary data, depending on encoding parameter + - `blockTime: ` - estimated production time, as Unix timestamp + (seconds since the Unix epoch) of when the transaction was processed. null + if not available + - `meta: ` - transaction status metadata object: + - `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://docs.rs/solana-sdk/latest/solana_sdk/transaction/enum.TransactionError.html) + - `fee: ` - fee this transaction was charged, as u64 integer + - `preBalances: ` - array of u64 account balances from before the + transaction was processed + - `postBalances: ` - array of u64 account balances after the + transaction was processed + - `innerInstructions: ` - List of + [inner instructions](/docs/rpc/json-structures#inner-instructions) or + `null` if inner instruction recording was not enabled during this + transaction + - `preTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from before the + transaction was processed or omitted if token balance recording was not + yet enabled during this transaction + - `postTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from after the + transaction was processed or omitted if token balance recording was not + yet enabled during this transaction + - `logMessages: ` - array of string log messages or `null` if + log message recording was not enabled during this transaction + - DEPRECATED: `status: ` - Transaction status + - `"Ok": ` - Transaction was successful + - `"Err": ` - Transaction failed with TransactionError + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getConfirmedTransaction", + "params": [ + "2nBhEBYYvfaAe16UMNqRHre4YNSskvuYgx3M6E4JP1oDYvZEJHvoPzyUidNgNX5r9sTyN1J9UxtbCXy2rqYcuyuv", + "base64" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "meta": { + "err": null, + "fee": 5000, + "innerInstructions": [], + "postBalances": [499998932500, 26858640, 1, 1, 1], + "postTokenBalances": [], + "preBalances": [499998937500, 26858640, 1, 1, 1], + "preTokenBalances": [], + "status": { + "Ok": null + } + }, + "slot": 430, + "transaction": [ + "AVj7dxHlQ9IrvdYVIjuiRFs1jLaDMHixgrv+qtHBwz51L4/ImLZhszwiyEJDIp7xeBSpm/TX5B7mYzxa+fPOMw0BAAMFJMJVqLw+hJYheizSoYlLm53KzgT82cDVmazarqQKG2GQsLgiqktA+a+FDR4/7xnDX7rsusMwryYVUdixfz1B1Qan1RcZLwqvxvJl4/t3zHragsUp0L47E24tAFUgAAAABqfVFxjHdMkoVmOYaR1etoteuKObS21cc1VbIQAAAAAHYUgdNXR0u3xNdiTr072z2DVec9EQQ/wNo1OAAAAAAAtxOUhPBp2WSjUNJEgfvy70BbxI00fZyEPvFHNfxrtEAQQEAQIDADUCAAAAAQAAAAAAAACtAQAAAAAAAAdUE18R96XTJCe+YfRfUp6WP+YKCy/72ucOL8AoBFSpAA==", + "base64" + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getFeeCalculatorForBlockhash.mdx b/docs/rpc/deprecated/getFeeCalculatorForBlockhash.mdx new file mode 100644 index 000000000..458690e67 --- /dev/null +++ b/docs/rpc/deprecated/getFeeCalculatorForBlockhash.mdx @@ -0,0 +1,93 @@ +--- +sidebarLabel: getFeeCalculatorForBlockhash +title: getFeeCalculatorForBlockhash RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getFeeCalculatorForBlockhash +--- + +Returns the fee calculator associated with the query blockhash, or `null` if the +blockhash has expired + + + This method is expected to be removed in `solana-core` v2.0. Please use + [isBlockhashValid](/docs/rpc/http/isBlockhashValid) or + [getFeeForMessage](/docs/rpc/http/getFeeForMessage) instead. + + + + + + +### Parameters + + + query blockhash, as a base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to: + +- `` - if the query blockhash has expired; or +- `` - otherwise, a JSON object containing: + - `feeCalculator: ` - `FeeCalculator` object describing the cluster + fee rate at the queried blockhash + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getFeeCalculatorForBlockhash", + "params": [ + "GJxqhuxcgfn5Tcj6y3f8X4FeCDd2RQ6SnEMo1AAxrPRZ" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 221 + }, + "value": { + "feeCalculator": { + "lamportsPerSignature": 5000 + } + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getFeeRateGovernor.mdx b/docs/rpc/deprecated/getFeeRateGovernor.mdx new file mode 100644 index 000000000..c7d64e35d --- /dev/null +++ b/docs/rpc/deprecated/getFeeRateGovernor.mdx @@ -0,0 +1,72 @@ +--- +sidebarLabel: getFeeRateGovernor +title: getFeeRateGovernor RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getFeeRateGovernor +--- + +Returns the fee rate governor information from the root bank + + + This method is expected to be removed in `solana-core` v2.0. + + + + + + +### Parameters + +**None** + +### Result + +The result will be an RpcResponse JSON object with `value` equal to an `object` +with the following fields: + +- `burnPercent: ` - Percentage of fees collected to be destroyed +- `maxLamportsPerSignature: ` - Largest value `lamportsPerSignature` can + attain for the next slot +- `minLamportsPerSignature: ` - Smallest value `lamportsPerSignature` can + attain for the next slot +- `targetLamportsPerSignature: ` - Desired fee rate for the cluster +- `targetSignaturesPerSlot: ` - Desired signature rate for the cluster + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getFeeRateGovernor"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 54 + }, + "value": { + "feeRateGovernor": { + "burnPercent": 50, + "maxLamportsPerSignature": 100000, + "minLamportsPerSignature": 5000, + "targetLamportsPerSignature": 10000, + "targetSignaturesPerSlot": 20000 + } + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getFees.mdx b/docs/rpc/deprecated/getFees.mdx new file mode 100644 index 000000000..dd673e28e --- /dev/null +++ b/docs/rpc/deprecated/getFees.mdx @@ -0,0 +1,91 @@ +--- +sidebarLabel: getFees +title: getFees RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getFees + - /docs/rpc/http/getFees +--- + +Returns a recent block hash from the ledger, a fee schedule that can be used to +compute the cost of submitting a transaction using it, and the last slot in +which the blockhash will be valid. + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getFeeForMessage](/docs/rpc/http/getFeeForMessage) instead. + + + + + + +### Parameters + + + Pubkey of account to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` set to a JSON object +with the following fields: + +- `blockhash: ` - a Hash as base-58 encoded string +- `feeCalculator: ` - FeeCalculator object, the fee schedule for this + block hash +- `lastValidSlot: ` - DEPRECATED - this value is inaccurate and should not + be relied upon +- `lastValidBlockHeight: ` - last + [block height](/docs/terminology.md#block-height) at which the blockhash will + be valid + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { "jsonrpc":"2.0", "id": 1, "method":"getFees"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1 + }, + "value": { + "blockhash": "CSymwgTNX1j3E4qhKfJAUE41nBWEwXufoYryPbkde5RR", + "feeCalculator": { + "lamportsPerSignature": 5000 + }, + "lastValidSlot": 297, + "lastValidBlockHeight": 296 + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getRecentBlockhash.mdx b/docs/rpc/deprecated/getRecentBlockhash.mdx new file mode 100644 index 000000000..987b67c79 --- /dev/null +++ b/docs/rpc/deprecated/getRecentBlockhash.mdx @@ -0,0 +1,84 @@ +--- +sidebarLabel: getRecentBlockhash +title: getRecentBlockhash RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getRecentBlockhash +--- + +Returns a recent block hash from the ledger, and a fee schedule that can be used +to compute the cost of submitting a transaction using it. + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getLatestBlockhash](/docs/rpc/http/getlatestblockhash) instead. + + + + + + +### Parameters + + + Pubkey of account to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +### Result + +An RpcResponse containing a JSON object consisting of a string blockhash and +FeeCalculator JSON object. + +- `RpcResponse` - RpcResponse JSON object with `value` field set to a + JSON object including: +- `blockhash: ` - a Hash as base-58 encoded string +- `feeCalculator: ` - FeeCalculator object, the fee schedule for this + block hash + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getRecentBlockhash"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1 + }, + "value": { + "blockhash": "CSymwgTNX1j3E4qhKfJAUE41nBWEwXufoYryPbkde5RR", + "feeCalculator": { + "lamportsPerSignature": 5000 + } + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/deprecated/getSnapshotSlot.mdx b/docs/rpc/deprecated/getSnapshotSlot.mdx new file mode 100644 index 000000000..a6eef8370 --- /dev/null +++ b/docs/rpc/deprecated/getSnapshotSlot.mdx @@ -0,0 +1,57 @@ +--- +sidebarLabel: getSnapshotSlot +title: getSnapshotSlot RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSnapshotSlot +--- + +Returns the highest slot that the node has a snapshot for + + + This method is expected to be removed in `solana-core` v2.0. Please use + [getHighestSnapshotSlot](/docs/rpc/http/getHighestSnapshotSlot) instead. + + + + + + +### Parameters + +**None** + +### Result + +`` - Snapshot slot + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getSnapshotSlot"} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 100, "id": 1 } +``` + +Result when the node has no snapshot: + +```json +{ + "jsonrpc": "2.0", + "error": { "code": -32008, "message": "No snapshot" }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getAccountInfo.mdx b/docs/rpc/http/getAccountInfo.mdx new file mode 100644 index 000000000..8d85a7782 --- /dev/null +++ b/docs/rpc/http/getAccountInfo.mdx @@ -0,0 +1,143 @@ +--- +sidebarLabel: getAccountInfo +title: getAccountInfo RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getAccountInfo +--- + +Returns all information associated with the account of provided Pubkey + + + + + +### Parameters + + + Pubkey of account to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +Encoding format for Account data + + + +
+ +- `base58` is slow and limited to less than 129 bytes of Account data. +- `base64` will return base64 encoded data for Account data of any size. +- `base64+zstd` compresses the Account data using + [Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to `base64` encoding, detectable when the `data` field is type `string`. + +
+ + + + + Request a slice of the account's data. + +- `length: ` - number of bytes to return +- `offset: ` - byte offset from which to start reading + + + Data slicing is only available for `base58`, `base64`, or `base64+zstd` + encodings. + + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to: + +- `` - if the requested account doesn't exist +- `` - otherwise, a JSON object containing: + - `lamports: ` - number of lamports assigned to this account, as a u64 + - `owner: ` - base-58 encoded Pubkey of the program this account has + been assigned to + - `data: <[string, encoding]|object>` - data associated with the account, + either as encoded binary data or JSON format `{: }` - + depending on encoding parameter + - `executable: ` - boolean indicating if the account contains a program + \(and is strictly read-only\) + - `rentEpoch: ` - the epoch at which this account will next owe rent, as + u64 + - `size: ` - the data size of the account + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getAccountInfo", + "params": [ + "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg", + { + "encoding": "base58" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1 + }, + "value": { + "data": [ + "11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHRTPuR3oZ1EioKtYGiYxpxMG5vpbZLsbcBYBEmZZcMKaSoGx9JZeAuWf", + "base58" + ], + "executable": false, + "lamports": 1000000000, + "owner": "11111111111111111111111111111111", + "rentEpoch": 2, + "space": 80 + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBalance.mdx b/docs/rpc/http/getBalance.mdx new file mode 100644 index 000000000..dc56f7edb --- /dev/null +++ b/docs/rpc/http/getBalance.mdx @@ -0,0 +1,73 @@ +--- +sidebarLabel: getBalance +title: getBalance RPC Method +sidebarSortOrder: 10 +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBalance +--- + +Returns the lamport balance of the account of provided Pubkey + + + + + +### Parameters + + + Pubkey of account to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +`RpcResponse` - RpcResponse JSON object with `value` field set to the +balance + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getBalance", + "params": [ + "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { "context": { "slot": 1 }, "value": 0 }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlock.mdx b/docs/rpc/http/getBlock.mdx new file mode 100644 index 000000000..6a44a6a2b --- /dev/null +++ b/docs/rpc/http/getBlock.mdx @@ -0,0 +1,287 @@ +--- +sidebarLabel: getBlock +title: getBlock RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlock +--- + +Returns identity and transaction information about a confirmed block in the +ledger + + + + + +### Parameters + + + slot number, as `u64` integer + + + + +Configuration object containing the following fields: + + + +- `processed` is not supported. + + + + + +encoding format for each returned Transaction + + + +
+ +- `jsonParsed` attempts to use program-specific instruction parsers to return + more human-readable and explicit data in the + `transaction.message.instructions` list. +- If `jsonParsed` is requested but a parser cannot be found, the instruction + falls back to regular JSON encoding (`accounts`, `data`, and `programIdIndex` + fields). + +
+ + + + + +level of transaction detail to return + + + +
+ +- If `accounts` are requested, transaction details only include signatures and + an annotated list of accounts in each transaction. +- Transaction metadata is limited to only: fee, err, pre_balances, + post_balances, pre_token_balances, and post_token_balances. + +
+ + + + + +the max transaction version to return in responses. + +
+ +- If the requested block contains a transaction with a higher version, an error + will be returned. +- If this parameter is omitted, only legacy transactions will be returned, and a + block containing any versioned transaction will prompt the error. + +
+ + + + + whether to populate the `rewards` array. If parameter not provided, the + default includes rewards. + + + + +### Result + +The result field will be an object with the following fields: + +- `` - if specified block is not confirmed +- `` - if block is confirmed, an object with the following fields: + - `blockhash: ` - the blockhash of this block, as base-58 encoded + string + - `previousBlockhash: ` - the blockhash of this block's parent, as + base-58 encoded string; if the parent block is not available due to ledger + cleanup, this field will return "11111111111111111111111111111111" + - `parentSlot: ` - the slot index of this block's parent + - `transactions: ` - present if "full" transaction details are + requested; an array of JSON objects containing: + - `transaction: ` - + [Transaction](/docs/rpc/json-structures#transactions) object, either in + JSON format or encoded binary data, depending on encoding parameter + - `meta: ` - transaction status metadata object, containing `null` + or: + - `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) + - `fee: ` - fee this transaction was charged, as u64 integer + - `preBalances: ` - array of u64 account balances from before the + transaction was processed + - `postBalances: ` - array of u64 account balances after the + transaction was processed + - `innerInstructions: ` - List of + [inner instructions](/docs/rpc/json-structures#inner-instructions) or + `null` if inner instruction recording was not enabled during this + transaction + - `preTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from before + the transaction was processed or omitted if token balance recording was + not yet enabled during this transaction + - `postTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from after + the transaction was processed or omitted if token balance recording was + not yet enabled during this transaction + - `logMessages: ` - array of string log messages or `null` if + log message recording was not enabled during this transaction + - `rewards: ` - transaction-level rewards, populated if + rewards are requested; an array of JSON objects containing: + - `pubkey: ` - The public key, as base-58 encoded string, of the + account that received the reward + - `lamports: `- number of reward lamports credited or debited by + the account, as a i64 + - `postBalance: ` - account balance in lamports after the reward + was applied + - `rewardType: ` - type of reward: "fee", "rent", + "voting", "staking" + - `commission: ` - vote account commission when the reward + was credited, only present for voting and staking rewards + - DEPRECATED: `status: ` - Transaction status + - `"Ok": ` - Transaction was successful + - `"Err": ` - Transaction failed with TransactionError + - `loadedAddresses: ` - Transaction addresses loaded + from address lookup tables. Undefined if + `maxSupportedTransactionVersion` is not set in request params, or if + `jsonParsed` encoding is set in request params. + - `writable: ` - Ordered list of base-58 encoded + addresses for writable loaded accounts + - `readonly: ` - Ordered list of base-58 encoded + addresses for readonly loaded accounts + - `returnData: ` - the most-recent return data generated + by an instruction in the transaction, with the following fields: + - `programId: ` - the program that generated the return data, as + base-58 encoded Pubkey + - `data: <[string, encoding]>` - the return data itself, as base-64 + encoded binary data + - `computeUnitsConsumed: ` - number of + [compute units](/docs/core/runtime.md#compute-budget) consumed by the + transaction + - `version: <"legacy"|number|undefined>` - Transaction version. Undefined if + `maxSupportedTransactionVersion` is not set in request params. + - `signatures: ` - present if "signatures" are requested for + transaction details; an array of signatures strings, corresponding to the + transaction order in the block + - `rewards: ` - block-level rewards, present if rewards are + requested; an array of JSON objects containing: + - `pubkey: ` - The public key, as base-58 encoded string, of the + account that received the reward + - `lamports: `- number of reward lamports credited or debited by the + account, as a i64 + - `postBalance: ` - account balance in lamports after the reward was + applied + - `rewardType: ` - type of reward: "fee", "rent", + "voting", "staking" + - `commission: ` - vote account commission when the reward was + credited, only present for voting and staking rewards + - `blockTime: ` - estimated production time, as Unix timestamp + (seconds since the Unix epoch). null if not available + - `blockHeight: ` - the number of blocks beneath this block + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0","id":1, + "method":"getBlock", + "params": [ + 430, + { + "encoding": "json", + "maxSupportedTransactionVersion":0, + "transactionDetails":"full", + "rewards":false + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "blockHeight": 428, + "blockTime": null, + "blockhash": "3Eq21vXNB5s86c62bVuUfTeaMif1N2kUqRPBmGRJhyTA", + "parentSlot": 429, + "previousBlockhash": "mfcyqEXB3DnHXki6KjjmZck6YjmZLvpAByy2fj4nh6B", + "transactions": [ + { + "meta": { + "err": null, + "fee": 5000, + "innerInstructions": [], + "logMessages": [], + "postBalances": [499998932500, 26858640, 1, 1, 1], + "postTokenBalances": [], + "preBalances": [499998937500, 26858640, 1, 1, 1], + "preTokenBalances": [], + "rewards": null, + "status": { + "Ok": null + } + }, + "transaction": { + "message": { + "accountKeys": [ + "3UVYmECPPMZSCqWKfENfuoTv51fTDTWicX9xmBD2euKe", + "AjozzgE83A3x1sHNUR64hfH7zaEBWeMaFuAN9kQgujrc", + "SysvarS1otHashes111111111111111111111111111", + "SysvarC1ock11111111111111111111111111111111", + "Vote111111111111111111111111111111111111111" + ], + "header": { + "numReadonlySignedAccounts": 0, + "numReadonlyUnsignedAccounts": 3, + "numRequiredSignatures": 1 + }, + "instructions": [ + { + "accounts": [1, 2, 3, 0], + "data": "37u9WtQpcm6ULa3WRQHmj49EPs4if7o9f1jSRVZpm2dvihR9C8jY4NqEwXUbLwx15HBSNcP1", + "programIdIndex": 4 + } + ], + "recentBlockhash": "mfcyqEXB3DnHXki6KjjmZck6YjmZLvpAByy2fj4nh6B" + }, + "signatures": [ + "2nBhEBYYvfaAe16UMNqRHre4YNSskvuYgx3M6E4JP1oDYvZEJHvoPzyUidNgNX5r9sTyN1J9UxtbCXy2rqYcuyuv" + ] + } + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlockCommitment.mdx b/docs/rpc/http/getBlockCommitment.mdx new file mode 100644 index 000000000..3e4789f78 --- /dev/null +++ b/docs/rpc/http/getBlockCommitment.mdx @@ -0,0 +1,65 @@ +--- +sidebarLabel: getBlockCommitment +title: getBlockCommitment RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlockCommitment +--- + +Returns commitment for particular block + + + + + +### Parameters + + + block number, identified by Slot + + +### Result + +The result field will be a JSON object containing: + +- `commitment` - commitment, comprising either: + - `` - Unknown block + - `` - commitment, array of u64 integers logging the amount of cluster + stake in lamports that has voted on the block at each depth from 0 to + `MAX_LOCKOUT_HISTORY` + 1 +- `totalStake` - total active stake, in lamports, of the current epoch + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getBlockCommitment", + "params":[5] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "commitment": [ + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 10, 32 + ], + "totalStake": 42 + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlockHeight.mdx b/docs/rpc/http/getBlockHeight.mdx new file mode 100644 index 000000000..c9d3270a4 --- /dev/null +++ b/docs/rpc/http/getBlockHeight.mdx @@ -0,0 +1,66 @@ +--- +sidebarLabel: getBlockHeight +title: getBlockHeight RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlockHeight +--- + +Returns the current block height of the node + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +- `` - Current block height + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0","id":1, + "method":"getBlockHeight" + } +' +``` + +Result: + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": 1233, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlockProduction.mdx b/docs/rpc/http/getBlockProduction.mdx new file mode 100644 index 000000000..eb51b4285 --- /dev/null +++ b/docs/rpc/http/getBlockProduction.mdx @@ -0,0 +1,94 @@ +--- +sidebarLabel: getBlockProduction +title: getBlockProduction RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlockProduction +--- + +Returns recent block production information from the current or previous epoch. + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + Only return results for this validator identity (base-58 encoded) + + + +Slot range to return block production for. If parameter not provided, defaults to current epoch. + +- `firstSlot: ` - first slot to return block production information for + (inclusive) +- (optional) `lastSlot: ` - last slot to return block production + information for (inclusive). If parameter not provided, defaults to the + highest slot + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to: + +- `` + - `byIdentity: ` - a dictionary of validator identities, as base-58 + encoded strings. Value is a two element array containing the number of + leader slots and the number of blocks produced. + - `range: ` - Block production slot range + - `firstSlot: ` - first slot of the block production information + (inclusive) + - `lastSlot: ` - last slot of block production information (inclusive) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getBlockProduction"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 9887 + }, + "value": { + "byIdentity": { + "85iYT5RuzRTDgjyRa3cP8SYhM2j21fj7NhfJ3peu1DPr": [9888, 9886] + }, + "range": { + "firstSlot": 0, + "lastSlot": 9887 + } + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlockTime.mdx b/docs/rpc/http/getBlockTime.mdx new file mode 100644 index 000000000..b92a32bd9 --- /dev/null +++ b/docs/rpc/http/getBlockTime.mdx @@ -0,0 +1,75 @@ +--- +sidebarLabel: getBlockTime +title: getBlockTime RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlockTime +--- + +Returns the estimated production time of a block. + + + Each validator reports their UTC time to the ledger on a regular interval by + intermittently adding a timestamp to a Vote for a particular block. A + requested block's time is calculated from the stake-weighted mean of the Vote + timestamps in a set of recent blocks recorded on the ledger. + + + + + + +### Parameters + + + block number, identified by Slot + + +### Result + +- `` - estimated production time, as Unix timestamp (seconds since the Unix + epoch) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0", "id":1, + "method": "getBlockTime", + "params":[5] + } +' +``` + +### Response + +When a block time is available: + +```json +{ + "jsonrpc": "2.0", + "result": 1574721591, + "id": 1 +} +``` + +When a block time is not available: + +```json +{ + "jsonrpc": "2.0", + "error": { + "code": -32004, + "message": "Block not available for slot 150" + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlocks.mdx b/docs/rpc/http/getBlocks.mdx new file mode 100644 index 000000000..225785bb8 --- /dev/null +++ b/docs/rpc/http/getBlocks.mdx @@ -0,0 +1,79 @@ +--- +sidebarLabel: getBlocks +title: getBlocks RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlocks +--- + +Returns a list of confirmed blocks between two slots + + + + + +### Parameters + + + start_slot, as `u64` integer + + + + end_slot, as `u64` integer (must be no more than 500,000 blocks higher than + the `start_slot`) + + + + +Configuration object containing the following fields: + + + +- "processed" is not supported + + + + + +### Result + +The result field will be an array of u64 integers listing confirmed blocks +between `start_slot` and either `end_slot` - if provided, or latest confirmed +block, inclusive. Max range allowed is 500,000 slots. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getBlocks", + "params": [ + 5, 10 + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [5, 6, 7, 8, 9, 10], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getBlocksWithLimit.mdx b/docs/rpc/http/getBlocksWithLimit.mdx new file mode 100644 index 000000000..4a5666e81 --- /dev/null +++ b/docs/rpc/http/getBlocksWithLimit.mdx @@ -0,0 +1,77 @@ +--- +sidebarLabel: getBlocksWithLimit +title: getBlocksWithLimit RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getBlocksWithLimit +--- + +Returns a list of confirmed blocks starting at the given slot + + + + + +### Parameters + + + start_slot, as `u64` integer + + + + limit, as `u64` integer (must be no more than 500,000 blocks higher than the + `start_slot`) + + + + +Configuration object containing the following field: + + + +- "processed" is not supported + + + + + +### Result + +The result field will be an array of u64 integers listing confirmed blocks +starting at `start_slot` for up to `limit` blocks, inclusive. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id":1, + "method":"getBlocksWithLimit", + "params":[5, 3] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [5, 6, 7], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getClusterNodes.mdx b/docs/rpc/http/getClusterNodes.mdx new file mode 100644 index 000000000..38b15726f --- /dev/null +++ b/docs/rpc/http/getClusterNodes.mdx @@ -0,0 +1,69 @@ +--- +sidebarLabel: getClusterNodes +title: getClusterNodes RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getClusterNodes +--- + +Returns information about all the nodes participating in the cluster + + + + + +### Parameters + +**None** + +### Result + +The result field will be an array of JSON objects, each with the following sub +fields: + +- `pubkey: ` - Node public key, as base-58 encoded string +- `gossip: ` - Gossip network address for the node +- `tpu: ` - TPU network address for the node +- `rpc: ` - JSON RPC network address for the node, or `null` if the + JSON RPC service is not enabled +- `version: ` - The software version of the node, or `null` if the + version information is not available +- `featureSet: ` - The unique identifier of the node's feature set +- `shredVersion: ` - The shred version the node has been configured to + use + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getClusterNodes" + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "gossip": "10.239.6.48:8001", + "pubkey": "9QzsJf7LPLj8GkXbYT3LFDKqsj2hHG7TA3xinJHu8epQ", + "rpc": "10.239.6.48:8899", + "tpu": "10.239.6.48:8856", + "version": "1.0.0 c375ce1f" + } + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getEpochInfo.mdx b/docs/rpc/http/getEpochInfo.mdx new file mode 100644 index 000000000..4d46885e3 --- /dev/null +++ b/docs/rpc/http/getEpochInfo.mdx @@ -0,0 +1,76 @@ +--- +sidebarLabel: getEpochInfo +title: getEpochInfo RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getEpochInfo +--- + +Returns information about the current epoch + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +The result field will be an object with the following fields: + +- `absoluteSlot: ` - the current slot +- `blockHeight: ` - the current block height +- `epoch: ` - the current epoch +- `slotIndex: ` - the current slot relative to the start of the current + epoch +- `slotsInEpoch: ` - the number of slots in this epoch +- `transactionCount: ` - total number of transactions processed + without error since genesis + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getEpochInfo"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "absoluteSlot": 166598, + "blockHeight": 166500, + "epoch": 27, + "slotIndex": 2790, + "slotsInEpoch": 8192, + "transactionCount": 22661093 + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getEpochSchedule.mdx b/docs/rpc/http/getEpochSchedule.mdx new file mode 100644 index 000000000..aac0b42c3 --- /dev/null +++ b/docs/rpc/http/getEpochSchedule.mdx @@ -0,0 +1,64 @@ +--- +sidebarLabel: getEpochSchedule +title: getEpochSchedule RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getEpochSchedule +--- + +Returns the epoch schedule information from this cluster's genesis config + + + + + +### Parameters + +**None** + +### Result + +The result field will be an object with the following fields: + +- `slotsPerEpoch: ` - the maximum number of slots in each epoch +- `leaderScheduleSlotOffset: ` - the number of slots before beginning of an + epoch to calculate a leader schedule for that epoch +- `warmup: ` - whether epochs start short and grow +- `firstNormalEpoch: ` - first normal-length epoch, log2(slotsPerEpoch) - + log2(MINIMUM_SLOTS_PER_EPOCH) +- `firstNormalSlot: ` - MINIMUM_SLOTS_PER_EPOCH \* + (2.pow(firstNormalEpoch) - 1) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0","id":1, + "method":"getEpochSchedule" + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "firstNormalEpoch": 8, + "firstNormalSlot": 8160, + "leaderScheduleSlotOffset": 8192, + "slotsPerEpoch": 8192, + "warmup": true + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getFeeForMessage.mdx b/docs/rpc/http/getFeeForMessage.mdx new file mode 100644 index 000000000..76df0a96f --- /dev/null +++ b/docs/rpc/http/getFeeForMessage.mdx @@ -0,0 +1,80 @@ +--- +sidebarLabel: getFeeForMessage +title: getFeeForMessage RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getFeeForMessage +--- + +Get the fee the network will charge for a particular Message + + + This method is only available in `solana-core` v1.9 or newer. Please use + [getFees](/docs/rpc/deprecated/getFees.mdx) for `solana-core` v1.8 and below. + + + + + + +### Parameters + + + Base-64 encoded Message + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +- `` - Fee corresponding to the message at the specified blockhash + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' +{ + "id":1, + "jsonrpc":"2.0", + "method":"getFeeForMessage", + "params":[ + "AQABAgIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEBAQAA", + { + "commitment":"processed" + } + ] +} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { "context": { "slot": 5068 }, "value": 5000 }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getFirstAvailableBlock.mdx b/docs/rpc/http/getFirstAvailableBlock.mdx new file mode 100644 index 000000000..0bd896171 --- /dev/null +++ b/docs/rpc/http/getFirstAvailableBlock.mdx @@ -0,0 +1,45 @@ +--- +sidebarLabel: getFirstAvailableBlock +title: getFirstAvailableBlock RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getFirstAvailableBlock +--- + +Returns the slot of the lowest confirmed block that has not been purged from the +ledger + + + + + +### Parameters + +**None** + +### Result + +- `` - Slot + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0","id":1, + "method":"getFirstAvailableBlock" + } +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 250000, "id": 1 } +``` + + + diff --git a/docs/rpc/http/getGenesisHash.mdx b/docs/rpc/http/getGenesisHash.mdx new file mode 100644 index 000000000..054f105ad --- /dev/null +++ b/docs/rpc/http/getGenesisHash.mdx @@ -0,0 +1,45 @@ +--- +sidebarLabel: getGenesisHash +title: getGenesisHash RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getGenesisHash +--- + +Returns the genesis hash + + + + + +### Parameters + +**None** + +### Result + +- `` - a Hash as base-58 encoded string + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getGenesisHash"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": "GH7ome3EiwEr7tu9JuTh2dpYWBJK3z69Xm1ZE3MEE6JC", + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getHealth.mdx b/docs/rpc/http/getHealth.mdx new file mode 100644 index 000000000..cc6dbcec5 --- /dev/null +++ b/docs/rpc/http/getHealth.mdx @@ -0,0 +1,78 @@ +--- +sidebarLabel: getHealth +title: getHealth RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getHealth +--- + +Returns the current health of the node. A healthy node is one that is within +`HEALTH_CHECK_SLOT_DISTANCE` slots of the latest cluster confirmed slot. + + + + + +### Parameters + +**None** + +### Result + +If the node is healthy: "ok" + +If the node is unhealthy, a JSON RPC error response is returned. The specifics +of the error response are **UNSTABLE** and may change in the future + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getHealth"} +' +``` + +### Response + +Healthy Result: + +```json +{ "jsonrpc": "2.0", "result": "ok", "id": 1 } +``` + +Unhealthy Result (generic): + +```json +{ + "jsonrpc": "2.0", + "error": { + "code": -32005, + "message": "Node is unhealthy", + "data": {} + }, + "id": 1 +} +``` + +Unhealthy Result (if additional information is available) + +```json +{ + "jsonrpc": "2.0", + "error": { + "code": -32005, + "message": "Node is behind by 42 slots", + "data": { + "numSlotsBehind": 42 + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getHighestSnapshotSlot.mdx b/docs/rpc/http/getHighestSnapshotSlot.mdx new file mode 100644 index 000000000..75f9a0f4a --- /dev/null +++ b/docs/rpc/http/getHighestSnapshotSlot.mdx @@ -0,0 +1,75 @@ +--- +sidebarLabel: getHighestSnapshotSlot +title: getHighestSnapshotSlot RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getHighestSnapshotSlot +--- + +Returns the highest slot information that the node has snapshots for. + +This will find the highest full snapshot slot, and the highest incremental +snapshot slot _based on_ the full snapshot slot, if there is one. + + + This method is only available in `solana-core` v1.9 or newer. Please use + [getSnapshotSlot](/docs/rpc/http/getSnapshotSlot) for `solana-core` v1.8 and + below. + + + + + + +### Parameters + +**None** + +### Result + +When the node has a snapshot, this returns a JSON object with the following +fields: + +- `full: ` - Highest full snapshot slot +- `incremental: ` - Highest incremental snapshot slot _based on_ + `full` + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1,"method":"getHighestSnapshotSlot"} +' +``` + +### Response + +Result when the node has a snapshot: + +```json +{ + "jsonrpc": "2.0", + "result": { + "full": 100, + "incremental": 110 + }, + "id": 1 +} +``` + +Result when the node has no snapshot: + +```json +{ + "jsonrpc": "2.0", + "error": { "code": -32008, "message": "No snapshot" }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getIdentity.mdx b/docs/rpc/http/getIdentity.mdx new file mode 100644 index 000000000..969ddaafb --- /dev/null +++ b/docs/rpc/http/getIdentity.mdx @@ -0,0 +1,50 @@ +--- +sidebarLabel: getIdentity +title: getIdentity RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getIdentity +--- + +Returns the identity pubkey for the current node + + + + + +### Parameters + +**None** + +### Result + +The result field will be a JSON object with the following fields: + +- `identity` - the identity pubkey of the current node \(as a base-58 encoded + string\) + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getIdentity"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "identity": "2r1F4iWqVcb8M1DbAjQuFpebkQHY9hcVU4WuW2DJBppN" + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getInflationGovernor.mdx b/docs/rpc/http/getInflationGovernor.mdx new file mode 100644 index 000000000..b2e64d238 --- /dev/null +++ b/docs/rpc/http/getInflationGovernor.mdx @@ -0,0 +1,71 @@ +--- +sidebarLabel: getInflationGovernor +title: getInflationGovernor RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getInflationGovernor +--- + +Returns the current inflation governor + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + +### Result + +The result field will be a JSON object with the following fields: + +- `initial: ` - the initial inflation percentage from time 0 +- `terminal: ` - terminal inflation percentage +- `taper: ` - rate per year at which inflation is lowered. (Rate reduction + is derived using the target slot time in genesis config) +- `foundation: ` - percentage of total inflation allocated to the + foundation +- `foundationTerm: ` - duration of foundation pool inflation in years + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getInflationGovernor"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "foundation": 0.05, + "foundationTerm": 7, + "initial": 0.15, + "taper": 0.15, + "terminal": 0.015 + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getInflationRate.mdx b/docs/rpc/http/getInflationRate.mdx new file mode 100644 index 000000000..312e44aaf --- /dev/null +++ b/docs/rpc/http/getInflationRate.mdx @@ -0,0 +1,56 @@ +--- +sidebarLabel: getInflationRate +title: getInflationRate RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getInflationRate +--- + +Returns the specific inflation values for the current epoch + + + + + +### Parameters + +**None** + +### Result + +The result field will be a JSON object with the following fields: + +- `total: ` - total inflation +- `validator: ` -inflation allocated to validators +- `foundation: ` - inflation allocated to the foundation +- `epoch: ` - epoch for which these values are valid + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getInflationRate"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "epoch": 100, + "foundation": 0.001, + "total": 0.149, + "validator": 0.148 + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getInflationReward.mdx b/docs/rpc/http/getInflationReward.mdx new file mode 100644 index 000000000..3db6d9d1a --- /dev/null +++ b/docs/rpc/http/getInflationReward.mdx @@ -0,0 +1,96 @@ +--- +sidebarLabel: getInflationReward +title: getInflationReward RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getInflationReward +--- + +Returns the inflation / staking reward for a list of addresses for an epoch + + + + + +### Parameters + + + An array of addresses to query, as base-58 encoded strings + + + + +Configuration object containing the following fields: + + + + + An epoch for which the reward occurs. If omitted, the previous epoch will be + used + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +The result field will be a JSON array with the following fields: + +- `epoch: ` - epoch for which reward occured +- `effectiveSlot: ` - the slot in which the rewards are effective +- `amount: ` - reward amount in lamports +- `postBalance: ` - post balance of the account in lamports +- `commission: ` - vote account commission when the reward was + credited + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getInflationReward", + "params": [ + [ + "6dmNQ5jwLeLk5REvio1JcMshcbvkYMwy26sJ8pbkvStu", + "BGsqMegLpV6n6Ve146sSX2dTjUMj3M92HnU8BbNRMhF2" + ], + {"epoch": 2} + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "amount": 2500, + "effectiveSlot": 224, + "epoch": 2, + "postBalance": 499999442500 + }, + null + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getLargestAccounts.mdx b/docs/rpc/http/getLargestAccounts.mdx new file mode 100644 index 000000000..27f08f4f3 --- /dev/null +++ b/docs/rpc/http/getLargestAccounts.mdx @@ -0,0 +1,146 @@ +--- +sidebarLabel: getLargestAccounts +title: getLargestAccounts RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getLargestAccounts +--- + +Returns the 20 largest accounts, by lamport balance (results may be cached up to +two hours) + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + filter results by account type + + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to an array of +`` containing: + +- `address: ` - base-58 encoded address of the account +- `lamports: ` - number of lamports in the account, as a u64 + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getLargestAccounts"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 54 + }, + "value": [ + { + "lamports": 999974, + "address": "99P8ZgtJYe1buSK8JXkvpLh8xPsCFuLYhz9hQFNw93WJ" + }, + { + "lamports": 42, + "address": "uPwWLo16MVehpyWqsLkK3Ka8nLowWvAHbBChqv2FZeL" + }, + { + "lamports": 42, + "address": "aYJCgU7REfu3XF8b3QhkqgqQvLizx8zxuLBHA25PzDS" + }, + { + "lamports": 42, + "address": "CTvHVtQ4gd4gUcw3bdVgZJJqApXE9nCbbbP4VTS5wE1D" + }, + { + "lamports": 20, + "address": "4fq3xJ6kfrh9RkJQsmVd5gNMvJbuSHfErywvEjNQDPxu" + }, + { + "lamports": 4, + "address": "AXJADheGVp9cruP8WYu46oNkRbeASngN5fPCMVGQqNHa" + }, + { + "lamports": 2, + "address": "8NT8yS6LiwNprgW4yM1jPPow7CwRUotddBVkrkWgYp24" + }, + { + "lamports": 1, + "address": "SysvarEpochSchedu1e111111111111111111111111" + }, + { + "lamports": 1, + "address": "11111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "Stake11111111111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "SysvarC1ock11111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "StakeConfig11111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "SysvarRent111111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "Config1111111111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "SysvarStakeHistory1111111111111111111111111" + }, + { + "lamports": 1, + "address": "SysvarRecentB1ockHashes11111111111111111111" + }, + { + "lamports": 1, + "address": "SysvarFees111111111111111111111111111111111" + }, + { + "lamports": 1, + "address": "Vote111111111111111111111111111111111111111" + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getLatestBlockhash.mdx b/docs/rpc/http/getLatestBlockhash.mdx new file mode 100644 index 000000000..de5adffae --- /dev/null +++ b/docs/rpc/http/getLatestBlockhash.mdx @@ -0,0 +1,91 @@ +--- +sidebarLabel: getLatestBlockhash +title: getLatestBlockhash RPC Method +sidebarSortOrder: 0 +hideTableOfContents: true +altRoutes: + - /docs/rpc/getLatestBlockhash +--- + +Returns the latest blockhash + + + This method is only available in `solana-core` v1.9 or newer. Please use + [getRecentBlockhash](/docs/rpc/http/getRecentBlockhash) for `solana-core` v1.8 + and below. + + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +`RpcResponse` - RpcResponse JSON object with `value` field set to a JSON +object including: + +- `blockhash: ` - a Hash as base-58 encoded string +- `lastValidBlockHeight: ` - last + [block height](/docs/terminology.md#block-height) at which the blockhash will + be valid + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "id":1, + "jsonrpc":"2.0", + "method":"getLatestBlockhash", + "params":[ + { + "commitment":"processed" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 2792 + }, + "value": { + "blockhash": "EkSnNWid2cvwEVnVx9aBqawnmiCNiDgp3gUdkDPTKN1N", + "lastValidBlockHeight": 3090 + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getLeaderSchedule.mdx b/docs/rpc/http/getLeaderSchedule.mdx new file mode 100644 index 000000000..a9cfc232e --- /dev/null +++ b/docs/rpc/http/getLeaderSchedule.mdx @@ -0,0 +1,93 @@ +--- +sidebarLabel: getLeaderSchedule +title: getLeaderSchedule RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getLeaderSchedule +--- + +Returns the leader schedule for an epoch + + + + + +### Parameters + + + +Fetch the leader schedule for the epoch that corresponds to the provided slot. + + + If unspecified, the leader schedule for the current epoch is fetched + + + + + + +Configuration object containing the following fields: + + + + + Only return results for this validator identity (base-58 encoded) + + + + +### Result + +Returns a result with one of the two following values: + +- `` - if requested epoch is not found, or +- `` - the result field will be a dictionary of validator identities, as + base-58 encoded strings, and their corresponding leader slot indices as values + (indices are relative to the first slot in the requested epoch) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getLeaderSchedule", + "params": [ + null, + { + "identity": "4Qkev8aNZcqFNSRhQzwyLMFSsi94jHqE8WNVTJzTP99F" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "4Qkev8aNZcqFNSRhQzwyLMFSsi94jHqE8WNVTJzTP99F": [ + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, + 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, + 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, + 57, 58, 59, 60, 61, 62, 63 + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getMaxRetransmitSlot.mdx b/docs/rpc/http/getMaxRetransmitSlot.mdx new file mode 100644 index 000000000..9def26990 --- /dev/null +++ b/docs/rpc/http/getMaxRetransmitSlot.mdx @@ -0,0 +1,42 @@ +--- +sidebarLabel: getMaxRetransmitSlot +title: getMaxRetransmitSlot RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getMaxRetransmitSlot +--- + +Get the max slot seen from retransmit stage. + + + + + +### Parameters + +**None** + +### Result + +`` - Slot number + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getMaxRetransmitSlot"} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 1234, "id": 1 } +``` + + + diff --git a/docs/rpc/http/getMaxShredInsertSlot.mdx b/docs/rpc/http/getMaxShredInsertSlot.mdx new file mode 100644 index 000000000..efa971b39 --- /dev/null +++ b/docs/rpc/http/getMaxShredInsertSlot.mdx @@ -0,0 +1,42 @@ +--- +sidebarLabel: getMaxShredInsertSlot +title: getMaxShredInsertSlot RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getMaxShredInsertSlot +--- + +Get the max slot seen from after shred insert. + + + + + +### Parameters + +**None** + +### Result + +`` - Slot number + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getMaxShredInsertSlot"} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 1234, "id": 1 } +``` + + + diff --git a/docs/rpc/http/getMinimumBalanceForRentExemption.mdx b/docs/rpc/http/getMinimumBalanceForRentExemption.mdx new file mode 100644 index 000000000..445d3f011 --- /dev/null +++ b/docs/rpc/http/getMinimumBalanceForRentExemption.mdx @@ -0,0 +1,62 @@ +--- +sidebarLabel: getMinimumBalanceForRentExemption +title: getMinimumBalanceForRentExemption RPC Method +sidebarSortOrder: 0 +hideTableOfContents: true +altRoutes: + - /docs/rpc/getMinimumBalanceForRentExemption +--- + +Returns minimum balance required to make account rent exempt. + + + + + +### Parameters + + + the Account's data length + + + + +Configuration object containing the following fields: + + + + + +### Result + +`` - minimum lamports required in the Account to remain rent free + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getMinimumBalanceForRentExemption", + "params": [50] + } +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 500, "id": 1 } +``` + + + diff --git a/docs/rpc/http/getMultipleAccounts.mdx b/docs/rpc/http/getMultipleAccounts.mdx new file mode 100644 index 000000000..3ecc5e58c --- /dev/null +++ b/docs/rpc/http/getMultipleAccounts.mdx @@ -0,0 +1,156 @@ +--- +sidebarLabel: getMultipleAccounts +title: getMultipleAccounts RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getMultipleAccounts +--- + +Returns the account information for a list of Pubkeys. + + + + + +### Parameters + + + An array of Pubkeys to query, as base-58 encoded strings (up to a maximum of + 100) + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + Request a slice of the account's data. + +- `length: ` - number of bytes to return +- `offset: ` - byte offset from which to start reading + + + Data slicing is only available for `base58`, `base64`, or `base64+zstd` + encodings. + + + + + + +encoding format for the returned Account data + + + +
+ +- `base58` is slow and limited to less than 129 bytes of Account data. +- `base64` will return base64 encoded data for Account data of any size. +- `base64+zstd` compresses the Account data using + [Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to `base64` encoding, detectable when the `data` field is type + ``. + +
+ + + + + +### Result + +The result will be a JSON object with `value` equal to an array of: + +- `` - if the account at that Pubkey doesn't exist, or +- `` - a JSON object containing: + - `lamports: ` - number of lamports assigned to this account, as a u64 + - `owner: ` - base-58 encoded Pubkey of the program this account has + been assigned to + - `data: <[string, encoding]|object>` - data associated with the account, + either as encoded binary data or JSON format `{: }` - + depending on encoding parameter + - `executable: ` - boolean indicating if the account contains a program + \(and is strictly read-only\) + - `rentEpoch: ` - the epoch at which this account will next owe rent, as + u64 + - `size: ` - the data size of the account + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getMultipleAccounts", + "params": [ + [ + "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg", + "4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA" + ], + { + "encoding": "base58" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1 + }, + "value": [ + { + "data": ["", "base64"], + "executable": false, + "lamports": 1000000000, + "owner": "11111111111111111111111111111111", + "rentEpoch": 2, + "space": 16 + }, + { + "data": ["", "base64"], + "executable": false, + "lamports": 5000000000, + "owner": "11111111111111111111111111111111", + "rentEpoch": 2, + "space": 0 + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getProgramAccounts.mdx b/docs/rpc/http/getProgramAccounts.mdx new file mode 100644 index 000000000..cce47ba3d --- /dev/null +++ b/docs/rpc/http/getProgramAccounts.mdx @@ -0,0 +1,180 @@ +--- +sidebarLabel: getProgramAccounts +title: getProgramAccounts RPC Method +sidebarSortOrder: 10 +hideTableOfContents: true +altRoutes: + - /docs/rpc/getProgramAccounts +--- + +Returns all accounts owned by the provided program Pubkey + + + + + +### Parameters + + + Pubkey of program, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + wrap the result in an RpcResponse JSON object + + + + +encoding format for the returned Account data + + + +
+ +- `base58` is slow and limited to less than 129 bytes of Account data. +- `base64` will return base64 encoded data for Account data of any size. +- `base64+zstd` compresses the Account data using + [Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to `base64` encoding, detectable when the `data` field is type + ``. + +
+ + + + + Request a slice of the account's data. + +- `length: ` - number of bytes to return +- `offset: ` - byte offset from which to start reading + + + Data slicing is only available for `base58`, `base64`, or `base64+zstd` + encodings. + + + + + + +filter results using up to 4 filter objects + + + The resultant account(s) must meet **ALL** filter criteria to be included in + the returned results + + + + + + +### Result + +By default, the result field will be an array of JSON objects. + + + If the `withContext` flag is set, the array will be wrapped in an + `RpcResponse` JSON object. + + +The resultant response array will contain: + +- `pubkey: ` - the account Pubkey as base-58 encoded string +- `account: ` - a JSON object, with the following sub fields: + - `lamports: ` - number of lamports assigned to this account, as a u64 + - `owner: ` - base-58 encoded Pubkey of the program this account has + been assigned to + - `data: <[string,encoding]|object>` - data associated with the account, + either as encoded binary data or JSON format `{: }` - + depending on encoding parameter + - `executable: ` - boolean indicating if the account contains a program + \(and is strictly read-only\) + - `rentEpoch: ` - the epoch at which this account will next owe rent, as + u64 + - `size: ` - the data size of the account + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getProgramAccounts", + "params": [ + "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T", + { + "filters": [ + { + "dataSize": 17 + }, + { + "memcmp": { + "offset": 4, + "bytes": "3Mc6vR" + } + } + ] + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "account": { + "data": "2R9jLfiAQ9bgdcw6h8s44439", + "executable": false, + "lamports": 15298080, + "owner": "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T", + "rentEpoch": 28, + "space": 42 + }, + "pubkey": "CxELquR1gPP8wHe33gZ4QxqGB3sZ9RSwsJ2KshVewkFY" + } + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getRecentPerformanceSamples.mdx b/docs/rpc/http/getRecentPerformanceSamples.mdx new file mode 100644 index 000000000..88bb4b06d --- /dev/null +++ b/docs/rpc/http/getRecentPerformanceSamples.mdx @@ -0,0 +1,99 @@ +--- +sidebarLabel: getRecentPerformanceSamples +title: getRecentPerformanceSamples RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getRecentPerformanceSamples +--- + +Returns a list of recent performance samples, in reverse slot order. Performance +samples are taken every 60 seconds and include the number of transactions and +slots that occur in a given time window. + + + + + +### Parameters + + + +number of samples to return (maximum 720) + + + +### Result + +An array of `RpcPerfSample` with the following fields: + +- `slot: ` - Slot in which sample was taken at +- `numTransactions: ` - Number of transactions processed during the sample + period +- `numSlots: ` - Number of slots completed during the sample period +- `samplePeriodSecs: ` - Number of seconds in a sample window +- `numNonVoteTransaction: ` - Number of non-vote transactions processed + during the sample period. + + + `numNonVoteTransaction` is present starting with v1.15. To get a number of + voting transactions compute: +
+ `numTransactions - numNonVoteTransaction` + + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0", "id":1, + "method": "getRecentPerformanceSamples", + "params": [4]} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "numSlots": 126, + "numTransactions": 126, + "numNonVoteTransaction": 1, + "samplePeriodSecs": 60, + "slot": 348125 + }, + { + "numSlots": 126, + "numTransactions": 126, + "numNonVoteTransaction": 1, + "samplePeriodSecs": 60, + "slot": 347999 + }, + { + "numSlots": 125, + "numTransactions": 125, + "numNonVoteTransaction": 0, + "samplePeriodSecs": 60, + "slot": 347873 + }, + { + "numSlots": 125, + "numTransactions": 125, + "numNonVoteTransaction": 0, + "samplePeriodSecs": 60, + "slot": 347748 + } + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getRecentPrioritizationFees.mdx b/docs/rpc/http/getRecentPrioritizationFees.mdx new file mode 100644 index 000000000..0392bcda9 --- /dev/null +++ b/docs/rpc/http/getRecentPrioritizationFees.mdx @@ -0,0 +1,93 @@ +--- +sidebarLabel: getRecentPrioritizationFees +title: getRecentPrioritizationFees RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getRecentPrioritizationFees +--- + +Returns a list of prioritization fees from recent blocks. + + + Currently, a node's prioritization-fee cache stores data from up to 150 + blocks. + + + + + + +### Parameters + + + +An array of Account addresses (up to a maximum of 128 addresses), as base-58 +encoded strings + + + If this parameter is provided, the response will reflect a fee to land a + transaction locking all of the provided accounts as writable. + + + + +### Result + +An array of `RpcPrioritizationFee` with the following fields: + +- `slot: ` - slot in which the fee was observed +- `prioritizationFee: ` - the per-compute-unit fee paid by at least one + successfully landed transaction, specified in increments of micro-lamports + (0.000001 lamports) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0", "id":1, + "method": "getRecentPrioritizationFees", + "params": [ + ["CxELquR1gPP8wHe33gZ4QxqGB3sZ9RSwsJ2KshVewkFY"] + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "slot": 348125, + "prioritizationFee": 0 + }, + { + "slot": 348126, + "prioritizationFee": 1000 + }, + { + "slot": 348127, + "prioritizationFee": 500 + }, + { + "slot": 348128, + "prioritizationFee": 0 + }, + { + "slot": 348129, + "prioritizationFee": 1234 + } + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getSignatureStatuses.mdx b/docs/rpc/http/getSignatureStatuses.mdx new file mode 100644 index 000000000..3adc2a6e3 --- /dev/null +++ b/docs/rpc/http/getSignatureStatuses.mdx @@ -0,0 +1,115 @@ +--- +sidebarLabel: getSignatureStatuses +title: getSignatureStatuses RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSignatureStatuses +--- + +Returns the statuses of a list of signatures. Each signature must be a +[txid](/docs/terminology.md#transaction-id), the first signature of a +transaction. + + + Unless the `searchTransactionHistory` configuration parameter is included, + this method only searches the recent status cache of signatures, which retains + statuses for all active slots plus `MAX_RECENT_BLOCKHASHES` rooted slots. + + + + + + +### Parameters + + + An array of transaction signatures to confirm, as base-58 encoded strings (up + to a maximum of 256) + + + + +Configuration object containing the following fields: + + + +if `true` - a Solana node will search its ledger cache for any signatures not +found in the recent status cache + + + + + +### Result + +An array of `RpcResponse` consisting of either: + +- `` - Unknown transaction, or +- `` + - `slot: ` - The slot the transaction was processed + - `confirmations: ` - Number of blocks since signature + confirmation, null if rooted, as well as finalized by a supermajority of the + cluster + - `err: ` - Error if transaction failed, null if transaction + succeeded. See + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) + - `confirmationStatus: ` - The transaction's cluster confirmation + status; Either `processed`, `confirmed`, or `finalized`. See + [Commitment](/docs/rpc/index.mdx#configuring-state-commitment) for more on + optimistic confirmation. + - DEPRECATED: `status: ` - Transaction status + - `"Ok": ` - Transaction was successful + - `"Err": ` - Transaction failed with TransactionError + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getSignatureStatuses", + "params": [ + [ + "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW" + ], + { + "searchTransactionHistory": true + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 82 + }, + "value": [ + { + "slot": 48, + "confirmations": null, + "err": null, + "status": { + "Ok": null + }, + "confirmationStatus": "finalized" + }, + null + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getSignaturesForAddress.mdx b/docs/rpc/http/getSignaturesForAddress.mdx new file mode 100644 index 000000000..c50e22364 --- /dev/null +++ b/docs/rpc/http/getSignaturesForAddress.mdx @@ -0,0 +1,116 @@ +--- +sidebarLabel: getSignaturesForAddress +title: getSignaturesForAddress RPC Method +sidebarSortOrder: 10 +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSignaturesForAddress +--- + +Returns signatures for confirmed transactions that include the given address in +their `accountKeys` list. Returns signatures backwards in time from the provided +signature or most recent confirmed block + + + + + +### Parameters + + + Account address as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + maximum transaction signatures to return (between 1 and 1,000). + + + + start searching backwards from this transaction signature. If not provided the + search starts from the top of the highest max confirmed block. + + + + search until this transaction signature, if found before limit reached + + + + +### Result + +An array of ``, ordered from **newest** to **oldest** transaction, +containing transaction signature information with the following fields: + +- `signature: ` - transaction signature as base-58 encoded string +- `slot: ` - The slot that contains the block with the transaction +- `err: ` - Error if transaction failed, null if transaction + succeeded. See + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) + for more info. +- `memo: ` - Memo associated with the transaction, null if no memo + is present +- `blockTime: ` - estimated production time, as Unix timestamp + (seconds since the Unix epoch) of when transaction was processed. null if not + available. +- `confirmationStatus: ` - The transaction's cluster confirmation + status; Either `processed`, `confirmed`, or `finalized`. See + [Commitment](/docs/rpc/index.mdx#configuring-state-commitment) for more on + optimistic confirmation. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getSignaturesForAddress", + "params": [ + "Vote111111111111111111111111111111111111111", + { + "limit": 1 + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "err": null, + "memo": null, + "signature": "5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv", + "slot": 114, + "blockTime": null + } + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getSlot.mdx b/docs/rpc/http/getSlot.mdx new file mode 100644 index 000000000..4439f4ad5 --- /dev/null +++ b/docs/rpc/http/getSlot.mdx @@ -0,0 +1,58 @@ +--- +sidebarLabel: getSlot +title: getSlot RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSlot +--- + +Returns the slot that has reached the +[given or default commitment level](/docs/rpc/index.mdx#configuring-state-commitment) + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +`` - Current slot + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getSlot"} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 1234, "id": 1 } +``` + + + diff --git a/docs/rpc/http/getSlotLeader.mdx b/docs/rpc/http/getSlotLeader.mdx new file mode 100644 index 000000000..bac7b1a49 --- /dev/null +++ b/docs/rpc/http/getSlotLeader.mdx @@ -0,0 +1,61 @@ +--- +sidebarLabel: getSlotLeader +title: getSlotLeader RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSlotLeader +--- + +Returns the current slot leader + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +`` - Node identity Pubkey as base-58 encoded string + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getSlotLeader"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": "ENvAW7JScgYq6o4zKZwewtkzzJgDzuJAFxYasvmEQdpS", + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getSlotLeaders.mdx b/docs/rpc/http/getSlotLeaders.mdx new file mode 100644 index 000000000..9e13db0dd --- /dev/null +++ b/docs/rpc/http/getSlotLeaders.mdx @@ -0,0 +1,73 @@ +--- +sidebarLabel: getSlotLeaders +title: getSlotLeaders RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSlotLeaders +--- + +Returns the slot leaders for a given slot range + + + + + +### Parameters + + + Start slot, as u64 integer + + + + Limit, as u64 integer (between 1 and 5,000) + + +### Result + +`` - array of Node identity public keys as base-58 encoded +strings + + + + + +### Code sample + +If the current slot is `#99` - query the next `10` leaders with the following +request: + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0", "id": 1, + "method": "getSlotLeaders", + "params": [100, 10] + } +' +``` + +### Response + +The first leader returned is the leader for slot `#100`: + +```json +{ + "jsonrpc": "2.0", + "result": [ + "ChorusmmK7i1AxXeiTtQgQZhQNiXYU84ULeaYF1EH15n", + "ChorusmmK7i1AxXeiTtQgQZhQNiXYU84ULeaYF1EH15n", + "ChorusmmK7i1AxXeiTtQgQZhQNiXYU84ULeaYF1EH15n", + "ChorusmmK7i1AxXeiTtQgQZhQNiXYU84ULeaYF1EH15n", + "Awes4Tr6TX8JDzEhCZY2QVNimT6iD1zWHzf1vNyGvpLM", + "Awes4Tr6TX8JDzEhCZY2QVNimT6iD1zWHzf1vNyGvpLM", + "Awes4Tr6TX8JDzEhCZY2QVNimT6iD1zWHzf1vNyGvpLM", + "Awes4Tr6TX8JDzEhCZY2QVNimT6iD1zWHzf1vNyGvpLM", + "DWvDTSh3qfn88UoQTEKRV2JnLt5jtJAVoiCo3ivtMwXP", + "DWvDTSh3qfn88UoQTEKRV2JnLt5jtJAVoiCo3ivtMwXP" + ], + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getStakeActivation.mdx b/docs/rpc/http/getStakeActivation.mdx new file mode 100644 index 000000000..93e47f04e --- /dev/null +++ b/docs/rpc/http/getStakeActivation.mdx @@ -0,0 +1,90 @@ +--- +sidebarLabel: getStakeActivation +title: getStakeActivation RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getStakeActivation +--- + +Returns epoch activation information for a stake account + + + + + +### Parameters + + + Pubkey of stake Account to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + epoch for which to calculate activation details. If parameter not provided, + defaults to current epoch. **DEPRECATED**, inputs other than the current epoch + return an error. + + + + +### Result + +The result will be a JSON object with the following fields: + +- `state: ` - the stake account's activation state, either: `active`, + `inactive`, `activating`, or `deactivating` +- `active: ` - stake active during the epoch +- `inactive: ` - stake inactive during the epoch + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getStakeActivation", + "params": [ + "CYRJWqiSjLitBAcRxPvWpgX3s5TvmN2SuRY3eEYypFvT", + { + "epoch": 4 + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "active": 124429280, + "inactive": 73287840, + "state": "activating" + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getStakeMinimumDelegation.mdx b/docs/rpc/http/getStakeMinimumDelegation.mdx new file mode 100644 index 000000000..40b447e2c --- /dev/null +++ b/docs/rpc/http/getStakeMinimumDelegation.mdx @@ -0,0 +1,67 @@ +--- +sidebarLabel: getStakeMinimumDelegation +title: getStakeMinimumDelegation RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getStakeMinimumDelegation +--- + +Returns the stake minimum delegation, in lamports. + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to: + +- `` - The stake minimum delegation, in lamports + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc":"2.0", "id":1, + "method": "getStakeMinimumDelegation" + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 501 + }, + "value": 1000000000 + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getSupply.mdx b/docs/rpc/http/getSupply.mdx new file mode 100644 index 000000000..79b81f13c --- /dev/null +++ b/docs/rpc/http/getSupply.mdx @@ -0,0 +1,84 @@ +--- +sidebarLabel: getSupply +title: getSupply RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getSupply +--- + +Returns information about the current supply. + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + exclude non circulating accounts list from response + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to a JSON +object containing: + +- `total: ` - Total supply in lamports +- `circulating: ` - Circulating supply in lamports +- `nonCirculating: ` - Non-circulating supply in lamports +- `nonCirculatingAccounts: ` - an array of account addresses of + non-circulating accounts, as strings. If `excludeNonCirculatingAccountsList` + is enabled, the returned array will be empty. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0", "id":1, "method":"getSupply"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1114 + }, + "value": { + "circulating": 16000, + "nonCirculating": 1000000, + "nonCirculatingAccounts": [ + "FEy8pTbP5fEoqMV1GdTz83byuA8EKByqYat1PKDgVAq5", + "9huDUZfxoJ7wGMTffUE7vh1xePqef7gyrLJu9NApncqA", + "3mi1GmwEE3zo2jmfDuzvjSX9ovRXsDUKHvsntpkhuLJ9", + "BYxEJTDerkaRWBem3XgnVcdhppktBXa2HbkHPKj2Ui4Z" + ], + "total": 1016000 + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getTokenAccountBalance.mdx b/docs/rpc/http/getTokenAccountBalance.mdx new file mode 100644 index 000000000..a427e208c --- /dev/null +++ b/docs/rpc/http/getTokenAccountBalance.mdx @@ -0,0 +1,90 @@ +--- +sidebarLabel: getTokenAccountBalance +title: getTokenAccountBalance RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTokenAccountBalance +--- + +Returns the token balance of an SPL Token account. + + + + + +### Parameters + + + Pubkey of Token account to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to a JSON +object containing: + +- `amount: ` - the raw balance without decimals, a string representation + of u64 +- `decimals: ` - number of base 10 digits to the right of the decimal place +- `uiAmount: ` - the balance, using mint-prescribed decimals + **DEPRECATED** +- `uiAmountString: ` - the balance as a string, using mint-prescribed + decimals + +For more details on returned data, the +[Token Balances Structure](/docs/rpc/json-structures#token-balances) response +from [getBlock](/docs/rpc/http/getblock) follows a similar structure. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getTokenAccountBalance", + "params": [ + "7fUAJdStEuGbc3sM84cKRL6yYaaSstyLSU4ve5oovLS7" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1114 + }, + "value": { + "amount": "9864", + "decimals": 2, + "uiAmount": 98.64, + "uiAmountString": "98.64" + }, + "id": 1 + } +} +``` + + + diff --git a/docs/rpc/http/getTokenAccountsByDelegate.mdx b/docs/rpc/http/getTokenAccountsByDelegate.mdx new file mode 100644 index 000000000..766ecdbcd --- /dev/null +++ b/docs/rpc/http/getTokenAccountsByDelegate.mdx @@ -0,0 +1,189 @@ +--- +sidebarLabel: getTokenAccountsByDelegate +title: getTokenAccountsByDelegate RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTokenAccountsByDelegate +--- + +Returns all SPL Token accounts by approved Delegate. + + + + + +### Parameters + + + Pubkey of account delegate to query, as base-58 encoded string + + + + +A JSON object with one of the following fields: + +- `mint: ` - Pubkey of the specific token Mint to limit accounts to, as + base-58 encoded string; or +- `programId: ` - Pubkey of the Token program that owns the accounts, as + base-58 encoded string + + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + Request a slice of the account's data. + +- `length: ` - number of bytes to return +- `offset: ` - byte offset from which to start reading + + + Data slicing is only available for `base58`, `base64`, or `base64+zstd` + encodings. + + + + + + +Encoding format for Account data + + + +
+ +- `base58` is slow and limited to less than 129 bytes of Account data. +- `base64` will return base64 encoded data for Account data of any size. +- `base64+zstd` compresses the Account data using + [Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to `base64` encoding, detectable when the `data` field is type `string`. + +
+ + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to an array of +JSON objects, which will contain: + +- `pubkey: ` - the account Pubkey as base-58 encoded string +- `account: ` - a JSON object, with the following sub fields: + - `lamports: ` - number of lamports assigned to this account, as a u64 + - `owner: ` - base-58 encoded Pubkey of the program this account has + been assigned to + - `data: ` - Token state data associated with the account, either as + encoded binary data or in JSON format `{: }` + - `executable: ` - boolean indicating if the account contains a program + (and is strictly read-only\) + - `rentEpoch: ` - the epoch at which this account will next owe rent, as + u64 + - `size: ` - the data size of the account + +When the data is requested with the `jsonParsed` encoding a format similar to +that of the [Token Balances Structure](/docs/rpc/json-structures#token-balances) +can be expected inside the structure, both for the `tokenAmount` and the +`delegatedAmount` - with the latter being an optional object. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getTokenAccountsByDelegate", + "params": [ + "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T", + { + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" + }, + { + "encoding": "jsonParsed" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1114 + }, + "value": [ + { + "account": { + "data": { + "program": "spl-token", + "parsed": { + "info": { + "tokenAmount": { + "amount": "1", + "decimals": 1, + "uiAmount": 0.1, + "uiAmountString": "0.1" + }, + "delegate": "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T", + "delegatedAmount": { + "amount": "1", + "decimals": 1, + "uiAmount": 0.1, + "uiAmountString": "0.1" + }, + "state": "initialized", + "isNative": false, + "mint": "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E", + "owner": "CnPoSPKXu7wJqxe59Fs72tkBeALovhsCxYeFwPCQH9TD" + }, + "type": "account" + }, + "space": 165 + }, + "executable": false, + "lamports": 1726080, + "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", + "rentEpoch": 4, + "space": 165 + }, + "pubkey": "28YTZEwqtMHWrhWcvv34se7pjS7wctgqzCPB3gReCFKp" + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getTokenAccountsByOwner.mdx b/docs/rpc/http/getTokenAccountsByOwner.mdx new file mode 100644 index 000000000..b5aae7281 --- /dev/null +++ b/docs/rpc/http/getTokenAccountsByOwner.mdx @@ -0,0 +1,190 @@ +--- +sidebarLabel: getTokenAccountsByOwner +title: getTokenAccountsByOwner RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTokenAccountsByOwner +--- + +Returns all SPL Token accounts by token owner. + + + + + +### Parameters + + + Pubkey of account delegate to query, as base-58 encoded string + + + + +A JSON object with one of the following fields: + +- `mint: ` - Pubkey of the specific token Mint to limit accounts to, as + base-58 encoded string; or +- `programId: ` - Pubkey of the Token program that owns the accounts, as + base-58 encoded string + + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + Request a slice of the account's data. + +- `length: ` - number of bytes to return +- `offset: ` - byte offset from which to start reading + + + Data slicing is only available for `base58`, `base64`, or `base64+zstd` + encodings. + + + + + + +Encoding format for Account data + + + +
+ +- `base58` is slow and limited to less than 129 bytes of Account data. +- `base64` will return base64 encoded data for Account data of any size. +- `base64+zstd` compresses the Account data using + [Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to `base64` encoding, detectable when the `data` field is type `string`. + +
+ + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to an array of +JSON objects, which will contain: + +- `pubkey: ` - the account Pubkey as base-58 encoded string +- `account: ` - a JSON object, with the following sub fields: + - `lamports: ` - number of lamports assigned to this account, as a u64 + - `owner: ` - base-58 encoded Pubkey of the program this account has + been assigned to + - `data: ` - Token state data associated with the account, either as + encoded binary data or in JSON format `{: }` + - `executable: ` - boolean indicating if the account contains a program + \(and is strictly read-only\) + - `rentEpoch: ` - the epoch at which this account will next owe rent, as + u64 + - `size: ` - the data size of the account + +When the data is requested with the `jsonParsed` encoding a format similar to +that of the [Token Balances Structure](/docs/rpc/json-structures#token-balances) +can be expected inside the structure, both for the `tokenAmount` and the +`delegatedAmount` - with the latter being an optional object. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getTokenAccountsByOwner", + "params": [ + "4Qkev8aNZcqFNSRhQzwyLMFSsi94jHqE8WNVTJzTP99F", + { + "mint": "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E" + }, + { + "encoding": "jsonParsed" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1114 + }, + "value": [ + { + "account": { + "data": { + "program": "spl-token", + "parsed": { + "accountType": "account", + "info": { + "tokenAmount": { + "amount": "1", + "decimals": 1, + "uiAmount": 0.1, + "uiAmountString": "0.1" + }, + "delegate": "4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T", + "delegatedAmount": { + "amount": "1", + "decimals": 1, + "uiAmount": 0.1, + "uiAmountString": "0.1" + }, + "state": "initialized", + "isNative": false, + "mint": "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E", + "owner": "4Qkev8aNZcqFNSRhQzwyLMFSsi94jHqE8WNVTJzTP99F" + }, + "type": "account" + }, + "space": 165 + }, + "executable": false, + "lamports": 1726080, + "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", + "rentEpoch": 4, + "space": 165 + }, + "pubkey": "C2gJg6tKpQs41PRS1nC8aw3ZKNZK3HQQZGVrDFDup5nx" + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getTokenLargestAccounts.mdx b/docs/rpc/http/getTokenLargestAccounts.mdx new file mode 100644 index 000000000..434bb924e --- /dev/null +++ b/docs/rpc/http/getTokenLargestAccounts.mdx @@ -0,0 +1,97 @@ +--- +sidebarLabel: getTokenLargestAccounts +title: getTokenLargestAccounts RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTokenLargestAccounts +--- + +Returns the 20 largest accounts of a particular SPL Token type. + + + + + +### Parameters + + + Pubkey of the token Mint to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to an array of +JSON objects containing: + +- `address: ` - the address of the token account +- `amount: ` - the raw token account balance without decimals, a string + representation of u64 +- `decimals: ` - number of base 10 digits to the right of the decimal place +- `uiAmount: ` - the token account balance, using mint-prescribed + decimals **DEPRECATED** +- `uiAmountString: ` - the token account balance as a string, using + mint-prescribed decimals + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getTokenLargestAccounts", + "params": [ + "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1114 + }, + "value": [ + { + "address": "FYjHNoFtSQ5uijKrZFyYAxvEr87hsKXkXcxkcmkBAf4r", + "amount": "771", + "decimals": 2, + "uiAmount": 7.71, + "uiAmountString": "7.71" + }, + { + "address": "BnsywxTcaYeNUtzrPxQUvzAWxfzZe3ZLUJ4wMMuLESnu", + "amount": "229", + "decimals": 2, + "uiAmount": 2.29, + "uiAmountString": "2.29" + } + ] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getTokenSupply.mdx b/docs/rpc/http/getTokenSupply.mdx new file mode 100644 index 000000000..353433f15 --- /dev/null +++ b/docs/rpc/http/getTokenSupply.mdx @@ -0,0 +1,86 @@ +--- +sidebarLabel: getTokenSupply +title: getTokenSupply RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTokenSupply +--- + +Returns the total supply of an SPL Token type. + + + + + +### Parameters + + + Pubkey of the token Mint to query, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` equal to a JSON +object containing: + +- `amount: ` - the raw total token supply without decimals, a string + representation of u64 +- `decimals: ` - number of base 10 digits to the right of the decimal place +- `uiAmount: ` - the total token supply, using mint-prescribed + decimals **DEPRECATED** +- `uiAmountString: ` - the total token supply as a string, using + mint-prescribed decimals + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "getTokenSupply", + "params": [ + "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 1114 + }, + "value": { + "amount": "100000", + "decimals": 2, + "uiAmount": 1000, + "uiAmountString": "1000" + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getTransaction.mdx b/docs/rpc/http/getTransaction.mdx new file mode 100644 index 000000000..b176d9710 --- /dev/null +++ b/docs/rpc/http/getTransaction.mdx @@ -0,0 +1,210 @@ +--- +sidebarLabel: getTransaction +title: getTransaction RPC Method +sidebarSortOrder: 10 +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTransaction +--- + +Returns transaction details for a confirmed transaction + + + + + +### Parameters + + + Transaction signature, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + Set the max transaction version to return in responses. If the requested + transaction is a higher version, an error will be returned. If this parameter + is omitted, only legacy transactions will be returned, and any versioned + transaction will prompt the error. + + + + +Encoding for the returned Transaction + + + +
+ +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit data in the + `transaction.message.instructions` list. +- If `jsonParsed` is requested but a parser cannot be found, the instruction + falls back to regular JSON encoding (`accounts`, `data`, and `programIdIndex` + fields). + +
+ + + + + +### Result + +- `` - if transaction is not found or not confirmed +- `` - if transaction is confirmed, an object with the following fields: + - `slot: ` - the slot this transaction was processed in + - `transaction: ` - + [Transaction](/docs/rpc/json-structures#transactions) object, either in JSON + format or encoded binary data, depending on encoding parameter + - `blockTime: ` - estimated production time, as Unix timestamp + (seconds since the Unix epoch) of when the transaction was processed. null + if not available + - `meta: ` - transaction status metadata object: + - `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://docs.rs/solana-sdk/latest/solana_sdk/transaction/enum.TransactionError.html) + - `fee: ` - fee this transaction was charged, as u64 integer + - `preBalances: ` - array of u64 account balances from before the + transaction was processed + - `postBalances: ` - array of u64 account balances after the + transaction was processed + - `innerInstructions: ` - List of + [inner instructions](/docs/rpc/json-structures#inner-instructions) or + `null` if inner instruction recording was not enabled during this + transaction + - `preTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from before the + transaction was processed or omitted if token balance recording was not + yet enabled during this transaction + - `postTokenBalances: ` - List of + [token balances](/docs/rpc/json-structures#token-balances) from after the + transaction was processed or omitted if token balance recording was not + yet enabled during this transaction + - `logMessages: ` - array of string log messages or `null` if + log message recording was not enabled during this transaction + - DEPRECATED: `status: ` - Transaction status + - `"Ok": ` - Transaction was successful + - `"Err": ` - Transaction failed with TransactionError + - `rewards: ` - transaction-level rewards, populated if rewards + are requested; an array of JSON objects containing: + - `pubkey: ` - The public key, as base-58 encoded string, of the + account that received the reward + - `lamports: `- number of reward lamports credited or debited by the + account, as a i64 + - `postBalance: ` - account balance in lamports after the reward was + applied + - `rewardType: ` - type of reward: currently only "rent", other + types may be added in the future + - `commission: ` - vote account commission when the reward + was credited, only present for voting and staking rewards + - `loadedAddresses: ` - Transaction addresses loaded from + address lookup tables. Undefined if `maxSupportedTransactionVersion` is + not set in request params, or if `jsonParsed` encoding is set in request + params. + - `writable: ` - Ordered list of base-58 encoded addresses + for writable loaded accounts + - `readonly: ` - Ordered list of base-58 encoded addresses + for readonly loaded accounts + - `returnData: ` - the most-recent return data generated + by an instruction in the transaction, with the following fields: + - `programId: ` - the program that generated the return data, as + base-58 encoded Pubkey + - `data: <[string, encoding]>` - the return data itself, as base-64 + encoded binary data + - `computeUnitsConsumed: ` - number of + [compute units](/docs/core/runtime.md#compute-budget) consumed by the + transaction + - `version: <"legacy"|number|undefined>` - Transaction version. Undefined if + `maxSupportedTransactionVersion` is not set in request params. + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getTransaction", + "params": [ + "2nBhEBYYvfaAe16UMNqRHre4YNSskvuYgx3M6E4JP1oDYvZEJHvoPzyUidNgNX5r9sTyN1J9UxtbCXy2rqYcuyuv", + "json" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "meta": { + "err": null, + "fee": 5000, + "innerInstructions": [], + "postBalances": [499998932500, 26858640, 1, 1, 1], + "postTokenBalances": [], + "preBalances": [499998937500, 26858640, 1, 1, 1], + "preTokenBalances": [], + "rewards": [], + "status": { + "Ok": null + } + }, + "slot": 430, + "transaction": { + "message": { + "accountKeys": [ + "3UVYmECPPMZSCqWKfENfuoTv51fTDTWicX9xmBD2euKe", + "AjozzgE83A3x1sHNUR64hfH7zaEBWeMaFuAN9kQgujrc", + "SysvarS1otHashes111111111111111111111111111", + "SysvarC1ock11111111111111111111111111111111", + "Vote111111111111111111111111111111111111111" + ], + "header": { + "numReadonlySignedAccounts": 0, + "numReadonlyUnsignedAccounts": 3, + "numRequiredSignatures": 1 + }, + "instructions": [ + { + "accounts": [1, 2, 3, 0], + "data": "37u9WtQpcm6ULa3WRQHmj49EPs4if7o9f1jSRVZpm2dvihR9C8jY4NqEwXUbLwx15HBSNcP1", + "programIdIndex": 4 + } + ], + "recentBlockhash": "mfcyqEXB3DnHXki6KjjmZck6YjmZLvpAByy2fj4nh6B" + }, + "signatures": [ + "2nBhEBYYvfaAe16UMNqRHre4YNSskvuYgx3M6E4JP1oDYvZEJHvoPzyUidNgNX5r9sTyN1J9UxtbCXy2rqYcuyuv" + ] + } + }, + "blockTime": null, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getTransactionCount.mdx b/docs/rpc/http/getTransactionCount.mdx new file mode 100644 index 000000000..3ad9ccc72 --- /dev/null +++ b/docs/rpc/http/getTransactionCount.mdx @@ -0,0 +1,57 @@ +--- +sidebarLabel: getTransactionCount +title: getTransactionCount RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getTransactionCount +--- + +Returns the current Transaction count from the ledger + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +`` - the current Transaction count from the ledger + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getTransactionCount"} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 268, "id": 1 } +``` + + + diff --git a/docs/rpc/http/getVersion.mdx b/docs/rpc/http/getVersion.mdx new file mode 100644 index 000000000..766cbbf24 --- /dev/null +++ b/docs/rpc/http/getVersion.mdx @@ -0,0 +1,50 @@ +--- +sidebarLabel: getVersion +title: getVersion RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getVersion +--- + +Returns the current Solana version running on the node + + + + + +### Parameters + +**None** + +### Result + +The result field will be a JSON object with the following fields: + +- `solana-core` - software version of solana-core as a `string` +- `feature-set` - unique identifier of the current software's feature set as a + `u32` + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"getVersion"} +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { "feature-set": 2891131721, "solana-core": "1.16.7" }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/getVoteAccounts.mdx b/docs/rpc/http/getVoteAccounts.mdx new file mode 100644 index 000000000..864200408 --- /dev/null +++ b/docs/rpc/http/getVoteAccounts.mdx @@ -0,0 +1,113 @@ +--- +sidebarLabel: getVoteAccounts +title: getVoteAccounts RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/getVoteAccounts +--- + +Returns the account info and associated stake for all the voting accounts in the +current bank. + + + + + +### Parameters + + + +Configuration object containing the following fields: + + + + + Only return results for this validator vote address (base-58 encoded) + + + + Do not filter out delinquent validators with no stake + + + + Specify the number of slots behind the tip that a validator must fall to be + considered delinquent. **NOTE:** For the sake of consistency between ecosystem + products, _it is **not** recommended that this argument be specified._ + + + + +### Result + +The result field will be a JSON object of `current` and `delinquent` accounts, +each containing an array of JSON objects with the following sub fields: + +- `votePubkey: ` - Vote account address, as base-58 encoded string +- `nodePubkey: ` - Validator identity, as base-58 encoded string +- `activatedStake: ` - the stake, in lamports, delegated to this vote + account and active in this epoch +- `epochVoteAccount: ` - bool, whether the vote account is staked for this + epoch +- `commission: ` - percentage (0-100) of rewards payout owed to the vote + account +- `lastVote: ` - Most recent slot voted on by this vote account +- `epochCredits: ` - Latest history of earned credits for up to five + epochs, as an array of arrays containing: `[epoch, credits, previousCredits]`. +- `rootSlot: ` - Current root slot for this vote account + + + + + +### Code sample + +Restrict results to a single validator vote account: + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getVoteAccounts", + "params": [ + { + "votePubkey": "3ZT31jkAGhUaw8jsy4bTknwBMP8i4Eueh52By4zXcsVw" + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "current": [ + { + "commission": 0, + "epochVoteAccount": true, + "epochCredits": [ + [1, 64, 0], + [2, 192, 64] + ], + "nodePubkey": "B97CCUW3AEZFGy6uUg6zUdnNYvnVq5VG8PUtb2HayTDD", + "lastVote": 147, + "activatedStake": 42, + "votePubkey": "3ZT31jkAGhUaw8jsy4bTknwBMP8i4Eueh52By4zXcsVw" + } + ], + "delinquent": [] + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/index.mdx b/docs/rpc/http/index.mdx new file mode 100644 index 000000000..9182e8a89 --- /dev/null +++ b/docs/rpc/http/index.mdx @@ -0,0 +1,103 @@ +--- +title: Solana RPC HTTP Methods +seoTitle: Solana RPC HTTP Methods +sidebarLabel: HTTP Methods +sidebarSortOrder: 0 +hideTableOfContents: false +--- + +Solana nodes accept HTTP requests using the +[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. + +> For JavaScript applications, use the +> [@solana/web3.js](https://github.com/solana-labs/solana-web3.js) library as a +> convenient interface for the RPC methods to interact with a Solana node. For +> an PubSub connection to a Solana node, use the +> [Websocket API](/docs/rpc/websocket/index.mdx). + +## RPC HTTP Endpoint + +Default port: `8899` + +- http://localhost:8899 +- http://192.168.1.88:8899 + +## Request Formatting + +To make a JSON-RPC request, send an HTTP POST request with a +`Content-Type: application/json` header. The JSON request data should contain 4 +fields: + +- `jsonrpc: ` - set to `"2.0"` +- `id: ` - a unique client-generated identifying integer +- `method: ` - a string containing the method to be invoked +- `params: ` - a JSON array of ordered parameter values + +Example using curl: + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getBalance", + "params": [ + "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri" + ] + } +' +``` + +The response output will be a JSON object with the following fields: + +- `jsonrpc: ` - matching the request specification +- `id: ` - matching the request identifier +- `result: ` - requested data or success + confirmation + +Requests can be sent in batches by sending an array of JSON-RPC request objects +as the data for a single POST. + +### Example Request + +The commitment parameter should be included as the last element in the `params` +array: + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "getBalance", + "params": [ + "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri", + { + "commitment": "finalized" + } + ] + } +' +``` + +## Definitions + +- Hash: A SHA-256 hash of a chunk of data. +- Pubkey: The public key of a Ed25519 key-pair. +- Transaction: A list of Solana instructions signed by a client keypair to + authorize those actions. +- Signature: An Ed25519 signature of transaction's payload data including + instructions. This can be used to identify transactions. + +## Health Check + +Although not a JSON RPC API, a `GET /health` at the RPC HTTP Endpoint provides a +health-check mechanism for use by load balancers or other network +infrastructure. This request will always return a HTTP 200 OK response with a +body of "ok", "behind" or "unknown": + +- `ok`: The node is within `HEALTH_CHECK_SLOT_DISTANCE` slots from the latest + cluster confirmed slot +- `behind { distance }`: The node is behind `distance` slots from the latest + cluster confirmed slot where `distance > HEALTH_CHECK_SLOT_DISTANCE` +- `unknown`: The node is unable to determine where it stands in relation to the + cluster diff --git a/docs/rpc/http/isBlockhashValid.mdx b/docs/rpc/http/isBlockhashValid.mdx new file mode 100644 index 000000000..da74a1562 --- /dev/null +++ b/docs/rpc/http/isBlockhashValid.mdx @@ -0,0 +1,84 @@ +--- +sidebarLabel: isBlockhashValid +title: isBlockhashValid RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/isBlockhashValid +--- + +Returns whether a blockhash is still valid or not + + + This method is only available in `solana-core` v1.9 or newer. Please use + [getFeeCalculatorForBlockhash](/docs/rpc/http/getFeeCalculatorForBlockhash) + for `solana-core` v1.8 and below. + + + + + + +### Parameters + + + the blockhash of the block to evauluate, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + The minimum slot that the request can be evaluated at + + + + +### Result + +`` - `true` if the blockhash is still valid + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "id":45, + "jsonrpc":"2.0", + "method":"isBlockhashValid", + "params":[ + "J7rBdM6AecPDEZp8aPq5iPSNKVkU5Q76F3oAV4eW5wsW", + {"commitment":"processed"} + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 2483 + }, + "value": false + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/minimumLedgerSlot.mdx b/docs/rpc/http/minimumLedgerSlot.mdx new file mode 100644 index 000000000..86e234458 --- /dev/null +++ b/docs/rpc/http/minimumLedgerSlot.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: minimumLedgerSlot +title: minimumLedgerSlot RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/minimumLedgerSlot +--- + +Returns the lowest slot that the node has information about in its ledger. + + + This value may increase over time if the node is configured to purge older + ledger data + + + + + + +### Parameters + +**None** + +### Result + +`u64` - Minimum ledger slot number + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + {"jsonrpc":"2.0","id":1, "method":"minimumLedgerSlot"} +' +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 1234, "id": 1 } +``` + + + diff --git a/docs/rpc/http/requestAirdrop.mdx b/docs/rpc/http/requestAirdrop.mdx new file mode 100644 index 000000000..9c80219a0 --- /dev/null +++ b/docs/rpc/http/requestAirdrop.mdx @@ -0,0 +1,72 @@ +--- +sidebarLabel: requestAirdrop +title: requestAirdrop RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/requestAirdrop +--- + +Requests an airdrop of lamports to a Pubkey + + + + + +### Parameters + + + Pubkey of account to receive lamports, as a base-58 encoded string + + + + lamports to airdrop, as a "u64" + + + + +Configuration object containing the following fields: + + + + + +### Result + +`` - Transaction Signature of the airdrop, as a base-58 encoded string + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", "id": 1, + "method": "requestAirdrop", + "params": [ + "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri", + 1000000000 + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW", + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/sendTransaction.mdx b/docs/rpc/http/sendTransaction.mdx new file mode 100644 index 000000000..30dbecf80 --- /dev/null +++ b/docs/rpc/http/sendTransaction.mdx @@ -0,0 +1,126 @@ +--- +sidebarLabel: sendTransaction +title: sendTransaction RPC Method +sidebarSortOrder: 0 +hideTableOfContents: true +altRoutes: + - /docs/rpc/sendTransaction +--- + +Submits a signed transaction to the cluster for processing. + +This method does not alter the transaction in any way; it relays the transaction +created by clients to the node as-is. + +If the node's rpc service receives the transaction, this method immediately +succeeds, without waiting for any confirmations. A successful response from this +method does not guarantee the transaction is processed or confirmed by the +cluster. + +While the rpc service will reasonably retry to submit it, the transaction could +be rejected if transaction's `recent_blockhash` expires before it lands. + +Use [`getSignatureStatuses`](#getsignaturestatuses) to ensure a transaction is +processed and confirmed. + +Before submitting, the following preflight checks are performed: + +1. The transaction signatures are verified +2. The transaction is simulated against the bank slot specified by the preflight + commitment. On failure an error will be returned. Preflight checks may be + disabled if desired. It is recommended to specify the same commitment and + preflight commitment to avoid confusing behavior. + +The returned signature is the first signature in the transaction, which is used +to identify the transaction +([transaction id](/docs/terminology.md#transaction-id)). This identifier can be +easily extracted from the transaction data before submission. + + + + + +### Parameters + + + Fully-signed Transaction, as encoded string. + + + + +Configuration object containing the following optional fields: + + + +Encoding used for the transaction data. + +Values: `base58` (_slow_, **DEPRECATED**), or `base64`. + + + + + when `true`, skip the preflight transaction checks + + + + Commitment level to use for preflight. + + + + Maximum number of times for the RPC node to retry sending the transaction to + the leader. If this parameter not provided, the RPC node will retry the + transaction until it is finalized or until the blockhash expires. + + + + set the minimum slot at which to perform preflight transaction checks + + + + +### Result + +`` - First Transaction Signature embedded in the transaction, as base-58 +encoded string ([transaction id](/docs/terminology.md#transaction-id)) + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "sendTransaction", + "params": [ + "4hXTCkRzt9WyecNzV1XPgCDfGAZzQKNxLXgynz5QDuWWPSAZBZSHptvWRL3BjCvzUXRdKvHL2b7yGrRQcWyaqsaBCncVG7BFggS8w9snUts67BSh3EqKpXLUm5UMHfD7ZBe9GhARjbNQMLJ1QD3Spr6oMTBU6EhdB4RD8CP2xUxr2u3d6fos36PD98XS6oX8TQjLpsMwncs5DAMiD4nNnR8NBfyghGCWvCVifVwvA8B8TJxE1aiyiv2L429BCWfyzAme5sZW8rDb14NeCQHhZbtNqfXhcp2tAnaAT" + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": "2id3YC2jK9G5Wo2phDx4gJVAew8DcY5NAojnVuao8rkxwPYPe8cSwE5GzhEgJA2y8fVjDEo6iR6ykBvDxrTQrtpb", + "id": 1 +} +``` + + + diff --git a/docs/rpc/http/simulateTransaction.mdx b/docs/rpc/http/simulateTransaction.mdx new file mode 100644 index 000000000..c58269be7 --- /dev/null +++ b/docs/rpc/http/simulateTransaction.mdx @@ -0,0 +1,187 @@ +--- +sidebarLabel: simulateTransaction +title: simulateTransaction RPC Method +sidebarSortOrder: 0 +hideTableOfContents: true +altRoutes: + - /docs/rpc/simulateTransaction +--- + +Simulate sending a transaction + + + + + +### Parameters + + + +Transaction, as an encoded string. + + + The transaction must have a valid blockhash, but is not required to be signed. + + + + + + +Configuration object containing the following fields: + + + Commitment level to simulate the transaction at + + + + if `true` the transaction signatures will be verified (conflicts with + `replaceRecentBlockhash`) + + + + if `true` the transaction recent blockhash will be replaced with the most + recent blockhash. (conflicts with `sigVerify`) + + + + the minimum slot that the request can be evaluated at + + + + +Encoding used for the transaction data. + +Values: `base58` (_slow_, **DEPRECATED**), or `base64`. + + + + + +Accounts configuration object containing the following fields: + + + An `array` of accounts to return, as base-58 encoded strings + + + + +encoding for returned Account data + + + +
+ +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a + [parser cannot be found](https://github.com/solana-labs/solana/blob/cfd0a00ae2ba85a6d76757df8b4fa38ed242d185/account-decoder/src/parse_account_data.rs#L98-L100), + the field falls back to `base64` encoding, detectable when the returned + `accounts.data` field is type `string`. + +
+ + + + + + + +### Result + +The result will be an RpcResponse JSON object with `value` set to a JSON object +with the following fields: + +- `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) +- `logs: ` - Array of log messages the transaction instructions + output during execution, null if simulation failed before the transaction was + able to execute (for example due to an invalid blockhash or signature + verification failure) +- `accounts: ` - array of accounts with the same length as the + `accounts.addresses` array in the request + - `` - if the account doesn't exist or if `err` is not null + - `` - otherwise, a JSON object containing: + - `lamports: ` - number of lamports assigned to this account, as a u64 + - `owner: ` - base-58 encoded Pubkey of the program this account has + been assigned to + - `data: <[string, encoding]|object>` - data associated with the account, + either as encoded binary data or JSON format `{: }` - + depending on encoding parameter + - `executable: ` - boolean indicating if the account contains a + program \(and is strictly read-only\) + - `rentEpoch: ` - the epoch at which this account will next owe rent, + as u64 +- `unitsConsumed: ` - The number of compute budget units consumed + during the processing of this transaction +- `returnData: ` - the most-recent return data generated by an + instruction in the transaction, with the following fields: + - `programId: ` - the program that generated the return data, as + base-58 encoded Pubkey + - `data: <[string, encoding]>` - the return data itself, as base-64 encoded + binary data + + + + + +### Code sample + +```bash +curl http://localhost:8899 -X POST -H "Content-Type: application/json" -d ' + { + "jsonrpc": "2.0", + "id": 1, + "method": "simulateTransaction", + "params": [ + "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDArczbMia1tLmq7zz4DinMNN0pJ1JtLdqIJPUw3YrGCzYAMHBsgN27lcgB6H2WQvFgyZuJYHa46puOQo9yQ8CVQbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCp20C7Wj2aiuk5TReAXo+VTVg8QTHjs0UjNMMKCvpzZ+ABAgEBARU=", + { + "encoding":"base64", + } + ] + } +' +``` + +### Response + +```json +{ + "jsonrpc": "2.0", + "result": { + "context": { + "slot": 218 + }, + "value": { + "err": null, + "accounts": null, + "logs": [ + "Program 83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri invoke [1]", + "Program 83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri consumed 2366 of 1400000 compute units", + "Program return: 83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri KgAAAAAAAAA=", + "Program 83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri success" + ], + "returnData": { + "data": ["Kg==", "base64"], + "programId": "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri" + }, + "unitsConsumed": 2366 + } + }, + "id": 1 +} +``` + + + diff --git a/docs/rpc/index.mdx b/docs/rpc/index.mdx new file mode 100644 index 000000000..4c9d9b604 --- /dev/null +++ b/docs/rpc/index.mdx @@ -0,0 +1,99 @@ +--- +title: Solana RPC Methods & Documentation +seoTitle: "Solana RPC Methods: HTTP & Websockets" +sidebarLabel: Solana RPC Methods +sidebarSortOrder: 0 +hideTableOfContents: false +--- + +Interact with Solana nodes directly with the JSON RPC API via the HTTP and +Websocket methods. + +## Configuring State Commitment + +For preflight checks and transaction processing, Solana nodes choose which bank +state to query based on a commitment requirement set by the client. The +commitment describes how finalized a block is at that point in time. When +querying the ledger state, it's recommended to use lower levels of commitment to +report progress and higher levels to ensure the state will not be rolled back. + +In descending order of commitment (most finalized to least finalized), clients +may specify: + +- `finalized` - the node will query the most recent block confirmed by + supermajority of the cluster as having reached maximum lockout, meaning the + cluster has recognized this block as finalized +- `confirmed` - the node will query the most recent block that has been voted on + by supermajority of the cluster. + - It incorporates votes from gossip and replay. + - It does not count votes on descendants of a block, only direct votes on that + block. + - This confirmation level also upholds "optimistic confirmation" guarantees in + release 1.3 and onwards. +- `processed` - the node will query its most recent block. Note that the block + may still be skipped by the cluster. + +For processing many dependent transactions in series, it's recommended to use +`confirmed` commitment, which balances speed with rollback safety. For total +safety, it's recommended to use `finalized` commitment. + +### Default Commitment + +If commitment configuration is not provided, the node will default to +`finalized` commitment + +Only methods that query bank state accept the commitment parameter. They are +indicated in the API Reference below. + +## RpcResponse Structure + +Many methods that take a commitment parameter return an RpcResponse JSON object +comprised of two parts: + +- `context` : An RpcResponseContext JSON structure including a `slot` field at + which the operation was evaluated. +- `value` : The value returned by the operation itself. + +## Parsed Responses + +Some methods support an `encoding` parameter, and can return account or +instruction data in parsed JSON format if `"encoding":"jsonParsed"` is requested +and the node has a parser for the owning program. Solana nodes currently support +JSON parsing for the following native and SPL programs: + +| Program | Account State | Instructions | +| ---------------------------- | ------------- | ------------ | +| Address Lookup | v1.15.0 | v1.15.0 | +| BPF Loader | n/a | stable | +| BPF Upgradeable Loader | stable | stable | +| Config | stable | | +| SPL Associated Token Account | n/a | stable | +| SPL Memo | n/a | stable | +| SPL Token | stable | stable | +| SPL Token 2022 | stable | stable | +| Stake | stable | stable | +| Vote | stable | stable | + +The list of account parsers can be found +[here](https://github.com/solana-labs/solana/blob/master/account-decoder/src/parse_account_data.rs), +and instruction parsers +[here](https://github.com/solana-labs/solana/blob/master/transaction-status/src/parse_instruction.rs). + +## Filter criteria + +Some methods support providing a `filters` object to enable pre-filtering the +data returned within the RpcResponse JSON object. The following filters exist: + +- `memcmp: object` - compares a provided series of bytes with program account + data at a particular offset. Fields: + + - `offset: usize` - offset into program account data to start comparison + - `bytes: string` - data to match, as encoded string + - `encoding: string` - encoding for filter `bytes` data, either "base58" or + "base64". Data is limited in size to 128 or fewer decoded bytes.
+ **NEW: This field, and base64 support generally, is only available in + solana-core v1.14.0 or newer. Please omit when querying nodes on earlier + versions** + +- `dataSize: u64` - compares the program account data length with the provided + data size diff --git a/docs/rpc/json-structures.mdx b/docs/rpc/json-structures.mdx new file mode 100644 index 000000000..0855dc189 --- /dev/null +++ b/docs/rpc/json-structures.mdx @@ -0,0 +1,110 @@ +--- +title: Common JSON Data Structures for Solana RPC Methods +sidebarLabel: Data Structures as JSON +sidebarSortOrder: -1 +hideTableOfContents: false +--- + +Various Solana RPC methods will return more complex responses as structured JSON +objects, filled with specific keyed values. + +The most common of these JSON data structures include: + +- [transactions](#transactions) +- [inner instructions](#inner-instructions) +- [token balances](#token-balances) + +## Transactions + +Transactions are quite different from those on other blockchains. Be sure to +review [Anatomy of a Transaction](/docs/core/transactions.md) to learn about +transactions on Solana. + +The JSON structure of a transaction is defined as follows: + +- `signatures: ` - A list of base-58 encoded signatures applied + to the transaction. The list is always of length + `message.header.numRequiredSignatures` and not empty. The signature at index + `i` corresponds to the public key at index `i` in `message.accountKeys`. The + first one is used as the + [transaction id](/docs/terminology.md#transaction-id). +- `message: ` - Defines the content of the transaction. + - `accountKeys: ` - List of base-58 encoded public keys used by + the transaction, including by the instructions and for signatures. The first + `message.header.numRequiredSignatures` public keys must sign the + transaction. + - `header: ` - Details the account types and signatures required by + the transaction. + - `numRequiredSignatures: ` - The total number of signatures + required to make the transaction valid. The signatures must match the + first `numRequiredSignatures` of `message.accountKeys`. + - `numReadonlySignedAccounts: ` - The last + `numReadonlySignedAccounts` of the signed keys are read-only accounts. + Programs may process multiple transactions that load read-only accounts + within a single PoH entry, but are not permitted to credit or debit + lamports or modify account data. Transactions targeting the same + read-write account are evaluated sequentially. + - `numReadonlyUnsignedAccounts: ` - The last + `numReadonlyUnsignedAccounts` of the unsigned keys are read-only accounts. + - `recentBlockhash: ` - A base-58 encoded hash of a recent block in + the ledger used to prevent transaction duplication and to give transactions + lifetimes. + - `instructions: ` - List of program instructions that will be + executed in sequence and committed in one atomic transaction if all succeed. + - `programIdIndex: ` - Index into the `message.accountKeys` array + indicating the program account that executes this instruction. + - `accounts: ` - List of ordered indices into the + `message.accountKeys` array indicating which accounts to pass to the + program. + - `data: ` - The program input data encoded in a base-58 string. + - `addressTableLookups: ` - List of address table + lookups used by a transaction to dynamically load addresses from on-chain + address lookup tables. Undefined if `maxSupportedTransactionVersion` is not + set. + - `accountKey: ` - base-58 encoded public key for an address lookup + table account. + - `writableIndexes: ` - List of indices used to load + addresses of writable accounts from a lookup table. + - `readonlyIndexes: ` - List of indices used to load + addresses of readonly accounts from a lookup table. + +## Inner Instructions + +The Solana runtime records the cross-program instructions that are invoked +during transaction processing and makes these available for greater transparency +of what was executed on-chain per transaction instruction. Invoked instructions +are grouped by the originating transaction instruction and are listed in order +of processing. + +The JSON structure of inner instructions is defined as a list of objects in the +following structure: + +- `index: number` - Index of the transaction instruction from which the inner + instruction(s) originated +- `instructions: ` - Ordered list of inner program instructions + that were invoked during a single transaction instruction. + - `programIdIndex: ` - Index into the `message.accountKeys` array + indicating the program account that executes this instruction. + - `accounts: ` - List of ordered indices into the + `message.accountKeys` array indicating which accounts to pass to the + program. + - `data: ` - The program input data encoded in a base-58 string. + +## Token Balances + +The JSON structure of token balances is defined as a list of objects in the +following structure: + +- `accountIndex: ` - Index of the account in which the token balance is + provided for. +- `mint: ` - Pubkey of the token's mint. +- `owner: ` - Pubkey of token balance's owner. +- `programId: ` - Pubkey of the Token program that owns the + account. +- `uiTokenAmount: ` - + - `amount: ` - Raw amount of tokens as a string, ignoring decimals. + - `decimals: ` - Number of decimals configured for token's mint. + - `uiAmount: ` - Token amount as a float, accounting for + decimals. **DEPRECATED** + - `uiAmountString: ` - Token amount as a string, accounting for + decimals. diff --git a/docs/rpc/websocket/accountSubscribe.mdx b/docs/rpc/websocket/accountSubscribe.mdx new file mode 100644 index 000000000..57bbc5057 --- /dev/null +++ b/docs/rpc/websocket/accountSubscribe.mdx @@ -0,0 +1,160 @@ +--- +sidebarLabel: accountSubscribe +title: accountSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/accountSubscribe +--- + +Subscribe to an account to receive notifications when the lamports or data for a +given account public key changes + + + + + +### Parameters + + + Account Pubkey, as base-58 encoded string + + + + +Configuration object containing the following fields: + + + + + +Encoding format for Account data + + + +
+ +- `base58` is slow. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to binary encoding, detectable when the `data`field is type`string`. + +
+ + + + + +### Result + +`` - Subscription id \(needed to unsubscribe\) + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "accountSubscribe", + "params": [ + "CM78CPUeXjn8o3yroDHxUtKsZZgoy4GPkPPXfouKNH12", + { + "encoding": "jsonParsed", + "commitment": "finalized" + } + ] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 23784, "id": 1 } +``` + + + + +#### Notification Format: + +The notification format is the same as seen in the +[getAccountInfo](/docs/rpc/http/getAccountInfo) RPC HTTP method. + +Base58 encoding: + +```json +{ + "jsonrpc": "2.0", + "method": "accountNotification", + "params": { + "result": { + "context": { + "slot": 5199307 + }, + "value": { + "data": [ + "11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHPXHRDEHrBesJhZyqnnq9qJeUuF7WHxiuLuL5twc38w2TXNLxnDbjmuR", + "base58" + ], + "executable": false, + "lamports": 33594, + "owner": "11111111111111111111111111111111", + "rentEpoch": 635, + "space": 80 + } + }, + "subscription": 23784 + } +} +``` + +Parsed-JSON encoding: + +```json +{ + "jsonrpc": "2.0", + "method": "accountNotification", + "params": { + "result": { + "context": { + "slot": 5199307 + }, + "value": { + "data": { + "program": "nonce", + "parsed": { + "type": "initialized", + "info": { + "authority": "Bbqg1M4YVVfbhEzwA9SpC9FhsaG83YMTYoR4a8oTDLX", + "blockhash": "LUaQTmM7WbMRiATdMMHaRGakPtCkc2GHtH57STKXs6k", + "feeCalculator": { + "lamportsPerSignature": 5000 + } + } + } + }, + "executable": false, + "lamports": 33594, + "owner": "11111111111111111111111111111111", + "rentEpoch": 635, + "space": 80 + } + }, + "subscription": 23784 + } +} +``` diff --git a/docs/rpc/websocket/accountUnsubscribe.mdx b/docs/rpc/websocket/accountUnsubscribe.mdx new file mode 100644 index 000000000..f46399941 --- /dev/null +++ b/docs/rpc/websocket/accountUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: accountUnsubscribe +title: accountUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/accountUnsubscribe +--- + +Unsubscribe from account change notifications + + + + + +### Parameters + + + id of the account Subscription to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "accountUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/blockSubscribe.mdx b/docs/rpc/websocket/blockSubscribe.mdx new file mode 100644 index 000000000..f40659ffa --- /dev/null +++ b/docs/rpc/websocket/blockSubscribe.mdx @@ -0,0 +1,386 @@ +--- +sidebarLabel: blockSubscribe +title: blockSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/blockSubscribe +--- + +Subscribe to receive notification anytime a new block is `confirmed` or +`finalized`. + + + This subscription is considered **unstable** and is only available if the + validator was started with the `--rpc-pubsub-enable-block-subscription` flag. + The format of this subscription may change in the future. + + + + + + +### Parameters + + + +filter criteria for the logs to receive results by account type; currently +supported: + + + `all` - include all transactions in block + + + + +A JSON object with the following field: + +- `mentionsAccountOrProgram: ` - return only transactions that mention + the provided public key (as base-58 encoded string). If no mentions in a given + block, then no notification will be sent. + + + + + + + +Configuration object containing the following fields: + + + +- `processed` is not supported. + + + + + +encoding format for each returned Transaction + + + +
+ +- `jsonParsed` attempts to use program-specific instruction parsers to return + more human-readable and explicit data in the + `transaction.message.instructions` list. +- If `jsonParsed` is requested but a parser cannot be found, the instruction + falls back to regular JSON encoding (`accounts`, `data`, and `programIdIndex` + fields). + +
+ + + + + +level of transaction detail to return + + + +
+ +- If `accounts` are requested, transaction details only include signatures and + an annotated list of accounts in each transaction. +- Transaction metadata is limited to only: fee, err, pre_balances, + post_balances, pre_token_balances, and post_token_balances. + +
+ + + + + +the max transaction version to return in responses. + +
+ +- If the requested block contains a transaction with a higher version, an error + will be returned. +- If this parameter is omitted, only legacy transactions will be returned, and a + block containing any versioned transaction will prompt the error. + +
+ + + + + whether to populate the `rewards` array. If parameter not provided, the + default includes rewards. + + + + +### Result + +`integer` - subscription id \(needed to unsubscribe\) + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "method": "blockSubscribe", + "params": ["all"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "method": "blockSubscribe", + "params": [ + { + "mentionsAccountOrProgram": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op" + }, + { + "commitment": "confirmed", + "encoding": "base64", + "showRewards": true, + "transactionDetails": "full" + } + ] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 0, "id": 1 } +``` + + + + +#### Notification Format: + +The notification will be an object with the following fields: + +- `slot: ` - The corresponding slot. +- `err: ` - Error if something went wrong publishing the + notification otherwise null. +- `block: ` - A block object as seen in the + [getBlock](/docs/rpc/http/getblock) RPC HTTP method. + +```json +{ + "jsonrpc": "2.0", + "method": "blockNotification", + "params": { + "result": { + "context": { + "slot": 112301554 + }, + "value": { + "slot": 112301554, + "block": { + "previousBlockhash": "GJp125YAN4ufCSUvZJVdCyWQJ7RPWMmwxoyUQySydZA", + "blockhash": "6ojMHjctdqfB55JDpEpqfHnP96fiaHEcvzEQ2NNcxzHP", + "parentSlot": 112301553, + "transactions": [ + { + "transaction": [ + "OpltwoUvWxYi1P2U8vbIdE/aPntjYo5Aa0VQ2JJyeJE2g9Vvxk8dDGgFMruYfDu8/IfUWb0REppTe7IpAuuLRgIBAAkWnj4KHRpEWWW7gvO1c0BHy06wZi2g7/DLqpEtkRsThAXIdBbhXCLvltw50ZnjDx2hzw74NVn49kmpYj2VZHQJoeJoYJqaKcvuxCi/2i4yywedcVNDWkM84Iuw+cEn9/ROCrXY4qBFI9dveEERQ1c4kdU46xjxj9Vi+QXkb2Kx45QFVkG4Y7HHsoS6WNUiw2m4ffnMNnOVdF9tJht7oeuEfDMuUEaO7l9JeUxppCvrGk3CP45saO51gkwVYEgKzhpKjCx3rgsYxNR81fY4hnUQXSbbc2Y55FkwgRBpVvQK7/+clR4Gjhd3L4y+OtPl7QF93Akg1LaU9wRMs5nvfDFlggqI9PqJl+IvVWrNRdBbPS8LIIhcwbRTkSbqlJQWxYg3Bo2CTVbw7rt1ZubuHWWp0mD/UJpLXGm2JprWTePNULzHu67sfqaWF99LwmwjTyYEkqkRt1T0Je5VzHgJs0N5jY4iIU9K3lMqvrKOIn/2zEMZ+ol2gdgjshx+sphIyhw65F3J/Dbzk04LLkK+CULmN571Y+hFlXF2ke0BIuUG6AUF+4214Cu7FXnqo3rkxEHDZAk0lRrAJ8X/Z+iwuwI5cgbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpDLAp8axcEkaQkLDKRoWxqp8XLNZSKial7Rk+ELAVVKWoWLRXRZ+OIggu0OzMExvVLE5VHqy71FNHq4gGitkiKYNFWSLIE4qGfdFLZXy/6hwS+wq9ewjikCpd//C9BcCL7Wl0iQdUslxNVCBZHnCoPYih9JXvGefOb9WWnjGy14sG9j70+RSVx6BlkFELWwFvIlWR/tHn3EhHAuL0inS2pwX7ZQTAU6gDVaoqbR2EiJ47cKoPycBNvHLoKxoY9AZaBjPl6q8SKQJSFyFd9n44opAgI6zMTjYF/8Ok4VpXEESp3QaoUyTI9sOJ6oFP6f4dwnvQelgXS+AEfAsHsKXxGAIUDQENAgMEBQAGBwgIDg8IBJCER3QXl1AVDBADCQoOAAQLERITDAjb7ugh3gOuTy==", + "base64" + ], + "meta": { + "err": null, + "status": { + "Ok": null + }, + "fee": 5000, + "preBalances": [ + 1758510880, 2067120, 1566000, 1461600, 2039280, 2039280, + 1900080, 1865280, 0, 3680844220, 2039280 + ], + "postBalances": [ + 1758505880, 2067120, 1566000, 1461600, 2039280, 2039280, + 1900080, 1865280, 0, 3680844220, 2039280 + ], + "innerInstructions": [ + { + "index": 0, + "instructions": [ + { + "programIdIndex": 13, + "accounts": [1, 15, 3, 4, 2, 14], + "data": "21TeLgZXNbtHXVBzCaiRmH" + }, + { + "programIdIndex": 14, + "accounts": [3, 4, 1], + "data": "6qfC8ic7Aq99" + }, + { + "programIdIndex": 13, + "accounts": [1, 15, 3, 5, 2, 14], + "data": "21TeLgZXNbsn4QEpaSEr3q" + }, + { + "programIdIndex": 14, + "accounts": [3, 5, 1], + "data": "6LC7BYyxhFRh" + } + ] + }, + { + "index": 1, + "instructions": [ + { + "programIdIndex": 14, + "accounts": [4, 3, 0], + "data": "7aUiLHFjSVdZ" + }, + { + "programIdIndex": 19, + "accounts": [17, 18, 16, 9, 11, 12, 14], + "data": "8kvZyjATKQWYxaKR1qD53V" + }, + { + "programIdIndex": 14, + "accounts": [9, 11, 18], + "data": "6qfC8ic7Aq99" + } + ] + } + ], + "logMessages": [ + "Program QMNeHCGYnLVDn1icRAfQZpjPLBNkfGbSKRB83G5d8KB invoke [1]", + "Program QMWoBmAyJLAsA1Lh9ugMTw2gciTihncciphzdNzdZYV invoke [2]" + ], + "preTokenBalances": [ + { + "accountIndex": 4, + "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u", + "uiTokenAmount": { + "uiAmount": null, + "decimals": 6, + "amount": "0", + "uiAmountString": "0" + }, + "owner": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op", + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" + }, + { + "accountIndex": 5, + "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u", + "uiTokenAmount": { + "uiAmount": 11513.0679, + "decimals": 6, + "amount": "11513067900", + "uiAmountString": "11513.0679" + }, + "owner": "rXhAofQCT7NN9TUqigyEAUzV1uLL4boeD8CRkNBSkYk", + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" + }, + { + "accountIndex": 10, + "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1", + "uiTokenAmount": { + "uiAmount": null, + "decimals": 6, + "amount": "0", + "uiAmountString": "0" + }, + "owner": "CL9wkGFT3SZRRNa9dgaovuRV7jrVVigBUZ6DjcgySsCU", + "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" + }, + { + "accountIndex": 11, + "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1", + "uiTokenAmount": { + "uiAmount": 15138.514093, + "decimals": 6, + "amount": "15138514093", + "uiAmountString": "15138.514093" + }, + "owner": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op", + "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" + } + ], + "postTokenBalances": [ + { + "accountIndex": 4, + "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u", + "uiTokenAmount": { + "uiAmount": null, + "decimals": 6, + "amount": "0", + "uiAmountString": "0" + }, + "owner": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op", + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" + }, + { + "accountIndex": 5, + "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u", + "uiTokenAmount": { + "uiAmount": 11513.103028, + "decimals": 6, + "amount": "11513103028", + "uiAmountString": "11513.103028" + }, + "owner": "rXhAofQCT7NN9TUqigyEAUzV1uLL4boeD8CRkNBSkYk", + "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" + }, + { + "accountIndex": 10, + "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1", + "uiTokenAmount": { + "uiAmount": null, + "decimals": 6, + "amount": "0", + "uiAmountString": "0" + }, + "owner": "CL9wkGFT3SZRRNa9dgaovuRV7jrVVigBUZ6DjcgySsCU", + "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" + }, + { + "accountIndex": 11, + "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1", + "uiTokenAmount": { + "uiAmount": 15489.767829, + "decimals": 6, + "amount": "15489767829", + "uiAmountString": "15489.767829" + }, + "owner": "BeiHVPRE8XeX3Y2xVNrSsTpAScH94nYySBVQ4HqgN9at", + "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" + } + ], + "rewards": [] + } + } + ], + "blockTime": 1639926816, + "blockHeight": 101210751 + }, + "err": null + } + }, + "subscription": 14 + } +} +``` diff --git a/docs/rpc/websocket/blockUnsubscribe.mdx b/docs/rpc/websocket/blockUnsubscribe.mdx new file mode 100644 index 000000000..a1dd8b893 --- /dev/null +++ b/docs/rpc/websocket/blockUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: blockUnsubscribe +title: blockUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/blockUnsubscribe +--- + +Unsubscribe from block notifications + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "blockUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/index.mdx b/docs/rpc/websocket/index.mdx new file mode 100644 index 000000000..bfee36c14 --- /dev/null +++ b/docs/rpc/websocket/index.mdx @@ -0,0 +1,23 @@ +--- +title: Solana RPC Websocket Methods +seoTitle: Solana RPC Websocket Methods +sidebarLabel: Websocket Methods +sidebarSortOrder: 2 +hideTableOfContents: false +--- + +After connecting to the RPC PubSub websocket at `ws://
/`: + +- Submit subscription requests to the websocket using the methods below +- Multiple subscriptions may be active at once +- Many subscriptions take the optional + [`commitment` parameter](/docs/rpc/index.mdx#configuring-state-commitment), + defining how finalized a change should be to trigger a notification. For + subscriptions, if commitment is unspecified, the default value is `finalized`. + +## RPC PubSub WebSocket Endpoint + +Default port: `8900` + +- ws://localhost:8900 +- http://192.168.1.88:8900 diff --git a/docs/rpc/websocket/logsSubscribe.mdx b/docs/rpc/websocket/logsSubscribe.mdx new file mode 100644 index 000000000..77e439e5e --- /dev/null +++ b/docs/rpc/websocket/logsSubscribe.mdx @@ -0,0 +1,138 @@ +--- +sidebarLabel: logsSubscribe +title: logsSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/logsSubscribe +--- + +Subscribe to transaction logging + + + + + +### Parameters + + + filter criteria for the logs to receive results by account type. The following filters types are currently supported: + + + +A string with one of the following values: + +- `all` - subscribe to all transactions except for simple vote transactions +- `allWithVotes` - subscribe to all transactions, including simple vote + transactions + + + + + +An object with the following field: + +- `mentions: [ ]` - array containing a single Pubkey (as base-58 + encoded string); if present, subscribe to only transactions mentioning this + address + + + The `mentions` field currently [only supports + one](https://github.com/solana-labs/solana/blob/master/rpc/src/rpc_pubsub.rs#L481) + Pubkey string per method call. Listing additional addresses will result in an + error. + + + + + + + + +Configuration object containing the following fields: + + + + + +### Result + +`` - Subscription id \(needed to unsubscribe\) + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "logsSubscribe", + "params": [ + { + "mentions": [ "11111111111111111111111111111111" ] + }, + { + "commitment": "finalized" + } + ] +} +{ + "jsonrpc": "2.0", + "id": 1, + "method": "logsSubscribe", + "params": [ "all" ] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 24040, "id": 1 } +``` + + + + +#### Notification Format: + +The notification will be an RpcResponse JSON object with value equal to: + +- `signature: ` - The transaction signature base58 encoded. +- `err: ` - Error if transaction failed, null if transaction + succeeded. + [TransactionError definitions](https://github.com/solana-labs/solana/blob/c0c60386544ec9a9ec7119229f37386d9f070523/sdk/src/transaction/error.rs#L13) +- `logs: ` - Array of log messages the transaction instructions + output during execution, null if simulation failed before the transaction was + able to execute (for example due to an invalid blockhash or signature + verification failure) + +Example: + +```json +{ + "jsonrpc": "2.0", + "method": "logsNotification", + "params": { + "result": { + "context": { + "slot": 5208469 + }, + "value": { + "signature": "5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv", + "err": null, + "logs": [ + "SBF program 83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri success" + ] + } + }, + "subscription": 24040 + } +} +``` diff --git a/docs/rpc/websocket/logsUnsubscribe.mdx b/docs/rpc/websocket/logsUnsubscribe.mdx new file mode 100644 index 000000000..a98d9da0f --- /dev/null +++ b/docs/rpc/websocket/logsUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: logsUnsubscribe +title: logsUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/logsUnsubscribe +--- + +Unsubscribe from transaction logging + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "logsUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/programSubscribe.mdx b/docs/rpc/websocket/programSubscribe.mdx new file mode 100644 index 000000000..f5847112d --- /dev/null +++ b/docs/rpc/websocket/programSubscribe.mdx @@ -0,0 +1,211 @@ +--- +sidebarLabel: programSubscribe +title: programSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/programSubscribe +--- + +Subscribe to a program to receive notifications when the lamports or data for an +account owned by the given program changes + + + + + +### Parameters + + + +Pubkey of the `program_id`, as base-58 encoded string + + + + + +Configuration object containing the following fields: + + + + + +filter results using various filter objects + + + The resultant account must meet **ALL** filter criteria to be included in the + returned results + + + + + + +Encoding format for Account data + + + +
+ +- `base58` is slow. +- `jsonParsed` encoding attempts to use program-specific state parsers to return + more human-readable and explicit account state data. +- If `jsonParsed` is requested but a parser cannot be found, the field falls + back to `base64` encoding, detectable when the `data` field is type `string`. + +
+ + + + + +### Result + +`` - Subscription id \(needed to unsubscribe\) + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "programSubscribe", + "params": [ + "11111111111111111111111111111111", + { + "encoding": "base64", + "commitment": "finalized" + } + ] +} +{ + "jsonrpc": "2.0", + "id": 1, + "method": "programSubscribe", + "params": [ + "11111111111111111111111111111111", + { + "encoding": "jsonParsed" + } + ] +} +{ + "jsonrpc": "2.0", + "id": 1, + "method": "programSubscribe", + "params": [ + "11111111111111111111111111111111", + { + "encoding": "base64", + "filters": [ + { + "dataSize": 80 + } + ] + } + ] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 24040, "id": 1 } +``` + + + + +#### Notification format + +The notification format is a single program account object as seen in the +[getProgramAccounts](/docs/rpc/http/getprogramaccounts) RPC HTTP method. + +Base58 encoding: + +```json +{ + "jsonrpc": "2.0", + "method": "programNotification", + "params": { + "result": { + "context": { + "slot": 5208469 + }, + "value": { + "pubkey": "H4vnBqifaSACnKa7acsxstsY1iV1bvJNxsCY7enrd1hq", + "account": { + "data": [ + "11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHPXHRDEHrBesJhZyqnnq9qJeUuF7WHxiuLuL5twc38w2TXNLxnDbjmuR", + "base58" + ], + "executable": false, + "lamports": 33594, + "owner": "11111111111111111111111111111111", + "rentEpoch": 636, + "space": 80 + } + } + }, + "subscription": 24040 + } +} +``` + +Parsed-JSON encoding: + +```json +{ + "jsonrpc": "2.0", + "method": "programNotification", + "params": { + "result": { + "context": { + "slot": 5208469 + }, + "value": { + "pubkey": "H4vnBqifaSACnKa7acsxstsY1iV1bvJNxsCY7enrd1hq", + "account": { + "data": { + "program": "nonce", + "parsed": { + "type": "initialized", + "info": { + "authority": "Bbqg1M4YVVfbhEzwA9SpC9FhsaG83YMTYoR4a8oTDLX", + "blockhash": "LUaQTmM7WbMRiATdMMHaRGakPtCkc2GHtH57STKXs6k", + "feeCalculator": { + "lamportsPerSignature": 5000 + } + } + } + }, + "executable": false, + "lamports": 33594, + "owner": "11111111111111111111111111111111", + "rentEpoch": 636, + "space": 80 + } + } + }, + "subscription": 24040 + } +} +``` diff --git a/docs/rpc/websocket/programUnsubscribe.mdx b/docs/rpc/websocket/programUnsubscribe.mdx new file mode 100644 index 000000000..e548ddf88 --- /dev/null +++ b/docs/rpc/websocket/programUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: programUnsubscribe +title: programUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/programUnsubscribe +--- + +Unsubscribe from program-owned account change notifications + + + + + +### Parameters + + + id of account Subscription to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "programUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/rootSubscribe.mdx b/docs/rpc/websocket/rootSubscribe.mdx new file mode 100644 index 000000000..16bf8b689 --- /dev/null +++ b/docs/rpc/websocket/rootSubscribe.mdx @@ -0,0 +1,55 @@ +--- +sidebarLabel: rootSubscribe +title: rootSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/rootSubscribe +--- + +Subscribe to receive notification anytime a new root is set by the validator. + + + + + +### Parameters + +**None** + +### Result + +`integer` - subscription id \(needed to unsubscribe\) + + + + + +### Code sample + +```json +{ "jsonrpc": "2.0", "id": 1, "method": "rootSubscribe" } +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 0, "id": 1 } +``` + + + + +#### Notification Format: + +The result is the latest root slot number. + +```json +{ + "jsonrpc": "2.0", + "method": "rootNotification", + "params": { + "result": 42, + "subscription": 0 + } +} +``` diff --git a/docs/rpc/websocket/rootUnsubscribe.mdx b/docs/rpc/websocket/rootUnsubscribe.mdx new file mode 100644 index 000000000..4f8068929 --- /dev/null +++ b/docs/rpc/websocket/rootUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: rootUnsubscribe +title: rootUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/rootUnsubscribe +--- + +Unsubscribe from root notifications + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "rootUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/signatureSubscribe.mdx b/docs/rpc/websocket/signatureSubscribe.mdx new file mode 100644 index 000000000..3ad3f9315 --- /dev/null +++ b/docs/rpc/websocket/signatureSubscribe.mdx @@ -0,0 +1,149 @@ +--- +sidebarLabel: signatureSubscribe +title: signatureSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/signatureSubscribe +--- + +Subscribe to receive a notification when the transaction with the given +signature reaches the specified commitment level. + + + This is a subscription to a single notification. It is automatically cancelled + by the server once the notification, `signatureNotification`, is sent by the + RPC. + + + + + + +### Parameters + + + +transaction signature, as base-58 encoded string + + + The transaction signature must be the first signature from the transaction + (see [transaction id](/docs/terminology.md#transaction-id) for more details). + + + + + + +Configuration object containing the following fields: + + + + + +Whether or not to subscribe for notifications when signatures are received by +the RPC, in addition to when they are processed. + + + + + +### Result + +`` - subscription id (needed to unsubscribe) + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "signatureSubscribe", + "params": [ + "2EBVM6cB8vAAD93Ktr6Vd8p67XPbQzCJX47MpReuiCXJAtcjaxpvWpcg9Ege1Nr5Tk3a2GFrByT7WPBjdsTycY9b", + { + "commitment": "finalized", + "enableReceivedNotification": false + } + ] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 0, "id": 1 } +``` + + + + +#### Notification Format: + +The notification will be an RpcResponse JSON object with value containing an +object with: + +- `slot: ` - The corresponding slot. +- `value: ` - a notification value of + [`RpcSignatureResult`](https://github.com/solana-labs/solana/blob/6d28fd455b07e3557fc6c0c3ddf3ba03e3fe8482/rpc-client-api/src/response.rs#L265-L268), + resulting in either: + - when `enableReceivedNotification` is `true` and the signature is received: + the literal string + [`"receivedSignature"`](https://github.com/solana-labs/solana/blob/6d28fd455b07e3557fc6c0c3ddf3ba03e3fe8482/rpc-client-api/src/response.rs#L286-L288), + or + - when the signature is processed: `err: `: + - `null` if the transaction succeeded in being processed at the specified + commitment level, or + - a + [`TransactionError`](https://github.com/solana-labs/solana/blob/6d28fd455b07e3557fc6c0c3ddf3ba03e3fe8482/sdk/src/transaction/error.rs#L15-L164), + if the transaction failed + +#### Example responses: + +The following is an example response of a notification from a successfully +**processed** transactions: + +```json +{ + "jsonrpc": "2.0", + "method": "signatureNotification", + "params": { + "result": { + "context": { + "slot": 5207624 + }, + "value": { + "err": null + } + }, + "subscription": 24006 + } +} +``` + +The following is an example response of a notification from a successfully +**recieved** transaction signature: + +```json +{ + "jsonrpc": "2.0", + "method": "signatureNotification", + "params": { + "result": { + "context": { + "slot": 5207624 + }, + "value": "receivedSignature" + }, + "subscription": 24006 + } +} +``` diff --git a/docs/rpc/websocket/signatureUnsubscribe.mdx b/docs/rpc/websocket/signatureUnsubscribe.mdx new file mode 100644 index 000000000..f34ced2dd --- /dev/null +++ b/docs/rpc/websocket/signatureUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: signatureUnsubscribe +title: signatureUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/signatureUnsubscribe +--- + +Unsubscribe from signature confirmation notification + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "signatureUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/slotSubscribe.mdx b/docs/rpc/websocket/slotSubscribe.mdx new file mode 100644 index 000000000..e90dff657 --- /dev/null +++ b/docs/rpc/websocket/slotSubscribe.mdx @@ -0,0 +1,65 @@ +--- +sidebarLabel: slotSubscribe +title: slotSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/slotSubscribe +--- + +Subscribe to receive notification anytime a slot is processed by the validator + + + + + +### Parameters + +**None** + +### Result + +`` - Subscription id \(needed to unsubscribe\) + + + + + +### Code sample + +```json +{ "jsonrpc": "2.0", "id": 1, "method": "slotSubscribe" } +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 0, "id": 1 } +``` + + + + +#### Notification Format: + +The notification will be an object with the following fields: + +- `parent: ` - The parent slot +- `root: ` - The current root slot +- `slot: ` - The newly set slot value + +Example: + +```json +{ + "jsonrpc": "2.0", + "method": "slotNotification", + "params": { + "result": { + "parent": 75, + "root": 44, + "slot": 76 + }, + "subscription": 0 + } +} +``` diff --git a/docs/rpc/websocket/slotUnsubscribe.mdx b/docs/rpc/websocket/slotUnsubscribe.mdx new file mode 100644 index 000000000..450afc276 --- /dev/null +++ b/docs/rpc/websocket/slotUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: slotUnsubscribe +title: slotUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/slotUnsubscribe +--- + +Unsubscribe from slot notifications + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "slotUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/slotsUpdatesSubscribe.mdx b/docs/rpc/websocket/slotsUpdatesSubscribe.mdx new file mode 100644 index 000000000..086aa1d48 --- /dev/null +++ b/docs/rpc/websocket/slotsUpdatesSubscribe.mdx @@ -0,0 +1,87 @@ +--- +sidebarLabel: slotsUpdatesSubscribe +title: slotsUpdatesSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/slotsUpdatesSubscribe +--- + +Subscribe to receive a notification from the validator on a variety of updates +on every slot + + + This subscription is unstable. The format of this subscription may change in + the future, and may not always be supported. + + + + + + +### Parameters + +**None** + +### Result + +`` - Subscription id (needed to unsubscribe) + + + + + +### Code sample + +```json +{ "jsonrpc": "2.0", "id": 1, "method": "slotsUpdatesSubscribe" } +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 0, "id": 1 } +``` + + + + +### Notification Format + +The notification will be an object with the following fields: + +- `err: ` - The error message. Only present if the update is + of type "dead". +- `parent: ` - The parent slot. Only present if the update is of + type "createdBank". +- `slot: ` - The newly updated slot +- `stats: ` - The error message. Only present if the update is + of type "frozen". An object with the following fields: + - `maxTransactionsPerEntry: `, + - `numFailedTransactions: `, + - `numSuccessfulTransactions: `, + - `numTransactionEntries: `, +- `timestamp: ` - The Unix timestamp of the update +- `type: ` - The update type, one of: + - "firstShredReceived" + - "completed" + - "createdBank" + - "frozen" + - "dead" + - "optimisticConfirmation" + - "root" + +```bash +{ + "jsonrpc": "2.0", + "method": "slotsUpdatesNotification", + "params": { + "result": { + "parent": 75, + "slot": 76, + "timestamp": 1625081266243, + "type": "optimisticConfirmation" + }, + "subscription": 0 + } +} +``` diff --git a/docs/rpc/websocket/slotsUpdatesUnsubscribe.mdx b/docs/rpc/websocket/slotsUpdatesUnsubscribe.mdx new file mode 100644 index 000000000..61f25e196 --- /dev/null +++ b/docs/rpc/websocket/slotsUpdatesUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: slotsUpdatesUnsubscribe +title: slotsUpdatesUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/slotsUpdatesUnsubscribe +--- + +Unsubscribe from slot-update notifications + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "slotsUpdatesUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/rpc/websocket/voteSubscribe.mdx b/docs/rpc/websocket/voteSubscribe.mdx new file mode 100644 index 000000000..77384856a --- /dev/null +++ b/docs/rpc/websocket/voteSubscribe.mdx @@ -0,0 +1,75 @@ +--- +sidebarLabel: voteSubscribe +title: voteSubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/voteSubscribe +--- + +Subscribe to receive notification anytime a new vote is observed in gossip. +These votes are pre-consensus therefore there is no guarantee these votes will +enter the ledger. + + + This subscription is unstable and only available if the validator was started + with the `--rpc-pubsub-enable-vote-subscription` flag. The format of this + subscription may change in the future. + + + + + + +### Parameters + +**None** + +### Result + +`` - subscription id (needed to unsubscribe) + + + + + +### Code sample + +```json +{ "jsonrpc": "2.0", "id": 1, "method": "voteSubscribe" } +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": 0, "id": 1 } +``` + + + + +#### Notification Format: + +The notification will be an object with the following fields: + +- `hash: ` - The vote hash +- `slots: ` - The slots covered by the vote, as an array of u64 integers +- `timestamp: ` - The timestamp of the vote +- `signature: ` - The signature of the transaction that contained this + vote +- `votePubkey: ` - The public key of the vote account, as base-58 + encoded string + +```json +{ + "jsonrpc": "2.0", + "method": "voteNotification", + "params": { + "result": { + "hash": "8Rshv2oMkPu5E4opXTRyuyBeZBqQ4S477VG26wUTFxUM", + "slots": [1, 2], + "timestamp": null + }, + "subscription": 0 + } +} +``` diff --git a/docs/rpc/websocket/voteUnsubscribe.mdx b/docs/rpc/websocket/voteUnsubscribe.mdx new file mode 100644 index 000000000..abcfe1354 --- /dev/null +++ b/docs/rpc/websocket/voteUnsubscribe.mdx @@ -0,0 +1,47 @@ +--- +sidebarLabel: voteUnsubscribe +title: voteUnsubscribe RPC Method +hideTableOfContents: true +altRoutes: + - /docs/rpc/voteUnsubscribe +--- + +Unsubscribe from vote notifications + + + + + +### Parameters + + + subscription id to cancel + + +### Result + +`` - unsubscribe success message + + + + + +### Code sample + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "voteUnsubscribe", + "params": [0] +} +``` + +### Response + +```json +{ "jsonrpc": "2.0", "result": true, "id": 1 } +``` + + + diff --git a/docs/terminology.md b/docs/terminology.md index 21044fce9..2b58f3397 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -68,8 +68,8 @@ a block chain. ## BPF loader The Solana program that owns and loads -[BPF](developing/on-chain-programs/faq#berkeley-packet-filter-bpf) smart -contract programs, allowing the program to interface with the runtime. +[BPF](/docs/programs/faq.md#berkeley-packet-filter-bpf) smart contract programs, +allowing the program to interface with the runtime. ## client @@ -111,7 +111,7 @@ A gossip network connecting all [nodes](#node) of a [cluster](#cluster). Some number of [epochs](#epoch) after [stake](#stake) has been deactivated while it progressively becomes available for withdrawal. During this period, the stake is considered to be "deactivating". More info about: -[warmup and cooldown](implemented-proposals/staking-rewards.md#stake-warmup-cooldown-withdrawal) +[warmup and cooldown](https://docs.solanalabs.com/implemented-proposals/staking-rewards#stake-warmup-cooldown-withdrawal) ## credit @@ -120,7 +120,7 @@ See [vote credit](#vote-credit). ## cross-program invocation (CPI) A call from one smart contract program to another. For more information, see -[calling between programs](developing/programming-model/calling-between-programs.md). +[calling between programs](/docs/core/cpi.md). ## data plane @@ -211,9 +211,9 @@ for accessing an account. A fractional [native token](#native-token) with the value of 0.000000001 [sol](#sol). -:::info Within the compute budget, a quantity of -_[micro-lamports](https://github.com/solana-labs/solana/blob/ced8f6a512c61e0dd5308095ae8457add4a39e94/program-runtime/src/prioritization_fee.rs#L1-L2)_ -is used in the calculation of [prioritization fees](#prioritization-fee). ::: +> Within the compute budget, a quantity of +> _[micro-lamports](https://github.com/solana-labs/solana/blob/ced8f6a512c61e0dd5308095ae8457add4a39e94/program-runtime/src/prioritization_fee.rs#L1-L2)_ +> is used in the calculation of [prioritization fees](#prioritization-fee). ## leader @@ -265,7 +265,7 @@ header, array of account addresses, recent [blockhash](#blockhash), and an array of [instructions](#instruction). Learn more about the -[message formatting inside of transactions](./developing/programming-model/transactions.md#message-format) +[message formatting inside of transactions](/docs/core/transactions.md#message-format) here. ## native token @@ -287,9 +287,9 @@ See [Proof of History](#proof-of-history-poh). ## point A weighted [credit](#credit) in a rewards regime. In the [validator](#validator) -[rewards regime](cluster/stake-delegation-and-rewards.md), the number of points -owed to a [stake](#stake) during redemption is the product of the -[vote credits](#vote-credit) earned and the number of lamports staked. +[rewards regime](https://docs.solanalabs.com/consensus/stake-delegation-and-rewards), +the number of points owed to a [stake](#stake) during redemption is the product +of the [vote credits](#vote-credit) earned and the number of lamports staked. ## private key @@ -299,7 +299,7 @@ The private key of a [keypair](#keypair). The executable code that interprets the [instructions](#instruction) sent inside of each [transaction](#transaction) on the Solana. These programs are often -referred to as "[_smart contracts_](./developing//intro/programs.md)" on other +referred to as "[_smart contracts_](/docs/core/programs.md)" on other blockchains. ## program derived account (PDA) @@ -341,13 +341,13 @@ blockchain. When accounts do not have enough balance to pay rent, they may be Garbage Collected. See also [rent exempt](#rent-exempt) below. Learn more about rent here: -[What is rent?](../src/developing/intro/rent.md). +[What is rent?](/docs/core/rent.md). ## rent exempt Accounts that maintain more than 2 years with of rent payments in their account are considered "_rent exempt_" and will not incur the -[collection of rent](../src/developing/intro/rent.md#collecting-rent). +[collection of rent](/docs/core/rent.md#collecting-rent). ## root @@ -435,7 +435,7 @@ behavior can be proven. ## sysvar A system [account](#account). -[Sysvars](developing/runtime-facilities/sysvars.md) provide cluster state +[Sysvars](https://docs.solanalabs.com/runtime/sysvars) provide cluster state information such as current tick height, rewards [points](#point) values, etc. Programs can access Sysvars via a Sysvar account (pubkey) or by querying via a syscall. @@ -463,7 +463,7 @@ A digitally transferable asset. ## tpu -[Transaction processing unit](validator/tpu.md). +[Transaction processing unit](https://docs.solanalabs.com/validator/tpu). ## transaction @@ -488,7 +488,7 @@ A set of [transactions](#transaction) that may be executed in parallel. ## tvu -[Transaction validation unit](validator/tvu.md). +[Transaction validation unit](https://docs.solanalabs.com/validator/tvu). ## validator @@ -523,4 +523,4 @@ A collection of [keypairs](#keypair) that allows users to manage their funds. Some number of [epochs](#epoch) after [stake](#stake) has been delegated while it progressively becomes effective. During this period, the stake is considered to be "activating". More info about: -[warmup and cooldown](cluster/stake-delegation-and-rewards.md#stake-warmup-cooldown-withdrawal) +[warmup and cooldown](https://docs.solanalabs.com/consensus/stake-delegation-and-rewards#stake-warmup-cooldown-withdrawal) diff --git a/next.config.js b/next.config.js index 800b3b6e9..751efc725 100644 --- a/next.config.js +++ b/next.config.js @@ -1,6 +1,8 @@ +// @ts-check /** @type {import('next').NextConfig} */ const { withContentlayer } = require("next-contentlayer"); +const redirectsJson = require("./redirects.json"); module.exports = withContentlayer({ reactStrictMode: true, @@ -27,6 +29,16 @@ module.exports = withContentlayer({ }, ], }, + async redirects() { + return [ + // common solana docs + ...redirectFormatter("https://solana.com/", redirectsJson["common-docs"]), + ...redirectFormatter( + "https://docs.solanalabs.com/", + redirectsJson["solana-client"], + ), + ]; + }, }); /** diff --git a/public/assets/docs/economics/example_adjusted_staking_yields.png b/public/assets/docs/economics/example_adjusted_staking_yields.png new file mode 100644 index 000000000..db68e4b0a Binary files /dev/null and b/public/assets/docs/economics/example_adjusted_staking_yields.png differ diff --git a/public/assets/docs/economics/example_relative_dilution.png b/public/assets/docs/economics/example_relative_dilution.png new file mode 100644 index 000000000..ba59a78bd Binary files /dev/null and b/public/assets/docs/economics/example_relative_dilution.png differ diff --git a/public/assets/docs/economics/example_staked_supply_w_range_initial_stake.png b/public/assets/docs/economics/example_staked_supply_w_range_initial_stake.png new file mode 100644 index 000000000..89b893d0e Binary files /dev/null and b/public/assets/docs/economics/example_staked_supply_w_range_initial_stake.png differ diff --git a/public/assets/docs/economics/example_staked_yields.png b/public/assets/docs/economics/example_staked_yields.png new file mode 100644 index 000000000..32311c396 Binary files /dev/null and b/public/assets/docs/economics/example_staked_yields.png differ diff --git a/public/assets/docs/economics/example_unstaked_dilution.png b/public/assets/docs/economics/example_unstaked_dilution.png new file mode 100644 index 000000000..a283011ac Binary files /dev/null and b/public/assets/docs/economics/example_unstaked_dilution.png differ diff --git a/public/assets/docs/economics/proposed_inflation_schedule.png b/public/assets/docs/economics/proposed_inflation_schedule.png new file mode 100644 index 000000000..f515efa12 Binary files /dev/null and b/public/assets/docs/economics/proposed_inflation_schedule.png differ diff --git a/public/assets/docs/economics/proposed_total_supply.png b/public/assets/docs/economics/proposed_total_supply.png new file mode 100644 index 000000000..e2562ffde Binary files /dev/null and b/public/assets/docs/economics/proposed_total_supply.png differ diff --git a/public/assets/docs/quickstarts/solana-get-started-build-and-deploy.png b/public/assets/docs/quickstarts/solana-get-started-build-and-deploy.png new file mode 100644 index 000000000..59bb3ef52 Binary files /dev/null and b/public/assets/docs/quickstarts/solana-get-started-build-and-deploy.png differ diff --git a/public/assets/docs/quickstarts/solana-get-started-import-on-playground.png b/public/assets/docs/quickstarts/solana-get-started-import-on-playground.png new file mode 100644 index 000000000..cd90b00cb Binary files /dev/null and b/public/assets/docs/quickstarts/solana-get-started-import-on-playground.png differ diff --git a/public/assets/docs/quickstarts/solana-get-started-successful-build.png b/public/assets/docs/quickstarts/solana-get-started-successful-build.png new file mode 100644 index 000000000..82b0a5df0 Binary files /dev/null and b/public/assets/docs/quickstarts/solana-get-started-successful-build.png differ diff --git a/public/assets/docs/quickstarts/solana-overview-client-program.png b/public/assets/docs/quickstarts/solana-overview-client-program.png new file mode 100644 index 000000000..42b80cee5 Binary files /dev/null and b/public/assets/docs/quickstarts/solana-overview-client-program.png differ diff --git a/public/assets/docs/rt-dropped-minority-fork-post-process.png b/public/assets/docs/rt-dropped-minority-fork-post-process.png new file mode 100644 index 000000000..ba56d1ccc Binary files /dev/null and b/public/assets/docs/rt-dropped-minority-fork-post-process.png differ diff --git a/public/assets/docs/rt-dropped-minority-fork-pre-process.png b/public/assets/docs/rt-dropped-minority-fork-pre-process.png new file mode 100644 index 000000000..10f08dfed Binary files /dev/null and b/public/assets/docs/rt-dropped-minority-fork-pre-process.png differ diff --git a/public/assets/docs/rt-dropped-via-rpc-pool.png b/public/assets/docs/rt-dropped-via-rpc-pool.png new file mode 100644 index 000000000..8020ebd87 Binary files /dev/null and b/public/assets/docs/rt-dropped-via-rpc-pool.png differ diff --git a/public/assets/docs/rt-tpu-jito-labs.png b/public/assets/docs/rt-tpu-jito-labs.png new file mode 100644 index 000000000..934e1dcdc Binary files /dev/null and b/public/assets/docs/rt-tpu-jito-labs.png differ diff --git a/public/assets/docs/rt-tx-journey.png b/public/assets/docs/rt-tx-journey.png new file mode 100644 index 000000000..faa8b6e22 Binary files /dev/null and b/public/assets/docs/rt-tx-journey.png differ diff --git a/public/assets/docs/transaction.svg b/public/assets/docs/transaction.svg new file mode 100644 index 000000000..49fb14b96 --- /dev/null +++ b/public/assets/docs/transaction.svg @@ -0,0 +1,75 @@ + + + + + + + + + + + + + + + + + + + + + + Neighborhood + 3 + + Neighborhood + 4 + + Neighborhood + 5 + + Neighborhood + 6 + Neighborhood + 0 + Neighborhood + 1 + Neighborhood + 2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/redirects.json b/redirects.json new file mode 100644 index 000000000..fd446b6bc --- /dev/null +++ b/redirects.json @@ -0,0 +1,394 @@ +{ + "solana-client": [ + { + "source": "/apps/sysvars", + "destination": "/developing/runtime-facilities/sysvars" + }, + { + "source": "/apps/builtins", + "destination": "/developing/runtime-facilities/programs" + }, + { + "source": "/apps/backwards-compatibility", + "destination": "/developing/backwards-compatibility" + }, + { + "source": "/implemented-proposals/secp256k1_instruction", + "destination": "/developing/runtime-facilities/programs#secp256k1-program" + }, + + { + "source": "/implemented-proposals/implemented-proposals", + "destination": "/implemented-proposals" + }, + { + "source": "/cli/install-solana-cli-tools", + "destination": "/cli/install" + }, + { "source": "/cli/conventions", "destination": "/cli/intro" }, + { + "source": "/cli/choose-a-cluster", + "destination": "/cli/examples/choose-a-cluster" + }, + { + "source": "/cli/delegate-stake", + "destination": "/cli/examples/delegate-stake" + }, + { + "source": "/delegate-stake", + "destination": "/cli/examples/delegate-stake" + }, + { + "source": "/cli/sign-offchain-message", + "destination": "/cli/examples/sign-offchain-message" + }, + { + "source": "/cli/deploy-a-program", + "destination": "/cli/examples/deploy-a-program" + }, + { + "source": "/cli/transfer-tokens", + "destination": "/cli/examples/transfer-tokens" + }, + { + "source": "/offline-signing/durable-nonce", + "destination": "/cli/examples/durable-nonce" + }, + { + "source": "/offline-signing", + "destination": "/cli/examples/offline-signing" + }, + { + "source": "/developing/test-validator", + "destination": "/cli/examples/test-validator" + }, + { "source": "/wallet-guide/cli", "destination": "/cli/wallets" }, + { + "source": "/wallet-guide/paper-wallet", + "destination": "/cli/wallets/paper" + }, + { + "source": "/wallet-guide/file-system-wallet", + "destination": "/cli/wallets/file-system" + }, + { + "source": "/wallet-guide/hardware-wallet", + "destination": "/cli/wallets/hardware-wallet" + }, + { + "source": "/wallet-guide/hardware-wallet/ledger", + "destination": "/cli/wallets/hardware-wallet/ledger" + }, + + { "source": "/cluster/overview", "destination": "/clusters/index" }, + { "source": "/cluster/bench-tps", "destination": "/clusters/benchmark" }, + { + "source": "/cluster/performance-metrics", + "destination": "/clusters/metrics" + }, + + { "source": "/running-validator", "destination": "/operations" }, + { + "source": "/validator/get-started/setup-a-validator", + "destination": "/operations/setup-a-validator" + }, + { + "source": "/validator/get-started/setup-an-rpc-node", + "destination": "/operations/setup-an-rpc-node" + }, + { + "source": "/validator/best-practices/operations", + "destination": "/operations/best-practices/general" + }, + { + "source": "/validator/best-practices/monitoring", + "destination": "/operations/best-practices/monitoring" + }, + { + "source": "/validator/best-practices/security", + "destination": "/operations/best-practices/security" + }, + { + "source": "/validator/overview/running-validator-or-rpc-node", + "destination": "/operations/validator-or-rpc-node" + }, + { + "source": "/validator/overview/validator-prerequisites", + "destination": "/operations/prerequisites" + }, + { + "source": "/validator/overview/validator-initiatives", + "destination": "/operations/validator-initiatives" + }, + { + "source": "/running-validator/validator-reqs", + "destination": "/operations/requirements" + }, + + { + "source": "/running-validator/validator-troubleshoot", + "destination": "/operations/guides/validator-troubleshoot" + }, + { + "source": "/running-validator/validator-start", + "destination": "/operations/guides/validator-start" + }, + { + "source": "/running-validator/vote-accounts", + "destination": "/operations/guides/vote-accounts" + }, + { + "source": "/running-validator/validator-stake", + "destination": "/operations/guides/validator-stake" + }, + { + "source": "/running-validator/validator-monitor", + "destination": "/operations/guides/validator-monitor" + }, + { + "source": "/running-validator/validator-info", + "destination": "/operations/guides/validator-info" + }, + { + "source": "/running-validator/validator-failover", + "destination": "/operations/guides/validator-failover" + }, + { + "source": "/running-validator/restart-cluster", + "destination": "/operations/guides/restart-cluster" + }, + + { + "source": "/cluster/synchronization", + "destination": "/consensus/synchronization" + }, + { + "source": "/cluster/leader-rotation", + "destination": "/consensus/leader-rotation" + }, + { + "source": "/cluster/fork-generation", + "destination": "/consensus/fork-generation" + }, + { + "source": "/cluster/managing-forks", + "destination": "/consensus/managing-forks" + }, + { + "source": "/cluster/turbine-block-propagation", + "destination": "/consensus/turbine-block-propagation" + }, + { + "source": "/cluster/commitments", + "destination": "/consensus/commitments" + }, + { + "source": "/cluster/vote-signing", + "destination": "/consensus/vote-signing" + }, + { + "source": "/cluster/stake-delegation-and-rewards", + "destination": "/consensus/stake-delegation-and-rewards" + }, + + { + "source": "/developing/backwards-compatibility", + "destination": "/backwards-compatibility" + }, + { "source": "/validator/faq", "destination": "/faq" }, + { + "source": "/developing/plugins/geyser-plugins", + "destination": "/validator/geyser" + }, + { + "source": "/validator/overview/what-is-an-rpc-node", + "destination": "/what-is-an-rpc-node" + }, + { + "source": "/validator/overview/what-is-a-validator", + "destination": "/what-is-a-validator" + }, + + { + "source": "/developing/runtime-facilities/:path*", + "destination": "/runtime/:path*" + } + ], + "common-docs": [ + { "source": "/apps", "destination": "/developers" }, + { + "source": "/developing/programming-model/overview", + "destination": "/docs/programs" + }, + { "source": "/apps/break", "destination": "/docs/programs/examples" }, + { "source": "/apps/drones", "destination": "/docs/programs/examples" }, + { "source": "/apps/hello-world", "destination": "/docs/programs/examples" }, + { + "source": "/apps/javascript-api", + "destination": "/docs/clients/javascript" + }, + { "source": "/apps/programming-faq", "destination": "/docs/programs/faq" }, + { "source": "/apps/rent", "destination": "/docs/core/rent" }, + { "source": "/apps/webwallet", "destination": "/docs/intro/wallets" }, + { + "source": "/implemented-proposals/cross-program-invocation", + "destination": "/docs/core/cpi" + }, + { + "source": "/implemented-proposals/program-derived-addresses", + "destination": "/docs/core/cpi#program-derived-addresses" + }, + + { "destination": "/docs/rpc/http:path*", "source": "/api/http/:path*" }, + { + "destination": "/docs/rpc/websocket/:path*", + "source": "/api/websocket/:path*" + }, + { + "destination": "/docs/rpc/:path*", + "source": "/developing/clients/jsonrpc-api" + }, + { "destination": "/docs/rpc/:path*", "source": "/apps/jsonrpc-api" }, + { "destination": "/docs/terminology", "source": "/terminology" }, + { "destination": "/docs/core/rent", "source": "/developing/intro/rent" }, + { + "destination": "/docs/core/programs", + "source": "/developing/intro/programs" + }, + { + "destination": "/docs/core/accounts", + "source": "/developing/programming-model/accounts" + }, + { + "destination": "/docs/core/cpi", + "source": "/developing/programming-model/calling-between-programs" + }, + { + "destination": "/docs/core/runtime", + "source": "/developing/programming-model/runtime" + }, + { + "destination": "/docs/core/transactions", + "source": "/developing/programming-model/transactions" + }, + { + "destination": "/docs/core/transactions/fees", + "source": "/developing/intro/transaction_fees" + }, + { + "destination": "/docs/core/transactions/confirmation", + "source": "/developing/transaction_confirmation" + }, + { + "destination": "/docs/core/transactions/versions", + "source": "/developing/versioned-transactions" + }, + { + "destination": "/docs/core/transactions/retry", + "source": "/integrations/retrying-transactions" + }, + { + "destination": "/docs/intro/dev", + "source": "/developing/programming-model/overview" + }, + { + "destination": "/docs/advanced/lookup-tables", + "source": "/developing/lookup-tables" + }, + { + "destination": "/docs/advanced/state-compression", + "source": "/learn/state-compression" + }, + { + "destination": "/developers/guides/javascript/compressed-nfts", + "source": "/developing/guides/compressed-nfts" + }, + { + "destination": "/docs/programs", + "source": "/developing/on-chain-programs/overview" + }, + { + "destination": "/docs/programs/debugging", + "source": "/developing/on-chain-programs/debugging" + }, + { + "destination": "/docs/programs/deploying", + "source": "/developing/on-chain-programs/deploying" + }, + { + "destination": "/docs/programs/examples", + "source": "/developing/on-chain-programs/examples" + }, + { + "destination": "/docs/programs/faq", + "source": "/developing/on-chain-programs/faq" + }, + { + "destination": "/docs/programs/limitations", + "source": "/developing/on-chain-programs/limitations" + }, + { + "destination": "/docs/programs/lang-rust", + "source": "/developing/on-chain-programs/developing-rust" + }, + { + "destination": "/docs/programs/lang-c", + "source": "/developing/on-chain-programs/developing-c" + }, + { + "destination": "/docs/clients/javascript-reference", + "source": "/developing/clients/javascript-reference" + }, + { + "destination": "/docs/clients/javascript", + "source": "/developing/clients/javascript-api" + }, + { + "destination": "/docs/clients/rust", + "source": "/developing/clients/rust-api" + }, + { "destination": "/docs/intro/dev", "source": "/getstarted/overview" }, + { + "destination": "/developers/guides/getstarted/hello-world-in-your-browser", + "source": "/getstarted/hello-world" + }, + { + "destination": "/developers/guides/getstarted/setup-local-development", + "source": "/getstarted/local" + }, + { + "destination": "/developers/guides/getstarted/local-rust-hello-world", + "source": "/getstarted/rust" + }, + { + "destination": "/docs/core/clusters", + "source": "/clusters/rpc-endpoints" + }, + { "destination": "/docs/economics/staking", "source": "/staking" }, + { + "destination": "/docs/economics/staking/:path*", + "source": "/staking/:path*" + }, + { + "destination": "/docs/economics/inflation/:path*", + "source": "/inflation/:path*" + }, + { + "destination": "/docs/more/exchange", + "source": "/integrations/exchange" + }, + { + "destination": "/docs/intro/transaction_fees", + "source": "/transaction_fees" + }, + { + "destination": "/docs/intro/economics", + "source": "/storage_rent_economics" + }, + { "destination": "/docs/intro/economics", "source": "/economics_overview" }, + { "destination": "/docs/intro/history", "source": "/history" }, + { "destination": "/docs/intro/wallets", "source": "/wallet-guide/support" }, + { "destination": "/docs/intro/wallets", "source": "/wallet-guide" }, + { "destination": "/docs/intro", "source": "/introduction" } + ] +}