# Architecture & Flow Diagrams

This document provides visual representations of the Solana Secure Signer architecture.

---

## 🏗️ System Architecture

```
┌───────────────────────────────────────────────────────────────────────┐
│                         USER APPLICATION LAYER                        │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │               Your Python CLI (Coldstar SOL)                 │     │
│  │  • Transaction building                                      │     │
│  │  • Network communication                                     │     │
│  │  • User interface                                            │     │
│  └───────────────┬────────────────────────────┬─────────────────┘     │
│                  │                            │                       │
│                  │                            │                       │
└──────────────────┼────────────────────────────┼───────────────────────┘
                   │                            │
                   ▼                            ▼
┌───────────────────────────────────────────────────────────────────────┐
│                      INTEGRATION LAYER                                │
│  ┌──────────────────────────┐   ┌────────────────────────────────┐   │
│  │   FFI Integration        │   │   CLI Subprocess Integration   │   │
│  │   (Fast, Direct)         │   │   (Portable, Isolated)         │   │
│  │                          │   │                                │   │
│  │  • ctypes bindings       │   │  • subprocess.run()            │   │
│  │  • Shared library        │   │  • stdin/stdout JSON           │   │
│  │  • Direct function calls │   │  • Process isolation           │   │
│  └────────────┬─────────────┘   └────────────┬───────────────────┘   │
│               │                              │                       │
└───────────────┼──────────────────────────────┼───────────────────────┘
                │                              │
                └──────────┬───────────────────┘
                           ▼
┌───────────────────────────────────────────────────────────────────────┐
│                      RUST SIGNING CORE                                │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │                    Public API                                │     │
│  │  • sign_transaction(container, passphrase, tx)              │     │
│  │  • create_encrypted_container(key, passphrase)              │     │
│  └────────────┬────────────────────────────────────────────────┘     │
│               ▼                                                       │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │                 Signing Logic (signer.rs)                    │     │
│  │  1. Derive decryption key (Argon2id)                        │     │
│  │  2. Decrypt ciphertext (AES-256-GCM)                        │     │
│  │  3. Copy to secure buffer                                   │     │
│  │  4. Sign with Ed25519                                       │     │
│  │  5. Return signature                                        │     │
│  └────────────┬────────────────────────────────────────────────┘     │
│               ▼                                                       │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │            Secure Memory (secure_memory.rs)                  │     │
│  │  • SecureBuffer: mlock/VirtualLock                          │     │
│  │  • Automatic zeroization on drop                            │     │
│  │  • Panic-safe cleanup                                       │     │
│  └─────────────────────────────────────────────────────────────┘     │
│                                                                       │
│  Dependencies: ed25519-dalek, aes-gcm, argon2, zeroize, region       │
└───────────────────────────────────────────────────────────────────────┘
```

---

## 🔄 Signing Flow (Detailed)

```
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 1: INPUT PREPARATION                                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Python Application                                                 │
│  ├─ Load encrypted container (JSON file)                           │
│  ├─ Get passphrase (user input, secure)                            │
│  └─ Prepare unsigned transaction bytes                             │
│                                                                     │
│  Status: ✅ No sensitive data yet                                   │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 2: ENTER RUST SECURE ZONE                                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  FFI Boundary / CLI Invocation                                      │
│  ├─ Serialize inputs to JSON/bytes                                 │
│  ├─ Call: sign_transaction_ffi() or subprocess                     │
│  └─ Enter Rust memory space                                        │
│                                                                     │
│  Status: ✅ Encrypted data crosses boundary                         │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 3: KEY DERIVATION                                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Argon2id Key Derivation                                           │
│  ├─ Input: passphrase + salt from container                        │
│  ├─ Compute: memory-hard hash                                      │
│  ├─ Output: 32-byte AES key                                        │
│  └─ Zeroize: passphrase copy                                       │
│                                                                     │
│  Status: ✅ Passphrase zeroized, no plaintext key yet               │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 4: MEMORY ALLOCATION & LOCKING                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  SecureKeyBuffer::new_secret_key()                                  │
│  ├─ Allocate: 32 bytes on heap                                     │
│  ├─ Lock: mlock()/VirtualLock() syscall                            │
│  ├─ Verify: lock succeeded or return error                         │
│  └─ Initialize: fill with zeros                                    │
│                                                                     │
│  Memory State:                                                      │
│  ┌────────────────────────────────────┐                            │
│  │  Locked RAM (32 bytes)             │                            │
│  │  [0, 0, 0, ..., 0]  (all zeros)    │                            │
│  │  Status: LOCKED, not swappable     │                            │
│  └────────────────────────────────────┘                            │
│                                                                     │
│  Status: ✅ Secure buffer ready, no sensitive data yet              │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 5: DECRYPTION                                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  AES-256-GCM Decryption                                             │
│  ├─ Input: ciphertext + nonce + derived key                        │
│  ├─ Decrypt: to temporary Vec<u8>                                  │
│  ├─ Verify: authentication tag                                     │
│  └─ Output: plaintext key (32 bytes)                               │
│                                                                     │
│  Temporary State:                                                   │
│  ┌────────────────────────────────────┐                            │
│  │  Stack/Heap (decrypted_bytes)      │                            │
│  │  [k₀, k₁, k₂, ..., k₃₁]            │                            │
│  │  Status: PLAINTEXT KEY! ⚠️          │                            │
│  └────────────────────────────────────┘                            │
│                                                                     │
│  Status: ⚠️ CRITICAL - Plaintext key in temporary buffer            │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 6: SECURE TRANSFER                                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Copy to Locked Buffer                                             │
│  ├─ Copy: decrypted_bytes → secure_key buffer                      │
│  ├─ Zeroize: decrypted_bytes (constant-time)                       │
│  └─ Verify: no copies remain                                       │
│                                                                     │
│  Before:                            After:                          │
│  ┌──────────────────────┐           ┌──────────────────────┐       │
│  │  Temporary Buffer    │           │  Temporary Buffer    │       │
│  │  [k₀, k₁, ..., k₃₁]  │  ───────> │  [0, 0, ..., 0]      │       │
│  │  (plaintext key)     │           │  (zeroized)          │       │
│  └──────────────────────┘           └──────────────────────┘       │
│                                                                     │
│  ┌──────────────────────┐           ┌──────────────────────┐       │
│  │  Locked Buffer       │           │  Locked Buffer       │       │
│  │  [0, 0, ..., 0]      │  ───────> │  [k₀, k₁, ..., k₃₁]  │       │
│  │  (empty)             │           │  (plaintext key)     │       │
│  └──────────────────────┘           └──────────────────────┘       │
│                                                                     │
│  Status: ✅ Key in locked memory, temporary copy zeroized           │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 7: SIGNING                                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Ed25519 Signing                                                    │
│  ├─ Create: SigningKey from locked buffer (borrow, no copy)        │
│  ├─ Sign: signature = signing_key.sign(transaction)                │
│  ├─ Output: 64-byte signature                                      │
│  └─ Note: SigningKey borrows, doesn't own the key                  │
│                                                                     │
│  Memory State:                                                      │
│  ┌────────────────────────────────────┐                            │
│  │  Locked Buffer                     │                            │
│  │  [k₀, k₁, k₂, ..., k₃₁]  ◄─────── SigningKey borrows            │
│  │  Status: LOCKED, being used        │                            │
│  └────────────────────────────────────┘                            │
│                                                                     │
│  Status: ⚠️ Key still in memory, being used for signing             │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 8: RESULT PREPARATION                                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Build Signed Transaction                                          │
│  ├─ Allocate: new Vec<u8> for result                               │
│  ├─ Append: signature (64 bytes, public data)                      │
│  ├─ Append: original transaction                                   │
│  └─ Return: SignedTransaction struct                               │
│                                                                     │
│  Status: ✅ Public signature ready, key still in locked buffer      │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 9: AUTOMATIC CLEANUP (Drop)                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  SecureKeyBuffer::drop() automatically called                       │
│  ├─ Trigger: secure_key goes out of scope                          │
│  ├─ Zeroize: data.zeroize() (constant-time)                        │
│  ├─ Unlock: munlock()/VirtualUnlock()                              │
│  └─ Extra: manual write_bytes for paranoia                         │
│                                                                     │
│  Before Drop:                       After Drop:                     │
│  ┌──────────────────────┐           ┌──────────────────────┐       │
│  │  Locked Buffer       │           │  Unlocked Memory     │       │
│  │  [k₀, k₁, ..., k₃₁]  │  ───────> │  [0, 0, ..., 0]      │       │
│  │  (plaintext key)     │           │  (zeroized)          │       │
│  │  Status: LOCKED      │           │  Status: FREE        │       │
│  └──────────────────────┘           └──────────────────────┘       │
│                                                                     │
│  Note: This happens even if signing panicked!                      │
│                                                                     │
│  Status: ✅ Key completely erased from memory                       │
└──────────────────────────┬──────────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PHASE 10: RETURN TO PYTHON                                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  FFI Boundary / CLI Output                                          │
│  ├─ Serialize: SignedTransaction to JSON                           │
│  ├─ Return: to Python via FFI or stdout                            │
│  └─ Python receives: signature + signed transaction                │
│                                                                     │
│  Data Returned to Python:                                          │
│  • signature: [s₀, s₁, ..., s₆₃] (64 bytes, public)                │
│  • signed_tx: signature + transaction (public)                     │
│                                                                     │
│  Status: ✅ Only public data crosses boundary                       │
└─────────────────────────────────────────────────────────────────────┘

SECURITY SUMMARY:
═══════════════════════════════════════════════════════════════════════
• Plaintext key existed in locked memory for phases 6-8 only
• Key was zeroized immediately after use (phase 9)
• No copies of plaintext key exist outside locked buffer
• Cleanup is guaranteed even on panic
• Only public data (signature) returned to Python
• Private key NEVER exposed to Python memory space
═══════════════════════════════════════════════════════════════════════
```

---

## 📦 Data Flow (Input → Output)

```
INPUT (Python)                    SECURE ZONE (Rust)              OUTPUT (Python)
═══════════════                   ═══════════════════             ═══════════════

┌──────────────┐                                                 ┌──────────────┐
│  Encrypted   │                                                 │   Signature  │
│  Container   │────────┐                                        │  (64 bytes)  │
│  (JSON)      │        │                                        │              │
└──────────────┘        │                                        └──────────────┘
                        │                                                 ▲
┌──────────────┐        │         ┌─────────────────────┐                │
│  Passphrase  │────────┼────────>│  Rust Signing Core  │────────────────┤
│  (string)    │        │         │                     │                │
└──────────────┘        │         │  1. Decrypt         │        ┌──────────────┐
                        │         │  2. Lock memory     │        │   Signed     │
┌──────────────┐        │         │  3. Sign            │        │  Transaction │
│  Unsigned TX │────────┘         │  4. Zeroize         │        │   (bytes)    │
│  (bytes)     │                  │  5. Return          │        └──────────────┘
└──────────────┘                  └─────────────────────┘                 ▲
                                                                           │
                                     Private key exists                    │
                                     here only! Never                      │
                                     leaves this box.                      │
                                                                           │
                                     ┌──────────────────┐                  │
                                     │  Locked Memory   │                  │
                                     │  ┌────────────┐  │                  │
                                     │  │ Private    │  │                  │
                                     │  │ Key        │  │                  │
                                     │  │ (32 bytes) │  │                  │
                                     │  └────────────┘  │                  │
                                     │  Auto-zeroized!  │                  │
                                     └──────────────────┘                  │
                                                                           │
══════════════════════════════════════════════════════════════════════════│══
                              FFI / CLI Boundary                          │
══════════════════════════════════════════════════════════════════════════╧══

Legend:
────> Data flow
═══> Security boundary
┌───┐ Data container
```

---

## 🔒 Memory Safety Guarantees

```
╔═══════════════════════════════════════════════════════════════════════╗
║                     MEMORY SAFETY GUARANTEES                          ║
╚═══════════════════════════════════════════════════════════════════════╝

Guarantee 1: MEMORY LOCKING
┌─────────────────────────────────────────────────────────────────────┐
│  RAM                                                                 │
│  ┌───────────────────────────────────┐                              │
│  │  Locked Pages (via mlock)         │  ◄── Private key here        │
│  │  Cannot be swapped to disk        │                              │
│  └───────────────────────────────────┘                              │
│                    ║                                                 │
│                    ║ BLOCKED (no swap)                               │
│                    ▼                                                 │
│  ┌───────────────────────────────────┐                              │
│  │  Disk / Swap File                 │  ◄── Key never reaches here  │
│  │  ✘ Private key CANNOT be here     │                              │
│  └───────────────────────────────────┘                              │
└─────────────────────────────────────────────────────────────────────┘

Guarantee 2: ZEROIZATION
┌─────────────────────────────────────────────────────────────────────┐
│  Before Drop:                    After Drop:                         │
│  ┌─────────────────┐             ┌─────────────────┐                │
│  │ [k₀, k₁, ..., k₃₁]│             │ [0, 0, ..., 0]  │                │
│  │  Private key     │  ────────>  │  All zeros      │                │
│  │  SENSITIVE! ⚠️    │             │  Safe ✅         │                │
│  └─────────────────┘             └─────────────────┘                │
│                                                                      │
│  Method: zeroize crate (constant-time, not optimized out)           │
└─────────────────────────────────────────────────────────────────────┘

Guarantee 3: PANIC SAFETY
┌─────────────────────────────────────────────────────────────────────┐
│  Normal Flow:          Panic Flow:                                   │
│  ┌──────────┐          ┌──────────┐                                 │
│  │  Signing │          │  Signing │                                 │
│  │  Success │          │  PANIC!  │                                 │
│  └────┬─────┘          └────┬─────┘                                 │
│       │                     │                                        │
│       ▼                     ▼                                        │
│  ┌──────────┐          ┌──────────┐                                 │
│  │  Drop    │          │  Drop    │  ◄── Drop ALWAYS runs            │
│  │  Runs    │          │  Runs    │                                 │
│  └────┬─────┘          └────┬─────┘                                 │
│       │                     │                                        │
│       ▼                     ▼                                        │
│  ┌──────────┐          ┌──────────┐                                 │
│  │ Zeroized │          │ Zeroized │  ◄── Key erased in both cases   │
│  └──────────┘          └──────────┘                                 │
└─────────────────────────────────────────────────────────────────────┘

Guarantee 4: NO COPIES
┌─────────────────────────────────────────────────────────────────────┐
│  ONLY ONE instance of plaintext key exists:                          │
│                                                                      │
│  ┌────────────────────────────────────────────────┐                 │
│  │  SecureKeyBuffer                               │                 │
│  │  ┌──────────────────────────────────┐          │                 │
│  │  │  Private Key (32 bytes)          │  ◄─────── Single instance  │
│  │  │  [k₀, k₁, k₂, ..., k₃₁]          │          │                 │
│  │  └──────────────────────────────────┘          │                 │
│  │                   ▲                             │                 │
│  │                   │ borrow (no copy)            │                 │
│  │                   │                             │                 │
│  │         ┌─────────┴──────────┐                  │                 │
│  │         │   SigningKey        │                 │                 │
│  │         │   (borrows data)    │                 │                 │
│  │         └─────────────────────┘                 │                 │
│  └────────────────────────────────────────────────┘                 │
│                                                                      │
│  All other buffers (decryption, etc.) are zeroized immediately       │
└─────────────────────────────────────────────────────────────────────┘

Guarantee 5: EPHEMERAL LIFECYCLE
┌─────────────────────────────────────────────────────────────────────┐
│  Function Scope:                                                     │
│                                                                      │
│  fn sign_transaction(...) {                                         │
│      let secure_key = SecureKeyBuffer::new();  ◄── Created          │
│      // ... decrypt into secure_key ...                             │
│      // ... use for signing ...                                     │
│      return signature;                                              │
│  } ◄── secure_key dropped here, automatic cleanup                   │
│                                                                      │
│  Key exists ONLY during function execution                          │
│  No global variables, no caching, no persistence                    │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 🎯 Integration Comparison

```
╔═══════════════════════════════════════════════════════════════════════╗
║                    INTEGRATION MODE COMPARISON                        ║
╚═══════════════════════════════════════════════════════════════════════╝

┌─────────────────────────────────────────────────────────────────────┐
│  FFI Mode (libsolana_secure_signer.so/dll/dylib)                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Python ←──(ctypes)──→ Rust Library                                 │
│                                                                      │
│  Pros:                                                               │
│  ✅ Fastest (no process overhead)                                    │
│  ✅ Direct function calls                                            │
│  ✅ Minimal latency (~0.1ms overhead)                                │
│                                                                      │
│  Cons:                                                               │
│  ⚠️ Requires compiled library for platform                           │
│  ⚠️ Shared memory space (less isolated)                              │
│                                                                      │
│  Use When:                                                           │
│  • Production deployments                                            │
│  • High transaction throughput                                       │
│  • Minimal latency required                                          │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  CLI Mode (solana-signer binary)                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Python ──(subprocess)──→ Rust Binary ──(exit)──→ All memory freed  │
│                                                                      │
│  Pros:                                                               │
│  ✅ Maximum isolation (separate process)                             │
│  ✅ Platform-agnostic (just needs binary)                            │
│  ✅ Automatic cleanup (process exit)                                 │
│  ✅ No FFI complexity                                                │
│                                                                      │
│  Cons:                                                               │
│  ⚠️ Slower (process startup ~10-50ms)                                │
│  ⚠️ IPC overhead (JSON serialization)                                │
│                                                                      │
│  Use When:                                                           │
│  • Development/testing                                               │
│  • Maximum security isolation                                        │
│  • Cross-platform portability                                        │
│  • Occasional signing (not high frequency)                           │
└─────────────────────────────────────────────────────────────────────┘

Performance Comparison:
┌────────────────┬──────────┬───────────┬──────────────┐
│  Operation     │   FFI    │    CLI    │  Difference  │
├────────────────┼──────────┼───────────┼──────────────┤
│  Overhead      │  ~0.1ms  │  ~10-50ms │  100-500x    │
│  Throughput    │  High    │  Low      │  -           │
│  Memory Safety │  Good    │  Excellent│  CLI better  │
│  Portability   │  Medium  │  High     │  CLI better  │
└────────────────┴──────────┴───────────┴──────────────┘
```

This completes the visual documentation! 🎉