lyra-plugin-onchain 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lyra-plugin-onchain",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
@@ -55,7 +55,7 @@
     "@scallop-io/sui-scallop-sdk": "^2.4.5",
     "@suilend/sdk": "1.1.99",
     "@suilend/sui-fe": "0.3.49",
-    "lyra-core": "^0.2.0",
+    "lyra-core": "^0.2.1",
     "navi-sdk": "^1.7.3",
     "zod": "^3.23.8"
   }

package/src/catalog.ts

@@ -0,0 +1,120 @@
+/**
+ * The tool catalog — the ONE place every on-chain tool is declared. Adding a tool
+ * is a single entry here (plus the tool file itself); everything downstream is
+ * derived:
+ *
+ *   - registration        → the plugin iterates TOOLS (index.ts)
+ *   - web console tool set → WEB_TOOL_NAMES (apps import it; no hand-kept allowlist)
+ *   - agent guidance       → capabilitySummary() feeds the system prompt (CLI + web),
+ *                            so the model learns a new capability with no prose edit
+ *
+ * `web` marks a tool for the browser console's inline-execute set (the rest run on
+ * the CLI/gateway, or have a web-native equivalent). `blurb` is an optional one-line
+ * capability description surfaced in the guidance — omit it for secondary tools in a
+ * family that a sibling already covers.
+ */
+
+import type { ToolDef } from 'lyra-core'
+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,
+  makeNaviPosition,
+  makeNaviRepay,
+  makeNaviSupply,
+  makeNaviWithdraw,
+} from './tools/navi'
+import { makePolicyCreate, makePolicyShow } from './tools/policy'
+import { makeProtocolsList } from './tools/protocols'
+import {
+  makeScallopMarkets,
+  makeScallopPosition,
+  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 { makeWalrusStake, makeWalrusStaking, makeWalrusUnstake } from './tools/walrus-stake'
+import type { OnchainRuntimeContext } from './types'
+
+// biome-ignore lint/suspicious/noExplicitAny: tools carry heterogeneous arg schemas
+type Make = (ctx: OnchainRuntimeContext) => ToolDef<any>
+
+export interface CatalogEntry {
+  /** The tool's registered name (also its dispatch key). */
+  name: string
+  /** Factory that binds the tool to a runtime context. */
+  make: Make
+  /** Exposed in the browser console's inline-execute tool set. */
+  web: boolean
+  /** One-line capability blurb for the agent guidance (optional). */
+  blurb?: string
+}
+
+export const TOOLS: CatalogEntry[] = [
+  // Reads / discovery
+  { name: 'account.info', make: makeAccountInfo, web: false, blurb: 'account.info — the agent address, network, balance, and active policy.' },
+  { name: 'sui.balance', make: makeSuiBalance, web: false, blurb: 'sui.balance — SUI + coin balances for the agent or any address.' },
+  { name: 'policy.show', make: makePolicyShow, web: false, blurb: 'policy.show — the active fund-control policy (caps, allowlists, expiry).' },
+  { name: 'protocols.list', make: makeProtocolsList, web: true, blurb: 'protocols.list — which protocols Lyra can READ vs EXECUTE on.' },
+  { name: 'defi.yields', make: makeDefiYields, web: true, blurb: 'defi.yields — best yields across Sui (DefiLlama), tagged executable / executeWith.' },
+  { name: 'deepbook.markets', make: makeDeepbookMarkets, web: true, blurb: 'deepbook.markets — DeepBook spot mid prices.' },
+  { name: 'cetus.quote', make: makeCetusQuote, web: false, blurb: 'cetus.quote — best swap route/price across DEXes (read-only aggregator).' },
+  { name: 'scallop.markets', make: makeScallopMarkets, web: true },
+  { name: 'scallop.position', make: makeScallopPosition, web: true },
+  { name: 'navi.markets', make: makeNaviMarkets, web: true },
+  { name: 'navi.position', make: makeNaviPosition, web: true },
+  { name: 'suilend.position', make: makeSuilendPosition, web: true },
+  { name: 'walrus.staking', make: makeWalrusStaking, web: true, blurb: "walrus.staking — the agent's WAL balance, StakedWal positions, and nodes to stake with." },
+
+  // Policy / transfer / swap
+  { name: 'policy.create', make: makePolicyCreate, web: false, blurb: 'policy.create — publish a shared on-chain AgentPolicy (arms enforcement + receipts).' },
+  { name: 'sui.send', make: makeSuiSend, web: false, blurb: 'sui.send — transfer SUI; blocked if out of policy, mints an on-chain receipt.' },
+  { name: 'swap', make: makeSwap, web: false, blurb: 'swap — best-route swap across the major Sui DEXes (7k aggregator).' },
+
+  // Lending
+  { name: 'scallop.supply', make: makeScallopSupply, web: true, blurb: 'Lending — scallop.supply/withdraw, navi.supply/withdraw/borrow/repay, suilend.supply/withdraw/borrow/repay.' },
+  { name: 'scallop.withdraw', make: makeScallopWithdraw, web: true },
+  { name: 'navi.supply', make: makeNaviSupply, web: true },
+  { name: 'navi.withdraw', make: makeNaviWithdraw, web: true },
+  { name: 'navi.borrow', make: makeNaviBorrow, web: true },
+  { name: 'navi.repay', make: makeNaviRepay, web: true },
+  { name: 'suilend.supply', make: makeSuilendSupply, web: true },
+  { name: 'suilend.withdraw', make: makeSuilendWithdraw, web: true },
+  { name: 'suilend.borrow', make: makeSuilendBorrow, web: true },
+  { name: 'suilend.repay', make: makeSuilendRepay, web: true },
+
+  // Staking
+  { name: 'sui.stake', make: makeStake, web: true, blurb: 'sui.stake / sui.unstake — native SUI staking to a validator (min 1 SUI).' },
+  { name: 'sui.unstake', make: makeUnstake, web: true },
+  { name: 'volo.stake', make: makeVoloStake, web: true, blurb: 'volo.stake / volo.unstake — liquid staking, SUI ↔ vSUI.' },
+  { name: 'volo.unstake', make: makeVoloUnstake, web: true },
+  { name: 'walrus.stake', make: makeWalrusStake, web: true, blurb: 'walrus.stake / walrus.unstake — stake WAL to a Walrus storage node (min 1 WAL; unstake returns WAL next epoch).' },
+  { name: 'walrus.unstake', make: makeWalrusUnstake, web: true },
+
+  // Storage
+  { name: 'walrus.store', make: makeWalrusStore, web: false, blurb: 'walrus.store — persist a receipt/report/memory artifact to Walrus.' },
+]
+
+/** Tool names exposed in the browser console's inline-execute set (derived). */
+export const WEB_TOOL_NAMES: string[] = TOOLS.filter(t => t.web).map(t => t.name)
+
+/** The capability inventory for the agent guidance (derived from the catalog). */
+export function capabilitySummary(): string {
+  return TOOLS.filter(t => t.blurb)
+    .map(t => `- ${t.blurb}`)
+    .join('\n')
+}

package/src/guidance.ts

@@ -1,55 +1,29 @@
 /**
- * System-prompt guidance injected when the onchain plugin is active. Tells the
- * brain what the Sui tools do and — critically — that the policy is enforced in
- * code and on-chain, not by the model.
+ * System-prompt guidance injected when the onchain plugin is active. The policy
+ * framing + rules are hand-written; the CAPABILITY LIST is generated from the tool
+ * catalog (see `./catalog`), so adding a tool there surfaces it to the model here
+ * automatically — no prose edit per integration.
  */
 
+import { capabilitySummary } from './catalog'
+
 export const ONCHAIN_GUIDANCE = `# Sui on-chain tools (Lyra)
 
 You operate a single Sui agent address. You can read and move funds ONLY through
 these tools; every value-moving action is checked by a deterministic policy in
 code AND re-enforced on-chain by the lyra::policy Move package. You cannot talk
-your way past a cap — if a transfer exceeds the per-tx cap or budget, the tool
+your way past a cap — if an action exceeds the per-tx cap or budget, the tool
 returns "policy blocked" before anything is signed.
 
-Read-only / discovery:
-- account.info — the agent's Sui address, network, balance, and active policy.
-- sui.balance — SUI and coin balances for the agent or any address.
-- policy.show — the active fund-control policy (caps, allowlists, expiry, tier).
-- protocols.list — which protocols Lyra can READ vs EXECUTE on.
-- defi.yields — best yields across ALL Sui protocols (DefiLlama). Each result is
-  tagged executable / executeWith.
-- deepbook.markets — DeepBook spot mid prices.
-- cetus.quote — best swap route/price across many DEXes (aggregator, read-only).
-- scallop.markets / scallop.position, navi.markets / navi.position,
-  suilend.position — lending rates + the agent's positions.
-- walrus.staking — the agent's WAL balance, current WAL staking positions
-  (StakedWal), and large Walrus storage nodes to stake with.
-
-Writes (policy-checked → simulated → executed):
-- policy.create — publish a shared on-chain AgentPolicy (budget, per-tx cap,
-  expiry). Do this first to arm on-chain enforcement + receipts.
-- sui.send — transfer SUI. Blocked if out of policy; mints an on-chain receipt.
-- swap — best-route swap across the major Sui DEXes (7k aggregator).
-- Lending: scallop.supply / scallop.withdraw, navi.supply / navi.withdraw /
-  navi.borrow / navi.repay, suilend.supply / suilend.withdraw / suilend.borrow /
-  suilend.repay — lend, redeem, borrow, and repay across the largest Sui markets.
-- Staking:
-  - sui.stake / sui.unstake — native SUI staking to a validator (min 1 SUI).
-  - volo.stake / volo.unstake — liquid staking, SUI ↔ vSUI.
-  - walrus.stake / walrus.unstake — stake WAL to a Walrus storage node to earn
-    rewards + secure decentralized storage (min 1 WAL; unstake returns WAL next
-    epoch). Use walrus.staking first to show the balance + available nodes.
-- walrus.store — persist a receipt/report/memory artifact to Walrus.
+Capabilities (each write runs policy-checked → simulated → executed):
+${capabilitySummary()}
 
 The capability boundary (important):
-- Discovery is broad; EXECUTION is bounded. Lyra can only act on the protocols in
-  protocols.list (lending on Scallop / NAVI / Suilend; SUI transfers + swaps;
-  native + Volo (liquid) SUI staking; WAL staking on Walrus; Walrus storage).
-- If the best yield a user wants is on a protocol Lyra has NOT integrated, DO NOT
-  invent a transaction. Say so honestly, then offer: (a) the best executable
-  alternative (e.g. supply on NAVI/Scallop), or (b) concise manual steps. The
-  policy's protocol-allowlist enforces this on-chain too.
+- Discovery is broad; EXECUTION is bounded to the protocols above (see
+  protocols.list). If the best yield/action a user wants is on a protocol Lyra has
+  NOT integrated, DO NOT invent a transaction. Say so honestly, then offer the best
+  executable alternative or concise manual steps. The policy's protocol-allowlist
+  enforces this on-chain too.
 
 Rules:
 - Call policy.show / protocols.list before claiming what you can spend or do.

package/src/index.ts

@@ -22,41 +22,10 @@
 // navi-sdk → axios → follow-redirects, which crashes Bun at import otherwise.
 import './capture-shim'
 import type { NativePlugin, ToolDef } from 'lyra-core'
-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,
-  makeNaviPosition,
-  makeNaviRepay,
-  makeNaviSupply,
-  makeNaviWithdraw,
-} from './tools/navi'
-import { makePolicyCreate, makePolicyShow } from './tools/policy'
-import { makeProtocolsList } from './tools/protocols'
-import {
-  makeScallopMarkets,
-  makeScallopPosition,
-  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 { makeWalrusStake, makeWalrusStaking, makeWalrusUnstake } from './tools/walrus-stake'
+import { TOOLS } from './catalog'
 import type { OnchainRuntimeContext } from './types'
 
+export { TOOLS, WEB_TOOL_NAMES, capabilitySummary, type CatalogEntry } from './catalog'
 export {
   makeSuiClient,
   keypairFromSecret,
@@ -98,45 +67,8 @@ const plugin: NativePlugin = {
     const onchain = (ctx as unknown as { onchain?: OnchainRuntimeContext }).onchain
     if (!onchain) return // soft-init for tests / non-onchain contexts
 
-    ctx.registerTool(makeAccountInfo(onchain) as ToolDef)
-    ctx.registerTool(makeSuiBalance(onchain) as ToolDef)
-    ctx.registerTool(makeSuiSend(onchain) as ToolDef)
-    ctx.registerTool(makeSwap(onchain) as ToolDef)
-    ctx.registerTool(makePolicyShow(onchain) as ToolDef)
-    ctx.registerTool(makePolicyCreate(onchain) as ToolDef)
-    ctx.registerTool(makeWalrusStore(onchain) as ToolDef)
-    ctx.registerTool(makeDeepbookMarkets(onchain) as ToolDef)
-
-    // Discovery + capability map.
-    ctx.registerTool(makeProtocolsList(onchain) as ToolDef)
-    ctx.registerTool(makeDefiYields(onchain) as ToolDef)
-    ctx.registerTool(makeCetusQuote(onchain) as ToolDef)
-
-    // Lending (the two largest Sui money markets).
-    ctx.registerTool(makeScallopMarkets(onchain) as ToolDef)
-    ctx.registerTool(makeScallopPosition(onchain) as ToolDef)
-    ctx.registerTool(makeScallopSupply(onchain) as ToolDef)
-    ctx.registerTool(makeScallopWithdraw(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)
-
-    // 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)
-    ctx.registerTool(makeWalrusStake(onchain) as ToolDef)
-    ctx.registerTool(makeWalrusUnstake(onchain) as ToolDef)
-    ctx.registerTool(makeWalrusStaking(onchain) as ToolDef)
+    // Every tool is declared once in the catalog; registration just iterates it.
+    for (const tool of TOOLS) ctx.registerTool(tool.make(onchain) as ToolDef)
   },
 }