ship

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ship a dApp

部署dApp

What You Probably Got Wrong

你可能踩过的这些坑

You jump to code without a plan. Before writing a single line of Solidity, you need to know: what goes onchain, what stays offchain, which chain, how many contracts, and who calls every function. Skip this and you'll rewrite everything.

You over-engineer. Most dApps need 0-2 contracts. A token launch is 1 contract. An NFT collection is 1 contract. A marketplace that uses existing DEX liquidity needs 0 contracts. Three contracts is the upper bound for an MVP. If you're writing more, you're building too much.

You put too much onchain. Solidity is for ownership, transfers, and commitments. It's not a database. It's not an API. It's not a backend. If it doesn't involve trustless value transfer or a permanent commitment, it doesn't belong in a smart contract.

You skip chain selection. The 2026 answer is almost always an L2. Base for consumer apps. Arbitrum for DeFi. Optimism for public goods. Mainnet only if you need maximum security or composability with mainnet-only protocols. Fetch

l2s/SKILL.md

for the full decision matrix.

You forget nothing is automatic. Smart contracts don't run themselves. Every state transition needs a caller who pays gas and a reason to do it. If you can't answer "who calls this and why?" for every function, your contract has dead code. Fetch

concepts/SKILL.md

for the full mental model.

**你还没做规划就直接写代码。**在编写任何Solidity代码之前，你需要明确：哪些内容上链，哪些内容留在链下，选择哪条链，需要多少个合约，以及每个函数的调用方是谁。跳过这一步，你最终会重写所有代码。

**你过度设计了。**大多数dApp只需要0-2个合约。代币发行只需要1个合约，NFT合集只需要1个合约，使用现有DEX流动性的市场甚至不需要合约。MVP的合约上限是3个，如果你的合约数量更多，说明你构建的内容太复杂了。

**你把太多内容放到链上。**Solidity适用于所有权管理、转账和承诺场景，它不是数据库、API或后端。如果不需要涉及无需信任的价值转移或永久承诺，就不应该放在智能合约里。

**你跳过了链的选择。**到2026年，大多数场景的最佳选择几乎都是L2。面向消费者的应用选Base，DeFi应用选Arbitrum，公共物品类应用选Optimism。只有当你需要最高安全性或与仅支持主网的协议组合时，才选择以太坊主网。获取

l2s/SKILL.md

查看完整的决策矩阵。

**你误以为一切都是自动的。**智能合约不会自行运行。每一次状态转换都需要调用方支付Gas费用，并且要有调用的理由。如果你无法回答每个函数的「谁调用？为什么调用？」，那么你的合约里就有死代码。获取

concepts/SKILL.md

查看完整的思维模型。

Phase 0 — Plan the Architecture

阶段0 — 规划架构

Do this BEFORE writing any code. Every hour spent here saves ten hours of rewrites.

在编写任何代码之前先完成这一步。在这里花费的每一小时，都能为你节省十小时的重写时间。

The Onchain Litmus Test

链上判定测试

Put it onchain if it involves:

Trustless ownership — who owns this token/NFT/position?
Trustless exchange — swapping, trading, lending, borrowing
Composability — other contracts need to call it
Censorship resistance — must work even if your team disappears
Permanent commitments — votes, attestations, proofs

Keep it offchain if it involves:

User profiles, preferences, settings
Search, filtering, sorting
Images, videos, metadata (store on IPFS, reference onchain)
Business logic that changes frequently
Anything that doesn't involve value transfer or trust

Judgment calls:

Reputation scores → offchain compute, onchain commitments (hashes or attestations)
Activity feeds → offchain indexing of onchain events (fetch
```
indexing/SKILL.md
```
)
Price data → offchain oracles writing onchain (Chainlink)
Game state → depends on stakes. Poker with real money? Onchain. Leaderboard? Offchain.

满足以下条件的内容才上链：

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

满足以下条件的内容留在链下：

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

判断案例：

声誉分数 → 链下计算，链上存储承诺（哈希或证明）
活动动态 → 链下索引链上事件（获取
```
indexing/SKILL.md
```
）
价格数据 → 链下预言机写入链上（如Chainlink）
游戏状态 → 取决于风险。涉及真钱的扑克游戏？上链。排行榜？链下。

MVP Contract Count

MVP合约数量

What you're building	Contracts	Pattern
Token launch	1	ERC-20 with custom logic
NFT collection	1	ERC-721 with mint/metadata
Simple marketplace	0-1	Use existing DEX; maybe a listing contract
Vault / yield	1	ERC-4626 vault
Lending protocol	1-2	Pool + oracle integration
DAO / governance	1-3	Governor + token + timelock
AI agent service	0-1	Maybe an ERC-8004 registration
Prediction market	1-2	Market + resolution oracle

If you need more than 3 contracts for an MVP, you're over-building. Ship the simplest version that works, then iterate.

你要构建的项目	合约数量	模式
代币发行	1	带自定义逻辑的ERC-20
NFT合集	1	带铸造/元数据的ERC-721
简单市场	0-1	使用现有DEX；可搭配一个挂单合约
金库/收益产品	1	ERC-4626金库
借贷协议	1-2	资金池 + 预言机集成
DAO/治理	1-3	治理合约 + 代币 + 时间锁
AI Agent服务	0-1	可搭配ERC-8004注册合约
预测市场	1-2	市场合约 + 结算预言机

**如果你的MVP需要超过3个合约，说明你构建的内容太复杂了。**先发布最简单的可用版本，再逐步迭代。

State Transition Audit

状态转换审计

For EVERY function in your contract, fill in this worksheet:

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

If "what if nobody calls it?" breaks your system, you have a design problem. Fix it before writing code. See

concepts/SKILL.md

for incentive design patterns.

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

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

如果「如果没人调用会怎样？」的答案会导致系统崩溃，说明你的设计有问题。在写代码之前先修复它。查看

concepts/SKILL.md

获取激励设计模式。

Chain Selection (Quick Version)

链选择（快速版）

Priority	Chain	Why
Consumer app, low fees	Base	Cheapest L2, Coinbase distribution, strong ecosystem
DeFi, complex protocols	Arbitrum	Deepest DeFi liquidity on any L2, mature tooling
Public goods, governance	Optimism	Retroactive public goods funding, OP Stack ecosystem
Maximum security	Ethereum mainnet	Only if you need mainnet composability or $100M+ TVL
Privacy features	zkSync / Scroll	ZK rollups with potential privacy extensions

Fetch

l2s/SKILL.md

for the complete comparison with gas costs, bridging, and deployment differences.

优先级	链	原因
消费者应用、低手续费	Base	最便宜的L2，Coinbase生态支持，生态系统完善
DeFi、复杂协议	Arbitrum	所有L2中DeFi流动性最充足，工具成熟
公共物品、治理	Optimism	追溯性公共物品资助，OP Stack生态
最高安全性	Ethereum mainnet	仅当你需要主网组合性或TVL超1亿美元时选择
隐私特性	zkSync / Scroll	支持隐私扩展的ZK Rollup

获取

l2s/SKILL.md

查看包含Gas费用、跨链桥和部署差异的完整对比。

dApp Archetype Templates

dApp原型模板

Find your archetype below. Each tells you exactly how many contracts you need, what they do, common mistakes, and which skills to fetch.

在下方找到你的项目原型，每个模板会告诉你需要多少个合约、合约功能、常见错误以及需要获取的技能。

1. Token Launch (1-2 contracts)

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

Architecture: One ERC-20 contract. Add a vesting contract if you have team/investor allocations.

Contracts:

```
MyToken.sol
```
— ERC-20 with initial supply, maybe mint/burn
```
TokenVesting.sol
```
(optional) — time-locked releases for team tokens

Common mistakes:

Infinite supply with no burn mechanism (what gives it value?)
No initial liquidity plan (deploying a token nobody can buy)
Fee-on-transfer mechanics that break DEX integrations

Fetch sequence:

standards/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

→

gas/SKILL.md

**架构：**一个ERC-20合约。如果有团队/投资者分配，可添加一个锁仓合约。

合约：

```
MyToken.sol
```
— 带初始供应量的ERC-20，可包含铸造/销毁逻辑
```
TokenVesting.sol
```
（可选）— 团队代币的时间锁仓释放合约

常见错误：

无销毁机制的无限供应量（代币的价值从何而来？）
没有初始流动性计划（发行的代币没人能买）
手续费转账机制破坏DEX集成

获取顺序：

standards/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

→

gas/SKILL.md

2. NFT Collection (1 contract)

2. NFT合集（1个合约）

Architecture: One ERC-721 contract. Metadata on IPFS. Frontend for minting.

Contracts:

```
MyNFT.sol
```
— ERC-721 with mint, max supply, metadata URI

Common mistakes:

Storing images onchain (use IPFS or Arweave, store the hash onchain)
No max supply cap (unlimited minting destroys value)
Complex whitelist logic when a simple Merkle root works

Fetch sequence:

standards/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

→

frontend-ux/SKILL.md

**架构：**一个ERC-721合约。元数据存储在IPFS。前端负责铸造功能。

合约：

```
MyNFT.sol
```
— 带铸造、最大供应量、元数据URI的ERC-721

常见错误：

图片存储在链上（使用IPFS或Arweave，链上仅存储哈希）
没有最大供应量上限（无限铸造会摧毁代币价值）
使用复杂的白名单逻辑，而简单的默克尔根就足够

获取顺序：

standards/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

→

frontend-ux/SKILL.md

3. Marketplace / Exchange (0-2 contracts)

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

Architecture: If trading existing tokens, you likely need 0 contracts — integrate with Uniswap/Aerodrome. If building custom order matching, 1-2 contracts.

Contracts:

(often none — use existing DEX liquidity via router)
```
OrderBook.sol
```
(if custom) — listing, matching, settlement
```
Escrow.sol
```
(if needed) — holds assets during trades

Common mistakes:

Building a DEX from scratch when Uniswap V4 hooks can do it
Ignoring MEV (fetch
```
security/SKILL.md
```
for sandwich attack protection)
Centralized order matching (defeats the purpose)

Fetch sequence:

building-blocks/SKILL.md

→

addresses/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

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

合约：

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

常见错误：

从头构建DEX，而Uniswap V4钩子就能实现需求
忽略MEV（获取
```
security/SKILL.md
```
查看三明治攻击防护）
中心化订单匹配（违背了区块链的初衷）

获取顺序：

building-blocks/SKILL.md

→

addresses/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

4. Lending / Vault / Yield (0-1 contracts)

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

Architecture: If using existing protocol (Aave, Compound), 0 contracts — just integrate. If building a vault, 1 ERC-4626 contract.

Contracts:

```
MyVault.sol
```
— ERC-4626 vault wrapping a yield source

Common mistakes:

Ignoring vault inflation attack (fetch
```
security/SKILL.md
```
)
Not using ERC-4626 standard (breaks composability)
Hardcoding token decimals (USDC is 6, not 18)

Fetch sequence:

building-blocks/SKILL.md

→

standards/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

**架构：**如果使用现有协议（Aave、Compound），无需合约 — 直接集成即可。如果构建金库，需要1个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 / Governance (1-3 contracts)

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

Architecture: Governor contract + governance token + timelock. Use OpenZeppelin's Governor — don't build from scratch.

Contracts:

```
GovernanceToken.sol
```
— ERC-20Votes
```
MyGovernor.sol
```
— OpenZeppelin Governor with voting parameters
```
TimelockController.sol
```
— delays execution for safety

Common mistakes:

No timelock (governance decisions execute instantly = rug vector)
Low quorum that allows minority takeover
Token distribution so concentrated that one whale controls everything

Fetch sequence:

standards/SKILL.md

→

building-blocks/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

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

合约：

```
GovernanceToken.sol
```
— ERC-20Votes
```
MyGovernor.sol
```
— 带投票参数的OpenZeppelin Governor
```
TimelockController.sol
```
— 为安全延迟执行

常见错误：

没有时间锁（治理决策立即执行 = rug风险）
低法定人数允许少数人接管
代币分布过于集中，导致一个巨鲸控制一切

获取顺序：

standards/SKILL.md

→

building-blocks/SKILL.md

→

security/SKILL.md

→

testing/SKILL.md

6. AI Agent Service (0-1 contracts)

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

Architecture: Agent logic is offchain. Onchain component is optional — ERC-8004 identity registration, or a payment contract for x402.

Contracts:

(often none — agent runs offchain, uses existing payment infra)
```
AgentRegistry.sol
```
(optional) — ERC-8004 identity + service endpoints

Common mistakes:

Putting agent logic onchain (Solidity is not for AI inference)
Overcomplicating payments (x402 handles HTTP-native payments)
Ignoring key management (fetch
```
wallets/SKILL.md
```
)

Fetch sequence:

standards/SKILL.md

→

wallets/SKILL.md

→

tools/SKILL.md

→

orchestration/SKILL.md

**架构：**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

Phase 1 — Build Contracts

阶段1 — 构建合约

Fetch:

standards/SKILL.md

building-blocks/SKILL.md

addresses/SKILL.md

security/SKILL.md

Key guidance:

Use OpenZeppelin contracts as your base — don't reinvent ERC-20, ERC-721, or AccessControl
Use verified addresses from
```
addresses/SKILL.md
```
for any protocol integration — never fabricate addresses
Follow the Checks-Effects-Interactions pattern for every external call
Emit events for every state change (your frontend and indexer need them)
Use
```
SafeERC20
```
for all token operations
Run through the security checklist in
```
security/SKILL.md
```
before moving to Phase 2

For SE2 projects, follow

orchestration/SKILL.md

Phase 1 for the exact build sequence.

获取：

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的精确构建顺序。

Phase 2 — Test

阶段2 — 测试

Fetch:

testing/SKILL.md

Don't skip this. Don't "test later." Test before deploy.

Key guidance:

Unit test every custom function (not OpenZeppelin internals)
Fuzz test all math operations — fuzzing finds the bugs you didn't think of
Fork test any integration with external protocols (Uniswap, Aave, etc.)
Run
```
slither .
```
for static analysis before deploying
Target edge cases: zero amounts, max uint, empty arrays, self-transfers, unauthorized callers

获取：

testing/SKILL.md

不要跳过这一步，不要「以后再测试」。部署前必须测试。

核心指南：

对每个自定义函数进行单元测试（无需测试OpenZeppelin内部逻辑）
对所有数学操作进行模糊测试 — 模糊测试能发现你没想到的bug
与外部协议（Uniswap、Aave等）的集成要进行分叉测试
部署前运行
```
slither .
```
进行静态分析
针对边缘案例测试：零金额、最大uint值、空数组、自转账、未授权调用方

Phase 3 — Build Frontend

阶段3 — 构建前端

Fetch:

orchestration/SKILL.md

frontend-ux/SKILL.md

tools/SKILL.md

Key guidance:

Use Scaffold-ETH 2 hooks, not raw wagmi —

useScaffoldReadContract

useScaffoldWriteContract

Implement the three-button flow: Switch Network → Approve → Execute
Show loading states on every async operation (blockchains take 5-12 seconds)
Display token amounts in human-readable form with
```
formatEther
```
/
```
formatUnits
```
Never use infinite approvals

获取：

orchestration/SKILL.md

frontend-ux/SKILL.md

tools/SKILL.md

核心指南：

使用Scaffold-ETH 2钩子，不要使用原始wagmi —
```
useScaffoldReadContract
```
,
```
useScaffoldWriteContract
```
实现三步流程：切换网络 → 授权 → 执行
每个异步操作都显示加载状态（区块链操作需要5-12秒）
使用
```
formatEther
```
/
```
formatUnits
```
将代币金额转换为人类可读形式
永远不要使用无限授权

Phase 4 — Ship to Production

阶段4 — 部署到生产环境

Fetch:

wallets/SKILL.md

frontend-playbook/SKILL.md

gas/SKILL.md

获取：

wallets/SKILL.md

frontend-playbook/SKILL.md

gas/SKILL.md

Contract Deployment

合约部署

Set gas settings appropriate for the target chain (fetch
```
gas/SKILL.md
```
)
Deploy and verify contracts on block explorer
Transfer ownership to a multisig (Gnosis Safe) — never leave a single EOA as owner in production
Post-deploy checks: call every read function, verify state, test one small transaction

根据目标链设置合适的Gas参数（获取
```
gas/SKILL.md
```
）
在区块浏览器上部署并验证合约
将所有权转移到多签钱包（如Gnosis Safe）— 生产环境中永远不要将单个EOA作为所有者
部署后检查：调用每个只读函数，验证状态，测试一笔小额交易

Frontend Deployment

前端部署

Fetch

frontend-playbook/SKILL.md

for the full pipeline:

IPFS — decentralized, censorship-resistant, permanent
Vercel — fast, easy, but centralized
ENS subdomain — human-readable URL pointing to IPFS

获取

frontend-playbook/SKILL.md

查看完整流程：

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

Post-Launch

上线后

Set up event monitoring with The Graph or Dune (fetch
```
indexing/SKILL.md
```
)
Monitor contract activity on block explorer
Have an incident response plan (pause mechanism if applicable, communication channel)

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

Anti-Patterns

反模式

Kitchen sink contract. One contract doing everything — swap, lend, stake, govern. Split responsibilities. Each contract should do one thing well.

Factory nobody asked for. Building a factory contract that deploys new contracts when you only need one instance. Factories are for protocols that serve many users creating their own instances (like Uniswap creating pools). Most dApps don't need them.

Onchain everything. Storing user profiles, activity logs, images, or computed analytics in a smart contract. Use onchain for ownership and value transfer, offchain for everything else.

Admin crutch. Relying on an admin account to call maintenance functions. What happens when the admin loses their key? Design permissionless alternatives with proper incentives.

Premature multi-chain. Deploying to 5 chains on day one. Launch on one chain, prove product-market fit, then expand. Multi-chain adds complexity in bridging, state sync, and liquidity fragmentation.

Reinventing audited primitives. Writing your own ERC-20, your own access control, your own math library. Use OpenZeppelin. They're audited, battle-tested, and free. Your custom version has bugs.

Ignoring the frontend. A working contract with a broken UI is useless. Most users interact through the frontend, not Etherscan. Budget 40% of your time for frontend polish.

**万能合约。**一个合约包揽所有功能 — 兑换、借贷、质押、治理。拆分职责，每个合约应该只做好一件事。

**没人需要的工厂合约。**构建一个工厂合约来部署新合约，但你其实只需要一个实例。工厂合约适用于为多个用户创建各自实例的协议（如Uniswap创建资金池）。大多数dApp不需要工厂合约。

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

**管理员依赖。**依赖管理员账户调用维护函数。如果管理员丢失密钥怎么办？设计无需权限的替代方案，并搭配适当的激励机制。

**过早多链部署。**第一天就部署到5条链。先在一条链上线，验证产品市场契合度，再进行扩展。多链会增加跨链桥、状态同步和流动性碎片化的复杂度。

**重新发明已审计的原语。**编写自己的ERC-20、访问控制或数学库。使用OpenZeppelin的合约，它们经过审计、久经考验且免费。你自己写的版本肯定有bug。

**忽略前端。**合约能正常工作但UI崩溃的dApp毫无用处。大多数用户通过前端交互，而不是Etherscan。预留40%的时间用于前端优化。

Quick-Start Checklist

快速启动清单

Skill Routing Table

技能路由表

Use this to know which skills to fetch at each phase:

Phase	What you're doing	Skills to fetch
Plan	Architecture, chain selection	`ship/` (this), `concepts/` , `l2s/` , `gas/`
Contracts	Writing Solidity	`standards/` , `building-blocks/` , `addresses/` , `security/`
Test	Testing contracts	`testing/`
Frontend	Building UI	`orchestration/` , `frontend-ux/` , `tools/`
Production	Deploy + monitor	`wallets/` , `frontend-playbook/` , `indexing/`

Base URLs: All skills are at

https://ethskills.com/<skill>/SKILL.md

使用此表了解每个阶段需要获取的技能：

阶段	你要做的事	需要获取的技能
规划	架构设计、链选择	`ship/` （本指南）, `concepts/` , `l2s/` , `gas/`
合约构建	编写Solidity代码	`standards/` , `building-blocks/` , `addresses/` , `security/`
测试	合约测试	`testing/`
前端构建	构建UI	`orchestration/` , `frontend-ux/` , `tools/`
生产部署	部署+监控	`wallets/` , `frontend-playbook/` , `indexing/`

**基础URL：**所有技能都在

https://ethskills.com/<skill>/SKILL.md