@zkp2p/cash 0.6.3-rc.2 → 0.7.0

package/docs/lifecycle-and-recovery.md

@@ -6,10 +6,9 @@ fills and ETA work, how unwinding works, and why every order survives a crash.
 ## The model: you are the maker
 
 A Peer Cash order is a **deposit** in the ZKP2P protocol. When you
-`cashout()`, Base USDC becomes protocol-held funds priced from Chainlink with
-zero spread. Existing corridors bind the on-chain oracle at intent signal;
-Alipay/CNY fixes a fresh Ethereum Chainlink snapshot as the maker floor during
-deposit preparation. A buyer (a standard protocol taker) _signals an
+`cashout()`, Base USDC becomes protocol-held funds priced from on-chain oracles with
+zero spread. Every corridor, including Alipay/CNY and UPI/INR, binds the
+on-chain Base oracle at intent signal. A buyer (a standard protocol taker) _signals an
 intent_ against your deposit, pays you fiat offchain (Venmo, Revolut, Wise,
 ...), and proves the payment via TEE-TLS. The protocol then releases your USDC
 to them.
@@ -19,6 +18,71 @@ special-cased.
 Because your deposit is priced at market with no spread, it is the best price
 a rational maker can offer. That is the fill incentive.
 
+## INR/CNY oracle migration (breaking)
+
+With the SDK dependency pinned to `@zkp2p/sdk` 0.14.5, new Express Cash
+UPI/INR and Alipay/CNY deposits float with the Base oracle plus
+`MARKET_SPREAD_BPS` (zero), exactly like every other supported currency.
+They no longer fix a creation-time snapshot. Each buyer's intent signal binds
+its rate. Existing deposits keep their on-chain pricing; upgrading does not
+reprice them. Historical fixed-rate Cash orders remain readable and withdrawable
+when indexed attribution and pricing evidence identify them as Cash.
+
+With `@zkp2p/sdk` 0.14.5, 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.
+
+This is a hard API cutover, with no deprecated aliases:
+
+- Remove `creationRateTransport`, `creationRateRpcUrl`,
+  `upiCreationRateTransport`, and `upiCreationRateRpcUrl` from client options.
+  Use the existing Base `transport` / `rpcUrl` for oracle reads.
+- Remove imports of `CREATION_RATE_MAX_STALENESS_SECONDS`,
+  `isCreationRateCorridor`, `readAlipayCnyCreationRate`, `CreationRateReader`,
+  and `CreationRateSnapshot`. The internal `readCashCreationRate` reader and
+  `prepareCashDepositParams`' fourth reader argument are also removed.
+- Estimates now expose only `binding: 'intent-signal'`; capability pricing
+  exposes only `kind: 'oracle-at-intent-signal'`. Their types and codecs reject
+  the removed `deposit-creation` / `fixed-at-deposit-creation` variants.
+  Refresh persisted estimates and capabilities when upgrading. Historical
+  order payout codecs retain fixed-rate evidence for recovery.
+
+For `zkp2p-clients` consumers (verified at `origin/main` commit `004abbc`),
+`clients/web/src/components/PeerCash/usePeerCashExpressFlow.ts:278-288` passes
+both `creationRateTransport` and `upiCreationRateTransport` through conditional
+object spreads. TypeScript will **not** flag these leftover options after the
+SDK bump; they will be silently ignored. Remove both spreads, their obsolete
+imports, and the Polygon RPC proxy plumbing (`rpcProxyPolygonUrl` in
+`clients/web/src/helpers/rpcProxy.ts`, its helper tests, and the Express test
+mock). Keep shared Ethereum proxy plumbing that other features still use.
+Remove `clients/web/src/components/PeerCash/peerCashCreationRate.test.ts`: it
+sets both removed options and expects `binding: 'deposit-creation'`, so it will
+fail after the bump. Replace that obsolete test with Base oracle transport
+coverage asserting `binding: 'intent-signal'`. Do not rely on the compiler to
+complete this migration.
+
+INR/USD and CNY/USD are ZKP2P-operated, 8-decimal AggregatorV3-compatible
+Base feeds consumed by the existing Chainlink adapter with `invert: true`.
+Oracle availability comes from the SDK catalog; there are no special INR/CNY
+support branches or Ethereum/Polygon rate readers. A failing estimate returns
+the same oracle errors as other currencies; stale estimates are display-flagged,
+and the on-chain adapter enforces `maxStaleness` at signal.
+
+The published SDK rc.1 → rc.2 diff also adds Microsoft OAuth seller-credential
+uploads (including PKCE `codeVerifier`) and shares the Google upload path's
+implementation. Cash's hosted Venmo Gmail connector is unchanged. The contracts
+pin moves from 0.4.2 to 0.4.3-rc.1, adding FxRateStore/feed ABIs and addresses
+and provider metadata to the oracle catalog. Existing payment-method catalog
+content, escrow/guardian addresses, and active dispute-stack selections are
+unchanged. Indexer schema remains 0.22.0. The prepared stable SDK 0.14.5
+pins stable contracts 0.4.3.
+
+Release history remains in PR titles per the contributor guide; this change
+does not bump the Cash package version or publish a release.
+
 ## Source routing
 
 The cashout destination is always canonical Base USDC. The minimal/default path
@@ -189,9 +253,8 @@ then read that pair from `fillStats()` without coupling the two loading states.
 - **Buyer arrival time is market-driven.** A deposit at market rate should
   fill fast, but the ETA is only a recent historical sample.
 - **The binding point is explicit.** `estimate().binding` is `intent-signal`
-  for existing on-chain oracle corridors. Alipay/CNY returns
-  `deposit-creation`: its fresh Ethereum Chainlink snapshot becomes the
-  on-chain maker floor when the deposit is prepared.
+  for every corridor, including Alipay/CNY and UPI/INR. Each buyer's signal
+  binds the live Base oracle rate.
 - **The label is display-ready.** Use `eta.label` in simple UIs; use
   `eta.seconds` only if you need your own formatting.
 
@@ -237,17 +300,22 @@ same ceil-to-cent math, and the decode is verified against live production
 receipts.
 
 Orders also carry their `payouts` legs reconstructed from the chain - platform,
-currency, payee hash, and indexed pricing evidence. Existing corridors expose
-`spreadBps: 0`, an oracle `kind`, and `marketRate: true`; Alipay/CNY exposes
-`fixedAtCreation: true` and its `fixedRate`. An order created with several
+currency, payee hash, and indexed pricing evidence. New orders expose
+`spreadBps: 0`, an oracle `kind`, and `marketRate: true`, including Alipay/CNY
+and UPI/INR. Historical fixed-rate orders expose `fixedAtCreation: true` and
+their `fixedRate`. An order created with several
 payout platforms (`receive` as an array of legs) surfaces one entry per
 platform-currency pair.
 
 Reconstruction is fail-closed: every payment method on the indexed deposit
-must resolve through the active SDK catalog. Oracle-priced rows retain the
-historical structural classification. Fixed Alipay/CNY rows must also carry the
-indexed `peer-cash` ERC-8021 attribution so unrelated Advanced Sell deposits
-cannot be mistaken for Cash orders. `orders()` excludes unsupported or mixed
+must resolve through the active SDK catalog. Zero-spread oracle payouts are
+classified structurally, without requiring the `peer-cash` ERC-8021 attribution
+marker. This includes INR/CNY, consistently with other oracle currencies: a
+qualifying oracle deposit created via Advanced Sell from the same wallet can
+appear in `cash.orders(owner)` and be returned by `cash.order(depositId)`.
+Historical fixed Alipay/CNY and UPI/INR rows instead require both positive
+fixed-rate evidence and indexed `peer-cash` attribution; unrelated fixed-rate
+Advanced Sell deposits do not qualify. `orders()` excludes unsupported or mixed
 rows; `order()` returns `ORDER_NOT_FOUND` rather than partially reclassifying
 them.
 
@@ -329,7 +397,7 @@ explicit override.
 | Code                                    | Retryable | What happened / what to do                                                                                                                   |
 | --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ORACLE_UNSUPPORTED_CURRENCY`           | no        | Platform/currency corridor is unavailable. Pick a pair from `capabilities()`.                                                                |
-| `ORACLE_READ_FAILED`                    | yes       | A Chainlink read failed. Retry through the configured Base or creation-rate Ethereum RPC; do not present a cached value as fresh.            |
+| `ORACLE_READ_FAILED`                    | yes       | A Chainlink read failed. Retry through the configured Base RPC; do not present a cached value as fresh.                                      |
 | `UNSUPPORTED_PLATFORM`                  | no        | Platform is absent from this environment's catalog. Pick from `capabilities()`.                                                              |
 | `UNSUPPORTED_PLATFORM_CURRENCY`         | no        | The platform does not support that currency. Use its `capabilities()` currencies.                                                            |
 | `AMOUNT_BELOW_MINIMUM`                  | no        | Amount is below the $0.01 hard floor. The recommended minimum is 1 USDC.                                                                     |

package/examples/onchain-demo/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "description": "Peer Cash Demo: the express sell flow stored entirely onchain on Base, after zSwap by z0r0z",
   "dependencies": {
-    "@zkp2p/cash": "0.6.1",
+    "@zkp2p/cash": "0.7.0",
     "esbuild": "0.28.2",
     "solc": "0.8.36",
     "viem": "2.55.18"

package/examples/onchain-demo/src/shell.html

@@ -103,7 +103,7 @@ select option{background:var(--c);color:var(--f)}
     <div id="error" class="warn hide"></div>
 
     <div id="details" class="hide">
-      <div class="drow"><span title="The estimate shows its rate-binding point. Most corridors bind when a buyer signals; Alipay/CNY binds when the deposit is prepared.">Market rate</span><b id="rate">…</b></div>
+      <div class="drow"><span title="All corridors, including INR and CNY, bind the live Base oracle rate when a buyer signals.">Market rate</span><b id="rate">…</b></div>
       <div class="drow"><span title="Median time recent cash-outs on this platform and currency waited for their first fill, from the last 30 days of onchain history. Historical, not a guarantee.">Time to fill</span><b id="eta">Varies</b></div>
     </div>
 

package/examples/upi-staging-cashout.ts

@@ -1,4 +1,4 @@
-// UPI pricing reads Polygon mainnet; configure upiCreationRateRpcUrl for a dedicated provider.
+// UPI pricing uses the Base oracle; configure transport or rpcUrl for a dedicated provider.
 import { createCashClient, usdc } from '@zkp2p/cash';
 import type { WalletClient } from 'viem';
 

package/llms.txt

@@ -3,7 +3,7 @@
 > Offramp-only SDK for the ZKP2P protocol: route Relay-supported EVM assets or
 > NEAR Intents 1Click external deposits to Base USDC, then cash out to fiat
 > (Venmo, Revolut, Wise, Alipay, Zelle, ...)
-> at a zero-spread Chainlink market rate with no centralized
+> at a zero-spread on-chain oracle market rate with no centralized
 > off-ramp provider. The user is the maker, a buyer pays them fiat and proves
 > the payment, and the SDK exposes readable order state.
 > Base-USDC flows are serializable through prepare paths; source-routed cashout
@@ -43,9 +43,9 @@ Key facts:
   address/memo, and deadline; send once with the origin wallet; optionally
   submit that existing hash; poll status to SUCCESS; reconcile Base evidence;
   then cash out Base-only. Use EXACT_OUTPUT when the order amount must be fixed.
-- estimate() reports its binding point. Existing corridors bind the on-chain
-  oracle when an intent is signaled; Alipay/CNY fixes a fresh Ethereum
-  Chainlink snapshot during deposit preparation; UPI/INR uses a fresh Polygon Chainlink snapshot. ETA is `{ seconds, label }` from the same rolling
+- estimate() reports binding: intent-signal for every corridor, including
+  Alipay/CNY and UPI/INR. All deposits float with the Base oracle plus zero
+  spread until a buyer signals. ETA is `{ seconds, label }` from the same rolling
   30-day, intent-attributed pair sampler as fillStats(), not a guarantee.
 - fillStats() returns raw `{ fills, medianFillSeconds? }` evidence keyed by
   `platform:currency` or a sorted set such as `revolut:EUR+GBP+USD`. Set
@@ -97,7 +97,7 @@ Key facts:
   platforms (each platform at most once); read each capability's pricing entry
   for its binding semantics.
 - Orders carry their payout legs (platform, currency, payee hash) plus indexed
-  pricing evidence for either signal-time oracle or fixed-at-creation pricing.
+  pricing evidence for signal-time oracle pricing (or historical fixed-rate orders).
 - Order reads fail closed when any deposit method is absent from the active
   catalog; mixed historical deposits are never partially reclassified.
 - buyer(address) aggregates a buyer's track record (fulfilled/pruned/success
@@ -154,11 +154,16 @@ Key facts:
 - [Codecs](src/codecs/): zod schemas + lossless JSON round-trips
 
 
-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.
+
+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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.6.3-rc.2",
-  "description": "Peer Cash - offramp-only SDK for routing Relay or NEAR Intents assets to Base USDC, then cashing out to fiat at zero-spread Chainlink market rates.",
+  "version": "0.7.0",
+  "description": "Peer Cash - offramp-only SDK for routing Relay or NEAR Intents assets to Base USDC, then cashing out to fiat at zero-spread on-chain oracle market rates.",
   "license": "MIT",
   "author": "Peer (https://peer.xyz)",
   "type": "module",
@@ -108,7 +108,7 @@
   },
   "dependencies": {
     "@relayprotocol/relay-sdk": "^7.0.1",
-    "@zkp2p/sdk": "0.14.5-rc.1",
+    "@zkp2p/sdk": "0.14.5",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/skills/peer-cash-integration/SKILL.md

@@ -28,11 +28,9 @@ protocol-held funds and no custodial off-ramp provider.
   send once with the origin wallet, optionally register that existing hash,
   poll status to `SUCCESS`, reconcile Base evidence, then cash out Base-only.
   Browser integrations use a same-origin proxy so the 1Click JWT stays server-side.
-- **Pricing has an explicit binding point.** Existing corridors carry
-  `oracleRateConfig { spreadBps: 0 }`; the binding rate is the Chainlink rate
-  when a buyer signals. Alipay/CNY is the exception: because Base has no CNY
-  oracle adapter, the SDK reads Chainlink CNY/USD on Ethereum and fixes that
-  fresh snapshot as the maker floor during deposit preparation. UPI/INR does the same using the direct Polygon INR/USD feed, rejecting wrong-chain, stale and invalid data. Read
+- **Pricing has an explicit binding point.** Every corridor carries
+  `oracleRateConfig { spreadBps: 0 }`; the binding rate is the Base oracle rate
+  when a buyer signals, including Alipay/CNY and UPI/INR. Read
   `estimate().binding` and `capabilities().platforms[].pricing`.
 - **Custody story.** Funds are held by the protocol contract only. An unmatched
   deposit is withdrawable by the maker at any time. The SDK never holds keys.
@@ -271,23 +269,20 @@ a human with the `depositId` and tx hashes.
 
 ## UPI oracle checks
 
-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.
 
 Before a funded UPI QA run, call
 `cash.estimate({ amount: 1000000n, platform: 'upi', currency: 'INR' }, { includeEta: false })`
-using the intended live Polygon RPC. Require a positive finite rate,
-`binding: 'deposit-creation'`, and `oracleUpdatedAt` no more than 86400 seconds
+using the intended live Base RPC. Require a positive finite rate,
+`binding: 'intent-signal'`, and `oracleUpdatedAt` no more than 86400 seconds
 old and not in the future. Record the observation time and selected chain,
 then stop before funding if the read fails. Unit-test fixtures prove routing,
-not live availability. The authoritative feed listing is
-https://data.chain.link/feeds/polygon/mainnet/inr-usd.
+not live availability. Use the pinned SDK oracle feed catalog for the feed address.
 
 ## Optional Venmo receipt linking
 

package/skills/upi-preprod-qa/SKILL.md

@@ -29,17 +29,14 @@ for (const environment of ['staging', 'preproduction', 'production'] as const) {
 Use an explicitly authorized low-value wallet and verified recipient UPI ID.
 Keep the identity and operation ledger in ignored private storage, outside this skill.
 `cashout` accepts any valid VPA; no seller bank login or identity attestation is required.
-Verify INR pricing is a fresh Polygon Chainlink snapshot fixed at deposit creation.
-The official [INR/USD feed](https://data.chain.link/feeds/polygon/mainnet/inr-usd)
-is proxy `0xDA0F8Df6F5dB15b346f4B8D1156722027E194E60` on chain 137;
-it is not registered in Ethereum's Feed Registry. Before funding, call
+Verify INR pricing uses the ZKP2P-operated Base INR/USD oracle from the SDK
+catalog, inverted through the Chainlink adapter with zero spread. Before funding, call
 `cash.estimate({ amount: 5_000_000n, platform: 'upi', currency: 'INR' }, { includeEta: false })`
-against the live default or explicitly configured Polygon RPC. Confirm a positive
-rate, fresh `oracleUpdatedAt`, and `binding: 'deposit-creation'`. Do not accept
-mocked-rate unit tests as proof of a functioning live corridor. The reader must
-reject the wrong chain, invalid/incomplete rounds, future timestamps and data
-older than 86,400 seconds. Forex market-hour gaps must fail closed; do not
-substitute a static price or relax freshness to make QA pass.
+against the live default or explicitly configured Base RPC. Confirm a positive
+rate, fresh `oracleUpdatedAt`, and `binding: 'intent-signal'`. Do not accept
+mocked-rate unit tests as proof of a functioning live corridor. Stop before funding
+if the read fails or is stale. The on-chain adapter enforces the SDK config's
+`maxStaleness` at signal; do not substitute a static price to make QA pass.
 
 With bounded task authorization, create one small Base-USDC deposit, recording
 transaction hash and deposit ID before any retry. Confirm the receipt, then
@@ -76,7 +73,7 @@ bodies out of committed evidence; publish only redacted checkpoint results.
 
 ## Live order reconstruction regression
 
-After the exact UPI fixture is indexed, require both `cash.order(depositId)` and `cash.orders(owner)` to return it. Fixed UPI/INR creation-rate deposits must have positive fixed-rate evidence and the indexed `peer-cash` attribution marker. Do not classify unrelated Advanced Sell deposits as Cash orders. A quoteable indexer row alone is insufficient: run order lookup, partial-fill observation and withdrawal checks too. Keep the method/currency pair explicit; UPI/CNY must be rejected.
+After the exact UPI fixture is indexed, require both `cash.order(depositId)` and `cash.orders(owner)` to return it. New UPI/INR deposits must have zero-spread oracle pricing evidence. Historical fixed-rate UPI/INR deposits still require positive fixed-rate evidence and the indexed `peer-cash` attribution marker for recovery. Zero-spread oracle payouts are classified structurally without requiring the `peer-cash` marker, including INR/CNY as with other oracle currencies. A qualifying zero-spread INR/CNY oracle deposit created via Advanced Sell from the same wallet can therefore appear in `cash.orders(owner)` and `cash.order(depositId)`. The attribution requirement excludes unrelated historical fixed-rate Advanced Sell deposits, not qualifying oracle deposits. A quoteable indexer row alone is insufficient: run order lookup, partial-fill observation and withdrawal checks too. Keep the method/currency pair explicit; UPI/CNY must be rejected.
 
 ## Small-fixture visibility and dust reconciliation