@zkp2p/sdk 0.10.0 → 0.11.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/README.md +29 -21
  2. package/dist/{chunk-JRLUSPR3.mjs → chunk-BRIDD433.mjs} +27831 -17236
  3. package/dist/chunk-BRIDD433.mjs.map +1 -0
  4. package/dist/{chunk-WXEP544Y.mjs → chunk-FCOH36IX.mjs} +3 -39
  5. package/dist/chunk-FCOH36IX.mjs.map +1 -0
  6. package/dist/index.cjs +28583 -18008
  7. package/dist/index.cjs.map +1 -1
  8. package/dist/index.d.mts +9 -64
  9. package/dist/index.d.ts +9 -64
  10. package/dist/index.mjs +124 -197
  11. package/dist/index.mjs.map +1 -1
  12. package/dist/protocolViewerParsers-ZZKVAPPA.mjs +5 -0
  13. package/dist/{protocolViewerParsers-QMHI74AA.mjs.map → protocolViewerParsers-ZZKVAPPA.mjs.map} +1 -1
  14. package/dist/react.cjs +0 -133
  15. package/dist/react.cjs.map +1 -1
  16. package/dist/react.d.mts +3 -25
  17. package/dist/react.d.ts +3 -25
  18. package/dist/react.mjs +4 -107
  19. package/dist/react.mjs.map +1 -1
  20. package/dist/{vaultUtils-DeUFIx3l.d.mts → vaultUtils-BnXI9_ng.d.mts} +48 -131
  21. package/dist/{vaultUtils-DeUFIx3l.d.ts → vaultUtils-BnXI9_ng.d.ts} +48 -131
  22. package/package.json +3 -3
  23. package/dist/chunk-JRLUSPR3.mjs.map +0 -1
  24. package/dist/chunk-WXEP544Y.mjs.map +0 -1
  25. package/dist/protocolViewerParsers-QMHI74AA.mjs +0 -5
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  Stable TypeScript SDK for trustless fiat-to-crypto on Base. ZKP2P combines escrowed on-chain settlement, TLS attestations for payment verification, and API/indexer helpers so makers, takers, wallets, and embedded ramps can ship production-grade fiat liquidity flows without building their own contract or indexing stack.
8
8
 
9
- Current version: `0.9.0`
9
+ Current version: `0.10.0`
10
10
 
11
11
  ## Why This SDK
12
12
 
@@ -29,7 +29,7 @@ Current version: `0.9.0`
29
29
  - RPC-first reads: primary reads use ProtocolViewer and on-chain fallbacks, so `getDeposits()`, `getDeposit()`, `getIntents()`, `getIntent()`, and the `getPv*` methods are not blocked on indexer lag.
30
30
  - Indexer for history and filtering: use `client.indexer.*` for pagination, historical volumes, fund activities, daily snapshots, and vault analytics.
31
31
  - V2-only routing: the client resolves against EscrowV2 and OrchestratorV2. Legacy V1 escrow/orchestrator fallbacks have been removed from both read and write paths.
32
- - Modular internals: intent, vault, and ProtocolViewer logic are extracted into `IntentOperations`, `VaultOperations`, and `ProtocolViewerReader`, keeping `Zkp2pClient` focused on orchestration.
32
+ - Modular internals: intent, guardian, access-policy, vault, and ProtocolViewer logic are extracted from `Zkp2pClient`, keeping the main client focused on orchestration.
33
33
  - App-level rollout control: the SDK is capability-based. Product gating and phase flags belong in your app layer, not inside transaction helpers.
34
34
 
35
35
  ## Installation
@@ -80,7 +80,7 @@ const client = new Zkp2pClient({
80
80
  - `indexerUrl` and `baseApiUrl`: override defaults when you are targeting custom deployments
81
81
  - `timeouts`: `{ api?: number }` — API timeout in milliseconds (default 15000)
82
82
 
83
- **No external API key is required.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, `signalIntent`, and the rest of the public SDK flows work without `apiKey` or `authorizationToken`. When `baseApiUrl` is configured, `signalIntent()` can auto-fetch a gating service signature from curator `/v3/intent/sign` without auth. Quote responses include resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`) when curator has them.
83
+ **No external API key is required.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `signalIntent`, and the rest of the public SDK flows work without `apiKey` or `authorizationToken`. When `baseApiUrl` is configured, `signalIntent()` uses curator `/v3/sign` without auth and treats its 409 response as a direct, signature-free signal. Quote responses include resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`) when curator has them.
84
84
 
85
85
  Indexer defaults by environment:
86
86
 
@@ -95,15 +95,16 @@ Indexer defaults by environment:
95
95
  | Deposits | `createDeposit`, `addFunds`, `removeFunds`, `withdrawDeposit`, `ensureAllowance`, `setAcceptingIntents`, `setIntentRange`, `setCurrencyMinRate`, `setRetainOnEmpty` |
96
96
  | Payment methods and currencies | `addPaymentMethods`, `removePaymentMethod`, `setPaymentMethodActive`, `addCurrencies`, `removeCurrency`, `deactivateCurrency`, `pruneExpiredIntents` |
97
97
  | Intents | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`, `getFulfillIntentInputs`, `getIntentGuardianPolicy`, `quoteIntentExtension`, `getIntentGuardianPayerFunding`, `extendIntentLifetime` |
98
+ | Deposit access policy | `client.accessPolicy.*`, `planAccessPolicyUpdate`, `diffAccessPolicy` |
98
99
  | Prepared transactions | `client.prepareCreateDeposit(...)`, `client.signalIntent.prepare(...)`, `client.fulfillIntent.prepare(...)`, `client.setVaultFee.prepare(...)`, and equivalent prepare flows across the rest of the prepareable write surface |
99
- | Payee and quote APIs | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getQuotesBestByPlatform`, `getTakerTier` |
100
+ | Payee and quote APIs | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getQuotesBestByPlatform` |
100
101
  | Seller automated release | `uploadSellerCredential`, `getSellerCredentialStatus`, `verifySellerPayment` |
101
102
  | Delegation and hooks | `setDelegate`, `removeDelegate`, `setRateManager`, `clearRateManager`, `setDepositRateManager`, `clearDepositRateManager`, `setDepositPreIntentHook`, `setDepositWhitelistHook` |
102
103
  | Vault / DRM | `createRateManager`, `setVaultMinRate`, `setVaultMinRatesBatch`, `setVaultFee`, `setVaultConfig`, `getDepositRateManager`, `getManagerFee`, `getEffectiveRate` |
103
104
  | Oracle config | `setOracleRateConfig`, `setOracleRateConfigBatch`, `removeOracleRateConfig`, `updateCurrencyConfigBatch`, `deactivateCurrenciesBatch`, `supportsInlineOracleRateConfig`, `validateOracleFeedsOnChain` |
104
105
  | RPC reads | `getDeposits`, `getDeposit`, `getDepositsById`, `getIntents`, `getIntent`, `getPvDepositById`, `getPvDepositsFromIds`, `getPvAccountDeposits`, `getPvAccountIntents`, `getPvIntent` |
105
106
  | Indexer | `client.indexer.getDeposits`, `getDepositsWithRelations`, `getDepositById`, `getDepositsByIds`, `getDepositsByIdsWithRelations`, `getDepositsByPayeeHash`, `getIntentsForDeposits`, `getOwnerIntents`, `getIntentsByRateManager`, `getIntentByHash`, `getExpiredIntents`, `getFulfilledIntentEvents`, `getIntentFulfillmentAmounts`, `getFulfillmentAndPayment`, `getDepositFundActivities`, `getMakerFundActivities`, `getDepositDailySnapshots`, `getProfitSnapshotsByDeposits`, `getRateManagers`, `getRateManagerDetail`, `getRateManagerDelegations`, `getDelegationForDeposit`, `getManagerDailySnapshots`, `getManualRateUpdates`, `getOracleConfigUpdates`, `query` |
106
- | React hooks | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, payment methods, and taker tier |
107
+ | React hooks | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, and payment methods |
107
108
  | Attribution | ERC-8021 helpers like `sendTransactionWithAttribution`, `encodeWithAttribution`, and `txOverrides.referrer` support |
108
109
 
109
110
  ## Extension Metadata Bridge
@@ -180,7 +181,7 @@ console.log(result.depositDetails);
180
181
 
181
182
  If you do not pass `payeeDetailsHashes`, `createDeposit()` can register the payee details for you. If you want to pre-register or reuse hashes across deposits, use `registerPayeeDetails()` first.
182
183
 
183
- ## Payee Registration, Quotes, and Taker Tier
184
+ ## Payee Registration and Quotes
184
185
 
185
186
  ```ts
186
187
  import { resolvePaymentMethodHash } from '@zkp2p/sdk';
@@ -212,18 +213,13 @@ const quote = await client.getQuote({
212
213
  isExactFiat: true,
213
214
  });
214
215
 
215
- const takerTier = await client.getTakerTier({
216
- owner: '0x1111111111111111111111111111111111111111',
217
- chainId: 8453,
218
- });
219
-
220
216
  const payeeHash = await client.resolvePayeeHash(
221
217
  42n,
222
218
  resolvePaymentMethodHash('wise', { env: 'production' }),
223
219
  );
224
220
  ```
225
221
 
226
- `getQuote()` returns available liquidity plus payee details when authenticated. Use `getQuotesBestByPlatform()` to fetch the best quote per supported payment platform in a single call (handy for cross-platform comparison UIs). `getTakerTier()` returns limits, cooldown data, Peer Pay volume progression, and `volumeBreakdown` rows for taker UX.
222
+ `getQuote()` returns available liquidity plus payee details when authenticated. Use `getQuotesBestByPlatform()` to fetch the best quote per supported payment platform in a single call (handy for cross-platform comparison UIs).
227
223
 
228
224
  For table-style liquidity UIs, the low-level `apiGetOrderbookTable()` adapter exposes curator's paginated public/private orderbook rows and row-level privacy metadata.
229
225
 
@@ -232,12 +228,12 @@ For table-style liquidity UIs, the low-level `apiGetOrderbookTable()` adapter ex
232
228
  ```ts
233
229
  await client.uploadSellerCredential({
234
230
  platform: 'venmo',
235
- offchainId: 'alice',
236
- payeeId: '123456',
231
+ offchainId: 'example-user',
232
+ payeeId: 'example-payee-id',
237
233
  sessionMaterial: {
238
- recipientUsername: 'alice',
239
- accountId: '123456',
240
- sessionCookie: 'session-cookie',
234
+ recipientUsername: 'example-user',
235
+ accountId: 'example-account-id',
236
+ sessionCookie: 'redacted-session-cookie',
241
237
  },
242
238
  });
243
239
  ```
@@ -331,6 +327,19 @@ The guardian charges the target deposit's token and pays the deposit owner.
331
327
  Extension payments are prepaid and non-refundable. `extendIntentLifetime.prepare()`
332
328
  returns calldata without sending it.
333
329
 
330
+ ## Deposit Access Policy
331
+
332
+ `client.accessPolicy` exposes environment-aware reads and prepareable writes
333
+ for `WhitelistPolicy` and `AddressGroupRegistry`. Gate the UI on
334
+ `client.accessPolicy.isSupported`; unsupported deployments fail closed.
335
+
336
+ Use `planAccessPolicyUpdate(persisted, draft)` or `diffAccessPolicy()` to turn a
337
+ policy edit into deterministic, idempotent transaction steps, then prepare each
338
+ step with `client.accessPolicy.preparePlanStep(...)` or the complete plan with
339
+ `preparePlan(...)`. Writes are depositor-only. A saved policy configures
340
+ storage; it does not enforce intent admission until the intent path consumes
341
+ the policy.
342
+
334
343
  ## Referral Account API
335
344
 
336
345
  Apps can read referral data publicly by wallet address and can write with either
@@ -671,26 +680,25 @@ Most mutation hooks return a named action plus status fields such as `isLoading`
671
680
  import {
672
681
  useCreateDeposit,
673
682
  useSignalIntent,
683
+ useExtendIntentLifetime,
674
684
  useCreateVault,
675
685
  useVaultDelegation,
676
- useGetTakerTier,
677
686
  } from '@zkp2p/sdk/react';
678
687
 
679
688
  const createDeposit = useCreateDeposit({ client });
680
689
  const signalIntent = useSignalIntent({ client });
690
+ const extendIntent = useExtendIntentLifetime({ client });
681
691
  const createVault = useCreateVault({ client, sendTransaction });
682
692
  const vaultDelegation = useVaultDelegation({ client, sendTransaction, sendBatch });
683
- const takerTier = useGetTakerTier({ client, owner, chainId, autoFetch: true });
684
693
  ```
685
694
 
686
695
  Hook groups:
687
696
 
688
697
  - Deposit lifecycle: `useCreateDeposit`, `useAddFunds`, `useRemoveFunds`, `useWithdrawDeposit`, `useSetAcceptingIntents`, `useSetIntentRange`, `useSetCurrencyMinRate`, `useSetRetainOnEmpty`
689
698
  - Payment and currency management: `useAddPaymentMethods`, `useRemovePaymentMethod`, `useSetPaymentMethodActive`, `useAddCurrencies`, `useRemoveCurrency`, `useDeactivateCurrency`
690
- - Intent lifecycle: `useSignalIntent`, `useFulfillIntent`, `useReleaseFundsToPayer`, `usePruneExpiredIntents`
699
+ - Intent lifecycle: `useSignalIntent`, `useFulfillIntent`, `useReleaseFundsToPayer`, `usePruneExpiredIntents`, `useExtendIntentLifetime`
691
700
  - Delegation: `useSetDelegate`, `useRemoveDelegate`
692
701
  - Vault / DRM: `useCreateVault`, `useVaultDelegation`, `useSetVaultFee`, `useSetVaultMinRate`, `useSetVaultConfig`
693
- - Taker tier: `useGetTakerTier`, plus `getTierDisplayInfo()` and `getNextTierCap()` helpers
694
702
 
695
703
  `useVaultDelegation()` is the batching-oriented hook. It returns `delegateDeposit`, `delegateDeposits`, `clearDelegation`, and `clearDelegations`.
696
704