SnapshotLib

Git Source

Snapshot

Snapshot structure represents the state of multiple Origin contracts deployed on multiple chains. In short, snapshot is a list of "State" structs. See State.sol for details about the "State" structs.

Snapshot usage

• Both Guards and Notaries are supposed to form snapshots and sign snapshot.hash() to verify its validity.
• Each Guard should be monitoring a set of Origin contracts chosen as they see fit.
• They are expected to form snapshots with Origin states for this set of chains, sign and submit them to Summit contract.
• Notaries are expected to monitor the Summit contract for new snapshots submitted by the Guards.
• They should be forming their own snapshots using states from snapshots of any of the Guards.
• The states for the Notary snapshots don't have to come from the same Guard snapshot, or don't even have to be submitted by the same Guard.
• With their signature, Notary effectively "notarizes" the work that some Guards have done in Summit contract.
• Notary signature on a snapshot doesn't only verify the validity of the Origins, but also serves as a proof of liveliness for Guards monitoring these Origins.

Snapshot validity

• Snapshot is considered "valid" in Origin, if every state referring to that Origin is valid there.
• Snapshot is considered "globally valid", if it is "valid" in every Origin contract.

Snapshot memory layout

Snapshot could be signed by both Guards and Notaries and submitted to Summit in order to produce Attestations that could be used in ExecutionHub for proving the messages coming from origin chains that the snapshot refers to.

Functions

formatSnapshot

Returns a formatted Snapshot payload using a list of States.

function formatSnapshot(State[] memory states) internal view returns (bytes memory);

Parameters

Returns

castToSnapshot

Returns a Snapshot view over for the given payload.

Will revert if the payload is not a snapshot payload.

function castToSnapshot(bytes memory payload) internal pure returns (Snapshot);

castToSnapshot

Casts a memory view to a Snapshot view.

Will revert if the memory view is not over a snapshot payload.

function castToSnapshot(MemView memView) internal pure returns (Snapshot);

isSnapshot

Checks that a payload is a formatted Snapshot.

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

hashValid

Returns the hash of a Snapshot, that could be later signed by an Agent to signal that the snapshot is valid.

function hashValid(Snapshot snapshot) internal pure returns (bytes32 hashedSnapshot);

unwrap

Convenience shortcut for unwrapping a view.

function unwrap(Snapshot snapshot) internal pure returns (MemView);

state

Returns a state with a given index from the snapshot.

function state(Snapshot snapshot, uint256 stateIndex) internal pure returns (State);

statesAmount

Returns the amount of states in the snapshot.

function statesAmount(Snapshot snapshot) internal pure returns (uint256);

snapGas

Extracts the list of ChainGas structs from the snapshot.

function snapGas(Snapshot snapshot) internal pure returns (ChainGas[] memory snapGas_);

calculateRoot

Returns the root for the "Snapshot Merkle Tree" composed of state leafs from the snapshot.

function calculateRoot(Snapshot snapshot) internal pure returns (bytes32);

proofSnapRoot

Reconstructs Snapshot merkle Root from State Merkle Data (root + origin domain) and proof of inclusion of State Merkle Data (aka State "left sub-leaf") in Snapshot Merkle Tree.

Reverts if any of these is true:

• State index is out of range.
• Snapshot Proof length exceeds Snapshot tree Height.

function proofSnapRoot(bytes32 originRoot, uint32 domain, bytes32[] memory snapProof, uint8 stateIndex)
    internal
    pure
    returns (bytes32);

Parameters

_isValidAmount

Checks if snapshot's states amount is valid.

function _isValidAmount(uint256 statesAmount_) internal pure returns (bool);