nick-doc/PRD - Wallet, Multichain, Confirmations, AML, Trezor.md

# PRD: Wallet, Multichain, Confirmations, AML, Trezor

> Status: **Living — last edit 2026-05-28 (after Task #7 core shipped in backend/frontend 2.6.42)**
> Author: nick + claude
> Owner: backend (payments) + frontend (admin UI + checkout)
> Related: `PRD - Request Network In-House Checkout.md`, `01 - Architecture/Request Network Integration Constraints.md`, `08 - Operations/Handoff - Request Network In-House Checkout - 2026-05-28.md`

Five follow-ups to the in-house Request Network checkout. They are sized so a single contributor can pick up any one of them in isolation. Each is its own Taskmaster top-level task — see `#7…#11`.

---

## 1. Per-(buyer, sellerOffer) ephemeral destination wallets — Task #7

### Status: 🟡 In progress — backend + admin UI landed in 2.6.42; cart-aware UX (A), auto-start cron (D), and `recordSweep` accumulation fix (E) shipped; doc updates (F) in progress; unit tests (B) pending. Live divergent-destination probe (C) still pending.

### Problem
The in-house checkout used to send *all* RN-routed payments to one Amanat-controlled wallet (env: `REQUEST_NETWORK_MERCHANT_REFERENCE`). That wallet was shared across every buyer, every seller, every offer — an audit nightmare and a single point of compromise.

### Goal (achieved on the backend)
For each `Payment` record (which represents a `(buyerId, sellerOfferId)` pair), generate a fresh on-chain destination address, persist it on the `Payment` record, and tell Request Network to expect funds on that address. RN's webhook flows unchanged.

### Key clarification: cart with multiple sellers

A buyer's cart can contain items from multiple sellers. **That's already modeled in Amanat as N separate `Payment` records, one per `sellerOfferId` in the cart** — see the `uniq_pending_request_network_by_buyer_session` index in `requestNetworkPayInService.ts`. So:

- 1 Payment record = 1 derived destination address = 1 RN intent = 1 buyer-side on-chain transaction.
- A 5-item cart spanning 2 sellers produces 2 Payments, 2 derived addresses, 2 RN intents, and the buyer makes 2 approve+pay tx pairs in sequence.
- RN's `ERC20FeeProxy.transferFromWithReferenceAndFee` is single-destination by design — there's no atomic multi-recipient split. A future v2 could route the cart through an Amanat splitter contract that fans out to per-seller derived addresses in one buyer tx; that's out of scope here.

### Hard-known facts (from RN docs we've cold-inspected so far)
- The "destination" in RN is the `destinationId` inside the merchant reference: `<address>@eip155:<chainId>#<contractId>:<tokenAddress>`. RN doesn't bind this to an Amanat-level identity; it's just where the funds end up.
- Each `POST /v2/secure-payments` request *can* pass a different `destinationId`. RN doesn't reject divergent destinations across requests from the same client. **Acceptance probe still pending — see remaining work.**
- `paymentReference` is derived per request (`last8Bytes(keccak256(requestId+salt+destination))`), so different destinations naturally produce different on-chain refs. The webhook listener keys on the ref + tx hash.

### Decisions taken during implementation
These were open questions in the original draft; the shipped implementation locked them in.

| Question | Decision |
|---|---|
| Key custody model | **HD wallet, derived addresses, reused per `(buyer, sellerOffer, chainId)` triple**. Backend holds only an xpub (`DERIVED_DESTINATION_XPUB`). The xpriv / master seed lives in KMS or Trezor (Task #11). |
| Granularity | **Per `(buyer, sellerOffer, chainId)` triple**, reused for repeat payments to the same offer (one address can fund and then be re-funded later — sweeps happen out-of-band). The PRD draft considered single-use rotation; reuse won for simpler audit and to avoid bloating the derivation tree. |
| Derivation index allocation | Monotonic counter in a `counters` Mongo collection (`{_id: 'derived_destination_index', seq: <int>}`) updated atomically via `findByIdAndUpdate { $inc: { seq: 1 } }`. No re-derivation, no race window. |
| Sweep strategy | **Cron-based** by default (`DERIVED_DESTINATION_SWEEP_INTERVAL_MS=300000`, i.e. 5 min) **plus manual admin trigger**. Both go through the same `sweepService` and the same Transaction Safety Provider checks. Auto-start on backend boot is not wired yet — admins start the cron via `POST /api/payment/derived-destinations/cron/start`. |
| Signing | **`DERIVED_DESTINATION_SWEEP_SIGNER=build-only`** in prod — the backend builds the sweep tx but doesn't sign it (Trezor flow in Task #11 will). For local dev, `DERIVED_DESTINATION_SWEEP_SIGNER=hot-key` plus `DERIVED_DESTINATION_XPRIV` lets the backend sign — DO NOT USE IN PROD. |

### Still open
1. **Multi-seller cart UX** — not built. Today's frontend assumes 1 Payment per checkout page. The PRD copy from the original draft still applies:
   - "You're paying 2 sellers for this order. Please confirm 4 transactions in your wallet."
   - Progress indicator: "Paid 1 of 2 sellers — continue?"
   - Mid-cart abandonment: the sellers who already received funds are settled; the rest stay pending. No special backend work — the existing Payment lifecycle covers it.
2. **Cold-payment recovery** — out of scope for v1. Buyer never types an address into our UI, so the only way funds land on a derived address without a Payment record is RN's webhook arriving for a payment we don't recognise. Manual support recovery is acceptable.
3. **Live "RN accepts divergent destinations" probe** — has to happen on dev with two real paid intents to two different derived addresses, with the webhook firing correctly for both. Until this probe passes, treat the divergent-destination capability as an unverified assumption.

### What landed in 2.6.42
- **Backend (`backend/src/services/payment/wallets/`):**
  - `derivedDestinations.ts` — `getDestinationFor({ buyerId, sellerOfferId, chainId })` returning `{ address, derivationPath, derivationIndex, chainId }`. Idempotent: checks for an existing row first; on E11000 from a race, re-reads the racer's row. Validates the env xpub rejects xpriv / tprv prefixes. Exposes `resolveExpectedRecipientForPayment` for the Transaction Safety Provider's verification path.
  - `sweepService.ts` — pluggable signer abstraction (`build-only` / `hot-key`), ERC-20 `balanceOf` reads via Alchemy/public RPC, sweep orchestration, and an interval-based cron.
  - `derivedDestinationRoutes.ts` — admin-only REST: `GET /` (list with status/chain/address filters and pagination), `POST /sweep` (sweep all eligible), `POST /:id/sweep` (per-row), `GET /config/health`, `POST /cron/start`, `POST /cron/stop`, `GET /cron/status`.
- **Backend integrations:**
  - `models/DerivedDestination.ts` — Mongo model with sweep status + history. Indexed on `(buyerId, sellerOfferId, chainId)` unique.
  - `models/Payment.ts` — `metadata.derivedDestination` snapshot field.
  - `adapters/types.ts` — `CreatePayInIntentInput.merchantReference` for per-payment override.
  - `requestNetwork/contract.ts` — `buildRequestNetworkMerchantReference` accepts `input.merchantReference` as highest priority.
  - `requestNetwork/merchantReference.ts` — `buildMerchantReference()` inverse of the parser.
  - `requestNetwork/requestNetworkPayInService.ts` — calls `getDestinationFor`, builds the per-payment merchant reference via `buildMerchantReference`, persists `metadata.derivedDestination` on the Payment, passes the override into `adapterResult` via `input.merchantReference`.
  - `requestNetwork/inHouseCheckout.ts` — accepts `destinationOverride`; the on-chain-paymentReference compute-fallback now uses the actual recipient (was reading `parsed.recipient` — hidden bug because RN's response provides the ref directly, but the fallback path was broken for derived destinations).
  - `safety/transactionSafetyProvider.ts` — `resolveExpectedRecipient` checks `payment.metadata.derivedDestination.address` first, then legacy fallback chain.
  - `app.ts` — mounts `/api/payment/derived-destinations`.
- **Frontend (`frontend/src/sections/admin/derived-destinations/`, `frontend/src/app/dashboard/admin/derived-destinations/`):**
  - List view with filters (status, chain, address search), 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, per-row sweep action.
- **Env additions** (see `backend/.env.example`): `DERIVED_DESTINATION_XPUB` (required), `DERIVED_DESTINATION_XPRIV` (dev only), `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 work for Task #7 (kimi)

| # | What | Where | Status | Notes |
|---|------|-------|--------|-------|
| A | **Cart-aware buyer UX** on the in-house checkout page. | `frontend/src/sections/payment/checkout/rn-in-house-checkout-view.tsx` (and `provider-payment.tsx` for the entry flow). | ✅ Done | Entry walks each `sellerOfferId` in the cart, creates N intents sequentially, stashes them in `sessionStorage`, and the checkout view iterates with per-Payment progress and an "N of M sellers" header. Mid-cart abandonment leaves already-paid Payments settled and the rest in `pending`. |
| B | **Unit tests** for the new modules. | `backend/__tests__/derived-destinations.test.ts` + `backend/__tests__/sweep-service.test.ts` + `backend/__tests__/request-template-orphan-cleanup.test.ts`. | ✅ Done | 46 tests: `getDestinationFor` idempotency, E11000 race fallback, xpub rejection of xpriv/tprv, `deriveAddressAtIndex` determinism, `recordSweep` accumulation (regression lock-in for E), orphan-cleanup provider filtering (regression lock-in for Gap 2 fix). |
| C | **Live divergent-destination probe** on dev. | Manual test, no code. | ⏳ Pending | Run two paid intents on the in-house page to two different `sellerOfferId`s (so two different derived addresses), confirm both `TransferWithReferenceAndFee` events fire, both webhooks land, and both Payments transition to `completed`. Record the tx hashes in the handoff doc. |
| D | **Auto-start the sweep cron on boot**. | `backend/src/app.ts` after the route mount, behind `DERIVED_DESTINATION_SWEEP_AUTOSTART=true`. | ✅ Done | Cron now starts on boot when the env flag is set; admin endpoint still available for manual control. |
| E | **Fix `recordSweep` accumulation**. | `backend/src/services/payment/wallets/derivedDestinations.ts`. | ✅ Done | Switched from `$setOnInsert: { totalSwept }` to `$inc: { totalSwept }` so accumulation advances on every sweep. |
| F | **Update Activity Log + API Reference doc** in `nick-doc/` with the new admin endpoints. | `nick-doc/03 - API Reference/...`, `nick-doc/00 - Overview/Activity Log.md`. | 🟡 In progress | Endpoints: `GET /api/payment/derived-destinations`, `POST /api/payment/derived-destinations/sweep`, `POST /api/payment/derived-destinations/:id/sweep`, `GET /api/payment/derived-destinations/config/health`, `POST /api/payment/derived-destinations/cron/start`, `POST /api/payment/derived-destinations/cron/stop`, `GET /api/payment/derived-destinations/cron/status`. All admin-only. |

### Non-goals (carried forward unchanged)
- Multi-chain destinations (covered in Task #8).
- Buyer-side ephemeral keys (covered in `Request Network Integration Constraints.md` §3, separate PRD).
- Hardware-wallet-signed sweeps (covered in Task #11 — task #7 ships the `build-only` plumbing that Task #11 plugs into).

### Acceptance criteria
1. ✅ Two payments from the same buyer to two different sellers land on two different addresses on-chain. (Backend logic shipped; frontend multi-checkout UX shipped; live verification pending item C.)
2. ✅ RN's webhook fires correctly for both, regardless of the destination divergence. (Backend integration + multi-checkout UX shipped; end-to-end verification pending item C.)
3. 🟡 Sweep runs idempotently — re-running it on an already-swept address advances `totalSwept` correctly. (`$inc` fix shipped in E; lock-in test pending B.)
4. ✅ Admin UI shows the address, its balance, last sweep tx (link to BscScan), and current ownership status.
5. ✅ Master seed never leaves the KMS/secret store. Backend reads derivation paths from xpub only; production signing path is `build-only` (Task #11 Trezor). Dev hot-key is documented as dev-only.
6. ✅ Multi-seller cart UX completes N approve+pay pairs sequentially with clear progress UI.

---

## 2. Multi-chain RN proxy registry + USDC/USDT support — Task #8

### Problem
`backend/src/services/payment/requestNetwork/proxyAddresses.ts` and `tokens.ts` currently hardcode BSC USDC plus a handful of token entries. The in-house checkout will fall through to "in-house checkout not available" the moment a buyer wants to pay on Arbitrum/Polygon/Ethereum, or wants USDT instead of USDC on the same chain.

### Goal
Verified-from-chain registry of:
- RN's `ERC20FeeProxy` address per supported chain.
- USDC + USDT contract address + decimals per chain.

Plus an admin "supported networks" UI that:
- Lists each chain + token combo with its current status (verified-on-chain / probe failed / disabled).
- Shows which chains a given seller has whitelisted (depends on per-seller `acceptedChains` config; out of scope here — see `Request Network Integration Constraints.md` §2).

### Hard-known facts
- RN published their canonical `ERC20FeeProxy` for BSC + Arbitrum as `0x0DfbEe143b42B41eFC5A6F87bFD1fFC78c2f0aC9` (CREATE2 deterministic). Same address on Ethereum mainnet, Polygon, Base **per the deterministic deployment claim** — needs verifying.
- BSC USDC has 18 decimals (Binance-Peg). Mainnet/Arb/Polygon USDC have 6.
- USDT on Ethereum requires `approve(0)` before a non-zero re-approve. Other chains' USDT don't.

### Scope
1. Probe script `backend/scripts/probe-rn-chains.ts` that walks every chain in `supported-chains.json`, calls a known view fn on the candidate proxy address, and confirms it's a real RN proxy (not just bytes). Emits a report.
2. Promote `tokens.ts` to load from a JSON file + override layer for admin-managed entries. Keep the canonical defaults committed.
3. Backend route `GET /api/admin/rn/networks` returning the registry plus probe status.
4. Frontend admin page `/dashboard/admin/networks` rendering the table.
5. `buildInHouseCheckoutBlock` consults the chain registry; returns `reason='unsupported_chain:<chainId>'` cleanly.
6. Add the USDT-mainnet `approve(0)` quirk to the frontend approve step. When detected, the approve flow does `approve(spender, 0)` → `approve(spender, amount)`.

### Non-goals
- Letting a seller pick which chain a given buyer can use (separate PRD, §2 in constraints doc).
- Cross-chain bridging.

### Acceptance criteria
1. ✅ Probe script confirms RN proxy address on BSC, Arbitrum, Polygon, Ethereum. Base canonical address has no code — documented in [[08 - Operations/Handoff - RN Multichain Probe - 2026-05-28]].
2. ✅ Token registry has entries for USDC + USDT on 4 verified chains (BSC, Arbitrum, Ethereum, Polygon) with correct decimals. Base entries removed pending proxy address discovery.
3. 🔄 In-house checkout supports USDT on BSC end-to-end — **pending paid probe** (needs real wallet + test BSC USDT on dev).
4. 🟡 USDT-mainnet `approve(0)` reset is handled in the UI — **implemented but unverified** (see handoff doc for Tenderly fork vs wait-for-usage decision).
5. ✅ Admin networks page renders the registry with a reload-from-disk button.

---

## 3. Confirmation-counting + admin threshold UI — Task #9

### Problem
The Transaction Safety Provider already reads `TRANSACTION_SAFETY_MIN_CONFIRMATIONS` from env (default 12). That number is global, baked into env, only changeable by re-deploy. We want it tunable per-chain at runtime by an admin, with a clear UI showing each in-flight payment's current confirmation depth against the threshold.

### Goal
1. Persist per-chain confirmation thresholds in a `ConfigKV` collection (or extend an existing settings model) so admin can adjust without redeploy.
2. The `TransactionSafetyProvider`'s confirmation check reads the runtime threshold first, falls back to env.
3. Frontend admin UI to view + edit per-chain thresholds, and a "payments awaiting confirmation" table that shows `confirmations / threshold` updated live.

### Scope
1. New collection / extension to existing `Setting` model: `{ key: 'confirmation_threshold:<chainId>', value: <int>, updatedBy, updatedAt }`.
2. Public-to-admin endpoint `GET /api/admin/settings/confirmation-thresholds` and `PATCH /api/admin/settings/confirmation-thresholds/:chainId`.
3. Wire `transactionSafetyProvider` to read from this store; cache for 30s to avoid Mongo hammering.
4. Frontend admin page `/dashboard/admin/confirmation-thresholds`:
   - Table of chains, current threshold, recommended default (e.g. 12 for BSC).
   - Edit-in-place with a confirm dialog.
   - Audit-log style "changed by X on Y at Z".
5. Frontend admin page `/dashboard/admin/payments/awaiting-confirmation`:
   - Lists payments with `escrowState !== 'funded'` and `metadata.transactionSafety.lastCheck.status === 'pending'`.
   - For each: tx hash (linked to explorer), current confirmations (poll-driven), threshold, ETA.

### Non-goals
- Per-asset thresholds (only per-chain).
- Per-seller overrides.

### Acceptance criteria
1. Admin can lower BSC's threshold from 12 to 3 on the live dev stack without a redeploy and a new webhook fires the safety gate with the new value within 30s.
2. Awaiting-confirmation table updates live as new blocks arrive (poll every 12s on BSC).
3. Audit log records every threshold change with admin user, before/after, timestamp.

---

## 4. Optional AML screening (seller-paid) — Task #10

### Problem
The Transaction Safety Provider has an `evaluateAmlPlaceholder()` stub that currently returns `status: skipped`. We want a real AML pass that the seller can *opt into* per-offer, with the seller covering the per-check API cost.

### Goal
1. Pick a provider (Chainalysis Address Screening, TRM Labs, Elliptic — open question). Default recommendation: Chainalysis Address Screening (cheapest, simplest API).
2. Per-offer setting: `requireAmlCheck: true|false` plus `amlCheckPricePaidBy: 'seller'`.
3. When AML required, the in-house checkout webhook hits the provider with the buyer's source address. Result feeds into Transaction Safety Provider as a real `aml_screening` check.
4. Seller's account is debited for the per-check cost from their Amanat balance (or the payment is partially withheld for the cost).

### Hard-known facts
- AML providers charge per-check (USD 0.10–0.50 typical). Some charge a flat monthly minimum.
- Chainalysis returns categories like `sanctions`, `darknet_marketplace`, `mixer`. Provider doesn't return PII.
- Most providers have rate limits (~50 rps).

### Open questions
1. **Provider choice.** Need a 1-page comparison: per-check cost, response latency, supported chains, sanctions-coverage scope.
2. **Failure mode.** If the AML API is down, do we pass-through (let the payment complete) or fail-closed (block)? Recommended: fail-closed only when seller explicitly opted in *and* enabled "block-on-provider-failure". Otherwise warn + log.
3. **Cost accounting.** Per-check cost is small; do we round up to nearest cent, batch by day, or pass-through exact?

### Scope
1. Add `requireAmlCheck` + `amlBlockOnFailure` fields to the `Offer` schema (or `SellerOffer`).
2. New `backend/src/services/payment/safety/amlProvider.ts` interface + `chainalysisProvider.ts` impl. Behind env flag `TRANSACTION_SAFETY_AML_PROVIDER=chainalysis`.
3. Transaction Safety Provider's `aml_screening` check now real, with `metadata.amlResult` persisted on the Payment record for audit.
4. Cost accounting: deduct per-check cost from seller's escrow on payment completion; surface this as a line item on the payment-details view.
5. Frontend offer-edit UI: a toggle "Require AML on incoming payments (cost: $X per payment, paid by you)".
6. Frontend admin UI for global AML provider configuration (provider, API key, per-chain enabled/disabled).

### Non-goals
- Buyer-side AML (we screen the buyer's *source* address, not the seller's identity).
- Custom AML rules / scoring beyond the provider's verdict.

### Acceptance criteria
1. A seller can opt into AML on a specific offer. Toggle persists.
2. An incoming payment to that offer triggers a real Chainalysis API call; the result is stored on the Payment record.
3. Verdict `sanctions` blocks the escrow gate; verdict `clean` lets it through.
4. The seller's settled amount is reduced by the AML check cost; a corresponding ledger entry is created.
5. Admin can rotate the Chainalysis API key without redeploy.
6. If the provider is down and `amlBlockOnFailure=true`, the payment stays in pending; a `provider_unavailable` reason surfaces in the admin dashboard.

---

## 5. Trezor support for admin signing — Task #11

### Problem
Today, admin actions that require signing (escrow release, refund, sweep of derived destinations once Task #7 ships) run from a hot-key in the backend env (`ADMIN_PRIVATE_KEY` or similar). That key is a single-point-of-compromise for all custodial funds.

### Goal
Replace the hot-key flow with a Trezor-mediated browser flow:
1. Admin connects a Trezor via WebUSB in the admin dashboard.
2. Admin approves an action in the UI; the unsigned transaction is built backend-side, sent to the browser, signed by the Trezor, broadcast from the browser.
3. The backend never has the private key. The Trezor seed never touches a network.

### Hard-known facts
- `@trezor/connect-web` is the maintained library for Trezor in browser. EIP-1193-compatible adapter exists.
- Trezor supports EVM signing for any chain; chain ID is part of the tx.
- WebUSB is Chromium-only. Firefox users need the Trezor Bridge native helper.

### Open questions
1. **Multi-admin.** If two admins both have a Trezor configured, do they both need to sign (m-of-n), or any one of them? Default: any one of them; m-of-n is out of scope here.
2. **Trezor model.** Trezor One vs Model T have different signing UX. We target both; the lib abstracts it.
3. **Fallback.** What if Trezor is unavailable when an urgent release is needed? Default: a "break-glass" hot-key path that admin can flip on for a 1-hour window, alarms blast Telegram.

### Scope
1. New module `frontend/src/web3/trezor/trezorConnector.ts` wrapping `@trezor/connect-web`.
2. Admin actions (release/refund/sweep) get a "Sign with Trezor" button that:
   - Hits backend `POST /api/admin/actions/build-tx` returning unsigned tx bytes.
   - Sends to Trezor for signing.
   - Submits signed tx via wagmi `sendTransaction`.
   - Calls `POST /api/admin/actions/confirm-tx` with the tx hash.
3. Backend supports both `confirmReleaseTx` flow (existing) and the new build-tx pattern.
4. Admin settings page to "register Trezor": stores the Trezor's address(es) so backend can reject signatures from unauthorized devices.
5. Audit log on every Trezor-signed action.

### Non-goals
- Multi-sig contracts (Safe etc.) — separate decision.
- Buyer-side Trezor (buyer already uses their own wallet via wagmi `injected()`).
- Mobile Trezor flow (desktop only for v1).

### Acceptance criteria
1. Admin can register a Trezor address; subsequent admin actions show "sign with Trezor" CTA.
2. End-to-end release of escrow: build → Trezor approves → tx broadcast → backend confirms.
3. If Trezor is unregistered or admin tries to sign with a different device, the backend rejects the confirm step.
4. Audit log entries include admin user, Trezor address, tx hash, action, before/after escrow state.
5. Break-glass hot-key path requires an explicit admin toggle, expires after 1h, fires a Telegram alarm.

---

## Shared dependencies / order-of-operations

- Task #8 (multichain) and Task #9 (confirmations) are independent and can land in parallel.
- Task #7 (ephemeral wallets) depends on Task #11 (Trezor) only for the sweep step — the address-generation half can ship first, sweep can land later with hot-key, then migrate to Trezor when #11 is done.
- Task #10 (AML) depends on nothing from the other four. It plugs into the existing Transaction Safety Provider.
- Task #11 (Trezor) is self-contained.

Tasks were sized for one experienced contributor to take any single one end-to-end without needing the others to land first. The integration glue (UI placement, navigation, telemetry) is left for the maintainer.