lyra-plugin-onchain 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lyra-plugin-onchain",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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/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,
@@ -36,13 +37,22 @@ import {
 import { makePolicyCreate, makePolicyShow } from './tools/policy'
 import { makeProtocolsList } from './tools/protocols'
 import {
+  makeScallopBorrow,
   makeScallopMarkets,
   makeScallopPosition,
+  makeScallopRepay,
   makeScallopSupply,
   makeScallopWithdraw,
 } 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'
@@ -95,16 +105,25 @@ const plugin: NativePlugin = {
     ctx.registerTool(makeScallopPosition(onchain) as ToolDef)
     ctx.registerTool(makeScallopSupply(onchain) as ToolDef)
     ctx.registerTool(makeScallopWithdraw(onchain) as ToolDef)
+    ctx.registerTool(makeScallopBorrow(onchain) as ToolDef)
+    ctx.registerTool(makeScallopRepay(onchain) as ToolDef)
     ctx.registerTool(makeNaviMarkets(onchain) as ToolDef)
     ctx.registerTool(makeNaviPosition(onchain) as ToolDef)
     ctx.registerTool(makeNaviSupply(onchain) as ToolDef)
     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',
@@ -51,8 +51,16 @@ export const PROTOCOLS: ProtocolCapability[] = [
     category: 'lending',
     read: true,
     execute: true,
-    tools: ['scallop.markets', 'scallop.position', 'scallop.supply', 'scallop.withdraw'],
+    tools: [
+      'scallop.markets',
+      'scallop.position',
+      'scallop.supply',
+      'scallop.withdraw',
+      'scallop.borrow',
+      'scallop.repay',
+    ],
     llamaProjects: ['scallop-lending', 'scallop'],
+    note: 'full supply / withdraw / borrow / repay',
   },
   {
     id: 'navi',
@@ -60,13 +68,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 +131,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

@@ -132,22 +132,29 @@ type AmountArgs = z.infer<typeof AmountSchema>
 async function runScallopWrite(
   ctx: OnchainRuntimeContext,
   amount: string,
-  kind: 'supply' | 'withdraw',
+  kind: 'supply' | 'withdraw' | 'borrow' | 'repay',
 ): Promise<{ ok: true; data: unknown } | { ok: false; error: string }> {
   const err = ensureMainnet(ctx)
   if (err) return { ok: false, error: err }
   const amountMist = suiToMist(amount)
   if (amountMist === undefined || amountMist <= 0n)
     return { ok: false, error: `invalid amount "${amount}"` }
-  if (kind === 'supply') {
-    const tooSmall = checkMinimum('supply', amountMist)
+  // Minimum guard for value-moving actions (withdraw pulls the agent's own funds).
+  const minAction = kind === 'borrow' ? 'borrow' : kind === 'withdraw' ? null : 'supply'
+  if (minAction) {
+    const tooSmall = checkMinimum(minAction, amountMist)
     if (tooSmall) return { ok: false, error: tooSmall }
   }
 
-  // Policy gate (deterministic). Supplying moves funds out; withdrawing back in.
-  if (ctx.policy && kind === 'supply') {
+  // Policy gate on value-moving actions (borrow creates debt + hands out funds).
+  if (ctx.policy && kind !== 'withdraw') {
     const verdict = evaluatePolicy(
-      { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'scallop' },
+      {
+        kind: 'transfer',
+        coinType: SUI_TYPE,
+        amountMist,
+        protocol: kind === 'borrow' ? 'borrow' : 'scallop',
+      },
       ctx.policy,
     )
     if (!verdict.allowed)
@@ -159,15 +166,16 @@ 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)
+    // *Quick helpers auto-select the user's coins/obligation. supply/withdraw and
+    // borrow return a coin to hand back; repay consumes coins. depositQuick's 3rd
+    // arg returnSCoin=false keeps the old market-coin standard (withdrawQuick
+    // redeems it; the new sCoin standard → "No valid coins").
+    let out: unknown
+    if (kind === 'supply') out = await tx.depositQuick(Number(amountMist), 'sui', false)
+    else if (kind === 'withdraw') out = await tx.withdrawQuick(Number(amountMist), 'sui')
+    else if (kind === 'borrow') out = await tx.borrowQuick(Number(amountMist), 'sui')
+    else await tx.repayQuick(Number(amountMist), '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 +228,24 @@ export function makeScallopWithdraw(ctx: OnchainRuntimeContext): ToolDef<AmountA
     handler: async args => runScallopWrite(ctx, args.amount, 'withdraw'),
   }
 }
+
+export function makeScallopBorrow(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'scallop.borrow',
+    description:
+      'Borrow SUI from Scallop against supplied collateral. Requires an existing supply position with enough health; the pre-flight simulation fails cleanly if under-collateralized. Policy-checked, simulated, then executed.',
+    searchHint: 'scallop borrow loan leverage debt against collateral sui',
+    schema: AmountSchema,
+    handler: async args => runScallopWrite(ctx, args.amount, 'borrow'),
+  }
+}
+
+export function makeScallopRepay(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'scallop.repay',
+    description: 'Repay borrowed SUI debt on Scallop. Simulated, then executed.',
+    searchHint: 'scallop repay pay back debt loan close sui',
+    schema: AmountSchema,
+    handler: async args => runScallopWrite(ctx, args.amount, 'repay'),
+  }
+}

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,419 @@
+/**
+ * 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. */
+async function findObligation(
+  ctx: OnchainRuntimeContext,
+): Promise<{ capId: string; obligationId: string } | null> {
+  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 }
+}
+
+// --- 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>
+
+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<AmountArgs> {
+  return {
+    name: 'suilend.borrow',
+    description:
+      'Borrow SUI from Suilend against supplied collateral (amount in underlying SUI). 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 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}"` }
+      const tooSmall = checkMinimum('borrow', amountMist)
+      if (tooSmall) return { ok: false, error: tooSmall }
+      if (ctx.policy) {
+        const verdict = evaluatePolicy(
+          { kind: 'transfer', coinType: SUI_TYPE, amountMist, 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,
+          SUI_TYPE,
+          amountMist.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',
+            amountSui: args.amount,
+            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<AmountArgs> {
+  return {
+    name: 'suilend.repay',
+    description:
+      'Repay borrowed SUI debt on Suilend (amount in underlying SUI). Simulated, then executed.',
+    searchHint: 'suilend repay pay back debt loan close 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}"` }
+      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 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,
+          SUI_TYPE,
+          amountMist.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',
+            amountSui: args.amount,
+            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,142 @@
+/**
+ * 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 { makeScallopBorrow, makeScallopRepay } from './scallop'
+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',
+      'scallop.borrow',
+      'scallop.repay',
+      '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('scallop.borrow rejects a dust amount', async () => {
+    const res = await makeScallopBorrow(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('scallop.repay is a registered, well-formed tool', () => {
+    const tool = makeScallopRepay(stubCtx())
+    expect(tool.name).toBe('scallop.repay')
+    expect(typeof tool.handler).toBe('function')
+  })
+})