lux/docs
2
0
Fork 0
mirror of https://github.com/luxfi/docs.git synced 2026-09-24 00:25:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update explorer, indexer, consensus, ZAP, and SDK documentation

Browse Source
This commit is contained in:
zeekay
2026-04-19 17:06:03 -07:00
parent d0d4b19a8e
commit 3075de3aad
34 changed files with 374 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dockerignore
+9
View File
@@ -0,0 +1,9 @@
node_modules
**/node_modules
**/.next
.git
.env*
.vscode/
.idea/
coverage/
.DS_Store
apps/docs/app/(home)/page.tsx
+1 -1
View File
@@ -68,7 +68,7 @@ const sections: Section[] = [
{ name: 'Operator', desc: 'Kubernetes operator for Lux blockchain infrastructure', href: '/operator' },
{ name: 'Wallet', desc: 'HD wallet with multi-chain, Ledger, and multi-sig support', href: '/wallet' },
{ name: 'Safe', desc: 'Multi-signature wallet for the Lux Network', href: '/safe' },
{ name: 'Explorer', desc: 'Blockscout blockchain explorer for all Lux chains', href: '/explorer' },
{ name: 'Explorer', desc: 'Single-binary omni-chain block explorer for all Lux chains', href: '/explorer' },
{ name: 'Indexer', desc: 'High-performance Go blockchain indexer', href: '/indexer' },
{ name: 'Bootnode', desc: 'Lux Cloud — RPC, WebSocket, Token, and NFT APIs', href: '/bootnode' },
{ name: 'Oracle', desc: 'Optimistic oracle for assertions, disputes, and truth verification', href: '/oracle' },
apps/docs/content/docs/api-reference/info.mdx
+1 -1
View File
@@ -69,7 +69,7 @@ curl -s -X POST --data '{
"rpcProtocolVersion": "28",
"gitCommit": "abc1234",
"vmVersions": {
"avm": "v1.12.0",
"xvm": "v1.12.0",
"evm": "v0.14.0",
"platform": "v1.12.0"
}
apps/docs/content/docs/api-reference/sdk-go.mdx
+1 -1
View File
@@ -22,7 +22,7 @@ github.com/luxfi/sdk/
client/ # High-level API client
info/ # Info API client
platform/ # Platform (P-Chain) API client
avm/ # AVM (X-Chain) API client
xvm/ # XVM (X-Chain) API client
evm/ # EVM (C-Chain) API client
health/ # Health API client
keychain/ # Key management
apps/docs/content/docs/explorer/api.mdx
+27 -20
View File
@@ -4,60 +4,60 @@ description: REST, GraphQL, and WebSocket APIs
icon: FileCode
---
## REST API v2
## REST API
Base URL: `https://api-explore.lux.network/api/v2`
Base URL: `https://api-explore.lux.network/v1/explorer`
### Blocks
```
GET /api/v2/blocks # List blocks
GET /api/v2/blocks/:number_or_hash # Get block
GET /v1/explorer/blocks # List blocks
GET /v1/explorer/blocks/:number_or_hash # Get block
```
### Transactions
```
GET /api/v2/transactions # List transactions
GET /api/v2/transactions/:hash # Get transaction
GET /api/v2/transactions/:hash/logs # Transaction logs
GET /v1/explorer/transactions # List transactions
GET /v1/explorer/transactions/:hash # Get transaction
GET /v1/explorer/transactions/:hash/logs # Transaction logs
```
### Addresses
```
GET /api/v2/addresses/:hash # Address details
GET /api/v2/addresses/:hash/transactions # Address transactions
GET /api/v2/addresses/:hash/token-transfers # Token transfers
GET /api/v2/addresses/:hash/tokens # Held tokens
GET /v1/explorer/addresses/:hash # Address details
GET /v1/explorer/addresses/:hash/transactions # Address transactions
GET /v1/explorer/addresses/:hash/token-transfers # Token transfers
GET /v1/explorer/addresses/:hash/tokens # Held tokens
```
### Tokens
```
GET /api/v2/tokens # List tokens
GET /api/v2/tokens/:address # Token details
GET /api/v2/tokens/:address/transfers # Token transfers
GET /v1/explorer/tokens # List tokens
GET /v1/explorer/tokens/:address # Token details
GET /v1/explorer/tokens/:address/transfers # Token transfers
```
### Smart Contracts
```
GET /api/v2/smart-contracts/:address # Contract details + ABI
POST /api/v2/smart-contracts/:address/verification # Verify contract
GET /v1/explorer/smart-contracts/:address # Contract details + ABI
POST /v1/explorer/smart-contracts/:address/verification # Verify contract
```
### Search
```
GET /api/v2/search?q=... # Search blocks, txs, addresses, tokens
GET /v1/explorer/search?q=... # Search blocks, txs, addresses, tokens
```
### Stats
```
GET /api/v2/stats # Network statistics
GET /api/v2/stats/charts/market # Market chart data
GET /v1/explorer/stats # Network statistics
GET /v1/explorer/stats/charts/market # Market chart data
```
## GraphQL
@@ -71,7 +71,7 @@ Available at the GraphQL playground: `GET /graphql`
## WebSocket
```
WS /api/v2/ws
WS /v1/explorer/ws
```
Subscribe to:
@@ -86,3 +86,10 @@ Subscribe to:
POST /api?module=account&action=txlist&address=0x...
POST /api?module=contract&action=getabi&address=0x...
```
## Health
```
GET /health
GET /metrics
```
apps/docs/content/docs/explorer/backend/architecture.mdx
+33 -30
View File
@@ -1,50 +1,53 @@
---
title: Architecture
description: Elixir OTP umbrella application structure
description: Single-binary Go explorer architecture
---
## Mix Umbrella
## Overview
The backend is a Mix umbrella project with six OTP applications:
The explorer is a single statically-linked Go binary with three concurrent subsystems:
```
explorer/
├── apps/
│ ├── block_scout_web/ # Web API (Phoenix)
│ ├── explorer/ # Core data layer (Ecto)
│ ├── ethereum_jsonrpc/ # RPC client
│ ├── indexer/ # Data fetcher
│ ├── utils/ # Shared utilities
│ └── nft_media_handler/ # NFT media
├── config/ # Configuration
├── docker/ # Docker files
└── mix.exs # Root project
explorer binary
├── Indexer goroutines (one per chain)
│ └── Writes to per-chain SQLite + BadgerDB
├── API server (HTTP)
│ └── Reads from all chain databases
│ └── Serves /v1/explorer/{chain}/* endpoints
└── Replicator (optional)
└── Streams WAL to S3 with PQ encryption
```
## Dependencies
## Per-Chain Storage
Key Elixir packages:
```
{data_dir}/{chain_slug}/
query/indexer.db # SQLite: blocks, txs, tokens, contracts
kv/ # BadgerDB: hash->data, height->block
```
| Package | Version | Purpose |
|---------|---------|---------|
| `phoenix` | 1.7.x | Web framework |
| `absinthe` | 1.5.x | GraphQL |
| `ecto` | 3.x | Database ORM |
| `postgrex` | — | PostgreSQL driver |
| `httpoison` | 2.0 | HTTP client |
| `jason` | — | JSON codec |
| `prometheus` | — | Metrics |
Each chain is isolated. No shared database. Zero write contention.
## Key Packages
| Package | Purpose |
|---------|---------|
| `cmd/explorer/` | CLI entrypoint |
| `evm/` | Full EVM indexer (blocks, txs, tokens, traces, contracts) |
| `evm/api/` | REST API server |
| `evm/api/repository.go` | Database query layer |
| `storage/` | Dual-layer SQLite + BadgerDB |
| `{x,a,b,q,t,z,k}chain/` | Native DAG chain adapters |
| `multichain/` | 100+ external chain indexer |
## Build Process
```bash
# Development
mix deps.get
mix compile
mix phx.server
go run ./cmd/explorer --rpc=...
# Production release
MIX_ENV=prod mix release blockscout
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o explorer ./cmd/explorer
```
The production release creates an OTP release at `/opt/release/blockscout/` that can run without Elixir/Erlang installed (ERTS is bundled).
The binary is fully self-contained. No external runtime, no Redis, no PostgreSQL required.
apps/docs/content/docs/explorer/backend/index.mdx
+25 -24
View File
@@ -1,40 +1,41 @@
---
title: Backend
description: Blockscout-based Elixir/Erlang backend
description: Go single-binary explorer backend
index: true
icon: Server
---
The explorer backend is a Blockscout fork built with Elixir/Erlang OTP. It handles blockchain data indexing, storage, and API serving.
The explorer backend is a single Go binary that handles blockchain indexing, storage, and API serving. The legacy Blockscout Elixir fork is archived at `github.com/luxfi/explorer-v1`.
## OTP Umbrella Apps
## Components
| App | Purpose |
|-----|---------|
| `block_scout_web` | Phoenix web API and endpoints |
| `explorer` | Core chain data and business logic |
| `ethereum_jsonrpc` | JSON-RPC client interface |
| `indexer` | Blockchain data fetcher and indexer |
| `utils` | Shared utilities |
| `nft_media_handler` | NFT media processing |
| Component | Purpose |
|-----------|---------|
| Indexer goroutines | Per-chain data fetching |
| API server | REST, GraphQL, WebSocket endpoints |
| Storage layer | SQLite (query) + BadgerDB (KV) |
| Replication | PQ encrypted WAL streaming to S3 |
## Technology Stack
- **Runtime**: Elixir 1.19.4 + Erlang 27.3.4.6
- **Web**: Phoenix 1.7 + Plug
- **Database**: Ecto + PostgreSQL 14+
- **Cache**: Redis
- **GraphQL**: Absinthe + Relay pagination
- **Crypto**: ex_keccak, ex_secp256k1, ex_eth_bls
- **Docker**: Multi-stage Alpine build
- **Language**: Go 1.26.1
- **Query storage**: SQLite WAL mode (per-chain isolation)
- **KV storage**: BadgerDB v4
- **API**: `/v1/explorer/*` REST + GraphQL + WebSocket
- **Backup**: ML-KEM-768 + X25519 encrypted streaming
- **Docker**: Alpine multi-stage build
## Docker Image
## Build
```bash
docker build -t blockscout:latest \
--build-arg MIX_ENV=prod \
--build-arg RELEASE_VERSION=10.0.1 \
-f docker/Dockerfile .
cd explorer
go build -o explorer ./cmd/explorer
```
Production image: `ghcr.io/luxfi/blockscout-lux`
## Run
```bash
./explorer --rpc=http://localhost:9650/ext/bc/C/rpc
```
Production image: `ghcr.io/luxfi/explorer`
apps/docs/content/docs/explorer/deployment/docker.mdx
+11 -11
View File
@@ -3,16 +3,16 @@ title: Docker
description: Building and running Docker images
---
## Backend Image
## Explorer Image
```bash
cd explorer
docker build -t ghcr.io/luxfi/blockscout-lux:latest \
--build-arg MIX_ENV=prod \
-f docker/Dockerfile .
docker build -t ghcr.io/luxfi/explorer:latest \
--build-arg VERSION=$(git describe --tags) \
-f Dockerfile .
```
Multi-stage build: Elixir compilation → OTP release → Alpine runtime.
Single-stage build: Go compilation -> Alpine runtime. No Elixir, no Redis, no PostgreSQL.
## Frontend Image
@@ -23,20 +23,20 @@ docker build -t ghcr.io/luxfi/explore:latest \
-f Dockerfile .
```
Three-stage build: deps → builder → runner (Node.js Alpine).
Three-stage build: deps -> builder -> runner (Node.js Alpine).
## Docker Compose
```bash
cd explore
cd explorer
docker compose up -d
```
Services:
- `redis` — Cache (redis:alpine)
- `postgres` — Database (ghcr.io/hanzoai/sql)
- `backend` — Blockscout (port 4000)
- `frontend` — Next.js (port 3000)
- `explorer` -- Go backend (port 4000)
- `frontend` -- Next.js (port 3000)
No Redis or PostgreSQL containers needed. SQLite is embedded.
## Production Compose
apps/docs/content/docs/explorer/deployment/index.mdx
+10 -23
View File
@@ -5,17 +5,17 @@ index: true
icon: Rocket
---
The Lux Explorer runs on Kubernetes with Docker containers. Five explorer instances serve different chains from the same codebase, each with its own PostgreSQL database and chain-specific branding.
The Lux Explorer runs on Kubernetes with Docker containers. Five explorer instances serve different chains from the same binary, each with its own SQLite database and chain-specific branding.
## Architecture
```
Traefik Ingress
explore.lux.network -> blockscout-mainnet:4000
explore-zoo.lux.network -> blockscout-zoo:4000
explore-hanzo.lux.network -> blockscout-hanzo:4000
explore-spc.lux.network -> blockscout-spc:4000
explore-pars.lux.network -> blockscout-pars:4000
explore.lux.network -> explorer-mainnet:4000
explore-zoo.lux.network -> explorer-zoo:4000
explore-hanzo.lux.network -> explorer-hanzo:4000
explore-spc.lux.network -> explorer-spc:4000
explore-pars.lux.network -> explorer-pars:4000
```
## Explorer Instances
@@ -32,25 +32,12 @@ Traefik Ingress
| Component | Image |
|-----------|-------|
| Backend (Elixir) | `ghcr.io/luxfi/blockscout-lux` |
| Explorer (Go) | `ghcr.io/luxfi/explorer` |
| Frontend (Next.js) | `ghcr.io/luxfi/explore` |
## Memory Optimization
For small chains, set these environment variables to prevent OOM crashes:
```
INDEXER_DISABLE_COIN_BALANCE_FETCHER=true
INDEXER_DISABLE_BLOCK_REWARD_FETCHER=true
INDEXER_DISABLE_EMPTY_BLOCKS_SANITIZER=true
POOL_SIZE=3
POOL_SIZE_API=2
INDEXER_MEMORY_LIMIT=1gb
```
## Kubernetes Requirements
- Container memory limit: 8Gi per instance
- Deployment strategy: `Recreate` (not `RollingUpdate`)
- PostgreSQL with chain-specific `chain` label on Service selector
- Container memory limit: 2Gi per instance (single Go binary, no PostgreSQL needed)
- Deployment strategy: `RollingUpdate`
- PVC for SQLite data persistence
- TLS via Traefik certResolver with letsencrypt
apps/docs/content/docs/explorer/index.mdx
+7 -12
View File
@@ -5,23 +5,18 @@ index: true
icon: Search
---
The Lux Explorer is a Blockscout-based blockchain explorer with a modern Next.js frontend, customized for the Lux Network ecosystem.
The Lux Explorer is a single-binary omni-chain block explorer with a Next.js frontend, purpose-built for the Lux Network ecosystem. It replaces the legacy Blockscout stack with a unified Go backend.
## Architecture
```
┌──────────────────────────┐ ┌──────────────────────────┐
│ Frontend (Next.js 15) │ │ Backend (Blockscout) │
│ React 19, Chakra UI v3 │────►│ Elixir/Erlang OTP │
│ explore.lux.network │ │ Phoenix + Absinthe │
│ Frontend (Next.js 15) │ │ Backend (Go) │
│ React 19, Chakra UI v3 │────►│ Single binary indexer │
│ explore.lux.network │ │ SQLite + BadgerDB │
└──────────────────────────┘ └────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ PostgreSQL │
│ + Redis Cache │
└────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ luxd (JSON-RPC) │
│ C-Chain + Chains │
└──────────────────────────┘
@@ -41,16 +36,16 @@ The Lux Explorer is a Blockscout-based blockchain explorer with a modern Next.js
| Component | Repository | Technology |
|-----------|-----------|------------|
| Backend | `github.com/luxfi/explorer` | Elixir 1.19, Erlang 27, PostgreSQL |
| Explorer | `github.com/luxfi/explorer` | Go 1.26, SQLite, BadgerDB |
| Frontend | `github.com/luxfi/explore` | Next.js 15, React 19, Chakra UI v3 |
| Indexer | `github.com/luxfi/indexer` | Go 1.26, PostgreSQL, BadgerDB |
| Legacy (archived) | `github.com/luxfi/explorer-v1` | Elixir/Erlang (Blockscout fork) |
## Key Features
- Real-time block and transaction indexing
- Smart contract verification (Solidity)
- Token tracking (ERC20, ERC721, ERC1155)
- REST API v2 + GraphQL + WebSocket subscriptions
- REST API `/v1/explorer/*` + GraphQL + WebSocket subscriptions
- Multi-chain support (5 explorers from one codebase)
- Dark mode default with monochrome theme
- OIDC authentication via hanzo.id
apps/docs/content/docs/explorer/indexer.mdx
+26 -26
View File
@@ -1,43 +1,43 @@
---
title: Indexer Integration
description: Using the Lux Indexer as an alternative backend
description: Using the Lux Indexer as the explorer backend
icon: Database
---
The [Lux Indexer](https://indexer.lux.network) (`github.com/luxfi/indexer`) is a high-performance Go alternative to the Blockscout Elixir backend.
The [Lux Explorer](https://github.com/luxfi/explorer) is a Go single-binary indexer that replaced the legacy Blockscout Elixir backend (now archived at `github.com/luxfi/explorer-v1`).
## API Compatibility
## API Endpoints
The indexer provides Blockscout API v2 compatible endpoints, so the explorer frontend can use either backend:
The explorer serves `/v1/explorer/*` endpoints:
| Endpoint | Blockscout | Lux Indexer |
|----------|-----------|-------------|
| `/api/v2/blocks` | Yes | Yes |
| `/api/v2/transactions` | Yes | Yes |
| `/api/v2/addresses/:hash` | Yes | Yes |
| `/api/v2/tokens` | Yes | Yes |
| `/api/v2/stats` | Yes | Yes |
| GraphQL | Yes | Yes |
| WebSocket | Yes | Yes |
| Endpoint | Supported |
|----------|-----------|
| `/v1/explorer/blocks` | Yes |
| `/v1/explorer/transactions` | Yes |
| `/v1/explorer/addresses/:hash` | Yes |
| `/v1/explorer/tokens` | Yes |
| `/v1/explorer/stats` | Yes |
| GraphQL | Yes |
| WebSocket | Yes |
## Switching Backends
## Frontend Configuration
To use the Lux Indexer instead of Blockscout:
Point the explore frontend to the explorer backend:
```bash
# Frontend .env
NEXT_PUBLIC_API_HOST=http://indexer-api.lux.network
NEXT_PUBLIC_API_HOST=http://api-explore.lux.network
```
No frontend code changes required.
## When to Use Each
## Capabilities
| Use Case | Recommendation |
|----------|---------------|
| Standard EVM explorer | Blockscout (battle-tested) |
| High-performance indexing | Lux Indexer |
| DAG chain indexing (X, A, B, Q, T, Z, K) | Lux Indexer (exclusive) |
| P-Chain indexing | Lux Indexer (exclusive) |
| Multi-chain (100+) | Lux Indexer (exclusive) |
| DeFi protocol indexing | Lux Indexer |
| Capability | Supported |
|------------|-----------|
| EVM indexing (C, Zoo, Hanzo, SPC, Pars) | Yes |
| DAG chain indexing (X, A, B, Q, T, Z, K) | Yes |
| P-Chain indexing | Yes |
| Multi-chain (100+) | Yes |
| DeFi protocol indexing | Yes |
| PQ encrypted backups | Yes |
| White-label | Yes |
apps/docs/content/docs/explorer/quickstart.mdx
+24 -25
View File
@@ -6,20 +6,19 @@ icon: Zap
## Prerequisites
- Docker and Docker Compose
- Go 1.26+ (for backend development)
- Node.js 22+ and pnpm 10+ (for frontend development)
- Elixir 1.19+ and Erlang 27+ (for backend development)
- A running luxd node with JSON-RPC access
## Docker Compose (Fastest)
## Single Binary (Fastest)
```bash
git clone https://github.com/luxfi/explore.git
cd explore
docker compose up -d
git clone https://github.com/luxfi/explorer.git
cd explorer
go run ./cmd/explorer --rpc=http://localhost:9650/ext/bc/C/rpc
```
This starts PostgreSQL, Redis, Blockscout backend, and the Next.js frontend. Open http://localhost:3000.
Open http://localhost:4000. The embedded frontend and SQLite storage start automatically.
## Frontend Only
@@ -39,32 +38,32 @@ pnpm dev
Open http://localhost:3000.
## Backend Only
## Docker
```bash
git clone https://github.com/luxfi/explorer.git
cd explorer
mix deps.get
mix compile
# Set environment
export DATABASE_URL="postgresql://blockscout:blockscout@localhost:5432/explorer"
export ETHEREUM_JSONRPC_HTTP_URL="http://localhost:9650/ext/bc/C/rpc"
export CHAIN_ID=96369
export COIN=LUX
export NETWORK="LUX Network"
mix phx.server
docker run -it \
-e RPC_ENDPOINT=http://host.docker.internal:9650/ext/bc/C/rpc \
-p 4000:4000 \
ghcr.io/luxfi/explorer:latest
```
Backend API available at http://localhost:4000.
## Verify Indexing
```bash
# Check health
curl http://localhost:4000/api/v2/stats
curl http://localhost:4000/health
# Check latest blocks
curl http://localhost:4000/api/v2/blocks
curl http://localhost:4000/v1/explorer/blocks
# Check stats
curl http://localhost:4000/v1/explorer/stats
```
## Multi-Chain (All Lux Chains)
```bash
go run ./cmd/explorer --config=chains.yaml
```
See the [Configuration](/explorer/configuration) page for `chains.yaml` format.
apps/docs/content/docs/index.mdx
+1 -1
View File
@@ -95,7 +95,7 @@ description: Post-quantum secure, multi-consensus blockchain infrastructure
| [Operator](/operator) | Kubernetes operator for Lux infra |
| [Wallet](/wallet) | HD wallet, multi-chain support |
| [Safe](/safe) | Multi-signature wallet |
| [Explorer](/explorer) | Blockscout blockchain explorer |
| [Explorer](/explorer) | Single-binary omni-chain block explorer |
| [Indexer](/indexer) | Multi-chain data indexer |
| [Bootnode](/bootnode) | Lux Cloud RPC and API platform |
| [Cloud](/cloud) | Build apps on Lux Network |
apps/docs/content/docs/indexer/api.mdx
+1 -1
View File
@@ -4,7 +4,7 @@ description: REST v2, GraphQL, WebSocket, and Etherscan-compatible RPC
icon: FileCode
---
## REST API v2 (Blockscout-Compatible)
## REST API
```
GET /api/v2/blocks # List blocks
apps/docs/content/docs/indexer/architecture.mdx
+1 -1
View File
@@ -26,7 +26,7 @@ icon: Layers
| File | Size | Purpose |
|------|------|---------|
| `evm/adapter.go` | 77.5 KB | Full EVM indexer with Blockscout compat |
| `evm/adapter.go` | 77.5 KB | Full EVM indexer |
| `evm/api/server.go` | 32.9 KB | HTTP/WebSocket API server |
| `evm/api/repository.go` | 30.3 KB | Database query layer |
| `storage/unified.go` | 20.8 KB | Unified KV + Query storage |
apps/docs/content/docs/indexer/chains/evm.mdx
+2 -2
View File
@@ -1,6 +1,6 @@
---
title: EVM Chains
description: Full-featured EVM indexer with Blockscout parity
description: Full-featured EVM indexer
---
## Features
@@ -34,4 +34,4 @@ description: Full-featured EVM indexer with Blockscout parity
## API Endpoints
The EVM adapter exposes 40+ Blockscout v2 compatible endpoints. See the [API Reference](/indexer/api) for details.
The EVM adapter exposes 40+ REST endpoints. See the [API Reference](/indexer/api) for details.
apps/docs/content/docs/indexer/explorer.mdx
+12 -17
View File
@@ -6,9 +6,9 @@ icon: Search
The Lux Indexer provides the data layer for the [Lux Explorer](https://explore.lux.network) frontend.
## API Compatibility
## API
The indexer implements the Blockscout API v2 specification, so the explorer frontend can use it as a drop-in replacement for the Blockscout Elixir backend.
The indexer serves `/v1/explorer/*` REST endpoints, GraphQL, and WebSocket subscriptions. The explorer frontend connects to these endpoints directly.
## Switching the Frontend
@@ -20,19 +20,14 @@ NEXT_PUBLIC_API_HOST=http://api-indexer.lux.network
No frontend code changes needed.
## Advantages Over Blockscout
## Capabilities
| Feature | Blockscout (Elixir) | Lux Indexer (Go) |
|---------|-------------------|------------------|
| DAG chain support | No | Yes (7 chains) |
| P-Chain support | No | Yes |
| Multi-chain (100+) | No | Yes |
| DeFi protocol indexing | No | Yes (20+ protocols) |
| Memory usage | Higher | Lower |
| Build time | Slower | Faster |
## When to Use Blockscout
- You need the full Blockscout microservices stack (stats, sig-provider, visualizer)
- You need the admin panel
- You're already running Blockscout infrastructure
| Feature | Supported |
|---------|-----------|
| EVM indexing (5 chains) | Yes |
| DAG chain support (7 chains) | Yes |
| P-Chain support | Yes |
| Multi-chain (100+) | Yes |
| DeFi protocol indexing (20+ protocols) | Yes |
| PQ encrypted backups | Yes |
| White-label | Yes |
apps/docs/content/docs/indexer/index.mdx
+2 -2
View File
@@ -5,7 +5,7 @@ index: true
icon: Database
---
The Lux Indexer is a Go-based blockchain data indexer supporting all 9 Lux native chain types and 100+ external blockchains with Blockscout API v2 compatibility.
The Lux Indexer is a Go-based blockchain data indexer supporting all 9 Lux native chain types and 100+ external blockchains.
## Three Binaries
@@ -27,6 +27,6 @@ The Lux Indexer is a Go-based blockchain data indexer supporting all 9 Lux nativ
- **Language**: Go 1.26.1
- **Storage**: PostgreSQL (production) + SQLite (dev) + BadgerDB (KV)
- **API**: Blockscout v2 compatible REST + GraphQL + WebSocket
- **API**: `/v1/explorer/*` REST + GraphQL + WebSocket
- **DeFi**: Native protocol indexing (AMMs, lending, perps, NFTs, bridges)
- **Image**: `ghcr.io/luxfi/indexer:v0.2.2`
apps/docs/content/docs/indexer/storage.mdx
+1 -1
View File
@@ -20,7 +20,7 @@ icon: HardDrive
## PostgreSQL Schema
Core tables (Blockscout-compatible):
Core tables:
| Table | Description |
|-------|-------------|
apps/docs/content/docs/meta.json
-1
View File
@@ -15,7 +15,6 @@
"liquid",
"---Trading---",
"exchange",
"exchange-sdk",
"dex",
"cex",
"broker",
apps/docs/content/docs/operator/crds.mdx
+1 -1
View File
@@ -72,7 +72,7 @@ spec:
## LuxIndexer
Deploys a blockchain data indexer with PostgreSQL storage and Blockscout v2 API.
Deploys a blockchain data indexer with SQLite storage and `/v1/explorer/*` API.
```yaml
apiVersion: lux.network/v1alpha1
apps/docs/content/docs/post-quantum.mdx
+6 -6
View File
@@ -57,7 +57,7 @@ ML-KEM-768 (formerly CRYSTALS-Kyber) is a **lattice-based** key encapsulation me
- **Security level**: NIST Level 3 (192-bit)
- **Ciphertext size**: ~1.09 KB
- **Public key size**: ~1.18 KB
- **Use in Lux**: TLS key exchange via X25519MLKEM768 hybrid, inter-node communication
- **Use in Lux**: PQ-TLS 1.3 key exchange via X25519MLKEM768 hybrid, inter-node communication. Go 1.26 defaults to ML-KEM-768 for TLS key exchange -- no additional configuration required
### Comparison
@@ -147,15 +147,15 @@ For existing users and applications:
## Quasar Consensus
Lux's Quasar consensus uses a **triple hybrid signature scheme** combining three independent cryptographic families:
Lux's Quasar consensus uses a **triple consensus** signature scheme combining three independent cryptographic families -- classical (BLS) and two post-quantum (Corona + ML-DSA):
| Scheme | Family | Purpose |
|--------|--------|---------|
| BLS (BLS12-381) | Pairing-based | Aggregatable validator signatures for efficient block finalization |
| Corona | Lattice-based | Post-quantum ring signatures for anonymous validator voting |
| ML-DSA-65 | Lattice-based (FIPS 204) | Post-quantum identity binding for validator authentication |
| BLS (BLS12-381) | Pairing-based (classical) | Aggregatable validator signatures for efficient block finalization |
| Corona | Ring-LWE (post-quantum) | Threshold consensus signatures with lattice-based security |
| ML-DSA-65 | FIPS 204 (post-quantum) | Per-validator identity signatures with Module-LWE security |
An attacker must break all three schemes simultaneously to forge a consensus vote. BLS provides efficient aggregation (reducing bandwidth), Corona provides voter privacy (preventing targeted attacks on specific validators), and ML-DSA-65 provides quantum-resistant identity authentication.
All three paths run in parallel via `TripleSignRound1`. A **QuasarCert** is the finality certificate containing a BLS aggregate signature and aggregated PQ proof (Corona + ML-DSA). Blocks are final only when all three certificates verify. An attacker must break ECDL (BLS), Module-LWE (ML-DSA), and Module-SIS (Corona) simultaneously to forge a consensus vote.
## Smart Account PQ Signing
apps/docs/content/docs/reference/lux-consensus.mdx
+33 -24
View File
@@ -5,7 +5,7 @@ description: "Lux Quasar -- Post-Quantum Consensus Engine"
## Overview
Lux Quasar is the consensus engine for the Lux network. It is a unified, leaderless, post-quantum protocol achieving sub-second 2-round finality with dual-certificate security (BLS12-381 aggregate signatures + Corona lattice-based threshold signatures). Quasar runs every chain in the Lux primary network -- Q, C, X, P -- and any dynamically registered chain.
Lux Quasar is the consensus engine for the Lux network. It is a unified, leaderless, post-quantum protocol achieving sub-second 2-round finality with triple-certificate security (BLS12-381 aggregate signatures + Corona lattice-based threshold signatures + ML-DSA-65 identity signatures). All three paths run in parallel via `TripleSignRound1`. Quasar runs every chain in the Lux primary network -- Q, C, X, P -- and any dynamically registered chain.
**This is NOT Snow, Snowball, or Lux BFT.** Quasar is an original consensus protocol built from first principles around Photonic Selection.
@@ -29,7 +29,7 @@ There are two code locations:
| Engine | Type | Location | Purpose | Status |
|--------|------|----------|---------|--------|
| **Quasar** | Hybrid PQ | `protocol/quasar/` + `node/consensus/quasar/` | Primary consensus for all chains. Dual BLS+Corona signatures run in parallel. 2-round finality. | Production |
| **Quasar** | Triple PQ | `protocol/quasar/` + `node/consensus/quasar/` | Primary consensus for all chains. Triple BLS+Corona+ML-DSA signatures run in parallel via `TripleSignRound1`. 2-round finality. | Production |
| **Nova** | Linear chain | `protocol/nova/` | Linear blockchain consensus mode. Wraps the Ray driver with Wave voting. Used for C-Chain and P-Chain style linear progression. | Production |
| **Wave** | Threshold voting | `protocol/wave/` | Core voting mechanism. Samples K peers, collects votes, checks alpha threshold, builds beta confidence. Supports FPC (Fast Probabilistic Consensus) for dynamic thresholds. | Production |
| **Ray** | Linear driver | `protocol/ray/` | Low-level engine that drives Wave voting for linearly-ordered items. Source/Sink pattern. Nova wraps this. | Production |
@@ -42,7 +42,7 @@ There are two code locations:
## Quasar Algorithm -- Detailed Steps
Quasar achieves hybrid quantum finality through parallel execution of classical and post-quantum signature paths. The full algorithm:
Quasar achieves triple quantum finality through parallel execution of classical and post-quantum signature paths (BLS + Corona + ML-DSA). The full algorithm:
### Phase 0: Photonic Selection (Committee Formation)
@@ -61,9 +61,9 @@ Quasar achieves hybrid quantum finality through parallel execution of classical
4. **FPC mode** (optional): Instead of fixed alpha, threshold theta is selected per-phase using a PRF over `[theta_min=0.5, theta_max=0.8]`, making the protocol more resistant to adaptive adversaries.
5. Classical finality typically completes in 600-700ms.
### Phase 2: Dual Certificate Generation (Quantum Finality)
### Phase 2: QuasarCert Generation (Quantum Finality)
Both paths execute **in parallel** immediately after classical decision:
All three paths execute **in parallel** immediately after classical decision (via `TripleSignRound1`):
**BLS Path (fast, classical):**
1. Each validator signs the finality message (blockID + height + timestamp, 48 bytes) with their BLS12-381 key share.
@@ -78,11 +78,16 @@ Both paths execute **in parallel** immediately after classical decision:
4. Requires t-of-n threshold (typically 2/3+1).
5. Corona adds approximately 200-300ms for quantum finality.
**Block is final ONLY when both certificates are valid:**
**ML-DSA Path (quantum-safe, identity proof):**
1. Each validator signs the finality message with their ML-DSA-65 key (FIPS 204).
2. ML-DSA signatures provide per-validator post-quantum identity binding.
3. Aggregated alongside Corona into the PQ proof field of QuasarCert.
**Block is final ONLY when all three certificates are valid:**
```go
type CertBundle struct {
BLSAgg []byte // 96B BLS aggregate signature
PQCert []byte // ~KB Corona threshold signature
PQCert []byte // Aggregated Corona + ML-DSA proof
}
isFinal := verifyBLS(blsAgg, quorum) && verifyPQ(pqCert, quorum)
@@ -129,11 +134,11 @@ For large validator sets, `GroupedEpochManager` splits validators into groups (d
| Security Model | Guarantee |
|----------------|-----------|
| **Pre-quantum** | Attacker must corrupt >= 1/3 stake to fork. Alpha threshold 69% ensures BFT safety. |
| **Q-day (BLS broken)** | Attacker can forge BLS but NOT Corona lattice signatures. Block fails quantum check. Consensus halts rather than accepting unsafe fork. |
| **Post-quantum** | Security rests on lattice SVP hardness (2^160 operations). Corona threshold signatures remain secure. |
| **Q-day (BLS broken)** | Attacker can forge BLS but NOT Corona or ML-DSA lattice signatures. Block fails quantum check. Consensus halts rather than accepting unsafe fork. |
| **Post-quantum** | Security rests on lattice SVP hardness (2^160 operations). Both Corona threshold and ML-DSA identity signatures remain secure. |
| **Attack window** | <= PQ round time ( <=50ms on mainnet). |
Both BLS and Corona proofs are **REQUIRED** for Q-Chain validators. No fallback mode. The `Verify` method enforces strict dual-proof validation.
All three proofs (BLS, Corona, ML-DSA) are **REQUIRED** for Q-Chain validators in triple mode. `IsTripleMode()` returns true when all three are configured. The `Verify` method enforces strict triple-proof validation.
## Validator Selection and Identity
@@ -156,6 +161,7 @@ Performance-based weighting: successful consensus participation increases bright
| Node-ID | ed25519 | P2P transport authentication | `$HOME/.lux/node.key` |
| Validator-BLS | BLS12-381 | Fast finality votes (classical) | `$HOME/.lux/bls.key` |
| Validator-PQ | Corona (Ring-LWE) | Post-quantum threshold shares | `$HOME/.lux/rt.key` |
| Validator-MLDSA | ML-DSA-65 (FIPS 204) | Post-quantum identity signatures | `$HOME/.lux/mldsa.key` |
| Wallet (EVM) | secp256k1 or Lamport-XMSS | User transaction signatures | In wallet |
| Wallet (X-Chain) | secp256k1 or Dilithium | UTXO locking | In wallet |
@@ -202,7 +208,7 @@ Quasar includes a Verkle witness system for hyper-efficient state verification:
|------|-----------|-------|
| `PQSignatureTypeMLDSA65` | NIST FIPS 204 ML-DSA-65 | Per-validator signatures (1952-byte public key) |
| `PQSignatureTypeCorona` | Ring-LWE threshold | Quasar consensus threshold signatures |
| `PQSignatureTypeHybrid` | Classical + PQ combined | Full Quasar hybrid proofs |
| `PQSignatureTypeHybrid` | Classical + PQ combined | Full Quasar triple proofs (BLS + Corona + ML-DSA) |
## Configuration Parameters
@@ -264,7 +270,7 @@ consensus/
nebula/ State sync protocol
field/ Nebula field operations
quasar/ Post-quantum finality engine
quasar.go Signer (BLS+Corona dual threshold)
quasar.go Signer (BLS+Corona+ML-DSA triple threshold)
core.go Quasar core (multi-chain block aggregator)
engine.go Engine interface implementation
epoch.go Epoch-based Corona key management
@@ -272,7 +278,7 @@ consensus/
grouped_threshold.go Grouped signing for 10K+ validators
bls.go DAG event horizon with BLS commitments
witness.go Verkle witness for hyper-efficient verification
types.go Block, BlockCert, Engine interface
types.go Block, QuasarCert, Engine interface
config.go QThreshold, QuasarTimeout
metrics.go Prometheus metrics
engine/
@@ -290,7 +296,7 @@ node/consensus/
acceptor.go Acceptor callback interface
engine/chain/ Vote message types (wire: Chits)
quasar/ Node-level Quasar integration
quasar.go Binds P-Chain + Q-Chain into hybrid finality
quasar.go Binds P-Chain + Q-Chain into triple finality
types.go Signature interfaces, CoronaCoordinator
zap/ ZAP agentic consensus bridge
bridge.go Query/Response/Vote consensus
@@ -378,7 +384,7 @@ ZAP (Zero-copy Agent Protocol) provides consensus for AI agent operations:
2. **SubmitResponse**: Other agents provide responses with DIDs.
3. **Vote**: Validators vote for responses (one vote per validator, enforced by DID).
4. **Consensus check**: When total votes >= `MinVotes` and a response has ` >= ConsensusThreshold` fraction, the query is finalized.
5. **Finality proof**: Signed with Quasar hybrid signatures (BLS + Corona).
5. **Finality proof**: Signed with Quasar dual signatures (BLS + Corona).
### ZAP Bridge Config
@@ -403,17 +409,20 @@ ZAP includes a `StakeRegistry` interface for stake-weighted voting:
|----------|----------|-----------|
| Classical adversary (< 1/3 stake) | Safe | BFT alpha=0.69 threshold prevents fork |
| Classical adversary ( &gt;= 1/3 stake) | Unsafe | Same as any BFT system |
| Quantum adversary (BLS breakable) | Safe | Corona lattice certificates prevent acceptance |
| Quantum adversary (both breakable) | Unsafe | Requires both lattice + BLS to be broken simultaneously |
| Quantum adversary (BLS breakable) | Safe | Corona + ML-DSA lattice certificates prevent acceptance |
| Quantum adversary (all three breakable) | Unsafe | Requires ECDL + Module-LWE + Module-SIS to be broken simultaneously |
| Adaptive adversary | Safe | FPC dynamic thresholds prevent threshold manipulation |
### QZMQ Transport Security
### Consensus Transport
All consensus messages use QZMQ (Quantum-Secure ZeroMQ):
- **Dilithium signatures** (post-quantum message authentication)
- **Kyber encryption** (quantum-resistant key encapsulation)
Consensus messages are transported via **ZAP** (`github.com/luxfi/zap`), the zero-copy binary protocol. ZAP provides 17x faster serialization than JSON-RPC with zero heap allocations on the parse path.
Node-to-node connections use **PQ-TLS 1.3** for transport encryption:
- **ML-KEM-768 + X25519** hybrid key exchange (Go 1.26 default via `crypto/tls`)
- **ML-DSA-65** post-quantum message authentication
- Forward secrecy via ephemeral keys
- Replay protection via session IDs
- Zero-copy semantics are preserved under TLS -- the TLS layer operates on the same buffer without additional allocations
## Account-Level PQ Options
@@ -467,7 +476,7 @@ for block := range engine.Finalized() {
}
```
### Node: Quasar with Hybrid Finality
### Node: Quasar with Triple Finality
```go
@@ -477,9 +486,9 @@ q.ConnectQuantumFallback(quantumSigner)
q.InitializeCorona(validatorNodeIDs)
q.Start(ctx)
// Listen for hybrid finality events
// Listen for dual finality events
for finality := range q.Subscribe() {
log.Printf("Hybrid finality: block=%s BLS=%dms RT=%dms",
log.Printf("Dual finality: block=%s BLS=%dms RT=%dms",
finality.BlockID, finality.BLSLatency.Milliseconds(), finality.CoronaLatency.Milliseconds())
}
```
apps/docs/content/docs/reference/lux-explore.mdx
+4 -4
View File
@@ -5,7 +5,7 @@ description: "Documentation for Lux Explore - Blockchain Explorer Frontend"
## Overview
Lux Explore is the **Next.js frontend** for the Lux Network block explorer, a fork of [Blockscout Frontend](https://github.com/blockscout/frontend). It provides the web UI for browsing transactions, contracts, tokens, and network activity at `explore.lux.network`.
Lux Explore is the **Next.js frontend** for the Lux Network block explorer. Originally a fork of the Blockscout frontend (now archived at `github.com/luxfi/explorer-v1`), it provides the web UI for browsing transactions, contracts, tokens, and network activity at `explore.lux.network`.
## Quick Reference
@@ -18,7 +18,7 @@ Lux Explore is the **Next.js frontend** for the Lux Network block explorer, a fo
| UI library | Chakra UI v3 |
| Package manager | pnpm 10.11.0 |
| Node | &gt;= 22.14.0 |
| Upstream | `blockscout/frontend` |
| Upstream | `blockscout/frontend` (diverged) |
| License | GPL v3.0 |
## Architecture
@@ -112,7 +112,7 @@ [email protected] # Language
## Lux Branding Customizations
Key areas where Lux branding diverges from upstream Blockscout:
Key areas where Lux branding diverges from the upstream fork:
- `ui/snippets/networkLogo/` -- Lux logo component
- `toolkit/theme/foundations/` -- Lux color palette
- `public/logos/` -- Lux brand assets
@@ -129,6 +129,6 @@ Key areas where Lux branding diverges from upstream Blockscout:
## Related Skills
- `lux/lux-explorer.md` -- Blockscout backend (Elixir)
- `lux/lux-explorer.md` -- Explorer backend (Go)
- `lux/lux-node.md` -- RPC node the explorer queries
- `lux/lux-indexer.md` -- Data indexing layer
apps/docs/content/docs/reference/lux-explorer.mdx
+75 -181
View File
@@ -1,239 +1,133 @@
---
title: "Lux Explorer"
description: "Multi-Chain Block Explorer"
description: "Single-Binary Omni-Chain Block 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.
Lux Explorer is a **single-binary Go block explorer** for browsing transactions, contracts, tokens, and network activity across the Lux ecosystem. It indexes an arbitrary number of heterogeneous blockchains concurrently (EVM, DAG, linear, DEX, FHE/threshold, post-quantum, zero-knowledge) with per-chain SQLite storage isolation and end-to-end post-quantum encrypted streaming backups to S3.
The legacy Blockscout-based Elixir explorer is archived at `github.com/luxfi/explorer-v1`.
**Repository**: `github.com/luxfi/explorer`
**License**: GPL-3.0
**License**: MIT
## Technology Stack
| Component | Version | Notes |
|-----------|---------|-------|
| Elixir | ~> 1.19 | All umbrella apps pin `elixir: "~> 1.19"` |
| Erlang/OTP | 27.3.4.6 | Docker base: `hexpm/elixir:1.19.4-erlang-27.3.4.6-alpine-3.22.2` |
| Phoenix | 1.6.16 | Exact pin in `block_scout_web/mix.exs` |
| Phoenix LiveView | ~> 1.1 | Real-time UI updates |
| Ecto | ~> 3.3 | PostgreSQL ORM, override for cross-app compatibility |
| PostgreSQL | 14+ | One database per chain (e.g., `explorer_luxnet`, `explorer_zoonet`) |
| Blockscout | 10.0.1 | All umbrella apps at version 10.0.1 |
| Alpine Linux | 3.22.2 | Runtime image base |
| Go | 1.26.1 | Single statically-linked binary |
| SQLite | WAL mode | Per-chain isolation, embedded |
| BadgerDB | v4 | KV layer for hash/height lookups |
| Next.js | 15 | Frontend (separate `github.com/luxfi/explore`) |
| Docker | Alpine 3.19 | Runtime image |
## Architecture
### Umbrella Apps
### Single Binary
The project is an OTP umbrella with 6 apps under `apps/`:
The explorer contains three concurrent subsystems:
| App | Module | Purpose |
|-----|--------|---------|
| `block_scout_web` | `BlockScoutWeb` | Phoenix web API and UI (GraphQL, REST v2, WebSocket) |
| `ethereum_jsonrpc` | `EthereumJSONRPC` | JSON-RPC client for EVM nodes (HTTP, WebSocket) |
| `explorer` | `Explorer` | Data layer -- Ecto schemas, chain queries, caches |
| `indexer` | `Indexer` | Fetchers that pull data from RPC and write to DB |
| `utils` | `Utils` | Shared utilities (HTTP, MIME, Tesla) |
| `nft_media_handler` | `NFTMediaHandler` | NFT image/video processing (S3, eVision) |
| Subsystem | Purpose |
|-----------|---------|
| Indexer goroutines | One per chain, each writing to its own SQLite + BadgerDB |
| API server | HTTP server serving `/v1/explorer/{chain}/*` endpoints |
| Replicator | Per-chain WAL streaming to S3 with PQ encryption |
### Database Schema
### Per-Chain Storage
318 Ecto migrations from `20180117` through `20260305`. Core tables include:
```
{data_dir}/{chain_slug}/
query/indexer.db # SQLite: blocks, txs, tokens, contracts
kv/ # BadgerDB: hash->data, height->block
```
- `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
Each chain is fully isolated. No shared database. Zero write contention between chains.
## Supported Networks
### Chain Configurations (`configs/chains/`)
| Network | Chain ID | Currency | Explorer URL |
|---------|----------|----------|-------------|
| LUX Mainnet | 96369 | LUX | explore.lux.network |
| LUX Testnet | 96368 | LUX | testnet.explore.lux.network |
| Zoo Mainnet | 200200 | ZOO | explore-zoo.lux.network |
| SPC Mainnet | 36911 | SPC | explore-spc.lux.network |
| Hanzo AI | 36963 | HZO | explore-hanzo.lux.network |
| Pars | 494949 | PARS | explore-pars.lux.network |
| Network | Chain ID | Currency | Frontend Host | Backend Host |
|---------|----------|----------|--------------|--------------|
| LUX Mainnet | 96369 | LUX | explore.lux.network | api-explore.lux.network |
| LUX Testnet | 96368 | LUX | testnet.explore.lux.network | api-testnet.explore.lux.network |
| Zoo Mainnet | 200200 | ZOO | explore.zoo.network | api-explore.zoo.network |
| SPC Mainnet | 36911 | SPC | explore.spc.network | api-explore.spc.network |
| Hanzo AI | 36963 | HZO | -- | -- |
## Native Chain Types
### Compose Files
9 Lux chain types indexed natively:
Per-network compose files bring up backend, frontend, visualizer, sig-provider, and stats:
- **EVM**: C-Chain, Zoo, Hanzo, SPC, Pars (blocks, transactions, tokens, contracts, DeFi)
- **DAG**: X, A, B, Q, T, Z, K (vertices, edges, UTXOs, attestations, proofs)
- **Linear**: P-Chain (validators, delegators, staking, subnet management)
| File | Network | Backend Port | Frontend Port |
|------|---------|-------------|---------------|
| `compose.luxnet.yml` | LUX Mainnet | 4000 | 3000 |
| `compose.luxtest.yml` | LUX Testnet | 4010 | 3010 |
| `compose.zoonet.yml` | Zoo Mainnet | 4001 | 3001 |
| `compose.zootest.yml` | Zoo Testnet | 4011 | 3011 |
| `compose.hanzonet.yml` | Hanzo AI | 4003 | 3003 |
Plus 100+ external chains (Ethereum, Solana, Bitcoin, Cosmos, Move, etc.).
### Multi-Chain All-In-One (`docker-compose.all-chains.yml`)
## API Surface
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 EVM-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 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
| Library | Purpose |
|---------|---------|
| `absinthe` ~> 1.5 | GraphQL toolkit |
| `tesla` ~> 1.16.0 | HTTP client (shared across all apps) |
| `bcrypt_elixir` ~> 3.0 | Password hashing (explorer app) |
| `ex_keccak` ~> 0.7.5 | Keccak-256 hashing |
| `redix` ~> 1.1 | Redis client for caching |
| `hammer` ~> 7.0 | Rate limiting |
| `ueberauth_auth0` ~> 2.0 | Auth0 authentication |
| `spandex` ~> 3.0 | Datadog tracing |
| `ezstd` ~> 1.2 | ZSTD compression |
| `cloak_ecto` ~> 1.3.0 | Ecto field encryption |
### 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.
- **REST**: `/v1/explorer/*` (blocks, transactions, addresses, tokens, stats, search)
- **GraphQL**: `/graphql` endpoint + playground
- **WebSocket**: Real-time block/transaction subscriptions
- **Prometheus**: `/metrics` endpoint
## Development
### Prerequisites
- Elixir 1.19+, Erlang/OTP 27+
- PostgreSQL 14+
- Node.js 16+ (for frontend)
- Running Lux node (luxd) with EVM
### Build
```bash
# Fetch deps and compile
mix deps.get
mix compile
go build -o explorer ./cmd/explorer
```
# Create and migrate database
mix ecto.create
mix ecto.migrate
### Run
# Start development server
mix phx.server
```bash
# Single chain
./explorer --rpc=http://localhost:9650/ext/bc/C/rpc
# Multi-chain
./explorer --config=chains.yaml
```
### Docker
```bash
# 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
docker build -t ghcr.io/luxfi/explorer:latest .
```
### Tests
```bash
# 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
go test -v ./...
```
### Environment Variables
## White-Label
Key variables (see `docker-compose/envs/common-blockscout.env`):
The explorer is white-label by design. Zero branding in code. Runtime-configurable via `chains.yaml`:
| Variable | Purpose | Example |
|----------|---------|---------|
| `DATABASE_URL` | PostgreSQL connection | `postgresql://blockscout:pass@host:5432/explorer_luxnet` |
| `ETHEREUM_JSONRPC_HTTP_URL` | RPC endpoint | `http://luxd:9650/ext/bc/.../rpc` |
| `ETHEREUM_JSONRPC_WS_URL` | WebSocket endpoint | `ws://luxd:9650/ext/bc/.../ws` |
| `ETHEREUM_JSONRPC_VARIANT` | Client type | `geth` |
| `CHAIN_ID` | EVM chain ID | `96369` |
| `COIN_NAME` | Native currency display | `LUX` |
| `PORT` | HTTP server port | `4000` |
| `SECRET_KEY_BASE` | Phoenix secret | 64-char random string |
| `API_V2_ENABLED` | Enable REST v2 | `true` |
| `CHAIN_TYPE` | Chain-specific modules | (empty for default) |
| `DISABLE_WEBAPP` | API-only mode | `true` |
```yaml
chains:
- slug: cchain
name: "C-Chain"
chain_id: 96369
rpc: "http://luxd:9630/ext/bc/C/rpc"
logo: "/logos/lux.svg"
color: "#1a1a2e"
```
## 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)
cmd/explorer/ # CLI entrypoint
evm/ # EVM indexer (blocks, txs, tokens, traces, contracts, DeFi)
evm/api/ # REST API server
dag/ # DAG vertex/edge indexer
chain/ # Linear block indexer
storage/ # Dual-layer SQLite + BadgerDB
multichain/ # 100+ external chain indexer
{x,a,b,q,t,z,k}chain/ # Per-chain adapters
config/chains.yaml # Chain configuration
go.mod # github.com/luxfi/explorer
```
apps/docs/content/docs/reference/lux-indexer.mdx
+9 -9
View File
@@ -5,7 +5,7 @@ description: "Multi-Chain Blockchain Data Indexing"
## Overview
Lux Indexer is a **Go-based blockchain data indexing system** that covers all Lux native chains (DAG and linear), EVM chains across the Lux chain ecosystem, and a universal multi-chain indexer supporting 100+ blockchains across EVM, Solana, Bitcoin, Cosmos, Move, and other runtimes. It works alongside Blockscout (which handles C-Chain EVM indexing) to provide complete data access for the Lux multi-chain architecture.
Lux Indexer is a **Go-based blockchain data indexing system** that covers all Lux native chains (DAG and linear), EVM chains across the Lux chain ecosystem, and a universal multi-chain indexer supporting 100+ blockchains across EVM, Solana, Bitcoin, Cosmos, Move, and other runtimes. It provides complete data access for the Lux multi-chain architecture via the `/v1/explorer/*` API.
**Repository**: `github.com/luxfi/indexer`
**License**: MIT
@@ -46,7 +46,7 @@ Uses `github.com/luxfi/indexer/dag` -- multiple parents per vertex for fast cons
| Chain | Port | Database | RPC Method | Description |
|-------|------|----------|-----------|-------------|
| X-Chain | 4200 | explorer_xchain | `xvm` | Asset exchange, UTXOs |
| A-Chain | 4500 | explorer_achain | `avm` | AI compute, attestations |
| A-Chain | 4500 | explorer_achain | `xvm` | AI compute, attestations |
| B-Chain | 4600 | explorer_bchain | `bvm` | Cross-chain bridge |
| Q-Chain | 4300 | explorer_qchain | `qvm` | Quantum finality proofs |
| T-Chain | 4700 | explorer_tchain | `tvm` | MPC threshold signatures |
@@ -61,11 +61,11 @@ Uses `github.com/luxfi/indexer/chain` -- single parent per block for strict orde
| P-Chain | 4100 | explorer_pchain | `pvm` | Platform, validators, staking |
#### EVM Chains
Uses `github.com/luxfi/indexer/evm` -- full EVM block/transaction indexing with Blockscout-compatible API.
Uses `github.com/luxfi/indexer/evm` -- full EVM block/transaction indexing with `/v1/explorer/*` API.
| Chain | Port | Database | Description |
|-------|------|----------|-------------|
| C-Chain (Go) | 4000 | explorer_cchain | Smart contracts (lightweight Go alternative to Blockscout) |
| C-Chain (Go) | 4000 | explorer_cchain | Smart contracts, full EVM indexing |
### EVM Multi-Chain Process (`evmchains`)
@@ -170,13 +170,13 @@ For linear native chains:
### API Compatibility
All indexers expose **Blockscout-compatible `/api/v2/` endpoints**:
All indexers expose `/v1/explorer/*` endpoints:
**DAG chains**: `/api/v2/stats`, `/api/v2/vertices`, `/api/v2/vertices/:id`, `/api/v2/edges`, `WS /api/v2/dag/subscribe`
**DAG chains**: `/v1/explorer/stats`, `/v1/explorer/vertices`, `/v1/explorer/vertices/:id`, `/v1/explorer/edges`, `WS /v1/explorer/dag/subscribe`
**Linear chains**: `/api/v2/stats`, `/api/v2/blocks`, `/api/v2/blocks/:id`, `/api/v2/blocks/height/:height`, `WS /api/v2/blocks/subscribe`
**Linear chains**: `/v1/explorer/stats`, `/v1/explorer/blocks`, `/v1/explorer/blocks/:id`, `/v1/explorer/blocks/height/:height`, `WS /v1/explorer/blocks/subscribe`
**EVM chains**: Full Blockscout API v2 compatibility (blocks, transactions, addresses, tokens, stats, search).
**EVM chains**: Full explorer API (blocks, transactions, addresses, tokens, stats, search).
### EVM Module (`evm/`)
@@ -184,7 +184,7 @@ Rich EVM indexing with subpackages:
| Package | Purpose |
|---------|---------|
| `evm/api/` | Blockscout-compatible REST API server |
| `evm/api/` | REST API server (`/v1/explorer/*`) |
| `evm/account/` | Account balance tracking |
| `evm/contracts/` | Contract verification and ABI decoding |
| `evm/defi/` | DeFi protocol indexing |
apps/docs/content/docs/reference/lux-node.mdx
+9 -9
View File
@@ -5,12 +5,12 @@ description: "Documentation for Lux Node - Core Validator Implementation"
## Overview
Lux Node (`luxd`) is the core validator node for the Lux Network -- a multi-chain, multi-consensus blockchain with post-quantum hybrid finality (Quasar), 14 chain types, custom VM support, and W3C DID-based validator identity. Written in Go. The binary name is `luxd`, the module path is `github.com/luxfi/node`.
Lux Node (`luxd`) is the core validator node for the Lux Network -- a multi-chain, multi-consensus blockchain with post-quantum dual finality (Quasar), 14 chain types, custom VM support, and W3C DID-based validator identity. Written in Go. The binary name is `luxd`, the module path is `github.com/luxfi/node`.
### Tech Stack
- **Language**: Go 1.26.1 (CGO enabled by default)
- **Consensus**: Quasar hybrid finality (BLS + Corona post-quantum threshold)
- **Consensus**: Quasar dual finality (BLS + Corona post-quantum threshold)
- **Crypto**: BLS aggregate signatures, ML-DSA-65 (post-quantum), ML-KEM, Corona threshold, Falcon, secp256k1
- **Database**: LevelDB/PebbleDB (via `github.com/luxfi/database`)
- **Networking**: Custom TCP P2P with TLS mutual auth, PROXY protocol support, Zstd compression
@@ -172,7 +172,7 @@ curl -X POST http://localhost:9630/ext/bc/C/rpc \
# X-Chain: asset balance
curl -X POST http://localhost:9630/ext/bc/X \
-d '{"jsonrpc":"2.0","id":1,"method":"avm.getBalance","params":{"address":"X-lux1...","assetID":"LUX"}}'
-d '{"jsonrpc":"2.0","id":1,"method":"xvm.getBalance","params":{"address":"X-lux1...","assetID":"LUX"}}'
```
### Go SDK client
@@ -211,7 +211,7 @@ luxd (main/main.go)
│ └── rpc/ — Inter-chain RPC communication
├── consensus/ — Consensus infrastructure
│ ├── engine/chain/ — Linear chain consensus engine (vote messages)
│ ├── quasar/ — Hybrid quantum-safe finality (BLS + Corona)
│ ├── quasar/ — Dual quantum-safe finality (BLS + Corona)
│ └── zap/ — ZAP bridge (W3C DID identity, agentic consensus)
├── network/ — P2P networking, peer management, IP tracking
│ ├── peer/ — Peer connections, handshake
@@ -265,7 +265,7 @@ luxd (main/main.go)
├── cache/ — Caching utilities (LRU)
├── gas/ — Gas pricing
├── nat/ — NAT traversal (UPnP, NAT-PMP)
├── pubsub/ — Pub/sub event system
├── pubsub/ — Pub/sub event system (durable messaging via hanzoai/pubsub)
├── router/ — Message routing
├── utils/ — General utilities
├── wallet/ — Wallet implementation
@@ -293,7 +293,7 @@ The Lux Network supports 14 built-in chain types across 3 tiers.
| Chain | Letter | VM | Purpose |
|-------|--------|----|---------|
| **Q-Chain** | Q | quantumvm | Post-quantum cryptography, Corona keys, quantum stamps |
| **Q-Chain** | Q | quantumvm | Post-quantum cryptography, Corona keys, QuasarCert finality certificates |
| **A-Chain** | A | aivm | AI/ML compute attestation, TEE verification (SGX/SEV-SNP/TDX/nvtrust) |
| **B-Chain** | B | bridgevm | Cross-chain bridge with MPC threshold signing |
| **T-Chain** | T | thresholdvm | MPC-as-a-service (CMP/LSS protocols) |
@@ -320,7 +320,7 @@ Lux Node implements a multi-consensus architecture:
2. **DAG (Lux/Lux)**: For directed acyclic graph chains (X-Chain). Vertices can have multiple parents. Uses `DAGVertex` interface. Enables higher throughput via parallel transaction processing.
3. **Quasar**: The hybrid quantum-safe finality engine. Runs on top of linear consensus. Produces **hybrid finality proofs** requiring both:
3. **Quasar**: The dual quantum-safe finality engine. Runs on top of linear consensus. Produces **dual finality proofs** (QuasarCert) requiring both:
- **BLS Path**: Aggregate BLS signatures from 2/3+ validator weight (96-byte proof, fast)
- **Corona Path**: Post-quantum threshold signatures (t-of-n, 2-round protocol)
- Both paths execute **in parallel**; blocks achieve quantum finality only when both complete
@@ -332,7 +332,7 @@ Lux Node implements a multi-consensus architecture:
```
SignatureTypeBLS = 0 // Classical BLS aggregate
SignatureTypeCorona = 1 // Post-quantum threshold
SignatureTypeQuasar = 2 // Hybrid BLS + Corona
SignatureTypeQuasar = 2 // Dual BLS + Corona
SignatureTypeMLDSA = 3 // ML-DSA fallback
```
@@ -356,7 +356,7 @@ Staking port is always API port + 1 (e.g., 9631 for mainnet).
- **TLS Certificates**: Self-signed ECDSA certs for P2P mutual auth (`staking/tls.go`)
- **BLS Keys**: For aggregate signature consensus
- **ML-DSA Keys**: Post-quantum key pairs for hybrid staking (`staking/pq.go`, uses `github.com/luxfi/crypto/mldsa`)
- **ML-DSA Keys**: Post-quantum key pairs for dual staking (`staking/pq.go`, uses `github.com/luxfi/crypto/mldsa`)
- **Corona Keys**: Post-quantum threshold signature shares
- **W3C DIDs**: Validator identity via did:lux method (ZAP bridge)
apps/docs/content/docs/reference/lux-p2p.mdx
+13
View File
@@ -14,6 +14,19 @@ The Lux P2P layer handles all node-to-node communication across the Lux consensu
| `github.com/luxfi/node/network` | 1.26.1 | `luxfi/consensus`, `luxfi/crypto/bls`, `luxfi/ids`, `luxfi/warp`, `luxfi/node/message`, `luxfi/validators`, `luxfi/compress` |
| `github.com/luxfi/p2p` | 1.26.1 | `luxfi/[email protected]`, `luxfi/[email protected]`, `luxfi/[email protected]`, `luxfi/[email protected]`, `luxfi/[email protected]`, `luxfi/[email protected]`, `luxfi/[email protected]`, `luxfi/[email protected]`, `google.golang.org/[email protected]` |
## ZAP Consensus Transport
**ZAP** (`github.com/luxfi/zap`) is the primary transport for consensus messages between validators. ZAP provides zero-copy binary serialization (17x faster than JSON-RPC, 2.9 ns parse time, 0 allocations) over TCP with optional TLS.
### PQ-TLS 1.3
All node-to-node connections use PQ-TLS 1.3 for transport security. Go 1.26 defaults to **ML-KEM-768 + X25519** hybrid key exchange in `crypto/tls`, so PQ-TLS is enabled without additional configuration. Key properties:
- **Key exchange**: X25519MLKEM768 hybrid (NIST Level 3 + classical ECDH)
- **Configuration**: `NodeConfig.TLS` field on the ZAP node
- **Zero-copy preserved**: TLS does not break ZAP zero-copy semantics -- the TLS layer operates on the same buffer without additional heap allocations
- **Mutual auth**: Validators authenticate via TLS client certificates (node staking cert)
## Node Network Layer (luxfi/node/network)
### Network Config
apps/docs/content/docs/reference/lux-stack.mdx
+3 -3
View File
@@ -40,7 +40,7 @@ Lux Stack is a **Docker Compose-based white-label L1 blockchain ecosystem**. Dep
| Service | Image | Port | Purpose |
|---------|-------|------|---------|
| `explorer` | `ghcr.io/blockscout/blockscout:latest` | 4000 | Block explorer (Blockscout) |
| `explorer` | `ghcr.io/luxfi/explorer:latest` | 4000 | Block explorer |
| `exchange` | `ghcr.io/luxfi/exchange:latest` | 3000 | DEX / Token exchange |
| `exchange-api` | `ghcr.io/luxfi/exchange-api:latest` | 3010 | Exchange backend API |
| `marketplace` | `ghcr.io/luxfi/marketplace:latest` | 3001 | NFT marketplace |
@@ -119,7 +119,7 @@ Health checks are configured on all critical services (node, redis, all database
## Explorer Configuration
The Blockscout explorer connects to the C-Chain:
The explorer connects to the C-Chain:
```
RPC: http://node:9650/ext/bc/C/rpc
@@ -191,7 +191,7 @@ make health # Check all health endpoints
|----------|-----------|
| Docker Compose | Simple orchestration, easy to customize |
| Separate databases | Service isolation, independent scaling |
| Blockscout | Most complete open-source EVM explorer |
| Lux Explorer | Single-binary Go explorer, replaces legacy Blockscout |
| The Graph | Standard subgraph indexing for DApps |
| `ghcr.io/hanzoai/sql` | Hanzo PostgreSQL image (consistent infra) |
| `ghcr.io/hanzoai/kv` | Hanzo Redis/Valkey image (consistent infra) |
apps/docs/content/docs/reference/lux-universe.mdx
+3 -3
View File
@@ -129,9 +129,9 @@ docker compose --profile bank up -d # Add Lux Bank (lux.financial)
| Explorer | Chain | Chain ID | Port | Image |
|----------|-------|----------|------|-------|
| LUX Explorer | C-Chain | 96369 | 4010 | Blockscout |
| Zoo Explorer | Zoo Network | 200200 | 4011 | Blockscout |
| Hanzo Explorer | AI Chain | 36963 | 4012 | Blockscout |
| LUX Explorer | C-Chain | 96369 | 4010 | `ghcr.io/luxfi/explorer` |
| Zoo Explorer | Zoo Network | 200200 | 4011 | `ghcr.io/luxfi/explorer` |
| Hanzo Explorer | AI Chain | 36963 | 4012 | `ghcr.io/luxfi/explorer` |
| Explorer Frontend | C-Chain | 96369 | 3100 | `ghcr.io/luxfi/explore` |
All explorers use shared PostgreSQL with separate databases (`explorer_lux`, `explorer_zoo`, `explorer_hanzo`).
apps/docs/content/docs/sdk/api.mdx
+5 -5
View File
@@ -34,11 +34,11 @@ All Lux chains expose JSON-RPC APIs. The SDK wraps these APIs with typed clients
| Method | Description |
|--------|-------------|
| `avm.getBalance` | Address balance for a specific asset |
| `avm.getUTXOs` | Unspent transaction outputs |
| `avm.send` | Send assets (requires unlocked keystore) |
| `avm.getAssetDescription` | Asset metadata (name, symbol, denomination) |
| `avm.getTx` | Transaction by ID |
| `xvm.getBalance` | Address balance for a specific asset |
| `xvm.getUTXOs` | Unspent transaction outputs |
| `xvm.send` | Send assets (requires unlocked keystore) |
| `xvm.getAssetDescription` | Asset metadata (name, symbol, denomination) |
| `xvm.getTx` | Transaction by ID |
## C-Chain Methods
apps/docs/content/docs/sdk/go/rpc.mdx
+2 -2
View File
@@ -67,9 +67,9 @@ validators, err := client.GetCurrentValidators(
Exchange chain operations for UTXO-based asset management:
```go
import "github.com/luxfi/sdk/avm"
import "github.com/luxfi/sdk/xvm"
client := avm.NewClient(
client := xvm.NewClient(
"https://api.lux.network/mainnet/ext/bc/X",
)
apps/docs/content/docs/zap/api.mdx
+1
View File
@@ -88,6 +88,7 @@ node := zap.NewNode(zap.NodeConfig{
NodeID: "node-1",
ServiceType: "_luxd._tcp",
Port: 9651,
TLS: tlsConfig, // optional; Go 1.26 defaults to PQ-TLS 1.3 (ML-KEM-768)
})
node.Handle(MsgTypePing, func(ctx context.Context, from string, msg *zap.Message) (*zap.Message, error) {
apps/docs/content/docs/zap/index.mdx
+15
View File
@@ -53,6 +53,21 @@ Data Segment (variable)
| Hash | 32 | EVM hash |
| Signature | 65 | EVM signature |
## TLS Support
ZAP supports optional TLS via `NodeConfig.TLS`. When running on Go 1.26+, TLS connections default to **PQ-TLS 1.3** with ML-KEM-768 + X25519 hybrid key exchange -- no additional configuration required.
```go
node := zap.NewNode(zap.NodeConfig{
NodeID: "node-1",
ServiceType: "_luxd._tcp",
Port: 9651,
TLS: tlsConfig, // *tls.Config; Go 1.26 defaults to ML-KEM-768
})
```
Zero-copy semantics are preserved under TLS. The TLS layer operates on the same buffer without additional heap allocations.
## Use Cases
- **AI Agent Orchestration**: 20-tool orchestrator runs at 150K ops/sec vs 10K with JSON-RPC