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

# StableDB

> 상태 커밋 분리, MemDB, mmap을 활용하여 디스크 I/O 병목을 제거하는 StableDB 아키텍처.

블록체인 성능에서 주요 병목 중 하나는 **디스크 I/O**에 있습니다. 보다 구체적으로는, 블록 실행 후 상태 데이터를 커밋하고 저장하는 작업이 핵심 병목 지점입니다. Stable은 이 문제를 해결하기 위해 `MemDB`, `VersionDB`, 메모리 매핑 파일 I/O 메커니즘 (`mmap`)와 같은 아키텍처 혁신을 도입하여 처리량을 획기적으로 향상시킵니다.

## 디스크 I/O가 병목이 되는 이유

### 상태 전환과 저장

트랜잭션 블록이 실행될 때마다 블록체인은 하나의 상태에서 다음 상태로 전환됩니다. 이 과정은 다음과 같은 두 가지 기본 단계로 나뉩니다:

1. **상태 커밋**: 트랜잭션 실행 후, 새로운 애플리케이션 상태가 커밋됩니다
2. **상태 저장**: 커밋된 상태가 디스크에 영구적으로 저장되어, 향후 접근성과 과거 기록에 검증을 가능하게 합니다.

<img className="block" src="https://mintcdn.com/stablelabs/J4B7HU7gv5jVOi-7/images/coupled-sc-ss.png?fit=max&auto=format&n=J4B7HU7gv5jVOi-7&q=85&s=6fd55cc406c071ebbae5738b6f3e213d" alt="Coupled State Commitment and Storage" width="1402" height="689" data-path="images/coupled-sc-ss.png" />

기존 아키텍처에서는, 상태 저장이 상태 커밋과 **강하게 결합되어** 있습니다. 이는 다음을 의미합니다.

* 노드는 다음 블록을 실행하기 전에 새로운 상태가 디스크에 완전히 저장될 때까지 대기해야 합니다.
* 상태 데이터는 고정된 주소를 가지지 않은 임의의 디스크 위치에 기록됩니다. 이로 인해 이후 트랜잭션 실행 시 상태 데이터를 검색하는 데 높은 레이턴시가 발생합니다.

합의 및 실행 계층이 아무리 최적화되어 있어도, 이처럼 느린 디스크 작업에 대한 의존성 때문에 시스템 전체 성능에는 상한선이 생깁니다.

## 더 높은 처리량을 위한 DB 연산 최적화

이러한 제약을 극복하기 위해 Stable은 **상태 연산의 분리** 및 **메모리 매핑 DB 최적화** 라는 두 가지 아키텍처 개선을 제안합니다.

### 1. 상태 커밋과 저장의 분리

<img className="block" src="https://mintcdn.com/stablelabs/J4B7HU7gv5jVOi-7/images/sc-ss-decouple.png?fit=max&auto=format&n=J4B7HU7gv5jVOi-7&q=85&s=a4aee154205eaabccdf0c91f1477118c" alt="Decoupled State Commitment and Storage" width="1402" height="720" data-path="images/sc-ss-decouple.png" />

첫 번째 단계는 상태 커밋과 저장을 분리하는 것입니다:

* 새로운 상태가 커밋되면, 노드는 즉시 다음 블록을 실행합니다.
* 상태를 디스크에 저장하는 작업은 비동기적으로 백그라운드에서 처리됩니다.

이러한 분리를 통해 실행은 디스크 쓰기의 레이턴시에 영향받지 않고 즉시 진행될 수 있으며, 의존성에 의해 작업이 멈추는 현상을 제거하여 결국 전체적인 성능이 향상될 수 있습니다.

### 2. `mmap` 을 통한`MemDB` 및 `VersionDB` 도입

Stable은 메모리 매핑 파일 I/O 메커니즘 (`mmap`)을 기반으로 한 이중 데이터베이스 모델을 도입하여 이를 보강합니다:

* **MemDB (메모리 DB)**:
  * 자주 접근되는 최근/활성 데이터를 저장
  * mmap을 통한 고정 주소 매핑을 사용하여 빠르고 결정론적인 조회가 가능
  * 최근 수정된 상태에 접근하는 대부분의 트랜잭션에 대해 이상적인 구조
* **VersionDB (히스토리컬 DB)**:
  * 오래된 과거 상태를 디스크에 저장
  * 자주 접근되지 않는, 오래되거나 넓은 범위의 데이터에 대한 쿼리에 최적화됨

이 설계를 통해 **핫 데이터는 빠른 메모리 기반 구조에서 제공**되고, 콜드 데이터는 느리지만 영구적인 스토리지로 오프로드됩니다. 효율을 고려하여 상태를 분류하고 `mmap` 접근을 활용함으로써, Stable은 블록 실행 중 DB의 읽기/쓰기 지연을 크게 줄일 수 있습니다.

## 예상되는 성능 개선 및 선례

이 아키텍처 최적화는 이론적인 아이디어에 그치지 않습니다. Sei 및 Cronos와 같은 고성능 블록체인들이 유사한 구조를 이미 구현하고 있으며, 메모리 매핑 DB 및 상태 커밋/저장의 분리를 통해 **전체 TPS가 최대 2배 향상**되었음을 보고했습니다.

Stable 또한 이와 유사한 성능 향상을 기대하고 있으며, 새로운 아키텍처에서는 스토리지 레이어가 더 이상 병목이 되지 않기 때문에, 합의 및 실행 성능이 디스크 연산에 의해 제한되지 않고 자유롭게 확장될 수 있게 됩니다.

## 추가 자료

더 자세한 기술 분석과 구현 내용을 보려면 다음 문서를 참고하세요:

* [ADR-065: Cosmos Store V2 Architecture](https://docs.cosmos.network/main/build/architecture/adr-065-store-v2)
* [MemIAVL: A Practical Guide](https://hackmd.io/@yihuang/rkeCvy5xh)
* [Cronos MemIAVL Node Configuration](https://docs.cronos.org/for-node-hosts/running-nodes/memiavl)
* [Sei’s DB Design Approach](https://4pillars.io/ko/articles/sei-db)
