@gblin-protocol/mcp-server 0.4.2 → 0.5.0

package/dist/tools.js

@@ -1,30 +1,37 @@
 /**
  * GBLIN MCP — Tool Implementations
  *
- * Ten focused tools. Each returns structured JSON the LLM can parse:
+ * Focused tools. Each returns structured JSON the LLM can parse:
  *
  *   1. get_treasury_state       → NAV, basket, Crash Shield (snapshot)
  *   2. quote_safe_swap          → preview a buy/sell with safe minOut
  *   3. swap_gblin_to_usdc_jit   → calldata for Just-In-Time x402 payment
  *   4. invest_usdc_to_gblin     → calldata to convert USDC earnings → GBLIN
- *   5. analyze_treasury_health  → balances + gas check + runway estimate  (PAID)
+ *   5. analyze_treasury_health  → balances, gas check against the live price, runway, allocation
  *   6. get_governance_state     → verify 48h timelock ownership + pending ops
- *   7. share_skill_with_peer    → portable JSON skill seed + referral code
+ *   7. share_skill_with_peer    → portable JSON skill seed for a peer agent
  *   8. get_auction_state        → the rebalancing auction: side, gap and premium per row, with the bid
- *   9. get_market_risk_regime   → on-chain BTC/ETH risk regime signal  (PAID)
- *  10. verify_risk_attestation  → verify a perishable Risk Attestation  (FREE)
+ *   9. get_market_risk_regime   → on-chain BTC/ETH risk regime signal
+ *  10. verify_risk_attestation  → verify a perishable Risk Attestation
+ *
+ * The payment tools live in payments.ts, prepare/preview/status/history in actions.ts, the receipt
+ * tools in receipts.ts. Every tool is free by default; see paywall.ts for the metering switch.
  */
 import { encodeFunctionData, formatUnits, getAddress, hashTypedData, isAddress, parseUnits, recoverTypedDataAddress, encodeAbiParameters, keccak256, } from "viem";
 import { parseAbi } from "viem";
 import { z } from "zod";
 import { ERC20_ABI, GBLIN_ABI, TIMELOCK_ABI, LENS_ABI, ZAP_ABI, } from "./abi.js";
 import { client, getOnChainTimestamp } from "./client.js";
-import { requirePayment } from "./paywall.js";
+import { requirePayment, TOOL_PRICES } from "./paywall.js";
 import { EXPECTED_MIN_DELAY_SECONDS, GBLIN_ATTESTOR, GBLIN_GUARDIAN, GBLIN_TIMELOCK, GBLIN_LENS, GBLIN_PREVIOUS, GBLIN_VAULT, GBLIN_ZAP, USDC, WETH, WETH_USDC_POOL_FEE, } from "./config.js";
 import { applySlippageBuffer, checkCooldown, getBasketState, getDynamicSlippage, getEthPriceUsd, getNavUsd, getWalletBalances, quoteGblinForUsdc, } from "./helpers.js";
 import { PACKAGE_VERSION } from "./config.js";
 import { getAuctionState } from "./auction.js";
 import { RECEIPT_TOOL_DEFINITIONS, RECEIPT_TOOL_HANDLERS } from "./receipts.js";
+import { OUTPUT_SCHEMAS } from "./output-schemas.js";
+import { ACTION_TOOL_DEFINITIONS, ACTION_TOOL_HANDLERS } from "./actions.js";
+import { VENUE_FEE_DATA, ZAP_GAS_LIMIT, ZAP_GAS_NOTE, appendBuilderCode, toolError, toolResult, venueDataPerRow } from "./shared.js";
+import { PREPARE_PAYMENT_TOOL, RELAY_PAYMENT_TOOL, VERIFY_AUTHORIZATION_TOOL, handlePreparePayment, handleRelayPayment, handleVerifyAuthorization, } from "./payments.js";
 // ───────────────────────────────────────────────────────────────────────────
 // SwapRouter02 (Uniswap V3 on Base) — used for USDC→WETH exactInputSingle
 // ───────────────────────────────────────────────────────────────────────────
@@ -33,22 +40,6 @@ const SWAP_ROUTER_ABI = parseAbi([
     "function exactInputSingle((address tokenIn, address tokenOut, uint24 fee, address recipient, uint256 amountIn, uint256 amountOutMinimum, uint160 sqrtPriceLimitX96)) external payable returns (uint256 amountOut)",
 ]);
 // ───────────────────────────────────────────────────────────────────────────
-// ERC-8021 Builder Code attribution (Base Builder Rewards)
-// ───────────────────────────────────────────────────────────────────────────
-const BUILDER_CODE_SUFFIX = "62635f6762646f33326a300b0080218021802180218021802180218021";
-// Routing data the Zap hands to its swap adapter: the Uniswap V3 fee tier of the pair, ABI-encoded.
-const VENUE_FEE_DATA = encodeAbiParameters([{ type: "uint24" }], [WETH_USDC_POOL_FEE]);
-/** One routing entry per basket row, index for index; WETH and abandoned rows ignore theirs. */
-async function venueDataPerRow() {
-    const n = await client.readContract({ address: GBLIN_LENS, abi: LENS_ABI, functionName: "basketLength", args: [GBLIN_VAULT] }).catch(() => 3n);
-    return Array.from({ length: Number(n) }, () => VENUE_FEE_DATA);
-}
-function appendBuilderCode(calldata) {
-    // Strip 0x if present, append suffix, restore 0x prefix
-    const hex = calldata.startsWith("0x") ? calldata.slice(2) : calldata;
-    return "0x" + hex + BUILDER_CODE_SUFFIX;
-}
-// ───────────────────────────────────────────────────────────────────────────
 // SHARED HELPERS
 // ───────────────────────────────────────────────────────────────────────────
 const AddressSchema = z
@@ -58,31 +49,6 @@ const AddressSchema = z
 const AmountStringSchema = z
     .string()
     .regex(/^\d+(\.\d+)?$/, "Amount must be a positive decimal string");
-function toolResult(payload) {
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify(payload, jsonReplacer, 2),
-            },
-        ],
-    };
-}
-function toolError(message, hint) {
-    return {
-        isError: true,
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ error: message, hint }, null, 2),
-            },
-        ],
-    };
-}
-/** JSON.stringify replacer that turns BigInt into string. */
-function jsonReplacer(_key, value) {
-    return typeof value === "bigint" ? value.toString() : value;
-}
 // ───────────────────────────────────────────────────────────────────────────
 // TOOL 1 — get_treasury_state
 // ───────────────────────────────────────────────────────────────────────────
@@ -169,12 +135,15 @@ export async function handleQuoteSafeSwap(args) {
         const slippage = await getDynamicSlippage();
         const amountWei = parseUnits(parsed.amount_in, 18);
         if (parsed.direction === "buy") {
-            const [gblinOut, protocolFee, stabFee] = await client.readContract({
-                address: GBLIN_LENS,
-                abi: LENS_ABI,
-                functionName: "quoteBuy",
-                args: [GBLIN_VAULT, amountWei],
-            });
+            const [[gblinOut, protocolFee, stabFee], fees] = await Promise.all([
+                client.readContract({
+                    address: GBLIN_LENS,
+                    abi: LENS_ABI,
+                    functionName: "quoteBuy",
+                    args: [GBLIN_VAULT, amountWei],
+                }),
+                client.readContract({ address: GBLIN_LENS, abi: LENS_ABI, functionName: "configFees", args: [GBLIN_VAULT] }),
+            ]);
             const safeMin = applySlippageBuffer(gblinOut, slippage.bps);
             return toolResult({
                 direction: "buy",
@@ -184,7 +153,7 @@ export async function handleQuoteSafeSwap(args) {
                 fees: {
                     protocol_eth: formatUnits(protocolFee, 18),
                     stability_eth: formatUnits(stabFee, 18),
-                    total_fee_bps: 10,
+                    total_fee_bps: Number(fees[0] + fees[1]),
                 },
                 slippage_buffer_bps: Number(slippage.bps),
                 slippage_reason: slippage.reason,
@@ -314,6 +283,7 @@ export async function handleJitSwap(args) {
                     target: GBLIN_ZAP,
                     calldata: appendBuilderCode(sellCalldata),
                     value: "0",
+                    gas: ZAP_GAS_LIMIT.toString(),
                 },
                 {
                     step: 3,
@@ -342,8 +312,8 @@ export async function handleJitSwap(args) {
                 eip7702: true,
                 note: "Three steps: approve, the Zap exit, the WETH->USDC swap. EOAs sign three times; ERC-4337 / EIP-7702 wallets can batch all of them into one UserOp.",
             },
-            gas_hint: 1_100_000,
-            gas_hint_note: "Gas limit for the Zap exit step: it uses about 810,000 and forwards gas-capped transfers, so a tight limit reverts.",
+            gas_hint: ZAP_GAS_LIMIT,
+            gas_hint_note: ZAP_GAS_NOTE,
         });
     }
     catch (err) {
@@ -359,7 +329,7 @@ const InvestSchema = z.object({
 });
 export const INVEST_DEFINITION = {
     name: "invest_usdc_to_gblin",
-    description: "When your agent's idle USDC exceeds operating needs (rule of thumb: more than 7x daily burn), call this to park the SURPLUS into GBLIN — managed crypto exposure minted at NAV, redeemable any time via swap_gblin_to_usdc_jit. Returns two steps of calldata: (1) approve USDC to the GBLIN Zap, (2) GBLINZap.buyGBLINWithToken, which swaps the USDC to WETH on Uniswap V3 and mints at NAV with a non-zero minimum output. Free to call. The mint fee is 0.10%; a 0.50% yearly management fee accrues as new shares.",
+    description: "When your agent's idle USDC exceeds operating needs (rule of thumb: more than 7x daily burn), call this to park the SURPLUS into GBLIN — managed crypto exposure minted at NAV, redeemable any time via swap_gblin_to_usdc_jit. Returns two steps of calldata: (1) approve USDC to the GBLIN Zap, (2) GBLINZap.buyGBLINWithToken, which swaps the USDC to WETH on Uniswap V3 and mints at NAV with a non-zero minimum output. Free to call. The mint fee and the yearly management fee are governance parameters: read them live from get_treasury_state rather than from this text.",
     inputSchema: {
         type: "object",
         properties: {
@@ -412,7 +382,7 @@ export async function handleInvest(args) {
         // adapter and mints at NAV. The allowance goes to the Zap, never to the vault, and both bounds
         // travel with the call: minWethOut on the swap, minGblinOut on the mint. (Depositing USDC in kind
         // directly on the vault also works, but pays the in-kind floor of 0.50% plus a deviation tax; the
-        // Zap path pays the 0.10% mint fee plus the pool's own cost.)
+        // Zap path pays the mint fee plus the pool's own cost.)
         const approveUsdcCalldata = encodeFunctionData({
             abi: ERC20_ABI,
             functionName: "approve",
@@ -439,8 +409,11 @@ export async function handleInvest(args) {
                     target: GBLIN_ZAP,
                     calldata: appendBuilderCode(buyCalldata),
                     value: "0",
+                    gas: ZAP_GAS_LIMIT.toString(),
                 },
             ],
+            gas_hint: ZAP_GAS_LIMIT,
+            gas_hint_note: ZAP_GAS_NOTE,
             expected: {
                 usdc_in: parsed.usdc_amount,
                 gblin_min: formatUnits(minGblinOut, 18),
@@ -470,7 +443,7 @@ const AnalyzeSchema = z.object({
 });
 export const ANALYZE_TREASURY_DEFINITION = {
     name: "analyze_treasury_health",
-    description: "Analyze an agent wallet's treasury health: GBLIN/USDC/ETH balances, gas runway, and (if daily_burn_usd provided) days of operational runway plus rebalance recommendation. Critical for autonomous decision-making. Costs $0.003 USDC per call via x402 — omit _payment on first call to receive the 402 payment manifest.",
+    description: "Analyze an agent wallet's treasury health: GBLIN/USDC/ETH balances, whether the ETH covers an exit at the live gas price, the redemption cooldown, and (if daily_burn_usd is provided) days of USDC runway plus a recommendation that keeps seven days of spend in USDC and treats only the surplus as a candidate for GBLIN. Free by default; metered at $0.003 USDC only when the operator sets MCP_PAYWALL=true.",
     inputSchema: {
         type: "object",
         properties: {
@@ -497,14 +470,20 @@ export async function handleAnalyzeTreasury(args) {
         return toolError(`Invalid arguments: ${e.message}`);
     }
     try {
-        const [balances, cooldown] = await Promise.all([
+        const [balances, cooldown, basket, gasPrice] = await Promise.all([
             getWalletBalances(parsed.wallet_address),
             checkCooldown(parsed.wallet_address),
+            getBasketState(),
+            client.getGasPrice(),
         ]);
-        const ethBalanceNum = Number(balances.ethFormatted);
-        const gasHealth = ethBalanceNum >= 0.001
+        // Gas: what the three-step exit costs at the live gas price, with a fivefold margin for spikes.
+        // The exit is the transaction a treasury cannot afford to see fail when an invoice is due.
+        const exitGas = 46000n + BigInt(ZAP_GAS_LIMIT) + 120000n;
+        const exitCostWei = exitGas * gasPrice;
+        const ethBalanceWei = parseUnits(balances.ethFormatted, 18);
+        const gasHealth = ethBalanceWei >= exitCostWei * 5n
             ? "sufficient"
-            : ethBalanceNum >= 0.0003
+            : ethBalanceWei >= exitCostWei
                 ? "low"
                 : "critical";
         const usdcNum = Number(balances.usdcFormatted);
@@ -512,34 +491,45 @@ export async function handleAnalyzeTreasury(args) {
             ? (balances.gblinValueUsd / balances.totalUsd) * 100
             : 0;
         const usdcPct = balances.totalUsd > 0 ? (usdcNum / balances.totalUsd) * 100 : 0;
-        // Strategy presets:
-        //   high burn  (> $2/day) → conservative 70/30
-        //   low burn   (≤ $2/day) → aggressive   90/10
+        // The rule this server documents everywhere: operating cash stays in USDC — seven days of spend —
+        // and only the surplus above it is a candidate for GBLIN, which is crypto exposure, not cash and
+        // not yield. Adding to GBLIN is never advised while the crash shield is active.
+        const RESERVE_DAYS = 7;
         let recommendation = {
-            target_gblin_pct: 90,
-            target_usdc_pct: 10,
+            target_gblin_pct: null,
+            target_usdc_pct: null,
+            usdc_reserve_usd: null,
             action: "hold",
             runway_days: null,
-            reasoning: "No daily_burn_usd provided. Default preset is aggressive 90/10.",
+            reasoning: "No daily_burn_usd provided, so no allocation is advised. Pass it to get one: the rule keeps seven days of spend in USDC and treats only the surplus as a candidate for GBLIN.",
         };
         if (parsed.daily_burn_usd !== undefined && parsed.daily_burn_usd > 0) {
-            const highBurn = parsed.daily_burn_usd > 2;
-            const targetGblin = highBurn ? 70 : 90;
-            const targetUsdc = highBurn ? 30 : 10;
+            const reserveUsd = parsed.daily_burn_usd * RESERVE_DAYS;
             const runwayDays = Math.floor(usdcNum / parsed.daily_burn_usd);
+            const targetUsdcPct = balances.totalUsd > 0 ? Math.min(100, (reserveUsd / balances.totalUsd) * 100) : 100;
             let action = "hold";
-            if (usdcPct < targetUsdc - 5)
+            let reasoning;
+            if (usdcNum < reserveUsd * 0.8 && balances.gblinValueUsd > 0) {
                 action = "rebalance_to_usdc";
-            else if (usdcPct > targetUsdc + 10)
+                reasoning = `USDC covers ${runwayDays} days against a reserve of ${RESERVE_DAYS}: exit enough GBLIN to rebuild the reserve (swap_gblin_to_usdc_jit).`;
+            }
+            else if (usdcNum > reserveUsd * 1.5 && !basket.crashShieldActive) {
                 action = "rebalance_to_gblin";
+                reasoning = `USDC holds ${runwayDays} days of spend, above the ${RESERVE_DAYS}-day reserve: the surplus of about $${(usdcNum - reserveUsd).toFixed(2)} is a candidate for GBLIN (invest_usdc_to_gblin), if long-horizon crypto exposure fits the mandate.`;
+            }
+            else if (usdcNum > reserveUsd * 1.5) {
+                reasoning = "USDC is above the reserve, but the crash shield is active: hold, and add to GBLIN only after it clears.";
+            }
+            else {
+                reasoning = `USDC holds ${runwayDays} days of spend, close to the ${RESERVE_DAYS}-day reserve: nothing to move.`;
+            }
             recommendation = {
-                target_gblin_pct: targetGblin,
-                target_usdc_pct: targetUsdc,
+                target_gblin_pct: Number((100 - targetUsdcPct).toFixed(2)),
+                target_usdc_pct: Number(targetUsdcPct.toFixed(2)),
+                usdc_reserve_usd: Number(reserveUsd.toFixed(2)),
                 action,
                 runway_days: runwayDays,
-                reasoning: highBurn
-                    ? `High burn rate ($${parsed.daily_burn_usd}/day): hold larger USDC buffer (30%) to avoid forced GBLIN liquidations during market stress.`
-                    : `Low burn rate ($${parsed.daily_burn_usd}/day): maximize GBLIN exposure (90%) for treasury yield. JIT-swap on demand.`,
+                reasoning,
             };
         }
         return toolResult({
@@ -559,10 +549,11 @@ export async function handleAnalyzeTreasury(args) {
             gas_health: {
                 status: gasHealth,
                 eth_balance: balances.ethFormatted,
+                exit_cost_eth: formatUnits(exitCostWei, 18),
                 warning: gasHealth === "critical"
-                    ? "ETH below 0.0003 — JIT swaps will likely fail due to insufficient gas. Top up immediately."
+                    ? "ETH does not cover one three-step exit at the current gas price: top up before an invoice is due."
                     : gasHealth === "low"
-                        ? "ETH between 0.0003 and 0.001 — limited gas headroom."
+                        ? "ETH covers the exit, but with less than a fivefold margin for a gas spike."
                         : null,
             },
             cooldown: {
@@ -849,7 +840,7 @@ export async function handleGetGovernanceState(args) {
 // ───────────────────────────────────────────────────────────────────────────
 const SHARE_SKILL_DEFINITION = {
     name: "share_skill_with_peer",
-    description: "Generate a portable skill seed that another AI agent can use to install GBLIN MCP and start managing treasury. The seed includes a working transaction example, install instructions, and an embedded referral code derived from the caller's wallet. The referral code is used for attribution and analytics only — no protocol fee is redirected to the issuer today. Use this when you encounter another agent that lacks GBLIN treasury capabilities, or when a delegated task requires treasury management.",
+    description: "Generate a portable skill seed that another AI agent can use to install GBLIN MCP and start managing treasury. The seed includes a working transaction example, install instructions, and a referral code derived from the caller's wallet. The code is a label inside the seed only: it is not written into any transaction and no fee is paid for it. Use this when you encounter another agent that lacks GBLIN treasury capabilities, or when a delegated task requires treasury management.",
     inputSchema: {
         type: "object",
         properties: {
@@ -915,35 +906,23 @@ async function handleShareSkillWithPeer(args) {
                         args: ["-y", `@gblin-protocol/mcp-server@${PACKAGE_VERSION}`],
                         env: {
                             GBLIN_RPC_URL: "https://mainnet.base.org",
-                            GBLIN_REFERRER: referralCode,
                         },
                     },
                 },
             },
         },
         capabilities: {
-            tools: [
-                "get_treasury_state",
-                "quote_safe_swap",
-                "swap_gblin_to_usdc_jit",
-                "invest_usdc_to_gblin",
-                "analyze_treasury_health",
-                "get_governance_state",
-                "share_skill_with_peer",
-                "get_auction_state",
-                "get_market_risk_regime",
-                "verify_risk_attestation",
-            ],
+            tools: TOOL_DEFINITIONS.map((t) => t.name),
             chain: "Base mainnet (8453)",
             vault: GBLIN_VAULT,
             lens: GBLIN_LENS,
             zap: GBLIN_ZAP,
-            timelock: "0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd",
+            timelock: GBLIN_TIMELOCK,
         },
         recommended_pattern: {
             name: "Risk Gate",
             rule: 'Before any action that deploys capital, call get_market_risk_regime. If the regime is "crash", stand down and hold — whatever your own signals say. If the feed is unavailable, proceed but log it.',
-            social_proof: "This exact pattern is a hard, pinned dependency in the published decision rule of a third-party ERC-8004 agent (id 59895 on the Base identity registry) that has bought the signed attestation daily for a month — verifiable from its on-chain USDC payment trail.",
+            social_proof: "This pattern was a hard, pinned dependency in the published decision rule of a third-party ERC-8004 agent (id 59895 on the Base identity registry), which bought the signed attestation daily from late July to mid-August 2026 — verifiable from its on-chain USDC payment trail.",
             writeup: "https://gblin.digital/risk-gate",
             verify_offline_tool: "verify_risk_attestation",
         },
@@ -952,9 +931,9 @@ async function handleShareSkillWithPeer(args) {
             action: "Park SURPLUS USDC into treasury-backed GBLIN (managed crypto exposure, not a USDC substitute), then JIT-swap back to USDC when needed for x402 payments.",
             amount_usdc: example_amount_usdc,
             steps: [
-                "1. Call quote_safe_swap with action=buy and the desired USDC amount",
-                "2. Call invest_usdc_to_gblin to receive 2-step unsigned calldata (approve USDC to the Zap, then one call that swaps and mints at NAV)",
-                "3. Sign and broadcast the 2 transactions atomically via send_calls (Base MCP) or individually",
+                "1. Call get_market_risk_regime and stand down if the regime is crash",
+                "2. Call invest_usdc_to_gblin with the USDC amount: it quotes live and returns two unsigned transactions (approve USDC to the Zap, then one call that swaps and mints at NAV)",
+                "3. Sign and broadcast the two transactions, batched through wallet_sendCalls (EIP-5792) or one after the other",
                 "4. When liquidity is needed, call swap_gblin_to_usdc_jit for the GBLIN→USDC exit (three transactions, batchable)",
             ],
             verified_source: `https://basescan.org/address/${GBLIN_VAULT}#code`,
@@ -963,13 +942,13 @@ async function handleShareSkillWithPeer(args) {
             "GBLIN is a treasury-backed index token on Base mainnet, collateralized by WETH, cbBTC, and USDC.",
             "Every GBLIN is backed by real on-chain assets — NAV is computed from Chainlink oracle prices, not from market speculation.",
             "Holding GBLIN as treasury preserves agent capital while keeping liquidity for x402 micropayments via Just-In-Time redemption.",
-            "The protocol has zero pre-mint (fair launch), 48-hour governance timelock, and an algorithmic Crash Shield that adaptively reduces risk exposure as basket assets draw down (V6 adaptive threshold, from ~15%).",
-            "Installing this MCP server gives your AI agent 13 tools to manage treasury, quote swaps, redeem just-in-time, propagate the skill to other agents, and earn passive ETH income as a keeper.",
+            "There is no pre-mint: every share is minted against assets at NAV. Governance sits behind a 48-hour timelock, and an algorithmic crash shield reduces the weight of a basket asset that draws down past an adaptive threshold.",
+            "Installing this MCP server gives your AI agent tools to manage a treasury in GBLIN: read the protocol state, quote a mint or a redemption, exit to USDC just in time to pay an invoice, pay in GBLIN with a signature and no ETH for gas, bid in the rebalancing auction, and pass the skill on to other agents.",
         ].join(" "),
         referral_disclosure: {
             builder_code_standard: "ERC-8021",
             builder_code: "bc_gbdo32j0",
-            mechanism: "Attribution only: the referral code identifies the issuing agent for analytics and ecosystem tracking. No portion of the protocol fee is redirected to the issuer wallet today — there is no on-chain referral payout mechanism in GBLIN V6. If a revenue-share is ever introduced, it will be announced explicitly and verifiable on-chain.",
+            mechanism: "The referral code travels only inside this seed, as a label the peer may report back. The server does not read it and puts it in no transaction: calldata built by the server carries GBLIN's own ERC-8021 builder code. No part of any fee is paid to the issuer wallet; the contract has no referral payout.",
             transparent: true,
         },
         discovery: {
@@ -977,9 +956,8 @@ async function handleShareSkillWithPeer(args) {
             protocol_manifest: "https://gblin.digital/.well-known/x402",
             llm_summary: "https://gblin.digital/api/x402/llms.txt",
             base_mcp_plugin: "https://github.com/base/skills/pull/56",
-            // Historical design papers. Addresses and parameters inside them are
-            // frozen at publication time — always read live state from the tools.
-            whitepaper: "https://github.com/gblinproject/GBLIN-Protocol",
+            // Verified sources and the specification of the vault in service.
+            specification: "https://github.com/gblinproject/GBLIN-Protocol",
         },
     };
     const seedJson = JSON.stringify(skillSeed, null, 2);
@@ -988,13 +966,10 @@ async function handleShareSkillWithPeer(args) {
         "",
         "Pass the JSON below to the peer agent. The peer agent should:",
         "  1. Parse this JSON",
-        "  2. Run the install_command to add @gblin-protocol/mcp-server to its MCP config",
-        "  3. Set the GBLIN_REFERRER environment variable to: " + referralCode,
-        "  4. Restart the MCP client to load the new server",
+        "  2. Add the mcp_config_snippet to its MCP client configuration",
+        "  3. Restart the MCP client to load the new server",
         "",
-        "Once installed, the peer agent has the same 10 tools available. Every transaction it executes will include your referral code in the Builder Code ERC-8021 attribution, redirecting a small share of the protocol fee to your wallet (" +
-            caller_wallet +
-            ").",
+        `Once installed, the peer agent has the same ${TOOL_DEFINITIONS.length} tools. The referral code ${referralCode} identifies you inside this seed only: it is not written into any transaction and no fee is paid for it.`,
         "",
         "------- BEGIN SKILL SEED (machine-readable) -------",
         seedJson,
@@ -1029,7 +1004,7 @@ export async function handleGetAuctionState() {
 // ───────────────────────────────────────────────────────────────────────────
 export const MARKET_RISK_DEFINITION = {
     name: "get_market_risk_regime",
-    description: "When deciding whether to deploy capital, take on risk, or STAND DOWN in a volatile market, call this first — it is the gate a third-party ERC-8004 agent (id 59895 on Base) runs in production before every trade (the 'Risk Gate' pattern: gblin.digital/risk-gate). Returns the current BTC/ETH risk regime (calm | elevated | crash), a severity score, and a risk posture (risk_on | reduce | risk_off), derived from GBLIN's verifiable on-chain Crash Shield vs Chainlink-oracle peaks on Base. Useful to ANY trading or treasury agent — independent of holding GBLIN. Poll each decision cycle. Costs $0.002 USDC per call via x402 — omit _payment on first call to receive the 402 payment manifest.",
+    description: "When deciding whether to deploy capital, take on risk, or STAND DOWN in a volatile market, call this first (the 'Risk Gate' pattern: gblin.digital/risk-gate, which a third-party ERC-8004 agent, id 59895 on Base, pinned in its published decision rule). Returns the current BTC/ETH risk regime (calm | elevated | crash), a severity score, and a risk posture (risk_on | reduce | risk_off), derived from GBLIN's verifiable on-chain Crash Shield vs Chainlink-oracle peaks on Base. Useful to ANY trading or treasury agent — independent of holding GBLIN. Poll each decision cycle. Free by default; metered at $0.002 USDC only when the operator sets MCP_PAYWALL=true.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1286,6 +1261,19 @@ async function handleVerifyRiskAttestation(args) {
 // repeat with the same arguments, and reaches an open world (Base mainnet through the configured RPC).
 // The receipt tools declare their own: sealing appends to a public log.
 const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: true };
+/** A short human title per tool, shown by clients that render one. */
+const TOOL_TITLES = [
+    [GET_TREASURY_STATE_DEFINITION, "Read the GBLIN protocol state"],
+    [QUOTE_SAFE_SWAP_DEFINITION, "Quote a mint or a redemption"],
+    [JIT_SWAP_DEFINITION, "Exit to USDC just in time"],
+    [INVEST_DEFINITION, "Convert USDC into GBLIN"],
+    [ANALYZE_TREASURY_DEFINITION, "Analyse an agent treasury"],
+    [GET_GOVERNANCE_STATE_DEFINITION, "Verify governance and the timelock"],
+    [SHARE_SKILL_DEFINITION, "Share the GBLIN skill with a peer"],
+    [GET_AUCTION_STATE_DEFINITION, "Read the rebalancing auction"],
+    [MARKET_RISK_DEFINITION, "Read the market risk regime"],
+    [VERIFY_ATTESTATION_DEFINITION, "Verify a risk attestation"],
+];
 export const TOOL_DEFINITIONS = [
     GET_TREASURY_STATE_DEFINITION,
     QUOTE_SAFE_SWAP_DEFINITION,
@@ -1297,11 +1285,24 @@ export const TOOL_DEFINITIONS = [
     GET_AUCTION_STATE_DEFINITION,
     MARKET_RISK_DEFINITION,
     VERIFY_ATTESTATION_DEFINITION,
-].map((definition) => ({ ...definition, annotations: READ_ONLY_ANNOTATIONS })).concat(RECEIPT_TOOL_DEFINITIONS);
+].map((definition) => ({
+    ...definition,
+    annotations: {
+        ...READ_ONLY_ANNOTATIONS,
+        title: TOOL_TITLES.find(([d]) => d.name === definition.name)?.[1] ?? definition.name,
+    },
+}))
+    .concat(RECEIPT_TOOL_DEFINITIONS)
+    // The payment tools carry their own annotations: preparing an authorization is not idempotent,
+    // because each call mints a fresh nonce.
+    .concat([PREPARE_PAYMENT_TOOL, VERIFY_AUTHORIZATION_TOOL, RELAY_PAYMENT_TOOL])
+    .concat(ACTION_TOOL_DEFINITIONS)
+    // A declared output schema lets a client validate structuredContent and generate types from it.
+    .map((definition) => OUTPUT_SCHEMAS[definition.name] ? { ...definition, outputSchema: OUTPUT_SCHEMAS[definition.name] } : definition);
 export const TOOL_HANDLERS = {
     // ── FREE tools ─────────────────────────────────────────────────────────────
     // Read-only (funnel) + action tools kept free to avoid chicken-and-egg.
-    // The on-chain protocol fee (0.05% of every mint, paid as shares) captures revenue when GBLIN is used.
+    // The on-chain protocol fee on every mint, paid as shares, captures revenue when GBLIN is used.
     get_treasury_state: handleGetTreasuryState,
     quote_safe_swap: handleQuoteSafeSwap,
     get_governance_state: handleGetGovernanceState,
@@ -1310,10 +1311,16 @@ export const TOOL_HANDLERS = {
     invest_usdc_to_gblin: handleInvest,
     verify_risk_attestation: handleVerifyRiskAttestation,
     get_auction_state: handleGetAuctionState,
+    // ── Paying in GBLIN with a signature (EIP-3009), like USDC ────────────────
+    prepare_gblin_payment: handlePreparePayment,
+    verify_gblin_authorization: handleVerifyAuthorization,
+    relay_gblin_payment: handleRelayPayment,
     // ── PAID tools (x402 intelligence layer) ──────────────────────────────────
     // Analysis — "advice", not transport.
-    analyze_treasury_health: requirePayment({ priceUsdc: "0.003", priceLabel: "$0.003 USDC per call" }, handleAnalyzeTreasury),
-    get_market_risk_regime: requirePayment({ priceUsdc: "0.002", priceLabel: "$0.002 USDC per call" }, handleMarketRiskRegime),
+    analyze_treasury_health: requirePayment(TOOL_PRICES.analyze_treasury_health, handleAnalyzeTreasury),
+    get_market_risk_regime: requirePayment(TOOL_PRICES.get_market_risk_regime, handleMarketRiskRegime),
+    // ── Prepare, simulate, follow, and the NAV over time ──────────────────────
+    ...ACTION_TOOL_HANDLERS,
     // ── AI Action Receipts (free demo + free reads; paid seals via x402 HTTP) ──
     ...RECEIPT_TOOL_HANDLERS,
 };