From b378cf230c3637b0938a47a7c2f20f48a44c8e16 Mon Sep 17 00:00:00 2001 From: Tyera Eulberg Date: Wed, 21 Sep 2022 11:59:30 -0600 Subject: [PATCH] Add missing fields to JSON-RPC docs (#27964) * Add docs for computeUnitsConsumed field * Add confirmationStatus to getSignaturesForAddress response docs * Make field-type formatting consistent (cherry picked from commit fa0550da32c63275bca2518851450a57e8dc3e55) --- docs/src/developing/clients/jsonrpc-api.md | 95 +++++++++++----------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/docs/src/developing/clients/jsonrpc-api.md b/docs/src/developing/clients/jsonrpc-api.md index bf5d8c2c74ebc2..5ede3e5064a94f 100644 --- a/docs/src/developing/clients/jsonrpc-api.md +++ b/docs/src/developing/clients/jsonrpc-api.md @@ -428,7 +428,7 @@ The result field will be an object with the following fields: - `transactions: ` - present if "full" transaction details are requested; an array of JSON objects containing: - `transaction: ` - [Transaction](#transaction-structure) 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) + - `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 @@ -451,6 +451,7 @@ The result field will be an object with the following fields: - `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](developing/programming-model/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: @@ -459,8 +460,8 @@ The result field will be an object with the following fields: - `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 + - `blockTime: ` - estimated production time, as Unix timestamp (seconds since the Unix epoch). null if not available + - `blockHeight: ` - the number of blocks beneath this block #### Example: @@ -623,12 +624,12 @@ The JSON structure of token balances is defined as a list of objects in the foll - `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. +- `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** + - `uiAmount: ` - Token amount as a float, accounting for decimals. **DEPRECATED** - `uiAmountString: ` - Token amount as a string, accounting for decimals. ### getBlockHeight @@ -920,12 +921,12 @@ None 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 +- `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 #### Example: @@ -974,7 +975,7 @@ The result field will be an object with the following fields: - `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 +- `transactionCount: `, total number of transactions processed without error since genesis #### Example: @@ -1063,7 +1064,7 @@ Get the fee the network will charge for a particular Message #### Results: -- `` - Fee corresponding to the message at the specified blockhash +- `` - Fee corresponding to the message at the specified blockhash #### Example: @@ -1239,7 +1240,7 @@ None - `` - `full: ` - Highest full snapshot slot - - `incremental: ` - Highest incremental snapshot slot _based on_ `full` + - `incremental: ` - Highest incremental snapshot slot _based on_ `full` #### Example: @@ -2138,9 +2139,10 @@ from newest to oldest transaction: - `` - `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. + - `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. + - `confirmationStatus: ` - The transaction's cluster confirmation status; either `processed`, `confirmed`, or `finalized`. See [Commitment](jsonrpc-api.md#configuring-state-commitment) for more on optimistic confirmation. #### Example: @@ -2204,9 +2206,9 @@ An array of: - `` - Unknown transaction - `` - `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. [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](jsonrpc-api.md#configuring-state-commitment) for more on optimistic confirmation. + - `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. [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](jsonrpc-api.md#configuring-state-commitment) for more on optimistic confirmation. - DEPRECATED: `status: ` - Transaction status - `"Ok": ` - Transaction was successful - `"Err": ` - Transaction failed with TransactionError @@ -2601,7 +2603,7 @@ The result will be an RpcResponse JSON object with `value` equal to a JSON objec - `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** +- `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 @@ -2867,7 +2869,7 @@ The result will be an RpcResponse JSON object with `value` equal to an array of - `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** +- `uiAmount: ` - the token account balance, using mint-prescribed decimals **DEPRECATED** - `uiAmountString: ` - the token account balance as a string, using mint-prescribed decimals #### Example: @@ -2924,7 +2926,7 @@ The result will be an RpcResponse JSON object with `value` equal to a JSON objec - `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** +- `uiAmount: ` - the total token supply, using mint-prescribed decimals **DEPRECATED** - `uiAmountString: ` - the total token supply as a string, using mint-prescribed decimals #### Example: @@ -2974,9 +2976,9 @@ Returns transaction details for a confirmed transaction - `` - if transaction is confirmed, an object with the following fields: - `slot: ` - the slot this transaction was processed in - `transaction: ` - [Transaction](#transaction-structure) 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/VERSION_FOR_DOCS_RS/solana_sdk/transaction/enum.TransactionError.html) + - `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/VERSION_FOR_DOCS_RS/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 @@ -2999,6 +3001,7 @@ Returns transaction details for a confirmed 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 + - `computeUnitsConsumed: `, number of [compute units](developing/programming-model/runtime.md#compute-budget) consumed by the transaction - `version: <"legacy"|number|undefined>` - Transaction version. Undefined if `maxSupportedTransactionVersion` is not set in request params. #### Example: @@ -3504,9 +3507,9 @@ Simulate sending a transaction An RpcResponse containing a TransactionStatus object 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 +- `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 @@ -3514,8 +3517,8 @@ The result will be an RpcResponse JSON object with `value` set to a JSON object - `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: +- `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 @@ -3785,8 +3788,8 @@ 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](jsonrpc-api.md#getblock) RPC HTTP method. +- `err: ` - Error if something went wrong publishing the notification otherwise null. +- `block: ` - A block object as seen in the [getBlock](jsonrpc-api.md#getblock) RPC HTTP method. ```json { @@ -4069,8 +4072,8 @@ Result: 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) +- `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: @@ -4341,7 +4344,7 @@ Result: The notification will be an RpcResponse JSON object with value containing an object with: -- `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) +- `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) Example: @@ -4664,7 +4667,7 @@ 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 +- `timestamp: ` - The timestamp of the vote - `signature: ` - The signature of the transaction that contained this vote ```json @@ -4739,7 +4742,7 @@ The result field will be an object with the following fields: - `transactions: ` - present if "full" transaction details are requested; an array of JSON objects containing: - `transaction: ` - [Transaction](#transaction-structure) 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) + - `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 @@ -4757,7 +4760,7 @@ The result field will be an object with the following fields: - `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 + - `blockTime: ` - estimated production time, as Unix timestamp (seconds since the Unix epoch). null if not available #### Example: @@ -4978,9 +4981,9 @@ from newest to oldest transaction: - `` - `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. + - `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. #### Example: @@ -5041,9 +5044,9 @@ Returns transaction details for a confirmed transaction - `` - if transaction is confirmed, an object with the following fields: - `slot: ` - the slot this transaction was processed in - `transaction: ` - [Transaction](#transaction-structure) 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/VERSION_FOR_DOCS_RS/solana_sdk/transaction/enum.TransactionError.html) + - `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/VERSION_FOR_DOCS_RS/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