AttestationLib

Git Source

Attestation

Attestation structure represents the "Snapshot Merkle Tree" created from every Notary snapshot accepted by the Summit contract. Attestation includes" the root of the "Snapshot Merkle Tree", as well as additional metadata.

Steps for creation of "Snapshot Merkle Tree":

1. The list of hashes is composed for states in the Notary snapshot.
2. The list is padded with zero values until its length is 2**SNAPSHOT_TREE_HEIGHT.
3. Values from the list are used as leafs and the merkle tree is constructed.

Differences between a State and Attestation

Similar to Origin, every derived Notary's "Snapshot Merkle Root" is saved in Summit contract. The main difference is that Origin contract itself is keeping track of an incremental merkle tree, by inserting the hash of the sent message and calculating the new "Origin Merkle Root". While Summit relies on Guards and Notaries to provide snapshot data, which is used to calculate the "Snapshot Merkle Root".

• Origin's State is "state of Origin Merkle Tree after N-th message was sent".
• Summit's Attestation is "data for the N-th accepted Notary Snapshot" + "agent merkle root at the time snapshot was submitted" + "attestation metadata".

Attestation validity

• Attestation is considered "valid" in Summit contract, if it matches the N-th (nonce) snapshot submitted by Notaries, as well as the historical agent merkle root.
• Attestation is considered "valid" in Origin contract, if its underlying Snapshot is "valid".
• This means that a snapshot could be "valid" in Summit contract and "invalid" in Origin, if the underlying snapshot is invalid (i.e. one of the states in the list is invalid).
• The opposite could also be true. If a perfectly valid snapshot was never submitted to Summit, its attestation would be valid in Origin, but invalid in Summit (it was never accepted, so the metadata would be incorrect).
• Attestation is considered "globally valid", if it is valid in the Summit and all the Origin contracts.

Memory layout of Attestation fields

Attestation could be signed by a Notary and submitted to Destination in order to use if for proving messages coming from origin chains that the initial snapshot refers to.

State Variables

OFFSET_SNAP_ROOT

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

uint256 private constant OFFSET_SNAP_ROOT = 0;

OFFSET_DATA_HASH

uint256 private constant OFFSET_DATA_HASH = 32;

OFFSET_NONCE

uint256 private constant OFFSET_NONCE = 64;

OFFSET_BLOCK_NUMBER

uint256 private constant OFFSET_BLOCK_NUMBER = 68;

OFFSET_TIMESTAMP

uint256 private constant OFFSET_TIMESTAMP = 73;

Functions

formatAttestation

Returns a formatted Attestation payload with provided fields.

function formatAttestation(bytes32 snapRoot_, bytes32 dataHash_, uint32 nonce_, uint40 blockNumber_, uint40 timestamp_)
    internal
    pure
    returns (bytes memory);

Parameters

Returns

castToAttestation

Returns an Attestation view over the given payload.

Will revert if the payload is not an attestation.

function castToAttestation(bytes memory payload) internal pure returns (Attestation);

castToAttestation

Casts a memory view to an Attestation view.

Will revert if the memory view is not over an attestation.

function castToAttestation(MemView memView) internal pure returns (Attestation);

isAttestation

Checks that a payload is a formatted Attestation.

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

hashValid

Returns the hash of an Attestation, that could be later signed by a Notary to signal that the attestation is valid.

function hashValid(Attestation att) internal pure returns (bytes32);

hashInvalid

Returns the hash of an Attestation, that could be later signed by a Guard to signal that the attestation is invalid.

function hashInvalid(Attestation att) internal pure returns (bytes32);

unwrap

Convenience shortcut for unwrapping a view.

function unwrap(Attestation att) internal pure returns (MemView);

snapRoot

Returns root of the Snapshot merkle tree created in the Summit contract.

function snapRoot(Attestation att) internal pure returns (bytes32);

dataHash

Returns hash of the Agent Root and SnapGasHash combined into a single hash.

function dataHash(Attestation att) internal pure returns (bytes32);

dataHash

Returns hash of the Agent Root and SnapGasHash combined into a single hash.

function dataHash(bytes32 agentRoot_, bytes32 snapGasHash_) internal pure returns (bytes32);

nonce

Returns nonce of Summit contract at the time, when attestation was created.

function nonce(Attestation att) internal pure returns (uint32);

blockNumber

Returns a block number when attestation was created in Summit.

function blockNumber(Attestation att) internal pure returns (uint40);

timestamp

Returns a block timestamp when attestation was created in Summit.

This is the timestamp according to the Synapse Chain.

function timestamp(Attestation att) internal pure returns (uint40);