@kaleidorg/mind 0.6.4 → 0.7.0

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

@@ -0,0 +1,61 @@
+# KaleidoSwap maker API (what the tools call)
+
+Base URLs: `https://api.kaleidoswap.com` (mainnet),
+`https://api.signet.kaleidoswap.com` (signet, `KALEIDO_NETWORK=signet` in
+kaleido-mcp). The MCP tools wrap these endpoints; you normally never call them
+directly. Amounts on the wire are raw units (see `assets.md`).
+
+| Endpoint | Tool |
+|---|---|
+| `GET /api/v1/market/assets` | `kaleidoswap_get_assets` |
+| `GET /api/v1/market/pairs` | `kaleidoswap_get_pairs` |
+| `POST /api/v1/market/quote` | `kaleidoswap_get_quote` |
+| `POST /api/v1/swaps/init` | `kaleidoswap_atomic_init` |
+| `POST /api/v1/swaps/execute` | `kaleidoswap_atomic_execute` |
+| `POST /api/v1/swaps/atomic/status` | `kaleidoswap_atomic_status` |
+| `GET /api/v1/lsps1/get_info` | `kaleidoswap_lsp_get_info` |
+| `POST /api/v1/lsps1/estimate_fees` | `kaleidoswap_lsp_estimate_fees` |
+| `POST /api/v1/lsps1/create_order` | `kaleidoswap_lsp_create_order` |
+| `POST /api/v1/lsps1/get_order` | `kaleidoswap_lsp_get_order` |
+
+## Pairs
+
+```json
+[{
+  "base":  { "ticker": "BTC",  "precision": 11 },
+  "quote": { "ticker": "USDT", "precision": 6 },
+  "routes": [
+    { "from_layer": "BTC_LN", "to_layer": "RGB_LN", "min_amount": 50000,   "max_amount": 10000000000 },
+    { "from_layer": "RGB_LN", "to_layer": "BTC_LN", "min_amount": 1000000, "max_amount": 999999000000 }
+  ]
+}]
+```
+
+`min_amount` / `max_amount` are raw units of the route's `from` asset.
+
+## Quote
+
+```json
+{
+  "rfq_id": "uuid", "expires_at": "2026-01-01T00:01:00Z",
+  "from_asset": { "ticker": "BTC",  "layer": "BTC_LN", "amount_raw": 100000000, "amount_display": 0.001 },
+  "to_asset":   { "ticker": "USDT", "layer": "RGB_LN", "amount_raw": 65763000,  "amount_display": 65.763 },
+  "price": 65763.0
+}
+```
+
+## Swap
+
+- `init` → `{ swapstring, payment_hash, access_token }` (`access_token` only here)
+- `execute` takes `{ swapstring, taker_pubkey, payment_hash }`
+- `status` takes `{ payment_hash, access_token }` →
+  `{ swap: { status: "Waiting" | "Pending" | "Succeeded" | "Expired" | "Failed" } }`
+
+## LSPS1 orders
+
+`estimate_fees` / `create_order` take `{ client_pubkey, lsp_balance_sat,
+client_balance_sat, channel_expiry_blocks }`. `create_order` returns
+`{ order_id, bolt11_invoice, order_total_sat }`; `get_order` reports
+`PENDING → CHANNEL_OPENING → COMPLETED | FAILED`. Good defaults:
+`lsp_balance_sat = 500000`, `client_balance_sat = 0`,
+`channel_expiry_blocks = 4320`.

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

@@ -0,0 +1,57 @@
+# Assets, units and precision
+
+Asset ids differ between signet and mainnet and may rotate on signet. Always
+discover them with `kaleidoswap_get_assets()` (cache for at most ~5 minutes);
+never hard-code them.
+
+```json
+{ "asset_id": "BTC" | "rgb:...", "ticker": "USDT", "name": "...", "precision": 6 }
+```
+
+Some environments omit BTC from the assets list; `kaleidoswap_get_pairs()`
+always includes it.
+
+## Units
+
+BTC uses **millisatoshis** as its raw unit (precision 11):
+
+```
+1 BTC     = 100,000,000 sats = 1e11 msat
+0.001 BTC =     100,000 sats = 1e8 msat
+1 sat     = 1,000 msat
+```
+
+RGB assets use their own precision:
+
+```
+raw     = round(display × 10^precision)
+display = raw / 10^precision
+```
+
+| Asset | Typical precision | Raw unit |
+|---|---|---|
+| BTC | 11 | msat |
+| USDT | 6 | micro-USDT |
+| XAUT | 9 | nano-XAUT |
+
+Read precision from the API; the table is illustrative.
+
+## Which unit each tool takes
+
+| Tool | Units |
+|---|---|
+| `kaleidoswap_get_quote` (kaleido-mcp) | display (`0.001` BTC, `65.0` USDT) |
+| `kaleidoswap_atomic_init` (kaleido-mcp) | raw: pass `quote.*.amount_raw` unchanged |
+| `kaleidoswap_get_quote` (in-app contract) | sats for BTC, asset units otherwise |
+| `rln_send_asset` / `rln_create_rgb_invoice` (kaleido-mcp) | display units |
+
+## Mapping user words
+
+- "BTC" over Lightning → `asset_id: "BTC"`, layer `BTC_LN`; on-chain → `BTC_L1`.
+- "USDT" → the asset whose `ticker === "USDT"`. "USD" usually means USDT: confirm.
+- "gold" / "XAUT" → `ticker === "XAUT"`. Confirm "gold".
+
+## Layers
+
+`BTC_L1`, `BTC_LN`, `BTC_SPARK`, `BTC_ARKADE`, `RGB_L1`, `RGB_LN`. Use the
+values from `kaleidoswap_get_pairs()` routes verbatim.

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.2"
 ---
 
 # RGB Lightning Node (taker-side)
@@ -79,6 +79,58 @@ hold / what's my USDT balance".
 Balance for one RGB asset by id. Use after `rln_list_assets` gave you the id,
 or when the user names a specific asset.
 
+| 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 }`. 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
 `kaleidoswap_atomic_init`. The node validates and stores it; **no funds move
@@ -92,22 +144,67 @@ 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.
+- `expiry_sec` (default 3600, kaleido-mcp only) — invoice TTL in seconds.
 
 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` (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) is required for `NIA` and `UDA`.
+- `amount` is the total supply in display units, required for `NIA` and `CFA`;
+  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 +222,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/src/index.ts

@@ -129,6 +129,9 @@ export {
 // ── Buy-an-asset-channel recipe (opt-in — register via Funnel.recipes) ─────
 export { buyAssetChannelRecipe, extractBuyAsset } from './recipe/buy-asset-channel.js';
 
+// ── Issue-an-RGB-asset recipe (opt-in — register via Funnel.recipes) ───────
+export { issueAssetRecipe, extractIssueAsset } from './recipe/issue-asset.js';
+
 // ── Recipes (mobile multi-step: "recipes, not planning") ───────────────────
 export { runRecipe, extractSlots, RecipeRegistry } from './recipe/runner.js';
 export type { RunRecipeOptions } from './recipe/runner.js';

package/src/qvac/delegate.ts

@@ -4,6 +4,8 @@
  * they stay shared + testable; the host passes the result to
  * `startQVACProvider({ firewall })` / `loadModel({ delegate })`.
  *
+ * P2P delegation exists in @qvac/sdk 0.13–0.18 only; 0.19 removed both calls.
+ *
  * Security note: a QVAC provider is reachable by anyone who learns its
  * Hyperswarm public key. Advertising with no firewall means any such peer can
  * run inference on your machine. Use {@link allowListFirewall} so a desktop

package/src/qvac/index.ts

@@ -38,6 +38,8 @@ export {
   type ConsumedTurn,
 } from './stream.js';
 
+export { toQvacTools, type QvacTool, type QvacToolProp } from './tools.js';
+
 export {
   createQvacProvider,
   type QvacProviderOptions,

package/src/qvac/parse.ts

@@ -17,6 +17,9 @@ export interface QvacTurnStats {
   tokensPerSecond?: number;
   totalTokens?: number;
   promptTokens?: number;
+  /** Tokens generated this turn (what the SDK reports; `totalTokens` is not emitted). */
+  generatedTokens?: number;
+  timeToFirstToken?: number;
   contextSize?: number;
   totalTime?: number;
 }
@@ -30,8 +33,8 @@ export interface QvacFinalLike {
   /** Tool calls the model requested this turn (empty ⇒ final answer). */
   toolCalls?: Array<{ id?: string; name: string; arguments?: Record<string, unknown> }>;
   /**
-   * Why generation stopped. QVAC 0.13 emits `"length"` when the token budget is
-   * exhausted, `"cancelled"` on abort, `undefined` on a natural stop. We surface
+   * Why generation stopped: `"length"` when the token budget is exhausted,
+   * `"cancelled"` on abort, `"eos"`/`"stopSequence"`/`undefined` on a natural stop. We surface
    * it so the funnel can tell a truncated tool-call from a complete one.
    */
   stopReason?: 'length' | 'cancelled' | string;

package/src/qvac/provider.test.ts

@@ -77,6 +77,18 @@ describe('createQvacProvider.runTurn', () => {
     expect(params.generationParams).toEqual({ temp: 0.9, predict: 99 });
   });
 
+  it('sends JSON-Schema tools in the SDK Tool shape so arguments survive', async () => {
+    const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    await p.runTurn({
+      messages: [{ role: 'user', content: 'x' }],
+      tools: [{ name: 'echo', description: 'e', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } }],
+    });
+    expect(calls[0].tools).toEqual([
+      { type: 'function', name: 'echo', description: 'e', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } },
+    ]);
+  });
+
   it('omits generationParams when no temperature/maxTokens is set (keeps SDK defaults)', async () => {
     const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
     const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
@@ -101,6 +113,32 @@ describe('createQvacProvider.runTurn', () => {
     expect(out.text).toMatch(/thinking budget/i);
   });
 
+  it('returns a cancelled turn when the SDK rejects final on abort', async () => {
+    const cancel = vi.fn(async () => {});
+    const fn = () => ({
+      requestId: 'req-a',
+      events: (async function* () {})(),
+      final: Promise.reject(Object.assign(new Error('cancelled'), { requestId: 'req-a', partial: {} })),
+    });
+    const ac = new AbortController();
+    ac.abort();
+    const p = createQvacProvider({ completion: fn as any, cancel: cancel as any, getModelId: () => 'm1' });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [], signal: ac.signal });
+    expect(cancel).toHaveBeenCalledWith({ requestId: 'req-a' });
+    expect(out.inference?.status).toBe('cancelled');
+    expect(out.toolCalls).toEqual([]);
+  });
+
+  it('derives token counts from the SDK generatedTokens stat', async () => {
+    const { fn } = fakeCompletion({
+      contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' },
+      stats: { promptTokens: 100, generatedTokens: 20, tokensPerSecond: 12, backendDevice: 'gpu' },
+    });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    const out = await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] });
+    expect(out.inference).toMatchObject({ promptTokens: 100, totalTokens: 120, completionTokens: 20, backendDevice: 'gpu' });
+  });
+
   it('streams visible content tokens to onToken', async () => {
     const { fn } = fakeCompletion(
       { contentText: 'Hi there', toolCalls: [], raw: { fullText: 'Hi there' } },

package/src/qvac/provider.ts

@@ -20,6 +20,7 @@ import type * as QvacSdk from '@qvac/sdk';
 import type { InferenceMetrics, LLMProvider, TurnInput, TurnOutput } from '../providers/types.js';
 import type { QvacTurnStats } from './parse.js';
 import { consumeRun } from './stream.js';
+import { toQvacTools } from './tools.js';
 
 type CompletionFn = typeof QvacSdk.completion;
 type CancelFn = typeof QvacSdk.cancel;
@@ -82,19 +83,11 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
         ? [{ role: 'system', content: input.system }, ...input.messages]
         : input.messages;
 
-      // Tools are forwarded by schema only (name/description/parameters). We
-      // carry `parameters` through verbatim (Zod for in-process tools, JSON
-      // Schema for MCP) — the model only needs the shape to pick a call; the
-      // Engine validates + executes.
-      const tools = input.tools.length
-        ? input.tools.map((t) => ({
-            name: t.name,
-            description: t.description,
-            parameters: t.parameters,
-          }))
-        : undefined;
-
-      // QVAC 0.13 nests sampling under `generationParams`; top-level
+      // Tools are forwarded by schema only — the Engine validates + executes.
+      // JSON-Schema tools are normalised to the SDK's Tool shape (see tools.ts).
+      const tools = toQvacTools(input.tools);
+
+      // QVAC (0.13+) nests sampling under `generationParams`; top-level
       // `temperature`/`max_tokens` (as older rate code passed) are dropped by
       // validation, so the cap silently no-op'd. Build it here, and only send it
       // when a value is set so a host that passes neither keeps SDK defaults.
@@ -155,8 +148,11 @@ export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
       // instead of an empty bubble so the agentic loop ends cleanly.
       const text =
         result.text || (result.thinkingBudgetExceeded ? THINKING_BUDGET_FALLBACK : result.text);
-      const totalTokens = result.stats?.totalTokens;
       const promptTokens = result.stats?.promptTokens;
+      const generated = result.stats?.generatedTokens;
+      const totalTokens =
+        result.stats?.totalTokens ??
+        (typeof generated === 'number' && typeof promptTokens === 'number' ? promptTokens + generated : undefined);
       const inference: InferenceMetrics = {
         requestId: result.requestId,
         durationMs: result.timing.durationMs,

package/src/qvac/stream.test.ts

@@ -112,4 +112,32 @@ describe('consumeRun', () => {
     );
     expect(out.timing).toEqual({ ttftMs: 45, durationMs: 90 });
   });
+
+  it('folds a rejected final (InferenceCancelledError) into a cancelled turn', async () => {
+    class InferenceCancelledError extends Error {
+      constructor(readonly requestId: string, readonly partial: { text?: string }) {
+        super('cancelled');
+      }
+    }
+    const run: CompletionRunLike = {
+      requestId: 'req-c',
+      events: (async function* () {
+        yield { type: 'contentDelta', text: 'Partial' };
+      })(),
+      final: Promise.reject(new InferenceCancelledError('req-c', { text: 'Partial' })),
+    };
+    const out = await consumeRun(run);
+    expect(out.stopReason).toBe('cancelled');
+    expect(out.text).toBe('Partial');
+    expect(out.toolCalls).toEqual([]);
+  });
+
+  it('re-throws a rejected final that is not a cancellation', async () => {
+    const run: CompletionRunLike = {
+      requestId: 'req-e',
+      events: (async function* () {})(),
+      final: Promise.reject(new Error('boom')),
+    };
+    await expect(consumeRun(run)).rejects.toThrow('boom');
+  });
 });