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
2026-05-28 15:50:24 +04:00
parent 37f946fc23
commit 0060b16912
69 changed files with 1513 additions and 147 deletions

View File

@@ -13,6 +13,8 @@ Request Network is request/payment-reference based. The platform creates a Reque
Primary recommendation: run a phased migration behind a provider adapter. Introduce Request Network for new pay-ins first using Secure Payment Pages, keep SHKeeper read-only for existing payments, then add funds ledger, release/refund gates, and Request Network payout flows.
2026-05-28 update: the first dev BSC payment probe confirmed Request Network did deliver webhooks to `dev.amn.gg`, but Amanat returned `404` because local correlation did not search all RN reference fields. The migration roadmap now needs two P0 additions before wider RN testing: a Transaction Safety Provider gate before escrow funding, and durable webhook ingress (Cloudflare Worker) so backend instability does not lose callback evidence.
## Source Findings
Current code:
@@ -219,6 +221,36 @@ Risk Assessment:
- Mitigation: raw-body middleware scoped to webhook route, event fixture tests, dead-letter queue/table, operator replay endpoint.
- Rollback: pause webhook processor and rely on manual/admin reconciliation for Request Network records.
## PRD 4A - Transaction Safety Provider and Durable Webhook Ingress
Priority: P0
Goal: prevent false-positive payment credit and prevent webhook loss when the main app is unstable.
Scope:
- Add a Transaction Safety Provider invoked by Request Network webhook and reconciliation paths before marking pay-ins completed.
- Require configurable checks: transaction hash present, minimum confirmations, on-chain transfer recipient/token/amount match, and AML/sanctions provider approval when configured.
- Store `metadata.transactionSafety`, last webhook payload, and safety-blocker reason for support/replay.
- Add a Cloudflare Worker as the public Request Network webhook target.
- Worker stores raw body, headers, delivery id, request id/payment reference, source IP, and timestamp in durable storage before forwarding to the backend.
- Provide replay by delivery id/time window/payment reference.
Acceptance Criteria:
- A signed RN webhook cannot set `Payment.status='completed'` unless safety checks approve.
- If tx hash is missing, webhook evidence is retained and the payment remains pending/safety-blocked rather than lost.
- Reconciliation uses the same safety gate as webhook processing.
- Unsigned/test callbacks are rejected unless explicit test mode is enabled.
- Backend outage still leaves a durable webhook record that an operator can replay.
Risk Assessment:
- Impact: Very High. This controls when escrow is credited.
- Likelihood: High. The 2026-05-28 probe already produced a dropped webhook.
- Main risks: accidentally blocking legitimate payments while tx hash/source evidence is missing, or accidentally trusting the Worker as the payment authority.
- Mitigation: safety decisions are explicit (`approved`, `pending`, `rejected`, `skipped`), backend remains the trust boundary, and operators can replay stored deliveries after fixes deploy.
## PRD 5 - Release, Refund, and Payout Orchestration
Priority: P1
@@ -313,11 +345,13 @@ Risk Assessment:
2. Add funds ledger models/services and dry-run backfill report.
3. Implement Request Network secure pay-in flow behind feature flag.
4. Implement signed webhook receiver and reconciliation job.
5. Enable Request Network for limited new checkout cohort.
6. Add release/refund orchestration using ledger gates.
7. Migrate admin/frontend views.
8. Backfill legacy records.
9. Decommission SHKeeper once no active records depend on it.
5. Add Transaction Safety Provider to webhook and reconciliation completion paths.
6. Add durable Request Network webhook ingress, preferably Cloudflare Worker + queue/storage + replay.
7. Enable Request Network for limited new checkout cohort.
8. Add release/refund orchestration using ledger gates.
9. Migrate admin/frontend views.
10. Backfill legacy records.
11. Decommission SHKeeper once no active records depend on it.
## Open Decisions
@@ -326,8 +360,9 @@ Risk Assessment:
- Which chains/currencies are required for launch: BSC USDT parity with today, or Request Network supported stablecoin routes first?
- Should platform fee be paid by buyer, seller, or absorbed by Amanat?
- Does Amanat need crypto-to-fiat/offramp later, which adds KYC/payment detail requirements?
- Which AML/sanctions provider should back the first Transaction Safety Provider implementation?
- Which Cloudflare durable primitive should store webhook evidence: Queues plus D1, R2 raw payloads, or another append-only store?
## Recommendation
Start with Secure Payment Pages and a platform escrow/payee destination controlled by Amanat. This best matches the current escrow mental model while reducing frontend transaction-building risk. Do not route pay-ins directly to sellers until dispute handling, refund logic, and service fee economics are fully redesigned.