@zkp2p/cash 0.1.2 → 0.1.4

package/dist/chunk-P3KYZ2FX.js

@@ -0,0 +1,373 @@
+// 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;
+
+// src/client/errors.ts
+var CashError = class extends Error {
+  code;
+  retryable;
+  remediation;
+  recovery;
+  constructor(shape, options) {
+    super(shape.message, options);
+    this.name = "CashError";
+    this.code = shape.code;
+    this.retryable = shape.retryable;
+    this.remediation = shape.remediation;
+    if (shape.recovery) this.recovery = shape.recovery;
+  }
+  /** Serializable view (for tool results and logs). */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      remediation: this.remediation,
+      ...this.recovery ? { recovery: this.recovery } : {}
+    };
+  }
+};
+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.`
+  }),
+  oracleReadFailed: (currency, cause) => new CashError(
+    {
+      code: "ORACLE_READ_FAILED",
+      message: `The ${currency} market-rate oracle could not be read.`,
+      retryable: true,
+      remediation: `Retry the estimate shortly or use another healthy Base RPC. Do not present a cached value as a live market rate.`
+    },
+    { cause }
+  ),
+  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().`
+  }),
+  unsupportedPlatformCurrency: (platform, currency) => new CashError({
+    code: "UNSUPPORTED_PLATFORM_CURRENCY",
+    message: `${platform} cannot receive ${currency} in this environment.`,
+    retryable: false,
+    remediation: `Pick one of the currencies listed for ${platform} 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).`
+  }),
+  invalidIntentAmountRange: (amount, min, max) => new CashError({
+    code: "INVALID_INTENT_AMOUNT_RANGE",
+    message: `Intent amount range ${min}-${max} is invalid for a ${amount} base-unit cash-out.`,
+    retryable: false,
+    remediation: `Use a positive minimum no greater than the maximum, and a maximum no greater than the cash-out amount.`
+  }),
+  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.`
+  }),
+  insufficientTokenBalance: (requiredAmount) => new CashError({
+    code: "INSUFFICIENT_TOKEN_BALANCE",
+    message: requiredAmount === void 0 ? `The wallet does not hold enough of the source token for this transaction.` : `The wallet does not hold the ${requiredAmount} base units required for this transaction.`,
+    retryable: false,
+    remediation: requiredAmount === void 0 ? `Fund the wallet with the required token amount, then retry.` : `Fund the wallet to at least ${requiredAmount} token base units, then retry.`
+  }),
+  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.`
+  }),
+  invalidDepositId: (depositId, cause) => new CashError(
+    {
+      code: "INVALID_DEPOSIT_ID",
+      message: `'${depositId}' is not a valid Peer Cash deposit id.`,
+      retryable: false,
+      remediation: `Use the depositId returned by cashout() (escrowAddress_onchainDepositId) without modifying it.`
+    },
+    { cause }
+  ),
+  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.`
+  }),
+  indexerUnavailable: (operation, cause) => new CashError(
+    {
+      code: "INDEXER_UNAVAILABLE",
+      message: `The protocol indexer could not complete the ${operation} query.`,
+      retryable: true,
+      remediation: `Retry shortly. Keep the composite depositId or owner address so the read can resume without repeating an on-chain transaction.`
+    },
+    { cause }
+  ),
+  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 }
+  ),
+  sourceRouteUnsupportedInPrepare: () => new CashError({
+    code: "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE",
+    message: `prepare() cannot execute a Relay source route before creating the Base USDC cash-out.`,
+    retryable: false,
+    remediation: `Use cashout(inputWithSource, { signer }) for the one-call bridge-then-cashout flow, or call quoteSource()/executeSourceQuote() first and then prepare() a Base USDC cash-out.`
+  }),
+  sourceRecipientMismatch: (recipient, owner) => new CashError({
+    code: "SOURCE_RECIPIENT_MISMATCH",
+    message: `Source recipient ${recipient} does not match the cash-out depositor ${owner}.`,
+    retryable: false,
+    remediation: `For one-call source cashout, deliver Relay output to the depositor address. For a different recipient, bridge first and then cash out from that recipient's signer.`
+  }),
+  sourceCapabilitiesFailed: (cause) => new CashError(
+    {
+      code: "SOURCE_CAPABILITIES_FAILED",
+      message: `Relay source-chain discovery failed.`,
+      retryable: true,
+      remediation: `Retry sourceCapabilities() shortly, or use the default Base USDC path.`
+    },
+    { cause }
+  ),
+  sourceQuoteFailed: (cause) => new CashError(
+    {
+      code: "SOURCE_QUOTE_FAILED",
+      message: `Relay did not return a valid route to canonical Base USDC.`,
+      retryable: true,
+      remediation: `Refresh source capabilities and request a new quote. Do not submit transactions from this response.`
+    },
+    { cause }
+  ),
+  sourceExecutionFailed: (cause, evidence) => new CashError(
+    {
+      code: "SOURCE_EXECUTION_FAILED",
+      message: `Relay source-route execution did not complete successfully.`,
+      retryable: false,
+      remediation: `Inspect the wallet transactions and Relay request status before retrying so the source transfer is never submitted twice.`,
+      ...evidence && (evidence.requestId !== void 0 || evidence.txHashes.length > 0) ? {
+        recovery: {
+          kind: "inspect-relay-route",
+          ...evidence.requestId ? { requestId: evidence.requestId } : {},
+          txHashes: evidence.txHashes,
+          ...evidence.transactions ? { transactions: evidence.transactions } : {}
+        }
+      } : {}
+    },
+    { cause }
+  ),
+  sourceStatusFailed: (requestId, cause) => new CashError(
+    {
+      code: "SOURCE_STATUS_FAILED",
+      message: `Relay status is unavailable for request ${requestId}.`,
+      retryable: true,
+      remediation: `Retry relayStatus(requestId) shortly; keep the request id and transaction hashes for recovery.`
+    },
+    { cause }
+  ),
+  sourceRouteCompletedCashoutFailed: (source, cause) => new CashError(
+    {
+      code: "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED",
+      message: `Relay completed, but the Base USDC cash-out transaction was not created.`,
+      retryable: false,
+      remediation: `Do not repeat the Relay route. Retry cashout() without source using the recovery amount already delivered on Base.`,
+      recovery: {
+        kind: "retry-base-usdc-cashout",
+        amount: source.amount.toString(),
+        ...source.requestId ? { requestId: source.requestId } : {},
+        txHashes: source.txHashes,
+        ...source.transactions ? { transactions: source.transactions } : {}
+      }
+    },
+    { cause }
+  ),
+  sourceCashoutSubmissionUnknown: (source, depositor, cause) => new CashError(
+    {
+      code: "SOURCE_CASHOUT_SUBMISSION_UNKNOWN",
+      message: `Relay completed, but the Base cash-out submission did not return a transaction hash.`,
+      retryable: false,
+      remediation: `Do not repeat Relay or submit another cash-out yet. Inspect recent Base transactions and orders(${depositor}) to prove no deposit was broadcast; only then retry Base-USDC-only with the recovery amount.`,
+      recovery: {
+        kind: "inspect-base-cashout-submission",
+        amount: source.amount.toString(),
+        ...source.requestId ? { requestId: source.requestId } : {},
+        txHashes: source.txHashes,
+        ...source.transactions ? { transactions: source.transactions } : {},
+        depositor
+      }
+    },
+    { cause }
+  ),
+  sourceCashoutStatusUnknown: (source, depositTxHash, cause) => new CashError(
+    {
+      code: "SOURCE_CASHOUT_STATUS_UNKNOWN",
+      message: `Relay completed and Base cash-out transaction ${depositTxHash} was submitted, but its receipt could not be confirmed.`,
+      retryable: false,
+      remediation: `Do not repeat the Relay route or submit another cash-out. Inspect the Base transaction; if it succeeded, recover the depositId from its DepositReceived log, and if it reverted, retry a Base-USDC-only cashout with the recovery amount.`,
+      recovery: {
+        kind: "inspect-base-cashout-transaction",
+        amount: source.amount.toString(),
+        ...source.requestId ? { requestId: source.requestId } : {},
+        txHashes: source.txHashes,
+        ...source.transactions ? { transactions: source.transactions } : {},
+        depositTxHash
+      }
+    },
+    { cause }
+  ),
+  allowanceNotVisible: (amount, cause) => 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 the RPC read path is stale or unavailable. Retry the same call in a few seconds.`
+    },
+    { cause }
+  ),
+  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.`
+  }),
+  signerChainMismatch: (verb, expectedChainId, actualChainId) => new CashError({
+    code: "SIGNER_CHAIN_MISMATCH",
+    message: `${verb} requires chain ${expectedChainId}, but the signer is connected to chain ${actualChainId}.`,
+    retryable: false,
+    remediation: `Switch the wallet to chain ${expectedChainId}, obtain a fresh quote if Relay is involved, and retry before submitting any transaction.`
+  }),
+  signerChainUnavailable: (verb, expectedChainId, cause) => new CashError(
+    {
+      code: "SIGNER_CHAIN_UNAVAILABLE",
+      message: `${verb} could not verify that the signer is connected to chain ${expectedChainId}.`,
+      retryable: true,
+      remediation: `Reconnect the wallet, switch it to chain ${expectedChainId}, and retry before submitting any transaction.`
+    },
+    { cause }
+  ),
+  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 }
+  ),
+  transactionSubmissionUnknown: (operation, cause, recovery) => new CashError(
+    {
+      code: "TRANSACTION_SUBMISSION_UNKNOWN",
+      message: `The Base ${operation} submission did not return a transaction hash.`,
+      retryable: false,
+      remediation: `Do not submit the operation again until you inspect recent Base wallet activity and protocol state; the first transaction may already exist.`,
+      ...recovery ? { recovery } : {}
+    },
+    { cause }
+  ),
+  transactionStatusUnknown: (txHash, cause, operation = "transaction") => new CashError(
+    {
+      code: "TRANSACTION_STATUS_UNKNOWN",
+      message: `Transaction ${txHash} was submitted, but its receipt could not be confirmed.`,
+      retryable: false,
+      remediation: `Do not resubmit the operation until you inspect ${txHash} on Base or successfully fetch its receipt; the transaction may already have succeeded.`,
+      recovery: {
+        kind: "inspect-base-transaction",
+        transactionHash: txHash,
+        operation
+      }
+    },
+    { 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, context = {}) {
+  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 balance|insufficient token balance/i.test(message)) {
+    return errors.insufficientTokenBalance(context.requiredAmount);
+  }
+  if (/exceeds allowance|insufficient allowance/i.test(message)) {
+    return errors.allowanceNotVisible(context.requiredAmount ?? 0n);
+  }
+  return errors.chainCallFailed(verb, err);
+}
+
+export { BASE_CHAIN_ID, BASE_USDC_ADDRESS, CASH_ORDER_POLL_INTERVAL_MS, CASH_ORDER_STATUSES, CASH_RETAIN_ON_EMPTY, CashError, MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, USDC_DECIMALS, errors, isCashError, mapChainError };

package/dist/{createCashClient-iHuGgjH_.d.cts → createCashClient-BbkfxILl.d.cts}

@@ -239,6 +239,7 @@ interface RelaySourceInput {
 }
 interface RelayQuoteInput {
     user: string;
+    /** Interpreted according to `tradeType`; defaults to exact source input. */
     amount: bigint;
     source: RelaySourceInput;
     recipient?: string;
@@ -248,7 +249,9 @@ interface RelayQuote {
     requestId?: string;
     source: CashAsset;
     destination: CashAsset;
+    /** Source amount Relay expects the route to consume. */
     inputAmount: bigint;
+    /** Conservative Base USDC output (Relay minimum output when supplied). */
     outputAmount: bigint;
     rate?: number;
     timeEstimateSeconds?: number;
@@ -259,8 +262,17 @@ interface RelayQuote {
 interface RelayExecutionResult {
     requestId?: string;
     txHashes: string[];
+    /** Chain-aware evidence (emitted by 0.1.4+; optional for wire compatibility). */
+    transactions?: {
+        origin: RelayTransaction[];
+        destination: RelayTransaction[];
+    };
     quote: Execute;
 }
+interface RelayTransaction {
+    hash: string;
+    chainId: number;
+}
 interface RelayStatus {
     requestId: string;
     status: 'refund' | 'waiting' | 'depositing' | 'failure' | 'pending' | 'submitted' | 'success';
@@ -360,7 +372,10 @@ interface CashFillEta {
  */
 
 interface EstimateInput {
-    /** Amount to cash out. Defaults to Base USDC base units; when `source` is set it is source-token base units. */
+    /**
+     * Without `source`, Base USDC base units. With `source`, Relay interprets
+     * this according to `tradeType`; default `EXACT_INPUT` uses source-token units.
+     */
     amount: bigint;
     /** Target fiat currency. */
     currency: CurrencyType;
@@ -372,6 +387,7 @@ interface EstimateInput {
         user: string;
         /** Base recipient for bridged USDC; defaults to `user`. */
         recipient?: string;
+        /** Relay amount mode. Omit for the recommended exact source-input estimate. */
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
 }
@@ -408,9 +424,10 @@ interface CashEstimate {
  * 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}).
+ * are equal consumers: Base-USDC mutations have unsigned `prepare` paths,
+ * Relay execution is explicitly signer-backed, every wire type is serializable,
+ * and every protocol transaction carries ERC-8021 attribution
+ * ({@link CASH_ATTRIBUTION_CODE}).
  */
 
 /**
@@ -452,14 +469,16 @@ interface CashLeg {
 }
 interface CashoutInput {
     /**
-     * Amount to cash out. Defaults to Base USDC base units. When `source` is set,
-     * this is source-token base units and Relay routes it into Base USDC first.
+     * Amount to cash out. Without `source`, this is Base USDC base units. With
+     * `source`, Relay interprets it according to `tradeType`; the default
+     * `EXACT_INPUT` treats it as source-token base units.
      */
     amount: bigint;
     /** Optional Relay source asset. Omit for the Base USDC default path. */
     source?: RelaySourceInput & {
         /** Base recipient for bridged USDC; defaults to the signer address. */
         recipient?: string;
+        /** Relay amount mode. Omit for the recommended exact source-input flow. */
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
     /** Where the fiat should arrive. Multi-payout is a deliberate v1 cut. */
@@ -511,9 +530,15 @@ interface CashoutResult {
     order: CashOrder;
     /** Present when `cashout()` first routed a source asset through Relay. */
     source?: {
+        /** Conservative Base USDC amount deposited (Relay's guaranteed minimum output). */
         amount: bigint;
         requestId?: string;
         txHashes: string[];
+        /** Chain-aware evidence (emitted by 0.1.4+; optional for wire compatibility). */
+        transactions?: {
+            origin: RelayTransaction[];
+            destination: RelayTransaction[];
+        };
     };
 }
 interface PrepareResult {
@@ -559,7 +584,11 @@ interface CashClient {
     /** Quote any Relay-supported EVM source asset into Base USDC. */
     quoteSource(input: RelayQuoteInput): Promise<RelayQuote>;
     /** Execute a Relay SDK quote into Base USDC before starting the Peer Cash order. */
-    executeSourceQuote(quote: Execute, opts: SignerOptions & {
+    executeSourceQuote(quote: RelayQuote | Execute, opts: {
+        /** Wallet signer on the quote's source chain. */
+        signer: WalletClient;
+        /** Expected Base recipient. Defaults to the source signer. */
+        recipient?: string;
         onProgress?: (data: ProgressData) => void;
         disableCapabilitiesCheck?: boolean;
     }): Promise<RelayExecutionResult>;
@@ -609,4 +638,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-export { type CuratorPayeeDataInput as A, type RelayExecutionResult as B, type CashPayoutInfo as C, type RelayOptions as D, type EstimateInput as E, type RelayQuote as F, type RelayQuoteInput as G, type RelaySourceInput as H, type IntentStatus as I, type RelayStatus as J, type WatchOptions as K, type WithdrawOptions as L, MIN_CASHOUT_AMOUNT as M, buildCapabilities as N, type OrdersOptions as O, type PrepareResult as P, createCashClient as Q, 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 CashAsset as l, type CashChain as m, type CashClient as n, type CashClientOptions as o, type CashFillEta as p, type CashLeg as q, type CashNextAction as r, type CashOrderState as s, type CashPayout as t, type CashPayoutPricing as u, type CashPlatformCapability as v, type CashPreparedStepKind as w, type CashSourceCapabilities as x, type CashoutInput as y, type CashoutOptions as z };
+export { type CashoutInput as A, type CashoutOptions as B, type CashPayoutInfo as C, type CuratorPayeeDataInput as D, type EstimateInput as E, RECOMMENDED_MIN_CASHOUT_AMOUNT as F, type RelayOptions as G, type RelayQuoteInput as H, type IntentStatus as I, type RelaySourceInput as J, type RelayTransaction as K, type WatchOptions as L, MIN_CASHOUT_AMOUNT as M, type WithdrawOptions as N, type OrdersOptions as O, type PrepareResult as P, buildCapabilities as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, createCashClient as U, 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, type RelayQuote as k, type RelayStatus as l, type CashSourceCapabilities as m, CASH_ATTRIBUTION_CODE as n, type CashAsset as o, type CashChain as p, type CashClient as q, type CashClientOptions as r, type CashFillEta as s, type CashLeg as t, type CashNextAction as u, type CashOrderState as v, type CashPayout as w, type CashPayoutPricing as x, type CashPlatformCapability as y, type CashPreparedStepKind as z };

package/dist/{createCashClient-iHuGgjH_.d.ts → createCashClient-BbkfxILl.d.ts}

@@ -239,6 +239,7 @@ interface RelaySourceInput {
 }
 interface RelayQuoteInput {
     user: string;
+    /** Interpreted according to `tradeType`; defaults to exact source input. */
     amount: bigint;
     source: RelaySourceInput;
     recipient?: string;
@@ -248,7 +249,9 @@ interface RelayQuote {
     requestId?: string;
     source: CashAsset;
     destination: CashAsset;
+    /** Source amount Relay expects the route to consume. */
     inputAmount: bigint;
+    /** Conservative Base USDC output (Relay minimum output when supplied). */
     outputAmount: bigint;
     rate?: number;
     timeEstimateSeconds?: number;
@@ -259,8 +262,17 @@ interface RelayQuote {
 interface RelayExecutionResult {
     requestId?: string;
     txHashes: string[];
+    /** Chain-aware evidence (emitted by 0.1.4+; optional for wire compatibility). */
+    transactions?: {
+        origin: RelayTransaction[];
+        destination: RelayTransaction[];
+    };
     quote: Execute;
 }
+interface RelayTransaction {
+    hash: string;
+    chainId: number;
+}
 interface RelayStatus {
     requestId: string;
     status: 'refund' | 'waiting' | 'depositing' | 'failure' | 'pending' | 'submitted' | 'success';
@@ -360,7 +372,10 @@ interface CashFillEta {
  */
 
 interface EstimateInput {
-    /** Amount to cash out. Defaults to Base USDC base units; when `source` is set it is source-token base units. */
+    /**
+     * Without `source`, Base USDC base units. With `source`, Relay interprets
+     * this according to `tradeType`; default `EXACT_INPUT` uses source-token units.
+     */
     amount: bigint;
     /** Target fiat currency. */
     currency: CurrencyType;
@@ -372,6 +387,7 @@ interface EstimateInput {
         user: string;
         /** Base recipient for bridged USDC; defaults to `user`. */
         recipient?: string;
+        /** Relay amount mode. Omit for the recommended exact source-input estimate. */
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
 }
@@ -408,9 +424,10 @@ interface CashEstimate {
  * 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}).
+ * are equal consumers: Base-USDC mutations have unsigned `prepare` paths,
+ * Relay execution is explicitly signer-backed, every wire type is serializable,
+ * and every protocol transaction carries ERC-8021 attribution
+ * ({@link CASH_ATTRIBUTION_CODE}).
  */
 
 /**
@@ -452,14 +469,16 @@ interface CashLeg {
 }
 interface CashoutInput {
     /**
-     * Amount to cash out. Defaults to Base USDC base units. When `source` is set,
-     * this is source-token base units and Relay routes it into Base USDC first.
+     * Amount to cash out. Without `source`, this is Base USDC base units. With
+     * `source`, Relay interprets it according to `tradeType`; the default
+     * `EXACT_INPUT` treats it as source-token base units.
      */
     amount: bigint;
     /** Optional Relay source asset. Omit for the Base USDC default path. */
     source?: RelaySourceInput & {
         /** Base recipient for bridged USDC; defaults to the signer address. */
         recipient?: string;
+        /** Relay amount mode. Omit for the recommended exact source-input flow. */
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
     /** Where the fiat should arrive. Multi-payout is a deliberate v1 cut. */
@@ -511,9 +530,15 @@ interface CashoutResult {
     order: CashOrder;
     /** Present when `cashout()` first routed a source asset through Relay. */
     source?: {
+        /** Conservative Base USDC amount deposited (Relay's guaranteed minimum output). */
         amount: bigint;
         requestId?: string;
         txHashes: string[];
+        /** Chain-aware evidence (emitted by 0.1.4+; optional for wire compatibility). */
+        transactions?: {
+            origin: RelayTransaction[];
+            destination: RelayTransaction[];
+        };
     };
 }
 interface PrepareResult {
@@ -559,7 +584,11 @@ interface CashClient {
     /** Quote any Relay-supported EVM source asset into Base USDC. */
     quoteSource(input: RelayQuoteInput): Promise<RelayQuote>;
     /** Execute a Relay SDK quote into Base USDC before starting the Peer Cash order. */
-    executeSourceQuote(quote: Execute, opts: SignerOptions & {
+    executeSourceQuote(quote: RelayQuote | Execute, opts: {
+        /** Wallet signer on the quote's source chain. */
+        signer: WalletClient;
+        /** Expected Base recipient. Defaults to the source signer. */
+        recipient?: string;
         onProgress?: (data: ProgressData) => void;
         disableCapabilitiesCheck?: boolean;
     }): Promise<RelayExecutionResult>;
@@ -609,4 +638,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-export { type CuratorPayeeDataInput as A, type RelayExecutionResult as B, type CashPayoutInfo as C, type RelayOptions as D, type EstimateInput as E, type RelayQuote as F, type RelayQuoteInput as G, type RelaySourceInput as H, type IntentStatus as I, type RelayStatus as J, type WatchOptions as K, type WithdrawOptions as L, MIN_CASHOUT_AMOUNT as M, buildCapabilities as N, type OrdersOptions as O, type PrepareResult as P, createCashClient as Q, 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 CashAsset as l, type CashChain as m, type CashClient as n, type CashClientOptions as o, type CashFillEta as p, type CashLeg as q, type CashNextAction as r, type CashOrderState as s, type CashPayout as t, type CashPayoutPricing as u, type CashPlatformCapability as v, type CashPreparedStepKind as w, type CashSourceCapabilities as x, type CashoutInput as y, type CashoutOptions as z };
+export { type CashoutInput as A, type CashoutOptions as B, type CashPayoutInfo as C, type CuratorPayeeDataInput as D, type EstimateInput as E, RECOMMENDED_MIN_CASHOUT_AMOUNT as F, type RelayOptions as G, type RelayQuoteInput as H, type IntentStatus as I, type RelaySourceInput as J, type RelayTransaction as K, type WatchOptions as L, MIN_CASHOUT_AMOUNT as M, type WithdrawOptions as N, type OrdersOptions as O, type PrepareResult as P, buildCapabilities as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, createCashClient as U, 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, type RelayQuote as k, type RelayStatus as l, type CashSourceCapabilities as m, CASH_ATTRIBUTION_CODE as n, type CashAsset as o, type CashChain as p, type CashClient as q, type CashClientOptions as r, type CashFillEta as s, type CashLeg as t, type CashNextAction as u, type CashOrderState as v, type CashPayout as w, type CashPayoutPricing as x, type CashPlatformCapability as y, type CashPreparedStepKind as z };