rewards O(1) macroblock + cold-start sync + rolling-upgrade mechanism

rewards:
- A: single watermarked emission mint, fixes per-node total_supply divergence
- B: per-epoch merkle root + lazy proof-claim, no eager O(N) accrual / O(N) emission-TX map
- O(1) macroblock: drop reward_heartbeats/reward_light_nodes; apply recomputes super
  (registry + heartbeat popcount>=9) and light (deterministic roster + on-chain bitmaps)
- reg_height: deterministic apply-only registry index (super_registrations_sorted /
  light_roster_sorted), replaces the non-deterministic RAM registry
- NodeActivation registers the canonical super pseudonym so a node is reward-resolvable
  without the separate NodeRegistration TX

cold-start sync:
- verify-before-commit snapshot: discard state on every reject path (no orphaned state)
- serve macroblocks from any synced super-node, not genesis-only
- no peer strike on local state_root_mismatch; quorum (>=2-peer) snapshot height

drift:
- C: block_ts forward-projected median cap -> drift ~0 (deterministic gen+validation)

rolling upgrades:
- feature_gates::is_active(feature, height): height-coordinated consensus-rule activation
- wire protocol-version range tolerance [MIN_SUPPORTED..=CURRENT] (was hard-reject)
- downgrade-safe rocksdb open (list_cf union with known CFs)

Validated: qnet-state 58 + qnet-integration 160 lib tests, 0 regressions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: AIQnetLab

core/qnet-state/src/account.rs

@@ -130,6 +130,12 @@ pub struct Account {
     /// popcount of `heartbeat_slots` for `heartbeat_final_epoch` (the finalized liveness count).
     #[serde(default)]
     pub heartbeat_final_count: u8,
+
+    /// Highest reward epoch this account has already claimed (merkle-claim anti-replay).
+    /// A claim TX is valid only for an epoch strictly greater than this and advances it on
+    /// success. Part of the leaf hash (consensus-bound — see hash_account).
+    #[serde(default)]
+    pub last_claimed_epoch: u64,
 }
 
 /// Account state (alias for compatibility)
@@ -188,6 +194,7 @@ impl Default for AccountState {
             heartbeat_slots: 0,
             heartbeat_final_epoch: 0,
             heartbeat_final_count: 0,
+            last_claimed_epoch: 0,
         }
     }
 }
@@ -262,6 +269,7 @@ impl Account {
             heartbeat_slots: 0,
             heartbeat_final_epoch: 0,
             heartbeat_final_count: 0,
+            last_claimed_epoch: 0,
         }
     }
 
@@ -287,6 +295,7 @@ impl Account {
             heartbeat_slots: 0,
             heartbeat_final_epoch: 0,
             heartbeat_final_count: 0,
+            last_claimed_epoch: 0,
         }
     }
 

core/qnet-state/src/feature_gates.rs

@@ -0,0 +1,55 @@
+//! Consensus feature gates — coordinated activation heights for protocol-rule changes.
+//!
+//! A consensus-rule change that is "born active" diverges the instant one node runs it while peers
+//! still run the old rule — the cause of the rolling-upgrade halt. Binding the change to an
+//! activation HEIGHT lets operators roll out a new binary node-by-node: the new rule stays dormant
+//! until `height`, then EVERY node switches at the same height — no cross-version divergence.
+//!
+//! To ship a rolling-safe consensus change:
+//!   1. add `("feature_id", activation_height)` to `ACTIVATIONS` (a coordinated FUTURE height);
+//!   2. gate the divergent code: `if feature_gates::is_active("feature_id", height) { new } else { old }`;
+//!   3. deploy the binary to all nodes BEFORE `activation_height`.
+//! Genesis-active rules need no entry — the default is active.
+
+/// (feature id, activation height). Empty on this chain — all current rules are genesis-active.
+/// Heights are hardcoded in the binary, so every node agrees without on-chain governance.
+const ACTIVATIONS: &[(&str, u64)] = &[];
+
+/// Core gate: active iff `feature` is unlisted (genesis-active default) or `height` has reached
+/// its scheduled activation. Pure ⇒ identical on every node at the same height.
+fn is_active_at(activations: &[(&str, u64)], feature: &str, height: u64) -> bool {
+    match activations.iter().find(|(f, _)| *f == feature) {
+        Some((_, activation_height)) => height >= *activation_height,
+        None => true,
+    }
+}
+
+/// True iff the consensus `feature` is active at `height` (see module docs).
+pub fn is_active(feature: &str, height: u64) -> bool {
+    is_active_at(ACTIVATIONS, feature, height)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::is_active_at;
+
+    #[test]
+    fn gate_switches_at_activation_height() {
+        let reg = &[("feat_x", 1000u64)][..];
+        assert!(!is_active_at(reg, "feat_x", 999), "dormant before activation height");
+        assert!(is_active_at(reg, "feat_x", 1000), "active exactly at activation height");
+        assert!(is_active_at(reg, "feat_x", 5000), "active after activation height");
+    }
+
+    #[test]
+    fn unlisted_feature_is_genesis_active() {
+        let reg = &[("feat_x", 1000u64)][..];
+        assert!(is_active_at(reg, "other", 0), "unlisted feature active from genesis");
+    }
+
+    #[test]
+    fn production_registry_all_active() {
+        // No scheduled features on this chain ⇒ every gate active from height 0.
+        assert!(super::is_active("any_current_rule", 0));
+    }
+}

core/qnet-state/src/lib.rs

@@ -15,6 +15,7 @@ pub mod state_db;
 pub mod state_manager;
 pub mod errors;
 pub mod state;
+pub mod feature_gates;
 
 #[cfg(feature = "python")]
 mod python_bindings;

core/qnet-state/src/state.rs

@@ -419,6 +419,11 @@ impl StateMerkleTree {
         hasher.update(&account.heartbeat_slots.to_le_bytes());
         hasher.update(&account.heartbeat_final_epoch.to_le_bytes());
         hasher.update(&[account.heartbeat_final_count]);
+        // last_claimed_epoch: reward-claim watermark — ALWAYS in leaf hash (fixed schema,
+        // same rule as pending_rewards/HB). Anti-replay for merkle claims must be
+        // consensus-bound, else nodes diverge on which epochs an account already claimed.
+        hasher.update(b"LCE:");
+        hasher.update(&account.last_claimed_epoch.to_le_bytes());
         // EXCLUDED from hash (non-deterministic or metadata-only):
         //   - reputation: f64 is non-deterministic across platforms
         //   - is_node, node_type, created_at, updated_at: metadata only
@@ -638,6 +643,9 @@ pub struct ChainState {
     pub height: u64,
     /// Total supply in nanoQNC (smallest units: 1 QNC = 10^9 nanoQNC)
     pub total_supply: u64,
+    /// Highest emission macroblock already minted into total_supply.
+    /// Monotonic watermark — makes emission idempotent across re-apply/sync.
+    pub last_minted_emission_mb: u64,
 
     /// Current epoch
     pub epoch: u64,
@@ -650,6 +658,7 @@ impl Default for ChainState {
         Self {
             height: 0,
             total_supply: 0, // FAIR LAUNCH: starts at 0, increases only through Pool 1 Base Emission
+            last_minted_emission_mb: 0,
 
             epoch: 0,
             last_finalized: 0,
@@ -1306,6 +1315,7 @@ impl StateManager {
             heartbeat_slots: 0,
             heartbeat_final_epoch: 0,
             heartbeat_final_count: 0,
+            last_claimed_epoch: 0,
         };
 
         StateMerkleTree::verify_proof(
@@ -1930,7 +1940,33 @@ impl StateManager {
 
         Ok(())
     }
-    
+
+    /// v3 merkle-claim credit: credit a proof-verified reward into the wallet's balance and
+    /// advance the per-account claim watermark. Anti-replay: returns false (no-op) if the
+    /// account already claimed this epoch or a later one. The merkle proof itself is verified
+    /// by the caller (node.rs apply, which holds the epoch root); this enforces the watermark
+    /// and applies the balance credit + Merkle update atomically under the state lock.
+    pub fn claim_reward(&self, wallet: &str, epoch: u64, amount: u64) -> bool {
+        let mut account = self.accounts.entry(wallet.to_string())
+            .or_insert_with(|| Account::new(wallet.to_string()));
+        if epoch <= account.last_claimed_epoch {
+            return false;
+        }
+        account.balance = account.balance.saturating_add(amount);
+        account.last_claimed_epoch = epoch;
+        {
+            let mut tree = self.merkle_tree.write();
+            tree.insert_lazy(wallet, &account);
+        }
+        true
+    }
+
+    /// Highest reward epoch this account has already claimed (0 if never claimed).
+    /// The RPC uses it to find the next unclaimed epoch to build a merkle claim for.
+    pub fn get_last_claimed_epoch(&self, wallet: &str) -> u64 {
+        self.accounts.get(wallet).map(|a| a.last_claimed_epoch).unwrap_or(0)
+    }
+
     /// v2.96: Get pending rewards for an account
     pub fn get_pending_rewards(&self, wallet: &str) -> u64 {
         self.accounts.get(wallet)
@@ -2028,20 +2064,30 @@ impl StateManager {
     /// Emit rewards with MAX_SUPPLY control
     /// amount: emission amount in nanoQNC (smallest units)
     /// Returns: actual emitted amount in nanoQNC (may be less if MAX_SUPPLY reached)
-    pub fn emit_rewards(&self, amount: u64) -> StateResult<u64> {
+    /// Idempotent: mints only when `emission_mb` exceeds the watermark, so re-apply,
+    /// bulk-sync, or any redundant call path can never double- or under-count supply.
+    pub fn emit_rewards(&self, amount: u64, emission_mb: u64) -> StateResult<u64> {
         let mut chain_state = self.chain_state.write();
-        
+
+        // Watermark: each emission macroblock mints exactly once, deterministically.
+        if emission_mb > 0 && emission_mb <= chain_state.last_minted_emission_mb {
+            return Ok(0);
+        }
+
         // Check if we would exceed MAX_SUPPLY (all in nanoQNC)
         let remaining_supply = MAX_QNC_SUPPLY_NANO.saturating_sub(chain_state.total_supply);
         let actual_emission = amount.min(remaining_supply);
-        
+
         if actual_emission == 0 {
             println!("⚠️ MAX_SUPPLY reached: {} QNC. No more emissions possible!", MAX_QNC_SUPPLY);
             return Ok(0);
         }
-        
+
         // Update total supply (in nanoQNC)
         chain_state.total_supply += actual_emission;
+        if emission_mb > 0 {
+            chain_state.last_minted_emission_mb = emission_mb;
+        }
 
         if actual_emission < amount {
             println!("⚠️ Emission limited: requested {} QNC, emitted {} QNC (remaining: {} QNC)",
@@ -2073,6 +2119,7 @@ impl StateManager {
             let mut chain_state = self.chain_state.write();
             chain_state.height = 0;
             chain_state.total_supply = 0; // NO PREMINE - starts at 0!
+            chain_state.last_minted_emission_mb = 0; // reset watermark with supply
             chain_state.epoch = 0;
             chain_state.last_finalized = 0;
         }
@@ -2205,6 +2252,27 @@ mod cache_tests {
         a
     }
 
+    /// B cutover anti-replay: claim_reward credits once per epoch and is monotonic.
+    /// last_claimed_epoch is consensus-bound (SMT leaf) so this property holds network-wide.
+    #[test]
+    fn claim_reward_is_replay_and_monotonic_safe() {
+        let sm = StateManager::new();
+        // First claim for epoch 5 credits and sets the watermark.
+        assert!(sm.claim_reward("w", 5, 100), "first claim must credit");
+        assert_eq!(sm.accounts.get("w").unwrap().balance, 100);
+        assert_eq!(sm.accounts.get("w").unwrap().last_claimed_epoch, 5);
+        // Replaying the SAME epoch must be a no-op (no double credit).
+        assert!(!sm.claim_reward("w", 5, 100), "replaying the same epoch must not credit");
+        assert_eq!(sm.accounts.get("w").unwrap().balance, 100);
+        // An OLDER epoch must be rejected (watermark is monotonic).
+        assert!(!sm.claim_reward("w", 4, 100), "older epoch must not credit");
+        assert_eq!(sm.accounts.get("w").unwrap().balance, 100);
+        // A NEWER epoch credits and advances the watermark.
+        assert!(sm.claim_reward("w", 6, 50), "newer epoch must credit");
+        assert_eq!(sm.accounts.get("w").unwrap().balance, 150);
+        assert_eq!(sm.accounts.get("w").unwrap().last_claimed_epoch, 6);
+    }
+
     #[test]
     fn test_warm_account_cache_hit() {
         let sm = StateManager::new();

core/qnet-state/src/state_db.rs

@@ -87,6 +87,7 @@ impl StateDB {
                     heartbeat_slots: 0,
                     heartbeat_final_epoch: 0,
                     heartbeat_final_count: 0,
+                    last_claimed_epoch: 0,
                 }
             });
 
@@ -155,6 +156,7 @@ impl StateDB {
                     heartbeat_slots: 0,
                     heartbeat_final_epoch: 0,
                     heartbeat_final_count: 0,
+                    last_claimed_epoch: 0,
                 }
             });
 

core/qnet-state/src/transaction.rs

@@ -2444,9 +2444,19 @@ impl Transaction {
                 // v2.96: CLAIM TX - validate and process reward claim
                 // This happens when user calls /api/v1/claim_rewards
                 if let Some(to) = &self.to {
+                    // v3 merkle-claim: the proofs were verified and balances credited in node.rs
+                    // apply Phase 2b (which has storage→epoch root). Skip the legacy pending_rewards
+                    // debit so a merkle claim is not double-applied here.
+                    if let Some(ref d) = self.data {
+                        if let Ok(p) = serde_json::from_str::<serde_json::Value>(d) {
+                            if p.get("claims").is_some() {
+                                return Ok(());
+                            }
+                        }
+                    }
                     let recipient = accounts.entry(to.clone())
                         .or_insert_with(|| Account::new(to.clone()));
-                    
+
                     // v2.96: SECURITY - Check if recipient has sufficient pending rewards
                     if self.amount > recipient.pending_rewards {
                         return Err(StateError::InvalidTransaction(

development/qnet-integration/src/block_pipeline.rs

@@ -2483,16 +2483,11 @@ impl BlockPipeline {
                     metrics.apply_failed.fetch_add(1, Ordering::Relaxed);
                     crate::unified_p2p::clear_block_pending_sync(height);
 
-                    // v14.8: Per-peer local quarantine — repeated state_root
-                    // mismatches from the same peer signal either (a) the
-                    // peer is on a different fork, or (b) the peer is
-                    // actively hostile. Either way, stop wasting apply
-                    // cycles on them for a cooldown window. This is a
-                    // LOCAL defense; on-chain slashing still happens via
-                    // the macroblock analyze_chain_for_slashing path.
-                    if let Some(ref p2p) = ctx.unified_p2p {
-                        p2p.record_apply_strike(&block.from_peer, "state_root_mismatch");
-                    }
+                    // Do NOT strike the peer here: the block already passed signature/hash
+                    // validation before apply, so a state_root_mismatch is a LOCAL-state defect
+                    // (e.g. a contaminated/orphaned base), not the peer's fault. Striking honest
+                    // peers poisoned the pool and blocked cold-start recovery. Genuine forks are
+                    // resolved by fork-choice; malice by on-chain analyze_chain_for_slashing.
                     metrics.mark_apply_idle();
                     continue;
                 }
@@ -2675,7 +2670,7 @@ impl BlockPipeline {
                             }
                         }
                         for (node_id, type_str, wallet) in &apply_result.deferred_registrations {
-                            let _ = ctx.storage.save_node_registration(node_id, type_str, wallet, 1.0);
+                            let _ = ctx.storage.save_node_registration_at_height(node_id, type_str, wallet, 1.0, height);
                         }
                         for mb_idx in &apply_result.deferred_emission_mbs {
                             let mut reward_mgr = ctx.reward_manager.write().await;

development/qnet-integration/src/consensus_v2_node.rs

@@ -187,26 +187,11 @@ pub async fn execute(effects: Vec<Effect>, node_id: &str, p2p: &Arc<SimplifiedP2
                 // it == qc.checkpoint_hash (binds this exact block), and full-verify the QC.
                 let qc_bytes = bincode::serialize(&(checkpoint.clone(), qc.clone())).unwrap_or_default();
                 let excluded = excluded_producers(storage, window);
-                // Emission macroblock (every 160 windows ≈ 4h): record the PREVIOUS epoch's
-                // reward recipients on-chain (Super HBC + Light pings) so the emission TX and
-                // the deterministic crediting (both read these fields) work under v2. Determ-
-                // inistic ⇒ every sealer records the same set. pool2 (fees→producer since
-                // v3.18) / pool3 (Phase 2) stay None. Heavy epoch scan, but 1 window in 160.
-                let (reward_heartbeats, reward_light_nodes) = if window > 0 && window % 160 == 0 {
-                    let ws = (window / 160 - 1) * 14400;
-                    let we = ws + 14400;
-                    // v35: discover recipients from on-chain Heartbeat-TX emitters and key
-                    // eligibility on the UNFORGEABLE per-epoch tally (heartbeat_slots popcount).
-                    // No HBC scan, no self-attested count; sorted output ⇒ identical body on all sealers.
-                    let hb = crate::node::BlockchainNode::collect_heartbeat_summaries_from_chain(storage, ws, we)
-                        .await.ok()
-                        .filter(|s| !s.is_empty())
-                        .and_then(|s| bincode::serialize(&s).ok());
-                    let lt = crate::node::BlockchainNode::collect_ping_commitments_from_blocks(storage, p2p, ws, we)
-                        .await.ok().filter(|m| !m.is_empty())
-                        .and_then(|m| bincode::serialize(&m).ok());
-                    (hb, lt)
-                } else { (None, None) };
+                // Reward recipients are NOT sealed in the macroblock — apply recomputes both Super
+                // (registry + per-epoch heartbeat tally) and Light (on-chain eligibility bitmaps +
+                // deterministic roster), giving an O(1) macroblock with an identical reward root on
+                // every node. pool2/pool3 stay None.
+                let _ = &p2p; // sealing removed; p2p no longer read here
                 // v2 SCALE ANCHOR: cumulative equivocation ban-set as of this window (prev
                 // macroblock's set ∪ this window's verified proofs), sorted for byte-stable
                 // bincode. Lets the next epoch's reputation fold derive bans in O(window)
@@ -232,8 +217,8 @@ pub async fn execute(effects: Vec<Effect>, node_id: &str, p2p: &Arc<SimplifiedP2
                         excluded_producers_for_next_epoch: excluded,
                         consensus_committee: Some(committee),
                         banned_validators,
-                        reward_heartbeats,
-                        reward_light_nodes,
+                        reward_heartbeats: None,
+                        reward_light_nodes: None,
                         ..Default::default()
                     },
                     previous_hash,