feat: New Staking workflow

README.md

@@ -78,6 +78,8 @@ This project includes the following smart contracts and their metadata:
     - HitchensOrderStatisticsTreeLib
   - Test Token
 
+**`StakeRegistry` / `applyUpdates` (bots & backends):** `applyUpdates(address)` applies the ready prefix of each owner’s update queue. If the next pending item at the queue head is a **due** `WithdrawTokens` or `ExitStake` and payouts are blocked by an active freeze, the call **reverts** with `FrozenWithdrawal()` and the **whole transaction rolls back** (no partial commit from that call). Integrators should treat that as retry-after-unfreeze, or rely on paths that advance the queue internally under different constraints (redistributor-triggered txs, paused migration flows). Inline NatSpec next to `applyUpdates` matches this behaviour.
+
 - Metadata ([Testnet](./testnet_deployed.json),[Mainnet](./mainnet_deployed.json))
   - **Chain ID**: Chain ID of the blockchain.
   - **Network ID**: Network ID.

deploy/local/003_deploy_staking.ts

@@ -4,12 +4,18 @@ import { networkConfig } from '../../helper-hardhat-config';
 const func: DeployFunction = async function ({ deployments, getNamedAccounts, network }) {
   const { deploy, get, log } = deployments;
   const { deployer } = await getNamedAccounts();
-  const swarmNetworkID = networkConfig[network.name]?.swarmNetworkId;
+  const config = networkConfig[network.name] || {};
+  const swarmNetworkID = config.swarmNetworkId;
 
   const token = await get('TestToken');
-  const oracleAddress = (await get('PriceOracle')).address;
 
-  const args = [token.address, swarmNetworkID, oracleAddress];
+  const args = [
+    token.address,
+    swarmNetworkID,
+    config.stakeWaitBase || 2,
+    config.stakeWaitOverlayChange || 2,
+    config.stakeWaitWithdrawal || 2,
+  ];
   await deploy('StakeRegistry', {
     from: deployer,
     args: args,

deploy/main/003_deploy_staking.ts

@@ -4,11 +4,17 @@ import { networkConfig } from '../../helper-hardhat-config';
 const func: DeployFunction = async function ({ deployments, getNamedAccounts, network }) {
   const { deploy, log, get } = deployments;
   const { deployer } = await getNamedAccounts();
-  const swarmNetworkID = networkConfig[network.name]?.swarmNetworkId;
+  const config = networkConfig[network.name] || {};
+  const swarmNetworkID = config.swarmNetworkId;
   const token = await get('Token');
-  const oracleAddress = (await get('PriceOracle')).address;
 
-  const args = [token.address, swarmNetworkID, oracleAddress];
+  const args = [
+    token.address,
+    swarmNetworkID,
+    config.stakeWaitBase || 2,
+    config.stakeWaitOverlayChange || 2,
+    config.stakeWaitWithdrawal || 2,
+  ];
   await deploy('StakeRegistry', {
     from: deployer,
     args: args,

deploy/main/010_deploy_verify.ts

@@ -6,7 +6,8 @@ const func: DeployFunction = async function ({ deployments, network }) {
   const { log, get } = deployments;
 
   if (network.name == 'mainnet' && process.env.MAINNET_ETHERSCAN_KEY) {
-    const swarmNetworkID = networkConfig[network.name]?.swarmNetworkId;
+    const config = networkConfig[network.name] || {};
+    const swarmNetworkID = config.swarmNetworkId;
     const token = await get('Token');
 
     // Verify postageStamp
@@ -27,14 +28,21 @@ const func: DeployFunction = async function ({ deployments, network }) {
 
     // Verify staking
     const staking = await get('StakeRegistry');
-    const argStaking = [token.address, swarmNetworkID, priceOracle.address];
+    const redistribution = await get('Redistribution');
+    const argStaking = [
+      token.address,
+      redistribution.address,
+      swarmNetworkID,
+      config.stakeWaitBase || 2,
+      config.stakeWaitOverlayChange || 2,
+      config.stakeWaitWithdrawal || 2,
+    ];
 
     log('Verifying...');
     await verify(staking.address, argStaking);
     log('----------------------------------------------------');
 
     // Verify redistribution
-    const redistribution = await get('Redistribution');
     const argRedistribution = [staking.address, postageStamp.address, priceOracle.address];
 
     log('Verifying...');

deploy/test/003_deploy_staking.ts

@@ -4,11 +4,17 @@ import { networkConfig } from '../../helper-hardhat-config';
 const func: DeployFunction = async function ({ deployments, getNamedAccounts, network }) {
   const { deploy, log, get } = deployments;
   const { deployer } = await getNamedAccounts();
-  const swarmNetworkID = networkConfig[network.name]?.swarmNetworkId;
+  const config = networkConfig[network.name] || {};
+  const swarmNetworkID = config.swarmNetworkId;
   const token = await get('TestToken');
-  const oracleAddress = (await get('PriceOracle')).address;
 
-  const args = [token.address, swarmNetworkID, oracleAddress];
+  const args = [
+    token.address,
+    swarmNetworkID,
+    config.stakeWaitBase || 2,
+    config.stakeWaitOverlayChange || 2,
+    config.stakeWaitWithdrawal || 2,
+  ];
   await deploy('StakeRegistry', {
     from: deployer,
     args: args,

deploy/test/010_deploy_verify.ts

@@ -6,7 +6,8 @@ const func: DeployFunction = async function ({ deployments, network }) {
   const { log, get } = deployments;
 
   if (process.env.TESTNET_ETHERSCAN_KEY) {
-    const swarmNetworkID = networkConfig[network.name]?.swarmNetworkId;
+    const config = networkConfig[network.name] || {};
+    const swarmNetworkID = config.swarmNetworkId;
 
     // Verify TestNet token
     const token = await get('TestToken');
@@ -34,14 +35,21 @@ const func: DeployFunction = async function ({ deployments, network }) {
 
     // Verify staking
     const staking = await get('StakeRegistry');
-    const argStaking = [token.address, swarmNetworkID, priceOracle.address];
+    const redistribution = await get('Redistribution');
+    const argStaking = [
+      token.address,
+      redistribution.address,
+      swarmNetworkID,
+      config.stakeWaitBase || 2,
+      config.stakeWaitOverlayChange || 2,
+      config.stakeWaitWithdrawal || 2,
+    ];
 
     log('Staking');
     await verify(staking.address, argStaking);
     log('----------------------------------------------------');
 
     // Verify redistribution
-    const redistribution = await get('Redistribution');
     const argRedistribution = [staking.address, postageStamp.address, priceOracle.address];
 
     log('Redistribution');

docs/DEPLOYMENT.md

@@ -18,7 +18,7 @@ The contracts must be deployed in this specific order due to dependencies:
 1. Token (external or TestToken for testnets)
 2. PostageStamp (depends on Token)
 3. PriceOracle (depends on PostageStamp)
-4. StakeRegistry (depends on Token and PriceOracle)
+4. StakeRegistry (depends on Token)
 5. Redistribution (depends on StakeRegistry, PostageStamp, PriceOracle)
 6. Role Setup (connects contracts together)
 ```
@@ -111,7 +111,7 @@ npx hardhat deploy --network mainnet --tags oracle
 
 **Constructor**:
 ```typescript
-[token.address, swarmNetworkId, priceOracle.address]
+[token.address, swarmNetworkId, waitBase, waitOverlayChange, waitWithdrawal]
 ```
 
 **Network IDs** (from `helper-hardhat-config.ts`):

docs/OVERVIEW.md

@@ -43,17 +43,17 @@ User → PostageStamp.createBatch()
 
 ### 2. Staking for Node Operators
 
-Node operators stake tokens to participate in the redistribution game:
+Node operators stake BZZ to participate in the redistribution game:
 
 ```
-Node Operator → StakeRegistry.manageStake()
-  ├─ Calculate overlay from network ID + nonce
-  ├─ Calculate committed stake (in storage units)
-  ├─ Track potential stake (in BZZ tokens)
-  └─ Allow withdrawal of surplus stake
+Node Operator → StakeRegistry (queued updates)
+  ├─ createDeposit / addTokens / increaseHeight / changeOverlay
+  ├─ overlay = keccak256(owner, networkId, nonce)
+  ├─ applyUpdates after round delays
+  └─ withdraw / exit (with WAIT_WITHDRAWAL)
 ```
 
-**Key Concept**: Height parameter allows nodes to register additional storage capacity (2^height multiplier).
+**Key Concept**: Height sets the minimum stake (`MIN_STAKE * 2^height`). Effective stake for the game is the previewed BZZ balance while not frozen (no oracle in staking).
 
 ### 3. Redistribution Game Phases
 
@@ -105,14 +105,13 @@ remainingBalance = normalisedBalance - currentTotalOutPayment()
 
 ### Staking Economics
 
-- **Committed Stake**: Amount of chunks pledged to store (in oracle price units)
-- **Potential Stake**: Actual BZZ tokens staked
-- **Effective Stake**: `min(committed_stake * price * 2^height, potential_stake)`
+- **Balance**: BZZ locked in `StakeRegistry` for the node
+- **Height**: Minimum balance scale (`MIN_STAKE * 2^height`); used with reported depth in redistribution
+- **Effective Stake**: Previewed balance when overlay is set and account is not frozen
 
 **Example**:
-- Node stakes 1000 BZZ at price 1000 chunks/BZZ with height 2
-- Committed stake: 100 chunks
-- Effective stake: min(100 * 1000 * 4, 1000 BZZ) = 1000 BZZ
+- Node deposits 1 BZZ at height 2 (minimum 0.1 * 4 = 0.4 BZZ)
+- `nodeEffectiveStake` returns 1 BZZ (or 0 while frozen)
 
 ### Redistribution Economics
 
@@ -138,7 +137,7 @@ Each contract defines specific roles:
 - `PRICE_UPDATER_ROLE`: Can adjust price based on redundancy (granted to Redistribution)
 
 **StakeRegistry**:
-- `DEFAULT_ADMIN_ROLE`: Change network ID, pause
+- `DEFAULT_ADMIN_ROLE`: Pause / unpause
 - `REDISTRIBUTOR_ROLE`: Freeze and slash deposits (granted to Redistribution)
 
 **Redistribution**:

docs/README.md

@@ -45,10 +45,11 @@ Automatically adjusts the price per chunk based on network redundancy.
 Manages staking for node operators participating in the redistribution game.
 
 **Key Features:**
-- Stake commitment and potential stake
-- Overlay management for nodes
-- Freeze and slash mechanisms for penalties
-- Height-based reserve calculations
+- Queued stake updates (deposit, top-up, height, overlay, withdraw, exit)
+- Overlay derivation from network ID and nonce
+- Effective stake = previewed BZZ balance (gated by freeze)
+- Height-based minimum stake (`MIN_STAKE * 2^height`)
+- Freeze and slash penalties via `REDISTRIBUTOR_ROLE`
 
 ### Redistribution (`Redistribution.sol`)
 Implements the Schelling coordination game for reserve commitment consensus.