Co-Processor base contract

This is a base contract containing functions for calling with the co-processor and also a callback function to receive response from the co-processor. This function can be overridden where necessary or in the most simple implementation just the "handleCallback" function can be overridden to contain implementations to handle response from the co-processor.

Usage

Installation

Install the base contract by running the following command:

forge install https://github.com/Mugen-Builders/coprocessor-base-contract

Import the base contract into your project through the following command:

import "cartesi-coprocessor-base-contract/BaseContract.sol";

Inherit the base contract and also populate the constructor parameters:

contract MyContract is CoprocessorAdapter {
    constructor(address _coprocessorAddress, bytes32 _machineHash)
        CoprocessorAdapter(_coprocessorAddress, _machineHash)
    {}
    // Add your Logic here
}

Authors

Carsten Munk
Henrique Marlon
Idogwu Chinonso

LibAddress

Git Source

Functions

safeCall

Perform a low level call and raise error if failed

function safeCall(address destination, uint256 value, bytes memory payload) internal returns (bool, uint256);

Parameters

Name	Type	Description
`destination`	`address`	The address that will be called
`value`	`uint256`	The amount of Wei to be transferred through the call
`payload`	`bytes`	The payload, which—in the case of Solidity contracts—encodes a function call

Returns

Name	Type	Description
`<none>`	`bool`	Whether the caller had enough Ether to make the call, and the balance before the call
`<none>`	`uint256`

safeDelegateCall

Perform a delegate call and raise error if failed

function safeDelegateCall(address destination, bytes memory payload) internal;

Parameters

Name	Type	Description
`destination`	`address`	The address that will be called
`payload`	`bytes`	The payload, which—in the case of Solidity libraries—encodes a function call

LibError

Git Source

Functions

raise

Raise error data

function raise(bytes memory errordata) internal pure;

Parameters

Name	Type	Description
`errordata`	`bytes`	Data returned by failed low-level call

CoprocessorAdapter

Git Source

Inherits: ICoprocessorCallback

A base contract, which should be inherited for interacting with the Coprocessor

State Variables

machineHash

bytes32 public machineHash;

coprocessor

ICoprocessor public coprocessor;

computationSent

mapping(bytes32 => bool) public computationSent;

Functions

constructor

Initializes the contract with the coprocessor address and machine hash

constructor(address _coprocessorAddress, bytes32 _machineHash);

Parameters

Name	Type	Description
`_coprocessorAddress`	`address`	Address of the coprocessor
`_machineHash`	`bytes32`	Initial machine hash

callCoprocessor

Issues a task to the coprocessor

function callCoprocessor(bytes calldata input) internal;

Parameters

Name	Type	Description
`input`	`bytes`	ABI-encoded input data for the coprocessor

handleNotice

Handles notices sent back from the coprocessor

This function should be overridden by child contracts to define specific behavior

function handleNotice(bytes memory notice) internal virtual;

Parameters

Name	Type	Description
`notice`	`bytes`	ABI-encoded notice data

coprocessorCallbackOutputsOnly

Callback function invoked by the coprocessor with computation outputs

function coprocessorCallbackOutputsOnly(bytes32 _machineHash, bytes32 _payloadHash, bytes[] calldata outputs)
    external
    override;

Parameters

Name	Type	Description
`_machineHash`	`bytes32`	The hash of the machine that processed the task
`_payloadHash`	`bytes32`	The hash of the input payload
`outputs`	`bytes[]`	Array of ABI-encoded outputs from the coprocessor

_executeVoucher

Executes a voucher

This function decodes and executes a voucher with the specified parameters

function _executeVoucher(bytes calldata arguments) internal;

Parameters

Name	Type	Description
`arguments`	`bytes`	ABI-encoded arguments containing the destination, value, and payload

Errors

UnauthorizedCaller

error UnauthorizedCaller(address caller);

InvalidOutputLength

error InvalidOutputLength(uint256 length);

ComputationNotFound

error ComputationNotFound(bytes32 payloadHash);

InsufficientFunds

error InsufficientFunds(uint256 value, uint256 balance);

MachineHashMismatch

error MachineHashMismatch(bytes32 current, bytes32 expected);

InvalidOutputSelector

error InvalidOutputSelector(bytes4 selector, bytes4 expected);

ICoprocessor

Git Source

Defines the interface for interacting with a coprocessor contract

Functions

issueTask

Issues a task to the coprocessor

function issueTask(bytes32 machineHash, bytes calldata input, address callbackAddress) external;

Parameters

Name	Type	Description
`machineHash`	`bytes32`	The hash of the machine to which the task is assigned
`input`	`bytes`	The ABI-encoded input data for the task
`callbackAddress`	`address`	The address to which the callback will be sent upon task completion

ICoprocessorCallback

Git Source

Defines the callback mechanism for handling coprocessor outputs

Functions

coprocessorCallbackOutputsOnly

Handles outputs from the coprocessor

function coprocessorCallbackOutputsOnly(bytes32 machineHash, bytes32 payloadHash, bytes[] calldata outputs) external;

Parameters

Name	Type	Description
`machineHash`	`bytes32`	The hash of the machine that processed the task
`payloadHash`	`bytes32`	The hash of the input payload that generated these outputs
`outputs`	`bytes[]`	Array of ABI-encoded outputs from the coprocessor

ICoprocessorOutputs

Git Source

Defines the outputs that can be generated by a coprocessor

Functions

Notice

Emits a notice event with the given payload

function Notice(bytes calldata payload) external;

Parameters

Name	Type	Description
`payload`	`bytes`	The ABI-encoded payload containing notice data

Voucher

Issues a voucher to execute a specific action

function Voucher(address destination, uint256 value, bytes calldata payload) external;

Parameters

Name	Type	Description
`destination`	`address`	The address to which the voucher is directed
`value`	`uint256`	The amount of ETH to transfer with the voucher
`payload`	`bytes`	The ABI-encoded payload containing the action data