> For the complete documentation index, see [llms.txt](https://docs.astralbeam.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.astralbeam.io/operators/configuration.md).

# Configuration

Complete reference for all bridge configuration options.

## Environment Variables

### Multi-Chain EVM Configuration

The bridge supports multiple EVM chains. Environment variables follow the format `{CHAIN_NAME}_RPC_URL` and `{CHAIN_NAME}_LOCKER`.

| Variable               | Required | Default | Description                     |
| ---------------------- | -------- | ------- | ------------------------------- |
| `SEPOLIA_RPC_URL`      | Yes      | -       | Sepolia RPC endpoint            |
| `SEPOLIA_BEACON_URL`   | Yes      | -       | Sepolia beacon API              |
| `SEPOLIA_LOCKER`       | Yes      | -       | Sepolia locker contract address |
| `BASE_SEPOLIA_RPC_URL` | No       | -       | Base Sepolia RPC                |
| `BASE_SEPOLIA_LOCKER`  | No       | -       | Base Sepolia locker address     |

```bash
# Sepolia (Primary)
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
SEPOLIA_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com
SEPOLIA_LOCKER=0x6aaea12cF566C9fddbC7082c15d38F1447a57D10

# Base Sepolia (Optional)
BASE_SEPOLIA_RPC_URL=https://base-sepolia.infura.io/v3/YOUR_KEY
BASE_SEPOLIA_LOCKER=0x5208f75aEa0c2AeC5f71494B5f1B7DCF07cC6000
```

### Casper Network

| Variable                  | Required | Default         | Description                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CASPER_NODE_URL`         | Yes      | -               | Casper RPC endpoint                                                                                                                                                                                                                                                                                                                      |
| `CASPER_PUBLIC_NODE_URLS` | No       | -               | Comma-separated additional public/community Casper RPC endpoints. These count as the *public* source class for the verification diversity gate — a terminal verification verdict requires a public-class source (CSPR.cloud alone can never verify or reject an event). Configure at least one besides `CASPER_NODE_URL` for resilience. |
| `CASPER_CHAIN_NAME`       | Yes      | -               | Chain name (casper-test)                                                                                                                                                                                                                                                                                                                 |
| `CSPR_CLOUD_RPC_URL`      | No       | CSPR.cloud host | CSPR.cloud RPC endpoint. Classified as the *cloud* source class — it can never satisfy the verification diversity gate on its own.                                                                                                                                                                                                       |
| `CASPER_ETH_CLIENT`       | Yes      | -               | EthClient contract hash                                                                                                                                                                                                                                                                                                                  |
| `CASPER_TOKEN_FACTORY`    | Yes      | -               | TokenFactory contract hash                                                                                                                                                                                                                                                                                                               |

```bash
CASPER_NODE_URL=https://node.testnet.casper.network
CASPER_CHAIN_NAME=casper-test
CASPER_ETH_CLIENT=hash-fa183fe46e92b65da88265deb0d48c7ae44bf44d7917f19875f4457321497aa2
CASPER_TOKEN_FACTORY=hash-bf16ba78a7ecfb0e64756aa8468251110f29639f38ccaf9bdb01b6f38a15c2f2
```

### Relayer Keys

| Variable              | Required | Default | Description                    |
| --------------------- | -------- | ------- | ------------------------------ |
| `RELAYER_PRIVATE_KEY` | Yes      | -       | Ethereum private key (0x...)   |
| `CASPER_SECRET_KEY`   | Yes      | -       | Path to Casper secret\_key.pem |

```bash
RELAYER_PRIVATE_KEY=0x1234567890abcdef...
CASPER_SECRET_KEY=/path/to/secret_key.pem
```

### P2P Network

| Variable                           | Required | Default | Description                                                                                                                                                                                                                                      |
| ---------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `P2P_ENABLED`                      | No       | true    | Enable P2P networking                                                                                                                                                                                                                            |
| `P2P_PORT_EVM2CASPER`              | No       | 8080    | EVM→Casper P2P port                                                                                                                                                                                                                              |
| `P2P_PORT_CASPER2EVM`              | No       | 8180    | Casper→EVM P2P port                                                                                                                                                                                                                              |
| `P2P_PEERS`                        | No       | -       | Comma-separated peer addresses                                                                                                                                                                                                                   |
| `P2P_TLS_ENABLED`                  | No       | true    | Enable TLS for P2P                                                                                                                                                                                                                               |
| `P2P_ALLOW_PRIVATE_PEER_ENDPOINTS` | No       | false   | Allow peer endpoints resolving to private/loopback addresses. The DNS-resolving SSRF guard (SSC v3 8.68) otherwise rejects them. Enable only for local test meshes or VPC-internal fleets — peers remain gated by mTLS + on-chain authorization. |
| `P2P_TLS_CERT`                     | No       | -       | TLS certificate path                                                                                                                                                                                                                             |
| `P2P_TLS_KEY`                      | No       | -       | TLS private key path                                                                                                                                                                                                                             |

```bash
P2P_ENABLED=true
P2P_PORT_EVM2CASPER=8080
P2P_PORT_CASPER2EVM=8180
P2P_PEERS=10.0.1.10:8080,10.0.1.11:8080,10.0.1.12:8080
P2P_TLS_ENABLED=true
P2P_TLS_CERT=/path/to/cert.pem
P2P_TLS_KEY=/path/to/key.pem
```

### Relayer Identity

| Variable            | Required | Default | Description                                                                                                                                                                                                                        |
| ------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RELAYER_INDEX`     | Yes      | -       | Relayer index (0-4)                                                                                                                                                                                                                |
| `RELAYER_COUNT`     | No       | 5       | Total relayers                                                                                                                                                                                                                     |
| `RELAYER_THRESHOLD` | No       | 3       | Required signatures. Must be ≥ 2 and a **strict majority** of the relayer set (`threshold × 2 > count`) — enforced on-chain (EVM V14+ / Casper EthClient); relayers log a SECURITY warning if an on-chain threshold is a minority. |

```bash
RELAYER_INDEX=0
RELAYER_COUNT=5
RELAYER_THRESHOLD=3
```

### Fee & Minimum-Amount Safety Rails

The bridge fee is the economic brake on dust-lock relayer griefing: every lock forces all relayers to sign and pay destination-chain gas, so an unmetered lock path drains relayer gas wallets. Configuration interplay to keep in mind:

* **Never run `bridgeFee = 0` AND `minLockAmount = 0` together** on the EVM locker — that is the unmetered-spam precondition. Relayers log a SECURITY warning at startup when they detect it. (Zero-amount locks are always rejected on-chain since V15 regardless of config.)
* **Size the fee against destination gas, not just source-chain UX.** The fee is flat; destination gas is variable. A 50 CSPR fee (\~$0.25) against a several-dollar mainnet-Ethereum mint leaves a 10–20x asymmetry in an attacker's favor. Revisit fee levels when destination gas regimes change.
* **Zero-fee mode rejects attached value**: with fee 0, `lock`/ `burnWrapped` revert on any `msg.value`, and Casper `burn`/`lock_native` revert on any attached CSPR. Wallet integrations must not attach value when the fee reads 0.
* **Casper fee ceiling**: fee setters reject values above 10,000 CSPR (`FeeExceedsMaximum`) so a fat-fingered fee can't brick the bridge.
* **Token remapping caveat** (`update_native_token_mapping`): re-pointing a CEP-18 mapping does not migrate the locked-total accounting recorded under the old token key. Reconcile totals manually after any remap (tooling tracked as a known limitation).

### Submission Claims (Duplicate-Submission Prevention)

Relayers claim in-flight submissions over P2P so backup relayers don't duplicate a transaction that is dispatched but not yet final. Holds are bounded: a claim extends (never resets) the backup failover deadline, hard-capped at `CLAIMS_MAX_ATTEMPTS × CLAIMS_GRACE_SECONDS` from the first claim.

| Variable                       | Required | Default | Description                                                                                |
| ------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `CLAIMS_ENABLED`               | No       | true    | Kill switch — `false` reverts to timed-only failover (no holds, no advisories, no parking) |
| `CLAIMS_GRACE_SECONDS`         | No       | 90      | Hold granted per claim, from its last renewal                                              |
| `CLAIMS_RENEWAL_SECONDS`       | No       | 30      | Interval between claim renewals for our own in-flight txs                                  |
| `CLAIMS_MAX_ATTEMPTS`          | No       | 2       | Distinct tx-hash attempts honored per event (caps total hold)                              |
| `CLAIMS_HASH_DEADLINE_SECONDS` | No       | 15      | A hash-less claim lapses unless a tx hash arrives within this window                       |

Deterministic on-chain rejections (e.g. unregistered token) park the affected event fleet-wide after independent on-chain verification, logged as `SUBMISSION_PERMANENT_FAILURE`. Parked state is in-memory: after fixing the root cause (e.g. registering the token), restart the relayers to resume.

```bash
CLAIMS_ENABLED=true
CLAIMS_GRACE_SECONDS=90
CLAIMS_MAX_ATTEMPTS=2
```

### Gas and Payments

| Variable                         | Required | Default     | Description                                                                              |
| -------------------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------- |
| `CASPER_STANDARD_PAYMENT_AMOUNT` | No       | 45000000000 | Block header submission payment (motes); sized to measured max cost +5%                  |
| `CASPER_MINT_PAYMENT`            | No       | 46000000000 | Mint payment (motes); sized to measured max cost +5% (unused Casper 2.0 gas is refunded) |
| `CASPER_BURN_PAYMENT`            | No       | 2500000000  | Burn payment (motes)                                                                     |

```bash
CASPER_STANDARD_PAYMENT_AMOUNT=45000000000   # 45 CSPR
CASPER_MINT_PAYMENT=46000000000       # 46 CSPR
CASPER_BURN_PAYMENT=2500000000        # 2.5 CSPR
```

### Logging

| Variable     | Required | Default | Description                          |
| ------------ | -------- | ------- | ------------------------------------ |
| `LOG_LEVEL`  | No       | info    | Log level (debug, info, warn, error) |
| `LOG_FORMAT` | No       | json    | Log format (json, pretty)            |

```bash
LOG_LEVEL=debug
LOG_FORMAT=json
```

### Persisted-State Retention

| Variable                            | Required | Default | Description                                                               |
| ----------------------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `CASPER2EVM_PROCESSED_EVENTS_LIMIT` | No       | 10000   | Max processed-event keys retained in Casper2Evm persisted state           |
| `EVM2CASPER_PROCESSED_EVENTS_LIMIT` | No       | 10000   | Max processed-event keys retained per chain in Evm2Casper persisted state |

Retention caps bound persisted-state growth. Events trimmed from local state remain protected by the on-chain processed-event guards, which are the authoritative replay defense; raise these limits if your deployment restarts frequently and you want a larger local dedup window.

```bash
CASPER2EVM_PROCESSED_EVENTS_LIMIT=10000
EVM2CASPER_PROCESSED_EVENTS_LIMIT=10000
```

### Monitoring

| Variable          | Required | Default | Description               |
| ----------------- | -------- | ------- | ------------------------- |
| `METRICS_ENABLED` | No       | true    | Enable Prometheus metrics |
| `METRICS_PORT`    | No       | 9080    | Metrics endpoint port     |

```bash
METRICS_ENABLED=true
METRICS_PORT=9080
```

### API Server

| Variable      | Required | Default | Description       |
| ------------- | -------- | ------- | ----------------- |
| `API_ENABLED` | No       | false   | Enable API server |
| `API_PORT`    | No       | 3001    | API server port   |
| `API_HOST`    | No       | 0.0.0.0 | API bind address  |

```bash
API_ENABLED=true
API_PORT=3001
API_HOST=0.0.0.0
```

## Chain Configuration

### Multi-Chain Setup

For multi-chain deployments, configure each chain:

```bash
# Sepolia (Chain ID: 11155111)
CHAIN_SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/KEY
CHAIN_SEPOLIA_LOCKER=0x...
CHAIN_SEPOLIA_CONFIRMATIONS=64
CHAIN_SEPOLIA_FINALITY_MODE=finalized

# Base Sepolia (Chain ID: 84532)
CHAIN_BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
CHAIN_BASE_SEPOLIA_LOCKER=0x...
CHAIN_BASE_SEPOLIA_CONFIRMATIONS=64
CHAIN_BASE_SEPOLIA_FINALITY_MODE=finalized
```

### Finality Settings

EVM source blocks must pass both the configured protocol-native block tag and the confirmation-depth floor. RPC errors or unsupported tags fail closed; the worker does not automatically fall back to depth-only processing.

| Variable                           | Default       | Description                                                                                            |
| ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `FINALITY_CONFIRMATIONS`           | 64            | Global confirmation floor; each chain enforces the stricter of this value and its per-chain setting    |
| `CHAIN_<CHAIN_NAME>_CONFIRMATIONS` | Chain default | Per-chain depth floor, for example `CHAIN_SEPOLIA_CONFIRMATIONS`                                       |
| `CHAIN_<CHAIN_NAME>_FINALITY_MODE` | `finalized`   | Protocol tag to query: `finalized` or `safe`; `depth-only` is an explicit emergency compatibility mode |
| `FINALIZED_TAG_TTL_MS`             | 12000         | Per-chain cache lifetime for protocol-finality tag lookups, in milliseconds                            |

| Chain            | Chain Default (global floor applies) | Block Time |
| ---------------- | ------------------------------------ | ---------- |
| Ethereum Sepolia | 6                                    | \~12s      |
| Base Sepolia     | 64                                   | \~2s       |
| Polygon Amoy     | 15                                   | \~2s       |

Use `depth-only` only when an RPC serves neither `finalized` nor `safe`. The worker logs a warning at startup whenever this emergency mode is configured.

## Configuration File

Alternatively, use a `config.json` file:

```json
{
  "chains": {
    "sepolia": {
      "chainId": 11155111,
      "rpcUrl": "https://sepolia.infura.io/v3/KEY",
      "lockerAddress": "0x...",
      "confirmations": 64
    },
    "base-sepolia": {
      "chainId": 84532,
      "rpcUrl": "https://sepolia.base.org",
      "lockerAddress": "0x...",
      "confirmations": 64
    }
  },
  "casper": {
    "nodeUrl": "https://node.testnet.casper.network",
    "chainName": "casper-test",
    "ethClient": "hash-...",
    "tokenFactory": "hash-..."
  },
  "relayer": {
    "index": 0,
    "count": 5,
    "threshold": 3
  },
  "p2p": {
    "enabled": true,
    "ports": {
      "eth2casper": 8080,
      "casper2eth": 8180
    },
    "tls": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    }
  }
}
```

Load with:

```bash
bridge-cli --config /path/to/config.json start
```

## Validation

Validate configuration before starting:

```bash
bridge-cli config validate
```

Output:

```
Configuration validation:
✓ Ethereum RPC responsive
✓ Base RPC responsive
✓ Casper RPC responsive
✓ Relayer key valid
✓ Casper key valid
✓ Contract addresses verified
✓ P2P configuration valid
✓ Data directory writable

Configuration is valid!
```

## Example Configurations

### Single Relayer (Development)

```bash
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/KEY
SEPOLIA_LOCKER=0x6aaea12cF566C9fddbC7082c15d38F1447a57D10
CASPER_NODE_URL=https://node.testnet.casper.network
RELAYER_PRIVATE_KEY=0x...
CASPER_SECRET_KEY=./keys/secret_key.pem
P2P_ENABLED=false
LOG_LEVEL=debug
```

### Multi-Relayer (Production)

```bash
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/KEY
SEPOLIA_LOCKER=0x6aaea12cF566C9fddbC7082c15d38F1447a57D10
CASPER_NODE_URL=https://node.testnet.casper.network
RELAYER_PRIVATE_KEY=aws:secretsmanager:bridge/relayer/0/eth_key
CASPER_SECRET_KEY=/opt/bridge/keys/secret_key.pem
RELAYER_INDEX=0
RELAYER_COUNT=5
RELAYER_THRESHOLD=3
P2P_ENABLED=true
P2P_PEERS=10.0.1.11:8080,10.0.1.12:8080,10.0.1.13:8080,10.0.1.14:8080
P2P_TLS_ENABLED=true
LOG_LEVEL=info
METRICS_ENABLED=true
```

> **Note**: Relayers use file-based JSON persistence in the `data/` directory. No database configuration is required for relayer operation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.astralbeam.io/operators/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.