!grants_badge

Subscan Essentials

!CI/CD

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
• Quick Start

• Docker Deployment
• Helm Chart Deployment
• Testing
• Contributing
• License
• Resources

Features

• Substrate Integration

• Extensibility

• APIs

Quick Start

Prerequisites

• Linux/macOS
• Git
• Go 1.26.10 (matching go.mod and Docker)
• Redis 3.0.4+
• MySQL 8.0+ or PostgreSQL 16+

Installation

./build.sh build

Validation

CI uses Go 1.26.10 and fresh MySQL/Redis services in .github/workflows/docker.yaml. Tests reset database tables and Redis keys; use a disposable subscan_test database and Redis instance when running them locally. After copying configs/config.yaml.example to configs/config.yaml and setting the MYSQL_ and REDIS_ environment variables for those services, run:

go build ./...
go test -mod=mod -p 1 -timeout 90s -v ./...
make lint

The serial package setting prevents the existing integration suites from resetting shared test data concurrently. make lint pins golangci-lint 2.12.2; an existing binary can be selected with GOLANGCI_LINT=/absolute/path/to/golangci-lint.

React UI Configuration

Subscan Essentials supports a React-based UI for a modern frontend experience. The React UI repository is available at subscan-essentials-ui-react.

Prerequisites

• Node.js 24.22.1 (matching the UI repository runtime)
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/subscan-explorer/subscan-essentials-ui-react.git
cd subscan-essentials-ui-react

1. Install dependencies:

nvm install
nvm use
npm ci --no-audit --no-fund

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 port
    timeout: 30s       # http timeout 
database:
  mysql:
    api: "mysql://root:[email protected]:3306?writeTimeout=3s&parseTime=true&loc=Local&charset=utf8mb4,utf8" # mysql default dsn
  postgres:
    api: "host=localhost user=gorm password=gorm dbname=gorm port=9920 sslmode=disable" # postgres default dsn
redis:
  proto: tcp
  addr: 127.0.0.1:6379 # redis host
  password: "" # redis password
  read_timeout: 1s 
  write_timeout: 1s
  idle: 10
  active: 100
UI:
  enable_substrate: true # if true, ui will show substrate data
  enable_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

• 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

testing

1. Create test database (if using MySQL):

CREATE DATABASE subscan-essentials;

1. 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