Circuit

概念

Circuit Breaker 是一个模块，旨在避免在存在漏洞时链需要停运/关闭，相反，该模块将允许禁用特定消息或所有消息。当运营链时，如果是应用特定的，那么链的停止影响较小，但如果链上有构建的应用程序，则停止链会由于对应用程序的干扰而变得非常昂贵。

Circuit Breaker 的工作原理是，某个地址或一组地址有权阻止消息的执行和/或包含在交易池中。任何具有权限的地址都能够重置该消息的断路器。

交易在两个阶段进行检查，并可能被拒绝：

• 在 CircuitBreakerDecorator 前置处理器中：

https://github.com/cosmos/cosmos-sdk/blob/x/circuit/v0.1.0/x/circuit/ante/circuit.go#L27-L41

• 通过消息路由器检查：

https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/baseapp/msg_service_router.go#L104-L115

:::note CircuitBreakerDecorator 适用于大多数用例，但不检查交易的内部消息。因此，一些交易（例如 x/authz 交易或某些 x/gov 交易）可能会通过前置处理器。这不会影响断路器，因为消息路由器的检查仍然会导致交易失败。这个折衷是为了避免在 x/circuit 模块中引入更多依赖。如果链希望这样做，可以重新定义 CircuitBreakerDecorator 以检查内部消息。 :::

状态

Accounts

• AccountPermissions 0x1 | account_address -> ProtocolBuffer(CircuitBreakerPermissions)

type level int32

const (
    // LEVEL_NONE_UNSPECIFIED indicates that the account will have no circuit
    // breaker permissions.
    LEVEL_NONE_UNSPECIFIED = iota
    // LEVEL_SOME_MSGS indicates that the account will have permission to
    // trip or reset the circuit breaker for some Msg type URLs. If this level
    // is chosen, a non-empty list of Msg type URLs must be provided in
    // limit_type_urls.
    LEVEL_SOME_MSGS
    // LEVEL_ALL_MSGS indicates that the account can trip or reset the circuit
    // breaker for Msg's of all type URLs.
    LEVEL_ALL_MSGS 
    // LEVEL_SUPER_ADMIN indicates that the account can take all circuit breaker
    // actions and can grant permissions to other accounts.
    LEVEL_SUPER_ADMIN
)

type Access struct {
	level int32 
	msgs []string // if full permission, msgs can be empty
}

Disable List

禁用的类型 URL 列表：

• DisableList 0x2 | msg_type_url -> []byte{}

状态转移

Authorize

Authorize 由模块权限（默认的治理模块账户）或任何具有 LEVEL_SUPER_ADMIN 权限的账户调用，用于授予另一个账户禁用/启用消息的权限。可以授予三种权限级别：LEVEL_SOME_MSGS 限制可以禁用的消息数量。LEVEL_ALL_MSGS 允许禁用所有消息。LEVEL_SUPER_ADMIN 允许账户执行所有断路器操作，包括授权和撤销授权其他账户。

  // AuthorizeCircuitBreaker allows a super-admin to grant (or revoke) another
  // account's circuit breaker permissions.
  rpc AuthorizeCircuitBreaker(MsgAuthorizeCircuitBreaker) returns (MsgAuthorizeCircuitBreakerResponse);

Trip

Trip 由授权账户调用，用于禁用特定 msgURL 的消息执行。如果为空，则会禁用所有消息。

  // TripCircuitBreaker pauses processing of Msg's in the state machine.
  rpc TripCircuitBreaker(MsgTripCircuitBreaker) returns (MsgTripCircuitBreakerResponse);

Reset

Reset 由授权账户调用，用于启用之前禁用的特定 msgURL 消息的执行。如果为空，则会启用所有禁用的消息。

  // ResetCircuitBreaker resumes processing of Msg's in the state machine that
  // have been been paused using TripCircuitBreaker.
  rpc ResetCircuitBreaker(MsgResetCircuitBreaker) returns (MsgResetCircuitBreakerResponse);

消息

MsgAuthorizeCircuitBreaker

https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/circuit/v1/tx.proto#L25-L75

如果出现以下情况，预计此消息会失败：

• 授权者不是具有 LEVEL_SUPER_ADMIN 权限级别的账户或模块权限账户。

MsgTripCircuitBreaker

https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/circuit/v1/tx.proto#L77-L93

如果出现以下情况，预计此消息会失败：

• 签名者没有权限级别，无法禁用指定类型 URL 的消息。

MsgResetCircuitBreaker

https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/circuit/v1/tx.proto#L95-109

如果出现以下情况，预计此消息会失败：

• 类型 URL 未被禁用。

事件 - 列出并描述事件标签

circuit模块会触发以下事件：

消息事件

MsgAuthorizeCircuitBreaker

类型	属性键	属性值
string	granter	{granterAddress}
string	grantee	{granteeAddress}
string	permission	{granteePermissions}
message	module	circuit
message	action	authorize_circuit_breaker

MsgTripCircuitBreaker

类型	属性键	属性值
string	authority	{authorityAddress}
[]string	msg_urls	[]string{msg_urls}
message	module	circuit
message	action	trip_circuit_breaker

ResetCircuitBreaker

类型	属性键	属性值
string	authority	{authorityAddress}
[]string	msg_urls	[]string{msg_urls}
message	module	circuit
message	action	reset_circuit_breaker

键 - circuit模块使用的键前缀列表

• AccountPermissionPrefix - 0x01

• DisableListPrefix - 0x02

客户端 - 列出并描述CLI命令以及gRPC和REST端点