How to Use the Firewall

If you want the shortest accurate path through this system, read this page first.

1. Get the registry script identity.
2. Fetch the live registry cell data.
3. Feed that data into the SDK before signing.
4. Use the CLI to inspect the live registry before you update anything.
5. Use the governance flow when you need to change the registry.

Do not mix up the two cell types

The registry script identity is what tells you which live cell to trust. The live registry cell data is the BLKL payload you actually parse. The registry contract binary cell is not the registry payload.

What the runtime needs

TypeScript SDK Pre-flight unsigned transactions in JavaScript or TypeScript.

Rust SDK Run the same policy from Rust code.

CLI quickstart Inspect the live registry and walk the governance flow.

BLKL format Exact registry payload layout and rules.

A wallet, bot, or service needs three things:

• the exact registryScript identity
• the live registry cell data
• the unsigned transaction outputs you want to check

1. Get the live registry data

If you are using the checked-in testnet fixture, start with notes/deployments/testnet.registry.json. It contains the current canonical registry script and the matching live registry cell outpoint.

ckb-cli --url https://testnet.ckb.dev rpc get_live_cell \
  --tx-hash 0x57edc162ddd476d970b8a65558466ca11bb1762be9366fd12c76d620fe695fb7 \
  --index 0 \
  --with-data \
  --output-format json

If you are on another network, replace that outpoint with the live registry cell you want to trust. The important part is the cell data, not the contract binary cell.

Checked-in fixture

{
  "registryScript": {
    "codeHash": "0xbbfbcf51b88c57c9c1d6414de4a7e4f9dae133625dfab71588c8bc5d05b71096",
    "hashType": "type",
    "args": "0x019bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce80114003f54dea35bcc7a0efef541d361799f77bd1b8581"
  },
  "canonicalRegistryCell": {
    "txHash": "0x57edc162ddd476d970b8a65558466ca11bb1762be9366fd12c76d620fe695fb7",
    "index": 0,
    "data": "0x424c4b4c010100000020ec2cd50681d6b1b71fd762734c6b212c074ffa52fc6aed9aa6bf3566f58a9c150000000000000000"
  }
}

From chain

ckb-cli --url "$RPC_URL" rpc get_live_cell \
  --tx-hash "$REGISTRY_TX" \
  --index "$REGISTRY_INDEX" \
  --with-data \
  --output-format json

2. Pass the live data into the SDK

import { TransactionFirewall } from "@ckb-firewall/sdk";

const firewall = new TransactionFirewall({
  registryScript: {
    codeHash: "0xbbfbcf51b88c57c9c1d6414de4a7e4f9dae133625dfab71588c8bc5d05b71096",
    hashType: "type",
    args: "0x019bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce80114003f54dea35bcc7a0efef541d361799f77bd1b8581",
  },
});

const result = firewall.checkTransaction({
  cellDeps: [
    {
      type: {
        codeHash: "0xbbfbcf51b88c57c9c1d6414de4a7e4f9dae133625dfab71588c8bc5d05b71096",
        hashType: "type",
        args: "0x019bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce80114003f54dea35bcc7a0efef541d361799f77bd1b8581",
      },
      data: "0x424c4b4c010100000020ec2cd50681d6b1b71fd762734c6b212c074ffa52fc6aed9aa6bf3566f58a9c150000000000000000",
    },
  ],
  outputs: [
    { lockArgs: "0xabc123..." },
    { lockArgs: "0xdef456...", typeArgs: "0x..." },
  ],
});

if (!result.ok) {
  throw new Error(`${result.reason} (${result.code})`);
}

What the SDK does and does not do

The SDK does not fetch RPC data for you. It also does not guess which registry dep is correct. You provide the live registry cell data, and it checks the transaction against that payload.

3. Inspect before you change anything

ckb-firewall inspect

That command reads the current live registry cell and prints the sorted blacklist entries. Use it before you propose changes and before you trust a new network deployment.

4. Update through governance when the registry needs to change

ckb-firewall propose
ckb-firewall vote --proposal <id> --vote yes --validator alice
ckb-firewall sign --proposal <id> --signer-index 0
ckb-firewall execute --proposal <id>

Rule

The quick add and remove commands are for testnet and development. The public path is the governance flow above.

Rules worth remembering

• BLKL is versioned. Current payload version is 0x01.
• Entries should be sorted by identifier.
• The TypeScript SDK currently accepts equal identifiers, but the Rust SDK rejects non-increasing order. If you want both SDKs to accept the same payload, keep entries strictly sorted.
• lock_args and type_args are checked independently.
• Missing, invalid, or ambiguous registry deps fail closed.
• The lock is the consensus guarantee; the SDK is the fast pre-flight path.

Next pages

Firewall lock args How the lock points at the registry and wrapped inner lock.

GOV1 witness How registry updates are bound to proposal and vote context.

Error codes Codes you should handle in wallets, bots, and CLIs.