Contract state
State declarations are provided in a form of
global
|owned
STATE_NAME POSTFIX :: STATE_TYPE, where POSTFIX denotes how the state is accumulated with each of the operations. The following postfixes are allowed:Postfix | Applicable to | Meaning |
---|---|---|
none | global , owned | Singular state: contract has just a single value or defined single-use-seal for the state of that time |
? | global , owned | Optional state: contract may have no state of this type - or can have a singular state. |
* | global , owned | State is a list, to which genesis and contract operations can add more item(s). The list may be empty, genesis may not assign an initial value for the state. |
+ | global , owned | State is a non-empty list, to which genesis and contract operations can add more item(s). The list can't be empty, genesis must assign an initial value for the state |
{*} | global only | State is a set, to which genesis and contract operations can add more item(s). The set may be empty, genesis may not assign an initial value for the state. |
{+} | global only | State is a non-empty set, to which genesis and contract operations can add more item(s). The set can't be empty, genesis must assign an initial value for the state |
{Key*} | global only | State is a map, to which genesis and contract operations can add more keyed item(s). The map may be empty, genesis may not assign an initial value for the state. |
{Key+} | global only | State is a non-empty map, to which genesis and contract operations can add more keyed item(s). The map can't be empty, genesis must assign an initial value for the state |
Lists, sets and maps are called state collections. Lists in case of a global state are ordered according to the consensus ordering; for owned state the data are not ordered in any specific order.
Only a part of the owned state can be known, i.e. postfix doesn't guarantee the availability of all owned state data as a part of the known contract state.
Postfix puts a requirements on the state which can or must be provided by genesis and state transitions. This is the summary of these requirements:
Schema | Genesis | Transitions | Contract state |
---|---|---|---|
State :: Type | <- State | none,
<- State
<- State? | Single, always present value |
State?
:: Type | none,
<-State? | none,
<-State? | Optional value of type |
State*
:: Type | none,
<-State?
<-State
<-[State]
<-[State+]
<-{State}
<-{State+} | none,
<-State?
<-State
<-[State]
<-[State+]
<-{State}
<-{State+} | List of values, which may be empty, ordered by consensus ordering |
State+
:: Type | <-State
<-[State+]
<-{State+} | none,
<-State?
<-State
<-[State]
<-[State+]
<-{State}
<-{State+} | List of values with at least one value |
state{*}
:: Type | none,
<-State?
<-State
<-{State}
<-{State+} | none,
<-State?
<-State
<-{State}
<-{State+} | Set of values, which may be empty, ordered by values |
State{+}
:: {Type+} | <-State
<-{State+} | none,
<-State?
<-State
<-{State}
<-{State+} | Set of values with at least one value, ordered by values |
state{Key*}
:: Type | none,
<-{Key->State}
<-{Key->+State} | none,
<-{Key->State}
<-{Key->+State} | Map from keys to types, which may be empty, ordered by key value |
State{Key+} :: {Type} | none,
<-{Key->+State} | none,
<-{Key->State}
<-{Key->+State} | Map from keys to types, with at least one key and value |
Other confined bounds (like
[T; N]
, [T^A..B]
etc) than the above listed comprehensions are prohibited to appear in the schema state declaration. The maximum number of elements in a global state collection is always restricted to 0xFFFF
, the maximum number of state items in an owned state is not bounded to any upper limit (due to inability of enforcing that restriction).If a global state needs to be a collection type by itself (for instance to be a string), it can be declared in a usual manner, with all comprehensions allowed.
It is important to remember about the difference between collections provided as a state value type, and a state itself operating as a collection. For instance,
schema Some
global State :: [Utf8]
means that the
State
consists of a single string, and it is replaced with new operations providing that state, whileschema Some
global State[] :: [Utf8]
means that the state is list of strings which accumulate over the time. If both of the contracts are created with
State := "abc"
in genesis, and than receive three consequent transitions with State := "xyz"
, State := "klm"
and State := "qrs"
, the resulting contract state in the first case would be State := ["abc", "xyz", "klm", "qrs"]
and in the second case State := "qrs"
Last modified 9mo ago