# Umbra: Private UTXO Payment System

## Technical Overview

### Table of Contents
1. [Architecture Overview](#architecture-overview)
2. [System Components](#system-components)
3. [Privacy Model](#privacy-model)
4. [Cryptographic Primitives](#cryptographic-primitives)
5. [Zero-Knowledge Proofs](#zero-knowledge-proofs)
6. [Encrypted Storage](#encrypted-storage)
7. [Security Model](#security-model)

---

## Architecture Overview

Umbra is a privacy-preserving payment system built on Ethereum (Sepolia) using a UTXO model with zero-knowledge proofs. It enables private transfers of USDC where transaction amounts and relationships between sender/receiver are hidden from observers.

### High-Level Architecture

                    ┌──────────────────────────────────────────────────────────┐
                    │              ETHEREUM (Sepolia) - Source of Truth        │
                    │  ┌────────────────────────────────────────────────────┐  │
                    │  │            PrivateUTXOLedger Contract              │  │
                    │  │  - SP1 Groth16 Verifier (on-chain proof verify)    │  │
                    │  │  - UTXO Merkle Tree State                          │  │
                    │  │  - Nullifier Registry (double-spend prevention)    │  │
                    │  │  - USDC Custody                                    │  │
                    │  └────────────────────────────────────────────────────┘  │
                    │  ┌─────────────────────┐  ┌────────────────────────────┐ │
                    │  │EncryptedContacts    │  │PrivatePaymentRequests      │ │
                    │  │- Tag-based lookup   │  │- Encrypted payment reqs    │ │
                    │  │- ECIES encryption   │  │- Tag-based recipient IDs   │ │
                    │  └─────────────────────┘  └────────────────────────────┘ │
                    └──────────────────────────────────────────────────────────┘
                                              ▲
                                              │ Submit proven transactions
                                              │ (Gasless via Account Abstraction)
                    ┌─────────────────────────┴─────────────────────────────┐
                    │                                                       │
                    ▼                                                       │
          ┌──────────────────┐                                              │
          │  Relayer Server  │                                              │
          │  - Alchemy Smart │                                              │
          │    Account (AA)  │                                              │
          │  - Gas Sponsored │                                              │
          │                  │                                              │
          └──────────────────┘                                              │
                    ▲                                                       │
                    │ Proof + encrypted notes                               │
                    │                                                       │
┌─────────────────────────────────────────────────────────────────┐         │
│                         Wallet UI (Next.js)                     │         │
│  - Key derivation from MetaMask signature                       │─────────┘
│  - UTXO scanning and decryption (client-side)                   │  Read state
│  - Transaction construction                                     │  (events, roots)
│  - Dual signature model (NullifierSig + TxSig)                  │
│  - All cryptography happens client-side                         │
└─────────────────────────────────────────────────────────────────┘
                    │
                    │ Witness data (notes, signatures, indices)
                    ▼
          ┌──────────────────┐
          │  Prover Server   │
          │  - Express.js    │
          │  - Spawns Rust   │
          │    prover-host   │
          └──────────────────┘
                    │
                    │ Proof request via SP1 SDK
                    ▼
          ┌──────────────────┐
          │ Succinct Prover  │
          │ Network          │
          │ - zkVM Execution │
          │ - Groth16 Proof  │
          │ (~30-60 seconds) │
          └──────────────────┘

### Data Flow

1. **Login**: User signs a fixed message with MetaMask → signature hashed → secp256k1 keypair derived
2. **Scan**: Wallet reads `OutputCommitted` events from contract, attempts ECIES decryption with private key
3. **Send**: User constructs transaction, signs commitments (NullifierSig + TxSig), sends witness to Prover Server
4. **Prove**: Prover Server precomputes values, submits to Succinct Network for Groth16 proof generation
5. **Submit**: Wallet receives proof, sends to Relayer (gasless)
6. **Verify**: Contract verifies SP1 proof on-chain, checks nullifiers unused, updates Merkle state

---

## System Components

| Component | Role | Trust Level |
|-----------|------|-------------|
| **PrivateUTXOLedger** | On-chain source of truth. Verifies SP1 proofs, manages UTXO state, prevents double-spends | Trustless (code is law) |
| **EncryptedContacts** | On-chain encrypted address book storage | Trustless (encryption is client-side) |
| **PaymentRequests** | On-chain encrypted payment request storage | Trustless (encryption is client-side) |
| **Wallet UI** | All client-side cryptography: key derivation, UTXO scanning, encryption, signing | Self-custody (keys never leave browser) |
| **Prover Server** | Orchestrates proof generation via Succinct Network | Not trusted - proofs verified on-chain |
| **Relayer** | Submits transactions via Alchemy Smart Account, pays gas | Cannot steal funds or modify proofs |
| **Succinct Network** | Generates Groth16 proofs from SP1 zkVM execution | Not trusted - proofs verified on-chain |

### Contract Addresses (Sepolia)

| Contract | Address |
|----------|---------|
| PrivateUTXOLedger | `0x42ae920DFD0d25Ac014DFd751bd2ff2D2fBa0443` |
| EncryptedContacts | `0x813e453D13dE769922aFc40780FADeF3AC6d939D` |
| PaymentRequests | `0x3c4d73f028d99eC10eB15fED99AC5080C99A4a4d` |

---

## Privacy Model

### What's Hidden vs. Public

| Data | On-Chain Visibility | Who Can Decrypt |
|------|---------------------|-----------------|
| Note commitment | Public | No one (hash) |
| Encrypted note data | Public (in events) | Only recipient |
| Nullifier | Public (when spent) | No one (hash of signature) |
| Transaction amount | Hidden | Sender & Recipient |
| Sender identity | Hidden | Recipient only (via contact name in note) |
| Recipient identity | Hidden | Sender only |
| Contacts | Encrypted on-chain | Only owner |
| Payment requests | Encrypted on-chain | Only recipient |

### Key Privacy Properties

- **Amount Privacy**: Transaction values are never revealed on-chain
- **Sender Privacy**: Cannot determine who sent a payment from on-chain data
- **Recipient Privacy**: Cannot determine who received a payment
- **Unlinkability**: Cannot link inputs to outputs in a transaction (nullifiers hide source notes)

---

## Cryptographic Primitives

### Key Derivation

Users derive a deterministic keypair from their Ethereum wallet signature:

User signs fixed message → SHA-256(domain + signature) → secp256k1 Private Key → Public Key

const domain = 'utxo-prototype-v1-key-derivation:'
const privateKey = sha256(domain + signature)
const publicKey = secp256k1.getPublicKey(privateKey, true) // compressed
const address = '0x' + hex(publicKey) // "Private Address"

- Keys exist only in browser memory - never transmitted
- Same MetaMask signature always produces same keypair (deterministic)

### Note Structure

A note represents a private UTXO:

Note {
    amount: u64,              // Value in USDC micro-units (6 decimals)
    owner_pubkey: [u8; 32],   // Recipient's X-coordinate (from compressed pubkey)
    blinding: [u8; 32]        // Random factor for commitment uniqueness
}

### Note Commitment

Domain-separated Blake3 hash ensuring collision resistance:

Commitment = Blake3(DOMAIN_NOTE_COMMITMENT || amount_le(8) || owner_pubkey(32) || blinding(32))

Where:
- `DOMAIN_NOTE_COMMITMENT = b"NOTE_COMMITMENT_v1"`
- `amount_le` = 8-byte little-endian encoding
- Commitment is stored on-chain in Merkle tree
- Blinding factor ensures two notes with same amount/owner have different commitments

### Nullifier Construction

Prevents double-spending while hiding which note is being spent:

Nullifier = Blake3(DOMAIN_NULLIFIER || NullifierSignature)

Where:
- `DOMAIN_NULLIFIER = b"NULLIFIER_v1"`
- `NullifierSignature` = ECDSA signature over `ethSignedMessage(keccak256(commitment))`

**Security Properties:**
- Only the owner can compute the nullifier (requires private key to sign)
- Cannot be computed from commitment alone
- Published on-chain when note is spent → prevents double-spend
- Deterministic: same note + same key always produces same nullifier

### Dual Signature Model

Each input note requires TWO signatures for security:

1. **NullifierSig**: Used to derive the nullifier (privacy)
- Signs: `keccak256(commitment)` with Ethereum prefix
- Purpose: Deterministic nullifier derivation

2. **TxSig**: Proves ownership for the ZK circuit (anti-theft)
- Signs: `keccak256(commitment)` with Ethereum prefix
- Purpose: Recovered pubkey must match note's `owner_pubkey`

Both signatures use the same message but serve different purposes in the security model.

### ECIES Encryption (Notes)

Notes are encrypted to the recipient's public key using ECIES:

1. Generate ephemeral keypair (r, R = r*G)
2. Compute shared secret: S = ECDH(r, recipient_pubkey)
3. Derive AES key: K = HKDF-SHA256(S, info="utxo-prototype-v1-encryption")
4. Encrypt: AES-256-GCM(K, nonce, plaintext)
5. Output: (R || nonce || ciphertext)

- Ephemeral pubkey (R) is stored on-chain in `OutputCommitted` events
- Only recipient can decrypt using their private key
- Forward secrecy via ephemeral keys

### ECIES Encryption (Contacts & Payment Requests)

Contacts and payment requests use a similar ECIES scheme:

1. Generate ephemeral keypair
2. ECDH shared secret with owner/recipient pubkey
3. HKDF-SHA256 key derivation (domain: "utxo-contacts-v1" or "utxo-requests-v1")
4. AES-256-GCM encryption
5. Store: ephemeralPub(33) || nonce(12) || ciphertext

---

## Zero-Knowledge Proofs

### SP1 zkVM

We use Succinct's SP1 zkVM which allows writing ZK circuits in Rust. The circuit is compiled to a RISC-V ELF binary and executed in a zkVM that generates Groth16 proofs verifiable on Ethereum.

### Optimized Proving Path

The system uses an **optimized path** where expensive ECDSA operations are performed on the host (prover server) rather than inside the zkVM:

Host (Rust):
  - Verify signatures via k256 library
  - Compute nullifiers from signatures
  - Compute commitments from note data
  - Pass precomputed values to zkVM

zkVM (SP1):
  - Verify precomputed commitments match note data (Blake3)
  - Use precomputed nullifiers (no ECDSA in circuit)
  - Verify value conservation
  - Output ABI-encoded public values

This reduces proving time by 40-60% compared to in-circuit ECDSA.

### What the Circuit Proves

| Statement | What It Proves | Why It Matters |
|-----------|----------------|----------------|
| Commitment Validity | Input commitments match `Hash(note)` | Cannot spend notes that don't exist |
| Nullifier Correctness | Nullifiers derived from valid signatures | Deterministic spend tracking |
| Output Validity | Output commitments properly formed | New notes are correctly structured |
| Value Conservation | `sum(inputs) >= sum(outputs)` | Cannot create money from nothing |

### Circuit Logic (Simplified)

// VERIFY precomputed values match note data
for (note, precomputed_commitment) in inputs {
    assert!(commit(note) == precomputed_commitment);
}

// VERIFY value conservation
assert!(sum(input_amounts) >= sum(output_amounts));

// OUTPUT (public, ABI-encoded):
//   - old_root (contract verifies this matches current state)
//   - new_root (new Merkle root after adding outputs)
//   - nullifiers (marks inputs as spent)
//   - output_commitments (new notes added to tree)

### Security Note

The standard path (in-circuit ECDSA) is **disabled** for security. The system requires precomputed values where:
- Host verifies signatures before proving
- zkVM verifies precomputed values via hash matching
- Contract verifies the proof and checks nullifiers haven't been used

---

## Encrypted Storage

### EncryptedContacts Contract

Stores encrypted address book entries on-chain:

mapping(bytes8 => uint256[]) public contactsByOwner;  // ownerTag => contactIds
mapping(uint256 => Contact) public contacts;

struct Contact {
    bytes8 ownerTag;      // First 8 bytes of keccak256(owner_pubkey)
    bytes encryptedData;  // ECIES-encrypted contact data
    uint256 timestamp;
}

**Owner Tag Computation:**

ownerTag = keccak256(publicKeyHex).slice(0, 8)  // First 8 bytes

### PaymentRequests Contract

Stores encrypted payment requests:

mapping(bytes8 => uint256[]) public requestsByRecipient;  // recipientTag => requestIds
mapping(uint256 => Request) public requests;

struct Request {
    bytes8 recipientTag;
    bytes encryptedPayload;  // ECIES-encrypted: {requesterName, requesterAddress, amount, reference, message}
    uint256 timestamp;
    RequestStatus status;    // Pending, Approved, Rejected, Expired
}

---

## Security Model

### Threat Model

| Threat | Mitigation |
|--------|------------|
| Double-spend | Nullifier registry on-chain - each nullifier used once |
| Forged ownership | ECDSA signature verification (host + zkVM hash check) |
| Invalid amounts | Value conservation check in ZK circuit |
| Malicious prover | All proofs verified on-chain by SP1 Verifier |
| Front-running | Nullifiers hide which specific note is being spent |
| Key theft | Keys derived from wallet signature, exist only in browser |
| Replay attacks | Nullifiers are one-time use, nonces in Permit2 |
| Proof-binding bypass | Contract decodes outputs from `publicValues` (not separate params) |

### Trust Assumptions

| Component | Security Trust | Liveness Trust |
|-----------|----------------|----------------|
| Smart Contract | Full (verified on-chain) | Ethereum availability |
| Succinct Network | None (proofs verified on-chain) | Required for proof generation |
| Relayer | None (cannot modify proofs) | Required for gasless tx submission |
| Wallet UI | Self-custody | User's device |

### Cryptographic Assumptions

- **secp256k1 ECDSA**: Discrete log hardness
- **Blake3**: Collision resistance, preimage resistance
- **Groth16**: Knowledge-of-exponent assumption, q-PKE
- **AES-256-GCM**: Standard symmetric encryption security
- **HKDF-SHA256**: PRF security of HMAC-SHA256

### Key Security Properties

- **Soundness**: Cannot create valid proof without knowing private keys
- **Zero-Knowledge**: Proof reveals nothing about transaction details
- **Unlinkability**: Cannot link sender to recipient from on-chain data
- **Non-Malleability**: Proofs cannot be modified without invalidation

---

## Gasless Transactions

All user-facing transactions are gasless via Alchemy Account Abstraction:

### Relayer Architecture

// Alchemy Smart Account with Gas Policy
const smartAccountClient = await createLightAccountAlchemyClient({
    chain: sepolia,
    signer: LocalAccountSigner.privateKeyToAccountSigner(RELAYER_PRIVATE_KEY),
    policyId: GAS_POLICY_ID,  // Alchemy gas sponsorship
});

### Supported Gasless Operations

| Endpoint | Operation |
|----------|-----------|
| `/api/deposit-with-permit` | Deposit USDC (Permit2 signature) |
| `/api/submit-tx` | Private transfer (proof required) |
| `/api/withdraw` | Withdraw to public address (proof required) |
| `/api/save-contact` | Save encrypted contact |
| `/api/create-payment-request` | Create encrypted payment request |

---

## References

- [SP1 Documentation](https://docs.succinct.xyz/)
- [Groth16 Paper](https://eprint.iacr.org/2016/260)
- [ECIES Specification](https://cryptopp.com/wiki/Elliptic_Curve_Integrated_Encryption_Scheme)
- [Blake3 Specification](https://github.com/BLAKE3-team/BLAKE3-specs)
- [Alchemy Account Kit](https://accountkit.alchemy.com/)
- [Permit2](https://github.com/Uniswap/permit2)