Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Python beacon chain implementation overview


The Python Ethereum client Trinity is developed by Ethereum Foundation (EF) Python team. To see all the Python tooling for the Ethereum ecosystem, please visit:

Recently, EF Research team is collaborating with Python team to implement the Ethereum 2.0/Serenity beacon chain testnet on Trinity. This document is a snapshot of the overview and the goals Ethereum 2.0/Serenity Python implementation at the beginning of 2019.


Short-term goals

  1. Phase 0 Milestone 1, [M1]: MVP testnet
  2. Supporting cross-client common tests: eth2.0-spec-tests
  3. Verifying the spec logic (Research team, WIP Spec January Release Milestone)

Mid-term goals

  1. Phase 0 Milestone 2, [M2]: March release - the "fully-reflecting-phase-0-spec" testnet
  2. Maintaining eth2.0-spec-tests

Long-term goals

  1. Providing a reference implementation of an Ethereum 2.0 / Serenity beacon node.
  2. Moving on shard node implementation (Phase 1).

Components overview

Unlike other brand new beacon chain clients, Trinity is also an Ethereum 1.0 Proof-of-Work chain client. The beacon chain design adopts the similar abstract architecture, and leave some placeholders for the shard chain design:

From bottom to top:


  • libp2p v.s. RLPx
    • We're planning to use libp2p library to support the transport layer.
  • Sharded Networks Peer management v.s. current Peer Management
    • (Phase 1) The shard block validators have to be shuffled and to be assigned to validate a specific shard of a specific slot. It requires different peer management design for the shard networks.

State Execution: Beacon State Machine v.s. Sharded State Engine v.s. EVM

  • (Phase 0) The beacon chain state represents the consensus of the Ethereum 2.0 validators.
  • (Phase 1) The shard state execution engine will be the new VM that replace EVM to support smart contract execution. Our current most promising candidate is eWASM.

Chain: Beacon Chain v.s. Shard Chain v.s. Proof-of-Work (PoW) Chain

Chain object is the component that represents a blockchain in Py-EVM. Currently, Trinity provides different PoW chains like Mainnet and Ropsten; for beacon chain, we're developing a different class with beacon-chain-specific features; likewise for the shard chain.

Python modules for Serenity developement

eth2 module introduction

The beacon chain implementation is based on the similar architecture of PoW chain module (eth module in Py-EVM repository). The main components includes:


The database interface for storing block data in local storage.


The state machine interface for applying a new block. The principle is that the BeaconState object would have enough context to perform:

state_1 = state_transition_function(state_0, block_1)

Py-EVM abstracts EVM with BaseVM that defines the interfaces, and implements subclasses for the different mainnet forks. For example, FrontierVM inherits VM and represents the VM for Frontier fork; beacon chain has the similar architecture as we implemented SerenityStateMachine as the first fork of beacon chain.

The in-protocol data structures are defined in eth2.beacon.types. If the data fields might be different from the future forks, we can implement a new subclass in the future.


The Chain represents a single blockchain. One chain might fork by the block number setting, or slot number in beacon chain, we call it versioning.

In BeaconChain initialization, a BeaconChainDB will be set in BeaconChain. While processing each block, it will initialize a BeaconStateMachine object via get_state_machine() function, and use this particular BeaconStateMachine to apply state transition of the given block.

Contribution guideline

You can’t perform that action at this time.