lyra-plugin-onchain 0.1.10 → 0.2.0

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,28 +1,46 @@
 {
   "name": "lyra-plugin-onchain",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "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", "ai", "agent", "sui", "defi", "deepbook", "walrus", "policy", "plugin"],
+  "keywords": [
+    "lyra",
+    "ai",
+    "agent",
+    "sui",
+    "defi",
+    "deepbook",
+    "walrus",
+    "policy",
+    "plugin"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "engines": {
     "bun": ">=1.1"
   },
-  "files": ["src", "!src/**/*.test.ts", "README.md"],
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./protocol-ids": "./src/protocol-ids.ts"
+  },
   "scripts": {
     "build": "tsc -b",
     "test": "bun test"
@@ -37,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.10",
+    "lyra-core": "^0.2.0",
     "navi-sdk": "^1.7.3",
     "zod": "^3.23.8"
   }

package/src/guidance.ts

@@ -21,20 +21,31 @@ Read-only / discovery:
   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.
+- 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.
-- scallop.supply / scallop.withdraw, navi.supply / navi.withdraw — lend or
-  redeem idle SUI on Scallop / NAVI (the two largest Sui money markets).
+- 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.
 
 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).
+  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

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
@@ -53,6 +54,7 @@ import {
 } 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'
 
 export {
@@ -132,6 +134,9 @@ const plugin: NativePlugin = {
     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)
   },
 }
 

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

@@ -124,7 +124,7 @@ export function makeSuiSend(ctx: OnchainRuntimeContext): ToolDef<Args> {
         const receipt = res.objectChanges?.find(
           c =>
             c.type === 'created' &&
-            String((c as { objectType?: string }).objectType).endsWith('::policy::ActionReceipt'),
+            String((c as { objectType?: string }).objectType).endsWith('::receipt::ActionReceipt'),
         ) as { objectId?: string } | undefined
 
         return {

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

package/src/vault.ts

@@ -9,10 +9,13 @@
 import { type SuiNetwork, makeSuiClient } from './client'
 import { deriveAgentAddress } from './derive'
 
-// A module keeps its DEFINING package id for types/events: `policy` shipped in
-// the original publish; `vault` was added in the first upgrade.
-const ORIGINAL_PKG = '0x250880a4c1a268da8011b164f599d4e100cefce84f862d36396cd1a943ee8a35'
-const VAULT_PKG = '0xa40689cc541f57af123e90819e73eab8a551e4385ab91bee89d02f6691590211'
+// Types/events are addressed by the id of the package that DEFINES them. The v1
+// package is a single fresh publish (policy, vault, receipt, allowlist, constants
+// all shipped together), so every module shares one id today. These stay separate
+// constants so a FUTURE upgrade can again split the LATEST (moveCall) id from a
+// module's DEFINING id without touching call sites.
+const ORIGINAL_PKG = '0x1925bced9aeb16ca8159be0a10d39a0778fe618404443a4b6149116ad9997617'
+const VAULT_PKG = '0x1925bced9aeb16ca8159be0a10d39a0778fe618404443a4b6149116ad9997617'
 
 export interface OwnerVault {
   policyId: string