StateHub

Git Source

Inherits: AgentSecured, StateHubEvents, IStateHub

StateHub is a parent contract for Origin. It is responsible for the following:

• Keeping track of the historical Origin Merkle Tree containing all the message hashes.
• Keeping track of the historical Origin States, as well as verifying their validity.

State Variables

_tree

Historical Merkle Tree Note: Takes two storage slots

HistoricalTree private _tree;

_originStates

All historical contract States

OriginState[] private _originStates;

__GAP

gap for upgrade safety

uint256[47] private __GAP;

Functions

isValidState

Check that a given state is valid: matches the historical state of Origin contract. Note: any Agent including an invalid state in their snapshot will be slashed upon providing the snapshot and agent signature for it to Origin contract.

*Will revert if any of these is true:

• State payload is not properly formatted.*

function isValidState(bytes memory statePayload) external view returns (bool isValid);

Parameters

Returns

statesAmount

Returns the amount of saved states so far.

This includes the initial state of "empty Origin Merkle Tree".

function statesAmount() external view returns (uint256);

suggestLatestState

Suggest the data (state after latest sent message) to sign for an Agent. Note: signing the suggested state data will will never lead to slashing of the actor, assuming they have confirmed that the block, which number is included in the data, is not subject to reorganization (which is different for every observed chain).

function suggestLatestState() external view returns (bytes memory stateData);

Returns

suggestState

Given the historical nonce, suggest the state data to sign for an Agent. Note: signing the suggested state data will will never lead to slashing of the actor, assuming they have confirmed that the block, which number is included in the data, is not subject to reorganization (which is different for every observed chain).

function suggestState(uint32 nonce) public view returns (bytes memory stateData);

Parameters

Returns

_initializeStates

Initializes the saved states list by inserting a state for an empty Merkle Tree.

function _initializeStates() internal;

_insertAndSave

Inserts leaf into the Merkle Tree and saves the updated origin State.

function _insertAndSave(bytes32 leaf) internal;

_saveState

Saves an updated state of the Origin contract

function _saveState(bytes32 root, OriginState memory state) internal;

_nextNonce

Returns nonce of the next sent message: the amount of saved States so far. This always equals to "total amount of sent messages" plus 1.

function _nextNonce() internal view returns (uint32);

_isValidState

Checks if a state is valid, i.e. if it matches the historical one. Reverts, if state refers to another Origin contract.

function _isValidState(State state) internal view returns (bool);

_formatOriginState

Returns a formatted payload for a stored OriginState.

function _formatOriginState(OriginState memory originState, bytes32 root, uint32 origin, uint32 nonce)
    internal
    pure
    returns (bytes memory);

_fetchGasData

Child contract should implement the logic for getting the current gas data from the gas oracle to be saved as part of the Origin State.

function _fetchGasData() internal view virtual returns (GasData);

_toOriginState

Returns a OriginState struct to save in the contract.

function _toOriginState() internal view returns (OriginState memory originState);

_areEqual

Checks that a state and its Origin representation are equal.

function _areEqual(State state, OriginState memory originState) internal pure returns (bool);

Structs

OriginState

struct OriginState {
    uint40 blockNumber;
    uint40 timestamp;
    GasData gasData;
}