diff --git a/PROJECT.md b/PROJECT.md index 5da2413..7afd0a7 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -1,5 +1,12 @@ # ETHEREUMJS CLIENT - PROJECT SUMMARY +NOTE: +**This document is OUTDATED** and will be rewritten at some point in time. For the moment please refer to our communication channels on information on the state of client development. + +The EthereumJS Team, 2020-06-01 + +--- + ## MAIN FOCUS Main goal of this project is to develop an Ethereum main net light client as well diff --git a/README.md b/README.md index ad1464e..89a9242 100644 --- a/README.md +++ b/README.md @@ -5,21 +5,16 @@ [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) [![Gitter](https://img.shields.io/gitter/room/ethereum/ethereumjs.svg?style=flat-square)](https://gitter.im/ethereum/ethereumjs) -This is the work repository for the EthereumJS main chain client implementation project. -This is a community project. See [Development Stages](./PROJECT.md#development-stages) for idea -about the current project status, [issues](https://github.com/ethereumjs/ethereumjs-client/issues) -for open issues and a project layout and read through [Community Project](./PROJECT.md#community-project) -if you want to join. +This is the work repository for the EthereumJS client project targetting both Node.js and the browser as a platform. See [Technical Guidelines](#technical-guidelines) if you directly want to dive into development info. -Current development stage: ``CONCEPT ANALYSIS / EARLY DEVELOPMENT`` +Current development stage: ``EARLY DEVELOPMENT`` # PROJECT SUMMARY -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](./PROJECT.md). +Project summary from [this document](./PROJECT.md) is currently outdated. Please refer to our communication channels for some information on the current state of client development. # TECHNICAL GUIDELINES @@ -66,7 +61,15 @@ for all output or something more targeted by listing the loggers like DEBUG=devp2p:rlpx,devp2p:eth,-babel [CLIENT_START_COMMAND] ``` -**Example 1: Light sync** +## API + +[API Reference](./docs/API.md) + +See also this [diagram](./client_diagram.png) with an overview of the client structure together with the initialization and message flow. + +## EXAMPLES + +### Example 1: Light sync In this example, we will run two ethereumjs-clients. The first will be a fast sync client that will connect to the rinkeby network and start downloading the blockchain. The second will be a @@ -97,7 +100,7 @@ ethereumjs --syncmode light --network rinkeby --datadir second --transports libp Notice that we have to run the second client on port 50506 using the ``multiaddrs=/ip4/0.0.0.0/tcp/50506`` libp2p option to avoid port conflicts. -**Example 2: Light sync from within a browser** +### Example 2: Light sync from within a browser In this example, we will again perform a light sync by connecting to the first client from above. However, this time we will connect directly to the first client from within a browser window using libp2p websockets. @@ -123,44 +126,6 @@ ethereumjs.run({ network: 'rinkeby', syncmode: 'light', bootnodes: '/ip4/127.0.0 That's it! Now, you should start seeing headers being downloaded to the local storage of your browser. Since IndexDB is being used, even if you close and re-open the browser window, the headers you'll already downloaded will be saved. -## API - -[API Reference](./docs/API.md) - -## Environment / Ecosystem - -**EthereumJS 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](https://github.com/ethereumjs/ethereumjs-block), [ethereumjs-vm](https://github.com/ethereumjs/ethereumjs-vm), the -[merkle-patricia-tree](https://github.com/ethereumjs/merkle-patricia-tree) or the -[ethereumjs-devp2p](https://github.com/ethereumjs/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](https://github.com/ethereumjs/ethereumjs-devp2p/issues/19) -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: - -- [Show external issues](https://github.com/search?utf8=%E2%9C%93&q=org%3Aethereumjs+label%3Aethereumjs-client&type=Issues&ref=advsearch&l=&l=) - -**Basic Environment** - -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. - -- ``Node.js`` -- ``Javascript`` (ES6) -- [Tape](https://github.com/substack/tape) for testing -- [Istanbul/nyc](https://istanbul.js.org/) for test coverage -- [standard.js](https://standardjs.com/) for linting/code formatting - ## Design **Goals** @@ -239,24 +204,16 @@ also make use of subclasses of the ``Fetcher`` class that help fetch headers and - ``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. -## Contribution Guidelines -**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. - -**Branch Structure** +## Environment / Ecosystem -Development will take place via feature branches being merged against a protected ``master`` -branch. Always develop on branch also when being on your own fork, use meaningful branch -names like ``new-debug-cl-option`` or ``fixed-this-really-annoying-bug``. +**EthereumJS Ecosystem** -**Testing** +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](https://github.com/ethereumjs/ethereumjs-block), [ethereumjs-vm](https://github.com/ethereumjs/ethereumjs-vm), the +[merkle-patricia-tree](https://github.com/ethereumjs/merkle-patricia-tree) or the +[ethereumjs-devp2p](https://github.com/ethereumjs/ethereumjs-devp2p) implementation. Work needs to be done both within this repos and related libraries. -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. +Related issues are labelled with the ``ethereumjs-client`` label, see [here](https://github.com/search?utf8=%E2%9C%93&q=org%3Aethereumjs+label%3Aethereumjs-client&type=Issues&ref=advsearch&l=&l=) for an org-wide search. ## EthereumJS diff --git a/client_diagram.png b/client_diagram.png new file mode 100644 index 0000000..d27c83b Binary files /dev/null and b/client_diagram.png differ