blockworks-foundation
/
solana
mirror of https://github.com/blockworks-foundation/solana.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
solana/docs/src/api/methods/_getBlock.mdx

289 lines
14 KiB
Plaintext
Raw Blame History

import {
DocBlock,
DocSideBySide,
CodeParams,
Parameter,
Field,
Values,
CodeSnippets,
} from "../../../components/CodeDocBlock";
<DocBlock>
## getBlock
Returns identity and transaction information about a confirmed block in the ledger
<DocSideBySide>
<CodeParams>
### Parameters:
<Parameter type={"u64"} required={true}>
slot number, as <code>u64</code> integer
</Parameter>
<Parameter type={"object"} optional={true}>
Configuration object containing the following fields:
<Field
name="commitment"
type="string"
optional={true}
defaultValue={"finalized"}
href="/api/http#configuring-state-commitment"
>
<li>
the default is <code>finalized</code>
</li>
<li>
<code>processed</code> is not supported.
</li>
</Field>
<Field name="encoding" type="string" optional={true} defaultValue={"json"} href="/api/http#parsed-responses">
encoding format for each returned Transaction
<Values values={["json", "jsonParsed", "base58", "base64"]} />
<details>
- `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).
</details>
</Field>
<Field name="transactionDetails" type="string" optional={true} defaultValue={"full"}>
level of transaction detail to return
<Values values={["full", "accounts", "signatures", "none"]} />
<details>
- 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.
</details>
</Field>
<Field name="maxSupportedTransactionVersion" type="number" optional={true}>
the max transaction version to return in responses.
<details>
- 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.
</details>
</Field>
<Field name="rewards" type="bool" optional={true}>
whether to populate the `rewards` array. If parameter not provided, the
default includes rewards.
</Field>
</Parameter>
### Result:
The result field will be an object with the following fields:
- `<null>` - if specified block is not confirmed
- `<object>` - if block is confirmed, an object with the following fields:
- `blockhash: <string>` - the blockhash of this block, as base-58 encoded string
- `previousBlockhash: <string>` - 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: <u64>` - the slot index of this block's parent
- `transactions: <array>` - present if "full" transaction details are requested; an array of JSON objects containing:
- `transaction: <object|[string,encoding]>` - [Transaction](#transaction-structure) object, either in JSON format or encoded binary data, depending on encoding parameter
- `meta: <object>` - transaction status metadata object, containing `null` or:
- `err: <object|null>` - 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: <u64>` - fee this transaction was charged, as u64 integer
- `preBalances: <array>` - array of u64 account balances from before the transaction was processed
- `postBalances: <array>` - array of u64 account balances after the transaction was processed
- `innerInstructions: <array|null>` - List of [inner instructions](#inner-instructions-structure) or `null` if inner instruction recording was not enabled during this transaction
- `preTokenBalances: <array|undefined>` - List of [token balances](#token-balances-structure) from before the transaction was processed or omitted if token balance recording was not yet enabled during this transaction
- `postTokenBalances: <array|undefined>` - List of [token balances](#token-balances-structure) from after the transaction was processed or omitted if token balance recording was not yet enabled during this transaction
- `logMessages: <array|null>` - array of string log messages or `null` if log message recording was not enabled during this transaction
- `rewards: <array|null>` - transaction-level rewards, populated if rewards are requested; an array of JSON objects containing:
- `pubkey: <string>` - The public key, as base-58 encoded string, of the account that received the reward
- `lamports: <i64>`- number of reward lamports credited or debited by the account, as a i64
- `postBalance: <u64>` - account balance in lamports after the reward was applied
- `rewardType: <string|undefined>` - type of reward: "fee", "rent", "voting", "staking"
- `commission: <u8|undefined>` - vote account commission when the reward was credited, only present for voting and staking rewards
- DEPRECATED: `status: <object>` - Transaction status
- `"Ok": <null>` - Transaction was successful
- `"Err": <ERR>` - Transaction failed with TransactionError
- `loadedAddresses: <object|undefined>` - 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: <array[string]>` - Ordered list of base-58 encoded addresses for writable loaded accounts
- `readonly: <array[string]>` - Ordered list of base-58 encoded addresses for readonly loaded accounts
- `returnData: <object|undefined>` - the most-recent return data generated by an instruction in the transaction, with the following fields:
- `programId: <string>` - 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: <u64|undefined>` - 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: <array>` - present if "signatures" are requested for transaction details; an array of signatures strings, corresponding to the transaction order in the block
- `rewards: <array|undefined>` - block-level rewards, present if rewards are requested; an array of JSON objects containing:
- `pubkey: <string>` - The public key, as base-58 encoded string, of the account that received the reward
- `lamports: <i64>`- number of reward lamports credited or debited by the account, as a i64
- `postBalance: <u64>` - account balance in lamports after the reward was applied
- `rewardType: <string|undefined>` - type of reward: "fee", "rent", "voting", "staking"
- `commission: <u8|undefined>` - vote account commission when the reward was credited, only present for voting and staking rewards
- `blockTime: <i64|null>` - estimated production time, as Unix timestamp (seconds since the Unix epoch). null if not available
- `blockHeight: <u64|null>` - the number of blocks beneath this block
</CodeParams>
<CodeSnippets>
### 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
}
```
</CodeSnippets>
</DocSideBySide>
---
#### Transaction Structure
Transactions are quite different from those on other blockchains. Be sure to review [Anatomy of a Transaction](developing/programming-model/transactions.md) to learn about transactions on Solana.
The JSON structure of a transaction is defined as follows:
- `signatures: <array[string]>` - 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](../../terminology.md#transaction-id).
- `message: <object>` - Defines the content of the transaction.
- `accountKeys: <array[string]>` - 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: <object>` - Details the account types and signatures required by the transaction.
- `numRequiredSignatures: <number>` - The total number of signatures required to make the transaction valid. The signatures must match the first `numRequiredSignatures` of `message.accountKeys`.
- `numReadonlySignedAccounts: <number>` - 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: <number>` - The last `numReadonlyUnsignedAccounts` of the unsigned keys are read-only accounts.
- `recentBlockhash: <string>` - A base-58 encoded hash of a recent block in the ledger used to prevent transaction duplication and to give transactions lifetimes.
- `instructions: <array[object]>` - List of program instructions that will be executed in sequence and committed in one atomic transaction if all succeed.
- `programIdIndex: <number>` - Index into the `message.accountKeys` array indicating the program account that executes this instruction.
- `accounts: <array[number]>` - List of ordered indices into the `message.accountKeys` array indicating which accounts to pass to the program.
- `data: <string>` - The program input data encoded in a base-58 string.
- `addressTableLookups: <array[object]|undefined>` - 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: <string>` - base-58 encoded public key for an address lookup table account.
- `writableIndexes: <array[number]>` - List of indices used to load addresses of writable accounts from a lookup table.
- `readonlyIndexes: <array[number]>` - List of indices used to load addresses of readonly accounts from a lookup table.
#### Inner Instructions Structure
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: <array[object]>` - Ordered list of inner program instructions that were invoked during a single transaction instruction.
- `programIdIndex: <number>` - Index into the `message.accountKeys` array indicating the program account that executes this instruction.
- `accounts: <array[number]>` - List of ordered indices into the `message.accountKeys` array indicating which accounts to pass to the program.
- `data: <string>` - The program input data encoded in a base-58 string.
#### Token Balances Structure
The JSON structure of token balances is defined as a list of objects in the following structure:
- `accountIndex: <number>` - Index of the account in which the token balance is provided for.
- `mint: <string>` - Pubkey of the token's mint.
- `owner: <string|undefined>` - Pubkey of token balance's owner.
- `programId: <string|undefined>` - Pubkey of the Token program that owns the account.
- `uiTokenAmount: <object>` -
- `amount: <string>` - Raw amount of tokens as a string, ignoring decimals.
- `decimals: <number>` - Number of decimals configured for token's mint.
- `uiAmount: <number|null>` - Token amount as a float, accounting for decimals. **DEPRECATED**
- `uiAmountString: <string>` - Token amount as a string, accounting for decimals.
</DocBlock>
Reference in New Issue View Git Blame Copy Permalink