From d3d352a37a3cf729d84f77483a6f4067b3ca7fc9 Mon Sep 17 00:00:00 2001 From: Emile Jellinek Date: Thu, 13 Aug 2026 16:50:05 +0200 Subject: [PATCH] docs: add Simplified Chinese translation Adds a full zh-Hans localization of the docs, covering all 80 pages across every tab, and restructures docs.json onto navigation.languages so Mintlify serves a language switcher. English pages stay at the repo root and keep their current URLs; the translation mirrors the tree under mintlify-docs/cn/. openapi.json and snippets/ are shared, not duplicated, so version numbers and the API spec keep a single source of truth. Tab and group labels, sidebar anchors, and the navbar are localized per language, since Mintlify does not translate docs.json UI copy. Anchor links are handled by pinning the English slug onto the translated heading with Mintlify's {#custom-id} syntax, rather than rewriting fragments to a slug derived from Chinese text. Links keep working if a heading is later reworded, and correctness does not depend on how CJK text gets slugified. Adds TRANSLATION-GUIDE.md (rules plus a ~60 term glossary) and two scripts that keep the tree honest as the English docs change: scripts/check-cn-parity.py coverage, structural parity, links, anchors scripts/pin-cn-anchors.py pins anchor ids, idempotent check-cn-parity.py currently reports no findings: 80/80 pages present, no structural drift from the English sources, no broken or unprefixed links, no unresolved anchors. Co-Authored-By: Claude Opus 5 --- TRANSLATION-GUIDE.md | 174 ++++ .../cn/ai-tools/additional-resources.mdx | 91 ++ mintlify-docs/cn/ai-tools/faq.mdx | 115 +++ mintlify-docs/cn/ai-tools/getting-started.mdx | 123 +++ mintlify-docs/cn/ai-tools/installation.mdx | 88 ++ mintlify-docs/cn/ai-tools/introduction.mdx | 34 + mintlify-docs/cn/ai-tools/kaleido-agent.mdx | 174 ++++ mintlify-docs/cn/ai-tools/kaleido-mind.mdx | 79 ++ mintlify-docs/cn/ai-tools/mcp-servers.mdx | 307 +++++++ mintlify-docs/cn/ai-tools/skills.mdx | 31 + mintlify-docs/cn/ai-tools/troubleshooting.mdx | 217 +++++ .../cn/api-reference/error-handling.mdx | 143 +++ .../cn/api-reference/getting-started.mdx | 160 ++++ .../cn/api-reference/introduction.mdx | 130 +++ .../cn/api-reference/market-apis.mdx | 392 ++++++++ .../cn/api-reference/rgb-lsps1-apis.mdx | 317 +++++++ mintlify-docs/cn/api-reference/swap-apis.mdx | 299 +++++++ .../cn/api-reference/swap-protocol.mdx | 136 +++ mintlify-docs/cn/cli/channels-lsp.mdx | 110 +++ mintlify-docs/cn/cli/command-reference.mdx | 206 +++++ mintlify-docs/cn/cli/getting-started.mdx | 150 ++++ mintlify-docs/cn/cli/introduction.mdx | 94 ++ mintlify-docs/cn/cli/market-and-swaps.mdx | 101 +++ mintlify-docs/cn/cli/node-environments.mdx | 138 +++ .../cn/cli/wallet-assets-payments.mdx | 136 +++ .../desktop-app/channels/channel-backups.mdx | 77 ++ .../desktop-app/channels/channel-requests.mdx | 53 ++ .../desktop-app/channels/opening-channel.mdx | 52 ++ .../channels/order-new-channel.mdx | 141 +++ .../getting-started/installation.mdx | 93 ++ .../getting-started/introduction.mdx | 67 ++ .../getting-started/node-hosting.mdx | 341 +++++++ .../cn/desktop-app/getting-started/setup.mdx | 75 ++ .../getting-started/verify-binaries.mdx | 155 ++++ .../cn/desktop-app/kaleidomind/brain.mdx | 40 + .../cn/desktop-app/kaleidomind/chat.mdx | 35 + .../support/additional-resources.mdx | 32 + .../cn/desktop-app/support/changelog.mdx | 121 +++ mintlify-docs/cn/desktop-app/support/faq.mdx | 128 +++ .../cn/desktop-app/support/settings.mdx | 108 +++ .../desktop-app/support/troubleshooting.mdx | 135 +++ .../cn/desktop-app/trading/asset-swaps.mdx | 91 ++ .../cn/desktop-app/wallet/creating-wallet.mdx | 47 + .../cn/desktop-app/wallet/deposits.mdx | 36 + .../wallet/initializing-mnemonic.mdx | 55 ++ .../desktop-app/wallet/unlocking-wallet.mdx | 50 ++ .../cn/desktop-app/wallet/withdrawals.mdx | 26 + mintlify-docs/cn/extensions/introduction.mdx | 106 +++ .../additional-resources.mdx | 64 ++ .../kaleidoswap-extension/bridge.mdx | 107 +++ .../dapp-connectivity.mdx | 203 +++++ .../extensions/kaleidoswap-extension/faq.mdx | 105 +++ .../kaleidoswap-extension/getting-started.mdx | 151 ++++ .../kaleidoswap-extension/installation.mdx | 141 +++ .../kaleidoswap-extension/swaps.mdx | 128 +++ .../kaleidoswap-extension/troubleshooting.mdx | 130 +++ .../kaleidoswap-extension/wallet-features.mdx | 257 ++++++ mintlify-docs/cn/sdk/additional-resources.mdx | 85 ++ mintlify-docs/cn/sdk/api-reference.mdx | 210 +++++ mintlify-docs/cn/sdk/best-practices.mdx | 367 ++++++++ mintlify-docs/cn/sdk/changelog.mdx | 162 ++++ mintlify-docs/cn/sdk/error-handling.mdx | 372 ++++++++ mintlify-docs/cn/sdk/examples.mdx | 118 +++ mintlify-docs/cn/sdk/faq.mdx | 106 +++ mintlify-docs/cn/sdk/getting-started.mdx | 267 ++++++ mintlify-docs/cn/sdk/how-to-swap.mdx | 201 +++++ mintlify-docs/cn/sdk/introduction.mdx | 56 ++ .../cn/sdk/maker-api-compatibility.mdx | 70 ++ mintlify-docs/cn/sdk/nwc.mdx | 86 ++ .../cn/sdk/rln-api-compatibility.mdx | 80 ++ mintlify-docs/cn/sdk/troubleshooting.mdx | 390 ++++++++ mintlify-docs/cn/sdk/types.mdx | 136 +++ mintlify-docs/cn/sdk/utilities.mdx | 282 ++++++ mintlify-docs/cn/sdk/websocket.mdx | 362 ++++++++ .../cn/whats-kaleidoswap/architecture.mdx | 195 ++++ .../cn/whats-kaleidoswap/background.mdx | 122 +++ .../cn/whats-kaleidoswap/glossary.mdx | 391 ++++++++ .../cn/whats-kaleidoswap/introduction.mdx | 201 +++++ .../cn/whats-kaleidoswap/key-features.mdx | 423 +++++++++ .../cn/whats-kaleidoswap/quickstart.mdx | 274 ++++++ .../cn/whats-kaleidoswap/troubleshooting.mdx | 560 ++++++++++++ mintlify-docs/docs.json | 840 ++++++++++++------ scripts/check-cn-parity.py | 254 ++++++ scripts/pin-cn-anchors.py | 253 ++++++ 84 files changed, 13901 insertions(+), 257 deletions(-) create mode 100644 TRANSLATION-GUIDE.md create mode 100644 mintlify-docs/cn/ai-tools/additional-resources.mdx create mode 100644 mintlify-docs/cn/ai-tools/faq.mdx create mode 100644 mintlify-docs/cn/ai-tools/getting-started.mdx create mode 100644 mintlify-docs/cn/ai-tools/installation.mdx create mode 100644 mintlify-docs/cn/ai-tools/introduction.mdx create mode 100644 mintlify-docs/cn/ai-tools/kaleido-agent.mdx create mode 100644 mintlify-docs/cn/ai-tools/kaleido-mind.mdx create mode 100644 mintlify-docs/cn/ai-tools/mcp-servers.mdx create mode 100644 mintlify-docs/cn/ai-tools/skills.mdx create mode 100644 mintlify-docs/cn/ai-tools/troubleshooting.mdx create mode 100644 mintlify-docs/cn/api-reference/error-handling.mdx create mode 100644 mintlify-docs/cn/api-reference/getting-started.mdx create mode 100644 mintlify-docs/cn/api-reference/introduction.mdx create mode 100644 mintlify-docs/cn/api-reference/market-apis.mdx create mode 100644 mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx create mode 100644 mintlify-docs/cn/api-reference/swap-apis.mdx create mode 100644 mintlify-docs/cn/api-reference/swap-protocol.mdx create mode 100644 mintlify-docs/cn/cli/channels-lsp.mdx create mode 100644 mintlify-docs/cn/cli/command-reference.mdx create mode 100644 mintlify-docs/cn/cli/getting-started.mdx create mode 100644 mintlify-docs/cn/cli/introduction.mdx create mode 100644 mintlify-docs/cn/cli/market-and-swaps.mdx create mode 100644 mintlify-docs/cn/cli/node-environments.mdx create mode 100644 mintlify-docs/cn/cli/wallet-assets-payments.mdx create mode 100644 mintlify-docs/cn/desktop-app/channels/channel-backups.mdx create mode 100644 mintlify-docs/cn/desktop-app/channels/channel-requests.mdx create mode 100644 mintlify-docs/cn/desktop-app/channels/opening-channel.mdx create mode 100644 mintlify-docs/cn/desktop-app/channels/order-new-channel.mdx create mode 100644 mintlify-docs/cn/desktop-app/getting-started/installation.mdx create mode 100644 mintlify-docs/cn/desktop-app/getting-started/introduction.mdx create mode 100644 mintlify-docs/cn/desktop-app/getting-started/node-hosting.mdx create mode 100644 mintlify-docs/cn/desktop-app/getting-started/setup.mdx create mode 100644 mintlify-docs/cn/desktop-app/getting-started/verify-binaries.mdx create mode 100644 mintlify-docs/cn/desktop-app/kaleidomind/brain.mdx create mode 100644 mintlify-docs/cn/desktop-app/kaleidomind/chat.mdx create mode 100644 mintlify-docs/cn/desktop-app/support/additional-resources.mdx create mode 100644 mintlify-docs/cn/desktop-app/support/changelog.mdx create mode 100644 mintlify-docs/cn/desktop-app/support/faq.mdx create mode 100644 mintlify-docs/cn/desktop-app/support/settings.mdx create mode 100644 mintlify-docs/cn/desktop-app/support/troubleshooting.mdx create mode 100644 mintlify-docs/cn/desktop-app/trading/asset-swaps.mdx create mode 100644 mintlify-docs/cn/desktop-app/wallet/creating-wallet.mdx create mode 100644 mintlify-docs/cn/desktop-app/wallet/deposits.mdx create mode 100644 mintlify-docs/cn/desktop-app/wallet/initializing-mnemonic.mdx create mode 100644 mintlify-docs/cn/desktop-app/wallet/unlocking-wallet.mdx create mode 100644 mintlify-docs/cn/desktop-app/wallet/withdrawals.mdx create mode 100644 mintlify-docs/cn/extensions/introduction.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/bridge.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/dapp-connectivity.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/installation.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/swaps.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx create mode 100644 mintlify-docs/cn/extensions/kaleidoswap-extension/wallet-features.mdx create mode 100644 mintlify-docs/cn/sdk/additional-resources.mdx create mode 100644 mintlify-docs/cn/sdk/api-reference.mdx create mode 100644 mintlify-docs/cn/sdk/best-practices.mdx create mode 100644 mintlify-docs/cn/sdk/changelog.mdx create mode 100644 mintlify-docs/cn/sdk/error-handling.mdx create mode 100644 mintlify-docs/cn/sdk/examples.mdx create mode 100644 mintlify-docs/cn/sdk/faq.mdx create mode 100644 mintlify-docs/cn/sdk/getting-started.mdx create mode 100644 mintlify-docs/cn/sdk/how-to-swap.mdx create mode 100644 mintlify-docs/cn/sdk/introduction.mdx create mode 100644 mintlify-docs/cn/sdk/maker-api-compatibility.mdx create mode 100644 mintlify-docs/cn/sdk/nwc.mdx create mode 100644 mintlify-docs/cn/sdk/rln-api-compatibility.mdx create mode 100644 mintlify-docs/cn/sdk/troubleshooting.mdx create mode 100644 mintlify-docs/cn/sdk/types.mdx create mode 100644 mintlify-docs/cn/sdk/utilities.mdx create mode 100644 mintlify-docs/cn/sdk/websocket.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/architecture.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/background.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/glossary.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/introduction.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/key-features.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx create mode 100644 mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx create mode 100644 scripts/check-cn-parity.py create mode 100644 scripts/pin-cn-anchors.py diff --git a/TRANSLATION-GUIDE.md b/TRANSLATION-GUIDE.md new file mode 100644 index 0000000..d5cf805 --- /dev/null +++ b/TRANSLATION-GUIDE.md @@ -0,0 +1,174 @@ +# Translation Guide — Simplified Chinese (`cn`) + +Canonical rules and glossary for the Chinese localization of the KaleidoSwap docs. +Read this before translating or updating any file under `mintlify-docs/cn/`. + +## Layout + +- English (default language) stays at the repo root: `mintlify-docs/
/.mdx`. +- Simplified Chinese mirrors that tree one-to-one under `mintlify-docs/cn/`: + `mintlify-docs/whats-kaleidoswap/introduction.mdx` → `mintlify-docs/cn/whats-kaleidoswap/introduction.mdx` +- `docs.json` declares both under `navigation.languages` (`en` first, then `cn`). + Adding or removing a page means updating **both** language trees. +- `mintlify-docs/snippets/` is shared. Chinese pages import the same snippet with the + same absolute path (`/snippets/versions.mdx`) — do not duplicate it. +- `mintlify-docs/openapi.json` is shared and not translated. + +## Tooling + +Run both after any change to the `cn/` tree: + +```bash +python scripts/check-cn-parity.py # structure, links, anchors, coverage +python scripts/pin-cn-anchors.py # add --apply to write +``` + +`check-cn-parity.py` compares every translated page against its English source +(heading count, code fences, components, table rows, images, links), confirms each +page in the `cn` navigation exists, and verifies every internal link is `/cn`-prefixed +and resolves. It exits with `PROBLEMS FOUND` if anything is off. + +## What to translate + +Translate: + +- Prose, headings, list items, table cells. +- Frontmatter **values** for `title`, `sidebarTitle`, `description`. + For `description`, target **60–80 CJK characters**, not the 150–160 used for + English. CJK glyphs are roughly double-width, so 60–80 of them occupy the same + space in a search result as a 150–160 character English description. Do not pad + a description to hit a count. +- User-facing component props: `title=`, `label=`, `header=`, `` text, + ``, ``, ``, ``. +- Image `alt` text (the square-bracket part of `![alt](path)`). +- Comments inside code blocks (`// ...`, `# ...`). + +Leave in English / untouched: + +- Product and brand names: KaleidoSwap, KaleidoMind, KaleidoAgent, Thunderstack. +- Protocol and standard names: Bitcoin, Lightning, RGB, Taproot Assets, LSPS1, NWC, + HTLC, PSBT, UTXO, MCP, QVAC. +- All code: identifiers, string literals, JSON keys, API field names, CLI commands + and flags, env vars, file paths, package names, URLs, version numbers. +- Code-fence language tags and their tab titles (```` ```typescript TypeScript ````). +- Component and prop **names**, and icon/layout values (`icon="wallet"`, `cols={2}`, + `horizontal`, `openapi=`). +- Image paths (`/assets/images/...`) — only the alt text changes. +- Network names: mainnet is 主网 and testnet is 测试网, but `signet` and `regtest` + stay lowercase in English. + +## Links + +- Rewrite every internal absolute link to the `cn` tree: + `[SDK](/sdk/introduction)` → `[SDK](/cn/sdk/introduction)` +- External links (`https://…`) are unchanged, including their `#fragments`. +- **Anchor fragments on internal links:** leave the English fragment verbatim + (e.g. `/cn/sdk/websocket#events`), including same-page anchors (`](#some-heading)`). + Do not translate fragments and do not guess another page's headings. + +### How anchors survive translation + +Mintlify derives a heading's anchor from its text, so translating a heading would +break every link pointing at it. Instead, any heading that is the target of a link +carries an explicit id with the **English** slug, using Mintlify's `{#custom-id}` +syntax: + +```mdx +## 客户端配置 {#client-configuration} +``` + +The link stays `](/cn/ai-tools/mcp-servers#client-configuration)` and keeps working +no matter how the heading text is later reworded. Consequences: + +- Never reorder or drop headings in a translated page — `scripts/pin-cn-anchors.py` + maps English to Chinese headings by position. +- After adding or changing any cross-page anchor link, re-run that script; it pins + the ids it needs and reports anything it cannot resolve. +- Headings with no inbound links need no id. Mintlify generates both the id and its + own table-of-contents link, so those stay self-consistent. +- A fragment containing `&` is normalised (`installation-&-configuration` becomes + `installation-and-configuration`) and the `cn` links are repointed to match. + Mintlify keeps `&` when it generates a slug from heading text, but its handling of + `&` inside an explicit `{#id}` is undocumented; since both sides live in the `cn` + tree, the script picks an id that cannot be ambiguous. The English pages are + untouched and keep their original `&` anchors. + +## Style + +Audience is Chinese-speaking Bitcoin developers and traders. Aim for the register of +good native technical documentation, not literal translation. + +- Simplified Chinese (简体), mainland conventions. +- Full-width punctuation for Chinese sentences: `，。：；！？、（）「」`. + Keep half-width punctuation inside code and inside English phrases. +- Put a half-width space between CJK and adjacent Latin text or numerals: + `使用 KaleidoSwap 桌面应用`, `需要 2 个通道`. +- Prefer verb-first, concise imperative sentences in instructions (`点击「创建钱包」`). +- Do not pad. If the English is one sentence, the Chinese is one sentence. +- Keep Markdown structure identical: same heading levels, same list nesting, + same number of table rows, same component tree. Only text changes. +- UI labels that appear in the app's English interface: translate, then keep the + English in parentheses on first use in a page — `点击「解锁钱包」(Unlock Wallet)`. + +## Positioning + +Do **not** frame KaleidoSwap as an RGB-first product. It is a multi-protocol Bitcoin +DEX; RGB is one of the supported Bitcoin layers. Use 多协议 / 比特币分层 framing. +This applies especially to `title` and `description` frontmatter. + +## Glossary + +| English | 简体中文 | Note | +|---|---|---| +| atomic swap | 原子交换 | | +| swap (noun/verb) | 交换 | consistent with 原子交换; never 兑换 | +| swap protocol | 交换协议 | | +| trading pair | 交易对 | | +| quote | 报价 | | +| request for quote (RFQ) | 询价 | | +| order | 订单 | | +| Lightning Network | 闪电网络 | | +| Lightning channel | 闪电通道 | `channel` alone → 通道 | +| open a channel | 开通通道 | | +| channel capacity | 通道容量 | | +| inbound / outbound liquidity | 入向流动性 / 出向流动性 | | +| liquidity | 流动性 | | +| LSP (Lightning Service Provider) | 闪电服务提供商（LSP） | | +| market maker | 做市商 | | +| maker / taker | 做市方 / 接单方 | | +| node | 节点 | | +| peer | 对等节点 | | +| non-custodial | 非托管 | | +| custodial | 托管 | | +| trustless | 无需信任 | | +| self-custody / sovereign | 自主保管 / 自主掌控 | | +| wallet | 钱包 | | +| mnemonic / recovery phrase | 助记词 | | +| seed | 种子 | | +| unlock the wallet | 解锁钱包 | | +| on-chain / off-chain | 链上 / 链下 | | +| Bitcoin | 比特币 | | +| BTC | BTC | never translate the ticker | +| sats / satoshis | 聪 | | +| Bitcoin Layers | 比特币分层协议 | | +| Layer 2 | 二层 | | +| RGB assets | RGB 资产 | | +| asset ID | 资产 ID | | +| mainnet / testnet | 主网 / 测试网 | | +| deposit | 存入 | noun 存入操作 / 充值 in UI context | +| withdrawal | 提取 | | +| balance | 余额 | | +| payment | 支付 | | +| invoice | 发票 | Lightning invoice → 闪电发票 | +| fee | 费用 | routing fee → 路由费 | +| backup | 备份 | | +| restore | 恢复 | | +| desktop app | 桌面应用 | | +| browser extension | 浏览器扩展 | | +| DApp | DApp | | +| open source | 开源 | | +| whitelist | 白名单 | | +| rate limit | 速率限制 | | +| endpoint | 接口端点 | | +| webhook | Webhook | | +| SDK / CLI / API / REST | keep in English | | diff --git a/mintlify-docs/cn/ai-tools/additional-resources.mdx b/mintlify-docs/cn/ai-tools/additional-resources.mdx new file mode 100644 index 0000000..f60abe6 --- /dev/null +++ b/mintlify-docs/cn/ai-tools/additional-resources.mdx @@ -0,0 +1,91 @@ +--- +title: "AI 工具：更多资源" +sidebarTitle: "更多资源" +description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP 与闪电付费 API 的协议规范，以及可用的支持渠道。" +--- + +## 源码仓库 + +每一种 AI 接入方式都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下开源。 + + + + 自主代理本体、它的仪表盘与状态 API，以及每个循环加载的 `skills/` 目录。 + + + 本地端引擎：分层漏斗、recipe 引擎、工具契约、记忆与检索，以及评测框架。 + + + 把所有领域组合到一条连接背后的统一网关。已发布到 npm。 + + + 以语音控制承载 KaleidoMind 的 React Native 移动钱包。 + + + +### 单域 MCP 服务器 + +| 仓库 | 工具前缀 | 领域 | +|-----------|-------------|--------| +| [wdk-wallet-mcp](https://github.com/kaleidoswap/wdk-wallet-mcp) | `wdk_*` | RGB Lightning Node 钱包、通道、原子交换接单方 | +| [wdk-wallet-spark-mcp](https://github.com/kaleidoswap/wdk-wallet-spark-mcp) | `spark_*` | Spark 钱包、闪电网络、代币转账、BTC 桥接 | +| [wdk-wallet-liquid-mcp](https://github.com/kaleidoswap/wdk-wallet-liquid-mcp) | `liquid_*` | Liquid 钱包、L-BTC 与资产余额、保密发送 | +| [kaleidoswap-mcp](https://github.com/kaleidoswap/kaleidoswap-mcp) _（已归档）_ | `kaleidoswap_*` | 已被 kaleido-mcp 中的 `kaleidoswap_*` 工具取代 | +| [l402-gateway-mcp](https://github.com/kaleidoswap/l402-gateway-mcp) _（已归档）_ | `mpp_*`、`l402_*` | 已被 kaleido-mcp 中的 `mpp_*` / `l402_*` 工具取代 | + +## 协议规范 + + + + 每个 KaleidoSwap MCP 服务器都实现的工具协议。 + + + RGB 工具背后的客户端验证与资产接口。 + + + `wdk_*` 工具所驱动的节点，附带它自己的 OpenAPI 参考。 + + + KaleidoMind 用于 LLM、向量嵌入、语音转文字和文字转语音的本地端推理运行时。 + + + +## KaleidoSwap 参考文档 + +先读这几篇，代理工具会好理解得多，因为那些工具只是它们之上的一层薄封装。 + + + + 原子 HTLC 流程如何结算，也就是交换工具所编排的那套流程。 + + + `kaleidoswap_lsp_*` 背后的通道下单接口端点。 + + + KaleidoAgent 调用的那个可执行文件，也是节点生命周期工具的来源。 + + + 直接从 TypeScript 或 Python 调用交换基础设施，跳过代理这一层。 + + + +## 产品与社区 + + + + 产品概览，以及每个 skill 的可阅读与可下载版本。 + + + 社区支持与讨论。 + + + Issue、Pull Request 和完整源码。 + + + 紧急问题的直接支持渠道。 + + + + + 反馈某个 AI 接入方式的问题时，请附上失败的工具名称、你所在的网络，以及移除了种子和所有 API 密钥的配置。请先查看[故障排查](/cn/ai-tools/troubleshooting)。 + diff --git a/mintlify-docs/cn/ai-tools/faq.mdx b/mintlify-docs/cn/ai-tools/faq.mdx new file mode 100644 index 0000000..5c12177 --- /dev/null +++ b/mintlify-docs/cn/ai-tools/faq.mdx @@ -0,0 +1,115 @@ +--- +title: "AI 工具常见问题" +sidebarTitle: "常见问题" +description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种子处理、模型选择、网络、成本，以及不同接入方式各自适合什么场景。" +--- + +## 常见问题 + + + + **不是。** 密钥始终留在本地 WDK 钱包和你所指向的 RGB Lightning Node 中。交易以闪电网络上的原子 HTLC 交换结算，因此做市商只是交易的对手方，从不持有你的资金。 + + 引入 AI 改变的不是托管方式，而是*由谁发起花费*。这正是确认机制和风险上限存在的意义。 + + + + 助记词以环境变量（`WDK_SEED`）的形式传给服务器进程，或从 `agent.config.json` 中读取。签名发生在该进程内部。模型只是调用工具并接收结果，因此种子不会成为提示词或工具输出的一部分。 + + 但这并不等于种子是安全的。任何能读取配置文件或进程环境的东西都能拿到你的助记词，所以主网种子绝不该出现在你会提交或分享的文件里。 + + + + | 如果你想 | 使用 | + |----------------|-----| + | 给已有的 MCP 客户端加上比特币工具 | [MCP 服务器](/cn/ai-tools/mcp-servers) | + | 无人值守地管理一个投资组合 | [KaleidoAgent](/cn/ai-tools/kaleido-agent) | + | 在本地端通过聊天或语音操作钱包 | [KaleidoMind](/cn/ai-tools/kaleido-mind) | + | 不改代码就调整代理行为 | [Skills](/cn/ai-tools/skills) | + + + + 取决于你调用哪些工具。 + + - 行情数据（`l402_*`）和 Spark 钱包（`spark_*`）**不需要节点**，后者只需要一份种子。 + - RGB Lightning Node 工具（`wdk_*`）和原子交换**需要节点**，因为 HTLC 的接单方一侧跑在你的节点上。 + + [KaleidoCLI](/cn/cli/getting-started) 可以为你部署一个基于 Docker 的节点，`kaleido-mcp` 也提供了 `kaleido_node_*` 工具来替你驱动这套生命周期。 + + + + 因接入方式而异： + + - **KaleidoAgent** 用托管模型推理，Claude 或 OpenAI，通过 `AGENT_PROVIDER` 选择。 + - **KaleidoMind** 通过 QVAC SDK 让模型**在设备上**运行，可以在本地，也可以在你显式配对过的桌面端。它的分层漏斗设计意味着大多数请求根本不会到达模型。 + - **MCP 服务器** 与模型无关。调用工具的就是你的 MCP 宿主所运行的那个模型。 + + + + 这些工具能够访问主网，但请把它当作最后一步而不是第一步。先用一次性种子在 regtest 或 signet 上起步，在 KaleidoAgent 上保持 `dry_run` 开启，直到 dry-run 的决策看起来都正确，然后再切换网络。 + + 另外要注意，不同接入方式的成熟度并不相同：KaleidoAgent 和 MCP 服务器会直接动用真实资金，而 LLM 调错一个工具是真实存在的失败模式。 + + + + 三条相互独立的成本线： + + - 托管模型的 **LLM token**。KaleidoAgent 会在 `GET /status` 中报告每轮运行的 token 开销。 + - KaleidoMind **没有推理成本**，因为模型跑在你自己的硬件上。 + - 每种情况下都有 **比特币费用**：闪电网络上的路由费、通道开通或关闭时的链上费用，以及交换中做市商的价差。 + + + + 有几种相互独立的控制手段，而且值得同时用上多个： + + | 控制项 | 效果 | + |---------|--------| + | `dry_run` | 只模拟决策，不真正执行 | + | `max_swap_usd` | 限制单笔交易的上限 | + | `stop_loss_btc_sats` | 低于某个 BTC 阈值时停止所有交易 | + | `min_btc_reserve_sats` | 为节点与 Spark 合计保留一个下限 | + | `max_concurrent_orders` | 限制同时挂出的订单数量 | + + 在 KaleidoMind 上，等价机制是结构性的而非配置出来的：会动用资金的工具被标记为 `requiresConfirmation`，并暂停等待宿主的确认面板。 + + + + 可以，这正是 Machine Payments Protocol 工具覆盖的场景。代理探测一个受门控的 URL，收到带闪电发票的 HTTP 402 挑战，支付它，然后提交凭据以拿到数据和一张收据。无需注册，也无需 API 密钥。完整流程见 [MCP 服务器页面](/cn/ai-tools/mcp-servers#paid-api-access)。 + + + + **MCP 服务器**提供工具：针对钱包、DEX 或节点的类型化、可调用操作。 + + **skill** 是一份 `SKILL.md` 操作手册，限定模型*可以调用其中哪些*工具，并承载执行计划。改动 skill 就能改变行为，无需触碰运行时代码。一个是能力，另一个是策略加计划。 + + + + 是的。所有仓库都公开在 [github.com/kaleidoswap](https://github.com/kaleidoswap) 下：MCP 服务器、KaleidoAgent、KaleidoMind，以及 skill 本身。直达链接见[更多资源](/cn/ai-tools/additional-resources)。 + + + + 桌面应用直接把 KaleidoMind 作为应用内聊天来承载，其工具以 stdio 边车方式接入 `kaleido-mcp`，可在**「设置 > 能力」**(Settings > Capabilities) 中切换。浏览器扩展自带一个内置的对话式代理来执行钱包操作。独立的 MCP 服务器则面向 Claude Desktop 或你自己的客户端这类外部宿主。 + + + +## 获取帮助 + +如果遇到的是报错而不是疑问，请查看[故障排查](/cn/ai-tools/troubleshooting)。其他情况请通过下面任一渠道反馈问题，并附上： + +1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本） +2. 你所在的网络（regtest、signet 或主网） +3. 失败的工具名称和报错文本 +4. 宿主与运行时版本（MCP 客户端、Node.js） +5. 你的配置，并移除其中的种子和所有密钥 + + + + 向社区提问。 + + + 在相关仓库提交缺陷报告。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/ai-tools/getting-started.mdx b/mintlify-docs/cn/ai-tools/getting-started.mdx new file mode 100644 index 0000000..b81db17 --- /dev/null +++ b/mintlify-docs/cn/ai-tools/getting-started.mdx @@ -0,0 +1,123 @@ +--- +title: "AI 工具：快速上手" +sidebarTitle: "快速上手" +description: "把 AI 代理接入比特币：从测试网络上的第一次只读工具调用，到验证过一笔报价之后再开启真实执行。" +--- + +这是从「装好工具」到「验证一笔交换」的完整路径。顺序是先只读，再报价，最后执行 —— 因为除第一步之外，每一步都会动用真实价值。 + +## 开始之前 + +| 要求 | 说明 | +|-------------|---------| +| **一个测试网络** | regtest 或 signet。首次运行绝不要用主网 | +| **一份钱包种子** | 用于测试网络的一次性 BIP-39 助记词，设置到 `WDK_SEED` | +| **一个节点** | 仅 `wdk_*` 工具和原子交换需要。Spark 工具只需要种子，行情数据什么都不需要 | +| **一个 MCP 宿主或 LLM 密钥** | Claude Desktop 或其他 MCP 客户端，或者用于 KaleidoAgent 的 Anthropic / OpenAI 密钥 | + +如果你还没有安装任何组件，请先看[安装](/cn/ai-tools/installation)。 + +## 选择接入方式 {#pick-a-surface} + +| 如果你想 | 从这里开始 | +|----------------|-----------| +| 给 Claude Desktop 或自己的 MCP 客户端加上比特币工具 | [MCP 服务器](/cn/ai-tools/mcp-servers) | +| 让代理无人值守地管理一个投资组合 | [KaleidoAgent](/cn/ai-tools/kaleido-agent) | +| 在本地端通过聊天或语音操作钱包 | [KaleidoMind](/cn/ai-tools/kaleido-mind) | +| 不改代码就调整代理行为 | [Skills](/cn/ai-tools/skills) | + +## 首次运行：MCP 服务器 + + + + 把 `kaleido-mcp` 配置块加入你的 MCP 宿主配置，将 `KALEIDOSWAP_API_URL` 指向测试环境，并把 `SPARK_NETWORK` 设为 `REGTEST`。完整 JSON 见 [MCP 服务器页面](/cn/ai-tools/mcp-servers#client-configuration)。 + + + + MCP 宿主只在启动时读取配置。已经在运行的客户端不会自动识别新服务器，必须重启。 + + + + 先从不会动用资金的操作开始。请求行情数据，它既不需要种子也不需要节点： + + ``` + What is the current Bitcoin price and the Fear and Greed index? + ``` + + 这会触发 `l402_get_price` 和 `l402_get_sentiment`。只要有回答，连接就是通的。 + + + + 接着确认钱包工具能正常解析： + + ``` + Show me my Spark balance and my Spark address. + ``` + + 这会调用 `spark_get_balance` 和 `spark_get_address`。这一步报错说明是种子或网络问题，而不是连接问题。 + + + + 只询价，不下单： + + ``` + Quote 100000 sats of BTC into USDT. Do not place an order. + ``` + + `kaleidoswap_get_quote` 会返回一个 `rfq_id`、原始数量、费用和过期时间。请仔细核对原始数量：它们以资产的最小单位计价，不是显示单位。 + + + + 一笔原子交换需要 DEX 工具和钱包工具配合，并且节点必须在通道中持有该资产。[跨服务器调用顺序](/cn/ai-tools/mcp-servers#atomic-swap-across-servers)按顺序列出了每一次调用。 + + + +## 首次运行：KaleidoAgent + + + + `agent.config.json` 中的 `portfolio.dry_run` 默认为 `true`。先别动它。代理会完成推理、决策并汇报一笔交易，但不会真正提交。 + + + + ```bash + npm start + ``` + + 这会同时启动代理和监听 `http://localhost:4242` 的状态 API。若要使用仪表盘，另外运行 `npm run dev:webapp` 并打开 `http://localhost:5173`。 + + + + 不必等定时任务，可以直接让状态 API 跑一轮： + + ```bash + curl -X POST http://localhost:4242/run \ + -H 'Content-Type: application/json' \ + -d '{"task_id":"rebalance"}' + ``` + + 然后读取 `GET /status`，查看它的决策、它看到的余额，以及 token 开销。 + + + + 确认 `max_swap_usd`、`min_btc_reserve_sats` 和 `stop_loss_btc_sats` 与你在测试网络上能接受的损失相符。每笔交换提交之前都会校验这些参数。 + + + + 当连续几轮的 dry-run 决策都看起来正确后，再把 `portfolio.dry_run` 设为 `false`。 + + + +## 确认机制长什么样 + +两种代理接入方式对花费的把关方式不同，值得弄清楚你依赖的是哪一种。 + +| 接入方式 | 把关机制 | +|---------|------| +| **KaleidoMind** | 结构性把关。每个会动用资金的工具都标记了 `requiresConfirmation`，引擎会暂停并等待宿主的确认面板。模型无法绕过 | +| **KaleidoAgent** | 策略性把关。`dry_run` 加上 `agent.config.json` 中的风险上限，在提交前校验 | +| **通用宿主中的 MCP 服务器** | 取决于你的宿主客户端。多数 MCP 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的 | + + + 通用 MCP 宿主是保护最弱的一条路径。如果你的客户端自动批准工具调用，LLM 就能不经询问地从配置的钱包中花钱。在完全弄清客户端如何处理批准之前，请只使用测试网络种子。 + diff --git a/mintlify-docs/cn/ai-tools/installation.mdx b/mintlify-docs/cn/ai-tools/installation.mdx new file mode 100644 index 0000000..0d6a55d --- /dev/null +++ b/mintlify-docs/cn/ai-tools/installation.mdx @@ -0,0 +1,88 @@ +--- +title: "AI 工具：安装" +sidebarTitle: "安装" +description: "安装 KaleidoSwap AI 工具：MCP 服务器网关、KaleidoAgent 以及本地端 KaleidoMind 引擎，并逐一说明各自的前置条件。" +--- + +每个 AI 接入方式都可以独立安装。挑选与你的开发目标最匹配的那一个，或者先安装 MCP 网关 —— 它是跑通第一次工具调用的最短路径。 + +| 接入方式 | 安装路径 | 前置条件 | +|---------|-------------|---------------| +| **[MCP 服务器](/cn/ai-tools/mcp-servers)** | 网关用 `npx`，专用服务器需本地构建 | Node.js 20+，一个 MCP 宿主客户端 | +| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 克隆仓库并从源码构建 | Node.js 20+、KaleidoCLI、Nanobot、一个 LLM API 密钥 | +| **[KaleidoMind](/cn/ai-tools/kaleido-mind)** | 随桌面应用一起提供，或构建仓库用于开发 | 桌面应用，或 pnpm 与 QVAC SDK | + + + 这里的每一种接入方式都会使用真实的 BIP-39 助记词签名，或直接驱动一个运行中的节点。请先在测试网络上起步，在配置验证通过之前保持 `dry_run` 开启，并且永远不要把主网种子写入会被提交或分享的文件。 + + +## MCP 服务器 + +`kaleido-mcp` 是跑通工具调用的最快路径，已发布到 npm，无需本地构建： + +```bash +npx -y kaleido-mcp +``` + +另有三个按钱包划分的服务器 `wdk-wallet-mcp`、`wdk-wallet-spark-mcp` 和 `wdk-wallet-liquid-mcp`，它们保持独立而未并入网关，需要从源码构建： + +```bash +git clone https://github.com/kaleidoswap/wdk-wallet-mcp.git +cd wdk-wallet-mcp +npm install +npm run build +node dist/index.js +``` + + + `kaleidoswap-mcp` 和 `l402-gateway-mcp` 已归档，它们各自的 README 也建议集成方改用 `kaleido-mcp`。新项目请不要再克隆或构建它们。 + + +完整的环境变量参考、stdio 与 HTTP 传输方式的对比、工具清单，以及每个服务器的客户端配置 JSON，都在 [MCP 服务器页面](/cn/ai-tools/mcp-servers#installation-and-configuration)。 + +## KaleidoAgent + +前置条件：Node.js 20 或更高版本、位于 `$PATH` 中的 [KaleidoCLI](/cn/cli/getting-started)、[Nanobot](https://nanobot.dev) 运行时，以及一个 Anthropic 或 OpenAI API 密钥。 + +```bash +git clone https://github.com/kaleidoswap/kaleido-agent.git +cd kaleido-agent +npm run install:all +``` + +之后的步骤 —— 设置 API 密钥、在 `agent.config.json` 中配置钱包、启动仪表盘 —— 以及容器部署方案，都在 [KaleidoAgent 页面](/cn/ai-tools/kaleido-agent#run-it)逐步说明。 + +## KaleidoMind + +KaleidoMind 是嵌入宿主应用中的引擎，而不是一个独立安装的程序。 + +### 通过桌面应用 + +这是最快的路径。[桌面应用](/cn/desktop-app/getting-started/installation)将该引擎打包为应用内聊天，负责管理本地模型的生命周期，并且可以作为手机端委托推理的配对节点。在 **设置 > 能力** (Settings > Capabilities) 中选择 **Node + Mind** 或 **Only Mind** 即可开启。 + + + KaleidoMind 依赖本地 AI 运行时，目前在 Windows 上可能尚不可用。所有交易与节点功能都不依赖它，因此如果你的平台上 Mind 暂不可用，可以用 **Only Node** 模式运行应用。 + + +### 从源码构建，用于开发 + +```bash +git clone https://github.com/kaleidoswap/kaleido-mind.git +cd kaleido-mind +pnpm install && pnpm -r build +``` + +`apps/cli` 中的 CLI 负责本地模型管理，也可以直接运行代理： + +```bash +cd apps/cli +npx tsx src/index.ts setup # 引导式首次运行：选择并拉取模型 +npx tsx src/index.ts run "what's my balance?" +npx tsx src/index.ts skills # 列出已安装的 Skills +``` + +如果想在没有手机的情况下用某个模型验证引擎，可以在仓库根目录使用 playground： + +```bash +pnpm play "pay bob 3 eur" +``` diff --git a/mintlify-docs/cn/ai-tools/introduction.mdx b/mintlify-docs/cn/ai-tools/introduction.mdx new file mode 100644 index 0000000..2cb69bf --- /dev/null +++ b/mintlify-docs/cn/ai-tools/introduction.mdx @@ -0,0 +1,34 @@ +--- +title: "KaleidoSwap AI 工具" +sidebarTitle: "总览" +description: "比特币支付 MCP 服务器、自主运行的比特币二层代理，以及本地端助手，让 AI 代理能够跨比特币分层协议完成询价、交换与支付。" +--- + +## AI 工具包含什么 + +KaleidoSwap 通过开源软件，把交换、钱包和节点基础设施开放给 AI 代理。三类接入方式覆盖了全部场景：从一个完整的自主代理，到在现有客户端里接入单个 MCP 连接。 + +产品总览请见 [kaleidoswap.com/products/ai-tools](https://kaleidoswap.com/products/ai-tools)。 + + + + 基于 KaleidoCLI 与 WDK 钱包原语的自主投资组合管理与钱包操作代理。 + + + 面向 Spark、RGB Lightning 与 Arkade 钱包的本地端推理引擎，支持聊天或语音操作。 + + + 为任意兼容 MCP 的客户端提供钱包、DEX、节点与支付工具。 + + + `SKILL.md` 操作手册，用于限定工具范围并承载执行计划。 + + + + + 这里的每一种接入方式都会使用真实的 BIP-39 助记词签名，或直接驱动一个运行中的节点。请参阅[安装](/cn/ai-tools/installation)，了解如何把测试种子与主网种子分开保管。 + + +## 我该选哪一个？ + +决策表见「快速上手」中的[选择接入方式](/cn/ai-tools/getting-started#pick-a-surface)，随后可直接进入安装或首次运行。 diff --git a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx new file mode 100644 index 0000000..6afd7ed --- /dev/null +++ b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx @@ -0,0 +1,174 @@ +--- +title: "KaleidoAgent：自主运行的比特币二层交易代理" +sidebarTitle: "KaleidoAgent" +description: "运行一个非托管的自主代理：用原子交换再平衡比特币二层投资组合、按需购买通道流动性，并了解其能力、风控与配置方式。" +--- + +[KaleidoAgent](https://github.com/kaleidoswap/kaleido-agent) 是一个自主运行的非托管比特币二层代理。它不涉及任何外部托管：密钥始终留在本地 WDK 钱包和 RGB Lightning Node 中，每笔交易都以闪电网络上的原子 HTLC 交换结算。 + +它管理闪电与 RGB 钱包、在 KaleidoSwap DEX 上执行原子 HTLC 交换、运行投资组合再平衡与 DCA 策略、维持闪电通道流动性健康，同时还能作为交互式的钱包助手聊天使用 —— 所有这些都由一个 LLM（Claude 或 OpenAI）基于 [KaleidoCLI](/cn/cli/introduction) 和 MCP 工具调用进行推理来驱动。 + + + KaleidoAgent 是一个独立的常驻服务。它目前**没有**嵌入 [KaleidoMind](/cn/ai-tools/kaleido-mind) 的 `Engine`，而是运行自己的代理循环。关于正在考虑的收敛路径，请见 [KaleidoMind 的关系说明](/cn/ai-tools/kaleido-mind#relationship-to-kaleidoagent)。 + + +## 能力 + +| 领域 | 代理做什么 | +|------|---------------------| +| **投资组合管理** | 检测 BTC、USDT (RGB) 和 XAUT (RGB) 之间的配置偏移，然后用原子交换再平衡 | +| **定投（DCA）** | 按计划执行固定金额买入，可选启用基于 EMA 的逻辑，在拉升时跳过、在回调时加倍 | +| **通道管理** | 监控节点健康度与出向流动性，清理卡住的 RGB 转移，通过 LSPS1 购买通道 | +| **跨二层调度** | 在闪电网络、RGB 通道、Spark 和链上 BTC 之间转移资产 | +| **钱包助手** | 以对话方式查询余额、生成发票、发送资金以及执行需确认的交换 | +| **MPP / L402 支付** | 通过闪电网络为 HTTP 402 付费数据 API 付费，并发现按次计费的接口端点 | +| **每日报告** | 在 UTC 00:00 输出投资组合快照、交易历史和行情数据 | + +## 架构 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ KaleidoAgent │ +│ │ +│ index.ts (Node.js bootstrap) │ +│ │ │ +│ ├── NanobotManager ──► Nanobot gateway │ +│ │ │ (core runtime: scheduling, LLM, MCP, Telegram) │ +│ │ │ │ +│ │ └── MCP servers (managed by Nanobot) │ +│ │ └── kaleido (kaleido-mcp), unified wallet+DEX │ +│ │ │ +│ ├── StatusServer :4242 (bridge API for webapp) │ +│ │ ├── NanobotTaskRunner (triggers agent tasks) │ +│ │ ├── NanobotChatRunner (wallet assistant chat) │ +│ │ └── WalletBridge (live balance cache) │ +│ │ │ +│ └── Scheduler (manual / startup task triggers) │ +│ │ +│ React Dashboard :5173 (Vite + Tailwind) │ +└──────────────────────────────────────────────────────────────┘ +``` + +**Nanobot 是核心运行时。** 它负责代理执行、cron 定时调度、MCP 工具集成、Telegram 消息和记忆。Node.js 只是一层很薄的桥接：启动 Nanobot，并在 `:4242` 上提供本地控制面板 API。 + +## 两种执行模式 + +| 模式 | 工作方式 | 适用场景 | +|------|-------------|-------------| +| `skill` _（默认）_ | `SKILL.md` 文件作为系统提示词加载，MCP 服务器由 Nanobot 直接管理：`kaleido`（统一的 `kaleido-mcp`）提供钱包、DEX 和支付工具，再加上用于本地代理控制的 `kaleido_control` | 轻量，Node.js 不需要直连 MCP | +| `mcp` | Node.js 通过 `McpManager` 直接连接 [MCP 服务器](/cn/ai-tools/mcp-servers)，并内联调用它们的工具 | 调试，或需要从 Node.js 精细控制工具的场景 | + +## MCP 服务器接线 + +KaleidoAgent 把 `kaleido-mcp`（[统一的 MCP 服务器](/cn/ai-tools/mcp-servers)）注册为主要工具源，一条连接就能拿到 `spark_*`、`wdk_*`/`rln_*`、`kaleidoswap_*`、`mpp_*`/`l402_*` 和 `kaleido_node_*` 工具。历史上它的配置还直接引用了现已归档的独立服务器 `kaleidoswap-mcp` 和 `l402-gateway-mcp`；由于这两者都已被 `kaleido-mcp` 取代（见[已退役的服务器](/cn/ai-tools/mcp-servers#retired-servers)），新配置应只依赖 `kaleido-mcp`，不要再单独接入它们。 + +远程的第三方 MCP 服务器同样可以注册，但会先做 API 密钥检查。例如 Bitrefill 礼品卡 MCP 只在存在 `BITREFILL_API_KEY` 环境变量时才注册，因为上游接口端点会拒绝匿名连接。 + +## 自主循环 + +| 循环 | 默认间隔 | Skill | 用途 | +|------|-----------------|-------|---------| +| `rebalance` | 按需或 cron | `portfolio-manager` | 偏移检测，随后执行原子交换 | +| `heartbeat` | 5 分钟 | `channel-manager` | 节点健康度、RGB flush、LSPS1 通道购买 | +| `daily_summary` | UTC 00:00 | `kaleidoagent` | 投资组合快照、交易历史、行情数据 | + +每个循环都由一个 [skill](/cn/ai-tools/skills) 驱动。 + +## 风险控制 + +风险上限位于 `agent.config.json` 的 `portfolio` 之下。每笔交换提交之前都会校验它们。 + +| 参数 | 默认值 | 作用 | +|-----------|---------|--------| +| `dry_run` | `true` | 只模拟决策，不真正执行交换 | +| `max_swap_usd` | `200` | 限制单笔交易的美元价值上限 | +| `min_btc_reserve_sats` | `50000` | RLN 节点与 Spark 合计的最低 BTC 余额 | +| `stop_loss_btc_sats` | `30000` | 低于该 BTC 阈值时停止所有交易 | +| `rebalance_threshold_pct` | `5` | 触发交换所需的最小偏移百分比 | +| `max_concurrent_orders` | `3` | 限制同时挂出的订单数量 | + +## 交易模式 + +| 模式 | 结算方式 | +|------|-----------| +| `atomic` | 原子 HTLC 交换，无需存入地址，在闪电网络上结算 | +| `rest` | 基于存入的 REST 订单 | +| `both` | 优先原子交换，REST 作为回退 | + +## 原子交换流程 + +与 KaleidoSwap 技术栈中其他部分相同的 5 步 HTLC 协议，通过 `kaleido-mcp` 或 CLI 驱动： + +``` +1. kaleidoswap_get_quote → rfq_id + amounts +2. kaleidoswap_atomic_init → swapstring + payment_hash +3. wdk_atomic_taker → whitelist HTLC on RLN node +4. kaleidoswap_atomic_execute → HTLC settlement triggered +5. kaleidoswap_atomic_status → poll → Succeeded +``` + +## 运行起来 {#run-it} + +前置条件：Node.js 20 或更高版本、位于 `$PATH` 中的 [KaleidoCLI](/cn/cli/getting-started)、[Nanobot](https://nanobot.dev) 运行时，以及一个 Anthropic 或 OpenAI API 密钥。 + + + + ```bash + git clone https://github.com/kaleidoswap/kaleido-agent.git + cd kaleido-agent + npm run install:all + ``` + + + 在仓库根目录创建 `.env` 文件，填入 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`。用 `AGENT_PROVIDER` 在 `anthropic` 和 `openai` 之间选择： + + ```bash + ANTHROPIC_API_KEY=sk-ant-... + AGENT_PROVIDER=anthropic + ``` + + + 编辑 `agent.config.json`： + + - `mcp.kaleido.env.WDK_SEED`，钱包助记词。 + - `mcp.kaleido.env.RLN_NODE_URL`，RGB Lightning Node 的 URL。 + - `mcp.spark.env.WDK_SPARK_SEED`，可选的独立 Spark 种子。 + - `portfolio.targets`，BTC、USDT 和 XAUT 之间的目标配置比例。 + - `portfolio.dry_run`，在配置验证通过之前保持 `true`。 + + 主要配置都在 `agent.config.json` 中：模型选择、MCP 服务器命令与环境变量、投资组合目标与风险上限、调度间隔，以及启用的 skill 列表。完整 schema 和环境变量参考见[仓库 README](https://github.com/kaleidoswap/kaleido-agent#configuration)。 + + + ```bash + npm run build:all + npm start + ``` + + `npm start` 会启动代理及其本地状态 API，地址为 `http://localhost:4242`。仪表盘单独提供：运行 `npm run dev:webapp`（或用 `npm run start:webapp` 运行已构建的 webapp），在 `http://localhost:5173` 上访问。若想让代理以后台进程运行，请改用 `npm run daemon:start`。 + + + +如需隔离部署，把 `.env.container.example` 复制为 `.env.container`，然后启动容器栈： + +```bash +docker compose --env-file .env.container -f docker-compose.container.yml up -d +``` + + + `agent.config.json` 中保存着真实的 BIP-39 助记词。请先在测试网络上起步，在配置验证通过之前保持 `dry_run` 开启，并且永远不要提交或分享这个文件。 + + +## 状态 API {#status-api} + +代理在端口 `4242` 上提供一个仅限本机访问的控制 API，供仪表盘使用，也可以直接调用。 + +| 接口端点 | 方法 | 用途 | +|----------|--------|---------| +| `/health` | GET | 服务健康状况 | +| `/status` | GET | 运行时长、余额、最近运行记录、token 开销 | +| `/wallets` | GET | Spark 与 RLN 的实时余额快照 | +| `/run` | POST | 触发一个任务，例如 `{ "task_id": "rebalance" }` | +| `/chat` | POST | 钱包助手对话 | +| `/config` | GET/POST | 读取或更新代理配置 | +| `/tasks` | GET/POST | 列出或创建定时任务 | +| `/skills` | GET/PATCH | 列出 skills，启用或禁用某一个 | diff --git a/mintlify-docs/cn/ai-tools/kaleido-mind.mdx b/mintlify-docs/cn/ai-tools/kaleido-mind.mdx new file mode 100644 index 0000000..3473fed --- /dev/null +++ b/mintlify-docs/cn/ai-tools/kaleido-mind.mdx @@ -0,0 +1,79 @@ +--- +title: "KaleidoMind：比特币钱包的本地端 AI 引擎" +sidebarTitle: "KaleidoMind" +description: "驱动 KaleidoSwap 代理式钱包的本地端推理引擎：分层请求漏斗、跨宿主统一的工具契约，以及内置的花费前确认机制。" +--- + +[KaleidoMind](https://github.com/kaleidoswap/kaleido-mind)（`@kaleidorg/mind`）是面向多 L2 比特币钱包的本地优先代理式推理与工具调用引擎。它是一个纯库：负责代理循环的 `Engine`、支持可插拔 `ToolSource` 的 `ToolRegistry`、一个 `SkillRegistry`，以及注入式的 `LLMProvider`，在手机和笔记本上的运行方式完全一致。 + +它的设计出发点是一个硬性约束：本地端的小模型在多步规划上既慢又不可靠。KaleidoMind 索性不让它们做这件事。 + + + KaleidoMind 不会独立运行，它是一个由宿主嵌入的库：[Rate 移动钱包](https://github.com/kaleidoswap/Rate)（React Native，完全本地端 QVAC）、[桌面应用](/cn/desktop-app/getting-started/introduction)的 Tauri sidecar，或者一套评测与基准测试框架。**[KaleidoAgent](/cn/ai-tools/kaleido-agent) 目前并未使用这个库**，它有自己独立的代理循环。详见下文[与 KaleidoAgent 的关系](#relationship-to-kaleidoagent)。 + + +## 分层漏斗 + +大多数请求根本不会到达模型。 + +| 层级 | 示例 | 成本 | +|------|---------|------| +| `T0` 快速通道 | "balance"、"address"、"btc price" | 零次推理，即时返回 | +| `T2` recipe | "pay bob 3 EUR"、"buy 0.001 BTC" | 约一次推理（模型可协助提取参数槽），随后是确定性链路，需确认才继续 | +| `T1` 代理循环 | 其余全部请求 | 由 skill 限定范围的 LLM，可通过 P2P 把困难或新型链路委托给已配对桌面端的更大模型 | + +- **T0，快速通道。** 确定性模式匹配，零推理。余额查询、地址、现货价格。 +- **T2，recipe 引擎。** 由 skill 承载有序的执行计划（解析、定价、换算、确认、发送），模型只负责填充参数槽。这让多步流程即使在约 0.6B 参数的模型上也足够可靠，而不是要求模型自己规划整条链路。 +- **T1，完整代理循环。** 其余全部请求，范围限定在该 skill 自己的工具清单内，这样小模型永远不必一次性面对全部工具。发现类流程（例如 merchant-finder）则有意更多依赖模型的自然语言理解能力。 + +## 统一的工具契约，多种传输方式 + +模型在任何地方看到的工具名称和 schema 都完全相同，只有*工具如何执行*会因接入方式而异： + +| 接入方式 | 工具执行方式 | 花费前确认 | +|---------|----------------|----------------------| +| 移动端（Rate） | 进程内 WDK 适配器（完全本地端、私密）；可选通过 P2P 委托给已配对的桌面端 | 确认面板 | +| 桌面端 | 以 stdio 工具源方式接入 `kaleido-mcp`（命名空间为 `spark_*`/`rln_*`/`kaleidoswap_*`） | 确认对话框 | +| 评测 / CLI | 预置的桩处理器，用于可复现的基准测试 | 自动批准（同时断言把关已触发） | + +规范的工具契约以 `ToolDef[]` 的形式定义在 core 中，其 `spend` 标记会映射为 `requiresConfirmation: true`。每个会动用资金的工具都带有这个标记，**Engine 会在执行前暂停并调用宿主的 `onConfirm`**，因此模型永远无法绕过花费把关。确认面板上的复述文本是确定性的、以语音优先方式生成（例如 *"Send 4,800 sats to bob over Spark. Confirm?"*），由已解析的调用内容拼装，而不是由模型生成，所以单位或收款方写错时会显示出来，便于被发现。 + +### 各分层的钱包工具 + +| 分层 | 状态 | 工具 | +|-------|--------|-------| +| Spark | 已上线 | `spark_get_balance` · `spark_get_address` · `spark_get_onchain_address` · `spark_create_invoice` · `spark_pay_invoice` 🔒 · `spark_send` 🔒 | +| RLN / RGB | 已上线 | `rln_get_balances` · `rln_get_node_info` · `rln_list_channels` · `rln_create_ln_invoice` · `rln_create_rgb_invoice` · `rln_pay_invoice` 🔒 · `rln_send_asset` 🔒 | +| Arkade | 已上线 | `arkade_get_balance` · `arkade_get_address` · `arkade_send` 🔒 | +| Liquid | 计划中，尚未实现 | `liquid_get_balance` · `liquid_create_invoice` · `liquid_send` 🔒（契约中已定义类型，但还没有适配器） | + +此外还有跨层的路由工具：`get_balances(layer?)`、`resolve_contact(name)`、`get_price(asset?, fiat?)`、`fiat_to_sats(amount, currency)`、`get_swap_quote`/`execute_swap`，会自动选择结算通道的统一 `send_payment(asset, amount, to, layer?)`，以及与之对应的收款工具 `create_invoice(asset?, amount?, layer?)`。 + +### KaleidoSwap 交易与 LSPS1 + +DEX 交易（`kaleidoswap_get_quote`、`kaleidoswap_place_order`、`kaleidoswap_atomic_init`/`execute`/`status`）与不绑定特定 LSP 的通道订单（`lsp_get_info`、`lsp_get_network_info`、`lsp_estimate_fees`、`lsp_create_order`、`lsp_get_order`）各有独立的契约。原子交换链路以单个需确认的 recipe（`kaleidoswapAtomicRecipe`）运行：先报价，用户确认一次后在做市方一侧初始化，读取节点的 pubkey，以接单方身份把 HTLC 加入白名单，然后执行。 + +## Skills + +Skills 是符合 Agent Skills 规范的操作手册（`SKILL.md` 加渐进式披露），用于限定哪些工具可见，并且在代理层级中还承载手册本身。内置的 skills 包括各钱包的操作手册（`spark-wallet`、`rgb-lightning-node`）、交易与通道（`kaleido-trading`、`kaleido-lsps`、`flashnet-swaps`、`channel-manager`、`liquidity-optimizer`）、投资组合自动化（`portfolio-manager`、`dca`）、消费与数据（`bitrefill`、`paid-data`、`wallet-assistant`），以及一个更依赖模型的商户发现 skill（`merchant-finder`，通过可插拔的嵌入选择器结合地理位置与 BTC Map）。支付与收款流程以 T2 recipe 而非 skill 的形式提供。 + +## QVAC：本地端推理 + +LLM、嵌入、语音转文字和文字转语音推理全部通过 [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk) 完成，默认在本地端运行，较重的任务也可以委托给用户明确配对并自行掌控的桌面端。它以 `@kaleidorg/mind/qvac` 子路径发布，使该 SDK 保持为 peer 依赖，而不是 core 的硬性依赖。记忆与 RAG（长期回忆、钱包历史检索、商户发现）同样走 QVAC 的嵌入能力，并通过近重复内容合并来避免记忆膨胀。 + +## 运行环境 + +| 宿主 | 角色 | +|------|------| +| [Rate](https://github.com/kaleidoswap/Rate) | React Native 移动钱包，内含本地 LLM、语音转文字、神经网络文字转语音，以及免手操作的语音循环 | +| [桌面应用](/cn/desktop-app/getting-started/introduction) | 通过 Tauri sidecar（`apps/provider`）把引擎作为应用内聊天运行，该 sidecar 以 stdio 工具源方式接入 `kaleido-mcp`，同时还能作为手机的配对推理节点 | + +最快的体验方式是桌面应用。[下载最新版本](https://kaleidoswap.com/downloads)，然后按照[安装指南](/cn/desktop-app/getting-started/installation)操作。 + +## 与 KaleidoAgent 的关系 {#relationship-to-kaleidoagent} + +[KaleidoAgent](/cn/ai-tools/kaleido-agent) 是一个独立的常驻 Node.js 服务（Nanobot 运行时、定时调度、Telegram），它早于 KaleidoMind 的 `Engine`，并且**尚未**迁移到该引擎上，而是直接对接 Anthropic 或 OpenAI 运行自己的代理循环。两者在概念上是同一个思路（在工具注册表之上运行带确认把关的代理循环）的两次实现。让二者收敛 —— 即由 KaleidoAgent 承载 KaleidoMind 的 `Engine` 而不再用自己的循环 —— 是一条已知但尚未启动的整合路径；在那之前，请把它们当作两个都消费 `kaleido-mcp` 的独立系统。 + +## 发布与子路径 + +从 `packages/core` 以 `@kaleidorg/mind` 发布，包含这些子路径：`./mcp`（MCP 工具源辅助函数）、`./skills`（skill 加载器）、`./logger` 和 `./qvac`（本地端推理适配器）。npm 上还有 `apps/provider`，即桌面应用嵌入的 Tauri 桌面 sidecar，包名为 `@kaleidorg/mind-provider`。`apps/cli` 中的 CLI 供仓库内的终端与评测使用，不对外发布。 diff --git a/mintlify-docs/cn/ai-tools/mcp-servers.mdx b/mintlify-docs/cn/ai-tools/mcp-servers.mdx new file mode 100644 index 0000000..e2f5d8a --- /dev/null +++ b/mintlify-docs/cn/ai-tools/mcp-servers.mdx @@ -0,0 +1,307 @@ +--- +title: "面向钱包、交换与付费 API 的比特币 MCP 服务器" +sidebarTitle: "MCP 服务器" +description: "用于比特币钱包、KaleidoSwap DEX 和闪电付费 API 的类型化 Model Context Protocol 工具：服务器清单、工具集与客户端配置一次讲清。" +--- + +KaleidoSwap 通过 **`kaleido-mcp`** 这一个统一服务器，把钱包、DEX 和支付能力开放给 AI 代理（Claude Desktop、[KaleidoAgent](/cn/ai-tools/kaleido-agent)、基于 [KaleidoMind](/cn/ai-tools/kaleido-mind) 的宿主，或任何其他 [MCP](https://modelcontextprotocol.io) 客户端），另外还有三个仍然独立存在的按钱包划分的服务器。 + +## 为什么只用一个服务器 + +早期存在多个各管一域的 MCP 服务器：一个 KaleidoSwap DEX 服务器、一个 MPP/L402 支付服务器，以及 RLN 和 Spark 各自的钱包服务器。DEX 与支付服务器此后已合并进 `kaleido-mcp`，它在同一条连接下重新暴露了完全相同的工具契约： + + + + 代理宿主只需配置一个 MCP 服务器，而不是接四五个。 + + + 工具契约（`kaleidoswap_*`、`wdk_*`、`spark_*`、`mpp_*`、`l402_*`）与原来的单域服务器完全一致，无需重新学习。 + + + 缺陷修复和新工具都落在同一个仓库，而不是在多个仓库里重复。 + + + 独立的 `kaleidoswap-mcp` 和 `l402-gateway-mcp` 仓库已归档。后续开发都在 `kaleido-mcp` 中进行。 + + + +## 可用的服务器 + +| 服务器 | 工具前缀 | 覆盖范围 | +|--------|-------------|--------| +| [kaleido-mcp](https://github.com/kaleidoswap/kaleido-mcp) | `kaleidoswap_*`、`wdk_*`、`spark_*`、`mpp_*`、`l402_*`、`kaleido_node_*` | 统一网关。下面所有领域，一条连接全包 | +| [wdk-wallet-mcp](https://github.com/kaleidoswap/wdk-wallet-mcp) | `wdk_*` | RGB Lightning Node 钱包：余额、RGB 与 BOLT11 发票、支付、通道、原子交换接单方 | +| [wdk-wallet-spark-mcp](https://github.com/kaleidoswap/wdk-wallet-spark-mcp) | `spark_*` | Spark 钱包：余额、闪电收付、代币转账、BTC 桥接的存入与提取 | +| [wdk-wallet-liquid-mcp](https://github.com/kaleidoswap/wdk-wallet-liquid-mcp) | `liquid_*` | Liquid 钱包：L-BTC 与资产余额、保密地址、发送，底层由进程内的 LWK 钱包支撑，无需外部守护进程 | + + + `kaleido-mcp` 的工具直接构建在 kaleido-sdk 和 WDK 工具包之上，而不是代理那些单域服务器：它是同一批工具契约的组合，而不是对那些进程的封装。为便于迁移，遗留的 `rln_*` 以及通用 `get_*` 行情别名仍然保留。 + + +### 已退役的服务器 {#retired-servers} + +以下仓库已归档。它们自己的 README 都指向 `kaleido-mcp`，并声明不再更新： + +| 仓库 | 取代者 | +|------|---------------| +| `kaleidoswap-mcp` | kaleido-mcp 中的 `kaleidoswap_*` 工具 | +| `l402-gateway-mcp` | kaleido-mcp 中的 `mpp_*` / `l402_*` 工具 | +| `kaleido-node-mcp` | 节点生命周期工具已移植为 `kaleido_node_*`；该仓库同时具备的钱包、资产、通道、支付、行情和交换工具已被弃用，改用 kaleido-mcp 中现有的、由 SDK 支撑的工具 | + +如果你的集成仍然直接指向 `kaleidoswap-mcp` 或 `l402-gateway-mcp`，请改指 `kaleido-mcp`。工具名和参数都没有变化。 + +## 安装与配置 {#installation-and-configuration} + +`kaleido-mcp` 已发布到 npm，因此最快的路径不需要本地构建： + +```bash +npx -y kaleido-mcp +``` + +实际使用中由 MCP 宿主替你执行这条命令，把宿主配置指向该命令即可（见下面的[客户端配置](#client-configuration)）。若用于开发，或要运行某个特定提交，请改为从源码构建： + +```bash +git clone https://github.com/kaleidoswap/kaleido-mcp +cd kaleido-mcp +npm install +npm run build +``` + +无论哪种方式，服务器读取的环境变量都相同，并且默认使用 stdio 通信： + +```bash +# stdio（Claude Desktop、KaleidoAgent 等） +WDK_SEED="word1 word2 ..." node dist/index.js + +# HTTP 传输 +PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js +``` + +| 环境变量 | 是否必需 | 说明 | +|---------|----------|--------------| +| `WDK_SEED` | 使用 Spark 工具时必需 | Spark 钱包的 BIP-39 助记词。没有它服务器仍能启动，只是 Spark 工具会被禁用 | +| `SPARK_NETWORK` | 否 | `MAINNET` 或 `REGTEST` | +| `SPARK_SCAN_API_KEY` | 否 | SparkScan API 密钥 | +| `SPARK_USDT_TOKEN` | 否 | 默认的 Spark 代币标识符 | +| `RLN_NODE_URL` | 否 | RLN 守护进程 URL，默认 `http://localhost:3001` | +| `KALEIDOSWAP_API_URL` | 否 | KaleidoSwap API URL，默认 `https://api.kaleidoswap.com` | +| `KALEIDO_BIN` | 否 | `kaleido` 可执行文件的路径，供节点生命周期工具使用 | +| `KALEIDO_NODE_URL` | 否 | 以 `--node-url` 传给节点生命周期工具的节点 URL | +| `KALEIDO_API_URL` | 否 | 以 `--api-url` 传给节点生命周期工具的 API URL | +| `KALEIDO_ENV_NAME` | 否 | 节点生命周期工具的默认环境名 | +| `PORT` | 否 | 启用 Streamable HTTP 传输，替代 stdio | +| `MCP_AUTH_TOKEN` | 否 | HTTP 模式下的 Bearer token | + +### 遗留别名 + +为兼容早期集成，部分工具仍可通过旧名称调用（`rln_*` 对应 `wdk_*`，通用 `get_*` 对应 `l402_get_*` 行情工具）。新的集成应使用规范的 `wdk_*` / `l402_*` 名称。 + +## 按领域划分的工具集 + +下面所有工具都由 `kaleido-mcp` 通过同一条连接提供。🔒 图标在本文档中标记会动用资金的工具；`kaleido-mcp` 本身不携带确认标志，因此调用在执行前是否需要确认，取决于 MCP 宿主的行为。例外是 WDK 内置的 `sendTransaction` 和 `transfer`，它们会在广播前自行发起一次 MCP elicitation 确认。 + + + + WDK 内置工具（通过 `@tetherto/wdk-mcp-toolkit`，作用域限定在 `spark` 链）：`getAddress`、`getBalance`、`getMaxSpendableBtc`、`sendTransaction`、`transfer`、`getTokenBalance`、`quoteSendTransaction`、`quoteTransfer`、`getFeeRates`、`sign`、`verify`。 + + 在内置工具之上的自定义 Spark 工具： + + | 工具 | 用途 | + |------|---------| + | `spark_get_balance` | Spark 二层钱包余额，以聪计价（转账免费） | + | `spark_get_address` | 用于接收聪或代币的 Spark 二层地址 | + | `spark_get_token_balance` | 按代币标识符查询某个 Spark 代币（如 USDT）的余额 | + | `spark_get_deposit_address` | 将 BTC 桥接进 Spark 二层钱包的比特币一层地址 | + | `spark_create_lightning_invoice` | 通过闪电网络把 BTC 收入 Spark 的 BOLT11 发票 | + | `spark_pay_lightning_invoice` 🔒 | 从 Spark 钱包支付一张 BOLT11 发票 | + | `spark_quote_lightning_payment` | 支付前预估闪电路由费 | + | `spark_send_sats` 🔒 | 向另一个 Spark 二层地址发送聪（免费） | + | `spark_transfer_token` 🔒 | 把 Spark 代币（如 USDT）转到另一个地址（免费） | + | `spark_quote_withdraw` | 协作退出提取到比特币一层的费用报价 | + | `spark_withdraw` 🔒 | 从 Spark 二层提取 BTC 到比特币一层地址 | + | `spark_get_transfers` | 最近的 Spark 二层转账历史 | + | `spark_create_sats_invoice` | 用于接收 BTC 聪的 Spark 发票（`spark1...`） | + | `spark_create_tokens_invoice` | 用于接收代币的 Spark 发票（`spark1...`） | + | `spark_pay_spark_invoice` 🔒 | 支付一张或多张 Spark 发票 | + | `spark_get_spark_invoices` | 查询一张或多张 Spark 发票的状态 | + | `spark_mpp_pay` 🔒 | 从 Spark 钱包支付一个 MPP 闪电挑战 | + + 在独立的 `wdk-wallet-spark-mcp` 服务器上通过 `WDK_SPARK_SEED` 配置，另有可选的 `SPARK_NETWORK`、`SPARK_SCAN_API_KEY` 和 `SPARK_USDT_TOKEN`。 + + + + | 工具 | 用途 | + |------|---------| + | `wdk_get_node_info` | 节点身份信息：pubkey、通道数量、闪电余额、对等节点 | + | `wdk_get_balances` | BTC 链上余额（普通与着色 UTXO）以及闪电余额 | + | `wdk_get_asset_balance` | 按 `asset_id` 查询某个 RGB 资产（USDT、XAUT）的余额 | + | `wdk_list_assets` | 节点持有的全部 RGB 资产（NIA、UDA、CFA schema） | + | `wdk_get_address` | 用于接收存入的链上 BTC 地址 | + | `wdk_create_rgb_invoice` | 创建一张 RGB 发票以接收 RGB 资产 | + | `wdk_create_ln_invoice` | 创建一张 BOLT11 发票，通过闪电网络接收 BTC | + | `wdk_pay_invoice` 🔒 | 支付一张 BOLT11 闪电发票 | + | `wdk_send_btc` 🔒 | 链上发送 BTC | + | `wdk_send_asset` 🔒 | 链上发送 RGB 资产（USDT/XAUT） | + | `wdk_list_channels` | 所有闪电通道：容量、余额、可用性、RGB 分配 | + | `wdk_connect_peer` | 连接到某个闪电对等节点（`pubkey@host:port`），LSPS1 购买通道前必需 | + | `wdk_open_channel` 🔒 | 开通一条闪电通道，可选携带 RGB 资产分配 | + | `wdk_close_channel` 🔒 | 关闭一条闪电通道（`force=true` 仅用于无响应的对等节点） | + | `wdk_get_channel_id` | 把 `temporary_channel_id` 解析为永久的 `channel_id` | + | `wdk_list_payments` | 最近的闪电支付，收发均含 | + | `wdk_refresh_transfers` | 同步待处理的 RGB 资产转移，在 KaleidoSwap 订单成交后调用 | + | `wdk_atomic_taker` 🔒 | 原子 HTLC 交换的第 2 步，把进入的 HTLC 加入白名单 | + | `wdk_list_swaps` | 列出节点上的所有原子交换，含做市方与接单方两侧 | + | `wdk_get_swap` | 按 `payment_hash` 查询原子交换状态 | + | `wdk_mpp_pay` 🔒 | 从 RLN 钱包支付一个 MPP 闪电挑战 | + + 需要一个运行中的 [RGB Lightning Node](https://github.com/RGB-Tools/rgb-lightning-node)，可通过 `RLN_NODE_URL` 访问，默认 `http://localhost:3001`。 + + + + | 工具 | 用途 | + |------|---------| + | `kaleidoswap_get_assets` | 可交易资产：代号、名称、精度、RGB 协议 ID | + | `kaleidoswap_get_pairs` | 可交易的交易对及其可用的分层路由 | + | `kaleidoswap_get_quote` | 一笔交换的价格报价，返回输出数量、价格、费用和 `rfq_id` | + | `kaleidoswap_get_spreads` | 某个交易对在每条路由上的报价，用于比价或发现套利机会 | + | `kaleidoswap_place_order` | 下一个 REST 交换订单，返回一个 `deposit_address` | + | `kaleidoswap_get_order_status` | 轮询订单状态，直到 `FILLED`、`FAILED`、`EXPIRED` 或 `CANCELLED` | + | `kaleidoswap_get_open_orders` | 本会话中下过的订单及其最后已知状态 | + | `kaleidoswap_cancel_order` | 在本地会话跟踪器中把订单标记为已取消 | + | `kaleidoswap_get_position` | 本会话交易统计：成交率、按资产统计的交易量 | + | `kaleidoswap_atomic_init` | 原子交换的第 1 步，返回 `swapstring` 和 `payment_hash` | + | `kaleidoswap_atomic_execute` 🔒 | 第 3 步，在 `wdk_atomic_taker` 把 HTLC 加入白名单后确认执行 | + | `kaleidoswap_atomic_status` | 按 `payment_hash` 轮询原子交换状态 | + | `kaleidoswap_lsp_get_info` | LSP 的对等节点连接信息与通道容量上限 | + | `kaleidoswap_lsp_estimate_fees` | 在下单前预估 LSPS1 开通通道的费用 | + | `kaleidoswap_lsp_create_order` 🔒 | 申请一条新的闪电通道（LSPS1），返回一张 BOLT11 发票 | + | `kaleidoswap_lsp_get_order` | 轮询 LSPS1 通道订单状态 | + | `kaleidoswap_lsp_quote_asset_channel` | 为预装了 RGB 资产（USDT、XAUT）的新通道报价 | + | `kaleidoswap_lsp_create_asset_channel` 🔒 | 向 LSP 订购一条预装资产的新通道 | + + 通过 `KALEIDOSWAP_API_URL` 配置。底层接口端点请见[交换协议](/cn/api-reference/swap-protocol)和 [RGB LSPS1 API](/cn/api-reference/rgb-lsps1-apis)参考。 + + + + | 工具 | 用途 | + |------|---------| + | `mpp_request_challenge` | 探测一个受 MPP 保护的 URL，把 HTTP 402 解析为发票 + `challenge_id` | + | `mpp_submit_credential` | 提交支付凭据（在 `wdk_mpp_pay` / `spark_mpp_pay` 之后）以访问资源 | + | `mpp_parse_challenge_header` | 不发 HTTP 请求，直接解析原始的 `WWW-Authenticate` 头 | + | `l402_request_challenge` | 针对付费接口端点的遗留 L402 挑战，返回 BOLT11 发票加 macaroon | + | `l402_fetch_resource` | 支付发票后获取受 L402 保护的资源 | + | `search_paid_apis` | 在 [402index.io](https://402index.io) 目录中搜索付费门控 API（L402/MPP/x402），含以聪计价的价格和健康状态 | + + + + WDK 内置行情工具（Bitfinex）：`getCurrentPrice`、`getHistoricalPrice`。 + + | 工具 | 用途 | + |------|---------| + | `l402_get_price` | 单个资产的现货价格和 24 小时统计 | + | `l402_get_market_data` | 一次调用批量获取多个资产的价格 | + | `l402_get_ohlcv` | OHLCV K 线，附带区间涨跌幅 | + | `l402_get_sentiment` | 恐慌与贪婪指数，0 到 100，附带一个交易信号 | + + 使用免费的公开 API（CoinGecko、alternative.me），无需任何配置。CoinGecko 免费层有速率限制，因此调用行情工具的间隔不要短于 30 秒。 + + + + 通过调用本地的 `kaleido` 可执行文件工作，因此代理可以自己把节点拉起来并解锁，而不必要求节点已在运行。这些操作的 CLI 原生等价方式见[节点环境](/cn/cli/node-environments)。 + + | 工具 | 用途 | + |------|---------| + | `kaleido_node_list` | 列出所有 kaleido 节点环境及其节点 URL | + | `kaleido_node_up` | 为指定环境启动 Docker 容器 | + | `kaleido_node_stop` | 停止运行中的容器，数据保留 | + | `kaleido_node_down` | 停止并删除容器和网络，卷保留 | + | `kaleido_node_ps` | 指定环境的 Docker 容器状态 | + | `kaleido_node_status` | RLN 节点健康检查 | + | `kaleido_node_info` | 来自当前 RLN 节点的详细节点与网络信息 | + | `kaleido_node_use` | 在 kaleido 配置中设置当前节点 URL | + | `kaleido_node_init` | 首次初始化 RLN 钱包 | + | `kaleido_node_unlock` | 重启后解锁 RLN 钱包 | + | `kaleido_node_lock` | 锁定 RLN 钱包 | + + + +## 客户端配置 {#client-configuration} + +把服务器添加到 Claude Desktop 这类 MCP 宿主中。已发布的网关用 `npx` 即可；独立的钱包服务器则从本地构建运行。 + + + 这些配置文件以明文保存着真实的 BIP-39 助记词。请先在测试网络上起步，绝不要提交或分享包含主网种子的配置。 + + + +```json kaleido-mcp +{ + "mcpServers": { + "kaleido": { + "command": "npx", + "args": ["-y", "kaleido-mcp"], + "env": { + "WDK_SEED": "your twelve word seed phrase", + "SPARK_NETWORK": "REGTEST", + "RLN_NODE_URL": "http://localhost:3001", + "KALEIDOSWAP_API_URL": "https://api.kaleidoswap.com" + } + } + } +} +``` + +```json wdk-wallet-mcp +{ + "mcpServers": { + "wdk_wallet": { + "command": "node", + "args": ["/path/to/wdk-wallet-mcp/dist/index.js"], + "env": { + "RLN_NODE_URL": "http://localhost:3001" + } + } + } +} +``` + +```json wdk-wallet-spark-mcp +{ + "mcpServers": { + "wdk_wallet_spark": { + "command": "node", + "args": ["/path/to/wdk-wallet-spark-mcp/dist/index.js"], + "env": { + "WDK_SPARK_SEED": "your twelve word seed phrase", + "SPARK_NETWORK": "REGTEST" + } + } + } +} +``` + + +## 跨服务器的原子交换 {#atomic-swap-across-servers} + +一笔原子交换需要 DEX 工具和钱包工具配合。`kaleido-mcp` 用它的 `kaleidoswap_*` 工具与做市方通信，并用 `wdk_*` 工具驱动接单方节点。任何一步都不涉及托管，HTLC 在闪电网络上结算。 + +``` +kaleidoswap_get_quote → rfq_id + raw amounts +kaleidoswap_atomic_init → swapstring + payment_hash +wdk_atomic_taker → whitelist the HTLC on the node +wdk_get_node_info → taker_pubkey +kaleidoswap_atomic_execute → trigger HTLC settlement +kaleidoswap_atomic_status → poll until Succeeded +``` + +上面每一步都走同一条 `kaleido-mcp` 连接，因为两组前缀同时可用。 + +## 付费 API 访问 {#paid-api-access} + +Machine Payments Protocol 流程让代理无需 API 密钥、无需注册就能买到受门控资源的访问权，直接通过闪电网络支付发票。 + +``` +mpp_request_challenge(url) → challenge { invoice, challenge_id } +wdk_mpp_pay(invoice, challenge_id) → payment credential +mpp_submit_credential(url, cred) → { ok, data, receipt } +``` diff --git a/mintlify-docs/cn/ai-tools/skills.mdx b/mintlify-docs/cn/ai-tools/skills.mdx new file mode 100644 index 0000000..e4d2f77 --- /dev/null +++ b/mintlify-docs/cn/ai-tools/skills.mdx @@ -0,0 +1,31 @@ +--- +title: "面向 AI 代理的 Skills 操作手册" +sidebarTitle: "Skills" +description: "SKILL.md 操作手册限定代理能调用哪些工具并承载执行计划：了解 KaleidoAgent 自带的每个 skill 分别负责什么。" +--- + +一个 skill 就是一个在运行时加载的自包含 `SKILL.md` 文件。它限定模型能够调用哪些工具，并承载执行计划，因此改变行为无需改动运行时代码。[KaleidoAgent](/cn/ai-tools/kaleido-agent) 的 skill 还支持 `!` bash 注入：这些命令会先执行，并在提示词到达 LLM 之前把输出内联进去。 + +## 可用的 skill + +| Skill | 用途 | +|-------|---------| +| `kaleidoagent` | 核心行为与每日报告：投资组合快照、行情数据、交易历史 | +| `portfolio-manager` | 从偏移检测到原子交换执行，包含完整的风险校验 | +| `channel-manager` | 节点健康度、RGB 转移 flush、LSPS1 购买通道 | +| `dca` | 按计划、感知价格的买入，受用户设定的上限约束 | +| `wallet-assistant` | 以对话方式查询余额、生成发票、支付和交换 | +| `cross-l2` | 在 Spark、闪电网络和链上比特币之间转移资产 | +| `kaleidoswap` | KaleidoSwap DEX 参考：报价、原子交换、REST 订单、未平仓头寸 | +| `mpp` | 通过闪电网络访问受 HTTP 402 门控的 API | +| `node-manager` | RGB Lightning Node 生命周期、钱包解锁、通道与余额检查 | +| `portfolio-loop` | 定时的投资组合再平衡器：对照目标测量偏移，执行最小规模的原子交换，并把 DCA 一并纳入 | +| `node-loop` | 定时的节点健康监控：通道流动性审计、清理卡住的 RGB 转移、低于阈值时自动通过 LSPS1 购买 | +| `bitrefill` | 通过 Bitrefill 购买礼品卡、手机充值和 eSIM，可用闪电网络支付 | + +`agent.config.json` 中默认启用的 skill 是 `portfolio-loop`、`node-loop` 和 `bitrefill`。 + +每个文件都发布在 [kaleido-agent 仓库的 `skills/` 目录](https://github.com/kaleidoswap/kaleido-agent/tree/main/skills)下，也可以从 [AI 工具产品页](https://kaleidoswap.com/products/ai-tools#skills)阅读或下载。 + +skill 可以在运行时通过代理的 `/skills` [状态 API 接口端点](/cn/ai-tools/kaleido-agent#status-api)列出、启用和禁用。 + diff --git a/mintlify-docs/cn/ai-tools/troubleshooting.mdx b/mintlify-docs/cn/ai-tools/troubleshooting.mdx new file mode 100644 index 0000000..99ae5a7 --- /dev/null +++ b/mintlify-docs/cn/ai-tools/troubleshooting.mdx @@ -0,0 +1,217 @@ +--- +title: "AI 工具故障排查" +sidebarTitle: "故障排查" +description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、工具缺失、节点报错、种子配置错误，以及原子交换失败。" +--- + +## MCP 连接问题 + + + + **现象**：工具不存在，或宿主把该服务器列为启动失败。 + + **解决办法**： + 1. **先构建。** 单域服务器从 `dist/` 运行，而在 `npm run build` 成功之前该目录并不存在。 + 2. **使用绝对路径。** `args` 必须指向 `dist/index.js` 的完整路径，而不是相对路径。宿主并不是从你的项目目录启动的。 + 3. **重启宿主。** MCP 宿主只在启动时读取配置，已经在运行的客户端不会识别新服务器。 + 4. **检查 JSON。** 多余的逗号或没加引号的键，在多数宿主中会让整份配置静默失效。 + + + + **现象**：宿主报告进程在启动时就已终止。 + + **原因**：缺少某个必需的环境变量。独立的 `wdk-wallet-spark-mcp` 在没有 `WDK_SPARK_SEED` 时会拒绝启动。`kaleido-mcp` 要宽容一些：没有 `WDK_SEED` 时它仍会启动，记录一条警告，并禁用 Spark 工具。 + + **解决办法**： + 1. 确认种子变量写在宿主配置的 `env` 块中，而不是你的 shell 里（宿主不会继承你的 shell 环境）。 + 2. 确认助记词是合法的 BIP-39 短语，单词之间以单个空格分隔。 + 3. 用同样的环境变量手动运行服务器，直接看报错： + ```bash + WDK_SPARK_SEED="your twelve word seed phrase" node dist/index.js + ``` + + + + **现象**：Streamable HTTP 请求被拒绝。 + + **原因**：服务器上设置了 `MCP_AUTH_TOKEN`，因此每个请求都必须携带 bearer token。 + + **解决办法**： + 1. 发送 `Authorization: Bearer `，值与 `MCP_AUTH_TOKEN` 完全一致。 + 2. 如果你本来不想启用鉴权，请取消 `MCP_AUTH_TOKEN` 并重启。仅在回环接口上这样做。 + + + + **现象**：`spark_*` 工具可用，但 `wdk_*` 或 `kaleidoswap_*` 不可用，或者反过来。 + + **原因**：你连接的是某个单域服务器，而不是统一网关。每个单域服务器只暴露它自己那一块。 + + **解决办法**： + 1. 使用 `kaleido-mcp`，一条连接拿到全部前缀。 + 2. 或者把每个单域服务器分别加入宿主配置。 + + + +## 节点与钱包报错 + + + + **现象**：钱包或通道工具失败，而行情数据工具仍然正常。 + + **原因**：`RLN_NODE_URL`（默认 `http://localhost:3001`）上没有可访问的 RGB Lightning Node。 + + **解决办法**： + 1. 启动一个节点。最快的方式是用 CLI： + ```bash + kaleido setup --mode local --create-node --defaults + ``` + 2. 确认它有响应： + ```bash + curl http://localhost:3001/nodeinfo + ``` + 3. 如果节点跑在别处，在宿主配置中把 `RLN_NODE_URL` 设为那个地址。 + 4. 基于 Docker 的部署方式见[节点环境](/cn/cli/node-environments)。 + + + + **现象**：节点有响应，但钱包调用报解锁或密码相关的错误。 + + **原因**：RGB Lightning Node 启动后必须先解锁，才会提供钱包操作。 + + **解决办法**： + 1. 通过 CLI 解锁，或使用 `kaleido-mcp` 暴露的 `kaleido_node_unlock` 工具。 + 2. 请预留等待时间：解锁过程会先同步节点，之后才完全可用。 + + + + **现象**：`skill` 模式下的 KaleidoAgent，或 `kaleido_node_*` 工具执行失败。 + + **原因**：可执行文件不在进程能看到的 `PATH` 中。 + + **解决办法**： + 1. 确认它能被解析：`kaleido --version` + 2. 在服务器或代理配置中把 `KALEIDO_BIN` 设为该可执行文件的绝对路径。 + 3. 如果尚未安装，请按 [CLI 快速上手](/cn/cli/getting-started)安装。 + + + + **现象**：对一个你确定已入资的钱包，工具返回空余额。 + + **解决办法**： + 1. **检查网络。** `SPARK_NETWORK` 和节点自身的网络必须与资金所在的网络一致。regtest 的种子在主网上什么都看不到。 + 2. **确认种子。** 换一份助记词派生出的是另一个钱包，而不是一个空钱包。 + 3. **等待同步。** 刚解锁的节点可能还没追上链的最新高度。 + 4. **区分链上与闪电。** `wdk_get_balances` 会把普通与着色 UTXO 和闪电余额分开列出，而通道里的资产并不是链上余额。 + + + +## 交换失败 + + + + **现象**：使用某个 `rfq_id` 时被拒绝。 + + **原因**：报价的有效期很短，而一轮 LLM 对话加上一次确认提示就可能超时。 + + **解决办法**： + 1. 在发起交换前立刻重新询价，不要复用早先的 `rfq_id`。 + 2. 在提示词或 skill 中减少询价与执行之间的步骤数。 + + + + **现象**：`kaleidoswap_atomic_execute` 报错，或状态一直停留在 pending。 + + **原因**：一笔原子交换需要 DEX 工具和钱包工具按顺序配合，还需要你这一侧有通道流动性。 + + **解决办法**： + 1. 确认整个顺序都跑完了：在 DEX 上 init，用 `wdk_atomic_taker` 在你的节点上把 HTLC 加入白名单，然后执行。见[跨服务器调用顺序](/cn/ai-tools/mcp-servers#atomic-swap-across-servers)。 + 2. 确认资产确实**在通道里**。仅有链上余额无法结算一笔闪电交换。 + 3. 按 `payment_hash` 轮询 `kaleidoswap_atomic_status` 获取真实状态。 + 4. 如果任一侧卡住，时间锁到期后双方各自取回自己的资金。这是设计好的结果，不是交换丢失。 + + + + **现象**：一笔交换的报价或执行金额远高于或远低于预期。 + + **原因**：工具接收的是以资产最小单位计价的**原始数量**，而不同资产精度不同。USDT 通常使用 6 位小数，而 BTC 的数量以聪计价。 + + **解决办法**： + 1. 在构造数量之前，先用 `kaleidoswap_get_assets` 读取每个资产的精度。 + 2. 让模型在确认信息中同时给出原始数量和显示数量，这样在你批准之前就能看出不一致。 + + + +## KaleidoAgent 问题 + + + + **现象**：循环在跑，也报告了打算执行的交易，但什么都没有真正执行。 + + **原因**：`portfolio.dry_run` 为 `true`。这是默认值，并且是有意为之。 + + **解决办法**：只有当连续几轮的 dry-run 决策都看起来正确之后，再把它设为 `false`。 + + + + **现象**：代理原本在执行，之后就不再提交交换了。 + + **原因**：某个风险上限被触发。最常见的是 `stop_loss_btc_sats`（低于其 BTC 阈值时停止所有交易），或者 `min_btc_reserve_sats`。 + + **解决办法**： + 1. 读取 `GET /status` 查看余额和最近的运行记录。 + 2. 把它们与 `agent.config.json` 中的上限做对比。 + 3. 给钱包补充资金，或者有意识地调整阈值，而不是把这道防线直接去掉。 + + + + **现象**：投资组合已经偏离目标，但没有提出任何交换。 + + **原因**：偏移还没有超过 `rebalance_threshold_pct`，其默认值为 5%。 + + **解决办法**：降低该阈值，或用 `POST /run` 配合 `{"task_id":"rebalance"}` 手动触发一轮。 + + + + **现象**：代理能启动，但推理调用失败。 + + **解决办法**： + 1. 确认 `.env` 中设置了 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`。 + 2. 确认 `AGENT_PROVIDER` 与你实际提供的那个密钥相匹配。 + + + +## 速率限制与数据 + + + + **现象**：`l402_get_price` 或 `l402_get_market_data` 间歇性失败。 + + **原因**：这些公开接口端点背后的 CoinGecko 免费层有速率限制。 + + **解决办法**： + 1. 调用行情工具的间隔不要短于 30 秒。 + 2. 用 `l402_get_market_data` 把多个资产合并到一次调用，而不是循环逐个请求。 + + + +## 获取帮助 + +如果遇到的是疑问而不是报错，请查看[常见问题](/cn/ai-tools/faq)。其他情况请通过下面任一渠道反馈问题，并附上： + +1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本） +2. 你所在的网络（regtest、signet 或主网） +3. 失败的工具名称和报错文本 +4. 宿主与运行时版本（MCP 客户端、Node.js） +5. 你的配置，并移除其中的种子和所有密钥 + + + + 向社区提问。 + + + 在相关仓库提交缺陷报告。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/api-reference/error-handling.mdx b/mintlify-docs/cn/api-reference/error-handling.mdx new file mode 100644 index 0000000..ae29048 --- /dev/null +++ b/mintlify-docs/cn/api-reference/error-handling.mdx @@ -0,0 +1,143 @@ +--- +title: "交换 API 错误处理" +sidebarTitle: "错误处理" +description: "了解 KaleidoSwap API 如何报告错误：HTTP 状态码、错误响应格式，以及构建高可用集成的处理策略与重试建议。" +--- + +KaleidoSwap API 使用标准 HTTP 状态码和详细的错误信息来传达 API 请求的结果。本节概述常见错误类型以及有效的处理方式。 + +--- + +## HTTP 状态码 + +### 2xx：成功 +- **200 OK**：请求成功，服务器返回了预期的响应。 + +### 4xx：客户端错误 +这类错误表示客户端请求存在问题： +- **400 Bad Request**：请求格式错误或包含无效参数。 +- **401 Unauthorized**：Bearer API 密钥缺失或无效（在 API 密钥强制校验开启后返回）。 +- **403 Forbidden**：客户端无权访问所请求的资源。 +- **404 Not Found**：找不到所请求的资源。 +- **429 Too Many Requests**：客户端已超出允许的速率限制。 + +### 5xx：服务器错误 +这类错误表示服务端存在问题： +- **500 Internal Server Error**：服务器发生了意外错误。 +- **502 Bad Gateway**：服务器从上游服务器收到了无效响应。 +- **503 Service Unavailable**：服务暂时不可用，可能因维护或过载导致。 + +--- + +## 错误响应格式 + +API 会根据请求失败的位置返回**三种不同的错误信封**。 + +### 应用错误 + +业务与应用错误（参数无效、资源缺失、冲突、速率限制、服务器错误）返回结构化信封： + +```json +{ + "error_code": "PAIR_NOT_FOUND", + "message": "Trading pair not found: BTC/USDT", + "details": {}, + "request_id": "req_01HV8Q9X7G0Q7Y3Z" +} +``` + +- `error_code`（`string`）：稳定的、机器可读的错误码（例如 `PAIR_NOT_FOUND`、`VALIDATION_ERROR`、`NOT_FOUND`、`RATE_LIMIT_EXCEEDED`、`INTERNAL_ERROR`）。 +- `message`（`string`）：错误的可读描述。 +- `details`（`object`）：关于该错误的可选结构化上下文（可能为空）。 +- `request_id`（`string`）：请求关联标识符 —— 联系支持团队时请一并提供。 + +### 请求校验错误（HTTP 422） + +在到达应用逻辑*之前*就未通过 schema 校验的请求，会返回 FastAPI 的校验信封，HTTP 状态码为 `422`： + +```json +{ + "detail": [ + { + "loc": ["body", "rfq_id"], + "msg": "Field required", + "type": "missing" + } + ] +} +``` + +- `detail`（`array`）：每个校验失败对应一个条目。 + - `loc`（`array<(string | integer)>`）：出错字段的路径。 + - `msg`（`string`）：校验错误信息。 + - `type`（`string`）：FastAPI/Pydantic 校验错误类型。 + +### 遗留错误 + +少数接口端点的部分 `400` 响应仍是一个裸的 detail 对象，**不含** `error_code` 或 `request_id` —— 例如 `POST /market/quote` 上不受支持的路由，或 `GET /market/pairs` 上格式错误的 `pair_ticker` 过滤条件： + +```json +{ + "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN" +} +``` + +- `detail`（`string`）：错误的可读描述。 + +处理 `400` 响应的客户端应同时兼容结构化信封和这种遗留形式。 + +--- + +## 常见错误 +以下是一些典型错误及其解决办法： + +### 400 Bad Request +- **原因**：请求中参数缺失或无效。 +- **解决办法**：核对请求载荷，确保所有必填字段都已提供且数据有效。 + +### 404 Not Found +- **原因**：请求的接口端点或资源不存在。 +- **解决办法**：检查接口端点 URL 和资源标识符。 + +### 429 Too Many Requests +- **原因**：客户端在短时间内发送了过多请求。 +- **解决办法**：在客户端应用中实现速率限制，并在指定的等待时间（如有提供）后重试。 + +### 500 Internal Server Error +- **原因**：服务器发生了意外错误。 +- **解决办法**：稍后重试请求。如果问题持续存在，请携带请求详情联系支持团队。 + +--- + +## WebSocket 错误处理 +对于 WebSocket 连接，错误以 JSON 消息形式传达。如果发生严重错误，服务器可能会关闭连接。 + +### 重连策略 +如果 WebSocket 连接意外关闭： + +1. 等待数秒（例如 5-10 秒）。 +2. 重新建立连接。 +3. 重新发送所有待处理的 `quote_request` 消息，以获取最新报价。 + +--- + +### 调试建议 +1. **查看日志**：监控应用日志，获取失败请求的详细信息。 +2. **校验输入**：确保所有请求参数和载荷都符合 API 要求。 +3. **联系支持**：对于持续出现或原因不明的错误，请提供以下信息： + - 请求 URL + - HTTP 方法 + - 请求载荷 + - 错误发生的时间戳 + - API 返回的完整错误响应 + +--- + +## 最佳实践 +1. **优雅处理错误**：在应用中实现完善的错误处理逻辑，避免崩溃或影响用户体验。 +2. **速率限制**：遵守 API 速率限制，避免出现 `429 Too Many Requests` 错误。 +3. **重试机制**：对于瞬时错误（例如 500 Internal Server Error），请实现带指数退避的重试机制。 + +--- + +关于错误码和故障排查的更多细节，请参阅 API 文档。 diff --git a/mintlify-docs/cn/api-reference/getting-started.mdx b/mintlify-docs/cn/api-reference/getting-started.mdx new file mode 100644 index 0000000..95ef8e5 --- /dev/null +++ b/mintlify-docs/cn/api-reference/getting-started.mdx @@ -0,0 +1,160 @@ +--- +title: "比特币交换 API：快速开始" +sidebarTitle: "快速开始" +description: "开始使用 KaleidoSwap 交换 API：signet 与主网的基础 URL、认证方式、请求格式和速率限制，快速完成首次集成。" +--- + +欢迎使用 KaleidoSwap API！本指南帮助你快速、高效地完成配置并开始调用 API。 + +--- + +## 基础 URL + +KaleidoSwap API 通过 HTTPS 提供访问，以保证通信安全。可用环境如下： + +### Signet（MutinyNet） +一个具备真实网络条件的公共测试网，建议在上主网之前用于集成测试。该环境**目前已上线**。此环境下的所有 API 请求都应发往以下基础 URL： + +- **基础 URL：** `https://api.signet.kaleidoswap.com/api/v1` + +### 比特币主网（即将推出） +主网环境是面向真实交易的生产接口端点。发布进展请关注后续更新。 + +- **基础 URL：** `https://api.kaleidoswap.com/api/v1` + +--- + +## 认证 + +### 当前状态 +匿名请求仍会被正常处理，因此你可以立即开始测试和集成 API。Bearer API 密钥（`Authorization: Bearer `）目前已被接受并记录归属。 + +### 强制校验上线计划 +API 密钥的强制校验正在逐步上线。一旦开启，不带有效密钥的请求将收到 `401` 响应 —— 集成方现在就应开始发送 API 密钥。详见[总览](/cn/api-reference/introduction#authentication)。 + +--- + +## 请求格式 + +### HTTP 方法 +该 API 使用以下 HTTP 方法： +- **GET：** 获取数据。 +- **POST：** 提交数据或执行操作。 + +实时报价推送使用 **WebSocket** 接口端点 —— 参见[交换协议](/cn/api-reference/swap-protocol)。 + +### 请求头 +请确保你的 `POST` HTTP 请求包含以下请求头： +- `Content-Type: application/json`（用于携带 JSON 载荷的请求） + +### 请求示例 +下面是一个发往测试网环境的 `POST` 请求示例： + +```bash +curl -X 'POST' \ + 'https://api.signet.kaleidoswap.com/api/v1/market/quote' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "from_asset": { + "asset_id": "BTC", + "layer": "BTC_LN", + "amount": 1500000 + }, + "to_asset": { + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "layer": "RGB_LN" + } +}' +``` + +每一条腿都要指定 `asset_id`、结算层 `layer`（例如 `BTC_LN`、`RGB_LN`、`BTC_L1`、`RGB_L1`），并可选地以该资产的最小单位指定 `amount` —— 两条腿中必须且只能有一条携带金额。 +--- + +## 响应格式 +KaleidoSwap API 的所有响应均为 JSON 格式，便于解析。典型响应包含： + +- 按对应 **schema** 结构组织的响应值。 +- `detail`：关于所遇错误的详细信息。 + +## 响应示例 +```json +{ + "rfq_id": "13d4777c-ae96-4858-9c7c-3ca730c5039a", + "from_asset": { + "asset_id": "BTC", + "name": "Bitcoin", + "ticker": "BTC", + "layer": "BTC_LN", + "amount": 1500000, + "precision": 8 + }, + "to_asset": { + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "name": "Tether USD", + "ticker": "USDT", + "layer": "RGB_LN", + "amount": 875000, + "precision": 6 + }, + "price": 59507000000, + "fee": { + "base_fee": 1000, + "variable_fee": 250, + "fee_rate": 0.0001, + "final_fee": 1250, + "fee_asset": "BTC", + "fee_asset_precision": 8 + }, + "timestamp": 1715896356, + "expires_at": 1715896416 +} +``` +--- + +## API 版本管理 +KaleidoSwap 使用版本号来保证向后兼容。当前 API 版本为： + +**版本**：`v1` + +版本号体现在基础 URL 中，例如 `https://api.signet.kaleidoswap.com/api/v1`。 + +--- + +## 速率限制 +为保证公平使用，API 实施速率限制。默认值为： +- **每 IP**：每分钟 600 次请求 +- **每接口端点**：每分钟 300 次请求 +- **全局**：每分钟 1000 次请求 + +这些限制可按部署配置，因此不同环境可能有所不同。每个响应都包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset` 请求头；超出限制的请求会收到 `429 Too Many Requests` 响应。 + +--- + +## 错误与调试 +API 返回标准 HTTP 状态码来表示请求结果： + +- **200**：成功 +- **400**：请求错误（例如参数无效） +- **404**：资源不存在 +- **500**：服务器内部错误 +关于错误处理的更多信息，见[错误处理](/cn/api-reference/error-handling)。 + +--- + +## 下一步 + + + + 在调用交换接口端点之前，先了解完整的接单方-做市方交换生命周期 + + + 获取资产、交易对和报价 + + + 创建并跟踪交换订单 + + + 订购通道并管理流动性 + + diff --git a/mintlify-docs/cn/api-reference/introduction.mdx b/mintlify-docs/cn/api-reference/introduction.mdx new file mode 100644 index 0000000..3a75b25 --- /dev/null +++ b/mintlify-docs/cn/api-reference/introduction.mdx @@ -0,0 +1,130 @@ +--- +title: "总览" +sidebarTitle: "总览" +description: "KaleidoSwap 比特币交换 API 提供 REST 接口端点，可在多协议比特币 DEX 上完成原子交换、获取市场数据以及下单开通闪电通道。" +--- + +RGB Lightning DEX API 用于与 RGB 闪电服务提供商（RGB-LSP）交互，后者按请求提供流动性并支持交换功能。交换协议采用接单方-做市方模型：客户端为交易对请求实时报价，并基于报价发起交换。该 API 同时支持 RGB LSPS1（Lightning Service Provider Specification），用于管理通道和流动性服务。 + +### 核心特性 +- **RGB LSPS1（Lightning Service Provider Specification）支持**：流动性服务与交换功能。 +- **实时市场数据**：基于 WebSocket 的请求/响应式报价推送（`quote_request`/`quote_response`）。 +- **交换协议**：接单方-做市方模型，用于发起和执行交换。 +- **资产与交易对管理**：完整的 API，用于获取支持的资产和交易对。 + +继续阅读[快速开始](/cn/api-reference/getting-started)。 + +--- + +## 两个子 API + +KaleidoSwap API 分为两个彼此独立的服务： + +| 子 API | 基础路径 | 用途 | +|---------|-----------|---------| +| **Maker API** | `/api/v1/` | 市场数据、报价、交换订单以及 LSPS1 通道操作 | +| **RLN API** | 节点根路径（例如 `http://:3001/`） | RGB Lightning Node 操作 —— 钱包、通道和支付 | + +**Maker API** 可公开访问，负责全部交易和流动性操作。**RLN API** 是直接由你自己的 RGB Lightning Node 根路径提供的 REST API（例如 `http://:3001/nodeinfo`），需要运行一个节点实例。 + +### 我该用哪个 API？ + +| 目标 | API | 接口端点分组 | +|------|-----|----------------| +| 获取可用资产或交易对 | Maker API | [市场 API](/cn/api-reference/market-apis) | +| 获取交换价格报价 | Maker API | [市场 API](/cn/api-reference/market-apis) | +| 发起或跟踪原子交换 | Maker API | [交换 API](/cn/api-reference/swap-apis) | +| 向 LSP 订购闪电通道 | Maker API | [RGB LSPS1 API](/cn/api-reference/rgb-lsps1-apis) | +| 通过 WebSocket 请求实时报价 | Maker API（WebSocket） | [交换协议](/cn/api-reference/swap-protocol) | +| 查询钱包余额或节点信息 | RLN API | 需要你自己的节点 | +| 收发 BTC 或 RGB 资产 | RLN API | 需要你自己的节点 | +| 开通或关闭闪电通道 | RLN API | 需要你自己的节点 | + + + 下方的 **交互式 API 演练场** 运行在 **signet 环境**（`https://api.signet.kaleidoswap.com`）。请用它来探索和测试。生产环境请在主网地址可用后改用主网 URL。 + + +--- + +## 认证 {#authentication} + +**当前状态**：所有 Maker API 接口端点均支持匿名访问。Bearer API 密钥（`Authorization: Bearer `）目前已被**接受并记录归属** —— 密钥携带 `quote:read`（市场数据与报价）和 `swap:execute`（交换发起/执行）等作用域 —— 但强制校验正在逐步上线，因此不带密钥的请求仍会被正常处理。API 演练场已预先配置 bearer 认证。 + +**即将上线**：一旦开启强制校验，缺失或无效密钥的请求将收到 `401` 响应。集成方现在就应开始发送 API 密钥，以便提前就绪。 + +--- + +## 基础响应格式 + +所有 API 响应遵循统一的 JSON 结构。成功响应直接返回请求的数据，形式为 JSON 对象或数组。错误使用三种信封格式之一。 + +**应用错误**（参数无效、资源缺失、冲突、速率限制、服务器错误）返回结构化信封： + +```json +{ + "error_code": "PAIR_NOT_FOUND", + "message": "Trading pair not found: BTC/USDT", + "details": {}, + "request_id": "req_01HV8Q9X7G0Q7Y3Z" +} +``` + +**请求校验错误**（schema 校验失败，HTTP `422`）返回 FastAPI 的校验信封： + +```json +{ + "detail": [ + { + "loc": ["body", "rfq_id"], + "msg": "Field required", + "type": "missing" + } + ] +} +``` + +**遗留错误**：少数接口端点的部分 `400` 响应仍是一个裸的 detail 对象，不含 `error_code` 或 `request_id` —— 例如 `/market/quote` 上不受支持的路由，或 `/market/pairs` 上格式错误的 `pair_ticker` 过滤条件： + +```json +{ + "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN" +} +``` + +HTTP 状态码遵循标准约定： + +| 状态码 | 含义 | +|--------|---------| +| `200` | 成功 | +| `400` | 请求错误 —— 参数无效 | +| `401` | 未授权 —— API 密钥缺失或无效（强制校验开启后） | +| `403` | 禁止访问 —— 该密钥不允许从此来源使用 | +| `404` | 资源不存在 | +| `422` | 无法处理的实体 —— 校验错误 | +| `429` | 请求过多 —— 超出速率限制 | +| `500` | 服务器内部错误 | +| `503` | 服务不可用 —— 做市方或 LSP 节点暂时无法访问 | + +完整的错误码列表见[错误处理](/cn/api-reference/error-handling)。 + +--- + +## 速率限制 + +速率限制适用于所有 API 接口端点。超出限制的请求会收到 `429 Too Many Requests` 响应。具体限制因接口端点和环境而异。构建集成时，请为重试实现指数退避，并尽可能在本地缓存静态数据（资产、交易对）。 + +--- + +## 使用 SDK + +除了直接调用 REST API，你也可以使用官方 KaleidoSDK 库，它们对这些接口端点做了封装，提供类型安全和便捷方法： + + + + 从 OpenAPI 规范自动生成的类型化客户端，提供 `client.maker.*` 和 `client.rln.*` 子客户端 + + + + 同步 Python 客户端，使用 Pydantic 模型，采用相同的子客户端架构 + + diff --git a/mintlify-docs/cn/api-reference/market-apis.mdx b/mintlify-docs/cn/api-reference/market-apis.mdx new file mode 100644 index 0000000..074e9cc --- /dev/null +++ b/mintlify-docs/cn/api-reference/market-apis.mdx @@ -0,0 +1,392 @@ +--- +title: 市场 API +description: 从 KaleidoSwap 做市方获取资产、交易对、路由与报价数据，为在多协议比特币 DEX 上发起原子交换做好准备。 +--- + +## 总览 + +市场 API 是任何交换集成的起点。在创建交换订单之前，你需要的信息都由它们提供： + +- **列出资产** —— 发现做市方支持的全部资产（资产 ID、ticker、精度、各层的交易限额）。 +- **列出交易对** —— 查看哪些交易对处于启用状态，以及它们支持哪些路由。 +- **请求报价** —— 为指定数量获取锁定价格；返回的 `rfq_id` 用于创建订单。 + +所有市场 API 接口端点均可公开访问，无需认证。 + +**基础 URL：** `https://api.signet.kaleidoswap.com/api/v1`（Signet） + +--- + +## 列出资产 + +### 接口端点 +**`GET /api/v1/market/assets`** + +### 说明 +列出做市方支持的资产，支持可选的过滤条件和分页。该接口端点可安全轮询并缓存。 + +### 查询参数 +所有过滤条件按 AND 组合，且均为可选。 + +| Parameter | Type | 说明 | +|-------------|---------|--------------------------------------------------------| +| `asset_id` | String | 按资产 ID 过滤（例如 `rgb:2dkSTbr-...`）。 | +| `ticker` | String | 按 ticker 过滤（例如 `BTC`、`USDT`）。 | +| `layer` | String | 按层过滤（例如 `BTC_LN`、`RGB_L1`）。 | +| `network` | String | 按网络过滤（例如 `LN`、`L1`）。 | +| `protocol` | String | 按协议过滤（例如 `BTC`、`RGB`）。 | +| `is_active` | Boolean | 按启用状态过滤。 | +| `limit` | Integer | 每页条目数（默认 50，最大 100）。 | +| `offset` | Integer | 分页偏移量（默认 0）。 | + +### 响应结构 +- **`assets`**：受支持资产的数组。 + - **`ticker`**：资产的简称或符号（例如 `USDT`）。 + - **`asset_id`**：资产的唯一标识符。 + - **`name`**：资产全称（例如 `Tether USD`）。 + - **`precision`**：资产的小数精度。 + - **`protocol_ids`**：协议名称到该资产在对应协议上的标识符的映射。 + - **`media`**：关于该资产的附加媒体或元数据（可选）。 + - **`issued_supply`**：该资产的总发行量。 + - **`timestamp`**：资产元数据的时间戳。 + - **`endpoints`**：各层交易限额的数组 —— 每一项包含 `layer`、`min_amount`、`max_amount`（以最小单位计）和 `is_active`。 + - **`is_active`**：布尔值，表示该资产当前是否启用。 + - **`added_at`**：该资产被添加的时间戳。 + - **`supported_layers`**：该资产可结算的层列表（例如 `["BTC_LN", "BTC_L1"]`）。 +- **`network`**：表明该响应对应主网、signet 还是 regtest。 +- **`total`**：匹配资产的总数（不只是当前页）。 +- **`limit`** / **`offset`**：请求中分页参数的回显。 +- **`timestamp`**：生成该响应时的服务端时间戳。 + +### 响应示例 +```json +{ + "assets": [ + { + "ticker": "USDT", + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "name": "Tether USD", + "precision": 6, + "protocol_ids": { + "RGB": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB" + }, + "media": null, + "issued_supply": 100000000000, + "timestamp": 1724676126, + "endpoints": [ + { + "layer": "RGB_LN", + "min_amount": 1000000, + "max_amount": 100000000000, + "is_active": true + } + ], + "is_active": true, + "added_at": 1724676126, + "supported_layers": ["RGB_LN"] + } + ], + "network": "regtest", + "total": 1, + "limit": 50, + "offset": 0, + "timestamp": 1724676126 +} +``` + +--- + +## 列出交易对 + +### 接口端点 + +`GET /api/v1/market/pairs` + +### 说明 + +获取交换操作支持的交易对列表，支持过滤条件和分页。该接口端点可安全轮询并缓存。 + +### 查询参数 +所有参数均为可选。用于指定单个交易对的标识方式彼此互斥。 + +| Parameter | Type | 说明 | +|---------------------------------|---------|---------------------------------------------------------| +| `pair_id` | String | 按交易对 UUID 过滤。 | +| `pair_ticker` | String | 按 `BASE/QUOTE` 格式的交易对 ticker 过滤。 | +| `base_ticker` + `quote_ticker` | String | 按资产 ticker 过滤。 | +| `from_asset_id` + `quote_asset_id` | String | 按资产 ID 过滤。 | +| `layer` | String | 按层过滤（例如 `BTC_LN`、`RGB_LN`）。 | +| `asset` | String | 按资产 ticker 或 ID 过滤（交易对任意一侧均可）。 | +| `active_only` | Boolean | 仅返回启用的交易对（默认 `true`）。 | +| `limit` | Integer | 每页条目数（默认 50，最大 100）。 | +| `offset` | Integer | 分页偏移量（默认 0）。 | + +### 响应结构 + +- `pairs`：受支持交易对的数组。 + - `id`：该交易对的唯一标识符（UUID）。 + - `base` / `quote`：完整的资产对象（`ticker`、`asset_id`、`name`、`precision`、`protocol_ids`、`media`、`issued_supply`、`endpoints`）。各层的最小/最大交易限额位于每个资产的 `endpoints` 数组中。 + - `price`：该交易对的指示性价格（字符串，可能为 `null`）。 + - `routes`：受支持的执行路由，每条包含 `from_layer` 和 `to_layer`。 + - `is_active`：布尔值，表示该交易对当前是否启用。 + - `ticker`：交易对 ticker（例如 `BTC/USDT`）。 + - `base_asset` / `base_asset_id`：基础资产的 ticker 和唯一标识符。 + - `quote_asset` / `quote_asset_id`：报价资产的 ticker 和唯一标识符。 +- `total`：匹配交易对的总数（不只是当前页）。 +- `limit` / `offset`：请求中分页参数的回显。 +- `timestamp`：生成该响应时的服务端时间戳。 + +### 响应示例 + +```json +{ + "pairs": [ + { + "id": "2c188c7b-a823-4e5b-a82f-4d9fcb5e80ba", + "base": { + "ticker": "BTC", + "asset_id": "BTC", + "name": "Bitcoin", + "precision": 8, + "protocol_ids": {}, + "media": null, + "issued_supply": null, + "endpoints": [ + { + "layer": "BTC_LN", + "min_amount": 100000, + "max_amount": 100000000000, + "is_active": true + } + ] + }, + "quote": { + "ticker": "USDT", + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "name": "Tether USD", + "precision": 6, + "protocol_ids": {}, + "media": null, + "issued_supply": 100000000000, + "endpoints": [ + { + "layer": "RGB_LN", + "min_amount": 1000000, + "max_amount": 100000000000, + "is_active": true + } + ] + }, + "price": "59507.00", + "routes": [ + { "from_layer": "BTC_LN", "to_layer": "RGB_LN" }, + { "from_layer": "RGB_LN", "to_layer": "BTC_LN" } + ], + "is_active": true, + "ticker": "BTC/USDT", + "base_asset": "BTC", + "base_asset_id": "BTC", + "quote_asset": "USDT", + "quote_asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB" + } + ], + "total": 1, + "limit": 50, + "offset": 0, + "timestamp": 1724676126 +} +``` +--- + +## 获取交易对路由 + +### 接口端点 +**`POST /api/v1/market/pairs/routes`** + +### 说明 +返回指定交易对支持的执行路由。请求体中必须且只能提供一种标识方式：`pair_id`、`from_asset_id` + `quote_asset_id`、`pair_ticker`，或 `base_ticker` + `quote_ticker`。 + +### 请求示例 +```json +{ + "pair_ticker": "BTC/USDT" +} +``` + +### 响应示例 +```json +{ + "routes": [ + { "from_layer": "BTC_LN", "to_layer": "RGB_LN" }, + { "from_layer": "RGB_LN", "to_layer": "BTC_LN" } + ] +} +``` + +如果所请求的交易对没有可用路由，该接口端点返回 `404` 错误。 + +--- + +## 发现路由 + +### 接口端点 +**`POST /api/v1/market/routes`** + +### 说明 +发现资产之间的直连路由和多跳路由。该响应仅供参考，不会预留流动性。 + +### 请求体 +| Field | Type | 说明 | +|--------------|---------|--------------------------------------------------------------------| +| `from_asset` | String | 源资产的 ticker 或 ID（必填）。 | +| `from_layer` | String | 按源层过滤（可选）。 | +| `to_asset` | String | 目标资产；省略时返回所有可达资产。 | +| `to_layer` | String | 按目标层过滤（可选）。 | +| `max_hops` | Integer | 最大跳数，1-5（默认 2）。 | + +### 响应示例 +```json +{ + "routes": [ + { + "steps": [ + { + "from_asset": "BTC", + "from_layer": "BTC_LN", + "to_asset": "USDT", + "to_layer": "RGB_LN", + "pair_ticker": "BTC/USDT", + "indicative_price": "59507.00" + } + ], + "total_hops": 1 + } + ], + "timestamp": 1724676126 +} +``` + +--- + +## 获取路由可达性矩阵 + +### 接口端点 +**`GET /api/v1/market/routes/matrix`** + +### 说明 +返回一个矩阵，展示哪些资产之间可以互相到达，以及每种组合的最小跳数。可安全轮询并缓存。 + +### 响应示例 +```json +{ + "matrix": [ + { + "from_asset": "BTC", + "to_asset": "USDT", + "layers": ["BTC_LN->RGB_LN"], + "min_hops": 1 + } + ], + "assets": ["BTC", "USDT"], + "timestamp": 1724676126 +} +``` + +--- + +## 为交易对请求报价 + +### 接口端点 +**`POST /api/v1/market/quote`** + +### 说明 +为两个资产腿之间的路由请求一份由 RFQ 支撑的报价。响应中包含该报价的详细信息，包括价格、费用和过期时间。 + +### 请求结构 + +请求体包含两个嵌套的腿对象 —— 没有 `pair_id`： + +- **`from_asset`**：源腿的规格。 + - **`asset_id`**：资产标识符（例如 `BTC` 或某个 RGB 合约 ID）。 + - **`layer`**：结算层（例如 `BTC_LN`、`RGB_LN`、`BTC_L1`、`RGB_L1`）。 + - **`amount`**（可选）：以该资产最小单位表示的数量。 +- **`to_asset`**：目标腿的规格 —— 字段与 `from_asset` 相同。 + +`from_asset.amount` 和 `to_asset.amount` 必须且只能提供其中一个：正向报价设置 `from_asset.amount`，反向报价设置 `to_asset.amount`。 + +### 请求示例 + +```json +{ + "from_asset": { + "asset_id": "BTC", + "layer": "BTC_LN", + "amount": 1500000 + }, + "to_asset": { + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "layer": "RGB_LN" + } +} +``` + +### 响应结构 + +- `rfq_id`：该报价请求的唯一标识符。 +- `from_asset` / `to_asset`：完整的腿规格，各自包含 `asset_id`、`name`、`ticker`、`layer`、`amount`（最小单位）和 `precision`。 +- `price`：1 个完整单位的 `from_asset` 的价格，以 `to_asset` 的最小单位表示。 +- `fee`：费用明细对象： + - `base_fee`：固定费用部分。 + - `variable_fee`：随数量变化的费用部分。 + - `fee_rate`：可变费用的费率。 + - `final_fee`：总费用（`base_fee + variable_fee`）。 + - `fee_asset`：费用计价所用的资产。 + - `fee_asset_precision`：费用资产的小数精度。 +- `timestamp`：生成该报价时的服务端时间戳。 +- `expires_at`：该报价过期的时间戳。 + +### 响应示例 + +```json +{ + "rfq_id": "13d4777c-ae96-4858-9c7c-3ca730c5039a", + "from_asset": { + "asset_id": "BTC", + "name": "Bitcoin", + "ticker": "BTC", + "layer": "BTC_LN", + "amount": 1500000, + "precision": 8 + }, + "to_asset": { + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "name": "Tether USD", + "ticker": "USDT", + "layer": "RGB_LN", + "amount": 875000, + "precision": 6 + }, + "price": 59507000000, + "fee": { + "base_fee": 1000, + "variable_fee": 250, + "fee_rate": 0.0001, + "final_fee": 1250, + "fee_asset": "BTC", + "fee_asset_precision": 8 + }, + "timestamp": 1715896356, + "expires_at": 1715896416 +} +``` + +### 补充说明 +- 所请求的路由（`from_asset.layer` → `to_asset.layer`）必须是 `/api/v1/market/pairs` 中该交易对所支持的 `routes` 之一；不受支持的路由返回 `400` 错误。 +- 数量应保持在每个资产 `endpoints` 数组中给出的各层 `min_amount`/`max_amount` 限额之内。 +- `expires_at` 字段表明该报价从何时起不再可用于发起交换。 +- 费用已计入所计算出的腿数量中。 +- 在过期之前，`rfq_id` 可用于后续的交换发起请求或 LSPS1 订单请求。 + +--- + +关于交换操作的更多细节，请继续阅读[交换 API](/cn/api-reference/swap-apis)。 diff --git a/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx b/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx new file mode 100644 index 0000000..c43bb41 --- /dev/null +++ b/mintlify-docs/cn/api-reference/rgb-lsps1-apis.mdx @@ -0,0 +1,317 @@ +--- +title: "闪电通道订单 API" +sidebarTitle: "通道订单" +description: "通过 LSPS1（Lightning Service Provider Specification）向闪电服务提供商订购通道并管理流动性，支持多资产通道。" +--- + +## 总览 + +RGB LSPS1 API 让客户端能够向闪电服务提供商（LSP）订购带 RGB 资产分配的闪电通道。在以下场景下使用这些接口端点： + +- **开通预分配 RGB 资产的通道** —— LSP 开通通道，并在 LSP 一侧预先注入所请求的资产数量。 +- **查询 LSP 能力** —— 在创建订单前查看支持的资产、通道大小上下限和费用结构。 +- **跟踪通道订单状态** —— 轮询订单，直到通道确认并开通。 + +当你通过默认 LSP 开通通道时，KaleidoSwap 桌面应用会使用这些接口端点。SDK 用户可以通过 `client.maker.createLspOrder()` 直接调用。 + +**基础 URL：** `https://api.signet.kaleidoswap.com/api/v1`（Signet） + +--- + +## 获取 LSP 信息 + +### 接口端点 +**`GET /api/v1/lsps1/get_info`** + +### 说明 +获取 RGB 闪电服务提供商的信息，包括可用资产、流动性选项和通道配置。 + +### 响应结构 +- **`lsp_connection_url`**：LSP 节点的连接 URI（`pubkey@host:port`）—— 订购通道前请先连接该对等节点。 +- **`options`**：订单和通道的配置项。 +- **`assets`**：由该 LSP 管理的资产列表。 + +### 响应示例 +```json +{ + "lsp_connection_url": "034eedc97802d7e2766704bd06d6bfded8aa2d35a1a007e277fd7278f3dc962706@lsp.signet.kaleidoswap.com:9735", + "options": { + "min_required_channel_confirmations": 0, + "min_funding_confirms_within_blocks": 0, + "min_onchain_payment_confirmations": 0, + "supports_zero_channel_reserve": true, + "min_onchain_payment_size_sat": 0, + "max_channel_expiry_blocks": 30160, + "min_initial_client_balance_sat": 0, + "max_initial_client_balance_sat": 100000000, + "min_initial_lsp_balance_sat": 0, + "max_initial_lsp_balance_sat": 100000000, + "min_channel_balance_sat": 50000, + "max_channel_balance_sat": 100000000 + }, + "assets": [ + { + "name": "Tether USD", + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "ticker": "USDT", + "precision": 6, + "issued_supply": 100000000000, + "min_initial_client_amount": 0, + "max_initial_client_amount": 0, + "min_initial_lsp_amount": 0, + "max_initial_lsp_amount": 1000000, + "min_channel_amount": 0, + "max_channel_amount": 1000000 + } + ] +} +``` + +--- + +## 获取网络信息 + +### 接口端点 +**`GET /api/v1/lsps1/network_info`** + +### 说明 +获取 LSP 节点当前的区块高度和所在网络。可安全轮询并缓存。 + +### 响应示例 +```json +{ + "network": "Signet", + "height": 805434 +} +``` + +--- + +## 费用预估 + +### 接口端点 + +`POST /api/v1/lsps1/estimate_fees` + +### 说明 + +在不创建订单的情况下预估通道订单的费用。当客户端购买资产时（`client_asset_amount > 0`），需要提供一个来自 `/market/quote` 的新鲜 `rfq_id`，以便将资产价格计入总额。 + +### 请求体 + +| Field | Type | 说明 | +|----------------------------------|---------|------------------------------------------------------------| +| `lsp_balance_sat` | Integer | 通道 LSP 一侧的余额，单位为聪。 | +| `client_balance_sat` | Integer | 通道客户端一侧的余额，单位为聪。 | +| `channel_expiry_blocks` | Integer | 通道在多少个区块后过期。 | +| `token`（可选） | String | 折扣码或推荐码。 | +| `asset_id`（可选） | String | 该通道使用的 RGB 资产 ID。 | +| `lsp_asset_amount`（可选） | Integer | LSP 一侧的 RGB 资产数量。 | +| `client_asset_amount`（可选） | Integer | 客户端一侧的 RGB 资产数量。 | +| `rfq_id`（可选） | String | 报价 ID —— 当 `client_asset_amount > 0` 时必填。 | + +### 响应示例 +```json +{ + "setup_fee": 1000, + "capacity_fee": 1500, + "duration_fee": 500, + "total_fee": 3000, + "applied_discount": null, + "discount_code": null +} +``` + +--- + +## 创建订单 + +### 接口端点 + +`POST /api/v1/lsps1/create_order` + +### 说明 + +向 RGB 闪电服务提供商创建一个新的通道订单。 + +### 请求体 + +| Field | Type | 说明 | +|----------------------------------|---------|------------------------------------------------------------| +| `client_pubkey` | String | 客户端的公钥（必填）。 | +| `lsp_balance_sat` | Integer | 通道 LSP 一侧的余额，单位为聪。 | +| `client_balance_sat` | Integer | 通道客户端一侧的余额，单位为聪。 | +| `required_channel_confirmations` | Integer | 该通道所需的确认数。 | +| `funding_confirms_within_blocks` | Integer | 注资应在多少个区块内确认。 | +| `channel_expiry_blocks` | Integer | 通道在多少个区块后过期。 | +| `token`（可选） | String | 应用于订单费用的折扣码或推荐码。 | +| `refund_onchain_address`（可选） | String | 订单失败或被拒时用于退款的链上地址。 | +| `announce_channel` | Boolean | 是否公开公告该通道。 | +| `asset_id`（可选） | String | 该通道使用的 RGB 资产 ID。 | +| `lsp_asset_amount`（可选） | Integer | LSP 一侧的 RGB 资产数量。 | +| `client_asset_amount`（可选） | Integer | 客户端一侧的 RGB 资产数量。 | +| `rfq_id`（可选） | String | 来自 `/market/quote` 的报价 ID。**当 `client_asset_amount > 0` 时必填** —— 此时客户端在购买资产，订单必须由一份新鲜报价支撑。 | +| `email`（可选） | String | 用于接收订单通知的邮箱地址。 | + +### 请求示例 + +```json +{ + "client_pubkey": "03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad", + "lsp_balance_sat": 100000, + "client_balance_sat": 50000, + "required_channel_confirmations": 3, + "funding_confirms_within_blocks": 144, + "channel_expiry_blocks": 4032, + "announce_channel": true, + "asset_id": "rgb:$i4cFKwt-2C5LZ3X-l$kOTGN-O6l1AOP-aP9COyn-7IeBkEM", + "lsp_asset_amount": 5000, + "client_asset_amount": 2500, + "rfq_id": "8e6635fb-ab37-4aed-89f4-bc9c98fb8b49", + "refund_onchain_address": "tb1qexampleaddress0000000000000000000000000", + "email": "ops@example.com" +} +``` + +### 响应体 + +| Field | Type | 说明 | +|-----------------------------------|------------------|----------------------------------------------------------------| +| `order_id` | String | 所创建订单的唯一标识符。 | +| `client_pubkey` | String | 客户端的公钥。 | +| `lsp_balance_sat` | Integer | 通道 LSP 一侧的余额，单位为聪。 | +| `client_balance_sat` | Integer | 通道客户端一侧的余额，单位为聪。 | +| `required_channel_confirmations` | Integer | 该通道所需的确认数。 | +| `funding_confirms_within_blocks` | Integer | 注资应在多少个区块内确认。 | +| `channel_expiry_blocks` | Integer | 通道在多少个区块后过期。 | +| `token` | String / Null | 与该订单关联的 token（如已提供）。 | +| `created_at` | String date-time | 订单创建的时间戳。 | +| `announce_channel` | Boolean | 该通道是否会被公开公告。 | +| `order_state` | String | 订单当前状态：`CREATED`、`CHANNEL_OPENING`、`COMPLETED`、`FAILED` 或 `PENDING_RATE_DECISION`。 | +| `payment` | Object | 支付详情，包括费用、发票或链上地址。支付过期时间位于 `payment.bolt11.expires_at` 和 `payment.onchain.expires_at`，顶层没有 `expires_at` 字段。 | +| `channel`（可选） | Object / Null | 通道已创建时的通道详情（其过期时间为 `channel.expires_at`）。 | +| `asset_id`（可选） | String / Null | 该通道使用的 RGB 资产 ID。 | +| `lsp_asset_amount`（可选） | Integer / Null | LSP 一侧的 RGB 资产数量。 | +| `client_asset_amount`（可选） | Integer / Null | 客户端一侧的 RGB 资产数量。 | +| `rfq_id`（可选） | String / Null | 创建该订单时所依据的报价 ID。 | +| `asset_price_sat`（可选） | Integer / Null | 为 `client_asset_amount` 支付的 BTC 价格（单位为聪）。 | +| `failure_reason`（可选） | String / Null | 当 `order_state` 为 `FAILED` 时，订单失败的原因。 | +| `access_token` | String | **调用 `get_order` 和 `rate_decision` 所需的单订单 token。仅在创建时返回一次 —— 请与订单 ID 一起保存。** | + +### 响应示例 + +```json +{ + "order_id": "string", + "client_pubkey": "string", + "lsp_balance_sat": 0, + "client_balance_sat": 0, + "required_channel_confirmations": 0, + "funding_confirms_within_blocks": 0, + "channel_expiry_blocks": 0, + "token": "", + "created_at": "2024-12-18T19:09:19.868Z", + "announce_channel": true, + "order_state": "CREATED", + "payment": { + "bolt11": { + "state": "EXPECT_PAYMENT", + "expires_at": "2024-12-18T19:09:19.868Z", + "fee_total_sat": 0, + "order_total_sat": 0, + "invoice": "string" + }, + "onchain": { + "state": "EXPECT_PAYMENT", + "expires_at": "2024-12-18T19:09:19.868Z", + "fee_total_sat": 0, + "order_total_sat": 0, + "address": "string", + "min_fee_for_0conf": 0, + "min_onchain_payment_confirmations": 0, + "refund_onchain_address": "string" + } + }, + "channel": null, + "asset_id": "string", + "lsp_asset_amount": 0, + "client_asset_amount": 0, + "rfq_id": "8e6635fb-ab37-4aed-89f4-bc9c98fb8b49", + "asset_price_sat": 0, + "failure_reason": null, + "access_token": "ord_live_3rCkP9dG7mN4" +} +``` +--- + +## 查询订单 + +### 接口端点 + +`POST /api/v1/lsps1/get_order` + +### 说明 +获取某个已存在订单的信息。该接口端点可安全轮询。 + +### 请求体 +| Field | Type | 说明 | +|----------------|----------|----------------------------------------------------------| +| `order_id` | String | 订单的唯一标识符。 | +| `access_token` | String | `create_order` 返回的单订单访问 token。 | + +### 请求示例 +```json +{ + "order_id": "550e8400-e29b-41d4-a716-446655440000", + "access_token": "ord_live_3rCkP9dG7mN4" +} +``` + +`access_token` 无效时返回 `400` 错误；`order_id` 未知时返回 `404`。 + +### 响应示例 +响应结构与 `create_order` 接口端点完全相同。 + +--- + +## 汇率决定 + +### 接口端点 + +`POST /api/v1/lsps1/rate_decision` + +### 说明 + +解决资产订单上的重新定价事件。如果在支付结算前市场汇率出现明显波动，LSP 不会直接开通通道，而是将订单置为 `PENDING_RATE_DECISION` 状态。客户端随后必须选择接受新汇率（订单按新价格继续），或拒绝新汇率（向 `refund_onchain_address` 发起退款）。 + +### 请求体 +| Field | Type | 说明 | +|-------------------|----------|-------------------------------------------------------------------| +| `order_id` | String | 订单的唯一标识符。 | +| `access_token` | String | `create_order` 返回的单订单访问 token。 | +| `accept_new_rate` | Boolean | `true` 表示接受新汇率，`false` 表示申请退款。 | + +### 请求示例 +```json +{ + "order_id": "550e8400-e29b-41d4-a716-446655440000", + "access_token": "ord_live_3rCkP9dG7mN4", + "accept_new_rate": true +} +``` + +### 响应示例 +```json +{ + "order_id": "550e8400-e29b-41d4-a716-446655440000", + "decision_accepted": true, + "message": "Rate accepted. Order will proceed with current market rate.", + "refund_txid": null +} +``` + +对不处于 `PENDING_RATE_DECISION` 状态的订单调用该接口端点会返回 `400` 错误。当申请退款并处理完成后，`refund_txid` 会携带链上交易 ID。 + +--- + +关于交易和市场操作的更多细节，请继续阅读[市场 API](/cn/api-reference/market-apis)。 diff --git a/mintlify-docs/cn/api-reference/swap-apis.mdx b/mintlify-docs/cn/api-reference/swap-apis.mdx new file mode 100644 index 0000000..3613d87 --- /dev/null +++ b/mintlify-docs/cn/api-reference/swap-apis.mdx @@ -0,0 +1,299 @@ +--- +title: 交换 API +description: 用于发起、执行和查询原子 HTLC 交换的接口端点 —— KaleidoSwap 桌面应用与直连节点的集成都建立在这些接口之上。 +--- + +## 总览 + +交换 API 实现了 KaleidoSwap 桌面应用所使用的**原子交换协议**。交换通过闪电网络上的哈希时间锁定合约（HTLC）执行 —— 双方同时锁定资产，因此要么整笔交换全部完成，要么资金原路退回。不存在对手方风险。 + +使用这些接口端点需要具备： +- 一个运行中的 **RGB Lightning Node（RLN）**，用于将 HTLC 加入白名单并进行路由。 +- 一条到做市方的 **WebSocket 连接**（或 REST `/market/quote` 接口端点），用于获取实时报价并生成 `rfq_id`。 + +报价和资产数据见[市场 API](/cn/api-reference/market-apis)，原子交换流程的完整讲解见[交换协议](/cn/api-reference/swap-protocol)。 + +**基础 URL：** `https://api.signet.kaleidoswap.com/api/v1`（Signet） + +--- + +## 获取节点信息 + +### 接口端点 +**`GET /api/v1/swaps/nodeinfo`** + +### 说明 +获取做市方 RGB Lightning Node 的公开身份信息 —— 包括其公钥、所在网络和当前区块高度。该接口端点可安全轮询。 + +### 响应结构 +- **`pubkey`**：做市方节点的公钥。 +- **`network`**：该节点所在的比特币网络（例如 `Signet`、`Regtest`、`Mainnet`）。 +- **`block_height`**：该节点已同步到的当前区块高度。 + +### 响应示例 +```json +{ + "pubkey": "034eedc97802d7e2766704bd06d6bfded8aa2d35a1a007e277fd7278f3dc962706", + "network": "Signet", + "block_height": 805434 +} +``` +--- + +## 通过 WebSocket 获取实时报价 +### WebSocket 接口端点 + +| Environment | URL | +|-------------|-----| +| **Signet** | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | +| **Mainnet** | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *（即将上线）* | + +### 说明 +建立 WebSocket 连接，向做市方请求实时报价。该协议采用请求/响应模式：客户端发送一条消息，服务端针对该消息回复。它没有订阅机制 —— 想让价格保持新鲜，就在需要更新报价时再发一条 `quote_request`。 + +### 连接 +- 将 `{client_id}` 替换为你的客户端的唯一标识符。 + +### 消息格式 +仅支持两种 action： + +- **`ping`** —— 心跳；服务端回复 `pong`。 +- **`quote_request`** —— 为两个资产之间的交换请求报价。 + +请求报价时，发送如下格式的 JSON 消息： + +```json +{ + "action": "quote_request", + "from_asset": "BTC", + "to_asset": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "from_amount": 1500000 +} +``` + +- **`from_asset`** / **`to_asset`**（必填）：资产标识符 —— 可以是 `BTC` 这类 ticker，也可以是 RGB 合约 ID。 +- **`from_amount`** / **`to_amount`**：以该资产**原始最小单位**表示的数量。两者必须且只能提供其中一个 —— 正向报价用 `from_amount`，反向报价用 `to_amount`。 +- **`from_layer`** / **`to_layer`**（可选）：显式指定结算层（例如 `BTC_LN`、`RGB_LN`）。省略时使用该交易对的默认路由。 + +### 响应格式 +服务端对每条 `quote_request` 回复一条 `quote_response` 消息，完整报价放在 `data` 中（结构与 REST `POST /api/v1/market/quote` 的响应相同）： + +```json +{ + "action": "quote_response", + "data": { + "rfq_id": "13d4777c-ae96-4858-9c7c-3ca730c5039a", + "from_asset": { + "asset_id": "BTC", + "name": "Bitcoin", + "ticker": "BTC", + "layer": "BTC_LN", + "amount": 1500000, + "precision": 8 + }, + "to_asset": { + "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB", + "name": "Tether USD", + "ticker": "USDT", + "layer": "RGB_LN", + "amount": 875000, + "precision": 6 + }, + "price": 59507000000, + "fee": { + "base_fee": 1000, + "variable_fee": 250, + "fee_rate": 0.0001, + "final_fee": 1250, + "fee_asset": "BTC", + "fee_asset_precision": 8 + }, + "timestamp": 1715896356, + "expires_at": 1715896416 + } +} +``` + +### 字段说明 + +- **`rfq_id`**：即 `request_for_quotation_id`，由做市方为该报价生成的唯一标识符。这个 ID 对发起交换至关重要，必须在 `expires_at` 之前传给 `init` 接口端点。 +- **`from_asset`** / **`to_asset`**：完整的腿规格，包含 `asset_id`、`name`、`ticker`、`layer`、`amount`（最小单位）和 `precision`。 +- **`price`**：1 个完整单位的 `from_asset` 的价格，以 `to_asset` 的最小单位表示。 +- **`fee`**：费用明细 —— `base_fee`、`variable_fee`、`fee_rate`、`final_fee`，以及费用计价所用的资产（`fee_asset`）和精度（`fee_asset_precision`）。 +- **`timestamp`**：报价生成的时间（unix 时间）。 +- **`expires_at`**：`rfq_id` 过期的时间（unix 时间）。 + +### 补充说明： + +- 请求失败时（交易对未知、路由不受支持、数量无效）返回的消息带有 `error` 字段，而不是 `quote_response`。 +- WebSocket 连接会一直保持，直到客户端断开或发生网络错误；请定期发送 `ping` 消息以维持连接健康。 + +--- + +## 发起交换 + +### 接口端点 + +`POST /api/v1/swaps/init` + +### 说明 +基于一份新鲜报价发起交换。该接口端点会锁定价格，并为执行做好准备。 + +### 请求体 +| Field | Type | 说明 | +|----------------------------|----------|---------------------------------------| +| `rfq_id` | String | 报价 ID，来自 WebSocket 的 `quote_response` 消息或 REST `POST /api/v1/market/quote` 接口端点。 | +| `from_asset` | String | 卖出方向的 RGB 资产 ID。 | +| `from_amount` | Integer | 卖出的资产数量。* | +| `to_asset` | String | 买入方向的 RGB 资产 ID。 | +| `to_amount` | Integer | 买入的资产数量。* | + +*如果资产是 BTC，数量应以**毫聪（msat）**为单位。其他资产的数量直接按该资产的原生单位提供，不考虑精度。 + +### 请求示例 +```json +{ + "rfq_id": "8e6635fb-ab37-4aed-89f4-bc9c98fb8b49", + "from_asset": "btc", + "from_amount": 1000000, + "to_asset": "rgb:2V2f58W-Tabtk3J4j-qGVQQwPWt-ksbujLNxx-x1BMTNBEf-KVsg2j3", + "to_amount": 587770 +} +``` + +### 响应结构 +- `swapstring`：待执行交换的字符串表示。 +- `payment_hash`：与该交换关联的支付哈希。 +- `access_token`：轮询 `/swaps/atomic/status` 所需的单笔交换 token。它只在发起时于此处返回一次 —— 请与支付哈希一起保存。 + +### 响应示例 +```json +{ + "swapstring": "1000000/btc/587770/rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB/be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e", + "payment_hash": "be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e", + "access_token": "ord_live_3rCkP9dG7mN4" +} +``` + +### 补充说明 + +- RGB 资产的精度可通过做市方节点上的 `/assets` API 获取。如果客户端持有同一资产，也可以通过节点 API 取得该精度。 +- 在执行交换之前，该接口端点返回的 swapstring 需要通过客户端 RGB Lightning Node（RLN）的 `/taker` API 加入白名单。 +- 在这个示例中，用户以 1,000 聪卖出，换取 0.5877 USDT（使用 RGB 资产 `rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB`）。 + +--- + +## 执行交换 + +### 接口端点 +`POST /api/v1/swaps/execute` + +### 说明 +在交换已发起并通过校验后执行该交换。 + +### 请求体 +| Field | Type | 说明 | +|----------------|----------|-----------------------------------------------| +| `swapstring` | String | 由 `init` 接口端点生成的 swap string。 | +| `taker_pubkey` | String | 接单方的公钥。 | +| `payment_hash` | String | 与该交换关联的支付哈希。 | + +### 请求示例 +```json +{ + "swapstring": "1000000/btc/587770/rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB/be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e", + "taker_pubkey": "03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad", + "payment_hash": "be35403fcd85722cb0373db0527a452ce9c2eb23d3ec489af8e33ffb57d5271e" +} +``` + +### 响应结构 +- `status`：交换执行的状态码。 +- `message`：关于本次执行的补充信息。 + +### 响应示例 +```json +{ + "status": 200, + "message": "Swap executed successfully" +} +``` +--- + +## 查询交换状态 + +### 接口端点 +`POST /api/v1/swaps/atomic/status` + +### 说明 +使用关联的 `payment_hash` 以及 `/swaps/init` 返回的单笔交换 `access_token`，获取某笔原子交换的当前状态。 + +### 请求体 +| Field | Type | 说明 | +|----------------|--------|--------------------------------------------------------| +| `payment_hash` | String | 要查询状态的那笔交换的支付哈希。 | +| `access_token` | String | `/swaps/init` 返回的单笔交换访问 token。 | + +### 请求示例 +```json +{ + "payment_hash": "7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664", + "access_token": "ord_live_3rCkP9dG7mN4" +} +``` + +### 响应 + +- `swap`：包含该交换详细信息的对象。 + +### 响应示例 +```json +{ + "swap": { + "qty_from": 1000000, + "qty_to": 587770, + "from_asset": "btc", + "to_asset": "rgb:2V2f58W-Tabtk3J4j-qGVQQwPWt-ksbujLNxx-x1BMTNBEf-KVsg2j3", + "payment_hash": "7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664", + "status": "Pending", + "requested_at": 1691160765, + "initiated_at": 1691168512, + "expires_at": 1691172703, + "completed_at": 1691171075 + } +} +``` + +### Swap 对象结构 +- **`qty_from`**（`integer`）：卖出方向的资产数量。示例：`30` +- **`qty_to`**（`integer`）：买入方向的资产数量。示例：`10` +- **`from_asset`**（`string`）：卖出方向的 RGB 资产 ID。示例：`rgb:2dkSTbr-jFhznbPmo-TQafzswCN-av4gTsJjX-ttx6CNou5-M98k8Zd` +- **`to_asset`**（`string`）：买入方向的 RGB 资产 ID。示例：`rgb:2eVw8uw-8G88LQ2tQ-kexM12SoD-nCX8DmQrw-yLMu6JDfK-xx1SCfc` +- **`payment_hash`**（`string`）：与该交换关联的唯一支付哈希。示例：`7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664` +- **`status`**（`SwapStatus`）：该交换的当前状态。可能的取值： + - `Waiting` + - `Pending` + - `Succeeded` + - `Expired` + - `Failed` +- **`requested_at`**（`integer`）：交换被请求时的 Unix 时间戳。示例：`1691160765` +- **`initiated_at`**（`integer`）：交换被发起时的 Unix 时间戳。示例：`1691168512` +- **`expires_at`**（`integer`）：交换过期时的 Unix 时间戳。示例：`1691172703` +- **`completed_at`**（`integer`）：交换完成时的 Unix 时间戳。示例：`1691171075` + +### 补充说明 + +- `status` 字段实时反映交换的进展。 +- 请确保提供的 `payment_hash` 准确无误，才能取回正确的交换状态。 +- `access_token` 缺失或无效时统一返回 `404 Swap not found`，因此无法用该接口端点探测已存在的支付哈希。 +- 与时间相关的字段均为 Unix 时间戳格式。 +- `Swap` 对象中的 `SwapStatus` 字段可以是以下取值之一： + - **`Waiting`**：交换等待发起。 + - **`Pending`**：交换已发起，正在进行中。 + - **`Succeeded`**：交换已成功完成。 + - **`Expired`**：交换在要求的时间内未完成。 + - **`Failed`**：交换遇到错误，未能成功完成。 + +--- + +错误详情请参阅[错误处理](/cn/api-reference/error-handling)。 diff --git a/mintlify-docs/cn/api-reference/swap-protocol.mdx b/mintlify-docs/cn/api-reference/swap-protocol.mdx new file mode 100644 index 0000000..20745e1 --- /dev/null +++ b/mintlify-docs/cn/api-reference/swap-protocol.mdx @@ -0,0 +1,136 @@ +--- +title: "原子交换协议" +sidebarTitle: "交换协议" +description: "深入了解 KaleidoSwap 交换的底层机制：基于闪电网络的 HTLC 原子交换，附流程图与代码示例，帮助你完成集成。" +--- + +KaleidoSwap 通过客户端的 RGB Lightning Node 原子性地执行交换： + +| 模型 | 使用方 | 所需信任 | 结算方式 | +|-------|---------|----------------|------------| +| **原子交换** | 桌面应用、SDK、节点集成 | 无 —— 由密码学保证 | 闪电网络上的 HTLC | + +--- + +## 原子交换 + +桌面应用使用**哈希时间锁合约（HTLC）**在闪电网络上原子性地执行交换。双方同时锁定各自的资产 —— 要么整笔交换完成，要么双方都拿回自己的资金。不存在对手方风险。这与[闪电主网上首笔 RGB 资产交换](https://kaleidoswap.medium.com/%EF%B8%8F-the-first-ever-rgb-asset-swap-on-lightning-mainnet-1b940dcd0efd)背后的机制相同。 + +### 工作原理 + +1. 接单方通过 WebSocket 向做市方请求实时报价（每个 `quote_response` 都带有一个 `rfq_id`）。 +2. 接单方调用 `POST /api/v1/swaps/init` —— 做市方锁定汇率，并返回 `swapstring`、`payment_hash` 和 `access_token`。`access_token` 只返回一次 —— 请与 payment hash 一起保存，后续轮询交换状态时需要用到它。 +3. 接单方的 RGB Lightning Node 将该 `swapstring` 加入白名单（授权其通过该节点路由）。 +4. 接单方调用 `POST /api/v1/swaps/execute` —— 做市方发起 HTLC。 +5. 闪电网络路由该 HTLC：做市方揭示 preimage 以领取 BTC，同时将 RGB 资产释放给接单方。 +6. 如果任一方未能在 HTLC 超时前完成，双方资金都会自动退回。 +7. 接单方用第 2 步得到的 `payment_hash` **和** `access_token` 轮询 `POST /api/v1/swaps/atomic/status`。token 缺失或无效时统一返回 `404 Swap not found`。 + +### 时序图 + +``` +Taker Client Maker (RGB-LSP) Taker RLN Node + | | | + |──── WebSocket connect ──────────────>| | + |──── quote_request (BTC/USDT) ───────>| | + |<─── quote_response (price, rfq_id) ──| | + | | | + |──── POST /api/v1/swaps/init ────────>| | + | (rfq_id, from, to, amounts) | | + |<─── { swapstring, payment_hash, | | + | access_token } ─────────────── | | + | | | + |──── whitelist_swap(swapstring) ──────────────────────────────────────>| + |<─── swap whitelisted ─────────────────────────────────────────────── | + | | | + |──── POST /api/v1/swaps/execute ─────>| | + | (swapstring, taker_pubkey, | | + | payment_hash) | | + |<─── 200 OK ──────────────────────── | | + | ← HTLC resolves atomically on Lightning Network → | + | | | + |── POST /api/v1/swaps/atomic/status ─>| | + | (payment_hash, access_token) | | + |<─── { status: "Succeeded" } ─────── | | +``` + +### 使用到的接口端点 + +| 步骤 | 接口端点 | +|------|----------| +| 请求报价 | WebSocket `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | +| 锁定汇率 | `POST /api/v1/swaps/init` | +| 执行交换 | `POST /api/v1/swaps/execute` | +| 查询状态 | `POST /api/v1/swaps/atomic/status`（需要 init 返回的 `access_token`） | + +### WebSocket 环境 + +| 环境 | URL | +|-------------|-----| +| **Signet** | `wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` | +| **主网** | `wss://api.kaleidoswap.com/api/v1/market/ws/{client_id}` *（即将推出）* | + +请将 `{client_id}` 替换为你本次会话的唯一标识符。 + +### SDK 集成 + +SDK 会替你处理 WebSocket、init 和 execute 这几个步骤： + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', // 原子交换必需 +}); + +// 订阅实时报价流 +client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client'); + +const unsubscribe = await client.maker.streamQuotesByTicker( + 'BTC', 'USDT', 100000, + async (quote) => { + // 用最新报价中的 rfq_id 执行 init + execute + const result = await client.maker.initSwap({ + rfq_id: quote.rfq_id, + from_asset: 'BTC', + from_amount: quote.from_amount, + to_asset: 'USDT', + to_amount: quote.to_amount, + }); + // 在你的节点上加入白名单，然后执行…… + } +); +``` + +```python Python +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", # 原子交换必需 +) + +# 订阅实时报价流并发起交换 +client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/api/v1/market/ws/my-client") +# 完整的原子交换流程见 sdk/examples +``` + + +--- + + + + 原子交换 init 与 execute 的接口端点 + + + 报价与市场数据的接口端点 + + + 原子交换流程的端到端代码示例 + + + 处理交换失败与边界情况 + + diff --git a/mintlify-docs/cn/cli/channels-lsp.mdx b/mintlify-docs/cn/cli/channels-lsp.mdx new file mode 100644 index 0000000..bb3959b --- /dev/null +++ b/mintlify-docs/cn/cli/channels-lsp.mdx @@ -0,0 +1,110 @@ +--- +title: '通道与 LSP 流程' +description: '在 KaleidoCLI 中直接开通闪电通道，或使用 KaleidoSwap 闪电服务提供商（LSP）的通道订单流程获取入向流动性' +--- + +## 通道操作 + +`channel` 命令组用于直接管理本地节点上的闪电通道。 + +| 命令 | 用途 | +|--------|---------| +| `kaleido channel list` | 列出当前通道 | +| `kaleido channel open ` | 向某个对等节点开通通道 | +| `kaleido channel close ` | 关闭通道 | + +对等节点参数使用 `pubkey@host:port` 格式。 + +## 开通通道 + +```bash +kaleido channel open 03abc...@peer.host:9735 --capacity 100000 +``` + +值得关注的选项： + +- `--capacity` +- `--push-msat` +- `--asset-id` +- `--asset-amount` +- `--push-asset-amount` +- `--public` 或 `--private` +- `--with-anchors` +- `--fee-base-msat` +- `--fee-proportional-millionths` + +染色通道示例： + +```bash +kaleido channel open 03abc...@peer.host:9735 \ + --capacity 100000 \ + --asset-id rgb:abc... \ + --asset-amount 5000 +``` + +## LSP 通道订单 + +如果你希望使用 KaleidoSwap 的 LSP 流程，而不是手动开通对等通道，请使用 `channel order`。 + +### 子命令 + +| 命令 | 用途 | +|--------|---------| +| `kaleido channel order create ` | 创建通道订单 | +| `kaleido channel order get ` | 获取订单状态与详情 | +| `kaleido channel order pay ` | 用本地钱包资金支付订单 | +| `kaleido channel order decide ` | 提交费率决定 | +| `kaleido channel order estimate-fees` | 估算开通费用 | + +### 创建订单 + +```bash +kaleido channel order create 03abc... \ + --lsp-balance 1000000 \ + --client-balance 500000 +``` + +常用选项： + +- `--confirmations` +- `--funding-within` +- `--expiry-blocks` +- `--refund-address` +- `--announce` 或 `--private` +- `--asset-id` +- `--lsp-asset-amount` +- `--client-asset-amount` +- `--email` + +染色通道订单示例： + +```bash +kaleido channel order create 03abc... \ + --lsp-balance 1000000 \ + --client-balance 500000 \ + --asset-id rgb:xyz... \ + --lsp-asset-amount 5000 \ + --client-asset-amount 2000 +``` + +## LSP 元数据 + +`lsp` 子命令组用于查看服务端元数据和网络详情： + +| 命令 | 用途 | +|--------|---------| +| `kaleido channel lsp info` | 显示 LSP 信息和可用选项 | +| `kaleido channel lsp network-info` | 显示该 LSP 的网络元数据 | + +在创建订单之前，或者在设定客户端默认值时，这些命令很有用。 + +## 实用操作顺序 + +```bash +kaleido channel lsp info +kaleido node swap pubkey +kaleido channel order estimate-fees --lsp-balance 1000000 --client-balance 500000 +kaleido channel order create 03abc... --lsp-balance 1000000 --client-balance 500000 +``` + +服务端交易流程通常与通道和流动性管理同时进行，详见[市场与交换](/cn/cli/market-and-swaps)。 diff --git a/mintlify-docs/cn/cli/command-reference.mdx b/mintlify-docs/cn/cli/command-reference.mdx new file mode 100644 index 0000000..32ebf5f --- /dev/null +++ b/mintlify-docs/cn/cli/command-reference.mdx @@ -0,0 +1,206 @@ +--- +title: '命令参考' +description: 'KaleidoCLI 的完整命令地图，包含嵌套命令组和最重要的标志，涵盖节点、钱包、资产、通道、市场与交换操作' +--- + +## 根命令 + +```bash +kaleido [global options] [subcommand] [args] +``` + +### 全局选项 + +| 选项 | 含义 | +|-------|---------| +| `--json` | 输出原始 JSON | +| `--agent` | 关闭提示，适用于非交互式场景 | +| `--node-url` | 覆盖已配置的节点 URL | +| `--api-url` | 覆盖已配置的 API URL | +| `--install-completion` | 安装 shell 补全 | +| `--show-completion` | 打印 shell 补全内容 | + +## 顶层命令 + +| 命令 | 说明 | +|--------|---------| +| `setup` | 首次运行配置，并可选择创建本地节点 | +| `node` | 基于 Docker 的 RLN 环境生命周期与钱包访问 | +| `wallet` | BTC 钱包操作 | +| `asset` | RGB 资产管理与发行 | +| `channel` | 通道管理与 LSP 订单流程 | +| `peer` | 对等节点连通性 | +| `payment` | 闪电与 RGB+LN 支付 | +| `market` | 市场发现、报价和路由 | +| `swap` | 由做市商支撑的原子交换流程 | +| `config` | 已存储的 CLI 配置 | + +## `setup` + +| 命令 | 备注 | +|--------|-------| +| `kaleido setup` | 非交互式默认行为：以默认设置创建并启动一个本地 mutinynet 节点 | +| `kaleido setup signetcustom` | 在显式指定的网络上执行同样的流程（位置参数，默认为 `mutinynet`） | +| `kaleido setup mutinynet --env-name taker-1` | 自定义环境名称 | +| `kaleido setup --mode market --defaults` | 仅市场模式设置 | +| `kaleido setup --mode local --create-node --defaults` | 本地节点设置 | + +主要标志：`--mode`、`--defaults`、`--api-url`、`--node-url`、`--create-node`、`--spawn-dir`、`--env-name`、`--node-count`、`--start` + +## `node` + +| 命令 | 说明 | +|--------|---------| +| `kaleido node create [name]` | 创建命名环境 | +| `kaleido node list` | 列出环境及节点 URL | +| `kaleido node use [--node N]` | 选择当前活动节点 | +| `kaleido node up ` | 启动容器 | +| `kaleido node stop ` | 停止容器 | +| `kaleido node down ` | 移除容器和网络 | +| `kaleido node ps ` | 显示容器状态 | +| `kaleido node logs ` | 实时输出日志（`--no-follow` 打印已有日志后退出） | +| `kaleido node clean ` | 删除数据卷（`--yes` 跳过确认提示） | +| `kaleido node info` | 显示节点详情 | +| `kaleido node network` | 显示网络信息 | +| `kaleido node init` | 初始化钱包 | +| `kaleido node unlock` | 解锁钱包 | +| `kaleido node lock` | 锁定钱包 | +| `kaleido node shutdown` | 优雅关闭节点 | + +### `node swap` + +| 命令 | 说明 | +|--------|---------| +| `kaleido node swap pubkey` | 打印接单方公钥 | +| `kaleido node swap init` | 启动本地的做市方初始化交换流程（`--from-asset`、`--qty-from`、`--to-asset`、`--qty-to`、`--timeout`） | +| `kaleido node swap whitelist --swapstring ''` | 在接单方一侧将某个交换加入白名单 | +| `kaleido node swap execute` | 执行本地节点交换 | +| `kaleido node swap status ` | 查询本地节点交换状态（`--taker` 或 `--maker`） | +| `kaleido node swap list` | 列出节点已知的交换 | + +## `wallet` + +| 命令 | 说明 | +|--------|---------| +| `kaleido wallet address` | 新的 BTC 存入地址 | +| `kaleido wallet balance` | BTC 余额 | +| `kaleido wallet send
` | 发送 BTC | +| `kaleido wallet utxos` | 列出 UTXO | +| `kaleido wallet create-utxos` | 创建供 RGB 使用的 UTXO（`--up-to`、`--fee-rate`、`--skip-sync`） | +| `kaleido wallet transactions` | 交易历史 | +| `kaleido wallet backup ` | 备份钱包数据 | +| `kaleido wallet restore ` | 恢复钱包数据 | +| `kaleido wallet change-password` | 修改钱包密码 | +| `kaleido wallet estimate-fee` | 估算费率（`--blocks/-b`，默认 6） | + +## `asset` + +| 命令 | 说明 | +|--------|---------| +| `kaleido asset list` | 列出资产 | +| `kaleido asset balance ` | 资产余额 | +| `kaleido asset metadata ` | 资产元数据 | +| `kaleido asset invoice ` | 创建 RGB 发票 | +| `kaleido asset send ` | 发送 RGB 资产 | +| `kaleido asset send-batch` | 向多个接收方发送 | +| `kaleido asset transfers ` | 转账历史 | +| `kaleido asset refresh` | 刷新待处理的转账 | +| `kaleido asset sync` | 同步 RGB 钱包 | +| `kaleido asset fail-transfers` | 将待处理的转账标记为失败 | +| `kaleido asset media` | 获取资产媒体 | + +### `asset issue` + +| 命令 | 说明 | +|--------|---------| +| `kaleido asset issue nia` | 发行固定供应量的同质化资产 | +| `kaleido asset issue cfa` | 发行可收藏的同质化资产 | +| `kaleido asset issue uda` | 发行独一无二的数字资产 | + +所有 `issue` 子命令都接受 `--precision`，用于指定小数位数。 + +## `channel` + +| 命令 | 说明 | +|--------|---------| +| `kaleido channel list` | 列出通道 | +| `kaleido channel open ` | 开通通道 | +| `kaleido channel close ` | 关闭通道（需要 `--peer `） | + +### `channel order` + +| 命令 | 说明 | +|--------|---------| +| `kaleido channel order create [client-pubkey]` | 创建 LSP 通道订单（公钥默认为本地节点；`--yes` 直接接受获取到的询价价格） | +| `kaleido channel order get ` | 获取订单状态（`--access-token`） | +| `kaleido channel order pay ` | 支付通道订单（`--access-token`；非交互式使用时传入 `--onchain` 或 `--offchain`，以及 `--fee-rate` 和 `--yes`） | +| `kaleido channel order decide ` | 提交费率决定（`--accept` 或 `--reject`、`--access-token`） | +| `kaleido channel order estimate-fees` | 估算通道订单费用 | + +### `channel lsp` + +| 命令 | 说明 | +|--------|---------| +| `kaleido channel lsp info` | LSP 元数据与选项 | +| `kaleido channel lsp network-info` | LSP 网络信息 | + +## `peer` + +| 命令 | 说明 | +|--------|---------| +| `kaleido peer list` | 列出对等节点 | +| `kaleido peer connect ` | 连接到对等节点 | +| `kaleido peer disconnect ` | 断开与对等节点的连接 | + +## `payment` + +| 命令 | 说明 | +|--------|---------| +| `kaleido payment invoice` | 创建 BOLT11 或 RGB+LN 发票（`--expiry`，默认 3600） | +| `kaleido payment send ` | 支付发票 | +| `kaleido payment list` | 列出支付记录 | +| `kaleido payment status ` | 支付状态 | +| `kaleido payment decode ` | 解码发票 | +| `kaleido payment invoice-status ` | 发票状态 | +| `kaleido payment keysend ` | 无需发票的即时闪电支付（RGB 场景使用 `--asset-id`/`--asset-amount`） | + +## `market` + +| 命令 | 说明 | +|--------|---------| +| `kaleido market assets` | 列出资产 | +| `kaleido market pairs` | 列出交易对 | +| `kaleido market quote ` | 请求报价 | +| `kaleido market info` | 做市商节点信息 | +| `kaleido market routes ` | 可用路由 | + +## `swap` + +### `swap atomic` + +| 命令 | 说明 | +|--------|---------| +| `kaleido swap atomic init ` | 初始化原子交换 | +| `kaleido swap atomic execute` | 执行交换（`--swapstring`、`--taker-pubkey`、`--payment-hash`，省略时会提示输入；`--auto-whitelist` 会先在本地节点上加入白名单） | +| `kaleido swap atomic status ` | 原子交换状态 | +| `kaleido swap atomic run ` | 运行完整的原子交换流程 | + +## `config` + +| 命令 | 说明 | +|--------|---------| +| `kaleido config show` | 打印当前配置 | +| `kaleido config set ` | 更新单个配置键 | +| `kaleido config reset` | 将配置重置为默认值 | +| `kaleido config path` | 打印配置文件路径 | + +有效的配置键：`node-url`、`api-url`、`network`、`spawn-dir` + +## 机器可读模式 + +每个命令组都可以与 `--json` 组合使用： + +```bash +kaleido --json wallet balance +kaleido --json market quote BTC/USDT --from-amount 0.001 +``` diff --git a/mintlify-docs/cn/cli/getting-started.mdx b/mintlify-docs/cn/cli/getting-started.mdx new file mode 100644 index 0000000..73a22a4 --- /dev/null +++ b/mintlify-docs/cn/cli/getting-started.mdx @@ -0,0 +1,150 @@ +--- +title: "KaleidoCLI：快速开始" +sidebarTitle: "快速开始" +description: '安装 KaleidoCLI，完成首次运行设置，并配置默认的 API 与节点端点，几分钟内即可在终端使用比特币分层协议交易' +--- + +## 环境要求 + +- Python 3.10 或更高版本 +- 推荐使用 [`uv`](https://docs.astral.sh/uv/)，也可以使用 `pip` +- 使用 `node` 命令以及任何本地 RLN 工作流都需要 Docker 与 Docker Compose + +## 安装 + +### 使用 `uv` 全局安装 + +```bash +uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git +``` + +这种方式无需先克隆仓库即可安装 `kaleido` 可执行文件。 + +### 从本地代码副本安装 + +```bash +git clone https://github.com/kaleidoswap/kaleido-cli +cd kaleido-cli +make install +``` + +### 从代码副本引导安装 + +```bash +python install.py +``` + +## 首次运行设置 + +新用户请从这条命令开始： + +```bash +kaleido setup +``` + +不带参数的 `kaleido setup` 以非交互方式运行：它会立即以默认设置创建并启动一个本地 Docker mutinynet 节点，因此 Docker 必须处于运行状态。比特币网络是可选的位置参数（默认为 `mutinynet`）： + +```bash +kaleido setup signetcustom +kaleido setup mutinynet --env-name taker-1 +``` + +使用 `--mode` 可以显式选择配置档案： + +- `market`：保存用于市场数据和服务端交换流程的 API 设置 +- `local`：配置 API 设置，并可选择创建本地 Docker 节点环境 + +### 非交互示例 + +```bash +# 使用已保存的默认值完成仅市场模式设置 +kaleido setup --mode market --defaults + +# 使用默认值创建并启动本地节点环境 +kaleido setup --mode local --create-node --defaults +``` + +### 设置标志 + +| 标志 | 用途 | +|------|---------| +| `` (positional) | 本地节点使用的比特币网络，默认为 `mutinynet` | +| `--mode market\|local` | 选择设置档案 | +| `--defaults` | 使用已保存的值或默认值，不再弹出提示 | +| `--api-url` | 保存 KaleidoSwap API 基础 URL | +| `--node-url` | 直接保存节点 URL | +| `--create-node` | 在设置过程中创建 Docker 节点环境 | +| `--spawn-dir` | 设置命名环境的基础目录 | +| `--env-name` | 为设置过程中创建的环境命名 | +| `--node-count` | 要创建的节点数量 | +| `--start` | 环境创建完成后启动它 | + +## 配置 + +CLI 将配置存储在： + +```text +~/.kaleido/config.json +``` + +支持的键： + +- `api-url` +- `node-url` +- `network` +- `spawn-dir` + +命令示例： + +```bash +kaleido config show +kaleido config set api-url https://api.signet.kaleidoswap.com +kaleido config set network signet +kaleido config set spawn-dir ~/.kaleido +kaleido config path +``` + +## 快速上手 + +### 仅市场模式 + +```bash +kaleido setup --mode market --defaults +kaleido market pairs +kaleido market quote BTC/USDT --from-amount 0.001 +``` + +### 本地节点 + +```bash +kaleido setup --mode local --create-node --defaults +kaleido node init +kaleido node unlock +kaleido node info +kaleido wallet address +``` + +## Shell 补全 + +为当前 shell 安装补全： + +```bash +kaleido --install-completion +``` + +或者打印补全脚本以便手动安装： + +```bash +kaleido --show-completion +``` + +## 何时覆盖配置 + +已存储的配置适用于你的默认环境。需要时可以按命令覆盖： + +```bash +kaleido --api-url https://api.signet.kaleidoswap.com market pairs +kaleido --node-url http://localhost:3002 wallet balance +``` + +如果你需要管理多套本地 RLN 节点栈，请继续阅读[节点环境](/cn/cli/node-environments)。 diff --git a/mintlify-docs/cn/cli/introduction.mdx b/mintlify-docs/cn/cli/introduction.mdx new file mode 100644 index 0000000..ee35122 --- /dev/null +++ b/mintlify-docs/cn/cli/introduction.mdx @@ -0,0 +1,94 @@ +--- +title: "KaleidoCLI" +sidebarTitle: "概览" +description: '使用 KaleidoCLI 在终端管理本地多资产闪电节点，并跨比特币分层协议访问 KaleidoSwap 的市场数据与原子交换流程' +--- + +## CLI 覆盖的范围 + +`kaleido` 是命令行界面，服务于两类不同的工作流： + +- **本地 RGB Lightning Node 操作**：创建基于 Docker 的节点环境，初始化并解锁钱包，管理 BTC、RGB 资产、通道、对等节点和闪电支付。 +- **KaleidoSwap 市场与交换流程**：查看市场数据、请求报价、执行由做市商支撑的原子交换，以及驱动底层的本地节点交换步骤。 + +同一个二进制文件既支持交互式终端使用，也支持脚本化自动化。 + +## 为什么使用它 + + + + 在同一个设置流程中，选择仅市场模式或搭建本地节点环境。 + + + 让多套本地节点栈相互隔离，并用一条命令切换当前活动节点。 + + + 处理 BTC、RGB 资产、发票、转账、备份和闪电支付。 + + + 查询交易对与报价，并执行原子交换或本地节点交换流程。 + + + +## 全局标志 + +所有命令组都继承同一组根标志： + +| 标志 | 用途 | +|------|---------| +| `--json` | 返回原始 JSON，而不是富文本终端输出 | +| `--agent` | 关闭交互式提示，适用于脚本或代理驱动的场景 | +| `--node-url` | 为单条命令覆盖已配置的 RGB Lightning Node URL | +| `--api-url` | 为单条命令覆盖已配置的 KaleidoSwap API URL | +| `--install-completion` | 为当前 shell 安装补全 | +| `--show-completion` | 打印 shell 补全内容，供手动配置 | + +示例： + +```bash +kaleido --json market pairs +kaleido --node-url http://localhost:3001 wallet balance +kaleido --agent channel open 03ab...@host:9735 --capacity 100000 +``` + +## 环境变量 + +CLI 还会读取以下环境变量： + +| 变量 | 用途 | +|----------|-----| +| `KALEIDO_NODE_URL` | 默认的 RLN 节点 URL | +| `KALEIDO_API_URL` | 默认的 KaleidoSwap API URL | + +命令行标志的优先级高于环境变量和已存储的配置。 + +## 命令组 + +| 组 | 用途 | +|------|---------| +| `setup` | 首次运行设置，用于仅市场模式或本地节点模式 | +| `node` | 环境生命周期、钱包初始化、解锁以及接单方操作 | +| `wallet` | BTC 余额、地址、发送、UTXO、费用、备份和恢复 | +| `asset` | RGB 资产、发行、发票、发送、转账历史和同步 | +| `channel` | 闪电通道以及由 LSP 支撑的通道订购 | +| `peer` | 对等节点发现与连通性 | +| `payment` | 闪电发票、发送、keysend、解码和状态 | +| `market` | 资产、交易对、路由、报价和做市商信息 | +| `swap` | 由做市商支撑的原子交换流程（init、execute、status、run）；本地节点交换步骤位于 `node swap` 下 | +| `config` | 存储在 `~/.kaleido/config.json` 中的 CLI 配置 | + +## 输出模式 + +默认情况下，`kaleido` 会渲染便于阅读的表格和摘要。用于流水线和自动化时，建议使用 `--json`： + +```bash +kaleido --json market quote BTC/USDT --from-amount 0.001 +``` + +当命令应当在缺少输入时直接失败、而不是弹出提示时，请使用 `--agent`。 + +## 后续步骤 + +- 如果你是第一次安装 CLI，请从[快速开始](/cn/cli/getting-started)开始。 +- 如果你需要本地 RLN 节点栈，请参阅[节点环境](/cn/cli/node-environments)。 +- 完整的命令地图请查看[命令参考](/cn/cli/command-reference)。 diff --git a/mintlify-docs/cn/cli/market-and-swaps.mdx b/mintlify-docs/cn/cli/market-and-swaps.mdx new file mode 100644 index 0000000..db3834f --- /dev/null +++ b/mintlify-docs/cn/cli/market-and-swaps.mdx @@ -0,0 +1,101 @@ +--- +title: '市场与交换' +description: '在 CLI 中浏览 KaleidoSwap 市场、请求报价，并跨比特币分层协议执行订单、原子交换或本地节点交换流程' +--- + +## 市场数据 + +`market` 命令组是只读入口，用于查看交易对、报价、路由和做市商元数据。 + +| 命令 | 用途 | +|--------|---------| +| `kaleido market assets` | 列出可交易资产 | +| `kaleido market pairs` | 列出交易对 | +| `kaleido market quote ` | 请求报价 | +| `kaleido market info` | 显示做市商节点信息 | +| `kaleido market routes ` | 列出可用路由 | + +### 报价示例 + +```bash +kaleido market quote BTC/USDT --from-amount 0.001 +kaleido market quote BTC/USDT --to-amount 500 --from-layer BTC_LN --to-layer RGB_LN +``` + +重要的报价选项： + +- `--from-amount` 或 `--to-amount` +- `--from-layer` +- `--to-layer` + +市场报价支持的分层值包括 `BTC_LN`、`RGB_LN` 和 `BTC_ONCHAIN`。 + +## 交换的两种范围 + +交换功能分布在两个命令组中： + +| 范围 | 适用场景 | +|------|----------| +| `swap atomic` | 以本地节点作为接单方，执行由做市商支撑的原子交换 | +| `node swap` | 直接驱动底层的本地 RLN 交换步骤（位于 `node` 命令组下） | + +## 原子交换流程 + +当做市方在远端、而执行使用本地节点作为接单方时，请使用 `swap atomic`。 + +### 子命令 + +| 命令 | 用途 | +|--------|---------| +| `kaleido swap atomic init ` | 初始化原子交换 | +| `kaleido swap atomic execute` | 执行已初始化的交换（`--swapstring`、`--taker-pubkey`、`--payment-hash`，省略时会提示输入；`--auto-whitelist`） | +| `kaleido swap atomic status ` | 跟踪原子交换状态 | +| `kaleido swap atomic run ` | 用一条命令依次完成 init、whitelist 和 execute | + +### 示例 + +```bash +kaleido swap atomic run BTC/USDT --to-amount 5 +``` + +你还可以提供： + +- `--taker-pubkey` +- `--yes` +- 显式的 `--from-layer` 和 `--to-layer` + +## 本地节点交换流程 + +使用 `node swap` 执行底层的 RLN 交换步骤（这些命令位于 `node` 命令组下）： + +| 命令 | 用途 | +|--------|---------| +| `kaleido node swap pubkey` | 打印接单方公钥 | +| `kaleido node swap init` | 启动本地的做市方初始化交换流程（`--from-asset`、`--qty-from`、`--to-asset`、`--qty-to`、`--timeout`） | +| `kaleido node swap whitelist --swapstring ''` | 在接单方一侧将该交换加入白名单 | +| `kaleido node swap execute` | 加入白名单后执行交换 | +| `kaleido node swap status ` | 查看状态（`--taker` 或 `--maker`） | +| `kaleido node swap list` | 列出节点已知的交换 | + +当你希望把每个步骤单独暴露出来时，这条路径适合调试、演示和更底层的协议操作。 + +## 推荐的交易流程 + +### 浏览市场（无需节点） + +```bash +kaleido market pairs +kaleido market quote BTC/USDT --from-amount 0.001 +``` + +执行交换需要本地 RLN 节点——请使用下面的原子交换流程。 + +### 使用本地节点 + +```bash +kaleido node unlock +kaleido node swap pubkey +kaleido swap atomic run BTC/USDT --from-amount 0.001 --from-layer BTC_LN --to-layer RGB_LN +``` + +完整的命令地图请查看[命令参考](/cn/cli/command-reference)。 diff --git a/mintlify-docs/cn/cli/node-environments.mdx b/mintlify-docs/cn/cli/node-environments.mdx new file mode 100644 index 0000000..ae5ad51 --- /dev/null +++ b/mintlify-docs/cn/cli/node-environments.mdx @@ -0,0 +1,138 @@ +--- +title: '节点环境' +description: '用 KaleidoCLI 创建、运行、切换和维护命名的本地多资产闪电节点环境，为比特币分层协议开发与测试提供隔离的节点栈' +--- + +## 命名环境模型 + +`kaleido node` 管理存放在某个基础目录下的**命名 Docker Compose 环境**，该目录默认为： + +```text +~/.kaleido +``` + +每个环境都有自己的 compose 文件和数据卷，因此可以方便地为开发、测试或演示保留彼此独立的本地节点栈。 + +布局示例： + +```text +~/.kaleido/ +├── default/ +│ ├── docker-compose.yml +│ └── volumes/ +└── staging/ + ├── docker-compose.yml + └── volumes/ +``` + +## 创建环境 + +```bash +kaleido node create +kaleido node create staging +``` + +向导会依次询问： + +1. 基础目录 +2. 环境名称 +3. 节点数量 +4. 比特币网络 +5. 守护进程与对等节点的起始端口 +6. 是否立即启动该环境 + +## 生命周期命令 + +| 命令 | 用途 | +|--------|---------| +| `kaleido node list` | 显示所有环境及其节点 URL | +| `kaleido node use [--node N]` | 将当前的 `node-url` 指向某个环境中的某个节点 | +| `kaleido node up ` | 启动容器 | +| `kaleido node stop ` | 停止容器但不删除数据 | +| `kaleido node down ` | 停止并移除容器和网络 | +| `kaleido node ps ` | 显示容器状态 | +| `kaleido node logs ` | 实时输出日志 | +| `kaleido node clean ` | 删除环境的数据卷 | + +当只存在一个环境时，`up`、`stop`、`logs` 和 `clean` 等命令可以自动识别它。 + +## 切换当前活动节点 + +使用 `kaleido node use` 更新已配置的节点 URL： + +```bash +kaleido node use default +kaleido node use staging --node 2 +``` + +它是 Docker 管理的环境与所有依赖节点的命令（如 `wallet`、`asset`、`channel` 和 `payment`）之间的桥梁。 + +## 初始化与解锁 + +新环境启动后，对钱包执行一次初始化： + +```bash +kaleido node init +``` + +主要选项： + +- `--password` 直接传入钱包密码 +- `--mnemonic` 在初始化时用已有助记词恢复钱包 + +每次重启之后，都需要解锁钱包： + +```bash +kaleido node unlock +``` + +值得关注的解锁选项： + +- `--password` +- `--bitcoind-user` +- `--bitcoind-pass` +- `--bitcoind-host` +- `--bitcoind-port` +- `--indexer-url` +- `--proxy-endpoint` +- `--announce-alias` +- `--announce-address` + +默认情况下，该命令使用 CLI 提供的 KaleidoSwap signet 服务。 + +## 查看状态与上锁 + +```bash +kaleido node info +kaleido node lock +``` + +在运行钱包、通道或交换流程之前，用 `info` 确认节点可访问且配置正确。 + +## 节点交换操作 + +嵌套的 `swap` 命令组支持节点侧的原子交换与底层交换操作： + +```bash +kaleido node swap pubkey +kaleido node swap whitelist --swapstring '30/rgb:abc.../10/rgb:def.../...' +``` + +## 推荐的本地流程 + +```bash +kaleido node create devnet +kaleido node up devnet +kaleido node use devnet +kaleido node init +kaleido node unlock +kaleido node info +``` + +## 运维注意事项 + +- `clean` 不可撤销，因为它会移除底层数据卷。 +- `down` 会移除容器和网络，但保留数据卷。 +- `logs` 支持 `--service`，可将输出限定到单个容器。 + +继续阅读[钱包、资产与支付](/cn/cli/wallet-assets-payments)，了解针对已解锁节点运行的命令。 diff --git a/mintlify-docs/cn/cli/wallet-assets-payments.mdx b/mintlify-docs/cn/cli/wallet-assets-payments.mdx new file mode 100644 index 0000000..9e60a6f --- /dev/null +++ b/mintlify-docs/cn/cli/wallet-assets-payments.mdx @@ -0,0 +1,136 @@ +--- +title: '钱包、资产与支付' +description: '通过 KaleidoCLI 管理比特币、比特币二层资产、闪电发票和节点备份，在终端完成余额查询、资产发行与支付操作' +--- + +## 开始之前 + +以下命令组需要一个已启动并解锁的节点： + +```bash +kaleido node use default +kaleido node unlock +``` + +## BTC 钱包 + +### 常用钱包命令 + +| 命令 | 用途 | +|--------|---------| +| `kaleido wallet address` | 生成新的链上 BTC 存入地址 | +| `kaleido wallet balance` | 显示 BTC 余额 | +| `kaleido wallet send
` | 发送链上 BTC | +| `kaleido wallet utxos` | 列出 UTXO | +| `kaleido wallet create-utxos` | 为 RGB 操作创建染色 UTXO | +| `kaleido wallet transactions` | 列出链上交易 | +| `kaleido wallet estimate-fee` | 估算链上费率 | +| `kaleido wallet backup ` | 创建加密的钱包备份 | +| `kaleido wallet restore ` | 从备份压缩包恢复 | +| `kaleido wallet change-password` | 更换钱包密码 | +### 示例 + +```bash +kaleido wallet address +kaleido wallet balance +kaleido wallet send 50000 bc1q... +kaleido wallet create-utxos --num 10 --size 3000 +``` + +### 备份与恢复 + +```bash +kaleido wallet backup ~/kaleido-backup.zip +kaleido wallet restore ~/kaleido-backup.zip +``` + +这两条命令都接受 `--password`。恢复会覆盖当前的节点数据，请谨慎使用。 + +## RGB 资产 + +### 核心资产命令 + +| 命令 | 用途 | +|--------|---------| +| `kaleido asset list` | 列出节点持有的资产 | +| `kaleido asset balance ` | 显示单个资产的余额 | +| `kaleido asset metadata ` | 显示资产元数据 | +| `kaleido asset invoice ` | 创建 RGB 发票 | +| `kaleido asset send ` | 发送 RGB 资产 | +| `kaleido asset send-batch` | 在一笔交易中向多个 RGB 接收方发送 | +| `kaleido asset transfers ` | 查看转账历史 | +| `kaleido asset refresh` | 刷新待处理的转账 | +| `kaleido asset sync` | 同步 RGB 钱包 | +| `kaleido asset fail-transfers` | 将待处理的转账标记为失败 | +| `kaleido asset media` | 按文件摘要获取资产媒体字节 | + +### 发行新资产 + +`issue` 子命令组支持三种受支持的 schema： + +```bash +kaleido asset issue nia --name "MyToken" --ticker MTK --supply 21000000 +kaleido asset issue cfa --name "Art Piece" --supply 100 --file ./art.png +kaleido asset issue uda --ticker TKT1 --name "Ticket #1" --file ./ticket.png +``` + +用法： + +- `nia` 用于固定供应量的同质化资产 +- `cfa` 用于可收藏的同质化资产 +- `uda` 用于独一无二的数字资产 + +### 资产发票与发送示例 + +```bash +kaleido asset invoice rgb:abc123... --amount 500 --duration 3600 +kaleido asset send rgb:abc123... 100 rgb:invoice... +``` + +`asset send` 值得关注的选项： + +- `--fee-rate` +- `--min-confirmations` +- `--donation` +- `--transport-endpoint` +- `--skip-sync` + +## 闪电与 RGB+LN 支付 + +### 支付命令 + +| 命令 | 用途 | +|--------|---------| +| `kaleido payment invoice` | 创建 BOLT11 发票 | +| `kaleido payment send ` | 支付闪电发票 | +| `kaleido payment list` | 列出支付记录 | +| `kaleido payment status ` | 查看支付状态 | +| `kaleido payment decode ` | 解码闪电发票或 RGB 发票 | +| `kaleido payment invoice-status ` | 查询发票状态 | +| `kaleido payment keysend` | 发送无需发票的即时闪电支付 | + +### 示例 + +```bash +# BTC 发票 +kaleido payment invoice --amount-msat 10000 + +# RGB+LN 发票 +kaleido payment invoice --asset-id rgb:abc... --asset-amount 500 + +# 支付发票 +kaleido payment send lnbc... + +# 解码收到的发票 +kaleido payment decode rgb:... +``` + +支付零金额发票时，需要提供 `--amount-msat`。对于 RGB+LN 支付，需要提供 `--asset-id` 和 `--asset-amount`。 + +## 使用习惯 + +- 需要机器可读的响应时，使用 `--json`。 +- 只有在可以接受钱包或转账状态陈旧时，才使用 `--skip-sync`。 +- 在进行大量 RGB 操作之前先创建额外的 UTXO，以免可用的染色输出耗尽。 + +如果你要管理通道或订购入向流动性，请接着阅读[通道与 LSP 流程](/cn/cli/channels-lsp)。 diff --git a/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx b/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx new file mode 100644 index 0000000..fe77df1 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/channels/channel-backups.mdx @@ -0,0 +1,77 @@ +--- +title: 通道备份 +description: "在 KaleidoSwap 桌面应用中创建和恢复闪电通道备份，保护通道内的资金，并在更换设备或重装应用后完整还原节点状态" +--- + +备份通道非常重要：一旦设备损坏或需要重装应用，没有备份就可能造成资金损失。 + + + 如果没有最新的通道备份，你可能会失去锁定在已开通闪电通道中的资金。每次开通或关闭通道后，都请重新创建备份。 + + +## 通道备份包含哪些内容 + +备份是你的节点数据目录的完整加密归档。它记录了节点的全部状态——闪电通道数据、RGB 资产数据以及链上钱包状态——因此恢复后的节点会精确地从备份时的状态继续运行。 + +备份**不能**替代助记词。两者都要保管好： + +- **助记词** — 钱包密钥的根，请离线抄写保存 +- **备份文件** — 恢复通道和资产所需的节点状态 + +## 创建通道备份 + + + + 点击应用右上角的按钮打开下拉菜单，然后选择 **「设置」(Settings)**。 + + + + 在设置面板中点击 **「备份钱包」(Backup Wallet)**。 + + + + 选择一个安全的位置保存备份文件。请选一个日后能顺利访问的地方——最好是外置硬盘或加密的云存储。 + + + + 输入你的节点密码。备份文件会用这个密码加密。 + + + + 点击 **「创建备份」(Create Backup)**。加密后的备份文件会保存到你选择的位置。 + + + +桌面应用中的备份钱包界面 + +## 何时需要重新备份 + +出现以下任一情况后，请创建新的备份： + +- 开通了新通道 +- 关闭了某条通道 +- 从旧备份恢复之后 +- 按固定周期备份（例如每周一次） + +每个备份只反映创建那一刻的通道状态。过期的备份可能不包含你最新开通的通道。 + +## 从备份恢复 + +如果需要在新设备上恢复钱包： + +1. 重新安装 KaleidoSwap 桌面应用 +2. 在初始设置流程中选择 **「恢复钱包」(Restore Wallet)** +3. 选择你的备份文件，并输入创建备份时设置的节点密码 +4. 等待节点启动并完成同步 + +由于备份包含完整的节点状态，恢复后通道会照常继续运行——既不需要输入助记词，也不会触发强制关闭。 + + + 备份文件使用你的节点密码加密。没有这个密码，备份文件无法解密，也无法恢复。 + + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx b/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx new file mode 100644 index 0000000..3e2d691 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/channels/channel-requests.mdx @@ -0,0 +1,53 @@ +--- +title: 通道请求 +description: "在 KaleidoSwap 桌面应用中向闪电服务提供商申请入向通道，配置容量与时长，并随时跟踪每个通道请求的处理状态" +--- + +除了与其他节点[开通通道](./opening-channel)之外，你还可以向 LSP 申请入向通道，代价是让出节点所持流动性的一定比例。当你需要入向容量来接收支付时，这种方式很有用。 + +## 申请入向通道 + + + +### 进入通道页面 + +打开「通道」(Channels) 页面。该页面包含三个标签页：**「管理通道」(Manage Channels)**、**「开通通道」(Open Channel)** 和 **「购买通道」(Buy Channel)**。 + +### 打开购买通道标签页 + +选择 **「购买通道」(Buy Channel)** 标签页开始申请。这与[订购新通道](/cn/desktop-app/channels/order-new-channel)中介绍的 LSP 购买流程是同一套流程。 + +### 填写对等节点信息 + +输入你想申请通道的那个 LSP 的 URL。 + +### 分配资金 + +指定所需的通道参数： +- **通道容量** - 通道的总大小 +- **流动性分配** - 你希望在自己这一侧保留多少流动性 +- **时长** - 通道需要保持开启的时间 +- **RGB 资产**（可选）- 需要加入通道的 RGB 资产 + +### 核对详情并付款 + +确认所有信息无误，然后按 LSP 的要求完成付款。你可以通过闪电网络付款，也可以链上付款。 + + + +## 重要提示 + +- 提供入向流动性的费用由 LSP 决定 +- 通道容量和时长都会影响总成本 +- 通道开通过程中请保持节点在线 +- 付款确认后，等待 LSP 声明的区块链确认数（大约 6 个区块，在主网上约为一小时） + +--- + +*下一步：[通道备份](./channel-backups)* + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/channels/opening-channel.mdx b/mintlify-docs/cn/desktop-app/channels/opening-channel.mdx new file mode 100644 index 0000000..57139db --- /dev/null +++ b/mintlify-docs/cn/desktop-app/channels/opening-channel.mdx @@ -0,0 +1,52 @@ +--- +title: 开通闪电通道 +description: "在 KaleidoSwap 桌面应用中开通闪电通道：选择对等节点、设定通道容量，并可在开通时加入比特币分层协议资产，让同一条通道支持多资产交易" +--- + +KaleidoSwap 既支持单独使用闪电网络，也支持在闪电网络之上使用 RGB 资产。前者适用于常规的闪电网络操作，后者用于在闪电网络上操作 RGB 资产。 + +## 开通通道 + +以下流程用于在你的节点上开通一条闪电通道。如第 4 步所述，你可以选择在通道中加入 RGB 资产，也可以不加入。 + +1. 打开 **「通道」(Channels)** 页面，选择 **「开通通道」(Open Channel)** 标签页。 +2. **选择对等节点**：输入对等节点的节点 ID 或公钥，或直接从推荐节点中选择。 对等节点选择界面，包含节点 ID 输入框和推荐的闪电网络节点 +3. 指定分配给通道的比特币数量，这个数量就是通道的总容量。 通道容量设置界面，包含比特币金额输入框 +4. [可选] **添加 RGB 资产**，操作如下： + - 点击「添加资产」(Add Asset)。 + - 选择要加入通道的 RGB 资产。注意：只有你事先已经收到或发行过的资产，才能用来开通通道。如果你想加入的是钱包中尚未出现过的资产——首次使用的用户通常都是这种情况——更合适的做法是改为[购买通道](/cn/desktop-app/channels/order-new-channel)。 + - 设定每种资产分配到通道中的数量。 +如果你打算用这条通道交换一种或多种 RGB 资产，这一步是必需的。 在新建闪电通道中添加 RGB 资产 +5. 选择 **交易费率**(Transaction Fee Rate)，然后点击「下一步」(Next)。 +6. **仔细核对**所有信息： + - 比特币数量。 + - RGB 资产数量（如有）。 + - 对等节点信息。 +7. **开通通道**：点击「确认」(Confirm) 启动通道开通流程。 + +## 通道开通流程 + +新开通的通道要投入使用，整体流程如下： + +1. **确认**：应用会显示一个包含通道详情的确认界面。 +2. **资金交易**：资金交易会被广播到比特币网络。 +3. **等待期**：等待所需的确认数（大约 6 个区块，在主网上约为一小时）。 +4. **通道激活**：确认完成后，通道即可使用。 + +## 重要提示 + +- 最小通道容量：50,000 聪 +- 所需确认数：大约 6 个区块 +- 通道容量在开通后无法修改 +- 通道开通后无法再追加 RGB 资产——请在创建通道时一并加入 +- 开通过程中请保持节点在线 + +--- + +*下一步：[购买新通道](/cn/desktop-app/channels/order-new-channel)* + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/channels/order-new-channel.mdx b/mintlify-docs/cn/desktop-app/channels/order-new-channel.mdx new file mode 100644 index 0000000..cabdb14 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/channels/order-new-channel.mdx @@ -0,0 +1,141 @@ +--- +title: 订购新通道 +description: "在 KaleidoSwap 桌面应用中向 LSP 订购闪电通道：设置通道容量与流动性、选择比特币分层协议资产、完成付款并等待通道交付" +--- + +本指南介绍如何从 KaleidoSwap 的闪电服务提供商（LSP）购买一条带有出向流动性的闪电网络通道。对于想要快速开始交易新资产的用户，这种方式尤其实用。 + +## 概览 + +通过 LSP 开通通道大致分为四步： +1. 连接 LSP。 +2. 配置通道订单。 +3. 完成付款。 +4. 开通通道。 + +## 第 1 步：连接 LSP + +首先，进入「通道」(Channels) 页面的 **「购买通道」(Buy Channel)** 标签页，然后连接到一个 LSP： +1. 输入 LSP 的 URL，或直接选择默认的 KaleidoSwap LSP。 +2. 界面会显示 LSP 的连接串。 +3. 确认连接后继续。 +在桌面应用中连接闪电服务提供商 + + +## 第 2 步：配置通道订单 + +1. 设定**通道容量**（以聪为单位），也就是通道的总大小（最小 50,000 聪，最大 16,777,215 聪）。 +2. 选择你要购买的**出向流动性**。这是 LSP 为你的通道投入的数量，剩余容量则成为你的入向流动性。例如：一条 100 万聪的通道，出向流动性为 70 万聪，那么入向容量就是 30 万聪。 +3. 选择 LSP 需要保证通道保持开启的时长（**通道时长**），可选项如下： +- 1 个月（4,320 个区块） +- 3 个月（12,960 个区块） +- 6 个月（25,920 个区块） +LSP 通道订单表单及容量选项 + +4. [可选] 启用「添加资产」(Add Asset) 选项并选择所需资产，即可在通道中请求 RGB 资产。随后你需要指定希望 LSP 投入的资产数量。注意：目前 RGB 资产只能由 LSP 一方提供。 + +通道订单表单中的 RGB 资产选择 + +## 第 3 步：完成付款 + +要继续开通通道，你需要完成付款。付款内容包括： +- 你的出向流动性，也就是开通后可以立即使用的资金。 +- LSP 服务费用，各家提供商的收费标准不同。下面列出默认 KaleidoSwap LSP 的费用结构。 + +### KaleidoSwap LSP 费用结构 +使用 KaleidoSwap LSP 时： +- 开通费：1,000 聪（每条通道一次性收取） +- 容量费：通道总容量的 1% +- 时长费：按保证的通道存续时间，每个区块 1 聪 +- 总费用设有上下限：最低 2,000 聪，最高 100,000 聪 +- 计算示例： + ``` + 一条 100 万聪的通道，锁定 1 个月（4,320 个区块）： + - 开通费：1,000 聪。 + - 容量费：10,000 聪（100 万的 1%）。 + - 时长费：4,320 聪（1 聪 × 4,320 个区块）。 + - 总费用：15,320 聪。 + ``` + +你可以选择链上或通过闪电网络付款，资金既可以来自 KaleidoSwap 钱包中已有的余额，也可以来自其他钱包。 + +### 闪电网络付款 +- 扫描二维码或复制闪电发票。 +- 使用外部闪电钱包付款，或勾选「使用钱包资金支付」(Pay with wallet funds) 复选框，用 KaleidoSwap 钱包中的余额付款（如余额充足）。 +- 付款金额包含： + - 通道容量。 + - LSP 费用（基础费用 + 时间锁费用）。 + - 网络费用。 + +### 链上付款 +- 向界面提供的地址转入比特币，可使用外部钱包，也可勾选「使用钱包资金支付」(Pay with wallet funds) 复选框，用 KaleidoSwap 钱包中的余额付款（如余额充足）。 +- 请按界面显示的金额精确转账。 +- 等待区块链确认。 +通道订单付款界面及闪电发票 + +## 第 4 步：开通通道 + +付款确认后： +1. LSP 开始开通通道。 +2. 等待 LSP 声明的区块链确认数（大约 6 个区块，在主网上约为一小时）。 +3. 通道随即激活，并具备你所指定的： + - 总容量。 + - 出向流动性。 + - RGB 资产（如已申请）。 + - 锁定期。 + +## 订单状态 + +通道订单可能处于以下状态： +- `CREATED`：订单已被 LSP 接受，等待付款和通道开通。 +- `COMPLETED`：通道已成功开通。 +- `FAILED`：处理过程中出现错误。 + +订单处于 `CREATED` 状态时，其付款会经历以下子状态： +- `EXPECT_PAYMENT`：等待你付款。 +- `HOLD`：已收到闪电付款，并在通道开通期间暂时挂起。 +- `PAID`：付款已结算。 +- `TIMEOUT` / `EXPIRED`：未在规定时间内收到付款，订单已失效。 + +## 退款政策 + +如果付款后通道开通失败： +1. 记下界面上显示的 `order_id`。 +2. 携带订单 ID 联系支持团队。 +3. 如被要求，请提供付款凭证。 +4. 核实后即会处理退款。 + +## 最佳实践 + +1. **容量规划** + - 计算你需要的出向 / 入向流动性比例。 + - 考虑未来对 RGB 资产的需求。 + - 把费用纳入预算。 + +2. **下单过程中** + - 付款期间保持应用处于打开状态。 + - 保存好订单 ID。 + - 等待全部所需确认完成。 + +3. **开通之后** + - 核对通道参数。 + - 先用小额交易测试。 + - 关注通道状态。 + +## 支持 + +如需帮助： +1. 查阅[常见问题](/cn/desktop-app/support/faq) +2. 加入我们的 [Telegram 群组](https://t.me/kaleidoswap) +3. 在 [GitHub](https://github.com/kaleidoswap/desktop-app) 上提交 issue + + +--- + +*下一步：[资产交换](/cn/desktop-app/trading/asset-swaps)* + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/getting-started/installation.mdx b/mintlify-docs/cn/desktop-app/getting-started/installation.mdx new file mode 100644 index 0000000..88ed892 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/getting-started/installation.mdx @@ -0,0 +1,93 @@ +--- +title: "KaleidoSwap 桌面应用：安装" +sidebarTitle: "安装" +description: "在 macOS、Windows 或 Linux 上安装 KaleidoSwap 桌面应用：下载地址、系统要求、校验二进制文件与节点配置，逐步说明每个环节。" +--- + +## 安装方式 + +安装 KaleidoSwap 桌面应用有两种方式： + +### 1. 下载二进制文件 + +1. **下载**：从 [KaleidoSwap 下载页面](https://kaleidoswap.com/downloads) 或 GitHub [Releases](https://github.com/kaleidoswap/desktop-app/releases) 页面获取最新构建，选择与你操作系统匹配的二进制文件。 +2. **校验**：安装前，用经 GPG 签名的 SHA256 校验和清单核对下载文件。详细步骤见[二进制文件校验指南](/cn/desktop-app/getting-started/verify-binaries)。 +3. **安装**：执行该二进制文件即可运行应用。 + +### 2. 本地构建 + +#### 通用前置条件 + +- **Tauri 2.x** + 确认已安装全部[官方 Tauri 前置依赖](https://v2.tauri.app/start/prerequisites/)（Rust、Node.js、pnpm）。 +- **代码仓库** + ```sh + git clone https://github.com/kaleidoswap/desktop-app + cd desktop-app + ``` + +#### 各平台专用说明 + +**Windows：** +- RGB Lightning Node 集成在 Windows 上尚未完全原生支持。要在 Windows 上使用 RLN，请在 Docker 容器中运行并远程连接 —— 参见[节点托管](/cn/desktop-app/getting-started/node-hosting)，其他远程节点方案见[故障排查](/cn/desktop-app/support/troubleshooting#connectivity) +- 安装 [vcpkg](https://github.com/microsoft/vcpkg)，用它安装 **openssl**、**sqlite3** 等库 +- 确认已安装 **Microsoft Visual C++**（通过 Visual Studio 或 Build Tools） + +**Linux：** +- 安装 `build-essential` 和 `pkg-config` +- 安装 CI 构建所用的 WebKitGTK / GTK 依赖：`libwebkit2gtk-4.1-dev`、`libwebkit2gtk-4.0-dev`、`libgtk-3-dev`、`libglib2.0-dev`、`librsvg2-dev`、`libappindicator3-dev` 和 `patchelf` +- 确认 Rust、Node.js 和 pnpm 均已正确安装 + +#### 构建与运行 + +1. **安装依赖**： + ```sh + pnpm install + ``` +2. **构建 Tauri 应用**： + ```sh + pnpm tauri build + ``` +3. **以开发模式运行 KaleidoSwap**： + ```sh + pnpm tauri dev + ``` + +## 节点配置选项 + +安装 KaleidoSwap 之后，你需要连接到一个 RGB Lightning Node。有两种选择： + +### 方案 1：连接远程节点 + +如果你不想在本机运行节点，可以连接到远程 RGB Lightning Node： + +- **自托管远程节点**：按照 [RGB Lightning Node 托管](/cn/desktop-app/getting-started/node-hosting)指南，在 VPS 或服务器上搭建自己的 RGB Lightning Node。 +- **托管服务商**：连接由 ThunderStack 等服务商专业运维的节点。 + +**远程节点的优势：** +- 不占用本地资源 +- 7×24 可用（托管方案） +- 配置流程更简单 + +### 方案 2：创建带集成节点的本地钱包 + +如果追求完全的控制权和隐私，可以直接在本机运行节点： + +- 按照[创建新钱包](/cn/desktop-app/wallet/creating-wallet)指南，创建一个带集成 RGB Lightning Node 的本地钱包。 + +**本地节点的优势：** +- 完全掌控自己的节点 +- 更强的隐私性 +- 不依赖外部服务 + + + 本地节点集成在 **Windows** 上尚未完全原生支持。Windows 用户应选择上面的方案 1（远程节点：通过 [Docker](/cn/desktop-app/getting-started/node-hosting) 自托管，或使用 ThunderStack 等托管服务商）—— 详见[故障排查](/cn/desktop-app/support/troubleshooting#connectivity)。 + + +在继续 KaleidoSwap 的配置之前，请先选择最符合你技术水平和需求的方案。 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/getting-started/introduction.mdx b/mintlify-docs/cn/desktop-app/getting-started/introduction.mdx new file mode 100644 index 0000000..dfa5e37 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/getting-started/introduction.mdx @@ -0,0 +1,67 @@ +--- +title: "KaleidoSwap 桌面应用" +sidebarTitle: "概览" +description: "KaleidoSwap 桌面应用是一款非托管钱包，内置原子交换，让你在闪电网络上管理比特币与比特币二层资产，并完全掌控自己的节点、通道和密钥。" +--- + +KaleidoSwap 桌面应用是一款功能完整的客户端，用于在闪电网络上交易比特币和 RGB 资产。它让你完全掌控自己的节点、钱包和通道。 + +## 你可以做什么 + + + + 在本地运行 RGB Lightning Node，或连接到远程节点 —— 基础设施完全自主掌控 + + + 创建钱包、生成助记词，并管理 BTC 与 RGB 资产余额 + + + 开通带或不带 RGB 资产的闪电通道，或通过 LSP 订购通道 + + + 直接从你的节点执行 BTC 与 RGB 资产之间的原子交换 + + + +## 桌面应用覆盖的范围 + +| 领域 | 桌面应用为你提供什么 | +|------|-------------------------------| +| **节点控制** | 在本机运行 RGB Lightning Node，或让应用指向你自己托管的远程节点 | +| **钱包** | 创建并解锁账户、生成或恢复助记词、持有 BTC 与 RGB 余额 | +| **通道** | 直接与对等节点开通通道，或向 LSP 订购一条预先分配 RGB 资产的通道 | +| **交易** | 从自己的节点发起询价，并结算 BTC 与 RGB 资产之间的原子交换 | +| **备份** | 导出通道备份，数据丢失后通道资金仍可恢复 | +| **设置** | 按账户配置节点接口端点、RGB proxy 和网络 | + +## 工作原理 + +桌面应用是客户端，不是托管方。它驱动一个 **RGB Lightning Node**，由该节点保管你的密钥、维护通道状态并在本地验证 RGB 合约。 + +- **应用**是界面层：账户、余额、通道和交易界面 +- **RGB Lightning Node** 保管密钥和通道状态，无论它运行在你的本机还是你控制的服务器上 +- **LSP** 提供入向流动性，并作为交换中锁定另一条腿的交易对手 +- **比特币**是通道的锚定层，也是仓位最终结算的地方 + +任何第三方在任何环节都无法接触你的资金。想了解它在整体架构中的位置，参见[架构](/cn/whats-kaleidoswap/architecture#client-architecture)。 + +## 日常流程 + +1. **解锁** —— 输入密码；应用启动节点或重新连接到节点 +2. **查看余额** —— 所选账户的链上 BTC、闪电余额和 RGB 资产 +3. **调动资金** —— 存入、提取或开通通道 +4. **交易** —— 为交易对获取报价，并与做市方结算原子交换 + +## 系统要求 + +- **macOS** 12+（Apple Silicon 与 Intel） +- **Windows** 10+（64 位） +- **Linux**（Ubuntu 22.04+、Debian 12+，或其他带 `webkit2gtk-4.1` 的等效发行版） + +如需从源码构建，还需要 Rust、Node.js 和 Tauri 的前置依赖。 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/getting-started/node-hosting.mdx b/mintlify-docs/cn/desktop-app/getting-started/node-hosting.mdx new file mode 100644 index 0000000..ffe427d --- /dev/null +++ b/mintlify-docs/cn/desktop-app/getting-started/node-hosting.mdx @@ -0,0 +1,341 @@ +--- +title: "自托管多资产闪电节点" +sidebarTitle: "节点托管" +description: "为 KaleidoSwap 自托管多资产闪电节点：Docker 部署、VPS 直装、防火墙配置，以及从桌面应用远程连接节点的完整步骤。" +--- + +本指南介绍如何自行托管 RGB Lightning Node 供 KaleidoSwap 使用。自托管让你完全掌控自己的节点，对熟悉服务器运维的用户来说是很好的选择。 + +## 概览 + +RGB Lightning Node（RLN）是一种专用的闪电网络节点，支持在闪电网络上使用 RGB 资产。它让你可以： + +- 创建包含 RGB 资产的支付通道 +- 跨多条通道路由以 RGB 资产计价的支付 +- 以与普通比特币闪电支付相同的体验和安全性转移 RGB 资产 + +## 托管方式对比 + +托管 RGB Lightning Node 有几种方式，各有优势和要求： + +| 托管方式 | 优势 | 注意事项 | 技术门槛 | +|----------------|------------|----------------|---------------------| +| **Docker** | 部署简单、环境隔离、升级方便 | 需要了解 Docker | 中 | +| **直接安装** | 完全掌控、没有容器化开销 | 需手动配置依赖、防火墙等 | 高 | +| **托管服务商** | 无需技术配置、有专业支持 | 控制权较少、需订阅付费 | 低 | + +选择最符合你技术水平和需求的方式： + +- **基于 Docker 安装**：适合大多数用户 —— 部署简单，可选择运行完整基础设施或仅运行节点。 +- **在 VPS 上直接安装**：适合需要完全掌控系统配置的高级用户。 +- **托管方案（ThunderStack）**：适合希望以最小技术投入获得专业运维方案的用户。 + +## 网络选项 + +无论采用哪种托管方式，你都可以让节点运行在不同的比特币网络上： + +| 网络 | 说明 | 适用场景 | +|---------|-------------|----------| +| **signet（Mutinynet）** | 自定义 signet，出块时间 30 秒 | 测试和开发的理想选择 | +| **测试网** | 比特币全球测试网 | 在更大范围的网络中测试 | +| **regtest** | 本地测试网络 | 开发与隔离测试 | +| **主网** | 比特币生产网络 | 生产使用（即将支持） | + +使用我们的 Docker 方案，你可以轻松为上述任一网络运行自己的 Bitcoin Core 和 Electrs 实例，从而完全掌控自己的技术栈。 + +## 信任考量 + +你选择自行运行哪些基础设施组件、又连接哪些外部服务，直接决定了所需的信任程度： + +- **零信任配置**：自行运行 Bitcoin Core、Electrs、RGB Proxy 和 RGB Lightning Node +- **最小信任配置**：只运行 RGB Lightning Node，其他服务连接托管实例 + +## 方案 1：基于 Docker 安装 + +我们的 Docker 方案是运行 RGB Lightning Node 最简单的途径。你可以运行完整技术栈，也可以只运行节点组件。 + +### 前置条件 + +- 已安装 Docker 和 Docker Compose +- 至少 4GB 内存和 50GB 存储 +- 具备基本的终端命令知识 + +### 用 Makefile 快速开始 + +最简单的上手方式是使用仓库内置的 Makefile： + +1. 克隆仓库： + +```bash +git clone https://github.com/kaleidoswap/docker-images.git +cd docker-images +``` + +2. 选择运行方式： + +```bash +# 查看所有可用命令 +make help + +# 仅运行 RGB Lightning Node（随后连接外部服务） +make node-only + +# 运行完整技术栈（所有组件运行在 signet 上） +make full + +# 查看所有服务的日志 +make logs +``` + +关于各命令和选项的更多信息，请查看 [README.md 文件](https://github.com/kaleidoswap/docker-images/blob/main/README.md)。 + +## 方案 2：在 VPS 上直接安装 + +如果你是希望完全掌控服务器环境的高级用户，可以把 RGB Lightning Node 直接安装在 VPS 或裸金属服务器上。 + +### 前置条件 + +- 一台运行 Linux 的 VPS 或服务器（推荐 Ubuntu/Debian） +- Rust 开发环境 +- 正确配置的防火墙（开放 3001 端口用于 API，9735 端口用于闪电网络） +- 足够存放区块链数据的存储空间 + +### 安装 + +1. 克隆仓库： + +```bash +git clone https://github.com/RGB-Tools/rgb-lightning-node --recurse-submodules --shallow-submodules +cd rgb-lightning-node +``` + +2. 安装二进制文件： + +```bash +cargo install --locked --path . +``` + +3. 启动节点： + +```bash +rgb-lightning-node / --daemon-listening-port 3001 \ +--disable-authentication \ +--ldk-peer-listening-port 9735 \ +--network +``` + +替换： +- `` 换成你选定的数据目录 +- `` 换成 `regtest`、`testnet` 或 `signet`（用于 Mutinynet） + +4. 解锁节点时，你需要提供： + +- Bitcoin RPC 连接信息 +- 索引器 URL +- RGB proxy 接口端点 + +### VPS 防火墙配置 +在 VPS 上运行时，你需要配置防火墙以放行必要的连接 + +```bash +# 放行 SSH +ufw allow ssh + +# 放行 RGB Lightning Node API +ufw allow 3001/tcp + +# 放行闪电网络 P2P 连接 +ufw allow 9735/tcp + +# 启用防火墙 +ufw enable +``` + +### 作为系统服务运行 + +生产环境建议创建一个 systemd 服务： + +```bash +sudo nano /etc/systemd/system/rgb-lightning-node.service +``` + +填入以下内容： + +``` +[Unit] +Description=RGB Lightning Node +After=network.target + +[Service] +User=YOUR_USERNAME +WorkingDirectory=/home/YOUR_USERNAME +ExecStart=/home/YOUR_USERNAME/.cargo/bin/rgb-lightning-node /home/YOUR_USERNAME/rgbln-data/ --daemon-listening-port 3001 --ldk-peer-listening-port 9735 --network signet +Restart=on-failure +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +启用并启动服务： + +```bash +sudo systemctl enable rgb-lightning-node +sudo systemctl start rgb-lightning-node +``` + +## 方案 3：托管服务商（ThunderStack） {#option-3-hosted-provider-thunderstack} + +如果你想要专业运维的方案，又不愿承担自托管的技术负担，[ThunderStack](https://thunderstack.org/product) 提供基于云的 RGB Lightning Node 托管服务。 + +### ThunderStack 是什么？ + +ThunderStack 是一套基于云的方案，为 RGB 和闪电网络应用提供顺畅的节点管理。它带来高可用性、更强的安全性和便捷的管理，同时免去自托管的技术负担。 + +### 主要特性 + +- **7×24 可用**：始终在线的基础设施保障业务不中断 +- **免维护**：把节点运维的复杂性交给 ThunderStack +- **可扩展**：随需求变化按需增减节点 +- **安全**：采用 mTLS、Cognito 等先进安全协议做访问控制 +- **易于集成**：支持 API、Webhook 和 SDK，便于集成 + +### ThunderStack 与自托管对比 + +| 维度 | ThunderStack | 自托管 | +|--------|-------------|--------------| +| 技术门槛 | 极低 | 中到高 | +| 部署耗时 | 几分钟 | 数小时到数天 | +| 维护 | 由 ThunderStack 负责 | 由用户负责 | +| 控制权 | 仅限 API 范围 | 完全掌控 | +| 成本 | 订阅制 | 基础设施开销 | +| 在线率 | 专业 SLA 保障 | 取决于你的部署 | + +如果你更看重便捷、可靠和专业支持，选择 ThunderStack；如果你更看重完全掌控、可定制和尽量少的第三方信任，选择自托管。 + +## 网络环境 + +### 不同网络的连接信息 + +#### regtest 环境 + +在 regtest 上测试时，可以使用以下连接信息： + +```json +{ + "password": "", + "bitcoind_rpc_username": "user", + "bitcoind_rpc_password": "password", + "bitcoind_rpc_host": "regtest-bitcoind.rgbtools.org", + "bitcoind_rpc_port": 80, + "indexer_url": "electrum.rgbtools.org:50041", + "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc" +} +``` + +#### 测试网环境 + +在 testnet3 上测试时，可以使用： + +```json +{ + "password": "", + "bitcoind_rpc_username": "user", + "bitcoind_rpc_password": "password", + "bitcoind_rpc_host": "electrum.iriswallet.com", + "bitcoind_rpc_port": 18332, + "indexer_url": "ssl://electrum.iriswallet.com:50013", + "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc" +} +``` + +#### signet（Mutinynet）环境 + +在 signet 上测试时，可以使用： + +```json +{ + "password": "", + "bitcoind_rpc_username": "user", + "bitcoind_rpc_password": "default_password", + "bitcoind_rpc_host": "bitcoind.signet.kaleidoswap.com", + "bitcoind_rpc_port": 38332, + "indexer_url": "https://esplora.signet.kaleidoswap.com", + "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc" +} +``` + +## Mutinynet：专为测试打造的自定义比特币 signet + +[Mutinynet](https://github.com/MutinyWallet/mutiny-net) 是一个自定义的比特币 signet 网络，专为测试闪电网络应用而设计。它提供： + +- 极快的出块速度（每块 30 秒，主网为 10 分钟） +- 稳定的测试网环境，无需争抢区块空间 +- 预先配置好，与 RGB Lightning Node 兼容 +- 非常适合在闪电网络上测试 RGB 资产 + +**Mutinynet 相关资源：** + +- [Mutinynet 浏览器与内存池](https://mutinynet.com/) - 查看区块、交易和内存池 +- [Mutinynet 水龙头](https://faucet.mutinynet.com/) - 获取免费测试币用于开发 +- [Mutinynet GitHub 仓库](https://github.com/MutinyWallet/mutiny-net) - 技术文档和源码 + +## 节点操作 + +节点运行起来之后，可以通过 REST API 操作。 + +### API 概览 + +节点提供一套完整的 API 来管理你的节点： + +- 通道管理：开通/关闭通道，连接/断开对等节点 +- 资产操作：发行、发送和管理 RGB 资产 +- 支付处理：创建/支付发票、keysend 等 +- 节点信息与控制 + +详细的 API 文档见 [OpenAPI 规范](https://rgb-tools.github.io/rgb-lightning-node)。 + +### 基本操作 + +以下是一些常见操作： + +#### 获取比特币地址 +```bash +curl -X POST http://localhost:3001/address +``` + +#### 获取节点信息 +```bash +curl http://localhost:3001/nodeinfo +``` + +#### 查询比特币余额 +```bash +curl -X POST -H "Content-type: application/json" \ + -d '{}' http://localhost:3001/btcbalance +``` + +## 硬件要求 + +为获得最佳性能： + +| 环境 | CPU | 内存 | 存储 | 网络 | +|-------------|-----|-----|---------|---------| +| 测试（Mutinynet） | 2 核 | 4GB | 25GB | 10Mbps | +| 测试网 | 2 核 | 4GB | 50GB | 10Mbps | +| 生产 | 4 核以上 | 8GB 以上 | 500GB 以上 SSD | 100Mbps 以上 | + +## 安全考量 + +自托管节点时请注意： + +1. **防火墙配置**：只暴露必要端口（3001 用于 API，9735 用于闪电网络对等连接） +2. **认证**：使用强密码，并考虑增加 API 认证 +3. **备份**：定期备份节点的数据目录 +4. **更新**：保持所有组件更新，及时修补安全漏洞 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/getting-started/setup.mdx b/mintlify-docs/cn/desktop-app/getting-started/setup.mdx new file mode 100644 index 0000000..db885e0 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/getting-started/setup.mdx @@ -0,0 +1,75 @@ +--- +title: "KaleidoSwap 桌面应用：快速上手" +sidebarTitle: "快速上手" +description: "从零开始配置 KaleidoSwap 桌面应用，按顺序完成安装、连接节点、创建钱包、充值和第一笔原子交换，并了解动手前需要准备什么。" +--- + +这是从全新安装到完成第一笔交换的完整路径。每一步都链接到详细的指南，因此这里不重复那些指南已经讲清的内容。 + +## 开始之前 + +要在桌面应用上交易，你需要准备： + +| 前提条件 | 说明 | +|-------------|---------| +| **比特币** | 建议至少约 100 万聪（0.01 BTC），用于为通道注资并覆盖费用 | +| **LSP 连接** | 一个用于开通通道的闪电服务提供商（默认 LSP 已预先配置） | +| **RGB 资产** | 在开通通道时分配到通道内，或通过交换获得 | + +如果你只想先体验应用而不打算交易，可以先安装并创建钱包，不必存入任何资金。 + + + 网络在账户创建时即固定，之后无法更改，因此请为每个网络分别创建账户。目前可选 regtest、signet、Mutinynet 和测试网；主网暂不可用。 + + +## 配置路径 + + + + 下载适用于你平台的已签名二进制文件，或从源码构建。运行前先校验 GPG 签名。 + + [安装](/cn/desktop-app/getting-started/installation) · [校验二进制文件下载](/cn/desktop-app/getting-started/verify-binaries) + + + + 应用需要一个 RGB Lightning Node。想要完全掌控就在本地运行，也可以部署在服务器上通过网络连接。你可以现在就做决定，或者让账户创建流程为你启动一个本地节点。 + + [节点托管](/cn/desktop-app/getting-started/node-hosting) + + + + 为账户命名、选择网络并生成钱包。把助记词离线保存好 —— 它是找回资金的唯一途径。 + + [创建新钱包](/cn/desktop-app/wallet/creating-wallet) · [初始化助记词](/cn/desktop-app/wallet/initializing-mnemonic) + + + + 解锁会启动节点并将其同步到链上。首次同步耗时最长。 + + [解锁钱包](/cn/desktop-app/wallet/unlocking-wallet) + + + + 在链上存入 BTC。要接收 RGB 资产，你还需要一个染色 UTXO，应用可以在存入过程中为你创建。 + + [存入](/cn/desktop-app/wallet/deposits) + + + + 交易通过闪电网络进行，因此你需要一条有流动性的通道。可以直接与对等节点开通，也可以从 LSP 购买一条已在内部分配好 RGB 资产的通道。 + + [开通通道](/cn/desktop-app/channels/opening-channel) · [订购新通道](/cn/desktop-app/channels/order-new-channel) + + + + 为某个交易对获取报价，并以原子交换的方式结算。两条腿要么同时完成，要么都不发生。 + + [资产交换](/cn/desktop-app/trading/asset-swaps) + + + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/getting-started/verify-binaries.mdx b/mintlify-docs/cn/desktop-app/getting-started/verify-binaries.mdx new file mode 100644 index 0000000..a350db3 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/getting-started/verify-binaries.mdx @@ -0,0 +1,155 @@ +--- +title: 校验二进制文件下载 +description: 如何用经 GPG 签名的 SHA256 校验和清单验证 KaleidoSwap 桌面应用二进制文件的真实性，确保安装包未被篡改 +--- + +安装处理比特币的软件时，安全性至关重要。KaleidoSwap 的发布版本可以通过多个层面进行校验： + +- **SHA256 校验和清单**（`manifest.txt`），由开发者用存放在硬件安全密钥（YubiKey）中的 GPG 密钥签名。私钥永不离开硬件令牌。 +- macOS 构建版本带有 **Apple Developer ID 签名与公证**，安装时不会出现任何安全警告。 +- **Tauri 更新器签名**（`.sig` 文件），应用内置的更新器会在应用更新前自动校验。 + + +为每个发布二进制文件提供独立的 GPG 分离签名（`.asc`）已在计划中，但目前尚未随发布版本一起发布。在此之前，请使用下面介绍的校验和清单来验证你的下载文件。 + + +## 为什么要校验下载文件？ + +安装前校验二进制文件可以确认： + +- 文件由 KaleidoSwap 开发者构建并签名 +- 文件在传输过程中未被篡改或损坏 +- 构建完成后没有被注入恶意代码 + +## 每个发布版本包含哪些文件 + +[Releases 页面](https://github.com/kaleidoswap/desktop-app/releases)为每个平台发布一个安装包： + +| 平台 | 二进制文件 | +|---|---| +| macOS Apple Silicon | `KaleidoSwap__aarch64.dmg` | +| macOS Intel | `KaleidoSwap__x64.dmg` | +| Linux (AppImage) | `KaleidoSwap__amd64.AppImage` | +| Linux (DEB) | `KaleidoSwap__amd64.deb` | +| Linux (RPM) | `KaleidoSwap--1.x86_64.rpm` | +| Windows (MSI) | `KaleidoSwap__x64_en-US.msi` | +| Windows (NSIS installer) | `KaleidoSwap__x64-setup.exe` | + +发布版本中还包含 `.sig` 文件和一个 `latest.json`。它们是 **Tauri 更新器签名**，由应用内置的更新器自动使用 —— 不是 GPG 签名，也不用于手动校验。 + +## SHA256 校验和验证 + +每个构建产物的 SHA256 哈希都列在 `manifest.txt` 文件中，该文件可作为每次 CI 运行的构建产物获取。清单由开发者用 GPG 签名（分离签名 `manifest.txt.sig`），所用密钥存放在 YubiKey 上。 + +### 前置条件 + +- 系统中已安装 **GPG**（GNU Privacy Guard） +- 你要校验的 KaleidoSwap 二进制文件 +- 同一发布版本的 `manifest.txt` 和 `manifest.txt.sig` 文件 + + +```sh macOS (Homebrew) +brew install gnupg +``` + +```sh Debian / Ubuntu +sudo apt install gnupg +``` + +```sh Windows (Gpg4win) +# 从 https://gpg4win.org 下载 +``` + + +### 1. 导入开发者公钥 + +这一步只需做一次。直接从 GitHub 导入 KaleidoSwap 开发者的 GPG 公钥： + +```sh +curl -s https://github.com/bitwalt.gpg | gpg --import +``` + +导入后可以校验密钥指纹： + +```sh +gpg --fingerprint walter@kaleidoswap.com +``` + +你在签名输出中看到的密钥 ID 应为 `9EE396C0452755F0`。 + +### 2. 校验清单签名 + +在信任清单里的校验和之前，先确认清单本身是真实的： + +```sh +gpg --verify manifest.txt.sig manifest.txt +``` + +**校验通过**时的输出如下： + +``` +gpg: Signature made Mon 10 Nov 2025 21:30:00 UTC +gpg: using RSA key 9EE396C0452755F0 +gpg: Good signature from "Walter (Kaleidoswap Developer) " +``` + +除非你为这个密钥显式设置了信任级别，否则 `gpg` 给出的 *"This key is not certified with a trusted signature!"* 警告是正常的。关键是那行 `Good signature`。 + + +如果看到 **"BAD signature"** 或 **"No public key"**，不要信任该清单，也不要安装该文件。请从官方 [GitHub Releases](https://github.com/kaleidoswap/desktop-app/releases) 页面重新下载后再试。如果问题仍在，请提交 [GitHub Issue](https://github.com/kaleidoswap/desktop-app/issues)，或在 [Telegram](https://t.me/kaleidoswap) 上联系我们。 + + +### 3. 用清单核对你的二进制文件 + +计算下载文件的 SHA256 哈希，并与 `manifest.txt` 中的条目比对： + + +```sh macOS +shasum -a 256 KaleidoSwap_0.5.0_aarch64.dmg +``` + +```sh Linux +sha256sum -c manifest.txt --ignore-missing +``` + +```powershell Windows (PowerShell) +Get-FileHash -Algorithm SHA256 KaleidoSwap_0.5.0_x64_en-US.msi +``` + + +哈希必须与清单条目完全一致。如果不一致，请删除文件并重新下载。 + +## macOS 平台的额外校验 + +macOS 构建版本还使用 Apple Developer ID 证书进行了代码签名，并通过了 Apple 公证。安装后你可以自行校验： + +```sh +# 检查 Gatekeeper 评估结果 +spctl --assess --verbose=4 --type install /Applications/KaleidoSwap.app + +# 检查代码签名 +codesign --verify --verbose=2 /Applications/KaleidoSwap.app +``` + +正确签名并公证的应用会让 `spctl` 输出 `accepted`，且 `codesign` 不报任何错误。 + +## 自动更新 + +安装完成后，应用内置的更新器会下载新版本，并用应用内嵌的公钥，对随发布版本一起发布的 `.sig` 更新器签名逐个校验。这一过程自动完成 —— 更新无需任何手动操作。 + +## 故障排查 + +| 错误 | 原因 | 解决方法 | +|---|---|---| +| `No public key` | 未导入开发者密钥 | 执行 `curl … \| gpg --import` 命令 | +| `BAD signature` | 清单被修改或损坏 | 重新下载清单及其签名文件 | +| `Can't check signature: No public key` | 密钥不匹配 | 确认你是从 `github.com/bitwalt.gpg` 导入的 | +| 校验和不匹配 | 下载不完整或文件损坏 | 删除并重新下载二进制文件 | + +如果以上方法都无法解决问题，请通过 [GitHub Issues](https://github.com/kaleidoswap/desktop-app/issues) 或 [Telegram](https://t.me/kaleidoswap) 联系团队。 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/kaleidomind/brain.mdx b/mintlify-docs/cn/desktop-app/kaleidomind/brain.mdx new file mode 100644 index 0000000..f38355c --- /dev/null +++ b/mintlify-docs/cn/desktop-app/kaleidomind/brain.mdx @@ -0,0 +1,40 @@ +--- +title: "启用 KaleidoMind 大脑" +sidebarTitle: "大脑" +description: "在 KaleidoSwap 桌面应用中开启本地 AI 大脑：应用模式选择、设备端模型下载、隐私边界，以及带风险限额的自动任务调度" +--- + + + KaleidoMind 目前是实验性预览版。各版本之间的行为可能变化，自动任务在你确认配置无误之前应一直保持演练模式。 + + +大脑是[对话](/cn/desktop-app/kaleidomind/chat)背后的推理引擎。它**在你的设备上**运行：模型、工具调用和推理过程全部保留在本地，钱包和节点数据不会离开这台机器。 + +## 如何开启 + +在 **「设置 > 功能」(Settings > Capabilities)** 中选择一种应用模式： + +| 模式 | 运行内容 | +|------|-----------| +| **Node + Mind** | 钱包和节点与本地大脑一起运行——完整体验 | +| **Only Node** | 仅运行 RGB Lightning Node、通道和交换功能，不含 AI | +| **Only Mind** | 仅运行本地大脑，无需节点 | + +首次启用时，应用会下载所需的运行时和模型文件。这些文件提供 macOS、Windows (x64) 和 Linux 版本。 + +![KaleidoMind AI 模型下载界面](/assets/images/desktop-app/28_model-download.png) + +## 它如何访问你的钱包 + +大脑不会接触你的密钥。它通过 KaleidoSwap 的 [MCP 服务器](/cn/ai-tools/mcp-servers)读取余额、通道和报价，并起草支付与交换——这与任何其他 MCP 客户端所用的是同一套带类型的工具接口。 + +由于在该契约中，每个动用资金的工具都被标记为需要确认，引擎必须停下来征求你的同意。读取操作可以自由执行，支出则不行。 + +## 自主运行 + +**「智能体」(Agent)** 标签页可以调度大脑自主运行优化类任务——例如组合管理和定投（DCA）类例程——而不必等你主动发问。 + +- 任务带有**风险限额**，并且**默认为演练模式**：任务照常运行、决策照常生成，但不会真正执行 +- 最近的运行记录及其成本可以事后查看 + +在你观察过若干次运行、并认可它的决策之前，请一直保持演练模式开启。 diff --git a/mintlify-docs/cn/desktop-app/kaleidomind/chat.mdx b/mintlify-docs/cn/desktop-app/kaleidomind/chat.mdx new file mode 100644 index 0000000..9347861 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/kaleidomind/chat.mdx @@ -0,0 +1,35 @@ +--- +title: "与你的钱包对话" +sidebarTitle: "对话" +description: "在 KaleidoSwap 桌面应用中用 KaleidoMind 对话：用自然语言查询余额、执行交易、购买通道，任何动用资金的操作都必须先经你确认" +--- + + + KaleidoMind 目前是实验性预览版。它还不够完善，偶尔会给出错误回答，因此在批准任何支出前，请务必核对确认界面上的详情。 + + +对话是 [KaleidoMind](/cn/ai-tools/kaleido-mind) 的会话入口，KaleidoMind 是随桌面应用一起提供的本地助手。你用自然语言提问，模型通过工具读取你的钱包和节点，并起草相应操作。在你确认之前，不会有任何资金变动。 + +在 **「设置 > 功能」(Settings > Capabilities)** 中选择 **Node + Mind** 即可启用。背后运行的组件请参见[大脑](/cn/desktop-app/kaleidomind/brain)。 + +## 你可以问什么 + +| 提问 | 会发生什么 | +|-----|--------------| +| **余额、通道、价格** | 模型通过工具读取状态并直接回答。无需确认——因为没有动用任何资金 | +| **「买 1 USDT」** | 向做市方询价，并在一次确认（确认界面显示真实数字）之后完成整个原子交换 | +| **「买一条通道」** | 订购入向 BTC 流动性，或订购由 LSP 预先注入 RGB 资产的通道，同样只需一次确认 | + +只读类问题可以随便问。任何会动用资金的操作，都会先停在确认界面。 + +## 支出前必须确认 + +每一个动用资金的操作都设有关卡。确认界面是根据已解析的实际调用生成的——真实的金额、资产和目标地址——而不是模型对操作的描述，因此单位或收款方一旦出错，你都能在这里发现。 + +模型无法绕过这道关卡。它属于工具契约的一部分，而不是界面上的客套提示。 + +## 一轮对话运行时 + +- **实时工具活动** — 工具调用会在发生时以带类型的结果卡片呈现，让你看清究竟读取了哪些余额、通道或报价 +- **推理过程** — 可以选择展开模型在这一轮中的思考过程 +- **停止** — 随时可以取消；正在运行的本地推理会立即中止，这一轮干净地结束 diff --git a/mintlify-docs/cn/desktop-app/support/additional-resources.mdx b/mintlify-docs/cn/desktop-app/support/additional-resources.mdx new file mode 100644 index 0000000..64041be --- /dev/null +++ b/mintlify-docs/cn/desktop-app/support/additional-resources.mdx @@ -0,0 +1,32 @@ +--- +title: 更多资源 +description: "面向 KaleidoSwap 用户和开发者的实用链接，包括社区渠道、源代码，以及闪电网络与比特币二层协议的相关资源。" +--- + +## 官方资源 + + + + 桌面应用的源代码、发布版本和问题跟踪。 + + + RGB 协议的官方文档与规范。 + + + +## 开发与测试 + + + + 获取用于在 Mutinynet 上开发和测试的测试网比特币。 + + + 加入社区获取支持并参与讨论。 + + + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/support/changelog.mdx b/mintlify-docs/cn/desktop-app/support/changelog.mdx new file mode 100644 index 0000000..ddd0d4a --- /dev/null +++ b/mintlify-docs/cn/desktop-app/support/changelog.mdx @@ -0,0 +1,121 @@ +--- +title: "KaleidoSwap 桌面应用更新日志" +sidebarTitle: "更新日志" +description: "KaleidoSwap 桌面应用版本历史：从最新版本回溯到 alpha 阶段，逐版本记录 macOS、Windows 和 Linux 上的新增功能、变更与修复。" +--- + +## v0.5.0（当前版本） + +**发布日期：** 21 June 2026 + +**支持平台：** macOS（Apple Silicon 和 Intel）、Windows (x64)、Linux（AppImage、deb、rpm） + + +KaleidoMind 目前是早期预览版。它还不够完善，各版本之间的行为也会变化。在批准任何支出前，请务必核对确认界面上的详情。 + + +### 新增 + +- **KaleidoMind**，一个运行在本地设备上的 AI 智能体。你可以在本地与钱包和节点对话，只需一次确认就能完成完整的原子交换或购买通道，还能调度带风险限额、默认演练模式的自主任务。 +- KaleidoMind 新增 Windows (x64) 支持，此前已支持 macOS 和 Linux。 +- 可在设置中修改密码，并新增一键连接 Docker regtest 的预设。 +- 韩语翻译。 + +### 变更 + +- 购买通道流程现在会沿用你配置的 LSP 或做市商，不再重置为网络默认值，并在整个下单过程中显示当前连接的 LSP。 +- 重新设计了存入、提取和历史记录界面，基于 Tailwind v4 和 kaleido-ui 设计令牌重建。 +- 做市商与 LSP 配置统一收纳到设置中。 +- 所有 RGB 资产模式（NIA、CFA、UDA、IFA）现在在钱包和交易界面中都可见。 + +### 修复 + +- 节点重连更快。远程节点被锁定时会明确报告为已锁定，而不再报成认证失败。 +- 精度为 `0` 的资产现在会被正确处理，空订单或失败的通道订单不再写入历史记录。 + +## v0.4.0 + +**发布日期：** 16 April 2026 + +### 新增 + +- **Docker 节点后端。** 可直接从应用中以容器方式运行 RGB Lightning Node，支持自动拉取镜像、容器生命周期管理和健康监控。 +- **限价单**与**定投（DCA）**，两者都支持本地持久化并由调度器驱动执行。 +- 反向报价，实现双向询价交易。 +- BIP21 存入 URI、端口冲突自动处理，以及本地节点的托盘图标和后台运行控制。 + +### 变更 + +- 交易页面拆分为做市商视图和限价单视图，并通过并行初始化加快加载速度。 +- 迁移到 KaleidoSDK v0.1.0。 +- 交易、钱包历史、初始设置和通道管理等模块的多语言覆盖更加完整。 + +### 修复 + +- 停用浅色模式以避免渲染不一致，深色模式成为唯一支持的主题。 +- 解锁重试超时时间从约 3 分钟提高到约 1 小时，同步较慢的节点不会再误报“已达到最大尝试次数”错误。 +- `rustls-webpki` 和 `tar` 的安全更新。 + +## v0.3.2 + +**发布日期：** 10 November 2025 + +### 新增 + +- 支持向见证接收方发送 RGB 资产，可为见证 UTXO 填写比特币金额，最低 512 聪。 +- Windows 安装包中内置 WebView2 引导程序。 + +### 变更 + +- 加强了存入和提取流程中 RGB 发票分配的校验与错误处理。 + +## v0.3.1 + +**发布日期：** 3 November 2025 + +### 新增 + +- 助记词查看器，可在安全警告和明确确认之后，在应用内显示你的助记词。 +- Windows 安装包的 NSIS 配置。 + +### 修复 + +- 链上发送 RGB 资产时缺少金额参数的问题。 +- 提取时若分配为 null 或 undefined 会导致崩溃的问题。 + +## v0.3.0 + +**发布日期：** 20 October 2025 + +### 新增 + +- 支持直接在通道中购买资产，通道会作为购买流程的一部分自动建立。 +- 通道订单的开通费、容量费和时长费实时估算。 +- 订单详情视图，包含资产交付状态、重试交付和重启订单流程。 +- RGB 发票的隐私模式，可在盲化 UTXO 和标准链上地址之间切换。 + +### 变更 + +- macOS 版本使用 Apple 证书签名，安装时不再出现安全警告。 +- 在没有可用通道时支持使用链上余额交易，并提示你创建通道。 + +## v0.2.0 + +**发布日期：** 23 July 2025（alpha） + +### 新增 + +- 通道关闭确认、地址校验，以及已连接对等节点的选择。 +- 带精度管理的资产选择，以及交易时的资产冲突校验。 +- 带消息队列和重试逻辑的 WebSocket 服务。 + +### 修复 + +- 购买通道流程中的最大可发送金额。 +- Windows manifest 集成与 MSVC 构建流程。 + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/support/faq.mdx b/mintlify-docs/cn/desktop-app/support/faq.mdx new file mode 100644 index 0000000..987f661 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/support/faq.mdx @@ -0,0 +1,128 @@ +--- +title: "KaleidoSwap 桌面应用常见问题" +sidebarTitle: "常见问题" +description: "关于 KaleidoSwap 桌面应用的常见问题解答，涵盖钱包、闪电通道、资产交换、费用与安全性，以及如何反馈问题和获取帮助" +--- + +## 常见问题 + + + + KaleidoSwap 桌面应用是一款开源桌面软件，支持在闪电网络上交易 RGB 资产。它提供了易用的界面来管理 RGB Lightning 节点，并连接闪电服务提供商（LSP）。 + + + + 钱包支持全部四种 RGB 模式：NIA（非可增发资产）、CFA（收藏类可替代资产）、UDA（唯一数字资产）和 IFA（可增发可替代资产）。平台目前交易的交易对都是 NIA 资产（此前称为 RGB20）——它们是运行在比特币上的客户端验证智能合约，代表固定供应量的可替代代币。 + + + + **不是**，KaleidoSwap 桌面应用是非托管的。你始终完全掌控自己的私钥和资产。应用提供安全的密钥管理和加密备份。 + + + + **不必**，你有两种选择： + - 自己运行 RGB Lightning 节点 + - 通过应用连接到已有的节点 + + + + KaleidoSwap 桌面应用采用接单方—做市方模型进行交易： + 1. 做市方提供流动性并设定价格 + 2. 接单方可以查看实时价格更新 + 3. 交易通过 RLN API 以原子交换方式执行 + 4. 所有交易都由闪电网络和 RGB 协议保障 + + + + **粉尘储备（3,000 聪）：** 在 RGB 闪电交换中，接单方（也就是你）必须作为交换的一部分，始终向做市方发送 3,000 聪。这些聪并没有丢失——它们只是充当临时的“粉尘金额”。当做市方完成 HTLC 并把资产发回时，你会连同资产一起收回这 3,000 聪。因此，你的余额中至少要留出 3,000 聪不可用于交易，交换流程才能正常运转。 + + 除了粉尘储备之外，可交易的数量还受你通道的出向容量限制，以及做市方为每条路由所公布的单资产限额限制。 + + + + KaleidoSwap 桌面应用采取了多重安全措施： + - 非托管架构 + - 加密的通道备份 + - 安全的密钥管理 + - 无需信任的交易协议 + - RGB 资产的客户端验证 + + + + 是的，KaleidoSwap 桌面应用高度重视隐私： + - 通道操作可以是私密的 + - 交易详情只有参与方知晓 + - 基础操作无需 KYC + + + + 要在 KaleidoSwap 桌面应用上开始交易： + 1. 安装桌面应用 + 2. 创建或导入钱包 + 3. 向钱包充入比特币 + 4. 开通闪电通道 + 5. 获取 RGB 资产 + + + + 你可以通过以下方式获取 RGB 资产： + - 在 KaleidoSwap 桌面应用中交易 + - 连接 RGB LSP + - 参与 RGB 代币分发 + + + + 运行 KaleidoSwap 桌面应用的最低要求： + - 较新的操作系统（Windows、macOS、Linux） + - 建议 4GB 内存 + - 稳定的网络连接 + - 如果运行全节点，需有足够的存储空间存放区块链数据 + + + + 反馈 bug 的方式： + 1. 先查看 GitHub 上已有的 issue + 2. 提供详细的复现步骤 + 3. 附上相关日志和系统信息 + 4. 通过 GitHub issues 提交 + + + + 有，开发者可以参考： + - [API 文档](/cn/api-reference/introduction) + - [RGB LSPS1 规范](/cn/api-reference/rgb-lsps1-apis) + - [交易协议](/cn/api-reference/swap-apis) + + + +## 获取帮助 + +如果遇到的是报错而不是疑问，请先查看[故障排查](/cn/desktop-app/support/troubleshooting)。其他情况请通过下方任一渠道反馈问题，并附上以下信息： + +1. 你的操作系统及版本（macOS、Windows 或 Linux） +2. KaleidoSwap 桌面应用版本 +3. 节点类型（本地或远程）及版本 +4. 复现步骤 +5. 错误信息或截图 +6. 日志文件： + - macOS：`~/Library/Logs/com.kaleidoswap.dev/` + - Windows：`%APPDATA%\com.kaleidoswap.dev\logs` + - Linux：`~/.local/share/com.kaleidoswap.dev/logs` + + + + 向社区提问。 + + + 在对应的代码仓库中反馈 bug。 + + + 紧急问题的直接支持渠道。 + + + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/support/settings.mdx b/mintlify-docs/cn/desktop-app/support/settings.mdx new file mode 100644 index 0000000..8e47351 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/support/settings.mdx @@ -0,0 +1,108 @@ +--- +title: "桌面应用设置" +sidebarTitle: "设置" +description: "配置 KaleidoSwap 桌面应用：应用模式、比特币单位与语言、做市商与 LSP 接入，以及节点连接、安全备份和节点状态等各项设置" +--- + +设置面板可从应用右上角的下拉菜单打开。它分为 **应用设置**(Application Settings)、**做市商与 LSP 设置**(Maker & LSP Settings) 和 **节点连接设置**(Node Connection Settings) 三部分，旁边还有 **安全与备份**(Security & Backup) 和 **节点状态**(Node Status) 面板。多数修改在点击 **「保存」(Save)** 后生效；节点连接设置下的修改还需要重启节点。 + +## 应用设置 + +应用设置面板 + +### 功能 (Capabilities / App Mode) + +**作用：** 决定显示 KaleidoSwap 的哪些部分： + +- **Node + Mind** — 同时运行钱包/节点和本地 AI 大脑（KaleidoMind） +- **Only Node** — 仅运行 RGB Lightning 节点、通道和交换功能 +- **Only Mind** — 仅运行本地 AI 大脑，无需节点 + +功能（应用模式）设置项 + +### 比特币单位 (Bitcoin Unit) + +**作用：** 控制应用中比特币金额的显示方式。 + +- **Satoshi (SAT)** — 以聪（最小单位）显示金额（例如 100,000 聪） +- **Bitcoin (BTC)** — 以比特币小数形式显示金额（例如 0.001 BTC） + +**何时需要修改：** 如果你觉得小额交易的小数金额不好读，切换成聪可以减少误读，也不会出现一长串前导零。 + +### 法币 (Fiat Currency) + +**作用：** 设置用于显示余额和交换估值的法币币种。 + +### 语言 (Language) + +**作用：** 设置应用的显示语言。下拉菜单中提供多种语言。 + +### 主题 (Theme) + +应用只支持深色模式。浅色模式已被停用，以避免不同界面渲染不一致，因此设置中没有主题切换开关，应用也会忽略操作系统的主题偏好。 + +## 做市商与 LSP 设置 + +做市商与 LSP 设置面板 + +### 做市商 URL (Maker URLs) + +**作用：** 管理应用可连接的做市商接口端点列表，用于获取报价和执行交换。你可以添加多个做市商、删除它们，并把其中一个标记为**默认**（星形图标）。 + +### LSP URL + +**作用：** 设置节点连接的闪电服务提供商 URL，用于获取通道流动性和交换路由。它通常与你的默认做市商 URL 一致。 + +**何时需要修改：** 默认值已预先配置好，适用于大多数用户。如果你自己运行 LSP、偏好的 LSP 使用其他 URL，或者默认地址无法访问，就需要修改。 + +## 节点连接设置 + + + 这些设置需要重启节点才能生效。保存后，应用会提示你 **「重启节点」(Restart Node)**，以便应用新的连接设置。 + + +### 节点连接串 (Node Connection String) + +**作用：** 指定应用连接的 RGB Lightning Node (RLN)，所有钱包、通道和支付操作都通过它完成（例如 `http://localhost:3001`）。 + +**何时需要修改：** 默认情况下，应用会管理一个内置的本地节点。如果你要连接远程或自建的 RGB Lightning Node，或者要在多个节点实例之间切换，就需要修改这一项。 + +### Bitcoin RPC + +**作用：** 节点访问其 bitcoind 后端所使用的 Bitcoin Core RPC 连接串。 + +### 索引器 URL (Indexer URL) + +**作用：** 节点用于查询区块链的 Electrum/Esplora 索引器。 + +### RGB 代理端点 (RGB Proxy Endpoint) + +**作用：** 用于交换 RGB 转账数据的 RGB 代理接口端点。 + + + 修改任何节点连接设置，都会让应用连接到另一个节点或后端。保存前请确认目标节点及相关服务正在运行且可以访问，然后在收到提示时重启节点。 + + +节点连接设置面板 + +## 安全与备份 + +安全与备份面板提供以下功能： + +- **查看助记词**(View Recovery Phrase) — 显示钱包的助记词种子短语 +- **修改密码**(Change Password) — 更新钱包的加密密码 +- **备份**(Backup) — 创建通道状态的加密备份。完整说明请参见[通道备份](/cn/desktop-app/channels/channel-backups)页面。 + +安全与备份设置面板 + +## 节点状态 + +显示节点当前是运行中还是已离线，以及它是本地节点还是远程节点。在这里你可以 **「登出」(Logout)**（锁定节点）或 **「关闭」(Shutdown)** 节点。对于本地节点，设置页面底部还会显示实时的节点日志。 + +节点状态与日志面板 + +--- + + + 获取适用于 macOS、Windows 和 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx b/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx new file mode 100644 index 0000000..5a9deb7 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/support/troubleshooting.mdx @@ -0,0 +1,135 @@ +--- +title: "KaleidoSwap 桌面应用故障排查" +sidebarTitle: "故障排查" +description: "解决 KaleidoSwap 桌面应用中交易失败、钱包恢复和 LSP 连接等常见问题，提供逐步排查方法，并链接到完整的支持指南。" +--- + +以下是桌面应用用户最常遇到问题的解决办法。如需了解涵盖各个 KaleidoSwap 组件的安装、节点同步、通道和交换问题，请参见[完整故障排查指南](/cn/whats-kaleidoswap/troubleshooting)。 + +## 交易 + + + + **现象**：原子交换未能完成。 + + **解决办法**： + 1. 检查通道流动性 + 2. 核对 RGB 资产详情 + 3. 确认节点已正常同步 + 4. 如问题持续，请联系支持 + + + + **现象**：「通道容量」(Channel Capacity) 字段拒绝手动输入，或只接受以 “50000” 开头的数值。 + + **原因**：50,000 聪是最小通道容量，该字段会在你输入时按这个下限校验。 + + **解决办法**：选中该字段的全部内容，一次性重新输入完整数字，而不要逐位修改——例如全选后直接输入 `500000`，而不是去改动已有数值的开头几位。只要不低于 50,000 聪，任何金额都会被接受。 + + + +## 钱包 + + + + 恢复钱包的步骤： + 1. 使用你此前创建的备份文件 + 2. 用你的密码解密备份文件 + 3. 等待节点同步完成 + + + +## 连接 {#connectivity} + + + + **现象**：出现关于 LSP 连接的错误提示，或无法开通通道。 + + **解决办法**： + 1. 检查网络连接是否稳定 + 2. 核对 LSP 地址——默认为 `https://api.mutinynet2.kaleidoswap.com/`，位于「设置」(Settings) → 「做市方与 LSP 设置」(Maker & LSP Settings) + 3. 检查防火墙/VPN 设置；需要开放的端口为 9735（闪电 P2P）和 3001（节点 API） + 4. 查看该 LSP 的状态页面，或在有其他 LSP 可选时切换一个 + + 更多连接问题（包括节点配置和通道容量问题）请参见[完整故障排查指南](/cn/whats-kaleidoswap/troubleshooting)。 + + + + **现象**：Windows 上没有运行本地节点的选项，或本地节点设置失败。 + + **原因**：RGB Lightning Node 集成尚未在 Windows 上获得完整的原生支持。 + + **解决办法**： + 1. 改为连接**远程节点**——在 Linux 或 macOS 上自行托管，或在 Docker 容器中运行并远程连接。两种方式都可参见[节点托管](/cn/desktop-app/getting-started/node-hosting) + 2. 或使用 [ThunderStack](/cn/desktop-app/getting-started/node-hosting#option-3-hosted-provider-thunderstack) 这类专业托管方案 + 3. 通过远程连接使用交易和钱包功能的方式完全相同——受影响的只有本地节点托管 + + + + **现象**：节点在启动过程中退出，或桌面应用无法访问它的 API。 + + **检查项**： + 1. 确认 Bitcoin Core 正在运行，且节点能访问所配置的 RPC 主机、端口、用户名和密码 + 2. 确认所配置的索引器和 RGB proxy 接口端点在线 + 3. 查看节点日志中出现的第一条启动错误，修正相关连接设置后重启 + + + + **现象**：应用提示远程节点不可达，或始终处于未连接状态。 + + **检查项**： + 1. 在**「设置」>「节点连接」** (Settings > Node Connection) 中核对节点地址，并确认节点正在运行且已解锁 + 2. 确保服务器防火墙放行节点 API 端口（默认：`3001`）以及 `9735` 上的闪电对等节点流量 + 3. 如果你使用了 VPN、反向代理或隧道，请确认它会把流量转发到应用中配置的同一地址和端口 + + + + **现象**：节点持续处于同步状态，钱包或通道操作不可用。 + + **检查项**： + 1. 等 Bitcoin Core 完成同步后再重试 + 2. 检查所配置的 Electrum 或 Esplora 索引器是否已追上所选网络的进度 + 3. 确认节点、比特币后端和索引器使用的是同一网络 + + + + **现象**：signet 节点无法连接，或交易在 Mutinynet 上不确认。 + + **检查项**： + 1. 使用支持 Mutinynet/signet 的比特币构建版本和 Electrs 配置 + 2. 确认节点配置了 `NETWORK=signet` 以及正确的 Mutinynet 种子节点 + 3. 在 [Mutinynet 浏览器](https://mutinynet.com/)上查看网络状态和交易确认情况 + + + +## 获取帮助 + +如果遇到的是疑问而不是报错，请查看[常见问题](/cn/desktop-app/support/faq)。其他情况请通过下方任一渠道反馈问题，并附上以下信息： + +1. 你的操作系统及版本（macOS、Windows 或 Linux） +2. KaleidoSwap 桌面应用版本 +3. 节点类型（本地或远程）及版本 +4. 复现步骤 +5. 错误信息或截图 +6. 日志文件： + - macOS：`~/Library/Logs/com.kaleidoswap.dev/` + - Windows：`%APPDATA%\com.kaleidoswap.dev\logs` + - Linux：`~/.local/share/com.kaleidoswap.dev/logs` + + + + 向社区提问。 + + + 在对应的代码仓库中反馈 bug。 + + + 紧急问题的直接支持渠道。 + + + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/trading/asset-swaps.mdx b/mintlify-docs/cn/desktop-app/trading/asset-swaps.mdx new file mode 100644 index 0000000..ee8dbbd --- /dev/null +++ b/mintlify-docs/cn/desktop-app/trading/asset-swaps.mdx @@ -0,0 +1,91 @@ +--- +title: 交换资产 +description: "在 KaleidoSwap 桌面应用中交换比特币与比特币二层资产：获取报价、执行无需信任的原子交换、了解各种交易模式与交易对，并跟踪交换状态。" +--- + +资产交换让你可以通过 KaleidoSwap 平台把一种资产换成另一种。桌面应用采用**原子交换**——交易双方同时执行，任何一方都无法作弊。 + +## 前置条件 + +开始交换之前，请确认你已具备： + +1. **已注资的钱包** —— 你需要持有想要换出的资产余额。参见[存入资金](/cn/desktop-app/wallet/deposits)。 +2. **已开通的通道** —— 通道容量必须足够覆盖交换数量，并且包含你想交易的 RGB 资产。参见[开通通道](/cn/desktop-app/channels/opening-channel)或[购买通道](/cn/desktop-app/channels/order-new-channel)。 + +## 执行资产交换 + + + + 点击左侧边栏的**「交易」(Trading)** 标签，然后选择**「做市商」(Market Maker)** 标签开始。 + + + + 选择你持有的资产（例如 BTC）和你想收到的资产（例如 USDT）。 + + + + 填写你想交换的资产数量。应用会按当前汇率显示你预计收到的数量。 + + + + 核对汇率和各项费用，点击**「交换」(Swap)** 执行交易。 + + + + 交换会通过闪电网络原子化执行。完成后，你会看到成功确认提示。 + + + +![KaleidoSwap 桌面应用交易页面，显示资产对选择与交换报价](/assets/images/desktop-app/19_trading_page.png) + +## 交易模式 + +**交易**区域把几种交易方式分别放在各自的标签页中： + +- **做市商** —— 基于已连接做市商的实时报价交易。交换按做市方的当前汇率原子化执行。这是默认模式，也就是上文描述的流程。 +- **手动交换** (Manual Swaps) —— 自行发起并确认单笔交换，可以选择做市方，并在执行前逐笔核对报价。 +- **DCA** —— 通过固定周期买入或下跌价格触发来自动积累 BTC。每次成功执行都会把固定金额换成 BTC。 + +![DCA 交易界面](/assets/images/desktop-app/24_dca.png) + +- **限价单** (Limit Orders) —— 为某个交易对设定目标价格；当市场达到该价格时，交换会自动执行。 + +![限价单交易界面](/assets/images/desktop-app/25_limit-order.png) +- **Nostr P2P** *（即将推出）* —— 通过 Nostr 进行点对点交易，无需依赖中心化做市方，直接与其他用户成交。 + +## 支持的交易对 + +可用交易对由你连接的做市方决定，因此具体列表会有所不同。截至撰写本文时，默认的 KaleidoSwap 做市方提供以下交易对： + +| 交易对 | 说明 | +|------|------------| +| **BTC / USDT** | 比特币兑 Tether USD（RGB NIA） | +| **BTC / XAUT** | 比特币兑 Tether Gold（RGB NIA） | + +应用中的**可用交易对** (Available Trading Pairs) 面板始终反映你所连接做市方当前支持的交易对。 + +## 交换历史 + +在**「历史」(History)** 标签中查看过往交换记录，便于留档和对账。 + +## 故障排查 + + + + 请确认对应通道中有足够余额。仅有链上余额是不够的——资产必须已分配到与交易对等节点之间的闪电通道中。 + + + + 检查你的节点是否已连接到支持该资产对的对等节点。你可能需要与提供做市服务的 LSP 开通一条通道。 + + + + 闪电网络上的原子交换应在几秒内完成结算。如果某笔交换看起来卡住了，请在设置中检查节点的连接状态。如果连接曾中断，重启应用可能有帮助。 + + + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新版 KaleidoSwap 桌面应用。 + diff --git a/mintlify-docs/cn/desktop-app/wallet/creating-wallet.mdx b/mintlify-docs/cn/desktop-app/wallet/creating-wallet.mdx new file mode 100644 index 0000000..0e8e23d --- /dev/null +++ b/mintlify-docs/cn/desktop-app/wallet/creating-wallet.mdx @@ -0,0 +1,47 @@ +--- +title: 创建新钱包 +description: "在 KaleidoSwap 桌面应用中创建新钱包：生成助记词、设置密码、初始化节点，并安全备份密钥，逐步完成整个流程。" +--- + +首次启动应用时，你需要选择钱包要连接的节点类型。有两个选项：使用远程节点，或使用本地节点。前者需要你连接到一个已在运行的 RGB Lightning Node，后者会在当前设备上自动初始化一个节点并把数据存在本地。本指南演示本地节点的流程，因为这是开始体验 KaleidoSwap 应用最简单的方式。 + +KaleidoSwap 桌面应用启动界面，显示节点连接选项 + +## 创建新钱包 + +要开始创建流程，先选择「创建新钱包」(Create New Wallet) 选项： + +KaleidoSwap 桌面应用中的创建新钱包选项 + +然后按以下步骤操作： + +1. **为账户命名**，并**选择要使用的网络**。网络选择器提供 regtest（及其 Local、Docker 和 Bitfinex 变体）、signet、Mutinynet 和测试网作为测试环境。主网暂不可选。 +钱包创建第 1 步：填写账户名称并选择网络 +2. **设置安全密码**：输入一个强密码来保护钱包，然后点击「初始化节点」(Initialize Node)。这会在你的机器上启动节点初始化。 +钱包创建第 2 步：设置安全密码并初始化节点 +3. **备份**：节点初始化完成后，抄下界面给出的助记词并妥善保存。 +钱包创建第 3 步：需要抄写的助记词备份短语 +4. **验证**助记词：出于安全考虑，应用会要求你重新输入助记词。 +钱包创建第 4 步：助记词验证 + +之后需要稍等一会儿来解锁新的本地节点，随后你就会进入 KaleidoSwap 主页，可以开始使用了！ + + + +## 选择账户 + +如果你不是要创建新账户，而是要选择一个已有账户，可以在左侧菜单中从之前保存的账户里选择，即使该账户尚未初始化也可以。步骤如下： + +1. **选择账户** (Select Account)：在左侧菜单中选择。 +2. 确认账户无误后，点击**选择节点** (Select Node)。 +3. **解锁钱包** (Unlock Wallet)：输入此前设置的密码，解锁本地 RGB Lightning Node 实例。 + +请注意，由于 RGB 闪电网络代码目前存在的限制，解锁节点可能需要一些时间。 + +KaleidoSwap 主界面，左侧菜单显示已保存的账户 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/wallet/deposits.mdx b/mintlify-docs/cn/desktop-app/wallet/deposits.mdx new file mode 100644 index 0000000..13166e5 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/wallet/deposits.mdx @@ -0,0 +1,36 @@ +--- +title: 向钱包存入资金 +description: "向 KaleidoSwap 钱包存入比特币和 RGB 资产：链上地址、二维码、闪电发票、染色 UTXO，以及测试网水龙头的用法。" +--- + +开始使用 KaleidoSwap 通常要做的第一件事就是存入一些资金，无论是为了交换资产还是为了保管资产。前者需要你存入比特币来开通 RGB 通道，后者则可以自行决定存入哪种资产（包括 RGB 资产）。 + +## 存入比特币 + +1. **点击「存入」(Deposit)**：它位于左侧菜单的「快捷操作」(Quick Actions) 区域。桌面应用快捷操作菜单中的存入按钮 +2. **选择资产**：在下拉菜单中选择「BTC」（比特币，默认应该已选中），然后点击「继续」(Continue)。你会进入**存入 BTC** (Deposit BTC) 界面。 +3. **存入方式**：在存入 BTC 界面选择你偏好的方式：**链上** (On-chain) 或**闪电** (Lightning)。选择链上时，应用会立即显示比特币地址和二维码（你可以复制地址，或刷新以获取新地址）。存入 BTC 界面，显示链上地址与二维码 +4. **完成存入**：如果选择**链上**，复制或扫描同一界面上显示的地址（或二维码），并向其发送你想存入的比特币金额。如果选择**闪电**，输入要存入的金额以生成发票，然后支付该发票。 + +## 存入 RGB 资产 + +1. **选择资产**：重复上一节的第 1、2 步，但这次选择某个已注册资产，或用资产 ID 上传一个。资产要出现在已注册列表中，你的节点必须此前遇到过（即接收过）它。本例中我们使用 test-USDT。 +2. **存入方式**：与上一节相同，在两种可用方式中选择一种存入资产：链上或闪电网络。 +3. **完成存入**：如果选择链上方式，你需要复制自动生成的 `recipient id`，用对应的 id 存入想要的资产数量。 +注意，要继续存入，你至少需要有一个可用的「染色」(Colored) UTXO —— 这是在比特币区块链上交易 RGB 资产所必需的一种特殊 UTXO。如果你没有可用的染色 UTXO，应用会在这一步允许你一键生成一个（前提是 KaleidoSwap 钱包中有一些可用的比特币余额）。 +4. **生成闪电发票**：如果选择通过闪电网络存入，你需要输入想存入的资产数量以生成发票，然后完成存入。 + +存入 RGB 资产界面 + +## 获取测试币 + +如果你在创建钱包时选择了测试网络来体验 KaleidoSwap，可以使用以下水龙头获取用于存入、开通通道、交换和提取的币和资产： + +- regtest：可以在 Telegram 上体验 RGB LN Bot（@rgb_lightning_bot）的各项功能。 +- signet：可以使用 [Mutiny 水龙头](https://faucet.mutinynet.com/)，在「How much?」字段输入想接收的聪数量，把 signet 比特币地址粘贴到水龙头的「Destination」字段，然后点击「Make it rain」即可收到资金。 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/wallet/initializing-mnemonic.mdx b/mintlify-docs/cn/desktop-app/wallet/initializing-mnemonic.mdx new file mode 100644 index 0000000..3512ab5 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/wallet/initializing-mnemonic.mdx @@ -0,0 +1,55 @@ +--- +title: 使用助记词备份初始化 +description: "在 KaleidoSwap 桌面应用中生成、备份并验证助记词，了解丢失助记词的后果，以及如何用加密备份文件恢复钱包。" +--- + +## 什么是助记词？ + +**助记词**（也叫种子短语或恢复短语）是一串 12 个单词，编码了你钱包的私钥。它是与你钱包相关的最重要的信息 —— 任何拿到它的人都能完整重建你的钱包并动用你的全部资金。 + +创建新钱包时，KaleidoSwap 会生成一组助记词。继续之前你必须先备份好它。在新设备上通过应用内恢复使用的是你的加密[备份文件](/cn/desktop-app/channels/channel-backups)，但助记词始终是钱包密钥的最终备份 —— 既没有助记词、也没有备份文件，你的资金将无法恢复。 + + + **立即备份你的助记词。** 用纸笔抄写下来，离线保存在安全的地方。如果你既丢失了助记词，又无法访问设备，你的资金将永久无法找回。KaleidoSwap 无法代你取回。 + + +## 生成并保存助记词 + + + + 在钱包创建过程中，应用会显示你的 **12 词助记词**。它在你的设备上本地生成 —— 绝不会发送到任何服务器。 + + + + 按顺序把每个单词写在纸上。仔细核对拼写 —— 只要有一个单词写错就无法恢复。 + + **最佳实践：** + - 用纸笔记录，不要用电子文档或截图 + - 把手写副本放在物理上安全的地方（例如保险箱） + - 考虑再做一份副本，存放在另一个地点 + - 绝不要保存在云存储、邮件或即时通讯应用中 + + + + 应用会要求你输入指定位置的单词以确认助记词。这一步用于在继续之前验证你已正确记录助记词。 + + + +## 助记词丢失会怎样？ + +如果你既丢失了助记词，**又**无法再访问安装钱包的那台设备： + +- 你的链上比特币资金将永久无法找回 +- 除非你有[通道备份](/cn/desktop-app/channels/channel-backups)，闪电通道中的资金也可能一并丢失 + +如果你仍能访问自己的设备并记得密码，应用会照常工作。只有在恢复到新设备或重装之后，才需要用到助记词。 + +## 恢复已有钱包 + +目前尚不支持直接用 12 词助记词导入钱包。要恢复已有钱包，请在初始设置流程中选择**「恢复钱包」(Restore Wallet)**，并提供你的加密[备份文件](/cn/desktop-app/channels/channel-backups)以及创建该备份时所用的节点密码。无论如何都要备份好助记词 —— 它始终是钱包密钥的根。 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/wallet/unlocking-wallet.mdx b/mintlify-docs/cn/desktop-app/wallet/unlocking-wallet.mdx new file mode 100644 index 0000000..fca9afe --- /dev/null +++ b/mintlify-docs/cn/desktop-app/wallet/unlocking-wallet.mdx @@ -0,0 +1,50 @@ +--- +title: 解锁钱包 +description: "在 KaleidoSwap 桌面应用中解锁钱包：输入密码、启动节点、等待区块同步，以及解锁耗时过长时该怎么处理。" +--- + +创建钱包之后，每次打开 KaleidoSwap 桌面应用都需要解锁节点。解锁使用的是你在节点初始化时设置的密码。 + +## 快速解锁流程 + +1. **打开应用** + 启动 KaleidoSwap 桌面应用。 + +2. **选择账户** + 选择与你要使用的节点关联的账户。 + +3. **运行节点** + 在账户仪表盘中启动节点。 + 如果节点处于锁定状态，解锁界面会自动出现。 + +4. **输入密码** + 在密码输入框中输入你初始化节点时使用的密码。 + KaleidoSwap 桌面应用的钱包解锁界面，带密码输入框 + +## 解锁前的节点同步 + +输入正确密码后，节点会**先**与区块链同步，然后才完全可用。 +这一过程的耗时取决于需要同步的区块数量，而这又取决于节点离线了多久。 +请耐心等待节点完成这一步。 + +RGB Lightning Node 解锁过程中的加载动画 + +## 理解解锁参数 + +- **密码** + 用于保护对钱包和节点的访问。就是你在首次配置节点时设置的那个密码。 + +- **网络** + 网络在账户创建时即固定 —— 解锁时不需要选择。解锁界面只会连接到该账户已配置的网络（例如 regtest、signet、Mutinynet 或测试网）。 + +- **高级设置** (Advanced Settings) + 这些设置取自节点的账户配置。如有需要，可在解锁前于工具栏中调整： + - Bitcoin Core 的 RPC 认证信息 + - Electrum 索引器地址 + - 与 RGB Lightning Node 通信所用的 RGB proxy 和端口设置 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/desktop-app/wallet/withdrawals.mdx b/mintlify-docs/cn/desktop-app/wallet/withdrawals.mdx new file mode 100644 index 0000000..8bd75b0 --- /dev/null +++ b/mintlify-docs/cn/desktop-app/wallet/withdrawals.mdx @@ -0,0 +1,26 @@ +--- +title: 从钱包提取资金 +description: "从 KaleidoSwap 桌面应用提取比特币和 RGB 资产：链上与闪电两种方式的操作步骤、费率选择和发送前的核对要点。" +--- + +从钱包提取资金可以把比特币或 RGB 资产发送到其他地址，流程如下： + + +1. **打开提取界面**：点击左侧边栏的**「提取」(Withdraw)** 快捷操作按钮（也可从**「快捷操作」(Quick Actions)** 菜单进入）。这会打开提取弹窗。 +2. **提取方式**：当你粘贴比特币链上地址、闪电发票／闪电地址或 RGB 发票时，提取方式会自动选定。 +3. **输入金额**：指定要提取的比特币金额或 RGB 资产数量。 +4. **费率**：链上交易可选慢速、普通或快速。 +5. **核对交易**：仔细检查各项细节。 +6. **确认并发送**：点击「提取」发起交易。 + +提取菜单，含链上与闪电两个选项 + +提取第 2 步的明细与确认界面 + +**BTC 与 RGB 链上提取的区别**：提取 RGB 资产的步骤与提取 BTC 几乎相同，唯一区别是你粘贴的是收款方的 RGB 发票，而不是比特币地址。盲化 UTXO 和 witness（基于地址）两种发票形式都支持，粘贴时应用会自动识别发票类型。 + +--- + + + 获取适用于 macOS、Windows 或 Linux 的最新 KaleidoSwap 桌面应用版本。 + diff --git a/mintlify-docs/cn/extensions/introduction.mdx b/mintlify-docs/cn/extensions/introduction.mdx new file mode 100644 index 0000000..f819a34 --- /dev/null +++ b/mintlify-docs/cn/extensions/introduction.mdx @@ -0,0 +1,106 @@ +--- +title: "KaleidoSwap 浏览器扩展" +sidebarTitle: "概览" +description: "KaleidoSwap 生态的浏览器扩展：面向 Spark、Arkade、Liquid 的多协议比特币分层钱包，内置原子交换、跨链桥和 DApp 连接，资产管理与支付审批都留在浏览器里完成。" +--- + +KaleidoSwap 浏览器扩展把钱包管理、协议账户、交换和 DApp 连接直接带进浏览器。它在工具栏上提供一个常驻的钱包界面，用于查看余额、发起转账、处理钱包审批请求以及执行协议操作。 + +## KaleidoSwap 扩展是什么？ + +KaleidoSwap 扩展是 KaleidoSwap 面向比特币及其分层协议的浏览器钱包。它把 Spark、Arkade、Liquid、Bitcoin L1 上的 RGB、可选的 RGB Lightning Node（RLN）、交换、跨链桥、Nostr 身份和 DApp 连接集中到同一个钱包界面里。 + +KaleidoSwap 扩展仪表盘 + +| 能力 | KaleidoSwap 扩展带来什么 | +|------------|-------------------------------------| +| **钱包** | 从浏览器工具栏直接访问内置钱包 | +| **支付** | 直接完成审批流程，无需在多个工具之间复制请求 | +| **资产管理** | 覆盖 Spark、Arkade、Liquid、无节点 RGB-L1 以及可选 RGB Lightning Node 账户中的 BTC 和资产 | +| **DApp 支持** | 为受信任的 DApp 提供 WebLN、WebBTC 和 Nostr（NIP-07 与 NIP-46）Provider | +| **交换** | 连接到受支持的交易场所后，可在扩展内直接交换 | +| **跨链桥** | 在 Spark 与外部链之间转移资金 | + +## 核心功能 + +### 钱包管理 + +- 使用新生成的 12 词助记词创建钱包，或导入已有的 12 词或 24 词助记词 +- 从同一助记词派生 Spark、Arkade、Liquid、RGB-L1 和 Nostr 身份状态 +- 需要 RGB 闪电通道和基于做市方的 RGB 交换时，可选择启用 RGB Lightning Node +- 按账户和分层查看 BTC：Spark、Arkade、Liquid、Bitcoin L1 以及 Lightning/RLN +- 按协议账户和网络筛选资产，并隐藏不想显示在仪表盘上的资产 +- 在侧边栏、弹出窗口或完整浏览器标签页中打开钱包 + +### 发送与接收 + +- **发送**（Send）至比特币地址、闪电发票、Lightning Address、LNURL-pay、Spark 地址、Arkade 路由、Liquid 地址和 `liquidnetwork:` URI，以及受支持场景下的 RGB 发票 +- **接收**（Receive）可根据所选账户和资产，通过 Spark、Arkade、Liquid、比特币链上、Lightning 或 RGB 发票流程完成 +- 生成二维码，方便分享 +- 自动识别目标地址类型和兼容的路由 + +### 资产交换与跨链桥 + +- RLN 连接后，可获取 KaleidoSwap 做市方交易对 +- Spark 池可用时，可使用 Spark/Flashnet 交易场所 +- 执行前先核对报价输出、费用、有效期和交易场所；内置的最大滑点会保护最小输出金额 +- 在 Spark 与外部链（EVM 网络、Solana 等）之间跨链转移资金，并持续跟踪订单状态 + +### DApp 连接 + +- **WebLN Provider**（`window.webln`）：提供节点信息、发票、支付、keysend 和 LNURL 能力 +- **WebBTC Provider**（`window.webbtc`）：提供链上地址、PSBT 签名和广播能力 +- **Nostr Provider**（`window.nostr`）：实现 NIP-07 事件签名与加密，身份来自助记词派生或导入 +- **NIP-46 远程签名**（`bunker://`）和 **Nostr Wallet Connect**，供外部应用使用 +- 敏感 DApp 操作会弹出权限提示，并可在已连接应用（Connected Apps）管理界面中按能力逐项查看和撤销 + +### 安全 + +- 基于 Argon2id 派生的密码哈希，以及一个独立的 Argon2id 派生 AES-GCM 加密密钥 +- 主助记词加密存储在 `chrome.storage.local` 中，仅在解锁期间于内存中解密 +- 除密码外，还可选启用 passkey（WebAuthn）解锁 +- PSBT 确认界面会在签名前解析并显示目标地址、金额和网络费用 +- 自动锁定超时时间可在安全（Security）设置中调整 + +## 架构 + +KaleidoSwap 扩展采用多协议适配器架构： + +| 协议 | 状态 | 说明 | +|----------|--------|-------------| +| **Spark** | 已实现 | 原生 Spark 钱包、Spark BTC、Spark 资产、Lightning 收发、Flashnet 路由和跨链桥 | +| **Arkade** | 已实现 | Arkade BTC、Arkade 原生资产、进出通道（boarding/offboarding）、VTXO 生命周期设置，以及可选的轮换地址（HD）模式 | +| **Liquid** | 已实现 | L-BTC 和 Liquid 资产（例如 USDt）——无节点、自主保管，通过 Esplora/waterfalls 接口端点同步 | +| **RGB-L1** | 已实现 | 完全运行在 WebAssembly 中的无节点 Bitcoin L1 RGB，支持云端（VSS）和本地文件备份 | +| **RGB Lightning** | 实验性，需手动启用 | RGB Lightning Node（直连 URL 或 Nostr Wallet Connect）、RGB 闪电通道，以及基于做市方的 RGB 交换 | + + +RGB-L1 和 RGB Lightning Node 两种后端互斥：RGB 资产要么存放在无节点的链上账户中，要么存放在你的 RLN 节点上，不能同时存在于两者。 + + +后台 service worker 负责协议适配器的生命周期和消息路由。弹出窗口是一个 React 钱包界面，而内容脚本和注入脚本则负责把网页的 DApp 请求桥接到后台 service worker。 + +## 工作原理 + +![KaleidoSwap 扩展架构图](/assets/images/overview/kaleidoswap-extension.png) + +- **扩展界面**运行在浏览器侧边栏、弹出窗口或完整标签页中 +- **后台 service worker** 管理协议适配器和跨上下文消息传递 +- **Spark、Arkade、Liquid 和 RGB-L1** 均由钱包助记词派生 +- **RGB Lightning Node** 为可选项，目前作为实验性功能提供 +- **DApp 连接**通过内容脚本实现，由其注入 `window.webln`、`window.webbtc`、`window.nostr`（NIP-07）和 `window.bitcoin` + +## 日常钱包流程 + +KaleidoSwap 扩展让钱包操作始终贴近浏览器： + +1. **打开 KaleidoSwap** - 从浏览器工具栏启动钱包 +2. **查看余额** - 检查 BTC 以及 Spark、Arkade、Liquid 和 RGB 资产状态 +3. **转移资金** - 在扩展内完成存入、提取、交换或跨链 +4. **审批请求** - 仅在核对细节后确认受信任的 DApp 操作 + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx new file mode 100644 index 0000000..adf03b0 --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/additional-resources.mdx @@ -0,0 +1,64 @@ +--- +title: "KaleidoSwap 扩展：更多资源" +sidebarTitle: "更多资源" +description: "KaleidoSwap 扩展用户的常用链接：测试版申请、社群与支持渠道，以及 Spark、Arkade、Liquid、RGB 和 Nostr 各项标准的官方文档。" +--- + +## 协议文档 + +扩展会从同一组助记词为每个分层派生一个账户。下面是各协议的上游参考资料。 + + + + 基于状态链的转账、Lightning 收发，以及 Spark 账户背后的代币机制。 + + + VTXO、进出通道（boarding/offboarding），以及 Arkade 账户背后的批量结算模型。 + + + L-BTC 和 USDt 等已发行资产背后的联邦侧链。 + + + 客户端验证和资产接口，同时适用于无节点 RGB-L1 和 Lightning 上的 RGB。 + + + +## DApp 标准 + +扩展注入网页的各个提供方所依据的规范。各提供方的具体暴露方式见 [DApp 连接](/cn/extensions/kaleidoswap-extension/dapp-connectivity)。 + + + + 面向 Lightning 的浏览器提供方标准，注入在 `window.webln` 上。 + + + 页面内的 Nostr 签名，注入在 `window.nostr` 上。 + + + 通过 `bunker://` 字符串，经中继完成的 Nostr Connect 远程签名。 + + + KaleidoSwap [MCP 服务器](/cn/ai-tools/mcp-servers)背后的工具协议。 + + + +## 社群与支持 + + + + 加入社群，与其他测试者交流并获取支持。 + + + 紧急问题的直接支持渠道。 + + + + + 反馈问题时，请附上浏览器及版本、**设置 > 关于**（Settings > About）中显示的扩展版本、复现步骤，以及控制台日志（右键点击弹出窗口，然后选择 **Inspect > Console**）。请先查看[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。 + + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/bridge.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/bridge.mdx new file mode 100644 index 0000000..b53a3bb --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/bridge.mdx @@ -0,0 +1,107 @@ +--- +title: 跨链桥 +description: 在 Spark 与外部链之间转移资金 +--- + +## 概览 + +**跨链桥**（Bridge）通过 **Flashnet Orchestra** 在你的 Spark 账户和外部区块链之间转移资金。它支持双向操作： + +- **存入**（Deposit） - 从外部链发送资产（例如以太坊或 Solana 上的 USDC），并在 Spark 账户中收到 **BTC** 或 **USDB**。 +- **提取**（Withdraw） - 从 Spark 发送到外部链上受支持的目标。在提取流程中粘贴外部链地址后，扩展会自动识别兼容的跨链路由。 + + +跨链桥用于跨链转移资金。要在钱包内部把一种资产换成另一种，请使用[交换](/cn/extensions/kaleidoswap-extension/swaps)。 + + +## 支持的网络 + +可用路由来自 Flashnet Orchestra，会随时间变化。跨链桥界面中出现的网络包括 Ethereum、Base、Arbitrum、Optimism、Polygon、Solana、Tron、Avalanche、BNB Chain、HyperCore 和 HyperEVM，常见资产有 BTC、USDT 和 USDC。 + +在资产选择器中使用**网络筛选器**和 **BTC / USDT / USDC 快捷标签**可以缩小路由列表。 + +跨链桥源资产选择器，列出 BTC、Base 上的 USDC 和以太坊上的 USDT，并带有搜索框 + +## 跨链转入（存入） + + + + 从仪表盘打开**跨链桥**。 + + + + 选择你要发送的源链和资产。使用网络筛选器或快捷标签可以更快找到它。 + + + + 选择你想在 Spark 上收到的资产：**BTC** 或 **USDB**。 + + + + 输入金额。扩展会获取报价，显示预期输出、费用和额度限制。 + + + + 跨链桥会显示源链上的存入地址（附二维码）。从你的外部钱包发送报价中的金额。 + + + + 随着存入交易确认、资金抵达 Spark，订单状态会持续更新。订单会被持久保存，因此即使你在跨链过程中关闭扩展，跟踪也会恢复。 + + + +跨链桥存入报价，在存入二维码上方显示发送金额、预计收到金额、以基点计的费用和有效期 + +跨链桥存入地址，包含二维码、可复制的地址、等待存入状态，以及粘贴交易哈希的输入框 + +## 跨链转出（提取） + +跨链提取从常规的**提取**流程开始： + + + + 粘贴目标链上的地址（例如 EVM 或 Solana 地址）。扩展会识别出哪些跨链路由可以抵达该地址。 + + + + 选择目标资产并输入金额。默认情况下，金额固定的是**你发送的数量**（You send），报价会显示预期输出。在符合条件的路由上，你可以切换到**你收到的数量**（You receive）模式，即固定接收方最终拿到的数量。 + + + + 核对目标地址、输出金额和费用，然后确认。扩展会从你的 Spark 账户付款，由跨链桥在目标链上交付。 + + + + 订单进度会被持久跟踪直至完成，扩展重启也不影响。 + + + +提取流程中识别出的跨链提取，显示目标网络、接收地址、接收代币、固定输出金额和费用 + +## 订单跟踪与恢复 + +跨链桥订单会作为会话保存在本地。如果订单进行中扩展被关闭或 service worker 重启，跨链桥界面会恢复待处理订单并继续跟踪。已完成和失败的订单会显示最终状态以及相关的交易引用。 + +正在处理的跨链桥订单，包含从处理中到已完成的六阶段进度列表，以及路由和订单 ID + +## 使用建议 + + + + 跨链转移不可撤销。确认前请反复检查目标地址和目标链。 + + + + 报价包含最小和最大金额。存入时发送报价范围之外的金额，可能导致订单延迟或资金卡住。 + + + + 重启后跟踪会自动恢复，但保持界面打开可以看到实时状态更新。 + + + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/dapp-connectivity.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/dapp-connectivity.mdx new file mode 100644 index 0000000..9c780bf --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/dapp-connectivity.mdx @@ -0,0 +1,203 @@ +--- +title: DApp 连接 +description: "用 WebLN、WebBTC 和 Nostr（NIP-07）提供方把 KaleidoSwap 扩展连接到受信任的 DApp：授权流程、权限管理与可用方法一览。" +--- + +## 概览 + +KaleidoSwap 扩展会把标准钱包提供方注入浏览器页面，DApp 在获得用户授权后即可调用钱包能力。它沿用与其他浏览器钱包（例如 Alby）相同的提供方约定，因此大多数现有的 WebLN、WebBTC 和 Nostr 应用无需为 KaleidoSwap 做任何专门集成即可使用。 + +扩展注入以下对象： + +- **`window.webln`** — 面向 Lightning 的 [WebLN](https://www.webln.dev/) 提供方（发票、支付、消息签名、keysend、LNURL）。 +- **`window.webbtc`** — 面向链上比特币的 WebBTC 提供方（地址、PSBT 签名、BIP-322 消息签名、广播）。 +- **`window.nostr`** — 完整的 [NIP-07](https://github.com/nostr-protocol/nips/blob/master/07.md) 提供方，用于 Nostr 事件签名与加密。 +- **`window.bitcoin`** — Bitcoin Wallet Standard 提供方（Unisat／OKX／Leather 风格），部分 DApp 会探测它来获取链上账户。 + +### 工作原理 + +1. KaleidoSwap 扩展的**内容脚本**被注入网页 +2. 内容脚本加载**注入脚本**，添加 `window.webln`、`window.webbtc`、`window.nostr` 和 `window.bitcoin` +3. DApp 调用这些提供方上的方法 +4. 请求被路由到 KaleidoSwap 扩展的**后台 service worker** +5. 敏感操作会触发确认或权限提示 + +### 提供方就绪事件 + +提供方安装完成后，注入脚本会派发就绪事件（同时提供带冒号和不带冒号两种写法，以兼容各类 SDK）： + +- `webln:ready` / `weblnReady` +- `webbtc:ready` / `webbtcReady` +- `nostr:ready` +- `bitcoin:ready` + +## WebLN 提供方 + +`window.webln` 遵循 WebLN 规范，可用于： + +- 请求节点信息 +- 创建闪电发票 +- 发送闪电支付 +- 签名和验证消息 +- 发送 keysend 支付 +- 处理 LNURL 请求 +- 读取余额详情 + +### 支持的方法 + +| 方法 | 说明 | +|--------|-------------| +| `enable()` | 连接 DApp 并为该来源请求授权 | +| `getInfo()` | 获取节点信息和支持的方法 | +| `sendPayment(paymentRequest)` | 支付 BOLT-11 发票 | +| `makeInvoice(args)` | 创建闪电发票 | +| `signMessage(message)` | 用节点密钥签名消息 | +| `verifyMessage(signature, message)` | 验证已签名的消息 | +| `keysend(args)` | 发送自发（keysend）支付 | +| `lnurl(input)` | 处理 LNURL 请求 | +| `getBalance()` | 获取钱包余额详情 | +| `request(method, params)` | 底层透传请求 | + +### 用法示例 + +```javascript +window.addEventListener('webln:ready', async () => { + await window.webln.enable(); + + const info = await window.webln.getInfo(); + + const { paymentRequest } = await window.webln.makeInvoice({ + amount: 1000, + defaultMemo: 'Coffee' + }); + + const { preimage } = await window.webln.sendPayment('lnbc...'); +}); +``` + +## WebBTC 提供方 + +`window.webbtc` 是链上比特币提供方，可以： + +- 返回接收地址 +- 签名并终结 PSBT +- 签名消息（BIP-322） +- 广播原始交易 +- 发送链上支付 + +### 支持的方法 + +| 方法 | 说明 | +|--------|-------------| +| `enable()` | 连接 DApp 并为该来源请求授权 | +| `getInfo()` | 获取节点／网络信息和支持的方法 | +| `getAddress()` | 获取链上接收地址 | +| `signPsbt(psbtHex)` | 签名 PSBT 中属于本钱包的输入 | +| `finalizePsbt(psbtHex)` | 把已签名的 PSBT 终结为可广播的 hex | +| `broadcastTransaction(txHex)` | 广播已签名的原始交易 | +| `signMessage(message, address?)` | 签名消息（BIP-322） | +| `sendPayment(paymentRequest)` | 支付 BIP-21 或 BOLT-11 请求 | +| `sendTransaction(address, amount)` | 发送链上支付 | + + +部分 DApp 会探测 `window.bitcoin`（Bitcoin Wallet Standard 提供方），替代或同时配合 `window.webbtc` 使用。它基于同一套钱包密钥暴露 `connect()`、`getAccounts()`、`getPublicKey()`、`signMessage()`、`signPsbt()`、`pushPsbt()` 和 `sendBitcoin()`。 + + +### PSBT 确认 + +批准 `signPsbt`、`finalizePsbt` 或 `pushPsbt` 绝不是盲签：确认提示会解码 PSBT，在你批准之前展示目标地址、金额和网络费用。如果无法从 PSBT 中解码出金额，提示会改为给出明确警告。 + +PSBT 签名确认界面，解码出交易总额、每个输出的目标地址和金额，以及网络费用 + +## Nostr 提供方（NIP-07） + +KaleidoSwap 扩展在 `window.nostr` 上注入完整的 **NIP-07** 提供方，Nostr 网页应用可以请求钱包公钥、签名事件，以及加密或解密私信。Nostr 身份由钱包助记词派生（若已设置，则使用导入的身份）。 + +### 支持的方法 + +| 方法 | 说明 | +|--------|-------------| +| `getPublicKey()` | 返回钱包的 Nostr 公钥（hex） | +| `signEvent(event)` | 签名一个 Nostr 事件 | +| `getRelays()` | 返回已配置的中继 | +| `signSchnorr(sigHash)` | 用 Nostr 密钥签名 32 字节哈希 | +| `nip04.encrypt(pubkey, plaintext)` / `nip04.decrypt(pubkey, ciphertext)` | NIP-04 加密 | +| `nip44.encrypt(pubkey, plaintext)` / `nip44.decrypt(pubkey, ciphertext)` | NIP-44 加密 | + +### 用法示例 + +```javascript +window.addEventListener('nostr:ready', async () => { + const pubkey = await window.nostr.getPublicKey(); + + const signed = await window.nostr.signEvent({ + kind: 1, + content: 'Hello from KaleidoSwap', + tags: [], + created_at: Math.floor(Date.now() / 1000) + }); +}); +``` + +## Nostr Connect（NIP-46） + +除了页面内的 NIP-07 签名，扩展还可以为支持 [NIP-46](https://github.com/nostr-protocol/nips/blob/master/46.md)（nsecBunker）的 Nostr 应用充当**远程签名器**。在**设置 > Nostr Connect**（Settings > Nostr Connect）中生成 `bunker://` 连接字符串，粘贴到客户端应用中，签名请求随后会通过 Nostr 中继传输，并在扩展中批准。活跃的 NIP-46 会话会出现在**已连接应用**（Connected Apps）中，可在那里查看和撤销。 + +Nostr Connect 远程签名界面，显示监听状态、生成的 bunker 连接字符串和撤销操作 + +## Nostr Wallet Connect（NWC） + +扩展也可以通过 **Nostr Wallet Connect** 把钱包暴露给外部应用：扫描配对二维码完成配对，再用**按金额生效的预算**限定它能做什么。通过 NWC 发起的 Zap 支付（NIP-57）会被校验，并与钱包交易记录关联。 + +## 权限提示与已连接应用 + +当已连接的站点发起敏感请求时，KaleidoSwap 扩展会要求用户批准或拒绝该操作。已连接的 Nostr 客户端默认采用「合理」(Reasonable) 授权级别（与其他 NIP-07 钱包相当）：已连接应用的常规低风险操作直接放行，而支付和其他敏感操作仍会弹出提示。 + +连接授权提示，显示发起请求的站点来源、它申请的访问权限，以及默认的「合理」授权级别和拒绝、允许两个操作 + +**设置 > 已连接应用**（Settings > Connected Apps）列出连接到钱包的每个站点和应用，并显示各自被授予的能力。你可以随时撤销单项能力，或彻底断开某个站点。 + +已连接应用界面，列出已连接的应用、Nostr Wallet Connect 会话，以及用于屏蔽站点的输入框 + + +批准之前务必看清 DApp 请求的内容。只批准来自你信任的站点的支付、发票、资产发送和签名请求。 + + +## Nostr 身份 + +KaleidoSwap 扩展从钱包助记词（或导入的身份）派生 Nostr 身份，并同时通过 `window.nostr` 暴露给网页，以及在扩展设置中展示。 + +### Nostr 密钥管理 + +你的 Nostr 密钥对在**设置 > Nostr 账户**（Settings > Nostr Account）中管理： + +- 查看公钥（`npub`） +- 钱包处于解锁状态时查看／复制会话私钥 +- 从钱包助记词重新派生身份 + +默认情况下，身份由助记词派生（NIP-06）。如果你已经有 Nostr 身份，可以在初始设置时或之后从设置中导入自己的密钥（`nsec1…` 或 64 位十六进制字符串）；它会被加密存储，并在所有原本使用派生身份的场景中生效。 + +## 浏览器授权流程 + +KaleidoSwap 扩展让 DApp 授权始终由用户驱动： + +1. 受信任的站点请求连接、支付、发票、资产或签名操作 +2. KaleidoSwap 扩展通过内容脚本和后台 service worker 转发请求 +3. 用户核对详情，批准或拒绝该操作 + +这样既保证钱包侧的操作始终显式确认，又允许 DApp 把 KaleidoSwap 扩展当作浏览器提供方使用。 + +## 安全注意事项 + +| 做法 | 说明 | +|----------|-------------| +| **核实站点** | 批准钱包连接前先检查 URL | +| **审阅请求** | 批准前读清发票、资产和签名的详细内容 | +| **用完即锁** | 使用完 DApp 后锁定 KaleidoSwap 扩展 | +| **控制暴露面** | 只连接受信任的站点 | + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx new file mode 100644 index 0000000..551aa96 --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/faq.mdx @@ -0,0 +1,105 @@ +--- +title: "KaleidoSwap 扩展常见问题" +sidebarTitle: "常见问题" +description: "关于 KaleidoSwap 扩展的常见问题：浏览器支持、多协议账户、可用资产、备份与恢复、密码，以及 DApp 连接方式。" +--- + +## 常见问题 + + + + 首个封闭测试面向基于 Chromium 的浏览器，例如 Google Chrome、Brave、Microsoft Edge 和 Opera，通过开发者模式加载私有测试版 zip 包安装。如果提供了 Firefox 构建，Firefox 支持会另行测试。Safari 暂不支持。 + + + + 受邀测试者会收到 KaleidoSwap 团队提供的专属下载链接，形式为 `https://kaleidoswap.com/dl?t=...`，该链接始终指向最新的测试版构建。扩展尚未上架浏览器商店，源码仓库也尚未公开，因此封闭测试者只应安装自己专属下载链接提供的 zip 包。 + + + + **不需要。** Spark、Arkade、Liquid 和无节点 RGB-L1 账户全部由 KaleidoSwap 扩展的助记词派生，无需任何节点即可运行——包括 Bitcoin L1 上的 RGB 资产，它们完全通过 WebAssembly 在扩展内运行。 + + 只有当你想使用 RGB **闪电通道**和基于做市方的 RGB 交换时，才需要 RGB Lightning Node（RLN）。要使用 RLN 功能，你可以连接： + - **本地节点**：使用 [KaleidoSwap 桌面应用](/cn/desktop-app/wallet/creating-wallet)，或在本机运行 [RGB Lightning Node](https://github.com/RGB-Tools/rgb-lightning-node)。 + - **远程节点**：通过 URL 或 **Nostr Wallet Connect** 访问。 + + 请注意，无节点 RGB-L1 账户和 RLN 账户是 RGB 资产的两种互斥后端。 + + + + **不是。** KaleidoSwap 扩展把钱包助记词加密后保存在本地，并由它派生各协议账户。若选择使用 RLN，扩展会连接到你自行配置的节点。 + + + + **不需要。** 交易场所是可选的。没有交易场所时： + - 发送、接收和余额功能正常可用 + - 只有**交换**功能不可用 + + + + KaleidoSwap 扩展支持： + - **BTC**，覆盖 Spark、Arkade、Liquid（L-BTC）、Bitcoin L1，以及已连接时的 RLN Lightning + - Spark 账户上可用时的 **Spark 原生资产** + - Arkade 账户上可用时的 **Arkade 原生资产** + - Liquid 账户上的 **Liquid 资产**，例如 USDt + - Bitcoin L1 上的 **RGB 资产**，通过无节点 RGB-L1 账户，或在连接 RGB Lightning Node 时通过 Lightning + + + + 进入**设置 > 备份钱包**（Settings > Backup Wallet），重新输入密码后即可显示并复制助记词。同一界面也提供无节点账户的 RGB 备份指引。 + + 请分别离线保存以下内容： + - 用于 Spark、Arkade、Liquid、RGB-L1 和派生 Nostr 身份的 **KaleidoSwap 扩展助记词** + - 如果你使用 RGB Lightning Node，还需保存较新的 **RGB 节点备份文件** + - 如果节点由你另行管理，还需保存 **RLN 节点助记词或节点备份材料** + + 无节点 **RGB-L1 账户会自动备份**：在发送、接收和 UTXO 变化等钱包活动之后，它会备份到加密云端（VSS）。你也可以在备份界面手动导出本地加密备份文件。重新导入钱包时，初始设置流程会询问是否从云端备份恢复——只有在你明确同意后才会执行恢复。 + + + + KaleidoSwap 扩展无法帮你找回密码。如果忘记了密码，你需要： + 1. 卸载并重新安装扩展 + 2. 导入助记词 + 3. 设置新密码 + 4. 重新连接 RGB Lightning Node 等可选服务 + + Spark、Arkade、Liquid 和派生的 Nostr 身份都可以从助记词恢复，无节点 RGB-L1 的状态可以在初始设置流程中从云端（VSS）备份恢复。RGB Lightning Node 的状态必须用该节点自己的备份材料恢复。 + + + + KaleidoSwap 扩展管理 Spark、Arkade、Liquid、RGB-L1 以及可选的 RLN 账户。对于 RLN，同一时间只能连接一个节点接口端点（直连 URL 或 NWC）。 + + + + KaleidoSwap 扩展在一段时间无操作后会自动锁定（默认 10 分钟）。锁定后需要输入密码才能解锁。超时时间可在**设置 > 安全**（Settings > Security）中配置。 + + + + **可以。** 受信任的 DApp 可以通过 KaleidoSwap 扩展的浏览器提供方请求钱包操作。批准之前请逐一核对每个连接、支付、资产或签名请求。 + + + +## 获取帮助 + +如果遇到的是报错而不是疑问，请查看[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。其他情况请从下面的渠道中选择一个反馈问题，并附上： + +1. 浏览器名称和版本 +2. KaleidoSwap 扩展版本（Settings > About） +3. 节点类型和版本 +4. 复现步骤 +5. 错误信息或截图 +6. 控制台日志（右键点击扩展弹出窗口 > Inspect > Console） + + + + 向社群提问。 + + + 紧急问题的直接支持渠道。 + + + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx new file mode 100644 index 0000000..f1d0456 --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/getting-started.mdx @@ -0,0 +1,151 @@ +--- +title: "KaleidoSwap 扩展：快速开始" +sidebarTitle: "快速开始" +description: "在 KaleidoSwap 扩展中创建或导入钱包、备份助记词、选择 RGB 后端，几分钟内配置好 Spark、Arkade 和 Liquid 多协议账户并开始使用。" +--- + +## 初始设置 + +首次打开 KaleidoSwap 扩展时，初始设置流程会引导你完成基础配置。 + +KaleidoSwap 扩展欢迎界面 + + + + 选择**创建新钱包**（Create New Wallet）或**导入已有钱包**（Import Existing Wallet）。 + + + + 设置一个安全密码来保护钱包。这个密码用于： + - 在扩展自动锁定后解锁 + - 加密本地存储的钱包数据 + + 请选择一个强密码并记住它（密码无法找回）。 + + + + 新钱包会生成 12 词助记词。这组 BIP39 助记词控制 Spark、Arkade、Liquid 和 RGB-L1 账户，以及扩展派生的默认 Nostr 身份。日后恢复钱包始终从这组助记词开始。 + + + + 你可以选择注册一个 passkey（WebAuthn），用设备的生物识别或安全密钥解锁钱包，而不必输入密码。也可以先跳过，之后在设置（Settings）中再添加。 + + + + 新钱包会获得一个从助记词派生的 Nostr 身份（NIP-06）。如果你已经有 Nostr 身份，可以在这一步导入已有密钥（`nsec1…` 或 64 位十六进制字符串），密钥会加密存储。跳过则保留派生出的身份。 + + + + 选择 RGB 的连接方式： + - **无节点（推荐）** - 完全在你的设备上运行的自主保管 RGB 资产和 Bitcoin L1 上的 BTC，无需运行节点。 + - **RLN 节点** - 连接你自己的 RGB Lightning Node，在 RGB 之上增加闪电通道和基于做市方的 RGB 交换。实验性功能，仅支持测试网络。 + + 之后可以在设置中更改。两种后端互斥。 + + + + 使用无节点 RGB 导入已有钱包时，扩展会询问是否从云端（VSS）备份恢复 RGB 状态。未经你在这一步明确同意，不会恢复任何内容。 + + + + 进入钱包。扩展会以 Spark、Arkade、Liquid 和 RGB 账户启动，连接节点后再加入 RLN 相关功能。 + + + +KaleidoSwap 扩展设置密码步骤 + + +恢复钱包时，请始终使用 **BIP39 助记词**，而不是 Nostr 密钥。导入的 Nostr 密钥只会替换 Nostr 身份，并不控制资金。 + + +发现云端备份的提示，询问是否从 VSS 备份服务器恢复加密的 RGB 状态，并提供「暂时跳过」选项 + +## RGB 账户 + +### 无节点 RGB（RGB-L1） + +默认的 RGB 后端完全在扩展内部（WebAssembly）运行 Bitcoin L1 上的 RGB，无需节点。它默认通过 Esplora 索引器连接主网（已提供默认端点，你也可以在**设置 > RGB-L1**（Settings > RGB-L1）中填入自己的），自动创建盲化接收发票，替你管理 UTXO，并把 RGB 状态备份到加密云端（VSS）和本地文件。 + +### RGB Lightning Node + +RLN 是可选的实验性功能。如果你需要 RGB 闪电通道、通过 Lightning 传输的 RGB 发票，或基于做市方的 RGB 交换，可以连接它。 + +KaleidoSwap 扩展中的 RLN 可选启用界面 + +扩展可以通过两种传输方式连接你的 RLN： + +- **直连**（Direct）- 填入 **RLN Node URL**（节点接口端点，例如 `http://localhost:3001`），以及节点要求时的可选 **Biscuit / JWT token**。 +- **Nostr Wallet Connect（NWC）** - 粘贴 `nostr+walletconnect://` 连接字符串（例如来自 KaleidoSwap 桌面应用）。你的节点保持远程，只有签名后的请求经中继传输。 + +两种传输方式共用同一个 RGB 交换做市方 URL。 + +KaleidoSwap 扩展的 RLN 连接表单 + + +在初始设置中，RGB Lightning 被标注为面向测试网络的实验性功能。你可以先跳过，之后在设置中连接。连接 RLN 节点会替换掉无节点的 RGB-L1 后端。 + + +## 仪表盘概览 + +设置完成后，仪表盘会显示各个已连接协议的账户状态和资产。 + +KaleidoSwap 仪表盘 + +### 账户状态 + +仪表盘会展示 Spark、Arkade、Liquid 和 RGB 账户的状态。每个账户标签会显示它处于就绪、离线、可选还是仍在同步。如果某个已连接账户停止响应（例如余额请求持续超时），对应标签会变为琥珀色并显示**无响应**（Not responding）状态，同时仪表盘会出现一条可关闭的横幅，附带**重试**（Retry）操作。 + +### 资产筛选 + +使用资产和网络筛选器可以聚焦于： + +- 所有协议中的 BTC +- Spark 资产 +- Arkade 资产 +- Liquid 资产（L-BTC 以及 USDt 等已发行资产） +- RGB 资产（无节点或通过 RLN） +- Bitcoin L1、Lightning、Spark、Arkade 和 Liquid 各网络分片 + +不同后端中代码相同的资产会合并为仪表盘上的同一行，你也可以从列表中隐藏单个资产。 + +### 操作 + +| 操作 | 说明 | +|--------|-------------| +| **存入**（Deposit） | 为所选资产和账户路由生成接收地址或发票 | +| **提取**（Withdraw） | 通过最合适的兼容路由发送到已识别的目标类型 | +| **交换**（Swap） | 打开扩展内的交换界面 | +| **跨链**（Bridge） | 在 Spark 与外部链之间转移资金 | + +## 锁定与解锁 + +### 自动锁定 + +KaleidoSwap 扩展会在一段时间无操作后自动锁定。锁定后，扩展需要你的密码（或已注册的 passkey）才会再次在内存中解密助记词。 + +「欢迎回来」锁定界面，主操作为使用 Passkey 解锁，并提供使用密码解锁的备选方式 + +### 解锁 + +扩展处于锁定状态时，你会看到上图所示的**欢迎回来**（Welcome Back）界面。 + +- **使用 passkey** - 如果已注册，点击**使用 Passkey 解锁**（Unlock with Passkey），并用设备的生物识别或安全密钥确认 +- **使用密码** - 输入密码后选择**解锁**（Unlock） + +如果忘记密码，KaleidoSwap 无法帮你找回 - 恢复步骤请参见[故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。 + +### 手动锁定 + +使用**设置 > 锁定钱包**（Settings > Lock Wallet）可立即锁定。 + +### 修改锁定超时时间 + +进入**设置 > 安全**（Settings > Security）调整自动锁定超时时间（从 1 分钟到 1 小时，或永不锁定）。比特币单位显示是设置主页面上的一个内嵌选择器。 + +KaleidoSwap 扩展就绪界面 + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/installation.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/installation.mdx new file mode 100644 index 0000000..8e3e742 --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/installation.mdx @@ -0,0 +1,141 @@ +--- +title: "KaleidoSwap 扩展：安装" +sidebarTitle: "安装" +description: "在浏览器中安装 KaleidoSwap 多协议比特币钱包扩展：封闭测试申请、开发者模式手动加载、校验下载文件，以及后续版本的更新方法。" +--- + +## 浏览器要求 + +KaleidoSwap 扩展基于 Manifest V3 构建。首个封闭测试版以 Chromium 兼容的 zip 压缩包形式分发，需通过开发者模式安装。 + +| 浏览器 | 是否支持 | +|---------|-----------| +| **Google Chrome** | 封闭测试目标浏览器 | +| **Brave** | 封闭测试目标浏览器 | +| **Edge** | 封闭测试目标浏览器 | +| **Opera** | 封闭测试目标浏览器 | +| **Firefox** | 除非提供 Firefox 构建版本，否则不在首个封闭测试范围内 | +| **Safari** | 暂不支持 | + +## 安装 + +### 封闭测试 zip 包（开发者模式） + +KaleidoSwap 扩展的首个版本是仅限邀请的封闭测试。目前还没有浏览器商店上架，扩展源码仓库也尚未公开。受邀测试者会从 KaleidoSwap 团队收到一个专属下载链接，形如 `https://kaleidoswap.com/dl?t=...`。该链接始终提供最新的测试构建，请保留这封邮件——每次更新都用同一个链接。 + + +只安装通过 KaleidoSwap 官方邀请或支持渠道分享的测试压缩包。不要安装来源未经验证的转发压缩包。你的下载链接是专属于你的，请当作私密信息对待。 + + + + + 打开测试邀请中的下载链接，它会以 zip 压缩包形式提供当前构建。 + + + + 同一个链接上还提供了公布的校验和以及维护者的分离签名： + + ```bash + # 当前构建的 SHA-256 校验和 + curl -s "https://kaleidoswap.com/dl?t=YOUR_TOKEN&file=sha256" + ``` + + 将其与你下载的压缩包对比： + + ```bash + shasum -a 256 kaleidoswap-extension-beta-latest.zip + ``` + + 如果还要校验签名，使用 `&file=asc` 获取签名文件，并用 KaleidoSwap 发布签名密钥（`696F19C9DA0ADBE8B38E5346E007BFF05941433B`）验证： + + ```bash + curl -s "https://kaleidoswap.com/dl?t=YOUR_TOKEN&file=asc" -o kaleidoswap-extension.zip.asc + gpg --verify kaleidoswap-extension.zip.asc kaleidoswap-extension-beta-latest.zip + ``` + + + + 把压缩包解压到本机一个固定的文件夹中。扩展安装期间请不要移动这个文件夹，因为浏览器会从该文件夹加载扩展。 + + + + 在 Chromium 系浏览器中访问 `chrome://extensions`。 + + + + 打开右上角的**开发者模式**（Developer mode）开关。 + + + + 点击**加载已解压的扩展程序**（Load unpacked），选择包含 `manifest.json` 的解压文件夹。 + + + + 把 KaleidoSwap 图标固定到工具栏，方便随时打开。 + + + +## 暂不可用的渠道 + +| 渠道 | 状态 | +|---------|--------| +| **浏览器商店** | 首个封闭测试期间不可用 | +| **源码构建** | 扩展源码开放之前不可用 | + + +封闭测试者只应安装自己专属下载链接提供的 zip 包。扩展仓库公开后，我们会补充源码构建说明。 + + +## 首次启动 + +安装完成后，点击工具栏中的 KaleidoSwap 图标，钱包会在浏览器**侧边栏**（side panel）中打开（在不支持侧边栏 API 的浏览器上，会退回到工具栏弹出窗口）。首次启动时，扩展会引导你完成**初始设置流程**： + +KaleidoSwap 扩展首次启动界面 + +1. **欢迎界面** - 创建新钱包或导入已有助记词 +2. **设置密码** - 创建一个安全密码来保护本地钱包 +3. **备份助记词** - 保存控制 Spark、Arkade 和 Nostr 身份的助记词 +4. **可选的 RLN 设置** - 连接 RGB Lightning Node，或跳过并稍后再连接 +5. **完成** - 进入钱包仪表盘 + +更多信息请参见[快速开始](/cn/extensions/kaleidoswap-extension/getting-started)。 + +## 权限 + +KaleidoSwap 扩展会申请以下 Chrome 扩展权限： + +| 权限 | 用途 | +|-----------|---------| +| **Storage** | 在本地存储加密的钱包数据、偏好设置和账户配置 | +| **Tabs** | 协调审批和确认窗口 | +| **Alarms** | 运行计划中的钱包／会话任务 | +| **Notifications** | 在支持的情况下就钱包事件通知用户 | +| **Clipboard Read** | 读取粘贴的发票、地址和连接字符串 | +| **Side Panel** | 在浏览器侧边栏中打开钱包 | +| **Declarative Net Request（含主机访问）** | 为钱包自身发往已授权主机的 API 调用调整请求头 | + +manifest 中还为钱包实际访问的接口端点声明了 `host_permissions`：KaleidoSwap 服务、区块浏览器与索引器、RGB proxy、Spark/Flashnet、Arkade 以及价格 API。 + + +KaleidoSwap 扩展把加密后的助记词存储在 `chrome.storage.local` 中。只有你主动连接的账户和服务才会产生网络请求。 + + +## 更新 + +封闭测试构建不会通过浏览器商店自动更新。有新测试版时，重新打开你的下载链接——它始终提供当前构建——解压后回到 `chrome://extensions`，在 KaleidoSwap 扩展卡片上点击**重新加载**（Reload）。如果你把新构建解压到了另一个文件夹，请先移除旧的已解压扩展，再加载新文件夹。 + +由于测试构建使用固定的扩展 ID（`mmldlmkphefjjbpbajnhnkbiahiabiog`），你的账户、余额和设置会在更新后保留。无论如何，请把助记词放在手边。 + +## 卸载 + +要移除 KaleidoSwap 扩展，请按照浏览器提供的说明操作。 + + +卸载扩展会删除所有本地存储的钱包数据。卸载前请确认已备份助记词，以及所有 RGB Lightning Node 相关的备份材料。 + + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/swaps.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/swaps.mdx new file mode 100644 index 0000000..1ff5ac3 --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/swaps.mdx @@ -0,0 +1,128 @@ +--- +title: "交换" +sidebarTitle: "交换" +description: "在 KaleidoSwap 扩展中直接完成资产交换：获取报价、核对费用与有效期、执行原子交换，并跨多个受支持的比特币分层网络跟踪进度。" +--- + +## 概览 + +KaleidoSwap 扩展内置了交换界面。当可选的 RGB Lightning Node 账户已连接时，它可以使用 KaleidoSwap 做市方交易对；当 Spark 池可用时，它可以使用 Spark/Flashnet 路由。 + +KaleidoSwap 交换界面 + + +交换是在你的钱包内部把一种资产换成另一种。要在 Spark 与外部链（EVM 网络、Solana 等）之间转移资金，请改用[跨链桥](/cn/extensions/kaleidoswap-extension/bridge)。 + + +## 前置条件 + +开始交换前： +1. 至少要有一个可用的兼容交易场所 +2. 相关账户必须已连接 +3. 源资产余额必须足以覆盖交换金额和网络费用 + +金额输入受所选源资产的**可用**余额限制，因此你无法对超出钱包实际可发送金额的数量询价。 + +## 交换流程 + + + + 在仪表盘的操作区点击**交换**（Swap）按钮。 + + + + 选择**支出**（From）和**获得**（To）资产： + - **支出** - 你想卖出的资产（例如 BTC） + - **获得** - 你想收到的资产 + + + + 输入想要交换的金额。扩展会从所选交易场所获取报价，其中包含： + - 汇率 + - 输出金额 + - 费用 + - 有效期 + + + + 交换预览界面会显示： + - 支出资产和金额 + - 获得资产和金额 + - 汇率 + - 费用明细 + - 总成本 + + + + 在报价过期前确认交换。 + + + + 交换状态界面会显示一个三步进度跟踪器： + - 请求中 + - 原子交换 + - 收尾中 + + 随后给出成功或失败的结果。 + + + +交换核对界面，在「确认交换」按钮上方显示支付与收到金额、提供方、汇率、费用、报价 ID 和有效期 + +## 实时报价 + +输入金额后，KaleidoSwap 扩展会从当前交易场所获取报价： + +| 报价字段 | 说明 | +|------------|-------------| +| **汇率**（Rate） | 两种资产之间的兑换比率 | +| **输出金额**（Output Amount） | 你将收到多少 | +| **费用**（Fee） | 协议费用和网络费用 | +| **有效期**（Expiry） | 报价的有效时长 | +| **交易场所**（Venue） | 路由提供方，例如 KaleidoSwap 做市方或 Flashnet | + +你调整金额时，报价会实时更新。 + +### 滑点保护 + +Flashnet 交换内置了 5% 的最大滑点限制：最小输出金额由该限制推导得出，一旦汇率变差，交换会直接失败而不会成交。滑点不可由用户配置。 + +## 交换状态 + +确认后，状态界面会通过三个步骤跟踪交换进度： + +| 步骤 | 说明 | +|------|-------------| +| **请求中**（Requesting） | 正在创建交换订单 | +| **原子交换**（Atomic Swap） | 交换正在原子性地执行 | +| **收尾中**（Completing） | 交换正在完成收尾 | + +交换结束后，界面会显示成功结果。如果某个步骤失败，则会显示带有失败细节的错误信息。 + +交换进行中，三步进度跟踪器显示请求中、原子交换和收尾中，并展示正在交换的交易对 + + +如果没有可用的兼容交易场所或交易对，KaleidoSwap 扩展会显示空状态而不是报价。存入、提取、余额和设置等钱包功能仍然可用。 + + +## 使用建议 + + + + 确保源资产的数量足以同时覆盖交换金额和各项费用。 + + + + 报价会在很短时间后过期。请及时核对并确认，以免需要重新询价。 + + + + 如果交换失败，状态界面会显示带有失败细节的错误信息。 + + + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx new file mode 100644 index 0000000..4ca9890 --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/troubleshooting.mdx @@ -0,0 +1,130 @@ +--- +title: "KaleidoSwap 扩展故障排查" +sidebarTitle: "故障排查" +description: "解决 KaleidoSwap 扩展中的节点连接、支付和 DApp 提供方问题，并说明向支持团队反馈缺陷时应该附上哪些信息。" +--- + +这里汇总了 KaleidoSwap 扩展用户最常遇到的问题及其解决办法。如需覆盖 KaleidoSwap 全部产品的问题排查，请参见[完整故障排查指南](/cn/whats-kaleidoswap/troubleshooting)。 + +## 连接问题 + + + + **现象：** 连接失败或显示「已断开」(Disconnected) + + **解决办法：** + 1. 确认 **节点 URL** 填写正确 + 2. 检查节点是否**正在运行且可访问** + 3. 使用本地节点时，确认它运行在预期端口上 + 4. 使用远程节点时，检查网络／防火墙设置 + 5. 使用 Biscuit／认证令牌时，确认**令牌仍然有效** + 6. 尝试在 Settings > RGB 中断开再重新连接 + + + + **现象：** 交换功能不可用，或显示连接错误 + + **解决办法：** + 1. 检查相关账户是否已连接 + 2. 使用 KaleidoSwap 做市方交易对时，确认 RLN 状态 + 3. 使用 Flashnet 路由时，确认 Spark 是否可用 + 4. 尝试刷新交换界面 + + + + **现象：** DApp 无法把 KaleidoSwap 扩展识别为钱包 + + **解决办法：** + 1. 确认 KaleidoSwap 扩展**已安装并已解锁** + 2. 刷新网页 + 3. 检查扩展是否对该站点**已启用** + 4. 确认 DApp 使用的是标准提供方——KaleidoSwap 扩展注入 `window.webln`（WebLN）、`window.webbtc`、`window.nostr`（NIP-07）和 `window.bitcoin` + 5. 有些应用会等待就绪事件——扩展会派发 `webln:ready`、`webbtc:ready`、`nostr:ready` 和 `bitcoin:ready` + + + +## 支付问题 + + + + **现象：** 发送支付时报错 + + **解决办法：** + 1. 检查**余额**是否充足 + 2. 确认**目标地址**填写正确 + 3. Lightning 支付需要确认到目标存在可用**路由** + 4. 检查节点是否**在线且已同步** + 5. 稍等一会儿再重试 + + + + **现象：** 无法生成接收发票 + + **解决办法：** + 1. 检查**节点连接** + 2. 确认节点具备**入向流动性**（Lightning 场景） + 3. 尝试生成其他类型（用链上代替 Lightning） + 4. 重启扩展后重试 + + + +## 扩展问题 + + + + **现象：** 点击图标没有反应，或弹出窗口空白 + + **解决办法：** + 1. 打开 `chrome://extensions`，检查 KaleidoSwap 扩展是否**已启用** + 2. 尝试**先禁用再重新启用**扩展 + 3. 清理浏览器缓存 + 4. 重启浏览器 + 5. 手动安装的版本可以尝试**重新加载**扩展 + + + + **现象：** 无法解锁扩展 + + **解决办法：** + 1. KaleidoSwap 扩展无法找回密码 + 2. **卸载**扩展并**重新安装** + 3. 导入助记词 + 4. 设置新密码，并重新连接可选服务 + + + + **现象：** 显示的余额是旧数据 + + **解决办法：** + 1. 检查**节点连接**状态 + 2. 在仪表盘上下拉**刷新** + 3. 关闭扩展弹出窗口再重新打开 + 4. 确认节点**已同步** + + + +## 获取帮助 + +如果是疑问而不是报错，请查看[常见问题](/cn/extensions/kaleidoswap-extension/faq)。其他情况请从下面的渠道中选择一个反馈问题，并附上： + +1. 浏览器名称和版本 +2. KaleidoSwap 扩展版本（Settings > About） +3. 节点类型和版本 +4. 复现步骤 +5. 错误信息或截图 +6. 控制台日志（右键点击扩展弹出窗口 > Inspect > Console） + + + + 向社群提问。 + + + 紧急问题的直接支持渠道。 + + + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/extensions/kaleidoswap-extension/wallet-features.mdx b/mintlify-docs/cn/extensions/kaleidoswap-extension/wallet-features.mdx new file mode 100644 index 0000000..8d351bf --- /dev/null +++ b/mintlify-docs/cn/extensions/kaleidoswap-extension/wallet-features.mdx @@ -0,0 +1,257 @@ +--- +title: "钱包" +sidebarTitle: "钱包" +description: "在 KaleidoSwap 扩展中管理多协议账户、资产、存入、提取和交易记录——一个跑在浏览器里的完整比特币分层钱包，覆盖 Spark、Arkade、Liquid 和 RGB。" +--- + +## 账户 + +KaleidoSwap 扩展从同一组助记词派生多个协议账户： + +| 账户 | 持有内容 | 说明 | +|---------|---------------|-------| +| **Spark** | Spark BTC、Spark 原生资产、Lightning 收发 | 同时支撑 Flashnet 交换和跨链桥 | +| **Arkade** | Arkade BTC 和 Arkade 原生资产 | 进出通道（boarding/offboarding）和 VTXO 生命周期；可选轮换地址（HD）模式 | +| **Liquid** | L-BTC 以及 USDt 等 Liquid 资产 | 无节点、自主保管；默认主网 | +| **RGB-L1** | Bitcoin L1 上的 RGB 资产和 BTC | 无节点，运行于 WebAssembly；默认主网 | +| **RGB Lightning（RLN）** | 通过闪电通道流转的 RGB 资产 | 可选、实验性；连接后会替换 RGB-L1 后端 | + +## 资产管理 + +KaleidoSwap 仪表盘 + +### 查看余额 + +KaleidoSwap 仪表盘会显示你的全部资产： + +- **BTC 余额**，覆盖 Spark、Arkade、Liquid、Bitcoin L1，以及已连接时的 RLN Lightning +- 来自 Spark 账户的 **Spark 资产** +- 来自 Arkade 账户的 **Arkade 资产** +- 来自 Liquid 账户的 **Liquid 资产** +- 来自无节点 RGB-L1 账户、或已连接时来自 RLN 的 **RGB 资产** +- **协议和网络筛选器**，用于聚焦单一后端或某个网络分片 + +不同后端中代码相同的资产会合并为仪表盘上的同一行，展开后可查看各网络的余额明细。 + +### 隐藏资产 + +在资产管理视图中，你可以隐藏不想显示在仪表盘上的资产。隐藏的资产余额不受影响，只是从列表中移除，直到你取消隐藏。 + +### 资产详情 + +点击任意资产可查看详情： + +| 字段 | 说明 | +|-------|-------------| +| **代码**（Ticker） | 资产简称（例如 USDT） | +| **名称**（Name） | 资产全称 | +| **精度**（Precision） | 小数位数 | +| **账户**（Account） | 持有该资产的协议账户 | +| **可用余额**（Spendable Balance） | 所选路由可动用的金额 | +| **网络标签**（Network Badges） | 该资产可用的位置，例如 Spark、Arkade、Liquid、RGB-L1 或 RGB-LN | + +RGB 资产的详情页，显示资产 ID、代码、精度、账户、协议、分层，以及链上与 Lightning 余额对比 + +## 发送支付 + +KaleidoSwap 扩展会根据你在目标字段中粘贴或输入的内容，自动识别支付类型。 + +### 支持的目标格式 + +| 格式 | 识别为 | 示例 | +|--------|------------|---------| +| **BOLT11 发票** | Lightning 支付 | `lnbc1...` | +| **Lightning Address** | Lightning 支付 | `name@example.com` | +| **LNURL-pay** | Lightning 支付 | `lnurl1...` | +| **RGB 发票** | RGB 资产转移 | `rgb:...` | +| **比特币地址** | 链上支付 | `bc1q...`、`3...`、`1...` | +| **Liquid 地址／URI** | Liquid 转移 | `lq1...`、`liquidnetwork:...` | +| **Spark 地址** | Spark 转移 | Spark 地址字符串 | +| **Arkade 路由** | Arkade 转移或离场路由 | 兼容 Arkade 的目标 | + +### 发送流程 + + + + 粘贴或输入目标地址、发票或公钥。KaleidoSwap 扩展会自动识别支付类型。 + + + + 对于地址和 keysend，请输入以聪或 BTC 计的金额。对于发票，金额会从发票中自动填入。**最大**（Max）会填入可用余额，并在链上发送时预留网络费用，确保交易能够真正广播。 + + + + 核对支付详情： + - 目标 + - 金额 + - 所选路由／账户 + - 可用时显示的费用或路由提示 + + + + 点击**发送**（Send）执行支付。状态页面会显示结果。 + + + +发送界面，已识别出链上目标地址，显示以聪计的金额、费率选项，以及在 Spark 和 Arkade 之间的建议路由 + +## 接收支付 + +根据所选资产和已连接的账户，生成发票和地址以接收 Spark、Arkade、Liquid、Bitcoin L1、Lightning 和 RGB 上支持的资产。 + +KaleidoSwap 存入流程 + +### 接收标签页 + +可用的接收方式取决于所选资产和已连接的账户： + +| 路由 | 生成内容 | +|-------|-------------------| +| **Spark** | Spark 地址或 Spark Lightning 发票 | +| **Arkade** | Arkade 地址、入场地址或兼容的接收路由 | +| **Liquid** | 用于 L-BTC 或已发行资产的 Liquid 地址 | +| **Bitcoin L1** | 用于链上接收的比特币地址 | +| **Lightning** | 所选账户支持时生成 BOLT11 发票 | +| **RGB** | 盲化 RGB 发票（无节点），或 RLN 已连接时的 RGB 闪电发票 | + +### 接收流程 + + + + 选择 BTC 或其他受支持的资产。 + + + + 选择一个可用的账户路由，例如 Spark、Arkade、Liquid、Bitcoin L1、Lightning 或 RGB。 + + + + 创建发票或地址。界面会同时显示二维码和文本内容。 + + + + - **复制**（Copy）发票／地址到剪贴板 + - **显示二维码**（Show QR）供付款方扫描 + - 过期的闪电发票会被**标记**出来，并可重新生成 + + + +接收 BTC 的界面，包含二维码、RLN、Spark、Arkade 和 Liquid 的目标账户标签页，以及生成的 Arkade 地址和链上入场地址 + +## 存入与提取 + +### 存入 + +把 BTC 或受支持的资产存入所选账户： + +1. 在仪表盘上点击**存入**（Deposit） +2. 选择资产和路由 +3. 生成地址或发票 +4. 从外部钱包或服务发送资金 + +### 提取 + +提取是从所选账户发送到已识别的目标： + +1. 在仪表盘上点击**提取**（Withdraw） +2. 粘贴比特币地址、闪电发票、Lightning Address、LNURL、RGB 发票、Liquid 地址或 `liquidnetwork:` URI、Spark 地址，或 Arkade 目标 +3. 输入金额 +4. 核对建议路由并确认 + +提取界面，列出它接受的全部目标格式：Lightning、Bitcoin、Spark、Liquid、Arkade、RGB，以及跨链 USDC 或 USDT + +从 Spark 提取到外部链（EVM 网络、Solana 等）的方式，请参见[跨链桥](/cn/extensions/kaleidoswap-extension/bridge)。 + +## 交易记录 + +在**记录**（Activity）标签页中查看你的全部交易： + +### 交易列表 + +- 列出所有已连接账户的近期交易；各数据源并发加载并渐进渲染 +- 每条记录显示：类型、金额、状态、承载网络和时间戳 +- 可按交易类型或状态筛选 + +记录标签页列出已接收的交易及其金额和时间戳，可按全部、链上或 Lightning 筛选 + +### 交易详情 + +点击任意交易可查看： +- 完整交易详情 +- 交易 ID +- 金额和费用 +- 承载网络和状态 +- 时间戳 + +展开后的交易详情，显示支付哈希、日期、承载网络和已完成状态 + +## 设置 + +通过齿轮图标或底部导航进入设置。 + +KaleidoSwap 设置界面 + +### 账户 + +- **Spark** - 网络选择、SDK 详情和连接状态 +- **Arkade** - 网络选择、VTXO 设置、入场流程、生命周期设置，以及可选的轮换地址（HD）模式（支持通过 gap scan 恢复） +- **Liquid** - 网络选择以及 Esplora/waterfalls 同步接口端点（已提供一个高速默认端点，你也可以填入自己的） +- **RGB-L1** - 网络选择，以及无节点账户使用的 Esplora 索引器和 RGB proxy 接口端点 +- **RGB & Lightning** - 可选的 RLN 账户（直连 URL 或 NWC），可在实验性设置中启用 + +设置中的账户部分，Spark、Arkade、RGB 和 Liquid 均显示为已连接状态 + +### KaleidoSwap 用户名 + +你可以在设置中申领一个 **Lightning Address 用户名**（`yourname@kaleidoswap.me`）。输入时会实时检查可用性，申领后它会关联到你的钱包以接收闪电支付，并在你恢复钱包时自动重新关联。 + +申领地址界面，包含名称输入框、kaleidoswap.me 后缀和实时可用性检查 + +### Nostr + +- **Nostr 账户**（Nostr Account） - 查看公钥（npub）、在可用时查看／导出会话私钥，以及重新派生或导入身份 +- **已连接应用**（Connected Apps） - 查看连接到钱包的每个网站和应用，并可逐项撤销权限 +- **Nostr Connect（NIP-46）** - 生成 `bunker://` 连接字符串，让外部 Nostr 应用远程请求签名 +- **Nostr Wallet Connect** - 通过二维码以 NWC 方式配对外部应用，并设置带金额上限的预算 + + +切勿分享你的 Nostr 私钥（nsec）。任何拿到这个密钥的人都能签名事件并以你的身份行事。 + + +### 安全 + +- **修改密码**（Change Password） - 更新钱包密码 +- **Passkey 登录**（Passkey Login） - 注册或移除用于解锁钱包的 passkey（WebAuthn） +- **自动锁定超时**（Auto-lock Timeout） - 设置无操作超时时间，从 1 分钟到 1 小时，或永不锁定 +- **备份钱包**（Backup Wallet） - 确认密码后显示助记词，并管理 RGB 备份（无节点账户的加密 VSS 云备份和本地备份文件，或 RLN 的 RGB 节点备份归档） + +备份钱包界面，解密助记词前要求输入密码，并附带警告和备份覆盖范围的说明 + +### 应用 + +显示相关的偏好设置是设置主页面上的内嵌选择器： + +| 设置项 | 选项 | +|---------|---------| +| **比特币单位**（Bitcoin Unit） | 聪、BTC，或仅 ₿ | +| **法币**（Fiat Currency） | USD、EUR、GBP、JPY、CHF、CAD、CNY、KRW | +| **语言**（Language） | 英语、西班牙语、法语、德语、葡萄牙语、日语、意大利语、韩语、中文 | + +自动锁定超时时间位于**设置 > 安全**（Settings > Security）下。 + +### 全标签页视图 + +钱包通常在浏览器侧边栏（或工具栏弹出窗口）中打开。如果需要更大的操作空间，可使用**设置 > 在完整标签页中打开**（Settings > Open in Full Tab），把钱包作为完整浏览器标签页打开。 + +钱包以完整浏览器标签页而非侧边栏运行，全宽显示解锁界面 + +### 关于 + +- 扩展版本和构建信息 +- 文档、GitHub 和支持渠道的链接 + +--- + + + 申请加入 KaleidoSwap 扩展的封闭测试。 + diff --git a/mintlify-docs/cn/sdk/additional-resources.mdx b/mintlify-docs/cn/sdk/additional-resources.mdx new file mode 100644 index 0000000..89342a2 --- /dev/null +++ b/mintlify-docs/cn/sdk/additional-resources.mdx @@ -0,0 +1,85 @@ +--- +title: "KaleidoSDK：更多资源" +sidebarTitle: "更多资源" +description: "面向 KaleidoSDK 开发者的资源汇总：已发布的软件包、OpenAPI 规范、节点与 RGB 协议参考、测试网络，以及技术支持渠道" +--- + +## 软件包与源码 + + + + 已发布的 TypeScript 包。`npm install kaleido-sdk` + + + + 已发布的 Python 包。`pip install kaleido-sdk` + + + + 两种语言实现的源码、发布记录与问题跟踪。 + + + + 两个 SDK 都基于这些规范生成各自的 API 类型，这也是两种语言的请求与响应结构能够保持一致的原因。 + + + +## 协议参考 + + + + SDK 所驱动的原子 HTLC 流程，逐个接口端点讲解，并附有时序图。 + + + + `client.maker` 的 LSPS1 调用背后的通道下单接口。 + + + + `client.rln` 所通信的节点。这是 KaleidoSwap 的分支版本；[上游项目](https://github.com/RGB-Tools/rgb-lightning-node)由 RGB Tools 维护。 + + + + 客户端验证、资产接口，以及规范本身。 + + + +## 开发与测试 + +上主网之前请先在测试网络上开发。两个环境都已上线，且都不需要 API key。 + +按下面的写法把它们传入 `baseUrl` / `base_url` —— `/api/v1` 路径由 SDK 自动追加。 + +| 环境 | Base URL | 适用场景 | +|-------------|----------|----------| +| **signet (MutinyNet)** | `https://api.signet.kaleidoswap.com` | 在贴近真实的条件下做集成测试 | + + + + 获取 signet 比特币，用于为节点充值并开通测试通道。 + + + + Base URL、认证方式、请求格式与速率限制。 + + + +## 社区与支持 + + + + 针对 SDK 报告缺陷或提出功能需求。 + + + + 向社区和团队提问。 + + + + 紧急问题的直接支持渠道。 + + + + 语言选择、子客户端、密钥保管、版本兼容与金额单位。 + + diff --git a/mintlify-docs/cn/sdk/api-reference.mdx b/mintlify-docs/cn/sdk/api-reference.mdx new file mode 100644 index 0000000..95f8584 --- /dev/null +++ b/mintlify-docs/cn/sdk/api-reference.mdx @@ -0,0 +1,210 @@ +--- +title: "KaleidoSDK 客户端参考" +sidebarTitle: "客户端参考" +description: "KaleidoSDK 中 KaleidoClient、MakerClient 与 RlnClient 的完整参考，涵盖各个方法、参数与返回类型。" +--- + +## 客户端初始化 + + +```typescript TypeScript +import { KaleidoClient, LogLevel } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', + apiKey: process.env.KALEIDO_API_KEY, + timeout: 30, + logLevel: LogLevel.INFO, +}); + +client.hasMaker(); // boolean +client.hasNode(); // boolean +client.maker; // MakerClient +client.rln; // RlnClient +``` + +```python Python +import logging +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", + api_key=None, + timeout=30.0, + max_retries=3, + cache_ttl=60, + log_level=logging.INFO, +) + +client.has_node() # bool +client.maker # MakerClient +client.rln # RlnClient，缺少 node_url 时会抛出异常 +``` + + +## MakerClient（`client.maker`） + +### 市场数据 + +| TypeScript | Python | 说明 | +|------------|--------|-------| +| `listAssets()` | `list_assets()` | 列出所有资产 | +| `listPairs()` | `list_pairs()` | 列出所有交易对 | +| `getQuote(body)` | `get_quote(body)` | 请求报价 | +| `getPairRoutes(body)` | `get_pair_routes(pair_ticker)` | TS 接收请求体；Python 接收交易对代码，例如 `"BTC/USDT"` | +| `getMarketRoutes(body)` | `get_market_routes(body)` | 发现市场路由 | + + +```typescript TypeScript +import { KaleidoClient, Layer } from 'kaleido-sdk'; + +const client = KaleidoClient.create(); + +const assets = await client.maker.listAssets(); +const pairs = await client.maker.listPairs(); +const quote = await client.maker.getQuote({ + from_asset: { asset_id: 'BTC', layer: Layer.BTC_LN, amount: 100000 }, + to_asset: { asset_id: 'USDT', layer: Layer.RGB_LN }, +}); +``` + +```python Python +from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput + +client = KaleidoClient.create() + +assets = await client.maker.list_assets() +pairs = await client.maker.list_pairs() +quote = await client.maker.get_quote( + PairQuoteRequest( + from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=100000), + to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN), + ) +) +``` + + +### 原子交换 + +| TypeScript | Python | 说明 | +|------------|--------|-------| +| `initSwap(body)` | `init_swap(body)` | 初始化一笔原子交换 | +| `executeSwap(body)` | `execute_swap(body)` | 确认或执行该笔交换 | +| `getAtomicSwapStatus(body)` | `get_atomic_swap_status(body)` | 查询交换状态 | +| `getSwapNodeInfo()` | `get_swap_node_info()` | 做市方交换节点详情 | + +### LSPS1 + +| TypeScript | Python | 说明 | +|------------|--------|-------| +| `getLspInfo()` | `get_lsp_info()` | LSP 元数据 | +| `getLspNetworkInfo()` | `get_lsp_network_info()` | LSP 网络信息 | +| `createLspOrder(body)` | `create_lsp_order(body)` | 创建 LSPS1 订单 | +| `getLspOrder(body)` | `get_lsp_order(body)` | 获取 LSPS1 订单 | +| `estimateLspFees(body)` | `estimate_lsp_fees(body)` | 估算订单费用 | +| `submitLspRateDecision(body)` | `submit_lsp_rate_decision(body)` | 费率决策接口端点 | + +### WebSocket 与流式推送 + +| TypeScript | Python | 说明 | +|------------|--------|-------| +| `enableWebSocket(wsUrl)` | `enable_websocket(ws_url, user_id=None)` | 创建一个 `WSClient` | +| `streamQuotes(...)` | `stream_quotes(...)` | 通过 WebSocket 轮询报价流 | +| `streamQuotesByTicker(...)` | `stream_quotes_by_ticker(...)` | 自动选择路由 | +| `streamQuotesForAllRoutes(...)` | `stream_quotes_for_all_routes(...)` | 推送全部路由 | +| `getAvailableRoutes(...)` | `get_available_routes(...)` | 路由辅助方法 | + +## RlnClient（`client.rln`） {#rlnclient-clientrln} + +### 钱包与 BTC + +| TypeScript | Python | +|------------|--------| +| `getNodeInfo()` | `get_node_info()` | +| `getNetworkInfo()` | `get_network_info()` | +| `initWallet(body)` | `init_wallet(body)` | +| `unlockWallet(body)` | `unlock_wallet(body)` | +| `lockWallet()` | `lock_wallet()` | +| `changePassword(body)` | `change_password(body)` | +| `backup(body)` | `backup(body)` | +| `restore(body)` | `restore(body)` | +| `shutdown()` | `shutdown()` | +| `getAddress()` | `get_address()` | +| `getBtcBalance(skipSync?)` | `get_btc_balance(skip_sync=False)` | +| `sendBtc(body)` | `send_btc(body)` | +| `listTransactions(request?)` | `list_transactions(...)` | +| `listUnspents()` | `list_unspents(...)` | +| `createUtxos(body)` | `create_utxos(body)` | +| `estimateFee(body)` | `estimate_fee(body)` | + +### RGB 资产 + +| TypeScript | Python | +|------------|--------| +| `listAssets(filterAssetSchemas?)` | `list_assets(filter_asset_schemas=...)` | +| `getAssetBalance(body)` | `get_asset_balance(body)` | +| `getAssetMetadata(body)` | `get_asset_metadata(body)` | +| `getAssetMedia(body)` | `get_asset_media(body)` | +| `postAssetMedia(body)` | `post_asset_media(body)` | +| `issueAssetNIA(body)` | `issue_asset_nia(body)` | +| `issueAssetCFA(body)` | `issue_asset_cfa(body)` | +| `issueAssetUDA(body)` | `issue_asset_uda(body)` | +| `issueAssetIFA(body)` | `issue_asset_ifa(body)` | +| `inflate(body)` | `inflate(body)` | +| `sendRgb(body)` | `send_rgb(body)` | +| `listTransfers(body)` | `list_transfers(body)` | +| `refreshTransfers(body?)` | `refresh_transfers(body=None)` | +| `syncRgbWallet(body?)` | `sync_rgb_wallet(body=None)` | +| `failTransfers(body)` | `fail_transfers(body)` | +| `decodeSwapstring(body)` | `decode_swapstring(body)` | + +### 通道、对等节点、发票与支付 + +| TypeScript | Python | +|------------|--------| +| `listChannels()` | `list_channels()` | +| `openChannel(body)` | `open_channel(body)` | +| `closeChannel(body)` | `close_channel(body)` | +| `getChannelId(body)` | `get_channel_id(body)` | +| `listPeers()` | `list_peers()` | +| `connectPeer(body)` | `connect_peer(body)` | +| `disconnectPeer(body)` | `disconnect_peer(body)` | +| `createLNInvoice(body)` | `create_ln_invoice(body)` | +| `createRgbInvoice(body)` | `create_rgb_invoice(body)` | +| `decodeLNInvoice(body)` | `decode_ln_invoice(body)` | +| `decodeRgbInvoice(body)` | `decode_rgb_invoice(body)` | +| `getInvoiceStatus(body)` | `get_invoice_status(body)` | +| `sendPayment(body)` | `send_payment(body)` | +| `keysend(body)` | `keysend(body)` | +| `listPayments()` | `list_payments()` | +| `getPayment(body)` | `get_payment(body)` | + +### 交换协调与辅助方法 + +| TypeScript | Python | 说明 | +|------------|--------|-------| +| `getTakerPubkey()` | `get_taker_pubkey()` | 返回节点公钥 | +| `whitelistSwap(body)` | `whitelist_swap(body)` | 接收请求对象或原始 swapstring | +| `makerInit(body)` | `maker_init(body)` | 做市方侧的交换初始化 | +| `makerExecute(body)` | `maker_execute(body)` | 做市方侧的执行 | +| `listSwaps()` | `list_swaps()` | 列出交换 | +| `getSwap(body)` | `get_swap(body)` | 获取某笔交换 | +| `signMessage(body)` | `sign_message(body)` | 辅助方法 | +| `sendOnionMessage(body)` | `send_onion_message(body)` | 辅助方法 | +| `checkIndexerUrl(body)` | `check_indexer_url(body)` | 辅助方法 | +| `checkProxyEndpoint(body)` | `check_proxy_endpoint(body)` | 辅助方法 | +| `revokeToken(body)` | `revoke_token(body)` | 辅助方法 | + +## 关闭客户端 + + +```typescript TypeScript +await client.close(); +``` + +```python Python +await client.close() +``` + diff --git a/mintlify-docs/cn/sdk/best-practices.mdx b/mintlify-docs/cn/sdk/best-practices.mdx new file mode 100644 index 0000000..920cc87 --- /dev/null +++ b/mintlify-docs/cn/sdk/best-practices.mdx @@ -0,0 +1,367 @@ +--- +title: "KaleidoSDK 最佳实践" +sidebarTitle: "最佳实践" +description: "用 KaleidoSDK 构建生产级应用的实践指南：客户端初始化、错误处理与重试、金额精度、节点检查、WebSocket 清理与安全" +--- + +## 客户端初始化 + +### 使用环境变量 + +不要把配置写进源码： + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: process.env.KALEIDO_API_URL!, + nodeUrl: process.env.KALEIDO_NODE_URL, + apiKey: process.env.KALEIDO_API_KEY, +}); +``` + +```python Python +import os + +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url=os.environ["KALEIDO_API_URL"], + node_url=os.environ.get("KALEIDO_NODE_URL"), + api_key=os.environ.get("KALEIDO_API_KEY"), +) +``` + + +### 使用单例客户端 + +只创建一个客户端实例，并在整个应用中复用： + + +```typescript TypeScript +// lib/kaleido.ts +import { KaleidoClient } from 'kaleido-sdk'; + +let client: KaleidoClient | null = null; + +export function getClient(): KaleidoClient { + if (!client) { + client = KaleidoClient.create({ + baseUrl: process.env.KALEIDO_API_URL!, + }); + } + return client; +} +``` + +```python Python +# lib/kaleido.py +import os + +from kaleido_sdk import KaleidoClient + +_client = None + +def get_client() -> KaleidoClient: + global _client + if _client is None: + _client = KaleidoClient.create( + base_url=os.environ["KALEIDO_API_URL"] + ) + return _client +``` + + +## 错误处理 + +### 始终处理错误 + +把 SDK 调用包在 try/catch 中，并针对具体错误类型分别处理。下面给出的是最起码值得区分的几类；完整版本见 [错误处理](/cn/sdk/error-handling#comprehensive-error-handling)。 + + +```typescript TypeScript +import { KaleidoError, NetworkError, QuoteExpiredError } from 'kaleido-sdk'; + +try { + const quote = await client.maker.getQuote({ /* ... */ }); +} catch (error) { + if (error instanceof QuoteExpiredError) { + // 用新报价重试 + } else if (error instanceof NetworkError && error.isRetryable()) { + // 延迟一段时间后重试 + } else if (error instanceof KaleidoError) { + // 记录日志并优雅处理 + console.error(`[${error.code}] ${error.message}`); + } +} +``` + +```python Python +from kaleido_sdk import KaleidoError, NetworkError, QuoteExpiredError, PairQuoteRequest + +try: + quote = await client.maker.get_quote(PairQuoteRequest(...)) +except QuoteExpiredError: + # 用新报价重试 + pass +except NetworkError as e: + if e.is_retryable(): + # 延迟一段时间后重试 + pass +except KaleidoError as e: + print(f"[{e.code}] {e}") +``` + + +### 检查是否可重试 + +不要盲目重试。每个错误都提供 `isRetryable()` / `is_retryable()`，其中已经编码了哪些失败在第二次尝试时可能成功 —— 请使用它，而不要自己去匹配状态码。 + +完整的异常层级结构、按状态码划分的可重试性表格，以及现成的指数退避封装，见 [错误处理](/cn/sdk/error-handling#retry-patterns)。 + +## 异步模式 + +### TypeScript：并行请求 + +对互不依赖的请求使用 `Promise.all`： + +```typescript +const [assets, pairs, lspInfo] = await Promise.all([ + client.maker.listAssets(), + client.maker.listPairs(), + client.maker.getLspInfo(), +]); +``` + +当你希望拿到部分结果时，使用 `Promise.allSettled`： + +```typescript +const results = await Promise.allSettled([ + client.maker.listAssets(), + client.maker.listPairs(), +]); + +for (const result of results) { + if (result.status === 'fulfilled') { + console.log('Success:', result.value); + } else { + console.error('Failed:', result.reason); + } +} +``` + +### Python：串行执行并从错误中恢复 + +```python +from kaleido_sdk import KaleidoError + +results = {} +for name, fn in [ + ("assets", lambda: client.maker.list_assets()), + ("pairs", lambda: client.maker.list_pairs()), +]: + try: + results[name] = await fn() + except KaleidoError as e: + print(f"Failed to fetch {name}: {e}") + results[name] = None +``` + +## 金额处理 + +### 调用 API 时一律使用原始单位 + +API 使用原始（最小单位）金额。发送前请先转换展示金额： + + +```typescript TypeScript +import { parseRawAmount } from 'kaleido-sdk'; + +// 用户输入 0.001 BTC +const userInput = 0.001; +const rawAmount = parseRawAmount(userInput, 8); // 100000 + +const quote = await client.maker.getQuote({ + from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: rawAmount }, + to_asset: { asset_id: 'USDT', layer: 'RGB_LN' } +}); +``` + +```python Python +from kaleido_sdk import Layer, PairQuoteRequest, SwapLegInput, parse_raw_amount + +# 用户输入 0.001 BTC +user_input = 0.001 +raw_amount = parse_raw_amount(user_input, 8) # 100000 + +quote = await client.maker.get_quote(PairQuoteRequest( + from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=raw_amount), + to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN) +)) +``` + + +### 多资产应用请使用 PrecisionHandler + +处理多种资产时，使用 `PrecisionHandler` 避免精度错误： + + +```typescript TypeScript +import { createPrecisionHandler } from 'kaleido-sdk'; + +const handler = createPrecisionHandler(mappedAssets); + +// 按资产 ID 安全转换 +const raw = handler.toRawAmount(userInput, assetId); +const display = handler.toDisplayAmount(rawFromApi, assetId); +``` + +```python Python +from kaleido_sdk import create_precision_handler + +handler = create_precision_handler(mapped_assets) +raw = handler.to_raw_amount(user_input, asset_id) +display = handler.to_display_amount(raw_from_api, asset_id) +``` + + +## 节点操作 + +### 使用 RLN 前先检查节点 + +务必确认节点已配置： + + +```typescript TypeScript +if (!client.hasNode()) { + throw new Error('Node URL required for this operation'); +} + +const balance = await client.rln.getBtcBalance(); +``` + +```python Python +if not client.has_node(): + raise RuntimeError("Node URL required for this operation") + +balance = await client.rln.get_btc_balance() +``` + + +## WebSocket + +### 用完后取消订阅 + +务必清理 WebSocket 订阅： + + +```typescript TypeScript +const unsubscribe = await client.maker.streamQuotesByTicker( + 'BTC', 'USDT', 100000, onQuote +); + +// 组件卸载或用户离开页面时清理 +unsubscribe(); +``` + +```python Python +unsubscribe = await client.maker.stream_quotes_by_ticker( + "BTC", "USDT", 100000, on_quote +) + +# 用完后清理 +unsubscribe() +``` + + +### 处理重连 + +`WSClient` 会自行以指数退避重连，因此你这边要做的是把状态呈现给用户：收到 `disconnected` 时显示「正在重连」提示，收到 `connected` 时重新请求报价，并把 `maxReconnectExceeded` 当作硬性错误而非短暂抖动来处理。 + +事件列表与重连配置见 [WebSocket](/cn/sdk/websocket#events)。 + +## 安全 + +### 切勿在客户端代码中暴露 API 密钥 + +API 密钥只应在服务端使用。浏览器应用请通过你自己的后端代理 API 调用。 + +### 校验用户输入 + +发送到 API 之前，务必校验金额和地址： + + +```typescript TypeScript +// 校验金额是否在该层的交易限额之内 +const pairs = await client.maker.listPairs(); +const pair = pairs.pairs.find(p => + p.base.ticker === 'BTC' && p.quote.ticker === 'USDT' +); + +const limits = pair?.base.endpoints?.find(e => e.layer === 'BTC_LN'); +if (limits && (amount < limits.min_amount || amount > limits.max_amount)) { + throw new Error(`Amount must be between ${limits.min_amount} and ${limits.max_amount}`); +} +``` + +```python Python +pairs = await client.maker.list_pairs() +pair = next( + (p for p in pairs.pairs + if p.base.ticker == "BTC" and p.quote.ticker == "USDT"), + None +) + +limits = next( + (e for e in (pair.base.endpoints or []) if e.layer == "BTC_LN"), + None, +) if pair else None + +if limits and not (limits.min_amount <= amount <= limits.max_amount): + raise ValueError( + f"Amount must be between {limits.min_amount} and {limits.max_amount}" + ) +``` + + +订单规模限额位于每个资产的 `endpoints` 列表中（按层给出的 `TradingLimits`）；`pair.routes` 只告诉你存在哪些 `from_layer -> to_layer` 组合。 + +## 性能 + +### 缓存静态数据 + +资产和交易对很少变化。缓存它们以减少 API 调用： + + +```typescript TypeScript +import type { TradingPairsResponse } from 'kaleido-sdk'; + +let cachedPairs: TradingPairsResponse | null = null; +let cacheTime = 0; + +async function getPairs() { + const now = Date.now(); + if (!cachedPairs || now - cacheTime > 60000) { // 缓存 60 秒 + cachedPairs = await client.maker.listPairs(); + cacheTime = now; + } + return cachedPairs; +} +``` + +```python Python +import time + +_cached_pairs = None +_cache_time = 0 + +async def get_pairs(): + global _cached_pairs, _cache_time + now = time.time() + if _cached_pairs is None or now - _cache_time > 60: + _cached_pairs = await client.maker.list_pairs() + _cache_time = now + return _cached_pairs +``` + diff --git a/mintlify-docs/cn/sdk/changelog.mdx b/mintlify-docs/cn/sdk/changelog.mdx new file mode 100644 index 0000000..7de1d69 --- /dev/null +++ b/mintlify-docs/cn/sdk/changelog.mdx @@ -0,0 +1,162 @@ +--- +title: "KaleidoSDK 更新日志" +sidebarTitle: "更新日志" +description: "KaleidoSDK 的版本历史：每个版本的新增功能、破坏性变更，以及与 RLN 和 Maker API 的兼容性说明" +--- + +## SDK v0.1.17（当前版本） + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.8.0** + +### 修复 + +- **TypeScript** `listSwaps()` 不再让超过 `Number.MAX_SAFE_INTEGER` 的 RGB 交换数量丢失精度 —— `qty_from`/`qty_to` 会原样保留（类型为 `string | number`，请用 `BigInt(...)` 读取）。此前 `JSON.parse` 会静默地对这些数值取整，导致大额交换被错误上报。 + +## SDK v0.1.16 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.8.0** + +### 新增 + +- **TypeScript** `KaleidoConfig` 新增 `nodeApiKey` —— 用于 RLN 节点请求（包括 `enableNodeClient()`）的 bearer token，与做市方的 `apiKey` 相互独立，因此凭据绝不会被跨服务发送。 + +### 修复 + +- **TypeScript** 面向需要认证的 RLN 节点的凭据会被静默丢弃 —— `apiKey` 只会附加到做市方客户端上，所有节点调用都以未认证的方式发出。 + +## SDK v0.1.15 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.8.0** + +### 修复 + +- 补齐 0.1.14 版本的发布：该版本**只发布到了 npm**（一个过期的 decode-invoice 单元测试失败后，PyPI 任务被跳过）。相对 0.1.14 没有任何功能变化。 + +## SDK v0.1.14 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.8.0** + + +如果你的 RGB Lightning Node 仍在运行 **v0.7.1**，请继续使用 SDK **0.1.13** —— 0.1.14 及之后重新生成的模型针对的是 0.8.0 API 的数据结构。 + + +### 变更 + +- 将随包提供的 RGB Lightning Node OpenAPI 规范同步到 RLN **v0.8.0**，并重新生成了节点模型（Python + TypeScript）。 +- `/refreshtransfers` 接口端点现在返回 `RefreshResponse`（`{ transfers }`），而不再是空响应体。SDK 的 `refreshTransfers()` / `refresh_transfers()` 方法仍返回 `void` / `None`。 + +### 新增 + +- 来自 v0.8.0 的新 RLN 接口端点：`/getconsignment`、`/provideoutofbandack`、`/provideoutofbandconsignment`（带外 consignment 转移），以及它们对应的请求/响应类型。 +- 新的转移状态 `WaitingBroadcast`。 +- `Utxo` 新增 `exists` 与 `derivation_index`；`Unspent` 新增 `pending_blinded`。 + +### 破坏性变更 + +- **`RgbInvoiceRequest` 现在要求 `expiration_timestamp` 与 `transport_endpoints`**（在 RLN 0.7.1 中这两个字段是可选的或并不存在）。调用 `createRgbInvoice`/`create_rgb_invoice` 时必须同时提供二者。 +- **`SendRgbRequest` 现在要求 `expiration_timestamp`**，适用于 `sendRgb`/`send_rgb`。 +- `TransferTransportEndpoint.proxy_endpoint` 已被移除。 + +## SDK v0.1.13 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.7.1** + +### 移除 + +- **基于订单的交换流程。** 做市方 API 的 `/api/v1/swaps/orders/*` 接口端点已下线，因此 SDK 不再提供基于订单的接口：`createSwapOrder`/`create_swap_order`、`getSwapOrderStatus`/`get_swap_order_status`、`getOrderHistory`/`get_order_history`、`getOrderAnalytics`/`get_order_analytics`、交换订单的费率决策方法，以及 `waitForSwapCompletion`/`wait_for_swap_completion`（连同 `SwapCompletionOptions`），还有 `SwapOrder*`、`OrderHistory*` 和 `OrderStats*` 这些类型。（LSPS1 的 `submitLspRateDecision` 以及 `RateDecisionRequest`/`RateDecisionResponse` 不受影响。） + +### 破坏性变更 + +- 请从已移除的基于订单的方法迁移到**原子交换流程**：`initSwap`/`init_swap` → 在你的 RLN 节点上把 swapstring 加入白名单 → `executeSwap`/`execute_swap`，并通过 `getAtomicSwapStatus`/`get_atomic_swap_status` 查询状态。LSPS1 通道订单（`createLspOrder`/`getLspOrder`）不受影响。 + +## SDK v0.1.11 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.7.1** + +### 修复 + +- `refreshTransfers()` / `refresh_transfers()` 现在会在默认请求体中发送 `filter: []`（刷新所有待处理的转移）。RLN 0.7.1 把 `filter` 变成了 `RefreshRequest`（`POST /refreshtransfers`）的必填字段；此前只带 `{skip_sync}` 的默认请求体会被拒绝，返回 `HTTP 400 "Failed to deserialize the JSON body into the target type"`。TypeScript 与 Python 客户端均受此修复影响。 + +## SDK v0.1.10 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.7.1** + +### 修复 + +- **TypeScript** `listUnspents()` 现在默认发送 `settled_only: false`，与 Python 客户端以及 RLN 0.7.1 所要求的 `ListUnspentsRequest` 结构保持一致。在 0.1.9 中，TS 的便捷方法仍然发送只带 `{skip_sync}` 的请求体，会被 RLN 0.7.1 拒绝并返回 `HTTP 400 "Failed to deserialize the JSON body into the target type"`。 + +## SDK v0.1.9 + +**兼容的 API：** 最新 Maker API · RLN (RGB Lightning Node) API **v0.7.1** + +### 新增 + +- **NWC (Nostr Wallet Connect, NIP-47) 客户端** —— 新增 `kaleido-sdk/nwc` 子路径。`NWCClient` 提供 `rln_*` RLN 扩展方法，以及一个 `RlnTransport` 接缝，可让 RLN 客户端在 NWC 连接上运行（NIP-44 加密，NIP-04 回退）。闪电发票解码、发送 BTC 和列出支付记录都已映射到 NWC 传输通道上。 +- 面向 `POST /sendrgb`、`POST /inflate`、`POST /issueassetifa` 的 RLN 客户端方法与模型，以及 Inflatable Fungible Asset (IFA) 相关类型。 + +### 变更 + +- 基于 `kaleidoswap/rgb-lightning-node` **v0.7.1** 重新生成了 RLN 模型。 + +### 破坏性变更 + +- `ListUnspentsRequest` 现在要求 `settled_only`。RLN 0.7.1 会拒绝旧的只带 `{skip_sync}` 的请求体，返回 `HTTP 400 "Failed to deserialize the JSON body into the target type"`。便捷方法 `list_unspents()` 默认使用 `settled_only=False`；直接构造请求的调用方必须自行设置该字段。 +- `POST /sendasset` 已重命名为 `POST /sendrgb`（`SendAssetRequest`/`SendAssetResponse` → `SendRgbRequest`/`SendRgbResponse`）。 + + + 这里省略了 0.1.6–0.1.8 版本；完整内容请查看 SDK 仓库中的 [CHANGELOG](https://github.com/kaleidoswap/kaleido-sdk/blob/master/CHANGELOG.md)。 + + +## SDK v0.1.5 + +**兼容的 API：** 最新 Maker API 与最新 RLN API + + +本条目描述的是 0.1.5 发布时的接口面。下面列出的基于订单的交换方法以及 `waitForSwapCompletion` 后来在 **0.1.13** 中被移除 —— 迁移路径请参见该版本条目。 + + +### 包含内容 + +#### Maker API 客户端（`client.maker`） + +市场数据、报价、交换订单、原子交换协议、LSPS1 通道下单，以及 WebSocket 流式推送： + +- 市场操作：资产与交易对列表，带缓存 +- 报价接口端点：单笔与批量询价，支持实时流式推送 +- 交换订单管理：创建、列出并监控基于订单的交换 +- 原子交换协议：面向桌面端和直连节点场景的 HTLC 交换 +- LSPS1 通道下单：流动性与通道供给 +- WebSocket 流式推送：`streamQuotesByTicker` / `streamQuotesForAllRoutes`，自动发现路由并自动重连 + +#### RLN API 客户端（`client.rln`） + +覆盖钱包管理、闪电通道与资产操作的完整 RGB Lightning Node 操作： + +- 钱包管理：BTC 与 RGB 资产操作，并跟踪余额 +- 通道管理：开通、监控与关闭闪电通道 +- 发票操作：创建、列出并监控闪电发票 +- 支付执行：支付发票并协调节点间交换 +- 节点信息与健康状况：读取节点配置与公钥信息 + +#### SDK 特性 + +- `KaleidoClient.create()` —— TypeScript 与 Python 通用的同步工厂方法 +- `waitForSwapCompletion` —— 内置的轮询辅助方法，超时时间与状态回调均可配置 +- `PrecisionHandler` 与 `AssetPairMapper` 工具，用于金额换算和交易对查找 +- 完整的错误层级：`KaleidoError`、`NetworkError`、`ValidationError`、`APIError`、`QuoteExpiredError`、`NodeNotConfiguredError` +- 根据 OpenAPI 规范自动生成的类型（TypeScript：`openapi-fetch`；Python：Pydantic 模型） + +--- + +## API v1 + +**状态：** 稳定。v1 没有计划中的破坏性变更。 + +Maker API 的接口端点分组请参见 [Maker API 兼容性](/cn/sdk/maker-api-compatibility)，节点侧的接口面请参见 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。线上环境及其 WebSocket URL 列在 [快速开始](/cn/sdk/getting-started#available-environments) 中。 + +--- + +## 路线图 + +- **主网上线** —— 面向真实 BTC 与 RGB 资产的生产环境。 +- **支持更多分层协议** —— 在 KaleidoSwap Extension 中加入 Spark、Arkade 与 Liquid 协议适配器。 diff --git a/mintlify-docs/cn/sdk/error-handling.mdx b/mintlify-docs/cn/sdk/error-handling.mdx new file mode 100644 index 0000000..c9086aa --- /dev/null +++ b/mintlify-docs/cn/sdk/error-handling.mdx @@ -0,0 +1,372 @@ +--- +title: "SDK 错误处理" +sidebarTitle: "错误处理" +description: "借助 KaleidoSDK 的异常层级处理错误：各类错误的含义、HTTP 状态码映射、可重试性判断与重试模式，以及排查集成问题的思路" +--- + +## 错误层级结构 + +两个 SDK 使用几乎完全一致的错误类层级。所有错误都继承自 `KaleidoError`： + +``` +KaleidoError (基类) +├── APIError (HTTP 400-599) +│ └── RateLimitError (HTTP 429，仅 TypeScript) +├── RateLimitError (HTTP 429，Python —— 直接继承 KaleidoError) +├── NetworkError (连接问题) +├── ValidationError (HTTP 400, 422) +├── TimeoutError (HTTP 408, 504) +├── WebSocketError (WebSocket 问题) +├── NotFoundError (HTTP 404) +├── ConfigError (配置问题) +├── SwapError (交换操作失败) +├── NodeNotConfiguredError (节点未配置) +├── QuoteExpiredError (报价已过期) +└── InsufficientBalanceError (余额不足) +``` + +有一处差异需要注意：在 TypeScript 中 `RateLimitError` 继承 `APIError`，而在 Python 中它直接继承 `KaleidoError` —— Python 里的 `except APIError` 处理块捕获不到速率限制错误。 + +## 基类错误：KaleidoError + +所有 SDK 错误都继承 `KaleidoError`，并带有以下属性： + +| 属性 | 类型 | 说明 | +|----------|------|-------------| +| `code` | `string` | 供程序化处理使用的错误码 | +| `message` | `string` | 可读的错误信息 | +| `statusCode` / `status_code` | `number?` | HTTP 状态码（如适用） | +| `details` | `string?` | 额外的错误细节 | +| `isRetryable()` / `is_retryable()` | `boolean` | 该错误是否可以安全重试 | + + +```typescript TypeScript +import { KaleidoError } from 'kaleido-sdk'; + +try { + await client.maker.listPairs(); +} catch (error) { + if (error instanceof KaleidoError) { + console.log(`Code: ${error.code}`); + console.log(`Message: ${error.message}`); + console.log(`Status: ${error.statusCode}`); + console.log(`Retryable: ${error.isRetryable()}`); + } +} +``` + +```python Python +from kaleido_sdk import KaleidoError + +try: + await client.maker.list_pairs() +except KaleidoError as e: + print(f"Code: {e.code}") + print(f"Message: {e}") + print(f"Status: {e.status_code}") + print(f"Retryable: {e.is_retryable()}") +``` + + +## 各个错误类 + +### APIError + +在发生 HTTP 错误（状态码 400-599）时抛出。 + + +```typescript TypeScript +import { APIError } from 'kaleido-sdk'; +// 属性：code='API_ERROR'、statusCode、message、details +``` + +```python Python +from kaleido_sdk import APIError +# 属性：code='API_ERROR'、status_code、response_body +``` + + +### RateLimitError + +超出速率限制（HTTP 429）时抛出。在 TypeScript 中继承 `APIError`；在 Python 中直接继承 `KaleidoError`。 + + +```typescript TypeScript +import { RateLimitError } from 'kaleido-sdk'; +// 额外属性：retryAfter?: number（秒） + +try { /* ... */ } catch (error) { + if (error instanceof RateLimitError) { + console.log(`Retry after: ${error.retryAfter} seconds`); + } +} +``` + +```python Python +from kaleido_sdk import RateLimitError +# 额外属性：retry_after: int | None + +try: + ... +except RateLimitError as e: + print(f"Retry after: {e.retry_after} seconds") +``` + + +### NetworkError + +在出现网络连接问题（DNS 解析失败、连接被拒等）时抛出。 + +始终可重试（`isRetryable()` 返回 `true`）。 + +### ValidationError + +在校验失败（HTTP 400、422）时抛出。包含对 FastAPI 校验错误的解析。 + +### TimeoutError + +在请求超时（HTTP 408、504）时抛出。 + +始终可重试。 + +### WebSocketError + +在 WebSocket 连接或通信出错时抛出。 + +### NotFoundError + +在资源不存在（HTTP 404）时抛出。 + +### ConfigError + +在 SDK 配置有问题（例如 URL 无效）时抛出。 + +### SwapError + +在交换操作失败时抛出。 + + +```typescript TypeScript +import { SwapError } from 'kaleido-sdk'; +// 额外属性：swapId?: string + +try { /* ... */ } catch (error) { + if (error instanceof SwapError) { + console.log(`Swap failed: ${error.swapId}`); + } +} +``` + +```python Python +from kaleido_sdk import SwapError +# 额外属性：swap_id: str | None +``` + + +### NodeNotConfiguredError + +当在未配置 `node_url` 的情况下执行 RLN 节点操作时，由 Python SDK 抛出。TypeScript 在未提供 `nodeUrl` 却调用 `client.rln.*` 方法时，改为抛出 `ConfigError`（"Node API not configured. Provide \"nodeUrl\" when creating the client."）。 + + +```typescript TypeScript +import { ConfigError } from 'kaleido-sdk'; + +try { + await client.rln.getNodeInfo(); +} catch (error) { + if (error instanceof ConfigError) { + console.log('Configure nodeUrl to use RLN operations'); + } +} +``` + +```python Python +from kaleido_sdk import NodeNotConfiguredError + +try: + await client.rln.get_node_info() +except NodeNotConfiguredError: + print("Configure node_url to use RLN operations") +``` + + +### QuoteExpiredError + +在尝试使用已过期的报价时抛出。 + +### InsufficientBalanceError + +在余额不足以完成所请求的操作时抛出。 + + +```typescript TypeScript +import { InsufficientBalanceError } from 'kaleido-sdk'; +// 属性：requiredAmount: number、availableAmount: number、asset?: string + +try { /* ... */ } catch (error) { + if (error instanceof InsufficientBalanceError) { + console.log(`Need: ${error.requiredAmount}, Have: ${error.availableAmount}`); + } +} +``` + +```python Python +from kaleido_sdk import InsufficientBalanceError +# 属性：required_amount、available_amount、asset + +try: + ... +except InsufficientBalanceError as e: + print(f"Need: {e.required_amount}, Have: {e.available_amount}") +``` + + +## 完整的错误处理 {#comprehensive-error-handling} + + +```typescript TypeScript +import { + KaleidoError, + APIError, + NetworkError, + ValidationError, + TimeoutError, + NotFoundError, + QuoteExpiredError, + ConfigError, + InsufficientBalanceError, + RateLimitError, +} from 'kaleido-sdk'; + +try { + const quote = await client.maker.getQuote({ /* ... */ }); + const swap = await client.maker.initSwap({ /* ... */ }); +} catch (error) { + if (error instanceof QuoteExpiredError) { + // 获取新报价并重试 + } else if (error instanceof InsufficientBalanceError) { + console.log(`Need ${error.requiredAmount}, have ${error.availableAmount}`); + } else if (error instanceof ValidationError) { + console.log(`Invalid request: ${error.message}`); + } else if (error instanceof RateLimitError) { + // 等待后重试 + await new Promise(r => setTimeout(r, (error.retryAfter ?? 5) * 1000)); + } else if (error instanceof NotFoundError) { + console.log('Resource not found'); + } else if (error instanceof TimeoutError) { + console.log('Request timed out, retrying...'); + } else if (error instanceof NetworkError) { + console.log('Network issue, check connectivity'); + } else if (error instanceof ConfigError) { + console.log('Node not configured'); + } else if (error instanceof APIError) { + console.log(`API error (${error.statusCode}): ${error.message}`); + } else if (error instanceof KaleidoError) { + console.log(`SDK error [${error.code}]: ${error.message}`); + } +} +``` + +```python Python +from kaleido_sdk import ( + KaleidoError, + APIError, + NetworkError, + ValidationError, + TimeoutError, + NotFoundError, + QuoteExpiredError, + NodeNotConfiguredError, + InsufficientBalanceError, + RateLimitError, + PairQuoteRequest, + SwapRequest, +) +import asyncio + +try: + quote = await client.maker.get_quote(PairQuoteRequest(...)) + swap = await client.maker.init_swap(SwapRequest(...)) +except QuoteExpiredError: + # 获取新报价并重试 + pass +except InsufficientBalanceError as e: + print(f"Need {e.required_amount}, have {e.available_amount}") +except ValidationError as e: + print(f"Invalid request: {e}") +except RateLimitError as e: + await asyncio.sleep(e.retry_after or 5) +except NotFoundError: + print("Resource not found") +except TimeoutError: + print("Request timed out, retrying...") +except NetworkError: + print("Network issue, check connectivity") +except NodeNotConfiguredError: + print("Node not configured") +except APIError as e: + print(f"API error ({e.status_code}): {e}") +except KaleidoError as e: + print(f"SDK error [{e.code}]: {e}") +``` + + +## 重试模式 {#retry-patterns} + +使用 `isRetryable()` 实现自动重试： + + +```typescript TypeScript +async function withRetry(fn: () => Promise, maxRetries = 3): Promise { + for (let attempt = 0; attempt < maxRetries; attempt++) { + try { + return await fn(); + } catch (error) { + if (error instanceof KaleidoError && error.isRetryable() && attempt < maxRetries - 1) { + const delay = Math.pow(2, attempt) * 1000; + await new Promise(r => setTimeout(r, delay)); + continue; + } + throw error; + } + } + throw new Error('Max retries exceeded'); +} + +const pairs = await withRetry(() => client.maker.listPairs()); +``` + +```python Python +import asyncio + +async def with_retry(fn, max_retries=3): + for attempt in range(max_retries): + try: + return await fn() + except KaleidoError as e: + if e.is_retryable() and attempt < max_retries - 1: + delay = 2 ** attempt + await asyncio.sleep(delay) + continue + raise + raise RuntimeError("Max retries exceeded") + +pairs = await with_retry(lambda: client.maker.list_pairs()) +``` + + +## HTTP 错误映射 + +SDK 通过 `mapHttpError` / `map_http_error` 自动把 HTTP 错误映射为带类型的异常： + +| HTTP 状态码 | 错误类 | 是否可重试 | +|------------|-------------|-----------| +| 400, 422 | `ValidationError` | 否 —— 请求本身就有问题 | +| 404 | `NotFoundError` | 否 | +| 408, 504 | `TimeoutError` | 是，始终可重试 | +| 429 | `RateLimitError` | TypeScript：可以，等待 `retryAfter` 之后重试。Python：`is_retryable()` 返回 `False` —— 需要你自己按 `retry_after` 退避 | +| 500, 502, 503 | `APIError` | 是 —— 服务端故障可能自行恢复 | +| 其他 4xx | `APIError` | 否 | +| 网络故障 | `NetworkError` | 是，始终可重试 | + +不要把这张表硬编码进你自己的重试逻辑，而应调用 `isRetryable()` / `is_retryable()` —— 它精确编码了这些规则，并会随映射关系的演进保持正确。 diff --git a/mintlify-docs/cn/sdk/examples.mdx b/mintlify-docs/cn/sdk/examples.mdx new file mode 100644 index 0000000..3779af8 --- /dev/null +++ b/mintlify-docs/cn/sdk/examples.mdx @@ -0,0 +1,118 @@ +--- +title: "KaleidoSDK 代码示例" +sidebarTitle: "代码示例" +description: "可直接运行的 KaleidoSDK TypeScript 与 Python 示例，涵盖市场数据查询、原子交换流程与基于 WebSocket 的实时报价流" +--- + +## 市场数据 + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', +}); + +const [assets, pairs] = await Promise.all([ + client.maker.listAssets(), + client.maker.listPairs(), +]); + +console.log(`Assets: ${assets.assets.length}`); +console.log(`Pairs: ${pairs.pairs.length}`); + +for (const pair of pairs.pairs.slice(0, 5)) { + console.log(`${pair.base.ticker}/${pair.quote.ticker}`); +} +``` + +```python Python +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com" +) + +assets = await client.maker.list_assets() +pairs = await client.maker.list_pairs() + +print(f"Assets: {len(assets.assets)}") +print(f"Pairs: {len(pairs.pairs)}") + +for pair in pairs.pairs[:5]: + print(f"{pair.base.ticker}/{pair.quote.ticker}") +``` + + +## 原子交换 + +一次交换由五个步骤组成 —— 询价、初始化、在你的节点上加入白名单、执行，然后跟踪结算 —— 在 `initSwap` 之后停下来，只会留下一笔永远不会执行的已锁定交换。两种语言的完整流程见 [如何交换](/cn/sdk/how-to-swap)。 + +## WebSocket 流式传输 + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', +}); + +client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client-id'); + +const stop = await client.maker.streamQuotesByTicker( + 'BTC', + 'USDT', + 100000, + (quote) => console.log(quote.price), + { pollInterval: 2000 } +); + +setTimeout(() => stop(), 10000); +``` + +```python Python +import asyncio + +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com" +) + +client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client-id") + +stop = await client.maker.stream_quotes_by_ticker( + "BTC", + "USDT", + 100000, + lambda quote: print(quote["price"]), + poll_interval=2.0, +) + +await asyncio.sleep(10) +stop() +``` + + +## 节点操作 + +关于 `client.rln` 入口 —— `hasNode()` 守卫以及最初的几个节点调用 —— 见 [快速开始](/cn/sdk/getting-started#node-configuration-checks)。全部可用方法列在 [客户端参考](/cn/sdk/api-reference#rlnclient-clientrln) 中。 + +## 后续步骤 + + + + 完整的原子交换流程：初始化、白名单、执行、状态查询。 + + + 流式传输选项、事件，以及底层的 `WSClient`。 + + + 金额换算、精度处理与资产交易对映射。 + + + `client.maker` 与 `client.rln` 上的全部方法。 + + diff --git a/mintlify-docs/cn/sdk/faq.mdx b/mintlify-docs/cn/sdk/faq.mdx new file mode 100644 index 0000000..2ab215f --- /dev/null +++ b/mintlify-docs/cn/sdk/faq.mdx @@ -0,0 +1,106 @@ +--- +title: "KaleidoSDK 常见问题" +sidebarTitle: "常见问题" +description: "关于 KaleidoSDK 的常见问题：语言选择、maker 与 RLN 两个子客户端、密钥保管、可用网络、版本兼容、金额单位以及浏览器端使用" +--- + +## 常见问题 + + + + 看你的技术栈。两者都是独立实现，类型都由同一份 [OpenAPI 规范](https://github.com/kaleidoswap/specs)生成，因此 API 结构、子客户端和错误层级在两者之间几乎完全一致 —— 少数差异（速率限制处理、节点缺失错误）已在[错误处理](/cn/sdk/error-handling)中说明。本文档中的每个示例都同时给出两种语言。 + + 运行环境要求：TypeScript 需要 **Node.js 18+**，Python 需要 **Python 3.10+**。Rust 核心正在开发中。 + + + + 它们是一笔交换的两侧，大多数流程都会同时用到。 + + | 子客户端 | 通信对象 | 覆盖范围 | + |------------|----------|--------| + | `client.maker` | KaleidoSwap 做市方 | 报价、询价流式推送、原子交换的初始化与执行、LSPS1 通道订单 | + | `client.rln` | 你自己的 RGB Lightning Node | 钱包与 RGB 资产、通道、发票、交换白名单 | + + 典型的原子交换会通过 `client.maker` 获取报价并初始化，在 `client.rln` 上把 `swapstring` 加入白名单，然后再回到 `client.maker` 执行。参见[如何进行交换](/cn/sdk/how-to-swap)。 + + + + **对原子交换路径来说，是的。** 持有密钥、把 `swapstring` 加入白名单并路由 HTLC 的正是接单方自己的节点。这也正是做市方从不托管资产的原因 —— 流程中根本没有让它托管的环节。 + + 你可以在本地运行节点，也可以让 SDK 指向一个由你控制的远端节点。部署方式请参见[节点托管](/cn/desktop-app/getting-started/node-hosting)。 + + + + **不会。** SDK 只是覆盖两套 HTTP API 的带类型客户端。密钥保存在你所指向的 RGB Lightning Node 中，签名也在那里完成。SDK 无法转移任何未经你的节点授权的资金。 + + + + signet（MutinyNet）目前已经上线；主网即将推出。 + + - **signet** —— `https://api.signet.kaleidoswap.com`，条件贴近真实环境，是上主网前的最佳选择 + + 把它作为 `baseUrl` / `base_url` 传入即可；`/api/v1` 由 SDK 自动追加。完整列表见[可用环境](/cn/sdk/getting-started#available-environments)。 + + + + 需要关注两套彼此独立的兼容性： + + - [Maker API 兼容性](/cn/sdk/maker-api-compatibility) —— SDK 始终跟随最新的 Maker API 版本，因此不需要管理版本配对 + - [RLN API 兼容性](/cn/sdk/rln-api-compatibility) —— SDK 是针对某个特定的 RGB Lightning Node API 版本生成的 + + 两者都必须对齐。如果某个调用返回的不是错误，而是意料之外的数据结构，首先要检查的就是版本不匹配。 + + + + API 使用的是**原始整数金额**，而不是小数。换算比例由资产的精度决定，而各个资产的精度并不相同 —— BTC 和 USDT 就不一样。 + + 请使用辅助函数，不要自己做这套算术： + + ```typescript + import { parseRawAmount } from 'kaleido-sdk'; + + const sats = parseRawAmount(0.001, 8); // 100000 + const usdt = parseRawAmount(10.50, 2); // 1050 + ``` + + 完整的函数集（包括资产映射）见[工具函数](/cn/sdk/utilities)。 + + + + 不必。WebSocket 用于**流式接收实时报价**并自动重连；如果你要展示不断变动的价格或据此做出反应，它才有意义。一次性的交换用 REST 取一次报价就够了。 + + 流式 API 请参见 [WebSocket](/cn/sdk/websocket)。 + + + + 面向做市方 API 不行。大多数接口端点都禁用了 CORS，因此浏览器端应用需要自建后端来代理这些调用。请把 SDK 放在服务端，只向前端暴露必要的能力。 + + + + 所有 SDK 异常都继承 `KaleidoError`，因此只捕获这一个类型就能覆盖整个层级。每个错误都提供 `isRetryable()` / `is_retryable()`，用来判断重试是否安全 —— 不要盲目重试，因为有些失败无论重试多少次都不会成功。 + + 完整的错误层级和带退避的重试模式见[错误处理](/cn/sdk/error-handling)，如何将其融入生产级客户端见[最佳实践](/cn/sdk/best-practices)。 + + + +## 获取帮助 + +如果遇到的是报错而不是疑问，请查阅[故障排查](/cn/sdk/troubleshooting)。其他情况请通过下面你偏好的渠道反馈问题，并附上： + +1. SDK 版本（`getVersion()` / `get_version()`） +2. 语言与运行时版本（Node.js / Python） +3. 错误信息与堆栈跟踪 +4. 可复现问题的最小代码 +5. 运行环境（regtest / signet / 主网） + + + + 向社区提问。 + + + 在相应的仓库中报告缺陷。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/sdk/getting-started.mdx b/mintlify-docs/cn/sdk/getting-started.mdx new file mode 100644 index 0000000..56a0697 --- /dev/null +++ b/mintlify-docs/cn/sdk/getting-started.mdx @@ -0,0 +1,267 @@ +--- +title: "KaleidoSDK 快速上手" +sidebarTitle: "快速上手" +description: "在 TypeScript 或 Python 中安装并配置 KaleidoSDK，了解客户端、接口端点与环境设置，几分钟内获取你的第一笔交换报价。" +--- + +`kaleido-sdk`（TypeScript）和 `kaleido_sdk`（Python）由同一份 Maker API 与 RGB Lightning Node 规范生成，并在其上封装了手写客户端： + +- `client.maker` 对应 KaleidoSwap 的市场、交换和 LSPS1 接口端点 +- `client.rln` 对应 RGB Lightning Node 的钱包、通道、支付和交换接口端点 + + + 要确认哪个 SDK 版本对应哪个 API 版本，请参阅 [Maker API 兼容性](/cn/sdk/maker-api-compatibility) 和 [RLN API 兼容性](/cn/sdk/rln-api-compatibility)。 + + +## 安装 + + +```bash npm +npm install kaleido-sdk +``` + +```bash pnpm +pnpm add kaleido-sdk +``` + +```bash yarn +yarn add kaleido-sdk +``` + +```bash pip +pip install kaleido-sdk +``` + + +### 环境要求 + + + + - Node.js 18 或更高版本 + - 推荐 TypeScript 5.x + + + - Python 3.10 或更高版本 + - 运行时依赖会自动安装 + + + +## 基础设置 + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', +}); + +const assets = await client.maker.listAssets(); +console.log(`Found ${assets.assets.length} assets`); +``` + +```python Python +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com" +) + +assets = await client.maker.list_assets() +print(f"Found {len(assets.assets)} assets") +``` + + + +`KaleidoClient.create()` 在两个 SDK 中都是同步方法。创建客户端时不要使用 `await`。 + + +## 配置 + +### TypeScript + +`KaleidoClient.create()` 接收一个 `KaleidoConfig` 对象： + +```typescript +import { KaleidoClient, LogLevel } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', + apiKey: process.env.KALEIDO_API_KEY, + timeout: 30, + logLevel: LogLevel.INFO, +}); +``` + +支持的配置字段： + +- `baseUrl?`：Maker API 基础 URL，默认为 `https://api.signet.kaleidoswap.com` +- `nodeUrl?`：RGB Lightning Node 地址 +- `apiKey?`：可选的 API key +- `nodeApiKey?`：可选的 bearer token，用于需要认证的 RLN 节点请求 +- `timeout?`：请求超时时间（秒） +- `logLevel?`：SDK 日志级别 +- `logger?`：自定义日志实现 + +### Python + +`KaleidoClient.create()` 接收关键字参数： + +```python +import logging +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", + api_key=None, + timeout=30.0, + max_retries=3, + cache_ttl=60, + log_level=logging.INFO, +) +``` + +Python 支持相同的连接设置，并额外提供： + +- `max_retries`：HTTP 客户端的重试次数上限 +- `cache_ttl`：缓存 TTL（秒） +- `log_level`：标准 Python 日志级别 + +## 环境变量 + +SDK 不会自动加载环境变量，但示例中使用了以下名称，作为约定也很实用： + +| 变量 | 常见用途 | +|----------|-------------| +| `KALEIDO_API_URL` | Maker API 基础 URL | +| `KALEIDO_NODE_URL` | RGB Lightning Node 地址 | +| `KALEIDO_API_KEY` | API key | + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: process.env.KALEIDO_API_URL || 'https://api.signet.kaleidoswap.com', + nodeUrl: process.env.KALEIDO_NODE_URL, + apiKey: process.env.KALEIDO_API_KEY, +}); +``` + +```python Python +import os +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url=os.environ.get("KALEIDO_API_URL", "https://api.signet.kaleidoswap.com"), + node_url=os.environ.get("KALEIDO_NODE_URL"), + api_key=os.environ.get("KALEIDO_API_KEY"), +) +``` + + +## 可用环境 {#available-environments} + +将 API URL 作为 `baseUrl` / `base_url` 传入即可，SDK 会自行拼接 `/api/v1` 路径。在测试网络上无需 API key。 + +| 环境 | API URL | WebSocket URL | 状态 | +|-------------|---------|---------------|--------| +| **signet** | `https://api.signet.kaleidoswap.com` | `wss://api.signet.kaleidoswap.com/ws/{id}` | 已上线（默认） | +| **主网** | `https://api.kaleidoswap.com` | `wss://api.kaleidoswap.com/ws/{id}` | 即将上线 | + +## 子客户端架构 + + +```typescript TypeScript +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', +}); + +const pairs = await client.maker.listPairs(); + +if (client.hasNode()) { + const nodeInfo = await client.rln.getNodeInfo(); + const channels = await client.rln.listChannels(); +} +``` + +```python Python +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", +) + +pairs = await client.maker.list_pairs() + +if client.has_node(): + node_info = await client.rln.get_node_info() + channels = await client.rln.list_channels() +``` + + +## 节点配置检查 {#node-configuration-checks} + +TypeScript 提供 `client.hasNode()`，并且始终返回一个 `rln` 客户端实例。Python 提供 `client.has_node()`，如果缺少 `node_url`，访问 `client.rln` 会抛出 `NodeNotConfiguredError`。 + + +```typescript TypeScript +if (!client.hasNode()) { + console.log('Node URL not configured; only maker operations are available'); +} else { + const nodeInfo = await client.rln.getNodeInfo(); + console.log(nodeInfo.pubkey); +} +``` + +```python Python +if not client.has_node(): + print("Node URL not configured; only maker operations are available") +else: + node_info = await client.rln.get_node_info() + print(node_info.pubkey) +``` + + +## 第一笔报价 + + +```typescript TypeScript +import { KaleidoClient, Layer } from 'kaleido-sdk'; + +const client = KaleidoClient.create(); + +const quote = await client.maker.getQuote({ + from_asset: { + asset_id: 'BTC', + layer: Layer.BTC_LN, + amount: 100000, + }, + to_asset: { + asset_id: 'USDT', + layer: Layer.RGB_LN, + }, +}); + +console.log(quote.rfq_id); +console.log(quote.price); +``` + +```python Python +from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput + +client = KaleidoClient.create() + +quote = await client.maker.get_quote( + PairQuoteRequest( + from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=100000), + to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN), + ) +) + +print(quote.rfq_id) +print(quote.price) +``` + diff --git a/mintlify-docs/cn/sdk/how-to-swap.mdx b/mintlify-docs/cn/sdk/how-to-swap.mdx new file mode 100644 index 0000000..ec01a5b --- /dev/null +++ b/mintlify-docs/cn/sdk/how-to-swap.mdx @@ -0,0 +1,201 @@ +--- +title: "使用 SDK 创建原子交换" +sidebarTitle: "如何交换" +description: "用 KaleidoSDK 创建并执行比特币原子交换：从询价、初始化、白名单授权到执行与结算跟踪，逐步走通多协议交换的完整流程" +--- + +本指南使用 KaleidoSDK 完整演示一次原子交换（节点直连），并同时提供 TypeScript 与 Python 示例。 + +原子交换无需信任：做市方始终不会托管你的资金，因为密钥由你自己的 RGB Lightning Node 持有，且必须先由它把交换加入白名单才能结算。这也意味着你需要在客户端旁运行一个 RLN 节点 —— 可选方案见 [节点托管](/cn/desktop-app/getting-started/node-hosting)。 + +## 环境准备 + +`baseUrl` 和 `nodeUrl` 都必须提供：前者用于访问做市方，后者用于访问你自己的节点。 + + +```typescript TypeScript +import { KaleidoClient, Layer } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', +}); +``` + +```python Python +from kaleido_sdk import ( + ConfirmSwapRequest, + KaleidoClient, + Layer, + PairQuoteRequest, + SwapLegInput, + SwapRequest, + SwapStatusRequest, +) +from kaleido_sdk.rln import TakerRequest + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", +) +``` + + +## 第 1 步：获取报价 + +为想要交换的交易对请求报价。金额一律使用**原始整数单位** —— 转换辅助函数见 [工具函数](/cn/sdk/utilities)。 + + +```typescript TypeScript +const quote = await client.maker.getQuote({ + from_asset: { + asset_id: 'BTC', + layer: Layer.BTC_LN, + amount: 1000000, + }, + to_asset: { + asset_id: 'rgb:...:...', // 你的 RGB 资产 ID + layer: Layer.RGB_LN, + }, +}); +``` + +```python Python +quote = await client.maker.get_quote(PairQuoteRequest( + from_asset=SwapLegInput( + asset_id="BTC", + layer=Layer.BTC_LN, + amount=1000000, + ), + to_asset=SwapLegInput( + asset_id="rgb:...:...", # 你的 RGB 资产 ID + layer=Layer.RGB_LN, + ), +)) +``` + + +响应中的 `rfq_id` 是把下一步与本次价格绑定起来的凭据。报价会过期 —— 不要让 `rfq_id` 跨越用户的思考时间，否则 `initSwap` 会抛出 `QuoteExpiredError`。 + +## 第 2 步：初始化交换 + +依据该报价与做市方锁定交换。这一步返回后续每一步都要用到的 `swapstring` 和 `payment_hash`，以及授权状态轮询的 `access_token` —— `access_token` 只在这里返回一次，请与 payment hash 一起保存。 + + +```typescript TypeScript +const swap = await client.maker.initSwap({ + rfq_id: quote.rfq_id, + from_asset: quote.from_asset.asset_id, + from_amount: quote.from_asset.amount, + to_asset: quote.to_asset.asset_id, + to_amount: quote.to_asset.amount, +}); + +// swap.swapstring, swap.payment_hash, swap.access_token +``` + +```python Python +swap = await client.maker.init_swap(SwapRequest( + rfq_id=quote.rfq_id, + from_asset=quote.from_asset.asset_id, + from_amount=quote.from_asset.amount, + to_asset=quote.to_asset.asset_id, + to_amount=quote.to_asset.amount, +)) + +# swap.swapstring, swap.payment_hash, swap.access_token +``` + + +## 第 3 步：在接单方节点上加入白名单 + +你的节点必须先授权该 `swapstring`，才会接受传入的 HTLC。这是唯一一个通过 `client.rln` 执行的步骤。 + + +```typescript TypeScript +const takerPubkey = await client.rln.getTakerPubkey(); + +await client.rln.whitelistSwap({ swapstring: swap.swapstring }); +``` + +```python Python +taker_pubkey = await client.rln.get_taker_pubkey() + +await client.rln.whitelist_swap(TakerRequest( + swapstring=swap.swapstring, +)) +``` + + + +跳过这一步是执行阶段出现 `SwapError` 的最常见原因：初始化成功，但由于接单方从未同意该交换，执行随即失败。 + + +## 第 4 步：执行交换 + +把你节点的信息交给做市方，由它完成结算。 + + +```typescript TypeScript +const execution = await client.maker.executeSwap({ + swapstring: swap.swapstring, + payment_hash: swap.payment_hash, + taker_pubkey: takerPubkey, +}); + +console.log(`Swap executed. Status: ${execution.status}`); +``` + +```python Python +execution = await client.maker.execute_swap(ConfirmSwapRequest( + swapstring=swap.swapstring, + payment_hash=swap.payment_hash, + taker_pubkey=taker_pubkey, +)) + +print(f"Swap executed. Status: {execution.status}") +``` + + +## 第 5 步：跟踪结算 + +`executeSwap` 返回并不等于交换已经结算。请携带 `initSwap` 返回的 `access_token`，按 `payment_hash` 轮询状态，直到进入终态。 + + +```typescript TypeScript +const status = await client.maker.getAtomicSwapStatus({ + payment_hash: swap.payment_hash, + access_token: swap.access_token, +}); + +console.log(status.swap?.status); +``` + +```python Python +status = await client.maker.get_atomic_swap_status(SwapStatusRequest( + payment_hash=swap.payment_hash, + access_token=swap.access_token, +)) + +print(status.swap.status if status.swap else None) +``` + + +如果某笔转移待处理的时间超出预期，`client.rln.refreshTransfers()` / `refresh_transfers()` 可以推进待处理的 RGB 转移，而 `client.rln.listSwaps()` 能让你看到节点自身的视图。各类失败情形见 [故障排查](/cn/sdk/troubleshooting#swap-issues)。 + +## 后续步骤 + + + + 异常层级结构，以及围绕每一步的重试模式。 + + + 底层 HTLC 流程，逐个接口端点讲解，并附时序图。 + + + 流式接收实时报价，而不必逐条请求。 + + + `client.maker` 与 `client.rln` 上的全部方法。 + + diff --git a/mintlify-docs/cn/sdk/introduction.mdx b/mintlify-docs/cn/sdk/introduction.mdx new file mode 100644 index 0000000..f9aa68e --- /dev/null +++ b/mintlify-docs/cn/sdk/introduction.mdx @@ -0,0 +1,56 @@ +--- +title: "多协议比特币交换 SDK" +sidebarTitle: "总览" +description: "使用 KaleidoSDK 构建比特币钱包与交易应用。提供 TypeScript 与 Python 客户端，支持跨比特币分层协议的非托管原子交换，类型安全、接口一致。" +--- + +KaleidoSDK（`kaleido-sdk`）让钱包开发者能够集成跨比特币、Lightning 和 RGB 的非托管原子交换。它是 [KaleidoSwap 非托管 DEX](https://kaleidoswap.com) 的底层实现，并提供 TypeScript 与 Python 两个版本。 + +## 官方 SDK + +KaleidoSwap 同时提供 TypeScript 和 Python 官方 SDK。两者都是独立实现，类型均由同一份 OpenAPI 规范自动生成，从而保证完整的类型安全和一致的 API 设计。 + +## 架构 + +两个 SDK 采用相同的 API 设计，各自独立构建： + +![KaleidoSDK 架构图：应用通过 KaleidoClient 连接 MakerClient 与 RlnClient 两个子客户端，底层由 HTTP 与 WebSocket 传输层支撑](/assets/images/overview/sdk-architecture.png) + +你的应用通过 `KaleidoClient` 接入，它提供两个子客户端：**MakerClient** 负责市场操作（报价、原子交换、LSPS1 通道订单），**RlnClient** 负责 RGB Lightning Node 操作（钱包、通道、发票）。两者内部都使用 HTTP 客户端，并可选择使用 WebSocket 进行实时推送。 + +## 两套 API 界面 + +**Maker API**（`client.maker`） + +接入 KaleidoSwap 的做市方 API，用于： +- 获取资产交易对的报价 +- 初始化并执行 HTLC 原子交换 +- 通过 WebSocket 订阅实时报价 +- LSPS1 通道订购 + +**RLN（RGB Lightning Node）操作**（`client.rln`） + +直接与 RGB Lightning Node 交互，用于： +- 钱包管理与 RGB 资产操作 +- 闪电通道管理 +- 发票创建与支付 +- 节点间交换协调 + +想了解 KaleidoSwap 作为协议的整体设计，请参阅 [KaleidoSwap 是什么](/cn/whats-kaleidoswap/introduction)。 + +## 主要特性 + +- **子客户端架构**：通过 `client.maker` 和 `client.rln` 分类访问 API +- **类型安全**：类型由 OpenAPI 规范自动生成 —— 完整的 TypeScript 类型和 Python Pydantic 模型 +- **一致的 API**：TypeScript 与 Python 结构完全相同 +- **WebSocket 支持**：实时报价推送，并支持自动重连 +- **错误处理**：两个 SDK 都提供完整的异常层次结构 +- **RGB 资产交易**：完整支持在 Lightning 和链上交易 RGB 资产 +- **原子交换**：基于 HTLC 的交换，无需信任做市方 + +## 支持 + +需要帮助？可以查看： +- [GitHub Issues](https://github.com/kaleidoswap/kaleido-sdk/issues) +- [社区 Telegram](https://t.me/kaleidoswap) +- [支持邮箱](mailto:support@kaleidoswap.com) diff --git a/mintlify-docs/cn/sdk/maker-api-compatibility.mdx b/mintlify-docs/cn/sdk/maker-api-compatibility.mdx new file mode 100644 index 0000000..a2ca413 --- /dev/null +++ b/mintlify-docs/cn/sdk/maker-api-compatibility.mdx @@ -0,0 +1,70 @@ +--- +title: 'Maker API 兼容性' +description: "了解 KaleidoSDK 版本如何跟随 Maker API 演进，以及 SDK 通过 client.maker 暴露的接口端点分组和调用方式。" +--- + +## 兼容性 + +SDK 始终跟随**最新的 Maker API** 版本：这一侧不需要管理版本配对关系。请让两者都保持更新，以便使用受支持的接口端点，并第一时间用上新功能。 + + +要查看当前的 Maker API 版本和更新内容，请参阅 [Maker API 更新日志](https://github.com/kaleidoswap/maker-api/releases) 或你自己的 API 文档。 + + +## API 接口端点分组 + +Maker API 提供以下接口端点分组： + +| 接口端点分组 | 基础路径 | 说明 | +|---|---|---| +| **Market** | `/api/v1/market/` | 资产列表、交易对、报价请求 | +| **Swaps (Atomic)** | `/api/v1/swaps/` | 基于 HTLC 的原子交换初始化、执行与状态跟踪 | +| **LSPS1** | `/api/v1/lsps1/` | 通道订购、费用估算、流动性供给与闪电通道建立 | + + +基于订单的交换接口端点（`/api/v1/swaps/orders/*`）已下线，对应的 SDK 方法在 **0.1.13** 中被移除。请改用原子交换流程 —— 参阅 [如何交换](/cn/sdk/how-to-swap)。 + + +## 使用 Maker API + +在 SDK 中使用 Maker API 功能： + + +```typescript TypeScript +import { KaleidoClient, Layer } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', +}); + +// 通过 client.maker 访问 Maker API +const assets = await client.maker.listAssets(); +const pairs = await client.maker.listPairs(); +const quote = await client.maker.getQuote({ + from_asset: { asset_id: 'BTC', layer: Layer.BTC_LN, amount: 100000 }, + to_asset: { asset_id: 'USDT', layer: Layer.RGB_LN }, +}); +``` + +```python Python +import asyncio +from kaleido_sdk import KaleidoClient, Layer, PairQuoteRequest, SwapLegInput + +async def main(): + client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com" + ) + + # 通过 client.maker 访问 Maker API + assets = await client.maker.list_assets() + pairs = await client.maker.list_pairs() + quote = await client.maker.get_quote( + PairQuoteRequest( + from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=100000), + to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN), + ) + ) + +asyncio.run(main()) +``` + diff --git a/mintlify-docs/cn/sdk/nwc.mdx b/mintlify-docs/cn/sdk/nwc.mdx new file mode 100644 index 0000000..46ec29b --- /dev/null +++ b/mintlify-docs/cn/sdk/nwc.mdx @@ -0,0 +1,86 @@ +--- +title: 'Nostr Wallet Connect (NWC)' +description: '通过 Nostr Wallet Connect（NIP-47）与 kaleido-sdk/nwc 客户端远程操控多资产闪电节点：标准钱包方法、RGB 闪电扩展方法，以及与 HTTP 接入方式的取舍' +--- + +## 概览 + +从 **kaleido-sdk 0.1.9** 起，SDK 在 `kaleido-sdk/nwc` 子路径下提供了一个 **Nostr Wallet Connect (NIP-47)** +客户端。它让客户端应用可以通过 Nostr 中继驱动远端的钱包服务 —— 例如运行 RGB Lightning Node 的 KaleidoSwap +桌面枢纽 —— 而无需与该节点建立直接的 HTTP 连接。 + +在标准 NIP-47 钱包方法之外，该客户端还增加了 **`rln*` RGB 闪电扩展方法**，让你能够通过同一条加密的 NWC +通道读取余额、管理 RGB 资产，并在远端节点上创建发票。 + + + 传输层采用 **NIP-44** 端到端加密；当钱包服务未声明支持 NIP-44 时，会回退到 **NIP-04**。 + + +## 建立连接 + +你需要一个由钱包服务签发的 NWC **连接 URI**（`nostr+walletconnect://...`）。 + +```ts +import { NWCClient } from 'kaleido-sdk/nwc'; + +const nwc = new NWCClient(connectionUri); + +const { balance } = await nwc.getBalance(); +console.log('balance (msat):', balance); + +// 用完后释放中继订阅 +nwc.close(); +``` + +如果你需要在连接前查看 URI 的内容（中继、钱包公钥、密钥），可以使用导出的 `parseNwcUri(uri)`；协议错误或 +超时会抛出 `NwcError`。 + +## 标准钱包方法（NIP-47） + +```ts +await nwc.getInfo(); // 能力 / 支持的方法 +await nwc.getBalance(); // { balance }，单位为 msat +await nwc.makeInvoice({ amount, description }); // 创建一张 BOLT11 发票 +await nwc.payInvoice({ invoice }); // 支付一张 BOLT11 发票 +await nwc.payKeysend({ pubkey, amount }); // 自发支付 +await nwc.lookupInvoice({ payment_hash }); // 发票状态 +await nwc.listTransactions({ limit, offset }); // 支付历史 +``` + +## RGB Lightning Node 扩展方法 + +这些方法把 RLN 操作映射到同一条 NWC 连接上： + +```ts +await nwc.rlnNodeInfo(); // NodeInfoResponse +await nwc.rlnListAssets(); // ListAssetsResponse +await nwc.rlnAssetBalance({ asset_id }); // AssetBalanceResponse +await nwc.rlnGetAddress(); // 链上地址 +await nwc.rlnListChannels(); // ListChannelsResponse +await nwc.rlnRgbInvoice(params); // 创建一张 RGB 发票 +await nwc.rlnDecodeRgbInvoice({ invoice }); +await nwc.rlnSendAsset(params); // SendRgbRequest -> SendRgbResponse +``` + +## 通过 NWC 使用完整的 RLN 客户端 + +如果你已经在用 [`RlnClient`](/cn/sdk/api-reference) 连接 HTTP 的 `nodeUrl`，可以把传输层换成 NWC —— 客户端 +接口完全一致，只是改由 Nostr 承载： + +```ts +import { NWCClient, createNwcRlnClient } from 'kaleido-sdk/nwc'; + +const rln = createNwcRlnClient(new NWCClient(connectionUri)); +const info = await rln.getNodeInfo(); +const channels = await rln.listChannels(); +``` + +如果你需要直接构造底层传输，可以使用 `NwcRlnNodeClient`。 + +## NWC 与 HTTP 的选择 + +| | HTTP (`nodeUrl`) | NWC | +| --- | --- | --- | +| 连通性 | 需要能直接访问节点的 REST API | 通过 Nostr 中继工作 —— 不需要入向端口或公网节点 URL | +| 认证 | API key / Authorization 请求头 | NWC 连接密钥，全程加密（NIP-44/04） | +| 适用场景 | 服务端集成与同网络环境下的集成 | 在公网上远程操控用户自己的节点（例如桌面枢纽） | diff --git a/mintlify-docs/cn/sdk/rln-api-compatibility.mdx b/mintlify-docs/cn/sdk/rln-api-compatibility.mdx new file mode 100644 index 0000000..3aee2b7 --- /dev/null +++ b/mintlify-docs/cn/sdk/rln-api-compatibility.mdx @@ -0,0 +1,80 @@ +--- +title: 'RLN API 兼容性' +description: "查看每个 KaleidoSDK 版本对应的 RGB Lightning Node (RLN) API 版本，以及 client.rln 暴露的节点侧接口端点分类。" +--- + +import { sdkVersion, rlnApiVersion } from "/snippets/versions.mdx"; + +## 兼容性 + +**SDK v{sdkVersion}** 基于 **RGB Lightning Node API v{rlnApiVersion}** 生成（即 `kaleidoswap/rgb-lightning-node` 分支）。 + +SDK 会自动支持最新发布的 RLN API。请始终保持 SDK 与 RGB Lightning Node 同步更新，以确保完整兼容，并及时获得最新功能和安全改进。版本历史请参阅[更新日志](/cn/sdk/changelog)。 + + +要查看最新的 RLN API 变更和更新内容，请参阅 [RGB Lightning Node](https://github.com/kaleidoswap/rgb-lightning-node) 或你自己的节点文档。 + + +## RLN API 总览 + +RLN（RGB Lightning Node）API 由你所配置的 RGB Lightning Node 直接提供，支持钱包操作、闪电通道管理以及节点间的交换协调。 + +## RLN API 分类 + +| 分类 | 用途 | 示例 | +|---|---|---| +| **Wallet** | BTC 与 RGB 资产管理 | 余额查询、转账、资产操作 | +| **Channels** | 闪电网络通道操作 | 开通、关闭、监控、备份通道 | +| **Invoices** | 支付请求管理 | 创建、列出并监控发票 | +| **Payments** | 支付执行 | 支付发票、协调交换、节点间交易 | +| **Node Info** | 节点状态与配置 | 公钥、同步状态、能力信息 | + +## 访问 RLN 操作 + +在使用 RLN 操作前，请确认已配置好节点： + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', // RLN 操作必需 +}); + +// 检查节点是否已配置 +if (client.hasNode()) { + // 通过 client.rln 访问 RLN API + const nodeInfo = await client.rln.getNodeInfo(); + const balance = await client.rln.getBtcBalance(); + const channels = await client.rln.listChannels(); +} else { + console.log('Node not configured - RLN operations unavailable'); +} +``` + +```python Python +import asyncio +from kaleido_sdk import KaleidoClient + + +async def main(): + client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001" # RLN 操作必需 + ) + + # 检查节点是否已配置 + if client.has_node(): + # 通过 client.rln 访问 RLN API + node_info = await client.rln.get_node_info() + balance = await client.rln.get_btc_balance() + channels = await client.rln.list_channels() + else: + print("Node not configured - RLN operations unavailable") + + +if __name__ == "__main__": + asyncio.run(main()) +``` + diff --git a/mintlify-docs/cn/sdk/troubleshooting.mdx b/mintlify-docs/cn/sdk/troubleshooting.mdx new file mode 100644 index 0000000..0ccfed6 --- /dev/null +++ b/mintlify-docs/cn/sdk/troubleshooting.mdx @@ -0,0 +1,390 @@ +--- +title: "KaleidoSDK 故障排查" +sidebarTitle: "故障排查" +description: "定位并解决 KaleidoSDK 的常见问题：连接失败、版本不匹配、交换报错等，每一项都给出可直接照做的排查步骤" +--- + +## 安装问题 + + + + **症状：** `npm install kaleido-sdk` 报错失败 + + **解决办法：** + 1. 确认已安装 Node.js 18+：`node --version` + 2. 清理 npm 缓存：`npm cache clean --force` + 3. 删除 `node_modules` 和 `package-lock.json`，然后重新安装 + 4. 换一个包管理器试试：`pnpm add kaleido-sdk` + + + + **症状：** `pip install kaleido-sdk` 失败 + + **解决办法：** + 1. 确认已安装 Python 3.10+：`python --version` + 2. 使用虚拟环境：`python -m venv .venv && source .venv/bin/activate` + 3. 升级 pip：`pip install --upgrade pip` + 4. 试试：`pip install kaleido-sdk --no-cache-dir` + + + + **症状：** `Cannot find module 'kaleido-sdk'` 或 `ModuleNotFoundError` + + **解决办法：** + - **TypeScript：** SDK 仅支持 ESM，因此 `tsconfig.json` 需要 `"moduleResolution": "bundler"`、`"node16"` 或 `"nodenext"`。旧的 `"node"` 设置会忽略包的 `exports` 字段，无法解析该模块 + - **Python：** 确认你处在正确的虚拟环境中 + - 确认包已安装：`npm list kaleido-sdk` 或 `pip show kaleido-sdk` + + + +## 运行时错误 + + + + **症状：** 调用 API 时抛出 `NetworkError` + + **原因：** + - API 服务器不可达 + - `baseUrl` 有误 + - 防火墙拦截了请求 + + **解决办法：** + 1. 确认 `baseUrl` 正确且可访问 + 2. 检查网络连通性 + 3. 在浏览器中访问该 API URL 试试：`https://api.signet.kaleidoswap.com/api/v1/market/assets` + 4. 如果处在防火墙之后，确认已放行出向 HTTPS + + + + **症状：** 调用 `client.rln.*` 方法时，TypeScript 抛出 `ConfigError`（"Node API not configured..."），Python 抛出 `NodeNotConfiguredError` + + **原因：** 创建客户端时没有提供 `nodeUrl` / `node_url`。 + + **解决办法：** + + + ```typescript TypeScript + const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', // 补上这一行 + }); + ``` + + ```python Python + client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", # 补上这一行 + ) + ``` + + + 调用 RLN 方法前，务必先检查 `client.hasNode()` / `client.has_node()`。 + + + + **症状：** 带 `rfq_id` 调用 `initSwap` / `init_swap` 时抛出 `QuoteExpiredError` + + **原因：** 报价的 `expires_at` 时间已经过了。 + + **解决办法：** + 1. 在调用 `initSwap` 之前才去获取新报价 —— 不要让一个 `rfq_id` 跨越用户的思考时间继续使用 + 2. 用 WebSocket 流式推送来保证报价始终是最新的 + 3. 尽快完成白名单和执行；整个 初始化 → 白名单 → 执行 的流程都基于同一个报价 + + + + **症状：** 抛出 `ValidationError`，错误信息与金额相关 + + **原因：** + - 金额低于最小值或高于最大值 + - 精度用错了（发送的是展示单位而不是原始单位） + - 金额为负数或零 + + **解决办法：** + 1. 从 `listPairs` 的响应中查看最小/最大限额 + 2. 确认你发送的是原始金额而不是展示金额 —— 用[工具函数](/cn/sdk/utilities)中的 `parseRawAmount` / `parse_raw_amount` 进行换算 + 3. 在发送之前先校验金额 + + + + **症状：** 抛出状态码为 401 的 `APIError` + + **原因：** API key 无效或缺失。 + + **解决办法：** + 1. 检查 `apiKey` / `api_key` 是否设置正确 + 2. 确认该密钥有效且未过期 + 3. 有些接口端点可能并不需要 API key —— 请查阅[客户端参考](/cn/sdk/api-reference) + + + + **症状：** API 调用抛出 `TimeoutError` + + **原因：** + - 网络连接较慢 + - 服务器负载过高 + - 超时时间设置得太短 + + **解决办法：** + 1. 增大超时时间：`timeout: 60`（单位为秒） + 2. 检查网络连通性 + 3. 用 `error.isRetryable()` 实现重试逻辑 —— 参见[错误处理](/cn/sdk/error-handling#retry-patterns) + + + + **症状：** 重复调用时抛出 `RateLimitError`，通常出现在轮询报价的场景中 + + **原因：** 在速率限制窗口内发出了过多请求。 + + **解决办法：** + 1. 先退避再重试，并遵守响应中携带的 `retry_after`（在 Python 中，速率限制错误的 `is_retryable()` 返回 `False`，需要你自己退避） + 2. 改用 WebSocket 流式接收报价，而不是循环轮询 `getQuote` + 3. 缓存 `listAssets` / `listPairs` 的结果，不要每次操作都重新拉取 + + + +## 交换问题 {#swap-issues} + + + + **症状：** `initSwap` 成功，但 `executeSwap` / `execute_swap` 失败并抛出 `SwapError` + + **原因：** `initSwap` 返回的 `swapstring` 从未在你自己的节点上加入白名单，因此接单方无法履行该 HTLC。 + + **解决办法：** 这三步必须按顺序执行，而且加入白名单这一步是在 `client.rln` 上完成，而不是 `client.maker`： + + 1. `client.maker.initSwap(...)` → 返回 `swapstring` + 2. `client.rln.whitelistSwap(swapstring)` → 你的节点接受这笔交换 + 3. `client.maker.executeSwap(...)` → 做市方完成结算 + + 完整流程见[如何进行交换](/cn/sdk/how-to-swap)。 + + + + **症状：** 初始化或执行时抛出 `InsufficientBalanceError` + + **原因：** + - 你要发送的这一侧在通道上的出向容量不足 + - 除交换金额之外，还需要预留的粉尘储备不可用 + - 余额在链上，而不在通道里 + + **解决办法：** + 1. 通过 `client.rln.listChannels()` 检查对应资产的出向容量，而不只看总余额 + 2. 确认金额在 `listPairs` 给出的该交易对最小/最大限额之内 + 3. 如果容量不够，通过 LSPS1 追加入向或出向流动性 + + + + **症状：** `executeSwap` 已经返回，但资产没有到账 + + **解决办法：** + 1. 轮询 `client.maker.getAtomicSwapStatus(...)` / `get_atomic_swap_status(...)`，不要以为执行就是终态 + 2. 调用 `client.rln.refreshTransfers()` / `refresh_transfers()` 推进处于待处理状态的 RGB 转移 + 3. 通过 `client.rln.listSwaps()` 查看节点自己对这笔交换的记录 + + + + **症状：** 某个调用在解析阶段失败（Pydantic 的 `ValidationError`，或者某个 TypeScript 字段意外为 `undefined`），而不是返回一个明确的 SDK 错误 + + **原因：** SDK 与它所对接的 API 是基于不同版本的规范生成的。这种情况在节点侧最常见，因为 RLN 的版本由你自己掌控。 + + **解决办法：** + 1. 把你节点的版本与你所用 SDK 版本对应的目标版本对比 —— 参见 [RLN API 兼容性](/cn/sdk/rln-api-compatibility) + 2. 升级 SDK：`npm install kaleido-sdk@latest` 或 `pip install --upgrade kaleido-sdk` + 3. 查看[更新日志](/cn/sdk/changelog)，了解你当前版本与最新版本之间的破坏性变更 —— 有几个版本新增了现在已成为必填的请求字段 + + + +## WebSocket 问题 + + + + **症状：** `connected` 事件始终不触发，或者抛出 `WebSocketError` + + **解决办法：** + 1. 确认 WebSocket URL 正确（应以 `wss://` 开头） + 2. 确认在开始流式接收之前调用过 `enableWebSocket` / `enable_websocket` + 3. 检查 WebSocket 连接是否被防火墙或代理拦截 + 4. 在 URL 中换一个 client ID 试试 + + + + **症状：** `quoteResponse` / `quote_response` 事件始终不触发 + + **解决办法：** + 1. 确认该资产交易对有效且存在可用路由 + 2. 检查金额是否在最小/最大限额之内 + 3. 监听 WSClient 上的 `error` 事件 + 4. 确认连接已经建立（检查 `connected` 事件） + + + + **症状：** WebSocket 反复断开并重连 + + **解决办法：** + 1. 检查网络是否稳定 + 2. WSClient 会以指数退避自动重连 + 3. 监听 `reconnecting` 事件以跟踪重连尝试 + 4. 如果触发了 `maxReconnectExceeded`，就手动重连： + + + ```typescript TypeScript + ws.on('maxReconnectExceeded', async () => { + console.log('Reconnecting manually...'); + await ws.connect(); + }); + ``` + + ```python Python + async def manual_reconnect(): + print("Reconnecting manually...") + await ws.connect() + + ws.on("max_reconnect_exceeded", manual_reconnect) + ``` + + + + +## TypeScript 特有问题 + + + + **症状：** TypeScript 编译器报告类型不兼容 + + **解决办法：** + 1. 确认你是从 `kaleido-sdk` 导入类型： + ```typescript + import type { AssetResponseModel, TradingPairResponseModel } from 'kaleido-sdk'; + ``` + 2. 检查 TypeScript 版本是否为 5.0+ + 3. 如果启用了 strict 模式，可能需要显式处理 `undefined` + + + + **症状：** `ERR_REQUIRE_ESM` 或 import 语法报错 + + **解决办法：** + 1. SDK 仅支持 ESM。请确认你的项目使用 ESM： + - 在 `package.json` 中设置 `"type": "module"` + - 或者使用 `.mts` 文件扩展名 + 2. 如果必须使用 CommonJS，请改用动态导入：`const sdk = await import('kaleido-sdk')` + + + +## Python 特有问题 + + + + **症状：** 解析 API 响应时 Pydantic 抛出 `ValidationError` + + **解决办法：** + 1. 确认已安装 `pydantic>=2.0` + 2. 检查你使用的请求格式是否正确 + 3. API 可能已经更新 —— 试着升级 SDK：`pip install --upgrade kaleido-sdk` + + + + **症状：** `httpx.ConnectError` 或类似报错 + + **解决办法：** + 1. 检查 API URL 是否可达 + 2. 如果使用代理，请通过环境变量配置：`HTTP_PROXY`、`HTTPS_PROXY` + 3. 如果连接较慢，请增大超时时间 + + + +## 调试 + +### 开启详细日志 + + +```typescript TypeScript +// 使用 Node.js 自带的调试能力 +// 设置环境变量：NODE_DEBUG=http +// 或者用浏览器 DevTools 检查网络请求 +``` + +```python Python +import logging + +# 为 httpx 开启调试日志 +logging.basicConfig(level=logging.DEBUG) +logging.getLogger("httpx").setLevel(logging.DEBUG) +logging.getLogger("websockets").setLevel(logging.DEBUG) +``` + + +### 校验配置 + + +```typescript TypeScript +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', +}); + +console.log(`Has node: ${client.hasNode()}`); + +// 测试连通性 +try { + const assets = await client.maker.listAssets(); + console.log(`API connected: ${assets.assets.length} assets`); +} catch (error) { + console.error('API connection failed:', error); +} + +if (client.hasNode()) { + try { + const nodeInfo = await client.rln.getNodeInfo(); + console.log(`Node connected: ${nodeInfo.pubkey}`); + } catch (error) { + console.error('Node connection failed:', error); + } +} +``` + +```python Python +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", +) + +print(f"Has node: {client.has_node()}") + +try: + assets = await client.maker.list_assets() + print(f"API connected: {len(assets.assets)} assets") +except Exception as e: + print(f"API connection failed: {e}") + +if client.has_node(): + try: + node_info = await client.rln.get_node_info() + print(f"Node connected: {node_info.pubkey}") + except Exception as e: + print(f"Node connection failed: {e}") +``` + + +## 获取帮助 + +如果是疑问而不是报错，请查阅[常见问题](/cn/sdk/faq)。其他情况请通过下面你偏好的渠道反馈问题，并附上： + +1. SDK 版本（`getVersion()` / `get_version()`） +2. 语言与运行时版本（Node.js / Python） +3. 错误信息与堆栈跟踪 +4. 可复现问题的最小代码 +5. 运行环境（regtest / signet / 主网） + + + + 向社区提问。 + + + 在相应的仓库中报告缺陷。 + + + 紧急问题的直接支持渠道。 + + diff --git a/mintlify-docs/cn/sdk/types.mdx b/mintlify-docs/cn/sdk/types.mdx new file mode 100644 index 0000000..646bafa --- /dev/null +++ b/mintlify-docs/cn/sdk/types.mdx @@ -0,0 +1,136 @@ +--- +title: "KaleidoSDK 类型定义" +sidebarTitle: "类型定义" +description: "KaleidoSDK 中通用的核心类型与配置对象，涵盖资产、交易对、报价、交换以及客户端配置的字段说明。" +--- + +## 总览 + +SDK 同时提供自动生成的 API 模型和一层轻量的手写客户端。 + +- TypeScript 从 `kaleido-sdk` 导出请求与响应类型 +- Python 从 `kaleido_sdk` 导出 Pydantic 模型 + +## 客户端配置 + +### TypeScript + +```typescript +import type { KaleidoConfig } from 'kaleido-sdk'; + +const config: KaleidoConfig = { + baseUrl: 'https://api.signet.kaleidoswap.com', + nodeUrl: 'http://localhost:3001', + apiKey: process.env.KALEIDO_API_KEY, + timeout: 30, + logLevel: 'info', + logger: console, +}; +``` + +`KaleidoConfig` 目前支持以下字段： + +- `baseUrl?` +- `nodeUrl?` +- `apiKey?` +- `nodeApiKey?` +- `timeout?` +- `logLevel?` +- `logger?` + +### Python + +在常规用法中，Python 不会暴露单独的构造参数对象。请通过 `KaleidoClient.create(...)` 配置客户端： + +```python +import logging +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="http://localhost:3001", + api_key=None, + timeout=30.0, + max_retries=3, + cache_ttl=60, + log_level=logging.INFO, +) +``` + +## 常用枚举与模型 + + +```typescript TypeScript +import type { + AssetResponseModel, + PairQuoteRequest, + PairQuoteResponse, + TradingPairResponseModel, +} from 'kaleido-sdk'; +import { Layer } from 'kaleido-sdk'; +``` + +```python Python +from kaleido_sdk import ( + AssetResponseModel, + Layer, + PairQuoteRequest, + PairQuoteResponse, + TradingPairResponseModel, +) +``` + + +## 分层协议 + +SDK 使用共用的 `Layer` 枚举，在受支持的网络之间路由资产。 + + +```typescript TypeScript +import { Layer } from 'kaleido-sdk'; + +const fromLayer = Layer.BTC_LN; +const toLayer = Layer.RGB_LN; +``` + +```python Python +from kaleido_sdk import Layer + +from_layer = Layer.BTC_LN +to_layer = Layer.RGB_LN +``` + + +## 报价模型 + + +```typescript TypeScript +import type { PairQuoteRequest, PairQuoteResponse } from 'kaleido-sdk'; + +const request: PairQuoteRequest = { + from_asset: { asset_id: 'BTC', layer: Layer.BTC_LN, amount: 100000 }, + to_asset: { asset_id: 'USDT', layer: Layer.RGB_LN }, +}; + +const response: PairQuoteResponse = await client.maker.getQuote(request); +``` + +```python Python +from kaleido_sdk import Layer, PairQuoteRequest, SwapLegInput + +request = PairQuoteRequest( + from_asset=SwapLegInput(asset_id="BTC", layer=Layer.BTC_LN, amount=100000), + to_asset=SwapLegInput(asset_id="USDT", layer=Layer.RGB_LN), +) + +response = await client.maker.get_quote(request) +``` + + +## 辅助类型 + +TypeScript 还从包根导出与 WebSocket 和日志相关的类型： + +```typescript +import type { QuoteResponse, LogLevelValue, SdkLogger } from 'kaleido-sdk'; +``` diff --git a/mintlify-docs/cn/sdk/utilities.mdx b/mintlify-docs/cn/sdk/utilities.mdx new file mode 100644 index 0000000..d96b79e --- /dev/null +++ b/mintlify-docs/cn/sdk/utilities.mdx @@ -0,0 +1,282 @@ +--- +title: "KaleidoSDK 工具函数" +sidebarTitle: "工具函数" +description: "KaleidoSDK 提供的辅助函数：金额换算、精度处理，以及跨比特币与比特币二层资产的资产与交易对映射" +--- + +## 金额换算 + +### `parseRawAmount` / `parse_raw_amount` + +把展示金额转换为原始（最小）单位，例如把 BTC 转换为聪。 + + +```typescript TypeScript +import { parseRawAmount } from 'kaleido-sdk'; + +const sats = parseRawAmount(0.001, 8); // 100000 +const usdt = parseRawAmount(10.50, 2); // 1050 +``` + +```python Python +from kaleido_sdk import parse_raw_amount + +sats = parse_raw_amount(0.001, 8) # 100000 +usdt = parse_raw_amount(10.50, 2) # 1050 +``` + + +### `toDisplayAmount` / `to_display_amount` + +把原始（最小单位）金额转换回展示金额。 + + +```typescript TypeScript +import { toDisplayAmount } from 'kaleido-sdk'; + +const display = toDisplayAmount(50000000, 8); // 0.5 +``` + +```python Python +from kaleido_sdk import to_display_amount + +display = to_display_amount(50000000, 8) # 0.5 +``` + + +## PrecisionHandler + +`PrecisionHandler` 负责多个资产的金额换算，它会利用资产元数据自动查找精度。 + +### 创建 PrecisionHandler + + +```typescript TypeScript +import { createPrecisionHandler } from 'kaleido-sdk'; + +// 带有 asset_id 和 precision 的 MappedAsset 对象 +const assets = [ + { asset_id: 'btc-asset-id', ticker: 'BTC', precision: 8, /* ... */ }, + { asset_id: 'usdt-asset-id', ticker: 'USDT', precision: 2, /* ... */ }, +]; + +const handler = createPrecisionHandler(assets); +``` + +```python Python +from kaleido_sdk import create_precision_handler + +assets = [ + {"asset_id": "btc-asset-id", "ticker": "BTC", "precision": 8}, + {"asset_id": "usdt-asset-id", "ticker": "USDT", "precision": 2}, +] + +handler = create_precision_handler(assets) +``` + + +### 方法 + +#### `toRawAmount` / `to_raw_amount` + +按资产的精度把展示金额转换为原始金额。 + + +```typescript TypeScript +const raw = handler.toRawAmount(0.5, 'btc-asset-id'); // 50000000 +``` + +```python Python +raw = handler.to_raw_amount(0.5, "btc-asset-id") # 50000000 +``` + + +#### `toDisplayAmount` / `to_display_amount` + +把原始金额转换为展示金额。 + + +```typescript TypeScript +const display = handler.toDisplayAmount(50000000, 'btc-asset-id'); // 0.5 +``` + +```python Python +display = handler.to_display_amount(50000000, "btc-asset-id") # 0.5 +``` + + +#### `getAssetPrecision` / `get_asset_precision` + +获取指定资产的精度。 + + +```typescript TypeScript +const precision = handler.getAssetPrecision('btc-asset-id'); // 8 +``` + +```python Python +precision = handler.get_asset_precision("btc-asset-id") # 8 +``` + + +#### `formatDisplayAmount` / `format_display_amount` + +按正确的小数位数格式化展示金额。 + + +```typescript TypeScript +const formatted = handler.formatDisplayAmount(0.5, 'btc-asset-id'); // "0.50000000" +``` + +```python Python +formatted = handler.format_display_amount(0.5, "btc-asset-id") # "0.50000000" +``` + + +#### `validateOrderSize` / `validate_order_size` + +对照最小/最大限额校验订单金额。 + + +```typescript TypeScript +const result = handler.validateOrderSize(0.001, btcAsset); +// 返回：{ valid: boolean, error?: string, rawAmount, minRawAmount, maxRawAmount } +``` + +```python Python +result = handler.validate_order_size(0.001, btc_asset) +# 返回：ValidationResult { valid, error, raw_amount, min_raw_amount, max_raw_amount } +``` + + +#### `getOrderSizeLimits` / `get_order_size_limits` + +获取某个资产的最小/最大订单规模。 + + +```typescript TypeScript +const limits = handler.getOrderSizeLimits(btcAsset); +// 返回：{ minDisplayAmount, maxDisplayAmount, minRawAmount, maxRawAmount, precision } +``` + +```python Python +limits = handler.get_order_size_limits(btc_asset) +# 返回：OrderSizeLimits { min_display_amount, max_display_amount, min_raw_amount, max_raw_amount, precision } +``` + + +## AssetPairMapper（TypeScript） + +`AssetPairMapper` 用于从 `listPairs` 的响应中查找资产和交易对。该工具仅在 TypeScript SDK 中提供。 + +### 创建 Mapper + +```typescript +import { createAssetPairMapper } from 'kaleido-sdk'; + +const pairsResponse = await client.maker.listPairs(); +const mapper = createAssetPairMapper(pairsResponse); +``` + +### 方法 + +#### `findByTicker` + +按代码（ticker）查找资产。 + +```typescript +const btc = mapper.findByTicker('BTC'); +// 返回：MappedAsset | undefined +``` + +#### `findById` + +按资产 ID 查找资产。 + +```typescript +const asset = mapper.findById('btc-asset-id'); +// 返回：MappedAsset | undefined +``` + +#### `getAllAssets` + +获取所有资产。 + +```typescript +const allAssets = mapper.getAllAssets(); +// 返回：MappedAsset[] +``` + +#### `canTrade` / `canTradeByTicker` + +检查两个资产之间能否交易。 + +```typescript +const canTrade = mapper.canTrade('btc-asset-id', 'usdt-asset-id'); // boolean +const canTradeByTicker = mapper.canTradeByTicker('BTC', 'USDT'); // boolean +``` + +#### `getTradingPartners` + +获取所有可与给定资产交易的资产。 + +```typescript +const partners = mapper.getTradingPartners('btc-asset-id'); +// 返回：MappedAsset[] +``` + +#### `getActivePairs` + +获取所有处于活跃状态的交易对。 + +```typescript +const activePairs = mapper.getActivePairs(); +// 返回：TradingPairResponseModel[] +``` + +#### `findPairByTickers` + +按基础资产与计价资产的代码查找指定交易对。 + +```typescript +const pair = mapper.findPairByTickers('BTC', 'USDT'); +// 返回：TradingPairResponseModel | undefined +``` + +## SDK 信息 + +### `getVersion` / `get_version` + +获取 SDK 的版本字符串。 + + +```typescript TypeScript +import { getVersion } from 'kaleido-sdk'; +console.log(getVersion()); // "0.1.0" —— 返回的是硬编码值，并非实际的包版本 +``` + +```python Python +from kaleido_sdk import get_version +print(get_version()) # "0.1.17" +``` + + + +TypeScript 的 `getVersion()` 目前返回硬编码的 `"0.1.0"`，而不是已安装的包版本。要读取真实版本，请在 `package.json` 中查看 `kaleido-sdk` 依赖项。 + + +### `getSdkName` / `get_sdk_name` + +获取 SDK 的包名。 + + +```typescript TypeScript +import { getSdkName } from 'kaleido-sdk'; +console.log(getSdkName()); // "kaleido-sdk" +``` + +```python Python +from kaleido_sdk import get_sdk_name +print(get_sdk_name()) # "kaleido-sdk" +``` + diff --git a/mintlify-docs/cn/sdk/websocket.mdx b/mintlify-docs/cn/sdk/websocket.mdx new file mode 100644 index 0000000..391af7f --- /dev/null +++ b/mintlify-docs/cn/sdk/websocket.mdx @@ -0,0 +1,362 @@ +--- +title: "WebSocket 实时报价推送" +sidebarTitle: "WebSocket" +description: "使用 KaleidoSDK 通过 WebSocket 订阅实时交换报价，了解订阅方式、消息格式、事件类型与自动重连处理机制。" +--- + +## 总览 + +SDK 提供 WebSocket 支持，用于实时报价推送。WebSocket 客户端会负责连接管理、带指数退避的自动重连，以及 ping/pong 保活。 + +使用 WebSocket 有两种方式： + +1. **高层接口**：使用 `MakerClient` 上的 `streamQuotes` / `streamQuotesByTicker` 便捷方法 +2. **底层接口**：直接使用 `WSClient`，基于事件处理消息 + +## 启用 WebSocket + +在订阅报价之前，先启用 WebSocket 连接： + + +```typescript TypeScript +const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client-id'); +``` + +```python Python +ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client-id") +``` + + +URL 中包含一个客户端 ID，用于会话跟踪。`enableWebSocket` 方法返回一个 `WSClient` 实例。 + + +本页示例使用 signet，它同时也是 SDK 的默认环境。请让 WebSocket URL 与 `baseUrl` 指向的环境保持一致。参阅 [可用环境](/cn/sdk/getting-started#available-environments)。 + + +## 高层接口 + +### `streamQuotesByTicker` / `stream_quotes_by_ticker` + +订阅报价最简单的方式，会自动发现路由并开始推送。 + + +```typescript TypeScript +const unsubscribe = await client.maker.streamQuotesByTicker( + 'BTC', // fromTicker + 'USDT', // toTicker + 100000, // amount + (quote) => { // 回调 + console.log(`Price: ${quote.price}, RFQ: ${quote.rfq_id}`); + }, + { // options（可选） + preferredFromLayer: 'BTC_LN', + preferredToLayer: 'RGB_LN', + pollInterval: 3000 + } +); + +// 完成后停止推送 +unsubscribe(); +``` + +```python Python +from kaleido_sdk import Layer + +unsubscribe = await client.maker.stream_quotes_by_ticker( + from_ticker="BTC", + to_ticker="USDT", + amount=100000, + on_update=lambda quote: print(f"Price: {quote['price']}, RFQ: {quote['rfq_id']}"), + preferred_from_layer=Layer.BTC_LN, + preferred_to_layer=Layer.RGB_LN, + poll_interval=3.0, +) + +# 完成后停止推送 +unsubscribe() +``` + + +选项： + +| 选项 | 类型 | 说明 | +|--------|------|-------------| +| `preferredFromLayer` / `preferred_from_layer` | `Layer` | 固定源分层协议，而不交由路由发现自动选择 | +| `preferredToLayer` / `preferred_to_layer` | `Layer` | 固定目标分层协议 | +| `pollInterval` / `poll_interval` | number | 两次报价请求之间的间隔。TypeScript 以毫秒为单位（默认 `2000`），Python 以秒为单位 | + +### `streamQuotes` / `stream_quotes` + +针对指定路由（代码与分层协议）订阅报价。 + + +```typescript TypeScript +const unsubscribe = await client.maker.streamQuotes( + 'BTC', // from_asset 代码 + 'USDT', // to_asset 代码 + 100000, // from_amount（或 null） + 'BTC_LN', // from_layer（或 null） + 'RGB_LN', // to_layer（或 null） + (quote) => { + console.log(`${quote.from_asset.amount} -> ${quote.to_asset.amount}`); + } +); +``` + +```python Python +unsubscribe = await client.maker.stream_quotes( + from_asset="BTC", + to_asset="USDT", + from_amount=100000, + from_layer=Layer.BTC_LN, + to_layer=Layer.RGB_LN, + on_update=lambda quote: print(f"{quote['from_asset']['amount']} -> {quote['to_asset']['amount']}") +) +``` + + +### `streamQuotesForAllRoutes` / `stream_quotes_for_all_routes` + +同时订阅两个代码之间所有可用路由的报价。 + + +```typescript TypeScript +const unsubscribers = await client.maker.streamQuotesForAllRoutes( + 'BTC', 'USDT', 100000, + (route, quote) => { + console.log(`Route ${route}: price=${quote.price}`); + } +); +// 返回：Map void> +// 调用其中任一取消函数即可停止，或遍历后全部调用 +``` + +```python Python +unsubscribers = await client.maker.stream_quotes_for_all_routes( + from_ticker="BTC", + to_ticker="USDT", + amount=100000, + on_update=lambda route, quote: print(f"Route {route}: price={quote['price']}") +) +# 返回：dict[str, Callable] +``` + + +### `getAvailableRoutes` / `get_available_routes` + +在订阅之前，先查询某个交易对可用的路由。 + + +```typescript TypeScript +const routes = await client.maker.getAvailableRoutes('BTC', 'USDT'); +// 返回：Array<{ from_layer: string; to_layer: string }> +for (const route of routes) { + console.log(`${route.from_layer} -> ${route.to_layer}`); +} +``` + +```python Python +routes = await client.maker.get_available_routes("BTC", "USDT") +for route in routes: + print(f"{route['from_layer']} -> {route['to_layer']}") +``` + + +## 底层 WSClient 接口 + +如需完全控制，可直接使用 `WSClient`。 + +### 连接 + + +```typescript TypeScript +const ws = client.maker.enableWebSocket('wss://api.signet.kaleidoswap.com/ws/my-client'); + +await ws.connect(); +console.log(`Connected: ${ws.isConnected()}`); + +// 完成后 +ws.disconnect(); +``` + +```python Python +ws = client.maker.enable_websocket("wss://api.signet.kaleidoswap.com/ws/my-client") + +await ws.connect() +print(f"Connected: {ws.is_connected()}") + +# 完成后 +ws.disconnect() +``` + + +### 事件 {#events} + +使用 `on` / `off` 订阅事件： + +| 事件 | 数据 | 说明 | +|-------|------|-------------| +| `connected` | -- | 连接已建立 | +| `disconnected` | -- | 连接已关闭 | +| `reconnecting` | `attempt: number` | 正在尝试重连 | +| `quoteResponse` / `quote_response` | `QuoteResponse` | 收到新报价 | +| `connectionEstablished` / `connection_established` | connection data | 服务端已确认连接 | +| `pong` | `PongResponse` | 收到 pong | +| `error` | `Error` | 发生错误 | +| `maxReconnectExceeded` / `max_reconnect_exceeded` | -- | 已达到最大重连次数 | + + +```typescript TypeScript +ws.on('connected', () => console.log('Connected')); +ws.on('disconnected', () => console.log('Disconnected')); +ws.on('reconnecting', (attempt) => console.log(`Reconnecting: attempt ${attempt}`)); +ws.on('quoteResponse', (quote) => console.log(`Quote: ${quote.price}`)); +ws.on('error', (error) => console.error(`Error: ${error.message}`)); +ws.on('maxReconnectExceeded', () => console.log('Max reconnects exceeded')); + +// 取消订阅 +const handler = (quote) => { /* ... */ }; +ws.on('quoteResponse', handler); +ws.off('quoteResponse', handler); +``` + +```python Python +ws.on("connected", lambda: print("Connected")) +ws.on("disconnected", lambda: print("Disconnected")) +ws.on("reconnecting", lambda attempt: print(f"Reconnecting: attempt {attempt}")) +ws.on("quote_response", lambda quote: print(f"Quote: {quote['price']}")) +ws.on("error", lambda err: print(f"Error: {err}")) +ws.on("max_reconnect_exceeded", lambda: print("Max reconnects exceeded")) + +# 取消订阅 +handler = lambda quote: ... +ws.on("quote_response", handler) +ws.off("quote_response", handler) +``` + + +### 请求报价 + + +```typescript TypeScript +ws.requestQuote({ + from_asset: 'BTC', + to_asset: 'USDT', + from_amount: 100000, + from_layer: 'BTC_LN', + to_layer: 'RGB_LN' +}); +``` + +```python Python +ws.request_quote({ + "from_asset": "BTC", + "to_asset": "USDT", + "from_amount": 100000, + "from_layer": "BTC_LN", + "to_layer": "RGB_LN" +}) +``` + + +### Ping 与保活 + +WSClient 会按配置的间隔自动向服务端发送 ping。你也可以手动发送： + + +```typescript TypeScript +ws.ping(); +``` + +```python Python +ws.ping() +``` + + +## 配置 + +WSClient 支持以下配置选项： + +| 选项 | 默认值 | 说明 | +|--------|---------|-------------| +| `maxReconnectAttempts` / `max_reconnect_attempts` | `5` | 最大重连尝试次数 | +| `reconnectDelay` / `reconnect_delay` | `1000ms` / `1.0s` | 两次重连之间的基础延迟（采用指数退避） | +| `pingInterval` / `ping_interval` | `30000ms` / `30.0s` | 保活 ping 的发送间隔 | + +重连采用指数退避：`delay * 2^attempt`。 + +## WebSocket 协议 + +WebSocket 使用 JSON 消息协议： + +### 消息类型 + +| Action | 方向 | 说明 | +|--------|-----------|-------------| +| `quote_request` | 客户端 -> 服务端 | 请求价格报价 | +| `quote_response` | 服务端 -> 客户端 | 报价更新 | +| `ping` | 客户端 -> 服务端 | 保活 ping | +| `pong` | 服务端 -> 客户端 | 保活响应 | +| `connection_established` | 服务端 -> 客户端 | 连接已确认 | +| `error` | 服务端 -> 客户端 | 错误消息 | + +### QuoteResponse 字段 + +| 字段 | 类型 | 说明 | +|-------|------|-------------| +| `action` | string | 始终为 `quote_response` | +| `from_asset` | SwapLegData | 交换中源侧的完整定义 | +| `to_asset` | SwapLegData | 交换中目标侧的完整定义 | +| `price` | number | 1 个完整单位 `from_asset` 的价格，以 `to_asset` 的最小单位表示 | +| `rfq_id` | string | 询价 ID（传给 `initSwap`） | +| `timestamp` | number | 服务端时间戳 | +| `expires_at` | number | 报价过期时间戳 | +| `fee` | Fee | 费用明细 | + +每个 `SwapLegData` 对象描述交换中的一侧： + +| 字段 | 类型 | 说明 | +|-------|------|-------------| +| `asset_id` | string | 资产的唯一标识（例如 `BTC`、RGB 合约 ID） | +| `name` | string | 资产全称（例如 `Bitcoin`） | +| `ticker` | string | 展示用代码（例如 `BTC`、`USDT`） | +| `layer` | string | 结算分层协议（例如 `BTC_LN`、`RGB_LN`） | +| `amount` | number | 以最小单位表示的原始数量 | +| `precision` | number | 该资产的小数位数（例如 BTC 为 8） | + +## 最佳实践 + + + + 订阅 `disconnected` 和 `reconnecting` 事件。WSClient 会以指数退避自动重连，但你仍应处理超出最大尝试次数的情况。 + + + + `streamQuotesByTicker` 会替你完成路由发现、连接管理和报价分发。只有在需要自定义控制时才使用底层的 `WSClient`。 + + + + 不再需要报价时，务必调用 `streamQuotes` / `streamQuotesByTicker` 返回的取消订阅函数，以避免内存泄漏和不必要的网络流量。 + + + + 每条报价响应中的 `rfq_id` 就是传给 `initSwap`（`POST /api/v1/swaps/init`）的值。请使用最新的报价，以确保汇率仍然有效。 + + + +## 后续步骤 + + + + 在完整的端到端示例中查看 WebSocket 推送用法 + + + MakerClient 上所有推送方法的完整参考 + + + QuoteResponse、QuoteRequest 及其他 WebSocket 类型定义 + + + 重连策略与生产环境实践模式 + + diff --git a/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx b/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx new file mode 100644 index 0000000..1170c3b --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx @@ -0,0 +1,195 @@ +--- +title: "KaleidoSwap 架构解析" +sidebarTitle: "架构" +description: "拆解 KaleidoSwap 技术栈：一套 SDK 驱动所有客户端，为各比特币分层协议提供统一适配层，配合询价流动性层，全程不托管用户资金。" +--- + +KaleidoSwap 是垂直整合的：同一套 SDK 驱动我们发布的每一个客户端和每一个第三方集成，因此每个入口面对的都是同一个交换引擎、同一批协议适配器和同一份流动性。接入一个协议一次，所有地方都能用；新增一个客户端，则无需再做协议层的工作。 + +本页自上而下梳理整个技术栈。若想了解协议本身，以及哈希锁定合约为何能实现跨层交易，请先阅读[工作原理](/cn/whats-kaleidoswap/background)。若想了解这一设计背后更宏观的多协议论述，请阅读 [Solving Bitcoin's L2 liquidity problem](https://kaleidoswap.medium.com/solving-bitcoins-l2-liquidity-problem-kaleidoswap-s-multi-protocol-dex-layer-0725b26f8de4)。 + +## 技术栈 + +| 层级 | 包含内容 | +|-------|------------------| +| **客户端与集成方** | 桌面应用、浏览器扩展、移动端、Web 应用、CLI —— 以及第三方钱包、新型银行、支付服务商和 AI 代理 | +| **集成层** | 负责交换与市场数据的 `kaleido-sdk`；提供跨协议钱包基础能力的 `wallet-engine` | +| **协议层** | 每个比特币分层协议一个适配器，统一在同一套契约之下 | +| **流动性层** | 询价引擎，目前由 KaleidoSwap LSP 承担，外部做市商从 2027 年起加入 | +| **智能层** | 负责本地推理的 KaleidoMind，负责自主执行的 KaleidoAgent | +| **结算** | 比特币 —— 上面所有层最终锚定的地方 | + +桌面应用、SDK、CLI、钱包引擎以及 MCP/AI 工具链均为开源（MIT），可在 [GitHub](https://github.com/kaleidoswap) 上查阅；浏览器扩展和做市方的询价引擎目前尚未开源。 + +## 集成层 + +应用与协议之间有两个软件包。我们自家的客户端使用它们的方式，与外部集成方完全一致。 + + + + 交换集成：报价、交易对、询价流式推送、交换执行、LSPS1 通道订单，以及对 RGB 闪电节点的直接访问。目前提供 TypeScript 与 Python 版本，Rust 核心正在开发中。 + + + + 无界面的多协议钱包内核：协议适配器、跨协议路由器、统一接收，以及精简/进阶两档信息披露。采用 TypeScript，可运行在浏览器、React Native 和 Node 环境中。 + + + +`kaleido-sdk` 暴露两个子客户端 —— 面向市场侧的 `client.maker` 和面向节点操作的 `client.rln` —— 并根据后端提供的同一份 [OpenAPI 规范](https://github.com/kaleidoswap/specs)生成类型，因此 TypeScript 和 Python 版本永远不会脱节。 + +![抽象示意图：代码编辑器连接到 TypeScript 与 Python 两条路径，各自指向闪电符号与齿轮图标，最终汇入云服务与服务器机架](/assets/images/overview/sdk-architecture.png) + +## 协议层 + +每个比特币分层协议都有自己的 SDK、地址格式和各种特殊之处：这个协议讲通道流动性，那个协议讲上船交易，另一个又用静态接收地址。如果不加治理，这些差异就会变成每个应用每个页面上的协议判断分支。 + +我们的做法是让每个协议实现**同一套适配器契约**：连接、列出资产与交易、创建与解析发票、发送、接收，以及可选的报价与交换执行。协议之间的差异以能力清单中的**数据**形式存在，而不是应用代码里的分支。路由器和界面读取该清单，永不按协议名称做特殊处理。 + +由此带来的实际好处： + +- **接入新协议只需改动一个适配器**和一条清单记录 —— 绝不触碰其他协议的代码路径。 +- **客户端只调用一套 API**，从不直接调用协议 SDK，因此桌面端、扩展和移动端的行为保持一致。 +- **由路由器选择通道。** 给定一个目标 —— 闪电发票、比特币地址、RGB 发票或 Liquid 地址 —— 它会判断哪些协议可以支付，以及哪一个最合适。 +- **一个接收二维码**可同时承载多个协议，任何钱包都能扫码支付，而 KaleidoSwap 钱包还能读取其中更丰富的参数。 + +## 交换引擎 + +交换采用**询价**（Request for Quote）模型，由哈希锁定合约完成结算。做市方给出价格；闪电网络负责传输；共享的原像保证交换的原子性。 + +![示意图：桌面端、浏览器和扩展客户端连接到 RGB 闪电节点与闪电服务提供商，两者又连向代表比特币结算的哈希锁定区块链条](/assets/images/overview/architecture-overview.png) + +在已上线的 BTC ↔ RGB 路径上，流程如下： + +1. 接单方通过 WebSocket 接收做市方推送的报价，每份报价都带一个 `rfq_id`。 +2. `POST /api/v1/swaps/init` 锁定汇率，并返回 `swapstring` 和 `payment_hash`。 +3. 接单方的 RGB 闪电节点将 `swapstring` 加入白名单，授权其通过该节点路由。 +4. `POST /api/v1/swaps/execute` 启动 HTLC。 +5. 闪电网络进行路由：做市方公开原像以领取其中一条腿，这同时释放了另一条腿。 +6. 若任意一方停滞，时间锁到期后双方各自取回自己的资金。 + +全过程中持有密钥并验证状态的都是接单方的节点 —— 做市方从不托管资金。完整的接口端点参考与时序图见：[原子交换协议](/cn/api-reference/swap-protocol)。 + + + 原子性取决于两个层级都具备原生哈希锁。关于目前哪些路径符合、哪些不符合，见 [Where atomicity holds](/cn/whats-kaleidoswap/background#where-atomicity-holds)。 + + +## 流动性层 + +### 闪电服务提供商 + +LSP 让用户无需手动操作通道也能使用闪电网络。在本架构中，它们负责： + +- **提供流动性** —— 开通带入向容量的通道，并可预先注入某种 RGB 资产 +- **路由支付** —— 为普通支付和交换的各条腿寻找路径 +- **充当对手方** —— 锁定交换的另一条腿 + +### RGB-LSPS1 + +KaleidoSwap 实现了 RGB Lightning Service Provider Specification，将标准的 LSPS1 通道订购流程扩展到资产： + +- **标准化接口** —— 与 LSP 交互使用统一的 API 形态 +- **资产分配** —— 订购通道时可指定 RGB 资产 +- **交换支持** —— 原子交换协调能力内建于同一套接口 +- **费用透明** —— 在你确认前就明确列出成本 + +接口端点详见 [RGB LSPS1 API](/cn/api-reference/rgb-lsps1-apis)。 + +### 做市商 + +询价引擎在设计上就允许做市方之间竞争。目前由 KaleidoSwap LSP 自行提供初始流动性。从 2027 年起，外部做市商将通过同一套接口接入，并在点差上展开竞争。 + +## 智能层 + +AI 入口同样是这套技术栈的客户端。它们调用的工具与人机界面调用的完全相同，也受同样的确认环节约束。 + + + + 本地优先的推理与工具调用引擎。推理在设备端运行；任何会动用资金的工具都需要明确确认，模型无法绕过。 + + + + 用于投资组合与节点管理的自主代理。可基于本地模型或托管模型运行，且从不托管资金。 + + + +## 客户端架构 {#client-architecture} + +### 非托管设计 + +所有涉及密钥的环节都在你的设备上运行。客户端在本地持有或驱动钱包，自行验证状态，只通过上述网络接口与做市方和 LSP 通信。交换的任何阶段都不存在第三方能动用你的资金。 + +- **你的密钥，你的币** —— 私钥永不离开你的设备 +- **加密存储** —— 敏感数据以你的密码静态加密 +- **不托管** —— 做市方和 LSP 只是对手方，绝不是托管方 +- **客户端验证** —— RGB 状态由你自己验证，而不是信任某个服务器 + +### 各客户端支持的协议 + +| 客户端 | 协议 | 钱包模型 | +|--------|-----------|--------------| +| **[桌面应用](/cn/desktop-app/getting-started/introduction)** | 比特币 L1、闪电网络、闪电网络上的 RGB | 驱动一个完整的 RGB 闪电节点 —— 本地、Docker 或远程 | +| **[浏览器扩展](/cn/extensions/introduction)** | 比特币 L1、闪电网络、Spark、Arkade、Liquid、无需节点的 RGB-L1，以及可选的 RGB 闪电节点 | 一组助记词派生出所有协议的账户 | +| **[CLI](/cn/cli/introduction)** | 比特币 L1、闪电网络、闪电网络上的 RGB | 通过 Docker 一条命令启动本地节点 | + +### 组件分层 + +在客户端内部，不论平台如何，分层方式都是一致的： + +1. **UI 层** —— 各平台自己的界面 +2. **业务逻辑** —— 状态管理与流程编排 +3. **协议层** —— `wallet-engine` 适配器与跨协议路由器 +4. **网络层** —— 节点 RPC、做市方 API、LSP 集成、P2P 连接 + +## 安全模型 + + + + 在比特币区块链上完成最终结算并锚定安全性 + + + + 哈希锁定合约与时间锁，让失败的交换退款而不是执行一半 + + + + 在客户端验证 RGB 状态，阻止无效或双花的转移 + + + + 本地密钥管理、加密存储，以及任何支出前的明确确认 + + + +### 这里的「无需信任」指什么 + +- **没有对手方风险** —— 在原子路径上，交换要么双方都完成，要么都不完成 +- **没有托管方** —— 全程由你保管自己的密钥和资产 +- **密码学保证** —— 由时间锁和原像强制执行 + +## 结算特性 + +不同的层做出不同的取舍，这也是这套技术栈同时使用多个层的原因。不存在一个层能同时做到最快、最便宜且最终性最强。 + +| 层级 | 结算形式 | 原生哈希锁 | 最终性 | 典型成本 | +|-------|-----------|-----------------|----------|--------------| +| **比特币 L1** | 一笔链上交易 | 有（比特币共识） | 10–60 分钟 | 当前费率 | +| **闪电网络** | 一次通道状态更新 | 有（比特币共识） | 数秒 | 若干聪 | +| **RGB** | 比特币交易或通道更新中的一次承诺 | 有（比特币共识），在闪电网络上 | 取决于其所依附的层 | 已包含在锚定交易内 | +| **Spark** | 一次状态链密钥分片轮换；链上 UTXO 始终不动 | 有（该层的信任模型） | 亚秒级，前提是运营方删除旧的密钥分片 | 网络内免费；进出时支付比特币费用 | +| **Arkade** | 一次 VTXO 转移，通过承诺交易在链上批量处理 | 有（该层的信任模型） | 即时预确认，批量结算时获得比特币最终性 | 由整批交易摊薄 | +| **Liquid** | 一笔联盟侧链交易 | 有（该层的信任模型） | 约 2 分钟，两个确认 | 0.1 sat/vB 起，以 L-BTC 支付 | + +交易发生在闪电网络上，因为它能以极低成本在数秒内结算；比特币 L1 则是仓位最终沉淀的地方。哈希锁那一列决定了某条腿能否做到原子化，以及由谁提供保证 —— 见 [Where atomicity holds](/cn/whats-kaleidoswap/background#where-atomicity-holds)。 + +## RGB 资产接口 + +RGB 定义了若干资产接口，以前用 schema 编号来称呼。钱包支持全部四种；目前交易覆盖 NIA 资产。 + +| 接口 | 旧称 | 含义 | 是否支持 | +|-----------|----------|------------|-----------| +| **NIA** | RGB20 | 不可增发资产（Non-Inflatable Asset）—— 固定供应量的同质化代币，用于 USDT、XAUT 等稳定币 | 支持 | +| **IFA** | — | 可增发同质化资产（Inflatable Fungible Asset）—— 发行方可铸造或销毁的同质化代币 | 支持 | +| **UDA** | RGB21 | 唯一数字资产（Unique Digital Asset）—— 非同质化的独一无二资产 | 支持 | +| **CFA** | RGB25 | 收藏型同质化资产（Collectible Fungible Asset）—— 带有更丰富媒体与元数据的收藏品 | 支持 | + +各术语的定义见[术语表](/cn/whats-kaleidoswap/glossary#bitcoin-layers-and-assets)。 diff --git a/mintlify-docs/cn/whats-kaleidoswap/background.mdx b/mintlify-docs/cn/whats-kaleidoswap/background.mdx new file mode 100644 index 0000000..e770251 --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/background.mdx @@ -0,0 +1,122 @@ +--- +title: "KaleidoSwap 工作原理：比特币、闪电网络与二层协议" +sidebarTitle: "工作原理" +description: "KaleidoSwap 背后的技术：比特币负责最终结算，闪电网络充当各比特币分层协议之间的互操作总线，哈希锁定合约则让跨层交易要么双方都完成，要么都不完成。" +--- + +比特币早已不再只有一层。资产如今分布在闪电通道、状态链、虚拟 UTXO、联盟侧链，以及锚定在比特币自身之上的客户端验证叠加层中。每一层都有自己的状态模型，而且没有任何一层能读取另一层的账目。 + +但它们几乎都*能*表达一种**哈希锁定合约**：只向公开某个哈希原像的人付款，或在期限过后退款。KaleidoSwap 正是构建在这个共享原语之上。同一个原像用在一笔交易的两条腿上，就能让跨越两个互不兼容分层的交换要么双方都完成，要么都不完成。 + +## 比特币：结算层 + +每个 KaleidoSwap 钱包的内核都是一个比特币钱包：它持有 UTXO、签署交易，并向比特币网络广播。链上交易用于： + +- **钱包充值** —— 在转入更快的分层之前先存入 BTC +- **开通与关闭通道** —— 把闪电通道锚定到链上 +- **RGB 承诺** —— 把资产状态转移嵌入比特币交易 +- **锚定进入与退出** —— 进出 Liquid、Arkade 或 Spark + +比特币是价值最终结算的地方，也是上面每一层安全性的来源。 + +## 闪电网络：互操作总线 + +闪电网络是一种二层协议，它通过双向支付通道而不是区块来转移价值。在 KaleidoSwap 中，它承担两个不同的角色。 + +第一个是**快速、低成本的支付**。交换以秒计结算，而不是等待若干个确认，费用也只有几聪。 + +第二个角色则是整套技术栈得以成立的原因：闪电网络是**互操作总线**。大多数比特币分层协议都可以通过闪电网络触达 —— 或原生支持，或经由服务提供商 —— 而闪电网络的 HTLC 本身就是哈希锁定的。这让它成为跨层交易可以借道的公共媒介，即便涉及的两个分层彼此毫不知情。 + +## KaleidoSwap 连接的分层 + +| 分层 | 是什么 | 你持有什么 | 状态 | +|-------|------------|---------------|--------| +| **比特币 L1** | 基础链 | UTXO | 已上线 | +| **闪电网络** | 比特币之上的支付通道 | 以 BTC 计的通道余额 | 已上线 | +| **闪电网络上的 RGB** | 闪电通道内经客户端验证的资产 | 同一通道内的 RGB 资产（USDT、XAUT）与 BTC | 已在测试网络上线，主网已验证 | +| **比特币 L1 上的 RGB** | 同样的资产直接锚定到 UTXO，不使用通道 | UTXO 上的 RGB 资产 | 已上线，无需节点 | +| **Spark** | 基于状态链的分层，用于快速、低费用的转账 | Spark 代币、USDB | 已上线 | +| **Arkade** | 使用虚拟 UTXO（VTXO）的链下比特币交易 | VTXO 余额 | 已上线 | +| **Liquid** | 联盟式比特币侧链 | Liquid 资产，包括 USDt | 已上线 | +| **Taproot Assets** | 兼容闪电网络的代币层 | — | 开发中 | +| **Fedimint** | 联盟式电子现金 | — | 计划中 | +| **Cashu** | 乔姆式电子现金铸造方 | Ecash 代币 | 计划中 | + + + 各客户端支持的范围不同。桌面应用驱动一个完整的 RGB 闪电节点，而浏览器扩展用一组助记词即可覆盖 Spark、Arkade、Liquid 以及无需节点的 RGB-L1。按客户端的详细对照见[架构](/cn/whats-kaleidoswap/architecture#client-architecture)。 + + +## 资产叠加层：RGB + +RGB 是构建在比特币之上的客户端验证智能合约系统（完整规范见 [RGB 协议官方文档](https://docs.rgb.info)）。与基于账户的智能合约平台不同，RGB 把合约逻辑和状态保留在**链下**，只把比特币交易当作密码学承诺来使用。由此带来： + +- **隐私** —— 资产余额和转移不会出现在区块链上 +- **可扩展性** —— 代币转移不会让链膨胀 +- **比特币级安全** —— 资产状态锚定在比特币的工作量证明上 +- **可编程性** —— 支持全部四种 RGB 接口：NIA 同质化代币（USDT、XAUT）、IFA、UDA 与 CFA + +RGB 是一个*叠加层*，而不是独立的一层：同一份资产既可以待在比特币 UTXO 上，也可以搭载在闪电通道里。正是「搭载在通道里」让 RGB 资产能以闪电网络的速度交易，也支撑了 KaleidoSwap 在 2025 年完成的[首笔闪电网络主网 RGB 资产交换](https://kaleidoswap.medium.com/%EF%B8%8F-the-first-ever-rgb-asset-swap-on-lightning-mainnet-1b940dcd0efd)。 + +## 一笔交换如何完成 + +KaleidoSwap 采用**询价（Request for Quote，RFQ）**模型，而不是自动做市商。你发出询价，做市商给出价格，再由你决定是否接下。 + + + + 你的客户端从做市方持续接收某个交易对的实时价格。每份报价都带一个 `rfq_id` 和一个有效期。 + + + + 接下一份报价即锁定汇率，并返回交换参数，其中包括 `payment_hash` —— 两条腿都会锁定到这个哈希上。 + + + + 双方各自把资产投入一份合约：只有出示该哈希的原像才能取走，超过期限则自动退款。此时还没有任何不可撤销的资金变动。 + + + + 为领取第一条腿，原像被公开。由于两条腿锁定的是同一个哈希，公开原像也就同时解锁了第二条腿。 + + + + 双方都收到自己换来的资产。若任意一方停滞，时间锁到期后双方各自取回自己的资金 —— 绝不会出现只完成一半的交易。 + + + +协议层面的细节 —— 接口端点、`swapstring` 以及时序图 —— 见[原子交换协议](/cn/api-reference/swap-protocol)。 + +## 原子性在哪些情况下成立 {#where-atomicity-holds} + +原子性取决于一笔交易所触及的分层。有两件事决定它，而且彼此独立：该分层是否具备原生哈希锁，以及由谁的保证来强制执行。 + +- **由比特币共识强制执行。** 比特币 L1、闪电网络，以及闪电网络上的 RGB。哈希锁不需要任何人配合，因此任何一方都不可能同时拿走两份资产。 +- **在该分层自身的信任模型内强制执行。** Spark 暴露 HTLC，Arkade 用 Tapscript 构建 VHTLC，Liquid 继承 Bitcoin Script。哈希锁是真实存在的，但它附带该分层自己的假设（一组运营方、一个服务器签名、一个联盟），因此这条腿的原子性只存在于该分层之内，而不延伸到它下面。 +- **由服务提供商中介。** 完全没有原生哈希锁：由某个服务为这条腿做桥接，在此期间你需要信任它，整笔交易也就不是端到端原子的。 + +KaleidoSwap 已上线的原子路径是闪电网络上的 BTC ↔ RGB 资产。其他路径通过已支持的交易场所完成，并在应用中作了相应标注。把原生哈希锁定结算扩展到更多分层的工作正在进行中；在 Spark、Arkade 和 Liquid 上，限制来自我们的实现进度，而不是缺少这个原语。 + +## 流动性：LSP 与做市商 + +一笔哈希锁定的交易依然需要对面有人，拿着对的资产，待在对的位置。 + +**闪电服务提供商（LSP）**解决的是位置问题。你不必自己四处寻找对等节点、盘算通道大小，只需连接一个 LSP，它会： + +- **按需开通通道** —— 需要时即可订购入向流动性，还可以预先注入某种 RGB 资产 +- **路由支付** —— 让你的交易能够抵达目的地 +- **实现 LSPS1** —— 标准的通道订购接口，KaleidoSwap 将其扩展到了 RGB 资产 +- **促成交换** —— 充当锁定另一条腿的对手方 + +**做市商**解决的是定价问题：他们把报价推送到询价引擎，赚取点差和路由费。目前这部分流动性由 KaleidoSwap LSP 自行启动；从 2027 年起，外部做市方将通过同一套接口展开竞争 —— 正是这一步把单一对手方变成一个市场。 + +## 网络 + +| 网络 | 用途 | 状态 | +|---------|---------|--------| +| **regtest** | 在私有链上进行本地开发 | 可用 | +| **signet** | 共享测试网络，不涉及真实价值 | 可用 | +| **Mutinynet** | signet 的一个变体，出块时间快且可预测，适合测试闪电网络 | 可用 | +| **主网** | 真实资金 | 在浏览器扩展中为实验性支持 | + + + 扩展中的主网支持仍属实验性质，SDK 也面向测试网络。交换可能失败或卡住。除非你能接受资金损失的风险，否则请使用测试网络。 + diff --git a/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx b/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx new file mode 100644 index 0000000..9393e39 --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/glossary.mdx @@ -0,0 +1,391 @@ +--- +title: "比特币二层与闪电网络术语表" +sidebarTitle: "术语表" +description: "跨比特币分层协议交易所需的核心术语：原子交换、HTLC、闪电通道、LSP，以及 RGB、Spark、Arkade、Liquid 与 Nostr 连接能力。" +--- + +## 比特币与链上 + + + + 比特币的最小单位，等于 0.00000001 BTC。KaleidoSwap 中的所有金额都以聪计价。 + + + + 一聪的千分之一，用于闪电网络支付中的精确计算（在链上无法强制执行）。 + + + + 一份可被花费的独立比特币份额。RGB 资产锚定在比特币区块链上特定的 UTXO 之上。 + + + + 比特币交易被打包进区块链上的某个区块。确认数越多，抵御链重组的安全性越高。 + + + + 等待被打包进下一个区块的未确认比特币交易的集合。 + + + + 把一笔交易打包进比特币区块的每字节成本，通常以每虚拟字节多少聪（sat/vB）来衡量。 + + + + 一种比特币区块链索引服务：钱包向它查询地址、UTXO 和交易历史，而不必自己扫描整条链。KaleidoSwap 在无需节点的 RGB-L1 账户和 Liquid 上使用 Esplora 接口端点；默认已配置一个，你也可以填入自己的。 + + + + 一个独立的比特币网络，专用于测试，其中的币没有真实价值。 + + + + 较新的测试网络，出块时间更可预测，用于开发和测试。 + + + + 定制的比特币 signet，出块快且可预测，也不存在区块空间竞争，是 KaleidoSwap 的主要公共测试网络。[创建账户](/cn/desktop-app/wallet/creating-wallet)时可以选择它。 + + + + 回归测试模式，让开发者可以创建本地私有比特币网络用于测试。 + + + +## 闪电网络 + + + + 构建在比特币之上的二层支付协议，通过链下支付通道实现即时、低成本的交易。 + + + + 两个闪电节点之间的双向支付通道，在通道关闭之前可以进行多次交易而无需触及区块链。 + + + + 锁定在支付通道中的比特币（以及可能的 RGB 资产）总量，决定了单笔交易的上限。 + + + + 他人通过通道可以向你发送的资金量，由通道对端的余额决定。 + + + + 你通过通道可以发送的资金量，由你在通道中的余额决定。 + + + + 闪电网络请求支付的标准发票格式，包含金额、收款方及其他元数据。 + + + + 一种人类可读的支付标识，形如电子邮件地址（`user@domain.com`），在后台解析为一张闪电发票。KaleidoSwap 扩展支持将其作为提取的目标地址。 + + + + 一组协议，让闪电钱包能从某个 URL 获取支付细节，从而实现可复用的支付链接、提取和身份认证。扩展支持 LNURL，并通过 WebLN 暴露给 DApp。 + + + + 一种闪电支付方式，无需发票即可发起即时支付，用于推送资产或资金。 + + + + 一种条件支付机制，借助密码学哈希和时间锁，保证跨闪电通道的交易具备原子性。 + + + + 原像是解锁 HTLC 的秘密值；支付哈希是它的哈希，会公布在发票或交换参数中。公开原像即可领取支付，这正是原子交换之所以原子的原因 —— 两条腿要么用同一个秘密值一起结算，要么都不结算。KaleidoSwap 在交换初始化时会返回一个 `payment_hash`。 + + + + 在闪电网络中寻找路径，把支付从发送方送达接收方的过程。 + + + + 在链上结清通道的两种方式。协作关闭中双方对最终状态达成一致并签名，成本低、确认快。强制关闭则由一方单方面广播最新状态 —— 用于对等节点失联或通道卡住的情况 —— 资金会一直被时间锁锁定，直到延迟期结束。从[通道备份](/cn/desktop-app/channels/channel-backups)恢复会强制关闭其中包含的所有通道。 + + + +## LSP 与流动性 + + + + 向用户提供闪电基础设施、流动性和通道管理服务的服务提供商。 + + + + 面向闪电服务提供商的一组标准化协议，规定它们与客户端之间如何交互。 + + + + 第一份 LSP 规范，定义了通道开通与流动性服务。KaleidoSwap 为支持 RGB 的通道实现了 LSPS1。 + + + + 客户端向 LSP 发出的请求，要求按指定参数（例如容量和资产分配）开通一条闪电通道。 + + + + LSPS1 中用于追踪通道请求生命周期的对象：已创建、已支付、已开通。每个订单都有一个 ID，你可以据此查询、支付或提交汇率决定 —— 在 [CLI](/cn/cli/channels-lsp) 中对应 `kaleido channel order create | get | pay | decide`，在桌面应用中对应**购买通道** (Buy Channel) 标签页。 + + + + 持续对某个交易对双边报价、并为交换提供可成交流动性的参与者。目前这一角色由 KaleidoSwap LSP 自行承担；外部做市商从 2027 年起加入。不要与单笔交换中的做市方混淆，后者定义在「交易与市场」一节。 + + + +## 比特币分层协议与资产 {#bitcoin-layers-and-assets} + + + + 使用 RGB 协议创建的数字资产。RGB 资产是经客户端验证的智能合约，既借用比特币的安全性，又通过链下验证保持可扩展性与隐私。 + + + + 能理解 RGB 资产的闪电节点，因此一条通道可以同时承载 BTC 和 RGB 代币。它持有你的密钥、管理通道，并在本地验证合约。桌面应用的每一项钱包、通道和支付操作都要连接一个 RLN；在扩展中它是可选的实验性账户。见[节点托管](/cn/desktop-app/getting-started/node-hosting)。 + + + + Non-Inflatable Asset —— 面向固定供应量同质化代币的 RGB 接口，类似以太坊上的 ERC-20。用于创建和管理稳定币、功能型代币等可分割资产。这也是 KaleidoSwap 目前交易的资产类型。 + + + + Inflatable Fungible Asset —— 面向供应量可由发行方扩充或替换（铸造/销毁）的同质化代币的 RGB 接口。KaleidoSwap 支持该接口。 + + + + Unique Digital Asset —— 面向非同质化代币（NFT）的 RGB 接口，可类比 ERC-721。用于独一无二的数字资产和收藏品。KaleidoSwap 支持该接口。 + + + + Collectible Fungible Asset —— 面向带有丰富媒体与元数据的收藏品的 RGB 接口。KaleidoSwap 支持该接口。 + + + + RGB 资产的唯一标识，通常形如 `rgb:xxxxxx-xxxxxx-xxxxxx`。每种资产都有一个由其创世交易派生出的全局唯一 ID。 + + + + RGB 的核心概念：资产状态和交易历史由客户端验证，而不是存放在区块链上。这带来了更强的隐私性和可扩展性。 + + + + 除了聪之外还承载 RGB 资产状态的比特币 UTXO。要在链上接收或交易 RGB 资产，至少需要一个可用的着色 UTXO；如果你有 BTC 余额，桌面应用可以在[存入](/cn/desktop-app/wallet/deposits)过程中替你创建一个。不附带任何资产状态的 UTXO 有时称为 vanilla UTXO。 + + + + 一种接收承诺，让发送方可以把 RGB 资产转给你，却不知道它最终落在哪个 UTXO 上。在链上 RGB 转移中，它取代了地址的位置，因此 RGB [提取](/cn/desktop-app/wallet/withdrawals)要求填入盲化 UTXO，而 BTC 提取要求填入地址。 + + + + RGB 转移使用的支付请求格式，以 `rgb:` 开头。它编码了资产、金额和盲化接收承诺。无需节点的 RGB-L1 账户会自动创建盲化发票；连接 RLN 后，你还可以通过闪电网络接收 RGB。 + + + + 一种中继服务，在发送方与接收方之间传递 RGB 交付包 —— 因为 RGB 转移数据走链下，从不触及区块链。在桌面应用中与节点接口端点一起配置，在扩展中位于 RGB-L1 设置内。 + + + + 一个数据包，包含验证一次 RGB 资产转移所需的全部信息，包括证明、历史和状态转移。 + + + + 定义 RGB 资产属性、状态转移和验证规则的蓝图。不同接口（NIA、IFA、UDA、CFA —— 旧称 RGB20/21/25）对应不同的资产类型。 + + + + 面向 BTC 与原生资产的比特币分层，支持通过闪电网络收付。在 KaleidoSwap 扩展中，它是由你的助记词派生的自主保管账户，同时也支撑 Flashnet 交换和跨链桥。 + + + + 构建在 Spark 上的流动性网络。KaleidoSwap 把 Flashnet 路径作为一个交易场所，并把 Flashnet Orchestra 作为跨链桥背后的路由服务。 + + + + 基于 Ark 设计的比特币分层，资金以 VTXO（虚拟 UTXO）而非链上输出的形式持有。进出分别称为上船（boarding）与下船（offboarding）。扩展中作为一个账户支持，并提供可选的轮换地址模式。 + + + + Arkade 中的价值单位。资金以在链下流转的虚拟输出形式持有，而不是链上 UTXO，这正是 Arkade 转账即时且便宜的原因。VTXO 有自己的生命周期：上船时创建，账户使用期间维护，下船时在链上结算。扩展在**设置 > Arkade** (Settings > Arkade) 下提供 VTXO 与生命周期相关设置。 + + + + 带有保密交易的比特币侧链，是 L-BTC 以及 USDt 等发行资产的所在地。扩展中作为无需节点的自主保管账户支持，默认运行在主网上。 + + + + Liquid Bitcoin —— 持有在 Liquid 网络上的 BTC，由锁定在主链上的比特币一比一背书。它是扩展中 Liquid 账户的基础资产，与 USDt 等发行资产并列，并与你的 Spark、Arkade、比特币 L1 和闪电网络余额分开计算。 + + + +## 交易与市场 + + + + 一种无需信任的资产交换，要么完整完成，要么完整失败，不存在部分执行的可能。 + + + + 可以互相交易的两种资产的组合，例如 BTC/USDT。 + + + + 交易对中的第一种资产 —— 也就是你买入或卖出的对象。 + + + + 交易对中的第二种资产 —— 也就是你用来支付或收到的资产。 + + + + 某种资产支持的小数位数。例如 USDT 通常有 6 位小数精度。 + + + + 针对两种资产之间的交换请求报价。报价只在有限时间内有效。 + + + + 通过创建可供他人接受的交换报价来提供流动性的一方。 + + + + 通过接受已有交换报价来消耗流动性的一方。 + + + + 预期价格与实际成交价格之间的差额，通常源于市场波动或流动性限制。你可以为每笔交易设置可接受的最大滑点；一旦超出，交换会直接失败，而不会以更差的汇率成交。 + + + + 客户端可以据以执行交换的报价与流动性来源。连接 RLN 时，扩展可以使用 KaleidoSwap 做市方的交易对；Spark 资金池可用时，则可以使用 Spark/Flashnet 路径。执行交换至少需要一个可用的交易场所；基础钱包功能则不需要。 + + + + 在某个比特币分层与外部链之间转移资金 —— 在扩展中，即在你的 Spark 账户与 Ethereum、Base、Solana、Tron 等网络之间转移。它与交换不同：交换是在你的钱包内把一种资产换成另一种。比特币分层协议之间的原子交换完全不需要跨链桥。见[跨链桥](/cn/extensions/kaleidoswap-extension/bridge)。 + + + + 原子交换的当前状态：Waiting、Pending、Succeeded、Expired 或 Failed。 + + + +## 钱包、密钥与安全 + + + + 由 12 或 24 个单词组成的短语，可以恢复你的整个钱包，也称为 mnemonic 或种子短语。一组助记词派生出所有账户：在扩展中，它掌控 Spark、Arkade、Liquid 和 RGB-L1，以及默认的 Nostr 身份。任何拿到它的人都能动用你的资金，因此请离线保存，绝不外传。 + + + + 密码学密钥对中的公开部分，可以安全地分享。用于接收支付和验证签名。 + + + + 密码学密钥对中的秘密部分，绝不可分享。用于签署交易和证明所有权。 + + + + 一种从单组助记词以确定性方式生成多个密钥的方案。 + + + + 只能查看余额和交易，但无法签署或发送交易的钱包。 + + + + 一个备份文件，包含在数据丢失时恢复闪电通道资金所需的关键数据。 + + + + 针对无需节点的 RGB-L1 账户的加密云端 RGB 状态备份，每次接收时都会自动写入，并同时生成一份本地文件备份。重新导入时，引导流程会提示从中恢复 —— 绝不会在你未明确同意的情况下进行。RLN 的状态则改由节点自身的备份材料恢复。 + + + +## 连接与身份 + + + + 一种 Web 应用，它通过注入的浏览器 provider 与你的钱包通信，而不是索要密钥。KaleidoSwap 扩展会向你批准的页面暴露 WebLN、WebBTC 和 Nostr provider，并在任何敏感操作前向你确认。见 [DApp 连接](/cn/extensions/kaleidoswap-extension/dapp-connectivity)。 + + + + 闪电网络的标准浏览器 provider，注入在 `window.webln`。已批准的页面可以借它请求发票、支付、消息签名、keysend 以及 LNURL 处理。 + + + + 面向链上比特币的配套浏览器 provider，注入在 `window.webbtc`，供已批准的页面发起地址和交易请求。 + + + + 一个开放协议，用于在服务器之间中继签名消息，常用于身份和社交类应用。扩展会从你的助记词派生一个 Nostr 身份，也可以导入你已有的身份。 + + + + Nostr 身份的两半：`npub1…` 是你的公钥，可以安全分享；`nsec1…` 是你的私钥。任何持有你 nsec 的人都能签署事件、以你的身份行事 —— 绝不要分享它。 + + + + 页面内 Nostr 签名的标准，注入在 `window.nostr`。已批准的页面可以请求你的公钥、让事件被签名，以及加密或解密私信，而始终看不到你的密钥。 + + + + 面向无法使用页面内 provider 的 Nostr 应用的远程签名。扩展会生成一个 `bunker://` 连接串，供你粘贴到应用中；签名请求随后经中继传输，并在扩展中批准。 + + + + 即 NIP-47 —— 让外部应用通过 Nostr 中继控制钱包的一种方式，用 `nostr+walletconnect://` 字符串或二维码完成配对，并受带金额上限的预算约束。也用于连接远程 RGB 闪电节点，让节点本身保持私密。 + + + + 以 Nostr 事件形式发布的闪电支付，通常是对某条笔记的打赏。通过 NWC 发起的 Zap 会被验证，并与钱包活动关联起来。 + + + +## KaleidoSwap 平台 + + + + 支持在支付通道中承载 RGB 资产的闪电服务提供商，让 RGB 资产可以通过闪电网络即时转移。 + + + + 交换的某一方在哪条通路上结算。每条交换腿都会指明一个 `asset_id` 和一个 `layer`，因此一笔交易可以跨通路 —— 例如从 `BTC_LN` 到 `RGB_LN`。市场报价接受 `BTC_LN`、`RGB_LN` 和 `BTC_L1`（`BTC_ONCHAIN` 是旧的别名）。 + + + + 一个紧凑的字符串，编码了一笔交换交易的全部参数，用于在各方之间协调原子交换。 + + + + 完成资产转移所用的方式 —— 可以是 LIGHTNING（通过支付通道即时完成）或 ONCHAIN（通过比特币交易完成）。 + + + + 通道开通后，通过 keysend 在闪电通道中转移 RGB 资产的过程。 + + + + 当订单处理期间市场汇率出现显著变化时，用户可以选择接受新汇率或申请退款。 + + + + 每个 KaleidoSwap 客户端都构建在这两个 SDK 界面之上：`kaleido-sdk` 负责交换集成（TypeScript 与 Python，发布在 npm 和 PyPI 上，Rust 核心正在开发中），`@kaleidorg/wallet-engine` 提供钱包基础能力（TypeScript）。第三方集成使用的接口与我们自家应用完全相同。见 [SDK 文档](/cn/sdk/introduction)。 + + + + 一个自主、非托管的比特币二层代理，负责管理闪电网络与 RGB 投资组合、用原子交换再平衡，并自行购买通道流动性。密钥始终留在本地钱包和 RGB 闪电节点中，每笔交易都以原子 HTLC 交换结算。见 [KaleidoAgent](/cn/ai-tools/kaleido-agent)。 + + + + 支撑代理化 KaleidoSwap 钱包的推理与工具调用引擎。模型运行在你的设备上，或运行在你明确配对的桌面端上，并通过同一套工具契约以聊天或语音方式驱动 Spark、RGB 闪电网络、Arkade 和 Liquid。见 [KaleidoMind](/cn/ai-tools/kaleido-mind)。 + + + +--- + + + 本术语表会持续更新。如果你遇到这里没有列出的陌生术语，欢迎通过我们的[支持渠道](/cn/desktop-app/support/additional-resources)告诉我们。 + diff --git a/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx b/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx new file mode 100644 index 0000000..450e2a5 --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/introduction.mdx @@ -0,0 +1,201 @@ +--- +title: "KaleidoSwap：闪电网络上的比特币 DEX" +sidebarTitle: "欢迎" +description: "非托管去中心化交易所，支持跨比特币分层协议的原子交换，并通过闪电网络完成结算。无需账户与中间人，专为无需信任、自主掌控的交易而设计。" +--- + +![抽象的 KaleidoSwap 标识：紫绿色多切面宝石图形，周围环绕闪电符号与代币图标，背景为深色电路板](/assets/images/overview/hero-banner.png) + +KaleidoSwap 正在为比特币原生原子交换构建流动性层，让任何人都能自由、私密地交换比特币资产，无需中间人。 + +其垂直整合的技术栈涵盖桌面应用与浏览器扩展等终端用户应用、多语言 SDK、面向自主 AI 代理与本地 AI 大脑的 AI 工具，以及做市商软件。 + +--- + +## 为什么选择 KaleidoSwap？ + + + + 在比特币分层协议之间持有、支付和交换资产。BTC ↔ RGB 交换通过闪电网络原子化结算；其他路径则通过已支持的交易场所完成 + + + + 你的密钥，你的币。无需账户，没有中间人。连接你的钱包，或运行自己的节点即可 + + + + 桌面应用、SDK、CLI、钱包引擎和 AI 工具均采用 MIT 许可。你可以审阅代码、参与贡献，或构建自己的集成 + + + + 桌面应用支持 macOS、Windows 和 Linux。扩展可在浏览器中使用 + + + +--- + +## 平台总览 + +![KaleidoSwap 平台架构图：桌面端、扩展、移动端和 Web 应用客户端通过 swap-sdk 与 wallet-sdk 集成层，连接到比特币、闪电网络和二层协议图标、KaleidoSwap LSP 与做市商，以及 KaleidoMind 和 KaleidoAgent 智能层](/assets/images/overview/kaleidoswap-platform-overview.jpg) + +整个技术栈是垂直整合的：同一套 SDK 驱动我们发布的每一个客户端和每一个第三方集成，因此每个入口面对的都是同一个交换引擎、同一批协议和同一份流动性。 + +- **客户端与集成方** — 桌面端、扩展、移动端和 Web 应用，以及基于相同接口构建的第三方钱包、新型银行、支付服务商和 AI 代理。 +- **集成层** — 用于交换集成的 `kaleido-sdk`（TypeScript 和 Python，Rust 核心正在开发中），以及提供钱包基础能力的 `@kaleidorg/wallet-engine`（TypeScript）。[从 SDK 开始 →](/cn/sdk/introduction) +- **协议** — 比特币链上与闪电网络，以及交换可结算的各类比特币分层协议。[工作原理 →](/cn/whats-kaleidoswap/background) +- **流动性层** — 目前由 KaleidoSwap LSP 提供初始流动性；外部做市商将从 2027 年起加入。 +- **智能层** — KaleidoMind 是自托管的 AI 大脑（QVAC 运行时、Skills 与 MCP 库、微调模型），KaleidoAgent 是自主交易代理，可基于本地模型或 Claude 与 OpenAI 运行。[了解 AI 工具 →](/cn/ai-tools/introduction) + +标记为 LIVE 的组件已在生产环境中运行；其余部分列在 2026 年路线图中。 + +--- + +## 面向交易者 + +使用我们的应用和扩展，从自己的钱包直接交易： + +### 快速上手 + + + + 下载 macOS、Windows 或 Linux 版本。 + [安装指南 →](/cn/desktop-app/getting-started/installation) + + + + 生成新钱包并保存你的助记词。 + [钱包设置 →](/cn/desktop-app/wallet/creating-wallet) + + + + 为钱包充值，然后开通闪电通道。 + [存入指南 →](/cn/desktop-app/wallet/deposits) · [通道指南 →](/cn/desktop-app/channels/opening-channel) + + + + 使用 RGB 资产执行原子交换。 + [交易指南 →](/cn/desktop-app/trading/asset-swaps) + + + +### 指南 + + + + 节点、钱包、通道与交易 + + + + 多层钱包、交换与 DApp 连接 + + + + 用于投资组合管理的自主代理与本地 AI 大脑 + + + +--- + +## 面向开发者 + +使用我们的 SDK、API 和 AI 工具在 KaleidoSwap 上构建应用： + +### 快速上手 + + + + TypeScript 使用 `npm install kaleido-sdk`，Python 使用 `pip install kaleido-sdk`。 + [安装指南 →](/cn/sdk/getting-started) + + + + 将 `KaleidoClient.create()` 指向 signet 接口端点 —— 主网即将上线。 + [客户端参考 →](/cn/sdk/api-reference) + + + + 从做市方获取交易对和实时报价。 + [市场 API →](/cn/api-reference/market-apis) + + + + 完整跑通你的第一笔非托管原子交换。 + [如何交换 →](/cn/sdk/how-to-swap) + + + + +```typescript TypeScript +import { KaleidoClient } from 'kaleido-sdk'; + +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com' +}); + +// 获取可用的交易对 +const pairs = await client.maker.listPairs(); + +// 获取报价 +const quote = await client.maker.getQuote({ + from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: 100000 }, + to_asset: { asset_id: 'USDT', layer: 'RGB_LN' } +}); +``` + +```python Python +from kaleido_sdk import KaleidoClient + +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com" +) + +# 获取可用的交易对 +pairs = client.maker.list_pairs() + +# 获取报价 +quote = client.maker.get_quote({ + "from_asset": {"asset_id": "BTC", "layer": "BTC_LN", "amount": 100000}, + "to_asset": {"asset_id": "USDT", "layer": "RGB_LN"} +}) +``` + + +### 指南 + + + + 完整的 SDK 参考、示例与最佳实践 + + + + REST 接口端点与交换协议细节 + + + + 在终端中运行本地节点、交换和通道流程 + + + + 用于钱包操作的 MCP 服务器，以及定义特定行为的 Skills 文件 + + + +--- + +## 社区与支持 + + + + 加入我们的社区聊天 + + + + 关注我们获取最新动态 + + + + 参与项目贡献 + + + +KaleidoSwap 是采用 [MIT 许可证](https://github.com/kaleidoswap/desktop-app/blob/main/LICENSE) 的开源软件。 diff --git a/mintlify-docs/cn/whats-kaleidoswap/key-features.mdx b/mintlify-docs/cn/whats-kaleidoswap/key-features.mdx new file mode 100644 index 0000000..37d2e2c --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/key-features.mdx @@ -0,0 +1,423 @@ +--- +title: "KaleidoSwap 核心功能" +sidebarTitle: "核心功能" +description: "自主保管钱包、内置 RGB 闪电节点、本地 AI 大脑、自主交易代理、跨协议原子交换与多资产支持，构成 KaleidoSwap 的完整能力版图。" +--- + +## 核心能力 + + + + 运行你自己的多资产闪电节点，或连接到已有节点。 + + + + 在闪电网络上即时交易比特币二层资产。 + + + + 通过支付通道实现快速、低成本的交易。 + + + + 非托管架构，配合加密备份。 + + + +--- + +## 多资产管理 + +### 完整的节点控制权 + +KaleidoSwap 允许你运行自托管的 RGB 闪电节点，或连接到远程节点。 + + + + **自托管 RGB 闪电节点** + + 通过本地运行的节点，完全掌控自己的基础设施。 + + - 最大程度的隐私 + - 直接的 P2P 连接 + - 不依赖任何第三方 + + ```bash + # 配置并启动你的 RGB 闪电节点 + kaleido setup --mode local --create-node --defaults + ``` + + + + **连接远程节点** + + 连接到专业托管的节点，或你自己的远程服务器。 + + - 可从多台设备访问 + - 可选择托管式基础设施 + - 通过节点的 REST API 连接 + + + +### 节点功能 + + + + - 开通/关闭闪电通道 + - 监控通道状态 + - 重新平衡流动性 + - 设置通道策略 + + + + - 将 RGB 资产分配到通道 + - 支持多资产通道 + - 按资产路由 + - 按资产跟踪余额 + + + + - 节点状态变化后自动创建备份 + - 手动导出为加密文件 + - 将文件保存在本地磁盘或你自己的外部存储中 + - 使用助记词加备份文件即可恢复 + + + + - 实时节点监控 + - 通道状态告警 + - 支付通知 + - 性能指标 + + + +--- + +## 多协议交易 + +### 原子交换 + +无需信任、无需中间人，即时完成资产交换。 + +**支持的交换类型**： + + + + 通过闪电通道，直接用 RGB 资产（如 USDT）交换 BTC。 + + + + 用你的链上资金开通通道，立即开始交易。 + + + + 将资产从闪电通道转回链上，用于冷存储。 + + + +### 交易功能 + + + + - **做市商** —— 自动报价，与流动性提供方即时成交 + - **手动交换** —— 单笔交易中自行选择对手方和汇率 + - **DCA** —— 定期定额买入或卖出，随时间摊平持仓成本 + - **限价单** —— 设定目标汇率，仅在市场触达时执行 + + + + - 每个交易对的实时市场汇率 + - 确认前显示预计到手数量 + - 每份报价均列出汇率与费用 + - 按笔计算价格影响 + + + + - 为每笔交易设置可接受的最大滑点 + - 汇率超出限制时交换自动中止 + - 报价有时效，需在过期前确认 + + + + - 在**历史**标签页查看完整交换记录 + - 每笔交换的详细执行数据 + - 可用于对账与会计的记录 + + + + - 连接多个流动性提供方 + - 比较不同做市商的汇率 + - 手动交换时自行选择做市方 + + + + + + + 可交易资产取决于所连接的 LSP。不同 LSP 支持的资产集合可能不同。 + + +--- + +## 闪电网络集成 + +### 快速且低成本的交易 + +借助闪电网络实现高性能交易。 + + + + 交易在毫秒级完成，余额立即更新。 + + + + 费用仅为链上成本的极小一部分，让微额交易变得可行。 + + + + 执行交易不受区块链拥堵或区块空间限制。 + + + + 链下交易配合洋葱路由，隐私性更佳。 + + + +### 通道操作 + +#### 开通通道 + +1. 选择 LSP 或对等节点 +2. 选择通道容量 +3. 分配 RGB 资产（可选） +4. 设置通道参数 +5. 确认并开通 + +**通道选项**： +- **公开通道**：参与路由并赚取费用 +- **私有通道**：仅用于直接支付，隐私性更好 +- **Anchor 通道**：使用 anchor 输出提升安全性 + +#### 管理流动性 + + + + **接收支付** + + 从 LSP 获取入向流动性： + - 订购带入向容量的通道 + - 潜艇交换（submarine swaps） + - 闪电服务提供商的各类服务 + + + + **发送支付** + + 确保拥有出向容量： + - 用链上存入的资金为通道注资 + - 接收支付以积累入向容量 + - 通道再平衡服务 + + + + **优化通道** + + 平衡通道流动性： + - 通过不同路径给自己支付 + - 保持通道处于理想状态 + - 自动再平衡机器人 + + + +--- + +## 安全特性 + +### 非托管架构 + +KaleidoSwap 建立在「你的密钥，你的币」这一原则之上。 + + + 私钥永不离开你的设备 + + + 第三方无法接触你的资金 + + + 交易完全由你掌控 + + + 基于原子交换的无需信任交易协议 + + +### 安全的密钥管理 + +**加密层**： + +- **软件钱包** + - AES-256 加密 + - 密码保护 + - 助记词备份 +- **硬件钱包支持（即将推出）** + +### 通道备份 + + + + - 每次状态变化后都会备份通道 + - 每份备份都反映创建时刻的通道状态 + + + + - 备份文件使用你的节点密码加密 + - 恢复时需要用同一个密码解密 + + + + - 可保存到本地磁盘、外部硬盘或加密云存储 + - 保留多份冗余副本，确保日后仍能取用 + + + + - 使用助记词加备份文件即可恢复 + - 节点会强制关闭备份中列出的通道 + + + +### 安全最佳实践 + + + **重要安全提示**： + - 安装前务必验证二进制文件签名 + - 将助记词离线妥善保存 + - 使用强度高且唯一的密码 + - 通道发生变化后导出一份新备份 + - 保持软件更新到最新版本 + + +--- + +## AI 功能 + +### 自主代理 + + + AI 投资组合管理者与钱包操作者。监控资产配置并管理资产，且从不托管你的资金。 + + +### 本地 AI + + + 设备端 AI 助手。用日常语言获取报价、构建支付、查找联系人或完成一笔交换。 + + +### AI 工具链 + + + + 为钱包、DEX 和支付门控 API 提供带类型的工具接口，任何兼容 MCP 的客户端均可调用 + + + + `SKILL.md` 操作手册，限定代理可使用的工具范围并承载执行计划 + + + + 代理可通过闪电网络为 HTTP 402 门控的数据 API 付费，无需 API 密钥或注册 + + + +--- + +## 其他功能 + +### 用户界面 + + + + 用一组 12 个单词的种子管理所有比特币分层协议的余额，不必在多个钱包之间来回切换。 + + + + 界面支持英语、西班牙语、意大利语、德语、法语、中文、日语和韩语。 + + + + 界面简洁现代，兼顾新手与资深用户，并支持深色与浅色主题。 + + + +### 平台增强 + + + + 在容器中启动你的 RGB 闪电节点。一次配置，省去依赖烦恼。 + + + + 通过托盘控制运行，应用最小化时节点仍持续同步。 + + + + 桌面应用支持 macOS、Windows 和 Linux。浏览器扩展面向基于 Chromium 的浏览器，目前处于邀请制封闭测试阶段。 + + + +### 进阶功能 + + + + 通过 WebSocket 连接获取实时市场数据与报价更新 + + + + 将多种 RGB 资产分配到同一条闪电通道 + + + + 为公开通道设置你自己的路由费 + + + + 为闪电支付自动寻找最优路径 + + + + 创建、跟踪和管理闪电发票 + + + +### 开发者工具 + +面向在 KaleidoSwap 上构建应用的开发者： + + + + 完整的 SDK 参考、示例与最佳实践。 + + + + REST 接口端点与交换协议细节。 + + + + 在终端中运行本地节点、交换和通道流程。 + + + + 用于钱包操作的 MCP 服务器，以及定义特定行为的 Skills 文件。 + + + +--- + +## 即将推出 + + + **即将上线的功能**： + - Web 应用与移动应用（iOS 与 Android） + - 硬件钱包集成 + - 多重签名钱包支持 + - 基于意图的交易引擎与 P2P 交易引擎 + + diff --git a/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx b/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx new file mode 100644 index 0000000..424392c --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/quickstart.mdx @@ -0,0 +1,274 @@ +--- +title: "KaleidoSwap 快速开始" +sidebarTitle: "快速开始" +description: "几分钟完成 KaleidoSwap 配置并做出首笔非托管交换：安装应用、为闪电钱包充值、交易比特币二层资产。桌面应用、浏览器扩展和 SDK 三条路径任选其一。" +--- + + + + 通过桌面应用执行原子交换 + + + + 在浏览器中使用钱包并完成交换 + + + + 将 KaleidoSwap 集成到你的应用中 + + + +--- + +## 桌面应用快速开始 + + + + 下载适用于你的平台的最新版本： + + - [macOS（Apple Silicon）](https://github.com/kaleidoswap/desktop-app/releases) + - [macOS（Intel）](https://github.com/kaleidoswap/desktop-app/releases) + - [Windows](https://github.com/kaleidoswap/desktop-app/releases) + - [Linux（AppImage）](https://github.com/kaleidoswap/desktop-app/releases) + + + 安装前请务必验证二进制文件签名。[了解方法 →](/cn/desktop-app/getting-started/verify-binaries) + + + + + 启动 KaleidoSwap 并创建新钱包： + + 1. 点击「创建新钱包」(Create New Wallet) + 2. **妥善保存你的 12 个单词助记词** + 3. 设置一个强密码 + 4. 确认你的助记词 + + + **切勿分享你的助记词！** 任何拿到助记词的人都能盗走你的资金。 + + + + + 获取你的比特币地址并存入资金： + + 1. 进入「钱包」(Wallet) → 「接收」(Receive) + 2. 复制你的比特币地址 + 3. 从交易所或其他钱包向该地址发送 BTC + 4. 等待确认（通常需要 10-60 分钟） + + + + 连接到闪电服务提供商（LSP）： + + 1. 进入「通道」(Channels) → 「开通通道」(Open Channel) + 2. 选择一个 LSP，或使用默认项 + 3. 选择通道容量（建议至少 1M 聪） + 4. 选择要分配的 RGB 资产（例如 USDT） + 5. 确认并等待通道开通 + + + + 执行一笔原子交换： + + 1. 进入「交换」(Swap) 标签页 + 2. 选择资产：BTC → USDT（或反向） + 3. 输入交换数量 + 4. 查看报价 + 5. 确认交换 + 6. 等待完成（通常不到 30 秒） + + + + + **恭喜！** 你已在闪电网络上完成了第一笔 RGB 资产原子交换。 + + +--- + +## 浏览器扩展快速开始 + + + + 从你的邀请链接下载最新的封闭测试版 zip 包，然后加载到浏览器中： + + 1. 解压该 zip 压缩包 + 2. 打开 `chrome://extensions` 并启用**开发者模式** + 3. 点击**加载已解压的扩展程序**，选择解压后的文件夹 + 4. 将 KaleidoSwap 图标固定到工具栏 + + + 完整流程（含校验和验证）见：[安装指南 →](/cn/extensions/kaleidoswap-extension/installation) + + + + + 打开扩展并创建新钱包： + + 1. 选择「创建新钱包」(Create New Wallet) + 2. 设置一个安全的密码 + 3. **妥善保存你的 12 个单词助记词** + 4. 可选：注册 passkey 并配置你的 Nostr 身份 + + + **切勿分享你的助记词！** 任何拿到助记词的人都能盗走你的资金。 + + + + + 向已连接的账户存入 BTC 或其他资产： + + 1. 在仪表盘点击「存入」(Deposit) + 2. 选择一条路径：比特币链上、闪电网络、Spark、Arkade、Liquid 或 RGB + 3. 复制地址或发票，从交易所或其他钱包发送资金 + 4. 等待确认（Spark/Arkade 上即时到账，链上按出块时间） + + + + 交换需要连接一个兼容的交换场所： + + - Spark 资金池会在你的 Spark 账户充值后可用 + - 如需 RGB 交换，请在「设置」(Settings) → 「账户」(Accounts) → 「RGB」中连接一个 RGB 闪电节点（直接填写 URL 或使用 Nostr Wallet Connect） + + + + 在仪表盘执行一笔交换： + + 1. 点击「交换」(Swap) + 2. 选择**支付**与**收到**的资产 + 3. 输入数量并查看报价 + 4. 在报价过期前确认交换 + 5. 跟踪状态直至完成 + + + + + **恭喜！** 你已在 KaleidoSwap 浏览器扩展中完成了第一笔交换。 + + +--- + +## SDK 快速开始 + +### Python SDK + + + +```bash Installation +pip install kaleido-sdk +``` + +```python Basic Usage +from kaleido_sdk import KaleidoClient + +# 初始化客户端 +client = KaleidoClient.create( + base_url="https://api.signet.kaleidoswap.com", + node_url="" +) + +# 获取可用的交易对 +pairs = client.maker.list_pairs() +print(f"Available pairs: {len(pairs)}") + +# 获取 BTC 兑 USDT 的报价 +quote = client.maker.get_quote({ + "from_asset": {"asset_id": "BTC", "layer": "BTC_LN", "amount": 100000}, + "to_asset": {"asset_id": "USDT", "layer": "RGB_LN"} +}) +print(f"Quote received: {quote}") +``` + + + + + 查看完整的 SDK 文档 → + + +### TypeScript SDK + + + +```bash npm +npm install kaleido-sdk +``` + +```bash yarn +yarn add kaleido-sdk +``` + +```typescript Basic Usage +import { KaleidoClient } from 'kaleido-sdk'; + +// 初始化客户端 +const client = KaleidoClient.create({ + baseUrl: 'https://api.signet.kaleidoswap.com' +}); + +// 获取可用的交易对 +const pairs = await client.maker.listPairs(); +console.log(`Available pairs: ${pairs.length}`); + +// 获取 BTC 兑 USDT 的报价 +const quote = await client.maker.getQuote({ + from_asset: { asset_id: 'BTC', layer: 'BTC_LN', amount: 100000 }, + to_asset: { asset_id: 'USDT', layer: 'RGB_LN' } +}); +console.log(`Quote received:`, quote); +``` + + + + + 查看完整的 SDK 文档 → + + +### API 快速参考 + + + +```bash Get Trading Pairs +curl https://api.signet.kaleidoswap.com/api/v1/market/pairs +``` + +```bash Get Asset List +curl https://api.signet.kaleidoswap.com/api/v1/market/assets +``` + +```bash Request Quote +curl -X POST https://api.signet.kaleidoswap.com/api/v1/market/quote \ + -H "Content-Type: application/json" \ + -d '{ + "from_asset": {"asset_id": "BTC", "layer": "BTC_LN", "amount": 100000}, + "to_asset": {"asset_id": "USDT", "layer": "RGB_LN"} + }' +``` + + + + + 查看完整的 API 文档 → + + +--- + +## 可用网络 + + + + **API URL**：`https://api.signet.kaleidoswap.com/api/v1` + + **WebSocket**：`wss://api.signet.kaleidoswap.com/api/v1/market/ws/{client_id}` + + - Bitcoin Signet（MutinyNet）—— 条件贴近真实环境的公共测试网 + - 建议在上主网前用于集成测试 + - **目前已上线** + + + + **API URL**：`https://api.kaleidoswap.com/api/v1` + + - 比特币主网 —— 生产环境 + - **即将上线** + + diff --git a/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx b/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx new file mode 100644 index 0000000..5daf131 --- /dev/null +++ b/mintlify-docs/cn/whats-kaleidoswap/troubleshooting.mdx @@ -0,0 +1,560 @@ +--- +title: "KaleidoSwap 故障排查" +sidebarTitle: "故障排查" +description: "排查桌面应用、浏览器扩展、API 与 SDK 上的常见问题：从连接失败、交换卡住，到通道异常、资产不显示与钱包恢复，逐一给出症状与解决办法。" +--- + +## 桌面应用 + +### 安装与启动问题 + + + + **症状**：双击应用没有任何反应，或弹出错误提示。 + + **解决办法**： + 1. **macOS**：检查应用是否被 Gatekeeper 拦截 + - 打开「系统偏好设置 → 安全性与隐私」(System Preferences → Security & Privacy) + - 如果看到与 KaleidoSwap 相关的提示，点击「仍要打开」(Open Anyway) + + 2. **Windows**：以管理员身份运行 + - 右键点击应用 → 以管理员身份运行 (Run as Administrator) + - 确认 Windows Defender 没有隔离该文件 + + 3. **Linux**：检查可执行权限 + ```bash + chmod +x kaleidoswap-desktop + ``` + + 4. 检查系统要求： + - 至少 4GB 内存 + - 500MB 可用磁盘空间 + - 受支持的操作系统版本（macOS 12+、Windows 10+ 64 位、Ubuntu 22.04+） + + + + **症状**：SHA256 校验和与公布的哈希不一致。 + + **解决办法**： + 1. 从官方 [GitHub releases](https://github.com/kaleidoswap/desktop-app/releases) 重新下载应用 + 2. 确认下载的是与你的平台匹配的文件 + 3. 使用稳定的网络下载（下载损坏会导致校验和不匹配） + 4. 确认你比对的是对应版本的校验和 + + 详细步骤见[二进制文件校验](/cn/desktop-app/getting-started/verify-binaries)指南。 + + + + **症状**：应用短暂打开后立即关闭，或弹出崩溃对话框。 + + **解决办法**： + 1. 查看日志文件： + - macOS：`~/Library/Logs/com.kaleidoswap.dev/` + - Windows：`%APPDATA%\com.kaleidoswap.dev\logs` + - Linux：`~/.local/share/com.kaleidoswap.dev/logs` + + 2. 常见原因： + - **配置文件损坏**：删除配置文件后重启 + - **端口冲突**：另一个应用占用了所需端口（9735、3001） + - **依赖缺失**：重新安装应用 + + 3. 如果崩溃持续出现，在联系支持或提交 GitHub issue 时，请附上上述目录中最新的日志文件。 + + + +### 节点与连接问题 + + + + **症状**：出现 LSP 连接相关的错误提示，或无法开通通道。 + + **解决办法**： + 1. **检查网络连接** + - 确认网络连接稳定 + - 尝试访问其他网站，确认连通性 + + 2. **核对 LSP URL** + - 默认值：`https://api.signet.kaleidoswap.com` + - 在「设置 → LSP 配置」(Settings → LSP Configuration) 中检查 + + 3. **防火墙 / VPN 问题** + - 临时关闭 VPN 进行测试 + - 在防火墙中放行 KaleidoSwap + - 需要开放的端口：9735（闪电网络 P2P）、3001（节点 API） + + 4. **检查 LSP 状态** + - 访问 LSP 的状态页面，或联系支持 + - 如有其他可用的 LSP，尝试切换 + + + + **症状**：区块链同步耗时数小时，或看起来卡住了。 + + **解决办法**： + 1. **属于正常现象**：初次同步可能需要 30 分钟到数小时，取决于： + - 你的网络速度 + - 系统的磁盘速度 + - 网络拥堵情况 + + 2. **查看同步进度**： + - 在界面中查看区块高度 + - 与当前网络高度对比 + + 3. **同步卡住时的排查**： + - 重启应用 + - 检查可用磁盘空间（至少需要 10GB） + - 清空对等节点列表并重新连接 + - 确认防火墙没有拦截 P2P 连接 + + + + **症状**：提示「没有连接对等节点」(No peers connected)，或对等节点数量过少。 + + **解决办法**： + 1. **先等一会儿**：对等节点发现可能需要几分钟 + + 2. **检查网络设置**： + - 确认路由器已启用 UPnP（用于接受入向连接） + - 若 UPnP 不可用，手动转发 9735 端口 + + 3. **引导节点**： + - 应用应会自动连接引导节点 + - 若未连接，检查你的网络连接和防火墙 + + 4. **网络选择**： + - 确认你处于正确的网络（主网 / 测试网 / signet / regtest） + - 对等节点必须处于同一网络 + + + +### 钱包与资产问题 + + + + **症状**：预期有资金，但余额显示 0 或数值不对。 + + **解决办法**： + 1. **等待同步完成**：节点完全同步前不会显示余额 + 2. **确认网络正确**：确保你所在的网络就是资金所在的网络 + 3. **核对钱包恢复过程**：如果是从种子恢复的，确认使用的助记词正确 + 4. **区分资产余额与 BTC 余额**：在比特币视图和 RGB 资产视图之间切换查看 + 5. **刷新**：尝试重启应用 + + + + **症状**：密码无效，钱包始终处于锁定状态。 + + **解决办法**： + 1. **核对密码**：密码区分大小写 + 2. **大写锁定**：检查是否误开了 Caps Lock + 3. **键盘布局不同**：确认与设置密码时使用的键盘布局一致 + 4. **钱包恢复**：如果密码确实丢失，只能用助记词恢复钱包 + 5. **联系支持**：作为最后手段，带上钱包公钥联系支持（切勿分享私钥） + + + + **症状**：已收到资产，但钱包中看不到。 + + **解决办法**： + 1. **等待确认**：RGB 资产转移需要比特币确认 + 2. **导入交付包**：你可能需要手动导入 consignment 数据 + 3. **核对资产 ID**：确认你查看的是正确的资产 + 4. **刷新资产列表**：设置 → 资产 → 刷新 (Settings → Assets → Refresh) + 5. **确认发送方已完成转移**：联系发送方，确认对方已走完发送流程 + + + +### 通道操作 + + + + **症状**：通道订单失败或卡住。 + + **解决办法**： + 1. **查询订单状态**：用订单 ID 通过 API 查询，或联系支持 + + 2. **常见失败原因**： + - **资金不足**：需要覆盖通道金额加费用 + - **支付超时**：发票在支付前已过期 + - **参数无效**：检查通道大小的上下限 + - **LSP 不可用**：LSP 临时停机 + + 3. **退款流程**： + - 订单失败后，退款会自动打到你的退款地址 + - 退款可能需要 6 个以上确认才会显示 + + 4. **重试**： + - 等几分钟后再试 + - 如果已达上限，减小通道大小 + - 确认入向流动性充足 + + + + **症状**：通道存在，但无法收发支付。 + + **解决办法**： + 1. **等待确认**：通道需要区块链确认才会激活 + - 通常需要 3 到 6 个确认 + - 在通道详情中查看确认数 + + 2. **对等节点离线**：通道对端需要在线 + - 等待对端重新上线 + - 查看「最后在线」(Last Seen) 时间戳 + + 3. **通道储备金**：不能花到低于通道储备金的额度 + - 闪电通道要求保留一部分储备余额 + - 这是协议的正常行为 + + 4. **强制关闭**：如果通道彻底卡死，可以强制关闭 + - 这会在一段延迟后把资金退回链上 + - 只作为最后手段 + + + + **症状**：通道已开通，但 RGB 资产尚未交付。 + + **解决办法**： + 1. **属于正常延迟**：通过 keysend 交付资产可能需要几分钟 + - 系统内置了自动重试机制 + - 个别情况下可能长达 30 分钟 + + 2. **查看交付状态**： + - 订单详情中会显示资产交付状态 + - 状态流转：PENDING → IN_PROGRESS → COMPLETED + + 3. **手动重试**： + - 如有「重试交付」(Retry Delivery) 按钮，点击它 + + 4. **交付失败**： + - 带上订单 ID 联系 LSP 支持 + - 如果交付无法完成，可能可以退款 + + + +### 交易与交换 + + + + **症状**：交换未完成，或已过期。 + + **解决办法**： + 1. **报价过期**：询价报价的有效期很短 —— 默认约 60 秒，且每份报价都自带 `expires_at` + - 在过期前完成交换 + - 若已过期，重新请求报价 + + 2. **汇率变动**：市场汇率出现显著变化 + - 收到提示时接受新汇率 + - 或者取消并获得退款 + + 3. **支付路由失败**：闪电支付找不到路径 + - 尝试更小的金额 + - 开通更多通道以获得更多流动性 + - 稍后重试 + + 4. **交换卡住**： + - 查询交换状态：`POST /api/v1/swaps/atomic/status`（按支付哈希查询） + - 带上支付哈希联系支持寻求协助 + + + + **症状**：最终价格与预期不同。 + + **解决办法**： + 1. **核对报价细节**：仔细查看询价响应 + - `from_amount` 与 `to_amount` + - 已计入的费用 + - 资产的精度 + + 2. **费用结构**： + - 基础费用 + 浮动费用 + - 计费资产与精度 + - 报价中会显示总费用 + + 3. **精度混淆**： + - BTC 使用 8 位小数 + - USDT 通常使用 6 位小数 + - 资产精度的说明见术语表 + + 4. **滑点**： + - 市价单的价格可能小幅变动 + - 如果需要精确价格，使用限价单 + + + + + 交易失败、钱包恢复以及 LSP 连接相关的问题，见[桌面应用故障排查](/cn/desktop-app/support/troubleshooting)。 + + +## 浏览器扩展 + +下面这些情况专门针对内测版的安装方式，以及各账户的支撑方式。 + +### 安装与更新 + + + + **症状**：`chrome://extensions` 拒绝该文件夹，或原本正常的扩展过一段时间后无法加载。 + + **解决办法**： + 1. **选对文件夹**：选择包含 `manifest.json` 的那个文件夹。如果压缩包里有 `dist` 目录，就选 `dist`。 + 2. **不要移动或删除解压后的文件夹**：浏览器每次都从该路径加载扩展。把它移到别的磁盘、重命名，或清空下载目录，都会让安装失效。 + 3. **先解压**：让浏览器指向解压后的文件夹，而不是 zip 文件。 + 4. **重新添加**：在 `chrome://extensions` 中移除出问题的卡片，然后重新加载该文件夹。你的钱包并不存放在那个文件夹里，因此这不会影响你的资金。 + + + + **症状**：你安装了更新的 zip，但扩展的行为仍与旧版本一致。 + + **解决办法**： + 1. 内测版本**不会自动更新** —— 没有商店条目来推送更新。 + 2. 解压新的 zip 之后，打开 `chrome://extensions`，在 KaleidoSwap 卡片上点击**重新加载** (Reload)。 + 3. 如果你解压到了**另一个文件夹**，请移除旧的已解压扩展，改为加载新文件夹 —— 否则浏览器会继续运行旧版本。 + 4. 在**设置 > 关于** (Settings > About) 中确认版本号。 + + + + **症状**：内测 zip 完全无法加载。 + + **解决办法**： + 1. 内测版面向**基于 Chromium 的浏览器**：Chrome、Brave、Edge、Opera。 + 2. 除非专门提供了 Firefox 版本，否则 **Firefox** 不在首轮内测范围内；**Safari** 目前也还不支持。 + 3. 必须先在 `chrome://extensions` 中打开**开发者模式** (Developer mode)，**加载已解压的扩展程序** (Load unpacked) 才会出现。 + 4. 只安装来自官方邀请或支持渠道的压缩包 —— 绝不要用转发来的副本。 + + + +### 账户与余额 + + + + **症状**：原本能看到 RGB 余额，连接 RGB 闪电节点后就不见了。 + + **说明**：无需节点的 **RGB-L1** 账户与 **RLN** 账户是 RGB 资产的两种*互斥*支撑方式。连接 RLN 会替换掉无需节点的那一种，因此你看到的是另一个账户 —— RGB-L1 的状态并没有丢失。 + + **解决办法**： + 1. 在**设置 > 账户 > RGB** (Settings > Accounts > RGB) 中断开 RLN，即可回到无需节点的 RGB-L1 支撑方式。 + 2. 决定你需要哪一种支撑方式：无需节点适用于比特币 L1 上的 RGB，RLN 适用于 RGB **闪电通道**以及基于做市方的交换。 + 3. 切换之前，确认你即将离开的那一种已经完成备份 —— RGB-L1 备份到云端（VSS）和本地文件，RLN 则备份到节点自身的备份材料。 + + + + **症状**：导入助记词后 Spark、Arkade 和 Liquid 的余额都回来了，但 RGB 资产没有。 + + **解决办法**： + 1. RGB-L1 状态**不是**从助记词派生的 —— 它由加密云端（VSS）备份恢复，而且只有在你于引导步骤中**明确同意**时才会恢复。跳过该提示就会把状态留在原处。 + 2. 重新导入钱包，并在恢复提示出现时接受它。 + 3. 如果你改用 RLN，RGB 状态必须从节点自身的备份材料恢复，而不是从扩展恢复。 + + + + **症状**：你用 `nsec1…` 密钥做了恢复，结果钱包是空的。 + + **解决办法**： + 1. Nostr 密钥**并不掌控资金**。导入它只会替换 Nostr 身份。 + 2. 恢复时始终使用 **BIP39 助记词** —— 派生 Spark、Arkade、Liquid 和 RGB-L1 账户的正是它。 + 3. 用助记词重新导入；之后可以在设置中再导入 Nostr 密钥。 + + + +### 交换与跨链桥 + + + + **症状**：交换界面拒绝了一个看起来你确实持有的金额。 + + **解决办法**： + 1. 金额输入受源资产的**可花费**余额限制，而不是总余额，因此你无法按超过钱包实际可发送的金额去询价。 + 2. 链上发送还会预留网络费用 —— **最大** (Max) 会自动把这部分算进去。 + 3. 确认余额位于所选路径实际使用的那个账户上；余额是按分层分别记账的。 + + + + **症状**：已报价的交换以失败告终，而不是以更差的汇率成交。 + + **解决办法**： + 1. 这是**滑点保护**在按预期工作：最小输出量由你设置的容忍度推导得出，一旦超出，交换会直接失败而不成交。 + 2. 重新询价 —— 报价会过期，汇率也可能已经变动。 + 3. 如果市场确实波动剧烈，可以调整滑点容忍度，或者减小金额。 + + + + **症状**：你在跨链桥进行中关闭了扩展，订单不再显示在界面上。 + + **解决办法**： + 1. 跨链桥订单会**以会话形式保存在本地**。重新打开跨链桥界面会恢复待处理的订单并继续跟踪，即便 service worker 已经重启过。 + 2. 已完成和已失败的订单会显示最终状态，并附上相关的交易引用。 + 3. 存入需要先在源链上确认 —— 在此期间订单会一直处于进行中状态。 + + + + + 节点连接、支付以及 DApp provider 相关的问题，见 [KaleidoSwap 扩展故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)。 + + +## API 与集成 + +### 认证与连接 + + + + **症状**：API 返回 401 状态码。 + + **解决办法**： + 1. **Bearer token**：确认认证 token 的发送格式正确 + ```http + Authorization: Bearer YOUR_TOKEN_HERE + ``` + + 2. **Token 过期**：token 可能已过期 —— 重新获取一个 + + 3. **接口端点不对**：确认使用了正确的 API 基础 URL + - signet（已上线）：`https://api.signet.kaleidoswap.com/api/v1` + - 主网：`https://api.kaleidoswap.com/api/v1` *（即将上线）* + + + + **症状**：API 返回 422 及校验错误。 + + **解决办法**： + 1. **检查请求体**：确认所有必填字段都已提供 + 2. **数据类型**：确认整数、字符串、布尔值的类型正确 + 3. **字段校验**：检查最小值 / 最大值和格式 + 4. **阅读错误详情**：响应中会指出哪些字段校验失败 + + 错误响应示例： + ```json + { + "detail": [ + { + "loc": ["body", "from_amount"], + "msg": "field required", + "type": "value_error.missing" + } + ] + } + ``` + + + + **症状**：浏览器以 CORS 错误拦截 API 请求。 + + **解决办法**： + 1. **改用后端调用**：从你的后端而不是前端发起 API 请求 + - 出于安全考虑，大多数接口端点都禁用了 CORS + - 基于浏览器的应用需要一个后端代理 + + 2. **开发期的临时办法**： + - 使用浏览器 CORS 插件（仅限开发环境） + - 把开发服务器配置成代理 + + 3. **生产环境**：始终使用服务端 API 调用 + + + +### 询价与订单问题 + + + + **症状**：使用询价 ID 时返回过期相关的错误。 + + **解决办法**： + 1. **检查 expires_at**：报价默认约 60 秒内有效；始终读取报价自带的 `expires_at`，不要假设一个固定时长 + 2. **重新请求报价**：再次调用 `/api/v1/market/quote` + 3. **加快集成流程**：尽量缩短从报价到创建订单之间的时间 + 4. **利用过期时间**：在界面上做一个显示剩余时间的倒计时 + + + + **症状**：订单停留在 PENDING_PAYMENT 或其他状态不再推进。 + + **解决办法**： + 1. **需要支付**：检查你是否还需要支付一张发票，或向某个地址转账 + 2. **查询支付状态**： + ```bash + POST /api/v1/lsps1/get_order + { + "order_id": "your-order-id" + } + ``` + + 3. **自动流转**：部分状态会自动推进 + - PENDING_PAYMENT → PAID（支付确认后） + - CHANNEL_OPENING → COMPLETED（通道开通后） + + 4. **超时**：订单未在时限内支付就会过期 + - 检查 `expires_at` 字段 + - 未支付的订单会自动过期并退款 + + + + + 完整的 HTTP 状态码列表、错误响应格式和重试策略，见 API 参考中的[错误处理](/cn/api-reference/error-handling)。 + + +## SDK + +两份 SDK 指南都同时覆盖 TypeScript 和 Python —— 每个示例都给出两种写法。按需选择： + + + + SDK 会抛出哪些异常、如何捕获它们、重试模式，以及与 HTTP 状态码的对应关系。 + + + + 针对安装失败、连接错误、WebSocket 问题以及各语言特有的坑，逐条给出症状与解决办法。 + + + +**速查提示**： +- 捕获 `KaleidoError` —— 所有 SDK 异常都继承自它，`isRetryable()` / `is_retryable()` 会告诉你重试是否安全 +- 开启调试日志，查看完整的请求与响应细节 +- 检查运行时版本：Node.js 18+ / Python 3.10+ + +## 通用最佳实践 + + + + 大多数问题都能从日志文件中查出原因。排查时请开启调试日志。 + + + + 确认你所处的网络（主网、测试网、signet、regtest）与你的使用场景相符。 + + + + 使用最新版本的桌面应用和 SDK，以获得问题修复与功能改进。 + + + + 在主网动用真实资金之前，务必先在测试网上验证新的集成。 + + + +## 还需要帮助？ + +如果上述排查步骤没能解决你的问题： + + + + 每个产品都有自己的参考文档：[桌面应用故障排查](/cn/desktop-app/support/troubleshooting)、[KaleidoSwap 扩展故障排查](/cn/extensions/kaleidoswap-extension/troubleshooting)、[KaleidoSDK 故障排查](/cn/sdk/troubleshooting)，以及 [API 错误处理](/cn/api-reference/error-handling)。 + + + + 用搜索框在文档中查找具体主题。 + + + + 到你所运行组件对应的仓库中，看看是否已有人报告过同样的问题。所有仓库都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下。 + + + + 可通过以下方式联系我们： + - 邮箱：[support@kaleidoswap.com](mailto:support@kaleidoswap.com) + - Telegram：[https://t.me/kaleidoswap](https://t.me/kaleidoswap) + - GitHub Issues：在与你的配置相符的仓库中提交，例如[桌面应用](https://github.com/kaleidoswap/desktop-app/issues/new)、[KaleidoSDK](https://github.com/kaleidoswap/kaleido-sdk/issues/new) 或 [KaleidoCLI](https://github.com/kaleidoswap/kaleido-cli/issues/new)。 + + + + + **绝不要把私钥或助记词分享给任何人，包括支持人员。** 正规的支持渠道永远不会索要这些信息。 + diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json index 9017f2d..cf54e34 100644 --- a/mintlify-docs/docs.json +++ b/mintlify-docs/docs.json @@ -9,310 +9,636 @@ }, "favicon": "/assets/logos/kaleidoswap-favicon.ico", "navigation": { - "tabs": [ + "languages": [ { - "tab": "Overview", - "groups": [ + "language": "en", + "default": true, + "tabs": [ { - "group": "Introduction", - "icon": "flag", - "pages": [ - "whats-kaleidoswap/introduction", - "whats-kaleidoswap/quickstart", - "whats-kaleidoswap/key-features" + "tab": "Overview", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "whats-kaleidoswap/introduction", + "whats-kaleidoswap/quickstart", + "whats-kaleidoswap/key-features" + ] + }, + { + "group": "System Design", + "icon": "diagram-project", + "pages": [ + "whats-kaleidoswap/architecture", + "whats-kaleidoswap/background" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "whats-kaleidoswap/glossary", + "whats-kaleidoswap/troubleshooting" + ] + } ] }, { - "group": "System Design", - "icon": "diagram-project", - "pages": [ - "whats-kaleidoswap/architecture", - "whats-kaleidoswap/background" + "tab": "Desktop App", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "desktop-app/getting-started/introduction", + "desktop-app/getting-started/installation", + "desktop-app/getting-started/verify-binaries", + "desktop-app/getting-started/setup" + ] + }, + { + "group": "Wallet Operations", + "icon": "wallet", + "pages": [ + "desktop-app/wallet/creating-wallet", + "desktop-app/wallet/unlocking-wallet", + "desktop-app/wallet/initializing-mnemonic", + "desktop-app/wallet/deposits", + "desktop-app/wallet/withdrawals", + "desktop-app/trading/asset-swaps" + ] + }, + { + "group": "Channel Management", + "icon": "code-branch", + "pages": [ + "desktop-app/channels/opening-channel", + "desktop-app/channels/order-new-channel", + "desktop-app/channels/channel-requests", + "desktop-app/channels/channel-backups" + ] + }, + { + "group": "KaleidoMind", + "icon": "brain", + "pages": [ + "desktop-app/kaleidomind/chat", + "desktop-app/kaleidomind/brain" + ] + }, + { + "group": "Configuration", + "icon": "sliders", + "pages": [ + "desktop-app/support/settings", + "desktop-app/getting-started/node-hosting" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "desktop-app/support/changelog", + "desktop-app/support/faq", + "desktop-app/support/troubleshooting", + "desktop-app/support/additional-resources" + ] + } ] }, { - "group": "Reference", - "icon": "book", - "pages": [ - "whats-kaleidoswap/glossary", - "whats-kaleidoswap/troubleshooting" - ] - } - ] - }, - { - "tab": "Desktop App", - "groups": [ - { - "group": "Introduction", - "icon": "flag", - "pages": [ - "desktop-app/getting-started/introduction", - "desktop-app/getting-started/installation", - "desktop-app/getting-started/verify-binaries", - "desktop-app/getting-started/setup" - ] - }, - { - "group": "Wallet Operations", - "icon": "wallet", - "pages": [ - "desktop-app/wallet/creating-wallet", - "desktop-app/wallet/unlocking-wallet", - "desktop-app/wallet/initializing-mnemonic", - "desktop-app/wallet/deposits", - "desktop-app/wallet/withdrawals", - "desktop-app/trading/asset-swaps" + "tab": "Extensions", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "extensions/introduction", + "extensions/kaleidoswap-extension/installation", + "extensions/kaleidoswap-extension/getting-started" + ] + }, + { + "group": "Features", + "icon": "star", + "pages": [ + "extensions/kaleidoswap-extension/wallet-features", + "extensions/kaleidoswap-extension/swaps", + "extensions/kaleidoswap-extension/bridge", + "extensions/kaleidoswap-extension/dapp-connectivity" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "extensions/kaleidoswap-extension/faq", + "extensions/kaleidoswap-extension/troubleshooting", + "extensions/kaleidoswap-extension/additional-resources" + ] + } ] }, { - "group": "Channel Management", - "icon": "code-branch", - "pages": [ - "desktop-app/channels/opening-channel", - "desktop-app/channels/order-new-channel", - "desktop-app/channels/channel-requests", - "desktop-app/channels/channel-backups" + "tab": "AI Tools", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "ai-tools/introduction", + "ai-tools/installation", + "ai-tools/getting-started" + ] + }, + { + "group": "Tools", + "icon": "toolbox", + "pages": [ + "ai-tools/kaleido-mind", + "ai-tools/kaleido-agent", + "ai-tools/mcp-servers", + "ai-tools/skills" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "ai-tools/faq", + "ai-tools/troubleshooting", + "ai-tools/additional-resources" + ] + } ] }, { - "group": "KaleidoMind", - "icon": "brain", - "pages": [ - "desktop-app/kaleidomind/chat", - "desktop-app/kaleidomind/brain" + "tab": "SDK", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "sdk/introduction", + "sdk/getting-started" + ] + }, + { + "group": "Version & Compatibility", + "icon": "check-double", + "pages": [ + "sdk/maker-api-compatibility", + "sdk/rln-api-compatibility" + ] + }, + { + "group": "Core Reference", + "icon": "code", + "pages": [ + "sdk/api-reference", + "sdk/types", + "sdk/websocket", + "sdk/nwc" + ] + }, + { + "group": "Guides", + "icon": "book-open", + "pages": [ + "sdk/how-to-swap", + "sdk/examples", + "sdk/best-practices", + "sdk/error-handling" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "sdk/changelog", + "sdk/utilities", + "sdk/faq", + "sdk/troubleshooting", + "sdk/additional-resources" + ] + } ] }, { - "group": "Configuration", - "icon": "sliders", - "pages": [ - "desktop-app/support/settings", - "desktop-app/getting-started/node-hosting" + "tab": "CLI", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "cli/introduction", + "cli/getting-started" + ] + }, + { + "group": "Local Node Operations", + "icon": "server", + "pages": [ + "cli/node-environments", + "cli/wallet-assets-payments" + ] + }, + { + "group": "Trading & Channels", + "icon": "arrows-rotate", + "pages": [ + "cli/channels-lsp", + "cli/market-and-swaps" + ] + }, + { + "group": "Reference", + "icon": "book", + "pages": [ + "cli/command-reference" + ] + } ] }, { - "group": "Reference", - "icon": "book", - "pages": [ - "desktop-app/support/changelog", - "desktop-app/support/faq", - "desktop-app/support/troubleshooting", - "desktop-app/support/additional-resources" + "tab": "API Reference", + "groups": [ + { + "group": "Introduction", + "icon": "flag", + "pages": [ + "api-reference/introduction", + "api-reference/getting-started" + ] + }, + { + "group": "Guides", + "icon": "book-open", + "pages": [ + "api-reference/swap-protocol", + "api-reference/error-handling" + ] + }, + { + "group": "Endpoints", + "icon": "code", + "openapi": "openapi.json", + "pages": [ + "api-reference/rgb-lsps1-apis", + "api-reference/market-apis", + "api-reference/swap-apis" + ] + } ] } - ] - }, - { - "tab": "Extensions", - "groups": [ - { - "group": "Introduction", - "icon": "flag", - "pages": [ - "extensions/introduction", - "extensions/kaleidoswap-extension/installation", - "extensions/kaleidoswap-extension/getting-started" - ] - }, - { - "group": "Features", - "icon": "star", - "pages": [ - "extensions/kaleidoswap-extension/wallet-features", - "extensions/kaleidoswap-extension/swaps", - "extensions/kaleidoswap-extension/bridge", - "extensions/kaleidoswap-extension/dapp-connectivity" - ] - }, - { - "group": "Reference", - "icon": "book", - "pages": [ - "extensions/kaleidoswap-extension/faq", - "extensions/kaleidoswap-extension/troubleshooting", - "extensions/kaleidoswap-extension/additional-resources" - ] - } - ] - }, - { - "tab": "AI Tools", - "groups": [ - { - "group": "Introduction", - "icon": "flag", - "pages": [ - "ai-tools/introduction", - "ai-tools/installation", - "ai-tools/getting-started" - ] - }, - { - "group": "Tools", - "icon": "toolbox", - "pages": [ - "ai-tools/kaleido-mind", - "ai-tools/kaleido-agent", - "ai-tools/mcp-servers", - "ai-tools/skills" - ] - }, - { - "group": "Reference", - "icon": "book", - "pages": [ - "ai-tools/faq", - "ai-tools/troubleshooting", - "ai-tools/additional-resources" - ] - } - ] + ], + "global": { + "anchors": [ + { + "anchor": "Access Extension Beta", + "href": "https://kaleidoswap.com/products/extension/beta", + "icon": "puzzle-piece" + }, + { + "anchor": "Download Desktop App", + "href": "https://github.com/kaleidoswap/desktop-app/releases", + "icon": "download" + }, + { + "anchor": "Website", + "href": "https://kaleidoswap.com", + "icon": "globe" + }, + { + "anchor": "GitHub", + "href": "https://github.com/kaleidoswap", + "icon": "github" + } + ] + } }, { - "tab": "SDK", - "groups": [ - { - "group": "Introduction", - "icon": "flag", - "pages": [ - "sdk/introduction", - "sdk/getting-started" - ] - }, - { - "group": "Version & Compatibility", - "icon": "check-double", - "pages": [ - "sdk/maker-api-compatibility", - "sdk/rln-api-compatibility" - ] - }, - { - "group": "Core Reference", - "icon": "code", - "pages": [ - "sdk/api-reference", - "sdk/types", - "sdk/websocket", - "sdk/nwc" - ] - }, + "language": "cn", + "tabs": [ { - "group": "Guides", - "icon": "book-open", - "pages": [ - "sdk/how-to-swap", - "sdk/examples", - "sdk/best-practices", - "sdk/error-handling" + "tab": "概览", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/whats-kaleidoswap/introduction", + "cn/whats-kaleidoswap/quickstart", + "cn/whats-kaleidoswap/key-features" + ] + }, + { + "group": "系统设计", + "icon": "diagram-project", + "pages": [ + "cn/whats-kaleidoswap/architecture", + "cn/whats-kaleidoswap/background" + ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/whats-kaleidoswap/glossary", + "cn/whats-kaleidoswap/troubleshooting" + ] + } ] }, { - "group": "Reference", - "icon": "book", - "pages": [ - "sdk/changelog", - "sdk/utilities", - "sdk/faq", - "sdk/troubleshooting", - "sdk/additional-resources" - ] - } - ] - }, - { - "tab": "CLI", - "groups": [ - { - "group": "Introduction", - "icon": "flag", - "pages": [ - "cli/introduction", - "cli/getting-started" + "tab": "桌面应用", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/desktop-app/getting-started/introduction", + "cn/desktop-app/getting-started/installation", + "cn/desktop-app/getting-started/verify-binaries", + "cn/desktop-app/getting-started/setup" + ] + }, + { + "group": "钱包操作", + "icon": "wallet", + "pages": [ + "cn/desktop-app/wallet/creating-wallet", + "cn/desktop-app/wallet/unlocking-wallet", + "cn/desktop-app/wallet/initializing-mnemonic", + "cn/desktop-app/wallet/deposits", + "cn/desktop-app/wallet/withdrawals", + "cn/desktop-app/trading/asset-swaps" + ] + }, + { + "group": "通道管理", + "icon": "code-branch", + "pages": [ + "cn/desktop-app/channels/opening-channel", + "cn/desktop-app/channels/order-new-channel", + "cn/desktop-app/channels/channel-requests", + "cn/desktop-app/channels/channel-backups" + ] + }, + { + "group": "KaleidoMind", + "icon": "brain", + "pages": [ + "cn/desktop-app/kaleidomind/chat", + "cn/desktop-app/kaleidomind/brain" + ] + }, + { + "group": "配置", + "icon": "sliders", + "pages": [ + "cn/desktop-app/support/settings", + "cn/desktop-app/getting-started/node-hosting" + ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/desktop-app/support/changelog", + "cn/desktop-app/support/faq", + "cn/desktop-app/support/troubleshooting", + "cn/desktop-app/support/additional-resources" + ] + } ] }, { - "group": "Local Node Operations", - "icon": "server", - "pages": [ - "cli/node-environments", - "cli/wallet-assets-payments" + "tab": "浏览器扩展", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/extensions/introduction", + "cn/extensions/kaleidoswap-extension/installation", + "cn/extensions/kaleidoswap-extension/getting-started" + ] + }, + { + "group": "功能", + "icon": "star", + "pages": [ + "cn/extensions/kaleidoswap-extension/wallet-features", + "cn/extensions/kaleidoswap-extension/swaps", + "cn/extensions/kaleidoswap-extension/bridge", + "cn/extensions/kaleidoswap-extension/dapp-connectivity" + ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/extensions/kaleidoswap-extension/faq", + "cn/extensions/kaleidoswap-extension/troubleshooting", + "cn/extensions/kaleidoswap-extension/additional-resources" + ] + } ] }, { - "group": "Trading & Channels", - "icon": "arrows-rotate", - "pages": [ - "cli/channels-lsp", - "cli/market-and-swaps" + "tab": "AI 工具", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/ai-tools/introduction", + "cn/ai-tools/installation", + "cn/ai-tools/getting-started" + ] + }, + { + "group": "工具", + "icon": "toolbox", + "pages": [ + "cn/ai-tools/kaleido-mind", + "cn/ai-tools/kaleido-agent", + "cn/ai-tools/mcp-servers", + "cn/ai-tools/skills" + ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/ai-tools/faq", + "cn/ai-tools/troubleshooting", + "cn/ai-tools/additional-resources" + ] + } ] }, { - "group": "Reference", - "icon": "book", - "pages": [ - "cli/command-reference" - ] - } - ] - }, - { - "tab": "API Reference", - "groups": [ - { - "group": "Introduction", - "icon": "flag", - "pages": [ - "api-reference/introduction", - "api-reference/getting-started" + "tab": "SDK", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/sdk/introduction", + "cn/sdk/getting-started" + ] + }, + { + "group": "版本与兼容性", + "icon": "check-double", + "pages": [ + "cn/sdk/maker-api-compatibility", + "cn/sdk/rln-api-compatibility" + ] + }, + { + "group": "核心参考", + "icon": "code", + "pages": [ + "cn/sdk/api-reference", + "cn/sdk/types", + "cn/sdk/websocket", + "cn/sdk/nwc" + ] + }, + { + "group": "指南", + "icon": "book-open", + "pages": [ + "cn/sdk/how-to-swap", + "cn/sdk/examples", + "cn/sdk/best-practices", + "cn/sdk/error-handling" + ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/sdk/changelog", + "cn/sdk/utilities", + "cn/sdk/faq", + "cn/sdk/troubleshooting", + "cn/sdk/additional-resources" + ] + } ] }, { - "group": "Guides", - "icon": "book-open", - "pages": [ - "api-reference/swap-protocol", - "api-reference/error-handling" + "tab": "CLI", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/cli/introduction", + "cn/cli/getting-started" + ] + }, + { + "group": "本地节点操作", + "icon": "server", + "pages": [ + "cn/cli/node-environments", + "cn/cli/wallet-assets-payments" + ] + }, + { + "group": "交易与通道", + "icon": "arrows-rotate", + "pages": [ + "cn/cli/channels-lsp", + "cn/cli/market-and-swaps" + ] + }, + { + "group": "参考", + "icon": "book", + "pages": [ + "cn/cli/command-reference" + ] + } ] }, { - "group": "Endpoints", - "icon": "code", - "openapi": "openapi.json", - "pages": [ - "api-reference/rgb-lsps1-apis", - "api-reference/market-apis", - "api-reference/swap-apis" + "tab": "API 参考", + "groups": [ + { + "group": "简介", + "icon": "flag", + "pages": [ + "cn/api-reference/introduction", + "cn/api-reference/getting-started" + ] + }, + { + "group": "指南", + "icon": "book-open", + "pages": [ + "cn/api-reference/swap-protocol", + "cn/api-reference/error-handling" + ] + }, + { + "group": "接口端点", + "icon": "code", + "openapi": "openapi.json", + "pages": [ + "cn/api-reference/rgb-lsps1-apis", + "cn/api-reference/market-apis", + "cn/api-reference/swap-apis" + ] + } ] } - ] - } - ], - "global": { - "anchors": [ - { - "anchor": "Access Extension Beta", - "href": "https://kaleidoswap.com/products/extension/beta", - "icon": "puzzle-piece" - }, - { - "anchor": "Download Desktop App", - "href": "https://github.com/kaleidoswap/desktop-app/releases", - "icon": "download" - }, - { - "anchor": "Website", - "href": "https://kaleidoswap.com", - "icon": "globe" + ], + "global": { + "anchors": [ + { + "anchor": "体验扩展 Beta", + "href": "https://kaleidoswap.com/products/extension/beta", + "icon": "puzzle-piece" + }, + { + "anchor": "下载桌面应用", + "href": "https://github.com/kaleidoswap/desktop-app/releases", + "icon": "download" + }, + { + "anchor": "官网", + "href": "https://kaleidoswap.com", + "icon": "globe" + }, + { + "anchor": "GitHub", + "href": "https://github.com/kaleidoswap", + "icon": "github" + } + ] }, - { - "anchor": "GitHub", - "href": "https://github.com/kaleidoswap", - "icon": "github" + "navbar": { + "links": [ + { + "label": "技术支持", + "href": "https://docs.google.com/forms/d/e/1FAIpQLSewf4-AJZxuoI878-TRex91kRH04l-9s5XC51UHW6140xXKVA/viewform" + } + ], + "primary": { + "type": "button", + "label": "下载应用", + "href": "https://kaleidoswap.com/products" + } } - ] - } + } + ] }, "logo": { "light": "/assets/logos/kaleidoswap-full-logo-horizontal-onlight.svg", diff --git a/scripts/check-cn-parity.py b/scripts/check-cn-parity.py new file mode 100644 index 0000000..c668719 --- /dev/null +++ b/scripts/check-cn-parity.py @@ -0,0 +1,254 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""Check the Simplified Chinese docs tree against the English sources. + +Run from anywhere in the repo: + + python scripts/check-cn-parity.py + +Verifies, for the `cn` language declared in mintlify-docs/docs.json: + + 1. Coverage — every page in the cn navigation exists on disk. + 2. Parity — each page matches its English source on heading count, + code fences, MDX components, table rows and images. + 3. Links — every internal link is /cn-prefixed and resolves to a page + that is actually in the cn navigation. + 4. Anchors — every link fragment resolves to a heading id in the target + page, whether pinned with {#id} or generated from the text. + 5. Frontmatter — title and description present, and title actually translated. + +Exits non-zero if anything is wrong, so it can gate a PR. + +See TRANSLATION-GUIDE.md for the rules this enforces. +""" +from __future__ import print_function + +import io +import json +import os +import re +import sys + +try: + from urllib.parse import unquote +except ImportError: # py2 + from urllib import unquote + +# the Windows console defaults to cp1252 and dies on CJK output +try: + sys.stdout.reconfigure(encoding="utf-8", errors="replace") +except AttributeError: + pass + +REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +ROOT = os.path.join(REPO, "mintlify-docs") +DOCS_JSON = os.path.join(ROOT, "docs.json") +LANG = "cn" + +CJK = "[一-鿿]" + +# titles that are nothing but product names / acronyms correctly stay English +PROPER_ONLY = re.compile( + r"^(?:Kaleido\w*|KaleidoSwap|Nostr|Wallet|Connect|SDK|CLI|API|NWC|RGB|MCP|" + r"LSPS1|RLN|Bitcoin|Lightning|FAQ|WebSocket|REST|Taproot|Assets|" + r"[-–&/()0-9.]+)(?:\s+|$)" +) + + +def read(p): + with io.open(p, encoding="utf-8") as f: + return f.read() + + +def strip_code(text): + return re.sub(r"```.*?```", "", text, flags=re.S) + + +def headings(text): + """Ordered [(level, title, pinned_id)] outside code fences.""" + out = [] + in_fence = False + for line in text.splitlines(): + if re.match(r"^\s*```", line): + in_fence = not in_fence + continue + if in_fence: + continue + m = re.match(r"^(#{1,6})\s+(.*?)\s*$", line) + if not m: + continue + title = m.group(2) + idm = re.search(r"\s*\{#([^}]*)\}\s*$", title) + pinned = idm.group(1) if idm else None + if idm: + title = title[: idm.start()].rstrip() + out.append((len(m.group(1)), title, pinned)) + return out + + +def slugify(title): + """Mintlify's heading -> anchor rules, validated against the English docs.""" + s = title.strip().lower() + s = s.replace("`", "").replace("*", "").replace("_", " ") + s = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", s) + s = re.sub(r"[:().,?!'\"|<>{}\[\]+=;$#@~^]", "", s) + s = s.replace(".", "-") + s = re.sub(r"\s+", "-", s.strip()) + s = re.sub(r"-{2,}", "-", s) + return s.strip("-") + + +def counts(text): + body = strip_code(text) + return { + "headings": len(headings(text)), + "fences": text.count("```"), + "images": len(re.findall(r"!\[[^\]]*\]\(", body)), + "table_rows": len([l for l in body.splitlines() if l.strip().startswith("|")]), + "components": len(re.findall(r"<([A-Z][A-Za-z]*)", body)), + } + + +def collect(node, acc): + if isinstance(node, list): + for n in node: + collect(n, acc) + elif isinstance(node, str): + acc.append(node) + elif isinstance(node, dict): + for k in ("tabs", "groups", "pages"): + if k in node: + collect(node[k], acc) + + +def path_of(page): + return os.path.join(ROOT, page.replace("/", os.sep) + ".mdx") + + +def main(): + doc = json.loads(read(DOCS_JSON)) + try: + langs = {l["language"]: l for l in doc["navigation"]["languages"]} + except KeyError: + print("docs.json has no navigation.languages — nothing to check") + return 0 + if LANG not in langs: + print("docs.json declares no '%s' language — nothing to check" % LANG) + return 0 + + default = [k for k, v in langs.items() if v.get("default")] or ["en"] + en_pages, cn_pages = [], [] + collect(langs[default[0]]["tabs"], en_pages) + collect(langs[LANG]["tabs"], cn_pages) + + errors, missing, parity, fm_issues, bad_links, anchors, thin = [], [], [], [], [], [], [] + + if len(en_pages) != len(cn_pages): + errors.append( + "navigation page count differs: %s=%d %s=%d" + % (default[0], len(en_pages), LANG, len(cn_pages)) + ) + + cn_set = set(cn_pages) + pair = dict(zip(cn_pages, en_pages)) + + # ---------------------------------------------------- coverage and parity + for cn_page, en_page in zip(cn_pages, en_pages): + cn_path, en_path = path_of(cn_page), path_of(en_page) + if not os.path.exists(cn_path): + missing.append(cn_page) + continue + if not os.path.exists(en_path): + errors.append("english source missing for %s" % en_page) + continue + ec, cc = counts(read(en_path)), counts(read(cn_path)) + diffs = {k: (ec[k], cc[k]) for k in ec if ec[k] != cc[k]} + if diffs: + parity.append((cn_page, diffs)) + + # -------------------------------------------------------- heading id index + ids = {} + for cn_page in cn_pages: + p = path_of(cn_page) + if not os.path.exists(p): + continue + s = set() + for _, title, pinned in headings(read(p)): + s.add(pinned if pinned else slugify(title)) + ids[cn_page] = s + + # ---------------------------------------------------- links and frontmatter + LINK = re.compile(r"\]\((/[^)\s]*)\)") + for cn_page in cn_pages: + p = path_of(cn_page) + if not os.path.exists(p): + continue + text = read(p) + + for target in sorted(set(LINK.findall(text))): + path, _, frag = target.partition("#") + path = path.rstrip("/") + if path.startswith("/assets/") or path.startswith("/snippets/"): + continue + if path and not path.startswith("/%s/" % LANG): + bad_links.append((cn_page, target, "not /%s-prefixed" % LANG)) + continue + page = path[1:] if path else cn_page + if page and page not in cn_set: + bad_links.append((cn_page, target, "target not in %s navigation" % LANG)) + continue + if not frag: + continue + tgt = page or cn_page + if unquote(frag) not in ids.get(tgt, set()): + anchors.append((cn_page, target, "fragment not a heading id in target")) + + if not text.startswith("---"): + fm_issues.append((cn_page, "no frontmatter")) + else: + fm = text[3 : text.find("\n---", 3)] + if "title:" not in fm: + fm_issues.append((cn_page, "no title")) + if "description:" not in fm: + fm_issues.append((cn_page, "no description")) + m = re.search(r'^title:\s*[\'"]?(.*?)[\'"]?\s*$', fm, re.M) + if m and not re.search(CJK, m.group(1)): + # parenthesised acronyms are part of the proper name + rest = m.group(1).replace("(", " ").replace(")", " ").strip() + while rest: + mm = PROPER_ONLY.match(rest) + if not mm: + break + rest = rest[mm.end():].strip() + if rest: + fm_issues.append( + (cn_page, "title looks untranslated: %s" % m.group(1)) + ) + + if len(re.findall(CJK, strip_code(text))) < 20: + thin.append(cn_page) + + # ------------------------------------------------------------------ report + def section(name, items, limit=40): + print("\n== %s: %d ==" % (name, len(items))) + for it in items[:limit]: + print(" ", it) + if len(items) > limit: + print(" ... and %d more" % (len(items) - limit)) + + print("pages in %s navigation: %d" % (LANG, len(cn_pages))) + section("hard errors", errors) + section("missing files", missing) + section("structural parity issues", parity) + section("frontmatter issues", fm_issues) + section("bad links", bad_links) + section("unresolved anchors", anchors) + section("suspiciously untranslated", thin) + + fatal = errors or missing or parity or bad_links or anchors + print("\nRESULT: %s" % ("PROBLEMS FOUND" if fatal else "OK")) + return 1 if fatal else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/pin-cn-anchors.py b/scripts/pin-cn-anchors.py new file mode 100644 index 0000000..f48ee60 --- /dev/null +++ b/scripts/pin-cn-anchors.py @@ -0,0 +1,253 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""Pin explicit anchor ids on translated headings that links point at. + + python scripts/pin-cn-anchors.py # dry run, reports what it would do + python scripts/pin-cn-anchors.py --apply # write the ids + +Mintlify derives a heading's anchor from its text, so translating a heading +breaks every link aimed at it. Instead of rewriting each link fragment to a +guessed Chinese slug, this pins the original English slug onto the translated +heading using Mintlify's `{#custom-id}` syntax: + + ## 客户端配置 {#client-configuration} + +The link then stays `](/cn/ai-tools/mcp-servers#client-configuration)` and keeps +resolving no matter how the heading text is later reworded. + +Which heading to pin is decided by POSITION: the nth heading of the English page +corresponds to the nth heading of its translation. So translated pages must keep +headings in the same order and count as their source — which is what +scripts/check-cn-parity.py enforces. + +Only headings that actually receive a link get an id. + +See TRANSLATION-GUIDE.md. +""" +from __future__ import print_function + +import io +import json +import os +import re +import sys + +try: + from urllib.parse import unquote +except ImportError: # py2 + from urllib import unquote + +try: + sys.stdout.reconfigure(encoding="utf-8", errors="replace") +except AttributeError: + pass + +REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +ROOT = os.path.join(REPO, "mintlify-docs") +DOCS_JSON = os.path.join(ROOT, "docs.json") +LANG = "cn" +APPLY = "--apply" in sys.argv + + +def read(p): + with io.open(p, encoding="utf-8") as f: + return f.read() + + +def write(p, s): + with io.open(p, "w", encoding="utf-8", newline="\n") as f: + f.write(s) + + +def heading_lines(text): + """Ordered [(line_index, level, title, pinned_id)] outside code fences.""" + out = [] + in_fence = False + for i, line in enumerate(text.splitlines()): + if re.match(r"^\s*```", line): + in_fence = not in_fence + continue + if in_fence: + continue + m = re.match(r"^(#{1,6})\s+(.*?)\s*$", line) + if not m: + continue + title = m.group(2) + idm = re.search(r"\s*\{#([^}]*)\}\s*$", title) + pinned = idm.group(1) if idm else None + if idm: + title = title[: idm.start()].rstrip() + out.append((i, len(m.group(1)), title, pinned)) + return out + + +def safe_id(frag): + """Normalise a fragment to characters whose handling is unambiguous. + + Mintlify preserves `&` when it generates a slug from heading text, but how it + treats `&` inside an explicit {#id} is not documented. Since both the id and + the link live in the translated tree, we sidestep the question: pin an id + with no ambiguous characters and rewrite the links to match. + """ + s = frag.replace("&", "and") + s = re.sub(r"[^0-9a-z一-鿿-]+", "-", s) + s = re.sub(r"-{2,}", "-", s) + return s.strip("-") + + +def slugify(title): + """Mintlify's heading -> anchor rules, validated against the English docs.""" + s = title.strip().lower() + s = s.replace("`", "").replace("*", "").replace("_", " ") + s = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", s) + s = re.sub(r"[:().,?!'\"|<>{}\[\]+=;$#@~^]", "", s) + s = s.replace(".", "-") + s = re.sub(r"\s+", "-", s.strip()) + s = re.sub(r"-{2,}", "-", s) + return s.strip("-") + + +def collect(node, acc): + if isinstance(node, list): + for n in node: + collect(n, acc) + elif isinstance(node, str): + acc.append(node) + elif isinstance(node, dict): + for k in ("tabs", "groups", "pages"): + if k in node: + collect(node[k], acc) + + +def path_of(page): + return os.path.join(ROOT, page.replace("/", os.sep) + ".mdx") + + +def main(): + doc = json.loads(read(DOCS_JSON)) + langs = {l["language"]: l for l in doc["navigation"]["languages"]} + default = [k for k, v in langs.items() if v.get("default")] or ["en"] + + en_pages, cn_pages = [], [] + collect(langs[default[0]]["tabs"], en_pages) + collect(langs[LANG]["tabs"], cn_pages) + pair = dict(zip(cn_pages, en_pages)) + + # ------------------------------------------ which fragments are asked for + LINK = re.compile(r"\]\((/[^)\s]*#[^)\s]*)\)") + needed = {} + for cn_page in cn_pages: + p = path_of(cn_page) + if not os.path.exists(p): + continue + for target in LINK.findall(read(p)): + path, _, frag = target.partition("#") + path = path.rstrip("/") + if path.startswith("/assets/") or path.startswith("/snippets/"): + continue + tgt = path[1:] if path else cn_page + if tgt not in pair: + print("WARN link to unknown page: %s (in %s)" % (target, cn_page)) + continue + needed.setdefault(tgt, set()).add(unquote(frag)) + + pinned = 0 + already = 0 + unresolved = [] + # target page -> [(original fragment, normalised id)] for links to follow + rewrites = {} + + for cn_page, frags in sorted(needed.items()): + cn_path, en_path = path_of(cn_page), path_of(pair[cn_page]) + if not (os.path.exists(cn_path) and os.path.exists(en_path)): + unresolved.append((cn_page, sorted(frags), "file missing")) + continue + cn_text = read(cn_path) + en_h = heading_lines(read(en_path)) + cn_h = heading_lines(cn_text) + if len(en_h) != len(cn_h): + unresolved.append( + (cn_page, sorted(frags), + "heading count differs: en=%d cn=%d" % (len(en_h), len(cn_h))) + ) + continue + + # index by raw slug and by normalised slug, so a fragment this script + # already normalised on an earlier run still finds its heading + en_slug_idx = {} + for idx, (_, _, title, _) in enumerate(en_h): + slug = slugify(title) + en_slug_idx.setdefault(slug, idx) + en_slug_idx.setdefault(safe_id(slug), idx) + + lines = cn_text.splitlines() + changed = False + for frag in sorted(frags): + idx = en_slug_idx.get(frag) + if idx is None: + unresolved.append((cn_page, frag, "no english heading matches")) + continue + li, level, title, existing = cn_h[idx] + wanted = safe_id(frag) + if existing == wanted: + already += 1 + if wanted != frag: + rewrites.setdefault(cn_page, []).append((frag, wanted)) + continue + if existing and existing != frag: + unresolved.append( + (cn_page, frag, "heading already pinned to #%s" % existing) + ) + continue + lines[li] = "%s %s {#%s}" % ("#" * level, title, wanted) + cn_h[idx] = (li, level, title, wanted) + changed = True + pinned += 1 + note = "" if wanted == frag else " (normalised from #%s)" % frag + print("pin %-50s #%-40s %s%s" % (cn_page, wanted, title, note)) + if wanted != frag: + rewrites.setdefault(cn_page, []).append((frag, wanted)) + if changed and APPLY: + write(cn_path, "\n".join(lines) + ("\n" if cn_text.endswith("\n") else "")) + + # ------------------------- point links at the ids we actually pinned + link_fixes = 0 + if rewrites: + try: + from urllib.parse import quote + except ImportError: + from urllib import quote + for cn_page in cn_pages: + p = path_of(cn_page) + if not os.path.exists(p): + continue + text = original = read(p) + for tgt, pairs in rewrites.items(): + for frag, wanted in pairs: + for encoded in {frag, quote(frag, safe="-")}: + for base in ("/" + tgt, ""): + old = "](%s#%s)" % (base, encoded) + if old in text: + text = text.replace( + old, "](%s#%s)" % (base, wanted) + ) + link_fixes += text.count("](%s#%s)" % (base, wanted)) + if text != original: + print("link %s -> normalised fragment(s)" % cn_page) + if APPLY: + write(p, text) + + print("\npinned: %d already pinned: %d links repointed: %d%s" + % (pinned, already, link_fixes, + "" if APPLY else " (dry run — pass --apply)")) + if unresolved: + print("\nUNRESOLVED: %d" % len(unresolved)) + for u in unresolved: + print(" ", u) + return 1 + print("all anchor targets resolved") + return 0 + + +if __name__ == "__main__": + sys.exit(main())