# Configuration

## 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 ETH
  max-validators: 10000
  
  # Rewards & penalties
  base-reward: "10000000000000000"   # 0.01 ETH
  attestation-reward: "1000000000000000"  # 0.001 ETH
  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 ETH  | 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="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><tr><td><strong>📊 Monitoring</strong></td><td>Prometheus &#x26; Grafana setup</td><td><a href="https://github.com/dolfrin/QuantumWing/blob/master/docs/operations/monitoring.md">https://github.com/dolfrin/QuantumWing/blob/master/docs/operations/monitoring.md</a></td></tr><tr><td><strong>⚡ Performance</strong></td><td>Optimization guide</td><td><a href="https://github.com/dolfrin/QuantumWing/blob/master/docs/operations/performance.md">https://github.com/dolfrin/QuantumWing/blob/master/docs/operations/performance.md</a></td></tr></tbody></table>