Skip to main content
Version: 1.0

CartesiDApp

The CartesiDApp contract acts as the base layer incarnation of a dApp running on the execution layer. The dApp is hereby able to interact with other smart contracts through the execution of vouchers and the validation of notices. These outputs are generated by the dApp back-end on the execution layer and can be proven in the base layer thanks to claims submitted by a consensus contract.

A voucher is a one-time message call to another contract. It can encode asset transfers, approvals, or any other message call that doesn't require Ether to be sent along. A voucher will only be consumed if the underlying message call succeeds (that is, it doesn't revert). Furthermore, the return data of the message call is discarded entirely. As a protective measure against reentrancy attacks, nested voucher executions are prohibited.

A notice, on the other hand, constitutes an arbitrary piece of data that can be proven any number of times. On their own, they do not trigger any type of contract-to-contract interaction. Rather, they merely serve to attest off-chain results, e.g. which player won a particular chess match.

Every dApp is subscribed to a consensus contract, and governed by a single address, the owner. The consensus has the power of submitting claims, which, in turn, are used to validate vouchers and notices. Meanwhile, the owner has complete power over the dApp, as it can replace the consensus at any time. Therefore, the users of a dApp must trust both the consensus and the dApp owner.

The dApp developer can choose whichever ownership and consensus models it wants.

Examples of dApp ownership models include:

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

See IConsensus for examples of consensus models.

This contract inherits the following OpenZeppelin contracts.

  • Ownable
  • ERC721Holder
  • ERC1155Holder
  • ReentrancyGuard

For more information, please consult OpenZeppelin's official documentation.

executeVoucher

function executeVoucher(address _destination, bytes _payload, struct Proof _proof) external returns (bool)

Try to execute a voucher.

Reverts if voucher was already successfully executed.

On a successful execution, emits a VoucherExecuted event.

Parameters

NameTypeDescription
_destinationaddressThe address that will receive the payload through a message call
_payloadbytesThe payload, which—in the case of Solidity contracts—encodes a function call
_proofstruct ProofThe proof used to validate the voucher against a claim submitted by the current consensus contract

Return Values

NameTypeDescription
[0]boolWhether the execution was successful or not

wasVoucherExecuted

function wasVoucherExecuted(uint256 _inboxInputIndex, uint256 _outputIndex) external view returns (bool)

Check whether a voucher has been executed.

Parameters

NameTypeDescription
_inboxInputIndexuint256The index of the input in the input box
_outputIndexuint256The index of output emitted by the input

Return Values

NameTypeDescription
[0]boolWhether the voucher has been executed before

validateNotice

function validateNotice(bytes _notice, struct Proof _proof) external view returns (bool)

Validate a notice.

Parameters

NameTypeDescription
_noticebytesThe notice
_proofstruct ProofData for validating outputs

Return Values

NameTypeDescription
[0]boolWhether the notice is valid or not

migrateToConsensus

function migrateToConsensus(contract IConsensus _newConsensus) external

Migrate the dApp to a new consensus.

Can only be called by the dApp owner.

Parameters

NameTypeDescription
_newConsensuscontract IConsensusThe new consensus

getTemplateHash

function getTemplateHash() external view returns (bytes32)

Get the dApp's template hash.

Return Values

NameTypeDescription
[0]bytes32The dApp's template hash

getConsensus

function getConsensus() external view returns (contract IConsensus)

Get the current consensus.

Return Values

NameTypeDescription
[0]contract IConsensusThe current consensus

receive

receive() external payable

Accept Ether transfers.

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

withdrawEther

function withdrawEther(address _receiver, uint256 _value) external

Transfer some amount of Ether to some recipient.

This function can only be called by the dApp itself through vouchers.

Parameters

NameTypeDescription
_receiveraddressThe address which will receive the amount of Ether
_valueuint256The amount of Ether to be transferred in Wei

NewConsensus

event NewConsensus(IConsensus newConsensus);

A new consensus is used, this event is emitted when a new consensus is set. This event must be triggered on a successful call to migrateToConsensus.

Parameters

NameTypeDescription
newConsensusIConsensusThe new consensus contract

VoucherExecuted

event VoucherExecuted(uint256 voucherId);

A voucher was executed from the dApp, this event is emitted when a voucher is executed so it must be triggered on a successful call to executeVoucher.

Parameters

NameTypeDescription
voucherIduint256A number that uniquely identifies the voucher amongst all vouchers emitted by this dApp

Proof

Data for validating outputs

struct Proof {
OutputValidityProof validity;
bytes context;
}

Members

NameTypeDescription
validityOutputValidityProofA validity proof for the output
contextbytesData for querying the right claim from consensus

OutputValidityProof

Data used to prove the validity of an output (notices and vouchers)

struct OutputValidityProof {
uint256 inputIndexWithinEpoch;
uint256 outputIndexWithinInput;
bytes32 outputHashesRootHash;
bytes32 vouchersEpochRootHash;
bytes32 noticesEpochRootHash;
bytes32 machineStateHash;
bytes32[] outputHashInOutputHashesSiblings;
bytes32[] outputHashesInEpochSiblings;
}

Members

NameTypeDescription
inputIndexWithinEpochuint256Which input, inside the epoch, the output belongs to
outputIndexWithinInputuint256Index of output emitted by the input
outputHashesRootHashbytes32Merkle root of hashes of outputs emitted by the input
vouchersEpochRootHashbytes32Merkle root of all epoch's voucher metadata hashes
noticesEpochRootHashbytes32Merkle root of all epoch's notice metadata hashes
machineStateHashbytes32Hash of the machine state claimed this epoch
outputHashInOutputHashesSiblingsbytes32[]Proof that this output metadata is in metadata memory range
outputHashesInEpochSiblingsbytes32[]Proof that this output metadata is in epoch's output memory range

© 2023 Cartesi Foundation Ltd. All rights reserved.

The Cartesi Project is commissioned by the Cartesi Foundation.

We use cookies to ensure that we give you the best experience on our website. By using the website, you agree to the use of cookies.