StatementInbox

Git Source

Inherits: MessagingBase, StatementInboxEvents, IStatementInbox

StatementInbox is the entry point for all agent-signed statements. It verifies the agent signatures, and passes the unsigned statements to the contract to consume it via acceptX functions. Is is also used to verify the agent-signed statements and initiate the agent slashing, should the statement be invalid. StatementInbox is responsible for the following:

• Accepting State and Receipt Reports to initiate a dispute between Guard and Notary.
• Storing all the Guard Reports with the Guard signature leading to a dispute.
• Verifying State/State Reports referencing the local chain and slashing the signer if statement is invalid.
• Verifying Receipt/Receipt Reports referencing the local chain and slashing the signer if statement is invalid.

State Variables

agentManager

address public agentManager;

origin

address public origin;

destination

address public destination;

_storedSignatures

bytes[] internal _storedSignatures;

_storedReports

StoredReport[] internal _storedReports;

__GAP

gap for upgrade safety

uint256[45] private __GAP;

Functions

__StatementInbox_init

*Initializes the contract:

• Sets up msg.sender as the owner of the contract.
• Sets up agentManager, origin, and destination.*

function __StatementInbox_init(address agentManager_, address origin_, address destination_)
    internal
    onlyInitializing;

submitStateReportWithSnapshot

Accepts a Guard's state report signature, a Snapshot containing the reported State, as well as Notary signature for the Snapshot.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithSnapshot() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State Report signer is not an active Guard.
• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Notary.
• State index is out of range.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithSnapshot(
    uint8 stateIndex,
    bytes memory srSignature,
    bytes memory snapPayload,
    bytes memory snapSignature
) external returns (bool wasAccepted);

Parameters

Returns

submitStateReportWithAttestation

Accepts a Guard's state report signature, a Snapshot containing the reported State, as well as Notary signature for the Attestation created from this Snapshot.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithAttestation() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State Report signer is not an active Guard.
• Snapshot payload is not properly formatted.
• State index is out of range.
• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from the Snapshot.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithAttestation(
    uint8 stateIndex,
    bytes memory srSignature,
    bytes memory snapPayload,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool wasAccepted);

Parameters

Returns

submitStateReportWithSnapshotProof

Accepts a Guard's state report signature, a proof of inclusion of the reported State in an Attestation, as well as Notary signature for the Attestation.

StateReport is a Guard statement saying "Reported state is invalid".

• This results in an opened Dispute between the Guard and the Notary.
• Note: Guard could (but doesn't have to) form a StateReport and use other values from verifyStateWithSnapshotProof() successful call that led to Notary being slashed in remote Origin.

Will revert if any of these is true:

• State payload is not properly formatted.
• State Report signer is not an active Guard.
• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot Tree Height.
• State index is out of range.
• The Guard or the Notary are already in a Dispute

function submitStateReportWithSnapshotProof(
    uint8 stateIndex,
    bytes memory statePayload,
    bytes memory srSignature,
    bytes32[] memory snapProof,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool wasAccepted);

Parameters

Returns

verifyReceipt

Verifies a message receipt signed by the Notary.

• Does nothing, if the receipt is valid (matches the saved receipt data for the referenced message).
• Slashes the Notary, if the receipt is invalid.

Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt signer is not an active Notary.
• Receipt's destination chain does not refer to this chain.

function verifyReceipt(bytes memory rcptPayload, bytes memory rcptSignature) external returns (bool isValidReceipt);

Parameters

Returns

verifyReceiptReport

Verifies a Guard's receipt report signature.

• Does nothing, if the report is valid (if the reported receipt is invalid).
• Slashes the Guard, if the report is invalid (if the reported receipt is valid).

Will revert if any of these is true:

• Receipt payload is not properly formatted.
• Receipt Report signer is not an active Guard.
• Receipt does not refer to this chain.

function verifyReceiptReport(bytes memory rcptPayload, bytes memory rrSignature)
    external
    returns (bool isValidReport);

Parameters

Returns

verifyStateWithAttestation

Verifies a state from the snapshot, that was used for the Notary-signed attestation.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Notary, if the state is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from the Snapshot.
• Snapshot payload is not properly formatted.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithAttestation(
    uint8 stateIndex,
    bytes memory snapPayload,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool isValidState);

Parameters

Returns

verifyStateWithSnapshotProof

Verifies a state from the snapshot, that was used for the Notary-signed attestation.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Notary, if the state is invalid.

Will revert if any of these is true:

• Attestation payload is not properly formatted.
• Attestation signer is not an active Notary.
• Attestation's snapshot root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot Tree Height.
• State payload is not properly formatted.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithSnapshotProof(
    uint8 stateIndex,
    bytes memory statePayload,
    bytes32[] memory snapProof,
    bytes memory attPayload,
    bytes memory attSignature
) external returns (bool isValidState);

Parameters

Returns

verifyStateWithSnapshot

Verifies a state from the snapshot (a list of states) signed by a Guard or a Notary.

• Does nothing, if the state is valid (matches the historical state of this contract).
• Slashes the Agent, if the state is invalid.

Will revert if any of these is true:

• Snapshot payload is not properly formatted.
• Snapshot signer is not an active Agent.
• State index is out of range.
• State does not refer to this chain.

function verifyStateWithSnapshot(uint8 stateIndex, bytes memory snapPayload, bytes memory snapSignature)
    external
    returns (bool isValidState);

Parameters

Returns

verifyStateReport

Verifies a Guard's state report signature.

• Does nothing, if the report is valid (if the reported state is invalid).
• Slashes the Guard, if the report is invalid (if the reported state is valid).

Will revert if any of these is true:

• State payload is not properly formatted.
• State Report signer is not an active Guard.
• Reported State does not refer to this chain.

function verifyStateReport(bytes memory statePayload, bytes memory srSignature) external returns (bool isValidReport);

Parameters

Returns

getReportsAmount

Returns the amount of Guard Reports stored in StatementInbox.

Only reports that led to opening a Dispute are stored.

function getReportsAmount() external view returns (uint256);

getGuardReport

Returns the Guard report with the given index stored in StatementInbox.

Only reports that led to opening a Dispute are stored.

Will revert if report with given index doesn't exist.

function getGuardReport(uint256 index)
    external
    view
    returns (bytes memory statementPayload, bytes memory reportSignature);

Parameters

Returns

getStoredSignature

Returns the signature with the given index stored in StatementInbox.

Will revert if signature with given index doesn't exist.

function getStoredSignature(uint256 index) external view returns (bytes memory);

Parameters

Returns

_saveReport

Saves the statement reported by Guard as invalid and the Guard Report signature.

function _saveReport(bytes memory statementPayload, bytes memory reportSignature) internal;

_saveSignature

Saves the signature and returns its index.

function _saveSignature(bytes memory signature) internal returns (uint256 sigIndex);

_recoverAgent

Recovers a signer from a hashed message, and a EIP-191 signature for it. Will revert, if the signer is not a known agent.

Agent flag could be any of these: Active/Unstaking/Resting/Fraudulent/Slashed Further checks need to be performed in a caller function.

function _recoverAgent(bytes32 hashedStatement, bytes memory signature)
    internal
    view
    returns (AgentStatus memory status, address agent);

Parameters

Returns

_verifyNotaryDomain

Verifies that Notary signature is active on local domain.

function _verifyNotaryDomain(uint32 notaryDomain) internal view;

_verifyAttestation

*Internal function to verify the signed attestation payload. Reverts if any of these is true:

• Attestation signer is not a known Notary.*

function _verifyAttestation(Attestation att, bytes memory attSignature)
    internal
    view
    returns (AgentStatus memory status, address notary);

Parameters

Returns

_verifyAttestationReport

*Internal function to verify the signed attestation report payload. Reverts if any of these is true:

• Report signer is not a known Guard.*

function _verifyAttestationReport(Attestation att, bytes memory arSignature)
    internal
    view
    returns (AgentStatus memory status, address guard);

Parameters

Returns

_verifyReceipt

*Internal function to verify the signed receipt payload. Reverts if any of these is true:

• Receipt signer is not a known Notary.*

function _verifyReceipt(Receipt rcpt, bytes memory rcptSignature)
    internal
    view
    returns (AgentStatus memory status, address notary);

Parameters

Returns

_verifyReceiptReport

*Internal function to verify the signed receipt report payload. Reverts if any of these is true:

• Report signer is not a known Guard.*

function _verifyReceiptReport(Receipt rcpt, bytes memory rrSignature)
    internal
    view
    returns (AgentStatus memory status, address guard);

Parameters

Returns

_verifyStateReport

*Internal function to verify the signed snapshot report payload. Reverts if any of these is true:

• Report signer is not a known Guard.*

function _verifyStateReport(State state, bytes memory srSignature)
    internal
    view
    returns (AgentStatus memory status, address guard);

Parameters

Returns

_verifySnapshot

*Internal function to verify the signed snapshot payload. Reverts if any of these is true:

• Snapshot signer is not a known Agent.
• Snapshot signer is not a Notary (if verifyNotary is true).*

function _verifySnapshot(Snapshot snapshot, bytes memory snapSignature, bool verifyNotary)
    internal
    view
    returns (AgentStatus memory status, address agent);

Parameters

Returns

_verifySnapshotMerkle

*Internal function to verify that snapshot roots match. Reverts if any of these is true:

• Attestation root is not equal to Merkle Root derived from State and Snapshot Proof.
• Snapshot Proof's first element does not match the State metadata.
• Snapshot Proof length exceeds Snapshot tree Height.
• State index is out of range.*

function _verifySnapshotMerkle(Attestation att, uint8 stateIndex, State state, bytes32[] memory snapProof)
    internal
    pure;

Parameters

Structs

StoredReport

struct StoredReport {
    uint256 sigIndex;
    bytes statementPayload;
}