Technical Overview

How Merkl works end to end — the engine, the reward lifecycle, and the core concepts

Merkl runs an offchain engine that analyzes both onchain and offchain data to track user activity and allocate rewards according to the rules each campaign creator defines. It writes the resulting rewards into a merkle tree, publishes that tree's root onchain, and lets users claim what they have earned — transparently and gas-efficiently.

🗺️ Platform Overview

Merkl operates through campaigns created by campaign creators. A campaign is a time-bound incentive program where Merkl tracks onchain and offchain activity based on predefined rules. Rewards or points are either posted onchain or updated offchain via Merkl’s endpoints, allowing users to monitor their accumulated rewards.

How it works

1. Campaign Creation: Campaign creators set up a campaign through a smart contract called the Merkl Distribution Creator. The campaign's configuration defines what activity is rewarded, who is eligible, how user scores are computed, and how rewards are distributed over time. These details are pushed onchain, along with the incentive tokens to be distributed.
2. User Participation: Users perform the rewarded activity (e.g., providing liquidity, lending, or borrowing) to earn the campaign's rewards or points.
3. Reward Computation: At fixed intervals, a system called the Merkl Engine fetches campaigns from the Merkl Distribution Creator contract and processes reward calculations based on available onchain and offchain data and on the rules set by the campaign creator. The Merkl Engine tracking is exhaustive and does not rely on discretionary snapshots.
4. Reward Update: After each computation, users see the pending rewards they have earned (awaiting the next onchain update). At regular intervals — potentially different from the computation intervals — the Merkl Engine generates a merkle tree from all processed campaigns, compresses it into a single merkle root, and pushes that root onchain to the Merkl Distributor contract. The matching reward file is published on the Merkl status page, so anyone can audit past distributions.
5. Dispute Period: After this step, a 1-2 hour dispute period begins, during which newly computed rewards cannot be claimed yet. However, rewards from the previous merkle root remain claimable. During this period, dispute bots verify the published reward file. If an inconsistency is found, a dispute can be raised to halt incorrect distributions before they become effective.
6. Reward Availability: Once the dispute period ends, users can see their rewards on any frontend integrated with the Merkl API. Users can claim rewards through a Merkl-powered frontend. Merkle proofs, required for claiming, are provided by the Merkl API or can be computed from reward files.

Key Features

• Single Merkle Root per Chain: Merkl consolidates rewards from every campaign into one merkle root per chain, so users can claim across multiple campaigns in a single transaction.
• Aggregated Updates: Campaigns operate independently, but Merkl batches their updates into a single onchain transaction per chain.
• Automatic Catch-Up Mechanism: If any rewards are not included in an update, they are automatically distributed in the next cycle. The Merkl engine ensures no missed rewards, processing only the data from the previous execution point.
• Unclaimed Rewards Roll Over: Users can claim at any time. Each merkle tree update starts from the previous tree's state and adds the new rewards, so unclaimed amounts always carry forward into the published root.

🤿 Deep-Dive

Reward Computation

Reward computation (or "compute") is the process by which the Merkl Engine calculates reward allocations based on campaign rules.

Computation mechanism: The Merkl Engine relies on events to reconstruct the exact position of each participant, then computes an integral over the selected time frame for every user — with no approximations. Each user is rewarded proportionally to their individual area under the curve, relative to the total area of all participants.

In rare cases, events alone aren't enough to reconstruct exact positions — for example, lending-market debt accrues continuously but only emits an event when a user interacts with the market. To handle this, the Merkl Engine tracks invariants: at regular intervals it compares the total event-based positions against the onchain value (e.g. calling totalDebt() on the market). If the two differ by more than 1%, it reads each user's position onchain to correct the computed value and stay exact.

Computation frequency: The Merkl engine processes rewards for each campaign approximately every 2 hours on average, analyzing all relevant onchain events affecting the incentivized asset.

After computation: Once a campaign completes its computation cycle, rewards are not immediately claimable onchain but appear as pending rewards in user dashboards.

Parallel processing: Campaigns on a chain are processed independently and in parallel. This means rewards from some campaigns may be available onchain while others are still computing or awaiting updates.

Delayed computations: Occasionally, campaign computations may be delayed due to processing constraints. Track delayed campaigns on the Merkl status page.

Continuous processing: When a campaign is processed, the Merkl Engine resumes from its last checkpoint, ensuring complete reward coverage even when updates occur at different intervals.

Reward Updates

Reward updates are the process of posting computed rewards onchain, making them claimable by users.

Update frequency: Reward updates occur approximately every 8 hours (ranging from 4 to 12 hours), depending on the chain.

Delayed updates: Like computations, updates may occasionally be delayed. Monitor update status on the Merkl status page.

Transparency: Each reward update includes a publicly available reward file on the status page for transparency and auditability.

Independent cycles: Reward computation and reward updates operate on independent schedules. Updates push the results of completed computations onchain, but the two processes follow separate lifecycles.

Example: Between two reward updates (8 hours apart on average), a campaign's rewards may be recomputed up to four times. Each computation refines the pending rewards, but they only become claimable when the next update occurs.

Rollover mechanism: Unclaimed rewards automatically roll over into subsequent reward updates, allowing users to claim at their convenience.

Tracking updates: View the last reward update for each chain on the Merkl status page.

Disputes

The dispute period is a security window of 1-2 hours following each reward update during which anyone can contest reward allocations made by the Merkl engine. This safeguard ensures the integrity and consistency of the reward infrastructure and allows campaign creators to oversee the reward computations before they become final and claimable.

Raising a dispute: If an issue is detected during the dispute period or if you want to contest reward allocations for a campaign, raise a dispute by sending a disputeToken to the Merkl Distributor contract.

Dispute outcomes:

• Valid dispute: The merkle root is revoked and the disputer is refunded
• Invalid dispute: The disputer forfeits their funds and the dispute period restarts

Dispute parameters: Retrieve dispute conditions (disputeToken, disputeAmount, disputePeriod) from the Distributor contract on the relevant chain.

Dispute Bots

Security infrastructure: The Merkl team operates several independent dispute bots on separate infrastructure to ensure redundancy and prevent malicious actors from compromising the reward update process.

Open-source reference: While the production bot code is closed source for security reasons, you can reference this open-source repository to understand how to build a dispute bot.

📌 Key Merkl Concepts

Opportunity vs. Campaign

Understanding the distinction between opportunities and campaigns is fundamental to how Merkl operates.

• Campaign: An individual incentive program created by a campaign creator with specific parameters including a distribution type, a scoring type, customization options, a budget amount, and a duration. Each campaign has a specific type and targets a particular onchain behavior (e.g., providing liquidity in a pool, holding a token, lending/borrowing). This targeted behavior represents an opportunity.
• Opportunity: A specific asset (e.g., pool, vault) and its associated action (e.g., depositing liquidity, borrowing assets) that can be incentivized. Multiple campaigns can run in parallel on a single opportunity, meaning users performing one onchain action can simultaneously earn rewards from several different campaigns.
  Example: Providing liquidity to a SushiSwap V3 pool is an opportunity that may have multiple active campaigns offering different rewards.

Main Metrics

The following metrics are fundamental to Merkl and appear throughout all Merkl user-facing components: the API, the app, and Merkl Studio.

Daily Rewards

Daily rewards for a campaign represent the total amount of tokens or points distributed each day, shared among all eligible users of the campaign. While this number is typically accurate, it may be estimated for certain distribution types (such as fixed and capped reward rates) that distribute based on the eligible TVL in the campaign.

When multiple campaigns run on an opportunity, including subcampaigns, the daily rewards displayed for the opportunity represent the sum of all individual campaign daily rewards.

TVL

The Total Value Locked (TVL) of a campaign on Merkl represents the total value of eligible assets for the campaigns on the opportunity. This reflects only the assets that meet the campaign's eligibility criteria, for example:

• if a campaign includes a blacklist, the TVL excludes the value held by blacklisted addresses.
• for certain campaign types like net-lending campaigns, the TVL represents the net supplied TVL (i.e., total supplied minus borrowed), as this reflects only the liquidity that's eligible for rewards.

In these cases, Merkl may initially approximate the TVL and requires an engine computation to display the accurate TVL for the campaign. As such, the TVL may not be accurate at launch for newly created campaigns. In some situations, the TVL might also be over- or underestimated due to approximations made for computational efficiency or because exact computing logic has not yet been implemented.

When the Merkl system has a fallback mechanism, TVL values update every 10 minutes on the Merkl app and API. For complex campaigns without such fallbacks, TVLs (and consequently APRs) only update after each computation cycle. This means TVL updates may occur at most every 2 hours for the opportunities related to these campaigns.

Overall, the TVL serves as a key indicator of the market or pool's size and liquidity depth.

When multiple campaigns run on the same opportunity with different eligibility rules, the displayed TVL for the opportunity is the maximum eligible TVL across all campaigns.

APR

The Annual Percentage Rate (APR) represents the yearly return from participating in a campaign, expressed as a percentage. Depending on the distribution type, the APR can be fixed and remain constant throughout the campaign, or it can be variable and fluctuate based on factors such as eligible TVL and the number of participants.

For distribution types where the APR is not fixed, the APR for a campaign is calculated as:

$$\frac{\text{Daily Rewards} \times 365}{\text{Eligible TVL}}$$

In these cases, the APR updates at the same frequency as the eligible TVL (every 10 minutes for simple campaigns, or every 2 hours for more complex campaigns where TVL cannot be simply approximated).

At the opportunity level, the displayed APR is the sum of the APRs from all campaigns (including subcampaigns) running on that opportunity.

🧱 User-Facing Components

Beyond the Merkl engine and dispute bots, the Merkl ecosystem includes several user-facing components that work together to enable campaign creation, reward tracking, and claiming.

Merkl Smart Contracts

Deployed on each blockchain integrated by Merkl, Merkl's smart contracts store campaign data, hold incentive tokens, and process reward claims.

These contracts are publicly available. Smart contract addresses (categorized by chain) along with audits are available here.

Key contracts:

• DistributionCreator: Stores campaign details and configurations.
• Distributor: Holds tokens and processes reward claims based on merkle proofs.
• AccessControlManager: A multisig-controlled contract that manages disputes, fees, and access control but cannot alter distributions. Merkl contracts are ultimately controlled by a 4/6 multisig with 6 independent signers, and there are never more than 3 signers physically present in the same location.

Merkl API

The Merkl API provides real-time access to Merkl data, including rewards, APRs, merkle proofs, and analytics. This API enables any frontend to integrate Merkl seamlessly.

Merkl App

The Merkl App, built on the Merkl API, enables users to explore reward opportunities, track APRs, and seamlessly claim their rewards.

The interface is organized around several types of pages:

• Home page (all opportunities) – displays all available opportunities with filtering options
• Opportunity page – dedicated view for each opportunity with all its campaigns
• Protocol / Chain / Liquidity program page – groups all opportunities related to a specific protocol, chain, or program
• Dashboard – where users can claim their rewards

.png)

Detailed info for each campaign running on an opportunity is available across several tabs:

• Overview: global details such as dates, APR, and eligibility rules.
• Advanced: distribution progress, last update, creator address, and campaign ID.
• Leaderboard: the list of addresses participating in the opportunity.
• Linked opportunities (optional): displays opportunities connected through shared liquidity and rewards

Merkl Studio

Merkl Studio is the command center for campaign creators. It enables anyone to launch and manage incentive campaigns independently within minutes, providing powerful tools for campaign configuration and oversight.