lyra-plugin-onchain 0.1.0

package/src/tools/scallop.ts

@@ -0,0 +1,217 @@
+/**
+ * Scallop lending tools (supporting integration): markets + position (read) and
+ * SUI supply/withdraw (policy-gated writes).
+ *
+ * Scallop is an over-collateralized money market on Sui (mainnet-only SDK).
+ * Writes are SUI-denominated so the MIST policy cap applies directly, and they
+ * route through the same policy → simulate → execute pipeline as sui.send. The
+ * dry-run simulate is the safety net: a malformed or out-of-funds supply/
+ * withdraw is caught before broadcast.
+ */
+
+import { Scallop } from '@scallop-io/sui-scallop-sdk'
+import type { ToolDef } from 'lyra-core'
+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 : 'Scallop SDK supports mainnet only'
+}
+
+async function newScallop(ctx: OnchainRuntimeContext): Promise<Scallop> {
+  return new Scallop({ networkType: 'mainnet', walletAddress: ctx.agentAddress })
+}
+
+// --- scallop.markets -------------------------------------------------------
+
+const MarketsSchema = z.object({
+  coins: z
+    .string()
+    .optional()
+    .describe('Comma-separated coin names, e.g. "sui,usdc,usdt". Default sui,usdc,usdt.'),
+})
+type MarketsArgs = z.infer<typeof MarketsSchema>
+
+export function makeScallopMarkets(ctx: OnchainRuntimeContext): ToolDef<MarketsArgs> {
+  return {
+    name: 'scallop.markets',
+    description:
+      'Read Scallop lending markets on Sui: supply APY, borrow APY, and utilization per asset. Read-only discovery for where idle funds could earn yield.',
+    searchHint: 'scallop lending market supply apy borrow yield utilization rates earn',
+    schema: MarketsSchema,
+    handler: async args => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      try {
+        const sdk = await newScallop(ctx)
+        const q = await sdk.createScallopQuery()
+        await q.init()
+        const coins = args.coins
+          ?.split(',')
+          .map(s => s.trim())
+          .filter(Boolean) ?? ['sui', 'usdc', 'usdt']
+        const pools = await Promise.all(
+          coins.map(async coin => {
+            try {
+              const p = await q.getMarketPool(coin)
+              return {
+                coin,
+                supplyApy: p?.supplyApy ?? null,
+                borrowApy: p?.borrowApy ?? null,
+                utilization: p?.utilizationRate ?? null,
+              }
+            } catch (e) {
+              return { coin, error: (e as Error).message.slice(0, 100) }
+            }
+          }),
+        )
+        return { ok: true, data: { protocol: 'scallop', network: 'mainnet', pools } }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- scallop.position ------------------------------------------------------
+
+const PositionSchema = z.object({})
+type PositionArgs = z.infer<typeof PositionSchema>
+
+export function makeScallopPosition(ctx: OnchainRuntimeContext): ToolDef<PositionArgs> {
+  return {
+    name: 'scallop.position',
+    description:
+      "The agent's Scallop position: total supplied, collateral, debt, and per-asset lendings/borrowings. Read-only.",
+    searchHint: 'scallop position portfolio supplied collateral debt lending borrowing health',
+    schema: PositionSchema,
+    handler: async () => {
+      const err = ensureMainnet(ctx)
+      if (err) return { ok: false, error: err }
+      try {
+        const sdk = await newScallop(ctx)
+        const q = await sdk.createScallopQuery()
+        await q.init()
+        const p = await q.getUserPortfolio({ walletAddress: ctx.agentAddress })
+        return {
+          ok: true,
+          data: {
+            protocol: 'scallop',
+            totalSupplyValue: p?.totalSupplyValue ?? 0,
+            totalCollateralValue: p?.totalCollateralValue ?? 0,
+            totalDebtValue: p?.totalDebtValue ?? 0,
+            lendings: (p?.lendings ?? []).map(
+              (l: { coinName?: string; suppliedCoin?: number; suppliedValue?: number }) => ({
+                coin: l.coinName,
+                supplied: l.suppliedCoin,
+                value: l.suppliedValue,
+              }),
+            ),
+            borrowings: p?.borrowings ?? [],
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+// --- scallop.supply / scallop.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 runScallopWrite(
+  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}"` }
+
+  // Policy gate (deterministic). Supplying moves funds out; withdrawing back in.
+  if (ctx.policy && kind === 'supply') {
+    const verdict = evaluatePolicy(
+      { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'scallop' },
+      ctx.policy,
+    )
+    if (!verdict.allowed)
+      return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+  }
+
+  try {
+    const sdk = await newScallop(ctx)
+    const builder = await sdk.createScallopBuilder()
+    const tx = builder.createTxBlock()
+    tx.setSender(ctx.agentAddress)
+    // deposit/withdraw auto-select the user's coins and return the resulting
+    // coin to hand back to the owner. depositQuick's 3rd arg returnSCoin=false
+    // keeps the old market-coin standard, which withdrawQuick can redeem (the
+    // new sCoin standard is not found by withdrawQuick → "No valid coins").
+    const out =
+      kind === 'supply'
+        ? await tx.depositQuick(Number(amountMist), 'sui', false)
+        : await tx.withdrawQuick(Number(amountMist), 'sui')
+    if (out) tx.transferObjects([out], ctx.agentAddress)
+    const transaction = tx.txBlock
+
+    const sim = await simulate(ctx.client, transaction, 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,
+      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 the not-yet-indexed position.
+    await ctx.client.waitForTransaction({ digest: res.digest })
+    return {
+      ok: true,
+      data: {
+        protocol: 'scallop',
+        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 makeScallopSupply(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'scallop.supply',
+    description:
+      'Supply (deposit) idle SUI into Scallop to earn lending yield. Policy-checked, simulated, then executed.',
+    searchHint: 'scallop supply deposit lend sui earn yield idle',
+    schema: AmountSchema,
+    handler: async args => runScallopWrite(ctx, args.amount, 'supply'),
+  }
+}
+
+export function makeScallopWithdraw(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
+  return {
+    name: 'scallop.withdraw',
+    description: 'Withdraw supplied SUI from Scallop back to the agent. Simulated, then executed.',
+    searchHint: 'scallop withdraw redeem unlend remove sui',
+    schema: AmountSchema,
+    handler: async args => runScallopWrite(ctx, args.amount, 'withdraw'),
+  }
+}

package/src/tools/send.ts

@@ -0,0 +1,121 @@
+/**
+ * `sui.send` — transfer SUI through the full guarded pipeline:
+ *   policy → simulate → execute → on-chain lyra::policy receipt.
+ *
+ * The deterministic policy is checked in code BEFORE anything is built. When a
+ * shared AgentPolicy object is configured, the PTB also calls
+ * `lyra::policy::record_action`, so the SAME on-chain limits are re-enforced in
+ * Move and an ActionReceipt is minted atomically with the transfer.
+ */
+
+import { Transaction } from '@mysten/sui/transactions'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { evaluatePolicy, suiToMist } from '../policy'
+import { simulate } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+
+const SUI_TYPE = '0x2::sui::SUI'
+
+const Schema = z.object({
+  to: z.string().min(3).describe('Recipient Sui address (0x...).'),
+  amount: z.string().min(1).describe('Amount in SUI, e.g. "0.05".'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeSuiSend(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'sui.send',
+    description:
+      'Transfer SUI from the agent to a recipient. Deterministically policy-checked, dry-run simulated, then executed; mints an on-chain lyra::policy ActionReceipt when a policy object is configured.',
+    searchHint: 'send transfer sui pay native move funds remit',
+    schema: Schema,
+    handler: async args => {
+      try {
+        const to = args.to.trim()
+        if (!to.startsWith('0x')) {
+          return { ok: false, error: `invalid recipient "${to}": expected a 0x Sui address` }
+        }
+        const amountMist = suiToMist(args.amount)
+        if (amountMist === undefined || amountMist <= 0n) {
+          return { ok: false, error: `invalid amount "${args.amount}"` }
+        }
+
+        // 1. Policy gate (deterministic) — block before simulate/execute.
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            { kind: 'transfer', coinType: SUI_TYPE, amountMist, to, protocol: 'transfer' },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+
+        // 2. Build the PTB: split + transfer, plus on-chain receipt/enforcement.
+        const tx = new Transaction()
+        const [coin] = tx.splitCoins(tx.gas, [amountMist])
+        tx.transferObjects([coin], to)
+        const recordsOnChain = Boolean(ctx.packageId && ctx.policyObjectId)
+        if (recordsOnChain) {
+          tx.moveCall({
+            target: `${ctx.packageId}::policy::record_action`,
+            typeArguments: [SUI_TYPE],
+            arguments: [
+              tx.object(ctx.policyObjectId as string),
+              tx.pure.u64(amountMist),
+              tx.pure.address('0x0'),
+              tx.pure.vector('u8', Array.from(new TextEncoder().encode('transfer'))),
+              tx.pure.vector('u8', Array.from(new TextEncoder().encode(`to ${to}`))),
+              tx.object.clock(),
+            ],
+          })
+        }
+
+        // 3. Simulate-before-write.
+        const sim = await simulate(ctx.client, tx, ctx.agentAddress)
+        if (!sim.ok) {
+          return { ok: false, error: `pre-flight simulation failed: ${sim.reason}` }
+        }
+
+        // 4. Execute.
+        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'}`,
+          }
+        }
+        // Settle/index before returning so a follow-up balance read is accurate.
+        await ctx.client.waitForTransaction({ digest: res.digest })
+        const receipt = res.objectChanges?.find(
+          c =>
+            c.type === 'created' &&
+            String((c as { objectType?: string }).objectType).endsWith('::policy::ActionReceipt'),
+        ) as { objectId?: string } | undefined
+
+        return {
+          ok: true,
+          data: {
+            digest: res.digest,
+            recipient: to,
+            amountSui: args.amount,
+            amountMist: amountMist.toString(),
+            status: 'success',
+            // Decision receipt: proof this write was policy-checked + simulated.
+            simGasUsed: sim.gasUsed,
+            policyEnforced: ctx.policy != null,
+            onchainReceipt: recordsOnChain,
+            receiptId: receipt?.objectId ?? null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/swap.ts

@@ -0,0 +1,171 @@
+/**
+ * `swap` — execute a token swap on Sui via the 7k aggregator (best route across
+ * Cetus, FlowX, Bluefin, DeepBook, ...). Runs through the same policy → simulate
+ * → execute pipeline as every other write.
+ *
+ * Why 7k and not the Cetus aggregator directly: Cetus's aggregator SDK pins
+ * @mysten/sui v2 (incompatible with this stack's v1.45), and DeepBook's own
+ * swap needs DEEP for fees + a 1-SUI min lot. 7k (@7kprotocol/sdk-ts) is
+ * v1-compatible and routes across all of them, paying fees from the route.
+ */
+
+import { MetaAg } from '@7kprotocol/sdk-ts'
+import { Transaction, coinWithBalance } from '@mysten/sui/transactions'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import { evaluatePolicy } from '../policy'
+import { simulate } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+
+const SUI_TYPE = '0x2::sui::SUI'
+
+/** Symbol → mainnet coin type + decimals for the common assets. */
+const COINS: Record<string, { type: string; decimals: number }> = {
+  sui: { type: SUI_TYPE, decimals: 9 },
+  usdc: {
+    type: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+    decimals: 6,
+  },
+  deep: {
+    type: '0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP',
+    decimals: 6,
+  },
+  wal: {
+    type: '0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL',
+    decimals: 9,
+  },
+}
+
+function resolve(input: string): { type: string; decimals: number } {
+  const k = input.trim().toLowerCase()
+  return COINS[k] ?? { type: input.trim(), decimals: 9 }
+}
+
+const Schema = z.object({
+  from: z.string().min(1).describe('Input coin: symbol (sui, usdc, deep, wal) or full coin type.'),
+  to: z.string().min(1).describe('Output coin: symbol or full coin type.'),
+  amount: z.string().min(1).describe('Input amount in whole units of `from`, e.g. "1".'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeSwap(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'swap',
+    description:
+      'Swap one coin for another on Sui via the 7k aggregator (best route across Cetus/FlowX/Bluefin/DeepBook). Policy-checked → simulated → executed. Use for "swap 1 SUI to USDC", "trade X for Y".',
+    searchHint: 'swap exchange trade convert dex aggregator best route sui usdc buy sell',
+    schema: Schema,
+    handler: async args => {
+      if (ctx.network !== 'mainnet') return { ok: false, error: 'swap supports mainnet only' }
+      try {
+        const from = resolve(args.from)
+        const to = resolve(args.to)
+        if (from.type === to.type) return { ok: false, error: 'from and to are the same coin' }
+        const amountIn = BigInt(Math.round(Number(args.amount) * 10 ** from.decimals))
+        if (amountIn <= 0n) return { ok: false, error: `invalid amount "${args.amount}"` }
+
+        // Policy gate. The MIST per-tx cap is SUI-denominated, so it only bounds
+        // SUI-input swaps; the slippage/protocol/expiry checks always apply.
+        if (ctx.policy) {
+          const verdict = evaluatePolicy(
+            {
+              kind: 'swap',
+              coinType: from.type,
+              amountMist: from.type === SUI_TYPE ? amountIn : 0n,
+              toCoinType: to.type,
+              protocol: 'swap',
+              slippageBps: ctx.policy.maxSlippageBps,
+            },
+            ctx.policy,
+          )
+          if (!verdict.allowed)
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+        }
+
+        const me = ctx.agentAddress
+        const ag = new MetaAg({ slippageBps: ctx.policy?.maxSlippageBps ?? 100 })
+        // Quote without the SDK's internal pre-simulation (it throws on routes it
+        // can't simulate); we simulate the chosen route ourselves below.
+        const quotes = (
+          await ag.quote({
+            coinTypeIn: from.type,
+            coinTypeOut: to.type,
+            amountIn: amountIn.toString(),
+            signer: me,
+          })
+        )
+          .filter(Boolean)
+          .sort((a, b) => Number(b.amountOut ?? 0) - Number(a.amountOut ?? 0))
+        if (quotes.length === 0) return { ok: false, error: 'no swap route found' }
+
+        // Best-execution with reliability: try routes in output order, skipping
+        // any that fail simulation (some providers build PTBs that leave an
+        // unconsumed value / revert). Use the first that simulates cleanly.
+        let used: {
+          provider: string
+          amountOut: number
+          tx: Transaction
+          gasUsed?: string
+        } | null = null
+        const failures: string[] = []
+        for (const q of quotes) {
+          const tx = new Transaction()
+          tx.setSender(me)
+          tx.setGasBudget(150_000_000)
+          try {
+            const coinIn =
+              from.type === SUI_TYPE
+                ? tx.splitCoins(tx.gas, [amountIn])[0]
+                : coinWithBalance({ type: from.type, balance: amountIn })
+            const coinOut = await ag.swap({ quote: q, signer: me, tx, coinIn: coinIn as never })
+            tx.transferObjects([coinOut as never], me)
+            const sim = await simulate(ctx.client, tx, me)
+            if (sim.ok) {
+              used = {
+                provider: String(q.provider),
+                amountOut: Number(q.amountOut ?? 0),
+                tx,
+                gasUsed: sim.gasUsed,
+              }
+              break
+            }
+            failures.push(`${q.provider}: ${sim.reason}`)
+          } catch (e) {
+            failures.push(`${q.provider}: ${(e as Error).message.slice(0, 60)}`)
+          }
+        }
+        if (!used)
+          return { ok: false, error: `no route simulated cleanly — ${failures.join(' | ')}` }
+
+        const res = await ctx.client.signAndExecuteTransaction({
+          signer: ctx.keypair,
+          transaction: used.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: {
+            from: args.from,
+            to: args.to,
+            amountIn: args.amount,
+            amountOut: (used.amountOut / 10 ** to.decimals).toString(),
+            route: used.provider,
+            digest: res.digest,
+            simGasUsed: used.gasUsed,
+            policyEnforced: ctx.policy != null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/walrus.ts

@@ -0,0 +1,66 @@
+/**
+ * `walrus.store` — write a durable, verifiable artifact (receipt, report,
+ * memory snapshot) to Walrus and return its blobId.
+ *
+ * This is what makes a short-lived action auditable across sessions: the agent
+ * stores receipts and analysis on Walrus, and on-chain ActionReceipts can
+ * reference the blob. Storing costs WAL from the agent address.
+ */
+
+import { WalrusClient } from '@mysten/walrus'
+import type { ToolDef } from 'lyra-core'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+const Schema = z.object({
+  content: z.string().min(1).describe('The text/JSON artifact to store durably.'),
+  epochs: z
+    .number()
+    .int()
+    .min(1)
+    .max(53)
+    .optional()
+    .describe('Storage duration in Walrus epochs. Default 3.'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeWalrusStore(ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'walrus.store',
+    description:
+      'Store a durable, verifiable artifact (receipt, report, or memory) on Walrus. Returns a blobId you can cite later. Use to persist agent memory or an execution receipt across sessions.',
+    searchHint: 'walrus store blob save receipt memory durable artifact persist record',
+    schema: Schema,
+    handler: async args => {
+      try {
+        const walrus = new WalrusClient({
+          network: ctx.walrusNetwork ?? ctx.network,
+          // cast: @mysten/walrus bundles a different @mysten/sui minor; runtime-
+          // compatible (verified: real mainnet blob written) but not type-identical.
+          suiClient: ctx.client as never,
+        })
+        const blob = new TextEncoder().encode(args.content)
+        const result = await walrus.writeBlob({
+          blob,
+          deletable: false,
+          epochs: args.epochs ?? 3,
+          signer: ctx.keypair as never,
+        })
+        return {
+          ok: true,
+          data: {
+            blobId: result.blobId,
+            bytes: blob.length,
+            epochs: args.epochs ?? 3,
+            network: ctx.walrusNetwork ?? ctx.network,
+          },
+        }
+      } catch (e) {
+        return {
+          ok: false,
+          error: `walrus store failed (needs WAL for storage): ${(e as Error).message.slice(0, 200)}`,
+        }
+      }
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Public types for lyra-plugin-onchain. The runtime context is side-banded onto
+ * PluginContext under `.onchain` (the harness builds it; the plugin reads it via
+ * `(ctx as any).onchain`), keeping PluginContext free of plugin-specific fields.
+ */
+
+import type { SuiClient } from '@mysten/sui/client'
+import type { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import type { SuiNetwork } from './client'
+import type { SuiPolicy } from './policy'
+
+export interface OnchainRuntimeContext {
+  /** Sui JSON-RPC client for `network`. */
+  client: SuiClient
+  /** The agent signer (signs + pays gas). */
+  keypair: Ed25519Keypair
+  /** `keypair.toSuiAddress()`, cached. */
+  agentAddress: string
+  network: SuiNetwork
+  /** Deterministic fund-control policy. When set, every write is checked before simulate/execute. */
+  policy?: SuiPolicy
+  /** Deployed `lyra::policy` package id (for on-chain receipts + policy objects). */
+  packageId?: string
+  /** Shared `AgentPolicy` object id. When set, writes compose an on-chain receipt + enforcement. */
+  policyObjectId?: string
+  /** Walrus network for receipt/memory storage (defaults to `network`). */
+  walrusNetwork?: SuiNetwork
+  agentDir: string
+  /** Optional: brain provider/model, surfaced by account.info. */
+  brainProvider?: string | null
+  brainModel?: string | null
+}

package/src/vault.ts

@@ -0,0 +1,76 @@
+/**
+ * Resolve an owner's on-chain setup: their `AgentPolicy` (delegating to their
+ * derived agent) + the treasury `Vault` bound to it. The binding lives on-chain
+ * (owner holds the `PolicyOwnerCap` → policy → vault), so any surface resolves
+ * "this owner's agent + vault" without a database. Mirrors
+ * `apps/web/lib/vault.ts`.
+ */
+
+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'
+
+export interface OwnerVault {
+  policyId: string
+  vaultId: string
+  capId: string
+  agent: string
+  vaultMist: string
+}
+
+/** Find the owner's policy (delegating to their derived agent) + its SUI vault. */
+export async function resolveOwnerVault(
+  owner: string,
+  network: SuiNetwork = 'mainnet',
+  masterSecret?: string,
+): Promise<OwnerVault | null> {
+  const client = makeSuiClient(network)
+  const agent = deriveAgentAddress(owner, masterSecret)
+  const caps = await client
+    .getOwnedObjects({
+      owner,
+      filter: { StructType: `${ORIGINAL_PKG}::policy::PolicyOwnerCap` },
+      options: { showContent: true },
+    })
+    .catch(() => null)
+  if (!caps) return null
+
+  for (const c of caps.data) {
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic Move object fields
+    const policyId = (c.data?.content as any)?.fields?.policy_id as string | undefined
+    if (!policyId) continue
+    const pol = await client
+      .getObject({ id: policyId, options: { showContent: true } })
+      .catch(() => null)
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic Move object fields
+    const pf = (pol?.data?.content as any)?.fields
+    if (!pf || pf.agent !== agent || pf.revoked) continue
+
+    const ev = await client
+      .queryEvents({
+        query: { MoveEventType: `${VAULT_PKG}::vault::VaultOpened` },
+        limit: 100,
+        order: 'descending',
+      })
+      .catch(() => null)
+    // biome-ignore lint/suspicious/noExplicitAny: parsed Move event
+    const match = ev?.data.find(e => (e.parsedJson as any)?.policy_id === policyId)
+    // biome-ignore lint/suspicious/noExplicitAny: parsed Move event
+    const vaultId = (match?.parsedJson as any)?.vault_id as string | undefined
+    if (!vaultId) continue
+
+    const v = await client
+      .getObject({ id: vaultId, options: { showContent: true } })
+      .catch(() => null)
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic Move object fields
+    const vaultMist = String((v?.data?.content as any)?.fields?.balance ?? '0')
+    const capId = c.data?.objectId
+    if (!capId) continue
+    return { policyId, vaultId, capId, agent, vaultMist }
+  }
+  return null
+}