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
Name | Type | Description |
---|---|---|
_destination | address | The address that will receive the payload through a message call |
_payload | bytes | The payload, which—in the case of Solidity contracts—encodes a function call |
_proof | struct Proof | The proof used to validate the voucher against a claim submitted by the current consensus contract |
Return Values
Name | Type | Description |
---|---|---|
[0] | bool | Whether 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
Name | Type | Description |
---|---|---|
_inboxInputIndex | uint256 | The index of the input in the input box |
_outputIndex | uint256 | The index of output emitted by the input |
Return Values
Name | Type | Description |
---|---|---|
[0] | bool | Whether the voucher has been executed before |
validateNotice()
function validateNotice(bytes _notice, struct Proof _proof) external view returns (bool)
Validate a notice.
Parameters
Name | Type | Description |
---|---|---|
_notice | bytes | The notice |
_proof | struct Proof | Data for validating outputs |
Return Values
Name | Type | Description |
---|---|---|
[0] | bool | Whether 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
Name | Type | Description |
---|---|---|
_newConsensus | contract IConsensus | The new consensus |
getTemplateHash()
function getTemplateHash() external view returns (bytes32)
Get the dApp's template hash.
Return Values
Name | Type | Description |
---|---|---|
[0] | bytes32 | The dApp's template hash |
getConsensus()
function getConsensus() external view returns (contract IConsensus)
Get the current consensus.
Return Values
Name | Type | Description |
---|---|---|
[0] | contract IConsensus | The 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
Name | Type | Description |
---|---|---|
_receiver | address | The address which will receive the amount of Ether |
_value | uint256 | The 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
Name | Type | Description |
---|---|---|
newConsensus | IConsensus | The 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
Name | Type | Description |
---|---|---|
voucherId | uint256 | A 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
Name | Type | Description |
---|---|---|
validity | OutputValidityProof | A validity proof for the output |
context | bytes | Data 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
Name | Type | Description |
---|---|---|
inputIndexWithinEpoch | uint64 | Which input, inside the epoch, the output belongs to |
outputIndexWithinInput | uint64 | Index of output emitted by the input |
outputHashesRootHash | bytes32 | Merkle root of hashes of outputs emitted by the input |
vouchersEpochRootHash | bytes32 | Merkle root of all epoch's voucher metadata hashes |
noticesEpochRootHash | bytes32 | Merkle root of all epoch's notice metadata hashes |
machineStateHash | bytes32 | Hash of the machine state claimed this epoch |
outputHashInOutputHashesSiblings | bytes32[] | Proof that this output metadata is in metadata memory range |
outputHashesInEpochSiblings | bytes32[] | Proof that this output metadata is in epoch's output memory range |