pyrevm Python Bindings

pyrevm supports state management through checkpoints. You can take a snapshot() of the current state and later revert(checkpoint) to that state. Alternatively, you can use commit() to clear all existing checkpoints.

Note: Unlike the Rust implementation, the Python library does not automatically commit to the database.

from pyrevm import EVM

evm = EVM()
checkpoint = evm.snapshot()
evm.message_call(
    caller=...,
    to=...,
    value=...,
)
evm.revert(checkpoint)  # or: evm.commit() to clear all checkpoints

To install the project and run the test suite locally, use the provided Makefile commands.

make install
make test

The project uses Maturin for Rust/Python FFI. Use the following commands to build the library:

• make build: Build for development.
• make build-prod: Build for production (recommended to avoid performance degradation).
• make test: Run the test suite.

make build
# or for production
make build-prod

The EVM class provides a mechanism to checkpoint the state and revert to it later using JournalCheckpoint objects.

1. snapshot(): Creates a checkpoint of the current journaled state. Returns a JournalCheckpoint object.
2. revert(checkpoint): Reverts the EVM state to the state captured in the provided checkpoint. Raises PyOverflowError if no checkpoint exists or PyKeyError if the checkpoint is invalid.
3. commit(): Commits the current journaled state changes to the underlying database.

# Example: Snapshot, execute, and revert
checkpoint = evm.snapshot()

# ... perform state-changing operations ...

evm.revert(checkpoint)
# State is now back to what it was at the snapshot

You can initialize an EVM instance by providing a fork_url to fork from a remote Ethereum node (e.g., Infura). This allows you to simulate transactions against real mainnet state. You can also configure the environment using Env and BlockEnv to set specific block parameters like timestamp.

from pyrevm import EVM, Env, BlockEnv

address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"  # vitalik.eth
address2 = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
fork_url = "https://mainnet.infura.io/v3/c60b0bb42f8a4c6481ecd229eddaca27"

# set up an evm
evm = EVM(
    fork_url=fork_url,
    tracing=True,
    env=Env(
        block=BlockEnv(timestamp=100)
    )
)

# Execute a transaction via message_call
evm.message_call(
    caller=address,
    to=address2,
    value=10000
)

To enable tracing during EVM execution, pass tracing=True when initializing the EVM instance.

from pyrevm import EVM

EVM(tracing=True)

The Env class is the top-level container for the EVM state, composing three distinct environment components: CfgEnv (configuration), BlockEnv (block parameters), and TxEnv (transaction parameters). You can initialize it by passing these components or use the default values.

To create a new environment, use Env(cfg, block, tx) where each argument is optional.

# Example of creating an Env with custom components
cfg = CfgEnv(chain_id=1)
block = BlockEnv(number=U256('12345'))
tx = TxEnv(caller='0x...', value=U256('100'))
env = Env(cfg, block, tx)

Perform a message_call to a specific address. This simulates a call from a caller to a to address with optional calldata, value, gas, and gas_price.

Parameters:

• caller: The address making the call.
• to: The target address.
• calldata (optional): The bytes to be sent.
• value (optional): The amount of Ether to send.
• gas (optional): The gas limit for the call.
• gas_price (optional): The gas price.
• is_static: Boolean indicating if the call should be treated as a static call.

# Example: Call a function on a contract
calldata = b"\x0a\x00\x00\x00..."
result = evm.message_call(
    caller="0x1234567890123456789012345678901234567890",
    to="0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    calldata=calldata,
    value=10**18,
    gas=100000
)

Use the following methods to inspect the state of the EVM:

• basic(address): Returns an AccountInfo object for the given address.
• get_code(address): Returns the contract bytecode at the address as bytes, or None if no code exists.
• storage(address, index): Returns the U256 value stored at a specific storage slot (index) for the given address.
• get_balance(address): Returns the U256 balance of the given address.
• block_hash(number): Returns the hash of the block at the specified number as bytes.

# Example: Check contract storage
slot = 0x0
value = evm.storage("0xContractAddress", slot)
print(f"Value at slot {slot}: {value}")

# Example: Get balance
balance = evm.get_balance("0xUserAddress")

When a transaction emits events, you can inspect them using the Log class. Each Log object provides access to the event's metadata and payload.

Available properties:

• address: The address of the contract that emitted the log (as a String).
• topics: A list of log topics (as Strings).
• data: Returns a tuple containing (topics, data).
  • topics: A list of PyBytes objects representing the topics.
  • data: A PyBytes object representing the raw log data.