# Umbra Private Payments

## What is this?

Umbra is an EVM compatible private UTXO-based payment system that uses zero-knowledge proofs to enable confidential transactions.

Users derive cryptographic keypairs from their MetaMask wallet signatures (keys never leave the browser), and all transaction amounts, sender identities, and recipient identities are hidden from on-chain observers.

When a user sends funds, they construct a transaction witness containing their input UTXOs (represented as Blake3 hash commitments), generate ECDSA signatures to derive deterministic nullifiers (which prevent double-spending without revealing which note is being spent), and encrypt the output note data using ECIES so only the intended recipient can decrypt it.

This witness is sent to an SP1 zkVM prover that generates a Groth16 proof verifying:

1. The input notes exist in the on-chain Merkle tree,
2. the sender owns the notes (via signature verification),
3. value is conserved (inputs >= outputs), and;
4. nullifiers are correctly derived. The proof is then submitted to the smart contract which cryptographically verifies it, marks the nullifiers as spent, inserts new commitments into the Merkle tree, and emits encrypted output events that only recipients can scan and decrypt to discover payments sent to them.

- [TECHNICAL DOCS](https://hackmd.io/TjCvJug0QfWyqfSNDVdVmQ)
- [GITHUB](https://github.com/hrook1/Umbra)

---

## Getting Started

### 1. Access the Wallet

*(Request access if prompted)*

### 2. Get Sepolia ETH

Visit Google's faucet to get free test ETH:
**https://cloud.google.com/application/web3/faucet/ethereum/sepolia**

- Enter your wallet address
- Request ETH (needed once for USDC approval)

### 3. Get Sepolia USDC

Visit Circle's faucet to get free test USDC:
**https://faucet.circle.com/**

- Connect your wallet
- Select "Sepolia" network
- Request USDC (you'll get 1 USDC, so dont spend it all at once!)

### 4. Connect Wallet

- Click "Connect Wallet"
- Switch to **Sepolia** network if prompted
- Generate private credentials

---

## Core Actions

### Deposit USDC

1. Click **"Deposit"**
2. Enter amount (e.g., 0.01 USDC)
3. First time: Approve USDC spending (one-time)
4. Sign the Permit2 message (gasless approval)
5. Wait for confirmation
6. Your private balance updates

### Send Private Payment

1. Click **"Send"**
2. Enter recipient's **private address** (starts with `0x...`).
2.1. Heres my private address if you need a fren to share $ `0x03855c29051a934ef7c15ce4750dce8f0c9997c8a5b12711cf796ed83af6194ee4`
3. Enter amount
4. Click "Send"
5. Wait for ZK proof generation (~1-2 minutes)
6. Transaction submitted automatically
7. Recipient sees funds in their private balance

*Requires ZK proof - amounts are hidden on-chain*

### Withdraw to Public Wallet

1. Click **"Withdraw"**
2. Enter your public ETH address
3. Enter amount
4. Wait for ZK proof generation (~1-2 minutes)
5. USDC sent to your public wallet

*Requires ZK proof - proves you own the funds without revealing balance*

---

## Understanding Your Wallet

| Term | Meaning |
|------|---------|
| **Private Balance** | Your encrypted USDC balance (only you can see) |
| **Private Address** | Address others use to send you private payments |
| **Public Address** | Your regular ETH address (for withdrawals) |

---

## How Privacy Works

- **Deposits**: USDC goes into a shared pool
- **Balances**: Stored as encrypted "notes" on-chain
- **Transfers**: ZK proofs verify validity without revealing amounts
- **Withdrawals**: Prove ownership, receive USDC publicly

Your activity is unlinkable - observers can't connect deposits to withdrawals.

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Prover offline" | Wait 1-2 min for server to wake up, retry |
| Proof taking long | Normal - ZK proofs take 1-2 minutes |
| Transaction failed | Check you have sufficient private balance |
| Wrong network | Switch MetaMask to Sepolia |