@zkp2p/sdk 0.4.3 → 0.5.0

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.4.3`
 
 ## 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;
+  }
+
+  console.log('captured payment metadata', message.metadata);
+});
+
+peer.authenticate({
+  actionType: 'transfer_venmo',
+  captureMode: 'buyerTee',
+  platform: 'venmo',
+  attestationServiceUrl: 'https://attestation.zkp2p.xyz',
+});
+```
 
-See [Extension Onramp Deeplinks](../../docs/extension-onramp-deeplinks.md) for the full parameter contract, exact-deposit semantics, and prepared calldata recovery behavior.
+`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
 
@@ -502,6 +511,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);

package/dist/index.cjs

@@ -43349,6 +43349,7 @@ var IntentOperations = class {
         paymentProof,
         data: encodeAddressAsBytes(attestation.responseObject.signer)
       });
+      params.callbacks?.onAttestationComplete?.(attestation);
     }
     const args = [
       {
@@ -45315,6 +45316,7 @@ var INTENT_FULFILLMENTS_QUERY = (
   query GetFulfilledIntents($intentHashes: [String!]) {
     Orchestrator_V21_IntentFulfilled(where: { intentHash: { _in: $intentHashes } }) {
       intentHash
+      amount
       isManualRelease
       fundsTransferredTo
     }
@@ -47357,6 +47359,58 @@ async function apiGetDepositBundle(params, optsOrBaseApiUrl, timeoutMs, apiKey)
   return response.responseObject;
 }
 
+// src/sellerCredentials.ts
+function normalizeBaseApiUrl(value) {
+  return (value?.trim().replace(/\/+$/u, "") || DEFAULT_BASE_API_URL).replace(/\/v1$/u, "");
+}
+function assertBundlePlatformMatches(params) {
+  if (params.bundle.platform.toLowerCase() !== params.platform) {
+    throw new Error("Seller credential bundle platform does not match upload platform");
+  }
+}
+async function apiUploadSellerCredentialBundle(params, baseApiUrl, timeoutMs) {
+  assertBundlePlatformMatches(params);
+  const normalizedBaseApiUrl = normalizeBaseApiUrl(baseApiUrl);
+  if (params.platform === "wise") {
+    return apiUploadSellerCredential(
+      params.platform,
+      params.bundle.payeeIdHash,
+      params.bundle,
+      normalizedBaseApiUrl,
+      timeoutMs
+    );
+  }
+  const registeredPayeePayload = {
+    offchainId: params.offchainId,
+    processorName: params.platform
+  };
+  if (params.telegramUsername !== void 0) {
+    registeredPayeePayload.telegramUsername = params.telegramUsername;
+  }
+  if (params.metadata !== void 0) {
+    registeredPayeePayload.metadata = params.metadata;
+  }
+  const registeredPayeeResponse = await apiPostDepositDetails(
+    registeredPayeePayload,
+    normalizedBaseApiUrl,
+    timeoutMs
+  );
+  if (!registeredPayeeResponse.success || !registeredPayeeResponse.responseObject) {
+    throw new Error(registeredPayeeResponse.message || "Failed to register seller payee details");
+  }
+  const registeredPayee = registeredPayeeResponse.responseObject;
+  if (registeredPayee.hashedOnchainId.toLowerCase() !== params.bundle.payeeIdHash.toLowerCase()) {
+    throw new Error("Seller credential payee hash does not match registered payee details");
+  }
+  return apiUploadSellerCredential(
+    params.platform,
+    registeredPayee.hashedOnchainId,
+    params.bundle,
+    normalizedBaseApiUrl,
+    timeoutMs
+  );
+}
+
 // src/client/Zkp2pClient.ts
 init_contracts();
 init_paymentResolution();
@@ -49248,7 +49302,9 @@ var Zkp2pClient = class {
    *   { limit: 50, orderBy: 'remainingDeposits', orderDirection: 'desc' }
    * );
    *
-   * // Get historical fulfillment data
+   * // Get historical fulfillment event data. Use `amount` for net USDC
+   * // transferred to the taker; use getIntentFulfillmentAmounts() when you
+   * // also need gross released USDC.
    * const fulfillments = await client.indexer.getFulfilledIntentEvents(['0x...']);
    * ```
    */
@@ -49310,13 +49366,15 @@ var Zkp2pClient = class {
         return service.fetchExpiredIntents(params);
       },
       /**
-       * Fetches fulfillment events for completed intents.
+       * Fetches fulfillment events for completed intents. `amount` is the net
+       * USDC transferred to the taker after protocol/referrer fees.
        */
       getFulfilledIntentEvents: (intentHashes) => {
         return service.fetchFulfilledIntentEvents(intentHashes);
       },
       /**
-       * Fetches gross and net fulfillment amounts for an intent.
+       * Fetches gross and net fulfillment amounts for an intent. Use
+       * `takerAmountNetFees` as the buyer/taker received USDC amount.
        */
       getIntentFulfillmentAmounts: (intentHash) => {
         return service.fetchIntentFulfillmentAmounts(intentHash);
@@ -49934,14 +49992,14 @@ var Zkp2pClient = class {
     const attestationServiceUrl = this.stripTrailingSlash(
       opts?.attestationServiceUrl ?? this.defaultAttestationServiceForBaseApiUrl(baseApiUrl)
     );
-    const createBundle = (uploadPayload2) => opts?.attestationRuntime ? apiCreateSellerCredentialBundle(
-      uploadPayload2,
+    const createBundle = (uploadPayload) => opts?.attestationRuntime ? apiCreateSellerCredentialBundle(
+      uploadPayload,
       attestationServiceUrl,
       params.platform,
       timeoutMs,
       opts.attestationRuntime
     ) : apiCreateSellerCredentialBundle(
-      uploadPayload2,
+      uploadPayload,
       attestationServiceUrl,
       params.platform,
       timeoutMs
@@ -49953,51 +50011,42 @@ var Zkp2pClient = class {
       if (!bundleResponse2.success || !bundleResponse2.responseObject) {
         throw new Error(bundleResponse2.message || "Failed to create seller credential bundle");
       }
-      return apiUploadSellerCredential(
-        params.platform,
-        bundleResponse2.responseObject.payeeIdHash,
-        bundleResponse2.responseObject,
-        baseApiUrl,
-        timeoutMs
+      return this.uploadSellerCredentialBundle(
+        {
+          bundle: bundleResponse2.responseObject,
+          platform: params.platform
+        },
+        { baseApiUrl, timeoutMs }
       );
     }
-    const registeredPayeePayload = {
-      offchainId: params.offchainId,
-      processorName: params.platform
-    };
-    if (params.telegramUsername !== void 0) {
-      registeredPayeePayload.telegramUsername = params.telegramUsername;
-    }
-    if (params.metadata !== void 0) {
-      registeredPayeePayload.metadata = params.metadata;
-    }
-    const registeredPayeeResponse = await apiPostDepositDetails(
-      registeredPayeePayload,
-      baseApiUrl,
-      timeoutMs
-    );
-    if (!registeredPayeeResponse.success || !registeredPayeeResponse.responseObject) {
-      throw new Error(registeredPayeeResponse.message || "Failed to register seller payee details");
-    }
-    const uploadPayload = {
+    const bundlePayload = {
       payeeId: params.payeeId,
       sessionMaterial: params.sessionMaterial
     };
-    const bundleResponse = await createBundle(uploadPayload);
+    const bundleResponse = await createBundle(bundlePayload);
     if (!bundleResponse.success || !bundleResponse.responseObject) {
       throw new Error(bundleResponse.message || "Failed to create seller credential bundle");
     }
-    const registeredPayee = registeredPayeeResponse.responseObject;
-    if (registeredPayee.hashedOnchainId.toLowerCase() !== bundleResponse.responseObject.payeeIdHash.toLowerCase()) {
-      throw new Error("Seller credential payee hash does not match registered payee details");
-    }
-    return apiUploadSellerCredential(
-      params.platform,
-      registeredPayee.hashedOnchainId,
-      bundleResponse.responseObject,
-      baseApiUrl,
-      timeoutMs
+    return this.uploadSellerCredentialBundle(
+      {
+        bundle: bundleResponse.responseObject,
+        offchainId: params.offchainId,
+        platform: params.platform,
+        ...params.telegramUsername !== void 0 ? { telegramUsername: params.telegramUsername } : {},
+        ...params.metadata !== void 0 ? { metadata: params.metadata } : {}
+      },
+      { baseApiUrl, timeoutMs }
+    );
+  }
+  /**
+   * Store an already-encrypted seller credential bundle with curator.
+   */
+  async uploadSellerCredentialBundle(params, opts) {
+    const baseApiUrl = this.stripTrailingSlash(
+      opts?.baseApiUrl ?? this.baseApiUrl ?? DEFAULT_BASE_API_URL
     );
+    const timeoutMs = opts?.timeoutMs ?? this.apiTimeoutMs;
+    return apiUploadSellerCredentialBundle(params, baseApiUrl, timeoutMs);
   }
   /**
    * Confirms the PayPal Gmail-forwarding setup for an existing maker payee hash.
@@ -50296,189 +50345,13 @@ var getPeerExtensionState = async (options) => {
     return "needs_connection";
   }
 };
-var fiatAmountRegex = /^-?\d*(\.\d{0,6})?$/;
-var usdcAmountRegex = /^\d+$/;
-var assertObjectInput = (params) => {
-  if (params === void 0) {
-    throw new Error("Peer extension onramp requires query params with intentHash.");
-  }
-  if (params === null || typeof params !== "object" || Array.isArray(params)) {
-    throw new Error("Peer extension onramp expects an object of query params.");
-  }
-  return params;
-};
-var normalizeOptionalString2 = (value, label) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`Peer extension onramp ${label} must be a non-empty string.`);
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new Error(`Peer extension onramp ${label} must be a non-empty string.`);
-  }
-  return trimmed;
-};
-var normalizeOptionalUrl = (value, label) => {
-  const trimmed = normalizeOptionalString2(value, label);
-  if (trimmed === void 0) {
-    return void 0;
-  }
-  let parsed;
-  try {
-    parsed = new URL(trimmed);
-  } catch (error) {
-    throw new Error(`Peer extension onramp ${label} must be a valid URL.`);
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`Peer extension onramp ${label} must use http or https.`);
-  }
-  return trimmed;
-};
-var normalizeFiatAmount = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  const normalized = typeof value === "number" ? String(value) : value;
-  if (typeof normalized !== "string") {
-    throw new Error("Peer extension onramp inputAmount must be a string or number.");
-  }
-  const trimmed = normalized.trim();
-  if (!trimmed) {
-    throw new Error("Peer extension onramp inputAmount must be a non-empty value.");
-  }
-  if (!fiatAmountRegex.test(trimmed)) {
-    throw new Error(
-      "Peer extension onramp inputAmount must be a non-negative number with up to 6 decimals."
-    );
-  }
-  if (Number.isNaN(Number(trimmed)) || Number(trimmed) < 0) {
-    throw new Error(
-      "Peer extension onramp inputAmount must be a non-negative number with up to 6 decimals."
-    );
-  }
-  return trimmed;
-};
-var normalizeUsdcAmount = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value === "bigint") {
-    if (value < 0n) {
-      throw new Error("Peer extension onramp amountUsdc must be a non-negative integer.");
-    }
-    return value.toString();
-  }
-  if (typeof value === "number") {
-    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
-      throw new Error("Peer extension onramp amountUsdc must be a non-negative integer.");
-    }
-    return String(value);
-  }
-  if (typeof value !== "string") {
-    throw new Error("Peer extension onramp amountUsdc must be a string, number, or bigint.");
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new Error("Peer extension onramp amountUsdc must be a non-empty value.");
-  }
-  if (!usdcAmountRegex.test(trimmed)) {
-    throw new Error("Peer extension onramp amountUsdc must be a non-negative integer.");
-  }
-  return trimmed;
-};
-var normalizeIntegerParam = (value, label) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value === "bigint") {
-    if (value < 0n) {
-      throw new Error(`Peer extension onramp ${label} must be a non-negative integer.`);
-    }
-    return value.toString();
-  }
-  if (typeof value === "number") {
-    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
-      throw new Error(`Peer extension onramp ${label} must be a non-negative integer.`);
-    }
-    if (!Number.isSafeInteger(value)) {
-      throw new Error(
-        `Peer extension onramp ${label} number input must be a safe integer; pass a string or bigint for larger values.`
-      );
-    }
-    return String(value);
-  }
-  if (typeof value !== "string") {
-    throw new Error(`Peer extension onramp ${label} must be a string, number, or bigint.`);
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new Error(`Peer extension onramp ${label} must be a non-empty value.`);
-  }
-  if (!/^\d+$/.test(trimmed)) {
-    throw new Error(`Peer extension onramp ${label} must be a non-negative integer.`);
-  }
-  return trimmed;
-};
-var intentHashRegex = /^0x[a-fA-F0-9]{64}$/;
-var normalizeIntentHash = (value) => {
-  if (value === void 0) {
-    throw new Error("Peer extension onramp intentHash is required.");
-  }
-  if (typeof value !== "string") {
-    throw new Error("Peer extension onramp intentHash must be a string.");
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new Error("Peer extension onramp intentHash must be a non-empty string.");
-  }
-  if (!intentHashRegex.test(trimmed)) {
-    throw new Error(
-      "Peer extension onramp intentHash must be a valid bytes32 hex string (0x + 64 hex characters)."
-    );
-  }
-  return trimmed.toLowerCase();
-};
-var buildOnrampQueryString = (params) => {
-  const validated = assertObjectInput(params);
-  const searchParams = new URLSearchParams();
-  const setParam = (key, value) => {
-    if (value !== void 0) {
-      searchParams.set(key, value);
-    }
-  };
-  setParam("referrer", normalizeOptionalString2(validated.referrer, "referrer"));
-  setParam("referrerLogo", normalizeOptionalUrl(validated.referrerLogo, "referrerLogo"));
-  setParam("inputCurrency", normalizeOptionalString2(validated.inputCurrency, "inputCurrency"));
-  setParam("inputAmount", normalizeFiatAmount(validated.inputAmount));
-  setParam(
-    "paymentPlatform",
-    normalizeOptionalString2(validated.paymentPlatform, "paymentPlatform")
-  );
-  setParam("depositId", normalizeIntegerParam(validated.depositId, "depositId"));
-  setParam("toToken", normalizeOptionalString2(validated.toToken, "toToken"));
-  setParam("amountUsdc", normalizeUsdcAmount(validated.amountUsdc));
-  setParam(
-    "recipientAddress",
-    normalizeOptionalString2(validated.recipientAddress, "recipientAddress")
-  );
-  setParam("intentHash", normalizeIntentHash(validated.intentHash));
-  return searchParams.toString();
-};
 var createPeerExtensionSdk = (options = {}) => ({
   isAvailable: () => isPeerExtensionAvailable(options),
   requestConnection: () => requirePeer(options).requestConnection(),
   checkConnectionStatus: () => requirePeer(options).checkConnectionStatus(),
-  openSidebar: (route) => requirePeer(options).openSidebar(route),
-  onramp: (params, callback) => {
-    if (typeof callback !== "function") {
-      throw new Error("Peer extension onramp callback is required.");
-    }
-    requirePeer(options).onramp(buildOnrampQueryString(params), callback);
-  },
-  getOnrampTransaction: (intentHash) => requirePeer(options).getOnrampTransaction(normalizeIntentHash(intentHash)),
   getVersion: () => requirePeer(options).getVersion(),
+  authenticate: (params) => requirePeer(options).authenticate(params),
+  onMetadataMessage: (callback) => requirePeer(options).onMetadataMessage(callback),
   openInstallPage: () => openPeerExtensionInstallPage(options),
   getState: () => getPeerExtensionState(options)
 });
@@ -50592,6 +50465,7 @@ exports.apiGetTakerTier = apiGetTakerTier;
 exports.apiPostDepositDetails = apiPostDepositDetails;
 exports.apiRequestIdentityAttestation = apiRequestIdentityAttestation;
 exports.apiUploadGoogleOAuthSellerCredential = apiUploadGoogleOAuthSellerCredential;
+exports.apiUploadSellerCredentialBundle = apiUploadSellerCredentialBundle;
 exports.apiValidatePayeeDetails = apiValidatePayeeDetails;
 exports.appendAttributionToCalldata = appendAttributionToCalldata;
 exports.asciiToBytes32 = asciiToBytes32;