IConsensus

Inherits: IOutputsMerkleRootValidator

Each application has its own stream of inputs. See the IInputBox interface for calldata-based on-chain data availability.

When an input is fed to the application, it may yield several outputs.

Since genesis, a Merkle tree of all outputs ever produced is maintained both inside and outside the Cartesi Machine.

The claim that validators may submit to the consensus contract is the root of this Merkle tree after processing all base layer blocks until some height.

A validator should be able to save transaction fees by not submitting a claim if it was...

already submitted by the validator (see the ClaimSubmitted event) or;
already accepted by the consensus (see the ClaimAccepted event).

The acceptance criteria for claims may depend on the type of consensus, and is not specified by this interface. For example, a claim may be accepted if it was...

submitted by an authority or;
submitted by the majority of a quorum or;
submitted and not proven wrong after some period of time or;
submitted and proven correct through an on-chain tournament.

Functions

submitClaim

Submit a claim to the consensus.

MUST fire a ClaimSubmitted event.

MAY fire a ClaimAccepted event, if the acceptance criteria is met.

function submitClaim(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
) external;

Parameters

Name	Type	Description
`appContract`	`address`	The application contract address
`lastProcessedBlockNumber`	`uint256`	The number of the last processed block
`outputsMerkleRoot`	`bytes32`	The outputs Merkle root

getEpochLength

Get the epoch length, in number of base layer blocks.

The epoch number of a block is defined as the integer division of the block number by the epoch length.

function getEpochLength() external view returns (uint256);

getNumberOfAcceptedClaims

Get the number of claims accepted by the consensus.

function getNumberOfAcceptedClaims() external view returns (uint256);

Events

ClaimSubmitted

MUST trigger when a claim is submitted.

event ClaimSubmitted(
    address indexed submitter,
    address indexed appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
);

Parameters

Name	Type	Description
`submitter`	`address`	The submitter address
`appContract`	`address`	The application contract address
`lastProcessedBlockNumber`	`uint256`	The number of the last processed block
`outputsMerkleRoot`	`bytes32`	The outputs Merkle root

ClaimAccepted

MUST trigger when a claim is accepted.

For each application and lastProcessedBlockNumber, there can be at most one accepted claim.

event ClaimAccepted(
    address indexed appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
);

Parameters

Name	Type	Description
`appContract`	`address`	The application contract address
`lastProcessedBlockNumber`	`uint256`	The number of the last processed block
`outputsMerkleRoot`	`bytes32`	The outputs Merkle root

Errors

NotEpochFinalBlock

The claim contains the number of a block that is not at the end of an epoch (its modulo epoch length is not epoch length - 1).

error NotEpochFinalBlock(uint256 lastProcessedBlockNumber, uint256 epochLength);

Parameters

Name	Type	Description
`lastProcessedBlockNumber`	`uint256`	The number of the last processed block
`epochLength`	`uint256`	The epoch length

NotPastBlock

The claim contains the number of a block in the future (it is greater or equal to the current block number).

error NotPastBlock(uint256 lastProcessedBlockNumber, uint256 currentBlockNumber);

Parameters

Name	Type	Description
`lastProcessedBlockNumber`	`uint256`	The number of the last processed block
`currentBlockNumber`	`uint256`	The number of the current block

NotFirstClaim

A claim for that application and epoch was already submitted by the validator.

error NotFirstClaim(address appContract, uint256 lastProcessedBlockNumber);

Parameters

Name	Type	Description
`appContract`	`address`	The application contract address
`lastProcessedBlockNumber`	`uint256`	The number of the last processed block

Keyboard shortcuts