@provable-games/metagame-sdk 0.1.2 → 0.1.4

package/dist/react.d.cts

@@ -1,7 +1,39 @@
-import { s as Token, S as StatusTimestamps, a as StatusResult, l as Participant, P as Prize, m as PositionPrizeGroup, j as EntryFeeShares, D as DistributionType, h as EntryFeeBreakdown, g as QualificationProof, f as EntryRequirementVariant, T as TournamentValidatorConfig, e as QualificationResult, O as OpusTrovesValidatorConfig } from './prizeAggregation-CHwIJzXr.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { m as MetagameClientConfig, l as MetagameClient, u as Token, S as StatusTimestamps, a as StatusResult, n as Participant, P as Prize, o as PositionPrizeGroup, j as EntryFeeShares, D as DistributionType, h as EntryFeeBreakdown, g as QualificationProof, f as EntryRequirementVariant, T as TournamentValidatorConfig, e as QualificationResult, O as OpusTrovesValidatorConfig } from './client-CcoKJS8i.cjs';
+import { MerkleTree, MerkleProofResponse } from './merkle.cjs';
 import { S as StarknetCallProvider } from './extensions-BskkhEHk.cjs';
 import 'starknet';
 
+interface MetagameProviderProps extends MetagameClientConfig {
+    children: ReactNode;
+}
+declare function MetagameProvider({ children, ...config }: MetagameProviderProps): react_jsx_runtime.JSX.Element;
+declare function useMetagameClient(): MetagameClient;
+
+interface UseMerkleTreesOptions {
+    page?: number;
+    limit?: number;
+}
+interface UseMerkleTreesReturn {
+    trees: MerkleTree[];
+    total: number;
+    totalPages: number;
+    page: number;
+    isLoading: boolean;
+}
+declare function useMerkleTrees(options?: UseMerkleTreesOptions): UseMerkleTreesReturn;
+
+interface UseMerkleProofReturn {
+    proof: MerkleProofResponse | null;
+    isLoading: boolean;
+}
+/**
+ * Fetch a merkle proof for a player address.
+ * Returns null when treeId or playerAddress is falsy (skips the fetch).
+ */
+declare function useMerkleProof(treeId: string | number | undefined, playerAddress: string | undefined): UseMerkleProofReturn;
+
 declare function useDebounce<T>(value: T, delay: number): T;
 
 interface UsePaginationOptions {
@@ -224,7 +256,9 @@ declare function useEntryQualification(options: UseEntryQualificationOptions): U
 /**
  * Hook to check extension qualification and entries left for multiple proofs.
  *
- * Ported from budokan — accepts a provider instead of relying on app-specific hooks.
+ * Generic across all extension types — each extension provides its own proof
+ * format. The hook simply passes the proof to `entries_left` on the contract
+ * and reports results.
  */
 
 /** A single qualification method for an extension */
@@ -233,13 +267,7 @@ interface ExtensionQualification {
     proof: string[];
     entriesLeft: number;
     label?: string;
-    metadata?: {
-        tournamentId?: string;
-        tournamentName?: string;
-        tokenId?: string;
-        position?: number;
-        [key: string]: unknown;
-    };
+    metadata?: Record<string, unknown>;
 }
 /** Result from extension qualification check */
 interface ExtensionQualificationResult {
@@ -249,24 +277,31 @@ interface ExtensionQualificationResult {
     loading: boolean;
     error: Error | null;
 }
-/** Input for building qualifications — tournament validator specific */
-interface TournamentValidatorInput {
-    tournamentId: string;
-    tokenId: string;
-    position: number;
-    tournamentName?: string;
+/**
+ * A potential qualification to check against the extension contract.
+ * The proof format is extension-specific — the SDK doesn't interpret it.
+ */
+interface QualificationInput {
+    /** Unique ID for this qualification method */
+    id: string;
+    /** Raw proof data (felt252 array) to pass to entries_left */
+    proof: string[];
+    /** Human-readable label for display */
+    label?: string;
+    /** Additional metadata for display */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Check extension qualification and entries left for multiple proofs.
  *
  * @param provider - Starknet RPC provider (or null to disable)
  * @param extensionAddress - The extension contract address
- * @param contextId - The metagame event ID (tournament ID, etc.)
+ * @param contextId - The metagame context ID
  * @param playerAddress - The player's address
  * @param qualificationInputs - Potential qualifications to check
  * @param enabled - Whether to run the check (default: true)
  */
-declare const useExtensionQualification: (provider: StarknetCallProvider | null, extensionAddress: string | undefined, contextId: string | undefined, playerAddress: string | undefined, qualificationInputs: TournamentValidatorInput[], enabled?: boolean) => ExtensionQualificationResult;
+declare const useExtensionQualification: (provider: StarknetCallProvider | null, extensionAddress: string | undefined, contextId: string | undefined, playerAddress: string | undefined, qualificationInputs: QualificationInput[], enabled?: boolean) => ExtensionQualificationResult;
 
 /**
  * Hook to calculate bannable entries for Opus Troves extension.
@@ -297,4 +332,4 @@ declare const useOpusTrovesBannableEntries: (provider: StarknetCallProvider | nu
     owner?: string;
 }>, config: OpusTrovesValidatorConfig | undefined, enabled: boolean) => UseOpusTrovesBannableEntriesResult;
 
-export { type CheckedExtensionQualification, type ExtensionQualification, type ExtensionQualificationResult, type QualificationMethod, type TournamentValidatorInput, type UseEntryFeePreviewOptions, type UseEntryFeePreviewReturn, type UseEntryQualificationOptions, type UseEntryQualificationReturn, type UseOpusTrovesBannableEntriesResult, type UsePaginationOptions, type UsePaginationReturn, type UsePrizeTableOptions, type UsePrizeTableReturn, type UseScoreTableOptions, type UseScoreTableReturn, type UseSearchFilterOptions, type UseSearchFilterReturn, type UseTokenSelectorOptions, type UseTokenSelectorReturn, useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };
+export { type CheckedExtensionQualification, type ExtensionQualification, type ExtensionQualificationResult, MetagameProvider, type MetagameProviderProps, type QualificationInput, type QualificationMethod, type UseEntryFeePreviewOptions, type UseEntryFeePreviewReturn, type UseEntryQualificationOptions, type UseEntryQualificationReturn, type UseMerkleProofReturn, type UseMerkleTreesOptions, type UseMerkleTreesReturn, type UseOpusTrovesBannableEntriesResult, type UsePaginationOptions, type UsePaginationReturn, type UsePrizeTableOptions, type UsePrizeTableReturn, type UseScoreTableOptions, type UseScoreTableReturn, type UseSearchFilterOptions, type UseSearchFilterReturn, type UseTokenSelectorOptions, type UseTokenSelectorReturn, useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useMerkleProof, useMerkleTrees, useMetagameClient, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };

package/dist/react.d.ts

@@ -1,7 +1,39 @@
-import { s as Token, S as StatusTimestamps, a as StatusResult, l as Participant, P as Prize, m as PositionPrizeGroup, j as EntryFeeShares, D as DistributionType, h as EntryFeeBreakdown, g as QualificationProof, f as EntryRequirementVariant, T as TournamentValidatorConfig, e as QualificationResult, O as OpusTrovesValidatorConfig } from './prizeAggregation-CHwIJzXr.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { m as MetagameClientConfig, l as MetagameClient, u as Token, S as StatusTimestamps, a as StatusResult, n as Participant, P as Prize, o as PositionPrizeGroup, j as EntryFeeShares, D as DistributionType, h as EntryFeeBreakdown, g as QualificationProof, f as EntryRequirementVariant, T as TournamentValidatorConfig, e as QualificationResult, O as OpusTrovesValidatorConfig } from './client-CD-q6Alx.js';
+import { MerkleTree, MerkleProofResponse } from './merkle.js';
 import { S as StarknetCallProvider } from './extensions-BskkhEHk.js';
 import 'starknet';
 
+interface MetagameProviderProps extends MetagameClientConfig {
+    children: ReactNode;
+}
+declare function MetagameProvider({ children, ...config }: MetagameProviderProps): react_jsx_runtime.JSX.Element;
+declare function useMetagameClient(): MetagameClient;
+
+interface UseMerkleTreesOptions {
+    page?: number;
+    limit?: number;
+}
+interface UseMerkleTreesReturn {
+    trees: MerkleTree[];
+    total: number;
+    totalPages: number;
+    page: number;
+    isLoading: boolean;
+}
+declare function useMerkleTrees(options?: UseMerkleTreesOptions): UseMerkleTreesReturn;
+
+interface UseMerkleProofReturn {
+    proof: MerkleProofResponse | null;
+    isLoading: boolean;
+}
+/**
+ * Fetch a merkle proof for a player address.
+ * Returns null when treeId or playerAddress is falsy (skips the fetch).
+ */
+declare function useMerkleProof(treeId: string | number | undefined, playerAddress: string | undefined): UseMerkleProofReturn;
+
 declare function useDebounce<T>(value: T, delay: number): T;
 
 interface UsePaginationOptions {
@@ -224,7 +256,9 @@ declare function useEntryQualification(options: UseEntryQualificationOptions): U
 /**
  * Hook to check extension qualification and entries left for multiple proofs.
  *
- * Ported from budokan — accepts a provider instead of relying on app-specific hooks.
+ * Generic across all extension types — each extension provides its own proof
+ * format. The hook simply passes the proof to `entries_left` on the contract
+ * and reports results.
  */
 
 /** A single qualification method for an extension */
@@ -233,13 +267,7 @@ interface ExtensionQualification {
     proof: string[];
     entriesLeft: number;
     label?: string;
-    metadata?: {
-        tournamentId?: string;
-        tournamentName?: string;
-        tokenId?: string;
-        position?: number;
-        [key: string]: unknown;
-    };
+    metadata?: Record<string, unknown>;
 }
 /** Result from extension qualification check */
 interface ExtensionQualificationResult {
@@ -249,24 +277,31 @@ interface ExtensionQualificationResult {
     loading: boolean;
     error: Error | null;
 }
-/** Input for building qualifications — tournament validator specific */
-interface TournamentValidatorInput {
-    tournamentId: string;
-    tokenId: string;
-    position: number;
-    tournamentName?: string;
+/**
+ * A potential qualification to check against the extension contract.
+ * The proof format is extension-specific — the SDK doesn't interpret it.
+ */
+interface QualificationInput {
+    /** Unique ID for this qualification method */
+    id: string;
+    /** Raw proof data (felt252 array) to pass to entries_left */
+    proof: string[];
+    /** Human-readable label for display */
+    label?: string;
+    /** Additional metadata for display */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Check extension qualification and entries left for multiple proofs.
  *
  * @param provider - Starknet RPC provider (or null to disable)
  * @param extensionAddress - The extension contract address
- * @param contextId - The metagame event ID (tournament ID, etc.)
+ * @param contextId - The metagame context ID
  * @param playerAddress - The player's address
  * @param qualificationInputs - Potential qualifications to check
  * @param enabled - Whether to run the check (default: true)
  */
-declare const useExtensionQualification: (provider: StarknetCallProvider | null, extensionAddress: string | undefined, contextId: string | undefined, playerAddress: string | undefined, qualificationInputs: TournamentValidatorInput[], enabled?: boolean) => ExtensionQualificationResult;
+declare const useExtensionQualification: (provider: StarknetCallProvider | null, extensionAddress: string | undefined, contextId: string | undefined, playerAddress: string | undefined, qualificationInputs: QualificationInput[], enabled?: boolean) => ExtensionQualificationResult;
 
 /**
  * Hook to calculate bannable entries for Opus Troves extension.
@@ -297,4 +332,4 @@ declare const useOpusTrovesBannableEntries: (provider: StarknetCallProvider | nu
     owner?: string;
 }>, config: OpusTrovesValidatorConfig | undefined, enabled: boolean) => UseOpusTrovesBannableEntriesResult;
 
-export { type CheckedExtensionQualification, type ExtensionQualification, type ExtensionQualificationResult, type QualificationMethod, type TournamentValidatorInput, type UseEntryFeePreviewOptions, type UseEntryFeePreviewReturn, type UseEntryQualificationOptions, type UseEntryQualificationReturn, type UseOpusTrovesBannableEntriesResult, type UsePaginationOptions, type UsePaginationReturn, type UsePrizeTableOptions, type UsePrizeTableReturn, type UseScoreTableOptions, type UseScoreTableReturn, type UseSearchFilterOptions, type UseSearchFilterReturn, type UseTokenSelectorOptions, type UseTokenSelectorReturn, useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };
+export { type CheckedExtensionQualification, type ExtensionQualification, type ExtensionQualificationResult, MetagameProvider, type MetagameProviderProps, type QualificationInput, type QualificationMethod, type UseEntryFeePreviewOptions, type UseEntryFeePreviewReturn, type UseEntryQualificationOptions, type UseEntryQualificationReturn, type UseMerkleProofReturn, type UseMerkleTreesOptions, type UseMerkleTreesReturn, type UseOpusTrovesBannableEntriesResult, type UsePaginationOptions, type UsePaginationReturn, type UsePrizeTableOptions, type UsePrizeTableReturn, type UseScoreTableOptions, type UseScoreTableReturn, type UseSearchFilterOptions, type UseSearchFilterReturn, type UseTokenSelectorOptions, type UseTokenSelectorReturn, useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useMerkleProof, useMerkleTrees, useMetagameClient, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };

package/dist/react.js

@@ -1,7 +1,238 @@
-import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
-import { CallData } from 'starknet';
+import { createContext, useMemo, useContext, useState, useEffect, useCallback, useRef } from 'react';
+import { StandardMerkleTree } from '@ericnordelo/strk-merkle-tree';
+import { CallData, hash } from 'starknet';
+import { jsx } from 'react/jsx-runtime';
 
-// src/react/useDebounce.ts
+// src/react/MetagameProvider.tsx
+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_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 = createContext(null);
+function MetagameProvider({
+  children,
+  ...config
+}) {
+  const client = useMemo(
+    () => createMetagameClient(config),
+    [config.chainId, config.merkleApiUrl]
+  );
+  return /* @__PURE__ */ jsx(MetagameContext.Provider, { value: client, children });
+}
+function useMetagameClient() {
+  const client = 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] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+  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] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
+  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] = useState(value);
   useEffect(() => {
@@ -700,11 +931,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 = useRef("");
@@ -727,36 +954,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;
@@ -901,6 +1118,6 @@ var useOpusTrovesBannableEntries = (provider, games, config, enabled) => {
   };
 };
 
-export { useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };
+export { MetagameProvider, useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useMerkleProof, useMerkleTrees, useMetagameClient, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map