Lux Explorer

Overview

Lux Explorer is a Blockscout-based block explorer for browsing transactions, contracts, tokens, and network activity across the Lux ecosystem. It is an Elixir/OTP umbrella application forked from Blockscout v10.0.1, extended with multi-chain compose files, Lux branding, and per-network JSON configuration for LUX, Zoo, SPC, Hanzo, and testnet deployments.

Repository: github.com/luxfi/explorer License: GPL-3.0

Technology Stack

Architecture

Umbrella Apps

The project is an OTP umbrella with 6 apps under apps/:

Database Schema

318 Ecto migrations from 20180117 through 20260305. Core tables include:

• addresses, blocks, transactions, logs, internal_transactions
• tokens, token_transfers, address_current_token_balances
• smart_contracts (verified sources with ABI)
• Chain-specific modules: Arbitrum, Optimism, ZkSync, Beacon, Celo, Filecoin, Polygon zkEVM

Supported Chain Types

The CHAIN_TYPE build arg / env var selects chain-specific modules at compile time:

• Default (EVM-compatible)
• optimism -- L2 deposits, withdrawals, output roots
• arbitrum -- L2 batches, cross-chain messages
• polygon_zkevm -- ZK proofs, batches
• zksync -- ZK batches, reader
• filecoin -- Filecoin-specific
• celo -- Celo-specific
• blackfort -- BlackFort-specific

Supported Networks

Chain Configurations (configs/chains/)

Compose Files

Per-network compose files bring up backend, frontend, visualizer, sig-provider, and stats:

Multi-Chain All-In-One (docker-compose.all-chains.yml)

Brings up C-Chain (Blockscout) plus Go indexers for all native chains:

• C-Chain: Blockscout backend on port 4000, frontend on port 3000
• Native chains: ghcr.io/luxfi/indexer image for A, B, P, Q, T, X, Z chains (ports 4100-4700)
• Shared visualizer (8050), sig-provider (8051)

Microservices (docker-compose/services/)

Backend, DB, frontend, NFT media handler, Nginx, Redis, sig-provider, smart-contract-verifier, stats, user-ops-indexer, visualizer.

Core Concepts

RPC Integration

The EthereumJSONRPC app connects to Lux nodes via SubnetEVM-compatible endpoints:

ETHEREUM_JSONRPC_HTTP_URL = http://<luxd>:9650/ext/bc/<blockchain-id>/rpc
ETHEREUM_JSONRPC_WS_URL   = ws://<luxd>:9650/ext/bc/<blockchain-id>/ws
ETHEREUM_JSONRPC_VARIANT  = geth

Each Lux subnet chain has a unique blockchain ID (e.g., dnmzhuf6poM6PUNQCe7MWWfBdTJEnddhHRNXz2x7H6qSmyBEJ for LUX mainnet C-Chain).

Branding

Custom branding lives in branding/ (logos, favicon) and is applied via:

1. Dockerfile.luxfi -- extends official Blockscout image with logo overlays and env defaults
2. Environment variables -- FOOTER_LOGO, FOOTER_CHAT_LINK, FOOTER_GITHUB_LINK

API Surface

• REST API v2: /api/v2/ (blocks, transactions, addresses, tokens, stats)
• GraphQL: Absinthe-based (/graphql), with Relay-compatible pagination
• WebSocket: Phoenix PubSub for real-time block/transaction updates
• Prometheus: /metrics endpoint via prometheus_plugs

Key Dependencies

Embedded Go Indexers (indexers/)

A small Go module (github.com/luxfi/explorer-indexers, Go 1.24.0) inside the explorer repo provides native-chain indexer code for non-EVM chains (A, B, P, Q, T, X, Z). These are lightweight companions to the full Go indexer at github.com/luxfi/indexer.

Dependencies: gorilla/mux 1.8.1, gorilla/websocket 1.5.4, lib/pq 1.11.2.

Development

Prerequisites

• Elixir 1.19+, Erlang/OTP 27+
• PostgreSQL 14+
• Node.js 16+ (for frontend)
• Running Lux node (luxd) with SubnetEVM

Build

# Fetch deps and compile
mix deps.get
mix compile

# Create and migrate database
mix ecto.create
mix ecto.migrate

# Start development server
mix phx.server

Docker

# Build Lux-branded image
docker build -f docker/Dockerfile.luxfi .

# Or from scratch
docker build -f docker/Dockerfile \
  --build-arg CHAIN_TYPE="" \
  --build-arg RELEASE_VERSION=10.0.1 \
  -t luxfi/explorer:latest .

# Run a network
docker compose -f compose.luxnet.yml up -d

Tests

# Run all tests (umbrella-wide)
mix test --no-start

# Run specific app tests
cd apps/explorer && mix test
cd apps/block_scout_web && mix test

Environment Variables

Key variables (see docker-compose/envs/common-blockscout.env):

File Structure

explorer/
  apps/
    block_scout_web/     # Phoenix web app (API + UI)
    ethereum_jsonrpc/    # JSON-RPC client library
    explorer/            # Data layer (Ecto schemas, 318 migrations)
    indexer/             # Data fetchers (blocks, txs, tokens, traces)
    nft_media_handler/   # NFT media processing (S3, eVision)
    utils/               # Shared utilities
  branding/              # Lux logos and favicon
  config/                # Elixir config (dev/test/prod/runtime)
  configs/chains/        # Per-network JSON config (lux, zoo, spc, lux-testnet)
  compose.*.yml          # Per-network Docker Compose files
  docker/                # Dockerfiles (standard + Lux-branded)
  docker-compose/        # Shared compose services and env files
  docker-*-mainnet/      # Per-chain Docker Compose dirs (a/b/p/q/t/x/z/zoo)
  docker-*-testnet/      # Per-chain testnet Docker Compose dirs
  indexers/              # Embedded Go indexers for native chains
  mix.exs                # Umbrella project (Elixir ~> 1.19, v10.0.1)
  Dockerfile             # Root Dockerfile (Node.js 16 for frontend)