1  # D007-fiat_offramp.plan.cspec
   2  # Implementation Plan for Fiat Off-Ramp Integration
   3  
   4  # === PLAN METADATA ===
   5  plan_metadata:
   6    component_id: D007
   7    component_ref: components/delta/D007-fiat_offramp.component.cspec
   8    plan_version: 1.2.0
   9    plan_status: phase_1_complete
  10    created: 2026-01-07
  11    updated: 2026-01-09
  12  
  13  # === WAVE CONTEXT ===
  14  wave_context:
  15    topological_level: 1
  16    is_root: false
  17    upstream_components: [D006]
  18    downstream_components: []
  19    critical_path: true
  20    cascade_group: fiat_gateway
  21  
  22  # === PHASES ===
  23  phases:
  24    - phase_id: phase_1
  25      name: Core Offramp Types and Storage
  26      status: complete
  27      blocked_by:
  28        - dependency_ref: D006.phase_1
  29          reason: "Requires oracle core types for price references"
  30          wait_for: complete
  31      tasks:
  32        - task_id: D007-T001
  33          name: Define Offramp Core Types
  34          description: "Define OfframpRequest, BankHash, EscrowState, DisputeStatus types"
  35          target_files:
  36            - path: deltavm/src/offramp/types.rs
  37              action: create
  38          estimate:
  39            effort: small
  40            confidence: high
  41          risk:
  42            level: low
  43            factors: []
  44  
  45        - task_id: D007-T002
  46          name: Define Currency Registry
  47          description: "Define supported fiat currencies for offramp (USD, EUR, GBP, etc.)"
  48          target_files:
  49            - path: deltavm/src/offramp/currencies.rs
  50              action: create
  51          estimate:
  52            effort: small
  53            confidence: high
  54          risk:
  55            level: low
  56            factors: []
  57  
  58        - task_id: D007-T003
  59          name: Implement Offramp Storage Module
  60          description: "Storage for offramp requests, escrow states, dispute records"
  61          target_files:
  62            - path: deltavm/src/offramp/storage.rs
  63              action: create
  64          estimate:
  65            effort: medium
  66            confidence: high
  67          risk:
  68            level: low
  69            factors: []
  70  
  71      deliverables:
  72        - deliverable_id: D007-D001
  73          name: Offramp Types Module
  74          type: code
  75          verification: "cargo test offramp::types"
  76        - deliverable_id: D007-D002
  77          name: Currency Registry
  78          type: code
  79          verification: "cargo test offramp::currencies"
  80  
  81      test_requirements:
  82        unit:
  83          - test_id: D007-UT001
  84            description: "Test OfframpRequest serialization and validation"
  85          - test_id: D007-UT002
  86            description: "Test BankHash derivation and verification"
  87          - test_id: D007-UT003
  88            description: "Test EscrowState transitions"
  89  
  90      success_criteria:
  91        - "All offramp types defined with proper validation"
  92        - "Supported currencies enumerated with ISO codes"
  93        - "Storage module compiles and passes unit tests"
  94  
  95      estimated_duration: 2d
  96  
  97    - phase_id: phase_2
  98      name: KYC Integration and Identity Verification
  99      status: pending
 100      blocked_by: []
 101      tasks:
 102        - task_id: D007-T004
 103          name: Define KYC Hash Structure
 104          description: "Define identity_hash storage in GID for offchain KYC reference"
 105          target_files:
 106            - path: deltavm/src/offramp/kyc.rs
 107              action: create
 108          estimate:
 109            effort: medium
 110            confidence: medium
 111          risk:
 112            level: medium
 113            factors: ["privacy_compliance", "hash_collision"]
 114  
 115        - task_id: D007-T005
 116          name: Implement Governor KYC Verification
 117          description: "Governor verifies KYC offchain, signs onchain confirmation"
 118          target_files:
 119            - path: deltavm/src/offramp/kyc.rs
 120              action: modify
 121          estimate:
 122            effort: medium
 123            confidence: medium
 124          risk:
 125            level: high
 126            factors: ["governor_trust", "regulatory_compliance"]
 127  
 128        - task_id: D007-T006
 129          name: Implement Bank Account Hash Verification
 130          description: "Verify bank_hash matches governor-confirmed account"
 131          target_files:
 132            - path: deltavm/src/offramp/bank_verification.rs
 133              action: create
 134          estimate:
 135            effort: small
 136            confidence: high
 137          risk:
 138            level: low
 139            factors: []
 140  
 141      deliverables:
 142        - deliverable_id: D007-D003
 143          name: KYC Integration Module
 144          type: code
 145          verification: "cargo test offramp::kyc"
 146        - deliverable_id: D007-D004
 147          name: Bank Verification Module
 148          type: code
 149          verification: "cargo test offramp::bank_verification"
 150  
 151      test_requirements:
 152        unit:
 153          - test_id: D007-UT004
 154            description: "Test identity hash derivation"
 155          - test_id: D007-UT005
 156            description: "Test governor signature verification for KYC"
 157          - test_id: D007-UT006
 158            description: "Test bank hash verification"
 159  
 160      success_criteria:
 161        - "Identity hash securely derived without exposing PII"
 162        - "Governor KYC signature properly validated"
 163        - "Bank account hash matches registered account"
 164  
 165      estimated_duration: 3d
 166  
 167    - phase_id: phase_3
 168      name: Escrow System Implementation
 169      status: pending
 170      blocked_by: []
 171      tasks:
 172        - task_id: D007-T007
 173          name: Implement AX Escrow Lock
 174          description: "Lock AX in escrow upon offramp request submission"
 175          target_files:
 176            - path: deltavm/src/offramp/escrow.rs
 177              action: create
 178          estimate:
 179            effort: medium
 180            confidence: high
 181          risk:
 182            level: medium
 183            factors: ["atomic_lock_failure", "double_lock"]
 184  
 185        - task_id: D007-T008
 186          name: Implement Escrow State Machine
 187          description: "State transitions: locked -> verified -> completed/disputed"
 188          target_files:
 189            - path: deltavm/src/offramp/escrow.rs
 190              action: modify
 191          estimate:
 192            effort: medium
 193            confidence: high
 194          risk:
 195            level: medium
 196            factors: ["invalid_state_transition"]
 197  
 198        - task_id: D007-T009
 199          name: Implement AX Release to Governor
 200          description: "Release escrowed AX to governor upon completion"
 201          target_files:
 202            - path: deltavm/src/offramp/escrow.rs
 203              action: modify
 204          estimate:
 205            effort: small
 206            confidence: high
 207          risk:
 208            level: medium
 209            factors: ["premature_release"]
 210  
 211      deliverables:
 212        - deliverable_id: D007-D005
 213          name: Escrow System
 214          type: code
 215          verification: "cargo test offramp::escrow"
 216        - deliverable_id: D007-D006
 217          name: Escrow State Machine
 218          type: interface
 219          verification: "State transitions validated in tests"
 220  
 221      test_requirements:
 222        unit:
 223          - test_id: D007-UT007
 224            description: "Test AX lock mechanism"
 225          - test_id: D007-UT008
 226            description: "Test state machine transitions"
 227          - test_id: D007-UT009
 228            description: "Test AX release conditions"
 229        integration:
 230          - test_id: D007-IT001
 231            description: "Test escrow with AlphaVM balance transfers"
 232            dependencies: []
 233  
 234      success_criteria:
 235        - "AX atomically locked in escrow"
 236        - "State machine prevents invalid transitions"
 237        - "AX released only upon valid completion"
 238  
 239      estimated_duration: 3d
 240  
 241    - phase_id: phase_4
 242      name: Exchange Rate Integration with TWAP
 243      status: pending
 244      blocked_by:
 245        - dependency_ref: D006.phase_3
 246          reason: "Requires TWAP-1000 for offramp exchange rate"
 247          wait_for: complete
 248        - dependency_ref: D006.interface_twap
 249          reason: "Must consume TWAP interface for rate derivation"
 250          wait_for: interface_stable
 251      tasks:
 252        - task_id: D007-T010
 253          name: Implement TWAP-1000 Rate Fetch
 254          description: "Fetch TWAP_1000(AX/fiat) for offramp rate calculation"
 255          target_files:
 256            - path: deltavm/src/offramp/exchange_rate.rs
 257              action: create
 258          estimate:
 259            effort: medium
 260            confidence: high
 261          risk:
 262            level: medium
 263            factors: ["rate_staleness", "oracle_dependency"]
 264  
 265        - task_id: D007-T011
 266          name: Implement Rate Validation
 267          description: "Validate rate freshness, reject if oracle stale"
 268          target_files:
 269            - path: deltavm/src/offramp/exchange_rate.rs
 270              action: modify
 271          estimate:
 272            effort: small
 273            confidence: high
 274          risk:
 275            level: low
 276            factors: []
 277  
 278        - task_id: D007-T012
 279          name: Implement Fiat Amount Calculation
 280          description: "Calculate fiat amount = AX amount * TWAP rate - governor fee"
 281          target_files:
 282            - path: deltavm/src/offramp/exchange_rate.rs
 283              action: modify
 284          estimate:
 285            effort: small
 286            confidence: high
 287          risk:
 288            level: medium
 289            factors: ["precision_loss", "fee_calculation"]
 290  
 291      deliverables:
 292        - deliverable_id: D007-D007
 293          name: Exchange Rate Module
 294          type: code
 295          verification: "cargo test offramp::exchange_rate"
 296        - deliverable_id: D007-D008
 297          name: TWAP Integration
 298          type: interface
 299          verification: "Correctly consumes D006 interface_twap"
 300  
 301      test_requirements:
 302        unit:
 303          - test_id: D007-UT010
 304            description: "Test TWAP rate fetching"
 305          - test_id: D007-UT011
 306            description: "Test rate validation and staleness rejection"
 307          - test_id: D007-UT012
 308            description: "Test fiat amount calculation precision"
 309        integration:
 310          - test_id: D007-IT002
 311            description: "Test exchange rate with live oracle data"
 312            dependencies: [D006]
 313  
 314      success_criteria:
 315        - "TWAP-1000 correctly consumed from D006 oracle"
 316        - "Stale oracle data rejects offramp requests"
 317        - "Fiat calculation maintains 4-decimal precision"
 318  
 319      estimated_duration: 2d
 320  
 321    - phase_id: phase_5
 322      name: Governor Fee and Competitive Market
 323      status: pending
 324      blocked_by: []
 325      tasks:
 326        - task_id: D007-T013
 327          name: Implement Governor Fee Structure
 328          description: "Governor sets competitive fee 0.5%-2% per offramp"
 329          target_files:
 330            - path: deltavm/src/offramp/fees.rs
 331              action: create
 332          estimate:
 333            effort: small
 334            confidence: high
 335          risk:
 336            level: low
 337            factors: []
 338  
 339        - task_id: D007-T014
 340          name: Implement Fee Competition Discovery
 341          description: "Allow users to discover governors by fee rate"
 342          target_files:
 343            - path: deltavm/src/offramp/governor_discovery.rs
 344              action: create
 345          estimate:
 346            effort: medium
 347            confidence: medium
 348          risk:
 349            level: low
 350            factors: ["discovery_ux"]
 351  
 352        - task_id: D007-T015
 353          name: Implement Fee Distribution
 354          description: "Fee retained by governor upon completion"
 355          target_files:
 356            - path: deltavm/src/offramp/fees.rs
 357              action: modify
 358          estimate:
 359            effort: small
 360            confidence: high
 361          risk:
 362            level: low
 363            factors: []
 364  
 365      deliverables:
 366        - deliverable_id: D007-D009
 367          name: Fee Structure Module
 368          type: code
 369          verification: "cargo test offramp::fees"
 370        - deliverable_id: D007-D010
 371          name: Governor Discovery
 372          type: code
 373          verification: "cargo test offramp::governor_discovery"
 374  
 375      test_requirements:
 376        unit:
 377          - test_id: D007-UT013
 378            description: "Test fee calculation within bounds"
 379          - test_id: D007-UT014
 380            description: "Test governor fee listing"
 381          - test_id: D007-UT015
 382            description: "Test fee distribution on completion"
 383  
 384      success_criteria:
 385        - "Fees enforced within 0.5%-2% bounds"
 386        - "Users can discover governors by fee"
 387        - "Fee correctly credited to governor"
 388  
 389      estimated_duration: 2d
 390  
 391    - phase_id: phase_6
 392      name: Submit and Complete Offramp Flow
 393      status: pending
 394      blocked_by:
 395        - dependency_ref: D006.phase_4
 396          reason: "Requires staleness check for rate validation"
 397          wait_for: complete
 398      tasks:
 399        - task_id: D007-T016
 400          name: Implement submit_offramp Function
 401          description: "User submits offramp: amount, currency, bank_hash -> escrow"
 402          target_files:
 403            - path: deltavm/src/offramp/submit.rs
 404              action: create
 405          estimate:
 406            effort: medium
 407            confidence: high
 408          risk:
 409            level: medium
 410            factors: ["validation_completeness"]
 411  
 412        - task_id: D007-T017
 413          name: Implement verify_kyc Function
 414          description: "Governor checks KYC offchain, confirms bank onchain"
 415          target_files:
 416            - path: deltavm/src/offramp/verify.rs
 417              action: create
 418          estimate:
 419            effort: medium
 420            confidence: medium
 421          risk:
 422            level: high
 423            factors: ["offchain_coordination"]
 424  
 425        - task_id: D007-T018
 426          name: Implement complete_offramp Function
 427          description: "User confirms or dispute window expires -> AX released"
 428          target_files:
 429            - path: deltavm/src/offramp/complete.rs
 430              action: create
 431          estimate:
 432            effort: medium
 433            confidence: high
 434          risk:
 435            level: medium
 436            factors: ["timeout_handling"]
 437  
 438      deliverables:
 439        - deliverable_id: D007-D011
 440          name: Submit Offramp Function
 441          type: interface
 442          verification: "interface_submit_offramp available"
 443        - deliverable_id: D007-D012
 444          name: Verify KYC Function
 445          type: interface
 446          verification: "interface_verify_kyc available"
 447        - deliverable_id: D007-D013
 448          name: Complete Offramp Function
 449          type: interface
 450          verification: "interface_complete_offramp available"
 451  
 452      test_requirements:
 453        unit:
 454          - test_id: D007-UT016
 455            description: "Test submit_offramp validation"
 456          - test_id: D007-UT017
 457            description: "Test verify_kyc signature validation"
 458          - test_id: D007-UT018
 459            description: "Test complete_offramp conditions"
 460        integration:
 461          - test_id: D007-IT003
 462            description: "Test full offramp flow: submit -> verify -> complete"
 463            dependencies: [D006]
 464  
 465      success_criteria:
 466        - "submit_offramp locks AX in escrow"
 467        - "verify_kyc requires valid governor signature"
 468        - "complete_offramp releases AX after confirmation or timeout"
 469  
 470      estimated_duration: 3d
 471  
 472    - phase_id: phase_7
 473      name: Dispute Resolution System
 474      status: pending
 475      blocked_by: []
 476      tasks:
 477        - task_id: D007-T019
 478          name: Implement Dispute Submission
 479          description: "User can raise dispute within 48h window"
 480          target_files:
 481            - path: deltavm/src/offramp/dispute.rs
 482              action: create
 483          estimate:
 484            effort: medium
 485            confidence: medium
 486          risk:
 487            level: medium
 488            factors: ["dispute_spam", "timing_attacks"]
 489  
 490        - task_id: D007-T020
 491          name: Implement Governance Arbitration
 492          description: "3-governor panel for dispute resolution"
 493          target_files:
 494            - path: deltavm/src/offramp/arbitration.rs
 495              action: create
 496          estimate:
 497            effort: large
 498            confidence: medium
 499          risk:
 500            level: high
 501            factors: ["panel_selection", "collusion_risk"]
 502  
 503        - task_id: D007-T021
 504          name: Implement Dispute Resolution
 505          description: "Panel decision: refund user or complete to governor"
 506          target_files:
 507            - path: deltavm/src/offramp/arbitration.rs
 508              action: modify
 509          estimate:
 510            effort: medium
 511            confidence: medium
 512          risk:
 513            level: medium
 514            factors: ["resolution_finality"]
 515  
 516      deliverables:
 517        - deliverable_id: D007-D014
 518          name: Dispute System
 519          type: code
 520          verification: "cargo test offramp::dispute"
 521        - deliverable_id: D007-D015
 522          name: Arbitration System
 523          type: code
 524          verification: "cargo test offramp::arbitration"
 525  
 526      test_requirements:
 527        unit:
 528          - test_id: D007-UT019
 529            description: "Test dispute submission within window"
 530          - test_id: D007-UT020
 531            description: "Test dispute rejection after window"
 532          - test_id: D007-UT021
 533            description: "Test panel selection randomness"
 534          - test_id: D007-UT022
 535            description: "Test resolution outcomes"
 536        integration:
 537          - test_id: D007-IT004
 538            description: "Test dispute flow with governance"
 539            dependencies: [D003]
 540  
 541      success_criteria:
 542        - "Disputes accepted within 48h window only"
 543        - "3-governor panel correctly selected"
 544        - "Resolution properly releases or refunds AX"
 545  
 546      estimated_duration: 4d
 547  
 548    - phase_id: phase_8
 549      name: Events and Interface Stabilization
 550      status: pending
 551      blocked_by:
 552        - dependency_ref: D006.phase_6
 553          reason: "Requires stable oracle interfaces for final integration"
 554          wait_for: complete
 555      tasks:
 556        - task_id: D007-T022
 557          name: Implement Offramp Events
 558          description: "Emit events: offramp_requested, verified, completed, disputed, resolved"
 559          target_files:
 560            - path: deltavm/src/offramp/events.rs
 561              action: create
 562          estimate:
 563            effort: small
 564            confidence: high
 565          risk:
 566            level: low
 567            factors: []
 568  
 569        - task_id: D007-T023
 570          name: Interface Stabilization
 571          description: "Finalize and stabilize all public offramp interfaces"
 572          target_files:
 573            - path: deltavm/src/offramp/mod.rs
 574              action: modify
 575          estimate:
 576            effort: small
 577            confidence: high
 578          risk:
 579            level: low
 580            factors: []
 581  
 582        - task_id: D007-T024
 583          name: Integration Testing
 584          description: "Full integration test with oracle and governance"
 585          target_files:
 586            - path: deltavm/tests/offramp_integration.rs
 587              action: create
 588          estimate:
 589            effort: medium
 590            confidence: medium
 591          risk:
 592            level: medium
 593            factors: ["multi_component_coordination"]
 594  
 595      deliverables:
 596        - deliverable_id: D007-D016
 597          name: Offramp Events
 598          type: code
 599          verification: "All events emitted correctly"
 600        - deliverable_id: D007-D017
 601          name: Stable Public Interfaces
 602          type: interface
 603          verification: "All interfaces stable and documented"
 604  
 605      test_requirements:
 606        unit:
 607          - test_id: D007-UT023
 608            description: "Test event emission for each state change"
 609        integration:
 610          - test_id: D007-IT005
 611            description: "Full offramp integration: submit -> verify -> complete with oracle"
 612            dependencies: [D006]
 613          - test_id: D007-IT006
 614            description: "Full dispute integration: submit -> verify -> dispute -> resolve"
 615            dependencies: [D003, D006]
 616  
 617      success_criteria:
 618        - "All events properly emitted"
 619        - "All interfaces stable and documented"
 620        - "Integration tests pass with D006 oracle"
 621  
 622      estimated_duration: 2d
 623  
 624  # === PARALLEL WORKSTREAMS ===
 625  # Tests, CI, and docs evolve alongside implementation
 626  parallel_workstreams:
 627  
 628    testing:
 629      strategy: test_alongside
 630      coverage_targets:
 631        unit_minimum: 80
 632        integration_required: true
 633  
 634      per_phase_requirements:
 635        - phase_ref: phase_1
 636          unit_tests:
 637            - OfframpRequest serialization and validation
 638            - BankHash derivation and verification
 639            - EscrowState transitions
 640            - Currency registry enumeration
 641          test_files:
 642            - path: deltavm/src/offramp/types_tests.rs
 643              action: create
 644            - path: deltavm/src/offramp/currencies_tests.rs
 645              action: create
 646            - path: deltavm/src/offramp/storage_tests.rs
 647              action: create
 648  
 649        - phase_ref: phase_2
 650          unit_tests:
 651            - Identity hash derivation security
 652            - Governor signature verification for KYC
 653            - Bank hash verification
 654          test_files:
 655            - path: deltavm/src/offramp/kyc_tests.rs
 656              action: create
 657            - path: deltavm/src/offramp/bank_verification_tests.rs
 658              action: create
 659  
 660        - phase_ref: phase_3
 661          unit_tests:
 662            - AX lock mechanism atomicity
 663            - State machine transition validation
 664            - AX release conditions
 665          integration_tests:
 666            - Escrow with AlphaVM balance transfers
 667          test_files:
 668            - path: deltavm/src/offramp/escrow_tests.rs
 669              action: create
 670            - path: deltavm/tests/integration/escrow_balance.rs
 671              action: create
 672  
 673        - phase_ref: phase_4
 674          unit_tests:
 675            - TWAP rate fetching correctness
 676            - Rate validation and staleness rejection
 677            - Fiat amount calculation precision
 678          integration_tests:
 679            - Exchange rate with live oracle data
 680          test_files:
 681            - path: deltavm/src/offramp/exchange_rate_tests.rs
 682              action: create
 683            - path: deltavm/tests/integration/offramp_oracle.rs
 684              action: create
 685  
 686        - phase_ref: phase_5
 687          unit_tests:
 688            - Fee calculation within bounds (0.5%-2%)
 689            - Governor fee listing
 690            - Fee distribution on completion
 691          test_files:
 692            - path: deltavm/src/offramp/fees_tests.rs
 693              action: create
 694            - path: deltavm/src/offramp/governor_discovery_tests.rs
 695              action: create
 696  
 697        - phase_ref: phase_6
 698          unit_tests:
 699            - submit_offramp validation
 700            - verify_kyc signature validation
 701            - complete_offramp conditions
 702          integration_tests:
 703            - Full offramp flow submit to verify to complete
 704          test_files:
 705            - path: deltavm/src/offramp/submit_tests.rs
 706              action: create
 707            - path: deltavm/src/offramp/verify_tests.rs
 708              action: create
 709            - path: deltavm/src/offramp/complete_tests.rs
 710              action: create
 711            - path: deltavm/tests/integration/offramp_flow.rs
 712              action: create
 713  
 714        - phase_ref: phase_7
 715          unit_tests:
 716            - Dispute submission within window
 717            - Dispute rejection after window
 718            - Panel selection randomness
 719            - Resolution outcomes
 720          integration_tests:
 721            - Dispute flow with governance
 722          test_files:
 723            - path: deltavm/src/offramp/dispute_tests.rs
 724              action: create
 725            - path: deltavm/src/offramp/arbitration_tests.rs
 726              action: create
 727            - path: deltavm/tests/integration/dispute_flow.rs
 728              action: create
 729  
 730        - phase_ref: phase_8
 731          unit_tests:
 732            - Event emission for each state change
 733          integration_tests:
 734            - Full offramp integration with oracle
 735            - Full dispute integration with governance
 736          test_files:
 737            - path: deltavm/src/offramp/events_tests.rs
 738              action: create
 739            - path: deltavm/tests/offramp_integration.rs
 740              action: create
 741  
 742      ci_test_gates:
 743        - gate_id: unit_tests
 744          command: cargo test --package deltavm --lib offramp
 745          required: true
 746        - gate_id: integration_tests
 747          command: cargo test --package deltavm --test '*offramp*'
 748          required: true
 749        - gate_id: clippy
 750          command: cargo clippy --package deltavm -- -D warnings
 751          required: true
 752        - gate_id: fmt
 753          command: cargo fmt --package deltavm --check
 754          required: true
 755  
 756    ci_workflows:
 757      affected_workflows:
 758        - workflow_file: .forgejo/workflows/ci.yml
 759          repo: deltavm
 760          triggers: [phase_1, phase_3, phase_6, phase_8]
 761  
 762      per_phase_ci_tasks:
 763        - phase_ref: phase_1
 764          workflow_changes:
 765            - file: .forgejo/workflows/ci.yml
 766              change_type: modify_job
 767              description: Add offramp module build and test job
 768  
 769        - phase_ref: phase_3
 770          workflow_changes:
 771            - file: .forgejo/workflows/ci.yml
 772              change_type: add_step
 773              description: Add escrow integration tests
 774  
 775        - phase_ref: phase_6
 776          workflow_changes:
 777            - file: .forgejo/workflows/ci.yml
 778              change_type: add_step
 779              description: Add offramp flow integration tests
 780  
 781        - phase_ref: phase_8
 782          workflow_changes:
 783            - file: .forgejo/workflows/ci.yml
 784              change_type: add_step
 785              description: Add full offramp and dispute integration tests
 786  
 787      required_ci_checks:
 788        - check_name: build
 789          check_type: build
 790          blocking: true
 791        - check_name: test
 792          check_type: test
 793          blocking: true
 794        - check_name: clippy
 795          check_type: lint
 796          blocking: true
 797        - check_name: fmt
 798          check_type: lint
 799          blocking: true
 800  
 801    documentation:
 802      cspec_update_policy: on_interface_change
 803  
 804      component_cspec_updates:
 805        - cspec_file: components/delta/D007-fiat_offramp.component.cspec
 806          update_triggers:
 807            - phase_ref: phase_3
 808              fields_to_update: [implementation_status, interfaces]
 809              description: Mark interface_escrow available
 810            - phase_ref: phase_6
 811              fields_to_update: [implementation_status, interfaces]
 812              description: Mark offramp interfaces available
 813            - phase_ref: phase_7
 814              fields_to_update: [implementation_status, interfaces]
 815              description: Mark interface_dispute available
 816            - phase_ref: phase_8
 817              fields_to_update: [implementation_status, interfaces]
 818              description: Mark all interfaces stable
 819  
 820      session_logging:
 821        required: true
 822        log_location: sessions/
 823        log_format: cspec
 824        log_triggers:
 825          - phase_complete
 826          - blocker_encountered
 827          - interface_change
 828          - major_decision
 829          - cross_component_coordination
 830  
 831      changelog_policy:
 832        update_frequency: per_phase
 833        required_fields:
 834          - version
 835          - date
 836          - type
 837          - description
 838          - affected_interfaces
 839  
 840      human_doc_derivation:
 841        target_human_doc: project/architecture/human/fiat-offramp.md
 842        regenerate_triggers:
 843          - phase_6  # Main flow complete
 844          - phase_8  # All interfaces stable
 845  
 846  # === INTERFACE COMMITMENTS ===
 847  interface_commitments:
 848    provides:
 849      - interface_id: interface_submit_offramp
 850        name: Offramp Request Submission
 851        stability: experimental
 852        available_from: phase_6
 853        stable_from: phase_8
 854        consumers: []
 855  
 856      - interface_id: interface_verify_kyc
 857        name: KYC Verification
 858        stability: experimental
 859        available_from: phase_6
 860        stable_from: phase_8
 861        consumers: []
 862  
 863      - interface_id: interface_complete_offramp
 864        name: Offramp Completion
 865        stability: experimental
 866        available_from: phase_6
 867        stable_from: phase_8
 868        consumers: []
 869  
 870      - interface_id: interface_dispute
 871        name: Dispute Submission
 872        stability: experimental
 873        available_from: phase_7
 874        stable_from: phase_8
 875        consumers: []
 876  
 877      - interface_id: interface_escrow
 878        name: Escrow State Management
 879        stability: experimental
 880        available_from: phase_3
 881        stable_from: phase_8
 882        consumers: []
 883  
 884    requires:
 885      - interface_ref: D006.interface_twap
 886        minimum_stability: stable
 887        required_from: phase_4
 888  
 889      - interface_ref: D006.interface_staleness_check
 890        minimum_stability: stable
 891        required_from: phase_6
 892  
 893      - interface_ref: D006.interface_price_feed
 894        minimum_stability: stable
 895        required_from: phase_4
 896  
 897  # === REPOSITORY TARGETS ===
 898  repository_targets:
 899    primary_repo:
 900      name: deltavm
 901      branch_strategy: feature_branch
 902  
 903    file_manifest:
 904      - path: deltavm/src/offramp/mod.rs
 905        action: create
 906        purpose: "Offramp module root with public exports"
 907        phase: phase_1
 908      - path: deltavm/src/offramp/types.rs
 909        action: create
 910        purpose: "Core offramp types (OfframpRequest, BankHash, EscrowState)"
 911        phase: phase_1
 912      - path: deltavm/src/offramp/currencies.rs
 913        action: create
 914        purpose: "Supported fiat currency registry"
 915        phase: phase_1
 916      - path: deltavm/src/offramp/storage.rs
 917        action: create
 918        purpose: "Offramp request and escrow storage"
 919        phase: phase_1
 920      - path: deltavm/src/offramp/kyc.rs
 921        action: create
 922        purpose: "KYC hash structure and verification"
 923        phase: phase_2
 924      - path: deltavm/src/offramp/bank_verification.rs
 925        action: create
 926        purpose: "Bank account hash verification"
 927        phase: phase_2
 928      - path: deltavm/src/offramp/escrow.rs
 929        action: create
 930        purpose: "Escrow lock, state machine, and release"
 931        phase: phase_3
 932      - path: deltavm/src/offramp/exchange_rate.rs
 933        action: create
 934        purpose: "TWAP rate fetching and fiat calculation"
 935        phase: phase_4
 936      - path: deltavm/src/offramp/fees.rs
 937        action: create
 938        purpose: "Governor fee structure and distribution"
 939        phase: phase_5
 940      - path: deltavm/src/offramp/governor_discovery.rs
 941        action: create
 942        purpose: "Governor discovery by fee rate"
 943        phase: phase_5
 944      - path: deltavm/src/offramp/submit.rs
 945        action: create
 946        purpose: "submit_offramp function implementation"
 947        phase: phase_6
 948      - path: deltavm/src/offramp/verify.rs
 949        action: create
 950        purpose: "verify_kyc function implementation"
 951        phase: phase_6
 952      - path: deltavm/src/offramp/complete.rs
 953        action: create
 954        purpose: "complete_offramp function implementation"
 955        phase: phase_6
 956      - path: deltavm/src/offramp/dispute.rs
 957        action: create
 958        purpose: "Dispute submission within 48h window"
 959        phase: phase_7
 960      - path: deltavm/src/offramp/arbitration.rs
 961        action: create
 962        purpose: "3-governor arbitration panel and resolution"
 963        phase: phase_7
 964      - path: deltavm/src/offramp/events.rs
 965        action: create
 966        purpose: "Offramp events (requested, verified, completed, disputed, resolved)"
 967        phase: phase_8
 968      - path: deltavm/tests/offramp_integration.rs
 969        action: create
 970        purpose: "Integration tests for full offramp flow"
 971        phase: phase_8
 972  
 973    secondary_repos: []
 974  
 975  # === COMPLEXITY ASSESSMENT ===
 976  complexity_assessment:
 977    overall_complexity: high
 978  
 979    risk_summary:
 980      - risk_id: RISK-001
 981        description: "Offchain KYC coordination could fail or be inconsistent"
 982        likelihood: medium
 983        impact: high
 984        mitigation: "Define clear KYC attestation protocol, governor accountability"
 985  
 986      - risk_id: RISK-002
 987        description: "Dispute arbitration panel could collude"
 988        likelihood: low
 989        impact: critical
 990        mitigation: "Random panel selection, stake slashing for malicious governors"
 991  
 992      - risk_id: RISK-003
 993        description: "Oracle staleness during offramp could lock funds"
 994        likelihood: medium
 995        impact: medium
 996        mitigation: "Implement graceful degradation, allow cancellation on stale oracle"
 997  
 998      - risk_id: RISK-004
 999        description: "Bank transfer failure outside system control"
1000        likelihood: medium
1001        impact: medium
1002        mitigation: "48h dispute window, clear user communication of offchain risks"
1003  
1004      - risk_id: RISK-005
1005        description: "Regulatory compliance varies by jurisdiction"
1006        likelihood: high
1007        impact: high
1008        mitigation: "Governors responsible for jurisdiction compliance, user attestation"
1009  
1010      - risk_id: RISK-006
1011        description: "Exchange rate manipulation via TWAP timing"
1012        likelihood: low
1013        impact: medium
1014        mitigation: "1000-block TWAP resists short-term manipulation"
1015  
1016  # === DEPENDENCIES SUMMARY ===
1017  dependencies_summary:
1018    blocks: []
1019    blocked_by: [D006]
1020    parallel_candidates: [D005]
1021  
1022  # === CHANGELOG ===
1023  changelog:
1024    - version: 1.1.0
1025      date: 2026-01-07
1026      type: revision
1027      description: "Added parallel_workstreams section for testing, CI, and documentation"
1028    - version: 1.0.0
1029      date: 2026-01-07
1030      type: initial
1031      description: "Initial implementation plan for D007 Fiat Off-Ramp Integration"