# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Common Development Commands
### Build and Test
```bash
# Build the library and CLI
cargo build --release
# Run all tests (unit + integration)
cargo test
# Run only unit tests
cargo test --test unit_tests
# Run only integration tests (requires TEST_WEBCASH_SECRET env var)
export TEST_WEBCASH_SECRET="e0.0001:secret:..."
cargo test --test integration_tests
# Format code
cargo fmt
# Lint and check code
cargo clippy
# Generate C bindings (if c_bindings feature enabled)
cargo build --features c_bindings
# Run specific test
cargo test test_name
# Run tests with output
cargo test -- --nocapture
# Run benchmarks
cargo bench
# Test biometric encryption (platform-specific)
cargo test biometric
```
### CLI Usage
The binary `webyc` (built from `src/bin/cli.rs`) provides the command-line interface:
```bash
# Setup new wallet (auto-generates master secret with hardware RNG)
./target/release/webyc setup [--biometric]
# Setup wallet with explicit master secret
./target/release/webyc setup -p <master_secret>
# Show wallet information
./target/release/webyc info
# Insert webcash
./target/release/webyc insert [webcash_string] [--offline]
# Generate payment
./target/release/webyc pay 0.00001 [-m memo]
# Check wallet against server
./target/release/webyc check
# Recover wallet from stored master secret
./target/release/webyc recover [--gap-limit 20]
# Merge small outputs
./target/release/webyc merge [--group 20] [--max 50000000]
# Encrypt wallet with biometrics (Face ID/Touch ID)
./target/release/webyc encrypt -o wallet_backup.enc
# Encrypt wallet with password
./target/release/webyc encrypt -o wallet_backup.enc --password
# Decrypt wallet with biometrics
./target/release/webyc decrypt -i wallet_backup.enc
# Decrypt wallet with password
./target/release/webyc decrypt -i wallet_backup.enc --password
```
## High-Level Architecture
### Core Library Structure (`src/`)
**Data Types & Primitives:**
- `amount.rs` - Fixed-point decimal amounts with 8-decimal precision
- `webcash.rs` - SecretWebcash and PublicWebcash types with secure string handling
- `error.rs` - Comprehensive error types for all library operations
- `crypto.rs` - SHA256 hashing, secure random generation, and CryptoSecret with hardware RNG
- `biometric.rs` - State-of-the-art biometric encryption (Face ID/Touch ID/Biometric API)
**Wallet System:**
- `wallet.rs` - Main Wallet struct providing all wallet operations (insert, pay, balance, etc.)
- `hd.rs` - Hierarchical Deterministic wallet with BIP32-style key derivation
- Chain codes: Receive(0), Pay(1), Change(2), Mining(3)
**Server Communication:**
- `server.rs` - HTTP client for Webcash server API with endpoints:
- `/api/v1/health_check` - Verify webcash status
- `/api/v1/replace` - Exchange webcash
- `/api/v1/target` - Get mining difficulty
- `/api/v1/mining_report` - Submit mining results
- `server/` directory contains platform-specific implementations
**Storage:**
- SQLite database for wallet state with encrypted master secrets
- Webcash entries tracked with spent/unspent status
- HD wallet derivation state maintained
- Biometric encryption for secure wallet backups and synchronization
### Key Patterns
**Error Handling:**
- All operations return `Result<T, Error>` where Error is the library's error type
- Async operations throughout for server communication and database I/O
**Security:**
- Sensitive data uses `SecureString` with zeroize-on-drop
- Master secrets auto-generated using platform hardware RNG (getrandom)
- CryptoSecret type with automatic memory zeroing
- Biometric encryption using hardware security modules (iOS Keychain/Android Keystore)
- AES-256-GCM encryption with HKDF-SHA256 key derivation
- Input validation on all user-provided data
**HD Wallet Flow:**
1. Master secret (32 bytes) generates HD wallet
2. Chain codes determine key purpose (receive, pay, change, mining)
3. Index increments for each new key derivation
4. Recovery scans chains up to gap limit to find used keys
### Testing Structure
**Unit Tests:** Decoupled from source code in `tests/unit_tests.rs` and `tests/unit/` directory:
- `tests/unit/amount.rs` - Amount parsing, arithmetic, and validation tests
- `tests/unit/crypto.rs` - SHA256 hashing and secure random generation tests
- `tests/unit/error.rs` - Error creation and display tests
- `tests/unit/hd.rs` - HD wallet key derivation and deterministic tests
- `tests/unit/lib.rs` - Library-level functionality tests (ChainCode, etc.)
- `tests/unit/server.rs` - Server client and API structure tests
- `tests/unit/server_ios.rs` - iOS-specific server implementation tests (platform-specific)
- `tests/unit/wallet.rs` - Wallet creation and basic operation tests
- `tests/unit/webcash.rs` - Webcash parsing and conversion tests
Run unit tests with: `cargo test --test unit_tests`
**Integration Tests:** `tests/integration_tests.rs` provides comprehensive workflows:
- Full wallet operations with real server communication
- Cross-wallet HD recovery scenarios
- Offline wallet operations
- Server API endpoint testing
**Test Environment:**
- Set `TEST_WEBCASH_SECRET` environment variable for integration tests
- Tests clean up temporary wallet files automatically
- Extensive logging shows test progress and results
- Unit tests are completely separate from source code for better maintainability
- All tests have been sanitized and extracted from source files for clean separation
### Important Implementation Notes
**Amount Handling:**
- All amounts use 8-decimal fixed-point arithmetic
- String parsing/formatting handles decimal precision correctly
- Overflow protection in arithmetic operations
**Webcash Format:**
- SecretWebcash: `e<amount>:<type>:<value>` (e.g., "e1.00000000:secret:abcdef...")
- PublicWebcash: SHA256 hash of the secret webcash
- Validation ensures proper format and cryptographic correctness
**Server Integration:**
- Webcash validation requires server communication unless explicitly bypassed
- Health check verifies webcash hasn't been spent
- Replace operation exchanges old webcash for new webcash
- Error handling distinguishes network vs. protocol errors
**HD Recovery Process:**
- Scans receive/pay/change/mining chains up to gap limit
- Finds all previously used addresses by checking server
- Reconstructs wallet state from blockchain/server data
- Gap limit prevents excessive scanning while ensuring completeness