Browse Source

update CHANGELOG, README, spec for v0.10. Fixes #205

pull/1780/head
Ethan Buchman 7 years ago
parent
commit
fb808a00d5
3 changed files with 84 additions and 45 deletions
  1. +10
    -5
      CHANGELOG.md
  2. +6
    -3
      README.md
  3. +68
    -37
      specification.rst

+ 10
- 5
CHANGELOG.md View File

@ -4,15 +4,20 @@
BREAKING CHANGES:
- [types] Socket messages are length prefixed with real protobuf Varint instead of `<len of len><big endian len>`
- [types] Drop gogo custom type magic with data.Bytes
- [types] Add `info string` field to responses for SetOption, Query, CheckTx, DeliverTx
- [types] Remove IsOk/IsErr methods from response types.
- [types] Replace KVPair with common.KVPair
- [types] Updates to CheckTx/DeliverTx around tags and fees
- [types] Remove code and log from Commit
- [types] Use `[(gogoproto.nullable)=false]` to prefer value over pointer for the types
- [types] Field re-ordering ...
- [types] KVPair: replace with common.KVPair. Add common KI64Pair too (for fees).
- [types] CheckTx/DeliverTx: updates for tags, gas, fees
- [types] Commit: Remove code and log from Commit
- [types] SetOption: Remove code
- [example/dummy] remove dependence on IAVL
- [types] IsOk/IsErr: methods removed
FEATURES:
- [types] SetOption/Query/CheckTx/DeliverTx: Add `info string` field to responses
- [types] RequestInitChain.AppStateBytes for app's genesis state
IMPROVEMENTS:


+ 6
- 3
README.md View File

@ -64,10 +64,13 @@ See the [examples](#examples) below for more information.
ABCI is best implemented as a streaming protocol.
The socket implementation provides for asynchronous, ordered message passing over unix or tcp.
Messages are serialized using Protobuf3 and length-prefixed.
Protobuf3 doesn't have an official length-prefix standard, so we use our own. The first byte represents the length of the big-endian encoded length.
Messages are serialized using Protobuf3 and length-prefixed with a [signed Varint](https://developers.google.com/protocol-buffers/docs/encoding?csw=1#signed-integers)
For example, if the Protobuf3 encoded ABCI message is `0xDEADBEEF` (4 bytes), the length-prefixed message is `0x0104DEADBEEF`. If the Protobuf3 encoded ABCI message is 65535 bytes long, the length-prefixed message would be like `0x02FFFF...`.
For example, if the Protobuf3 encoded ABCI message is `0xDEADBEEF` (4 bytes), the length-prefixed message is `0x08DEADBEEF`, since `0x08` is the signed varint
encoding of `4`. If the Protobuf3 encoded ABCI message is 65535 bytes long, the length-prefixed message would be like `0xFEFF07...`.
Note the benefit of using this `varint` encoding over the old version (where integers were encoded as `<len of len><big endian len>` is that
it is the standard way to encode integers in Protobuf. It is also generally shorter.
### GRPC


+ 68
- 37
specification.rst View File

@ -40,6 +40,10 @@ Flush
Info
^^^^
- **Arguments**:
- ``Version (string)``: The Tendermint version
- **Returns**:
- ``Data (string)``: Some arbitrary information
@ -48,8 +52,10 @@ Info
called Commit
- ``LastBlockAppHash ([]byte)``: Latest result of Commit
- **Usage**: Return information about the application state. Used to
sync the app with Tendermint on crash/restart.
- **Usage**:
- Return information about the application state.
- Used to sync the app with Tendermint on crash/restart.
SetOption
^^^^^^^^^
@ -62,11 +68,14 @@ SetOption
- **Returns**:
- ``Code (uint32)``: Response code
- ``Log (string)``: Debug or error message
- ``Log (string)``: The output of the application's logger. May be non-deterministic.
- ``Info (string)``: Additional information. May be non-deterministic.
- **Usage**: Set application options. E.g. Key="mode", Value="mempool"
for a mempool connection, or Key="mode", Value="consensus" for a
consensus connection. Other options are application specific.
- **Usage**:
- 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
^^^^^^^^^
@ -76,7 +85,9 @@ InitChain
- ``Validators ([]Validator)``: Initial genesis validators
- ``AppStateBytes ([]byte)``: Serialized initial application state
- **Usage**: Called once upon genesis
- **Usage**:
- Called once upon genesis
Query
^^^^^
@ -100,15 +111,22 @@ Query
- **Returns**:
- ``Code (uint32)``: Response code
- ``Key ([]byte)``: The key of the matching data
- ``Value ([]byte)``: The value of the matching data
- ``Proof ([]byte)``: Proof for the data, if requested
- ``Code (uint32)``: Response code.
- ``Log (string)``: The output of the application's logger. May be non-deterministic.
- ``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 ([]byte)``: Proof for the data, if requested.
- ``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
- ``Log (string)``: Debug or error message
- **Usage**:
- Query for data from the application at current or past height.
- Optionally return Merkle proof.
BeginBlock
^^^^^^^^^^
@ -123,25 +141,29 @@ BeginBlock
- ``ByzantineValidators ([]Evidence)``: List of evidence of
validators that acted maliciously
- **Usage**: Signals the beginning of a new block. Called prior to any
DeliverTxs. The header is expected to at least contain the Height.
The ``AbsentValidators`` and ``ByzantineValidators`` can be used to
determine rewards and punishments for the validators.
- **Usage**:
- Signals the beginning of a new block. Called prior to any DeliverTxs.
- The header is expected to at least contain the Height.
- The ``AbsentValidators`` and ``ByzantineValidators`` can be used to
determine rewards and punishments for the validators.
CheckTx
^^^^^^^
- **Arguments**:
- ``Data ([]byte)``: The request transaction bytes
- ``Tx ([]byte)``: The request transaction bytes
- **Returns**:
- ``Code (uint32)``: Response code
- ``Data ([]byte)``: Result bytes, if any
- ``Log (string)``: Debug or error message
- ``Gas (int64)``: Amount of gas consumed by transaction
- ``Fee (int64)``: Fee paid by transaction
- ``Data ([]byte)``: Result bytes, if any.
- ``Log (string)``: The output of the application's logger. May be non-deterministic.
- ``Info (string)``: Additional information. May be non-deterministic.
- ``GasWanted (int64)``: Amount of gas consumed by transaction.
- ``Tags ([]cmn.KVPair)``: Key-Value tags for filtering and indexing transactions (eg. by account).
- ``Fee ([]cmn.KI64Pair)``: Fee paid for the transaction.
- **Usage**: Validate a mempool transaction, prior to broadcasting or
proposing. This message should not mutate the main state, but
@ -157,42 +179,49 @@ CheckTx
Transactions are first run through CheckTx before broadcast to peers
in the mempool layer. You can make CheckTx semi-stateful and clear
the state upon ``Commit`` or ``BeginBlock``, to allow for dependent
sequences of transactions in the same block.
the state upon ``Commit``, to allow for dependent sequences of transactions
in the same block.
DeliverTx
^^^^^^^^^
- **Arguments**:
- ``Data ([]byte)``: The request transaction bytes
- ``Tx ([]byte)``: The request transaction bytes.
- **Returns**:
- ``Code (uint32)``: Response code
- ``Data ([]byte)``: Result bytes, if any
- ``Log (string)``: Debug or error message
- ``Tags ([]*KVPair)``: Optional tags for indexing
- ``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 be non-deterministic.
- ``GasWanted (int64)``: Amount of gas predicted to be consumed by transaction.
- ``GasUsed (int64)``: Amount of gas consumed by transaction.
- ``Tags ([]cmn.KVPair)``: Key-Value tags for filtering and indexing transactions (eg. by account).
- **Usage**: Append and run a transaction. If the transaction is valid,
returns CodeType.OK
- **Usage**:
- Deliver a transaction to be executed in full by the application. If the transaction is valid,
returns CodeType.OK.
EndBlock
^^^^^^^^
- **Arguments**:
- ``Height (int64)``: The block height that ended
- ``Height (int64)``: Height of the block just executed.
- **Returns**:
- ``ValidatorUpdates ([]Validator)``: Changes to validator set (set
voting power to 0 to remove)
voting power to 0 to remove).
- ``ConsensusParamUpdates (ConsensusParams)``: Changes to
consensus-critical time/size parameters
consensus-critical time, size, and other parameters.
- **Usage**:
- **Usage**: Signals the end of a block. Called prior to each Commit
after all transactions. Validator set is updated with the result.
- Signals the end of a block.
- Called prior to each Commit, after all transactions.
- Validator set and consensus params are updated with the result.
Commit
^^^^^^
@ -200,6 +229,8 @@ Commit
- **Returns**:
- ``Data ([]byte)``: The Merkle root hash
- ``Log (string)``: Debug or error message
- **Usage**: Return a Merkle root hash of the application state.
- **Usage**:
- Persist the application state.
- Return a Merkle root hash of the application state.

Loading…
Cancel
Save