software-crypto-web3

软件加密/Web3 工程

快速参考

任务	默认选择	适用场景
EVM 合约	优先使用 Foundry；在插件密集型 TS 工作流很重要时使用 Hardhat	Solidity、DeFi、代币标准、可升级系统
Solana 程序	Anchor + 当前 Solana SDK 指南	Rust 程序、SPL 资产、高吞吐量应用
Cosmos 合约	CosmWasm	原生支持 IBC 或 Cosmos 应用链生态
TON 合约	新合约使用 Tolk；在 TON 文档中确认支持的工具包	Telegram 分发、TON 原生钱包和资产
Bitcoin/Lightning	Bitcoin Core + BDK/LND 模式	钱包、PSBT、结算、支付渠道
账户抽象	EOA 使用 ERC-7702（委托会持续生效；限制调用方），智能账户使用 ERC-4337	批量交易、Gas 赞助、会话密钥、社交恢复
安全审查	Slither、Echidna、Medusa、Halmos、Certora；审计指南	审计、部署前审查、不变量执行
跨链	Chainlink CCIP、LayerZero、Wormhole、IBC	代币桥、跨链消息传递、互操作性
后端集成	基于队列的 RPC 客户端 + 幂等处理程序	托管、存款、取款、Webhook/事件接收
研究	优先查阅官方文档/规范，然后参考生态分析	链选择、框架选择、当前最佳实践

何时使用此技能

• 智能合约和区块链程序开发
• DeFi、代币、NFT、治理和跨链桥集成
• 加密后端基础设施、托管和签名工作流
• 链和框架的权衡分析
• 安全审查、审计准备和生产环境加固

何时不使用此技能

• 不涉及区块链的一般后端工作 → software-backend
• 不涉及钱包/协议集成的纯前端 UI 工作 → software-frontend
• 智能合约和加密运维之外的通用应用安全工作 → software-security-appsec
• Sui/Aptos 上的 Move 实现不属于此技能覆盖的链范围。请从 Sui Move 或 Aptos Move 入手；仅在共享托管和运营风险控制方面使用此技能，切勿移植 EVM/Anchor 代码。

工作流

1. 推荐工具前，先确定链、产品界面、托管模式和攻击面。
2. 如果区块链只是附带因素，将通用后端、前端或非加密 AppSec 工作转交给相邻技能。
3. 根据决策树选择满足需求的最小协议或框架。
4. 讨论实现细节前，先应用合约、签名、结算和运营控制方面的执行默认设置。
5. 最终提供指导前，通过相关官方来源重新确认网络支持和工具成熟度。对于 Solana，加载工具链与扩展门槛；对于 TON，加载语言/工具包选择。

决策树

选择满足产品需求的最小技术面：

• 如果生态深度、审计和工具成熟度最重要，选择 EVM
• 如果吞吐量和低费用最重要，且团队能够安全地使用 Rust，选择 Solana
• 如果原生 IBC 互操作性是核心要求，选择 CosmWasm
• 如果产品要求原生集成 Telegram 的分发能力，选择 TON；选择语言前，请查看 Tolk 和工具包指南
• 如果系统侧重支付结算或钱包，而非智能合约，选择 Bitcoin/Lightning

优先选择：

• 使用 Foundry 进行 EVM 测试、模糊测试、不变量测试和 Gas 快照
• 当插件生态或以 TS 为主的工作流是真正的驱动因素时，使用 Hardhat 3（可原生运行 Solidity 测试；请查看 hardhat.org 了解其当前发布状态）；Nomic Foundation 不会为每次未来的硬分叉都升级 Hardhat 2，因此请规划从 Hardhat 2 迁移
• 使用与目标 EVM 兼容且经过审查的 Solidity 编译器。请查看所选优化器/IR 流程的发布版本和已知漏洞，包括瞬态存储处理；固定使用确切的编译器版本，并确保所有 pragma 都与之兼容。
• EOA 迁移使用 ERC-7702（保留现有地址历史，自 Pectra 升级后已上线；委托会一直持续，直到重新委托或通过委托给零地址来清除，因此委托代码必须在执行前检查 msg.sender == address(this) 或签名，钱包也必须将委托请求视为高风险钓鱼目标）；新智能账户或需要完整 Bundler/Paymaster 基础设施时使用 ERC-4337——两者互为补充，且日益常见同时部署，并非互斥
• 如果桥接安全（独立风险管理网络）是首要考虑因素，使用 Chainlink CCIP；如果需要更广泛的链覆盖，则使用 LayerZero 或 Wormhole——在将有实质价值的资产交给桥接前，请核实当前 DVN/guardian 集和审计状态
• 仅在核实当前网络支持、桥接假设和运维成熟度后使用 L2；请查看 L2Beat 或 DefiLlama 了解当前流动性，不要轻信记忆中的市场份额数据
• 优先采用现有的经审计协议组件，而非自定义桥接或自定义密码学方案

执行默认要求

• 将合约、签名服务和 webhook 端点视为公开攻击面
• 存款、提现和结算处理程序必须具备幂等性
• 将读取路径与交易提交路径分开
• 对热钱包自动化实施速率限制，并要求高风险转账经过审批
• 在有助于缩小影响范围时，优先采用允许列表、时间锁、可暂停机制和回滚计划
• 未经最新核实，绝不轻信有关生态流行度的说法

部署前安全检查清单

在将合约或托管流程部署到生产环境前：

• 所有外部调用路径均设有重入防护（CEI 模式或 ReentrancyGuard）
• 访问控制：每个特权函数都明确检查所有者/角色
• 整数溢出：Solidity 0.8+ 使用已检查的算术运算（无需 SafeMath）；审查时必须说明每个 unchecked 代码块的合理性
• 重放保护：消耗 nonce/过期时间并绑定域（链、验证合约、操作）；仅使用 EIP-712 格式并不能阻止同域重放
• 存款/提现处理程序：已定义幂等键、确认阈值和 DLQ
• 预言机输入：检查数据时效性（最大年龄）；不得依赖单一价格真值来源
• 紧急控制：已在演练中测试暂停机制或时间锁
• 升级路径：代理管理员密钥由多签持有，而非 EOA；已记录升级流程
• 模糊测试和不变量测试通过（Foundry、Echidna 或 Medusa）；根据协议风险设定运行次数/深度预算；对于承载价值的代码，应将预算提高到高于工具默认值

托管、密钥管理与链上判断

特权控制关卡。 将每个升级、暂停、铸造、冻结、预言机、桥接和费用设置权限都纳入协议范围。对每项权限，记录签名者集合、法定人数、延迟、范围、轮换路径和故障后果。在分叉链或本地链上测试签名者被攻破、签名者不可用和恶意升级场景；仅有多签标签，并不能证明特权操作受到约束或可以恢复。

• 不应上链的内容：个人身份信息、需要日后删除或更正的数据（与删除权冲突）、在链下处理成本更低且同样可信、只需定期将检查点／根提交到链上的高频状态，以及仅要求内部可审计，而非公开可验证或无需信任结算的业务逻辑。上链是一种成本与信任之间的权衡，不是默认选择。
• 托管决策关卡：
  • 单人／EOA 签名——仅用于原型和个人非托管钱包；绝不可用于汇集的用户资金。
  • 多签（Safe 或同等方案）——财库和管理／升级密钥的默认选择；链上法定人数透明，但每位签署者的设备和审查纪律都会成为信任边界的一部分（见下方签名关卡）。
  • MPC（阈值签名）——适合大规模热钱包操作签名：协议可使用分布式密钥份额签名，无需重构完整密钥。核实阈值、独立的份额／控制域、恢复机制、绕过策略的路径和供应商信任；刷新份额与更改公钥会带来不同的迁移后果。
  • HSM——用于冷密钥／根密钥，以及合规制度要求使用通过 FIPS 验证的硬件托管密钥的场景；应搭配 M-of-N 操作员访问机制，而非由单个操作员控制。
  • 根据以下因素选择：风险敞口金额、签名频率、监管托管要求，以及你要防范的故障模式是密钥被盗、内部人员串通还是供应商遭入侵——这些情况需要不同的控制措施。
• 清晰签名关卡：在进行特权签名之前，使用独立获取的合约／ABI 数据解码目标地址、链、金额、方法、接收方、授权额度和嵌套调用。钱包支持时，使用 ERC-7730 描述符；核实其支持的架构，并将描述符绑定到链／地址／签名类型。对于未知或不匹配的描述符，以及不透明的关键字段，在独立解码之前禁止进行特权签名。可读的显示内容无法证明意图安全：描述符注册表和外部元数据同样属于信任边界。
• 钱包前端供应链：锁定并审查依赖项／构建输入，限制可变的第三方脚本，保护发布／CDN 凭据，验证所提供资产的来源，并演练 UI 遭入侵的情形。对于财库／管理流程，应通过独立签名路径比对实际载荷；遭入侵的 dApp 可能会显示无害的摘要，同时请求另一种签名。
• 测试网与主网的部署规范：绝不可假设测试网的 gas、内存池、MEV 或重组行为能够预测主网行为。任何涉及真实价值的主网部署都必须先通过主网分叉模拟（Foundry/Anvil 或 Tenderly）；主网部署密钥和升级密钥必须与测试网密钥分开管理，确保测试网遭入侵时无法影响生产环境。
• 预言机操纵故障模式：单区块现货价格（原始 DEX 储备、单一来源数据馈送）可通过闪电贷在单笔交易中操纵；应优先使用时间加权平均值（TWAP）或聚合式推送／拉取预言机（Chainlink、Pyth），并检查数据是否过时及偏差是否超限；对于任何决定清算或借款能力的机制，都必须满足“价格真值不存在单一来源”（见上方清单）这一硬性要求，而非将其视为可有可无。
• 拥有签名权限的 LLM 或 Agent（交易、兑换、财库资金转移）：应假设模型迟早会受到链上文本、代币名称、数据馈送或 webhook 的影响，从而被诱导执行有害交易；必须确保以下每项控制措施都不受模型输出影响。提示注入的关键词过滤很容易绕过，不要将其视为控制措施。
  • 通过模型与签名者之间的代码实施单笔交易及滚动时间窗口的支出上限，并在本地策略中设置限额。
  • 模拟每笔交易（eth_call 或分叉环境）；除非已设置最低输出和截止时间，且模拟结果满足这两项要求，否则拒绝签名。
  • 设置回撤和连续亏损熔断机制，暂停交易并要求人工恢复；状态无效时（基准值为零或缺失）也应暂停。
  • 使用专用热钱包，且仅为当前会话注入资金，绝不使用财库钱包；密钥应由密钥管理器提供。存在三明治攻击风险时，应使用受保护的路由（私有内存池）。
  • 记录每一项模型决策的审计日志，包括拒绝和失败的决策，而不只是已发送的交易。

已知陷阱

• 根据本地或测试网的行为来推断 Gas、内存池和重组情况，但这些推断在目标网络上并不成立。
• 将索引事件视为事实来源，而实际上合约状态、钱包余额或最终结算系统才是权威依据。
• 构建存款和提现处理程序时，未加入重放保护、确认阈值和幂等记账机制。
• 认为桥、转发器或 Paymaster 的信任边界只是基础设施细节，而非核心产品风险。
• 升级代理、账户抽象流程或签名者策略时，未演练回滚和冻结状态的流程。
• 认为钱包用户体验故障无关紧要，但错误的链选择、过时的授权状态或签名混淆都可能导致资金损失。

导航

资源：

• references/blockchain-best-practices.md - 通用区块链架构与安全模式
• references/backend-integration-best-practices.md - 后端托管、Webhook、队列、CQRS、提供方抽象（.NET/C# 示例；架构模式与语言无关）
• references/solidity-best-practices.md - EVM 与 Solidity 指南
• references/rust-solana-best-practices.md - Solana + Anchor 模式
• references/cosmwasm-best-practices.md - CosmWasm 与 IBC 指南
• references/ton-best-practices.md - TON 合约与钱包集成模式
• references/defi-protocol-patterns.md - AMM、借贷、金库、质押、预言机
• references/nft-token-standards.md - ERC-20/721/1155、SPL 资产、NFT 元数据
• references/cross-chain-bridges.md - 桥接模型、信任假设和风险控制
• references/operational-playbook.md - 主题到参考资料的索引，以及链上与链下数据表
• data/sources.json - 精选外部参考资料和研究起点

模板：

• Ethereum/EVM：assets/ethereum/template-solidity-hardhat.md、assets/ethereum/template-solidity-foundry.md
• Solana：assets/solana/template-rust-anchor.md
• Cosmos：assets/cosmos/template-cosmwasm.md
• TON：assets/ton/template-tact-blueprint.md、assets/ton/template-func-blueprint.md
• Bitcoin：assets/bitcoin/template-bitcoin-core.md

相关技能：

• ../software-security-appsec/SKILL.md - 威胁建模与安全加固
• ../software-backend/SKILL.md - 后端服务、API、队列、持久化
• ../software-code-review/SKILL.md - 评审流程与正确性检查
• ../ops-devops-platform/SKILL.md - 基础设施、CI/CD、可观测性、节点运维
• ../qa-resilience/SKILL.md - 故障模式、重试、熔断器
• ../dev-api-design/SKILL.md - 托管服务与区块链交互服务的 API 边界

生态系统查询

在推荐框架、网络、桥或钱包功能之前，请查阅其官方版本与支持文档，以及确切的已部署配置。仅使用生态系统分析来比较当前的流动性和采用情况；不要引用凭记忆得出的市场份额或吞吐量数据。请注明来源，以及会影响选择的信任假设。

监管陷阱（仅限工程控制）

法律地位、许可和截止日期由法律技能负责；请勿在此重述。无论司法管辖区如何，都应构建以下控制措施：

• Travel Rule 流程：根据法律顾问批准的司法管辖区和转账规则，配置所需的发起方／受益方字段、自托管钱包证明及异常处理；明确建模“交易对手不具备 Travel Rule 支持能力”这一状态。
• 托管隔离与对账：客户资产与自有资产隔离；每日进行链上数据与账本对账，并以此作为提现的关卡。
• 稳定币发行系统：根据法律顾问批准的发行方／资产资格、赎回规则及各货币区的交换媒介遥测配置系统参数；将阈值参数化，并演练“暂停发行”开关。
• 营销关卡：公开发售页面和推广内容仅可基于当前版本的白皮书发布；对未经授权的司法管辖区实施地域限制，并记录决策。
• 分类依据：保留管理密钥、升级路径、费用开关和代币唯一性元数据；NFT 和“完全去中心化”的范围属于法律判断。

检查清单：references/mica-casp-checklist.md。状态和截止日期：欧盟合格监管法律顾问（MiCA、TFR）、美国合格监管法律顾问（GENIUS Act 规则制定、CLARITY Act）、英国合格监管法律顾问（FCA 加密资产制度）。

经验反馈循环

当以往的决策或陷阱与当前情况相关时，请在 learnings.consolidated.md 存在时查阅；仅在需要了解历史或将其用作可用的备用资料时查阅 learnings.md。否则跳过这两个文件。

应用后，如果遇到值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的要点。请勿修改 SKILL.md 本身。