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, while
schema 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"

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

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

Last modified 9mo ago