Skip to content

Commit 39dcf06

Browse files
dgcadgca
committed
docs: Update builder code docs to suggest using dataSuffix at the client level
1 parent 443b032 commit 39dcf06

1 file changed

Lines changed: 180 additions & 57 deletions

File tree

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

Lines changed: 180 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -5,104 +5,227 @@ description: "Integrate Builder Codes to attribute onchain activity to your app
55

66
## What are Builder Codes
77

8-
Base Builder Codes are an ERC-721 NFT collection where unique codes (e.g. “abc123”) are minted to help identify builders onchain.
8+
Base Builder Codes are an ERC-721 NFT collection where unique codes (e.g. "abc123") are minted to help identify builders onchain.
99

10-
Each code has associated metadata. Onchain metadata primarily includes a “payout address” where each code declares where potential rewards should be sent to. Offchain metadata includes more details about the app including its name and site.
10+
Each code has associated metadata. Onchain metadata primarily includes a "payout address" where each code declares where potential rewards should be sent to. Offchain metadata includes more details about the app including its name and site.
1111

1212
## Automatic Builder-Code Attribution on Base
1313

1414
Once your app is registered on [Base.dev](http://base.dev/), the Base App will auto-append your Base Builder Code to transactions its users make in your app (e.g. via your mini app, or the Base App's browser). This powers your onchain analytics in [Base.dev](http://base.dev/) and qualifies you for potential future rewards.
1515

16-
1716
## For App Developers
1817

19-
When you register on [base.dev](https://base.dev/), you will receive a **Builder Code**—a random string (e.g., `bc_b7k3p9da` ) that you'll use to generate your attribution suffix.
18+
When you register on [base.dev](https://base.dev/), you will receive a **Builder Code**—a random string (e.g., `bc_b7k3p9da`) that you'll use to generate your attribution suffix.
2019

2120
<Tip>
2221
You can find your code anytime under **Settings** → **Builder Code**.
2322
</Tip>
2423

25-
<Steps>
26-
<Step title="Install the Standard Library for Ethereum">
24+
The recommended approach is to configure `dataSuffix` at the client level, which automatically appends your Builder Code to all transactions.
25+
26+
<Note>
27+
Requires [viem](https://viem.sh) version 2.45.0 or higher, or [wagmi](https://wagmi.sh) version 2.17.0 or higher.
28+
</Note>
2729

28-
This will allow you to append the encoded version of your builder code.
30+
### Quick setup with Wagmi
2931

30-
```bash Terminal
31-
npm i ox
32-
```
33-
</Step>
32+
<Steps>
33+
<Step title="Install dependencies">
34+
Install the required packages. The `dataSuffix` feature requires viem version 2.45.0 or higher.
3435

35-
<Step title="Copy Your Builder Code">
36-
Navigate to **base.dev > Settings > Builder Codes** to find your unique builder code.
36+
```bash
37+
npm i ox wagmi viem
38+
```
3739
</Step>
3840

39-
<Step title="Create the Encoded Data Suffix">
40-
Use the `Attribution.toDataSuffix` method from the `ox` library to encode your builder code:
41+
<Step title="Configure your Wagmi client">
42+
Add the `dataSuffix` option to your Wagmi config. This automatically appends your Builder Code to all transactions.
4143

42-
```ts App.tsx
44+
```ts config.ts
45+
import { createConfig, http } from "wagmi";
46+
import { base } from "wagmi/chains";
4347
import { Attribution } from "ox/erc8021";
4448

49+
// Get your Builder Code from base.dev > Settings > Builder Codes
4550
const DATA_SUFFIX = Attribution.toDataSuffix({
46-
codes: ["YOUR-BUILDER-CODE"], // obtained from base.dev > Settings > Builder Codes
51+
codes: ["YOUR-BUILDER-CODE"],
52+
});
53+
54+
export const config = createConfig({
55+
chains: [base],
56+
transports: {
57+
[base.id]: http(),
58+
},
59+
dataSuffix: DATA_SUFFIX,
4760
});
4861
```
4962
</Step>
5063

51-
<Step title="Send transaction using the dataSuffix capability">
52-
Use Wagmi's `useSendCalls` hook with the `dataSuffix` capability to append attribution data to your transactions.
64+
<Step title="Use Wagmi hooks as usual">
65+
With the config in place, all transactions automatically include your Builder Code—no changes to your hooks or components. This works with both `useSendTransaction` and `useSendCalls`.
5366

54-
```ts App.tsx
55-
import { useSendCalls } from "wagmi";
67+
```tsx App.tsx
68+
import { useSendTransaction } from "wagmi";
5669
import { parseEther } from "viem";
57-
import { Attribution } from "ox/erc8021";
5870

59-
const DATA_SUFFIX = Attribution.toDataSuffix({
60-
codes: ["YOUR-BUILDER-CODE"],
61-
});
62-
63-
function App() {
64-
const { sendCalls } = useSendCalls();
71+
function SendButton() {
72+
const { sendTransaction } = useSendTransaction();
6573

6674
return (
6775
<button
6876
onClick={() =>
69-
sendCalls({
70-
calls: [
71-
{
72-
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
73-
value: parseEther("1"),
74-
},
75-
{
76-
data: "0xdeadbeef",
77-
to: "0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC",
78-
},
79-
],
80-
capabilities: {
81-
dataSuffix: {
82-
value: DATA_SUFFIX,
83-
optional: true,
84-
},
85-
},
77+
sendTransaction({
78+
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
79+
value: parseEther("0.01"),
8680
})
8781
}
8882
>
89-
Send calls
83+
Send ETH
9084
</button>
9185
);
9286
}
9387
```
9488
</Step>
9589
</Steps>
9690

91+
### Quick setup with Viem
92+
93+
<Steps>
94+
<Step title="Install dependencies">
95+
Install the required packages. The `dataSuffix` feature requires viem version 2.45.0 or higher.
96+
97+
```bash
98+
npm i ox viem
99+
```
100+
</Step>
101+
102+
<Step title="Configure your wallet client">
103+
Add the `dataSuffix` option when creating your wallet client. See the [viem wallet client docs](https://viem.sh/docs/clients/wallet) for more configuration options.
104+
105+
```ts client.ts
106+
import { createWalletClient, http } from "viem";
107+
import { base } from "viem/chains";
108+
import { Attribution } from "ox/erc8021";
109+
110+
// Get your Builder Code from base.dev > Settings > Builder Codes
111+
const DATA_SUFFIX = Attribution.toDataSuffix({
112+
codes: ["YOUR-BUILDER-CODE"],
113+
});
114+
115+
export const walletClient = createWalletClient({
116+
chain: base,
117+
transport: http(),
118+
dataSuffix: DATA_SUFFIX,
119+
});
120+
```
121+
</Step>
122+
123+
<Step title="Send transactions as usual">
124+
All transactions sent through this client automatically include your Builder Code.
125+
126+
```ts
127+
import { parseEther } from "viem";
128+
import { walletClient } from "./client";
129+
130+
const hash = await walletClient.sendTransaction({
131+
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
132+
value: parseEther("0.01"),
133+
});
134+
```
135+
</Step>
136+
</Steps>
137+
138+
### Legacy: Per-transaction approach
139+
140+
<Accordion title="Appending dataSuffix per-transaction">
141+
If you need to append the suffix on a per-transaction basis rather than at the client level, you can pass `dataSuffix` directly to the transaction.
142+
143+
<Tabs>
144+
<Tab title="useSendTransaction">
145+
```tsx App.tsx
146+
import { useSendTransaction } from "wagmi";
147+
import { parseEther } from "viem";
148+
import { Attribution } from "ox/erc8021";
149+
150+
const DATA_SUFFIX = Attribution.toDataSuffix({
151+
codes: ["YOUR-BUILDER-CODE"],
152+
});
153+
154+
function App() {
155+
const { sendTransaction } = useSendTransaction();
156+
157+
return (
158+
<button
159+
onClick={() =>
160+
sendTransaction({
161+
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
162+
value: parseEther("0.01"),
163+
dataSuffix: DATA_SUFFIX,
164+
})
165+
}
166+
>
167+
Send ETH
168+
</button>
169+
);
170+
}
171+
```
172+
</Tab>
173+
<Tab title="useSendCalls">
174+
When using `useSendCalls`, pass the suffix via the `capabilities` object. This requires the connected wallet to support the `dataSuffix` capability.
175+
176+
```tsx App.tsx
177+
import { useSendCalls } from "wagmi";
178+
import { parseEther } from "viem";
179+
import { Attribution } from "ox/erc8021";
180+
181+
const DATA_SUFFIX = Attribution.toDataSuffix({
182+
codes: ["YOUR-BUILDER-CODE"],
183+
});
184+
185+
function App() {
186+
const { sendCalls } = useSendCalls();
187+
188+
return (
189+
<button
190+
onClick={() =>
191+
sendCalls({
192+
calls: [
193+
{
194+
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
195+
value: parseEther("1"),
196+
},
197+
],
198+
capabilities: {
199+
dataSuffix: {
200+
value: DATA_SUFFIX,
201+
optional: true,
202+
},
203+
},
204+
})
205+
}
206+
>
207+
Send calls
208+
</button>
209+
);
210+
}
211+
```
212+
</Tab>
213+
</Tabs>
214+
</Accordion>
215+
216+
### Verify attribution
217+
218+
To confirm your Builder Code is being appended correctly, see [How do I verify that my transaction was properly attributed?](/base-chain/builder-codes/builder-codes-faq#how-do-i-verify-that-my-transaction-was-properly-attributed) in the FAQ.
219+
97220
## For Wallet Developers
98221

99222
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.
100223

101224
<Steps>
102-
<Step title="Support the dataSuffix Capability">
225+
<Step title="Support the dataSuffix capability">
103226
Your wallet should accept a `dataSuffix` object in the `capabilities` object of `wallet_sendCalls`.
104227

105-
```typescript lines
228+
```typescript
106229
type DataSuffixCapability = {
107230
value: `0x${string}`; // hex-encoded bytes provided by the app
108231
optional?: boolean; // whether the capability is optional
@@ -111,14 +234,14 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
111234
112235
</Step>
113236
114-
<Step title="Append Suffix to Calldata">
237+
<Step title="Append suffix to calldata">
115238
When constructing the transaction or User Operation, extract the `dataSuffix` and append it to the calldata.
116239
117240
<Tabs>
118241
<Tab title="EOA Transactions">
119242
Append to `tx.data`.
120243
121-
```typescript lines
244+
```typescript
122245
// Minimal example for EOA
123246
function applySuffixToEOA(tx, capabilities) {
124247
const suffix = capabilities.dataSuffix?.value
@@ -135,7 +258,7 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
135258
<Tab title="ERC-4337 User Operations">
136259
Append to `userOp.callData` (not the transaction-level calldata).
137260

138-
```typescript lines
261+
```typescript
139262
// Minimal example for ERC-4337
140263
function applySuffixToUserOp(userOp, capabilities) {
141264
const suffix = capabilities.dataSuffix?.value
@@ -152,11 +275,11 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
152275
</Tabs>
153276

154277
</Step>
155-
<Step title="(Optional) Add Wallet Attribution">
156-
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.
278+
<Step title="Add wallet attribution (optional)">
279+
Wallets may also include their own attribution code (their own ERC-8021 suffix) by prepending the wallet's suffix before the app's.
157280

158-
* **No interaction required with apps:** The wallet handles this independently.
159-
* **Multi-code support:** ERC-8021 natively supports multiple attribution codes.
281+
- **No interaction required with apps:** The wallet handles this independently.
282+
- **Multi-code support:** ERC-8021 natively supports multiple attribution codes.
160283

161284
**Example:**
162285

@@ -191,7 +314,7 @@ Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-sol
191314

192315
</Step>
193316

194-
<Step title="Attach to Bridge Message">
317+
<Step title="Attach to bridge message">
195318
Set `to = BRIDGE_CAMPAIGN_ADDRESS` and attach a call to `Flywheel.send`.
196319

197320
<Tabs>
@@ -251,7 +374,7 @@ Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-sol
251374
</Tabs>
252375

253376
</Step>
254-
<Step title="Learn More: A Full Implementation Example">
377+
<Step title="Learn more: A full implementation example">
255378
[Terminally Onchain](https://terminallyonchain.com/) is a production Next.js app that exposes the bridge via a command terminal UI. Users connect a Solana wallet, type commands such as to bridge and call a contract on Base:
256379

257380
You can use [Terminally Onchain](https://terminallyonchain.com/) to test bridge transactions with Builder Codes like so:

0 commit comments

Comments
 (0)