Skip to content

Update builder codes #739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
youssefea wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Update builder codes #739

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f297175
update builder codes
youssefea Dec 17, 2025
b2bc450
add builder code example
youssefea Dec 18, 2025
360f632
update addresses on sepolia
youssefea Dec 18, 2025
d3c5563
Merge branch 'master' into update-builder-codes
youssefea Dec 18, 2025
634ed31
add callout
youssefea Dec 18, 2025
3f0f50f
maj bc
youssefea Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/base-chain/quickstart/base-solana-bridge.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,9 @@ Set `CDP_API_KEY` in your `.env` file to get access to the faucet.
"Bridge": "0x01824a90d32A69022DdAEcC6C5C14Ed08dB4EB9B",
"BridgeValidator": "0xa80C07DF38fB1A5b3E6a4f4FAAB71E7a056a4EC7",
"CrossChainERC20Factory": "0x488EB7F7cb2568e31595D48cb26F63963Cc7565D",
"SOL": "0xCace0c896714DaF7098FFD8CC54aFCFe0338b4BC"
"SOL": "0xCace0c896714DaF7098FFD8CC54aFCFe0338b4BC",
"FLYWHEEL_ADDRESS": "0x00000f14ad09382841db481403d1775adee1179f",
"BRIDGE_CAMPAIGN_ADDRESS": "0xb61A842E4361C53C3f3c376DF3758b330BD6201c"
}
```

Expand Down
119 changes: 102 additions & 17 deletions docs/base-chain/quickstart/builder-codes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Base Builder Codes"
title: "Base Builder Codes"
description: "Integrate Builder Codes to attribute onchain activity to your app or wallet."
---

Expand All @@ -14,7 +14,9 @@ Each code has associated metadata. Onchain metadata primarily includes a “payo
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.

<Warning>
**Builder Code analytics currently only support Smart Account (AA) transactions.** EOA support is coming soon. Your attribution data is preserved and will appear once EOA support is activated.
**Builder Code analytics currently only support Smart Account (AA)
transactions.** EOA support is coming soon. Your attribution data is preserved
and will appear once EOA support is activated.
</Warning>

## For App Developers
Expand All @@ -38,6 +40,7 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
dataSuffix: string; // hex-encoded bytes provided by the app
}
```

</Step>

<Step title="Append Suffix to Calldata">
Expand All @@ -56,7 +59,7 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
return {
...tx,
// Append suffix bytes (remove 0x prefix from suffix if tx.data has it)
data: tx.data + suffix.slice(2)
data: tx.data + suffix.slice(2)
}
}
```
Expand All @@ -79,6 +82,7 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
```
</Tab>
</Tabs>

</Step>
<Step title="(Optional) Add Wallet Attribution">
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.
Expand All @@ -93,20 +97,21 @@ Wallet providers need to support the `dataSuffix` capability to enable attributi
```

This ensures both the app and the wallet receive onchain attribution.

</Step>
</Steps>

## For Base-Solana Bridge Developers

<Warning>
Onchain Builder codes are currently still not live on mainnet.
Onchain Builder codes are currently still not live on mainnet.
</Warning>

Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-solana-bridge) via the [`hookData`](https://github.com/base/flywheel/blob/30266bba4649b0eb161e55bfa4755651049a5d1f/src/hooks/BridgeReferralFees.sol#L75) mechanism. Currently available for **Solana → Base** flows only.

<Steps>
<Step title="Get your Builder Code">
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.
When you register on base.dev, you will find a Builder Code under your app's settings. This is a random string (e.g., k3p9da) that you will use to generate your attribution suffix.
</Step>

<Step title="Build hookData">
Expand All @@ -119,6 +124,7 @@ Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-sol
100 // feeBps (100 = 1%)
);
```

</Step>

<Step title="Attach to Bridge Message">
Expand All @@ -129,15 +135,15 @@ Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-sol
For a bridge with no follow-up call:

```
to: <BRIDGE_CAMPAIGN_ADDRESS>
to: <BRIDGE_CAMPAIGN_ADDRESS> // 0xb61A842E4361C53C3f3c376DF3758b330BD6201c on Base Sepolia
amount: 100
call:
ty: Call
to: <FLYWHEEL_ADDRESS>
to: <FLYWHEEL_ADDRESS> // 0x00000f14ad09382841db481403d1775adee1179f on Base Sepolia
value: 0
data: abi.encodeWithSelector(
Flywheel.send.selector,
<BRIDGE_CAMPAIGN_ADDRESS>,
<BRIDGE_CAMPAIGN_ADDRESS>, // 0xb61A842E4361C53C3f3c376DF3758b330BD6201c on Base Sepolia
<wSOL_ADDRESS>,
hookData
)
Expand All @@ -151,12 +157,12 @@ Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-sol

// 1) Flywheel attribution (must be first)
calls[0] = Call({
to: <FLYWHEEL_ADDRESS>,
to: <FLYWHEEL_ADDRESS>, // 0x00000f14ad09382841db481403d1775adee1179f on Base Sepolia
value: 0,
data: abi.encodeWithSelector(
Flywheel.send.selector,
<BRIDGE_CAMPAIGN_ADDRESS>,
<SOL_ADDRESS>, // 0x311935Cd80B76769bF2ecC9D8Ab7635b2139cf82 on Base Mainnet
<BRIDGE_CAMPAIGN_ADDRESS>, // 0xb61A842E4361C53C3f3c376DF3758b330BD6201c on Base Sepolia
<TOKEN_ADDRESS>, // e.g. For SOL on Base Sepolia, use 0xCace0c896714DaF7098FFD8CC54aFCFe0338b4BC
hookData
)
});
Expand All @@ -179,16 +185,95 @@ Builder codes work with the [Base-Solana bridge](/base-chain/quickstart/base-sol
```
</Tab>
</Tabs>

</Step>
</Steps>
<Step title="Learn More: A Full Implementation Example">
[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:

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

## Give feedback!
```bash
bridge 0.0001 sol 0xYOUR_DESTINATION_ADDRESS --with-bc YOUR_BUILDER_CODE --bc-fee YOUR_FEE_BPS
```

<Note>
Base is constantly working to improve the Builder Codes experience. If you have any feedback, please let the team know [here](https://t.co/zwvtmXXzGz).
</Note>
To see how this is implemented, you can take a look at the [Github repo](https://github.com/base/sol2base/blob/e0c283035be1e3e345d329e2d77b05e29a1d38b3/src/components/MainContent.tsx#L667):

```typescript sol2base/MainContent.tsx expandable
// Constants
const BRIDGE_CAMPAIGN_ADDRESS = "0xb61A842E4361C53C3f3c376DF3758b330BD6201c";
const FLYWHEEL_ADDRESS = "0x00000f14ad09382841db481403d1775adee1179f";
const MULTICALL_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";

// Encode hookData: (address user, string code, uint8 feeBps)
const buildBuilderHookData = (
destination: string,
builderCode: string,
feeBps: number
) => {
const coder = new AbiCoder();
return coder.encode(
["address", "string", "uint8"],
[destination, builderCode, feeBps]
);
};

// Build Flywheel.send call
const buildBuilderCall = (
destination: string,
builderCode: string,
feeBps: number,
tokenAddress: string
): BaseContractCall => {
const hookData = buildBuilderHookData(destination, builderCode, feeBps);
const data = encodeFunctionData({
abi: FLYWHEEL_ABI,
functionName: "send",
args: [BRIDGE_CAMPAIGN_ADDRESS, tokenAddress, hookData],
});
return { type: "call", target: FLYWHEEL_ADDRESS, value: "0", data };
};

// Wrap builder + user calls in Multicall (for chained calls)
const buildMulticall = (
builder: BaseContractCall,
userCall: BaseContractCall
): BaseContractCall => {
const data = encodeFunctionData({
abi: MULTICALL_ABI,
functionName: "multicall",
args: [
[
{ target: builder.target, callData: builder.data },
{ target: userCall.target, callData: userCall.data },
],
],
});
return { type: "delegatecall", target: MULTICALL_ADDRESS, value: "0", data };
};

// Usage: attach builder code to bridge
if (payload.flags.withBc) {
const builderCall = buildBuilderCall(
destination,
builderCode,
feeBps,
remoteToken
);
callOption = userCall ? buildMulticall(builderCall, userCall) : builderCall;
}

// Set destination to campaign address when using builder codes
const destinationForBridge = builderCode
? BRIDGE_CAMPAIGN_ADDRESS
: payload.destination;
```

</Step>
</Steps>

## Give feedback!

<Note>
Base is constantly working to improve the Builder Codes experience. If you
have any feedback, please let the team know [here](https://t.co/zwvtmXXzGz).
</Note>