Yos Riady

Posted on Mar 22 • Originally published at formo.so

Builder Codes and ERC-8021 Explained: How to Solve Onchain Attribution

#webdev #blockchain #web3 #tutorial

Builder Codes and EIP-8021 solve onchain attribution by appending standardized data suffixes to transaction calldata, linking apps to transactions for verifiable tracking. Base supports this natively via automatic RPC suffixing and a code registry mapping strings to payout addresses. Benefits include fair revenue sharing, precise ROI measurement, and reduced integration effort, enabling builders to claim credit for driven volume without smart contract changes.

Onchain builders struggle to attribute transactions to specific apps, as standard tx data obscures referral sources. This attribution gap distorts acquisition metrics and growth decisions. This playbook dissects builder codes and ERC-8021, standards Base now supports to deliver verifiable onchain tracking.

Introduction

Attribution remains one of the most persistent challenges for onchain builders. While web2 relies on cookies and UTM parameters to track user acquisition, the pseudonymous nature of blockchain transactions often breaks the link between a user's interface interaction and the final smart contract execution. This disconnect makes it difficult for developers, wallets, and interfaces to claim fair credit for the volume they drive.

Builder Codes and the underlying ERC-8021 standard introduce a solution to this visibility problem. By appending a standardized data suffix to transaction calldata, these protocols create an onchain paper trail that links applications to the transactions they facilitate. This allows for programmatic revenue sharing and precise ROI tracking without compromising decentralization.

The standard, authored by Conner Swenberg (@ilikesymmetry) and introduced as a draft EIP in September 2025, exploits an underutilized property of the EVM: smart contracts ignore extra data appended beyond expected function arguments. If you call a contract function with additional bytes after the expected parameters, those bytes are safely discarded without errors or reverts. ERC-8021 takes advantage of this by tucking attribution metadata into that "invisible" trailing space.

"ERC-8021 is a standardized method for attributing transactions to applications through data suffixes. It enables interoperable tracking and reward distribution on Ethereum." -ERC8021 Official Site(ERC8021.com)

The Onchain Attribution Gap

Before standards like ERC-8021, attributing onchain value was largely a guessing game. A smart contract sees a wallet address and a function call, but it remains blind to where that transaction originated. Did the user come from a specific frontend, a wallet's in-app browser, or a direct contract interaction? Without this context, ecosystem rewards often fail to reach the interfaces actually driving adoption.

This lack of data forces teams to rely on vanity metrics rather than actionable insights. Marketing spend vanishes into a "dark forest" where conversion rates are untrackable, and infrastructure providers cannot prove their contribution to network growth. Teams cannot calculate whether their lifetime value (LTV) exceeds customer acquisition cost (CAC) at healthy multiples, because the attribution chain is broken the moment a user signs a transaction.

The problem compounds at scale. A DeFi aggregator routing millions in volume through a lending protocol generates real economic value for that protocol, but the lending contract has no native way to distinguish aggregator-sourced volume from direct users. Without attribution, the aggregator has no leverage to negotiate revenue shares and no data to prove its contribution.

"ERC-8021 solves a fundamental problem in blockchain ecosystems: how do we properly attribute value creation to the applications, wallets, and infrastructure providers that facilitate transactions?" -ERC-8021 Official Site(ERC-8021 Official Site)

What Are Builder Codes?

Builder Codes function as onchain referral IDs designed specifically for application developers. In traditional affiliate marketing, a unique link tracks sales to a referrer. Similarly, a Builder Code is a human-readable ASCII string (like "baseapp", "phantom", or "morpho") that identifies the frontend or tool initiating a transaction.

On Base, Builder Codes are implemented as an ERC-721 NFT collection. Each code is a unique alphanumeric token with onchain metadata containing the registered payout address, plus offchain metadata including the app name and site details. When a user interacts with a protocol through a specific interface, the interface attaches its Builder Code to the transaction. This signals to the network exactly which entity facilitated the activity, allowing the underlying protocol or chain to route a portion of fees or rewards back to that builder.

"A builder code is essentially referral code designed for application developers - applications can use it to generate transaction volume and earn revenue for another platform."

What Is ERC-8021?

ERC-8021 is the technical standard that makes Builder Codes interoperable across the Ethereum ecosystem. Rather than every protocol inventing its own tracking method, ERC-8021 defines a universal format for writing attribution data directly onto the blockchain.

The standard relies on four key components:

Transaction data suffix: A method for developers to append small data packets to the end of a transaction's calldata. Because the EVM ignores bytes beyond the expected function arguments, this suffix is invisible to the contract's execution logic but permanently recorded on the ledger.
Code registry: A smart contract that maps readable ASCII codes (e.g., "uniswap") to payout wallet addresses. The registry exposes a single key function: payoutAddress(string memory code) returns (address), allowing any system to resolve a code to its owner.
Schema ID (1 byte): A tag identifying which attribution logic is being used. Schema 0 represents the canonical registry format. This byte provides extensibility, allowing future schemas to define different parsing rules without breaking existing implementations.
ERC Marker (16 bytes): A fixed identifier consisting of the hex value 0x80218021802180218021802180218021 (the string "8021" repeated). Parsers locate attribution data by reading backward from the end of the calldata and matching this marker, making detection deterministic and unambiguous.

Key Benefits for Crypto Apps and Protocols

Adopting a standardized attribution model shifts the industry away from vague estimates toward verifiable data. For builders, this transparency translates directly into sustainability and growth.

Transparency: Onchain attribution ensures fair, verifiable revenue distribution, eliminating disputes over who drove volume. Any party can independently verify attribution by inspecting calldata on a block explorer.
Zero integration friction: The standard works with any existing smart contract without modifications. There are no ABI changes, no proxy upgrades, and no redeployments required. On Base, the RPC handles suffixing automatically, meaning many developers already generate attribution data without active configuration.
Scalability: A single standardized system works across multiple platforms, reducing integration overhead for wallets and apps. The same Builder Code works across every protocol on the chain.
Composability: Because ERC-8021 uses comma-delimited codes, multiple entities in a transaction's supply chain can receive attribution. A wallet, an aggregator, and a frontend can all be credited in a single transaction.
Innovation: With clear incentives, developers are motivated to build higher-quality interfaces and infrastructure, knowing their contributions will be recognized and rewarded.

The Byte Layout in Detail

The suffix is structured to be read from end to start:
[original calldata] + [codes (variable)] + [codesLength (1 byte)] + [schemaId (1 byte)] + [ERC marker (16 bytes)][original calldata] + [codes (variable)] + [codesLength (1 byte)] + [schemaId (1 byte)] + [ERC marker (16 bytes)][original calldata] + [codes (variable)] + [codesLength (1 byte)] + [schemaId (1 byte)] + [ERC marker (16 bytes)]

For Schema 0 (the canonical format), the parsing algorithm works as follows:

Extract the final 16 bytes of calldata and verify they match the ERC marker (0x8021...8021).
Read the preceding byte as the schemaId. If it equals 0x00, continue with Schema 0 parsing.
Read the next preceding byte as codesLength, which indicates the byte length of the codes section.
Extract the codes section. Multiple entity codes are delimited by 0x2C (the comma character in ASCII).

For example, the hex suffix 07626173656170700080218021802180218021802180218021 breaks down as: 07 (codesLength = 7 bytes), 62617365617070 ("baseapp" in ASCII), 00 (schemaId = 0), and 80218021802180218021802180218021 (ERC marker, 16 bytes).

Getting Started with Builder Codes

Builder Codes act as the user-facing identifier, while ERC-8021 provides the infrastructure to record them. When an app integrates this system, it doesn't need to change its core smart contract logic. Instead, it appends a standardized suffix to the transaction data sent to the network.

This separation of concerns is critical. The core business logic of a smart contract remains untouched, ensuring security and gas efficiency are not compromised for the sake of analytics.

Registering Codes in the Registry

The process begins with the Code Registry. This smart contract acts as a directory, linking a human-readable string to a wallet address capable of receiving funds.

Identity mapping: Entities register "codes" (ASCII strings like "baseapp") instead of using opaque hexadecimal hashes. The first entity to register a code owns it exclusively; duplicate registrations revert.
Revenue routing: The registry maps these codes to payout addresses via the payoutAddress() function, enabling automatic onchain revenue distribution without manual reconciliation.
Custom schemas: Advanced users can define custom schema IDs that point to specific registry contracts with alternative attribution logic, keeping the standard extensible without requiring protocol upgrades.

Builder Codes on Base

Builders on Base must claim their identity by interacting with the Base registry contract to mint a unique ASCII string that represents their project.

Once claimed, this code becomes the project's permanent onchain identifier. Any transaction tagged with this string will be attributed to the registered owner, regardless of which wallet or interface initiated the action. Builders can register and manage their codes through the base.dev settings dashboard, which also provides an attribution tracking view showing volume and revenue attributed to their code.

Builder Codes on Other EVM Chains

Find an existing Registry contract address or deploy your own Registry contract on your chain if none exists yet. Specify that registry address when writing your dataSuffix. We recommend using the ox library from the wevm team to generate your suffix.

You can deploy your own registry on any chain and specify it when you attach your suffix:
import { Attribution } from 'ox/erc8021'

const dataSuffix1 = Attribution.toDataSuffix({
codes: ['baseapp']
})

const dataSuffix2 = Attribution.toDataSuffix({
codes: ['baseapp', 'morpho'],
codeRegistry: { address: '0x0000000000000000000000000000000000000000', chainId: 1 },
})import { Attribution } from 'ox/erc8021'

const dataSuffix1 = Attribution.toDataSuffix({
codes: ['baseapp']
})

const dataSuffix2 = Attribution.toDataSuffix({
codes: ['baseapp', 'morpho'],
codeRegistry: { address: '0x0000000000000000000000000000000000000000', chainId: 1 },
})

Generating and Appending the Data Suffix

Once a code is registered, the application must attach it to user transactions. This is done via the data suffix.

Appending data: The application concatenates the Builder Code structure to the end of the transaction calldata. Because the EVM discards unexpected trailing bytes during contract execution, the original function call processes identically whether the suffix is present or not.
Automatic attribution: In ecosystems like Base, this process is often handled automatically by the RPC layer. Standard wallet libraries and SDKs are configured to detect the application context and append the code to the ERC-8021 standard structure without developer intervention.
Wallet compatibility: For wallets implementing the ERC-5792 standard, the DataSuffixCapability parameter enables automatic suffixing. Whether using wagmi's writeContract or sendTransaction calls, the attribution logic handles suffixing transparently.
Backward parsing: The system uses a backward-parsing approach, reading from the end of the calldata using the ERC Marker to find the attribution tag without disrupting the main transaction payload. // Sample ERC-8021 attribution for "baseapp" from earlier const response = await provider.request({ method: 'wallet_sendCalls', params: [{ calls: [{ to: protocolAddress, data: encodedCalldata, value: '0x0' }], capabilities: { dataSuffix: { value: '0x62617365617070070080218021802180218021802180218021' // here optional: true } } }] });

Parsing Transactions Offchain

The final step happens offchain. Because the attribution data sits in the calldata suffix, it is permanently recorded on the ledger but does not require expensive onchain processing during execution.

Indexers and analytics platforms scan the blockchain, identify the ERC Marker at the tail of calldata, and extract the Builder Code using the backward-parsing algorithm. This allows for retroactive analysis: any existing smart contract supports ERC-8021 attribution without upgrades, as the data is extracted by indexers after the fact.

The suffix adds a negligible gas overhead of approximately 16 gas per non-zero byte, which for a typical Builder Code translates to roughly 100-400 additional gas on top of the base transaction cost. If you want to quickly convert ETH amounts or understand gas costs in smaller units, you can use this handywei converter.

Integrating with Wallets and SDKs

For most developers using standard libraries and crypto-native analytics tools like Formo, integration is automatic.

Automatic support: Whether using wagmi writeContract or sendTransaction calls, the automatic attribution logic handles the suffixing. ERC-5792 compatible wallets can use the DataSuffixCapability to enable this at the wallet layer.
Embedded wallets: Providers like Privy and Turnkey support Builder Code attribution natively, extending coverage to apps using embedded wallet flows.
Broad compatibility: The standard works across different transaction types for both externally owned accounts (EOAs) and smart contract wallets, ensuring comprehensive coverage of user activity.
Native support in Formo: The Formo platform and SDKs are configured to detect the application context and detect the ERC-8021 data suffix and translate it into human readable builder codes.

Verifying Attribution

Verification is straightforward because the data is public. Builders can audit their attribution by inspecting the calldata of transactions initiated through their interfaces.

Anyone looking at the onchain data can identify a transaction containing the ERC-8021 standard marker (0x8021...8021 in the final 16 bytes of calldata) and read the associated Builder Code. Base provides a dedicated Builder Code Validation tool for checking whether codes are being appended correctly. Standard block explorers like Basescan and Etherscan also display the raw calldata, allowing manual inspection of the suffix.

Best Practices for Maximum Impact

While ERC-8021 handles the source of the transaction, maximizing its value requires combining it with robust user profiling. Attribution data tells you which app drove a transaction, but not who the user is or their long-term value.

Combine with offchain data: Map Builder Codes to offchain campaigns (UTM parameters, referrer URLs) to see full-funnel ROI from first touch to onchain conversion. This bridges the gap between marketing spend and actual protocol revenue.
Use multi-touch attribution: A single Builder Code tells you the final interface, but users often interact with multiple touchpoints before transacting. Pair onchain attribution with session-level tracking to understand the complete journey.
Monitor retention: Use attribution to track not just acquisition, but whether users from specific partners stick around. A channel that drives 1,000 wallets with 2% retention is less valuable than one that drives 100 wallets with 40% retention.
Sybil resistance: Analyze attributed volume for bot-like patterns. High volume from a single code doesn't always mean high quality. Look for organic clustering, temporal variance, and diverse wallet profiles rather than raw transaction counts.
Track downstream LTV: Connect the Builder Code to the user's lifetime revenue contribution. This lets you calculate acquisition cost against actual value generated, enabling data-driven partnership and incentive decisions.

Unlocking Full-Funnel Attribution with Formo

Builder Codes solve the problem of source attribution at the transaction level, but they are one piece of a larger puzzle. Understanding which interface sent a transaction is valuable, but growth teams also need to know: What marketing campaign originally brought this user to the interface? What was their journey from first page view to wallet connection to onchain conversion? How does their lifetime value compare across acquisition channels?

Formo bridges this gap by unifying onchain signals like ERC-8021 with offchain context to create a complete picture of user behavior and journey from first visit to transactions.

How Formo Completes the Attribution Chain

Formo is an analytics and data platform purpose-built for onchain apps. It ingests data from standards like ERC-8021 and combines it with web, product, and in-app events to transform a raw wallet address and a Builder Code into a rich, actionable user profile.

Here is how the layers connect:

Offchain tracking: Formo's lightweight, open-source SDK captures the user's entry point, including referrer, UTM parameters, page views, and session behavior. Available as Web, Mobile (React Native), and Server SDKs, it drops into any stack in minutes without heavy tag managers.
Identity resolution: When the user connects their wallet, Formo stitches the anonymous browsing session to the wallet address. Multiple wallets from the same anonymous session are unified into a single user profile, and historical browsing is retroactively attributed to the wallet once connected.
Onchain event capture: Formo monitors smart contract events in real time across 30+ supported chains, including Ethereum, Base, Arbitrum, Optimism, and Polygon. Transaction events, contract calls, and decoded logs are automatically captured and tied to the resolved user profile.
Attribution modeling: With the full journey mapped, Formo applies first-touch, last-touch, and linear attribution models to calculate which builder codes, channels, campaigns, and partners actually drove conversions. Teams can define custom conversion events (a mint, a swap, a stake) and measure attribution against those specific goals. Additional models are available on request.

Wallet Intelligence for Deeper Segmentation

Beyond attribution, Formo enriches wallet addresses with onchain behavioral data to power audience segmentation:

Audience insights: See the top apps, tokens, chains, net worth, and DeFi positions held by your user base, broken out by acquisition source.
Wallet profiles: Every wallet that touches your app gets a unified profile combining session history, transaction data, and cross-chain activity. These profiles include social identities (ENS, Farcaster, Lens) when available.
User segmentation: Build segments based on wallet holdings, onchain behavior, retention cohort, or lifecycle stage (new, returning, power user, churned, resurrected). Export these segments for targeted campaigns.

Connecting Builder Codes to Business Outcomes

The real power emerges when you connect ERC-8021 attribution with Formo's full-funnel data. Instead of knowing only that "500 transactions came from Builder Code X," teams can answer questions like:

What was the CAC for users acquired through each partner interface?
Which Builder Code sources produce users with the highest 30-day retention?
What is the average revenue per user (ARPU) segmented by the original acquisition channel and the Builder Code on the converting transaction?
Are high-value wallets (by net worth or DeFi positions) coming from specific interfaces?

Formo exposes this data through custom dashboards, SQL-based exploration, an AI-powered query interface, and a public API for programmatic access. Teams can also sync data to external BI tools and CRMs for integration into broader business intelligence workflows. All of this operates without third-party cookies, IP tracking, or device fingerprinting, aligning with both GDPR requirements and the privacy expectations of the crypto-native user base.

For detailed integration guidance, visit docs.formo.so.

Conclusion

Builder Codes and ERC-8021 represent a critical maturity step for the crypto ecosystem. By standardizing how value is attributed, the industry moves toward a revenue-driven model where interfaces, protocols, and creators are fairly compensated.

For builders, implementing these standards is no longer optional. It is the foundation for sustainable, data-driven growth.

Paired with analytics platforms like Formo that connect onchain attribution to the full user journey, teams finally have the data they need to accelerate user acquisition, retention, and revenue onchain.

Frequently Asked Questions

Can any Ethereum app use ERC-8021?

Yes. ERC-8021 works with any EVM-compatible smart contract without modifications. The standard exploits a core EVM property: contracts ignore extra bytes appended beyond expected function arguments. This means the suffix is invisible to contract execution but permanently stored in calldata. It works across L1 Ethereum and any EVM L2, including Base, Optimism, Arbitrum, Polygon, and others.

How do I register a Builder Code on Base?

Navigate to the base.dev Settings dashboard and claim a unique ASCII string like "myapp". This interacts with the Code Registry smart contract to mint an ERC-721 token that maps your code to a payout wallet address. Once registered, any transaction tagged with your string is attributed to your project, and revenue distributions route to the registered payout address.

What happens if two apps try to claim the same Builder Code?

The first entity to register via the Code Registry owns the code exclusively. The registry enforces uniqueness at the contract level, so duplicate registration attempts will revert. Choose a distinctive, brand-aligned string and register it early to secure your preferred code.

Does ERC-8021 increase transaction gas costs?

The overhead is negligible. The suffix adds gas at a rate of 16 gas per non-zero byte. A typical Builder Code suffix (code + length byte + schema byte + 16-byte marker) totals roughly 100-400 gas, depending on the code length. For context, a standard ETH transfer costs 21,000 gas, so the attribution overhead represents less than 2% of even the cheapest transaction type.

Is Builder Code support live on chains besides Base?

Yes. Any other EVM chain supports ERC-8021 through manual integration, since the standard only requires appending bytes to calldata and deploying a registry contract. Broader adoption across L2s like Optimism and Arbitrum is in progress.

Do I need to modify my smart contracts to support ERC-8021?

No. This is one of the standard's most important design decisions. Because the suffix sits in calldata beyond the expected function arguments, the contract's execution logic never encounters it. No ABI changes, proxy upgrades, or redeployments are needed. Existing deployed contracts support ERC-8021 attribution retroactively.

How does backward parsing work, and why was it chosen?

The parser reads calldata from the end rather than the beginning. It first checks the final 16 bytes for the ERC marker (0x8021...8021). If the marker matches, it reads the preceding byte as the schema ID, then parses the attribution data according to that schema's rules.

This approach was chosen because it avoids interfering with the contract's forward-reading ABI decoder. The contract reads function selectors and arguments from the start of calldata as usual, and the attribution suffix at the end is simply never reached during execution.

Can multiple entities receive attribution in a single transaction?

Yes. Schema 0 supports comma-delimited codes (using 0x2C as the delimiter). For example, a transaction could carry the suffix "walletapp,aggregator,frontend" to credit all three entities in the supply chain. This enables multi-party revenue sharing models where each participant in a transaction's path receives proportional attribution.

How does Formo connect Builder Codes to full-funnel analytics?

Formo ingests ERC-8021 attribution data alongside offchain tracking (page views, UTM parameters, referrer data) through its open-source SDK. When a user connects their wallet, Formo's identity resolution engine stitches the anonymous browsing session to the wallet address.

This means you can see not just which Builder Code tagged a transaction, but what marketing campaign originally brought the user to the interface, their complete session journey, and their long-term onchain LTV. Formo supports first-touch, last-touch, and linear attribution models across 30+ chains.

DEV Community