lyra-plugin-onchain 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lyra-plugin-onchain",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "description": "The Sui on-chain tools for Lyra: SUI transfers, DeepBook market data, Walrus receipts/memory — every write policy-checked, simulated, and recorded on-chain via lyra::policy",
   "license": "MIT",
@@ -13,28 +13,14 @@
   "bugs": {
     "url": "https://github.com/rifkyeasy/lyra/issues"
   },
-  "keywords": [
-    "lyra",
-    "ai",
-    "agent",
-    "sui",
-    "defi",
-    "deepbook",
-    "walrus",
-    "policy",
-    "plugin"
-  ],
+  "keywords": ["lyra", "ai", "agent", "sui", "defi", "deepbook", "walrus", "policy", "plugin"],
   "publishConfig": {
     "access": "public"
   },
   "engines": {
     "bun": ">=1.1"
   },
-  "files": [
-    "src",
-    "!src/**/*.test.ts",
-    "README.md"
-  ],
+  "files": ["src", "!src/**/*.test.ts", "README.md"],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
@@ -47,7 +33,10 @@
     "@mysten/deepbook-v3": "^0.18.0",
     "@mysten/sui": "^1.40.0",
     "@mysten/walrus": "^0.6.4",
+    "@pythnetwork/pyth-sui-js": "2.2.0",
     "@scallop-io/sui-scallop-sdk": "^2.4.5",
+    "@suilend/sdk": "1.1.99",
+    "@suilend/sui-fe": "0.3.49",
     "lyra-core": "^0.1.2",
     "navi-sdk": "^1.7.3",
     "zod": "^3.23.8"

package/src/client.ts

@@ -11,14 +11,23 @@ import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
 
 export type SuiNetwork = 'testnet' | 'mainnet'
 
-/** Canonical fullnode JSON-RPC URL for a network. */
+/**
+ * Fullnode JSON-RPC URL for a network. `LYRA_RPC_URL` overrides the default
+ * public endpoint — recommended in production: the public `fullnode.mainnet.
+ * sui.io` is load-balanced across replicas at different checkpoint heights, so
+ * a freshly-created object (e.g. a just-opened lending obligation) can flicker
+ * in and out between calls. A single dedicated node gives read-your-writes
+ * consistency. The override applies to mainnet only (testnet keeps its default).
+ */
 export function suiRpcUrl(network: SuiNetwork): string {
+  const override = process.env.LYRA_RPC_URL?.trim()
+  if (network === 'mainnet' && override) return override
   return getFullnodeUrl(network)
 }
 
-/** A Sui JSON-RPC client for the given network. */
+/** A Sui JSON-RPC client for the given network (honours `LYRA_RPC_URL`). */
 export function makeSuiClient(network: SuiNetwork): SuiClient {
-  return new SuiClient({ url: getFullnodeUrl(network) })
+  return new SuiClient({ url: suiRpcUrl(network) })
 }
 
 /**

package/src/index.ts

@@ -25,6 +25,7 @@ import { makeAccountInfo, makeSuiBalance } from './tools/balance'
 import { makeCetusQuote } from './tools/cetus'
 import { makeDeepbookMarkets } from './tools/deepbook'
 import { makeDefiYields } from './tools/defillama'
+import { makeVoloStake, makeVoloUnstake } from './tools/liquid-stake'
 import {
   makeNaviBorrow,
   makeNaviMarkets,
@@ -43,6 +44,13 @@ import {
 } from './tools/scallop'
 import { makeSuiSend } from './tools/send'
 import { makeStake, makeUnstake } from './tools/stake'
+import {
+  makeSuilendBorrow,
+  makeSuilendPosition,
+  makeSuilendRepay,
+  makeSuilendSupply,
+  makeSuilendWithdraw,
+} from './tools/suilend'
 import { makeSwap } from './tools/swap'
 import { makeWalrusStore } from './tools/walrus'
 import type { OnchainRuntimeContext } from './types'
@@ -101,10 +109,17 @@ const plugin: NativePlugin = {
     ctx.registerTool(makeNaviWithdraw(onchain) as ToolDef)
     ctx.registerTool(makeNaviBorrow(onchain) as ToolDef)
     ctx.registerTool(makeNaviRepay(onchain) as ToolDef)
+    ctx.registerTool(makeSuilendSupply(onchain) as ToolDef)
+    ctx.registerTool(makeSuilendWithdraw(onchain) as ToolDef)
+    ctx.registerTool(makeSuilendBorrow(onchain) as ToolDef)
+    ctx.registerTool(makeSuilendRepay(onchain) as ToolDef)
+    ctx.registerTool(makeSuilendPosition(onchain) as ToolDef)
 
-    // Native staking (delegate SUI to a validator; min 1 SUI).
+    // Staking: native delegation (min 1 SUI) + Volo liquid staking (vSUI).
     ctx.registerTool(makeStake(onchain) as ToolDef)
     ctx.registerTool(makeUnstake(onchain) as ToolDef)
+    ctx.registerTool(makeVoloStake(onchain) as ToolDef)
+    ctx.registerTool(makeVoloUnstake(onchain) as ToolDef)
   },
 }
 

package/src/protocols.ts

@@ -43,7 +43,7 @@ export const PROTOCOLS: ProtocolCapability[] = [
     execute: false,
     tools: ['deepbook.markets'],
     llamaProjects: ['deepbook'],
-    note: 'market data read; on-chain order execution not wired yet',
+    note: 'market data read; swaps route through DeepBook via the 7k aggregator',
   },
   {
     id: 'scallop',
@@ -53,6 +53,7 @@ export const PROTOCOLS: ProtocolCapability[] = [
     execute: true,
     tools: ['scallop.markets', 'scallop.position', 'scallop.supply', 'scallop.withdraw'],
     llamaProjects: ['scallop-lending', 'scallop'],
+    note: 'supply / withdraw lending yield (borrow/repay via NAVI or Suilend)',
   },
   {
     id: 'navi',
@@ -60,13 +61,55 @@ export const PROTOCOLS: ProtocolCapability[] = [
     category: 'lending',
     read: true,
     execute: true,
-    tools: ['navi.markets', 'navi.position', 'navi.supply', 'navi.withdraw'],
+    tools: [
+      'navi.markets',
+      'navi.position',
+      'navi.supply',
+      'navi.withdraw',
+      'navi.borrow',
+      'navi.repay',
+    ],
     llamaProjects: ['navi-lending', 'navi-protocol', 'navi'],
-    note: 'largest Sui lending market by TVL',
+    note: 'largest Sui lending market by TVL; full supply / withdraw / borrow / repay',
+  },
+  {
+    id: 'suilend',
+    name: 'Suilend',
+    category: 'lending',
+    read: true,
+    execute: true,
+    tools: [
+      'suilend.position',
+      'suilend.supply',
+      'suilend.withdraw',
+      'suilend.borrow',
+      'suilend.repay',
+    ],
+    llamaProjects: ['suilend'],
+    note: 'MAIN_POOL market; full supply / withdraw / borrow / repay',
+  },
+  {
+    id: 'native-staking',
+    name: 'Sui Native Staking',
+    category: 'staking',
+    read: false,
+    execute: true,
+    tools: ['sui.stake', 'sui.unstake'],
+    note: 'delegate SUI to a validator (min 1 SUI); classic staking rewards',
+  },
+  {
+    id: 'volo',
+    name: 'Volo (Liquid Staking)',
+    category: 'staking',
+    read: false,
+    execute: true,
+    tools: ['volo.stake', 'volo.unstake'],
+    llamaProjects: ['volo', 'volo-staked-sui'],
+    note: 'stake SUI → vSUI, a liquid staking token usable across DeFi while earning',
   },
   {
     id: 'aggregator',
-    name: 'DEX aggregator (7k / Cetus / FlowX / Bluefin)',
+    name: 'DEX aggregator (7k best-route)',
     category: 'aggregator',
     read: true,
     execute: true,
@@ -81,8 +124,12 @@ export const PROTOCOLS: ProtocolCapability[] = [
       'bluefin',
       'turbos',
       'kriya-dex',
+      'aftermath-amm',
+      'aftermath',
+      'momentum',
+      'mmt',
     ],
-    note: 'swap executes via the 7k aggregator, routing across Cetus/FlowX/Bluefin/DeepBook',
+    note: 'swap executes via the 7k aggregator, routing best price across Cetus / Turbos / FlowX / Bluefin / Aftermath / Momentum / Kriya / DeepBook',
   },
 ]
 

package/src/tools/liquid-stake.ts

@@ -0,0 +1,152 @@
+/**
+ * Volo liquid staking — stake SUI for vSUI (a liquid staking token that keeps
+ * earning while remaining tradeable / usable in DeFi), and unstake vSUI back to
+ * SUI. Built on navi-sdk's Volo PTB helpers.
+ *
+ *   volo.stake   → SUI → vSUI  (stake_pool::stake)
+ *   volo.unstake → vSUI → SUI  (stake_pool::unstake)
+ *
+ * Same guarded pipeline: minimum guard → policy → dry-run simulate → execute →
+ * on-chain effects check.
+ */
+
+import { Transaction, coinWithBalance } from '@mysten/sui/transactions'
+import type { ToolDef } from 'lyra-core'
+import { stakeTovSuiPTB, unstakeTovSui } from 'navi-sdk'
+import { z } from 'zod'
+import { checkMinimum } from '../minimums'
+import { evaluatePolicy, suiToMist } from '../policy'
+import { simulate } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+
+const SUI_TYPE = '0x2::sui::SUI'
+const VSUI_TYPE = '0x549e8b69270defbfafd4f94e17ec44cdbdd99820b33bda2278dea3b9a32d3f55::cert::CERT'
+
+const StakeSchema = z.object({
+  amount: z.string().min(1).describe('Amount of SUI to liquid-stake (minimum 1 SUI).'),
+})
+type StakeArgs = z.infer<typeof StakeSchema>
+
+const UnstakeSchema = z.object({
+  amount: z.string().min(1).describe('Amount of vSUI to unstake back to SUI.'),
+})
+type UnstakeArgs = z.infer<typeof UnstakeSchema>
+
+export function makeVoloStake(ctx: OnchainRuntimeContext): ToolDef<StakeArgs> {
+  return {
+    name: 'volo.stake',
+    description:
+      'Liquid-stake SUI with Volo and receive vSUI — a liquid staking token that keeps earning staking rewards while remaining tradeable and usable across Sui DeFi (unlike native staking, which locks the position). Minimum 1 SUI. Policy-checked, simulated, then executed.',
+    searchHint:
+      'volo liquid stake vsui lst liquid-staking derivative earn yield tradeable sui defi',
+    schema: StakeSchema,
+    handler: async args => {
+      try {
+        if (ctx.network !== 'mainnet') return { ok: false, error: 'Volo supports mainnet only' }
+        const amountMist = suiToMist(args.amount)
+        if (amountMist === undefined || amountMist <= 0n) {
+          return { ok: false, error: `invalid amount "${args.amount}"` }
+        }
+        const tooSmall = checkMinimum('stake', amountMist)
+        if (tooSmall) return { ok: false, error: tooSmall }
+
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'stake' },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+
+        const tx = new Transaction()
+        const [suiCoin] = tx.splitCoins(tx.gas, [amountMist])
+        const vsui = await stakeTovSuiPTB(tx as never, suiCoin as never)
+        tx.transferObjects([vsui as never], ctx.agentAddress)
+
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true },
+        })
+        if (res.effects?.status?.status !== 'success') {
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        }
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        return {
+          ok: true,
+          data: {
+            protocol: 'volo',
+            action: 'liquid-stake',
+            amountSui: args.amount,
+            received: 'vSUI',
+            digest: res.digest,
+            status: 'success',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+export function makeVoloUnstake(ctx: OnchainRuntimeContext): ToolDef<UnstakeArgs> {
+  return {
+    name: 'volo.unstake',
+    description:
+      'Unstake vSUI back to SUI via Volo (returns SUI including accrued staking rewards). The amount is denominated in vSUI. Simulated, then executed.',
+    searchHint: 'volo unstake vsui redeem convert back sui liquid staking withdraw',
+    schema: UnstakeSchema,
+    handler: async args => {
+      try {
+        if (ctx.network !== 'mainnet') return { ok: false, error: 'Volo supports mainnet only' }
+        const amountMist = suiToMist(args.amount)
+        if (amountMist === undefined || amountMist <= 0n) {
+          return { ok: false, error: `invalid amount "${args.amount}"` }
+        }
+
+        const tx = new Transaction()
+        // coinWithBalance resolves the agent's vSUI coins into one of the exact size.
+        const vsuiCoin = coinWithBalance({ type: VSUI_TYPE, balance: amountMist })
+        const sui = await unstakeTovSui(tx as never, vsuiCoin as never)
+        tx.transferObjects([sui as never], ctx.agentAddress)
+
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true },
+        })
+        if (res.effects?.status?.status !== 'success') {
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        }
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        return {
+          ok: true,
+          data: {
+            protocol: 'volo',
+            action: 'unstake',
+            amountVsui: args.amount,
+            digest: res.digest,
+            status: 'success',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/navi.ts

@@ -126,7 +126,12 @@ async function runNaviWrite(
   // repay/supply move SUI out). Withdraw pulls the agent's own funds back.
   if (ctx.policy && kind !== 'withdraw') {
     const verdict = evaluatePolicy(
-      { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: kind === 'borrow' ? 'borrow' : 'navi' },
+      {
+        kind: 'transfer',
+        coinType: SUI_TYPE,
+        amountMist,
+        protocol: kind === 'borrow' ? 'borrow' : 'navi',
+      },
       ctx.policy,
     )
     if (!verdict.allowed)

package/src/tools/onchain.integration.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Integration coverage — LIVE mainnet dry-runs (devInspect, never broadcast).
+ *
+ * Gated: runs only when `LYRA_RUN_INTEGRATION=1` and a real `LYRA_AGENT_KEY` is
+ * present. In CI (no secret) the whole suite is skipped, so it never flakes the
+ * default `bun test`. Run locally with:
+ *
+ *   LYRA_RUN_INTEGRATION=1 bun test src/tools/onchain.integration.test.ts
+ *
+ * Each write case builds the exact PTB its tool builds and simulates it against
+ * mainnet, proving the SDK integration + PTB are valid on-chain without moving
+ * funds. Read-only tools are invoked directly (safe).
+ */
+
+import { describe, expect, test } from 'bun:test'
+import { Transaction } from '@mysten/sui/transactions'
+import { LENDING_MARKET_ID, LENDING_MARKET_TYPE, SuilendClient } from '@suilend/sdk'
+import { stakeTovSuiPTB } from 'navi-sdk'
+import { keypairFromSecret, makeSuiClient } from '../client'
+import type { OnchainRuntimeContext } from '../types'
+import { makeScallopMarkets } from './scallop'
+import { makeSuilendPosition } from './suilend'
+
+const SUI = '0x2::sui::SUI'
+const RUN = process.env.LYRA_RUN_INTEGRATION === '1' && !!process.env.LYRA_AGENT_KEY
+const ONE_SUI = 1_000_000_000n
+
+function realCtx(): OnchainRuntimeContext {
+  const client = makeSuiClient('mainnet')
+  const keypair = keypairFromSecret(process.env.LYRA_AGENT_KEY as string)
+  return {
+    client,
+    keypair,
+    agentAddress: keypair.getPublicKey().toSuiAddress(),
+    network: 'mainnet',
+    agentDir: '/tmp/lyra-integration',
+  }
+}
+
+async function simStatus(ctx: OnchainRuntimeContext, tx: Transaction): Promise<string | undefined> {
+  const r = await ctx.client.devInspectTransactionBlock({
+    sender: ctx.agentAddress,
+    transactionBlock: tx as never,
+  })
+  return r.effects?.status?.status
+}
+
+describe.skipIf(!RUN)('mainnet dry-run integration', () => {
+  test('native stake (1 SUI → validator) simulates success', async () => {
+    const ctx = realCtx()
+    const state = await ctx.client.getLatestSuiSystemState()
+    const validator = state.activeValidators
+      .slice()
+      .sort((a, b) => Number(b.votingPower) - Number(a.votingPower))[0]
+    if (!validator) throw new Error('no active validators')
+    const tx = new Transaction()
+    tx.setSender(ctx.agentAddress)
+    const [coin] = tx.splitCoins(tx.gas, [ONE_SUI])
+    tx.moveCall({
+      target: '0x3::sui_system::request_add_stake',
+      arguments: [tx.object('0x5'), coin, tx.pure.address(validator.suiAddress)],
+    })
+    expect(await simStatus(ctx, tx)).toBe('success')
+  }, 45_000)
+
+  test('Volo liquid stake (1 SUI → vSUI) simulates success', async () => {
+    const ctx = realCtx()
+    const tx = new Transaction()
+    tx.setSender(ctx.agentAddress)
+    const [coin] = tx.splitCoins(tx.gas, [ONE_SUI])
+    const vsui = await stakeTovSuiPTB(tx as never, coin as never)
+    tx.transferObjects([vsui as never], ctx.agentAddress)
+    expect(await simStatus(ctx, tx)).toBe('success')
+  }, 45_000)
+
+  test('Suilend supply (1 SUI) simulates success', async () => {
+    const ctx = realCtx()
+    const suilend = await SuilendClient.initialize(
+      LENDING_MARKET_ID,
+      LENDING_MARKET_TYPE,
+      ctx.client as never,
+    )
+    const caps = await SuilendClient.getObligationOwnerCaps(
+      ctx.agentAddress,
+      [LENDING_MARKET_TYPE],
+      ctx.client as never,
+    )
+    const tx = new Transaction()
+    tx.setSender(ctx.agentAddress)
+    const [coin] = tx.splitCoins(tx.gas, [ONE_SUI])
+    if (caps.length === 0) {
+      const cap = suilend.createObligation(tx as never)
+      suilend.deposit(coin as never, SUI, cap, tx as never)
+      tx.transferObjects([cap as never], ctx.agentAddress)
+    } else {
+      const c = caps[0] as { id: string | { id: string } }
+      const capId = typeof c.id === 'string' ? c.id : c.id.id
+      suilend.deposit(coin as never, SUI, capId, tx as never)
+    }
+    expect(await simStatus(ctx, tx)).toBe('success')
+  }, 45_000)
+
+  test('read-only tools return live data', async () => {
+    const ctx = realCtx()
+    const position = await makeSuilendPosition(ctx).handler({})
+    expect(position.ok).toBe(true)
+
+    const markets = await makeScallopMarkets(ctx).handler({ coins: 'sui' })
+    expect(markets.ok).toBe(true)
+  }, 45_000)
+})

package/src/tools/scallop.ts

@@ -129,6 +129,10 @@ const AmountSchema = z.object({
 })
 type AmountArgs = z.infer<typeof AmountSchema>
 
+// Scallop redeems a MARKET-COIN amount on withdraw (not underlying SUI). We
+// find the agent's SUI market coin by type pattern (robust to package upgrades).
+const MARKET_COIN_SUI_RE = /::reserve::MarketCoin<0x0*2::sui::SUI>$/
+
 async function runScallopWrite(
   ctx: OnchainRuntimeContext,
   amount: string,
@@ -139,12 +143,13 @@ async function runScallopWrite(
   const amountMist = suiToMist(amount)
   if (amountMist === undefined || amountMist <= 0n)
     return { ok: false, error: `invalid amount "${amount}"` }
+  // Minimum guard on supply (withdraw pulls the agent's own funds back).
   if (kind === 'supply') {
     const tooSmall = checkMinimum('supply', amountMist)
     if (tooSmall) return { ok: false, error: tooSmall }
   }
 
-  // Policy gate (deterministic). Supplying moves funds out; withdrawing back in.
+  // Policy gate on the value-moving supply.
   if (ctx.policy && kind === 'supply') {
     const verdict = evaluatePolicy(
       { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'scallop' },
@@ -159,15 +164,35 @@ async function runScallopWrite(
     const builder = await sdk.createScallopBuilder()
     const tx = builder.createTxBlock()
     tx.setSender(ctx.agentAddress)
-    // deposit/withdraw auto-select the user's coins and return the resulting
-    // coin to hand back to the owner. depositQuick's 3rd arg returnSCoin=false
-    // keeps the old market-coin standard, which withdrawQuick can redeem (the
-    // new sCoin standard is not found by withdrawQuick → "No valid coins").
-    const out =
-      kind === 'supply'
-        ? await tx.depositQuick(Number(amountMist), 'sui', false)
-        : await tx.withdrawQuick(Number(amountMist), 'sui')
-    if (out) tx.transferObjects([out], ctx.agentAddress)
+    // depositQuick's 3rd arg returnSCoin=false keeps the old market-coin standard.
+    let out: unknown
+    if (kind === 'supply') {
+      out = await tx.depositQuick(Number(amountMist), 'sui', false)
+    } else {
+      // withdrawQuick redeems a MARKET-COIN amount, not underlying SUI. Convert
+      // the requested SUI to market coins at the position's rate and clamp to the
+      // held balance, so a full/over-withdraw cleanly redeems everything.
+      const [balances, q] = await Promise.all([
+        ctx.client.getAllBalances({ owner: ctx.agentAddress }),
+        sdk.createScallopQuery().then(async query => {
+          await query.init()
+          return query
+        }),
+      ])
+      const mc = balances.find(b => MARKET_COIN_SUI_RE.test(b.coinType))
+      const heldMc = BigInt(mc?.totalBalance ?? '0')
+      if (heldMc <= 0n) return { ok: false, error: 'no Scallop SUI position to withdraw' }
+      const port = (await q.getUserPortfolio({ walletAddress: ctx.agentAddress })) as {
+        lendings?: Array<{ coinName?: string; suppliedCoin?: number }>
+      }
+      const supplied = (port.lendings ?? []).find(l => l.coinName === 'sui')?.suppliedCoin ?? 0
+      const suppliedMist = BigInt(Math.floor(supplied * 1e9))
+      // redeem = requested/rate, where rate = supplied/heldMc; clamp to heldMc.
+      let redeemMc = suppliedMist > 0n ? (amountMist * heldMc) / suppliedMist : heldMc
+      if (redeemMc > heldMc || redeemMc <= 0n) redeemMc = heldMc
+      out = await tx.withdrawQuick(Number(redeemMc), 'sui')
+    }
+    if (out) tx.transferObjects([out as never], ctx.agentAddress)
     const transaction = tx.txBlock
 
     const sim = await simulate(ctx.client, transaction, ctx.agentAddress)
@@ -220,3 +245,9 @@ export function makeScallopWithdraw(ctx: OnchainRuntimeContext): ToolDef<AmountA
     handler: async args => runScallopWrite(ctx, args.amount, 'withdraw'),
   }
 }
+
+// NOTE: Scallop borrow/repay require opening a Scallop obligation + posting
+// collateral (a separate flow from lending deposits — borrowQuick alone aborts
+// "No obligation found"). Until that flow is wired, borrowing routes through the
+// verified NAVI/Suilend adapters instead, so we don't ship a borrow tool here
+// that can't execute.

package/src/tools/stake.ts

@@ -31,7 +31,7 @@ async function resolveValidator(
   // biome-ignore lint/suspicious/noExplicitAny: SuiSystemState validator fields
   const vals = (state.activeValidators ?? []) as any[]
   if (vals.length === 0) return null
-  if (want && want.trim()) {
+  if (want?.trim()) {
     const w = want.trim().toLowerCase()
     const m = vals.find(
       v => String(v.suiAddress).toLowerCase() === w || String(v.name ?? '').toLowerCase() === w,
@@ -100,7 +100,10 @@ export function makeStake(ctx: OnchainRuntimeContext): ToolDef<StakeArgs> {
           options: { showEffects: true, showObjectChanges: true },
         })
         if (res.effects?.status?.status !== 'success') {
-          return { ok: false, error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}` }
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
         }
         await ctx.client.waitForTransaction({ digest: res.digest })
         const staked = res.objectChanges?.find(
@@ -181,7 +184,10 @@ export function makeUnstake(ctx: OnchainRuntimeContext): ToolDef<UnstakeArgs> {
           options: { showEffects: true },
         })
         if (res.effects?.status?.status !== 'success') {
-          return { ok: false, error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}` }
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
         }
         await ctx.client.waitForTransaction({ digest: res.digest })
 

package/src/tools/suilend.ts

@@ -0,0 +1,472 @@
+/**
+ * Suilend lending tools (supporting integration): SUI supply / withdraw /
+ * borrow / repay + a read-only position, on Suilend's MAIN_POOL lending market.
+ *
+ * Suilend is one of the three largest money markets on Sui. Its SDK's 3.x line
+ * pins @mysten/sui v2 (a Transaction-class ABI break vs. our v1 stack), so we
+ * use @suilend/sdk@1.1.x, whose @mysten/sui is a *peerDependency* — it binds to
+ * our hosted v1 copy, so the v1 Transaction we build is accepted directly by the
+ * SDK (verified end-to-end with a live mainnet dry-run of a deposit).
+ *
+ * Value semantics (checked against the SDK source):
+ *   deposit / borrow / repay  → underlying MIST (clean).
+ *   withdraw                  → cTokens; we convert the requested underlying via
+ *                               the reserve's cToken exchange rate.
+ *
+ * Every write runs the same guarded pipeline as sui.send: minimum guard →
+ * policy gate → dry-run simulate → execute → on-chain effects check. The
+ * simulate is the safety net — an under-collateralized borrow or an over-sized
+ * withdraw fails before broadcast, never a false success.
+ */
+
+import { Transaction } from '@mysten/sui/transactions'
+import {
+  LENDING_MARKET_ID,
+  LENDING_MARKET_TYPE,
+  SuilendClient,
+  initializeSuilend,
+} from '@suilend/sdk'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { checkMinimum } from '../minimums'
+import { evaluatePolicy, suiToMist } from '../policy'
+import { simulate } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+
+const SUI_TYPE = '0x2::sui::SUI'
+// Canonical + long-form SUI coin types (reserve maps may use either).
+const SUI_LONG = `0x${'0'.repeat(63)}2::sui::SUI`
+
+function ensureMainnet(ctx: OnchainRuntimeContext): string | null {
+  return ctx.network === 'mainnet' ? null : 'Suilend SDK supports mainnet only'
+}
+
+async function newSuilend(ctx: OnchainRuntimeContext): Promise<SuilendClient> {
+  // ctx.client is @mysten/sui v1.4x; @suilend/sdk@1.1.x binds @mysten/sui as a
+  // peer, so the client interops directly across the copy boundary.
+  return SuilendClient.initialize(LENDING_MARKET_ID, LENDING_MARKET_TYPE, ctx.client as never)
+}
+
+/** Extract the object id from a parsed ObligationOwnerCap (`id` is a UID). */
+function capObjectId(cap: { id: unknown }): string {
+  const id = cap.id as string | { id: string }
+  return typeof id === 'string' ? id : id.id
+}
+
+function isSuiType(t: string): boolean {
+  return t === SUI_TYPE || t === SUI_LONG
+}
+
+/** The agent's obligation cap + id, or null if it has no Suilend position yet.
+ *  Retries: getObligationOwnerCaps reads owned objects + their BCS, which some
+ *  fullnode replicas serve inconsistently right after a write ("invalid data
+ *  type" / stale owned-object index) — a short retry rides out that lag. */
+async function findObligation(
+  ctx: OnchainRuntimeContext,
+): Promise<{ capId: string; obligationId: string } | null> {
+  let lastErr: unknown
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      const caps = await SuilendClient.getObligationOwnerCaps(
+        ctx.agentAddress,
+        [LENDING_MARKET_TYPE],
+        ctx.client as never,
+      )
+      if (!caps.length) return null
+      const c = caps[0] as { id: unknown; obligationId: string | { id: string } }
+      const obligationId = typeof c.obligationId === 'string' ? c.obligationId : c.obligationId.id
+      return { capId: capObjectId(c), obligationId }
+    } catch (e) {
+      lastErr = e
+      await new Promise(r => setTimeout(r, 1200))
+    }
+  }
+  throw lastErr
+}
+
+// --- suilend.supply --------------------------------------------------------
+
+const AmountSchema = z.object({
+  amount: z.string().min(1).describe('Amount of SUI, e.g. "1.5".'),
+})
+type AmountArgs = z.infer<typeof AmountSchema>
+
+// Borrowable/repayable assets. Suilend (like most money markets) forbids
+// borrowing the SAME asset you post as collateral (obligation::borrow abort 8),
+// so the canonical flow is "supply SUI → borrow a stablecoin". USDC is the
+// default; SUI is available for the reverse (supply a stable, borrow SUI).
+const USDC_TYPE = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC'
+type CoinInfo = { type: string; decimals: number; minBase: bigint; label: string }
+const BORROW_COINS: Record<'usdc' | 'sui', CoinInfo> = {
+  usdc: { type: USDC_TYPE, decimals: 6, minBase: 100_000n, label: 'USDC' }, // 0.1 USDC
+  sui: { type: SUI_TYPE, decimals: 9, minBase: 10_000_000n, label: 'SUI' }, // 0.01 SUI
+}
+
+/** Parse a decimal amount into base units for a given decimals count. */
+function toBaseUnits(amount: string, decimals: number): bigint | undefined {
+  const a = amount.trim()
+  if (!/^\d+(\.\d+)?$/.test(a)) return undefined
+  const dot = a.indexOf('.')
+  const whole = dot === -1 ? a : a.slice(0, dot)
+  const frac = dot === -1 ? '' : a.slice(dot + 1)
+  const fracPadded = (frac + '0'.repeat(decimals)).slice(0, decimals)
+  try {
+    return BigInt(whole || '0') * 10n ** BigInt(decimals) + BigInt(fracPadded || '0')
+  } catch {
+    return undefined
+  }
+}
+
+const BorrowSchema = z.object({
+  amount: z.string().min(1).describe('Amount to borrow/repay, e.g. "5".'),
+  coin: z
+    .enum(['usdc', 'sui'])
+    .optional()
+    .describe(
+      'Asset to borrow/repay (default "usdc"). Suilend disallows borrowing the same asset you supply as collateral, so borrowing USDC against SUI collateral is the canonical flow.',
+    ),
+})
+type BorrowArgs = z.infer<typeof BorrowSchema>
+
+export function makeSuilendSupply(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'suilend.supply',
+    description:
+      'Supply (deposit) idle SUI into Suilend to earn lending yield. Creates a Suilend obligation on first use, then deposits into it. Policy-checked, simulated, then executed.',
+    searchHint: 'suilend supply deposit lend sui earn yield idle money market',
+    schema: AmountSchema,
+    handler: async args => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      const amountMist = suiToMist(args.amount)
+      if (amountMist === undefined || amountMist <= 0n)
+        return { ok: false, error: `invalid amount "${args.amount}"` }
+      const tooSmall = checkMinimum('supply', amountMist)
+      if (tooSmall) return { ok: false, error: tooSmall }
+      if (ctx.policy) {
+        const verdict = evaluatePolicy(
+          { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'suilend' },
+          ctx.policy,
+        )
+        if (!verdict.allowed)
+          return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+      }
+      try {
+        const suilend = await newSuilend(ctx)
+        const existing = await findObligation(ctx)
+        const tx = new Transaction()
+        tx.setSender(ctx.agentAddress)
+        const [coin] = tx.splitCoins(tx.gas, [amountMist])
+        // The @suilend/sdk@1.1.x SDK carries its own nested @mysten/sui copy, so
+        // TS sees a distinct Transaction class — cast at the boundary. The two
+        // copies interop at runtime (verified with a live mainnet dry-run).
+        if (existing) {
+          suilend.deposit(coin as never, SUI_TYPE, existing.capId, tx as never)
+        } else {
+          const cap = suilend.createObligation(tx as never)
+          suilend.deposit(coin as never, SUI_TYPE, cap, tx as never)
+          tx.transferObjects([cap as never], ctx.agentAddress)
+        }
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true },
+        })
+        if (res.effects?.status?.status !== 'success')
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        return {
+          ok: true,
+          data: {
+            protocol: 'suilend',
+            action: 'supply',
+            amountSui: args.amount,
+            newObligation: !existing,
+            digest: res.digest,
+            policyEnforced: ctx.policy != null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- suilend.withdraw ------------------------------------------------------
+
+export function makeSuilendWithdraw(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'suilend.withdraw',
+    description:
+      'Withdraw supplied SUI from Suilend back to the agent (amount in underlying SUI). Refreshes prices, converts to cTokens at the current exchange rate, simulated, then executed.',
+    searchHint: 'suilend withdraw redeem unlend remove supplied sui money market',
+    schema: AmountSchema,
+    handler: async args => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      const amountMist = suiToMist(args.amount)
+      if (amountMist === undefined || amountMist <= 0n)
+        return { ok: false, error: `invalid amount "${args.amount}"` }
+      try {
+        const suilend = await newSuilend(ctx)
+        const obligation = await findObligation(ctx)
+        if (!obligation)
+          return { ok: false, error: 'no Suilend position — supply SUI before withdrawing' }
+        // Convert underlying → cTokens using the SUI reserve exchange rate.
+        const data = await initializeSuilend(ctx.client as never, suilend)
+        const rate = suiReserveExchangeRate(data)
+        if (rate === null) return { ok: false, error: 'could not read SUI reserve exchange rate' }
+        // cTokens = floor(underlying / rate); floor keeps us at/under the request.
+        const ctokens = BigInt(Math.floor(Number(amountMist) / rate))
+        if (ctokens <= 0n) return { ok: false, error: 'amount too small to withdraw' }
+        const tx = new Transaction()
+        tx.setSender(ctx.agentAddress)
+        await suilend.withdrawAndSendToUser(
+          ctx.agentAddress,
+          obligation.capId,
+          obligation.obligationId,
+          SUI_TYPE,
+          ctokens.toString(),
+          tx as never,
+        )
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true },
+        })
+        if (res.effects?.status?.status !== 'success')
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        return {
+          ok: true,
+          data: {
+            protocol: 'suilend',
+            action: 'withdraw',
+            amountSui: args.amount,
+            digest: res.digest,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- suilend.borrow --------------------------------------------------------
+
+export function makeSuilendBorrow(ctx: OnchainRuntimeContext): ToolDef<BorrowArgs> {
+  return {
+    name: 'suilend.borrow',
+    description:
+      'Borrow an asset from Suilend against supplied collateral. Default borrows USDC against SUI collateral (Suilend disallows same-asset borrows). Requires an existing obligation with enough health; the pre-flight simulation fails cleanly if under-collateralized. Policy-checked, simulated, then executed.',
+    searchHint: 'suilend borrow loan leverage debt against collateral usdc stablecoin money market',
+    schema: BorrowSchema,
+    handler: async args => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      const coin = BORROW_COINS[args.coin ?? 'usdc']
+      const amountBase = toBaseUnits(args.amount, coin.decimals)
+      if (amountBase === undefined || amountBase <= 0n)
+        return { ok: false, error: `invalid amount "${args.amount}"` }
+      if (amountBase < coin.minBase)
+        return { ok: false, error: `amount too small: below the minimum ${coin.label} borrow` }
+      if (ctx.policy) {
+        const verdict = evaluatePolicy(
+          { kind: 'transfer', coinType: coin.type, amountMist: amountBase, protocol: 'borrow' },
+          ctx.policy,
+        )
+        if (!verdict.allowed)
+          return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+      }
+      try {
+        const suilend = await newSuilend(ctx)
+        const obligation = await findObligation(ctx)
+        if (!obligation)
+          return { ok: false, error: 'no Suilend position — supply collateral before borrowing' }
+        const tx = new Transaction()
+        tx.setSender(ctx.agentAddress)
+        // borrow() self-refreshes prices (addRefreshCalls default true).
+        await suilend.borrowAndSendToUser(
+          ctx.agentAddress,
+          obligation.capId,
+          obligation.obligationId,
+          coin.type,
+          amountBase.toString(),
+          tx as never,
+        )
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true },
+        })
+        if (res.effects?.status?.status !== 'success')
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        return {
+          ok: true,
+          data: {
+            protocol: 'suilend',
+            action: 'borrow',
+            amount: args.amount,
+            coin: coin.label,
+            digest: res.digest,
+            policyEnforced: ctx.policy != null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- suilend.repay ---------------------------------------------------------
+
+export function makeSuilendRepay(ctx: OnchainRuntimeContext): ToolDef<BorrowArgs> {
+  return {
+    name: 'suilend.repay',
+    description:
+      'Repay borrowed debt on Suilend (default USDC; pass coin "sui" to repay a SUI loan). Simulated, then executed.',
+    searchHint: 'suilend repay pay back debt loan close usdc stablecoin sui money market',
+    schema: BorrowSchema,
+    handler: async args => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      const coin = BORROW_COINS[args.coin ?? 'usdc']
+      const amountBase = toBaseUnits(args.amount, coin.decimals)
+      if (amountBase === undefined || amountBase <= 0n)
+        return { ok: false, error: `invalid amount "${args.amount}"` }
+      if (ctx.policy) {
+        const verdict = evaluatePolicy(
+          { kind: 'transfer', coinType: coin.type, amountMist: amountBase, protocol: 'suilend' },
+          ctx.policy,
+        )
+        if (!verdict.allowed)
+          return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+      }
+      try {
+        const suilend = await newSuilend(ctx)
+        const obligation = await findObligation(ctx)
+        if (!obligation) return { ok: false, error: 'no Suilend position — nothing to repay' }
+        const tx = new Transaction()
+        tx.setSender(ctx.agentAddress)
+        await suilend.repayIntoObligation(
+          ctx.agentAddress,
+          obligation.obligationId,
+          coin.type,
+          amountBase.toString(),
+          tx as never,
+        )
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true },
+        })
+        if (res.effects?.status?.status !== 'success')
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        return {
+          ok: true,
+          data: {
+            protocol: 'suilend',
+            action: 'repay',
+            amount: args.amount,
+            coin: coin.label,
+            digest: res.digest,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- suilend.position (read) -----------------------------------------------
+
+const PositionSchema = z.object({})
+type PositionArgs = z.infer<typeof PositionSchema>
+
+export function makeSuilendPosition(ctx: OnchainRuntimeContext): ToolDef<PositionArgs> {
+  return {
+    name: 'suilend.position',
+    description:
+      "The agent's Suilend position: deposits, borrows, and per-asset balances. Read-only.",
+    searchHint: 'suilend position portfolio deposits borrows collateral debt health',
+    schema: PositionSchema,
+    handler: async () => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      try {
+        const suilend = await newSuilend(ctx)
+        const obligation = await findObligation(ctx)
+        if (!obligation)
+          return {
+            ok: true,
+            data: { protocol: 'suilend', hasPosition: false, deposits: [], borrows: [] },
+          }
+        const parsed = (await suilend.getObligation(obligation.obligationId)) as {
+          deposits?: Array<{ coinType?: { name?: string }; depositedCtokenAmount?: bigint }>
+          borrows?: Array<{ coinType?: { name?: string }; borrowedAmount?: { value?: bigint } }>
+        }
+        return {
+          ok: true,
+          data: {
+            protocol: 'suilend',
+            hasPosition: true,
+            obligationId: obligation.obligationId,
+            deposits: (parsed.deposits ?? []).map(d => ({
+              coin: d.coinType?.name,
+              ctokens: String(d.depositedCtokenAmount ?? 0n),
+            })),
+            borrows: (parsed.borrows ?? []).map(b => ({
+              coin: b.coinType?.name,
+              borrowed: String(b.borrowedAmount?.value ?? 0n),
+            })),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+/** Find the SUI reserve's cToken exchange rate (underlying per cToken) from an
+ *  initializeSuilend() result, or null if not present. */
+function suiReserveExchangeRate(data: unknown): number | null {
+  const d = data as {
+    reserveMap?: Record<string, { coinType?: string; cTokenExchangeRate?: unknown }>
+  }
+  const map = d.reserveMap
+  if (!map) return null
+  const reserve =
+    map[SUI_TYPE] ??
+    map[SUI_LONG] ??
+    Object.values(map).find(r => typeof r.coinType === 'string' && isSuiType(r.coinType))
+  if (!reserve) return null
+  const rate = Number(String(reserve.cTokenExchangeRate))
+  return Number.isFinite(rate) && rate > 0 ? rate : null
+}

package/src/tools/tools.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Unit coverage for the DeFi tool surface: (1) the plugin registers every
+ * value-moving adapter, and (2) each new write tool runs its guard checks
+ * (mainnet-only, valid amount, minimum size) BEFORE it ever touches the
+ * network — so a dust/invalid/testnet request fails fast and deterministically,
+ * never a false success.
+ *
+ * These tests deliberately use a bare stub context: the guard branches return
+ * before any `client`/`keypair` access, so no RPC is needed. Live end-to-end
+ * PTB simulation lives in `onchain.integration.test.ts` (gated on a real key).
+ */
+
+import { describe, expect, test } from 'bun:test'
+import type { PluginContext, ToolDef } from 'lyra-core'
+import plugin from '../index'
+import type { OnchainRuntimeContext } from '../types'
+import { makeVoloStake } from './liquid-stake'
+import { makeNaviBorrow, makeNaviRepay } from './navi'
+import { makeSuilendBorrow, makeSuilendSupply } from './suilend'
+
+// A context whose network/amount guards resolve before any client access.
+function stubCtx(network: 'mainnet' | 'testnet' = 'mainnet'): OnchainRuntimeContext {
+  return {
+    network,
+    agentAddress: '0x0000000000000000000000000000000000000000000000000000000000000abc',
+    agentDir: '/tmp/lyra-test',
+    // Accessing either of these would throw — guards must return first.
+    client: new Proxy(
+      {},
+      {
+        get() {
+          throw new Error('network access before guard')
+        },
+      },
+    ) as never,
+    keypair: {} as never,
+  }
+}
+
+describe('onchain plugin registration', () => {
+  test('registers the full DeFi write surface (lending + staking + swap)', () => {
+    const names: string[] = []
+    const ctx = {
+      registerTool: (def: ToolDef) => names.push(def.name),
+      registerListener: () => {},
+      addHook: () => {},
+      network: 'mainnet',
+      agentDir: '/tmp',
+      agentId: 'test',
+      // side-banded onchain runtime the plugin reads off PluginContext
+      onchain: stubCtx(),
+    } as unknown as PluginContext
+    plugin.register(ctx)
+
+    for (const expected of [
+      // lending: the three biggest Sui money markets, full CRUD
+      'scallop.supply',
+      'scallop.withdraw',
+      'navi.supply',
+      'navi.borrow',
+      'navi.repay',
+      'suilend.supply',
+      'suilend.withdraw',
+      'suilend.borrow',
+      'suilend.repay',
+      'suilend.position',
+      // staking: native + Volo liquid staking
+      'sui.stake',
+      'sui.unstake',
+      'volo.stake',
+      'volo.unstake',
+      // swap aggregator
+      'swap',
+    ]) {
+      expect(names).toContain(expected)
+    }
+  })
+
+  test('registers nothing without an onchain runtime (safe no-op for loaders)', () => {
+    const names: string[] = []
+    const ctx = {
+      registerTool: (def: ToolDef) => names.push(def.name),
+      registerListener: () => {},
+      addHook: () => {},
+      network: 'mainnet',
+      agentDir: '/tmp',
+      agentId: 'test',
+    } as unknown as PluginContext
+    plugin.register(ctx)
+    expect(names).toHaveLength(0)
+  })
+})
+
+describe('write-tool guards (fail before network)', () => {
+  test('suilend.supply rejects a dust amount below the supply minimum', async () => {
+    const res = await makeSuilendSupply(stubCtx()).handler({ amount: '0.001' })
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.error).toContain('amount too small')
+  })
+
+  test('suilend.borrow rejects a dust amount below the borrow minimum', async () => {
+    const res = await makeSuilendBorrow(stubCtx()).handler({ amount: '0.0001' })
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.error).toContain('amount too small')
+  })
+
+  test('volo.stake rejects below the 1 SUI staking minimum', async () => {
+    const res = await makeVoloStake(stubCtx()).handler({ amount: '0.1' })
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.error).toContain('amount too small')
+  })
+
+  test('navi.borrow rejects a dust amount', async () => {
+    const res = await makeNaviBorrow(stubCtx()).handler({ amount: '0.001' })
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.error).toContain('amount too small')
+  })
+
+  test('invalid amount strings are rejected before any network call', async () => {
+    const res = await makeVoloStake(stubCtx()).handler({ amount: 'not-a-number' })
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.error).toContain('invalid amount')
+  })
+
+  test('mainnet-only tools refuse to run on testnet', async () => {
+    const supply = await makeSuilendSupply(stubCtx('testnet')).handler({ amount: '5' })
+    expect(supply.ok).toBe(false)
+    if (!supply.ok) expect(supply.error).toContain('mainnet only')
+
+    const stake = await makeVoloStake(stubCtx('testnet')).handler({ amount: '5' })
+    expect(stake.ok).toBe(false)
+    if (!stake.ok) expect(stake.error).toContain('mainnet only')
+  })
+
+  test('navi.repay is a registered, well-formed tool', () => {
+    const tool = makeNaviRepay(stubCtx())
+    expect(tool.name).toBe('navi.repay')
+    expect(typeof tool.handler).toBe('function')
+  })
+})