lyra-plugin-onchain 0.1.11 → 0.2.1

package/README.md

@@ -1,26 +1,30 @@
 # lyra-plugin-onchain
 
-The **Sui limbs** for **lyra** — the brain tools that do real on-chain work,
-every value-moving call routed through the deterministic policy → simulation →
-approval pipeline:
+The **Sui limbs** for **lyra** — the tools that do real on-chain work. Every
+value-moving call is routed through the deterministic **policy → simulate →
+approve → execute** pipeline, and (when a vault is provisioned) sources funds from
+the on-chain `Vault` via `vault_spend`, so nothing moves outside the on-chain
+`lyra::policy` limits.
 
-- **Wallet / account** — `account.info`, `chain.balance`, `tokens.info`
-- **Transfers** — `chain.send`, `chain.wrap`, `chain.unwrap`
-- **Trading** — `swap.best` / `swap.compare` (**Cetus Finance** + **DeepBook**
-  best-execution), `swap.quote` / `swap.execute`, `moe.quote` / `moe.swap`
-- **Lending** — full **Scallop V3** suite: `scallop.markets` / `position` / `supply` /
-  `withdraw` / `borrow` / `repay`
-- **Discovery + risk** — `defi.yields` (DeFiLlama), `risk.token`, `nansen.labels`,
-  `cex.balance` (Bybit, read-only)
-- **Identity** — `identity.resolve` / `identity.register` (**lyra::policy** Trustless
-  Agents)
-- **Controls + analysis** — `policy.show`, `tx.simulate`, `chain.read` /
-  `chain.write`, `chain.tx` / `chain.contract` / `chain.activity`, `chain.block` /
-  `chain.gas`
+- **Wallet / reads** — `account.info`, `sui.balance`
+- **Transfers** — `sui.send` (recipient-allowlist aware)
+- **Swaps** — `swap` (7k aggregator best-route across Cetus / Turbos / FlowX /
+  Bluefin / Aftermath / Momentum / Kriya / DeepBook), `cetus.quote`
+- **Lending** — `scallop.*` (markets / position / supply / withdraw),
+  `navi.*` (markets / position / supply / withdraw / borrow / repay),
+  `suilend.*` (position / supply / withdraw / borrow / repay)
+- **Staking** — `sui.stake` / `sui.unstake` (native delegation), `volo.stake` /
+  `volo.unstake` (liquid staking → vSUI)
+- **Discovery** — `defi.yields` (DeFiLlama), `deepbook.markets`, `protocols.list`
+  (the honest read-vs-execute capability map)
+- **Storage** — `walrus.store` (durable, verifiable receipts/memory on Walrus)
+- **Policy** — `policy.create` (provision an `AgentPolicy` + `Vault`), `policy.show`
 
 ## Install
 
 Auto-installed with [`lyra-ai-agent`](https://www.npmjs.com/package/lyra-ai-agent).
 Or directly: `bun add lyra-plugin-onchain`.
 
-See the [root README](https://github.com/rifkyeasy/lyra#readme) for the full tool reference.
+The on-chain package it targets lives in
+[`lyraai-protocol/contracts`](https://github.com/lyraai-protocol/contracts). See the
+[root README](https://github.com/lyraai-protocol/lyra#readme) for the full architecture.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "lyra-plugin-onchain",
-  "version": "0.1.11",
+  "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",
-  "homepage": "https://github.com/rifkyeasy/lyra",
+  "homepage": "https://github.com/lyraai-protocol/lyra",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rifkyeasy/lyra.git",
+    "url": "git+https://github.com/lyraai-protocol/lyra.git",
     "directory": "packages/plugin-onchain"
   },
   "bugs": {
-    "url": "https://github.com/rifkyeasy/lyra/issues"
+    "url": "https://github.com/lyraai-protocol/lyra/issues"
   },
   "keywords": [
     "lyra",
@@ -37,6 +37,10 @@
   ],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./protocol-ids": "./src/protocol-ids.ts"
+  },
   "scripts": {
     "build": "tsc -b",
     "test": "bun test"
@@ -51,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.1.11",
+    "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,44 +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 — lending
-  rates + the agent's positions.
-
-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.
-- scallop.supply / scallop.withdraw, navi.supply / navi.withdraw — lend or
-  redeem idle SUI on Scallop / NAVI (the two largest Sui money markets).
-- 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 (currently Scallop + NAVI lending, Sui transfers, Walrus).
-- 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

@@ -7,6 +7,7 @@
  *   Transfers:   sui.send            (policy → simulate → execute → on-chain receipt)
  *   Policy:      policy.show, policy.create   (lyra::policy AgentPolicy)
  *   Storage:     walrus.store        (durable, verifiable receipts/memory)
+ *   WAL staking: walrus.stake, walrus.unstake, walrus.staking  (Walrus storage nodes)
  *   Markets:     deepbook.markets    (DeepBook spot mid prices, read-only)
  *
  * Value-moving tools run through policy → simulate → (approval) → execute, and
@@ -21,40 +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 { TOOLS } from './catalog'
 import type { OnchainRuntimeContext } from './types'
 
+export { TOOLS, WEB_TOOL_NAMES, capabilitySummary, type CatalogEntry } from './catalog'
 export {
   makeSuiClient,
   keypairFromSecret,
@@ -96,42 +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)
+    // Every tool is declared once in the catalog; registration just iterates it.
+    for (const tool of TOOLS) ctx.registerTool(tool.make(onchain) as ToolDef)
   },
 }
 

package/src/protocol-ids.ts

@@ -1,48 +1,70 @@
 /**
- * Canonical on-chain protocol ids for the policy's protocol allowlist.
+ * Canonical on-chain protocol registry — the SINGLE SOURCE OF TRUTH for the
+ * policy's protocol allowlist, shared by the tools (which tag a vault_spend with a
+ * protocol id), the console UI (which lets the owner toggle each one), and the
+ * landing. Adding a protocol is ONE entry in `REGISTRY` below — `PROTOCOL_IDS`,
+ * `PROTOCOL_LABELS`, and `ALLOWLISTABLE_PROTOCOLS` are all derived from it, and the
+ * web + landing import `ALLOWLISTABLE_PROTOCOLS` from here (via the package's
+ * `./protocol-ids` subpath) instead of maintaining their own copies.
  *
- * When a tool draws from the vault via `vault_spend`, it tags the action with the
- * protocol's package id. The owner's `allowed_protocols` allowlist (settable via
- * `lyra::policy::set_allowed_protocols`) is checked against this tag on-chain — so
- * an owner can restrict the agent to, say, only staking + NAVI. These ids are the
- * SINGLE SOURCE OF TRUTH shared by the tools (which tag) and the console UI (which
- * lets the owner toggle) so the two never drift.
- *
- * They are STABLE labels: a protocol upgrading its package doesn't change the tag
+ * The ids are STABLE labels: a protocol upgrading its package doesn't change the tag
  * (the tag is a self-reported label for the allowlist, not the call target), so an
  * owner's allowlist keeps working across protocol upgrades. Sourced from each
  * protocol's SDK on mainnet.
  *
+ * This file is a dependency-free leaf so the browser can import it safely.
+ *
  * `0x0` is the reserved "no specific protocol" tag used by transfers + swaps —
  * always allowed by the policy (they're bounded by budget/cap/coin/recipient/
  * slippage instead), so restricting protocols never blocks a plain transfer/swap.
  */
 export const NO_PROTOCOL = '0x0'
 
-export const PROTOCOL_IDS = {
-  suiStaking: '0x3',
-  navi: '0x1e4a13a0494d5facdbe8473e74127b838c2d446ecec0ce262e2eddafa77259cb',
-  suilend: '0xf95b06141ed4a174f239417323bde3f209b972f5930d8521ea38a52aff3a6ddf',
-  volo: '0x68d22cf8bdbcd11ecba1e094922873e4080d4d11133e2443fddda0bfd11dae20',
-  scallop: '0xde5c09ad171544aa3724dc67216668c80e754860f419136a68d78504eb2e2805',
-} as const
+/** The one place a protocol is declared. Everything below is derived. */
+const REGISTRY = [
+  { key: 'suiStaking', id: '0x3', label: 'Sui staking' },
+  {
+    key: 'navi',
+    id: '0x1e4a13a0494d5facdbe8473e74127b838c2d446ecec0ce262e2eddafa77259cb',
+    label: 'NAVI',
+  },
+  {
+    key: 'suilend',
+    id: '0xf95b06141ed4a174f239417323bde3f209b972f5930d8521ea38a52aff3a6ddf',
+    label: 'Suilend',
+  },
+  {
+    key: 'volo',
+    id: '0x68d22cf8bdbcd11ecba1e094922873e4080d4d11133e2443fddda0bfd11dae20',
+    label: 'Volo (vSUI)',
+  },
+  {
+    key: 'scallop',
+    id: '0xde5c09ad171544aa3724dc67216668c80e754860f419136a68d78504eb2e2805',
+    label: 'Scallop',
+  },
+  // The type-defining (original) Walrus package — where `StakedWal` lives — as the
+  // stable tag for WAL staking (survives Walrus package upgrades).
+  {
+    key: 'walrusStaking',
+    id: '0xfdc88f7d7cf30afab2f82e8380d11ee8f70efb90e863d1de8616fae1bb09ea77',
+    label: 'Walrus staking',
+  },
+] as const
+
+export type ProtocolKey = (typeof REGISTRY)[number]['key']
 
-export type ProtocolKey = keyof typeof PROTOCOL_IDS
+/** `key → package id`, for the tools that tag a vault_spend. */
+export const PROTOCOL_IDS = Object.fromEntries(REGISTRY.map(p => [p.key, p.id])) as Record<
+  ProtocolKey,
+  string
+>
 
-/** Human labels for each allowlistable protocol (for the owner UI + receipts). */
-export const PROTOCOL_LABELS: Record<string, string> = {
-  [PROTOCOL_IDS.suiStaking]: 'Sui staking',
-  [PROTOCOL_IDS.navi]: 'NAVI',
-  [PROTOCOL_IDS.suilend]: 'Suilend',
-  [PROTOCOL_IDS.volo]: 'Volo (vSUI)',
-  [PROTOCOL_IDS.scallop]: 'Scallop',
-}
+/** `package id → human label`, for the owner UI + receipts. */
+export const PROTOCOL_LABELS: Record<string, string> = Object.fromEntries(
+  REGISTRY.map(p => [p.id, p.label]),
+)
 
 /** The allowlistable protocols in display order, for building the owner UI. */
-export const ALLOWLISTABLE_PROTOCOLS: { key: ProtocolKey; id: string; label: string }[] = [
-  { key: 'suiStaking', id: PROTOCOL_IDS.suiStaking, label: 'Sui staking' },
-  { key: 'navi', id: PROTOCOL_IDS.navi, label: 'NAVI' },
-  { key: 'suilend', id: PROTOCOL_IDS.suilend, label: 'Suilend' },
-  { key: 'volo', id: PROTOCOL_IDS.volo, label: 'Volo (vSUI)' },
-  { key: 'scallop', id: PROTOCOL_IDS.scallop, label: 'Scallop' },
-]
+export const ALLOWLISTABLE_PROTOCOLS: { key: ProtocolKey; id: string; label: string }[] =
+  REGISTRY.map(p => ({ key: p.key, id: p.id, label: p.label }))

package/src/protocols.ts

@@ -35,6 +35,15 @@ export const PROTOCOLS: ProtocolCapability[] = [
     execute: true,
     tools: ['walrus.store'],
   },
+  {
+    id: 'walrus-staking',
+    name: 'Walrus staking',
+    category: 'staking',
+    read: true,
+    execute: true,
+    tools: ['walrus.stake', 'walrus.unstake', 'walrus.staking'],
+    note: 'stake WAL to a Walrus storage node to earn rewards + secure decentralized storage (min 1 WAL)',
+  },
   {
     id: 'deepbook',
     name: 'DeepBook',

package/src/tools/walrus-stake.ts

@@ -0,0 +1,326 @@
+/**
+ * Walrus (WAL) staking — delegate WAL to a Walrus storage node's staking pool to
+ * earn rewards + help secure the storage network. This is the integration behind
+ * https://stake-wal.wal.app, exposed to the agent:
+ *
+ *   walrus.stake    → <walrus>::staking::stake_with_pool        → StakedWal
+ *   walrus.unstake  → <walrus>::staking::request_withdraw_stake (returns WAL next epoch)
+ *   walrus.staking  → read: WAL balance, StakedWal positions, top nodes
+ *
+ * Same guarded pipeline as the other write tools: minimum-amount guard →
+ * deterministic off-chain policy → dry-run simulate → execute → on-chain effects
+ * check. WAL is drawn from the agent's WAL balance (not the SUI vault — the vault
+ * is SUI-typed), so the on-chain SUI budget doesn't apply; the action is bounded
+ * by the `walrus` protocol allowlist and audited by the on-chain StakedWal object.
+ */
+
+import { Transaction } from '@mysten/sui/transactions'
+import {
+  MAINNET_WALRUS_PACKAGE_CONFIG,
+  TESTNET_WALRUS_PACKAGE_CONFIG,
+  WalrusClient,
+} from '@mysten/walrus'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { evaluatePolicy, suiToMist } from '../policy'
+import { simulate } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+
+// WAL has 9 decimals (like SUI). Walrus rejects a pool contribution below its
+// minimum stake (staked_wal::mint aborts with code 7 for a too-small stake) — the
+// on-chain floor is 1 WAL, so reject anything smaller early with a clear message.
+const MIN_WAL_FROST = 1_000_000_000n // 1 WAL (Walrus minimum stake)
+const STAKED_WAL_SUFFIX = '::staked_wal::StakedWal'
+
+const WAL_TYPE: Record<string, string> = {
+  mainnet: '0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL',
+}
+
+function fmtWal(frost: bigint): string {
+  return (Number(frost) / 1e9).toString()
+}
+
+interface WalrusStaking {
+  pkg: string // walrus package (moveCall target; resolved live so upgrades are safe)
+  stakingId: string // the shared Staking system object
+  walType: string
+  walrus: WalrusClient
+}
+
+/** Resolve the live Walrus staking objects + WAL coin type for the network. */
+async function resolveWalrus(ctx: OnchainRuntimeContext): Promise<WalrusStaking> {
+  const network = ctx.walrusNetwork ?? ctx.network
+  const walrus = new WalrusClient({
+    network,
+    // cast: @mysten/walrus bundles a different @mysten/sui minor; runtime-compatible.
+    suiClient: ctx.client as never,
+  })
+  const stakingObj = await walrus.stakingObject()
+  const cfg = network === 'testnet' ? TESTNET_WALRUS_PACKAGE_CONFIG : MAINNET_WALRUS_PACKAGE_CONFIG
+  let walType = WAL_TYPE[network]
+  if (!walType) {
+    // Non-mainnet: discover the WAL type from the agent's own balances.
+    const balances = await ctx.client.getAllBalances({ owner: ctx.agentAddress })
+    walType = balances.find(b => b.coinType.endsWith('::wal::WAL'))?.coinType ?? ''
+    if (!walType) throw new Error(`could not resolve the WAL coin type on ${network}`)
+  }
+  return { pkg: stakingObj.package_id, stakingId: cfg.stakingPoolId, walType, walrus }
+}
+
+/** Pick a storage node to stake with: match `want` by node id, else the node with
+ *  the most stake weight (a large, reliable committee member). */
+async function resolveNode(
+  walrus: WalrusClient,
+  want?: string,
+): Promise<{ nodeId: string; weight: number } | null> {
+  const state = await walrus.systemState()
+  const members = state.committee.members
+  if (members.length === 0) return null
+  if (want?.trim()) {
+    const w = want.trim().toLowerCase()
+    const m = members.find(x => String(x.node_id).toLowerCase() === w)
+    if (m) return { nodeId: m.node_id, weight: m.weight }
+    if (w.startsWith('0x')) return { nodeId: want.trim(), weight: 0 }
+    return null
+  }
+  const best = members.reduce((a, b) => (Number(b.weight) > Number(a.weight) ? b : a))
+  return { nodeId: best.node_id, weight: best.weight }
+}
+
+// ─────────────────────────── walrus.stake ───────────────────────────
+
+const StakeSchema = z.object({
+  amount: z.string().min(1).describe('Amount of WAL to stake (minimum 1 WAL).'),
+  node: z
+    .string()
+    .optional()
+    .describe('Storage node id (0x…) to stake with. Optional — defaults to a large active node.'),
+})
+type StakeArgs = z.infer<typeof StakeSchema>
+
+export function makeWalrusStake(ctx: OnchainRuntimeContext): ToolDef<StakeArgs> {
+  return {
+    name: 'walrus.stake',
+    description:
+      'Stake WAL to a Walrus storage node to earn staking rewards and help secure decentralized storage. Minimum 1 WAL. Policy-checked → simulated → executed; returns a StakedWal object.',
+    searchHint: 'walrus stake WAL storage node delegate earn rewards staking wal.app',
+    schema: StakeSchema,
+    handler: async args => {
+      try {
+        const frost = suiToMist(args.amount) // WAL shares SUI's 9-decimal scaling
+        if (frost === undefined || frost <= 0n) {
+          return { ok: false, error: `invalid amount "${args.amount}"` }
+        }
+        if (frost < MIN_WAL_FROST) {
+          return {
+            ok: false,
+            error: `amount too small: ${fmtWal(frost)} WAL is below the ${fmtWal(MIN_WAL_FROST)} WAL minimum for staking`,
+          }
+        }
+
+        const { pkg, stakingId, walType, walrus } = await resolveWalrus(ctx)
+
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            { kind: 'transfer', coinType: walType, amountMist: frost, protocol: 'walrus' },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+
+        const bal = await ctx.client.getBalance({ owner: ctx.agentAddress, coinType: walType })
+        if (BigInt(bal.totalBalance) < frost) {
+          return {
+            ok: false,
+            error: `insufficient WAL: have ${fmtWal(BigInt(bal.totalBalance))}, need ${fmtWal(frost)}`,
+          }
+        }
+
+        const node = await resolveNode(walrus, args.node)
+        if (!node) return { ok: false, error: 'no active Walrus storage node found to stake with' }
+
+        const coins = await ctx.client.getCoins({ owner: ctx.agentAddress, coinType: walType })
+        const [firstCoin, ...restCoins] = coins.data
+        if (!firstCoin) return { ok: false, error: 'no WAL coins in the agent wallet' }
+
+        const tx = new Transaction()
+        const primary = tx.object(firstCoin.coinObjectId)
+        if (restCoins.length > 0) {
+          tx.mergeCoins(
+            primary,
+            restCoins.map(c => tx.object(c.coinObjectId)),
+          )
+        }
+        const [toStake] = tx.splitCoins(primary, [tx.pure.u64(frost)])
+        const staked = tx.moveCall({
+          target: `${pkg}::staking::stake_with_pool`,
+          arguments: [tx.object(stakingId), toStake, tx.pure.id(node.nodeId)],
+        })
+        tx.transferObjects([staked], 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, showObjectChanges: 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 })
+        const stakedWal = res.objectChanges?.find(
+          c =>
+            c.type === 'created' &&
+            String((c as { objectType?: string }).objectType).endsWith(STAKED_WAL_SUFFIX),
+        ) as { objectId?: string } | undefined
+
+        return {
+          ok: true,
+          data: {
+            protocol: 'walrus-staking',
+            action: 'stake',
+            amountWal: args.amount,
+            node: node.nodeId,
+            digest: res.digest,
+            stakedWalId: stakedWal?.objectId ?? null,
+            status: 'success',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// ─────────────────────────── walrus.unstake ───────────────────────────
+
+const UnstakeSchema = z.object({
+  stakedWalId: z
+    .string()
+    .optional()
+    .describe('StakedWal object id to withdraw. Optional — defaults to the first staked position.'),
+})
+type UnstakeArgs = z.infer<typeof UnstakeSchema>
+
+export function makeWalrusUnstake(ctx: OnchainRuntimeContext): ToolDef<UnstakeArgs> {
+  return {
+    name: 'walrus.unstake',
+    description:
+      'Request to withdraw staked WAL from a Walrus node. The principal + rewards become withdrawable after the next epoch. Uses a StakedWal object id, or the first staked position if omitted.',
+    searchHint: 'walrus unstake withdraw WAL staking redeem claim rewards storage node',
+    schema: UnstakeSchema,
+    handler: async args => {
+      try {
+        const { pkg, stakingId, walType } = await resolveWalrus(ctx)
+
+        let stakedId = args.stakedWalId?.trim()
+        if (!stakedId) {
+          const owned = await ctx.client.getOwnedObjects({
+            owner: ctx.agentAddress,
+            filter: { StructType: `${walType.split('::')[0]}${STAKED_WAL_SUFFIX}` },
+          })
+          stakedId = owned.data[0]?.data?.objectId
+          if (!stakedId) return { ok: false, error: 'no StakedWal position found to unstake' }
+        }
+
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            { kind: 'transfer', coinType: walType, amountMist: 0n, protocol: 'walrus' },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+
+        const tx = new Transaction()
+        tx.moveCall({
+          target: `${pkg}::staking::request_withdraw_stake`,
+          arguments: [tx.object(stakingId), tx.object(stakedId)],
+        })
+
+        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: 'walrus-staking',
+            action: 'unstake',
+            stakedWalId: stakedId,
+            digest: res.digest,
+            note: 'WAL becomes withdrawable after the next Walrus epoch',
+            status: 'success',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// ─────────────────────────── walrus.staking (read) ───────────────────────────
+
+const ReadSchema = z.object({})
+type ReadArgs = z.infer<typeof ReadSchema>
+
+export function makeWalrusStaking(ctx: OnchainRuntimeContext): ToolDef<ReadArgs> {
+  return {
+    name: 'walrus.staking',
+    description:
+      "Read the agent's Walrus staking position: WAL balance, current StakedWal positions, and a few large storage nodes to stake with.",
+    searchHint: 'walrus staking position WAL balance staked nodes committee read status',
+    schema: ReadSchema,
+    handler: async () => {
+      try {
+        const { walType, walrus } = await resolveWalrus(ctx)
+        const [bal, owned, state] = await Promise.all([
+          ctx.client.getBalance({ owner: ctx.agentAddress, coinType: walType }),
+          ctx.client.getOwnedObjects({
+            owner: ctx.agentAddress,
+            filter: { StructType: `${walType.split('::')[0]}${STAKED_WAL_SUFFIX}` },
+            options: { showType: true },
+          }),
+          walrus.systemState(),
+        ])
+        const topNodes = [...state.committee.members]
+          .sort((a, b) => Number(b.weight) - Number(a.weight))
+          .slice(0, 5)
+          .map(m => ({ nodeId: m.node_id, weight: m.weight }))
+        return {
+          ok: true,
+          data: {
+            walBalance: fmtWal(BigInt(bal.totalBalance)),
+            stakedPositions: owned.data.map(o => o.data?.objectId).filter(Boolean),
+            committeeSize: state.committee.members.length,
+            topNodes,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}