@zkp2p/sdk 0.11.2 → 0.12.1

package/README.md

@@ -6,8 +6,8 @@
 
 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.
 
-Workspace version: `0.11.0`. Install `@zkp2p/sdk@latest` for the stable Curator
-v3 routes and OrchestratorV3 hard cut.
+Install `@zkp2p/sdk@latest` for the stable Curator v3, OrchestratorV3, staking,
+and chargeback-risk surface. The workspace version lives in `package.json`.
 
 ## Why This SDK
 
@@ -30,7 +30,7 @@ v3 routes and OrchestratorV3 hard cut.
 - 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.
 - Indexer for history and filtering: use `client.indexer.*` for pagination, historical volumes, fund activities, daily snapshots, and vault analytics.
 - Version-aware routing: new intents use EscrowV2 and OrchestratorV3; existing intent reads and lifecycle writes resolve their OrchestratorV2 or V3 owner. Legacy V1 fallbacks have been removed.
-- Modular internals: intent, guardian, access-policy, vault, and ProtocolViewer logic are extracted from `Zkp2pClient`, keeping the main client focused on orchestration.
+- Modular internals: intent, guardian, access-policy, staking, vault, and ProtocolViewer logic are extracted from `Zkp2pClient`, keeping the main client focused on orchestration.
 - App-level rollout control: the SDK is capability-based. Product gating and phase flags belong in your app layer, not inside transaction helpers.
 
 ## Installation
@@ -107,6 +107,8 @@ Indexer defaults by environment:
 | 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Attribution                    | ERC-8021 helpers like `sendTransactionWithAttribution`, `encodeWithAttribution`, and `txOverrides.referrer` support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Taker staking                  | `ensureStakeAllowance`, `depositStake`, `withdrawStake`, `claim`, `setTakerAuthorization`, `selectStakeOwner`, `clearStakeOwner`, direct StakeVault reads, and `client.indexer.getStakingState()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Chargeback keepers             | `releaseMaturedChargebackIntent`, `releaseMaturedChargebackIntents`, with caller-pinned `chargebackPolicyAddress` support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 ## Extension Metadata Bridge
 
@@ -144,10 +146,11 @@ peer.authenticate({
 });
 ```
 
-`requestConnection()` is required for third-party origins. `authenticate()`
-accepts an optional inline `providerConfig` object; otherwise the extension
-fetches the default template from `https://api.zkp2p.xyz/providers/`. Buyer TEE
-is API/template driven: pass `captureMode: "buyerTee"` plus
+`requestConnection()` opens an extension-owned approval window for third-party
+origins. Trusted Peer hosts and `localhost` are already connected.
+`authenticate()` identifies the provider with `platform` and
+`actionType`; the extension fetches the matching extension-managed template
+from `https://api.zkp2p.xyz/providers/`. Buyer TEE is API/template driven: pass `captureMode: "buyerTee"` plus
 `attestationServiceUrl`, and the extension returns encrypted session material.
 For SAR, pass `captureMode: "sellerCredential"` and optionally pass
 `attestationServiceUrl` only when overriding the extension's production
@@ -212,8 +215,8 @@ const { hashedOnchainIds } = await client.registerPayeeDetails({
 const quote = await client.getQuote({
   paymentPlatforms: ['wise'],
   fiatCurrency: 'USD',
-  user: '0x1111111111111111111111111111111111111111',
-  recipient: '0x1111111111111111111111111111111111111111',
+  user: '0xBuyer',
+  recipient: '0xBuyer',
   destinationChainId: 8453,
   destinationToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
   amount: '250',
@@ -228,6 +231,79 @@ const payeeHash = await client.resolvePayeeHash(
 
 `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).
 
+## Taker Staking
+
+```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 onchain = await client.getStakeVaultState({
+  staker: takerAddress,
+  taker: takerAddress,
+});
+
+const indexed = await client.indexer.getStakingState({
+  chainId: 8453,
+  environment: 'base',
+  vaultAddress: client.getStakeVaultContract().address,
+  chargebackPolicyAddress: client.getChargebackPolicyContract().address,
+  taker: takerAddress,
+  // Always supply the effective owner from the fresh on-chain read.
+  stakeOwner: onchain.stakeOwner,
+});
+// indexed: effective/raw ownership, total/locked/free stake, claimable,
+// authorizations, admissions-pause state, Vault controller, and per-row
+// freshness.
+```
+
+Stake writes expose direct and `.prepare()` variants: `depositStake`,
+`withdrawStake`, `claim`, `setTakerAuthorization`, `selectStakeOwner`, and
+`clearStakeOwner`. 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 (1:1); never sum a taker's self-stake with a
+sponsor's stake.
+
+The vault's controller is the `ChargebackPolicy` contract. It owns
+per-payment-method risk windows (`getRiskWindow(paymentMethodHash)`),
+per-deposit chargeback enablement (`isChargebackEnabled(escrow, depositId)`),
+and the global `admissionsPaused()` switch. `@zkp2p/contracts-v2@0.4.0`
+resolves the deployed StakeVault, ChargebackPolicy, and OrchestratorV3 for
+both the production and staging bundles; a bundle without them fails closed
+(`VITE_BASE_STAGING_STAKE_VAULT_ADDRESS` /
+`VITE_BASE_STAGING_CHARGEBACK_POLICY_ADDRESS` overrides support local
+deployments).
+
+Keeper writes are direct and prepareable:
+
+```ts
+const release = await client.releaseMaturedChargebackIntents.prepare({
+  intentHashes: [intentHash],
+  chargebackPolicyAddress: snapshottedPolicyAddress,
+});
+```
+
+An explicit `chargebackPolicyAddress` is caller-pinned and may be outside the
+client's configured deployment context, allowing sweepers to group intents by
+their snapshotted policy deployment without a later SDK configuration change
+rerouting them.
+
+`client.indexer.getStakingState()` composes the `@zkp2p/indexer-schema@0.20.0`
+account rows and preserves their individual freshness. Its caller-supplied
+`stakeOwner` must come from a fresh on-chain `stakeOwnerOf(taker)` read; stale
+indexed ownership is reported without attributing another owner's balance.
+Refetch immediately before signaling; the contract stays authoritative.
+
 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
@@ -644,6 +720,17 @@ const fulfilledEvents = await client.indexer.getFulfilledIntentEvents(['0xIntent
 const fulfillment = await client.indexer.getIntentFulfillmentAmounts('0xIntentHash');
 const fulfillmentAndPayment = await client.indexer.getFulfillmentAndPayment('0xIntentHash');
 
+// Indexed staking state. stakeOwner must come from a fresh
+// stakeOwnerOf(taker) read; the adapter checks it against indexed ownership.
+const stakingState = await client.indexer.getStakingState({
+  chainId: 8453,
+  environment: 'base',
+  vaultAddress: '0xStakeVault',
+  chargebackPolicyAddress: '0xChargebackPolicy',
+  taker: '0xTaker',
+  stakeOwner: '0xEffectiveStakeOwner',
+});
+
 // Received USDC:
 // - fulfilledEvents[0].amount is the net USDC transferred to the taker.
 // - fulfillment.takerAmountNetFees is the same net taker amount from the Intent row.
@@ -713,15 +800,23 @@ Hook groups:
 
 ```ts
 import {
+  DEFERRED_SETTLEMENT_FUNDED_EVENT_ABI,
   getContracts,
+  getOrchestratorV3Contract,
   getPaymentMethodsCatalog,
   getRateManagerContracts,
+  getChargebackPolicyContract,
+  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 chargebackPolicy = getChargebackPolicyContract(8453, 'staging');
 const paymentMethods = getPaymentMethodsCatalog(8453, 'production');
 const usdHash = resolveFiatCurrencyBytes32('USD');
 const wiseHash = resolvePaymentMethodHash('wise', { env: 'production' });