diff --git a/07 - Development/Environment Variables.md b/07 - Development/Environment Variables.md index 9dcb5d7..fbc8e73 100644 --- a/07 - Development/Environment Variables.md +++ b/07 - Development/Environment Variables.md @@ -299,8 +299,22 @@ AUTO_SEED_ON_START=true ESCROW_WALLET_ADDRESS=0xa3049825c0785095EEd5E7976E0E539466c84044 ADMIN_PAYOUT_WALLET_ADDRESS= +# Derived destinations (per-(buyer, sellerOffer) RN ephemeral wallets — Task #7) +# Backend ONLY needs the xpub. The master seed must live in KMS/Trezor. +DERIVED_DESTINATION_XPUB= +# Only set DERIVED_DESTINATION_XPRIV when DERIVED_DESTINATION_SWEEP_SIGNER=hot-key +# (dev shortcut). For prod, leave this blank and use the Trezor flow (Task #11). +DERIVED_DESTINATION_XPRIV= +DERIVED_DESTINATION_BASE_PATH=m/44'/60'/0' +DERIVED_DESTINATION_CHAIN_ID=56 +DERIVED_DESTINATION_SWEEP_SIGNER=build-only +DERIVED_DESTINATION_MIN_SWEEP_AMOUNT=0 +DERIVED_DESTINATION_SWEEP_INTERVAL_MS=300000 + # OAuth GOOGLE_CLIENT_ID= ``` > [!tip] Generate `JWT_SECRET` deterministically per environment so you don't accidentally invalidate sessions when restarting. Store it in your team's secret manager. + +> [!warning] `DERIVED_DESTINATION_XPRIV` is a development-only shortcut. In production, set `DERIVED_DESTINATION_SWEEP_SIGNER=build-only` and pair with Task #11 Trezor signing so the master seed never sits on the backend host. diff --git a/08 - Operations/Handoff - Request Network In-House Checkout - 2026-05-28.md b/08 - Operations/Handoff - Request Network In-House Checkout - 2026-05-28.md index b3d2297..8841c3c 100644 --- a/08 - Operations/Handoff - Request Network In-House Checkout - 2026-05-28.md +++ b/08 - Operations/Handoff - Request Network In-House Checkout - 2026-05-28.md @@ -61,10 +61,40 @@ From `PRD - Request Network In-House Checkout.md` §10: Five follow-ups scoped for kimi to pick up independently. Full spec in `PRD - Wallet, Multichain, Confirmations, AML, Trezor.md`. Quick index: -| # | Task | Priority | Depends on | -|---|---------------------------------------------------------------|----------|------------| -| 7 | Per-(buyer, sellerOffer) ephemeral RN destination wallets | high | (sweep step soft-depends on #11) | -| 8 | Multichain RN proxy registry + USDC/USDT support | high | — | -| 9 | Per-chain confirmation thresholds + admin UI | medium | — | -| 10 | Optional AML screening on incoming payments (seller-paid) | medium | — | -| 11 | Trezor signing for admin actions (release/refund/sweep) | high | — | +| # | Task | Priority | Status | +|---|---------------------------------------------------------------|----------|--------| +| 7 | Per-(buyer, sellerOffer) ephemeral RN destination wallets | high | 🟡 In progress — backend + admin UI shipped in 2.6.42, cart-aware buyer UX + tests + live RN-accepts-divergent-destination probe remain | +| 8 | Multichain RN proxy registry + USDC/USDT support | high | ⏳ Not started | +| 9 | Per-chain confirmation thresholds + admin UI | medium | ⏳ Not started | +| 10 | Optional AML screening on incoming payments (seller-paid) | medium | ⏳ Not started | +| 11 | Trezor signing for admin actions (release/refund/sweep) | high | ⏳ Not started | + +## Task #7 — what landed in 2.6.42 + +**Backend** (`backend/src/services/payment/wallets/` + plumbing) +- `DerivedDestination` model: `(buyerId, sellerOfferId, chainId)` → address, derivation path, status, sweep history. +- `derivedDestinations.ts`: xpub-driven HD address derivation, atomic counter-based index allocation, idempotent `getDestinationFor`, race-safe upsert. Backend holds `DERIVED_DESTINATION_XPUB` only — master seed lives in KMS / Trezor (Task #11). +- `sweepService.ts`: pluggable signer abstraction (`build-only` default; `hot-key` for dev), ERC-20 balance queries, sweep orchestration, interval-based cron. +- `derivedDestinationRoutes.ts`: admin-only REST endpoints (list, sweep-all, sweep-one, config health, cron start/stop/status). Mounted at `/api/payment/derived-destinations`. +- `requestNetworkPayInService.ts` now calls `getDestinationFor(buyer, sellerOffer, chainId)`, builds the per-payment merchant reference via `buildMerchantReference`, persists `metadata.derivedDestination`, and passes the override to RN. +- `inHouseCheckout.ts` accepts a `destinationOverride`; the on-chain `paymentReference` compute-fallback now uses the actual destination (previously read `parsed.recipient` — hidden bug because RN's response provides the ref directly, but the fallback was broken for derived destinations). +- `TransactionSafetyProvider.resolveExpectedRecipient` checks `metadata.derivedDestination.address` first, then legacy fallback. + +**Frontend** (admin only) +- `/dashboard/admin/derived-destinations` page (table view, filters by status/chain/address, pagination, sweep-all, cron start/stop). +- Per-row UI: address with copy + BscScan link, status chip, derivation path, balance, sweep count, last sweep tx link. + +**Env additions** (see `backend/.env.example`): +- `DERIVED_DESTINATION_XPUB` — required for address derivation. +- `DERIVED_DESTINATION_XPRIV` — only when `DERIVED_DESTINATION_SWEEP_SIGNER=hot-key` (dev shortcut). +- `DERIVED_DESTINATION_BASE_PATH=m/44'/60'/0'` +- `DERIVED_DESTINATION_CHAIN_ID=56` +- `DERIVED_DESTINATION_SWEEP_SIGNER=build-only` +- `DERIVED_DESTINATION_MIN_SWEEP_AMOUNT=0` +- `DERIVED_DESTINATION_SWEEP_INTERVAL_MS=300000` + +**Remaining in task #7:** +1. Cart-aware buyer UX on the in-house checkout (sequential multi-seller approval flow with clear progress UI). +2. Unit tests for `derivedDestinations.ts` (idempotency, race handling) and `sweepService.ts`. +3. Live probe on dev: confirm RN accepts divergent `destinationId` across consecutive `POST /v2/secure-payments` calls from the same client. +4. Optional: auto-start sweep cron on backend boot via `app.ts` (currently manual via admin endpoint).