@zkp2p/cash 0.6.3-rc.1 → 0.7.0-rc.0

package/AGENTS.md

@@ -7,8 +7,8 @@
 You are integrating Peer Cash: an offramp that routes Relay-supported EVM
 assets or NEAR Intents 1Click external deposits into Base USDC, then converts
 Base USDC to fiat (Venmo, Revolut, Wise, Alipay, Zelle, ...) at a zero-spread
-Chainlink market rate. Existing corridors bind at intent signal; Alipay/CNY
-fixes a fresh Ethereum Chainlink snapshot during deposit preparation; UPI/INR uses Polygon Chainlink. The user whose USDC you
+oracle market rate. Every corridor, including Alipay/CNY and UPI/INR, binds
+the Base oracle at intent signal. The user whose USDC you
 manage is the **maker**; a buyer pays them fiat and proves it with TEE-TLS; the
 protocol releases the USDC. Funds are held by the protocol, and only the maker
 can withdraw an unmatched deposit.
@@ -200,10 +200,8 @@ const route = await cash.nearIntentsStatus({
 ## Rules that prevent wrong behavior
 
 - **Respect the declared binding point.** `estimate()` is
-  `kind: 'oracle-estimate'`. Its `binding` is `intent-signal` for existing
-  on-chain oracle corridors and `deposit-creation` for Alipay/CNY and UPI/INR. Do not call
-  an estimate locked before that point. Once a creation-time corridor is prepared, its fresh
-  Chainlink snapshot is the on-chain maker floor.
+  `kind: 'oracle-estimate'` with `binding: 'intent-signal'` for every currency.
+  The estimate is approximate; each buyer's signal binds the live oracle rate.
 - **Do not invent an ETA.** Use `estimate().eta`: `{ seconds, label }` backed
   by the same rolling 30-day, intent-attributed pair sample as `fillStats()`,
   measured from deposit creation to first fill. Use `order.explain()` for live
@@ -340,13 +338,11 @@ wallet. Never wait on a buyer - buyer-side is out of your scope:
 If step 4 ever fails with funds stuck, stop and escalate - do not retry
 blindly.
 
-UPI/INR reads the live Chainlink Polygon mainnet proxy
-`0xDA0F8Df6F5dB15b346f4B8D1156722027E194E60` (chain 137), inverts
-USD per INR, and rounds the creation-time maker floor up. Configure its
-read-only RPC with `upiCreationRateRpcUrl` or `upiCreationRateTransport`.
-Alipay/CNY retains the Ethereum registry and `creationRateRpcUrl` /
-`creationRateTransport`. UPI rejects the wrong chain, invalid rounds, and
-observations older than 24 hours; market closures do not bypass freshness.
+UPI/INR and Alipay/CNY use ZKP2P-operated AggregatorV3-compatible feeds on Base,
+through the SDK's Chainlink oracle adapter with `invert: true` and zero spread.
+The SDK feed catalog supplies the addresses and determines oracle availability;
+Cash adds no currency exceptions. Estimates read through the normal Base
+`transport` / `rpcUrl`; deposits float until each buyer signals an intent.
 UPI is available in production, preproduction, and staging without a feature flag.
 
 ## Optional Venmo receipt linking
@@ -356,8 +352,8 @@ Run `cash.prepareVenmoGmailConnect(handle)` when the user selects Venmo, then
 call `cash.openVenmoGmailConnect(link.payeeDetails)` directly from a separate
 button click. Re-prepare when the selected handle changes. Use
 `cash.isVenmoGmailConnected(link.payeeDetails)` after returning from a mobile
-tab or an ambiguous closure; service errors reject, and only an active Google
-credential counts as connected. Persist the hash with its environment and user.
+tab or an ambiguous closure; service errors reject, and only an active Gmail or
+Outlook credential counts as connected. Persist the hash with its environment and user.
 
 For native apps, use `prepareVenmoGmailConnect(handle, { returnUrl })` and
 open `link.url` with Expo's `openAuthSessionAsync(link.url, returnUrl)`.
@@ -365,9 +361,9 @@ Register the scheme in your app binary; no registration with Peer is needed.
 Peer appends no data to the callback. Omitted/empty callbacks attempt closure;
 tabs that block it keep the success page. Always re-check status on return.
 
-The hosted flow verifies actual Venmo receipts, including Google-hosted custom
-inboxes. `VenmoGmailConnectError` is separate from `CashError`; no emails or
-Google tokens reach the partner. Configure `venmoGmail: { appearance, popup }`
+The hosted flow offers Gmail, including Google-hosted custom domains, and
+personal Outlook, then verifies actual Venmo receipts. `VenmoGmailConnectError`
+is separate from `CashError`; no emails or mailbox tokens reach the partner. Configure `venmoGmail: { appearance, popup }`
 for branding and desktop dimensions; omission keeps Peer defaults.
 See the README for error codes, native callbacks, package-free URLs, and
 customization, plus `examples/venmo-link.ts`.

package/README.md

@@ -2,10 +2,9 @@
 
 Route Relay-supported EVM assets or NEAR Intents 1Click external deposits into
 Base USDC, then cash out to fiat on Venmo, Revolut, Wise, Alipay, Zelle, and
-more at a zero-spread Chainlink market rate with no centralized off-ramp
-provider. Existing corridors bind the live oracle when a buyer signals;
-Alipay/CNY and UPI/INR fix fresh Chainlink snapshots when the SDK prepares
-the deposit (Ethereum for CNY; Polygon for INR).
+more at a zero-spread on-chain oracle market rate with no centralized off-ramp
+provider. Every corridor, including Alipay/CNY and UPI/INR, binds the live
+Base oracle when a buyer signals.
 
 Peer Cash is an **offramp-only** SDK for the [ZKP2P](https://peer.xyz)
 protocol. The cashing-out user is the maker: their USDC becomes a deposit in
@@ -79,14 +78,14 @@ const widestReach = await cash.cashout(
   { signer },
 );
 
-// Alipay/CNY is the explicit creation-time exception. New Alipay payees need
+// Alipay/CNY uses the same signal-time oracle path. New Alipay payees need
 // the identity attestation prepared by first-party Peer web.
 const alipayEstimate = await cash.estimate({
   amount: usdc(1000),
   platform: 'alipay',
   currency: 'CNY',
 });
-// alipayEstimate.binding === 'deposit-creation'
+// alipayEstimate.binding === 'intent-signal'
 
 for await (const order of cash.watch(depositId)) {
   console.log(order.state, order.explain());
@@ -96,8 +95,8 @@ for await (const order of cash.watch(depositId)) {
 
 ### Staging and preproduction UPI cash-out
 
-UPI requires the canonical UPI/INR catalog from `@zkp2p/sdk` 0.14.2-rc.1
-or its approved successor; a missing catalog entry keeps the corridor disabled.
+UPI requires the canonical UPI/INR catalog and INR oracle config from the
+pinned `@zkp2p/sdk` 0.14.5-rc.2; missing oracle support disables the corridor.
 UPI is available in every environment without an opt-in. Any valid UPI ID from any bank can receive a cash-out. The seller
 does not connect a bank account, install an extension, or complete a separate
 registration flow:
@@ -120,21 +119,30 @@ Buyers pay and verify through Amazon Pay using standard UPI. UPI Lite and
 merchant payments are unsupported. The seller may receive at a valid UPI ID
 from any bank.
 
-INR pricing uses the [Chainlink Polygon INR/USD feed](https://data.chain.link/feeds/polygon/mainnet/inr-usd),
-inverted into INR per USDC and fixed at deposit preparation. The SDK rejects
-invalid rounds and readings older than 24 hours, including market-hour gaps.
-Only oracle reads use Polygon; funds and transactions stay on Base. Override
-the Polygon reader with `upiCreationRateTransport` or `upiCreationRateRpcUrl`.
-The existing `creationRateTransport`/`creationRateRpcUrl` options remain Ethereum-only for CNY.
+UPI/INR and Alipay/CNY use ZKP2P-operated AggregatorV3-compatible feeds on Base,
+through the SDK's Chainlink oracle adapter with `invert: true` and zero spread.
+The SDK feed catalog supplies the addresses and determines oracle availability;
+Cash adds no currency exceptions. Estimates read through the normal Base
+`transport` / `rpcUrl`; deposits float until each buyer signals an intent.
+UPI is available in production, preproduction, and staging without a feature flag.
+
+With `@zkp2p/sdk` 0.14.5-rc.2, Express Cash intentionally also offers
+Wise/INR, Wise/CNY, and Revolut/CNY because corridor support derives from
+oracle availability and each platform's currency catalog. The exact INR/CNY
+corridor set in production, preproduction, and staging is UPI/INR, Wise/INR,
+Alipay/CNY, Wise/CNY, and Revolut/CNY. All five use zero-spread oracle pricing
+bound at intent signal; currencies without an oracle config remain unsupported.
+
+See [the INR/CNY migration notes](docs/lifecycle-and-recovery.md#inrcny-oracle-migration-breaking) before upgrading an existing integration.
 
 ## Pick the right SDK
 
 Peer Cash and the general ZKP2P SDK serve different integration depths:
 
-| Package       | Use it when                                       | Boundary                                                                                                                                                                                                                       |
-| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@zkp2p/cash` | Cash-out is the product                           | Offramp only. The user is always the maker, the destination is Base USDC, pricing is zero-spread Chainlink (signal-time by default; creation-time for Alipay/CNY and UPI/INR), and the SDK owns the resumable order lifecycle. |
-| `@zkp2p/sdk`  | You are composing directly with the Peer protocol | General maker and taker operations, deposits, intents, proofs, quotes, vaults, rate managers, referrals, hooks, and API helpers. Your application owns the workflow and protocol choices.                                      |
+| Package       | Use it when                                       | Boundary                                                                                                                                                                                  |
+| ------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zkp2p/cash` | Cash-out is the product                           | Offramp only. The user is always the maker, the destination is Base USDC, pricing is zero-spread Base oracles at intent signal, and the SDK owns the resumable order lifecycle.           |
+| `@zkp2p/sdk`  | You are composing directly with the Peer protocol | General maker and taker operations, deposits, intents, proofs, quotes, vaults, rate managers, referrals, hooks, and API helpers. Your application owns the workflow and protocol choices. |
 
 Peer Cash is a narrow facade over `@zkp2p/sdk`, not a replacement for it. It
 cannot express custom spreads, buyer-side proof flows, vaults, disputes, or
@@ -146,7 +154,7 @@ arbitrary protocol operations.
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `prepareVenmoGmailConnect(payee, { returnUrl }?)`              | Optional Venmo handle registration; returns the payee hash and hosted URL, with an optional app callback                        |
 | `openVenmoGmailConnect(payeeDetails)`                          | Optional browser popup/tab; call directly from a click                                                                          |
-| `isVenmoGmailConnected(payeeDetails)`                          | Read whether an active Google receipt credential exists                                                                         |
+| `isVenmoGmailConnected(payeeDetails)`                          | Read whether an active Gmail or Outlook receipt credential exists                                                               |
 | `capabilities()`                                               | Sync discovery: Base USDC destination/default source, platforms × currencies × payee hints × amount bounds                      |
 | `capabilities({ includeRelaySources: true })`                  | Async discovery: adds live Relay SDK EVM source chains/tokens                                                                   |
 | `capabilities({ includeNearIntentsSources: true })`            | Async discovery: adds live NEAR Intents 1Click source assets                                                                    |
@@ -188,8 +196,8 @@ mixed historical deposit.
 ## Optional Venmo receipt linking
 
 Partners such as Tailgate can offer **Link Venmo** separately from cash-out.
-`cashout()` and `prepare()` never open Gmail, check receipt credentials, or
-require this step. Skipping or cancelling linking leaves cash-out available.
+`cashout()` and `prepare()` never open Gmail or Outlook, check receipt
+credentials, or require this step. Skipping or cancelling linking leaves cash-out available.
 
 ```ts
 import { createCashClient, VenmoGmailConnectError } from '@zkp2p/cash';
@@ -226,14 +234,17 @@ Desktop opens a popup; mobile requests a new browser tab (including Safari).
 The browser controls presentation and may sever the opener connection. In that
 case check status rather than assuming `connection_closed` or
 `connection_timeout` means verification failed. Status is true only for an
-active `google_oauth` credential; lookup failures reject.
-
-Gmail and Google-hosted school/custom-domain inboxes are accepted. The hosted
-flow verifies actual receipts; there is no email-domain precheck. A missing
-receipt reports `venmo_google_oauth_receipt_not_found` through
+active `google_oauth` or `microsoft_oauth` credential; lookup failures reject.
+Versions before `0.6.3-rc.2` count only `google_oauth`.
+
+The hosted page offers Gmail, including Google-hosted school/custom-domain
+inboxes, and personal Outlook. It verifies actual receipts; there is no
+email-domain precheck. A missing receipt reports
+`venmo_google_oauth_receipt_not_found` (Gmail) or
+`VENMO_MICROSOFT_OAUTH_RECEIPT_NOT_FOUND` (Outlook) through
 `VenmoGmailConnectError.code`. Cancellation, popup blocking, and other hosted
 errors retain their codes. This error class is separate from `CashError`;
-registration and status service errors also reject. Emails and Google tokens
+registration and status service errors also reject. Emails and mailbox tokens
 never pass through the partner app or Cash SDK.
 
 See [the browser example](examples/venmo-link.ts). JSON codecs are exported for
@@ -259,7 +270,7 @@ const connected = await cash.isVenmoGmailConnected(link.payeeDetails);
 Register the callback scheme in your app binary and test on iOS and Android;
 see [Expo's callback requirements](https://docs.expo.dev/versions/latest/sdk/webbrowser/#webbrowseropenauthsessionasyncurl-redirecturl-options).
 Peer requires no callback registration or deployment configuration. After
-verification, the hosted page navigates to `returnUrl` unchanged: no Google
+verification, the hosted page navigates to `returnUrl` unchanged: no mailbox
 credentials, email, account hash, or status are appended. Errors remain on
 the page with a manual return button. Always re-check connection status on
 return or dismissal; a browser return alone is not proof of linking.
@@ -521,15 +532,10 @@ awaiting-buyer ──────────► matched ───────
    returned ◄─────────────────┘
 ```
 
-- **You are the maker.** Pricing is zero-spread. Existing corridors resolve
-  from the on-chain Chainlink oracle when a buyer signals an intent.
-- **Alipay/CNY binds earlier.** Base has no CNY oracle adapter, so the SDK reads
-  Chainlink CNY/USD on Ethereum, rejects stale or invalid data, and fixes the
-  resulting CNY-per-USDC maker floor when it prepares the deposit. A buyer may
-  signal at that floor or a better rate for the maker.
-- **Read `binding`.** `estimate().binding` is `intent-signal` by default and
-  `deposit-creation` for Alipay/CNY and UPI/INR. An estimate remains approximate until its
-  stated binding point.
+- **You are the maker.** Every corridor uses the live Base oracle with zero
+  spread when a buyer signals an intent, including Alipay/CNY and UPI/INR.
+- **Read `binding`.** `estimate().binding` is `intent-signal`. An estimate
+  remains approximate; each signal binds the then-current rate.
 - **ETA is historical.** `estimate().eta` is just `{ seconds, label }`, backed
   by the same rolling 30-day, intent-attributed pair sampler as `fillStats()`,
   measured from deposit creation to the first fulfilled fill through the pair.

package/dist/{createCashClient-p7RZVUmC.d.cts → createCashClient-lYL_Vx2Z.d.cts}

@@ -314,10 +314,7 @@ declare const BASE_CHAIN_ID = 8453;
 declare const BASE_USDC_ADDRESS: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 /** USDC has 6 decimals. */
 declare const USDC_DECIMALS = 6;
-/**
- * Signal-time oracle corridors use zero spread. Alipay/CNY instead fixes a
- * fresh creation-time snapshot because Base has no CNY oracle adapter.
- */
+/** Every corridor uses the signal-time oracle rate with zero spread. */
 declare const MARKET_SPREAD_BPS = 0;
 /**
  * EscrowV2 rejects a zero `minConversionRate` even when an oracle-backed rate
@@ -475,10 +472,6 @@ declare const RECOMMENDED_MIN_CASHOUT_AMOUNT = 1000000n;
 type CashCorridorPricing = {
     kind: 'oracle-at-intent-signal';
     spreadBps: 0;
-} | {
-    kind: 'fixed-at-deposit-creation';
-    source: 'chainlink-ethereum';
-    spreadBps: 0;
 };
 interface CashPlatformCapability {
     /** Platform id, e.g. `'venmo'` - the value `receive.platform` accepts. */
@@ -548,7 +541,7 @@ interface CashCapabilities {
         recommendedMin: bigint;
         max: null;
     };
-    /** Default pricing for corridors without a platform-level creation-time exception. */
+    /** Pricing for every supported corridor. */
     pricing: {
         kind: 'oracle-market-rate';
         spreadBps: 0;
@@ -578,9 +571,7 @@ interface CashFillEta {
  * Estimate - currency + amount only. No payee, no side effects, no expiry,
  * idempotent, cacheable.
  *
- * Existing corridors read the same Chainlink feed the protocol uses when an
- * intent is signaled. Creation-rate corridors read Chainlink on Ethereum (CNY)
- * or Polygon (INR), fixing the fresh snapshot when preparing the deposit.
+ * Reads the same Base oracle feed the protocol uses when an intent is signaled.
  */
 
 interface EstimateInput {
@@ -591,7 +582,7 @@ interface EstimateInput {
     amount: bigint;
     /** Target fiat currency. */
     currency: CurrencyType;
-    /** Optional payout platform for pricing semantics and pair-specific ETA sampling. */
+    /** Optional payout platform for pair-specific ETA sampling. */
     platform?: string;
     /** Optional Relay EVM source asset. Omit for the current Base USDC default path. */
     source?: RelaySourceInput & {
@@ -614,7 +605,7 @@ interface CashEstimate {
     /** Always `'oracle-estimate'`; inspect `binding` for when it becomes a maker floor. */
     kind: 'oracle-estimate';
     /** When this estimate becomes the deposit's binding maker floor. */
-    binding?: 'intent-signal' | 'deposit-creation';
+    binding?: 'intent-signal';
     currency: CurrencyType;
     /** Base USDC amount that Peer Cash would deposit after any source routing. */
     amount: bigint;
@@ -691,14 +682,6 @@ interface CashClientOptions {
     };
     /** Optional ZKP2P API key. */
     apiKey?: string;
-    /** Ethereum transport used only to snapshot Alipay/CNY's creation-time rate. */
-    creationRateTransport?: Transport;
-    /** Convenience alternative to `creationRateTransport`. */
-    creationRateRpcUrl?: string;
-    /** Polygon transport used only to snapshot UPI/INR's creation-time rate. */
-    upiCreationRateTransport?: Transport;
-    /** Convenience alternative to `upiCreationRateTransport`; requires Polygon mainnet. */
-    upiCreationRateRpcUrl?: string;
     /** Relay API configuration for source assets outside Base USDC. */
     relay?: RelayOptions;
     /** NEAR Intents 1Click configuration for externally funded source routes. */
@@ -867,7 +850,7 @@ interface CashClient {
     }): Promise<PreparedVenmoGmailConnect>;
     /** Optional, browser-only: call directly from a click handler with the prepared payee hash. */
     openVenmoGmailConnect(payeeDetails: Hash): Promise<VenmoGmailConnectResult>;
-    /** True only for an active Google receipt credential; errors reject instead of reporting unlinked. */
+    /** True only for an active Gmail or Outlook receipt credential; errors reject instead of reporting unlinked. */
     isVenmoGmailConnected(payeeDetails: Hash): Promise<boolean>;
     /** 0 - Discovery: sync, static. */
     capabilities(): CashCapabilities;

package/dist/{createCashClient-p7RZVUmC.d.ts → createCashClient-lYL_Vx2Z.d.ts}

@@ -314,10 +314,7 @@ declare const BASE_CHAIN_ID = 8453;
 declare const BASE_USDC_ADDRESS: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 /** USDC has 6 decimals. */
 declare const USDC_DECIMALS = 6;
-/**
- * Signal-time oracle corridors use zero spread. Alipay/CNY instead fixes a
- * fresh creation-time snapshot because Base has no CNY oracle adapter.
- */
+/** Every corridor uses the signal-time oracle rate with zero spread. */
 declare const MARKET_SPREAD_BPS = 0;
 /**
  * EscrowV2 rejects a zero `minConversionRate` even when an oracle-backed rate
@@ -475,10 +472,6 @@ declare const RECOMMENDED_MIN_CASHOUT_AMOUNT = 1000000n;
 type CashCorridorPricing = {
     kind: 'oracle-at-intent-signal';
     spreadBps: 0;
-} | {
-    kind: 'fixed-at-deposit-creation';
-    source: 'chainlink-ethereum';
-    spreadBps: 0;
 };
 interface CashPlatformCapability {
     /** Platform id, e.g. `'venmo'` - the value `receive.platform` accepts. */
@@ -548,7 +541,7 @@ interface CashCapabilities {
         recommendedMin: bigint;
         max: null;
     };
-    /** Default pricing for corridors without a platform-level creation-time exception. */
+    /** Pricing for every supported corridor. */
     pricing: {
         kind: 'oracle-market-rate';
         spreadBps: 0;
@@ -578,9 +571,7 @@ interface CashFillEta {
  * Estimate - currency + amount only. No payee, no side effects, no expiry,
  * idempotent, cacheable.
  *
- * Existing corridors read the same Chainlink feed the protocol uses when an
- * intent is signaled. Creation-rate corridors read Chainlink on Ethereum (CNY)
- * or Polygon (INR), fixing the fresh snapshot when preparing the deposit.
+ * Reads the same Base oracle feed the protocol uses when an intent is signaled.
  */
 
 interface EstimateInput {
@@ -591,7 +582,7 @@ interface EstimateInput {
     amount: bigint;
     /** Target fiat currency. */
     currency: CurrencyType;
-    /** Optional payout platform for pricing semantics and pair-specific ETA sampling. */
+    /** Optional payout platform for pair-specific ETA sampling. */
     platform?: string;
     /** Optional Relay EVM source asset. Omit for the current Base USDC default path. */
     source?: RelaySourceInput & {
@@ -614,7 +605,7 @@ interface CashEstimate {
     /** Always `'oracle-estimate'`; inspect `binding` for when it becomes a maker floor. */
     kind: 'oracle-estimate';
     /** When this estimate becomes the deposit's binding maker floor. */
-    binding?: 'intent-signal' | 'deposit-creation';
+    binding?: 'intent-signal';
     currency: CurrencyType;
     /** Base USDC amount that Peer Cash would deposit after any source routing. */
     amount: bigint;
@@ -691,14 +682,6 @@ interface CashClientOptions {
     };
     /** Optional ZKP2P API key. */
     apiKey?: string;
-    /** Ethereum transport used only to snapshot Alipay/CNY's creation-time rate. */
-    creationRateTransport?: Transport;
-    /** Convenience alternative to `creationRateTransport`. */
-    creationRateRpcUrl?: string;
-    /** Polygon transport used only to snapshot UPI/INR's creation-time rate. */
-    upiCreationRateTransport?: Transport;
-    /** Convenience alternative to `upiCreationRateTransport`; requires Polygon mainnet. */
-    upiCreationRateRpcUrl?: string;
     /** Relay API configuration for source assets outside Base USDC. */
     relay?: RelayOptions;
     /** NEAR Intents 1Click configuration for externally funded source routes. */
@@ -867,7 +850,7 @@ interface CashClient {
     }): Promise<PreparedVenmoGmailConnect>;
     /** Optional, browser-only: call directly from a click handler with the prepared payee hash. */
     openVenmoGmailConnect(payeeDetails: Hash): Promise<VenmoGmailConnectResult>;
-    /** True only for an active Google receipt credential; errors reject instead of reporting unlinked. */
+    /** True only for an active Gmail or Outlook receipt credential; errors reject instead of reporting unlinked. */
     isVenmoGmailConnected(payeeDetails: Hash): Promise<boolean>;
     /** 0 - Discovery: sync, static. */
     capabilities(): CashCapabilities;