From 6a80c7952401228a051becce283c0b966ca32bf0 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 13 Dec 2023 07:52:27 +0100 Subject: [PATCH] docs: add ante precision (#18709) (cherry picked from commit 49825ea40c609b3484c5cfd521848323516d5e74) # Conflicts: # x/circuit/README.md --- docs/docs/learn/beginner/01-tx-lifecycle.md | 4 ++++ x/circuit/README.md | 22 +++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/docs/docs/learn/beginner/01-tx-lifecycle.md b/docs/docs/learn/beginner/01-tx-lifecycle.md index e3831ae3b45c..1fddabddad48 100644 --- a/docs/docs/learn/beginner/01-tx-lifecycle.md +++ b/docs/docs/learn/beginner/01-tx-lifecycle.md @@ -112,6 +112,10 @@ A copy of the cached context is provided to the `AnteHandler`, which performs li For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module `AnteHandler` checks and increments sequence numbers, checks signatures and account numbers, and deducts fees from the first signer of the transaction - all state changes are made using the `checkState`. +:::warning +Ante handlers only run on a transaction. If a transaction embed multiple messages (like some x/authz, x/gov transactions for instance), the ante handlers only have awareness of the outer message. Inner messages are mostly directly routed to the [message router](https://docs.cosmos.network/main/learn/advanced/baseapp#msg-service-router) and will skip the chain of ante handlers. Keep that in mind when designing your own ante handler. +::: + ### Gas The [`Context`](../advanced/02-context.md), which keeps a `GasMeter` that tracks how much gas is used during the execution of `Tx`, is initialized. The user-provided amount of gas for `Tx` is known as `GasWanted`. If `GasConsumed`, the amount of gas consumed during execution, ever exceeds `GasWanted`, the execution stops and the changes made to the cached copy of the state are not committed. Otherwise, `CheckTx` sets `GasUsed` equal to `GasConsumed` and returns it in the result. After calculating the gas and fee values, validator-nodes check that the user-specified `gas-prices` is greater than their locally defined `min-gas-prices`. diff --git a/x/circuit/README.md b/x/circuit/README.md index 7386680e3ef3..2dea94c02b54 100644 --- a/x/circuit/README.md +++ b/x/circuit/README.md @@ -6,6 +6,28 @@ Circuit Breaker is a module that is meant to avoid a chain needing to halt/shut Circuit Breaker works with the idea that an address or set of addresses have the right to block messages from being executed and/or included in the mempool. Any address with a permission is able to reset the circuit breaker for the message. +<<<<<<< HEAD +======= +The transactions are checked and can be rejected at two points: + +* In `CircuitBreakerDecorator` [ante handler](https://docs.cosmos.network/main/learn/advanced/baseapp#antehandler): + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/x/circuit/v0.1.0/x/circuit/ante/circuit.go#L27-L41 +``` + +* With a [message router check](https://docs.cosmos.network/main/learn/advanced/baseapp#msg-service-router): + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/baseapp/msg_service_router.go#L104-L115 +``` + +:::note +The `CircuitBreakerDecorator` works for most use cases, but [does not check the inner messages of a transaction](https://docs.cosmos.network/main/learn/beginner/tx-lifecycle#antehandler). This some transactions (such as `x/authz` transactions or some `x/gov` transactions) may pass the ante handler. **This does not affect the circuit breaker** as the message router check will still fail the transaction. +This tradeoff is to avoid introducing more dependencies in the `x/circuit` module. Chains can re-define the `CircuitBreakerDecorator` to check for inner messages if they wish to do so. +::: + +>>>>>>> 49825ea40 (docs: add ante precision (#18709)) ## State ### Accounts