Campaign Configuration

Understanding Campaign Configurations on Merkl

A campaign configuration is the collection of all parameters—such as campaign type, distribution method, and customization options—that define how a campaign operates. It serves as the source of truth for the Merkl engine.

When a campaign is launched, an encoded version of this configuration is stored onchain in the Merkl Distribution Creator contract. The Merkl engine continuously monitors this contract to detect new campaigns, then parses each configuration to understand among others:

  • What type of user activity to track (e.g., providing liquidity, holding tokens, lending assets)

  • How to calculate user scores based on their participation

  • How rewards should be distributed over time

  • Which addresses are eligible or excluded from rewards

This configuration-driven approach allows Merkl to support diverse incentive mechanisms while maintaining a unified reward computation and distribution infrastructure.

Creating and Retrieving Configurations

You can generate or retrieve campaign configurations in two main ways:

  • Via Merkl Studio: When you create a campaign using Merkl Studio, the configuration is generated automatically.

  • Via Merkl API: You can programmatically generate or retrieve configurations using the Merkl API.

You can also retrieve the configuration of any existing campaign using its database ID via this Merkl API endpoint.

Configuration Structure

A campaign configuration is typically represented as a JSON object containing various parameters.

Common Parameters

These parameters are standard across most campaigns:

  • creator: The address managing the campaign

  • rewardToken: The address of the token distributed as rewards

  • distributionChainId: The chain ID where rewards are distributed

  • computeChainId: The chain ID where user activity is tracked (can differ from distributionChainId for cross-chain campaigns)

  • startTimestamp: The start date of the campaign (Unix timestamp)

  • endTimestamp: The end date of the campaign (Unix timestamp)

  • amount: The total amount of rewards to be distributed

  • blacklist: A list of addresses excluded from receiving rewards

  • whitelist: A list of addresses allowed to receive rewards (if set, all others are excluded)

  • campaignType: The campaign type

  • computeScoreParameters: The scoring method used by the campaign

  • distributionMethodParameters: The distribution method for reward distribution

You can use this converter to convert dates to Unix timestamps.

Distribution Methods

The distributionMethodParameters field defines how rewards are distributed over time.

Variable Reward Rate (Dutch Auction):

{
  "distributionMethod": "DUTCH_AUCTION"
}

Fixed APR:

{
  "distributionMethod": "FIX_APR",
  "distributionSettings": {
      "apr": "0.08",
      "targetToken": "0x...",
      "rewardTokenPricing": true,
      "targetTokenPricing": true
  }
}

Capped APR:

{
  "distributionMethod": "MAX_APR",
  "distributionSettings": {
      "apr": "1",
      "targetToken": "0x...",
      "rewardTokenPricing": true,
      "targetTokenPricing": true
  }
}

Campaign-Specific Parameters

Each campaign type has its own set of specific parameters in addition to the common parameters listed above.

Examples by Campaign Type:

  • ERC20 / Token Holding (Type 18) - Example config

    • targetToken: Address of the token to incentivize (or LP token for V2 pools)

  • Uniswap V3 (Type 2) - Example config

    • poolAddress: The pool address

    • weightToken0, weightToken1, weightFees: Weights for scoring liquidity

  • Uniswap V4 (Type 13) - Example config

    • Specific hook and pool parameters

  • Morpho (Type 57) - Example config

    • targetToken: Address of the supplied token on a Morpho Market

  • Euler Supply (Type 12) - Example config

    • evkAddress: Address of the incentivized vault

  • Euler Borrow (Type 12) - Example config

    • evkAddress: Address of the incentivized vault

Encoding and Decoding Configurations

The Merkl API provides endpoints to convert between campaign configurations and the encoded format used onchain.

Encoding configurations for onchain deployment:

Decoding onchain campaign data into configurations:

PreviousAdditional FeaturesNextGlossary

Last updated