@merkl/api 1.19.27 → 1.20.0

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

@@ -394,6 +394,615 @@ 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`.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * Staleness: `amount` / `claimed` reflect the MV refresh cadence (≤ 30 min). Acceptable for the
+     * rewards-summary surface (display-only); not safe for transactional reads.
+     *
+     * 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`.
+     */
+    static getBreakdownsByOpportunity(recipient: string, distributionChainIds: number[]): Promise<{
+        distributionChainId: number;
+        opportunityId: string;
+        tokenAddress: string;
+        amount: string;
+        claimed: string;
+        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;
+            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;
+                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;
+        } | ({
+            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;
+        })[];
+    }[]>;
     private static fetchData;
     /** Extracts unique campaign and token keys from temp leaves for batch prefetch. */
     private static extractTempLeafKeys;