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

# Valuation, harvest and accrual reporting

> Strategy NAV estimation, vault lockedProfit buffer mechanics, harvest allocations, and statutory period-close adjustments.

[Reporting TL;DR](/en/developers/financial-data#tldr) · [Partner accounting](/en/developers/financial-data) · [Reconciliation walkthrough](/en/developers/reconciliation-guide) · [Data API overview](/en/developers/data-access) · [Scalar reference](https://api.superearn.io/v1/docs)

Accrual accounting records economic effects in the periods in which they occur, regardless of when cash settlement takes place. For institutional partners, SuperEarn provides verified on-chain evidence to support accrual accounting under corporate standards (such as IFRS and US GAAP). [Conceptual Framework §1.17 (AASB)](https://standards.aasb.gov.au/node/2695#para_1-17)

## Choose the evidence

| Need                                  | Resource / Parameter                                                                                   | Read                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **Canonical holdings, cost, and PnL** | [earnings](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings)                                 | Share price (PPS) valuation by default; select estimated NAV when needed |
| **Instantaneous balance snapshot**    | [balances](https://api.superearn.io/v1/docs#tag/balances/GET/balances)                                 | Active position value plus redemption receivables                        |
| **Reconcile reported assets vs PPS**  | Add `include=reconciliation`                                                                           | Boundary `reportedPositionValue` and locked-profit adjustment components |
| **Inspect venue strategy accruals**   | Add `valuation=estimated_nav`                                                                          | Estimated balances, pre-harvest venue earnings, and period returns       |
| **Explain strategy report events**    | [harvests](https://api.superearn.io/v1/docs#tag/harvests/GET/harvests)                                 | Confirmed gain, loss, assessed fees, and optional wallet allocation      |
| **Fixed-rate institutional interest** | [interest](https://api.superearn.io/v1/docs#tag/institutions/GET/institutions/\{institution}/interest) | Contractual interest ledger with checkpoint coverage                     |

### The 2-track settlement model

For institutional partners with commercial revenue-sharing agreements, reporting follows a strict **2-track separation**:

1. **Track 1: On-Chain Data API (Gross Yield)**:
   * Reflects pure, unadulterated on-chain vault operations.
   * Provides canonical Gross PnL, holdings, and time-weighted returns.
   * Serves as the immutable single source of truth for corporate balance sheet valuation and financial audits.
2. **Track 2: Commercial Settlement Statement (Net Payout)**:
   * Off-chain commercial calculation applied to the API Gross PnL.
   * Applies agreed contractual terms: performance fee sharing (e.g. 10% fee with 50\~70% partner share) and deductions for off-chain expenses (such as monthly Rhino bridge invoices).
   * Produced as a monthly settlement statement for cash disbursement.

## Strategy NAV estimate

By default, SuperEarn uses `valuation=pps` (the on-chain share value). However, when underlying strategies (such as Morpho lending markets, Pendle PT discount accretion, or tokenized RWA yield) accumulate interest between root harvest transactions, partners can inspect real-time venue accruals by setting `valuation=estimated_nav`.

| View                              | Boundary value                                                                                | Period result                                                                                    |
| --------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **`valuation=pps` (default)**     | Shares × free funds ÷ supply, floored once, then converted; add pending claims                | Canonical PnL, realized/unrealized decomposition, and period return/APY                          |
| **Reported-asset reconciliation** | Pro-rata root `totalAssets`, including effective locked profit                                | Additional evidence through `include=reconciliation` (enrichment; does not alter balance or PnL) |
| **`valuation=estimated_nav`**     | Idle + registered strategies' `estimatedTotalAssets`, allocated to shares; add pending claims | Same balance/earnings fields; `return.estimated=true`                                            |

```text theme={null}
Estimated Total Assets        = Root Reported Assets - Reported Strategy Debt + Sum(Strategy Estimated Assets)
Estimated Total Value         = floor(Held Shares * Estimated Total Assets / Total Supply) (converted) + Redemption Receivables
Estimated PnL                 = Ending Estimated Total Value - Beginning Estimated Total Value - (Inflows - Outflows)
```

**Operational rules for Strategy NAV**

* **Same-block reads**: NAV estimation uses exact same-block queries across all underlying venue adapters.
* **Availability with flows**: True TWR under estimated NAV supports periods without external cash flows. If an external flow occurs during the period, NAV return rates are returned as `null` with `twr_nav_flow_state_unavailable`, while monetary cash flows and estimated PnL remain available.
* **Cost basis preservation**: Setting `valuation=estimated_nav` revalues `positionValue` and `unrealizedPnl`, but retains the exact same historical `costBasis`.

## Harvest to investor earnings

To understand how underlying protocol yields translate into investor earnings, follow the lifecycle across smart contract layers:

| Stage                          | Smart contract event                                           | Financial reporting action                                        |
| ------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------- |
| **1. Strategy yield accrues**  | Assets increase at venue (Morpho, Pendle) prior to root report | Track accrued yield via Strategy NAV estimates                    |
| **2. Strategy harvest report** | Keeper executes `harvest`; profit/loss reported to root vault  | Harvest evidence recorded; performance fees mint fee shares       |
| **3. Profit locked**           | Reported profit quarantined in vault `lockedProfit` buffer     | Total assets rise, but free funds and PPS do not jump immediately |
| **4. Linear unlock**           | `lockedProfit` decays linearly over 7 days                     | PPS rises daily; investors recognize period earnings              |
| **5. Redemption**              | User burns shares for nominal claim                            | Accumulated gain shifts from unrealized PnL to realized PnL       |
| **6. Claim payment**           | Cooldown expires; underlying cash paid to wallet               | Cash received; nominal receivable eliminated from balance sheet   |

### Two realization measures

| Measure                             | Basis                                                        | Interpretation                                                           |
| ----------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **Strategy report `gain` / `loss`** | Reported by strategy adapter to root vault during `harvest`  | Realized earnings at the strategy level; `debtPayment` returns principal |
| **Investor `realizedPnl`**          | Redemption consideration less allocated acquisition cost     | Cash profit realized by the investor upon disposing of vault shares      |
| **Investor `pnl`**                  | Closing totalValue − opening totalValue − inflows + outflows | Total net economic profit, including paper gains on active shares        |

### Cooldown principal and settlement

| Component                                               | Accounting treatment                                                                                                        |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Active investment (`positionValue`)**                 | Earning asset valued under PPS or estimated NAV; `costBasis` tracks remaining cost                                          |
| **Cooldown nominal principal (`redemptionReceivable`)** | Non-earning receivable. Conversion remains 1:1; retains nominal value while awaiting liquidity                              |
| **Protocol debt and shortfall**                         | Strategy shortfalls and protocol debt are tracked in the protocol ledger separately from investor nominal receivables       |
| **Accepted claim loss**                                 | If an emergency settlement occurs at an accepted lower payout, the difference is recorded as a payment loss in investor PnL |

### Example across three periods

Consider a wallet starting with 100 shares and cost 100 in a vault with 1,000 root assets and 1,000 supply (1:1 conversion, no external flows):

| Period closes after                   | Strategy report gain | Effective lock | Position / pending claim | Investor `pnl` | `realizedPnl` | `unrealizedPnlChange` |
| ------------------------------------- | -------------------: | -------------: | -----------------------: | -------------: | ------------: | --------------------: |
| **Report of 100; fully locked**       |                  100 |            100 |                  100 / 0 |              0 |             0 |                     0 |
| **Full release; no new report**       |                    0 |              0 |                  110 / 0 |             10 |             0 |                    10 |
| **Redeem into verified claim of 110** |                    0 |              0 |                  0 / 110 |              0 |            10 |                   −10 |

* When the harvest occurs, profit is fully locked; investor PnL is 0.
* Over the 7-day degradation window, profit unlocks; investor recognizes +10 in unrealized PnL.
* When shares are redeemed, the +10 unrealized gain shifts into +10 realized PnL; net PnL is 0.

### Why legacy harvestReport is retired in v1

In earlier prototypes (`kaia-usdt-miniapp` and legacy `/external/v2/...`), an experimental `accountedBy=harvestReport` parameter existed. It attributed keeper report gains immediately to holders at the harvest block, under the assumption that locked profit would eventually unlock to current holders.

This mode was deliberately retired in v1 for three strict accounting reasons:

1. **No Legal Entitlement or Liquidity at Report Time (IFRS Asset Recognition Failure)**:
   * Under smart contract mechanics, profit reported by a harvest is locked in a degradation buffer and released linearly over 7 days.
   * If an investor redeems shares immediately after harvest, the contract settles strictly at `pricePerShare` (using `freeFunds`), completely excluding unreleased locked profit.
   * Recording an unredeemable locked amount as current holder balance or PnL violates the IFRS definition of an asset (present economic control and expected realizable inflow).

2. **Shareholding Dilution and Flow Mismatch**:
   * Assuming locked profit belongs to current holders requires assuming zero subsequent deposits or withdrawals over the next 7 days.
   * If new depositors enter the vault on day 2, they acquire shares at the current PPS, and the remaining locked profit unlocks across the enlarged share supply. Current holders are diluted.
   * Recognizing 100% of the locked profit on day 1 produces phantom gains that change retrospectively when other participants transact.

3. **Breakage of the Lifetime Ledger Invariant**:
   * Any compliant accounting ledger must satisfy:
     ```text theme={null}
     Cumulative Lifetime PnL = Closing Total Value + Total Withdrawn - Total Deposited
     ```
   * Because all deposits and redemptions execute in real tokens at PPS, booking locked profit in balance/earnings causes a sharp artificial disposal loss when an investor exits at actual PPS.

#### How to query the information you need

Rather than blending hypothetical future releases into canonical balance and PnL, v1 separates the information into dedicated, audit-grade endpoints:

| If you need...                                         | Query this                                       | What it returns                                                                                                                      |
| :----------------------------------------------------- | :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **Official holder balance & PnL**                      | `GET /v1/earnings` (default `valuation=pps`)     | Audit-grade, fully realizable balance sheet holdings and period earnings.                                                            |
| **Contract reported assets & locked profit breakdown** | `GET /v1/earnings?include=reconciliation`        | Keeps official PPS numbers intact while providing `reportedAssets`, `lockedProfit`, and `rounding` adjustments as audit evidence.    |
| **Strategy harvest events & gross allocation**         | `GET /v1/harvests?account=...&start=...&end=...` | Block-by-block confirmed harvest events, gross report gains, fee deductions, and pro-rata wallet share allocations at report blocks. |
| **Pre-harvest real-time venue accruals**               | `GET /v1/earnings?valuation=estimated_nav`       | Live economic yield directly from underlying venues (Morpho, Pendle PT, RWA) before root vault reporting.                            |

### Boundary valuation equation

For supported SuperVault roots (`apiVersion: "0.4.6"`), the boundary valuation is computed in three precise stages:

**1. Linear profit release**

```text theme={null}
Released Profit         = floor(min(Elapsed Seconds * Degradation Rate, 10^18) * Stored Locked Profit / 10^18)
Effective Locked Profit = Stored Locked Profit - Released Profit
```

**2. Free funds and active position valuation**

```text theme={null}
Free Funds            = Reported Total Assets - Effective Locked Profit
Active Position Value = floor(Held Shares * Free Funds / Total Supply) (converted)
Total Value           = Active Position Value + Redemption Receivables
```

**3. Reported-asset reconciliation (`include=reconciliation`)**

```text theme={null}
Reported Position Value = Active Position Value + Allocated Locked Profit + Rounding Adjustment
```

* **Allocated Locked Profit**: `floor(Held Shares * Effective Locked Profit / Total Supply) (converted)`.
* **Rounding Adjustment**: Integer floor difference between the converted reported allocation (`floor(Held Shares * Reported Total Assets / Total Supply) (converted)`) and the sum of active position value and allocated locked profit.

> \[!NOTE]
> **Valuation mode vs reconciliation evidence**: The Data API supports exactly two valuation modes: `valuation=pps` (default canonical share value) and `valuation=estimated_nav` (real-time underlying venue accruals). `include=reconciliation` is **not** an independent valuation mode; it is an enrichment parameter available exclusively with `valuation=pps` that supplies audit evidence reconciling the difference between canonical PPS valuation and total reported assets (including the locked profit buffer and integer rounding differences).

## Harvest allocation

For each harvest report, optional wallet allocation uses **end-of-report-block** ownership:

```text theme={null}
Wallet Harvest Allocation = floor(Wallet Shares * Net Report Gain / Total Supply) (converted)
```

* **Net report gain**: Gross report gain minus gross report loss in underlying token atoms (signed integer division truncates toward zero before conversion).
* **Report-block ownership**: Wallet shares and total supply measured after all transactions in the report block.
* **Assessed fees**: Fees equal `min(Gross Gain, Management Fee + Performance Fee + Strategist Fee)`; zero gain charges zero.

## Period-close workflow

To perform an audit-grade monthly or annual financial close:

| Step             | Action                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **1. Define**    | Select asset, scope (wallet vs whole vault), reporting dates, and local timezone (e.g. `Asia/Seoul`)                     |
| **2. Read**      | Query `GET /v1/earnings` for the entire interval or daily rows; add `include=reconciliation` if auditing reported assets |
| **3. Verify**    | Verify that `quality.status` is `complete` and confirm that the reconciliation residual is zero (`residual = 0`)         |
| **4. Reconcile** | Confirm `closing.totalValue = opening.totalValue + inflows - outflows + pnl`                                             |
| **5. Freeze**    | Archive the API payload, query parameters, confirmed block hashes, and policy version in the financial ledger            |

> \[!TIP]
> **Practical Walkthrough**: For an end-to-end walkthrough with live curl requests, actual response payloads, and ledger journal entries, see the [Partner Reconciliation Walkthrough](/en/developers/reconciliation-guide).

## Additional recognition and measurement

| Additional coverage                          | Required evidence                                                                                                                                                                                                                                   |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Income outside strategy getter**           | Venue position proof, entitlement, measurement time, and valuation                                                                                                                                                                                  |
| **Financial statement carrying adjustments** | Accounting classification, impairment assessments, FX conversion                                                                                                                                                                                    |
| **Statutory balance sheet adjustments**      | Application of [IFRS 9](https://www.ifrs.org/issued-standards/list-of-standards/ifrs-9-financial-instruments/) (classification) and [IFRS 13](https://www.ifrs.org/issued-standards/list-of-standards/ifrs-13-fair-value-measurement/) (fair value) |

When applying a separately supported carrying adjustment without altering underlying on-chain cash flows, adjust the book as follows:

```text theme={null}
Adjusted Balance = Ledger Balance + Carrying Adjustment
Adjusted PnL     = Ledger PnL + (Ending Adjustment - Beginning Adjustment)
```