@blockrun/franklin 3.12.0 → 3.12.2

package/dist/agent/context.js

@@ -205,13 +205,14 @@ You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun
 - \`GET /v1/models\` — full model catalog (id, owner, context window, pricing).
 - \`GET /v1/health/overview\` · \`/v1/health/regions\` · \`/v1/health/chain\` · \`/v1/health/models\` — gateway status.
 
-**Trading & DeFi (mixed methods, x402-paid; new in v3.12.0)**
-- \`GET  /v1/jupiter/quote?inputMint=...&outputMint=...&amount=...&slippageBps=50\` — Solana DEX-aggregator price quote across every DEX Jupiter knows. \$0.001/call.
-- \`POST /v1/jupiter/swap\` — body \`{ userPublicKey, quoteResponse }\`. Returns a base64-encoded **unsigned** Solana transaction. Caller signs locally; gateway never custodies keys. \$0.001/call.
-- \`GET  /v1/defillama/protocols\` · \`/v1/defillama/protocol/{slug}\` · \`/v1/defillama/chains\` · \`/v1/defillama/yields\` — TVL / yield-pool data, Apache-2.0 source. \$0.005/call.
-- \`GET  /v1/defillama/prices/{coins}\` — token price lookup (coingecko:bitcoin, ethereum:0x..., solana:mint, comma-separated). \$0.001/call.
+**Trading & DeFi (mixed methods, x402-paid)**
+- For DefiLlama data, **use the built-in tools** \`DeFiLlamaProtocols\`, \`DeFiLlamaProtocol\`, \`DeFiLlamaChains\`, \`DeFiLlamaYields\`, \`DeFiLlamaPrice\`. They handle x402 payment automatically and filter responses (DefiLlama raw payloads are 5–10 MB; the tools return ranked summaries). Do NOT call \`/v1/defillama/*\` via Bash + curl — the wallet won't sign payments through that path.
 - \`POST /v1/solana/rpc\` — JSON-RPC passthrough to public mainnet-beta (getAccountInfo, getTokenSupply, sendTransaction, etc.). \$0.0005 per call (per element of a batch). Use this instead of running your own RPC infra.
 
+**Solana DEX swap (Jupiter Ultra)**
+- 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).
+
 **Sandbox (POST, x402-paid)**
 - \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).
 - \`/v1/pm/{...path}\` — prediction-market data passthrough.

package/dist/tools/defillama.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DefiLlama capabilities — TVL, yield pools, protocol metadata, and token
+ * prices via the BlockRun `/v1/defillama/*` endpoints. Each tool handles
+ * x402 payment automatically against the user's USDC wallet.
+ *
+ * Five tools, each filtered + formatted on the way back so we don't dump
+ * 5–10 MB of raw DefiLlama JSON into agent context:
+ *  - DeFiLlamaProtocols   $0.005/call — top-N protocols by TVL
+ *  - DeFiLlamaProtocol    $0.005/call — single protocol detail
+ *  - DeFiLlamaChains      $0.005/call — TVL ranked by chain
+ *  - DeFiLlamaYields      $0.005/call — yield pools, filtered + ranked
+ *  - DeFiLlamaPrice       $0.001/call — token price lookup
+ *
+ * DefiLlama is Apache 2.0 / "free for public and commercial use" — the
+ * BlockRun gateway adds metering + (future) caching/reliability layers,
+ * which is what the per-call charge funds.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const defiLlamaProtocolsCapability: CapabilityHandler;
+export declare const defiLlamaProtocolCapability: CapabilityHandler;
+export declare const defiLlamaChainsCapability: CapabilityHandler;
+export declare const defiLlamaYieldsCapability: CapabilityHandler;
+export declare const defiLlamaPriceCapability: CapabilityHandler;

package/dist/tools/defillama.js

@@ -0,0 +1,408 @@
+/**
+ * DefiLlama capabilities — TVL, yield pools, protocol metadata, and token
+ * prices via the BlockRun `/v1/defillama/*` endpoints. Each tool handles
+ * x402 payment automatically against the user's USDC wallet.
+ *
+ * Five tools, each filtered + formatted on the way back so we don't dump
+ * 5–10 MB of raw DefiLlama JSON into agent context:
+ *  - DeFiLlamaProtocols   $0.005/call — top-N protocols by TVL
+ *  - DeFiLlamaProtocol    $0.005/call — single protocol detail
+ *  - DeFiLlamaChains      $0.005/call — TVL ranked by chain
+ *  - DeFiLlamaYields      $0.005/call — yield pools, filtered + ranked
+ *  - DeFiLlamaPrice       $0.001/call — token price lookup
+ *
+ * DefiLlama is Apache 2.0 / "free for public and commercial use" — the
+ * BlockRun gateway adds metering + (future) caching/reliability layers,
+ * which is what the per-call charge funds.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+const TIMEOUT_MS = 30_000;
+// ─── Shared GET-with-x402 flow ────────────────────────────────────────────
+async function getWithPayment(path, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${path}`;
+    const headers = {
+        Accept: 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        let response = await fetch(endpoint, {
+            method: 'GET',
+            signal: controller.signal,
+            headers,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint);
+            if (!paymentHeaders) {
+                throw new Error('Payment signing failed — check wallet balance');
+            }
+            response = await fetch(endpoint, {
+                method: 'GET',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(`DefiLlama ${path} failed (${response.status}): ${errText.slice(0, 200)}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function signPayment(response, chain, endpoint) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            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 DefiLlama call',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = await getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        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 DefiLlama call',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        console.error(`[franklin] DefiLlama payment error: ${err.message}`);
+        return null;
+    }
+}
+async function extractPaymentReq(response) {
+    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 */
+        }
+    }
+    return header;
+}
+// ─── Formatting helpers ──────────────────────────────────────────────────
+function formatUsd(value) {
+    if (value == null || !Number.isFinite(value))
+        return 'n/a';
+    if (value >= 1e9)
+        return `$${(value / 1e9).toFixed(2)}B`;
+    if (value >= 1e6)
+        return `$${(value / 1e6).toFixed(2)}M`;
+    if (value >= 1e3)
+        return `$${(value / 1e3).toFixed(2)}K`;
+    return `$${value.toFixed(2)}`;
+}
+function formatPct(value, digits = 2) {
+    if (value == null || !Number.isFinite(value))
+        return 'n/a';
+    const sign = value >= 0 ? '+' : '';
+    return `${sign}${value.toFixed(digits)}%`;
+}
+export const defiLlamaProtocolsCapability = {
+    spec: {
+        name: 'DeFiLlamaProtocols',
+        description: 'Rank DeFi protocols by total value locked (TVL) across all chains, optionally filtered by category, chain, or minimum TVL. ' +
+            'Returns the top-N protocols (default 20), each with TVL, 24h/7d change, chain breakdown, and slug. ' +
+            'Uses BlockRun gateway → DefiLlama. $0.005 per call. ' +
+            'Categories include: Lending, Liquid Staking, Bridge, Dexes, CDP, Yield, Yield Aggregator, Derivatives, Stablecoins, Insurance, etc.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                top_n: { type: 'number', description: 'Max results (default 20, hard cap 100).' },
+                category: { type: 'string', description: 'Category filter, exact match (case-insensitive).' },
+                chain: { type: 'string', description: 'Chain name filter (e.g. "Ethereum", "Solana", "Base").' },
+                min_tvl_usd: { type: 'number', description: 'Drop protocols with TVL below this floor.' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        const topN = Math.min(Math.max(1, params.top_n ?? 20), 100);
+        try {
+            const res = await getWithPayment('/v1/defillama/protocols', ctx);
+            let list = res ?? [];
+            if (params.category) {
+                const want = params.category.toLowerCase();
+                list = list.filter((p) => (p.category ?? '').toLowerCase() === want);
+            }
+            if (params.chain) {
+                const want = params.chain.toLowerCase();
+                list = list.filter((p) => (p.chains ?? []).some((c) => c.toLowerCase() === want));
+            }
+            if (params.min_tvl_usd != null) {
+                list = list.filter((p) => Number(p.tvl) >= params.min_tvl_usd);
+            }
+            list.sort((a, b) => Number(b.tvl) - Number(a.tvl));
+            list = list.slice(0, topN);
+            if (list.length === 0)
+                return { output: 'No DefiLlama protocols matched the filters.' };
+            const lines = [
+                `## DefiLlama protocols — top ${list.length}` +
+                    (params.category ? ` · category=${params.category}` : '') +
+                    (params.chain ? ` · chain=${params.chain}` : ''),
+            ];
+            list.forEach((p, i) => {
+                const chains = (p.chains ?? []).slice(0, 4).join(', ');
+                const more = (p.chains ?? []).length > 4 ? ` +${(p.chains ?? []).length - 4}` : '';
+                const cat = p.category ? ` · ${p.category}` : '';
+                const change = p.change_1d != null ? ` · 24h ${formatPct(p.change_1d)}` : '';
+                lines.push(`${i + 1}. **${p.name}** (${p.slug}) — ${formatUsd(Number(p.tvl))}${cat}${change}\n   chains: ${chains}${more}`);
+            });
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaProtocolCapability = {
+    spec: {
+        name: 'DeFiLlamaProtocol',
+        description: 'Detailed TVL + chain breakdown for a single DeFi protocol identified by DefiLlama slug ' +
+            '(e.g. "aave", "uniswap", "lido", "jito", "marinade-finance"). ' +
+            'Returns TVL across each chain it operates on, recent change, audits, social. ' +
+            '$0.005 per call. To find a slug, run DeFiLlamaProtocols first.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'DefiLlama protocol slug, lowercase, dash-separated.' },
+            },
+            required: ['slug'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.slug)
+            return { output: 'Error: slug is required', isError: true };
+        try {
+            const safeSlug = encodeURIComponent(params.slug.trim().toLowerCase());
+            const p = await getWithPayment(`/v1/defillama/protocol/${safeSlug}`, ctx);
+            const chainBreakdown = p.currentChainTvls
+                ? Object.entries(p.currentChainTvls)
+                    .filter(([k]) => !k.endsWith('-staking') && !k.endsWith('-borrowed') && !k.endsWith('-pool2'))
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 8)
+                    .map(([chain, tvl]) => `${chain} ${formatUsd(tvl)}`)
+                    .join(', ')
+                : 'n/a';
+            const totalTvl = p.currentChainTvls
+                ? Object.values(p.currentChainTvls).reduce((a, b) => a + b, 0)
+                : Array.isArray(p.tvl)
+                    ? p.tvl[p.tvl.length - 1]?.totalLiquidityUSD ?? 0
+                    : p.tvl ?? 0;
+            const lines = [
+                `## ${p.name}${p.category ? ` (${p.category})` : ''}`,
+                '',
+                `TVL: ${formatUsd(totalTvl)}`,
+            ];
+            if (p.change_1d != null)
+                lines.push(`24h change: ${formatPct(p.change_1d)}`);
+            if (p.change_7d != null)
+                lines.push(`7d change: ${formatPct(p.change_7d)}`);
+            lines.push(`Chains: ${chainBreakdown}`);
+            if (p.url)
+                lines.push(`URL: ${p.url}`);
+            if (p.twitter)
+                lines.push(`Twitter: @${p.twitter}`);
+            if (p.audits)
+                lines.push(`Audits: ${p.audits}`);
+            if (p.description)
+                lines.push('', p.description);
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaChainsCapability = {
+    spec: {
+        name: 'DeFiLlamaChains',
+        description: 'TVL ranking across every chain DefiLlama tracks. Default returns top 20 by TVL. $0.005 per call.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                top_n: { type: 'number', description: 'Max results (default 20, hard cap 200).' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        const topN = Math.min(Math.max(1, params.top_n ?? 20), 200);
+        try {
+            const list = await getWithPayment('/v1/defillama/chains', ctx);
+            const sorted = (list ?? []).slice().sort((a, b) => Number(b.tvl) - Number(a.tvl)).slice(0, topN);
+            if (sorted.length === 0)
+                return { output: 'DefiLlama returned no chains.' };
+            const lines = [`## TVL by chain — top ${sorted.length}`];
+            sorted.forEach((c, i) => {
+                const sym = c.tokenSymbol ? ` (${c.tokenSymbol})` : '';
+                lines.push(`${i + 1}. **${c.name}**${sym} — ${formatUsd(Number(c.tvl))}`);
+            });
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaYieldsCapability = {
+    spec: {
+        name: 'DeFiLlamaYields',
+        description: 'Search DeFi yield pools (lending, LPs, vaults, staking) by symbol/chain/project, ranked by APY. ' +
+            'Returns top-N pools (default 10). $0.005 per call. ' +
+            'Default filters: TVL > $1M (avoid microcaps), APY > 0. Override via params. ' +
+            'Use stablecoin_only=true for "where can my USDC earn?" queries.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'Token symbol filter (e.g. "USDC", "ETH"). Matches tokens in the pool.' },
+                chain: { type: 'string', description: 'Chain filter (e.g. "Ethereum", "Solana", "Base").' },
+                project: { type: 'string', description: 'DefiLlama project slug filter (e.g. "aave-v3", "lido", "kamino").' },
+                min_tvl_usd: { type: 'number', description: 'Minimum pool TVL in USD (default 1_000_000).' },
+                min_apy_pct: { type: 'number', description: 'Minimum APY in percent (default 0).' },
+                stablecoin_only: { type: 'boolean', description: 'If true, only stablecoin pools.' },
+                top_n: { type: 'number', description: 'Max results (default 10, hard cap 50).' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        const topN = Math.min(Math.max(1, params.top_n ?? 10), 50);
+        const minTvl = params.min_tvl_usd ?? 1_000_000;
+        const minApy = params.min_apy_pct ?? 0;
+        try {
+            const res = await getWithPayment('/v1/defillama/yields', ctx);
+            const pools = res.data ?? [];
+            let filtered = pools.filter((p) => (p.apy ?? -1) >= minApy && (p.tvlUsd ?? 0) >= minTvl);
+            if (params.symbol) {
+                const want = params.symbol.toUpperCase();
+                filtered = filtered.filter((p) => p.symbol?.toUpperCase().includes(want));
+            }
+            if (params.chain) {
+                const want = params.chain.toLowerCase();
+                filtered = filtered.filter((p) => p.chain?.toLowerCase() === want);
+            }
+            if (params.project) {
+                const want = params.project.toLowerCase();
+                filtered = filtered.filter((p) => p.project?.toLowerCase() === want);
+            }
+            if (params.stablecoin_only) {
+                filtered = filtered.filter((p) => p.stablecoin === true);
+            }
+            filtered.sort((a, b) => (b.apy ?? 0) - (a.apy ?? 0));
+            const top = filtered.slice(0, topN);
+            if (top.length === 0)
+                return { output: 'No yield pools matched the filters.' };
+            const filterDesc = [
+                params.symbol && `symbol=${params.symbol}`,
+                params.chain && `chain=${params.chain}`,
+                params.project && `project=${params.project}`,
+                params.stablecoin_only && 'stablecoin_only',
+                `min_tvl=${formatUsd(minTvl)}`,
+                `min_apy=${minApy}%`,
+            ]
+                .filter(Boolean)
+                .join(' · ');
+            const lines = [`## Yield pools — top ${top.length} by APY · ${filterDesc}`];
+            top.forEach((p, i) => {
+                const breakdown = p.apyBase != null && p.apyReward != null
+                    ? ` (base ${p.apyBase.toFixed(2)}% + reward ${p.apyReward.toFixed(2)}%)`
+                    : '';
+                const il = p.ilRisk ? ` · IL: ${p.ilRisk}` : '';
+                lines.push(`${i + 1}. **${p.project}** / ${p.chain} / ${p.symbol} — ${(p.apy ?? 0).toFixed(2)}% APY${breakdown}\n   TVL: ${formatUsd(p.tvlUsd)}${il} · pool: ${p.pool}`);
+            });
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaPriceCapability = {
+    spec: {
+        name: 'DeFiLlamaPrice',
+        description: 'Token price lookup via DefiLlama (covers thousands of tokens — anything DEX-listed). $0.001 per call. ' +
+            'Coin identifier syntax: "{platform}:{address}" or "coingecko:{slug}". ' +
+            'Examples: "coingecko:bitcoin" (BTC USD), "ethereum:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" (WETH), ' +
+            '"solana:So11111111111111111111111111111111111111112" (SOL/wSOL), ' +
+            '"solana:DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" (BONK). ' +
+            'Pass multiple identifiers for batch lookup. ' +
+            'Use the existing /v1/crypto/price/{symbol} endpoint via TradingMarket for the major-asset shorthand instead — ' +
+            'this tool is for arbitrary on-chain mints / addresses.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                coins: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Coin identifiers in DefiLlama syntax. Up to 50 per call.',
+                },
+            },
+            required: ['coins'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.coins || params.coins.length === 0) {
+            return { output: 'Error: coins array is required', isError: true };
+        }
+        if (params.coins.length > 50) {
+            return { output: `Error: max 50 coins per call (got ${params.coins.length})`, isError: true };
+        }
+        try {
+            const safeList = params.coins.map((c) => encodeURIComponent(c.trim())).join(',');
+            const res = await getWithPayment(`/v1/defillama/prices/${safeList}`, ctx);
+            const coins = res.coins ?? {};
+            const lines = [`## Token prices — ${Object.keys(coins).length} match(es)`];
+            for (const id of params.coins) {
+                const entry = coins[id];
+                if (!entry || entry.price == null) {
+                    lines.push(`- ${id}: no price returned`);
+                    continue;
+                }
+                const sym = entry.symbol ? ` (${entry.symbol})` : '';
+                const conf = entry.confidence != null ? ` · conf ${(entry.confidence * 100).toFixed(0)}%` : '';
+                const ts = entry.timestamp ? ` · ${new Date(entry.timestamp * 1000).toISOString().slice(0, 19)}Z` : '';
+                lines.push(`- **${id}**${sym}: $${entry.price.toFixed(entry.price < 0.01 ? 8 : 4)}${conf}${ts}`);
+            }
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};

package/dist/tools/index.js

@@ -25,6 +25,8 @@ import { postToXCapability } from './posttox.js';
 import { moaCapability } from './moa.js';
 import { webhookPostCapability } from './webhook.js';
 import { walletCapability } from './wallet.js';
+import { jupiterQuoteCapability, jupiterSwapCapability } from './jupiter.js';
+import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -144,6 +146,13 @@ export const allCapabilities = [
     moaCapability,
     webhookPostCapability,
     walletCapability,
+    jupiterQuoteCapability,
+    jupiterSwapCapability,
+    defiLlamaProtocolsCapability,
+    defiLlamaProtocolCapability,
+    defiLlamaChainsCapability,
+    defiLlamaYieldsCapability,
+    defiLlamaPriceCapability,
 ];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/jupiter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Jupiter Ultra Swap — Solana DEX aggregator (built-in Franklin tool).
+ *
+ * We do NOT proxy through the BlockRun gateway — Jupiter's ToU forbids that.
+ * Instead the agent calls Jupiter's Ultra API directly from this process,
+ * embedding BlockRun's Referral Program identity in every order. The 20 bps
+ * platform fee flows on-chain to BlockRun's referral wallet at swap settlement
+ * (Jupiter's officially-supported integrator monetization mechanism — same one
+ * Phantom and other wallets use).
+ *
+ * Two tools exposed:
+ *   - JupiterQuote — read-only price check (no AskUser, no signing)
+ *   - JupiterSwap  — full flow: order → AskUser confirm → sign → execute
+ *
+ * Reference implementation:
+ *   https://github.com/Jupiter-DevRel/typescript-examples/tree/main/ultra/order-execute-with-referral-accounts
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const jupiterQuoteCapability: CapabilityHandler;
+export declare const jupiterSwapCapability: CapabilityHandler;

package/dist/tools/jupiter.js

@@ -0,0 +1,326 @@
+/**
+ * Jupiter Ultra Swap — Solana DEX aggregator (built-in Franklin tool).
+ *
+ * We do NOT proxy through the BlockRun gateway — Jupiter's ToU forbids that.
+ * Instead the agent calls Jupiter's Ultra API directly from this process,
+ * embedding BlockRun's Referral Program identity in every order. The 20 bps
+ * platform fee flows on-chain to BlockRun's referral wallet at swap settlement
+ * (Jupiter's officially-supported integrator monetization mechanism — same one
+ * Phantom and other wallets use).
+ *
+ * Two tools exposed:
+ *   - JupiterQuote — read-only price check (no AskUser, no signing)
+ *   - JupiterSwap  — full flow: order → AskUser confirm → sign → execute
+ *
+ * Reference implementation:
+ *   https://github.com/Jupiter-DevRel/typescript-examples/tree/main/ultra/order-execute-with-referral-accounts
+ */
+import { Keypair, VersionedTransaction } from '@solana/web3.js';
+import { getOrCreateSolanaWallet, solanaKeyToBytes, } from '@blockrun/llm';
+// ─── BlockRun Referral identity ───────────────────────────────────────────
+// Set up via referral.jup.ag. Owns ATAs for USDC, wSOL, JUP, USDT, etc. Every
+// swap routed through these tools deposits 20 bps of output to this wallet's
+// matching ATA.
+const BLOCKRUN_REFERRAL_ACCOUNT = 'DUGyfGMTAvyHtrvCa2qPE2KJd3qtGBe4ra7u6URne4xQ';
+const BLOCKRUN_REFERRAL_FEE_BPS = 20; // 0.2% — Jupiter docs default; well below Phantom's 85 bps.
+// ─── Ultra API endpoints ──────────────────────────────────────────────────
+const ULTRA_BASE = 'https://lite-api.jup.ag/ultra/v1';
+const ORDER_TIMEOUT_MS = 15_000;
+const EXECUTE_TIMEOUT_MS = 30_000;
+// ─── Symbol → mint shortcuts ──────────────────────────────────────────────
+// Agents prefer "USDC" / "SOL" over 44-char base58 mint addresses. Anything
+// not in this map is passed through verbatim — power users can drop in any
+// mint they want.
+const SYMBOL_TO_MINT = {
+    SOL: 'So11111111111111111111111111111111111111112', // wSOL
+    WSOL: 'So11111111111111111111111111111111111111112',
+    USDC: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    USDT: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
+    JUP: 'JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN',
+    BONK: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
+    WIF: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm',
+    TRUMP: '6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN',
+    PUMP: 'pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn',
+};
+const TOKEN_DECIMALS = {
+    // wSOL — 9
+    So11111111111111111111111111111111111111112: 9,
+    // USDC — 6
+    EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: 6,
+    // USDT — 6
+    Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB: 6,
+    // JUP — 6
+    JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN: 6,
+    // BONK — 5
+    DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263: 5,
+    // WIF — 6
+    EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm: 6,
+};
+function resolveMint(input) {
+    const upper = input.trim().toUpperCase();
+    if (SYMBOL_TO_MINT[upper])
+        return SYMBOL_TO_MINT[upper];
+    return input.trim();
+}
+function decimalsFor(mint, fallback = 9) {
+    return TOKEN_DECIMALS[mint] ?? fallback;
+}
+function symbolFor(mint) {
+    for (const [sym, m] of Object.entries(SYMBOL_TO_MINT)) {
+        if (m === mint)
+            return sym;
+    }
+    return mint.slice(0, 4) + '…';
+}
+function toAtomicUnits(amount, decimals) {
+    // BigInt math — JavaScript number can lose precision for large lamport counts.
+    const scale = BigInt(10) ** BigInt(decimals);
+    const whole = BigInt(Math.floor(amount));
+    const fractional = BigInt(Math.round((amount - Math.floor(amount)) * Number(scale)));
+    return (whole * scale + fractional).toString();
+}
+function fromAtomicUnits(atomic, decimals) {
+    const value = typeof atomic === 'string' ? Number(atomic) : atomic;
+    return value / Math.pow(10, decimals);
+}
+async function ultraOrder(params) {
+    const url = new URL(`${ULTRA_BASE}/order`);
+    url.searchParams.set('inputMint', params.inputMint);
+    url.searchParams.set('outputMint', params.outputMint);
+    url.searchParams.set('amount', params.amount);
+    if (params.taker)
+        url.searchParams.set('taker', params.taker);
+    url.searchParams.set('referralAccount', BLOCKRUN_REFERRAL_ACCOUNT);
+    url.searchParams.set('referralFee', String(BLOCKRUN_REFERRAL_FEE_BPS));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ORDER_TIMEOUT_MS);
+    try {
+        const res = await fetch(url.toString(), {
+            method: 'GET',
+            headers: { Accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Jupiter Ultra /order returned ${res.status}: ${text}`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function ultraExecute(args) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EXECUTE_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${ULTRA_BASE}/execute`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify(args),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Jupiter Ultra /execute returned ${res.status}: ${text}`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function loadSolanaKeypair() {
+    const wallet = await getOrCreateSolanaWallet();
+    const bytes = await solanaKeyToBytes(wallet.privateKey);
+    return Keypair.fromSecretKey(bytes);
+}
+function formatQuote(order) {
+    const inMint = order.inputMint;
+    const outMint = order.outputMint;
+    const inDec = decimalsFor(inMint);
+    const outDec = decimalsFor(outMint);
+    const inAmount = fromAtomicUnits(order.inAmount, inDec);
+    const outAmount = fromAtomicUnits(order.outAmount, outDec);
+    const inSym = symbolFor(inMint);
+    const outSym = symbolFor(outMint);
+    const impact = order.priceImpactPct
+        ? `${(Number(order.priceImpactPct) * 100).toFixed(3)}%`
+        : 'n/a';
+    const route = order.routePlan
+        ?.map((step) => step.swapInfo?.label)
+        .filter(Boolean)
+        .join(' → ') || 'Jupiter Ultra';
+    const rate = inAmount > 0 ? outAmount / inAmount : 0;
+    return [
+        `${inAmount.toFixed(Math.min(6, inDec))} ${inSym} → ${outAmount.toFixed(Math.min(6, outDec))} ${outSym}`,
+        `Rate: 1 ${inSym} ≈ ${rate.toPrecision(6)} ${outSym}`,
+        `Price impact: ${impact}`,
+        `Route: ${route}`,
+        `Platform fee: ${BLOCKRUN_REFERRAL_FEE_BPS} bps (BlockRun referral)`,
+    ].join('\n');
+}
+async function executeJupiterQuote(input) {
+    const inputMint = resolveMint(input.input_mint);
+    const outputMint = resolveMint(input.output_mint);
+    const inDec = decimalsFor(inputMint);
+    const amountAtomic = toAtomicUnits(input.amount, inDec);
+    try {
+        const order = await ultraOrder({ inputMint, outputMint, amount: amountAtomic });
+        if (order.errorMessage) {
+            return { output: `Jupiter Ultra rejected the quote: ${order.errorMessage}`, isError: true };
+        }
+        return { output: formatQuote(order) };
+    }
+    catch (err) {
+        return {
+            output: `Jupiter Ultra /order failed: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+}
+async function executeJupiterSwap(input, ctx) {
+    const inputMint = resolveMint(input.input_mint);
+    const outputMint = resolveMint(input.output_mint);
+    const inDec = decimalsFor(inputMint);
+    const amountAtomic = toAtomicUnits(input.amount, inDec);
+    // Load wallet first — fail fast if Solana isn't set up.
+    let keypair;
+    try {
+        keypair = await loadSolanaKeypair();
+    }
+    catch (err) {
+        return {
+            output: `No Solana wallet found. Run \`franklin setup solana\` to generate one, or check ~/.blockrun/solana-wallet.json.\n` +
+                `(${err instanceof Error ? err.message : 'unknown error'})`,
+            isError: true,
+        };
+    }
+    // Step 1 — fetch order with our referral identity attached.
+    let order;
+    try {
+        order = await ultraOrder({
+            inputMint,
+            outputMint,
+            amount: amountAtomic,
+            taker: keypair.publicKey.toBase58(),
+        });
+    }
+    catch (err) {
+        return {
+            output: `Jupiter Ultra /order failed: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+    if (order.errorMessage || !order.transaction) {
+        return {
+            output: `Jupiter Ultra rejected the order: ${order.errorMessage ?? 'no transaction returned'}`,
+            isError: true,
+        };
+    }
+    // Step 2 — confirm with user (unless explicit auto_approve override).
+    if (!input.auto_approve && ctx.onAskUser) {
+        const quoteText = formatQuote(order);
+        const question = `Execute this Jupiter swap?\n\n${quoteText}\n\nWallet: ${keypair.publicKey.toBase58()}`;
+        const answer = await ctx.onAskUser(question, ['Confirm', 'Cancel']);
+        if (answer.toLowerCase() !== 'confirm') {
+            return { output: 'Swap cancelled by user.' };
+        }
+    }
+    // Step 3 — sign locally with the user's Solana keypair.
+    let signedBase64;
+    try {
+        const txBytes = Buffer.from(order.transaction, 'base64');
+        const tx = VersionedTransaction.deserialize(txBytes);
+        tx.sign([keypair]);
+        signedBase64 = Buffer.from(tx.serialize()).toString('base64');
+    }
+    catch (err) {
+        return {
+            output: `Failed to sign Jupiter transaction: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+    // Step 4 — submit through Jupiter Ultra (handles broadcast + confirmation).
+    try {
+        const exec = await ultraExecute({
+            signedTransaction: signedBase64,
+            requestId: order.requestId,
+        });
+        if (exec.status !== 'Success') {
+            return {
+                output: `Jupiter Ultra /execute reported ${exec.status}` +
+                    (exec.error ? `: ${exec.error}` : '') +
+                    (exec.code ? ` (code ${exec.code})` : ''),
+                isError: true,
+            };
+        }
+        const sig = exec.signature ?? '<unknown>';
+        const explorer = `https://solscan.io/tx/${sig}`;
+        return {
+            output: [
+                '✓ Swap executed.',
+                formatQuote(order),
+                `Signature: ${sig}`,
+                explorer,
+            ].join('\n'),
+        };
+    }
+    catch (err) {
+        return {
+            output: `Jupiter Ultra /execute failed: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+}
+// ─── Capability handlers ──────────────────────────────────────────────────
+const COMMON_INPUT_PROPERTIES = {
+    input_mint: {
+        type: 'string',
+        description: 'Input SPL mint address, OR a symbol shortcut: SOL, USDC, USDT, JUP, BONK, WIF, TRUMP, PUMP.',
+    },
+    output_mint: {
+        type: 'string',
+        description: 'Output SPL mint address, OR a symbol shortcut (same list as input_mint).',
+    },
+    amount: {
+        type: 'number',
+        description: 'Amount of input_mint to swap, in human units (e.g. 1.5 USDC, 0.05 SOL). Decimals are looked up automatically for known mints; defaults to 9 for unknown mints.',
+    },
+};
+export const jupiterQuoteCapability = {
+    spec: {
+        name: 'JupiterQuote',
+        description: "Read-only price quote for a Solana DEX swap via Jupiter Ultra. Returns input/output amounts, rate, price impact, and routing path. Free — no on-chain transaction, no signing. Use this before JupiterSwap to inspect what a trade would do.",
+        input_schema: {
+            type: 'object',
+            required: ['input_mint', 'output_mint', 'amount'],
+            properties: COMMON_INPUT_PROPERTIES,
+        },
+    },
+    execute: async (input) => {
+        return executeJupiterQuote(input);
+    },
+    concurrent: true,
+};
+export const jupiterSwapCapability = {
+    spec: {
+        name: 'JupiterSwap',
+        description: "Execute a Solana DEX swap via Jupiter Ultra. Quotes the order, asks the user to confirm via AskUser, signs locally with the Franklin Solana wallet, and submits. A 20 bps platform fee is collected on-chain by Jupiter as part of the swap (BlockRun referral — official integrator program). Returns the Solscan transaction link.",
+        input_schema: {
+            type: 'object',
+            required: ['input_mint', 'output_mint', 'amount'],
+            properties: {
+                ...COMMON_INPUT_PROPERTIES,
+                auto_approve: {
+                    type: 'boolean',
+                    description: 'If true, skip the AskUser confirm step. Default false — agent should leave this false unless the user explicitly authorized batch execution for this turn.',
+                },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        return executeJupiterSwap(input, ctx);
+    },
+    concurrent: false,
+};

package/package.json

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