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.
The Byte Layout in Detail
The suffix is structured to be read from end to start:
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 equals0x00, 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).
How Builder Codes and ERC-8021 Work Together
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.
"We're using a transaction attribution standard called 8021 to do this... this defines a method for actually getting that attribution onchain." - Base Builder Codes YouTube Video (YouTube)
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.
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
DataSuffixCapabilityparameter enables automatic suffixing. Whether using wagmi'swriteContractorsendTransactioncalls, 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.
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.
Key Benefits for Onchain Builders
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.
Implementing Builder Codes on Base
Base has pioneered the practical application of ERC-8021, making it nearly effortless for developers to participate. The implementation is designed to be "opt-out" rather than "opt-in" for standard tooling, meaning many developers may already be generating attribution data without active configuration.
"The way that you implement this is like do nothing. It will just work. If your app is on base dev that builder code will make it on chain." - Base Builder Codes YouTube (YouTube)
Claiming Your Unique Code
To ensure rewards are routed correctly, builders must claim their identity. This involves interacting with the 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.
Integrating with Wallets and SDKs
For most developers using standard libraries and crypto-native analytics tools like Formo, integration is automatic. The RPCs and SDKs are configured to detect the application context and append the necessary data suffix.
Automatic support: Whether using wagmi
writeContractorsendTransactioncalls, the automatic attribution logic handles the suffixing. ERC-5792 compatible wallets can use theDataSuffixCapabilityto 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.
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 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.
The Future of Onchain Attribution
As L2 ecosystems mature, standards like ERC-8021 are likely to become native to the infrastructure layer. The ability to track provenance is essential for the next generation of affiliate models, developer rewards, and programmatic advertising onchain.
Several trends point to where attribution is headed. First, the composability of ERC-8021's comma-delimited format opens the door to multi-party attribution within a single transaction, where a wallet, aggregator, and frontend each receive proportional credit. Second, as more chains adopt the standard (it already works on any EVM chain through manual integration), cross-chain attribution becomes feasible, meaning a user acquired on Base who later transacts on Arbitrum can be tracked across that journey. Third, the combination of onchain attribution with wallet intelligence creates the foundation for onchain programmatic advertising, where ad spend can be directly tied to protocol revenue rather than impressions.
Conclusion
Builder Codes and ERC-8021 represent a critical maturity step for the crypto ecosystem. By standardizing how value is attributed, the industry moves away from zero-sum competition toward a cooperative 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.
The standard's elegance lies in its simplicity: a handful of bytes appended to calldata, parsed backward by indexers, costing almost nothing in gas, yet unlocking a transparent attribution layer that the entire ecosystem can build on. Paired with analytics platforms like Formo that connect onchain attribution to the full user journey, teams finally have the data they need to make acquisition, retention, and revenue decisions with confidence.
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?
Base offers the most mature implementation, with automatic RPC-level suffixing that requires zero developer configuration. 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.
What is the difference between ERC-8021 attribution and Formo's attribution?
ERC-8021 provides transaction-level source attribution: it tells you which interface or app facilitated a specific transaction. Formo provides full-funnel user attribution: it traces the complete journey from ad click or referral link through website visit, wallet connection, and onchain conversion.
ERC-8021 answers "which app sent this transaction?" while Formo answers "which campaign brought this user, what did they do before transacting, and what is their lifetime value?" The two are complementary, and combining them gives the most complete attribution picture available in web3.
Is ERC-8021 backward compatible with existing attribution schemes?
Not fully. The ERC-8021 suffix format (which ends with the 0x8021...8021 marker) is a distinct standard.
Existing schemes like CoinbaseSmartWallet's previous attribution method use different suffix formats. However, the schema ID byte provides forward extensibility: new schemas can be defined without breaking existing parsers, and legacy systems can be wrapped into custom schema definitions.
How does ERC-8021 handle privacy?
Builder Codes attribute transactions to applications, not to individual users. The standard does not add any user-identifying information to the transaction.
The wallet address is already public on the blockchain. The only new data is the application identifier (the Builder Code string), which reveals which interface was used but nothing about the user's identity, location, or behavior beyond what the blockchain already exposes.
Can I verify Builder Code attribution without running my own indexer?
Yes. The simplest approach is to inspect raw calldata on any block explorer (Basescan, Etherscan) and check for the 0x8021...8021 marker in the final 16 bytes.
Base also provides a dedicated Builder Code Validation tool that checks whether codes are being appended correctly to transactions from your application. For ongoing monitoring, analytics platforms like Formo automatically parse and aggregate ERC-8021 attribution data.
What analytics can I track once Builder Codes are implemented?
With Builder Codes alone, you can track transaction volume, value, and frequency attributed to your application.
Combined with a platform like Formo, you can measure: daily/weekly/monthly active users by acquisition source, conversion funnels from page view to transaction, retention cohorts segmented by the originating Builder Code, revenue per user by channel, wallet-level LTV, and audience composition (token holdings, chain activity, DeFi positions) by source.
Formo surfaces this data through dashboards, SQL queries, an AI assistant, and a programmatic API.
Related articles
Share this post
