Skip to main content

​
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:
  1. Poll the Bridge Hub API for transactions with READY_TO_CLAIM status.
  2. Filter the returned transactions by source network and claim type.
  3. For each transaction: fetch the Merkle proof, compute the global index, submit the claim transaction, and wait for on-chain confirmation.
  4. 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 on-chain and do not result in lost funds.

​
Configuration

The auto-claim service is configured through environment variables.
VariableRequiredExampleDescription
BRIDGE_HUB_API_URLYeshttp://api:3000Bridge Hub API URL
SOURCE_NETWORKSYes[1,137]Source network IDs (JSON array)
DESTINATION_NETWORKYes2442Destination network ID
DESTINATION_NETWORK_CHAINIDYes2442Destination chain ID
BRIDGE_CONTRACTYes0x...Bridge contract address
PRIVATE_KEYYes0x...Wallet private key for submitting claims
RPC_CONFIGYes{"2442":"https://..."}RPC endpoints (JSON object)
SENTRY_DSNNohttps://...@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 on-chain 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

ProblemSolution
Transactions stuck in READY_TO_CLAIMCheck that the claiming wallet has sufficient gas on the destination chain.
”API unreachable” errorsVerify BRIDGE_HUB_API_URL is correct and accessible from the auto-claim service.
Nonce conflictsEnsure only one auto-claim instance runs per destination network.
Claims failingCheck RPC endpoint connectivity. Verify the BRIDGE_CONTRACT address is correct for the destination network.