> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KaleidoSwap 架构解析

> 拆解 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) 上查阅；浏览器扩展和做市方的询价引擎目前尚未开源。

## 集成层

应用与协议之间有两个软件包。我们自家的客户端使用它们的方式，与外部集成方完全一致。

<CardGroup cols={2}>
  <Card title="kaleido-sdk" icon="code" href="/cn/sdk/introduction">
    交换集成：报价、交易对、询价流式推送、交换执行、LSPS1 通道订单，以及对 RGB 闪电节点的直接访问。目前提供 TypeScript 与 Python 版本，Rust 核心正在开发中。
  </Card>

  <Card title="wallet-engine" icon="wallet" href="https://github.com/kaleidoswap/wallet-engine">
    无界面的多协议钱包内核：协议适配器、跨协议路由器、统一接收，以及精简/进阶两档信息披露。采用 TypeScript，可运行在浏览器、React Native 和 Node 环境中。
  </Card>
</CardGroup>

`kaleido-sdk` 暴露两个子客户端 —— 面向市场侧的 `client.maker` 和面向节点操作的 `client.rln` —— 并根据后端提供的同一份 [OpenAPI 规范](https://github.com/kaleidoswap/specs)生成类型，因此 TypeScript 和 Python 版本永远不会脱节。

<img src="https://mintcdn.com/kaleidoswap/jZkXeFEXDE4-8PkF/assets/images/overview/sdk-architecture.png?fit=max&auto=format&n=jZkXeFEXDE4-8PkF&q=85&s=dde2d2f3bee7f4a664ed4e0754b5eee1" alt="抽象示意图：代码编辑器连接到 TypeScript 与 Python 两条路径，各自指向闪电符号与齿轮图标，最终汇入云服务与服务器机架" width="2752" height="1536" data-path="assets/images/overview/sdk-architecture.png" />

## 协议层

每个比特币分层协议都有自己的 SDK、地址格式和各种特殊之处：这个协议讲通道流动性，那个协议讲上船交易，另一个又用静态接收地址。如果不加治理，这些差异就会变成每个应用每个页面上的协议判断分支。

我们的做法是让每个协议实现**同一套适配器契约**：连接、列出资产与交易、创建与解析发票、发送、接收，以及可选的报价与交换执行。协议之间的差异以能力清单中的**数据**形式存在，而不是应用代码里的分支。路由器和界面读取该清单，永不按协议名称做特殊处理。

由此带来的实际好处：

* **接入新协议只需改动一个适配器**和一条清单记录 —— 绝不触碰其他协议的代码路径。
* **客户端只调用一套 API**，从不直接调用协议 SDK，因此桌面端、扩展和移动端的行为保持一致。
* **由路由器选择通道。** 给定一个目标 —— 闪电发票、比特币地址、RGB 发票或 Liquid 地址 —— 它会判断哪些协议可以支付，以及哪一个最合适。
* **一个接收二维码**可同时承载多个协议，任何钱包都能扫码支付，而 KaleidoSwap 钱包还能读取其中更丰富的参数。

## 交换引擎

交换采用**询价**（Request for Quote）模型，由哈希锁定合约完成结算。做市方给出价格；闪电网络负责传输；共享的原像保证交换的原子性。

<img src="https://mintcdn.com/kaleidoswap/jZkXeFEXDE4-8PkF/assets/images/overview/architecture-overview.png?fit=max&auto=format&n=jZkXeFEXDE4-8PkF&q=85&s=827899baffc0f2d4c37834a21c558c24" alt="示意图：桌面端、浏览器和扩展客户端连接到 RGB 闪电节点与闪电服务提供商，两者又连向代表比特币结算的哈希锁定区块链条" width="2752" height="1536" data-path="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)。

<Note>
  原子性取决于两个层级都具备原生哈希锁。关于目前哪些路径符合、哪些不符合，见 [Where atomicity holds](/cn/whats-kaleidoswap/background#where-atomicity-holds)。
</Note>

## 流动性层

### 闪电服务提供商

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 入口同样是这套技术栈的客户端。它们调用的工具与人机界面调用的完全相同，也受同样的确认环节约束。

<CardGroup cols={2}>
  <Card title="KaleidoMind" icon="brain" href="/cn/ai-tools/kaleido-mind">
    本地优先的推理与工具调用引擎。推理在设备端运行；任何会动用资金的工具都需要明确确认，模型无法绕过。
  </Card>

  <Card title="KaleidoAgent" icon="robot" href="/cn/ai-tools/kaleido-agent">
    用于投资组合与节点管理的自主代理。可基于本地模型或托管模型运行，且从不托管资金。
  </Card>
</CardGroup>

<h2 id="client-architecture">
  客户端架构
</h2>

### 非托管设计

所有涉及密钥的环节都在你的设备上运行。客户端在本地持有或驱动钱包，自行验证状态，只通过上述网络接口与做市方和 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 连接

## 安全模型

<Steps>
  <Step title="比特币基础层">
    在比特币区块链上完成最终结算并锚定安全性
  </Step>

  <Step title="分层协议">
    哈希锁定合约与时间锁，让失败的交换退款而不是执行一半
  </Step>

  <Step title="资产叠加层">
    在客户端验证 RGB 状态，阻止无效或双花的转移
  </Step>

  <Step title="应用层">
    本地密钥管理、加密存储，以及任何支出前的明确确认
  </Step>
</Steps>

### 这里的「无需信任」指什么

* **没有对手方风险** —— 在原子路径上，交换要么双方都完成，要么都不完成
* **没有托管方** —— 全程由你保管自己的密钥和资产
* **密码学保证** —— 由时间锁和原像强制执行

## 结算特性

不同的层做出不同的取舍，这也是这套技术栈同时使用多个层的原因。不存在一个层能同时做到最快、最便宜且最终性最强。

| 层级         | 结算形式                     | 原生哈希锁           | 最终性                 | 典型成本                    |
| ---------- | ------------------------ | --------------- | ------------------- | ----------------------- |
| **比特币 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)。