The Lite Explorer is a client-side only web application that connects directly to a Ethereum JSON RPC compatible node. This means you can have your own private Ethereum Explorer should you wish so. No need for servers, hosting or trusting any third parties to display chain data.

WARNING v1.x.x is a breaking update from previous v0.x.x releases

NOTICE Please report any bugs using Github's issues

• Technical Details
  • Project structure
• Getting started
  • Prerequisites
  • Configuration
  • Running in Docker
  • Setup/Build Instructions
  • Example setups
    • With Infura
    • With Parity Light Client
    • With Ganache
    • With Pantheon
  • Example Deployments
    • surge.sh
• Contributing
• License

The project is built on a React/MobX and TypeScript stack, using the Alethio CMS, which allows us to add extensions dynamically through 3rd party plugins. The basic functionality of the explorer is implemented via a series of open-source core plugins, which we also use internally for our aleth.io platform. Please refer to Alethio CMS for documentation on the plugin system.

📁ethereum-lite-explorer
├─📁dev             - dev server for serving the app
├─📁dist            - target folder for application that contains deployables
└─📁src             - source files
  ├─📁app (*1)      - application source code
  ├─📁assets        - static assets (e.g. images) that will be bundled together with the application
  └─📁public        - contains static assets that are copied to the dist folder as they are

(*1)
📁app
├─📁components      - React components
├─📁translation     - localized strings
├─📁util            - application-agnostic utilities. Ideally these would be in a separate repo/package.
└─📄index.ts         - entry point

Please make sure you have the following installed and running properly

• Node.js >= 8.0 or Docker
• If building it you will also need NPM >= 6.9 (NPM is distributed with Node.js. For more information see: https://www.npmjs.com/get-npm)
• A JSON-RPC enabled and accessible Ethereum Client, some examples:
  • An Infura Account
  • Parity Light Client
  • Ganache
  • Pantheon Dev Mode - private chain example
• If not using the pre-built Docker images, you will need an HTTP server for serving the app and it must be deployed at the root of the domain/subdomain.

The application requires a JSON configuration file which is loaded at runtime but with different approaches for development vs production environments.

For development the config file is called config.dev.json located in the root of the repository. As for the production environment the config file is copied in the dist folder and renamed to config.json.

The dist is the target folder for the built application that needs to be served by an HTTP server.

Here are 2 sample config files as starting point.

The possibility to change the URL of the RPC enabled Ethereum node is done through the eth-lite core plugin. See the nodeUrl attribute for the plugin which has the default value set to https://mainnet.infura.io/.

For advanced configuration editing, please refer to the Alethio CMS documentation

You can run the Lite Explorer in Docker by using the already published images on Docker Hub. The config file in the Docker images have the default values from the config.default.json sample file. By default it will connect to https://mainnet.infura.io/.

The simplest command to run it is

$ docker run -p 80:80 alethio/ethereum-lite-explorer

which will start a container on port 80 of your computer with a nginx embedded to serve the pre-build explorer. You can now open localhost in your browser and use it.

There are 2 env vars that can be passed in at runtime:

For example if you want to connect to your node on localhost with all default configs run the following command:

$ docker run -p 80:80 -e APP_NODE_URL="http://localhost:8545" alethio/ethereum-lite-explorer

If more customization is needed, a full configuration file can be mounted in the application root (e.g. in the /usr/share/nginx/html folder).

$ docker run -p 80:80 -v /your-config-dir/config.json:/usr/share/nginx/html/config.json alethio/ethereum-lite-explorer

Clone the explorer in a folder of your choosing

$ git clone https://github.com/Alethio/ethereum-lite-explorer.git
$ cd ethereum-lite-explorer

IMPORTANT: Make sure you are using npm 6.9+ for the next step. Older versions will NOT work due to alias feature usages introduced in npm 6.9.

Install npm packages

$ npm install

Copy the sample config file

$ cp config.default.json config.dev.json

Make necessary modifications into config.dev.json if needed. For development, you must also remove the version query strings ?v=#.#.# from the "plugins" URIs. Full list of configuration options available here

To start the development build run the following command:

$ npm run watch

This terminal will be kept open, as the above command continuously watches the source files for changes and triggers an incremental build on every change.

Alternatively, to build the minified version (used also for production) use:

$ npm run build

Since the app is using the Alethio CMS for using the core plugins the next step is to install them:

$ npm i -g @alethio/cms-plugin-tool
$ acp install --dev \
    @alethio/explorer-plugin-eth-common \
    @alethio/explorer-plugin-eth-lite \
    @alethio/explorer-plugin-3box

If you need other custom plugins like for example to decode the extraData field of a block for the IBFT2 based networks, you can install them at this step:

$ acp install --dev @alethio/explorer-plugin-eth-ibft2

The above command acp installs the plugins in the dist folder. Basically they will be copied, together with the base app.

IMPORTANT: Whenever you use npm run build or npm run build-dev the dist folder is emptied, thus the plugins are also deleted and they need to be reinstalled.

Finally, you can start the explorer with

$ npm start

• Sign-up for an account or sign-in into your Infura account.

• From the control panel, obtain your endpoint url for the network you are interested in (mainnet, ropsten, kovan, rinkeby). It will looks similar to https://mainnet.infura.io/v3/aa11bb22cc33......

• Update config.dev.json file and set the nodeUrl attribute for the eth-lite plugin to your Infura endpoint.

Build and start Lite Explorer

$ npm run build && npm start

This will allow you to run both your own node and explorer. No third-party dependencies. It will be slower to browse older data because it is fetching it real time from other ethereum peer nodes but it's fast to sync and low in resource usage.

Install Parity Ethereum through one of the convenient methods and start it with the --light cli flag.

As a simple step, if you have Docker, you could just run

$ docker run -d --restart always --name parity-light -p 127.0.0.1:8545:8545 parity/parity:stable --light --jsonrpc-interface all

Update config.dev.json file and set the nodeUrl attribute for the eth-lite plugin to http://127.0.0.1:8545.

Build and start Lite Explorer

$ npm run build && npm start

First of all, if you do not have it, download and install Ganache which will give you your own personal test chain.

After setting up and starting Ganache, update the config.dev.json file and set the nodeUrl attribute for the eth-lite plugin to http://127.0.0.1:7545.

Build and start Lite Explorer

$ npm run build && npm start

This is a great way to use a full featured client, and to see how the explorer works with a private network.

First of all, if you do not have it, download and install Pantheon stable release.

To get started, run a Pantheon node with the HTTP and WebSockets JSON-RPC services enabled, allowing traffic from all hosts and CORS origins:

$ pantheon --host-whitelist="*" --rpc-http-cors-origins="*" --rpc-http-enabled --rpc-http-host=0.0.0.0 --rpc-ws-enabled --rpc-ws-host=0.0.0.0

(Note: using "*" values for host whitelist and CORS origins is not a recommended way to run a production node securely, this configuration is intended for test or developement purpose only. For more information about these options, refer to the Pantheon CLI reference).

After running Pantheon, update the config.dev.json file, and set the nodeUrl attribute for the eth-lite plugin to http://127.0.0.1:8545.

Build and start Lite Explorer

$ npm run build && npm start

Surge.sh is a simple, single-command web publishing service that you can use to deploy your own version of the Lite Explorer.

Make sure you have set a proper and accessible APP_NODE_URL environment variable.

# copy and edit a config file
$ cp config.default.json config.json
# install surge
$ npm install --global surge
# build explorer
$ npm run build
# go to build dir
$ cd dist
# make push state work as it should
$ cp ../config.json config.json && cp index.html 200.html
# deploy
$ surge