@blockrun/franklin 3.13.1 → 3.14.0

package/dist/agent/context.js

@@ -213,11 +213,11 @@ You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun
 - Use the **\`JupiterQuote\` and \`JupiterSwap\` built-in tools** — they call Jupiter's Ultra API directly from this process. The user is the first-party caller of Jupiter; we are not a gateway proxy here. A 20 bps platform fee is collected on-chain as part of the swap (Jupiter Referral Program — official integrator mechanism, not a hidden cost).
 - Do NOT try to call \`/v1/jupiter/...\` on the BlockRun gateway — there is no such endpoint (Jupiter ToU forbids the gateway-proxy model).
 
-**Base DEX swap (0x V2 Permit2)**
-- Use the **\`Base0xQuote\` and \`Base0xSwap\` built-in tools** for swaps on Base (chain id 8453). Mirrors Jupiter's local-call posture: 0x's API is hit directly, the user signs the Permit2 EIP-712 with their Base keypair, the tx settles on Base RPC. 0x's official affiliate program embeds 20 bps in the sell-token automatically (BlockRun affiliate, on-chain).
+**Base DEX swap (0x V2 Permit2 via BlockRun gateway)**
+- Use the **\`Base0xQuote\` and \`Base0xSwap\` built-in tools** for swaps on Base (chain id 8453). Tools route through BlockRun gateway \`/v1/zerox/{price,quote}\` (server-side 0x key, x402-paid). User pays $0.001 USDC per quote/swap call to the gateway; on-chain affiliate (20 bps in the sell-token) flows automatically to BlockRun treasury at swap settlement. **No 0x signup needed** — BlockRun manages the upstream key.
 - Symbol shortcuts pre-mapped: ETH (native), WETH, USDC, USDT, CBBTC, CBETH, AERO, DAI. Raw \`0x...\` addresses pass through.
-- **Each Franklin user supplies their OWN \`ZERO_EX_API_KEY\`** (free, no credit card, 10 req/s — sign up at https://dashboard.0x.org). The affiliate cut routes to BlockRun via the swap query params regardless of whose API key is making the call. If the swap tool errors with the env-var message, repeat the URL to the user — do not try to set the env yourself or invent a key.
 - For native ETH → token: no Permit2 approval needed (native value path). For ERC-20 → token: first-time-per-token Permit2 approval auto-runs before the swap (one-time gas cost; future swaps of the same sell-token reuse it).
+- The user signs Permit2 typed data locally with their Base keypair; the signed transaction is submitted to a Base RPC (default public mainnet-beta) — BlockRun never custodies keys.
 
 **Sandbox (POST, x402-paid)**
 - \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).

package/dist/tools/zerox-base.js

@@ -24,18 +24,22 @@
 import { createWalletClient, http, publicActions, concat, numberToHex, size, parseUnits, formatUnits, maxUint256, erc20Abi, getContract, } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { base } from 'viem/chains';
-import { getOrCreateWallet } from '@blockrun/llm';
+import { getOrCreateWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, getOrCreateSolanaWallet, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
 import { loadConfig } from '../commands/config.js';
+import { loadChain, API_URLS, VERSION } from '../config.js';
 // ─── BlockRun affiliate identity on Base ─────────────────────────────────
 // Reuses the existing BlockRun ops wallet that already receives x402
 // settlements on Base. Every swap routed through these tools deposits 20
 // bps of the sell-token amount into this address at settlement.
 const BLOCKRUN_BASE_AFFILIATE = '0xe9030014F5DAe217d0A152f02A043567b16c1aBf';
 const BLOCKRUN_AFFILIATE_FEE_BPS = 20; // 0.2% — matches Jupiter Ultra path.
-// ─── 0x API endpoints ─────────────────────────────────────────────────────
-const ZEROX_BASE = 'https://api.0x.org/swap/permit2';
-const ZEROX_VERSION = 'v2';
-const ZEROX_TIMEOUT_MS = 20_000;
+// ─── BlockRun gateway path for 0x ────────────────────────────────────────
+// As of v3.14.0 we route through the BlockRun gateway (server-side 0x key),
+// not directly to api.0x.org. User pays $0.001 via x402 per gateway call;
+// affiliate 20 bps is force-set server-side and lands on-chain in the same
+// BlockRun treasury that already collects x402 settlements.
+const ZEROX_GATEWAY_PATH = '/v1/zerox';
+const ZEROX_TIMEOUT_MS = 30_000;
 // ─── Default Base RPC ────────────────────────────────────────────────────
 // Public Base mainnet endpoint. Override via BASE_RPC_URL env or
 // `franklin config set base-rpc-url <url>` (Alchemy, QuickNode public, etc.).
@@ -46,9 +50,6 @@ function resolveBaseRpcUrl() {
         loadConfig()['base-rpc-url'] ||
         DEFAULT_BASE_RPC);
 }
-function resolveZeroxApiKey() {
-    return process.env.ZERO_EX_API_KEY || loadConfig()['zerox-api-key'];
-}
 // ─── Session safety: cumulative live-swap counter ─────────────────────────
 const DEFAULT_LIVE_SWAP_CAP = 10;
 const liveSwapCap = (() => {
@@ -145,53 +146,104 @@ function makeClient(account) {
         transport: http(resolveBaseRpcUrl()),
     }).extend(publicActions);
 }
-function zeroxHeaders() {
-    const apiKey = resolveZeroxApiKey();
-    if (!apiKey) {
-        throw new Error("Base swaps need a 0x API key. Each Franklin user sets their own (free, no credit card, 10 req/s): " +
-            "1) Sign up at https://dashboard.0x.org · " +
-            "2) Copy the API key from the Demo App or your own app · " +
-            "3a) Persist it: `franklin setup zerox` (interactive) or `franklin config set zerox-api-key zx_...`, OR " +
-            "3b) Per-session: `ZERO_EX_API_KEY=zx_... franklin`. " +
-            "BlockRun does NOT need a 0x account — the affiliate fee routes to BlockRun's wallet regardless of whose key is making the call.");
-    }
-    return {
-        'Content-Type': 'application/json',
-        '0x-api-key': apiKey,
-        '0x-version': ZEROX_VERSION,
+// ─── 0x calls via BlockRun gateway (x402-paid) ───────────────────────────
+async function gatewayGetWithPayment(path, params, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${ZEROX_GATEWAY_PATH}/${path}?${params.toString()}`;
+    const headers = {
+        Accept: 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
     };
-}
-// ─── 0x API calls ────────────────────────────────────────────────────────
-async function zeroxFetch(path, params) {
-    const url = `${ZEROX_BASE}/${path}?${params.toString()}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), ZEROX_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
     try {
-        const res = await fetch(url, { headers: zeroxHeaders(), signal: controller.signal });
-        if (!res.ok) {
-            const text = await res.text();
-            throw new Error(`0x ${path} returned ${res.status}: ${text.slice(0, 300)}`);
+        let response = await fetch(endpoint, {
+            method: 'GET',
+            headers,
+            signal: controller.signal,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signGatewayPayment(response, chain, endpoint);
+            if (!paymentHeaders) {
+                throw new Error('Payment signing failed — check wallet balance');
+            }
+            response = await fetch(endpoint, {
+                method: 'GET',
+                headers: { ...headers, ...paymentHeaders },
+                signal: controller.signal,
+            });
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`BlockRun gateway /v1/zerox/${path} returned ${response.status}: ${text.slice(0, 300)}`);
         }
-        return (await res.json());
+        return (await response.json());
     }
     finally {
         clearTimeout(timer);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function signGatewayPayment(response, chain, endpoint) {
+    try {
+        let header = response.headers.get('payment-required');
+        if (!header) {
+            try {
+                const body = (await response.json());
+                if (body.x402 || body.accepts)
+                    header = btoa(JSON.stringify(body));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        if (!header)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(header);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || 'Franklin 0x swap call',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = await getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(header);
+        const details = extractPaymentDetails(paymentRequired);
+        const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || 'Franklin 0x swap call',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        console.error(`[franklin] 0x gateway payment error: ${err.message}`);
+        return null;
     }
 }
 function buildSwapParams(args) {
-    const p = new URLSearchParams({
+    // Affiliate params (swapFeeRecipient/Bps/Token) are NOT set here —
+    // the BlockRun gateway forces them server-side, ensuring every
+    // gateway-routed swap pays affiliate to BlockRun treasury regardless
+    // of what the agent passes. See blockrun/src/lib/zerox.ts:proxyToZerox.
+    return new URLSearchParams({
         chainId: String(base.id),
         sellToken: args.sellTokenAddr,
         buyToken: args.buyTokenAddr,
         sellAmount: args.sellAmountAtomic,
         taker: args.taker,
     });
-    if (args.feeRecipient && args.feeBps && args.feeBps > 0 && args.feeToken) {
-        p.set('swapFeeRecipient', args.feeRecipient);
-        p.set('swapFeeBps', String(args.feeBps));
-        p.set('swapFeeToken', args.feeToken);
-    }
-    return p;
 }
 // ─── Formatting ──────────────────────────────────────────────────────────
 function formatQuoteText(q) {
@@ -219,7 +271,7 @@ function formatQuoteText(q) {
     return lines.join('\n');
 }
 // ─── Quote (read-only) ───────────────────────────────────────────────────
-async function executeBase0xQuote(input) {
+async function executeBase0xQuote(input, ctx) {
     let walletAddress;
     try {
         const wallet = await loadEvmWallet();
@@ -240,14 +292,9 @@ async function executeBase0xQuote(input) {
         buyTokenAddr,
         sellAmountAtomic: sellAmount,
         taker: walletAddress,
-        feeRecipient: BLOCKRUN_BASE_AFFILIATE,
-        feeBps: BLOCKRUN_AFFILIATE_FEE_BPS,
-        // Take the fee in the sell token so it's deterministic and doesn't
-        // depend on the output token having an existing recipient ATA / balance.
-        feeToken: sellTokenAddr,
     });
     try {
-        const price = await zeroxFetch('price', params);
+        const price = await gatewayGetWithPayment('price', params, ctx);
         if (!price.liquidityAvailable && price.liquidityAvailable !== undefined) {
             return {
                 output: `0x reports no liquidity for ${symbolFor(sellTokenAddr)} → ${symbolFor(buyTokenAddr)} on Base.`,
@@ -257,7 +304,7 @@ async function executeBase0xQuote(input) {
         return { output: formatQuoteText(price) };
     }
     catch (err) {
-        return { output: `0x /price failed: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+        return { output: `BlockRun gateway 0x /price failed: ${err instanceof Error ? err.message : String(err)}`, isError: true };
     }
 }
 // ─── Swap (full execute) ─────────────────────────────────────────────────
@@ -290,18 +337,16 @@ async function executeBase0xSwap(input, ctx) {
         buyTokenAddr,
         sellAmountAtomic: sellAmount,
         taker: wallet.address,
-        feeRecipient: BLOCKRUN_BASE_AFFILIATE,
-        feeBps: BLOCKRUN_AFFILIATE_FEE_BPS,
-        feeToken: sellTokenAddr,
     });
-    // Step 1 — fetch the firm quote (returns tx + permit2.eip712 to sign).
+    // Step 1 — fetch the firm quote via BlockRun gateway (x402-paid).
+    // Gateway forces affiliate params server-side; user pays $0.001 USDC.
     let quote;
     try {
-        quote = await zeroxFetch('quote', params);
+        quote = await gatewayGetWithPayment('quote', params, ctx);
     }
     catch (err) {
         return {
-            output: `0x /quote failed: ${err instanceof Error ? err.message : String(err)}`,
+            output: `BlockRun gateway 0x /quote failed: ${err instanceof Error ? err.message : String(err)}`,
             isError: true,
         };
     }
@@ -453,15 +498,15 @@ export const base0xQuoteCapability = {
             properties: COMMON_INPUT_PROPERTIES,
         },
     },
-    execute: async (input) => {
-        return executeBase0xQuote(input);
+    execute: async (input, ctx) => {
+        return executeBase0xQuote(input, ctx);
     },
     concurrent: true,
 };
 export const base0xSwapCapability = {
     spec: {
         name: 'Base0xSwap',
-        description: "Execute a Base DEX swap via 0x V2 (Permit2). Quotes the order, asks the user to confirm, signs locally with the Franklin Base wallet, and submits via Base RPC. A 20 bps affiliate fee in the sell-token is collected on-chain by 0x as part of the swap (BlockRun affiliate program — official 0x integrator mechanism). Returns the BaseScan transaction link. Requires ZERO_EX_API_KEY env var (free at dashboard.0x.org).",
+        description: "Execute a Base DEX swap via 0x V2 (Permit2). Quotes through BlockRun gateway (x402-paid, server-side 0x key — no user setup needed), asks the user to confirm, signs locally with the Franklin Base wallet, and submits via Base RPC. A 20 bps affiliate fee in the sell-token is collected on-chain by 0x as part of the swap (BlockRun affiliate program — official 0x integrator mechanism). Returns the BaseScan transaction link.",
         input_schema: {
             type: 'object',
             required: ['sell_token', 'buy_token', 'sell_amount'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.13.1",
+  "version": "3.14.0",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {