Subscan Essentials

Subscan Essentials is a high-precision blockchain explorer scaffold supporting Substrate-based networks. Developed by the Subscan team and powering subscan.io, it provides:

• Developer-friendly interface
• Standard/custom module parsing
• Extensible plugin system
• Multi-chain compatibility

Table of Contents

• Features
• Monorepo Layout
• Quick Start
  • Prerequisites
  • Installation
  • React UI Configuration
  • Configuration
  • Running Services
• Docker Deployment
• Helm Chart Deployment
• Testing
• Contributing
• License
• Resources

Features

• Substrate Integration
  • Custom type registration (guide)
  • Indexes blocks, extrinsics, events, logs, and EVM data
• Extensibility
  • Custom plugins framework (docs)
  • Auto-generate plugin templates via gen tool
• APIs
  • Built-in HTTP API documentation (docs)

---

Monorepo Layout

• Backend service: repository root
• React UI: ui-react/

Quick Start

Prerequisites

• Linux/macOS
• Git
• Go 1.23+
• Redis 3.0.4+
• MySQL 8.0+ or PostgreSQL 16+

Installation

./build.sh build

React UI Configuration

Subscan Essentials supports a React-based UI for a modern frontend experience. The React UI is included in this monorepo under ui-react/.

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Enter the React UI project:

cd ui-react

2. Install dependencies:

npm install
# or
yarn

Configuration

Add API host environment variable when deployment:

# API endpoint address
NEXT_PUBLIC_API_HOST=http://localhost:4399

Development Server

npm run dev
# or
yarn run dev

Visit http://localhost:3000 to view the UI interface.

Production Build

npm run build
# or
yarn run build

configuration

Init config file

cp configs/config.yaml.example configs/config.yaml

server:
http:
addr: 0.0.0.0:4399 # http api porttimeout: 30s# http timeout database:
mysql:
api: "mysql://root:helloload@127.0.0.1:3306?writeTimeout=3s&parseTime=true&loc=Local&charset=utf8mb4,utf8"# mysql default dsnpostgres:
api: "host=localhost user=gorm password=gorm dbname=gorm port=9920 sslmode=disable"# postgres default dsnredis:
proto: tcpaddr: 127.0.0.1:6379 # redis hostpassword: ""# redis passwordread_timeout: 1swrite_timeout: 1sidle: 10active: 100UI:
enable_substrate: true # if true, ui will show substrate dataenable_evm: true # if true, ui will show evm data

Available Environment Variables

Common

Name	Default Value	Describe
CONF_DIR	../configs	configs path
VERIFY_SERVER	NULL	solidity verify server
SUBSTRATE_ADDRESS_TYPE	0	ss58 address type
SUBSTRATE_ACCURACY	10	native token accuracy
CHAIN_WS_ENDPOINT		websocket endpoint url
NETWORK_NODE	moonbeam	network node name
WORKER_GOROUTINE_COUNT	10	worker goroutine count
ETH_RPC		Evm rpc endpoint

Database

Name	Default Value	Describe
DB_DRIVER	mysql	support mysql/postgres
MYSQL_HOST	127.0.0.1	mysql host
MYSQL_USER	root	mysql user
MYSQL_PASS		mysql password
MYSQL_DB	subscan-essentials	mysql db name
MYSQL_PORT	3306	mysql port
POSTGRES_HOST	127.0.0.1	postgres port
POSTGRES_USER	gorm	postgres user
POSTGRES_PASS	gorm	postgres password
POSTGRES_DB	subscan-essentials	postgres db name
POSTGRES_PORT	9920	postgres port
POSTGRES_SSL_MODE	disable	postgres ssl mode
MAX_DB_CONN_COUNT	200	gorm max db conn count

Redis

Name	Default Value	Describe
REDIS_HOST	127.0.0.1	redis host
REDIS_PORT	6379	redis host port
REDIS_DATABASE	0	redis db
REDIS_PASSWORD		redis password default nil

running-services

• Start DB

Make sure you have started redis and mysql/postgres

• Subscribe

cd cmd && ./subscan start subscribe

• Worker

cd cmd && ./subscan start worker

• Api Server

cd cmd && ./subscan

• Help

NAME:
SUBSCAN - SUBSCAN Backend Service, use -h get help
USAGE:
cmd [global options] command [command options] [arguments...]
VERSION:
2.0
DESCRIPTION:
SubScan Backend Service, substrate blockchain explorer
COMMANDS:
start Start one worker, E.g. subscribe
install Install default database and create default conf file
CheckCompleteness Create blocks completeness
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--conf value (default: "../configs")
--help, -h show help
--version, -v print the version

docker-deployment

Use docker-compose can start projects quickly

Create local network

docker network create app_net

Run mysql and redis container

docker-compose -f docker-compose.db.yml up -d

Run subscan service

docker-compose build
docker-compose up -d

Helm Chart Deployment

Subscan Essentials supports deployment on Kubernetes via the official Helm Chart.

Helm Chart repository: subscan-explorer/subscan-essentials-chart

Add Helm Repository

helm repo add subscan https://subscan-explorer.github.io/subscan-essentials-chart/
helm repo update

Install

helm install subscan-essentials subscan/subscan-essentials-chart -f example/subscan-essentials/values.yaml

Upgrade

helm upgrade subscan-essentials subscan/subscan-essentials-chart -f example/subscan-essentials/values.yaml

Key Configuration Notes

• Supports multi-network (mainnet/testnet) configuration
• Custom images, resources, environment variables, and Ingress domains are supported
• You must have PostgreSQL and Redis services ready, and configure their connection info in values.yaml
• For detailed parameters, refer to the values.yaml example

For more details, please see the Helm Chart repository README

testing

1. Create test database (if using MySQL):

CREATEDATABASEsubscan-essentials;

2. Run tests:

go test -v ./...

contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines. Good first issues are labeled with good first issue.

LICENSE

GPL-3.0

resources

• [SUBSCAN] https://github.com/subscan-explorer
• [scale.go] https://github.com/subscan-explorer/scale.go SCALE codec implementation
• [Darwinia] https://github.com/darwinia-network