RGB smart contract state transfers

[dr-orlovsky]

This is description of generalized protocol for transferring state under arbitrary RGB smart contract. This includes token contracts, but can also apply to non-token and non-fungible contracts.

Transferring state involves several stages.

First, a wallet has to compose PSBT file defining structure of underlying witness transaction.

Basing on this PSBT, a list of spent outputs is passed to the RGB Node, given specific contract id. Node prepares a state transfer consignment, which contains all history for the spent outputs.

This consignment is now used in transfer preparation, when basing on the consignment file, PSBT, list of beneficiaries and available change addresses a (bundled) new state transition(s) for the state transfers are composed. This is performed not by an RGB Node but by a software/library, aware of the contract schema and semantics (assets, NFTs etc); i.e usually by a wallet using some schema-specific helper library, like RGB20.

Next, RGB Node is asked to finalize the consignment and prepare disclosure. It includes the following operations:

• Extracting all other contracts affected by the operation; preparing "blank" state transitions for them;
• Packing state transitions under main contract with additional blank transitions under other affected contracts into an anchor;
• Updating consignment with the newly formed anchor and state transition;
• Preparing disclosure, containing remaining blank state transitions. This disclosure will be used lately for updating stash when the witness transaction will be mined.

This completes compose of new state transfer consignment and corresponding witness transaction. The consignment is sent to the beneficiary, which must return a signature on this transfer. Once the signature is received, the witness transaction from the PSBT should be signed by all signers and published to the network - and RGB Node in parallel should enclose previously prepared disclosure to maintain the state of the remaining smart contracts valid.

PS Moved from https://github.com/orgs/LNP-BP/discussions/126