# near/nearcore architecture

> Architecture diagram of the GitHub repository near/nearcore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/near/nearcore
- Repository: https://github.com/near/nearcore

## Overview

nearcore is the Rust reference implementation of the NEAR Protocol: node software for a sharded smart-contract blockchain. At a high level, users and applications submit transactions through RPC; nodes communicate over the peer network, obtain and process blocks and shard chunks, execute state transitions, and persist resulting chain state. The tree also identifies distinct subsystems for state sync, stateless validation, resharding, archival storage, and epoch/validator management. Only selected source relationships are evidenced in the excerpts and source index; dashed edges indicate the broader workflow where implementation-level calls were not sampled.

Main entry points: [`chain/client/src/client.rs`](https://github.com/near/nearcore/blob/master/chain/client/src/client.rs) (Client orchestration), [`chain/chain/src/chain.rs`](https://github.com/near/nearcore/blob/master/chain/chain/src/chain.rs) (Chain processing), [`chain/chunks/src/shards_manager_actor.rs`](https://github.com/near/nearcore/blob/master/chain/chunks/src/shards_manager_actor.rs) (Shard chunks), [`chain/network/src/peer_manager/peer_manager_actor.rs`](https://github.com/near/nearcore/blob/master/chain/network/src/peer_manager/peer_manager_actor.rs) (Peer management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_rpc["JSON-RPC APIs<br/>[mod.rs]"]
end

subgraph group_chain["Chain processing"]
  node_client["Client orchestration<br/>[client.rs]"]
  node_chain_core["Chain processing<br/>[chain.rs]"]
  node_chunks["Shard chunks"]
  node_chunk_cache["Chunk cache<br/>[chunk_cache.rs]"]
  node_chunk_logic["Chunk processing logic<br/>[logic.rs]"]
  node_runtime["Execution runtime<br/>[mod.rs]"]
  node_epoch["Epoch and validators"]
  node_stateless["Stateless validation<br/>[state_witness.rs]"]
  node_state_sync["State synchronization<br/>[downloader.rs]"]
end

subgraph group_network["Peer networking"]
  node_network_actor["Peer management"]
  node_peer_actor["Peer connections<br/>[peer_actor.rs]"]
  node_network_protocol["Network protocol<br/>[mod.rs]"]
end

subgraph group_state["State and storage"]
  node_store[("Persistent store<br/>[trie_store.rs]")]
  node_flat_storage[("Flat storage<br/>[storage.rs]")]
  node_trie_storage[("Trie storage<br/>[trie_storage.rs]")]
  node_cold_storage[("Cold archival storage<br/>[cold_storage.rs]")]
  node_resharding["Flat-storage resharding"]
end

subgraph group_operations["Node operations"]
  node_indexer["Indexer<br/>[fetchers.rs]"]
  node_replay["Chain replay<br/>[controller.rs]"]
  node_neard["Node process<br/>[main.rs]"]
end

node_apps(("Applications"))

node_apps -.->|"submit requests"| node_rpc
node_rpc -.->|"dispatches to"| node_client
node_client -.->|"processes chain"| node_chain_core
node_network_actor -->|"uses protocol"| node_network_protocol
node_network_actor -.->|"manages peers"| node_peer_actor
node_client -.->|"exchanges messages"| node_network_actor
node_chunks -->|"reads and updates"| node_chunk_cache
node_chunks -->|"processes chunks"| node_chunk_logic
node_chunks -->|"uses client adapter"| node_client
node_chain_core -.->|"executes transitions"| node_runtime
node_runtime -.->|"reads and writes state"| node_store
node_chain_core -.->|"uses epoch data"| node_epoch
node_client -.->|"downloads state"| node_state_sync
node_client -.->|"coordinates validation"| node_stateless
node_trie_storage -->|"reads trie data"| node_store
node_trie_storage -.->|"uses flat adapter"| node_flat_storage
node_resharding -->|"copies flat state"| node_flat_storage
node_resharding -->|"accesses runtime store"| node_runtime
node_cold_storage -->|"copies archived data"| node_store
node_indexer -.->|"reads chain data"| node_chain_core
node_replay -.->|"replays blocks"| node_chain_core
node_neard -.->|"starts node services"| node_client

click node_rpc "https://github.com/near/nearcore/blob/master/chain/jsonrpc/src/api/mod.rs"
click node_client "https://github.com/near/nearcore/blob/master/chain/client/src/client.rs"
click node_chain_core "https://github.com/near/nearcore/blob/master/chain/chain/src/chain.rs"
click node_chunks "https://github.com/near/nearcore/blob/master/chain/chunks/src/shards_manager_actor.rs"
click node_chunk_cache "https://github.com/near/nearcore/blob/master/chain/chunks/src/chunk_cache.rs"
click node_chunk_logic "https://github.com/near/nearcore/blob/master/chain/chunks/src/logic.rs"
click node_runtime "https://github.com/near/nearcore/blob/master/chain/chain/src/runtime/mod.rs"
click node_epoch "https://github.com/near/nearcore/blob/master/chain/epoch-manager/src/validator_selection.rs"
click node_stateless "https://github.com/near/nearcore/blob/master/chain/chain/src/stateless_validation/state_witness.rs"
click node_state_sync "https://github.com/near/nearcore/blob/master/chain/client/src/sync/state/downloader.rs"
click node_network_actor "https://github.com/near/nearcore/blob/master/chain/network/src/peer_manager/peer_manager_actor.rs"
click node_peer_actor "https://github.com/near/nearcore/blob/master/chain/network/src/peer/peer_actor.rs"
click node_network_protocol "https://github.com/near/nearcore/blob/master/chain/network/src/network_protocol/mod.rs"
click node_store "https://github.com/near/nearcore/blob/master/core/store/src/adapter/trie_store.rs"
click node_flat_storage "https://github.com/near/nearcore/blob/master/core/store/src/flat/storage.rs"
click node_trie_storage "https://github.com/near/nearcore/blob/master/core/store/src/trie/trie_storage.rs"
click node_cold_storage "https://github.com/near/nearcore/blob/master/core/store/src/archive/cold_storage.rs"
click node_resharding "https://github.com/near/nearcore/blob/master/chain/chain/src/resharding/flat_storage_resharder.rs"
click node_indexer "https://github.com/near/nearcore/blob/master/chain/indexer/src/streamer/fetchers.rs"
click node_replay "https://github.com/near/nearcore/blob/master/chain/replay/src/controller.rs"
click node_neard "https://github.com/near/nearcore/blob/master/neard/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rpc toneBlue
class node_client,node_chain_core,node_chunks,node_chunk_cache,node_chunk_logic,node_runtime,node_epoch,node_stateless,node_state_sync toneAmber
class node_network_actor,node_peer_actor,node_network_protocol toneMint
class node_store,node_flat_storage,node_trie_storage,node_cold_storage,node_resharding toneRose
class node_indexer,node_replay,node_neard,node_apps toneIndigo
```

## Components

### User interfaces

- [JSON-RPC APIs](https://github.com/near/nearcore/blob/master/chain/jsonrpc/src/api/mod.rs): `chain/jsonrpc/src/api/mod.rs`

### Chain processing

- [Client orchestration](https://github.com/near/nearcore/blob/master/chain/client/src/client.rs): `chain/client/src/client.rs`
- [Chain processing](https://github.com/near/nearcore/blob/master/chain/chain/src/chain.rs): `chain/chain/src/chain.rs`
- [Shard chunks](https://github.com/near/nearcore/blob/master/chain/chunks/src/shards_manager_actor.rs): `chain/chunks/src/shards_manager_actor.rs`
- [Chunk cache](https://github.com/near/nearcore/blob/master/chain/chunks/src/chunk_cache.rs): `chain/chunks/src/chunk_cache.rs`
- [Chunk processing logic](https://github.com/near/nearcore/blob/master/chain/chunks/src/logic.rs): `chain/chunks/src/logic.rs`
- [Execution runtime](https://github.com/near/nearcore/blob/master/chain/chain/src/runtime/mod.rs): `chain/chain/src/runtime/mod.rs`
- [Epoch and validators](https://github.com/near/nearcore/blob/master/chain/epoch-manager/src/validator_selection.rs): `chain/epoch-manager/src/validator_selection.rs`
- [Stateless validation](https://github.com/near/nearcore/blob/master/chain/chain/src/stateless_validation/state_witness.rs): `chain/chain/src/stateless_validation/state_witness.rs`
- [State synchronization](https://github.com/near/nearcore/blob/master/chain/client/src/sync/state/downloader.rs): `chain/client/src/sync/state/downloader.rs`

### Peer networking

- [Peer management](https://github.com/near/nearcore/blob/master/chain/network/src/peer_manager/peer_manager_actor.rs): `chain/network/src/peer_manager/peer_manager_actor.rs`
- [Peer connections](https://github.com/near/nearcore/blob/master/chain/network/src/peer/peer_actor.rs): `chain/network/src/peer/peer_actor.rs`
- [Network protocol](https://github.com/near/nearcore/blob/master/chain/network/src/network_protocol/mod.rs): `chain/network/src/network_protocol/mod.rs`

### State and storage

- [Persistent store](https://github.com/near/nearcore/blob/master/core/store/src/adapter/trie_store.rs): `core/store/src/adapter/trie_store.rs`
- [Flat storage](https://github.com/near/nearcore/blob/master/core/store/src/flat/storage.rs): `core/store/src/flat/storage.rs`
- [Trie storage](https://github.com/near/nearcore/blob/master/core/store/src/trie/trie_storage.rs): `core/store/src/trie/trie_storage.rs`
- [Cold archival storage](https://github.com/near/nearcore/blob/master/core/store/src/archive/cold_storage.rs): `core/store/src/archive/cold_storage.rs`
- [Flat-storage resharding](https://github.com/near/nearcore/blob/master/chain/chain/src/resharding/flat_storage_resharder.rs): `chain/chain/src/resharding/flat_storage_resharder.rs`

### Node operations

- [Indexer](https://github.com/near/nearcore/blob/master/chain/indexer/src/streamer/fetchers.rs): `chain/indexer/src/streamer/fetchers.rs`
- [Chain replay](https://github.com/near/nearcore/blob/master/chain/replay/src/controller.rs): `chain/replay/src/controller.rs`
- [Node process](https://github.com/near/nearcore/blob/master/neard/src/main.rs): `neard/src/main.rs`

### Other components

- **Applications**

## Connections

- Applications → JSON-RPC APIs: submit requests
- JSON-RPC APIs → Client orchestration: dispatches to
- Client orchestration → Chain processing: processes chain
- Peer management → Network protocol: uses protocol (evidence: `chain/network/src/peer_manager/peer_manager_actor.rs`)
- Peer management → Peer connections: manages peers (evidence: `chain/network/src/peer_manager/peer_manager_actor.rs`)
- Client orchestration → Peer management: exchanges messages
- Shard chunks → Chunk cache: reads and updates (evidence: `chain/chunks/src/shards_manager_actor.rs`)
- Shard chunks → Chunk processing logic: processes chunks (evidence: `chain/chunks/src/shards_manager_actor.rs`)
- Shard chunks → Client orchestration: uses client adapter (evidence: `chain/chunks/src/shards_manager_actor.rs`)
- Chain processing → Execution runtime: executes transitions
- Execution runtime → Persistent store: reads and writes state
- Chain processing → Epoch and validators: uses epoch data
- Client orchestration → State synchronization: downloads state
- Client orchestration → Stateless validation: coordinates validation
- Trie storage → Persistent store: reads trie data (evidence: `core/store/src/trie/trie_storage.rs`)
- Trie storage → Flat storage: uses flat adapter
- Flat-storage resharding → Flat storage: copies flat state (evidence: `chain/chain/src/resharding/flat_storage_resharder.rs`)
- Flat-storage resharding → Execution runtime: accesses runtime store (evidence: `chain/chain/src/resharding/flat_storage_resharder.rs`)
- Cold archival storage → Persistent store: copies archived data (evidence: `core/store/src/archive/cold_storage.rs`)
- Indexer → Chain processing: reads chain data
- Chain replay → Chain processing: replays blocks
- Node process → Client orchestration: starts node services
