# Request Network Integration — Constraints and Design Implications **Date:** 2026-05-27 **Status:** Active concerns; mitigations partially designed, partially blocked on RN clarifications **Owners:** Backend payments (Amanat), product This document captures four payment-flow issues that surfaced while integrating Request Network (RN) into the Amanat escrow stack. Each one is either a show-stopper or a non-trivial architectural constraint. Listed in priority order. --- ## 1. RN does not support Rabby — show-stopper for our wallet user base ### 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) 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. So the new flow becomes: 1. Backend calls RN `/v2/secure-payments` (same as today) and stores the `requestIds[0]` + destination wallet + amount + token on our `Payment` doc. 2. **We render our own checkout screen** that: - Shows the buyer the wallet address to pay to (the destination resolved from the merchant reference / chain / token). - Lets the buyer connect *any* wallet — Rabby, MetaMask, OKX, Phantom-bridged, WalletConnect. - Builds the transfer transaction client-side (standard ERC-20 transfer) and asks the wallet to sign. 3. RN's webhook (`/v2/request/{id}`-style polling fallback) tells us when the payment lands. ### Why this is acceptable - 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 - Need to confirm RN actually settles a payment that arrives from a *transaction we built*, not from their hosted page. Their pricing/fees may be tied to going through their UI. **Test required** before committing to this path. - 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. --- ## 2. RN's multi-chain routing forces an expensive LiFi bridge ### Problem When we configure a destination route (e.g. BSC + USDC), RN's hosted UI still lets the buyer pick *any* chain where they hold funds (e.g. ARB). To honor that, RN routes the buyer's funds through **LiFi**, which charges bridging fees that **someone has to pay**, and it's not clearly disclosed who. The visible costs: - Buyer over-pays vs. nominal invoice amount (bad UX). - Or we eat the spread (bad margin). - 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) Take the chain choice away from RN's UI and bring it into ours, gated by what the *seller* will accept. Two-step UX: 1. **At offer creation (seller side):** seller specifies which chain(s) they accept payouts on. We persist this as `acceptedChains: [bsc, arb, base, …]` on the offer / merchant configuration. 2. **At checkout (buyer side, before any RN call):** we show the buyer the seller's accepted chains. Buyer picks one. *Then* we call RN with that exact chain pinned as the destination. No LiFi bridge — same-chain transfer. ### 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. ### 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. - 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.** --- ## 3. Sanctioned-funds risk — single escrow wallet poisons the entire platform ### Problem Today the entire escrow stack receives funds into one (or a handful of) wallets — `REQUEST_NETWORK_MERCHANT_REFERENCE` resolves to a single destination address. If a buyer pays with funds tied to a sanctioned source / mixer / known-bad address: - That destination wallet gets tagged non-compliant by Chainalysis / TRM / Elliptic. - Downstream exchanges and OTC desks won't accept transfers from it. - One bad buyer can effectively brick the entire platform's settlement layer. 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) 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: - Only that wallet is tainted. - We never sweep it into our main treasury (or sweep only after the payment passes screening). - Risk is **siloed to the individual escrow**, not platform-wide. ### 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. ### 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: - 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.** --- ## 4. RN reduced to a notification service — viable, but not yet validated ### Problem statement If we adopt #1 (own checkout UI), #2 (own chain selection), and #3 (own ephemeral wallets), RN's role in the flow collapses to: > "Tell me when wallet X receives Y tokens (or doesn't, before timeout)." Which is a *notification* primitive, not a payment platform. We'd be paying for a feature we're using maybe 5% of. ### Why this might still be worth it - We get RN's chain watchers + reorg handling + webhook reliability for free. - We don't have to run our own indexer on n chains. - Their screening (if they do any) is one more compliance layer. ### Why this might NOT be worth it - Pricing built around hosted-UI usage, not API-only. May not be cost-effective at API-only volumes. - 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 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. Until #5 is confirmed, the rest is just paper architecture. --- ## Cross-cutting next actions | # | Action | Blocker / Owner | |---|---|---| | 1 | Test: payment via wallet-built transfer triggers RN webhook | Backend payments | | 2 | Test: `/v2/secure-payments` accepts a per-request destination wallet | Backend payments | | 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 | | 6 | Spec the seller-side accepted-chains config | Backend + frontend | 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.