kilax9276/collateral-settlement-gateway

# 抵押品结算网关 **链上抵押品。链下速度。可审计的结算。** 抵押品结算网关 (Collateral Settlement Gateway) 是一个专业的 Web3 参考实现，适用于需要在链上持有用户抵押品，同时在链下执行快速业务逻辑的应用程序。它将 Solidity 金库、EIP-712 钱包签名意图、应用授权结算、受保护的提取、结算审计报告、对账以及操作员控制台整合为一个连贯的开发者项目。 该代码库包含一个交易参考应用程序，用于在金融工作流中演示此模式。网关本身的范围更广：它可以支持预测市场、抵押游戏、奖励引擎、交易竞赛、风险模拟、衍生品实验，以及其他需要可验证结算层的链下应用程序。 ## 项目存在的意义 许多 Web3 产品都面临相同的架构冲突： - 区块链提供托管、结算透明度和可验证事件； - 应用逻辑通常需要比公链最终确定交易更快的响应速度； - 用户仍然需要证明存款、取款和最终余额不是任意的后端数字。 抵押品结算网关通过分离职责来解决这一差距： | 层级 | 职责 | | ---------------- | -------------------------------------------------------------------------------------------- | | 智能合约 | 抵押品托管、保险流动性、受保护的提取、最终结算事件 | | 网关后端 | 签名意图验证、应用授权、链下业务工作流、结算提交、审计报告 | | 外部应用 | 产品特定的逻辑，例如奖励、预测、游戏结果或交易计算 | | 操作员控制台 | 对健康状态、指标、对账、结算和系统活动的可视化 | 结果是一个可重用的模式：**具有链上抵押品锚定和可审计性的快速链下执行**。 ## 适用场景 本代码库适用于创始人、后端工程师、Web3 团队和技术评估人员，他们希望了解如何构建混合链上/链下金融基础设施。 潜在用例： - **交易竞赛** — 用户存入抵押品，在链下交易模拟市场，并在链上结算结果。 - **预测市场** — 用户签署链下参与意图，应用解析结果，网关结算奖励。 - **抵押游戏** — 游戏逻辑在链下运行，而用户存款和支出仍然锚定到金库。 - **奖励系统** — 外部应用提交与签名用户操作相关联的奖励结算。 - **衍生品实验** — 头寸和风险可以在链下快速计算，同时保持结算可审计。 - **内部风险模拟** — 团队可以对结算工作流进行建模，而无需从头构建托管堆栈。 ## 核心能力 - 用于存款、保险流动性、结算和受保护提取的 Solidity `CollateralVault`。 - 具有 USDC 类似 6 位小数的本地/测试 `MockUSDC` token。 - 用于钱包授权链下操作的通用 EIP-712 `SignedIntent` 模型。 - 通过 `X-App-Id` 和 `X-App-Secret` 进行应用授权。 - 通过 bearer token 进行管理员/操作员授权。 - 包含 `settlementId`、`reasonHash`、`referenceIds` 和关联的 `signedIntentIds` 的通用结算 API。 - 连接签名意图、链下引用和链上事件的结算审计报告。 - 用户签名的提取请求加上操作员批准。 - 用于金库事件的区块链索引器。 - 后端状态与智能合约状态之间的对账。 - 带有 Swagger/OpenAPI 文档的 Fastify API。 - 支持 SQLite 的本地持久化，带有用于测试的内存模式。 - WebSocket 事件流。 - 静态操作员控制台。 - 独立的外部客户端集成示例。 - 带有签名订单、头寸跟踪、P&L、费用和链上结算的交易参考应用程序。 ## 架构 ``` flowchart LR Wallet[User wallet] -->|deposit / withdraw tx| Vault[CollateralVault] Wallet -->|EIP-712 SignedIntent| API[Gateway API] ExternalApp[External app] -->|X-App-Id + X-App-Secret| API Operator[Operator/Admin] -->|Bearer token| API subgraph Chain[On-chain layer] Token[MockUSDC local/test token] Vault Events[Vault events] Token --> Vault Vault --> Events end subgraph Gateway[Core gateway] API --> Registry[App Registry] API --> Intent[SignedIntent Service] API --> Settlement[Settlement Service] API --> Withdrawal[Withdrawal Service] API --> Ledger[SQLite / In-memory Ledger] API --> Admin[Admin + Metrics] API --> WS[WebSocket Events] Indexer[Blockchain Indexer] --> Ledger Reconciliation[Reconciliation Service] --> Ledger Events --> Indexer Settlement -->|settle delta| Vault Withdrawal -->|request / approve| Vault end subgraph Examples[Reference apps] Trading[Trading Example] ExternalClient[Standalone External Client] Trading --> Settlement ExternalClient --> API end subgraph UI[Operator UI] Console[Operator Console] Console --> API end ``` 后端布局： ``` backend/src/ core/ auth/ # Signed intents, app registry, admin auth blockchain/ # Vault event indexing collateral/ # collateral-facing routes and contract metadata settlement/ # generic settlement service and audit reports withdrawals/ # signed withdrawal request and approval flow reconciliation/ # on-chain/off-chain state comparison storage/ # memory and SQLite repositories websocket/ # realtime event hub money/ # centralized money conversion helpers risk/ # reusable risk checks examples/ trading/ # trading reference application demo/ # local walkthrough helpers admin/ # metrics, recent records, system health ``` ## 网关流程 1. **存入抵押品** — 用户将测试抵押品存入 `CollateralVault`。 2. **索引事件** — 后端索引器观察金库事件并更新网关账本。 3. **签署意图** — 用户通过 EIP-712 `SignedIntent` 授权链下操作。 4. **运行应用逻辑** — 外部应用或参考模块执行快速的链下业务逻辑。 5. **提交结算** — 应用发送带有相关签名意图的授权结算请求。 6. **应用链上增量** — 网关将最终余额增量提交给金库。 7. **生成审计报告** — 结算可以通过 `settlementId`、`reasonHash`、引用、签名意图和交易哈希进行追踪。 8. **请求提取** — 用户签署提取意图；操作员在风险检查后批准它。 9. **对账** — 管理员端点比较后端账本状态和金库状态。 ## 交易参考应用程序 交易模块在具体的金融工作流中演示了网关模式： - 用户存入抵押品； - 用户签署交易订单意图； - 后端在链下执行市价订单； - 计算 P&L 和费用； - 提交带有相关意图 ID 的 `TRADING_PNL` 结算； - 金库在链上应用结果； - 结算报告连接交易、签名意图和交易数据。 交易模块有意被限定为一个参考应用程序。它不是一个完整的交易所、订单簿、清算引擎或永续期货平台。 ## 仓库结构 ``` contracts/ Solidity contracts backend/src/core/ Gateway core modules backend/src/examples/trading/ Trading reference app backend/src/admin/ Operator/admin endpoints backend/src/demo/ Local walkthrough helpers dashboard/ Static Operator Console examples/external-client/ Standalone integration example scripts/ Deployment, demo, reset, report scripts test/ Contract, backend, and end-to-end tests docs/ Architecture, operations, deployment, security, use cases .github/ CI workflow and contribution templates ``` ## 要求 - Node.js 22+ - npm 10+ - Linux/macOS shell 或 WSL - 本地端口： - `8545` 用于 Hardhat JSON-RPC - `3000` 用于后端/API/控制台 ## 快速开始 ``` npm ci cp .env.example .env ``` 终端 1： ``` npm run chain ``` 终端 2： ``` npm run deploy:local npm run dev ``` 有用的 URL： ``` Health: http://localhost:3000/health Swagger UI: http://localhost:3000/docs OpenAPI JSON: http://localhost:3000/openapi.json Dashboard: http://localhost:3000/dashboard ``` 运行完整的本地流程： ``` npm run demo:e2e ``` 运行独立的外部应用集成示例： ``` npm run example:external-client ``` ## 常用命令 ``` npm run format:check npm run lint npm run build npm run test:contracts npm run test:backend npm run test:e2e npm test npm audit --audit-level=critical --omit=dev ``` 重置本地状态： ``` npm run local:reset ``` 从 CLI 生成结算报告： ``` npm run settlement:report -- ``` ## 环境配置 从 `.env.example` 开始： ``` PORT=3000 HOST=0.0.0.0 RPC_URL=http://127.0.0.1:8545 CHAIN_ID=31337 CONTRACTS_FILE=backend/src/generated/contracts.json GATEWAY_ADMIN_TOKEN=change-me-admin-token REGISTERED_APPS=trading-example:change-me-trading-secret,fantasy-trading-app:change-me-external-secret STORAGE_DRIVER=sqlite SQLITE_PATH=backend/data/app.db ENABLE_DEMO_ROUTES=false ``` 重要说明： - `backend/src/generated/contracts.json` 由部署脚本生成，不应提交。 - `backend/src/generated/contracts.example.json` 是一个安全的占位符。 - `MockUSDC` 仅用于本地/测试 token。 - 默认密钥仅供本地开发使用；在任何共享环境中替换它们。 ## API 认证 管理员/操作员端点需要： ``` Authorization: Bearer ``` 外部应用结算需要管理员身份验证或应用凭据： ``` X-App-Id: fantasy-trading-app X-App-Secret: change-me-external-secret ``` 对于应用授权的结算： - `appId` 必须与 header 匹配； - `settlementType` 必须对该应用允许； - `signedIntentIds` 是必需的； - 每个关联的意图都必须经过验证、未过期、未被消耗、由同一用户拥有，并在同一应用下注册。 ## API 示例 管理员指标： ``` curl -H "Authorization: Bearer change-me-admin-token" \ http://localhost:3000/admin/gateway-metrics ``` 结算报告： ``` curl http://localhost:3000/settlements//report ``` 应用授权结算体： ``` { "userAddress": "0x0000000000000000000000000000000000000001", "appId": "fantasy-trading-app", "settlementType": "EXTERNAL_APP_REWARD", "amountDelta": "+25", "reasonHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "referenceIds": ["round-001"], "signedIntentIds": ["intent_abc123"], "metadata": { "source": "external-client-example" } } ``` 用户签名的提取请求： ``` { "userAddress": "0x0000000000000000000000000000000000000001", "amount": 1000, "signedIntentId": "intent_withdrawal_123" } ``` ## 操作员控制台 控制台访问地址： ``` http://localhost:3000/dashboard ``` 选项卡： - **网关概览** — 系统健康状况、链、金库、索引器、抵押品、保险、负债和运营指标。 - **结算审计** — 通过 `settlementId` 查找、关联意图、原因哈希、交易数据。 - **对账** — 比较后端账本和金库状态。 - **交易示例** — 参考交易工作流和当前示例状态。 - **演示演练** — 仅限本地的引导流程；除非 `ENABLE_DEMO_ROUTES=true`，否则禁用。 ## 部署概述 对于本地开发，使用 Hardhat + Fastify： ``` npm run chain npm run deploy:local npm run dev ``` 对于服务器部署，使用部署指南： - [部署指南](docs/deployment.md) - [操作指南](docs/operations.md) - [安全模型](docs/security-model.md) 生产样式的高层级步骤： 1. 准备一台 Linux 主机； 2. 安装 Node.js 22+ 和 npm； 3. 配置受管理的 RPC endpoint； 4. 通过环境变量或密钥管理器配置密钥； 5. 部署或指向合约； 6. 在带有 TLS 的反向代理后运行后端； 7. 在 systemd 或进程监控程序下运行进程； 8. 禁用演示路由； 9. 设置真实的管理员 token 和应用凭据； 10. 监控索引器延迟、对账状态、结算失败和金库流动性。 ## 测试网部署 支持的脚本： ``` npm run deploy:sepolia npm run deploy:arbitrum-sepolia npm run verify:sepolia npm run verify:arbitrum-sepolia ``` 测试网部署是一个开发者工作流。它并不能使系统适合真实资金。 ## 质量检查 预计该项目可以通过： ``` npm ci npm run format:check npm run lint npm run build npm test npm run test:e2e npm audit --audit-level=critical --omit=dev ``` `.github/workflows/ci.yml` 下包含了一个 GitHub Actions 工作流。 ## 安全模型 当前模型是明确的： - 用户持有钱包并签署链下意图； - 抵押品保存在金库合约中； - 外部应用在提交结算前需经过身份验证； - 管理员/操作员端点需要 bearer 授权； - 结算由操作员提交，并可通过报告进行审计； - 提取需要用户签名的意图以及操作员批准； - 对账可检测后端/链上的不匹配。 该系统是**可审计的，而非无信任的**。操作员仍然受信任以提交正确的结算。在没有智能合约审计、后端安全审查、更强的密钥管理、稳健的监控和正式的操作程序的情况下，请勿使用真实资金。 参见 [SECURITY.md](SECURITY.md) 和 [docs/security-model.md](docs/security-model.md)。 ## 已知限制 - 受信任的操作员结算模型。 - 无去中心化争议解决。 - 无智能合约审计。 - 无后端安全审计。 - 基于环境变量的应用注册表；生产环境应使用带有哈希密钥和轮换的受管注册表。 - SQLite 持久化用于本地/参考用途。 - 为了开发者清晰起见，存储中保留了一些可读的十进制字段；原生的 token 合约调用使用 microUSDC 单位。 - 无生产级 oracle 策略。 - 无清算引擎。 - 无完整订单簿。 - 无高可用性部署。 - 演示路由是本地演练辅助工具，在受控环境之外必须保持禁用。 ## 路线图 参见 [ROADMAP.md](ROADMAP.md)。未来的关键方向： - 端到端定点整数存储； - Postgres 迁移和操作备份； - 数据库管理的应用注册表，支持密钥轮换； - 针对管理员/操作员访问的 RBAC； - 多重签名或治理的操作员签名者； - 结算批处理和审查窗口； - 带有新鲜度/置信度约束的 oracle 策略； - 索引器重组处理和确认深度； - 监控和报警； - 智能合约审计和后端安全审查。 ## 项目定位 **简短版本** 抵押品结算网关是可重用的 Web3 基础设施，适用于需要快速链下逻辑，同时保持抵押品托管和最终结算锚定在链上的应用。 **技术版本** 该系统结合了 Solidity 金库、EIP-712 签名意图、应用身份验证结算、经过审计的 reason hash、操作员批准工作流、对账以及交易参考应用程序，以演示混合金融产品如何将速度与最终确定性分离开来。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。

标签：EIP-712, MITM代理, Solidity, Web3, 区块链后端, 智能合约, 结算系统, 自动化攻击, 金融基础设施