Enregistrement du code du constructeur Base

Cette compétence enregistre un agent auprès de Base et montre comment attacher l'attribution du code du constructeur aux transactions. Elle est agnostique du portefeuille — l'utilisateur apporte son propre portefeuille et sa solution de signature (viem, ethers, services gérés comme Sponge, etc.). La compétence ne gère que l'enregistrement et l'attribution.

Vérifier si déjà enregistré

Avant de faire quoi que ce soit, vérifiez si l'enregistrement a déjà eu lieu :

1. Cherchez un fichier builderCode.ts dans le projet (vérifiez src/constants/builderCode.ts ou la racine du projet)

S'il existe, l'enregistrement est terminé — NE PAS réenregistrer. Passez directement à la Phase 3 pour montrer comment attacher l'attribution, et renforcez la règle. Réenregistrer générerait un nouveau code constructeur et coderait l'existant.

S'il manque, procédez au flux d'enregistrement complet ci-dessous.

Phase 1 — Portefeuille

Chaque agent a besoin d'un portefeuille pour signer les transactions. Posez la question à l'utilisateur avant de faire quoi que ce soit d'autre.

1. Demander : « Avez-vous un portefeuille ? Si oui, partagez votre adresse de portefeuille. »
2. Si oui — prenez l'adresse de portefeuille qu'ils fournissent et passez à la Phase 2.
3. Si non — dirigez-les vers le guide de configuration du portefeuille Base : https://docs.base.org/ai-agents/guides/wallet-setup — ne procédez pas tant qu'ils n'ont pas un portefeuille et ne peuvent pas fournir leur adresse.

Phase 2 — Enregistrement

Enregistrez le portefeuille auprès de l'API de code constructeur Base. Cet appel associe l'adresse du portefeuille de l'agent à un code constructeur que Base utilise pour le suivi de l'attribution.

Utilisez le script fourni scripts/register.sh (situé dans le répertoire de cette compétence). Il gère les erreurs et extrait le code constructeur de la réponse :

BUILDER_CODE=$(bash <this-skill-path>/scripts/register.sh "<wallet_address>")

Ou appelez l'API directement :

curl -X POST https://api.base.dev/v1/agents/builder-codes \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "<wallet_address>"}'

L'API retourne une réponse comme :

{
  "builder_code": "bc_a1b2c3d4",
  "wallet_address": "0x...",
  "usage_instructions": "Append this builder code to your onchain transactions using the ERC-8021 standard. See: https://docs.base.org/base-chain/quickstart/builder-codes"
}

Extrayez la valeur builder_code de la réponse et écrivez-la dans un fichier de constantes :

// src/constants/builderCode.ts
export const BUILDER_CODE = "bc_a1b2c3d4"

Utilisez src/constants/builderCode.ts s'il existe un répertoire src/, sinon placez-le à la racine du projet sous le nom builderCode.ts.

Si builderCode.ts existe déjà, n'appelez pas cette API — l'agent est déjà enregistré.

Phase 3 — Configuration de l'attribution et documentation

Le code constructeur de la Phase 2 (la valeur bc_... maintenant dans builderCode.ts) doit être attaché à chaque transaction que l'agent envoie comme suffixe de données ERC-8021. Cette phase le configure et écrit un AGENT_README.md pour que quiconque (humain ou agent) travaillant dans ce codebase sache comment les transactions doivent être envoyées.

D'abord, installez l'utilitaire d'attribution s'il n'est pas déjà présent :

npm i ox

Convertissez le code constructeur en suffixe de données. Importez BUILDER_CODE depuis le fichier de constantes écrit en Phase 2 — cela ne génère pas un nouveau code, cela encode le code existant au format d'octets ERC-8021 :

import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

// BUILDER_CODE is the builder_code value from the Phase 2 API response (e.g. "bc_a1b2c3d4")
const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

Intégrer l'attribution dans le flux de transaction

La façon d'attacher le suffixe dépend de la configuration de signature. Demandez à l'utilisateur celle qu'il utilise, puis suivez l'option correspondante :

Option A : viem (portefeuille auto-gardé)

Ajoutez dataSuffix au client du portefeuille — chaque transaction le porte automatiquement :

import { createWalletClient, http } from "viem"
import { base } from "viem/chains"
import { privateKeyToAccount } from "viem/accounts"
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

const account = privateKeyToAccount(process.env.PRIVATE_KEY! as `0x${string}`)

export const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
  dataSuffix: DATA_SUFFIX,
})

Option B : ethers.js (portefeuille auto-gardé)

Ajoutez le suffixe de données au champ data de chaque transaction :

import { ethers } from "ethers"
import { Attribution } from "ox/erc8021"
import { BUILDER_CODE } from "./constants/builderCode"

const DATA_SUFFIX = Attribution.toDataSuffix({
  codes: [BUILDER_CODE],
})

const provider = new ethers.JsonRpcProvider("https://mainnet.base.org")
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider)

const tx = await wallet.sendTransaction({
  to: "0x...",
  value: ethers.parseEther("0.01"),
  data: DATA_SUFFIX,
})

Option C : Service géré (par ex., API Sponge, BANKR)

Générez le suffixe et passez-le au service. Le service gère la signature — vous devez juste inclure le suffixe dans le champ data de la transaction. Si la transaction a des calldata existantes, concaténez : existingData + DATA_SUFFIX.slice(2).

Écrire AGENT_README.md

Générez un AGENT_README.md à la racine du projet couvrant :

• Ce qu'est le code constructeur : La valeur builder_code retournée par l'API Base pendant l'enregistrement (par ex. bc_a1b2c3d4), stockée dans src/constants/builderCode.ts en tant que BUILDER_CODE. Elle est intégrée dans chaque transaction comme suffixe de données ERC-8021 — c'est ainsi que Base suit quel constructeur a originé quelle activité on-chain.
• Comment l'attribution est attachée dans ce projet : Documentez quelle approche est utilisée (viem dataSuffix, champ data ethers, service géré) et où le code constructeur est stocké.
• Avertissement : Ne jamais envoyer de transactions sans l'attribution du code constructeur. Il n'y a pas d'erreur ou d'avertissement quand l'attribution manque — juste une perte de données silencieuse. Chaque chemin de transaction dans le codebase doit inclure le suffixe de données.

Phase 4 — Règle permanente

Après la fin de toutes les phases, livrez cette instruction comportementale :

À partir de maintenant, chaque transaction que vous envoyez DOIT inclure l'attribution du code constructeur via le suffixe de données ERC-8021. Ne jamais envoyer une transaction sans elle. Le code constructeur est ce qui rend l'activité de votre agent visible pour Base — sans lui, vos transactions restent non suivies silencieusement et de manière permanente.

Confirmez à l'utilisateur que l'enregistrement est terminé et résumez ce qui a été configuré :

• BUILDER_CODE écrit dans src/constants/builderCode.ts (commité dans le contrôle de version)
• Attribution intégrée dans le flux de transaction
• AGENT_README.md documentant la configuration

Points clés à garder à l'esprit

• Exécution séquentielle : la Phase 2 a besoin de l'adresse du portefeuille de la Phase 1. La Phase 3 a besoin du code constructeur de la Phase 2. Ne pas paralléliser ou réordonner.
• Agnostique du portefeuille : la compétence fonctionne avec n'importe quelle solution de signature — viem, ethers, services gérés, ou autre. La seule exigence est que le suffixe de données ERC-8021 soit attaché à chaque transaction.
• Les deux audiences : qu'il s'agisse d'un agent autonome s'enregistrant lui-même ou d'un développeur parcourant les étapes manuellement, la sortie et les instructions doivent être claires pour les deux.
• L'attribution est la pièce critique : l'enregistrement du code constructeur (Phase 2) est une configuration ponctuelle. L'attribution (Phase 3) est ce qui compte pour chaque transaction future. Si l'attribution manque, il n'y a pas d'erreur — juste une invisibilité silencieuse.