1  # A001-credits_only.plan.cspec
  2  # Implementation plan for Credits-Only Model (ALPHA)
  3  
  4  # === PLAN METADATA ===
  5  plan_metadata:
  6    component_id: A001
  7    component_ref: components/alpha/A001-credits_only.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  wave_context:
 15    topological_level: 0
 16    is_root: true
 17    upstream_components: []
 18    downstream_components: [A004]
 19    critical_path: true
 20    cascade_group: alpha_foundation
 21  
 22  # === PHASES ===
 23  phases:
 24    - phase_id: phase_1
 25      name: "Core Credits Program Implementation"
 26      status: pending
 27      blocked_by: []
 28  
 29      tasks:
 30        - task_id: A001-T001
 31          name: "Define credits.alpha program structure"
 32          description: "Create the single audited program for all credit operations"
 33          target_files:
 34            - path: alphavm/programs/credits/mod.rs
 35              action: create
 36            - path: alphavm/programs/credits/lib.rs
 37              action: create
 38          estimate:
 39            effort: medium
 40            confidence: high
 41          risk:
 42            level: low
 43            factors: [well_understood_pattern]
 44  
 45        - task_id: A001-T002
 46          name: "Implement AX token type"
 47          description: "Define AX native token with decimals:4, microcredits:10000/AX, zk_full privacy, record_utxo state"
 48          target_files:
 49            - path: alphavm/programs/credits/types.rs
 50              action: create
 51          estimate:
 52            effort: small
 53            confidence: high
 54          risk:
 55            level: low
 56            factors: []
 57  
 58        - task_id: A001-T003
 59          name: "Implement credit_transfer operation"
 60          description: "Core transfer logic with ZK proof generation"
 61          target_files:
 62            - path: alphavm/programs/credits/transfer.rs
 63              action: create
 64          estimate:
 65            effort: medium
 66            confidence: medium
 67          risk:
 68            level: medium
 69            factors: [zk_proof_complexity]
 70  
 71        - task_id: A001-T004
 72          name: "Implement credit_mint operation"
 73          description: "GOV-only mint operation for AX supply management"
 74          target_files:
 75            - path: alphavm/programs/credits/mint.rs
 76              action: create
 77          estimate:
 78            effort: small
 79            confidence: high
 80          risk:
 81            level: medium
 82            factors: [governance_integration]
 83  
 84        - task_id: A001-T005
 85          name: "Implement credit_burn operation"
 86          description: "Burn operation for AX supply reduction"
 87          target_files:
 88            - path: alphavm/programs/credits/burn.rs
 89              action: create
 90          estimate:
 91            effort: small
 92            confidence: high
 93          risk:
 94            level: low
 95            factors: []
 96  
 97      deliverables:
 98        - deliverable_id: A001-D001
 99          name: "credits.alpha program"
100          type: code
101          verification: "Program compiles, single entry point for all credit ops"
102        - deliverable_id: A001-D002
103          name: "AX token type definition"
104          type: code
105          verification: "Type validates decimals:4, privacy:zk_full, state:record_utxo"
106  
107      test_requirements:
108        unit:
109          - test_id: A001-UT001
110            description: "AX token instantiation and validation"
111          - test_id: A001-UT002
112            description: "Transfer operation correctness"
113          - test_id: A001-UT003
114            description: "Mint operation GOV-only enforcement"
115          - test_id: A001-UT004
116            description: "Burn operation balance check"
117        integration:
118          - test_id: A001-IT001
119            description: "Full transfer cycle with ZK proof"
120            dependencies: [A001-UT002]
121  
122      success_criteria:
123        - "credits.alpha is sole program for credit operations"
124        - "No deployment capability for arbitrary programs"
125        - "All 3 events (credit_transfer, credit_mint, credit_burn) emit correctly"
126        - "13 instructions maximum (vs 85+ in full Aleo)"
127        - "5 types maximum (vs 20+ in full Aleo)"
128  
129      estimated_duration: 2w
130  
131    - phase_id: phase_2
132      name: "Program Deployment Lockdown"
133      status: pending
134      blocked_by: []
135  
136      tasks:
137        - task_id: A001-T006
138          name: "Disable program deployment mechanism"
139          description: "Remove/disable all code paths that allow arbitrary program deployment"
140          target_files:
141            - path: alphavm/src/deployment.rs
142              action: modify
143            - path: alphavm/src/vm/execute.rs
144              action: modify
145          estimate:
146            effort: medium
147            confidence: medium
148          risk:
149            level: medium
150            factors: [accidental_reintroduction, upgrade_paths]
151  
152        - task_id: A001-T007
153          name: "Add deployment denial tests"
154          description: "Explicit tests verifying program deployment is rejected"
155          target_files:
156            - path: alphavm/tests/deployment_denied_test.rs
157              action: create
158          estimate:
159            effort: small
160            confidence: high
161          risk:
162            level: low
163            factors: []
164  
165      deliverables:
166        - deliverable_id: A001-D003
167          name: "Deployment lockdown"
168          type: code
169          verification: "All deployment attempts return error"
170        - deliverable_id: A001-D004
171          name: "Deployment denial test suite"
172          type: test
173          verification: "Tests pass, coverage >95% on deployment paths"
174  
175      test_requirements:
176        unit:
177          - test_id: A001-UT005
178            description: "Deployment request returns DeploymentDisabled error"
179          - test_id: A001-UT006
180            description: "No deployment instructions exist in instruction set"
181        integration:
182          - test_id: A001-IT002
183            description: "End-to-end deployment attempt rejection"
184            dependencies: [A001-UT005]
185  
186      success_criteria:
187        - "No code path allows program deployment"
188        - "Deployment attempts return clear error"
189        - "Codebase audit confirms no deployment backdoors"
190  
191      estimated_duration: 1w
192  
193    - phase_id: phase_3
194      name: "Security Hardening & Attack Surface Validation"
195      status: pending
196      blocked_by:
197        - dependency_ref: A001.phase_1
198          reason: "Need credits program before validating security"
199          wait_for: complete
200        - dependency_ref: A001.phase_2
201          reason: "Deployment lockdown must be complete"
202          wait_for: complete
203  
204      tasks:
205        - task_id: A001-T008
206          name: "Formal verification setup"
207          description: "Prepare credits.alpha for formal verification (single program makes this feasible)"
208          target_files:
209            - path: alphavm/formal/credits_spec.rs
210              action: create
211          estimate:
212            effort: large
213            confidence: low
214          risk:
215            level: high
216            factors: [formal_methods_expertise, tool_availability]
217  
218        - task_id: A001-T009
219          name: "Attack surface documentation"
220          description: "Document eliminated attack vectors: reentrancy, logic_bombs, arbitrary_execution"
221          target_files:
222            - path: docs/security/attack_surface_analysis.md
223              action: create
224          estimate:
225            effort: small
226            confidence: high
227          risk:
228            level: low
229            factors: []
230  
231        - task_id: A001-T010
232          name: "Security audit preparation"
233          description: "Prepare package for external security audit of single audited program"
234          target_files:
235            - path: audit/A001_credits_only_audit_package.md
236              action: create
237          estimate:
238            effort: medium
239            confidence: medium
240          risk:
241            level: low
242            factors: [audit_schedule_dependency]
243  
244      deliverables:
245        - deliverable_id: A001-D005
246          name: "Formal verification spec"
247          type: documentation
248          verification: "Spec covers all credits.alpha functions"
249        - deliverable_id: A001-D006
250          name: "Attack surface analysis"
251          type: documentation
252          verification: "Documents all eliminated vectors"
253        - deliverable_id: A001-D007
254          name: "Audit package"
255          type: documentation
256          verification: "Ready for external auditor submission"
257  
258      test_requirements:
259        unit:
260          - test_id: A001-UT007
261            description: "Reentrancy impossible by design"
262          - test_id: A001-UT008
263            description: "No arbitrary code execution paths"
264  
265      success_criteria:
266        - "Formal spec exists for credits.alpha"
267        - "Attack surface reduced by eliminating generic programs"
268        - "Audit package ready for submission"
269        - "60% codebase reduction achieved vs full Aleo"
270  
271      estimated_duration: 2w
272  
273  # === PARALLEL WORKSTREAMS ===
274  # Tests, CI, and docs evolve alongside implementation
275  parallel_workstreams:
276  
277    testing:
278      strategy: test_alongside
279      coverage_targets:
280        unit_minimum: 80
281        integration_required: true
282  
283      per_phase_requirements:
284        - phase_ref: phase_1
285          unit_tests:
286            - AX token instantiation and validation
287            - Credit transfer operation correctness
288            - Mint operation GOV-only enforcement
289            - Burn operation balance verification
290          integration_tests:
291            - Full transfer cycle with ZK proof
292          test_files:
293            - path: alphavm/programs/credits/tests/mod.rs
294              action: create
295            - path: alphavm/programs/credits/tests/transfer_tests.rs
296              action: create
297            - path: alphavm/programs/credits/tests/mint_tests.rs
298              action: create
299            - path: alphavm/programs/credits/tests/burn_tests.rs
300              action: create
301  
302        - phase_ref: phase_2
303          unit_tests:
304            - Deployment request returns DeploymentDisabled error
305            - No deployment instructions in instruction set
306            - Import statement rejection
307          integration_tests:
308            - End-to-end deployment attempt rejection
309          test_files:
310            - path: alphavm/tests/deployment_denied_test.rs
311              action: create
312  
313        - phase_ref: phase_3
314          unit_tests:
315            - Reentrancy impossible by design
316            - No arbitrary code execution paths
317          integration_tests:
318            - Formal spec property validation
319          test_files:
320            - path: alphavm/formal/credits_spec.rs
321              action: create
322            - path: alphavm/tests/security_properties.rs
323              action: create
324  
325      ci_test_gates:
326        - gate_id: unit_tests
327          command: cargo test --package alphavm-credits
328          required: true
329        - gate_id: integration_tests
330          command: cargo test --test '*' --package alphavm
331          required: true
332        - gate_id: clippy
333          command: cargo clippy --package alphavm-credits -- -D warnings
334          required: true
335        - gate_id: fmt
336          command: cargo fmt --check
337          required: true
338  
339    ci_workflows:
340      affected_workflows:
341        - workflow_file: .forgejo/workflows/ci.yml
342          repo: alphavm
343          triggers: [phase_1, phase_2, phase_3]
344  
345      per_phase_ci_tasks:
346        - phase_ref: phase_1
347          workflow_changes:
348            - file: .forgejo/workflows/ci.yml
349              change_type: modify_job
350              description: Add credits program test job
351  
352        - phase_ref: phase_2
353          workflow_changes:
354            - file: .forgejo/workflows/ci.yml
355              change_type: add_step
356              description: Add deployment denial test step
357  
358        - phase_ref: phase_3
359          workflow_changes:
360            - file: .forgejo/workflows/ci.yml
361              change_type: add_step
362              description: Add formal verification step (if tooling available)
363  
364      required_ci_checks:
365        - check_name: build
366          check_type: build
367          blocking: true
368        - check_name: test
369          check_type: test
370          blocking: true
371        - check_name: clippy
372          check_type: lint
373          blocking: true
374        - check_name: fmt
375          check_type: lint
376          blocking: true
377  
378    documentation:
379      cspec_update_policy: on_interface_change
380  
381      component_cspec_updates:
382        - cspec_file: components/alpha/A001-credits_only.component.cspec
383          update_triggers:
384            - phase_ref: phase_1
385              fields_to_update: [implementation_status]
386              description: Mark credits program core complete
387            - phase_ref: phase_2
388              fields_to_update: [implementation_status]
389              description: Mark deployment lockdown complete
390            - phase_ref: phase_3
391              fields_to_update: [implementation_status, interfaces]
392              description: Mark security hardening complete, 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          - security_finding
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/credits-only.md
416        regenerate_triggers:
417          - phase_1  # Core credits program defined
418          - phase_3  # Security hardening complete
419  
420  # === INTERFACE COMMITMENTS ===
421  interface_commitments:
422    provides:
423      - interface_id: interface_credits_program
424        name: "Credits Program Interface"
425        stability: unstable
426        available_from: phase_1
427        stable_from: phase_3
428        consumers: [A004, T001, T002]
429        description: "credits.alpha program providing transfer/mint/burn"
430  
431      - interface_id: interface_whitelisted_ops
432        name: "Whitelisted Operations Interface"
433        stability: unstable
434        available_from: phase_1
435        stable_from: phase_3
436        consumers: [A004]
437        description: "13 allowed instructions (vs 85+ in full Aleo)"
438  
439    requires: []
440  
441  # === REPOSITORY TARGETS ===
442  repository_targets:
443    primary_repo:
444      name: alphavm
445      branch_strategy: feature_branch
446      feature_branch_name: feat/A001-credits-only
447  
448    file_manifest:
449      - path: alphavm/programs/credits/mod.rs
450        action: create
451        purpose: "Credits program module root"
452        phase: phase_1
453      - path: alphavm/programs/credits/lib.rs
454        action: create
455        purpose: "Credits program library entry"
456        phase: phase_1
457      - path: alphavm/programs/credits/types.rs
458        action: create
459        purpose: "AX token type definition"
460        phase: phase_1
461      - path: alphavm/programs/credits/transfer.rs
462        action: create
463        purpose: "Transfer operation implementation"
464        phase: phase_1
465      - path: alphavm/programs/credits/mint.rs
466        action: create
467        purpose: "Mint operation (GOV-only)"
468        phase: phase_1
469      - path: alphavm/programs/credits/burn.rs
470        action: create
471        purpose: "Burn operation implementation"
472        phase: phase_1
473      - path: alphavm/src/deployment.rs
474        action: modify
475        purpose: "Disable arbitrary deployment"
476        phase: phase_2
477      - path: alphavm/src/vm/execute.rs
478        action: modify
479        purpose: "Remove deployment execution paths"
480        phase: phase_2
481      - path: alphavm/tests/deployment_denied_test.rs
482        action: create
483        purpose: "Deployment denial test suite"
484        phase: phase_2
485      - path: alphavm/formal/credits_spec.rs
486        action: create
487        purpose: "Formal verification specification"
488        phase: phase_3
489      - path: docs/security/attack_surface_analysis.md
490        action: create
491        purpose: "Security documentation"
492        phase: phase_3
493      - path: audit/A001_credits_only_audit_package.md
494        action: create
495        purpose: "External audit preparation"
496        phase: phase_3
497  
498    secondary_repos: []
499  
500  # === COMPLEXITY ASSESSMENT ===
501  complexity_assessment:
502    overall_complexity: medium
503    rationale: "Single program is simpler than general VM, but ZK proofs and formal verification add complexity"
504  
505    risk_summary:
506      - risk_id: RISK-001
507        description: "ZK proof generation complexity may cause performance issues"
508        likelihood: medium
509        impact: medium
510        mitigation: "Profile early, optimize prover for single program"
511  
512      - risk_id: RISK-002
513        description: "Deployment lockdown may be accidentally bypassed in future"
514        likelihood: low
515        impact: critical
516        mitigation: "Compile-time checks, CI gates, regular audits"
517  
518      - risk_id: RISK-003
519        description: "Formal verification tooling may be insufficient"
520        likelihood: medium
521        impact: low
522        mitigation: "Start with property-based testing, escalate to formal methods as tools mature"
523  
524  # === DEPENDENCIES SUMMARY ===
525  dependencies_summary:
526    blocks: [A004]
527    blocked_by: []
528    parallel_candidates: [D001, D002, T001]
529  
530  # === CHANGELOG ===
531  changelog:
532    - version: 1.1.0
533      date: 2026-01-07
534      type: revision
535      description: "Added parallel_workstreams section for testing, CI, and documentation"
536  
537    - version: 1.0.0
538      date: 2026-01-07
539      type: initial
540      description: "Initial implementation plan for A001 credits-only model"