SnapshotHub

Inherits: AgentSecured, SnapshotHubEvents, ISnapshotHub

SnapshotHub is a parent contract for Summit. It is responsible for the following:

Accepting and storing Guard and Notary snapshots to keep track of all the remote Origin states.
Generating and storing Attestations derived from Notary snapshots, as well as verifying their validity.

State Variables

_states

All States submitted by any of the Guards

SummitState[] private _states;

_guardSnapshots

All Snapshots submitted by any of the Guards

SummitSnapshot[] private _guardSnapshots;

_notarySnapshots

All Snapshots submitted by any of the Notaries

SummitSnapshot[] private _notarySnapshots;

_attestations

All Attestations created from Notary-submitted Snapshots Invariant: _attestations.length == _notarySnapshots.length

SummitAttestation[] private _attestations;

_leafPtr

Pointer for the given State Leaf of the origin with ZERO as a sentinel value for "state not submitted yet".

mapping(uint32 => mapping(bytes32 => uint256)) private _leafPtr;

_latestStatePtr

Pointer for the latest Agent State of a given origin with ZERO as a sentinel value for "no states submitted yet".

mapping(uint32 => mapping(uint32 => uint256)) private _latestStatePtr;

_latestAttNonce

Latest nonce that a Notary created

mapping(uint32 => uint32) private _latestAttNonce;

__GAP

gap for upgrade safety

uint256[43] private __GAP;

Functions

isValidAttestation

Check that a given attestation is valid: matches the historical attestation derived from an accepted Notary snapshot.

*Will revert if any of these is true:

Attestation payload is not properly formatted.*

function isValidAttestation(bytes memory attPayload) external view returns (bool isValid);

Parameters

Name	Type	Description
`attPayload`	`bytes`	Raw payload with attestation data

Returns

Name	Type	Description
`isValid`	`bool`	Whether the provided attestation is valid

getAttestation

Returns saved attestation with the given nonce.

Reverts if attestation with given nonce hasn't been created yet.

function getAttestation(uint32 attNonce)
    external
    view
    returns (bytes memory attPayload, bytes32 agentRoot, uint256[] memory snapGas);

Parameters

Name	Type	Description
`attNonce`	`uint32`	Nonce for the attestation

Returns

Name	Type	Description
`attPayload`	`bytes`	Raw payload with formatted Attestation data
`agentRoot`	`bytes32`	Agent root hash used for the attestation
`snapGas`	`uint256[]`	Snapshot gas data used for the attestation

getLatestAgentState

Returns the state with the highest known nonce submitted by a given Agent.

function getLatestAgentState(uint32 origin, address agent) external view returns (bytes memory stateData);

Parameters

Name	Type	Description
`origin`	`uint32`	Domain of origin chain
`agent`	`address`	Agent address

Returns

Name	Type	Description
`stateData`	`bytes`	statePayload Raw payload with agent's latest state for origin

getLatestNotaryAttestation

Returns latest saved attestation for a Notary.

function getLatestNotaryAttestation(address notary)
    external
    view
    returns (bytes memory attPayload, bytes32 agentRoot, uint256[] memory snapGas);

Parameters

Name	Type	Description
`notary`	`address`	Notary address

Returns

Name	Type	Description
`attPayload`	`bytes`	Raw payload with formatted Attestation data
`agentRoot`	`bytes32`	Agent root hash used for the attestation
`snapGas`	`uint256[]`	Snapshot gas data used for the attestation

getGuardSnapshot

Returns Guard snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getGuardSnapshot(uint256 index) external view returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Name	Type	Description
`index`	`uint256`	Snapshot index in the list of all Guard snapshots

Returns

Name	Type	Description
`snapPayload`	`bytes`	Raw payload with Guard snapshot
`snapSignature`	`bytes`	Raw payload with Guard signature for snapshot

getNotarySnapshot

Returns Notary snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getNotarySnapshot(uint256 index) public view returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Name	Type	Description
`index`	`uint256`	Snapshot index in the list of all Notary snapshots

Returns

Name	Type	Description
`snapPayload`	`bytes`	Raw payload with Notary snapshot
`snapSignature`	`bytes`	Raw payload with Notary signature for snapshot

getNotarySnapshot

Returns Notary snapshot from the list of all accepted Guard snapshots.

Reverts if snapshot with given index hasn't been accepted yet.

function getNotarySnapshot(bytes memory attPayload)
    external
    view
    returns (bytes memory snapPayload, bytes memory snapSignature);

Parameters

Name	Type	Description
`attPayload`	`bytes`

Returns

Name	Type	Description
`snapPayload`	`bytes`	Raw payload with Notary snapshot
`snapSignature`	`bytes`	Raw payload with Notary signature for snapshot

getSnapshotProof

Returns proof of inclusion of (root, origin) fields of a given snapshot's state into the Snapshot Merkle Tree for a given attestation.

*Reverts if any of these is true:

Attestation with given nonce hasn't been created yet.
State index is out of range of snapshot list.*

function getSnapshotProof(uint32 attNonce, uint8 stateIndex) external view returns (bytes32[] memory snapProof);

Parameters

Name	Type	Description
`attNonce`	`uint32`	Nonce for the attestation
`stateIndex`	`uint8`	Index of state in the attestation's snapshot

Returns

Name	Type	Description
`snapProof`	`bytes32[]`	The snapshot proof

_acceptGuardSnapshot

Accepts a Snapshot signed by a Guard. It is assumed that the Guard signature has been checked outside of this contract.

function _acceptGuardSnapshot(Snapshot snapshot, uint32 guardIndex, uint256 sigIndex) internal;

_acceptNotarySnapshot

Accepts a Snapshot signed by a Notary. It is assumed that the Notary signature has been checked outside of this contract. Returns the attestation created from the Notary snapshot.

function _acceptNotarySnapshot(Snapshot snapshot, bytes32 agentRoot, uint32 notaryIndex, uint256 sigIndex)
    internal
    returns (bytes memory attPayload);

_initializeAttestations

Initializes the saved _attestations list by inserting empty values.

function _initializeAttestations() internal;

_saveGuardSnapshot

Saves the Guard snapshot.

function _saveGuardSnapshot(uint256[] memory statePtrs, uint256 sigIndex) internal;

_saveNotarySnapshot

Saves the Notary snapshot and the attestation created from it. Returns the created attestation.

function _saveNotarySnapshot(
    Snapshot snapshot,
    uint256[] memory statePtrs,
    bytes32 agentRoot,
    uint32 notaryIndex,
    uint256 sigIndex
) internal returns (bytes memory attPayload);

_saveState

Add a single element to both _attestations and _notarySnapshots, enforcing the (_attestations.length == _notarySnapshots.length) invariant.

Saves the state signed by a Guard.

function _saveState(State state, uint32 guardIndex) internal returns (uint256 statePtr);

_isValidAttestation

Checks if attestation was previously submitted by a Notary (as a signed snapshot).

function _isValidAttestation(Attestation att) internal view returns (bool);

_restoreSnapshot

Restores Snapshot payload from a list of state pointers used for the snapshot.

function _restoreSnapshot(SummitSnapshot memory snapshot)
    internal
    view
    returns (bytes memory snapPayload, bytes memory snapSignature);

_restoreSnapGas

Restores the gas data from the snapshot.

function _restoreSnapGas(SummitSnapshot memory snapshot) internal view returns (uint256[] memory snapGas);

_stateAgents

Returns indexes of agents who provided state data for the Notary snapshot with the given nonce.

function _stateAgents(uint32 nonce, uint8 stateIndex) internal view returns (uint32 guardIndex, uint32 notaryIndex);

_statePtr

Returns the pointer for a matching Guard State, if it exists.

function _statePtr(State state) internal view returns (uint256);

_latestState

Returns the latest state submitted by the Agent for the origin. Will return an empty struct, if the Agent hasn't submitted a single origin State yet.

function _latestState(uint32 origin, uint32 agentIndex) internal view returns (SummitState memory state);

_formatSummitState

Returns a formatted payload for a stored SummitState.

function _formatSummitState(SummitState memory summitState) internal pure returns (bytes memory);

_toSummitState

Returns a SummitState struct to save in the contract.

function _toSummitState(State state, uint32 guardIndex) internal pure returns (SummitState memory summitState);

_formatSummitAttestation

Returns a formatted payload for a stored SummitAttestation.

function _formatSummitAttestation(SummitAttestation memory summitAtt, uint32 nonce)
    internal
    pure
    returns (bytes memory);

_toSummitAttestation

Returns an Attestation struct to save in the Summit contract. Current block number and timestamp are used.

function _toSummitAttestation(bytes32 snapRoot, bytes32 agentRoot, bytes32 snapGasHash)
    internal
    view
    returns (SummitAttestation memory summitAtt);

_areEqual

Checks that an Attestation and its Summit representation are equal.

function _areEqual(Attestation att, SummitAttestation memory summitAtt) internal pure returns (bool);

Structs

SummitState

Struct that represents stored State of Origin contract

struct SummitState {
    bytes32 root;
    uint32 origin;
    uint32 nonce;
    uint40 blockNumber;
    uint40 timestamp;
    GasData gasData;
    uint32 guardIndex;
    uint32 notaryIndex;
}

SummitSnapshot

struct SummitSnapshot {
    uint256[] statePtrs;
    uint256 sigIndex;
}

SummitAttestation

struct SummitAttestation {
    bytes32 snapRoot;
    bytes32 agentRoot;
    bytes32 snapGasHash;
    uint40 blockNumber;
    uint40 timestamp;
}