alpha-clp-completion.cspec
1 # Alpha CLP Completion Plan 2 # component: N004 (clp_system) 3 # status: in_progress 4 # created: 2026-01-05 5 # updated: 2026-01-05 6 7 # === OVERVIEW === 8 overview: 9 purpose: Integrate CLP (Continuous Liveness Proof) into alphaos consensus 10 current_state: Phase 6.3 (consensus integration) COMPLETE, blocked by P1.1 ipc_hooks errors 11 location: alphaos/node/consensus/src/clp/ 12 blocker: P1.1 ipc_hooks.rs has compilation errors (being fixed in separate instance) 13 14 # === EXISTING CODE === 15 existing_modules: 16 clp/types.rs: 17 status: complete 18 provides: [ClpConfig, ClpChallenge, ClpResponse, ValidatorClpStatus, ClpEpochResult] 19 20 clp/challenge.rs: 21 status: complete 22 provides: [ChallengeGenerator] 23 methods: [generate, should_generate, compute_challenge_value] 24 25 clp/response.rs: 26 status: complete 27 provides: [ResponseHandler] 28 methods: [create_response, verify_response] 29 30 clp/aggregator.rs: 31 status: complete 32 provides: [ResponseAggregator] 33 methods: [register_challenge, record_response, finalize_challenge, all_statuses] 34 35 clp/penalty.rs: 36 status: complete 37 provides: [PenaltyEvaluator, GovernorClpImpact] 38 methods: [evaluate_epoch, calculate_slash] 39 40 # === INTEGRATION STATUS === 41 completed: 42 - mod_clp_exported: lib.rs now imports clp module (pub mod clp;) 43 - clp_manager_created: manager.rs with ClpManager orchestrator 44 - challenge_generation_wired: on_block_finalized() called in try_advance_to_next_block 45 - epoch_boundary_detection: evaluate_epoch() called at epoch boundary 46 - serde_dependency_added: Cargo.toml updated for serialization 47 48 remaining: 49 - no_response_collection: responses not collected from network (deferred: 6.3.4) 50 - no_slash_application: slashes not yet applied to staking (deferred: 6.4.3) 51 - no_ejection_processing: ejections not yet processed (deferred: 6.4.4) 52 - no_api_endpoints: CLP status not exposed via REST (phase 6.5) 53 - no_ci_tests: module tests exist but no integration tests in CI (phase 6.6) 54 55 # === PHASES === 56 phases: 57 phase_6.3_proof_submission: 58 description: Integrate CLP into consensus block production 59 status: COMPLETE (code done, blocked by P1.1 ipc_hooks errors) 60 tasks: 61 - id: 6.3.1 62 task: Export clp module in lib.rs 63 status: DONE 64 file: alphaos/node/consensus/src/lib.rs 65 change: "pub mod clp;" 66 67 - id: 6.3.2 68 task: Add ClpManager struct to orchestrate CLP 69 status: DONE 70 file: alphaos/node/consensus/src/clp/manager.rs (NEW - 209 lines) 71 provides: 72 - new(config, validator_list) 73 - start_epoch(epoch, validators) 74 - on_block_finalized(height, hash) 75 - process_response(response) 76 - finalize_expired_challenges(current_block) 77 - evaluate_epoch() 78 79 - id: 6.3.3 80 task: Wire ClpManager into Consensus struct 81 status: DONE 82 file: alphaos/node/consensus/src/lib.rs 83 changes: 84 - added clp_manager: Option<Arc<ClpManager>> field 85 - added set_clp_manager(), has_clp_manager(), clp_manager() methods 86 - wired on_block_finalized() in try_advance_to_next_block 87 - wired finalize_expired_challenges() after block commit 88 - wired evaluate_epoch() at epoch boundary 89 90 - id: 6.3.4 91 task: Add CLP response gossip to network layer 92 status: DEFERRED 93 file: alphaos/node/router/src/handshake.rs 94 note: validators gossip ClpResponse messages - needs P2P work 95 96 phase_6.4_epoch_distribution: 97 description: Apply CLP penalties at epoch boundaries 98 status: PARTIAL (detection done, application deferred) 99 tasks: 100 - id: 6.4.1 101 task: Detect epoch boundary in block commit 102 status: DONE 103 file: alphaos/node/consensus/src/lib.rs 104 trigger: "next_block.height() % N::NUM_BLOCKS_PER_EPOCH == 0" 105 106 - id: 6.4.2 107 task: Call PenaltyEvaluator.evaluate_epoch() 108 status: DONE 109 integration: in try_advance_to_next_block after epoch check 110 111 - id: 6.4.3 112 task: Apply slashes to validator stakes 113 status: DEFERRED 114 integration: submit stake reduction transactions 115 note: requires alphavm_staking integration 116 117 - id: 6.4.4 118 task: Process validator ejections 119 status: DEFERRED 120 integration: remove from committee on next epoch 121 note: requires committee management integration 122 123 phase_6.5_metrics_api: 124 description: Expose CLP status via REST API 125 tasks: 126 - id: 6.5.1 127 task: Add /alpha/clp/status endpoint 128 returns: [current_epoch, active_challenges, validator_statuses] 129 130 - id: 6.5.2 131 task: Add /alpha/clp/validator/{address} endpoint 132 returns: [response_rate, consecutive_failures, status] 133 134 - id: 6.5.3 135 task: Add Prometheus metrics 136 metrics: 137 - alphaos_clp_challenges_issued_total 138 - alphaos_clp_responses_received_total 139 - alphaos_clp_validators_slashed_total 140 - alphaos_clp_validators_ejected_total 141 142 phase_6.6_ci_tests: 143 description: Add CI test coverage 144 tasks: 145 - id: 6.6.1 146 task: Integration test for challenge/response flow 147 test: multi-validator scenario with responses 148 149 - id: 6.6.2 150 task: Integration test for epoch penalty 151 test: simulate failing validator, verify slash 152 153 - id: 6.6.3 154 task: Add CLP tests to CI workflow 155 file: alphaos/.forgejo/workflows/ci.yml 156 157 # === DEPENDENCIES === 158 dependencies: 159 - alphavm_staking: for applying slashes 160 - alphaos_network: for gossip responses 161 - alphaos_api: for REST endpoints 162 163 # === EXECUTION ORDER === 164 execution: 165 recommended_order: [6.3.1, 6.3.2, 6.3.3, 6.4.1, 6.4.2, 6.5.1, 6.6.1] 166 parallel_candidates: [6.5.2, 6.5.3] # can run after 6.5.1 167 deferred: [6.3.4, 6.4.3, 6.4.4] # require more network integration 168 169 # === RISK ASSESSMENT === 170 risks: 171 - id: R1 172 description: Network gossip for responses may need P2P changes 173 mitigation: start with local-only testing, add gossip later 174 175 - id: R2 176 description: Slash transactions may fail if stake insufficient 177 mitigation: add validation before slash attempt