py-evm (Python Ethereum Virtual Machine)

Warnings

• breaking The Py-EVM project has been officially archived and is now read-only. No further development, feature additions, or bug fixes are planned by the maintainers. Users should be aware that the library is no longer actively maintained.
  Fix: Consider migrating to actively maintained EVM implementations if ongoing support and new feature compatibility are required. This library is best suited for historical research or specific, isolated use cases related to the Prague fork or earlier.
• breaking Py-EVM's last officially supported Ethereum hard fork is Prague. It does not include support for subsequent hard forks, meaning it cannot accurately simulate or interact with the EVM behavior introduced in newer Ethereum versions.
  Fix: For EVM simulations or interactions with post-Prague Ethereum networks, use an alternative, actively maintained EVM implementation. Py-EVM is limited to the protocol rules up to and including the Prague fork.
• breaking Version 0.8.0-beta.1 removed external dependencies for Proof-of-Work (like `pyethash`, `pysha3`, and `pycryptodome`) and internalized a less performant `ethash` implementation. This change deprioritized PoW consensus logic within Py-EVM.
  Fix: If high-performance Proof-of-Work computations or specific `pyethash`/`pysha3`/`pycryptodome` integrations were part of your workflow, this version (and later) will exhibit slower performance for PoW or require manual re-integration of those libraries/functionalities if needed.
• breaking In version 0.3.0-alpha.13, the consensus mechanism abstraction was significantly refactored. `validate_seal` and `validate_header` methods were changed from classmethods to instance methods, and new `ConsensusAPI` and `ConsensusContextAPI` were introduced.
  Fix: Code that directly interacted with or overrode the `validate_seal` or `validate_header` methods, or that implemented custom consensus logic before this version, will require updates to conform to the new `ConsensusAPI` and `ConsensusContextAPI` interfaces.
• gotcha Py-EVM is a low-level EVM implementation focused on the execution layer. It does not inherently handle the consensus layer (e.g., Proof of Stake networking, block propagation, or peer-to-peer communication) or direct interaction with live Ethereum networks. It is primarily for local simulation and testing of EVM logic.
  Fix: For interacting with live Ethereum networks (Mainnet, testnets), sending transactions, or deploying contracts, a higher-level library like `web3.py` is typically used, which often leverages an EVM client (not `py-evm`) for execution.

Install

• pip install py-evm Install Py-EVM

Imports

• MainnetChain

  from eth.chains.mainnet import MainnetChain

• AtomicDB

  from eth.db.atomic import AtomicDB

• GAS_LIMIT

  from eth.constants import GAS_LIMIT

• to_wei

  from eth_utils import to_wei

• encode_hex

  from eth_utils import encode_hex

• Address

  from eth_typing import Address

Quickstart

This quickstart demonstrates how to initialize a basic Ethereum chain and Virtual Machine (VM) using Py-EVM. It sets up an in-memory database, pre-funds a mock address, and then retrieves the current block number and the balance of the pre-funded address. This provides a minimal runnable example of interacting with Py-EVM's core components for simulating EVM behavior.

import os

from eth import constants
from eth.chains.mainnet import MainnetChain
from eth.db.atomic import AtomicDB
from eth_utils import to_wei, encode_hex
from eth_typing import Address

def run_evm_example():
    # Setup a mock address and initial balance
    MOCK_ADDRESS = Address(b'\x00' * 19 + b'\x01')  # An arbitrary address
    PREFUND_AMOUNT = to_wei(100, 'ether')

    # Initialize a new chain with an atomic database
    # AtomicDB is an in-memory database suitable for tests and examples
    chain = MainnetChain.from_genesis(
        AtomicDB(),
        genesis_state={
            MOCK_ADDRESS: {
                'balance': PREFUND_AMOUNT,
                'nonce': 0,
                'code': b'',
                'storage': {}
            }
        },
        genesis_header_params={
            'gas_limit': constants.GAS_LIMIT,
            'difficulty': 1  # Simplified difficulty for non-PoW chain
        }
    )

    # Get the current VM from the chain
    vm = chain.get_vm()

    print(f"Chain created successfully. Current block number: {vm.get_block().header.block_number}")
    print(f"Balance of {encode_hex(MOCK_ADDRESS)}: {vm.get_balance(MOCK_ADDRESS)} Wei")

    # Example: Accessing a constant
    print(f"Default transaction gas limit: {constants.GAS_LIMIT}")

if __name__ == "__main__":
    run_evm_example()