Skip to main content

​
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.
AutoClaim is L1 to L2 only in this release. L2 to Lx auto-claiming is reserved for future work and must stay disabled.

​
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 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.
PolicyBehavior
allow-allEvery eligible request is claimed.
api-approveRequests wait in manual-approval-required status until an operator approves or rejects them through the admin API.
no-messageAsset claims are submitted; message claims are rejected.
basic-filterRequests 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.
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.
Minimal AutoClaim configuration with a single destination and the allow-all policy: 
[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.