adding-builder-codes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adding Builder Codes

添加Builder Codes

Integrate Base Builder Codes into an onchain application. Builder Codes append an ERC-8021 attribution suffix to transaction calldata so Base can attribute activity to your app and you can earn referral fees. No smart contract changes required.

将Base Builder Codes集成到链上应用中。Builder Codes会在交易调用数据后附加ERC-8021归因后缀，这样Base就能将活动归因到你的应用，你也可以赚取推荐费。无需修改智能合约。

When to Use This Skill

何时使用此技能

Use this skill when a developer asks to:

"Add builder codes to my application"
"How do I append a builder code to my transactions?"
"I want to earn referral fees on Base transactions"
"Integrate builder codes"
Set up transaction attribution on Base

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

"为我的应用添加builder codes"
"如何为我的交易附加builder code？"
"我想在Base交易中赚取推荐费"
"集成builder codes"
在Base上设置交易归因

Prerequisites

前提条件

A Builder Code from base.dev > Settings > Builder Codes
The
```
ox
```
library for generating ERC-8021 suffixes:
```
npm install ox
```

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

Integration Workflow

集成流程

Copy this checklist and track progress:

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

复制此清单并跟踪进度：

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

Framework Detection (Required First Step)

框架检测（第一步，必须执行）

Before implementing, determine the framework in use.

在实施前，先确定所使用的框架。

1. Read package.json and scan source files

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

bash

undefined

bash

undefined

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

undefined

grep "@privy-io/react-auth" package.json

undefined

2. Classify into one framework

2. 归类到对应框架

Framework	Detection Signal
`privy`	`@privy-io/react-auth` in package.json or imports
`wagmi`	`wagmi` in package.json or imports (without Privy)
`viem`	`viem` in package.json, no React framework
`rpc`	`ethers` , `window.ethereum` , or no Web3 library detected

Priority order if multiple are detected: Privy > Wagmi > Viem > Standard RPC

框架	检测信号
`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 > 标准RPC

3. Confirm with user

3. 与用户确认

Before proceeding, confirm the detected framework:

"I detected you are using [Framework]. I'll implement builder codes using the [Framework] approach — does that sound right?"

Wait for user confirmation before implementing.

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

"我检测到你正在使用[Framework]。我将采用[Framework]方案来实现builder codes——这样可以吗？"

等待用户确认后再进行实施。

Implementation Path

实施路径

Privy (
```
@privy-io/react-auth
```
v3.13.0+) → See references/privy.md
Wagmi (without Privy) → See references/wagmi.md
Viem only (no React framework) → See references/viem.md
Standard RPC (ethers.js or raw
```
window.ethereum
```
) → See references/rpc.md

Privy（
```
@privy-io/react-auth
```
v3.13.0+）→ 查看references/privy.md
Wagmi（无Privy）→ 查看references/wagmi.md
仅Viem（无React框架）→ 查看references/viem.md
标准RPC（ethers.js或原生
```
window.ethereum
```
）→ 查看references/rpc.md

Step 2: Install dependencies

步骤2：安装依赖

bash

npm install ox

Requires

viem >= 2.45.0

for Wagmi/Viem paths. Privy requires

@privy-io/react-auth >= 3.13.0

bash

npm install ox

Wagmi/Viem路径需要

viem >= 2.45.0

。Privy需要

@privy-io/react-auth >= 3.13.0

。

Step 3: Generate the dataSuffix constant

步骤3：生成dataSuffix常量

Create a shared constant (e.g.,

src/lib/attribution.ts

src/constants/builderCode.ts

typescript

import { Attribution } from "ox/erc8021";

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

创建一个共享常量（例如

src/lib/attribution.ts

或

src/constants/builderCode.ts

）：

typescript

import { Attribution } from "ox/erc8021";

export const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"], // 替换为你从base.dev获取的代码
});

Step 4: Apply attribution

步骤4：应用归因

Follow the framework-specific guide:

遵循框架特定指南：

Privy Implementation

Privy实施

See references/privy.md — plugin-based, one config change required.

查看references/privy.md —— 基于插件，只需修改一处配置。

Wagmi Implementation

Wagmi实施

See references/wagmi.md — add

dataSuffix

to Wagmi client config.

查看references/wagmi.md —— 在Wagmi客户端配置中添加

dataSuffix

。

Viem Implementation

Viem实施

See references/viem.md — add

dataSuffix

to wallet client.

查看references/viem.md —— 在钱包客户端中添加

dataSuffix

。

Standard RPC Implementation

标准RPC实施

See references/rpc.md — append

DATA_SUFFIX

to transaction data for ethers.js or raw

window.ethereum

Preferred approach: Configure at the client level so all transactions are automatically attributed. Only use the per-transaction approach if you need conditional attribution.

For Smart Wallets (EIP-5792

sendCalls

): See references/smart-wallets.md — pass via

capabilities

查看references/rpc.md —— 为ethers.js或原生

window.ethereum

的交易数据附加

DATA_SUFFIX

。

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

对于智能钱包（EIP-5792

sendCalls

）：查看references/smart-wallets.md —— 通过

capabilities

传递。

Step 5: Verify attribution

步骤5：验证归因

base.dev: Check Onchain > Total Transactions for attribution counts
Block explorer: Find tx hash, view input data, confirm last 16 bytes are
```
8021
```
repeating
Validation tool: Use builder-code-checker.vercel.app

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

Key Facts

关键事实

Builder Codes are ERC-721 NFTs minted on Base
The suffix is appended to calldata; smart contracts ignore it (no upgrades needed)
Gas cost is negligible: 16 gas per non-zero byte
Analytics on base.dev currently support Smart Account (AA) transactions; EOA support is coming (attribution data is preserved)
The
```
dataSuffix
```
plugin in Privy appends to all chains, not just Base. If chain-specific behavior is needed, contact Privy
Privy's
```
dataSuffix
```
plugin is NOT yet supported with
```
@privy-io/wagmi
```
adapter

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

Finding Transaction Call Sites

查找交易调用位置

When retrofitting an existing project, search for these patterns:

bash

undefined

在改造现有项目时，搜索以下模式：

bash

undefined

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/


For client-level integration (Wagmi/Viem/Privy), you typically only need to modify the config file — individual transaction call sites remain unchanged.

grep -rn "window.ethereum|eth_sendTransaction" src/


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