@merkl/api 1.20.0 → 1.20.21

package/dist/src/modules/v4/leaf/leaf.service.d.ts

@@ -1,6 +1,8 @@
 import type { TokenType } from "@package/databases";
 import type { ChainId } from "@package/resources/enums";
-import type { RootsByChain } from "./leaf.model";
+import type { RootsByChain, TempLeaf } from "./leaf.model";
+import { LeafRepository } from "./leaf.repository";
+type Token = Awaited<ReturnType<typeof LeafRepository.getTokensByKeys>>[number];
 export declare abstract class LeafService {
     /** Fetches leaves for a recipient, reconciling with pending temp leaves from the engine. */
     static getByRecipient(recipient: string, roots: RootsByChain, tags: string[], options?: {
@@ -10,6 +12,7 @@ export declare abstract class LeafService {
         withTestTokens?: boolean;
         reasonFilter?: string;
         type?: TokenType;
+        tokenAddresses?: string[];
         skipBreakdowns?: boolean;
         chainFilter?: ChainId[] | null;
     }): Promise<{
@@ -395,30 +398,55 @@ export declare abstract class LeafService {
         }[];
     }[]>;
     /**
-     * Fetches per-`(chain, opportunity, token)` reward totals for a recipient, with the resolved
-     * `Opportunity` (including standard relations) and every `Campaign` linked to those opps —
-     * sufficient for opportunity-level privacy masking via `CampaignService.checkAccessBatch`.
+     * Lean per-`(chain, token)` rollup of a recipient's rewards — bypasses `getByRecipient`'s heavy
+     * `Breakdowns → Campaign → Opportunity → ...` include tree.
      *
-     * Implementation:
-     *   1. Step 1 (sums) is served by the `leaf_breakdown_amounts_per_recipient_opportunity`
-     *      materialized view via `LeafViewRepository.amountsByRecipientOpportunity` — pre-aggregated
-     *      and refreshed every 30 min, mirroring every other recipient-keyed reward MV.
-     *   2. Step 2 (campaigns + opportunities per `(chain, opp)`) goes through `CampaignService.findMany`
-     *      and `OpportunityService.findMany` in parallel; both apply formatting and centralize
-     *      access semantics.
+     * Designed for `/users/:address/rewards/summary` and `/users/:address/rewards/stats` where only
+     * `amount` / `claimed` / `pending` / `proofs` per `(chain, token)` are needed. The protocol
+     * filter is pushed to SQL via `Breakdowns.some.Opportunity.mainProtocolId` — no second roundtrip.
      *
-     * Privacy semantic: campaigns checked for access are **all campaigns linked to each opp**, not
-     * only those the recipient earned from. This means an opp where the recipient only earned from
-     * a private campaign but where a public sibling campaign exists will resolve as accessible.
+     * `pending` is computed by matching live `LeafBreakdown` rows against `TempLeaves` (engine DB)
+     * and unmerged `DiffBreakdowns` for the in-flight tree root, mirroring the per-breakdown logic
+     * in `reconcileLeaf` but aggregated to `(chain, token)`. Unmatched temp leaves (orphans) are
+     * filtered against `type` / `isTest` / `tokenAddresses` and either folded into pending for an
+     * existing leaf row or emitted as phantom rows with `amount = "0"`, `proofs = []`.
      *
-     * Staleness: `amount` / `claimed` reflect the MV refresh cadence (≤ 30 min). Acceptable for the
-     * rewards-summary surface (display-only); not safe for transactional reads.
+     * Mutability contract: returned rows are plain objects (no Prisma references); callers may
+     * mutate `claimed` in place — used by `RewardService.checkLastClaim` for on-chain reconciliation.
+     */
+    static getSummaryByRecipient(recipient: string, roots: RootsByChain, options?: {
+        chainFilter?: ChainId[] | null;
+        type?: TokenType;
+        withTestTokens?: boolean;
+        tokenAddresses?: string[];
+        protocols?: string[];
+    }): Promise<Array<{
+        distributionChainId: number;
+        tokenAddress: string;
+        amount: string;
+        claimed: string;
+        pending: string;
+        proofs: string[];
+        RewardToken: Token;
+    }>>;
+    /**
+     * Per-`(chain, opportunity, token)` reward sums for a recipient, **restricted to LIVE
+     * opportunities**. Each row carries the opportunity (heavy includes) and every `Campaign`
+     * linked to that opp — the campaign list drives opportunity-level privacy masking via
+     * `CampaignService.checkAccessBatch`.
+     *
+     * Sums come from `leaf_breakdown_amounts_per_recipient_opportunity` (≤30 min stale). The
+     * LIVE-status filter is pushed into the `Opportunity` and `Campaign` SQL queries so we never
+     * hydrate non-LIVE rows or their campaigns. Sums whose opportunity is non-LIVE are dropped.
      *
-     * Currency: `amount` and `claimed` are raw token-decimal integers (never USD); grouping by
-     * `tokenAddress` keeps every output row single-currency. USD conversion remains a JS-side
-     * concern in `getRewardsSummary`.
+     * Privacy semantic: an opp is accessible if ANY linked campaign is accessible — even campaigns
+     * the recipient didn't earn from. Currency: `amount` / `claimed` are raw token-decimal integers;
+     * grouping by `tokenAddress` keeps every output row single-currency.
      */
-    static getBreakdownsByOpportunity(recipient: string, distributionChainIds: number[]): Promise<{
+    static getBreakdownsByOpportunity(recipient: string, distributionChainIds: number[], options?: {
+        withTestTokens?: boolean;
+        liveOnly?: boolean;
+    }): Promise<{
         distributionChainId: number;
         opportunityId: string;
         tokenAddress: string;
@@ -440,196 +468,6 @@ export declare abstract class LeafService {
             maxDailyRewards: number;
             tags: string[];
             liveCampaigns: number;
-            aprRecord: {
-                cumulated: number;
-                timestamp: bigint;
-                breakdowns: ({
-                    distributionType: import("@package/databases").DistributionType;
-                    identifier: string;
-                    type: "CAMPAIGN";
-                    timestamp: bigint;
-                    value: number;
-                } | {
-                    identifier: string;
-                    type: import("@package/databases").AprType;
-                    timestamp: bigint;
-                    value: number;
-                })[];
-            };
-            nativeAprRecord: {
-                title: string;
-                description: string | undefined;
-                value: number;
-                timestamp: bigint;
-                amount: bigint | undefined;
-                rewardToken: {
-                    id: string;
-                    name: string | null;
-                    chainId: number;
-                    address: string;
-                    decimals: number;
-                    symbol: string;
-                    icon: string;
-                    verified: boolean;
-                    isNative: boolean;
-                    isTest: boolean;
-                    type: "POINT" | "PRETGE" | "TOKEN";
-                    price?: number | null | undefined;
-                    updatedAt?: number | null | undefined;
-                    priceSource?: string | null | undefined;
-                    displaySymbol?: string | undefined;
-                    underlyingTokenId?: string | undefined;
-                    priceAlertDismissedAt?: number | undefined;
-                    priceAlertCount?: number | undefined;
-                } | undefined;
-            };
-            tvlRecord: {
-                id: string;
-                total: number;
-                timestamp: bigint;
-                breakdowns: {
-                    identifier: string;
-                    type: import("@package/databases").TvlType;
-                    value: number;
-                }[];
-            };
-            rewardsRecord: {
-                id: string;
-                total: number;
-                timestamp: bigint;
-                breakdowns: {
-                    id: string;
-                    timestamp: bigint;
-                    campaignId: string;
-                    dailyRewardsRecordId: string;
-                    token: {
-                        id: string;
-                        name: string | null;
-                        chainId: number;
-                        address: string;
-                        decimals: number;
-                        symbol: string;
-                        icon: string;
-                        verified: boolean;
-                        isNative: boolean;
-                        isTest: boolean;
-                        type: "POINT" | "PRETGE" | "TOKEN";
-                        price?: number | null | undefined;
-                        updatedAt?: number | null | undefined;
-                        priceSource?: string | null | undefined;
-                        displaySymbol?: string | undefined;
-                        underlyingTokenId?: string | undefined;
-                        priceAlertDismissedAt?: number | undefined;
-                        priceAlertCount?: number | undefined;
-                    };
-                    amount: bigint;
-                    maxAmount: bigint;
-                    value: number;
-                    maxValue: number;
-                    distributionType: import("@package/databases").DistributionType;
-                    onChainCampaignId: string;
-                }[];
-            };
-            campaigns: (Omit<import("../campaign/campaign.model").CampaignWithParams<import("@package/resources/enums").CampaignType>, "createdAt" | "endTimestamp" | "manualOverrides" | "parentCampaignId" | "pauseCompute" | "pausePrecompute" | "rootCampaignId" | "startTimestamp" | "subType"> & {
-                subType: number | null;
-                startTimestamp: number;
-                endTimestamp: number;
-                createdAt: string;
-                parentCampaignId?: string | undefined;
-                rootCampaignId?: string | undefined;
-                pauseCompute?: string | undefined;
-                pausePrecompute?: string | undefined;
-            } & {
-                Opportunity: {
-                    chainId: number;
-                    type: string;
-                    identifier: string;
-                    name: string;
-                    description: string;
-                    howToSteps: string[];
-                    status: import("@package/databases").Status;
-                    action: import("@package/databases").OpportunityAction;
-                    tvl: number;
-                    apr: number;
-                    maxApr: number | null;
-                    dailyRewards: number;
-                    maxDailyRewards: number;
-                    tags: string[];
-                    liveCampaigns: number;
-                    tokens: {
-                        id: string;
-                        name: string | null;
-                        chainId: number;
-                        address: string;
-                        decimals: number;
-                        symbol: string;
-                        icon: string;
-                        verified: boolean;
-                        isNative: boolean;
-                        isTest: boolean;
-                        type: "POINT" | "PRETGE" | "TOKEN";
-                        price?: number | null | undefined;
-                        updatedAt?: number | null | undefined;
-                        priceSource?: string | null | undefined;
-                        displaySymbol?: string | undefined;
-                        underlyingTokenId?: string | undefined;
-                        priceAlertDismissedAt?: number | undefined;
-                        priceAlertCount?: number | undefined;
-                    }[];
-                    chain: {
-                        id: number;
-                        name: string;
-                        icon: string;
-                        liveCampaigns: number;
-                        endOfDisputePeriod: number;
-                        explorers?: {
-                            type: "BLOCKSCOUT" | "ETHERSCAN" | "SOLSCAN";
-                            url: string;
-                            chainId: number;
-                        }[] | undefined;
-                        lastClaimsOnchainFetchTimestamp: string | null;
-                    };
-                    protocol: {
-                        id: string;
-                        tags: string[];
-                        name: string;
-                        description: string;
-                        url: string;
-                        icon: string;
-                        banner: string | null;
-                        opportunityBannerLight: string | null;
-                        opportunityBannerDark: string | null;
-                    } | undefined;
-                    activePrograms: {
-                        icon: string;
-                        id: string;
-                        name: string;
-                        slug: string | null;
-                    }[];
-                    depositUrls: {
-                        id: string;
-                        title: string;
-                        url: string;
-                        subtitle?: string | undefined;
-                        icon?: string | undefined;
-                        priority: number;
-                    }[] | undefined;
-                    id: string;
-                    hidden: true | undefined;
-                    nativeApr: number | undefined;
-                    depositUrl: string | undefined;
-                    explorerAddress: string | undefined;
-                    lastCampaignCreatedAt: number;
-                    earliestCampaignStart: bigint | undefined;
-                    latestCampaignStart: bigint | undefined;
-                    earliestCampaignEnd: bigint | undefined;
-                    latestCampaignEnd: bigint | undefined;
-                };
-            })[] | undefined;
-            liveCampaignsForCreator?: any;
-            soonCampaignsForCreator?: any;
-            pastCampaignsForCreator?: any;
-            distributedBycreator?: any;
             tokens: {
                 id: string;
                 name: string | null;
@@ -698,311 +536,42 @@ export declare abstract class LeafService {
             latestCampaignStart: bigint | undefined;
             earliestCampaignEnd: bigint | undefined;
             latestCampaignEnd: bigint | undefined;
-        } | ({
-            id: string;
-            type: string;
-            identifier: string;
-            chainId: number;
-            name: string;
-            description: string;
-            howToSteps: string[];
-            status: "LIVE" | "NONE" | "PAST" | "SOON";
-            action: "BORROW" | "DROP" | "HOLD" | "INVALID" | "LEND" | "LONG" | "POOL" | "SHORT" | "STAKE" | "SWAP";
-            tags: string[];
-            mainProtocol?: string | undefined;
-            depositUrl?: string | undefined;
-            depositUrls?: {
-                id: string;
-                title: string;
-                url: string;
-                subtitle?: string | undefined;
-                icon?: string | undefined;
-                priority: number;
-            }[] | undefined;
-            explorerAddress?: string | undefined;
-            hidden?: boolean | undefined;
-            tvl: number;
-            apr: number;
-            dailyRewards: number;
-            maxDailyRewards?: number | null | undefined;
-            liveCampaigns: number;
-            lastCampaignCreatedAt: number;
-            earliestCampaignStart?: string | bigint | undefined;
-            latestCampaignStart?: string | bigint | undefined;
-            earliestCampaignEnd?: string | bigint | undefined;
-            latestCampaignEnd?: string | bigint | undefined;
-            nativeApr?: number | undefined;
-            maxApr?: number | null | undefined;
-            liveCampaignsForCreator?: number | undefined;
-            soonCampaignsForCreator?: number | undefined;
-            pastCampaignsForCreator?: number | undefined;
-            distributionType?: string | undefined;
-            tokens: {
-                id: string;
-                name: string | null;
-                chainId: number;
-                address: string;
-                decimals: number;
-                symbol: string;
-                icon: string;
-                verified: boolean;
-                isNative: boolean;
-                isTest: boolean;
-                type: "POINT" | "PRETGE" | "TOKEN";
-                price?: number | null | undefined;
-                updatedAt?: number | null | undefined;
-                priceSource?: string | null | undefined;
-                displaySymbol?: string | undefined;
-                underlyingTokenId?: string | undefined;
-                priceAlertDismissedAt?: number | undefined;
-                priceAlertCount?: number | undefined;
-            }[];
-            chain: {
-                id: number;
-                name: string;
-                icon: string;
-                liveCampaigns: number;
-                endOfDisputePeriod: number;
-                explorers?: {
-                    type: "BLOCKSCOUT" | "ETHERSCAN" | "SOLSCAN";
-                    url: string;
-                    chainId: number;
-                }[] | undefined;
-                lastClaimsOnchainFetchTimestamp: string | null;
-            };
-            activePrograms: {
-                id: string;
-                name: string;
-                slug?: string | null | undefined;
-                description?: string | undefined;
-                icon?: string | undefined;
-            }[];
-            protocol?: {
-                id: string;
-                name: string;
-                icon: string;
-                tags: string[];
-                description: string;
-                url: string;
-                dailyRewards?: number | undefined;
-                numberOfLiveCampaigns?: number | undefined;
-                opportunityLiveTags?: string[] | undefined;
-                banner: string | null;
-                opportunityBannerLight: string | null;
-                opportunityBannerDark: string | null;
-            } | null | undefined;
-            aprRecord?: {
-                cumulated: number;
-                timestamp: string | bigint;
-                breakdowns: {
-                    identifier: string;
-                    type: "CAMPAIGN" | "PROTOCOL" | "TOKEN";
-                    value: number;
-                    timestamp: string | bigint;
-                    distributionType?: "AAVE_NET_APR" | "AAVE_V4_NET_APR" | "DUTCH_AUCTION" | "ERC4626_APR" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "FIX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "MAX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | undefined;
-                }[];
-            } | undefined;
-            nativeAprRecord?: {
-                title: string;
-                description?: string | undefined;
-                value: number;
-                timestamp: string | bigint;
-                amount?: bigint | undefined;
-                rewardToken?: {
-                    id: string;
-                    name: string | null;
-                    chainId: number;
-                    address: string;
-                    decimals: number;
-                    symbol: string;
-                    icon: string;
-                    verified: boolean;
-                    isNative: boolean;
-                    isTest: boolean;
-                    type: "POINT" | "PRETGE" | "TOKEN";
-                    price?: number | null | undefined;
-                    updatedAt?: number | null | undefined;
-                    priceSource?: string | null | undefined;
-                    displaySymbol?: string | undefined;
-                    underlyingTokenId?: string | undefined;
-                    priceAlertDismissedAt?: number | undefined;
-                    priceAlertCount?: number | undefined;
-                } | undefined;
-            } | undefined;
-            tvlRecord?: {
-                total: number;
-                timestamp: string | bigint;
-                breakdowns: {
-                    identifier: string;
-                    type: "PROTOCOL" | "TOKEN";
-                    value: number;
-                }[];
-            } | undefined;
-            rewardsRecord?: {
-                total: number;
-                timestamp: string | bigint;
-                breakdowns: {
-                    campaignId: string;
-                    value: number;
-                    maxValue?: number | undefined;
-                    timestamp: string | bigint;
-                    token: {
-                        id: string;
-                        name: string | null;
-                        chainId: number;
-                        address: string;
-                        decimals: number;
-                        symbol: string;
-                        icon: string;
-                        verified: boolean;
-                        isNative: boolean;
-                        isTest: boolean;
-                        type: "POINT" | "PRETGE" | "TOKEN";
-                        price?: number | null | undefined;
-                        updatedAt?: number | null | undefined;
-                        priceSource?: string | null | undefined;
-                        displaySymbol?: string | undefined;
-                        underlyingTokenId?: string | undefined;
-                        priceAlertDismissedAt?: number | undefined;
-                        priceAlertCount?: number | undefined;
-                    };
-                    amount: string | bigint;
-                    distributionType?: "AAVE_NET_APR" | "AAVE_V4_NET_APR" | "DUTCH_AUCTION" | "ERC4626_APR" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "FIX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "MAX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | undefined;
-                    onChainCampaignId?: string | undefined;
-                }[];
-            } | undefined;
-        } & {
-            campaigns?: {
-                id: string;
-                computeChainId: number;
-                distributionChainId: number;
-                campaignId: string;
-                type: string;
-                subType?: number | null | undefined;
-                amount: string;
-                startTimestamp: string | number | bigint;
-                endTimestamp: string | number | bigint;
-                creatorAddress: string;
-                apr?: number | undefined;
-                dailyRewards?: number | undefined;
-                creator?: {
-                    address: string;
-                    tags?: string[] | undefined;
-                    creatorId?: string | null | undefined;
-                } | undefined;
-                params: unknown;
-                description?: string | undefined;
-                chain: {
-                    id: number;
-                    name: string;
-                    icon: string;
-                    liveCampaigns: number;
-                    endOfDisputePeriod: number;
-                    explorers?: {
-                        type: "BLOCKSCOUT" | "ETHERSCAN" | "SOLSCAN";
-                        url: string;
-                        chainId: number;
-                    }[] | undefined;
-                    lastClaimsOnchainFetchTimestamp: string | null;
-                };
-                rewardTokenId?: string | undefined;
-                rewardToken: {
-                    id: string;
-                    name: string | null;
-                    chainId: number;
-                    address: string;
-                    decimals: number;
-                    symbol: string;
-                    icon: string;
-                    verified: boolean;
-                    isNative: boolean;
-                    isTest: boolean;
-                    type: "POINT" | "PRETGE" | "TOKEN";
-                    price?: number | null | undefined;
-                    updatedAt?: number | null | undefined;
-                    priceSource?: string | null | undefined;
-                    displaySymbol?: string | undefined;
-                    underlyingTokenId?: string | undefined;
-                    priceAlertDismissedAt?: number | undefined;
-                    priceAlertCount?: number | undefined;
-                };
-                opportunityId?: string | undefined;
-                distributionChain?: {
-                    id: number;
-                    name: string;
-                    icon: string;
-                    liveCampaigns: number;
-                    endOfDisputePeriod: number;
-                    explorers?: {
-                        type: "BLOCKSCOUT" | "ETHERSCAN" | "SOLSCAN";
-                        url: string;
-                        chainId: number;
-                    }[] | undefined;
-                    lastClaimsOnchainFetchTimestamp: string | null;
-                } | undefined;
-                distributionType?: "AAVE_NET_APR" | "AAVE_V4_NET_APR" | "DUTCH_AUCTION" | "ERC4626_APR" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "FIX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "MAX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | undefined;
-                campaignStatus: {
-                    campaignId: string;
-                    computedUntil: string | number;
-                    processingStarted: string | number;
-                    status: string;
-                    preComputeProcessingStarted: string | number;
-                    preComputeStatus: string;
-                    delay?: number | undefined;
-                    error?: string | undefined;
-                    details?: unknown;
-                };
-                createdAt: string;
-                rootCampaignId?: string | null | undefined;
-                parentCampaignId?: string | null | undefined;
-                childCampaignIds?: string[] | undefined;
-                dailyRewardsBreakdown?: {
-                    campaignId: string;
-                    value: number;
-                    maxValue?: number | undefined;
-                    timestamp: string | bigint;
-                    token: {
-                        id: string;
-                        name: string | null;
-                        chainId: number;
-                        address: string;
-                        decimals: number;
-                        symbol: string;
-                        icon: string;
-                        verified: boolean;
-                        isNative: boolean;
-                        isTest: boolean;
-                        type: "POINT" | "PRETGE" | "TOKEN";
-                        price?: number | null | undefined;
-                        updatedAt?: number | null | undefined;
-                        priceSource?: string | null | undefined;
-                        displaySymbol?: string | undefined;
-                        underlyingTokenId?: string | undefined;
-                        priceAlertDismissedAt?: number | undefined;
-                        priceAlertCount?: number | undefined;
-                    };
-                    amount: string | bigint;
-                    distributionType?: "AAVE_NET_APR" | "AAVE_V4_NET_APR" | "DUTCH_AUCTION" | "ERC4626_APR" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "FIX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "FIX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_AMOUNT_PER_LIQUIDITY_VALUE" | "MAX_REWARD_VALUE_PER_LIQUIDITY_AMOUNT" | "MAX_REWARD_VALUE_PER_LIQUIDITY_VALUE" | undefined;
-                    onChainCampaignId?: string | undefined;
-                }[] | undefined;
-                pauseCompute?: string | null | undefined;
-                pausePrecompute?: string | null | undefined;
-                hasOverrides?: boolean | undefined;
-                isPrivate: boolean;
-                campaignEncodingHash?: string | undefined;
-            }[] | undefined;
-        }) | null;
-        Campaigns: (Omit<import("../campaign/campaign.model").CampaignWithParams<import("@package/resources/enums").CampaignType>, "createdAt" | "endTimestamp" | "manualOverrides" | "parentCampaignId" | "pauseCompute" | "pausePrecompute" | "rootCampaignId" | "startTimestamp" | "subType"> & {
-            subType: number | null;
-            startTimestamp: number;
-            endTimestamp: number;
-            createdAt: string;
-            parentCampaignId?: string | undefined;
-            rootCampaignId?: string | undefined;
-            pauseCompute?: string | undefined;
-            pausePrecompute?: string | undefined;
-        })[];
+        };
+        Campaigns: import("../campaign/campaign.formatter").LeanCampaign[];
     }[]>;
+    /**
+     * Reconciles pending amounts not yet reflected in the MV and aggregates them per
+     * `(opportunity, token)` for a recipient.
+     *
+     * Formula (per (chain, token, campaignId, reason)):
+     *   pending = max(0, tempLeaf.amount − (breakdown.amount + Σ liveDiff.amount))
+     *
+     * - `tempLeaf.amount`   = cumulative engine-computed total, not yet merged into any on-chain root
+     * - `breakdown.amount`  = cumulative settled amount in the MV for that composite key
+     * - `liveDiff.amount`   = sum of unmerged `DiffBreakdown` rows tied to the live root (already
+     *                         visible in the live tree but not yet folded into the breakdown row);
+     *                         subtracted so amounts already counted as claimable in the MV are not
+     *                         double-counted as pending
+     *
+     * Attribution is parent-only — each temp leaf is credited to the opportunity its parent
+     * `Campaign` maps to via `oppByCampaignKey`. Temp leaves whose campaign is not in the map are
+     * dropped (no surfaced opportunity to attribute them to).
+     *
+     * Shared by `UserService.getActiveOpportunities` (cross-chain) and `UserService.getChainBreakdown`
+     * (single-chain) — both rely on the same MV-aligned attribution rule.
+     *
+     * @param recipient
+     * @param chainIds  chains the live-roots map is filtered to
+     * @param roots     full roots map; only chains with a `live` root contribute liveDiff offsets
+     * @param tempLeaves pre-fetched temp leaves (caller usually needs them for token seed too)
+     * @param oppByCampaignKey  `${chainId}-${campaignId}` → opportunityId; defines attribution
+     * @returns Map<opportunityId, Map<`${chainId}-${tokenAddress}`, { chainId, tokenAddress, amount }>>
+     */
+    static computePendingByOpportunity(recipient: string, chainIds: number[], roots: RootsByChain, tempLeaves: TempLeaf[], oppByCampaignKey: Map<string, string>): Promise<Map<string, Map<string, {
+        chainId: number;
+        tokenAddress: string;
+        amount: bigint;
+    }>>>;
     private static fetchData;
     /** Extracts unique campaign and token keys from temp leaves for batch prefetch. */
     private static extractTempLeafKeys;
@@ -1030,3 +599,4 @@ export declare abstract class LeafService {
         amount: string;
     }, roots: string[]): Promise<void>;
 }
+export {};