🌈 RGB Protocol Practical Learning Series
8. RGB Protocol v0.12 Complete Workflow Experiment: CLI + Sparrow Integration Practice

8.RGB Protocol v0.12 Complete Workflow Experiment: CLI + Sparrow Integration Practice

Experiment Date: 2025-09-01

Tech Stack: macOS + Bitcoin Testnet + Sparrow + electrs-esplora + RGB CLI

Technical Environment Evolution Process

Phase 1: Environment Migration

  • Goal: Migrate from Docker regtest environment to local testnet
  • Bitcoin Core: Running testnet mode locally
  • Indexing Service: Switch from Docker local environment (port 3002) to Electrs (port 60001)
  • Problem Encountered: RGB CLI version compatibility conflicts

Phase 2: Version Adaptation

  • Discovery: Version differences exist between different RGB implementations
  • Attempt: Sparrow Wallet and RGB CLI integration solution
  • Challenge: Old version contract files cannot be used in new version CLI

Phase 3: Successful Implementation

  • Bitcoin Node: Local testnet lightmode
  • Indexing Service: electrs-esplora (127.0.0.1:60001)
  • RGB CLI: v0.12 version running stably
  • Signing Tool: Sparrow Wallet

Key Technical Breakthroughs

1. Mastering RGB CLI Issuance Mechanism

Breakthrough: Discovered that RGB v0.12 uses YAML configuration files for issuance, not command-line parameters

Successful AARONTEST Token Issuance Configuration:

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

Key Findings:

  • Contract name cannot contain hyphens (-)
  • seal must be a UTXO actually controlled by the issuer
  • Issuance is a purely off-chain operation, bound to an existing UTXO

2. RGB Contract Propagation Mechanism

Core Discovery: backup + accept -u is the standard contract propagation method in RGB v0.12

Successful Propagation Flow:

# Alice backs up contract
rgb -d .alice -n testnet --no-network-prefix backup contract:mHQeZs0y-Te_2e95-6CFwQZb-GyE1sJP-hLGh8rn-JQ7_QoI aarontest-backup.rgb
 
# Bob accepts contract (-u parameter is crucial)
rgb -d .bob -n testnet --no-network-prefix accept -u aarontest-backup.rgb

Important Lesson: The -u parameter is key to success, indicating unconditional acceptance

3. Complete Asset Transfer Process

Phase 1: Invoice Generation

# Bob generates receiving invoice
rgb -d .bob -n testnet --no-network-prefix invoice contract:mHQeZs0y-Te_2e95-6CFwQZb-GyE1sJP-hLGh8rn-JQ7_QoI 1000
# Output: contract:tb@contract:...1000@at:HNendhw3-T4evES4k-Ybo_4kpi-KRcR37db-8DnaKWlZ-KxUVWA/

Phase 2: Create Payment

# Alice creates payment based on invoice
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

Phase 3: Transaction Signing

  • Import PSBT file using Sparrow Wallet
  • Sign and broadcast to testnet
  • Transaction ID: 40e8aa4a08811dac8d073ac6c7008406bc1dbe65114e45ca69eed1c95903c8cf

Phase 4: Complete Transfer

# Bob accepts transfer
rgb -d .bob -n testnet --no-network-prefix accept alice-to-bob-atest.rgb

RGB Protocol Core Mechanism Analysis

1. Issuance Mechanism

Discovery: RGB issuance is a purely off-chain operation, binding asset state to existing UTXO through the client

Verification:

  • Faucet transaction: 1a0306af...968e (regular Bitcoin transaction, no OP_RETURN)
  • Issuance operation: Off-chain binding of 10,000 ATEST to that UTXO
  • No dedicated "issuance transaction"

2. Transfer Mechanism

On-chain Commitment: Transfer transaction contains OP_RETURN commitment hash

Transaction Analysis:

OP_RETURN: 0c8415abc2538ec9b9cd2a37d763811c19b16df61c2e64b361f673e0ed4ce3fa
Input: 1a0306af...968e:0 (10,500 sats)
Output0: OP_RETURN (0 sats) - RGB commitment
Output1: tb1p2t02eft... (9,500 sats) - Change

Commitment Hash Principle:

  • 32-byte hash commits to specific state changes
  • External observers can only see mysterious data, cannot know specific transfer content
  • Participants verify integrity through consignment files

3. Client-side Validation Mechanism

Validation Flow:

  1. Bob receives consignment file (contains complete state change data)
  2. Bob recalculates the hash value of state changes
  3. Compare with commitment hash in on-chain OP_RETURN
  4. If matches, validation passes; if not, reject

Privacy Protection:

  • Only commitment hash on-chain, no specific transfer information
  • State data stored on client, not on-chain
  • External observers cannot know asset type and quantity

Technical Issues and Solutions

1. Version Compatibility Issues

Problem: Severe version fragmentation in RGB ecosystem

  • RGB-WG official: v0.11 -> v0.12 rapid iteration
  • Bitlight Labs: Toolchain based on v0.11
  • Community tutorials: Most based on old versions

Solution: Stick to RGB CLI v0.12, master new operation methods

2. Synchronization Issues

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

Impact Analysis:

  • Does not affect core functionality (issuance, transfer both successful)
  • Mainly affects state synchronization and queries
  • Possibly a known issue with RGB v0.12

Solution: Accept the issue, focus on core functionality

3. PSBT Signing Integration

Problem: RGB's complete command cannot recognize PSBT signed by Sparrow

Solution:

  • Broadcast transaction directly in Sparrow
  • Let RGB protocol recognize state changes through on-chain commitment
  • Bob completes acceptance through accept command

4. Testnet vs Regtest Differences

Discovery:

  • Bitlight public registry based on testnet3, not testnet4
  • Local environment uses regtest, production testing uses testnet
  • Network switching only requires modifying a few parameters

Experimental Results Verification

Final State

Alice Balance:

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

Bob Balance:

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

Mathematical Verification: 10,000 = 9,000 + 1,000 ✅

On-chain Evidence:

  • Transfer transaction: 40e8aa4a08811dac8d073ac6c7008406bc1dbe65114e45ca69eed1c95903c8cf
  • OP_RETURN commitment: 0c8415abc2538ec9b9cd2a37d763811c19b16df61c2e64b361f673e0ed4ce3fa
  • Verifiable on mempool.space

Reflections on RGB Protocol Design Philosophy

Privacy vs Transparency Trade-off

RGB's Choice: Extreme privacy priority

  • Contracts do not automatically appear in public registry
  • State changes only known to participants
  • Only encrypted commitments on-chain

Practical Issues:

  • Users have difficulty discovering and verifying assets
  • Consignment file management is complex
  • Lack of global state transparency

Suggested Balanced Approach:

  1. Issuance Phase: Mandatory public registration of basic information
  2. Transfer Phase: Maintain privacy, only record commitments
  3. Dispute Resolution: Consignment as legal evidence
  4. Selective Disclosure: Allow users to choose to disclose specific transactions

Technical Maturity Assessment

Strengths:

  • Innovative client-side validation mechanism
  • Excellent privacy protection
  • Perfect integration with Bitcoin

Shortcomings:

  • Unstable toolchain, version chaos
  • Complex user experience
  • Lack of standardized processes

Conclusion: RGB protocol is advanced conceptually, but the ecosystem still needs time to mature

Core Discoveries and Reflections

Practical Effects of RGB Privacy Design

We successfully issued AARONTEST tokens and completed Alice → Bob transfer (10,000 → 9,000 + 1,000), but this token did not appear in Bitlight's public asset registry.

This reveals RGB's privacy mechanism:

  • Contract issuance is purely off-chain operation, not public by default
  • Only actively registered contracts appear in public registry
  • External observers cannot know about privately issued tokens

Reflections on Protocol Improvements: The current pure privacy approach has practical problems:

  1. Users have difficulty verifying token authenticity
  2. Lack of mechanism to prevent duplicate token names
  3. Consignment file management is complex, affecting circulation

Suggested Hybrid Approach:

  • Issuance Phase: Mandatory public registration of basic information to ensure verifiability
  • Transfer Phase: Maintain privacy, only record commitment hash on-chain
  • Legal Function: Complete Consignment files as evidence for dispute resolution

Core Technical Implementation Points

  1. YAML Configuration Issuance: RGB v0.12 uses configuration files instead of command-line parameters
  2. Client-side Validation: State bound to UTXO, verified through OP_RETURN commitments
  3. Toolchain Integration: RGB CLI + Sparrow Wallet implements complete issuance to transfer process
  4. Version Adaptation: Mastered migration method from Docker environment to local environment

Experimental Conclusion: RGB protocol is technically innovative, but the trade-off between usability and transparency may be too biased toward privacy. Future improvements should consider providing necessary public verification mechanisms while maintaining core privacy advantages.

7. Esplora Blockchain Explorer Deployment Practice on macOS1. 本地 RGB20 发行与转账踩坑记录（bitlight-local-env-public）