nebula-ai-plugin-onchain 0.1.0

package/data/tokens.json

@@ -0,0 +1,94 @@
+{
+  "name": "Jaine Token List",
+  "timestamp": "2025-01-03T20:47:02.923Z",
+  "version": {
+    "major": 1,
+    "minor": 0,
+    "patch": 0
+  },
+  "tags": {},
+  "logoURI": "ipfs://QmNa8mQkrNKp1WEEeGjFezDmDeodkWRevGFN8JCV7b4Xir",
+  "keywords": ["jaine", "active"],
+  "tokens": [
+    {
+      "name": "stOG",
+      "address": "0x7bbc63d01ca42491c3e084c941c3e86e55951404",
+      "symbol": "st0G",
+      "decimals": 18,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/0x7bbc63d01ca42491c3e084c941c3e86e55951404/stOG.svg"
+    },
+    {
+      "name": "USDCe",
+      "address": "0x1f3aa82227281ca364bfb3d253b0f1af1da6473e",
+      "symbol": "USDCe",
+      "decimals": 6,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/USDCe.svg"
+    },
+    {
+      "name": "wstETH",
+      "address": "0x161a128567bf0c005b58211757f7e46eed983f02",
+      "symbol": "wstETH",
+      "decimals": 18,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/wstETH.svg"
+    },
+    {
+      "name": "PAI",
+      "address": "0x59ef6f3943bbdfe2fb19565037ac85071223e94c",
+      "symbol": "PAI",
+      "decimals": 9,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/PAI.svg"
+    },
+    {
+      "name": "wETH",
+      "address": "0x564770837ef8bbf077cfe54e5f6106538c815b22",
+      "symbol": "wETH",
+      "decimals": 18,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/wETH.svg"
+    },
+    {
+      "name": "oUSDT",
+      "address": "0x1217bfe6c773eec6cc4a38b5dc45b92292b6e189",
+      "symbol": "oUSDT",
+      "decimals": 6,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/oUSDT.svg"
+    },
+    {
+      "name": "LINK",
+      "address": "0x76159c2b43ff6f630193e37ec68452169914c1bb",
+      "symbol": "LINK",
+      "decimals": 18,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/Link.svg"
+    },
+    {
+      "name": "WBTC",
+      "address": "0x0555e30da8f98308edb960aa94c0db47230d2b9c",
+      "symbol": "wBTC",
+      "decimals": 8,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/wBTC.png"
+    },
+    {
+      "name": "cbBTC",
+      "address": "0xa5613ac7f1e83a68719b1398c8f6aaa25581db82",
+      "symbol": "CoinbaseBTC",
+      "decimals": 8,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/cbBTC.svg"
+    },
+    {
+      "name": "HaiO",
+      "address": "0xbCB868d3d0A823ced82B77DD72E4f7A3C720A40E",
+      "symbol": "HAIO",
+      "decimals": 9,
+      "chainId": 16661,
+      "logoURI": "https://raw.githubusercontent.com/Mantle-X/jaine-token-lists/main/assets/mainnet/HaiO_SVG.svg"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "nebula-ai-plugin-onchain",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The Mantle on-chain tools for nebula: transfers, Agni + Merchant Moe swaps, Aave V3 lending, DeFiLlama discovery, and ERC-8004 identity — every write policy + simulation gated",
+  "license": "MIT",
+  "homepage": "https://github.com/rstfulzz/nebula",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rstfulzz/nebula.git",
+    "directory": "packages/plugin-onchain"
+  },
+  "bugs": {
+    "url": "https://github.com/rstfulzz/nebula/issues"
+  },
+  "keywords": [
+    "nebula",
+    "ai",
+    "agent",
+    "mantle",
+    "defi",
+    "swap",
+    "aave",
+    "agni",
+    "erc-8004",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "abis",
+    "data",
+    "README.md"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "nebula-ai-core": "0.1.0",
+    "viem": "^2.21.55",
+    "zod": "^3.23.8"
+  }
+}

package/src/aave.ts

@@ -0,0 +1,193 @@
+/**
+ * Aave V3 adapter for Mantle. Pool verified live (getReservesList returns the
+ * supported markets). We expose supply / withdraw (writes, guarded by the
+ * policy + simulate pipeline) and a read-only position view (health factor).
+ */
+import { type Address, type PublicClient, erc20Abi, parseAbi } from 'viem'
+import { MULTICALL3 } from './constants'
+
+export const AAVE_V3_POOL_ABI = [
+  {
+    name: 'supply',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'asset', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'onBehalfOf', type: 'address' },
+      { name: 'referralCode', type: 'uint16' },
+    ],
+    outputs: [],
+  },
+  {
+    name: 'withdraw',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'asset', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'to', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+  },
+  {
+    name: 'borrow',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'asset', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'interestRateMode', type: 'uint256' },
+      { name: 'referralCode', type: 'uint16' },
+      { name: 'onBehalfOf', type: 'address' },
+    ],
+    outputs: [],
+  },
+  {
+    name: 'repay',
+    type: 'function',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'asset', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+      { name: 'interestRateMode', type: 'uint256' },
+      { name: 'onBehalfOf', type: 'address' },
+    ],
+    outputs: [{ type: 'uint256' }],
+  },
+  {
+    name: 'getUserAccountData',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [{ name: 'user', type: 'address' }],
+    outputs: [
+      { name: 'totalCollateralBase', type: 'uint256' },
+      { name: 'totalDebtBase', type: 'uint256' },
+      { name: 'availableBorrowsBase', type: 'uint256' },
+      { name: 'currentLiquidationThreshold', type: 'uint256' },
+      { name: 'ltv', type: 'uint256' },
+      { name: 'healthFactor', type: 'uint256' },
+    ],
+  },
+  {
+    name: 'getReservesList',
+    type: 'function',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ type: 'address[]' }],
+  },
+] as const
+
+/** Full-balance sentinel for Aave withdraw (and full-debt sentinel for repay). */
+export const AAVE_MAX_WITHDRAW = (1n << 256n) - 1n
+
+/** Aave V3 interest rate mode: 2 = variable (stable rate mode is deprecated). */
+export const AAVE_VARIABLE_RATE = 2n
+
+/** getReserveData returns the V3 ReserveData struct; we read the two rate fields. */
+const AAVE_RESERVE_DATA_ABI = parseAbi([
+  'struct ReserveData { uint256 configuration; uint128 liquidityIndex; uint128 currentLiquidityRate; uint128 variableBorrowIndex; uint128 currentVariableBorrowRate; uint128 currentStableBorrowRate; uint40 lastUpdateTimestamp; uint16 id; address aTokenAddress; address stableDebtTokenAddress; address variableDebtTokenAddress; address interestRateStrategyAddress; uint128 accruedToTreasury; uint128 unbacked; uint128 isolationModeTotalDebt; }',
+  'function getReserveData(address asset) view returns (ReserveData)',
+  'function getReservesList() view returns (address[])',
+])
+
+const RAY = 10n ** 27n
+
+/** Aave rates are per-second APR scaled to RAY (1e27). APR% = rate / 1e27 * 100. */
+export function rayToAprPct(rateRay: bigint): number {
+  return Number((rateRay * 1_000_000n) / RAY) / 10_000
+}
+
+export interface AaveMarket {
+  symbol: string
+  address: Address
+  supplyAprPct: number
+  variableBorrowAprPct: number
+}
+
+/** Read every Aave V3 reserve on Mantle with its live supply + variable-borrow APR. */
+export async function readAaveMarkets(client: PublicClient, pool: Address): Promise<AaveMarket[]> {
+  const reserves = (await client.readContract({
+    address: pool,
+    abi: AAVE_RESERVE_DATA_ABI,
+    functionName: 'getReservesList',
+  })) as readonly Address[]
+
+  // One Multicall3 batch instead of 2N parallel calls (public RPCs rate-limit
+  // a 20-call burst). For each reserve: getReserveData(pool) + symbol(asset).
+  const contracts = reserves.flatMap(asset => [
+    {
+      address: pool,
+      abi: AAVE_RESERVE_DATA_ABI,
+      functionName: 'getReserveData' as const,
+      args: [asset] as const,
+    },
+    { address: asset, abi: erc20Abi, functionName: 'symbol' as const },
+  ])
+  const results = await client.multicall({
+    contracts,
+    allowFailure: true,
+    multicallAddress: MULTICALL3,
+  })
+
+  return reserves.map((asset, i) => {
+    const dRes = results[i * 2]
+    const symRes = results[i * 2 + 1]
+    const d =
+      dRes?.status === 'success'
+        ? (dRes.result as { currentLiquidityRate: bigint; currentVariableBorrowRate: bigint })
+        : { currentLiquidityRate: 0n, currentVariableBorrowRate: 0n }
+    const symbol = symRes?.status === 'success' ? (symRes.result as string) : '?'
+    return {
+      symbol,
+      address: asset,
+      supplyAprPct: rayToAprPct(d.currentLiquidityRate),
+      variableBorrowAprPct: rayToAprPct(d.currentVariableBorrowRate),
+    }
+  })
+}
+
+export interface AaveAccount {
+  totalCollateralBase: bigint
+  totalDebtBase: bigint
+  availableBorrowsBase: bigint
+  liquidationThresholdBps: bigint
+  ltvBps: bigint
+  healthFactorRaw: bigint
+}
+
+/** Human health factor — '∞ (no debt)' when there is no borrow, else 1e18-scaled. */
+export function formatHealthFactor(raw: bigint): string {
+  if (raw >= AAVE_MAX_WITHDRAW) return '∞ (no debt)'
+  const whole = raw / 10n ** 18n
+  const frac = ((raw % 10n ** 18n) * 100n) / 10n ** 18n
+  return `${whole.toString()}.${frac.toString().padStart(2, '0')}`
+}
+
+/** Aave base currency is USD with 8 decimals on this market. */
+export function formatBaseUsd(base: bigint): string {
+  const whole = base / 10n ** 8n
+  const frac = ((base % 10n ** 8n) * 100n) / 10n ** 8n
+  return `$${whole.toString()}.${frac.toString().padStart(2, '0')}`
+}
+
+export async function readAaveAccount(
+  client: PublicClient,
+  pool: Address,
+  user: Address,
+): Promise<AaveAccount> {
+  const d = (await client.readContract({
+    address: pool,
+    abi: AAVE_V3_POOL_ABI,
+    functionName: 'getUserAccountData',
+    args: [user],
+  })) as readonly bigint[]
+  return {
+    totalCollateralBase: d[0] ?? 0n,
+    totalDebtBase: d[1] ?? 0n,
+    availableBorrowsBase: d[2] ?? 0n,
+    liquidationThresholdBps: d[3] ?? 0n,
+    ltvBps: d[4] ?? 0n,
+    healthFactorRaw: d[5] ?? 0n,
+  }
+}

package/src/abis.ts

@@ -0,0 +1,84 @@
+/**
+ * Typed ABIs for plugin-onchain. Small ABIs use `parseAbi` inline so viem can
+ * infer arg/return types. The big vendored JSON ABIs (SwapRouter, Quoter,
+ * Factory) load via JSON import + `as Abi` cast — too large to inline,
+ * generated from the canonical AGNI testnet artifacts (bytecode-equivalent
+ * on mainnet, verified May 1 2026).
+ */
+
+import { type Abi, parseAbi } from 'viem'
+import factoryJson from '../abis/factory.json' with { type: 'json' }
+import quoterJson from '../abis/quoter.json' with { type: 'json' }
+import swapRouterJson from '../abis/swap-router.json' with { type: 'json' }
+
+export const ERC20_ABI = parseAbi([
+  'function name() view returns (string)',
+  'function symbol() view returns (string)',
+  'function decimals() view returns (uint8)',
+  'function totalSupply() view returns (uint256)',
+  'function balanceOf(address account) view returns (uint256)',
+  'function allowance(address owner, address spender) view returns (uint256)',
+  'function transfer(address to, uint256 amount) returns (bool)',
+  'function approve(address spender, uint256 amount) returns (bool)',
+  'event Transfer(address indexed from, address indexed to, uint256 value)',
+  'event Approval(address indexed owner, address indexed spender, uint256 value)',
+])
+
+export const WETH9_ABI = parseAbi([
+  'function deposit() payable',
+  'function withdraw(uint256 wad)',
+  'function balanceOf(address account) view returns (uint256)',
+  'function totalSupply() view returns (uint256)',
+  'function transfer(address to, uint256 wad) returns (bool)',
+  'function approve(address spender, uint256 wad) returns (bool)',
+  'function name() view returns (string)',
+  'function symbol() view returns (string)',
+  'function decimals() view returns (uint8)',
+])
+
+// `aggregate3` is `payable` on-chain but we only ever call it for batched
+// reads (no msg.value). Marking it `view` here lets viem's `readContract`
+// type-narrowing keep `aggregate3` callable; the runtime contract still
+// accepts the call without msg.value.
+export const MULTICALL3_ABI = parseAbi([
+  'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) view returns ((bool success, bytes returnData)[] returnData)',
+  'function getEthBalance(address addr) view returns (uint256 balance)',
+  'function getBlockNumber() view returns (uint256 blockNumber)',
+])
+
+export const SWAP_ROUTER_ABI = swapRouterJson as Abi
+export const QUOTER_ABI = quoterJson as Abi
+export const FACTORY_ABI = factoryJson as Abi
+
+/**
+ * Merchant Moe Liquidity Book quoter. `findBestPathFromAmountIn` scans LB pairs
+ * for the best route; the last element of `amounts` is the output. `binSteps`
+ * + `versions` + `route` feed directly into the router's swap `Path`.
+ */
+export const LB_QUOTER_ABI = parseAbi([
+  'struct Quote { address[] route; address[] pairs; uint256[] binSteps; uint8[] versions; uint128[] amounts; uint128[] virtualAmountsWithoutSlippage; uint128[] fees; }',
+  'function findBestPathFromAmountIn(address[] route, uint128 amountIn) view returns (Quote)',
+])
+
+/**
+ * Merchant Moe Liquidity Book router. The `Path` struct carries the per-hop bin
+ * steps + pair versions (V1=0, V2=1, V2_1=2, V2_2=3) + token path returned by
+ * the quoter. Native legs go through WNATIVE (WMNT) automatically.
+ */
+export const LB_ROUTER_ABI = parseAbi([
+  'struct Path { uint256[] pairBinSteps; uint8[] versions; address[] tokenPath; }',
+  'function getWNATIVE() view returns (address)',
+  'function swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, Path path, address to, uint256 deadline) returns (uint256 amountOut)',
+  'function swapExactNATIVEForTokens(uint256 amountOutMin, Path path, address to, uint256 deadline) payable returns (uint256 amountOut)',
+  'function swapExactTokensForNATIVE(uint256 amountIn, uint256 amountOutMinNATIVE, Path path, address to, uint256 deadline) returns (uint256 amountOut)',
+])
+
+/** All known function fragments concatenated, for `analysis.decodeCalldata`. */
+export const ALL_KNOWN_ABIS: Abi = [
+  ...(SWAP_ROUTER_ABI as readonly unknown[]),
+  ...(QUOTER_ABI as readonly unknown[]),
+  ...(FACTORY_ABI as readonly unknown[]),
+  ...(WETH9_ABI as readonly unknown[]),
+  ...(ERC20_ABI as readonly unknown[]),
+  ...(MULTICALL3_ABI as readonly unknown[]),
+] as Abi

package/src/allowance.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared ERC-20 allowance helper. Reads current allowance via Multicall3,
+ * sends approve(spender, maxUint256) only if insufficient. Used by
+ * `swap.execute` (Agni router) and `aave.supply` (Aave Pool).
+ */
+
+import { getGasPriceWithFloor } from 'nebula-ai-core'
+import {
+  type Address,
+  type PublicClient,
+  type WalletClient,
+  decodeFunctionResult,
+  encodeFunctionData,
+  getAddress,
+  maxUint256,
+} from 'viem'
+import { ERC20_ABI, MULTICALL3_ABI } from './abis'
+import { MULTICALL3 } from './constants'
+import { waitForReceipt } from './wait-receipt'
+
+export async function readAllowance(opts: {
+  client: PublicClient
+  token: Address
+  owner: Address
+  spender: Address
+}): Promise<bigint> {
+  const { client, token, owner, spender } = opts
+  const calls = [
+    {
+      target: token,
+      allowFailure: false,
+      callData: encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: 'allowance',
+        args: [owner, spender],
+      }),
+    },
+  ]
+  const results = (await client.readContract({
+    address: MULTICALL3,
+    abi: MULTICALL3_ABI,
+    functionName: 'aggregate3',
+    args: [calls],
+  })) as ReadonlyArray<{ success: boolean; returnData: `0x${string}` }>
+  return decodeFunctionResult({
+    abi: ERC20_ABI,
+    functionName: 'allowance',
+    data: results[0]!.returnData,
+  }) as bigint
+}
+
+export async function ensureAllowance(opts: {
+  publicClient: PublicClient
+  walletClient: WalletClient
+  token: Address
+  owner: Address
+  spender: Address
+  amount: bigint
+}): Promise<{ approved: boolean; txHash?: `0x${string}` }> {
+  const { publicClient, walletClient, token, owner, spender, amount } = opts
+  const current = await readAllowance({ client: publicClient, token, owner, spender })
+  if (current >= amount) return { approved: false }
+  const gasPrice = await getGasPriceWithFloor(publicClient)
+  const account = walletClient.account
+  if (!account) throw new Error('walletClient has no account; cannot approve')
+  const txHash = await walletClient.writeContract({
+    address: getAddress(token) as Address,
+    abi: ERC20_ABI,
+    functionName: 'approve',
+    args: [spender, maxUint256],
+    chain: walletClient.chain,
+    account,
+    gasPrice,
+  })
+  await waitForReceipt(publicClient, txHash)
+  return { approved: true, txHash }
+}

package/src/analysis.ts

@@ -0,0 +1,195 @@
+/**
+ * Tx + contract analysis helpers. Tries our local ABI library first, falls
+ * back to the 4byte directory for unknown selectors with a canonical-first
+ * filter (longest, lowercase, simplest signature wins; spam filtered out).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { type AbiFunction, decodeFunctionData, parseAbiItem, toFunctionSelector } from 'viem'
+import { ALL_KNOWN_ABIS } from './abis'
+
+const KNOWN_ABIS = ALL_KNOWN_ABIS as readonly AbiFunction[]
+
+/**
+ * Build a selector → abi item map from KNOWN_ABIS. Multiple ABIs can include
+ * the same selector (e.g. `transfer` in both ERC-20 and W0G); we keep the
+ * first hit since they share the same signature anyway.
+ */
+const KNOWN_SELECTORS = (() => {
+  const map = new Map<string, AbiFunction>()
+  for (const item of KNOWN_ABIS) {
+    if ((item as AbiFunction).type !== 'function') continue
+    const fn = item as AbiFunction
+    try {
+      const sel = toFunctionSelector(fn).toLowerCase()
+      if (!map.has(sel)) map.set(sel, fn)
+    } catch {
+      // skip items that don't selector-encode (events, errors)
+    }
+  }
+  return map
+})()
+
+interface FourByteCacheFile {
+  version: 1
+  hits: Record<string, string> // selector → canonical signature
+}
+
+function fourByteCachePath(agentDir: string): string {
+  return join(agentDir, 'onchain', '4byte-cache.json')
+}
+
+function loadFourByteCache(agentDir: string): FourByteCacheFile {
+  const path = fourByteCachePath(agentDir)
+  if (!existsSync(path)) return { version: 1, hits: {} }
+  try {
+    const raw = readFileSync(path, 'utf8')
+    const parsed = JSON.parse(raw) as FourByteCacheFile
+    if (parsed?.version === 1 && parsed.hits) return parsed
+    return { version: 1, hits: {} }
+  } catch {
+    return { version: 1, hits: {} }
+  }
+}
+
+function saveFourByteCache(agentDir: string, cache: FourByteCacheFile): void {
+  const path = fourByteCachePath(agentDir)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(cache, null, 2))
+}
+
+interface FourByteResult {
+  text_signature: string
+  hex_signature: string
+  bytes_signature: string
+}
+
+/**
+ * Pick the most "canonical" signature out of 4byte's results. Spam bots
+ * register PascalCase or all-caps names whose hashes collide with real
+ * selectors; filter those out, then prefer fewer args + shorter names.
+ */
+function pickCanonical(results: FourByteResult[]): string | null {
+  if (results.length === 0) return null
+  const scored = results
+    .map(r => {
+      const sig = r.text_signature
+      const fnName = sig.split('(')[0] ?? sig
+      const argList = sig.slice(fnName.length + 1, -1)
+      const argCount = argList.length === 0 ? 0 : argList.split(',').length
+      const looksLikeSpam =
+        /^[A-Z][a-zA-Z]*$/.test(fnName) || /[A-Z]{4,}/.test(fnName) || fnName.length > 32
+      return { sig, fnName, argCount, looksLikeSpam }
+    })
+    .filter(s => !s.looksLikeSpam)
+    .sort((a, b) => {
+      if (a.argCount !== b.argCount) return a.argCount - b.argCount
+      if (a.fnName.length !== b.fnName.length) return a.fnName.length - b.fnName.length
+      return a.fnName.localeCompare(b.fnName)
+    })
+  return scored[0]?.sig ?? null
+}
+
+async function lookup4byte(selector: string): Promise<FourByteResult[]> {
+  const url = `https://www.4byte.directory/api/v1/signatures/?hex_signature=${selector}`
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), 5000)
+  try {
+    const res = await fetch(url, { signal: ctrl.signal })
+    if (!res.ok) return []
+    const json = (await res.json()) as { results?: FourByteResult[] }
+    return json.results ?? []
+  } catch {
+    return []
+  } finally {
+    clearTimeout(t)
+  }
+}
+
+export interface DecodedFunction {
+  name: string
+  signature: string
+  args: unknown[]
+  source: 'local' | '4byte' | 'cache'
+}
+
+export async function decodeCalldata(opts: {
+  data: `0x${string}`
+  agentDir: string
+}): Promise<DecodedFunction | { selector: `0x${string}`; source: 'unknown' }> {
+  const { data, agentDir } = opts
+  if (data.length < 10) {
+    return { selector: '0x' as `0x${string}`, source: 'unknown' }
+  }
+  const selector = data.slice(0, 10).toLowerCase() as `0x${string}`
+  // Local ABI hit
+  const localHit = KNOWN_SELECTORS.get(selector)
+  if (localHit) {
+    try {
+      const decoded = decodeFunctionData({
+        abi: [localHit] as readonly [AbiFunction],
+        data,
+      })
+      return {
+        name: localHit.name,
+        signature: formatAbiFunction(localHit),
+        args: Array.isArray(decoded.args) ? [...decoded.args] : [],
+        source: 'local',
+      }
+    } catch {
+      // fall through to 4byte
+    }
+  }
+  // Cache hit
+  const cache = loadFourByteCache(agentDir)
+  const cached = cache.hits[selector]
+  if (cached) {
+    const args = tryDecodeWithSignature(cached, data)?.args ?? []
+    return {
+      name: cached.split('(')[0] ?? cached,
+      signature: cached,
+      args,
+      source: 'cache',
+    }
+  }
+  // 4byte fallback
+  const results = await lookup4byte(selector)
+  const canonical = pickCanonical(results)
+  if (!canonical) {
+    return { selector, source: 'unknown' }
+  }
+  cache.hits[selector] = canonical
+  saveFourByteCache(agentDir, cache)
+  const out = tryDecodeWithSignature(canonical, data)
+  return {
+    name: canonical.split('(')[0] ?? canonical,
+    signature: canonical,
+    args: out?.args ?? [],
+    source: '4byte',
+  }
+}
+
+function tryDecodeWithSignature(
+  sig: string,
+  data: `0x${string}`,
+): { decoded: boolean; args: unknown[] } | null {
+  try {
+    const fn = parseAbiItem(`function ${sig}`) as AbiFunction
+    const decoded = decodeFunctionData({
+      abi: [fn] as readonly [AbiFunction],
+      data,
+    })
+    return {
+      decoded: true,
+      args: Array.isArray(decoded.args) ? [...decoded.args] : [],
+    }
+  } catch {
+    return null
+  }
+}
+
+function formatAbiFunction(fn: AbiFunction): string {
+  const params = fn.inputs.map(p => p.type).join(',')
+  return `${fn.name}(${params})`
+}