T002-dx_token.plan.cspec
1 # T002 DX Token Implementation Plan 2 # Generated: 2026-01-07 3 # Planning Worker: Wave 0 (ROOT) 4 5 plan_metadata: 6 component_id: T002 7 component_ref: components/tokens/T002-dx_token.component.cspec 8 plan_version: 1.1.0 9 plan_status: phase_1_complete 10 created: 2026-01-07 11 updated: 2026-01-09 12 13 wave_context: 14 topological_level: 0 15 is_root: true 16 upstream_components: [] 17 downstream_components: [T006, T007, D008] 18 critical_path: true 19 cascade_group: tokenomics_core 20 21 # === IMPLEMENTATION PHASES === 22 phases: 23 - phase_id: phase_1 24 name: Core DX Token Type and Genesis Allocation 25 status: pending 26 blocked_by: [] 27 28 tasks: 29 - task_id: T002-T001 30 name: Define DX token type in DeltaVM 31 description: "Implement DX as governance/dividend token with 0 decimals, 1B fixed supply, ZK-shielded holdings" 32 target_files: 33 - path: deltavm/src/tokens/dx.rs 34 action: create 35 - path: deltavm/src/tokens/mod.rs 36 action: modify 37 estimate: 38 effort: medium 39 confidence: high 40 risk: 41 level: low 42 factors: [well_defined_spec, similar_to_ax_pattern] 43 44 - task_id: T002-T002 45 name: Implement genesis allocation structures 46 description: "Define genesis distribution: 300M founders, 100M investors, 250M network, 350M rewards" 47 target_files: 48 - path: deltavm/src/genesis/dx_allocation.rs 49 action: create 50 - path: deltavm/src/genesis/mod.rs 51 action: modify 52 estimate: 53 effort: medium 54 confidence: high 55 risk: 56 level: medium 57 factors: [vesting_logic_complexity, treasury_constraints] 58 59 - task_id: T002-T003 60 name: Implement vesting schedules 61 description: "4-year founders vesting, 2-year investors vesting with treasury-only sale restrictions" 62 target_files: 63 - path: deltavm/src/vesting/dx_vesting.rs 64 action: create 65 - path: deltavm/src/vesting/mod.rs 66 action: modify 67 estimate: 68 effort: medium 69 confidence: medium 70 risk: 71 level: medium 72 factors: [time_based_logic, unlock_calculation] 73 74 deliverables: 75 - deliverable_id: T002-D001 76 name: DX token type implementation 77 type: code 78 verification: "cargo test dx_token_type" 79 - deliverable_id: T002-D002 80 name: Genesis allocation module 81 type: code 82 verification: "cargo test genesis_allocation" 83 - deliverable_id: T002-D003 84 name: Vesting schedule module 85 type: code 86 verification: "cargo test vesting_schedule" 87 88 test_requirements: 89 unit: 90 - test_id: T002-UT001 91 description: "DX token has 0 decimals" 92 - test_id: T002-UT002 93 description: "Total supply is exactly 1B" 94 - test_id: T002-UT003 95 description: "Genesis allocation sums to 1B" 96 - test_id: T002-UT004 97 description: "Vesting schedules unlock correctly over time" 98 - test_id: T002-UT005 99 description: "No minting allowed after genesis" 100 101 success_criteria: 102 - "DX token type compiles and passes unit tests" 103 - "Genesis allocation totals exactly 1,000,000,000 DX" 104 - "Vesting schedules correctly enforce time locks" 105 - "Treasury-only sale restriction enforced" 106 107 estimated_duration: 3d 108 109 - phase_id: phase_2 110 name: ZK Privacy and Shielded State 111 status: pending 112 blocked_by: [] 113 114 tasks: 115 - task_id: T002-T004 116 name: Implement ZK-shielded holdings 117 description: "DX balances use shielded records for privacy" 118 target_files: 119 - path: deltavm/src/privacy/dx_shielded.rs 120 action: create 121 - path: deltavm/src/privacy/mod.rs 122 action: modify 123 estimate: 124 effort: large 125 confidence: medium 126 risk: 127 level: high 128 factors: [zk_circuit_complexity, privacy_correctness] 129 130 - task_id: T002-T005 131 name: Implement shielded balance queries 132 description: "Query interface for DX balances with ZK proofs" 133 target_files: 134 - path: deltavm/src/queries/dx_balance.rs 135 action: create 136 estimate: 137 effort: medium 138 confidence: medium 139 risk: 140 level: medium 141 factors: [proof_verification_overhead] 142 143 deliverables: 144 - deliverable_id: T002-D004 145 name: ZK shielded holdings module 146 type: code 147 verification: "cargo test dx_shielded" 148 - deliverable_id: T002-D005 149 name: Shielded balance query interface 150 type: interface 151 verification: "cargo test dx_balance_query" 152 153 test_requirements: 154 unit: 155 - test_id: T002-UT006 156 description: "Shielded balances hide actual amounts" 157 - test_id: T002-UT007 158 description: "Balance proofs verify correctly" 159 - test_id: T002-UT008 160 description: "Unauthorized queries fail" 161 integration: 162 - test_id: T002-IT001 163 description: "End-to-end shielded balance flow" 164 dependencies: [T002-D004, T002-D005] 165 166 success_criteria: 167 - "ZK circuits for balance privacy pass tests" 168 - "interface_dx_balance available for downstream consumers" 169 - "Privacy guarantees documented and verified" 170 171 estimated_duration: 5d 172 173 - phase_id: phase_3 174 name: Network Pool Grants and Closure Logic 175 status: pending 176 blocked_by: [] 177 178 tasks: 179 - task_id: T002-T006 180 name: Implement network pool grant types 181 description: "Governor 1M, Validator 100K, Prover lottery 10K grants" 182 target_files: 183 - path: deltavm/src/grants/network_pool.rs 184 action: create 185 - path: deltavm/src/grants/mod.rs 186 action: modify 187 estimate: 188 effort: medium 189 confidence: high 190 risk: 191 level: low 192 factors: [straightforward_logic] 193 194 - task_id: T002-T007 195 name: Implement pool closure trigger 196 description: "Close network pool when governors >= 150, transfer remainder to reward pool" 197 target_files: 198 - path: deltavm/src/grants/pool_closure.rs 199 action: create 200 estimate: 201 effort: small 202 confidence: high 203 risk: 204 level: low 205 factors: [simple_threshold_logic] 206 207 - task_id: T002-T008 208 name: Implement treasury-only sale enforcement 209 description: "Grants can only be sold to treasury, not open market" 210 target_files: 211 - path: deltavm/src/grants/sale_restrictions.rs 212 action: create 213 estimate: 214 effort: medium 215 confidence: medium 216 risk: 217 level: medium 218 factors: [transfer_restriction_complexity] 219 220 deliverables: 221 - deliverable_id: T002-D006 222 name: Network pool grants module 223 type: code 224 verification: "cargo test network_pool_grants" 225 - deliverable_id: T002-D007 226 name: Pool closure logic 227 type: code 228 verification: "cargo test pool_closure" 229 - deliverable_id: T002-D008 230 name: Treasury-only sale enforcement 231 type: code 232 verification: "cargo test sale_restrictions" 233 234 test_requirements: 235 unit: 236 - test_id: T002-UT009 237 description: "Governor grant is exactly 1M DX" 238 - test_id: T002-UT010 239 description: "Validator grant is locked until paid" 240 - test_id: T002-UT011 241 description: "Pool closes at 150 governors" 242 - test_id: T002-UT012 243 description: "Non-treasury sales rejected" 244 integration: 245 - test_id: T002-IT002 246 description: "Full grant lifecycle including closure" 247 dependencies: [T002-D006, T002-D007] 248 249 success_criteria: 250 - "All three grant types implemented with correct amounts" 251 - "Pool closure triggers correctly at threshold" 252 - "Treasury-only sale restriction enforced" 253 254 estimated_duration: 3d 255 256 - phase_id: phase_4 257 name: Governance and Dividend Interfaces 258 status: pending 259 blocked_by: 260 - dependency_ref: T002.phase_2 261 reason: "Governance voting power requires shielded balance access" 262 wait_for: complete 263 264 tasks: 265 - task_id: T002-T009 266 name: Implement governance voting power interface 267 description: "interface_dx_governance for voting weight calculation" 268 target_files: 269 - path: deltavm/src/governance/voting_power.rs 270 action: create 271 - path: deltavm/src/governance/mod.rs 272 action: modify 273 estimate: 274 effort: medium 275 confidence: high 276 risk: 277 level: low 278 factors: [well_defined_interface] 279 280 - task_id: T002-T010 281 name: Implement dividend rights interface 282 description: "interface_dividend_rights for claim eligibility" 283 target_files: 284 - path: deltavm/src/dividends/rights.rs 285 action: create 286 - path: deltavm/src/dividends/mod.rs 287 action: modify 288 estimate: 289 effort: medium 290 confidence: medium 291 risk: 292 level: medium 293 factors: [snapshot_timing_complexity] 294 295 deliverables: 296 - deliverable_id: T002-D009 297 name: Governance voting power interface 298 type: interface 299 verification: "cargo test voting_power" 300 - deliverable_id: T002-D010 301 name: Dividend rights interface 302 type: interface 303 verification: "cargo test dividend_rights" 304 305 test_requirements: 306 unit: 307 - test_id: T002-UT013 308 description: "Voting power proportional to DX holdings" 309 - test_id: T002-UT014 310 description: "Vesting tokens have reduced voting power" 311 - test_id: T002-UT015 312 description: "Dividend eligibility based on snapshot" 313 integration: 314 - test_id: T002-IT003 315 description: "Governance integration with D008" 316 dependencies: [T002-D009] 317 - test_id: T002-IT004 318 description: "Dividend calculation with T007" 319 dependencies: [T002-D010] 320 321 success_criteria: 322 - "interface_dx_governance stable for D008 consumption" 323 - "interface_dividend_rights stable for T007 consumption" 324 - "All downstream consumers can integrate" 325 326 estimated_duration: 3d 327 328 - phase_id: phase_5 329 name: Integration Tests and Documentation 330 status: pending 331 blocked_by: 332 - dependency_ref: T002.phase_4 333 reason: "All interfaces must be stable before integration testing" 334 wait_for: complete 335 336 tasks: 337 - task_id: T002-T011 338 name: Full integration test suite 339 description: "End-to-end tests covering all DX functionality" 340 target_files: 341 - path: deltavm/tests/integration/dx_token_test.rs 342 action: create 343 estimate: 344 effort: medium 345 confidence: high 346 risk: 347 level: low 348 factors: [standard_test_patterns] 349 350 - task_id: T002-T012 351 name: Update component spec with implementation details 352 description: "Add implementation notes to component.cspec" 353 target_files: 354 - path: components/tokens/T002-dx_token.component.cspec 355 action: modify 356 estimate: 357 effort: small 358 confidence: high 359 risk: 360 level: low 361 factors: [] 362 363 deliverables: 364 - deliverable_id: T002-D011 365 name: Integration test suite 366 type: test 367 verification: "cargo test --test dx_token_test" 368 - deliverable_id: T002-D012 369 name: Updated component spec 370 type: documentation 371 verification: "Manual review" 372 373 test_requirements: 374 integration: 375 - test_id: T002-IT005 376 description: "Genesis to dividend lifecycle" 377 dependencies: [T002-D001, T002-D002, T002-D009, T002-D010] 378 - test_id: T002-IT006 379 description: "Grant lifecycle with pool closure" 380 dependencies: [T002-D006, T002-D007, T002-D008] 381 382 success_criteria: 383 - "100% integration test coverage of critical paths" 384 - "All downstream interface contracts verified" 385 - "Component ready for T006, T007, D008 integration" 386 387 estimated_duration: 2d 388 389 # === PARALLEL WORKSTREAMS === 390 # Tests, CI, and docs evolve alongside implementation 391 parallel_workstreams: 392 393 testing: 394 strategy: test_alongside 395 coverage_targets: 396 unit_minimum: 80 397 integration_required: true 398 399 per_phase_requirements: 400 - phase_ref: phase_1 401 unit_tests: 402 - DX token has 0 decimals 403 - Total supply is exactly 1B 404 - Genesis allocation sums to 1B 405 - Vesting schedules unlock correctly over time 406 - No minting allowed after genesis 407 test_files: 408 - path: deltavm/src/tokens/dx_tests.rs 409 action: create 410 - path: deltavm/src/genesis/tests.rs 411 action: create 412 - path: deltavm/src/vesting/tests.rs 413 action: create 414 415 - phase_ref: phase_2 416 unit_tests: 417 - Shielded balances hide actual amounts 418 - Balance proofs verify correctly 419 - Unauthorized queries fail 420 integration_tests: 421 - End-to-end shielded balance flow 422 test_files: 423 - path: deltavm/src/privacy/dx_shielded_tests.rs 424 action: create 425 - path: deltavm/src/queries/tests.rs 426 action: create 427 - path: deltavm/tests/integration/shielded_balance.rs 428 action: create 429 430 - phase_ref: phase_3 431 unit_tests: 432 - Governor grant is exactly 1M DX 433 - Validator grant is locked until paid 434 - Pool closes at 150 governors 435 - Non-treasury sales rejected 436 integration_tests: 437 - Full grant lifecycle including closure 438 test_files: 439 - path: deltavm/src/grants/tests.rs 440 action: create 441 - path: deltavm/tests/integration/grant_lifecycle.rs 442 action: create 443 444 - phase_ref: phase_4 445 unit_tests: 446 - Voting power proportional to DX holdings 447 - Vesting tokens have reduced voting power 448 - Dividend eligibility based on snapshot 449 integration_tests: 450 - Governance integration with D008 451 - Dividend calculation with T007 452 test_files: 453 - path: deltavm/src/governance/tests.rs 454 action: create 455 - path: deltavm/src/dividends/tests.rs 456 action: create 457 - path: deltavm/tests/integration/governance_voting.rs 458 action: create 459 460 - phase_ref: phase_5 461 integration_tests: 462 - Genesis to dividend lifecycle 463 - Grant lifecycle with pool closure 464 test_files: 465 - path: deltavm/tests/integration/dx_token_test.rs 466 action: create 467 468 ci_test_gates: 469 - gate_id: unit_tests 470 command: cargo test --workspace 471 required: true 472 - gate_id: integration_tests 473 command: cargo test --test '*' 474 required: true 475 - gate_id: clippy 476 command: cargo clippy --workspace -- -D warnings 477 required: true 478 - gate_id: fmt 479 command: cargo fmt --check 480 required: true 481 482 ci_workflows: 483 affected_workflows: 484 - workflow_file: .forgejo/workflows/ci.yml 485 repo: deltavm 486 triggers: [phase_1, phase_2, phase_3, phase_4] 487 488 per_phase_ci_tasks: 489 - phase_ref: phase_1 490 workflow_changes: 491 - file: .forgejo/workflows/ci.yml 492 change_type: modify_job 493 description: Ensure basic build and test job exists for deltavm 494 495 - phase_ref: phase_2 496 workflow_changes: 497 - file: .forgejo/workflows/ci.yml 498 change_type: add_step 499 description: Add ZK shielded balance test step 500 501 - phase_ref: phase_3 502 workflow_changes: 503 - file: .forgejo/workflows/ci.yml 504 change_type: add_step 505 description: Add network pool grant integration test step 506 507 - phase_ref: phase_4 508 workflow_changes: 509 - file: .forgejo/workflows/ci.yml 510 change_type: add_step 511 description: Add governance and dividend interface integration test step 512 513 required_ci_checks: 514 - check_name: build 515 check_type: build 516 blocking: true 517 - check_name: test 518 check_type: test 519 blocking: true 520 - check_name: clippy 521 check_type: lint 522 blocking: true 523 - check_name: fmt 524 check_type: lint 525 blocking: true 526 527 documentation: 528 cspec_update_policy: on_interface_change 529 530 component_cspec_updates: 531 - cspec_file: components/tokens/T002-dx_token.component.cspec 532 update_triggers: 533 - phase_ref: phase_1 534 fields_to_update: [implementation_status] 535 description: Mark DX token type and genesis allocation complete 536 - phase_ref: phase_2 537 fields_to_update: [implementation_status, interfaces] 538 description: Mark ZK shielded balance interface available 539 - phase_ref: phase_4 540 fields_to_update: [implementation_status, interfaces] 541 description: Mark governance and dividend interfaces available 542 - phase_ref: phase_5 543 fields_to_update: [implementation_status, interfaces] 544 description: Mark all interfaces stable 545 546 session_logging: 547 required: true 548 log_location: sessions/ 549 log_format: cspec 550 log_triggers: 551 - phase_complete 552 - blocker_encountered 553 - interface_change 554 - major_decision 555 - zk_circuit_change 556 557 changelog_policy: 558 update_frequency: per_phase 559 required_fields: 560 - version 561 - date 562 - type 563 - description 564 - affected_interfaces 565 566 human_doc_derivation: 567 target_human_doc: project/architecture/human/dx-token.md 568 regenerate_triggers: 569 - phase_4 # Governance interface stable 570 - phase_5 # All interfaces stable 571 572 # === INTERFACE COMMITMENTS === 573 interface_commitments: 574 provides: 575 - interface_id: interface_dx_balance 576 name: DX Balance Query 577 stability: experimental 578 available_from: phase_2 579 stable_from: phase_4 580 consumers: [T006, T007] 581 582 - interface_id: interface_dx_governance 583 name: DX Governance Voting Power 584 stability: experimental 585 available_from: phase_4 586 stable_from: phase_5 587 consumers: [D008] 588 589 - interface_id: interface_dividend_rights 590 name: Dividend Claim Eligibility 591 stability: experimental 592 available_from: phase_4 593 stable_from: phase_5 594 consumers: [T007] 595 596 requires: [] 597 598 # === REPOSITORY TARGETS === 599 repository_targets: 600 primary_repo: 601 name: deltavm 602 branch_strategy: feature_branch 603 604 file_manifest: 605 - path: deltavm/src/tokens/dx.rs 606 action: create 607 purpose: "Core DX token type definition" 608 phase: phase_1 609 - path: deltavm/src/tokens/mod.rs 610 action: modify 611 purpose: "Export DX module" 612 phase: phase_1 613 - path: deltavm/src/genesis/dx_allocation.rs 614 action: create 615 purpose: "Genesis allocation structures" 616 phase: phase_1 617 - path: deltavm/src/genesis/mod.rs 618 action: modify 619 purpose: "Export genesis module" 620 phase: phase_1 621 - path: deltavm/src/vesting/dx_vesting.rs 622 action: create 623 purpose: "Vesting schedule logic" 624 phase: phase_1 625 - path: deltavm/src/vesting/mod.rs 626 action: modify 627 purpose: "Export vesting module" 628 phase: phase_1 629 - path: deltavm/src/privacy/dx_shielded.rs 630 action: create 631 purpose: "ZK shielded holdings" 632 phase: phase_2 633 - path: deltavm/src/privacy/mod.rs 634 action: modify 635 purpose: "Export privacy module" 636 phase: phase_2 637 - path: deltavm/src/queries/dx_balance.rs 638 action: create 639 purpose: "Shielded balance queries" 640 phase: phase_2 641 - path: deltavm/src/grants/network_pool.rs 642 action: create 643 purpose: "Network pool grant types" 644 phase: phase_3 645 - path: deltavm/src/grants/pool_closure.rs 646 action: create 647 purpose: "Pool closure logic" 648 phase: phase_3 649 - path: deltavm/src/grants/sale_restrictions.rs 650 action: create 651 purpose: "Treasury-only sale enforcement" 652 phase: phase_3 653 - path: deltavm/src/grants/mod.rs 654 action: modify 655 purpose: "Export grants module" 656 phase: phase_3 657 - path: deltavm/src/governance/voting_power.rs 658 action: create 659 purpose: "Governance voting power interface" 660 phase: phase_4 661 - path: deltavm/src/governance/mod.rs 662 action: modify 663 purpose: "Export governance module" 664 phase: phase_4 665 - path: deltavm/src/dividends/rights.rs 666 action: create 667 purpose: "Dividend rights interface" 668 phase: phase_4 669 - path: deltavm/src/dividends/mod.rs 670 action: modify 671 purpose: "Export dividends module" 672 phase: phase_4 673 - path: deltavm/tests/integration/dx_token_test.rs 674 action: create 675 purpose: "Integration test suite" 676 phase: phase_5 677 678 secondary_repos: [] 679 680 # === COMPLEXITY ASSESSMENT === 681 complexity_assessment: 682 overall_complexity: medium 683 684 risk_summary: 685 - risk_id: RISK-001 686 description: "ZK circuit complexity for shielded holdings" 687 likelihood: medium 688 impact: high 689 mitigation: "Start with simpler commitment scheme, iterate" 690 691 - risk_id: RISK-002 692 description: "Vesting schedule edge cases (leap years, time zones)" 693 likelihood: low 694 impact: medium 695 mitigation: "Use block-based timing instead of wall clock" 696 697 - risk_id: RISK-003 698 description: "Genesis allocation immutability" 699 likelihood: low 700 impact: critical 701 mitigation: "Extensive testing, formal verification of totals" 702 703 # === DEPENDENCIES SUMMARY === 704 dependencies_summary: 705 blocks: [T006, T007, D008] 706 blocked_by: [] 707 parallel_candidates: [T001, T004, T005, T008] 708 709 # === CHANGELOG === 710 changelog: 711 - version: 1.1.0 712 date: 2026-01-07 713 type: revision 714 description: "Added parallel_workstreams section for testing, CI workflows, and documentation" 715 716 - version: 1.0.0 717 date: 2026-01-07 718 type: initial 719 description: "Initial implementation plan for DX token"