@usdctofiat/offramp 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Fixed
+
+- Replace the PayPal/Wise Peer extension recovery path with the headless
+  `authenticate` metadata bridge after upstream removed sidepanel proof flows in
+  `zkp2p-clients@3cfa50430b9c6a2a57c3c1c1100756702feded77`, including the
+  identity-attestation and maker-registration metadata step required before
+  retrying deposit creation.
+- Reject shortened or non-PayPal URLs in the PayPal.me username normalizer so
+  inputs like `t.co/...` cannot be converted into a fake PayPal username.
+
+### Changed
+
+- Bump `@zkp2p/sdk` to `0.4.1`.
+
+## [3.0.3] - 2026-05-20
+
+### Fixed
+
+- Return canonical OTC share links from `getOtcLink()` and `enableOtc()` using
+  `https://otc.usdctofiat.xyz/d/<escrow>/<depositId>`.
+
 ## [3.0.2] - 2026-05-19
 
 ### Fixed

package/README.md

@@ -37,6 +37,16 @@ const result = await offramp(walletClient, {
 // { depositId: "362", txHash: "0x...", resumed: false }
 ```
 
+## Fees
+
+Every deposit created with this SDK is delegated to the **Delegate vault**'s rate manager (the SDK always calls `setRateManager` to the vault — see [How It Works](#how-it-works)). That rate manager charges a **0.10% (10 bps) manager fee**:
+
+- **Who pays:** the buyer (taker). The fee is deducted from the USDC released to them at fill time — it is **not** added to your deposit cost and is **not** baked into the displayed rate.
+- **Where it goes:** the Delegate vault (Galleon Labs).
+- **Discover it in code:** `createOfframp({ walletClient }).getVaultStatus().feeRateBps` returns the current `feeRateBps` (`10`).
+
+The only other attribution the SDK attaches is the on-chain referrer tag `referrer: "galleonlabs"` (ERC-8021 builder attribution). That is **not a fee** — no separate referral/`referrerFee` is configured by this SDK. There is no SDK spread either: `getQuote()` returns `vaultSpreadBps: 0`.
+
 ## Deposit Management
 
 ```typescript
@@ -102,7 +112,7 @@ const { depositId, otcLink } = await offramp(walletClient, {
   identifier: "alice",
   otcTaker: "0xBuyerAddress",
 });
-// otcLink = "https://usdctofiat.xyz/deposit/0x.../362"
+// otcLink = "https://otc.usdctofiat.xyz/d/0x.../362"
 // Share otcLink with the buyer — they open it, connect their wallet, and fill the order.
 ```
 
@@ -118,7 +128,24 @@ getOtcLink("362"); // just the URL, no tx
 
 ## Resumable
 
-`offramp()` is idempotent. If an undelegated deposit exists for the wallet, it skips straight to delegation. Handles browser crashes, failed delegation, and retries automatically. Just call `offramp()` again.
+`offramp()` is idempotent on the **delegation step**. If an undelegated deposit exists for the wallet, it skips straight to delegation. Handles browser crashes, failed delegation, and retries automatically. Just call `offramp()` again.
+
+## Idempotency & server-side dedup
+
+`OfframpParams.idempotencyKey` is **browser-only**: the replay cache is backed by `sessionStorage`, so it is a **no-op in Node and workers** — a backend integrator who passes a key gets zero duplicate protection there. It is also honored only by the `Offramp` class (`createDeposit`) and the `useOfframp` hook; the standalone `offramp()` function ignores it entirely. When you pass a key in a runtime with no `sessionStorage`, the SDK emits a one-time `console.warn` so you find out at startup instead of via duplicate deposits.
+
+For server-side dedup, check for an existing open deposit before creating a new one (this is the same idea as the [resume behavior](#resumable) above):
+
+```typescript
+import { createOfframp, deposits } from "@usdctofiat/offramp";
+
+const existing = await deposits(walletAddress);
+const open = existing.find((d) => d.status === "active" && d.remainingUsdc > 0);
+
+const result = open
+  ? open // reuse it — don't create a duplicate
+  : await createOfframp({ walletClient }).createDeposit(params);
+```
 
 ## Error Handling
 
@@ -144,7 +171,8 @@ try {
 PayPal and Wise makers must register their handle inside the Peer (PeerAuth)
 browser extension before the first deposit. The SDK throws `OfframpError`
 with code `EXTENSION_REGISTRATION_REQUIRED` when curator rejects a maker for
-this reason. Drive the three-step handshake via the React hook:
+this reason. Drive install, connection approval, headless seller-credential capture,
+seller-credential upload, and retry via the React hook:
 
 ```tsx
 import { PLATFORMS, CURRENCIES, OFFRAMP_ERROR_CODES } from "@usdctofiat/offramp";
@@ -153,23 +181,18 @@ import { useOfframp, usePeerExtensionRegistration } from "@usdctofiat/offramp/re
 function PayPalSellButton({ walletClient }) {
   const { offramp, lastError } = useOfframp();
   const peer = usePeerExtensionRegistration(PLATFORMS.PAYPAL);
+  const depositParams = {
+    amount: "100",
+    platform: PLATFORMS.PAYPAL,
+    currency: CURRENCIES.USD,
+    identifier: "alicepay", // PayPal.me username, NOT email
+  };
 
   const needsExtension = lastError?.code === OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED;
 
   return (
     <>
-      <button
-        onClick={() =>
-          offramp(walletClient, {
-            amount: "100",
-            platform: PLATFORMS.PAYPAL,
-            currency: CURRENCIES.USD,
-            identifier: "alicepay", // PayPal.me username, NOT email
-          })
-        }
-      >
-        Sell USDC
-      </button>
+      <button onClick={() => offramp(walletClient, depositParams)}>Sell USDC</button>
 
       {needsExtension && (
         <div>
@@ -183,7 +206,14 @@ function PayPalSellButton({ walletClient }) {
             </button>
           )}
           {peer.phase === "ready" && (
-            <button onClick={peer.openVerifySidebar}>Verify in Peer</button>
+            <button onClick={peer.startRegistrationCapture} disabled={peer.busy}>
+              {peer.info?.ctaLabel ?? "Register with Peer"}
+            </button>
+          )}
+          {peer.capturedMetadata?.sarCredentialCapture?.credentialBundle && !peer.error && (
+            <button onClick={() => peer.completeRegistration(walletClient, depositParams)}>
+              Continue registration
+            </button>
           )}
           {peer.info?.ctaSubtext && <small>{peer.info.ctaSubtext}</small>}
         </div>
@@ -193,31 +223,106 @@ function PayPalSellButton({ walletClient }) {
 }
 ```
 
-Or drive the handshake manually via `peerExtensionSdk`:
+Or drive the handshake manually via `peerExtensionSdk`.
+`getPeerExtensionRegistrationAuthParams(...)` returns
+`actionType: transfer_<provider>` and `captureMode: "sellerCredential"`:
 
 ```typescript
-import { peerExtensionSdk } from "@usdctofiat/offramp";
+import {
+  CURRENCIES,
+  PLATFORMS,
+  completePeerExtensionRegistration,
+  getPeerExtensionRegistrationAuthParams,
+  isPeerExtensionMetadataBridgeAvailable,
+  offramp,
+  peerExtensionSdk,
+} from "@usdctofiat/offramp";
+
+const params = getPeerExtensionRegistrationAuthParams("paypal");
+if (!params) throw new Error("PayPal registration is not extension-gated.");
+// Auth params use captureMode: "sellerCredential" and actionType: "transfer_paypal".
+const depositParams = {
+  amount: "100",
+  platform: PLATFORMS.PAYPAL,
+  currency: CURRENCIES.USD,
+  identifier: "alicepay",
+};
+
+const startCapture = () => {
+  const unsubscribe = peerExtensionSdk.onMetadataMessage(async (message) => {
+    if (message.platform !== params.platform) return;
+    if (!message.sarCredentialCapture?.credentialBundle) return;
+    await completePeerExtensionRegistration({
+      platform: PLATFORMS.PAYPAL,
+      identifier: "alicepay",
+      capturedMetadata: message,
+    });
+    await offramp(walletClient, depositParams);
+  });
+  peerExtensionSdk.authenticate(params);
+  return unsubscribe;
+};
 
 const state = await peerExtensionSdk.getState();
-if (state === "needs_install") {
+if (state === "needs_install" || !isPeerExtensionMetadataBridgeAvailable()) {
   peerExtensionSdk.openInstallPage();
 } else if (state === "needs_connection") {
   const approved = await peerExtensionSdk.requestConnection();
-  if (approved) peerExtensionSdk.openSidebar("/verify/paypal");
+  if (approved) startCapture();
 } else {
-  peerExtensionSdk.openSidebar("/verify/paypal");
+  startCapture();
 }
 ```
 
-After the user completes the flow in the extension, call `offramp()` again.
+The captured metadata passed to `completePeerExtensionRegistration(...)` must
+include `sarCredentialCapture.credentialBundle`. Completion validates the
+captured `offchainId` against your identifier and validates the payee hash in
+the credential bundle. PayPal first registers the normalized handle through
+`/v2/makers/create` to resolve `hashedOnchainId`; Wise uses
+`credentialBundle.payeeIdHash` directly. Both paths upload the seller credential
+bundle to `/v2/makers/<processor>/<payeeHash>/seller-credential` and return
+`sellerCredentialResponse` plus `sellerCredentialStatus`. After that succeeds,
+call `offramp()` again with the same handle.
 
 ## How It Works
 
-Every deposit is automatically delegated to the Delegate vault for oracle-based rate management, auto-closes when filled, and is attributed to Galleon Labs via ERC-8021.
+Every deposit is automatically delegated to the Delegate vault for oracle-based rate management (which charges a 0.10% manager fee — see [Fees](#fees)), auto-closes when filled, and is attributed to Galleon Labs via ERC-8021.
+
+## Testing your integration
+
+There is no public staging or sandbox deployment — the SDK targets Base mainnet and the production curator API. Two ways to test:
+
+- **Small-amount mainnet runs (recommended).** Create a 1 USDC deposit against a real payment handle, confirm it on [basescan](https://basescan.org) and via `deposits(walletAddress)`, then `close()` it. This exercises the real approve → register → deposit → delegate path end to end.
+- **Proxy or mock the curator REST surface.** Pass `apiBaseUrl` to point the SDK's maker registration/validation calls (`/v2/makers/*`) at a local proxy or mock. Defaults are byte-for-byte unchanged when omitted. Only the curator REST surface is overridable — the indexer and Base RPC always target mainnet, and on-chain calls still need a real wallet client.
+
+```typescript
+import { createOfframp, PLATFORMS, CURRENCIES } from "@usdctofiat/offramp";
+
+const sdk = createOfframp({
+  walletClient,
+  apiBaseUrl: "http://localhost:8787", // proxy/mock of https://api.zkp2p.xyz
+});
+
+await sdk.createDeposit({
+  amount: "1",
+  platform: PLATFORMS.REVOLUT,
+  currency: CURRENCIES.EUR,
+  identifier: "alice",
+});
+```
 
 ## Webhooks
 
-Subscribe to live `deposit.created`, `deposit.filled`, `deposit.partially_filled`, `deposit.closed`, and `otc.taken` events for your attributed deposits. `otc.enabled` and `otc.disabled` are reserved event names. Register endpoints at [usdctofiat.xyz/developers](https://usdctofiat.xyz/developers) with your Peerlytics API key. HMAC-SHA256 signed deliveries use the `X-Usdctofiat-Signature: t=<unix>,v1=<hex>` header. Reference HMAC receiver in the [starters repo](https://github.com/ADWilkinson/usdctofiat-peerlytics-starters).
+Subscribe to live `deposit.created`, `deposit.filled`, `deposit.partially_filled`, `deposit.closed`, and `otc.taken` events for your attributed deposits. Register endpoints at [usdctofiat.xyz/developers](https://usdctofiat.xyz/developers) with your Peerlytics API key. HMAC-SHA256 signed deliveries use the `X-Usdctofiat-Signature: t=<unix>,v1=<hex>` header. Reference HMAC receiver in the [starters repo](https://github.com/ADWilkinson/usdctofiat-peerlytics-starters). (`otc.enabled` / `otc.disabled` are intentionally not emitted.)
+
+There are **two separate webhook families** — different event vocabularies, different dispatchers, different registration surfaces. Pick the one for the product you integrate:
+
+| Family                                                                              | Events                                                                                         | Emitted by                    | Register at                                                    |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------- |
+| **Offramp** (this SDK)                                                              | `deposit.created`, `deposit.filled`, `deposit.partially_filled`, `deposit.closed`, `otc.taken` | usdctofiat offramp dispatcher | [usdctofiat.xyz/developers](https://usdctofiat.xyz/developers) |
+| **Integrator** ([`@peerlytics/sdk`](https://www.npmjs.com/package/@peerlytics/sdk)) | `deposit.created`, `intent.signaled`, `intent.fulfilled`, `deposit.rate_updated`               | Peerlytics cron dispatcher    | [peerlytics.xyz/developers](https://peerlytics.xyz/developers) |
+
+One Peerlytics API key authenticates both. The integrator family also accepts the legacy aliases `intent.created`, `intent.filled`, `rate.updated` on registration (normalized server-side).
 
 ## Links