lyra-plugin-onchain 0.1.0

package/src/tools/defillama.ts

@@ -0,0 +1,89 @@
+/**
+ * `defi.yields` — read-only yield discovery across Sui DeFi via DefiLlama.
+ *
+ * Discovery only: it never moves funds. It gives the agent market context — the
+ * best APYs on Sui, with TVL, stablecoin, and impermanent-loss-risk signals — so
+ * a supply/swap proposal is grounded in real data before it hits the policy gate.
+ */
+
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { adapterForProject } from '../protocols'
+import type { OnchainRuntimeContext } from '../types'
+
+const YIELDS_URL = 'https://yields.llama.fi/pools'
+
+interface LlamaPool {
+  chain: string
+  project: string
+  symbol: string
+  apy: number | null
+  tvlUsd: number | null
+  stablecoin: boolean
+  ilRisk: string
+  exposure: string
+}
+
+const Schema = z.object({
+  asset: z.string().optional().describe('Filter by symbol substring, e.g. "USDC", "SUI".'),
+  project: z.string().optional().describe('Filter by protocol, e.g. "scallop", "navi-lending".'),
+  limit: z.number().int().min(1).max(25).optional().describe('Max pools to return. Default 8.'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeDefiYields(_ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'defi.yields',
+    description:
+      'Discover the best yields on Sui (DefiLlama, read-only): pools ranked by APY with TVL, stablecoin, and IL-risk signals. Use for "where can I earn yield", "best stablecoin yield on Sui". Never moves funds.',
+    searchHint: 'yield apy best earn discover defillama pools tvl stablecoin opportunities sui',
+    schema: Schema,
+    handler: async args => {
+      try {
+        const res = await fetch(YIELDS_URL)
+        if (!res.ok) return { ok: false, error: `DefiLlama returned ${res.status}` }
+        const body = (await res.json()) as { data: LlamaPool[] }
+        const asset = args.asset?.trim().toUpperCase()
+        const project = args.project?.trim().toLowerCase()
+        const pools = body.data
+          .filter(p => p.chain === 'Sui')
+          .filter(p => (asset ? p.symbol?.toUpperCase().includes(asset) : true))
+          .filter(p => (project ? p.project?.toLowerCase().includes(project) : true))
+          .sort((a, b) => (b.apy ?? 0) - (a.apy ?? 0))
+          .slice(0, args.limit ?? 8)
+          .map(p => {
+            // Tag each opportunity with whether Lyra can actually ACT on it.
+            const adapter = adapterForProject(p.project)
+            return {
+              project: p.project,
+              symbol: p.symbol,
+              apy: p.apy != null ? `${p.apy.toFixed(2)}%` : null,
+              tvlUsd: p.tvlUsd,
+              stablecoin: p.stablecoin,
+              ilRisk: p.ilRisk,
+              exposure: p.exposure,
+              executable: adapter?.execute ?? false,
+              executeWith: adapter?.execute
+                ? (adapter.tools.find(t => /supply|stake|deposit/.test(t)) ?? adapter.tools[0])
+                : null,
+            }
+          })
+        const executable = pools.filter(p => p.executable).length
+        return {
+          ok: true,
+          data: {
+            chain: 'Sui',
+            count: pools.length,
+            pools,
+            note:
+              executable < pools.length
+                ? `${executable}/${pools.length} are directly executable by Lyra (Scallop/NAVI). For others Lyra can discover + explain, but cannot execute — propose the best executable alternative or give manual steps.`
+                : undefined,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/navi.ts

@@ -0,0 +1,189 @@
+/**
+ * NAVI lending tools (the largest Sui lending market by TVL): markets + position
+ * (read) and SUI supply/withdraw (policy-gated writes).
+ *
+ * NAVI's SDK is v1-compatible and exposes PTB builders (`depositCoin`,
+ * `withdrawCoin`) that take a @mysten/sui Transaction, so writes flow through the
+ * SAME policy → simulate → execute pipeline as sui.send. The dry-run simulate is
+ * the safety net for a malformed or out-of-funds action.
+ */
+
+import { Transaction } from '@mysten/sui/transactions'
+import type { ToolDef } from 'lyra-core'
+import { NAVISDKClient, depositCoin, pool, withdrawCoin } from 'navi-sdk'
+import { z } from 'zod'
+import { evaluatePolicy, suiToMist } from '../policy'
+import { simulate } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+
+const SUI_TYPE = '0x2::sui::SUI'
+
+function ensureMainnet(ctx: OnchainRuntimeContext): string | null {
+  return ctx.network === 'mainnet' ? null : 'NAVI SDK supports mainnet only'
+}
+
+// --- navi.markets ----------------------------------------------------------
+
+export function makeNaviMarkets(ctx: OnchainRuntimeContext): ToolDef<Record<string, never>> {
+  return {
+    name: 'navi.markets',
+    description:
+      'Read NAVI lending markets on Sui (the largest Sui money market by TVL): supply/borrow APY and reserves per asset. Read-only discovery.',
+    searchHint: 'navi lending market supply borrow apy yield reserves rates earn largest tvl',
+    schema: z.object({}),
+    handler: async () => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      try {
+        const c = new NAVISDKClient({ networkType: 'mainnet' })
+        const info = (await c.getPoolInfo()) as Record<string, unknown>
+        const pools = Object.values(info)
+          .map(p => {
+            const r = p as {
+              coinType?: string
+              symbol?: string
+              supplyIncentiveApyInfo?: { apy?: number }
+              borrowIncentiveApyInfo?: { apy?: number }
+              base_supply_rate?: number
+              base_borrow_rate?: number
+            }
+            return {
+              symbol: r.symbol ?? r.coinType,
+              supplyApy: r.base_supply_rate ?? r.supplyIncentiveApyInfo?.apy ?? null,
+              borrowApy: r.base_borrow_rate ?? r.borrowIncentiveApyInfo?.apy ?? null,
+            }
+          })
+          .filter(p => p.symbol)
+          .slice(0, 12)
+        return { ok: true, data: { protocol: 'navi', network: 'mainnet', pools } }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- navi.position ---------------------------------------------------------
+
+export function makeNaviPosition(ctx: OnchainRuntimeContext): ToolDef<Record<string, never>> {
+  return {
+    name: 'navi.position',
+    description:
+      "The agent's NAVI position: supplied/borrowed balances and health factor (lower = closer to liquidation). Read-only.",
+    searchHint: 'navi position portfolio supplied borrowed debt health factor liquidation',
+    schema: z.object({}),
+    handler: async () => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      try {
+        const c = new NAVISDKClient({ networkType: 'mainnet' })
+        const [health, portfolios] = await Promise.all([
+          c.getHealthFactor(ctx.agentAddress).catch(() => null),
+          // .d.ts declares 0 args but it accepts an address at runtime.
+          (c as { getAllNaviPortfolios(a: string): Promise<unknown> })
+            .getAllNaviPortfolios(ctx.agentAddress)
+            .catch(() => null),
+        ])
+        return {
+          ok: true,
+          data: {
+            protocol: 'navi',
+            healthFactor: health,
+            portfolios: portfolios ? Object.fromEntries(portfolios as Map<string, unknown>) : null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- navi.supply / navi.withdraw (SUI) -------------------------------------
+
+const AmountSchema = z.object({ amount: z.string().min(1).describe('Amount of SUI, e.g. "1.5".') })
+type AmountArgs = z.infer<typeof AmountSchema>
+
+async function runNaviWrite(
+  ctx: OnchainRuntimeContext,
+  amount: string,
+  kind: 'supply' | 'withdraw',
+): 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 (ctx.policy && kind === 'supply') {
+    const verdict = evaluatePolicy(
+      { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'navi' },
+      ctx.policy,
+    )
+    if (!verdict.allowed)
+      return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+  }
+
+  try {
+    const tx = new Transaction()
+    const suiPool = (pool as Record<string, unknown>).Sui
+    if (kind === 'supply') {
+      const [coin] = tx.splitCoins(tx.gas, [amountMist])
+      await depositCoin(tx as never, suiPool as never, coin as never, Number(amountMist))
+    } else {
+      // navi-sdk's withdrawCoin already wraps the withdrawn Balance into a Coin
+      // (via coin::from_balance) and returns [coin]; destructure and transfer it.
+      const [coin] = await withdrawCoin(tx as never, suiPool as never, Number(amountMist))
+      tx.transferObjects([coin 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'}` }
+    }
+    // Wait for the tx to settle/index so a follow-up action (e.g. an immediate
+    // withdraw after a supply) doesn't race NAVI's not-yet-settled accounting.
+    await ctx.client.waitForTransaction({ digest: res.digest })
+    return {
+      ok: true,
+      data: {
+        protocol: 'navi',
+        action: kind,
+        amountSui: amount,
+        digest: res.digest,
+        simGasUsed: sim.gasUsed,
+        policyEnforced: ctx.policy != null,
+      },
+    }
+  } catch (e) {
+    return { ok: false, error: (e as Error).message.slice(0, 240) }
+  }
+}
+
+export function makeNaviSupply(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'navi.supply',
+    description:
+      'Supply (deposit) idle SUI into NAVI to earn lending yield. Policy-checked, simulated, then executed.',
+    searchHint: 'navi supply deposit lend sui earn yield idle',
+    schema: AmountSchema,
+    handler: async args => runNaviWrite(ctx, args.amount, 'supply'),
+  }
+}
+
+export function makeNaviWithdraw(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'navi.withdraw',
+    description: 'Withdraw supplied SUI from NAVI back to the agent. Simulated, then executed.',
+    searchHint: 'navi withdraw redeem unlend remove sui',
+    schema: AmountSchema,
+    handler: async args => runNaviWrite(ctx, args.amount, 'withdraw'),
+  }
+}

package/src/tools/policy.ts

@@ -0,0 +1,180 @@
+/**
+ * Policy tools: `policy.show` (legible control layer) and `policy.create`
+ * (mint an on-chain `lyra::policy::AgentPolicy`).
+ *
+ * The control layer is only trustworthy if it is legible and enforceable.
+ * `policy.show` reports the active off-chain caps; `policy.create` publishes a
+ * shared AgentPolicy on Sui so the same budget/per-tx/expiry are enforced in
+ * Move and every action mints an auditable receipt.
+ */
+
+import { bcs } from '@mysten/sui/bcs'
+import { Transaction } from '@mysten/sui/transactions'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { suiToMist } from '../policy'
+import type { OnchainRuntimeContext } from '../types'
+import { fmtSui } from './balance'
+
+// --- policy.show -----------------------------------------------------------
+
+const ShowSchema = z.object({})
+type ShowArgs = z.infer<typeof ShowSchema>
+
+export function makePolicyShow(ctx: OnchainRuntimeContext): ToolDef<ShowArgs> {
+  return {
+    name: 'policy.show',
+    description:
+      'Show the active deterministic fund-control policy: per-tx cap, auto-approve ceiling, autonomy tier, coin/protocol allowlists, slippage cap, and expiry. Read-only. Call for "what are my limits", "what can you spend", or before explaining why an action was blocked.',
+    searchHint:
+      'policy limits caps allowlist autonomy approval guardrails rules what can you spend',
+    schema: ShowSchema,
+    handler: async () => {
+      const p = ctx.policy
+      if (!p) {
+        return {
+          ok: true,
+          data: {
+            enforced: false,
+            policyPackage: ctx.packageId ?? null,
+            note: 'No LYRA_POLICY_* configured — no in-code caps this session. Value-moving actions still go through simulation and the session permission mode.',
+          },
+        }
+      }
+      const readOnly = p.readOnly === true || p.autonomy === 'readonly'
+      const maxPerTx = p.maxMistPerTx === undefined ? null : `${fmtSui(p.maxMistPerTx)} SUI`
+      const autoUpTo = p.autoMaxMistPerTx === undefined ? null : `${fmtSui(p.autoMaxMistPerTx)} SUI`
+      const lines: string[] = []
+      if (readOnly) lines.push('READ-ONLY: all writes are blocked.')
+      if (maxPerTx) lines.push(`Hard cap: sends over ${maxPerTx} are blocked.`)
+      if (autoUpTo) lines.push(`Auto-execute up to ${autoUpTo}; above that requires approval.`)
+      if (p.maxSlippageBps !== undefined)
+        lines.push(`Swaps over ${p.maxSlippageBps} bps slippage are blocked.`)
+      if (p.coinAllowlist?.length)
+        lines.push(`Only ${p.coinAllowlist.length} allowlisted coin type(s) may be moved.`)
+      if (p.protocolAllowlist?.length)
+        lines.push(`Only protocols: ${p.protocolAllowlist.join(', ')}.`)
+      if (p.recipientAllowlist?.length)
+        lines.push(`Transfers only to ${p.recipientAllowlist.length} allowlisted recipient(s).`)
+      if (p.expiryMs !== undefined)
+        lines.push(`Policy expires ${new Date(p.expiryMs).toISOString()}.`)
+      if (p.autonomy === 'confirm') lines.push('Autonomy=confirm: every write needs approval.')
+
+      return {
+        ok: true,
+        data: {
+          enforced: true,
+          readOnly,
+          autonomy: p.autonomy ?? 'auto',
+          maxPerTx,
+          autoApproveUpTo: autoUpTo,
+          maxSlippageBps: p.maxSlippageBps ?? null,
+          coinAllowlist: p.coinAllowlist ?? null,
+          protocolAllowlist: p.protocolAllowlist ?? null,
+          recipientAllowlist: p.recipientAllowlist ?? null,
+          expiry: p.expiryMs ? new Date(p.expiryMs).toISOString() : null,
+          policyPackage: ctx.packageId ?? null,
+          policyObject: ctx.policyObjectId ?? null,
+          summary:
+            lines.length > 0 ? lines.join(' ') : 'Policy armed but with no specific caps set.',
+        },
+      }
+    },
+  }
+}
+
+// --- policy.create ---------------------------------------------------------
+
+const CreateSchema = z.object({
+  budgetSui: z.string().min(1).describe('Lifetime spend ceiling in SUI, e.g. "10".'),
+  maxPerTxSui: z.string().min(1).describe('Hard per-action cap in SUI, e.g. "1".'),
+  maxSlippageBps: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Reference slippage cap (bps). Default 100.'),
+  expiryMinutes: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Minutes until the policy expires. 0 / omit = never.'),
+})
+type CreateArgs = z.infer<typeof CreateSchema>
+
+export function makePolicyCreate(ctx: OnchainRuntimeContext): ToolDef<CreateArgs> {
+  return {
+    name: 'policy.create',
+    description:
+      'Publish a shared on-chain lyra::policy::AgentPolicy bounding this agent: a lifetime budget, a per-tx cap, slippage, and an expiry. Enforced in Move on every subsequent action. Returns the policy object id + owner cap.',
+    searchHint: 'create policy on-chain agentpolicy budget cap expiry mint publish guardrail',
+    schema: CreateSchema,
+    handler: async args => {
+      try {
+        if (!ctx.packageId)
+          return { ok: false, error: 'no lyra::policy package configured (LYRA_PACKAGE_ID)' }
+        const budget = suiToMist(args.budgetSui)
+        const maxPerTx = suiToMist(args.maxPerTxSui)
+        if (budget === undefined || maxPerTx === undefined) {
+          return { ok: false, error: 'invalid budget or per-tx amount' }
+        }
+        const expiryMs = args.expiryMinutes ? Date.now() + args.expiryMinutes * 60_000 : 0
+        const tx = new Transaction()
+        tx.moveCall({
+          target: `${ctx.packageId}::policy::create_policy`,
+          arguments: [
+            tx.pure.address(ctx.agentAddress),
+            tx.pure.u64(budget),
+            tx.pure.u64(maxPerTx),
+            tx.pure.u64(BigInt(args.maxSlippageBps ?? 100)),
+            // allowed_coins: vector<vector<u8>> — empty = any coin (off-chain policy still applies).
+            tx.pure(bcs.vector(bcs.vector(bcs.u8())).serialize([])),
+            // allowed_protocols: vector<address> — empty = any protocol.
+            tx.pure(bcs.vector(bcs.Address).serialize([])),
+            tx.pure.u64(BigInt(expiryMs)),
+            tx.object.clock(),
+          ],
+        })
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: tx,
+          options: { showEffects: true, showObjectChanges: true },
+        })
+        if (res.effects?.status?.status !== 'success') {
+          return {
+            ok: false,
+            error: `execution failed: ${res.effects?.status?.error ?? 'unknown'}`,
+          }
+        }
+        // Wait for indexing so the new shared policy object is queryable before
+        // the next action references it (avoids a notExists race on sui.send).
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        const created = (res.objectChanges ?? []).filter(c => c.type === 'created') as {
+          objectId: string
+          objectType?: string
+        }[]
+        const policyObj = created.find(c => String(c.objectType).endsWith('::policy::AgentPolicy'))
+        const ownerCap = created.find(c =>
+          String(c.objectType).endsWith('::policy::PolicyOwnerCap'),
+        )
+        // Wire subsequent writes to record against this policy on-chain.
+        if (policyObj) ctx.policyObjectId = policyObj.objectId
+
+        return {
+          ok: true,
+          data: {
+            digest: res.digest,
+            policyObject: policyObj?.objectId ?? null,
+            ownerCap: ownerCap?.objectId ?? null,
+            budgetSui: args.budgetSui,
+            maxPerTxSui: args.maxPerTxSui,
+            expiry: expiryMs ? new Date(expiryMs).toISOString() : 'never',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/protocols.ts

@@ -0,0 +1,38 @@
+/**
+ * `protocols.list` — Lyra's honest capability map: which Sui protocols it can
+ * READ vs EXECUTE on. The agent calls this before claiming it can act somewhere,
+ * so it never promises a transaction on a protocol it has no adapter for.
+ */
+
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { PROTOCOLS } from '../protocols'
+import type { OnchainRuntimeContext } from '../types'
+
+export function makeProtocolsList(_ctx: OnchainRuntimeContext): ToolDef<Record<string, never>> {
+  return {
+    name: 'protocols.list',
+    description:
+      "Lyra's integrated protocols and what it can do with each: read-only vs executable, by category (lending, DEX, staking, storage, CLOB). Call this to answer 'what can you do', 'which protocols do you support', or before telling a user whether an action is possible. Discovery (defi.yields) spans ALL Sui protocols; execution is bounded to this list.",
+    searchHint:
+      'protocols supported integrations capabilities what can you do execute adapters list',
+    schema: z.object({}),
+    handler: async () => ({
+      ok: true,
+      data: {
+        protocols: PROTOCOLS.map(p => ({
+          id: p.id,
+          name: p.name,
+          category: p.category,
+          canRead: p.read,
+          canExecute: p.execute,
+          tools: p.tools,
+          note: p.note,
+        })),
+        executable: PROTOCOLS.filter(p => p.execute).map(p => p.id),
+        boundary:
+          'Lyra can DISCOVER yields on any Sui protocol (defi.yields) but only EXECUTE on the protocols marked canExecute. For others, it surfaces the opportunity and proposes the best executable alternative or manual steps — it does not fabricate transactions.',
+      },
+    }),
+  }
+}