@gblin-protocol/mcp-server 0.3.2 → 0.4.0

package/dist/tools.js

@@ -10,20 +10,20 @@
  *   5. analyze_treasury_health  → balances + gas check + runway estimate  (PAID)
  *   6. get_governance_state     → verify 48h timelock ownership + pending ops
  *   7. share_skill_with_peer    → portable JSON skill seed + referral code
- *   8. find_keeper_bounty       → check rebalance bounty availability + calldata  (PAID)
+ *   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)
  */
-import { encodeFunctionData, formatUnits, getAddress, hashTypedData, isAddress, parseUnits, recoverTypedDataAddress, } from "viem";
+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 } from "./abi.js";
+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 { EXPECTED_MIN_DELAY_SECONDS, GBLIN_ATTESTOR, GBLIN_GUARDIAN, GBLIN_TIMELOCK, GBLIN_V6, MIN_DEPOSIT_WEI, USDC, WETH, WETH_USDC_POOL_FEE, } from "./config.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 { findKeeperBounty } from "./keeper.js";
+import { getAuctionState } from "./auction.js";
 import { RECEIPT_TOOL_DEFINITIONS, RECEIPT_TOOL_HANDLERS } from "./receipts.js";
 // ───────────────────────────────────────────────────────────────────────────
 // SwapRouter02 (Uniswap V3 on Base) — used for USDC→WETH exactInputSingle
@@ -36,6 +36,13 @@ const SWAP_ROUTER_ABI = parseAbi([
 // 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;
@@ -90,15 +97,21 @@ export const GET_TREASURY_STATE_DEFINITION = {
 };
 export async function handleGetTreasuryState() {
     try {
-        const [navUsd, ethPriceUsd, basket, slippage] = await Promise.all([
+        const [navUsd, ethPriceUsd, basket, slippage, navReliable, mgmtFeeBps, openedAt] = await Promise.all([
             getNavUsd(),
             getEthPriceUsd(),
             getBasketState(),
             getDynamicSlippage(),
+            client.readContract({ address: GBLIN_VAULT, abi: GBLIN_ABI, functionName: "isNavReliable" }).catch(() => false),
+            client.readContract({ address: GBLIN_LENS, abi: LENS_ABI, functionName: "managementFeeBps", args: [GBLIN_VAULT] }).catch(() => 0n),
+            client.readContract({ address: GBLIN_LENS, abi: LENS_ABI, functionName: "auctionOpenedAt", args: [GBLIN_VAULT] }).catch(() => 0n),
         ]);
         return toolResult({
             nav_usd: Number(navUsd.toFixed(6)),
             eth_price_usd: Number(ethPriceUsd.toFixed(2)),
+            nav_reliable: navReliable,
+            management_fee_bps_per_year: Number(mgmtFeeBps),
+            auction_open: openedAt !== 0n,
             crash_shield_active: basket.crashShieldActive,
             slippage_buffer_pct: slippage.pct,
             slippage_reason: slippage.reason,
@@ -108,10 +121,10 @@ export async function handleGetTreasuryState() {
                 base_weight_pct: e.baseWeightBps / 100,
                 dynamic_weight_pct: e.dynamicWeightBps / 100,
                 slashed: e.isSlashed,
-                pool_fee_bps: e.poolFee,
             })),
             meta: {
-                contract: GBLIN_V6,
+                vault: GBLIN_VAULT,
+                lens: GBLIN_LENS,
                 chain: "base",
                 chain_id: 8453,
             },
@@ -156,14 +169,11 @@ export async function handleQuoteSafeSwap(args) {
         const slippage = await getDynamicSlippage();
         const amountWei = parseUnits(parsed.amount_in, 18);
         if (parsed.direction === "buy") {
-            if (amountWei < MIN_DEPOSIT_WEI) {
-                return toolError(`DepositTooSmall: minimum buy is ${formatUnits(MIN_DEPOSIT_WEI, 18)} ETH.`, "Increase amount_in or pool buys into batches.");
-            }
-            const [gblinOut, founderFee, stabFee] = await client.readContract({
-                address: GBLIN_V6,
-                abi: GBLIN_ABI,
-                functionName: "quoteBuyGBLIN",
-                args: [amountWei],
+            const [gblinOut, protocolFee, stabFee] = await client.readContract({
+                address: GBLIN_LENS,
+                abi: LENS_ABI,
+                functionName: "quoteBuy",
+                args: [GBLIN_VAULT, amountWei],
             });
             const safeMin = applySlippageBuffer(gblinOut, slippage.bps);
             return toolResult({
@@ -172,7 +182,7 @@ export async function handleQuoteSafeSwap(args) {
                 expected_gblin_out: formatUnits(gblinOut, 18),
                 safe_min_gblin_out: formatUnits(safeMin, 18),
                 fees: {
-                    founder_eth: formatUnits(founderFee, 18),
+                    protocol_eth: formatUnits(protocolFee, 18),
                     stability_eth: formatUnits(stabFee, 18),
                     total_fee_bps: 10,
                 },
@@ -184,10 +194,10 @@ export async function handleQuoteSafeSwap(args) {
         }
         // sell
         const ethOut = await client.readContract({
-            address: GBLIN_V6,
-            abi: GBLIN_ABI,
-            functionName: "quoteSellGBLIN",
-            args: [amountWei],
+            address: GBLIN_LENS,
+            abi: LENS_ABI,
+            functionName: "quoteSell",
+            args: [GBLIN_VAULT, amountWei],
         });
         const safeMin = applySlippageBuffer(ethOut, slippage.bps);
         return toolResult({
@@ -197,8 +207,8 @@ export async function handleQuoteSafeSwap(args) {
             safe_min_eth_out: formatUnits(safeMin, 18),
             slippage_buffer_bps: Number(slippage.bps),
             slippage_reason: slippage.reason,
-            cooldown_note: "Sell reverts with CooldownActive if last buy was <2 min ago. Check via analyze_treasury_health.",
-            next_step: "Call contract.sellGBLINForEth(amount_in, safe_min_eth_out).",
+            cooldown_note: "A redemption reverts with CooldownActive inside the vault's cooldown after your own mint (read live by analyze_treasury_health).",
+            next_step: "Redeem in kind with vault.sellGBLIN(amount_in) (no fee, no price feed), or exit to ETH through the Zap: approve the shares to it, then GBLINZap.sellGBLINForEth(amount_in, safe_min_eth_out, venueData, receiver) — all or nothing.",
         });
     }
     catch (err) {
@@ -214,7 +224,7 @@ const JitSwapSchema = z.object({
 });
 export const JIT_SWAP_DEFINITION = {
     name: "swap_gblin_to_usdc_jit",
-    description: "When an x402 invoice (or any USDC obligation) arrives and your treasury sits in GBLIN, call this to get ready-to-broadcast calldata that redeems exactly the USDC you need, just in time. Two sequential transactions: (1) redeem GBLIN to ETH directly against the contract (sellGBLINForEth), (2) a Uniswap WETH->USDC swap. EOAs sign twice; ERC-4337 / EIP-7702 wallets can batch both into one UserOp. MEV-safe minOut included, never zero. Free to call — revenue is captured on-chain via the 0.05% founder fee on every swap.",
+    description: "When an x402 invoice (or any USDC obligation) arrives and your treasury sits in GBLIN, call this to get ready-to-broadcast calldata that redeems exactly the USDC you need, just in time. Two sequential transactions: (1) redeem GBLIN to ETH directly against the contract (sellGBLINForEth), (2) a Uniswap WETH->USDC swap. EOAs sign twice; ERC-4337 / EIP-7702 wallets can batch both into one UserOp. MEV-safe minOut included, never zero. Free to call. A redemption carries no protocol fee; the costs are the Zap's swaps and gas.",
     inputSchema: {
         type: "object",
         properties: {
@@ -244,26 +254,34 @@ export async function handleJitSwap(args) {
         }
         // 2. Reverse quote: how much GBLIN to sell?
         const quote = await quoteGblinForUsdc(parsed.usdc_needed);
-        // 3a. Quote the ETH leg: how much ETH sellGBLINForEth returns for that GBLIN.
+        // 3a. Quote the ETH leg through the Lens: what the vault would pay for that many shares.
         const ethExpected = await client.readContract({
-            address: GBLIN_V6,
-            abi: GBLIN_ABI,
-            functionName: "quoteSellGBLIN",
-            args: [quote.gblinToSell],
+            address: GBLIN_LENS,
+            abi: LENS_ABI,
+            functionName: "quoteSell",
+            args: [GBLIN_VAULT, quote.gblinToSell],
         });
         const minEthOut = applySlippageBuffer(ethExpected, quote.slippage.bps);
         if (minEthOut === 0n) {
             return toolError("Quote returned zero ETH out - oracle stale or amount too small.");
         }
-        // V6 removed sellGBLINForToken. GBLIN -> USDC is now two steps:
-        //   TX1: sellGBLINForEth(gblin, minEthOut)  -> agent receives ETH
-        //   TX2: Uniswap exactInputSingle WETH->USDC, paid with the ETH received.
-        // TX2 amountIn = minEthOut (the GUARANTEED minimum from TX1), so the second tx
-        // can never request more ETH than the first actually delivered.
-        const sellCalldata = encodeFunctionData({
+        // The vault redeems in kind and never swaps, so GBLIN -> USDC is three steps:
+        //   TX1: approve the shares to the Zap (it pulls them);
+        //   TX2: Zap.sellGBLINForEth(shares, minEthOut, venueData, receiver): redeem in kind on the vault,
+        //        sell every leg, deliver ETH — all or nothing, so a leg that cannot be sold reverts the
+        //        whole step instead of paying out less;
+        //   TX3: Uniswap exactInputSingle WETH->USDC, paid with the ETH received.
+        // TX3 amountIn = minEthOut (the GUARANTEED minimum from TX2), so the last tx can never request
+        // more ETH than the previous one actually delivered.
+        const approveSharesCalldata = encodeFunctionData({
             abi: GBLIN_ABI,
+            functionName: "approve",
+            args: [GBLIN_ZAP, quote.gblinToSell],
+        });
+        const sellCalldata = encodeFunctionData({
+            abi: ZAP_ABI,
             functionName: "sellGBLINForEth",
-            args: [quote.gblinToSell, minEthOut],
+            args: [quote.gblinToSell, minEthOut, await venueDataPerRow(), parsed.wallet_address],
         });
         const swapCalldata = encodeFunctionData({
             abi: SWAP_ROUTER_ABI,
@@ -285,13 +303,20 @@ export async function handleJitSwap(args) {
             steps: [
                 {
                     step: 1,
-                    description: "Redeem GBLIN to ETH on the GBLIN contract (sellGBLINForEth)",
-                    target: GBLIN_V6,
-                    calldata: appendBuilderCode(sellCalldata),
+                    description: "Approve the shares to the GBLIN Zap",
+                    target: GBLIN_VAULT,
+                    calldata: appendBuilderCode(approveSharesCalldata),
                     value: "0",
                 },
                 {
                     step: 2,
+                    description: "Redeem in kind and sell every leg for ETH through the Zap (all or nothing)",
+                    target: GBLIN_ZAP,
+                    calldata: appendBuilderCode(sellCalldata),
+                    value: "0",
+                },
+                {
+                    step: 3,
                     description: "Swap the received ETH to USDC via Uniswap V3 (WETH->USDC)",
                     target: SWAP_ROUTER_02,
                     calldata: swapCalldata,
@@ -315,7 +340,7 @@ export async function handleJitSwap(args) {
                 eoa: true,
                 erc4337: true,
                 eip7702: true,
-                note: "V6 path is two steps (sellGBLINForEth + Uniswap WETH->USDC). EOAs sign twice; ERC-4337 / EIP-7702 wallets can batch both into one UserOp for atomicity. Both legs carry a minOut, so there is no sandwich surface.",
+                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: 600_000,
         });
@@ -333,7 +358,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 directly from the contract, redeemable any time via swap_gblin_to_usdc_jit. Returns two steps of calldata: (1) approve USDC to the GBLIN contract, (2) buyGBLINInKind(USDC, amount, minGblinOut). No Uniswap leg, MEV-safe minOut, never zero. Free to call - revenue is captured on-chain via the 0.05% founder fee on every buy.",
+    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 directly from the contract, redeemable any time via swap_gblin_to_usdc_jit. Returns two steps of calldata: (1) approve USDC to the GBLIN contract, (2) buyGBLINInKind(USDC, amount, minGblinOut). No Uniswap leg, MEV-safe minOut, never zero. Free to call. An in-kind deposit pays a fee of 0.50% to 2.00% (the floor, plus a tax when the deposit moves the USDC row away from its target); 0.05% of it is minted as shares to the fee recipient and the rest stays in the vault.",
     inputSchema: {
         type: "object",
         properties: {
@@ -373,46 +398,45 @@ export async function handleInvest(args) {
         const ethPriceScaled = BigInt(Math.round(ethPriceUsd * 1_000_000)); // 6 decimals
         const wethExpected = (usdcUnits * parseUnits("1", 18)) / ethPriceScaled;
         const minWethOut = applySlippageBuffer(wethExpected, slippage.bps);
-        if (minWethOut < MIN_DEPOSIT_WEI) {
-            return toolError(`DepositTooSmall: ${parsed.usdc_amount} USDC converts to ~${formatUnits(wethExpected, 18)} WETH, below contract minimum of ${formatUnits(MIN_DEPOSIT_WEI, 18)} ETH.`, "Aggregate more USDC before investing.");
-        }
-        // Quote GBLIN out: value the USDC in ETH terms (USDC ~ $1) via the contract's
-        // own buy quote, then buffer with dynamic slippage so the call won't revert.
+        // Quote the shares for that much WETH through the Lens, then buffer with the dynamic slippage so
+        // the mint does not revert on a small move between quote and block.
         const [gblinExpected] = await client.readContract({
-            address: GBLIN_V6,
-            abi: GBLIN_ABI,
-            functionName: "quoteBuyGBLIN",
-            args: [wethExpected],
+            address: GBLIN_LENS,
+            abi: LENS_ABI,
+            functionName: "quoteBuy",
+            args: [GBLIN_VAULT, wethExpected],
         });
         const minGblinOut = applySlippageBuffer(gblinExpected, slippage.bps);
-        // V6 buys USDC DIRECTLY (in-kind) - no Uniswap swap needed. Two steps only:
-        //   1) approve USDC to the GBLIN contract
-        //   2) buyGBLINInKind(USDC, amountIn, minGblinOut)
+        // Two steps, through the Zap: approve USDC to it, then one call that swaps USDC -> WETH on the
+        // 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.)
         const approveUsdcCalldata = encodeFunctionData({
             abi: ERC20_ABI,
             functionName: "approve",
-            args: [GBLIN_V6, usdcUnits],
+            args: [GBLIN_ZAP, usdcUnits],
         });
         const buyCalldata = encodeFunctionData({
-            abi: GBLIN_ABI,
-            functionName: "buyGBLINInKind",
-            args: [USDC, usdcUnits, minGblinOut],
+            abi: ZAP_ABI,
+            functionName: "buyGBLINWithToken",
+            args: [USDC, usdcUnits, minWethOut, minGblinOut, VENUE_FEE_DATA, parsed.wallet_address],
         });
         return toolResult({
             action: "sequential_txs",
             steps: [
                 {
                     step: 1,
-                    description: "Approve USDC to the GBLIN V6 contract",
+                    description: "Approve USDC to the GBLIN Zap",
                     target: USDC,
                     calldata: appendBuilderCode(approveUsdcCalldata),
                     value: "0",
                 },
                 {
                     step: 2,
-                    description: "Buy GBLIN directly with USDC (V6 in-kind mint, no swap)",
-                    target: GBLIN_V6,
-                    calldata: buyCalldata,
+                    description: "Swap USDC to WETH and mint GBLIN at NAV, in one transaction",
+                    target: GBLIN_ZAP,
+                    calldata: appendBuilderCode(buyCalldata),
                     value: "0",
                 },
             ],
@@ -424,7 +448,7 @@ export async function handleInvest(args) {
             security: {
                 mev_protected: true,
                 min_outs_set: true,
-                note: "minGblinOut > 0, computed from the on-chain quote + dynamic slippage. Reverts on bad execution. No Uniswap swap - USDC is deposited directly as in-kind collateral.",
+                note: "minWethOut and minGblinOut are both above zero, computed from the oracle price and the Lens quote plus the dynamic slippage. Either bound failing reverts the whole call.",
             },
         });
     }
@@ -564,7 +588,7 @@ const GovernanceStateSchema = z.object({
 });
 export const GET_GOVERNANCE_STATE_DEFINITION = {
     name: "get_governance_state",
-    description: "Verify GBLIN protocol governance state: confirms whether GBLIN_V6 is owned by the 48h Timelock, reads the timelock's min delay and grace period, reports role member counts, and surfaces any pending asset-addition proposal on the index contract. If an operation_id is provided, also reports the status of that specific timelock operation. Read-only — use this to gate trust-sensitive agent actions.",
+    description: "Verify GBLIN protocol governance state: confirms whether the GBLIN vault is owned by the 48h Timelock, reads the timelock's min delay and grace period, reports role member counts, and surfaces any pending asset-addition proposal on the index contract. If an operation_id is provided, also reports the status of that specific timelock operation. Read-only — use this to gate trust-sensitive agent actions.",
     inputSchema: {
         type: "object",
         properties: {
@@ -585,22 +609,23 @@ export async function handleGetGovernanceState(args) {
         return toolError(`Invalid arguments: ${e.message}`);
     }
     try {
-        // 1. Read owner + pending asset from GBLIN_V6
-        const [owner, founder, proposedAsset] = await Promise.all([
+        // 1. Owner, pending owner and fee recipient of the vault.
+        const [owner, pendingOwner, feeRecipient] = await Promise.all([
             client.readContract({
-                address: GBLIN_V6,
+                address: GBLIN_VAULT,
                 abi: GBLIN_ABI,
                 functionName: "owner",
             }),
             client.readContract({
-                address: GBLIN_V6,
+                address: GBLIN_VAULT,
                 abi: GBLIN_ABI,
-                functionName: "founderWallet",
+                functionName: "pendingOwner",
             }),
             client.readContract({
-                address: GBLIN_V6,
-                abi: GBLIN_ABI,
-                functionName: "proposedAsset",
+                address: GBLIN_LENS,
+                abi: LENS_ABI,
+                functionName: "feeRecipient",
+                args: [GBLIN_VAULT],
             }),
         ]);
         const ownerNorm = getAddress(owner);
@@ -641,17 +666,13 @@ export async function handleGetGovernanceState(args) {
             // OZ TimelockController v5 uses AccessControl (not AccessControlEnumerable),
             // so getRoleMemberCount is unavailable. Use hasRole on known addresses instead.
             const ZERO = "0x0000000000000000000000000000000000000000";
-            const founderAddr = await client.readContract({
-                address: GBLIN_V6,
-                abi: GBLIN_ABI,
-                functionName: "founderWallet",
-            });
-            const [founderIsProposer, guardianIsCanceller, timelockIsSelfAdmin, executorOpen,] = await Promise.all([
+            const feeRecipientAddr = feeRecipient;
+            const [feeRecipientIsProposer, guardianIsCanceller, timelockIsSelfAdmin, executorOpen,] = await Promise.all([
                 client.readContract({
                     address: GBLIN_TIMELOCK,
                     abi: TIMELOCK_ABI,
                     functionName: "hasRole",
-                    args: [proposerRole, founderAddr],
+                    args: [proposerRole, feeRecipientAddr],
                 }),
                 // Guardian multisig should hold CANCELLER_ROLE (veto power)
                 client.readContract({
@@ -682,7 +703,7 @@ export async function handleGetGovernanceState(args) {
                 min_delay_matches_expected: minDelay === EXPECTED_MIN_DELAY_SECONDS,
                 expected_min_delay_seconds: Number(EXPECTED_MIN_DELAY_SECONDS),
                 roles: {
-                    founder_is_proposer: founderIsProposer,
+                    fee_recipient_is_proposer: feeRecipientIsProposer,
                     guardian_is_canceller: guardianIsCanceller,
                     timelock_is_self_admin: timelockIsSelfAdmin,
                     executor_open_to_anyone: executorOpen,
@@ -758,40 +779,63 @@ export async function handleGetGovernanceState(args) {
                 };
             }
         }
-        // 4. Pending asset proposal inside GBLIN_V6 itself (separate 48h mini-timelock)
-        const [pToken, pOracle, pPoolFee, pIsStable, pBaseWeight, pExecuteAfter] = proposedAsset;
-        const hasPendingAsset = pExecuteAfter > 0n;
-        const nowSec = Math.floor(Date.now() / 1000);
-        const pendingAssetProposal = hasPendingAsset
-            ? {
-                token: getAddress(pToken),
-                oracle: getAddress(pOracle),
-                pool_fee_bps: pPoolFee,
-                is_stable: pIsStable,
-                base_weight_bps: Number(pBaseWeight),
-                execute_after_unix: Number(pExecuteAfter),
-                execute_after_iso: new Date(Number(pExecuteAfter) * 1000).toISOString(),
-                seconds_until_executable: Number(pExecuteAfter) > nowSec ? Number(pExecuteAfter) - nowSec : 0,
+        // 4. A pending handover. Ownership moves in two steps (transferOwnership, then acceptOwnership by
+        //    the new owner), and the timelock can only accept through a scheduled operation. When the
+        //    pending owner is the timelock, the operation id is deterministic — TimelockController v5:
+        //    keccak256(abi.encode(target, value, data, predecessor, salt)) — so its state can be reported.
+        const pendingOwnerNorm = getAddress(pendingOwner);
+        const handoverPending = pendingOwnerNorm !== "0x0000000000000000000000000000000000000000";
+        let pendingHandover = null;
+        if (handoverPending) {
+            pendingHandover = { pending_owner: pendingOwnerNorm, pending_owner_is_timelock: pendingOwnerNorm === timelockNorm };
+            if (pendingOwnerNorm === timelockNorm) {
+                const ZERO32 = `0x${"0".repeat(64)}`;
+                const acceptCalldata = encodeFunctionData({ abi: GBLIN_ABI, functionName: "acceptOwnership" });
+                const opId = keccak256(encodeAbiParameters([{ type: "address" }, { type: "uint256" }, { type: "bytes" }, { type: "bytes32" }, { type: "bytes32" }], [GBLIN_VAULT, 0n, acceptCalldata, ZERO32, ZERO32]));
+                try {
+                    const [isPending, isReady, isDone, ts] = await Promise.all([
+                        client.readContract({ address: GBLIN_TIMELOCK, abi: TIMELOCK_ABI, functionName: "isOperationPending", args: [opId] }),
+                        client.readContract({ address: GBLIN_TIMELOCK, abi: TIMELOCK_ABI, functionName: "isOperationReady", args: [opId] }),
+                        client.readContract({ address: GBLIN_TIMELOCK, abi: TIMELOCK_ABI, functionName: "isOperationDone", args: [opId] }),
+                        client.readContract({ address: GBLIN_TIMELOCK, abi: TIMELOCK_ABI, functionName: "getTimestamp", args: [opId] }),
+                    ]);
+                    const tsNum = Number(ts);
+                    pendingHandover.accept_ownership_operation = {
+                        id: opId,
+                        scheduled: isPending || isDone,
+                        pending: isPending,
+                        ready: isReady,
+                        done: isDone,
+                        execute_after_unix: tsNum > 1 ? tsNum : null,
+                        execute_after_iso: tsNum > 1 ? new Date(tsNum * 1000).toISOString() : null,
+                    };
+                }
+                catch (err) {
+                    pendingHandover.accept_ownership_operation = { id: opId, error: err.message };
+                }
             }
-            : null;
+        }
         return toolResult({
-            gblin_v6: GBLIN_V6,
+            vault: GBLIN_VAULT,
+            lens: GBLIN_LENS,
             owner: ownerNorm,
             owner_is_timelock: ownerIsTimelock,
             owner_is_renounced: ownerIsRenounced,
-            founder_wallet: getAddress(founder),
+            fee_recipient: getAddress(feeRecipient),
             trust_summary: ownerIsRenounced
                 ? "Ownership fully renounced — no admin can touch the contract."
                 : ownerIsTimelock
                     ? "Ownership held by the 48h Timelock. All admin actions are delay-enforced on-chain."
-                    : "WARNING: owner is an EOA / unknown contract — admin actions are NOT timelocked.",
+                    : handoverPending && pendingOwnerNorm === timelockNorm
+                        ? "Ownership is held by the deployer with the 48h Timelock as pending owner; see pending_handover for the scheduled acceptance. Until it executes, admin actions are NOT timelocked."
+                        : "WARNING: owner is an EOA / unknown contract — admin actions are NOT timelocked.",
             timelock: timelockState,
-            pending_asset_proposal: pendingAssetProposal,
+            pending_handover: pendingHandover,
             pending_timelock_operation: operationStatus,
             verification: {
-                gblin_v6_basescan: `https://basescan.org/address/${GBLIN_V6}#readContract`,
+                vault_basescan: `https://basescan.org/address/${GBLIN_VAULT}#readContract`,
+                lens_basescan: `https://basescan.org/address/${GBLIN_LENS}#readContract`,
                 timelock_basescan: `https://basescan.org/address/${GBLIN_TIMELOCK}#readContract`,
-                ownership_transfer_tx: "https://basescan.org/tx/0xb653f54ffa9b1764b41932e6a411077e7e34550605303f15d90900de682edaaf",
             },
         });
     }
@@ -885,12 +929,14 @@ async function handleShareSkillWithPeer(args) {
                 "analyze_treasury_health",
                 "get_governance_state",
                 "share_skill_with_peer",
-                "find_keeper_bounty",
+                "get_auction_state",
                 "get_market_risk_regime",
                 "verify_risk_attestation",
             ],
             chain: "Base mainnet (8453)",
-            contract: GBLIN_V6,
+            vault: GBLIN_VAULT,
+            lens: GBLIN_LENS,
+            zap: GBLIN_ZAP,
             timelock: "0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd",
         },
         recommended_pattern: {
@@ -906,19 +952,18 @@ async function handleShareSkillWithPeer(args) {
             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 → buyGBLINInKind: direct in-kind buy, no swap)",
+                "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",
-                "4. When liquidity is needed, call swap_gblin_to_usdc_jit for atomic GBLIN→USDC redemption",
+                "4. When liquidity is needed, call swap_gblin_to_usdc_jit for the GBLIN→USDC exit (three transactions, batchable)",
             ],
-            verified_on_mainnet: true,
-            reference_tx: "https://basescan.org/tx/0x3d1084f6374dff2125ba337208c4b547d9821523a0a51f797f9fb422c9b24e2c",
+            verified_source: `https://basescan.org/address/${GBLIN_VAULT}#code`,
         },
         natural_language_explanation: [
             "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 8 production-tested tools to manage treasury, quote swaps, redeem just-in-time, propagate the skill to other agents, and earn passive ETH income as a keeper.",
+            "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.",
         ].join(" "),
         referral_disclosure: {
             builder_code_standard: "ERC-8021",
@@ -957,27 +1002,22 @@ async function handleShareSkillWithPeer(args) {
     return toolResult({ text: responseText });
 }
 // ───────────────────────────────────────────────────────────────────────────
-// TOOL 8: find_keeper_bounty
+// TOOL 8: get_auction_state
 // ───────────────────────────────────────────────────────────────────────────
-const FIND_KEEPER_BOUNTY_DEFINITION = {
-    name: "find_keeper_bounty",
-    description: "Check if there is a profitable rebalance opportunity on GBLIN right now. GBLIN pays the caller an on-chain bounty for rebalancing its treasury when it drifts: 0.05% of the rebalanced ETH value (up to double with recent volume), floor 0.00005 ETH, cap 0.01 ETH, at most once per hour and only while the stability fund covers it — the tool reads these rules from the contract at call time. The swap uses the contract's own funds; the caller only pays gas. Returns ready-to-send calldata, the estimated reward, and whether the reward is actually payable right now (rewardGate). Use this when an AI agent wants to earn passive ETH income as a keeper on Base. Costs $0.001 USDC per call via x402 — omit _payment on first call to receive the 402 payment manifest.",
+const GET_AUCTION_STATE_DEFINITION = {
+    name: "get_auction_state",
+    description: "Read the GBLIN rebalancing auction on Base. The vault does not rebalance itself and pays nobody to do it: when a basket row drifts past its band it holds a Dutch auction, and whoever trades with it toward the target weights is the counterparty, at the oracle price adjusted by a premium that starts at a discount and rises to a cap over one ramp. Returns, per row, the side the vault takes, the gap in ETH, the token and amount the bidder hands over, and unsigned calldata (approval + bid). The premium is the whole reward; nothing is paid out of the vault.",
     inputSchema: {
         type: "object",
-        properties: {
-            _payment: {
-                type: "string",
-                description: "Base64-encoded x402 PaymentProof JSON. Omit on first call to receive the 402 payment manifest.",
-            },
-        },
+        properties: {},
         required: [],
         additionalProperties: false,
     },
 };
-async function handleFindKeeperBounty() {
+export async function handleGetAuctionState() {
     try {
-        const bounty = await findKeeperBounty(process.env.GBLIN_RPC_URL);
-        return toolResult(bounty);
+        const state = await getAuctionState();
+        return toolResult(state);
     }
     catch (err) {
         return toolError(err.message, "Check RPC connectivity.");
@@ -1041,30 +1081,18 @@ async function handleMarketRiskRegime() {
             defensive_cash_pct: defensiveCashPct,
             assets,
             source: "GBLIN on-chain Crash Shield (Base mainnet, Chainlink-oracle drawdown)",
-            verify: "https://basescan.org/address/0x36C81d7E1966310F305eA637e761Cf77F90852f0",
-            meta: { contract: GBLIN_V6, chain: "base", chain_id: 8453 },
+            verify: `https://basescan.org/address/${GBLIN_VAULT}#readContract`,
+            meta: { vault: GBLIN_VAULT, lens: GBLIN_LENS, chain: "base", chain_id: 8453 },
         });
     }
     catch (err) {
         return toolError(err.message, "Check RPC connectivity and oracle freshness.");
     }
 }
-// ───────────────────────────────────────────────────────────────────────────
-// TOOL 10 — verify_risk_attestation  (FREE public-good verifier — adoption flywheel)
-//
-// The counterpart to the paid /api/x402/attestation endpoint. Verifying a peer's
-// attestation is FREE on purpose: every agent that verifies one is exposed to
-// GBLIN and learns it can mint its own → drives paid calls to the attestation
-// endpoint. Keyless integrity + EIP-712 recover + live-drift, no RPC secrets.
-// ───────────────────────────────────────────────────────────────────────────
-// EIP-712 schema — MUST stay byte-for-byte identical to the webapp signer
-// (GBLIN_WEBAPP/src/app/api/x402/attestation/route.ts). Do not reorder fields.
-const ATTESTATION_EIP712_DOMAIN = {
-    name: "GBLIN Risk Attestation",
-    version: "1",
-    chainId: 8453,
-    verifyingContract: GBLIN_V6,
-};
+const ATTESTATION_DOMAIN_V1 = { name: "GBLIN Risk Attestation", version: "1", chainId: 8453, verifyingContract: GBLIN_PREVIOUS };
+const ATTESTATION_DOMAIN_V2 = { name: "GBLIN Risk Attestation", version: "2", chainId: 8453, verifyingContract: GBLIN_VAULT };
+const ATTESTATION_EIP712_DOMAINS = { "1": ATTESTATION_DOMAIN_V1, "2": ATTESTATION_DOMAIN_V2 };
+const ATTESTATION_EIP712_DOMAIN = ATTESTATION_DOMAIN_V2;
 const ATTESTATION_EIP712_TYPES = {
     RiskAttestation: [
         { name: "regime", type: "uint8" },
@@ -1117,6 +1145,8 @@ async function handleVerifyRiskAttestation(args) {
     if (!eip712 || !eip712.message || !eip712.domain || !eip712.types) {
         return toolError("Attestation is missing its `eip712` payload (domain/types/message).", "Pass the whole object returned by /api/x402/attestation, including the `eip712` field.");
     }
+    const declaredVersion = String(eip712.domain?.version ?? "");
+    const canonicalDomain = ATTESTATION_EIP712_DOMAINS[declaredVersion] ?? ATTESTATION_EIP712_DOMAIN;
     // Rebuild the typed message (uint64 fields as bigint for viem).
     const m = eip712.message;
     let message;
@@ -1137,7 +1167,7 @@ async function handleVerifyRiskAttestation(args) {
     // 1. INTEGRITY — recompute the id using the CANONICAL schema from this build
     //    (never trust the schema embedded in the payload for hashing).
     const recomputedId = hashTypedData({
-        domain: ATTESTATION_EIP712_DOMAIN,
+        domain: canonicalDomain,
         types: ATTESTATION_EIP712_TYPES,
         primaryType: "RiskAttestation",
         message,
@@ -1146,9 +1176,10 @@ async function handleVerifyRiskAttestation(args) {
     const integrityOk = claimedId ? recomputedId.toLowerCase() === claimedId.toLowerCase() : null;
     // The payload's OWN domain must match the canonical GBLIN domain, else it is
     // a different (untrusted) schema even if internally consistent.
-    const schemaMatches = eip712.domain?.name === ATTESTATION_EIP712_DOMAIN.name &&
-        String(eip712.domain?.version) === ATTESTATION_EIP712_DOMAIN.version &&
-        Number(eip712.domain?.chainId) === ATTESTATION_EIP712_DOMAIN.chainId;
+    const schemaMatches = eip712.domain?.name === canonicalDomain.name &&
+        String(eip712.domain?.version) === canonicalDomain.version &&
+        Number(eip712.domain?.chainId) === canonicalDomain.chainId &&
+        String(eip712.domain?.verifyingContract ?? "").toLowerCase() === canonicalDomain.verifyingContract.toLowerCase();
     // 2. AUTHENTICITY — signature recover
     const expectedAttestor = typeof a.expected_attestor === "string" && isAddress(a.expected_attestor)
         ? getAddress(a.expected_attestor)
@@ -1160,7 +1191,7 @@ async function handleVerifyRiskAttestation(args) {
     if (signature) {
         try {
             recoveredSigner = await recoverTypedDataAddress({
-                domain: ATTESTATION_EIP712_DOMAIN,
+                domain: canonicalDomain,
                 types: ATTESTATION_EIP712_TYPES,
                 primaryType: "RiskAttestation",
                 message,
@@ -1249,6 +1280,11 @@ async function handleVerifyRiskAttestation(args) {
 // ───────────────────────────────────────────────────────────────────────────
 // REGISTRY
 // ───────────────────────────────────────────────────────────────────────────
+// MCP tool annotations. Every tool here reads the chain or does pure math and returns data or
+// unsigned calldata: nothing is written, signed or broadcast, so each one is read-only, safe to
+// 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 };
 export const TOOL_DEFINITIONS = [
     GET_TREASURY_STATE_DEFINITION,
     QUOTE_SAFE_SWAP_DEFINITION,
@@ -1257,15 +1293,14 @@ export const TOOL_DEFINITIONS = [
     ANALYZE_TREASURY_DEFINITION,
     GET_GOVERNANCE_STATE_DEFINITION,
     SHARE_SKILL_DEFINITION,
-    FIND_KEEPER_BOUNTY_DEFINITION,
+    GET_AUCTION_STATE_DEFINITION,
     MARKET_RISK_DEFINITION,
     VERIFY_ATTESTATION_DEFINITION,
-    ...RECEIPT_TOOL_DEFINITIONS,
-];
+].map((definition) => ({ ...definition, annotations: READ_ONLY_ANNOTATIONS })).concat(RECEIPT_TOOL_DEFINITIONS);
 export const TOOL_HANDLERS = {
     // ── FREE tools ─────────────────────────────────────────────────────────────
     // Read-only (funnel) + action tools kept free to avoid chicken-and-egg.
-    // On-chain founder fee (0.05%) captures revenue from every swap/buy.
+    // The on-chain protocol fee (0.05% of every mint, paid as shares) captures revenue when GBLIN is used.
     get_treasury_state: handleGetTreasuryState,
     quote_safe_swap: handleQuoteSafeSwap,
     get_governance_state: handleGetGovernanceState,
@@ -1273,10 +1308,10 @@ export const TOOL_HANDLERS = {
     swap_gblin_to_usdc_jit: handleJitSwap,
     invest_usdc_to_gblin: handleInvest,
     verify_risk_attestation: handleVerifyRiskAttestation,
+    get_auction_state: handleGetAuctionState,
     // ── PAID tools (x402 intelligence layer) ──────────────────────────────────
-    // Analysis and keeper discovery — these are "advice", not transport.
+    // Analysis — "advice", not transport.
     analyze_treasury_health: requirePayment({ priceUsdc: "0.003", priceLabel: "$0.003 USDC per call" }, handleAnalyzeTreasury),
-    find_keeper_bounty: requirePayment({ priceUsdc: "0.001", priceLabel: "$0.001 USDC per call" }, handleFindKeeperBounty),
     get_market_risk_regime: requirePayment({ priceUsdc: "0.002", priceLabel: "$0.002 USDC per call" }, handleMarketRiskRegime),
     // ── AI Action Receipts (free demo + free reads; paid seals via x402 HTTP) ──
     ...RECEIPT_TOOL_HANDLERS,