> 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/architecture/three-layer-design.md).

# Three-Layer Design

Per-layer responsibilities, ports, and trust boundaries

QuantumWing separates the chain into three independently-running layers — execution, beacon, and validator — connected by REST and P2P. The split mirrors Ethereum 2.0's design and lets a deployment collocate or distribute layers as policy demands.

```
┌──────────────────────────────────────────────────────┐
│  VALIDATOR LAYER (off-chain)                         │
│  Holds Dilithium private keys, proposes + attests    │
│  Talks to: beacon + execution                         │
└──────────────────────────────────────────────────────┘
              │ REST (proposals, attestations)
              ▼
┌──────────────────────────────────────────────────────┐
│  BEACON CHAIN (port 8080)                            │
│  Coordinates consensus — VRF, RANDAO, slashing       │
│  Verifies every signature, owns validator registry   │
│  Talks to: execution (engine API), validators        │
└──────────────────────────────────────────────────────┘
              │ REST engine API
              ▼
┌──────────────────────────────────────────────────────┐
│  EXECUTION LAYER (port 8546)                         │
│  Applies blocks, runs QWVM, persists state            │
│  Independently re-verifies signatures + VRF          │
│  Talks to: beacon (engine API), wallets (RPC), P2P    │
└──────────────────────────────────────────────────────┘
```

## Per-layer responsibilities

### Execution layer (port 8546)

```
INPUTS:    blocks from beacon (engine_newPayload),
           transactions from wallets (REST + JSON-RPC),
           tx gossip from P2P
OUTPUTS:   state diffs, receipts, mempool, contract storage,
           reward credits

OWNS:      account balances, contract bytecode, contract storage,
           tx mempool, MPT state trie, BadgerDB datadir
```

Independently re-verifies every Dilithium signature and VRF proof on incoming blocks — does NOT trust the beacon. Defence in depth: a compromised beacon cannot smuggle invalid blocks past execution.

Code: `blockchain/core/`, `cmd/execution/`, `blockchain/api/jsonrpc/`.

### Beacon chain (port 8080)

```
INPUTS:    block proposals from validators (REST),
           attestations from validators (REST),
           RANDAO commits / reveals,
           slashing evidence
OUTPUTS:   accepted blocks (forwarded to execution),
           epoch finalisation events,
           slashing events,
           reward / penalty deltas

OWNS:      validator registry, slashing manager, rewards manager,
           RANDAO state, fork-choice tree (LMD-GHOST),
           bridge state machine
```

Code: `blockchain/consensus/por/`, `blockchain/api/`, `blockchain/bridge/`.

### Validator layer (off-chain client)

```
INPUTS:    duties + slot signals from beacon,
           pending txs from execution
OUTPUTS:   signed block proposals,
           signed attestations,
           RANDAO reveals

HOLDS:     Dilithium private key (highest-value secret on the host)
```

Validators do NOT have public RPC ports. They are out-bound clients that authenticate to the beacon and execution layers via TLS + an operator-issued bearer token.

Code: `cmd/validator/`.

## Ports

| Port         | Protocol   | Layer              | Public?             |
| ------------ | ---------- | ------------------ | ------------------- |
| 8080         | REST       | Beacon             | yes (TLS-fronted)   |
| 8545         | JSON-RPC   | Execution          | yes (TLS-fronted)   |
| 8546         | REST       | Execution          | yes (TLS-fronted)   |
| 9000         | libp2p     | Execution + Beacon | yes (NAT-traversed) |
| 9090         | Prometheus | All                | loopback only       |
| Engine paths | REST       | Beacon ↔ Execution | loopback only       |

`/api/v1/engine/*` paths MUST be firewalled to the loopback interface. An external caller with engine access can rewrite the chain head.

## Trust boundaries

```
Validator → Beacon         Dilithium signature, plus TLS
Beacon → Execution         loopback REST, no auth (engine API)
Execution → BadgerDB       SHA3-256 Merkle proofs
P2P                        libp2p Noise + Kyber (for select streams)
```

The beacon is the trust authority on consensus. Execution defence-in-depth re-verifies. Validators trust the beacon for slot selection but the beacon holds them accountable via slashing.

See [trust-boundaries.md](/quantumwing/architecture/trust-boundaries.md) for the formal model.

## Communication patterns

### Block production

```mermaid
sequenceDiagram
    participant V as Validator
    participant B as Beacon
    participant E as Execution

    Note over B: Slot N begins
    B->>B: VRF selects proposer
    B->>V: notify proposer
    V->>E: GET /api/v1/engine/getPendingTransactions
    E->>V: pending txs
    V->>V: pack block, sign with Dilithium
    V->>B: POST /api/v1/validator/blocks/propose
    B->>B: verify Dilithium + VRF
    B->>E: POST /api/v1/engine/newPayload
    E->>E: re-verify, apply block
    E->>B: state root + receipts
    B->>V: reward (deferred to epoch end)
```

### Attestation

```mermaid
sequenceDiagram
    participant Vi as Validator i
    participant B as Beacon

    Note over B: Slot N completed
    B->>Vi: attest to block N
    Vi->>B: POST /api/v1/attestation
    B->>B: verify Dilithium signature
    B->>B: aggregate
    Note over B: 2/3+ → finalisation queued
```

### Reward distribution

```mermaid
sequenceDiagram
    participant B as Beacon
    participant E as Execution

    Note over B: Epoch boundary
    B->>B: RewardsManager.DistributePending()
    B->>E: POST /api/v1/engine/creditRewards
    E->>E: update validator account balances
    E->>B: ack
    B->>B: clear pendingRewards
```

## Deployment patterns

### Single-host (development)

All three layers in one process. Used by `secure-three-layer.sh` and the multi-node testnet scripts.

### Three-host (production validator)

```
Host A:  execution layer       (port 8546, public TLS)
Host B:  beacon chain           (port 8080, public TLS)
Host C:  validator client       (no public ports, outbound only)
```

`engine API` traffic between A and B traverses a private network or VPN — never the public internet.

### Read-only RPC node

Execution + beacon, no validator. Serves wallet RPC traffic without risking a slashing event.

## Layer choice cheat sheet

| I want to...              | Connect to layer                                    |
| ------------------------- | --------------------------------------------------- |
| Read a balance            | Execution (8546 REST or 8545 RPC)                   |
| Submit a tx               | Execution                                           |
| Watch new blocks          | Beacon `/ws` (Execution `eth_subscribe` is stubbed) |
| Query validator status    | Beacon (`/api/v1/validators/...`)                   |
| Inspect slashing events   | Beacon (`/api/v1/slashing/...`)                     |
| Submit an attestation     | Beacon (`/api/v1/attestation`)                      |
| Read fork state (D-10)    | Beacon (`/api/v1/forks/state`)                      |
| Light-client header proof | Beacon (`/api/v1/light/...`)                        |
| Bridge BID lifecycle      | Beacon (`/api/v1/bridge/...`)                       |

## Code paths

* `cmd/blockchain/main.go` — single-process all-layers entry point
* `cmd/execution/main.go` — execution-only mode
* `cmd/validator/main.go` — validator client
* `blockchain/api/server.go` — beacon-side router
* `cmd/execution/main.go` — execution-side router

## Related

* [overview.md](/quantumwing/architecture/overview.md) — high-level intro
* [trust-boundaries.md](/quantumwing/architecture/trust-boundaries.md) — formal trust model
* [canonical-encoding.md](/quantumwing/architecture/canonical-encoding.md) — block-header binary format
* [../api-reference/rest-execution.md](/quantumwing/api-reference/rest-execution.md)
* [../api-reference/rest-beacon.md](/quantumwing/api-reference/rest-beacon.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/architecture/three-layer-design.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.