DApp 连接

概览

KaleidoSwap 扩展会把标准钱包提供方注入浏览器页面，DApp 在获得用户授权后即可调用钱包能力。它沿用与其他浏览器钱包（例如 Alby）相同的提供方约定，因此大多数现有的 WebLN、WebBTC 和 Nostr 应用无需为 KaleidoSwap 做任何专门集成即可使用。扩展注入以下对象：

window.webln — 面向 Lightning 的 WebLN 提供方（发票、支付、消息签名、keysend、LNURL）。
window.webbtc — 面向链上比特币的 WebBTC 提供方（地址、PSBT 签名、BIP-322 消息签名、广播）。
window.nostr — 完整的 NIP-07 提供方，用于 Nostr 事件签名与加密。
window.bitcoin — Bitcoin Wallet Standard 提供方（Unisat／OKX／Leather 风格），部分 DApp 会探测它来获取链上账户。
window.rgb — KaleidoSwap 专有的 RGB 资产提供方：发行、接收、发送和跟踪资产；接入闪电节点后还可通过闪电网络收付资产。

工作原理

KaleidoSwap 扩展的内容脚本被注入网页
内容脚本加载注入脚本，添加 window.webln、window.webbtc、window.nostr、window.bitcoin 和 window.rgb
DApp 调用这些提供方上的方法
请求被路由到 KaleidoSwap 扩展的后台 service worker
敏感操作会触发确认或权限提示

提供方就绪事件

提供方安装完成后，注入脚本会派发就绪事件（同时提供带冒号和不带冒号两种写法，以兼容各类 SDK）：

webln:ready / weblnReady
webbtc:ready / webbtcReady
nostr:ready
bitcoin:ready
rgb:ready

错误码

每个提供方在拒绝时都会抛出带 code 属性的 Error，DApp 可据此区分用户的”拒绝”与钱包故障：

错误码	含义
`USER_REJECTED`	用户拒绝了连接或确认提示
`NOT_ENABLED`	在该来源的 `enable()` 完成之前就调用了提供方
`METHOD_NOT_SUPPORTED`	已连接的钱包无法提供该方法（例如在无节点的 RGB 钱包上使用 RGB 闪电功能）
`INTERNAL_ERROR`	其他所有情况，钱包的说明在 `error.message` 中

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)`	底层透传请求

用法示例

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 中解码出金额，提示会改为给出明确警告。

RGB 提供方

window.rgb 把钱包的 RGB 运行时暴露给 DApp——无节点的 RGB 钱包或已连接的 RGB 闪电节点，取决于钱包的配置——让应用无需自建 RGB 后端即可发行、接收、发送和跟踪 RGB 资产。每个涉及资金的调用都会在扩展弹窗中确认，连接提示还允许用户把某个来源限制在特定能力范围内（发行资产受独立的 issueAsset 能力控制）。

window.rgb 从扩展 0.3.0 起提供，0.2.0 构建中不存在；请用 rgb:ready 事件做特性检测，不要假定它一定存在。

TypeScript 支持

@kaleidorg/webrgb 包提供 window.rgb 的类型声明，以及一个 requestProvider() 辅助函数：当页面先于钱包运行时，它会等待 rgb:ready 事件：

npm install @kaleidorg/webrgb

import { requestProvider } from "@kaleidorg/webrgb";

const rgb = await requestProvider(); // 返回带类型的 RgbProvider，找不到时以 METHOD_NOT_SUPPORTED 拒绝
await rgb.enable();

支持的方法

方法	说明
`enable()`	连接 DApp；与其他提供方共用同一份来源授权
`getInfo()`	`{ ready, network, protocol, methods }`——未连接 RGB 钱包时 `ready` 为 `false`
`getAddress()`	RGB 钱包的比特币地址，用于锚定 RGB 状态
`blindReceive(args)`	某资产的盲化 UTXO 接收发票（`assetId`，可选 `amount`、`durationSeconds`、`minConfirmations`）
`issueAsset(args)`	发行新资产（`schema: "nia"`、`ticker`、`name`、`amounts`、`precision`）；仅当钱包可发行时才出现在 `methods` 中
`listAssets()`	钱包持有的资产
`getAssetBalance(assetId)`	单个资产的 `{ assetId, balance }`
`sendAsset(args)`	按接收方的 RGB 发票发送（`{ invoice }`），或显式指定（`assetId`、`amount`、`recipientId`）
`listTransfers(assetId?)`	转账历史，可按资产过滤
`getTransferStatus(id, assetId?)`	按索引、接收方 ID 或 txid 查询单笔转账
`makeLnInvoice(args)`	携带资产的 BOLT-11 发票（`assetId`，可选 `assetAmount`、`amountSats`、`description`、`expirySeconds`）；仅限 RGB 闪电钱包
`payLnInvoice(args)`	支付携带资产的 BOLT-11 发票（`{ invoice }`）；仅限 RGB 闪电钱包
`on(event, listener)` / `off(event, listener)`	订阅 `transferReceived` 和 `transferSettled`

用法示例

window.addEventListener("rgb:ready", async () => {
  await window.rgb.enable();

  const info = await window.rgb.getInfo();
  // { ready: true, network: "signet", protocol: "RGB_L1" | "RGB_LN", methods: [...] }

  const { invoice } = await window.rgb.blindReceive({
    assetId: "rgb:…",
    amount: 1, // 省略则为任意金额发票
  });

  // 推荐：按接收方的 RGB 发票发送
  await window.rgb.sendAsset({ invoice: "rgb:…/…utxob:…" });
});

RGB 闪电网络

当钱包的 RGB 运行时是闪电节点时，getInfo().protocol 为 "RGB_LN"，methods 中还会列出 makeLnInvoice 和 payLnInvoice。在无节点的 RGB 钱包上，两者都会以 METHOD_NOT_SUPPORTED 拒绝。

// 接收：携带资产的 BOLT-11 发票。`amountSats` 是 HTLC 携带的比特币；
// 节点有最低限额，钱包会把金额提高到该限额，确认弹窗显示的就是这个数字。
const { invoice, paymentHash } = await window.rgb.makeLnInvoice({
  assetId: "rgb:…",
  assetAmount: 5, // 省略则为任意金额发票
  description: "tickets",
});

// 支付：发票必须携带带有明确金额的资产。纯比特币发票会被拒绝——
// 请改用 window.webln.sendPayment()。
const { preimage, assetId, assetAmount } = await window.rgb.payLnInvoice({ invoice: "lnbc…" });

两个调用都会在弹窗中确认，显示资产、单位数量以及 HTLC 携带的聪。消费额度不适用于资产支付：每次 payLnInvoice 都会提示确认。

事件

window.rgb.on("transferReceived", (t) => { /* 发现新的入账转账 */ });
window.rgb.on("transferSettled", (t) => { /* 已知转账达到 Settled 状态 */ });

事件负载为 { assetId, transferId, status, kind, amount, recipientId, txid }。事件由后台轮询推送，只要有已订阅的来源保持标签页打开，就会大约每分钟运行一次，因此无需循环调用 listTransfers()——但也不要期待分钟以内的延迟。

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 加密

用法示例

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（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）会被校验，并与钱包交易记录关联。

面向开发者

凡是不在同一浏览器中运行的网页之外的一切——移动应用、桌面客户端、机器人和后端——都应通过 NWC 集成。扩展充当 NIP-47 钱包服务；任何 NIP-47 客户端库都能与之配合，无需任何 KaleidoSwap 专有的实现。在设置 > Nostr Wallet Connect（Settings > Nostr Wallet Connect）中生成的配对字符串采用标准格式：

nostr+walletconnect://<wallet-pubkey>?relay=<wss-relay-url>&secret=<client-secret>

该服务声明 NIP-47 版本 1.0，支持 nip04 与 nip44_v2 加密，并支持以下方法：

方法	说明
`get_info`	节点别名、网络、支持的方法与加密方式
`get_balance`	可支配的闪电余额
`make_invoice`	创建 BOLT-11 发票
`pay_invoice`	支付 BOLT-11 发票；超出客户端预算时会提示确认
`multi_pay_invoice`	一次请求支付多张发票，每张都按预算单独判定
`lookup_invoice`	按支付哈希或 BOLT-11 查询发票
`list_transactions`	最近的收付款记录
`sign_message`	用节点密钥签名消息

每个已配对的客户端都有独立的消费预算，可在设置 > 已连接应用（Settings > Connected Apps）中查看和撤销。预算内的支付无需提示即可完成；超出预算的支付会打开与页面内提供方相同的确认窗口。

权限提示与已连接应用

当已连接的站点发起敏感请求时，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 授权始终由用户驱动：

受信任的站点请求连接、支付、发票、资产或签名操作
KaleidoSwap 扩展通过内容脚本和后台 service worker 转发请求
用户核对详情，批准或拒绝该操作

这样既保证钱包侧的操作始终显式确认，又允许 DApp 把 KaleidoSwap 扩展当作浏览器提供方使用。

安全注意事项

做法	说明
核实站点	批准钱包连接前先检查 URL
审阅请求	批准前读清发票、资产和签名的详细内容
用完即锁	使用完 DApp 后锁定 KaleidoSwap 扩展
控制暴露面	只连接受信任的站点

申请测试版访问权限

申请加入 KaleidoSwap 扩展的封闭测试。

简介

功能

参考

概览

工作原理

提供方就绪事件

错误码

WebLN 提供方

支持的方法

用法示例

WebBTC 提供方

支持的方法

PSBT 确认

RGB 提供方

TypeScript 支持

支持的方法

用法示例

RGB 闪电网络

事件

Nostr 提供方（NIP-07）

支持的方法

用法示例

Nostr Connect（NIP-46）

Nostr Wallet Connect（NWC）

面向开发者

权限提示与已连接应用

Nostr 身份

Nostr 密钥管理

浏览器授权流程

安全注意事项

申请测试版访问权限

​概览

​工作原理

​提供方就绪事件

​错误码

​WebLN 提供方

​支持的方法

​用法示例

​WebBTC 提供方

​支持的方法

​PSBT 确认

​RGB 提供方

​TypeScript 支持

​支持的方法

​用法示例

​RGB 闪电网络

​事件

​Nostr 提供方（NIP-07）

​支持的方法

​用法示例

​Nostr Connect（NIP-46）

​Nostr Wallet Connect（NWC）

​面向开发者

​权限提示与已连接应用

​Nostr 身份

​Nostr 密钥管理

​浏览器授权流程

​安全注意事项

申请测试版访问权限

概览

工作原理

提供方就绪事件

错误码

WebLN 提供方

支持的方法

用法示例

WebBTC 提供方

支持的方法

PSBT 确认

RGB 提供方

TypeScript 支持

支持的方法

用法示例

RGB 闪电网络

事件

Nostr 提供方（NIP-07）

支持的方法

用法示例

Nostr Connect（NIP-46）

Nostr Wallet Connect（NWC）

面向开发者

权限提示与已连接应用

Nostr 身份

Nostr 密钥管理

浏览器授权流程

安全注意事项