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

# Configuration

Advanced configuration options for production QuantumWing deployments

## Configuration Files

QuantumWing uses **YAML** configuration files for each layer:

```
config/
├── execution.yaml     # Execution layer settings
├── beacon.yaml        # Beacon chain settings
└── validator.yaml     # Validator settings
```

## Execution Layer Configuration

### Full Example (`config/execution.yaml`)

```yaml
# Network settings
network:
  chain-id: "quantum-wing-1"
  network-id: 1
  p2p-port: 30303
  max-peers: 50
  bootnodes:
    - "/ip4/104.131.131.82/tcp/30303/p2p/16Uiu2HAm..."
    - "/ip4/134.209.68.74/tcp/30303/p2p/16Uiu2HAm..."

# API settings
api:
  http-enabled: true
  http-host: "0.0.0.0"
  http-port: 8546
  http-cors-domains: ["*"]
  http-virtual-hosts: ["*"]
  
  ws-enabled: true
  ws-host: "0.0.0.0"
  ws-port: 8547
  ws-origins: ["*"]
  
  # JSON-RPC methods
  http-api: ["eth", "net", "web3", "txpool"]
  ws-api: ["eth", "net", "web3"]

# Storage settings
storage:
  datadir: "./data/execution"
  backend: "badgerdb"
  
  # BadgerDB tuning
  badger:
    sync-writes: false           # Async writes for performance
    num-versions-to-keep: 1      # Minimal version history
    num-memtables: 4             # More memtables = faster writes
    value-log-max-entries: 1000000
    table-size: 64MB             # Larger SST tables
    value-threshold: 1KB         # Store small values in LSM
    
    # Garbage collection
    gc-interval: "15m"
    gc-ratio: 0.5                # Collect when 50% garbage

# Transaction pool settings
txpool:
  locals: []
  no-locals: false
  journal: "txpool.journal"
  rejournal: "1h"
  
  price-limit: 1               # Min gas price (gwei)
  price-bump: 10               # % increase for replacement
  
  account-slots: 16            # Max txs per account
  global-slots: 4096           # Max pending txs globally
  account-queue: 64            # Max queued per account
  global-queue: 1024           # Max queued globally
  
  lifetime: "3h"               # Drop txs after 3 hours

# Gas settings
gas:
  floor: 8000000               # Min gas limit
  ceil: 40000000               # Max gas limit
  price: 1                     # Suggested gas price

# Mining/validator settings
miner:
  etherbase: "0x0000000000000000000000000000000000000000"
  gas-price: 1
  gas-limit: 40000000

# Logging settings
log:
  level: "info"                # debug, info, warn, error
  format: "json"               # json or text
  file: "./logs/execution.log"
  max-size: 100MB              # Rotate after 100MB
  max-age: 30                  # Keep logs for 30 days
  max-backups: 10              # Keep 10 old logs
  compress: true               # Compress old logs

# Metrics settings
metrics:
  enabled: true
  http-host: "0.0.0.0"
  http-port: 6060
  
  # Prometheus integration
  prometheus: true
  prometheus-addr: "0.0.0.0:9090"

# Performance settings
cache:
  database: 768                # BadgerDB cache (MB)
  trie: 256                    # State trie cache (MB)
  trie-journal: "triecache"    # Trie cache journal
  trie-rejournal: "1h"         # Rejournal interval
  
  gc: 25                       # GC target %
  snapshot: true               # Enable state snapshots
  preimages: true              # Store trie preimages
```

### Key Parameters

#### Network Settings

| Parameter   | Default | Description                  |
| ----------- | ------- | ---------------------------- |
| `p2p-port`  | 30303   | P2P listening port           |
| `max-peers` | 50      | Maximum peer connections     |
| `bootnodes` | \[]     | Initial peer discovery nodes |

#### API Settings

| Parameter           | Default | Description          |
| ------------------- | ------- | -------------------- |
| `http-port`         | 8546    | JSON-RPC HTTP port   |
| `ws-port`           | 8547    | WebSocket port       |
| `http-cors-domains` | \["\*"] | CORS allowed origins |

#### Storage Settings

| Parameter     | Default  | Description                         |
| ------------- | -------- | ----------------------------------- |
| `backend`     | badgerdb | Database backend                    |
| `sync-writes` | false    | Sync every write (slower but safer) |
| `table-size`  | 64MB     | SSTable size for BadgerDB           |

## Beacon Chain Configuration

### Full Example (`config/beacon.yaml`)

```yaml
# Network settings
network:
  chain-id: "quantum-wing-1"
  p2p-port: 9000
  max-peers: 100
  target-peers: 75
  
  # Peer discovery
  discovery-port: 9000
  discovery-v5: true
  
  # libp2p settings
  libp2p:
    listen-addresses:
      - "/ip4/0.0.0.0/tcp/9000"
      - "/ip6/::/tcp/9000"
    
    # Gossipsub tuning
    gossipsub:
      d: 8              # Desired peers per topic
      d-low: 6          # Min peers before adding
      d-high: 12        # Max peers before pruning
      d-score: 4        # Score-based peer retention
      
      heartbeat-interval: "700ms"
      history-length: 5
      history-gossip: 3

# Consensus settings
consensus:
  block-time: 12              # Slot duration (seconds)
  slots-per-epoch: 32         # Slots per epoch
  finality-depth: 64          # Slots for finality
  
  # Validator settings
  min-stake: "32000000000000000000"  # 32 QWING
  max-validators: 10000
  
  # Rewards & penalties
  base-reward: "10000000000000000"   # 0.01 QWING
  attestation-reward: "1000000000000000"  # 0.001 QWING
  proposer-reward-fraction: 0.125
  
  # Slashing
  slash-fraction-double-sign: 0.5
  slash-fraction-offline: 0.25
  slash-withdraw-delay-epochs: 8192   # ~36 days

# VRF & RANDAO settings
randomness:
  vrf-threshold: 0.5          # Probability threshold
  randao-mix-length: 65536    # RANDAO history size

# REST API settings
api:
  host: "0.0.0.0"
  port: 8080
  cors-domains: ["*"]
  
  # Enable API endpoints
  endpoints:
    - "/beacon/v1/*"
    - "/validator/v1/*"
    - "/node/v1/*"
    - "/config/v1/*"

# Storage settings
storage:
  datadir: "./data/beacon"
  backend: "badgerdb"
  
  # Pruning
  prune-old-states: true
  states-to-keep: 64          # Keep last 64 finalized states

# Logging
log:
  level: "info"
  file: "./logs/beacon.log"
  max-size: 100MB
  max-age: 30
  max-backups: 10

# Metrics
metrics:
  enabled: true
  port: 8081
  prometheus: true
```

### Key Parameters

#### Consensus Settings

| Parameter         | Default  | Description               |
| ----------------- | -------- | ------------------------- |
| `block-time`      | 12       | Slot duration in seconds  |
| `slots-per-epoch` | 32       | Number of slots per epoch |
| `min-stake`       | 32 QWING | Minimum validator stake   |

#### Slashing Conditions

| Condition          | Penalty   | Description                          |
| ------------------ | --------- | ------------------------------------ |
| **Double-sign**    | 50% stake | Signing two blocks at same height    |
| **Offline**        | 25% stake | Missing 10+ consecutive attestations |
| **Invalid RANDAO** | 10% stake | Wrong RANDAO reveal                  |

## Validator Configuration

### Full Example (`config/validator.yaml`)

```yaml
# Beacon chain connection
beacon:
  rpc-host: "http://localhost:8080"
  timeout: "10s"
  retry-delay: "5s"

# Wallet settings
wallet:
  file: "./validator-wallet.json"
  password-file: "./password.txt"
  
  # Slashing protection
  slashing-protection-db: "./data/validators/slashing_protection.db"
  
  # Key management
  key-manager: "local"        # local, remote, or vault
  
  # Remote signing (optional)
  # remote-signer:
  #   url: "http://remote-signer:9000"
  #   public-key: "0x..."

# Graffiti (included in proposed blocks)
graffiti: "QuantumWing Validator"

# Fee recipient (where block rewards go)
fee-recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"

# Performance settings
performance:
  # Attestation submission
  attestation-deadline: "4s"  # Submit attestations within 4s of slot start
  
  # Block proposal
  proposal-deadline: "8s"     # Propose block within 8s of slot start
  
  # Parallelization
  parallel-attestations: 4    # Process 4 attestations concurrently

# Logging
log:
  level: "info"
  file: "./logs/validator.log"
  max-size: 50MB
  max-age: 30

# Metrics
metrics:
  enabled: true
  port: 8082
```

### Key Parameters

#### Wallet Settings

| Parameter                | Default | Description                        |
| ------------------------ | ------- | ---------------------------------- |
| `file`                   | -       | Path to Dilithium wallet JSON      |
| `password-file`          | -       | Password file for wallet           |
| `slashing-protection-db` | -       | Database to prevent double-signing |

#### Performance Tuning

| Parameter              | Default | Description                       |
| ---------------------- | ------- | --------------------------------- |
| `attestation-deadline` | 4s      | Max time to create attestation    |
| `proposal-deadline`    | 8s      | Max time to create block proposal |

## Environment Variables

Override config with environment variables:

```bash
# Execution layer
export QWNG_HTTP_PORT=8546
export QWNG_WS_PORT=8547
export QWNG_DATADIR=/data/execution

# Beacon chain
export QWNG_BEACON_PORT=8080
export QWNG_P2P_PORT=9000

# Validator
export QWNG_VALIDATOR_WALLET=/secure/wallet.json
export QWNG_FEE_RECIPIENT=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5
```

## Production Best Practices

### Security

{% hint style="danger" %}
**Critical**: Never commit `password.txt` or wallet files to Git! Use environment variables or secret management systems.
{% endhint %}

```yaml
# Use Vault for secrets (recommended)
wallet:
  key-manager: "vault"
  vault:
    address: "https://vault.example.com"
    token: "${VAULT_TOKEN}"
    path: "secret/validators/wallet"
```

### High Availability

```yaml
# Run multiple beacon nodes
beacon:
  rpc-hosts:
    - "http://beacon-1:8080"
    - "http://beacon-2:8080"
    - "http://beacon-3:8080"
  failover-timeout: "5s"
```

### Monitoring

```yaml
# Enable all metrics
metrics:
  enabled: true
  prometheus: true
  prometheus-addr: "0.0.0.0:9090"
  
  # Export custom metrics
  export:
    - "blocks_proposed_total"
    - "attestations_submitted_total"
    - "slashing_events_total"
```

## Further Reading

<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>🚀 Production Setup</strong></td><td>Deploy to production environments</td><td><a href="/quantumwing/deployment/production-setup.md">Production Setup</a></td></tr><tr><td><strong>📊 Monitoring</strong></td><td>Prometheus &#x26; Grafana setup</td><td><a href="/quantumwing/operations/monitoring.md">Monitoring</a></td></tr><tr><td><strong>⚡ Performance</strong></td><td>Optimization guide</td><td><a href="/quantumwing/operations/performance.md">Performance Tuning</a></td></tr></tbody></table>


---

# 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/configuration.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.