LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs(x/circuit): add note on ante handler (#18637)

Browse Source 
Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com>
This commit is contained in:
Julien Robert 2023-12-06 18:28:48 +01:00 committed by GitHub
parent 0b26c89956
commit 0b907e8c54
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 56 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
x/circuit/README.md
View File

@ -4,8 +4,29 @@
Circuit Breaker is a module that is meant to avoid a chain needing to halt/shut down in the presence of a vulnerability, instead the module will allow specific messages or all messages to be disabled. When operating a chain, if it is app specific then a halt of the chain is less detrimental, but if there are applications built on top of the chain then halting is expensive due to the disturbance to applications.
## How it works
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.
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. 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.
:::
## State
### Accounts
@ -38,7 +59,6 @@ type Access struct {
}
```
### Disable List
List of type urls that are disabled.
@ -108,7 +128,7 @@ This message is expected to fail if:
* if the type url is not disabled
## Events - list and describe event tags
## Events
The circuit module emits the following events:
@ -143,9 +163,41 @@ The circuit module emits the following events:
| message | action | reset_circuit_breaker |
## Keys - list of key prefixes used by the circuit module
## Keys
* `AccountPermissionPrefix` - `0x01`
* `DisableListPrefix` - `0x02`
## Client - list and describe CLI commands and gRPC and REST endpoints
## Client
### CLI
`x/circuit` module client provides the following CLI commands:
```shell
$ <appd> tx circuit
Transactions commands for the circuit module
Usage:
simd tx circuit [flags]
simd tx circuit [command]
Available Commands:
authorize Authorize an account to trip the circuit breaker.
disable Disable a message from being executed
reset Enable a message to be executed
```
```shell
$ <appd> query circuit
Querying commands for the circuit module
Usage:
simd query circuit [flags]
simd query circuit [command]
Available Commands:
account Query a specific account's permissions
accounts Query all account permissions
disabled-list Query a list of all disabled message types
```