nebula-ai-plugin-onchain 0.1.0

package/src/tools/moe.ts

@@ -0,0 +1,245 @@
+/**
+ * `moe.quote` + `moe.swap` — Merchant Moe Liquidity Book swaps.
+ *
+ * A second on-chain DEX venue alongside Agni. The brain can quote both
+ * (`swap.quote` for Agni, `moe.quote` for Merchant Moe) and execute on whichever
+ * is better — agent-driven best execution. `moe.swap` runs the same fund-control
+ * pipeline as every other write: policy -> simulate -> (approval) -> execute.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { getGasPriceWithFloor } from 'nebula-ai-core'
+import { type Address, formatUnits, parseUnits } from 'viem'
+import { z } from 'zod'
+import { ensureAllowance } from '../allowance'
+import {
+  AGNI_BY_NETWORK,
+  DEFAULT_DEADLINE_SECS,
+  DEFAULT_SLIPPAGE_BPS,
+  MOE_LB_BY_NETWORK,
+  requireMainnet,
+} from '../constants'
+import { encodeMoeSwap, quoteMoe } from '../moe'
+import { evaluatePolicy } from '../policy'
+import { simulateRawTx } from '../simulate'
+import { isNativeToken, resolveToken } from '../tokens'
+import type { OnchainRuntimeContext, TokenInfo } from '../types'
+import { waitForReceipt } from '../wait-receipt'
+
+/** WMNT is the wrapped-native used as the path endpoint for native legs. */
+function wmnt(ctx: OnchainRuntimeContext): Address {
+  return AGNI_BY_NETWORK[ctx.network]!.weth9 as Address
+}
+
+async function resolveOrNative(
+  ctx: OnchainRuntimeContext,
+  input: string,
+): Promise<{ token: TokenInfo; isNative: boolean } | null> {
+  if (isNativeToken(input)) {
+    requireMainnet(ctx.network)
+    return {
+      token: {
+        address: wmnt(ctx),
+        symbol: 'WMNT',
+        name: 'Wrapped Mantle',
+        decimals: 18,
+        source: 'list',
+      },
+      isNative: true,
+    }
+  }
+  const t = await resolveToken({ client: ctx.publicClient, agentDir: ctx.agentDir, input })
+  if (!t) return null
+  return { token: t, isNative: false }
+}
+
+const QuoteSchema = z.object({
+  tokenIn: z.string().describe('Input token: symbol, 0x address, or "MNT"/"native".'),
+  tokenOut: z.string().describe('Output token: symbol, 0x address, or "MNT"/"native".'),
+  amountIn: z.string().describe('Input amount in tokenIn units (e.g. "1.5").'),
+  slippageBps: z
+    .number()
+    .int()
+    .nonnegative()
+    .max(10000)
+    .optional()
+    .describe(`Slippage tolerance in basis points (default ${DEFAULT_SLIPPAGE_BPS} = 0.5%).`),
+})
+type QuoteArgs = z.infer<typeof QuoteSchema>
+
+export function makeMoeQuote(ctx: OnchainRuntimeContext): ToolDef<QuoteArgs> {
+  return {
+    name: 'moe.quote',
+    description:
+      'Preview a swap on Merchant Moe (Liquidity Book). Returns the best LB route + amountOut + amountOutMin (after slippage). Read-only. Quote both moe.quote and swap.quote (Agni) to pick the best venue.',
+    searchHint: 'moe merchant moe quote swap price preview liquidity book lb dex best execution',
+    schema: QuoteSchema,
+    handler: async (args: QuoteArgs) => {
+      try {
+        requireMainnet(ctx.network)
+        const moe = MOE_LB_BY_NETWORK[ctx.network]!
+        const tin = await resolveOrNative(ctx, args.tokenIn)
+        const tout = await resolveOrNative(ctx, args.tokenOut)
+        if (!tin) return { ok: false, error: `unknown tokenIn: ${args.tokenIn}` }
+        if (!tout) return { ok: false, error: `unknown tokenOut: ${args.tokenOut}` }
+        const amountInWei = parseUnits(args.amountIn, tin.token.decimals)
+        const quote = await quoteMoe({
+          client: ctx.publicClient,
+          quoter: moe.quoter as Address,
+          route: [tin.token.address, tout.token.address],
+          amountIn: amountInWei,
+        })
+        if (!quote) {
+          return {
+            ok: false,
+            error: `no Merchant Moe LB route with liquidity for ${tin.token.symbol}→${tout.token.symbol}`,
+          }
+        }
+        const slippageBps = BigInt(args.slippageBps ?? DEFAULT_SLIPPAGE_BPS)
+        const amountOutMin = (quote.amountOut * (10000n - slippageBps)) / 10000n
+        return {
+          ok: true,
+          data: {
+            venue: 'Merchant Moe (Liquidity Book)',
+            tokenIn: tin.token.symbol,
+            tokenOut: tout.token.symbol,
+            amountIn: args.amountIn,
+            amountOut: formatUnits(quote.amountOut, tout.token.decimals),
+            amountOutMin: formatUnits(amountOutMin, tout.token.decimals),
+            hops: quote.route.length - 1,
+            slippageBps: Number(slippageBps),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+const ExecuteSchema = z.object({
+  tokenIn: z.string(),
+  tokenOut: z.string(),
+  amountIn: z.string(),
+  slippageBps: z.number().int().nonnegative().max(10000).optional(),
+})
+type ExecuteArgs = z.infer<typeof ExecuteSchema>
+
+export function makeMoeSwap(ctx: OnchainRuntimeContext): ToolDef<ExecuteArgs> {
+  return {
+    name: 'moe.swap',
+    description:
+      'Execute a swap on Merchant Moe (Liquidity Book). Re-quotes at exec for slippage protection; auto-approves the router for ERC-20 input on first use. Runs policy -> simulate -> (approval) -> execute like every write.',
+    searchHint: 'moe merchant moe swap execute trade liquidity book lb dex exchange',
+    schema: ExecuteSchema,
+    handler: async (args: ExecuteArgs) => {
+      try {
+        requireMainnet(ctx.network)
+        const account = ctx.walletClient.account
+        if (!account) return { ok: false, error: 'walletClient has no account; cannot swap' }
+        const moe = MOE_LB_BY_NETWORK[ctx.network]!
+        const tin = await resolveOrNative(ctx, args.tokenIn)
+        const tout = await resolveOrNative(ctx, args.tokenOut)
+        if (!tin) return { ok: false, error: `unknown tokenIn: ${args.tokenIn}` }
+        if (!tout) return { ok: false, error: `unknown tokenOut: ${args.tokenOut}` }
+        const amountInWei = parseUnits(args.amountIn, tin.token.decimals)
+
+        // Policy gate (deterministic): block BEFORE any allowance/quote/execute.
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            {
+              kind: 'swap',
+              asset: tin.isNative ? 'native' : tin.token.address,
+              toAsset: tout.isNative ? 'native' : tout.token.address,
+              amountRaw: amountInWei,
+              slippageBps: Number(args.slippageBps ?? DEFAULT_SLIPPAGE_BPS),
+            },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+
+        const [quote, allow] = await Promise.all([
+          quoteMoe({
+            client: ctx.publicClient,
+            quoter: moe.quoter as Address,
+            route: [tin.token.address, tout.token.address],
+            amountIn: amountInWei,
+          }),
+          tin.isNative
+            ? Promise.resolve({ approved: false, txHash: undefined as `0x${string}` | undefined })
+            : ensureAllowance({
+                publicClient: ctx.publicClient,
+                walletClient: ctx.walletClient,
+                token: tin.token.address,
+                owner: ctx.agentEoa,
+                spender: moe.router as Address,
+                amount: amountInWei,
+              }),
+        ])
+        if (!quote) {
+          return {
+            ok: false,
+            error: `no Merchant Moe LB route for ${tin.token.symbol}→${tout.token.symbol}`,
+          }
+        }
+        const slippageBps = BigInt(args.slippageBps ?? DEFAULT_SLIPPAGE_BPS)
+        const amountOutMin = (quote.amountOut * (10000n - slippageBps)) / 10000n
+        const approveTxHash = allow.txHash
+
+        const composed = encodeMoeSwap({
+          quote,
+          amountIn: amountInWei,
+          amountOutMin,
+          to: ctx.agentEoa,
+          deadline: BigInt(Math.floor(Date.now() / 1000)) + DEFAULT_DEADLINE_SECS,
+          nativeIn: tin.isNative,
+          nativeOut: tout.isNative,
+        })
+
+        const sim = await simulateRawTx(ctx.publicClient, {
+          account: account.address,
+          to: moe.router as Address,
+          data: composed.data,
+          value: composed.value,
+        })
+        if (!sim.ok) {
+          return { ok: false, error: `pre-flight simulation reverted: ${sim.reason}` }
+        }
+        const gasPrice = await getGasPriceWithFloor(ctx.publicClient)
+        const txHash = await ctx.walletClient.sendTransaction({
+          to: moe.router as Address,
+          data: composed.data,
+          value: composed.value,
+          chain: ctx.walletClient.chain,
+          account,
+          gasPrice,
+        })
+        const receipt = await waitForReceipt(ctx.publicClient, txHash)
+        return {
+          ok: true,
+          data: {
+            venue: 'Merchant Moe (Liquidity Book)',
+            ...(approveTxHash ? { approveTxHash } : {}),
+            txHash,
+            blockNumber: Number(receipt.blockNumber),
+            gasUsed: receipt.gasUsed.toString(),
+            tokenIn: tin.token.symbol,
+            tokenOut: tout.token.symbol,
+            amountIn: args.amountIn,
+            amountOutExpected: formatUnits(quote.amountOut, tout.token.decimals),
+            amountOutMin: formatUnits(amountOutMin, tout.token.decimals),
+            status: receipt.status === 'success' ? 'success' : 'reverted',
+            // Decision receipt: proof this swap was policy-checked + simulated.
+            simGasEstimate: sim.gas.toString(),
+            policyEnforced: ctx.policy != null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/nansen.ts

@@ -0,0 +1,71 @@
+/**
+ * `nansen.labels` — Nansen address intelligence for counterparty vetting.
+ * Read-only. Requires NANSEN_API_KEY in the environment (never committed);
+ * surfaces a clear message when the key is unset or out of credits.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { z } from 'zod'
+import { categorySummary, fetchNansenLabels, redFlags } from '../nansen'
+import type { OnchainRuntimeContext } from '../types'
+
+const Schema = z.object({
+  address: z.string().min(1).describe('0x address to look up.'),
+  chain: z
+    .string()
+    .optional()
+    .describe('Chain to query (e.g. "ethereum", "mantle"). Default "ethereum".'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeNansenLabels(_ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'nansen.labels',
+    description:
+      'Nansen entity labels for an address (exchange / fund / smart-money / contract / and red-flag categories like scam, hack, sanctioned, mixer) — vet a counterparty before transacting. Read-only; needs NANSEN_API_KEY in the env. Reports a flagged warning when the address carries a red-flag label.',
+    searchHint:
+      'nansen address labels entity intel exchange smart money scam sanctioned counterparty vet who is',
+    schema: Schema,
+    handler: async (args: Args) => {
+      try {
+        const apiKey = process.env.NANSEN_API_KEY
+        if (!apiKey) {
+          return {
+            ok: true,
+            data: {
+              configured: false,
+              note: 'NANSEN_API_KEY is not set — counterparty intel unavailable. Set it in the env (never commit it) to enable nansen.labels.',
+            },
+          }
+        }
+        const chain = args.chain ?? 'ethereum'
+        const res = await fetchNansenLabels({ address: args.address, chain, apiKey })
+        if (!res.ok) {
+          return {
+            ok: true,
+            data: { address: args.address, chain, available: false, note: res.error },
+          }
+        }
+        const flags = redFlags(res.labels)
+        return {
+          ok: true,
+          data: {
+            address: args.address,
+            chain,
+            labelCount: res.labels.length,
+            categories: categorySummary(res.labels),
+            labels: res.labels.slice(0, 25),
+            flagged: flags.length > 0,
+            ...(flags.length > 0
+              ? {
+                  warning: `RED FLAG: address carries Nansen label(s) in [${flags.join(', ')}] — do not transact without confirmation`,
+                }
+              : {}),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/policy-show.ts

@@ -0,0 +1,74 @@
+/**
+ * `policy.show` — surface the active deterministic fund-control policy.
+ *
+ * The control layer is only trustworthy if it is legible. This read-only tool
+ * reports exactly which caps, allowlists, and autonomy tier are in force for
+ * this session (resolved from NEBULA_POLICY_* at runtime), so the operator (and
+ * the agent, when asked "what are my limits") sees the enforced boundary rather
+ * than guessing. No signer, no state change.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { formatEther } from 'viem'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+const Schema = z.object({})
+type Args = z.infer<typeof Schema>
+
+export function makePolicyShow(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'policy.show',
+    description:
+      'Show the active deterministic fund-control policy: hard caps, allowlists, slippage cap, autonomy tier, and the approval threshold. Read-only. Call this for "what are my limits", "what can you spend", "show the policy", or before explaining why an action was blocked or needs approval.',
+    searchHint:
+      'policy limits caps allowlist autonomy approval guardrails rules what can you spend',
+    schema: Schema,
+    handler: async () => {
+      const p = ctx.policy
+      if (!p) {
+        return {
+          ok: true,
+          data: {
+            enforced: false,
+            note: 'No NEBULA_POLICY_* configured — there are no in-code caps this session. Set NEBULA_POLICY_* (e.g. MAX_NATIVE_MNT, AUTO_MAX_NATIVE_MNT, AUTONOMY) to arm fund controls. Value-moving actions still go through the session permission mode + pre-flight simulation.',
+          },
+        }
+      }
+      const readOnly = p.readOnly === true || p.autonomy === 'readonly'
+      const maxNative =
+        p.maxNativeWeiPerTx === undefined ? null : `${formatEther(p.maxNativeWeiPerTx)} MNT`
+      const autoUpTo =
+        p.autoMaxNativeWeiPerTx === undefined ? null : `${formatEther(p.autoMaxNativeWeiPerTx)} MNT`
+      const lines: string[] = []
+      if (readOnly) lines.push('READ-ONLY: all writes are blocked.')
+      if (maxNative) lines.push(`Hard cap: native sends over ${maxNative} are blocked.`)
+      if (autoUpTo)
+        lines.push(`Auto-execute native sends up to ${autoUpTo}; above that requires approval.`)
+      if (p.maxSlippageBps !== undefined)
+        lines.push(`Swaps over ${p.maxSlippageBps} bps slippage are blocked.`)
+      if (p.recipientAllowlist?.length)
+        lines.push(`Transfers only to ${p.recipientAllowlist.length} allowlisted recipient(s).`)
+      if (p.tokenAllowlist?.length)
+        lines.push(`Only ${p.tokenAllowlist.length} allowlisted token(s) may be moved/swapped.`)
+      if (p.autonomy === 'confirm') lines.push('Autonomy=confirm: every write needs approval.')
+
+      return {
+        ok: true,
+        data: {
+          enforced: true,
+          readOnly,
+          autonomy: p.autonomy ?? 'auto',
+          maxNativePerTx: maxNative,
+          autoApproveUpToNative: autoUpTo,
+          approvalAboveAuto: autoUpTo !== null,
+          maxSlippageBps: p.maxSlippageBps ?? null,
+          recipientAllowlist: p.recipientAllowlist ?? null,
+          tokenAllowlist: p.tokenAllowlist ?? null,
+          summary:
+            lines.length > 0 ? lines.join(' ') : 'Policy armed but with no specific caps set.',
+        },
+      }
+    },
+  }
+}

package/src/tools/risk.ts

@@ -0,0 +1,134 @@
+/**
+ * `risk.token` — pre-trade risk assessment for any Mantle token. Read-only.
+ *
+ * Composes the signals a treasury manager checks before holding or swapping
+ * into an asset: can you actually exit it (a live quote on Agni / Merchant Moe),
+ * how deep is its liquidity, is it a restricted RWA, and is the address even a
+ * contract. Returns a low/elevated/high verdict with plain-language reasons.
+ * Analytics only — moves nothing.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { type Address, parseUnits } from 'viem'
+import { z } from 'zod'
+import { AGNI_BY_NETWORK, MOE_LB_BY_NETWORK } from '../constants'
+import { fetchMantleYields, isRestrictedAsset } from '../defillama'
+import { quoteMoe } from '../moe'
+import { quoteAcrossTiers } from '../quoter'
+import { assessTokenRisk } from '../risk'
+import { resolveToken } from '../tokens'
+import type { OnchainRuntimeContext } from '../types'
+
+const USDC: Address = '0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9'
+
+const Schema = z.object({
+  token: z.string().min(1).describe('Token symbol or 0x address to assess.'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeRiskToken(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'risk.token',
+    description:
+      'Assess the risk of holding or swapping into a Mantle token before you act: tradeability (can you exit it on Agni / Merchant Moe), liquidity depth, restricted-RWA flag, and whether the address is a real contract. Returns a low/elevated/high verdict with reasons. Read-only analytics — call it before proposing a buy/supply into an unfamiliar token.',
+    searchHint:
+      'risk token assess safe rug honeypot liquidity tradeable exit restricted rwa due diligence vet',
+    schema: Schema,
+    handler: async (args: Args) => {
+      try {
+        const wmnt = AGNI_BY_NETWORK[ctx.network]?.weth9 as Address | undefined
+        const moe = MOE_LB_BY_NETWORK[ctx.network]
+        const token = await resolveToken({
+          client: ctx.publicClient,
+          agentDir: ctx.agentDir,
+          input: args.token,
+        })
+        if (!token) {
+          const v = assessTokenRisk({
+            resolved: false,
+            symbol: args.token,
+            restricted: false,
+            tradeableVenues: [],
+            maxPoolTvlUsd: null,
+            isContract: false,
+          })
+          return { ok: true, data: { token: args.token, ...v } }
+        }
+
+        // Reference asset for the tradeability probe (avoid self-pairing).
+        // Agni + Merchant Moe are mainnet-only, so the venue probes run there.
+        const mainnet = ctx.network === 'mantle-mainnet'
+        const ref = token.address.toLowerCase() === USDC.toLowerCase() ? wmnt : USDC
+        const isReference =
+          token.address.toLowerCase() === USDC.toLowerCase() ||
+          (wmnt && token.address.toLowerCase() === wmnt.toLowerCase())
+        const amountIn = parseUnits('1', token.decimals)
+
+        const [code, yields, agni, moeQ] = await Promise.all([
+          // '0x' = genuinely no code (EOA/typo); 'ERR' = RPC failed (don't penalize).
+          ctx.publicClient
+            .getBytecode({ address: token.address })
+            .then(c => c ?? '0x')
+            .catch(() => 'ERR' as const),
+          fetchMantleYields({ minTvlUsd: 0, sortBy: 'tvl', limit: 50 }).catch(() => []),
+          mainnet && ref
+            ? quoteAcrossTiers({
+                client: ctx.publicClient,
+                network: 'mantle-mainnet',
+                tokenIn: token.address,
+                tokenOut: ref,
+                amountIn,
+              }).catch(() => null)
+            : Promise.resolve(null),
+          mainnet && ref && moe
+            ? quoteMoe({
+                client: ctx.publicClient,
+                quoter: moe.quoter as Address,
+                route: [token.address, ref],
+                amountIn,
+              }).catch(() => null)
+            : Promise.resolve(null),
+        ])
+
+        const tradeableVenues: string[] = []
+        if (isReference) {
+          tradeableVenues.push('reference asset (deep liquidity)')
+        } else {
+          if (agni) tradeableVenues.push('Agni Finance')
+          if (moeQ) tradeableVenues.push('Merchant Moe')
+        }
+
+        const sym = token.symbol.toUpperCase()
+        const maxPoolTvlUsd =
+          yields
+            .filter(p => p.symbol.toUpperCase().includes(sym))
+            .reduce((mx, p) => Math.max(mx, p.tvlUsd), 0) || null
+
+        const verdict = assessTokenRisk({
+          resolved: true,
+          symbol: token.symbol,
+          restricted: isRestrictedAsset(token.symbol, ''),
+          tradeableVenues,
+          maxPoolTvlUsd,
+          // Only a successful '0x' read means "not a contract"; an RPC error must
+          // not down-rank a real token.
+          isContract: code === 'ERR' ? true : code !== '0x',
+        })
+
+        return {
+          ok: true,
+          data: {
+            token: token.symbol,
+            address: token.address,
+            tradeableVenues,
+            maxPoolTvlUsd,
+            restricted: isRestrictedAsset(token.symbol, ''),
+            ...verdict,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/simulate-tx.ts

@@ -0,0 +1,98 @@
+/**
+ * `tx.simulate` — dry-run any contract call before doing it. Read-only: it
+ * never broadcasts. Exposes the same pre-flight simulation engine that guards
+ * every write, as a tool the agent (or operator) can point at an arbitrary
+ * call to answer "would this succeed, and what would it cost?" up front.
+ *
+ * Same arg shape as `chain.write` (to + signature + args + value) plus an
+ * optional `from` to simulate as another account.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { type Address, encodeFunctionData, getAddress, isAddress } from 'viem'
+import { z } from 'zod'
+import { simulateRawTx } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+import { buildAbiFunction, coerceArg, parseChainWriteValue } from './generic'
+
+const Schema = z.object({
+  to: z.string().min(42).describe('0x contract address to call.'),
+  signature: z
+    .string()
+    .optional()
+    .describe('Function signature, e.g. "transfer(address,uint256)". Omit if passing raw `data`.'),
+  args: z.array(z.unknown()).optional().describe('Args matching the signature.'),
+  data: z.string().optional().describe('Raw calldata hex (alternative to signature+args).'),
+  value: z
+    .string()
+    .optional()
+    .describe('Native value to attach. Decimal MNT ("0.01") or wei integer.'),
+  from: z.string().optional().describe('Account to simulate as (default: the agent EOA).'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeTxSimulate(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'tx.simulate',
+    description:
+      'Dry-run a contract call WITHOUT broadcasting: returns whether it would succeed and the gas estimate, or the decoded revert reason if it would fail. Pass `to` + `signature` + `args` (like chain.write) or raw `data`, plus optional `value`/`from`. Read-only. Use it to preview an action, debug a revert, or check a call before proposing it.',
+    searchHint:
+      'simulate dry run preview estimate gas would revert test call before execute eth_estimategas',
+    schema: Schema,
+    handler: async (args: Args) => {
+      try {
+        let data: `0x${string}` | undefined
+        if (args.signature) {
+          const fn = buildAbiFunction(args.signature)
+          const coerced = (args.args ?? []).map(coerceArg)
+          data = encodeFunctionData({
+            abi: [fn] as readonly [import('viem').AbiFunction],
+            args: coerced,
+          })
+        } else if (args.data) {
+          data = args.data as `0x${string}`
+        } else {
+          return { ok: false, error: 'provide either `signature` (+args) or raw `data`' }
+        }
+        if (!isAddress(args.to)) return { ok: false, error: `invalid address: ${args.to}` }
+        const from =
+          args.from && isAddress(args.from) ? (getAddress(args.from) as Address) : ctx.agentEoa
+        const value = args.value ? parseChainWriteValue(args.value) : undefined
+
+        const sim = await simulateRawTx(ctx.publicClient, {
+          account: from,
+          to: getAddress(args.to) as Address,
+          data,
+          value,
+        })
+
+        if (sim.ok) {
+          return {
+            ok: true,
+            data: {
+              wouldSucceed: true,
+              gasEstimate: sim.gas.toString(),
+              to: getAddress(args.to),
+              from,
+              ...(args.signature ? { signature: args.signature } : {}),
+              ...(value !== undefined ? { value: value.toString() } : {}),
+              note: 'Dry-run only — nothing was broadcast.',
+            },
+          }
+        }
+        return {
+          ok: true,
+          data: {
+            wouldSucceed: false,
+            revertReason: sim.reason,
+            to: getAddress(args.to),
+            from,
+            note: 'Dry-run only — this call would revert; nothing was broadcast.',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}