Circuit

概念

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

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

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

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端点

Last updated