The primary use case for Py-EVM is supporting the public Ethereum blockchain.
However, it is architected with a strong focus on configurability and extensibility. Use of Py-EVM for alternate use cases such as private chains, consortium chains, or even chains with fundamentally different VM semantics should be possible without any changes to the core library.
The following abstractions are used to represent the full consensus rules for a Py-EVM based blockchain.
- Chain: High level API for interacting with the blockchain.
- VM: High level API for a single fork within a Chain
- VMState: The current state of the VM, transaction execution logic and the state transition function.
- Message: Representation of the portion of the transaction which is relevant to VM execution.
- Computation: The computational state and result of VM execution.
- Opcode: The logic for a single opcode.
The term Chain is used to encapsulate:
- The state transition function (e.g. VM opcodes and execution logic)
- Protocol rules (e.g. block rewards, header rewards, difficulty calculations, transaction execution)
- The chain data (e.g. Headers, Blocks, Transactions and Receipts)
- The state data (e.g. balance, nonce, code and storage)
- The chain state (e.g. tracking the chain head, canonical blocks)
While a chain is used to wrap these concepts, many of them are actually defined at lower layers such as the underlying Virtual Machines.
Chain object itself is largely an interface and orchestration layer.
Most of the
Chain APIs merely serving as a passthrough to the appropriate
A chain has one or more underlying Virtual Machines or VMs. The chain contains a mapping which defines which VM should be active for which blocks.
The chain for the public mainnet Ethereum blockchain would have a separate VM defined for each fork ruleset (e.g. Frontier, Homestead, Tangerine Whistle, Spurious Dragon, Byzantium).
The term VM is used to encapsulate:
- The state transition function for a single fork ruleset.
- Orchestration logic for transaction execution.
- Block construction and validation.
- Chain data storage and retrieval APIs
VM object loosely mirrors many of the Chain APIs for retrieval of chain
state such as blocks, headers, transactions and receipts. It is also
responsible for block level protocol logic such as block creation and
The term VMState is used to encapsulate:
- Execution context for the VM (e.g.
- The state root defining the current VM state.
- Some block validation
The term Message comes from the yellow paper. It encapsulates the information from the transaction needed to initiate the outermost layer of VM execution.
- Parameters like
The message can be thought of as the VM’s internal representation of a transaction.
The term Computation is used to encapsulate:
- The computational state during VM execution (e.g. memory, stack, gas metering)
- The computational results of VM execution (e.g. return data, gas consumption and refunds, execution errors)
This abstraction is the interface through which opcode logic is implemented.
The term Opcode is used to encapsulate:
- A single instruction within the VM such as the
Opcodes are implemented as TODO