1  # F001-wallet_core.component.cspec
  2  
  3  metadata:
  4    id: F001
  5    name: wallet_core
  6    version: 1.1.0
  7    domain: frontend
  8    stability: stable
  9    updated: 2026-01-15
 10    cascade_priority: 10
 11    roles:
 12      primary: [Dev, Security]
 13      review: [Security]
 14    expertise:
 15      required: [rust, cryptography, ffi]
 16      helpful: [wasm, mobile_ffi, bls12_377]
 17    context_tags: [wallet, crypto, keys, signing, ffi, wasm]
 18  
 19  dependencies:
 20    upstream: []
 21    downstream: [F002, F003, F004, F005, F006]
 22  
 23  interface:
 24    types_ref: _registry/types.cspec
 25    types:
 26      mnemonic: bip39_24_words
 27      payment_code: bech32m_acdc1_prefix_81_bytes
 28      swap_code: bech32m_swap1_prefix
 29      derivation_path: "m/47'/[BLOX]'/account'/class'/index"
 30      address_class:
 31        0: alpha_private
 32        1: delta_trading_public
 33        2: delta_dx_private
 34        3: reserved
 35      backup_key: "m/47'/[BLOX]'/backup'/0'"
 36  
 37    functions:
 38      generate_mnemonic:
 39        inputs: [entropy: 256_bits]
 40        outputs: [mnemonic: 24_words]
 41      derive_keys:
 42        inputs: [mnemonic, path]
 43        outputs: [keypair]
 44      generate_payment_code:
 45        inputs: [seed]
 46        outputs: [payment_code: acdc1...]
 47      generate_stealth_address:
 48        inputs: [payment_code, counter]
 49        outputs: [stealth_address]
 50      create_multisig_address:
 51        inputs: [signers: [address], threshold: u8]
 52        outputs: [payment_code, group_address]
 53      create_departmental_address:
 54        inputs: [departments: [[address]], thresholds: [u8]]
 55        outputs: [payment_code, org_address]
 56      create_multisig_proposal:
 57        inputs: [tx_data, group_info]
 58        outputs: [proposal_id, partial_tx]
 59      create_departmental_proposal:
 60        inputs: [tx_data, org_structure]
 61        outputs: [proposal_id, partial_tx]
 62      sign_multisig_proposal:
 63        inputs: [proposal_id, keypair]
 64        outputs: [signature]
 65      aggregate_multisig_signatures:
 66        inputs: [proposal_id, signatures: [signature]]
 67        outputs: [final_tx]
 68      sign_transaction:
 69        inputs: [tx_data, keypair]
 70        outputs: [signature]
 71      encrypt_backup:
 72        inputs: [data, backup_key]
 73        outputs: [ciphertext]
 74      decrypt_backup:
 75        inputs: [ciphertext, backup_key]
 76        outputs: [plaintext]
 77      shamir_split:
 78        inputs: [secret, n, k]
 79        outputs: [shares: n]
 80      shamir_reconstruct:
 81        inputs: [shares: k]
 82        outputs: [secret]
 83  
 84    events: []
 85  
 86    constants:
 87      COIN_TYPE_BLOX: TBD  # Register with SLIP-44
 88      PAYMENT_CODE_VERSION: 0x01
 89      CHECKSUM_ALGO: blake2s_truncated_4bytes
 90  
 91  spec:
 92    # === CORE LIBRARY ===
 93    purpose: Central Rust library handling all cryptographic operations
 94  
 95    structure:
 96      wallet-core/:
 97        src/:
 98          - keys/           # BLS/secp/ed25519 key management, BIP39 mnemonic
 99          - address/        # Address generation and validation
100          - signing/        # Signatures (BLS, ed25519 legacy)
101          - backup/         # Encrypted backup with Argon2id KDF
102          - error/          # Error types
103          - ffi/            # UniFFI platform bindings
104        tests/: []
105        # Future modules (not yet implemented):
106        # - payment_code/   # Aleo-native payment codes
107        # - stealth/        # Stealth address generation
108        # - transaction/    # Transaction construction
109        # - recovery/       # Shamir + Social recovery
110        # - device_mesh/    # 2FA device mesh
111  
112    # === DERIVATION SPEC ===
113    derivation:
114      format: "m/47'/[BLOX]'/account'/class'/index"
115      classes:
116        0: alpha_private_addresses
117        1: delta_trading_addresses_public
118        2: delta_dx_addresses_private
119        3: reserved
120        backup: "m/47'/[BLOX]'/backup'/0'"
121      curves:
122        bls12_377: native_alpha_delta (classes 0, 1, 2)
123        secp256k1: btc_eth_trx_external
124        ed25519: sol_external
125  
126    # === PAYMENT CODE SPEC ===
127    payment_code:
128      format_bytes: 81  # 1+1+32+32+11+4=81
129      structure:
130        - version: 1_byte (0x01)
131        - features: 1_byte (bitfield)
132        - view_key: 32_bytes
133        - spend_key: 32_bytes
134        - diversifier: 11_bytes
135        - checksum: 4_bytes (blake2s)
136      encoding: bech32m
137      hrp: acdc1
138      example: "acdc1qxp72k9wd5clhm8yvqtnjfk4zqwqglz8v7qwc5r..."
139  
140    # === SWAP CODE SPEC ===
141    swap_code:
142      structure:
143        - version: 1_byte
144        - swap_id: 16_bytes
145        - maker_address: 32_bytes
146        - offer_asset_amount: variable
147        - request_asset_amount: variable
148        - expiry_timestamp: 8_bytes
149        - maker_adaptor_pubkey: 32_bytes
150        - checksum: 4_bytes
151      encoding: bech32m
152      hrp: swap1
153  
154    # === BACKUP ENCRYPTION ===
155    backup:
156      key_derivation: "seed -> m/47'/[BLOX]'/backup'/0' -> backup_key"
157      algorithm: aes_256_gcm
158      nonce: random_12_bytes_per_backup
159      aad: version + timestamp
160      storage:
161        - upload_encrypted_to_ipfs -> cid
162        - store_cid_on_delta_chain
163        - recovery: fetch_cid -> decrypt_with_seed
164  
165    # === FFI TARGETS ===
166    ffi:
167      ios: swift_via_uniffi
168      android: kotlin_via_uniffi
169      desktop: direct_rust (tauri)
170      web: wasm (wasm-bindgen)
171      cli: direct_rust
172  
173    # === TESTING ===
174    testing:
175      coverage_target: 80%
176      critical_paths_100%:
177        - key_derivation
178        - payment_code_generation_parsing
179        - transaction_signing
180        - adaptor_signatures
181        - backup_encryption_decryption
182        - recovery_flows
183  
184  changelog:
185    - version: 1.1.0
186      date: 2026-01-15
187      type: fix
188      description: "Fixed payment code byte count (81 bytes), clarified UniFFI for FFI bindings"
189      breaking: false
190  
191    - version: 1.0.0
192      date: 2026-01-14
193      type: initial
194      description: "Initial wallet-core spec from Implementation Plan v1.0"
195      breaking: false