{"id":13720461,"url":"https://github.com/Alethio/ethereum-lite-explorer","last_synced_at":"2025-05-07T12:31:28.444Z","repository":{"id":41390215,"uuid":"159354912","full_name":"Alethio/ethereum-lite-explorer","owner":"Alethio","description":"Alethio's Light Weight Open Source Ethereum Explorer","archived":false,"fork":false,"pushed_at":"2023-01-04T18:32:51.000Z","size":10721,"stargazers_count":259,"open_issues_count":29,"forks_count":125,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-11-14T09:39:15.775Z","etag":null,"topics":["blockchain-explorer","ethereum","ethstats-lite","web3js"],"latest_commit_sha":null,"homepage":"https://lite-explorer.aleth.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Alethio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-27T15:13:31.000Z","updated_at":"2024-10-27T05:49:01.000Z","dependencies_parsed_at":"2023-02-02T19:45:16.077Z","dependency_job_id":null,"html_url":"https://github.com/Alethio/ethereum-lite-explorer","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alethio%2Fethereum-lite-explorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alethio%2Fethereum-lite-explorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alethio%2Fethereum-lite-explorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alethio%2Fethereum-lite-explorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alethio","download_url":"https://codeload.github.com/Alethio/ethereum-lite-explorer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252876401,"owners_count":21818174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain-explorer","ethereum","ethstats-lite","web3js"],"created_at":"2024-08-03T01:01:04.045Z","updated_at":"2025-05-07T12:31:23.869Z","avatar_url":"https://github.com/Alethio.png","language":"TypeScript","funding_links":[],"categories":["Block Explorers"],"sub_categories":[],"readme":"# Ethereum Lite Explorer by Alethio\nThe **Lite Explorer**  is a client-side only web application that connects directly to a [Ethereum JSON RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC) compatible node.\nThis means you can have your own private Ethereum Explorer should you wish so.\nNo need for servers, hosting or trusting any third parties to display chain data.\n\n[![CircleCI](https://circleci.com/gh/Alethio/ethereum-lite-explorer.svg?style=svg)](https://circleci.com/gh/Alethio/ethereum-lite-explorer)\n[![Docker](https://images.microbadger.com/badges/version/alethio/ethereum-lite-explorer.svg)](https://hub.docker.com/r/alethio/ethereum-lite-explorer \"Get Ethereum Lite Explorer through Docker Hub\")\n\n\u003e **WARNING v1.x.x is a breaking update from previous v0.x.x releases**\n\n\u003e NOTICE\n\u003e Please report any bugs using Github's [issues](https://github.com/Alethio/ethereum-lite-explorer/issues/)\n\n## Contents\n\u003c!-- TOC depthFrom:2 depthTo:4 --\u003e\n\n- [Contents](#contents)\n- [Technical Details](#technical-details)\n    - [Project structure](#project-structure)\n- [Getting started](#getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Configuration](#configuration)\n    - [Running in Docker](#running-in-docker)\n    - [Running in Kubernetes](#running-in-kubernetes)\n    - [Building from source](#building-from-source)\n        - [Deploying the built assets to production](#deploying-the-built-assets-to-production)\n        - [Custom build arguments](#custom-build-arguments)\n    - [Example setups](#example-setups)\n        - [With Memento](#with-memento)\n        - [With Infura](#with-infura)\n        - [With Parity Light Client](#with-parity-light-client)\n        - [With Ganache](#with-ganache)\n        - [With Besu](#with-besu)\n    - [Example Deployments](#example-deployments)\n        - [surge.sh](#surgesh)\n- [How to](#how-to)\n    - [Deploy to a domain sub-path](#deploy-to-a-domain-sub-path)\n    - [Show the network name](#show-the-network-name)\n    - [Link to a custom deployment of EthStats](#link-to-a-custom-deployment-of-ethstats)\n    - [Use a custom ETH currency symbol](#use-a-custom-eth-currency-symbol)\n    - [Show the transactions per account in account page](#show-the-transactions-per-account-in-account-page)\n    - [Override specific text strings (translations)](#override-specific-text-strings-translations)\n    - [Use a custom RPC node authentication method](#use-a-custom-rpc-node-authentication-method)\n\n\u003c!-- /TOC --\u003e\n- [Contributing](CONTRIBUTING.md)\n- [License](LICENSE.md)\n\n## Technical Details\n\nThe project is built on a React/MobX and TypeScript stack, using the [Alethio CMS](https://github.com/Alethio/cms), which allows us to add extensions dynamically through 3rd party plugins.\nThe basic functionality of the explorer is implemented via a series of open-source [core plugins](https://github.com/Alethio/explorer-core-plugins), which we also use internally for our [aleth.io](https://aleth.io) platform. Please refer to [Alethio CMS](https://github.com/Alethio/cms) for documentation on the plugin system.\n\n### Project structure\n```\n📁ethereum-lite-explorer\n├─📁dev             - dev server for serving the app\n├─📁dist            - target folder for application that contains deployables\n└─📁src             - source files\n  ├─📁app (*1)      - application source code\n  ├─📁assets        - static assets (e.g. images) that will be bundled together with the application\n  └─📁public        - contains static assets that are copied to the dist folder as they are\n\n(*1)\n📁app\n├─📁components      - React components\n├─📁translation     - localized strings\n├─📁util            - application-agnostic utilities. Ideally these would be in a separate repo/package.\n└─📄index.ts         - entry point\n```\n\n## Getting started\n\n### Prerequisites\nPlease make sure you have the following installed and running properly\n- [Node.js](https://nodejs.org/en/download/) \u003e= 8.0 or [Docker](https://www.docker.com/)\n- If building it you will also need NPM \u003e= 6.9 (NPM is distributed with Node.js. For more information see: https://www.npmjs.com/get-npm)\n- A JSON-RPC enabled and accessible Ethereum Client, some examples:\n    * [An Infura Account](#with-infura)\n    * [Parity Light Client](#with-parity-light-client)\n    * [Ganache](#with-ganache)\n    * [Besu Dev Mode](#with-besu) - private chain example\n- 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.\n\n### Configuration\n\nThe application requires a JSON configuration file which is loaded at runtime but with different approaches for `development` vs `production` environments.\n\nFor `development` the config file is called `config.dev.json` located in the root of the repository.\nAs for the `production` environment the config file is copied in the `dist` folder and renamed to `config.json`.\n\nThe `dist` is the target folder for the built application that needs to be served by an HTTP server.\n\nHere are 3 sample config files as starting point.\n\n| Config name | Description |\n| --- | --- |\n| config.default.json | Default configuration file which contains the core plugins of the app that are enough to run the explorer. |\n| config.ibft2.json | Configuration file that has the default core plugins plus an extra one useful for [IBFT2 based chains](https://pegasys.tech/another-day-another-consensus-algorithm-why-ibft-2-0/) that decodes the extraData field of a block. |\n| config.memento.json | Configuration file that has the default core plugins plus the memento plugins to use the Memento API as a data source |\n\nThe possibility to change the URL of the RPC enabled Ethereum node is done through the `eth-lite` core plugin.\nSee the [`nodeUrl`](https://github.com/Alethio/ethereum-lite-explorer/blob/master/config.default.json#L16) attribute for the plugin which has the default value set to `https://mainnet.infura.io/`.\n\nFor advanced configuration editing, please refer to the [Alethio CMS documentation](https://github.com/Alethio/cms)\n\n### Running in Docker\nYou can run the Lite Explorer in Docker by using the already published images on [Docker Hub](https://hub.docker.com/r/alethio/ethereum-lite-explorer).\nThe config file in the Docker images have the default values from the `config.default.json` sample file.\nBy default it will connect to `https://mainnet.infura.io/`.\n\nThe simplest command to run it is\n```sh\n$ docker run -p 80:80 alethio/ethereum-lite-explorer\n```\nwhich 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](http://localhost) in your browser and use it.\n\nThere are 2 env vars that can be passed in at runtime:\n\n| ENV var | Description |\n|---|---|\n| APP_NODE_URL | URL of RPC enabled node. (e.g. `https://host:port`, also supports Basic Auth by prepending `user:pass@` to the `host`). This overrides in the config file the `nodeUrl` attribute of the `eth-lite` core plugin. |\n| APP_BASE_URL | It is used ONLY in `index.html` for `og:tags` (e.g. `https://my.app.tld`). Overrides build time defined value. |\n\nFor example if you want to connect to your node on localhost with all default configs run the following command:\n```sh\n$ docker run -p 80:80 -e APP_NODE_URL=\"http://localhost:8545\" alethio/ethereum-lite-explorer\n```\nIf more customization is needed, a full configuration file can be mounted in the application root (e.g. in the `/usr/share/nginx/html` folder).\n```sh\n$ docker run -p 80:80 -v /your-config-dir/config.json:/usr/share/nginx/html/config.json alethio/ethereum-lite-explorer\n```\n### Running in Kubernetes\nYou can deploy the Lite Explorer in Kubernetes using the following steps:\n- `cd .kubernetes`\n- Run `./deploy.sh` to deploy, uses `config.default.json` as config.\n- Use for example `./deploy.sh ../config.memento.json` to select other config files.\n- Run `./remove.sh` to remove\n\n\n### Building from source\nClone the explorer in a folder of your choosing\n```sh\n$ git clone https://github.com/Alethio/ethereum-lite-explorer.git\n$ cd ethereum-lite-explorer\n```\n\n**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.\n\nInstall npm packages\n```sh\n$ npm install\n```\n\nCopy the sample config file\n```sh\n$ cp config.default.json config.dev.json\n```\nMake 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](#configuration)\n\nTo start the development build run the following command:\n```sh\n$ npm run watch\n```\n\nThis terminal will be kept open, as the above command continuously watches the source files for changes and triggers an incremental build on every change.\n\nAlternatively, to build the minified version (used also for `production`) use:\n```sh\n$ npm run build\n```\n\nSince the app is using the Alethio CMS for using the core plugins the next step is to install them:\n```sh\n$ npm i -g @alethio/cms-plugin-tool\n$ acp install --dev \\\n    @alethio/explorer-plugin-eth-common \\\n    @alethio/explorer-plugin-eth-lite \\\n    @alethio/explorer-plugin-eth-memento \\\n    @alethio/explorer-plugin-3box\n```\n\nIf 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:\n```sh\n$ acp install --dev @alethio/explorer-plugin-eth-ibft2\n```\n\nThe above command `acp` installs the plugins in the `dist` folder. Basically they will be copied, together with the base app.\n\n**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.\n\nFinally, you can start the local Explorer development server with\n```sh\n$ npm start\n```\n\n#### Deploying the built assets to production\n\nWhen building from source, you are responsible for setting up your own production environment. There are two available options: you can either start from our existing Dockerfile found in the root of the repo and customize that, or you can use your own custom solution.\n\nFor a custom deployment, first make sure you have built the Explorer distributables for production, using `npm run build`. Assuming you already have a web server, such as Nginx, you will need to copy everything from the `dist/` folder to the public folder of the web server (e.g. /usr/share/nginx/html). Then, in the same target folder you need a valid `config.json` file. Note the filename, which is different from the development version. You can use the `config.*.json` from the root of the repo as templates. Make sure to also fill in the `nodeUrl` in the `eth-lite` plugin config section. Lastly, make sure that your web server redirects all routes to the `index.html` to enable HTML5 routing. You can refer to `.docker/nginx.conf` as an example.\n\n#### Custom build arguments\n\nThe following env vars can be passed when building from source:\n\n| ENV var | Description |\n|---|---|\n| APP_BASE_URL | It is used ONLY in `index.html` for `og:tags` (e.g. `https://my.app.tld`) |\n| APP_BASE_PATH | Enables serving the app on a sub-path instead of the domain root (e.g. `some/path/to/app`). |\n\nExample:\nIf serving the app from `https://my.tld/path/to/app`:\n` $ APP_BASE_URL=\"https://my.tld\" APP_BASE_PATH=\"path/to/app\" npm run build`\n\n### Example setups\n\n#### With Memento\n[Memento](https://github.com/Alethio/memento) is Alethio's open source tool for scraping and indexing Ethereum data from any web3-compatible node.\nThe biggest advantage of using Memento as a data source is the indexed data which allows a faster access as well as the ability to show transactions on the account page.\n\nIf you don't have a Memento environment set up already, follow the instructions [here](https://github.com/Alethio/memento#installation)\n\n\u003e This requires Memento \u003e= v1.1.0\n\n**Easiest way to run with Memento** is to follow the steps from [Running in Docker](#running-in-docker) and mount `config.memento.js` as config file.\n\n**If you want a more customized setup**, follow [Building from source](#building-from-source) and the following steps\n\nBuild the Lite Explorer\n```sh\n$ npm run build\n```\n\nInstall the necessary plugins\n```sh\n$ acp install --dev \\\n    @alethio/explorer-plugin-eth-common \\\n    @alethio/explorer-plugin-eth-memento \\\n    @alethio/explorer-plugin-3box\n```\n\nCopy the config file\n```sh\n$ cp config.memento.json config.dev.json\n```\n\nModify the `apiBasePath` to point to Memento's API and, since we are running in dev mode, remove the version query strings `?v=#.#.#` from the \"plugins\". The \"plugins\" section should look as follows:\n```sh\n\"plugins\": [{\n    \"uri\": \"plugin://aleth.io/eth-common\"\n}, {\n    \"uri\": \"plugin://aleth.io/3box\",\n    \"config\": {\n        \"ipfsUrlMask\": \"https://ipfs.infura.io/ipfs/%s\"\n    }\n}, {\n    \"uri\": \"plugin://aleth.io/eth-memento\",\n    \"config\": {\n        \"apiBasePath\": \"http://localhost:3001/api/explorer\"\n    }\n}],\n```\n\nStart the explorer\n```sh\n$ npm start\n```\n\n#### With Infura\n- [Sign-up](https://infura.io/register) for an account or [sign-in](https://infura.io/login) into your Infura account.\n\n- 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.....`.\n\n- Update `config.dev.json` file and set the `nodeUrl` attribute for the `eth-lite` plugin to your Infura endpoint.\n\nBuild and start Lite Explorer\n```sh\n$ npm run build \u0026\u0026 npm start\n```\n\n####  With Parity Light Client\nThis will allow you to run both your own node and explorer.\nNo third-party dependencies.\nIt 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.\n\n[Install Parity Ethereum](https://wiki.parity.io/Setup) through one of the convenient methods and start it with the `--light` cli flag.\n\nAs a simple step, if you have Docker, you could just run\n\n```sh\n$ docker run -d --restart always --name parity-light -p 127.0.0.1:8545:8545 parity/parity:stable --light --jsonrpc-interface all\n```\n\nUpdate `config.dev.json` file and set the `nodeUrl` attribute for the `eth-lite` plugin to `http://127.0.0.1:8545`.\n\nBuild and start Lite Explorer\n```sh\n$ npm run build \u0026\u0026 npm start\n```\n\n#### With Ganache\nFirst of all, if you do not have it, download and install [Ganache](https://truffleframework.com/ganache) which will give you your own personal test chain.\n\nAfter 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`.\n\nBuild and start Lite Explorer\n```sh\n$ npm run build \u0026\u0026 npm start\n```\n\n#### With Besu\nThis is a great way to use a full featured client, and to see how the explorer works with a private network.\n\nRefer to [Besu Light Explorer HowTo](https://besu.hyperledger.org/en/stable/HowTo/Deploy/Lite-Block-Explorer/ ) to configure your node and explorer.\n\n### Example Deployments\n\n#### surge.sh\nSurge.sh is a simple, single-command web publishing service that you can use to deploy your own version of the Lite Explorer.\n\nMake sure you have set a proper and accessible `APP_NODE_URL` environment variable.\n\n```sh\n# copy and edit a config file\n$ cp config.default.json config.json\n# install surge\n$ npm install --global surge\n# build explorer\n$ npm run build\n# go to build dir\n$ cd dist\n# make push state work as it should\n$ cp ../config.json config.json \u0026\u0026 cp index.html 200.html\n# deploy\n$ surge\n```\n\n## How to\n\n### Deploy to a domain sub-path\n\nThis case is supported only when building from source. You will have to pass the `APP_BASE_PATH` env variable to the build command. See [Custom build arguments](#custom-build-arguments) for reference and examples.\n\n### Show the network name\n\nYou can use our predefined module that shows the current network and an optional switch for navigating to other deployments/networks. To use this module, just add the following in `config.json`:\n\n```jsonc\n{\n    // ...\n    \"pages\": [\n        // ...\n        {\n            \"def\": \"page://aleth.io/dashboard\",\n            \"children\": {\n                \"content\": [\n                    {\n                        \"def\": \"module://aleth.io/dashboard/network\",\n                        \"options\": {\n                            \"networkName\": \"MyTestNet\",\n                            // This is optional\n                            \"otherNetworks\": [\n                                { \"name\": \"Ethereum MainNet\", \"url\": \"https://aleth.io\" }\n                            ]\n                        }\n                    },\n                    // ...\n                ]\n            }\n        }\n    ]\n}\n```\n\n### Link to a custom deployment of EthStats\n\nIf you have a custom deployment of our [EthStats](https://github.com/Alethio/ethstats-network-dashboard) product, you can easily link to it from the main app toolbar using the predefined module. You'll have to edit `config.json` as shown below:\n\n```jsonc\n{\n    \"plugins\": [{\n        \"uri\": \"plugin://aleth.io/eth-common?v#.#.#\",\n        \"config\": {\n            // ...\n            \"ethstatsUrl\": \"https://ethstats.io\"\n        }\n    }],\n    // ...\n    \"rootModules\": {\n        \"toolbarTop\": [\n            // ...\n            { \"def\": \"module://aleth.io/toolbar/ethstats\" }\n        ],\n        // ...\n    }\n}\n```\n\n### Use a custom ETH currency symbol\n\nIf you are deploying for a private or test net, you can customize the main currency symbol by editing the config:\n\n\n```jsonc\n{\n    \"plugins\": [{\n        \"uri\": \"plugin://aleth.io/eth-lite?v#.#.#\",\n        \"config\": {\n            // ...\n            \"ethSymbol\": \"GöETH\"\n        }\n    }]\n}\n```\n### Show the transactions per account in account page\n\nThis module requires `@alethio/explorer-plugin-eth-memento` and access to call the api of a memento lite pipeline deployment.\nEdit the config:\n\n```jsonc\n{\n    \"plugins\": [{\n        \"uri\": \"plugin://aleth.io/eth-memento?v#.#.#\",\n        \"config\": {\n            \"ethSymbol\": \"GoETH\",\n            \"apiBasePath\": \"http://memento-api.example/api/explorer\"\n        }\n    }]\n}\n```\n\nAnd add the module to account page:\n\n```jsonc\n{\n    \"pages\": [{\n        \"def\": \"page://aleth.io/account\",\n        \"children\": {\n            // ...\n            \"bottom\": [\n                { \"def\": \"module://aleth.io/memento/account/txs\" }\n                // ...\n            ]\n        }\n    }]\n}\n```\n\nIf you want to use Memento as a full backend replacement (recommended), see the [With Memento](#with-memento) section.\n\n### Override specific text strings (translations)\n\nYou can customize texts for each plugin by overriding the corresponding translation keys in the plugin's configuration:\n\n```jsonc\n{\n    \"plugins\": [{\n        \"uri\": \"plugin://aleth.io/eth-lite?v#.#.#\",\n        \"config\": {\n            //...\n        },\n        \"translations\": {\n            \"en-US\": {\n                \"dashboardView.title\": \"My Private Network Explorer\"\n            }\n        }\n    }]\n}\n```\n\nYou can refer to individual translation keys in the core plugins repo. Follow [this link](https://github.com/Alethio/explorer-core-plugins/tree/master/src/app/eth-lite/translation) for the eth-lite plugin translations and [this one](https://github.com/Alethio/explorer-core-plugins/tree/master/src/app/eth-common/translation) for eth-common plugin translations.\n\n### Use a custom RPC node authentication method\n\nIf your RPC node requires a custom authentication step (e.g. Besu), the `eth-lite` plugin supports initialization hooks for the purpose of injecting authorization headers into the web3 instance. You will need to create a plugin that handles the authentication steps (e.g. collects credentials via a login form or 3rd party page redirect). The plugin will export a data adapter returning an object that follows the [IAuthStore](https://github.com/Alethio/explorer-core-plugins/blob/master/src/app/eth-lite/IAuthStore.ts) interface definition. The public URI for that adapter is passed to the `eth-lite` plugin config via the [authStoreUri](https://github.com/Alethio/explorer-core-plugins/blob/master/src/app/eth-lite/EthLitePluginConfig.ts#L14) key. This will pause the initialization of the `eth-lite` plugin until the authentication is handled.\n\nCheck out this Besu plugin as an example: https://www.npmjs.com/package/@adetante/explorer-besu-plugin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlethio%2Fethereum-lite-explorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAlethio%2Fethereum-lite-explorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlethio%2Fethereum-lite-explorer/lists"}