@provable-games/metagame-sdk 0.1.2 → 0.1.4

package/dist/merkle.cjs

@@ -0,0 +1,209 @@
+'use strict';
+
+var strkMerkleTree = require('@ericnordelo/strk-merkle-tree');
+var starknet = require('starknet');
+
+// src/merkle/merkleTree.ts
+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()
+  };
+}
+function getProof(treeData, address, count) {
+  const tree = strkMerkleTree.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 strkMerkleTree.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);
+}
+
+exports.MerkleClient = MerkleClient;
+exports.buildMerkleTree = buildMerkleTree;
+exports.buildQualification = buildQualification;
+exports.computeLeafValue = computeLeafValue;
+exports.createMerkleClient = createMerkleClient;
+exports.findEntry = findEntry;
+exports.getProof = getProof;
+exports.verifyProof = verifyProof;
+//# sourceMappingURL=merkle.cjs.map
+//# sourceMappingURL=merkle.cjs.map

package/dist/merkle.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/merkle/merkleTree.ts","../src/merkle/client.ts"],"names":["hash","StandardMerkleTree"],"mappings":";;;;;;AAyBO,SAAS,gBAAA,CAAiB,SAAiB,KAAA,EAAuB;AACvE,EAAA,MAAM,YAAA,GAAeA,aAAA,CAAK,mBAAA,CAAoB,KAAA,EAAO,OAAO,CAAA;AAC5D,EAAA,OAAOA,cAAK,mBAAA,CAAoB,YAAA,EAAc,OAAO,KAAA,CAAM,QAAA,CAAS,EAAE,CAAC,CAAA;AACzE;AAMO,SAAS,gBAAgB,OAAA,EAAwC;AACtE,EAAA,IAAI,OAAA,CAAQ,WAAW,CAAA,EAAG;AACxB,IAAA,MAAM,IAAI,MAAM,0CAA0C,CAAA;AAAA,EAC5D;AAEA,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAM,CAAC,gBAAA,CAAiB,CAAA,CAAE,OAAA,EAAS,CAAA,CAAE,KAAK,CAAC,CAAC,CAAA;AAExE,EAAA,MAAM,OAAOC,iCAAA,CAAmB,EAAA,CAAG,MAAA,EAAQ,CAAC,SAAS,CAAA,EAAG;AAAA,IACtD,UAAA,EAAY;AAAA,GACb,CAAA;AAED,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,CAAA;AAAA,IACT,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA,EAAY;AAAA,IAClC,OAAA;AAAA,IACA,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,IAAA,EAAM,KAAK,IAAA;AAAK,GAClB;AACF;AAKO,SAAS,QAAA,CACd,QAAA,EACA,OAAA,EACA,KAAA,EACiB;AACjB,EAAA,MAAM,IAAA,GAAOA,iCAAA,CAAmB,IAAA,CAAK,QAAA,CAAS,IAAI,CAAA;AAClD,EAAA,MAAM,SAAA,GAAY,gBAAA,CAAiB,OAAA,EAAS,KAAK,CAAA;AAEjD,EAAA,KAAA,MAAW,CAAC,KAAA,EAAO,IAAI,CAAA,IAAK,IAAA,CAAK,SAAQ,EAAG;AAC1C,IAAA,IAAI,OAAO,IAAA,CAAK,CAAC,CAAW,CAAA,KAAM,MAAA,CAAO,SAAS,CAAA,EAAG;AACnD,MAAA,OAAO,IAAA,CAAK,SAAS,KAAK,CAAA;AAAA,IAC5B;AAAA,EACF;AAEA,EAAA,OAAO,IAAA;AACT;AAKO,SAAS,WAAA,CACd,QAAA,EACA,OAAA,EACA,KAAA,EACA,KAAA,EACS;AACT,EAAA,MAAM,SAAA,GAAY,gBAAA,CAAiB,OAAA,EAAS,KAAK,CAAA;AACjD,EAAA,OAAOA,iCAAA,CAAmB,MAAA;AAAA,IACxB,QAAA,CAAS,IAAA;AAAA,IACT,CAAC,SAAS,CAAA;AAAA,IACV,CAAC,SAAS,CAAA;AAAA,IACV;AAAA,GACF;AACF;AAKO,SAAS,kBAAA,CAAmB,OAAe,KAAA,EAA2B;AAC3E,EAAA,OAAO,CAAC,IAAA,GAAO,KAAA,CAAM,SAAS,EAAE,CAAA,EAAG,GAAG,KAAK,CAAA;AAC7C;AAKO,SAAS,SAAA,CACd,UACA,OAAA,EACoB;AACpB,EAAA,OACE,SAAS,OAAA,CAAQ,IAAA;AAAA,IACf,CAAC,CAAA,KACC,CAAA,CAAE,OAAA,CAAQ,aAAY,KAAM,OAAA,CAAQ,WAAA,EAAY,IAChD,MAAA,CAAO,CAAA,CAAE,OAAO,CAAA,KAAM,OAAO,OAAO;AAAA,GACxC,IAAK,IAAA;AAET;;;ACrGA,IAAM,uBAAA,GAAkD;AAAA,EACtD,UAAA,EAAY,2CAAA;AAAA,EACZ,OAAA,EAAS;AACX,CAAA;AAwEO,IAAM,eAAN,MAAmB;AAAA,EACf,MAAA;AAAA,EAET,YAAY,MAAA,EAA4B;AACtC,IAAA,IAAA,CAAK,SACH,MAAA,CAAO,MAAA,IACP,wBAAwB,MAAA,CAAO,OAAO,KACtC,uBAAA,CAAwB,OAAA;AAAA,EAC5B;AAAA;AAAA,EAGA,MAAM,SAAS,OAAA,EAGkB;AAC/B,IAAA,MAAM,KAAA,GAA6B;AAAA,MACjC,MAAM,EAAC;AAAA,MACP,KAAA,EAAO,CAAA;AAAA,MACP,IAAA,EAAM,CAAA;AAAA,MACN,KAAA,EAAO,EAAA;AAAA,MACP,UAAA,EAAY;AAAA,KACd;AACA,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,IAAI,eAAA,EAAgB;AACnC,MAAA,IAAI,OAAA,EAAS,MAAM,MAAA,CAAO,GAAA,CAAI,QAAQ,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAC1D,MAAA,IAAI,OAAA,EAAS,OAAO,MAAA,CAAO,GAAA,CAAI,SAAS,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAC,CAAA;AAC7D,MAAA,MAAM,EAAA,GAAK,OAAO,QAAA,EAAS;AAC3B,MAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,MAAA,EAAS,EAAA,GAAK,CAAA,CAAA,EAAI,EAAE,CAAA,CAAA,GAAK,EAAE,CAAA,CAAE,CAAA;AACnE,MAAA,IAAI,CAAC,GAAA,CAAI,EAAA,EAAI,OAAO,KAAA;AACpB,MAAA,MAAM,IAAA,GAAO,MAAM,GAAA,CAAI,IAAA,EAAK;AAC5B,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,IAAA,CAAK,IAAA,IAAQ,EAAC;AAAA,QACpB,KAAA,EAAO,KAAK,KAAA,IAAS,CAAA;AAAA,QACrB,IAAA,EAAM,KAAK,IAAA,IAAQ,CAAA;AAAA,QACnB,KAAA,EAAO,KAAK,KAAA,IAAS,EAAA;AAAA,QACrB,UAAA,EAAY,KAAK,UAAA,IAAc;AAAA,OACjC;AAAA,IACF,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,cAAA,CACJ,MAAA,EACA,OAAA,EACoC;AACpC,IAAA,MAAM,KAAA,GAAmC;AAAA,MACvC,MAAM,EAAC;AAAA,MACP,KAAA,EAAO,CAAA;AAAA,MACP,IAAA,EAAM,CAAA;AAAA,MACN,KAAA,EAAO,EAAA;AAAA,MACP,UAAA,EAAY;AAAA,KACd;AACA,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,IAAI,eAAA,EAAgB;AACnC,MAAA,IAAI,OAAA,EAAS,MAAM,MAAA,CAAO,GAAA,CAAI,QAAQ,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAC1D,MAAA,IAAI,OAAA,EAAS,OAAO,MAAA,CAAO,GAAA,CAAI,SAAS,MAAA,CAAO,OAAA,CAAQ,KAAK,CAAC,CAAA;AAC7D,MAAA,MAAM,EAAA,GAAK,OAAO,QAAA,EAAS;AAC3B,MAAA,MAAM,MAAM,MAAM,KAAA;AAAA,QAChB,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,OAAA,EAAU,MAAM,WAAW,EAAA,GAAK,CAAA,CAAA,EAAI,EAAE,CAAA,CAAA,GAAK,EAAE,CAAA;AAAA,OAC7D;AACA,MAAA,IAAI,CAAC,GAAA,CAAI,EAAA,EAAI,OAAO,KAAA;AACpB,MAAA,MAAM,IAAA,GAAO,MAAM,GAAA,CAAI,IAAA,EAAK;AAC5B,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,IAAA,CAAK,IAAA,IAAQ,EAAC;AAAA,QACpB,KAAA,EAAO,KAAK,KAAA,IAAS,CAAA;AAAA,QACrB,IAAA,EAAM,KAAK,IAAA,IAAQ,CAAA;AAAA,QACnB,KAAA,EAAO,KAAK,KAAA,IAAS,EAAA;AAAA,QACrB,UAAA,EAAY,KAAK,UAAA,IAAc;AAAA,OACjC;AAAA,IACF,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,QAAA,CACJ,MAAA,EACA,aAAA,EACqC;AACrC,IAAA,IAAI;AACF,MAAA,MAAM,MAAM,MAAM,KAAA;AAAA,QAChB,CAAA,EAAG,KAAK,MAAM,CAAA,OAAA,EAAU,MAAM,CAAA,OAAA,EAAU,aAAA,CAAc,aAAa,CAAA;AAAA,OACrE;AACA,MAAA,IAAI,CAAC,GAAA,CAAI,EAAA,EAAI,OAAO,IAAA;AACpB,MAAA,OAAO,MAAM,IAAI,IAAA,EAAK;AAAA,IACxB,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,UACJ,OAAA,EACmC;AACnC,IAAA,MAAM,MAAM,MAAM,KAAA,CAAM,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,MAAA,CAAA,EAAU;AAAA,MAC9C,MAAA,EAAQ,MAAA;AAAA,MACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA,EAAmB;AAAA,MAC9C,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,OAAO;AAAA,KAC7B,CAAA;AACD,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,MAAM,IAAA,GAAO,MAAM,GAAA,CAAI,IAAA,EAAK;AAC5B,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,8BAAA,EAAiC,IAAI,CAAA,CAAE,CAAA;AAAA,IACzD;AACA,IAAA,OAAO,MAAM,IAAI,IAAA,EAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,iBAAA,CACE,SACA,gBAAA,EACc;AACd,IAAA,MAAM,IAAA,GAAO,gBAAgB,OAAO,CAAA;AACpC,IAAA,OAAO;AAAA,MACL,IAAA;AAAA,MACA,IAAA,EAAM;AAAA,QACJ,eAAA,EAAiB,gBAAA;AAAA,QACjB,UAAA,EAAY,aAAA;AAAA,QACZ,QAAA,EAAU,CAAC,IAAA,CAAK,IAAI;AAAA;AACtB,KACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,qBAAA,CAAsB,QAAe,gBAAA,EAAyC;AAC5E,IAAA,MAAM,eAAA,GAAkB,OAAO,gBAAgB,CAAA;AAE/C,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,IAAA,CAAK,CAAC,CAAA,KAAW;AACxC,MAAA,IAAI;AACF,QAAA,OAAO,MAAA,CAAO,CAAA,CAAE,YAAY,CAAA,KAAM,eAAA;AAAA,MACpC,CAAA,CAAA,MAAQ;AACN,QAAA,OAAO,KAAA;AAAA,MACT;AAAA,IACF,CAAC,CAAA;AACD,IAAA,IAAI,CAAC,SAAA,EAAW,IAAA,GAAO,CAAC,GAAG,OAAO,IAAA;AAClC,IAAA,OAAO,OAAO,MAAA,CAAO,SAAA,CAAU,IAAA,CAAK,CAAC,CAAC,CAAC,CAAA;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,WAAW,MAAA,EAKqB;AACpC,IAAA,OAAO,KAAK,SAAA,CAAU;AAAA,MACpB,IAAI,MAAA,CAAO,MAAA;AAAA,MACX,MAAM,MAAA,CAAO,IAAA;AAAA,MACb,aAAa,MAAA,CAAO,WAAA;AAAA,MACpB,SAAS,MAAA,CAAO;AAAA,KACjB,CAAA;AAAA,EACH;AACF;AAGO,SAAS,mBAAmB,MAAA,EAA0C;AAC3E,EAAA,OAAO,IAAI,aAAa,MAAM,CAAA;AAChC","file":"merkle.cjs","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/merkle.d.cts

@@ -0,0 +1,151 @@
+interface MerkleEntry {
+    address: string;
+    count: number;
+}
+interface MerkleTreeData {
+    version: 2;
+    createdAt: string;
+    entries: MerkleEntry[];
+    root: string;
+    tree: any;
+}
+/**
+ * Compute the leaf value that gets passed to StandardMerkleTree.
+ * This matches the Cairo contract's leaf computation:
+ *   PedersenTrait::new(0).update(address).update(count).finalize()
+ *
+ * The StandardMerkleTree then applies its own leaf hashing on top:
+ *   H(0, value, 1) using PedersenCHasher
+ */
+declare function computeLeafValue(address: string, count: number): string;
+/**
+ * Build a StandardMerkleTree from entries.
+ * Each leaf is a single felt252 value (the pre-hashed leaf value).
+ */
+declare function buildMerkleTree(entries: MerkleEntry[]): MerkleTreeData;
+/**
+ * Load a tree from saved data and get the proof for an address.
+ */
+declare function getProof(treeData: MerkleTreeData, address: string, count: number): string[] | null;
+/**
+ * Verify a proof against a root (client-side).
+ */
+declare function verifyProof(treeData: MerkleTreeData, address: string, count: number, proof: string[]): boolean;
+/**
+ * Build qualification array for contract calls: [count, ...proof]
+ */
+declare function buildQualification(count: number, proof: string[]): string[];
+/**
+ * Find an entry in the tree by address.
+ */
+declare function findEntry(treeData: MerkleTreeData, address: string): MerkleEntry | null;
+
+/**
+ * MerkleClient — chainId-aware client for the merkle API service.
+ *
+ * Resolves the API URL once at construction time so callers never
+ * need to pass chainId on every request.
+ */
+
+interface MerkleClientConfig {
+    /** Starknet chain ID, e.g. "SN_MAIN" or "SN_SEPOLIA" */
+    chainId: string;
+    /** Override the default API URL for this chain */
+    apiUrl?: string;
+}
+interface MerkleTree {
+    id: number;
+    name: string;
+    description: string;
+    root: string;
+    entryCount: number;
+    createdAt: string;
+}
+interface MerkleTreesResponse {
+    data: MerkleTree[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+interface MerkleProofResponse {
+    address: string;
+    count: number;
+    proof: string[];
+    qualification: string[];
+}
+interface MerkleTreeEntry {
+    address: string;
+    count: number;
+}
+interface MerkleTreeEntriesResponse {
+    data: MerkleTreeEntry[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+interface CreateMerkleTreeRequest {
+    id: number;
+    name: string;
+    description: string;
+    entries: MerkleEntry[];
+}
+interface CreateMerkleTreeResponse {
+    id: number;
+    root: string;
+    entryCount: number;
+}
+interface TreeCalldata {
+    tree: ReturnType<typeof buildMerkleTree>;
+    call: {
+        contractAddress: string;
+        entrypoint: string;
+        calldata: string[];
+    };
+}
+declare class MerkleClient {
+    readonly apiUrl: string;
+    constructor(config: MerkleClientConfig);
+    /** Fetch paginated list of merkle trees. */
+    getTrees(options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<MerkleTreesResponse>;
+    /** Fetch entries for a specific merkle tree. */
+    getTreeEntries(treeId: string | number, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<MerkleTreeEntriesResponse>;
+    /** Fetch a merkle proof for a player address. */
+    getProof(treeId: string | number, playerAddress: string): Promise<MerkleProofResponse | null>;
+    /** Store a merkle tree in the API (after on-chain registration). */
+    storeTree(request: CreateMerkleTreeRequest): Promise<CreateMerkleTreeResponse>;
+    /**
+     * 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: MerkleEntry[], validatorAddress: string): TreeCalldata;
+    /**
+     * Parse the tree ID from transaction receipt events.
+     * Returns null if the event cannot be found.
+     */
+    parseTreeIdFromEvents(events: any[], validatorAddress: string): number | null;
+    /**
+     * Store the tree in the API after on-chain registration.
+     * Pass the tree ID from the on-chain event along with the original entries.
+     */
+    createTree(params: {
+        treeId: number;
+        name: string;
+        description: string;
+        entries: MerkleEntry[];
+    }): Promise<CreateMerkleTreeResponse>;
+}
+/** Factory function for creating a MerkleClient. */
+declare function createMerkleClient(config: MerkleClientConfig): MerkleClient;
+
+export { type CreateMerkleTreeRequest, type CreateMerkleTreeResponse, MerkleClient, type MerkleClientConfig, type MerkleEntry, type MerkleProofResponse, type MerkleTree, type MerkleTreeData, type MerkleTreeEntriesResponse, type MerkleTreeEntry, type MerkleTreesResponse, type TreeCalldata, buildMerkleTree, buildQualification, computeLeafValue, createMerkleClient, findEntry, getProof, verifyProof };

package/dist/merkle.d.ts

@@ -0,0 +1,151 @@
+interface MerkleEntry {
+    address: string;
+    count: number;
+}
+interface MerkleTreeData {
+    version: 2;
+    createdAt: string;
+    entries: MerkleEntry[];
+    root: string;
+    tree: any;
+}
+/**
+ * Compute the leaf value that gets passed to StandardMerkleTree.
+ * This matches the Cairo contract's leaf computation:
+ *   PedersenTrait::new(0).update(address).update(count).finalize()
+ *
+ * The StandardMerkleTree then applies its own leaf hashing on top:
+ *   H(0, value, 1) using PedersenCHasher
+ */
+declare function computeLeafValue(address: string, count: number): string;
+/**
+ * Build a StandardMerkleTree from entries.
+ * Each leaf is a single felt252 value (the pre-hashed leaf value).
+ */
+declare function buildMerkleTree(entries: MerkleEntry[]): MerkleTreeData;
+/**
+ * Load a tree from saved data and get the proof for an address.
+ */
+declare function getProof(treeData: MerkleTreeData, address: string, count: number): string[] | null;
+/**
+ * Verify a proof against a root (client-side).
+ */
+declare function verifyProof(treeData: MerkleTreeData, address: string, count: number, proof: string[]): boolean;
+/**
+ * Build qualification array for contract calls: [count, ...proof]
+ */
+declare function buildQualification(count: number, proof: string[]): string[];
+/**
+ * Find an entry in the tree by address.
+ */
+declare function findEntry(treeData: MerkleTreeData, address: string): MerkleEntry | null;
+
+/**
+ * MerkleClient — chainId-aware client for the merkle API service.
+ *
+ * Resolves the API URL once at construction time so callers never
+ * need to pass chainId on every request.
+ */
+
+interface MerkleClientConfig {
+    /** Starknet chain ID, e.g. "SN_MAIN" or "SN_SEPOLIA" */
+    chainId: string;
+    /** Override the default API URL for this chain */
+    apiUrl?: string;
+}
+interface MerkleTree {
+    id: number;
+    name: string;
+    description: string;
+    root: string;
+    entryCount: number;
+    createdAt: string;
+}
+interface MerkleTreesResponse {
+    data: MerkleTree[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+interface MerkleProofResponse {
+    address: string;
+    count: number;
+    proof: string[];
+    qualification: string[];
+}
+interface MerkleTreeEntry {
+    address: string;
+    count: number;
+}
+interface MerkleTreeEntriesResponse {
+    data: MerkleTreeEntry[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+interface CreateMerkleTreeRequest {
+    id: number;
+    name: string;
+    description: string;
+    entries: MerkleEntry[];
+}
+interface CreateMerkleTreeResponse {
+    id: number;
+    root: string;
+    entryCount: number;
+}
+interface TreeCalldata {
+    tree: ReturnType<typeof buildMerkleTree>;
+    call: {
+        contractAddress: string;
+        entrypoint: string;
+        calldata: string[];
+    };
+}
+declare class MerkleClient {
+    readonly apiUrl: string;
+    constructor(config: MerkleClientConfig);
+    /** Fetch paginated list of merkle trees. */
+    getTrees(options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<MerkleTreesResponse>;
+    /** Fetch entries for a specific merkle tree. */
+    getTreeEntries(treeId: string | number, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<MerkleTreeEntriesResponse>;
+    /** Fetch a merkle proof for a player address. */
+    getProof(treeId: string | number, playerAddress: string): Promise<MerkleProofResponse | null>;
+    /** Store a merkle tree in the API (after on-chain registration). */
+    storeTree(request: CreateMerkleTreeRequest): Promise<CreateMerkleTreeResponse>;
+    /**
+     * 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: MerkleEntry[], validatorAddress: string): TreeCalldata;
+    /**
+     * Parse the tree ID from transaction receipt events.
+     * Returns null if the event cannot be found.
+     */
+    parseTreeIdFromEvents(events: any[], validatorAddress: string): number | null;
+    /**
+     * Store the tree in the API after on-chain registration.
+     * Pass the tree ID from the on-chain event along with the original entries.
+     */
+    createTree(params: {
+        treeId: number;
+        name: string;
+        description: string;
+        entries: MerkleEntry[];
+    }): Promise<CreateMerkleTreeResponse>;
+}
+/** Factory function for creating a MerkleClient. */
+declare function createMerkleClient(config: MerkleClientConfig): MerkleClient;
+
+export { type CreateMerkleTreeRequest, type CreateMerkleTreeResponse, MerkleClient, type MerkleClientConfig, type MerkleEntry, type MerkleProofResponse, type MerkleTree, type MerkleTreeData, type MerkleTreeEntriesResponse, type MerkleTreeEntry, type MerkleTreesResponse, type TreeCalldata, buildMerkleTree, buildQualification, computeLeafValue, createMerkleClient, findEntry, getProof, verifyProof };