@merkl/api 0.9.15

package/dist/src/modules/v4/referral/referral.service.js

@@ -0,0 +1,171 @@
+import { ChainId, ChainInteractionService } from "@sdk";
+import { decodeFunctionResult, encodeFunctionData, parseAbi, } from "viem";
+export class ReferralService {
+    static abi = parseAbi([
+        "function getReferralKeys() external view returns (string[] memory)",
+        "function getReferrerStatus(string calldata key, address user) external view returns (bytes32)",
+        "function referrerCodeMapping(string key, address user) external view returns (string)",
+        "function codeToReferrer(string key, string user) external view returns (address)",
+        "function getReferrer(string calldata key, address user) external view returns (address)",
+        "function getReferredUsers(string calldata key, address user) external view returns (address[] memory)",
+        "function acknowledgeReferrerByKey(string calldata key, string calldata referrerCode) external",
+        "function getCostOfReferral(string calldata key) external view returns (uint256)",
+        "function getPaymentToken(string calldata key) external view returns (address)",
+        "function getReferrerStatusByKey(string calldata key, address referrer) external view returns (uint8)",
+        "function requiresAuthorization(string calldata key) external view returns (bool)",
+        "function requiresRefererToBeSet(string calldata key) external view returns (bool)",
+        "function becomeReferrer(string calldata key, string calldata referrerCode) external payable",
+    ]);
+    static getReferralContract(chainId) {
+        if (chainId === ChainId.ETHERLINK)
+            return "0xF39CC381B91f36238c77f42B9fF4D45376F80E5b";
+        return;
+    }
+    /**
+     * Makes an on-chain call to the referral contract
+     * @param chainId
+     * @param functionName
+     * @param args
+     * @returns
+     */
+    static async #call(chainId, functionName, args) {
+        const referralContractAddress = ReferralService.getReferralContract(chainId);
+        if (!referralContractAddress)
+            throw new Error(`Referral contract not deployed on chain ${chainId}`);
+        return await ChainInteractionService(chainId).fetchAndDecode({
+            target: referralContractAddress,
+            allowFailure: true,
+            callData: encodeFunctionData({
+                abi: ReferralService.abi,
+                functionName,
+                args,
+            }),
+        }, (r) => decodeFunctionResult({
+            abi: ReferralService.abi,
+            functionName,
+            data: r?.returnData,
+        }));
+    }
+    static async isKeyAvailable(key, chainId) {
+        const referralKeys = await ReferralService.#call(chainId, "getReferralKeys", []);
+        return referralKeys.includes(key);
+    }
+    static async getReferredUsers(chainId, key, address) {
+        const isReferralKeyAvailable = ReferralService.isKeyAvailable(key, chainId);
+        if (!isReferralKeyAvailable)
+            throw new Error(`Referral key ${key} not available on ${chainId}`);
+        return await ReferralService.#call(chainId, "getReferredUsers", [key, address]);
+    }
+    static async getReferralStatus(chainId, key, address) {
+        const referralContractAddress = ReferralService.getReferralContract(chainId);
+        const isReferralKeyAvailable = ReferralService.isKeyAvailable(key, chainId);
+        if (!referralContractAddress)
+            throw new Error(`Referral contract not deployed on chain ${chainId}`);
+        if (!isReferralKeyAvailable)
+            throw new Error(`Referral key ${key} not available on ${chainId}`);
+        const shouldCheckStatus = await ReferralService.#call(chainId, "requiresAuthorization", [key]);
+        if (!shouldCheckStatus)
+            return true;
+        const referralStatus = await ReferralService.#call(chainId, "getReferrerStatusByKey", [
+            key,
+            address,
+        ]);
+        return referralStatus === 1;
+    }
+    static generateCode(chainId, key, address) {
+        const digits = [chainId, key, address, 4, 5, 6].map(() => Math.floor(Math.random() * 10)).join("");
+        return `${key.toUpperCase()}-${digits}`;
+    }
+    static async getCode(chainId, key, address) {
+        const referralContractAddress = ReferralService.getReferralContract(chainId);
+        if (!referralContractAddress)
+            throw new Error(`Referral contract not deployed on chain ${chainId}`);
+        const code = await ReferralService.#call(chainId, "referrerCodeMapping", [key, address]);
+        return code === "" ? undefined : code;
+    }
+    /**
+     * Get state & transaction for creating a referral code
+     * @param chainId of the referral contract
+     * @param key of referral
+     * @param address of the creator
+     */
+    static async getCodeOrTransaction(chainId, key, address) {
+        const referralContractAddress = ReferralService.getReferralContract(chainId);
+        const isReferralKeyAvailable = ReferralService.isKeyAvailable(key, chainId);
+        if (!referralContractAddress)
+            throw new Error(`Referral contract not deployed on chain ${chainId}`);
+        if (!isReferralKeyAvailable)
+            throw new Error(`Referral key ${key} not available on ${chainId}`);
+        const contractCode = await ReferralService.getCode(chainId, key, address);
+        if (!contractCode) {
+            const code = ReferralService.generateCode(chainId, key, address);
+            return {
+                code,
+                referrer: false,
+                referredUsers: [],
+                transaction: {
+                    to: referralContractAddress,
+                    data: encodeFunctionData({
+                        abi: ReferralService.abi,
+                        functionName: "becomeReferrer",
+                        args: [key, code],
+                    }),
+                },
+            };
+        }
+        const code = await ReferralService.getCode(chainId, key, address);
+        const referredUsers = await ReferralService.getReferredUsers(chainId, key, address);
+        return {
+            code,
+            referrer: true,
+            referredUsers,
+        };
+    }
+    /**
+     * Checks if code exists in the contracts
+     * @param chainId of the referral contract
+     * @param key of referral
+     * @param code user referral code
+     * @returns referrerAddress if code exitst
+     */
+    static async isCodeRegistered(chainId, key, code) {
+        const referralContractAddress = ReferralService.getReferralContract(chainId);
+        if (!referralContractAddress)
+            throw new Error(`Referral contract not deployed on chain ${chainId}`);
+        const referrerAddress = await ReferralService.#call(chainId, "codeToReferrer", [key, code]);
+        return referrerAddress === "" ? undefined : referrerAddress;
+    }
+    /**
+     * Get state & transaction for redeeming a referral code
+     * @param chainId of the referral contract
+     * @param key of referral
+     * @param code user referral code
+     */
+    static async getReferralTransaction(chainId, key, code) {
+        const referralContractAddress = ReferralService.getReferralContract(chainId);
+        const isReferralKeyAvailable = ReferralService.isKeyAvailable(key, chainId);
+        if (!referralContractAddress)
+            throw new Error(`Referral contract not deployed on chain ${chainId}`);
+        if (!isReferralKeyAvailable)
+            throw new Error(`Referral key ${key} not available on ${chainId}`);
+        const referrerAddress = await ReferralService.isCodeRegistered(chainId, key, code);
+        if (!referrerAddress) {
+            return {
+                code,
+                referrer: referrerAddress,
+            };
+        }
+        return {
+            code,
+            referrer: referrerAddress,
+            transaction: {
+                to: referralContractAddress,
+                data: encodeFunctionData({
+                    abi: ReferralService.abi,
+                    functionName: "acknowledgeReferrerByKey",
+                    args: [key, code],
+                }),
+            },
+        };
+    }
+}

package/dist/src/modules/v4/reward/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@/modules/v4/reward/reward.service";
+export * from "@/modules/v4/reward/reward.model";

package/dist/src/modules/v4/reward/index.js

@@ -0,0 +1,2 @@
+export * from "@/modules/v4/reward/reward.service";
+export * from "@/modules/v4/reward/reward.model";

package/dist/src/modules/v4/reward/reward.controller.d.ts

@@ -0,0 +1,338 @@
+import Elysia from "elysia";
+export declare const RewardController: Elysia<"/rewards", false, {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    type: {};
+    error: {};
+}, {
+    schema: {};
+    macro: {};
+    macroFn: {};
+}, {
+    rewards: {
+        index: {
+            get: {
+                body: unknown;
+                params: {};
+                query: {
+                    items?: number | undefined;
+                    page?: number | undefined;
+                    campaignId: string;
+                    chainId: number;
+                };
+                headers: unknown;
+                response: {
+                    200: import("./reward.model").BreakdownForCampaignsRaw[];
+                };
+            };
+        };
+    } & {
+        total: {
+            get: {
+                body: unknown;
+                params: {};
+                query: {
+                    items?: number | undefined;
+                    page?: number | undefined;
+                    campaignId: string;
+                    chainId: number;
+                };
+                headers: unknown;
+                response: {
+                    200: {
+                        campaignId: string;
+                        amount: bigint;
+                    };
+                };
+            };
+        };
+    } & {
+        count: {
+            get: {
+                body: unknown;
+                params: {};
+                query: {
+                    items?: number | undefined;
+                    page?: number | undefined;
+                    campaignId: string;
+                    chainId: number;
+                };
+                headers: unknown;
+                response: {
+                    200: {
+                        count: number;
+                    };
+                };
+            };
+        };
+    } & {
+        campaign: {
+            ":campaignId": {
+                index: {
+                    get: {
+                        body: unknown;
+                        params: {};
+                        query: {
+                            items?: number | undefined;
+                            page?: number | undefined;
+                        };
+                        headers: unknown;
+                        response: {
+                            200: {
+                                amount: string;
+                                claimed: string;
+                                pending: string;
+                                recipient: string;
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        campaign: {
+            ":campaignId": {
+                total: {
+                    get: {
+                        body: unknown;
+                        params: {};
+                        query: {
+                            items?: number | undefined;
+                            page?: number | undefined;
+                        };
+                        headers: unknown;
+                        response: {
+                            200: {
+                                tokenId: string;
+                                amount: bigint;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        campaign: {
+            ":campaignId": {
+                count: {
+                    get: {
+                        body: unknown;
+                        params: {};
+                        query: {
+                            items?: number | undefined;
+                            page?: number | undefined;
+                        };
+                        headers: unknown;
+                        response: {
+                            200: {
+                                count: number;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        token: {
+            index: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        items?: number | undefined;
+                        page?: number | undefined;
+                        campaignIds?: string[] | undefined;
+                        address: string;
+                        chainId: number;
+                    };
+                    headers: unknown;
+                    response: {
+                        200: {
+                            amount: string;
+                            claimed: string;
+                            pending: string;
+                            recipient: string;
+                        }[];
+                    };
+                };
+            };
+        };
+    } & {
+        token: {
+            total: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        items?: number | undefined;
+                        page?: number | undefined;
+                        campaignIds?: string[] | undefined;
+                        address: string;
+                        chainId: number;
+                    };
+                    headers: unknown;
+                    response: {
+                        200: {
+                            tokenId: string;
+                            amount: bigint;
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        token: {
+            count: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        items?: number | undefined;
+                        page?: number | undefined;
+                        campaignIds?: string[] | undefined;
+                        address: string;
+                        chainId: number;
+                    };
+                    headers: unknown;
+                    response: {
+                        200: {
+                            count: number;
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        engine: {
+            index: {
+                post: {
+                    body: {
+                        pending: string;
+                        distributionChainId: number;
+                        amount: string;
+                        root: string;
+                        recipient: string;
+                        claimed: string;
+                        proofs: string[];
+                        rewardToken: string;
+                    }[];
+                    params: {};
+                    query: unknown;
+                    headers: {
+                        authorization: string;
+                    };
+                    response: {
+                        200: {
+                            count: number;
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        engine: {
+            breakdowns: {
+                post: {
+                    body: {
+                        distributionChainId: number;
+                        campaignId: string;
+                        root: string;
+                        rewardToken: string;
+                        breakdowns: {
+                            protocolId?: string | undefined;
+                            pending: string;
+                            reason: string;
+                            amount: string;
+                            recipient: string;
+                            claimed: string;
+                        }[];
+                    }[];
+                    params: {};
+                    query: unknown;
+                    headers: {
+                        authorization: string;
+                    };
+                    response: {
+                        200: {
+                            count: number;
+                        } | undefined;
+                    };
+                };
+            };
+        };
+    } & {
+        engine: {
+            claims: {
+                post: {
+                    body: {
+                        token: string;
+                        chainId: number;
+                        root: string;
+                        recipient: string;
+                    }[];
+                    params: {};
+                    query: unknown;
+                    headers: {
+                        authorization: string;
+                    };
+                    response: {
+                        200: void;
+                    };
+                };
+            };
+        };
+    } & {
+        count: {
+            chain: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        chainId: number;
+                    };
+                    headers: {
+                        authorization: string;
+                    };
+                    response: {
+                        200: {
+                            [x: number]: {
+                                rewardCount: number;
+                                breakdownCount: number;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        unclaim: {
+            index: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        chainId: number;
+                        campaignIds: string[];
+                    };
+                    headers: unknown;
+                    response: {
+                        200: {
+                            [x: string]: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+}>;

package/dist/src/modules/v4/reward/reward.controller.js

@@ -0,0 +1,124 @@
+import { BackOfficeGuard } from "@/guards/BackOffice.guard";
+import { AuthorizationHeadersDto, EngineGuard } from "@/guards/Engine.guard";
+import { ChainDto } from "@/modules/v4/accounting/accounting.model";
+import { CampaignService } from "@/modules/v4/campaign/campaign.service";
+import { TokenService } from "@/modules/v4/token/token.service";
+import { throwOnInvalidRequiredAddress, throwOnUnsupportedChainId } from "@/utils/throw";
+import Elysia from "elysia";
+import { CampaignIdDto, CampaignIdWithoutPageDto, CampaignRewardsDto, CreateManyBreakdownDto, CreateManyRewardDto, RegisterClaimsDto, TokenIdDto, } from "./reward.model";
+import { RewardService } from "./reward.service";
+// ─── Rewards Controller ──────────────────────────────────────────────────────
+export const RewardController = new Elysia({ prefix: "/rewards", detail: { tags: ["Rewards"] } })
+    // ─── Get Reward Breakdowns For Campaign Ids ──────────────────────────
+    .get("/", async ({ query }) => await RewardService.breakdownForCampaign(query), {
+    query: CampaignIdDto,
+    beforeHandle: ({ query }) => {
+        throwOnUnsupportedChainId(query.chainId);
+    },
+    detail: {
+        description: "Returns the all the address that received rewards for a given campaign, sorted by descending amounts",
+    },
+})
+    // ─── Get Total Amount Rewarded For Campaign Id ──────────────────────
+    .get("/total", async ({ query }) => await RewardService.totalForCampaign(query), {
+    query: CampaignIdDto,
+    beforeHandle: ({ query }) => {
+        throwOnUnsupportedChainId(query.chainId);
+    },
+    detail: { description: "Returns the total amount distributed for a given campaign" },
+})
+    // ─── Get Reward Count By Chain And Root For Campaign Id ─────────────
+    .get("/count", async ({ query }) => await RewardService.countForCampaign(query), {
+    query: CampaignIdDto,
+    beforeHandle: ({ query }) => {
+        throwOnUnsupportedChainId(query.chainId);
+    },
+    detail: { hide: true },
+})
+    // ─── Get Reward by campaign ─────────────
+    .group("/campaign/:campaignId", app => {
+    return app
+        .resolve(async ({ params: { campaignId } }) => {
+        const campaign = await CampaignService.findUniqueOrThrow(CampaignService.splitIdOrThrow(campaignId));
+        const token = await TokenService.findUniqueOrThrow(campaign.rewardTokenId);
+        const rewardQuery = {
+            chainId: token.chainId,
+            address: token.address,
+            campaignIds: [campaign.campaignId],
+        };
+        return { campaign, token, rewardQuery };
+    })
+        .guard({
+        query: CampaignRewardsDto,
+        detail: { hide: true },
+    })
+        .get("/", async ({ query, rewardQuery }) => await RewardService.breakdownForToken({ ...query, ...rewardQuery }))
+        .get("/total", async ({ query, rewardQuery }) => await RewardService.totalForToken({ ...query, ...rewardQuery }))
+        .get("/count", async ({ query, rewardQuery }) => await RewardService.countForToken({ ...query, ...rewardQuery }));
+})
+    // ─── Get Reward Breakdowns For Token ───────────────────────────────
+    .group("/token", app => {
+    return app
+        .guard({
+        query: TokenIdDto,
+        beforeHandle: ({ query }) => {
+            query.address = throwOnInvalidRequiredAddress(query.address);
+            throwOnUnsupportedChainId(query.chainId);
+        },
+        detail: { hide: true },
+    })
+        .get("/", async ({ query }) => await RewardService.breakdownForToken(query))
+        .get("/total", async ({ query }) => await RewardService.totalForToken(query))
+        .get("/count", async ({ query }) => await RewardService.countForToken(query));
+})
+    .group("/engine", app => {
+    return (app
+        // ─── Create Many Rewards ─────────────────────────────────────────────
+        .post("/", async ({ body }) => await RewardService.createManyReward(body), {
+        headers: AuthorizationHeadersDto,
+        body: CreateManyRewardDto,
+        beforeHandle: EngineGuard,
+        detail: { hide: true },
+    })
+        // ─── Create Many Reward Breakdowns ───────────────────────────────────
+        .post("/breakdowns", async ({ body }) => await RewardService.createManyBreakdown(body), {
+        headers: AuthorizationHeadersDto,
+        body: CreateManyBreakdownDto,
+        beforeHandle: EngineGuard,
+        detail: { hide: true },
+    })
+        // ─── Register new claims ──────────────────────────────────────────────
+        .post("/claims", async ({ body }) => await RewardService.registerClaims(body), {
+        headers: AuthorizationHeadersDto,
+        body: RegisterClaimsDto,
+        beforeHandle: ({ headers, body }) => {
+            EngineGuard({ headers });
+            for (const claim of body) {
+                throwOnUnsupportedChainId(claim.chainId);
+                claim.token = throwOnInvalidRequiredAddress(claim.token);
+                claim.recipient = throwOnInvalidRequiredAddress(claim.recipient);
+            }
+        },
+        detail: { hide: true },
+    }));
+})
+    // ─── Get Reward Count By Chain And Root ──────────────────────────────
+    .get("/count/chain", async ({ query }) => await RewardService.countOnChain(query.chainId), {
+    query: ChainDto,
+    headers: AuthorizationHeadersDto,
+    beforeHandle: ({ headers, query }) => {
+        BackOfficeGuard({ headers });
+        throwOnUnsupportedChainId(query.chainId);
+    },
+    detail: { hide: true },
+})
+    // ─── Unclaimed Data routes ───────────────────────────────────────────
+    .group("/unclaim", app => {
+    return app.get("/", async ({ query }) => await RewardService.getUnclaimed(query), {
+        query: CampaignIdWithoutPageDto,
+        beforeHandle: ({ query }) => {
+            throwOnUnsupportedChainId(query.chainId);
+        },
+        detail: { description: "Returns the total of unclaimed rewards for given campaigns" },
+    });
+});

package/dist/src/modules/v4/reward/reward.converter.d.ts

@@ -0,0 +1,14 @@
+import type { MerklAPIType, MerklChainId } from "@sdk";
+import type { RewardV3Model, UserRewardV3Model } from "./reward.model";
+import { RewardService } from "./reward.service";
+export declare class RewardConvertorService {
+    /**
+     * Convert the v4 reward data to the v3 model used in the v3/userRewards route
+     */
+    static convertV4toUserRewardV3(data: Awaited<ReturnType<(typeof RewardService)["getUserRewardsByChain"]>>, includeProofs?: boolean): UserRewardV3Model;
+    /**
+     * Convert the v4 reward data to the v3 model used in the v3/rewards route
+     */
+    static convertV4toRewardV3(data: Awaited<ReturnType<(typeof RewardService)["getUserRewardsByChain"]>>): RewardV3Model;
+    static convertV4toMerklV2(user: string, chainId: MerklChainId, data: MerklAPIType[number]): Promise<MerklAPIType[number]>;
+}