@zkp2p/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,30 +1,36 @@
 # @zkp2p/sdk
 
 [![npm version](https://img.shields.io/npm/v/@zkp2p/sdk.svg)](https://www.npmjs.com/package/@zkp2p/sdk)
+[![npm types](https://img.shields.io/npm/types/@zkp2p/sdk.svg)](https://www.npmjs.com/package/@zkp2p/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-TypeScript SDK for ZKP2P liquidity providers and integrators.
+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.
 
-Current version: `0.1.0-rc.14`. Includes V1/V2 contract routing, referral-fee intent signaling, signed oracle spreads, EscrowV2 batch currency-config updates, Pyth oracle feeds, on-chain oracle feed validation, and indexer helpers.
+Current version: `0.1.0`
+
+## Why This SDK
+
+- Build maker, taker, vault, and embedded ramp flows from one client.
+- Read live protocol state directly from ProtocolViewer instead of waiting on indexer sync.
+- Route against the upgraded escrow/orchestrator stack while preserving historical deposit visibility.
+- Use prepareable write methods for smart accounts, relayers, gas estimation, and batching.
+- Keep advanced analytics, fund activity history, and vault stats behind `client.indexer.*`.
 
 ## Who This Is For
 
-- maker/liquidity-provider applications
-- internal client apps (web, extension)
-- tools that need contract-safe deposit/intent operations
-- dashboard/reporting services that query `client.indexer.*`
+- maker and liquidity-provider applications
+- wallets and embedded onramp/offramp products
+- backends that need contract-safe deposit and intent operations
+- dashboards and analytics services that query `client.indexer.*`
+- React apps that want first-party hooks instead of writing transaction glue
 
-## Core Capabilities
+## Architecture
 
-| Area              | Highlights                                                                                                                                |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Deposit lifecycle | `createDeposit`, `addFunds`, `removeFunds`, `withdrawDeposit`                                                                             |
-| Intent lifecycle  | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`                                                                    |
-| Vault/DRM         | `createRateManager`, `setRateManager`, `clearRateManager`, `setVaultFee`, `setVaultMinRate`, `setVaultMinRatesBatch`, `setVaultConfig`    |
-| Oracle config     | `setOracleRateConfig`, `setOracleRateConfigBatch`, `updateCurrencyConfigBatch`, `deactivateCurrenciesBatch`, `validateOracleFeedsOnChain` |
-| RPC-first reads   | `getDeposits`, `getDeposit`, `getIntents`, `getIntent`                                                                                    |
-| Indexer services  | `client.indexer.*`, `IndexerRateManagerService`, `getIntentFulfillmentAmounts`                                                            |
-| React hooks       | `@zkp2p/sdk/react` hooks for deposit/intent/vault operations                                                                              |
+- 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.
+- Current-stack routing: the client resolves against the upgraded escrow and orchestrator contracts by default, while keeping historical escrow lookups available for reads and legacy deposits.
+- Modular internals: stable `0.1.0` extracted intent, vault, and ProtocolViewer logic into `IntentOperations`, `VaultOperations`, and `ProtocolViewerReader`, keeping `Zkp2pClient` 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
 
@@ -33,7 +39,13 @@ npm install @zkp2p/sdk viem
 # or
 pnpm add @zkp2p/sdk viem
 # or
-yarn add @zkp2p/sdk viem
+bun add @zkp2p/sdk viem
+```
+
+If you use React hooks, add React as well:
+
+```bash
+pnpm add react
 ```
 
 ## Quick Start
@@ -51,213 +63,461 @@ const walletClient = createWalletClient({
 const client = new Zkp2pClient({
   walletClient,
   chainId: base.id,
-  runtimeEnv: 'staging', // 'production' | 'staging'
-  indexerApiKey: 'YOUR_INDEXER_API_KEY',
 });
 ```
 
-## Routing Defaults
-
-- SDK methods are capability-based and do not enforce product rollout flags.
-- SDK defaults to V2 routing when V2 contracts are deployed, with legacy fallback when not.
-- Apply phase/rollout gating in app layers above the SDK (web/extension/backend).
+`runtimeEnv` defaults to `'production'`. Use `'preproduction'` or `'staging'` when you want to point the SDK at those deployments.
 
-## Authentication
+## Environment and Authentication
 
-- `apiKey` is optional and is forwarded to curator API endpoints when provided.
-- `authorizationToken` and `getAuthorizationToken` support optional bearer auth.
-- `indexerApiKey` adds `x-api-key` for indexer proxy auth.
+- Supported runtime environments: `'production'`, `'preproduction'`, `'staging'`
+- `runtimeEnv` default: `'production'`
+- `apiKey`: optional curator API key for authenticated service endpoints
+- `authorizationToken` / `getAuthorizationToken`: optional bearer auth for hybrid client and indexer flows
+- `indexerApiKey`: optional `x-api-key` for indexer proxy auth
+- `indexerUrl` and `baseApiUrl`: override defaults when you are targeting custom deployments
 
-If you provide both bearer and indexer API key, both headers are sent.
+Indexer defaults by environment:
 
-## Indexer Defaults
+- `production`: `https://indexer.zkp2p.xyz/v1/graphql`
+- `preproduction`: `https://indexer-preprod.zkp2p.xyz/v1/graphql`
+- `staging`: `https://indexer-staging.zkp2p.xyz/v1/graphql`
 
-- Production: `https://indexer.zkp2p.xyz/v1/graphql`
-- Preproduction: `https://indexer-preprod.zkp2p.xyz/v1/graphql`
-- Staging: `https://indexer-staging.zkp2p.xyz/v1/graphql`
-
-## Common Operations
+## Core Capabilities
 
-### Create a Deposit
+| Area                           | Stable surface                                                                                                                                                                                                                           |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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`                                                                                                                                         |
+| 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`, `getTakerTier`                                                                                                                                                                   |
+| Delegation and hooks           | `setDelegate`, `removeDelegate`, `setRateManager`, `clearRateManager`, `setDepositRateManager`, `clearDepositRateManager`, `setDepositPreIntentHook`, `setDepositWhitelistHook`                                                          |
+| Vault / DRM                    | `createRateManager`, `setVaultMinRate`, `setVaultMinRatesBatch`, `setVaultFee`, `setVaultConfig`, `getDepositRateManager`, `getManagerFee`, `getEffectiveRate`                                                                           |
+| 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`, `getIntentFulfillmentAmounts`, `getDepositFundActivities`, `getDepositDailySnapshots`, `getRateManagers`, `getRateManagerDetail`, `getManagerDailySnapshots` |
+| 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                                                                                                                      |
+
+## Create a Deposit
 
 ```ts
 import { Currency } from '@zkp2p/sdk';
 
-await client.createDeposit({
-  token: '0xUSDC_ADDRESS',
+const result = await client.createDeposit({
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
   amount: 10_000_000n,
   intentAmountRange: { min: 100_000n, max: 5_000_000n },
   processorNames: ['wise'],
   depositData: [{ email: 'maker@example.com' }],
   conversionRates: [[{ currency: Currency.USD, conversionRate: '1020000000000000000' }]],
 });
+
+console.log(result.hash);
+console.log(result.depositDetails);
 ```
 
-### Configure Oracle Spread (EscrowV2)
+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, Quotes, and Taker Tier
 
 ```ts
-await client.setOracleRateConfig({
-  depositId: 42n,
-  paymentMethodHash: '0x...',
-  currencyHash: '0x...',
-  config: {
-    adapter: '0x...',
-    adapterConfig: '0x',
-    spreadBps: -50, // signed int16 bps: -0.50% below market
-    maxStaleness: 180,
-  },
+import { resolvePaymentMethodHash } from '@zkp2p/sdk';
+
+const { hashedOnchainIds } = await client.registerPayeeDetails({
+  processorNames: ['wise'],
+  depositData: [{ email: 'maker@example.com' }],
 });
-```
 
-### Validate Oracle Feed Availability
+const quote = await client.getQuote({
+  paymentPlatforms: ['wise'],
+  fiatCurrency: 'USD',
+  user: '0xBuyer',
+  recipient: '0xBuyer',
+  destinationChainId: 8453,
+  destinationToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  amount: '250',
+  isExactFiat: true,
+});
 
-```ts
-import { validateOracleFeedsOnChain } from '@zkp2p/sdk';
+const takerTier = await client.getTakerTier({
+  owner: '0xBuyer',
+  chainId: 8453,
+});
 
-// Validate all Chainlink + Pyth feeds on Base via multicall
-const availableCurrencies = await validateOracleFeedsOnChain(publicClient);
-// Set<CurrencyType> — only currencies whose feeds responded successfully
+const payeeHash = await client.resolvePayeeHash(
+  42n,
+  resolvePaymentMethodHash('wise', { env: 'production' }),
+);
 ```
 
-### Signal an Intent with Referral Fees
+`getQuote()` returns available liquidity plus payee details when authenticated. `getTakerTier()` returns limits and cooldown data for taker UX.
+
+## Signal, Fulfill, and Release Intents
 
 ```ts
-await client.signalIntent({
+const intentHash = await client.signalIntent({
   depositId: 42n,
   amount: 250_000n,
-  to: '0xBuyer',
-  paymentMethod: 'wise',
+  toAddress: '0xBuyer',
+  processorName: 'wise',
+  payeeDetails: '0xPAYEE_DETAILS_HASH',
   fiatCurrencyCode: 'USD',
-  conversionRate: '1020000000000000000',
+  conversionRate: 1_020_000_000_000_000_000n,
   referralFees: [
     { recipient: '0xPlatformFeeRecipient', fee: 2_500n },
     { recipient: '0xPartnerFeeRecipient', fee: 1_250n },
   ],
 });
+
+await client.fulfillIntent({
+  intentHash,
+  proof: zkTlsProofJson,
+});
+
+await client.releaseFundsToPayer({
+  intentHash,
+});
 ```
 
-Legacy `referrer` / `referrerFee` fields are still accepted as a backwards-compatible fallback, but new integrations should send `referralFees[]`.
+For OrchestratorV2 flows, prefer `referralFees[]`. Legacy `referrer` and `referrerFee` fields remain available for compatibility.
+
+## Prepared Transactions
 
-### Vault / DRM Operations
+Most write methods expose `.prepare(params)` and return a `PreparedTransaction` without sending the transaction. `createDeposit()` is the main exception and uses `client.prepareCreateDeposit(params)`, which returns `{ depositDetails, prepared }`. This is the stable pattern for smart accounts, batched user-ops, relayers, gas estimation, and custom senders.
 
 ```ts
-// Create a vault (rate manager)
-await client.createRateManager({
+const prepared = await client.signalIntent.prepare({
+  depositId: 42n,
+  amount: 250_000n,
+  toAddress: '0xBuyer',
+  processorName: 'wise',
+  payeeDetails: '0xPAYEE_DETAILS_HASH',
+  fiatCurrencyCode: 'USD',
+  conversionRate: 1_020_000_000_000_000_000n,
+});
+
+console.log(prepared);
+// { to, data, value, chainId }
+```
+
+React hooks mirror this where useful. For example, `useSignalIntent()` returns `prepareSignalIntent()` and `prepared`.
+
+## Error Handling
+
+The SDK exports a normalized error model:
+
+- `ZKP2PError`
+- `ValidationError`
+- `NetworkError`
+- `APIError`
+- `ContractError`
+- `ErrorCode`
+
+```ts
+import { APIError, ErrorCode, ValidationError, ZKP2PError } from '@zkp2p/sdk';
+
+try {
+  await client.createDeposit({
+    token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    amount: 10_000_000n,
+    intentAmountRange: { min: 100_000n, max: 5_000_000n },
+    processorNames: ['wise'],
+    depositData: [{ email: 'maker@example.com' }],
+    conversionRates: [[{ currency: 'USD', conversionRate: '1020000000000000000' }]],
+  });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Invalid field:', error.field, error.message);
+  } else if (error instanceof APIError) {
+    console.error('HTTP status:', error.status, error.message);
+  } else if (error instanceof ZKP2PError) {
+    console.error('SDK error:', error.code ?? ErrorCode.UNKNOWN, error.details);
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+You should still handle generic `Error` for lower-level transport or wallet failures that originate outside the normalized SDK wrappers.
+
+## Oracle Configuration
+
+The SDK exports Chainlink and Pyth adapter helpers, plus a Chainlink-first `getSpreadOracleConfig()` resolver for bundled feed metadata.
+
+```ts
+import {
+  getSpreadOracleConfig,
+  resolveFiatCurrencyBytes32,
+  resolvePaymentMethodHash,
+  validateOracleFeedsOnChain,
+} from '@zkp2p/sdk';
+
+const paymentMethodHash = resolvePaymentMethodHash('wise', { env: 'production' });
+const currencyHash = resolveFiatCurrencyBytes32('USD');
+const oracle = getSpreadOracleConfig('USD');
+
+if (!oracle) throw new Error('No bundled oracle config for USD');
+
+await client.setOracleRateConfig({
+  depositId: 42n,
+  paymentMethodHash,
+  currencyHash,
+  config: {
+    adapter: oracle.adapter,
+    adapterConfig: oracle.adapterConfig,
+    spreadBps: -50,
+    maxStaleness: oracle.maxStaleness,
+  },
+});
+
+await client.updateCurrencyConfigBatch({
+  depositId: 42n,
+  paymentMethods: [paymentMethodHash],
+  updates: [
+    [
+      {
+        code: currencyHash,
+        minConversionRate: 1_020_000_000_000_000_000n,
+        updateOracle: true,
+        oracleRateConfig: {
+          adapter: oracle.adapter,
+          adapterConfig: oracle.adapterConfig,
+          spreadBps: -50,
+          maxStaleness: oracle.maxStaleness,
+        },
+      },
+    ],
+  ],
+});
+
+const availableFeeds = await validateOracleFeedsOnChain(client.publicClient);
+console.log([...availableFeeds].sort());
+```
+
+Useful helpers and methods in this area:
+
+- `CHAINLINK_ORACLE_ADAPTER`
+- `PYTH_ORACLE_ADAPTER`
+- `encodeSpreadOracleAdapterConfig`
+- `encodePythAdapterConfig`
+- `getSpreadOracleConfig`
+- `setOracleRateConfigBatch`
+- `updateCurrencyConfigBatch`
+- `deactivateCurrenciesBatch`
+
+## Delegation and Hooks
+
+```ts
+await client.setDelegate({
+  depositId: 42n,
+  delegate: '0xDelegate',
+});
+
+await client.setRateManager({
+  depositId: 42n,
+  rateManagerAddress: '0xVaultAddress',
+  rateManagerId: '0xVaultId',
+});
+
+await client.setDepositPreIntentHook({
+  depositId: 42n,
+  preIntentHook: '0xHookAddress',
+});
+
+await client.setDepositWhitelistHook({
+  depositId: 42n,
+  whitelistHook: '0xHookAddress',
+});
+```
+
+Use `removeDelegate()` and `clearRateManager()` to unwind delegation. Phase-4 hook methods are available when the target deployment supports them.
+
+## Vault / DRM
+
+```ts
+const createHash = await client.createRateManager({
   config: {
     manager: '0xManager',
     feeRecipient: '0xFeeRecipient',
     maxFee: 50_000_000_000_000_000n,
     fee: 10_000_000_000_000_000n,
     name: 'My Vault',
-    uri: 'ipfs://...',
+    uri: 'ipfs://vault-metadata',
   },
 });
 
-// Delegate a deposit to a vault
-await client.setRateManager({
-  depositId: 42n,
-  rateManagerAddress: '0xVaultAddress',
+await client.setVaultFee({
+  rateManagerId: '0xVaultId',
+  newFee: 20_000_000_000_000_000n,
+});
+
+await client.setVaultMinRate({
   rateManagerId: '0xVaultId',
+  paymentMethodHash: resolvePaymentMethodHash('wise', { env: 'production' }),
+  currencyHash: resolveFiatCurrencyBytes32('USD'),
+  rate: 1_010_000_000_000_000_000n,
 });
 
-// Update vault fee and config
-await client.setVaultFee({ rateManagerId: '0xVaultId', newFee: 20_000_000_000_000_000n });
 await client.setVaultConfig({
   rateManagerId: '0xVaultId',
   newManager: '0xNewManager',
   newFeeRecipient: '0xNewFeeRecipient',
   newName: 'Updated Vault',
-  newUri: 'ipfs://updated',
+  newUri: 'ipfs://updated-vault-metadata',
 });
 ```
 
-### Query Indexer Data
+## Protocol Viewer (RPC) Reads
+
+ProtocolViewer methods bypass indexer lag and are the right default for primary user-facing reads.
+
+```ts
+const deposit = await client.getPvDepositById(42n);
+const deposits = await client.getPvDepositsFromIds([42n, 43n]);
+const makerDeposits = await client.getPvAccountDeposits('0xMaker');
+const takerIntents = await client.getPvAccountIntents('0xTaker');
+const intent = await client.getPvIntent('0xIntentHash');
+```
+
+You can also use the convenience wrappers `getDeposits()`, `getDeposit()`, `getIntents()`, and `getIntent()` for common flows.
+
+## Indexer Queries
+
+Use the indexer for filtered queries, pagination, fund activity history, snapshots, and vault analytics.
 
 ```ts
 const deposits = await client.indexer.getDeposits(
-  { status: 'ACTIVE', depositor: '0xYourAddress' },
-  { limit: 25 },
+  { status: 'ACTIVE', depositor: '0xMaker' },
+  { limit: 25, orderBy: 'updatedAt', orderDirection: 'desc' },
 );
 
-const amounts = await client.indexer.getIntentFulfillmentAmounts('0xIntentHash');
-// amounts?.releasedAmount, amounts?.takerAmountNetFees
+const depositWithRelations = await client.indexer.getDepositById('8453_0xEscrowAddress_42', {
+  includeIntents: true,
+});
+
+const fulfillment = await client.indexer.getIntentFulfillmentAmounts('0xIntentHash');
+const fundActivities = await client.indexer.getDepositFundActivities('8453_0xEscrowAddress_42');
+const snapshots = await client.indexer.getDepositDailySnapshots('8453_0xEscrowAddress_42', 30);
+
+const managers = await client.indexer.getRateManagers({
+  limit: 10,
+  orderBy: 'currentDelegatedBalance',
+  orderDirection: 'desc',
+});
+
+const managerDetail = await client.indexer.getRateManagerDetail('0xVaultId', {
+  rateManagerAddress: '0xVaultAddress',
+});
 ```
 
+`managerDetail?.aggregate` gives you current delegated balance and filled volume stats alongside recent snapshots and delegation history.
+
 ## React Hooks
 
+Install React and import hooks from `@zkp2p/sdk/react`. React is an optional peer dependency of the SDK.
+
+Most mutation hooks return a named action plus status fields such as `isLoading`, `error`, and `txHash`. Hooks with prepare support expose dedicated `prepare...` helpers, and some of them also store the latest `prepared` transaction in hook state. Every hook exports a matching `Use*Options` type.
+
 ```tsx
 import {
-  // Deposit lifecycle
   useCreateDeposit,
-  useAddFunds,
-  useRemoveFunds,
-  useWithdrawDeposit,
-  useSetAcceptingIntents,
-  useSetIntentRange,
-  useSetCurrencyMinRate,
-  useSetRetainOnEmpty,
-
-  // Payment method management
-  useAddPaymentMethods,
-  useRemovePaymentMethod,
-  useSetPaymentMethodActive,
-  useAddCurrencies,
-  useRemoveCurrency,
-  useDeactivateCurrency,
-
-  // Intent lifecycle
   useSignalIntent,
-  useFulfillIntent,
-  useReleaseFundsToPayer,
-  usePruneExpiredIntents,
-
-  // Delegation
-  useSetDelegate,
-  useRemoveDelegate,
-
-  // Vault / DRM
   useCreateVault,
   useVaultDelegation,
-  useSetVaultFee,
-  useSetVaultMinRate,
-  useSetVaultConfig,
-
-  // Taker tier
   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:
+
+- Deposit lifecycle: `useCreateDeposit`, `useAddFunds`, `useRemoveFunds`, `useWithdrawDeposit`, `useSetAcceptingIntents`, `useSetIntentRange`, `useSetCurrencyMinRate`, `useSetRetainOnEmpty`
+- Payment and currency management: `useAddPaymentMethods`, `useRemovePaymentMethod`, `useSetPaymentMethodActive`, `useAddCurrencies`, `useRemoveCurrency`, `useDeactivateCurrency`
+- Intent lifecycle: `useSignalIntent`, `useFulfillIntent`, `useReleaseFundsToPayer`, `usePruneExpiredIntents`
+- Delegation: `useSetDelegate`, `useRemoveDelegate`
+- Vault / DRM: `useCreateVault`, `useVaultDelegation`, `useSetVaultFee`, `useSetVaultMinRate`, `useSetVaultConfig`
+- Taker tier: `useGetTakerTier`, plus `getTierDisplayInfo()` and `getNextTierCap()` helpers
+
+`useVaultDelegation()` is the batching-oriented hook. It returns `delegateDeposit`, `delegateDeposits`, `clearDelegation`, and `clearDelegations`.
+
 ## Contracts and Catalog Helpers
 
 ```ts
 import {
   getContracts,
-  getRateManagerContracts,
   getPaymentMethodsCatalog,
+  getRateManagerContracts,
   resolveFiatCurrencyBytes32,
   resolvePaymentMethodHash,
 } from '@zkp2p/sdk';
 
-const { addresses } = getContracts(8453, 'staging');
-const rateManager = getRateManagerContracts(8453, 'staging');
-const catalog = getPaymentMethodsCatalog(8453, 'staging');
+const contracts = getContracts(8453, 'production');
+const rateManagerContracts = getRateManagerContracts(8453, 'production');
+const paymentMethods = getPaymentMethodsCatalog(8453, 'production');
+const usdHash = resolveFiatCurrencyBytes32('USD');
+const wiseHash = resolvePaymentMethodHash('wise', { env: 'production' });
 ```
 
+## Supported Currencies
+
+The SDK ships currency metadata for 34 fiat currencies:
+
+`AED`, `ARS`, `AUD`, `BRL`, `CAD`, `CHF`, `CNY`, `CZK`, `DKK`, `EUR`, `GBP`, `HKD`, `HUF`, `IDR`, `ILS`, `INR`, `JPY`, `KES`, `MXN`, `MYR`, `NOK`, `NZD`, `PHP`, `PLN`, `RON`, `SAR`, `SEK`, `SGD`, `THB`, `TRY`, `UGX`, `USD`, `VND`, `ZAR`
+
 ## Supported Payment Platforms
 
 `wise`, `venmo`, `revolut`, `cashapp`, `mercadopago`, `zelle`, `paypal`, `monzo`, `chime`, `luxon`, `n26`
 
-## Extension SDK Helpers
+## Attribution (ERC-8021)
+
+The SDK includes builder-code attribution helpers and transaction overrides for partner attribution:
+
+```ts
+const hash = await client.signalIntent({
+  depositId: 42n,
+  amount: 250_000n,
+  toAddress: '0xBuyer',
+  processorName: 'wise',
+  payeeDetails: '0xPAYEE_DETAILS_HASH',
+  fiatCurrencyCode: 'USD',
+  conversionRate: 1_020_000_000_000_000_000n,
+  txOverrides: {
+    referrer: ['my-app', 'campaign-42'],
+  },
+});
+```
+
+Lower-level helpers are also exported: `BASE_BUILDER_CODE`, `getAttributionDataSuffix()`, `appendAttributionToCalldata()`, `encodeWithAttribution()`, and `sendTransactionWithAttribution()`.
+
+## TypeDoc API Reference
 
-If you integrate with the Peer extension:
+The package already includes TypeDoc configuration. Generate the full API reference locally with:
+
+```bash
+pnpm --filter @zkp2p/sdk docs
+```
+
+This writes documentation to [`packages/sdk/docs`](./docs) and now includes the React entry point as well as the main SDK and extension surfaces.
+
+## Debug Logging
+
+Use `setLogLevel()` when you want verbose SDK logging during local development or integration debugging.
 
 ```ts
-import { peerExtensionSdk } from '@zkp2p/sdk';
+import { setLogLevel } from '@zkp2p/sdk';
 
-const state = await peerExtensionSdk.getState();
-if (state === 'needs_install') peerExtensionSdk.openInstallPage();
+setLogLevel('debug');
 ```
 
+Supported log levels: `'error'`, `'info'`, `'debug'`
+
 ## Development
 
 ```bash
@@ -266,10 +526,12 @@ pnpm build
 pnpm test
 pnpm typecheck
 pnpm lint
+pnpm docs
 ```
 
 ## Links
 
 - NPM: https://www.npmjs.com/package/@zkp2p/sdk
-- Monorepo: https://github.com/zkp2p/zkp2p-clients
 - Docs: https://docs.zkp2p.xyz
+- Monorepo: https://github.com/zkp2p/zkp2p-clients
+- TypeDoc output: [`packages/sdk/docs`](./docs)