digitaldrreamer/ckb-transaction-firewall

# CKB 交易防火墙 [](https://www.npmjs.com/package/@ckb-firewall/sdk) [](https://github.com/digitaldrreamer/ckb-transaction-firewall/actions/workflows/tests.yml)  **合约已部署在 CKB 测试网上。** Cell 交易 [`0x11b0397c`](https://explorer.nervos.org/transaction/0x11b0397cd58dce5c2bd704108ee6e1609128c0d828a3f3360237585e82bb7aed) 已提交至区块 `0x141be3d`。注册表值：[`docs/deployments/testnet.registry.json`](./docs/deployments/testnet.registry.json)。 ## 为什么需要这个项目 自主智能体在构建、签名和广播交易时无需人工干预。这种自主性非常有价值 —— 但是**仅依靠应用层的安全检查是不够的**：受损的智能体代码、提示注入（包括[链上载荷技巧](https://arxiv.org/abs/2503.16248)）、错误的工具输出以及多智能体级联，都可能将资金路由到攻击者控制的地址。模拟环节可以被跳过；一旦交易成为最终状态，监控就为时已晚。 该防火墙增加了一个**协议层级的底线**：当钱包 Cell 使用防火墙锁时，SDK 检查的相同黑名单规则会被**每个 CKB 节点**强制执行。治理机制（多重签名、审查窗口等）记录在 [docs/governance.md](./docs/governance.md) 中。 **不仅限于智能体。** 任何构建 CKB 交易的软件 —— 钱包、dapps、托管批处理任务 —— 都可以在签名前运行 SDK 进行预检，并且无论是否涉及 LLM，链上强制执行都适用于任何使用防火墙锁的 Cell。 ## 工作原理 ``` ┌─────────────────────────────────────────────────┐ │ AI Agent / Wallet Runtime │ └──────────────────────┬──────────────────────────┘ │ constructs a transaction ▼ ┌─────────────────────────────────────────────────┐ │ Layer 1 — SDK Pre-flight │ │ Fast, synchronous, no RPC │ │ Parses registry cell dep, rejects blacklisted │ │ outputs before signing │ └──────────────────────┬──────────────────────────┘ │ passes pre-flight → sign and broadcast ▼ ┌─────────────────────────────────────────────────┐ │ Layer 2 — CKB Consensus Enforcement │ │ Every node validates the Firewall lock │ │ Fails closed on missing/invalid/ambiguous dep │ └─────────────────────────────────────────────────┘ ``` **为什么两者都要？** 如果从未调用 SDK，标准锁将无法提供共识黑名单。如果仅存在 SDK，受损的运行时可能会完全跳过检查。两者结合：**SDK = 智能体的快速路径；锁 = 对其他所有人的保证。** 有关更深入的 CKB 原理（Cell 模型、锁脚本、无预言机设计），请参阅：[docs/architecture.md](./docs/architecture.md)。 ## 快速开始 ### TypeScript SDK ``` npm install @ckb-firewall/sdk ``` ``` import { TransactionFirewall } from "@ckb-firewall/sdk"; const registryScript = { codeHash: "0xbbfbcf51b88c57c9c1d6414de4a7e4f9dae133625dfab71588c8bc5d05b71096", hashType: "type", args: "0x019bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce80114003f54dea35bcc7a0efef541d361799f77bd1b8581", }; const registryData = "0x..."; // fetch live cell data from your CKB node const recipientLockArgs = "0x..."; // the lock args you want to check const firewall = new TransactionFirewall({ registryScript }); const result = firewall.checkTransaction({ cellDeps: [{ type: registryScript, data: registryData }], outputs: [{ lockArgs: recipientLockArgs }], }); if (!result.ok) { console.error(result.reason, result.code); } ``` `registryScript` 和 `canonicalRegistryCell` 的实际测试网值记录在 [`docs/deployments/testnet.registry.json`](./docs/deployments/testnet.registry.json) 中。 ### Rust SDK ``` cd sdk/rust && cargo test ``` 使用带有 `FirewallConfig` 和 `UnsignedTxLike` 参数的 `ckb_transaction_firewall_sdk::check_transaction`；请参阅 [`sdk/rust/src/lib.rs`](./sdk/rust/src/lib.rs)。 ## 链上强制执行 防火墙锁和黑名单注册表合约已部署到 CKB 测试网。要部署您自己的实例或升级现有实例： ``` ./scripts/deploy.sh \ --network testnet \ --rpc-url https://testnet.ckb.dev \ --from-address ``` 完整的部署演示：[docs/deployments/testnet.md](./docs/deployments/testnet.md)。 要在 Cell 上使用防火墙锁，请将注册表类型脚本身份编码到锁参数中（请参阅 [docs/lock-script-spec.md](./docs/lock-script-spec.md)）。该锁需要且仅需要一个活跃的注册表 `cell_dep`，其类型脚本必须匹配；否则将拒绝执行并安全关闭。 ## 本地构建与测试 ``` rustup target add riscv64imac-unknown-none-elf # 构建 contracts cd contracts/firewall-lock cargo build --release --target=riscv64imac-unknown-none-elf cd ../blacklist-registry cargo build --release --target=riscv64imac-unknown-none-elf --features dev-signer-keys # 运行 Rust 单元测试 cd ../../tests/unit cargo test --test firewall_lock_tests cargo test --test blacklist_registry_tests # 运行 TypeScript SDK 测试 cd ../sdk/typescript npm ci && npm test ``` ## 安全模型 **防范范围：** 向已知的黑名单锁/类型参数发送交易；智能体被劫持并选择错误接收地址的各类攻击，包括提示注入和受损的工具输出。 **不防范：** 尚未列入黑名单的地址；非地址类的漏洞利用；治理密钥泄露（可通过多重签名和流程缓解）；未使用防火墙锁的 Cell。 **故障安全机制：** 注册表依赖缺失、无效或存在歧义 → **拒绝**。请参阅 [docs/architecture.md](./docs/architecture.md#failure-semantics)。 ## 生态系统 交易防火墙是 [CKB 智能体控制中心](https://github.com/digitaldrreamer/ckb-agent-control-hub) 的强制执行底线 —— 这是 CKB 上 AI 智能体的授权、身份和市场化协议。控制中心定义了智能体*可以*做什么；而本代码库在使用该锁时，强制规定了**任何**智能体都不得向列出的目的地执行操作。 ## 文档 | 主题 | 链接 | |-------|------| | 架构与信任模型 | [docs/architecture.md](./docs/architecture.md) | | 锁脚本规范（参数、错误码） | [docs/lock-script-spec.md](./docs/lock-script-spec.md) | | 治理 | [docs/governance.md](./docs/governance.md) | | 测试网部署 | [docs/deployments/testnet.md](./docs/deployments/testnet.md) | | 标准注册表值 | [docs/deployments/testnet.registry.json](./docs/deployments/testnet.registry.json) | | 更新日志 | [CHANGELOG.md](./CHANGELOG.md) | ## 贡献 在提交 PR 之前，对于较大的更改请先提出 Issue。关于黑名单治理，请遵循 [docs/governance.md](./docs/governance.md) 的说明，而不是通过普通的 PR。安全报告：请使用 GitHub Security Advisories。 ## 许可证 MIT —— 请参阅每个 crate 中的 `Cargo.toml` 以及 `sdk/typescript/LICENSE`。

标签：CISA项目, dApp开发, MITM代理, Nervos CKB, NPM包, OSV-Scalibr, TypeScript, Web3安全, 交易防火墙, 共识层, 区块链安全, 协议层防护, 去中心化应用, 可视化界面, 多重签名, 安全插件, 密码学, 手动系统调用, 智能合约, 社区治理, 自动化交易, 资金安全, 通知系统, 钱包安全, 链上执行, 锁定脚本, 防范提示注入, 黑名单