mirror of
https://github.com/tendermint/tendermint.git
synced 2026-01-05 04:55:18 +00:00
ci: add markdown linter (#146)
This commit is contained in:
Marko
GitHub
@@ -65,34 +65,34 @@ Example:
|
||||
|
||||
```go
|
||||
abci.ResponseDeliverTx{
|
||||
// ...
|
||||
Events: []abci.Event{
|
||||
{
|
||||
Type: "validator.provisions",
|
||||
Attributes: kv.Pairs{
|
||||
kv.Pair{Key: []byte("address"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("amount"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("balance"), Value: []byte("...")},
|
||||
},
|
||||
},
|
||||
{
|
||||
Type: "validator.provisions",
|
||||
Attributes: kv.Pairs{
|
||||
kv.Pair{Key: []byte("address"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("amount"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("balance"), Value: []byte("...")},
|
||||
},
|
||||
},
|
||||
{
|
||||
Type: "validator.slashed",
|
||||
Attributes: kv.Pairs{
|
||||
kv.Pair{Key: []byte("address"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("amount"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("reason"), Value: []byte("...")},
|
||||
},
|
||||
},
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
Events: []abci.Event{
|
||||
{
|
||||
Type: "validator.provisions",
|
||||
Attributes: kv.Pairs{
|
||||
kv.Pair{Key: []byte("address"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("amount"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("balance"), Value: []byte("...")},
|
||||
},
|
||||
},
|
||||
{
|
||||
Type: "validator.provisions",
|
||||
Attributes: kv.Pairs{
|
||||
kv.Pair{Key: []byte("address"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("amount"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("balance"), Value: []byte("...")},
|
||||
},
|
||||
},
|
||||
{
|
||||
Type: "validator.slashed",
|
||||
Attributes: kv.Pairs{
|
||||
kv.Pair{Key: []byte("address"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("amount"), Value: []byte("...")},
|
||||
kv.Pair{Key: []byte("reason"), Value: []byte("...")},
|
||||
},
|
||||
},
|
||||
// ...
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
@@ -120,19 +120,19 @@ non-determinism must be fixed and the nodes restarted.
|
||||
Sources of non-determinism in applications may include:
|
||||
|
||||
- Hardware failures
|
||||
- Cosmic rays, overheating, etc.
|
||||
- Cosmic rays, overheating, etc.
|
||||
- Node-dependent state
|
||||
- Random numbers
|
||||
- Time
|
||||
- Random numbers
|
||||
- Time
|
||||
- Underspecification
|
||||
- Library version changes
|
||||
- Race conditions
|
||||
- Floating point numbers
|
||||
- JSON serialization
|
||||
- Iterating through hash-tables/maps/dictionaries
|
||||
- Library version changes
|
||||
- Race conditions
|
||||
- Floating point numbers
|
||||
- JSON serialization
|
||||
- Iterating through hash-tables/maps/dictionaries
|
||||
- External Sources
|
||||
- Filesystem
|
||||
- Network calls (eg. some external REST API service)
|
||||
- Filesystem
|
||||
- Network calls (eg. some external REST API service)
|
||||
|
||||
See [#56](https://github.com/tendermint/abci/issues/56) for original discussion.
|
||||
|
||||
@@ -177,16 +177,16 @@ via light client.
|
||||
### Echo
|
||||
|
||||
- **Request**:
|
||||
- `Message (string)`: A string to echo back
|
||||
- `Message (string)`: A string to echo back
|
||||
- **Response**:
|
||||
- `Message (string)`: The input string
|
||||
- `Message (string)`: The input string
|
||||
- **Usage**:
|
||||
- Echo a string to test an abci client/server implementation
|
||||
- Echo a string to test an abci client/server implementation
|
||||
|
||||
### Flush
|
||||
|
||||
- **Usage**:
|
||||
- Signals that messages queued on the client should be flushed to
|
||||
- Signals that messages queued on the client should be flushed to
|
||||
the server. It is called periodically by the client
|
||||
implementation to ensure asynchronous requests are actually
|
||||
sent, and is called immediately to make a synchronous request,
|
||||
@@ -195,62 +195,62 @@ via light client.
|
||||
### Info
|
||||
|
||||
- **Request**:
|
||||
- `Version (string)`: The Tendermint software semantic version
|
||||
- `BlockVersion (uint64)`: The Tendermint Block Protocol version
|
||||
- `P2PVersion (uint64)`: The Tendermint P2P Protocol version
|
||||
- `Version (string)`: The Tendermint software semantic version
|
||||
- `BlockVersion (uint64)`: The Tendermint Block Protocol version
|
||||
- `P2PVersion (uint64)`: The Tendermint P2P Protocol version
|
||||
- **Response**:
|
||||
- `Data (string)`: Some arbitrary information
|
||||
- `Version (string)`: The application software semantic version
|
||||
- `AppVersion (uint64)`: The application protocol version
|
||||
- `LastBlockHeight (int64)`: Latest block for which the app has
|
||||
- `Data (string)`: Some arbitrary information
|
||||
- `Version (string)`: The application software semantic version
|
||||
- `AppVersion (uint64)`: The application protocol version
|
||||
- `LastBlockHeight (int64)`: Latest block for which the app has
|
||||
called Commit
|
||||
- `LastBlockAppHash ([]byte)`: Latest result of Commit
|
||||
- `LastBlockAppHash ([]byte)`: Latest result of Commit
|
||||
- **Usage**:
|
||||
- Return information about the application state.
|
||||
- Used to sync Tendermint with the application during a handshake
|
||||
- Return information about the application state.
|
||||
- Used to sync Tendermint with the application during a handshake
|
||||
that happens on startup.
|
||||
- The returned `AppVersion` will be included in the Header of every block.
|
||||
- Tendermint expects `LastBlockAppHash` and `LastBlockHeight` to
|
||||
- The returned `AppVersion` will be included in the Header of every block.
|
||||
- Tendermint expects `LastBlockAppHash` and `LastBlockHeight` to
|
||||
be updated during `Commit`, ensuring that `Commit` is never
|
||||
called twice for the same block height.
|
||||
|
||||
### SetOption
|
||||
|
||||
- **Request**:
|
||||
- `Key (string)`: Key to set
|
||||
- `Value (string)`: Value to set for key
|
||||
- `Key (string)`: Key to set
|
||||
- `Value (string)`: Value to set for key
|
||||
- **Response**:
|
||||
- `Code (uint32)`: Response code
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
- `Code (uint32)`: Response code
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
be non-deterministic.
|
||||
- `Info (string)`: Additional information. May
|
||||
- `Info (string)`: Additional information. May
|
||||
be non-deterministic.
|
||||
- **Usage**:
|
||||
- Set non-consensus critical application specific options.
|
||||
- e.g. Key="min-fee", Value="100fermion" could set the minimum fee
|
||||
- Set non-consensus critical application specific options.
|
||||
- e.g. Key="min-fee", Value="100fermion" could set the minimum fee
|
||||
required for CheckTx (but not DeliverTx - that would be
|
||||
consensus critical).
|
||||
|
||||
### InitChain
|
||||
|
||||
- **Request**:
|
||||
- `Time (google.protobuf.Timestamp)`: Genesis time.
|
||||
- `ChainID (string)`: ID of the blockchain.
|
||||
- `ConsensusParams (ConsensusParams)`: Initial consensus-critical parameters.
|
||||
- `Validators ([]ValidatorUpdate)`: Initial genesis validators, sorted by voting power.
|
||||
- `AppStateBytes ([]byte)`: Serialized initial application state. Amino-encoded JSON bytes.
|
||||
- `InitialHeight (int64)`: Height of the initial block (typically `1`).
|
||||
- `Time (google.protobuf.Timestamp)`: Genesis time.
|
||||
- `ChainID (string)`: ID of the blockchain.
|
||||
- `ConsensusParams (ConsensusParams)`: Initial consensus-critical parameters.
|
||||
- `Validators ([]ValidatorUpdate)`: Initial genesis validators, sorted by voting power.
|
||||
- `AppStateBytes ([]byte)`: Serialized initial application state. Amino-encoded JSON bytes.
|
||||
- `InitialHeight (int64)`: Height of the initial block (typically `1`).
|
||||
- **Response**:
|
||||
- `ConsensusParams (ConsensusParams)`: Initial
|
||||
- `ConsensusParams (ConsensusParams)`: Initial
|
||||
consensus-critical parameters (optional).
|
||||
- `Validators ([]ValidatorUpdate)`: Initial validator set (optional).
|
||||
- `AppHash ([]byte)`: Initial application hash.
|
||||
- `Validators ([]ValidatorUpdate)`: Initial validator set (optional).
|
||||
- `AppHash ([]byte)`: Initial application hash.
|
||||
- **Usage**:
|
||||
- Called once upon genesis.
|
||||
- If ResponseInitChain.Validators is empty, the initial validator set will be the RequestInitChain.Validators
|
||||
- If ResponseInitChain.Validators is not empty, it will be the initial
|
||||
- Called once upon genesis.
|
||||
- If ResponseInitChain.Validators is empty, the initial validator set will be the RequestInitChain.Validators
|
||||
- If ResponseInitChain.Validators is not empty, it will be the initial
|
||||
validator set (regardless of what is in RequestInitChain.Validators).
|
||||
- This allows the app to decide if it wants to accept the initial validator
|
||||
- This allows the app to decide if it wants to accept the initial validator
|
||||
set proposed by tendermint (ie. in the genesis file), or if it wants to use
|
||||
a different one (perhaps computed based on some application specific
|
||||
information in the genesis file).
|
||||
@@ -258,154 +258,154 @@ via light client.
|
||||
### Query
|
||||
|
||||
- **Request**:
|
||||
- `Data ([]byte)`: Raw query bytes. Can be used with or in lieu
|
||||
- `Data ([]byte)`: Raw query bytes. Can be used with or in lieu
|
||||
of Path.
|
||||
- `Path (string)`: Path of request, like an HTTP GET path. Can be
|
||||
- `Path (string)`: Path of request, like an HTTP GET path. Can be
|
||||
used with or in liue of Data.
|
||||
- Apps MUST interpret '/store' as a query by key on the
|
||||
- Apps MUST interpret '/store' as a query by key on the
|
||||
underlying store. The key SHOULD be specified in the Data field.
|
||||
- Apps SHOULD allow queries over specific types like
|
||||
- Apps SHOULD allow queries over specific types like
|
||||
'/accounts/...' or '/votes/...'
|
||||
- `Height (int64)`: The block height for which you want the query
|
||||
- `Height (int64)`: The block height for which you want the query
|
||||
(default=0 returns data for the latest committed block). Note
|
||||
that this is the height of the block containing the
|
||||
application's Merkle root hash, which represents the state as it
|
||||
was after committing the block at Height-1
|
||||
- `Prove (bool)`: Return Merkle proof with response if possible
|
||||
- `Prove (bool)`: Return Merkle proof with response if possible
|
||||
- **Response**:
|
||||
- `Code (uint32)`: Response code.
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
- `Code (uint32)`: Response code.
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
be non-deterministic.
|
||||
- `Info (string)`: Additional information. May
|
||||
- `Info (string)`: Additional information. May
|
||||
be non-deterministic.
|
||||
- `Index (int64)`: The index of the key in the tree.
|
||||
- `Key ([]byte)`: The key of the matching data.
|
||||
- `Value ([]byte)`: The value of the matching data.
|
||||
- `Proof (Proof)`: Serialized proof for the value data, if requested, to be
|
||||
- `Index (int64)`: The index of the key in the tree.
|
||||
- `Key ([]byte)`: The key of the matching data.
|
||||
- `Value ([]byte)`: The value of the matching data.
|
||||
- `Proof (Proof)`: Serialized proof for the value data, if requested, to be
|
||||
verified against the `AppHash` for the given Height.
|
||||
- `Height (int64)`: The block height from which data was derived.
|
||||
- `Height (int64)`: The block height from which data was derived.
|
||||
Note that this is the height of the block containing the
|
||||
application's Merkle root hash, which represents the state as it
|
||||
was after committing the block at Height-1
|
||||
- `Codespace (string)`: Namespace for the `Code`.
|
||||
- `Codespace (string)`: Namespace for the `Code`.
|
||||
- **Usage**:
|
||||
- Query for data from the application at current or past height.
|
||||
- Optionally return Merkle proof.
|
||||
- Merkle proof includes self-describing `type` field to support many types
|
||||
- Query for data from the application at current or past height.
|
||||
- Optionally return Merkle proof.
|
||||
- Merkle proof includes self-describing `type` field to support many types
|
||||
of Merkle trees and encoding formats.
|
||||
|
||||
### BeginBlock
|
||||
|
||||
- **Request**:
|
||||
- `Hash ([]byte)`: The block's hash. This can be derived from the
|
||||
- `Hash ([]byte)`: The block's hash. This can be derived from the
|
||||
block header.
|
||||
- `Header (struct{})`: The block header.
|
||||
- `LastCommitInfo (LastCommitInfo)`: Info about the last commit, including the
|
||||
- `Header (struct{})`: The block header.
|
||||
- `LastCommitInfo (LastCommitInfo)`: Info about the last commit, including the
|
||||
round, and the list of validators and which ones signed the last block.
|
||||
- `ByzantineValidators ([]Evidence)`: List of evidence of
|
||||
- `ByzantineValidators ([]Evidence)`: List of evidence of
|
||||
validators that acted maliciously.
|
||||
- **Response**:
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
- **Usage**:
|
||||
- Signals the beginning of a new block. Called prior to
|
||||
- Signals the beginning of a new block. Called prior to
|
||||
any DeliverTxs.
|
||||
- The header contains the height, timestamp, and more - it exactly matches the
|
||||
- The header contains the height, timestamp, and more - it exactly matches the
|
||||
Tendermint block header. We may seek to generalize this in the future.
|
||||
- The `LastCommitInfo` and `ByzantineValidators` can be used to determine
|
||||
- The `LastCommitInfo` and `ByzantineValidators` can be used to determine
|
||||
rewards and punishments for the validators. NOTE validators here do not
|
||||
include pubkeys.
|
||||
|
||||
### CheckTx
|
||||
|
||||
- **Request**:
|
||||
- `Tx ([]byte)`: The request transaction bytes
|
||||
- `Type (CheckTxType)`: What type of `CheckTx` request is this? At present,
|
||||
- `Tx ([]byte)`: The request transaction bytes
|
||||
- `Type (CheckTxType)`: What type of `CheckTx` request is this? At present,
|
||||
there are two possible values: `CheckTx_New` (the default, which says
|
||||
that a full check is required), and `CheckTx_Recheck` (when the mempool is
|
||||
initiating a normal recheck of a transaction).
|
||||
- **Response**:
|
||||
- `Code (uint32)`: Response code
|
||||
- `Data ([]byte)`: Result bytes, if any.
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
- `Code (uint32)`: Response code
|
||||
- `Data ([]byte)`: Result bytes, if any.
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
be non-deterministic.
|
||||
- `Info (string)`: Additional information. May
|
||||
- `Info (string)`: Additional information. May
|
||||
be non-deterministic.
|
||||
- `GasWanted (int64)`: Amount of gas requested for transaction.
|
||||
- `GasUsed (int64)`: Amount of gas consumed by transaction.
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
- `GasWanted (int64)`: Amount of gas requested for transaction.
|
||||
- `GasUsed (int64)`: Amount of gas consumed by transaction.
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
transactions (eg. by account).
|
||||
- `Codespace (string)`: Namespace for the `Code`.
|
||||
- `Codespace (string)`: Namespace for the `Code`.
|
||||
- **Usage**:
|
||||
- Technically optional - not involved in processing blocks.
|
||||
- Guardian of the mempool: every node runs CheckTx before letting a
|
||||
- Technically optional - not involved in processing blocks.
|
||||
- Guardian of the mempool: every node runs CheckTx before letting a
|
||||
transaction into its local mempool.
|
||||
- The transaction may come from an external user or another node
|
||||
- CheckTx need not execute the transaction in full, but rather a light-weight
|
||||
- The transaction may come from an external user or another node
|
||||
- CheckTx need not execute the transaction in full, but rather a light-weight
|
||||
yet stateful validation, like checking signatures and account balances, but
|
||||
not running code in a virtual machine.
|
||||
- Transactions where `ResponseCheckTx.Code != 0` will be rejected - they will not be broadcast to
|
||||
- Transactions where `ResponseCheckTx.Code != 0` will be rejected - they will not be broadcast to
|
||||
other nodes or included in a proposal block.
|
||||
- Tendermint attributes no other value to the response code
|
||||
- Tendermint attributes no other value to the response code
|
||||
|
||||
### DeliverTx
|
||||
|
||||
- **Request**:
|
||||
- `Tx ([]byte)`: The request transaction bytes.
|
||||
- `Tx ([]byte)`: The request transaction bytes.
|
||||
- **Response**:
|
||||
- `Code (uint32)`: Response code.
|
||||
- `Data ([]byte)`: Result bytes, if any.
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
- `Code (uint32)`: Response code.
|
||||
- `Data ([]byte)`: Result bytes, if any.
|
||||
- `Log (string)`: The output of the application's logger. May
|
||||
be non-deterministic.
|
||||
- `Info (string)`: Additional information. May
|
||||
- `Info (string)`: Additional information. May
|
||||
be non-deterministic.
|
||||
- `GasWanted (int64)`: Amount of gas requested for transaction.
|
||||
- `GasUsed (int64)`: Amount of gas consumed by transaction.
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
- `GasWanted (int64)`: Amount of gas requested for transaction.
|
||||
- `GasUsed (int64)`: Amount of gas consumed by transaction.
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
transactions (eg. by account).
|
||||
- `Codespace (string)`: Namespace for the `Code`.
|
||||
- `Codespace (string)`: Namespace for the `Code`.
|
||||
- **Usage**:
|
||||
- The workhorse of the application - non-optional.
|
||||
- Execute the transaction in full.
|
||||
- `ResponseDeliverTx.Code == 0` only if the transaction is fully valid.
|
||||
- The workhorse of the application - non-optional.
|
||||
- Execute the transaction in full.
|
||||
- `ResponseDeliverTx.Code == 0` only if the transaction is fully valid.
|
||||
|
||||
### EndBlock
|
||||
|
||||
- **Request**:
|
||||
- `Height (int64)`: Height of the block just executed.
|
||||
- `Height (int64)`: Height of the block just executed.
|
||||
- **Response**:
|
||||
- `ValidatorUpdates ([]ValidatorUpdate)`: Changes to validator set (set
|
||||
- `ValidatorUpdates ([]ValidatorUpdate)`: Changes to validator set (set
|
||||
voting power to 0 to remove).
|
||||
- `ConsensusParamUpdates (ConsensusParams)`: Changes to
|
||||
- `ConsensusParamUpdates (ConsensusParams)`: Changes to
|
||||
consensus-critical time, size, and other parameters.
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
- `Tags ([]kv.Pair)`: Key-Value tags for filtering and indexing
|
||||
- **Usage**:
|
||||
- Signals the end of a block.
|
||||
- Called after all transactions, prior to each Commit.
|
||||
- Validator updates returned by block `H` impact blocks `H+1`, `H+2`, and
|
||||
- Signals the end of a block.
|
||||
- Called after all transactions, prior to each Commit.
|
||||
- Validator updates returned by block `H` impact blocks `H+1`, `H+2`, and
|
||||
`H+3`, but only effects changes on the validator set of `H+2`:
|
||||
- `H+1`: NextValidatorsHash
|
||||
- `H+2`: ValidatorsHash (and thus the validator set)
|
||||
- `H+3`: LastCommitInfo (ie. the last validator set)
|
||||
- Consensus params returned for block `H` apply for block `H+1`
|
||||
- `H+1`: NextValidatorsHash
|
||||
- `H+2`: ValidatorsHash (and thus the validator set)
|
||||
- `H+3`: LastCommitInfo (ie. the last validator set)
|
||||
- Consensus params returned for block `H` apply for block `H+1`
|
||||
|
||||
### Commit
|
||||
|
||||
- **Response**:
|
||||
- `Data ([]byte)`: The Merkle root hash of the application state
|
||||
- `RetainHeight (int64)`: Blocks below this height may be removed. Defaults
|
||||
- `Data ([]byte)`: The Merkle root hash of the application state
|
||||
- `RetainHeight (int64)`: Blocks below this height may be removed. Defaults
|
||||
to `0` (retain all).
|
||||
- **Usage**:
|
||||
- Persist the application state.
|
||||
- Return an (optional) Merkle root hash of the application state
|
||||
- `ResponseCommit.Data` is included as the `Header.AppHash` in the next block
|
||||
- it may be empty
|
||||
- Later calls to `Query` can return proofs about the application state anchored
|
||||
- Persist the application state.
|
||||
- Return an (optional) Merkle root hash of the application state
|
||||
- `ResponseCommit.Data` is included as the `Header.AppHash` in the next block
|
||||
- it may be empty
|
||||
- Later calls to `Query` can return proofs about the application state anchored
|
||||
in this Merkle root hash
|
||||
- Note developers can return whatever they want here (could be nothing, or a
|
||||
- Note developers can return whatever they want here (could be nothing, or a
|
||||
constant string, etc.), so long as it is deterministic - it must not be a
|
||||
function of anything that did not come from the
|
||||
BeginBlock/DeliverTx/EndBlock methods.
|
||||
- Use `RetainHeight` with caution! If all nodes in the network remove historical
|
||||
- Use `RetainHeight` with caution! If all nodes in the network remove historical
|
||||
blocks then this data is permanently lost, and no new nodes will be able to
|
||||
join the network and bootstrap. Historical blocks may also be required for
|
||||
other purposes, e.g. auditing, replay of non-persisted heights, light client
|
||||
@@ -414,256 +414,254 @@ via light client.
|
||||
### ListSnapshots
|
||||
|
||||
- **Response**:
|
||||
- `Snapshots ([]Snapshot)`: List of local state snapshots.
|
||||
- `Snapshots ([]Snapshot)`: List of local state snapshots.
|
||||
- **Usage**:
|
||||
- Used during state sync to discover available snapshots on peers.
|
||||
- See `Snapshot` data type for details.
|
||||
- Used during state sync to discover available snapshots on peers.
|
||||
- See `Snapshot` data type for details.
|
||||
|
||||
### LoadSnapshotChunk
|
||||
|
||||
- **Request**:
|
||||
- `Height (uint64)`: The height of the snapshot the chunks belongs to.
|
||||
- `Format (uint32)`: The application-specific format of the snapshot the chunk belongs to.
|
||||
- `Chunk (uint32)`: The chunk index, starting from `0` for the initial chunk.
|
||||
- `Height (uint64)`: The height of the snapshot the chunks belongs to.
|
||||
- `Format (uint32)`: The application-specific format of the snapshot the chunk belongs to.
|
||||
- `Chunk (uint32)`: The chunk index, starting from `0` for the initial chunk.
|
||||
- **Response**:
|
||||
- `Chunk ([]byte)`: The binary chunk contents, in an arbitray format. Chunk messages cannot be
|
||||
- `Chunk ([]byte)`: The binary chunk contents, in an arbitray format. Chunk messages cannot be
|
||||
larger than 16 MB _including metadata_, so 10 MB is a good starting point.
|
||||
- **Usage**:
|
||||
- Used during state sync to retrieve snapshot chunks from peers.
|
||||
- Used during state sync to retrieve snapshot chunks from peers.
|
||||
|
||||
### OfferSnapshot
|
||||
|
||||
- **Request**:
|
||||
- `Snapshot (Snapshot)`: The snapshot offered for restoration.
|
||||
- `AppHash ([]byte)`: The light client-verified app hash for this height, from the blockchain.
|
||||
- `Snapshot (Snapshot)`: The snapshot offered for restoration.
|
||||
- `AppHash ([]byte)`: The light client-verified app hash for this height, from the blockchain.
|
||||
- **Response**:
|
||||
- `Result (Result)`: The result of the snapshot offer.
|
||||
- `ACCEPT`: Snapshot is accepted, start applying chunks.
|
||||
- `ABORT`: Abort snapshot restoration, and don't try any other snapshots.
|
||||
- `REJECT`: Reject this specific snapshot, try others.
|
||||
- `REJECT_FORMAT`: Reject all snapshots with this `format`, try others.
|
||||
- `REJECT_SENDERS`: Reject all snapshots from all senders of this snapshot, try others.
|
||||
- `Result (Result)`: The result of the snapshot offer.
|
||||
- `ACCEPT`: Snapshot is accepted, start applying chunks.
|
||||
- `ABORT`: Abort snapshot restoration, and don't try any other snapshots.
|
||||
- `REJECT`: Reject this specific snapshot, try others.
|
||||
- `REJECT_FORMAT`: Reject all snapshots with this `format`, try others.
|
||||
- `REJECT_SENDERS`: Reject all snapshots from all senders of this snapshot, try others.
|
||||
- **Usage**:
|
||||
- `OfferSnapshot` is called when bootstrapping a node using state sync. The application may
|
||||
- `OfferSnapshot` is called when bootstrapping a node using state sync. The application may
|
||||
accept or reject snapshots as appropriate. Upon accepting, Tendermint will retrieve and
|
||||
apply snapshot chunks via `ApplySnapshotChunk`. The application may also choose to reject a
|
||||
snapshot in the chunk response, in which case it should be prepared to accept further
|
||||
`OfferSnapshot` calls.
|
||||
- Only `AppHash` can be trusted, as it has been verified by the light client. Any other data
|
||||
- Only `AppHash` can be trusted, as it has been verified by the light client. Any other data
|
||||
can be spoofed by adversaries, so applications should employ additional verification schemes
|
||||
to avoid denial-of-service attacks. The verified `AppHash` is automatically checked against
|
||||
the restored application at the end of snapshot restoration.
|
||||
- For more information, see the `Snapshot` data type or the [state sync section](apps.md#state-sync).
|
||||
- For more information, see the `Snapshot` data type or the [state sync section](apps.md#state-sync).
|
||||
|
||||
### ApplySnapshotChunk
|
||||
|
||||
- **Request**:
|
||||
- `Index (uint32)`: The chunk index, starting from `0`. Tendermint applies chunks sequentially.
|
||||
- `Chunk ([]byte)`: The binary chunk contents, as returned by `LoadSnapshotChunk`.
|
||||
- `Sender (string)`: The P2P ID of the node who sent this chunk.
|
||||
- `Index (uint32)`: The chunk index, starting from `0`. Tendermint applies chunks sequentially.
|
||||
- `Chunk ([]byte)`: The binary chunk contents, as returned by `LoadSnapshotChunk`.
|
||||
- `Sender (string)`: The P2P ID of the node who sent this chunk.
|
||||
- **Response**:
|
||||
- `Result (Result)`: The result of applying this chunk.
|
||||
- `ACCEPT`: The chunk was accepted.
|
||||
- `ABORT`: Abort snapshot restoration, and don't try any other snapshots.
|
||||
- `RETRY`: Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate.
|
||||
- `RETRY_SNAPSHOT`: Restart this snapshot from `OfferSnapshot`, reusing chunks unless
|
||||
- `Result (Result)`: The result of applying this chunk.
|
||||
- `ACCEPT`: The chunk was accepted.
|
||||
- `ABORT`: Abort snapshot restoration, and don't try any other snapshots.
|
||||
- `RETRY`: Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate.
|
||||
- `RETRY_SNAPSHOT`: Restart this snapshot from `OfferSnapshot`, reusing chunks unless
|
||||
instructed otherwise.
|
||||
- `REJECT_SNAPSHOT`: Reject this snapshot, try a different one.
|
||||
- `RefetchChunks ([]uint32)`: Refetch and reapply the given chunks, regardless of `Result`. Only
|
||||
- `REJECT_SNAPSHOT`: Reject this snapshot, try a different one.
|
||||
- `RefetchChunks ([]uint32)`: Refetch and reapply the given chunks, regardless of `Result`. Only
|
||||
the listed chunks will be refetched, and reapplied in sequential order.
|
||||
- `RejectSenders ([]string)`: Reject the given P2P senders, regardless of `Result`. Any chunks
|
||||
- `RejectSenders ([]string)`: Reject the given P2P senders, regardless of `Result`. Any chunks
|
||||
already applied will not be refetched unless explicitly requested, but queued chunks from these senders will be discarded, and new chunks or other snapshots rejected.
|
||||
- **Usage**:
|
||||
- The application can choose to refetch chunks and/or ban P2P peers as appropriate. Tendermint
|
||||
- The application can choose to refetch chunks and/or ban P2P peers as appropriate. Tendermint
|
||||
will not do this unless instructed by the application.
|
||||
- The application may want to verify each chunk, e.g. by attaching chunk hashes in
|
||||
- The application may want to verify each chunk, e.g. by attaching chunk hashes in
|
||||
`Snapshot.Metadata` and/or incrementally verifying contents against `AppHash`.
|
||||
- When all chunks have been accepted, Tendermint will make an ABCI `Info` call to verify that
|
||||
- When all chunks have been accepted, Tendermint will make an ABCI `Info` call to verify that
|
||||
`LastBlockAppHash` and `LastBlockHeight` matches the expected values, and record the
|
||||
`AppVersion` in the node state. It then switches to fast sync or consensus and joins the
|
||||
network.
|
||||
- If Tendermint is unable to retrieve the next chunk after some time (e.g. because no suitable
|
||||
- If Tendermint is unable to retrieve the next chunk after some time (e.g. because no suitable
|
||||
peers are available), it will reject the snapshot and try a different one via `OfferSnapshot`.
|
||||
The application should be prepared to reset and accept it or abort as appropriate.
|
||||
|
||||
###
|
||||
|
||||
## Data Types
|
||||
|
||||
### Header
|
||||
|
||||
- **Fields**:
|
||||
- `Version (Version)`: Version of the blockchain and the application
|
||||
- `ChainID (string)`: ID of the blockchain
|
||||
- `Height (int64)`: Height of the block in the chain
|
||||
- `Time (google.protobuf.Timestamp)`: Time of the previous block.
|
||||
- `Version (Version)`: Version of the blockchain and the application
|
||||
- `ChainID (string)`: ID of the blockchain
|
||||
- `Height (int64)`: Height of the block in the chain
|
||||
- `Time (google.protobuf.Timestamp)`: Time of the previous block.
|
||||
For most blocks it's the weighted median of the timestamps of the valid votes in the
|
||||
block.LastCommit, except for the initial height where it's the genesis time.
|
||||
- `LastBlockID (BlockID)`: Hash of the previous (parent) block
|
||||
- `LastCommitHash ([]byte)`: Hash of the previous block's commit
|
||||
- `ValidatorsHash ([]byte)`: Hash of the validator set for this block
|
||||
- `NextValidatorsHash ([]byte)`: Hash of the validator set for the next block
|
||||
- `ConsensusHash ([]byte)`: Hash of the consensus parameters for this block
|
||||
- `AppHash ([]byte)`: Data returned by the last call to `Commit` - typically the
|
||||
- `LastBlockID (BlockID)`: Hash of the previous (parent) block
|
||||
- `LastCommitHash ([]byte)`: Hash of the previous block's commit
|
||||
- `ValidatorsHash ([]byte)`: Hash of the validator set for this block
|
||||
- `NextValidatorsHash ([]byte)`: Hash of the validator set for the next block
|
||||
- `ConsensusHash ([]byte)`: Hash of the consensus parameters for this block
|
||||
- `AppHash ([]byte)`: Data returned by the last call to `Commit` - typically the
|
||||
Merkle root of the application state after executing the previous block's
|
||||
transactions
|
||||
- `LastResultsHash ([]byte)`: Root hash of all results from the txs from the previous block.
|
||||
- `EvidenceHash ([]byte)`: Hash of the evidence included in this block
|
||||
- `ProposerAddress ([]byte)`: Original proposer for the block
|
||||
- `LastResultsHash ([]byte)`: Root hash of all results from the txs from the previous block.
|
||||
- `EvidenceHash ([]byte)`: Hash of the evidence included in this block
|
||||
- `ProposerAddress ([]byte)`: Original proposer for the block
|
||||
- **Usage**:
|
||||
- Provided in RequestBeginBlock
|
||||
- Provides important context about the current state of the blockchain -
|
||||
- Provided in RequestBeginBlock
|
||||
- Provides important context about the current state of the blockchain -
|
||||
especially height and time.
|
||||
- Provides the proposer of the current block, for use in proposer-based
|
||||
- Provides the proposer of the current block, for use in proposer-based
|
||||
reward mechanisms.
|
||||
- `LastResultsHash` is the root hash of a Merkle tree built from `ResponseDeliverTx` responses (`Log`, `Info`, `Codespace` and `Events` fields are ignored).
|
||||
- `LastResultsHash` is the root hash of a Merkle tree built from `ResponseDeliverTx` responses (`Log`, `Info`, `Codespace` and `Events` fields are ignored).
|
||||
|
||||
### Version
|
||||
|
||||
- **Fields**:
|
||||
- `Block (uint64)`: Protocol version of the blockchain data structures.
|
||||
- `App (uint64)`: Protocol version of the application.
|
||||
- `Block (uint64)`: Protocol version of the blockchain data structures.
|
||||
- `App (uint64)`: Protocol version of the application.
|
||||
- **Usage**:
|
||||
- Block version should be static in the life of a blockchain.
|
||||
- App version may be updated over time by the application.
|
||||
- Block version should be static in the life of a blockchain.
|
||||
- App version may be updated over time by the application.
|
||||
|
||||
### Validator
|
||||
|
||||
- **Fields**:
|
||||
- `Address ([]byte)`: Address of the validator (the first 20 bytes of SHA256(public key))
|
||||
- `Power (int64)`: Voting power of the validator
|
||||
- `Address ([]byte)`: Address of the validator (the first 20 bytes of SHA256(public key))
|
||||
- `Power (int64)`: Voting power of the validator
|
||||
- **Usage**:
|
||||
- Validator identified by address
|
||||
- Used in RequestBeginBlock as part of VoteInfo
|
||||
- Does not include PubKey to avoid sending potentially large quantum pubkeys
|
||||
- Validator identified by address
|
||||
- Used in RequestBeginBlock as part of VoteInfo
|
||||
- Does not include PubKey to avoid sending potentially large quantum pubkeys
|
||||
over the ABCI
|
||||
|
||||
### ValidatorUpdate
|
||||
|
||||
- **Fields**:
|
||||
- `PubKey (PubKey)`: Public key of the validator
|
||||
- `Power (int64)`: Voting power of the validator
|
||||
- `PubKey (PubKey)`: Public key of the validator
|
||||
- `Power (int64)`: Voting power of the validator
|
||||
- **Usage**:
|
||||
- Validator identified by PubKey
|
||||
- Used to tell Tendermint to update the validator set
|
||||
- Validator identified by PubKey
|
||||
- Used to tell Tendermint to update the validator set
|
||||
|
||||
### VoteInfo
|
||||
|
||||
- **Fields**:
|
||||
- `Validator (Validator)`: A validator
|
||||
- `SignedLastBlock (bool)`: Indicates whether or not the validator signed
|
||||
- `Validator (Validator)`: A validator
|
||||
- `SignedLastBlock (bool)`: Indicates whether or not the validator signed
|
||||
the last block
|
||||
- **Usage**:
|
||||
- Indicates whether a validator signed the last block, allowing for rewards
|
||||
- Indicates whether a validator signed the last block, allowing for rewards
|
||||
based on validator availability
|
||||
|
||||
### PubKey
|
||||
|
||||
- **Fields**:
|
||||
- `Type (string)`: Type of the public key. A simple string like `"ed25519"`.
|
||||
- `Type (string)`: Type of the public key. A simple string like `"ed25519"`.
|
||||
In the future, may indicate a serialization algorithm to parse the `Data`,
|
||||
for instance `"amino"`.
|
||||
- `Data ([]byte)`: Public key data. For a simple public key, it's just the
|
||||
- `Data ([]byte)`: Public key data. For a simple public key, it's just the
|
||||
raw bytes. If the `Type` indicates an encoding algorithm, this is the
|
||||
encoded public key.
|
||||
- **Usage**:
|
||||
- A generic and extensible typed public key
|
||||
- A generic and extensible typed public key
|
||||
|
||||
### Evidence
|
||||
|
||||
- **Fields**:
|
||||
- `Type (string)`: Type of the evidence. A hierarchical path like
|
||||
- `Type (string)`: Type of the evidence. A hierarchical path like
|
||||
"duplicate/vote".
|
||||
- `Validator (Validator`: The offending validator
|
||||
- `Height (int64)`: Height when the offense occured
|
||||
- `Time (google.protobuf.Timestamp)`: Time of the block that was committed at the height that the offense occured
|
||||
- `TotalVotingPower (int64)`: Total voting power of the validator set at
|
||||
- `Validator (Validator`: The offending validator
|
||||
- `Height (int64)`: Height when the offense occured
|
||||
- `Time (google.protobuf.Timestamp)`: Time of the block that was committed at the height that the offense occured
|
||||
- `TotalVotingPower (int64)`: Total voting power of the validator set at
|
||||
height `Height`
|
||||
|
||||
### LastCommitInfo
|
||||
|
||||
- **Fields**:
|
||||
- `Round (int32)`: Commit round.
|
||||
- `Votes ([]VoteInfo)`: List of validators addresses in the last validator set
|
||||
- `Round (int32)`: Commit round.
|
||||
- `Votes ([]VoteInfo)`: List of validators addresses in the last validator set
|
||||
with their voting power and whether or not they signed a vote.
|
||||
|
||||
### ConsensusParams
|
||||
|
||||
- **Fields**:
|
||||
- `Block (BlockParams)`: Parameters limiting the size of a block and time between consecutive blocks.
|
||||
- `Evidence (EvidenceParams)`: Parameters limiting the validity of
|
||||
- `Block (BlockParams)`: Parameters limiting the size of a block and time between consecutive blocks.
|
||||
- `Evidence (EvidenceParams)`: Parameters limiting the validity of
|
||||
evidence of byzantine behaviour.
|
||||
- `Validator (ValidatorParams)`: Parameters limiting the types of pubkeys validators can use.
|
||||
- `Version (VersionParams)`: The ABCI application version.
|
||||
- `Validator (ValidatorParams)`: Parameters limiting the types of pubkeys validators can use.
|
||||
- `Version (VersionParams)`: The ABCI application version.
|
||||
|
||||
### BlockParams
|
||||
|
||||
- **Fields**:
|
||||
- `MaxBytes (int64)`: Max size of a block, in bytes.
|
||||
- `MaxGas (int64)`: Max sum of `GasWanted` in a proposed block.
|
||||
- NOTE: blocks that violate this may be committed if there are Byzantine proposers.
|
||||
- `MaxBytes (int64)`: Max size of a block, in bytes.
|
||||
- `MaxGas (int64)`: Max sum of `GasWanted` in a proposed block.
|
||||
- NOTE: blocks that violate this may be committed if there are Byzantine proposers.
|
||||
It's the application's responsibility to handle this when processing a
|
||||
block!
|
||||
|
||||
### EvidenceParams
|
||||
|
||||
- **Fields**:
|
||||
- `MaxAgeNumBlocks (int64)`: Max age of evidence, in blocks.
|
||||
- `MaxAgeDuration (time.Duration)`: Max age of evidence, in time.
|
||||
- `MaxAgeNumBlocks (int64)`: Max age of evidence, in blocks.
|
||||
- `MaxAgeDuration (time.Duration)`: Max age of evidence, in time.
|
||||
It should correspond with an app's "unbonding period" or other similar
|
||||
mechanism for handling [Nothing-At-Stake
|
||||
attacks](https://github.com/ethereum/wiki/wiki/Proof-of-Stake-FAQ#what-is-the-nothing-at-stake-problem-and-how-can-it-be-fixed).
|
||||
|
||||
- Evidence older than `MaxAgeNumBlocks` && `MaxAgeDuration` is considered
|
||||
- Evidence older than `MaxAgeNumBlocks` && `MaxAgeDuration` is considered
|
||||
stale and ignored.
|
||||
- In Cosmos-SDK based blockchains, `MaxAgeDuration` is usually equal to the
|
||||
- In Cosmos-SDK based blockchains, `MaxAgeDuration` is usually equal to the
|
||||
unbonding period. `MaxAgeNumBlocks` is calculated by dividing the unboding
|
||||
period by the average block time (e.g. 2 weeks / 6s per block = 2d8h).
|
||||
- `MaxNum (uint32)`: The maximum number of evidence that can be committed to a single block
|
||||
- `ProofTrialPeriod (int64)`: The duration in terms of blocks that an indicted node has to
|
||||
provide proof of correctly executing a lock change in the event of amnesia evidence.
|
||||
- `MaxNum (uint32)`: The maximum number of evidence that can be committed to a single block
|
||||
- `ProofTrialPeriod (int64)`: The duration in terms of blocks that an indicted node has to
|
||||
provide proof of correctly executing a lock change in the event of amnesia evidence.
|
||||
|
||||
### ValidatorParams
|
||||
|
||||
- **Fields**:
|
||||
- `PubKeyTypes ([]string)`: List of accepted pubkey types. Uses same
|
||||
- `PubKeyTypes ([]string)`: List of accepted pubkey types. Uses same
|
||||
naming as `PubKey.Type`.
|
||||
|
||||
### VersionParams
|
||||
|
||||
- **Fields**:
|
||||
- `AppVersion (uint64)`: The ABCI application version.
|
||||
- `AppVersion (uint64)`: The ABCI application version.
|
||||
|
||||
### Proof
|
||||
|
||||
- **Fields**:
|
||||
- `Ops ([]ProofOp)`: List of chained Merkle proofs, of possibly different types
|
||||
- The Merkle root of one op is the value being proven in the next op.
|
||||
- The Merkle root of the final op should equal the ultimate root hash being
|
||||
- `Ops ([]ProofOp)`: List of chained Merkle proofs, of possibly different types
|
||||
- The Merkle root of one op is the value being proven in the next op.
|
||||
- The Merkle root of the final op should equal the ultimate root hash being
|
||||
verified against.
|
||||
|
||||
### ProofOp
|
||||
|
||||
- **Fields**:
|
||||
- `Type (string)`: Type of Merkle proof and how it's encoded.
|
||||
- `Key ([]byte)`: Key in the Merkle tree that this proof is for.
|
||||
- `Data ([]byte)`: Encoded Merkle proof for the key.
|
||||
- `Type (string)`: Type of Merkle proof and how it's encoded.
|
||||
- `Key ([]byte)`: Key in the Merkle tree that this proof is for.
|
||||
- `Data ([]byte)`: Encoded Merkle proof for the key.
|
||||
|
||||
### Snapshot
|
||||
|
||||
- **Fields**:
|
||||
- `Height (uint64)`: The height at which the snapshot was taken (after commit).
|
||||
- `Format (uint32)`: An application-specific snapshot format, allowing applications to version
|
||||
- `Height (uint64)`: The height at which the snapshot was taken (after commit).
|
||||
- `Format (uint32)`: An application-specific snapshot format, allowing applications to version
|
||||
their snapshot data format and make backwards-incompatible changes. Tendermint does not
|
||||
interpret this.
|
||||
- `Chunks (uint32)`: The number of chunks in the snapshot. Must be at least 1 (even if empty).
|
||||
- `Hash (bytes)`: An arbitrary snapshot hash. Must be equal only for identical snapshots across
|
||||
- `Chunks (uint32)`: The number of chunks in the snapshot. Must be at least 1 (even if empty).
|
||||
- `Hash (bytes)`: An arbitrary snapshot hash. Must be equal only for identical snapshots across
|
||||
nodes. Tendermint does not interpret the hash, it only compares them.
|
||||
- `Metadata (bytes)`: Arbitrary application metadata, for example chunk hashes or other
|
||||
- `Metadata (bytes)`: Arbitrary application metadata, for example chunk hashes or other
|
||||
verification data.
|
||||
|
||||
- **Usage**:
|
||||
- Used for state sync snapshots, see [separate section](apps.md#state-sync) for details.
|
||||
- A snapshot is considered identical across nodes only if _all_ fields are equal (including
|
||||
- Used for state sync snapshots, see [separate section](apps.md#state-sync) for details.
|
||||
- A snapshot is considered identical across nodes only if _all_ fields are equal (including
|
||||
`Metadata`). Chunks may be retrieved from all nodes that have the same snapshot.
|
||||
- When sent across the network, a snapshot message can be at most 4 MB.
|
||||
- When sent across the network, a snapshot message can be at most 4 MB.
|
||||
|
||||
@@ -203,7 +203,7 @@ blockchain.
|
||||
Updates to the Tendermint validator set can be made by returning
|
||||
`ValidatorUpdate` objects in the `ResponseEndBlock`:
|
||||
|
||||
```
|
||||
```proto
|
||||
message ValidatorUpdate {
|
||||
PubKey pub_key
|
||||
int64 power
|
||||
@@ -226,9 +226,9 @@ following rules:
|
||||
- if power is 0, the validator must already exist, and will be removed from the
|
||||
validator set
|
||||
- if power is non-0:
|
||||
- if the validator does not already exist, it will be added to the validator
|
||||
- if the validator does not already exist, it will be added to the validator
|
||||
set with the given power
|
||||
- if the validator does already exist, its power will be adjusted to the given power
|
||||
- if the validator does already exist, its power will be adjusted to the given power
|
||||
- the total power of the new validator set must not exceed MaxTotalVotingPower
|
||||
|
||||
Note the updates returned in block `H` will only take effect at block `H+2`.
|
||||
@@ -293,14 +293,14 @@ Must have `MaxAgeNumBlocks > 0`.
|
||||
|
||||
This is the maximum number of evidence that can be committed to a single block.
|
||||
|
||||
The product of this and the `MaxEvidenceBytes` must not exceed the size of
|
||||
The product of this and the `MaxEvidenceBytes` must not exceed the size of
|
||||
a block minus it's overhead ( ~ `MaxBytes`).
|
||||
|
||||
The amount must be a positive number.
|
||||
|
||||
### EvidenceParams.ProofTrialPeriod
|
||||
|
||||
This is the duration in terms of blocks that an indicted validator has to prove a
|
||||
This is the duration in terms of blocks that an indicted validator has to prove a
|
||||
correct lock change in the event of amnesia evidence when a validator voted more
|
||||
than once across different rounds.
|
||||
|
||||
@@ -381,7 +381,7 @@ Some applications (eg. Ethereum, Cosmos-SDK) have multiple "levels" of Merkle tr
|
||||
where the leaves of one tree are the root hashes of others. To support this, and
|
||||
the general variability in Merkle proofs, the `ResponseQuery.Proof` has some minimal structure:
|
||||
|
||||
```
|
||||
```proto
|
||||
message Proof {
|
||||
repeated ProofOp ops
|
||||
}
|
||||
@@ -437,7 +437,7 @@ failed during the Commit of block H, then `last_block_height = H-1` and
|
||||
We now distinguish three heights, and describe how Tendermint syncs itself with
|
||||
the app.
|
||||
|
||||
```
|
||||
```md
|
||||
storeBlockHeight = height of the last block Tendermint saw a commit for
|
||||
stateBlockHeight = height of the last block for which Tendermint completed all
|
||||
block processing and saved all ABCI results to disk
|
||||
@@ -497,8 +497,8 @@ State sync is an alternative mechanism for bootstrapping a new node, where it fe
|
||||
of the state machine at a given height and restores it. Depending on the application, this can
|
||||
be several orders of magnitude faster than replaying blocks.
|
||||
|
||||
Note that state sync does not currently backfill historical blocks, so the node will have a
|
||||
truncated block history - users are advised to consider the broader network implications of this in
|
||||
Note that state sync does not currently backfill historical blocks, so the node will have a
|
||||
truncated block history - users are advised to consider the broader network implications of this in
|
||||
terms of block availability and auditability. This functionality may be added in the future.
|
||||
|
||||
For details on the specific ABCI calls and types, see the [methods and types section](abci.md).
|
||||
@@ -509,20 +509,20 @@ Applications that want to support state syncing must take state snapshots at reg
|
||||
this is accomplished is entirely up to the application. A snapshot consists of some metadata and
|
||||
a set of binary chunks in an arbitrary format:
|
||||
|
||||
* `Height (uint64)`: The height at which the snapshot is taken. It must be taken after the given
|
||||
- `Height (uint64)`: The height at which the snapshot is taken. It must be taken after the given
|
||||
height has been committed, and must not contain data from any later heights.
|
||||
|
||||
* `Format (uint32)`: An arbitrary snapshot format identifier. This can be used to version snapshot
|
||||
formats, e.g. to switch from Protobuf to MessagePack for serialization. The application can use
|
||||
- `Format (uint32)`: An arbitrary snapshot format identifier. This can be used to version snapshot
|
||||
formats, e.g. to switch from Protobuf to MessagePack for serialization. The application can use
|
||||
this when restoring to choose whether to accept or reject a snapshot.
|
||||
|
||||
* `Chunks (uint32)`: The number of chunks in the snapshot. Each chunk contains arbitrary binary
|
||||
- `Chunks (uint32)`: The number of chunks in the snapshot. Each chunk contains arbitrary binary
|
||||
data, and should be less than 16 MB; 10 MB is a good starting point.
|
||||
|
||||
* `Hash ([]byte)`: An arbitrary hash of the snapshot. This is used to check whether a snapshot is
|
||||
- `Hash ([]byte)`: An arbitrary hash of the snapshot. This is used to check whether a snapshot is
|
||||
the same across nodes when downloading chunks.
|
||||
|
||||
* `Metadata ([]byte)`: Arbitrary snapshot metadata, e.g. chunk hashes for verification or any other
|
||||
- `Metadata ([]byte)`: Arbitrary snapshot metadata, e.g. chunk hashes for verification or any other
|
||||
necessary info.
|
||||
|
||||
For a snapshot to be considered the same across nodes, all of these fields must be identical. When
|
||||
@@ -533,15 +533,15 @@ application via the ABCI `ListSnapshots` method to discover available snapshots,
|
||||
snapshot chunks via `LoadSnapshotChunk`. The application is free to choose how to implement this
|
||||
and which formats to use, but should provide the following guarantees:
|
||||
|
||||
* **Consistent:** A snapshot should be taken at a single isolated height, unaffected by
|
||||
concurrent writes. This can e.g. be accomplished by using a data store that supports ACID
|
||||
- **Consistent:** A snapshot should be taken at a single isolated height, unaffected by
|
||||
concurrent writes. This can e.g. be accomplished by using a data store that supports ACID
|
||||
transactions with snapshot isolation.
|
||||
|
||||
* **Asynchronous:** Taking a snapshot can be time-consuming, so it should not halt chain progress,
|
||||
- **Asynchronous:** Taking a snapshot can be time-consuming, so it should not halt chain progress,
|
||||
for example by running in a separate thread.
|
||||
|
||||
* **Deterministic:** A snapshot taken at the same height in the same format should be identical
|
||||
(at the byte level) across nodes, including all metadata. This ensures good availability of
|
||||
- **Deterministic:** A snapshot taken at the same height in the same format should be identical
|
||||
(at the byte level) across nodes, including all metadata. This ensures good availability of
|
||||
chunks, and that they fit together across nodes.
|
||||
|
||||
A very basic approach might be to use a datastore with MVCC transactions (such as RocksDB),
|
||||
@@ -583,7 +583,7 @@ the application aborts.
|
||||
#### Snapshot Restoration
|
||||
|
||||
Once a snapshot has been accepted via `OfferSnapshot`, Tendermint begins downloading chunks from
|
||||
any peers that have the same snapshot (i.e. that have identical metadata fields). Chunks are
|
||||
any peers that have the same snapshot (i.e. that have identical metadata fields). Chunks are
|
||||
spooled in a temporary directory, and then given to the application in sequential order via
|
||||
`ApplySnapshotChunk` until all chunks have been accepted.
|
||||
|
||||
@@ -603,7 +603,7 @@ restarting restoration, or simply abort with an error.
|
||||
#### Snapshot Verification
|
||||
|
||||
Once all chunks have been accepted, Tendermint issues an `Info` ABCI call to retrieve the
|
||||
`LastBlockAppHash`. This is compared with the trusted app hash from the chain, retrieved and
|
||||
`LastBlockAppHash`. This is compared with the trusted app hash from the chain, retrieved and
|
||||
verified using the light client. Tendermint also checks that `LastBlockHeight` corresponds to the
|
||||
height of the snapshot.
|
||||
|
||||
@@ -623,8 +623,8 @@ P2P configuration options to whitelist a set of trusted peers that can provide v
|
||||
#### Transition to Consensus
|
||||
|
||||
Once the snapshot has been restored, Tendermint gathers additional information necessary for
|
||||
bootstrapping the node (e.g. chain ID, consensus parameters, validator sets, and block headers)
|
||||
from the genesis file and light client RPC servers. It also fetches and records the `AppVersion`
|
||||
bootstrapping the node (e.g. chain ID, consensus parameters, validator sets, and block headers)
|
||||
from the genesis file and light client RPC servers. It also fetches and records the `AppVersion`
|
||||
from the ABCI application.
|
||||
|
||||
Once the node is bootstrapped with this information and the restored state machine, it transitions
|
||||
|
||||
Reference in New Issue
Block a user