smom-dbis-138/services/token-aggregation/docs/DEPLOYMENT.md

Deployment Guide

Prerequisites

1. Database: PostgreSQL 14+ with TimescaleDB extension
2. Node.js: Version 20 or higher
3. Docker: (Optional) For containerized deployment
4. RPC Access: Access to RPC endpoints for ChainID 138 and 651940

Database Setup

1. Ensure PostgreSQL is running with TimescaleDB extension enabled:

CREATE EXTENSION IF NOT EXISTS timescaledb;

2. Run the migration from the explorer database:

# The migration file is located at:
# explorer-monorepo/backend/database/migrations/0011_token_aggregation_schema.up.sql

3. Verify tables were created:

\dt token_market_data
\dt liquidity_pools
\dt token_ohlcv

Environment Configuration

1. Copy the example environment file:

cp .env.example .env

2. Configure required variables:

# Required
CHAIN_138_RPC_URL=https://rpc-http-pub.d-bis.org
CHAIN_651940_RPC_URL=https://mainnet-rpc.alltra.global
DATABASE_URL=postgresql://user:password@localhost:5432/explorer_db

# Optional (for external API enrichment)
COINGECKO_API_KEY=your_key_here
COINMARKETCAP_API_KEY=your_key_here
DEXSCREENER_API_KEY=your_key_here

Local Deployment

Using npm

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Start the service:

npm start

Using Docker

1. Build the image:

docker build -t token-aggregation-service .

2. Run the container:

docker run -d \
  --name token-aggregation \
  -p 3000:3000 \
  --env-file .env \
  token-aggregation-service

Using Docker Compose

1. Start all services:

docker-compose up -d

2. View logs:

docker-compose logs -f token-aggregation

Production Deployment

Kubernetes

1. Create a ConfigMap for environment variables:

apiVersion: v1
kind: ConfigMap
metadata:
  name: token-aggregation-config
data:
  CHAIN_138_RPC_URL: "https://rpc-http-pub.d-bis.org"
  CHAIN_651940_RPC_URL: "https://mainnet-rpc.alltra.global"
  INDEXING_INTERVAL: "5000"
  LOG_LEVEL: "info"

2. Create a Secret for sensitive data:

apiVersion: v1
kind: Secret
metadata:
  name: token-aggregation-secrets
type: Opaque
stringData:
  DATABASE_URL: "postgresql://..."
  COINGECKO_API_KEY: "..."
  COINMARKETCAP_API_KEY: "..."

3. Deploy the service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: token-aggregation
spec:
  replicas: 2
  selector:
    matchLabels:
      app: token-aggregation
  template:
    metadata:
      labels:
        app: token-aggregation
    spec:
      containers:
      - name: token-aggregation
        image: token-aggregation-service:latest
        ports:
        - containerPort: 3000
        envFrom:
        - configMapRef:
            name: token-aggregation-config
        - secretRef:
            name: token-aggregation-secrets
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 5

DEX Factory Configuration

For ChainID 138, configure DODO PoolManager address:

CHAIN_138_DODO_POOL_MANAGER=0x...

For ChainID 651940, configure DEX factories as they are discovered:

CHAIN_651940_UNISWAP_V2_FACTORY=0x...
CHAIN_651940_UNISWAP_V3_FACTORY=0x...

Monitoring

Health Checks

The service exposes a health check endpoint:

curl http://localhost:3000/health

Logs

View service logs:

# Docker
docker logs -f token-aggregation

# Kubernetes
kubectl logs -f deployment/token-aggregation

Metrics

Monitor the following:

• Database connection pool usage
• Indexing progress (tokens indexed, pools discovered)
• API request rates
• External API call success rates

Troubleshooting

Database Connection Issues

1. Verify database is accessible:

psql $DATABASE_URL -c "SELECT 1"

2. Check connection pool settings in .env

RPC Connection Issues

1. Test RPC endpoints:

curl -X POST $CHAIN_138_RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

2. Verify RPC URLs in .env

Indexing Not Working

1. Check logs for errors
2. Verify DEX factory addresses are configured
3. Ensure RPC endpoints have required APIs enabled (ETH, NET, etc.)

Scaling

Horizontal Scaling

The service is stateless and can be scaled horizontally:

• Multiple instances can run simultaneously
• Each instance will index independently
• Database handles concurrent writes

Vertical Scaling

For high-volume chains:

• Increase INDEXING_INTERVAL for less frequent updates
• Increase database connection pool size
• Use read replicas for database queries

Backup and Recovery

Database Backups

Regular backups of the following tables:

• token_market_data
• liquidity_pools
• token_ohlcv
• swap_events

Recovery

1. Restore database from backup
2. Restart indexing service
3. Service will backfill missing data automatically