# Installation

## System Requirements

### Minimum Requirements

| Component   | Specification            |
| ----------- | ------------------------ |
| **CPU**     | 4 cores                  |
| **RAM**     | 8 GB                     |
| **Storage** | 50 GB SSD                |
| **Network** | 10 Mbps                  |
| **OS**      | Ubuntu 20.04+, macOS 11+ |

### Recommended Requirements

| Component   | Specification    |
| ----------- | ---------------- |
| **CPU**     | 8+ cores         |
| **RAM**     | 16 GB            |
| **Storage** | 500 GB NVMe SSD  |
| **Network** | 100 Mbps         |
| **OS**      | Ubuntu 22.04 LTS |

## Install Dependencies

### Ubuntu/Debian

```bash
# Update package lists
sudo apt update

# Install Go 1.21+
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Install build tools
sudo apt install -y build-essential git make

# Install BadgerDB dependencies
sudo apt install -y libsnappy-dev zlib1g-dev libbz2-dev liblz4-dev libzstd-dev
```

### macOS

```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Go
brew install go@1.21

# Install build tools
brew install make git
```

## Build QuantumWing

### Clone Repository

```bash
git clone https://github.com/quantumwing/protocol.git
cd protocol
```

### Build All Binaries

```bash
# Build all three layers
make build

# This creates:
# - build/quantum-wing-execution   (Execution layer)
# - build/quantum-wing-blockchain  (Beacon chain)
# - build/quantum-wing-validator   (Validator)
```

### Install Globally

```bash
# Install to /usr/local/bin
sudo make install

# Verify installation
quantum-wing --version
```

Expected output:

```
QuantumWing v1.0.0
├─ Go: go1.21.5
├─ Commit: a1b2c3d
├─ Build Date: 2025-10-28
└─ Quantum-Safe: Dilithium Mode 3
```

## Generate Genesis File

```bash
# Create genesis configuration
quantum-wing genesis generate genesis.json \
  --chain-id quantum-wing-1 \
  --timestamp $(date +%s) \
  --initial-validators 4
```

Genesis file structure:

```json
{
  "config": {
    "chainId": "quantum-wing-1",
    "consensusEngine": "proof-of-randomness",
    "blockTime": 12,
    "epochLength": 32
  },
  "timestamp": 1730102400,
  "validators": [
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5",
      "publicKey": "dilithium_mode3_key...",
      "stake": "32000000000000000000"
    }
  ],
  "alloc": {
    "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5": {
      "balance": "1000000000000000000000"
    }
  }
}
```

## Create Validator Wallet

```bash
# Generate Dilithium Mode 3 key
quantum-wing crypto generate-key \
  --mode 3 \
  --output validator-wallet.json \
  --password-file password.txt
```

{% hint style="warning" %}
**Security**: Store `validator-wallet.json` and `password.txt` securely! These control your validator and staked funds.
{% endhint %}

### Import Existing Key

```bash
# From mnemonic
quantum-wing wallet import \
  --mnemonic "word1 word2 ... word24" \
  --output imported-wallet.json

# From private key
quantum-wing wallet import \
  --private-key 0xabcd1234... \
  --output imported-wallet.json
```

## Initialize Data Directories

```bash
# Create directory structure
mkdir -p data/execution data/beacon data/validators logs

# Set permissions
chmod 700 data/validators
```

## Configuration Files

### Execution Layer Config

Create `config/execution.yaml`:

```yaml
datadir: "./data/execution"
http-port: 8546
ws-port: 8547
p2p-port: 30303
max-peers: 50
db:
  backend: "badgerdb"
  cache-size: 1024
  max-open-files: 1000
log:
  level: "info"
  file: "./logs/execution.log"
```

### Beacon Chain Config

Create `config/beacon.yaml`:

```yaml
datadir: "./data/beacon"
http-port: 8080
p2p-port: 9000
genesis-file: "./genesis.json"
consensus:
  block-time: 12
  epoch-length: 32
  finality-depth: 64
p2p:
  bootnodes:
    - "/ip4/104.131.131.82/tcp/9000/p2p/16Uiu2HAm..."
log:
  level: "info"
  file: "./logs/beacon.log"
```

### Validator Config

Create `config/validator.yaml`:

```yaml
beacon-rpc: "http://localhost:8080"
wallet-file: "./validator-wallet.json"
password-file: "./password.txt"
graffiti: "QuantumWing Validator"
log:
  level: "info"
  file: "./logs/validator.log"
```

## Start the Network

### Option 1: Quick Start Script

```bash
./scripts/secure-three-layer.sh
```

### Option 2: Manual Start

#### Terminal 1: Execution Layer

```bash
quantum-wing-execution \
  --config config/execution.yaml \
  --genesis genesis.json
```

#### Terminal 2: Beacon Chain

```bash
quantum-wing-blockchain \
  --config config/beacon.yaml \
  --genesis genesis.json
```

#### Terminal 3: Validator

```bash
quantum-wing-validator \
  --config config/validator.yaml \
  --wallet validator-wallet.json
```

## Verify Installation

### Check All Services

```bash
# Execution layer
curl http://localhost:8546/health

# Beacon chain
curl http://localhost:8080/beacon/v1/node/health

# Validator (check logs)
tail -f logs/validator.log | grep "Successfully proposed"
```

### Run Test Suite

```bash
# Unit tests
make test

# Integration tests
make test-integration

# End-to-end tests
make test-e2e
```

Expected output:

```
✅ PASS: blockchain/core/block_test.go (0.23s)
✅ PASS: blockchain/consensus/por_test.go (1.45s)
✅ PASS: crypto/dilithium/sign_test.go (0.08s)
✅ PASS: blockchain/evm/transaction_test.go (0.34s)

Total: 247 tests passed, 0 failed
```

## Next Steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>⚙️ Configuration</strong></td><td>Advanced configuration options</td><td><a href="configuration">configuration</a></td></tr><tr><td><strong>🏗️ Architecture</strong></td><td>Understand the system design</td><td><a href="../architecture/overview">overview</a></td></tr><tr><td><strong>🚀 Production Deployment</strong></td><td>Deploy to production environments</td><td><a href="https://github.com/dolfrin/QuantumWing/blob/master/docs/deployment/production-setup.md">https://github.com/dolfrin/QuantumWing/blob/master/docs/deployment/production-setup.md</a></td></tr></tbody></table>

## Troubleshooting

### Build Failures

**Error**: `cannot find package "github.com/dgraph-io/badger/v3"`

```bash
# Clear Go module cache
go clean -modcache

# Reinstall dependencies
go mod download
go mod verify
```

**Error**: `undefined: dilithium.GenerateKey`

```bash
# Update submodules
git submodule update --init --recursive

# Rebuild
make clean && make build
```

### Genesis Validation Errors

**Error**: `genesis timestamp is in the future`

```bash
# Regenerate with current timestamp
quantum-wing genesis generate genesis.json \
  --timestamp $(date +%s)
```

### Validator Not Starting

**Error**: `failed to unlock wallet`

```bash
# Check password file exists
cat password.txt

# Try interactive unlock
quantum-wing-validator --wallet validator-wallet.json
# Enter password when prompted
```

{% hint style="info" %}
**Need Help?** Join our Discord at [discord.gg/quantumwing](https://discord.gg/quantumwing) or open an issue on [GitHub](https://github.com/quantumwing/protocol/issues).
{% endhint %}