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

# AutoClaim

> Optional AggKit component that discovers L1 to L2 bridge exits, prepares claim proofs, and submits claim transactions on the destination L2

## What AutoClaim Does

AutoClaim is an opt-in AggKit component that automates the destination-side leg of a bridge transfer. When users bridge assets or messages from L1 to L2, someone has to submit the `claimAsset` or `claimMessage` transaction on the destination L2 before the funds land. AutoClaim performs that submission on the operator's behalf.

AutoClaim runs alongside the other AggKit components, sharing the same L1 and L2 sync sources. It picks up bridge exits from `BridgeSync`, prepares the Merkle proof with data from `L1InfoTreeSync` and a per-claimer `L2GERSync`, and sends the claim through an isolated `EthTxManager`. Each request is persisted through discovery, policy evaluation, proof preparation, submission, and final confirmation.

<Note>
  AutoClaim is L1 to L2 only in this release. L2 to Lx auto-claiming is reserved for future work and must stay disabled.
</Note>

## Where AutoClaim Fits

AutoClaim complements the read-only bridge data that `BridgeSync` and `Bridge Service` already expose. Chain operators and application teams who want claims to happen without user interaction add AutoClaim to their AggKit deployment; operators who prefer users to claim manually leave the component off. It is not required for a chain to connect to Agglayer.

Compared to running the standalone [auto-claim service](/interoperability/agglayer/integrations/bridge-hub/auto-claim/) against Bridge Hub, the AggKit-native AutoClaim reuses the sync components already deployed with AggKit, keeps its state in the same operator environment, and adds per-destination policies and an admin approval workflow.

## Per-Destination Claimers

A single AutoClaim instance can serve multiple destination L2 networks. Each destination is configured as an independent claimer with its own RPC endpoint, bridge contract address, signing key, gas settings, and policy. Claimers do not share nonces, storage, or reorg-detector state; a stuck claim on one destination does not block progress on the others.

Each claimer runs its own `L2GERSync` against the destination L2 to check GER readiness during proof preparation. By default, the claimer inherits `BlockFinality` and `InitialBlockNum` from the shared `[L2GERSync]` section; either value can be overridden per claimer when a destination needs a different finality or start block.

## Claim Policies

Every claimer chooses one of four policies that decide whether an eligible bridge exit is submitted, held for approval, or rejected.

| Policy         | Behavior                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow-all`    | Every eligible request is claimed.                                                                                                                                                                |
| `api-approve`  | Requests wait in `manual-approval-required` status until an operator approves or rejects them through the admin API.                                                                              |
| `no-message`   | Asset claims are submitted; message claims are rejected.                                                                                                                                          |
| `basic-filter` | Requests are checked against an allowlist of origins and tokens, an optional message-claim toggle, and a maximum gas cap. Rejections can optionally fall back to `api-approve` for manual review. |

The `basic-filter` policy is configured under `[AutoClaim.Claimers.Policy]` with:

* `AllowMessageClaims` — whether message claims are eligible at all.
* `AllowedOrigins` — list of origin network IDs. Empty means all origins.
* `AllowedTokens` — list of token addresses. Empty means all tokens.
* `ManualFallback` — when `true`, requests rejected by the filter enter `manual-approval-required` instead of `policy-rejected`.
* `MaxGas` — per-claim gas ceiling. `0` disables the check.

The `api-approve` policy requires the admin REST server to be enabled so approvals and rejections can reach the component.

## Request Lifecycle

AutoClaim persists each discovered exit as a request identified by `origin_network:destination_network:deposit_count`, where `origin_network` is the bridged token's origin network, not necessarily the chain where the bridge was initiated.

A request moves through the following terminal statuses:

* `claimed` — the claim transaction confirmed on the destination L2.
* `policy-rejected` — the policy declined the request without asking for manual review.
* `manual-approval-required` — waiting on an admin decision via the `api-approve` policy or the `basic-filter` fallback.
* `dry-run` — the full pipeline ran but transaction submission was intentionally skipped (see below).
* Failure statuses recording proof preparation or submission errors after retries are exhausted.

Because requests are keyed by deposit count, restarting AutoClaim does not double-claim: an already-claimed exit is skipped on the next discovery pass.

## Dry-Run Mode

Setting `DryRun = true` at the top of the `[AutoClaim]` section runs discovery, policy evaluation, and proof preparation for every eligible request, but stops short of broadcasting the claim transaction. Requests terminate in the distinct `dry-run` status rather than `claimed`. This is intended for staging deployments and for validating configuration changes against real bridge traffic without moving funds.

`dry-run` is separate from `policy-rejected`: it means the pipeline succeeded end-to-end but submission was skipped.

## APIs

Enabling AutoClaim exposes two API surfaces on separate HTTP servers.

**Public read endpoints** are registered on the same `[PublicREST]` server that already hosts Bridge Service, under a distinct `/autoclaim/v1` prefix:

* `GET /autoclaim/v1/bridges` — list AutoClaim requests and their status.
* `GET /autoclaim/v1/bridges/:id` — read a single request.

Bridge Service routes under `/bridge/v1` are unchanged.

**Admin write endpoints** run on a separate `[AdminREST]` server, gated by `[AutoClaim.API].Enabled`. They exist to service the `api-approve` policy and the `basic-filter` manual fallback:

* `POST /autoclaim/v1/bridges/:id/approve`
* `POST /autoclaim/v1/bridges/:id/reject`

Admin requests are subject to length limits on `decider`, `decider_id`, and `reason`, and to a 1 MiB body cap.

## Storage

AutoClaim owns a dedicated SQLite database at `AutoClaim.StoragePath`, holding request state, cursors, and attempt history. Each claimer keeps its own independent `EthTxManager.StoragePath` for signing state and separate per-claimer `L2GERSync` and reorg-detector databases under the AutoClaim storage directory. Storage layouts are isolated per claimer so adding, removing, or resetting one destination does not affect the others.

## Configuration

AutoClaim is opt-in. It only runs if `autoclaim` is added to the AggKit process component list.

The HTTP servers used by AutoClaim are configured at the top level. `[PublicREST]` replaces the previous `[REST]` section for the bridge service; `[AdminREST]` is new and exists solely to host AutoClaim's admin endpoints.

<Warning>
  **Breaking change:** The single top-level `[REST]` section is replaced by `[PublicREST]` (bridge service plus AutoClaim public read endpoints) and `[AdminREST]` (AutoClaim admin endpoints only). Rename `[REST]` to `[PublicREST]` in existing configs; there is no automatic migration. A leftover `[REST]` section is currently ignored and logs a deprecation warning at startup.
</Warning>

Minimal AutoClaim configuration with a single destination and the `allow-all` policy:

```toml theme={null}
[PublicREST]
Host = "0.0.0.0"
Port = 5577
ReadTimeout = "5m"
WriteTimeout = "5m"
MaxRequestsPerIPAndSecond = 10

[AdminREST]
Host = "0.0.0.0"
Port = 5579
ReadTimeout = "5m"
WriteTimeout = "5m"
MaxRequestsPerIPAndSecond = 10

[AutoClaim]
DryRun = false
StoragePath = "{{PathRWData}}/autoclaim.sqlite"

[AutoClaim.API]
Enabled = false

[AutoClaim.L1ToL2BridgeDetector]
Enabled = true
StartBlock = 0
PollInterval = "3s"
RetryAfterErrorPeriod = "1s"
MaxRetryAttemptsAfterError = -1
EtrogL1UpgradeBlock = 0

[AutoClaim.L2ToLxBridgeDetector]
Enabled = false

[[AutoClaim.Claimers]]
Enabled = true
ID = "my-l2"
NetworkType = "evm"
NetworkID = 1
URLRPC = "http://l2-rpc:8545"
BridgeAddr = "0x0000000000000000000000000000000000000000"
PolicyName = "allow-all"
GasOffset = 0
WaitPeriod = "5s"
RetryAfter = "30s"
MaxRetries = 3
# Optional per-claimer overrides for the destination-L2 GER syncer:
# BlockFinality = "LatestBlock"
# InitialBlockNum = 0

[AutoClaim.Claimers.Policy]
AllowMessageClaims = false
AllowedOrigins     = []
AllowedTokens      = []
ManualFallback     = false
MaxGas             = 0

[AutoClaim.Claimers.EthTxManager]
StoragePath = "{{PathRWData}}/autoclaim-claimer-my-l2-ethtx.sqlite"
# PrivateKeys, ForcedGas, MaxGasPrice, RetryInterval, WaitTxToBeMined, and the
# other fields from the standard [EthTxManager] block apply here as well.
```

Add one `[[AutoClaim.Claimers]]` block per destination network. Each block requires its own `ID`, `URLRPC`, `BridgeAddr`, `EthTxManager` configuration, and policy selection.

## Security Considerations

AutoClaim signs and submits transactions on the destination L2, so it holds a private key per claimer. The same operational practices that apply to any signing service apply here: load private keys from a secret manager rather than embedding them in config, run each claimer with a dedicated wallet funded only enough to cover gas, and monitor claim wallets for unexpected balance changes.

The admin REST server should only be exposed on a trusted network. Its endpoints can accept or reject any queued request under the `api-approve` policy.