adding-builder-codes

添加 Builder Codes

将 Base Builder Codes 集成到链上应用中。Builder Codes 会在交易调用数据末尾附加 ERC-8021 归因后缀，以便 Base 将活动归因到你的应用，并让你赚取推荐费。无需更改智能合约。

何时使用此技能

当开发者提出以下需求时使用此技能：

• “为我的应用添加 Builder Codes”
• “如何在交易中附加 Builder Code？”
• “我想从 Base 交易中赚取推荐费”
• “集成 Builder Codes”
• 设置 Base 上的交易归因

前置条件

• 从 base.dev > Settings > Builder Codes 获取 Builder Code
• 用于生成 ERC-8021 后缀的 ox 库：npm install ox

集成工作流

复制此清单并跟踪进度：

Builder Codes Integration:
- [ ] Step 1: Detect framework (Required First Step)
- [ ] Step 2: Install dependencies
- [ ] Step 3: Generate the dataSuffix constant
- [ ] Step 4: Apply attribution (framework-specific)
- [ ] Step 5: Verify attribution is working

框架检测（必需的第一步）

开始实现前，先确定正在使用的框架。

1. 阅读 package.json 并扫描源文件

# Check for framework dependencies
grep -E "wagmi|@privy-io/react-auth|viem|ethers" package.json

# Check for smart wallet / account abstraction usage
grep -rn "useSendCalls\|sendCalls\|ERC-4337\|useSmartWallets" src/

# Check for EOA transaction patterns
grep -rn "useSendTransaction\|sendTransaction\|writeContract\|useWriteContract" src/

# Check Privy version if present
grep "@privy-io/react-auth" package.json

2. 归类到一个框架

框架	检测信号
privy	package.json 或导入项中包含 @privy-io/react-auth
wagmi	package.json 或导入项中包含 wagmi（未使用 Privy）
viem	package.json 中包含 viem，且未使用 React 框架
rpc	检测到 ethers、window.ethereum 或未检测到 Web3 库

检测到多个框架时的优先级：Privy > Wagmi > Viem > Standard RPC

3. 与用户确认

继续之前，确认检测到的框架：

“我检测到你正在使用 [Framework]。我将采用 [Framework] 方案实现 Builder Codes，可以吗？”

等待用户确认后再开始实现。

实现路径

• Privy（@privy-io/react-auth v3.13.0+）→ 参阅 references/privy.md
• Wagmi（未使用 Privy）→ 参阅 references/wagmi.md
• 仅使用 Viem（未使用 React 框架）→ 参阅 references/viem.md
• Standard RPC（ethers.js 或原始 window.ethereum）→ 参阅 references/rpc.md

步骤 2：安装依赖

npm install ox

Wagmi/Viem 路径需要 viem >= 2.45.0。Privy 需要 @privy-io/react-auth >= 3.13.0。

步骤 3：生成 dataSuffix 常量

创建一个共享常量（例如 src/lib/attribution.ts 或 src/constants/builderCode.ts）：

import { Attribution } from "ox/erc8021";

export const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"], // Replace with your code from base.dev
});

步骤 4：应用归因

按照对应框架的指南操作：

Privy 实现

参阅 references/privy.md — 基于插件，需要更改一处配置。

Wagmi 实现

参阅 references/wagmi.md — 在 Wagmi 客户端配置中添加 dataSuffix。

Viem 实现

参阅 references/viem.md — 在钱包客户端中添加 dataSuffix。

Standard RPC 实现

参阅 references/rpc.md — 对于 ethers.js 或原始 window.ethereum，将 DATA_SUFFIX 附加到交易数据中。

首选方案：在客户端级别进行配置，这样所有交易都会自动归因。仅当需要按条件归因时，才使用逐笔交易方案。

对于 Smart Wallets（EIP-5792 sendCalls）：参阅 references/smart-wallets.md — 通过 capabilities 传递。

步骤 5：验证归因

1. base.dev：在 Onchain > Total Transactions 中检查归因计数
2. 区块浏览器：查找交易哈希，查看输入数据，确认最后 16 个字节重复为 8021
3. 验证工具：使用 builder-code-checker.vercel.app

关键事实

• Builder Codes 是在 Base 上铸造的 ERC-721 NFT
• 后缀会附加到 calldata 中；智能合约会忽略它（无需升级）
• Gas 成本可以忽略不计：每个非零字节消耗 16 gas
• base.dev 上的分析目前支持智能账户（AA）交易；即将支持 EOA（归因数据会保留）
• Privy 的 dataSuffix 插件会附加到所有链，而不只是 Base。如果需要针对特定链设置行为，请联系 Privy
• Privy 的 dataSuffix 插件尚不支持 @privy-io/wagmi 适配器

查找交易调用位置

在现有项目中补充集成时，搜索以下模式：

# React hooks (Wagmi)
grep -rn "useSendTransaction\|useSendCalls\|useWriteContract\|useContractWrite" src/

# Viem client calls
grep -rn "sendTransaction\|writeContract\|sendRawTransaction" src/

# Privy embedded wallet calls
grep -rn "sendTransaction\|signTransaction" src/

# ethers.js
grep -rn "signer\.sendTransaction\|contract\.connect" src/

# Raw window.ethereum
grep -rn "window\.ethereum\|eth_sendTransaction" src/

对于客户端级集成（Wagmi/Viem/Privy），通常只需修改配置文件，单个交易调用位置无需更改。