> ## 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.

# 발생주의 평가, Harvest 및 보고

> 전략 NAV 추정, 볼트 lockedProfit 버퍼 메커니즘, harvest 배분 및 법정 회계 결산 조정.

[보고 요약 (TL;DR)](/ko/developers/financial-data#tldr) · [파트너 회계 및 보고](/ko/developers/financial-data) · [실무 회계 대사 워크스루](/ko/developers/reconciliation-guide) · [데이터 API 개요](/ko/developers/data-access) · [Scalar 레퍼런스](https://api.superearn.io/v1/docs)

발생주의 회계는 현금의 수수 시점과 무관하게 경제적 사건이 발생한 기간에 수익과 비용을 인식합니다. 기관 파트너를 위해 SuperEarn은 IFRS 및 일반기업회계기준에 부합하는 온체인 검증 증거를 제공합니다. [Conceptual Framework §1.17 (AASB)](https://standards.aasb.gov.au/node/2695#para_1-17)

## 회계 증거 기준

| 목적                    | 리소스 / 파라미터                                                                                             | 확인 내용                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| **공식 보유 잔고, 원가 및 손익** | [earnings](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings)                                 | 기본 주당순자산가치(PPS) 기준; 필요 시 추정 NAV 선택               |
| **특정 시점 잔고 스냅샷**      | [balances](https://api.superearn.io/v1/docs#tag/balances/GET/balances)                                 | 활성 운용 지분 가치와 출금 대기금의 합                           |
| **보고 자산과 PPS 대사**     | `include=reconciliation` 추가                                                                            | 경계별 보고 총자산(`reportedPositionValue`) 및 미해제 이익 조정분 |
| **전략 실시간 발생 수익 확인**   | `valuation=estimated_nav` 추가                                                                           | 추정 잔고, Harvest 보고 전 하위 전략 실시간 발생 손익 및 수익률        |
| **전략 Harvest 보고 내역**  | [harvests](https://api.superearn.io/v1/docs#tag/harvests/GET/harvests)                                 | 확정된 전략 수익·손실, 부과된 수수료 및 지갑별 배분액                  |
| **기관 고정금리 계약 이자**     | [interest](https://api.superearn.io/v1/docs#tag/institutions/GET/institutions/\{institution}/interest) | 체크포인트 기반 계약상 미수 발생 이자 원장                         |

### 2-Track 상업 정산 모델

상업적 수익 배분 계약(Revenue Sharing)을 체결한 기관 파트너의 경우, 시스템 무결성을 위해 **2-Track 분리 체계**를 운영합니다:

1. **Track 1: 온체인 Data API (총 운용 성과, Gross Yield)**:
   * 온체인 확정 블록 상태에 기반한 순수 총 운용 원장.
   * Gross PnL, 잔고, TWR 수익률을 제공하며 일체의 오프체인 비용을 임의 차감하지 않음.
   * 기업 재무상태표 작성 및 외부 회계 감사의 기준선(Single Source of Truth).
2. **Track 2: 상업적 월별 정산 명세서 (실지급액, Net Payout)**:
   * 온체인 Gross PnL을 기초로 오프체인 상업 계약 조항을 적용.
   * 성과보수율(10%) 중 파트너 배분율(50\~70%) 적용 및 오프체인 브릿지 실비(Rhino 월별 인보이스) 공제.
   * 월말 확정 데이터를 결합한 별도 정산서 승인 및 현금 지급.

## 전략 NAV 추정

기본적으로 SuperEarn은 온체인 확정 주당 가치(`valuation=pps`)를 사용합니다. 그러나 하위 전략(Morpho 대출 이자, Pendle PT 할인 수렴, RWA 실물 자산 수익 등)에서 매일 발생하는 이자를 루트 볼트 Harvest 전에 실시간으로 파악하고자 할 경우 `valuation=estimated_nav` 옵션을 사용합니다.

| 구분                            | 경계 시점 평가액                                              | 기간 성과                                                           |
| ----------------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |
| **`valuation=pps` (기본값)**     | 지분 × free funds ÷ 발행량 (내림 후 환산); 출금 대기금 합산             | 공식 PnL, 실현·미실현 분해, 기간 수익률/APY                                   |
| **보고 자산 대사**                  | 유효 locked profit을 포함한 루트 `totalAssets` 비례 배분           | `include=reconciliation`을 통한 추가 증거 (부가 대사 증빙; 잔고 및 PnL 자체는 미변경) |
| **`valuation=estimated_nav`** | 유휴 현금 + 등록 전략의 `estimatedTotalAssets` 지분 배분; 출금 대기금 합산 | 동일한 잔고/손익 필드; `return.estimated=true`                           |

```text theme={null}
추정 총자산 = 루트 보고 자산 - 보고된 전략 부채 + 총합산(하위 전략별 추정 자산)
추정 총자산 (추정 totalValue) = floor(보유 지분 * 추정 총자산 / 총 발행량) (환산) + 출금 대기금
추정 손익                     = 기말 추정 totalValue - 기초 추정 totalValue - (외부 유입 - 외부 유출)
```

**전략 NAV 운영 규칙**

* **동일 블록 조회**: 모든 하위 전략 어댑터의 상태를 동일한 확정 블록에서 일괄 조회합니다.
* **자금 유출입 시 수익률 제약**: 추정 NAV 기준의 True TWR은 외부 자금 유출입이 없는 기간을 지원합니다. 기간 중 외부 자금 이동이 발생한 경우 NAV 시점 상태 미비로 `twr_nav_flow_state_unavailable`과 함께 수익률은 `null` 처리되며, 순손익(PnL)은 검증된 현금 흐름으로 정상 산출됩니다.
* **취득원가 보존**: `valuation=estimated_nav`는 `positionValue`와 `unrealizedPnl`을 재평가하지만, 검증된 과거 `costBasis`는 변경 없이 그대로 유지합니다.

## Harvest 보고와 투자자 손익 연계

스마트 컨트랙트에서 하위 전략의 운용 수익이 투자자의 최종 손익으로 이어지는 생애주기:

| 단계                       | 스마트 컨트랙트 동작                              | 회계적 처리 및 성격                          |
| ------------------------ | ---------------------------------------- | ------------------------------------ |
| **1. 전략 운용 수익 발생**       | 루트 볼트 보고 전 하위 운용처(Venue)에서 자산 가치 증가      | 전략 NAV 추정치로 발생 수익 확인                 |
| **2. 전략 Harvest 보고**     | 키퍼가 `harvest` 트랜잭션 실행; 수익/손실이 루트 볼트에 보고됨 | Harvest 증거 확인; 성과보수에 따라 수수료 지분 발행    |
| **3. 이익 잠금 (Locked)**    | 보고된 수익이 볼트의 `lockedProfit` 버퍼로 격리됨       | 총자산은 증가하나 free funds와 PPS는 즉시 변하지 않음 |
| **4. 이익 선형 해제 (Unlock)** | `lockedProfit`이 7일에 걸쳐 선형으로 서서히 풀림       | PPS가 매일 상승하며 투자자가 기간 운용 수익을 인식       |
| **5. 출금 신청 (Redeem)**    | 사용자가 지분을 소각하고 명목 채권 생성                   | 누적된 미실현 평가이익이 실현이익으로 전환              |
| **6. 청구 대금 지급 (Claim)**  | 쿨다운 만료 후 기초 자산 현금이 지갑으로 지급됨              | 현금 수령 완료; 대차대조표상 출금 청구권 제거           |

### 두 가지 실현 기준

| 지표                        | 측정 기준                                         | 회계적 의미                                   |
| ------------------------- | --------------------------------------------- | ---------------------------------------- |
| **전략 보고 `gain` / `loss`** | 하베스트 시점에 전략 어댑터가 루트 볼트에 보고한 수익/손실             | 하위 전략 차원의 실현 운용 성과; `debtPayment`는 원금 상환 |
| **투자자 `realizedPnl`**     | 지분 출금/처분 대가에서 안분 차감된 과거 취득원가를 뺀 금액            | 투자자가 지분을 처분함으로써 장부상 확정한 실현 이익            |
| **투자자 `pnl`**             | 기말 totalValue − 기초 totalValue − 외부 유입 + 외부 유출 | 지분을 보유 중인 상태에서 발생한 평가이익을 포함한 총순손익        |

### Cooldown 원금과 정산

| 구성요소                                  | 회계적 처리                                              |
| ------------------------------------- | --------------------------------------------------- |
| **활성 운용 지분 (`positionValue`)**        | 이자 창출 자산; `costBasis`로 역사적 취득원가 추적                  |
| **출금 대기 채권 (`redemptionReceivable`)** | 이자 미발생 확정 채권; USDT와 1:1 환산되며 유동성 대기 중 명목 원금 100% 보존 |
| **프로토콜 부채 및 손실**                      | 전략 부채 및 회수 부족분은 프로토콜 자체 장부에서 관리되며 투자자 명목 청구권과 분리됨   |
| **손실 수용 정산**                          | 비상 상황에서 낮은 지급액을 수용하고 청구를 종결한 경우 차액을 지급 손실로 손익에 반영   |

### 3개 기간에 걸친 손익 변동 예시

기초 상태: 지분 100개, 원가 100, 볼트 총자산 1,000, 발행량 1,000 (1:1 환산, 수수료 및 외부 유출입 없음 가정):

| 기간 마감 시점                | 전략 보고 gain | 유효 lockedProfit | 지분 가치 / 미수금 | 투자자 `pnl` | `realizedPnl` | `unrealizedPnlChange` |
| ----------------------- | ---------: | --------------: | ----------: | --------: | ------------: | --------------------: |
| **100 보고 직후 (전액 잠김)**   |        100 |             100 |     100 / 0 |         0 |             0 |                     0 |
| **7일 해제 완료 (추가 보고 없음)** |          0 |               0 |     110 / 0 |        10 |             0 |                    10 |
| **110 전액 출금 신청 (소각)**   |          0 |               0 |     0 / 110 |         0 |            10 |                   −10 |

* 하베스트 보고 직후에는 이익이 전액 잠겨 있으므로 투자자 PnL은 0입니다.
* 7일에 걸쳐 잠금이 해제되면서 지분 가치가 110으로 상승하고 투자자는 10의 미실현이익을 인식합니다.
* 출금 신청 시 지분이 소각되면서 10의 미실현이익이 10의 실현이익으로 완벽히 치환되며, 총 관리 자산은 110으로 유지됩니다.

### 레거시 harvestReport 모드가 폐기된 이유와 대체 조회 방법

초기 레거시 프로토타입(`kaia-usdt-miniapp` 및 `/external/v2/...`)에는 하베스트 직후 발생한 `lockedProfit`이 향후 7일간 기존 지분권자에게 그대로 귀속될 것이라는 가정하에, 하베스트 시점에 이익을 전액 인식하는 `accountedBy=harvestReport` 모드가 존재했습니다.

이 방식은 다음과 같은 3가지 회계적·기술적 이유로 v1에서 \*\*공식 폐기(HTTP 410)\*\*되었습니다:

1. **하베스트 시점의 청구권 및 환금성 부재 (IFRS 자산 인식 요건 불충족)**:
   * 스마트 컨트랙트 원리상, 하베스트 직후 7일 동안의 실제 출금 가치는 `lockedProfit`을 제외한 `freeFunds`(PPS)로만 확정됩니다.
   * 만약 투자자가 하베스트 직후 지분을 출금(`redeem`)하면, 컨트랙트는 `lockedProfit`을 지급하지 않고 오직 당시의 PPS 금액만 지급합니다.
   * 출금 시 회수할 권리가 없는 미해제 금액을 홀더의 '장부 잔고'나 '실현/미실현 손익'으로 기록하는 것은 IFRS 및 GAAP의 자산/수익 인식 요건에 위배됩니다.

2. **지분 희석(Dilution) 및 유출입 왜곡**:
   * "잠금이익이 결국 현재 홀더에게 배분된다"는 가정은 "향후 7일간 제3자의 신규 입출금이 전혀 없다"는 비현실적 전제를 필요로 합니다.
   * 하베스트 2일 뒤 신규 자금이 대규모로 유입되면 신규 투자자가 발행 당시의 PPS로 지분을 취득하고, 남은 5일간 해제되는 이익을 신규 투자자와 나눠 갖게 되어 기존 홀더의 몫이 희석됩니다.
   * 따라서 하베스트 블록 시점에 이익을 100% 홀더에게 귀속시키는 것은 실제 온체인 자금 흐름과 모순됩니다.

3. **원장 통산 불변식(Lifetime Ledger Invariant) 붕괴**:
   * 감사 통과의 핵심 항등식인 다음 관계는 모든 입출금이 실제 온체인 현금 및 PPS로 집행된다는 사실에 기반합니다:
     ```text theme={null}
     총누적손익 = 기말 totalValue + 총출금액 - 총예치액
     ```
   * 장부 잔고만 locked profit을 더해 높여 놓으면, 실제 출금 시점에 실제 현금 수령액과의 차이로 인해 대규모 \*\*허위 처분손실(False Disposal Loss)\*\*이 장부에 발생하여 재무제표가 왜곡됩니다.

#### 필요한 정보별 공식 조회 방법

v1은 가상의 미해제 이익을 공식 장부에 섞지 않고, 목적에 따라 명확히 분리된 엔드포인트를 제공합니다:

| 필요한 정보                     | 호출 엔드포인트 / 파라미터                                  | 반환 내용 및 성격                                                                  |
| :------------------------- | :----------------------------------------------- | :-------------------------------------------------------------------------- |
| **공식 홀더 잔고 및 기간 손익**       | `GET /v1/earnings` (기본값 `valuation=pps`)         | 온체인 환금 가능한 확정 감사 기준 장부 잔고 및 손익                                              |
| **컨트랙트 총자산 및 잠금이익 대사**     | `GET /v1/earnings?include=reconciliation`        | 공식 잔고는 유지하되, `reportedAssets`, `lockedProfit`, `rounding` 차이 내역을 감사 증빙으로 첨부 |
| **전략별 하베스트 보고 내역 및 지갑 배분** | `GET /v1/harvests?account=...&start=...&end=...` | 블록별 확정 하베스트 이벤트, 순수익, 부과된 수수료 및 보고 블록 지분율에 따른 단순 배분액 확인                     |
| **하베스트 보고 전 실시간 발생 수익**    | `GET /v1/earnings?valuation=estimated_nav`       | 루트 볼트 보고 이전의 하위 운용처(Morpho 대출, Pendle PT 만기 수렴 등)의 실시간 가치를 경제적 실질로 확인       |

### 경계 평가 수식

지원되는 SuperVault 루트 볼트(`apiVersion: "0.4.6"`)의 경계 평가는 3단계로 엄밀하게 산출됩니다:

**1. 선형 이익 잠금 해제**

```text theme={null}
해제된 이익        = floor(min(경과 초 * 감소율, 10^18) * 보관된 Locked Profit / 10^18)
유효 Locked Profit = 보관된 Locked Profit - 해제된 이익
```

**2. Free Funds 및 활성 지분 평가**

```text theme={null}
Free Funds                  = 보고된 총자산 - 유효 Locked Profit
활성 지분 가치 (positionValue) = floor(보유 지분 * Free Funds / 총 발행량) (환산)
총 평가 자산 (totalValue)   = 활성 지분 가치 + 출금 대기금
```

**3. 보고 자산 대사 (`include=reconciliation`)**

```text theme={null}
보고 지분 가치 = 활성 지분 가치 + 배분된 Locked Profit + 반올림 조정액
```

* **배분된 Locked Profit**: `floor(보유 지분 * 유효 Locked Profit / 총 발행량) (환산)`.
* **반올림 조정액**: 보고 총자산의 단순 환산액(`floor(보유 지분 * 보고 총자산 / 총 발행량) (환산)`)과 (활성 지분 가치 + 배분된 Locked Profit)의 합 사이의 정수 내림 차이.

> \[!NOTE]
> **평가 모드(Valuation Mode)와 대사 증거의 구분**: Data API가 지원하는 공식 평가 모드는 `valuation=pps`(기본 공식 장부)와 `valuation=estimated_nav`(하위 전략 실시간 발생 수익 추정)의 2가지뿐입니다. `include=reconciliation`은 별도의 valuation 모드가 아니며, `valuation=pps` 조회 시 공식 PPS 장부 가치와 컨트랙트 보고 총자산 사이의 차이 내역(locked profit 버퍼 및 정수 절사 반올림 조정액)을 감사용 증거로 제공하는 **부가 대사(Enrichment) 기능**입니다.

## Harvest 배분

개별 보고 건에 대해 선택적 지갑 배분은 \*\*보고 블록 종료 시점(end-of-report-block)\*\*의 지분율을 사용합니다:

```text theme={null}
지갑별 Harvest 배분액 = floor(지갑 보유 지분 * 순 보고 수익 / 총 발행량) (환산)
```

* **순 보고 수익**: 기초 토큰 단위의 총 보고 이익(gross gain) − 총 보고 손실(gross loss).
* **보고 블록 지분율**: 보고 트랜잭션이 포함된 블록의 모든 처리가 완료된 직후의 지갑 지분과 총 발행량.
* **부과 수수료**: `min(총 이익, 운용보수 + 성과보수 + 전략보수)`; 이익이 0이면 수수료도 0.

## 회계 결산 워크플로우

감사 수준의 월별 또는 연간 법정 결산 절차:

| 단계        | 처리                                                                               |
| --------- | -------------------------------------------------------------------------------- |
| **1. 정의** | 자산, 보고 범위(지갑 vs 볼트 전체), 조회 기간, 지역 시간대(`Asia/Seoul`) 선택                           |
| **2. 조회** | `GET /v1/earnings`로 전체 기간 또는 일별 행 조회; 보고 자산 감사가 필요하면 `include=reconciliation` 추가 |
| **3. 검증** | `quality.status`가 `complete`인지 확인하고 대사 잔여값(`residual = 0`) 검산                    |
| **4. 대사** | `기말 totalValue = 기초 totalValue + 외부 유입 - 외부 유출 + 기간 손익` 일치 확인                    |
| **5. 확정** | API 응답 원본, 쿼리 파라미터, 확정 블록 해시 및 적용 정책 버전을 재무 원장에 동결 보존                            |

> \[!TIP]
> **실무 워크스루**: 실제 계정 기준의 curl 호출 및 실측 수치 대사 과정은 [파트너 실무 회계 대사 워크스루](/ko/developers/reconciliation-guide)를 참고하십시오.

## 추가 인식·측정

| 추가 영역              | 필요 증거                                                                                                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **어댑터 조회 범위 외 수익** | 운용처 포지션 증명, 권리 관계, 측정 시점 및 평가 근거                                                                                                                                                                                               |
| **재무제표 장부금액 조정**   | 금융자산 분류, 손상 평가, 외화 환산                                                                                                                                                                                                          |
| **법정 재무제표 작성**     | [IFRS 9](https://www.ifrs.org/issued-standards/list-of-standards/ifrs-9-financial-instruments/) (금융상품 분류·측정) 및 [IFRS 13](https://www.ifrs.org/issued-standards/list-of-standards/ifrs-13-fair-value-measurement/) (공정가치 측정) 적용 |

온체인 현금 흐름의 변동 없이 장부금액 조정을 적용하는 경우, 다음과 같이 대사합니다:

```text theme={null}
조정된 잔고 = 원장 잔고 + 장부금액 조정액
조정된 손익 = 원장 손익 + (기말 조정액 - 기초 조정액)
```