Formatting updates

Author: johnpmitsch

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,48 @@
+# Implementation plan: x402 drawdown + MPP session
+
+Source of truth for the UX design:
+`~/.claude/plans/research-quicknode-gateway-payment-vast-babbage.md`.
+This file tracks execution status only; do not re-litigate the 14 decisions.
+
+Branch `x402_MPP`, one PR, both models, phased commits (x402 drawdown first,
+then MPP session). Do NOT commit this file (public repo).
+
+Pre-stage (done): popped stash and committed the per-request `--payment-*`
+flag rename + asset-name resolution. Plan naming is now real.
+
+## Stage 1: SDK x402 drawdown
+**Goal**: SIWX auth (POST /auth), JWT seed/export, drawdown call (Bearer, no
+signing), GET /credits, POST /drip, credit purchase via existing 402 signer.
+New `PaymentScheme` variant(s) in `../sdk/crates/core/src/rpc/payment/mod.rs`.
+**Success criteria**: SDK wiremock unit tests; per-request paths untouched.
+**Status**: Complete (SDK commit e6416f4)
+
+## Stage 2: CLI `qn rpc x402` noun
+**Goal**: buy-credits/balance/drip in `src/commands/rpc/x402.rs`; JWT cache
+(0600, wallet-address keyed); Mild gating w/ ceiling-naming prompt; next hints.
+**Success criteria**: happy + error + both gating tests in tests/rpc_payment.rs.
+**Status**: Complete (CLI commit 21ef1b1)
+
+## Stage 3: CLI `--x402-drawdown` on call
+**Goal**: ArgGroup member; auto re-auth; error mapping (empty credits, monthly
+limit). context.md + README in same commits.
+**Success criteria**: wiremock tests incl. expired-JWT re-auth; single-attempt.
+**Status**: Complete (CLI commit 7b11106)
+
+## Stage 4: SDK MPP session
+**Goal**: escrow deposit tx (Tempo first), open/top-up/close/status, cumulative
+EIP-712 voucher signer, `/session/:network` prefix via `host_base`.
+**Success criteria**: SDK tests; charge-intent path untouched.
+**Status**: Complete (SDK commit 6da9adc; byte-exact voucher+channelId vectors)
+
+## Stage 5: CLI `qn rpc mpp` noun + `--mpp-session` on call
+**Goal**: open/top-up/close/status in `src/commands/rpc/mpp.rs`; channel state
+file + recovery-via-status; Mild gating incl. close; voucher call mode.
+**Success criteria**: full test matrix; snapshot review for table output.
+**Status**: Complete (SDK 06b5bc4; CLI ab0c188)
+
+## Stage 6: README Micropayments refactor + docs polish
+**Goal**: one Micropayments section, four zero-to-call walkthroughs + shared
+Get-a-wallet preamble; call --help examples; deferral notes.
+**Success criteria**: all four walkthroughs copy-pasteable; full verify clean.
+**Status**: In Progress

README.md

@@ -353,8 +353,8 @@ Every path needs a payment wallet. Two options:
    referenced by name with `--payment-wallet`):
 
    ```sh
-   qn wallet generate --chain evm --name payer       # evm also covers MPP/Tempo
-   qn wallet generate --chain svm --name sol-payer   # svm for x402/Solana
+   qn wallet generate --vm evm --name payer       # evm also covers MPP/Tempo
+   qn wallet generate --vm svm --name sol-payer   # svm for x402/Solana
    ```
 
    `generate` prints the address (and a QR on a terminal) to fund. The key is
@@ -377,7 +377,7 @@ is a ready `--payment-asset`. Cached at `~/.config/qn/pay-networks.toml` (24h).
 Sign an x402 payment on each call (EVM or Solana stablecoin):
 
 ```sh
-qn wallet generate --chain evm --name payer           # fund the printed address with Base Sepolia USDC
+qn wallet generate --vm evm --name payer           # fund the printed address with Base Sepolia USDC
 qn rpc call eth_blockNumber \
     --network base-sepolia --x402 \
     --payment-wallet payer \
@@ -389,7 +389,7 @@ qn rpc call eth_blockNumber \
 `--network` is the chain you *query*; `--payment-network` is the chain the
 payment *settles* on (independent). `--max-amount` is the per-call ceiling in
 integer base units (e.g. `1000` = 0.001 USDC); an offer above it is refused
-before anything is signed. For Solana, generate an `--chain svm` wallet and use
+before anything is signed. For Solana, generate a `--vm svm` wallet and use
 `--network solana-devnet --payment-network solana-devnet` (add `--svm-rpc-url`
 at volume; the public default rate-limits).
 
@@ -400,7 +400,7 @@ uses the same secp256k1 key format); `--receipt` wraps the result with the
 settlement transaction hash:
 
 ```sh
-qn wallet generate --chain evm --name payer           # fund on Tempo testnet
+qn wallet generate --vm evm --name payer           # fund on Tempo testnet
 qn rpc call eth_blockNumber \
     --network tempo-testnet --mpp --receipt \
     --payment-wallet payer \
@@ -419,7 +419,7 @@ Buy a block of prepaid credits once, then spend them with no per-call signing
 (one credit per successful response):
 
 ```sh
-qn wallet generate --chain evm --name payer           # dedicated wallet
+qn wallet generate --vm evm --name payer           # dedicated wallet
 
 # Testnet only: fund the wallet from the faucet (Base Sepolia, once per
 # account). Prints the funding tx; mainnet wallets are funded normally.
@@ -448,7 +448,7 @@ Open an on-chain escrow payment channel once, then pay per call with a
 cumulative EIP-712 voucher (no on-chain transaction per call):
 
 ```sh
-qn wallet generate --chain evm --name payer           # evm covers Tempo; fund the address
+qn wallet generate --vm evm --name payer           # evm covers Tempo; fund the address
 
 # Open a channel by depositing into the escrow (moves real funds; gated).
 qn rpc mpp open --network tempo-testnet --deposit 1000000 \
@@ -512,8 +512,8 @@ paid RPC lane uses (see [Micropayments](#micropayments)). It needs no API key
 or login:
 
 ```sh
-qn wallet generate --chain evm --name payer   # create + store; prints the address and a QR to fund
-qn wallet list                                # names, chain, address (never the key)
+qn wallet generate --vm evm --name payer      # create + store; prints the address and a QR to fund
+qn wallet list                                # names, vm, address (never the key)
 qn wallet show payer                          # bare address to stdout; QR + key path to stderr
 qn wallet rm payer                            # gated: --yes to confirm; the key is unrecoverable
 ```

src/commands/agent/context.md

@@ -209,7 +209,7 @@ Top-level nouns (plurals like `endpoints`/`streams` and `ls` are accepted aliase
   `--x402`/`--mpp`/`--x402-drawdown`/`--endpoint-url`, and points at
   `qn rpc mpp top-up` when the channel deposit is exhausted.
 - `wallet` — the local store of payment wallets for the paid RPC lane; no API
-  key or login required. `qn wallet generate --chain <evm|svm> --name <NAME>`
+  key or login required. `qn wallet generate --vm <evm|svm> --name <NAME>`
   creates and stores a dedicated payment wallet (raw key at 0600 under
   `<config-dir>/qn/wallets/`, `evm` also covers MPP/Tempo), printing its
   address (and a QR to fund it on a terminal); `qn wallet list`/`show <NAME>`
@@ -295,7 +295,7 @@ refused with HTTP 400/402 before anything settles.
 
 ```sh
 qn rpc pay-networks                                  # which networks are payable, and the x402 asset
-qn wallet generate --chain evm --name payer          # dedicated wallet; prints its address + a QR to fund
+qn wallet generate --vm evm --name payer             # dedicated wallet; prints its address + a QR to fund
 # → fund THAT address, then pick a lane:
 
 # x402 on EVM (Base Sepolia testnet, USDC):
@@ -309,7 +309,7 @@ qn rpc call eth_blockNumber --network tempo-testnet --mpp --receipt \
     --payment-asset USDC --max-amount 1000
 
 # x402 on Solana (devnet); needs an SVM wallet:
-qn wallet generate --chain svm --name sol-payer
+qn wallet generate --vm svm --name sol-payer
 qn rpc call getSlot --network solana-devnet --x402 \
     --payment-wallet sol-payer --payment-network solana-devnet \
     --payment-asset USDC --max-amount 1000

src/commands/rpc/mod.rs

@@ -77,7 +77,7 @@ pub enum RpcCmd {
         qn rpc call eth_blockNumber --network tempo-testnet --mpp-session --payment-wallet payer\n\n\
         See payable networks and manage wallets:\n  \
         qn rpc pay-networks\n  \
-        qn wallet generate --chain evm --name payer")]
+        qn wallet generate --vm evm --name payer")]
     Call(Box<CallArgs>),
 
     /// List the endpoint's available network keys (no RPC call).

src/commands/rpc/x402.rs

@@ -24,6 +24,7 @@ use quicknode_sdk::{CreditBalance, PaymentConfig};
 use crate::config::{self, PaymentSection};
 use crate::context::{Ctx, GlobalArgs};
 use crate::errors::CliError;
+use crate::output::{style, Style};
 
 use super::payment::{
     ensure_gateway_session, resolve_payment_params, resolve_session_params, PaymentParams,
@@ -256,23 +257,32 @@ async fn run_buy_credits(args: PaymentArgs, global: GlobalArgs) -> Result<(), Cl
         "✓ Bought credits (balance: {})",
         fmt_credits(balance.credits)
     ));
-    ctx.out
-        .note(&format!("  Next: {}", drawdown_call_hint(&args, &network)));
+    ctx.out.note(&format!(
+        "\n{}\n\n{}",
+        style(
+            "Spend the credits on calls (signs nothing per request):",
+            Style::Bold,
+            ctx.out.color,
+        ),
+        drawdown_call_hint(&args, &network)
+    ));
     emit_balance(&ctx, &balance)
 }
 
-// A copy-pasteable `--x402-drawdown` call reflecting the flags the user just
-// used, so the chained next step runs as-is.
+// A copy-pasteable, multi-line `--x402-drawdown` call reflecting the flags the
+// user just used, so the chained next step runs as-is.
 fn drawdown_call_hint(args: &PaymentArgs, network: &str) -> String {
     let mut cmd = format!(
-        "qn rpc call eth_blockNumber --network {network} --x402-drawdown --payment-wallet {}",
+        "  qn rpc call eth_blockNumber \\\n    \
+           --network {network} --x402-drawdown \\\n    \
+           --payment-wallet {}",
         args.payment_wallet.as_deref().unwrap_or("<NAME>")
     );
     // The drawdown call defaults its pay network to --network, so only append
     // --payment-network when the user set an explicit one that differs.
     if let Some(pn) = &args.payment_network {
         if pn != network {
-            cmd.push_str(&format!(" --payment-network {pn}"));
+            cmd.push_str(&format!(" \\\n    --payment-network {pn}"));
         }
     }
     cmd
@@ -296,17 +306,54 @@ async fn run_drip(args: SessionArgs, global: GlobalArgs) -> Result<(), CliError>
         "✓ Faucet funded {} (tx: {})",
         receipt.account_id, receipt.transaction_hash
     ));
-    // Point at buy-credits with the flags the user already supplied.
-    let net = args.network.as_deref().or(args.payment_network.as_deref());
-    // buy-credits signs, so the hint carries the asset + ceiling placeholders
-    // the user fills in for the purchase (drip itself collects neither).
-    ctx.out.note(&format!(
-        "  Next: qn rpc x402 buy-credits --network {} --payment-wallet {} \
-         --payment-network {} --payment-asset <ASSET> --max-amount 1000000",
-        net.unwrap_or("<SLUG>"),
-        args.payment_wallet.as_deref().unwrap_or("<NAME>"),
-        args.payment_network.as_deref().unwrap_or("<NET>"),
+    // Point at the two paid lanes with the flags the user already supplied;
+    // USDC is the asset the faucet just funded.
+    let query_net = args
+        .network
+        .as_deref()
+        .or(args.payment_network.as_deref())
+        .unwrap_or("<SLUG>");
+    let wallet = args.payment_wallet.as_deref().unwrap_or("<NAME>");
+    let pay_net = args.payment_network.as_deref().unwrap_or("<NET>");
+    let c = ctx.out.color;
+
+    let mut block = String::new();
+    block.push_str(
+        "\nThis wallet now has funds that can be used to pay for blockchain calls\n\
+         using micropayments.\n\n",
+    );
+    block.push_str(&style(
+        "Pay per-request (sign a payment on each call):",
+        Style::Bold,
+        c,
+    ));
+    block.push_str(&format!(
+        "\n\n  \
+         qn rpc call eth_blockNumber \\\n    \
+           --network {query_net} --x402 \\\n    \
+           --payment-wallet {wallet} \\\n    \
+           --payment-network {pay_net} \\\n    \
+           --payment-asset USDC \\\n    \
+           --max-amount 1000\n\n"
+    ));
+    block.push_str(&style(
+        "Credit drawdown (buy prepaid credits once, then spend them):",
+        Style::Bold,
+        c,
+    ));
+    block.push_str(&format!(
+        "\n\n  \
+         qn rpc x402 buy-credits \\\n    \
+           --network {query_net} \\\n    \
+           --payment-wallet {wallet} \\\n    \
+           --payment-network {pay_net} \\\n    \
+           --payment-asset USDC \\\n    \
+           --max-amount 1000000\n\n  \
+         qn rpc call eth_blockNumber \\\n    \
+           --network {query_net} --x402-drawdown \\\n    \
+           --payment-wallet {wallet}"
     ));
+    ctx.out.note(&block);
     if matches!(ctx.global.format, Some(f) if f.is_structured()) {
         let v = serde_json::json!({
             "account_id": receipt.account_id,