# Network Overview

## Goliath Network Architecture

Goliath follows a layered architecture where write-path consensus and read-path indexing are separated for performance and reliability. This architecture is deployed on both **Goliath Mainnet** (Chain 327) and **Goliath Testnet** (Chain 8901).

This page uses canonical component names used in the platform:

* **Core Ledger Node (`ledger-core`)**
* **EVM Gateway (`evm-gateway`)**
* **Stream Fetcher (`stream-fetcher`)**
* **Observer Ingestor (`observer-ingestor`)**
* **Ledger Index DB (`ledger-index-db`)**
* **Observer REST API (`observer-rest`)**
* **Observer gRPC API (`observer-grpc`)**
* **EVM Indexer API (`evm-indexer-api`)**

## Architecture Map (ASCII)

```
+======================================================================================================+
|                                         GOLIATH ARCHITECTURE                                         |
+======================================================================================================+
| USER LAYER                                                                                           |
|                                                                                                      |
|   [ Wallets ]                     [ dApps ]                     [ Enterprise Apps ]                  |
+-----------------------------------------+----------------------------------------------------------------+
                                          |
                                          | tx submit / state reads / event subscriptions
                                          v
+======================================================================================================+
| API LAYER                                                                                            |
|                                                                                                      |
|  +-------------------------------+  +------------------------------+  +----------------------------+  |
|  | EVM Gateway                   |  | Observer REST API            |  | Observer gRPC API          |  |
|  | (evm-gateway)                 |  | (observer-rest)              |  | (observer-grpc)            |  |
|  | write + EVM-compatible reads  |  | indexed query interface      |  | stream + bulk query API    |  |
|  +---------------+---------------+  +---------------^--------------+  +--------------^-------------+  |
+------------------|----------------------------------|-------------------------------|-------------------+
                   |                                  |                               |
                   | submit tx                        | indexed history/query models   | indexed streams
                   v                                  |                               |
+======================================================================================================+
| CORE NETWORK LAYER                                                                                   |
|                                                                                                      |
|  +--------------------------------------+       gossip + consensus       +-------------------------+  |
|  | Core Ledger Node                     | <----------------------------> | Core Ledger Node       |  |
|  | (ledger-core)                        |                                | (ledger-core)          |  |
|  | - validate tx                        |                                | - order tx             |  |
|  | - execute state transitions          |                                | - finalize records     |  |
|  +--------------------+-----------------+                                +------------+------------+  |
|                       \                                                             /                |
|                        \_________ event streams + record files (canonical) ________/                 |
+-----------------------------------------------+------------------------------------------------------+
                                                |
                                                v
+======================================================================================================+
| MIRROR NODE LAYER                                                                                    |
|                                                                                                      |
|  +-----------------------------+   +-----------------------------+   +-----------------------------+ |
|  | Stream Fetcher              |-->| Observer Ingestor           |-->| Ledger Index DB            | |
|  | (stream-fetcher)            |   | (observer-ingestor)         |   | (ledger-index-db)          | |
|  | pull + verify stream files  |   | decode + normalize records  |   | canonical indexed storage  | |
|  +-----------------------------+   +--------------+--------------+   +--------------+--------------+ |
|                                                   |                                 |                |
|                                                   v                                 v                |
|                                        +---------------------+          +-------------------------+   |
|                                        | EVM Indexer API     |          | Explorer / Analytics   |   |
|                                        | (evm-indexer-api)   |          | / external services    |   |
|                                        | EVM-focused models  |          | query + dashboards     |   |
|                                        +---------------------+          +-------------------------+   |
+======================================================================================================+
```

## Core Components

### 1. Core Ledger Node (`ledger-core`)

The consensus execution engine of the network.

* Validates and orders transactions
* Executes state transitions
* Produces canonical event streams and records
* Provides finalized write-path state

### 2. EVM Gateway (`evm-gateway`)

Ethereum-compatible ingress and query interface.

* Exposes JSON-RPC for wallets and dApps
* Accepts EVM transactions and routes them to consensus
* Supports EVM toolchain compatibility

### 3. Stream Fetcher (`stream-fetcher`)

Mirror-side stream acquisition service.

* Pulls event stream and record files from consensus outputs
* Verifies integrity before ingestion
* Buffers data for deterministic processing

### 4. Observer Ingestor (`observer-ingestor`)

Canonical record ingestion pipeline.

* Parses and validates record payloads
* Normalizes entities (accounts, tx, contracts, logs, tokens)
* Writes structured data into index storage

### 5. Ledger Index DB (`ledger-index-db`)

Primary indexed data store for read APIs and analytics.

* Stores normalized historical records
* Supports high-throughput querying
* Powers explorer and programmatic read paths

### 6. Observer APIs (`observer-rest`, `observer-grpc`)

Read APIs for applications and infrastructure tooling.

* REST for standard query workflows
* gRPC for streaming and bulk query patterns
* Query indexed data without loading consensus nodes

### 7. EVM Indexer API (`evm-indexer-api`)

EVM-focused indexed query surface.

* Contract/event/log-oriented queries
* Token and account activity views
* dApp-friendly EVM read models

## End-to-End Data Flow

1. Wallets/dApps submit EVM transactions through `evm-gateway`.
2. `ledger-core` nodes validate, order, and execute transactions.
3. Consensus output is emitted as event streams and records.
4. `stream-fetcher` acquires and verifies these stream artifacts.
5. `observer-ingestor` decodes and normalizes records.
6. Data is persisted in `ledger-index-db` and exposed by observer/EVM index APIs.

## Why the Indexer Layer Matters

The indexer layer turns consensus artifacts into developer-usable data products.

* Converts low-level records into query-ready entities
* Enables historical and analytical queries at scale
* Keeps read-heavy workloads off consensus infrastructure
* Supports explorer, dashboards, and external integrations with low latency


---

# Agent Instructions: 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 current page URL with the `ask` query parameter:

```
GET https://docs.goliath.net/architecture/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.