Auto-Claim Service - Polygon Developer Docs

Overview

The auto-claim service automates the claiming of bridge transactions on the destination chain. It polls the Bridge Hub API for transactions in READY_TO_CLAIM status, fetches Merkle proofs, and submits claim transactions. It handles both ASSET and MESSAGE claim types and filters out zero-amount MESSAGE transactions.

How it works

The auto-claim service runs a continuous polling loop on a 30-second interval. Each cycle follows this sequence:

Poll the Bridge Hub API for transactions with READY_TO_CLAIM status.
Filter the returned transactions by source network and claim type.
For each transaction: fetch the Merkle proof, compute the global index, submit the claim transaction, and wait for onchain confirmation.
Sleep for 30 seconds, then repeat.

        ┌─────────────────┐
        │  Poll API       │
        │  (30s interval) │
        └────────┬────────┘
                 │
                 ▼
        ┌─────────────────┐
        │ Filter Txs      │
        └────────┬────────┘
                 │
                 ▼
        ┌─────────────────┐
        │ For Each Tx:    │
        │ 1. Get Proof    │
        │ 2. Compute Index│
        │ 3. Submit Claim │
        │ 4. Wait Confirm │
        └────────┬────────┘
                 │
                 ▼
        ┌─────────────────┐
        │  Sleep 30s      │
        └────────┬────────┘
                 │
                 └──────→ (repeat)

Claims are processed sequentially to avoid nonce conflicts. One auto-claim instance should run per destination network.

Errors on one transaction do not affect others. The blockchain enforces claim uniqueness, so the service is safe to restart at any time without risk of double-claiming. Failed claim transactions are reverted onchain and do not result in lost funds.

Configuration

The auto-claim service is configured through environment variables.

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 submitting claims
`RPC_CONFIG`	Yes	`{"2442":"https://..."}`	RPC endpoints (JSON object)
`SENTRY_DSN`	No	`https://...@sentry.io/...`	Error tracking DSN

Deployment

Deploy one auto-claim instance for each destination network you want to auto-claim for.

Docker Compose

Add the following service to your docker-compose.yml:

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

Direct execution with Bun

You can also run the service directly:

# Auto-claim for destination network 2442
BRIDGE_HUB_API_URL=http://localhost:3001 \
DESTINATION_NETWORK=2442 \
DESTINATION_NETWORK_CHAINID=2442 \
SOURCE_NETWORKS=[0,1,137] \
BRIDGE_CONTRACT=0x... \
PRIVATE_KEY=0x... \
RPC_CONFIG='{"2442":"https://rpc.example.com"}' \
bun start

To auto-claim for multiple destination networks, run a separate instance for each:

# Instance 1: destination 2442
DESTINATION_NETWORK=2442 DESTINATION_NETWORK_CHAINID=2442 bun start

# Instance 2: destination 1101
DESTINATION_NETWORK=1101 DESTINATION_NETWORK_CHAINID=1101 bun start

Security

The auto-claim service requires a private key to submit onchain transactions. Follow these guidelines to protect it:

Never log or expose private keys. Ensure your logging configuration does not capture environment variables.
Load keys from a secret management system such as AWS Secrets Manager, HashiCorp Vault, or Kubernetes Secrets. Avoid hardcoding keys in configuration files.
Use a dedicated wallet with minimal funding. The wallet only needs enough native tokens to cover gas on the destination chain.
Monitor for unusual activity. Set up alerts for unexpected balance changes or transaction patterns on the claiming wallet.

Claims are atomic: they either succeed or revert entirely. The blockchain enforces uniqueness, so a transaction cannot be claimed twice even if the service processes it again after a restart.

Troubleshooting

Problem	Solution
Transactions stuck in `READY_TO_CLAIM`	Check that the claiming wallet has sufficient gas on the destination chain.
”API unreachable” errors	Verify `BRIDGE_HUB_API_URL` is correct and accessible from the auto-claim service.
Nonce conflicts	Ensure only one auto-claim instance runs per destination network.
Claims failing	Check RPC endpoint connectivity. Verify the `BRIDGE_CONTRACT` address is correct for the destination network.

​Overview

​How it works

​Configuration

​Deployment

​Docker Compose

​Direct execution with Bun

​Security

​Troubleshooting

Overview

How it works

Configuration

Deployment

Docker Compose

Direct execution with Bun

Security

Troubleshooting