@kaleidorg/mind 0.6.4 → 0.8.0

package/src/testing/mock-wallet.ts

@@ -0,0 +1,278 @@
+/**
+ * A stateful mock wallet — balances per layer, contacts (incl. ambiguous +
+ * injectable), a price, validation (insufficient funds, no route, unknown
+ * contact, no colored UTXOs), RGB issuance, and a record of what actually got
+ * "sent". The canonical contract tools bind to it, so the agent sees real
+ * schemas and real failure modes — not trivial canned stubs.
+ *
+ * Used by the eval harness and exported as `@kaleidorg/mind/testing` so hosts
+ * can build and demo an agent with no node, no funds and no network.
+ */
+
+import { bindWalletTools, type WalletHandler } from '../wallet/contract.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { bindSubmarineTools, type SubmarineHandler } from '../submarine/contract.js';
+
+export interface SendRecord {
+  tool: string;
+  to: string;
+  amount_sats?: number;
+  asset?: string;
+  amount?: number;
+}
+export interface MockContact { name: string; ln_address: string; note?: string }
+export interface MockWalletOptions {
+  priceUsd?: number;
+  failRoute?: boolean;
+  contacts?: MockContact[];
+  balances?: { spark: number; rln: number; arkade: number };
+  assets?: Record<string, number>;
+  /** Free colored UTXOs on the RLN node (issuance / RGB receive consume one). */
+  utxos?: number;
+  /** Liquid balances in smallest units (L-USDT: 8 decimals, L-BTC: sats) for submarine swaps. */
+  liquid?: { 'L-USDT': number; 'L-BTC': number };
+}
+export interface MockRgbAsset {
+  asset_id: string;
+  ticker: string;
+  name: string;
+  precision: number;
+  schema: 'NIA' | 'CFA' | 'UDA';
+  issued_supply: number;
+}
+export interface MockTransfer {
+  idx: number;
+  asset_id: string;
+  kind: 'Issuance' | 'Send' | 'ReceiveBlind';
+  status: 'Settled' | 'WaitingCounterparty';
+  amount: number;
+}
+
+export class MockWallet {
+  priceUsd: number;
+  failRoute: boolean;
+  balances: { spark: number; rln: number; arkade: number };
+  assets: Record<string, number>;
+  contacts: MockContact[];
+  utxos: number;
+  liquid: { 'L-USDT': number; 'L-BTC': number };
+  /** Submarine swaps opened against the mock /v2 maker, by id. */
+  submarineSwaps: Record<string, { from: 'L-USDT' | 'L-BTC'; invoice: string; expected: number; funded: boolean }> = {};
+  /** RGB assets the node knows about (seeded USDT/XAUT + anything issued). */
+  rgbAssets: MockRgbAsset[];
+  transfers: MockTransfer[] = [];
+  sends: SendRecord[] = [];
+
+  private readonly opts: MockWalletOptions;
+
+  constructor(o: MockWalletOptions = {}) {
+    this.opts = o;
+    this.priceUsd = o.priceUsd ?? 65_000;
+    this.failRoute = o.failRoute ?? false;
+    // Copies: the wallet mutates its state, and reset() rebuilds from `o`.
+    this.balances = { ...(o.balances ?? { spark: 500_000, rln: 300_000, arkade: 200_000 }) };
+    this.assets = { ...(o.assets ?? { USDT: 25_000_000, XAUT: 0 }) };
+    this.contacts = o.contacts ? [...o.contacts] : [
+      { name: 'bob', ln_address: 'bob@kaleidoswap.com' },
+      { name: 'alice', ln_address: 'alice@kaleidoswap.com' },
+      { name: 'john', ln_address: 'john.smith@kaleidoswap.com' },
+      { name: 'john', ln_address: 'john.doe@kaleidoswap.com' }, // ambiguous on purpose
+    ];
+    this.utxos = o.utxos ?? 5;
+    this.liquid = { ...(o.liquid ?? { 'L-USDT': 100 * 1e8, 'L-BTC': 200_000 }) };
+    this.rgbAssets = Object.keys(this.assets).map((ticker) => ({
+      asset_id: mockAssetId(ticker),
+      ticker,
+      name: ticker === 'USDT' ? 'Tether USD' : ticker === 'XAUT' ? 'Tether Gold' : ticker,
+      precision: 0,
+      schema: 'NIA' as const,
+      issued_supply: this.assets[ticker]!,
+    }));
+  }
+
+  private findAsset(ref: unknown): MockRgbAsset | undefined {
+    const q = String(ref ?? '');
+    return this.rgbAssets.find((a) => a.asset_id === q || a.ticker.toUpperCase() === q.toUpperCase());
+  }
+
+  /** Issue a new RGB asset — mirrors the node: needs a free colored UTXO. */
+  issueAsset(args: Record<string, unknown>): MockRgbAsset {
+    if (this.utxos < 1) throw new Error('No available colored UTXOs — call rln_create_utxos first.');
+    const schema = (['NIA', 'CFA', 'UDA'].includes(String(args.schema)) ? args.schema : 'NIA') as MockRgbAsset['schema'];
+    const ticker = String(args.ticker ?? '').toUpperCase();
+    if (!/^[A-Z0-9]{1,8}$/.test(ticker)) throw new Error('ticker must be 1-8 uppercase letters/digits.');
+    if (this.findAsset(ticker)) throw new Error(`An asset with ticker ${ticker} already exists.`);
+    const supply = schema === 'UDA' ? 1 : Number(args.amount);
+    if (!(supply > 0)) throw new Error('amount must be positive.');
+    const asset: MockRgbAsset = {
+      asset_id: mockAssetId(ticker),
+      ticker,
+      name: String(args.name ?? ticker),
+      precision: Number(args.precision ?? 0),
+      schema,
+      issued_supply: supply,
+    };
+    this.utxos -= 1;
+    this.rgbAssets.push(asset);
+    this.assets[ticker] = supply;
+    this.transfers.push({ idx: this.transfers.length + 1, asset_id: asset.asset_id, kind: 'Issuance', status: 'Settled', amount: supply });
+    this.sends.push({ tool: 'rln_issue_asset', to: 'self', asset: ticker, amount: supply });
+    return asset;
+  }
+
+  totalSats(): number {
+    return this.balances.spark + this.balances.rln + this.balances.arkade;
+  }
+  /** Back to the constructor state: balances, contacts, UTXOs, issued assets, history. */
+  reset(): void {
+    Object.assign(this, new MockWallet(this.opts));
+  }
+
+  private send(tool: string, rec: { to: string; amount_sats?: number; asset?: string; amount?: number }) {
+    if (this.failRoute) throw new Error('No route to destination.');
+    if (rec.amount_sats != null && rec.amount_sats > this.totalSats()) {
+      throw new Error(`Insufficient funds: have ${this.totalSats()} sats, need ${rec.amount_sats}.`);
+    }
+    this.sends.push({ tool, ...rec });
+    return { status: 'SUCCESS', payment_hash: 'mock' + this.sends.length };
+  }
+
+  handlers(): Record<string, WalletHandler> {
+    return {
+      get_balances: async () => ({
+        total_sats: this.totalSats(),
+        layers: [
+          { layer: 'spark', btc_sats: this.balances.spark, assets: [] },
+          { layer: 'rln', btc_sats: this.balances.rln, assets: Object.entries(this.assets).filter(([, v]) => v > 0).map(([ticker, amount]) => ({ ticker, amount })) },
+          { layer: 'arkade', btc_sats: this.balances.arkade, assets: [] },
+        ],
+      }),
+      spark_get_balance: async () => ({ btc_sats: this.balances.spark }),
+      rln_get_balances: async () => ({ btc_sats: this.balances.rln, assets: this.assets }),
+      arkade_get_balance: async () => ({ btc_sats: this.balances.arkade }),
+      spark_get_address: async () => ({ address: 'bc1qspark0mockreceiveaddr' }),
+      arkade_get_address: async () => ({ address: 'ark1q0mockreceiveaddr' }),
+      get_price: async ({ fiat }) => ({ asset: 'BTC', price_usd: this.priceUsd, fiat: (fiat as string) ?? 'USD' }),
+      fiat_to_sats: async ({ amount }) => ({ sats: Math.round((Number(amount) / this.priceUsd) * 1e8) }),
+      resolve_contact: async ({ name }) => {
+        const q = String(name).toLowerCase();
+        const matches = this.contacts.filter((c) => c.name.toLowerCase() === q);
+        if (matches.length === 0) throw new Error(`No contact named "${name}".`);
+        if (matches.length > 1) throw new Error(`Ambiguous: ${matches.length} contacts named "${name}" — ask the user which one.`);
+        return matches[0]!;
+      },
+      rln_create_ln_invoice: async ({ amount_sats }) => ({ invoice: `lnbcmock${amount_sats ?? ''}` }),
+      rln_create_rgb_invoice: async ({ asset, amount }) => ({ invoice: 'rgb:mockinvoice', asset, amount }),
+      send_payment: async ({ to, amount_sats }) => this.send('send_payment', { to: String(to), amount_sats: amount_sats != null ? Number(amount_sats) : undefined }),
+      rln_pay_invoice: async ({ invoice }) => this.send('rln_pay_invoice', { to: String(invoice) }),
+      rln_send_asset: async ({ asset, amount, to }) => {
+        const a = String(asset);
+        if ((this.assets[a] ?? 0) < Number(amount)) throw new Error(`Insufficient ${a} balance.`);
+        const res = this.send('rln_send_asset', { to: String(to), asset: a, amount: Number(amount) });
+        const found = this.findAsset(a);
+        if (found) this.transfers.push({ idx: this.transfers.length + 1, asset_id: found.asset_id, kind: 'Send', status: 'Settled', amount: Number(amount) });
+        return res;
+      },
+      rln_list_assets: async () => ({
+        assets: this.rgbAssets.map((a) => ({ ...a, balance: { spendable: this.assets[a.ticker] ?? 0 } })),
+      }),
+      rln_list_transfers: async ({ asset_id, asset }) => {
+        const ref = asset_id ?? asset;
+        const found = this.findAsset(ref);
+        if (!found) throw new Error(`Unknown asset "${String(ref)}".`);
+        return { transfers: this.transfers.filter((x) => x.asset_id === found.asset_id) };
+      },
+      rln_create_utxos: async ({ num }) => {
+        const n = Number(num ?? 5);
+        this.utxos += n;
+        this.sends.push({ tool: 'rln_create_utxos', to: 'self', amount: n });
+        return { created: true, num: n, free_utxos: this.utxos };
+      },
+      rln_issue_asset: async (args) => {
+        const a = this.issueAsset(args);
+        return { issued: true, asset_id: a.asset_id, ticker: a.ticker, name: a.name, schema: a.schema, issued_supply: a.issued_supply };
+      },
+      get_swap_quote: async ({ from_asset, to_asset, amount }) => ({
+        quote_id: 'quote-mock',
+        from_asset,
+        to_asset,
+        amount: Number(amount),
+        // toy rate: 1 USDT ≈ 1538 sats at $65k; otherwise echo.
+        receive_amount: String(from_asset).toUpperCase() === 'USDT' ? Math.round(Number(amount) * (1e8 / this.priceUsd)) : Number(amount),
+      }),
+      execute_swap: async ({ from_asset, to_asset, amount }) => {
+        this.sends.push({ tool: 'execute_swap', to: `${from_asset}->${to_asset}`, amount: Number(amount) });
+        return { status: 'SUCCESS', swap_id: 'swap' + this.sends.length };
+      },
+    };
+  }
+
+  /**
+   * The KaleidoSwap /v2 submarine contract against a toy maker: 0.5% fee, the
+   * invoice amount read from its BOLT11 human-readable part, L-USDT at `priceUsd`.
+   */
+  submarineHandlers(): Record<string, SubmarineHandler> {
+    return {
+      kaleidoswap_submarine_pairs: async () => ({
+        pairs: [
+          { from: 'L-USDT', to: 'BTC', fees: { percentage: 0.5 }, limits: { minimal: 10 * 1e8, maximal: 1_000 * 1e8 } },
+          { from: 'L-BTC', to: 'BTC', fees: { percentage: 0.5 }, limits: { minimal: 10_000, maximal: 1_000_000 } },
+        ],
+      }),
+      kaleidoswap_submarine_create: async ({ invoice, from_asset }) => {
+        const from = (from_asset ?? 'L-USDT') as 'L-USDT' | 'L-BTC';
+        if (from !== 'L-USDT' && from !== 'L-BTC') throw new Error(`Unsupported from_asset "${String(from_asset)}".`);
+        const sats = bolt11Sats(String(invoice));
+        if (sats == null) throw new Error('invalid_invoice: the invoice must be BOLT11 with an amount.');
+        const withFee = sats * 1.005;
+        const expected = Math.ceil(from === 'L-USDT' ? (withFee / 1e8) * this.priceUsd * 1e8 : withFee);
+        const id = `sub${Object.keys(this.submarineSwaps).length + 1}`;
+        this.submarineSwaps[id] = { from, invoice: String(invoice), expected, funded: false };
+        return { swap_id: id, from_asset: from, expected_amount: String(expected), lockup_address: `tlq1qmock${id}` };
+      },
+      kaleidoswap_submarine_fund: async ({ swap_id }) => {
+        const swap = this.submarineSwaps[String(swap_id)];
+        if (!swap) throw new Error(`No submarine swap "${String(swap_id)}" was created by this server.`);
+        if (swap.funded) throw new Error(`Swap ${String(swap_id)} is already funded.`);
+        if (this.liquid[swap.from] < swap.expected) throw new Error(`Insufficient ${swap.from} balance.`);
+        this.liquid[swap.from] -= swap.expected;
+        swap.funded = true;
+        this.sends.push({ tool: 'kaleidoswap_submarine_fund', to: swap.invoice, asset: swap.from, amount: swap.expected });
+        return { funded: true, swap_id, asset: swap.from, amount: String(swap.expected), txid: `mocktx${String(swap_id)}` };
+      },
+      kaleidoswap_submarine_status: async ({ swap_id }) => {
+        const swap = this.submarineSwaps[String(swap_id)];
+        if (!swap) throw new Error(`invalid_swap_id: "${String(swap_id)}" is not a swap id`);
+        const status = swap.funded ? 'transaction.claimed' : 'swap.created';
+        return { swap_id, status, done: swap.funded, failed: false, funded: swap.funded };
+      },
+    };
+  }
+
+  /** Bind the contract tools to this wallet (optionally overriding some — e.g. to inject). */
+  registry(overrides?: Partial<Record<string, WalletHandler>>): ToolRegistry {
+    const h = { ...this.handlers(), ...(overrides ?? {}) } as Record<string, WalletHandler>;
+    const sub = { ...this.submarineHandlers(), ...(overrides ?? {}) } as Record<string, SubmarineHandler>;
+    return new ToolRegistry([
+      bindWalletTools(h, { layers: ['spark', 'rln', 'arkade', 'core'], allowMissing: true }),
+      bindSubmarineTools(sub, { allowMissing: true }),
+    ]);
+  }
+}
+
+/** Deterministic fake RGB contract id per ticker (stable across runs). */
+function mockAssetId(ticker: string): string {
+  let h = 0;
+  for (const c of ticker) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+  return `rgb:mock-${ticker.toLowerCase()}-${h.toString(36)}`;
+}
+
+/** Amount in sats from a BOLT11 human-readable part ("lntbs10u…" → 1000), or null. */
+function bolt11Sats(invoice: string): number | null {
+  const m = invoice.toLowerCase().match(/^ln(?:bcrt|tbs|bc|tb)(\d+)([munp])?1/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const mult = { m: 1e5, u: 100, n: 0.1, p: 0.0001 }[m[2] ?? ''] ?? 1e8;
+  const sats = n * mult;
+  return sats >= 1 ? Math.round(sats) : null;
+}

package/src/testing/scripted-provider.ts

@@ -0,0 +1,37 @@
+/**
+ * A scripted LLMProvider — replays planned turns instead of running a model.
+ *
+ * Lets hosts wire the full Engine / Funnel (skills, recipes, confirm gate) in
+ * unit tests, CI and demos without loading a QVAC model. Deterministic tiers
+ * (fast-path, recipes with regex extraction) never call it at all.
+ */
+
+import type { ToolCall } from '../types.js';
+import type { LLMProvider } from '../providers/types.js';
+
+export interface ScriptedTurn {
+  /** Assistant text for this turn. */
+  text?: string;
+  /** Tool to call — ignored when the tool is not in the turn's scoped tool list. */
+  tool?: string;
+  args?: Record<string, unknown>;
+}
+
+export function scriptedProvider(turns: ScriptedTurn[] = [], fallback = 'I need more information.'): LLMProvider {
+  let index = 0;
+  return {
+    name: 'scripted',
+    async runTurn(input) {
+      const planned = turns[index++] ?? { text: fallback };
+      const call: ToolCall | undefined = planned.tool && input.tools.some((t) => t.name === planned.tool)
+        ? { id: `scripted-${index}`, name: planned.tool, arguments: planned.args ?? {} }
+        : undefined;
+      return {
+        text: planned.text ?? '',
+        rawContent: planned.text ?? '',
+        toolCalls: call ? [call] : [],
+        inference: { durationMs: 0, status: 'completed' },
+      };
+    },
+  };
+}

package/src/wallet/confirm.test.ts

@@ -48,6 +48,22 @@ describe('confirmReadback', () => {
     expect(line).toBe('Pay Lightning invoice lnbc1p…abcd over Spark. Confirm?');
   });
 
+  it('rln_send_asset: kaleido-mcp argument names', () => {
+    expect(confirmReadback({ name: 'rln_send_asset', arguments: { asset_id: 'rgb:abcdefgh-1234567890-xyz', amount: 5, recipient_id: 'utxob:ab12cd34ef56gh78ij90' } }))
+      .toBe('Send 5 rgb:ab…-xyz to utxob:…ij90 over RLN. Confirm?');
+  });
+
+  it('rln_send_btc / channel / atomic taker readbacks', () => {
+    expect(confirmReadback({ name: 'rln_send_btc', arguments: { address: 'tb1qexampleaddress0000000000xyz', amount_sat: 25000 } }))
+      .toBe('Send 25,000 sats on-chain to tb1qex…0xyz over RLN. Confirm?');
+    expect(confirmReadback({ name: 'rln_open_channel', arguments: { peer_pubkey_and_addr: '03abcdef0123456789abcdef0123456789@1.2.3.4:9735', capacity_sat: 100000 } }))
+      .toBe('Open a 100,000 sats channel to 03abcd…6789. Confirm?');
+    expect(confirmReadback({ name: 'rln_close_channel', arguments: { channel_id: 'chan0123456789abcdef0123', peer_pubkey: 'x', force: true } }))
+      .toBe('Force-close channel chan01…0123. Confirm?');
+    expect(confirmReadback({ name: 'rln_atomic_taker', arguments: { swapstring: '30/rgb:asset/10/btc/3600/abcdef0123456789' } }))
+      .toBe('Accept atomic swap 30/rgb…6789 on your node. Confirm?');
+  });
+
   it('execute_swap: from → to with amount', () => {
     expect(confirmReadback({ name: 'execute_swap', arguments: { from_asset: 'BTC', to_asset: 'USDT', amount: 0.01 } }))
       .toBe('Swap 0.01 BTC for USDT. Confirm?');

package/src/wallet/confirm.ts

@@ -31,7 +31,7 @@ function isRef(s: string): boolean {
 /** Shorten an address/invoice for speech; leave contact names intact. */
 function shortRef(s: string): string {
   const v = s.trim();
-  return isRef(v) ? `${v.slice(0, 6)}…${v.slice(-4)}` : v;
+  return isRef(v) && v.length > 12 ? `${v.slice(0, 6)}…${v.slice(-4)}` : v;
 }
 
 /** " over Spark" suffix for the call's layer (explicit arg wins, else the tool's). */
@@ -41,8 +41,26 @@ function over(name: string, args: Record<string, unknown>): string {
   return label ? ` over ${label}` : '';
 }
 
-const sats = (v: unknown) => `${fmtNum(Number(v))} sats`;
-const asset = (amount: unknown, ticker: unknown) => `${fmtNum(Number(amount))} ${String(ticker)}`;
+/** A finite number from a tool arg, else undefined (never NaN in a readback). */
+function num(v: unknown): number | undefined {
+  if (typeof v === 'number') return Number.isFinite(v) ? v : undefined;
+  if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) return Number(v);
+  return undefined;
+}
+
+/** A display string from a tool arg, stripped of stray quotes/commas a model may leave in. */
+function label(v: unknown): string {
+  return String(v ?? '').trim().replace(/^[\s'"`,]+|[\s'"`,]+$/g, '') || '?';
+}
+
+const sats = (v: unknown) => {
+  const n = num(v);
+  return n === undefined ? 'an unspecified amount of sats' : `${fmtNum(n)} sats`;
+};
+const asset = (amount: unknown, ticker: unknown) => {
+  const n = num(amount);
+  return n === undefined ? `an unspecified amount of ${label(ticker)}` : `${fmtNum(n)} ${label(ticker)}`;
+};
 
 /** A spoken confirmation ending in "Confirm?", or null for non-spend tools. */
 export function confirmReadback(call: { name: string; arguments: Record<string, unknown> }): string | null {
@@ -62,12 +80,32 @@ export function confirmReadback(call: { name: string; arguments: Record<string,
       return ask(`Send ${sats(a.amount_sats)} to ${to()}${over(name, a)}`);
     case 'rln_send_asset':
     case 'liquid_send':
-      return ask(`Send ${asset(a.amount, a.asset)} to ${to()}${over(name, a)}`);
+      // kaleido-mcp names these asset_id / recipient_id.
+      return ask(`Send ${asset(a.amount, a.asset ?? shortRef(String(a.asset_id ?? '')))} to ${to(a.to != null ? 'to' : 'recipient_id')}${over(name, a)}`);
     case 'rln_pay_invoice':
     case 'spark_pay_invoice':
       return ask(`Pay Lightning invoice ${shortRef(String(a.invoice ?? ''))}${over(name, a)}`);
+    case 'rln_issue_asset': {
+      const named = a.name != null && a.ticker != null && label(a.name) !== label(a.ticker) ? ` (${label(a.name)})` : '';
+      return a.schema === 'UDA'
+        ? ask(`Issue unique asset ${label(a.ticker ?? a.name)}${named} on RGB`)
+        : ask(`Issue ${asset(a.amount, a.ticker ?? a.name)}${named}, a new RGB asset`);
+    }
+    case 'rln_create_utxos':
+      return ask(`Create ${fmtNum(num(a.num) ?? 5)} RGB UTXOs on-chain${over(name, a)}`);
+    case 'rln_send_btc':
+      return ask(`Send ${sats(a.amount_sat)} on-chain to ${to('address')}${over(name, a)}`);
+    case 'rln_open_channel': {
+      const peer = shortRef(String(a.peer_pubkey_and_addr ?? '').split('@')[0] ?? '');
+      const withAsset = a.asset_id != null && num(a.asset_amount) !== undefined ? ` with ${fmtNum(num(a.asset_amount)!)} of ${shortRef(String(a.asset_id))}` : '';
+      return ask(`Open a ${sats(a.capacity_sat)} channel to ${peer}${withAsset}`);
+    }
+    case 'rln_close_channel':
+      return ask(`${a.force ? 'Force-close' : 'Close'} channel ${shortRef(String(a.channel_id ?? ''))}`);
+    case 'rln_atomic_taker':
+      return ask(`Accept atomic swap ${shortRef(String(a.swapstring ?? ''))} on your node`);
     case 'execute_swap':
-      return ask(`Swap ${fmtNum(Number(a.amount))} ${String(a.from_asset)} for ${String(a.to_asset)}`);
+      return ask(`Swap ${asset(a.amount, a.from_asset)} for ${label(a.to_asset)}`);
     default:
       // Unknown but spend-flagged tool → a generic, still-honest readback.
       return getWalletTool(name)?.spend ? ask(`Confirm ${name.replace(/_/g, ' ')}`) : null;

package/src/wallet/contract.test.ts

@@ -1,6 +1,8 @@
 /** Wallet contract tests — integrity of the single source of truth. */
 
 import { describe, it, expect, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { parseSkill } from '../skills/registry.js';
 import {
   WALLET_TOOLS,
   SPEND_TOOLS,
@@ -40,9 +42,13 @@ describe('WALLET_TOOLS contract', () => {
     expect(isSpendTool('execute_swap')).toBe(true);
     expect(isSpendTool('spark_send')).toBe(true);
     expect(isSpendTool('spark_pay_invoice')).toBe(true);
+    expect(isSpendTool('rln_issue_asset')).toBe(true);
+    expect(isSpendTool('rln_create_utxos')).toBe(true);
     // reads are not
     expect(isSpendTool('get_balances')).toBe(false);
     expect(isSpendTool('get_price')).toBe(false);
+    expect(isSpendTool('rln_list_assets')).toBe(false);
+    expect(isSpendTool('rln_list_transfers')).toBe(false);
     expect([...SPEND_TOOLS].length).toBeGreaterThanOrEqual(5);
   });
 
@@ -97,3 +103,35 @@ describe('bindWalletTools', () => {
     expect(src.listTools().map((t) => t.name)).toEqual(['spark_get_balance']);
   });
 });
+
+describe('RLN tools vs kaleido-mcp and the rgb-lightning-node skill', () => {
+  // The rln_* tools kaleido-mcp registers (rln_mpp_pay belongs to paid-data).
+  const MCP_RLN = [
+    'rln_get_node_info', 'rln_get_balances', 'rln_get_asset_balance', 'rln_list_assets',
+    'rln_get_address', 'rln_create_rgb_invoice', 'rln_create_ln_invoice', 'rln_pay_invoice',
+    'rln_send_btc', 'rln_send_asset', 'rln_list_channels', 'rln_connect_peer', 'rln_open_channel',
+    'rln_close_channel', 'rln_get_channel_id', 'rln_list_payments', 'rln_refresh_transfers',
+    'rln_atomic_taker', 'rln_list_swaps', 'rln_get_swap',
+  ];
+
+  it('covers every rln_* tool kaleido-mcp exposes', () => {
+    const missing = MCP_RLN.filter((n) => !getWalletTool(n));
+    expect(missing).toEqual([]);
+  });
+
+  it('gates every fund-moving or committing RLN tool', () => {
+    for (const n of ['rln_send_btc', 'rln_open_channel', 'rln_close_channel', 'rln_atomic_taker']) {
+      expect(isSpendTool(n)).toBe(true);
+    }
+    for (const n of ['rln_get_asset_balance', 'rln_refresh_transfers', 'rln_list_swaps', 'rln_get_swap']) {
+      expect(isSpendTool(n)).toBe(false);
+    }
+  });
+
+  it('the skill only declares tools that exist in the contract', () => {
+    const md = readFileSync(new URL('../../skills/rgb-lightning-node/SKILL.md', import.meta.url), 'utf8');
+    const skill = parseSkill(md);
+    const unknown = (skill.tools ?? []).filter((n) => !getWalletTool(n));
+    expect(unknown).toEqual([]);
+  });
+});

package/src/wallet/contract.ts

@@ -91,6 +91,42 @@ export const WALLET_TOOLS: WalletToolDef[] = [
   t('rln', 'rln_create_rgb_invoice', 'Create an RGB asset invoice to receive an asset (e.g. USDT).', { asset, amount: { type: 'number', description: 'Asset amount' } }, ['asset', 'amount']),
   t('rln', 'rln_pay_invoice', 'Pay a Lightning invoice from the RLN node.', { invoice: { type: 'string' } }, ['invoice'], true),
   t('rln', 'rln_send_asset', 'Send an RGB asset (e.g. USDT) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+  t('rln', 'rln_list_assets', 'List RGB assets held by the RLN node (asset_id, ticker, name, precision, balances).'),
+  t('rln', 'rln_get_asset_balance', 'Get the balance of one RGB asset by asset_id (settled, future, spendable, off-chain).', { asset_id: { type: 'string', description: "RGB asset id, e.g. 'rgb:2JEUOrsc-…'" } }, ['asset_id']),
+  t('rln', 'rln_refresh_transfers', 'Refresh pending RGB transfers so balances and transfer status are up to date.'),
+  t('rln', 'rln_get_address', 'Get an on-chain BTC address of the RLN node for deposits.'),
+  t('rln', 'rln_send_btc', 'Send on-chain BTC from the RLN node.', { address: { type: 'string', description: 'Destination Bitcoin address' }, amount_sat: { type: 'number', description: 'Amount in satoshis' }, fee_rate: { type: 'number', description: 'sat/vbyte (default 3)' } }, ['address', 'amount_sat'], true),
+  t('rln', 'rln_list_payments', 'List recent Lightning payments (sent and received) on the RLN node.', { limit: { type: 'number', description: 'Max payments (default 20)' } }),
+  t('rln', 'rln_connect_peer', 'Connect the RLN node to a Lightning peer.', { peer_pubkey_and_addr: { type: 'string', description: 'pubkey@host:port' } }, ['peer_pubkey_and_addr']),
+  t('rln', 'rln_open_channel', 'Open a Lightning channel, optionally allocating an RGB asset to it.', {
+    peer_pubkey_and_addr: { type: 'string', description: 'pubkey@host:port' },
+    capacity_sat: { type: 'number', description: 'Channel capacity in satoshis' },
+    push_msat: { type: 'number', description: 'Millisatoshis pushed to the peer (default 0)' },
+    asset_id: { type: 'string', description: 'RGB asset id to allocate' },
+    asset_amount: { type: 'number', description: 'RGB asset amount to allocate' },
+    is_public: { type: 'boolean', description: 'Announce the channel (default false)' },
+  }, ['peer_pubkey_and_addr', 'capacity_sat'], true),
+  t('rln', 'rln_close_channel', 'Close a Lightning channel (force only for an unresponsive peer).', { channel_id: { type: 'string' }, peer_pubkey: { type: 'string' }, force: { type: 'boolean', description: 'Unilateral close (default false)' } }, ['channel_id', 'peer_pubkey'], true),
+  t('rln', 'rln_get_channel_id', 'Resolve a temporary_channel_id from rln_open_channel to the final channel_id.', { temporary_channel_id: { type: 'string' } }, ['temporary_channel_id']),
+  t('rln', 'rln_atomic_taker', 'Whitelist a maker swap on the node (taker side). Pass the swapstring from kaleidoswap_atomic_init, before kaleidoswap_atomic_execute.', { swapstring: { type: 'string' } }, ['swapstring'], true),
+  t('rln', 'rln_list_swaps', 'List atomic swaps on the RLN node (maker and taker sides).'),
+  t('rln', 'rln_get_swap', 'Get an atomic swap by payment_hash.', { payment_hash: { type: 'string' }, taker: { type: 'boolean', description: 'Taker-side swap' } }, ['payment_hash']),
+  t('rln', 'rln_list_transfers', 'List RGB transfers for one asset (issuance, sends, receives) with their status — use to check if an RGB invoice was paid.', { asset_id: { type: 'string', description: 'RGB asset id (in-app wallets also accept a ticker)' } }, ['asset_id']),
+  // Issuance + UTXO prep spend on-chain BTC and are irreversible → gated like any spend.
+  t('rln', 'rln_create_utxos', 'Create colorable UTXOs on the RLN node — needed before issuing or receiving RGB assets on a fresh node.', {
+    num: { type: 'number', description: 'How many UTXOs (default 5)' },
+    size: { type: 'number', description: 'Size of each UTXO in sats (default: node decides)' },
+    up_to: { type: 'boolean', description: 'Only top up to `num` free UTXOs (default false)' },
+    fee_rate: { type: 'number', description: 'sat/vbyte (default 1)' },
+  }, [], true),
+  t('rln', 'rln_issue_asset', 'Issue a NEW RGB asset owned by this node (e.g. an event ticket or loyalty token).', {
+    schema: { type: 'string', enum: ['NIA', 'CFA', 'UDA'], description: 'NIA = token (default), CFA = collectible, UDA = unique/NFT' },
+    name: { type: 'string', description: 'Asset name, e.g. "Hackathon Ticket"' },
+    ticker: { type: 'string', description: 'Uppercase ticker, e.g. "TICKET". Required for NIA and UDA' },
+    amount: { type: 'number', description: 'Total supply in display units. Required for NIA and CFA; UDA is always 1' },
+    precision: { type: 'number', description: 'Decimal places (default 0)' },
+    details: { type: 'string', description: 'Optional description (CFA and UDA)' },
+  }, ['name'], true),
 
   // ── Arkade ─────────────────────────────────────────────────────────────
   t('arkade', 'arkade_get_balance', 'Get the Arkade wallet balance.'),