ovm-contracts

Usage

Build

$ forge build

Test

$ forge test

Format

$ forge fmt

Gas Snapshots

$ forge snapshot

Anvil

$ anvil

Deploy

Currently supported network: VLS Testnet LocalDevNet

To add new network, you need to:

update local .env
edit ./deploy-config/{chain_id}.json, add required params.

# With verification
forge script script/Deploy.s.sol:Deploy \
--chain-id $CHAIN_ID \
--rpc-url $RPC_URL \
--private-key $PRIVATE_KEY \
--verifier-url $VERIFIER_URL \
--verifier $VERIFIER \
--verify \
--etherscan-api-key $ETHERSCAN_API_KEY \
--broadcast --ffi -vvvv

# Without verification
forge script script/Deploy.s.sol:Deploy \
--chain-id $CHAIN_ID \
--rpc-url $RPC_URL \
--private-key $PRIVATE_KEY \
--broadcast --ffi -vvvv


# generate easily readable abi to /deployments
forge script script/Deploy.s.sol:Deploy --sig 'sync()' --rpc-url $RPC_URL --broadcast --ffi

IOVMClient

Git Source

The IOVMClient contract interface.

Functions

cancelRequest

Cancels a request by its requestId. Emits a {RequestCancelled} event.

function cancelRequest(bytes32 requestId) external;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the request to be cancelled.

setResponse

Sets the response data for a specific request. This function is called by the OVMGateway contract.

function setResponse(bytes32 requestId, bytes calldata data) external;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the request.
`data`	`bytes`	The response data to be set.

updateSpecification

Updates the specification of the OVM client.

function updateSpecification(Specification calldata newSpec) external;

Parameters

Name	Type	Description
`newSpec`	`Specification`	The new specification to update.

withdraw

Withdraws the contract's balance to the contract owner.

function withdraw() external;

isPendingRequest

Checks if a request is pending.

function isPendingRequest(bytes32 requestId) external view returns (bool);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the request.

Returns

Name	Type	Description
`<none>`	`bool`	isPending True if the request is pending, otherwise false.

getSpecification

Returns the specification of the contract.

function getSpecification() external view returns (Specification memory);

Returns

Name	Type	Description
`<none>`	`Specification`	specification The specification of the contract.

getOVMGatewayAddress

Get the address of the OVMGateway contract.

function getOVMGatewayAddress() external view returns (address);

Returns

Name	Type	Description
`<none>`	`address`	The address of the OVMGateway contract.

IOVMGateway

Git Source

The OVMGateway contract interface.

Functions

sendRequest

Sends a request to execute a task.

function sendRequest(
    address requester,
    address callbackAddress,
    bool deterministic,
    bytes calldata data
) external payable returns (bytes32 requestId);

Parameters

Name	Type	Description
`requester`	`address`	The address of the requester.
`callbackAddress`	`address`	The address of the contract to receive the callback.
`deterministic`	`bool`	Whether the request is deterministic.
`data`	`bytes`	The data to be passed to the callback function. msg.value is the payment for the task.

Returns

Name	Type	Description
`requestId`	`bytes32`	The unique identifier for the request.

cancelRequest

Cancels a request.

function cancelRequest(bytes32 requestId) external;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The request ID to cancel.

setResponse

Sets the response for a given requestId.

function setResponse(bytes32 requestId, bytes calldata data) external;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The unique identifier for the request.
`data`	`bytes`	The response data to be set.

getSpecification

Gets the specification of the callback contract.

function getSpecification(address callbackAddress) external view returns (Specification memory);

Parameters

Name	Type	Description
`callbackAddress`	`address`	The address of the callback contract.

Returns

Name	Type	Description
`<none>`	`Specification`	specification The specification of the callback contract.

getCommitments

Gets the commitments of a request.

function getCommitments(bytes32 requestId) external view returns (Commitment memory);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The request ID to get the commitments for.

Returns

Name	Type	Description
`<none>`	`Commitment`	commitments The commitments of the request.

getRequestsCount

Gets the number of requests.

function getRequestsCount() external view returns (uint256);

Returns

Name	Type	Description
`<none>`	`uint256`	count The number of requests.

ExecMode

Git Source

enum ExecMode {
    JIT,
    PERSISTENT
}

GPUModel

Git Source

enum GPUModel {
    T4
}

Requirement

Git Source

struct Requirement {
    string ram;
    string disk;
    uint256 timeout;
    uint256 cpu;
    uint256 gpu;
    GPUModel gpuModel;
}

Arch

Git Source

enum Arch {
    AMD64,
    ARM64
}

Specification

Git Source

Specification of the computing task. However, it doesn't define the running environment, etc. You need to define it in Dockerfile along with the source code of the computing task.

struct Specification {
    string version;
    string name;
    string description;
    string repository;
    string repoTag;
    string license;
    Requirement requirement;
    uint256 royalty;
    string apiABIs;
    Arch arch;
    ExecMode execMode;
}

Commitment

Git Source

struct Commitment {
    address requester;
    address callbackAddress;
    uint256 payment;
    uint256 cancelExpiration;
}

TransferFailed

Git Source

Transfer failed.

error TransferFailed();

RequestNotExpired

Git Source

Request not expired.

error RequestNotExpired();

InvalidRequesterOrCallback

Git Source

Requester or callback is invalid.

error InvalidRequesterOrCallback(address sender, address callbackAddress);

CallbackAddressIsNotContract

Git Source

Callback address is not a contract.

error CallbackAddressIsNotContract(address callbackAddress);

TaskRequestSent

Git Source

Emitted on sendRequest()

event TaskRequestSent(
    address indexed requester,
    bytes32 indexed requestId,
    address indexed callbackAddr,
    uint256 payment,
    uint256 cancelExpiration,
    bool deterministic,
    bytes data
);

Parameters

Name	Type	Description
`requester`	`address`	The address of the requester.
`requestId`	`bytes32`	The unique identifier of the request.
`callbackAddr`	`address`	The address of the callback contract.
`payment`	`uint256`	The amount of tokens sent with the request.
`cancelExpiration`	`uint256`	The timestamp when the request can be canceled.
`deterministic`	`bool`	Whether the request is deterministic.
`data`	`bytes`	The data sent with the request.

TaskRequestCanceled

Git Source

Emitted on cancelRequest()

event TaskRequestCanceled(bytes32 indexed requestId);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The unique identifier of the request.

TaskResponseSet

Git Source

Emitted on setResponse()

event TaskResponseSet(bytes32 indexed requestId, bytes data);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The unique identifier of the request.
`data`	`bytes`	The response data.

SpecificationUpdated

Git Source

Emitted on _updateSpecification()

event SpecificationUpdated(Specification specification);

Parameters

Name	Type	Description
`specification`	`Specification`	The new specification.

ResponseRecorded

Git Source

Emitted on modifier recordResponse()

event ResponseRecorded(bytes32 indexed requestId);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The unique identifier of the request.

OVMClient

Git Source

Inherits: IOVMClient, AccessControlEnumerable

THIS IS AN EXAMPLE CONTRACT WHICH USES HARDCODED VALUES FOR CLARITY. THIS EXAMPLE USES UN-AUDITED CODE. DO NOT USE THIS CODE IN PRODUCTION.

State Variables

ADMIN_ROLE

ADMIN_ROLE is the role that can do permissioned operations, such as updating the tax, update the specification, withdrawing funds.

bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");

DENOMINATOR

uint96 public constant DENOMINATOR = 10000;

_OVMGateway

address of the OVMGateway contract

address private immutable _OVMGateway;

_pendingRequests

pending requests are requests that are not yet responded by the OVM task contract

mapping(bytes32 requestId => bool isPending) private _pendingRequests;

_specification

specification is the metadata of the OVM client

Specification private _specification;

Functions

recordResponse

Modifier to record the response of a request. It removes the pending request, emits a ResponseRecorded event, and then executes the function.

modifier recordResponse(bytes32 requestId);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the request to record the response for.

onlyAdmin

modifier onlyAdmin();

onlyOVMGateway

modifier onlyOVMGateway();

constructor

constructor(address OVMGateway, address admin);

cancelRequest

Cancels a request by its requestId. Emits a {RequestCancelled} event.

function cancelRequest(bytes32 requestId) public virtual override;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the request to be cancelled.

updateSpecification

Updates the specification of the OVM client.

function updateSpecification(Specification calldata newSpec) public virtual override onlyAdmin;

Parameters

Name	Type	Description
`newSpec`	`Specification`	The new specification to update.

withdraw

Withdraws the contract's balance to the contract owner.

function withdraw() public virtual override onlyAdmin;

isPendingRequest

Checks if a request is pending.

function isPendingRequest(bytes32 requestId) public view virtual override returns (bool);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the request.

Returns

Name	Type	Description
`<none>`	`bool`	isPending True if the request is pending, otherwise false.

getSpecification

Returns the specification of the contract.

function getSpecification() public view virtual override returns (Specification memory);

Returns

Name	Type	Description
`<none>`	`Specification`	specification The specification of the contract.

getOVMGatewayAddress

Get the address of the OVMGateway contract.

function getOVMGatewayAddress() public view virtual override returns (address);

Returns

Name	Type	Description
`<none>`	`address`	The address of the OVMGateway contract.

_updateSpecification

Updates the specification of the OVM client.

function _updateSpecification(Specification memory spec) internal;

Parameters

Name	Type	Description
`spec`	`Specification`	The new specification to update.

_sendRequest

Creates a request that can hold additional parameters.

function _sendRequest(address requester, uint256 payment, bool deterministic, bytes memory data)
    internal
    virtual
    returns (bytes32 requestId);

Parameters

Name	Type	Description
`requester`	`address`	The address to send the requester.
`payment`	`uint256`	The amount of payment to send with the request.
`deterministic`	`bool`	Whether the request is deterministic.
`data`	`bytes`	The data encoded with computing params to send in the request.

Returns

Name	Type	Description
`requestId`	`bytes32`	The new ID of the request.

_removePendingRequest

Removes a pending request.

function _removePendingRequest(bytes32 requestId) internal virtual;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The ID of the pending request to be removed.

OVMGateway

Git Source

Inherits: IOVMGateway

THIS IS AN EXAMPLE CONTRACT WHICH USES HARDCODED VALUES FOR CLARITY. THIS EXAMPLE USES UN-AUDITED CODE. DO NOT USE THIS CODE IN PRODUCTION.

State Variables

EXPIRYTIME

The time after which a request can be canceled

uint256 public constant EXPIRYTIME = 5 minutes;

_requestCount

uint256 internal _requestCount;

_commitments

a commitment is a request that has not been fulfilled yet

mapping(bytes32 requestId => Commitment commitment) internal _commitments;

_tokensInEscrow

Tokens sent for requests that have not been fulfilled yet

uint256 internal _tokensInEscrow;

Functions

sendRequest

Sends a request to execute a task.

function sendRequest(
    address requester,
    address callbackAddress,
    bool deterministic,
    bytes calldata data
) external payable override returns (bytes32 requestId);

Parameters

Name	Type	Description
`requester`	`address`	The address of the requester.
`callbackAddress`	`address`	The address of the contract to receive the callback.
`deterministic`	`bool`	Whether the request is deterministic.
`data`	`bytes`	The data to be passed to the callback function. msg.value is the payment for the task.

Returns

Name	Type	Description
`requestId`	`bytes32`	The unique identifier for the request.

cancelRequest

Cancels a request.

function cancelRequest(bytes32 requestId) external override;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The request ID to cancel.

setResponse

Sets the response for a given requestId.

function setResponse(bytes32 requestId, bytes calldata data) external override;

Parameters

Name	Type	Description
`requestId`	`bytes32`	The unique identifier for the request.
`data`	`bytes`	The response data to be set.

getSpecification

Gets the specification of the callback contract.

function getSpecification(address callbackAddress)
    external
    view
    override
    returns (Specification memory);

Parameters

Name	Type	Description
`callbackAddress`	`address`	The address of the callback contract.

Returns

Name	Type	Description
`<none>`	`Specification`	specification The specification of the callback contract.

getCommitments

Gets the commitments of a request.

function getCommitments(bytes32 requestId) external view override returns (Commitment memory);

Parameters

Name	Type	Description
`requestId`	`bytes32`	The request ID to get the commitments for.

Returns

Name	Type	Description
`<none>`	`Commitment`	commitments The commitments of the request.

getRequestsCount

Gets the number of requests.

function getRequestsCount() external view override returns (uint256);

Returns

Name	Type	Description
`<none>`	`uint256`	count The number of requests.

_transfer

transfer native tokens by a low-level call. _transfer should always be at the end of the function, to apply the checks-effects-interactions pattern

function _transfer(address to, uint256 amount) internal;