TaprootFreak · May 10, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop, main]
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint-and-build:
+    name: Lint & Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust 1.81.0
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: "1.81.0"
+          components: rustfmt, clippy
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Check formatting
+        run: cargo fmt --all --check
+
+      - name: Run clippy (server + shared)
+        run: cargo clippy -p server -p shared -- -D warnings
+
+      - name: Run clippy (program lib)
+        run: cargo clippy -p zkcoins-program --lib -- -D warnings
+
+      - name: Build server
+        run: cargo build -p server
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Rust 1.81.0
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: "1.81.0"
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Run tests (server + shared, skip slow SP1 prover tests)
+        run: cargo test -p server -p shared -- --skip account_server::tests
+
+      - name: Run tests (program lib)
+        run: cargo test -p zkcoins-program --lib
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,7 +8,7 @@ This guide covers everything you need to develop, test, and deploy the zkCoins b
 git clone https://github.com/zk-coins/server.git
 cd server
 SP1_PROVER=mock cargo run -p server
-# Server starts on http://127.0.0.1:4242
+# Server starts on http://0.0.0.0:4242
 ```
 
 ## Prerequisites
@@ -169,10 +169,11 @@ The `zkvm` feature gates the SP1 entrypoint and all `sp1_zkvm::` calls.
 
 | Variable | Default | Description |
 |---|---|---|
-| `SP1_PROVER` | `mock` | `mock` (stub proofs) or `local` (real SP1) |
-| `ESPLORA_URL` | `https://mutinynet.com/api` | Bitcoin node API |
-| `BITCOIN_RPC_USER` | — | Bitcoin Core RPC username |
-| `BITCOIN_RPC_PASSWORD` | — | Bitcoin Core RPC password |
+| `SP1_PROVER` | `mock` | `mock` (no proof), `cpu`, `cuda`, or `network` |
+| `ESPLORA_URL` | `https://mutinynet.com/api` | Esplora API endpoint (electrs or public) |
+| `IS_MAINNET` | `false` | `true` for Bitcoin Mainnet, `false` for Mutinynet/Signet |
+| `NETWORK_NAME` | `Mutinynet` | Human-readable network name (returned by `/api/info`) |
+| `PUBLISHER_KEY` | test key | 32-byte hex private key for inscription publishing. **Required on mainnet** |
 | `RUST_LOG` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
 
 ## Docker
@@ -182,15 +183,15 @@ docker build -t zkcoin/server .
 docker run -p 4242:4242 \
   --network bitcoin \
   -e SP1_PROVER=mock \
-  -e ESPLORA_URL=http://bitcoind-mainnet:8332 \
+  -e ESPLORA_URL=http://electrs-mainnet:3000 \
   zkcoin/server
 ```
 
-The Dockerfile removes the `script` crate from the workspace (via `sed`) to avoid requiring the SP1 toolchain. The stub prover in `script/src/lib.rs` provides the same API surface with mock proofs.
+The pre-built ELF (`elf/zkcoins-program`) is committed to the repo, so Docker builds do not require the Succinct toolchain — only standard Rust.
 
 ### Bitcoin Node
 
-The server needs a Bitcoin node. In production, it connects via the shared Docker network `bitcoin` to `bitcoind-mainnet:8332`. Requirements:
+The server needs a Bitcoin node with an Esplora-compatible indexer (electrs). In production, it connects via the shared Docker network `bitcoin` to `electrs-mainnet:3000` (DEV: `electrs-mutinynet:3000`). The underlying bitcoind requires:
 - `txindex=1`
 - `rest=1`
 - `server=1`
@@ -207,15 +208,6 @@ See [docs.zkcoins.app/infrastructure/backend](https://docs.zkcoins.app/infrastru
 
 Build time is ~5 minutes (Rust compilation on ARM64).
 
-## API Reference
-
-| Endpoint | Method | Description | Success |
-|---|---|---|---|
-| `/api/mint` | POST | Mint coins from minting account | `{ proof_id }` |
-| `/api/send` | POST | Transfer coins between accounts | `{ proof_id }` |
-| `/api/balance?address=<hex>` | GET | Query account balance | `{ balance }` |
-| `/api/proof/:id` | GET | Download coin proof (binary) | Binary data |
-
 ## Related Repos
 
 - [zk-coins/app](https://github.com/zk-coins/app) — Web application (frontend)

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ Rust/Axum backend for [zkcoins.app](https://zkcoins.app) — account management,
 | ZK Proofs | SP1 zkVM | Write proofs in standard Rust, no DSL |
 | Data structures | SMT + MMR | Non-inclusion proofs + append-only history |
 | Bitcoin | Taproot Inscriptions | 64-byte nullifiers, Esplora API scanning |
-| Bitcoin node | bitcoind-mainnet | Shared Docker network `bitcoin`, port 8332 |
+| Bitcoin index | electrs (Esplora) | Esplora REST API via shared Docker network `bitcoin` |
 
 Full rationale: [docs.zkcoins.app/tech-decisions](https://docs.zkcoins.app/tech-decisions)
 
@@ -36,11 +36,25 @@ SP1_PROVER=mock cargo run -p server
 | Endpoint | Method | Description | Response |
 |---|---|---|---|
 | `/health` | GET | Health check | `ok` (200) |
-| `/api/mint` | POST | Mint coins (faucet) | `{ proof_id }` |
-| `/api/send` | POST | Transfer coins | `{ proof_id }` |
+| `/api/info` | GET | Network info | `{ network }` |
+| `/api/mint` | POST | Mint coins (faucet) | `{ success, proof_id }` |
+| `/api/send` | POST | Transfer coins (phase 1) | `{ success, proof_id, account_state_hash, output_coins_root }` |
+| `/api/commit` | POST | Submit signed commitment (phase 2) | `{ success, proof_id }` |
 | `/api/balance?address=<hex>` | GET | Query balance | `{ balance }` |
+| `/api/address` | GET | List all addresses | `{ addresses }` |
+| `/api/receive` | POST | Receive coins from sender | `{ success }` |
 | `/api/proof/:id` | GET | Download coin proof | Binary |
 
+### Two-Phase Send Flow
+
+User sends require a two-phase flow because the server doesn't hold sender private keys:
+
+1. **`POST /api/send`** — server generates ZK proof, returns `proof_id` + `account_state_hash` + `output_coins_root`
+2. **Client signs commitment** — `Schnorr(hash_concat(account_state_hash, output_coins_root))` with BIP-32 key at `numPubkeys`
+3. **`POST /api/commit`** — server verifies commitment, broadcasts Taproot inscription, delivers coin to recipient via `receive_coin`
+
+Mint uses a single-phase flow (server holds the minting account key).
+
 ## Project Structure
 
 ```
@@ -54,7 +68,7 @@ server/                # Axum REST API
 │   └── publisher.rs   # Taproot Inscription broadcaster (commit/reveal)
 shared/                # Shared types (Commitment, Invoice, ClientAccount)
 program/               # SP1 zkVM circuit types (AccountState, Coin, ProofData)
-│   └── src/merkle/    # SMT + MMR implementations
+├── src/merkle/        # SMT + MMR implementations
 script/                # Prover (real SP1 zkVM — create_account, update_account)
 ```
 
@@ -63,9 +77,10 @@ script/                # Prover (real SP1 zkVM — create_account, update_accoun
 | Variable | Default | Description |
 |---|---|---|
 | `SP1_PROVER` | `mock` | `mock` (no proof), `cpu`, `cuda`, or `network` |
-| `ESPLORA_URL` | `https://mutinynet.com/api` | Bitcoin node API |
-| `BITCOIN_RPC_USER` | — | Bitcoin Core RPC username |
-| `BITCOIN_RPC_PASSWORD` | — | Bitcoin Core RPC password |
+| `ESPLORA_URL` | `https://mutinynet.com/api` | Esplora API endpoint (electrs or public) |
+| `IS_MAINNET` | `false` | `true` for Bitcoin Mainnet, `false` for Mutinynet/Signet |
+| `NETWORK_NAME` | `Mutinynet` | Human-readable network name (returned by `/api/info`) |
+| `PUBLISHER_KEY` | test key | 32-byte hex private key for inscription publishing. **Required on mainnet** — server panics if default test key is used |
 | `RUST_LOG` | `info` | Log level |
 
 ## Docker
@@ -75,7 +90,7 @@ docker build -t zkcoin/server .
 docker run -p 4242:4242 \
   --network bitcoin \
   -e SP1_PROVER=mock \
-  -e ESPLORA_URL=http://bitcoind-mainnet:8332 \
+  -e ESPLORA_URL=http://electrs-mainnet:3000 \
   zkcoin/server
 ```
 
@@ -97,19 +112,17 @@ Staged scaling for the SP1 prover:
 
 | Stage | When to move | Configuration |
 |---|---|---|
-| **1. CPU (current)** | Baseline | `SP1_PROVER=cpu` running on Mac Studio M3 Ultra, 96 GB unified memory. Measure `update_account` / `create_account` latency under real load before scaling further. |
+| **0. Mock (DEV)** | Development & testing | `SP1_PROVER=mock` — no real proofs, instant responses. Required on DEV because CPU prover causes OOM (SP1 `update_account` exceeds available memory). |
+| **1. CPU (PRD)** | Production baseline | `SP1_PROVER=cpu` running on Mac Studio M3 Ultra, 96 GB unified memory. `create_account` works, `update_account` needs memory tuning. |
 | **2. Succinct Prover Network** | CPU latency becomes a bottleneck | `SP1_PROVER=network` — no hardware commitment, requires PROVE token deposit and accepts token-price exposure. See [docs.succinct.xyz](https://docs.succinct.xyz/docs/sp1/prover-network/quickstart). |
 | **3. Self-hosted CUDA** | Network volume too costly or PROVE exposure undesirable | `SP1_PROVER=cuda` on x86 Linux with NVIDIA GPU (Compute Capability ≥ 8.6, ≥ 24 GB VRAM — RTX 4090 / 5090 / RTX 6000 Ada). Apple Silicon is not supported. |
 
 Skip stages only with concrete latency or cost data, not assumptions.
 
 ## Open Tasks
 
-- [x] CORS headers (allow frontend to call API directly)
-- [x] Real SP1 proofs (CPU prover live on DEV/PRD)
 - [ ] GPU acceleration (`SP1_PROVER=cuda`) or Succinct Prover Network
 - [ ] Explorer endpoints (`/api/stats`, `/api/nullifiers`)
-- [ ] Publisher key from environment variable (currently hardcoded)
 - [ ] Light client support
 
 ## Related

diff --git a/elf/zkcoins-program b/elf/zkcoins-program
diff --git a/program/src/lib.rs b/program/src/lib.rs
@@ -1,11 +1,11 @@
 use merkle::{hash_concat, merkle_mountain_range::MMRProof};
-use rand::Rng;
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 
 use derive_builder::Builder;
 use merkle::{
-    sparse_merkle_tree::{InclusionProof, NonInclusionProof, DEFAULT_HASHES}, HashDigest
+    sparse_merkle_tree::{InclusionProof, NonInclusionProof, DEFAULT_HASHES},
+    HashDigest,
 };
 
 pub type Amount = u64;
@@ -67,7 +67,10 @@ impl CommitmentMerkleProofs {
     }
 }
 
-pub const MINTING_ADDRESS: HashDigest = [44, 153, 26, 227, 141, 88, 195, 127, 88, 144, 228, 143, 121, 49, 51, 158, 111, 205, 183, 53, 133, 35, 183, 240, 183, 165, 104, 116, 66, 228, 94, 242];
+pub const MINTING_ADDRESS: HashDigest = [
+    175, 83, 161, 5, 16, 78, 44, 44, 237, 20, 140, 19, 48, 116, 86, 210, 247, 116, 223, 190, 106,
+    191, 59, 198, 226, 248, 55, 102, 143, 24, 155, 216,
+];
 
 pub fn hash(data: &[u8]) -> HashDigest {
     Sha256::digest(data).into()
@@ -139,13 +142,7 @@ pub struct AccountState {
 
 impl AccountState {
     pub fn new(initial_public_key: PublicKey) -> Self {
-        // TODO: The randomness here is annoying why do we not hash the public key directly and
-        // skip the first one in the commitments?
-        // We add random bytes to the public key as a blinding factor for the address.
-        // This ensures that the on-chain commited public keys can not be linked to the address.
-        let mut rng = rand::thread_rng();
-        let random_bytes: [u8; 32] = rng.gen();
-        let address = hash(&[initial_public_key.clone(), random_bytes.to_vec()].concat());
+        let address = hash(&initial_public_key);
         AccountState {
             owner: address,
             balance: 0,
@@ -160,7 +157,7 @@ impl AccountState {
 
         self.balance = match self.balance.checked_add(coin.amount) {
             Some(balance) => balance,
-            None => return Err("Receiving coin causes an overflow")
+            None => return Err("Receiving coin causes an overflow"),
         };
         Ok(self)
     }
@@ -187,7 +184,7 @@ impl AccountState {
             // Apply coin.
             self.balance = match self.balance.checked_sub(coin.amount) {
                 Some(balance) => balance,
-                None => return Err("Balance too small to create Coin.")
+                None => return Err("Balance too small to create Coin."),
             };
         }