Skip to main content

Circuit Breaker Module

ZIGChain includes the Cosmos SDK circuit breaker module (x/circuit) — an emergency safety valve that can stop specific message types from being executed. It is an independent module: it is not part of the governance voting flow, and tripping it is not a proposal.

Overview​

Every transaction on ZIGChain carries one or more messages, each identified by a type URL such as cosmos.bank.v1beta1.MsgSend. The circuit breaker keeps a list of disabled message types. When a message type is on that list, the chain rejects any transaction containing it until the type is re-enabled.

This is a targeted control, not a kill switch. Blocks continue to be produced and every message type that is not on the list keeps working normally.

Key Concepts​

  • Trip (disable): Add a message type to the disabled list so the chain stops executing it.
  • Reset (enable): Remove a message type from the disabled list so it can be executed again.
  • Type URL: The identifier of a message, for example cosmos.bank.v1beta1.MsgSend. Trips and resets operate on these.
  • Permission level: How much an authorized account may do. Levels are listed below.
  • Grantee: An account that has been authorized to use the circuit breaker.

Permission Levels​

Accounts must be authorized before they can trip anything. Authorization is itself a transaction, sent by an account that already holds super-admin permission.

LevelNameWhat the account may do
1SOME_MSGSTrip and reset only the message type URLs listed in its own grant.
2ALL_MSGSTrip and reset any message type.
3SUPER_ADMINTrip and reset any message type, and authorize or revoke other accounts.

Circuit Breaker on ZIGChain​

  • Who holds it: The ZIGChain Foundation holds circuit-breaker permissions. Those permissions are assigned and revocable through on-chain governance — the module itself is separate from governance, but who may use it is a decision the chain makes by vote.
  • What it can do: Disable selected message types temporarily during incident response.
  • What it cannot do: Seize balances, mint or burn tokens, blocklist addresses, or halt CometBFT consensus itself.

This is distinct from Token Wrapper pausers or contract-level blocklists on regulated assets.

How a Trip Works​

  1. An authorized account submits a trip for one or more message type URLs.
  2. Those types are added to the disabled list on chain.
  3. Any transaction containing a disabled message type is rejected. Other traffic is unaffected.
  4. When the incident is resolved, an authorized account resets the same type URLs and normal execution resumes.
note

Tripping the circuit breaker takes effect as soon as the transaction is included in a block. There is no voting period, which is what makes it useful during an incident.

Circuit Breaker CLI Quick Sheet​

Query commands are read-only and safe to run against a public node. The tx commands below require an authorized key and will fail for accounts without permission.

List all disabled message types
zigchaind query circuit disabled-list \
--chain-id zigchain-1 --node https://public-zigchain-rpc.numia.xyz
Query one account's permissions
zigchaind query circuit account <ADDRESS> \
--chain-id zigchain-1 --node https://public-zigchain-rpc.numia.xyz
Query all account permissions
zigchaind query circuit accounts \
--chain-id zigchain-1 --node https://public-zigchain-rpc.numia.xyz

Authorized Account Commands​

Authorize an account
zigchaind tx circuit authorize <GRANTEE-ADDRESS> \
'{"level":1,"limit_type_urls":["cosmos.bank.v1beta1.MsgSend"]}' \
--from <SUPER-ADMIN-KEY> --chain-id zigchain-1 \
--node https://public-zigchain-rpc.numia.xyz \
--gas-prices 0.0025uzig --gas auto --gas-adjustment 1.3
Disable (trip) message types
zigchaind tx circuit disable "cosmos.bank.v1beta1.MsgSend cosmos.bank.v1beta1.MsgMultiSend" \
--from <AUTHORIZED-KEY> --chain-id zigchain-1 \
--node https://public-zigchain-rpc.numia.xyz \
--gas-prices 0.0025uzig --gas auto --gas-adjustment 1.3
Reset (re-enable) message types
zigchaind tx circuit reset "cosmos.bank.v1beta1.MsgSend cosmos.bank.v1beta1.MsgMultiSend" \
--from <AUTHORIZED-KEY> --chain-id zigchain-1 \
--node https://public-zigchain-rpc.numia.xyz \
--gas-prices 0.0025uzig --gas auto --gas-adjustment 1.3

References​