@aifinpay/agent 0.3.0-alpha.4 → 1.0.0

package/dist/unifiedAgent.js

@@ -14,10 +14,11 @@ import bs58 from "bs58";
 import { createHash } from "node:crypto";
 import { createPublicClient, createWalletClient, http, } from "viem";
 import { privateKeyToAccount, generatePrivateKey, } from "viem/accounts";
-import { polygon } from "viem/chains";
+import { polygon, base, arbitrum, optimism, bsc, mainnet } from "viem/chains";
 import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction, } from "@solana/web3.js";
 import { AiFinPayError, X402Error, } from "./errors.js";
 import { Agent } from "./agent.js";
+import { bridgeQuote as crossChainQuote, bridgeExecute as crossChainExecute, bridgeWaitForArrival, USDC_NATIVE, } from "./crossChain.js";
 // ── B2BSplitter contract (deployed at 0xE34Fc0…8440 on Polygon mainnet) ──
 const SPLITTER_PAY_MATIC_ABI = [
     {
@@ -32,6 +33,40 @@ const SPLITTER_PAY_MATIC_ABI = [
         outputs: [],
     },
 ];
+// ── EVM chain object lookup — viem chains keyed by our EvmChainName ─────
+const EVM_CHAIN_OBJECTS = {
+    ethereum: mainnet,
+    polygon,
+    bsc,
+    arbitrum,
+    optimism,
+    base,
+};
+// Mainnet USDC SPL mint on Solana (Circle native, not Wormhole-wrapped USDCet)
+const USDC_SOLANA_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+// Native Polygon USDC ERC20 (Circle-native, not bridged USDC.e)
+const USDC_POLYGON_ERC20 = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359";
+// Minimal ERC20 balanceOf ABI fragment
+const ERC20_BALANCE_OF_ABI = [
+    {
+        type: "function",
+        name: "balanceOf",
+        stateMutability: "view",
+        inputs: [{ type: "address", name: "owner" }],
+        outputs: [{ type: "uint256" }],
+    },
+];
+// B2BSplitter.treasury() view — used to route the ipCreator royalty slot
+// when the bridge challenge doesn't name a recipient.
+const SPLITTER_TREASURY_ABI = [
+    {
+        type: "function",
+        name: "treasury",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ type: "address" }],
+    },
+];
 // ── Errors ─────────────────────────────────────────────────────────────────
 export class ProviderUnknownError extends AiFinPayError {
 }
@@ -104,6 +139,10 @@ export class AiFinPayAgent {
     telemetry;
     _polygonPublic;
     _polygonWallet;
+    // Multi-chain client cache for cross-chain orchestration (bridge flows).
+    // Keyed by EVM chain name (see crossChain.ts EVM_CHAINS).
+    _evmClients = new Map();
+    evmRpcUrls = {};
     constructor(inner, evmAccount, opts = {}) {
         this.inner = inner;
         this.evmAccount = evmAccount;
@@ -115,8 +154,16 @@ export class AiFinPayAgent {
         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)
+            this.evmRpcUrls = opts.evmRpcUrls;
+        if (this.polygonRpc)
+            this.evmRpcUrls.polygon = this.polygonRpc;
     }
     // Lazy viem clients — only spun up when a Polygon flow runs.
+    // Kept as-is for the legacy call() Polygon path; cross-chain flows use
+    // evmClients() below which is generalised across all supported EVM chains.
     polygonClients() {
         if (!this._polygonPublic) {
             this._polygonPublic = createPublicClient({
@@ -133,6 +180,26 @@ export class AiFinPayAgent {
         }
         return { publicClient: this._polygonPublic, walletClient: this._polygonWallet };
     }
+    // Multi-EVM-chain client cache. Used by bridge orchestration to sign source
+    // and (optionally) dest transactions on chains other than Polygon. Picks
+    // viem's built-in chain definitions; an optional RPC override per chain
+    // can be supplied via opts.evmRpcUrls.
+    evmClients(name) {
+        const cached = this._evmClients.get(name);
+        if (cached)
+            return cached;
+        const chain = EVM_CHAIN_OBJECTS[name];
+        if (!chain) {
+            throw new AiFinPayError(`evmClients: unsupported EVM chain "${name}"`);
+        }
+        const rpcUrl = this.evmRpcUrls[name];
+        const transport = rpcUrl ? http(rpcUrl) : http();
+        const publicClient = createPublicClient({ chain, transport });
+        const walletClient = createWalletClient({ chain, transport, account: this.evmAccount });
+        const pair = { publicClient, walletClient };
+        this._evmClients.set(name, pair);
+        return pair;
+    }
     // ── Constructors ─────────────────────────────────────────────────────────
     /**
      * Generate a fresh agent — new Solana keypair + new EVM keypair.
@@ -150,9 +217,11 @@ export class AiFinPayAgent {
      * chains.
      *
      * Solana key = nacl.sign.keyPair.fromSeed(seed)
-     * EVM key    = keccak256(seed)[:32]    (independent path; not BIP-44
-     *                                       compatible — see design notes
-     *                                       in 23 - Unified SDK Design).
+     * EVM key    = SHA-256("aifinpay:evm:v1\0" || seed)
+     *              (domain-separated; independent path; not BIP-44 — see
+     *               design notes in 23 - Unified SDK Design. This is the
+     *               canonical derivation both SDKs implement — the Python
+     *               SDK mirrors it byte-for-byte.)
      *
      * 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
@@ -172,12 +241,21 @@ export class AiFinPayAgent {
         return new AiFinPayAgent(inner, evmAccount, opts);
     }
     /**
-     * Legacy: load the Solana side from an existing keypair, then either
-     * generate a fresh EVM key or import one with `attachEvmKey`.
+     * Legacy: load the Solana side from an existing keypair. The EVM key is
+     * derived deterministically from the Solana secret's 32-byte seed
+     * (domain-separated SHA-256, same path as `fromSeed`) unless an explicit
+     * `opts.evmPrivateKey` is provided.
+     *
+     * Why deterministic: a random key here would change the EVM address on
+     * every process restart — anything sent to the previous address becomes
+     * unrecoverable because the key was never persisted or printed. With
+     * derivation, the same AIFINPAY_AGENT_SECRET always reproduces the same
+     * EVM address (this is what the MCP server relies on).
      */
     static async fromSolanaSecret(secretB58, opts = {}) {
         const inner = Agent.fromSecretB58(secretB58, opts);
-        const evmKey = opts.evmPrivateKey ?? generatePrivateKey();
+        const evmKey = opts.evmPrivateKey
+            ?? ("0x" + bytesToHex(crypto32(inner.secretKey.subarray(0, 32))));
         const evmAccount = privateKeyToAccount(evmKey);
         return new AiFinPayAgent(inner, evmAccount, opts);
     }
@@ -208,6 +286,92 @@ export class AiFinPayAgent {
         }
         return hit;
     }
+    // ── Network directory ─────────────────────────────────────────────────────
+    /**
+     * Publish this agent to the public AiFinPay network so other agents can
+     * discover and call it. Self-sovereign: proves control of the EVM address by
+     * signing a one-time nonce with the agent's own key (EIP-191) — no partner
+     * account needed.
+     */
+    async register(opts) {
+        const base = this.inner.baseUrl;
+        const addr = this.evmAddress.toLowerCase();
+        const nonce = await this.networkNonce();
+        const message = `AiFinPay-network-publish:polygon:${addr}:${nonce}`;
+        const signature = await this.evmAccount.signMessage({ message });
+        const r = await fetch(`${base}/api/network/agents/${addr}/publish`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                name: opts.name,
+                description: opts.description ?? null,
+                endpoint: opts.endpoint,
+                capabilities: opts.capabilities ?? [],
+                pricing: opts.pricing
+                    ? { per_call: opts.pricing.perCall, currency: opts.pricing.currency ?? "USDC" }
+                    : null,
+                nonce,
+                signature,
+            }),
+        });
+        const j = (await r.json().catch(() => ({})));
+        if (!r.ok || !j.ok || !j.agent) {
+            throw new AiFinPayError(`network publish failed: ${j.error ?? r.status}`);
+        }
+        return j.agent;
+    }
+    /** Remove this agent from the public network directory (same signature proof). */
+    async unregister() {
+        const base = this.inner.baseUrl;
+        const addr = this.evmAddress.toLowerCase();
+        const nonce = await this.networkNonce();
+        const message = `AiFinPay-network-unpublish:polygon:${addr}:${nonce}`;
+        const signature = await this.evmAccount.signMessage({ message });
+        const r = await fetch(`${base}/api/network/agents/${addr}/unpublish`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ nonce, signature }),
+        });
+        if (!r.ok) {
+            const j = (await r.json().catch(() => ({})));
+            throw new AiFinPayError(`network unpublish failed: ${j.error ?? r.status}`);
+        }
+    }
+    /**
+     * Search the public network for agents advertising a capability or matching a
+     * free-text query. Pass a bare string to search by capability
+     * (`agent.search("weather")`) or an object for finer control. Returns the
+     * directory entries; invoking one (pay + call) lands in a later release.
+     */
+    async search(query) {
+        const base = this.inner.baseUrl;
+        const params = new URLSearchParams();
+        if (typeof query === "string") {
+            params.set("capability", query);
+        }
+        else {
+            if (query.capability)
+                params.set("capability", query.capability);
+            if (query.q)
+                params.set("q", query.q);
+            if (query.limit)
+                params.set("limit", String(query.limit));
+        }
+        const r = await fetch(`${base}/api/network/agents?${params.toString()}`);
+        if (!r.ok)
+            throw new AiFinPayError(`network search ${base} → ${r.status}`);
+        const j = (await r.json());
+        return j.agents ?? [];
+    }
+    async networkNonce() {
+        const r = await fetch(`${this.inner.baseUrl}/api/network/nonce`);
+        if (!r.ok)
+            throw new AiFinPayError(`network nonce → ${r.status}`);
+        const { nonce } = (await r.json());
+        if (!nonce)
+            throw new AiFinPayError("network nonce: empty response");
+        return nonce;
+    }
     // ── Budget caps ─────────────────────────────────────────────────────────
     setBudget(caps) {
         this.budgetCaps = caps;
@@ -242,6 +406,38 @@ export class AiFinPayAgent {
     getSpend24h() {
         return this.spend24h.total24h();
     }
+    /**
+     * Sanity-check the USD estimate of an on-chain challenge amount against
+     * the declared cost and the per-call cap BEFORE signing the tx.
+     *
+     * The estimate uses env-priced MATIC/SOL (AIFINPAY_MATIC_USD /
+     * AIFINPAY_SOL_USD — same stopgap as balance()), so it is approximate.
+     * A 2x + $0.05 tolerance absorbs oracle drift while still catching the
+     * dangerous case: a bridge that quotes $0.01 in the registry and then
+     * demands 100x in the 402 challenge.
+     *
+     * Returns false (skip) instead of throwing when on_limit_exceeded="skip".
+     */
+    guardChallengeAmount(estUsd, declaredCost, providerName) {
+        if (!Number.isFinite(estUsd) || estUsd <= 0)
+            return true; // can't estimate — don't block
+        const limits = [];
+        if (declaredCost > 0)
+            limits.push(Math.max(declaredCost * 2, declaredCost + 0.05));
+        if (this.budgetCaps.per_call_usd !== undefined)
+            limits.push(this.budgetCaps.per_call_usd);
+        if (!limits.length)
+            return true; // no cap declared anywhere — caller opted out
+        const limit = Math.min(...limits);
+        if (estUsd <= limit)
+            return true;
+        const err = new BudgetCapExceededError("per_call", `bridge ${providerName} challenge demands ≈$${estUsd.toFixed(4)} on-chain, ` +
+            `above the allowed $${limit.toFixed(4)} (declared cost/per-call cap). ` +
+            `Set AIFINPAY_MATIC_USD / AIFINPAY_SOL_USD for a tighter estimate.`);
+        if ((this.budgetCaps.on_limit_exceeded ?? "throw") === "skip")
+            return false;
+        throw err;
+    }
     // ── Routing — chain selection ───────────────────────────────────────────
     /**
      * Chain selection heuristic — see Obsidian/23 - Unified SDK Design §Routing.
@@ -302,6 +498,64 @@ export class AiFinPayAgent {
     async deposit(_usd, _opts) {
         throw new AiFinPayError("deposit() not implemented yet — see migration phase 1.5");
     }
+    // ── Cross-chain orchestration (Phase 1.5a: EVM↔EVM via LiFi) ────────────
+    //
+    // We orchestrate; we do not custody. The agent signs every step.
+    // See Obsidian/21 - Unified Agent Economy non-goals.
+    //
+    // Typical flow for "agent has USDC on Base, merchant wants USDC on Polygon":
+    //   const quote   = await agent.bridgeQuote({ fromChain: "base", toChain: "polygon", amount_usdc: 1.0 });
+    //   const receipt = await agent.bridgeExecute(quote);                  // sign source tx
+    //   const arrival = await agent.bridgeWaitForArrival(receipt.source_tx); // wait for dest
+    //   // ...then proceed with agent.call({ provider, chain: "polygon" })
+    /**
+     * Quote a USDC-denominated cross-chain transfer via LiFi.
+     *
+     * The convenience overload takes a USD amount and the chain names; the
+     * full overload accepts arbitrary token addresses for non-USDC corridors.
+     * The agent's EVM address is used as both `fromAddress` and `toAddress`
+     * unless overridden — bridging to a different recipient is rare for agents.
+     */
+    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
+                ? Math.round(opts.amount_usdc * 1e6).toString() // USDC has 6 decimals
+                : undefined);
+        if (!fromAmount) {
+            throw new AiFinPayError(`bridgeQuote: provide either amount_usdc OR fromAmount (in base units)`);
+        }
+        const quoteOpts = {
+            fromChain: opts.fromChain,
+            toChain: opts.toChain,
+            fromToken,
+            toToken,
+            fromAmount,
+            fromAddress: this.evmAccount.address,
+            toAddress: opts.toAddress ?? this.evmAccount.address,
+            slippage: opts.slippage,
+        };
+        return crossChainQuote(quoteOpts);
+    }
+    /**
+     * Execute a previously-fetched bridge quote. Signs and submits the source
+     * transaction with the agent's EVM key on the SOURCE chain. Returns once
+     * source-side inclusion is confirmed; dest-side arrival is async — call
+     * `bridgeWaitForArrival(receipt.source_tx)` if you need to block on it.
+     */
+    async bridgeExecute(quote) {
+        const { publicClient, walletClient } = this.evmClients(quote.from.chain);
+        return crossChainExecute(quote, walletClient, publicClient);
+    }
+    /**
+     * Wait for the bridge to deliver on the destination chain. Wraps LiFi's
+     * /status polling; timeout default is 30 minutes (Circle CCTP can take
+     * 15-25 min on Polygon side). Throws AiFinPayError on timeout.
+     */
+    async bridgeWaitForArrival(sourceTxHash, opts = {}) {
+        return bridgeWaitForArrival(sourceTxHash, opts);
+    }
     // ── Call ────────────────────────────────────────────────────────────────
     /**
      * High-level paid call. Resolves the provider, picks a chain, builds the
@@ -318,7 +572,10 @@ export class AiFinPayAgent {
     async call(opts) {
         const provider = await this.resolveProvider(opts.provider);
         const chain = this.pickChain(provider, opts);
-        const cost = opts.cost ?? provider.price_usd;
+        // Registry may carry price_usd: null — normalise to a finite number so a
+        // null/NaN cost can't poison the SpendTracker and silently disable caps.
+        const rawCost = opts.cost ?? provider.price_usd;
+        const cost = typeof rawCost === "number" && Number.isFinite(rawCost) ? rawCost : 0;
         const withinBudget = this.checkBudget(cost);
         if (!withinBudget)
             return null;
@@ -344,14 +601,16 @@ export class AiFinPayAgent {
             method: opts.method ?? "POST",
             headers: { "content-type": "application/json", ...extraHeaders },
             body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-            signal: opts.signal,
+            // CallOptions.timeoutMs was previously declared but never applied.
+            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;
         const initialResp = await this.inner.fetchImpl(fullUrl, buildInit());
         if (initialResp.status !== 402) {
             // Bridge didn't ask for payment — pass response through unchanged.
-            this.spend24h.add(cost);
+            // Nothing was paid, so the call does NOT count against budget caps.
             if (this.telemetry)
                 this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, free: true });
             return initialResp;
@@ -371,6 +630,17 @@ export class AiFinPayAgent {
                     `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,
@@ -383,6 +653,12 @@ export class AiFinPayAgent {
             this.spend24h.add(cost);
             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;
         }
         // ── Polygon branch (B2BSplitter.payMatic atomic split, legacy default) ──
@@ -390,7 +666,24 @@ export class AiFinPayAgent {
             throw new X402Error(`bridge ${provider.name} returned 402 but no pay_matic block — only legacy AiFinPay/Coinbase facilitators not yet wired into AiFinPayAgent.call()`);
         }
         const pm = challenge.pay_matic;
+        // Guard: same ballpark check as the Solana branch — never sign for an
+        // amount wildly above the declared cost / per-call cap.
+        {
+            const wei = Number(pm.total_wei);
+            const maticUsd = parseFloat(process.env.AIFINPAY_MATIC_USD ?? "0.70");
+            const estUsd = (Number.isFinite(wei) ? wei / 1e18 : 0) * maticUsd;
+            const guarded = this.guardChallengeAmount(estUsd, cost, provider.name);
+            if (!guarded)
+                return null;
+        }
         // 2. Submit B2BSplitter.payMatic on Polygon mainnet.
+        // ipCreator routing: prefer the challenge's explicit ip_creator; else
+        // route the royalty slot to the splitter's treasury (mirrors the Solana
+        // branch). Passing address(0) would skip the transfer and permanently
+        // strand the 1bp inside B2BSplitter — the contract has no sweep function.
+        const ipCreator = pm.ip_creator
+            ?? await this.splitterTreasury(pm.splitter)
+            ?? "0x0000000000000000000000000000000000000000";
         const { publicClient, walletClient } = this.polygonClients();
         const txHash = await walletClient.writeContract({
             address: pm.splitter,
@@ -398,7 +691,7 @@ export class AiFinPayAgent {
             functionName: "payMatic",
             args: [
                 pm.merchant_wallet,
-                "0x0000000000000000000000000000000000000000",
+                ipCreator,
                 pm.order_id,
             ],
             value: BigInt(pm.total_wei),
@@ -422,6 +715,9 @@ export class AiFinPayAgent {
         this.spend24h.add(cost);
         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 = "polygon";
         return paidResp;
     }
     // ── Solana b2b_pay_with_split — build, sign, send via @solana/web3.js ───
@@ -505,13 +801,17 @@ export class AiFinPayAgent {
         const solUsd = parseFloat(process.env.AIFINPAY_SOL_USD ?? "200");
         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
         return {
-            agent_balance_usd: polygonUsd + solanaUsd,
+            agent_balance_usd: polygonUsd + solanaUsd + solanaUsdcUsd + polygonUsdcUsd,
             chains: {
-                solana: { sol: solana, usdc: 0, msecco_balance: 0 },
-                polygon: { matic: polygon, usdc: 0, msecco_balance: 0 },
+                solana: { sol: solana, usdc: solana_usdc, msecco_balance: 0 },
+                polygon: { matic: polygon, usdc: polygon_usdc, msecco_balance: 0 },
             },
             spend_24h_usd: this.spend24h.total24h(),
             budget_caps: this.budgetCaps,
@@ -526,8 +826,9 @@ export class AiFinPayAgent {
         return Number(wei) / 1e18;
     }
     async fetchSolanaNative() {
-        // Use raw JSON-RPC to avoid pulling @solana/web3.js as a dep.
-        const rpc = process.env.AIFINPAY_SOLANA_RPC || "https://api.mainnet.solana.com";
+        // Raw JSON-RPC; honours the constructor's solanaRpc option (previously
+        // re-read env here with a different default endpoint).
+        const rpc = this.solanaRpc;
         const r = await this.inner.fetchImpl(rpc, {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -544,6 +845,91 @@ export class AiFinPayAgent {
         const lamports = j.result?.value ?? 0;
         return lamports / 1e9;
     }
+    /**
+     * Sum SPL USDC balances across all token accounts owned by the agent's
+     * Solana pubkey. Uses raw JSON-RPC `getTokenAccountsByOwner` so we don't
+     * pull `@solana/spl-token` as a dep. Returns 0 (never throws) when the
+     * RPC is unreachable or returns nothing — `balance()` must remain a
+     * non-blocking introspection call.
+     */
+    async fetchSolanaUsdc() {
+        const rpc = this.solanaRpc;
+        try {
+            const r = await this.inner.fetchImpl(rpc, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: 1,
+                    method: "getTokenAccountsByOwner",
+                    params: [
+                        this.solanaAddress,
+                        { mint: USDC_SOLANA_MINT },
+                        { encoding: "jsonParsed" },
+                    ],
+                }),
+            });
+            if (!r.ok)
+                return 0;
+            const j = (await r.json());
+            // Sum all USDC token accounts (usually just one, but be safe)
+            const accounts = j.result?.value ?? [];
+            let total = 0;
+            for (const acc of accounts) {
+                const ui = acc.account?.data?.parsed?.info?.tokenAmount?.uiAmount;
+                if (typeof ui === "number")
+                    total += ui;
+            }
+            return total;
+        }
+        catch {
+            return 0; // never block balance() on Solana RPC issues
+        }
+    }
+    // Cache: splitter address → treasury address (constant per deployment).
+    splitterTreasuryCache = new Map();
+    /** Read + cache B2BSplitter.treasury(). Returns null on RPC failure. */
+    async splitterTreasury(splitter) {
+        const cached = this.splitterTreasuryCache.get(splitter.toLowerCase());
+        if (cached)
+            return cached;
+        try {
+            const { publicClient } = this.polygonClients();
+            const treasury = await publicClient.readContract({
+                address: splitter,
+                abi: SPLITTER_TREASURY_ABI,
+                functionName: "treasury",
+            });
+            if (!treasury || treasury === "0x0000000000000000000000000000000000000000")
+                return null;
+            this.splitterTreasuryCache.set(splitter.toLowerCase(), treasury);
+            return treasury;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Read the native Polygon USDC (Circle-issued, 6 decimals) balance for the
+     * agent's EVM address via the existing viem publicClient. Returns 0
+     * (never throws) on RPC failure — see fetchSolanaUsdc rationale.
+     */
+    async fetchPolygonUsdc() {
+        try {
+            const { publicClient } = this.polygonClients();
+            const raw = await publicClient.readContract({
+                address: USDC_POLYGON_ERC20,
+                abi: ERC20_BALANCE_OF_ABI,
+                functionName: "balanceOf",
+                args: [this.evmAccount.address],
+            });
+            // USDC has 6 decimals on Polygon
+            return Number(raw) / 1e6;
+        }
+        catch {
+            return 0;
+        }
+    }
     // ── Reputation ──────────────────────────────────────────────────────────
     /**
      * TODO(phase-4 / phase-5): query operator backend reputation engine.
@@ -594,15 +980,10 @@ function bytesToHex(b) {
  * before audit-grade derivation lands.
  */
 function crypto32(seed) {
-    // Lazy require to avoid pulling node:crypto into bundlers that don't need it.
-    const c = globalThis.crypto;
-    if (c?.subtle) {
-        // Browser / modern Node — but subtle is async, and we're sync here.
-        // Fall through to the node:crypto path.
-    }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const nodeCrypto = require("node:crypto");
-    const h = nodeCrypto.createHash("sha256");
+    // Must stay sync (constructors call it). Uses the createHash imported at
+    // the top of this file — a bare `require()` is a ReferenceError here
+    // because this package ships as ESM ("type": "module").
+    const h = createHash("sha256");
     h.update("aifinpay:evm:v1\0");
     h.update(seed);
     return new Uint8Array(h.digest());