@provable-games/metagame-sdk 0.1.3 → 0.1.4

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var starknet = require('starknet');
+var strkMerkleTree = require('@ericnordelo/strk-merkle-tree');
 
 // src/types/extensions.ts
 var QualifyingMode = /* @__PURE__ */ ((QualifyingMode2) => {
@@ -477,12 +478,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",
@@ -490,7 +492,9 @@ var EXTENSION_ADDRESSES = {
     opusTrovesValidator: "0x0604bc0d54727f439786c65d7dc6f7d46de1aba7e129ef9caf65fef111a1644e",
     snapshotValidator: "0x03e6820e9e1cfb5c22465a86f469c651355f05397e29fc94de8e832d5f3d8ede",
     zkPassportValidator: "0x01a25f04c8a39da7bb37adcc53d595fde9e60702611d15b1c498df0657001479",
-    governanceValidator: ""
+    governanceValidator: "",
+    // placeholder until deployed
+    merkleValidator: ""
     // placeholder until deployed
   }
 };
@@ -555,6 +559,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) {
@@ -625,6 +632,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) {
@@ -652,6 +665,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 };
   }
@@ -1012,6 +1029,285 @@ function calculatePaidPlaces(sponsoredPrizes, entryFeeDistributionCount) {
   return Math.max(maxSponsoredPosition, entryFeeDistributionCount);
 }
 
+// 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 = 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_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);
+}
+
+exports.MetagameClient = MetagameClient;
 exports.QualifyingMode = QualifyingMode;
 exports.aggregatePrizesByPosition = aggregatePrizesByPosition;
 exports.aggregatePrizesBySponsor = aggregatePrizesBySponsor;
@@ -1031,11 +1327,16 @@ exports.calculatePayouts = calculatePayouts;
 exports.calculatePrizeValue = calculatePrizeValue;
 exports.calculateTotalPrizeValueUSD = calculateTotalPrizeValueUSD;
 exports.computeStatus = computeStatus;
+exports.createMerkleTree = createMerkleTree;
+exports.createMetagameClient = createMetagameClient;
 exports.displayAddress = displayAddress;
 exports.distributePool = distributePool;
 exports.evaluateExtensionQualification = evaluateExtensionQualification;
 exports.evaluateQualification = evaluateQualification;
 exports.evaluateTokenQualification = evaluateTokenQualification;
+exports.fetchMerkleProof = fetchMerkleProof;
+exports.fetchMerkleTreeEntries = fetchMerkleTreeEntries;
+exports.fetchMerkleTrees = fetchMerkleTrees;
 exports.filterClaimablePrizes = filterClaimablePrizes;
 exports.filterZeroPrizes = filterZeroPrizes;
 exports.findAllBannableEntries = findAllBannableEntries;
@@ -1048,6 +1349,7 @@ exports.formatTime = formatTime;
 exports.formatTokenAmount = formatTokenAmount;
 exports.formatUsdValue = formatUsdValue;
 exports.getExtensionAddresses = getExtensionAddresses;
+exports.getMerkleApiUrl = getMerkleApiUrl;
 exports.getOpusSupportedAssets = getOpusSupportedAssets;
 exports.getOrdinalSuffix = getOrdinalSuffix;
 exports.getQualifyingModeInfo = getQualifyingModeInfo;
@@ -1061,11 +1363,13 @@ exports.padAddress = padAddress;
 exports.parseERC20BalanceValidatorConfig = parseERC20BalanceValidatorConfig;
 exports.parseExtensionConfig = parseExtensionConfig;
 exports.parseGovernanceValidatorConfig = parseGovernanceValidatorConfig;
+exports.parseMerkleValidatorConfig = parseMerkleValidatorConfig;
 exports.parseNFTBulkInput = parseNFTBulkInput;
 exports.parseOpusTrovesValidatorConfig = parseOpusTrovesValidatorConfig;
 exports.parseSnapshotValidatorConfig = parseSnapshotValidatorConfig;
 exports.parseTournamentValidatorConfig = parseTournamentValidatorConfig;
 exports.parseZkPassportValidatorConfig = parseZkPassportValidatorConfig;
 exports.resolveTournamentQualifications = resolveTournamentQualifications;
+exports.setMerkleApiUrl = setMerkleApiUrl;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map