T004-fee_model.plan.cspec
1 # T004-fee_model.plan.cspec 2 # Implementation Plan for Fee Model Component 3 # Schema: plan-schema.cspec v1.0.0 4 5 # === PLAN METADATA === 6 plan_metadata: 7 component_id: T004 8 component_ref: components/tokens/T004-fee_model.component.cspec 9 plan_version: 1.1.0 10 plan_status: phase_1_complete 11 created: 2026-01-07 12 updated: 2026-01-09 13 14 # === WAVE CONTEXT === 15 wave_context: 16 topological_level: 0 17 is_root: true 18 upstream_components: [] 19 downstream_components: [] 20 critical_path: false 21 cascade_group: tokenomics 22 23 # === PHASES === 24 phases: 25 - phase_id: phase_1 26 name: Core Fee Types & Calculation Engine 27 status: pending 28 blocked_by: [] 29 30 tasks: 31 - task_id: T004-T001 32 name: Define fee type structures 33 description: "Create Rust types for ALPHA_FEE, DELTA_FEE, FEE_SPLIT with no-gas semantics" 34 target_files: 35 - path: crates/adnet-core/src/fees/types.rs 36 action: create 37 estimate: 38 effort: small 39 confidence: high 40 risk: 41 level: low 42 factors: [straightforward_modeling] 43 44 - task_id: T004-T002 45 name: Implement Alpha fee calculator 46 description: "base_fee + (proof_weight * prover_rate), base=100u, prover_rate=50u/weight" 47 target_files: 48 - path: crates/adnet-core/src/fees/alpha.rs 49 action: create 50 estimate: 51 effort: small 52 confidence: high 53 risk: 54 level: low 55 factors: [simple_arithmetic] 56 57 - task_id: T004-T003 58 name: Implement Delta fee calculator 59 description: "base_fee + (notional * tier_rate), tiers: [0.1%, 0.05%, 0.025%, 0.01%]" 60 target_files: 61 - path: crates/adnet-core/src/fees/delta.rs 62 action: create 63 estimate: 64 effort: medium 65 confidence: high 66 risk: 67 level: low 68 factors: [tier_lookup_logic] 69 70 - task_id: T004-T004 71 name: Create fee module entry point 72 description: "Export fee types and calculators via mod.rs" 73 target_files: 74 - path: crates/adnet-core/src/fees/mod.rs 75 action: create 76 estimate: 77 effort: trivial 78 confidence: high 79 risk: 80 level: low 81 factors: [] 82 83 deliverables: 84 - deliverable_id: T004-D001 85 name: Fee types module 86 type: code 87 verification: "cargo check passes, types compile correctly" 88 - deliverable_id: T004-D002 89 name: Alpha fee calculator 90 type: code 91 verification: "Unit tests pass for formula: 100 + (weight * 50)" 92 - deliverable_id: T004-D003 93 name: Delta fee calculator 94 type: code 95 verification: "Unit tests pass for tiered fee calculation" 96 97 test_requirements: 98 unit: 99 - test_id: T004-UT001 100 description: "Alpha fee calculation: transfer with weight=1.0 yields 150u" 101 - test_id: T004-UT002 102 description: "Delta fee tier boundaries: verify correct tier selection" 103 - test_id: T004-UT003 104 description: "Delta fee calculation at each tier level" 105 - test_id: T004-UT004 106 description: "Edge cases: zero weight, zero notional, boundary volumes" 107 108 success_criteria: 109 - "All fee types defined with proper documentation" 110 - "Alpha fee formula: base_fee + (proof_weight * prover_rate) implemented" 111 - "Delta fee formula with all 4 tiers implemented" 112 - "Unit tests achieve >90% coverage" 113 114 estimated_duration: 2d 115 116 - phase_id: phase_2 117 name: Tier Management & Volume Tracking 118 status: pending 119 blocked_by: [] 120 121 tasks: 122 - task_id: T004-T005 123 name: Implement tier resolver 124 description: "Lookup tier based on monthly_volume thresholds: <100k, 100k-1M, 1M-10M, >10M sAX" 125 target_files: 126 - path: crates/adnet-core/src/fees/tiers.rs 127 action: create 128 estimate: 129 effort: small 130 confidence: high 131 risk: 132 level: low 133 factors: [threshold_boundaries] 134 135 - task_id: T004-T006 136 name: Create volume tracker interface 137 description: "Trait for querying user's monthly trading volume (implementation in storage layer)" 138 target_files: 139 - path: crates/adnet-core/src/fees/volume.rs 140 action: create 141 estimate: 142 effort: small 143 confidence: medium 144 risk: 145 level: medium 146 factors: [storage_integration_point] 147 148 - task_id: T004-T007 149 name: Implement fee tier configuration 150 description: "Configurable tier thresholds and rates (for testnet vs mainnet)" 151 target_files: 152 - path: crates/adnet-core/src/fees/config.rs 153 action: create 154 estimate: 155 effort: small 156 confidence: high 157 risk: 158 level: low 159 factors: [] 160 161 deliverables: 162 - deliverable_id: T004-D004 163 name: Tier resolution logic 164 type: code 165 verification: "Correct tier returned for all volume ranges" 166 - deliverable_id: T004-D005 167 name: Volume tracker trait 168 type: interface 169 verification: "Trait compiles, mock implementation works" 170 - deliverable_id: T004-D006 171 name: Fee configuration 172 type: config 173 verification: "Config loads, defaults match spec" 174 175 test_requirements: 176 unit: 177 - test_id: T004-UT005 178 description: "Tier boundary tests: 99999 -> tier1, 100000 -> tier2" 179 - test_id: T004-UT006 180 description: "Volume tracker mock returns expected tiers" 181 - test_id: T004-UT007 182 description: "Config override tests for testnet settings" 183 integration: 184 - test_id: T004-IT001 185 description: "End-to-end tier lookup with mock volume" 186 dependencies: [T004-D004, T004-D005] 187 188 success_criteria: 189 - "Tier resolver correctly maps all 4 tier thresholds" 190 - "Volume tracker trait defined for storage integration" 191 - "Configuration supports testnet/mainnet differentiation" 192 193 estimated_duration: 1d 194 195 - phase_id: phase_3 196 name: Fee Distribution Logic 197 status: pending 198 blocked_by: [] 199 200 tasks: 201 - task_id: T004-T008 202 name: Implement fee splitter 203 description: "Split collected fees: validators 70%, provers 30%, burn 0%, treasury 0%" 204 target_files: 205 - path: crates/adnet-core/src/fees/distribution.rs 206 action: create 207 estimate: 208 effort: small 209 confidence: high 210 risk: 211 level: low 212 factors: [simple_percentage_split] 213 214 - task_id: T004-T009 215 name: Create fee collector trait 216 description: "Interface for collecting and distributing fees (called by runtime)" 217 target_files: 218 - path: crates/adnet-core/src/fees/collector.rs 219 action: create 220 estimate: 221 effort: medium 222 confidence: medium 223 risk: 224 level: medium 225 factors: [runtime_integration_point] 226 227 - task_id: T004-T010 228 name: Add fee events 229 description: "Events for fee collection, distribution (for indexers/explorers)" 230 target_files: 231 - path: crates/adnet-core/src/fees/events.rs 232 action: create 233 estimate: 234 effort: small 235 confidence: high 236 risk: 237 level: low 238 factors: [] 239 240 deliverables: 241 - deliverable_id: T004-D007 242 name: Fee distribution logic 243 type: code 244 verification: "70/30 split verified with rounding tests" 245 - deliverable_id: T004-D008 246 name: Fee collector trait 247 type: interface 248 verification: "Trait compiles, mock collector works" 249 - deliverable_id: T004-D009 250 name: Fee events 251 type: code 252 verification: "Events serialize correctly" 253 254 test_requirements: 255 unit: 256 - test_id: T004-UT008 257 description: "Fee split: 1000u -> validators 700u, provers 300u" 258 - test_id: T004-UT009 259 description: "Rounding behavior: odd amounts handled consistently" 260 - test_id: T004-UT010 261 description: "Event emission on fee collection" 262 integration: 263 - test_id: T004-IT002 264 description: "Full fee flow: calculate -> collect -> distribute" 265 dependencies: [T004-D002, T004-D003, T004-D007] 266 267 success_criteria: 268 - "Fee distribution matches spec: 70% validators, 30% provers" 269 - "No rounding errors in distribution" 270 - "Events emitted for all fee operations" 271 272 estimated_duration: 1d 273 274 - phase_id: phase_4 275 name: Integration & Documentation 276 status: pending 277 blocked_by: [] 278 279 tasks: 280 - task_id: T004-T011 281 name: Integrate with adnet-core lib.rs 282 description: "Export fees module from crate root" 283 target_files: 284 - path: crates/adnet-core/src/lib.rs 285 action: modify 286 estimate: 287 effort: trivial 288 confidence: high 289 risk: 290 level: low 291 factors: [] 292 293 - task_id: T004-T012 294 name: Add rustdoc documentation 295 description: "Document all public types and functions with examples" 296 target_files: 297 - path: crates/adnet-core/src/fees/mod.rs 298 action: modify 299 - path: crates/adnet-core/src/fees/types.rs 300 action: modify 301 - path: crates/adnet-core/src/fees/alpha.rs 302 action: modify 303 - path: crates/adnet-core/src/fees/delta.rs 304 action: modify 305 estimate: 306 effort: small 307 confidence: high 308 risk: 309 level: low 310 factors: [] 311 312 - task_id: T004-T013 313 name: Create integration test suite 314 description: "Full fee calculation and distribution tests" 315 target_files: 316 - path: crates/adnet-core/tests/fees_integration.rs 317 action: create 318 estimate: 319 effort: medium 320 confidence: high 321 risk: 322 level: low 323 factors: [] 324 325 deliverables: 326 - deliverable_id: T004-D010 327 name: Crate integration 328 type: code 329 verification: "cargo doc builds, exports visible" 330 - deliverable_id: T004-D011 331 name: API documentation 332 type: documentation 333 verification: "rustdoc generates complete docs" 334 - deliverable_id: T004-D012 335 name: Integration test suite 336 type: test 337 verification: "cargo test --test fees_integration passes" 338 339 test_requirements: 340 integration: 341 - test_id: T004-IT003 342 description: "Alpha transaction fee: full flow test" 343 dependencies: [T004-D002, T004-D007] 344 - test_id: T004-IT004 345 description: "Delta trade fee: tier selection to distribution" 346 dependencies: [T004-D003, T004-D004, T004-D007] 347 - test_id: T004-IT005 348 description: "Config-driven fee adjustment test" 349 dependencies: [T004-D006] 350 351 success_criteria: 352 - "Fee module exported from adnet-core" 353 - "All public APIs documented with rustdoc" 354 - "Integration tests cover Alpha and Delta fee flows" 355 - "cargo test passes with no warnings" 356 357 estimated_duration: 1d 358 359 # === PARALLEL WORKSTREAMS === 360 # Tests, CI, and docs evolve alongside implementation 361 parallel_workstreams: 362 363 testing: 364 strategy: test_alongside 365 coverage_targets: 366 unit_minimum: 80 367 integration_required: true 368 369 per_phase_requirements: 370 - phase_ref: phase_1 371 unit_tests: 372 - Alpha fee calculation (transfer with weight=1.0 yields 150u) 373 - Delta fee tier boundaries (verify correct tier selection) 374 - Delta fee calculation at each tier level 375 - Edge cases (zero weight, zero notional, boundary volumes) 376 test_files: 377 - path: crates/adnet-core/src/fees/types_tests.rs 378 action: create 379 - path: crates/adnet-core/src/fees/alpha_tests.rs 380 action: create 381 - path: crates/adnet-core/src/fees/delta_tests.rs 382 action: create 383 384 - phase_ref: phase_2 385 unit_tests: 386 - Tier boundary tests (99999 -> tier1, 100000 -> tier2) 387 - Volume tracker mock returns expected tiers 388 - Config override tests for testnet settings 389 integration_tests: 390 - End-to-end tier lookup with mock volume 391 test_files: 392 - path: crates/adnet-core/src/fees/tiers_tests.rs 393 action: create 394 - path: crates/adnet-core/src/fees/volume_tests.rs 395 action: create 396 - path: crates/adnet-core/src/fees/config_tests.rs 397 action: create 398 399 - phase_ref: phase_3 400 unit_tests: 401 - Fee split (1000u -> validators 700u, provers 300u) 402 - Rounding behavior (odd amounts handled consistently) 403 - Event emission on fee collection 404 integration_tests: 405 - Full fee flow (calculate -> collect -> distribute) 406 test_files: 407 - path: crates/adnet-core/src/fees/distribution_tests.rs 408 action: create 409 - path: crates/adnet-core/src/fees/collector_tests.rs 410 action: create 411 - path: crates/adnet-core/src/fees/events_tests.rs 412 action: create 413 414 - phase_ref: phase_4 415 integration_tests: 416 - Alpha transaction fee full flow 417 - Delta trade fee (tier selection to distribution) 418 - Config-driven fee adjustment 419 test_files: 420 - path: crates/adnet-core/tests/fees_integration.rs 421 action: create 422 423 ci_test_gates: 424 - gate_id: unit_tests 425 command: cargo test --workspace 426 required: true 427 - gate_id: integration_tests 428 command: cargo test --test '*' 429 required: true 430 - gate_id: clippy 431 command: cargo clippy --workspace -- -D warnings 432 required: true 433 - gate_id: fmt 434 command: cargo fmt --check 435 required: true 436 437 ci_workflows: 438 affected_workflows: 439 - workflow_file: .forgejo/workflows/ci.yml 440 repo: adnet 441 triggers: [phase_1, phase_3, phase_4] 442 443 per_phase_ci_tasks: 444 - phase_ref: phase_1 445 workflow_changes: 446 - file: .forgejo/workflows/ci.yml 447 change_type: modify_job 448 description: Ensure fee module tests run in adnet-core CI 449 450 - phase_ref: phase_3 451 workflow_changes: 452 - file: .forgejo/workflows/ci.yml 453 change_type: add_step 454 description: Add fee distribution integration test step 455 456 - phase_ref: phase_4 457 workflow_changes: 458 - file: .forgejo/workflows/ci.yml 459 change_type: add_step 460 description: Add full fee flow integration test step 461 462 required_ci_checks: 463 - check_name: build 464 check_type: build 465 blocking: true 466 - check_name: test 467 check_type: test 468 blocking: true 469 - check_name: clippy 470 check_type: lint 471 blocking: true 472 - check_name: fmt 473 check_type: lint 474 blocking: true 475 476 documentation: 477 cspec_update_policy: on_interface_change 478 479 component_cspec_updates: 480 - cspec_file: components/tokens/T004-fee_model.component.cspec 481 update_triggers: 482 - phase_ref: phase_1 483 fields_to_update: [implementation_status] 484 description: Mark fee calculation interfaces available 485 - phase_ref: phase_2 486 fields_to_update: [implementation_status, interfaces] 487 description: Mark fee tier interfaces available 488 - phase_ref: phase_4 489 fields_to_update: [implementation_status, interfaces] 490 description: Mark all interfaces stable 491 492 session_logging: 493 required: true 494 log_location: sessions/ 495 log_format: cspec 496 log_triggers: 497 - phase_complete 498 - blocker_encountered 499 - interface_change 500 - major_decision 501 502 changelog_policy: 503 update_frequency: per_phase 504 required_fields: 505 - version 506 - date 507 - type 508 - description 509 - affected_interfaces 510 511 human_doc_derivation: 512 target_human_doc: project/architecture/human/fee-model.md 513 regenerate_triggers: 514 - phase_4 # All interfaces stable 515 516 # === INTERFACE COMMITMENTS === 517 interface_commitments: 518 provides: 519 - interface_id: interface_fee_calculation 520 name: Fee Calculation Interface 521 stability: stable 522 available_from: phase_1 523 stable_from: phase_4 524 consumers: [] 525 description: | 526 calculate_alpha_fee(proof_weight: u64) -> u64 527 calculate_delta_fee(notional: u128, monthly_volume: u128) -> u64 528 529 - interface_id: interface_fee_tiers 530 name: Fee Tier Interface 531 stability: stable 532 available_from: phase_2 533 stable_from: phase_4 534 consumers: [] 535 description: | 536 get_tier(monthly_volume: u128) -> FeeLevel 537 get_tier_rate(tier: FeeLevel) -> Decimal 538 539 requires: [] 540 541 # === REPOSITORY TARGETS === 542 repository_targets: 543 primary_repo: 544 name: adnet 545 branch_strategy: feature_branch 546 547 file_manifest: 548 - path: crates/adnet-core/src/fees/mod.rs 549 action: create 550 purpose: "Fee module entry point and re-exports" 551 phase: phase_1 552 - path: crates/adnet-core/src/fees/types.rs 553 action: create 554 purpose: "ALPHA_FEE, DELTA_FEE, FEE_SPLIT type definitions" 555 phase: phase_1 556 - path: crates/adnet-core/src/fees/alpha.rs 557 action: create 558 purpose: "Alpha chain fee calculation" 559 phase: phase_1 560 - path: crates/adnet-core/src/fees/delta.rs 561 action: create 562 purpose: "Delta chain fee calculation with tiers" 563 phase: phase_1 564 - path: crates/adnet-core/src/fees/tiers.rs 565 action: create 566 purpose: "Tier resolution logic" 567 phase: phase_2 568 - path: crates/adnet-core/src/fees/volume.rs 569 action: create 570 purpose: "Volume tracker trait" 571 phase: phase_2 572 - path: crates/adnet-core/src/fees/config.rs 573 action: create 574 purpose: "Fee configuration (testnet/mainnet)" 575 phase: phase_2 576 - path: crates/adnet-core/src/fees/distribution.rs 577 action: create 578 purpose: "Fee split: 70% validators, 30% provers" 579 phase: phase_3 580 - path: crates/adnet-core/src/fees/collector.rs 581 action: create 582 purpose: "Fee collector trait for runtime" 583 phase: phase_3 584 - path: crates/adnet-core/src/fees/events.rs 585 action: create 586 purpose: "Fee-related events" 587 phase: phase_3 588 - path: crates/adnet-core/src/lib.rs 589 action: modify 590 purpose: "Export fees module" 591 phase: phase_4 592 - path: crates/adnet-core/tests/fees_integration.rs 593 action: create 594 purpose: "Integration test suite" 595 phase: phase_4 596 597 secondary_repos: [] 598 599 # === COMPLEXITY ASSESSMENT === 600 complexity_assessment: 601 overall_complexity: low 602 603 risk_summary: 604 - risk_id: RISK-001 605 description: "Tier boundary edge cases could cause incorrect fee calculation" 606 likelihood: low 607 impact: medium 608 mitigation: "Comprehensive boundary tests at 99999, 100000, 999999, 1000000, etc." 609 610 - risk_id: RISK-002 611 description: "Rounding in fee distribution could accumulate errors" 612 likelihood: low 613 impact: low 614 mitigation: "Use truncation toward validators, add rounding tests" 615 616 - risk_id: RISK-003 617 description: "Volume tracker integration may require storage layer changes" 618 likelihood: medium 619 impact: low 620 mitigation: "Define trait only, defer implementation to storage component" 621 622 # === DEPENDENCIES SUMMARY === 623 dependencies_summary: 624 blocks: [] 625 blocked_by: [] 626 parallel_candidates: 627 - T001 # token_types 628 - T002 # supply_model 629 - T003 # earn_in 630 - T005 # lp_incentives 631 632 # === CHANGELOG === 633 changelog: 634 - version: 1.1.0 635 date: 2026-01-07 636 type: revision 637 description: "Added parallel_workstreams section for testing, CI workflows, and documentation" 638 639 - version: 1.0.0 640 date: 2026-01-07 641 type: initial 642 description: "Initial implementation plan for T004 Fee Model"