# coldstar-privacy

Privacy transaction layer for the Coldstar cold wallet, ported from devsyrem's Python privacy module.

## Components

### Mode Selector (`mode`)

State machine for explicit transaction mode selection (public/private). Mode must be chosen before signing and is locked after proof generation.

State transitions:

```
UNSELECTED -> SELECTED -> LOCKED
(Any state) -> REJECTED (terminal)
```

### Signing Policy Engine (`policy`)

Evaluates transfer envelopes against configurable policy rules:

- **Mode validity** - mode is recognized
- **Envelope structure** - sender, recipient, and amount are present
- **Amount limits** - transfer does not exceed configured maximum
- **Destination allowlist** - recipient is on the approved list (if enforced)
- **Replay protection** - nonce has not been seen before
- **Proof completeness** - (private mode) ownership proof, range proof, policy proofs
- **Proof binding** - (private mode) binding hash is present

### Privacy Validator (`validator`)

Top-level orchestrator that chains the full validation pipeline:

1. Mode selection (explicit, locked)
2. Proof bundle verification (private mode)
3. Envelope construction
4. Policy evaluation
5. Final sign/reject decision

### Confidential Transfer Manager (`confidential`)

CLI wrapper around the `spl-token` binary for SPL Token-2022 confidential transfers:

- Create Token-2022 mints with confidential transfer extension
- Configure token accounts for confidential transfers
- Deposit tokens to confidential balance (public -> encrypted)
- Transfer tokens confidentially (amount hidden on-chain)
- Apply pending balance / withdraw from confidential balance

## Usage

```rust
use coldstar_privacy::{PrivacyValidator, ConfidentialTransferManager};

// Validation pipeline
let mut validator = PrivacyValidator::default();
validator.select_mode("public").unwrap();
let result = validator.validate_transaction(&tx_context, None);
if result.approved {
    // proceed to signing
}

// Confidential transfers (requires spl-token CLI)
let manager = ConfidentialTransferManager::new(None, None, None).unwrap();
let prereqs = manager.check_prerequisites();
```

## Security

- Mode must be explicitly selected, never defaulted
- Mode switching after proof generation is forbidden
- Replay protection via nonce tracking
- All policy checks must pass for signing approval
- Confidential transfer amounts are ElGamal-encrypted on-chain
