> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yattacorp.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How NEXUS works — a unified smart contract execution layer starting on Zcash

## What is NEXUS?

NEXUS is a **unified smart contract execution layer** for proof-of-work blockchains. It adds programmability to Zcash first, with Bitcoin and Dogecoin joining the same execution layer as it expands.

NEXUS is a **metaprotocol** — it has no separate chain. It reads Zcash (and later Bitcoin/Dogecoin) transactions, processes them according to NEXUS rules, runs WASM smart contracts, and writes a state summary back to those same chains. The underlying L1 never changes; NEXUS just gives it superpowers.

<Tip>
  **New to blockchain terms?** See the [Glossary](/glossary) for plain-English definitions of L1, WASM, ZK proofs, vaults, and more.
</Tip>

***

## V1 vs V2 — What's Available Now

| Feature                              | V1 (Live on Zcash) | V2 (Planned)           |
| ------------------------------------ | ------------------ | ---------------------- |
| Smart Contracts (WASM)               | ✅ Zcash            | ✅ + Bitcoin + Dogecoin |
| ZEC Deposits & Withdrawals           | ✅                  | ✅                      |
| BTC Deposits & Withdrawals           | 🔄 Coming soon     | ✅                      |
| DOGE Deposits & Withdrawals          | 🔄 Coming soon     | ✅                      |
| Stealth Addresses                    | ✅                  | ✅                      |
| Encrypted Mempool (MEV protection)   | ✅                  | ✅                      |
| Zcash Shielded Withdrawals (z-addr)  | 🔄 Coming in V2    | ✅                      |
| Cross-Chain Swaps (ZEC ↔ BTC ↔ DOGE) | ❌                  | ✅                      |
| Unified Liquidity Pools              | ❌                  | ✅                      |

***

## Core Components

```
┌─────────────────────────────────────────────────────────────────┐
│                      NEXUS Metaprotocol                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Execution Layer (processes transactions)     │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │
│  │  │  WASM VM    │  │  State      │  │  Encrypted  │       │   │
│  │  │  Executor   │  │  Processor  │  │  Mempool    │       │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           Bridge Layer (connects to each chain)          │   │
│  │  ┌────────────────────┐  ┌──────────┐  ┌──────────┐      │   │
│  │  │  Zcash Bridge      │  │  Bitcoin │  │ Dogecoin │      │   │
│  │  │  ✅ Live           │  │  🔄 Soon │  │ 🔄 Soon  │      │   │
│  │  └────────────────────┘  └──────────┘  └──────────┘      │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Security Layer                          │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │
│  │  │  ZK Proofs  │  │   Fraud     │  │  Economic   │       │   │
│  │  │   Groth16   │  │   Proofs    │  │   Bonds     │       │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

***

## Execution Layer

### WASM Virtual Machine (Smart Contract Engine)

NEXUS runs smart contracts written in Rust, compiled to [WebAssembly (WASM)](/glossary#w) — a compact, portable binary format. The VM:

* Runs the same contract code identically on every node
* Charges [gas](/glossary#g) for each operation (prevents runaway code)
* Provides contracts access to storage, events, L1 chain data, and cross-contract calls
* Today runs on Zcash; the same VM will execute contracts anchored to Bitcoin and Dogecoin when those chains join

### State Processor

The state processor maintains the global record of all contract state and balances. It:

* Processes transactions in order
* Computes a [state root](/glossary#s) — a single hash summarizing all state
* Posts that root to Zcash L1 so anyone can verify NEXUS is behaving correctly
* When Bitcoin/Dogecoin join, state roots are committed to all live chains simultaneously

### Encrypted Mempool

Transactions are encrypted before submission using [ECDH](/glossary#e) + [ChaCha20-Poly1305](/glossary#c). Their contents are hidden from miners until a block is produced. This prevents [MEV](/glossary#m) (front-running and sandwich attacks).

Protocol version 2. Domain: `nexus-encrypted-mempool-chacha20poly1305-v2`.

See [Encrypted Mempool](/concepts/encrypted-mempool) for details.

### Fee Market (EIP-1559 Style)

NEXUS uses a dynamic fee system:

* A **base fee** adjusts automatically — rises when blocks are full, falls when empty
* Maximum change per block: **±12.5%** (smooth, predictable)
* Target utilization: **40%** of block gas
* On Zcash: fees are denominated in zatoshi. Base fee: **244,000,000 zatoshi/gas unit**
* Add a **priority tip** for faster inclusion

***

## Bridge Layer

Each chain has a dedicated bridge that monitors deposits, processes withdrawals, and posts state commitments to L1.

### Zcash Bridge ✅ Live

* **Vault type**: Transparent address (t-addr), P2SH 2-of-2 multisig (you + protocol)
* **Verification**: [Groth16](/glossary#g) ZK proofs — verified **natively by Zcash nodes**. No external verifier needed.
* **State commits**: Posted as [Sapling](/glossary#s) shielded notes — **not OP\_RETURN**. Each epoch writes a shielded note with a 512-byte encrypted memo containing the full state metadata. Epochs are linked via [nullifiers](/glossary#n), forming a cryptographically verifiable chain from genesis.
* **Deposit confirmations**: 10 blocks (\~12.5 min at 75s/block)
* **Escape timelock**: 16,128 blocks (\~2 weeks)

<Info>
  **Why Sapling notes instead of OP\_RETURN?** Sapling memos hold 512 bytes (vs 80 bytes for OP\_RETURN), nullifiers prevent state replay, and Zcash natively verifies the cryptography. Anyone with the public Full Viewing Key can independently verify all NEXUS state history on Zcash.
</Info>

### Bitcoin Bridge 🔄 Coming soon

* **Vault type**: [Taproot (P2TR)](/glossary#t) with escape hatch
* **Verification**: [ZK-STARK](/glossary#z) proofs + [BitVM2](/glossary#b) bisection fraud proofs
* **State commits**: OP\_RETURN outputs (32-byte state root)
* **Deposit confirmations**: 6 blocks (\~60 min)
* **Escape timelock**: 2,016 blocks (\~2 weeks)

### Dogecoin Bridge 🔄 Coming soon

* **Vault type**: [P2PKH](/glossary#p) with [CLTV](/glossary#c) escape hatch
* **Verification**: ZK-STARK proofs + fraud proofs
* **State commits**: OP\_RETURN outputs
* **Deposit confirmations**: 3 blocks (\~3 min — Dogecoin's 1-minute blocks are the fastest)
* **Escape timelock**: 20,160 blocks (\~2 weeks)

***

## Security Layer

### How NEXUS Ensures Correctness

Two independent security mechanisms protect NEXUS on Zcash:

**1. Cryptographic proofs (Groth16 ZK)**

Before posting state, the operator generates a Groth16 proof that all transactions were processed correctly. Zcash nodes verify this natively — the same cryptography Zcash uses for shielded transactions. If the proof is invalid, Zcash rejects it outright.

**2. Economic bonds + fraud proofs**

Operators post a bond in ZEC before committing state. If the commitment is wrong, anyone can challenge:

```
1. Challenger detects an incorrect state commitment
2. Challenger posts a bond and opens a challenge
3. Bisection game narrows down to the single bad computation step
4. That step is verified on-chain via Groth16
5. The fraudulent operator loses their bond to the challenger
```

Both mechanisms must fail simultaneously for any attack to succeed.

### Verification by Chain

| Chain    | Proof System                | Who Verifies              | Status         |
| -------- | --------------------------- | ------------------------- | -------------- |
| Zcash    | Groth16 (native on-chain)   | Zcash nodes automatically | ✅ Live         |
| Bitcoin  | ZK-STARK + BitVM2 bisection | Anyone (permissionless)   | 🔄 Coming soon |
| Dogecoin | ZK-STARK + fraud proofs     | Anyone (permissionless)   | 🔄 Coming soon |

***

## Vault Architecture

Every user's deposited funds are held in a **vault** — an on-chain address with two spending paths:

```
Vault Address (Zcash t-addr, P2SH 2-of-2)
│
├── Normal Path — you + NEXUS together
│   └── Instant withdrawal — processed by the protocol
│
└── Escape Path — you alone, after ~2 weeks
    └── Safety exit — no permission needed, works even if NEXUS stops
```

The escape path ensures your funds are always recoverable. NEXUS cannot unilaterally spend from your vault — it needs your key.

### Escape Hatch Waiting Periods

| Chain    | Blocks | Time      | Why                     |
| -------- | ------ | --------- | ----------------------- |
| Zcash    | 16,128 | \~2 weeks | 16,128 × 75s = 14 days  |
| Bitcoin  | 2,016  | \~2 weeks | 2,016 × 10min = 14 days |
| Dogecoin | 20,160 | \~2 weeks | 20,160 × 1min = 14 days |

***

## Privacy Layer

NEXUS ships two privacy features in V1, live on Zcash:

**Stealth Addresses** — Generate a unique one-time address per transaction. Observers cannot link multiple transactions to the same wallet. Uses ECDH + HKDF-SHA256 with 1-byte view tags (filters 99.6% of non-matching scans). See [Stealth Addresses](/concepts/stealth-addresses).

**Encrypted Mempool** — Transactions encrypted before submission. Miners cannot read contents until after inclusion. Prevents MEV. See [Encrypted Mempool](/concepts/encrypted-mempool).

***

## Transaction Flow (on Zcash)

### Deposit

```
1. You request a vault address → SDK or CLI returns a Zcash t-addr
2. You send ZEC to that address
3. NEXUS scanner detects deposit after 10 confirmations (~12.5 min)
4. Your vZEC balance is credited on NEXUS
```

### Withdrawal

```
1. You request a withdrawal on NEXUS → vZEC burned immediately
2. Withdrawal queued for batch processing
3. Protocol signs and broadcasts the Zcash L1 transaction
4. You receive ZEC in your Zcash wallet
```

### Smart Contract Call

```
1. You submit a signed transaction (optionally encrypted via stealth/mempool)
2. Transaction waits in mempool
3. Block producer includes it in the next NEXUS block
4. WASM VM executes the contract function
5. State changes recorded; events emitted
6. At next epoch: Groth16 proof generated, state root committed to Zcash L1
```

***

## Node Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                       NEXUS Node                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │    RPC      │  │  Prover     │  │  Relayer    │              │
│  │   Server    │  │  (Groth16)  │  │  (L1 txs)  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   WASM      │  │   Vault     │  │  Watchtower │              │
│  │   VM        │  │   Manager   │  │  (fraud     │              │
│  │             │  │             │  │   detection)│              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Zcash     │  │   Bitcoin   │  │  Dogecoin   │              │
│  │   Scanner   │  │   Scanner   │  │  Scanner    │              │
│  │   ✅ Live   │  │   🔄 Soon  │  │   🔄 Soon  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Storage (RocksDB key-value database)         │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

| Node Mode | What it does                                                  | Who runs it               |
| --------- | ------------------------------------------------------------- | ------------------------- |
| Primary   | Produces NEXUS blocks, runs prover, commits state to Zcash L1 | Main operator             |
| Replica   | Syncs from primary, serves read requests                      | Scaling / redundancy      |
| Archive   | Full history, never prunes                                    | Block explorers, auditors |

***

## V2: Unified Execution Layer

When Bitcoin and Dogecoin join, NEXUS becomes a single execution layer across all three chains. V2 adds **intent exchange** — swap across chains without manually managing deposits and withdrawals:

```
You declare: "Swap 1 ZEC for at least 50,000 DOGE"
                    ↓
Solver network sees your intent and competes to fill it
                    ↓
Best solver executes across chains atomically
                    ↓
You receive DOGE; solver earns a small fee
```

No price slippage surprise. No counterparty risk. MEV protection built in.