ETH Block Scanner

• Directory Structure
• TODOs

TLDR;

The simplest steps to run the application using docker-compose:

• Create an .env file, having the following variables defined:
  • NODE_URL (required), Websocket RPC URL of Ethereum node
  • RETENTION_BLOCKS (defaults to 50)
  • API_PORT (defaults to 8080)
• Run docker compose up
• Browse http://localhost:8080/ (adjust the port according to the config) for GraphQL Playground.

Running tests

Runing make gotest will execute all the unit tests in all the packages in the repository.

Building

As containers

Both the API and Scanner binaries are containerized as a Dockerfile with 3 image targets:

• builder: An intermediate image for building the binaries
• api: API server executable
• scanner: Block scanner's executable

Two executable targets (api and scanner) are standalone images that can be run as containers. To build the images:

• make api.Dockerfile for building the API server container, with eth-block-scanner/api image tag by default.
• make scanner.Dockerfile for building the Block scanner container, with eth-block-scanner/scanner image tag by default.

As binaries

Alternative to the container distributions, the components (API and Scanner) can be built locally and run by the executable binaries.

• make bin/api for building the API server executable at bin/api
• make bin/scanner for building the Block Scanner executable at bin/scanner

The two Makefile targets implicitly downloads the necessary Go dependencies (see make godown) and generates synthetic Go files (see make gogen).

Running

The application (the both components, api and scanner) parses environment variables as configuration parameters during boot. So the environment variables listed below need to be present on runtime: (See example.env)

• DATABASE_URL (for api and scanner): Connection URL to the shared database instance with write access for scanner and read access for api instances.
• NODE_URL (for scanner): Websocket RPC URL of the ETH node for the scanner to fetch the blocks.
• RETENTION_BLOCKS (for scanner): Number of the recent blocks to be persisted in the db, older blocks will be pruned.
• API_URL (for api): The TCP port to serve the HTTP (GraphQL API and Playground) requests.

Using Docker Compose

The docker-compose.yml file provides the ready-to run setup for the whole application.

• Runs postgres container as the shared database instance.
  • The databaes schema is prepared using the database/schema.sql file as an initialization script.
• Runs scanner container as the Block Scanner instance.
• Runs api container as the API server instance.

Note: The compose setup does NOT need the images being built as it is configured to build from the Dockerfile when needed.

To run the services up: docker compose up

(or in the background: docker compose up -d)

To stop the services: docker compose stop

To remove the containers: docker compose down

Docker Compose supports .env files, so it is possible to create an .env file for specifying the required config parameters for the services under the same directory of the compose file.

Note: The compose setup overrides DATABASE_URL parameter accordingly to the preconfigured database instance.

Manual deployment

To run the application independently without using the docker-compose, it is needed to run a Postgres instance and apply the schema from the database/schema.sql script.

Then, depending on the preference wheter running as container or local binary, follow the instructions on sections Building As containers or As binaries.

Hint: Running the components with the config parameters from .env files: env $(cat .env | xargs) ./bin/api (or ... ./bin/scanner).