explorer-monorepo/docs/TIERED_ARCHITECTURE_SETUP.md

Tiered Architecture Setup Guide

Complete setup and integration guide for SolaceScanScout tiered architecture.

Quick Start

# 1. Run the setup script
cd explorer-monorepo
bash scripts/setup-tiered-architecture.sh

# 2. Set required environment variables
export JWT_SECRET="your-strong-random-secret-here"
export RPC_URL="http://192.168.11.250:8545"
export DB_HOST="localhost"
export DB_USER="explorer"
export DB_PASSWORD="changeme"
export DB_NAME="explorer"

# 3. Start the API server
cd backend
./bin/api-server

Environment Variables

Required

• DB_HOST - PostgreSQL host (default: localhost)
• DB_USER - Database user (default: explorer; use blockscout for the shared Blockscout DB mode)
• DB_PASSWORD - Database password (default: changeme)
• DB_NAME - Database name (default: explorer; use blockscout for the shared Blockscout DB mode)

Recommended (Production)

• JWT_SECRET - Strong random secret for JWT signing (required for production)
• RPC_URL - RPC endpoint for Track 1 gateway (default: http://localhost:8545)
• CHAIN_ID - Chain ID (default: 138)
• PORT - API server port (default: 8080)

Database Migration

Run the migration helper:

bash scripts/run-migration-0010.sh

The helper auto-detects the database layout:

• Standalone explorer DB: creates the full Track 2-4 schema
• Shared Blockscout DB: creates only operator_events, operator_ip_whitelist, operator_roles, and wallet_nonces

Do not apply backend/database/migrations/0010_track_schema.up.sql directly to the shared Blockscout DB.

User Management

Approve a User for Track 2-4

# Approve user for Track 2
bash scripts/approve-user.sh 0x1234...5678 2

# Approve user for Track 3
bash scripts/approve-user.sh 0x1234...5678 3

# Approve user for Track 4 (operator)
bash scripts/approve-user.sh 0x1234...5678 4 0xAdminAddress

Add IP to Operator Whitelist (Track 4)

bash scripts/add-operator-ip.sh 0x1234...5678 192.168.1.100 "Office network"

API Endpoints

Track 1 (Public - No Auth)

• GET /api/v1/track1/blocks/latest - Latest blocks
• GET /api/v1/track1/txs/latest - Latest transactions
• GET /api/v1/track1/block/:number - Block by number
• GET /api/v1/track1/tx/:hash - Transaction by hash
• GET /api/v1/track1/address/:addr/balance - Address balance
• GET /api/v1/track1/bridge/status - Bridge status

Track 2 (Authenticated - Track 2+)

• GET /api/v1/track2/address/:addr/txs - Address transaction history
• GET /api/v1/track2/address/:addr/tokens - Address token balances
• GET /api/v1/track2/token/:contract - Token information
• GET /api/v1/track2/search?q= - Enhanced search
• GET /api/v1/track2/address/:addr/internal-txs - Internal transactions

Track 3 (Authenticated - Track 3+)

• GET /api/v1/track3/analytics/flows - Flow tracking
• GET /api/v1/track3/analytics/bridge - Bridge analytics
• GET /api/v1/track3/analytics/token-distribution/:contract - Token distribution
• GET /api/v1/track3/analytics/address-risk/:addr - Address risk analysis

Track 4 (Authenticated - Track 4 + IP Whitelist)

• GET /api/v1/track4/operator/bridge/events - Bridge operator events
• GET /api/v1/track4/operator/validators - Validator status
• GET /api/v1/track4/operator/contracts - Contract registry
• GET /api/v1/track4/operator/protocol-state - Protocol state

Authentication

• POST /api/v1/auth/nonce - Request nonce for wallet auth
• POST /api/v1/auth/wallet - Authenticate with wallet signature

Feature Flags

• GET /api/v1/features - Get available features for current user

Frontend Integration

The frontend automatically:

1. Loads feature flags on page load
2. Shows/hides UI elements based on track level
3. Provides wallet connect button for authentication
4. Stores auth token in localStorage

Testing Authentication

1. Open browser console
2. Connect wallet using the "Connect Wallet" button
3. Sign the authentication message
4. Check localStorage.getItem('authToken') to verify token storage
5. Check feature flags: fetch('/api/v1/features').then(r => r.json())

Indexer Setup

To populate Track 2 data, start the indexers:

cd backend/indexer
go run main.go

The indexers will:

• Index blocks and transactions
• Extract ERC-20 token transfers
• Update address statistics
• Build analytics data

Production Considerations

1. JWT Secret: Must be set to a strong random value
2. Redis: Replace in-memory cache/rate limiter with Redis
3. HTTPS: Use HTTPS in production
4. Rate Limiting: Configure appropriate rate limits per track
5. IP Whitelist: Strictly enforce for Track 4 operators
6. Audit Logging: Monitor operator_events table

Troubleshooting

Migration Fails

• Check database connection: psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"
• Verify user has CREATE TABLE permissions
• If you are using the shared Blockscout DB, keep DB_USER and DB_NAME aligned to blockscout

Authentication Fails

• Check JWT_SECRET is set
• Verify wallet_nonces table exists
• Check database connection in auth handlers
• If the wallet popup shows Nonce: undefined, the nonce request failed before signing. Run bash scripts/run-migration-0010.sh, restart the backend, and retry.

Track Routes Not Working

• Verify user is approved: Check operator_roles table
• Check track level in JWT token
• Verify middleware is applied correctly

Frontend Feature Gating Not Working

• Check browser console for errors
• Verify /api/v1/features endpoint returns correct track
• Check localStorage for authToken

Next Steps

1. ✅ Run database migration
2. ✅ Set environment variables
3. ✅ Start API server
4. ✅ Approve test users
5. ✅ Start indexers
6. ✅ Test authentication flow
7. ✅ Verify feature gating

For detailed API documentation, see: docs/api/track-api-contracts.md