ship

发布一个 dApp

你可能做错了什么

你没做规划就开始写代码。 在写第一行 Solidity 之前，你需要弄清楚：哪些内容放在链上，哪些留在链下，选择哪条链，需要多少个合约，以及谁会调用每个函数。跳过这一步，你就得把所有东西重写一遍。

你过度设计了。 大多数 dApp 只需要 0–2 个合约。发行代币需要 1 个合约。NFT 系列需要 1 个合约。使用现有 DEX 流动性的市场不需要合约。MVP 最多需要 3 个合约。如果你写的更多，那就是做得太多了。

你把太多东西放到了链上。 Solidity 用于所有权、转账和承诺。它不是数据库，不是 API，也不是后端。如果不涉及无需信任的价值转移或永久承诺，就不该放进智能合约。

你跳过了链的选择。 主网比你想象的便宜——ETH 转账约需 $0.004，兑换约需 $0.04。“以太坊很贵”这一说法已经过时。但这并不意味着所有东西都该放在主网上。L2 不只是“更便宜的以太坊”——每条链都有独特优势（Base 拥有 Coinbase 的分发渠道和智能钱包，Arbitrum 拥有最深厚的 DeFi 流动性，Optimism 拥有 retroPGF 和 Superchain）。如果你的应用需要高频交互，或适合 L2 的独特优势，就在 L2 上构建。如果你只需要低成本和安全性，主网就可以。请谨慎选择。获取 l2s/SKILL.md 和 gas/SKILL.md，了解全貌。不确定以太坊是否适合你的需求？获取 why/SKILL.md。

你满足于“能用”，跳过了 CROPS 权衡。 dApp 可以通过编译和测试，却仍然让用户依赖可被审查的前端、私有索引器/API、不可见的 RPC 依赖、托管钱包，或拥有完全控制权的管理员密钥。在编码之前，检查设计对抗审查、开源与自由（自由意义上的自由）、隐私和安全的影响。

你忘了没有任何事情会自动发生。 智能合约不会自行运行。每次状态转换都需要有人调用并支付 Gas，也需要一个调用理由。如果你无法回答每个函数的“谁会调用它，为什么调用？”，那么合约中就有死代码。获取 concepts/SKILL.md，了解完整的思维模型。

---

阶段 0 — 规划架构

务必在编写任何代码之前完成这一步。在这里花的每个小时，都能省下十个小时的返工。

CROPS 检查关卡

敲定架构之前，先进行 CROPS 检查。CROPS 指对抗审查、开源与自由（自由意义上的自由）、隐私和安全。

使用简短检查，找出主要权衡：

• 对抗审查： 谁能阻止用户或关键应用路径？
• 开源与自由： 整个技术栈能否被检查、分叉、可自托管且合法复用？
• 隐私： 哪些用户活动或身份数据会公开或被第三方看到？
• 安全： 谁控制资金、权限、升级、紧急权力、恢复和退出？

明确选定的默认方案、主要妥协，以及用户的退出路径。

敲定架构之前，获取 crops/SKILL.md，对任何 dApp 进行深入审查。另行获取 concepts/SKILL.md，了解激励设计和“没有任何事情会自动发生”。

链上判断标准

如果涉及以下内容，就放到链上：

• 无需信任的所有权 —— 谁拥有这个代币／NFT／头寸？
• 无需信任的交易 —— 兑换、交易、借贷
• 可组合性 —— 其他合约需要调用它
• 抗审查性 —— 即使你的团队消失，也必须能正常运行
• 永久承诺 —— 投票、证明、凭证

如果涉及以下内容，就放到链下：

• 用户资料、偏好设置、配置
• 搜索、筛选、排序
• 图片、视频、元数据（存储在 IPFS 上，在链上引用）
• 频繁变更的业务逻辑
• 不涉及价值转移或信任的任何内容

需要酌情判断的情况：

• 声誉分数 → 链下计算，链上承诺（哈希或凭证）
• 活动动态 → 对链上事件进行链下索引（获取 indexing/SKILL.md）
• 价格数据 → 由链下预言机写入链上（Chainlink）
• 游戏状态 → 取决于 stakes。真钱扑克？放到链上。排行榜？放到链下。

MVP 合约数量

你要构建的内容	合约数量	模式
代币发行	1	带自定义逻辑的 ERC-20
NFT 系列	1	带铸造／元数据功能的 ERC-721
简单市场	0-1	使用现有 DEX；也可以添加一个挂单合约
金库／收益	1	ERC-4626 金库
借贷协议	1-2	资金池 + 预言机集成
DAO／治理	1-3	Governor + 代币 + timelock
AI Agent 服务	0-1	也可以使用 ERC-8004 注册
预测市场	1-2	市场 + 结果判定预言机

如果 MVP 需要超过 3 个合约，那就是过度构建。 先发布能运行的最简单版本，再迭代。

状态转换审计

针对合约中的每个函数，填写以下工作表：

Function: ____________
Who calls it? ____________
Why would they? ____________
What if nobody calls it? ____________
Does it need gas incentives? ____________

如果「万一没人调用它？」会导致系统崩溃，那就是设计问题。先解决问题，再编写代码。请参阅 concepts/SKILL.md，了解激励设计模式。

链选择

主网重新成为可选项。 大多数 AI 仍认为主网费用高——事实并非如此（按当前 Gas 价格，每笔转账约 $0.004，每次兑换约 $0.04）。主网能提供最高程度的去中心化、无需信任排序器、没有桥接风险，并且能与所有主要协议组合使用。不过，L2 并非退而求其次——每个 L2 都有其独特优势。选择与你的应用优势相匹配的链：

链	独特优势	适合在此构建的情况……
Ethereum 主网	最高程度的去中心化，可与所有主要协议组合使用	DeFi、治理、身份、高价值转账，或你只需要「低成本 + 安全」
Base	Coinbase 分发、智能钱包、账户抽象	消费级应用、社交、引导非加密用户、高频小额支付
Arbitrum	最深厚的 L2 DeFi 流动性、Stylus（Rust 合约）	需要与现有 Arbitrum 流动性组合使用的 DeFi 协议
Optimism	RetroPGF、Superchain 生态系统	公共产品、OP Stack 生态项目
zkSync / Scroll	ZK 证明、原生账户抽象	隐私功能、原生采用 ZK 的应用

不要因为「主网费用高」就选择 L2。选择 L2，是因为它的独特优势适合你的应用。

获取 l2s/SKILL.md 和 gas/SKILL.md，查看包含实际成本和部署差异的完整对比。

---

dApp 架构模板

在下方找到你的架构类型。每种类型都会明确说明所需的合约数量、合约的用途、常见错误，以及需要获取哪些技能文件。

1. 代币发行（1-2 个合约）

**架构：**一个 ERC-20 合约。如果有团队/投资者配额，则添加一个归属合约。

合约：

• MyToken.sol — ERC-20，包含初始供应量，也可以支持铸造/销毁
• TokenVesting.sol（可选）— 为团队代币设置时间锁定释放

常见错误：

• 无限供应且没有销毁机制（它的价值从何而来？）
• 没有初始流动性计划（部署一个无人能买的代币）
• 转账收费机制破坏 DEX 集成

获取顺序：standards/SKILL.md → security/SKILL.md → testing/SKILL.md → gas/SKILL.md

2. NFT 收藏集（1 个合约）

**架构：**一个 ERC-721 合约。元数据存放在 IPFS 上。提供用于铸造的前端。

合约：

• MyNFT.sol — ERC-721，包含铸造、最大供应量和元数据 URI

常见错误：

• 将图片存储在链上（使用 IPFS 或 Arweave，并将哈希存储在链上）
• 没有最大供应量上限（无限铸造会摧毁价值）
• 在简单的 Merkle root 就能满足需求时，采用复杂的白名单逻辑

获取顺序：standards/SKILL.md → security/SKILL.md → testing/SKILL.md → frontend-ux/SKILL.md

3. 市场 / 交易所（0-2 个合约）

**架构：**如果交易现有代币，可能无需编写任何合约——集成 Uniswap/Aerodrome 即可。如果要构建自定义订单撮合，则需要 1-2 个合约。

合约：

• （通常无需编写合约——通过路由器使用现有 DEX 流动性）
• OrderBook.sol（如需自定义）— 挂单、撮合、结算
• Escrow.sol（如有需要）— 在交易期间托管资产

常见错误：

• 明明可以通过 Uniswap V4 hooks 实现，却从头构建 DEX
• 忽略 MEV（获取 security/SKILL.md，了解如何防范三明治攻击）
• 中心化订单撮合（这违背了设计初衷）

获取顺序：building-blocks/SKILL.md → addresses/SKILL.md → security/SKILL.md → testing/SKILL.md

4. 借贷 / 金库 / 收益（0-1 个合约）

**架构：**如果使用现有协议（Aave、Compound），无需编写合约——只需集成。如果要构建金库，则需要一个 ERC-4626 合约。

合约：

• MyVault.sol — 包装收益来源的 ERC-4626 金库

常见错误：

• 忽略金库通胀攻击（获取 security/SKILL.md）
• 不使用 ERC-4626 标准（会破坏可组合性）
• 将代币精度写死（USDC 是 6，不是 18）

获取顺序：building-blocks/SKILL.md → standards/SKILL.md → security/SKILL.md → testing/SKILL.md

5. DAO / 治理（1-3 个合约）

**架构：**Governor 合约 + 治理代币 + 时间锁。使用 OpenZeppelin 的 Governor，不要从头构建。

合约：

• GovernanceToken.sol — ERC-20Votes
• MyGovernor.sol — 配置了投票参数的 OpenZeppelin Governor
• TimelockController.sol — 延迟执行以确保安全

常见错误：

• 没有时间锁（治理决策立即执行，可能导致项目被卷款跑路）
• 法定人数过低，少数人就能控制治理
• 代币分配过于集中，导致一名巨鲸控制一切

获取顺序：standards/SKILL.md → building-blocks/SKILL.md → security/SKILL.md → testing/SKILL.md

6. AI Agent 服务（0-1 个合约）

**架构：**Agent 逻辑在链下运行。链上组件是可选的——可以是 ERC-8004 身份注册，也可以是用于 x402 的支付合约。

合约：

• （通常无需编写合约——Agent 在链下运行，并使用现有支付基础设施）
• AgentRegistry.sol（可选）— ERC-8004 身份 + 服务端点

常见错误：

• 将 Agent 逻辑放到链上（Solidity 不适合 AI 推理）
• 让支付过于复杂（x402 支持原生 HTTP 支付）
• 忽略密钥管理（获取 wallets/SKILL.md）

获取顺序：standards/SKILL.md → wallets/SKILL.md → tools/SKILL.md → orchestration/SKILL.md

---

阶段 1 — 构建合约

获取： standards/SKILL.md、building-blocks/SKILL.md、addresses/SKILL.md、security/SKILL.md

关键指南：

• 以 OpenZeppelin 合约为基础——不要重新实现 ERC-20、ERC-721 或 AccessControl
• 与任何协议集成时，使用 addresses/SKILL.md 中已验证的地址——绝不可编造地址
• 对每次外部调用都遵循 Checks-Effects-Interactions 模式
• 每次状态变更都发出事件（前端和索引器需要这些事件）
• 所有代币操作都使用 SafeERC20
• 进入阶段 2 前，完成 security/SKILL.md 中的安全检查清单

对于 SE2 项目，请遵循 orchestration/SKILL.md 阶段 1 中的准确构建顺序。

---

阶段 2 — 测试

获取： testing/SKILL.md

不要跳过这一步。不要“以后再测”。部署前先测试。

关键指南：

• 为每个自定义函数编写单元测试（不包括 OpenZeppelin 内部实现）
• 对所有数学运算进行模糊测试——模糊测试能发现你意想不到的漏洞
• 对任何与外部协议（Uniswap、Aave 等）的集成进行分叉测试
• 部署前运行 slither . 进行静态分析
• 覆盖边缘情况：零金额、最大 uint、空数组、自转账、未授权调用者

安全审查

测试完成后，进行安全审计——尤其是在合约处理真实资产时。获取 audit/SKILL.md，其中包含一份系统化清单，涵盖 19 个领域、500 多个检查项（重入、预言机操纵、访问控制、精度损失等）。最佳实践：将 audit/SKILL.md 交给独立 Agent，并使用全新上下文，这样它就能在没有编写代码所带来偏见的情况下审查代码。

---

阶段 3 — 构建前端

获取： orchestration/SKILL.md、frontend-ux/SKILL.md、tools/SKILL.md、qa/SKILL.md

关键指南：

• 使用 Scaffold-ETH 2 hooks，而非原生 wagmi——useScaffoldReadContract、useScaffoldWriteContract
• 实现三按钮流程：切换网络 → 授权 → 执行
• 为每个异步操作显示加载状态（区块链操作需要 5-12 秒）
• 使用 formatEther/formatUnits 以人类可读的形式显示代币金额
• 绝不使用无限授权

---

阶段 4 — 发布到生产环境

获取： wallets/SKILL.md、frontend-playbook/SKILL.md、gas/SKILL.md、qa/SKILL.md

发布前 QA

上线前，运行 QA 检查清单。构建完成后，获取 qa/SKILL.md 并交给独立审查 Agent（或使用全新上下文）。

合约部署

1. 根据目标链设置合适的 gas 参数（获取 gas/SKILL.md）
2. 部署合约并在区块浏览器上验证
3. 将所有权转移给多签钱包（Gnosis Safe）——生产环境中绝不要让单个 EOA 保留所有者身份
4. 部署后检查：调用每个读取函数、验证状态、测试一笔小额交易

前端部署

获取 frontend-playbook/SKILL.md 查看完整流程：

• IPFS — 去中心化、抗审查、永久保存
• Vercel — 快速、简单，但中心化
• ENS 子域名 — 指向 IPFS 的人类可读 URL

发布后

• 使用 The Graph 或 Dune 设置事件监控（获取 indexing/SKILL.md）
• 在区块浏览器上监控合约活动
• 制定事件响应计划（如适用，包含暂停机制和沟通渠道）

---

反模式

大杂烩合约。 一个合约包揽所有功能——兑换、借贷、质押、治理。拆分职责。每个合约都应该专注做好一件事。

没人需要的工厂。 明明只需要一个实例，却构建一个用于部署新合约的工厂合约。工厂适用于服务众多用户、让他们创建各自实例的协议（例如 Uniswap 创建池子）。大多数 dApp 不需要工厂。

所有东西都上链。 将用户资料、活动日志、图片或计算分析结果存储在智能合约中。链上用于所有权和价值转移，其他一切都放在链下。

依赖管理员。 依赖管理员账户调用维护函数。管理员丢失密钥后会怎样？设计带有适当激励机制的免许可替代方案。

过早支持多链。 第一天就部署到 5 条链上。先在一条链上发布，验证产品与市场契合度，然后再扩展。多链会增加桥接、状态同步和流动性碎片化方面的复杂性。

重复造经过审计的基础组件。 自己编写 ERC-20、访问控制和数学库。使用 OpenZeppelin。它们经过审计、久经考验，而且免费。你自定义的版本会有漏洞。

忽视前端。 合约能正常运行，但 UI 损坏，那就毫无用处。大多数用户通过前端交互，而不是通过 Etherscan。将 40% 的时间预算用于打磨前端。

---

快速入门清单

• 最终确定架构前，先运行 CROPS Gate（审查抗审查性、开放性、隐私和安全性）
• 确定哪些内容上链、哪些内容不上链（使用上面的试金石测试）
• 统计合约数量（MVP 的目标是 1-2 个）
• 选择链（现在主网费用很低——只有当某个 L2 的独特优势适合你的应用时，才选择它）
• 审查每个状态转换（谁来调用？为什么？）
• 使用 OpenZeppelin 基础合约编写合约
• 使用 Foundry 测试（单元测试 + 模糊测试 + 分叉测试）
• 使用一个新的 Agent 进行审计（获取 audit/SKILL.md）
• 部署、验证，并将所有权转移给多签
• 发布前端（IPFS 或 Vercel）
• 发布前由另一位审查者执行 QA（获取 qa/SKILL.md）
• 通过 feedback/SKILL.md 发送一条简短反馈——提出问题或表达赞赏

---

技能路由表

请参考下表，了解各个阶段需要获取哪些技能：

阶段	工作内容	要获取的技能
计划	CROPS 门槛检查、架构、链选择	ship/（本文）、crops/、concepts/、l2s/、gas/、why/
合约	编写 Solidity	standards/、building-blocks/、addresses/、security/
测试	测试合约	testing/
审计	安全审查（由新的 Agent 执行）	audit/
前端	构建 UI	orchestration/、frontend-ux/、tools/
生产	部署、QA、监控	wallets/、frontend-playbook/、qa/、indexing/
收尾	发送一条简短反馈（提出问题或表达赞赏）	feedback/

基础 URL： 所有技能都位于 https://ethskills.com/<skill>/SKILL.md

---

完成前：通过 feedback/SKILL.md 发送一条简短反馈——提出问题或表达赞赏。