Circuit
Concepts
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.
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:
With a message router check:
:::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
AccountPermissions
0x1 | account_address -> ProtocolBuffer(CircuitBreakerPermissions)
Disable List
List of type urls that are disabled.
DisableList
0x2 | msg_type_url -> []byte{}
State Transitions
Authorize
Authorize, is called by the module authority (default governance module account) or any account with LEVEL_SUPER_ADMIN
to give permission to disable/enable messages to another account. There are three levels of permissions that can be granted. LEVEL_SOME_MSGS
limits the number of messages that can be disabled. LEVEL_ALL_MSGS
permits all messages to be disabled. LEVEL_SUPER_ADMIN
allows an account to take all circuit breaker actions including authorizing and deauthorizing other accounts.
Trip
Trip, is called by an authorized account to disable message execution for a specific msgURL. If empty, all the msgs will be disabled.
Reset
Reset is called by an authorized account to enable execution for a specific msgURL of previously disabled message. If empty, all the disabled messages will be enabled.
Messages
MsgAuthorizeCircuitBreaker
This message is expected to fail if:
the granter is not an account with permission level
LEVEL_SUPER_ADMIN
or the module authority
MsgTripCircuitBreaker
This message is expected to fail if:
if the signer does not have a permission level with the ability to disable the specified type url message
MsgResetCircuitBreaker
This message is expected to fail if:
if the type url is not disabled
Events - list and describe event tags
The circuit module emits the following events:
Message Events
MsgAuthorizeCircuitBreaker
MsgTripCircuitBreaker
ResetCircuitBreaker
Keys - list of key prefixes used by the circuit module
AccountPermissionPrefix
-0x01
DisableListPrefix
-0x02
Client - list and describe CLI commands and gRPC and REST endpoints
Last updated