Builder API Methods

This reference outlines the methods that are exposed to contract authors for building a GatewayRequest to read data from other chains.

Internally these methods utilize OP codes (opens in a new tab) that our Virtual Machine can interpret and execute.

Targets

These methods modifies the target contract for operations that follow.

Javascript	Solidity
Sets the target contract to the specified address.
`setTarget(x: HexString)`	`setTarget(address a)`

Javascript	Solidity
Sets the target contract to the top item on the stack.
`target()`	`target()`

Slot Manipulation

These methods manipulate the slot from which data will be read when a read command is executed.

Javascript	Solidity
Sets the current slot to x.
`setSlot(x: BigNumberish)`	`setSlot(uint256 x)`

Javascript	Solidity
Sets the current slot to the value at the top of the stack.
`slot()`	`slot()`

Javascript	Solidity
Increments the current slot by x.
`offset(x: BigNumberish)`	`offset(uint256 dx)`

Javascript	Solidity
Increments the current slot by the value at the top of the stack.
`addSlot()`	`addSlot()`

Javascript	Solidity
Updates the slot based on a key defined at the top of the stack.
`follow()`	`follow()`

Javascript	Solidity

`followIndex()`	`followIndex()`

Reading Values

These commands read data from the target contract.

Javascript	Solidity
Reads the value of n slots starting from the current VM slot.
`read(n = 1)`	`read() / read(uint256 n)`

Javascript	Solidity
Reads the bytes value at the current storage slot.
`readBytes()`	`readBytes()`

Javascript	Solidity

`readHashedBytes()`	`readHashedBytes()`

Javascript	Solidity
Reads an array value at the current storage slot. The step represents the array value length (in bytes).
`readArray(step: number)`	`readArray(uint256 step)`

Outputs

These commands set outputs that will be returned to the callback in the implementing contract.

Javascript	Solidity
Sets the output at index i to the item at the HEAD of the stack.
`setOutput(i: number)`	`setOutput(uint8 i)`

Javascript	Solidity
Sets the output at the index defined at the HEAD of the stack to the value found at HEAD-1
`output()`	`output()`

Nested Requests

These commands allow you to evaluate nested requests.

!! Advanced functionality - more documentation coming.

Javascript	Solidity
Will evaluate an encoded request that has been pushed onto the HEAD of the stack.
`eval()`	`eval()`

Javascript	Solidity
Will evaluate an encoded request that has been pushed onto the HEAD of the stack IF the previous operation resolves to true.
`evalIf()`	`evalIf()`

Javascript	Solidity
Will evaluate an encoded request that has been pushed onto the HEAD of the stack against the specified number of items on the stack. Execution results are conditional on passed flags which in Javascript are passed as booleans on object properties, whilst in Solidity they are passed as a uint8.
`evalLoop(opts: {success?: boolean; failure?: boolean; acquire?: boolean; keep?: boolean; count?: number;} = {})`	`evalLoop(uint8 flags)/evalLoop(uint8 flags,uint256 count)`

The available evaluation flags are enumerated here: Typescript (opens in a new tab) and Solidity (opens in a new tab). They are:

STOP_ON_SUCCESS
STOP_ON_FAILURE
ACQUIRE_STATE
KEEP_ARGS

Exiting

These commands handle assertions, requirements, and graceful request exits.

Javascript	Solidity
Exit with the specified exit code.
`exit(exitCode: number)`	`exit(uint8 exitCode)`

Javascript	Solidity
Exit with the specified exit code if the item at the top of the stack is not zero.
`assertNonzero(exitCode: number)`	`assertNonzero(uint8 exitCode)`

Javascript	Solidity
Exit with the specified exit code if the current target is not a contract.
`requireContract(exitCode = 1)`	`requireContract(uint8 exitCode)`

Javascript	Solidity
Exit with the specified exit code if the item at the top of the stack is not zero. Leaves the item on the stack
`requireNonzero(exitCode = 1)`	`requireNonzero(uint8 exitCode)`

Stack Manipulation

These commands manipulate the data on the Virtual Machine's internal stack.

Javascript	Solidity

`pop()`	`pop()`

Javascript	Solidity

`dup(back = 0)`	`dup() / dup(uint256 back)`

Javascript	Solidity

`swap(back = 1)`	`swap() / swap(uint256 back)`

Javascript	Solidity

`pushOutput(i: number)`	`pushOutput(uint256 i)`

Javascript	Solidity

`pushStack(i: number)`	`pushStack(uint256 i)`

Javascript	Solidity

`push(x: BigNumberish \| boolean)`	N/A

Javascript	Solidity

`pushStr(s: string)`	N/A

Javascript	Solidity

`pushBytes(v: BytesLike)`	N/A

Javascript	Solidity

`pushProgram(program: GatewayProgram)`	N/A

Javascript	Solidity
Pushes the current slot onto the stack.
`getSlot()`	`getSlot()`

Javascript	Solidity
Pushes the current target onto the stack.
`getTarget()`	`getTarget()`

Javascript	Solidity
Pushes the current stack size onto the stack.
`stackSize()`	`stackCount()`

Javascript	Solidity
Pushes onto the stack if the current target is a contract.
`isContract()`	`isContract()`

Data Manipulation

These commands manipulate data on the stack.

Javascript	Solidity
Replaces the top two items on the stack with their concatentation.
`concat()`	`concat()`

Javascript	Solidity
Replaces the top item on the stack with its keccak256 representation.
`keccak()`	`keccak()`

Javascript	Solidity
Slices n/len bytes from the value at the HEAD of the stack starting at position x/pos
`slice(x: number, n: number)`	`slice(uint256 pos, uint256 len)`

Javascript	Solidity
Replaces the value at the head of the stack with its length.
`length()`	`length()`

Javascript	Solidity
Replaces the two items at the top of the stack with their summation.
`plus()`	`plus()`

Javascript	Solidity
Replaces the two items at the head of the stack with the result of subtracting the value at HEAD from the value at HEAD - 1.
`subtract()`	`subtract()`

Javascript	Solidity
Replaces the value at the top of the stack with its twos complement.
`twosComplement()`	`twosComplement()`

Javascript	Solidity
Multiplies the two values at the head of the stack and replaces them with the result.
`times()`	`times()`

Javascript	Solidity
Divides the value at HEAD-1 of the stack by the value at HEAD and replaces them with the result.
`divide()`	`divide()`

Javascript	Solidity
Calculates the value at HEAD-1 modulo the value at HEAD and replaces them with the result.
`mod()`	`mod()`

Javascript	Solidity
Replaces the two items at the head of the stack with the result of the value at HEAD-1 being raised to the power of the value at HEAD.
`pow()`	`pow()`

Javascript	Solidity
Replaces the two values at the top of the stack with their Bitwise AND
`and()`	`and()`

Javascript	Solidity
Replaces the two values at the top of the stack with their Bitwise OR
`or()`	`or()`

Javascript	Solidity
Replaces the two values at the top of the stack with their Bitwise XOR
`xor()`	`xor()`

Javascript	Solidity
Replaces the value at the top of the stack with its Bitwise NOT
`not()`	`not()`

Javascript	Solidity
Bitwise shifts the value at the top of the stack by `shift` bits to the left.
`shl(shift: BigNumberish)`	`shl(uint8 shift)`

Javascript	Solidity
Bitwise shifts the value at the top of the stack by `shift` bits to the right.
`shr(shift: BigNumberish)`	`shr(uint8 shift)`

Comparison Operations

These commands perform comparison operations on stack data.

Javascript	Solidity
Replaces the value at the top of the stack with a boolean indicating if it is zero.
`isZero()`	`isZero()`

Javascript	Solidity
Replaces the top two items on the stack with a boolean indicating if they are equal.
`eq()`	`eq()`

Javascript	Solidity
Replaces the top two items on the stack with a boolean indicating if they are not equal.
`neq()`	`neq()`

Javascript	Solidity
Replaces the top two items on the stack with a boolean indicating of the value at HEAD-1 is greater than the value at the HEAD.
`gt()`	`gt()`

Javascript	Solidity
Replaces the top two items on the stack with a boolean indicating of the value at HEAD-1 is less than the value at the HEAD.
`lt()`	`lt()`

Javascript	Solidity
Replaces the top two items on the stack with a boolean indicating of the value at HEAD-1 is less than or equal the value at the HEAD.
`lte()`	`lte()`

Javascript	Solidity
Replaces the top two items on the stack with a boolean indicating of the value at HEAD-1 is greater than or equal to the value at the HEAD.
`gte()`	`gte()`

Javascript	Solidity
Duplicate the top two items on the stack.
`dup2()`	`dup2()`

Javascript	Solidity
Puts the minimum value out of the last two values on the stack at the HEAD.
`min()`	`min()`

Javascript	Solidity
Puts the maximum value out of the last two values on the stack at the HEAD.
`max()`	`max()`

Debug

These commands aid in debugging your requests.

Javascript	Solidity
Used for debugging. Outputs the machine state to the console. Available only in JavaScript.
`debug(label = '')`	N/A

Virtual Machine Verifier deployments