> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Claim Service

> Automated bridge transaction claiming: configuration, deployment, and security.

## 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)
```

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

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.

| 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`:

```yaml theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<Warning>
  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.
</Warning>

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. |