IApplication
Inherits: IERC721Receiver, IERC1155Receiver
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 IConsensus contract (see the getConsensus 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 consensus, and may be governed by some owner. The consensus has the power to accept claims, which, in turn, are used to validate outputs. Meanwhile, the owner can replace the consensus at any time. Therefore, the users of an application must trust both the consensus 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)
See IConsensus for examples of consensus models.
Functions
migrateToConsensus
Migrate the application to a new consensus.
Can only be called by the application owner.
function migrateToConsensus(IConsensus newConsensus) external;
Parameters
| Name | Type | Description |
|---|---|---|
newConsensus | IConsensus | The new consensus |
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
| Name | Type | Description |
|---|---|---|
output | bytes | The output |
proof | OutputValidityProof | The proof used to validate the output against a claim submitted to the current consensus contract |
wasOutputExecuted
Check whether an output has been executed.
function wasOutputExecuted(uint256 outputIndex) external view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
outputIndex | uint256 | The index of output |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | Whether the output has been executed before |
validateOutput
Validate an output.
May raise any of the errors raised by validateOutputHash.
function validateOutput(bytes calldata output, OutputValidityProof calldata proof) external view;
Parameters
| Name | Type | Description |
|---|---|---|
output | bytes | The output |
proof | OutputValidityProof | The proof used to validate the output against a claim submitted to the current consensus contract |
validateOutputHash
Validate an output hash.
May raise InvalidOutputHashesSiblingsArrayLength
or ClaimNotAccepted.
function validateOutputHash(bytes32 outputHash, OutputValidityProof calldata proof) external view;
Parameters
| Name | Type | Description |
|---|---|---|
outputHash | bytes32 | The output hash |
proof | OutputValidityProof | The proof used to validate the output against a claim submitted to the current consensus contract |
getTemplateHash
Get the application's template hash.
function getTemplateHash() external view returns (bytes32);
Returns
| Name | Type | Description |
|---|---|---|
<none> | bytes32 | The application's template hash |
getConsensus
Get the current consensus.
function getConsensus() external view returns (IConsensus);
Returns
| Name | Type | Description |
|---|---|---|
<none> | IConsensus | The current consensus |
Events
NewConsensus
MUST trigger when a new consensus is chosen.
event NewConsensus(IConsensus newConsensus);
Parameters
| Name | Type | Description |
|---|---|---|
newConsensus | IConsensus | The new consensus |
OutputExecuted
MUST trigger when an output is executed.
event OutputExecuted(uint64 outputIndex, bytes output);
Parameters
| Name | Type | Description |
|---|---|---|
outputIndex | uint64 | The index of the output |
output | bytes | The output |
Errors
OutputNotExecutable
Could not execute an output, because the application contract doesn't know how to.
error OutputNotExecutable(bytes output);
Parameters
| Name | Type | Description |
|---|---|---|
output | bytes | The output |
OutputNotReexecutable
Could not execute an output, because it was already executed.
error OutputNotReexecutable(bytes output);
Parameters
| Name | Type | Description |
|---|---|---|
output | bytes | The output |
InvalidOutputHashesSiblingsArrayLength
Raised when the output hashes siblings array has an invalid size.
Please consult CanonicalMachine for the maximum number of outputs.
error InvalidOutputHashesSiblingsArrayLength();
ClaimNotAccepted
Raised when the required claim was not accepted by the current consensus.
error ClaimNotAccepted(bytes32 claim);