Deployment - Polygon Developer Docs

Prerequisites

Infrastructure requirements

Each Bridge Hub component has specific compute requirements:

Component	CPU	RAM	Notes
API	2+ vCPU	4 GB	Per instance
Consumer	2+ vCPU	4 GB	Per network
Auto-Claim	1+ vCPU	2 GB	Per destination

You also need a MongoDB instance (version 4.4 or later). A 3-node replica set is recommended for production, with at least 100 GB of storage that can grow with transaction volume.

Software requirements

Bun >= 1.0.0
MongoDB >= 4.4
Docker (optional; for containerized deployment)
Kubernetes (optional; for orchestrated deployment)

External services

Bridge Service API access for each network you plan to index.
Blockchain RPC endpoints from a reliable provider.
Sentry account (optional) for error tracking.

Build

From the repository root, install dependencies and create production builds:

bun install
bun run build

This outputs production artifacts to packages/api/dist/, packages/consumer/dist/, and packages/auto-claim/dist/.

Docker deployment

The repository includes production-ready Dockerfiles for each service:

Dockerfile.api:API service (exposes port 3001)
Dockerfile.consumer:Consumer service
Dockerfile.autoclaim:Auto-Claim service

Each Dockerfile uses oven/bun:1.2-alpine with multi-stage builds and runs as a non-root user (bunuser).

Build images

docker build -f Dockerfile.api -t bridge-hub-api:latest .
docker build -f Dockerfile.consumer -t bridge-hub-consumer:latest .
docker build -f Dockerfile.autoclaim -t bridge-hub-autoclaim:latest .

Docker Compose

Create a docker-compose.yml in the repository root:

version: "3.8"

services:
    mongodb:
        image: mongo:7
        volumes:
            - mongo-data:/data/db
        environment:
            MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER}
            MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
        ports:
            - "27017:27017"
        restart: unless-stopped
        networks:
            - bridge-hub

    api:
        build:
            context: .
            dockerfile: Dockerfile.api
        ports:
            - "3001:3001"
        environment:
            NODE_ENV: production
            MONGODB_CONNECTION_URI: ${MONGODB_CONNECTION_URI}
            MONGODB_DB_NAME: ${MONGODB_DB_NAME}
            PROOF_CONFIG: ${PROOF_CONFIG}
            RPC_CONFIG: ${RPC_CONFIG}
            SENTRY_DSN: ${SENTRY_DSN}
        depends_on:
            - mongodb
        restart: unless-stopped
        networks:
            - bridge-hub

    consumer-net1:
        build:
            context: .
            dockerfile: Dockerfile.consumer
        environment:
            NODE_ENV: production
            NETWORK_ID: ${CONSUMER_NETWORK_ID}
            NETWORK: ${CONSUMER_NETWORK}
            BRIDGE_SERVICE_URL: ${BRIDGE_SERVICE_URL}
            BRIDGE_CONTRACT_ADDRESS: ${BRIDGE_CONTRACT_ADDRESS}
            MONGODB_CONNECTION_URI: ${MONGODB_CONNECTION_URI}
            MONGODB_DB_NAME: ${MONGODB_DB_NAME}
            SENTRY_DSN: ${SENTRY_DSN}
        depends_on:
            - mongodb
        restart: unless-stopped
        networks:
            - bridge-hub

    autoclaim:
        build:
            context: .
            dockerfile: Dockerfile.autoclaim
        environment:
            NODE_ENV: production
            BRIDGE_HUB_API_URL: http://api:3001
            SOURCE_NETWORKS: ${SOURCE_NETWORKS}
            DESTINATION_NETWORK: ${DESTINATION_NETWORK}
            DESTINATION_NETWORK_CHAINID: ${DESTINATION_NETWORK_CHAINID}
            BRIDGE_CONTRACT: ${BRIDGE_CONTRACT}
            PRIVATE_KEY: ${PRIVATE_KEY}
            RPC_CONFIG: ${RPC_CONFIG}
            SENTRY_DSN: ${SENTRY_DSN}
        depends_on:
            - api
        restart: unless-stopped
        networks:
            - bridge-hub

volumes:
    mongo-data:

networks:
    bridge-hub:
        driver: bridge

Adding consumer instances for additional networks

To index more than one network, duplicate the consumer-net1 block with a unique service name and network-specific environment variables. For example:

consumer-net137:
    build:
        context: .
        dockerfile: Dockerfile.consumer
    environment:
        NETWORK_ID: 137
        NETWORK: mainnet
        BRIDGE_SERVICE_URL: ${BRIDGE_SERVICE_URL_NET137}
        BRIDGE_CONTRACT_ADDRESS: ${BRIDGE_CONTRACT_ADDRESS_NET137}
        MONGODB_CONNECTION_URI: ${MONGODB_CONNECTION_URI}
        MONGODB_DB_NAME: ${MONGODB_DB_NAME}
    depends_on:
        - mongodb
    restart: unless-stopped
    networks:
        - bridge-hub

Common Docker Compose commands

# Start all services in the background
docker-compose up -d

# Follow logs from all services
docker-compose logs -f

# Follow logs from a specific service
docker-compose logs -f api

# Check service status
docker-compose ps

# Restart a single service
docker-compose restart api

# Stop all services
docker-compose down

Kubernetes deployment

Namespace and ConfigMap

apiVersion: v1
kind: Namespace
metadata:
    name: bridge-hub
---
apiVersion: v1
kind: ConfigMap
metadata:
    name: bridge-hub-config
    namespace: bridge-hub
data:
    MONGODB_DB_NAME: "bridge_hub"
    NODE_ENV: "production"

API Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
    name: bridge-hub-api
    namespace: bridge-hub
spec:
    replicas: 3
    selector:
        matchLabels:
            app: bridge-hub-api
    template:
        metadata:
            labels:
                app: bridge-hub-api
        spec:
            containers:
                - name: api
                  image: bridge-hub-api:latest
                  ports:
                      - containerPort: 3000
                  env:
                      - name: MONGODB_CONNECTION_URI
                        valueFrom:
                            secretKeyRef:
                                name: bridge-hub-secrets
                                key: mongodb-uri
                      - name: MONGODB_DB_NAME
                        valueFrom:
                            configMapKeyRef:
                                name: bridge-hub-config
                                key: MONGODB_DB_NAME
                  resources:
                      requests:
                          memory: "2Gi"
                          cpu: "1000m"
                      limits:
                          memory: "4Gi"
                          cpu: "2000m"
                  livenessProbe:
                      httpGet:
                          path: /health
                          port: 3000
                      initialDelaySeconds: 30
                      periodSeconds: 10
                  readinessProbe:
                      httpGet:
                          path: /health
                          port: 3000
                      initialDelaySeconds: 5
                      periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
    name: bridge-hub-api
    namespace: bridge-hub
spec:
    selector:
        app: bridge-hub-api
    ports:
        - port: 80
          targetPort: 3000
    type: LoadBalancer

Apply and manage resources

# Apply all manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secrets.yaml
kubectl apply -f k8s/api-deployment.yaml
kubectl apply -f k8s/consumer-deployment.yaml
kubectl apply -f k8s/auto-claim-deployment.yaml

# Check pod status
kubectl get pods -n bridge-hub

# Follow API logs
kubectl logs -f -n bridge-hub deployment/bridge-hub-api

# Scale the API horizontally
kubectl scale deployment bridge-hub-api --replicas=5 -n bridge-hub

Configuration reference

Never commit secrets to the repository. Use a secret management system such as AWS Secrets Manager, HashiCorp Vault, or Kubernetes Secrets.

API package

Variable	Required	Example	Description
`MONGODB_CONNECTION_URI`	Yes	`mongodb://user:pass@host:27017`	MongoDB connection string
`MONGODB_DB_NAME`	Yes	`bridge_hub`	Database name
`RPC_CONFIG`	Yes	`{"mainnet":{"1":"https://..."}}`	RPC endpoints by network
`PROOF_CONFIG`	Yes	`{"mainnet":{"1":"https://..."}}`	Proof generation endpoints
`PORT`	No	`3000`	HTTP port (default: 3000)
`NODE_ENV`	No	`production`	Environment mode
`SENTRY_DSN`	No	`https://...@sentry.io/...`	Error tracking DSN

Consumer package

Variable	Required	Example	Description
`NETWORK_ID`	Yes	`1`	Network identifier
`NETWORK`	Yes	`mainnet`	Network name (mainnet/testnet/devnet)
`BRIDGE_SERVICE_URL`	Yes	`https://bridge-api.polygon.technology`	Bridge Service API URL
`BRIDGE_CONTRACT_ADDRESS`	Yes	`0x...`	Bridge contract address
`MONGODB_CONNECTION_URI`	Yes	`mongodb://user:pass@host:27017`	MongoDB connection string
`MONGODB_DB_NAME`	Yes	`bridge_hub`	Database name
`ETROG_UPDATE_BLOCK_NUMBER`	No	`0`	Starting block for indexing
`SENTRY_DSN`	No	`https://...@sentry.io/...`	Error tracking DSN

Auto-Claim package

Variable	Required	Example	Description
`BRIDGE_HUB_API_URL`	Yes	`http://api:3000`	Bridge Hub API URL
`SOURCE_NETWORKS`	Yes	`[1,137]`	Source network IDs (JSON array)
`DESTINATION_NETWORK`	Yes	`2442`	Destination network ID
`DESTINATION_NETWORK_CHAINID`	Yes	`2442`	Destination chain ID
`BRIDGE_CONTRACT`	Yes	`0x...`	Bridge contract address
`PRIVATE_KEY`	Yes	`0x...`	Wallet private key for gas funds
`RPC_CONFIG`	Yes	`{"2442":"https://..."}`	RPC endpoints (JSON)
`SENTRY_DSN`	No	`https://...@sentry.io/...`	Error tracking DSN

Adding a new network

Deploy a consumer instance

Start a new consumer with the network’s configuration:

NETWORK_ID=42161 \
NETWORK=mainnet \
BRIDGE_CONTRACT_ADDRESS=0x... \
BRIDGE_SERVICE_URL=https://aggkit-42161.example.com \
MONGODB_CONNECTION_URI=mongodb://... \
bun start

In Docker Compose, add a new consumer-net<id> service block. In Kubernetes, create a new Consumer Deployment manifest.

Update API configuration

Add the new network’s RPC endpoint to RPC_CONFIG and its proof endpoint to PROOF_CONFIG, then restart the API instances so they pick up the change.

Update Auto-Claim configuration

Append the new network ID to the SOURCE_NETWORKS JSON array, then restart Auto-Claim instances.

Verify data flow

Confirm the pipeline is working end to end:

Consumer indexing: Query the MongoDB metadata collection for the new network’s checkpoint.
API serving data: Call GET /transactions?sourceNetworkIds=42161 and confirm results appear.
Auto-Claim detection: Monitor Auto-Claim logs to verify it picks up new transactions.

Troubleshooting

Symptom	Likely cause	Solution
Services crash with MongoDB connection errors	MongoDB is unreachable or credentials are wrong	Verify MongoDB is running (`mongosh $MONGODB_CONNECTION_URI`). Check network connectivity with `telnet mongo-host 27017`. Review credentials in your environment variables.
API queries return no data	Consumer is not running or has not indexed yet	Confirm the Consumer process is active. Check that MongoDB contains documents (`db.transactions.count()`). Review API logs for errors and verify your query parameters.
Transactions stuck in `READY_TO_CLAIM`	Auto-Claim cannot submit transactions	Check that the wallet has sufficient gas on the destination chain. Verify `BRIDGE_HUB_API_URL` is reachable from the Auto-Claim service. Test RPC endpoint connectivity. Confirm the private key is correct.
Excessive memory usage	Unbounded batch sizes or tight poll intervals	Review Consumer batch size settings and increase poll intervals. Add memory limits in Docker or Kubernetes resource specs. Check logs for memory leak indicators.

​Prerequisites

​Infrastructure requirements

​Software requirements

​External services

​Build

​Docker deployment

​Build images

​Docker Compose

​Adding consumer instances for additional networks

​Common Docker Compose commands

​Kubernetes deployment

​Namespace and ConfigMap

​API Deployment

​Apply and manage resources

​Configuration reference

​API package

​Consumer package

​Auto-Claim package

​Adding a new network

​Troubleshooting

Prerequisites

Infrastructure requirements

Software requirements

External services

Build

Docker deployment

Build images

Docker Compose

Adding consumer instances for additional networks

Common Docker Compose commands

Kubernetes deployment

Namespace and ConfigMap

API Deployment

Apply and manage resources

Configuration reference

API package

Consumer package

Auto-Claim package

Adding a new network

Troubleshooting