RGB Node contract state API

[dr-orlovsky]

Since the release of v0.8 of RGB Node and LNP/BP protocol stack we have had quite a progress in making RGB ecosystem more opened. Specifically, we have introduced

• upgrade of RGB20, 21 and other standard protocols from specific schema implementation to interfaces which can cover many different schema
• allowed smart contracts to implement multiple interfaces, such that assets of different types can interact within one contract
• new contractum language for describing interfaces

All of this requires significant changes (re-write) of the RGB Node API. This proposal tries to start a discussion on the best way of doing that. It takes some ideas from previous discussion in #221 and develops them further.

We do not target the functionality described here to a specific future RGB Node release. Most of this functionality exists on the levels above RGB consensus, so can be gradually introduced without soft or hardforks and its adoption can be spanned across multiple releases.

Workflow

Upon installation RGB Node would not know anything about RGB schemata nor iterfaces; it would be exposing "raw" contract state as it does today, which is not very readable for a wallet.

This can be improved by importing interface into RGB Node

$ curl -o https://repo.rgb.tech/rgb20.rgb

$ rgb info rgb20.rgb
type: interface
name: RGB20
developer: 
  name: LNP/BP Standards Association
  url: https://lnp-bp.org
  trust: trusted
signature: valid

$ rgb-cli import rgb20.rgb
Importing RGB20 interface by LNP/BP Standards Association ... success
Indexing contracts exposing RGB20 API ... complete

Warning: none of the known contracts expose RGB20 API. 
Some of this contracts may still support RGB20, but you have
to import interface implementation from the contract developer.

As you can read this does not give much since RGB Node can't know how to apply interface to existing contract: this can be defined only by a contract developer. Interface is not a part of the consensus layer, thus RGB schema doesn't say anything about interfaces it implements. Also, a developer may add more interfaces to the schema after a release, or update an interface version without re-issuing the schema or contracts under it.

If you take our analogy with RGB schema to be equal to a class in Java or struct in Rust, interface to be equal to a Java interface or Rust trait, and a contract to be equal to an object or an instance: library developer defines a class/struct like struct SomeStruct { ... } may later add multiple trait implementations on it in other libraries without changing the library which ships the original structure.

There will be a way for the contract developers to ship interface implementation together with a schema as a part of RGB package -- and also include it into a consignment, such that information about interface implementation will automatically propagate -- but here for the demo purposes we assume that it doesn't happens yet. In this case it can be manually imported in this way:

$ curl -o https://token-issuer.xyz/token-rgb20.rgb
$ rgb-cli import token-rgb20.rgb
Importing RGB20 interface implementation for contract ... success
Indexing contract exposing RGB20 API ... complete

Now we should be able to query the contract state with the interface:

$ rgb-cli state -i RGB20 rgb1....

This should provide (I use YAML for reading simplicity, but it can be JSON by using -f jsonflag)

denomination:
  ticker: OTI
  name: One time issued token
  details: Absolutely useless
  precision: 8
contract: some legal text
issued:
  - 1000000000000000
assets:
  - fac503c4641c3deda72a2d00bc9d6ff1094b15276c386efea403746a91436772:0:
    - 100000000000000
  - fac503c4641c3deda72a2d00bc9d6ff1094b15276c386efea403746a91436772:1:
    - 900000000000000

State mapping

The following rules will apply to map the state of the contract to the interface:

1. Global singular state (which has no postfixes like ?, * or +) is provided as an object printout. For instance, for Denomination state defined in RGB20
   output would be an object denomination as printed out in the example above
2. Global optional state will be either an object (if set) or ~ (for YAML, nil for JSON) otherwise
3. For a global appendable state (i.e. posfixed with * or +) the output would always be a list of objects, like issued in the example above
4. Owned state will represented by form of SEAL: [ STATE ], where SEAL is always a txid:vout pair and STATE is the actual object of the state.
   • unlike in new transition creation, the SEAL always has txid even for witness-based seals, which is taken from the anchor data;
   • the state is always provided as a list, since there always can be multiple state assignments for the same seal.
   • if the state is optional or can be a list (?, * or + in the interface declaration, like for Issued in RGB20) it is reported as a [ SEAL: [ STATE ] ] and not as a single object.

It can be that the node dosn't know full contract state. For an owned state, this can be due to the concealed seal or state data, or due to state transitions which are not known. In all of these cases, the unknown state is not reported anyhow and only a known state is listed. NB: this is the case even if a state is known, while a seal is concealed with an unknown blinding.

For a global state, which can be unknown only due to an absence of a state transition which can modify that state, a last known state is reported.

Node can also provide an insights into the global state using special query with -F flag set:

$ rgb-cli state -F -i RGB20 rgb1....

denomination:
  mutable: true
  final: ~
  genesis:
    ticker: OTI
    name: One time issued token
    details: Absolutely useless
    precision: 8
  lastKnown:
    ticker: OTI
    name: One time issued token
    details: Absolutely useless
    precision: 8
contract: 
  mutable: false
  final: some legal text
  genesis: some legal text
issued:
  mutable: false
  history:
   - 1000000000000000
   - ~ # indicates presence of an unknown state transition
assets:
  known:
    - fac503c4641c3deda72a2d00bc9d6ff1094b15276c386efea403746a91436772:0:
      - 100000000000000
    - fac503c4641c3deda72a2d00bc9d6ff1094b15276c386efea403746a91436772:1:
      - 900000000000000
  concealedSeal:
    - 500
  hasConcealedState: true
  hasFullyConcealed: true
  hasUnknown: true

Here, unknown final global state is indicated with ~ (nil in JSON). Immutable global state (i.e. state which can't be changed/appended with any state transition) does not include lastKnown field.

Concealed state is not reported in full since it would create a huge log for any of the assets. "Unknown" owned state is the state which may be present in a state transitions which are not known, for instance when a known single-use-seal is spent without state transition information - or when any concealed owned state is present.

[dr-orlovsky]

Immutable global state (i.e. state which can't be changed/appended with any state transition) does not include lastKnown field.

Interface defines only a part of a possible smart contract functionality (since a contract may implement multiple interfaces), and even if a global state can't be changed with state transitions known to the interface, it still can be changed with other types of state transitions. Thus, RGB Node has to analyze global state mutability outside of the scope of any particular interface, and use that data.