feat: mass (un)delegation in stake table contract

staking-cli/DEVELOPER_DOCS.md

@@ -2,30 +2,121 @@
 
 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 -->
+**Table of Contents**
 
-Usage: staking-cli stake-for-demo [OPTIONS]
+- [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 <NUM_VALIDATORS>
-          The number of validators to register.
 
-          The default (5) works for the local native and docker demos.
+- `--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
 
-          [default: 5]
+Example:
 
-      --delegation-config <DELEGATION_CONFIG>
-          [default: VariableAmounts]
-          [possible values: equal-amounts, variable-amounts, multiple-delegators]
+    staking-cli demo stake --num-validators 10 --num-delegators-per-validator 50
 
-  -h, --help
-          Print help (see a summary with '-h')
-```
+### `demo delegate`
 
-Currently supported are these delegation configurations:
+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:
+
+- `--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
+- `--batch-size`: Number of transactions to submit per batch (default: all at once)
+- `--delay`: Delay between batches (e.g., "1s", "500ms"); requires `--batch-size`
+
+Delegators are distributed round-robin across validators.
+
+### `demo undelegate`
+
+Mass undelegate from validators. Queries on-chain delegation amounts and undelegates everything.
+
+    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
+- `--batch-size`: Number of transactions to submit per batch (default: all at once)
+- `--delay`: Delay between batches (e.g., "1s", "500ms"); requires `--batch-size`
+
+Skips delegators with zero delegation to a validator.
+
+### `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,12 +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)
-    - [Getting Help](#getting-help)
+    - [Overview](#overview)
     - [Choose your type of wallet (mnemonic based or Ledger)](#choose-your-type-of-wallet-mnemonic-based-or-ledger)
     - [Initialize the configuration file](#initialize-the-configuration-file)
     - [Inspect the configuration](#inspect-the-configuration)
@@ -26,6 +25,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 -->
 
@@ -82,7 +83,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:
@@ -379,31 +380,7 @@ Format handling:
 - Stdin defaults to JSON: `cat signatures.json | staking-cli register-validator --node-signatures - --commission 4.99`
 - 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.