@provable-games/metagame-sdk 0.1.2 → 0.1.4

package/dist/merkle.js

@@ -0,0 +1,200 @@
+import { StandardMerkleTree } from '@ericnordelo/strk-merkle-tree';
+import { hash } from 'starknet';
+
+// src/merkle/merkleTree.ts
+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()
+  };
+}
+function getProof(treeData, address, count) {
+  const tree = StandardMerkleTree.load(treeData.tree);
+  const leafValue = computeLeafValue(address, count);
+  for (const [index, leaf] of tree.entries()) {
+    if (BigInt(leaf[0]) === BigInt(leafValue)) {
+      return tree.getProof(index);
+    }
+  }
+  return null;
+}
+function verifyProof(treeData, address, count, proof) {
+  const leafValue = computeLeafValue(address, count);
+  return StandardMerkleTree.verify(
+    treeData.root,
+    ["felt252"],
+    [leafValue],
+    proof
+  );
+}
+function buildQualification(count, proof) {
+  return ["0x" + count.toString(16), ...proof];
+}
+function findEntry(treeData, address) {
+  return treeData.entries.find(
+    (e) => e.address.toLowerCase() === address.toLowerCase() || BigInt(e.address) === BigInt(address)
+  ) || null;
+}
+
+// src/merkle/client.ts
+var DEFAULT_MERKLE_API_URLS = {
+  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_URLS[config.chainId] ?? DEFAULT_MERKLE_API_URLS.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
+    });
+  }
+};
+function createMerkleClient(config) {
+  return new MerkleClient(config);
+}
+
+export { MerkleClient, buildMerkleTree, buildQualification, computeLeafValue, createMerkleClient, findEntry, getProof, verifyProof };
+//# sourceMappingURL=merkle.js.map
+//# sourceMappingURL=merkle.js.map

package/dist/merkle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/merkle/merkleTree.ts","../src/merkle/client.ts"],"names":[],"mappings":"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","file":"merkle.js","sourcesContent":["import { StandardMerkleTree } from \"@ericnordelo/strk-merkle-tree\";\nimport { hash } from \"starknet\";\n\nexport interface MerkleEntry {\n  address: string;\n  count: number;\n}\n\nexport interface MerkleTreeData {\n  version: 2;\n  createdAt: string;\n  entries: MerkleEntry[];\n  root: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  tree: any; // StandardMerkleTree dump format\n}\n\n/**\n * Compute the leaf value that gets passed to StandardMerkleTree.\n * This matches the Cairo contract's leaf computation:\n *   PedersenTrait::new(0).update(address).update(count).finalize()\n *\n * The StandardMerkleTree then applies its own leaf hashing on top:\n *   H(0, value, 1) using PedersenCHasher\n */\nexport function computeLeafValue(address: string, count: number): string {\n  const intermediate = hash.computePedersenHash(\"0x0\", address);\n  return hash.computePedersenHash(intermediate, \"0x\" + count.toString(16));\n}\n\n/**\n * Build a StandardMerkleTree from entries.\n * Each leaf is a single felt252 value (the pre-hashed leaf value).\n */\nexport function buildMerkleTree(entries: MerkleEntry[]): MerkleTreeData {\n  if (entries.length === 0) {\n    throw new Error(\"Cannot build merkle tree with no entries\");\n  }\n\n  const leaves = entries.map((e) => [computeLeafValue(e.address, e.count)]);\n\n  const tree = StandardMerkleTree.of(leaves, [\"felt252\"], {\n    sortLeaves: true,\n  });\n\n  return {\n    version: 2,\n    createdAt: new Date().toISOString(),\n    entries,\n    root: tree.root,\n    tree: tree.dump(),\n  };\n}\n\n/**\n * Load a tree from saved data and get the proof for an address.\n */\nexport function getProof(\n  treeData: MerkleTreeData,\n  address: string,\n  count: number,\n): string[] | null {\n  const tree = StandardMerkleTree.load(treeData.tree);\n  const leafValue = computeLeafValue(address, count);\n\n  for (const [index, leaf] of tree.entries()) {\n    if (BigInt(leaf[0] as string) === BigInt(leafValue)) {\n      return tree.getProof(index);\n    }\n  }\n\n  return null;\n}\n\n/**\n * Verify a proof against a root (client-side).\n */\nexport function verifyProof(\n  treeData: MerkleTreeData,\n  address: string,\n  count: number,\n  proof: string[],\n): boolean {\n  const leafValue = computeLeafValue(address, count);\n  return StandardMerkleTree.verify(\n    treeData.root,\n    [\"felt252\"],\n    [leafValue],\n    proof,\n  );\n}\n\n/**\n * Build qualification array for contract calls: [count, ...proof]\n */\nexport function buildQualification(count: number, proof: string[]): string[] {\n  return [\"0x\" + count.toString(16), ...proof];\n}\n\n/**\n * Find an entry in the tree by address.\n */\nexport function findEntry(\n  treeData: MerkleTreeData,\n  address: string,\n): MerkleEntry | null {\n  return (\n    treeData.entries.find(\n      (e) =>\n        e.address.toLowerCase() === address.toLowerCase() ||\n        BigInt(e.address) === BigInt(address),\n    ) || null\n  );\n}\n","/**\n * MerkleClient — chainId-aware client for the merkle API service.\n *\n * Resolves the API URL once at construction time so callers never\n * need to pass chainId on every request.\n */\n\nimport { buildMerkleTree } from \"./merkleTree\";\nimport type { MerkleEntry } from \"./merkleTree\";\n\n// ── Default API URLs per chain ──────────────────────────────────────────────\n\nconst DEFAULT_MERKLE_API_URLS: Record<string, string> = {\n  SN_SEPOLIA: \"https://merkle-api-sepolia.up.railway.app\",\n  SN_MAIN: \"https://merkle-api.up.railway.app\",\n};\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\nexport interface MerkleClientConfig {\n  /** Starknet chain ID, e.g. \"SN_MAIN\" or \"SN_SEPOLIA\" */\n  chainId: string;\n  /** Override the default API URL for this chain */\n  apiUrl?: string;\n}\n\nexport interface MerkleTree {\n  id: number;\n  name: string;\n  description: string;\n  root: string;\n  entryCount: number;\n  createdAt: string;\n}\n\nexport interface MerkleTreesResponse {\n  data: MerkleTree[];\n  total: number;\n  page: number;\n  limit: number;\n  totalPages: number;\n}\n\nexport interface MerkleProofResponse {\n  address: string;\n  count: number;\n  proof: string[];\n  qualification: string[];\n}\n\nexport interface MerkleTreeEntry {\n  address: string;\n  count: number;\n}\n\nexport interface MerkleTreeEntriesResponse {\n  data: MerkleTreeEntry[];\n  total: number;\n  page: number;\n  limit: number;\n  totalPages: number;\n}\n\nexport interface CreateMerkleTreeRequest {\n  id: number;\n  name: string;\n  description: string;\n  entries: MerkleEntry[];\n}\n\nexport interface CreateMerkleTreeResponse {\n  id: number;\n  root: string;\n  entryCount: number;\n}\n\nexport interface TreeCalldata {\n  tree: ReturnType<typeof buildMerkleTree>;\n  call: {\n    contractAddress: string;\n    entrypoint: string;\n    calldata: string[];\n  };\n}\n\n// ── Client ──────────────────────────────────────────────────────────────────\n\nexport class MerkleClient {\n  readonly apiUrl: string;\n\n  constructor(config: MerkleClientConfig) {\n    this.apiUrl =\n      config.apiUrl ??\n      DEFAULT_MERKLE_API_URLS[config.chainId] ??\n      DEFAULT_MERKLE_API_URLS.SN_MAIN;\n  }\n\n  /** Fetch paginated list of merkle trees. */\n  async getTrees(options?: {\n    page?: number;\n    limit?: number;\n  }): Promise<MerkleTreesResponse> {\n    const empty: MerkleTreesResponse = {\n      data: [],\n      total: 0,\n      page: 1,\n      limit: 20,\n      totalPages: 0,\n    };\n    try {\n      const params = new URLSearchParams();\n      if (options?.page) params.set(\"page\", String(options.page));\n      if (options?.limit) params.set(\"limit\", String(options.limit));\n      const qs = params.toString();\n      const res = await fetch(`${this.apiUrl}/trees${qs ? `?${qs}` : \"\"}`);\n      if (!res.ok) return empty;\n      const json = await res.json();\n      return {\n        data: json.data ?? [],\n        total: json.total ?? 0,\n        page: json.page ?? 1,\n        limit: json.limit ?? 20,\n        totalPages: json.totalPages ?? 0,\n      };\n    } catch {\n      return empty;\n    }\n  }\n\n  /** Fetch entries for a specific merkle tree. */\n  async getTreeEntries(\n    treeId: string | number,\n    options?: { page?: number; limit?: number },\n  ): Promise<MerkleTreeEntriesResponse> {\n    const empty: MerkleTreeEntriesResponse = {\n      data: [],\n      total: 0,\n      page: 1,\n      limit: 50,\n      totalPages: 0,\n    };\n    try {\n      const params = new URLSearchParams();\n      if (options?.page) params.set(\"page\", String(options.page));\n      if (options?.limit) params.set(\"limit\", String(options.limit));\n      const qs = params.toString();\n      const res = await fetch(\n        `${this.apiUrl}/trees/${treeId}/entries${qs ? `?${qs}` : \"\"}`,\n      );\n      if (!res.ok) return empty;\n      const json = await res.json();\n      return {\n        data: json.data ?? [],\n        total: json.total ?? 0,\n        page: json.page ?? 1,\n        limit: json.limit ?? 50,\n        totalPages: json.totalPages ?? 0,\n      };\n    } catch {\n      return empty;\n    }\n  }\n\n  /** Fetch a merkle proof for a player address. */\n  async getProof(\n    treeId: string | number,\n    playerAddress: string,\n  ): Promise<MerkleProofResponse | null> {\n    try {\n      const res = await fetch(\n        `${this.apiUrl}/trees/${treeId}/proof/${playerAddress.toLowerCase()}`,\n      );\n      if (!res.ok) return null;\n      return await res.json();\n    } catch {\n      return null;\n    }\n  }\n\n  /** Store a merkle tree in the API (after on-chain registration). */\n  async storeTree(\n    request: CreateMerkleTreeRequest,\n  ): Promise<CreateMerkleTreeResponse> {\n    const res = await fetch(`${this.apiUrl}/trees`, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify(request),\n    });\n    if (!res.ok) {\n      const text = await res.text();\n      throw new Error(`Failed to create merkle tree: ${text}`);\n    }\n    return await res.json();\n  }\n\n  /**\n   * Build a merkle tree locally and return the calldata needed\n   * to register it on-chain via the validator contract.\n   *\n   * The consumer is responsible for executing the call with their\n   * own account/signer.\n   */\n  buildTreeCalldata(\n    entries: MerkleEntry[],\n    validatorAddress: string,\n  ): TreeCalldata {\n    const tree = buildMerkleTree(entries);\n    return {\n      tree,\n      call: {\n        contractAddress: validatorAddress,\n        entrypoint: \"create_tree\",\n        calldata: [tree.root],\n      },\n    };\n  }\n\n  /**\n   * Parse the tree ID from transaction receipt events.\n   * Returns null if the event cannot be found.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  parseTreeIdFromEvents(events: any[], validatorAddress: string): number | null {\n    const validatorBigInt = BigInt(validatorAddress);\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const treeEvent = events.find((e: any) => {\n      try {\n        return BigInt(e.from_address) === validatorBigInt;\n      } catch {\n        return false;\n      }\n    });\n    if (!treeEvent?.keys?.[1]) return null;\n    return Number(BigInt(treeEvent.keys[1]));\n  }\n\n  /**\n   * Store the tree in the API after on-chain registration.\n   * Pass the tree ID from the on-chain event along with the original entries.\n   */\n  async createTree(params: {\n    treeId: number;\n    name: string;\n    description: string;\n    entries: MerkleEntry[];\n  }): Promise<CreateMerkleTreeResponse> {\n    return this.storeTree({\n      id: params.treeId,\n      name: params.name,\n      description: params.description,\n      entries: params.entries,\n    });\n  }\n}\n\n/** Factory function for creating a MerkleClient. */\nexport function createMerkleClient(config: MerkleClientConfig): MerkleClient {\n  return new MerkleClient(config);\n}\n"]}

package/dist/react.cjs

@@ -1,9 +1,240 @@
 'use strict';
 
 var react = require('react');
+var strkMerkleTree = require('@ericnordelo/strk-merkle-tree');
 var starknet = require('starknet');
+var jsxRuntime = require('react/jsx-runtime');
 
-// src/react/useDebounce.ts
+// src/react/MetagameProvider.tsx
+function computeLeafValue(address, count) {
+  const intermediate = starknet.hash.computePedersenHash("0x0", address);
+  return starknet.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 = strkMerkleTree.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_URLS = {
+  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_URLS[config.chainId] ?? DEFAULT_MERKLE_API_URLS.SN_MAIN;
+  }
+  /** Fetch paginated list of merkle trees. */
+  async getTrees(options) {
+    const empty2 = {
+      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 empty2;
+      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 empty2;
+    }
+  }
+  /** Fetch entries for a specific merkle tree. */
+  async getTreeEntries(treeId, options) {
+    const empty2 = {
+      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 empty2;
+      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 empty2;
+    }
+  }
+  /** 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);
+}
+var MetagameContext = react.createContext(null);
+function MetagameProvider({
+  children,
+  ...config
+}) {
+  const client = react.useMemo(
+    () => createMetagameClient(config),
+    [config.chainId, config.merkleApiUrl]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(MetagameContext.Provider, { value: client, children });
+}
+function useMetagameClient() {
+  const client = react.useContext(MetagameContext);
+  if (!client) {
+    throw new Error(
+      "useMetagameClient must be used within a MetagameProvider"
+    );
+  }
+  return client;
+}
+function useMerkleTrees(options) {
+  const client = useMetagameClient();
+  const [data, setData] = react.useState(null);
+  const [isLoading, setIsLoading] = react.useState(true);
+  react.useEffect(() => {
+    setIsLoading(true);
+    client.merkle.getTrees({ page: options?.page, limit: options?.limit }).then(setData).finally(() => setIsLoading(false));
+  }, [client, options?.page, options?.limit]);
+  return {
+    trees: data?.data ?? [],
+    total: data?.total ?? 0,
+    totalPages: data?.totalPages ?? 0,
+    page: data?.page ?? 1,
+    isLoading
+  };
+}
+function useMerkleProof(treeId, playerAddress) {
+  const client = useMetagameClient();
+  const [proof, setProof] = react.useState(null);
+  const [isLoading, setIsLoading] = react.useState(false);
+  react.useEffect(() => {
+    if (!treeId || !playerAddress) {
+      setProof(null);
+      return;
+    }
+    setIsLoading(true);
+    client.merkle.getProof(treeId, playerAddress).then(setProof).finally(() => setIsLoading(false));
+  }, [client, treeId, playerAddress]);
+  return { proof, isLoading };
+}
 function useDebounce(value, delay) {
   const [debouncedValue, setDebouncedValue] = react.useState(value);
   react.useEffect(() => {
@@ -702,11 +933,7 @@ var useExtensionQualification = (provider, extensionAddress, contextId, playerAd
       extensionAddress,
       contextId,
       playerAddress,
-      inputs: qualificationInputs.map((i) => ({
-        tid: i.tournamentId,
-        token: i.tokenId,
-        pos: i.position
-      }))
+      inputs: qualificationInputs.map((i) => ({ id: i.id, proof: i.proof }))
     });
   }, [enabled, provider, extensionAddress, contextId, playerAddress, qualificationInputs]);
   const lastFetchedKey = react.useRef("");
@@ -729,36 +956,26 @@ var useExtensionQualification = (provider, extensionAddress, contextId, playerAd
         const results = await Promise.all(
           qualificationInputs.map(async (input) => {
             try {
-              const proof = [
-                input.tournamentId,
-                input.tokenId,
-                input.position.toString()
-              ];
               const entriesLeft = await getExtensionEntriesLeft(
                 provider,
                 extensionAddress,
                 contextId,
                 playerAddress,
-                proof
+                input.proof
               );
               if (entriesLeft !== null && entriesLeft > 0) {
                 return {
-                  id: `${input.tournamentId}-${input.tokenId}-${input.position}`,
-                  proof,
+                  id: input.id,
+                  proof: input.proof,
                   entriesLeft,
-                  label: input.tournamentName,
-                  metadata: {
-                    tournamentId: input.tournamentId,
-                    tournamentName: input.tournamentName,
-                    tokenId: input.tokenId,
-                    position: input.position
-                  }
+                  label: input.label,
+                  metadata: input.metadata
                 };
               }
               return null;
             } catch (err) {
               console.error(
-                `Error checking qualification for ${input.tournamentId}:`,
+                `Error checking qualification ${input.id}:`,
                 err
               );
               return null;
@@ -903,10 +1120,14 @@ var useOpusTrovesBannableEntries = (provider, games, config, enabled) => {
   };
 };
 
+exports.MetagameProvider = MetagameProvider;
 exports.useDebounce = useDebounce;
 exports.useEntryFeePreview = useEntryFeePreview;
 exports.useEntryQualification = useEntryQualification;
 exports.useExtensionQualification = useExtensionQualification;
+exports.useMerkleProof = useMerkleProof;
+exports.useMerkleTrees = useMerkleTrees;
+exports.useMetagameClient = useMetagameClient;
 exports.useOpusTrovesBannableEntries = useOpusTrovesBannableEntries;
 exports.usePagination = usePagination;
 exports.usePrizeTable = usePrizeTable;