docs: sync from backend 19f7eb9, frontend 60ee6fb — Task #10 AML screening
This commit is contained in:
Siavash Sameni
@@ -8,15 +8,15 @@ This document captures payment-flow issues that surfaced while integrating Reque
|
||||
|
||||
---
|
||||
|
||||
## 1. RN does not support Rabby — show-stopper for our wallet user base
|
||||
## 1. RN hosted UI does not support Rabby -- mitigated by Amanat in-house checkout
|
||||
|
||||
### Problem
|
||||
|
||||
RN's hosted payment page (the `pay.request.network/?token=…` UI returned by `/v2/secure-payments`) does not detect / connect to Rabby. A meaningful slice of Amanat's user base pays from Rabby. Sending them to a screen that won't even let them connect is a hard block.
|
||||
|
||||
### Mitigation (designed, not yet implemented)
|
||||
### Mitigation (implemented core path)
|
||||
|
||||
Skip the RN-hosted UI. We already call `/v2/secure-payments` and receive a `securePaymentUrl`, but we also receive `requestIds` and `token` — that's everything we need to know what the merchant request is. Behind that token there is a contract on the destination chain that anyone can fulfill.
|
||||
Skip the RN-hosted UI. Amanat still calls `/v2/secure-payments`, stores the Request Network identifiers, and exposes an in-house checkout block. The frontend builds the same RN-compatible on-chain action from the buyer's wallet, so Rabby/MetaMask users stay inside the Amanat flow.
|
||||
|
||||
So the new flow becomes:
|
||||
|
||||
@@ -32,10 +32,11 @@ So the new flow becomes:
|
||||
- RN's value to us at that point is the *settlement bookkeeping*, not the UI. We use them as "did this address receive the expected amount before timeout?" — the wallet UX stays in our control.
|
||||
- Buyer never sees a third-party brand mid-checkout, which is a UX win regardless of Rabby.
|
||||
|
||||
### Open
|
||||
### Remaining work
|
||||
|
||||
- Need to confirm RN settles a payment that arrives from a *proxy transaction we built*, not from their hosted page. The 2026-05-28 probe confirms RN webhook delivery to Amanat, but the app returned `404`; repeat the probe only after the confirmation repair is deployed.
|
||||
- Need a fallback for the buyer who insists on the RN hosted UI (some users will already have the link copied). Keep `securePaymentUrl` exposed as a "advanced / pay with RN" link.
|
||||
- Keep the RN hosted URL exposed as an escape hatch.
|
||||
- Continue hardening timer/persistence/telemetry around the in-house checkout.
|
||||
- Treat durable webhook ingress as a production gate, because the main Express app should not be the only landing zone for callback evidence.
|
||||
|
||||
---
|
||||
|
||||
@@ -51,7 +52,7 @@ The visible costs:
|
||||
- Or seller gets less than they expected (worst — they'll dispute).
|
||||
- Plus settlement latency goes from seconds to minutes-hours depending on the bridge.
|
||||
|
||||
### Mitigation (designed)
|
||||
### Mitigation (partially implemented)
|
||||
|
||||
Take the chain choice away from RN's UI and bring it into ours, gated by what the *seller* will accept.
|
||||
|
||||
@@ -62,11 +63,11 @@ Two-step UX:
|
||||
|
||||
### Side benefit
|
||||
|
||||
This composes cleanly with #1 (own checkout screen): we already have to render the wallet picker, so adding a chain selector before the wallet step costs almost nothing.
|
||||
This composes cleanly with #1 (own checkout screen): we already render the wallet picker, so seller-accepted chain selection can happen before wallet connection. The chain/token registry and admin networks page exist; seller-side accepted-chain policy remains a separate product/data-model task.
|
||||
|
||||
### Open
|
||||
|
||||
- We need a per-seller config table for accepted chains. Today the env-level `REQUEST_NETWORK_MERCHANT_REFERENCE` hard-codes a single chain (`bsc`). Needs to become per-seller, per-offer.
|
||||
- We need a per-seller/per-offer config table for accepted chains. Today the global merchant reference is still the fallback, while derived destination work handles recipient variation.
|
||||
- Does RN's API support creating a secure-payment that *rejects* off-chain payments rather than auto-bridging? Or do we have to enforce this purely on our side by never offering the cross-chain option to the buyer? **Confirm with RN docs/support.**
|
||||
|
||||
---
|
||||
@@ -83,7 +84,7 @@ Today the entire escrow stack receives funds into one (or a handful of) wallets
|
||||
|
||||
This is a show-stopper for going live at scale. Same class of issue we already considered around SHKeeper.
|
||||
|
||||
### Mitigation (designed; needs RN feasibility check)
|
||||
### Mitigation (implemented core path; operational probe pending)
|
||||
|
||||
Per-`(buyer, merchant)`-pair ephemeral wallets. Each new escrow gets a freshly-generated address that only ever receives that one transaction. If those funds turn out to be dirty:
|
||||
|
||||
@@ -93,23 +94,23 @@ Per-`(buyer, merchant)`-pair ephemeral wallets. Each new escrow gets a freshly-g
|
||||
|
||||
### What this requires (architectural work)
|
||||
|
||||
1. **Wallet abstraction layer** — service that on demand generates a fresh address (HD wallet derivation from a master seed kept in a hardware module / KMS) and returns it to the payment-intent flow.
|
||||
2. **Address book / registry** — maps `(paymentId, chainId)` → derived address. Persists derivation path + sequence number so we can reproduce keys for sweeps later.
|
||||
3. **Sweep job** — once a payment is confirmed AND has passed an on-chain screening check (Chainalysis API or similar), sweep the ephemeral wallet to the main treasury. If screening fails, the ephemeral wallet is quarantined and the payment refunded out of band.
|
||||
4. **Key custody policy** — these are still our funds in custody briefly; need clear policy on who can sign sweeps, hot-key vs cold-key separation.
|
||||
1. **Wallet abstraction layer** -- implemented in `backend/src/services/payment/wallets/derivedDestinations.ts` using xpub-only derivation.
|
||||
2. **Address book / registry** -- implemented in `DerivedDestination`, keyed by `(buyerId, sellerOfferId, chainId)`.
|
||||
3. **Sweep job** -- implemented with build-only/hot-key signer abstraction; production must keep build-only and move execution to Trezor/Safe.
|
||||
4. **Key custody policy** -- still the important missing operational layer. See [[PRD - Decentralized Custody and Smart-Contract Escrow Roadmap]].
|
||||
|
||||
### Critical open question
|
||||
|
||||
**Does RN support creating a secure-payment with a destination wallet we specify per-request, rather than a static merchant reference?** If yes, this is straightforward — we generate a wallet, register it as the destination for one specific `/v2/secure-payments` call, done. If no (RN only allows pre-registered destinations), we have to either:
|
||||
**Does RN support creating a secure-payment with a destination wallet we specify per request at production volume, rather than a static merchant reference?** The backend/frontend support the shape, but the live divergent-destination probe remains the operational proof point. If RN cannot support this reliably, fallback options are:
|
||||
|
||||
- Pre-register a large pool of addresses with RN and rotate through them, or
|
||||
- Bypass RN's destination model and go full self-host (which is most of issue #4).
|
||||
|
||||
**Action: confirm with RN support whether per-request destinations are supported on the same API key.**
|
||||
**Action: run the two-paid-intent divergent-destination probe and confirm with RN support whether this usage is supported on the same API key at expected volume.**
|
||||
|
||||
---
|
||||
|
||||
## 4. RN reduced to a notification service — viable, but not yet validated
|
||||
## 4. RN reduced to a notification service -- viable, partially validated
|
||||
|
||||
### Problem statement
|
||||
|
||||
@@ -131,19 +132,19 @@ Which is a *notification* primitive, not a payment platform. We'd be paying for
|
||||
- We're outsourcing the *one thing* RN is good at (settlement) and keeping the parts they don't help with (UX, wallet generation, compliance).
|
||||
- Alternative: do the same with our own chain watcher (Alchemy webhooks / Tenderly / Goldsky) and skip RN entirely.
|
||||
|
||||
### What needs testing before we commit
|
||||
### What still needs testing before we commit at scale
|
||||
|
||||
1. **Webhook reliability at our volume.** What's RN's SLA for "address received funds → webhook delivered"? P50? P99?
|
||||
2. **Custom destination support.** See open question in #3.
|
||||
3. **Per-API-key rate limits.** If we end up calling `/v2/secure-payments` once per escrow, do we hit ceilings?
|
||||
4. **Pricing for the notification-only flow** — is there a tier, or is it the same as the full-stack price?
|
||||
5. **What happens when the payment arrives from a transaction WE built** (not theirs)? Does the webhook still fire? Is settlement still recognized? — this is the load-bearing test for the whole strategy.
|
||||
5. **What happens when the payment arrives from a transaction WE built** (not theirs)? The 2026-05-28 in-house checkout probe proved the basic path for a real BSC USDC payment; this still needs repeated paid probes across tokens/chains and webhook durability coverage.
|
||||
|
||||
Until #5 is confirmed, the rest is just paper architecture.
|
||||
Until webhook durability, destination divergence, pricing, and SLA are confirmed, treat RN as useful but not irreplaceable infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## 5. Webhook durability and transaction safety are P0 before more paid probes
|
||||
## 5. Webhook durability remains P0 before production rollout
|
||||
|
||||
### What the 2026-05-28 probe proved
|
||||
|
||||
@@ -153,12 +154,12 @@ The dev test transaction `0x3a23febd9abd43d7e0851c1ea86c4ceaf08c11098852cb0425fa
|
||||
|
||||
Do not treat the main Express app as the only webhook landing zone, and do not treat a signed provider callback as enough to credit escrow.
|
||||
|
||||
### Required mitigation
|
||||
### Required mitigation and status
|
||||
|
||||
1. **Correlation repair:** lookup Request Network payments by every persisted reference shape, including `providerPaymentId`, top-level RN request id/payment reference, and nested raw RN data.
|
||||
2. **Callback repair:** payment callback polling must unwrap the backend response shape, clear polling after terminal states, and avoid a 3-second loop that self-rate-limits.
|
||||
3. **Transaction Safety Provider:** completion must pass configured safety checks: transaction hash present, minimum confirmations, token/recipient/amount transfer match, and future AML/sanctions provider approval.
|
||||
4. **Durable ingress:** put a Cloudflare Worker in front of RN webhooks. The Worker stores raw delivery evidence durably, forwards to the backend, and supports replay. It is not the trust oracle; the backend still verifies, deduplicates, and applies safety/ledger transitions.
|
||||
1. **Correlation repair:** implemented for the in-house checkout path; keep smoke coverage around every persisted RN reference shape.
|
||||
2. **Callback repair:** implemented enough for the successful paid dev probe; keep polling/backoff hardening on the checkout roadmap.
|
||||
3. **Transaction Safety Provider:** implemented for tx hash, confirmations, transfer match, and AML placeholder; real AML provider remains Task #10.
|
||||
4. **Durable ingress:** not started. Put a Cloudflare Worker in front of RN webhooks. The Worker stores raw delivery evidence durably, forwards to the backend, and supports replay. It is not the trust oracle; the backend still verifies, deduplicates, and applies safety/ledger transitions.
|
||||
|
||||
---
|
||||
|
||||
@@ -166,13 +167,13 @@ Do not treat the main Express app as the only webhook landing zone, and do not t
|
||||
|
||||
| # | Action | Blocker / Owner |
|
||||
|---|---|---|
|
||||
| 1 | Deploy confirmation repair and repeat the dev payment probe | Backend payments |
|
||||
| 2 | Test: `/v2/secure-payments` accepts a per-request destination wallet | Backend payments |
|
||||
| 1 | Run the live divergent-destination probe: two paid intents to two derived addresses | Backend payments |
|
||||
| 2 | Confirm `/v2/secure-payments` per-request destination usage with RN support and pricing | Product / RN account manager |
|
||||
| 3 | Confirm RN doesn't auto-bridge when buyer pays on the destination chain natively | Backend payments |
|
||||
| 4 | Get RN's webhook P99 latency + delivery guarantees in writing | Product / RN account manager |
|
||||
| 5 | Spec the wallet-abstraction layer (HD derivation + sweep job + key policy) | Backend, before going live |
|
||||
| 5 | Move sweep/release/refund custody to Trezor/Safe, not backend hot keys | Backend + ops |
|
||||
| 6 | Spec the seller-side accepted-chains config | Backend + frontend |
|
||||
| 7 | Add Cloudflare Worker durable webhook ingress to the roadmap | Backend / platform |
|
||||
| 7 | Build Cloudflare Worker durable webhook ingress + replay | Backend / platform |
|
||||
| 8 | Add AML/sanctions adapter behind Transaction Safety Provider | Compliance / backend |
|
||||
|
||||
Actions 1–4 are *information-gathering* and should run in parallel before any more architectural commitment to RN. Actions 5–6 are blocked on 1–3 confirming RN can actually support this shape.
|
||||
Actions 1-4 are information-gathering and should run in parallel before deeper RN commitment. Actions 5, 7, and 8 are production-safety work regardless of whether Amanat keeps RN long-term or replaces it with a direct chain watcher.
|
||||
|
||||
Reference in New Issue
Block a user