feat(cashout): allocation-funded offramp v2 + retry-from-cancelled + proxy history merge (p2pdotme#11)

Opt-in, backward-compatible support for the TradeStars offramp v2 (per-user-proxy allocation). offramp-machine: retry-from-cancelled (retain feeUsdc, add retryPlace/canRetryPlace, PLACING resets order fields). Cashout: optional fetchAvailableOfframp sources the Max/insufficient amount from an integrator allocation instead of balanceOf; Try-again button on the cancelled screen. types: CashoutProps.fetchAvailableOfframp?. PaymentHistory: optional resolveExtraAddresses merges the user's per-user-proxy orders (offramp order.user) with the EOA's, de-duped + re-sorted, bypassing the b2b intersection. README recipe added. No SDK change. npm run verify green.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Software-Artist-Aash

README.md

@@ -575,6 +575,88 @@ For a different integrator (e.g., a custom one not following the LotPot
 shape), the contract above is the same — only the ABI fragments and event
 parser change. The widget never knows the difference.
 
+### TradeStars offramp v2 (allocation-funded)
+
+The TradeStars offramp funds the SELL from a **per-user-proxy allocation** (a
+relayer moves vault USDC into the user's proxy after a Solana burn), not the
+user's wallet USDC. Three differences vs the LotPot recipe:
+
+1. **No USDC approve** — the proxy already holds the funds; `placeCashout` just
+   calls `userStartOfframp(allocationId, …)`.
+2. **`fetchAvailableOfframp`** sources the "Max" amount from the integrator's
+   `availableOfframp(user)` view instead of the wallet balance.
+3. **History** merges the user's per-user proxy (where `order.user` lives for
+   offramps) via `<PaymentHistory resolveExtraAddresses=…>`.
+
+```ts
+const TRADESTARS_ABI = [
+  { name: "userStartOfframp", type: "function", stateMutability: "nonpayable",
+    inputs: [
+      { name: "allocationId", type: "uint256" }, { name: "currency", type: "bytes32" },
+      { name: "fiatAmount", type: "uint256" }, { name: "circleId", type: "uint256" },
+      { name: "preferredPaymentChannelConfigId", type: "uint256" }, { name: "userPubKey", type: "string" },
+    ], outputs: [{ name: "orderId", type: "uint256" }] },
+  { name: "userDeliverOfframpUpi", type: "function", stateMutability: "nonpayable",
+    inputs: [{ name: "orderId", type: "uint256" }, { name: "encUpi", type: "string" }], outputs: [] },
+  { name: "syncOfframp", type: "function", stateMutability: "nonpayable",
+    inputs: [{ name: "orderId", type: "uint256" }], outputs: [] },
+  { name: "availableOfframp", type: "function", stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }], outputs: [{ type: "uint256" }] },
+  { name: "pendingAllocations", type: "function", stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }], outputs: [{ type: "uint256[]" }] },
+  { name: "proxyAddress", type: "function", stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }], outputs: [{ type: "address" }] },
+  { type: "event", name: "OfframpOrderPlaced", inputs: [
+    { name: "allocationId", type: "uint256", indexed: true },
+    { name: "orderId", type: "uint256", indexed: true },
+    { name: "user", type: "address", indexed: true },
+    { name: "amount", type: "uint256", indexed: false } ] },
+] as const;
+
+// Host picks an allocationId from pendingAllocations(user) before mounting <Cashout>.
+const allocationId = /* selected pending allocation (a bigint) */;
+
+<Cashout
+  /* …usdcAddress, diamondAddress, signer, currencies, subgraphUrl… */
+  fetchAvailableOfframp={(user) =>
+    publicClient.readContract({ address: INTEGRATOR, abi: TRADESTARS_ABI,
+      functionName: "availableOfframp", args: [user] }) as Promise<bigint>}
+  placeCashout={async (ctx) => {                 // NO approve — proxy already funded
+    const data = encodeFunctionData({ abi: TRADESTARS_ABI, functionName: "userStartOfframp",
+      args: [allocationId, stringToHex(ctx.currency.symbol, { size: 32 }), 0n,
+             ctx.currency.circleId!, ctx.currency.paymentChannelConfigId ?? 0n, ctx.userPubKey] });
+    const { hash } = await signer.sendTransaction({ to: INTEGRATOR, data, gasLimit: 1_000_000 });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    return { orderId: parseTradeStarsOrderId(receipt) /* OfframpOrderPlaced */, txHash: hash };
+  }}
+  deliverUpi={async (ctx) => {
+    const data = encodeFunctionData({ abi: TRADESTARS_ABI, functionName: "userDeliverOfframpUpi",
+      args: [BigInt(ctx.orderId), ctx.encryptedUpi] });
+    const { hash } = await signer.sendTransaction({ to: INTEGRATOR, data, gasLimit: 500_000 });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return { txHash: hash };
+  }}
+  reconcile={async (ctx) => {                     // permissionless syncOfframp
+    const data = encodeFunctionData({ abi: TRADESTARS_ABI, functionName: "syncOfframp",
+      args: [BigInt(ctx.orderId)] });
+    const { hash } = await signer.sendTransaction({ to: INTEGRATOR, data, gasLimit: 200_000 });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return { txHash: hash };
+  }}
+/>
+
+// Offramps are attributed to the user's proxy — merge it into history:
+<PaymentHistory signer={signer} subgraphUrl={SUBGRAPH} usdcAddress={USDC}
+  resolveExtraAddresses={async (user) => [
+    (await publicClient.readContract({ address: INTEGRATOR, abi: TRADESTARS_ABI,
+      functionName: "proxyAddress", args: [user] })) as `0x${string}`,
+  ]} />
+```
+
+A cancelled offramp leaves the USDC in the user's proxy, so the `<Cashout>`
+"Try again" button re-places from the same balance — self-serve retry, no
+relayer/owner. See `payment-integrators/docs/OFFRAMP-V2.md` for the contract side.
+
 > **Tip:** `userPubKey` is auto-generated from the SDK's relay identity
 > (lazily persisted in localStorage). Hosts that already use `<Checkout>`
 > share the same identity — no extra wiring required.

src/core/offramp-machine.ts

@@ -48,12 +48,14 @@ interface OfframpState {
   currency: CurrencyOption | null;
   paymentAddress: string | null;
   usdcAmount: bigint | null;
+  /** Small-order fee retained so a retry-from-cancelled can recompute the charge. */
+  feeUsdc: bigint | null;
   fiatAmount: bigint | null;
   error: string | null;
 }
 
 type OfframpAction =
-  | { type: "PLACING"; currency: CurrencyOption; paymentAddress: string; usdcAmount: bigint }
+  | { type: "PLACING"; currency: CurrencyOption; paymentAddress: string; usdcAmount: bigint; feeUsdc: bigint }
   | { type: "PLACED"; orderId: string; txHash: string }
   | { type: "ACCEPTED" }
   | { type: "ENCRYPTING" }
@@ -66,12 +68,12 @@ type OfframpAction =
 const INITIAL: OfframpState = {
   phase: "form",
   orderId: null, txHash: null, currency: null, paymentAddress: null,
-  usdcAmount: null, fiatAmount: null, error: null,
+  usdcAmount: null, feeUsdc: null, fiatAmount: null, error: null,
 };
 
 function reducer(s: OfframpState, a: OfframpAction): OfframpState {
   switch (a.type) {
-    case "PLACING": return { ...s, phase: "placing", currency: a.currency, paymentAddress: a.paymentAddress, usdcAmount: a.usdcAmount, error: null };
+    case "PLACING": return { ...s, phase: "placing", currency: a.currency, paymentAddress: a.paymentAddress, usdcAmount: a.usdcAmount, feeUsdc: a.feeUsdc, orderId: null, txHash: null, fiatAmount: null, error: null };
     case "PLACED": return { ...s, phase: "placed", orderId: a.orderId, txHash: a.txHash };
     case "ACCEPTED": return { ...s, phase: "accepted" };
     case "ENCRYPTING": return { ...s, phase: "encrypting" };
@@ -139,7 +141,7 @@ export function useOfframpMachine(opts: UseOfframpMachineOpts) {
       // SDK routing, host's approve+place txs) can each take several seconds
       // and would otherwise leave the user staring at a disabled button
       // with no feedback.
-      dispatch({ type: "PLACING", currency, paymentAddress, usdcAmount });
+      dispatch({ type: "PLACING", currency, paymentAddress, usdcAmount, feeUsdc });
 
       const errorCtx: P2PErrorContext = {
         flow: "place-sell",
@@ -346,11 +348,24 @@ export function useOfframpMachine(opts: UseOfframpMachineOpts) {
     }
   }, [state.orderId, publicClient, opts, encryptAndDeliver]);
 
+  /**
+   * Re-place a fresh SELL after a CANCELLED order. For allocation-funded
+   * offramps (TradeStars) the cancelled order's USDC is back in the user's
+   * proxy, so re-placing draws from the same balance — self-serve retry with
+   * no relayer/owner. Reuses the retained currency / paymentAddress / amount.
+   */
+  const retryPlace = useCallback(() => {
+    if (!state.currency || state.paymentAddress === null || state.usdcAmount === null) return;
+    return submit(state.currency, state.paymentAddress, state.usdcAmount, state.feeUsdc ?? 0n);
+  }, [state.currency, state.paymentAddress, state.usdcAmount, state.feeUsdc, submit]);
+
   return {
     state,
     submit,
     retryDeliver,
+    retryPlace,
     canRetry: state.phase === "error" && state.orderId !== null,
+    canRetryPlace: state.phase === "cancelled" && state.currency !== null,
     reset: () => dispatch({ type: "RESET" }),
   };
 }

src/types.ts

@@ -364,6 +364,11 @@ export interface CashoutProps {
    *  Diamond hits a terminal status. Skip if your integrator doesn't
    *  need it. Always called best-effort (errors swallowed). */
   reconcile?: (ctx: ReconcileContext) => Promise<{ txHash: string }>;
+  /** Optional — source the cashout-able amount from an integrator allocation
+   *  (e.g. TradeStars per-user-proxy) instead of the user's wallet USDC
+   *  balance. When provided, the "Max" affordance + insufficient-balance check
+   *  use this value (6-decimal USDC). Omit for the default user-holds-USDC flow. */
+  fetchAvailableOfframp?: (user: `0x${string}`) => Promise<bigint>;
   chainId?: number;
   rpcUrl?: string;
   /** Required when any selected `CurrencyOption` omits `circleId` — passed

src/widgets/Cashout.tsx

@@ -40,7 +40,7 @@ export function Cashout(props: CashoutProps) {
   const {
     usdcAddress, diamondAddress, signer, currencies,
     chainId = 84532, rpcUrl, subgraphUrl, fiatAmountLimit,
-    placeCashout, deliverUpi, reconcile,
+    placeCashout, deliverUpi, reconcile, fetchAvailableOfframp,
     defaultAmountUsdc, mode = "modal", open = true, theme,
     onClose, onOrderPlaced, onComplete, onCancelled, onError,
   } = props;
@@ -116,16 +116,27 @@ export function Cashout(props: CashoutProps) {
     }
   }, [amountInput]);
 
-  // Read USDC balance for the "Max" affordance + insufficient-balance hint.
-  // Uses the read-only ERC20 ABI fragment — no integrator dependency.
+  // Source the cashout-able amount for the "Max" affordance + insufficient
+  // hint. Default: the user's on-chain USDC balance (read-only ERC20 ABI, no
+  // integrator dependency). Allocation-funded offramps (e.g. TradeStars) pass
+  // `fetchAvailableOfframp` so the amount comes from the user's per-user-proxy
+  // allocation instead of their wallet balance.
   useEffect(() => {
+    let cancelled = false;
+    if (fetchAvailableOfframp) {
+      fetchAvailableOfframp(signer.address)
+        .then((b) => { if (!cancelled) setBalance(b); })
+        .catch(() => {});
+      return () => { cancelled = true; };
+    }
     const chain = chainId === 8453 ? base : baseSepolia;
     const pc = createPublicClient({ chain, transport: http(rpcUrl) });
     pc.readContract({
       address: usdcAddress, abi: ERC20_READ_ABI,
       functionName: "balanceOf", args: [signer.address],
-    }).then((b) => setBalance(b as bigint)).catch(() => {});
-  }, [chainId, rpcUrl, usdcAddress, signer.address]);
+    }).then((b) => { if (!cancelled) setBalance(b as bigint); }).catch(() => {});
+    return () => { cancelled = true; };
+  }, [chainId, rpcUrl, usdcAddress, signer.address, fetchAvailableOfframp]);
 
   useEffect(() => {
     if (!dropdownOpen) return;
@@ -138,7 +149,7 @@ export function Cashout(props: CashoutProps) {
     return () => document.removeEventListener("mousedown", onClick);
   }, [dropdownOpen]);
 
-  const { state, submit, retryDeliver, canRetry, reset } = useOfframpMachine({
+  const { state, submit, retryDeliver, canRetry, retryPlace, canRetryPlace, reset } = useOfframpMachine({
     usdcAddress, diamondAddress, signer,
     chainId, rpcUrl, subgraphUrl, fiatAmountLimit,
     placeCashout, deliverUpi, reconcile,
@@ -506,11 +517,21 @@ export function Cashout(props: CashoutProps) {
                   <CenterStatus
                     icon={<XIcon />}
                     title="Order cancelled"
-                    subtitle="Your USDC was refunded to your wallet automatically. You can try again any time."
+                    subtitle="The order was cancelled and your funds were returned. You can try again any time."
                     variant="warning"
                   />
+                  {canRetryPlace && (
+                    <button style={{ ...S.primaryBtn, marginTop: 20 }} onClick={() => retryPlace()}>
+                      Try again
+                    </button>
+                  )}
                   {onClose && (
-                    <button style={{ ...S.primaryBtn, marginTop: 20 }} onClick={onClose}>Close</button>
+                    <button
+                      style={canRetryPlace
+                        ? { ...S.ghostBtn, width: "100%", marginTop: 8, height: 40 }
+                        : { ...S.primaryBtn, marginTop: 20 }}
+                      onClick={onClose}
+                    >Close</button>
                   )}
                 </div>
               )}

src/widgets/PaymentHistory.tsx

@@ -124,6 +124,15 @@ export interface PaymentHistoryProps {
    * address. Lookup is case-insensitive.
    */
   integratorNames?: Record<string, string>;
+  /**
+   * Optional — extra addresses to merge into this user's history. For
+   * integrators that place orders under a per-user proxy (e.g. TradeStars
+   * offramp v2, where `order.user` is the user's proxy), resolve the proxy
+   * address(es) here so those orders show alongside the EOA's. Results are
+   * merged, de-duped by orderId, and re-sorted newest-first; extra-address
+   * orders bypass the b2b intersection (they're keyed on the proxy, not the EOA).
+   */
+  resolveExtraAddresses?: (user: `0x${string}`) => Promise<`0x${string}`[]>;
   /** Optional theming overrides. See `P2PTheme` for the surface. */
   theme?: P2PTheme;
 }
@@ -142,6 +151,7 @@ export function PaymentHistory(props: PaymentHistoryProps) {
     b2bOnly,
     integrators,
     integratorNames,
+    resolveExtraAddresses,
     theme,
   } = props;
   const themeStyle = themeToCssVars(theme);
@@ -173,6 +183,9 @@ export function PaymentHistory(props: PaymentHistoryProps) {
   const [loading, setLoading] = useState(true);
   // orderId (decimal string) → owning integrator, populated only in B2B mode.
   const [b2bMap, setB2bMap] = useState<Map<string, B2BOrderMeta> | null>(null);
+  // orderIds sourced from an extra (proxy) address via `resolveExtraAddresses`;
+  // these bypass the b2b intersection since they're keyed on the proxy.
+  const [extraOrderIds, setExtraOrderIds] = useState<Set<string>>(new Set());
   // Per-currency on-chain config — fetched lazily for currencies that have
   // at least one order missing `actualFiatAmount` (i.e. pre-acceptance:
   // placed orders and orders cancelled before a merchant accepted). Lets us
@@ -199,19 +212,40 @@ export function PaymentHistory(props: PaymentHistoryProps) {
       // Fetch the canonical order list and (in B2B mode) the user's B2B
       // order→integrator map together so they land in the same render and
       // the list never flickers through a "no orders" frame.
-      const [result, b2b] = await Promise.all([
+      const extraAddrs = resolveExtraAddresses
+        ? await resolveExtraAddresses(signer.address)
+        : [];
+      const [result, b2b, ...extra] = await Promise.all([
         client.getOrders({ userAddress: signer.address, skip: 0, limit }),
         b2bMode ? fetchB2BMap(subgraphUrl, signer.address) : Promise.resolve(null),
+        ...extraAddrs.map((a) => client.getOrders({ userAddress: a, skip: 0, limit })),
       ]);
       if (result.isErr()) throw result.error;
-      setOrders(result.value);
+      // Merge the EOA's orders with any extra-address (e.g. per-user proxy)
+      // orders, de-duping by orderId and re-sorting newest-first.
+      const merged = [...result.value];
+      const seen = new Set(merged.map((o) => o.orderId.toString()));
+      const extraIds = new Set<string>();
+      for (const r of extra) {
+        if (r.isErr()) continue;
+        for (const o of r.value) {
+          const id = o.orderId.toString();
+          if (seen.has(id)) continue;
+          seen.add(id);
+          extraIds.add(id);
+          merged.push(o);
+        }
+      }
+      merged.sort((a, b) => Number(b.placedAt - a.placedAt));
+      setOrders(merged);
+      setExtraOrderIds(extraIds);
       setB2bMap(b2b);
     } catch (err: any) {
       setError(err?.message ?? "Failed to fetch orders");
     } finally {
       setLoading(false);
     }
-  }, [signer?.address, subgraphUrl, usdcAddress, chainId, diamondAddress, rpcUrl, limit, b2bMode]);
+  }, [signer?.address, subgraphUrl, usdcAddress, chainId, diamondAddress, rpcUrl, limit, b2bMode, resolveExtraAddresses]);
 
   useEffect(() => { fetchOrders(); }, [fetchOrders, refreshKey]);
 
@@ -286,6 +320,9 @@ export function PaymentHistory(props: PaymentHistoryProps) {
   // integrator is on it. In non-B2B mode this is a no-op pass-through.
   const allOrders = b2bMode
     ? overlaidOrders.filter((o) => {
+        // Extra-address (per-user proxy) orders are keyed on the proxy, not the
+        // EOA's b2Borders set, so the intersection would drop them — keep them.
+        if (extraOrderIds.has(o.orderId.toString())) return true;
         const meta = b2bMap?.get(o.orderId.toString());
         if (!meta) return false;
         if (integratorFilter && !integratorFilter.has(meta.integrator)) return false;