A006-privacy_model.plan.cspec
1 # A006-privacy_model.plan.cspec 2 # Implementation Plan for Privacy Model Component 3 # Generated: 2026-01-07 4 5 # === PLAN METADATA === 6 plan_metadata: 7 component_id: A006 8 component_ref: components/alpha/A006-privacy_model.component.cspec 9 plan_version: 1.1.0 10 plan_status: draft 11 created: 2026-01-07 12 updated: 2026-01-07 13 14 # === WAVE CONTEXT === 15 wave_context: 16 topological_level: 0 17 is_root: true 18 upstream_components: [] 19 downstream_components: [] 20 critical_path: true 21 cascade_group: alpha_privacy 22 23 # === PHASES === 24 phases: 25 - phase_id: phase_1 26 name: "Core ZK Verification Infrastructure" 27 status: pending 28 blocked_by: [] 29 tasks: 30 - task_id: A006-T001 31 name: "Define ZK proof types and structures" 32 description: "Create Rust types for ZK proof representations, commitment schemes, and serial numbers" 33 target_files: 34 - path: crates/alphavm/src/privacy/types.rs 35 action: create 36 - path: crates/alphavm/src/privacy/mod.rs 37 action: create 38 estimate: 39 effort: medium 40 confidence: high 41 risk: 42 level: medium 43 factors: 44 - "ZK proof format must align with snarkVM" 45 - "Type definitions affect downstream interfaces" 46 47 - task_id: A006-T002 48 name: "Implement commitment scheme" 49 description: "Pedersen commitment implementation for record commitments" 50 target_files: 51 - path: crates/alphavm/src/privacy/commitment.rs 52 action: create 53 estimate: 54 effort: medium 55 confidence: high 56 risk: 57 level: low 58 factors: 59 - "Well-understood cryptographic primitive" 60 61 - task_id: A006-T003 62 name: "Implement serial number derivation" 63 description: "PRF-based serial number generation for double-spend prevention" 64 target_files: 65 - path: crates/alphavm/src/privacy/serial_number.rs 66 action: create 67 estimate: 68 effort: small 69 confidence: high 70 risk: 71 level: low 72 factors: 73 - "Standard PRF construction" 74 75 deliverables: 76 - deliverable_id: A006-D001 77 name: "ZK type definitions" 78 type: code 79 verification: "cargo check passes, types exported in lib.rs" 80 - deliverable_id: A006-D002 81 name: "Commitment scheme implementation" 82 type: code 83 verification: "Unit tests pass for commit/verify" 84 - deliverable_id: A006-D003 85 name: "Serial number module" 86 type: code 87 verification: "Deterministic SN generation tests pass" 88 89 test_requirements: 90 unit: 91 - test_id: A006-UT001 92 description: "Commitment hiding property" 93 - test_id: A006-UT002 94 description: "Commitment binding property" 95 - test_id: A006-UT003 96 description: "Serial number determinism" 97 - test_id: A006-UT004 98 description: "Serial number uniqueness per record" 99 100 success_criteria: 101 - "All ZK types compile without errors" 102 - "Commitment scheme passes hiding/binding tests" 103 - "Serial numbers are deterministic and unique" 104 - "No unsafe code in cryptographic modules" 105 106 estimated_duration: 3d 107 108 - phase_2: 109 phase_id: phase_2 110 name: "ZK Proof Verification Interface" 111 status: pending 112 blocked_by: [] 113 tasks: 114 - task_id: A006-T004 115 name: "Define interface_zk_verify trait" 116 description: "Public trait for ZK proof verification that other components can depend on" 117 target_files: 118 - path: crates/alphavm/src/privacy/interface.rs 119 action: create 120 estimate: 121 effort: medium 122 confidence: high 123 risk: 124 level: medium 125 factors: 126 - "Interface stability critical for downstream" 127 - "Must support multiple proof types" 128 129 - task_id: A006-T005 130 name: "Implement proof verifier" 131 description: "Groth16 and Marlin proof verification implementations" 132 target_files: 133 - path: crates/alphavm/src/privacy/verifier.rs 134 action: create 135 estimate: 136 effort: large 137 confidence: medium 138 risk: 139 level: high 140 factors: 141 - "Cryptographic complexity" 142 - "Performance critical path" 143 - "Must integrate with snarkVM verification" 144 145 - task_id: A006-T006 146 name: "Verification key management" 147 description: "Storage and retrieval of verification keys for circuits" 148 target_files: 149 - path: crates/alphavm/src/privacy/vk_store.rs 150 action: create 151 estimate: 152 effort: small 153 confidence: high 154 risk: 155 level: low 156 factors: 157 - "Key storage is straightforward" 158 159 deliverables: 160 - deliverable_id: A006-D004 161 name: "interface_zk_verify trait" 162 type: interface 163 verification: "Trait is public, documented, and stable" 164 - deliverable_id: A006-D005 165 name: "Proof verifier implementation" 166 type: code 167 verification: "Verifies valid proofs, rejects invalid proofs" 168 - deliverable_id: A006-D006 169 name: "VK storage module" 170 type: code 171 verification: "Keys retrievable by circuit ID" 172 173 test_requirements: 174 unit: 175 - test_id: A006-UT005 176 description: "Valid proof acceptance" 177 - test_id: A006-UT006 178 description: "Invalid proof rejection" 179 - test_id: A006-UT007 180 description: "Malformed proof handling" 181 integration: 182 - test_id: A006-IT001 183 description: "End-to-end proof generation and verification" 184 dependencies: [] 185 186 success_criteria: 187 - "interface_zk_verify is stable and exported" 188 - "Valid proofs verify correctly" 189 - "Invalid/malformed proofs rejected with proper errors" 190 - "Verification completes within 100ms for standard proofs" 191 192 estimated_duration: 5d 193 194 - phase_id: phase_3 195 name: "Record Encryption Interface" 196 status: pending 197 blocked_by: [] 198 tasks: 199 - task_id: A006-T007 200 name: "Define interface_record_encryption trait" 201 description: "Public trait for record encryption/decryption operations" 202 target_files: 203 - path: crates/alphavm/src/privacy/encryption_interface.rs 204 action: create 205 estimate: 206 effort: medium 207 confidence: high 208 risk: 209 level: medium 210 factors: 211 - "Interface stability for downstream consumers" 212 213 - task_id: A006-T008 214 name: "Implement record encryption" 215 description: "ChaCha20-Poly1305 encryption for record ciphertexts" 216 target_files: 217 - path: crates/alphavm/src/privacy/encryption.rs 218 action: create 219 estimate: 220 effort: medium 221 confidence: high 222 risk: 223 level: medium 224 factors: 225 - "Must use constant-time implementations" 226 - "Key derivation must be secure" 227 228 - task_id: A006-T009 229 name: "View key derivation" 230 description: "Derive view keys from spending keys for transaction decryption" 231 target_files: 232 - path: crates/alphavm/src/privacy/view_key.rs 233 action: create 234 estimate: 235 effort: small 236 confidence: high 237 risk: 238 level: low 239 factors: 240 - "Standard key derivation" 241 242 deliverables: 243 - deliverable_id: A006-D007 244 name: "interface_record_encryption trait" 245 type: interface 246 verification: "Trait is public, documented, and stable" 247 - deliverable_id: A006-D008 248 name: "Record encryption implementation" 249 type: code 250 verification: "Encrypt/decrypt roundtrip succeeds" 251 - deliverable_id: A006-D009 252 name: "View key module" 253 type: code 254 verification: "View key can decrypt owned transactions" 255 256 test_requirements: 257 unit: 258 - test_id: A006-UT008 259 description: "Encryption roundtrip" 260 - test_id: A006-UT009 261 description: "Wrong key decryption failure" 262 - test_id: A006-UT010 263 description: "View key derivation determinism" 264 - test_id: A006-UT011 265 description: "Ciphertext indistinguishability" 266 267 success_criteria: 268 - "interface_record_encryption is stable and exported" 269 - "Encryption is authenticated (AEAD)" 270 - "View keys decrypt owned records only" 271 - "No timing side channels in crypto code" 272 273 estimated_duration: 4d 274 275 - phase_id: phase_4 276 name: "State Model Integration" 277 status: pending 278 blocked_by: [] 279 tasks: 280 - task_id: A006-T010 281 name: "Implement sparse Merkle tree for commitments" 282 description: "Data structure for storing record commitments" 283 target_files: 284 - path: crates/alphavm/src/privacy/merkle.rs 285 action: create 286 estimate: 287 effort: large 288 confidence: medium 289 risk: 290 level: medium 291 factors: 292 - "Tree structure must be efficient" 293 - "Proof generation performance" 294 295 - task_id: A006-T011 296 name: "Serial number nullifier set" 297 description: "Efficient set for tracking spent serial numbers" 298 target_files: 299 - path: crates/alphavm/src/privacy/nullifier_set.rs 300 action: create 301 estimate: 302 effort: medium 303 confidence: high 304 risk: 305 level: low 306 factors: 307 - "Standard set operations" 308 309 - task_id: A006-T012 310 name: "Governor audit interface" 311 description: "Mint/burn log access for governor oversight" 312 target_files: 313 - path: crates/alphavm/src/privacy/audit.rs 314 action: create 315 estimate: 316 effort: small 317 confidence: high 318 risk: 319 level: low 320 factors: 321 - "Public logs, no privacy concerns" 322 323 deliverables: 324 - deliverable_id: A006-D010 325 name: "Sparse Merkle tree" 326 type: code 327 verification: "Insert, lookup, proof generation work correctly" 328 - deliverable_id: A006-D011 329 name: "Nullifier set" 330 type: code 331 verification: "Double-spend detection works" 332 - deliverable_id: A006-D012 333 name: "Audit interface" 334 type: code 335 verification: "Governor can query mint/burn logs" 336 337 test_requirements: 338 unit: 339 - test_id: A006-UT012 340 description: "Merkle tree insert and proof" 341 - test_id: A006-UT013 342 description: "Merkle root updates" 343 - test_id: A006-UT014 344 description: "Nullifier set membership" 345 - test_id: A006-UT015 346 description: "Double-spend detection" 347 integration: 348 - test_id: A006-IT002 349 description: "Full UTXO lifecycle" 350 dependencies: [] 351 352 success_criteria: 353 - "Merkle proofs verify against root" 354 - "Serial numbers prevent double-spending" 355 - "Governor audit access works" 356 - "State updates are atomic" 357 358 estimated_duration: 5d 359 360 - phase_id: phase_5 361 name: "Documentation and Final Testing" 362 status: pending 363 blocked_by: [] 364 tasks: 365 - task_id: A006-T013 366 name: "API documentation" 367 description: "Rustdoc for all public interfaces" 368 target_files: 369 - path: crates/alphavm/src/privacy/mod.rs 370 action: modify 371 estimate: 372 effort: small 373 confidence: high 374 risk: 375 level: low 376 factors: [] 377 378 - task_id: A006-T014 379 name: "Integration test suite" 380 description: "Full privacy flow integration tests" 381 target_files: 382 - path: crates/alphavm/tests/privacy_integration.rs 383 action: create 384 estimate: 385 effort: medium 386 confidence: high 387 risk: 388 level: low 389 factors: [] 390 391 - task_id: A006-T015 392 name: "Security audit preparation" 393 description: "Document security assumptions and attack surface" 394 target_files: 395 - path: crates/alphavm/src/privacy/SECURITY.md 396 action: create 397 estimate: 398 effort: small 399 confidence: high 400 risk: 401 level: low 402 factors: [] 403 404 deliverables: 405 - deliverable_id: A006-D013 406 name: "Complete rustdoc" 407 type: documentation 408 verification: "cargo doc generates without warnings" 409 - deliverable_id: A006-D014 410 name: "Integration tests" 411 type: test 412 verification: "All integration tests pass" 413 - deliverable_id: A006-D015 414 name: "Security documentation" 415 type: documentation 416 verification: "Security review checklist complete" 417 418 test_requirements: 419 integration: 420 - test_id: A006-IT003 421 description: "End-to-end shielded transfer" 422 dependencies: [] 423 - test_id: A006-IT004 424 description: "View key transaction scanning" 425 dependencies: [] 426 - test_id: A006-IT005 427 description: "Governor audit flow" 428 dependencies: [] 429 430 success_criteria: 431 - "All unit tests pass (>90% coverage)" 432 - "All integration tests pass" 433 - "Documentation complete" 434 - "Security assumptions documented" 435 436 estimated_duration: 3d 437 438 # === PARALLEL WORKSTREAMS === 439 # Tests, CI, and docs evolve alongside implementation 440 parallel_workstreams: 441 442 testing: 443 strategy: test_alongside 444 coverage_targets: 445 unit_minimum: 80 446 integration_required: true 447 448 per_phase_requirements: 449 - phase_ref: phase_1 450 unit_tests: 451 - Commitment hiding property 452 - Commitment binding property 453 - Serial number determinism 454 - Serial number uniqueness per record 455 test_files: 456 - path: crates/alphavm/src/privacy/types_tests.rs 457 action: create 458 - path: crates/alphavm/src/privacy/commitment_tests.rs 459 action: create 460 - path: crates/alphavm/src/privacy/serial_number_tests.rs 461 action: create 462 463 - phase_ref: phase_2 464 unit_tests: 465 - Valid proof acceptance 466 - Invalid proof rejection 467 - Malformed proof handling 468 integration_tests: 469 - End-to-end proof generation and verification 470 test_files: 471 - path: crates/alphavm/src/privacy/verifier_tests.rs 472 action: create 473 - path: crates/alphavm/src/privacy/vk_store_tests.rs 474 action: create 475 - path: crates/alphavm/tests/proof_e2e.rs 476 action: create 477 478 - phase_ref: phase_3 479 unit_tests: 480 - Encryption roundtrip 481 - Wrong key decryption failure 482 - View key derivation determinism 483 - Ciphertext indistinguishability 484 test_files: 485 - path: crates/alphavm/src/privacy/encryption_tests.rs 486 action: create 487 - path: crates/alphavm/src/privacy/view_key_tests.rs 488 action: create 489 490 - phase_ref: phase_4 491 unit_tests: 492 - Merkle tree insert and proof 493 - Merkle root updates 494 - Nullifier set membership 495 - Double-spend detection 496 integration_tests: 497 - Full UTXO lifecycle 498 test_files: 499 - path: crates/alphavm/src/privacy/merkle_tests.rs 500 action: create 501 - path: crates/alphavm/src/privacy/nullifier_set_tests.rs 502 action: create 503 - path: crates/alphavm/tests/utxo_lifecycle.rs 504 action: create 505 506 - phase_ref: phase_5 507 integration_tests: 508 - End-to-end shielded transfer 509 - View key transaction scanning 510 - Governor audit flow 511 test_files: 512 - path: crates/alphavm/tests/privacy_integration.rs 513 action: create 514 - path: crates/alphavm/tests/shielded_transfer.rs 515 action: create 516 517 ci_test_gates: 518 - gate_id: unit_tests 519 command: cargo test --package alphavm --lib privacy 520 required: true 521 - gate_id: integration_tests 522 command: cargo test --test '*privacy*' --test '*shielded*' --test '*utxo*' --test '*proof*' 523 required: true 524 - gate_id: clippy 525 command: cargo clippy --package alphavm -- -D warnings 526 required: true 527 - gate_id: fmt 528 command: cargo fmt --check 529 required: true 530 - gate_id: crypto_audit 531 command: cargo audit 532 required: false 533 534 ci_workflows: 535 affected_workflows: 536 - workflow_file: .forgejo/workflows/ci.yml 537 repo: alphavm 538 triggers: [phase_1, phase_2, phase_4, phase_5] 539 540 per_phase_ci_tasks: 541 - phase_ref: phase_1 542 workflow_changes: 543 - file: .forgejo/workflows/ci.yml 544 change_type: add_job 545 description: Add privacy module build and test 546 547 - phase_ref: phase_2 548 workflow_changes: 549 - file: .forgejo/workflows/ci.yml 550 change_type: add_step 551 description: Add ZK proof verification integration tests 552 553 - phase_ref: phase_4 554 workflow_changes: 555 - file: .forgejo/workflows/ci.yml 556 change_type: add_step 557 description: Add Merkle tree and nullifier set tests 558 559 - phase_ref: phase_5 560 workflow_changes: 561 - file: .forgejo/workflows/ci.yml 562 change_type: add_step 563 description: Add full privacy integration test suite 564 - file: .forgejo/workflows/ci.yml 565 change_type: add_job 566 description: Add cargo-audit for cryptographic dependencies (optional) 567 568 required_ci_checks: 569 - check_name: build 570 check_type: build 571 blocking: true 572 - check_name: test 573 check_type: test 574 blocking: true 575 - check_name: clippy 576 check_type: lint 577 blocking: true 578 - check_name: fmt 579 check_type: lint 580 blocking: true 581 - check_name: crypto_audit 582 check_type: security 583 blocking: false 584 585 documentation: 586 cspec_update_policy: on_interface_change 587 588 component_cspec_updates: 589 - cspec_file: components/alpha/A006-privacy_model.component.cspec 590 update_triggers: 591 - phase_ref: phase_1 592 fields_to_update: [implementation_status] 593 description: Mark ZK infrastructure core complete 594 - phase_ref: phase_2 595 fields_to_update: [implementation_status, interfaces] 596 description: Mark ZK verify interface available 597 - phase_ref: phase_3 598 fields_to_update: [implementation_status, interfaces] 599 description: Mark record encryption interface available 600 - phase_ref: phase_4 601 fields_to_update: [implementation_status] 602 description: Mark state model integration complete 603 - phase_ref: phase_5 604 fields_to_update: [implementation_status, interfaces] 605 description: Mark all privacy interfaces stable 606 607 session_logging: 608 required: true 609 log_location: sessions/ 610 log_format: cspec 611 log_triggers: 612 - phase_complete 613 - blocker_encountered 614 - interface_change 615 - major_decision 616 - cryptographic_decision 617 - security_vulnerability_found 618 619 changelog_policy: 620 update_frequency: per_phase 621 required_fields: 622 - version 623 - date 624 - type 625 - description 626 - affected_interfaces 627 628 human_doc_derivation: 629 target_human_doc: project/architecture/human/privacy-model.md 630 regenerate_triggers: 631 - phase_2 # ZK verify interface available 632 - phase_3 # Record encryption available 633 - phase_5 # All privacy interfaces stable 634 635 # === INTERFACE COMMITMENTS === 636 interface_commitments: 637 provides: 638 - interface_id: interface_zk_verify 639 name: "ZK Proof Verification" 640 stability: unstable 641 available_from: phase_2 642 stable_from: phase_5 643 consumers: [] 644 - interface_id: interface_record_encryption 645 name: "Record Encryption/Decryption" 646 stability: unstable 647 available_from: phase_3 648 stable_from: phase_5 649 consumers: [] 650 651 requires: [] 652 653 # === REPOSITORY TARGETS === 654 repository_targets: 655 primary_repo: 656 name: alphavm 657 branch_strategy: feature_branch 658 659 file_manifest: 660 - path: crates/alphavm/src/privacy/mod.rs 661 action: create 662 purpose: "Privacy module entry point" 663 phase: phase_1 664 - path: crates/alphavm/src/privacy/types.rs 665 action: create 666 purpose: "ZK proof and commitment types" 667 phase: phase_1 668 - path: crates/alphavm/src/privacy/commitment.rs 669 action: create 670 purpose: "Pedersen commitment implementation" 671 phase: phase_1 672 - path: crates/alphavm/src/privacy/serial_number.rs 673 action: create 674 purpose: "Serial number derivation" 675 phase: phase_1 676 - path: crates/alphavm/src/privacy/interface.rs 677 action: create 678 purpose: "interface_zk_verify trait definition" 679 phase: phase_2 680 - path: crates/alphavm/src/privacy/verifier.rs 681 action: create 682 purpose: "Proof verification implementation" 683 phase: phase_2 684 - path: crates/alphavm/src/privacy/vk_store.rs 685 action: create 686 purpose: "Verification key storage" 687 phase: phase_2 688 - path: crates/alphavm/src/privacy/encryption_interface.rs 689 action: create 690 purpose: "interface_record_encryption trait" 691 phase: phase_3 692 - path: crates/alphavm/src/privacy/encryption.rs 693 action: create 694 purpose: "Record encryption implementation" 695 phase: phase_3 696 - path: crates/alphavm/src/privacy/view_key.rs 697 action: create 698 purpose: "View key derivation" 699 phase: phase_3 700 - path: crates/alphavm/src/privacy/merkle.rs 701 action: create 702 purpose: "Sparse Merkle tree for commitments" 703 phase: phase_4 704 - path: crates/alphavm/src/privacy/nullifier_set.rs 705 action: create 706 purpose: "Serial number nullifier tracking" 707 phase: phase_4 708 - path: crates/alphavm/src/privacy/audit.rs 709 action: create 710 purpose: "Governor audit interface" 711 phase: phase_4 712 - path: crates/alphavm/tests/privacy_integration.rs 713 action: create 714 purpose: "Privacy integration tests" 715 phase: phase_5 716 - path: crates/alphavm/src/privacy/SECURITY.md 717 action: create 718 purpose: "Security assumptions documentation" 719 phase: phase_5 720 721 secondary_repos: [] 722 723 # === COMPLEXITY ASSESSMENT === 724 complexity_assessment: 725 overall_complexity: high 726 727 risk_summary: 728 - risk_id: RISK-001 729 description: "ZK proof verification performance may not meet targets" 730 likelihood: medium 731 impact: high 732 mitigation: "Benchmark early, optimize critical paths, consider batch verification" 733 - risk_id: RISK-002 734 description: "Cryptographic implementation bugs" 735 likelihood: low 736 impact: critical 737 mitigation: "Use audited libraries, extensive testing, security review" 738 - risk_id: RISK-003 739 description: "Interface changes may break downstream (future)" 740 likelihood: low 741 impact: medium 742 mitigation: "Mark interfaces unstable until phase_5, version carefully" 743 744 # === DEPENDENCIES SUMMARY === 745 dependencies_summary: 746 blocks: [] 747 blocked_by: [] 748 parallel_candidates: [] 749 750 # === CHANGELOG === 751 changelog: 752 - version: 1.1.0 753 date: 2026-01-07 754 type: revision 755 description: "Added parallel_workstreams section for testing, CI, and documentation" 756 757 - version: 1.0.0 758 date: 2026-01-07 759 type: initial 760 description: "Initial implementation plan for A006 Privacy Model"