@kaleidorg/mind 0.6.4 → 0.8.0

package/skills/kaleido-trading/references/atomic.md

@@ -0,0 +1,93 @@
+# Atomic swap over kaleido-mcp
+
+Every KaleidoSwap swap settles as an atomic HTLC swap between the maker and
+the user's RGB Lightning Node (RLN). There is no deposit or order flow on
+kaleido-mcp 0.3.0+. If either side fails, nothing settles. Typical end-to-end
+time: 2–15 s.
+
+These are kaleido-mcp's argument names. In-app wallets that bind the
+`@kaleidorg/mind` KaleidoSwap contract use the simpler `from_asset` /
+`to_asset` / `amount` quote and run the chain through a recipe instead.
+
+## Steps
+
+```
+0. kaleidoswap_get_pairs()    → pairs + routes[{ from_layer, to_layer, min_amount, max_amount }]
+   kaleidoswap_get_assets()   → asset_id + precision per ticker (ids differ per network)
+
+1. kaleidoswap_get_quote({
+     from_asset_id: "BTC",  from_layer: "BTC_LN",  from_amount: 0.001,   // display units
+     to_asset_id:   "<USDT asset_id>",  to_layer: "RGB_LN"
+   })
+   → { rfq_id, expires_at, from_asset: { amount_raw, amount_display },
+       to_asset: { amount_raw, amount_display }, price }
+   Pass exactly one of from_amount (sell a fixed input) or to_amount (buy a fixed output).
+   Show the user amount in → amount out → rate, and wait for a yes.
+
+2. kaleidoswap_atomic_init({ rfq_id,
+     from_asset_id, from_amount_raw: quote.from_asset.amount_raw,
+     to_asset_id,   to_amount_raw:   quote.to_asset.amount_raw })
+   → { swapstring, payment_hash, access_token }
+   access_token is returned only here; keep it for status.
+
+3. rln_atomic_taker({ swapstring })      ← whitelist the incoming HTLC. MUST precede execute.
+   rln_get_node_info()                   → { pubkey }  (the taker_pubkey)
+
+4. kaleidoswap_atomic_execute({ swapstring, taker_pubkey, payment_hash })
+
+5. kaleidoswap_atomic_status({ payment_hash, access_token })   ← poll every 2 s
+   Waiting → Pending → Succeeded | Failed | Expired
+
+6. rln_refresh_transfers()               ← after an RGB leg, so balances update
+```
+
+`amount_raw` values are already in the maker's raw units (msat for BTC, atomic
+units for RGB). Never convert them again. `payment_hash` identifies the swap
+and is not an order id.
+
+## Errors
+
+| Situation | What to do |
+|---|---|
+| Quote expired (~60 s) | Re-quote. Never reuse an rfq_id or swapstring. |
+| `rln_atomic_taker` fails | Do NOT execute. Re-quote and restart. |
+| Status `Expired` / `Failed` | Nothing settled. Check liquidity on both legs (`rln_list_channels`), then re-quote. |
+| Polling > 120 s | Check `rln_get_swap({ payment_hash, taker: true })` before retrying. Never start a second swap for the same trade while one may still settle. |
+
+## Liquidity prerequisites
+
+The swap needs outbound capacity on the asset you send and inbound capacity on
+the asset you receive. If either side is short, `atomic_execute` fails. Buy a
+channel first (skill: `kaleido-lsps`).
+
+## Reading the result
+
+An RGB asset received into a Lightning channel shows up in
+`rln_get_asset_balance({ asset_id }).offchain_outbound`, not in `spendable`
+(which is on-chain only). `offchain_outbound + offchain_inbound` is the
+channel's capacity for that asset. The node's own view of swaps:
+`rln_list_swaps()` / `rln_get_swap({ payment_hash, taker: true })`.
+
+## Cross-layer moves
+
+| From | To | How |
+|---|---|---|
+| BTC_LN | RGB_LN (USDT/XAUT) | atomic swap |
+| RGB_LN | BTC_LN | atomic swap |
+| RGB_LN | RGB_LN (e.g. XAUT → USDT) | atomic swap |
+| BTC_LN | BTC_SPARK | not a swap: create a Spark Lightning invoice, pay it from the node (`rln_pay_invoice`) |
+| BTC_SPARK | BTC_LN | create an invoice on the node (`rln_create_ln_invoice`), pay it from Spark |
+| BTC_LN | BTC_L1 | close a channel (`rln_close_channel`), slow |
+
+Other layers can appear in `kaleidoswap_get_pairs()` routes but are not
+executable through these tools.
+
+## Safety
+
+1. Confirm from / to / amount / rate before `atomic_init`.
+2. Never hard-code asset ids or layers; read them from the API.
+3. Re-quote if execution would start more than ~30 s after the quote.
+4. Check `rln_list_swaps()` for a pending taker swap before starting another.
+5. Dry run: when asked for a dry run, quote and report only; never call
+   `kaleidoswap_atomic_init`, `rln_atomic_taker`, `kaleidoswap_atomic_execute`,
+   `rln_send_asset` or `rln_pay_invoice`.

package/skills/paid-data/SKILL.md

@@ -1,12 +1,65 @@
 ---
 name: paid-data
-description: Fetch premium or paywalled data that requires a small Lightning (L402) payment — paid feeds, gated APIs, unlockable resources. Triggers when the user wants premium, paid, or unlockable data behind an L402 paywall.
-tools: fetch_paid_resource
-triggers: premium, paid, l402, feed, subscription, unlock, paywall
+description: Fetch premium or paywalled data behind an HTTP 402 Lightning payment (L402 or MPP, the Machine Payments Protocol) — paid feeds, pay-per-call APIs, unlockable resources — without signing up or holding an API key. Also finds paid APIs in the public 402index registry. Triggers when the user wants premium, paid, gated or unlockable data, or asks for a paid API.
+tools: fetch_paid_resource, search_paid_apis, mpp_request_challenge, mpp_parse_challenge_header, mpp_submit_credential, rln_mpp_pay, spark_mpp_pay, l402_request_challenge, l402_fetch_resource
+triggers: premium, paid, l402, mpp, 402, feed, subscription, unlock, paywall, pay per call, paid api, gated
+metadata:
+  author: kaleidoswap
+  version: "0.2.0"
 ---
 
 # Paid data
 
-Fetch L402-paywalled resources, paying small Lightning invoices automatically
-with `fetch_paid_resource`. Small amounts pay without prompting (capped);
-anything larger is declined. Tell the user what was paid and what was returned.
+Servers gate a resource behind an HTTP 402 Lightning challenge; you pay the
+invoice and present the proof. L402 is the Lightning-only subset of MPP. Tell
+the user what was paid and what came back.
+
+Use whichever tools you have:
+
+## In-app: one call
+
+`fetch_paid_resource({ url })` fetches, pays small invoices automatically
+(capped by the host) and returns the data. Anything above the cap is declined;
+report that instead of retrying.
+
+## Over kaleido-mcp: three steps
+
+```
+1. mpp_request_challenge({ url })
+   → { challenge_id, invoice, amount_sats, intent, expires_at, macaroon? }
+
+2. rln_mpp_pay({ invoice, challenge_id, macaroon? })     ← pays from the RGB Lightning Node
+   (or spark_mpp_pay with the same arguments, from the Spark wallet; better for
+    tiny amounts where Lightning routing may fail)
+   → { paid, payment_hash, preimage?, credential: "<JSON string>" }
+
+3. mpp_submit_credential({ url, credential })            ← pass credential verbatim
+   → { ok, status, data, receipt }
+```
+
+Finish all three before `expires_at` (~60 s); a credential is single-use, so
+restart from step 1 if it expires. Keep the `receipt` as proof of payment.
+
+- **Discovery:** `search_paid_apis({ query, protocol?, health: "healthy" })`
+  lists registered endpoints with their price; pick a healthy one, then run the
+  flow on its `url`.
+- **Own fetch:** with a `WWW-Authenticate` header already in hand, use
+  `mpp_parse_challenge_header({ url, www_authenticate })` instead of step 1.
+- **Legacy L402-only servers:** `l402_request_challenge` /
+  `l402_fetch_resource`. Prefer the `mpp_*` tools; they handle both.
+- **Sessions:** `intent: "session"` challenges allow pay-once, then cheap
+  repeat calls. Not every server offers them; fall back to `charge`.
+
+| Error | Meaning | Fix |
+|---|---|---|
+| `Expected HTTP 402` | URL is not payment-gated | Fetch it normally |
+| `payment failed` | Route or balance problem | Check balances; try `spark_mpp_pay` |
+| `401 after submit` | Bad or reused credential | Redo steps 1–3 |
+| `challenge expired` | Too slow between steps | Restart from step 1 |
+
+## Rules
+
+1. Show `amount_sats` before paying; ask for a yes above 1,000 sats.
+2. Only pay challenges for URLs the user asked for.
+3. Stop after two failures in a row and report; don't loop.
+4. Dry run: report the price and what you would fetch; never pay.

package/skills/rgb-lightning-node/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: rgb-lightning-node
-description: "Drive the user's local RGB Lightning Node (RLN) — read its pubkey/status, list channels and their capacities, check RGB asset balances, manage channels/peers, whitelist a swap, or create Lightning/RGB receive invoices. Triggers when the user asks about the node, their channels or capacities, needs an invoice, or is mid-atomic-swap and the maker needs the node pubkey or a swapstring whitelisted."
-tools: rln_get_node_info, rln_get_balances, rln_list_channels, rln_list_assets, rln_get_asset_balance, rln_open_channel, rln_close_channel, rln_connect_peer, rln_get_channel_id, rln_whitelist_swap, rln_atomic_taker, rln_list_payments, rln_create_ln_invoice, rln_create_rgb_invoice
-triggers: node, nodeinfo, pubkey, peer, channels, channel capacity, list channels, inbound, capacity, asset balance, whitelist, taker, swapstring, invoice, receive, rgb invoice, ln invoice
+description: "Drive the user's local RGB Lightning Node (RLN) — read its pubkey/status, list channels and their capacities, check RGB asset balances, manage channels/peers, whitelist a swap, or create Lightning/RGB receive invoices. Triggers when the user asks about the node, their channels or capacities, needs an invoice, wants to issue/mint a new RGB token or NFT, or is mid-atomic-swap and the maker needs the node pubkey or a swapstring whitelisted."
+tools: rln_get_node_info, rln_get_balances, rln_list_channels, rln_list_assets, rln_get_asset_balance, rln_refresh_transfers, rln_get_address, rln_send_btc, rln_send_asset, rln_pay_invoice, rln_open_channel, rln_close_channel, rln_connect_peer, rln_get_channel_id, rln_atomic_taker, rln_list_swaps, rln_get_swap, rln_list_payments, rln_create_ln_invoice, rln_create_rgb_invoice, rln_list_transfers, rln_create_utxos, rln_issue_asset
+triggers: node, nodeinfo, pubkey, peer, channels, channel capacity, list channels, open channel, close channel, inbound, capacity, asset balance, whitelist, taker, swapstring, swaps, payments, invoice, receive, send asset, send rgb, on-chain address, deposit, rgb invoice, ln invoice, issue, mint, new token, nft, utxos, transfers
 metadata:
   author: kaleidoswap
-  version: "0.1.0"
+  version: "0.3.3"
 ---
 
 # RGB Lightning Node (taker-side)
@@ -70,14 +70,79 @@ ASYNCHRONOUSLY (seconds to minutes after payment). If the new channel isn't
 listed yet, say it's still opening and suggest checking again — don't claim
 failure.
 
-### `rln_list_assets` — no args
-Lists RGB assets known to the node with per-asset balances (settled, future,
-spendable, offchain_outbound, offchain_inbound). Use for "what assets do I
-hold / what's my USDT balance".
+### `rln_list_assets` — { schemas? }
+Lists RGB assets known to the node: `asset_id`, `ticker`, `name`, `precision`
+(in-app wallets also return balances). `schemas` is an optional filter — an
+array of `"Nia"`, `"Uda"`, `"Cfa"`; call it with `{}` to list everything.
+Use for "what assets do I hold / what's my USDT balance".
+
+Call it **once** per question. An empty list is a real answer: the node holds
+no RGB assets yet — tell the user that (and offer to issue one) instead of
+calling it again.
+
+### Tickers are not asset ids
+`asset_id` arguments take the full RGB id (`rgb:…`), never a ticker like
+`USDT` or `HCK`. When the user names an asset by ticker or name, first call
+`rln_list_assets`, find the entry whose `ticker`/`name` matches, and pass its
+`asset_id`. If nothing matches, say the node has no such asset — do not guess
+an id.
 
 ### `rln_get_asset_balance` — { asset_id }
-Balance for one RGB asset by id. Use after `rln_list_assets` gave you the id,
-or when the user names a specific asset.
+Balance for one RGB asset by id. Resolve a ticker to its `asset_id` with
+`rln_list_assets` first.
+
+| Field | Meaning |
+|---|---|
+| `settled` / `spendable` | On-chain (RGB_L1), UTXO-bound |
+| `future` | Pending settlement |
+| `offchain_outbound` | In a Lightning channel: what you can **send** |
+| `offchain_inbound` | Channel receive capacity for this asset |
+
+For USDT/XAUT held in an RGB channel, report `offchain_outbound`; `spendable`
+is 0 and that is normal.
+
+### `rln_refresh_transfers` — no args
+Syncs pending RGB transfers. Call it before re-reading a balance or transfer
+status that looks stale (e.g. right after an invoice was paid or a swap filled).
+
+### `rln_get_address` — no args
+An on-chain BTC address of the node, for funding it. Not an RGB invoice and not
+a Lightning invoice.
+
+### `rln_send_btc` — { address, amount_sat, fee_rate? } — 🔒 confirm-gated
+Sends on-chain BTC from the node. Only when the user gave both the address and
+the amount.
+
+### `rln_send_asset` — 🔒 confirm-gated
+Sends an RGB asset to the recipient encoded in an RGB invoice. Use the argument
+names of the schema you were given: in-app wallets take `{ asset, amount, to }`
+(ticker or asset_id, units, the invoice); kaleido-mcp takes
+`{ asset_id, amount, recipient_id }`, where `asset_id` is the `rgb:…` id from
+`rln_list_assets`. Never invent a recipient.
+
+### `rln_pay_invoice` — { invoice } — 🔒 confirm-gated
+Pays a BOLT11 Lightning invoice from the node. Pass the full invoice string.
+
+### Channels and peers
+- `rln_connect_peer { peer_pubkey_and_addr }` — `pubkey@host:port`. Needed
+  before opening a channel to a peer the node has never seen.
+- `rln_open_channel { peer_pubkey_and_addr, capacity_sat, asset_id?, asset_amount?, push_msat?, is_public? }`
+  — 🔒 confirm-gated. Locks on-chain BTC (and optionally an RGB asset) into a
+  channel. Opening is asynchronous: report the `temporary_channel_id` and
+  suggest checking `rln_list_channels`.
+- `rln_get_channel_id { temporary_channel_id }` — the final `channel_id` once
+  the channel is established.
+- `rln_close_channel { channel_id, peer_pubkey, force? }` — 🔒 confirm-gated.
+  Both values come from `rln_list_channels`. `force` only for an unresponsive
+  peer.
+
+### `rln_list_payments` — { limit? }
+Recent Lightning payments, sent and received. Use for "did I get paid" /
+"what did I pay" over Lightning.
+
+### `rln_list_swaps` / `rln_get_swap { payment_hash, taker? }`
+Atomic swaps as the node sees them (HTLC status). For the maker-side status use
+`kaleidoswap_atomic_status`.
 
 ### `rln_atomic_taker` — { swapstring } — 🔒 confirm-gated
 Tell the node "I accept this swap." Args: the `swapstring` returned by
@@ -92,22 +157,74 @@ Call this **after** `kaleidoswap_atomic_init` and **before**
 ### `rln_create_ln_invoice` — Lightning invoice for receiving sats
 Args:
 - `amount_sats` (optional) — omit for an amountless invoice.
-- `expiry_sec` (default 3600) — invoice TTL in seconds.
-- `asset_id` + `asset_amount` — optional, for RGB-over-Lightning.
+- `description` (optional, kaleido-mcp) — memo shown to the payer.
+- `expiry_sec` (default 3600, kaleido-mcp only) — invoice TTL in seconds.
+
+Reply with the full `invoice` string from the result — never write an invoice
+yourself.
 
 Use when the user wants to **receive** a Lightning payment. Do NOT call inside
 an atomic swap flow unless the user explicitly asked to invoice someone.
 
 ### `rln_create_rgb_invoice` — on-chain RGB receive invoice
-Args:
-- `min_confirmations` (default 1).
-- `witness` (default false).
-- `asset_id` (optional — omit for an any-asset invoice).
-- `expiration_timestamp` (optional, Unix seconds).
+Args (use the names in your schema):
+- in-app wallets: `asset` (ticker or asset_id) + `amount`.
+- kaleido-mcp: `asset_id` (the `rgb:…` id from `rln_list_assets` — never a
+  ticker; omit for an any-asset invoice), `amount` (display units),
+  `duration_seconds` (default 86400).
+
+Reply with the full `invoice` string; the payer needs all of it.
 
 Use when the user wants to **receive** an RGB asset directly (not over
 Lightning). Outside the atomic swap flow.
 
+### `rln_list_transfers` — { asset_id }
+Transfers for one asset (issuance, sends, receives) with `status`
+(`WaitingCounterparty`, `WaitingConfirmations`, `Settled`, `Failed`). Use it to
+answer "has my RGB invoice been paid?". Pass the `asset_id` (`rgb:…`) from
+`rln_list_assets` or `rln_issue_asset`; in-app wallets also accept a ticker.
+
+### `rln_create_utxos` — { num?, size?, up_to?, fee_rate? } — 🔒 confirm-gated
+Creates colorable UTXOs (spends a little on-chain BTC). A fresh node needs
+these before it can **issue** or **receive** RGB assets. Call it when an RGB
+call fails with "no available UTXOs", then retry the original action. The
+defaults (`num` 5, `fee_rate` 1) are fine; set `up_to: true` to only top up to
+`num` free UTXOs.
+
+### `rln_issue_asset` — { name, ticker?, amount?, precision?, schema?, details? } — 🔒 confirm-gated
+Creates a **new** RGB asset owned by this node. `schema`: `NIA` fungible token
+(default), `CFA` collectible, `UDA` unique asset / NFT (supply 1).
+- `ticker` (uppercase, 1–8 letters/digits, nothing else) is required for `NIA`
+  and `UDA`.
+- `amount` is the total supply in display units (a number), required for `NIA`
+  and `CFA` — if the user did not say how many, ask before calling;
+  the raw supply is `amount × 10^precision` (`precision` defaults to 0).
+- `details` is an optional description for `CFA` and `UDA`.
+
+Reply with the returned `asset_id` — the user needs it to invoice or send the
+new asset.
+
+Examples:
+- "issue 1000 TICKET tokens called Hackathon Ticket" →
+  `rln_issue_asset { name: "Hackathon Ticket", ticker: "TICKET", amount: 1000 }`
+- "mint an NFT called Genesis Badge" →
+  `rln_issue_asset { name: "Genesis Badge", ticker: "GENESISB", schema: "UDA" }`
+- "has anyone paid my TICKET invoice?" → `rln_refresh_transfers` →
+  `rln_list_transfers { asset_id: "<TICKET asset_id from rln_list_assets>" }`
+
+kaleido-mcp exposes these three as `wdk_issue_asset`, `wdk_create_utxos` and
+`wdk_list_transfers`, with the same arguments and `rln_*` aliases.
+
+### Recipe: issue your own RGB asset
+1. `rln_get_node_info` — the node is reachable and unlocked.
+2. `rln_create_utxos {}` — skip if the node already has free colored UTXOs;
+   wait for the funding tx to confirm before issuing.
+3. `rln_issue_asset { name, ticker, amount }` — confirm with the user first.
+4. `rln_create_rgb_invoice` on the receiver's node, then `rln_send_asset` with
+   the new `asset_id` to distribute it.
+5. `rln_refresh_transfers` → `rln_list_transfers { asset_id }` until the
+   transfer is `Settled`.
+
 ## The maker / node split
 
 A user-driven swap on KaleidoSwap is a two-service flow. Keep them straight:
@@ -125,6 +242,14 @@ The node's two contributions to the swap are the **pubkey** and the
 **whitelist ack** — nothing more. Don't reach for `/makerinit` or
 `/makerexecute`; those are for nodes that act AS the maker, which is not us.
 
+## Safety
+
+- Show amount, recipient and asset before any send; the engine also asks for
+  confirmation on every 🔒 tool.
+- Flag a send above half of the available balance.
+- If the node is unreachable or the wallet is locked, use the `kaleido-node`
+  skill (start / unlock) before retrying.
+
 ## Reply style
 
 - One short sentence built from the tool result.

package/skills/spark-wallet/SKILL.md

@@ -3,6 +3,7 @@ name: spark-wallet
 description: "Operate the user's Spark BTC wallet on this device — check Spark balance, get a Spark deposit address, create a Spark Lightning invoice to receive, pay any BOLT11 Lightning invoice with Spark, or send BTC on-chain from Spark. Use this when the user names Spark explicitly OR when paying a Lightning invoice on a phone where Spark is the connected layer. Pairs with the bitrefill skill: a Bitrefill purchase that returns a Lightning invoice is paid with `spark_pay_invoice`."
 tools: spark_get_balance, spark_get_address, spark_get_onchain_address, spark_create_invoice, spark_pay_invoice, spark_send, get_price, fiat_to_sats, bitrefill_search, bitrefill_get_product, bitrefill_get_balance, bitrefill_create_invoice, bitrefill_get_invoice, bitrefill_get_order
 triggers: spark, sprak, spakr, spark wallet, pay with spark, send with spark, spark balance, spark address, spark invoice, lightning invoice, pay invoice, bolt11, ln invoice, pay this invoice, on-chain address, onchain address, deposit address, deposit btc, fund spark
+requires-tools: spark_get_balance
 metadata:
   author: kaleidoswap
   version: "1.0.0"

package/skills/submarine-swaps/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: submarine-swaps
+description: "Pay a Lightning invoice from Liquid funds (L-USDT or L-BTC) through a KaleidoSwap submarine swap on the /v2 maker, and follow its status. Triggers when the user wants to pay a Lightning invoice with Liquid USDT / L-USDT / L-BTC, asks what Liquid assets can pay Lightning, or asks about a submarine swap."
+tools: kaleidoswap_submarine_pairs, kaleidoswap_submarine_create, kaleidoswap_submarine_fund, kaleidoswap_submarine_status
+triggers: l-usdt, liquid usdt, usdt on liquid, l-btc, liquid bitcoin, submarine, submarine swap, pay invoice with liquid, swap status
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+---
+
+# Submarine swaps — pay Lightning from Liquid
+
+A submarine swap pays a Lightning (BOLT11) invoice with funds the user locks on
+Liquid. The KaleidoSwap maker pays the invoice, then claims the lockup. It is
+atomic: if the maker can't pay, the lockup is refunded to the user.
+
+## Critical rules
+
+- Every amount, fee and status in your reply MUST come from a tool result in the
+  CURRENT turn. Never guess the amount to lock — `kaleidoswap_submarine_create`
+  returns it.
+- `kaleidoswap_submarine_fund` moves money. Call it ONLY after the user has
+  confirmed the exact `expected_amount` returned by `kaleidoswap_submarine_create`.
+- `kaleidoswap_submarine_fund` takes only `swap_id`. Never try to pass an amount
+  or an address.
+- A bare "USDT" means RGB USDT on the Lightning node, which uses the atomic swap
+  tools, not this skill. Use this skill only for Liquid assets (L-USDT, L-BTC).
+
+## Flow
+
+1. `kaleidoswap_submarine_create { invoice, from_asset }` — from_asset is
+   `L-USDT` (default) or `L-BTC`. Returns `swap_id`, `expected_amount` (smallest
+   unit: L-USDT has 8 decimals, L-BTC is sats) and the fees.
+2. Tell the user the amount and ask to confirm.
+3. `kaleidoswap_submarine_fund { swap_id }`.
+4. `kaleidoswap_submarine_status { swap_id }` — `transaction.claimed` means the
+   invoice was paid. `failed: true` on a funded swap means the funds need a refund;
+   say so and quote the `refund` field.
+
+Use `kaleidoswap_submarine_pairs` when the user asks what can pay a Lightning
+invoice, or for the limits and fees.
+
+## Examples
+
+- "pay lntbs10u1p… with L-USDT" →
+  `kaleidoswap_submarine_create { invoice: "lntbs10u1p…", from_asset: "L-USDT" }`
+- "did my Liquid payment go through? swap sub1" →
+  `kaleidoswap_submarine_status { swap_id: "sub1" }`

package/src/context/compress.ts

@@ -48,6 +48,7 @@ export const DEFAULT_PRESERVE_KEYS: readonly string[] = [
   'total',
   'total_sats',
   'balance',
+  'balance_display',
   'balance_sat',
   'address',
   'invoice',

package/src/context/rgb-units.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { annotateRgbBalances, fixRgbBalanceUnits, formatRgbAmount } from './rgb-units.js';
+
+const LIST = {
+  assets: [
+    { asset_id: 'rgb:usdt', ticker: 'USDT', name: 'Tether USD', precision: 0, balance: { settled: 1000, spendable: 1000 } },
+    { asset_id: 'rgb:xaut', ticker: 'XAUT', name: 'Tether Gold', precision: 0, balance: { spendable: 2 } },
+    { asset_id: 'rgb:dec', ticker: 'DEC', precision: 6, balance: { spendable: 1_500_000 } },
+  ],
+};
+
+describe('RGB balance units', () => {
+  it('formats raw amounts with the asset precision', () => {
+    expect(formatRgbAmount(1_500_000, 6)).toBe('1.5');
+    expect(formatRgbAmount(1_000_000, 0)).toBe('1,000,000');
+  });
+
+  it('adds balance_display next to each asset balance without touching the rest', () => {
+    const out = annotateRgbBalances(LIST) as typeof LIST & { assets: Array<{ balance_display: Record<string, string> }> };
+    expect(out.assets[0]!.balance_display).toEqual({ settled: '1,000 USDT', spendable: '1,000 USDT' });
+    expect(out.assets[2]!.balance_display).toEqual({ spendable: '1.5 DEC' });
+    expect(out.assets[0]!.balance).toEqual({ settled: 1000, spendable: 1000 });
+    expect(annotateRgbBalances({ vanilla: { spendable: 4277 } })).toEqual({ vanilla: { spendable: 4277 } });
+  });
+
+  it('relabels the asset balances the 2B model called satoshis', () => {
+    const answer =
+      'You hold two RGB assets:\n1. **USDT** (Tether USD)\n   - Balance: 1,000 satoshis (spendable)\n' +
+      '2. **XAUT** (Tether Gold)\n   - Balance: 2 satoshis (spendable)';
+    expect(fixRgbBalanceUnits(answer, [LIST])).toBe(
+      'You hold two RGB assets:\n1. **USDT** (Tether USD)\n   - Balance: 1,000 USDT (spendable)\n' +
+        '2. **XAUT** (Tether Gold)\n   - Balance: 2 XAUT (spendable)',
+    );
+    expect(fixRgbBalanceUnits('DEC balance: 1,500,000 sats', [LIST])).toBe('DEC balance: 1.5 DEC');
+  });
+
+  it('leaves real sats and unmatched numbers alone', () => {
+    const btc = { btc: { vanilla: { spendable: 4277 } } };
+    expect(fixRgbBalanceUnits('Your on-chain balance is 4,277 sats.', [btc, LIST])).toBe('Your on-chain balance is 4,277 sats.');
+    expect(fixRgbBalanceUnits('USDT channel fee: 300 sats', [LIST])).toBe('USDT channel fee: 300 sats');
+  });
+});

package/src/context/rgb-units.ts

@@ -0,0 +1,89 @@
+/**
+ * RGB asset balances are raw integers in the asset's own unit, scaled by its
+ * `precision`. Nothing in the tool result says so, and small models fill the
+ * gap with "satoshis" ("USDT — Balance: 1,000 satoshis").
+ *
+ * `annotateRgbBalances` adds a `balance_display` next to each asset's
+ * `balance` before the result reaches the model ("1,000 USDT").
+ * `fixRgbBalanceUnits` corrects a final answer that still labels an asset
+ * balance as sats: the number must equal one of that asset's balances and the
+ * nearest ticker before it must be that asset's.
+ */
+
+type Obj = Record<string, unknown>;
+
+interface RgbAsset {
+  ticker: string;
+  precision: number;
+  amounts: number[];
+}
+
+const BALANCE_FIELDS = ['settled', 'spendable', 'future'] as const;
+
+const isObj = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
+
+function asAsset(v: Obj): RgbAsset | null {
+  if (typeof v.ticker !== 'string' || !v.ticker || !isObj(v.balance)) return null;
+  const amounts = BALANCE_FIELDS.map((k) => (v.balance as Obj)[k]).filter((n): n is number => typeof n === 'number');
+  if (!amounts.length) return null;
+  const precision = typeof v.precision === 'number' && v.precision > 0 ? v.precision : 0;
+  return { ticker: v.ticker, precision, amounts };
+}
+
+/** A raw RGB amount in display units, e.g. 1500000 at precision 6 → "1.5". */
+export function formatRgbAmount(raw: number, precision: number): string {
+  const value = raw / 10 ** precision;
+  return value.toLocaleString('en-US', { maximumFractionDigits: precision });
+}
+
+/** Return a copy of `result` where every RGB asset carries `balance_display`. */
+export function annotateRgbBalances(result: unknown): unknown {
+  if (Array.isArray(result)) return result.map(annotateRgbBalances);
+  if (!isObj(result)) return result;
+  const out: Obj = {};
+  for (const [k, v] of Object.entries(result)) out[k] = annotateRgbBalances(v);
+  const asset = asAsset(result);
+  if (asset) {
+    const balance = result.balance as Obj;
+    const display: Obj = {};
+    for (const k of BALANCE_FIELDS) {
+      if (typeof balance[k] === 'number') display[k] = `${formatRgbAmount(balance[k] as number, asset.precision)} ${asset.ticker}`;
+    }
+    out.balance_display = display;
+  }
+  return out;
+}
+
+function collectAssets(value: unknown, into: RgbAsset[]): void {
+  if (Array.isArray(value)) {
+    for (const v of value) collectAssets(v, into);
+  } else if (isObj(value)) {
+    const asset = asAsset(value);
+    if (asset) into.push(asset);
+    for (const v of Object.values(value)) collectAssets(v, into);
+  }
+}
+
+const AMOUNT_IN_SATS = /(\d[\d,]*(?:\.\d+)?)\s*(?:satoshis|sats?)\b/gi;
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Relabel asset balances that the answer calls sats, using the tool results it was built from. */
+export function fixRgbBalanceUnits(text: string, toolResults: unknown[]): string {
+  const assets: RgbAsset[] = [];
+  for (const r of toolResults) collectAssets(r, assets);
+  if (!assets.length) return text;
+  const tickerRe = new RegExp(`\\b(${[...new Set(assets.map((a) => escapeRe(a.ticker)))].join('|')})\\b`, 'g');
+
+  return text.replace(AMOUNT_IN_SATS, (match: string, num: string, offset: number) => {
+    let nearest: string | undefined;
+    for (const m of text.slice(Math.max(0, offset - 300), offset).matchAll(tickerRe)) nearest = m[1];
+    if (!nearest) return match;
+    const value = Number(num.replace(/,/g, ''));
+    const asset = assets.find(
+      (a) => a.ticker === nearest && a.amounts.some((raw) => raw === value || raw / 10 ** a.precision === value),
+    );
+    if (!asset) return match;
+    const raw = asset.amounts.find((r) => r === value) ?? value * 10 ** asset.precision;
+    return `${formatRgbAmount(raw, asset.precision)} ${asset.ticker}`;
+  });
+}