@zkp2p/sdk 0.10.0-rc.6 → 0.10.0

package/README.md

@@ -80,7 +80,7 @@ const client = new Zkp2pClient({
 - `indexerUrl` and `baseApiUrl`: override defaults when you are targeting custom deployments
 - `timeouts`: `{ api?: number }` — API timeout in milliseconds (default 15000)
 
-**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.
+**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.
 
 Indexer defaults by environment:
 
@@ -94,18 +94,16 @@ Indexer defaults by environment:
 | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Deposits                       | `createDeposit`, `addFunds`, `removeFunds`, `withdrawDeposit`, `ensureAllowance`, `setAcceptingIntents`, `setIntentRange`, `setCurrencyMinRate`, `setRetainOnEmpty`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | Payment methods and currencies | `addPaymentMethods`, `removePaymentMethod`, `setPaymentMethodActive`, `addCurrencies`, `removeCurrency`, `deactivateCurrency`, `pruneExpiredIntents`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Intents                        | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`, `getFulfillIntentInputs`, including explicit staging OrchestratorV3 routing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Intents                        | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`, `getFulfillIntentInputs`, `getIntentGuardianPolicy`, `quoteIntentExtension`, `getIntentGuardianPayerFunding`, `extendIntentLifetime`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | 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                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Payee and quote APIs           | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getQuotesBestByPlatform`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Payee and quote APIs           | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getQuotesBestByPlatform`, `getTakerTier`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | Seller automated release       | `uploadSellerCredential`, `getSellerCredentialStatus`, `verifySellerPayment`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Delegation and hooks           | `setDelegate`, `removeDelegate`, `setRateManager`, `clearRateManager`, `setDepositRateManager`, `clearDepositRateManager`, `setDepositPreIntentHook`, `setDepositWhitelistHook`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Vault / DRM                    | `createRateManager`, `setVaultMinRate`, `setVaultMinRatesBatch`, `setVaultFee`, `setVaultConfig`, `getDepositRateManager`, `getManagerFee`, `getEffectiveRate`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Taker staking                  | `ensureStakeAllowance`, `depositStake`, `withdrawStake`, `claim`, `setTakerAuthorization`, `selectStakeOwner`, `clearStakeOwner`, direct StakeVault reads, and exact full-gross risk math                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| V3 settlement operations       | `releaseMaturedPositions`, `reconcileCancellation(s)`, OrchestratorV3 intent prepares, and exported settlement event ABIs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Oracle config                  | `setOracleRateConfig`, `setOracleRateConfigBatch`, `removeOracleRateConfig`, `updateCurrencyConfigBatch`, `deactivateCurrenciesBatch`, `supportsInlineOracleRateConfig`, `validateOracleFeedsOnChain`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | RPC reads                      | `getDeposits`, `getDeposit`, `getDepositsById`, `getIntents`, `getIntent`, `getPvDepositById`, `getPvDepositsFromIds`, `getPvAccountDeposits`, `getPvAccountIntents`, `getPvIntent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | 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` |
-| React hooks                    | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, and payment methods                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| React hooks                    | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, payment methods, and taker tier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Attribution                    | ERC-8021 helpers like `sendTransactionWithAttribution`, `encodeWithAttribution`, and `txOverrides.referrer` support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ## Extension Metadata Bridge
@@ -182,7 +180,7 @@ console.log(result.depositDetails);
 
 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.
 
-## Payee Registration and Quotes
+## Payee Registration, Quotes, and Taker Tier
 
 ```ts
 import { resolvePaymentMethodHash } from '@zkp2p/sdk';
@@ -206,112 +204,26 @@ const { hashedOnchainIds } = await client.registerPayeeDetails({
 const quote = await client.getQuote({
   paymentPlatforms: ['wise'],
   fiatCurrency: 'USD',
-  user: '0xBuyer',
-  recipient: '0xBuyer',
+  user: '0x1111111111111111111111111111111111111111',
+  recipient: '0x1111111111111111111111111111111111111111',
   destinationChainId: 8453,
   destinationToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
   amount: '250',
   isExactFiat: true,
 });
 
+const takerTier = await client.getTakerTier({
+  owner: '0x1111111111111111111111111111111111111111',
+  chainId: 8453,
+});
+
 const payeeHash = await client.resolvePayeeHash(
   42n,
   resolvePaymentMethodHash('wise', { env: 'production' }),
 );
 ```
 
-`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.
-
-## Taker Stake & Capacity
-
-```ts
-const amount = 250_000000n;
-const approval = await client.ensureStakeAllowance({ amount });
-// Wait for approval.hash to confirm when hadAllowance is false.
-
-await client.depositStake({ amount }); // sender becomes the stake owner
-await client.withdrawStake({ amount: 50_000000n }); // immediate, free stake only
-await client.claim(); // withdraws the caller's full claimable balance
-
-// Safe sponsorship is a two-actor flow:
-await client.setTakerAuthorization({ taker, authorized: true }); // signed by the Safe
-await client.selectStakeOwner({ stakeOwner: safeAddress }); // signed by the taker
-await client.clearStakeOwner(); // taker returns to self-stake
-
-const stake = await client.getTakerStake({ owner: takerAddress, chainId: 8453 });
-// stake.responseObject: effective stakeOwner, selectedStakeOwner +
-// selectionAuthorized, stake { totalUsdc, lockedUsdc, freeUsdc },
-// claimableUsdc, riskTakingPaused — base-unit strings.
-
-const capacity = await client.getTakerCapacity({ owner: takerAddress, chainId: 8453 });
-// capacity.responseObject.platforms[]: enabled, chargebackable,
-// deferredPayoutEnabled, riskWindowSeconds, extensionPenaltyBpsPerHour, and
-// stakeBacked (1:1 free stake, or an explicit unbounded-by-stake state).
-
-const onchain = await client.getStakeVaultState({
-  staker: stakeOwnerAddress,
-  taker: takerAddress,
-});
-```
-
-Stake writes expose direct and `.prepare()` variants: `depositStake`,
-`withdrawStake`, `claim`, `setTakerAuthorization`, `selectStakeOwner`, and
-`clearStakeOwner`. Post-PR #200 there is no withdrawal request, cooldown, or
-exit lifecycle — `withdrawStake` is immediate up to `freeStake`, and `claim`
-withdraws the complete claimable balance. Chargebackable capacity is exactly
-the effective owner's free stake (full-gross 1:1); never sum a taker's
-self-stake with a sponsor's stake. No post-#200 StakeVault/RiskManager
-deployment exists yet in any environment, so SDK contract resolution fails
-closed everywhere until one ships (a `VITE_BASE_STAGING_STAKE_VAULT_ADDRESS` /
-`VITE_BASE_STAGING_RISK_MANAGER_ADDRESS` override supports local deployments).
-
-The staging deployment exposes OrchestratorV3 through
-`getDeployedAddresses()` and `getOrchestratorV3Contract()`;
-`getRiskManagerContract()` resolves only once a post-#200 RiskManager is
-deployed (or via the env-var override). Route an intent explicitly by passing
-`orchestratorAddress: client.getDeployedAddresses().orchestratorV3`.
-OrchestratorV3 signals are ungated: the SDK encodes an empty gating signature
-and zero expiration without calling the curator signing endpoint. Existing
-OrchestratorV2 signaling remains gated.
-
-An explicit `orchestratorAddress` is caller-pinned. The SDK honors it even when
-the address is outside the client's configured deployment context, using the
-OrchestratorV3 ABI for signal, cancel, and fulfill preparation. This lets
-integrators snapshot the target when a payment is created and keep every
-lifecycle transaction on that target across later SDK or deployment changes.
-
-Keeper writes are direct and prepareable:
-
-```ts
-const sweep = await client.releaseMaturedPositions.prepare({
-  intentHashes: [intentHash],
-  riskManagerAddress: snapshottedRiskManagerAddress,
-});
-const cancellations = await client.reconcileCancellations.prepare({
-  intentHashes: [intentHash],
-  riskManagerAddress: snapshottedRiskManagerAddress,
-});
-```
-
-Like `orchestratorAddress`, an explicit `riskManagerAddress` is caller-pinned
-and may be outside the client's configured deployment context. All keeper
-methods honor it for direct and `.prepare()` calls, allowing sweepers to group
-positions by their snapshotted RiskManager deployment without a later SDK
-configuration change rerouting them.
-
-For receipt classification, import `RISK_POSITION_SETTLED_EVENT_ABI` and
-`DEFERRED_SETTLEMENT_FUNDED_EVENT_ABI` and pass them to viem's
-`decodeEventLog()`.
-
-`getTakerStake()` and `getTakerCapacity()` wrap curator
-`GET /v2/taker/stake` and `GET /v2/taker/capacity` on the post-PR #200
-full-gross contract. Platform capacities are alternative views of one shared
-stake-owner portfolio — never sum them, and never filter quotes by capacity.
-Non-chargebackable platforms report an explicit unbounded-by-stake state, and
-deferred payout is an alternative settlement mode that never adds to
-stake-backed capacity. Capacity can change whenever any authorized taker uses
-the shared stake, so refetch immediately before signaling; the contract stays
-authoritative.
+`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.
 
 For table-style liquidity UIs, the low-level `apiGetOrderbookTable()` adapter exposes curator's paginated public/private orderbook rows and row-level privacy metadata.
 
@@ -372,6 +284,53 @@ await client.releaseFundsToPayer({
 
 Use `referralFees[]` for multi-recipient fee distribution on OrchestratorV2.
 
+## Extend an Intent Lifetime
+
+The standalone `IntentGuardian` lets any payer buy more time for a live intent.
+The fee is owner-governed, so read a fresh quote immediately before signing and
+use `maxCost` as the payer's hard ceiling.
+
+```ts
+const policy = await client.getIntentGuardianPolicy();
+if (!policy.extensionsEnabled) {
+  throw new Error('Intent extensions are disabled');
+}
+
+const quote = await client.quoteIntentExtension({
+  intentAmount: 250_000n,
+  additionalTime: 60n * 60n,
+});
+
+const depositToken = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const payer = walletClient.account.address;
+const funding = await client.getIntentGuardianPayerFunding({
+  payer,
+  token: depositToken,
+});
+
+if (funding.balance < quote.cost) {
+  throw new Error('Insufficient token balance');
+}
+
+await client.ensureAllowance({
+  token: depositToken,
+  spender: policy.guardian,
+  amount: quote.cost,
+});
+
+await client.extendIntentLifetime({
+  escrow: '0xEscrow',
+  depositId: 42n,
+  intentHash,
+  additionalTime: 60n * 60n,
+  maxCost: quote.cost,
+});
+```
+
+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.
+
 ## Referral Account API
 
 Apps can read referral data publicly by wallet address and can write with either
@@ -714,12 +673,14 @@ import {
   useSignalIntent,
   useCreateVault,
   useVaultDelegation,
+  useGetTakerTier,
 } from '@zkp2p/sdk/react';
 
 const createDeposit = useCreateDeposit({ client });
 const signalIntent = useSignalIntent({ client });
 const createVault = useCreateVault({ client, sendTransaction });
 const vaultDelegation = useVaultDelegation({ client, sendTransaction, sendBatch });
+const takerTier = useGetTakerTier({ client, owner, chainId, autoFetch: true });
 ```
 
 Hook groups:
@@ -729,7 +690,7 @@ Hook groups:
 - Intent lifecycle: `useSignalIntent`, `useFulfillIntent`, `useReleaseFundsToPayer`, `usePruneExpiredIntents`
 - Delegation: `useSetDelegate`, `useRemoveDelegate`
 - Vault / DRM: `useCreateVault`, `useVaultDelegation`, `useSetVaultFee`, `useSetVaultMinRate`, `useSetVaultConfig`
-- Taker stake and capacity: `useGetTakerStake`, `useGetTakerCapacity`
+- Taker tier: `useGetTakerTier`, plus `getTierDisplayInfo()` and `getNextTierCap()` helpers
 
 `useVaultDelegation()` is the batching-oriented hook. It returns `delegateDeposit`, `delegateDeposits`, `clearDelegation`, and `clearDelegations`.
 
@@ -737,23 +698,15 @@ Hook groups:
 
 ```ts
 import {
-  DEFERRED_PAYOUT_RECORDED_EVENT_ABI,
   getContracts,
-  getOrchestratorV3Contract,
   getPaymentMethodsCatalog,
   getRateManagerContracts,
-  getRiskManagerContract,
-  getStakeVaultContract,
-  RISK_POSITION_SETTLED_EVENT_ABI,
   resolveFiatCurrencyBytes32,
   resolvePaymentMethodHash,
 } from '@zkp2p/sdk';
 
 const contracts = getContracts(8453, 'production');
 const rateManagerContracts = getRateManagerContracts(8453, 'production');
-const stakeVault = getStakeVaultContract(8453, 'staging');
-const orchestratorV3 = getOrchestratorV3Contract(8453, 'staging');
-const riskManager = getRiskManagerContract(8453, 'staging');
 const paymentMethods = getPaymentMethodsCatalog(8453, 'production');
 const usdHash = resolveFiatCurrencyBytes32('USD');
 const wiseHash = resolvePaymentMethodHash('wise', { env: 'production' });