adding-builder-codes

Builder Codes の追加

Base Builder Codes をオンチェーンアプリケーションに統合します。Builder Codes は ERC-8021 アトリビューションサフィックスをトランザクションの calldata に追加するため、Base はアプリのアクティビティを特定でき、紹介手数料を獲得できます。スマートコントラクトの変更は不要です。

このスキルを使うタイミング

開発者から次のような依頼があった場合に、このスキルを使います。

• 「アプリケーションに builder codes を追加して」
• 「トランザクションに builder code を追加する方法を教えて」
• 「Base のトランザクションで紹介手数料を獲得したい」
• 「builder codes を統合して」
• Base でトランザクションのアトリビューションを設定する

前提条件

• base.dev > Settings > Builder Codes で取得した Builder Code
• ERC-8021 サフィックスの生成に使う ox ライブラリ：npm install ox

統合ワークフロー

このチェックリストをコピーして、進捗を記録します。

Builder Codes Integration:
- [ ] Step 1: Detect framework (Required First Step)
- [ ] Step 2: Install dependencies
- [ ] Step 3: Generate the dataSuffix constant
- [ ] Step 4: Apply attribution (framework-specific)
- [ ] Step 5: Verify attribution is working

フレームワークの検出（最初に必ず実施）

実装の前に、使用されているフレームワークを特定します。

1. package.json を読み込み、ソースファイルを調べる

# Check for framework dependencies
grep -E "wagmi|@privy-io/react-auth|viem|ethers" package.json

# Check for smart wallet / account abstraction usage
grep -rn "useSendCalls\|sendCalls\|ERC-4337\|useSmartWallets" src/

# Check for EOA transaction patterns
grep -rn "useSendTransaction\|sendTransaction\|writeContract\|useWriteContract" src/

# Check Privy version if present
grep "@privy-io/react-auth" package.json

2. いずれかのフレームワークに分類する

フレームワーク	検出シグナル
privy	package.json またはインポートに @privy-io/react-auth がある
wagmi	package.json またはインポートに wagmi がある（Privy を使用していない）
viem	package.json に viem があり、React フレームワークを使用していない
rpc	ethers、window.ethereum、または Web3 ライブラリが検出されない

複数検出された場合の優先順位：Privy > Wagmi > Viem > Standard RPC

3. ユーザーに確認する

先に進む前に、検出したフレームワークを確認します。

「[Framework] を使用していることを検出しました。[Framework] の方法で builder codes を実装します。よろしいですか？」

実装を始める前に、ユーザーの確認を待ちます。

実装方法

• Privy（@privy-io/react-auth v3.13.0 以降）→ references/privy.md を参照
• Wagmi（Privy を使用していない場合）→ references/wagmi.md を参照
• Viem のみ（React フレームワークを使用していない場合）→ references/viem.md を参照
• Standard RPC（ethers.js または生の window.ethereum）→ references/rpc.md を参照

Step 2: 依存関係をインストールする

npm install ox

Wagmi/Viem の方法では viem >= 2.45.0 が必要です。Privy には @privy-io/react-auth >= 3.13.0 が必要です。

Step 3: dataSuffix 定数を生成する

共有定数を作成します（例：src/lib/attribution.ts または src/constants/builderCode.ts）。

import { Attribution } from "ox/erc8021";

export const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: ["YOUR-BUILDER-CODE"], // Replace with your code from base.dev
});

Step 4: アトリビューションを適用する

フレームワークごとのガイドに従います。

Privy の実装

references/privy.md を参照してください。プラグインベースで、設定の変更が 1 か所必要です。

Wagmi の実装

references/wagmi.md を参照してください。Wagmi クライアントの設定に dataSuffix を追加します。

Viem の実装

references/viem.md を参照してください。ウォレットクライアントに dataSuffix を追加します。

Standard RPC の実装

references/rpc.md を参照してください。ethers.js または生の window.ethereum のトランザクションデータに DATA_SUFFIX を追加します。

推奨される方法：すべてのトランザクションに自動でアトリビューションが適用されるよう、クライアントレベルで設定します。条件付きのアトリビューションが必要な場合にのみ、トランザクションごとの方法を使います。

Smart Wallets（EIP-5792 sendCalls）の場合：references/smart-wallets.md を参照し、capabilities 経由で渡します。

Step 5: アトリビューションを確認する

1. base.dev：Onchain > Total Transactions でアトリビューション数を確認します
2. ブロックエクスプローラー：tx hash を検索し、input data を表示して、末尾の 16 バイトが 8021 の繰り返しであることを確認します
3. 検証ツール：builder-code-checker.vercel.app を使います

主な事実

• Builder Codes は Base 上で発行される ERC-721 NFT です
• サフィックスは calldata に追加されます。スマートコントラクトはこれを無視するため、アップグレードは不要です
• ガス代はごくわずかです。ゼロ以外の各バイトにつき 16 ガスです
• base.dev の分析機能は現在、Smart Account（AA）トランザクションに対応しています。EOA への対応は今後予定されています（アトリビューションデータは保持されます）
• Privy の dataSuffix プラグインは Base だけでなく、すべてのチェーンに追加します。チェーンごとの動作が必要な場合は、Privy にお問い合わせください
• Privy の dataSuffix プラグインは、まだ @privy-io/wagmi アダプターに対応していません

トランザクション呼び出し箇所の特定

既存のプロジェクトに後付けする場合は、次のパターンを検索してください。

# React hooks (Wagmi)
grep -rn "useSendTransaction\|useSendCalls\|useWriteContract\|useContractWrite" src/

# Viem client calls
grep -rn "sendTransaction\|writeContract\|sendRawTransaction" src/

# Privy embedded wallet calls
grep -rn "sendTransaction\|signTransaction" src/

# ethers.js
grep -rn "signer\.sendTransaction\|contract\.connect" src/

# Raw window.ethereum
grep -rn "window\.ethereum\|eth_sendTransaction" src/

クライアントレベルで統合する場合（Wagmi／Viem／Privy）、通常は設定ファイルのみを変更すればよく、個々のトランザクション呼び出し箇所は変更されません。