Ajouter des Builder Codes

Intégrez les Base Builder Codes dans une application onchain. Les Builder Codes ajoutent un suffixe d'attribution ERC-8021 aux données d'appel de transaction afin que Base puisse attribuer l'activité à votre application et que vous puissiez percevoir des frais de parrainage. Aucune modification de contrat intelligent requise.

Quand utiliser cette compétence

Utilisez cette compétence quand un développeur demande :

• « Ajouter les builder codes à mon application »
• « Comment ajouter un builder code à mes transactions ? »
• « Je veux percevoir des frais de parrainage sur les transactions Base »
• « Intégrer les builder codes »
• Mettre en place l'attribution de transactions sur Base

Prérequis

• Un Builder Code depuis base.dev > Settings > Builder Codes
• La bibliothèque ox pour générer les suffixes ERC-8021 : npm install ox

Workflow d'intégration

Copiez cette checklist et suivez la progression :

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

Framework Detection (Required First Step)

Avant la mise en œuvre, déterminez le framework utilisé.

1. Lire package.json et scanner les fichiers source

# 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. Classifier dans un framework

Ordre de priorité si plusieurs sont détectés : Privy > Wagmi > Viem > Standard RPC

3. Confirmer avec l'utilisateur

Avant de procéder, confirmez le framework détecté :

« J'ai détecté que vous utilisez [Framework]. Je vais implémenter les builder codes en utilisant l'approche [Framework] — est-ce correct ? »

Attendez la confirmation de l'utilisateur avant d'implémenter.

Chemin d'implémentation

• Privy (@privy-io/react-auth v3.13.0+) → Voir references/privy.md
• Wagmi (sans Privy) → Voir references/wagmi.md
• Viem uniquement (pas de framework React) → Voir references/viem.md
• Standard RPC (ethers.js ou window.ethereum brut) → Voir references/rpc.md

Step 2: Install dependencies

npm install ox

Nécessite viem >= 2.45.0 pour les chemins Wagmi/Viem. Privy nécessite @privy-io/react-auth >= 3.13.0.

Step 3: Generate the dataSuffix constant

Créez une constante partagée (par exemple, src/lib/attribution.ts ou 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: Apply attribution

Suivez le guide spécifique au framework :

Privy Implementation

Voir references/privy.md — basé sur plugin, une modification de config requise.

Wagmi Implementation

Voir references/wagmi.md — ajouter dataSuffix à la config du client Wagmi.

Viem Implementation

Voir references/viem.md — ajouter dataSuffix au client wallet.

Standard RPC Implementation

Voir references/rpc.md — ajouter DATA_SUFFIX aux données de transaction pour ethers.js ou window.ethereum brut.

Approche préférée : Configurez au niveau du client afin que toutes les transactions soient automatiquement attribuées. Utilisez l'approche par-transaction seulement si vous avez besoin d'une attribution conditionnelle.

Pour les Smart Wallets (EIP-5792 sendCalls) : Voir references/smart-wallets.md — passer via capabilities.

Step 5: Verify attribution

1. base.dev : Consultez Onchain > Total Transactions pour les comptes d'attribution
2. Explorateur de blocs : Trouvez le hash tx, consultez les données d'entrée, confirmez que les 16 derniers octets sont 8021 répétés
3. Outil de validation : Utilisez builder-code-checker.vercel.app

Faits clés

• Les Builder Codes sont des NFT ERC-721 frappés sur Base
• Le suffixe est ajouté aux données d'appel ; les contrats intelligents l'ignorent (aucune mise à niveau requise)
• Coût en gas négligeable : 16 gas par octet non nul
• L'analyse sur base.dev supporte actuellement les transactions Smart Account (AA) ; le support EOA arrive (les données d'attribution sont conservées)
• Le plugin dataSuffix dans Privy ajoute à toutes les chaînes, pas seulement Base. Si un comportement spécifique à la chaîne est nécessaire, contactez Privy
• Le plugin dataSuffix de Privy n'est PAS encore supporté avec l'adaptateur @privy-io/wagmi

Trouver les sites d'appel de transaction

Lors de la rétroactivité sur un projet existant, recherchez ces motifs :

# 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/

Pour l'intégration au niveau du client (Wagmi/Viem/Privy), vous devez généralement modifier seulement le fichier config — les sites d'appel de transaction individuels restent inchangés.