# Krogan Architecture (Geth)
## Summary
Running full nodes today is resource-intensive, especially for state verification and storage. To scale RPC services, operators typically deploy multiple full nodes with the entire capability set—even though many requests don’t require all of those features.
Krogan proposes a trust-based architecture in which lightweight Krogan nodes serve RPC requests by syncing from a trusted full node without performing state verification. This approach substantially reduces disk usage while preserving the ability to answer most RPC requests.
## Goals & Objectives
- Reduce hardware requirements for RPC serving nodes
- Enable horizontal scaling of RPC capacity without proportional hardware investment
- Better RPC performances due to better caching and less resources used on execution
- A good testbed for some state expiry designs
Expected target:
- Less than 150GB disk space needed to run a Krogan node
## Solution Overview
### Architecture
The Krogan mode is split into 2 parallel processes:
1. Snapshot sync - reconstructs the state
2. Diff sync - heals, handle reorgs and keep up with the chain
#### Snapshot sync
Snapshot sync is similar to the regular snap sync's leaves downloading phase, except that:
- it uses JSON-RPC instead of devP2P
- it doesn't require trie proofs
- pivot is determined by the master node (current head block - 64)
Here's the overview:
#### Diff sync
In snapshot sync, the pivot moves which may invalidate some of the previous synced state. A Krogan node can perform healing by retrieving the state diffs from the master node.
A state diff object consists of:
- account changes
- storage slot changes
In case of a small reorg (<=128 blocks), a Krogan node can use the state diffs to rewind the state. For large reorgs, we need to detect it and resync from the beginning.
#### (optional) Offline snapshot export
We may also want to introduce a CLI tool where users can transfer the snapshot data from one database to another. Doing this allows for much faster syncing time compared to the snapshot sync.
#### What Krogan stores
At the end, a Krogan node would only store:
1. The latest snapshot data (~110GB)
2. Recent blocks (e.g. 2048)
### API changes
We create a new namespace called "krogan", which consists of the following endpoints:
- `krogan_getAccountRange`
- `krogan_getStorageRange`
- `krogan_getBytecodes`
- `krogan_getStateDiffs`
### Risks
1. How can we be sure that the state on Krogan node matches exactly the master node?
## Execution Plan
### Task Group 1: State
1. Implement Krogan-specific storage layer
2. Implement database accessors for Krogan data
### Task Group 2: Sync
1. Implement snapshot sync for initial sync download
2. Implement diff sync for continuous updates and reorg handling
5. Implement main Krogan sync orchestrator
7. Implement Krogan-specific sync metrics and monitoring
### Task Group 3: JSON-RPC client and server
1. Create Krogan RPC namespace
3. Implement `krogan_getAccountRange`
4. Implement `krogan_getStorageRange`
5. Implement `krogan_getBytecodes`
6. Implement `krogan_getStateDiffs`
### Task Group 4: CLI & Integration
1. Create Krogan configuration structure and flags
2. Write Krogan service registration in geth
3. Integrate Krogan sync into Ethereum handler and backend