staker

Automated validator management CLI for Swarm Bee nodes on Gnosis Chain. Runs an infinite loop that performs periodic staking, token transfers, postage batch top-ups, and wealth redistribution across a set of local Bee nodes.

What it does

Each loop iteration:

1. Queries all configured Bee nodes (at http://localhost:1633 through http://localhost:1632+n) for wallet balance and redistribution freeze state
2. Filters to eligible nodes (sufficient BZZ balance, not frozen)
3. Picks a random eligible node and attempts actions in priority order:
   • Postage top-up — fetches TTLs from https://bzz.limo/batches; tops up a random configured batch whose TTL is under 1 year. Skipped if all batches are above 1 year.
   • Stake / aid — checks every node's current stake. Nodes in the bottom 50% by stake deposit BZZ as stake (skipped if already at or above --stake-threshold). Nodes in the top 50% transfer BZZ to a random bottom-50% node to help it stake.
   • External transfer — fallback only when both top-up and stake/aid have nothing to do; sends BZZ to the configured external wallet.
4. The loop coin-flips the order of top-up vs stake/aid on each iteration; the external transfer always runs last.
5. Reports the result (success or failure) to a Telegram chat
6. Sleeps for the configured interval and repeats

Prerequisites

• Node.js 18+
• pnpm
• n Bee nodes running locally on consecutive ports starting at 1633
• A Gnosis Chain RPC endpoint
• A Telegram bot token and chat ID (for notifications)

Install & build

pnpm install
pnpm build

Usage

node dist/index.js \
  --n <count> \
  --bzz <amount> \
  --sleep <interval> \
  --postage-batch-id <batchId1>,<batchId2> \
  --external-wallet <address> \
  --private-keys-path <path> \
  --json-rpc-url <rpcUrl> \
  --telegram-token <token> \
  --telegram-chat-id <chatId> \
  --stake-threshold <bzz>

All arguments are required.

Arguments

| Argument | Description | Example | |---|---|---| | --n | Number of Bee nodes to manage | 3 | | --bzz | BZZ amount per operation | 0.5 | | --sleep | Interval between loop iterations | 5m, 30s | | --postage-batch-id | Comma-separated postage batch IDs to top up | abc...,def... | | --external-wallet | Ethereum address for fund transfers | 0x123... | | --private-keys-path | Path to file with private keys (one per line) | /etc/staker/keys.txt | | --json-rpc-url | Gnosis Chain JSON-RPC endpoint | https://rpc.gnosischain.com | | --telegram-token | Telegram Bot API token | 123456:ABC... | | --telegram-chat-id | Telegram chat ID for notifications | 123456789 | | --stake-threshold | Max BZZ stake before a node stops staking | 250 |

Private keys file

Plain text, one private key per line, with or without 0x prefix. Must contain exactly n keys. On startup the tool validates each key against the corresponding node's Ethereum address and exits if any mismatch is detected.

Project structure

src/index.ts      — all application logic (single file)
dist/index.js     — compiled output (generated by build)
package.json      — dependencies and build script
tsconfig.json     — TypeScript config (ES2022, strict)

Key constants (hardcoded in src/index.ts)

| Name | Value | Purpose | |---|---|---| | BASE_PORT | 1633 | Starting port for Bee node discovery | | BZZ_ADDRESS | 0xdbf3ea6f5bee45c02255b2c26a16f300502f68da | BZZ token contract on Gnosis Chain | | ONE_YEAR_SECONDS | 31,557,600 | TTL threshold below which a postage batch is eligible for top-up |

Dependencies

• @ethersphere/bee-js — Bee node HTTP client (wallet, stake, postage batch APIs)
• viem — Ethereum client for signing and broadcasting transactions on Gnosis Chain
• cafe-utility — CLI argument parsing, scheduling, and utilities

For agents

• Entry point: src/index.ts — the entire application is one file; start there for any changes
• Build command: pnpm build (runs tsc)
• No tests exist — verify changes by reading the logic and checking TypeScript compilation
• No environment variables — all configuration is via CLI arguments
• Blockchain network: Gnosis Chain (chain ID 100); do not change the target network without updating BZZ_ADDRESS and the viem chain config
• Action order is randomised per iteration: a coin flip picks either topup-first or stake/aid-first; the external transfer is always the last resort. runAction() returns false when nothing was done, triggering the fallback.
• Stake/aid logic lives in tryStake(): bottom-50% nodes stake (if under threshold), top-50% nodes transfer BZZ to a random bottom-50% node
• Top-up eligibility is determined by fetchEligibleBatchIds(), which filters configured batch IDs against https://bzz.limo/batches for TTL < 1 year
• Telegram reporting wraps every action via runAction(); if adding a new action, follow the same pattern
• Node indexing: nodes are indexed 0 to n-1; port for node i is BASE_PORT + i; private key index matches node index