Cartesi Rollups Contracts

The Cartesi Rollups Contracts are a set of Solidity smart contracts that provide Data Availability, Consensus and Settlement to Cartesi Rollups applications. They are completely permissionless, and can be deployed by anyone to any EVM-compatible chain. Nevertheless, the Cartesi Foundation, as a form of public good, kindly deploys them to Ethereum, Arbitrum, Optimism, Base, and their respective testnets.

Data Availability of user transactions and Consensus over their order is provided by the InputBox contract, while Settlement is provided by the Application contract in conjunction with a settlement module. Currently, we have implemented an authority-based module (Authority) and a quorum-based module (Quorum). In the near future, we plan to support our very own fraud proof system, Dave.

The Cartesi Rollups Contracts are an integral part of the Cartesi Rollups SDK, and are used by the Cartesi Rollups Node, the Cartesi Rollups Explorer, and, of course, by Cartesi Rollups applications. Through simple Solidity interfaces, one can easily send and list user transactions, deposit assets, submit claims, execute asset withdrawal orders, and more.

Features

• Supports deposits and withdrawals of several types of assets:
  • ETH: the native token of the chain
  • ERC-20: regular, fungible tokens
  • ERC-721: non-fungible tokens (NFTs)
  • ERC-1155: Multi-tokens, both single and batch transfers
• Supports the validation of outputs and output hashes
• Supports the execution of CALL and DELEGATECALL vouchers
• Supports Quorum and Authority-based settlement models
• Includes factory contracts for easy deployment

Getting started

First, please ensure the following dependencies are installed:

• corepack
• foundry 1.0.0

Then, you may clone the repository...

git clone https://github.com/cartesi/rollups-contracts.git

... and install the Node.js and Solidity packages.

pnpm install
forge soldeer install

Having done that, you can run a local devnet with Cannon. It will be listening to 127.0.0.1:8545.

pnpm start

You can interact with the contracts by pressing i on the terminal running Cannon, or by running cast commands on another terminal. The following command, for example, calls the getDeploymentBlockNumber function of the InputBox contract deployed to the local devnet.

cast call $(jq -r .address deployments/InputBox.json) 'getDeploymentBlockNumber()(uint256)'

Documentation

A more in-depth documentation on the contracts can be found here.

Use cases

The Cartesi Rollups Contracts are used by the Cartesi Rollups SDK. They offer an extensible framework for input relays and output execution. Here are some examples of use cases:

• Trustless relaying of on-chain information
• Trustless locking of on-chain assets
• Withdrawal of on-chain assets
• Minting of on-chain assets
• Scheduling of on-chain actions
• Liquidity for on-chain assets

Related projects

The contracts are used by several other projects in the Cartesi ecossystem:

• Cartesi CLI
• Cartesi Rollups Node
• Cartesi Rollups Explorer

Authors

• Guilherme Dantas (guidanoli)
• Pedro Argento (pedroargento)
• Zehui Zheng (ZzzzHui)

License

The project is licensed under Apache-2.0.

Contents

• IOwnable

IOwnable

Git Source

The interface of OpenZeppelin's Ownable contract.

Functions

owner

function owner() external view returns (address);

renounceOwnership

function renounceOwnership() external;

transferOwnership

function transferOwnership(address newOwner) external;

Contents

• CanonicalMachine
• DataAvailability
• InputEncoding
• Inputs
• OutputValidityProof
• Outputs

CanonicalMachine

Git Source

Defines several constants related to the reference implementation of the RISC-V machine that runs Linux, also known as the "Cartesi Machine".

State Variables

INPUT_MAX_SIZE

Maximum input size (2 megabytes).

uint256 constant INPUT_MAX_SIZE = 1 << 21;

LOG2_MAX_OUTPUTS

Log2 of maximum number of outputs.

uint256 constant LOG2_MAX_OUTPUTS = 63;

DataAvailability

Git Source

Defines the signatures of data availability solutions.

Functions

InputBox

The application receives inputs only from a contract that implements the IInputBox interface.

function InputBox(IInputBox inputBox) external;

Parameters

InputBoxAndEspresso

The application receives inputs from a contract that implements the IInputBox interface, and from Espresso, starting from a given block height, and for a given namespace ID.

function InputBoxAndEspresso(IInputBox inputBox, uint256 fromBlock, uint32 namespaceId)
    external;

Parameters

InputEncoding

Git Source

Defines the encoding of inputs added by core trustless and permissionless contracts, such as portals.

Functions

encodeEtherDeposit

Encode an Ether deposit.

function encodeEtherDeposit(address sender, uint256 value, bytes calldata execLayerData)
    internal
    pure
    returns (bytes memory);

Parameters

Returns

encodeERC20Deposit

Encode an ERC-20 token deposit.

function encodeERC20Deposit(
    IERC20 token,
    address sender,
    uint256 value,
    bytes calldata execLayerData
) internal pure returns (bytes memory);

Parameters

Returns

encodeERC721Deposit

Encode an ERC-721 token deposit.

baseLayerData should be forwarded to token.

function encodeERC721Deposit(
    IERC721 token,
    address sender,
    uint256 tokenId,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) internal pure returns (bytes memory);

Parameters

Returns

encodeSingleERC1155Deposit

Encode an ERC-1155 single token deposit.

baseLayerData should be forwarded to token.

function encodeSingleERC1155Deposit(
    IERC1155 token,
    address sender,
    uint256 tokenId,
    uint256 value,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) internal pure returns (bytes memory);

Parameters

Returns

encodeBatchERC1155Deposit

Encode an ERC-1155 batch token deposit.

baseLayerData should be forwarded to token.

function encodeBatchERC1155Deposit(
    IERC1155 token,
    address sender,
    uint256[] calldata tokenIds,
    uint256[] calldata values,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) internal pure returns (bytes memory);

Parameters

Returns

Inputs

Git Source

Defines the signatures of inputs.

Functions

EvmAdvance

An advance request from an EVM-compatible blockchain to a Cartesi Machine.

See EIP-4399 for safe usage of prevRandao.

function EvmAdvance(
    uint256 chainId,
    address appContract,
    address msgSender,
    uint256 blockNumber,
    uint256 blockTimestamp,
    uint256 prevRandao,
    uint256 index,
    bytes calldata payload
) external;

Parameters

OutputValidityProof

Git Source

Proof of inclusion of an output in the output Merkle tree.

From the index and siblings, one can calculate the root of the Merkle tree.

The siblings array should have size equal to the log2 of the maximum number of outputs.

See the CanonicalMachine library for constants.

struct OutputValidityProof {
    uint64 outputIndex;
    bytes32[] outputHashesSiblings;
}

Properties

Outputs

Git Source

Defines the signatures of outputs that can be generated by the off-chain machine and verified by the on-chain contracts.

Functions

Notice

A piece of verifiable information.

function Notice(bytes calldata payload) external;

Parameters

Voucher

A single-use permission to execute a specific message call from the context of the application contract.

function Voucher(address destination, uint256 value, bytes calldata payload) external;

Parameters

DelegateCallVoucher

A single-use permission to execute a specific delegate call from the context of the application contract.

function DelegateCallVoucher(address destination, bytes calldata payload) external;

Parameters

Contents

• authority
• quorum
• AbstractConsensus
• IConsensus
• IOutputsMerkleRootValidator

Contents

• Authority
• AuthorityFactory
• IAuthority
• IAuthorityFactory

Authority

Git Source

Inherits: IAuthority, AbstractConsensus, Ownable

A consensus contract controlled by a single address, the owner.

This contract inherits from OpenZeppelin's Ownable contract. For more information on Ownable, please consult OpenZeppelin's official documentation.

Functions

constructor

Reverts if the epoch length is zero.

constructor(address initialOwner, uint256 epochLength)
    AbstractConsensus(epochLength)
    Ownable(initialOwner);

Parameters

submitClaim

Submit a claim to the consensus.

MUST fire a ClaimSubmitted event.

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

Parameters

owner

function owner() public view override(IOwnable, Ownable) returns (address);

renounceOwnership

function renounceOwnership() public override(IOwnable, Ownable);

transferOwnership

function transferOwnership(address newOwner) public override(IOwnable, Ownable);

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    override(IERC165, AbstractConsensus)
    returns (bool);

AuthorityFactory

Git Source

Inherits: IAuthorityFactory

Allows anyone to reliably deploy a new IAuthority contract.

Functions

newAuthority

function newAuthority(address authorityOwner, uint256 epochLength)
    external
    override
    returns (IAuthority);

newAuthority

function newAuthority(address authorityOwner, uint256 epochLength, bytes32 salt)
    external
    override
    returns (IAuthority);

calculateAuthorityAddress

function calculateAuthorityAddress(
    address authorityOwner,
    uint256 epochLength,
    bytes32 salt
) external view override returns (address);

IAuthority

Git Source

Inherits: IConsensus, IOwnable

A consensus contract controlled by a single address, the owner.

IAuthorityFactory

Git Source

Functions

newAuthority

Deploy a new authority.

On success, MUST emit an AuthorityCreated event.

Reverts if the authority owner address is zero.

Reverts if the epoch length is zero.

function newAuthority(address authorityOwner, uint256 epochLength)
    external
    returns (IAuthority);

Parameters

Returns

newAuthority

Deploy a new authority deterministically.

On success, MUST emit an AuthorityCreated event.

Reverts if the authority owner address is zero.

Reverts if the epoch length is zero.

function newAuthority(address authorityOwner, uint256 epochLength, bytes32 salt)
    external
    returns (IAuthority);

Parameters

Returns

calculateAuthorityAddress

Calculate the address of an authority to be deployed deterministically.

Beware that only the newAuthority function with the salt parameter is able to deterministically deploy an authority.

function calculateAuthorityAddress(
    address authorityOwner,
    uint256 epochLength,
    bytes32 salt
) external view returns (address);

Parameters

Returns

Events

AuthorityCreated

A new authority was deployed.

MUST be triggered on a successful call to newAuthority.

event AuthorityCreated(IAuthority authority);

Parameters

Contents

• IQuorum
• IQuorumFactory
• Quorum
• QuorumFactory

IQuorum

Git Source

Inherits: IConsensus

A consensus model controlled by a small, immutable set of n validators.

You can know the value of n by calling the numOfValidators function.

Upon construction, each validator is assigned a unique number between 1 and n. These numbers are used internally instead of addresses for gas optimization reasons.

You can list the validators in the quorum by calling the validatorById function for each ID from 1 to n.

Functions

numOfValidators

Get the number of validators.

function numOfValidators() external view returns (uint256);

validatorId

Get the ID of a validator.

Validators have IDs greater than zero.

Non-validators are assigned to ID zero.

function validatorId(address validator) external view returns (uint256);

Parameters

validatorById

Get the address of a validator by its ID.

Validator IDs range from 1 to N, the total number of validators.

Invalid IDs map to address zero.

function validatorById(uint256 id) external view returns (address);

Parameters

numOfValidatorsInFavorOf

Get the number of validators in favor of a claim.

function numOfValidatorsInFavorOf(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
) external view returns (uint256);

Parameters

Returns

isValidatorInFavorOf

Check whether a validator is in favor of a claim.

Assumes the provided ID is valid.

function isValidatorInFavorOf(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot,
    uint256 id
) external view returns (bool);

Parameters

Returns

IQuorumFactory

Git Source

Functions

newQuorum

Deploy a new quorum.

On success, MUST emit a QuorumCreated event.

Duplicates in the validators array are ignored.

Reverts if the epoch length is zero.

function newQuorum(address[] calldata validators, uint256 epochLength)
    external
    returns (IQuorum);

Parameters

Returns

newQuorum

Deploy a new quorum deterministically.

On success, MUST emit a QuorumCreated event.

Duplicates in the validators array are ignored.

Reverts if the epoch length is zero.

function newQuorum(address[] calldata validators, uint256 epochLength, bytes32 salt)
    external
    returns (IQuorum);

Parameters

Returns

calculateQuorumAddress

Calculate the address of a quorum to be deployed deterministically.

Beware that only the newQuorum function with the salt parameter is able to deterministically deploy a quorum.

function calculateQuorumAddress(
    address[] calldata validators,
    uint256 epochLength,
    bytes32 salt
) external view returns (address);

Parameters

Returns

Events

QuorumCreated

A new quorum was deployed.

MUST be triggered on a successful call to newQuorum.

event QuorumCreated(IQuorum quorum);

Parameters

Quorum

Git Source

Inherits: IQuorum, AbstractConsensus

State Variables

_numOfValidators

The total number of validators.

See the numOfValidators function.

uint256 private immutable _numOfValidators;

_validatorId

Validator IDs indexed by address.

See the validatorId function.

Non-validators are assigned to ID zero.

Validators have IDs greater than zero.

mapping(address => uint256) private _validatorId;

_validatorById

Validator addresses indexed by ID.

See the validatorById function.

Invalid IDs map to address zero.

mapping(uint256 => address) private _validatorById;

_votes

Votes indexed by application contract address, last processed block number and outputs Merkle root.

See the numOfValidatorsInFavorOf and isValidatorInFavorOf functions.

mapping(address => mapping(uint256 => mapping(bytes32 => Votes))) private _votes;

Functions

constructor

Duplicates in the validators array are ignored.

Reverts if the epoch length is zero.

constructor(address[] memory validators, uint256 epochLength)
    AbstractConsensus(epochLength);

Parameters

submitClaim

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

numOfValidators

function numOfValidators() external view override returns (uint256);

validatorId

function validatorId(address validator) external view override returns (uint256);

validatorById

function validatorById(uint256 id) external view override returns (address);

numOfValidatorsInFavorOf

function numOfValidatorsInFavorOf(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
) external view override returns (uint256);

isValidatorInFavorOf

function isValidatorInFavorOf(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot,
    uint256 id
) external view override returns (bool);

_getVotes

Get a Votes structure from storage from a given claim.

function _getVotes(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
) internal view returns (Votes storage);

Parameters

Returns

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    override(IERC165, AbstractConsensus)
    returns (bool);

Structs

Votes

Votes in favor of a particular claim.

inFavorById is a bitmap indexed by validator IDs.

struct Votes {
    uint256 inFavorCount;
    BitMaps.BitMap inFavorById;
}

Properties

QuorumFactory

Git Source

Inherits: IQuorumFactory

Allows anyone to reliably deploy a new IQuorum contract.

Functions

newQuorum

function newQuorum(address[] calldata validators, uint256 epochLength)
    external
    override
    returns (IQuorum);

newQuorum

function newQuorum(address[] calldata validators, uint256 epochLength, bytes32 salt)
    external
    override
    returns (IQuorum);

calculateQuorumAddress

function calculateQuorumAddress(
    address[] calldata validators,
    uint256 epochLength,
    bytes32 salt
) external view override returns (address);

AbstractConsensus

Git Source

Inherits: IConsensus, ERC165

Abstract implementation of IConsensus

State Variables

_epochLength

The epoch length

uint256 private immutable _epochLength;

_validOutputsMerkleRoots

Indexes accepted claims by application contract address.

mapping(address => mapping(bytes32 => bool)) private _validOutputsMerkleRoots;

Functions

constructor

Reverts if the epoch length is zero.

constructor(uint256 epochLength);

Parameters

isOutputsMerkleRootValid

Check whether an outputs Merkle root is valid.

function isOutputsMerkleRootValid(address appContract, bytes32 outputsMerkleRoot)
    public
    view
    override
    returns (bool);

Parameters

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() public view override returns (uint256);

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(IERC165, ERC165)
    returns (bool);

_acceptClaim

Accept a claim.

Emits a ClaimAccepted event.

function _acceptClaim(
    address appContract,
    uint256 lastProcessedBlockNumber,
    bytes32 outputsMerkleRoot
) internal;

Parameters

IConsensus

Git Source

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

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);

Events

ClaimSubmitted

MUST trigger when a claim is submitted.

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

Parameters

ClaimAccepted

MUST trigger when a claim is accepted.

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

Parameters

IOutputsMerkleRootValidator

Git Source

Inherits: IERC165

Provides valid outputs Merkle roots for validation.

ERC-165 can be used to determine whether this contract also supports any other interface (e.g. for submitting claims).

Functions

isOutputsMerkleRootValid

Check whether an outputs Merkle root is valid.

function isOutputsMerkleRootValid(address appContract, bytes32 outputsMerkleRoot)
    external
    view
    returns (bool);

Parameters

Contents

• Application
• ApplicationFactory
• IApplication
• IApplicationFactory
• ISelfHostedApplicationFactory
• SelfHostedApplicationFactory

Application

Git Source

Inherits: IApplication, Ownable, ERC721Holder, ERC1155Holder, ReentrancyGuard

State Variables

_deploymentBlockNumber

Deployment block number

uint256 immutable _deploymentBlockNumber = block.number;

_templateHash

The initial machine state hash.

See the getTemplateHash function.

bytes32 internal immutable _templateHash;

_executed

Keeps track of which outputs have been executed.

See the wasOutputExecuted function.

BitMaps.BitMap internal _executed;

_outputsMerkleRootValidator

The current outputs Merkle root validator contract.

See the getOutputsMerkleRootValidator and migrateToOutputsMerkleRootValidator functions.

IOutputsMerkleRootValidator internal _outputsMerkleRootValidator;

_dataAvailability

The data availability solution.

See the getDataAvailability function.

bytes internal _dataAvailability;

Functions

constructor

Creates an Application contract.

Reverts if the initial application owner address is zero.

constructor(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address initialOwner,
    bytes32 templateHash,
    bytes memory dataAvailability
) Ownable(initialOwner);

Parameters

receive

Accept Ether transfers.

If you wish to transfer Ether to an application while informing the backend of it, then please do so through the Ether portal contract.

receive() external payable;

executeOutput

Execute an output.

On a successful execution, emits a OutputExecuted event.

function executeOutput(bytes calldata output, OutputValidityProof calldata proof)
    external
    override
    nonReentrant;

Parameters

migrateToOutputsMerkleRootValidator

Migrate the application to a new outputs Merkle root validator.

Can only be called by the application owner.

function migrateToOutputsMerkleRootValidator(
    IOutputsMerkleRootValidator newOutputsMerkleRootValidator
) external override onlyOwner;

Parameters

wasOutputExecuted

Check whether an output has been executed.

function wasOutputExecuted(uint256 outputIndex) external view override returns (bool);

Parameters

Returns

validateOutput

Validate an output.

May raise any of the errors raised by validateOutputHash.

function validateOutput(bytes calldata output, OutputValidityProof calldata proof)
    public
    view
    override;

Parameters

validateOutputHash

Validate an output hash.

May raise InvalidOutputHashesSiblingsArrayLength or InvalidOutputsMerkleRoot.

function validateOutputHash(bytes32 outputHash, OutputValidityProof calldata proof)
    public
    view
    override;

Parameters

getTemplateHash

Get the application's template hash.

function getTemplateHash() external view override returns (bytes32);

Returns

getOutputsMerkleRootValidator

Get the current outputs Merkle root validator.

function getOutputsMerkleRootValidator()
    external
    view
    override
    returns (IOutputsMerkleRootValidator);

Returns

getDataAvailability

Get the data availability solution used by application.

function getDataAvailability() external view override returns (bytes memory);

Returns

getDeploymentBlockNumber

Get number of block in which contract was deployed

function getDeploymentBlockNumber() external view override returns (uint256);

owner

function owner() public view override(IOwnable, Ownable) returns (address);

renounceOwnership

function renounceOwnership() public override(IOwnable, Ownable);

transferOwnership

function transferOwnership(address newOwner) public override(IOwnable, Ownable);

_isOutputsMerkleRootValid

Check if an outputs Merkle root is valid, according to the current outputs Merkle root validator.

function _isOutputsMerkleRootValid(bytes32 outputsMerkleRoot)
    internal
    view
    returns (bool);

Parameters

_executeVoucher

Executes a voucher

function _executeVoucher(bytes calldata arguments) internal;

Parameters

_executeDelegateCallVoucher

Executes a delegatecall voucher

function _executeDelegateCallVoucher(bytes calldata arguments) internal;

Parameters

ApplicationFactory

Git Source

Inherits: IApplicationFactory

Allows anyone to reliably deploy a new IApplication contract.

Functions

newApplication

function newApplication(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability
) external override returns (IApplication);

newApplication

function newApplication(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external override returns (IApplication);

calculateApplicationAddress

function calculateApplicationAddress(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external view override returns (address);

IApplication

Git Source

Inherits: IOwnable

The base layer incarnation of an application running on the execution layer.

The state of the application advances through inputs sent to an IInputBox contract.

These inputs can be sent either directly, or indirectly through portals.

Reader nodes can retrieve inputs sent to the IInputBox contract through events, and feed them into the machine.

Validator nodes can also submit claims to the IOutputsMerkleRootValidator contract (see the getOutputsMerkleRootValidator function).

Once accepted, claims can be used to validate outputs generated by the machine.

Some outputs are executable, which means they can have on-chain side effects.

Every application is subscribed to some outputs Merkle root validator, and may be governed by some owner. The outputs Merkle root validator has the power to accept claims, which, in turn, are used to validate outputs. Meanwhile, the owner can replace the outputs Merkle root validator at any time. Therefore, the users of an application must trust both the outputs Merkle root validator and the application owner.

There are several ownership models to choose from:

• no owner (address zero)
• individual signer (externally-owned account)
• multiple signers (multi-sig)
• DAO (decentralized autonomous organization)
• self-owned application (off-chain governance logic)

Functions

migrateToOutputsMerkleRootValidator

Migrate the application to a new outputs Merkle root validator.

Can only be called by the application owner.

function migrateToOutputsMerkleRootValidator(
    IOutputsMerkleRootValidator newOutputsMerkleRootValidator
) external;

Parameters

executeOutput

Execute an output.

On a successful execution, emits a OutputExecuted event.

May raise any of the errors raised by validateOutput, as well as OutputNotExecutable and OutputNotReexecutable.

function executeOutput(bytes calldata output, OutputValidityProof calldata proof)
    external;

Parameters

wasOutputExecuted

Check whether an output has been executed.

function wasOutputExecuted(uint256 outputIndex) external view returns (bool);

Parameters

Returns

validateOutput

Validate an output.

May raise any of the errors raised by validateOutputHash.

function validateOutput(bytes calldata output, OutputValidityProof calldata proof)
    external
    view;

Parameters

validateOutputHash

Validate an output hash.

May raise InvalidOutputHashesSiblingsArrayLength or InvalidOutputsMerkleRoot.

function validateOutputHash(bytes32 outputHash, OutputValidityProof calldata proof)
    external
    view;

Parameters

getTemplateHash

Get the application's template hash.

function getTemplateHash() external view returns (bytes32);

Returns

getOutputsMerkleRootValidator

Get the current outputs Merkle root validator.

function getOutputsMerkleRootValidator()
    external
    view
    returns (IOutputsMerkleRootValidator);

Returns

getDataAvailability

Get the data availability solution used by application.

function getDataAvailability() external view returns (bytes memory);

Returns

getDeploymentBlockNumber

Get number of block in which contract was deployed

function getDeploymentBlockNumber() external view returns (uint256);

Events

OutputsMerkleRootValidatorChanged

MUST trigger when a new outputs Merkle root validator is chosen.

event OutputsMerkleRootValidatorChanged(
    IOutputsMerkleRootValidator newOutputsMerkleRootValidator
);

Parameters

OutputExecuted

MUST trigger when an output is executed.

event OutputExecuted(uint64 outputIndex, bytes output);

Parameters

Errors

OutputNotExecutable

Could not execute an output, because the application contract doesn't know how to.

error OutputNotExecutable(bytes output);

Parameters

OutputNotReexecutable

Could not execute an output, because it was already executed.

error OutputNotReexecutable(bytes output);

Parameters

InsufficientFunds

Could not execute an output, because the application contract doesn't have enough Ether.

error InsufficientFunds(uint256 value, uint256 balance);

Parameters

InvalidOutputHashesSiblingsArrayLength

Raised when the output hashes siblings array has an invalid size.

Please consult CanonicalMachine for the maximum number of outputs.

error InvalidOutputHashesSiblingsArrayLength();

InvalidOutputsMerkleRoot

Raised when the computed outputs Merkle root is invalid, according to the current outputs Merkle root validator.

error InvalidOutputsMerkleRoot(bytes32 outputsMerkleRoot);

IApplicationFactory

Git Source

Functions

newApplication

Deploy a new application.

On success, MUST emit an ApplicationCreated event.

Reverts if the application owner address is zero.

function newApplication(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability
) external returns (IApplication);

Parameters

Returns

newApplication

Deploy a new application deterministically.

On success, MUST emit an ApplicationCreated event.

Reverts if the application owner address is zero.

function newApplication(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external returns (IApplication);

Parameters

Returns

calculateApplicationAddress

Calculate the address of an application contract to be deployed deterministically.

Beware that only the newApplication function with the salt parameter is able to deterministically deploy an application.

function calculateApplicationAddress(
    IOutputsMerkleRootValidator outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external view returns (address);

Parameters

Returns

Events

ApplicationCreated

A new application was deployed.

MUST be triggered on a successful call to newApplication.

event ApplicationCreated(
    IOutputsMerkleRootValidator indexed outputsMerkleRootValidator,
    address appOwner,
    bytes32 templateHash,
    bytes dataAvailability,
    IApplication appContract
);

Parameters

ISelfHostedApplicationFactory

Git Source

Functions

getAuthorityFactory

Get the factory used to deploy IAuthority contracts

function getAuthorityFactory() external view returns (IAuthorityFactory);

Returns

getApplicationFactory

Get the factory used to deploy IApplication contracts

function getApplicationFactory() external view returns (IApplicationFactory);

Returns

deployContracts

Deploy new application and authority contracts deterministically.

Reverts if the authority owner address is zero.

Reverts if the application owner address is zero.

Reverts if the epoch length is zero.

function deployContracts(
    address authorityOwner,
    uint256 epochLength,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external returns (IApplication, IAuthority);

Parameters

Returns

calculateAddresses

Calculate the addresses of the application and authority contracts to be deployed deterministically.

function calculateAddresses(
    address authorityOwner,
    uint256 epochLength,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external view returns (address, address);

Parameters

Returns

SelfHostedApplicationFactory

Git Source

Inherits: ISelfHostedApplicationFactory

Allows anyone to reliably deploy a new IAuthority contract, along with an IApplication contract already linked to it.

State Variables

_authorityFactory

IAuthorityFactory immutable _authorityFactory;

_applicationFactory

IApplicationFactory immutable _applicationFactory;

Functions

constructor

constructor(IAuthorityFactory authorityFactory, IApplicationFactory applicationFactory);

Parameters

getAuthorityFactory

function getAuthorityFactory() external view override returns (IAuthorityFactory);

getApplicationFactory

function getApplicationFactory() external view override returns (IApplicationFactory);

deployContracts

function deployContracts(
    address authorityOwner,
    uint256 epochLength,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external returns (IApplication application, IAuthority authority);

calculateAddresses

function calculateAddresses(
    address authorityOwner,
    uint256 epochLength,
    address appOwner,
    bytes32 templateHash,
    bytes calldata dataAvailability,
    bytes32 salt
) external view returns (address application, address authority);

Contents

• SafeERC20Transfer

SafeERC20Transfer

Git Source

Functions

safeTransfer

function safeTransfer(IERC20 token, address to, uint256 value) external;

Contents

• IInputBox
• InputBox

IInputBox

Git Source

Provides data availability of inputs for applications.

Each application has its own append-only list of inputs.

Off-chain, inputs can be retrieved via events.

On-chain, only the input hashes are stored.

See LibInput for more details on how such hashes are computed.

Functions

addInput

Send an input to an application.

MUST fire an InputAdded event.

function addInput(address appContract, bytes calldata payload)
    external
    returns (bytes32);

Parameters

Returns

getNumberOfInputs

Get the number of inputs sent to an application.

function getNumberOfInputs(address appContract) external view returns (uint256);

Parameters

getInputHash

Get the hash of an input in an application's input box.

The provided index must be valid.

function getInputHash(address appContract, uint256 index)
    external
    view
    returns (bytes32);

Parameters

getDeploymentBlockNumber

Get number of block in which contract was deployed

function getDeploymentBlockNumber() external view returns (uint256);

Events

InputAdded

MUST trigger when an input is added.

event InputAdded(address indexed appContract, uint256 indexed index, bytes input);

Parameters

Errors

InputTooLarge

Input is too large.

error InputTooLarge(address appContract, uint256 inputLength, uint256 maxInputLength);

Parameters

InputBox

Git Source

Inherits: IInputBox

State Variables

_deploymentBlockNumber

Deployment block number

uint256 immutable _deploymentBlockNumber = block.number;

_inputBoxes

Mapping of application contract addresses to arrays of input hashes.

mapping(address => bytes32[]) private _inputBoxes;

Functions

addInput

Send an input to an application.

MUST fire an InputAdded event.

function addInput(address appContract, bytes calldata payload)
    external
    override
    returns (bytes32);

Parameters

Returns

getNumberOfInputs

Get the number of inputs sent to an application.

function getNumberOfInputs(address appContract)
    external
    view
    override
    returns (uint256);

Parameters

getInputHash

Get the hash of an input in an application's input box.

The provided index must be valid.

function getInputHash(address appContract, uint256 index)
    external
    view
    override
    returns (bytes32);

Parameters

getDeploymentBlockNumber

Get number of block in which contract was deployed

function getDeploymentBlockNumber() external view override returns (uint256);

Contents

• LibAddress
• LibError
• LibMerkle32
• LibOutputValidityProof

LibAddress

Git Source

Functions

safeCall

Perform a low level call and raise error if failed

function safeCall(address destination, uint256 value, bytes memory payload)
    internal
    returns (bool, uint256);

Parameters

Returns

safeDelegateCall

Perform a delegate call and raise error if failed

function safeDelegateCall(address destination, bytes memory payload) internal;

Parameters

LibError

Git Source

Functions

raise

Raise error data

function raise(bytes memory errordata) internal pure;

Parameters

LibMerkle32

Git Source

This library is meant for creating and verifying Merkle proofs.

Each Merkle tree is assumed to have 2^height leaves.

Nodes are concatenated pairwise and hashed with keccak256.

Siblings are in bottom-up order, from leaf to root.

Functions

merkleRoot

Compute the root of a Merkle tree from its leaves.

Raises an error if more than 2^height leaves are provided.

function merkleRoot(bytes32[] memory leaves, uint256 height)
    internal
    pure
    returns (bytes32);

Parameters

Returns

siblings

Compute the siblings of the ancestors of a leaf in a Merkle tree.

Raises an error if the provided index is out of bounds.

Raises an error if more than 2^height leaves are provided.

function siblings(bytes32[] memory leaves, uint256 index, uint256 height)
    internal
    pure
    returns (bytes32[] memory);

Parameters

Returns

merkleRootAfterReplacement

Compute the root of a Merkle tree after replacing one of its leaves.

Raises an error if the provided index is out of bounds.

function merkleRootAfterReplacement(bytes32[] calldata sibs, uint256 index, bytes32 leaf)
    internal
    pure
    returns (bytes32);

Parameters

Returns

parent

Compute the parent of two nodes.

Uses assembly for extra performance

function parent(bytes32 leftNode, bytes32 rightNode)
    internal
    pure
    returns (bytes32 parentNode);

Parameters

Returns

parentLevel

Compute the parent level of an array of nodes.

The default node of a parent level is the parent node of two default nodes.

function parentLevel(bytes32[] memory nodes, bytes32 defaultNode)
    internal
    pure
    returns (bytes32[] memory);

Parameters

Returns

at

Get the node at some index

function at(bytes32[] memory nodes, uint256 index, bytes32 defaultNode)
    internal
    pure
    returns (bytes32);

Parameters

LibOutputValidityProof

Git Source

Functions

isSiblingsArrayLengthValid

function isSiblingsArrayLengthValid(OutputValidityProof calldata v)
    internal
    pure
    returns (bool);

computeOutputsMerkleRoot

function computeOutputsMerkleRoot(OutputValidityProof calldata v, bytes32 outputHash)
    internal
    pure
    returns (bytes32);

Contents

• ERC1155BatchPortal
• ERC1155SinglePortal
• ERC20Portal
• ERC721Portal
• EtherPortal
• IERC1155BatchPortal
• IERC1155SinglePortal
• IERC20Portal
• IERC721Portal
• IEtherPortal
• IPortal
• Portal

ERC1155BatchPortal

Git Source

Inherits: IERC1155BatchPortal, Portal

This contract allows anyone to perform batch transfers of ERC-1155 tokens to an application contract while informing the off-chain machine.

Functions

constructor

Constructs the portal.

constructor(IInputBox inputBox) Portal(inputBox);

Parameters

depositBatchERC1155Token

function depositBatchERC1155Token(
    IERC1155 token,
    address appContract,
    uint256[] calldata tokenIds,
    uint256[] calldata values,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) external override;

ERC1155SinglePortal

Git Source

Inherits: IERC1155SinglePortal, Portal

This contract allows anyone to perform single transfers of ERC-1155 tokens to an application contract while informing the off-chain machine.

Functions

constructor

Constructs the portal.

constructor(IInputBox inputBox) Portal(inputBox);

Parameters

depositSingleERC1155Token

function depositSingleERC1155Token(
    IERC1155 token,
    address appContract,
    uint256 tokenId,
    uint256 value,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) external override;

ERC20Portal

Git Source

Inherits: IERC20Portal, Portal

This contract allows anyone to perform transfers of ERC-20 tokens to an application contract while informing the off-chain machine.

Functions

constructor

Constructs the portal.

constructor(IInputBox inputBox) Portal(inputBox);

Parameters

depositERC20Tokens

function depositERC20Tokens(
    IERC20 token,
    address appContract,
    uint256 value,
    bytes calldata execLayerData
) external override;

ERC721Portal

Git Source

Inherits: IERC721Portal, Portal

This contract allows anyone to perform transfers of ERC-721 tokens to an application contract while informing the off-chain machine.

Functions

constructor

Constructs the portal.

constructor(IInputBox inputBox) Portal(inputBox);

Parameters

depositERC721Token

function depositERC721Token(
    IERC721 token,
    address appContract,
    uint256 tokenId,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) external override;

EtherPortal

Git Source

Inherits: IEtherPortal, Portal

This contract allows anyone to perform transfers of Ether to an application contract while informing the off-chain machine.

Functions

constructor

Constructs the portal.

constructor(IInputBox inputBox) Portal(inputBox);

Parameters

depositEther

function depositEther(address appContract, bytes calldata execLayerData)
    external
    payable
    override;

IERC1155BatchPortal

Git Source

Inherits: IPortal

Functions

depositBatchERC1155Token

Transfer a batch of ERC-1155 tokens of multiple types to an application contract and add an input to the application's input box to signal such operation. The caller must enable approval for the portal to manage all of their tokens beforehand, by calling the setApprovalForAll function in the token contract.

Please make sure the arrays tokenIds and values have the same length.

function depositBatchERC1155Token(
    IERC1155 token,
    address appContract,
    uint256[] calldata tokenIds,
    uint256[] calldata values,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) external;

Parameters

IERC1155SinglePortal

Git Source

Inherits: IPortal

Functions

depositSingleERC1155Token

Transfer ERC-1155 tokens of a single type to an application contract and add an input to the application's input box to signal such operation. The caller must enable approval for the portal to manage all of their tokens beforehand, by calling the setApprovalForAll function in the token contract.

function depositSingleERC1155Token(
    IERC1155 token,
    address appContract,
    uint256 tokenId,
    uint256 value,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) external;

Parameters

IERC20Portal

Git Source

Inherits: IPortal

Functions

depositERC20Tokens

Transfer ERC-20 tokens to an application contract and add an input to the application's input box to signal such operation. The caller must allow the portal to withdraw at least value tokens from their account beforehand, by calling the approve function in the token contract.

function depositERC20Tokens(
    IERC20 token,
    address appContract,
    uint256 value,
    bytes calldata execLayerData
) external;

Parameters

Errors

ERC20TransferFailed

Failed to transfer ERC-20 tokens to application

error ERC20TransferFailed();

IERC721Portal

Git Source

Inherits: IPortal

Functions

depositERC721Token

Transfer an ERC-721 token to an application contract and add an input to the application's input box to signal such operation. The caller must change the approved address for the ERC-721 token to the portal address beforehand, by calling the approve function in the token contract.

function depositERC721Token(
    IERC721 token,
    address appContract,
    uint256 tokenId,
    bytes calldata baseLayerData,
    bytes calldata execLayerData
) external;

Parameters

IEtherPortal

Git Source

Inherits: IPortal

Functions

depositEther

Transfer Ether to an application contract and add an input to the application's input box to signal such operation.

Any Ether sent through this function will be forwarded to the application contract. If the transfer fails, an EtherTransferFailed error will be raised.

function depositEther(address appContract, bytes calldata execLayerData)
    external
    payable;

Parameters

Errors

EtherTransferFailed

Failed to transfer Ether to application

error EtherTransferFailed();

IPortal

Git Source

Functions

getInputBox

Get the input box used by this portal.

function getInputBox() external view returns (IInputBox);

Returns

Portal

Git Source

Inherits: IPortal

This contract serves as a base for all the other portals.

State Variables

_inputBox

The input box used by the portal.

IInputBox internal immutable _inputBox;

Functions

constructor

Constructs the portal.

constructor(IInputBox inputBox);

Parameters

getInputBox

function getInputBox() external view override returns (IInputBox);