Cap Merkl MAX_APR incentive rewards at aprCap (v158: +migration & backfill)

Author: apexearth

db/migrations/1782950000000-AddMerklDistributionFields.js

@@ -0,0 +1,21 @@
+module.exports = class AddMerklDistributionFields1782950000000 {
+  name = 'AddMerklDistributionFields1782950000000'
+
+  // Adds the Merkl distribution-strategy fields to the live merkl_campaign table (the running
+  // v158 DB predates them), then backfills the one existing ARM campaign. Its row was captured
+  // before these fields existed, so without the backfill it would keep using the uncapped max
+  // budget instead of the MAX_APR (2%) cap. New campaigns capture these at resolve time.
+  async up(db) {
+    await db.query(`ALTER TABLE "merkl_campaign" ADD "distribution_method" text`)
+    await db.query(`ALTER TABLE "merkl_campaign" ADD "apr_cap" numeric`)
+    await db.query(
+      `UPDATE "merkl_campaign" SET "distribution_method" = 'MAX_APR', "apr_cap" = 0.02 ` +
+        `WHERE "campaign_id" = '0x459f4891c0a39a940a938e81122017aa8d7509abf73cddef3b5fb7c14bb3124c'`,
+    )
+  }
+
+  async down(db) {
+    await db.query(`ALTER TABLE "merkl_campaign" DROP COLUMN "apr_cap"`)
+    await db.query(`ALTER TABLE "merkl_campaign" DROP COLUMN "distribution_method"`)
+  }
+}

schema.graphql

@@ -109,6 +109,12 @@ type MerklCampaign @entity {
   endTimestamp: DateTime!
   # Seconds; mutable via overrideCampaign.
   duration: Int!
+  # Merkl distribution strategy (params.distributionMethodParameters.distributionMethod), e.g.
+  # "MAX_APR". Determines actual emission vs the max (amount/duration). null if unknown.
+  distributionMethod: String
+  # APR cap for MAX_APR campaigns (params.distributionSettings.apr, e.g. 0.02 = 2%); null when
+  # uncapped. Actual daily rewards = min(amount/duration, aprCap * TVL / 365).
+  aprCap: Float
   # Raw 32-byte campaignData (off-chain payload pointer/hash), for reference.
   campaignData: String!
   # Resolved via Merkl API (params.targetToken) at capture time: the contract whose

src/mainnet/processors/merkl.graphql

@@ -20,6 +20,12 @@ type MerklCampaign @entity {
   endTimestamp: DateTime!
   # Seconds; mutable via overrideCampaign.
   duration: Int!
+  # Merkl distribution strategy (params.distributionMethodParameters.distributionMethod), e.g.
+  # "MAX_APR". Determines actual emission vs the max (amount/duration). null if unknown.
+  distributionMethod: String
+  # APR cap for MAX_APR campaigns (params.distributionSettings.apr, e.g. 0.02 = 2%); null when
+  # uncapped. Actual daily rewards = min(amount/duration, aprCap * TVL / 365).
+  aprCap: Float
   # Raw 32-byte campaignData (off-chain payload pointer/hash), for reference.
   campaignData: String!
   # Resolved via Merkl API (params.targetToken) at capture time: the contract whose

src/mainnet/processors/merkl.ts

@@ -29,7 +29,24 @@ type CampaignStruct = ReturnType<typeof abi.events.NewCampaign.decode>['campaign
  * so Subsquid retries it later — no partial/null data is ever written, and the processor
  * pauses rather than crashing.
  */
-type ResolvedCampaign = { targetToken: string | null; rewardTokenDecimals: number }
+type ResolvedCampaign = {
+  targetToken: string | null
+  rewardTokenDecimals: number
+  distributionMethod: string | null
+  aprCap: number | null
+}
+
+type MerklCampaignApi = {
+  campaignId?: string
+  params?: {
+    targetToken?: string
+    decimalsRewardToken?: number
+    distributionMethodParameters?: {
+      distributionMethod?: string
+      distributionSettings?: { apr?: string | number }
+    }
+  }
+}
 
 const resolveCampaign = async (ctx: Context, chainId: number, campaignId: string): Promise<ResolvedCampaign> => {
   // test=true includes test campaigns in the response (additive — live campaigns still returned).
@@ -41,12 +58,19 @@ const resolveCampaign = async (ctx: Context, chainId: number, campaignId: string
     try {
       const res = await fetch(url)
       if (!res.ok) throw new Error(`status ${res.status}`)
-      const data = (await res.json()) as { campaignId?: string; params?: { targetToken?: string; decimalsRewardToken?: number } }[]
+      const data = (await res.json()) as MerklCampaignApi[]
       const match = data.find((c) => c?.campaignId?.toLowerCase() === campaignId.toLowerCase())
       if (!match) throw new Error('campaign not yet indexed by Merkl')
+      const dist = match.params?.distributionMethodParameters
+      // MAX_APR campaigns cap the reward rate; distributionSettings.apr is the cap (e.g. "0.02").
+      const aprCap = dist?.distributionMethod === 'MAX_APR' && dist.distributionSettings?.apr != null
+        ? Number(dist.distributionSettings.apr)
+        : null
       return {
         targetToken: match.params?.targetToken?.toLowerCase() ?? null,
         rewardTokenDecimals: match.params?.decimalsRewardToken ?? 18,
+        distributionMethod: dist?.distributionMethod ?? null,
+        aprCap: Number.isFinite(aprCap) ? aprCap : null,
       }
     } catch (err) {
       lastError = err
@@ -77,7 +101,11 @@ const upsertFromStruct = async (
   if (!creatorSet.has(campaign.creator.toLowerCase())) return
 
   const id = `${ctx.chain.id}:${campaign.campaignId}`
-  const { targetToken, rewardTokenDecimals } = await resolveCampaign(ctx, ctx.chain.id, campaign.campaignId)
+  const { targetToken, rewardTokenDecimals, distributionMethod, aprCap } = await resolveCampaign(
+    ctx,
+    ctx.chain.id,
+    campaign.campaignId,
+  )
   const timestamp = new Date(block.header.timestamp)
   const existing = campaigns.get(id) ?? (await ctx.store.get(MerklCampaign, id))
 
@@ -97,6 +125,8 @@ const upsertFromStruct = async (
 
   // Resolved target (Merkl API), and the ARM it rewards when the target is one of ours.
   entity.rewardTokenDecimals = rewardTokenDecimals
+  entity.distributionMethod = distributionMethod
+  entity.aprCap = aprCap
   entity.targetToken = targetToken
   entity.armAddress = targetToken && armSet.has(targetToken) ? targetToken : null
   // Mutable fields (overrideCampaign can change start/duration/campaignData).

src/model/generated/merklCampaign.model.ts

@@ -1,4 +1,4 @@
-import {Entity as Entity_, Column as Column_, PrimaryColumn as PrimaryColumn_, IntColumn as IntColumn_, Index as Index_, StringColumn as StringColumn_, BigIntColumn as BigIntColumn_, DateTimeColumn as DateTimeColumn_} from "@subsquid/typeorm-store"
+import {Entity as Entity_, Column as Column_, PrimaryColumn as PrimaryColumn_, IntColumn as IntColumn_, Index as Index_, StringColumn as StringColumn_, BigIntColumn as BigIntColumn_, DateTimeColumn as DateTimeColumn_, FloatColumn as FloatColumn_} from "@subsquid/typeorm-store"
 
 @Entity_()
 export class MerklCampaign {
@@ -44,6 +44,12 @@ export class MerklCampaign {
     @IntColumn_({nullable: false})
     duration!: number
 
+    @StringColumn_({nullable: true})
+    distributionMethod!: string | undefined | null
+
+    @FloatColumn_({nullable: true})
+    aprCap!: number | undefined | null
+
     @StringColumn_({nullable: false})
     campaignData!: string
 

src/templates/origin-arm/arm-incentive-apy.ts

@@ -19,6 +19,8 @@ const TOKEN0_DECIMALS = 18
  *   - incentiveYield: that value expressed in token0 units (parallel to ArmDailyStat.yield)
  *   - incentiveApr:   dailyRewardUSD / TVL_USD * 365.25
  *   - incentiveApy:   the same, daily-compounded
+ * MAX_APR campaigns (aprCap set) don't emit their full budget — Merkl caps the daily payout at
+ * aprCap * TVL / 365 — so we use min(maxDaily, cappedDaily), matching what holders actually earn.
  * Reward tokens are valued via the exchange-rate infra; unpriceable ones are skipped rather than
  * failing the batch. Returns zeros when no campaigns are active.
  */
@@ -50,6 +52,10 @@ export const calculateArmIncentiveApy = async (
   })
   if (campaigns.length === 0) return zero
 
+  const token0PriceUSD = +formatUnits(rateUSD?.rate ?? 0n, rateUSD?.decimals ?? 18)
+  if (token0PriceUSD <= 0) return zero
+  const tvlUSD = +formatUnits(totalAssets, TOKEN0_DECIMALS) * token0PriceUSD
+
   let dailyRewardsUSD = 0
   for (const campaign of campaigns) {
     const durationDays = campaign.duration / 86_400
@@ -64,22 +70,22 @@ export const calculateArmIncentiveApy = async (
       continue
     }
     if (priceUSD <= 0) continue
-    const dailyTokens = +formatUnits(campaign.amount, campaign.rewardTokenDecimals) / durationDays
+    // Max daily emission: the full budget spread evenly over the campaign duration.
+    const maxDailyUSD = (+formatUnits(campaign.amount, campaign.rewardTokenDecimals) / durationDays) * priceUSD
+    // MAX_APR campaigns cap the rate: Merkl distributes only min(maxDaily, aprCap * TVL / 365), so a
+    // small pool earns far less than the max budget. Uncapped campaigns emit the full daily budget.
+    const dailyUSD =
+      campaign.aprCap != null && tvlUSD > 0 ? Math.min(maxDailyUSD, (campaign.aprCap * tvlUSD) / 365) : maxDailyUSD
     // Prorate the first/last day by how much of it the campaign is active.
     const overlapMs =
       Math.min(endOfDay.getTime(), campaign.endTimestamp.getTime()) -
       Math.max(startOfDay.getTime(), campaign.startTimestamp.getTime())
     const activeFraction = Math.max(0, Math.min(1, overlapMs / DAY_MS))
-    dailyRewardsUSD += dailyTokens * priceUSD * activeFraction
+    dailyRewardsUSD += dailyUSD * activeFraction
   }
 
-  const token0PriceUSD = +formatUnits(rateUSD?.rate ?? 0n, rateUSD?.decimals ?? 18)
-  if (token0PriceUSD <= 0) return zero
-
   // Express the day's reward value in token0 units, to parallel ArmDailyStat.yield.
   const incentiveYield = parseUnits((dailyRewardsUSD / token0PriceUSD).toFixed(TOKEN0_DECIMALS), TOKEN0_DECIMALS)
-
-  const tvlUSD = +formatUnits(totalAssets, TOKEN0_DECIMALS) * token0PriceUSD
   if (tvlUSD <= 0) return { ...zero, incentiveYield }
 
   const dailyRate = dailyRewardsUSD / tvlUSD