From e7144e20fdb2ec1686656ac17dbc748645a30e3d Mon Sep 17 00:00:00 2001 From: eric-brown Date: Wed, 19 Nov 2025 20:18:23 -0300 Subject: [PATCH 1/4] Add builder code docs --- .../quickstart/base-solana-bridge.mdx | 1 - docs/base-chain/quickstart/builder-codes.mdx | 178 ++++++++++++++++++ docs/docs.json | 3 +- 3 files changed, 180 insertions(+), 2 deletions(-) create mode 100644 docs/base-chain/quickstart/builder-codes.mdx diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index e7092aa3..fd21c281 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -1,7 +1,6 @@ --- title: "Base-Solana Bridge" description: "Bridge tokens and messages between Base and Solana" -icon: "bridge" --- import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx" diff --git a/docs/base-chain/quickstart/builder-codes.mdx b/docs/base-chain/quickstart/builder-codes.mdx new file mode 100644 index 00000000..b32e0062 --- /dev/null +++ b/docs/base-chain/quickstart/builder-codes.mdx @@ -0,0 +1,178 @@ +--- +title: "Builder Codes" +description: "Integrate Builder Codes to attribute onchain activity to your app or wallet." +--- + +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. + +## For App Developers + +Integrating Builder Codes requires appending a suffix—provided by Base—to your transaction data. + + + + When you register on **base.dev**, you will receive: + + * **Builder Code**: A random string (e.g., `k3p9da`). + * **ERC-8021 Suffix**: A hex-encoded string (e.g., `0x...`). + + You will use the **suffix** to attribute transactions to your app. + + + + 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. + + + + Use the `useSendCalls` hook from Wagmi's experimental features to pass the `dataSuffix` capability. + + ```typescript lines highlight={14-16} + import { useSendCalls } from 'wagmi/experimental' + + // Your suffix provided by base.dev + const dataSuffix = "0x1234abcd..." + + function SendTx() { + const { sendCalls } = useSendCalls() + + async function submit() { + await sendCalls({ + calls: [ + { + to: "0xYourContract", + data: "0xYourCalldata" + } + ], + capabilities: { + dataSuffix: dataSuffix + } + }) + } + + return + } + ``` + + + If you are using Viem directly, pass the `dataSuffix` in the `capabilities` object. + + ```typescript lines highlight={11-13} + import { walletClient } from './client' + + const dataSuffix = "0x1234abcd..." + + await walletClient.sendCalls({ + calls: [ + { + to: "0xYourContract", + data: "0xYourCalldata" + } + ], + capabilities: { + dataSuffix: dataSuffix + } + }) + ``` + + + 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. + + ```typescript lines highlight={15} + import { encodeFunctionData } from 'viem' + + // 1. Encode your function call + const encoded = encodeFunctionData({ + abi, + functionName: "yourFn", + args: [a, b, c], + }) + + // 2. Manually append the suffix (stripping the '0x' prefix from the suffix) + const dataWithSuffix = encoded + dataSuffix.slice(2) + + // 3. Send the transaction + await sendTransaction({ + to: "0xYourContract", + data: dataWithSuffix, + }) + ``` + + + + + +Once you have added the suffix, your app is fully ERC-8021 compliant. + +--- + +## For Wallet Developers + +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. + + + + Your wallet should accept a `dataSuffix` string in the `capabilities` object of `wallet_sendCalls`. + + ```typescript lines + interface DataSuffixCapability { + dataSuffix: string; // hex-encoded bytes provided by the app + } + ``` + + + + When constructing the transaction or User Operation, extract the `dataSuffix` and append it to the calldata. + + + + Append to `tx.data`. + + ```typescript lines + // Minimal example for EOA + function applySuffixToEOA(tx, capabilities) { + const suffix = capabilities.find(c => c.dataSuffix)?.dataSuffix + if (!suffix) return tx + + return { + ...tx, + // Append suffix bytes (remove 0x prefix from suffix if tx.data has it) + data: tx.data + suffix.slice(2) + } + } + ``` + + + Append to `userOp.callData` (not the transaction-level calldata). + + ```typescript lines + // Minimal example for ERC-4337 + function applySuffixToUserOp(userOp, capabilities) { + const suffix = capabilities.find(c => c.dataSuffix)?.dataSuffix + if (!suffix) return userOp + + return { + ...userOp, + // Append suffix bytes to the UserOp callData + callData: userOp.callData + suffix.slice(2) + } + } + ``` + + + + + 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. + + * **No interaction required with apps:** The wallet handles this independently. + * **Multi-code support:** ERC-8021 natively supports multiple attribution codes. + + **Example:** + + ```typescript + finalSuffix = walletSuffix + appSuffix + ``` + + This ensures both the app and the wallet receive onchain attribution. + + + diff --git a/docs/docs.json b/docs/docs.json index 55c5f64f..8982b2a8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -90,7 +90,8 @@ "base-chain/quickstart/deploy-on-base", "base-chain/quickstart/connecting-to-base", "base-chain/quickstart/bridge-token", - "base-chain/quickstart/base-solana-bridge" + "base-chain/quickstart/base-solana-bridge", + "base-chain/quickstart/builder-codes" ] }, { From 16dac09b0d5384eac1025e5a69b92b136cd098cc Mon Sep 17 00:00:00 2001 From: Eric Brown Date: Thu, 20 Nov 2025 12:43:51 -0300 Subject: [PATCH 2/4] Update docs/base-chain/quickstart/builder-codes.mdx Co-authored-by: Conner Swenberg --- docs/base-chain/quickstart/builder-codes.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/base-chain/quickstart/builder-codes.mdx b/docs/base-chain/quickstart/builder-codes.mdx index b32e0062..7c7468cc 100644 --- a/docs/base-chain/quickstart/builder-codes.mdx +++ b/docs/base-chain/quickstart/builder-codes.mdx @@ -28,9 +28,13 @@ Integrating Builder Codes requires appending a suffix—provided by Base—to yo ```typescript lines highlight={14-16} import { useSendCalls } from 'wagmi/experimental' - - // Your suffix provided by base.dev - const dataSuffix = "0x1234abcd..." + import { Attribution } from 'ox/erc8021' + + // Your builder code provided by base.dev + const builderCode = "abcd1234" + const dataSuffix = Attribution.toDataSuffix({ + codes: [builderCode] + }) function SendTx() { const { sendCalls } = useSendCalls() From 58cd75214a8ca3f912565102af7bab8ad365053c Mon Sep 17 00:00:00 2001 From: eric-brown Date: Thu, 20 Nov 2025 12:47:15 -0300 Subject: [PATCH 3/4] update to use only builder code --- docs/base-chain/quickstart/builder-codes.mdx | 25 +++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/base-chain/quickstart/builder-codes.mdx b/docs/base-chain/quickstart/builder-codes.mdx index 7c7468cc..9e1d36b7 100644 --- a/docs/base-chain/quickstart/builder-codes.mdx +++ b/docs/base-chain/quickstart/builder-codes.mdx @@ -10,13 +10,8 @@ Builder Codes allow you to attribute onchain activity to your app or wallet, unl Integrating Builder Codes requires appending a suffix—provided by Base—to your transaction data. - - When you register on **base.dev**, you will receive: - - * **Builder Code**: A random string (e.g., `k3p9da`). - * **ERC-8021 Suffix**: A hex-encoded string (e.g., `0x...`). - - You will use the **suffix** to attribute transactions to your app. + + When you register on **base.dev**, you will receive a **Builder Code**. This is a random string (e.g., `k3p9da`) that you will use to generate your attribution suffix. @@ -62,8 +57,13 @@ Integrating Builder Codes requires appending a suffix—provided by Base—to yo ```typescript lines highlight={11-13} import { walletClient } from './client' - - const dataSuffix = "0x1234abcd..." + import { Attribution } from 'ox/erc8021' + + // Your builder code provided by base.dev + const builderCode = "abcd1234" + const dataSuffix = Attribution.toDataSuffix({ + codes: [builderCode] + }) await walletClient.sendCalls({ calls: [ @@ -83,6 +83,13 @@ Integrating Builder Codes requires appending a suffix—provided by Base—to yo ```typescript lines highlight={15} import { encodeFunctionData } from 'viem' + import { Attribution } from 'ox/erc8021' + + // Your builder code provided by base.dev + const builderCode = "abcd1234" + const dataSuffix = Attribution.toDataSuffix({ + codes: [builderCode] + }) // 1. Encode your function call const encoded = encodeFunctionData({ From ad7404349b02c5b4f3e4be7dff4cf683757f6ea9 Mon Sep 17 00:00:00 2001 From: eric-brown Date: Fri, 21 Nov 2025 12:51:26 -0300 Subject: [PATCH 4/4] update to coming soon with callout at the top of the document --- docs/base-chain/quickstart/builder-codes.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/builder-codes.mdx b/docs/base-chain/quickstart/builder-codes.mdx index 9e1d36b7..739cd487 100644 --- a/docs/base-chain/quickstart/builder-codes.mdx +++ b/docs/base-chain/quickstart/builder-codes.mdx @@ -1,8 +1,14 @@ --- -title: "Builder Codes" +title: "Builder Codes (coming soon)" +sidebarTitle: "Builder Codes" description: "Integrate Builder Codes to attribute onchain activity to your app or wallet." --- + +Base will issue Builder Codes out of Base.dev starting **in early December**. We've released these docs ahead of launch to give teams time to understand implementation. + + + 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. ## For App Developers