nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: sync vault with Task #7 backend + admin UI shipping (2.6.42)

Browse Source 
- Handoff doc: mark Task #7 in-progress with what landed (backend
  modules, admin UI), what remains (cart-aware buyer UX, unit tests,
  live RN divergent-destination probe, optional auto-start cron).
  Promote the followups table from 'depends on' to 'status'.
- Environment Variables: add DERIVED_DESTINATION_* block with KMS /
  Trezor production guidance.

Code is on backend commit c98b3d7 / frontend commit 82d9a70, both
on integrate-main-into-development.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
2026-05-28 16:35:18 +04:00
parent 31dd475b73
commit d80892dbaa
2 changed files with 51 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
07 - Development/Environment Variables.md
View File

@@ -299,8 +299,22 @@ AUTO_SEED_ON_START=true
ESCROW_WALLET_ADDRESS=0xa3049825c0785095EEd5E7976E0E539466c84044 ESCROW_WALLET_ADDRESS=0xa3049825c0785095EEd5E7976E0E539466c84044
ADMIN_PAYOUT_WALLET_ADDRESS= 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 # OAuth
GOOGLE_CLIENT_ID= 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. > [!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.

44
08 - Operations/Handoff - Request Network In-House Checkout - 2026-05-28.md
View File

@@ -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: 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 | | # | Task | Priority | Status |
|---|---------------------------------------------------------------|----------|------------| |---|---------------------------------------------------------------|----------|--------|
| 7 | Per-(buyer, sellerOffer) ephemeral RN destination wallets | high | (sweep step soft-depends on #11) | | 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 | — | | 8 | Multichain RN proxy registry + USDC/USDT support | high | ⏳ Not started |
| 9 | Per-chain confirmation thresholds + admin UI | medium | — | | 9 | Per-chain confirmation thresholds + admin UI | medium | ⏳ Not started |
| 10 | Optional AML screening on incoming payments (seller-paid) | medium | — | | 10 | Optional AML screening on incoming payments (seller-paid) | medium | ⏳ Not started |
| 11 | Trezor signing for admin actions (release/refund/sweep) | high | — | | 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).