restake 2.1.0 → 3.0.0

package/README.md

@@ -0,0 +1,105 @@
+# staker
+
+Automated validator management CLI for [Swarm](https://ethswarm.org/) 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
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Usage
+
+```bash
+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`](https://github.com/ethersphere/bee-js) — Bee node HTTP client (wallet, stake, postage batch APIs)
+- [`viem`](https://viem.sh/) — Ethereum client for signing and broadcasting transactions on Gnosis Chain
+- [`cafe-utility`](https://github.com/Cafe137/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

package/dist/index.js

@@ -25,19 +25,27 @@ const abi = [
 const n = cafe_utility_1.Arrays.requireNumberArgument(process_1.argv, 'n');
 const bzz = bee_js_1.BZZ.fromFloat(cafe_utility_1.Arrays.requireNumberArgument(process_1.argv, 'bzz'));
 const sleep = cafe_utility_1.Dates.make(cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'sleep'));
-const postageBatchId = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'postage-batch-id');
+const postageBatchIds = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'postage-batch-id')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
 const externalWallet = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'external-wallet');
 const privateKeysPath = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'private-keys-path');
 const jsonRpcUrl = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'json-rpc-url');
 const telegramToken = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'telegram-token');
 const telegramChatId = cafe_utility_1.Arrays.requireStringArgument(process_1.argv, 'telegram-chat-id');
+const stakeThreshold = bee_js_1.BZZ.fromFloat(cafe_utility_1.Arrays.requireNumberArgument(process_1.argv, 'stake-threshold'));
 const BASE_PORT = 1633;
+const ONE_YEAR_SECONDS = 365.25 * 24 * 3600;
 const privateKeys = (0, fs_1.readFileSync)(privateKeysPath, 'utf-8').split('\n').filter(Boolean);
 if (n !== privateKeys.length) {
     console.error(`Expected ${n} private keys, but got ${privateKeys.length}`);
     (0, process_1.exit)(1);
 }
-main();
+main().catch(error => {
+    console.error(error);
+    (0, process_1.exit)(1);
+});
 async function main() {
     await validatePrivateKeys();
     runLoop();
@@ -57,79 +65,119 @@ async function validatePrivateKeys() {
 }
 function runLoop() {
     cafe_utility_1.System.forever(async () => {
-        const port = BASE_PORT + cafe_utility_1.Random.intBetween(0, n - 1);
-        const bee = new bee_js_1.Bee(`http://localhost:${port}`);
-        const wallet = await bee.getWalletBalance();
-        if (wallet.bzzBalance.lt(bzz)) {
-            console.log(`:${port} balance is ${wallet.bzzBalance.toDecimalString()} BZZ, skipping`);
+        const eligiblePorts = await findEligiblePorts();
+        if (eligiblePorts.length === 0) {
+            console.log('no eligible nodes found, skipping');
             return;
         }
-        if (cafe_utility_1.Random.chance(1 / 4)) {
-            await runAction(port, `stake ${bzz.toDecimalString()} BZZ`, () => stake(bee, port));
-        }
-        else if (cafe_utility_1.Random.chance(1 / 3)) {
-            await runAction(port, `transfer ${bzz.toDecimalString()} BZZ to external wallet`, () => transfer(port));
-        }
-        else if (cafe_utility_1.Random.chance(1 / 2)) {
-            await runAction(port, `top up postage batch ${postageBatchId}`, () => topup(bee, port));
+        const port = cafe_utility_1.Arrays.pick(eligiblePorts);
+        const bee = new bee_js_1.Bee(`http://localhost:${port}`);
+        if (cafe_utility_1.Random.chance(1 / 2)) {
+            if (!(await runAction(port, 'top up postage batch', () => tryTopup(bee, port)))) {
+                if (!(await runAction(port, 'stake/aid', () => tryStake(bee, port)))) {
+                    await runAction(port, `transfer ${bzz.toDecimalString()} BZZ to external wallet`, () => doTransfer(port));
+                }
+            }
         }
         else {
-            await runAction(port, `aid weakest node with ${bzz.toDecimalString()} BZZ`, () => aid(port));
+            if (!(await runAction(port, 'stake/aid', () => tryStake(bee, port)))) {
+                if (!(await runAction(port, 'top up postage batch', () => tryTopup(bee, port)))) {
+                    await runAction(port, `transfer ${bzz.toDecimalString()} BZZ to external wallet`, () => doTransfer(port));
+                }
+            }
         }
     }, sleep, console.error);
 }
+async function findEligiblePorts() {
+    const eligible = [];
+    for (let i = 0; i < n; i++) {
+        const port = BASE_PORT + i;
+        const bee = new bee_js_1.Bee(`http://localhost:${port}`);
+        const [wallet, redistribution] = await Promise.all([bee.getWalletBalance(), bee.getRedistributionState()]);
+        if (!redistribution.isFrozen && wallet.bzzBalance.gte(bzz)) {
+            eligible.push(port);
+        }
+    }
+    return eligible;
+}
 async function runAction(port, description, action) {
     try {
-        await action();
-        await sendTelegramMessage(`Port ${port}: ${description} succeeded`);
+        const done = await action();
+        if (done) {
+            await sendTelegramMessage(`Port ${port}: ${description} succeeded`);
+        }
+        return done;
     }
     catch (error) {
         await sendTelegramMessage(`Port ${port}: ${description} failed: ${error}`);
+        throw error;
     }
 }
-async function stake(bee, port) {
-    console.log(`:${port} depositing ${bzz.toDecimalString()} BZZ as stake`);
-    await bee.depositStake(bzz);
-}
-async function transfer(port) {
-    console.log(`:${port} transferring ${bzz.toDecimalString()} BZZ to external wallet`);
-    await transferBZZ(privateKeys[port - BASE_PORT], externalWallet, bzz);
-}
-async function topup(bee, port) {
+async function tryTopup(bee, port) {
+    const eligibleBatchIds = await fetchEligibleBatchIds();
+    if (eligibleBatchIds.length === 0) {
+        console.log(`:${port} no postage batches need topping up`);
+        return false;
+    }
+    const batchId = cafe_utility_1.Arrays.pick(eligibleBatchIds);
     const postageBatches = await bee.getGlobalPostageBatches();
-    const postageBatch = postageBatches.find(batch => batch.batchID.toString() === postageBatchId);
+    const postageBatch = postageBatches.find(batch => batch.batchID.toString() === batchId);
     if (!postageBatch) {
-        console.error(`Postage batch with ID ${postageBatchId} not found`);
-        return;
+        console.error(`:${port} postage batch ${batchId} not found in global batches`);
+        return false;
     }
     const { amount } = await bee.calculateTopUpForBzz(postageBatch.depth, bzz);
-    console.log(`:${port} topping up postage batch ${postageBatchId} with ${amount} amount`);
+    console.log(`:${port} topping up postage batch ${batchId} with ${amount} amount`);
     await bee.topUpBatch(postageBatch.batchID, amount);
-}
-async function aid(port) {
-    const weakestAddress = await findWeakestNodeAddress();
-    const currentAddress = (0, accounts_1.privateKeyToAccount)(ensure0x(privateKeys[port - BASE_PORT])).address;
-    if (weakestAddress && weakestAddress.toLowerCase() !== currentAddress.toLowerCase()) {
-        console.log(`:${port} aiding weakest node ${weakestAddress} with ${bzz.toDecimalString()} BZZ`);
-        await transferBZZ(privateKeys[port - BASE_PORT], weakestAddress, bzz);
+    return true;
+}
+async function tryStake(bee, port) {
+    const stakes = await getNodeStakes();
+    const bottomHalfPorts = getBottomHalfPorts(stakes);
+    if (bottomHalfPorts.has(port)) {
+        const currentStake = stakes.get(port);
+        if (currentStake.gte(stakeThreshold)) {
+            console.log(`:${port} in bottom 50% but stake above threshold, skipping`);
+            return false;
+        }
+        console.log(`:${port} depositing ${bzz.toDecimalString()} BZZ as stake`);
+        await bee.depositStake(bzz);
+        return true;
     }
     else {
-        console.log(`:${port} weakest node is self, skipping aid`);
+        const bottomPorts = [...bottomHalfPorts];
+        const targetPort = cafe_utility_1.Arrays.pick(bottomPorts);
+        const targetAddress = (0, accounts_1.privateKeyToAccount)(ensure0x(privateKeys[targetPort - BASE_PORT])).address;
+        console.log(`:${port} aiding port ${targetPort} (${targetAddress}) with ${bzz.toDecimalString()} BZZ`);
+        await transferBZZ(privateKeys[port - BASE_PORT], targetAddress, bzz);
+        return true;
     }
 }
-async function findWeakestNodeAddress() {
-    let minStake = null;
-    let weakestAddress = null;
-    for (let i = 0; i < n; i++) {
+async function doTransfer(port) {
+    console.log(`:${port} transferring ${bzz.toDecimalString()} BZZ to external wallet`);
+    await transferBZZ(privateKeys[port - BASE_PORT], externalWallet, bzz);
+    return true;
+}
+async function fetchEligibleBatchIds() {
+    const response = await fetch('https://bzz.limo/batches');
+    if (!response.ok) {
+        throw new Error(`Failed to fetch batches: HTTP ${response.status}`);
+    }
+    const batches = (await response.json());
+    return batches.filter(b => postageBatchIds.includes(b.batchID) && b.batchTTL < ONE_YEAR_SECONDS).map(b => b.batchID);
+}
+async function getNodeStakes() {
+    const entries = await Promise.all(Array.from({ length: n }, (_, i) => {
         const port = BASE_PORT + i;
         const bee = new bee_js_1.Bee(`http://localhost:${port}`);
-        const stake = await bee.getStake();
-        if (minStake === null || stake.lt(minStake)) {
-            minStake = stake;
-            weakestAddress = (0, accounts_1.privateKeyToAccount)(ensure0x(privateKeys[i])).address;
-        }
-    }
-    return weakestAddress;
+        return bee.getStake().then(stake => [port, stake]);
+    }));
+    return new Map(entries);
+}
+function getBottomHalfPorts(stakes) {
+    const sorted = [...stakes.entries()].sort((a, b) => (a[1].lt(b[1]) ? -1 : a[1].gt(b[1]) ? 1 : 0));
+    const bottomCount = Math.ceil(n / 2);
+    return new Set(sorted.slice(0, bottomCount).map(([port]) => port));
 }
 async function transferBZZ(privateKey, targetAddress, amount) {
     const account = (0, accounts_1.privateKeyToAccount)(ensure0x(privateKey));
@@ -160,7 +208,7 @@ async function getTransactionCount(address) {
         jsonrpc: '2.0',
         id: 1,
         method: 'eth_getTransactionCount',
-        params: [address.toLowerCase(), 'latest']
+        params: [address.toLowerCase(), 'pending']
     };
     const count = await fetchJsonRpcHexString(payload);
     return parseInt(count, 16);
@@ -171,8 +219,14 @@ async function fetchJsonRpcHexString(payload) {
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(payload)
     });
+    if (!response.ok) {
+        throw new Error(`JSON-RPC request failed: HTTP ${response.status}`);
+    }
     const data = await response.json();
     const object = cafe_utility_1.Types.asObject(data);
+    if (object.error) {
+        throw new Error(`JSON-RPC error: ${JSON.stringify(object.error)}`);
+    }
     return cafe_utility_1.Types.asHexString(object.result, { strictPrefix: true, uneven: true });
 }
 function ensure0x(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "restake",
-    "version": "2.1.0",
+    "version": "3.0.0",
     "description": "",
     "bin": {
         "restake": "./dist/index.js"