@zkp2p/sdk 0.5.2 → 0.5.4

package/README.md

@@ -6,7 +6,7 @@
 
 Stable TypeScript SDK for trustless fiat-to-crypto on Base. ZKP2P combines escrowed on-chain settlement, TLS attestations for payment verification, and API/indexer helpers so makers, takers, wallets, and embedded ramps can ship production-grade fiat liquidity flows without building their own contract or indexing stack.
 
-Current version: `0.5.0`
+Current version: `0.5.2`
 
 ## Why This SDK
 
@@ -73,13 +73,13 @@ const client = new Zkp2pClient({
 - Supported runtime environments: `'production'`, `'preproduction'`, `'staging'`
 - `runtimeEnv` default: `'production'`
 - `rpcUrl`: optional RPC URL override (defaults to wallet's chain RPC)
-- `apiKey`: optional curator-issued API key — used when the SDK auto-fetches `signalIntent()` gating signatures and enables richer authenticated `getQuote()` responses with resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`)
-- `authorizationToken` / `getAuthorizationToken`: optional bearer auth for hybrid client and indexer flows
+- `apiKey`: optional internal curator API key for internal seller verification only
+- `authorizationToken` / `getAuthorizationToken`: optional bearer auth for indexer flows
 - `indexerApiKey`: optional `x-api-key` for indexer proxy auth
 - `indexerUrl` and `baseApiUrl`: override defaults when you are targeting custom deployments
 - `timeouts`: `{ api?: number }` — API timeout in milliseconds (default 15000)
 
-**No API key is required to get started.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, and the rest of the SDK work without `apiKey` or `authorizationToken`. The main tradeoff is that `signalIntent()` only auto-fetches a gating service signature from curator `/v3/intent/sign` when `apiKey` or `authorizationToken` is available; otherwise provide both `gatingServiceSignature` and `signatureExpiration` manually if your integration needs one. Authenticated quotes also include resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`).
+**No external API key is required.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, `signalIntent`, and the rest of the public SDK flows work without `apiKey` or `authorizationToken`. When `baseApiUrl` is configured, `signalIntent()` can auto-fetch a gating service signature from curator `/v3/intent/sign` without auth. Quote responses include resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`) when curator has them.
 
 Indexer defaults by environment:
 

package/dist/{chunk-LPJE2MN7.mjs → chunk-TGMRXUP2.mjs}

@@ -1,3 +1,28 @@
+// src/takerTiers.ts
+var TAKER_TIER_SCHEDULE = [
+  { tier: "PLATINUM", perIntentCapUsd: 5e3, minVolumeUsd: 25e3, maxVolumeUsd: Infinity },
+  { tier: "PRO", perIntentCapUsd: 2500, minVolumeUsd: 1e4, maxVolumeUsd: 24999 },
+  { tier: "PLUS", perIntentCapUsd: 1e3, minVolumeUsd: 2e3, maxVolumeUsd: 9999 },
+  { tier: "PEER", perIntentCapUsd: 250, minVolumeUsd: 500, maxVolumeUsd: 1999 },
+  { tier: "PEASANT", perIntentCapUsd: 100, minVolumeUsd: 0, maxVolumeUsd: 499 }
+];
+var TAKER_TIER_ORDER = [
+  "PEASANT",
+  "PEER",
+  "PLUS",
+  "PRO",
+  "PLATINUM"
+];
+var TAKER_TIER_CAPS = Object.fromEntries(
+  TAKER_TIER_SCHEDULE.map((entry) => [entry.tier, entry.perIntentCapUsd])
+);
+function getNextTakerTier(currentTier) {
+  if (!currentTier) return null;
+  const index = TAKER_TIER_ORDER.indexOf(currentTier);
+  if (index === -1 || index >= TAKER_TIER_ORDER.length - 1) return null;
+  return TAKER_TIER_ORDER[index + 1];
+}
+
 // src/react/hooks/vaultUtils.ts
 var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 var ZERO_RATE_MANAGER_ID = "0x0000000000000000000000000000000000000000000000000000000000000000";
@@ -70,6 +95,6 @@ var prepareSetDelegationTx = async (client, params, referrer) => {
   });
 };
 
-export { ZERO_ADDRESS, ZERO_RATE_MANAGER_ID, asErrorMessage, assertAtomicDelegationSwitchSupport, assertDelegationMethodSupport, classifyDelegationState, getDelegationRoute, isZeroRateManagerId, normalizeRateManagerId, normalizeRegistry, prepareClearDelegationTx, prepareSetDelegationTx };
-//# sourceMappingURL=chunk-LPJE2MN7.mjs.map
-//# sourceMappingURL=chunk-LPJE2MN7.mjs.map
+export { TAKER_TIER_CAPS, TAKER_TIER_ORDER, TAKER_TIER_SCHEDULE, ZERO_ADDRESS, ZERO_RATE_MANAGER_ID, asErrorMessage, assertAtomicDelegationSwitchSupport, assertDelegationMethodSupport, classifyDelegationState, getDelegationRoute, getNextTakerTier, isZeroRateManagerId, normalizeRateManagerId, normalizeRegistry, prepareClearDelegationTx, prepareSetDelegationTx };
+//# sourceMappingURL=chunk-TGMRXUP2.mjs.map
+//# sourceMappingURL=chunk-TGMRXUP2.mjs.map

package/dist/chunk-TGMRXUP2.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/takerTiers.ts","../src/react/hooks/vaultUtils.ts"],"names":[],"mappings":"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","file":"chunk-TGMRXUP2.mjs","sourcesContent":["import type { TakerTierLevel } from './types';\n\n/**\n * Canonical taker tier schedule — the single client-side source of truth for\n * per-intent caps and volume thresholds. Mirrors the curator's authoritative\n * tier engine (curator `src/common/services/tier/tierConstants.ts`), which is\n * what the backend actually enforces.\n *\n * A user's *live* cap (after lock-score penalties and per-platform risk\n * multipliers) always comes from the taker-tier API payload\n * (`TakerTier.perIntentCapBaseUnits` / `nextTierMaxOrderSizeDisplay`). This\n * static schedule is for reference displays that must show every tier at once —\n * the Fees & Tiers ladder — and the forward-looking \"next tier cap\" hint.\n *\n * Ordered highest tier → lowest (PLATINUM first) to match UI display order.\n * PEER_PRESIDENT is invite-only and excluded from the volume ladder.\n */\nexport interface TakerTierScheduleEntry {\n  tier: TakerTierLevel;\n  /** Per-intent order cap in whole USD (base, before platform risk multipliers). */\n  perIntentCapUsd: number;\n  /** Inclusive lower bound of lifetime volume (USD) that qualifies for this tier. */\n  minVolumeUsd: number;\n  /** Inclusive upper bound of lifetime volume (USD); `Infinity` for the top tier. */\n  maxVolumeUsd: number;\n}\n\nexport const TAKER_TIER_SCHEDULE: readonly TakerTierScheduleEntry[] = [\n  { tier: 'PLATINUM', perIntentCapUsd: 5000, minVolumeUsd: 25000, maxVolumeUsd: Infinity },\n  { tier: 'PRO', perIntentCapUsd: 2500, minVolumeUsd: 10000, maxVolumeUsd: 24999 },\n  { tier: 'PLUS', perIntentCapUsd: 1000, minVolumeUsd: 2000, maxVolumeUsd: 9999 },\n  { tier: 'PEER', perIntentCapUsd: 250, minVolumeUsd: 500, maxVolumeUsd: 1999 },\n  { tier: 'PEASANT', perIntentCapUsd: 100, minVolumeUsd: 0, maxVolumeUsd: 499 },\n];\n\n/** Volume-based tier order, lowest → highest, for next-tier progression. */\nexport const TAKER_TIER_ORDER: readonly TakerTierLevel[] = [\n  'PEASANT',\n  'PEER',\n  'PLUS',\n  'PRO',\n  'PLATINUM',\n];\n\n/** Per-intent caps (whole USD) keyed by tier, derived from the schedule. */\nexport const TAKER_TIER_CAPS: Readonly<Record<string, number>> = Object.fromEntries(\n  TAKER_TIER_SCHEDULE.map((entry) => [entry.tier, entry.perIntentCapUsd]),\n);\n\n/** The next tier up from `currentTier`, or `null` at the top / for unknown tiers. */\nexport function getNextTakerTier(currentTier: string | undefined): TakerTierLevel | null {\n  if (!currentTier) return null;\n  const index = TAKER_TIER_ORDER.indexOf(currentTier as TakerTierLevel);\n  if (index === -1 || index >= TAKER_TIER_ORDER.length - 1) return null;\n  return TAKER_TIER_ORDER[index + 1];\n}\n","import type { Address, Hex } from 'viem';\nimport type { PreparedTransaction } from '../../types/prepared';\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\nexport const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000' as const;\nexport const ZERO_RATE_MANAGER_ID =\n  '0x0000000000000000000000000000000000000000000000000000000000000000' as const;\n\n// ---------------------------------------------------------------------------\n// Normalizers\n// ---------------------------------------------------------------------------\n\nexport const normalizeRateManagerId = (value?: string | null): string =>\n  (value ?? ZERO_RATE_MANAGER_ID).toLowerCase();\n\nexport const normalizeRegistry = (value?: string | null): string =>\n  (value ?? ZERO_ADDRESS).toLowerCase();\n\nexport const isZeroRateManagerId = (value?: string | null): boolean => {\n  if (!value) return true;\n  const normalized = value.toLowerCase();\n  return normalized === ZERO_ADDRESS || normalized === ZERO_RATE_MANAGER_ID;\n};\n\n// ---------------------------------------------------------------------------\n// Error helper\n// ---------------------------------------------------------------------------\n\nexport const asErrorMessage = (error: unknown): string => {\n  if (!error) return 'Unknown error';\n  if (error instanceof Error) return error.message;\n  if (typeof error === 'string') return error;\n\n  const anyErr = error as Record<string, unknown>;\n  if (typeof anyErr.shortMessage === 'string') return anyErr.shortMessage;\n  if (typeof anyErr.details === 'string') return anyErr.details;\n  if (typeof anyErr.message === 'string') return anyErr.message;\n\n  try {\n    return JSON.stringify(error);\n  } catch {\n    return String(error);\n  }\n};\n\n// ---------------------------------------------------------------------------\n// Delegation state classification\n// ---------------------------------------------------------------------------\n\nexport type DelegationState = 'delegated_here' | 'delegated_elsewhere' | 'not_delegated';\n\n/**\n * Classify whether a deposit is delegated to the target vault, delegated\n * elsewhere, or not delegated at all.\n *\n * @param currentRateManagerId    The deposit's current rateManagerId (from indexer)\n * @param currentRegistry         The deposit's current rateManagerAddress / registry (from indexer)\n * @param targetRateManagerId     The vault's rateManagerId we're comparing against\n * @param targetRegistry          The vault's registry address we're comparing against\n */\nexport const classifyDelegationState = (\n  currentRateManagerId: string | null | undefined,\n  currentRegistry: string | null | undefined,\n  targetRateManagerId: string,\n  targetRegistry: string | null | undefined,\n): DelegationState => {\n  if (isZeroRateManagerId(currentRateManagerId)) {\n    return 'not_delegated';\n  }\n\n  const normalizedCurrent = normalizeRateManagerId(currentRateManagerId);\n  const normalizedTarget = targetRateManagerId.toLowerCase();\n  const normalizedCurrentRegistry = normalizeRegistry(currentRegistry);\n  const normalizedTargetRegistry = targetRegistry ? targetRegistry.toLowerCase() : '';\n\n  const idsMatch = normalizedCurrent === normalizedTarget;\n  const registryMatches = normalizedTargetRegistry\n    ? normalizedCurrentRegistry === normalizedTargetRegistry\n    : true;\n\n  if (idsMatch && registryMatches) {\n    return 'delegated_here';\n  }\n\n  return 'delegated_elsewhere';\n};\n\nexport const assertAtomicDelegationSwitchSupport = (\n  requiresSwitch: boolean,\n  canBatch: boolean,\n): void => {\n  if (!requiresSwitch || canBatch) return;\n  throw new Error(\n    'Switching delegation targets requires smart-account batching. Clear the existing delegation first.',\n  );\n};\n\n// ---------------------------------------------------------------------------\n// Contract routing\n// ---------------------------------------------------------------------------\n\nexport type DelegationRoute = 'v2';\n\nexport const getDelegationRoute = (_client: unknown, _escrow: Address): DelegationRoute => 'v2';\n\ntype DelegationMethodSupportClient = Partial<\n  Record<'setRateManager' | 'clearRateManager', { prepare?: unknown }>\n>;\n\nexport const assertDelegationMethodSupport = (\n  client: DelegationMethodSupportClient,\n  _route: DelegationRoute,\n  action: 'set' | 'clear',\n): void => {\n  const method = action === 'set' ? 'setRateManager' : 'clearRateManager';\n  if (client?.[method]?.prepare) return;\n  throw new Error(`Delegation requires SDK ${method} support`);\n};\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface DelegationDepositTarget {\n  compositeDepositId: string;\n  escrow: Address;\n  depositId: bigint;\n  currentRateManagerId?: string | null;\n  currentRateManagerRegistry?: string | null;\n}\n\nexport interface BatchResult {\n  hashes: string[];\n  failed: Array<{ compositeDepositId: string; error: string }>;\n}\n\n/**\n * Callback the consumer provides for sending a single prepared transaction.\n * Returns the transaction hash.\n */\nexport type SendTransactionFn = (tx: { to: Address; data: Hex; value?: bigint }) => Promise<string>;\n\n/**\n * Optional callback for batching multiple calls in a single user operation\n * (e.g. via a smart account). If not provided, transactions are sent\n * sequentially via sendTransaction.\n */\nexport type SendBatchFn = (\n  txs: Array<{ to: Address; data: Hex; value?: bigint }>,\n) => Promise<string>;\n\n// ---------------------------------------------------------------------------\n// Prepare helpers (used internally by hooks)\n// ---------------------------------------------------------------------------\n\nexport const prepareClearDelegationTx = async (\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  client: any,\n  params: { escrow: Address; depositId: bigint },\n  referrer?: string | string[],\n): Promise<PreparedTransaction> => {\n  const route = getDelegationRoute(client, params.escrow);\n  assertDelegationMethodSupport(client, route, 'clear');\n  return client.clearRateManager.prepare({\n    escrowAddress: params.escrow,\n    depositId: params.depositId,\n    ...(referrer ? { txOverrides: { referrer } } : {}),\n  });\n};\n\nexport const prepareSetDelegationTx = async (\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  client: any,\n  params: {\n    escrow: Address;\n    depositId: bigint;\n    registry: Address;\n    rateManagerId: Hex;\n  },\n  referrer?: string | string[],\n): Promise<PreparedTransaction> => {\n  const route = getDelegationRoute(client, params.escrow);\n  assertDelegationMethodSupport(client, route, 'set');\n  return client.setRateManager.prepare({\n    escrowAddress: params.escrow,\n    depositId: params.depositId,\n    rateManagerAddress: params.registry,\n    rateManagerId: params.rateManagerId,\n    ...(referrer ? { txOverrides: { referrer } } : {}),\n  });\n};\n"]}