lyra-plugin-onchain 0.1.0

package/src/policy.ts

@@ -0,0 +1,267 @@
+/**
+ * Deterministic policy engine — Lyra's "verifiable autonomy" core.
+ *
+ * The project rule (CLAUDE.md): the AI is advisory; fund controls are enforced
+ * in deterministic code, NOT by the model. Every write is checked here BEFORE
+ * it is simulated/broadcast. The verdict is a pure function of (action, policy)
+ * — no network, no model — so it is fully unit-testable and auditable. This is
+ * the off-chain mirror of the on-chain `lyra::policy::AgentPolicy`: the same
+ * caps, coin/protocol allowlists, and expiry are enforced again in Move so a
+ * compromised agent still cannot exceed them.
+ *
+ * Order of the write pipeline: policy → simulate → (approval) → execute → receipt.
+ */
+
+/** 1 SUI = 10^9 MIST. */
+export const MIST_PER_SUI = 1_000_000_000n
+
+/** Canonical lowercased coin type for native SUI. */
+const SUI_CANON = '0x2::sui::sui'
+
+/**
+ * Normalize a coin type for comparison: lowercase, map the `native`/`sui`
+ * aliases to the canonical SUI type, and collapse a leading-zero-padded address
+ * (`0x000…02::sui::SUI`) to its short form (`0x2::sui::SUI`). The on-chain
+ * `type_name` form is fully padded; users write the short form — both compare
+ * equal here.
+ */
+export function normalizeCoinType(input: string): string {
+  let t = input.trim().toLowerCase()
+  if (t === 'native' || t === 'sui') return SUI_CANON
+  const sep = t.indexOf('::')
+  if (sep > 0 && t.startsWith('0x')) {
+    const addr = t.slice(2, sep).replace(/^0+/, '') || '0'
+    t = `0x${addr}${t.slice(sep)}`
+  }
+  return t
+}
+
+const lc = (a: string): string => a.trim().toLowerCase()
+
+export interface SuiPolicy {
+  /** Reject every write (read-only agent). */
+  readOnly?: boolean
+  /** Hard cap on MIST moved per action. */
+  maxMistPerTx?: bigint
+  /** MIST at/under which the `auto` tier executes without approval. */
+  autoMaxMistPerTx?: bigint
+  /** If set, only these coin types may be moved/swapped (normalized compare). */
+  coinAllowlist?: string[]
+  /**
+   * If set, only these protocols may be touched. Values are short ids
+   * (`transfer`, `deepbook`, `walrus`) or package addresses. Empty = any.
+   */
+  protocolAllowlist?: string[]
+  /** If set, transfers may only go to these recipient addresses. */
+  recipientAllowlist?: string[]
+  /** Max swap slippage tolerance, in basis points. */
+  maxSlippageBps?: number
+  /**
+   * Autonomy tier:
+   *  - 'auto'     execute within caps without asking
+   *  - 'confirm'  every write needs human approval
+   *  - 'readonly' alias for readOnly=true
+   * A spend above `autoMaxMistPerTx` always escalates to approval.
+   */
+  autonomy?: 'auto' | 'confirm' | 'readonly'
+  /** Absolute expiry (epoch ms). Past this, every write is blocked. */
+  expiryMs?: number
+}
+
+export interface SuiPolicyAction {
+  kind: 'transfer' | 'swap'
+  /** Coin type of the INPUT asset. `native` / `sui` accepted as aliases. */
+  coinType: string
+  /** Amount in MIST. */
+  amountMist: bigint
+  /** Recipient (transfers only). */
+  to?: string
+  /** Swap OUTPUT coin type — checked against the coin allowlist. */
+  toCoinType?: string
+  /** Protocol touched (`transfer`, `deepbook`, `walrus`, or a package id). */
+  protocol?: string
+  /** Swap slippage tolerance in bps. */
+  slippageBps?: number
+}
+
+export interface PolicyVerdict {
+  /** Hard policy violations — if non-empty the action is BLOCKED. */
+  violations: string[]
+  /** True when the action is permitted to proceed (no violations). */
+  allowed: boolean
+  /** True when a permitted action still needs human approval before execution. */
+  requiresApproval: boolean
+}
+
+/**
+ * Evaluate a proposed Sui action against the policy. Pure + deterministic.
+ * `nowMs` defaults to the wall clock but can be passed for deterministic tests.
+ */
+export function evaluatePolicy(
+  action: SuiPolicyAction,
+  policy: SuiPolicy,
+  nowMs: number = Date.now(),
+): PolicyVerdict {
+  const violations: string[] = []
+  const readOnly = policy.readOnly || policy.autonomy === 'readonly'
+  if (readOnly) violations.push('policy is read-only: all writes are blocked')
+
+  // Coin allowlist — checks the input asset AND, for swaps, the OUTPUT asset,
+  // otherwise the agent could swap an allowed coin INTO an arbitrary one.
+  if (policy.coinAllowlist?.length) {
+    const allowed = policy.coinAllowlist.map(normalizeCoinType)
+    if (!allowed.includes(normalizeCoinType(action.coinType))) {
+      violations.push(`coin ${action.coinType} is not in the coin allowlist`)
+    }
+    if (
+      action.kind === 'swap' &&
+      action.toCoinType !== undefined &&
+      !allowed.includes(normalizeCoinType(action.toCoinType))
+    ) {
+      violations.push(`swap output coin ${action.toCoinType} is not in the coin allowlist`)
+    }
+  }
+
+  // Protocol allowlist.
+  if (policy.protocolAllowlist?.length && action.protocol !== undefined) {
+    const allowed = policy.protocolAllowlist.map(lc)
+    if (!allowed.includes(lc(action.protocol))) {
+      violations.push(`protocol ${action.protocol} is not in the protocol allowlist`)
+    }
+  }
+
+  // Recipient allowlist (transfers).
+  if (policy.recipientAllowlist?.length && action.to) {
+    const allowed = policy.recipientAllowlist.map(lc)
+    if (!allowed.includes(lc(action.to))) {
+      violations.push(`recipient ${action.to} is not in the recipient allowlist`)
+    }
+  }
+
+  // Per-tx amount cap.
+  if (policy.maxMistPerTx !== undefined && action.amountMist > policy.maxMistPerTx) {
+    violations.push(
+      `amount ${action.amountMist} MIST exceeds per-tx cap ${policy.maxMistPerTx} MIST`,
+    )
+  }
+
+  // Slippage cap (swaps).
+  if (
+    action.slippageBps !== undefined &&
+    policy.maxSlippageBps !== undefined &&
+    action.slippageBps > policy.maxSlippageBps
+  ) {
+    violations.push(`slippage ${action.slippageBps} bps exceeds max ${policy.maxSlippageBps} bps`)
+  }
+
+  // Expiry.
+  if (policy.expiryMs !== undefined && nowMs > policy.expiryMs) {
+    violations.push(`policy expired at ${new Date(policy.expiryMs).toISOString()}`)
+  }
+
+  const allowed = violations.length === 0
+
+  // Approval gate: 'confirm' tier always needs approval; 'auto' escalates only
+  // when the spend is above the auto ceiling (material risk).
+  let requiresApproval = false
+  if (allowed) {
+    if (policy.autonomy === 'confirm') {
+      requiresApproval = true
+    } else if (
+      policy.autoMaxMistPerTx !== undefined &&
+      action.amountMist > policy.autoMaxMistPerTx
+    ) {
+      requiresApproval = true
+    }
+  }
+
+  return { violations, allowed, requiresApproval }
+}
+
+/** Parse a decimal SUI string to MIST. Returns undefined for invalid input. */
+export function suiToMist(sui?: string): bigint | undefined {
+  if (sui === undefined || sui === '') return undefined
+  const n = Number(sui)
+  if (!Number.isFinite(n) || n < 0) return undefined
+  // Round to whole MIST to avoid float drift for typical 1–9 decimal inputs.
+  return BigInt(Math.round(n * 1e9))
+}
+
+const list = (s?: string): string[] | undefined =>
+  s
+    ? s
+        .split(',')
+        .map(x => x.trim())
+        .filter(Boolean)
+    : undefined
+
+/**
+ * Build a policy from environment variables (operator opt-in). Returns
+ * undefined when no policy env is set. `nowMs` seeds the relative expiry.
+ *   LYRA_POLICY_READONLY=1
+ *   LYRA_POLICY_MAX_PER_TX_SUI=1.0
+ *   LYRA_POLICY_AUTO_MAX_SUI=0.1
+ *   LYRA_POLICY_MAX_SLIPPAGE_BPS=100
+ *   LYRA_POLICY_AUTONOMY=auto|confirm|readonly
+ *   LYRA_POLICY_ALLOWED_PROTOCOLS=transfer,deepbook,walrus
+ *   LYRA_POLICY_ALLOWED_COINS=0x2::sui::SUI
+ *   LYRA_POLICY_RECIPIENT_ALLOWLIST=0xabc...,0xdef...
+ *   LYRA_POLICY_EXPIRY_MINUTES=60
+ */
+export function policyFromEnv(
+  env: Record<string, string | undefined> = process.env,
+  nowMs: number = Date.now(),
+): SuiPolicy | undefined {
+  const policy: SuiPolicy = {}
+  let any = false
+
+  if (env.LYRA_POLICY_READONLY === '1') {
+    policy.readOnly = true
+    any = true
+  }
+  const maxPerTx = suiToMist(env.LYRA_POLICY_MAX_PER_TX_SUI)
+  if (maxPerTx !== undefined) {
+    policy.maxMistPerTx = maxPerTx
+    any = true
+  }
+  const autoMax = suiToMist(env.LYRA_POLICY_AUTO_MAX_SUI)
+  if (autoMax !== undefined) {
+    policy.autoMaxMistPerTx = autoMax
+    any = true
+  }
+  if (env.LYRA_POLICY_MAX_SLIPPAGE_BPS) {
+    const bps = Number(env.LYRA_POLICY_MAX_SLIPPAGE_BPS)
+    if (Number.isFinite(bps) && bps >= 0) {
+      policy.maxSlippageBps = bps
+      any = true
+    }
+  }
+  const autonomy = env.LYRA_POLICY_AUTONOMY
+  if (autonomy === 'auto' || autonomy === 'confirm' || autonomy === 'readonly') {
+    policy.autonomy = autonomy
+    any = true
+  }
+  const protocols = list(env.LYRA_POLICY_ALLOWED_PROTOCOLS)
+  if (protocols) {
+    policy.protocolAllowlist = protocols
+    any = true
+  }
+  const coins = list(env.LYRA_POLICY_ALLOWED_COINS)
+  if (coins) {
+    policy.coinAllowlist = coins
+    any = true
+  }
+  const recipients = list(env.LYRA_POLICY_RECIPIENT_ALLOWLIST)
+  if (recipients) {
+    policy.recipientAllowlist = recipients
+    any = true
+  }
+  if (env.LYRA_POLICY_EXPIRY_MINUTES) {
+    const mins = Number(env.LYRA_POLICY_EXPIRY_MINUTES)
+    if (Number.isFinite(mins) && mins > 0) {
+      policy.expiryMs = nowMs + mins * 60_000
+      any = true
+    }
+  }
+  return any ? policy : undefined
+}

package/src/protocols.ts

@@ -0,0 +1,109 @@
+/**
+ * Protocol capability registry — Lyra's honest map of what it can DO vs only SEE.
+ *
+ * Discovery is broad (DefiLlama indexes every Sui protocol), but execution is
+ * bounded to vetted adapters and the policy's protocol-allowlist. This registry
+ * is the single source of truth for that boundary, so when a user finds a great
+ * yield on a protocol Lyra has not integrated, Lyra says so honestly and offers
+ * what it CAN do — it never fabricates a transaction for a protocol it cannot
+ * actually reach.
+ */
+
+export type ProtocolCategory = 'clob' | 'dex' | 'aggregator' | 'lending' | 'staking' | 'storage'
+
+export interface ProtocolCapability {
+  id: string
+  name: string
+  category: ProtocolCategory
+  /** Can Lyra read live data here (markets, prices, positions)? */
+  read: boolean
+  /** Can Lyra execute a state-changing action here (through the policy pipeline)? */
+  execute: boolean
+  /** Tool names that touch this protocol. */
+  tools: string[]
+  /** DefiLlama `project` slugs that map to this adapter (for executability tagging). */
+  llamaProjects?: string[]
+  note?: string
+}
+
+export const PROTOCOLS: ProtocolCapability[] = [
+  {
+    id: 'walrus',
+    name: 'Walrus',
+    category: 'storage',
+    read: false,
+    execute: true,
+    tools: ['walrus.store'],
+  },
+  {
+    id: 'deepbook',
+    name: 'DeepBook',
+    category: 'clob',
+    read: true,
+    execute: false,
+    tools: ['deepbook.markets'],
+    llamaProjects: ['deepbook'],
+    note: 'market data read; on-chain order execution not wired yet',
+  },
+  {
+    id: 'scallop',
+    name: 'Scallop',
+    category: 'lending',
+    read: true,
+    execute: true,
+    tools: ['scallop.markets', 'scallop.position', 'scallop.supply', 'scallop.withdraw'],
+    llamaProjects: ['scallop-lending', 'scallop'],
+  },
+  {
+    id: 'navi',
+    name: 'NAVI',
+    category: 'lending',
+    read: true,
+    execute: true,
+    tools: ['navi.markets', 'navi.position', 'navi.supply', 'navi.withdraw'],
+    llamaProjects: ['navi-lending', 'navi-protocol', 'navi'],
+    note: 'largest Sui lending market by TVL',
+  },
+  {
+    id: 'aggregator',
+    name: 'DEX aggregator (7k / Cetus / FlowX / Bluefin)',
+    category: 'aggregator',
+    read: true,
+    execute: true,
+    tools: ['swap', 'cetus.quote'],
+    llamaProjects: [
+      'cetus-amm',
+      'cetus-clmm',
+      'cetus',
+      'flowx-finance',
+      'flowx-v3',
+      'bluefin-spot',
+      'bluefin',
+      'turbos',
+      'kriya-dex',
+    ],
+    note: 'swap executes via the 7k aggregator, routing across Cetus/FlowX/Bluefin/DeepBook',
+  },
+]
+
+const PROJECT_INDEX: Record<string, ProtocolCapability> = (() => {
+  const idx: Record<string, ProtocolCapability> = {}
+  for (const p of PROTOCOLS) for (const slug of p.llamaProjects ?? []) idx[slug] = p
+  return idx
+})()
+
+/** Map a DefiLlama `project` slug to an integrated adapter, if any. */
+export function adapterForProject(project: string): ProtocolCapability | null {
+  const key = project.trim().toLowerCase()
+  if (PROJECT_INDEX[key]) return PROJECT_INDEX[key]
+  // Loose contains-match: e.g. "scallop-lending" / "navi-lending".
+  for (const p of PROTOCOLS) {
+    if ((p.llamaProjects ?? []).some(s => key.includes(s) || s.includes(key))) return p
+  }
+  return null
+}
+
+/** Protocols Lyra can actually execute a state-changing action on. */
+export function executableProtocols(): ProtocolCapability[] {
+  return PROTOCOLS.filter(p => p.execute)
+}

package/src/simulate.ts

@@ -0,0 +1,60 @@
+/**
+ * Simulate-before-write guard.
+ *
+ * Lyra's core safety rule (project thesis): every state-changing transaction is
+ * dry-run against the live chain BEFORE it is broadcast, so Move aborts and
+ * insufficient-funds are caught pre-flight and surfaced to the operator instead
+ * of burning gas on a doomed tx. Read-only — no transaction is sent here.
+ */
+
+import type { SuiClient } from '@mysten/sui/client'
+import type { Transaction } from '@mysten/sui/transactions'
+
+export interface SimOk {
+  ok: true
+  /** Net gas the (validated) transaction would cost, in MIST. */
+  gasUsed: string
+}
+export interface SimFail {
+  ok: false
+  /** Decoded Move abort / node error (truncated). */
+  reason: string
+}
+export type SimResult = SimOk | SimFail
+
+/** Net gas = computation + storage − rebate, as a MIST string. */
+function netGas(gas: {
+  computationCost: string
+  storageCost: string
+  storageRebate: string
+}): string {
+  return (
+    BigInt(gas.computationCost) +
+    BigInt(gas.storageCost) -
+    BigInt(gas.storageRebate)
+  ).toString()
+}
+
+/**
+ * Dry-run a PTB. `dryRunTransactionBlock` executes the block at the node
+ * (no broadcast), so Move aborts, type errors, and funding shortfalls surface
+ * here. Returns the decoded failure reason or the net gas estimate.
+ */
+export async function simulate(
+  client: SuiClient,
+  tx: Transaction,
+  sender: string,
+): Promise<SimResult> {
+  try {
+    tx.setSenderIfNotSet(sender)
+    const bytes = await tx.build({ client })
+    const res = await client.dryRunTransactionBlock({ transactionBlock: bytes })
+    const status = res.effects.status
+    if (status.status !== 'success') {
+      return { ok: false, reason: status.error ?? 'transaction would fail' }
+    }
+    return { ok: true, gasUsed: netGas(res.effects.gasUsed) }
+  } catch (e) {
+    return { ok: false, reason: (e as Error).message?.slice(0, 240) ?? 'unknown simulation error' }
+  }
+}

package/src/tools/balance.ts

@@ -0,0 +1,81 @@
+/**
+ * Read-only account tools: `sui.balance` and `account.info`.
+ */
+
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+const SUI_TYPE = '0x2::sui::SUI'
+
+/** Format a MIST amount as a human SUI string. */
+export function fmtSui(mist: string | bigint): string {
+  return (Number(BigInt(mist)) / 1e9).toLocaleString('en-US', { maximumFractionDigits: 6 })
+}
+
+const BalanceSchema = z.object({
+  address: z.string().optional().describe('Address to check. Defaults to the agent address.'),
+})
+type BalanceArgs = z.infer<typeof BalanceSchema>
+
+export function makeSuiBalance(ctx: OnchainRuntimeContext): ToolDef<BalanceArgs> {
+  return {
+    name: 'sui.balance',
+    description:
+      "Show SUI and other coin balances for the agent (or a given address). Read-only. Use for 'what's my balance', 'how much SUI do I have'.",
+    searchHint: 'balance sui holdings funds wallet how much do i have coins',
+    schema: BalanceSchema,
+    handler: async args => {
+      try {
+        const owner = args.address?.trim() || ctx.agentAddress
+        const sui = await ctx.client.getBalance({ owner, coinType: SUI_TYPE })
+        const all = await ctx.client.getAllBalances({ owner })
+        return {
+          ok: true,
+          data: {
+            address: owner,
+            network: ctx.network,
+            sui: { mist: sui.totalBalance, formatted: `${fmtSui(sui.totalBalance)} SUI` },
+            coins: all
+              .filter(b => b.coinType !== SUI_TYPE && BigInt(b.totalBalance) > 0n)
+              .map(b => ({ coinType: b.coinType, balance: b.totalBalance })),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+const InfoSchema = z.object({})
+type InfoArgs = z.infer<typeof InfoSchema>
+
+export function makeAccountInfo(ctx: OnchainRuntimeContext): ToolDef<InfoArgs> {
+  return {
+    name: 'account.info',
+    description:
+      "The agent's on-chain identity: Sui address, network, SUI balance, the lyra::policy package + policy object in force, and whether a deterministic policy is armed. Read-only.",
+    searchHint: 'account identity who am i address agent network policy package',
+    schema: InfoSchema,
+    handler: async () => {
+      try {
+        const sui = await ctx.client.getBalance({ owner: ctx.agentAddress, coinType: SUI_TYPE })
+        return {
+          ok: true,
+          data: {
+            agentAddress: ctx.agentAddress,
+            network: ctx.network,
+            sui: `${fmtSui(sui.totalBalance)} SUI`,
+            policyPackage: ctx.packageId ?? null,
+            policyObject: ctx.policyObjectId ?? null,
+            policyArmed: ctx.policy != null,
+            brainModel: ctx.brainModel ?? null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/cetus.ts

@@ -0,0 +1,93 @@
+/**
+ * `cetus.quote` — best-execution price discovery across Cetus (Sui's largest
+ * DEX) via the Cetus aggregator. Read-only: it finds the best route and output
+ * for a swap so the agent can compare venues (e.g. vs DeepBook) before acting.
+ *
+ * Note: on-chain swap execution is intentionally NOT wired here. The Cetus
+ * aggregator SDK builds transactions with @mysten/sui v2, which is incompatible
+ * with this stack's v1 policy → simulate → execute pipeline. Quoting uses the
+ * aggregator's router with our v1 client; executing a Cetus swap would require
+ * migrating the whole stack to SDK v2.
+ */
+
+import { AggregatorClient } from '@cetusprotocol/aggregator-sdk'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+/** Symbol → mainnet coin type + decimals for the common assets. */
+const COINS: Record<string, { type: string; decimals: number }> = {
+  sui: { type: '0x2::sui::SUI', decimals: 9 },
+  usdc: {
+    type: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+    decimals: 6,
+  },
+  deep: {
+    type: '0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP',
+    decimals: 6,
+  },
+  wal: {
+    type: '0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL',
+    decimals: 9,
+  },
+}
+
+function resolve(input: string): { type: string; decimals: number } {
+  const k = input.trim().toLowerCase()
+  if (COINS[k]) return COINS[k]
+  return { type: input.trim(), decimals: 9 }
+}
+
+const Schema = z.object({
+  from: z.string().min(1).describe('Input coin: symbol (sui, usdc, deep, wal) or full coin type.'),
+  to: z.string().min(1).describe('Output coin: symbol or full coin type.'),
+  amount: z.string().min(1).describe('Input amount in whole units of `from`, e.g. "1.5".'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeCetusQuote(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'cetus.quote',
+    description:
+      'Quote the best Cetus swap route on Sui (read-only): input → output amount and implied price across Cetus pools. Use to compare execution venues before proposing a swap. Does not execute.',
+    searchHint: 'cetus swap quote price route dex best execution exchange convert',
+    schema: Schema,
+    handler: async args => {
+      if (ctx.network !== 'mainnet')
+        return { ok: false, error: 'Cetus aggregator supports mainnet only' }
+      try {
+        const from = resolve(args.from)
+        const to = resolve(args.to)
+        const amountIn = BigInt(Math.round(Number(args.amount) * 10 ** from.decimals))
+        if (amountIn <= 0n) return { ok: false, error: `invalid amount "${args.amount}"` }
+
+        // The aggregator accepts our v1 client for read-only routing.
+        const agg = new AggregatorClient({ signer: ctx.agentAddress, client: ctx.client as never })
+        const route = await agg.findRouters({
+          from: from.type,
+          target: to.type,
+          amount: amountIn,
+          byAmountIn: true,
+        })
+        if (!route || route.amountOut == null) return { ok: false, error: 'no Cetus route found' }
+
+        const out = BigInt(route.amountOut.toString())
+        const price = Number(out) / 10 ** to.decimals / (Number(amountIn) / 10 ** from.decimals)
+        return {
+          ok: true,
+          data: {
+            venue: 'cetus',
+            from: args.from,
+            to: args.to,
+            amountIn: args.amount,
+            amountOut: (Number(out) / 10 ** to.decimals).toString(),
+            price: `${price.toPrecision(6)} ${args.to}/${args.from}`,
+            note: 'read-only quote; Cetus swap execution not wired (SDK v2 vs stack v1)',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/deepbook.ts

@@ -0,0 +1,60 @@
+/**
+ * `deepbook.markets` — read DeepBook spot market data on Sui (mid prices for the
+ * core pools). Read-only discovery; never moves funds.
+ */
+
+import { DeepBookClient } from '@mysten/deepbook-v3'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+/** Core mainnet pool keys shipped with the DeepBook SDK config. */
+const DEFAULT_POOLS = ['SUI_USDC', 'DEEP_USDC', 'DEEP_SUI', 'WAL_USDC', 'WAL_SUI']
+
+const Schema = z.object({
+  pools: z
+    .string()
+    .optional()
+    .describe('Comma-separated pool keys (e.g. "SUI_USDC,DEEP_USDC"). Omit for the core set.'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeDeepbookMarkets(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'deepbook.markets',
+    description:
+      'Read DeepBook spot market data on Sui: mid price for the core pools (SUI/USDC, DEEP/USDC, WAL/USDC, ...). Read-only market context for execution.',
+    searchHint: 'deepbook market price pool spot orderbook mid quote sui usdc liquidity',
+    schema: Schema,
+    handler: async args => {
+      try {
+        const db = new DeepBookClient({
+          // cast: @mysten/deepbook-v3 bundles a different @mysten/sui minor; the
+          // client is runtime-compatible (verified live) but not type-identical.
+          client: ctx.client as never,
+          address: ctx.agentAddress,
+          env: ctx.network,
+        })
+        const keys = args.pools
+          ? args.pools
+              .split(',')
+              .map(s => s.trim())
+              .filter(Boolean)
+          : DEFAULT_POOLS
+        const markets = await Promise.all(
+          keys.map(async pool => {
+            try {
+              const mid = await db.midPrice(pool)
+              return { pool, midPrice: mid }
+            } catch (e) {
+              return { pool, error: (e as Error).message.slice(0, 120) }
+            }
+          }),
+        )
+        return { ok: true, data: { network: ctx.network, markets } }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}