docs: sync from backend 19f7eb9, frontend 60ee6fb — Task #10 AML screening

00 - Overview/System Overview.md

@@ -16,7 +16,7 @@ Amn is a **two-repo system**:
 - **Frontend** (`/Users/mojtabaheidari/code/frontend`) — a Next.js 16 App Router application that serves the marketplace UI, the admin dashboard, the public blog, and the user-facing Web3 wallet flow.
 - **Backend** (`/Users/mojtabaheidari/code/backend`) — an Express 5 + TypeScript API server that owns all business logic, persists to MongoDB, caches in Redis, and brokers all external integrations.
 
-The two repos are deployable independently. They communicate over **HTTPS (REST)** for stateful actions and over **WebSocket (Socket.IO)** for live updates. The frontend never talks directly to MongoDB, Redis, SHKeeper, or OpenAI — every external interaction is mediated by the backend so that secrets stay on the server.
+The two repos are deployable independently. They communicate over **HTTPS (REST)** for stateful actions and over **WebSocket (Socket.IO)** for live updates. The frontend never talks directly to MongoDB, Redis, Request Network API keys, OpenAI, or admin custody secrets -- every sensitive external interaction is mediated by the backend so that secrets stay on the server.
 
 ## System map
 
@@ -41,7 +41,7 @@ flowchart TB
         Auth["Auth service<br/>JWT + Passkey + Google + Telegram"]
         Market["Marketplace service<br/>Requests, Offers, Templates"]
         ChatSvc["Chat service"]
-        PaySvc["Payment service<br/>SHKeeper + Request Network + ledger"]
+        PaySvc["Payment service<br/>Request Network + ledger + custody controls"]
         TelegramSvc["Telegram service<br/>bot + Mini App + notifications"]
         Disp["Dispute service"]
         Points["Points / Referrals"]
@@ -58,8 +58,6 @@ flowchart TB
     end
 
     subgraph External["External services"]
-        SHK["SHKeeper<br/>crypto invoicing"]
-        DePay["DePay widget"]
         Chain["EVM chains<br/>BSC / ETH / Polygon"]
         SMTP["SMTP<br/>(nodemailer)"]
         OpenAI["OpenAI API"]
@@ -68,6 +66,7 @@ flowchart TB
         Alchemy["Alchemy RPC"]
         TelegramAPI["Telegram Bot API<br/>+ Mini App"]
         ReqNet["Request Network<br/>pay-in / webhooks"]
+        CFWorker["Durable webhook ingress<br/>(roadmap)"]
     end
 
     Browser --> SSR
@@ -88,13 +87,10 @@ flowchart TB
     Auth & PaySvc & Notif --> RedisDB
     Files --> Disk
 
-    PaySvc <--> SHK
-    SHK -.webhook.-> PaySvc
     PaySvc <--> ReqNet
-    ReqNet -.webhook.-> PaySvc
+    ReqNet -.webhook.-> CFWorker
+    CFWorker -.forward/replay.-> PaySvc
     PaySvc --> Chain
-    Wagmi --> DePay
-    DePay --> Chain
     PaySvc -.tx fetch.-> Alchemy
 
     TelegramSvc <--> TelegramAPI
@@ -130,16 +126,17 @@ The heart of the platform. Three first-class models drive it:
 
 Services live in `backend/src/services/marketplace/` and are exposed through `/api/marketplace/*`. The frontend uses a mix of React Query (`@tanstack/react-query`) and SWR for data fetching, with mutations gated through the actions layer in `frontend/src/actions/`.
 
-### Payments — [[Payments Overview]] / [[SHKeeper Integration]]
+### Payments -- Request Network, Ledger, And Custody Controls
 
-Payments are where Amn is most distinctive. The backend supports **four payment surfaces** routed through a common `Payment` model (`backend/src/models/Payment.ts`) via a provider-neutral adapter layer (`backend/src/services/payment/adapters/`):
+Payments are where Amn is most distinctive. The live backend has converged on **Request Network** as the primary provider through a common `Payment` model (`backend/src/models/Payment.ts`) and provider-neutral adapter layer (`backend/src/services/payment/adapters/`):
 
-- **SHKeeper** — `/api/payment/shkeeper`. Issues a fresh wallet address per invoice, polls / webhooks for payment confirmation, and runs through `PaymentCoordinator` to avoid race conditions. Health is monitored in the background (`shkeeperHealthCheck.ts`).
-- **Request Network** — `/api/payment/request-network`. Creates on-chain payment requests via the Request Network protocol, generates Secure Payment Page URLs for the buyer, and receives real-time payment status via signed webhooks (`x-request-network-signature`). Pay-in service: `requestNetworkPayInService.ts`; reconciliation: `requestNetworkReconciliationService.ts`.
-- **Decentralized (Wagmi + DePay)** — `/api/payment/decentralized`. The user signs and sends the transfer from their own wallet; the backend verifies on-chain via `blockchainTxFetcher.ts` and the Alchemy SDK.
-- **Payout** — `/api/payment/shkeeper/payout`. Admin-triggered release of escrow funds to the seller's wallet once delivery is confirmed.
+- **Request Network pay-in** -- `/api/payment/request-network`. Creates requests, exposes the Amanat in-house checkout block, and receives signed webhooks (`x-request-network-signature`). Pay-in service: `requestNetworkPayInService.ts`; reconciliation: `requestNetworkReconciliationService.ts`.
+- **In-house wallet checkout** -- buyer signs the RN-compatible `approve` + `transferFromWithReferenceAndFee` flow from their own wallet, so Rabby/MetaMask wallet UX stays inside Amanat.
+- **Derived destination wallets** -- `/api/payment/derived-destinations` admin endpoints manage per-`(buyer, sellerOffer, chainId)` receiving addresses, sweep status, and config health.
+- **Funds ledger** -- `backend/src/services/payment/ledger/` tracks payment detection, holds, releases, refunds, fees, and adjustments independently of provider metadata.
+- **Release/refund orchestration** -- `/api/payment/:id/(release|refund)` builds instructions; `/confirm` records confirmed transaction hashes. Optional Trezor enforcement gates confirmation when `TREZOR_SAFEKEEPING_REQUIRED=true`.
 
-All surfaces converge on the same `Payment` record (with `direction: 'in' | 'out' | 'refund'`) and share the internal **funds ledger** (`backend/src/services/payment/ledger/`) which tracks available / held / releasable amounts independently of the provider. **Pending payments are auto-cleaned** by a background timer started in `app.ts`.
+Historical SHKeeper and DePay docs remain in the vault for migration context, but the current backend tree no longer has `backend/src/services/payment/shkeeper/`. The current strategic path is in [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]].
 
 ### Real-time chat — [[Chat System]]
 
@@ -164,9 +161,10 @@ Push and SMS are tracked as **planned** in `backend/TODO.md`.
 
 ### Disputes — [[Dispute System]]
 
-When a deal goes wrong (see [[Glossary#Dispute]]), either party can open a dispute. The backend would create a **three-way chat** between buyer, seller, and admin, open a `Dispute` document with a structured `timeline[]` and `evidence[]`, and assign the dispute to an admin via `assignAdmin()`. Resolution can be `refund | replacement | compensation | warning_seller | ban_seller | no_action` and is recorded on the dispute itself.
-> [!warning] Not implemented
-> `backend/src/services/dispute/DisputeService.ts` does not exist as of 2026-05-24.
+When a deal goes wrong (see [[Glossary#Dispute]]), either party can open a dispute. The backend creates a **three-way chat** between buyer, seller, and admin, opens a `Dispute` document with a structured `timeline[]` and `evidence[]`, and can assign the dispute to an admin via `assignAdmin()`. Resolution can be `refund | replacement | compensation | warning_seller | ban_seller | no_action` in the current Mongoose model.
+
+> [!note] State alignment gap
+> The dispute module exists now, but its model still uses the legacy `pending | in_progress | resolved | ...` enum. [[Funds Ledger and Escrow State Machine Specification]] defines the canonical future enum and financial side effects.
 
 ### Points & referrals — [[Points System]]
 
@@ -191,9 +189,10 @@ OpenAI (model configurable per call) is exposed through `/api/ai/*`. The current
 - locks used by `PaymentCoordinator` to serialise status transitions
 - rate-limit counters (currently disabled in code but plumbed in)
 
-**Background workers** run inside the Express process for now — no separate worker tier. Notable timers:
+**Background workers** run inside the Express process for now -- no separate worker tier. Notable timers:
 - `startPendingPaymentsCleanup()` — sweeps stale unpaid invoices
-- `startShkeeperHealthMonitor()` — pings the SHKeeper instance and surfaces alerts
+- optional derived-destination sweep cron — sweeps eligible per-payment receiving addresses when configured
+- Request Network reconciliation — enabled via provider config when the rollout requires fallback status repair
 - Auto-seed logic on startup (gated by `NODE_ENV` and `AUTO_SEED_ON_START`)
 
 ## Request lifecycle (the happy path)
@@ -203,9 +202,10 @@ OpenAI (model configurable per call) is exposed through `/api/ai/*`. The current
 > 2. Buyer creates a [[Purchase Request]] → `POST /api/marketplace/requests`. The request lands in `pending`/`active`. Sellers in the matching category receive a Socket.IO notification.
 > 3. Seller views the request, opens [[Seller Offer]] modal, submits price + delivery time → `POST /api/marketplace/offers`. Buyer sees the offer arrive live.
 > 4. Buyer accepts an offer → request moves to `payment`. UI opens the payment selector.
-> 5. Buyer picks **SHKeeper** → backend creates a SHKeeper invoice, returns a wallet address + QR code. Buyer pays. SHKeeper webhook hits `/api/payment/shkeeper/webhook`; `PaymentCoordinator` flips `Payment.status = paid` and `PurchaseRequest.status = processing`.
-> 6. Seller ships. Buyer confirms delivery (or it auto-confirms after the SLA window). Admin triggers (or schedules) a **payout** → SHKeeper releases USDT to the seller's wallet.
-> 7. Both parties leave reviews. Points are awarded. The deal is closed.
+> 5. Buyer picks **Request Network** -> backend creates a Payment and RN intent, returns an in-house checkout block, and the buyer signs the on-chain payment from their wallet.
+> 6. Request Network webhook/reconciliation plus the Transaction Safety Provider confirm tx hash, recipient, token, amount, and confirmations before the backend marks escrow funded.
+> 7. Seller ships. Buyer confirms delivery (or an admin resolves the order/dispute). Admin/custody owners execute release/refund through the release/refund instruction flow.
+> 8. Both parties leave reviews. Points are awarded. The deal is closed.
 >
 > If the buyer disputes the delivery, jump to step 7 of the [[Dispute Flow]] instead.