@merkl/api 0.9.15

package/dist/src/modules/v4/chain/chain.repository.js

@@ -0,0 +1,70 @@
+import { apiDbClient } from "@db";
+import { ExplorerRepository } from "../explorer/explorer.repository";
+export class ChainRepository {
+    /**
+     * @param id ChainId
+     * @returns
+     */
+    static async read(id) {
+        //TODO: tweak query to not have 5
+        return await apiDbClient.chain.findUnique({ where: { id }, include: { Explorer: { take: 5 } } });
+    }
+    static transformQueryToPrismaFilters(query) {
+        return {
+            where: { name: query.name ? { contains: query.name, mode: "insensitive" } : undefined },
+        };
+    }
+    /** Returns many chains based on query
+     * @param query object with fields to search for
+     * @returns
+     */
+    static async findMany(query) {
+        const args = ChainRepository.transformQueryToPrismaFilters(query);
+        return apiDbClient.chain.findMany({
+            include: { Explorer: { take: 5 } },
+            ...args,
+        });
+    }
+    static async countMany(query) {
+        const args = ChainRepository.transformQueryToPrismaFilters(query);
+        return apiDbClient.chain.count({
+            ...args,
+        });
+    }
+    /** Returns all chainIds in the database
+     */
+    static async readIds() {
+        return apiDbClient.chain.findMany({
+            select: { id: true },
+        });
+    }
+    /**
+     * Creates a new chain
+     * @param template for chain creation
+     * @returns
+     */
+    static async create(data) {
+        await apiDbClient.chain.create({
+            data: {
+                id: data.id,
+                icon: data.icon,
+                name: data.name,
+            },
+        });
+        await ExplorerRepository.create(data.id, data.explorerType, data.explorerUrl);
+        return await ChainRepository.findUniqueOrThrow(data.id);
+    }
+    static async findUniqueOrThrow(id) {
+        return await apiDbClient.chain.findUniqueOrThrow({
+            where: {
+                id,
+            },
+            select: {
+                Explorer: true,
+            },
+        });
+    }
+    static async update(id, data) {
+        return await apiDbClient.chain.update({ where: { id }, data });
+    }
+}

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

@@ -0,0 +1,55 @@
+import type { ChainSearchDto, CreateChainModel, UpdateChainModel } from "./chain.model";
+export declare abstract class ChainService {
+    static get(chainId: number): Promise<({
+        Explorer: {
+            id: string;
+            type: import("@db/api").$Enums.ExplorerType;
+            url: string;
+            chainId: number;
+        }[];
+    } & {
+        id: number;
+        name: string;
+        icon: string;
+    }) | null>;
+    static findMany(query: ChainSearchDto): Promise<({
+        Explorer: {
+            id: string;
+            type: import("@db/api").$Enums.ExplorerType;
+            url: string;
+            chainId: number;
+        }[];
+    } & {
+        id: number;
+        name: string;
+        icon: string;
+    })[]>;
+    static countMany(query: ChainSearchDto): Promise<number>;
+    /** List all chainIds available in the databse
+     * @warning some chains may not be fully integrated yet
+     * @returns an array of chainId
+     */
+    static getIds(): Promise<number[]>;
+    /** List all chainIds which have a distribituor (i.e. which is fully integrated)
+     * @returns an array of chainId
+     */
+    static getSupportedIds(): Promise<number[]>;
+    static create(chain: CreateChainModel): Promise<{
+        Explorer: {
+            id: string;
+            type: import("@db/api").$Enums.ExplorerType;
+            url: string;
+            chainId: number;
+        }[];
+    }>;
+    static update(id: number, data: UpdateChainModel): Promise<{
+        id: number;
+        name: string;
+        icon: string;
+    }>;
+    static updateDailyRewards(id: number, dailyRewards: number): Promise<{
+        id: number;
+        name: string;
+        icon: string;
+    }>;
+}

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

@@ -0,0 +1,48 @@
+import { DistributorService } from "@sdk";
+import { CacheService } from "../cache";
+import { TTLPresets } from "../cache/cache.model";
+import { ChainRepository } from "./chain.repository";
+export class ChainService {
+    static async get(chainId) {
+        return ChainRepository.read(chainId);
+    }
+    //TODO: determine find vs get nomenclature and cache handling
+    static async findMany(query) {
+        return await CacheService.wrap(TTLPresets.HOUR_4, ChainRepository.findMany, query);
+    }
+    static async countMany(query) {
+        return await ChainRepository.countMany(query);
+    }
+    /** List all chainIds available in the databse
+     * @warning some chains may not be fully integrated yet
+     * @returns an array of chainId
+     */
+    static async getIds() {
+        const ids = await ChainRepository.readIds();
+        return ids.map(({ id }) => id);
+    }
+    /** List all chainIds which have a distribituor (i.e. which is fully integrated)
+     * @returns an array of chainId
+     */
+    static async getSupportedIds() {
+        const ids = await ChainService.getIds();
+        const supportedIds = [];
+        for (const chainId of ids) {
+            try {
+                DistributorService(chainId);
+                supportedIds.push(chainId);
+            }
+            catch { }
+        }
+        return supportedIds;
+    }
+    static async create(chain) {
+        return await ChainRepository.create(chain);
+    }
+    static async update(id, data) {
+        return await ChainRepository.update(id, data);
+    }
+    static async updateDailyRewards(id, dailyRewards) {
+        return await ChainRepository.update(id, { dailyRewards });
+    }
+}

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

@@ -0,0 +1,2 @@
+declare const ChainInteractionServiceWrapper: any;
+export { ChainInteractionServiceWrapper as ChainInteractionService };

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

@@ -0,0 +1,4 @@
+import { ChainInteractionService } from "@sdk";
+import { TracerService } from "../tracer";
+const ChainInteractionServiceWrapper = TracerService.createTracedProxy(ChainInteractionService, "ChainInteractionService");
+export { ChainInteractionServiceWrapper as ChainInteractionService };

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

@@ -0,0 +1,42 @@
+import Elysia from "elysia";
+export declare const ClaimController: Elysia<"/claims", false, {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    type: {};
+    error: {};
+}, {
+    schema: {};
+    macro: {};
+    macroFn: {};
+}, {
+    claims: {
+        ":address": {
+            get: {
+                body: unknown;
+                params: {
+                    address: string;
+                };
+                query: {
+                    chainIds?: number[] | undefined;
+                };
+                headers: unknown;
+                response: {
+                    200: (import("./claims.model").ClaimModel & {
+                        token?: import("../token/token.model").Token["model"];
+                    })[];
+                };
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+}>;

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

@@ -0,0 +1,18 @@
+import { throwOnInvalidRequiredAddress, throwOnUnsupportedChainId } from "@/utils/throw";
+import Elysia from "elysia";
+import { ChainArrayOptionalDto } from "../chain/chain.model";
+import { UserUniqueDto } from "../user/user.model";
+import { ClaimService } from "./claims.service";
+// ─── Claim Controller ───────────────────────────────────────────────────────
+export const ClaimController = new Elysia({ prefix: "/claims", detail: { tags: ["Claims"] } })
+    // ─── Get Historical Claims ────────────────────────────────────────────
+    .get("/:address", async ({ params, query }) => await ClaimService.getHistoricalClaims(params, query.chainIds), {
+    params: UserUniqueDto,
+    query: ChainArrayOptionalDto,
+    beforeHandle: ({ params, query }) => {
+        params.address = throwOnInvalidRequiredAddress(params.address);
+        for (const chainId of query?.chainIds ?? []) {
+            throwOnUnsupportedChainId(chainId);
+        }
+    },
+});

package/dist/src/modules/v4/claims/claims.model.d.ts

@@ -0,0 +1,9 @@
+export type ClaimModel = {
+    timestamp: number;
+    token: string;
+    user: string;
+    amount: string;
+    rawAmount: string;
+    root: string;
+    txHash?: string;
+};

package/dist/src/modules/v4/claims/claims.model.js

@@ -0,0 +1 @@
+export {};

package/dist/src/modules/v4/claims/claims.repository.d.ts

@@ -0,0 +1,5 @@
+import { type MerklChainId } from "@sdk";
+import type { ClaimModel } from "./claims.model";
+export declare class ClaimRepository {
+    static fetch(chainId: MerklChainId, address: string): Promise<ClaimModel[]>;
+}

package/dist/src/modules/v4/claims/claims.repository.js

@@ -0,0 +1,39 @@
+import { merklSubgraphClaimsEndpoints } from "@sdk";
+import request, { gql } from "graphql-request";
+export class ClaimRepository {
+    static async fetch(chainId, address) {
+        try {
+            return (await request(merklSubgraphClaimsEndpoints[chainId], 
+            // Request is limited to first 100 by default so needs to be sorted
+            gql `query MerklClaims($user: String) {
+              merklClaims(where: {user: $user }, orderBy: timestamp, orderDirection: desc) {
+                timestamp
+                token
+                user
+                amount
+                rawAmount
+                root
+                id
+                txHash
+              }
+            }
+    `, { user: address?.toLowerCase() })).merklClaims;
+        }
+        catch {
+            return (await request(merklSubgraphClaimsEndpoints[chainId], 
+            // Request is limited to first 100 by default so needs to be sorted
+            gql `query MerklClaims($user: String) {
+                merklClaims(where: {user: $user }, orderBy: timestamp, orderDirection: desc) {
+                  timestamp
+                  token
+                  user
+                  amount
+                  rawAmount
+                  root
+                  id
+                }
+              }
+      `, { user: address?.toLowerCase() })).merklClaims;
+        }
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { ChainId } from "@sdk";
+import type { Token } from "../token/token.model";
+import type { UserUniqueModel } from "../user/user.model";
+import type { ClaimModel } from "./claims.model";
+export declare abstract class ClaimService {
+    static getHistoricalClaims(params: UserUniqueModel, chainFilter?: ChainId[]): Promise<(ClaimModel & {
+        token?: Token["model"];
+    })[]>;
+}

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

@@ -0,0 +1,40 @@
+import { MerklRootService } from "../merklRoot";
+import { RewardService } from "../reward";
+import { ClaimRepository } from "./claims.repository";
+export class ClaimService {
+    // ─── Get Historical Claims ─────────────────────────────────────────────────
+    static async getHistoricalClaims(params, chainFilter = []) {
+        const roots = Object.values(await MerklRootService.fetchAll()).map(r => r.live);
+        const rewards = await RewardService.getByRecipient(params.address, roots, true, true, chainFilter);
+        const filteredRewards = chainFilter.length
+            ? rewards.filter(reward => chainFilter.includes(reward.RewardToken.chainId))
+            : rewards;
+        const chainIds = [];
+        for (const reward of filteredRewards) {
+            if (!chainIds.includes(reward.RewardToken.chainId)) {
+                chainIds.push(reward.RewardToken.chainId);
+            }
+        }
+        const tokens = filteredRewards.reduce((acc, reward) => {
+            acc[reward.RewardToken.address.toLowerCase()] = reward.RewardToken;
+            return acc;
+        }, {});
+        const promises = await Promise.allSettled(chainIds.map(chainId => ClaimRepository.fetch(chainId, params.address)));
+        const claims = promises.filter(p => p.status === "fulfilled")
+            .flatMap(p => p.value ?? []) // null/undefined claim arrays
+            .filter(claim => {
+            // Ensure the claim's token exists and matches the chainFilter
+            const token = claim?.token ? tokens[claim.token.toLowerCase()] : undefined;
+            return token && (!chainFilter.length || chainFilter.includes(token.chainId));
+        })
+            .map(claim => {
+            const token = claim?.token ? tokens[claim.token.toLowerCase()] : undefined;
+            return {
+                ...claim,
+                amount: claim.rawAmount,
+                token,
+            };
+        });
+        return claims.sort((a, b) => Number(b.timestamp) - Number(a.timestamp));
+    }
+}

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

@@ -0,0 +1,119 @@
+import Elysia from "elysia";
+export declare const ComputedValueController: Elysia<"/value", false, {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    type: {};
+    error: {};
+}, {
+    schema: {};
+    macro: {};
+    macroFn: {};
+}, {
+    value: {
+        campaign: {
+            ":campaignId": {
+                ":field": {
+                    get: {
+                        body: unknown;
+                        params: {
+                            campaignId: string;
+                            field: string;
+                        };
+                        query: unknown;
+                        headers: unknown;
+                        response: {
+                            200: {
+                                averageBoost: number | null;
+                                totalDistributedInUSD: number | null;
+                                forfeitingBoost: number | null;
+                            } | null;
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    value: {
+        user: {
+            ":address": {
+                ":field": {
+                    get: {
+                        body: unknown;
+                        params: {
+                            address: string;
+                            field: string;
+                        };
+                        query: unknown;
+                        headers: unknown;
+                        response: {
+                            200: {
+                                id: number;
+                                reason: string;
+                                campaignId: string;
+                                boost: number | null;
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+    };
+} & {
+    value: {
+        engine: {
+            campaign: {
+                post: {
+                    body: {
+                        value: number;
+                        campaignId: string;
+                        field: string;
+                    };
+                    params: {};
+                    query: unknown;
+                    headers: {
+                        authorization: string;
+                    };
+                    response: {
+                        200: void;
+                    };
+                };
+            };
+        };
+    };
+} & {
+    value: {
+        engine: {
+            user: {
+                post: {
+                    body: {
+                        reason: string;
+                        value: number;
+                        campaignId: string;
+                        address: string;
+                        field: string;
+                    }[];
+                    params: {};
+                    query: unknown;
+                    headers: {
+                        authorization: string;
+                    };
+                    response: {
+                        200: void;
+                    };
+                };
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+}>;

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

@@ -0,0 +1,45 @@
+import { AuthorizationHeadersDto, EngineGuard } from "@/guards/Engine.guard";
+import { throwOnInvalidRequiredAddress } from "@/utils/throw";
+import Elysia from "elysia";
+import { GetCampaignComputedValue, GetUserComputedValues, UpsertCampaignComputedValue, UpsertUserComputedValues, } from "./computedValue.model";
+import { ComputedValueService } from "./computedValue.service";
+export const ComputedValueController = new Elysia({
+    prefix: "/value",
+    detail: { tags: ["Value"] },
+})
+    // ─── Get a Campaign Value ──────────────────────────────────────
+    .get("/campaign/:campaignId/:field", async ({ params }) => ComputedValueService.findCampaignValue(params), {
+    params: GetCampaignComputedValue,
+    detail: { description: "Gets campaign-level values computed by Merkl Engine (for example average boost)" },
+})
+    // ─── Get user Values ──────────────────────────────────────
+    .get("/user/:address/:field", async ({ params }) => ComputedValueService.findUserValues(params), {
+    params: GetUserComputedValues,
+    beforeHandle: ({ params }) => {
+        params.address = throwOnInvalidRequiredAddress(params.address);
+    },
+    detail: {
+        description: "Gets campaign-level values computed by Merkl Engine (for example position specific boosts)",
+    },
+})
+    // ─── Update a Campaign Value ──────────────────────────────────────
+    .post("/engine/campaign", async ({ body }) => await ComputedValueService.upsertCampaignComputedValue(body), {
+    headers: AuthorizationHeadersDto,
+    body: UpsertCampaignComputedValue,
+    beforeHandle: ({ headers }) => {
+        EngineGuard({ headers });
+    },
+    detail: { hide: true },
+})
+    // ─── Update some User Values ──────────────────────────────────────
+    .post("/engine/user", async ({ body }) => await ComputedValueService.upsertUserComputedValues(body), {
+    headers: AuthorizationHeadersDto,
+    body: UpsertUserComputedValues,
+    beforeHandle: async ({ headers, body }) => {
+        await EngineGuard({ headers });
+        for (const item of body) {
+            item.address = throwOnInvalidRequiredAddress(item.address);
+        }
+    },
+    detail: { hide: true },
+});

package/dist/src/modules/v4/computedValue/computedValue.model.d.ts

@@ -0,0 +1,27 @@
+import type { Resource } from "../prisma";
+export type CampaignComputedFields = keyof Resource<"CampaignComputedValue", "campaignId">["model"];
+export type UserComputedFields = keyof Resource<"UserComputedValue", "campaignId" | "address" | "reason">["model"];
+export declare const GetCampaignComputedValue: import("@sinclair/typebox").TObject<{
+    campaignId: import("@sinclair/typebox").TString;
+    field: import("@sinclair/typebox").TString;
+}>;
+export declare const UpsertCampaignComputedValue: import("@sinclair/typebox").TObject<{
+    campaignId: import("@sinclair/typebox").TString;
+    value: import("@sinclair/typebox").TNumber;
+    field: import("@sinclair/typebox").TString;
+}>;
+export declare const GetUserComputedValues: import("@sinclair/typebox").TObject<{
+    address: import("@sinclair/typebox").TString;
+    field: import("@sinclair/typebox").TString;
+}>;
+export declare const UpsertUserComputedValues: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    campaignId: import("@sinclair/typebox").TString;
+    address: import("@sinclair/typebox").TString;
+    reason: import("@sinclair/typebox").TString;
+    value: import("@sinclair/typebox").TNumber;
+    field: import("@sinclair/typebox").TString;
+}>>;
+export type GetCampaignComputedValueModel = typeof GetCampaignComputedValue.static;
+export type UpsertCampaignComputedValueModel = typeof UpsertCampaignComputedValue.static;
+export type GetUserComputedValuesModel = typeof GetUserComputedValues.static;
+export type UpsertUserComputedValuesModel = typeof UpsertUserComputedValues.static;

package/dist/src/modules/v4/computedValue/computedValue.model.js

@@ -0,0 +1,30 @@
+import { t } from "elysia";
+// ─── DTOs ────────────────────────────────────────────────────────────────────
+export const GetCampaignComputedValue = t.Object({
+    campaignId: t.String({
+        description: "The campaign Id to get the computed value for. Can be either of the for '0x1234...5678' (solidity id) or '0x1234...5678_<DISTRIBUTION_CHAIN>' or '22222' (Database id).",
+    }),
+    field: t.String({
+        description: "The field you're querying for. Example includes 'averageBoost', 'totalDistributedInUSD', 'forfeitingBoost'. Note that these aren't always available and depend on the campaign type.",
+    }),
+});
+export const UpsertCampaignComputedValue = t.Object({
+    campaignId: t.String(),
+    value: t.Number(),
+    field: t.String(),
+});
+export const GetUserComputedValues = t.Object({
+    address: t.String({
+        description: "The user's address to get the computed values for.",
+    }),
+    field: t.String({
+        description: "The field you're querying for. Example includes 'boost'.",
+    }),
+});
+export const UpsertUserComputedValues = t.Array(t.Object({
+    campaignId: t.String(),
+    address: t.String(),
+    reason: t.String(),
+    value: t.Number(),
+    field: t.String(),
+}));

package/dist/src/modules/v4/computedValue/computedValue.repository.d.ts

@@ -0,0 +1,16 @@
+import type { GetCampaignComputedValueModel, GetUserComputedValuesModel, UpsertCampaignComputedValueModel, UpsertUserComputedValuesModel } from "./computedValue.model";
+export declare abstract class ComputedValueRepository {
+    static findCampaignValue(params: GetCampaignComputedValueModel): Promise<{
+        averageBoost: number | null;
+        totalDistributedInUSD: number | null;
+        forfeitingBoost: number | null;
+    } | null>;
+    static upsertCampaignComputedValue(data: UpsertCampaignComputedValueModel): Promise<void>;
+    static findUserValues(data: GetUserComputedValuesModel): Promise<{
+        id: number;
+        reason: string;
+        campaignId: string;
+        boost: number | null;
+    }[]>;
+    static upsertUserComputedValues(data: UpsertUserComputedValuesModel): Promise<void>;
+}

package/dist/src/modules/v4/computedValue/computedValue.repository.js

@@ -0,0 +1,48 @@
+import { apiDbClient } from "@db";
+import { UserRepository } from "../user/user.repository";
+export class ComputedValueRepository {
+    static async findCampaignValue(params) {
+        return await apiDbClient.campaignComputedValue.findUnique({
+            where: { campaignId: params.campaignId },
+            select: { [params.field]: true },
+        });
+    }
+    static async upsertCampaignComputedValue(data) {
+        await apiDbClient.campaignComputedValue.upsert({
+            where: { campaignId: data.campaignId },
+            update: { [data.field]: data.value },
+            create: {
+                campaignId: data.campaignId,
+                [data.field]: data.value,
+            },
+        });
+    }
+    static async findUserValues(data) {
+        return await apiDbClient.userComputedValue.findMany({
+            where: { address: data.address },
+            select: {
+                campaignId: true,
+                reason: true,
+                [data.field]: true,
+            },
+        });
+    }
+    static async upsertUserComputedValues(data) {
+        // Make sure user foreign keys exist
+        await UserRepository.createMany(data.map(item => ({ address: item.address, tags: [] })));
+        await apiDbClient.$transaction(data.map(item => {
+            return apiDbClient.userComputedValue.upsert({
+                where: {
+                    campaignId_address_reason: { campaignId: item.campaignId, address: item.address, reason: item.reason },
+                },
+                update: { [item.field]: item.value },
+                create: {
+                    campaignId: item.campaignId,
+                    address: item.address,
+                    reason: item.reason,
+                    [item.field]: item.value,
+                },
+            });
+        }));
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { GetCampaignComputedValueModel, GetUserComputedValuesModel, UpsertCampaignComputedValueModel, UpsertUserComputedValuesModel } from "./computedValue.model";
+export declare abstract class ComputedValueService {
+    static findCampaignValue(params: GetCampaignComputedValueModel): Promise<{
+        averageBoost: number | null;
+        totalDistributedInUSD: number | null;
+        forfeitingBoost: number | null;
+    } | null>;
+    static upsertCampaignComputedValue(data: UpsertCampaignComputedValueModel): Promise<void>;
+    static findUserValues(params: GetUserComputedValuesModel): Promise<{
+        id: number;
+        reason: string;
+        campaignId: string;
+        boost: number | null;
+    }[]>;
+    static upsertUserComputedValues(data: UpsertUserComputedValuesModel): Promise<void>;
+}