> 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/quick-start.md).

# Quick Start

Get QuantumWing running in 5 minutes with our three-layer blockchain

## Prerequisites

* Linux/macOS system
* Go 1.21+ installed
* 8GB RAM minimum (32GB for multi-node)
* 50GB disk space

## Deployment Options

QuantumWing supports **4 deployment methods**:

| Method             | Script                          | Use Case                         | Nodes        |
| ------------------ | ------------------------------- | -------------------------------- | ------------ |
| **🧪 Development** | `secure-three-layer.sh`         | Local testing, single machine    | 1 (3 layers) |
| **🏭 Production**  | `production-setup.sh`           | Real validators, true separation | 3 validators |
| **🌐 Multi-Node**  | `start-3node-dht-testnet.sh`    | P2P testing, DHT discovery       | 3 nodes      |
| **🐳 Docker**      | `docker-compose-production.yml` | Container deployment             | 5 nodes      |

## Option 1: Development (Fastest)

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

# Run secure three-layer setup
./scripts/secure-three-layer.sh
```

This script starts all three layers:

* **Execution Layer** (Port 8546) - Transaction processing + QWVM
* **Beacon Chain** (Port 8080) - PoR consensus
* **Validator** (3 instances) - Block proposals and attestations

## Option 2: Production Setup

For **real validator separation** (enterprise deployment):

```bash
./scripts/production-setup.sh
```

**What this does**:

* Creates 3 **production validator wallets** with Dilithium Mode 3 keys
* Generates **production genesis** (`quantum-production-1` chain ID)
* Starts **Beacon Coordinator** (no self-validation)
* Launches **3 external validators** (submit blocks via API)
* True separation: validators are **independent processes**

**Verify**:

```bash
# Check validator registration
curl http://localhost:8080/api/v1/validators | jq '.'

# Monitor validator 0 logs
tail -f logs/validators/production-validator-0.log
```

## Option 3: Multi-Node P2P Network

For **DHT peer discovery** testing:

```bash
./scripts/start-3node-dht-testnet.sh
```

**Network topology**:

* **Node 1**: Bootstrap seed (Execution: 8546, Beacon: 8080)
* **Node 2**: Bootstraps to Node 1 (Execution: 8547, Beacon: 8081)
* **Node 3**: Discovers Node 2 via DHT (Execution: 8548, Beacon: 8082)

**Verify P2P connectivity**:

```bash
# Check Node 1 peers
curl http://localhost:8080/api/v1/p2p/peers | jq '.peers | length'

# Check Node 3 discovered Node 2 via DHT
grep "Discovered peer via DHT" logs/node3/beacon/beacon.log
```

## Option 4: Docker Multi-Node

For **containerized** production deployment:

```bash
cd deployments

# Start 5-node network
docker-compose -f docker-compose-production.yml up -d

# Check status
docker-compose -f docker-compose-production.yml ps

# View logs
docker-compose -f docker-compose-production.yml logs -f node-0
```

**Architecture**:

* 5 blockchain nodes (ports 8080-8084)
* HAProxy load balancer (port 80)
* Prometheus + Grafana monitoring
* Persistent volumes for data

## Verify It's Running

### Check Execution Layer

```bash
curl http://localhost:8546/health
```

Expected output:

```json
{
  "status": "healthy",
  "layer": "execution",
  "latest_block": 42,
  "peers": 3
}
```

### Check Beacon Chain

```bash
curl http://localhost:8080/beacon/v1/node/syncing
```

Expected output:

```json
{
  "data": {
    "head_slot": "64",
    "sync_distance": "0",
    "is_syncing": false
  }
}
```

### Check Validator

```bash
tail -f logs/validators/validator-0.log
```

Look for:

```
INFO Successfully proposed block slot=64 block_root=0x1234...
INFO Attestation included slot=65 committee_index=0
```

## Create Your First Wallet

```bash
./build/quantum-wing-blockchain wallet generate-v2 \
    -o wallet.json --mode 3 --words 24
```

This generates a Dilithium Mode 3 key pair with an EVM-style address, plus a BIP-39 24-word mnemonic. The mnemonic is shown **once on stdout** and is the only recovery path — write it down. The wallet file stores **only the encrypted seed** (Argon2id + AES-256-GCM); the plaintext private key never touches disk.

```json
{
  "version": "2.0",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5",
  "ecdsa_address": "0xC012aB...",
  "encrypted_seed": "argon2id-aes256gcm-base64...",
  "kdf": { "algo": "argon2id", "memory": 65536, "iterations": 3, "parallelism": 4, "salt": "..." },
  "dilithium_mode": 3,
  "ecdsa_curve": "secp256k1",
  "derivation_path": "m/44'/60'/0'/0/0"
}
```

For non-TTY environments (CI, Docker), redirect the seed to a file descriptor:

```bash
./build/quantum-wing-blockchain wallet generate-v2 \
    -o wallet.json --mode 3 --words 24 \
    --show-mnemonic-fd 3 3>seed.txt
```

## Fund Your Wallet (Testnet)

```bash
curl -X POST http://localhost:8546/api/v1/faucet/claim \
  -H "Content-Type: application/json" \
  -d '{"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"}'
```

Returns:

```json
{
  "success": true,
  "tx_hash": "0xabcd1234...",
  "amount": "10000000000000000000"
}
```

You now have **10 QWING** test tokens (24-hour cooldown per address).

## Send Your First Transaction

```bash
./build/quantum-wing-blockchain wallet send \
  --wallet wallet.json \
  --to 0x1234567890abcdef1234567890abcdef12345678 \
  --amount 1.5 \
  --rpc http://localhost:8545
```

Output:

```
✅ Transaction sent successfully!
├─ Hash: 0xdef5678...
├─ From: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5
├─ To: 0x1234567890abcdef1234567890abcdef12345678
├─ Amount: 1.5 QWING
├─ Gas Price: 20 Gwei
└─ Status: Pending...

⏳ Waiting for confirmation...
✅ Confirmed in block 127 (finalized in ~12.8 min)
```

## Next Steps

<table data-card-size="large" 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>📦 Full Installation</strong></td><td>Build from source and configure production setup</td><td><a href="/quantumwing/getting-started/installation.md">Installation</a></td></tr><tr><td><strong>🏗️ Architecture</strong></td><td>Understand the three-layer design</td><td><a href="/quantumwing/architecture/overview.md">Overview</a></td></tr><tr><td><strong>🤖 Deploy Smart Contracts</strong></td><td>Learn QWVM WebAssembly contracts</td><td><a href="/quantumwing/smart-contracts/qwvm.md">QWVM Overview</a></td></tr></tbody></table>

## Troubleshooting

### Port Already in Use

```bash
# Check what's using port 8546
lsof -i :8546

# Kill the process
kill -9 <PID>
```

### Genesis File Mismatch

```bash
# The production genesis is checked in at genesis/production-genesis.json.
# Do NOT regenerate it for a normal local-dev run — just clear stale data:
rm -rf data/execution data/beacon
./scripts/secure-three-layer.sh

# To inspect the current fork manifest in the genesis:
./build/qwfork list --genesis genesis/production-genesis.json
```

### Validator Not Proposing

Check validator logs:

```bash
grep "ERROR" logs/validators/validator-0.log
```

Common issues:

* Clock not synced (run `sudo ntpdate pool.ntp.org`)
* Insufficient stake (need 32 QWING minimum)
* Wrong genesis file

## Performance Tips

{% hint style="success" %}
**Production Optimization**: For high-throughput deployments, see [Performance Tuning](/quantumwing/operations/performance.md) for BadgerDB configuration and P2P networking optimizations.
{% endhint %}

{% hint style="info" %}
**Monitoring**: Enable Prometheus metrics with `--metrics-enabled` flag. See [Monitoring](/quantumwing/operations/monitoring.md) for Grafana dashboards.
{% 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/quick-start.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.