This is the work repository for the EthereumJS main chain client implementation project. This is a community project. See Development Stages for idea about the current project status, issues for open issues and a project layout and read through Community Project if you want to join.
See Technical Guidelines if you directly want to dive into development info.
Current development stage:
CONCEPT ANALYSIS / EARLY DEVELOPMENT
For a summary of the project focus, some outline of a roadmap and information on the team and how to contribute/join see this document.
Installing the Client
npm install -g ethereumjs-client
Running the Client
Some building blocks for the client have already been implemented or outlined to further build upon.
You can run the current state of the client with:
ethereumjs --network=mainnet [--loglevel=debug]
Or show the help with
If you want to have verbose logging output for the p2p communication you can use...
for all output or something more targeted by listing the loggers like
Environment / Ecosystem
This project will be embedded in the EthereumJS ecosystem and many submodules already exist and can be used within the project, have a look e.g. at ethereumjs-block, ethereumjs-vm, the merkle-patricia-tree or the ethereumjs-devp2p implementation.
To play well together within a client context, many sub module libraries need enhancements, e.g. to create a common logging context. There are also larger building blocks still missing, e.g. the Node Discovery V5 p2p implementation being necessary for a proper working light client sync. Due to the distributed nature of EthereumJS there will be internal (to be done in this repo) and external issues (to be done in other EthereumJS repos) to be worked on.
All (hopefully :-)) issues referring to the client implementation will be provided with a
ethereumjs-client label which should be discoverable with a label search on GitHub:
For library development the following basic environment is targeted. Some base requirements like the testing tool arise from the need of maintaining a somewhat unified EthereumJS environment where developers can switch between with some ease without the need to learn (too much) new tooling.
- Tape for testing
- Istanbul/nyc for test coverage
- standard.js for linting/code formatting
Contributors should aim to achieve the following goals when making design decisions:
- Loosely coupled components: Components should require as little knowledge of the definitions of other components as possible. This reduces dependencies between PRs and encourages contributors to work in parallel. It also improves extensibility of the code as new features like sharding and libp2p support are added.
- Easily tested: The design should make testing of individual components as easy as possible. This goes hand in hand with the previous goal of loose coupling.
- Readable code: More readable code should encourage more contributions from the community and help with bug fixing.
- Well documented: Similar to above, this will help both contributors and users of the project.
We will now briefly describe the directory structure and main components of the Ethereumjs client to help contributors better understand how the project is organized.
/binContains the CLI script for the
/docsContains auto-generated API docs as well as other supporting documentation
/lib/netContains all of the network layer classes including
Protocoland its subclasses,
Serverand its subclasses, and
/lib/serviceContains the various services. Currently, only
/lib/rpcContains the RPC server (optionally) embedded in the client.
/lib/syncContains the various chain synchronizers. Currently, only
/testsContains test cases, testing helper functions, mocks and test data
Chain[In Progress] This class represents the blockchain and is a wrapper around
ethereumjs-blockchain. It handles creation of the data directory, provides basic blockchain operations and maintains an updated current state of the blockchain, including current height, total difficulty, and latest block.
BlockPool[In Progress] This class holds segments of the blockchain that have been downloaded from other peers. Once valid, sequential segments are available, they are automatically added to the blockchain
HeaderPool[In Progress] This is a subclass of
BlockPoolthat holds header segments instead of block segments. It is useful for light syncs when downloading sequential headers in parallel.
ServerThis class represents a server that discovers new peers and handles incoming and dropped connections. When a new peer connects, the
Serverclass will negotiate protocols and emit a
connectedevent with a new
Peerinstance. The peer will have properties corresponding to each protocol. For example, if a new peer understands the
ethprotocol, it will contain an
ethproperty that provides all
ethprotocol methods (for example:
RlpxServer[In Progress] Subclass of
Serverthat implements the
Libp2pServer[Not Started] Subclass of
Serverthat implements the
PeerRepresents a network peer. Instances of
Peerare generated by the
Serversubclasses and contain instances of supported protocol classes as properties. Instances of
Peersubclasses can also be used to directly connect to other nodes via the
connect()method. Peers emit
messageevents whenever a new message is received using any of the supported protocols.
RlpxPeer[In Progress] Subclass of
Peerthat implements the
Libp2pPeer[Not Started] Subclass of
Peerthat implements the
Protocol[In Progress] This class and subclasses provide a user-friendly wrapper around the low level ethereum protocols such as
les/2. Subclasses must define the messages provided by the protocol.
EthProtocol[In Progress] Implements the
LesProtocol[In Progress] Implements the
ShhProtocol[Not Started] Implements the whisper protocol.
PeerPool[In Progress] Represents a pool of network peers.
removedevents when new peers are added and removed and also emit the
messageevent whenever any of the peers in the pool emit a message. Each
Servicehas an associated
PeerPooland they are used primarily by
Synchronizers to help with blockchain synchronization.
SynchronizerSubclasses of this class implements a specific blockchain synchronization strategy. They also make use of subclasses of the
Fetcherclass that help fetch headers and bodies from pool peers.
FastSynchronizer[Not Started] Implements fast syncing of the blockchain
LightSynchronizer[In Progress] Implements light syncing of the blockchain
Servicewill implement specific functionality of a
Node. For example, the
EthServicewill synchronize the blockchain using the fast or light sync protocols. Each service must specify which protocols it needs and define a
EthService[In Progress] Implementation of an ethereum fast sync and light sync node.
ShhService[Not Started] Implementation of an ethereum whisper node.
Node[In Progress] Represents the top-level ethereum node, and is responsible for managing the lifecycle of included services.
RPCManager[In Progress] Implements an embedded JSON-RPC server to handle incoming RPC requests.
Communication This is distributed team effort. If you plan to take on larger issues always pre-announce your work intention on the issue page and drop a short note on what you are planning to do. If there is no issue for the stuff you want to work on create one and describe the problem and outline the intended implementation before start working.
Development will take place via feature branches being merged against a protected
branch. Always develop on branch also when being on your own fork, use meaningful branch
No meaningful new PR will be accepted without associated tests (exceptions might be done on a case-by-case basis). Test coverage should not increase (significantly) by a new PR. You might also want to consider writing your tests first and then directly push them, since this would be a good starting point for discussing the scope/implementation of a feature.