ZKStaker bump bot

Minimal bump bot for ZKStaker. This repo is intentionally small and focused on bump execution.

See the simplification blueprint: docs/zkstaker-bump-bot.md.

Configuration

Copy .env.example to .env and fill in values.

Required

• RPC_URL — JSON-RPC endpoint for ZKSync.
• CHAIN_ID — Chain ID for the network.
• STAKER_PROXY_ADDRESS — Proxy address for the ZKStaker contract. STAKER_CONTRACT_ADDRESS is accepted as a legacy alias but must also point at the proxy.

Optional

• EARNING_POWER_CALCULATOR_ADDRESS — Override for the earning power calculator. If unset, the runtime will resolve it from the proxy/event.
• START_BLOCK — Starting block for monitoring (default 0).
• POLL_INTERVAL_MS — Polling interval in milliseconds (default 30000).
• LOG_LEVEL — debug | info | warn | error (default info).

Bump configuration

• BUMP_TIP_RECEIVER — Receiver for the bump tip (default zero address).
• BUMP_TIP_AMOUNT — Tip amount in wei (default 0).
• BUMP_COOLDOWN_MS — Cooldown between checks per deposit (default 300000).
• BUMP_MAX_ATTEMPTS — Max attempts per deposit before pausing checks (default 5).
• BUMP_SCHEDULER_INTERVAL_MS — Scheduler cadence (default 30000).
• BUMP_EXECUTION_INTERVAL_MS — Executor cadence (default 30000).
• DEPOSIT_IDS — Comma-separated deposit IDs to monitor. If empty, the bot will discover active deposits by watching StakeDeposited/StakeWithdrawn events starting at START_BLOCK.

Executor configuration

• EXECUTOR_STRATEGY — wallet (default) or relayer.
• WALLET_PRIVATE_KEY — Private key for the wallet strategy (required when EXECUTOR_STRATEGY=wallet).
• CONFIRMATION_BLOCKS — Receipt confirmations to wait for (default 1).
• REORG_DEPTH — Reorg depth budget for monitoring (default 0; currently informational).

Runtime selection

• COMPONENTS — all (default) or a comma-separated list of monitor,bump,executor.

Storage

• DATABASE_PATH — Path to the JSON database file (default ./data/zksync-staker.json).

Runbook

1. Copy .env.example to .env and set required fields.
2. Set DEPOSIT_IDS to the deposit IDs you want to monitor.
3. Provide WALLET_PRIVATE_KEY for wallet execution.
4. Run npm run build then node dist/index.js (or npm run bump-bot for the slim bump-bot entry point).

ZKSync operational notes

• Use chain ID 324 for mainnet and confirm your RPC provider supports ZKSync.
• Always use the proxy address for runtime calls and the calculator override if needed.
• Defender relayers on ZKSync may require explicit gas limits; use the relayer sender only when the relayer is configured for ZKSync.
• CONFIRMATION_BLOCKS=1 is a safe default; increase for higher finality assurances.

Notes

• Tip defaults to zero; set BUMP_TIP_AMOUNT to enable tips.
• When using COMPONENTS, omit executor to disable transaction submission.