PracticalParticle/Bloxchain-Protocol
GitHub: PracticalParticle/Bloxchain-Protocol
企业级智能合约安全框架，通过多阶段工作流、强制多重签名、时间锁和动态 RBAC 在架构层面消除单点故障。
Stars: 10 | Forks: 1
# Bloxchain Protocol：企业级区块链安全框架
[](https://opensource.org/licenses/MPL-2.0)
[](https://soliditylang.org/)
[](./sdk/typescript/)
[](https://hardhat.org/)
[](https://sepolia.etherscan.io/)
[](https://particlecs.com/)
## 系统概述
该协议的安全态势建立在三个原则之上：
1. **单一变更源。** 所有可变状态都存在于一个结构体（`SecureOperationState`）中，每个部署的合约实例化一次。只有 **EngineBlox** 库可以对其进行变更，这将不变量隔离到单一的审计面上。
2. **强制双重签名授权。** 每个改变状态的操作都必须由至少两个不同的参与方授权——无论是**跨时间**（现在请求，稍后批准，并设有干预窗口）还是**跨角色**（对于元交易，签名者 ≠ 执行者）。这是在**架构层面**强制执行的，而非依靠约定。
3. **通过冗余关卡实现纵深防御。** 在一次检查可能就足够的地方，协议会从不同角度对同一属性进行两层或更多层的检查：身份 vs 角色成员资格、权限授予 vs handler/执行绑定、存储状态 vs 结构不变量。单个受损的层无法绕过其他层。
深入探讨：[协议架构](./docs/bloxchain-architecture.md) · [状态机引擎](./docs/state-machine-engine.md)。
## ⚡ 快速入门：创建钱包
在网络（例如 Sepolia）上[部署基础库和 CopyBlox 之后](#deployment)，您可以通过几个步骤创建自己的安全钱包（AccountBlox 克隆）：
```
npm run create-wallet
```
脚本是交互式的：选择网络、**基础钱包 (AccountBlox)** 或自定义 blox，然后设置 owner / broadcaster / recovery 和 time-lock。它使用您的 `.env.deployment` 部署者密钥，并在完成后写入新的克隆地址（以及 Sepolia 浏览器链接）。
非交互式（全默认）：`CREATE_WALLET_USE_DEFAULTS=1 node scripts/deployment/create-wallet-copyblox.js`
## 🚀 什么是 Bloxchain Protocol？
通过**多阶段工作流**实现的企业级安全性：带有**角色分离**的 time-locked 操作和元交易，因此合约控制存储，而操作需要至少两个参与方。**EngineBlox** 通过模块化组合驱动 time-lock、无 gas 执行和动态 RBAC（参见上文的**系统概述**）。
## 🏗️ 架构概述
### 组件分层
| 层级 | 角色 |
|--------|------|
| **EngineBlox** (library) | 通过 `DELEGATECALL` 链接到集成器中（存储上下文 = 调用者的 `address(this)`）。仅变更传入的 `SecureOperationState` 引用；自身不拥有任何存储。 |
| **BaseStateMachine** | 唯一声明 `_secureState` 的合约。为每个 EngineBlox 流程公开封装器、初始化 helper、hook 和查看辅助工具。 |
| **SecureOwnable** | Owner、Broadcaster、Recovery 以及面向 timelock 的操作。 |
| **RuntimeRBAC** | 动态角色管理和元交易批处理流程。 |
| **GuardController** | 任意外部执行路径和 guard 配置（在协议规则内）。 |
该框架组织为**三个层级**：顶部的无状态库，拥有协议存储的**单一基础合约**，以及**三个可组合组件**（每个组件添加一部分公共接口，外加用于函数 schema 和默认权限授予的定义库）。
**具体可部署的合约**继承它们所需的任何部分。钱包式合约通常组合所有三个组件；金库、ERC-20 或支付调度程序可能只继承 **SecureOwnable**；克隆工厂可能只继承 **BaseStateMachine**。组合方式因部署而异——该框架不强制规定一种模式。
### 核心组件
```
%%{init: {'theme': 'base', 'themeVariables': {'primaryTextColor': '#111827', 'lineColor': '#374151', 'edgeLabelBackground': '#ffffff', 'edgeLabelTextColor': '#111827'}}}%%
graph TB
EB["EngineBlox
(library)"] BSM["BaseStateMachine
owns _secureState
wrappers for every EngineBlox flow
init helper, hooks, view helpers"] SO["SecureOwnable
Owner, Broadcaster, Recovery + timelock operations"] RBAC["RuntimeRBAC
dynamic role management + meta-tx batch flow"] GC["GuardController
arbitrary external execution + guard config"] EB -->|DELEGATECALL
storage context preserved| BSM BSM --> SO BSM --> RBAC BSM --> GC style EB fill:#dbeafe,color:#1e3a8a,stroke:#2563eb style BSM fill:#ccfbf1,color:#115e59,stroke:#0d9488 style SO fill:#ffedd5,color:#7c2d12,stroke:#ea580c style RBAC fill:#ffedd5,color:#7c2d12,stroke:#ea580c style GC fill:#ffedd5,color:#7c2d12,stroke:#ea580c ``` ### 模块化组合 - **BaseStateMachine** → **SecureOwnable**、**RuntimeRBAC**、**GuardController**（可选的 `contracts/experimental/` 中的 **HookManager**） - **Account** 模式组合了所有三个组件 → **AccountBlox** 模板 (`contracts/examples/templates/`) - **示例：** SimpleVault、SimpleRWA20、PayBlox（仅限 **SecureOwnable**）；**CopyBlox**（仅限 **BaseStateMachine**）；GuardianSafe（**SecureOwnable** + Safe guard）；BasicERC20（独立 ERC20，通常由 AccountBlox 铸造） ### 交易生命周期 每个操作都是一个以单调递增的 **txId** 为键的 **TxRecord**，具有单一的 **TxStatus**（Solidity enum 顺序）：`UNDEFINED`、`PENDING`、`EXECUTING`、`PROCESSING_PAYMENT`、`CANCELLED`、`COMPLETED`、`FAILED`。 ``` %%{init: {'theme': 'base', 'themeVariables': {'primaryTextColor': '#111827', 'lineColor': '#374151', 'edgeLabelBackground': '#ffffff', 'edgeLabelTextColor': '#111827'}}}%% stateDiagram-v2 direction LR classDef active fill:#dbeafe,color:#1e3a8a,stroke:#2563eb classDef terminal fill:#dcfce7,color:#14532d,stroke:#16a34a classDef cancelled fill:#fee2e2,color:#7f1d1d,stroke:#dc2626 classDef failed fill:#ffedd5,color:#7c2d12,stroke:#ea580c [*] --> UNDEFINED UNDEFINED --> PENDING: time-delay request PENDING --> CANCELLED: cancel PENDING --> EXECUTING: approve or meta-tx execute EXECUTING --> COMPLETED: success EXECUTING --> FAILED: revert EXECUTING --> PROCESSING_PAYMENT: attached payment PROCESSING_PAYMENT --> COMPLETED: payment ok PROCESSING_PAYMENT --> FAILED: payment revert CANCELLED --> [*] COMPLETED --> [*] FAILED --> [*] class UNDEFINED,PENDING,EXECUTING,PROCESSING_PAYMENT active class COMPLETED terminal class CANCELLED cancelled class FAILED failed ``` 两种工作流模式共享相同的 **PENDING → EXECUTING → terminal**（终态）推进过程（`COMPLETED`、`FAILED` 或 `CANCELLED`）；它们的区别在于如何提供授权以及是否适用等待窗口。 - **Time-delay 流程。** 拥有 **EXECUTE_TIME_DELAY_REQUEST** 权限的参与方创建一个 `PENDING` 记录，其中 `releaseTime = block.timestamp + timeLockPeriodSec`。在时间窗口之后，拥有 **EXECUTE_TIME_DELAY_APPROVE** 权限的参与方将记录从 `EXECUTING` 推进到终态。**EXECUTE_TIME_DELAY_CANCEL** 可以在此窗口期间将其移至 `CANCELLED`。 - **元交易流程。** 拥有 `SIGN_META_*` 权限的签名者在链下对完整的 `MetaTransaction` 结构体生成 **EIP-712** 签名。拥有 `EXECUTE_META_*` 权限的执行者在链上提交它。EngineBlox 运行完整性检查（签名长度、chain ID、deadline、gas price、nonce、handler 绑定、签名者权限双重检查、ECDSA 恢复），递增签名者的 nonce，并在一次调用中完成生命周期。 - **融合的“请求并批准”元交易。** 用于协议省略 time-delay 的情况（例如 recovery 轮换、time-lock 更改、role-config 批处理、guard-config 批处理）：通过签名者与执行者的分离保留了双重签名属性，而无需单独的链上等待窗口。 **外部执行：** 向 **`EXECUTING`** 的转换是协议调用任意外部代码的唯一节点。 ### 安全模型（角色） - **Time-delay：** 请求 → 等待 → 批准（两步 / 两方）。**元交易：** 签名 → 执行（签名者 ≠ 执行者）。 - **角色：** Owner（管理员、批准）、Broadcaster（执行元交易、gas）、Recovery（紧急情况）。 ## 🚀 快速开始 **前提条件：** 此 monorepo 需要 Node.js **>=22.12.0**（开发工具、CI、`npm ci`；通过根目录 `engines` + `.npmrc` `engine-strict=true` 强制执行）。已发布的 **`@bloxchain/sdk`** 消费者在 runtime 仍需 **>=18.20.5**（参见 `sdk/typescript/package.json`）。 ``` git clone https://github.com/PracticalParticle/Bloxchain-Protocol.git cd Bloxchain-Protocol npm install npm run compile:foundry npm run test:foundry ``` **SDK / 合约：** `npm install @bloxchain/sdk @bloxchain/contracts` **网络：** 本地、[Sepolia](https://sepolia.etherscan.io/) ## 部署 1. 将 `env.deployment.example` 复制到 `.env.deployment` 并设置 `DEPLOY_RPC_URL`、`DEPLOY_PRIVATE_KEY`；可选设置 `DEPLOY_CHAIN_ID`（Sepolia：`11155111`）和 `DEPLOY_NETWORK_NAME`。 2. **基础库：** `npm run deploy:hardhat:foundation` 或者：`npx hardhat run scripts/deployment/deploy-foundation-libraries.js --network sepolia` 3. **示例：** `npx hardhat run scripts/deployment/deploy-example-copyblox.js --network sepolia` 地址将写入 **`deployed-addresses.json`**。 ### 已部署地址 **Ethereum Sepolia (testnet)** #### 基础库 | 合约 | 地址 | |----------|---------| | EngineBlox | [`0x726d78c9683a96d66196d2b8350923e8ca0d8597`](https://sepolia.etherscan.io/address/0x726d78c9683a96d66196d2b8350923e8ca0d8597) | | SecureOwnableDefinitions | [`0xcb8834e55c2c7b012e5643de98a1bf5fda22191c`](https://sepolia.etherscan.io/address/0xcb8834e55c2c7b012e5643de98a1bf5fda22191c) | | RuntimeRBACDefinitions | [`0x27c103b2b1a1e7dc345aeff766aa3656b4825653`](https://sepolia.etherscan.io/address/0x27c103b2b1a1e7dc345aeff766aa3656b4825653) | | GuardControllerDefinitions | [`0x6ce6f314fa35d34782f2743db4d0c1f824639938`](https://sepolia.etherscan.io/address/0x6ce6f314fa35d34782f2743db4d0c1f824639938) | #### 账户 | 合约 | 地址 | |----------|---------| | AccountBlox | [`0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0`](https://sepolia.etherscan.io/address/0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0) | #### 示例 | 合约 | 地址 | |----------|---------| | CopyBlox | [`0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7`](https://sepolia.etherscan.io/address/0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7) | ## 📖 用法示例 ``` import { SecureOwnable } from '@bloxchain/sdk'; const secureOwnable = new SecureOwnable(publicClient, walletClient, contractAddress, chain); // Time-locked ownership transfer await secureOwnable.transferOwnershipRequest({ from: ownerAddress }); await secureOwnable.transferOwnershipDelayedApproval(txId, { from: ownerAddress }); ``` 元交易和 Runtime RBAC 示例：参见 [@bloxchain/sdk](https://www.npmjs.com/package/@bloxchain/sdk) 以及代码库的 `sdk/` 和 `test/` 目录。 ## 🔐 Runtime RBAC 和 GuardController - **Runtime RBAC：** 通过 `roleConfigBatch` 实现的动态角色；函数级权限（action 位图），受保护的系统角色。使用 `@bloxchain/sdk` 中的 `RuntimeRBAC` 进行角色创建和查询。 - **GuardController：** 受控的外部调用：基于函数的 target 白名单，time-lock/元交易工作流。注册 schema，将 target 加入白名单，然后通过 EngineBlox 工作流执行。参见 `AccountBlox` 和示例合约。 ## 📋 定义数据层 `IDefinition` 以 `pure` 函数的形式提供**函数 schema**和**角色权限**；定义位于单独的库中，以减小合约体积。参见 `contracts/.../lib/definitions/` 和 SDK 以进行发现。 ## 🧪 Fuzz 测试 **37 个测试套件，309 个测试**（状态机、元交易、RBAC、GuardController、支付、hook、定义、gas limit、组合攻击）。有关 Attack Vectors Codex，请参见 [test/foundry/docs](test/foundry/docs/)。 ``` npm run test:foundry:fuzz # 或者：forge test --match-path "test/foundry/fuzz/ComprehensiveStateMachineFuzz.t.sol" --fuzz-runs 10000 ``` ## 🔧 开发工具 本仓库开发需要 Node.js **>=22.12.0**（参见根目录 `package.json` 中的 `engines`）。对于 npm 消费者，SDK runtime 最低版本要求在 `sdk/typescript/package.json` 中保持为 **>=18.20.5**。 ``` npm run compile:foundry # compile; add :size for 24KB check npm run test:foundry # tests npm run test:foundry:fuzz # fuzz npm run test:e2e # compile:foundry:abi + test:sanity-sdk:core (TypeScript SDK runner) npm run test:sanity-sdk:core # live core suites (SecureOwnable, RuntimeRBAC, GuardController) npm run docgen # docs ``` **E2E 与 legacy 健全性测试：** `test:e2e` 运行 `compile:foundry:abi`，然后运行 `test:sanity-sdk:core` —— 这是基于 TypeScript SDK 的运行器，用于 `remote_evm` 上的核心集成套件。建议优先使用此命令而不是 `test:sanity:core`（legacy Web3 `scripts/sanity/` 运行器；不在默认的发布门控中，可能需要额外依赖）。使用 `RUN_SANITY_SDK_TESTS=1 npm run release:prepare` 可执行包含实时 SDK 测试在内的完整发布前门控。 ## 📚 文档 - **[核心审计与变更策略](contracts/core/AUDIT.md)** · **[Nethermind 报告](audits/nethermind/)** · **[技术概述](TECHNICAL_OVERVIEW.md)** – 事实来源、审查者背景、已发布的审计 - **[版本控制与发布](docs/VERSIONING.md)** – npm 包、链上 `EngineBlox.VERSION`、Release Please - [协议架构](./docs/bloxchain-architecture.md) · [状态机](./docs/state-machine-engine.md) · [快速入门](./docs/getting-started.md) · [API 参考](./docs/api-reference.md) · [SecureOwnable](./docs/secure-ownable.md) · [RuntimeRBAC](./docs/runtime-rbac.md) · [最佳实践](./docs/best-practices.md) · [示例](./docs/examples-basic.md) **合约 API（生成）：** [docs/](docs/) – 通过 `npm run docgen` 从 Solidity NatSpec 生成 ## 🛡️ 安全特性 - **单一变更面、双方操作、冗余关卡** — 参见[系统概述](#system-overview)。 - **Time-delay：** 请求 →（等待）→ 批准 → 执行。**元交易：** 签名 → 执行（签名者 ≠ 执行者）。 - **EIP-712** 结构化数据、每个签名者的 nonce、time-lock 强制执行。函数级权限：请求/批准/取消、签名/执行，以及动态 RBAC。 ## 🌟 主要优势 **开发者：** 无单点故障；无 gas 元交易；runtime RBAC；类型安全的 SDK。**企业：** Time-lock、审计追踪、24KB 以下的合约。**用户：** Recovery 选项、透明度。 ## 🔬 技术规格 **技术栈：** Solidity 0.8.34、OpenZeppelin ^5.4.0（可升级）。**库：** EngineBlox → BaseStateMachine → SecureOwnable、RuntimeRBAC、GuardController、HookManager。合约体积在 24KB 以下；EIP-712；基于 Viem 的 TypeScript SDK。**测试：** Foundry（fuzz + invariant）、Hardhat、健全性脚本。所有核心组件、模板 (AccountBlox)、示例应用程序和 Sepolia 部署均已实现并被测试覆盖。 ## 📄 许可证 **MPL-2.0** – 参见 [LICENSE](LICENSE)。涵盖核心合约（`contracts/core/`）、SDK（`sdk/typescript/`）、文档、测试、工具。**排除项：** `contracts/examples/`（按文件的 SPDX 许可证；代码库内示例为 MIT）。入库贡献：MPL-2.0 + [DCO](DCO)；参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 📞 支持与社区 文档：[`docs/`](./docs/)。示例：[`contracts/examples/`](./contracts/examples/)。测试：[`test/foundry/`](./test/foundry/) · [`scripts/sanity/`](./scripts/sanity/)。[问题](https://github.com/PracticalParticle/Bloxchain-Protocol/issues) · [讨论](https://github.com/PracticalParticle/Bloxchain-Protocol/discussions)。 由 [Particle Crypto Security](https://particlecs.com/) 创建 · 版权所有 © 2025 Particle Crypto Security。
(library)"] BSM["BaseStateMachine
owns _secureState
wrappers for every EngineBlox flow
init helper, hooks, view helpers"] SO["SecureOwnable
Owner, Broadcaster, Recovery + timelock operations"] RBAC["RuntimeRBAC
dynamic role management + meta-tx batch flow"] GC["GuardController
arbitrary external execution + guard config"] EB -->|DELEGATECALL
storage context preserved| BSM BSM --> SO BSM --> RBAC BSM --> GC style EB fill:#dbeafe,color:#1e3a8a,stroke:#2563eb style BSM fill:#ccfbf1,color:#115e59,stroke:#0d9488 style SO fill:#ffedd5,color:#7c2d12,stroke:#ea580c style RBAC fill:#ffedd5,color:#7c2d12,stroke:#ea580c style GC fill:#ffedd5,color:#7c2d12,stroke:#ea580c ``` ### 模块化组合 - **BaseStateMachine** → **SecureOwnable**、**RuntimeRBAC**、**GuardController**（可选的 `contracts/experimental/` 中的 **HookManager**） - **Account** 模式组合了所有三个组件 → **AccountBlox** 模板 (`contracts/examples/templates/`) - **示例：** SimpleVault、SimpleRWA20、PayBlox（仅限 **SecureOwnable**）；**CopyBlox**（仅限 **BaseStateMachine**）；GuardianSafe（**SecureOwnable** + Safe guard）；BasicERC20（独立 ERC20，通常由 AccountBlox 铸造） ### 交易生命周期 每个操作都是一个以单调递增的 **txId** 为键的 **TxRecord**，具有单一的 **TxStatus**（Solidity enum 顺序）：`UNDEFINED`、`PENDING`、`EXECUTING`、`PROCESSING_PAYMENT`、`CANCELLED`、`COMPLETED`、`FAILED`。 ``` %%{init: {'theme': 'base', 'themeVariables': {'primaryTextColor': '#111827', 'lineColor': '#374151', 'edgeLabelBackground': '#ffffff', 'edgeLabelTextColor': '#111827'}}}%% stateDiagram-v2 direction LR classDef active fill:#dbeafe,color:#1e3a8a,stroke:#2563eb classDef terminal fill:#dcfce7,color:#14532d,stroke:#16a34a classDef cancelled fill:#fee2e2,color:#7f1d1d,stroke:#dc2626 classDef failed fill:#ffedd5,color:#7c2d12,stroke:#ea580c [*] --> UNDEFINED UNDEFINED --> PENDING: time-delay request PENDING --> CANCELLED: cancel PENDING --> EXECUTING: approve or meta-tx execute EXECUTING --> COMPLETED: success EXECUTING --> FAILED: revert EXECUTING --> PROCESSING_PAYMENT: attached payment PROCESSING_PAYMENT --> COMPLETED: payment ok PROCESSING_PAYMENT --> FAILED: payment revert CANCELLED --> [*] COMPLETED --> [*] FAILED --> [*] class UNDEFINED,PENDING,EXECUTING,PROCESSING_PAYMENT active class COMPLETED terminal class CANCELLED cancelled class FAILED failed ``` 两种工作流模式共享相同的 **PENDING → EXECUTING → terminal**（终态）推进过程（`COMPLETED`、`FAILED` 或 `CANCELLED`）；它们的区别在于如何提供授权以及是否适用等待窗口。 - **Time-delay 流程。** 拥有 **EXECUTE_TIME_DELAY_REQUEST** 权限的参与方创建一个 `PENDING` 记录，其中 `releaseTime = block.timestamp + timeLockPeriodSec`。在时间窗口之后，拥有 **EXECUTE_TIME_DELAY_APPROVE** 权限的参与方将记录从 `EXECUTING` 推进到终态。**EXECUTE_TIME_DELAY_CANCEL** 可以在此窗口期间将其移至 `CANCELLED`。 - **元交易流程。** 拥有 `SIGN_META_*` 权限的签名者在链下对完整的 `MetaTransaction` 结构体生成 **EIP-712** 签名。拥有 `EXECUTE_META_*` 权限的执行者在链上提交它。EngineBlox 运行完整性检查（签名长度、chain ID、deadline、gas price、nonce、handler 绑定、签名者权限双重检查、ECDSA 恢复），递增签名者的 nonce，并在一次调用中完成生命周期。 - **融合的“请求并批准”元交易。** 用于协议省略 time-delay 的情况（例如 recovery 轮换、time-lock 更改、role-config 批处理、guard-config 批处理）：通过签名者与执行者的分离保留了双重签名属性，而无需单独的链上等待窗口。 **外部执行：** 向 **`EXECUTING`** 的转换是协议调用任意外部代码的唯一节点。 ### 安全模型（角色） - **Time-delay：** 请求 → 等待 → 批准（两步 / 两方）。**元交易：** 签名 → 执行（签名者 ≠ 执行者）。 - **角色：** Owner（管理员、批准）、Broadcaster（执行元交易、gas）、Recovery（紧急情况）。 ## 🚀 快速开始 **前提条件：** 此 monorepo 需要 Node.js **>=22.12.0**（开发工具、CI、`npm ci`；通过根目录 `engines` + `.npmrc` `engine-strict=true` 强制执行）。已发布的 **`@bloxchain/sdk`** 消费者在 runtime 仍需 **>=18.20.5**（参见 `sdk/typescript/package.json`）。 ``` git clone https://github.com/PracticalParticle/Bloxchain-Protocol.git cd Bloxchain-Protocol npm install npm run compile:foundry npm run test:foundry ``` **SDK / 合约：** `npm install @bloxchain/sdk @bloxchain/contracts` **网络：** 本地、[Sepolia](https://sepolia.etherscan.io/) ## 部署 1. 将 `env.deployment.example` 复制到 `.env.deployment` 并设置 `DEPLOY_RPC_URL`、`DEPLOY_PRIVATE_KEY`；可选设置 `DEPLOY_CHAIN_ID`（Sepolia：`11155111`）和 `DEPLOY_NETWORK_NAME`。 2. **基础库：** `npm run deploy:hardhat:foundation` 或者：`npx hardhat run scripts/deployment/deploy-foundation-libraries.js --network sepolia` 3. **示例：** `npx hardhat run scripts/deployment/deploy-example-copyblox.js --network sepolia` 地址将写入 **`deployed-addresses.json`**。 ### 已部署地址 **Ethereum Sepolia (testnet)** #### 基础库 | 合约 | 地址 | |----------|---------| | EngineBlox | [`0x726d78c9683a96d66196d2b8350923e8ca0d8597`](https://sepolia.etherscan.io/address/0x726d78c9683a96d66196d2b8350923e8ca0d8597) | | SecureOwnableDefinitions | [`0xcb8834e55c2c7b012e5643de98a1bf5fda22191c`](https://sepolia.etherscan.io/address/0xcb8834e55c2c7b012e5643de98a1bf5fda22191c) | | RuntimeRBACDefinitions | [`0x27c103b2b1a1e7dc345aeff766aa3656b4825653`](https://sepolia.etherscan.io/address/0x27c103b2b1a1e7dc345aeff766aa3656b4825653) | | GuardControllerDefinitions | [`0x6ce6f314fa35d34782f2743db4d0c1f824639938`](https://sepolia.etherscan.io/address/0x6ce6f314fa35d34782f2743db4d0c1f824639938) | #### 账户 | 合约 | 地址 | |----------|---------| | AccountBlox | [`0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0`](https://sepolia.etherscan.io/address/0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0) | #### 示例 | 合约 | 地址 | |----------|---------| | CopyBlox | [`0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7`](https://sepolia.etherscan.io/address/0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7) | ## 📖 用法示例 ``` import { SecureOwnable } from '@bloxchain/sdk'; const secureOwnable = new SecureOwnable(publicClient, walletClient, contractAddress, chain); // Time-locked ownership transfer await secureOwnable.transferOwnershipRequest({ from: ownerAddress }); await secureOwnable.transferOwnershipDelayedApproval(txId, { from: ownerAddress }); ``` 元交易和 Runtime RBAC 示例：参见 [@bloxchain/sdk](https://www.npmjs.com/package/@bloxchain/sdk) 以及代码库的 `sdk/` 和 `test/` 目录。 ## 🔐 Runtime RBAC 和 GuardController - **Runtime RBAC：** 通过 `roleConfigBatch` 实现的动态角色；函数级权限（action 位图），受保护的系统角色。使用 `@bloxchain/sdk` 中的 `RuntimeRBAC` 进行角色创建和查询。 - **GuardController：** 受控的外部调用：基于函数的 target 白名单，time-lock/元交易工作流。注册 schema，将 target 加入白名单，然后通过 EngineBlox 工作流执行。参见 `AccountBlox` 和示例合约。 ## 📋 定义数据层 `IDefinition` 以 `pure` 函数的形式提供**函数 schema**和**角色权限**；定义位于单独的库中，以减小合约体积。参见 `contracts/.../lib/definitions/` 和 SDK 以进行发现。 ## 🧪 Fuzz 测试 **37 个测试套件，309 个测试**（状态机、元交易、RBAC、GuardController、支付、hook、定义、gas limit、组合攻击）。有关 Attack Vectors Codex，请参见 [test/foundry/docs](test/foundry/docs/)。 ``` npm run test:foundry:fuzz # 或者：forge test --match-path "test/foundry/fuzz/ComprehensiveStateMachineFuzz.t.sol" --fuzz-runs 10000 ``` ## 🔧 开发工具 本仓库开发需要 Node.js **>=22.12.0**（参见根目录 `package.json` 中的 `engines`）。对于 npm 消费者，SDK runtime 最低版本要求在 `sdk/typescript/package.json` 中保持为 **>=18.20.5**。 ``` npm run compile:foundry # compile; add :size for 24KB check npm run test:foundry # tests npm run test:foundry:fuzz # fuzz npm run test:e2e # compile:foundry:abi + test:sanity-sdk:core (TypeScript SDK runner) npm run test:sanity-sdk:core # live core suites (SecureOwnable, RuntimeRBAC, GuardController) npm run docgen # docs ``` **E2E 与 legacy 健全性测试：** `test:e2e` 运行 `compile:foundry:abi`，然后运行 `test:sanity-sdk:core` —— 这是基于 TypeScript SDK 的运行器，用于 `remote_evm` 上的核心集成套件。建议优先使用此命令而不是 `test:sanity:core`（legacy Web3 `scripts/sanity/` 运行器；不在默认的发布门控中，可能需要额外依赖）。使用 `RUN_SANITY_SDK_TESTS=1 npm run release:prepare` 可执行包含实时 SDK 测试在内的完整发布前门控。 ## 📚 文档 - **[核心审计与变更策略](contracts/core/AUDIT.md)** · **[Nethermind 报告](audits/nethermind/)** · **[技术概述](TECHNICAL_OVERVIEW.md)** – 事实来源、审查者背景、已发布的审计 - **[版本控制与发布](docs/VERSIONING.md)** – npm 包、链上 `EngineBlox.VERSION`、Release Please - [协议架构](./docs/bloxchain-architecture.md) · [状态机](./docs/state-machine-engine.md) · [快速入门](./docs/getting-started.md) · [API 参考](./docs/api-reference.md) · [SecureOwnable](./docs/secure-ownable.md) · [RuntimeRBAC](./docs/runtime-rbac.md) · [最佳实践](./docs/best-practices.md) · [示例](./docs/examples-basic.md) **合约 API（生成）：** [docs/](docs/) – 通过 `npm run docgen` 从 Solidity NatSpec 生成 ## 🛡️ 安全特性 - **单一变更面、双方操作、冗余关卡** — 参见[系统概述](#system-overview)。 - **Time-delay：** 请求 →（等待）→ 批准 → 执行。**元交易：** 签名 → 执行（签名者 ≠ 执行者）。 - **EIP-712** 结构化数据、每个签名者的 nonce、time-lock 强制执行。函数级权限：请求/批准/取消、签名/执行，以及动态 RBAC。 ## 🌟 主要优势 **开发者：** 无单点故障；无 gas 元交易；runtime RBAC；类型安全的 SDK。**企业：** Time-lock、审计追踪、24KB 以下的合约。**用户：** Recovery 选项、透明度。 ## 🔬 技术规格 **技术栈：** Solidity 0.8.34、OpenZeppelin ^5.4.0（可升级）。**库：** EngineBlox → BaseStateMachine → SecureOwnable、RuntimeRBAC、GuardController、HookManager。合约体积在 24KB 以下；EIP-712；基于 Viem 的 TypeScript SDK。**测试：** Foundry（fuzz + invariant）、Hardhat、健全性脚本。所有核心组件、模板 (AccountBlox)、示例应用程序和 Sepolia 部署均已实现并被测试覆盖。 ## 📄 许可证 **MPL-2.0** – 参见 [LICENSE](LICENSE)。涵盖核心合约（`contracts/core/`）、SDK（`sdk/typescript/`）、文档、测试、工具。**排除项：** `contracts/examples/`（按文件的 SPDX 许可证；代码库内示例为 MIT）。入库贡献：MPL-2.0 + [DCO](DCO)；参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 📞 支持与社区 文档：[`docs/`](./docs/)。示例：[`contracts/examples/`](./contracts/examples/)。测试：[`test/foundry/`](./test/foundry/) · [`scripts/sanity/`](./scripts/sanity/)。[问题](https://github.com/PracticalParticle/Bloxchain-Protocol/issues) · [讨论](https://github.com/PracticalParticle/Bloxchain-Protocol/discussions)。 由 [Particle Crypto Security](https://particlecs.com/) 创建 · 版权所有 © 2025 Particle Crypto Security。
标签：Solidity, 区块链, 多签钱包, 智能合约, 权限控制