@zkp2p/sdk 0.10.0-rc.5 → 0.10.0-rc.6

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 +110 -16
  2. package/dist/{chunk-2KGAHUBH.mjs → chunk-3XY3E4VH.mjs} +34812 -248
  3. package/dist/chunk-3XY3E4VH.mjs.map +1 -0
  4. package/dist/{chunk-EIOXBVXP.mjs → chunk-LPJE2MN7.mjs} +3 -39
  5. package/dist/chunk-LPJE2MN7.mjs.map +1 -0
  6. package/dist/index.cjs +35280 -411
  7. package/dist/index.cjs.map +1 -1
  8. package/dist/index.d.mts +47 -61
  9. package/dist/index.d.ts +47 -61
  10. package/dist/index.mjs +358 -31
  11. package/dist/index.mjs.map +1 -1
  12. package/dist/protocolViewerParsers-HMOHJWSP.mjs +5 -0
  13. package/dist/{protocolViewerParsers-V2RTIEDG.mjs.map → protocolViewerParsers-HMOHJWSP.mjs.map} +1 -1
  14. package/dist/react.cjs +97 -94
  15. package/dist/react.cjs.map +1 -1
  16. package/dist/react.d.mts +33 -14
  17. package/dist/react.d.ts +33 -14
  18. package/dist/react.mjs +99 -68
  19. package/dist/react.mjs.map +1 -1
  20. package/dist/{vaultUtils-D-DVzOoX.d.mts → vaultUtils-B2FVQeaS.d.mts} +324 -106
  21. package/dist/{vaultUtils-D-DVzOoX.d.ts → vaultUtils-B2FVQeaS.d.ts} +324 -106
  22. package/package.json +1 -1
  23. package/dist/chunk-2KGAHUBH.mjs.map +0 -1
  24. package/dist/chunk-EIOXBVXP.mjs.map +0 -1
  25. package/dist/protocolViewerParsers-V2RTIEDG.mjs +0 -5
package/README.md CHANGED
@@ -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()` 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.
84
84
 
85
85
  Indexer defaults by environment:
86
86
 
@@ -94,16 +94,18 @@ Indexer defaults by environment:
94
94
  | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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
- | Intents | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`, `getFulfillIntentInputs` |
97
+ | Intents | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`, `getFulfillIntentInputs`, including explicit staging OrchestratorV3 routing |
98
98
  | 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` |
99
+ | Payee and quote APIs | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getQuotesBestByPlatform` |
100
100
  | Seller automated release | `uploadSellerCredential`, `getSellerCredentialStatus`, `verifySellerPayment` |
101
101
  | Delegation and hooks | `setDelegate`, `removeDelegate`, `setRateManager`, `clearRateManager`, `setDepositRateManager`, `clearDepositRateManager`, `setDepositPreIntentHook`, `setDepositWhitelistHook` |
102
102
  | Vault / DRM | `createRateManager`, `setVaultMinRate`, `setVaultMinRatesBatch`, `setVaultFee`, `setVaultConfig`, `getDepositRateManager`, `getManagerFee`, `getEffectiveRate` |
103
+ | Taker staking | `ensureStakeAllowance`, `depositStake`, `withdrawStake`, `claim`, `setTakerAuthorization`, `selectStakeOwner`, `clearStakeOwner`, direct StakeVault reads, and exact full-gross risk math |
104
+ | V3 settlement operations | `releaseMaturedPositions`, `reconcileCancellation(s)`, OrchestratorV3 intent prepares, and exported settlement event ABIs |
103
105
  | Oracle config | `setOracleRateConfig`, `setOracleRateConfigBatch`, `removeOracleRateConfig`, `updateCurrencyConfigBatch`, `deactivateCurrenciesBatch`, `supportsInlineOracleRateConfig`, `validateOracleFeedsOnChain` |
104
106
  | RPC reads | `getDeposits`, `getDeposit`, `getDepositsById`, `getIntents`, `getIntent`, `getPvDepositById`, `getPvDepositsFromIds`, `getPvAccountDeposits`, `getPvAccountIntents`, `getPvIntent` |
105
107
  | 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 |
108
+ | React hooks | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, and payment methods |
107
109
  | Attribution | ERC-8021 helpers like `sendTransactionWithAttribution`, `encodeWithAttribution`, and `txOverrides.referrer` support |
108
110
 
109
111
  ## Extension Metadata Bridge
@@ -180,7 +182,7 @@ console.log(result.depositDetails);
180
182
 
181
183
  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
184
 
183
- ## Payee Registration, Quotes, and Taker Tier
185
+ ## Payee Registration and Quotes
184
186
 
185
187
  ```ts
186
188
  import { resolvePaymentMethodHash } from '@zkp2p/sdk';
@@ -204,26 +206,112 @@ const { hashedOnchainIds } = await client.registerPayeeDetails({
204
206
  const quote = await client.getQuote({
205
207
  paymentPlatforms: ['wise'],
206
208
  fiatCurrency: 'USD',
207
- user: '0x1111111111111111111111111111111111111111',
208
- recipient: '0x1111111111111111111111111111111111111111',
209
+ user: '0xBuyer',
210
+ recipient: '0xBuyer',
209
211
  destinationChainId: 8453,
210
212
  destinationToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
211
213
  amount: '250',
212
214
  isExactFiat: true,
213
215
  });
214
216
 
215
- const takerTier = await client.getTakerTier({
216
- owner: '0x1111111111111111111111111111111111111111',
217
- chainId: 8453,
218
- });
219
-
220
217
  const payeeHash = await client.resolvePayeeHash(
221
218
  42n,
222
219
  resolvePaymentMethodHash('wise', { env: 'production' }),
223
220
  );
224
221
  ```
225
222
 
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.
223
+ `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). Quotes do not reserve or filter by OrchestratorV3 stake capacity; fetch the configured Curator environment's capacity view separately and treat on-chain admission as final.
224
+
225
+ ## Taker Stake & Capacity
226
+
227
+ ```ts
228
+ const amount = 250_000000n;
229
+ const approval = await client.ensureStakeAllowance({ amount });
230
+ // Wait for approval.hash to confirm when hadAllowance is false.
231
+
232
+ await client.depositStake({ amount }); // sender becomes the stake owner
233
+ await client.withdrawStake({ amount: 50_000000n }); // immediate, free stake only
234
+ await client.claim(); // withdraws the caller's full claimable balance
235
+
236
+ // Safe sponsorship is a two-actor flow:
237
+ await client.setTakerAuthorization({ taker, authorized: true }); // signed by the Safe
238
+ await client.selectStakeOwner({ stakeOwner: safeAddress }); // signed by the taker
239
+ await client.clearStakeOwner(); // taker returns to self-stake
240
+
241
+ const stake = await client.getTakerStake({ owner: takerAddress, chainId: 8453 });
242
+ // stake.responseObject: effective stakeOwner, selectedStakeOwner +
243
+ // selectionAuthorized, stake { totalUsdc, lockedUsdc, freeUsdc },
244
+ // claimableUsdc, riskTakingPaused — base-unit strings.
245
+
246
+ const capacity = await client.getTakerCapacity({ owner: takerAddress, chainId: 8453 });
247
+ // capacity.responseObject.platforms[]: enabled, chargebackable,
248
+ // deferredPayoutEnabled, riskWindowSeconds, extensionPenaltyBpsPerHour, and
249
+ // stakeBacked (1:1 free stake, or an explicit unbounded-by-stake state).
250
+
251
+ const onchain = await client.getStakeVaultState({
252
+ staker: stakeOwnerAddress,
253
+ taker: takerAddress,
254
+ });
255
+ ```
256
+
257
+ Stake writes expose direct and `.prepare()` variants: `depositStake`,
258
+ `withdrawStake`, `claim`, `setTakerAuthorization`, `selectStakeOwner`, and
259
+ `clearStakeOwner`. Post-PR #200 there is no withdrawal request, cooldown, or
260
+ exit lifecycle — `withdrawStake` is immediate up to `freeStake`, and `claim`
261
+ withdraws the complete claimable balance. Chargebackable capacity is exactly
262
+ the effective owner's free stake (full-gross 1:1); never sum a taker's
263
+ self-stake with a sponsor's stake. No post-#200 StakeVault/RiskManager
264
+ deployment exists yet in any environment, so SDK contract resolution fails
265
+ closed everywhere until one ships (a `VITE_BASE_STAGING_STAKE_VAULT_ADDRESS` /
266
+ `VITE_BASE_STAGING_RISK_MANAGER_ADDRESS` override supports local deployments).
267
+
268
+ The staging deployment exposes OrchestratorV3 through
269
+ `getDeployedAddresses()` and `getOrchestratorV3Contract()`;
270
+ `getRiskManagerContract()` resolves only once a post-#200 RiskManager is
271
+ deployed (or via the env-var override). Route an intent explicitly by passing
272
+ `orchestratorAddress: client.getDeployedAddresses().orchestratorV3`.
273
+ OrchestratorV3 signals are ungated: the SDK encodes an empty gating signature
274
+ and zero expiration without calling the curator signing endpoint. Existing
275
+ OrchestratorV2 signaling remains gated.
276
+
277
+ An explicit `orchestratorAddress` is caller-pinned. The SDK honors it even when
278
+ the address is outside the client's configured deployment context, using the
279
+ OrchestratorV3 ABI for signal, cancel, and fulfill preparation. This lets
280
+ integrators snapshot the target when a payment is created and keep every
281
+ lifecycle transaction on that target across later SDK or deployment changes.
282
+
283
+ Keeper writes are direct and prepareable:
284
+
285
+ ```ts
286
+ const sweep = await client.releaseMaturedPositions.prepare({
287
+ intentHashes: [intentHash],
288
+ riskManagerAddress: snapshottedRiskManagerAddress,
289
+ });
290
+ const cancellations = await client.reconcileCancellations.prepare({
291
+ intentHashes: [intentHash],
292
+ riskManagerAddress: snapshottedRiskManagerAddress,
293
+ });
294
+ ```
295
+
296
+ Like `orchestratorAddress`, an explicit `riskManagerAddress` is caller-pinned
297
+ and may be outside the client's configured deployment context. All keeper
298
+ methods honor it for direct and `.prepare()` calls, allowing sweepers to group
299
+ positions by their snapshotted RiskManager deployment without a later SDK
300
+ configuration change rerouting them.
301
+
302
+ For receipt classification, import `RISK_POSITION_SETTLED_EVENT_ABI` and
303
+ `DEFERRED_SETTLEMENT_FUNDED_EVENT_ABI` and pass them to viem's
304
+ `decodeEventLog()`.
305
+
306
+ `getTakerStake()` and `getTakerCapacity()` wrap curator
307
+ `GET /v2/taker/stake` and `GET /v2/taker/capacity` on the post-PR #200
308
+ full-gross contract. Platform capacities are alternative views of one shared
309
+ stake-owner portfolio — never sum them, and never filter quotes by capacity.
310
+ Non-chargebackable platforms report an explicit unbounded-by-stake state, and
311
+ deferred payout is an alternative settlement mode that never adds to
312
+ stake-backed capacity. Capacity can change whenever any authorized taker uses
313
+ the shared stake, so refetch immediately before signaling; the contract stays
314
+ authoritative.
227
315
 
228
316
  For table-style liquidity UIs, the low-level `apiGetOrderbookTable()` adapter exposes curator's paginated public/private orderbook rows and row-level privacy metadata.
229
317
 
@@ -626,14 +714,12 @@ import {
626
714
  useSignalIntent,
627
715
  useCreateVault,
628
716
  useVaultDelegation,
629
- useGetTakerTier,
630
717
  } from '@zkp2p/sdk/react';
631
718
 
632
719
  const createDeposit = useCreateDeposit({ client });
633
720
  const signalIntent = useSignalIntent({ client });
634
721
  const createVault = useCreateVault({ client, sendTransaction });
635
722
  const vaultDelegation = useVaultDelegation({ client, sendTransaction, sendBatch });
636
- const takerTier = useGetTakerTier({ client, owner, chainId, autoFetch: true });
637
723
  ```
638
724
 
639
725
  Hook groups:
@@ -643,7 +729,7 @@ Hook groups:
643
729
  - Intent lifecycle: `useSignalIntent`, `useFulfillIntent`, `useReleaseFundsToPayer`, `usePruneExpiredIntents`
644
730
  - Delegation: `useSetDelegate`, `useRemoveDelegate`
645
731
  - Vault / DRM: `useCreateVault`, `useVaultDelegation`, `useSetVaultFee`, `useSetVaultMinRate`, `useSetVaultConfig`
646
- - Taker tier: `useGetTakerTier`, plus `getTierDisplayInfo()` and `getNextTierCap()` helpers
732
+ - Taker stake and capacity: `useGetTakerStake`, `useGetTakerCapacity`
647
733
 
648
734
  `useVaultDelegation()` is the batching-oriented hook. It returns `delegateDeposit`, `delegateDeposits`, `clearDelegation`, and `clearDelegations`.
649
735
 
@@ -651,15 +737,23 @@ Hook groups:
651
737
 
652
738
  ```ts
653
739
  import {
740
+ DEFERRED_PAYOUT_RECORDED_EVENT_ABI,
654
741
  getContracts,
742
+ getOrchestratorV3Contract,
655
743
  getPaymentMethodsCatalog,
656
744
  getRateManagerContracts,
745
+ getRiskManagerContract,
746
+ getStakeVaultContract,
747
+ RISK_POSITION_SETTLED_EVENT_ABI,
657
748
  resolveFiatCurrencyBytes32,
658
749
  resolvePaymentMethodHash,
659
750
  } from '@zkp2p/sdk';
660
751
 
661
752
  const contracts = getContracts(8453, 'production');
662
753
  const rateManagerContracts = getRateManagerContracts(8453, 'production');
754
+ const stakeVault = getStakeVaultContract(8453, 'staging');
755
+ const orchestratorV3 = getOrchestratorV3Contract(8453, 'staging');
756
+ const riskManager = getRiskManagerContract(8453, 'staging');
663
757
  const paymentMethods = getPaymentMethodsCatalog(8453, 'production');
664
758
  const usdHash = resolveFiatCurrencyBytes32('USD');
665
759
  const wiseHash = resolvePaymentMethodHash('wise', { env: 'production' });