packages/contracts-core/contracts/interfaces/IStatementInbox.sol
// SPDX-License-Identifier: MIT
pragma solidity 0.8.17;
interface IStatementInbox {
// ══════════════════════════════════════════ SUBMIT AGENT STATEMENTS ══════════════════════════════════════════════
/**
* @notice 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
* @param stateIndex Index of the reported State in the Snapshot
* @param srSignature Guard signature for the report
* @param snapPayload Raw payload with Snapshot data
* @param snapSignature Notary signature for the Snapshot
* @return wasAccepted Whether the Report was accepted (resulting in Dispute between the agents)
*/
function submitStateReportWithSnapshot(
uint8 stateIndex,
bytes memory srSignature,
bytes memory snapPayload,
bytes memory snapSignature
) external returns (bool wasAccepted);
/**
* @notice 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
* @param stateIndex Index of the reported State in the Snapshot
* @param srSignature Guard signature for the report
* @param snapPayload Raw payload with Snapshot data
* @param attPayload Raw payload with Attestation data
* @param attSignature Notary signature for the Attestation
* @return wasAccepted Whether the Report was accepted (resulting in Dispute between the agents)
*/
function submitStateReportWithAttestation(
uint8 stateIndex,
bytes memory srSignature,
bytes memory snapPayload,
bytes memory attPayload,
bytes memory attSignature
) external returns (bool wasAccepted);
/**
* @notice 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
* @param stateIndex Index of the reported State in the Snapshot
* @param statePayload Raw payload with State data that Guard reports as invalid
* @param srSignature Guard signature for the report
* @param snapProof Proof of inclusion of reported State's Left Leaf into Snapshot Merkle Tree
* @param attPayload Raw payload with Attestation data
* @param attSignature Notary signature for the Attestation
* @return wasAccepted Whether the Report was accepted (resulting in Dispute between the agents)
*/
function submitStateReportWithSnapshotProof(
uint8 stateIndex,
bytes memory statePayload,
bytes memory srSignature,
bytes32[] memory snapProof,
bytes memory attPayload,
bytes memory attSignature
) external returns (bool wasAccepted);
// ══════════════════════════════════════════ VERIFY AGENT STATEMENTS ══════════════════════════════════════════════
/**
* @notice 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.
* @param rcptPayload Raw payload with Receipt data
* @param rcptSignature Notary signature for the receipt
* @return isValidReceipt Whether the provided receipt is valid.
* Notary is slashed, if return value is FALSE.
*/
function verifyReceipt(bytes memory rcptPayload, bytes memory rcptSignature)
external
returns (bool isValidReceipt);
/**
* @notice 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.
* @param rcptPayload Raw payload with Receipt data that Guard reports as invalid
* @param rrSignature Guard signature for the report
* @return isValidReport Whether the provided report is valid.
* Guard is slashed, if return value is FALSE.
*/
function verifyReceiptReport(bytes memory rcptPayload, bytes memory rrSignature)
external
returns (bool isValidReport);
/**
* @notice 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.
* @param stateIndex State index to check
* @param snapPayload Raw payload with snapshot data
* @param attPayload Raw payload with Attestation data
* @param attSignature Notary signature for the attestation
* @return isValidState Whether the provided state is valid.
* Notary is slashed, if return value is FALSE.
*/
function verifyStateWithAttestation(
uint8 stateIndex,
bytes memory snapPayload,
bytes memory attPayload,
bytes memory attSignature
) external returns (bool isValidState);
/**
* @notice 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.
* @param stateIndex Index of state in the snapshot
* @param statePayload Raw payload with State data to check
* @param snapProof Proof of inclusion of provided State's Left Leaf into Snapshot Merkle Tree
* @param attPayload Raw payload with Attestation data
* @param attSignature Notary signature for the attestation
* @return isValidState Whether the provided state is valid.
* Notary is slashed, if return value is FALSE.
*/
function verifyStateWithSnapshotProof(
uint8 stateIndex,
bytes memory statePayload,
bytes32[] memory snapProof,
bytes memory attPayload,
bytes memory attSignature
) external returns (bool isValidState);
/**
* @notice 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.
* @param stateIndex State index to check
* @param snapPayload Raw payload with snapshot data
* @param snapSignature Agent signature for the snapshot
* @return isValidState Whether the provided state is valid.
* Agent is slashed, if return value is FALSE.
*/
function verifyStateWithSnapshot(uint8 stateIndex, bytes memory snapPayload, bytes memory snapSignature)
external
returns (bool isValidState);
/**
* @notice 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.
* @param statePayload Raw payload with State data that Guard reports as invalid
* @param srSignature Guard signature for the report
* @return isValidReport Whether the provided report is valid.
* Guard is slashed, if return value is FALSE.
*/
function verifyStateReport(bytes memory statePayload, bytes memory srSignature)
external
returns (bool isValidReport);
// ═══════════════════════════════════════════════════ VIEWS ═══════════════════════════════════════════════════════
/**
* @notice 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);
/**
* @notice Returns the Guard report with the given index stored in StatementInbox.
* > Only reports that led to opening a Dispute are stored.
* @dev Will revert if report with given index doesn't exist.
* @param index Report index
* @return statementPayload Raw payload with statement that Guard reported as invalid
* @return reportSignature Guard signature for the report
*/
function getGuardReport(uint256 index)
external
view
returns (bytes memory statementPayload, bytes memory reportSignature);
/**
* @notice Returns the signature with the given index stored in StatementInbox.
* @dev Will revert if signature with given index doesn't exist.
* @param index Signature index
* @return Raw payload with signature
*/
function getStoredSignature(uint256 index) external view returns (bytes memory);
}