agentwallet-mcp 1.10.9 → 1.12.0

package/build/local-wallet.js

@@ -18,6 +18,8 @@ import { readFileSync } from 'node:fs';
 import { createPublicClient, createWalletClient, http, encodeFunctionData, parseAbi, formatUnits, } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { lookupTrustedDecimals } from './x402-payment.js';
+import { typedDataFor } from './x402-eip3009.js';
+import { uptoTypedData } from './x402-permit2.js';
 /* ── Key loading ─────────────────────────────────────────────────── */
 /**
  * Read the key once at startup. Kept module-private: nothing exports the key
@@ -306,3 +308,44 @@ export function localWalletRecord() {
         note: 'Signed in-process. The private key is never sent to AgentWallet servers.',
     };
 }
+/* ── x402 "exact": EIP-3009 authorization signed in-process ──────── */
+/**
+ * Sign a TransferWithAuthorization for an x402 payment. Nothing is broadcast;
+ * the resource server's facilitator settles it on-chain. The amount is put
+ * through the same AGENTWALLET_MAX_TX_TOKEN guard as a transfer, because that
+ * is exactly what the authorization lets someone else execute.
+ */
+export async function localSignAuthorization(chainId, asset, domain, auth) {
+    if (!/^0x[a-fA-F0-9]{40}$/.test(asset))
+        throw new Error(`Local mode needs an EVM token address for x402, got "${asset}".`);
+    if (!/^0x[a-fA-F0-9]{40}$/.test(auth.to))
+        throw new Error(`Local mode needs an EVM payTo address for x402, got "${auth.to}".`);
+    if (!/^\d+$/.test(auth.value))
+        throw new Error(`x402 authorization value must be integer base units, got "${auth.value}".`);
+    const calldata = ('0xa9059cbb'
+        + auth.to.slice(2).toLowerCase().padStart(64, '0')
+        + BigInt(auth.value).toString(16).padStart(64, '0'));
+    await assertWithinTokenCap(chainId, asset, calldata);
+    const from = getLocalAddress();
+    const signature = await getLocalAccount().signTypedData(typedDataFor(chainId, asset, domain.name, domain.version, { ...auth, from }));
+    return { signature, from, mode: 'local' };
+}
+/** Read-only eth_call against the local RPC, same shape as the hosted /eth-call route. */
+export async function localEthCall(chainId, to, data) {
+    const client = createPublicClient({ transport: http(resolveRpcUrl(chainId)) });
+    const r = await client.call({ to, data });
+    return { result: r.data ?? '0x' };
+}
+/** x402 "upto": sign a Permit2 max-authorization in-process. The maximum goes through the token cap like a transfer would. */
+export async function localSignPermit2Upto(chainId, auth) {
+    const token = auth.permitted.token;
+    if (!/^0x[a-fA-F0-9]{40}$/.test(token))
+        throw new Error(`Local mode needs an EVM token address for x402 upto, got "${token}".`);
+    if (!/^\d+$/.test(auth.permitted.amount))
+        throw new Error(`x402 upto amount must be integer base units, got "${auth.permitted.amount}".`);
+    const calldata = ('0xa9059cbb' + auth.witness.to.slice(2).toLowerCase().padStart(64, '0') + BigInt(auth.permitted.amount).toString(16).padStart(64, '0'));
+    await assertWithinTokenCap(chainId, token, calldata);
+    const from = getLocalAddress();
+    const signature = await getLocalAccount().signTypedData(uptoTypedData(chainId, { ...auth, from }));
+    return { signature, from, mode: 'local' };
+}

package/build/token-risk.d.ts

@@ -0,0 +1,19 @@
+export type RiskLevel = 'low' | 'medium' | 'high' | 'unknown';
+export interface TokenRisk {
+    level: RiskLevel;
+    score: number;
+    flags: string[];
+    notes: string[];
+    source: 'goplus' | 'onchain' | 'none';
+    holder_count?: number;
+    top_holder_percent?: number;
+    buy_tax?: number;
+    sell_tax?: number;
+}
+/** Turn a GoPlus token_security record into a verdict. Exported so it can be unit-tested offline. */
+export declare function assessGoPlus(r: Record<string, unknown>): TokenRisk;
+/**
+ * Assess a token. `ethCall` runs a read-only call and returns the hex result
+ * (used for the on-chain fallback: does the contract answer name() and decimals()?).
+ */
+export declare function assessTokenRisk(chainId: number, token: string, ethCall?: (to: string, data: string) => Promise<string>): Promise<TokenRisk>;

package/build/token-risk.js

@@ -0,0 +1,127 @@
+/**
+ * Asset risk before an approval or a swap. The wallet layer knows the amount;
+ * it did not know the asset. This asks GoPlus Security's free token_security
+ * endpoint (no key) and, when that is unavailable, falls back to what the
+ * chain itself can tell us. Always a WARNING, never a block: the caller
+ * decides. Requested in agentwallet-mcp issue #13.
+ */
+import { safeFetch } from './ssrf-guard.js';
+const GOPLUS_CHAINS = new Set([1, 56, 137, 8453, 42161, 10, 43114, 324, 59144, 534352, 25, 250, 100, 1101, 5000, 81457, 204]);
+function num(v) {
+    if (v === undefined || v === null || v === '')
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+function flag(v) { return v === '1' || v === 1 || v === true; }
+/** Turn a GoPlus token_security record into a verdict. Exported so it can be unit-tested offline. */
+export function assessGoPlus(r) {
+    const flags = [];
+    const notes = [];
+    let score = 0;
+    const add = (cond, name, pts, note) => { if (cond) {
+        flags.push(name);
+        score += pts;
+        if (note)
+            notes.push(note);
+    } };
+    add(flag(r.is_honeypot), 'honeypot', 100, 'GoPlus marks this token as a honeypot: it can be bought but not sold.');
+    add(flag(r.fake_token), 'fake_token', 100, 'Flagged as an imitation of a known token.');
+    add(flag(r.is_airdrop_scam), 'airdrop_scam', 80);
+    add(flag(r.cannot_sell_all), 'cannot_sell_all', 60);
+    add(flag(r.transfer_pausable), 'transfer_pausable', 30, 'The owner can pause transfers.');
+    add(flag(r.is_blacklisted), 'blacklist', 30, 'The contract has a blacklist function.');
+    add(flag(r.owner_change_balance), 'owner_change_balance', 80, 'The owner can change any balance.');
+    add(flag(r.hidden_owner), 'hidden_owner', 40);
+    add(flag(r.selfdestruct), 'selfdestruct', 40);
+    add(flag(r.is_mintable), 'mintable', 15);
+    add(flag(r.slippage_modifiable), 'tax_modifiable', 25, 'Buy/sell tax can be changed by the owner.');
+    add(flag(r.personal_slippage_modifiable), 'personal_tax', 40, 'The owner can set a different tax for specific addresses.');
+    add(flag(r.trading_cooldown), 'trading_cooldown', 10);
+    add(flag(r.external_call), 'external_call', 15);
+    add(r.is_open_source === '0', 'closed_source', 35, 'Contract source is not verified.');
+    add(flag(r.is_proxy), 'proxy', 10, 'Upgradeable proxy: the logic can change.');
+    const buy = num(r.buy_tax), sell = num(r.sell_tax);
+    if (buy !== null && buy > 0.1) {
+        flags.push('buy_tax_high');
+        score += 30;
+    }
+    if (sell !== null && sell > 0.1) {
+        flags.push('sell_tax_high');
+        score += 40;
+    }
+    const holders = num(r.holder_count);
+    if (holders !== null && holders < 50) {
+        flags.push('few_holders');
+        score += 25;
+    }
+    let top = 0;
+    const list = Array.isArray(r.holders) ? r.holders : [];
+    for (const h of list) {
+        const p = num(h.percent);
+        if (p !== null && !flag(h.is_contract) && !flag(h.is_locked) && p > top)
+            top = p;
+    }
+    if (top > 0.5) {
+        flags.push('top_holder_over_50pct');
+        score += 40;
+    }
+    else if (top > 0.2) {
+        flags.push('top_holder_over_20pct');
+        score += 15;
+    }
+    if (r.is_in_dex === '0') {
+        flags.push('no_dex_liquidity');
+        score += 20;
+    }
+    if (flag(r.trust_list)) {
+        notes.push('On GoPlus trust list (well-known token).');
+        score = Math.min(score, 5);
+    }
+    score = Math.min(100, score);
+    const level = score >= 60 ? 'high' : score >= 25 ? 'medium' : 'low';
+    const out = { level, score, flags, notes, source: 'goplus' };
+    if (holders !== null)
+        out.holder_count = holders;
+    if (top)
+        out.top_holder_percent = Math.round(top * 10000) / 100;
+    if (buy !== null)
+        out.buy_tax = buy;
+    if (sell !== null)
+        out.sell_tax = sell;
+    return out;
+}
+/**
+ * Assess a token. `ethCall` runs a read-only call and returns the hex result
+ * (used for the on-chain fallback: does the contract answer name() and decimals()?).
+ */
+export async function assessTokenRisk(chainId, token, ethCall) {
+    const addr = token.toLowerCase();
+    if (GOPLUS_CHAINS.has(chainId)) {
+        try {
+            const res = await safeFetch(`https://api.gopluslabs.io/api/v1/token_security/${chainId}?contract_addresses=${addr}`, {
+                method: 'GET', headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(12_000),
+            });
+            const j = (await res.json());
+            const rec = j?.result?.[addr];
+            if (rec && Object.keys(rec).length > 0)
+                return assessGoPlus(rec);
+        }
+        catch { /* fall through to on-chain */ }
+    }
+    if (ethCall) {
+        try {
+            const name = await ethCall(token, '0x06fdde03');
+            const decimals = await ethCall(token, '0x313ce567');
+            const answers = Boolean(name && name !== '0x') && Boolean(decimals && decimals !== '0x');
+            return {
+                level: answers ? 'unknown' : 'high', score: answers ? 50 : 90,
+                flags: answers ? ['no_security_data'] : ['not_an_erc20'],
+                notes: [answers ? 'No security data available for this chain or token; only basic ERC-20 shape was confirmed.' : 'Contract did not answer name() and decimals(); it may not be an ERC-20 token at all.'],
+                source: 'onchain',
+            };
+        }
+        catch { /* fall through */ }
+    }
+    return { level: 'unknown', score: 50, flags: ['no_security_data'], notes: ['No risk data could be fetched.'], source: 'none' };
+}

package/build/x402-eip3009.d.ts

@@ -0,0 +1,171 @@
+export declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+/** One entry of a 402 "accepts" array, v1 or v2 (and AgentWallet's own legacy shape). */
+export interface X402Requirement {
+    scheme: string;
+    network: string;
+    payTo: string;
+    asset?: string;
+    amount?: string;
+    maxAmountRequired?: string;
+    maxTimeoutSeconds?: number;
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    outputSchema?: Record<string, unknown>;
+    requiredDecimals?: number;
+    extra?: {
+        name?: string;
+        version?: string;
+        token?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+export interface X402PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: X402Requirement[];
+    extensions?: Record<string, unknown>;
+}
+export interface Eip3009Authorization {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: `0x${string}`;
+}
+export interface X402Settlement {
+    success?: boolean;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+    amount?: string;
+    errorReason?: string;
+    errorMessage?: string;
+    [k: string]: unknown;
+}
+/**
+ * AgentWallet's own paywalls (hifriendbot.com /x402/access/{id}) predate the
+ * spec's field names: no `asset`, token under `extra.token`, `requiredDecimals`
+ * present, and they verify a broadcast transfer by receipt. Anything with an
+ * `asset` is treated as standard x402.
+ */
+export declare function isLegacyAgentWalletAccept(a: X402Requirement): boolean;
+/** Required amount in base units, whichever spelling the server used. */
+export declare function requiredAmount(a: X402Requirement): string;
+export declare function createNonce(): `0x${string}`;
+/** Authorization window mirrors the reference client: valid from 10 minutes ago until maxTimeoutSeconds from now. */
+export declare function buildAuthorization(from: string, req: X402Requirement, nowSeconds?: number, nonce?: `0x${string}`): Eip3009Authorization;
+/** EIP-712 typed data for the authorization. `name`/`version` are the token's own domain values. */
+export declare function typedDataFor(chainId: number, asset: string, name: string, version: string, auth: Eip3009Authorization): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly TransferWithAuthorization: readonly [{
+            readonly name: "from";
+            readonly type: "address";
+        }, {
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly name: "validAfter";
+            readonly type: "uint256";
+        }, {
+            readonly name: "validBefore";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "TransferWithAuthorization";
+    message: {
+        from: `0x${string}`;
+        to: `0x${string}`;
+        value: bigint;
+        validAfter: bigint;
+        validBefore: bigint;
+        nonce: `0x${string}`;
+    };
+};
+/**
+ * Token EIP-712 domains we know without asking the chain. USDC's domain name
+ * differs by deployment ("USD Coin" on most mainnets, "USDC" on Base Sepolia),
+ * which is exactly the kind of thing that silently produces an unrecoverable
+ * signature, so only well-known deployments are listed; anything else is read
+ * from the contract's name()/version().
+ */
+export declare const KNOWN_TOKEN_DOMAINS: Record<string, {
+    name: string;
+    version: string;
+}>;
+export declare function knownTokenDomain(chainId: number, asset: string): {
+    name: string;
+    version: string;
+} | null;
+/** Decode a single ABI-encoded string return value (name()/version()). */
+export declare function decodeAbiString(hex: string): string;
+/** Build the payment payload the resource server expects for this x402 version. */
+export declare function buildPaymentPayload(x402Version: number, req: X402Requirement, auth: Eip3009Authorization, signature: string, resource?: X402PaymentRequired['resource'], extensions?: Record<string, unknown>): Record<string, unknown>;
+/** Same envelope for any scheme payload (EIP-3009 authorization, Permit2 authorization, tx hash). */
+export declare function buildPaymentPayloadRaw(x402Version: number, req: X402Requirement, payload: Record<string, unknown>, resource?: X402PaymentRequired['resource'], extensions?: Record<string, unknown>): Record<string, unknown>;
+/** 16-128 chars of [A-Za-z0-9_-], the shape the payment-identifier extension accepts. */
+export declare function generatePaymentId(): string;
+/**
+ * x402 v2 "payment-identifier" extension: the server may ask for a client-chosen
+ * id so it can de-duplicate retries. The 402's extensions are echoed back with
+ * info.id filled in. Other extensions pass through untouched.
+ */
+export declare function withPaymentIdentifier(extensions?: Record<string, unknown>, id?: string): Record<string, unknown> | null;
+export declare function paymentHeaderFor(x402Version: number, payload: Record<string, unknown>): {
+    name: string;
+    value: string;
+};
+/** v2 servers put the requirements in PAYMENT-REQUIRED; v1 servers put them in the JSON body. */
+export declare function parsePaymentRequired(getHeader: (name: string) => string | null | undefined, body: unknown): X402PaymentRequired | null;
+export declare function parseSettlement(getHeader: (name: string) => string | null | undefined): X402Settlement | null;
+/**
+ * Choose which accepts[] entry to pay. `exact` (EIP-3009, gasless for the
+ * payer) is preferred. `upto` is accepted when it carries the facilitator
+ * address the Permit2 witness must be bound to; an upto option without it is
+ * refused rather than approximated with an upfront transfer (issue #6).
+ * Returns the reason when nothing is payable.
+ */
+export declare function pickOption(accepts: X402Requirement[], resolveChainId: (network: string) => number | null, preferChain?: number): {
+    option: X402Requirement | null;
+    chainId: number | null;
+    reason?: string;
+};

package/build/x402-eip3009.js

@@ -0,0 +1,207 @@
+/**
+ * x402 "exact" scheme on EVM, done the way the spec says: an EIP-3009
+ * TransferWithAuthorization signed off-chain and handed to the resource server
+ * in the payment header. The facilitator settles it; the payer broadcasts
+ * nothing and pays no gas.
+ *
+ * Before v1.11.0 pay_x402 broadcast a plain ERC-20 transfer() and put the tx
+ * hash in the header. That only ever worked against AgentWallet's own paywalls
+ * (which verify by receipt); every standard x402 server rejected it (issue #7).
+ * The receipt-style flow is kept for those paywalls and detected by their
+ * shape, see isLegacyAgentWalletAccept().
+ *
+ * Wire formats, both supported (issue #7 endpoint speaks v1, newer servers v2):
+ *   v1: 402 body {x402Version:1, accepts:[{maxAmountRequired, asset, payTo, network:"base", ...}]}
+ *       request header  X-PAYMENT: base64({x402Version:1, scheme, network, payload:{signature, authorization}})
+ *       response header X-PAYMENT-RESPONSE
+ *   v2: 402 header PAYMENT-REQUIRED: base64({x402Version:2, resource, accepts:[{amount, asset, payTo, network:"eip155:8453", ...}]})
+ *       request header  PAYMENT-SIGNATURE: base64({x402Version:2, resource, accepted, payload:{signature, authorization}})
+ *       response header PAYMENT-RESPONSE
+ */
+import { randomBytes } from 'node:crypto';
+import { isUptoPayable } from './x402-permit2.js';
+export const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+/**
+ * AgentWallet's own paywalls (hifriendbot.com /x402/access/{id}) predate the
+ * spec's field names: no `asset`, token under `extra.token`, `requiredDecimals`
+ * present, and they verify a broadcast transfer by receipt. Anything with an
+ * `asset` is treated as standard x402.
+ */
+export function isLegacyAgentWalletAccept(a) {
+    if (a.asset)
+        return false;
+    return Boolean(a.extra?.token) || typeof a.requiredDecimals === 'number';
+}
+/** Required amount in base units, whichever spelling the server used. */
+export function requiredAmount(a) {
+    const v = a.amount ?? a.maxAmountRequired ?? '';
+    return String(v);
+}
+export function createNonce() {
+    return ('0x' + randomBytes(32).toString('hex'));
+}
+const DEFAULT_TIMEOUT_SECONDS = 300;
+/** Authorization window mirrors the reference client: valid from 10 minutes ago until maxTimeoutSeconds from now. */
+export function buildAuthorization(from, req, nowSeconds = Math.floor(Date.now() / 1000), nonce = createNonce()) {
+    const value = requiredAmount(req);
+    if (!/^\d+$/.test(value))
+        throw new Error(`x402: invalid required amount "${value}" (expected integer base units).`);
+    if (!/^0x[0-9a-fA-F]{40}$/.test(req.payTo))
+        throw new Error(`x402: payTo is not an EVM address: "${req.payTo}".`);
+    const timeout = Number.isFinite(req.maxTimeoutSeconds) && req.maxTimeoutSeconds > 0
+        ? Math.floor(req.maxTimeoutSeconds) : DEFAULT_TIMEOUT_SECONDS;
+    return {
+        from: from,
+        to: req.payTo,
+        value,
+        validAfter: String(nowSeconds - 600),
+        validBefore: String(nowSeconds + timeout),
+        nonce,
+    };
+}
+/** EIP-712 typed data for the authorization. `name`/`version` are the token's own domain values. */
+export function typedDataFor(chainId, asset, name, version, auth) {
+    return {
+        domain: { name, version, chainId, verifyingContract: asset },
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: 'TransferWithAuthorization',
+        message: {
+            from: auth.from,
+            to: auth.to,
+            value: BigInt(auth.value),
+            validAfter: BigInt(auth.validAfter),
+            validBefore: BigInt(auth.validBefore),
+            nonce: auth.nonce,
+        },
+    };
+}
+/**
+ * Token EIP-712 domains we know without asking the chain. USDC's domain name
+ * differs by deployment ("USD Coin" on most mainnets, "USDC" on Base Sepolia),
+ * which is exactly the kind of thing that silently produces an unrecoverable
+ * signature, so only well-known deployments are listed; anything else is read
+ * from the contract's name()/version().
+ */
+export const KNOWN_TOKEN_DOMAINS = {
+    '8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': { name: 'USD Coin', version: '2' }, // USDC Base
+    '84532:0x036cbd53842c5426634e7929541ec2318f3dcf7e': { name: 'USDC', version: '2' }, // USDC Base Sepolia
+    '1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': { name: 'USD Coin', version: '2' }, // USDC Ethereum
+    '137:0x3c499c542cef5e3811e1192ce70d8cc03d5c3359': { name: 'USD Coin', version: '2' }, // USDC Polygon (native)
+    '42161:0xaf88d065e77c8cc2239327c5edb3a432268e5831': { name: 'USD Coin', version: '2' }, // USDC Arbitrum
+    '10:0x0b2c639c533813f4aa9d7837caf62653d097ff85': { name: 'USD Coin', version: '2' }, // USDC Optimism
+    '43114:0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e': { name: 'USD Coin', version: '2' }, // USDC Avalanche
+};
+export function knownTokenDomain(chainId, asset) {
+    return KNOWN_TOKEN_DOMAINS[`${chainId}:${asset.toLowerCase()}`] ?? null;
+}
+/** Decode a single ABI-encoded string return value (name()/version()). */
+export function decodeAbiString(hex) {
+    const h = (hex || '').replace(/^0x/, '');
+    if (h.length < 128)
+        return '';
+    const len = parseInt(h.slice(64, 128), 16);
+    if (!Number.isFinite(len) || len <= 0 || len > 256)
+        return '';
+    const bytes = Buffer.from(h.slice(128, 128 + len * 2), 'hex');
+    return bytes.toString('utf8');
+}
+/** Build the payment payload the resource server expects for this x402 version. */
+export function buildPaymentPayload(x402Version, req, auth, signature, resource, extensions) {
+    return buildPaymentPayloadRaw(x402Version, req, { signature, authorization: auth }, resource, extensions);
+}
+/** Same envelope for any scheme payload (EIP-3009 authorization, Permit2 authorization, tx hash). */
+export function buildPaymentPayloadRaw(x402Version, req, payload, resource, extensions) {
+    if (x402Version >= 2) {
+        const out = { x402Version, accepted: req, payload };
+        if (resource)
+            out.resource = resource;
+        const ext = withPaymentIdentifier(extensions);
+        if (ext)
+            out.extensions = ext;
+        return out;
+    }
+    return { x402Version: 1, scheme: req.scheme, network: req.network, payload };
+}
+/** 16-128 chars of [A-Za-z0-9_-], the shape the payment-identifier extension accepts. */
+export function generatePaymentId() {
+    return 'agw_' + randomBytes(16).toString('hex');
+}
+/**
+ * x402 v2 "payment-identifier" extension: the server may ask for a client-chosen
+ * id so it can de-duplicate retries. The 402's extensions are echoed back with
+ * info.id filled in. Other extensions pass through untouched.
+ */
+export function withPaymentIdentifier(extensions, id) {
+    if (!extensions || typeof extensions !== 'object')
+        return null;
+    const out = { ...extensions };
+    const pid = out['payment-identifier'];
+    if (pid && typeof pid === 'object' && pid.info && typeof pid.info === 'object') {
+        out['payment-identifier'] = { ...pid, info: { ...pid.info, id: pid.info.id || id || generatePaymentId() } };
+    }
+    return out;
+}
+export function paymentHeaderFor(x402Version, payload) {
+    const value = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+    return { name: x402Version >= 2 ? 'PAYMENT-SIGNATURE' : 'X-PAYMENT', value };
+}
+function decodeBase64Json(v) {
+    if (!v)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(v.trim(), 'base64').toString('utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** v2 servers put the requirements in PAYMENT-REQUIRED; v1 servers put them in the JSON body. */
+export function parsePaymentRequired(getHeader, body) {
+    const fromHeader = decodeBase64Json(getHeader('PAYMENT-REQUIRED') ?? getHeader('payment-required'));
+    if (fromHeader && Array.isArray(fromHeader.accepts))
+        return fromHeader;
+    if (body && typeof body === 'object' && Array.isArray(body.accepts)) {
+        return body;
+    }
+    return null;
+}
+export function parseSettlement(getHeader) {
+    return (decodeBase64Json(getHeader('PAYMENT-RESPONSE') ?? getHeader('payment-response'))
+        ?? decodeBase64Json(getHeader('X-PAYMENT-RESPONSE') ?? getHeader('x-payment-response')));
+}
+/**
+ * Choose which accepts[] entry to pay. `exact` (EIP-3009, gasless for the
+ * payer) is preferred. `upto` is accepted when it carries the facilitator
+ * address the Permit2 witness must be bound to; an upto option without it is
+ * refused rather than approximated with an upfront transfer (issue #6).
+ * Returns the reason when nothing is payable.
+ */
+export function pickOption(accepts, resolveChainId, preferChain) {
+    const onChain = accepts.filter(a => resolveChainId(a.network) !== null);
+    const exact = onChain.filter(a => a.scheme === 'exact');
+    const upto = onChain.filter(a => isUptoPayable(a));
+    const payable = [...exact, ...upto];
+    if (payable.length === 0) {
+        const schemes = Array.from(new Set(accepts.map(a => a.scheme))).join(', ') || 'none';
+        const reason = accepts.some(a => a.scheme === 'upto')
+            ? 'This endpoint offers the x402 "upto" scheme without an extra.facilitatorAddress (or without an asset), so the ' +
+                'Permit2 authorization cannot be bound to a facilitator. AgentWallet will not approximate it with an upfront transfer. ' +
+                'Ask the endpoint operator to publish facilitatorAddress, or an "exact" option.'
+            : `No payable option: schemes offered were ${schemes}.`;
+        return { option: null, chainId: null, reason };
+    }
+    let option = payable[0];
+    if (preferChain)
+        option = payable.find(a => resolveChainId(a.network) === preferChain) ?? option;
+    return { option, chainId: resolveChainId(option.network) };
+}