> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/getting-started/installation.md).

# Installation

Complete installation guide for building QuantumWing from source

## 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="/quantumwing/getting-started/configuration.md">Configuration</a></td></tr><tr><td><strong>🏗️ Architecture</strong></td><td>Understand the system design</td><td><a href="/quantumwing/architecture/overview.md">Overview</a></td></tr><tr><td><strong>🚀 Production Deployment</strong></td><td>Deploy to production environments</td><td><a href="/quantumwing/deployment/production-setup.md">Production Setup</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/WJu7tsS8W4](https://discord.gg/WJu7tsS8W4) or open an issue on [GitHub](https://github.com/quantumwing/protocol/issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://quantumwing.gitbook.io/quantumwing/getting-started/installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.