nebula-ai-plugin-onchain 0.1.0

package/src/tools/swap-best.ts

@@ -0,0 +1,218 @@
+/**
+ * `swap.compare` + `swap.best` — multi-venue best execution across Agni and
+ * Merchant Moe.
+ *
+ * `swap.compare` (read-only) quotes the same trade on both DEXes and reports
+ * which returns more output. `swap.best` does the same, then EXECUTES on the
+ * winning venue by delegating to that venue's existing tool — so the trade runs
+ * through the identical policy -> simulate -> (approval) -> execute pipeline and
+ * decision receipt, with no duplicated execution path.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { type Address, formatUnits, parseUnits } from 'viem'
+import { z } from 'zod'
+import { AGNI_BY_NETWORK, MOE_LB_BY_NETWORK, requireMainnet } from '../constants'
+import { quoteMoe } from '../moe'
+import { quoteAcrossTiers } from '../quoter'
+import { isNativeToken, resolveToken } from '../tokens'
+import type { OnchainRuntimeContext } from '../types'
+import { makeMoeSwap } from './moe'
+import { makeSwapExecute } from './swap'
+
+interface Resolved {
+  address: Address
+  decimals: number
+  symbol: string
+  isNative: boolean
+}
+
+async function resolve(ctx: OnchainRuntimeContext, input: string): Promise<Resolved | null> {
+  if (isNativeToken(input)) {
+    return {
+      address: AGNI_BY_NETWORK[ctx.network]!.weth9 as Address,
+      decimals: 18,
+      symbol: 'WMNT',
+      isNative: true,
+    }
+  }
+  const t = await resolveToken({ client: ctx.publicClient, agentDir: ctx.agentDir, input })
+  if (!t) return null
+  return { address: t.address, decimals: t.decimals, symbol: t.symbol, isNative: false }
+}
+
+const Schema = 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(),
+})
+type Args = z.infer<typeof Schema>
+
+export interface VenueQuote {
+  venue: 'agni' | 'moe'
+  amountOutRaw: bigint
+  amountOut: string
+}
+
+export interface RankedQuotes {
+  sorted: VenueQuote[]
+  best: VenueQuote
+  /** Output edge of the best venue over the worst, percent (null if one venue). */
+  edgePct: number | null
+}
+
+/** Pure: rank venue quotes by output desc and compute the best-vs-worst edge. */
+export function rankVenueQuotes(quotes: VenueQuote[]): RankedQuotes | null {
+  if (quotes.length === 0) return null
+  const sorted = [...quotes].sort((a, b) =>
+    b.amountOutRaw > a.amountOutRaw ? 1 : b.amountOutRaw < a.amountOutRaw ? -1 : 0,
+  )
+  const best = sorted[0]!
+  const worst = sorted[sorted.length - 1]!
+  const edgePct =
+    sorted.length > 1 && worst.amountOutRaw > 0n
+      ? Number(((best.amountOutRaw - worst.amountOutRaw) * 10000n) / worst.amountOutRaw) / 100
+      : null
+  return { sorted, best, edgePct }
+}
+
+async function quoteVenues(
+  ctx: OnchainRuntimeContext,
+  args: Args,
+): Promise<
+  | { ok: false; error: string }
+  | {
+      ok: true
+      tokenIn: string
+      tokenOut: string
+      decimalsOut: number
+      quotes: VenueQuote[]
+    }
+> {
+  requireMainnet(ctx.network)
+  const tin = await resolve(ctx, args.tokenIn)
+  const tout = await resolve(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.decimals)
+  const moe = MOE_LB_BY_NETWORK[ctx.network]!
+
+  const [agni, moeQ] = await Promise.all([
+    quoteAcrossTiers({
+      client: ctx.publicClient,
+      network: ctx.network,
+      tokenIn: tin.address,
+      tokenOut: tout.address,
+      amountIn: amountInWei,
+    }).catch(() => null),
+    quoteMoe({
+      client: ctx.publicClient,
+      quoter: moe.quoter as Address,
+      route: [tin.address, tout.address],
+      amountIn: amountInWei,
+    }).catch(() => null),
+  ])
+
+  const quotes: VenueQuote[] = []
+  if (agni)
+    quotes.push({
+      venue: 'agni',
+      amountOutRaw: agni.amountOut,
+      amountOut: formatUnits(agni.amountOut, tout.decimals),
+    })
+  if (moeQ)
+    quotes.push({
+      venue: 'moe',
+      amountOutRaw: moeQ.amountOut,
+      amountOut: formatUnits(moeQ.amountOut, tout.decimals),
+    })
+  if (quotes.length === 0)
+    return {
+      ok: false,
+      error: `no liquidity on Agni or Merchant Moe for ${tin.symbol}→${tout.symbol}`,
+    }
+
+  return {
+    ok: true,
+    tokenIn: tin.symbol,
+    tokenOut: tout.symbol,
+    decimalsOut: tout.decimals,
+    quotes,
+  }
+}
+
+function venueLabel(v: 'agni' | 'moe'): string {
+  return v === 'agni' ? 'Agni Finance' : 'Merchant Moe (Liquidity Book)'
+}
+
+export function makeSwapCompare(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'swap.compare',
+    description:
+      'Compare a swap across both DEX venues (Agni + Merchant Moe) and report which returns more output. Read-only. Use before a non-trivial swap, or call swap.best to compare AND execute on the winner in one step.',
+    searchHint: 'swap compare best execution venue route agni moe which dex better price quote',
+    schema: Schema,
+    handler: async (args: Args) => {
+      try {
+        const r = await quoteVenues(ctx, args)
+        if (!r.ok) return { ok: false, error: r.error }
+        const ranked = rankVenueQuotes(r.quotes)!
+        return {
+          ok: true,
+          data: {
+            tokenIn: r.tokenIn,
+            tokenOut: r.tokenOut,
+            amountIn: args.amountIn,
+            best: {
+              venue: venueLabel(ranked.best.venue),
+              amountOut: ranked.best.amountOut,
+            },
+            quotes: ranked.sorted.map(q => ({
+              venue: venueLabel(q.venue),
+              amountOut: q.amountOut,
+            })),
+            bestEdgePct: ranked.edgePct,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+export function makeSwapBest(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'swap.best',
+    description:
+      'Best execution: quote the swap on BOTH Agni and Merchant Moe, then execute on whichever returns more output. Runs the winning venue through the full policy -> simulate -> (approval) -> execute pipeline. One call instead of quoting both venues by hand.',
+    searchHint: 'swap best execution auto route smart order router agni moe trade exchange optimal',
+    schema: Schema,
+    handler: async (args: Args) => {
+      try {
+        const r = await quoteVenues(ctx, args)
+        if (!r.ok) return { ok: false, error: r.error }
+        const ranked = rankVenueQuotes(r.quotes)!
+        // Delegate execution to the winning venue's existing tool: same args,
+        // same policy/simulate/approval/receipt pipeline (re-quotes at exec).
+        const executor = ranked.best.venue === 'agni' ? makeSwapExecute(ctx) : makeMoeSwap(ctx)
+        const exec = await executor.handler(args)
+        if (!exec.ok) return exec
+        return {
+          ok: true,
+          data: {
+            routedTo: venueLabel(ranked.best.venue),
+            comparedQuotes: ranked.sorted.map(q => ({
+              venue: venueLabel(q.venue),
+              amountOut: q.amountOut,
+            })),
+            ...(exec.data as Record<string, unknown>),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/swap.ts

@@ -0,0 +1,253 @@
+/**
+ * `swap.quote` + `swap.execute` — AGNI V3 single-pool swaps with 3-tier scan.
+ *
+ * Quote and execute share the same resolver path so the executed price
+ * matches what was quoted (re-quote at exec for slippage protection).
+ */
+
+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,
+  requireMainnet,
+} from '../constants'
+import { evaluatePolicy } from '../policy'
+import { quoteAcrossTiers } from '../quoter'
+import { simulateRawTx } from '../simulate'
+import { type ExactInputSingleParams, composeSwap } from '../swap'
+import { isNativeToken, resolveToken } from '../tokens'
+import type { OnchainRuntimeContext, TokenInfo } from '../types'
+import { waitForReceipt } from '../wait-receipt'
+
+async function resolveOrNative(
+  ctx: OnchainRuntimeContext,
+  input: string,
+): Promise<{ token: TokenInfo; isNative: boolean } | null> {
+  if (isNativeToken(input)) {
+    requireMainnet(ctx.network)
+    const wmnt = AGNI_BY_NETWORK[ctx.network]!.weth9
+    return {
+      token: {
+        address: wmnt as Address,
+        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 "Mantle"/"native".'),
+  tokenOut: z.string().describe('Output token: symbol, 0x address, or "Mantle"/"native".'),
+  amountIn: z.string().describe('Input amount in tokenIn units (e.g. "0.005").'),
+  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 makeSwapQuote(ctx: OnchainRuntimeContext): ToolDef<QuoteArgs> {
+  return {
+    name: 'swap.quote',
+    description:
+      'Preview a swap on AGNI. Scans all 3 fee tiers and returns the best route + amountOut + amountOutMin (after slippage). Read-only.',
+    searchHint: 'swap quote price preview agni dex amountout',
+    schema: QuoteSchema,
+    handler: async args => {
+      try {
+        requireMainnet(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 quoteAcrossTiers({
+          client: ctx.publicClient,
+          network: ctx.network,
+          tokenIn: tin.token.address,
+          tokenOut: tout.token.address,
+          amountIn: amountInWei,
+        })
+        if (!quote) {
+          return {
+            ok: false,
+            error: `no AGNI pool 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: {
+            tokenIn: tin.token.symbol,
+            tokenOut: tout.token.symbol,
+            amountIn: args.amountIn,
+            amountOut: formatUnits(quote.amountOut, tout.token.decimals),
+            amountOutMin: formatUnits(amountOutMin, tout.token.decimals),
+            fee: quote.fee,
+            pool: quote.pool,
+            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 makeSwapExecute(ctx: OnchainRuntimeContext): ToolDef<ExecuteArgs> {
+  return {
+    name: 'swap.execute',
+    description:
+      'Execute a swap on AGNI. Re-quotes at exec time for slippage protection; auto-approves the router for ERC-20 input on first use. Native via multicall+refundETH; native output via unwrapWETH9 chain.',
+    searchHint: 'swap execute trade agni dex exchange',
+    schema: ExecuteSchema,
+    handler: async args => {
+      try {
+        requireMainnet(ctx.network)
+        const account = ctx.walletClient.account
+        if (!account) return { ok: false, error: 'walletClient has no account; cannot swap' }
+        const agni = AGNI_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('; ')}` }
+          }
+        }
+        // Quote and allowance are independent: race them so the ERC-20 path
+        // doesn't pay two sequential RPC round-trips when one would do.
+        // Native input has no allowance to ensure (router pulls via msg.value).
+        const [quote, allow] = await Promise.all([
+          quoteAcrossTiers({
+            client: ctx.publicClient,
+            network: ctx.network,
+            tokenIn: tin.token.address,
+            tokenOut: 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: agni.swapRouter as Address,
+                amount: amountInWei,
+              }),
+        ])
+        if (!quote) {
+          return {
+            ok: false,
+            error: `no AGNI pool 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 params: ExactInputSingleParams = {
+          tokenIn: tin.token.address,
+          tokenOut: tout.token.address,
+          fee: quote.fee,
+          recipient: ctx.agentEoa,
+          deadline: BigInt(Math.floor(Date.now() / 1000)) + DEFAULT_DEADLINE_SECS,
+          amountIn: amountInWei,
+          amountOutMinimum: amountOutMin,
+          sqrtPriceLimitX96: 0n,
+        }
+        const composed = composeSwap({
+          params,
+          nativeIn: tin.isNative,
+          nativeOut: tout.isNative,
+          router: agni.swapRouter as Address,
+        })
+        // Simulate-before-write: dry-run the composed swap; abort if it would revert.
+        const sim = await simulateRawTx(ctx.publicClient, {
+          account: account.address,
+          to: composed.to,
+          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: composed.to,
+          data: composed.data,
+          value: composed.value,
+          chain: ctx.walletClient.chain,
+          account,
+          gasPrice,
+        })
+        const receipt = await waitForReceipt(ctx.publicClient, txHash)
+        return {
+          ok: true,
+          data: {
+            ...(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),
+            fee: quote.fee,
+            pool: quote.pool,
+            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/tokens-info.ts

@@ -0,0 +1,49 @@
+/**
+ * `tokens.info` — resolve a symbol or address to token metadata.
+ *
+ * Source priority: cache → vendored AGNI list → on-chain ERC-20 reads
+ * (cache-write-through). Returns `{symbol, name, address, decimals, source}`.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { z } from 'zod'
+import { isNativeToken, nativeTokenInfo, resolveToken } from '../tokens'
+import type { OnchainRuntimeContext } from '../types'
+
+const Schema = z.object({
+  symbol: z.string().optional().describe('Symbol (e.g. "USDCe", "stOG", "Mantle").'),
+  address: z.string().optional().describe('0x token contract address.'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeTokensInfo(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'tokens.info',
+    description:
+      'Resolve a token symbol or address to {symbol, name, address, decimals, source}. Tries local cache → vendored AGNI token list → on-chain ERC-20 reads (cached after).',
+    searchHint: 'token metadata symbol decimals erc20 lookup',
+    schema: Schema,
+    handler: async args => {
+      try {
+        const input = args.symbol ?? args.address ?? ''
+        if (!input) {
+          return { ok: false, error: 'provide one of `symbol` or `address`' }
+        }
+        if (isNativeToken(input)) {
+          return { ok: true, data: nativeTokenInfo() }
+        }
+        const token = await resolveToken({
+          client: ctx.publicClient,
+          agentDir: ctx.agentDir,
+          input,
+        })
+        if (!token) {
+          return { ok: false, error: `token not found: ${input}` }
+        }
+        return { ok: true, data: token }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/transfer.ts

@@ -0,0 +1,164 @@
+/**
+ * `chain.send` — native or ERC-20 transfer.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { getGasPriceWithFloor } from 'nebula-ai-core'
+import {
+  type Abi,
+  type Address,
+  type PublicClient,
+  getAddress,
+  isAddress,
+  parseEther,
+  parseUnits,
+} from 'viem'
+import { z } from 'zod'
+import { ERC20_ABI } from '../abis'
+import { evaluatePolicy } from '../policy'
+import { simulateContractWrite, simulateNativeSend } from '../simulate'
+import { isNativeToken, resolveToken } from '../tokens'
+import type { OnchainRuntimeContext } from '../types'
+import { waitForReceipt } from '../wait-receipt'
+
+const Schema = z.object({
+  to: z.string().min(1).describe('Recipient 0x address.'),
+  amount: z.string().min(1).describe('Amount in token units (e.g. "0.05" for 0.05 MNT).'),
+  token: z
+    .string()
+    .optional()
+    .describe('Symbol or 0x address. Omit / "MNT" / "native" for native transfer.'),
+})
+type Args = z.infer<typeof Schema>
+
+// Recipient resolution is 0x-only on Mantle. (Nebula does not depend on an
+// on-chain name service; pass a checksummed/lowercase 0x address.)
+export async function resolveRecipient(to: string, _publicClient: PublicClient): Promise<Address> {
+  const trimmed = to.trim()
+  if (isAddress(trimmed)) return getAddress(trimmed) as Address
+  throw new Error(`cannot resolve recipient "${trimmed}": expected a 0x address`)
+}
+
+export function makeChainSend(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'chain.send',
+    description:
+      'Transfer Mantle or any ERC-20 from your agent EOA. Pass `token` for ERC-20; omit for native Mantle. Auto-detects decimals via tokens.info.',
+    searchHint: 'send transfer 0g native erc20 pay',
+    schema: Schema,
+    handler: async args => {
+      try {
+        const recipient = await resolveRecipient(args.to, ctx.publicClient)
+        const account = ctx.walletClient.account
+        if (!account) {
+          return { ok: false, error: 'walletClient has no account; cannot send' }
+        }
+        const gasPrice = await getGasPriceWithFloor(ctx.publicClient)
+        if (isNativeToken(args.token)) {
+          const value = parseEther(args.amount)
+          // Policy gate (deterministic): block before simulate/execute.
+          if (ctx.policy) {
+            const verdict = evaluatePolicy(
+              { kind: 'transfer', asset: 'native', amountRaw: value, to: recipient },
+              ctx.policy,
+            )
+            if (!verdict.allowed) {
+              return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+            }
+          }
+          // Simulate-before-write: dry-run against the chain; abort if it would revert.
+          const sim = await simulateNativeSend(ctx.publicClient, {
+            account: account.address,
+            to: recipient,
+            value,
+          })
+          if (!sim.ok) {
+            return { ok: false, error: `pre-flight simulation reverted: ${sim.reason}` }
+          }
+          const txHash = await ctx.walletClient.sendTransaction({
+            to: recipient,
+            value,
+            chain: ctx.walletClient.chain,
+            account,
+            gasPrice,
+          })
+          const receipt = await waitForReceipt(ctx.publicClient, txHash)
+          return {
+            ok: true,
+            data: {
+              txHash,
+              blockNumber: Number(receipt.blockNumber),
+              gasUsed: receipt.gasUsed.toString(),
+              token: 'Mantle',
+              amount: args.amount,
+              recipient,
+              status: receipt.status === 'success' ? 'success' : 'reverted',
+              // Decision receipt: proof this write was policy-checked + simulated.
+              simGasEstimate: sim.gas.toString(),
+              policyEnforced: ctx.policy != null,
+            },
+          }
+        }
+        const token = await resolveToken({
+          client: ctx.publicClient,
+          agentDir: ctx.agentDir,
+          input: args.token!,
+        })
+        if (!token) {
+          return { ok: false, error: `unknown token: ${args.token}` }
+        }
+        const value = parseUnits(args.amount, token.decimals)
+        // Policy gate (deterministic): block before simulate/execute.
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            { kind: 'transfer', asset: token.address, amountRaw: value, to: recipient },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+        // Simulate-before-write: dry-run the ERC-20 transfer; abort if it would revert.
+        const sim = await simulateContractWrite(ctx.publicClient, {
+          account: account.address,
+          address: token.address,
+          abi: ERC20_ABI as Abi,
+          functionName: 'transfer',
+          args: [recipient, value],
+        })
+        if (!sim.ok) {
+          return { ok: false, error: `pre-flight simulation reverted: ${sim.reason}` }
+        }
+        const txHash = await ctx.walletClient.writeContract({
+          address: token.address,
+          abi: ERC20_ABI,
+          functionName: 'transfer',
+          args: [recipient, value],
+          chain: ctx.walletClient.chain,
+          account,
+          gasPrice,
+        })
+        const receipt = await waitForReceipt(ctx.publicClient, txHash)
+        return {
+          ok: true,
+          data: {
+            txHash,
+            blockNumber: Number(receipt.blockNumber),
+            gasUsed: receipt.gasUsed.toString(),
+            token: token.symbol,
+            tokenAddress: token.address,
+            amount: args.amount,
+            amountRaw: value.toString(),
+            recipient,
+            status: receipt.status === 'success' ? 'success' : 'reverted',
+            // Decision receipt: proof this write 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) }
+      }
+    },
+  }
+}