From 5ea82fdf94051e71daf8ba8ddda5912aa2cf5c0f Mon Sep 17 00:00:00 2001 From: Po Date: Fri, 13 Mar 2026 18:40:17 +0800 Subject: [PATCH 1/3] 8021: initial doc --- developer/builder-codes/app-developers.mdx | 224 ++++++++++++++++++ developer/builder-codes/overview.mdx | 70 ++++++ developer/builder-codes/wallet-developers.mdx | 57 +++++ xlayer-docs.js | 9 + 4 files changed, 360 insertions(+) create mode 100644 developer/builder-codes/app-developers.mdx create mode 100644 developer/builder-codes/overview.mdx create mode 100644 developer/builder-codes/wallet-developers.mdx diff --git a/developer/builder-codes/app-developers.mdx b/developer/builder-codes/app-developers.mdx new file mode 100644 index 0000000..98328c7 --- /dev/null +++ b/developer/builder-codes/app-developers.mdx @@ -0,0 +1,224 @@ +# Builder Codes for App Developers + +Integrate Builder Codes into your app using Wagmi or Viem to attribute onchain activity on X Layer. + +## Automatic Attribution on X Layer + +Once your app is registered on the [OKX developer portal](https://www.okx.com/xlayer/developer), the OKX Wallet will auto-append your Builder Code to transactions its users make in your app. This powers your onchain analytics and qualifies you for potential future rewards. + +## Integrating Outside the OKX Wallet + +If users also access your app on the web or through other clients, you'll need to integrate the `dataSuffix` parameter to capture that activity. + +When you register, you will receive a **Builder Code**—a 16-character random string (e.g., `8k3m1v0q7z2c9a5x`) that you'll use to generate your attribution suffix. The recommended approach is to configure `dataSuffix` at the client level, which appends your Builder Code to all transactions. + +> **Note:** You can find your code anytime under **Settings** → **Builder Code** in the OKX developer portal. + +## Quick Setup with Wagmi + +Requires viem version `2.45.0` or higher. + +1. Install the required packages: + +```bash +npm i ox wagmi viem +``` + +2. Add the `dataSuffix` option to your Wagmi config. This automatically appends your Builder Code to all transactions. + +```ts +// config.ts +import { createConfig, http } from "wagmi"; +import { defineChain } from "viem"; +import { Attribution } from "ox/erc8021"; + +const xlayer = defineChain({ + id: 196, + name: "X Layer", + nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, + rpcUrls: { + default: { http: ["https://rpc.xlayer.tech"] }, + }, + blockExplorers: { + default: { name: "OKLink", url: "https://www.oklink.com/xlayer" }, + }, +}); + +// Get your Builder Code from the OKX developer portal > Settings > Builder Codes +const DATA_SUFFIX = Attribution.toDataSuffix({ + codes: ["YOUR-BUILDER-CODE"], +}); + +export const config = createConfig({ + chains: [xlayer], + transports: { + [xlayer.id]: http(), + }, + dataSuffix: DATA_SUFFIX, +}); +``` + +3. With the config in place, transactions sent via `useSendTransaction` and `useSendCalls` automatically include your Builder Code with no further changes. `useSendCalls` requires the connected wallet to support the `dataSuffix` capability. + +```tsx +// App.tsx +import { useSendTransaction } from "wagmi"; +import { parseEther } from "viem"; + +function SendButton() { + const { sendTransaction } = useSendTransaction(); + + return ( + + ); +} +``` + +## Quick Setup with Viem + +Requires viem version `2.45.0` or higher. + +1. Install the required packages: + +```bash +npm i ox viem +``` + +2. Add the `dataSuffix` option when creating your wallet client. + +```ts +// client.ts +import { createWalletClient, http, defineChain } from "viem"; +import { Attribution } from "ox/erc8021"; + +const xlayer = defineChain({ + id: 196, + name: "X Layer", + nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, + rpcUrls: { + default: { http: ["https://rpc.xlayer.tech"] }, + }, + blockExplorers: { + default: { name: "OKLink", url: "https://www.oklink.com/xlayer" }, + }, +}); + +// Get your Builder Code from the OKX developer portal > Settings > Builder Codes +const DATA_SUFFIX = Attribution.toDataSuffix({ + codes: ["YOUR-BUILDER-CODE"], +}); + +export const walletClient = createWalletClient({ + chain: xlayer, + transport: http(), + dataSuffix: DATA_SUFFIX, +}); +``` + +3. All transactions sent through this client automatically include your Builder Code. + +```ts +import { parseEther } from "viem"; +import { walletClient } from "./client"; + +const hash = await walletClient.sendTransaction({ + to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", + value: parseEther("0.01"), +}); +``` + +## Using Privy + +Privy provides a `dataSuffix` plugin that automatically appends your Builder Code to all EOA transactions (ERC-4337 smart wallet user operations will be supported in the future). + +See the [Privy Builder Codes integration guide](https://docs.privy.io/recipes/evm/base-builder-codes) for setup instructions. When configuring for X Layer, use chain ID `196` (mainnet) or `195` (testnet). + +## Per-Transaction Approach + +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. + +### useSendTransaction + +```tsx +// App.tsx +import { useSendTransaction } from "wagmi"; +import { parseEther } from "viem"; +import { Attribution } from "ox/erc8021"; + +const DATA_SUFFIX = Attribution.toDataSuffix({ + codes: ["YOUR-BUILDER-CODE"], +}); + +function App() { + const { sendTransaction } = useSendTransaction(); + + return ( + + ); +} +``` + +### useSendCalls + +When using `useSendCalls`, pass the suffix via the `capabilities` object. This requires the connected wallet to support the `dataSuffix` capability. + +```tsx +// App.tsx +import { useSendCalls } from "wagmi"; +import { parseEther } from "viem"; +import { Attribution } from "ox/erc8021"; + +const DATA_SUFFIX = Attribution.toDataSuffix({ + codes: ["YOUR-BUILDER-CODE"], +}); + +function App() { + const { sendCalls } = useSendCalls(); + + return ( + + ); +} +``` + +## Verify Attribution + +> See [How Do I Verify That My Transaction Was Properly Attributed?](/developer/builder-codes/overview#how-do-i-verify-that-my-transaction-was-properly-attributed) for attribution verification steps. diff --git a/developer/builder-codes/overview.mdx b/developer/builder-codes/overview.mdx new file mode 100644 index 0000000..1b78aea --- /dev/null +++ b/developer/builder-codes/overview.mdx @@ -0,0 +1,70 @@ +# Builder Codes + +Attribute onchain activity to your app or wallet with Builder Codes on X Layer. + +## What Are Builder Codes + +X Layer Builder Codes are an ERC-721 NFT collection where unique 16-character codes (e.g. "8k3m1v0q7z2c9a5x") are minted to help identify builders onchain. + +Each code has associated metadata. Onchain metadata primarily includes a "payout address" where each code declares where potential rewards should be sent to. + +> **Note:** Get your Builder Code by registering on the [OKX developer portal](https://www.okx.com/xlayer/developer). You can find your code under **Settings** → **Builder Code**. + +## Integration Guides + +- [For App Developers](/developer/builder-codes/app-developers) — Integrate Builder Codes using Wagmi or Viem +- [For Wallet Developers](/developer/builder-codes/wallet-developers) — Implement the dataSuffix capability + +## Benefits + +- **Rewards:** If your app drives transactions, Builder Codes let X Layer automatically attribute that usage back to you, unlocking rewards as the program expands. +- **Analytics:** Reliably track onchain usage, user acquisition, and conversion metrics in the OKX developer portal. +- **Visibility:** Apps with Builder Codes can show up in discovery surfaces like App Leaderboards and ecosystem spotlights. + +## FAQ + +### Do I Need to Modify My Smart Contracts? + +No. The attribution suffix is appended to the end of transaction calldata. Smart contracts execute normally and ignore the extra data. Attribution is extracted by offchain indexers after the fact. + +This means: + +- Any existing smart contract automatically supports ERC-8021 +- No upgrades or redeployments required +- Zero impact on contract execution + +### How Much Additional Gas Do Builder Codes Cost? + +The ERC-8021 suffix adds a negligible amount of gas to each transaction at 16 gas per non-zero byte. + +### Can I Use ERC-8021 with Externally Owned Accounts (EOAs)? + +Yes. ERC-8021 works with both EOAs and ERC-7702 smart wallets. + +### How Do I Verify That My Transaction Was Properly Attributed? + +**1. Use a Block Explorer (OKLink)** + +- Find your transaction hash on [OKLink](https://www.oklink.com/xlayer) +- View the input data field +- Verify the last 16 bytes are the `8021` repeating, and view the decoded attribution data to confirm your Builder Code is included. + +**2. Open Source Tools** + +- Use the [Builder Code Validation](https://nextjs-boilerplate-silk-gamma-760zp49dit.vercel.app/) tool +- Enter the input data of the transaction +- Click the **Check Attribution** button + +### Which Wallets Currently Support ERC-8021? + +**EOAs:** Transactions from EOA wallets and ERC-7702 smart wallets can include an ERC-8021 suffix when the app or client appends it. + +**4337 Smart Wallets:** Not supported yet, will be supported in the future. + +**Embedded Wallets:** + +- **Privy** - Embedded wallet solution with ERC-8021 capability + +## Additional Resources + +- [Official ERC-8021 Proposal](https://eip.tools/eip/8021) diff --git a/developer/builder-codes/wallet-developers.mdx b/developer/builder-codes/wallet-developers.mdx new file mode 100644 index 0000000..dcb9b87 --- /dev/null +++ b/developer/builder-codes/wallet-developers.mdx @@ -0,0 +1,57 @@ +# Builder Codes for Wallet Developers + +Implement the `dataSuffix` capability in your wallet to enable Builder Code attribution on X Layer. + +## Overview + +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. + +## Implementation + +### 1. Support the dataSuffix Capability + +Your wallet should accept a `dataSuffix` object in the `capabilities` object of `wallet_sendCalls`. + +```typescript +type DataSuffixCapability = { + value: `0x${string}`; // hex-encoded bytes provided by the app + optional?: boolean; // whether the capability is optional +} +``` + +### 2. Append Suffix to Calldata + +When constructing the transaction, extract the `dataSuffix` and append it to the calldata. + +**EOA Transactions** — append to `tx.data`: + +```typescript +// Minimal example for EOA +function applySuffixToEOA(tx, capabilities) { + const suffix = capabilities.dataSuffix?.value + 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) + } +} +``` + +**ERC-4337 User Operations** — not supported yet. + +### 3. Add Wallet Attribution (Optional) + +Wallets may also include their own attribution code (their own ERC-8021 suffix) by prepending the wallet's 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. + +```typescript +finalSuffix = walletSuffix + appSuffix +``` + +This ensures both the app and the wallet receive onchain attribution on X Layer. + +> **Note:** Get your Builder Code by registering on the [OKX developer portal](https://www.okx.com/xlayer/developer). You can find your code under **Settings** → **Builder Code**. diff --git a/xlayer-docs.js b/xlayer-docs.js index e6f90ee..13cb603 100644 --- a/xlayer-docs.js +++ b/xlayer-docs.js @@ -74,6 +74,15 @@ module.exports = [ '/developer/flashblocks/faq', ], }, + + { + title: 'Builder Codes', + path: '/developer/builder-codes/overview', + children: [ + '/developer/builder-codes/app-developers', + '/developer/builder-codes/wallet-developers', + ], + }, ] }, From 844b3c86599593333a0e981ed9bfaf5985bdbc40 Mon Sep 17 00:00:00 2001 From: Po Date: Tue, 17 Mar 2026 18:34:19 +0800 Subject: [PATCH 2/3] doc(8021): remove privy --- developer/builder-codes/app-developers.mdx | 6 ------ developer/builder-codes/overview.mdx | 6 +----- 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/developer/builder-codes/app-developers.mdx b/developer/builder-codes/app-developers.mdx index 98328c7..cbd213d 100644 --- a/developer/builder-codes/app-developers.mdx +++ b/developer/builder-codes/app-developers.mdx @@ -136,12 +136,6 @@ const hash = await walletClient.sendTransaction({ }); ``` -## Using Privy - -Privy provides a `dataSuffix` plugin that automatically appends your Builder Code to all EOA transactions (ERC-4337 smart wallet user operations will be supported in the future). - -See the [Privy Builder Codes integration guide](https://docs.privy.io/recipes/evm/base-builder-codes) for setup instructions. When configuring for X Layer, use chain ID `196` (mainnet) or `195` (testnet). - ## Per-Transaction Approach 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. diff --git a/developer/builder-codes/overview.mdx b/developer/builder-codes/overview.mdx index 1b78aea..ef97e20 100644 --- a/developer/builder-codes/overview.mdx +++ b/developer/builder-codes/overview.mdx @@ -29,7 +29,7 @@ No. The attribution suffix is appended to the end of transaction calldata. Smart This means: -- Any existing smart contract automatically supports ERC-8021 +- Any existing smart contract automatically supports ERC-8021, but **developers should verify that their calldata parsing logic is not affected by the additional suffix data**. - No upgrades or redeployments required - Zero impact on contract execution @@ -61,10 +61,6 @@ Yes. ERC-8021 works with both EOAs and ERC-7702 smart wallets. **4337 Smart Wallets:** Not supported yet, will be supported in the future. -**Embedded Wallets:** - -- **Privy** - Embedded wallet solution with ERC-8021 capability - ## Additional Resources - [Official ERC-8021 Proposal](https://eip.tools/eip/8021) From b31abf60c43500b184a4da73e04509be2726022b Mon Sep 17 00:00:00 2001 From: Po Date: Tue, 17 Mar 2026 19:56:27 +0800 Subject: [PATCH 3/3] 8021: update doc --- .../{app-developers.mdx => integration.mdx} | 141 +++++++++++------- developer/builder-codes/overview.mdx | 68 ++++----- ...et-developers.mdx => wallet-providers.mdx} | 14 +- xlayer-docs.js | 4 +- 4 files changed, 122 insertions(+), 105 deletions(-) rename developer/builder-codes/{app-developers.mdx => integration.mdx} (52%) rename developer/builder-codes/{wallet-developers.mdx => wallet-providers.mdx} (63%) diff --git a/developer/builder-codes/app-developers.mdx b/developer/builder-codes/integration.mdx similarity index 52% rename from developer/builder-codes/app-developers.mdx rename to developer/builder-codes/integration.mdx index cbd213d..dc5f95b 100644 --- a/developer/builder-codes/app-developers.mdx +++ b/developer/builder-codes/integration.mdx @@ -1,50 +1,65 @@ -# Builder Codes for App Developers +# Integrate Builder Codes -Integrate Builder Codes into your app using Wagmi or Viem to attribute onchain activity on X Layer. +Add ERC-8021 attribution to your app on X Layer using Wagmi or Viem to attribute onchain activity on X Layer. -## Automatic Attribution on X Layer +## Prerequisites -Once your app is registered on the [OKX developer portal](https://www.okx.com/xlayer/developer), the OKX Wallet will auto-append your Builder Code to transactions its users make in your app. This powers your onchain analytics and qualifies you for potential future rewards. +Requires viem `2.45.0` or higher. Define the X Layer chain(s) you need and reuse them across your config: -## Integrating Outside the OKX Wallet +```ts +// chain.ts +import { defineChain } from "viem"; + +export const xlayer = defineChain({ + id: 196, + name: "X Layer", + nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, + rpcUrls: { + default: { http: ["https://rpc.xlayer.tech"] }, + }, + blockExplorers: { + default: { name: "OKLink", url: "https://www.oklink.com/xlayer" }, + }, +}); -If users also access your app on the web or through other clients, you'll need to integrate the `dataSuffix` parameter to capture that activity. +export const xlayerTestnet = defineChain({ + id: 1952, + name: "X Layer Testnet", + nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, + rpcUrls: { + default: { http: ["https://testrpc.xlayer.tech"] }, + }, + blockExplorers: { + default: { name: "OKLink", url: "https://www.oklink.com/x-layer-testnet" }, + }, +}); +``` -When you register, you will receive a **Builder Code**—a 16-character random string (e.g., `8k3m1v0q7z2c9a5x`) that you'll use to generate your attribution suffix. The recommended approach is to configure `dataSuffix` at the client level, which appends your Builder Code to all transactions. +**Get your Builder Code** -> **Note:** You can find your code anytime under **Settings** → **Builder Code** in the OKX developer portal. +- **Mainnet:** Register on the [OKX developer portal](https://www.okx.com/xlayer/developer) under **Settings** → **Builder Code**. +- **Testnet:** Connect your wallet and call `registerAuto` on the [Builder Code registry contract](https://www.oklink.com/zh-hans/x-layer-testnet/address/0x00a3b805dbf39e5d54f9d09c130ff2132b4a0a21/contract#category=proxy-write). Need testnet OKB? Use the [faucet](https://www.okx.com/xlayer/faucet). -## Quick Setup with Wagmi +## Client-Level Setup -Requires viem version `2.45.0` or higher. +Configure `dataSuffix` once at the client level. All transactions sent through this client automatically include your Builder Code. -1. Install the required packages: +### Wagmi + +1. Install dependencies: ```bash npm i ox wagmi viem ``` -2. Add the `dataSuffix` option to your Wagmi config. This automatically appends your Builder Code to all transactions. +2. Add `dataSuffix` to your Wagmi config: ```ts // config.ts import { createConfig, http } from "wagmi"; -import { defineChain } from "viem"; import { Attribution } from "ox/erc8021"; +import { xlayer } from "./chain"; -const xlayer = defineChain({ - id: 196, - name: "X Layer", - nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, - rpcUrls: { - default: { http: ["https://rpc.xlayer.tech"] }, - }, - blockExplorers: { - default: { name: "OKLink", url: "https://www.oklink.com/xlayer" }, - }, -}); - -// Get your Builder Code from the OKX developer portal > Settings > Builder Codes const DATA_SUFFIX = Attribution.toDataSuffix({ codes: ["YOUR-BUILDER-CODE"], }); @@ -58,7 +73,7 @@ export const config = createConfig({ }); ``` -3. With the config in place, transactions sent via `useSendTransaction` and `useSendCalls` automatically include your Builder Code with no further changes. `useSendCalls` requires the connected wallet to support the `dataSuffix` capability. +3. Transactions via `useSendTransaction` automatically include your Builder Code: ```tsx // App.tsx @@ -83,36 +98,58 @@ function SendButton() { } ``` -## Quick Setup with Viem +For batch transactions, use `useSendCalls` and pass the suffix via `capabilities`: + +```tsx +import { useSendCalls } from "wagmi"; +import { parseEther } from "viem"; + +function SendCallsButton() { + const { sendCalls } = useSendCalls(); + + return ( + + ); +} +``` + +> **Note:** `useSendCalls` requires the connected wallet to support the `dataSuffix` capability. -Requires viem version `2.45.0` or higher. +### Viem -1. Install the required packages: +1. Install dependencies: ```bash npm i ox viem ``` -2. Add the `dataSuffix` option when creating your wallet client. +2. Add `dataSuffix` when creating your wallet client: ```ts // client.ts -import { createWalletClient, http, defineChain } from "viem"; +import { createWalletClient, http } from "viem"; import { Attribution } from "ox/erc8021"; +import { xlayer } from "./chain"; -const xlayer = defineChain({ - id: 196, - name: "X Layer", - nativeCurrency: { name: "OKB", symbol: "OKB", decimals: 18 }, - rpcUrls: { - default: { http: ["https://rpc.xlayer.tech"] }, - }, - blockExplorers: { - default: { name: "OKLink", url: "https://www.oklink.com/xlayer" }, - }, -}); - -// Get your Builder Code from the OKX developer portal > Settings > Builder Codes const DATA_SUFFIX = Attribution.toDataSuffix({ codes: ["YOUR-BUILDER-CODE"], }); @@ -124,7 +161,7 @@ export const walletClient = createWalletClient({ }); ``` -3. All transactions sent through this client automatically include your Builder Code. +3. All transactions sent through this client include your Builder Code: ```ts import { parseEther } from "viem"; @@ -136,14 +173,13 @@ const hash = await walletClient.sendTransaction({ }); ``` -## Per-Transaction Approach +## Per-Transaction Configuration -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. +If you need granular control, pass `dataSuffix` directly on individual transactions instead of at the client level. ### useSendTransaction ```tsx -// App.tsx import { useSendTransaction } from "wagmi"; import { parseEther } from "viem"; import { Attribution } from "ox/erc8021"; @@ -173,10 +209,11 @@ function App() { ### useSendCalls -When using `useSendCalls`, pass the suffix via the `capabilities` object. This requires the connected wallet to support the `dataSuffix` capability. +Pass the suffix via the `capabilities` object. + +> **Note:** `useSendCalls` requires the connected wallet to support the `dataSuffix` capability. ```tsx -// App.tsx import { useSendCalls } from "wagmi"; import { parseEther } from "viem"; import { Attribution } from "ox/erc8021"; @@ -215,4 +252,4 @@ function App() { ## Verify Attribution -> See [How Do I Verify That My Transaction Was Properly Attributed?](/developer/builder-codes/overview#how-do-i-verify-that-my-transaction-was-properly-attributed) for attribution verification steps. +> See [Verify Attribution](/developer/builder-codes/overview#verify-attribution) for steps to confirm your transaction was properly attributed. diff --git a/developer/builder-codes/overview.mdx b/developer/builder-codes/overview.mdx index ef97e20..ea69a37 100644 --- a/developer/builder-codes/overview.mdx +++ b/developer/builder-codes/overview.mdx @@ -4,63 +4,47 @@ Attribute onchain activity to your app or wallet with Builder Codes on X Layer. ## What Are Builder Codes -X Layer Builder Codes are an ERC-721 NFT collection where unique 16-character codes (e.g. "8k3m1v0q7z2c9a5x") are minted to help identify builders onchain. +X Layer Builder Codes are an ERC-721 NFT collection where unique 16-character codes (e.g. `8k3m1v0q7z2c9a5x`) identify builders onchain. Each code has a "payout address" in its metadata — this is where potential rewards are sent. -Each code has associated metadata. Onchain metadata primarily includes a "payout address" where each code declares where potential rewards should be sent to. +Builder Codes give you: -> **Note:** Get your Builder Code by registering on the [OKX developer portal](https://www.okx.com/xlayer/developer). You can find your code under **Settings** → **Builder Code**. +- **Rewards:** Attribute transactions back to your app and unlock rewards as the program expands. +- **Analytics:** Track onchain usage, user acquisition, and conversion metrics in the OKX developer portal. +- **Visibility:** Apps with Builder Codes can appear in discovery surfaces like App Leaderboards and ecosystem spotlights. -## Integration Guides +> **Get your Builder Code:** Register on the [OKX developer portal](https://www.okx.com/xlayer/developer), then go to **Settings** → **Builder Code**. -- [For App Developers](/developer/builder-codes/app-developers) — Integrate Builder Codes using Wagmi or Viem -- [For Wallet Developers](/developer/builder-codes/wallet-developers) — Implement the dataSuffix capability +## How It Works -## Benefits +When a transaction is sent, an [ERC-8021](https://eip.tools/eip/8021) attribution suffix is appended to the end of the calldata. The suffix contains your Builder Code and is extracted by offchain indexers — it does not affect contract execution. No smart contract changes are required. -- **Rewards:** If your app drives transactions, Builder Codes let X Layer automatically attribute that usage back to you, unlocking rewards as the program expands. -- **Analytics:** Reliably track onchain usage, user acquisition, and conversion metrics in the OKX developer portal. -- **Visibility:** Apps with Builder Codes can show up in discovery surfaces like App Leaderboards and ecosystem spotlights. +The suffix adds negligible gas: 16 gas per non-zero byte. -## FAQ +Wallets that support the `dataSuffix` capability append it to calldata before signing. EOAs and ERC-7702 smart wallets are supported. ERC-4337 user operations are not yet supported. -### Do I Need to Modify My Smart Contracts? +> **Note:** Automatic Builder Code injection is not yet available in OKX Wallet. You need to configure `dataSuffix` in your app as described in the integration guide. -No. The attribution suffix is appended to the end of transaction calldata. Smart contracts execute normally and ignore the extra data. Attribution is extracted by offchain indexers after the fact. +## Get Started -This means: +**App developers** -- Any existing smart contract automatically supports ERC-8021, but **developers should verify that their calldata parsing logic is not affected by the additional suffix data**. -- No upgrades or redeployments required -- Zero impact on contract execution +1. Register on the [OKX developer portal](https://www.okx.com/xlayer/developer) and get your Builder Code under **Settings** → **Builder Code**. +2. Follow the [Integration Guide](/developer/builder-codes/integration) to add attribution to your app. -### How Much Additional Gas Do Builder Codes Cost? +**Wallet providers** -The ERC-8021 suffix adds a negligible amount of gas to each transaction at 16 gas per non-zero byte. +See the [Wallet Provider Guide](/developer/builder-codes/wallet-providers). -### Can I Use ERC-8021 with Externally Owned Accounts (EOAs)? +## Verify Attribution -Yes. ERC-8021 works with both EOAs and ERC-7702 smart wallets. +**Option 1 — OKLink Explorer** -### How Do I Verify That My Transaction Was Properly Attributed? +1. Find your transaction on [OKLink](https://www.oklink.com/xlayer). +2. Open the input data field. +3. Verify the last 16 bytes are the `8021` repeating pattern, and check the decoded attribution data for your Builder Code. -**1. Use a Block Explorer (OKLink)** +**Option 2 — Open Source Tool** -- Find your transaction hash on [OKLink](https://www.oklink.com/xlayer) -- View the input data field -- Verify the last 16 bytes are the `8021` repeating, and view the decoded attribution data to confirm your Builder Code is included. - -**2. Open Source Tools** - -- Use the [Builder Code Validation](https://nextjs-boilerplate-silk-gamma-760zp49dit.vercel.app/) tool -- Enter the input data of the transaction -- Click the **Check Attribution** button - -### Which Wallets Currently Support ERC-8021? - -**EOAs:** Transactions from EOA wallets and ERC-7702 smart wallets can include an ERC-8021 suffix when the app or client appends it. - -**4337 Smart Wallets:** Not supported yet, will be supported in the future. - -## Additional Resources - -- [Official ERC-8021 Proposal](https://eip.tools/eip/8021) +1. Open the [Builder Code Validation](https://nextjs-boilerplate-silk-gamma-760zp49dit.vercel.app/) tool. +2. Paste the transaction input data. +3. Click **Check Attribution**. diff --git a/developer/builder-codes/wallet-developers.mdx b/developer/builder-codes/wallet-providers.mdx similarity index 63% rename from developer/builder-codes/wallet-developers.mdx rename to developer/builder-codes/wallet-providers.mdx index dcb9b87..ec0181d 100644 --- a/developer/builder-codes/wallet-developers.mdx +++ b/developer/builder-codes/wallet-providers.mdx @@ -1,16 +1,12 @@ -# Builder Codes for Wallet Developers +# Builder Codes for Wallet Providers -Implement the `dataSuffix` capability in your wallet to enable Builder Code attribution on X Layer. - -## Overview - -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. +If you are building a wallet and want to support ERC-8021 attribution for apps running on X Layer, implement the following. ## Implementation ### 1. Support the dataSuffix Capability -Your wallet should accept a `dataSuffix` object in the `capabilities` object of `wallet_sendCalls`. +Your wallet should accept a `dataSuffix` object in the `capabilities` field of `wallet_sendCalls`. ```typescript type DataSuffixCapability = { @@ -43,7 +39,7 @@ function applySuffixToEOA(tx, capabilities) { ### 3. Add Wallet Attribution (Optional) -Wallets may also include their own attribution code (their own ERC-8021 suffix) by prepending the wallet's suffix before the app's. +Wallets may include their own Builder Code by prepending the wallet's suffix before the app's suffix. - **No interaction required with apps:** The wallet handles this independently. - **Multi-code support:** ERC-8021 natively supports multiple attribution codes. @@ -54,4 +50,4 @@ finalSuffix = walletSuffix + appSuffix This ensures both the app and the wallet receive onchain attribution on X Layer. -> **Note:** Get your Builder Code by registering on the [OKX developer portal](https://www.okx.com/xlayer/developer). You can find your code under **Settings** → **Builder Code**. +> **Get your Builder Code:** Register on the [OKX developer portal](https://www.okx.com/xlayer/developer) under **Settings** → **Builder Code**. diff --git a/xlayer-docs.js b/xlayer-docs.js index 13cb603..56342d7 100644 --- a/xlayer-docs.js +++ b/xlayer-docs.js @@ -79,8 +79,8 @@ module.exports = [ title: 'Builder Codes', path: '/developer/builder-codes/overview', children: [ - '/developer/builder-codes/app-developers', - '/developer/builder-codes/wallet-developers', + '/developer/builder-codes/integration', + '/developer/builder-codes/wallet-providers', ], }, ]