@provable-games/metagame-sdk 0.1.3 → 0.1.4

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-import { P as Prize, S as StatusTimestamps, a as StatusResult, E as ExtensionAddresses, Q as QualifyingModeInfo, b as ExtensionType, c as ERC20BalanceValidatorConfig, T as TournamentValidatorConfig, O as OpusTrovesValidatorConfig, d as SnapshotValidatorConfig, Z as ZkPassportValidatorConfig, G as GovernanceValidatorConfig, e as QualificationResult, f as EntryRequirementVariant, g as QualificationProof } from './prizeAggregation-CHwIJzXr.cjs';
-export { D as DistributionType, h as EntryFeeBreakdown, i as EntryFeeExtensionConfig, j as EntryFeeShares, k as ExtensionCategory, l as Participant, m as PositionPrizeGroup, n as PrizeExtensionConfig, o as QualificationEntry, p as QualifyingMode, q as SponsorContribution, r as StatusVariant, s as Token, t as aggregatePrizesByPosition, u as aggregatePrizesBySponsor, v as calculateDistribution, w as calculateEntryFeeBreakdown, x as calculatePayouts, y as distributePool, z as filterClaimablePrizes, A as filterZeroPrizes, B as formatNumber, C as formatPrizeAmount, F as formatScore, H as formatTime, I as formatUsdValue, J as getOrdinalSuffix } from './prizeAggregation-CHwIJzXr.cjs';
+import { P as Prize, S as StatusTimestamps, a as StatusResult, E as ExtensionAddresses, Q as QualifyingModeInfo, b as ExtensionType, c as ERC20BalanceValidatorConfig, T as TournamentValidatorConfig, O as OpusTrovesValidatorConfig, d as SnapshotValidatorConfig, Z as ZkPassportValidatorConfig, G as GovernanceValidatorConfig, M as MerkleValidatorConfig, e as QualificationResult, f as EntryRequirementVariant, g as QualificationProof } from './client-CcoKJS8i.cjs';
+export { D as DistributionType, h as EntryFeeBreakdown, i as EntryFeeExtensionConfig, j as EntryFeeShares, k as ExtensionCategory, l as MetagameClient, m as MetagameClientConfig, n as Participant, o as PositionPrizeGroup, p as PrizeExtensionConfig, q as QualificationEntry, r as QualifyingMode, s as SponsorContribution, t as StatusVariant, u as Token, v as aggregatePrizesByPosition, w as aggregatePrizesBySponsor, x as calculateDistribution, y as calculateEntryFeeBreakdown, z as calculatePayouts, A as createMetagameClient, B as distributePool, C as filterClaimablePrizes, F as filterZeroPrizes, H as formatNumber, I as formatPrizeAmount, J as formatScore, K as formatTime, L as formatUsdValue, N as getOrdinalSuffix } from './client-CcoKJS8i.cjs';
 import { CairoOption, CairoCustomEnum } from 'starknet';
+import './merkle.cjs';
 
 interface EntryFee {
     tokenAddress: string;
@@ -160,6 +161,12 @@ declare function parseZkPassportValidatorConfig(config: Array<string | number |
  *                 votes_per_entry_low, votes_per_entry_high]
  */
 declare function parseGovernanceValidatorConfig(config: Array<string | number | bigint>): GovernanceValidatorConfig | null;
+/**
+ * Parse a Merkle validator extension config array.
+ *
+ * Config format: [tree_id]
+ */
+declare function parseMerkleValidatorConfig(config: Array<string | number | bigint>): MerkleValidatorConfig | null;
 /**
  * Parse any extension config by first identifying its type.
  *
@@ -185,6 +192,9 @@ declare function parseExtensionConfig(extensionAddress: string, config: Array<st
 } | {
     type: "governance";
     config: GovernanceValidatorConfig;
+} | {
+    type: "merkle";
+    config: MerkleValidatorConfig;
 } | {
     type: "unknown";
     config: null;
@@ -486,4 +496,114 @@ declare function calculateTotalPrizeValueUSD(prizes: Prize[], prices: TokenPrice
  */
 declare function calculatePaidPlaces(sponsoredPrizes: Prize[], entryFeeDistributionCount: number): number;
 
-export { type Distribution, ERC20BalanceValidatorConfig, type EntryFee, type EntryFeeConfig, type EntryRequirement, EntryRequirementVariant, ExtensionAddresses, type ExtensionQualificationInput, ExtensionType, GovernanceValidatorConfig, type GroupedTokenPrize, type NftParseResult, type NftPrizeInput, OpusTrovesValidatorConfig, Prize, QualificationProof, QualificationResult, QualifyingModeInfo, SnapshotValidatorConfig, StatusResult, StatusTimestamps, type TokenDecimalsLookup, type TokenPriceLookup, type TokenQualificationInput, type TournamentLeaderboard, type TournamentQualificationInput, type TournamentRegistration, TournamentValidatorConfig, ZkPassportValidatorConfig, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, displayAddress, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatTokenAmount, getExtensionAddresses, getOpusSupportedAssets, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications };
+/**
+ * Merkle API client for fetching proofs.
+ *
+ * The merkle validator stores tree data in a separate API service.
+ * Each network has its own API instance and database.
+ * Proofs are computed on-demand from the stored tree.
+ */
+/**
+ * Set the merkle API URL for a specific network.
+ * Call this at app initialization for each network you want to override.
+ * @deprecated Use `createMerkleClient({ chainId, apiUrl })` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function setMerkleApiUrl(chainId: string, url: string): void;
+/**
+ * Get the merkle API URL for a specific network.
+ * Falls back to SN_MAIN if the chain ID is not configured.
+ * @deprecated Use `createMerkleClient({ chainId })` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function getMerkleApiUrl(chainId?: string): string;
+interface MerkleTree {
+    id: number;
+    name: string;
+    description: string;
+    root: string;
+    entryCount: number;
+    createdAt: string;
+}
+interface MerkleProofResponse {
+    address: string;
+    count: number;
+    proof: string[];
+    qualification: string[];
+}
+interface MerkleTreesResponse {
+    data: MerkleTree[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * Fetch merkle trees from the API with pagination.
+ *
+ * @param options - Optional pagination and network parameters
+ * @returns Paginated response with tree metadata, or empty result on error
+ * @deprecated Use `MerkleClient.getTrees()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function fetchMerkleTrees(options?: {
+    page?: number;
+    limit?: number;
+    chainId?: string;
+}): Promise<MerkleTreesResponse>;
+interface CreateMerkleTreeRequest {
+    id: number;
+    name: string;
+    description: string;
+    entries: Array<{
+        address: string;
+        count: number;
+    }>;
+}
+interface CreateMerkleTreeResponse {
+    id: number;
+    root: string;
+    entryCount: number;
+}
+/**
+ * Create a merkle tree in the API.
+ *
+ * @param request - Tree data including ID (from on-chain), name, description, and entries
+ * @param chainId - Optional chain ID to select the correct API
+ * @returns The created tree metadata
+ * @deprecated Use `MerkleClient.storeTree()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function createMerkleTree(request: CreateMerkleTreeRequest, chainId?: string): Promise<CreateMerkleTreeResponse>;
+interface MerkleTreeEntry {
+    address: string;
+    count: number;
+}
+interface MerkleTreeEntriesResponse {
+    data: MerkleTreeEntry[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * Fetch entries for a merkle tree from the API with pagination.
+ *
+ * @param treeId - The on-chain tree ID
+ * @param options - Optional pagination and network parameters
+ * @returns Paginated response with tree entries, or empty result on error
+ * @deprecated Use `MerkleClient.getTreeEntries()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function fetchMerkleTreeEntries(treeId: string | number, options?: {
+    page?: number;
+    limit?: number;
+    chainId?: string;
+}): Promise<MerkleTreeEntriesResponse>;
+/**
+ * Fetch a merkle proof for a player address from the API.
+ *
+ * @param treeId - The on-chain tree ID
+ * @param playerAddress - The player's address
+ * @param chainId - Optional chain ID to select the correct API
+ * @returns The proof data including the qualification array, or null if not found
+ * @deprecated Use `MerkleClient.getProof()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function fetchMerkleProof(treeId: string | number, playerAddress: string, chainId?: string): Promise<MerkleProofResponse | null>;
+
+export { type CreateMerkleTreeRequest, type CreateMerkleTreeResponse, type Distribution, ERC20BalanceValidatorConfig, type EntryFee, type EntryFeeConfig, type EntryRequirement, EntryRequirementVariant, ExtensionAddresses, type ExtensionQualificationInput, ExtensionType, GovernanceValidatorConfig, type GroupedTokenPrize, type MerkleProofResponse, type MerkleTree, type MerkleTreeEntriesResponse, type MerkleTreeEntry, type MerkleTreesResponse, MerkleValidatorConfig, type NftParseResult, type NftPrizeInput, OpusTrovesValidatorConfig, Prize, QualificationProof, QualificationResult, QualifyingModeInfo, SnapshotValidatorConfig, StatusResult, StatusTimestamps, type TokenDecimalsLookup, type TokenPriceLookup, type TokenQualificationInput, type TournamentLeaderboard, type TournamentQualificationInput, type TournamentRegistration, TournamentValidatorConfig, ZkPassportValidatorConfig, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, createMerkleTree, displayAddress, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, fetchMerkleProof, fetchMerkleTreeEntries, fetchMerkleTrees, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatTokenAmount, getExtensionAddresses, getMerkleApiUrl, getOpusSupportedAssets, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseMerkleValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications, setMerkleApiUrl };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { P as Prize, S as StatusTimestamps, a as StatusResult, E as ExtensionAddresses, Q as QualifyingModeInfo, b as ExtensionType, c as ERC20BalanceValidatorConfig, T as TournamentValidatorConfig, O as OpusTrovesValidatorConfig, d as SnapshotValidatorConfig, Z as ZkPassportValidatorConfig, G as GovernanceValidatorConfig, e as QualificationResult, f as EntryRequirementVariant, g as QualificationProof } from './prizeAggregation-CHwIJzXr.js';
-export { D as DistributionType, h as EntryFeeBreakdown, i as EntryFeeExtensionConfig, j as EntryFeeShares, k as ExtensionCategory, l as Participant, m as PositionPrizeGroup, n as PrizeExtensionConfig, o as QualificationEntry, p as QualifyingMode, q as SponsorContribution, r as StatusVariant, s as Token, t as aggregatePrizesByPosition, u as aggregatePrizesBySponsor, v as calculateDistribution, w as calculateEntryFeeBreakdown, x as calculatePayouts, y as distributePool, z as filterClaimablePrizes, A as filterZeroPrizes, B as formatNumber, C as formatPrizeAmount, F as formatScore, H as formatTime, I as formatUsdValue, J as getOrdinalSuffix } from './prizeAggregation-CHwIJzXr.js';
+import { P as Prize, S as StatusTimestamps, a as StatusResult, E as ExtensionAddresses, Q as QualifyingModeInfo, b as ExtensionType, c as ERC20BalanceValidatorConfig, T as TournamentValidatorConfig, O as OpusTrovesValidatorConfig, d as SnapshotValidatorConfig, Z as ZkPassportValidatorConfig, G as GovernanceValidatorConfig, M as MerkleValidatorConfig, e as QualificationResult, f as EntryRequirementVariant, g as QualificationProof } from './client-CD-q6Alx.js';
+export { D as DistributionType, h as EntryFeeBreakdown, i as EntryFeeExtensionConfig, j as EntryFeeShares, k as ExtensionCategory, l as MetagameClient, m as MetagameClientConfig, n as Participant, o as PositionPrizeGroup, p as PrizeExtensionConfig, q as QualificationEntry, r as QualifyingMode, s as SponsorContribution, t as StatusVariant, u as Token, v as aggregatePrizesByPosition, w as aggregatePrizesBySponsor, x as calculateDistribution, y as calculateEntryFeeBreakdown, z as calculatePayouts, A as createMetagameClient, B as distributePool, C as filterClaimablePrizes, F as filterZeroPrizes, H as formatNumber, I as formatPrizeAmount, J as formatScore, K as formatTime, L as formatUsdValue, N as getOrdinalSuffix } from './client-CD-q6Alx.js';
 import { CairoOption, CairoCustomEnum } from 'starknet';
+import './merkle.js';
 
 interface EntryFee {
     tokenAddress: string;
@@ -160,6 +161,12 @@ declare function parseZkPassportValidatorConfig(config: Array<string | number |
  *                 votes_per_entry_low, votes_per_entry_high]
  */
 declare function parseGovernanceValidatorConfig(config: Array<string | number | bigint>): GovernanceValidatorConfig | null;
+/**
+ * Parse a Merkle validator extension config array.
+ *
+ * Config format: [tree_id]
+ */
+declare function parseMerkleValidatorConfig(config: Array<string | number | bigint>): MerkleValidatorConfig | null;
 /**
  * Parse any extension config by first identifying its type.
  *
@@ -185,6 +192,9 @@ declare function parseExtensionConfig(extensionAddress: string, config: Array<st
 } | {
     type: "governance";
     config: GovernanceValidatorConfig;
+} | {
+    type: "merkle";
+    config: MerkleValidatorConfig;
 } | {
     type: "unknown";
     config: null;
@@ -486,4 +496,114 @@ declare function calculateTotalPrizeValueUSD(prizes: Prize[], prices: TokenPrice
  */
 declare function calculatePaidPlaces(sponsoredPrizes: Prize[], entryFeeDistributionCount: number): number;
 
-export { type Distribution, ERC20BalanceValidatorConfig, type EntryFee, type EntryFeeConfig, type EntryRequirement, EntryRequirementVariant, ExtensionAddresses, type ExtensionQualificationInput, ExtensionType, GovernanceValidatorConfig, type GroupedTokenPrize, type NftParseResult, type NftPrizeInput, OpusTrovesValidatorConfig, Prize, QualificationProof, QualificationResult, QualifyingModeInfo, SnapshotValidatorConfig, StatusResult, StatusTimestamps, type TokenDecimalsLookup, type TokenPriceLookup, type TokenQualificationInput, type TournamentLeaderboard, type TournamentQualificationInput, type TournamentRegistration, TournamentValidatorConfig, ZkPassportValidatorConfig, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, displayAddress, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatTokenAmount, getExtensionAddresses, getOpusSupportedAssets, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications };
+/**
+ * Merkle API client for fetching proofs.
+ *
+ * The merkle validator stores tree data in a separate API service.
+ * Each network has its own API instance and database.
+ * Proofs are computed on-demand from the stored tree.
+ */
+/**
+ * Set the merkle API URL for a specific network.
+ * Call this at app initialization for each network you want to override.
+ * @deprecated Use `createMerkleClient({ chainId, apiUrl })` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function setMerkleApiUrl(chainId: string, url: string): void;
+/**
+ * Get the merkle API URL for a specific network.
+ * Falls back to SN_MAIN if the chain ID is not configured.
+ * @deprecated Use `createMerkleClient({ chainId })` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function getMerkleApiUrl(chainId?: string): string;
+interface MerkleTree {
+    id: number;
+    name: string;
+    description: string;
+    root: string;
+    entryCount: number;
+    createdAt: string;
+}
+interface MerkleProofResponse {
+    address: string;
+    count: number;
+    proof: string[];
+    qualification: string[];
+}
+interface MerkleTreesResponse {
+    data: MerkleTree[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * Fetch merkle trees from the API with pagination.
+ *
+ * @param options - Optional pagination and network parameters
+ * @returns Paginated response with tree metadata, or empty result on error
+ * @deprecated Use `MerkleClient.getTrees()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function fetchMerkleTrees(options?: {
+    page?: number;
+    limit?: number;
+    chainId?: string;
+}): Promise<MerkleTreesResponse>;
+interface CreateMerkleTreeRequest {
+    id: number;
+    name: string;
+    description: string;
+    entries: Array<{
+        address: string;
+        count: number;
+    }>;
+}
+interface CreateMerkleTreeResponse {
+    id: number;
+    root: string;
+    entryCount: number;
+}
+/**
+ * Create a merkle tree in the API.
+ *
+ * @param request - Tree data including ID (from on-chain), name, description, and entries
+ * @param chainId - Optional chain ID to select the correct API
+ * @returns The created tree metadata
+ * @deprecated Use `MerkleClient.storeTree()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function createMerkleTree(request: CreateMerkleTreeRequest, chainId?: string): Promise<CreateMerkleTreeResponse>;
+interface MerkleTreeEntry {
+    address: string;
+    count: number;
+}
+interface MerkleTreeEntriesResponse {
+    data: MerkleTreeEntry[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * Fetch entries for a merkle tree from the API with pagination.
+ *
+ * @param treeId - The on-chain tree ID
+ * @param options - Optional pagination and network parameters
+ * @returns Paginated response with tree entries, or empty result on error
+ * @deprecated Use `MerkleClient.getTreeEntries()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function fetchMerkleTreeEntries(treeId: string | number, options?: {
+    page?: number;
+    limit?: number;
+    chainId?: string;
+}): Promise<MerkleTreeEntriesResponse>;
+/**
+ * Fetch a merkle proof for a player address from the API.
+ *
+ * @param treeId - The on-chain tree ID
+ * @param playerAddress - The player's address
+ * @param chainId - Optional chain ID to select the correct API
+ * @returns The proof data including the qualification array, or null if not found
+ * @deprecated Use `MerkleClient.getProof()` from `@provable-games/metagame-sdk/merkle` instead.
+ */
+declare function fetchMerkleProof(treeId: string | number, playerAddress: string, chainId?: string): Promise<MerkleProofResponse | null>;
+
+export { type CreateMerkleTreeRequest, type CreateMerkleTreeResponse, type Distribution, ERC20BalanceValidatorConfig, type EntryFee, type EntryFeeConfig, type EntryRequirement, EntryRequirementVariant, ExtensionAddresses, type ExtensionQualificationInput, ExtensionType, GovernanceValidatorConfig, type GroupedTokenPrize, type MerkleProofResponse, type MerkleTree, type MerkleTreeEntriesResponse, type MerkleTreeEntry, type MerkleTreesResponse, MerkleValidatorConfig, type NftParseResult, type NftPrizeInput, OpusTrovesValidatorConfig, Prize, QualificationProof, QualificationResult, QualifyingModeInfo, SnapshotValidatorConfig, StatusResult, StatusTimestamps, type TokenDecimalsLookup, type TokenPriceLookup, type TokenQualificationInput, type TournamentLeaderboard, type TournamentQualificationInput, type TournamentRegistration, TournamentValidatorConfig, ZkPassportValidatorConfig, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, createMerkleTree, displayAddress, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, fetchMerkleProof, fetchMerkleTreeEntries, fetchMerkleTrees, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatTokenAmount, getExtensionAddresses, getMerkleApiUrl, getOpusSupportedAssets, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseMerkleValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications, setMerkleApiUrl };

package/dist/index.js

@@ -1,4 +1,5 @@
-import { CairoOption, CairoOptionVariant, CairoCustomEnum } from 'starknet';
+import { CairoOption, CairoOptionVariant, CairoCustomEnum, hash } from 'starknet';
+import { StandardMerkleTree } from '@ericnordelo/strk-merkle-tree';
 
 // src/types/extensions.ts
 var QualifyingMode = /* @__PURE__ */ ((QualifyingMode2) => {
@@ -475,12 +476,13 @@ function parseKeyValueFormat(input) {
 // src/utils/extensions.ts
 var EXTENSION_ADDRESSES = {
   SN_SEPOLIA: {
-    tournamentValidator: "0x04c9ba290bbebd47f87141801623748884af610230cdaf69232007b4135be3f1",
-    erc20BalanceValidator: "0x05437210fd8231893da2317971983ae1f810d8d500344ad09e5b258b5820a908",
+    tournamentValidator: "0x07eade45e4317b1a036e3a8123bb1f95215d37a6f6b0cea25cdd48030a932dfc",
+    erc20BalanceValidator: "0x028112199f873e919963277b41ef1231365986e2fd7722501cd7d293de60b64e",
     opusTrovesValidator: "0x0317f96eeff41d1badffd9bda126d36c1806523d8c91a5b440f9bdf2aa2b9fe7",
-    snapshotValidator: "0x02628045f0688663ecacbaefdbbc46c2e315b2da39271419e8a3443fe4120f61",
+    snapshotValidator: "0x05520239f16dc58c5dfdccb1f0480977e7fea18d4305e64f5eae88ae786a22fe",
     zkPassportValidator: "0x025b65137c5297e03491830635f4c5d76eb17e5b2db3bf49dbee34bba94ad3e6",
-    governanceValidator: "0x0585e6b1aa8daac7711004a92a8d0d3b5a81eaac8c9a07db24fc34b1a4f2322c"
+    governanceValidator: "0x0585e6b1aa8daac7711004a92a8d0d3b5a81eaac8c9a07db24fc34b1a4f2322c",
+    merkleValidator: "0x07a5b716c65ac5726ecd0b023ff1b4cc9090820707a508b49f5ed42e44a401c4"
   },
   SN_MAIN: {
     tournamentValidator: "0x0771b57c0709fc4407ff8b63d573f302b96fb03638364032fad734e3c310b9e0",
@@ -488,7 +490,9 @@ var EXTENSION_ADDRESSES = {
     opusTrovesValidator: "0x0604bc0d54727f439786c65d7dc6f7d46de1aba7e129ef9caf65fef111a1644e",
     snapshotValidator: "0x03e6820e9e1cfb5c22465a86f469c651355f05397e29fc94de8e832d5f3d8ede",
     zkPassportValidator: "0x01a25f04c8a39da7bb37adcc53d595fde9e60702611d15b1c498df0657001479",
-    governanceValidator: ""
+    governanceValidator: "",
+    // placeholder until deployed
+    merkleValidator: ""
     // placeholder until deployed
   }
 };
@@ -553,6 +557,9 @@ function identifyExtensionType(extensionAddress, chainId) {
   if (addresses.governanceValidator && normalizeAddr(addresses.governanceValidator) === normalized) {
     return "governance";
   }
+  if (addresses.merkleValidator && normalizeAddr(addresses.merkleValidator) === normalized) {
+    return "merkle";
+  }
   return "unknown";
 }
 function parseTournamentValidatorConfig(config) {
@@ -623,6 +630,12 @@ function parseGovernanceValidatorConfig(config) {
     votesPerEntry: BigInt(config[10]) << 128n | BigInt(config[9])
   };
 }
+function parseMerkleValidatorConfig(config) {
+  if (!config || config.length === 0) return null;
+  return {
+    treeId: String(Number(BigInt(config[0] ?? "0")))
+  };
+}
 function parseExtensionConfig(extensionAddress, config, chainId) {
   const extensionType = identifyExtensionType(extensionAddress, chainId);
   switch (extensionType) {
@@ -650,6 +663,10 @@ function parseExtensionConfig(extensionAddress, config, chainId) {
       const parsed = parseGovernanceValidatorConfig(config);
       return parsed ? { type: "governance", config: parsed } : null;
     }
+    case "merkle": {
+      const parsed = parseMerkleValidatorConfig(config);
+      return parsed ? { type: "merkle", config: parsed } : null;
+    }
     default:
       return { type: "unknown", config: null };
   }
@@ -1010,6 +1027,284 @@ function calculatePaidPlaces(sponsoredPrizes, entryFeeDistributionCount) {
   return Math.max(maxSponsoredPosition, entryFeeDistributionCount);
 }
 
-export { QualifyingMode, aggregatePrizesByPosition, aggregatePrizesBySponsor, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateDistribution, calculateEntryFeeBreakdown, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePayouts, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, displayAddress, distributePool, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, filterClaimablePrizes, filterZeroPrizes, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatNumber, formatPrizeAmount, formatScore, formatTime, formatTokenAmount, formatUsdValue, getExtensionAddresses, getOpusSupportedAssets, getOrdinalSuffix, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications };
+// src/utils/merkleApi.ts
+var DEFAULT_MERKLE_API_URLS = {
+  SN_SEPOLIA: "https://merkle-api-sepolia.up.railway.app",
+  SN_MAIN: "https://merkle-api.up.railway.app"
+};
+var merkleApiUrls = { ...DEFAULT_MERKLE_API_URLS };
+function setMerkleApiUrl(chainId, url) {
+  merkleApiUrls[chainId] = url;
+}
+function getMerkleApiUrl(chainId) {
+  if (chainId && merkleApiUrls[chainId]) {
+    return merkleApiUrls[chainId];
+  }
+  return merkleApiUrls.SN_MAIN ?? DEFAULT_MERKLE_API_URLS.SN_MAIN;
+}
+async function fetchMerkleTrees(options) {
+  const empty = {
+    data: [],
+    total: 0,
+    page: 1,
+    limit: 20,
+    totalPages: 0
+  };
+  try {
+    const baseUrl = getMerkleApiUrl(options?.chainId);
+    const params = new URLSearchParams();
+    if (options?.page) params.set("page", String(options.page));
+    if (options?.limit) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const res = await fetch(`${baseUrl}/trees${qs ? `?${qs}` : ""}`);
+    if (!res.ok) return empty;
+    const json = await res.json();
+    return {
+      data: json.data ?? [],
+      total: json.total ?? 0,
+      page: json.page ?? 1,
+      limit: json.limit ?? 20,
+      totalPages: json.totalPages ?? 0
+    };
+  } catch {
+    return empty;
+  }
+}
+async function createMerkleTree(request, chainId) {
+  const baseUrl = getMerkleApiUrl(chainId);
+  const res = await fetch(`${baseUrl}/trees`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Failed to create merkle tree: ${text}`);
+  }
+  return await res.json();
+}
+async function fetchMerkleTreeEntries(treeId, options) {
+  const empty = {
+    data: [],
+    total: 0,
+    page: 1,
+    limit: 50,
+    totalPages: 0
+  };
+  try {
+    const baseUrl = getMerkleApiUrl(options?.chainId);
+    const params = new URLSearchParams();
+    if (options?.page) params.set("page", String(options.page));
+    if (options?.limit) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const res = await fetch(
+      `${baseUrl}/trees/${treeId}/entries${qs ? `?${qs}` : ""}`
+    );
+    if (!res.ok) return empty;
+    const json = await res.json();
+    return {
+      data: json.data ?? [],
+      total: json.total ?? 0,
+      page: json.page ?? 1,
+      limit: json.limit ?? 50,
+      totalPages: json.totalPages ?? 0
+    };
+  } catch {
+    return empty;
+  }
+}
+async function fetchMerkleProof(treeId, playerAddress, chainId) {
+  try {
+    const baseUrl = getMerkleApiUrl(chainId);
+    const res = await fetch(
+      `${baseUrl}/trees/${treeId}/proof/${playerAddress.toLowerCase()}`
+    );
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+function computeLeafValue(address, count) {
+  const intermediate = hash.computePedersenHash("0x0", address);
+  return hash.computePedersenHash(intermediate, "0x" + count.toString(16));
+}
+function buildMerkleTree(entries) {
+  if (entries.length === 0) {
+    throw new Error("Cannot build merkle tree with no entries");
+  }
+  const leaves = entries.map((e) => [computeLeafValue(e.address, e.count)]);
+  const tree = StandardMerkleTree.of(leaves, ["felt252"], {
+    sortLeaves: true
+  });
+  return {
+    version: 2,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    entries,
+    root: tree.root,
+    tree: tree.dump()
+  };
+}
+
+// src/merkle/client.ts
+var DEFAULT_MERKLE_API_URLS2 = {
+  SN_SEPOLIA: "https://merkle-api-sepolia.up.railway.app",
+  SN_MAIN: "https://merkle-api.up.railway.app"
+};
+var MerkleClient = class {
+  apiUrl;
+  constructor(config) {
+    this.apiUrl = config.apiUrl ?? DEFAULT_MERKLE_API_URLS2[config.chainId] ?? DEFAULT_MERKLE_API_URLS2.SN_MAIN;
+  }
+  /** Fetch paginated list of merkle trees. */
+  async getTrees(options) {
+    const empty = {
+      data: [],
+      total: 0,
+      page: 1,
+      limit: 20,
+      totalPages: 0
+    };
+    try {
+      const params = new URLSearchParams();
+      if (options?.page) params.set("page", String(options.page));
+      if (options?.limit) params.set("limit", String(options.limit));
+      const qs = params.toString();
+      const res = await fetch(`${this.apiUrl}/trees${qs ? `?${qs}` : ""}`);
+      if (!res.ok) return empty;
+      const json = await res.json();
+      return {
+        data: json.data ?? [],
+        total: json.total ?? 0,
+        page: json.page ?? 1,
+        limit: json.limit ?? 20,
+        totalPages: json.totalPages ?? 0
+      };
+    } catch {
+      return empty;
+    }
+  }
+  /** Fetch entries for a specific merkle tree. */
+  async getTreeEntries(treeId, options) {
+    const empty = {
+      data: [],
+      total: 0,
+      page: 1,
+      limit: 50,
+      totalPages: 0
+    };
+    try {
+      const params = new URLSearchParams();
+      if (options?.page) params.set("page", String(options.page));
+      if (options?.limit) params.set("limit", String(options.limit));
+      const qs = params.toString();
+      const res = await fetch(
+        `${this.apiUrl}/trees/${treeId}/entries${qs ? `?${qs}` : ""}`
+      );
+      if (!res.ok) return empty;
+      const json = await res.json();
+      return {
+        data: json.data ?? [],
+        total: json.total ?? 0,
+        page: json.page ?? 1,
+        limit: json.limit ?? 50,
+        totalPages: json.totalPages ?? 0
+      };
+    } catch {
+      return empty;
+    }
+  }
+  /** Fetch a merkle proof for a player address. */
+  async getProof(treeId, playerAddress) {
+    try {
+      const res = await fetch(
+        `${this.apiUrl}/trees/${treeId}/proof/${playerAddress.toLowerCase()}`
+      );
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    }
+  }
+  /** Store a merkle tree in the API (after on-chain registration). */
+  async storeTree(request) {
+    const res = await fetch(`${this.apiUrl}/trees`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Failed to create merkle tree: ${text}`);
+    }
+    return await res.json();
+  }
+  /**
+   * Build a merkle tree locally and return the calldata needed
+   * to register it on-chain via the validator contract.
+   *
+   * The consumer is responsible for executing the call with their
+   * own account/signer.
+   */
+  buildTreeCalldata(entries, validatorAddress) {
+    const tree = buildMerkleTree(entries);
+    return {
+      tree,
+      call: {
+        contractAddress: validatorAddress,
+        entrypoint: "create_tree",
+        calldata: [tree.root]
+      }
+    };
+  }
+  /**
+   * Parse the tree ID from transaction receipt events.
+   * Returns null if the event cannot be found.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parseTreeIdFromEvents(events, validatorAddress) {
+    const validatorBigInt = BigInt(validatorAddress);
+    const treeEvent = events.find((e) => {
+      try {
+        return BigInt(e.from_address) === validatorBigInt;
+      } catch {
+        return false;
+      }
+    });
+    if (!treeEvent?.keys?.[1]) return null;
+    return Number(BigInt(treeEvent.keys[1]));
+  }
+  /**
+   * Store the tree in the API after on-chain registration.
+   * Pass the tree ID from the on-chain event along with the original entries.
+   */
+  async createTree(params) {
+    return this.storeTree({
+      id: params.treeId,
+      name: params.name,
+      description: params.description,
+      entries: params.entries
+    });
+  }
+};
+
+// src/client.ts
+var MetagameClient = class {
+  chainId;
+  merkle;
+  constructor(config) {
+    this.chainId = config.chainId;
+    const merkleConfig = {
+      chainId: config.chainId,
+      apiUrl: config.merkleApiUrl
+    };
+    this.merkle = new MerkleClient(merkleConfig);
+  }
+};
+function createMetagameClient(config) {
+  return new MetagameClient(config);
+}
+
+export { MetagameClient, QualifyingMode, aggregatePrizesByPosition, aggregatePrizesBySponsor, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateDistribution, calculateEntryFeeBreakdown, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePayouts, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, createMerkleTree, createMetagameClient, displayAddress, distributePool, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, fetchMerkleProof, fetchMerkleTreeEntries, fetchMerkleTrees, filterClaimablePrizes, filterZeroPrizes, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatNumber, formatPrizeAmount, formatScore, formatTime, formatTokenAmount, formatUsdValue, getExtensionAddresses, getMerkleApiUrl, getOpusSupportedAssets, getOrdinalSuffix, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseMerkleValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications, setMerkleApiUrl };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map