> 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/operations/performance.md).

# Performance Tuning

Tuning knobs for throughput, latency, and resource use

QuantumWing's defaults target a 1-vCPU validator on commodity SSD with 16 GB RAM and 1 Gbit network. The numbers below come from `monitoring/` runs of the alpha load test (2,000 TPS sustained) and the per-package benchmark suite. Operators with different SLOs can move these knobs.

## Where the time goes

```
Per-block budget (12s slot):
  P2P propagation ......... 150 ms
  QWVM execution .......... 50 ms / contract call
  Dilithium verify ........ 120 ms / sig (Mode 3)
  BadgerDB sync write ..... 30 ms
  Block proposal .......... ~2 s end-to-end
  ────────────────────────────────────────
  Slack ................... ~9 s
```

## Throughput ceilings

```
Layer       Limit           Bottleneck
────────────────────────────────────────────
Execution   2,000 TPS       BadgerDB Put + signature verify
Beacon      64 blocks/s     CPU (Dilithium aggregate)
Validator   10 K sig/s      Dilithium signing throughput
Network     ~100 MB/s       Bandwidth + GossipSub overhead
```

## CPU

Dilithium is the dominant cost (\~120 µs per Mode 3 verification). Vectorized AVX2 / NEON paths in `crypto/dilithium/` are picked up automatically when `GOAMD64=v3` or `GOARM64=v8.2` is set at build time:

```bash
# Production binary (AVX2):
GOAMD64=v3 make build

# ARM64 production:
GOARM64=v8.2 make build
```

Validators benefit from CPU-pinning the libp2p host and the consensus goroutine to dedicated cores:

```bash
# Pin to cores 2-3 (out of 0-7), exclude scheduler IRQs from those cores
taskset -c 2,3 ./build/quantum-wing-blockchain start ...
```

## Memory

Defaults work in 8 GB. Validators on 4 GB hosts must drop:

```
mempool size cap:       --mempool-max=2000   (default ~10000)
GossipSub mesh degree:  D=6                   (default D=8)
DHT routing table:      no change — fixed at 256
```

The biggest variable is the mempool — a flooded mempool can balloon to several hundred MB. Operator alerts on `MempoolSize > 50000`.

## Disk (BadgerDB)

BadgerDB's `SyncWrites` controls per-`Put` durability. Validators MUST keep `SyncWrites=true` (slashing protection depends on it). Read-only RPC nodes can drop it for \~2x throughput at the cost of a fsync window on crash:

```go
// blockchain/storage/storage.go::Config
Config{
  SyncWrites:  false,   // RPC ONLY — never validators
  Compression: true,
}
```

Compression (`ZSTD`) is on by default and is essentially free on modern CPUs. Disabling saves \~5% CPU at the cost of \~60% larger LSM tree.

Vlog GC ticker runs every 10 minutes (`runValueLogGC`). On a hot chain with > 10K Puts/s, dropping the cadence to 2 minutes prevents the vlog from growing past 10 GB:

```go
// patch in storage.go
ticker := time.NewTicker(2 * time.Minute)
```

See [../state-storage/badgerdb.md](/quantumwing/state-and-storage/badgerdb.md).

## Pruning

Full-mode pruning keeps disk usage stable at the working-set size + the keep-window. For most operators this is `~5 GB`. Archive nodes grow `~2-5 GB / month` at alpha throughput. Choose mode at first launch — switching after the fact requires a fresh datadir resync.

## Network

GossipSub `D=8` mesh degree is the default. On peers with limited bandwidth, drop to `D=6` saving \~25% peer-to-peer traffic at the cost of higher message-loss probability. Anything below `D=4` becomes fragile under churn.

```yaml
# config/p2p.yaml
gossipsub:
  d: 8
  d_lo: 6
  d_hi: 12
  d_lazy: 6
```

## Validator pipeline

Three knobs matter on the validator side:

```
slot_timer_offset:   500 ms before slot end, start packing block
                      (default 1s — too conservative on fast CPUs)

max_tx_per_block:    leave blank to inherit MaxGasPerBlock budget
                      (recommended)

attestation_lookahead: 1 slot (default)
                      Validator pre-fetches the attesting committee
                      one slot ahead.
```

Source: `cmd/validator/main.go`.

## Monitoring

Every tuning step lands in Prometheus:

```
qw_block_propose_duration_seconds            histogram
qw_dilithium_verify_duration_seconds         histogram
qw_badgerdb_lsm_size_bytes                   gauge
qw_badgerdb_vlog_size_bytes                  gauge
qw_mempool_size                               gauge
qw_gossipsub_published_messages_total        counter
qw_p2p_peers_connected                        gauge
```

The Grafana dashboard (`monitoring/grafana/dashboards/quantumwing.json`) already plots all of these; tuning means watching the histograms move.

## Benchmarks

```bash
# Cryptography
go test -bench=. ./crypto/dilithium
go test -bench=. ./vrf

# Mempool admission (signature heavy)
go test -bench=. -benchtime=10s ./blockchain/core

# QWVM contract execution
go test -bench=. ./qwvm
```

## Quick wins

| Symptom                   | First-line fix                                           |
| ------------------------- | -------------------------------------------------------- |
| Slow block production     | `GOAMD64=v3` build, taskset pin                          |
| Mempool ballooning        | Drop validator selection to faster validator host        |
| BadgerDB compaction lag   | Vlog GC ticker → 2 min, alert on `BadgerDBCompactionLag` |
| P2P drop-outs             | Raise `D_hi` to 12, audit reputation log                 |
| Dilithium verify > 200 µs | Rebuild with vector flags; check \`cat /proc/cpuinfo     |

## Code paths

* `crypto/dilithium/` — vectorized verify
* `blockchain/storage/storage.go` — BadgerDB tuning
* `blockchain/p2p/network.go` — GossipSub config
* `cmd/validator/main.go` — validator timing knobs
* `monitoring/` — dashboards + load test

## Related

* [monitoring.md](/quantumwing/operations/monitoring.md) — what to graph
* [metrics.md](/quantumwing/operations/metrics.md) — full metric inventory
* [../state-storage/badgerdb.md](/quantumwing/state-and-storage/badgerdb.md)
* [../resources/benchmarks.md](/quantumwing/resources/benchmarks.md)


---

# 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/operations/performance.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.