Lib.rs

基本概念

为了理解以下内容，您需要掌握以下先决概念。

模式

RGB协议使用模式，类似于面向对象的类，定义了合约业务逻辑，即合约是如何工作的。每个RGB合约都是通过模式的原生操作创建的模式的一个实例，这有助于将合约开发者和发行者的角色分开，以便更容易地操作。

状态

全局状态适用于整个合约（例如代币名称不属于合约的任何一方），而自有状态与特定的一次性印章相关联。合约还使用特殊语法结构，如花括号、方括号和问号，来表示在状态操作中涉及的数据类型集合或数组及其可选性。

状态扩展允许公众参与合约的特定逻辑部分，例如声明烧毁。状态扩展操作允许任何人创建状态扩展，而不需要链上承诺，类似于尚未打包进区块的比特币交易。

接口

在RGB中，合约接口类似于以太坊的ERC标准。通用接口称为“RGBxx”，并定义为独立的LNP/BP标准。

接口定义：定义全局状态（如代币标识符和名称）和自有状态（如通货膨胀和资产），以及操作（如发行和转账）。

接口实现：实现接口时，特定模式的状态和操作绑定到接口。例如，FungibleToken接口为DecentralizedIdentity模式实现了全局和自有状态绑定。

安装

来源

$ git clone <https://github.com/RGB-WG/rgb>
$ cd rgb/cli
$ cargo install --path --all-features .

数据目录

RGB钱包将其数据存储在由DATA_DIR常量指定的目录中。

使用环境变量 DATA_DIR_ENV 可以覆盖默认数据目录位置。如果未设置，默认数据目录位置如下：

• 基于 Linux 和 BSD 的系统： ~/.lnp-bp
• macOS： ~/Library/Application Support/LNP-BP Suite
• Windows： %LOCALAPPDATA%\\LNP-BP Suite
• iOS： ~/Documents
• Android： .（当前工作目录）

如果数据目录尚不存在，钱包会创建它。数据目录用于存储钱包的配置、交易历史和其他持久数据。

钱包的基本目录将是 $data_dir/$network。

配置文件

默认配置文件是 rgb.toml。

目前，唯一支持的配置密钥是 default_wallet，默认值是 default。

概述

以下是 rgb-cli 的命令行帮助信息。

Command-line wallet for RGB smart contracts on Bitcoin

Usage: rgb [OPTIONS] <COMMAND>

Commands:
  list              List known wallets
  default           Get or set default wallet
  create            Create a wallet
  address           Generate a new wallet address(es)
  taprets
  schemata          Prints out list of known RGB schemata
  interfaces        Prints out list of known RGB interfaces
  contracts         Prints out list of known RGB contracts
  import            Imports RGB data into the stash: contracts, schema, interfaces, etc
  export            Exports existing RGB contract
  armor             Convert binary RGB file into a text armored version
  state             Reports information about state of a contract
  history-fungible  Print operation history for a default fungible token under a given interface
  utxos             Display all known UTXOs belonging to this wallet
  issue             Issues new contract
  invoice           Create new invoice
  prepare           Prepare PSBT file for transferring RGB assets. In the most of cases you need to use `transfer` command instead of `prepare` and `consign`
  consign           Prepare consignment for transferring RGB assets. In the most of cases you need to use `transfer` command instead of `prepare` and `consign`
  transfer          Transfer RGB assets
  inspect           Inspects any RGB data file
  dump              Debug-dump all stash and inventory data
  validate          Validate transfer consignment
  accept            Validate transfer consignment & accept to the stash
  help              Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...
          Set verbosity level
  -w, --wallet <NAME>

  -W, --wallet-path <WALLET_PATH>
          Path to wallet directory
      --tapret-key-only <TAPRET_KEY_ONLY>
          Use tapret(KEY) descriptor as wallet
      --wpkh <WPKH>
          Use wpkh(KEY) descriptor as wallet
  -e, --esplora <URL>
          Esplora server to use [env: ESPLORA_SERVER=] [default: <https://blockstream.info/testnet/api>]
      --sync

  -d, --data-dir <DATA_DIR>
          Data directory path [env: LNPBP_DATA_DIR=] [default: ~/.lnp-bp]
  -n, --network <NETWORK>
          Network to use [env: LNPBP_NETWORK=] [default: testnet]
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

准备

创建钱包

要创建钱包，您需要准备一个钱包描述符。您可以通过 bdk-cli 或其他类似工具创建钱包。

以下是一个示例描述符

[1f09c6b9/86h/1h/0h]tpubDCrfSMscBA93FWm8qounj6kcBjnw6LxmVeKSi6VoYS327VCpoLHARWjdqeVtDt2ujDRznB9m1uXpHkDpDXyXM5gsvg2bMMmFcSHrtWUA4Py/<0;1;9;10>/*

$ rgb create my_wallet --wpkh "[1f09c6b9/86h/1h/0h]tpubDCrfSMscBA93FWm8qounj6kcBjnw6LxmVeKSi6VoYS327VCpoLHARWjdqeVtDt2ujDRznB9m1uXpHkDpDXyXM5gsvg2bMMmFcSHrtWUA4Py/<0;1;9;10>/*"

现在我们可以在钱包运行时目录中找到创建的相关文件

$ ls ~/.lnp-bp/testnet3/my_wallet     

cache.yaml  data.toml  descriptor.toml

列出钱包

用法

$ rgb list

示例输出

Known wallets:
my_wallet

设置默认钱包

现在我们将默认钱包设置为 my_wallet

$ rgb default my_wallet

资产

导入模式

模式文件名以 .rgba 结尾，标准模式可以在 https://github.com/RGB-WG/rgb-schemata 存储库中找到。

您可以在 https://github.com/RGB-WG/rgb-schemata/blob/master/schemata/NonInflatableAssets.rgba 中查看，这是 NIA 模式。

示例

$ rgb import rgb-schemata/schemata/NonInflatableAssets.rgb

列出模式

$ rgb schemata

示例输出

urn:lnp-bp:sc:9ZKGvK-tGs6nJvr-HQVRDDyV-zPnJYE5U-J2mb6yDi-PgBrby#frog-order-costume

导入接口

现在我们需要导入接口定义和接口实现，否则您可能会遇到错误

Error: no known interface implementation for XXX

执行

$ rgb import ../rgb-schemata/interfaces/RGB20.rgb
$ rgb import ../rgb-schemata/schemata/NonInflatableAssets-RGB20.rgb

列出接口

$ rgb interfaces

RGB21 urn:lnp-bp:if:KtMq1E-bFRhMzn5-sc9NezhQ-kn2JzeJn-VxjDCqru-sieYa#portal-ecology-hostel
RGB25 urn:lnp-bp:if:75swax-yN5mDaKB-B3peGeLu-tLctU3Ef-rAjFySp7-RMLTVF#cable-kayak-david
RGB20 urn:lnp-bp:if:9UMsvx-HkLVK5VT-GkSy7yNU-ihAUBo7a-hxQvLCFq-U4aouK#object-spring-silk

发布合约

用法

$ rgb issue [OPTIONS] <SCHEMA_ID> <CONTRACT_PATH>

教程

编写合约声明。（本例中为 YAML）

interface: RGB20

globals:
  spec:
    naming:
      ticker: DBG
      name: Debug asset
      details: "Pay attention: the asset has no value"
    precision: 2
  data:
    terms: >
      SUBJECT TO, AND WITHOUT IN ANY WAY LIMITING, THE REPRESENTATIONS AND WARRANTIES OF ANY SELLER 
      EXPRESSLY SET FORTH IN THIS AGREEMENT OR ANY OTHER EXPRESS OBLIGATION OF SELLERS PURSUANT TO THE
      TERMS HEREOF, AND ACKNOWLEDGING THE PRIOR USE OF THE PROPERTY AND PURCHASER’S OPPORTUNITY 
      TO INSPECT THE PROPERTY, PURCHASER AGREES TO PURCHASE THE PROPERTY “AS IS”, “WHERE IS”, 
      WITH ALL FAULTS AND CONDITIONS THEREON. ANY WRITTEN OR ORAL INFORMATION, REPORTS, STATEMENTS, 
      DOCUMENTS OR RECORDS CONCERNING THE PROPERTY PROVIDED OR MADE AVAILABLE TO PURCHASER, ITS AGENTS
      OR CONSTITUENTS BY ANY SELLER, ANY SELLER’S AGENTS, EMPLOYEES OR THIRD PARTIES REPRESENTING OR
      PURPORTING TO REPRESENT ANY SELLER, SHALL NOT BE REPRESENTATIONS OR WARRANTIES, UNLESS
      SPECIFICALLY SET FORTH HEREIN. IN PURCHASING THE PROPERTY OR TAKING OTHER ACTION HEREUNDER,
      PURCHASER HAS NOT AND SHALL NOT RELY ON ANY SUCH DISCLOSURES, BUT RATHER, PURCHASER SHALL RELY
      ONLY ON PURCHASER’S OWN INSPECTION OF THE PROPERTY AND THE REPRESENTATIONS AND WARRANTIES 
      HEREIN. PURCHASER ACKNOWLEDGES THAT THE PURCHASE PRICE REFLECTS AND TAKES INTO ACCOUNT THAT THE
      PROPERTY IS BEING SOLD “AS IS”.
    media: ~
  issuedSupply: 100000000
  created: 1687969158

assignments:
  assetOwner:
    seal: tapret1st:fb9ae7ae4b70a27e7fdfdefac91b37967b549d65007dbf25470b0817a2ae810a:1
    amount: 100000000 # this is 1 million (we have two digits for cents)

这里，我们观察到以 closing_method:txid:vout 形式的密封值，这里的关闭方法是 tapret1st（也可以是 opret1st）。实际上，这个哈希代表之前创建的 PSBT 的 txid。而 txid:vout 是一个有效 UTXO 的出点。

编译合约

$ rgb issue urn:lnp-bp:sc:9ZKGvK-tGs6nJvr-HQVRDDyV-zPnJYE5U-J2mb6yDi-PgBrby#frog-order-costume ./examples/rgb20-demo.yaml

将生成一个合约（也用作寄存器）并将其导入当前运行时的库存。

输出

A new contract rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB is issued and added to the stash.

导出合约

接下来，我们导出刚刚创建的合约。

$ rgb export rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB
RGB: command-line wallet for RGB smart contracts
     by LNP/BP Standards Association

Loading descriptor from wallet my_wallet ... success
Loading stock ... success
-----BEGIN RGB CONSIGNMENT-----
Id: urn:lnp-bp:consignment:Ctc1wq-Xrqm78uM-nNaDsoHj-TJESKydn-4GLgtYmr-G9AdQE#smoke-oxford-burger
Version: v2
Type: contract
Contract-Id: rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB
Checksum-SHA256: 50468d33da7aab15c8c2b467126b721c4c3c6cf31d00c8964fb12e23fbc64777

0ssM^4-D2iQYiE=(kr<ho`PqD7ID7TPL?t(cy6J>o^uy=TL1t60DmODi%$$wo#Ma
...

-----END RGB CONSIGNMENT-----

编码在 base64 格式的寄存器将被输出到 stdout。

或者，您可以指定一个文件名以获取二进制寄存器

$ rgb export rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB demo.rgb  

Contract rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB exported to 'demo.rgb'

导入合约（或其他类型的寄存器）

可以使用导入子命令导入寄存器，但 RGB CLI 已自动导入合约，因此无需执行它。

$ rgb import demo.rgb

读取合约状态

$ rgb state rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB RGB20

Global:
  spec := (naming=(ticker=("DBG"), name=("Debug asset"), details=1(("Pay attention: the asset has no value"))), precision=2)
  data := (terms=("..."), media=~)
  issuedSupply := (100000000)
  created := (1687969158)

Owned:
  assetOwner:

列出合约

执行

$ rgb contracts

示例输出

rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB

取一个地址

$ rgb address
Term.   Address
&0/0    tb1qeyu926l47099vtp7wewvhwt03vc5sn5c6t604p

运行多次以在不同索引处生成更多地址。例如，要查看给定索引的地址，例如 0，执行

$ rgb address --index 0

创建基于地址的发票

$ rgb invoice --address-based rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB RGB20 100

已创建发票

rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB/RGB20/100+tb:q0q6u0urtzn59cg9qacm7c5aq7ud3wmgms7stew

以下是发票字符串不同部分的分解

1. rgb:DF4vyV9-i85ZzUqbq-QLxvKtgtp-AJk9NvpL3-k4AHmcRrf-vyHksB：这是合同ID，它是与该发票相关的合同的唯一标识符。
2. RGB20：这是用于交易的接口（或协议）。
3. 100：这是交易金额，为100单位。
4. tb:q0q6u0urtzn59cg9qacm7c5aq7ud3wmgms7stew：这是交易的受益人

发票字符串还可以包含一些作为查询参数编码的附加参数，这些参数由?字符分隔。这些参数用于提供有关交易的额外信息，例如正在执行的操作或与交易相关的分配。

验证货物

$ rgb validate demo.rgb

示例输出

Consignment has non-mined terminal(s)
Non-mined terminals:
- f17d544c0ac161f758d379c4366e6ede8f394da9633671908738b415ae5c8fb4
Validation warnings:
- terminal witness transaction f17d544c0ac161f758d379c4366e6ede8f394da9633671908738b415ae5c8fb4 is not yet mined.

签名并广播交易

创建转账

$ rgb transfer <INVOICE> <CONSIGNMENT_FILE> [PSBT]
$ rgb transfer \ 
    rgb:2bLwMXo-deVgzKq97-GUVy6wXea-G1nE84nxw-v5CX3WSJN-mbhsMn7/RGB20/1000+bcrt:p9yjaffzhuh9p7d9gnwfunxssngesk25tz7rudu4v69dl6e7w7qhq5x43k5 \
    transfer.consignment \ 
    alice.psbt

现在您可以使用bdk-cli或其他钱包来签名和广播交易。

等待确认并接受转账

作为接收者

$ rgb accept -f CONSIGNMENT_FILE