🌈 RGB 协议实战学习系列
8. RGB 协议 v0.12 全流程实验：CLI + Sparrow 集成实践

8.RGB 协议 v0.12 全流程实验：CLI + Sparrow 集成实践

实验日期: 2025-09-01

技术栈: macOS + Bitcoin Testnet + Sparrow + electrs-esplora + RGB CLI

技术环境演进过程

第一阶段：环境迁移

  • 目标: 从 Docker regtest 环境迁移到本机 testnet
  • Bitcoin Core: 本机运行 testnet 模式
  • 索引服务: 从 Docker 本地环境 (port 3002) 切换到 Electrs (port 60001)
  • 遇到问题: RGB CLI 版本兼容性冲突

第二阶段：版本适配

  • 发现: 不同 RGB 实现之间存在版本差异
  • 尝试: Sparrow Wallet 与 RGB CLI 集成方案
  • 挑战: 旧版本合约文件无法在新版本 CLI 中使用

第三阶段：成功实现

  • Bitcoin 节点: 本机 testnet lightmode
  • 索引服务: electrs-esplora (127.0.0.1:60001)
  • RGB CLI: v0.12 版本稳定运行
  • 签名工具: Sparrow Wallet

关键技术突破

1. RGB CLI 发行机制的掌握

突破点: 发现 RGB v0.12 使用 YAML 配置文件发行，而不是命令行参数

成功的 AARONTEST 代币发行配置:

consensus: bitcoin
testnet: true
issuer:
  codexId: 7C15w3W1-L0T~zXw-Aeh5~kV-Zquz729-HXQFKQW-_5lX9O8
  version: 0
  checksum: AYkSrg
name: AARONTEST
method: issue
timestamp: "2025-09-01T19:30:00+00:00"
global:
  - name: ticker
    verified: ATEST
  - name: name
    verified: AARON Test Token
  - name: precision
    verified: centiMilli
  - name: issued
    verified: 10000
owned:
  - name: balance
    seal: 1a0306af6d35b7cf31ffa2cacdd9c00da94d3a71f12e41b9a2addb6c8be3968e:0
    data: 10000

关键发现:

  • 合约名称不能包含连字符 (-)
  • seal 必须是发行方实际控制的 UTXO
  • 发行是纯链下操作，绑定到现有 UTXO

2. RGB 合约传播机制

核心发现: backup + accept -u 是 RGB v0.12 的标准合约传播方式

成功的传播流程:

# Alice 备份合约
rgb -d .alice -n testnet --no-network-prefix backup contract:mHQeZs0y-Te_2e95-6CFwQZb-GyE1sJP-hLGh8rn-JQ7_QoI aarontest-backup.rgb
 
# Bob 接受合约（-u 参数至关重要）
rgb -d .bob -n testnet --no-network-prefix accept -u aarontest-backup.rgb

重要教训: -u 参数是成功的关键，表示无条件接受

3. 完整的资产转移流程

第一阶段：发票生成

# Bob 生成接收发票
rgb -d .bob -n testnet --no-network-prefix invoice contract:mHQeZs0y-Te_2e95-6CFwQZb-GyE1sJP-hLGh8rn-JQ7_QoI 1000
# 输出: contract:tb@contract:...1000@at:HNendhw3-T4evES4k-Ybo_4kpi-KRcR37db-8DnaKWlZ-KxUVWA/

第二阶段：创建支付

# Alice 根据发票创建支付
rgb -d .alice -n testnet --no-network-prefix pay --wallet default --electrum="127.0.0.1:60001" "$(cat bob-invoice.txt)" alice-to-bob-atest.rgb alice-to-bob-atest.psbt

第三阶段：交易签名

  • 使用 Sparrow Wallet 导入 PSBT 文件
  • 签名并广播到 testnet
  • 交易ID: 40e8aa4a08811dac8d073ac6c7008406bc1dbe65114e45ca69eed1c95903c8cf

第四阶段：完成转移

# Bob 接受转移
rgb -d .bob -n testnet --no-network-prefix accept alice-to-bob-atest.rgb

RGB 协议核心机制解析

1. 发行机制

发现: RGB 发行是纯链下操作，通过客户端将资产状态绑定到现有 UTXO

验证:

  • Faucet 交易: 1a0306af...968e (普通比特币交易，无 OP_RETURN)
  • 发行操作: 链下绑定 10,000 ATEST 到该 UTXO
  • 无专门的"发行交易"

2. 转移机制

链上承诺: 转移交易包含 OP_RETURN 承诺哈希

交易解析:

OP_RETURN: 0c8415abc2538ec9b9cd2a37d763811c19b16df61c2e64b361f673e0ed4ce3fa
输入: 1a0306af...968e:0 (10,500 sats)
输出0: OP_RETURN (0 sats) - RGB 承诺
输出1: tb1p2t02eft... (9,500 sats) - 找零

承诺哈希原理:

  • 32 字节哈希承诺特定的状态变更
  • 外部观察者只能看到神秘数据，无法知道具体转移内容
  • 参与者通过 consignment 文件验证完整性

3. 客户端验证机制

验证流程:

  1. Bob 收到 consignment 文件（包含完整状态变更数据）
  2. Bob 重新计算状态变更的哈希值
  3. 对比链上 OP_RETURN 中的承诺哈希
  4. 匹配则验证通过，不匹配则拒绝

隐私保护:

  • 链上只有承诺哈希，无具体转移信息
  • 状态数据存储在客户端，不上链
  • 外部观察者无法知道资产类型和数量

技术问题与解决方案

1. 版本兼容性问题

问题: RGB 生态版本分化严重

  • RGB-WG 官方: v0.11 -> v0.12 快速迭代
  • Bitlight Labs: 基于 v0.11 的工具链
  • 社区教程: 多数基于旧版本

解决: 坚持使用 RGB CLI v0.12，掌握新的操作方式

2. 同步问题

现象: Error: unable to retrieve the status of a witness id. Details: Protocol

影响分析:

  • 不影响核心功能（发行、转移都成功）
  • 主要影响状态同步和查询
  • 可能是 RGB v0.12 的已知问题

解决: 接受问题，专注核心功能

3. PSBT 签名集成

问题: RGB 的 complete 命令无法识别 Sparrow 签名的 PSBT

解决:

  • 在 Sparrow 中直接广播交易
  • 让 RGB 协议通过链上承诺识别状态变更
  • Bob 通过 accept 命令完成接收

4. Testnet vs Regtest 差异

发现:

  • Bitlight 公共注册表基于 testnet3，不是 testnet4
  • 本地环境使用 regtest，生产测试使用 testnet
  • 网络切换只需修改少量参数

实验结果验证

最终状态

Alice 余额:

balance  tentative  9000  ApNmA4rGKSPI9~ujRZo64AflM8f5S0_axkJFsxD_efk:1  40e8aa4a...:1

Bob 余额:

balance  tentative  1000  ApNmA4rGKSPI9~ujRZo64AflM8f5S0_axkJFsxD_efk:0  76d3febc...:1

数学验证: 10,000 = 9,000 + 1,000 ✅

链上证据:

  • 转移交易: 40e8aa4a08811dac8d073ac6c7008406bc1dbe65114e45ca69eed1c95903c8cf
  • OP_RETURN 承诺: 0c8415abc2538ec9b9cd2a37d763811c19b16df61c2e64b361f673e0ed4ce3fa
  • 在 mempool.space 可查询验证

RGB 协议设计哲学的思考

隐私 vs 透明度的权衡

RGB 的选择: 极端隐私优先

  • 合约不自动出现在公共注册表
  • 状态变更只有参与者知道
  • 链上只有加密承诺

实际问题:

  • 用户难以发现和验证资产
  • consignment 文件管理复杂
  • 缺乏全局状态透明度

建议的平衡方案:

  1. 发行阶段: 强制公共注册基本信息
  2. 转移阶段: 保持隐私，只记录承诺
  3. 争议解决: consignment 作为法律证据
  4. 选择性公开: 允许用户选择公开特定交易

技术成熟度评估

优势:

  • 创新的客户端验证机制
  • 优秀的隐私保护
  • 与比特币完美集成

不足:

  • 工具链不稳定，版本混乱
  • 用户体验复杂
  • 缺乏标准化流程

结论: RGB 协议在概念上先进，但生态系统仍需时间成熟

核心发现与思考

RGB 隐私设计的实际效果

我们成功发行了 AARONTEST 代币，完成了 Alice → Bob 的转移（10,000 → 9,000 + 1,000），但这个代币并未出现在 Bitlight 的公共资产注册表中。

这揭示了 RGB 的隐私机制：

  • 合约发行是纯链下操作，默认不公开
  • 只有主动注册的合约才会出现在公共注册表
  • 外部观察者无法知道私人发行的代币存在

协议改进的思考： 当前的纯隐私方案存在实用性问题：

  1. 用户难以验证代币的真实性
  2. 缺乏防止重名代币的机制
  3. Consignment 文件管理复杂，影响流通

建议的混合方案：

  • 发行阶段：强制基本信息公开注册，确保可验证性
  • 转移阶段：保持隐私，只在链上记录承诺哈希
  • 法律功能：完整的 Consignment 文件作为争议解决的证据

技术实现的核心要点

  1. YAML 配置发行：RGB v0.12 使用配置文件而非命令行参数
  2. 客户端验证：状态绑定到 UTXO，通过 OP_RETURN 承诺验证
  3. 工具链集成：RGB CLI + Sparrow Wallet 实现完整的发行到转移流程
  4. 版本适配：掌握了从 Docker 环境到本机环境的迁移方法

实验结论：RGB 协议在技术上创新，但在可用性和透明度之间的权衡可能过于偏向隐私。未来的改进应该考虑在保持核心隐私优势的同时，提供必要的公开验证机制。

7. macOS 环境下 Esplora 区块链浏览器部署实践1. Bitlight Wallet SDK