feat: mass (un)delegation in stake table contract

Cargo.toml

@@ -95,6 +95,7 @@ edition = "2021"
 
 [workspace.dependencies]
 alloy = { version = "1.0", features = [
+    "eips",
     "provider-ws",
     "json-rpc",
     "signer-mnemonic",

README.md

@@ -50,16 +50,22 @@ Please note the disclaimer about API stability at the end of the readme.
 
 To generate the documentation locally and view it in the browser, run
 
-    just doc --open
+```sh
+just doc --open
+```
 
 ## Run the tests
 
-    just pull # to pull docker images
-    just test
+```sh
+just pull # to pull docker images
+just test
+```
 
 ## Building figures
 
-    make doc
+```sh
+make doc
+```
 
 ## Building and running
 
@@ -140,15 +146,21 @@ forge doc
 
 To deploy the contracts to a local testnet, first run a dev chain (e.g. `anvil`), then run
 
-    forge script DeployHotShot --broadcast --rpc-url local
+```sh
+forge script DeployHotShot --broadcast --rpc-url local
+```
 
 To deploy to sepolia set `SEPOLIA_RPC_URL` and `MNEMONIC` env vars and run
 
-    forge script DeployHotShot --broadcast --rpc-url sepolia
+```sh
+forge script DeployHotShot --broadcast --rpc-url sepolia
+```
 
 To additionally verify the contract on etherscan set the `ETHERSCAN_API_KEY` env var and run
 
-    forge script DeployHotShot --broadcast --rpc-url sepolia --verify
+```sh
+forge script DeployHotShot --broadcast --rpc-url sepolia --verify
+```
 
 Running the script will save a file with details about the deployment in `contracts/broadcast/$CHAIN_ID`.
 
@@ -238,11 +250,11 @@ docker run --env-file .env.docker -e RUST_LOG=debug ...
 The gas consumption for verifying a plonk proof as well as updating the state of the light client contract can be seen
 by running:
 
-```
-> just gas-benchmarks
-> cat gas-benchmarks.txt
-[PASS] test_verify_succeeds() (gas: 507774)
-[PASS] testCorrectUpdateBench() (gas: 594533)
+```sh
+just gas-benchmarks
+cat gas-benchmarks.txt
+# [PASS] test_verify_succeeds() (gas: 507774)
+# [PASS] testCorrectUpdateBench() (gas: 594533)
 ```
 
 In order to profile the gas consumption of the light client contract do the following:

staking-cli/DEVELOPER_DOCS.md

@@ -2,30 +2,125 @@
 
 The staking-cli can be used to fund the stake table on L1 for our testnet and demos.
 
-```
-cargo run --bin staking-cli -- stake-for-demo --help
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
 
-Usage: staking-cli stake-for-demo [OPTIONS]
+**Table of Contents**
+
+- [staking-cli Developer Docs](#staking-cli-developer-docs)
+  - [Demo Commands](#demo-commands)
+    - [`demo stake`](#demo-stake)
+    - [`demo delegate`](#demo-delegate)
+    - [`demo undelegate`](#demo-undelegate)
+    - [`demo churn`](#demo-churn)
+  - [Delegation Configurations](#delegation-configurations)
+  - [Deprecated Commands](#deprecated-commands)
+
+<!-- markdown-toc end -->
+
+## Demo Commands
+
+The `demo` subcommand provides tools for testing and demonstration purposes.
+
+### `demo stake`
+
+Register validators and create delegators for testing.
+
+    staking-cli demo stake --num-validators 5
+
+Options:
+
+- `--num-validators`: Number of validators to register (default: 5)
+- `--num-delegators-per-validator`: Number of delegators per validator (default: random 2-5, max: 100,000)
+- `--delegation-config`: Delegation configuration mode (default: variable-amounts)
+  - `equal-amounts`: All validators have equal delegation amounts
+  - `variable-amounts`: Variable delegation amounts per validator
+  - `multiple-delegators`: Multiple delegators per validator
+  - `no-self-delegation`: Validators do not self-delegate
+
+Example:
+
+    staking-cli demo stake --num-validators 10 --num-delegators-per-validator 50
+
+### `demo delegate`
+
+Mass delegate to existing validators with deterministic delegator generation.
+
+    staking-cli demo delegate \
+      --validators 0xAAA,0xBBB,0xCCC \
+      --delegator-start-index 0 \
+      --num-delegators 100 \
+      --min-amount 100 \
+      --max-amount 500
 
 Options:
-      --num-validators <NUM_VALIDATORS>
-          The number of validators to register.
 
-          The default (5) works for the local native and docker demos.
+- `--validators`: Comma-separated validator addresses to delegate to
+- `--delegator-start-index`: Starting index for deterministic delegator generation
+- `--num-delegators`: Number of delegators to create
+- `--min-amount`: Minimum delegation amount in ESP
+- `--max-amount`: Maximum delegation amount in ESP
+- `--log-path`: Path to transaction log file for recoverable execution (default:
+  `~/.local/share/espresso-staking-cli/tx_log.json`)
+- `--concurrency`: Number of concurrent transaction submissions (default: 20)
 
-          [default: 5]
+Delegators are distributed round-robin across validators. The transaction log enables resumable execution if
+interrupted.
 
-      --delegation-config <DELEGATION_CONFIG>
-          [default: VariableAmounts]
-          [possible values: equal-amounts, variable-amounts, multiple-delegators]
+### `demo undelegate`
 
-  -h, --help
-          Print help (see a summary with '-h')
-```
+Mass undelegate from validators. Queries on-chain delegation amounts and undelegates everything.
 
-Currently supported are these delegation configurations:
+    staking-cli demo undelegate \
+      --validators 0xAAA,0xBBB \
+      --delegator-start-index 0 \
+      --num-delegators 100
+
+Options:
+
+- `--validators`: Comma-separated validator addresses to undelegate from
+- `--delegator-start-index`: Starting index for delegator generation
+- `--num-delegators`: Number of delegators
+- `--log-path`: Path to transaction log file for recoverable execution (default:
+  `~/.local/share/espresso-staking-cli/tx_log.json`)
+- `--concurrency`: Number of concurrent transaction submissions (default: 20)
+
+Skips delegators with zero delegation to a validator. The transaction log enables resumable execution if interrupted.
+
+### `demo churn`
+
+Continuous delegation/undelegation activity forever. Useful for testing stake table changes.
+
+    staking-cli demo churn \
+      --validator-start-index 20 \
+      --num-validators 5 \
+      --delegator-start-index 0 \
+      --num-delegators 50 \
+      --min-amount 100 \
+      --max-amount 500 \
+      --delay 2s
+
+Options:
+
+- `--validator-start-index`: Starting mnemonic index for validators (default: 20)
+- `--num-validators`: Number of validators to target
+- `--delegator-start-index`: Starting index for delegator generation
+- `--num-delegators`: Number of delegators in the pool
+- `--min-amount`: Minimum delegation amount in ESP
+- `--max-amount`: Maximum delegation amount in ESP
+- `--delay`: Delay between operations (default: "1s")
+
+The churn loop picks random delegators and either delegates (if idle) or undelegates (if delegated).
+
+## Delegation Configurations
+
+Currently supported delegation configurations for `demo stake`:
 
 1. Equal amounts: each validator self delegates an equal amount. Leading to uniform staking weights.
-2. Variable amounts: validator delegate 100, 200, ..., 500 ESP tokens in order. This is currently the default because it
-   used to be the only option.
+2. Variable amounts: validators delegate 100, 200, ..., 500 ESP tokens in order. This is currently the default because
+   it used to be the only option.
 3. Multiple delegators: Like 2, but also adds a randomly chosen number of other delegators to each validator.
+4. No self-delegation: Validators do not self-delegate, only external delegators.
+
+## Deprecated Commands
+
+The `stake-for-demo` command is deprecated and will be removed in a future release. Use `demo stake` instead.

staking-cli/README.md

@@ -5,11 +5,11 @@ WARNING: This CLI is intended for use in testnet purposes only.
 This CLI helps users interact with the Espresso staking contract, either as a delegator or a node operator.
 
 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
-
 **Table of Contents**
 
 - [Espresso staking CLI](#espresso-staking-cli)
   - [Getting Started](#getting-started)
+    - [Overview](#overview)
     - [Getting Help](#getting-help)
     - [Choose your type of wallet (mnemonic, private key, or Ledger)](#choose-your-type-of-wallet-mnemonic-private-key-or-ledger)
     - [Initialize the configuration file](#initialize-the-configuration-file)
@@ -27,6 +27,8 @@ This CLI helps users interact with the Espresso staking contract, either as a de
     - [Updating your metadata URL](#updating-your-metadata-url)
     - [De-registering your validator](#de-registering-your-validator)
     - [Rotating your consensus keys](#rotating-your-consensus-keys)
+    - [Exporting Node Signatures](#exporting-node-signatures)
+    - [Demo Commands](#demo-commands)
 
 <!-- markdown-toc end -->
 
@@ -83,7 +85,7 @@ Commands:
     token-allowance        Check ESP token allowance of stake table contract
     transfer               Transfer ESP tokens
     export-node-signatures       Export validator node signatures for address validation
-    stake-for-demo         Register the validators and delegates for the local demo
+    demo                   Demo commands for testing (stake, delegate, undelegate, churn)
     help                   Print this message or the help of the given subcommand(s)
 
 Options:
@@ -497,31 +499,7 @@ Format handling:
 - Explicit format for stdin:
   `cat signatures.toml | staking-cli register-validator --node-signatures - --format toml --commission 4.99`
 
-### Native Demo Staking
-
-The `stake-for-demo` command is used to set up validators and delegators for testing purposes.
-
-    staking-cli stake-for-demo --num-validators 5
-
-Configuration options:
-
-- `--num-validators`: Number of validators to register (default: 5)
-- `--num-delegators-per-validator`: Number of delegators per validator (default: random 2-5, max: 100,000)
-- `--delegation-config`: Delegation configuration mode (default: variable-amounts)
-  - `equal-amounts`: All validators have equal delegation amounts
-  - `variable-amounts`: Variable delegation amounts per validator
-  - `multiple-delegators`: Multiple delegators per validator
-  - `no-self-delegation`: Validators do not self-delegate
-
-Environment variables:
-
-- `NUM_DELEGATORS_PER_VALIDATOR`: Set the number of delegators per validator
-- `DELEGATION_CONFIG`: Set the delegation configuration mode
-
-Example usage:
-
-    # Create 10 validators with 50 delegators each
-    staking-cli stake-for-demo --num-validators 10 --num-delegators-per-validator 50
+### Demo Commands
 
-    # Using environment variables with native demo
-    env NUM_DELEGATORS_PER_VALIDATOR=1000 DELEGATION_CONFIG=no-self-delegation just demo-native-drb-header
+The `demo` subcommand provides tools for testing and demonstration purposes.
+See [DEVELOPER_DOCS.md](DEVELOPER_DOCS.md) for details.