1  # D003-hybrid_privacy.plan.cspec
  2  # Implementation Plan for Hybrid Privacy Model
  3  
  4  plan_metadata:
  5    component_id: D003
  6    component_ref: components/delta/D003-hybrid_privacy.component.cspec
  7    plan_version: 1.1.0
  8    plan_status: phase_1_complete
  9    created: 2026-01-07
 10    updated: 2026-01-09
 11  
 12  wave_context:
 13    topological_level: 0
 14    is_root: true
 15    upstream_components: [D001]
 16    downstream_components: [D004]
 17    critical_path: true
 18    cascade_group: delta_privacy
 19  
 20  phases:
 21    - phase_id: phase_1
 22      name: "Privacy Model Foundation"
 23      status: pending
 24      blocked_by: []
 25  
 26      tasks:
 27        - task_id: D003-T001
 28          name: "Define privacy boundary types"
 29          description: "Create type definitions for public vs private data categories"
 30          target_files:
 31            - path: deltavm/src/privacy/types.rs
 32              action: create
 33            - path: deltavm/src/privacy/mod.rs
 34              action: create
 35          estimate:
 36            effort: medium
 37            confidence: high
 38          risk:
 39            level: low
 40            factors: []
 41  
 42        - task_id: D003-T002
 43          name: "Implement shielded record structure"
 44          description: "Core data structure for zk_shielded_records used in dx_holdings"
 45          target_files:
 46            - path: deltavm/src/privacy/shielded.rs
 47              action: create
 48          estimate:
 49            effort: large
 50            confidence: medium
 51          risk:
 52            level: medium
 53            factors:
 54              - "ZK proof integration complexity"
 55              - "Cross-chain verification requirements"
 56  
 57        - task_id: D003-T003
 58          name: "Define public orderbook visibility layer"
 59          description: "Interface for exposing order_book_entries, trade_executions, market_prices, trading_volumes"
 60          target_files:
 61            - path: deltavm/src/privacy/public_layer.rs
 62              action: create
 63          estimate:
 64            effort: small
 65            confidence: high
 66          risk:
 67            level: low
 68            factors: []
 69  
 70      deliverables:
 71        - deliverable_id: D003-D001
 72          name: "Privacy type system"
 73          type: code
 74          verification: "cargo test --package deltavm --lib privacy::types"
 75  
 76        - deliverable_id: D003-D002
 77          name: "Shielded record implementation"
 78          type: code
 79          verification: "cargo test --package deltavm --lib privacy::shielded"
 80  
 81      test_requirements:
 82        unit:
 83          - test_id: D003-UT001
 84            description: "Privacy boundary classification correctness"
 85          - test_id: D003-UT002
 86            description: "Shielded record serialization/deserialization"
 87          - test_id: D003-UT003
 88            description: "Public data extraction does not leak private fields"
 89  
 90      success_criteria:
 91        - "Privacy type system compiles and passes unit tests"
 92        - "Shielded records can be created, serialized, and verified"
 93        - "Public layer exposes only designated public fields"
 94  
 95      estimated_duration: 2w
 96  
 97    - phase_2:
 98      phase_id: phase_2
 99      name: "Private Holdings System"
100      status: pending
101      blocked_by:
102        - dependency_ref: D003.phase_1
103          reason: "Requires shielded record types from phase 1"
104          wait_for: complete
105  
106      tasks:
107        - task_id: D003-T004
108          name: "Implement DX holdings privacy"
109          description: "ZK-shielded storage for DX token balances"
110          target_files:
111            - path: deltavm/src/privacy/dx_holdings.rs
112              action: create
113            - path: deltavm/src/state/shielded_state.rs
114              action: create
115          estimate:
116            effort: large
117            confidence: medium
118          risk:
119            level: high
120            factors:
121              - "ZK circuit complexity"
122              - "State commitment verification"
123  
124        - task_id: D003-T005
125          name: "Implement dividend payment privacy"
126          description: "Private dividend claim mechanism supporting private_sax_or_alpha_withdraw"
127          target_files:
128            - path: deltavm/src/privacy/dividends.rs
129              action: create
130          estimate:
131            effort: medium
132            confidence: medium
133          risk:
134            level: medium
135            factors:
136              - "Cross-chain coordination with ALPHA for withdrawals"
137  
138        - task_id: D003-T006
139          name: "Implement trading address recycling"
140          description: "Address recycling mechanism for trading privacy"
141          target_files:
142            - path: deltavm/src/privacy/address_recycling.rs
143              action: create
144          estimate:
145            effort: medium
146            confidence: high
147          risk:
148            level: low
149            factors: []
150  
151      deliverables:
152        - deliverable_id: D003-D003
153          name: "Private DX holdings system"
154          type: code
155          verification: "cargo test --package deltavm --lib privacy::dx_holdings"
156  
157        - deliverable_id: D003-D004
158          name: "Private dividend system"
159          type: code
160          verification: "cargo test --package deltavm --lib privacy::dividends"
161  
162      test_requirements:
163        unit:
164          - test_id: D003-UT004
165            description: "DX balance updates preserve privacy"
166          - test_id: D003-UT005
167            description: "Dividend claims do not reveal holder identity"
168          - test_id: D003-UT006
169            description: "Recycled addresses break transaction linkability"
170        integration:
171          - test_id: D003-IT001
172            description: "End-to-end private balance query"
173            dependencies: [D003-T004]
174  
175      success_criteria:
176        - "DX holdings are fully shielded with ZK proofs"
177        - "Dividend payments cannot be linked to holder addresses"
178        - "Trading addresses are recycled correctly"
179  
180      estimated_duration: 3w
181  
182    - phase_3:
183      phase_id: phase_3
184      name: "Interface Stabilization"
185      status: pending
186      blocked_by:
187        - dependency_ref: D003.phase_2
188          reason: "Requires complete private holdings implementation"
189          wait_for: complete
190  
191      tasks:
192        - task_id: D003-T007
193          name: "Stabilize public orderbook interface"
194          description: "Finalize interface_public_orderbook for D004 consumption"
195          target_files:
196            - path: deltavm/src/privacy/interface_public.rs
197              action: create
198          estimate:
199            effort: small
200            confidence: high
201          risk:
202            level: low
203            factors: []
204  
205        - task_id: D003-T008
206          name: "Stabilize private balance query interface"
207          description: "Finalize interface_private_balances for authenticated queries"
208          target_files:
209            - path: deltavm/src/privacy/interface_private.rs
210              action: create
211          estimate:
212            effort: medium
213            confidence: high
214          risk:
215            level: low
216            factors: []
217  
218        - task_id: D003-T009
219          name: "Cross-chain ownership mapping"
220          description: "Implement ownership_mapping stored_on_alpha (fully_private)"
221          target_files:
222            - path: deltavm/src/privacy/ownership_mapping.rs
223              action: create
224          estimate:
225            effort: medium
226            confidence: medium
227          risk:
228            level: medium
229            factors:
230              - "Cross-chain state synchronization"
231              - "Privacy preservation during mapping lookup"
232  
233      deliverables:
234        - deliverable_id: D003-D005
235          name: "interface_public_orderbook"
236          type: interface
237          verification: "Interface documentation and integration test with D004 stubs"
238  
239        - deliverable_id: D003-D006
240          name: "interface_private_balances"
241          type: interface
242          verification: "Authenticated query tests pass"
243  
244      test_requirements:
245        unit:
246          - test_id: D003-UT007
247            description: "Public orderbook interface returns only public data"
248          - test_id: D003-UT008
249            description: "Private balance queries require valid authentication"
250        integration:
251          - test_id: D003-IT002
252            description: "D004 spot engine can read public orderbook"
253            dependencies: [D003-T007]
254          - test_id: D003-IT003
255            description: "Cross-chain ownership lookup works"
256            dependencies: [D003-T009]
257  
258      success_criteria:
259        - "interface_public_orderbook is stable and documented"
260        - "interface_private_balances is stable and documented"
261        - "Ownership mapping preserves full privacy"
262        - "D004 can integrate without breaking changes"
263  
264      estimated_duration: 2w
265  
266  # === PARALLEL WORKSTREAMS ===
267  # Tests, CI, and docs evolve alongside implementation
268  parallel_workstreams:
269  
270    testing:
271      strategy: test_alongside
272      coverage_targets:
273        unit_minimum: 80
274        integration_required: true
275  
276      per_phase_requirements:
277        - phase_ref: phase_1
278          unit_tests:
279            - Privacy boundary classification correctness
280            - Shielded record serialization/deserialization
281            - Public data extraction does not leak private fields
282            - ZK proof verification basics
283          test_files:
284            - path: deltavm/src/privacy/tests.rs
285              action: create
286            - path: deltavm/src/privacy/types_tests.rs
287              action: create
288  
289        - phase_ref: phase_2
290          unit_tests:
291            - DX balance updates preserve privacy
292            - Dividend claims do not reveal holder identity
293            - Recycled addresses break transaction linkability
294            - Shielded state commitment verification
295          integration_tests:
296            - End-to-end private balance query
297          test_files:
298            - path: deltavm/src/privacy/dx_holdings_tests.rs
299              action: create
300            - path: deltavm/src/privacy/dividends_tests.rs
301              action: create
302            - path: deltavm/tests/integration/private_balance.rs
303              action: create
304  
305        - phase_ref: phase_3
306          unit_tests:
307            - Public orderbook interface returns only public data
308            - Private balance queries require valid authentication
309            - Ownership mapping privacy preservation
310          integration_tests:
311            - D004 spot engine can read public orderbook
312            - Cross-chain ownership lookup works
313          test_files:
314            - path: deltavm/src/privacy/interface_tests.rs
315              action: create
316            - path: deltavm/tests/integration/privacy_interfaces.rs
317              action: create
318  
319      ci_test_gates:
320        - gate_id: unit_tests
321          command: cargo test --package deltavm --lib privacy
322          required: true
323        - gate_id: integration_tests
324          command: cargo test --package deltavm --test '*privacy*'
325          required: true
326        - gate_id: clippy
327          command: cargo clippy --package deltavm -- -D warnings
328          required: true
329        - gate_id: fmt
330          command: cargo fmt --package deltavm --check
331          required: true
332        - gate_id: zk_proof_tests
333          command: cargo test --package deltavm --lib privacy::shielded
334          required: true
335  
336    ci_workflows:
337      affected_workflows:
338        - workflow_file: .forgejo/workflows/ci.yml
339          repo: deltavm
340          triggers: [phase_1, phase_2, phase_3]
341  
342      per_phase_ci_tasks:
343        - phase_ref: phase_1
344          workflow_changes:
345            - file: .forgejo/workflows/ci.yml
346              change_type: modify_job
347              description: Add privacy module build and test job
348  
349        - phase_ref: phase_2
350          workflow_changes:
351            - file: .forgejo/workflows/ci.yml
352              change_type: add_step
353              description: Add ZK proof verification tests
354  
355        - phase_ref: phase_3
356          workflow_changes:
357            - file: .forgejo/workflows/ci.yml
358              change_type: add_step
359              description: Add privacy interface integration tests
360  
361      required_ci_checks:
362        - check_name: build
363          check_type: build
364          blocking: true
365        - check_name: test
366          check_type: test
367          blocking: true
368        - check_name: clippy
369          check_type: lint
370          blocking: true
371        - check_name: fmt
372          check_type: lint
373          blocking: true
374        - check_name: zk_tests
375          check_type: test
376          blocking: true
377  
378    documentation:
379      cspec_update_policy: on_interface_change
380  
381      component_cspec_updates:
382        - cspec_file: components/delta/D003-hybrid_privacy.component.cspec
383          update_triggers:
384            - phase_ref: phase_1
385              fields_to_update: [implementation_status]
386              description: Mark privacy foundation complete
387            - phase_ref: phase_2
388              fields_to_update: [implementation_status, interfaces]
389              description: Mark interface_private_balances available
390            - phase_ref: phase_3
391              fields_to_update: [implementation_status, interfaces]
392              description: Mark all privacy interfaces stable
393  
394      session_logging:
395        required: true
396        log_location: sessions/
397        log_format: cspec
398        log_triggers:
399          - phase_complete
400          - blocker_encountered
401          - interface_change
402          - major_decision
403          - cross_component_coordination
404  
405      changelog_policy:
406        update_frequency: per_phase
407        required_fields:
408          - version
409          - date
410          - type
411          - description
412          - affected_interfaces
413  
414      human_doc_derivation:
415        target_human_doc: project/architecture/human/hybrid-privacy.md
416        regenerate_triggers:
417          - phase_2  # Private holdings complete
418          - phase_3  # All interfaces stable
419  
420  # === INTERFACE COMMITMENTS ===
421  interface_commitments:
422    provides:
423      - interface_id: interface_public_orderbook
424        name: "Public Orderbook Visibility"
425        stability: experimental
426        available_from: phase_1
427        stable_from: phase_3
428        consumers: [D004, D005]
429  
430      - interface_id: interface_private_balances
431        name: "Private Balance Queries"
432        stability: experimental
433        available_from: phase_2
434        stable_from: phase_3
435        consumers: [D004]
436  
437    requires:
438      - interface_ref: D001.interface_dex_rationale
439        minimum_stability: stable
440        required_from: phase_1
441  
442  repository_targets:
443    primary_repo:
444      name: deltavm
445      branch_strategy: feature_branch
446  
447    file_manifest:
448      - path: deltavm/src/privacy/mod.rs
449        action: create
450        purpose: "Privacy module root"
451        phase: phase_1
452  
453      - path: deltavm/src/privacy/types.rs
454        action: create
455        purpose: "Privacy boundary type definitions"
456        phase: phase_1
457  
458      - path: deltavm/src/privacy/shielded.rs
459        action: create
460        purpose: "Shielded record implementation"
461        phase: phase_1
462  
463      - path: deltavm/src/privacy/public_layer.rs
464        action: create
465        purpose: "Public data exposure layer"
466        phase: phase_1
467  
468      - path: deltavm/src/privacy/dx_holdings.rs
469        action: create
470        purpose: "Private DX token holdings"
471        phase: phase_2
472  
473      - path: deltavm/src/privacy/dividends.rs
474        action: create
475        purpose: "Private dividend payments"
476        phase: phase_2
477  
478      - path: deltavm/src/privacy/address_recycling.rs
479        action: create
480        purpose: "Trading address recycling"
481        phase: phase_2
482  
483      - path: deltavm/src/state/shielded_state.rs
484        action: create
485        purpose: "Shielded state storage"
486        phase: phase_2
487  
488      - path: deltavm/src/privacy/interface_public.rs
489        action: create
490        purpose: "Public orderbook interface"
491        phase: phase_3
492  
493      - path: deltavm/src/privacy/interface_private.rs
494        action: create
495        purpose: "Private balance query interface"
496        phase: phase_3
497  
498      - path: deltavm/src/privacy/ownership_mapping.rs
499        action: create
500        purpose: "Cross-chain ownership mapping"
501        phase: phase_3
502  
503    secondary_repos: []
504  
505  complexity_assessment:
506    overall_complexity: high
507  
508    risk_summary:
509      - risk_id: RISK-001
510        description: "ZK proof integration may require specialized cryptographic expertise"
511        likelihood: medium
512        impact: high
513        mitigation: "Early consultation with cryptography team; use proven ZK libraries"
514  
515      - risk_id: RISK-002
516        description: "Cross-chain privacy preservation during ownership mapping"
517        likelihood: medium
518        impact: high
519        mitigation: "Design ownership mapping to store on ALPHA chain only; never expose on DELTA"
520  
521      - risk_id: RISK-003
522        description: "Performance impact of shielded record operations"
523        likelihood: medium
524        impact: medium
525        mitigation: "Benchmark early; optimize critical paths; consider hardware acceleration"
526  
527  dependencies_summary:
528    blocks: [D004, D005]
529    blocked_by: [D001]
530    parallel_candidates: [D002]
531  
532  changelog:
533    - version: 1.1.0
534      date: 2026-01-07
535      type: revision
536      description: "Added parallel_workstreams section for testing, CI, and documentation"
537    - version: 1.0.0
538      date: 2026-01-07
539      type: initial
540      description: "Initial implementation plan for hybrid privacy model"