Consignment

Data package exchanged between users (peers) when they are using RGB smart contracts (or participate some other client-side validation protocol).

In blockchain world, the data are stored in a public ledger (blockchain) and replicated by each peer. This leads to the loss of privacy, informational centralization and poor scalability. RGB smart contracts use client-side validation, which keeps the data on the peers site and doesn't put them into a blockchain or any shared ledger. The data are exchanged between peers on an ad-hoc basis, only when needed, in pure peer-to-peer way, which significantly improves the privacy, scalability and decentralization. The package of the data exchanged by peers specific to some particular RGB contract is called consignment.

Types of consignments

There are two main types of consignments: contract and transfer.

Contract consignments are used to provide a user with an information required to use some specific RGB contract. They are usually distributed by the contract issuers, but may also be downloaded from asset or contract registries and explorers (like https://rgbex.io), or sent peer-to-peer, from a user to a user.

Transfer consignments are used by contract clients for state transfers from one user to another. For instance, when a payment is made, the sender of the payment must provide the beneficiary with a transfer consignment.

How do consignments look like?

Consignments are usually binary files, which do not contain human-readable information.

When a users need to send consignment data through a channel which doesn't support a binary format, they have an option to use binary-to-text encoding (see ASCII armoring). In RGB, armoring is done in Base85, and the encoded data are accompanied by additional headers and checksums. Here is a typical ASCII-armored contract consignment, in a cut version:

-----BEGIN RGB CONSIGNMENT-----
Id: rgb:csg:3yJCUNgH-xxfXcHX-E1dfL80-kT2R4z5-BJptGHf-sEERkJI#grace-austria-current
Version: 2
Type: contract
Contract: rgb:pHRSdpDs-!wc6x7N-C4F4nPQ-PO!22oI-UUpEV6f-00RRQZM
Schema: rgb:sch:lOk3!8GHPOTYbmEPaNg!tsUh1trhOA!VobyCWo2q6VM#talent-easy-vincent
Interface: RGB20Replaceable
Check-SHA256: 7ba3f563f39177820e2bb66f51022db9865547015b11a55a36aab2fb49b7f23c

0ssI2005NfH~YbdJmlDJVGn57KDNan*4p7X50#<3f?AEL=~DoUInZVR0000m07D^JRC!cxG%a#)bxc-a
O)XJIRykrMP%TwjN^o{`Gc9>xRc%=|K`mu>WKcynV*vmHpbvUQRh+9Pt&l(-@t+}8R@c3%)}vg<ht@H5
                   ... here we skip few hundreds of lines ...
(u?g--(Ch+6*7N1n=+qwe6YFx|MoP&lb}4dCIbUOOjQU%P((>bMN?D*Qb$4|01E&B0MMWh0S5~J0RRgK
000XC0szR`2LU-S0MVci0S5#C0096100000

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

Consignment ids

Consignments are identified by their ids. Like most of other ids used in RGB, consignment id is a form of URL, starting with rgb:csg prefix, followed by Baid64-encoded SHA256 hash over all consignment data. The last part of the URL is a mnemonic fragment made of three words, representing the id checksum. This mnemonic can be used for simple consignment identification visually or in speech.

An example of the consignment id:
rgb:csg:3yJCUNgH-xxfXcHX-E1dfL80-kT2R4z5-BJptGHf-sEERkJI#grace-austria-current

How consignments are sent?

Consignments are sent peer-to-peer, usually from contract issuers to contract users (contract consignments), or from payers to beneficiaries (transfer consignments). Peers are free to use any channel for the consignment, including even messengers, e-mail, QR codes or paper. However, the most typically consignments are sent either directly, with a use of RGB Node, or via RGB RPC relays, which remove a requirement for both sender and receiver to be on-line at the same time. The privacy of the data in this case may be achieved by a cryptographic encoding of the consignments, when receiver provides the sender with its public key as a part of the RGB invoice.

What if I lose a consignment?

It depends. If you lose a contract consignment, you can easily recover it from the contract issuer, other users or asset explorer sites like https://rgbex.com.

If you are a beneficiary of a payment, and you have lost a transfer consignment before you have accepted it into your RGB stash, you won't be able to see or use your assets unless you recover the consignment. In such a case consignment can be recovered by either asking the sender to provide you with it once again.

In order to prevent consignment loss it is recommended to use several relays and accept the consignment into your stash the moment you receive it. Once the consignment is accepted, there is no need to keep its data and its loss doesn't prevent any threat to your assets and contract state.

What is a typical size of the consignment?

The size of the consignment can vary; it also depends on its type.

For contracts the size is usually an order of magnitude of kilobytes; however, if a contract represents an asset with multiple issues (like stablecoin), its size may be measured in megabytes.

For transfers, the size heavily depends on the history of the contract operations included in the consignment. Typically, the size of the consignment growth few hundred megabytes with each transfer; thus usually it is an order of hundreds of kilobytes to tens of megabytes. However, high-velocity assets may have transfer consignments over the years grown to several gigabytes.

Which data consignments do include?

Consignments include the data about the RGB smart contract, including its genesis and complete operation history. Additionally, they include schema, under which the contract is issued, interfaces, implemented by it, and data type and script libraries used by the contract.