@zkp2p/cash 0.1.0-dev.0

package/dist/createCashClient-DpAx9A1A.d.ts

@@ -0,0 +1,449 @@
+import { Address, WalletClient, Hash, Transport } from 'viem';
+import { IndexerIntentStatus, Zkp2pClient, IndexerIntent, CurrencyType, RuntimeEnv, PreparedTransaction } from '@zkp2p/sdk';
+
+/**
+ * Name-mapping shim over the published `@zkp2p/sdk` (^0.8).
+ *
+ * The reference implementation imported these from internal SDK paths; the
+ * published package exports them under indexer-prefixed names, and one type
+ * (`CuratorPayeeDataInput`) is not exported at all - it is recovered here from
+ * the `registerPayeeDetails` method signature. Everything else in this package
+ * imports SDK types from this module so the mapping lives in exactly one place.
+ */
+
+type IntentStatus = IndexerIntentStatus;
+type IntentEntity = IndexerIntent;
+type CuratorPayeeDataInput = NonNullable<Parameters<Zkp2pClient['registerPayeeDetails']>[0]['payeeData']>[number];
+type CreateDepositParamsArg = Parameters<Zkp2pClient['createDeposit']>[0];
+
+/**
+ * Peer Cash - public domain types for the engine.
+ */
+
+/**
+ * The lifecycle state of a cash-out, derived purely from on-chain-observable
+ * intent events against the user's deposit.
+ *
+ * - `awaiting-buyer` - deposit is live, no buyer has signaled yet.
+ * - `matched` - a buyer signaled an intent (`SIGNALED`); fiat not yet proven.
+ * - `delivering` - partial fill in progress (some intents fulfilled, some still signaled).
+ * - `delivered` - fiat paid + proven, escrow released (`FULFILLED`).
+ * - `returned` - buyer didn't deliver; intent pruned, deposit recoverable/recovered.
+ */
+type CashOrderState = 'awaiting-buyer' | 'matched' | 'delivering' | 'delivered' | 'returned';
+/** What the caller can do next. The lifecycle is self-driving - no consumer heuristics. */
+type CashNextAction = 'wait' | 'withdraw';
+/**
+ * One buyer's intent against the deposit (one "fill"). The order id is the
+ * `intentHash`. Hashes are decoded to human units wherever the protocol
+ * catalogs know them; the raw values stay available for anything unknown.
+ */
+interface CashFill {
+    /** The order id once a buyer has signaled. */
+    intentHash: string;
+    status: IntentStatus;
+    /** Intent amount in USDC base units (6 decimals). */
+    amount: bigint;
+    /** The buyer (taker) address. */
+    buyer: string;
+    /** Decoded fiat currency code the buyer pays in, e.g. `'EUR'`. */
+    currency?: string;
+    /** Raw on-chain currency hash (bytes32), for anything the catalog can't decode. */
+    currencyHash?: string;
+    /** Fiat per USDC locked at signal time - the binding rate for THIS fill. */
+    rate?: number;
+    /** Raw locked conversion rate (1e18 precision). */
+    conversionRate?: bigint;
+    /** Fiat the buyer must send: `amount × rate`, rounded up to the cent. */
+    fiatOwed?: number;
+    /** Verified receipt - actual fiat paid, from the payment proof. */
+    fiatPaid?: number;
+    /** Verified receipt - decoded currency actually paid (may differ from `currency`). */
+    paidCurrency?: string;
+    /** Verified receipt - the platform's external payment id. */
+    paymentId?: string;
+    /** Verified receipt - unix seconds the fiat payment was made. */
+    paidAt?: number;
+    /** USDC actually released from escrow for this fill (gross, base units). */
+    releasedAmount?: bigint;
+    /** Seconds from buyer signal to proven delivery. */
+    fillLatencySeconds?: number;
+    /** Indexer reconciler flag: the intent's window has lapsed on-chain. */
+    isExpired?: boolean;
+    /** Unix seconds - when the buyer signaled (matched). */
+    signaledAt?: number;
+    /** Unix seconds - when the signaled intent expires and becomes prunable. */
+    expiresAt?: number;
+    /** Unix seconds - when fiat was proven and escrow released (delivered). */
+    fulfilledAt?: number;
+    /** Unix seconds - when the intent expired and was pruned (returned). */
+    prunedAt?: number;
+}
+/** Pricing state of one payout tuple - the zero-spread claim, verifiable from indexed data. */
+interface CashPayoutPricing {
+    /** Depositor-configured spread markup in basis points (0 for every cash order). */
+    spreadBps?: number;
+    /** Oracle kind, e.g. `'oracle_chainlink'`. */
+    kind?: string;
+    /** Which source currently binds the rate: `ORACLE` | `MANAGER` | `ESCROW_FLOOR` | …. */
+    rateSource?: string;
+    /** Current oracle rate (fiat per USDC), decoded from 1e18. */
+    oracleRate?: number;
+    /** Unix seconds of the last accepted oracle snapshot. */
+    lastOracleUpdatedAt?: number;
+    /** True when the tuple is priced by an oracle at zero spread - the Peer Cash invariant. */
+    marketRate: boolean;
+}
+/** One payout leg reconstructed from the chain - platform, currency, payee hash, pricing. */
+interface CashPayoutInfo {
+    /** Decoded platform id, e.g. `'venmo'` (undefined if the catalog doesn't know the hash). */
+    platform?: string;
+    /** Raw payment method hash (bytes32). */
+    platformHash: string;
+    /** Decoded fiat currency code, e.g. `'USD'`. */
+    currency?: string;
+    /** Raw currency hash (bytes32). */
+    currencyHash?: string;
+    /** Hashed payee details (the handle itself never touches the chain). */
+    payeeHash: string;
+    /** Whether the method still accepts new intents. */
+    active: boolean;
+    pricing: CashPayoutPricing;
+}
+/**
+ * The full, resumable view of a cash-out order, reconstructed from the indexer
+ * by `depositId` alone - survives a closed tab, new device, or wallet reconnect.
+ */
+interface CashOrder {
+    /** Composite deposit id (`escrow_onchainId`) - the resume key. */
+    depositId: string;
+    state: CashOrderState;
+    /** Every buyer intent against the deposit (>1 only for partial fills). */
+    fills: CashFill[];
+    /** Deposit amount in USDC base units. */
+    totalAmount: bigint;
+    /** Sum of fulfilled (delivered) intent amounts. */
+    filledAmount: bigint;
+    /** Sum of signaled-but-not-yet-fulfilled intent amounts. */
+    pendingAmount: bigint;
+    /** Sum returned (withdrawn) to the maker. */
+    returnedAmount: bigint;
+    /** Self-driving lifecycle - what the caller can do right now. */
+    nextActions: CashNextAction[];
+    /** The primary order id (first/active intent's `intentHash`) once matched. */
+    primaryIntentHash?: string;
+    /** Unix seconds - earliest signal (first match). */
+    matchedAt?: number;
+    /** Unix seconds - latest fulfilment (delivery). */
+    deliveredAt?: number;
+    /** Unix seconds - when the deposit last changed on-chain. */
+    updatedAt?: number;
+    /** Total number of buyer intents against the deposit (from the indexer aggregate). */
+    intentCount?: number;
+    /**
+     * Payout legs reconstructed from the chain (platform, currency, payee hash,
+     * pricing proof). Present on `order()`; absent on `orders()` list rows.
+     */
+    payouts?: CashPayoutInfo[];
+    /** Deposit quality signal takers see (basis points, 0–10000; new deposits start at 10000). */
+    successRateBps?: number;
+    /** True while the order still needs the user's attention / a buyer to act. */
+    isInFlight: boolean;
+    /** Whether the deposit has been withdrawn on-chain (terminal return). */
+    withdrawn?: boolean;
+    /** One honest sentence from live data - never a fake countdown. */
+    explain(): string;
+}
+/** A buyer's protocol track record, aggregated from their full intent history. */
+interface CashBuyerProfile {
+    address: string;
+    /** Lifetime intents this buyer has signaled (all statuses). */
+    totalIntents: number;
+    /** Intents completed: fiat paid, proven, escrow released. */
+    fulfilled: number;
+    /** Intents that expired unpaid and were pruned. */
+    pruned: number;
+    /** Intents currently open. */
+    signaled: number;
+    /** fulfilled / (fulfilled + pruned) in basis points; undefined until they have history. */
+    successRateBps?: number;
+    /** Unix seconds of the buyer's first and latest signal. */
+    firstSeenAt?: number;
+    lastSeenAt?: number;
+}
+/** A single payout leg of a cash-out (one platform + currency + payee). */
+interface CashPayout {
+    /** Payment platform / processor name, e.g. `'venmo'`, `'revolut'`, `'wise'`. */
+    processorName: string;
+    /** Fiat currency the user wants to receive. */
+    currency: CurrencyType;
+    /** The user's payee handle for that platform (e.g. a Venmo username, Wisetag). */
+    payeeData: CuratorPayeeDataInput;
+}
+/**
+ * Input to create a market-rate (0% spread) cash-out deposit.
+ *
+ * Deliberately narrow: no rate/spread knobs, no vault/DRM delegate, no
+ * retain-on-empty override - a cash-out is a one-shot order that cleans up
+ * when fully filled. The API cannot express what Peer Cash does not offer.
+ */
+interface CashDepositInput {
+    /** Deposit asset - Base USDC (defaults to {@link BASE_USDC_ADDRESS}). */
+    token?: Address;
+    /** Total amount to cash out, in USDC base units (6 decimals). */
+    amount: bigint;
+    /** One or more payout legs (platform + currency + payee). */
+    payouts: CashPayout[];
+    /** Per-order min/max in USDC base units. Defaults derive from {@link buildIntentAmountRange}. */
+    intentAmountRange?: {
+        min: bigint;
+        max: bigint;
+    };
+}
+
+/** Hard floor: below one cent a deposit is dust and can never fill. */
+declare const MIN_CASHOUT_AMOUNT = 10000n;
+/** Recommended floor: sub-1-USDC deposits force min==max fills and starve matching. */
+declare const RECOMMENDED_MIN_CASHOUT_AMOUNT = 1000000n;
+interface CashPlatformCapability {
+    /** Platform id, e.g. `'venmo'` - the value `receive.platform` accepts. */
+    platform: string;
+    /** Market-rate (oracle-priced) currencies this platform can pay out. */
+    currencies: CurrencyType[];
+    /** Human hint for the payee handle format. */
+    payeeHint: string;
+    /**
+     * When true, registering a payee for this platform requires a signed maker
+     * identity attestation the SDK cannot produce - register the payee via the
+     * ZKP2P app/extension first. A bare-handle `cashout()` throws
+     * `PAYEE_VERIFICATION_REQUIRED`.
+     */
+    requiresIdentityAttestation: boolean;
+}
+interface CashCapabilities {
+    chainId: number;
+    token: {
+        address: string;
+        symbol: 'USDC';
+        decimals: number;
+    };
+    environment: RuntimeEnv;
+    /** Every payout corridor: platform × oracle-priced currencies. */
+    platforms: CashPlatformCapability[];
+    /** All oracle-priced (market-rate) currencies across platforms. */
+    currencies: CurrencyType[];
+    /** Amount bounds in USDC base units. */
+    amount: {
+        min: bigint;
+        recommendedMin: bigint;
+        max: null;
+    };
+    /** Pricing is always the live oracle at fill time - never a committed quote. */
+    pricing: {
+        kind: 'oracle-market-rate';
+        spreadBps: 0;
+    };
+}
+declare function buildCapabilities(environment: RuntimeEnv): CashCapabilities;
+
+/**
+ * Estimate - currency + amount only. No payee, no side effects, no expiry,
+ * idempotent, cacheable. "≈ at whatever the oracle says when a buyer fills."
+ *
+ * Reads the same Chainlink feed the protocol prices the deposit against, so
+ * there is no external FX dependency. USD is a zero-address passthrough
+ * (USDC ≈ USD). The binding rate resolves on-chain at fill time.
+ */
+
+interface EstimateInput {
+    /** Amount to cash out, USDC base units (6 decimals). Use `usdc()` to build it. */
+    amount: bigint;
+    /** Target fiat currency. */
+    currency: CurrencyType;
+}
+interface CashEstimate {
+    /** Always `'oracle-estimate'` - there is no committed quote in Peer Cash. */
+    kind: 'oracle-estimate';
+    currency: CurrencyType;
+    /** The input amount, USDC base units. */
+    amount: bigint;
+    /** Target-currency units per 1 USDC at the time of the read. */
+    rate: number;
+    /** `amount × rate` in target-currency units. */
+    receiveAmount: number;
+    /** Unix seconds when the oracle was read. */
+    asOf: number;
+    /** Unix seconds the Chainlink feed last updated (absent for the USD passthrough). */
+    oracleUpdatedAt?: number;
+    /** True when the feed reading is older than a day - treat the rate with caution. */
+    stale?: boolean;
+}
+
+/**
+ * `createCashClient` - the eight-verb facade over a read-only `Zkp2pClient`.
+ *
+ * The facade keeps the outward surface tiny (capabilities / estimate / cashout
+ * / order / orders / watch / withdraw / topUp) while reusing the published
+ * SDK's battle-tested internals. A React app, a Node service, and an AI agent
+ * are equal consumers: every mutating verb has an unsigned `prepare` path,
+ * every wire type is serializable, and every transaction carries ERC-8021
+ * attribution ({@link CASH_ATTRIBUTION_CODE}).
+ */
+
+/**
+ * ERC-8021 attribution code stamped on every transaction this package
+ * produces (signed and prepare paths, including approves). Integrator codes
+ * from `CashClientOptions.referrer` are appended after it; the SDK always
+ * appends the Base builder code last.
+ */
+declare const CASH_ATTRIBUTION_CODE = "peer-cash";
+interface CashClientOptions {
+    /** `'production' | 'preproduction' | 'staging'` - selects contracts, curator, and indexer. */
+    environment: RuntimeEnv;
+    /** viem transport for RPC reads; defaults to the public Base RPC. */
+    transport?: Transport;
+    /** Convenience alternative to `transport`. */
+    rpcUrl?: string;
+    /** Indexer URL override. */
+    indexerUrl?: string;
+    /** Curator (ZKP2P API) URL override. */
+    curatorUrl?: string;
+    /** Optional ZKP2P API key. */
+    apiKey?: string;
+    /**
+     * Your own ERC-8021 attribution code(s), appended after
+     * {@link CASH_ATTRIBUTION_CODE} on every transaction (e.g. `'acme-app'`).
+     */
+    referrer?: string | string[];
+}
+/** One payout leg: platform + currency + payee handle. */
+interface CashLeg {
+    /** Platform id from `capabilities()`, e.g. `'venmo'`. */
+    platform: string;
+    /** Fiat currency to receive. */
+    currency: CurrencyType;
+    /** Payee details, e.g. `{ offchainId: '@andrew' }`. */
+    payee: CuratorPayeeDataInput;
+}
+interface CashoutInput {
+    /** Amount to cash out, USDC base units. Use `usdc()` to build it. */
+    amount: bigint;
+    /** Where the fiat should arrive. Multi-payout is a deliberate v1 cut. */
+    receive: CashLeg;
+    /** Per-order min/max override (USDC base units). */
+    intentAmountRange?: {
+        min: bigint;
+        max: bigint;
+    };
+}
+interface SignerOptions {
+    /** A viem WalletClient with an account, on Base. */
+    signer: WalletClient;
+}
+interface WithdrawOptions extends SignerOptions {
+    /**
+     * Partial amount to withdraw (USDC base units). Only unlocked funds are
+     * withdrawable partially - a live buyer intent does not block it. Omit to
+     * close the order fully (prunes expired intents first when needed).
+     */
+    amount?: bigint;
+}
+interface TopUpResult {
+    depositId: string;
+    txHash: Hash;
+}
+type CashPreparedStepKind = 'approve' | 'createDeposit' | 'pruneExpiredIntents' | 'withdrawDeposit' | 'removeFunds' | 'addFunds';
+interface CashPreparedStep {
+    /** Stable action label for the transaction at the same index in `txs[]`. */
+    kind: CashPreparedStepKind;
+    /** Human-readable reason to show in approval UIs, logs, or policy reviews. */
+    description: string;
+}
+interface CashoutResult {
+    /** Composite deposit id (`escrow_onchainId`) - the resume key. Bind it to your user. */
+    depositId: string;
+    txHash: Hash;
+    escrowAddress: string;
+    onchainDepositId: bigint;
+    /** Optimistic snapshot (`awaiting-buyer`); poll `order(depositId)` for live state. */
+    order: CashOrder;
+}
+interface PrepareResult {
+    /**
+     * Unsigned transactions in submission order: `[approve, createDeposit]`.
+     * Submit with any signer - agent wallet, AA bundler, server key. Drop the
+     * approve when the escrow already has sufficient allowance.
+     */
+    txs: PreparedTransaction[];
+    /** One label per transaction in `txs[]`, same order. */
+    steps: CashPreparedStep[];
+    /** Curator payee registration output - the payee hashes now live on the deposit params. */
+    register: {
+        hashedOnchainIds: string[];
+    };
+}
+interface WithdrawResult {
+    depositId: string;
+    /** Present when expired intents had to be pruned before withdrawal. */
+    pruneTxHash?: Hash;
+    withdrawTxHash: Hash;
+}
+interface WatchOptions {
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+interface OrdersOptions {
+    /** Only orders still needing attention (`awaiting-buyer` / `matched` / `delivering`). */
+    inFlight?: boolean;
+    /** Max deposits to scan (default 100). */
+    limit?: number;
+}
+interface CashClient {
+    /** 0 - Discovery: sync, static. */
+    capabilities(): CashCapabilities;
+    /** 1 - Estimate: currency + amount only. No payee, no side effects, no expiry. */
+    estimate(input: EstimateInput): Promise<CashEstimate>;
+    /** 2 - Cash out: payee registration + deposit params + submission happen here. */
+    cashout(input: CashoutInput, opts: SignerOptions): Promise<CashoutResult>;
+    /** 2b - Unsigned path: `txs[]` for agent wallets, AA, server keys, policy layers. */
+    prepare(input: CashoutInput): Promise<PrepareResult>;
+    /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
+    order(depositId: string): Promise<CashOrder>;
+    /**
+     * 3b - Observe helper: a buyer's protocol track record from their full
+     * intent history. Answers "who just matched my order?" during `matched`.
+     */
+    buyer(address: string): Promise<CashBuyerProfile>;
+    /** 4 - List: indexer-native. A cash order IS a deposit; the chain is the database. */
+    orders(owner: string, opts?: OrdersOptions): Promise<CashOrder[]>;
+    /** 5 - Watch: yields on change; ends at a terminal state, abort, or timeout. */
+    watch(depositId: string, opts?: WatchOptions): AsyncGenerator<CashOrder, void, void>;
+    /**
+     * 6 - Withdraw: ONE unwind verb. With `amount`, withdraws that much of the
+     * unlocked balance (partial; a live buyer intent does not block it).
+     * Without, closes the order fully - pruning expired intents first when
+     * needed.
+     */
+    withdraw(depositId: string, opts: WithdrawOptions): Promise<WithdrawResult>;
+    /**
+     * 6b - Unsigned path for the unwind verb (agent surface): the same state
+     * checks as `withdraw()`, returning `txs[]` for host-side signing.
+     */
+    prepareWithdraw(depositId: string, opts?: {
+        amount?: bigint;
+    }): Promise<{
+        txs: PreparedTransaction[];
+        steps: CashPreparedStep[];
+    }>;
+    /** 7 - Top up: add USDC to a live order (same payee, same market rate). */
+    topUp(depositId: string, amount: bigint, opts: SignerOptions): Promise<TopUpResult>;
+    /** 7b - Unsigned path: `[approve, addFunds]` for host-side signing. */
+    prepareTopUp(depositId: string, amount: bigint): Promise<{
+        txs: PreparedTransaction[];
+        steps: CashPreparedStep[];
+    }>;
+}
+declare function createCashClient(options: CashClientOptions): CashClient;
+
+export { type CashPayoutInfo as C, type EstimateInput as E, type IntentStatus as I, MIN_CASHOUT_AMOUNT as M, type OrdersOptions as O, type PrepareResult as P, RECOMMENDED_MIN_CASHOUT_AMOUNT as R, type SignerOptions as S, type TopUpResult as T, type WithdrawResult as W, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashPreparedStep as j, CASH_ATTRIBUTION_CODE as k, type CashClient as l, type CashClientOptions as m, type CashLeg as n, type CashNextAction as o, type CashOrderState as p, type CashPayout as q, type CashPayoutPricing as r, type CashPlatformCapability as s, type CashPreparedStepKind as t, type CashoutInput as u, type CuratorPayeeDataInput as v, type WatchOptions as w, type WithdrawOptions as x, buildCapabilities as y, createCashClient as z };