​

evm

​

Namespaces

• Arithmetic
• Bitwise
• Block
• Comparison
• Context
• Control
• Keccak
• Log
• Memory
• Stack
• Storage
• System

​

Type Aliases

​

BrandedFrame

BrandedFrame = object

​

Properties

[brand]

readonly [brand]: "Frame"

accessedAddresses?

optional accessedAddresses: Set<string>

accessedStorageKeys?

optional accessedStorageKeys: Map<string, boolean>

address

address: AddressType

authorized

authorized: bigint | null

blobBaseFee?

optional blobBaseFee: bigint

blobVersionedHashes?

optional blobVersionedHashes: bigint[]

blockBaseFee?

optional blockBaseFee: bigint

blockDifficulty?

optional blockDifficulty: bigint

blockGasLimit?

optional blockGasLimit: bigint

blockHashes?

optional blockHashes: Map<bigint, bigint>

blockNumber?

optional blockNumber: bigint

blockPrevrandao?

optional blockPrevrandao: bigint

blockTimestamp?

optional blockTimestamp: bigint

bytecode

bytecode: Uint8Array

calldata

calldata: Uint8Array

callDepth

callDepth: number

caller

caller: AddressType

chainId?

optional chainId: bigint

coinbase?

optional coinbase: AddressType

gasRefunds?

optional gasRefunds: bigint

gasRemaining

gasRemaining: bigint

hardfork?

optional hardfork: HardforkType

isStatic

isStatic: boolean

logs?

optional logs: object[]

address

address: AddressType

data

data: Uint8Array

topics

topics: bigint[]

memory

memory: Map<number, number>

memorySize

memorySize: number

output

output: Uint8Array

pc

pc: number

returnData

returnData: Uint8Array

reverted

reverted: boolean

selfBalance?

optional selfBalance: bigint

stack

stack: bigint[]

stopped

stopped: boolean

storageOriginalValues?

optional storageOriginalValues: Map<string, bigint>

value

value: bigint

​

Methods

add()

add(): EvmError | null

Returns

addmod()

addmod(): EvmError | null

Returns

div()

div(): EvmError | null

Returns

exp()

exp(): EvmError | null

Returns

mod()

mod(): EvmError | null

Returns

mul()

mul(): EvmError | null

Returns

mulmod()

mulmod(): EvmError | null

Returns

sdiv()

sdiv(): EvmError | null

Returns

signextend()

signextend(): EvmError | null

Returns

smod()

smod(): EvmError | null

Returns

sub()

sub(): EvmError | null

Returns

​

BrandedHost

BrandedHost = object

​

Architecture Note

• guillotine: Production EVM with async state access, tracing, and full EIP support
• guillotine-mini: Lightweight synchronous EVM for testing and simple use cases

​

Properties

[brand]

readonly [brand]: "Host"

call()?

optional call: (params) => CallResult

Parameters

params

Returns

create()?

optional create: (params) => CreateResult

Parameters

params

Returns

getBalance()

getBalance: (address) => bigint

Parameters

address

Returns

getCode()

getCode: (address) => Uint8Array

Parameters

address

Returns

getNonce()

getNonce: (address) => bigint

Parameters

address

Returns

getStorage()

getStorage: (address, slot) => bigint

Parameters

address

slot

Returns

getTransientStorage()

getTransientStorage: (address, slot) => bigint

Parameters

address

slot

Returns

setBalance()

setBalance: (address, balance) => void

Parameters

address

balance

Returns

setCode()

setCode: (address, code) => void

Parameters

address

code

Returns

setNonce()

setNonce: (address, nonce) => void

Parameters

address

nonce

Returns

setStorage()

setStorage: (address, slot, value) => void

Parameters

address

slot

value

Returns

setTransientStorage()

setTransientStorage: (address, slot, value) => void

Parameters

address

slot

value

Returns

​

CallParams

CallParams = object

​

Example

const params: CallParams = {
  callType: "CALL",
  target: targetAddress,
  value: 1000000000000000000n, // 1 ether in wei
  gasLimit: 100000n,
  input: calldata,
  caller: frame.address,
  isStatic: false,
};

​

Properties

caller

caller: AddressType

callType

callType: CallType

depth

depth: number

gasLimit

gasLimit: bigint

input

input: Uint8Array

isStatic

isStatic: boolean

target

target: AddressType

value

value: bigint

​

CallResult

CallResult = object

​

Example

// Successful call
const result: CallResult = {
  success: true,
  gasUsed: 21000n,
  output: returnData,
  logs: [{ address, topics, data }],
  gasRefund: 0n,
};

// Failed call (reverted)
const revertResult: CallResult = {
  success: false,
  gasUsed: 50000n,
  output: revertReason,
  logs: [],
  gasRefund: 0n,
};

​

Properties

gasRefund

gasRefund: bigint

gasUsed

gasUsed: bigint

logs

logs: object[]

address

address: AddressType

data

data: Uint8Array

topics

topics: bigint[]

output

output: Uint8Array

success

success: boolean

​

CallType

CallType = "CALL" | "STATICCALL" | "DELEGATECALL" | "CALLCODE"

​

CreateParams

CreateParams = object

​

Example

// CREATE2 with deterministic address
const params: CreateParams = {
  caller: deployerAddress,
  value: 0n,
  initCode: contractBytecode,
  gasLimit: 1000000n,
  salt: 0x123n, // For CREATE2
};

​

Properties

caller

caller: AddressType

depth

depth: number

gasLimit

gasLimit: bigint

initCode

initCode: Uint8Array

salt?

optional salt: bigint

value

value: bigint

​

CreateResult

CreateResult = object

​

Example

// Successful deployment
const result: CreateResult = {
  success: true,
  address: newContractAddress,
  gasUsed: 200000n,
  output: runtimeCode,
};

// Failed deployment
const failResult: CreateResult = {
  success: false,
  address: null,
  gasUsed: 100000n,
  output: revertReason,
};

​

Properties

address

address: AddressType | null

gasRefund

gasRefund: bigint

gasUsed

gasUsed: bigint

output

output: Uint8Array

success

success: boolean

​

EvmError

EvmError = { type: "StackOverflow"; } | { type: "StackUnderflow"; } | { type: "OutOfGas"; } | { type: "OutOfBounds"; } | { type: "InvalidJump"; } | { type: "InvalidOpcode"; } | { type: "RevertExecuted"; } | { type: "CallDepthExceeded"; } | { type: "WriteProtection"; } | { type: "InsufficientBalance"; } | { message: string; type: "NotImplemented"; }

​

InstructionHandler()

InstructionHandler = (frame, host) => EvmError | { type: "Success"; }

​

Parameters

frame

host

​

Returns

​

Example

// ADD opcode handler (0x01)
const addHandler: InstructionHandler = (frame: BrandedFrame, host: BrandedHost) => {
  if (frame.stack.length < 2) {
    return { type: "StackUnderflow" };
  }
  const b = frame.stack.pop()!;
  const a = frame.stack.pop()!;
  frame.stack.push((a + b) % 2n**256n); // Mod 2^256
  return { type: "Success" };
};

​

Functions

​

Frame()

Frame(params): BrandedFrame

​

Parameters

params

​

Returns

​

Example

import { Frame } from 'voltaire/evm/Frame';

const frame = Frame({
  bytecode: new Uint8Array([0x60, 0x01]),
  gas: 100000n,
});

​

Host()

Host(impl): BrandedHost

​

Parameters

impl

​

Returns

​

Example

import { Host } from 'voltaire/evm/Host';

const host = Host({
  getBalance: (addr) => balances.get(addr) ?? 0n,
  setBalance: (addr, bal) => balances.set(addr, bal),
  // ... other methods
});

​

References

​

Precompiles