Skip to content

Commit e7144e2

Browse files
ericbrown99ericbrown99
committed
Add builder code docs
1 parent 611388b commit e7144e2

File tree

3 files changed

+180
-2
lines changed

3 files changed

+180
-2
lines changed

‎docs/base-chain/quickstart/base-solana-bridge.mdx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: "Base-Solana Bridge"
33
description: "Bridge tokens and messages between Base and Solana"
4-
icon: "bridge"
54
---
65

76
import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx"

‎docs/base-chain/quickstart/builder-codes.mdx‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: "Builder Codes"
3+
description: "Integrate Builder Codes to attribute onchain activity to your app or wallet."
4+
---
5+
6+
Builder Codes allow you to attribute onchain activity to your app or wallet, unlocking analytics, rewards, and future incentives. This guide covers the implementation steps for both application developers and wallet providers.
7+
8+
## For App Developers
9+
10+
Integrating Builder Codes requires appending a suffix—provided by Base—to your transaction data.
11+
12+
<Steps>
13+
<Step title="Get your Builder Code and Suffix">
14+
When you register on **base.dev**, you will receive:
15+
16+
* **Builder Code**: A random string (e.g., `k3p9da`).
17+
* **ERC-8021 Suffix**: A hex-encoded string (e.g., `0x...`).
18+
19+
You will use the **suffix** to attribute transactions to your app.
20+
</Step>
21+
22+
<Step title="Append the Suffix to Transactions">
23+
The recommended way to attach your suffix is using `wallet_sendCalls` (ERC-5792). This passes the suffix through a capability, allowing the wallet to handle the attachment automatically for both EOA and Smart Account (ERC-4337) users.
24+
25+
<Tabs>
26+
<Tab title="Wagmi (Recommended)">
27+
Use the `useSendCalls` hook from Wagmi's experimental features to pass the `dataSuffix` capability.
28+
29+
```typescript lines highlight={14-16}
30+
import { useSendCalls } from 'wagmi/experimental'
31+
32+
// Your suffix provided by base.dev
33+
const dataSuffix = "0x1234abcd..."
34+
35+
function SendTx() {
36+
const { sendCalls } = useSendCalls()
37+
38+
async function submit() {
39+
await sendCalls({
40+
calls: [
41+
{
42+
to: "0xYourContract",
43+
data: "0xYourCalldata"
44+
}
45+
],
46+
capabilities: {
47+
dataSuffix: dataSuffix
48+
}
49+
})
50+
}
51+
52+
return <button onClick={submit}>Send</button>
53+
}
54+
```
55+
</Tab>
56+
<Tab title="Viem">
57+
If you are using Viem directly, pass the `dataSuffix` in the `capabilities` object.
58+
59+
```typescript lines highlight={11-13}
60+
import { walletClient } from './client'
61+
62+
const dataSuffix = "0x1234abcd..."
63+
64+
await walletClient.sendCalls({
65+
calls: [
66+
{
67+
to: "0xYourContract",
68+
data: "0xYourCalldata"
69+
}
70+
],
71+
capabilities: {
72+
dataSuffix: dataSuffix
73+
}
74+
})
75+
```
76+
</Tab>
77+
<Tab title="Legacy (writeContract)">
78+
If you are restricted to `writeContract` (EOA only), you must manually append the suffix to the calldata. This is **not recommended** as it does not support Smart Accounts automatically.
79+
80+
```typescript lines highlight={15}
81+
import { encodeFunctionData } from 'viem'
82+
83+
// 1. Encode your function call
84+
const encoded = encodeFunctionData({
85+
abi,
86+
functionName: "yourFn",
87+
args: [a, b, c],
88+
})
89+
90+
// 2. Manually append the suffix (stripping the '0x' prefix from the suffix)
91+
const dataWithSuffix = encoded + dataSuffix.slice(2)
92+
93+
// 3. Send the transaction
94+
await sendTransaction({
95+
to: "0xYourContract",
96+
data: dataWithSuffix,
97+
})
98+
```
99+
</Tab>
100+
</Tabs>
101+
</Step>
102+
</Steps>
103+
104+
Once you have added the suffix, your app is fully ERC-8021 compliant.
105+
106+
---
107+
108+
## For Wallet Developers
109+
110+
Wallet providers need to support the `dataSuffix` capability to enable attribution. This involves accepting the capability and appending the suffix to the calldata before signing.
111+
112+
<Steps>
113+
<Step title="Support the dataSuffix Capability">
114+
Your wallet should accept a `dataSuffix` string in the `capabilities` object of `wallet_sendCalls`.
115+
116+
```typescript lines
117+
interface DataSuffixCapability {
118+
dataSuffix: string; // hex-encoded bytes provided by the app
119+
}
120+
```
121+
</Step>
122+
123+
<Step title="Append Suffix to Calldata">
124+
When constructing the transaction or User Operation, extract the `dataSuffix` and append it to the calldata.
125+
126+
<Tabs>
127+
<Tab title="EOA Transactions">
128+
Append to `tx.data`.
129+
130+
```typescript lines
131+
// Minimal example for EOA
132+
function applySuffixToEOA(tx, capabilities) {
133+
const suffix = capabilities.find(c => c.dataSuffix)?.dataSuffix
134+
if (!suffix) return tx
135+
136+
return {
137+
...tx,
138+
// Append suffix bytes (remove 0x prefix from suffix if tx.data has it)
139+
data: tx.data + suffix.slice(2)
140+
}
141+
}
142+
```
143+
</Tab>
144+
<Tab title="ERC-4337 User Operations">
145+
Append to `userOp.callData` (not the transaction-level calldata).
146+
147+
```typescript lines
148+
// Minimal example for ERC-4337
149+
function applySuffixToUserOp(userOp, capabilities) {
150+
const suffix = capabilities.find(c => c.dataSuffix)?.dataSuffix
151+
if (!suffix) return userOp
152+
153+
return {
154+
...userOp,
155+
// Append suffix bytes to the UserOp callData
156+
callData: userOp.callData + suffix.slice(2)
157+
}
158+
}
159+
```
160+
</Tab>
161+
</Tabs>
162+
</Step>
163+
<Step title="(Optional) Add Wallet Attribution">
164+
Wallets may also include their own attribution code (their own ERC-8021 suffix) by simply prepending the wallet’s own suffix before the app’s.
165+
166+
* **No interaction required with apps:** The wallet handles this independently.
167+
* **Multi-code support:** ERC-8021 natively supports multiple attribution codes.
168+
169+
**Example:**
170+
171+
```typescript
172+
finalSuffix = walletSuffix + appSuffix
173+
```
174+
175+
This ensures both the app and the wallet receive onchain attribution.
176+
</Step>
177+
</Steps>
178+

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,8 @@
9090
"base-chain/quickstart/deploy-on-base",
9191
"base-chain/quickstart/connecting-to-base",
9292
"base-chain/quickstart/bridge-token",
93-
"base-chain/quickstart/base-solana-bridge"
93+
"base-chain/quickstart/base-solana-bridge",
94+
"base-chain/quickstart/builder-codes"
9495
]
9596
},
9697
{

0 commit comments

Comments
 (0)