diff --git a/docs/building-modules/README.md b/docs/building-modules/README.md index f23a129e7b..15a2f0c464 100644 --- a/docs/building-modules/README.md +++ b/docs/building-modules/README.md @@ -19,3 +19,4 @@ This repository contains documentation on concepts developers need to know in or 9. [Genesis](./genesis.md) 10. [Module Interfaces](./module-interfaces.md) 11. [Standard Module Structure](./structure.md) +12. [Errors](./errors.md) diff --git a/docs/building-modules/errors.md b/docs/building-modules/errors.md new file mode 100644 index 0000000000..426a9d6d91 --- /dev/null +++ b/docs/building-modules/errors.md @@ -0,0 +1,53 @@ + + +# Errors + +Modules are encouraged to define and register their own errors to provide better +context on failed message or handler execution. Typically, these errors should be +common or general errors which can be further wrapped to provide additional specific +execution context. + +## Registration + +Modules should define and register their custom errors in `x/{module}/types/errors.go`. Registration +of errors is handled via the `types/errors` package. + +Example: + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.38.1/x/distribution/types/errors.go#L1-L21 + +Each custom module error must provide the codespace, which is typically the module name +(e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code +provide a globally unique SDK error. Typically, the code is monotonically increasing but does not +necessarily have to be. The only restrictions on error codes are the following: + +* Must be greater than one, as a code value of one is reserved for internal errors. +* Must be unique within the module. + +Note, the SDK provides a core set of *common* errors. These errors are defined in `types/errors/errors.go`. + +## Wrapping + +The custom module errors can be returned as their concrete type as they already fulfill the `error` +interface. However, module errors can be wrapped to provide further context and meaning to failed +execution. + +Example: + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.38.1/x/distribution/keeper/querier.go#L62-L80 + +Regardless if an error is wrapped or not, the SDK's `errors` package provides an API to determine if +an error is of a particular kind via `Is`. + +## ABCI + +If a module error is registered, the SDK `errors` package allows ABCI information to be extracted +through the `ABCIInfo` API. The package also provides `ResponseCheckTx` and `ResponseDeliverTx` as +auxiliary APIs to automatically get `CheckTx` and `DeliverTx` responses from an error. + +## Next {hide} + +Learn about [interfaces](../interfaces/interfaces-intro.md) {hide} diff --git a/docs/building-modules/structure.md b/docs/building-modules/structure.md index 47d9a82b19..bb20c9945e 100644 --- a/docs/building-modules/structure.md +++ b/docs/building-modules/structure.md @@ -85,9 +85,9 @@ allows for greater freedom of development while maintaining API stability. - `module.go`: The module's implementation of the `AppModule` and `AppModuleBasic` interfaces. - `simulation/`: The module's simulation package defines all the required functions -used on the blockchain simulator: randomized genesis state, parameters, weigthed +used on the blockchain simulator: randomized genesis state, parameters, weighted operations, proposal contents and types decoders. ## Next {hide} -Learn about [interfaces](../interfaces/interfaces-intro.md) {hide} +Learn about [Errors](./errors.md) {hide}