aeron-wallet 0.3.0 → 0.4.0

package/README.md

@@ -30,7 +30,7 @@ need ETH: the facilitator relays the transaction and pays gas.
 |---|---|
 | `address` | Print the wallet address. Creates the key if none exists. |
 | `balance` | ETH and USDG balances, read from chain. |
-| `pay <url> [json]` | Call an x402 endpoint, paying if it answers 402. |
+| `pay [--method GET] <url> [json]` | Call an x402 endpoint, paying if it answers 402. POST unless told otherwise. |
 | `history` | The last 10 payments, from the local log. |
 | `session create` | Mint a scoped session: hosts, budget, per-call cap, expiry. |
 | `session list` | Every session, what it spent, and whether it is still live. |
@@ -142,6 +142,41 @@ The wallet refuses to sign above either cap, so a loop cannot drain it.
 | `MAX_PER_CALL_USD` | `0.05` | Largest single payment. |
 | `DAILY_CAP_USD` | `1` | Total for the current UTC day. |
 
+## Paying merchants you did not write
+
+Reading a 402 sounds like one line — take `accepts[0]` from the body — and that
+line works against servers written the same way this wallet was. It works
+against almost nothing else. On a survey of the machine-payable endpoints
+listed on Robinhood Chain, **not one merchant put this rail's offer first**:
+every one of them leads with Base, and the payable entry sits somewhere down a
+list of a dozen.
+
+So the offer is searched for, not assumed, across every shape merchants
+actually use:
+
+| What differs | What is done |
+|---|---|
+| Offers in the JSON body, or in a base64 `payment-required` header, or both | Both are read, and the same offer stated twice is one offer |
+| The amount is `maxAmountRequired` (v1) or `amount` (v2) | Either is accepted |
+| The list mixes chains and address formats this wallet has no key for | Non-EVM entries are skipped rather than treated as errors |
+| Several offers are payable | The cheapest one wins |
+| Nothing is payable | The refusal names what *was* offered, so the reason is actionable |
+
+### The two protocol versions are not a version number
+
+v1 carries the payment in `X-PAYMENT` and names the scheme and network at the
+top level. v2 carries it in `payment-signature`, names neither, and states the
+chosen offer verbatim in `accepted` — a rebuilt copy does not match, because
+the server compares it against what it advertised. Answering a v2 merchant in
+v1's form does not degrade; it is refused.
+
+Worse, the split is not clean in the wild: merchants advertise a v2 header
+beside a v1 body, and one host in a family of five wants `X-PAYMENT` while its
+siblings want `payment-signature`. So the payment is offered in the form the
+version asks for and, if that is refused outright, in the other one. Both
+carry the **same** signed authorization, whose EIP-3009 nonce can be spent
+exactly once — so the fallback cannot pay twice, however the server answers.
+
 ## What a result means
 
 A request that comes back 4xx is not one situation, it is three, and they

package/dist/cli-args.js

@@ -0,0 +1,32 @@
+/**
+ * Pulling `--name value` out of an argument list.
+ *
+ * Small on purpose: the CLI takes positional arguments that mean different
+ * things per command, so a flag has to be lifted out before the positions are
+ * read, or `pay <url> <body>` starts seeing `--method` as its body.
+ */
+export function takeFlag(argv, name) {
+    const at = argv.indexOf(`--${name}`);
+    if (at === -1)
+        return { value: undefined, rest: [...argv] };
+    const value = argv[at + 1];
+    if (value === undefined || value.startsWith('--'))
+        throw new Error(`--${name} needs a value`);
+    return { value, rest: [...argv.slice(0, at), ...argv.slice(at + 2)] };
+}
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/**
+ * The method to call a resource with.
+ *
+ * Defaults to POST, which is what most paid endpoints take — but plenty are
+ * plain GETs, and a wallet that can only POST cannot pay them at all.
+ */
+export function parseMethod(raw) {
+    if (raw === undefined)
+        return 'POST';
+    const method = raw.toUpperCase();
+    if (!METHODS.includes(method)) {
+        throw new Error(`--method must be one of ${METHODS.join(', ')}`);
+    }
+    return method;
+}

package/dist/cli.js

@@ -7,6 +7,7 @@ import { payX402, resolveDomain } from './payer.js';
 import { startMcpServer } from './mcp.js';
 import { bindSession, createSessions } from './sessions.js';
 import { runSessionCommand } from './cli-sessions.js';
+import { parseMethod, takeFlag } from './cli-args.js';
 const out = (line) => process.stdout.write(`${line}\n`);
 async function main() {
     const cfg = loadConfig();
@@ -23,12 +24,10 @@ async function main() {
     const [command = 'mcp', ...argv] = process.argv.slice(2);
     // A `--session <token>` flag scopes one call; AERON_WALLET_SESSION scopes
     // the whole process, which is how you hand a sub-agent a bounded server.
-    const flagAt = argv.indexOf('--session');
-    const inlineToken = flagAt === -1 ? undefined : argv[flagAt + 1];
-    if (flagAt !== -1 && !inlineToken)
-        throw new Error('--session needs a token');
-    const rest = flagAt === -1 ? argv : [...argv.slice(0, flagAt), ...argv.slice(flagAt + 2)];
-    const token = inlineToken ?? cfg.AERON_WALLET_SESSION;
+    const session = takeFlag(argv, 'session');
+    const methodFlag = takeFlag(session.rest, 'method');
+    const rest = methodFlag.rest;
+    const token = session.value ?? cfg.AERON_WALLET_SESSION;
     const binding = token ? bindSession(sessions, token) : null;
     if (binding && !binding.current()) {
         throw new Error('that session token is unknown, revoked, or already gone');
@@ -51,9 +50,14 @@ async function main() {
         case 'pay': {
             const url = rest[0];
             if (!url)
-                throw new Error('usage: pay <url> [json-body]');
+                throw new Error('usage: pay [--method GET] <url> [json-body]');
             const body = rest[1];
-            const result = await payX402(url, { method: 'POST', headers: { 'content-type': 'application/json' }, ...(body ? { body } : {}) }, { cfg, account, history, domain: await domain(), binding });
+            const method = parseMethod(methodFlag.value);
+            const result = await payX402(url, {
+                method,
+                // A GET carries no body, so it should not announce one either.
+                ...(body ? { headers: { 'content-type': 'application/json' }, body } : {}),
+            }, { cfg, account, history, domain: await domain(), binding });
             out(JSON.stringify(result, null, 2));
             if (!result.paid && result.reason)
                 process.exitCode = 1;

package/dist/offers.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+/**
+ * Reading what a 402 is actually offering.
+ *
+ * This was one line for a long time — `accepts[0]` from the response body —
+ * and that line only ever worked against servers written the same way this
+ * wallet was. Out in the open, a merchant lists a dozen offers across a dozen
+ * chains, in whichever order suits it, and the one this wallet can pay is
+ * rarely the first. Taking the first offer is not a simplification of the
+ * protocol; it is a different protocol.
+ *
+ * Three shapes have to be read as one:
+ *
+ * - the offers live in the JSON body, or in a base64 `payment-required`
+ *   header, or both;
+ * - the amount is called `maxAmountRequired` by some servers and `amount` by
+ *   others;
+ * - the list mixes chains and address formats this wallet has no key for.
+ *
+ * So: gather every offer from wherever it is stated, keep the ones this rail
+ * can actually settle, and take the cheapest of those.
+ */
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const ATOMIC = /^\d+$/;
+const offerSchema = z.looseObject({
+    scheme: z.string(),
+    network: z.string(),
+    asset: z.string(),
+    payTo: z.string(),
+    maxAmountRequired: z.string().optional(),
+    amount: z.string().optional(),
+    maxTimeoutSeconds: z.number().optional(),
+});
+const envelopeSchema = z.looseObject({
+    x402Version: z.number().optional(),
+    accepts: z.array(z.unknown()).min(1),
+    extensions: z.unknown().optional(),
+});
+/**
+ * An offer this wallet could sign for, or null.
+ *
+ * Non-EVM offers are dropped here rather than treated as errors: a Solana or
+ * Stellar payee in the list is a normal thing for a merchant to publish, and
+ * nothing for an EVM wallet to complain about.
+ */
+function normalize(raw, version, extensions) {
+    const parsed = offerSchema.safeParse(raw);
+    if (!parsed.success)
+        return null;
+    const offer = parsed.data;
+    if (offer.scheme !== 'exact')
+        return null;
+    if (!ADDRESS.test(offer.payTo) || !ADDRESS.test(offer.asset))
+        return null;
+    const atomicAmount = offer.maxAmountRequired ?? offer.amount;
+    if (atomicAmount === undefined || !ATOMIC.test(atomicAmount) || atomicAmount === '0')
+        return null;
+    return {
+        network: offer.network,
+        asset: offer.asset,
+        payTo: offer.payTo,
+        atomicAmount,
+        x402Version: version,
+        raw,
+        ...(extensions !== undefined ? { extensions } : {}),
+        ...(offer.maxTimeoutSeconds !== undefined ? { maxTimeoutSeconds: offer.maxTimeoutSeconds } : {}),
+    };
+}
+const acceptsIn = (value) => {
+    const parsed = envelopeSchema.safeParse(value);
+    if (!parsed.success)
+        return { accepts: [], version: 1 };
+    // An envelope that does not say is v1: that is the version that predates
+    // anyone having to say.
+    return {
+        accepts: parsed.data.accepts,
+        version: parsed.data.x402Version ?? 1,
+        ...(parsed.data.extensions !== undefined ? { extensions: parsed.data.extensions } : {}),
+    };
+};
+const EMPTY = { accepts: [], version: 1 };
+function decodeHeader(header) {
+    if (!header)
+        return EMPTY;
+    try {
+        return acceptsIn(JSON.parse(Buffer.from(header, 'base64').toString('utf8')));
+    }
+    catch {
+        return EMPTY;
+    }
+}
+function decodeBody(body) {
+    try {
+        return acceptsIn(JSON.parse(body));
+    }
+    catch {
+        return EMPTY;
+    }
+}
+/**
+ * Every offer a 402 states, from the body and the `payment-required` header
+ * alike. Neither is authoritative over the other: servers use one, the other,
+ * or both, and an offer is an offer wherever it was written down.
+ */
+export function readOffers(body, paymentRequiredHeader) {
+    const fromBody = decodeBody(body);
+    const fromHeader = decodeHeader(paymentRequiredHeader ?? null);
+    const offers = [
+        ...fromBody.accepts.map((raw) => normalize(raw, fromBody.version, fromBody.extensions)),
+        ...fromHeader.accepts.map((raw) => normalize(raw, fromHeader.version, fromHeader.extensions)),
+    ].filter((offer) => offer !== null);
+    // The same offer stated in both places is one offer, not two — and when a
+    // server states it twice it is usually a v2 server keeping a v1 body around
+    // for old clients. Answering the older statement makes a v2 server refuse a
+    // payment it advertised itself, so the newer one wins.
+    const best = new Map();
+    for (const offer of offers) {
+        const key = `${offer.network}|${offer.asset.toLowerCase()}|${offer.payTo.toLowerCase()}|${offer.atomicAmount}`;
+        const held = best.get(key);
+        if (!held || offer.x402Version > held.x402Version)
+            best.set(key, offer);
+    }
+    return [...best.values()];
+}
+/**
+ * The cheapest offer payable on this rail.
+ *
+ * When nothing matches, the reason names what was on the table instead — a
+ * buyer debugging a refusal needs to know whether the merchant wants another
+ * chain or another token, not merely that it said no.
+ */
+export function selectOffer(offers, want) {
+    if (offers.length === 0)
+        return { ok: false, reason: 'unrecognized 402 offer' };
+    const asset = want.asset.toLowerCase();
+    const payable = offers
+        .filter((offer) => offer.network === want.network && offer.asset.toLowerCase() === asset)
+        .sort((a, b) => (BigInt(a.atomicAmount) < BigInt(b.atomicAmount) ? -1 : 1));
+    const offer = payable[0];
+    if (offer)
+        return { ok: true, offer };
+    const onNetwork = offers.filter((o) => o.network === want.network);
+    if (onNetwork.length > 0) {
+        const tokens = [...new Set(onNetwork.map((o) => o.asset))].join(', ');
+        return { ok: false, reason: `no offer in USDG on ${want.network} (offered: ${tokens})` };
+    }
+    const networks = [...new Set(offers.map((o) => o.network))].join(', ');
+    return { ok: false, reason: `no offer on ${want.network} (offered: ${networks})` };
+}

package/dist/payer.js

@@ -1,8 +1,9 @@
 import { randomBytes } from 'node:crypto';
-import { z } from 'zod';
 import { hashDomain } from 'viem';
 import { checkSession } from './sessions.js';
 import { describeOutcome } from './outcome.js';
+import { readOffers, selectOffer } from './offers.js';
+import { paymentAttempts } from './payment-header.js';
 /** EIP-3009 typed data, mirrored from the facilitator side. */
 const TRANSFER_WITH_AUTHORIZATION_TYPES = {
     TransferWithAuthorization: [
@@ -44,18 +45,6 @@ export async function resolveDomain(publicClient, cfg) {
     }
     throw new Error('could not match the token EIP-712 domain version');
 }
-const requirementsSchema = z.looseObject({
-    scheme: z.literal('exact'),
-    network: z.string(),
-    maxAmountRequired: z.string().regex(/^\d+$/),
-    payTo: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
-    asset: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
-    maxTimeoutSeconds: z.number().optional(),
-});
-const body402Schema = z.looseObject({
-    x402Version: z.number(),
-    accepts: z.array(requirementsSchema).min(1),
-});
 /** Refused by the wallet before any request went out. */
 const refused = (reason, amountUsd = 0) => ({
     paid: false,
@@ -88,18 +77,18 @@ export async function payX402(url, init, deps) {
     if (first.status !== 402) {
         return { paid: false, status: first.status, amountUsd: 0, transaction: null, body: firstBody };
     }
-    const parsed = body402Schema.safeParse(JSON.parse(firstBody));
-    if (!parsed.success) {
-        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: 'unrecognized 402 offer' };
-    }
-    const offer = parsed.data.accepts[0];
-    if (offer.network !== cfg.network) {
-        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: `network mismatch: ${offer.network}` };
-    }
-    if (offer.asset.toLowerCase() !== cfg.USDG_ADDRESS.toLowerCase()) {
-        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: 'offer asset is not USDG' };
+    // A merchant states its offers in the body, in the payment-required header,
+    // or both, and lists every chain it takes. The one this wallet can settle is
+    // rarely the first, so it is searched for rather than assumed.
+    const choice = selectOffer(readOffers(firstBody, first.headers.get('payment-required')), {
+        network: cfg.network,
+        asset: cfg.USDG_ADDRESS,
+    });
+    if (!choice.ok) {
+        return { paid: false, status: 402, amountUsd: 0, transaction: null, body: firstBody, reason: choice.reason };
     }
-    const amountUsd = Number(offer.maxAmountRequired) / 1e6;
+    const offer = choice.offer;
+    const amountUsd = Number(offer.atomicAmount) / 1e6;
     if (amountUsd > cfg.MAX_PER_CALL_USD) {
         return {
             paid: false, status: 402, amountUsd, transaction: null, body: firstBody,
@@ -126,7 +115,7 @@ export async function payX402(url, init, deps) {
     const authorization = {
         from: account.address,
         to: offer.payTo,
-        value: BigInt(offer.maxAmountRequired),
+        value: BigInt(offer.atomicAmount),
         validAfter: BigInt(t - 60),
         validBefore: BigInt(t + (offer.maxTimeoutSeconds ?? 60) + 540),
         nonce: `0x${randomBytes(32).toString('hex')}`,
@@ -137,27 +126,31 @@ export async function payX402(url, init, deps) {
         primaryType: 'TransferWithAuthorization',
         message: authorization,
     });
-    const paymentHeader = Buffer.from(JSON.stringify({
-        x402Version: 1,
-        scheme: 'exact',
-        network: cfg.network,
-        payload: {
-            signature,
-            authorization: {
-                from: authorization.from,
-                to: authorization.to,
-                value: String(authorization.value),
-                validAfter: String(authorization.validAfter),
-                validBefore: String(authorization.validBefore),
-                nonce: authorization.nonce,
-            },
+    const attempts = paymentAttempts(offer, {
+        signature,
+        authorization: {
+            from: authorization.from,
+            to: authorization.to,
+            value: String(authorization.value),
+            validAfter: String(authorization.validAfter),
+            validBefore: String(authorization.validBefore),
+            nonce: authorization.nonce,
         },
-    })).toString('base64');
-    const second = await fetchImpl(url, {
-        ...init,
-        headers: { ...init.headers, 'x-payment': paymentHeader },
     });
-    const secondBody = await second.text();
+    // Offer the payment in the form the version asks for, then in the other one
+    // if it is refused outright. Both carry the same authorization, so at most
+    // one of them can ever settle.
+    let second;
+    let secondBody = '';
+    for (const attempt of attempts) {
+        second = await fetchImpl(url, {
+            ...init,
+            headers: { ...init.headers, [attempt.name]: attempt.value },
+        });
+        secondBody = await second.text();
+        if (second.status !== 402)
+            break;
+    }
     let transaction = null;
     const receiptHeader = second.headers.get('x-payment-response');
     if (receiptHeader) {

package/dist/payment-header.js

@@ -0,0 +1,50 @@
+const encode = (payload) => Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+function v2Header(offer, signed) {
+    return {
+        name: 'payment-signature',
+        value: encode({
+            x402Version: Math.max(offer.x402Version, 2),
+            // The chosen offer, exactly as the server wrote it. v2 has no top-level
+            // scheme or network — they live in here, and a server that matches the
+            // payment against what it advertised needs the entry back byte for byte
+            // rather than rebuilt.
+            accepted: offer.raw,
+            payload: signed,
+            // Echoed the way the reference client echoes it: the server sent these
+            // with the offer, and some read them again on the way in.
+            ...(offer.extensions !== undefined ? { extensions: offer.extensions } : {}),
+        }),
+    };
+}
+function v1Header(offer, signed) {
+    return {
+        name: 'x-payment',
+        value: encode({
+            x402Version: 1,
+            scheme: 'exact',
+            network: offer.network,
+            payload: signed,
+        }),
+    };
+}
+/** The form this offer's own version asks for. */
+export function buildPaymentHeader(offer, signed) {
+    return offer.x402Version >= 2 ? v2Header(offer, signed) : v1Header(offer, signed);
+}
+/**
+ * The forms to offer a payment in, best guess first.
+ *
+ * Out in the open the two versions are not cleanly separated: merchants
+ * advertise a v2 header beside a v1 body, and which one they will actually
+ * accept is not reliably stated anywhere — one host in a family of five wants
+ * `X-PAYMENT` while its siblings want `payment-signature`.
+ *
+ * So present the other form too. A refusal costs nothing, and both forms carry
+ * the *same* signed authorization, whose EIP-3009 nonce can be spent exactly
+ * once. The fallback therefore cannot pay twice, however the server answers.
+ */
+export function paymentAttempts(offer, signed) {
+    return offer.x402Version >= 2
+        ? [v2Header(offer, signed), v1Header(offer, signed)]
+        : [v1Header(offer, signed), v2Header(offer, signed)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeron-wallet",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "mcpName": "io.github.aeronlabs/aeron-wallet",
   "description": "Non-custodial agent wallet for Robinhood Chain. Pays x402 requests in USDG. Ships as a CLI and an MCP server.",
   "license": "MIT",