lyra-plugin-onchain 0.1.8 → 0.1.10

package/package.json

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

package/src/client.ts

@@ -11,14 +11,23 @@ import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
 
 export type SuiNetwork = 'testnet' | 'mainnet'
 
-/** Canonical fullnode JSON-RPC URL for a network. */
+/**
+ * Fullnode JSON-RPC URL for a network. `LYRA_RPC_URL` overrides the default
+ * public endpoint — recommended in production: the public `fullnode.mainnet.
+ * sui.io` is load-balanced across replicas at different checkpoint heights, so
+ * a freshly-created object (e.g. a just-opened lending obligation) can flicker
+ * in and out between calls. A single dedicated node gives read-your-writes
+ * consistency. The override applies to mainnet only (testnet keeps its default).
+ */
 export function suiRpcUrl(network: SuiNetwork): string {
+  const override = process.env.LYRA_RPC_URL?.trim()
+  if (network === 'mainnet' && override) return override
   return getFullnodeUrl(network)
 }
 
-/** A Sui JSON-RPC client for the given network. */
+/** A Sui JSON-RPC client for the given network (honours `LYRA_RPC_URL`). */
 export function makeSuiClient(network: SuiNetwork): SuiClient {
-  return new SuiClient({ url: getFullnodeUrl(network) })
+  return new SuiClient({ url: suiRpcUrl(network) })
 }
 
 /**

package/src/index.ts

@@ -37,10 +37,8 @@ import {
 import { makePolicyCreate, makePolicyShow } from './tools/policy'
 import { makeProtocolsList } from './tools/protocols'
 import {
-  makeScallopBorrow,
   makeScallopMarkets,
   makeScallopPosition,
-  makeScallopRepay,
   makeScallopSupply,
   makeScallopWithdraw,
 } from './tools/scallop'
@@ -76,9 +74,21 @@ export {
 } from './policy'
 export { policyRequiresApprovalForCall } from './approval'
 export { deriveAgentKeypair, deriveAgentAddress } from './derive'
-export { resolveOwnerVault, type OwnerVault } from './vault'
+export {
+  resolveOwnerVault,
+  resolveVaultForAgent,
+  type OwnerVault,
+  type AgentVault,
+} from './vault'
 export { ONCHAIN_GUIDANCE } from './guidance'
 export type { OnchainRuntimeContext } from './types'
+export {
+  PROTOCOL_IDS,
+  PROTOCOL_LABELS,
+  ALLOWLISTABLE_PROTOCOLS,
+  NO_PROTOCOL,
+  type ProtocolKey,
+} from './protocol-ids'
 
 const plugin: NativePlugin = {
   name: 'onchain',
@@ -105,8 +115,6 @@ const plugin: NativePlugin = {
     ctx.registerTool(makeScallopPosition(onchain) as ToolDef)
     ctx.registerTool(makeScallopSupply(onchain) as ToolDef)
     ctx.registerTool(makeScallopWithdraw(onchain) as ToolDef)
-    ctx.registerTool(makeScallopBorrow(onchain) as ToolDef)
-    ctx.registerTool(makeScallopRepay(onchain) as ToolDef)
     ctx.registerTool(makeNaviMarkets(onchain) as ToolDef)
     ctx.registerTool(makeNaviPosition(onchain) as ToolDef)
     ctx.registerTool(makeNaviSupply(onchain) as ToolDef)

package/src/protocol-ids.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical on-chain protocol ids for the policy's protocol allowlist.
+ *
+ * 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 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.
+ *
+ * `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
+
+export type ProtocolKey = keyof typeof PROTOCOL_IDS
+
+/** 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',
+}
+
+/** 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' },
+]

package/src/protocols.ts

@@ -51,16 +51,9 @@ export const PROTOCOLS: ProtocolCapability[] = [
     category: 'lending',
     read: true,
     execute: true,
-    tools: [
-      'scallop.markets',
-      'scallop.position',
-      'scallop.supply',
-      'scallop.withdraw',
-      'scallop.borrow',
-      'scallop.repay',
-    ],
+    tools: ['scallop.markets', 'scallop.position', 'scallop.supply', 'scallop.withdraw'],
     llamaProjects: ['scallop-lending', 'scallop'],
-    note: 'full supply / withdraw / borrow / repay',
+    note: 'supply / withdraw lending yield (borrow/repay via NAVI or Suilend)',
   },
   {
     id: 'navi',

package/src/tools/liquid-stake.ts

@@ -16,8 +16,10 @@ import { stakeTovSuiPTB, unstakeTovSui } from 'navi-sdk'
 import { z } from 'zod'
 import { checkMinimum } from '../minimums'
 import { evaluatePolicy, suiToMist } from '../policy'
+import { PROTOCOL_IDS } from '../protocol-ids'
 import { simulate } from '../simulate'
 import type { OnchainRuntimeContext } from '../types'
+import { fundSui } from '../vault-fund'
 
 const SUI_TYPE = '0x2::sui::SUI'
 const VSUI_TYPE = '0x549e8b69270defbfafd4f94e17ec44cdbdd99820b33bda2278dea3b9a32d3f55::cert::CERT'
@@ -61,7 +63,12 @@ export function makeVoloStake(ctx: OnchainRuntimeContext): ToolDef<StakeArgs> {
         }
 
         const tx = new Transaction()
-        const [suiCoin] = tx.splitCoins(tx.gas, [amountMist])
+        // Source the stake from the treasury vault (policy-enforced) when wired.
+        const suiCoin = fundSui(tx, ctx, amountMist, {
+          protocol: PROTOCOL_IDS.volo,
+          kind: 'stake',
+          memo: 'volo liquid stake',
+        })
         const vsui = await stakeTovSuiPTB(tx as never, suiCoin as never)
         tx.transferObjects([vsui as never], ctx.agentAddress)
 

package/src/tools/navi.ts

@@ -14,8 +14,10 @@ import { NAVISDKClient, borrowCoin, depositCoin, pool, repayDebt, withdrawCoin }
 import { z } from 'zod'
 import { checkMinimum } from '../minimums'
 import { evaluatePolicy, suiToMist } from '../policy'
+import { PROTOCOL_IDS } from '../protocol-ids'
 import { simulate } from '../simulate'
 import type { OnchainRuntimeContext } from '../types'
+import { fundSui, returnSuiToVault } from '../vault-fund'
 
 const SUI_TYPE = '0x2::sui::SUI'
 
@@ -142,20 +144,33 @@ async function runNaviWrite(
     const tx = new Transaction()
     const suiPool = (pool as Record<string, unknown>).Sui
     if (kind === 'supply') {
-      const [coin] = tx.splitCoins(tx.gas, [amountMist])
+      // Source the supply from the treasury vault (policy-enforced) when wired.
+      const coin = fundSui(tx, ctx, amountMist, {
+        protocol: PROTOCOL_IDS.navi,
+        kind: 'supply',
+        memo: 'navi supply',
+      })
       await depositCoin(tx as never, suiPool as never, coin as never, Number(amountMist))
     } else if (kind === 'withdraw') {
       // navi-sdk's withdrawCoin already wraps the withdrawn Balance into a Coin
-      // (via coin::from_balance) and returns [coin]; destructure and transfer it.
+      // (via coin::from_balance) and returns [coin]. Option 1: cycle it back into
+      // the vault (treasury stays intact); fall back to the agent when no vault.
       const [coin] = await withdrawCoin(tx as never, suiPool as never, Number(amountMist))
-      tx.transferObjects([coin as never], ctx.agentAddress)
+      if (!returnSuiToVault(tx, ctx, coin as never))
+        tx.transferObjects([coin as never], ctx.agentAddress)
     } else if (kind === 'borrow') {
-      // Borrow against supplied collateral; hand the borrowed coin to the agent.
+      // Borrow against supplied collateral; park the borrowed SUI in the vault
+      // (spendable under policy) when wired, else hand it to the agent.
       const [coin] = await borrowCoin(tx as never, suiPool as never, Number(amountMist))
-      tx.transferObjects([coin as never], ctx.agentAddress)
+      if (!returnSuiToVault(tx, ctx, coin as never))
+        tx.transferObjects([coin as never], ctx.agentAddress)
     } else {
-      // repay: split the repayment from gas and pay down the debt.
-      const [coin] = tx.splitCoins(tx.gas, [amountMist])
+      // repay: draw the repayment from the vault (policy-enforced) and pay the debt.
+      const coin = fundSui(tx, ctx, amountMist, {
+        protocol: PROTOCOL_IDS.navi,
+        kind: 'repay',
+        memo: 'navi repay',
+      })
       await repayDebt(tx as never, suiPool as never, coin as never, Number(amountMist))
     }
 

package/src/tools/scallop.ts

@@ -14,8 +14,10 @@ import type { ToolDef } from 'lyra-core'
 import { z } from 'zod'
 import { checkMinimum } from '../minimums'
 import { evaluatePolicy, suiToMist } from '../policy'
+import { PROTOCOL_IDS } from '../protocol-ids'
 import { simulate } from '../simulate'
 import type { OnchainRuntimeContext } from '../types'
+import { fundSui, returnSuiToVault } from '../vault-fund'
 
 const SUI_TYPE = '0x2::sui::SUI'
 
@@ -129,32 +131,30 @@ const AmountSchema = z.object({
 })
 type AmountArgs = z.infer<typeof AmountSchema>
 
+// Scallop redeems a MARKET-COIN amount on withdraw (not underlying SUI). We
+// find the agent's SUI market coin by type pattern (robust to package upgrades).
+const MARKET_COIN_SUI_RE = /::reserve::MarketCoin<0x0*2::sui::SUI>$/
+
 async function runScallopWrite(
   ctx: OnchainRuntimeContext,
   amount: string,
-  kind: 'supply' | 'withdraw' | 'borrow' | 'repay',
+  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}"` }
-  // Minimum guard for value-moving actions (withdraw pulls the agent's own funds).
-  const minAction = kind === 'borrow' ? 'borrow' : kind === 'withdraw' ? null : 'supply'
-  if (minAction) {
-    const tooSmall = checkMinimum(minAction, amountMist)
+  // Minimum guard on supply (withdraw pulls the agent's own funds back).
+  if (kind === 'supply') {
+    const tooSmall = checkMinimum('supply', amountMist)
     if (tooSmall) return { ok: false, error: tooSmall }
   }
 
-  // Policy gate on value-moving actions (borrow creates debt + hands out funds).
-  if (ctx.policy && kind !== 'withdraw') {
+  // Policy gate on the value-moving supply.
+  if (ctx.policy && kind === 'supply') {
     const verdict = evaluatePolicy(
-      {
-        kind: 'transfer',
-        coinType: SUI_TYPE,
-        amountMist,
-        protocol: kind === 'borrow' ? 'borrow' : 'scallop',
-      },
+      { kind: 'transfer', coinType: SUI_TYPE, amountMist, protocol: 'scallop' },
       ctx.policy,
     )
     if (!verdict.allowed)
@@ -166,16 +166,48 @@ async function runScallopWrite(
     const builder = await sdk.createScallopBuilder()
     const tx = builder.createTxBlock()
     tx.setSender(ctx.agentAddress)
-    // *Quick helpers auto-select the user's coins/obligation. supply/withdraw and
-    // borrow return a coin to hand back; repay consumes coins. depositQuick's 3rd
-    // arg returnSCoin=false keeps the old market-coin standard (withdrawQuick
-    // redeems it; the new sCoin standard → "No valid coins").
     let out: unknown
-    if (kind === 'supply') out = await tx.depositQuick(Number(amountMist), 'sui', false)
-    else if (kind === 'withdraw') out = await tx.withdrawQuick(Number(amountMist), 'sui')
-    else if (kind === 'borrow') out = await tx.borrowQuick(Number(amountMist), 'sui')
-    else await tx.repayQuick(Number(amountMist), 'sui')
-    if (out) tx.transferObjects([out as never], ctx.agentAddress)
+    if (kind === 'supply') {
+      // Source the deposit from the treasury vault (policy-enforced) when wired,
+      // then hand the vault-drawn Coin<SUI> to Scallop's non-quick `deposit` (the
+      // `*Quick` helpers auto-select the agent's own coins, so they can't be vault-
+      // funded). `deposit` returns the market coin, sent to the agent below.
+      const coin = fundSui(tx.txBlock as never, ctx, amountMist, {
+        protocol: PROTOCOL_IDS.scallop,
+        kind: 'supply',
+        memo: 'scallop supply',
+      })
+      out = await tx.deposit(coin as never, 'sui')
+    } else {
+      // withdrawQuick redeems a MARKET-COIN amount, not underlying SUI. Convert
+      // the requested SUI to market coins at the position's rate and clamp to the
+      // held balance, so a full/over-withdraw cleanly redeems everything.
+      const [balances, q] = await Promise.all([
+        ctx.client.getAllBalances({ owner: ctx.agentAddress }),
+        sdk.createScallopQuery().then(async query => {
+          await query.init()
+          return query
+        }),
+      ])
+      const mc = balances.find(b => MARKET_COIN_SUI_RE.test(b.coinType))
+      const heldMc = BigInt(mc?.totalBalance ?? '0')
+      if (heldMc <= 0n) return { ok: false, error: 'no Scallop SUI position to withdraw' }
+      const port = (await q.getUserPortfolio({ walletAddress: ctx.agentAddress })) as {
+        lendings?: Array<{ coinName?: string; suppliedCoin?: number }>
+      }
+      const supplied = (port.lendings ?? []).find(l => l.coinName === 'sui')?.suppliedCoin ?? 0
+      const suppliedMist = BigInt(Math.floor(supplied * 1e9))
+      // redeem = requested/rate, where rate = supplied/heldMc; clamp to heldMc.
+      let redeemMc = suppliedMist > 0n ? (amountMist * heldMc) / suppliedMist : heldMc
+      if (redeemMc > heldMc || redeemMc <= 0n) redeemMc = heldMc
+      out = await tx.withdrawQuick(Number(redeemMc), 'sui')
+    }
+    if (out) {
+      // Option 1: cycle withdrawn SUI back into the vault (treasury stays intact);
+      // supply's market coin and the no-vault case go to the agent.
+      const cycled = kind === 'withdraw' && returnSuiToVault(tx.txBlock as never, ctx, out as never)
+      if (!cycled) tx.transferObjects([out as never], ctx.agentAddress)
+    }
     const transaction = tx.txBlock
 
     const sim = await simulate(ctx.client, transaction, ctx.agentAddress)
@@ -229,23 +261,8 @@ export function makeScallopWithdraw(ctx: OnchainRuntimeContext): ToolDef<AmountA
   }
 }
 
-export function makeScallopBorrow(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
-  return {
-    name: 'scallop.borrow',
-    description:
-      'Borrow SUI from Scallop against supplied collateral. Requires an existing supply position with enough health; the pre-flight simulation fails cleanly if under-collateralized. Policy-checked, simulated, then executed.',
-    searchHint: 'scallop borrow loan leverage debt against collateral sui',
-    schema: AmountSchema,
-    handler: async args => runScallopWrite(ctx, args.amount, 'borrow'),
-  }
-}
-
-export function makeScallopRepay(ctx: OnchainRuntimeContext): ToolDef<AmountArgs> {
-  return {
-    name: 'scallop.repay',
-    description: 'Repay borrowed SUI debt on Scallop. Simulated, then executed.',
-    searchHint: 'scallop repay pay back debt loan close sui',
-    schema: AmountSchema,
-    handler: async args => runScallopWrite(ctx, args.amount, 'repay'),
-  }
-}
+// NOTE: Scallop borrow/repay require opening a Scallop obligation + posting
+// collateral (a separate flow from lending deposits — borrowQuick alone aborts
+// "No obligation found"). Until that flow is wired, borrowing routes through the
+// verified NAVI/Suilend adapters instead, so we don't ship a borrow tool here
+// that can't execute.

package/src/tools/send.ts

@@ -15,6 +15,7 @@ import { checkMinimum } from '../minimums'
 import { evaluatePolicy, suiToMist } from '../policy'
 import { simulate } from '../simulate'
 import type { OnchainRuntimeContext } from '../types'
+import { canFundFromVault } from '../vault-fund'
 
 const SUI_TYPE = '0x2::sui::SUI'
 
@@ -55,26 +56,51 @@ export function makeSuiSend(ctx: OnchainRuntimeContext): ToolDef<Args> {
           }
         }
 
-        // 2. Build the PTB: split + transfer, plus on-chain receipt/enforcement.
+        // 2. Build the PTB.
         const tx = new Transaction()
-        const [coin] = tx.splitCoins(tx.gas, [amountMist])
-        tx.transferObjects([coin], to)
-        const recordsOnChain = Boolean(ctx.packageId && ctx.policyObjectId)
-        if (recordsOnChain) {
+        const vaultBacked = canFundFromVault(ctx, amountMist)
+        if (vaultBacked) {
+          // Vault-backed transfer: draw from the treasury via the full policy gate
+          // AND enforce the recipient allowlist ON-CHAIN (vault_transfer sends the
+          // funds to `to` and routes the ActionReceipt to the owner). A prompt-
+          // injected agent can't pay an un-allowlisted address even within budget.
           tx.moveCall({
-            target: `${ctx.packageId}::policy::record_action`,
+            target: `${ctx.packageId}::vault::vault_transfer`,
             typeArguments: [SUI_TYPE],
             arguments: [
+              tx.object(ctx.vaultId as string),
               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.pure.address(to),
+              tx.pure.vector('u8', Array.from(new TextEncoder().encode('send transfer'))),
               tx.object.clock(),
             ],
           })
+        } else {
+          // Single-key mode (no vault wired): split from the agent's coin + transfer,
+          // plus an on-chain receipt when a policy object is configured.
+          const [coin] = tx.splitCoins(tx.gas, [amountMist])
+          tx.transferObjects([coin], to)
+          if (ctx.packageId && ctx.policyObjectId) {
+            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(),
+              ],
+            })
+          }
         }
 
+        // Both paths enforce on-chain when configured: vault_transfer always mints
+        // a receipt; the gas path records only when a policy object is set.
+        const recordsOnChain = vaultBacked || Boolean(ctx.packageId && ctx.policyObjectId)
+
         // 3. Simulate-before-write.
         const sim = await simulate(ctx.client, tx, ctx.agentAddress)
         if (!sim.ok) {

package/src/tools/stake.ts

@@ -15,8 +15,10 @@ import type { ToolDef } from 'lyra-core'
 import { z } from 'zod'
 import { checkMinimum } from '../minimums'
 import { evaluatePolicy, suiToMist } from '../policy'
+import { PROTOCOL_IDS } from '../protocol-ids'
 import { simulate } from '../simulate'
 import type { OnchainRuntimeContext } from '../types'
+import { fundSui } from '../vault-fund'
 
 const SUI_TYPE = '0x2::sui::SUI'
 const SUI_SYSTEM_STATE = '0x5'
@@ -85,7 +87,13 @@ export function makeStake(ctx: OnchainRuntimeContext): ToolDef<StakeArgs> {
         if (!validator) return { ok: false, error: 'no active validator found to stake with' }
 
         const tx = new Transaction()
-        const [coin] = tx.splitCoins(tx.gas, [amountMist])
+        // Source the stake from the treasury vault (policy-enforced) when one is
+        // wired; otherwise from the agent's gas coin (single-key mode).
+        const coin = fundSui(tx, ctx, amountMist, {
+          protocol: PROTOCOL_IDS.suiStaking,
+          kind: 'stake',
+          memo: `stake ${args.amount} SUI`,
+        })
         tx.moveCall({
           target: '0x3::sui_system::request_add_stake',
           arguments: [tx.object(SUI_SYSTEM_STATE), coin, tx.pure.address(validator.address)],