@zkp2p/cash 0.4.3 → 0.4.5

package/dist/index.js

@@ -1,5 +1,5 @@
-import { MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, CASH_RETAIN_ON_EMPTY, CASH_INTENT_GUARDIAN_ADDRESS, BASE_USDC_ADDRESS, USDC_DECIMALS, BASE_CHAIN_ID, errors, isCashError, CASH_ORDER_STATUSES, mapChainError, CashError } from './chunk-IHEOGLAS.js';
-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, isUserRejectedError } from './chunk-IHEOGLAS.js';
+import { MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, CASH_RETAIN_ON_EMPTY, CASH_INTENT_GUARDIAN_ADDRESS, BASE_USDC_ADDRESS, USDC_DECIMALS, BASE_CHAIN_ID, CASH_RESTRICTED_PLATFORMS, errors, isCashError, CASH_ORDER_STATUSES, mapChainError, CashError, CASH_ACCESS_GROUP_IDS } from './chunk-YD5VHZXR.js';
+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, isUserRejectedError } from './chunk-YD5VHZXR.js';
 import { parseAbi, parseEventLogs, isAddress, http, createWalletClient, encodeFunctionData } from 'viem';
 import { base } from 'viem/chains';
 import { getSpreadOracleConfig, currencyInfo, getPaymentMethodsCatalog, getGatingServiceAddress, resolvePaymentMethodHashFromCatalog, resolvePaymentMethodNameFromHash, getCurrencyCodeFromHash, createCompositeDepositId, appendAttributionToCalldata, Zkp2pClient, CHAINLINK_ORACLE_FEEDS } from '@zkp2p/sdk';
@@ -461,7 +461,8 @@ function buildCapabilities(environment) {
       platform,
       currencies: [...new Set(currencies2)].sort(),
       payeeHint: PAYEE_HINTS[platform] ?? "Your payment handle for this platform",
-      requiresIdentityAttestation: IDENTITY_ATTESTATION_PLATFORMS.has(platform)
+      requiresIdentityAttestation: IDENTITY_ATTESTATION_PLATFORMS.has(platform),
+      requiresAtomicAccessPolicy: CASH_RESTRICTED_PLATFORMS.has(platform)
     };
   }).filter((p) => p.currencies.length > 0).sort((a, b) => a.platform.localeCompare(b.platform));
   const currencies = [...new Set(platforms.flatMap((p) => p.currencies))].sort();
@@ -1427,6 +1428,12 @@ function createCashClient(options) {
       ...range ? { intentAmountRange: range } : {}
     };
   }
+  function assertGenericCashoutSupported(payoutInput) {
+    const restrictedPlatforms = payoutInput.payouts.map((payout) => payout.processorName.toLowerCase()).filter((platform) => CASH_RESTRICTED_PLATFORMS.has(platform));
+    if (restrictedPlatforms.length > 0) {
+      throw errors.atomicAccessPolicyRequired(restrictedPlatforms);
+    }
+  }
   function isCashPayoutSet(payouts) {
     return payouts.length > 0 && payouts.every((payout) => payout.pricing.marketRate && payout.pricing.spreadBps === 0);
   }
@@ -1666,6 +1673,28 @@ function createCashClient(options) {
     if (lastNonceError) throw lastNonceError;
     throw new Error(`Signer provider did not observe Relay nonce ${afterRelay - 1}`);
   }
+  function prepareCashoutAccess(depositId, client = readClient) {
+    const { compositeId, escrowAddress, onchainDepositId } = parseDepositId(depositId);
+    const groupIds = CASH_ACCESS_GROUP_IDS[environment];
+    try {
+      const prepared = client.accessPolicy.prepareConfigureDeposit({
+        escrow: escrowAddress,
+        depositId: onchainDepositId,
+        enabled: true,
+        groupIds,
+        takers: [],
+        txOverrides: attribution
+      });
+      return {
+        to: prepared.to,
+        data: prepared.data,
+        value: prepared.value,
+        chainId: prepared.chainId
+      };
+    } catch (err) {
+      throw errors.accessPolicyConfigurationFailed(compositeId, groupIds, err);
+    }
+  }
   return {
     capabilities,
     async sourceCapabilities() {
@@ -1703,6 +1732,7 @@ function createCashClient(options) {
     },
     async cashout(input, opts) {
       const payoutInput = validatePayout(input);
+      assertGenericCashoutSupported(payoutInput);
       const client = await signingClient("cashout", opts);
       const owner = opts.signer.account.address;
       let sourceResult;
@@ -1870,6 +1900,7 @@ function createCashClient(options) {
     async prepare(input) {
       if (input.source) throw errors.sourceRouteUnsupportedInPrepare();
       const depositInput = validateDepositInput(input.amount, input);
+      assertGenericCashoutSupported(depositInput);
       const params = await buildDepositParams(readClient, depositInput);
       const { prepared } = await readClient.prepareCreateDeposit({
         ...params,
@@ -1901,7 +1932,8 @@ function createCashClient(options) {
             description: "Create the protocol-held cash-out order."
           }
         ],
-        register: { hashedOnchainIds }
+        register: { hashedOnchainIds },
+        accessPolicyRequired: false
       };
     },
     finalizePreparedCashout(receipt) {
@@ -1930,6 +1962,7 @@ function createCashClient(options) {
         })
       };
     },
+    prepareAccessPolicy: prepareCashoutAccess,
     async order(depositId) {
       return fetchOrder(depositId);
     },
@@ -2384,6 +2417,7 @@ var cashoutResultJsonSchema = z.object({
   escrowAddress: z.string(),
   onchainDepositId: nonNegativeBigintString,
   order: cashOrderJsonSchema,
+  accessPolicyTxHash: z.string().optional(),
   source: z.object({
     amount: nonNegativeBigintString,
     requestId: z.string().optional(),
@@ -2394,7 +2428,8 @@ var cashoutResultJsonSchema = z.object({
 var prepareResultJsonSchema = z.object({
   txs: z.array(preparedTransactionJsonSchema),
   steps: z.array(cashPreparedStepJsonSchema),
-  register: z.object({ hashedOnchainIds: z.array(z.string()) })
+  register: z.object({ hashedOnchainIds: z.array(z.string()) }),
+  accessPolicyRequired: z.boolean()
 });
 var withdrawResultJsonSchema = z.object({
   depositId: z.string(),
@@ -2425,7 +2460,8 @@ var cashCapabilitiesJsonSchema = z.object({
       platform: z.string(),
       currencies: z.array(z.string()),
       payeeHint: z.string(),
-      requiresIdentityAttestation: z.boolean()
+      requiresIdentityAttestation: z.boolean(),
+      requiresAtomicAccessPolicy: z.boolean().optional()
     })
   ),
   currencies: z.array(z.string()),
@@ -2461,6 +2497,7 @@ var CASH_ERROR_CODES = defineCashErrorCodes([
   "ORDER_NOT_FOUND",
   "PAYEE_REGISTRATION_FAILED",
   "PAYEE_VERIFICATION_REQUIRED",
+  "ATOMIC_ACCESS_POLICY_REQUIRED",
   "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE",
   "SOURCE_RECIPIENT_MISMATCH",
   "SOURCE_CAPABILITIES_FAILED",
@@ -2472,6 +2509,7 @@ var CASH_ERROR_CODES = defineCashErrorCodes([
   "SOURCE_CASHOUT_SUBMISSION_UNKNOWN",
   "SOURCE_CASHOUT_STATUS_UNKNOWN",
   "DEPOSIT_RESOLUTION_FAILED",
+  "ACCESS_POLICY_CONFIGURATION_FAILED",
   "ALLOWANCE_NOT_VISIBLE",
   "SIGNER_REQUIRED",
   "SIGNER_CHAIN_MISMATCH",
@@ -2517,6 +2555,12 @@ var cashErrorRecoveryJsonSchema = z.discriminatedUnion("kind", [
     kind: z.literal("inspect-base-transaction"),
     transactionHash: z.string(),
     operation: z.string()
+  }).strict(),
+  z.object({
+    kind: z.literal("configure-cashout-access-policy"),
+    depositId: z.string(),
+    groupIds: z.array(z.string()),
+    transactionHash: z.string().optional()
   }).strict()
 ]);
 var cashErrorJsonSchema = z.object({
@@ -2774,6 +2818,7 @@ function cashoutResultToJson(result) {
     escrowAddress: result.escrowAddress,
     onchainDepositId: result.onchainDepositId.toString(),
     order: orderToJson(result.order),
+    accessPolicyTxHash: result.accessPolicyTxHash,
     source: result.source ? {
       ...result.source,
       amount: result.source.amount.toString()
@@ -2788,6 +2833,7 @@ function cashoutResultFromJson(json) {
     escrowAddress: parsed.escrowAddress,
     onchainDepositId: BigInt(parsed.onchainDepositId),
     order: orderFromJson(parsed.order),
+    accessPolicyTxHash: parsed.accessPolicyTxHash,
     source: parsed.source ? {
       ...parsed.source,
       amount: BigInt(parsed.source.amount)
@@ -2798,7 +2844,8 @@ function prepareResultToJson(result) {
   return {
     txs: result.txs.map(preparedTxToJson),
     steps: result.steps.map(preparedStepToJson),
-    register: result.register
+    register: result.register,
+    accessPolicyRequired: result.accessPolicyRequired
   };
 }
 function prepareResultFromJson(json) {
@@ -2806,7 +2853,8 @@ function prepareResultFromJson(json) {
   return {
     txs: parsed.txs.map(preparedTxFromJson),
     steps: parsed.steps.map(preparedStepFromJson),
-    register: parsed.register
+    register: parsed.register,
+    accessPolicyRequired: parsed.accessPolicyRequired
   };
 }
 function withdrawResultToJson(result) {
@@ -2857,7 +2905,8 @@ function capabilitiesFromJson(json) {
     },
     platforms: parsed.platforms.map((p) => ({
       ...p,
-      currencies: p.currencies
+      currencies: p.currencies,
+      requiresAtomicAccessPolicy: p.requiresAtomicAccessPolicy ?? CASH_RESTRICTED_PLATFORMS.has(p.platform)
     })),
     currencies: parsed.currencies,
     amount: {
@@ -2886,6 +2935,13 @@ function cashErrorFromJson(json) {
         transactionHash: parsed.recovery.transactionHash,
         operation: parsed.recovery.operation
       };
+    } else if (parsed.recovery.kind === "configure-cashout-access-policy") {
+      recovery = {
+        kind: parsed.recovery.kind,
+        depositId: parsed.recovery.depositId,
+        groupIds: parsed.recovery.groupIds,
+        ...parsed.recovery.transactionHash !== void 0 ? { transactionHash: parsed.recovery.transactionHash } : {}
+      };
     } else if (parsed.recovery.kind === "inspect-base-operation-submission") {
       recovery = {
         kind: parsed.recovery.kind,

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-import { s as CashClient, L as EstimateInput, i as CashEstimate, J as CashoutOptions, h as CashoutResult, H as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-CYSM84-K.cjs';
+import { s as CashClient, L as EstimateInput, i as CashEstimate, J as CashoutOptions, h as CashoutResult, H as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-CL1SCbqF.cjs';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-import { s as CashClient, L as EstimateInput, i as CashEstimate, J as CashoutOptions, h as CashoutResult, H as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-CYSM84-K.js';
+import { s as CashClient, L as EstimateInput, i as CashEstimate, J as CashoutOptions, h as CashoutResult, H as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-CL1SCbqF.js';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 

package/dist/react.js

@@ -1,4 +1,4 @@
-import { isCashError, CASH_ORDER_POLL_INTERVAL_MS } from './chunk-IHEOGLAS.js';
+import { isCashError, CASH_ORDER_POLL_INTERVAL_MS } from './chunk-YD5VHZXR.js';
 import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
 
 function useEstimate({

package/dist/tools.cjs

@@ -2,7 +2,7 @@
 
 // package.json
 var package_default = {
-  version: "0.4.3"};
+  version: "0.4.5"};
 
 // src/tools/index.ts
 var bigintString = {
@@ -164,7 +164,7 @@ var builtInCashTools = [
   },
   {
     name: "cash_cashout",
-    description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",
+    description: "Start an unrestricted-rail Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. Platforms marked requiresAtomicAccessPolicy fail closed because this tool cannot safely prepare them. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",
     inputSchema: {
       type: "object",
       properties: {

package/dist/tools.d.cts

@@ -145,7 +145,7 @@ declare const builtInCashTools: readonly [{
     };
 }, {
     readonly name: "cash_cashout";
-    readonly description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.";
+    readonly description: "Start an unrestricted-rail Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. Platforms marked requiresAtomicAccessPolicy fail closed because this tool cannot safely prepare them. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/dist/tools.d.ts

@@ -145,7 +145,7 @@ declare const builtInCashTools: readonly [{
     };
 }, {
     readonly name: "cash_cashout";
-    readonly description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.";
+    readonly description: "Start an unrestricted-rail Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. Platforms marked requiresAtomicAccessPolicy fail closed because this tool cannot safely prepare them. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/dist/tools.js

@@ -1,6 +1,6 @@
 // package.json
 var package_default = {
-  version: "0.4.3"};
+  version: "0.4.5"};
 
 // src/tools/index.ts
 var bigintString = {
@@ -162,7 +162,7 @@ var builtInCashTools = [
   },
   {
     name: "cash_cashout",
-    description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",
+    description: "Start an unrestricted-rail Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. Platforms marked requiresAtomicAccessPolicy fail closed because this tool cannot safely prepare them. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",
     inputSchema: {
       type: "object",
       properties: {

package/docs/lifecycle-and-recovery.md

@@ -65,6 +65,16 @@ but the host or a signer-backed client must execute the route before
 transaction confirms, call `finalizePreparedCashout(receipt)` to decode it with
 the environment-correct escrow ABI and obtain the resumable `CashoutResult`.
 
+Venmo, Cash App, and PayPal require atomic deposit creation and access-policy
+configuration. The generic `cashout()` and `prepare()` paths reject these rails
+with `ATOMIC_ACCESS_POLICY_REQUIRED` before wallet access, Relay work, payee
+registration, allowance, or deposit submission. Peer web performs the required
+guard-before, create, guard-after, and policy configuration in one Curator-backed
+batch. A host must provide the same atomic guarantee to support these rails.
+Discovery marks them with `requiresAtomicAccessPolicy: true`.
+`prepareAccessPolicy(depositId)` is retained only to recover a restricted
+deposit already created by `0.4.4`; it is not a safe new-order sequence.
+
 There is no static chain/token allowlist in Peer Cash. Relay decides source
 support through its metadata and quote execution, filtered to the viem/EVM
 execution surface this SDK can sign. Peer Cash hardcodes only the Base USDC
@@ -291,6 +301,7 @@ explicit override.
 | `INVALID_PAYOUT_PLATFORMS`              | no        | The payout leg set is empty or repeats a platform. Pass one leg, or an array of legs using each platform at most once.                       |
 | `PAYEE_VERIFICATION_REQUIRED`           | no        | A new Wise/PayPal payee needs an attestation. Register it through Peer first; an existing registration can be reused.                        |
 | `PAYEE_REGISTRATION_FAILED`             | yes       | Curator rejected the handle or was unavailable. Check `payeeHint` and retry.                                                                 |
+| `ATOMIC_ACCESS_POLICY_REQUIRED`         | no        | Venmo, Cash App, or PayPal needs atomic creation and group policy setup. Use Peer web or an equivalent atomic host; nothing was submitted.   |
 | `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`   | no        | `prepare()` accepts Base USDC only. Use signed source execution, or complete Relay first and then prepare the Base cashout.                  |
 | `SOURCE_RECIPIENT_MISMATCH`             | no        | Relay output recipient differs from the cashout depositor. Use the depositor address.                                                        |
 | `SOURCE_CAPABILITIES_FAILED`            | yes       | Relay source discovery failed. Retry or use Base USDC.                                                                                       |
@@ -308,6 +319,7 @@ explicit override.
 | `TRANSACTION_SUBMISSION_UNKNOWN`        | no        | A Base mutation returned no hash but may have broadcast. Inspect wallet/protocol state and its recovery action before any retry.             |
 | `TRANSACTION_STATUS_UNKNOWN`            | no        | A transaction was submitted but its receipt is unknown. Inspect `recovery.transactionHash` before resubmitting.                              |
 | `DEPOSIT_RESOLUTION_FAILED`             | no        | Base tx succeeded but no `DepositReceived` was decoded. Inspect its logs and recover the composite id.                                       |
+| `ACCESS_POLICY_CONFIGURATION_FAILED`    | no        | A `0.4.4` cash-out exists without confirmed group policy. Configure that existing deposit from recovery data; never create it again.         |
 | `INVALID_DEPOSIT_ID`                    | no        | The id is not `escrowAddress_onchainId`. A bare number cannot cold-hydrate; use the value returned by `cashout()`.                           |
 | `ORDER_NOT_FOUND`                       | yes       | Unknown id or immediate indexer lag. Verify the id and retry shortly after creation.                                                         |
 | `INDEXER_LAG`                           | yes       | Indexer trails the chain. Retry the read shortly.                                                                                            |

package/examples/agent-tool-use.ts

@@ -104,10 +104,16 @@ console.log(`manifest: ${cashToolManifest.name}@${cashToolManifest.version}`);
 console.log(`tools: ${cashToolManifest.tools.map((t) => t.name).join(', ')}\n`);
 
 const caps = (await executeTool('cash_capabilities', {})) as {
-  platforms: { platform: string; currencies: string[]; payeeHint: string }[];
+  platforms: {
+    platform: string;
+    currencies: string[];
+    payeeHint: string;
+    requiresAtomicAccessPolicy: boolean;
+  }[];
 };
-console.log(`agent sees ${caps.platforms.length} platforms; venmo hint:`);
-console.log(`  "${caps.platforms.find((p) => p.platform === 'venmo')?.payeeHint}"\n`);
+const venmo = caps.platforms.find((p) => p.platform === 'venmo');
+console.log(`agent sees ${caps.platforms.length} platforms; venmo capability:`);
+console.log(`  hint="${venmo?.payeeHint}" atomic=${venmo?.requiresAtomicAccessPolicy}\n`);
 
 const est = await executeTool('cash_estimate', {
   amount: usdc(250).toString(),

package/examples/node-cashout.ts

@@ -11,8 +11,10 @@
  * The curator validates supported handles against the live platform, so the
  * payee must be a real account. A new Wise/PayPal registration also needs the
  * identity attestation created by Peer; an existing registered handle can be
- * reused. Override the demo corridor with:
- *   CASH_PLATFORM=venmo CASH_CURRENCY=USD CASH_PAYEE=@your-venmo
+ * reused. Venmo, Cash App, and PayPal require Peer web or another host that
+ * creates the deposit and access policy atomically, so this generic demo uses
+ * Chime by default. Override the demo corridor with:
+ *   CASH_PLATFORM=revolut CASH_CURRENCY=EUR CASH_PAYEE=your-revtag
  */
 import { createWalletClient, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -26,9 +28,9 @@ const signer = createWalletClient({ account, chain: base, transport: http() });
 // One leg here; `receive` also accepts an array of legs to offer several
 // platforms on one order (each platform at most once, all at the oracle rate).
 const receive = {
-  platform: process.env.CASH_PLATFORM ?? 'venmo',
+  platform: process.env.CASH_PLATFORM ?? 'chime',
   currency: (process.env.CASH_CURRENCY ?? 'USD') as CurrencyType,
-  payee: { offchainId: process.env.CASH_PAYEE ?? '@your-venmo' },
+  payee: { offchainId: process.env.CASH_PAYEE ?? '$your-chime-sign' },
 };
 
 const cash = createCashClient({ environment: 'staging' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Peer Cash - offramp-only SDK for routing crypto to Base USDC, then cashing out to fiat at the live oracle market rate.",
   "license": "MIT",
   "author": "Peer (https://peer.xyz)",