docs: ship in-house RN checkout, scope 5 follow-up tasks (#7-11)
In-house Request Network checkout went fully end-to-end on dev today. A real 0.01 USDC payment flowed through wallet connect -> approve -> ERC20FeeProxy.transferFromWithReferenceAndFee -> RN webhook -> TransactionSafetyProvider -> Payment.status=completed -> page success state. Tx 0x494c77a29161b5100d8e0b1ac675f1822955d0bb3633ecdbfafb886f84f2f320. Docs: - New PRD: Wallet, Multichain, Confirmations, AML, Trezor (5 follow-ups, each sized for an independent contributor) - Updated PRD: Request Network In-House Checkout (phases 0..3 done, phase 4 partial, phases 5-6 not started) - Updated handoff: deployed versions, what is working end-to-end, follow-up tasks index Taskmaster: 5 new top-level tasks (#7..#11) covering ephemeral destination wallets, multichain proxy registry + USDC/USDT, runtime confirmation thresholds, optional seller-paid AML screening, and Trezor signing for admin actions. Tasks are scoped fine-grained so each is independent enough for kimi to pick up. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
@@ -1,10 +1,10 @@
|
||||
# Request Network Integration — Constraints and Design Implications
|
||||
|
||||
**Date:** 2026-05-27
|
||||
**Status:** Active concerns; mitigations partially designed, partially blocked on RN clarifications
|
||||
**Status:** Active concerns; 2026-05-28 probe confirmed RN webhook delivery but exposed Amanat confirmation handling gaps
|
||||
**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.
|
||||
This document captures 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -24,8 +24,8 @@ So the new flow becomes:
|
||||
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.
|
||||
- Builds the two RN-compatible transactions client-side: token `approve(proxy, amount)`, then `transferFromWithReferenceAndFee(...)` on RN's ERC20FeeProxy.
|
||||
3. RN's webhook tells us when the proxy event lands; Request Network search/status APIs remain the polling fallback.
|
||||
|
||||
### Why this is acceptable
|
||||
|
||||
@@ -34,7 +34,7 @@ So the new flow becomes:
|
||||
|
||||
### 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 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.
|
||||
|
||||
---
|
||||
@@ -143,15 +143,36 @@ Until #5 is confirmed, the rest is just paper architecture.
|
||||
|
||||
---
|
||||
|
||||
## 5. Webhook durability and transaction safety are P0 before more paid probes
|
||||
|
||||
### What the 2026-05-28 probe proved
|
||||
|
||||
The dev test transaction `0x3a23febd9abd43d7e0851c1ea86c4ceaf08c11098852cb0425fa074e9c88350b` succeeded on BSC. RN then called `POST /api/payment/request-network/webhook` on `dev.amn.gg` four times from `34.34.233.192`. Amanat returned `404` because backend correlation looked up the wrong reference shape; the `Payment` record held RN request/payment-reference values that the handler did not search.
|
||||
|
||||
### Design implication
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting next actions
|
||||
|
||||
| # | Action | Blocker / Owner |
|
||||
|---|---|---|
|
||||
| 1 | Test: payment via wallet-built transfer triggers RN webhook | Backend payments |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 7 | Add Cloudflare Worker durable webhook ingress to the roadmap | 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.
|
||||
|
||||
Reference in New Issue
Block a user