> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 저장소 아키텍처

## 목적 및 범위

이 문서는 StableNet이 블록체인 상태, 블록, 영수증을 유지하기 위해 사용하는 영구 및 메모리 저장소 아키텍처를 설명합니다.\
고수준 StateDB 캐싱 레이어부터 원시 데이터베이스 백엔드까지의 계층형 저장소 구조를 다루며, Merkle Patricia Trie, 캐싱 전략, 스냅샷 시스템을 포함합니다.

상태 전환 및 EVM 실행에 대한 내용은 State Transitions and Gas를 참고하세요.\
블록체인 관리 및 정식 체인 유지에 대한 내용은 Blockchain Management를 참고하세요.\
고대 저장소와 데이터 라이프사이클에 대한 상세 설명은 Ancient Store and Data Lifecycle을 참고하세요.

## 저장소 레이어 계층

StableNet의 저장소 아키텍처는 각기 다른 추상화 수준과 성능 최적화를 제공하는 여러 레이어로 구성됩니다.

## StateDB: 상태 캐싱 레이어

StateDB는 블록체인 상태를 조회하고 수정하기 위한 핵심 인터페이스입니다.\
저널링 기반의 원자성 보장과 스냅샷을 이용한 롤백 기능을 제공하는 고급 캐싱 레이어입니다.

### StateDB 구조

| Component              | Type                                        | Purpose            |
| ---------------------- | ------------------------------------------- | ------------------ |
| `db`                   | `Database`                                  | Trie 데이터베이스 인터페이스  |
| `trie`                 | `Trie`                                      | 계정 트라이 루트          |
| `snaps`                | `*snapshot.Tree`                            | 빠른 접근을 위한 스냅샷 트리   |
| `snap`                 | `snapshot.Snapshot`                         | 현재 활성 스냅샷          |
| `stateObjects`         | `map[common.Address]*stateObject`           | 활성 계정 객체           |
| `stateObjectsPending`  | `map[common.Address]struct{}`               | 최종화되었으나 커밋되지 않은 객체 |
| `stateObjectsDirty`    | `map[common.Address]struct{}`               | 실행 중 수정된 객체        |
| `stateObjectsDestruct` | `map[common.Address]*types.StateAccount`    | 소멸된 객체             |
| `accounts`             | `map[common.Hash][]byte`                    | 수정된 계정 데이터         |
| `storages`             | `map[common.Hash]map[common.Hash][]byte`    | 수정된 저장소 슬롯         |
| `accountsOrigin`       | `map[common.Address][]byte`                 | 원본 계정 값            |
| `storagesOrigin`       | `map[common.Address]map[common.Hash][]byte` | 원본 저장소 값           |
| `journal`              | `*journal`                                  | 상태 변경 로그           |
| `validRevisions`       | `[]revision`                                | 스냅샷 리비전            |
| `refund`               | `uint64`                                    | 가스 환불 카운터          |

### 상태 객체 관리

각 계정은 기본 `types.StateAccount`를 래핑한 `stateObject`로 관리되며, 실행 중 변경 사항을 추적합니다.

| Field            | Type                  | Purpose            |
| ---------------- | --------------------- | ------------------ |
| `address`        | `common.Address`      | 계정 주소              |
| `addrHash`       | `common.Hash`         | Keccak256(address) |
| `origin`         | `*types.StateAccount` | 원본 계정 데이터          |
| `data`           | `types.StateAccount`  | 현재 계정 데이터          |
| `trie`           | `Trie`                | 저장소 트라이            |
| `code`           | `Code`                | 컨트랙트 바이트코드         |
| `originStorage`  | `Storage`             | 원본 저장소             |
| `pendingStorage` | `Storage`             | 커밋 대기 저장소          |
| `dirtyStorage`   | `Storage`             | 실행 중 변경된 저장소       |
| `dirtyCode`      | `bool`                | 코드 변경 여부           |
| `selfDestructed` | `bool`                | 소멸 표시              |
| `deleted`        | `bool`                | 삭제 표시              |
| `created`        | `bool`                | 현재 트랜잭션에서 생성       |

### 저널링 및 스냅샷

StateDB는 모든 상태 변경을 저널에 기록하여 롤백 가능성을 보장합니다.\
각 저널 항목은 `revert()` 메서드를 구현하며 다음과 같은 변경 유형을 포함합니다.

* `balanceChange`
* `nonceChange`
* `storageChange`
* `codeChange`
* `extraChange`
* `createObjectChange`
* `selfDestructChange`
* `touchChange`
* `addLogChange`

## Merkle Patricia Trie 구현

Merkle Patricia Trie(MPT)는 상태를 저장하는 핵심 암호화 데이터 구조입니다.\
StableNet은 해시 기반 스키마와 경로 기반 스키마를 모두 지원합니다.

### Trie 노드 타입

| Node Type   | Purpose   | Structure                |
| ----------- | --------- | ------------------------ |
| `fullNode`  | 16개 자식 분기 | `Children [17]node`      |
| `shortNode` | 경로 압축     | `Key []byte`, `Val node` |
| `valueNode` | 리프 값      | `[]byte`                 |
| `hashNode`  | 해시 참조     | `[]byte`                 |

## 저장소 스키마: Hash vs Path

StableNet은 두 가지 trie 저장 방식을 지원합니다.

| Scheme      | Key Format | Purpose       |
| ----------- | ---------- | ------------- |
| Hash Scheme | 노드 해시      | 콘텐츠 주소 기반     |
| Path Scheme | 트라이 경로     | 히스토리 및 프루닝 지원 |

경로 스키마는 상태 히스토리, 효율적인 프루닝, 과거 상태 조회를 지원합니다.\
해시 스키마는 단순하지만 히스토리를 내장하지 않습니다.

## BlockChain 캐싱 전략

BlockChain은 다수의 LRU 캐시를 사용해 데이터베이스 접근을 최소화합니다.

| Cache         | Size | Purpose    |
| ------------- | ---- | ---------- |
| bodyCache     | 256  | 블록 본문      |
| blockCache    | 256  | 전체 블록      |
| receiptsCache | 32   | 영수증        |
| txLookupCache | 1024 | 트랜잭션 조회    |
| headerCache   | 512  | 블록 헤더      |
| tdCache       | 1024 | 총 난이도      |
| numberCache   | 2048 | 해시 → 블록 번호 |

## 스냅샷 시스템

스냅샷은 상태 트라이를 순회하지 않고 계정과 저장소에 빠르게 접근하기 위한 평면화된 뷰를 제공합니다.

### 스냅샷 레이어

| Layer       | Purpose | Storage |
| ----------- | ------- | ------- |
| `difflayer` | 최근 변경   | 메모리     |
| `disklayer` | 기준 상태   | 디스크     |

스냅샷 접근 순서는 diff → disk → trie 폴백입니다.

### 스냅샷 구성

| Field             | Default | Purpose       |
| ----------------- | ------- | ------------- |
| `SnapshotLimit`   | 256MB   | 스냅샷 캐시        |
| `SnapshotNoBuild` | false   | 백그라운드 생성 비활성화 |
| `SnapshotWait`    | true    | 시작 시 대기       |

## 상태 커밋 및 최종화

상태 변경은 수정 → 최종화 → 트라이 업데이트 → 커밋 단계를 거칩니다.\
최종 결과는 새로운 상태 루트 해시로 반환됩니다.

## 원시 데이터베이스 및 고대 저장소

저수준에서는 키-값 데이터베이스를 사용하며, 오래된 데이터는 고대 저장소로 이동됩니다.

### 고대 저장소 특징

* 데이터베이스 크기 감소
* 과거 데이터의 빠른 순차 접근
* 활성 DB 프루닝 가능
* Era1 아카이브 생성 지원

## 캐시 구성 요약

| Configuration        | Default | Purpose       |
| -------------------- | ------- | ------------- |
| `TrieCleanLimit`     | 256MB   | Clean trie 캐시 |
| `TrieDirtyLimit`     | 256MB   | Dirty trie 캐시 |
| `TrieTimeLimit`      | 5분      | 플러시 지연        |
| `SnapshotLimit`      | 256MB   | 스냅샷 캐시        |
| `StateHistory`       | 0       | 상태 히스토리       |
| `bodyCacheLimit`     | 256     | 블록 본문         |
| `blockCacheLimit`    | 256     | 전체 블록         |
| `receiptsCacheLimit` | 32      | 영수증           |
| `txLookupCacheLimit` | 1024    | 트랜잭션 조회       |