across-pay-mpp 1.0.0

package/STEP2-DEMO-PLAN.md

@@ -0,0 +1,357 @@
+# MPP Step 2 Demo Plan
+
+**Status:** Agreed plan  
+**Date locked:** March 31, 2026  
+**Audience:** Stripe-facing MPP demo only  
+**Goal:** Prove that agents can avoid per-request bridging by paying locally on Arbitrum, while the merchant still settles treasury to Tempo via hourly batching.
+
+---
+
+## Locked Decisions
+
+- Keep the `MPP` Step 2 demo code **separate** from `x402`.
+- Buyer starts with funds on **Arbitrum**.
+- Merchant's preferred settlement chain is **Tempo**.
+- Token can be **USDC** or **USDC.e**, whichever is simplest in the implementation.
+- Receiver is **predeployed** before the demo.
+- Verifier is **run by us**.
+- Each paid request is **$0.02**.
+- Demo shows **3 successful payments**.
+- Merchant serves after **each** successful payment.
+- After payment 3, the demo shows a live **manual trigger of the hourly sweep**.
+- Step 1 comparison is explained **verbally**, not shown as a second live path.
+- Buyer UX should still feel like an **MPP flow**, even though the buyer is Step 2-aware under the hood.
+- Buyer retry should send **`reference + txHash`** back to the merchant.
+- Do **not** retrofit the existing `src/dev/server.ts`; build a **new Step 2 server**.
+
+---
+
+## Demo Story
+
+This is the exact story we are telling:
+
+1. Merchant wants final settlement on **Tempo**.
+2. Agent only has funds on **Arbitrum**.
+3. Merchant returns an MPP-facing 402 challenge.
+4. Buyer derives the merchant's deterministic Arbitrum receiver and proves it exists.
+5. Buyer pays the receiver locally on Arbitrum.
+6. Merchant verifies the Arbitrum payment and serves immediately.
+7. This happens three times.
+8. After the third payment, the operator triggers the scheduled hourly sweep.
+9. Accumulated funds move from the Arbitrum receiver to the merchant's Tempo settlement address.
+
+**Headline:** the user got three successful paid responses without three separate bridge operations.
+
+---
+
+## What "MPP Step 2" Means
+
+This is **not** the current Step 1 flow in `tempo-with-across.ts`.
+
+Step 1 today:
+
+- buyer gets Tempo challenge
+- if buyer lacks Tempo funds, Across bridges to the buyer on Tempo
+- buyer completes a normal Tempo payment
+
+Step 2 for this demo:
+
+- buyer gets an MPP-facing challenge
+- buyer checks whether the merchant has a deployed receiver on **Arbitrum**
+- if yes, buyer pays that receiver locally on Arbitrum
+- merchant verifies the local payment and serves
+- treasury moves to Tempo later on an hourly schedule
+
+That is why this demo needs a separate server and a separate buyer path.
+
+---
+
+## Current Code We Keep As Reference
+
+- Buyer Step 1 wrapper: `src/buyer/tempo-with-across.ts`
+- Current local MPP seller: `src/dev/server.ts`
+- Current demo entrypoints: `src/demo/local.ts`, `src/demo/external.ts`
+
+We should **not** try to mutate those into Step 2. They remain the Step 1 baseline.
+
+---
+
+## New Modules To Add
+
+Create a new `src/step2/` area for the demo-specific code.
+
+### 1. Merchant server
+
+`src/step2/server.ts`
+
+Responsibilities:
+
+- issue the MPP-facing 402 challenge
+- create a unique `reference` per challenge
+- store challenge state
+- accept retry requests containing `reference + txHash`
+- call the verifier
+- serve the paid response after successful verification
+- expose a manual "run hourly sweep now" action for the demo
+
+### 2. Challenge store
+
+`src/step2/challenges.ts`
+
+Responsibilities:
+
+- create challenge records
+- store:
+  - `reference`
+  - `amount`
+  - `payer` if known
+  - `createdAt`
+  - `expiresAt`
+  - `consumedAt`
+  - `txHash`
+  - verification status
+- mark one-time consumption after serving
+
+For the demo, in-memory storage is acceptable.
+
+### 3. Verifier service
+
+`src/step2/verifier.ts`
+
+Responsibilities:
+
+- read Arbitrum transaction receipts
+- decode `PaymentReceived`
+- confirm:
+  - event emitter is the expected receiver
+  - `reference` matches
+  - amount matches
+  - token matches
+  - confirmations threshold is met
+- return a compact decision to the merchant server
+
+Recommended demo default:
+
+- `CONFIRMATIONS_REQUIRED=1`
+- keep it configurable
+
+### 4. Buyer Step 2 path
+
+`src/step2/buyer.ts`
+
+Responsibilities:
+
+- request the protected resource
+- parse the MPP-facing challenge
+- derive the deterministic Arbitrum receiver from merchant identity
+- check `eth_getCode(receiver)` on Arbitrum
+- log clearly that the buyer discovered the correct receiver
+- pay the receiver locally
+- retry the original request with `reference + txHash`
+
+Important:
+
+- this is a **custom Step 2-aware buyer**
+- the audience should still experience it as an MPP flow
+
+### 5. Receiver address derivation helper
+
+`src/step2/receiver.ts`
+
+Responsibilities:
+
+- compute deterministic receiver address
+- share the same derivation logic between buyer, merchant server, and verifier
+
+### 6. Sweep trigger
+
+`src/step2/sweep.ts`
+
+Responsibilities:
+
+- run the manual demo sweep
+- log that this represents the scheduled hourly sweep policy
+- show source balance, destination chain, and completion
+
+### 7. Demo runner
+
+`src/step2/demo.ts`
+
+Responsibilities:
+
+- execute the three-payment script
+- show:
+  - payment 1 verified
+  - payment 2 verified
+  - payment 3 verified
+  - receiver balance accumulated to `$0.06`
+  - hourly sweep triggered
+  - Tempo settlement observed
+
+---
+
+## HTTP Contract For The Demo
+
+### First request
+
+`GET /api/premium`
+
+Expected result:
+
+- merchant returns `402`
+- challenge includes enough identity for the buyer to derive the receiver
+
+### Retry after local payment
+
+`GET /api/premium`
+
+Headers:
+
+- `X-Step2-Reference: <reference>`
+- `X-Step2-Tx-Hash: <txHash>`
+
+Merchant flow:
+
+- load challenge by `reference`
+- call verifier with `reference + txHash`
+- if verified and not consumed, serve content
+
+The buyer should make this obvious in logs:
+
+- `Derived receiver`
+- `Receiver deployed: yes`
+- `Paid locally on Arbitrum`
+- `Retrying with reference + txHash`
+
+---
+
+## Event Contract
+
+The receiver needs one event:
+
+```solidity
+event PaymentReceived(
+  address indexed payer,
+  address indexed token,
+  uint256 amount,
+  bytes32 indexed reference
+);
+```
+
+That is enough for the verifier to bind the Arbitrum payment to the original merchant challenge.
+
+If we want easier demo logging, add a non-indexed string or bytes field later, but the default should stay compact.
+
+---
+
+## Demo UX Requirements
+
+Minimal but explicit.
+
+The demo must show:
+
+1. Buyer got a payment challenge.
+2. Buyer derived the correct Arbitrum receiver.
+3. Buyer found deployed code at that address.
+4. Buyer paid locally on Arbitrum.
+5. Merchant served immediately after verification.
+6. Three payments accumulated on the receiver.
+7. One live "hourly sweep" moved the balance to Tempo.
+
+We do **not** need a polished dashboard.
+We do need logs or a minimal operator view that makes the batching story visually obvious.
+
+---
+
+## Operator View
+
+Minimal output is enough.
+
+Show these fields:
+
+- `reference`
+- `payment count`
+- `receiver address`
+- `receiver balance`
+- `last verified tx`
+- `sweep status`
+- `Tempo settlement tx`
+
+A single terminal + one minimal status page is enough.
+
+---
+
+## Sweep Policy
+
+Real policy:
+
+- sweep **every hour**
+
+Demo behavior:
+
+- after payment 3, manually trigger the "hourly sweep now" action
+
+What we say out loud:
+
+- "In production, this runs on the hourly policy."
+- "For the demo, we're forcing the scheduled action to happen now."
+
+---
+
+## Success Criteria
+
+The demo succeeds if all of the following are true:
+
+1. Buyer makes **3** paid requests from Arbitrum.
+2. Merchant serves after each one.
+3. Buyer never bridges three separate payments to Tempo.
+4. Receiver balance visibly accumulates to roughly **$0.06** before sweep.
+5. One sweep moves the accumulated balance to Tempo.
+6. The audience can plainly see that Step 2 replaced per-request bridging with hourly batching.
+
+---
+
+## Non-Goals
+
+- shared code with x402
+- retrofitting the current Step 1 demo surface
+- undeployed counterfactual receive
+- automatic scheduler infrastructure
+- polished production dashboard
+- live Step 1 comparison path in the same demo
+
+---
+
+## Build Order
+
+### Phase 1
+
+- receiver address derivation helper
+- challenge store
+- merchant Step 2 server shell
+
+### Phase 2
+
+- verifier service
+- buyer Step 2 path
+- retry contract with `reference + txHash`
+
+### Phase 3
+
+- manual sweep action
+- minimal operator view / logs
+- scripted three-payment demo runner
+
+---
+
+## Open Implementation Details
+
+These do **not** block the architecture, but they need to be decided during build:
+
+- exact receiver contract ABI
+- exact `reference` type (`bytes32` vs string encoded to bytes32)
+- whether Tempo settlement target is plain `USDC` or `USDC.e`
+- exact verifier response schema
+- whether the status view is terminal-only or terminal + tiny web page
+
+None of those change the agreed demo story.