IApplication

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

Name	Type	Description
`newOutputsMerkleRootValidator`	`IOutputsMerkleRootValidator`	The new outputs Merkle root validator

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 accepted to the current outputs Merkle root validator 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 accepted to the current outputs Merkle root validator contract

validateOutputHash

Validate an output hash.

May raise InvalidOutputHashesSiblingsArrayLength or InvalidOutputsMerkleRoot.

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 accepted to the current outputs Merkle root validator 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

getOutputsMerkleRootValidator

Get the current outputs Merkle root validator.

function getOutputsMerkleRootValidator()
    external
    view
    returns (IOutputsMerkleRootValidator);

Returns

Name	Type	Description
`<none>`	`IOutputsMerkleRootValidator`	The current outputs Merkle root validator

getDataAvailability

Get the data availability solution used by application.

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

Returns

Name	Type	Description
`<none>`	`bytes`	Solidity ABI-encoded function call that describes the source of inputs that should be fed to the application.

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

Name	Type	Description
`newOutputsMerkleRootValidator`	`IOutputsMerkleRootValidator`	The new outputs Merkle root validator

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

InsufficientFunds

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

error InsufficientFunds(uint256 value, uint256 balance);

Parameters

Name	Type	Description
`value`	`uint256`	The amount of Wei necessary for the execution of the output
`balance`	`uint256`	The current application contract balance

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