From 8756ff79dcf45750fd6527c0f730f7a485ccfba8 Mon Sep 17 00:00:00 2001
From: Patrick Hughes <patrick.hughes@coinbase.com>
Date: Thu, 12 Mar 2026 16:50:35 -0500
Subject: [PATCH] add schema 2 support + faq

---
 .../builder-codes/app-developers.mdx          | 89 +++++++++++++++++++
 .../builder-codes/builder-codes.mdx           | 12 +++
 2 files changed, 101 insertions(+)

diff --git a/docs/base-chain/builder-codes/app-developers.mdx b/docs/base-chain/builder-codes/app-developers.mdx
index 2d5b55d24..b0b70482b 100644
--- a/docs/base-chain/builder-codes/app-developers.mdx
+++ b/docs/base-chain/builder-codes/app-developers.mdx
@@ -210,6 +210,95 @@ See the [Privy Builder Codes integration guide](https://docs.privy.io/recipes/ev
   </Tabs>
 </Accordion>
 
+## Schema 2: CBOR Attribution 
+
+### Encoding a Schema 2 Suffix
+
+Pass `appCode`, `walletCode`, or both to `Attribution.toDataSuffix`. The `ox` library detects Schema 2 automatically when either field is present.
+
+<Steps>
+  <Step title="Install Dependencies">
+    Install the required packages. Requires the version of `ox` that includes ERC-8021 Schema 2 support.
+
+    ```bash  theme={null}
+    npm i ox wagmi viem
+    ```
+  </Step>
+
+  <Step title="Generate Your Attribution Suffix">
+    Call `Attribution.toDataSuffix` with your app code and add it to your Wagmi config or Viem wallet client.
+
+    ```ts config.ts theme={null}
+    import { createConfig, http } from "wagmi";
+    import { base } from "wagmi/chains";
+    import { Attribution } from "ox/erc8021";
+
+    // Get your Builder Code from base.dev > Settings > Builder Codes
+    const DATA_SUFFIX = Attribution.toDataSuffix({
+      appCode: "YOUR-APP-CODE",
+    });
+
+    export const config = createConfig({
+      chains: [base],
+      transports: { [base.id]: http() },
+      dataSuffix: DATA_SUFFIX,
+    });
+    ```
+  </Step>
+
+  <Step title="Extend with Wallet Code, Registries, or Metadata (Optional)">
+    If you also need to attribute the wallet provider, point entities to custom registries, or attach campaign metadata, pass the additional fields to `Attribution.toDataSuffix`.
+
+    ```ts config.ts theme={null}
+    import { Attribution } from "ox/erc8021";
+
+    const DATA_SUFFIX = Attribution.toDataSuffix({
+     appCode:    "YOUR-APP-CODE",    // optional: use if you're an app
+     walletCode: "YOUR-WALLET-CODE", // optional: use if you're a wallet
+      registries: {
+        app: {
+          chainId: 8453,
+          address: "0xYourAppRegistryAddress",
+        },
+        wallet: {
+          chainId: 8453,
+          address: "0xYourWalletRegistryAddress",
+        },
+      },
+      metadata: {
+        utm_campaign: "winter-promo",
+        source: "webapp",
+      },
+    });
+    ```
+  </Step>
+</Steps>
+
+<Note>
+  At least one of `appCode` or `walletCode` must be present. `chainId` in registries is a plain number (e.g., `8453`), consistent with Schema 1.
+</Note>
+
+### Decoding a Schema 2 Suffix
+
+`Attribution.fromData` handles all three schemas. Check `attribution.id === 2` to type-narrow to Schema 2 fields:
+
+```ts theme={null}
+import { Attribution } from "ox/erc8021";
+
+const attribution = Attribution.fromData(hexSuffix);
+
+if (attribution && attribution.id === 2) {
+  console.log(attribution.appCode);    // string | undefined
+  console.log(attribution.walletCode); // string | undefined
+  console.log(attribution.registries); // { app?, wallet? } | undefined
+  console.log(attribution.metadata);   // Record<string, unknown> | undefined
+}
+```
+
+<Tip>
+  Use the [Builder Code Validation](https://builder-code-checker.vercel.app/) tool to verify that your Schema 2 suffix decodes correctly before shipping.
+</Tip>
+
 ## Verify Attribution
 
 To confirm your Builder Code is being appended correctly:
diff --git a/docs/base-chain/builder-codes/builder-codes.mdx b/docs/base-chain/builder-codes/builder-codes.mdx
index 4373a0284..cfe47cbfd 100644
--- a/docs/base-chain/builder-codes/builder-codes.mdx
+++ b/docs/base-chain/builder-codes/builder-codes.mdx
@@ -110,6 +110,18 @@ Wallets supporting ERC-5792 can use the `DataSuffixCapability` for clean suffix
 - **Privy** - Embedded wallet solution with ERC-8021 capability
 - **Turnkey** - Infrastructure for programmatic wallets
 
+### What if I have my own onchain attribution method, or need to attribute both the app and the wallet separately?
+
+Use Schema 2 , which supports separate app and wallet codes, per-entity custom registries, and arbitrary key-value metadata. 
+
+Schema 2 lets the dapp and the wallet provider each claim attribution for the same transaction independently. See [Schema 2: CBOR Attribution](./app-developers#schema-2:-cbor-attribution) in the App Developers guide.
+
+**Use Schema 2 when you need to:**
+
+- Attribute a transaction to both an app code and a wallet code separately
+- Point each entity to its own custom code registry (different registry per role)
+- Attach campaign or tracking metadata (e.g., `utm_campaign`, `source`)
+
 ## Additional Resources
 
 - [Official ERC-8021 Proposal](https://eip.tools/eip/8021)