docs: Clarify the commitment levels based on questions (#13387)
* Clarify the commitment levels based on questions Many people have asked about what commitment levels mean, and which to choose. This update includes some of the language at `sdk/src/commitment_config.rs` and a recommendation for different use cases. Additionally, the preflight commitment documentation was out of date, specifying that "max" was always used, and this is no longer the case. * Update docs/src/developing/clients/jsonrpc-api.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/developing/clients/jsonrpc-api.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Update docs/src/developing/clients/jsonrpc-api.md Co-authored-by: Tyera Eulberg <teulberg@gmail.com> * Fix typo Co-authored-by: Tyera Eulberg <teulberg@gmail.com>
This commit is contained in:
parent
7f4debdad5
commit
ede891a6c6
|
@ -122,18 +122,33 @@ Requests can be sent in batches by sending an array of JSON-RPC request objects
|
||||||
|
|
||||||
## Configuring State Commitment
|
## Configuring State Commitment
|
||||||
|
|
||||||
Solana nodes choose which bank state to query based on a commitment requirement
|
For preflight checks and transaction processing, Solana nodes choose which bank
|
||||||
set by the client. Clients may specify either:
|
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.
|
||||||
|
|
||||||
- `"max"` - the node will query the most recent block confirmed by supermajority of the cluster as having reached
|
In descending order of commitment (most finalized to least finalized), clients
|
||||||
maximum lockout.
|
may specify:
|
||||||
- `"root"` - the node will query the most recent block having reached maximum lockout on this node.
|
|
||||||
|
- `"max"` - 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
|
||||||
|
- `"root"` - the node will query the most recent block having reached maximum
|
||||||
|
lockout on this node, meaning the node has recognized this block as finalized
|
||||||
- `"singleGossip"` - the node will query the most recent block that has been voted on by supermajority of the cluster.
|
- `"singleGossip"` - 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 incorporates votes from gossip and replay.
|
||||||
- It does not count votes on descendants of a block, only direct votes on that block.
|
- 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
|
- This confirmation level also upholds "optimistic confirmation" guarantees in
|
||||||
release 1.3 and onwards.
|
release 1.3 and onwards.
|
||||||
- `"recent"` - the node will query its most recent block.
|
- `"recent"` - the node will query its most recent block. Note that the block
|
||||||
|
may not be complete.
|
||||||
|
|
||||||
|
For processing many dependent transactions in series, it's recommended to use
|
||||||
|
`"singleGossip"` commitment, which balances speed with rollback safety.
|
||||||
|
For total safety, it's recommended to use`"max"` commitment.
|
||||||
|
|
||||||
|
#### Example
|
||||||
|
|
||||||
The commitment parameter should be included as the last element in the `params` array:
|
The commitment parameter should be included as the last element in the `params` array:
|
||||||
|
|
||||||
|
@ -2668,9 +2683,10 @@ Submits a signed transaction to the cluster for processing.
|
||||||
Before submitting, the following preflight checks are performed:
|
Before submitting, the following preflight checks are performed:
|
||||||
|
|
||||||
1. The transaction signatures are verified
|
1. The transaction signatures are verified
|
||||||
2. The transaction is simulated against the latest max confirmed bank
|
2. The transaction is simulated against the bank slot specified by the preflight
|
||||||
and on failure an error will be returned. Preflight checks may be disabled if
|
commitment. On failure an error will be returned. Preflight checks may be
|
||||||
desired.
|
disabled if desired. It is recommended to specify the same commitment and
|
||||||
|
preflight commitment to avoid confusing behavior.
|
||||||
|
|
||||||
#### Parameters:
|
#### Parameters:
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue