feat(lib-blockchain): Add DifficultyConfig struct for adaptive diffic… (#652)

* feat(lib-blockchain): Add DifficultyConfig struct for adaptive difficulty adjustment

- Add DifficultyConfig struct with governance-controlled parameters
- Fields: target_timespan, adjustment_interval, min/max_adjustment_factor, last_updated_at_height
- Default values: 14 days, 2016 blocks, 4x max adjustment (Bitcoin-style)
- Add difficulty_config field to Blockchain struct
- Initialize with defaults in Blockchain::new()
- Implement serialization/deserialization for persistence
- Add get_difficulty_config() getter method
- Add comprehensive unit tests for validation and serialization
- Ensure backward compatibility with existing genesis blocks
- Document in lib-blockchain/docs/architecture.md

Resolves #605

* fix(lib-blockchain): Improve DifficultyConfig naming and add governance setter

- Rename min/max_adjustment_factor to max_decrease/increase_factor for clarity
- Add tracing warning when adjustment_interval is zero in target_block_time()
- Add adjust_difficulty_with_config() that uses DifficultyConfig parameters
- Add set_difficulty_config() setter with validation for governance updates
- Update documentation and add test for new adjust function

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* fix: Remove useless port validation on u16 type

* fix: Remove redundant DifficultyConfig re-export

* fix: Avoid unnecessary cloning of DifficultyConfig in difficulty getter

- Add get_difficulty_target_timespan() to retrieve specific field without cloning entire config
- Update blockchain.rs to use the new method instead of cloning whole DifficultyConfig
- Add documentation to get_difficulty_config() noting that it clones (intended for cases needing full config)
- Keep set_difficulty_config() for governance updates as already implemented

* fix: Make with_params validate parameters and return Result

- Changed DifficultyConfig::with_params() to return Result<Self, String>
- Validates all parameters before creating the configuration
- Prevents creation of invalid configs that would fail later
- Added test_difficulty_config_with_params_invalid() to test validation
- Updated existing test to use .expect() for valid parameters

* refactor: Rename difficulty adjustment fields for semantic clarity

- Renamed max_decrease_factor to max_difficulty_decrease_factor
- Renamed max_increase_factor to max_difficulty_increase_factor
- Updated all usages: struct fields, with_params, validate, clamp_timespan
- Updated all tests to use new field names
- Updated blockchain.rs logging to use new field names

These names make it explicit that the fields control difficulty changes,
not timespan directly, eliminating confusion in clamp_timespan docs and impl.
Tests verify all 7 difficulty config tests still pass.

---------

Co-authored-by: Hugo <[email protected]>
Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: 3 people

lib-blockchain/docs/architecture.md

@@ -328,6 +328,33 @@ Web4 Architecture:
 └─────────────────────────────────────────────────┘
 ```
 
+## Consensus Architecture
+
+### Adaptive Difficulty Adjustment
+
+The blockchain uses governance-controlled difficulty parameters through `DifficultyConfig`:
+
+- **Configurable Parameters**: Target timespan, adjustment interval, and adjustment factors
+- **Default Settings**: 14-day timespan, 2016-block interval, 4x max adjustment (Bitcoin-style)
+- **Governance Updates**: Parameters can be modified via DAO proposals using `set_difficulty_config()`
+- **Audit Trail**: `last_updated_at_height` tracks parameter changes
+
+```rust
+pub struct DifficultyConfig {
+    pub target_timespan: u64,         // Default: 14 days (1,209,600 seconds)
+    pub adjustment_interval: u64,      // Default: 2016 blocks
+    pub max_decrease_factor: u64,      // Default: 4 (difficulty can decrease by 4x max)
+    pub max_increase_factor: u64,      // Default: 4 (difficulty can increase by 4x max)
+    pub last_updated_at_height: u64,
+}
+```
+
+**Key Methods:**
+- `target_block_time()` - Calculates target seconds per block (default: 600s)
+- `clamp_timespan()` - Prevents extreme difficulty changes
+- `validate()` - Ensures parameters are within safe ranges
+- `adjust_difficulty_with_config()` - Calculates new difficulty using config parameters
+
 ## Economic Architecture
 
 ### Universal Basic Income System

lib-blockchain/src/blockchain.rs

@@ -7,7 +7,7 @@ use std::collections::{HashMap, HashSet};
 use anyhow::Result;
 use serde::{Serialize, Deserialize};
 use tracing::{info, warn, error, debug};
-use crate::types::{Hash, Difficulty};
+use crate::types::{Hash, Difficulty, DifficultyConfig};
 use crate::transaction::{Transaction, TransactionInput, TransactionOutput, IdentityTransactionData};
 use crate::types::transaction_type::TransactionType;
 use crate::block::Block;
@@ -40,6 +40,8 @@ pub struct Blockchain {
     pub height: u64,
     /// Current mining difficulty
     pub difficulty: Difficulty,
+    /// Difficulty adjustment configuration (governance-controlled)
+    pub difficulty_config: DifficultyConfig,
     /// Total work done (cumulative difficulty)
     pub total_work: u128,
     /// UTXO set for transaction validation
@@ -162,6 +164,7 @@ impl Blockchain {
             blocks: vec![genesis_block.clone()],
             height: 0,
             difficulty: Difficulty::from_bits(crate::INITIAL_DIFFICULTY),
+            difficulty_config: DifficultyConfig::default(),
             total_work: 0,
             utxo_set: HashMap::new(),
             nullifier_set: HashSet::new(),
@@ -798,8 +801,8 @@ impl Blockchain {
                 tokio::runtime::Handle::current().block_on(async {
                     let coord = coordinator.read().await;
                     let interval = coord.get_difficulty_adjustment_interval().await;
-                    let config = coord.get_difficulty_config().await;
-                    (interval, config.target_timespan)
+                    let target_timespan = coord.get_difficulty_target_timespan().await;
+                    (interval, target_timespan)
                 })
             })
         } else {
@@ -913,6 +916,33 @@ impl Blockchain {
         self.height
     }
 
+    /// Get the current difficulty configuration
+    pub fn get_difficulty_config(&self) -> &DifficultyConfig {
+        &self.difficulty_config
+    }
+
+    /// Update the difficulty configuration (for governance updates)
+    ///
+    /// This method validates the new configuration before applying it.
+    /// The `last_updated_at_height` field will be set to the current blockchain height.
+    ///
+    /// # Errors
+    /// Returns an error if the configuration parameters are invalid.
+    pub fn set_difficulty_config(&mut self, mut config: DifficultyConfig) -> Result<()> {
+        config.validate().map_err(|e| anyhow::anyhow!("Invalid difficulty config: {}", e))?;
+        config.last_updated_at_height = self.height;
+        info!(
+            "Updating difficulty config at height {}: target_timespan={}, adjustment_interval={}, max_decrease={}, max_increase={}",
+            self.height,
+            config.target_timespan,
+            config.adjustment_interval,
+            config.max_difficulty_decrease_factor,
+            config.max_difficulty_increase_factor
+        );
+        self.difficulty_config = config;
+        Ok(())
+    }
+
     /// Check if a nullifier has been used
     pub fn is_nullifier_used(&self, nullifier: &Hash) -> bool {
         self.nullifier_set.contains(nullifier)

lib-blockchain/src/integration/consensus_integration.rs

@@ -260,11 +260,21 @@ impl BlockchainConsensusCoordinator {
     }
 
     /// Get the current difficulty configuration
+    ///
+    /// **Note**: This clones the entire DifficultyConfig. For better performance,
+    /// use specific field getters like `get_difficulty_target_timespan()` when you
+    /// only need individual fields.
     pub async fn get_difficulty_config(&self) -> DifficultyConfig {
         let manager = self.difficulty_manager.read().await;
         manager.config().clone()
     }
-    
+
+    /// Get the target timespan for difficulty adjustment without cloning the entire config
+    pub async fn get_difficulty_target_timespan(&self) -> u64 {
+        let manager = self.difficulty_manager.read().await;
+        manager.target_timespan()
+    }
+
     /// Calculate new difficulty using the consensus-owned algorithm
     ///
     /// This is the entry point for blockchain difficulty adjustment.