From a57aae7072ac1ed97f4b782b08fc262e8f1d30af Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 9 Sep 2018 14:04:01 -0400 Subject: [PATCH] [ADR] ABCI errors and events (#2314) * Start of ADR * flesh out abci events and errors adrs * adr: move 012 to 023 * adr-022: add note from cwgoes --- docs/architecture/adr-021-abci-events.md | 47 ++++++++++++++ docs/architecture/adr-022-abci-errors.md | 64 +++++++++++++++++++ ...opose-tx.md => adr-023-ABCI-propose-tx.md} | 0 3 files changed, 111 insertions(+) create mode 100644 docs/architecture/adr-021-abci-events.md create mode 100644 docs/architecture/adr-022-abci-errors.md rename docs/architecture/{adr-012-ABCI-propose-tx.md => adr-023-ABCI-propose-tx.md} (100%) diff --git a/docs/architecture/adr-021-abci-events.md b/docs/architecture/adr-021-abci-events.md new file mode 100644 index 000000000..7d60d45a0 --- /dev/null +++ b/docs/architecture/adr-021-abci-events.md @@ -0,0 +1,47 @@ +# ADR 012: ABCI Events + +## Changelog + +- *2018-09-02* Remove ABCI errors component. Update description for events +- *2018-07-12* Initial version + +## Context + +ABCI tags were first described in [ADR 002](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-002-event-subscription.md). +They are key-value pairs that can be used to index transactions. + +Currently, ABCI messages return a list of tags to describe an +"event" that took place during the Check/DeliverTx/Begin/EndBlock, +where each tag refers to a different property of the event, like the sending and receiving account addresses. + +Since there is only one list of tags, recording data for multiple such events in +a single Check/DeliverTx/Begin/EndBlock must be done using prefixes in the key +space. + +TODO: brief description of how the indexing works + +## Decision + +Instead of returning a list of tags, return a list of events, where +each event is a list of tags. This way we naturally capture the concept of +multiple events happening during a single ABCI message. + +TODO: describe impact on indexing and querying + +## Status + +Proposed + +## Consequences + +### Positive + +- Ability to track distinct events separate from ABCI calls (DeliverTx/BeginBlock/EndBlock) +- More powerful query abilities + +### Negative + +- More complex query syntax +- More complex search implementation + +### Neutral diff --git a/docs/architecture/adr-022-abci-errors.md b/docs/architecture/adr-022-abci-errors.md new file mode 100644 index 000000000..23e917f47 --- /dev/null +++ b/docs/architecture/adr-022-abci-errors.md @@ -0,0 +1,64 @@ +# ADR 023: ABCI Codespaces + +## Changelog + +- *2018-09-01* Initial version + +## Context + +ABCI errors should provide an abstraction between application details +and the client interface responsible for formatting & displaying errors to the user. + +Currently, this abstraction consists of a single integer (the `code`), where any +`code > 0` is considered an error (ie. invalid transaction) and all type +information about the error is contained in the code. This integer is +expected to be decoded by the client into a known error string, where any +more specific data is contained in the `data`. + +In a [previous conversation](https://github.com/tendermint/abci/issues/165#issuecomment-353704015), +it was suggested that not all non-zero codes need to be errors, hence why it's called `code` and not `error code`. +It is unclear exactly how the semantics of the `code` field will evolve, though +better lite-client proofs (like discussed for tags +[here](https://github.com/tendermint/tendermint/issues/1007#issuecomment-413917763)) +may play a role. + +Note that having all type information in a single integer +precludes an easy coordination method between "module implementers" and "client +implementers", especially for apps with many "modules". With an unbounded error domain (such as a string), module +implementers can pick a globally unique prefix & error code set, so client +implementers could easily implement support for "module A" regardless of which +particular blockchain network it was running in and which other modules were running with it. With +only error codes, globally unique codes are difficult/impossible, as the space +is finite and collisions are likely without an easy way to coordinate. + +For instance, while trying to build an ecosystem of modules that can be composed into a single +ABCI application, the Cosmos-SDK had to hack a higher level "codespace" into the +single integer so that each module could have its own space to express its +errors. + +## Decision + +Include a `string code_space` in all ABCI messages that have a `code`. +This allows applications to namespace the codes so they can experiment with +their own code schemes. + +It is the responsibility of applications to limit the size of the `code_space` +string. + +How the codespace is hashed into block headers (ie. so it can be queried +efficiently by lite clients) is left for a separate ADR. + +## Consequences + +## Positive + +- No need for complex codespacing on a single integer +- More expressive type system for errors + +## Negative + +- Another field in the response needs to be accounted for +- Some redundancy with `code` field +- May encourage more error/code type info to move to the `codespace` string, which + could impact lite clients. + diff --git a/docs/architecture/adr-012-ABCI-propose-tx.md b/docs/architecture/adr-023-ABCI-propose-tx.md similarity index 100% rename from docs/architecture/adr-012-ABCI-propose-tx.md rename to docs/architecture/adr-023-ABCI-propose-tx.md