[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

@@ -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

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.
+