X Layer 8021 support

developer/builder-codes/integration.mdx

@@ -0,0 +1,255 @@
+# Integrate Builder Codes
+
+Add ERC-8021 attribution to your app on X Layer using Wagmi or Viem to attribute onchain activity on X Layer.
+
+## Prerequisites
+
+Requires viem `2.45.0` or higher. Define the X Layer chain(s) you need and reuse them across your config:
+
+```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" },
+  },
+});
+
+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" },
+  },
+});
+```
+
+**Get your Builder Code**
+
+- **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).
+
+## Client-Level Setup
+
+Configure `dataSuffix` once at the client level. All transactions sent through this client automatically include your Builder Code.
+
+### Wagmi
+
+1. Install dependencies:
+
+```bash
+npm i ox wagmi viem
+```
+
+2. Add `dataSuffix` to your Wagmi config:
+
+```ts
+// config.ts
+import { createConfig, http } from "wagmi";
+import { Attribution } from "ox/erc8021";
+import { xlayer } from "./chain";
+
+const DATA_SUFFIX = Attribution.toDataSuffix({
+  codes: ["YOUR-BUILDER-CODE"],
+});
+
+export const config = createConfig({
+  chains: [xlayer],
+  transports: {
+    [xlayer.id]: http(),
+  },
+  dataSuffix: DATA_SUFFIX,
+});
+```
+
+3. Transactions via `useSendTransaction` automatically include your Builder Code:
+
+```tsx
+// App.tsx
+import { useSendTransaction } from "wagmi";
+import { parseEther } from "viem";
+
+function SendButton() {
+  const { sendTransaction } = useSendTransaction();
+
+  return (
+    <button
+      onClick={() =>
+        sendTransaction({
+          to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
+          value: parseEther("0.01"),
+        })
+      }
+    >
+      Send OKB
+    </button>
+  );
+}
+```
+
+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 (
+    <button
+      onClick={() =>
+        sendCalls({
+          calls: [
+            {
+              to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
+              value: parseEther("0.01"),
+            },
+          ],
+          capabilities: {
+            dataSuffix: {
+              value: DATA_SUFFIX,
+              optional: true,
+            },
+          },
+        })
+      }
+    >
+      Send calls
+    </button>
+  );
+}
+```
+
+> **Note:** `useSendCalls` requires the connected wallet to support the `dataSuffix` capability.
+
+### Viem
+
+1. Install dependencies:
+
+```bash
+npm i ox viem
+```
+
+2. Add `dataSuffix` when creating your wallet client:
+
+```ts
+// client.ts
+import { createWalletClient, http } from "viem";
+import { Attribution } from "ox/erc8021";
+import { xlayer } from "./chain";
+
+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 include your Builder Code:
+
+```ts
+import { parseEther } from "viem";
+import { walletClient } from "./client";
+
+const hash = await walletClient.sendTransaction({
+  to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
+  value: parseEther("0.01"),
+});
+```
+
+## Per-Transaction Configuration
+
+If you need granular control, pass `dataSuffix` directly on individual transactions instead of at the client level.
+
+### useSendTransaction
+
+```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 (
+    <button
+      onClick={() =>
+        sendTransaction({
+          to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
+          value: parseEther("0.01"),
+          dataSuffix: DATA_SUFFIX,
+        })
+      }
+    >
+      Send OKB
+    </button>
+  );
+}
+```
+
+### useSendCalls
+
+Pass the suffix via the `capabilities` object.
+
+> **Note:** `useSendCalls` requires the connected wallet to support the `dataSuffix` capability.
+
+```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 (
+    <button
+      onClick={() =>
+        sendCalls({
+          calls: [
+            {
+              to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
+              value: parseEther("1"),
+            },
+          ],
+          capabilities: {
+            dataSuffix: {
+              value: DATA_SUFFIX,
+              optional: true,
+            },
+          },
+        })
+      }
+    >
+      Send calls
+    </button>
+  );
+}
+```
+
+## Verify Attribution
+
+> See [Verify Attribution](/developer/builder-codes/overview#verify-attribution) for steps to confirm your transaction was properly attributed.

developer/builder-codes/overview.mdx

@@ -0,0 +1,50 @@
+# 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`) identify builders onchain. Each code has a "payout address" in its metadata — this is where potential rewards are sent.
+
+Builder Codes give you:
+
+- **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.
+
+> **Get your Builder Code:** Register on the [OKX developer portal](https://www.okx.com/xlayer/developer), then go to **Settings** → **Builder Code**.
+
+## How It Works
+
+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.
+
+The suffix adds negligible gas: 16 gas per non-zero byte.
+
+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.
+
+> **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.
+
+## Get Started
+
+**App developers**
+
+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.
+
+**Wallet providers**
+
+See the [Wallet Provider Guide](/developer/builder-codes/wallet-providers).
+
+## Verify Attribution
+
+**Option 1 — OKLink Explorer**
+
+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.
+
+**Option 2 — Open Source Tool**
+
+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**.

developer/builder-codes/wallet-providers.mdx

@@ -0,0 +1,53 @@
+# Builder Codes for Wallet Providers
+
+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` field 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 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.
+
+```typescript
+finalSuffix = walletSuffix + appSuffix
+```
+
+This ensures both the app and the wallet receive onchain attribution on X Layer.
+
+> **Get your Builder Code:** Register on the [OKX developer portal](https://www.okx.com/xlayer/developer) under **Settings** → **Builder Code**.

xlayer-docs.js

@@ -74,6 +74,15 @@ module.exports = [
               '/developer/flashblocks/faq',
             ],
           },
+
+          {
+            title: 'Builder Codes',
+            path: '/developer/builder-codes/overview',
+            children: [
+              '/developer/builder-codes/integration',
+              '/developer/builder-codes/wallet-providers',
+            ],
+          },
           ]
         },