lyra-plugin-onchain 0.1.5 → 0.1.8

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/swap.ts

@@ -13,6 +13,7 @@ import { MetaAg } from '@7kprotocol/sdk-ts'
 import { Transaction, coinWithBalance } from '@mysten/sui/transactions'
 import type { ToolDef } from 'lyra-core'
 import { z } from 'zod'
+import { checkMinimum } from '../minimums'
 import { evaluatePolicy } from '../policy'
 import { simulate } from '../simulate'
 import type { OnchainRuntimeContext } from '../types'
@@ -63,6 +64,11 @@ export function makeSwap(ctx: OnchainRuntimeContext): ToolDef<Args> {
         if (from.type === to.type) return { ok: false, error: 'from and to are the same coin' }
         const amountIn = BigInt(Math.round(Number(args.amount) * 10 ** from.decimals))
         if (amountIn <= 0n) return { ok: false, error: `invalid amount "${args.amount}"` }
+        // Minimum only bounds SUI-denominated input (amountIn is then in MIST).
+        if (from.type === SUI_TYPE) {
+          const tooSmall = checkMinimum('swap', amountIn)
+          if (tooSmall) return { ok: false, error: tooSmall }
+        }
 
         // Policy gate. The MIST per-tx cap is SUI-denominated, so it only bounds
         // SUI-input swaps; the slippage/protocol/expiry checks always apply.

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')
+  })
+})