github.com/badrootd/nibiru-cometbft@v0.37.5-0.20240307173500-2a75559eee9b/docs/architecture/adr-022-abci-errors.md (about)

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