T006-validator_earn_in.plan.cspec
1 # T006 Validator Earn-In Implementation Plan 2 # Generated: 2026-01-07 3 # Planning Worker: Wave 1 (depends on T001, T002) 4 5 plan_metadata: 6 component_id: T006 7 component_ref: components/tokens/T006-validator_earn_in.component.cspec 8 plan_version: 1.1.0 9 plan_status: draft 10 created: 2026-01-07 11 updated: 2026-01-07 12 13 wave_context: 14 topological_level: 1 15 is_root: false 16 upstream_components: [T001, T002] 17 downstream_components: [] 18 critical_path: true 19 cascade_group: validator_bootstrap 20 21 # === IMPLEMENTATION PHASES === 22 phases: 23 - phase_id: phase_1 24 name: Validator Registration and Types 25 status: pending 26 blocked_by: 27 - dependency_ref: T001.phase_1 28 reason: "Need AX type definitions for stake denomination" 29 wait_for: complete 30 - dependency_ref: T002.phase_1 31 reason: "Need DX type definitions for grants" 32 wait_for: complete 33 34 tasks: 35 - task_id: T006-T001 36 name: Define validator types and constants 37 description: "VAL type with max:300, stake_req:100k_AX, dx_grant:100k" 38 target_files: 39 - path: adnet/src/consensus/validator/types.rs 40 action: create 41 - path: adnet/src/consensus/validator/mod.rs 42 action: modify 43 estimate: 44 effort: medium 45 confidence: high 46 risk: 47 level: low 48 factors: [clear_spec_from_tokenomics] 49 50 - task_id: T006-T002 51 name: Define provisional validator status 52 description: "Status enum: Provisional, Active, Slashed, Exited with state transitions" 53 target_files: 54 - path: adnet/src/consensus/validator/status.rs 55 action: create 56 estimate: 57 effort: small 58 confidence: high 59 risk: 60 level: low 61 factors: [] 62 63 - task_id: T006-T003 64 name: Define earn-in state structure 65 description: "Track accumulated AX towards 100k stake threshold" 66 target_files: 67 - path: adnet/src/consensus/validator/earn_in_state.rs 68 action: create 69 estimate: 70 effort: medium 71 confidence: high 72 risk: 73 level: low 74 factors: [] 75 76 - task_id: T006-T004 77 name: Define governor exception types 78 description: "GOV type with mint_own_stake, 1M_DX_immediate, sovereign status" 79 target_files: 80 - path: adnet/src/consensus/validator/governor.rs 81 action: create 82 estimate: 83 effort: small 84 confidence: high 85 risk: 86 level: low 87 factors: [] 88 89 deliverables: 90 - deliverable_id: T006-D001 91 name: Validator type definitions 92 type: interface 93 verification: "Types compile, constants match tokenomics spec" 94 - deliverable_id: T006-D002 95 name: Validator status state machine 96 type: code 97 verification: "Status transitions are valid per spec" 98 - deliverable_id: T006-D003 99 name: Earn-in state tracking 100 type: code 101 verification: "State persists and updates correctly" 102 103 test_requirements: 104 unit: 105 - test_id: T006-UT001 106 description: "Validator max count is 300" 107 - test_id: T006-UT002 108 description: "Stake requirement is exactly 100,000 AX" 109 - test_id: T006-UT003 110 description: "DX grant amount is exactly 100,000 DX" 111 - test_id: T006-UT004 112 description: "Governor DX grant is exactly 1,000,000 DX" 113 - test_id: T006-UT005 114 description: "Status transitions are valid only in allowed directions" 115 116 success_criteria: 117 - "All validator types compile with no warnings" 118 - "Constants match tokenomics specification exactly" 119 - "Status state machine validated" 120 - "Unit tests pass (5 minimum)" 121 122 estimated_duration: 2d 123 124 - phase_id: phase_2 125 name: Registration and DX Grant Allocation 126 status: pending 127 blocked_by: 128 - dependency_ref: T002.phase_3 129 reason: "Need network pool grants interface for DX allocation" 130 wait_for: complete 131 - dependency_ref: T006.phase_1 132 reason: "Need validator types defined" 133 wait_for: complete 134 135 tasks: 136 - task_id: T006-T005 137 name: Implement validator registration 138 description: "register_validator function: KYC check, allocate locked DX grant" 139 target_files: 140 - path: adnet/src/consensus/validator/registration.rs 141 action: create 142 - path: adnet/src/consensus/validator/mod.rs 143 action: modify 144 estimate: 145 effort: large 146 confidence: medium 147 risk: 148 level: medium 149 factors: [kyc_integration, dx_grant_atomicity] 150 151 - task_id: T006-T006 152 name: Implement DX grant locking 153 description: "Allocated DX is locked+staked, cannot be transferred until paid" 154 target_files: 155 - path: adnet/src/consensus/validator/dx_lock.rs 156 action: create 157 estimate: 158 effort: medium 159 confidence: medium 160 risk: 161 level: medium 162 factors: [lock_enforcement_security] 163 164 - task_id: T006-T007 165 name: Implement validator registry 166 description: "Track all validators: provisional and active, enforce max:300" 167 target_files: 168 - path: adnet/src/consensus/validator/registry.rs 169 action: create 170 estimate: 171 effort: medium 172 confidence: high 173 risk: 174 level: low 175 factors: [] 176 177 - task_id: T006-T008 178 name: Emit validator_registered event 179 description: "Event emission for registration with all relevant data" 180 target_files: 181 - path: adnet/src/consensus/validator/events.rs 182 action: create 183 estimate: 184 effort: small 185 confidence: high 186 risk: 187 level: low 188 factors: [] 189 190 deliverables: 191 - deliverable_id: T006-D004 192 name: Validator registration module 193 type: code 194 verification: "cargo test validator_registration" 195 - deliverable_id: T006-D005 196 name: DX grant lock mechanism 197 type: code 198 verification: "Locked grants cannot be transferred" 199 - deliverable_id: T006-D006 200 name: Validator registry 201 type: code 202 verification: "Registry enforces max validator count" 203 - deliverable_id: T006-D007 204 name: Registration events 205 type: code 206 verification: "Events emitted with correct data" 207 208 test_requirements: 209 unit: 210 - test_id: T006-UT006 211 description: "Registration fails without KYC" 212 - test_id: T006-UT007 213 description: "Registration allocates exactly 100k DX" 214 - test_id: T006-UT008 215 description: "Locked DX transfer fails" 216 - test_id: T006-UT009 217 description: "Registry rejects 301st validator" 218 - test_id: T006-UT010 219 description: "validator_registered event emitted" 220 integration: 221 - test_id: T006-IT001 222 description: "Full registration flow with DX grant from T002" 223 dependencies: [T002.interface_dx_balance] 224 225 success_criteria: 226 - "Registration requires valid KYC" 227 - "DX grants are locked immediately upon allocation" 228 - "Max validator count enforced" 229 - "Events emitted correctly" 230 231 estimated_duration: 4d 232 233 - phase_id: phase_3 234 name: Earn-In Period and Fee Accumulation 235 status: pending 236 blocked_by: 237 - dependency_ref: T001.phase_3 238 reason: "Need AX mint interface for fee distribution" 239 wait_for: complete 240 - dependency_ref: T001.phase_4 241 reason: "Need AX transfer interface for fee accumulation" 242 wait_for: complete 243 - dependency_ref: T006.phase_2 244 reason: "Need registration complete" 245 wait_for: complete 246 247 tasks: 248 - task_id: T006-T009 249 name: Implement fee share calculation 250 description: "Calculate validator's share of block fees based on participation" 251 target_files: 252 - path: adnet/src/consensus/validator/fee_share.rs 253 action: create 254 estimate: 255 effort: medium 256 confidence: medium 257 risk: 258 level: medium 259 factors: [fee_calculation_precision] 260 261 - task_id: T006-T010 262 name: Implement earn-in accumulation 263 description: "Lock earned fees to AX stake, cannot spend during earn-in" 264 target_files: 265 - path: adnet/src/consensus/validator/earn_in.rs 266 action: create 267 estimate: 268 effort: large 269 confidence: medium 270 risk: 271 level: high 272 factors: [lock_logic_complexity, state_consistency] 273 274 - task_id: T006-T011 275 name: Implement continuous liveness proof (CLP) 276 description: "Track uptime >= 95%, consensus participation >= 99%" 277 target_files: 278 - path: adnet/src/consensus/validator/liveness.rs 279 action: create 280 estimate: 281 effort: large 282 confidence: medium 283 risk: 284 level: high 285 factors: [uptime_measurement_accuracy, byzantine_resistance] 286 287 - task_id: T006-T012 288 name: Implement performance monitoring 289 description: "Track metrics: uptime, participation, slashing events" 290 target_files: 291 - path: adnet/src/consensus/validator/performance.rs 292 action: create 293 estimate: 294 effort: medium 295 confidence: high 296 risk: 297 level: medium 298 factors: [metric_accuracy] 299 300 - task_id: T006-T013 301 name: Emit earn_in_started event 302 description: "Event when validator begins earning towards stake" 303 target_files: 304 - path: adnet/src/consensus/validator/events.rs 305 action: modify 306 estimate: 307 effort: small 308 confidence: high 309 risk: 310 level: low 311 factors: [] 312 313 deliverables: 314 - deliverable_id: T006-D008 315 name: Fee share calculation module 316 type: code 317 verification: "Fee shares sum to 100% across validators" 318 - deliverable_id: T006-D009 319 name: Earn-in accumulation logic 320 type: code 321 verification: "Fees locked to stake, cannot be spent" 322 - deliverable_id: T006-D010 323 name: Continuous liveness proof 324 type: code 325 verification: "CLP tracks uptime and participation correctly" 326 - deliverable_id: T006-D011 327 name: Performance monitoring 328 type: code 329 verification: "Metrics accurate within 0.1%" 330 331 test_requirements: 332 unit: 333 - test_id: T006-UT011 334 description: "Fee share proportional to participation" 335 - test_id: T006-UT012 336 description: "Earned fees locked to stake account" 337 - test_id: T006-UT013 338 description: "Cannot spend locked earn-in AX" 339 - test_id: T006-UT014 340 description: "CLP tracks uptime correctly" 341 - test_id: T006-UT015 342 description: "Participation below 99% flagged" 343 - test_id: T006-UT016 344 description: "Uptime below 95% flagged" 345 integration: 346 - test_id: T006-IT002 347 description: "Fee accumulation over multiple blocks" 348 dependencies: [T001.interface_transfer] 349 - test_id: T006-IT003 350 description: "CLP validation across consensus rounds" 351 dependencies: [] 352 353 success_criteria: 354 - "Fee shares calculated correctly per block" 355 - "Earned AX locked until 100k threshold" 356 - "CLP enforces uptime >= 95%" 357 - "CLP enforces participation >= 99%" 358 - "Performance metrics accurate" 359 360 estimated_duration: 6d 361 362 - phase_id: phase_4 363 name: Stake Completion and Status Transition 364 status: pending 365 blocked_by: 366 - dependency_ref: T001.interface_ax_balance 367 reason: "Need balance query to check stake threshold" 368 wait_for: interface_stable 369 - dependency_ref: T006.phase_3 370 reason: "Need earn-in accumulation working" 371 wait_for: complete 372 373 tasks: 374 - task_id: T006-T014 375 name: Implement stake completion check 376 description: "Detect when earned AX reaches 100k threshold" 377 target_files: 378 - path: adnet/src/consensus/validator/stake_completion.rs 379 action: create 380 estimate: 381 effort: medium 382 confidence: high 383 risk: 384 level: low 385 factors: [threshold_precision] 386 387 - task_id: T006-T015 388 name: Implement status transition to Active 389 description: "Transition from Provisional to Active validator" 390 target_files: 391 - path: adnet/src/consensus/validator/status.rs 392 action: modify 393 estimate: 394 effort: small 395 confidence: high 396 risk: 397 level: low 398 factors: [] 399 400 - task_id: T006-T016 401 name: Implement post-completion earnings 402 description: "Future earnings are freely spendable after stake completion" 403 target_files: 404 - path: adnet/src/consensus/validator/earn_in.rs 405 action: modify 406 estimate: 407 effort: medium 408 confidence: high 409 risk: 410 level: medium 411 factors: [unlock_logic_correctness] 412 413 - task_id: T006-T017 414 name: Emit stake_completed event 415 description: "Event when validator reaches full stake" 416 target_files: 417 - path: adnet/src/consensus/validator/events.rs 418 action: modify 419 estimate: 420 effort: small 421 confidence: high 422 risk: 423 level: low 424 factors: [] 425 426 deliverables: 427 - deliverable_id: T006-D012 428 name: Stake completion detection 429 type: code 430 verification: "Completion detected at exactly 100k AX" 431 - deliverable_id: T006-D013 432 name: Status transition to Active 433 type: code 434 verification: "Provisional -> Active transition works" 435 - deliverable_id: T006-D014 436 name: Post-completion earnings 437 type: code 438 verification: "Earnings after completion are spendable" 439 440 test_requirements: 441 unit: 442 - test_id: T006-UT017 443 description: "Completion triggered at exactly 100k AX" 444 - test_id: T006-UT018 445 description: "Completion not triggered at 99,999 AX" 446 - test_id: T006-UT019 447 description: "Status transitions Provisional -> Active" 448 - test_id: T006-UT020 449 description: "Post-completion earnings are spendable" 450 - test_id: T006-UT021 451 description: "stake_completed event emitted" 452 integration: 453 - test_id: T006-IT004 454 description: "Full earn-in to completion lifecycle" 455 dependencies: [T001.interface_ax_balance, T001.interface_transfer] 456 457 success_criteria: 458 - "Stake completion detected at threshold" 459 - "Status transitions correctly" 460 - "Post-completion earnings freely spendable" 461 - "All events emitted" 462 463 estimated_duration: 3d 464 465 - phase_id: phase_5 466 name: DX Unlock and Treasury Sale 467 status: pending 468 blocked_by: 469 - dependency_ref: T002.interface_dx_balance 470 reason: "Need DX balance interface for unlock" 471 wait_for: interface_stable 472 - dependency_ref: T006.phase_4 473 reason: "Need stake completion working" 474 wait_for: complete 475 476 tasks: 477 - task_id: T006-T018 478 name: Implement DX unlock logic 479 description: "DX grant unlocks after paid at launch prices from earnings" 480 target_files: 481 - path: adnet/src/consensus/validator/dx_unlock.rs 482 action: create 483 estimate: 484 effort: large 485 confidence: medium 486 risk: 487 level: high 488 factors: [unlock_calculation_complexity, launch_price_oracle] 489 490 - task_id: T006-T019 491 name: Implement treasury-only sale enforcement 492 description: "Unlocked DX can only be sold to treasury" 493 target_files: 494 - path: adnet/src/consensus/validator/dx_sale.rs 495 action: create 496 estimate: 497 effort: medium 498 confidence: medium 499 risk: 500 level: medium 501 factors: [transfer_restriction_enforcement] 502 503 - task_id: T006-T020 504 name: Implement DX stake retention 505 description: "DX remains staked even after unlock (governs voting power)" 506 target_files: 507 - path: adnet/src/consensus/validator/dx_stake.rs 508 action: create 509 estimate: 510 effort: medium 511 confidence: high 512 risk: 513 level: low 514 factors: [] 515 516 - task_id: T006-T021 517 name: Emit dx_unlocked event 518 description: "Event when DX grant becomes unlocked" 519 target_files: 520 - path: adnet/src/consensus/validator/events.rs 521 action: modify 522 estimate: 523 effort: small 524 confidence: high 525 risk: 526 level: low 527 factors: [] 528 529 deliverables: 530 - deliverable_id: T006-D015 531 name: DX unlock mechanism 532 type: code 533 verification: "DX unlocks at correct launch price calculation" 534 - deliverable_id: T006-D016 535 name: Treasury-only sale 536 type: code 537 verification: "Non-treasury DX sales rejected" 538 - deliverable_id: T006-D017 539 name: DX stake retention 540 type: code 541 verification: "DX remains staked for governance" 542 543 test_requirements: 544 unit: 545 - test_id: T006-UT022 546 description: "DX unlocks at launch price calculation" 547 - test_id: T006-UT023 548 description: "Treasury sale succeeds" 549 - test_id: T006-UT024 550 description: "Non-treasury sale fails" 551 - test_id: T006-UT025 552 description: "DX remains staked after unlock" 553 - test_id: T006-UT026 554 description: "dx_unlocked event emitted" 555 integration: 556 - test_id: T006-IT005 557 description: "Full DX lifecycle: grant -> lock -> unlock -> sale" 558 dependencies: [T002.interface_dx_balance] 559 560 success_criteria: 561 - "DX unlock calculation correct" 562 - "Treasury-only sale enforced" 563 - "DX remains staked for governance" 564 - "All events emitted" 565 566 estimated_duration: 4d 567 568 - phase_id: phase_6 569 name: Performance Failure Handling 570 status: pending 571 blocked_by: 572 - dependency_ref: T006.phase_3 573 reason: "Need CLP and performance monitoring" 574 wait_for: complete 575 576 tasks: 577 - task_id: T006-T022 578 name: Implement extended earn-in penalty 579 description: "Poor performance extends earn-in period" 580 target_files: 581 - path: adnet/src/consensus/validator/penalties.rs 582 action: create 583 estimate: 584 effort: medium 585 confidence: medium 586 risk: 587 level: medium 588 factors: [penalty_calculation_fairness] 589 590 - task_id: T006-T023 591 name: Implement validator removal 592 description: "Severe/repeated failures result in removal from network" 593 target_files: 594 - path: adnet/src/consensus/validator/removal.rs 595 action: create 596 estimate: 597 effort: large 598 confidence: medium 599 risk: 600 level: high 601 factors: [removal_finality, fund_handling] 602 603 - task_id: T006-T024 604 name: Implement slashing protection 605 description: "Zero slashing tolerance during earn-in (immediate removal)" 606 target_files: 607 - path: adnet/src/consensus/validator/slashing.rs 608 action: create 609 estimate: 610 effort: medium 611 confidence: high 612 risk: 613 level: high 614 factors: [slashing_detection_accuracy] 615 616 deliverables: 617 - deliverable_id: T006-D018 618 name: Extended earn-in penalty 619 type: code 620 verification: "Poor performance extends earn-in period" 621 - deliverable_id: T006-D019 622 name: Validator removal 623 type: code 624 verification: "Failed validators removed correctly" 625 - deliverable_id: T006-D020 626 name: Slashing protection 627 type: code 628 verification: "Any slashing triggers immediate removal" 629 630 test_requirements: 631 unit: 632 - test_id: T006-UT027 633 description: "Uptime below 95% extends earn-in" 634 - test_id: T006-UT028 635 description: "Participation below 99% extends earn-in" 636 - test_id: T006-UT029 637 description: "Repeated failures trigger removal" 638 - test_id: T006-UT030 639 description: "Any slashing triggers immediate removal" 640 integration: 641 - test_id: T006-IT006 642 description: "Performance degradation to removal lifecycle" 643 dependencies: [] 644 645 success_criteria: 646 - "Extended earn-in penalty works correctly" 647 - "Removal process handles all fund types" 648 - "Zero slashing tolerance enforced" 649 650 estimated_duration: 4d 651 652 - phase_id: phase_7 653 name: Governor Exception Implementation 654 status: pending 655 blocked_by: 656 - dependency_ref: T001.interface_mint_burn 657 reason: "Governors mint their own stake" 658 wait_for: interface_stable 659 - dependency_ref: T006.phase_2 660 reason: "Need registration infrastructure" 661 wait_for: complete 662 663 tasks: 664 - task_id: T006-T025 665 name: Implement governor self-minting 666 description: "Governors can mint their own 100k AX stake (sovereign)" 667 target_files: 668 - path: adnet/src/consensus/validator/governor.rs 669 action: modify 670 estimate: 671 effort: medium 672 confidence: high 673 risk: 674 level: high 675 factors: [mint_authorization_security] 676 677 - task_id: T006-T026 678 name: Implement governor DX grant 679 description: "1M DX immediate grant for governors" 680 target_files: 681 - path: adnet/src/consensus/validator/governor.rs 682 action: modify 683 estimate: 684 effort: small 685 confidence: high 686 risk: 687 level: low 688 factors: [] 689 690 - task_id: T006-T027 691 name: Implement governor KYC facilitation 692 description: "Governors can attest KYC for validators under them" 693 target_files: 694 - path: adnet/src/consensus/validator/kyc.rs 695 action: create 696 estimate: 697 effort: medium 698 confidence: medium 699 risk: 700 level: medium 701 factors: [kyc_chain_of_trust] 702 703 deliverables: 704 - deliverable_id: T006-D021 705 name: Governor self-minting 706 type: code 707 verification: "Governors can mint own stake" 708 - deliverable_id: T006-D022 709 name: Governor DX grant 710 type: code 711 verification: "Governors receive 1M DX" 712 - deliverable_id: T006-D023 713 name: Governor KYC facilitation 714 type: code 715 verification: "KYC attestation chain works" 716 717 test_requirements: 718 unit: 719 - test_id: T006-UT031 720 description: "Governor can mint 100k AX stake" 721 - test_id: T006-UT032 722 description: "Non-governor cannot self-mint" 723 - test_id: T006-UT033 724 description: "Governor receives 1M DX immediately" 725 - test_id: T006-UT034 726 description: "Governor can attest validator KYC" 727 integration: 728 - test_id: T006-IT007 729 description: "Full governor registration flow" 730 dependencies: [T001.interface_mint_burn] 731 732 success_criteria: 733 - "Governor self-minting works" 734 - "Governor 1M DX grant immediate" 735 - "KYC facilitation works" 736 737 estimated_duration: 3d 738 739 - phase_id: phase_8 740 name: Integration and API 741 status: pending 742 blocked_by: 743 - dependency_ref: T006.phase_7 744 reason: "All features must be complete" 745 wait_for: complete 746 747 tasks: 748 - task_id: T006-T028 749 name: Integrate with adnet consensus 750 description: "Wire earn-in into consensus module" 751 target_files: 752 - path: adnet/src/consensus/mod.rs 753 action: modify 754 estimate: 755 effort: medium 756 confidence: high 757 risk: 758 level: low 759 factors: [] 760 761 - task_id: T006-T029 762 name: Implement RPC endpoints 763 description: "validator_register, validator_status, validator_earnings, validator_list" 764 target_files: 765 - path: adnet/src/rpc/validator_rpc.rs 766 action: create 767 - path: adnet/src/rpc/mod.rs 768 action: modify 769 estimate: 770 effort: medium 771 confidence: high 772 risk: 773 level: low 774 factors: [] 775 776 - task_id: T006-T030 777 name: Add CLI commands 778 description: "adnet validator register, adnet validator status, adnet validator list" 779 target_files: 780 - path: adnet/src/cli/validator_commands.rs 781 action: create 782 - path: adnet/src/cli/mod.rs 783 action: modify 784 estimate: 785 effort: small 786 confidence: high 787 risk: 788 level: low 789 factors: [] 790 791 - task_id: T006-T031 792 name: Full integration test suite 793 description: "End-to-end tests covering all earn-in functionality" 794 target_files: 795 - path: adnet/tests/integration/validator_earn_in_test.rs 796 action: create 797 estimate: 798 effort: large 799 confidence: medium 800 risk: 801 level: medium 802 factors: [test_complexity] 803 804 deliverables: 805 - deliverable_id: T006-D024 806 name: Consensus integration 807 type: code 808 verification: "Earn-in integrated into consensus" 809 - deliverable_id: T006-D025 810 name: RPC API 811 type: interface 812 verification: "All endpoints respond correctly" 813 - deliverable_id: T006-D026 814 name: CLI commands 815 type: code 816 verification: "All commands execute correctly" 817 - deliverable_id: T006-D027 818 name: Integration test suite 819 type: test 820 verification: "cargo test --test validator_earn_in_test" 821 822 test_requirements: 823 unit: 824 - test_id: T006-UT035 825 description: "RPC endpoint serialization" 826 - test_id: T006-UT036 827 description: "CLI argument parsing" 828 integration: 829 - test_id: T006-IT008 830 description: "Full validator lifecycle: register -> earn-in -> complete -> unlock" 831 dependencies: [T001.interface_ax_balance, T001.interface_mint_burn, T002.interface_dx_balance] 832 833 success_criteria: 834 - "All RPC endpoints functional" 835 - "CLI commands work" 836 - "Integration tests pass" 837 - "API documentation complete" 838 839 estimated_duration: 4d 840 841 # === PARALLEL WORKSTREAMS === 842 # Tests, CI, and docs evolve alongside implementation 843 parallel_workstreams: 844 845 testing: 846 strategy: test_alongside 847 coverage_targets: 848 unit_minimum: 80 849 integration_required: true 850 851 per_phase_requirements: 852 - phase_ref: phase_1 853 unit_tests: 854 - Validator max count is 300 855 - Stake requirement is exactly 100,000 AX 856 - DX grant amount is exactly 100,000 DX 857 - Governor DX grant is exactly 1,000,000 DX 858 - Status transitions are valid only in allowed directions 859 test_files: 860 - path: adnet/src/consensus/validator/types_tests.rs 861 action: create 862 - path: adnet/src/consensus/validator/status_tests.rs 863 action: create 864 - path: adnet/src/consensus/validator/earn_in_state_tests.rs 865 action: create 866 867 - phase_ref: phase_2 868 unit_tests: 869 - Registration fails without KYC 870 - Registration allocates exactly 100k DX 871 - Locked DX transfer fails 872 - Registry rejects 301st validator 873 - validator_registered event emitted 874 integration_tests: 875 - Full registration flow with DX grant from T002 876 test_files: 877 - path: adnet/src/consensus/validator/registration_tests.rs 878 action: create 879 - path: adnet/src/consensus/validator/dx_lock_tests.rs 880 action: create 881 - path: adnet/src/consensus/validator/registry_tests.rs 882 action: create 883 - path: adnet/tests/integration/validator_registration.rs 884 action: create 885 886 - phase_ref: phase_3 887 unit_tests: 888 - Fee share proportional to participation 889 - Earned fees locked to stake account 890 - Cannot spend locked earn-in AX 891 - CLP tracks uptime correctly 892 - Participation below 99% flagged 893 - Uptime below 95% flagged 894 integration_tests: 895 - Fee accumulation over multiple blocks 896 - CLP validation across consensus rounds 897 test_files: 898 - path: adnet/src/consensus/validator/fee_share_tests.rs 899 action: create 900 - path: adnet/src/consensus/validator/earn_in_tests.rs 901 action: create 902 - path: adnet/src/consensus/validator/liveness_tests.rs 903 action: create 904 - path: adnet/tests/integration/earn_in_accumulation.rs 905 action: create 906 907 - phase_ref: phase_4 908 unit_tests: 909 - Completion triggered at exactly 100k AX 910 - Completion not triggered at 99,999 AX 911 - Status transitions Provisional -> Active 912 - Post-completion earnings are spendable 913 - stake_completed event emitted 914 integration_tests: 915 - Full earn-in to completion lifecycle 916 test_files: 917 - path: adnet/src/consensus/validator/stake_completion_tests.rs 918 action: create 919 - path: adnet/tests/integration/stake_completion.rs 920 action: create 921 922 - phase_ref: phase_5 923 unit_tests: 924 - DX unlocks at launch price calculation 925 - Treasury sale succeeds 926 - Non-treasury sale fails 927 - DX remains staked after unlock 928 - dx_unlocked event emitted 929 integration_tests: 930 - Full DX lifecycle (grant -> lock -> unlock -> sale) 931 test_files: 932 - path: adnet/src/consensus/validator/dx_unlock_tests.rs 933 action: create 934 - path: adnet/src/consensus/validator/dx_sale_tests.rs 935 action: create 936 - path: adnet/tests/integration/dx_lifecycle.rs 937 action: create 938 939 - phase_ref: phase_6 940 unit_tests: 941 - Uptime below 95% extends earn-in 942 - Participation below 99% extends earn-in 943 - Repeated failures trigger removal 944 - Any slashing triggers immediate removal 945 integration_tests: 946 - Performance degradation to removal lifecycle 947 test_files: 948 - path: adnet/src/consensus/validator/penalties_tests.rs 949 action: create 950 - path: adnet/src/consensus/validator/removal_tests.rs 951 action: create 952 - path: adnet/src/consensus/validator/slashing_tests.rs 953 action: create 954 - path: adnet/tests/integration/performance_failure.rs 955 action: create 956 957 - phase_ref: phase_7 958 unit_tests: 959 - Governor can mint 100k AX stake 960 - Non-governor cannot self-mint 961 - Governor receives 1M DX immediately 962 - Governor can attest validator KYC 963 integration_tests: 964 - Full governor registration flow 965 test_files: 966 - path: adnet/src/consensus/validator/governor_tests.rs 967 action: create 968 - path: adnet/src/consensus/validator/kyc_tests.rs 969 action: create 970 - path: adnet/tests/integration/governor_flow.rs 971 action: create 972 973 - phase_ref: phase_8 974 unit_tests: 975 - RPC endpoint serialization 976 - CLI argument parsing 977 integration_tests: 978 - Full validator lifecycle (register -> earn-in -> complete -> unlock) 979 test_files: 980 - path: adnet/src/rpc/validator_rpc_tests.rs 981 action: create 982 - path: adnet/src/cli/validator_commands_tests.rs 983 action: create 984 - path: adnet/tests/integration/validator_earn_in_test.rs 985 action: create 986 987 ci_test_gates: 988 - gate_id: unit_tests 989 command: cargo test --workspace 990 required: true 991 - gate_id: integration_tests 992 command: cargo test --test '*' 993 required: true 994 - gate_id: clippy 995 command: cargo clippy --workspace -- -D warnings 996 required: true 997 - gate_id: fmt 998 command: cargo fmt --check 999 required: true 1000 - gate_id: consensus_tests 1001 command: cargo test --test 'consensus*' 1002 required: true 1003 1004 ci_workflows: 1005 affected_workflows: 1006 - workflow_file: .forgejo/workflows/ci.yml 1007 repo: adnet 1008 triggers: [phase_1, phase_2, phase_3, phase_6, phase_8] 1009 1010 per_phase_ci_tasks: 1011 - phase_ref: phase_1 1012 workflow_changes: 1013 - file: .forgejo/workflows/ci.yml 1014 change_type: modify_job 1015 description: Ensure validator type tests run in adnet CI 1016 1017 - phase_ref: phase_2 1018 workflow_changes: 1019 - file: .forgejo/workflows/ci.yml 1020 change_type: add_step 1021 description: Add validator registration integration test step 1022 1023 - phase_ref: phase_3 1024 workflow_changes: 1025 - file: .forgejo/workflows/ci.yml 1026 change_type: add_step 1027 description: Add earn-in and CLP integration test step 1028 1029 - phase_ref: phase_6 1030 workflow_changes: 1031 - file: .forgejo/workflows/ci.yml 1032 change_type: add_step 1033 description: Add performance failure and removal test step 1034 1035 - phase_ref: phase_8 1036 workflow_changes: 1037 - file: .forgejo/workflows/ci.yml 1038 change_type: add_job 1039 description: Add full validator lifecycle integration test job 1040 1041 required_ci_checks: 1042 - check_name: build 1043 check_type: build 1044 blocking: true 1045 - check_name: test 1046 check_type: test 1047 blocking: true 1048 - check_name: clippy 1049 check_type: lint 1050 blocking: true 1051 - check_name: fmt 1052 check_type: lint 1053 blocking: true 1054 - check_name: consensus 1055 check_type: test 1056 blocking: true 1057 1058 documentation: 1059 cspec_update_policy: on_interface_change 1060 1061 component_cspec_updates: 1062 - cspec_file: components/tokens/T006-validator_earn_in.component.cspec 1063 update_triggers: 1064 - phase_ref: phase_2 1065 fields_to_update: [implementation_status, interfaces] 1066 description: Mark registration interface available 1067 - phase_ref: phase_3 1068 fields_to_update: [implementation_status, interfaces] 1069 description: Mark earn-in status and performance interfaces available 1070 - phase_ref: phase_8 1071 fields_to_update: [implementation_status, interfaces] 1072 description: Mark all interfaces stable 1073 1074 session_logging: 1075 required: true 1076 log_location: sessions/ 1077 log_format: cspec 1078 log_triggers: 1079 - phase_complete 1080 - blocker_encountered 1081 - interface_change 1082 - major_decision 1083 - security_review_needed 1084 - consensus_mechanism_change 1085 1086 changelog_policy: 1087 update_frequency: per_phase 1088 required_fields: 1089 - version 1090 - date 1091 - type 1092 - description 1093 - affected_interfaces 1094 1095 human_doc_derivation: 1096 target_human_doc: project/architecture/human/validator-earn-in.md 1097 regenerate_triggers: 1098 - phase_4 # Stake completion interface stable 1099 - phase_8 # All interfaces stable 1100 1101 # === INTERFACE COMMITMENTS === 1102 interface_commitments: 1103 provides: 1104 - interface_id: interface_validator_registration 1105 name: Validator Registration Interface 1106 stability: experimental 1107 available_from: phase_2 1108 stable_from: phase_8 1109 consumers: [] 1110 1111 - interface_id: interface_earn_in_status 1112 name: Earn-In Status Query Interface 1113 stability: experimental 1114 available_from: phase_3 1115 stable_from: phase_8 1116 consumers: [] 1117 1118 - interface_id: interface_validator_performance 1119 name: Validator Performance Metrics Interface 1120 stability: experimental 1121 available_from: phase_3 1122 stable_from: phase_8 1123 consumers: [] 1124 1125 requires: 1126 - interface_ref: T001.interface_ax_balance 1127 minimum_stability: stable 1128 required_from: phase_3 1129 1130 - interface_ref: T001.interface_mint_burn 1131 minimum_stability: stable 1132 required_from: phase_3 1133 1134 - interface_ref: T001.interface_transfer 1135 minimum_stability: stable 1136 required_from: phase_3 1137 1138 - interface_ref: T002.interface_dx_balance 1139 minimum_stability: stable 1140 required_from: phase_2 1141 1142 # === REPOSITORY TARGETS === 1143 repository_targets: 1144 primary_repo: 1145 name: adnet 1146 branch_strategy: feature_branch 1147 1148 file_manifest: 1149 # Phase 1 - Types 1150 - path: adnet/src/consensus/validator/types.rs 1151 action: create 1152 purpose: "Validator type definitions and constants" 1153 phase: phase_1 1154 - path: adnet/src/consensus/validator/status.rs 1155 action: create 1156 purpose: "Validator status state machine" 1157 phase: phase_1 1158 - path: adnet/src/consensus/validator/earn_in_state.rs 1159 action: create 1160 purpose: "Earn-in state tracking" 1161 phase: phase_1 1162 - path: adnet/src/consensus/validator/governor.rs 1163 action: create 1164 purpose: "Governor exception types" 1165 phase: phase_1 1166 - path: adnet/src/consensus/validator/mod.rs 1167 action: modify 1168 purpose: "Export validator modules" 1169 phase: phase_1 1170 1171 # Phase 2 - Registration 1172 - path: adnet/src/consensus/validator/registration.rs 1173 action: create 1174 purpose: "Validator registration logic" 1175 phase: phase_2 1176 - path: adnet/src/consensus/validator/dx_lock.rs 1177 action: create 1178 purpose: "DX grant locking" 1179 phase: phase_2 1180 - path: adnet/src/consensus/validator/registry.rs 1181 action: create 1182 purpose: "Validator registry" 1183 phase: phase_2 1184 - path: adnet/src/consensus/validator/events.rs 1185 action: create 1186 purpose: "Validator events" 1187 phase: phase_2 1188 1189 # Phase 3 - Earn-In 1190 - path: adnet/src/consensus/validator/fee_share.rs 1191 action: create 1192 purpose: "Fee share calculation" 1193 phase: phase_3 1194 - path: adnet/src/consensus/validator/earn_in.rs 1195 action: create 1196 purpose: "Earn-in accumulation logic" 1197 phase: phase_3 1198 - path: adnet/src/consensus/validator/liveness.rs 1199 action: create 1200 purpose: "Continuous liveness proof" 1201 phase: phase_3 1202 - path: adnet/src/consensus/validator/performance.rs 1203 action: create 1204 purpose: "Performance monitoring" 1205 phase: phase_3 1206 1207 # Phase 4 - Completion 1208 - path: adnet/src/consensus/validator/stake_completion.rs 1209 action: create 1210 purpose: "Stake completion detection" 1211 phase: phase_4 1212 1213 # Phase 5 - DX Unlock 1214 - path: adnet/src/consensus/validator/dx_unlock.rs 1215 action: create 1216 purpose: "DX unlock logic" 1217 phase: phase_5 1218 - path: adnet/src/consensus/validator/dx_sale.rs 1219 action: create 1220 purpose: "Treasury-only sale enforcement" 1221 phase: phase_5 1222 - path: adnet/src/consensus/validator/dx_stake.rs 1223 action: create 1224 purpose: "DX stake retention" 1225 phase: phase_5 1226 1227 # Phase 6 - Failure Handling 1228 - path: adnet/src/consensus/validator/penalties.rs 1229 action: create 1230 purpose: "Extended earn-in penalty" 1231 phase: phase_6 1232 - path: adnet/src/consensus/validator/removal.rs 1233 action: create 1234 purpose: "Validator removal" 1235 phase: phase_6 1236 - path: adnet/src/consensus/validator/slashing.rs 1237 action: create 1238 purpose: "Slashing protection" 1239 phase: phase_6 1240 1241 # Phase 7 - Governor 1242 - path: adnet/src/consensus/validator/kyc.rs 1243 action: create 1244 purpose: "Governor KYC facilitation" 1245 phase: phase_7 1246 1247 # Phase 8 - Integration 1248 - path: adnet/src/consensus/mod.rs 1249 action: modify 1250 purpose: "Export validator module" 1251 phase: phase_8 1252 - path: adnet/src/rpc/validator_rpc.rs 1253 action: create 1254 purpose: "Validator RPC endpoints" 1255 phase: phase_8 1256 - path: adnet/src/rpc/mod.rs 1257 action: modify 1258 purpose: "Export validator RPC" 1259 phase: phase_8 1260 - path: adnet/src/cli/validator_commands.rs 1261 action: create 1262 purpose: "Validator CLI commands" 1263 phase: phase_8 1264 - path: adnet/src/cli/mod.rs 1265 action: modify 1266 purpose: "Export validator CLI" 1267 phase: phase_8 1268 - path: adnet/tests/integration/validator_earn_in_test.rs 1269 action: create 1270 purpose: "Integration test suite" 1271 phase: phase_8 1272 1273 secondary_repos: [] 1274 1275 # === COMPLEXITY ASSESSMENT === 1276 complexity_assessment: 1277 overall_complexity: high 1278 1279 risk_summary: 1280 - risk_id: RISK-001 1281 description: "Fee accumulation state consistency during network partitions" 1282 likelihood: medium 1283 impact: high 1284 mitigation: "Use consensus-committed state, replay from blocks" 1285 1286 - risk_id: RISK-002 1287 description: "CLP measurement accuracy under adversarial conditions" 1288 likelihood: medium 1289 impact: high 1290 mitigation: "Multiple attestation sources, byzantine-tolerant averaging" 1291 1292 - risk_id: RISK-003 1293 description: "DX unlock calculation with launch price oracle" 1294 likelihood: medium 1295 impact: medium 1296 mitigation: "Use time-weighted average price, multiple oracle sources" 1297 1298 - risk_id: RISK-004 1299 description: "Governor self-minting authorization bypass" 1300 likelihood: low 1301 impact: critical 1302 mitigation: "Multi-layer authorization checks, audit logging, rate limits" 1303 1304 - risk_id: RISK-005 1305 description: "Validator removal fund handling edge cases" 1306 likelihood: low 1307 impact: high 1308 mitigation: "Comprehensive state machine testing, formal verification" 1309 1310 - risk_id: RISK-006 1311 description: "Race conditions in stake completion detection" 1312 likelihood: low 1313 impact: medium 1314 mitigation: "Atomic state transitions, block-based finality" 1315 1316 # === DEPENDENCIES SUMMARY === 1317 dependencies_summary: 1318 blocks: [] 1319 blocked_by: [T001, T002] 1320 parallel_candidates: [T003, T004, T005, T007, T008] 1321 1322 # === CHANGELOG === 1323 changelog: 1324 - version: 1.1.0 1325 date: 2026-01-07 1326 type: revision 1327 description: "Added parallel_workstreams section for testing, CI workflows, and documentation" 1328 1329 - version: 1.0.0 1330 date: 2026-01-07 1331 type: initial 1332 description: "Initial implementation plan for Validator Earn-In mechanism"