diff --git a/03 - API Reference/Payment API.md b/03 - API Reference/Payment API.md index 525099b..f6df2ed 100644 --- a/03 - API Reference/Payment API.md +++ b/03 - API Reference/Payment API.md @@ -365,6 +365,90 @@ Payouts are SHKeeper-side outbound transfers (admin pays the seller from a hot w ``` **Response 200:** `{ success, data: { /* payout receipt */ } }` +## Derived Destinations + +These endpoints manage per-(buyer, sellerOffer) ephemeral payment addresses. + +| Method | Route | Auth | Purpose | +|--------|-------|------|---------| +| `GET` | `/api/payment/derived-destinations` | Admin | List destinations with filters/pagination | +| `POST` | `/api/payment/derived-destinations/sweep` | Admin | Sweep **all** active destinations | +| `POST` | `/api/payment/derived-destinations/:id/sweep` | Admin | Sweep **one** destination | +| `POST` | `/api/payment/derived-destinations/:id/balance` | Admin | Refresh on-chain balance for one destination | +| `GET` | `/api/payment/derived-destinations/config/health` | Admin | Verify xpub and sweep signer config | +| `POST` | `/api/payment/derived-destinations/cron/start` | Admin | Start the sweep cron | +| `POST` | `/api/payment/derived-destinations/cron/stop` | Admin | Stop the sweep cron | +| `GET` | `/api/payment/derived-destinations/cron/status` | Admin | Check if sweep cron is running | + +### `GET /api/payment/derived-destinations` + +Query params: `buyerId`, `sellerOfferId`, `status` (`active|swept`), `address`, `chainId`, `page`, `limit`. + +**Response 200:** +```json +{ + "success": true, + "data": { + "destinations": [ + { + "_id": "...", + "buyerId": "...", + "sellerOfferId": "...", + "address": "0x...", + "derivationPath": "m/44'/60'/0'/0/5", + "derivationIndex": 5, + "chainId": 56, + "status": "active", + "balance": "1000000000", + "sweepCount": 0, + "totalSwept": "0", + "createdAt": "..." + } + ], + "pagination": { "page": 1, "limit": 20, "total": 42 } + } +} +``` + +### `POST /api/payment/derived-destinations/sweep` + +Body: `{ chainId?: number, tokenSymbol?: string, minSweepAmount?: string }` — all optional. + +**Response 200:** `{ success: true, data: { results: SweepResult[] } }` + +Each `SweepResult`: +```ts +{ + destinationId: string; + address: string; + status: 'success' | 'error' | 'skipped'; + txHash?: string; + amount?: string; + error?: string; +} +``` + +### `POST /api/payment/derived-destinations/:id/sweep` + +Same result shape as above, but for a single destination. + +### `GET /api/payment/derived-destinations/config/health` + +**Response 200:** +```json +{ + "success": true, + "data": { + "xpubValid": true, + "xpubFingerprint": "0xabcd...", + "signerType": "build-only", + "signerHealthy": true, + "chainId": 56, + "masterWallet": "0x..." + } +} +``` + ## Status model [[Payment]] uses the statuses below across all providers: diff --git a/07 - Development/Environment Variables.md b/07 - Development/Environment Variables.md index fbc8e73..81dd7e1 100644 --- a/07 - Development/Environment Variables.md +++ b/07 - Development/Environment Variables.md @@ -310,6 +310,7 @@ DERIVED_DESTINATION_CHAIN_ID=56 DERIVED_DESTINATION_SWEEP_SIGNER=build-only DERIVED_DESTINATION_MIN_SWEEP_AMOUNT=0 DERIVED_DESTINATION_SWEEP_INTERVAL_MS=300000 +DERIVED_DESTINATION_SWEEP_AUTOSTART=true # OAuth GOOGLE_CLIENT_ID= diff --git a/09 - Audits/Activity Log.md b/09 - Audits/Activity Log.md index 9dbd3de..c225fbe 100644 --- a/09 - Audits/Activity Log.md +++ b/09 - Audits/Activity Log.md @@ -11,6 +11,18 @@ entries on top. Maintained by agents per the rule in `../AGENTS.md`. --- +### 2026-05-28 — backend@faf2221, frontend@022ecb6 — Task #7 derived destinations: sweep autostart, recordSweep fix, multi-seller checkout UX + +**Commits:** backend `faf2221` (2.6.42 → 2.6.43), frontend `022ecb6` (2.6.42 → 2.6.43) +**Touched:** +- Backend: `src/app.ts`, `src/models/DerivedDestination.ts`, `src/models/Payment.ts`, `src/services/payment/requestNetwork/requestNetworkPayInService.ts`, `src/services/payment/wallets/derivedDestinations.ts`, `.env.example` +- Frontend: `src/sections/payment/checkout/rn-in-house-checkout-view.tsx`, `src/sections/request-template/request-template-checkout-payment.tsx`, `src/web3/components/multi-seller-provider-payment.tsx`, `src/sections/payment/checkout/rn-multi-checkout-view.tsx`, `src/app/checkout/request-network/multi/page.tsx` +**Why:** PRD items D/E/F + frontend cart-aware checkout (A). Auto-start sweep cron on boot; fix `recordSweep` to `$inc` totalSwept instead of `$setOnInsert`; widen Payment unique index to include `sellerOfferId` for multi-seller carts; add multi-seller checkout wrapper and wire into template + request flows. +**Verification:** Pushed to `integrate-main-into-development` on both repos — Woodpecker builds pending. +**Linked docs updated:** [[03 - API Reference/Payment API]] (derived-destination endpoints) + +--- + ### 2026-05-28 — backend@e46be98, frontend@af77b3c — add nick-doc sync rule + version bumps **Commits:** backend `e46be98` (2.6.24 → 2.6.25), frontend `af77b3c` (2.6.25 → 2.6.26)