@zkp2p/sdk 0.4.3 → 0.5.2

package/README.md

@@ -6,7 +6,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.
 
-Current version: `0.3.3`
+Current version: `0.5.0`
 
 ## Why This SDK
 
@@ -105,50 +105,59 @@ Indexer defaults by environment:
 | 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 Onramp Deeplinks
+## Extension Metadata Bridge
 
-Use `createPeerExtensionSdk()` when a third-party page has signaled an intent and should hand payment authentication and proof generation into the Peer extension.
+Use `createPeerExtensionSdk()` when a page needs the Peer extension to open a
+provider auth tab and interact with the Peer TEE protocol. The extension owns
+provider-tab capture and Buyer TEE session encryption. For seller automated
+release, the extension captures seller session material, creates the encrypted
+attestation-service bundle, and returns only that bundle plus the maker
+`offchainId`. The page owns maker payee registration and curator credential
+storage.
 
 ```ts
 import { createPeerExtensionSdk } from '@zkp2p/sdk';
 
 const peer = createPeerExtensionSdk();
-const intentHash = await client.signalIntent({
-  // quote-selected intent params
-});
 
-const submitPreparedTransaction = async ({ transaction }) => {
-  await walletClient.sendTransaction({
-    to: transaction.to,
-    data: transaction.data,
-    value: BigInt(transaction.value),
-  });
-};
-
-const existing = await peer.getOnrampTransaction(intentHash);
-if (existing) {
-  await submitPreparedTransaction(existing);
-} else {
-  peer.onramp(
-    {
-      intentHash,
-      referrer: 'Liquidity Page',
-      inputCurrency: 'USD',
-      inputAmount: '500',
-      paymentPlatform: 'venmo',
-      depositId: '12345678901234567890',
-      amountUsdc: '488280000',
-      toToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-      recipientAddress: '0xRecipient',
-    },
-    submitPreparedTransaction,
-  );
+if ((await peer.getState()) === 'needs_connection') {
+  await peer.requestConnection();
 }
-```
 
-For exact-deposit handoffs, pass `depositId` as a string or bigint unless it is known to be a JavaScript-safe integer. The extension derives payment method hashes from `paymentPlatform`; do not pass escrow addresses, payment method hashes, or hashed on-chain ids through the onramp URL. `getOnrampTransaction(intentHash)` is the pull recovery path for prepared calldata when the callback message was missed.
+const unsubscribe = peer.onMetadataMessage((message) => {
+  if (message.sarCredentialCapture) {
+    console.log('SAR credential bundle captured', message.sarCredentialCapture.credentialBundle);
+    return;
+  }
 
-See [Extension Onramp Deeplinks](../../docs/extension-onramp-deeplinks.md) for the full parameter contract, exact-deposit semantics, and prepared calldata recovery behavior.
+  console.log('captured payment metadata', message.metadata);
+});
+
+peer.authenticate({
+  actionType: 'transfer_venmo',
+  captureMode: 'buyerTee',
+  platform: 'venmo',
+  attestationServiceUrl: 'https://attestation.zkp2p.xyz',
+});
+```
+
+`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
+`attestationServiceUrl`, and the extension returns encrypted session material.
+For SAR, pass `captureMode: "sellerCredential"` and optionally pass
+`attestationServiceUrl` only when overriding the extension's production
+attestation default. The extension returns `sarCredentialCapture.credentialBundle`
+plus `offchainId`. The page should call `apiUploadSellerCredentialBundle()` to
+register maker payee details with curator, compare the registered hash to the
+bundle `payeeIdHash`, and store the encrypted bundle with curator. Plaintext
+seller session material is never returned to the page.
+
+`Zkp2pClient.uploadSellerCredential()` remains the backwards-compatible
+plaintext convenience path for mobile and React Native callers. Internally it
+creates the encrypted bundle, then uses the same
+`apiUploadSellerCredentialBundle()` storage helper.
 
 ## Create a Deposit
 
@@ -247,7 +256,11 @@ const intentHash = await client.signalIntent({
 
 await client.fulfillIntent({
   intentHash,
-  proof: zkTlsProofJson,
+  proof: {
+    proofType: 'buyerTee',
+    encryptedSessionMaterial,
+    params: buyerTeePaymentParams,
+  },
 });
 
 await client.releaseFundsToPayer({
@@ -406,7 +419,7 @@ await client.setDepositWhitelistHook({
 });
 ```
 
-Use `removeDelegate()` and `clearRateManager()` to unwind delegation. Phase-4 hook methods are available when the target deployment supports them.
+Use `removeDelegate()` and `clearRateManager()` to unwind delegation. Hook methods are part of the current V2 surface; still validate target contract support before assuming a deployment exposes every hook.
 
 ## Vault / DRM
 
@@ -502,6 +515,11 @@ const fulfilledEvents = await client.indexer.getFulfilledIntentEvents(['0xIntent
 const fulfillment = await client.indexer.getIntentFulfillmentAmounts('0xIntentHash');
 const fulfillmentAndPayment = await client.indexer.getFulfillmentAndPayment('0xIntentHash');
 
+// 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.
+// - fulfillment.releasedAmount is gross USDC released from the deposit before fees.
+
 // Fund activity and snapshots
 const fundActivities = await client.indexer.getDepositFundActivities('8453_0xEscrowAddress_42');
 const makerActivities = await client.indexer.getMakerFundActivities('0xMaker', 50);