​
Introduction

Cheatcodes are PhEVM (Phylax EVM) specific instructions implemented in native code instead of EVM bytecode. They can communicate with Internal APIs and support all existing Ethereum cheatcodes up to Dancun, plus new capabilities for:

  1. Manipulation of the PhEVM state
  2. Forking of state from one or multiple EVM networks
  3. Utilities for writing and managing assertions

You may notice the terms “precompiles” and “cheatcodes” used interchangeably in some contexts. We use the term “cheatcodes” as it’s more familiar to Solidity developers who are already using testing frameworks like Foundry/Forge or Hardhat. Both terms refer to native functions that extend the EVM’s capabilities, but “cheatcodes” better reflects their role in the developer experience.

​
Storage Operations

​
load

Loads a storage slot from an address.

Using forge inspect <ContractName> storage-layout is an easy way to get the storage layout of a contract. This can be used to determine the storage slot of a specific variable to use in the cheatcode.

function load(
    address target, 
    bytes32 slot
) external view returns (bytes32 data)

​
State Management

​
forkPreState

Updates the active fork to the state before the triggering transaction. Useful for:

  • Checking chain state before a transaction
  • Comparing values between pre and post states
function forkPreState() external

​
forkPostState

Updates the active fork to the state after the triggering transaction. Useful for:

  • Verifying chain state after a transaction
  • Comparing values between pre and post states
function forkPostState() external

​
Transaction Data

​
getLogs

Retrieves all logs emitted by the latest transaction.

struct Log {
    bytes32[] topics;   // Log topics, including signature
    bytes data;         // Raw log data
    address emitter;    // Log emitter address
}

function getLogs() external returns (Log[] memory logs)

​
getCallInputs

Gets the call inputs of all the calls made in the current transaction and returns them in an array of CallInputs structs. This is a useful precompile to use for intra-transaction assertions such as checking if the price reported by an oracle deviates from an allowed range, which could be a sign of an oracle manipulation.

struct CallInputs {
    bytes input;                // Call data
    uint64 gas_limit;           // Gas limit
    address bytecode_address;   // Code execution address
    address target_address;     // Storage modification target
    address caller;             // Transaction caller
    uint256 value;              // Call value
}

function getCallInputs(
    address target, 
    bytes4 selector
) external view returns (CallInputs[] memory calls);

Internal calls are not actual EVM calls but rather a Solidity language feature. They are not traced by the CallTracer and will not result in CallInputs or trigger call-based assertions. However, using the this keyword (e.g., this.functionName()) creates an external call that will be traced and can trigger assertions.

Example:

function foo() external {
    // Internal call - not traced, no CallInputs generated
    bar();
   
    // External call via 'this' - traced, generates CallInputs
    this.bar();
}

function bar() public {
    // Function implementation
}

​
State Change Tracking

​
getStateChanges

Returns state changes for a contract’s storage slot within the current call stack.

Using forge inspect <ContractName> storage-layout is an easy way to get the storage layout of a contract. This can be used to determine the storage slot of a specific variable to use in the cheatcode.

function getStateChanges(
    address contractAddress,
    bytes32 slot
) external view returns (bytes32[] memory stateChanges);

The array returned includes the initial value of the slot as the first element, so the length of the array is either 0 or >= 2.

​
Helper Functions

The following helpers convert state changes to specific types. Each has three variants:

  • Basic: Get changes for a single slot
  • Mapping: Get changes using a mapping key
  • Mapping with Offset: Get changes using a key and offset for complex storage

​
getStateChangesUint

Gets state changes for a storage slot as uint256 values.

// Basic
function getStateChangesUint(
    address target,
    bytes32 slot
) internal view returns (uint256[] memory)

// With mapping
function getStateChangesUint(
    address target,
    bytes32 slot,
    uint256 key
) internal view returns (uint256[] memory)

// With mapping and offset
function getStateChangesUint(
    address target,
    bytes32 slot,
    uint256 key,
    uint256 offset
) internal view returns (uint256[] memory)

Similar helper functions exist for:

  • getStateChangesAddress: Convert to address values
  • getStateChangesBool: Convert to boolean values
  • getStateChangesBytes32: Get raw bytes32 values

Each of these functions follows the same pattern with basic, mapping, and mapping-with-offset variants.

​
Triggers

Triggers determine when your assertion functions will be executed. You can register different types of triggers in your assertion’s triggers() function.

Use triggers to make sure that assertions are only called when they are needed in order to save gas and resources. For example, instead of triggering an assertion on every call to a contract, you can trigger it only on specific function calls that are able to change the state of the specific value you are asserting on.

​
Call Triggers

Call triggers execute your assertion when specific contract calls occur.

// Trigger on any call to the contract
// Note: It is not recommended to use this trigger as it will trigger the assertion on every call to the contract
// This can be expensive and inefficient
function registerCallTrigger(
    bytes4 assertionFnSelector
) internal view

// Trigger on specific function calls
function registerCallTrigger(
    bytes4 assertionFnSelector,
    bytes4 triggerSelector
) internal view

Example:

function triggers() external view override {
    // Run assertion on ALL calls to the contract
    registerCallTrigger(this.checkAllCalls.selector);
    
    // Run assertion only on transfer calls
    registerCallTrigger(
        this.checkTransfer.selector,
        IERC20.transfer.selector
    );
}

​
Storage Triggers

Storage triggers execute your assertion when contract storage changes.

Using forge inspect <ContractName> storage-layout is an easy way to get the storage layout of a contract. This can be used to determine the storage slot of a specific variable to use in the cheatcode.

// Trigger on ANY storage slot change
// Note: It is not recommended to use this trigger as it will trigger the assertion on every storage slot change
// This can be expensive and inefficient
function registerStorageChangeTrigger(
    bytes4 assertionFnSelector
) internal view

// Trigger on changes to a specific storage slot
function registerStorageChangeTrigger(
    bytes4 assertionFnSelector,
    bytes32 slot
) internal view

Example:

function triggers() external view override {
    // Run assertion on ANY storage change
    registerStorageChangeTrigger(this.checkAllStorage.selector);
    
    // Run assertion when totalSupply slot changes
    registerStorageChangeTrigger(
        this.checkSupply.selector,
        TOTAL_SUPPLY_SLOT
    );
}

​
Balance Triggers

Executes assertion on ETH balance changes.

function registerBalanceChangeTrigger(
    bytes4 assertionFnSelector
) internal view

​
Combining Triggers

Triggers can be combined for comprehensive coverage:

function triggers() external view override {
    // Multiple triggers for one assertion
    registerStorageChangeTrigger(this.mainInvariant.selector);
    registerCallTrigger(this.mainInvariant.selector);
    
    // Different assertions for different events
    registerBalanceChangeTrigger(this.checkBalances.selector);
    registerCallTrigger(
        this.checkCalls.selector,
        IERC20.transfer.selector
    );
}

​
Helpers

​
getAssertionAdopter

Get assertion adopter contract address associated with the assertion triggering transaction.

function getAssertionAdopter() external view returns (address);

This cheat code allows for not defining an assertion adopter contract in the assertion contract constructor.

The cheat code is only available in the triggers() function and the assertion functions. It cannot be used in the constructor since assertion contracts have no state during deployment.