blockscout/docs

BlockScout

Blockchain Explorer for inspecting and analyzing EVM Chains.

BlockScout provides a comprehensive, easy-to-use interface for users to view, confirm, and inspect transactions on all EVM (Ethereum Virtual Machine) blockchains. This includes the Ethereum main and test networks as well as Ethereum forks and sidechains.

Following is an overview of the project and instructions for getting started.

Visit the POA BlockScout forum for additional deployment instructions, FAQs, troubleshooting, and other BlockScout related items. You can also post and answer questions here.

You can also access the dev chatroom on our Gitter Channel.

About BlockScout

BlockScout is an Elixir application that allows users to search transactions, view accounts and balances, and verify smart contracts on the entire Ethereum network including all forks and sidechains.

Currently available block explorers (i.e. Etherscan and Etherchain) are closed systems which are not independently verifiable. As Ethereum sidechains continue to proliferate in both private and public settings, transparent tools are needed to analyze and validate transactions.

Features

• Open source development: The code is community driven and available for anyone to use, explore and improve.

• Real time transaction tracking: Transactions are updated in real time - no page refresh required. Infinite scrolling is also enabled.

• Smart contract interaction: Users can read and verify Solidity smart contracts and access pre-existing contracts to fast-track development. Support for Vyper, LLL, and Web Assembly contracts is in progress.

• Token support: ERC20 and ERC721 tokens are supported. Future releases will support additional token types including ERC223 and ERC1155.

• User customization: Users can easily deploy on a network and customize the Bootstrap interface.

• Ethereum sidechain networks: BlockScout supports the Ethereum mainnet, Ethereum testnets, POA network, and forks like Ethereum Classic, xDAI, additional sidechains, and private EVM networks.

Supported Projects

Hosted Mainnets	Hosted Testnets	Additional Chains using BlockScout
Aerum	Goerli Testnet	ARTIS
Callisto	Kovan Testnet	Ether-1
Ethereum Classic	POA Sokol Testnet	Fuse Network
Ethereum Mainnet	Rinkeby Testnet	Oasis Labs
POA Core Network	Ropsten Testnet	Petrichor
RSK		PIRL
xDai Chain		SafeChain
		SpringChain
		Kotti Testnet

Visual Interface

Interface for the POA network updated 02/2019

Umbrella Project Organization

This repository is an umbrella project. Each directory under apps/ is a separate Mix project and OTP application, but the projects can use each other as a dependency in their mix.exs.

Each OTP application has a restricted domain.

Directory	OTP Application	Namespace	Purpose
apps/ethereum_jsonrpc	:ethereum_jsonrpc	EthereumJSONRPC	Ethereum JSONRPC client. It is allowed to know Explorer's param format, but it cannot directly depend on :explorer
apps/explorer	:explorer	Explorer	Storage for the indexed chain. Can read and write to the backing storage. MUST be able to boot in a read-only mode when run independently from :indexer, so cannot depend on :indexer as that would start :indexer indexing.
apps/block_scout_web	:block_scout_web	BlockScoutWeb	Phoenix interface to :explorer. The minimum interface to allow web access should go in :block_scout_web. Any business rules or interface not tied directly to Phoenix or Plug should go in :explorer. MUST be able to boot in a read-only mode when run independently from :indexer, so cannot depend on :indexer as that would start :indexer indexing.
apps/indexer	:indexer	Indexer	Uses :ethereum_jsonrpc to index chain and batch import data into :explorer. Any process, Task, or GenServer that automatically reads from the chain and writes to :explorer should be in :indexer. This restricts automatic writes to :indexer and read-only mode can be achieved by not running :indexer.

Getting Started

Requirements

Dependency	Mac	Linux
Erlang/OTP 21.0.4	brew install erlang	Erlang Install Example
Elixir 1.8.1	☝️	Elixir Install Example
Postgres 10.3	brew install postgresql	Postgres Install Example
Node.js 10.x.x	brew install node	Node.js Install Example
Automake	brew install automake	Automake Install Example
Libtool	brew install libtool	Libtool Install Example
Inotify-tools	Not Required	Ubuntu - apt-get install inotify-tools
GCC Compiler	brew install gcc	GCC Compiler Example
GMP	brew install gmp	Install GMP Devel

Build and Run

Playbook Deployment

We use Ansible & Terraform to build the correct infrastructure to run BlockScout. See https://github.com/poanetwork/blockscout-terraform for details and instructions.

Manual Deployment

See Manual BlockScout Deployment for instructions.

Environment Variables

Our forum contains a full list of BlockScout environment variables.

Configuring EVM Chains

• CSS: Update the import instruction in apps/block_scout_web/assets/css/theme/_variables.scss to select a preset css file. This is reflected in the production-${chain} branch for each instance. For example, in the production-xdai branch, it is set to @import "dai-variables".

• ENV: Update the environment variables to match the chain specs.

Automating Restarts

By default blockscout does not restart if it crashes. To enable automated restarts, set the environment variable HEART_COMMAND to whatever command you run to start blockscout. Configure the heart beat timeout to change how long it waits before considering the application unresponsive. At that point, it will kill the current blockscout instance and execute the HEART_COMMAND. By default a crash dump is not written unless you set ERL_CRASH_DUMP_SECONDS to a positive or negative integer. See the heart documentation for more information.

CircleCI Updates

To monitor build status, configure your local CCMenu with the following url: https://circleci.com/gh/poanetwork/blockscout.cc.xml?circle-token=f8823a3d0090407c11f87028c73015a331dbf604

Testing

Requirements

• PhantomJS (for wallaby)

Running the tests

1. Build the assets. cd apps/block_scout_web/assets && npm run build; cd -

2. Format the Elixir code. mix format

3. Run the test suite with coverage for whole umbrella project. This step can be run with different configuration outlined below. mix coveralls.html --umbrella

4. Lint the Elixir code. mix credo --strict

5. Run the dialyzer. mix dialyzer --halt-exit-status

6. Check the Elixir code for vulnerabilities. cd apps/explorer && mix sobelow --config; cd - cd apps/block_scout_web && mix sobelow --config; cd -

7. Lint the JavaScript code. cd apps/block_scout_web/assets && npm run eslint; cd -

8. Test the JavaScript code. cd apps/block_scout_web/assets && npm run test; cd -

Parity

Mox

This is the default setup. mix coveralls.html --umbrella will work on its own, but to be explicit, use the following setup:

export ETHEREUM_JSONRPC_CASE=EthereumJSONRPC.Case.Parity.Mox
export ETHEREUM_JSONRPC_WEB_SOCKET_CASE=EthereumJSONRPC.WebSocket.Case.Mox
mix coveralls.html --umbrella --exclude no_parity

HTTP / WebSocket

export ETHEREUM_JSONRPC_CASE=EthereumJSONRPC.Case.Parity.HTTPWebSocket
export ETHEREUM_JSONRPC_WEB_SOCKET_CASE=EthereumJSONRPC.WebSocket.Case.Parity
mix coveralls.html --umbrella --exclude no_parity

Protocol	URL
HTTP	http://localhost:8545
WebSocket	ws://localhost:8546

Geth

Mox

export ETHEREUM_JSONRPC_CASE=EthereumJSONRPC.Case.Geth.Mox
export ETHEREUM_JSONRPC_WEB_SOCKET_CASE=EthereumJSONRPC.WebSocket.Case.Mox
mix coveralls.html --umbrella --exclude no_geth

HTTP / WebSocket

export ETHEREUM_JSONRPC_CASE=EthereumJSONRPC.Case.Geth.HTTPWebSocket
export ETHEREUM_JSONRPC_WEB_SOCKET_CASE=EthereumJSONRPC.WebSocket.Case.Geth
mix coveralls.html --umbrella --exclude no_geth

Protocol	URL
HTTP	https://mainnet.infura.io/8lTvJTKmHPCHazkneJsY
WebSocket	wss://mainnet.infura.io/ws/8lTvJTKmHPCHazkneJsY

API Documentation

To view Modules and API Reference documentation:

1. Generate documentation. mix docs
2. View the generated docs. open doc/index.html

Front-end

Javascript

All Javascript files are under apps/block_scout_web/assets/js and the main file is app.js. This file imports all javascript used in the application. If you want to create a new JS file consider creating into /js/pages or /js/lib, as follows:

js/lib

This folder contains all scripts that can be reused in any page or can be used as a helper to some component.

js/pages

This folder contains the scripts that are specific for some page.

Redux

This project uses Redux to control the state in some pages. There are pages that have things happening in real-time thanks to the Phoenix channels, e.g. Address page, so the page state changes a lot depending on which events it is listening. The redux is also used to load some contents asynchronous, see async_listing_load.js.

To understand how to build new pages that need redux in this project, see the redux_helpers.js

Internationalization

The app is currently internationalized. It is only localized to U.S. English. To translate new strings.

1. To setup translation file. cd apps/block_scout_web; mix gettext.extract --merge; cd -
2. To edit the new strings, go to apps/block_scout_web/priv/gettext/en/LC_MESSAGES/default.po.

Metrics

BlockScout is setup to export Prometheus metrics at /metrics.

Prometheus

1. Install prometheus: brew install prometheus
2. Start the web server iex -S mix phx.server
3. Start prometheus: prometheus --config.file=prometheus.yml

Grafana

1. Install grafana: brew install grafana
2. Install Pie Chart panel plugin: grafana-cli plugins install grafana-piechart-panel
3. Start grafana: brew services start grafana
4. Add Prometheus as a Data Source
   1. open http://localhost:3000/datasources
   2. Click "+ Add data source"
   3. Put "Prometheus" for "Name"
   4. Change "Type" to "Prometheus"
   5. Set "URL" to "http://localhost:9090"
   6. Set "Scrape Interval" to "10s"
5. Add the dashboards from https://github.com/deadtrickster/beam-dashboards: For each *.json file in the repo.
   1. open http://localhost:3000/dashboard/import
   2. Copy the contents of the JSON file in the "Or paste JSON" entry
   3. Click "Load"
6. View the dashboards. (You will need to click-around and use BlockScout for the web-related metrics to show up.)

Tracing

Blockscout supports tracing via Spandex. Each application has its own tracer, that is configured internally to that application. In order to enable it, visit each application's config/<env>.ex and update its tracer configuration to change disabled?: true to disabled?: false. Do this for each application you'd like included in your trace data.

Currently, only Datadog is supported as a tracing backend, but more will be added soon.

DataDog

If you would like to use DataDog, after enabling Spandex, set "DATADOG_HOST" and "DATADOG_PORT" environment variables to the host/port that your Datadog agent is running on. For more information on Datadog and the Datadog agent, see their documentation.

Other

If you want to use a different backend, remove the SpandexDatadog.ApiServer Supervisor.child_spec from Explorer.Application and follow any instructions provided in Spandex for setting up that backend.

Memory Usage

The work queues for building the index of all blocks, balances (coin and token), and internal transactions can grow quite large. By default, the soft-limit is 1 GiB, which can be changed in apps/indexer/config/config.exs:

config :indexer, memory_limit: 1 <<< 30

Memory usage is checked once per minute. If the soft-limit is reached, the shrinkable work queues will shed half their load. The shed load will be restored from the database, the same as when a restart of the server occurs, so rebuilding the work queue will be slower, but use less memory.

If all queues are at their minimum size, then no more memory can be reclaimed and an error will be logged.

Acknowledgements

We would like to thank the EthPrize foundation for their funding support.

Contributing

See CONTRIBUTING.md for contribution and pull request protocol. We expect contributors to follow our code of conduct when submitting code or comments.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.