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 闪电功能）
`INVALID_PARAMS`	参数格式错误，例如 `assetId` 无效，或向 `payLnInvoice` 传入任意金额发票（`window.rgb`）
`ASSET_NOT_FOUND`	钱包不认识该资产；在 `blindReceive` 中省略 `assetId` 即可接受任意资产（`window.rgb`）
`POPUP_CLOSED`	用户回答之前，审批窗口被关闭或无法打开。这不是拒绝：DApp 可以再次请求
`REQUEST_INTERRUPTED`	钱包在后台重启，未能给出回答。请求可能已完成，也可能未完成：在重复任何涉及资金的操作之前，先检查结果（例如支付状态）
`NO_AVAILABLE_UTXOS`	没有可用于盲化接收的空闲可着色 UTXO；请调用 `createUtxos()` 或改用 `witnessReceive()`（`window.rgb`）
`UNSAFE_PSBT`	该 PSBT 会花费持有 RGB 资产的输入，因此在弹出任何提示之前就被拒绝（`window.rgb`）
`INTERNAL_ERROR`	其他所有情况，钱包的说明在 `error.message` 中

window.rgb 只使用 WebRGB 规范定义的错误代码，因此在该提供方上，POPUP_CLOSED 和 REQUEST_INTERRUPTED 会以 INTERNAL_ERROR 返回。

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(opts?)`	获取链上接收地址。传入 `{ protocol: "LIQUID" }`（或其他账户）可获取该账户的地址。需要站点已连接
`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()、requestAccounts()、getAccounts()、getPublicKey()、signMessage()、signPsbt()、pushPsbt()、sendBitcoin() 和 disconnect()。

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 事件做特性检测，不要假定它一定存在。WebRGB 0.4 的方法（witnessReceive、createUtxos、cancelReceive、getBtcBalance、refresh、getAssetMetadata、signPsbt、signMessage）从扩展 0.4.0 起提供；调用前请先检查 getInfo().methods。

TypeScript 支持

@kaleidorg/webrgb 包提供 window.rgb 的类型声明、提供方发现机制、一个内存版模拟钱包，以及一套一致性检查。该仓库中的 SPEC.md 就是本提供方所实现的接口契约。

npm install @kaleidorg/webrgb

import { requestProvider, isProviderError, supports } from "@kaleidorg/webrgb";

// 解析 window.rgb；若页面先于钱包运行，则等待钱包就绪。
const rgb = await requestProvider({ enable: true });

const info = await rgb.getInfo();
if (supports(info, "makeLnInvoice")) {
  // 钱包的 RGB 运行时是一个闪电节点
}

拒绝信息会穿过 postMessage 边界离开钱包，因此页面捕获到的是一个携带 code 的普通 Error——请用 isProviderError(err) 判断，不要用 instanceof。从 0.3.0 起，listAssets() 与 listTransfers() 始终返回数组；包中的 toAssetArray() / toTransferArray() 可兼容那些把数组包起来的钱包。

在没有扩展的情况下开发

@kaleidorg/webrgb/mock 是一个内存版提供方，它执行与真实提供方相同的规则——enable() 之前返回 NOT_ENABLED，对不在 getInfo().methods 中的方法返回 METHOD_NOT_SUPPORTED，并且确认环节可以设置为拒绝——因此在没有安装钱包的情况下也能开发和测试 DApp。

import { installMockProvider } from "@kaleidorg/webrgb/mock";

const { provider, uninstall } = installMockProvider({ protocol: "RGB_LN" });

playground 可以针对扩展或该模拟钱包调用每个方法，并实时记录调用、结果和错误码。@kaleidorg/webrgb/conformance 只使用只读调用来检查钱包是否符合规范，因此不会弹出任何确认。

提供方发现

window.rgb 只有一个位置，只能由一个钱包占据，因此扩展还会以 EIP-6963 的方式宣告自身：它在加载时派发 rgb:announceProvider，并在页面派发 rgb:requestProvider 时作出响应，事件携带 { info: { uuid, name, rdns }, provider }，其 rdns 为 com.kaleidoswap.extension。

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

// 所有作出响应的已安装 RGB 钱包，按 rdns 去重。
for (const { info, provider } of await listProviders()) {
  console.log(info.name, info.rdns);
}

发现机制是增量的：直接读取 window.rgb 仍然有效，requestProvider() 会采用最先到达的那一个。

支持的方法

方法	说明
`enable()`	连接 DApp；与其他提供方共用同一份来源授权
`getInfo()`	`{ ready, network, protocol, methods }`——未连接 RGB 钱包时 `ready` 为 `false`
`getAddress()`	RGB 钱包的比特币地址，用于锚定 RGB 状态
`blindReceive(args)`	盲化 UTXO 接收发票（可选 `assetId`：省略则生成接受任意资产的发票；可选 `amount`、`durationSeconds`、`minConfirmations`，最低为 3）
`witnessReceive(args)`	见证接收发票：由发送方向本钱包新建一个输出，因此不需要空闲的可着色 UTXO（参数与 `blindReceive` 相同）
`createUtxos(args?)`	用 RGB 钱包的比特币创建可着色 UTXO（可选 `num`、`size`、`feeRate`）；会花费 BTC，因此总是在弹窗中确认
`cancelReceive(recipientId)`	取消本钱包创建且未被支付的接收，释放其保留的 UTXO；在弹窗中确认；返回 `{ cancelled }`
`getBtcBalance()`	RGB 钱包持有的比特币，分为普通（vanilla）和已着色（colored）的 `{ settled, future, spendable }`，以及 `freeColorableUtxos`
`refresh(assetId?)`	同步并推进待处理的转账；返回 `{ refreshed }`
`getAssetMetadata(assetId)`	钱包所知的该资产的 RGB 元数据
`signPsbt(psbt, { finalize? })`	在显示每个输入的确认之后，签名 base64 PSBT 中属于本钱包的输入；持有 RGB 资产的输入会以 `UNSAFE_PSBT` 拒绝；返回 `{ psbt, signedInputs }`
`signMessage(message)`	确认后用钱包的消息密钥签名一条消息（LND `signmessage` 格式），便于后端验证钱包；返回 `{ signature }`
`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 查询单笔转账
`decodeRgbInvoice(invoice)`	在据此发送之前，读取发票的内容——资产、金额、接收方。只读，因此不会弹出确认；不限金额的发票其 `amount` 为 `null`
`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 字节哈希
`hashAndSignSchnorr(message)`	对消息做哈希，并用 Nostr 密钥签名该哈希
`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 时，会先询问预先批准的范围。每次都询问（Ask every time，默认）会逐个确认每个请求；仅登录（Sign-in only）会自动批准中继登录（NIP-42，kind 22242），发帖、删除等其他操作仍会询问。只为 WebLN 或 WebBTC 连接的站点，必须再次请求才能使用你的 Nostr 身份；读取你的公钥或中继列表也需要该站点的 Nostr 权限。如果你拒绝了某个站点的连接，window.nostr 在该页面剩余的生命周期内不再弹出提示，钱包也会在 10 分钟内记住对该站点的拒绝。被关闭或未回答的提示只会短暂退避，不会记为拒绝。

Nostr Connect（NIP-46）

除了页面内的 NIP-07 签名，扩展还可以为支持 NIP-46（nsecBunker）的 Nostr 应用充当远程签名器。在设置 > Nostr > Nostr Connect（Settings > Nostr > 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`	用节点密钥签名消息
`pay_keysend`	仅当当前闪电后端支持 keysend 时才会声明

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

权限提示与已连接应用

当已连接的站点发起敏感请求时，KaleidoSwap 扩展会要求用户批准或拒绝该操作。连接提示会列出站点请求的能力（创建发票、发送闪电支付、签名消息、签名 PSBT、发送比特币、发行 RGB 资产、Nostr），站点只获得用户保留开启的那些能力；不带能力列表的批准不授予任何能力。每个提示都会注明发起请求的站点。

更多请求需要批准： LNURL-auth、LNURL-withdraw 和 LNURL-channel 与其他请求一样经过站点权限和解锁检查，读取节点信息或地址也需要批准。站点不能切换钱包当前使用的账户。
站点支付会先校验： 闪电发票在预留任何支出额度之前会被完整解析（校验和、网络、到期时间）并验证，若发票所属网络与付款钱包不同则拒绝。只有在确定支付没有发出时，额度才会退还。
Arkade： 站点不能从 Arkade 账户发起闪电支付（WebLN、LNURL、WebBTC），因为 Arkade 通过 Intents 交换支付闪电，而站点确认无法显示求解方费用和延迟的支付证明。请改用钱包的发送界面。
提示更可靠： 钱包在后台重启时审批窗口仍然有效；未回答就关闭的窗口会以 POPUP_CLOSED 报告，而不是拒绝；钱包锁定时可以在提示中用通行密钥（passkey）解锁。
其他钱包照常工作： 注入的提供方是只读但可重新定义的，因此扩展不会替换其他钱包的 window.webln、webbtc、bitcoin、rgb 或 nostr。

连接授权提示，显示发起请求的站点来源、它申请的访问权限，以及 Nostr 的「每次都询问」（默认）和「仅登录」选项，还有拒绝和允许按钮

设置 > 已连接应用（Settings > Connected Apps）列出连接到钱包的每个站点和应用（包括 NIP-46（bunker）客户端），并显示各自被授予的能力。你可以随时撤销单项能力，或彻底断开某个站点。

已连接应用界面，列出已连接的应用、Nostr Wallet Connect 会话，以及用于屏蔽站点的输入框

批准之前务必看清 DApp 请求的内容。只批准来自你信任的站点的支付、发票、资产发送和签名请求。

Nostr 身份

KaleidoSwap 扩展从钱包助记词（或导入的身份）派生 Nostr 身份，并同时通过 window.nostr 暴露给网页，以及在扩展设置中展示。

Nostr 密钥管理

你的 Nostr 密钥对在设置 > Nostr > Nostr 身份（Settings > Nostr > Nostr Identity）中管理：

查看公钥（npub）
钱包处于解锁状态时查看／复制会话私钥
导入密钥，或把已导入的密钥恢复为从助记词派生的身份

默认情况下，身份由助记词派生（NIP-06）。如果你已经有 Nostr 身份，可以在初始设置时或之后从设置 > Nostr > 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 密钥管理

浏览器授权流程

安全注意事项