You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

64 lines
2.6 KiB

  1. # ADR 023: ABCI Codespaces
  2. ## Changelog
  3. - *2018-09-01* Initial version
  4. ## Context
  5. ABCI errors should provide an abstraction between application details
  6. and the client interface responsible for formatting & displaying errors to the user.
  7. Currently, this abstraction consists of a single integer (the `code`), where any
  8. `code > 0` is considered an error (ie. invalid transaction) and all type
  9. information about the error is contained in the code. This integer is
  10. expected to be decoded by the client into a known error string, where any
  11. more specific data is contained in the `data`.
  12. In a [previous conversation](https://github.com/tendermint/abci/issues/165#issuecomment-353704015),
  13. it was suggested that not all non-zero codes need to be errors, hence why it's called `code` and not `error code`.
  14. It is unclear exactly how the semantics of the `code` field will evolve, though
  15. better lite-client proofs (like discussed for tags
  16. [here](https://github.com/tendermint/tendermint/issues/1007#issuecomment-413917763))
  17. may play a role.
  18. Note that having all type information in a single integer
  19. precludes an easy coordination method between "module implementers" and "client
  20. implementers", especially for apps with many "modules". With an unbounded error domain (such as a string), module
  21. implementers can pick a globally unique prefix & error code set, so client
  22. implementers could easily implement support for "module A" regardless of which
  23. particular blockchain network it was running in and which other modules were running with it. With
  24. only error codes, globally unique codes are difficult/impossible, as the space
  25. is finite and collisions are likely without an easy way to coordinate.
  26. For instance, while trying to build an ecosystem of modules that can be composed into a single
  27. ABCI application, the Cosmos-SDK had to hack a higher level "codespace" into the
  28. single integer so that each module could have its own space to express its
  29. errors.
  30. ## Decision
  31. Include a `string code_space` in all ABCI messages that have a `code`.
  32. This allows applications to namespace the codes so they can experiment with
  33. their own code schemes.
  34. It is the responsibility of applications to limit the size of the `code_space`
  35. string.
  36. How the codespace is hashed into block headers (ie. so it can be queried
  37. efficiently by lite clients) is left for a separate ADR.
  38. ## Consequences
  39. ## Positive
  40. - No need for complex codespacing on a single integer
  41. - More expressive type system for errors
  42. ## Negative
  43. - Another field in the response needs to be accounted for
  44. - Some redundancy with `code` field
  45. - May encourage more error/code type info to move to the `codespace` string, which
  46. could impact lite clients.