@zkp2p/sdk 0.15.0-rc.0 → 0.15.0-rc.2

package/README.md

@@ -35,7 +35,7 @@ and chargeback-risk surface. The workspace version lives in `package.json`.
 
 ## Optional Venmo Gmail connection
 
-For partner cash-out integrations, prefer stable `@zkp2p/cash@0.7.2` and its
+For partner cash-out integrations, prefer stable `@zkp2p/cash@0.7.3` and its
 [prepare/open/status flow](https://docs.peer.xyz/developer/peer-cash/guide#optional-venmo-receipt-linking).
 It selects the matching environment and keeps linking separate from cash-out.
 The direct SDK helpers below require `@zkp2p/sdk@0.14.2` or later.
@@ -79,6 +79,23 @@ hosts and custom window handling with account-status polling at least ten second
 apart. Deploy the hosted page before using the SDK helper. See the
 [flow specification](https://github.com/zkp2p/zkp2p-clients/blob/main/docs/venmo-gmail-connect.md).
 
+### X Money receipt linking
+
+SDK `0.14.10` adds `getXMoneyConnectUrl` and `openXMoneyConnect`, using the same mailbox flow at
+`/connect/xmoney`. Pass the registered `payeeDetails` hash and `payeeUsername`.
+The normalized X username must hash to that identity. Both stay in the URL
+fragment. X Money email notifications must be enabled and the inbox must contain
+a signed received-payment receipt for that account. Gmail, personal Outlook and
+iCloud Mail are supported. Deploy the hosted page before enabling this helper.
+
+```ts
+import { openXMoneyConnect } from '@zkp2p/sdk';
+await openXMoneyConnect({ payeeDetails, payeeUsername: 'seller' });
+```
+
+The URL builder also accepts `returnUrl` for native hosts. Re-check the mailbox
+credential status after return or dismissal, as with Venmo.
+
 ### Native app return
 
 SDK `0.14.3` adds optional `returnUrl` to the URL builder. Partners
@@ -292,9 +309,10 @@ bundle `payeeIdHash`, and store the encrypted bundle with curator. Plaintext
 seller session material is never returned to the page.
 
 `Zkp2pClient.uploadSellerCredential()` supports Cash App, Wise, and Amazon Pay UPI
-plaintext input from trusted runtimes. Venmo and PayPal use the Google OAuth helper. Internally it
-creates the encrypted bundle, then uses the same
-`apiUploadSellerCredentialBundle()` storage helper.
+plaintext input from trusted runtimes. It creates the encrypted bundle, then uses
+`apiUploadSellerCredentialBundle()` for storage. Venmo, PayPal, and X Money use
+the [mailbox upload helpers](#seller-credential-status) for Gmail, personal
+Outlook, or iCloud Mail.
 
 ## Create a Deposit
 
@@ -314,14 +332,17 @@ console.log(result.hash);
 console.log(result.depositDetails);
 ```
 
-By default, `createDeposit()` enables the trusted group bypass on Venmo and
-PayPal methods. After the deposit mines, it sends one
-`WhitelistPolicy.configureDeposit` per Venmo/PayPal method with the Peer Pay
+The trusted-group whitelist is opt-in via `enableTrustedGroupBypass: true`
+(defaults to false). By default, `createDeposit()` sends only the deposit and
+returns empty `result.accessPolicyTxHashes` without waiting for a receipt.
+When opted in, after the deposit mines, it sends one `configureDeposit` on the
+current deposit whitelist (see [Deposit Access Policy](#deposit-access-policy))
+per Venmo/PayPal method with the Peer Pay
 merchant group and returns the confirmed hashes as
 `result.accessPolicyTxHashes` (empty for other methods). Members of that group
-skip dispute-protection staking; other takers still stake, and until the policy
-mines, merchants stake too. Pass `enableTrustedGroupBypass: false` to skip it.
-If the deposit was sent but the policy was not confirmed, it throws a
+skip dispute-protection staking. On OrchestratorV4 an enabled whitelist makes
+the deposit private: only Peer Pay merchant-group members can signal.
+When opted in, if the deposit was sent but the policy was not confirmed, it throws a
 `ContractError` whose `details.hash` is the deposit transaction. `prepareCreateDeposit()` does not add
 the policy; custom senders call `client.accessPolicy.prepareConfigurePeerPayMerchantDeposit()`
 once the deposit ID is known.
@@ -390,6 +411,7 @@ await client.setTakerAuthorization({ taker, authorized: true }); // signed by th
 await client.selectStakeOwner({ stakeOwner: safeAddress }); // signed by the taker
 await client.clearStakeOwner(); // taker returns to self-stake
 
+// Explicit vaults are verified through the live stack independently by each client.
 const onchain = await client.getStakeVaultState({
   staker: takerAddress,
   taker: takerAddress,
@@ -451,32 +473,34 @@ withdraws the complete claimable balance. Chargebackable capacity is exactly
 the effective owner's free stake (1:1); never sum a taker's self-stake with a
 sponsor's stake.
 
-`getActiveDisputeProtectionStack()` reads the live OrchestratorV3 hook, policy,
-and vault. It returns `null` for a zero hook, rejects unknown policies or vaults,
-and caches discovery per client for 30 seconds; failures are never cached.
-`getActiveStakeVaultContract()` returns that vault (canonical when the hook is zero).
-`getKnownStakeVaults()` lists canonical, Bypass, and any exported MethodScoped
-predecessor vault, deduplicated by address. `isNoStakeAvailable()` is true only
-when the live policy is the resolved payment-validation policy.
-
-Pass `stakeVaultAddress?: Address` to `getStakeVaultContract(options?)`,
-`getStakeVaultState({ staker, taker?, stakeVaultAddress? })`, every vault write,
-and `ensureStakeAllowance`. Single-value vault reads accept a trailing optional
-`options?: { stakeVaultAddress?: Address }`. Unknown vaults throw; reads, writes,
-and allowance default to the active vault (canonical only for a zero hook).
-The synchronous `getStakeVaultContract()` getter still returns bundle/canonical
-coordinates when no address is given; use `getActiveStakeVaultContract()` for
-the vault the live policy locks from. Each vault-state call resolves one vault
-for all accounting reads and its stake token; `admissionsPaused` comes from
-that vault's controller.
-The standalone `getAdmissionsPaused`, `getRiskWindow`, and
-`isDisputeProtectionEnabled` reads follow the live policy, using canonical only
-when the live hook is zero. `setDisputeProtectionEnabled` follows the same live
-policy unless `disputeProtectionPolicyAddress` is supplied.
-
-The vault's controller is the `DisputeProtectionPolicy` contract. It owns
+`getDisputeProtectionStacks()` discovers `{ current, draining }` from
+OrchestratorV4 and OrchestratorV3 respectively, following O4 settlementPolicy to its vault, and the August/O3 hook to its policy and
+vault. Discovery is cached for 30 seconds; failures are retried. The active vault
+is the V4 vault when V4 is deployed, otherwise the V3 vault. Known previous vaults
+remain selectable with `stakeVaultAddress` for reads and withdrawals; on staging these
+are the August and Bypass vaults. The Bypass policy also stays known, so O3 intents
+holding records there still resolve. O4 discovery verifies
+`policy.isOrchestratorAuthorized(O4)` and `vault.isController(policy)`. V2 uses
+the StakeVaultV2 ABI; August vaults retain StakeVault and its single controller. A missing
+current stack fails closed. `@zkp2p/contracts-v2@0.4.4-rc.6` exports the Base staging
+V4 stack. Base exports zero placeholders, which never enable V4.
+
+Explicit vault addresses passed to stake reads, writes and allowance setup are verified
+against bundled deployments or the trusted V4 live stack, cached per client for 30 seconds.
+Use `await client.resolveStakeVaultContract({ stakeVaultAddress })` when contract
+coordinates are needed before a direct read. `getStakeVaultContract` remains a
+synchronous lookup of already-known vaults.
+
+`getAdmissionsPaused`, `getRiskWindow`, `isDisputeProtectionEnabled` and
+`setDisputeProtectionEnabled` target only the August V1 policy behind
+OrchestratorV3. An explicit V2 address or a missing V3 stack fails closed.
+V2 has no on-chain risk-window or pause getter; `StakeVaultState.admissionsPaused`
+is omitted for V2 vaults. Use the attestor rail policy for quote-time defaults.
+Releases look up each intent's original policy;
+a batch spanning policies throws `ValidationError`.
+
+The August vault's controller is the `DisputeProtectionPolicy` contract. It owns
 per-payment-method risk windows (`getRiskWindow(paymentMethodHash)`),
-per-deposit chargeback enablement (`isDisputeProtectionEnabled(escrow, depositId)`),
 and the global `admissionsPaused()` switch. The selected `@zkp2p/contracts-v2`
 bundle resolves the StakeVault, DisputeProtectionPolicy, and OrchestratorV3 for
 both the production and staging bundles; a bundle without them fails closed
@@ -487,9 +511,11 @@ deployments).
 Keeper writes are direct and prepareable:
 
 ```ts
+// August V1 policy behind OrchestratorV3 only.
 const enableProtection = await client.setDisputeProtectionEnabled.prepare({
   escrow: depositEscrow,
   depositId: 42n,
+  paymentMethod: paymentMethodHash,
   enabled: true,
 });
 
@@ -523,24 +549,8 @@ same finalized cutoff for every cursor in one ingestion pass. Follow
 `endCursor` with its final block/log position; `endCursor` is null only for an
 empty page.
 
-Before enabling dispute-protected admission, prove that the live Base contracts
-match the packaged manifest or verified Bypass successor records:
-
-```ts
-const readiness = await client.getDisputeProtectionReadiness();
-
-if (readiness.state !== 'active_successor_verified' || !readiness.readyForDisputeProtection) {
-  throw new Error(`Dispute protection is unavailable: ${readiness.state}`);
-}
-```
-
-Known results expose `verifiedStack`: `manifest` for the manifest path or
-`bypass_records` for an active Bypass hook distinct from the manifest hook. The
-Bypass path proves code presence and the specified hook/registry/policy/vault
-relations at one block; it does not claim manifest runtime-hash or governance
-verification for those new deployments. Missing records leave this path off.
-On Base staging the manifest now names the Bypass stack, so its Bypass records
-equal the manifest identities and readiness runs the full manifest path there.
+The existing readiness API verifies the V3 manifest only. V4 readiness is pending
+the new deployment manifest.
 
 The manifest reader pins every code and state read to one `asOfBlock`, including exact
 governance owners, authorization sets, attestation witnesses, and signature
@@ -588,13 +598,11 @@ selection hashes. A local build has the deterministic `development` identity
 and is deliberately non-distributable, so its readiness reader returns
 `mismatch` before making RPC calls.
 
-Quote and orderbook requests accept `includeNoStakeCompatible?: boolean` to opt in to protected rows a taker may signal without stake (Venmo only today). Only `true` is sent; false and omitted values leave the field absent.
-
 For table-style liquidity UIs, the low-level `apiGetOrderbookTable()` adapter exposes curator's paginated public/private orderbook rows and row-level privacy metadata.
 
 ## Seller Credential Status
 
-Venmo and PayPal Seller Autopilot connections use `uploadGoogleOAuthSellerCredential` for Gmail, `uploadMicrosoftOAuthSellerCredential` for personal Outlook accounts, or `uploadICloudMailSellerCredential` for iCloud Mail. The normal `uploadSellerCredential` and extension seller-capture paths support Cash App, Wise (token upload only), and Amazon Pay UPI. Existing backend Venmo cookie bundles remain usable through status/verification and low-level encrypted-bundle APIs.
+Venmo, PayPal and X Money Seller Autopilot connections use `uploadGoogleOAuthSellerCredential` for Gmail, `uploadMicrosoftOAuthSellerCredential` for personal Outlook accounts, or `uploadICloudMailSellerCredential` for iCloud Mail. The normal `uploadSellerCredential` and extension seller-capture paths support Cash App, Wise (token upload only), and Amazon Pay UPI. Existing backend Venmo cookie bundles remain usable through status/verification and low-level encrypted-bundle APIs.
 
 ```ts
 await client.uploadGoogleOAuthSellerCredential({
@@ -618,9 +626,11 @@ await client.uploadMicrosoftOAuthSellerCredential({
 });
 ```
 
+X Money mailbox uploads require SDK 0.14.9 or later. For Gmail and Outlook, pass `platform: 'xmoney'` with the registered maker hash and the same OAuth code fields; no `payeeEmail` is needed. Enable X Money email notifications and receive a payment before connecting. The server accepts a credential only after validating a received-payment email for the registered X account. A historical receipt establishes delivery, not the current notification-setting state; keep notifications enabled for future payments. A missing or invalid receipt returns `XMONEY_EMAIL_RECEIPT_NOT_FOUND`.
+
 Validate OAuth state in the initiating browser tab before uploading. `redirectUri` must exactly match the one in the authorization request. Both methods exchange a one-time code without retrying; start fresh consent if the response is lost. The Microsoft client secret stays server-side. See [email connection setup](../../docs/email-oauth.md).
 
-iCloud Mail has no OAuth. Pass the seller's Apple app-specific password with the registered maker hash; PayPal also passes its receiving email. For Venmo, the SDK fetches the maker's account ID from Curator (`GET /v2/makers/venmo/{payeeDetails}/payee-id`) and checks it against `payeeDetails` before any mailbox work, so sellers never enter it.
+iCloud Mail has no OAuth. Pass the seller's Apple app-specific password with the registered maker hash; PayPal also passes its receiving email, and X Money passes `payeeUsername` (normalized lowercase and checked against the maker hash). For Venmo, the SDK fetches the maker's account ID from Curator (`GET /v2/makers/venmo/{payeeDetails}/payee-id`) and checks it against `payeeDetails` before any mailbox work, so sellers never enter it.
 
 ```ts
 await client.uploadICloudMailSellerCredential({
@@ -675,90 +685,124 @@ await client.releaseFundsToPayer({
 
 Use `referralFees[]` for multi-recipient fee distribution on OrchestratorV2 and V3.
 
-### Signal intent stake mode
-
-`signalIntent`, `signalIntent.prepare`, `prepareSignalIntent`, and the React
-`useSignalIntent` hook accept `noStake?: boolean` (default `false`). Use `true`
-only for Venmo Friends & Family payments funded from Venmo balance. Any other
-payment method, by name or hash, throws `ValidationError` with field `noStake`
-before `/v3/sign` is called. The SDK sends
-`abi.encode(paymentValidationPolicy, abi.encode(noStake))` to both `/v3/sign`
-and OrchestratorV3 whenever the selected deployment has a payment-validation
-policy. This target comes from the bundle, independently of the live hook.
-
-The installed `@zkp2p/contracts-v2@0.4.4-rc.5` bundle records the fresh Bypass trio
-redeployed on Base staging on 2026-10-13 as active: the staging canonical aliases
-(`StakeVault`, `DisputeProtectionPolicy`, `IntentLifecycleHookV1`) and the staging
-dispute-stack manifest name the same addresses as the Bypass records, staging
-selects UPV4, and staging signals carry the policy envelope. The predecessor
-staging vault stays exported as `StakeVaultMethodScoped`, so its stake remains
-readable and withdrawable. Base (production and preproduction) exports zero
-placeholders that the resolvers ignore: signals keep `0x`, UPV3 remains
-selected, and `noStake: true` throws `ValidationError` with field `noStake`.
-Base canonical aliases and its dispute-stack manifest are unchanged. No-stake
-availability still follows the live chain: the live lifecycle hook's policy
-must be the resolved payment-validation policy.
-
-**Breaking migration:** caller `data` is removed from signal parameters. UPV4
-interprets every non-empty V3 data value as a payment-validation envelope.
-Pass `noStake` instead; supply post-intent hook inputs as `postIntentHookData`
-at fulfillment. Legacy JavaScript calls with `data: '0x'` or `undefined`
-are accepted; other values throw `ValidationError` with field `data`.
-
-### Read or change an intent's stake mode
-
-`client.getPaymentValidationPolicyContract()` returns `{ address, abi }` or
-`undefined`. The standalone `getPaymentValidationPolicyContract(chainId, env)`
-resolves only the named Bypass policy record or its staging override. Bypass
-records remain exported by name after canonical aliases move to their addresses;
-without a Bypass address, resolution fails closed.
-The returned ABI merges the bundle with `NO_STAKE_DISPUTE_PROTECTION_POLICY_ABI`.
-
-For a deployment with that policy, the taker can change a pending intent's mode:
+### Signal data and deferred payouts
+
+New intents target OrchestratorV4 when its deployment is present, otherwise
+OrchestratorV3. Caller `data?: Hex` and `postIntentHook` are O3-only;
+O4 rejects non-empty caller data or a nonzero hook. Its `/v3/sign` request omits
+`postIntentHook` and sends `data: '0x'`. O4 fulfilment contains only `paymentProof`, `intentHash`, and
+`verificationData`; non-empty `postIntentHookData` is rejected. Existing intents resolve their original orchestrator through indexer
+routing and on-chain reads; they keep fulfilling, cancelling and releasing there.
+O4 reads use the package O4 ABI directly, including account-intent enumeration;
+ProtocolViewerV2 only decodes O3 and older intents. O4 intents have no `postIntentHook`.
+Use `getCurrentOrchestratorContract()` for new intents and
+`resolveIntentOrchestrator(intentHash)` for existing ones.
+
+Every O4 `signalIntent` struct ends with `bytes data`. The SDK always sends `0x`,
+so the gating signature covers the plain V3 packed message. The contracts can
+check a conditions hash carried in `data`, but nothing sets one yet. A stale O4
+ABI fails before signing or encoding.
+
+Attestation data retains the 448-byte UPV3 payload. For non-manual O4
+fulfilment, extension word 0 is the required `disputeWindow` in seconds (0 means
+pay now, maximum 180 days), so O4 payloads are 480 bytes. O3's 448-byte payload
+is unchanged. The SDK forwards the attestor's bytes unchanged.
+
+V2 may require stake or hold a payout when the rail default window is positive,
+the deposit token is the vault's stake token (USDC), the deposit+method whitelist
+is off, and the taker is not a registered relayer bypassing collateral.
+Registered relayers bypass by default unless the deposit has opted out.
+Registration means O4's current `relayerRegistry()`: the policy has no registry of
+its own and reads O4's at settlement, so compute `takerIsRelayer` from O4's
+registry at the same block as the other quote inputs. The SDK re-exports `DISPUTE_WINDOW_POLICY`,
+`getDefaultDisputeWindow` and `DisputeWindowPaymentMethod` from the attestation
+client. `mayRequireDisputeProtection({ paymentMethod, depositToken, stakeToken,
+whitelistEnabled, takerIsRelayer, relayerBypassOptedOut })` implements this
+quote-time rule. Venmo and PayPal default to 14 days; other supported rails default to zero. The attestor can sign a
+shorter window, including zero for balance-funded Venmo buyer-TEE evidence or
+when its window config switch is disabled.
+
+Manual release, a signed zero window, or a non-stake deposit token pays now
+without a policy record or event. With a positive window and USDC, an enabled
+deposit+method whitelist with an allowed taker pays directly without a record
+or policy event. Registered relayers also pay directly unless the deposit opts out.
+Otherwise sufficient free stake produces `STAKE`, or the net payout is
+held as `DEFERRED_PAYOUT` until `releaseEligibleAt = settlement time + window`.
+Whitelist membership, relayer registration (O4's registry, read by the policy at
+settlement) and the deposit opt-out are read live at fulfilment. O4 never executes post-intent hooks.
+
+`setDepositOptOutForRelayerBypass({ escrow, depositId, optOut })` and its
+`.prepare()` form configure a V2 deposit after creation. Only the depositor may
+write, not a delegate (`NotDepositor`). Read the setting with
+`isDepositOptedOutForRelayerBypass({ escrow, depositId })`; false is the default.
+Both methods resolve and verify the current O4 `settlementPolicy()` and fail
+closed without O4. This is deposit-wide, independent of payment method; indexer
+projections use `relayerBypassOptedOut`. It does not disable protection generally
+or change the whitelist. No deposit-creation setting is added.
+
+`CollateralSource` is `NONE, STAKE, DEFERRED_PAYOUT`. A missing (`NONE`)
+record returns `NOT_PROTECTED`; callers treat that as paid only after successful
+fulfilment. Whitelisted orders also read as `NONE`. Deferred records are `SETTLED` from
+creation. Classify a fulfil receipt using the policy's
+`DisputeProtectionIntentSettled` log first (it has no `isManualRelease`), then
+O4's `IntentPayoutDeferred` (deferred, including after policy rotation), then
+`IntentFulfilled.isManualRelease` for direct/unprotected payouts.
+`parsePayoutSettlementFromLogs(logs, intentHash, resolvedAddresses)` applies this
+order and rejects logs from other addresses or intents; call it only for a successful receipt.
 
 ```ts
-const policy = client.getPaymentValidationPolicyContract();
-if (!policy) throw new Error('No payment-validation policy in this deployment');
-
-const prepared = await client.setIntentNoStake.prepare({
-  intentHash,
-  noStake: true,
-});
-// Or execute using client.setIntentNoStake({ intentHash, noStake: true }).
-
-const noStake = await client.isIntentNoStake(intentHash);
-const intent = await client.getDisputeProtectionIntent(intentHash, {
-  disputeProtectionPolicyAddress: policy.address,
-  blockNumber: 123456n, // Optional historical read
-});
+const payout = await client.getPayoutStatus(intentHash);
+const payouts = await client.getPayoutStatuses(intentHashes);
+const prepared = await client.claimFor.prepare({ intentHash });
 ```
 
-`setIntentNoStake` accepts optional `orchestratorAddress`,
-`disputeProtectionPolicyAddress`, and `txOverrides`. The default orchestrator
-is configured OrchestratorV3; an override must be a configured orchestrator.
-The policy defaults to the payment-validation policy and throws if neither
-resolution nor an explicit address supplies one. The contract enforces taker
-ownership, pending status, and sufficient free stake when switching back to
-staked mode.
-
-`isIntentNoStake(intentHash, { disputeProtectionPolicyAddress? })` uses the same
-policy default. `getDisputeProtectionIntent(intentHash, options?)` also accepts
-`blockNumber` and falls back to the canonical policy: its eight-field tuple is
-identical on the old deployment. Pin the original policy when reading historical
-intents; this API does not discover which policy owns an intent.
-
-`DisputeProtectionIntent` contains `taker`, `stakeOwner`, `depositor`,
-`paymentMethod`, `status`, `riskWindow`, `releaseEligibleAt`, and
-`releaseAmount`. Its exported `DisputeProtectionIntentStatus` enum is
-`None=0, Pending=1, Cancelled=2, Settled=3, Released=4, Disputed=5`.
-`parseDisputeProtectionIntent(value: unknown)` accepts a named object or
-positional tuple and returns `null` for malformed values. The client getter
-throws for malformed results.
-
-`encodePaymentValidationHookData(policy: Address, noStake: boolean): Hex` and
-`decodePaymentValidationHookData(data: Hex): { policy: Address; noStake: boolean } | null`
-are exported for integrations validating envelopes; decoding rejects malformed
-or noncanonical data.
+`PayoutState` contains `NOT_PROTECTED`, `PAID`, `HELD`,
+`CLAIMABLE`, `CLAIMED`, `RELEASED_TO_STAKE`, and `DISPUTED`. Results include
+`collateralSource`, `recipient`, `taker`, `lockedAmount`, `claimedAmount`,
+`releaseEligibleAt`, and `claimable`. Reads pin the intent and dependent free-stake
+batches to one block. A released payout can be claimed only up to the remaining
+per-intent amount and the recipient's free stake. The taker or recipient may call
+`claimFor`; funds always go to the recipient.
+
+`claimFor({ intentHash, disputeProtectionPolicyAddress?, txOverrides? })` resolves
+the policy holding the intent. An optional `disputeProtectionPolicyAddress` must
+match that resolved policy; a mismatch, missing intent, invalid hash, or
+non-cascade policy throws `ValidationError`. Both sending and `.prepare()` target
+the resolved cascade policy. Omitting the address performs the same lookup.
+Payout reads and `claimFor` first ask the client's indexer for the intent's
+settlement policy (`IntentSettlementPolicyState`, recorded from O4's
+`IntentSettlementPolicySnapshotted`; O4 deletes its own snapshot at settlement).
+They read the record from that policy and use that policy's `stakeVault()`, so a
+policy rotated out before a package update still resolves. Only rows for the
+client's chain and packaged OrchestratorV4 count, and the indexed policy must
+return a valid V2 record for the intent. When the indexer has no row (for example
+just after fulfilment), fails, or does not serve the entity yet, or the indexed
+policy has no record, the SDK falls back to the packaged `disputeProtectionPolicyV2`
+and the live `settlementPolicy()` read from the packaged OrchestratorV4 address.
+Zero addresses are skipped and candidates are deduplicated; both are classified
+as V2. If the indexed policy's read fails and the fallback finds no record, the
+read throws instead of returning `NOT_PROTECTED`. Payout reads pin every record,
+each holding policy's `stakeVault()`, and its recipient's `freeStake` to one
+block. No record returns `NOT_PROTECTED`; records on two fallback policies fail
+closed. Claims target the policy holding the record, which pays only the
+record's recipient. The standalone `getPayoutStatuses(publicClient, chainId, env,
+hashes, { indexer? })` and `findDisputeProtectionIntent({ ..., indexer? })` use an
+indexer only when one is passed. The strict current-stack checks for stake writes
+are unchanged.
+
+`client.parseDeferredPayoutFromLogs(logs, intentHash)` accepts only events from
+its packaged cascade policy or V4 orchestrator. O4's `IntentPayoutDeferred` also identifies deferrals after policy rotation. The standalone parser additionally
+requires `{ disputeProtectionPolicyV2Address, orchestratorV4Address }`.
+
+`findDisputeProtectionIntent` returns a discriminated `generation`:
+`PolicyGeneration.V2` has a validated ten-field record (no `riskWindow` or `releaseAmount`) and four statuses (`NONE`, `SETTLED`, `RELEASED`, `DISPUTED`, ordinals 0–3);
+`PolicyGeneration.V1` retains the eight-field record and six statuses.
+`readDisputeAttestationConfig({ policyAddress })` follows either known generation.
+
+V4 readiness and indexer APIs that list deferred payouts await the new manifest
+and indexer schema; payout reads already use the indexer's settlement-policy rows
+when it serves them. The retained readiness reader verifies V3 only and is not V4 readiness
+proof. This SDK version is `0.15.0-rc.2`, a prerelease on the npm `dev` tag.
 
 ## Extend an Intent Lifetime
 
@@ -807,15 +851,28 @@ The guardian charges the target deposit's token and pays the deposit owner.
 Extension payments are prepaid and non-refundable. `extendIntentLifetime.prepare()`
 returns calldata without sending it.
 
-## Historical Deposit Access Policy
+## Deposit Access Policy
 
 `client.accessPolicy` exposes environment-aware reads and unwind-only prepared
 transactions for policies written before Groups were retired. Gate use on
 `client.accessPolicy.isSupported`; unsupported deployments fail closed.
 
+It targets the current orchestrator's deposit whitelist. That is
+`WhitelistPolicyV4` when OrchestratorV4 is deployed (Base staging), otherwise
+`WhitelistPolicy` (Base production). `getContracts().addresses.whitelistPolicy`
+and `client.whitelistPolicyAddress` resolve the same contract, which equals
+`whitelistPolicy()` on OrchestratorV4 and DisputeProtectionPolicyV2. If
+OrchestratorV4 is deployed without `WhitelistPolicyV4`, both are undefined and
+access-policy calls fail closed. They never fall back to O3's whitelist.
+Every deposit starts with the whitelist off on `WhitelistPolicyV4`. Entries on
+O3's `WhitelistPolicy` don't carry over and only gate OrchestratorV3 signals.
+
 Existing policies remain enforced on-chain until disabled or their deposits
-close. The only new policy is the trusted group bypass that `createDeposit()`
-adds to Venmo and PayPal deposits by default. Depositors can use
+close. The only new policy is the opt-in trusted-group whitelist that
+`createDeposit()` adds to Venmo and PayPal deposits only with
+`enableTrustedGroupBypass: true` (defaults to false). On OrchestratorV4 an enabled
+whitelist makes the deposit private: only Peer Pay merchant-group members can
+signal, and members skip dispute-protection staking. Depositors can use
 `prepareDisable`, `prepareRemoveAllowedGroups`, and
 `prepareRemoveWhitelistedAddresses` to fail open and remove historical entries.
 
@@ -1325,11 +1382,15 @@ Amazon capture requires extension 0.6.8 or later. Staging SAR uses the trusted s
 ### Historical dispute policy lookup
 
 `findDisputeProtectionIntent({ publicClient, chainId, environment, intentHash,
-blockNumber? })` queries the payment-validation, canonical, manifest, and
-recognized predecessor policies in that order, deduplicated. The first intent
-whose status is not `None` wins. It returns `null` only when every intent read
-parses as `None`; an unreadable intent throws. The result contains
-`policyAddress`, the parsed `intent`, and `noStake` (false if that getter reverts).
+blockNumber?, indexer? })` first reads the indexer's settlement policy for the
+intent when an `indexer` is passed (see deferred payouts). Otherwise, or when that
+policy holds no record, it queries the packaged V2 and O4 live settlement policies, then
+canonical, manifest, and recognized predecessor policies, deduplicated at one
+block. Both V2 candidates use the cascade ABI. Multiple V2 records for one hash
+throw; otherwise the first intent whose status is not `None` wins. It returns `null` only when every intent read parses as
+`None`; an unreadable intent throws. The result contains the policy
+`generation` (`v2` or `v1`), `policyAddress`, and the `intent` parsed with
+that generation's struct and status enum.
 All calls share a block. Use the returned policy for dispute submission and
 `readDisputeAttestationConfig({ publicClient, chainId, environment, policyAddress })`.
 For a known non-manifest policy, the latter follows `disputeVerifier()` and

package/dist/build-metadata.json

@@ -2,12 +2,12 @@
   "schemaVersion": 2,
   "source": {
     "repository": "zkp2p/zkp2p-clients",
-    "commitSha": "471e50cadb04d41b35fe48316aa94c56dec4d4a7",
+    "commitSha": "82e9074021ad0c79aa3391e64e2879f0f23c118e",
     "kind": "github",
     "distributable": true
   },
-  "sdkPackageVersion": "0.15.0-rc.0",
-  "contractsPackageVersion": "0.4.4-rc.5",
+  "sdkPackageVersion": "0.15.0-rc.2",
+  "contractsPackageVersion": "0.4.4-rc.6",
   "indexerSchemaPackageVersion": "0.22.0",
   "activeDisputeStack": {
     "base": {
@@ -16,7 +16,7 @@
     },
     "baseStaging": {
       "version": 2,
-      "selectionHash": "e3b360a09c2f541052ab7519987862e1f59c0efc9bc25daea09937e9ea59b783"
+      "selectionHash": "6c49c1ce51eec594a22385c4efcab08aa9926b6b63a725e14a0027ec5d2f4fc9"
     }
   }
 }