orchestration

dApp 编排

你可能弄错的地方

SE2 有必须遵循的特定模式。 通用的“构建 dApp”建议行不通。SE2 会自动生成 deployedContracts.ts——不要编辑它。使用 Scaffold hooks，而不是原生 wagmi。外部合约必须在构建前端之前添加到 externalContracts.ts。

整个流程分为三个阶段。切勿跳过或合并阶段。 合约 → 前端 → 生产环境。每个阶段都有验证关卡。

三阶段构建系统

阶段	环境	进行的工作
Phase 1	本地 fork	在 localhost 上开发合约和 UI。快速迭代。
Phase 2	实时网络 + 本地 UI	将合约部署到主网/L2。使用真实状态进行测试。完善 UI。
Phase 3	生产环境	将前端部署到 IPFS/Vercel。进行最终 QA。

Phase 1：Scaffold（本地）

1.1 合约

npx create-eth@latest my-dapp
cd my-dapp && yarn install
yarn fork --network base  # Terminal 1: fork of real chain (or mainnet, your target chain)
yarn deploy               # Terminal 2: deploy contracts

始终使用 fork，绝不要用 yarn chain。 yarn fork 能完成 yarn chain 的所有工作，还能提供真实的协议状态——Uniswap、USDC、Aave、巨鲸余额等都已部署（已验证的地址：addresses/SKILL.md）。yarn chain 会提供一条空链，诱使你编写并不需要的模拟合约。链上已有的东西不要模拟——直接 fork 即可。

关键步骤：

1. 在 packages/foundry/contracts/（或 packages/hardhat/contracts/）中编写合约
2. 编写部署脚本
3. 在 packages/nextjs/contracts/externalContracts.ts 中添加所有外部合约——在 Phase 1.2 之前完成
4. 编写测试（覆盖率 ≥90%）
5. 开始开发前端之前先审计合约——获取 audit/SKILL.md 并按其中的步骤执行

验证： yarn deploy 成功。自动生成 deployedContracts.ts。测试通过。

1.2 前端

yarn fork --network base  # Terminal 1: fork of real chain (has Uniswap, USDC, etc.)
yarn deploy --watch       # Terminal 2: auto-redeploy on changes
yarn start                # Terminal 3: Next.js at localhost:3000

使用 SCAFFOLD HOOKS，而不是原生 WAGMI：

// Read
const { data } = useScaffoldReadContract({
  contractName: "YourContract",
  functionName: "balanceOf",
  args: [address],
  watch: true,
});

// Write
const { writeContractAsync, isMining } = useScaffoldWriteContract("YourContract");
await writeContractAsync({
  functionName: "swap",
  args: [tokenIn, tokenOut, amount],
  onBlockConfirmation: (receipt) => console.log("Done!", receipt),
});

// Events
const { data: events } = useScaffoldEventHistory({
  contractName: "YourContract",
  eventName: "SwapExecuted",
  fromBlock: 0n,
  watch: true,
});

三按钮流程（强制要求）

每次代币交互一次只显示一个按钮：

1. 切换网络（链不正确时）
2. 批准代币（授权额度不足时）
3. 执行操作（仅在满足 1 和 2 后）

绝不要同时显示“批准”和“执行”。

UX 规则

• 金额易于理解： 显示时使用 formatEther() / formatUnits()，与合约交互时使用 parseEther() / parseUnits()
• 所有操作都显示加载状态： 在所有异步操作中使用 isLoading、isMining
• 待处理交易期间禁用按钮（区块链操作需要 5-12 秒）
• 绝不要使用无限授权——批准精确额度或 3-5 倍额度
• 提供有帮助的错误信息： 将 “insufficient funds”、“user rejected”、“execution reverted” 转换为通俗易懂的语言

验证： 使用真实钱包在 localhost 上完成整个用户流程。处理好所有边界情况。

🚨 绝不要将密钥提交到 Git

开始 Phase 2 之前，请先阅读此部分。 AI Agent 是 GitHub 上凭证泄露的头号来源。机器人会实时抓取代码仓库，并在密钥泄露后的几秒内加以利用。

这包括所有密钥，而不仅仅是钱包私钥：

• 钱包私钥——资金会在几秒内被转走
• API 密钥——Alchemy、Infura、Etherscan、WalletConnect 项目 ID
• 包含密钥的 RPC URL——例如 https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
• OAuth 令牌、密码、Bearer 令牌

⚠️ 常见的 SE2 陷阱：scaffold.config.ts

scaffold.config.ts 中的 rpcOverrides 和 alchemyApiKey 会提交到 Git。**绝不要将 API 密钥直接粘贴到此文件中。**请使用环境变量：

// ❌ WRONG — key committed to public repo
rpcOverrides: {
  [chains.base.id]: "https://base-mainnet.g.alchemy.com/v2/8GVG8WjDs-LEAKED",
},

// ✅ RIGHT — key stays in .env.local
rpcOverrides: {
  [chains.base.id]: process.env.NEXT_PUBLIC_BASE_RPC || "https://mainnet.base.org",
},

每次执行 git add 或 git commit 之前：

# Check for leaked secrets
git diff --cached --name-only | grep -iE '\.env|key|secret|private'
grep -rn "0x[a-fA-F0-9]\{64\}" packages/ --include="*.ts" --include="*.js" --include="*.sol"
# Check for hardcoded API keys in config files
grep -rn "g.alchemy.com/v2/[A-Za-z0-9]" packages/ --include="*.ts" --include="*.js"
grep -rn "infura.io/v3/[A-Za-z0-9]" packages/ --include="*.ts" --include="*.js"
# If ANYTHING matches, STOP. Move the secret to .env and add .env to .gitignore.

你的 .gitignore 必须包含：

.env
.env.*
*.key
broadcast/
cache/
node_modules/

SE2 默认会处理部署者密钥——yarn generate 会创建一个包含部署者密钥的 .env，而 .gitignore 会将其排除。**不要覆盖此模式。**不要将密钥复制到脚本、配置文件或部署日志中。这包括 RPC 密钥、API 密钥和任何凭证，而不仅仅是钱包密钥。

请参阅 wallets/SKILL.md，了解完整的密钥安全指南、密钥已泄露时的处理方法，以及安全的部署模式。

阶段 2：实时合约 + 本地 UI

1. 更新 scaffold.config.ts：targetNetworks: [mainnet]（或你的 L2）
2. 为部署账户注资：yarn generate → yarn account → 转入真实 ETH
3. 部署：yarn deploy --network mainnet
4. 部署后立即验证：yarn verify --network mainnet
   • 无需区块浏览器 API 密钥——SE2 会帮你处理
   • 部署后立即运行，不要拖到之后。不要跳过。
5. 使用真实钱包和小额资金（1–10 美元）进行测试
6. 打磨 UI——移除 SE2 品牌元素，采用自定义样式

**设计规则：**不要有 LLM 垃圾内容。不要使用通用的紫色渐变。要做出独特风格。

**验证：**合约已在区块浏览器上验证。使用真实合约的完整流程可正常运行。

阶段 3：生产环境部署

部署前检查清单

• 在 scaffold.config.ts 中设置 burnerWalletMode: "localNetworksOnly"（防止在生产环境显示 burner 钱包）
• 更新元数据（标题、描述、OG 图片尺寸为 1200x630px）
• 将所有测试值还原为生产值
• 运行完整的前端 QA 审核——获取 qa/SKILL.md，并在部署前交给一个独立的 Agent

部署

IPFS——使用 BGIPFS 进行去中心化部署（获取该技能以了解完整详情）。它已集成到 SE2 中，无需设置：

yarn ipfs
# → https://{CID}.ipfs.community.bgipfs.com/

注意：IPFS 仅适用于静态内容——不支持服务器端渲染、API 端点或函数。

Vercel：

yarn vercel

生产环境 QA

• 应用可通过公开 URL 加载
• 钱包可连接，网络切换正常
• 合约读写操作正常
• 控制台没有错误
• 未显示 burner 钱包
• OG 图片在链接预览中正常显示
• 适配移动设备
• 已使用 MetaMask、Rainbow、WalletConnect 测试

阶段转换规则

阶段 3 出现错误 → 返回阶段 2（使用本地 UI 和生产合约修复） 阶段 2 出现合约错误 → 返回阶段 1（在本地修复，编写回归测试，然后重新部署） 绝不要在生产环境中绕过错误。

SE2 关键目录

packages/
├── foundry/contracts/          # Solidity contracts
├── foundry/script/             # Deploy scripts
├── foundry/test/               # Tests
└── nextjs/
    ├── app/                    # Pages
    ├── components/             # React components
    ├── contracts/
    │   ├── deployedContracts.ts   # AUTO-GENERATED (don't edit)
    │   └── externalContracts.ts   # YOUR external contracts (edit this)
    ├── hooks/scaffold-eth/     # USE THESE hooks
    └── scaffold.config.ts      # Main config

资源

• **SE2 文档：**https://docs.scaffoldeth.io/
• **SE2 技能：**https://docs.scaffoldeth.io/SKILL.md
• **UI 组件：**https://ui.scaffoldeth.io/
• **SE2 AGENTS.md：**https://github.com/scaffold-eth/scaffold-eth-2/blob/main/AGENTS.md