tanka420/arcready

# ArcReady 针对钱包、桥接器、App Kit 集成和 dApp 的 Arc 专用静态 CI 质量门控和集成模式验证器。 [](https://github.com/tanka420/arcready/actions/workflows/arcready-example.yml) [](https://github.com/tanka420/arcready/releases)     ArcReady 可帮助开发者在发布前捕获常见的 Arc 集成错误。它是用于本地工作流和 CI 中静态检查的开发者侧早期预警层。 ## 它是什么 ArcReady 会扫描源文件，检查三种预设下常见的 Arc 专用集成假设： - `wallet` - `bridge` - `app-kit` 它会以终端、JSON、Markdown 或 HTML 格式报告检查结果，并可以根据 `critical`、`warning`、`info` 或 `none` 阈值使 CI 失败。 ## 快速演示 ``` npx --yes arcready@0.3.0 init npx --yes arcready@0.3.0 scan ``` 面向 CI 的 Markdown 报告： ``` npx --yes arcready@0.3.0 scan --format markdown --out arcready-report.md ``` 简化版示例输出： ``` ArcReady v0.3.0 Project: my-arc-app Score: 75 Status: fail Summary: 1 critical, 0 warning, 0 info ``` ## 快速开始 无需安装直接运行： ``` npx --yes arcready@0.3.0 scan ``` 创建配置文件： ``` npx --yes arcready@0.3.0 init ``` 本地安装： ``` npm install -D arcready npx arcready scan ``` ## GitHub Action 最小工作流： ``` name: ArcReady on: pull_request: push: branches: [main] jobs: arcready: runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v4 - uses: tanka420/arcready@v0.3.0 with: fail-on: critical ``` 该 action 会运行已发布的 npm CLI，且默认使用 `arcready@0.3.0`。你可以固定或覆盖该 CLI 包的版本： ``` with: arcready-version: "0.3.0" ``` 请参阅 [docs/github-action.md](docs/github-action.md) 了解输入、artifact 行为和外部使用说明。 ## ArcReady 检查的内容 ### Wallet - Arc 链元数据 - 原生 USDC 显示 - 避免关于 ETH gas 标签的假设 - 单次确认（one-confirmation）最终性假设 - 不受支持的 PREVRANDAO 假设 - Blob 交易假设 ### Bridge - 单次确认（one-confirmation）桥接假设 - CCTP 域 `26` - 原生 USDC 与封装版 USDC 的假设 - 中继器（Relayer）gas token 假设 - 可重试的 CCTP attestation `404` 处理 - 避免关于 PREVRANDAO 中继选择的假设 ### App Kit - `Arc_Testnet` / Arc 链标识符的使用 - 能力防护（Capability guardrails） - 显式 RPC 配置 - 用户可控的钱包委托（Delegate）处理 - 面向用户的费用说明 - 桥接最小金额提示文案 ArcReady 仅检查静态集成模式。它不会在 runtime 验证 Circle SDK 或 App Kit。 ## 示例输出 ``` CRITICAL (1) - wallet/ONE_CONFIRMATION_FINAL Message: Arc wallet transaction flow appears to wait for more than one confirmation. Files: src/wallet.ts Suggested fix: Set Arc confirmation waits and release logic to 1 confirmation. ``` ## 报告 支持的格式： - 终端 - JSON - Markdown - HTML ``` npx --yes arcready@0.3.0 scan --format terminal npx --yes arcready@0.3.0 scan --format json --out arcready-report.json npx --yes arcready@0.3.0 scan --format markdown --out arcready-report.md npx --yes arcready@0.3.0 scan --format html --out arcready-report.html ``` 生成的报告文件夹（如 `.arcready/` 和 `reports/`）会被 git 忽略。 ## ArcReady 不做的事 ArcReady 不会执行： - 实时的 Arc RPC 检查 - Circle API 检查 - 链上交易模拟 - 合约部署验证 - 桥接 runtime 模拟 - 真正的 App Kit runtime 验证 - SaaS/仪表盘监控 它是一个静态 CI 质量门控，而不是 runtime 验证器或兼容性保证。 ## 为什么会有这个项目 Arc 兼容 EVM，但 Arc 集成不应盲目继承 Ethereum 的默认假设。开发团队可能会不小心发布错误的 gas 标签、最终性等待、CCTP 域值、封装资产假设或 App Kit 配置错误。 ArcReady 会将这些常见的集成风险转化为本地和 CI 检查。 ## 配置基础 在你要扫描的项目中创建 `arcready.config.json`： ``` { "presets": ["wallet", "bridge", "app-kit"], "paths": ["src", "app", "components", "lib", "package.json"], "exclude": ["dist/**", "coverage/**", ".next/**", "node_modules/**"], "reporters": ["terminal", "json", "markdown", "html"], "failOn": "critical", "rules": { "wallet/ONE_CONFIRMATION_FINAL": "critical", "bridge/BRIDGE_CONFIRMATIONS_ONE": "critical", "app-kit/APPKIT_CHAIN_IDENTIFIER_VALID": "critical" } } ``` ### CI 行为 `failOn` 控制何时让 CLI 以非零状态退出： | 值 | 行为 | | --- | --- | | `critical` | 仅当存在严重（critical）发现时失败 | | `warning` | 当存在警告（warning）或严重（critical）发现时失败 | | `info` | 当存在任何发现时失败 | | `none` | 永远不会因为发现而失败 | CLI 的 `--fail-on` 选项会覆盖配置值。 ## 预设 | 预设 | 关注点 | 示例规则 | | --- | --- | --- | | `wallet` | Wallet UX、链元数据、费用显示、最终性 | `ARC_CHAIN_METADATA`、`NO_ETH_GAS_LABEL`、`ONE_CONFIRMATION_FINAL` | | `bridge` | CCTP、最终性、中继器（relayer）gas、原生 USDC | `BRIDGE_CONFIRMATIONS_ONE`、`CCTP_DOMAIN_26`、`RELAYER_USES_USDC_FOR_GAS` | | `app-kit` | App Kit 链标识符、能力防护、统一余额（Unified Balance）UX | `APPKIT_CHAIN_IDENTIFIER_VALID`、`APPKIT_CAPABILITY_SUPPORTED`、`UB_FEE_EXPLANATION_PRESENT` | 完整规则列表：[docs/rule-catalog.md](docs/rule-catalog.md) 演示项目：使用[错误的 Arc 集成](examples/demo-projects/broken-arc-integration)和[修复后的 Arc 集成](examples/demo-projects/fixed-arc-integration)作为静态修复工作流的修复前后状态。 ## 验证测试夹具（Validation Fixtures） ArcReady 包含用于 wallet、bridge 和 App Kit 集成的好坏测试夹具： ``` corepack pnpm validate:fixtures ``` 好的测试夹具应该通过检查且没有任何发现。坏的测试夹具应该产生发现，并根据其预期结果使检查失败。 ## 独立声明 ArcReady 是一个独立的开源项目。它不是官方的 Circle 或 Arc 产品，其静态检查结果应被视为开发者侧的发布检查，而非官方验证。 ## 许可证 MIT

标签：MITM代理, TypeScript, Web3, 代码质量检查, 区块链, 安全插件, 暗色界面, 聊天机器人, 自动化攻击, 错误基检测, 静态代码分析