StateLib

Git Source

State

State structure represents the state of Origin contract at some point of time.

• State is structured in a way to track the updates of the Origin Merkle Tree.
• State includes root of the Origin Merkle Tree, origin domain and some additional metadata.

Origin Merkle Tree

Hash of every sent message is inserted in the Origin Merkle Tree, which changes the value of Origin Merkle Root (which is the root for the mentioned tree).

• Origin has a single Merkle Tree for all messages, regardless of their destination domain.
• This leads to Origin state being updated if and only if a message was sent in a block.
• Origin contract is a "source of truth" for states: a state is considered "valid" in its Origin, if it matches the state of the Origin contract after the N-th (nonce) message was sent.

Memory layout of State fields

State could be used to form a Snapshot to be signed by a Guard or a Notary.

State Variables

OFFSET_ROOT

The variables below are not supposed to be used outside of the library directly.

uint256 private constant OFFSET_ROOT = 0;

OFFSET_ORIGIN

uint256 private constant OFFSET_ORIGIN = 32;

OFFSET_NONCE

uint256 private constant OFFSET_NONCE = 36;

OFFSET_BLOCK_NUMBER

uint256 private constant OFFSET_BLOCK_NUMBER = 40;

OFFSET_TIMESTAMP

uint256 private constant OFFSET_TIMESTAMP = 45;

OFFSET_GAS_DATA

uint256 private constant OFFSET_GAS_DATA = 50;

Functions

formatState

Returns a formatted State payload with provided fields

function formatState(
    bytes32 root_,
    uint32 origin_,
    uint32 nonce_,
    uint40 blockNumber_,
    uint40 timestamp_,
    GasData gasData_
) internal pure returns (bytes memory);

Parameters

Returns

castToState

Returns a State view over the given payload.

Will revert if the payload is not a state.

function castToState(bytes memory payload) internal pure returns (State);

castToState

Casts a memory view to a State view.

Will revert if the memory view is not over a state.

function castToState(MemView memView) internal pure returns (State);

isState

Checks that a payload is a formatted State.

function isState(MemView memView) internal pure returns (bool);

hashInvalid

Returns the hash of a State, that could be later signed by a Guard to signal that the state is invalid.

function hashInvalid(State state) internal pure returns (bytes32);

unwrap

Convenience shortcut for unwrapping a view.

function unwrap(State state) internal pure returns (MemView);

equals

Compares two State structures.

function equals(State a, State b) internal pure returns (bool);

leaf

Returns the hash of the State.

We are using the Merkle Root of a tree with two leafs (see below) as state hash.

function leaf(State state) internal pure returns (bytes32);

subLeafs

Returns "sub-leafs" of the State. Hash of these "sub leafs" is going to be used as a "state leaf" in the "Snapshot Merkle Tree". This enables proving that leftLeaf = (root, origin) was a part of the "Snapshot Merkle Tree", by combining rightLeaf with the remainder of the "Snapshot Merkle Proof".

function subLeafs(State state) internal pure returns (bytes32 leftLeaf_, bytes32 rightLeaf_);

leftLeaf

Returns the left "sub-leaf" of the State.

function leftLeaf(bytes32 root_, uint32 origin_) internal pure returns (bytes32);

rightLeaf

Returns the right "sub-leaf" of the State.

function rightLeaf(uint32 nonce_, uint40 blockNumber_, uint40 timestamp_, GasData gasData_)
    internal
    pure
    returns (bytes32);

root

Returns a historical Merkle root from the Origin contract.

function root(State state) internal pure returns (bytes32);

origin

Returns domain of chain where the Origin contract is deployed.

function origin(State state) internal pure returns (uint32);

nonce

Returns nonce of Origin contract at the time, when root was the Merkle root.

function nonce(State state) internal pure returns (uint32);

blockNumber

Returns a block number when root was saved in Origin.

function blockNumber(State state) internal pure returns (uint40);

timestamp

Returns a block timestamp when root was saved in Origin.

This is the timestamp according to the origin chain.

function timestamp(State state) internal pure returns (uint40);

gasData

Returns gas data for the chain.

function gasData(State state) internal pure returns (GasData);