@merkl/api 0.16.14 → 0.16.15

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

@@ -0,0 +1,216 @@
+export declare abstract class ReferralService {
+    #private;
+    static abi: readonly [{
+        readonly name: "getReferralKeys";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly type: "string[]";
+        }];
+    }, {
+        readonly name: "getReferrerStatus";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "address";
+            readonly name: "user";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "bytes32";
+        }];
+    }, {
+        readonly name: "referrerCodeMapping";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "address";
+            readonly name: "user";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "string";
+        }];
+    }, {
+        readonly name: "codeToReferrer";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "string";
+            readonly name: "user";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "address";
+        }];
+    }, {
+        readonly name: "getReferrer";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "address";
+            readonly name: "user";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "address";
+        }];
+    }, {
+        readonly name: "getReferredUsers";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "address";
+            readonly name: "user";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "address[]";
+        }];
+    }, {
+        readonly name: "acknowledgeReferrerByKey";
+        readonly type: "function";
+        readonly stateMutability: "nonpayable";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "string";
+            readonly name: "referrerCode";
+        }];
+        readonly outputs: readonly [];
+    }, {
+        readonly name: "getCostOfReferral";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "getPaymentToken";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "address";
+        }];
+    }, {
+        readonly name: "getReferrerStatusByKey";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "address";
+            readonly name: "referrer";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "uint8";
+        }];
+    }, {
+        readonly name: "requiresAuthorization";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "bool";
+        }];
+    }, {
+        readonly name: "requiresRefererToBeSet";
+        readonly type: "function";
+        readonly stateMutability: "view";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }];
+        readonly outputs: readonly [{
+            readonly type: "bool";
+        }];
+    }, {
+        readonly name: "becomeReferrer";
+        readonly type: "function";
+        readonly stateMutability: "payable";
+        readonly inputs: readonly [{
+            readonly type: "string";
+            readonly name: "key";
+        }, {
+            readonly type: "string";
+            readonly name: "referrerCode";
+        }];
+        readonly outputs: readonly [];
+    }];
+    static getReferralContract(chainId: number): "0xF39CC381B91f36238c77f42B9fF4D45376F80E5b" | undefined;
+    static isKeyAvailable(key: string, chainId: number): Promise<any>;
+    static getReferredUsers(chainId: number, key: string, address: string): Promise<any>;
+    static getReferralStatus(chainId: number, key: string, address: string): Promise<boolean>;
+    static generateCode(chainId: number, key: string, address: string): string;
+    static getCode(chainId: number, key: string, address: string): Promise<any>;
+    /**
+     * Get state & transaction for creating a referral code
+     * @param chainId of the referral contract
+     * @param key of referral
+     * @param address of the creator
+     */
+    static getCodeOrTransaction(chainId: number, key: string, address: string): Promise<{
+        code: string;
+        referrer: boolean;
+        referredUsers: never[];
+        transaction: {
+            to: string;
+            data: `0x${string}`;
+        };
+    } | {
+        code: any;
+        referrer: boolean;
+        referredUsers: any;
+        transaction?: undefined;
+    }>;
+    /**
+     * 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 isCodeRegistered(chainId: number, key: string, code: string): Promise<any>;
+    /**
+     * Get state & transaction for redeeming a referral code
+     * @param chainId of the referral contract
+     * @param key of referral
+     * @param code user referral code
+     */
+    static getReferralTransaction(chainId: number, key: string, code: string): Promise<{
+        code: string;
+        referrer: any;
+        transaction?: undefined;
+    } | {
+        code: string;
+        referrer: any;
+        transaction: {
+            to: string;
+            data: `0x${string}`;
+        };
+    }>;
+}

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

@@ -0,0 +1,170 @@
+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) {
+        return Bun.hash([chainId, key, address].join("-")).toString().slice(0, 12);
+    }
+    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/router.d.ts

@@ -3789,6 +3789,68 @@ export declare const v4: Elysia<"/v4", false, {
             };
         };
     };
+} & {
+    v4: {
+        referral: {
+            code: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        chainId: number;
+                        address: string;
+                        referralKey: string;
+                    };
+                    headers: unknown;
+                    response: {
+                        200: {
+                            code: string;
+                            referrer: boolean;
+                            referredUsers: never[];
+                            transaction: {
+                                to: string;
+                                data: `0x${string}`;
+                            };
+                        } | {
+                            code: any;
+                            referrer: boolean;
+                            referredUsers: any;
+                            transaction?: undefined;
+                        };
+                    };
+                };
+            };
+        };
+    } & {
+        referral: {
+            redeem: {
+                get: {
+                    body: unknown;
+                    params: {};
+                    query: {
+                        code: string;
+                        chainId: number;
+                        referralKey: string;
+                    };
+                    headers: unknown;
+                    response: {
+                        200: {
+                            code: string;
+                            referrer: any;
+                            transaction?: undefined;
+                        } | {
+                            code: string;
+                            referrer: any;
+                            transaction: {
+                                to: string;
+                                data: `0x${string}`;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
 }, {
     derive: {};
     resolve: {};

package/dist/src/modules/v4/router.js

@@ -27,6 +27,7 @@ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
 import { PrismaInstrumentation } from "@prisma/instrumentation";
 import Elysia from "elysia";
+import { ReferralController } from "./referral/referral.controller";
 // ─── V4 Router ───────────────────────────────────────────────────────────────
 export const v4 = new Elysia({ tags: ["v4"], prefix: "/v4" })
     // ─── OpenTelemetry ───────────────────────────────────────────────────
@@ -71,4 +72,5 @@ export const v4 = new Elysia({ tags: ["v4"], prefix: "/v4" })
     .use(ProgramPayloadController)
     .use(BoostController)
     .use(ComputedValueController)
-    .use(CreatorController);
+    .use(CreatorController)
+    .use(ReferralController);