RGB glossary, part I

[dr-orlovsky]

Legal terms

RGB contract

is an agreement between contract parties structured in a form of bearer digital contract. The contract may relate to the both digital of physical assets and events. Contracts which relate to only digital world potentially may be settled in an automatic way without involving any third parties or indermidiaries outside of the contract parties. RGB contracts may provide an ability for the broader public, which is not a part of the contract parties to participate contract operations via mechanism of valencies and state extensions.

A contract has state and business logic, expressed in terms of ownership rights and executive rights. The contract state, rights and conditions of valid operations are defined using RGB schema; only state and operations which allowed by the schema declarations and valdiation scripts are allowed to happen withint the contract scope.

Contract participant

an actor which participate in contract operations. Contract parties are classified into the following categories:

• Contract issuer, an actor creating contract genesis
• Contract party – all actors which has ownership rights over RGB contract state
• Public &ndash an actor constructing state extensions. Can exist only in contracts providing valencies and state extensions.

Contract issuer

a contract participant has created the contract genesis

Contract parties

RGB contract always have a well-defined parties of the contract, which hold ownership rights over atoms of state. The state owned by a contract party is called owned state.A contract party is always also a contract participant.

Contract rights

RGB contract parties have a different rights as a part of the contract conditions defined through RGB schema. The rights under RGB contract can be classified into the following categories:

• Ownership rights
• Executive rights
• Public rights

Ownership rights

a party having rights over some of the owned contract state. This is exactly the same party which can spend bitcoin UTXO serving as a single-use-seal definition for the state assignment.

It is important to note that ownership rights and ability to spend UTXO participating assignment doesn't necessary implies ability to update the contract state or construct a valid state transition (see executive rights). See rights mismatch section for the details.

Executive rights

ability to update the contract state in a final form, i.e. to construct a valid state transition satisfying schema validation rules. See also rights mismatch and ownership rights to better understand the difference of executive and ownership rights in the scope of RGB smart contract.

Public rights

a right under some schemata to use a contract valency and construct a valid state extensions, which can be later included into the state via reference from a different valid state transition. See state extension for the details.

Rights mismatch

a mismatch between ownership rights and executive rights; an inability to provide an update to the state owned by a party. This is caused due to the schema bugs leading to the impossibility to construct a valid state transition with a specific set of ownership rights of the party and/or combination of seal definitions in their assignments.

Rights mismatch may happen in two main cases:

A user by mistake has assigned different rights to the same UTXO and the schema doesn't provide a way of spending that combination of rights with a valid state transition. This is a reason why properly-designed schema must provide a rights split transition option.
A schema doesn't provide a way of constructing state transition for a defined owned state

Contractum compiler notifies about this two bugs during schema compilation, however schemata designed without Contractum may still contain it.

RGB consensus-level terms, part I

RGB consensus

A form of client-side-validation consensus based on bitcoin consensus, UTXO TapRet/OpRet single-use-seals, multi-protocol commitments and consensus-ordered history of contract operations valid under a given RGB schema

RGB consensus has the following layers

1. Nakamoto consensus (bitcoin proof of work)
2. LNPBP10 seals
3. Deterministic bitcoin commitments using either TapRet and OpRet procedures
4. Multi-protocol commitments with LNPBP-4 standard, allowing to pack state transitions under different RGB contracts in an independent way

Data type

is a declaration of structured data used in an RGB contract as a part of the state. Uses strict encoding schema, i.e. data types are always composed of strict encoding type primitives and use strict encoding for the binary serialization.

Data types are defined in the same terms as variable types in any structural language (C, Rust, Haskell, etc).

Contract state

the state of an RGB contract; consists of state atoms of different data types. State classified into two categories: global state and owned state.

Contract participants usually have only a partial view on the contract state, with some parts of the state not known to them at all (even the fact of its existence), some parts known only in form of zero-knowledge proofs – and some state known.

The contract state is constructed starting from the contract genesis by consecutively applying operations from the history in their consensus order. Notwithstanding the fact of the partial view of the contract participant (and, as a result, of RGB Node run by that participant) on the contract state, consensus ordering allows the following statements to hold true

• Contract state is a part of the RGB consensus
• All participants have a non-contradictory information about the contract state, meaning that if peer `A` has state transitions `a` < `c`, peer `B` has state transitions `a` < `b`, and peer `C` has state transitions `b` < `c`, than their orders are in concord between each other and with a global ordering of `a` < `b` < `c`.

Contract operations

An update to the contract state performed according to the rules defined in the contract schema.

Contract operations include:

• Genesis
• State transitions
• State extensions

Contract nodes

The same as contract operations, but in a serialized on in-memory structured form. Used in the context of RGB core and standard libraries APIs.

Consensus order (of contract operations)

Deterministic ordering of all operations under a given contract based on the bitcoin consensus.

All state transitions in an RGB contract (both stash-stored and new one coming with consignment) have a deterministic ordering, which will be the same on the consensus level, meaning that each RGB Node (or other software based on RGB Core-core consensus engine) will come to the same order of state transition for a given contract. If two peers have a different subset of state transitions, the order they get will still be non-contradictory, specifically: if peer `A` has state transitions `a` < `c`, peer `B` has state transitions `a` < `b`, and peer `C` has state transitions `b` < `c`, than their orders are in concord between each other and with a global ordering of `a` < `b` < `c`.

The full definition of the consensus ordering can be found in RGB core issue #117

RGB schema

The schema defines a rules of how the contract operates. Specifically it declares

• contract state of the contract
• rules for updating the contract state

A schema does that by providing declarations and implementation for the following components:

• used data types
• types of global state and owned state
• structure of the contract operations
• validation logic for the contract state and operations, defined through (1) type system and (2) custom validation scripts, compiled to either EmbeddedVM or AluVM virtual machine instructions

In the result, a schema defines the following:

• Global state
• Ownership rights
• Executive rights
• Public rights

One may think of a schema as a "class" definition in the OOP world; in that terms specific RGB contracts are "class instance" created by the schema constructor (see genesis). Such approach allows to separate role of contract developer (in RGB called schema developer) and contract issuer: the first one needs to be an experienced developer, while the second one is not required to know anything about coding or security at all. This also promotes re-use of common codebase by different issuers for the same typical use cases (like fungible assets), reducing the risk of mistakes.

See also RGB consensus

Genesis

a contrat operation initializing the contract state. Must commit to a specific schema under which the contract is created.

State transition

is a contract operation updating the contract state which may be performed by a contract party possessing executive rights. A set of state transitions available for the contract is defined in the schema.

A state transition has inputs, referencing the assignments from the previous contract operations, outputs, constructing new assignments, and an optional declaration of valencies.

State extension

allows to extend (add a new or update existing) contract state. It can can be created by anybody without doing an on-chain commitment (i.e. without closing any single-use-seals). In this it is similar to genesis. However, the state created by the extension is not "final" (compare to an non-mined transaction in the bitcoin mempool) until it gets included into a valid state transition (like transaction gets mined by being included into bitcoin valid block).

Probably the simplest way to understand state extensions is by example. Let's assume we'd like to do an asset which can be issued by anybody in the world through burning equivalent amount of bitcoins. Such operation can't be a state transition, since we do not have a predefined set of single-use-seals to define a "rights of issue" for an open and unknown set of participants. We can't also do "multiple geneses", since each genesis will define a new RGB contract and the assets under different RGB contracts are not fungible. State extensions were created exactly to address this issue.

Assignment

A one-to-one mapping between seal definition and state data. A state assigned to a single-use-seal is called owned state.

Owned state

A form of state s assigned to a seal definition (see also single-use-seals). It is created as a result of contract operations applied in the consensus order, starting from the contract genesis, which defines the initial contract state. The types of the owned state, its validation rules and how contract operations may affect it are defined in the schema.

Global state

in many situations a contract needs a state which is "global" for the contract and is not "owned" by anyone (i.e. not assigned to a UTXO single-use-seal, see owned state). For instance, the name of a fungible asset (and ticker) is that sort of information: it does not "belong" to a contract party but instead is a "property" of the contract itself. Another example could be the name of the identity holder which can't be changed and thus can't be assigned to a UTXO single-use-seal.

It is important to note, that while the global state is not "directly owned" by any contract party, it still may be updated through state transitions – but only if schema enables that explicitly. In such cases the use of the global state (as compared to the owned state) is reasonable only when it may be possible to opt-out from future state updates (i.e. do not define a new single-use-seals) but still needs to keep the state. The asset name is again such an example, since even if the asset can be renamed, future renames after certain renaming may be prohibited (i.e. no new owned state can be created), but the asset name should stay; global allows exactly that.

Valency

declaration a possibility of the public participation in the contract logic made in the schema (see public rights). To be executed it requires the schema also to declare a state transition< using the valency./dd>

Contract interface

a standard for contract API as it can be used by the software, like RGB node, wallets etc. Contract interface provides a way to abstract contract-specific business logic and present pieces of it in a standard form. For instance, it can be used as a way of communicating with RGB Node, like asking it for a semantically-meaningful state and creating operations.

The concept of RGB contract interface is similar to the concept of ERC standards and ABI files in Ethereum world; the most common interfaces are called "RGBxx" and are defined as a separate LNP/BP standards.

List of interfaces standardized by LNP/BP Standards Association:

• RGB20: fungible assets (tokens etc) issued by centralized party
• RGB21: non-fungible collectibles ("traditional" NFTs). Represent ownership rights for any form of digital or physical property, including art and media files (audio, video, books, texts, images etc).
• RGB22: digital identity standard (also NFT)
• RGB23: provable audit logs
• RGB30: fungible assets with decentralized issuance and on-chain issue proofs (wrapped bitcoins etc)

Rights split transition (RST)

A transition taking any combination of all owned rights defined by a schema and mapping them one-to-one to the new assignments, without changing the contract state or doing any other form of validation. Technically equivalent to the blank transition, but semantically different to it since it is constructed by a wallet in solving right mismatches and not by an RGB Node.

Blank transition (BT)

A transition taking any combination of all owned rights defined by a schema and mapping them one-to-one to the new assignments, without changing the contract state or doing any other form of validation. Technically equivalent to the blank transition, but semantically different to it since it is constructed by an RGB Node (and not by a wallet) in moving other contract's state assigned to the same seal that is closed in as a part of a given state transition under some contract.

[EthanShang8989]

Could you please add explanations for the following vocabulary: 'stock', 'stash', 'inventory', 'batch', 'opid', 'bundles','bindle','hoard'and 'fascia'?