Technical Overview
Technical overview of the Merkl system
Merkl operates through an offchain engine that analyzes both onchain and offchain data to track user activity and allocate rewards based on campaign rules set by campaign creators. The Merkl engine processes reward data into a merkle tree, compresses it into a merkle root, and pushes it onchain, enabling users to claim rewards transparently and 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
Campaign Creation: Campaign creators set up campaigns using a smart contract called the Merkl Distribution Creator. This includes defining eligibility criteria, reward structures, and distribution methods. Campaign details are pushed onchain, along with the incentive tokens that need to be distributed
User Participation: Users engage with the protocol (e.g., providing liquidity, lending, borrowing) in order to earn the rewards/points as specified in the campaign.
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. After this step, users can see that they have earned rewards which are only pending as they cannot claim them yet (awaiting reward update).
Reward Update: At regular intervals as well (potentially different from the reward computation intervals), the Merkl Engine generates a merkle tree from processed campaigns. This tree is then compressed as a merkle root that is pushed onchain to a contract called the Merkl Distributor contract. A reward file is also made available on the Merkl status page, in order to ensure transparency and enable anyone to manually audit past reward distributions.
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.
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 Merkl Root per Chain: Merkl consolidates rewards from multiple campaigns into one merkle root per chain, enabling efficient batch claiming rewards from multiple different campaigns in a single transaction.
Aggregated Campaigns: While campaigns operate independently, Merkl batches multiple campaign updates into a single onchain transaction
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 their rewards at anytime they want: each merkle tree update takes the previous merkle tree state and simply adds the new rewards, which are then reflected in the published merkle 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 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.
Dispute Period & Process
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 compute 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 also, the TVL might be over or underestimated due to approximations for computational simplicity or because exact computing logic has not yet been implemented.
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) within Merkl 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 the number of participants.
For distribution types where the APR is not defined as fixed, the main APR for a campaign is calculated as:
At the level of an opportunity, the APR is the sum of the APRs of the campaigns (including the subcampaigns) running on this 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 contract are publicly available and have been audited by Code4rena (Audit Report).
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.
Smart contract addresses, categorized by chain are listed here.
Merkl API
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 campains
Protocol / Chain / Liquidity program page – groups all opportunities related to a specific protocol, chain, or program
Dashboard – where users can claim their rewards
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 snapshot, creator address, and campaign ID,…
Leaderboard: 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.
Last updated