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

# 핵심 컴포넌트

> SuperEarn 아키텍처와 통합 지점 개요

## 1. 아키텍처 한눈에 보기

SuperEarn은 Kaia 네이티브 스테이블코인 포트폴리오로, Kaia DeFi 전략과 원격 체인(Ethereum 등) 전략에 자금을 배분한 뒤 다시 하나의 수익형 토큰 **EarnUSDT**(Kaia)로 집계합니다.

통합 관점에서 보면:

* 모든 입·출금은 **Kaia**에서 일어납니다.
* 사용자·프로토콜은 글로벌 포트폴리오 지분을 나타내는 **EarnUSDT shares**를 보유합니다.
* 크로스체인 라우팅·브릿징·정산은 CCIP 기반 레이어 **Runespear**가 내부에서 처리합니다.

각 체인별 볼트는 순수 로컬 상태머신이며, Runespear가 보수적 멀티체인 회계를 유지해 시간이 지나며 일관성 있게 맞춥니다.

***

## 1.1 Kaia (오리진 체인)

Kaia 온체인 시스템은 세 레이어로 구성됩니다.

### CooldownVault (입·출금 풀)

* 사용자/통합 프로토콜은 **SuperEarnRouter**를 통해 Kaia **USDT**를 예치합니다. **CooldownVault** 자체에는 직접 입·출금 엔트리가 없습니다.
* CooldownVault는:
  * 라우터와 Super Vault flow에서 사용하는 intermediate shares로 USDT를 래핑합니다.
  * 짧은 출금 대기와 손실 한도를 적용합니다.
  * 느리거나 지연 유동성 전략(RWA 등)을 위한 유동성 버퍼 역할을 합니다.

### Super Vault (Kaia 집계 볼트)

* 유동성이 모이면 CooldownVault가 자금을 Kaia의 **Super Vault**로 보냅니다.
* Super Vault는:
  * CooldownVault 자금을 집계합니다.
  * 자본을 Kaia 네이티브 전략(RWA, 대출 등)과 포트폴리오의 크로스체인 비중 사이에서 배분합니다.
  * Kaia 측 배분이 포트폴리오 정책·리스크 한도에 맞도록 유지합니다.

EarnUSDT는 이 집계된 Super Vault 포트폴리오의 지분입니다.

### OriginVault (Kaia 크로스체인 허브, ERC‑7540 유사)

* 멀티체인 비중을 위해 Super Vault는 Kaia의 **OriginVault**(ERC‑7540 유사 비동기 볼트)에 예치합니다.
* OriginVault는:
  * 원격 체인용으로 할당된 USDT를 보관합니다.
  * 크로스체인 비중의 비동기 예치·출금 요청을 관리합니다.
  * 큐에 쌓인 크로스체인 예치·출금을 유지합니다.
  * MessageAgent+어댑터를 통한 Runespear 메시징 레이어와만 통신하며 브릿지와 직접 대화하지 않습니다.

통합 시 OriginVault와 직접 상호작용하지 않습니다. 표면은 Kaia의 **USDT ↔ EarnUSDT**(라우터+Cooldown/Super Vault)입니다.

***

## 1.2 원격 체인 (예: Ethereum)

원격 체인마다 단일 집계 볼트가 있습니다.

### RemoteVault

* **RemoteVault**는 Kaia에서 브릿지된 스테이블코인(USDT/USDC)을 받습니다.
* RemoteVault는:
  * 출금용 소량 버퍼를 유지합니다.
  * 로컬 라우터를 통해 화이트리스트된 원격 전략(대출, 유동성 볼트, RWA 등)에 배치합니다.
  * 원격 전략에 자체 쿨다운이 있을 때 **미이행 출금액**을 추적합니다.
  * Runespear를 통해 상태(totalAssets, idleAssets, 미이행 출금, 타임스탬프)를 보고해 OriginVault·Super Vault가 보수적으로 `totalAssets()`를 계산하도록 합니다.

원격에서 발생한 수익은 Kaia의 EarnUSDT 지분 가격에 반영됩니다.

***

## 1.3 크로스체인 조정: Runespear

**Runespear**는 Chainlink CCIP와 자산 전송용 브릿지 제공업체 위에 구축된 SuperEarn의 “관제탑”입니다.

크로스체인 스택은 네 레이어로 나뉩니다:

1. **Vaults (OriginVault, RemoteVault)** – 비즈니스 로직
2. **MessageAgent (SuperEarnMessageAgent)** – 라우팅 로직
3. **CrosschainAdapter** – 인프라·브릿지 회계
4. **Runespear / CCIP + 브릿지** – 전송(메시지 + 토큰)

핵심 아이디어:

* **볼트는 체인별 로컬 상태머신**
  * 직접 크로스체인 호출 없음.
  * 로컬 회계·큐만 처리.
* **MessageAgent (SuperEarnMessageAgent)**
  * 비즈니스 페이로드 인코딩/디코딩.
  * 볼트와 어댑터 사이 명령 라우팅.
  * 볼트 변경 없이 교체/업그레이드 가능.
* **CrosschainAdapter + BridgeAccountant**
  * 모든 CCIP + 브릿지 동작 처리.
  * 논스, 이동 중 자산, “메시지 경로”와 “브릿지 경로” 중첩을 추적.
  * **보편적 상태 piggybacking** 구현: 모든 CCIP 메시지가 동일 타임스탬프의 전체 StateSnapshot(볼트 + 브릿지 상태)을 실어 중복 계산을 방지하고 회계가 자동 수렴.
* **Runespear / CCIP + 브릿지**
  * 외부 전송 레이어.
  * 메시지·브릿지 전송이 어떤 순서로 와도 어댑터 로직과 스냅샷으로 `totalAssets()`를 일관되게 유지.

***

## 2. 스마트컨트랙트 (통합 지점)

프로토콜 통합 관점에서 주로 다루는 것은 두 가지입니다:

* **쓰기 경로:** Kaia의 SuperEarn 컨트랙트(USDT ↔ EarnUSDT)
* **읽기 경로:** SuperEarn이 지원하는 공개 backend 데이터 API와 dashboard 표면. indexed 온체인/오프체인 처리(processing)로 구동.

### 2.1 사용자 플로우(Kaia)

일반적으로 앱/래퍼가 호출하는 컨트랙트:

* **USDT (Kaia)** — 기본 ERC‑20 스테이블코인

* **EarnUSDT shares**
  * Super Vault 포트폴리오에 대한 비례 청구권을 나타내는 수익형 토큰.
  * 지분 가격 모델: 잔액은 고정, 수익이 쌓이면 지분가치 상승.

* **SuperEarnRouter** — 예치·출금 편의 컨트랙트
  * `deposit(superVault, amount, minSharesOut)` — USDT → EarnUSDT
  * `previewDeposit(superVault, amount)` — 예상 지분
  * `previewRedeem(superVault, shares)` — 예상 USDT
  * `redeem(superVault, shares, receiver, minAssetsOut)` — 큐 기반 출금 시작

라우터가 **CooldownVault → Super Vault** 내부 흐름을 관리하므로 직접 조합할 필요가 없습니다.

> 모든 사용자 플로우는 Kaia USDT와 EarnUSDT Super Vault 주소로 **`SuperEarnRouter`를 통해 예치/리딤**해야 합니다. **CooldownVault는 직접 입·출금을 받지 않습니다.**

***

### 2.2 Kaia 집계 볼트

직접 호출할 일은 드물지만 EarnUSDT 동작을 이해하는 데 필요합니다.

* **CooldownVault**
  * (라우터 전용) 입·출금 풀
    * 사용자 USDT 예치는 `SuperEarnRouter`를 통해 도착.
    * Router가 Super Vault share flow를 완료하기 전에 USDT를 CooldownVault shares로 래핑.
  * 출금 쿨다운·손실 한도 적용.
  * 느린/지연 유동성 전략(RWA 등)과 연결될 때 버퍼 역할.

* **Super Vault (Kaia 집계 볼트)**
  * CooldownVault에서 자본을 수령.
  * 배분 대상:
    * Kaia 네이티브 DeFi 전략
    * 멀티체인 노출을 위한 OriginVault
  * “Kaia의 포트폴리오 두뇌”로 생각하면 됩니다. EarnUSDT는 이 집계 포트폴리오의 지분입니다.

***

### 2.3 크로스체인 볼트 (Origin / Remote)

EarnUSDT 포트폴리오의 백엔드를 구성합니다.

* **OriginVault (Kaia, ERC‑7540 유사)**
  * 크로스체인 허브:
    * 원격 전략에 배정된 Kaia 측 USDT를 보유.
    * 비동기 리딤션(요청 → 실행 → 클레임) 처리.
    * MessageAgent + 어댑터를 통한 Runespear 메시징 스택과만 통신.

* **RemoteVault (예: Ethereum)**
  * OriginVault로부터 브릿지된 자산을 수령.
  * 로컬 라우터로 원격 전략(대출, 유동성 볼트, RWA 등)에 투자.
  * `totalAssets`, `idleAssets`, 미이행 출금액을 상태 스냅샷으로 OriginVault에 보고.

Kaia 통합 시 이 볼트를 직접 호출할 일은 없으며, EarnUSDT 지분 가격·멀티체인 수익 흐름에 영향을 주는 내부 구성 요소입니다.

***

### 2.4 Runespear & 메시징 레이어 (내부)

코어 레포의 `v2/messaging`, `v2/core/crosschain`에 있으며, 공개 통합 지면은 아니지만 로그·런북·감사에서 보게 됩니다.

* **SuperEarnMessageAgent** — 볼트와 어댑터 사이 라우팅
* **CrosschainAdapter** — CCIP + 브릿지 실행, 자산/메시지 정합 관리
* **BridgeAccountant** — 이동 중 자산 추적, 메시지/브릿지 경로 중첩 조정
* **StateSnapshot** — 모든 CCIP 메시지에 실리는 전체 상태(볼트/브릿지) 캡처

***

## 3. 데이터 액세스

읽기는 raw 컨트랙트 상태를 스크래핑하기보다 SuperEarn의 \*\*지원되는 read 표면(supported read surfaces)\*\*을 사용합니다.

오늘 기준으로는 보통 다음을 의미합니다.

* 사람이 읽을 protocol 정보를 위한 공개 docs와 dashboard
* 제품 표면이 사용하는 지원되는 backend 데이터 API와 processed view
* 그 API 뒤에 있는 indexed 온체인 데이터

정확한 공개 API 표면은 고수준 protocol 아키텍처보다 빠르게 변합니다. endpoint별 예시는 별도 developer integration 문서에서 유지하세요.

***

## 4. 통합 팁

* **예치/리딤은 항상 라우터**: `SuperEarnRouter`를 통해 USDT ↔ EarnUSDT를 수행합니다.
* **쿨다운 확인**: 쿨다운이 있는 출금 큐 모델이므로 예상 시간을 UI에 표시하세요.
* **지분 가격 모델**: EarnUSDT는 리베이스되지 않으므로 잔액은 그대로, 지분 가치가 오릅니다. 미리보기 함수로 예상 값을 노출하세요.
* **멀티체인 안전성**: Runespear 스냅샷으로 회계가 보수적으로 유지되므로, 짧은 구간 동안 잔액이 다소 보수적으로 보일 수 있습니다.
* **주요 주소**: USDT, EarnUSDT, SuperEarnRouter, CooldownVault, Super Vault, OriginVault, RemoteVault 주소는 `smart-contracts.mdx`를 참고하세요.