@aifinpay/agent 2.0.0-rc.7 → 2.0.1

package/dist/unifiedAgent.js

@@ -14,12 +14,14 @@ import { blake2b } from "@noble/hashes/blake2b";
 import bs58 from "bs58";
 import { createHash, randomBytes } from "node:crypto";
 import { createPublicClient, createWalletClient, http, keccak256, toHex, toFunctionSelector, formatEther, } from "viem";
-import { privateKeyToAccount, } from "viem/accounts";
+import { privateKeyToAccount } from "viem/accounts";
 import { polygon, base, arbitrum, optimism, bsc, mainnet, unichain } from "viem/chains";
 import { botchain, xrplevm } from "./chains.js";
-import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction, } from "@solana/web3.js";
-import { AiFinPayError, X402Error, } from "./errors.js";
+import { AiFinPayError, X402Error } from "./errors.js";
 import { Agent } from "./agent.js";
+import { loadLocalWalletIdentity } from "./localIdentity.js";
+import { SettlementClient, executeSettlementInvoice, } from "./settlement.js";
+import { getQuota } from "./agentHistory.js";
 import { MemorySpendLedger, FileSpendLedger } from "./spendLedger.js";
 import { aifp1Fetch, Aifp1ReceiptCache, } from "./aifp1.js";
 import { bridgeQuote as crossChainQuote, bridgeExecute as crossChainExecute, bridgeWaitForArrival, USDC_NATIVE, } from "./crossChain.js";
@@ -132,6 +134,7 @@ export const SPLITTER_DEPLOYMENTS = {
         nativeUsdEnv: "AIFINPAY_ETH_USD",
         nativeUsdDefault: 1870, // reference only; ~$1870 on 2026-08-03
     },
+    /** @deprecated BOT Chain (chainId: 677) is deprecated. Use robinhood (chainId: 4663) instead. */
     botchain: {
         version: "1.2",
         chainId: 677,
@@ -165,8 +168,8 @@ const EVM_CHAIN_OBJECTS = {
     base,
 };
 function evmChainObject(name) {
-    return (EVM_CHAIN_OBJECTS[name]
-        ?? SPLITTER_DEPLOYMENTS[name]?.chain);
+    return (EVM_CHAIN_OBJECTS[name] ??
+        SPLITTER_DEPLOYMENTS[name]?.chain);
 }
 // Mainnet USDC SPL mint on Solana (Circle native, not Wormhole-wrapped USDCet)
 const USDC_SOLANA_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
@@ -295,8 +298,7 @@ export class AiFinPayAgent {
     constructor(inner, evmAccount, opts = {}) {
         this.inner = inner;
         this.evmAccount = evmAccount;
-        this.registryUrl = opts.registryUrl
-            ?? `${inner.baseUrl}${DEFAULT_REGISTRY_PATH}`;
+        this.registryUrl = opts.registryUrl ?? `${inner.baseUrl}${DEFAULT_REGISTRY_PATH}`;
         this.registryCandidates = opts.registryUrl
             ? [opts.registryUrl]
             : DEFAULT_REGISTRY_PATHS.map((path) => `${inner.baseUrl}${path}`);
@@ -311,9 +313,7 @@ export class AiFinPayAgent {
             this.ledgerOverride = opts.spendLedger;
         this.telemetry = opts.telemetry !== false;
         this.polygonRpc = opts.polygonRpc ?? "https://polygon.drpc.org";
-        this.solanaRpc = opts.solanaRpc
-            ?? process.env.AIFINPAY_SOLANA_RPC
-            ?? "https://api.mainnet-beta.solana.com";
+        this.solanaRpc = opts.solanaRpc ?? process.env.AIFINPAY_SOLANA_RPC ?? "https://api.mainnet-beta.solana.com";
         // Optional RPC overrides for non-Polygon EVM chains used in bridge flows.
         // Falls back to viem's chain.rpcUrls.default if not provided.
         if (opts.evmRpcUrls)
@@ -354,8 +354,7 @@ export class AiFinPayAgent {
         if (!chain) {
             throw new AiFinPayError(`evmClients: unsupported EVM chain "${name}"`);
         }
-        const rpcUrl = this.evmRpcUrls[name]
-            ?? SPLITTER_DEPLOYMENTS[name]?.defaultRpc;
+        const rpcUrl = this.evmRpcUrls[name] ?? SPLITTER_DEPLOYMENTS[name]?.defaultRpc;
         const transport = rpcUrl ? http(rpcUrl) : http();
         const publicClient = createPublicClient({ chain, transport });
         const walletClient = createWalletClient({ chain, transport, account: this.evmAccount });
@@ -373,8 +372,30 @@ export class AiFinPayAgent {
     }
     // ── Constructors ─────────────────────────────────────────────────────────
     /**
-     * Generate a fresh agent — new Solana keypair + new EVM keypair.
-     * Use `fromSeed()` to derive both from a single backup phrase instead.
+     * Load an existing local identity without creating or replacing a wallet.
+     * Priority: SEED_HASH → ./aifinpay/agents.json → AIFINPAY_AGENT_SECRET →
+     * the MCP keystore at AIFINPAY_HOME/agent.json (default ~/.aifinpay).
+     * AIFINPAY_AGENTS_FILE/AGENT_ID select a project file/record; encrypted
+     * keystores require AIFINPAY_WALLET_PASSPHRASE. Reads process.env, not .env.
+     * Missing, invalid or ambiguous configuration throws before any network call.
+     */
+    static async fromEnvironment(opts = {}) {
+        const identity = loadLocalWalletIdentity();
+        try {
+            return identity.seedHash !== undefined
+                ? await AiFinPayAgent.fromSeed(identity.seedHash, opts)
+                : await AiFinPayAgent.fromSolanaSecret(identity.secretB58, opts);
+        }
+        catch {
+            // Decoder/library errors can include input. Never echo local key material.
+            throw new AiFinPayError(`Invalid wallet selected from ${identity.source}; refusing to generate a replacement wallet`);
+        }
+    }
+    /**
+     * Generate a fresh, ephemeral agent. Every call selects a new identity;
+     * existing environment variables and keystores are NOT loaded or changed.
+     * This method does not persist its keys. Use fromEnvironment() for a funded
+     * existing wallet, or privately persist the new seed/secret before funding.
      */
     static async new(opts = {}) {
         // Seed-derived, NOT an independent random EVM key.
@@ -411,17 +432,20 @@ export class AiFinPayAgent {
      * TODO(phase-1): replace with BIP-39/BIP-44 derivation
      *   m/44'/501'/0'/0' (Solana) + m/44'/60'/0'/0/0 (EVM) once the
      *   wallet-import audit recommendation lands.
+     * An explicit opts.evmPrivateKey imports an existing EVM wallet instead;
+     * keep that key as well as the seed to restore the same EVM address.
      */
     static async fromSeed(seedHex, opts = {}) {
-        const seed = hexToBytes(seedHex.replace(/^0x/, ""));
-        if (seed.length !== 32) {
+        const normalizedSeed = seedHex.replace(/^0x/, "");
+        if (!/^[0-9a-fA-F]{64}$/.test(normalizedSeed)) {
             throw new AiFinPayError(`fromSeed: seed must be 32 bytes (64 hex chars)`);
         }
+        const seed = hexToBytes(normalizedSeed);
         const kp = nacl.sign.keyPair.fromSeed(seed);
-        const inner = Agent
-            ._ofKeyPair?.(kp, opts) ?? Agent.fromSecretB58(bs58.encode(kp.secretKey), opts);
+        const inner = Agent._ofKeyPair?.(kp, opts) ??
+            Agent.fromSecretB58(bs58.encode(kp.secretKey), opts);
         // Derive EVM key from seed (independent, not BIP-44 — see TODO above)
-        const evmHex = ("0x" + bytesToHex(crypto32(seed)));
+        const evmHex = opts.evmPrivateKey ?? ("0x" + bytesToHex(crypto32(seed)));
         const evmAccount = privateKeyToAccount(evmHex);
         return new AiFinPayAgent(inner, evmAccount, opts);
     }
@@ -439,8 +463,7 @@ export class AiFinPayAgent {
      */
     static async fromSolanaSecret(secretB58, opts = {}) {
         const inner = Agent.fromSecretB58(secretB58, opts);
-        const evmKey = opts.evmPrivateKey
-            ?? ("0x" + bytesToHex(crypto32(inner.secretKey.subarray(0, 32))));
+        const evmKey = opts.evmPrivateKey ?? ("0x" + bytesToHex(crypto32(inner.secretKey.subarray(0, 32))));
         const evmAccount = privateKeyToAccount(evmKey);
         return new AiFinPayAgent(inner, evmAccount, opts);
     }
@@ -449,8 +472,12 @@ export class AiFinPayAgent {
         // Canonical: Solana pubkey for back-compat with the leaderboard / Seat PDA.
         return this.inner.address;
     }
-    get solanaAddress() { return this.inner.address; }
-    get evmAddress() { return this.evmAccount.address; }
+    get solanaAddress() {
+        return this.inner.address;
+    }
+    get evmAddress() {
+        return this.evmAccount.address;
+    }
     /**
      * Casper identity, derived from the same seed as the other two.
      *
@@ -466,7 +493,9 @@ export class AiFinPayAgent {
         return casperIdentityFromSeed(this.inner.secretKey.subarray(0, 32));
     }
     /** Convenience: the account hash, which is what a Casper explorer wants. */
-    get casperAddress() { return this.casper.accountHash; }
+    get casperAddress() {
+        return this.casper.accountHash;
+    }
     // ── Registry ────────────────────────────────────────────────────────────
     async fetchRegistry(force = false) {
         if (this.cachedRegistry && !force)
@@ -541,9 +570,7 @@ export class AiFinPayAgent {
                 description: opts.description ?? null,
                 endpoint: opts.endpoint,
                 capabilities: opts.capabilities ?? [],
-                pricing: opts.pricing
-                    ? { per_call: opts.pricing.perCall, currency: opts.pricing.currency ?? "USDC" }
-                    : null,
+                pricing: opts.pricing ? { per_call: opts.pricing.perCall, currency: opts.pricing.currency ?? "USDC" } : null,
                 nonce,
                 signature,
             }),
@@ -629,9 +656,8 @@ export class AiFinPayAgent {
         if (this.ledgerOverride)
             return this.ledgerOverride;
         if (!this._ledger) {
-            this._ledger = this.budgetCaps.daily_usd !== undefined
-                ? FileSpendLedger.forAgent(this.evmAddress)
-                : new MemorySpendLedger();
+            this._ledger =
+                this.budgetCaps.daily_usd !== undefined ? FileSpendLedger.forAgent(this.evmAddress) : new MemorySpendLedger();
         }
         return this._ledger;
     }
@@ -671,23 +697,6 @@ export class AiFinPayAgent {
             return false;
         throw err;
     }
-    checkBudget(costUsd) {
-        const mode = this.budgetCaps.on_limit_exceeded ?? "throw";
-        if (this.budgetCaps.per_call_usd !== undefined && costUsd > this.budgetCaps.per_call_usd) {
-            const err = new BudgetCapExceededError("per_call", `cost $${costUsd} exceeds per-call cap $${this.budgetCaps.per_call_usd}`);
-            if (mode === "skip")
-                return false;
-            throw err;
-        }
-        const after = this.spend24h.total24h() + costUsd;
-        if (this.budgetCaps.daily_usd !== undefined && after > this.budgetCaps.daily_usd) {
-            const err = new BudgetCapExceededError("daily", `daily spend ${after.toFixed(4)} would exceed cap $${this.budgetCaps.daily_usd}`);
-            if (mode === "skip")
-                return false;
-            throw err;
-        }
-        return true;
-    }
     /**
      * Current 24-hour rolling spend across all paid calls made by this
      * agent instance. Useful for budget dashboards on the consumer side.
@@ -695,6 +704,16 @@ export class AiFinPayAgent {
     getSpend24h() {
         return this.spend24h.total24h();
     }
+    /**
+     * Durable daily spend from the budget ledger (settled + outstanding, 24h
+     * window). Unlike getSpend24h()'s in-memory ring, this survives reload and
+     * reflects reserve/commit accounting even with no signing tool attached —
+     * the number a long-lived host (e.g. MCP) should display. 0 when no
+     * daily_usd cap is set and nothing was reserved.
+     */
+    async getDailySpendUsd() {
+        return this.ledger.total(24 * 3600 * 1000);
+    }
     /**
      * Sanity-check the USD estimate of an on-chain challenge amount against
      * the declared cost and the per-call cap BEFORE signing the tx.
@@ -725,13 +744,21 @@ export class AiFinPayAgent {
      */
     priceCache;
     async nativeUsdFor(deployment) {
-        const env = process.env[deployment.nativeUsdEnv];
+        return this.tokenUsd(deployment.chain.nativeCurrency.symbol.toUpperCase(), deployment.nativeUsdEnv);
+    }
+    /**
+     * Native-token USD price: explicit env var, then the protocol price feed,
+     * then NaN ("unknown") — never a stale constant. Callers decide what an
+     * unknown price means for their flow (balance() excludes the leg;
+     * guardChallengeAmount declines to block).
+     */
+    async tokenUsd(symbol, envVar) {
+        const env = process.env[envVar];
         if (env !== undefined) {
             const v = parseFloat(env);
             if (Number.isFinite(v) && v > 0)
-                return { usd: v, source: deployment.nativeUsdEnv };
+                return { usd: v, source: envVar };
         }
-        const symbol = deployment.chain.nativeCurrency.symbol.toUpperCase();
         const fresh = this.priceCache && Date.now() - this.priceCache.at < 60_000;
         if (!fresh) {
             try {
@@ -771,10 +798,7 @@ export class AiFinPayAgent {
         let balance;
         let gasPrice;
         try {
-            [balance, gasPrice] = await Promise.all([
-                publicClient.getBalance({ address }),
-                publicClient.getGasPrice(),
-            ]);
+            [balance, gasPrice] = await Promise.all([publicClient.getBalance({ address }), publicClient.getGasPrice()]);
         }
         catch {
             // An RPC that will not answer must not turn into a funding error; let
@@ -795,7 +819,7 @@ export class AiFinPayAgent {
             return s.includes(".") ? s.replace(/(\.\d{6})\d+$/, "$1").replace(/\.?0+$/, "") || "0" : s;
         };
         const { usd } = await this.nativeUsdFor(deployment);
-        const toUsd = (wei) => Number.isFinite(usd) ? (Number(wei) / 1e18) * usd : Number.NaN;
+        const toUsd = (wei) => (Number.isFinite(usd) ? (Number(wei) / 1e18) * usd : Number.NaN);
         throw new InsufficientFundsError(toUsd(needed), toUsd(balance), `Agent ${address} holds ${short(balance)} ${symbol} on ${chainName}, but this call needs ` +
             `about ${short(needed)} ${symbol} — ${short(valueWei)} for the payment and up to ` +
             `${short(gasBudget)} for gas. The gas figure is a ceiling: it assumes 200k gas at the ` +
@@ -909,8 +933,8 @@ export class AiFinPayAgent {
     async bridgeQuote(opts) {
         const fromToken = opts.fromToken ?? USDC_NATIVE[opts.fromChain];
         const toToken = opts.toToken ?? USDC_NATIVE[opts.toChain];
-        const fromAmount = opts.fromAmount
-            ?? (opts.amount_usdc !== undefined
+        const fromAmount = opts.fromAmount ??
+            (opts.amount_usdc !== undefined
                 ? Math.round(opts.amount_usdc * 1e6).toString() // USDC has 6 decimals
                 : undefined);
         if (!fromAmount) {
@@ -948,14 +972,10 @@ export class AiFinPayAgent {
     }
     // ── Call ────────────────────────────────────────────────────────────────
     /**
-     * High-level paid call. Resolves the provider, picks a chain, builds the
-     * payment, sends to the bridge, retries with payment proof.
-     *
-     * EVM settlement: per-call splitter via on-chain `B2BSplitter.payMatic()`
-     * (generic native-token entrypoint) on any SPLITTER_DEPLOYMENTS chain —
-     * polygon (default), base, optimism, unichain, botchain, xrplevm. Pass
-     * `chain` in CallOptions to override (the provider must accept it).
-     * Solana settlement: b2b_pay_with_split (live since 2026-05-18).
+     * Legacy bridge call. Free/read-only bridge responses are passed through;
+     * paid 402 challenges fail closed because this legacy settlement surface has
+     * no independently reviewed target. Use the reviewed fetchPaid v1.3 route
+     * with a fresh trusted quote/FX result for paid requests.
      *
      * Returns `null` (instead of a `Response`) iff a budget cap was hit
      * AND budget.on_limit_exceeded is set to "skip" — the call is dropped
@@ -975,7 +995,7 @@ export class AiFinPayAgent {
         const reservation = await this.reserveDaily(cost);
         if (reservation === "skip")
             return null;
-        let settled = false;
+        const settled = false;
         try {
             if (provider.mode === "session") {
                 throw new AiFinPayError(`Provider ${provider.name} requires session mode — use openSession() (phase-3 feature)`);
@@ -1000,8 +1020,7 @@ export class AiFinPayAgent {
                 headers: { "content-type": "application/json", ...extraHeaders },
                 body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
                 // CallOptions.timeoutMs was previously declared but never applied.
-                signal: opts.signal
-                    ?? (opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined),
+                signal: opts.signal ?? (opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined),
             });
             // 1. Initial unauthenticated POST → expect 402 challenge from the bridge.
             const fullUrl = url.replace(/\/$/, "") + path;
@@ -1020,119 +1039,22 @@ export class AiFinPayAgent {
             catch (e) {
                 throw new X402Error(`bridge returned 402 with non-JSON body`);
             }
-            // ── Solana branch (b2b_pay_with_split atomic split, live 2026-05-18) ──
-            if (chain === "solana") {
-                if (!challenge.pay_solana) {
-                    throw new X402Error(`Bridge ${provider.name} returned 402 without a pay_solana block. ` +
-                        `Either pick chain: "polygon" or ask the operator to set ` +
-                        `BRIDGE_MERCHANT_SOLANA on the bridge service.`);
-                }
-                const ps = challenge.pay_solana;
-                // Guard: the bridge controls the challenge — verify the demanded
-                // amount is in the same ballpark as the declared cost / caps before
-                // signing anything. Stops a misquoting bridge from draining the agent.
-                {
-                    const lamports = Number(ps.total_lamports ?? ps.merchant_amount_lamports);
-                    const solUsd = parseFloat(process.env.AIFINPAY_SOL_USD ?? "200");
-                    const estUsd = (Number.isFinite(lamports) ? lamports / 1e9 : 0) * solUsd;
-                    const guarded = this.guardChallengeAmount(estUsd, cost, provider.name);
-                    if (!guarded)
-                        return null;
-                }
-                const solTxSig = await this.submitSolanaB2BPayWithSplit(ps);
-                const paidResp = await this.inner.fetchImpl(fullUrl, buildInit({
-                    "x-solana-tx": solTxSig,
-                    "x-order-id": ps.order_id,
-                }));
-                if (!paidResp.ok) {
-                    const detail = await paidResp.text().catch(() => "<unreadable>");
-                    throw new AiFinPayError(`Bridge retry failed ${paidResp.status} after Solana payment ${solTxSig}: ${detail.slice(0, 300)}`);
-                }
-                // Money moved here, and only here. The reservation becomes a
-                // settled amount; the finally below then has nothing to release.
-                this.spend24h.add(cost);
-                if (typeof reservation === "string") {
-                    await this.ledger.commit(reservation, cost);
-                }
-                settled = true;
-                if (this.telemetry)
-                    this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, tx: solTxSig });
-                // @internal — attach settlement metadata for consumers (MCP, telemetry
-                // dashboards) that need to surface the tx hash without an extra RPC
-                // call. Response headers are read-only after construction so we use
-                // an instance property + cast on the read side.
-                paidResp.aifinpayTx = solTxSig;
-                paidResp.aifinpayChain = "solana";
-                return paidResp;
-            }
-            // ── EVM branch (B2BSplitter.payMatic — generic native-token atomic split) ──
-            // Settles on any chain in SPLITTER_DEPLOYMENTS (polygon default; base,
-            // optimism, unichain, botchain, xrplevm). Native token only — the
-            // deployed splitter payment path has no ERC-20/USDC entrypoint.
-            const pm = nativePayBlock(challenge);
-            if (!pm) {
-                throw new X402Error(`bridge ${provider.name} returned 402 with neither a pay_native nor a pay_matic block — it is speaking a protocol this SDK does not implement (fields: ${Object.keys(challenge).join(", ")})`);
+            // Legacy bridge settlement is fail-closed. The challenge historically
+            // supplied arbitrary splitter/program addresses and native amounts, so
+            // continuing from here could sign against an unreviewed target or let a
+            // missing price bypass the budget. Keep free/read-only calls above, but
+            // refuse every paid legacy challenge before any signing or broadcast.
+            if (!(typeof provider.price_usd === "number" && Number.isFinite(provider.price_usd) && provider.price_usd > 0) ||
+                !(typeof cost === "number" && Number.isFinite(cost) && cost > 0)) {
+                throw new AiFinPayError(`legacy call() refused ${provider.name}: the provider has no trusted positive USD price; ` +
+                    `use the reviewed fetchPaid v1.3 route with fresh trusted FX instead`);
             }
-            const deployment = SPLITTER_DEPLOYMENTS[chain];
-            if (!deployment) {
-                throw new AiFinPayError(`No B2BSplitter deployment registered for chain "${chain}" — supported: ${Object.keys(SPLITTER_DEPLOYMENTS).join(", ")}`);
+            if (!legacySettlementIsReviewed()) {
+                throw new AiFinPayError(`legacy call() settlement is disabled: challenge targets are not trusted for mainnet payment; ` +
+                    `use fetchPaid with a reviewed v1.3 settlement pin and fresh trusted FX`);
             }
-            // Refuse to pay a quote denominated for another chain's native token:
-            // total_wei quoted for POL on Polygon would be a massive overpay if
-            // blindly re-sent as ETH on Base. Legacy bridges always emit "polygon".
-            if (pm.chain && pm.chain !== chain) {
-                throw new X402Error(`bridge ${provider.name} quoted a native payment for chain "${pm.chain}" but the call was routed to "${chain}" — refusing cross-denomination payment`);
-            }
-            // Guard: same ballpark check as the Solana branch — never sign for an
-            // amount wildly above the declared cost / per-call cap. Native-token
-            // USD price per chain via SPLITTER_DEPLOYMENTS.nativeUsdEnv.
-            {
-                const wei = Number(pm.total_wei);
-                const { usd: nativeUsd } = await this.nativeUsdFor(deployment);
-                // NaN when no price is known — guardChallengeAmount then declines to
-                // block rather than blocking on a guess. See nativeUsdFor().
-                const estUsd = (Number.isFinite(wei) ? wei / 1e18 : 0) * nativeUsd;
-                const guarded = this.guardChallengeAmount(estUsd, cost, provider.name);
-                if (!guarded)
-                    return null;
-            }
-            // 2. Submit the B2BSplitter payment on the selected chain's mainnet and
-            // wait for it to land. Prefer the challenge's splitter address (current
-            // bridge behaviour); fall back to the registry address for bridges that
-            // omit it.
-            const splitterAddress = pm.splitter
-                ?? deployment.splitter;
-            const txHash = await this.settleSplitterNative({
-                chain,
-                splitter: splitterAddress,
-                splitterVersion: pm.splitter_version,
-                merchantWallet: pm.merchant_wallet,
-                totalWei: BigInt(pm.total_wei),
-                orderId: pm.order_id,
-                ipCreator: pm.ip_creator,
-            });
-            // 3. Retry the bridge with payment proof.
-            const paidResp = await this.inner.fetchImpl(fullUrl, buildInit({
-                "x-tx-hash": txHash,
-                "x-order-id": pm.order_id,
-            }));
-            if (!paidResp.ok) {
-                const detail = await paidResp.text().catch(() => "<unreadable>");
-                throw new AiFinPayError(`Bridge retry failed ${paidResp.status} after on-chain payment ${txHash}: ${detail.slice(0, 300)}`);
-            }
-            // Money moved here, and only here. The reservation becomes a
-            // settled amount; the finally below then has nothing to release.
-            this.spend24h.add(cost);
-            if (typeof reservation === "string") {
-                await this.ledger.commit(reservation, cost);
-            }
-            settled = true;
-            if (this.telemetry)
-                this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, tx: txHash });
-            // @internal — see Solana branch above for rationale on property-attach.
-            paidResp.aifinpayTx = txHash;
-            paidResp.aifinpayChain = chain;
-            return paidResp;
+            throw new AiFinPayError(`legacy call() settlement is disabled: challenge targets are not trusted for mainnet payment; ` +
+                `use fetchPaid with a reviewed v1.3 settlement pin and fresh trusted FX`);
         }
         finally {
             // Every path that did not move money gives the budget back now rather
@@ -1156,87 +1078,14 @@ export class AiFinPayAgent {
     // a reverted transaction would otherwise be handed to a merchant as proof of
     // a payment that never moved.
     async settleSplitterNative(p) {
-        // call() has already checked this for the bridge flow; repeated here
-        // because settlement is now reachable without going through call().
-        const deployment = SPLITTER_DEPLOYMENTS[p.chain];
-        if (!deployment) {
-            throw new AiFinPayError(`No B2BSplitter deployment registered for chain "${p.chain}" — supported: ${Object.keys(SPLITTER_DEPLOYMENTS).join(", ")}`);
-        }
-        // ipCreator routing: the caller's explicit ip_creator, or address(0).
-        //
-        // This used to fall back to the splitter's own treasury, on the reasoning
-        // that address(0) "would skip the transfer and permanently strand the 1bp
-        // inside B2BSplitter — the contract has no sweep function". That premise is
-        // false. B2BSplitter._split(), lines 238-244:
-        //
-        //     if (_ipCreator != address(0)) { ipAmt = _total * ipCreatorBps / D; }
-        //     // else: ipAmt stays 0 and is absorbed into merchantAmt below
-        //     merchantAmt = _total - treasuryAmt - ipAmt;
-        //
-        // With address(0) the royalty is not stranded — it is folded into the
-        // MERCHANT's leg, which is where it belongs when no creator was named. The
-        // fallback therefore took 1bp off every payment whose merchant had not set
-        // a creator, and paid it to OUR treasury.
-        //
-        // Fixed in the Python client on 2026-08-27 and not ported here. That is the
-        // third instance this week of one implementation being corrected and its
-        // twin left alone; the others were gate/src/scope.ts and this file.
-        const ipCreator = p.ipCreator ?? "0x0000000000000000000000000000000000000000";
-        const { publicClient, walletClient } = this.splitterClients(p.chain);
-        // The entrypoint follows the deployed contract, not the SDK release: v1.2
-        // (Polygon, Optimism, BOT Chain, XRPL EVM as of 2026-07-31) takes a bytes32
-        // paymentId and rejects one it has already settled, while Base and Unichain
-        // still run v1.1. Sending v1.2 calldata to a v1.1 contract reverts with no
-        // useful reason, so this must be decided per chain.
-        // An explicit `splitterVersion` wins — a server that states it knows what
-        // it deployed. What it must NOT fall back to is this registry's
-        // chain -> version entry, because the ADDRESS came from the server and
-        // the version would come from a table: two sources that can disagree.
-        //
-        // In production they did. The Exa bridge still hands out the pre-v1.2
-        // splitter 0xE34Fc0E6… and sends no version; the table says "polygon is
-        // 1.2"; the SDK called payNative on a contract that only has payMatic, and
-        // the payment reverted with nothing in the reason to explain it.
-        //
-        // So when the server is silent, ask the contract at the address we were
-        // actually handed. The registry is used only if the chain cannot be read.
-        const splitterVersion = p.splitterVersion
-            ?? await this.detectSplitterVersion(p.splitter, p.chain, deployment.version);
-        await this.assertCanAffordNative(publicClient, deployment, p.totalWei);
-        const txHash = splitterVersion === "1.2"
-            ? await walletClient.writeContract({
-                address: p.splitter,
-                abi: SPLITTER_PAY_NATIVE_ABI,
-                functionName: "payNative",
-                args: [
-                    paymentIdFor(p.orderId),
-                    p.merchantWallet,
-                    ipCreator,
-                    p.orderId,
-                ],
-                value: p.totalWei,
-                chain: deployment.chain,
-                account: this.evmAccount,
-            })
-            : await walletClient.writeContract({
-                address: p.splitter,
-                abi: SPLITTER_PAY_MATIC_ABI,
-                functionName: "payMatic",
-                args: [
-                    p.merchantWallet,
-                    ipCreator,
-                    p.orderId,
-                ],
-                value: p.totalWei,
-                chain: deployment.chain,
-                account: this.evmAccount,
-            });
-        // Wait for receipt (inclusion is enough on these fast-block chains).
-        const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
-        if (receipt.status !== "success") {
-            throw new AiFinPayError(`${deployment.chain.name} tx reverted: ${txHash}`);
-        }
-        return txHash;
+        void p;
+        throw new AiFinPayError("legacy splitter settlement is disabled; use fetchPaid with a reviewed v1.3 settlement pin");
+    }
+    // Legacy Solana settlement remains a named private surface only so older
+    // callers fail with a clear migration error instead of reaching a signer.
+    async submitSolanaB2BPayWithSplit(ps) {
+        void ps;
+        throw new AiFinPayError("legacy Solana settlement is disabled; use fetchPaid with a reviewed v1.3 settlement pin");
     }
     // ── AIFP-1 merchant paywall (gateway.aifinpay.io) ───────────────────────
     //
@@ -1252,16 +1101,43 @@ export class AiFinPayAgent {
      * test asserting that a receipt was reused, both need to see it. The entries
      * contain bearer JWTs — treat them like keys, and do not log them.
      */
-    get aifp1Receipts() { return this._aifp1Cache; }
+    get aifp1Receipts() {
+        return this._aifp1Cache;
+    }
     /**
-     * Legacy fetchPaid cannot safely execute a v1.3 quote yet: it has no
-     * independently pinned runtime hash/profile input. Keep it fail-closed until
-     * it is wired through SettlementClient + executeSettlementInvoice.
-     *
-     * Tests replace this method with a chain stub; production never signs here.
+     * Redacted receipt-cache view (no bearer JWTs): what batches this instance
+     * holds, for shutdown decisions and dashboards. Safe to log and to expose
+     * over MCP — use this, never `aifp1Receipts.list()`.
      */
-    async settleAifp1NativeV13(_p) {
-        throw new AiFinPayError("AIFP-1 fetchPaid settlement is disabled until a trusted v1.3 deployment/runtime profile is supplied; use SettlementClient with an independent TrustedSettlementRoutePin");
+    getReceiptCacheSummary() {
+        return this._aifp1Cache.summary();
+    }
+    /**
+     * Use the canonical invoice executor only with a caller-supplied deployment
+     * pin. An unauthenticated quote cannot establish its own signing authority.
+     */
+    async settleAifp1NativeV13(p, opts) {
+        const pin = opts.settlementPin;
+        if (!pin || pin.route_class !== "AIFP-1" || pin.chain !== "polygon" || pin.testnet) {
+            throw new AiFinPayError("AIFP-1 fetchPaid requires an independent trusted Polygon v1.3 settlement pin; other receipt networks are not supported");
+        }
+        const client = new SettlementClient({
+            baseUrl: opts.apiBaseUrl ?? "https://api.aifinpay.io",
+            fetchImpl: this.inner.fetchImpl,
+            timeoutMs: this.inner.timeoutMs,
+        });
+        const invoice = await client.invoice({
+            route_class: "AIFP-1",
+            chain: "polygon",
+            asset: "POL",
+            gross_amount: p.grossWei,
+            merchant_wallet: p.merchantWallet,
+            order_id: p.orderId,
+            valid_until: Number(p.validUntil),
+        });
+        const { publicClient, walletClient } = this.polygonClients();
+        const execution = await executeSettlementInvoice(invoice, walletClient, publicClient, pin);
+        return execution.settlement_tx;
     }
     /**
      * Fetch a paywalled URL, paying the AIFP-1 gateway if it asks.
@@ -1285,7 +1161,9 @@ export class AiFinPayAgent {
             // (backend/aifp/agent-policy.js normalizeAddress) — a Solana pubkey here
             // would silently opt the agent out of its owner's own limits.
             agentId: opts.agentId ?? this.evmAddress,
-            settle: (p) => this.settleAifp1NativeV13(p),
+            payerAddress: this.evmAddress,
+            signPaymentAuthorization: (message) => this.evmAccount.signMessage({ message }),
+            settle: (p) => this.settleAifp1NativeV13(p, opts),
             checkPerCall: (usd) => this.checkPerCall(usd),
             reserveDaily: (usd) => this.reserveDaily(usd),
             commit: (id, usd) => this.ledger.commit(id, usd),
@@ -1294,77 +1172,57 @@ export class AiFinPayAgent {
                 this.spend24h.add(amountUsd);
                 if (this.telemetry) {
                     this.reportTelemetry({
-                        kind: "aifp1", merchant: merchantId, chain: "polygon",
-                        cost: amountUsd, tx: txRef,
+                        kind: "aifp1",
+                        merchant: merchantId,
+                        chain: "polygon",
+                        cost: amountUsd,
+                        tx: txRef,
                     });
                 }
             },
         };
         return aifp1Fetch(deps, url, init, opts);
     }
-    // ── Solana b2b_pay_with_split — build, sign, send via @solana/web3.js ───
-    //
-    // Manual instruction encoding (no Anchor dep):
-    //   discriminator = sha256("global:b2b_pay_with_split")[:8]
-    //   args (Borsh)   = u64 merchant_amount_lamports + string order_id
-    //   accounts       = [config_pda, vault_pda, agent (signer), treasury,
-    //                     ip_creator, merchant_wallet, system_program]
-    // PDAs derived from program_id with seeds ["config"] and ["vault"].
-    async submitSolanaB2BPayWithSplit(ps) {
-        const conn = new Connection(this.solanaRpc, "confirmed");
-        const programId = new PublicKey(ps.program_id);
-        const merchant = new PublicKey(ps.merchant_wallet);
-        const treasury = new PublicKey(ps.treasury);
-        // ip_creator slot: not surfaced by current bridge 402s; route through
-        // treasury so the on-chain 1bp still settles atomically (treasury earns
-        // both 100bp + 1bp). When bridges add per-merchant ip_creator support,
-        // accept it from `ps` and pass through.
-        const ipCreator = treasury;
-        // Solana keypair from legacy Agent inner (tweetnacl 64-byte secret).
-        const kp = Keypair.fromSecretKey(this.inner.secretKey);
-        if (kp.publicKey.toString() !== this.inner.address) {
-            throw new AiFinPayError(`Internal: Solana keypair pubkey ${kp.publicKey.toString()} does not match agent address ${this.inner.address}`);
-        }
-        // PDAs
-        const [configPda] = PublicKey.findProgramAddressSync([Buffer.from("config")], programId);
-        const [vaultPda] = PublicKey.findProgramAddressSync([Buffer.from("vault")], programId);
-        // Instruction discriminator: Anchor convention sha256("global:<fn_name>")[:8].
-        const disc = createHash("sha256").update("global:b2b_pay_with_split").digest().subarray(0, 8);
-        // Borsh args: merchant_amount_lamports (u64 LE) + order_id (string = u32 len + utf8)
-        const merchantAmount = BigInt(ps.merchant_amount_lamports);
-        const amountBuf = Buffer.alloc(8);
-        amountBuf.writeBigUInt64LE(merchantAmount);
-        const orderBytes = Buffer.from(ps.order_id, "utf8");
-        if (orderBytes.length > 64) {
-            throw new AiFinPayError(`order_id too long (${orderBytes.length} bytes > 64 limit)`);
-        }
-        const orderLenBuf = Buffer.alloc(4);
-        orderLenBuf.writeUInt32LE(orderBytes.length);
-        const data = Buffer.concat([disc, amountBuf, orderLenBuf, orderBytes]);
-        const ix = new TransactionInstruction({
-            programId,
-            keys: [
-                { pubkey: configPda, isSigner: false, isWritable: false },
-                { pubkey: vaultPda, isSigner: false, isWritable: false },
-                { pubkey: kp.publicKey, isSigner: true, isWritable: true },
-                { pubkey: treasury, isSigner: false, isWritable: true },
-                { pubkey: ipCreator, isSigner: false, isWritable: true },
-                { pubkey: merchant, isSigner: false, isWritable: true },
-                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
-            ],
-            data,
+    /**
+     * List verified settlement routes. Non-signing: fetches + returns the
+     * backend route table (same client the MCP `settlement_routes` tool should
+     * use instead of its own inline HTTP). Never signs or broadcasts.
+     */
+    async settlementRoutes(routeClass, baseUrl) {
+        return this.settlementClient(baseUrl).routes(routeClass);
+    }
+    /**
+     * Request a settlement invoice and validate it (canonical split,
+     * chain binding, request match). Non-signing: returns the invoice for
+     * display/approval. Never signs or broadcasts.
+     */
+    async requestSettlementInvoice(input, baseUrl) {
+        return this.settlementClient(baseUrl).invoice(input);
+    }
+    settlementClient(baseUrl) {
+        return new SettlementClient({
+            baseUrl: baseUrl ?? "https://api.aifinpay.io",
+            fetchImpl: this.inner.fetchImpl,
+            timeoutMs: this.inner.timeoutMs,
         });
-        const tx = new Transaction().add(ix);
-        // sendAndConfirmTransaction sets recentBlockhash + feePayer + signs.
-        const sig = await sendAndConfirmTransaction(conn, tx, [kp], {
-            commitment: "confirmed",
-            preflightCommitment: "confirmed",
+    }
+    /**
+     * Prepaid quota batches for this agent's address, most room first with a
+     * per-merchant rollup. Non-signing read of retained receipts metadata.
+     */
+    async getQuota(opts = {}) {
+        return getQuota({
+            address: this.evmAddress,
+            merchantId: opts.merchantId,
+            includeExhausted: opts.includeExhausted,
+            baseUrl: opts.baseUrl,
+            fetchImpl: this.inner.fetchImpl,
         });
-        return sig;
     }
     // ── Sessions ────────────────────────────────────────────────────────────
     /**
      * TODO(phase-3): open a metered budget session.
+     * @deprecated Not implemented — always throws. Tracked for phase 3; do not call.
      */
     async openSession(_args) {
         throw new AiFinPayError("openSession() not implemented yet — see migration phase 3");
@@ -1373,24 +1231,32 @@ export class AiFinPayAgent {
     /**
      * Snapshot the agent's funds across both chains, USD-normalised.
      *
-     * Phase 1.4: native MATIC + native SOL via RPC; ERC-20 / SPL token balances
-     * deferred (we don't yet need them for the unified `call()` flow which
-     * settles in MATIC). Pyth feeds are TODO; for now uses
-     * `AIFINPAY_MATIC_USD` and `AIFINPAY_SOL_USD` env, defaulting to 0.7 and 200.
+     * Native prices are env-first (`AIFINPAY_MATIC_USD` / `AIFINPAY_SOL_USD`),
+     * then the protocol price feed — never a stale compiled-in constant. A leg
+     * with no known price is excluded from the total and listed in
+     * `unknown_legs` instead of being fabricated.
      */
     async balance() {
-        const maticUsd = parseFloat(process.env.AIFINPAY_MATIC_USD ?? "0.70");
-        const solUsd = parseFloat(process.env.AIFINPAY_SOL_USD ?? "200");
+        const [pol, sol] = await Promise.all([
+            this.tokenUsd("POL", SPLITTER_DEPLOYMENTS.polygon.nativeUsdEnv),
+            this.tokenUsd("SOL", "AIFINPAY_SOL_USD"),
+        ]);
         const polygon = await this.fetchPolygonNative().catch(() => 0);
         const solana = await this.fetchSolanaNative().catch(() => 0);
         const solana_usdc = await this.fetchSolanaUsdc().catch(() => 0);
         const polygon_usdc = await this.fetchPolygonUsdc().catch(() => 0);
-        const polygonUsd = polygon * maticUsd;
-        const solanaUsd = solana * solUsd;
-        const solanaUsdcUsd = solana_usdc; // USDC ≈ $1
-        const polygonUsdcUsd = polygon_usdc; // USDC ≈ $1
+        const unknown_legs = [];
+        let agent_balance_usd = solana_usdc + polygon_usdc; // USDC ≈ $1
+        if (Number.isFinite(pol.usd))
+            agent_balance_usd += polygon * pol.usd;
+        else
+            unknown_legs.push("pol");
+        if (Number.isFinite(sol.usd))
+            agent_balance_usd += solana * sol.usd;
+        else
+            unknown_legs.push("sol");
         return {
-            agent_balance_usd: polygonUsd + solanaUsd + solanaUsdcUsd + polygonUsdcUsd,
+            agent_balance_usd,
             chains: {
                 solana: { sol: solana, usdc: solana_usdc, msecco_balance: 0 },
                 polygon: { matic: polygon, usdc: polygon_usdc, msecco_balance: 0 },
@@ -1398,6 +1264,8 @@ export class AiFinPayAgent {
             spend_24h_usd: this.spend24h.total24h(),
             budget_caps: this.budgetCaps,
             priced_at: Math.floor(Date.now() / 1000),
+            prices: { pol, sol },
+            ...(unknown_legs.length ? { unknown_legs } : {}),
         };
     }
     async fetchPolygonNative() {
@@ -1444,11 +1312,7 @@ export class AiFinPayAgent {
                     jsonrpc: "2.0",
                     id: 1,
                     method: "getTokenAccountsByOwner",
-                    params: [
-                        this.solanaAddress,
-                        { mint: USDC_SOLANA_MINT },
-                        { encoding: "jsonParsed" },
-                    ],
+                    params: [this.solanaAddress, { mint: USDC_SOLANA_MINT }, { encoding: "jsonParsed" }],
                 }),
             });
             if (!r.ok)
@@ -1486,8 +1350,8 @@ export class AiFinPayAgent {
      * six registry chains against mainnet.
      *
      * One eth_getCode, cached per (chain, address). Falls back to the registry
-     * only when the code cannot be read: guessing beats refusing to pay, and for
-     * the addresses we deployed the guess is right.
+     * only for this read-only diagnostic when code cannot be read. The legacy
+     * payment path is disabled regardless of the reported or detected version.
      */
     splitterVersionCache = new Map();
     async detectSplitterVersion(splitter, chainName, fallback) {
@@ -1533,6 +1397,7 @@ export class AiFinPayAgent {
     // ── Reputation ──────────────────────────────────────────────────────────
     /**
      * TODO(phase-4 / phase-5): query operator backend reputation engine.
+     * @deprecated Zero-stub — returns unverified zeros until the engine lands; do not treat as signal.
      */
     async reputation() {
         return {
@@ -1546,13 +1411,19 @@ export class AiFinPayAgent {
     // ── Telemetry (opt-out) ─────────────────────────────────────────────────
     reportTelemetry(payload) {
         // Fire-and-forget. No body content, only metadata.
-        void this.inner.fetchImpl(`${this.inner.baseUrl}/api/telemetry`, {
+        void this.inner
+            .fetchImpl(`${this.inner.baseUrl}/api/telemetry`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({ agent_id: this.id, ...payload, ts: Date.now() }),
-        }).catch(() => { });
+        })
+            .catch(() => { });
     }
 }
+/** Legacy bridge settlement has no reviewed mainnet route; keep this closed. */
+function legacySettlementIsReviewed() {
+    return false;
+}
 // ── Internal hex helpers (small, no extra deps) ────────────────────────────
 function hexToBytes(hex) {
     const out = new Uint8Array(hex.length / 2);