From 8c65b79d2af42c7fb40c8166aa82511f1d9fa771 Mon Sep 17 00:00:00 2001 From: Jeancarlo Barrios Date: Sun, 3 Apr 2022 03:17:37 -0600 Subject: [PATCH] docs: added middleware documentation (#9954) (#11445) ## Description Closes: #9954 --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [x] added `!` to the type prefix if API or client breaking change - [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [ ] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [ ] reviewed "Files changed" and left comments if necessary - [ ] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable) --- docs/core/baseapp_transaction-middleware.png | Bin 0 -> 14266 bytes docs/core/cli.md | 2 +- docs/core/encoding.md | 2 +- docs/core/events.md | 2 +- docs/core/grpc_rest.md | 2 +- docs/core/middleware.md | 160 +++++++++++++++++++ docs/core/node.md | 2 +- docs/core/ocap.md | 2 +- docs/core/proto-docs.md | 2 +- docs/core/runtx_middleware.md | 2 +- docs/core/simulation.md | 2 +- docs/core/store.md | 2 +- docs/core/telemetry.md | 2 +- 13 files changed, 171 insertions(+), 11 deletions(-) create mode 100644 docs/core/baseapp_transaction-middleware.png create mode 100644 docs/core/middleware.md diff --git a/docs/core/baseapp_transaction-middleware.png b/docs/core/baseapp_transaction-middleware.png new file mode 100644 index 0000000000000000000000000000000000000000..76db2a6b1475d067b679a8ed05048db31fc76d51 GIT binary patch literal 14266 zcmd6Oc~n!^`u1TGK?Ms192le(X&EhufQ&*_1OY_`83QWwkVpt&3Pe4N&slQ)l4cibtl`K9DXiC<)-Y+nB%Oto)6qIu~m�?i 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 # Command-Line Interface diff --git a/docs/core/encoding.md b/docs/core/encoding.md index 2d08f05f8..9e71968c2 100644 --- a/docs/core/encoding.md +++ b/docs/core/encoding.md @@ -1,5 +1,5 @@ # Encoding diff --git a/docs/core/events.md b/docs/core/events.md index 616f9c654..62362a6de 100644 --- a/docs/core/events.md +++ b/docs/core/events.md @@ -1,5 +1,5 @@ # Events diff --git a/docs/core/grpc_rest.md b/docs/core/grpc_rest.md index c52327be1..5052f64cf 100644 --- a/docs/core/grpc_rest.md +++ b/docs/core/grpc_rest.md @@ -1,5 +1,5 @@ # gRPC, REST, and Tendermint Endpoints diff --git a/docs/core/middleware.md b/docs/core/middleware.md new file mode 100644 index 000000000..f86cff112 --- /dev/null +++ b/docs/core/middleware.md @@ -0,0 +1,160 @@ + + +# Middlewares + + +`Middlewares` are objects that the developer can create to add logic before or after the transaction handler in a composable manner. +{synopsis} + +## Pre-requisite Readings + +* [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq} +* [Transactons](transactions.md){prereq} + + +## Middlewares + +The SDK Baseapp's implementation of ABCI CheckTx, DeliverTx, and Baseapp's own Simulate methods use a middleware-based design. Middlewares can add logic to be executed before or after a transaction handler execution. Middlewares are like an `antehandler` with the added feature of being able to add post-transaction handler execution. Middlewares allow us to solve use cases like transaction Tips and refund unused gas (issue [#2150](https://github.com/cosmos/cosmos-sdk/issues/2150)). + + +### Type Definition + +The two following interfaces are the base of the middleware design, and are defined in types/tx: + ++++ https://github.com/cosmos/cosmos-sdk/blob/5491be27d02e796746bd78d3d08bd1b2a9b1deb2/types/tx/middleware.go#L62-L71 + +Where we define the following arguments and return types: + ++++ https://github.com/cosmos/cosmos-sdk/blob/5491be27d02e796746bd78d3d08bd1b2a9b1deb2/types/tx/middleware.go#L25-L60 + +BaseApp holds a reference to a `tx.Handler`, which will process the incoming transactions. It could be a simple `sdk.Msg` executor, but in practice, it will be defined as a middleware stack wrapping around the base `sdk.Msg` executor. + +```go +type BaseApp struct { + // other fields + txHandler tx.Handler +} +``` + + +## Implementing a Middleware + +To implement a middleware is done simply by a Go function that takes as arguments and some parameters and returns a `tx.Middleware`. + +For example, we can create a Generic middleware. + +```go +// myTxHandler is the tx.Handler of this middleware. Note that it holds a +// reference to the next tx.Handler in the stack. +type myTxHandler struct { + // next is the next tx.Handler in the middleware stack. + next tx.Handler + // some other fields that are relevant to the middleware can be added here +} + +// NewMyMiddleware returns a middleware that does this and that. +func NewMyMiddleware(arg1, arg2) tx.Middleware { + return func (txh tx.Handler) tx.Handler { + return myTxHandler{ + next: txh, + // optionally, set arg1, arg2... if they are needed in the middleware + } + } +} + +// Assert myTxHandler is a tx.Handler. +var _ tx.Handler = myTxHandler{} +``` + +Next we need to implement the middleware [interface](#Type-Definition). + +```go +func (h myTxHandler) CheckTx(ctx context.Context, req Request, checkReq RequestcheckTx) (Response, ResponseCheckTx, error) { + // CheckTx specific pre-processing logic + + // run the next middleware + res, checkRes, err := txh.next.CheckTx(ctx, req, checkReq) + + // CheckTx specific post-processing logic + + return res, checkRes, err +} + +func (h myTxHandler) DeliverTx(ctx context.Context, req Request) (Response, error) { + // DeliverTx specific pre-processing logic + + // run the next middleware + res, err := txh.next.DeliverTx(ctx, tx, req) + + // DeliverTx specific post-processing logic + + return res, err +} + +func (h myTxHandler) SimulateTx(ctx context.Context, req Request) (Response, error) { + // SimulateTx specific pre-processing logic + + // run the next middleware + res, err := txh.next.SimulateTx(ctx, tx, req) + + // SimulateTx specific post-processing logic + + return res, err +} +``` + +### Composing Middlewares + +While BaseApp holds a reference to a `tx.Handler`, this `tx.Handler` itself is defined using a middleware stack. The Cosmos SDK exposes a base (i.e. innermost) `tx.Handler` called `RunMsgsTxHandler`, which executes messages. It holds a reference to the `MsgServiceRouter`, which is used to map each `sdk.Msg` to the correct module's `Msg` server handler. + +Then, the app developer can compose multiple middlewares on top of the base `tx.Handler`. Each middleware can run pre-and-post-processing logic around its next middleware, as described in the section above. Conceptually, as an example, given the middlewares `A`, `B`, and `C` and the base `tx.Handler` `H` the stack looks like: + +![Composing](baseapp_transaction-middleware.png) + +```text +A.pre + B.pre + C.pre + Handler # The base tx.handler, for example `RunMsgsTxHandler` + C.post + B.post +A.post +``` + +We define a `ComposeMiddlewares` function for composing middlewares. It takes the base handler as first argument, and middlewares in the "outer to inner" order. For the above stack, the final `tx.Handler` is: + +```go +txHandler := middleware.ComposeMiddlewares(H, A, B, C) +``` + +The middleware is set in BaseApp via its `SetTxHandler` setter: + +```go +// simapp/app.go + +txHandler := middleware.ComposeMiddlewares(...) +app.SetTxHandler(txHandler) +``` + +The app developer can define their own middlewares, or use the Cosmos SDK's pre-defined middlewares from `middleware.NewDefaultTxHandler()`. + +### Middlewares Maintained by the Cosmos SDK + +While the app developer can define and compose the middlewares of their choice, the Cosmos SDK provides a set of middlewares that caters to the ecosystem's most common use cases. These middlewares are: + +| Middleware | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| RunMsgsTxHandler | This is the base `tx.Handler`. It replaces the old baseapp's `runMsgs`, and executes a transaction's `Msg`s. | +| TxDecoderMiddleware | This middleware takes in transaction raw bytes, and decodes them into a `sdk.Tx`. It replaces the `baseapp.txDecoder` field, so that BaseApp stays as thin as possible. Since most middlewares read the contents of the `sdk.Tx`, the TxDecoderMiddleware should be run first in the middelware stack. | +| {Antehandlers} | Each antehandler is converted to its own middleware. These middlewares perform signature verification, fee deductions and other validations on the incoming transaction. | +| IndexEventsTxMiddleware | This is a simple middleware that chooses which events to index in Tendermint. Replaces `baseapp.indexEvents` (which unfortunately still exists in baseapp too, because it's used to index Begin/EndBlock events) | +| RecoveryTxMiddleware | This index recovers from panics. It replaces baseapp.runTx's panic recovery described in [ADR-022](./adr-022-custom-panic-handling.md). | +| GasTxMiddleware | This replaces the [`Setup`](https://github.com/cosmos/cosmos-sdk/blob/v0.43.0/x/auth/ante/setup.go) Antehandler. It sets a GasMeter on sdk.Context. Note that before, GasMeter was set on sdk.Context inside the antehandlers, and there was some mess around the fact that antehandlers had their own panic recovery system so that the GasMeter could be read by baseapp's recovery system. Now, this mess is all removed: one middleware sets GasMeter, another one handles recovery. +| TipMiddleware | This pays for transaction fees using another denom than the native fee denom of the chain. [`docs`](tips.md) +| SigGasConsumeMiddleware | SigGasConsumeMiddleware consumes parameter-defined amount of gas for each signature. +| SigVerificationMiddleware | verifies all signatures for a tx and return an error if any are invalid + + + diff --git a/docs/core/node.md b/docs/core/node.md index 3c61291cf..a4693643e 100644 --- a/docs/core/node.md +++ b/docs/core/node.md @@ -1,5 +1,5 @@ # Node Client (Daemon) diff --git a/docs/core/ocap.md b/docs/core/ocap.md index a365fd106..dd3d40d7e 100644 --- a/docs/core/ocap.md +++ b/docs/core/ocap.md @@ -1,5 +1,5 @@ # Object-Capability Model diff --git a/docs/core/proto-docs.md b/docs/core/proto-docs.md index b8cc6f6d9..ba2a6f37c 100644 --- a/docs/core/proto-docs.md +++ b/docs/core/proto-docs.md @@ -1,5 +1,5 @@ # Protobuf Documentation diff --git a/docs/core/runtx_middleware.md b/docs/core/runtx_middleware.md index f5fba2079..32f7bb1ce 100644 --- a/docs/core/runtx_middleware.md +++ b/docs/core/runtx_middleware.md @@ -1,5 +1,5 @@ # RunTx recovery middleware diff --git a/docs/core/simulation.md b/docs/core/simulation.md index 586cc1ed5..68503d8af 100644 --- a/docs/core/simulation.md +++ b/docs/core/simulation.md @@ -1,5 +1,5 @@ # Cosmos Blockchain Simulator diff --git a/docs/core/store.md b/docs/core/store.md index e7ff13e68..3a0781562 100644 --- a/docs/core/store.md +++ b/docs/core/store.md @@ -1,5 +1,5 @@ # Store diff --git a/docs/core/telemetry.md b/docs/core/telemetry.md index d34ad51ec..3c312c7fa 100644 --- a/docs/core/telemetry.md +++ b/docs/core/telemetry.md @@ -1,5 +1,5 @@ # Telemetry