Worker Commands
Configuration values prefixed YOUR_ are placeholders for your own deployment. For the public testnet use the contract reference; never mix networks or environments.
Commands for managing bridge relayer workers.
Relay commands accept only evm2casper, casper2evm, and both (the default). Unsupported values fail before keys or relay services are initialized; there are no legacy aliases. These CLI values are distinct from the API transaction-direction schema, which is unchanged.
start, status, and stop share .bridge-pid in the current working directory: run them from the same directory. Start stays in the foreground and records one process with its enabled directions. Status reports process existence, not independently verified worker health. stop sends SIGTERM through the existing graceful shutdown path and waits up to 10 seconds; a timeout is a failure, not a forced kill. Default both stops the whole recorded instance. An explicit single direction is allowed only when that is the instance's sole direction; partial stops of a both instance and directions not running are rejected without a signal. service start, service stop, and service restart operate on the entire installed systemd/launchd service and do not accept --direction. Service templates start both.
Missing state means no recorded instance. Malformed/legacy or stale state is never signalled or automatically deleted. Start refuses any existing record, including concurrent startup. After independently confirming the old instance is gone, remove its stale .bridge-pid before restarting; do not remove a live instance's record. Normal shutdown and failed startup clean up only their own record. SIGKILL cannot run cleanup. The state directory must be trusted and local; Linux uses boot ID/process birth ticks, and macOS/BSD uses ps birth time and command to reject reused PIDs.
Changing CLI versions
Stop the foreground relayer with the currently installed CLI, confirm that its process has exited and its owned .bridge-pid has been removed, and only then upgrade or roll back the CLI. If shutdown times out, do not change versions or delete the record while the process remains alive.
Running-instance control across CLI versions is unsupported. In particular, older status/stop implementations do not understand this PID schema: an older stop can delete the record without stopping the new process. Never use an old CLI to control an instance started by a newer version. This restriction does not change Docker/Kubernetes or service-manager lifecycle control.
start
Start relay services.
bridge-cli start [options]
Options:
| Option | Default | Description |
|---|---|---|
-d, --direction <dir> |
both |
Relay direction: evm2casper, casper2evm, or both |
Examples:
# Start all workers
bridge-cli start
# Start only EVM→Casper worker
bridge-cli start --direction evm2casper
# Start only Casper→EVM worker
bridge-cli start --direction casper2evm
Output:
Starting bridge relayer...
Configuration:
Direction: both
Chains: sepolia (11155111), baseSepolia (84532)
P2P: enabled
[12:00:00] INFO: EVM→Casper worker started
[12:00:01] INFO: Casper→EVM worker started
[12:00:02] INFO: Connected to 4 P2P peers
[12:00:02] INFO: Listening for events...
Proactive EVM headers
The EVM-to-Casper worker publishes finalized block headers even when there are no transfers. A queued proposal is not a confirmed submission. Temporary peer finality disagreement is retried without relaxing finality checks; pending headers survive worker restarts. The normal publication interval starts only after confirmation on Casper.
When investigating delays, correlate the chain and block number through quorum, submission and on-chain confirmation. Healthy workers or a proposal log alone do not establish completion. Keep the relayer state volume intact during restarts.
stop
Stop relay services.
bridge-cli stop [options]
Options:
| Option | Default | Description |
|---|---|---|
-d, --direction <dir> |
both |
Relay direction: evm2casper, casper2evm, or both |
Examples:
# Stop all workers
bridge-cli stop
# Stop an instance running only EVM→Casper
bridge-cli stop --direction evm2casper
status
Show relay service status.
bridge-cli status
Output:
Bridge Relayer Status
=====================
Main Process: Running
PID: 12345
Enabled directions: both
Workers share this process; worker health is not independently verified.
Configuration:
Relayer ID: 0
Log Level: info
Contract Addresses:
Sepolia Locker: YOUR_SEPOLIA_LOCKER
Base Locker: YOUR_CHAIN_LOCKER
TokenFactory: YOUR_TOKEN_FACTORY_PACKAGE_HASH
EthClient: YOUR_ETH_CLIENT_PACKAGE_HASH
watch
Launch the full-screen TUI (Terminal User Interface) dashboard.
bridge-cli watch [options]
Options:
| Option | Default | Description |
|---|---|---|
-r, --refresh <seconds> |
2 |
Refresh interval in seconds |
Examples:
# Launch TUI with default refresh
bridge-cli watch
# Launch with 5-second refresh
bridge-cli watch --refresh 5
TUI Dashboard Layout
The dashboard is a blessed-based terminal UI with multiple panels:
┌───────────────────────────────────────────────────────────────────────────────┐
│ CASPER-EVM BRIDGE RELAYER │
├───────────────────────────────────┬───────────────────────────────────────────┤
│ Chain: All Chains [c] │ Peers: [0] Local 1 2 3 4 [Tab] │
├──────────────────┬────────────────┴───┬───────────────────────────────────────┤
│ Eth2Casper │ Casper2Eth │ System │
│ │ │ │
│ Status: Running │ Status: Running │ Uptime: 2d 4h 32m │
│ Last Block: 5.1M │ Last Block: 2.0M │ Memory: 256 MB │
│ Finalized: 5.0M │ Pending: 0 │ Peers: 4/5 │
│ Pending: 2 │ Burns: 42 │ Relayer: R0 (3-of-5) │
│ Locks: 156 │ Unlocks: 38 │ Log Level: info │
│ Burns: 12 │ │ │
├──────────────────┴────────────────────┴───────────────────────────────────────┤
│ Signature Collection │
│ MINT#42: ████████░░ 4/5 (Leader: R2) UNLOCK#15: ██████████ 5/5 Complete │
├───────────────────────────────────────────────────────────────────────────────┤
│ Recent Events │
│ │
│ [12:00:15] Lock detected: 100 USDC (Sepolia → Casper) │
│ [12:00:45] Signature collected: MINT#42 (4/5) │
│ [12:01:00] Mint submitted: 100 USDC to account-hash-abc... │
│ [12:01:30] Burn detected: 50 USDC (Casper → Sepolia) │
│ │
├───────────────────────────────────────────────────────────────────────────────┤
│ Keys: 0=Local, 1-9=Peers, Tab=Cycle | c/C=Chain | 'q' quit, 'h' help │
└───────────────────────────────────────────────────────────────────────────────┘
Dashboard Panels
| Panel | Description |
|---|---|
| Header | Title and current view |
| Chain Selector | Switch between chains (press c to cycle) |
| Peer Selector | View local or remote peer metrics |
| Eth2Casper | EVM→Casper worker status and stats |
| Casper2Eth | Casper→EVM worker status and stats |
| System | Memory, uptime, peer count, relayer info |
| Signature Collection | In-progress multi-sig collection status |
| Events | Scrollable log of recent bridge events |
| Footer | Keyboard shortcuts reference |
Keyboard Shortcuts
| Key | Action |
|---|---|
0 |
Switch to local view |
1-9 |
Switch to peer 1-9 |
Tab |
Cycle to next peer |
Shift+Tab |
Cycle to previous peer |
c |
Cycle to next EVM chain |
C (Shift+c) |
Cycle to previous EVM chain |
h or ? |
Show help dialog |
q, Esc, Ctrl+C |
Quit dashboard |
Peer Switching
The TUI supports viewing metrics from other relayer nodes in the P2P network:
- Local (0): Your own relayer's metrics
- Peers (1-9): Remote peer metrics fetched via HTTP/HTTPS
When viewing a peer, the dashboard fetches their Prometheus metrics endpoint and displays their worker status, signature collection progress, and event logs.
Service Commands
Manage bridge as a systemd service.
service install
Install bridge as a systemd service.
bridge-cli service install [options]
Options:
| Option | Default | Description |
|---|---|---|
--user <user> |
bridge |
Service user |
--config <path> |
- | Configuration file |
Creates /etc/systemd/system/bridge-relayer.service.
service uninstall
Remove systemd service.
bridge-cli service uninstall
service start
Start the systemd service.
bridge-cli service start
Equivalent to: sudo systemctl start bridge-relayer
service stop
Stop the systemd service.
bridge-cli service stop
service restart
Restart the systemd service.
bridge-cli service restart
service status
Show service status.
bridge-cli service status
service logs
View service logs.
bridge-cli service logs [options]
Options:
| Option | Default | Description |
|---|---|---|
--follow |
false |
Follow log output |
--lines <n> |
100 |
Number of lines to show |
--since <time> |
- | Show logs since time |
Examples:
# View last 100 lines
bridge-cli service logs
# Follow logs
bridge-cli service logs --follow
# View logs from last hour
bridge-cli service logs --since "1 hour ago"
Equivalent to: journalctl -u bridge-relayer
Process Management
Production deployments use systemd for process management. The Ansible playbooks automatically configure the systemd service.
Manual systemd Commands
# Check status
sudo systemctl status bridge-relayer
# Start service
sudo systemctl start bridge-relayer
# Stop service
sudo systemctl stop bridge-relayer
# Restart service
sudo systemctl restart bridge-relayer
# View logs
sudo journalctl -u bridge-relayer -f
# Enable on boot
sudo systemctl enable bridge-relayer
Service Configuration
The systemd service file is deployed to /etc/systemd/system/bridge-relayer.service:
[Unit]
Description=AstralBeam Relayer
After=network.target
[Service]
Type=simple
User=bridge
WorkingDirectory=/opt/bridge
ExecStart=/usr/local/bin/bridge-cli start
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
Health Checks
Metrics Endpoint
The relayer exposes Prometheus metrics on port 9090 (configurable):
curl http://localhost:9090/metrics
Manual Health Check
bridge-cli status
Verify all workers show "Running" status.