@zkp2p/cash 0.1.0-dev.0

package/dist/index.cjs

@@ -0,0 +1,1572 @@
+'use strict';
+
+var viem = require('viem');
+var chains = require('viem/chains');
+var sdk = require('@zkp2p/sdk');
+var zod = require('zod');
+
+// src/client/createCashClient.ts
+
+// src/engine/constants.ts
+var BASE_CHAIN_ID = 8453;
+var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+var USDC_DECIMALS = 6;
+var MARKET_SPREAD_BPS = 0;
+var ORACLE_MIN_CONVERSION_RATE_SENTINEL = 1n;
+var CASH_ORDER_STATUSES = [
+  "SIGNALED",
+  "FULFILLED",
+  "PRUNED",
+  "MANUALLY_RELEASED"
+];
+var CASH_ORDER_POLL_INTERVAL_MS = 5e3;
+var CASH_RETAIN_ON_EMPTY = false;
+function isMarketRateSupported(currency, adapters) {
+  return sdk.getSpreadOracleConfig(currency, adapters) != null;
+}
+function buildMarketRateCurrencyOverride(currency, adapters) {
+  const code = sdk.currencyInfo[currency]?.currencyCodeHash;
+  const oracle = sdk.getSpreadOracleConfig(currency, adapters);
+  if (!code || !oracle) return null;
+  return {
+    code,
+    minConversionRate: ORACLE_MIN_CONVERSION_RATE_SENTINEL,
+    oracleRateConfig: {
+      adapter: oracle.adapter,
+      adapterConfig: oracle.adapterConfig,
+      spreadBps: MARKET_SPREAD_BPS,
+      maxStaleness: oracle.maxStaleness
+    }
+  };
+}
+var DEFAULT_MIN_ORDER_FLOOR = 1000000n;
+function buildIntentAmountRange(amount) {
+  if (amount <= 0n) throw new Error("Cash-out amount must be positive");
+  const min = amount < DEFAULT_MIN_ORDER_FLOOR ? amount : DEFAULT_MIN_ORDER_FLOOR;
+  return { min, max: amount };
+}
+async function prepareCashDepositParams(client, input, adapters) {
+  const { payouts } = input;
+  if (!payouts.length) throw new Error("At least one payout is required");
+  const chainId = client.chainId;
+  const runtimeEnv = client.runtimeEnv;
+  const catalog = sdk.getPaymentMethodsCatalog(chainId, runtimeEnv);
+  const intentGatingService = sdk.getGatingServiceAddress(chainId, runtimeEnv);
+  for (const payout of payouts) {
+    if (!isMarketRateSupported(payout.currency, adapters)) {
+      throw new Error(
+        `${payout.currency} has no live market-rate oracle feed; Peer Cash supports market-rate currencies only.`
+      );
+    }
+  }
+  const processorNames = payouts.map((p) => p.processorName);
+  const { hashedOnchainIds } = await client.registerPayeeDetails({
+    processorNames,
+    payeeData: payouts.map((p) => p.payeeData)
+  });
+  if (hashedOnchainIds.length !== payouts.length) {
+    throw new Error("Payee registration returned an unexpected number of hashes");
+  }
+  const paymentMethodsOverride = processorNames.map(
+    (name) => sdk.resolvePaymentMethodHashFromCatalog(name, catalog)
+  );
+  const paymentMethodDataOverride = hashedOnchainIds.map((hid) => ({
+    intentGatingService,
+    payeeDetails: hid,
+    data: "0x"
+  }));
+  const currenciesOverride = payouts.map((p) => {
+    const tuple = buildMarketRateCurrencyOverride(p.currency, adapters);
+    if (!tuple) throw new Error(`Failed to build market-rate config for ${p.currency}`);
+    return [tuple];
+  });
+  const conversionRates = payouts.map((p) => [
+    { currency: p.currency, conversionRate: ORACLE_MIN_CONVERSION_RATE_SENTINEL.toString() }
+  ]);
+  const intentAmountRange = input.intentAmountRange ?? buildIntentAmountRange(input.amount);
+  return {
+    token: input.token ?? BASE_USDC_ADDRESS,
+    amount: input.amount,
+    intentAmountRange,
+    processorNames,
+    conversionRates,
+    paymentMethodsOverride,
+    paymentMethodDataOverride,
+    currenciesOverride,
+    retainOnEmpty: CASH_RETAIN_ON_EMPTY
+  };
+}
+
+// src/internal/convert.ts
+function toBigInt(value) {
+  return toBigIntOrUndefined(value) ?? 0n;
+}
+function toBigIntOrUndefined(value) {
+  if (value === null || value === void 0 || value === "") return void 0;
+  try {
+    return BigInt(typeof value === "number" ? Math.trunc(value) : String(value));
+  } catch {
+    return void 0;
+  }
+}
+
+// src/engine/amounts.ts
+function usdc(amount) {
+  const text = typeof amount === "number" ? amount.toString() : amount.trim();
+  if (!/^\d+(\.\d+)?$/.test(text)) {
+    throw new Error(`Invalid USDC amount: '${amount}'`);
+  }
+  const [whole = "0", frac = ""] = text.split(".");
+  if (frac.length > USDC_DECIMALS) {
+    throw new Error(`USDC has ${USDC_DECIMALS} decimals; '${amount}' has too many`);
+  }
+  return BigInt(whole) * 10n ** BigInt(USDC_DECIMALS) + BigInt(frac.padEnd(USDC_DECIMALS, "0") || "0");
+}
+function formatUsdc(amount) {
+  const negative = amount < 0n;
+  const abs = negative ? -amount : amount;
+  const whole = abs / 10n ** BigInt(USDC_DECIMALS);
+  const frac = (abs % 10n ** BigInt(USDC_DECIMALS)).toString().padStart(USDC_DECIMALS, "0");
+  const trimmed = frac.replace(/0+$/, "");
+  return `${negative ? "-" : ""}${whole}${trimmed ? `.${trimmed}` : ""}`;
+}
+var RATE_PRECISION = 10n ** 18n;
+function fiatFromUsdc(amount, conversionRate) {
+  const raw = amount * conversionRate / RATE_PRECISION;
+  const penny = 10n ** BigInt(USDC_DECIMALS - 2);
+  const remainder = raw % penny;
+  return remainder > 0n ? raw - remainder + penny : raw;
+}
+function rateToNumber(conversionRate) {
+  return Number(conversionRate) / 1e18;
+}
+function fiatToNumber(fiat) {
+  return Number(fiat) / 10 ** USDC_DECIMALS;
+}
+function centsToNumber(cents) {
+  return Number(cents) / 100;
+}
+
+// src/engine/orderState.ts
+var DUST_THRESHOLD = 10000n;
+function toUnixSeconds(value) {
+  if (value === null || value === void 0 || value === "") return void 0;
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+var FULFILLED_STATUSES = /* @__PURE__ */ new Set([
+  "FULFILLED",
+  "MANUALLY_RELEASED"
+]);
+function toFill(intent) {
+  const signaledAt = toUnixSeconds(intent.signalTimestamp);
+  const expiresAt = toUnixSeconds(intent.expiryTime);
+  const fulfilledAt = toUnixSeconds(intent.fulfillTimestamp);
+  const prunedAt = toUnixSeconds(intent.prunedTimestamp ?? intent.pruneTimestamp);
+  const paidAt = toUnixSeconds(intent.paymentTimestamp);
+  const amount = toBigInt(intent.amount);
+  const conversionRate = toBigIntOrUndefined(intent.conversionRate);
+  const currency = intent.fiatCurrency != null ? sdk.getCurrencyCodeFromHash(intent.fiatCurrency) : void 0;
+  const paidCurrency = intent.paymentCurrency != null ? sdk.getCurrencyCodeFromHash(intent.paymentCurrency) : void 0;
+  const paymentCents = toBigIntOrUndefined(intent.paymentAmount);
+  const releasedAmount = toBigIntOrUndefined(intent.releasedAmount);
+  const fillLatencySeconds = signaledAt !== void 0 && fulfilledAt !== void 0 && fulfilledAt >= signaledAt ? fulfilledAt - signaledAt : void 0;
+  return {
+    intentHash: intent.intentHash,
+    status: intent.status,
+    amount,
+    buyer: (intent.owner ?? "").toLowerCase(),
+    ...currency !== void 0 ? { currency } : {},
+    ...intent.fiatCurrency != null ? { currencyHash: intent.fiatCurrency } : {},
+    ...conversionRate !== void 0 && conversionRate > 0n ? {
+      conversionRate,
+      rate: rateToNumber(conversionRate),
+      fiatOwed: fiatToNumber(fiatFromUsdc(amount, conversionRate))
+    } : {},
+    ...paymentCents !== void 0 && paymentCents > 0n ? { fiatPaid: centsToNumber(paymentCents) } : {},
+    ...paidCurrency !== void 0 ? { paidCurrency } : {},
+    ...intent.paymentId != null && intent.paymentId !== "" ? { paymentId: intent.paymentId } : {},
+    ...paidAt !== void 0 ? { paidAt } : {},
+    ...releasedAmount !== void 0 && releasedAmount > 0n ? { releasedAmount } : {},
+    ...fillLatencySeconds !== void 0 ? { fillLatencySeconds } : {},
+    ...intent.isExpired != null ? { isExpired: intent.isExpired } : {},
+    ...signaledAt !== void 0 ? { signaledAt } : {},
+    ...expiresAt !== void 0 ? { expiresAt } : {},
+    ...fulfilledAt !== void 0 ? { fulfilledAt } : {},
+    ...prunedAt !== void 0 ? { prunedAt } : {}
+  };
+}
+function isFillLive(fill, nowSeconds) {
+  if (fill.status !== "SIGNALED") return false;
+  if (fill.isExpired === true) return false;
+  return fill.expiresAt === void 0 || fill.expiresAt > nowSeconds;
+}
+function fmtUsdc(amount) {
+  return `${formatUsdc(amount)} USDC`;
+}
+function explainOrder(order) {
+  switch (order.state) {
+    case "awaiting-buyer":
+      return `Your ${fmtUsdc(order.totalAmount)} cash-out is live and waiting for a buyer; you can withdraw it any time before a buyer commits.`;
+    case "matched":
+      return `A buyer committed to ${fmtUsdc(order.pendingAmount)} and is sending fiat now; funds release automatically once their payment is proven.`;
+    case "delivering":
+      return `${fmtUsdc(order.filledAmount)} of ${fmtUsdc(order.totalAmount)} has been delivered; the rest is ${order.pendingAmount > 0n ? "locked by an active buyer" : "still waiting for a buyer"}.`;
+    case "delivered":
+      return `Cash-out complete: ${fmtUsdc(order.filledAmount)} was delivered to ${order.fills.filter((f) => f.fulfilledAt !== void 0).length || "your"} buyer fill(s).`;
+    case "returned":
+      return order.filledAmount > 0n ? `${fmtUsdc(order.filledAmount)} was delivered and the remaining ${fmtUsdc(order.returnedAmount)} was returned to your wallet.` : `No buyer delivered; ${fmtUsdc(order.returnedAmount)} was returned to your wallet.`;
+  }
+}
+function withExplain(data) {
+  return { ...data, explain: () => explainOrder(data) };
+}
+function deriveNextActions(state, hasLiveIntent) {
+  if (state === "delivered" || state === "returned") return [];
+  if (state === "awaiting-buyer") return ["wait", "withdraw"];
+  return hasLiveIntent ? ["wait"] : ["wait", "withdraw"];
+}
+function deriveCashOrder(depositId, intents, options = {}) {
+  const fills = intents.map(toFill);
+  const taken = options.takenAmount ?? fills.filter((f) => FULFILLED_STATUSES.has(f.status)).reduce((a, f) => a + f.amount, 0n);
+  const outstanding = options.outstandingAmount ?? fills.filter((f) => f.status === "SIGNALED").reduce((a, f) => a + f.amount, 0n);
+  const withdrawn = options.withdrawnAmount ?? 0n;
+  const remaining = options.remainingAmount ?? 0n;
+  const total = options.totalAmount ?? remaining + outstanding + taken + withdrawn;
+  const status = options.status;
+  const isTerminal = status === "CLOSED" || status === "WITHDRAWN";
+  const hasLiveFunds = remaining > DUST_THRESHOLD || outstanding > 0n;
+  let state;
+  if (outstanding > 0n) {
+    state = taken > 0n ? "delivering" : "matched";
+  } else if (taken > 0n && !hasLiveFunds) {
+    state = "delivered";
+  } else if (taken > 0n && hasLiveFunds) {
+    state = "delivering";
+  } else if (!hasLiveFunds && (withdrawn > 0n || isTerminal)) {
+    state = "returned";
+  } else if (hasLiveFunds) {
+    state = "awaiting-buyer";
+  } else {
+    state = taken > 0n ? "delivered" : "returned";
+  }
+  let matchedAt;
+  let deliveredAt;
+  for (const fill of fills) {
+    if (fill.signaledAt && (!matchedAt || fill.signaledAt < matchedAt)) matchedAt = fill.signaledAt;
+    if (FULFILLED_STATUSES.has(fill.status) && fill.fulfilledAt) {
+      if (!deliveredAt || fill.fulfilledAt > deliveredAt) deliveredAt = fill.fulfilledAt;
+    }
+  }
+  const primary = fills.find((f) => f.status === "SIGNALED") ?? fills.find((f) => FULFILLED_STATUSES.has(f.status)) ?? fills[0];
+  const isInFlight = state === "awaiting-buyer" || state === "matched" || state === "delivering";
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const fillsIncluded = options.fillsIncluded ?? fills.length > 0;
+  const hasLiveIntent = fillsIncluded ? fills.some((f) => isFillLive(f, nowSeconds)) : outstanding > 0n;
+  return withExplain({
+    depositId,
+    state,
+    fills,
+    totalAmount: total,
+    filledAmount: taken,
+    pendingAmount: outstanding,
+    returnedAmount: withdrawn,
+    nextActions: deriveNextActions(state, hasLiveIntent),
+    ...primary?.intentHash !== void 0 ? { primaryIntentHash: primary.intentHash } : {},
+    ...matchedAt !== void 0 ? { matchedAt } : {},
+    ...deliveredAt !== void 0 ? { deliveredAt } : {},
+    ...options.updatedAt !== void 0 ? { updatedAt: options.updatedAt } : {},
+    intentCount: options.intentCount ?? fills.length,
+    ...options.payouts !== void 0 ? { payouts: options.payouts } : {},
+    ...options.successRateBps !== void 0 ? { successRateBps: options.successRateBps } : {},
+    isInFlight,
+    withdrawn: isTerminal
+  });
+}
+var ORACLE_KINDS = /* @__PURE__ */ new Set(["oracle_chainlink", "oracle_pyth"]);
+function toPricing(tuple) {
+  if (!tuple) return { marketRate: false };
+  const spreadBps = tuple.spreadBps != null ? Number(tuple.spreadBps) : void 0;
+  const oracleRate = toBigIntOrUndefined(tuple.oracleRate);
+  const lastOracleUpdatedAt = tuple.lastOracleUpdatedAt != null ? Number(tuple.lastOracleUpdatedAt) : void 0;
+  return {
+    ...spreadBps !== void 0 && Number.isFinite(spreadBps) ? { spreadBps } : {},
+    ...tuple.kind != null ? { kind: tuple.kind } : {},
+    ...tuple.rateSource != null ? { rateSource: tuple.rateSource } : {},
+    ...oracleRate !== void 0 && oracleRate > 0n ? { oracleRate: rateToNumber(oracleRate) } : {},
+    ...lastOracleUpdatedAt !== void 0 && Number.isFinite(lastOracleUpdatedAt) ? { lastOracleUpdatedAt } : {},
+    marketRate: spreadBps === 0 && tuple.kind != null && ORACLE_KINDS.has(tuple.kind)
+  };
+}
+function derivePayouts(paymentMethods, currencies, catalog) {
+  return paymentMethods.flatMap((method) => {
+    const platformHash = method.paymentMethodHash ?? "";
+    if (!platformHash) return [];
+    let platform;
+    try {
+      platform = sdk.resolvePaymentMethodNameFromHash(platformHash, catalog);
+    } catch {
+      platform = void 0;
+    }
+    const tuples = currencies.filter(
+      (c) => (c.paymentMethodHash ?? "").toLowerCase() === platformHash.toLowerCase()
+    );
+    const base2 = {
+      ...platform !== void 0 ? { platform } : {},
+      platformHash,
+      payeeHash: method.payeeDetailsHash ?? "",
+      active: method.active ?? true
+    };
+    if (tuples.length === 0) return [{ ...base2, pricing: toPricing(void 0) }];
+    return tuples.map((tuple) => {
+      const currency = tuple.currencyCode != null ? sdk.getCurrencyCodeFromHash(tuple.currencyCode) : void 0;
+      return {
+        ...base2,
+        ...currency !== void 0 ? { currency } : {},
+        ...tuple.currencyCode != null ? { currencyHash: tuple.currencyCode } : {},
+        pricing: toPricing(tuple)
+      };
+    });
+  });
+}
+
+// src/engine/buyerProfile.ts
+function toSeconds(value) {
+  if (value === null || value === void 0 || value === "") return void 0;
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+function deriveBuyerProfile(address, intents) {
+  let fulfilled = 0;
+  let pruned = 0;
+  let signaled = 0;
+  let firstSeenAt;
+  let lastSeenAt;
+  for (const intent of intents) {
+    const status = intent.status ?? "";
+    if (status === "FULFILLED" || status === "MANUALLY_RELEASED") fulfilled += 1;
+    else if (status === "PRUNED") pruned += 1;
+    else if (status === "SIGNALED") signaled += 1;
+    const at = toSeconds(intent.signalTimestamp);
+    if (at !== void 0) {
+      if (firstSeenAt === void 0 || at < firstSeenAt) firstSeenAt = at;
+      if (lastSeenAt === void 0 || at > lastSeenAt) lastSeenAt = at;
+    }
+  }
+  const settled = fulfilled + pruned;
+  return {
+    address: address.toLowerCase(),
+    totalIntents: intents.length,
+    fulfilled,
+    pruned,
+    signaled,
+    ...settled > 0 ? { successRateBps: Math.round(fulfilled / settled * 1e4) } : {},
+    ...firstSeenAt !== void 0 ? { firstSeenAt } : {},
+    ...lastSeenAt !== void 0 ? { lastSeenAt } : {}
+  };
+}
+function resolveCashDepositId(params) {
+  let events;
+  try {
+    events = viem.parseEventLogs({
+      abi: params.abi,
+      eventName: "DepositReceived",
+      logs: params.logs
+    });
+  } catch {
+    return null;
+  }
+  const event = events[0];
+  if (!event) return null;
+  const rawId = event.args.depositId;
+  if (rawId === void 0 || rawId === null) return null;
+  const onchainDepositId = BigInt(rawId);
+  const escrowAddress = event.address.toLowerCase();
+  return {
+    onchainDepositId,
+    escrowAddress,
+    compositeId: sdk.createCompositeDepositId(escrowAddress, onchainDepositId)
+  };
+}
+function parseCompositeDepositId(compositeId) {
+  const idx = compositeId.lastIndexOf("_");
+  if (idx === -1) {
+    return { escrowAddress: "", onchainDepositId: BigInt(compositeId) };
+  }
+  const escrowAddress = compositeId.slice(0, idx);
+  const onchainDepositId = BigInt(compositeId.slice(idx + 1) || "0");
+  return { escrowAddress, onchainDepositId };
+}
+var MIN_CASHOUT_AMOUNT = 10000n;
+var RECOMMENDED_MIN_CASHOUT_AMOUNT = 1000000n;
+var PAYEE_HINTS = {
+  venmo: "Venmo username, with or without the leading @ (e.g. @andrew-w)",
+  cashapp: "Cashtag, with or without the leading $ (e.g. $andrew)",
+  revolut: "Revtag (e.g. andrew1abc)",
+  wise: "Wisetag or the email on the Wise account",
+  zelle: "Email address or US phone number enrolled with Zelle",
+  paypal: "PayPal.Me handle or account email",
+  mercadopago: "Mercado Pago alias or CVU",
+  monzo: "Monzo.me username",
+  chime: "ChimeSign (e.g. $andrew)",
+  luxon: "Luxon Pay ID or account email",
+  n26: "MoneyBeam email or phone number"
+};
+var IDENTITY_ATTESTATION_PLATFORMS = /* @__PURE__ */ new Set(["wise", "paypal"]);
+function platformRequiresIdentityAttestation(platform) {
+  return IDENTITY_ATTESTATION_PLATFORMS.has(platform);
+}
+function buildCapabilities(environment) {
+  const catalog = sdk.getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
+  const platforms = Object.entries(catalog).map(([platform, entry]) => {
+    const currencies2 = (entry.currencies ?? []).map((hash) => sdk.getCurrencyCodeFromHash(hash)).filter(
+      (code) => code != null && isMarketRateSupported(code)
+    );
+    return {
+      platform,
+      currencies: [...new Set(currencies2)],
+      payeeHint: PAYEE_HINTS[platform] ?? "Your payment handle for this platform",
+      requiresIdentityAttestation: IDENTITY_ATTESTATION_PLATFORMS.has(platform)
+    };
+  }).filter((p) => p.currencies.length > 0).sort((a, b) => a.platform.localeCompare(b.platform));
+  const currencies = [...new Set(platforms.flatMap((p) => p.currencies))].sort();
+  return {
+    chainId: BASE_CHAIN_ID,
+    token: { address: BASE_USDC_ADDRESS, symbol: "USDC", decimals: USDC_DECIMALS },
+    environment,
+    platforms,
+    currencies,
+    amount: { min: MIN_CASHOUT_AMOUNT, recommendedMin: RECOMMENDED_MIN_CASHOUT_AMOUNT, max: null },
+    pricing: { kind: "oracle-market-rate", spreadBps: 0 }
+  };
+}
+
+// src/client/errors.ts
+var CashError = class extends Error {
+  code;
+  retryable;
+  remediation;
+  constructor(shape, options) {
+    super(shape.message, options);
+    this.name = "CashError";
+    this.code = shape.code;
+    this.retryable = shape.retryable;
+    this.remediation = shape.remediation;
+  }
+  /** Serializable view (for tool results and logs). */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      remediation: this.remediation
+    };
+  }
+};
+function isCashError(value) {
+  return value instanceof CashError;
+}
+var errors = {
+  oracleUnsupportedCurrency: (currency) => new CashError({
+    code: "ORACLE_UNSUPPORTED_CURRENCY",
+    message: `${currency} has no live Chainlink oracle feed; Peer Cash is market-rate only.`,
+    retryable: false,
+    remediation: `Pick a currency listed in capabilities() - each one is priced by a live oracle feed.`
+  }),
+  unsupportedPlatform: (platform) => new CashError({
+    code: "UNSUPPORTED_PLATFORM",
+    message: `'${platform}' is not a supported payout platform in this environment.`,
+    retryable: false,
+    remediation: `Pick a platform listed in capabilities().`
+  }),
+  amountBelowMinimum: (amount, min) => new CashError({
+    code: "AMOUNT_BELOW_MINIMUM",
+    message: `Amount ${amount} is below the minimum cash-out of ${min} USDC base units.`,
+    retryable: false,
+    remediation: `Increase the amount to at least ${min} base units (${Number(min) / 1e6} USDC).`
+  }),
+  activeIntentBlocksWithdrawal: (depositId) => new CashError({
+    code: "ACTIVE_INTENT_BLOCKS_WITHDRAWAL",
+    message: `Order ${depositId} has a live buyer intent; escrow blocks withdrawal while a buyer may still deliver.`,
+    retryable: true,
+    remediation: `Wait for the buyer to complete or for their intent to expire, then call withdraw() again - it prunes expired intents automatically.`
+  }),
+  insufficientAvailableFunds: (depositId, requested, available) => new CashError({
+    code: "INSUFFICIENT_AVAILABLE_FUNDS",
+    message: `Order ${depositId} has ${available} base units available; ${requested} requested.`,
+    retryable: true,
+    remediation: `Withdraw at most the available (unlocked) amount, or omit the amount to close the order fully once no buyer intent is live.`
+  }),
+  orderNotActive: (depositId) => new CashError({
+    code: "ORDER_NOT_ACTIVE",
+    message: `Order ${depositId} is closed (delivered or returned); it cannot be topped up.`,
+    retryable: false,
+    remediation: `Start a new cash-out with cashout() instead.`
+  }),
+  nothingToWithdraw: (depositId) => new CashError({
+    code: "NOTHING_TO_WITHDRAW",
+    message: `Order ${depositId} holds no withdrawable funds (already delivered or returned).`,
+    retryable: false,
+    remediation: `Check order(depositId).state - this order is terminal.`
+  }),
+  indexerLag: (depositId) => new CashError({
+    code: "INDEXER_LAG",
+    message: `Order ${depositId} is not indexed yet (the deposit may be seconds old).`,
+    retryable: true,
+    remediation: `Retry in a few seconds; on-chain state is ahead of the indexer right after a transaction.`
+  }),
+  orderNotFound: (depositId) => new CashError({
+    code: "ORDER_NOT_FOUND",
+    message: `No deposit found for id ${depositId}.`,
+    retryable: true,
+    remediation: `Verify the composite depositId (escrow_onchainId). If the deposit was created seconds ago this is indexer lag - retry shortly.`
+  }),
+  payeeRegistrationFailed: (cause) => new CashError(
+    {
+      code: "PAYEE_REGISTRATION_FAILED",
+      message: `Registering payee details with the curator failed.`,
+      retryable: true,
+      remediation: `Check the payee handle format for the platform (see capabilities() hints) and retry.`
+    },
+    { cause }
+  ),
+  payeeVerificationRequired: (platform, cause) => new CashError(
+    {
+      code: "PAYEE_VERIFICATION_REQUIRED",
+      message: `${platform} requires a verified maker identity attestation to register a payee; a bare handle is not accepted.`,
+      retryable: false,
+      remediation: `Register this ${platform} payee through the ZKP2P app / extension (which produces the signed identity attestation) before cashing out. capabilities() flags such platforms with requiresIdentityAttestation: true.`
+    },
+    { cause }
+  ),
+  allowanceNotVisible: (amount) => new CashError({
+    code: "ALLOWANCE_NOT_VISIBLE",
+    message: `USDC approval for ${amount} base units did not become visible on the read path in time.`,
+    retryable: true,
+    remediation: `The approve transaction mined but a load-balanced RPC is serving stale state. Retry the same call in a few seconds.`
+  }),
+  depositResolutionFailed: (txHash) => new CashError({
+    code: "DEPOSIT_RESOLUTION_FAILED",
+    message: `Deposit transaction ${txHash} succeeded but no DepositReceived event was found in the receipt.`,
+    retryable: false,
+    remediation: `Inspect the transaction on Basescan; recover the depositId from the DepositReceived log manually, then resume with order(depositId).`
+  }),
+  signerRequired: (verb) => new CashError({
+    code: "SIGNER_REQUIRED",
+    message: `${verb}() mutates on-chain state and needs a signer.`,
+    retryable: false,
+    remediation: `Pass { signer } (a viem WalletClient with an account), or use prepare() and submit the returned txs with your own signing infrastructure.`
+  }),
+  watchTimeout: (depositId, timeoutMs) => new CashError({
+    code: "WATCH_TIMEOUT",
+    message: `watch(${depositId}) exceeded ${timeoutMs}ms without reaching a terminal state.`,
+    retryable: true,
+    remediation: `The order is still live - resume any time with watch(depositId) or order(depositId).`
+  }),
+  transactionFailed: (txHash, cause) => new CashError(
+    {
+      code: "TRANSACTION_FAILED",
+      message: `Transaction ${txHash} reverted.`,
+      retryable: false,
+      remediation: `Inspect the transaction on Basescan; the deposit state is unchanged if the revert happened before escrow accepted funds.`
+    },
+    { cause }
+  ),
+  escrowPaused: () => new CashError({
+    code: "ESCROW_PAUSED",
+    message: `The escrow contract is paused; deposits are temporarily disabled.`,
+    retryable: true,
+    remediation: `Wait for the protocol to unpause and retry. Existing funds remain withdrawable.`
+  }),
+  /** Generic fallback for an on-chain call that failed for an unrecognized reason. */
+  chainCallFailed: (verb, cause) => new CashError(
+    {
+      code: "TRANSACTION_FAILED",
+      message: `The on-chain ${verb} call failed.`,
+      retryable: false,
+      remediation: `Inspect the error cause and the wallet on Basescan. Deposit state is unchanged if the call reverted before escrow accepted funds.`
+    },
+    { cause }
+  )
+};
+function mapChainError(verb, err) {
+  if (isCashError(err)) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  if (/\bpaused\b/i.test(message)) return errors.escrowPaused();
+  if (/exceeds allowance|insufficient allowance|transfer amount exceeds/i.test(message)) {
+    return errors.allowanceNotVisible(0n);
+  }
+  return errors.chainCallFailed(verb, err);
+}
+
+// src/client/estimate.ts
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var CHAINLINK_LATEST_ROUND_ABI = [
+  {
+    name: "latestRoundData",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [
+      { name: "roundId", type: "uint80" },
+      { name: "answer", type: "int256" },
+      { name: "startedAt", type: "uint256" },
+      { name: "updatedAt", type: "uint256" },
+      { name: "answeredInRound", type: "uint80" }
+    ]
+  }
+];
+var DEFAULT_MAX_STALENESS_SECONDS = 86400;
+async function readEstimate(publicClient, input) {
+  const { amount, currency } = input;
+  if (amount < MIN_CASHOUT_AMOUNT) {
+    throw errors.amountBelowMinimum(amount, MIN_CASHOUT_AMOUNT);
+  }
+  if (!isMarketRateSupported(currency)) {
+    throw errors.oracleUnsupportedCurrency(currency);
+  }
+  const feedConfig = sdk.CHAINLINK_ORACLE_FEEDS[currency];
+  const asOf = Math.floor(Date.now() / 1e3);
+  let rate;
+  let oracleUpdatedAt;
+  if (!feedConfig || feedConfig.feed.toLowerCase() === ZERO_ADDRESS) {
+    rate = 1;
+  } else {
+    const result = await publicClient.readContract({
+      address: feedConfig.feed,
+      abi: CHAINLINK_LATEST_ROUND_ABI,
+      functionName: "latestRoundData"
+    });
+    const answer = Number(result[1]);
+    const price = answer / 10 ** feedConfig.decimals;
+    if (!Number.isFinite(price) || price <= 0) {
+      throw errors.oracleUnsupportedCurrency(currency);
+    }
+    const updatedAt = Number(result[3]);
+    if (Number.isFinite(updatedAt) && updatedAt > 0) oracleUpdatedAt = updatedAt;
+    rate = feedConfig.invert ? 1 / price : price;
+  }
+  const stale = oracleUpdatedAt !== void 0 && asOf - oracleUpdatedAt > DEFAULT_MAX_STALENESS_SECONDS;
+  return {
+    kind: "oracle-estimate",
+    currency,
+    amount,
+    rate,
+    receiveAmount: Number(amount) / 10 ** USDC_DECIMALS * rate,
+    asOf,
+    ...oracleUpdatedAt !== void 0 ? { oracleUpdatedAt } : {},
+    ...stale ? { stale: true } : {}
+  };
+}
+
+// src/client/createCashClient.ts
+var DEFAULT_RPC_URL = "https://mainnet.base.org";
+var CASH_ATTRIBUTION_CODE = "peer-cash";
+var DEFAULT_CURATOR_URLS = {
+  staging: "https://api-staging.zkp2p.xyz"
+};
+var ERC20_APPROVE_ABI = viem.parseAbi([
+  "function approve(address spender, uint256 amount) returns (bool)"
+]);
+var ERC20_ALLOWANCE_ABI = viem.parseAbi([
+  "function allowance(address owner, address spender) view returns (uint256)"
+]);
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      signal?.removeEventListener("abort", done);
+      clearTimeout(timer);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+function orderFingerprint(order) {
+  return [
+    order.state,
+    order.filledAmount,
+    order.pendingAmount,
+    order.returnedAmount,
+    order.intentCount ?? 0,
+    order.nextActions.join("+")
+  ].join("|");
+}
+async function submitAndConfirm(client, verb, send) {
+  let hash;
+  try {
+    hash = await send();
+  } catch (err) {
+    throw mapChainError(verb, err);
+  }
+  const receipt = await client.publicClient.waitForTransactionReceipt({ hash });
+  if (receipt.status === "reverted") throw errors.transactionFailed(hash);
+  return hash;
+}
+function depositOrderOptions(deposit) {
+  const remaining = toBigIntOrUndefined(deposit.remainingDeposits);
+  const outstanding = toBigIntOrUndefined(deposit.outstandingIntentAmount);
+  const taken = toBigIntOrUndefined(deposit.totalAmountTaken);
+  const withdrawn = toBigIntOrUndefined(deposit.totalWithdrawn);
+  const updatedAt = deposit.updatedAt != null ? Number(deposit.updatedAt) : void 0;
+  return {
+    ...remaining !== void 0 ? { remainingAmount: remaining } : {},
+    ...outstanding !== void 0 ? { outstandingAmount: outstanding } : {},
+    ...taken !== void 0 ? { takenAmount: taken } : {},
+    ...withdrawn !== void 0 ? { withdrawnAmount: withdrawn } : {},
+    ...deposit.status != null ? { status: deposit.status } : {},
+    ...deposit.totalIntents != null ? { intentCount: deposit.totalIntents } : {},
+    ...deposit.successRateBps != null ? { successRateBps: deposit.successRateBps } : {},
+    ...updatedAt !== void 0 && Number.isFinite(updatedAt) ? { updatedAt } : {}
+  };
+}
+function createCashClient(options) {
+  const { environment } = options;
+  const transport = options.transport ?? viem.http(options.rpcUrl ?? DEFAULT_RPC_URL);
+  const referrerCodes = [
+    CASH_ATTRIBUTION_CODE,
+    ...options.referrer === void 0 ? [] : Array.isArray(options.referrer) ? options.referrer : [options.referrer]
+  ];
+  const attribution = { referrer: referrerCodes };
+  function buildSdkClient(walletClient) {
+    return new sdk.Zkp2pClient({
+      walletClient,
+      chainId: BASE_CHAIN_ID,
+      runtimeEnv: environment,
+      rpcTransport: transport,
+      ...options.rpcUrl ? { rpcUrl: options.rpcUrl } : {},
+      ...options.indexerUrl ? { indexerUrl: options.indexerUrl } : {},
+      ...options.curatorUrl ?? DEFAULT_CURATOR_URLS[environment] ? { baseApiUrl: options.curatorUrl ?? DEFAULT_CURATOR_URLS[environment] } : {},
+      ...options.apiKey ? { apiKey: options.apiKey } : {}
+    });
+  }
+  const readClient = buildSdkClient(viem.createWalletClient({ chain: chains.base, transport }));
+  const signingClients = /* @__PURE__ */ new WeakMap();
+  function signingClient(verb, opts) {
+    const signer = opts?.signer;
+    if (!signer?.account) throw errors.signerRequired(verb);
+    let client = signingClients.get(signer);
+    if (!client) {
+      client = buildSdkClient(signer);
+      signingClients.set(signer, client);
+    }
+    return client;
+  }
+  function validateInput(input) {
+    const { amount, receive } = input;
+    if (amount < MIN_CASHOUT_AMOUNT) throw errors.amountBelowMinimum(amount, MIN_CASHOUT_AMOUNT);
+    const catalog = sdk.getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
+    if (!catalog[receive.platform]) throw errors.unsupportedPlatform(receive.platform);
+    if (!isMarketRateSupported(receive.currency)) {
+      throw errors.oracleUnsupportedCurrency(receive.currency);
+    }
+    if (platformRequiresIdentityAttestation(receive.platform) && !receive.payee.identityAttestation) {
+      throw errors.payeeVerificationRequired(receive.platform);
+    }
+    return {
+      amount,
+      payouts: [
+        {
+          processorName: receive.platform,
+          currency: receive.currency,
+          payeeData: receive.payee
+        }
+      ],
+      ...input.intentAmountRange ? { intentAmountRange: input.intentAmountRange } : {}
+    };
+  }
+  async function buildDepositParams(client, depositInput) {
+    try {
+      return await prepareCashDepositParams(client, depositInput);
+    } catch (err) {
+      if (isCashError(err)) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      if (/identityAttestation is required|identity attestation/i.test(message)) {
+        const platform = depositInput.payouts[0]?.processorName ?? "this platform";
+        throw errors.payeeVerificationRequired(platform, err);
+      }
+      throw errors.payeeRegistrationFailed(err);
+    }
+  }
+  async function fetchOrder(depositId) {
+    const deposits = await readClient.indexer.getDepositsByIdsWithRelations([depositId], {
+      includeIntents: true,
+      intentStatuses: CASH_ORDER_STATUSES
+    });
+    const deposit = deposits[0];
+    if (!deposit) {
+      const intents = await readClient.indexer.getIntentsForDeposits(
+        [depositId],
+        CASH_ORDER_STATUSES
+      );
+      if (intents.length === 0) throw errors.orderNotFound(depositId);
+      return deriveCashOrder(depositId, intents);
+    }
+    const payouts = derivePayouts(
+      deposit.paymentMethods ?? [],
+      deposit.currencies ?? [],
+      sdk.getPaymentMethodsCatalog(BASE_CHAIN_ID, environment)
+    );
+    return deriveCashOrder(depositId, deposit.intents ?? [], {
+      ...depositOrderOptions(deposit),
+      ...payouts.length > 0 ? { payouts } : {}
+    });
+  }
+  function escrowContext(depositId) {
+    const { escrowAddress, onchainDepositId } = parseCompositeDepositId(depositId);
+    return {
+      onchainDepositId,
+      escrowArg: escrowAddress ? { escrowAddress } : {}
+    };
+  }
+  function availableAmount(order) {
+    return order.totalAmount - order.filledAmount - order.pendingAmount - order.returnedAmount;
+  }
+  async function withdrawContext(depositId) {
+    const order = await fetchOrder(depositId);
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    const signaled = order.fills.filter((f) => f.status === "SIGNALED");
+    const liveIntent = signaled.some((f) => isFillLive(f, nowSeconds));
+    const expiredIntent = signaled.length > 0 && !liveIntent;
+    if (order.pendingAmount > 0n && liveIntent) {
+      throw errors.activeIntentBlocksWithdrawal(depositId);
+    }
+    if (availableAmount(order) <= 0n && order.pendingAmount === 0n) {
+      throw errors.nothingToWithdraw(depositId);
+    }
+    return { expiredIntent, ...escrowContext(depositId) };
+  }
+  async function partialWithdrawContext(depositId, amount) {
+    if (amount <= 0n) throw errors.amountBelowMinimum(amount, 1n);
+    const order = await fetchOrder(depositId);
+    const available = availableAmount(order);
+    if (amount > available) {
+      throw errors.insufficientAvailableFunds(depositId, amount, available);
+    }
+    return escrowContext(depositId);
+  }
+  async function topUpContext(depositId, amount) {
+    if (amount < MIN_CASHOUT_AMOUNT) throw errors.amountBelowMinimum(amount, MIN_CASHOUT_AMOUNT);
+    const order = await fetchOrder(depositId);
+    if (!order.isInFlight) throw errors.orderNotActive(depositId);
+    return escrowContext(depositId);
+  }
+  async function settleAllowance(client, token, owner, escrow, amount) {
+    let allowance;
+    try {
+      allowance = await client.ensureAllowance({
+        token,
+        amount,
+        spender: escrow,
+        txOverrides: attribution
+      });
+    } catch (err) {
+      throw mapChainError("approve", err);
+    }
+    if (allowance.hadAllowance || !allowance.hash) return;
+    const receipt = await client.publicClient.waitForTransactionReceipt({ hash: allowance.hash });
+    if (receipt.status === "reverted") throw errors.transactionFailed(allowance.hash);
+    for (let attempt = 0; attempt < 15; attempt++) {
+      const visible = await client.publicClient.readContract({
+        address: token,
+        abi: ERC20_ALLOWANCE_ABI,
+        functionName: "allowance",
+        args: [owner, escrow]
+      });
+      if (visible >= amount) return;
+      await sleep(1e3);
+    }
+    throw errors.allowanceNotVisible(amount);
+  }
+  return {
+    capabilities() {
+      return buildCapabilities(environment);
+    },
+    async estimate(input) {
+      return readEstimate(readClient.publicClient, input);
+    },
+    async cashout(input, opts) {
+      const depositInput = validateInput(input);
+      const client = signingClient("cashout", opts);
+      const params = await buildDepositParams(client, depositInput);
+      const escrow = client.escrowV2Address ?? client.escrowAddress;
+      const owner = opts.signer.account.address;
+      await settleAllowance(client, params.token, owner, escrow, depositInput.amount);
+      const attributedParams = { ...params, txOverrides: attribution };
+      const send = async () => {
+        try {
+          return (await client.createDeposit(attributedParams)).hash;
+        } catch (err) {
+          if (err instanceof Error && /exceeds allowance/i.test(err.message)) {
+            await sleep(2e3);
+            return (await client.createDeposit(attributedParams)).hash;
+          }
+          throw err;
+        }
+      };
+      let hash;
+      try {
+        hash = await send();
+      } catch (err) {
+        throw mapChainError("createDeposit", err);
+      }
+      const receipt = await client.publicClient.waitForTransactionReceipt({ hash });
+      if (receipt.status === "reverted") throw errors.transactionFailed(hash);
+      const abi = client.escrowV2Abi ?? client.escrowAbi;
+      const resolved = resolveCashDepositId({ logs: receipt.logs, abi });
+      if (!resolved) throw errors.depositResolutionFailed(hash);
+      const order = deriveCashOrder(resolved.compositeId, [], {
+        remainingAmount: depositInput.amount,
+        status: "ACTIVE"
+      });
+      return {
+        depositId: resolved.compositeId,
+        txHash: hash,
+        escrowAddress: resolved.escrowAddress,
+        onchainDepositId: resolved.onchainDepositId,
+        order
+      };
+    },
+    async prepare(input) {
+      const depositInput = validateInput(input);
+      const params = await buildDepositParams(readClient, depositInput);
+      const { prepared } = await readClient.prepareCreateDeposit({
+        ...params,
+        txOverrides: attribution
+      });
+      const approve = {
+        to: params.token,
+        data: sdk.appendAttributionToCalldata(
+          viem.encodeFunctionData({
+            abi: ERC20_APPROVE_ABI,
+            functionName: "approve",
+            args: [prepared.to, depositInput.amount]
+          }),
+          referrerCodes
+        ),
+        value: 0n,
+        chainId: BASE_CHAIN_ID
+      };
+      const hashedOnchainIds = (params.paymentMethodDataOverride ?? []).map((d) => d.payeeDetails);
+      return {
+        txs: [approve, prepared],
+        steps: [
+          {
+            kind: "approve",
+            description: "Approve Base USDC for the Peer Cash escrow."
+          },
+          {
+            kind: "createDeposit",
+            description: "Create the protocol-held cash-out order."
+          }
+        ],
+        register: { hashedOnchainIds }
+      };
+    },
+    async order(depositId) {
+      return fetchOrder(depositId);
+    },
+    async buyer(address) {
+      const intents = await readClient.indexer.getOwnerIntents(address, CASH_ORDER_STATUSES);
+      return deriveBuyerProfile(address, intents);
+    },
+    async orders(owner, opts = {}) {
+      const { inFlight = false, limit = 100 } = opts;
+      const deposits = await readClient.indexer.getDeposits({ depositor: owner }, { limit });
+      const derived = deposits.map((d) => deriveCashOrder(d.id, [], { ...depositOrderOptions(d), fillsIncluded: false })).filter((o) => o.totalAmount > 10000n).sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+      return inFlight ? derived.filter((o) => o.isInFlight) : derived;
+    },
+    async *watch(depositId, opts = {}) {
+      const { signal, pollIntervalMs = 5e3, timeoutMs } = opts;
+      const startedAt = Date.now();
+      let lastFingerprint;
+      while (true) {
+        if (signal?.aborted) return;
+        if (timeoutMs !== void 0 && Date.now() - startedAt >= timeoutMs) {
+          throw errors.watchTimeout(depositId, timeoutMs);
+        }
+        let order = null;
+        try {
+          order = await fetchOrder(depositId);
+        } catch (err) {
+          if (!(isCashError(err) && err.code === "ORDER_NOT_FOUND")) throw err;
+        }
+        if (order) {
+          const fingerprint = orderFingerprint(order);
+          if (fingerprint !== lastFingerprint) {
+            lastFingerprint = fingerprint;
+            yield order;
+          }
+          if (!order.isInFlight) return;
+        }
+        await sleep(pollIntervalMs, signal);
+      }
+    },
+    async withdraw(depositId, opts) {
+      const client = signingClient("withdraw", opts);
+      if (opts.amount !== void 0) {
+        const { onchainDepositId: onchainDepositId2, escrowArg: escrowArg2 } = await partialWithdrawContext(
+          depositId,
+          opts.amount
+        );
+        const withdrawTxHash2 = await submitAndConfirm(
+          client,
+          "removeFunds",
+          () => client.removeFunds({
+            depositId: onchainDepositId2,
+            amount: opts.amount,
+            ...escrowArg2,
+            txOverrides: attribution
+          })
+        );
+        return { depositId, withdrawTxHash: withdrawTxHash2 };
+      }
+      const { expiredIntent, onchainDepositId, escrowArg } = await withdrawContext(depositId);
+      let pruneTxHash;
+      if (expiredIntent) {
+        pruneTxHash = await submitAndConfirm(
+          client,
+          "pruneExpiredIntents",
+          () => client.pruneExpiredIntents({
+            depositId: onchainDepositId,
+            ...escrowArg,
+            txOverrides: attribution
+          })
+        );
+      }
+      const withdrawTxHash = await submitAndConfirm(
+        client,
+        "withdrawDeposit",
+        () => client.withdrawDeposit({
+          depositId: onchainDepositId,
+          ...escrowArg,
+          txOverrides: attribution
+        })
+      );
+      return {
+        depositId,
+        ...pruneTxHash !== void 0 ? { pruneTxHash } : {},
+        withdrawTxHash
+      };
+    },
+    async prepareWithdraw(depositId, opts = {}) {
+      if (opts.amount !== void 0) {
+        const { onchainDepositId: onchainDepositId2, escrowArg: escrowArg2 } = await partialWithdrawContext(
+          depositId,
+          opts.amount
+        );
+        const tx = await readClient.removeFunds.prepare({
+          depositId: onchainDepositId2,
+          amount: opts.amount,
+          ...escrowArg2,
+          txOverrides: attribution
+        });
+        return {
+          txs: [tx],
+          steps: [
+            {
+              kind: "removeFunds",
+              description: "Withdraw the requested unlocked USDC amount."
+            }
+          ]
+        };
+      }
+      const { expiredIntent, onchainDepositId, escrowArg } = await withdrawContext(depositId);
+      const txs = [];
+      const steps = [];
+      if (expiredIntent) {
+        txs.push(
+          await readClient.pruneExpiredIntents.prepare({
+            depositId: onchainDepositId,
+            ...escrowArg,
+            txOverrides: attribution
+          })
+        );
+        steps.push({
+          kind: "pruneExpiredIntents",
+          description: "Prune expired buyer intents so the locked amount becomes withdrawable."
+        });
+      }
+      txs.push(
+        await readClient.withdrawDeposit.prepare({
+          depositId: onchainDepositId,
+          ...escrowArg,
+          txOverrides: attribution
+        })
+      );
+      steps.push({
+        kind: "withdrawDeposit",
+        description: "Close the order and withdraw all remaining USDC."
+      });
+      return { txs, steps };
+    },
+    async topUp(depositId, amount, opts) {
+      const client = signingClient("topUp", opts);
+      const { onchainDepositId, escrowArg } = await topUpContext(depositId, amount);
+      const owner = opts.signer.account.address;
+      const escrow = escrowArg.escrowAddress ?? client.escrowV2Address ?? client.escrowAddress;
+      await settleAllowance(client, BASE_USDC_ADDRESS, owner, escrow, amount);
+      const txHash = await submitAndConfirm(
+        client,
+        "addFunds",
+        () => client.addFunds({
+          depositId: onchainDepositId,
+          amount,
+          ...escrowArg,
+          txOverrides: attribution
+        })
+      );
+      return { depositId, txHash };
+    },
+    async prepareTopUp(depositId, amount) {
+      const { onchainDepositId, escrowArg } = await topUpContext(depositId, amount);
+      const prepared = await readClient.addFunds.prepare({
+        depositId: onchainDepositId,
+        amount,
+        ...escrowArg,
+        txOverrides: attribution
+      });
+      const approve = {
+        to: BASE_USDC_ADDRESS,
+        data: sdk.appendAttributionToCalldata(
+          viem.encodeFunctionData({
+            abi: ERC20_APPROVE_ABI,
+            functionName: "approve",
+            args: [prepared.to, amount]
+          }),
+          referrerCodes
+        ),
+        value: 0n,
+        chainId: BASE_CHAIN_ID
+      };
+      return {
+        txs: [approve, prepared],
+        steps: [
+          {
+            kind: "approve",
+            description: "Approve additional Base USDC for the Peer Cash escrow."
+          },
+          {
+            kind: "addFunds",
+            description: "Add USDC to the live cash-out order."
+          }
+        ]
+      };
+    }
+  };
+}
+var bigintString = zod.z.string().regex(/^-?\d+$/, "expected a decimal bigint string");
+var cashOrderStateSchema = zod.z.enum([
+  "awaiting-buyer",
+  "matched",
+  "delivering",
+  "delivered",
+  "returned"
+]);
+var cashNextActionSchema = zod.z.enum(["wait", "withdraw"]);
+var intentStatusSchema = zod.z.enum(["SIGNALED", "FULFILLED", "PRUNED", "MANUALLY_RELEASED"]);
+var cashFillJsonSchema = zod.z.object({
+  intentHash: zod.z.string(),
+  status: intentStatusSchema,
+  amount: bigintString,
+  buyer: zod.z.string(),
+  currency: zod.z.string().optional(),
+  currencyHash: zod.z.string().optional(),
+  rate: zod.z.number().optional(),
+  conversionRate: bigintString.optional(),
+  fiatOwed: zod.z.number().optional(),
+  fiatPaid: zod.z.number().optional(),
+  paidCurrency: zod.z.string().optional(),
+  paymentId: zod.z.string().optional(),
+  paidAt: zod.z.number().optional(),
+  releasedAmount: bigintString.optional(),
+  fillLatencySeconds: zod.z.number().optional(),
+  isExpired: zod.z.boolean().optional(),
+  signaledAt: zod.z.number().optional(),
+  expiresAt: zod.z.number().optional(),
+  fulfilledAt: zod.z.number().optional(),
+  prunedAt: zod.z.number().optional()
+});
+var cashPayoutPricingJsonSchema = zod.z.object({
+  spreadBps: zod.z.number().optional(),
+  kind: zod.z.string().optional(),
+  rateSource: zod.z.string().optional(),
+  oracleRate: zod.z.number().optional(),
+  lastOracleUpdatedAt: zod.z.number().optional(),
+  marketRate: zod.z.boolean()
+});
+var cashPayoutInfoJsonSchema = zod.z.object({
+  platform: zod.z.string().optional(),
+  platformHash: zod.z.string(),
+  currency: zod.z.string().optional(),
+  currencyHash: zod.z.string().optional(),
+  payeeHash: zod.z.string(),
+  active: zod.z.boolean(),
+  pricing: cashPayoutPricingJsonSchema
+});
+var cashBuyerProfileJsonSchema = zod.z.object({
+  address: zod.z.string(),
+  totalIntents: zod.z.number(),
+  fulfilled: zod.z.number(),
+  pruned: zod.z.number(),
+  signaled: zod.z.number(),
+  successRateBps: zod.z.number().optional(),
+  firstSeenAt: zod.z.number().optional(),
+  lastSeenAt: zod.z.number().optional()
+});
+var cashOrderJsonSchema = zod.z.object({
+  depositId: zod.z.string(),
+  state: cashOrderStateSchema,
+  fills: zod.z.array(cashFillJsonSchema),
+  totalAmount: bigintString,
+  filledAmount: bigintString,
+  pendingAmount: bigintString,
+  returnedAmount: bigintString,
+  nextActions: zod.z.array(cashNextActionSchema),
+  primaryIntentHash: zod.z.string().optional(),
+  matchedAt: zod.z.number().optional(),
+  deliveredAt: zod.z.number().optional(),
+  updatedAt: zod.z.number().optional(),
+  intentCount: zod.z.number().optional(),
+  payouts: zod.z.array(cashPayoutInfoJsonSchema).optional(),
+  successRateBps: zod.z.number().optional(),
+  isInFlight: zod.z.boolean(),
+  withdrawn: zod.z.boolean().optional()
+});
+var cashEstimateJsonSchema = zod.z.object({
+  kind: zod.z.literal("oracle-estimate"),
+  currency: zod.z.string(),
+  amount: bigintString,
+  rate: zod.z.number(),
+  receiveAmount: zod.z.number(),
+  asOf: zod.z.number(),
+  oracleUpdatedAt: zod.z.number().optional(),
+  stale: zod.z.boolean().optional()
+});
+var preparedTransactionJsonSchema = zod.z.object({
+  to: zod.z.string(),
+  data: zod.z.string(),
+  value: bigintString,
+  chainId: zod.z.number()
+});
+var cashPreparedStepJsonSchema = zod.z.object({
+  kind: zod.z.enum([
+    "approve",
+    "createDeposit",
+    "pruneExpiredIntents",
+    "withdrawDeposit",
+    "removeFunds",
+    "addFunds"
+  ]),
+  description: zod.z.string()
+});
+var cashoutResultJsonSchema = zod.z.object({
+  depositId: zod.z.string(),
+  txHash: zod.z.string(),
+  escrowAddress: zod.z.string(),
+  onchainDepositId: bigintString,
+  order: cashOrderJsonSchema
+});
+var prepareResultJsonSchema = zod.z.object({
+  txs: zod.z.array(preparedTransactionJsonSchema),
+  steps: zod.z.array(cashPreparedStepJsonSchema),
+  register: zod.z.object({ hashedOnchainIds: zod.z.array(zod.z.string()) })
+});
+var withdrawResultJsonSchema = zod.z.object({
+  depositId: zod.z.string(),
+  pruneTxHash: zod.z.string().optional(),
+  withdrawTxHash: zod.z.string()
+});
+var topUpResultJsonSchema = zod.z.object({
+  depositId: zod.z.string(),
+  txHash: zod.z.string()
+});
+var cashCapabilitiesJsonSchema = zod.z.object({
+  chainId: zod.z.number(),
+  token: zod.z.object({ address: zod.z.string(), symbol: zod.z.literal("USDC"), decimals: zod.z.number() }),
+  environment: zod.z.enum(["production", "preproduction", "staging"]),
+  platforms: zod.z.array(
+    zod.z.object({
+      platform: zod.z.string(),
+      currencies: zod.z.array(zod.z.string()),
+      payeeHint: zod.z.string(),
+      requiresIdentityAttestation: zod.z.boolean()
+    })
+  ),
+  currencies: zod.z.array(zod.z.string()),
+  amount: zod.z.object({ min: bigintString, recommendedMin: bigintString, max: zod.z.null() }),
+  pricing: zod.z.object({ kind: zod.z.literal("oracle-market-rate"), spreadBps: zod.z.literal(0) })
+});
+var cashErrorJsonSchema = zod.z.object({
+  code: zod.z.string(),
+  message: zod.z.string(),
+  retryable: zod.z.boolean(),
+  remediation: zod.z.string()
+});
+
+// src/codecs/json.ts
+function omitUndefined(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+function fillToJson(fill) {
+  return omitUndefined({
+    intentHash: fill.intentHash,
+    status: fill.status,
+    amount: fill.amount.toString(),
+    buyer: fill.buyer,
+    currency: fill.currency,
+    currencyHash: fill.currencyHash,
+    rate: fill.rate,
+    conversionRate: fill.conversionRate?.toString(),
+    fiatOwed: fill.fiatOwed,
+    fiatPaid: fill.fiatPaid,
+    paidCurrency: fill.paidCurrency,
+    paymentId: fill.paymentId,
+    paidAt: fill.paidAt,
+    releasedAmount: fill.releasedAmount?.toString(),
+    fillLatencySeconds: fill.fillLatencySeconds,
+    isExpired: fill.isExpired,
+    signaledAt: fill.signaledAt,
+    expiresAt: fill.expiresAt,
+    fulfilledAt: fill.fulfilledAt,
+    prunedAt: fill.prunedAt
+  });
+}
+function fillFromJson(json) {
+  return omitUndefined({
+    ...json,
+    amount: BigInt(json.amount),
+    conversionRate: json.conversionRate !== void 0 ? BigInt(json.conversionRate) : void 0,
+    releasedAmount: json.releasedAmount !== void 0 ? BigInt(json.releasedAmount) : void 0
+  });
+}
+function orderToJson(order) {
+  return omitUndefined({
+    depositId: order.depositId,
+    state: order.state,
+    fills: order.fills.map(fillToJson),
+    totalAmount: order.totalAmount.toString(),
+    filledAmount: order.filledAmount.toString(),
+    pendingAmount: order.pendingAmount.toString(),
+    returnedAmount: order.returnedAmount.toString(),
+    nextActions: order.nextActions,
+    primaryIntentHash: order.primaryIntentHash,
+    matchedAt: order.matchedAt,
+    deliveredAt: order.deliveredAt,
+    updatedAt: order.updatedAt,
+    intentCount: order.intentCount,
+    payouts: order.payouts?.map(
+      (p) => omitUndefined({ ...p, pricing: omitUndefined({ ...p.pricing }) })
+    ),
+    successRateBps: order.successRateBps,
+    isInFlight: order.isInFlight,
+    withdrawn: order.withdrawn
+  });
+}
+function orderFromJson(json) {
+  const parsed = cashOrderJsonSchema.parse(json);
+  const data = omitUndefined({
+    ...parsed,
+    fills: parsed.fills.map(fillFromJson),
+    totalAmount: BigInt(parsed.totalAmount),
+    filledAmount: BigInt(parsed.filledAmount),
+    pendingAmount: BigInt(parsed.pendingAmount),
+    returnedAmount: BigInt(parsed.returnedAmount)
+  });
+  return withExplain(data);
+}
+function estimateToJson(estimate) {
+  return { ...estimate, amount: estimate.amount.toString() };
+}
+function estimateFromJson(json) {
+  const parsed = cashEstimateJsonSchema.parse(json);
+  return omitUndefined({
+    ...parsed,
+    currency: parsed.currency,
+    amount: BigInt(parsed.amount)
+  });
+}
+function preparedTxToJson(tx) {
+  return { to: tx.to, data: tx.data, value: tx.value.toString(), chainId: tx.chainId };
+}
+function preparedTxFromJson(json) {
+  const parsed = preparedTransactionJsonSchema.parse(json);
+  return {
+    to: parsed.to,
+    data: parsed.data,
+    value: BigInt(parsed.value),
+    chainId: parsed.chainId
+  };
+}
+function preparedStepToJson(step) {
+  return { kind: step.kind, description: step.description };
+}
+function preparedStepFromJson(json) {
+  return cashPreparedStepJsonSchema.parse(json);
+}
+function cashoutResultToJson(result) {
+  return {
+    depositId: result.depositId,
+    txHash: result.txHash,
+    escrowAddress: result.escrowAddress,
+    onchainDepositId: result.onchainDepositId.toString(),
+    order: orderToJson(result.order)
+  };
+}
+function cashoutResultFromJson(json) {
+  const parsed = cashoutResultJsonSchema.parse(json);
+  return {
+    depositId: parsed.depositId,
+    txHash: parsed.txHash,
+    escrowAddress: parsed.escrowAddress,
+    onchainDepositId: BigInt(parsed.onchainDepositId),
+    order: orderFromJson(parsed.order)
+  };
+}
+function prepareResultToJson(result) {
+  return {
+    txs: result.txs.map(preparedTxToJson),
+    steps: result.steps.map(preparedStepToJson),
+    register: result.register
+  };
+}
+function prepareResultFromJson(json) {
+  const parsed = prepareResultJsonSchema.parse(json);
+  return {
+    txs: parsed.txs.map(preparedTxFromJson),
+    steps: parsed.steps.map(preparedStepFromJson),
+    register: parsed.register
+  };
+}
+function withdrawResultToJson(result) {
+  return omitUndefined({
+    depositId: result.depositId,
+    pruneTxHash: result.pruneTxHash,
+    withdrawTxHash: result.withdrawTxHash
+  });
+}
+function withdrawResultFromJson(json) {
+  const parsed = withdrawResultJsonSchema.parse(json);
+  return omitUndefined({
+    depositId: parsed.depositId,
+    pruneTxHash: parsed.pruneTxHash,
+    withdrawTxHash: parsed.withdrawTxHash
+  });
+}
+function buyerProfileToJson(profile) {
+  return omitUndefined({ ...profile });
+}
+function buyerProfileFromJson(json) {
+  return omitUndefined(cashBuyerProfileJsonSchema.parse(json));
+}
+function topUpResultToJson(result) {
+  return { depositId: result.depositId, txHash: result.txHash };
+}
+function topUpResultFromJson(json) {
+  const parsed = topUpResultJsonSchema.parse(json);
+  return { depositId: parsed.depositId, txHash: parsed.txHash };
+}
+function capabilitiesToJson(caps) {
+  return {
+    ...caps,
+    amount: {
+      min: caps.amount.min.toString(),
+      recommendedMin: caps.amount.recommendedMin.toString(),
+      max: null
+    }
+  };
+}
+function capabilitiesFromJson(json) {
+  const parsed = cashCapabilitiesJsonSchema.parse(json);
+  return {
+    ...parsed,
+    platforms: parsed.platforms.map((p) => ({
+      ...p,
+      currencies: p.currencies
+    })),
+    currencies: parsed.currencies,
+    amount: {
+      min: BigInt(parsed.amount.min),
+      recommendedMin: BigInt(parsed.amount.recommendedMin),
+      max: null
+    }
+  };
+}
+
+exports.BASE_CHAIN_ID = BASE_CHAIN_ID;
+exports.BASE_USDC_ADDRESS = BASE_USDC_ADDRESS;
+exports.CASH_ATTRIBUTION_CODE = CASH_ATTRIBUTION_CODE;
+exports.CASH_ORDER_POLL_INTERVAL_MS = CASH_ORDER_POLL_INTERVAL_MS;
+exports.CASH_ORDER_STATUSES = CASH_ORDER_STATUSES;
+exports.CASH_RETAIN_ON_EMPTY = CASH_RETAIN_ON_EMPTY;
+exports.CashError = CashError;
+exports.MARKET_SPREAD_BPS = MARKET_SPREAD_BPS;
+exports.MIN_CASHOUT_AMOUNT = MIN_CASHOUT_AMOUNT;
+exports.ORACLE_MIN_CONVERSION_RATE_SENTINEL = ORACLE_MIN_CONVERSION_RATE_SENTINEL;
+exports.RATE_PRECISION = RATE_PRECISION;
+exports.RECOMMENDED_MIN_CASHOUT_AMOUNT = RECOMMENDED_MIN_CASHOUT_AMOUNT;
+exports.USDC_DECIMALS = USDC_DECIMALS;
+exports.bigintString = bigintString;
+exports.buildCapabilities = buildCapabilities;
+exports.buildIntentAmountRange = buildIntentAmountRange;
+exports.buildMarketRateCurrencyOverride = buildMarketRateCurrencyOverride;
+exports.buyerProfileFromJson = buyerProfileFromJson;
+exports.buyerProfileToJson = buyerProfileToJson;
+exports.capabilitiesFromJson = capabilitiesFromJson;
+exports.capabilitiesToJson = capabilitiesToJson;
+exports.cashBuyerProfileJsonSchema = cashBuyerProfileJsonSchema;
+exports.cashCapabilitiesJsonSchema = cashCapabilitiesJsonSchema;
+exports.cashErrorJsonSchema = cashErrorJsonSchema;
+exports.cashEstimateJsonSchema = cashEstimateJsonSchema;
+exports.cashFillJsonSchema = cashFillJsonSchema;
+exports.cashNextActionSchema = cashNextActionSchema;
+exports.cashOrderJsonSchema = cashOrderJsonSchema;
+exports.cashOrderStateSchema = cashOrderStateSchema;
+exports.cashPayoutInfoJsonSchema = cashPayoutInfoJsonSchema;
+exports.cashPayoutPricingJsonSchema = cashPayoutPricingJsonSchema;
+exports.cashPreparedStepJsonSchema = cashPreparedStepJsonSchema;
+exports.cashoutResultFromJson = cashoutResultFromJson;
+exports.cashoutResultJsonSchema = cashoutResultJsonSchema;
+exports.cashoutResultToJson = cashoutResultToJson;
+exports.centsToNumber = centsToNumber;
+exports.createCashClient = createCashClient;
+exports.deriveBuyerProfile = deriveBuyerProfile;
+exports.deriveCashOrder = deriveCashOrder;
+exports.derivePayouts = derivePayouts;
+exports.errors = errors;
+exports.estimateFromJson = estimateFromJson;
+exports.estimateToJson = estimateToJson;
+exports.explainOrder = explainOrder;
+exports.fiatFromUsdc = fiatFromUsdc;
+exports.fiatToNumber = fiatToNumber;
+exports.fillFromJson = fillFromJson;
+exports.fillToJson = fillToJson;
+exports.formatUsdc = formatUsdc;
+exports.intentStatusSchema = intentStatusSchema;
+exports.isCashError = isCashError;
+exports.isFillLive = isFillLive;
+exports.isMarketRateSupported = isMarketRateSupported;
+exports.orderFromJson = orderFromJson;
+exports.orderToJson = orderToJson;
+exports.parseCompositeDepositId = parseCompositeDepositId;
+exports.prepareCashDepositParams = prepareCashDepositParams;
+exports.prepareResultFromJson = prepareResultFromJson;
+exports.prepareResultJsonSchema = prepareResultJsonSchema;
+exports.prepareResultToJson = prepareResultToJson;
+exports.preparedStepFromJson = preparedStepFromJson;
+exports.preparedStepToJson = preparedStepToJson;
+exports.preparedTransactionJsonSchema = preparedTransactionJsonSchema;
+exports.preparedTxFromJson = preparedTxFromJson;
+exports.preparedTxToJson = preparedTxToJson;
+exports.rateToNumber = rateToNumber;
+exports.resolveCashDepositId = resolveCashDepositId;
+exports.topUpResultFromJson = topUpResultFromJson;
+exports.topUpResultJsonSchema = topUpResultJsonSchema;
+exports.topUpResultToJson = topUpResultToJson;
+exports.usdc = usdc;
+exports.withExplain = withExplain;
+exports.withdrawResultFromJson = withdrawResultFromJson;
+exports.withdrawResultJsonSchema = withdrawResultJsonSchema;
+exports.withdrawResultToJson = withdrawResultToJson;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map