@blockrun/franklin 3.11.0 → 3.12.1

package/dist/agent/context.js

@@ -205,6 +205,15 @@ 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/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.
+- \`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/skills/loader.js

@@ -43,6 +43,9 @@ export function parseSkill(content) {
     if (typeof fields['cost-receipt'] === 'boolean') {
         skill.costReceipt = fields['cost-receipt'];
     }
+    if (Array.isArray(fields.triggers)) {
+        skill.triggers = fields.triggers.filter((t) => typeof t === 'string');
+    }
     return { skill, warnings };
 }
 function extractFrontmatter(content) {
@@ -57,6 +60,7 @@ function extractFrontmatter(content) {
     const body = rest.slice(closeIdx + 1 + FRONTMATTER_FENCE.length + 1);
     return { frontmatter, body };
 }
+const LIST_ITEM_RE = /^\s+-\s+(.+)$/;
 function parseFrontmatter(text) {
     const fields = {};
     const warnings = [];
@@ -65,6 +69,9 @@ function parseFrontmatter(text) {
         const line = lines[i];
         if (line.trim() === '' || line.trim().startsWith('#'))
             continue;
+        // YAML list continuation: skip — handled by the key-line that opened it.
+        if (LIST_ITEM_RE.test(line))
+            continue;
         const colon = line.indexOf(':');
         if (colon < 0) {
             return { error: `frontmatter line ${i + 1} is not key: value — got "${line}"` };
@@ -74,6 +81,30 @@ function parseFrontmatter(text) {
         if (key.length === 0) {
             return { error: `frontmatter line ${i + 1} has empty key` };
         }
+        // Empty value followed by indented `- item` lines = YAML list.
+        if (rawValue === '') {
+            const items = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const next = lines[j];
+                if (next.trim() === '') {
+                    j++;
+                    continue;
+                }
+                const m = LIST_ITEM_RE.exec(next);
+                if (!m)
+                    break;
+                items.push(parseScalarString(m[1].trim()));
+                j++;
+            }
+            if (items.length > 0) {
+                fields[key] = items;
+                continue;
+            }
+            // No list followed; treat as empty string.
+            fields[key] = '';
+            continue;
+        }
         fields[key] = parseScalar(rawValue);
     }
     return { fields, warnings };
@@ -140,7 +171,10 @@ function parseScalar(raw) {
         return Number.parseInt(raw, 10);
     if (/^-?\d+\.\d+$/.test(raw))
         return Number.parseFloat(raw);
-    // Strip surrounding quotes if present.
+    return parseScalarString(raw);
+}
+/** Strip surrounding quotes from a string-shaped value, leaving everything else as-is. */
+function parseScalarString(raw) {
     if ((raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) ||
         (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2)) {
         return raw.slice(1, -1);

package/dist/skills/types.d.ts

@@ -21,6 +21,8 @@ export interface ParsedSkill {
     budgetCapUsd?: number;
     /** Franklin extension: append a paid-call receipt under the agent reply. */
     costReceipt?: boolean;
+    /** Trigger phrases that should auto-invoke this skill when matched. */
+    triggers?: string[];
 }
 export type ParseResult = {
     skill: ParsedSkill;

package/dist/skills-bundled/budget-grill/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: budget-grill
 description: Wallet-aware grilling — interview me about a plan one question at a time, with each branch of the decision tree framed as a USDC cost impact
+triggers:
+  - "grill my plan"
+  - "interview my plan"
+  - "budget review"
+  - "cost analysis"
+  - "wallet drain"
+  - "spending review"
+  - "cost impact"
+  - "plan review"
+  - "challenge my idea"
+  - "stress test plan"
 argument-hint: <plan or topic to grill on>
 cost-receipt: true
 ---

package/dist/tools/index.js

@@ -25,6 +25,7 @@ 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 { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -144,6 +145,8 @@ export const allCapabilities = [
     moaCapability,
     webhookPostCapability,
     walletCapability,
+    jupiterQuoteCapability,
+    jupiterSwapCapability,
 ];
 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.11.0",
+  "version": "3.12.1",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {