Skip to main content

CartesiDApp

The CartesiDApp contract acts as the base layer incarnation of a dApp running on the execution layer. The dApp can interact with other smart contracts through the execution of vouchers and the validation of notices. The dApp frontend on the execution layer generates these outputs, which can be proven in the base layer thanks to claims submitted by a consensus contract.

Every dApp is subscribed to a consensus contract and governed by a single address, the owner. The consensus has the power to submit claims, which, in turn, are used to validate vouchers and notices. The owner has complete power over the dApp, as it can replace the consensus anytime. 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 {
uint64 inputIndexWithinEpoch;
uint64 outputIndexWithinInput;
bytes32 outputHashesRootHash;
bytes32 vouchersEpochRootHash;
bytes32 noticesEpochRootHash;
bytes32 machineStateHash;
bytes32[] outputHashInOutputHashesSiblings;
bytes32[] outputHashesInEpochSiblings;
}

Members

NameTypeDescription
inputIndexWithinEpochuint64Which input, inside the epoch, the output belongs to
outputIndexWithinInputuint64Index 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

© 2024 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.