Skip to content

outputs.md

Latest commit

 

History

History
248 lines (182 loc) · 8.25 KB

outputs.md

File metadata and controls

248 lines (182 loc) · 8.25 KB
Raw

Kong Outputs (Timeseries) Documentation

This document catalogs all output types generated by Kong's timeseries hooks. Outputs are stored in the output table and represent time-series data for indexed contracts.

Output Schema

All outputs share a common schema:

{
  chainId: number        // EVM chain ID
  address: `0x${string}` // Contract address
  blockNumber: bigint    // Block height
  blockTime: bigint      // Block timestamp
  label: string          // Output type identifier
  component: string      // Component/field name
  value: number          // Calculated value
}

Output Types

1. tvl (Legacy - Deprecated)

Status: Legacy output, migrate to tvl-c

Available for: ERC4626, Yearn v2, Yearn v3

Components:

  • tvl: Total Value Locked in USD

Description: Single-component TVL calculation. For Yearn v2 vaults, this historically subtracted delegated assets from total assets. Delegated assets are no longer subtracted from the total. This output is replaced by the more detailed tvl-c output. If you're using tvl, migrate to tvl-c.

Deprecation Notice: The GraphQL API has migrated to use tvl-c. The legacy tvl hooks remain for backward compatibility during the transition period.

2. tvl-c (Componentized TVL)

Status: Active (current standard)

Available for: ERC4626, Yearn v2, Yearn v3

Components:

  • tvl: Total Value Locked in USD (vault assets only)
  • delegated: Delegated assets TVL in USD (Yearn v2 only, 0 for others)
  • totalAssets: Raw total assets (token units)
  • delegatedAssets: Raw delegated assets (token units, Yearn v2 only)
  • priceUsd: Asset price in USD

Description: Componentized TVL calculation that separates vault TVL from delegated assets. This provides more granular data for analysis and reporting.

Migration Guide:

-- Old query (tvl)
SELECT value FROM output
WHERE label = 'tvl'

-- New query (tvl-c)
SELECT value FROM output
WHERE label = 'tvl-c' AND component = 'tvl'

-- Get total including delegated (Yearn v2)
SELECT
  SUM(value) as total_tvl
FROM output
WHERE label = 'tvl-c'
  AND component IN ('tvl', 'delegated')

3. apy-bwd-delta-pps

Status: Active

Available for: ERC4626, Yearn v2, Yearn v3

Components:

  • net: Selected net APY (best available from weekly/monthly/inception)
  • grossApr: Gross APR before fees
  • pricePerShare: Current price per share
  • weeklyNet: Net APY based on 7-day price change
  • weeklyPricePerShare: Price per share 7 days ago
  • weeklyBlockNumber: Block number from 7 days ago
  • monthlyNet: Net APY based on 30-day price change
  • monthlyPricePerShare: Price per share 30 days ago
  • monthlyBlockNumber: Block number from 30 days ago
  • inceptionNet: Net APY since vault inception
  • inceptionPricePerShare: Price per share at inception
  • inceptionBlockNumber: Vault inception block number

Description: Backward-looking APY calculation based on price per share (PPS) delta over various time periods. The net component selects the most appropriate APY based on chain and data availability:

  • Mainnet: Prefers monthly → weekly → inception
  • Other chains: Prefers weekly → monthly → inception

Calculation Method:

  1. Compare current PPS with historical PPS (7d, 30d, or inception)
  2. Calculate delta: (currentPPS - historicalPPS) / historicalPPS
  3. Annualize: (1 + delta)^(365.2425 / period) - 1
  4. Convert net APY to gross APR using compounding periods

4. pps

Status: Active

Available for: ERC4626, Yearn v2, Yearn v3

Components:

  • raw: Raw price per share (in token decimals)
  • humanized: Human-readable price per share (decimal adjusted)

Description: Price per share tracking over time. This represents the value of one vault share in terms of the underlying asset.

Implementation Differences:

  • ERC4626: Uses convertToAssets(10^decimals) function
  • Yearn v2/v3: Uses pricePerShare() function (v2) or convertToAssets() (v3)
  • yTranche: authoritativeAssets × 10^decimals / totalSupply, where authoritative assets come from trancheController.liveAssets(tranche)

5. tranche-accounting

Status: Active

Available for: yTranche tranches

Address: the tranche

Components:

  • baselineAssets: principal plus accrued target plus realized excess
  • pendingExcess: profit assigned but not yet realized through a report
  • liveAssets: authoritative tranche assets, excluding pendingExcess
  • claim: what the tranche claims
  • covered: how much of that claim the system's backing covers
  • coverageRatio: covered / claim, NULL when there is no claim (such days are absent from the REST timeseries)
  • targetRatePerSecondWad: target accrual rate, raw WAD
  • excessShareBps: share of surplus, basis points
  • accrualPaused: 1 when accrual is paused (the tranche absorbed a loss), else 0

Description: Daily per-tranche accounting read from the tranche controller — not from the tranche's own ERC-4626 view, which does not know what the tranche has accrued or what losses it has absorbed. Asset amounts are normalized to the asset's decimals. coverageRatio is accounting coverage and is not a statement about withdrawal capacity.

6. tranche-system

Status: Active

Available for: yTranche controllers

Address: the controller

Components:

  • totalClaims: what the tranches collectively claim
  • vaultAssets: main vault assets held for the system
  • reserveAssets: reserve vault assets
  • backingAssets: what actually stands behind the claims
  • coverageRatio: backingAssets / totalClaims, NULL when there are no claims (such days are absent from the REST timeseries)

Description: Daily system-wide backing, read at the controller. Each observation reads at a single historical block. See ytranche for accounting semantics.

7. *-estimated-apr

Status: Active

Available for: Yearn v3 (full contract), Yearn v2 (legacy read path only, see below)

Reserved components (promoted out of components, see docs/estimated-apr.md):

  • netAPR: promoted to apr, net of all fees
  • netAPY: promoted to apy, net of all fees
  • grossAPR: promoted to grossAPR, before fees
  • grossAPY: promoted to grossAPY, before fees
  • compoundingPeriodsPerYear: stays in components, not an APR
  • isStrategy: stays in components, scope marker. A non-zero value marks the emission strategy-scoped. If absent or null, Kong falls back to the legacy debtRatio heuristic.

Description: An external publisher sends one row per component, under a label ending in -estimated-apr. Kong promotes the reserved components above; the rest stay in components. Full promotion rules, scope resolution, and the frozen legacy v2 read path are documented in docs/estimated-apr.md.

Protocol Coverage

Output Type ERC4626 Yearn v2 Yearn v3 yTranche
tvl (legacy) ✓ ✓ ✓ —
tvl-c ✓ ✓ ✓ ✓
apy-bwd-delta-pps ✓ ✓ ✓ ✓
pps ✓ ✓ ✓ ✓
tranche-accounting — — — ✓
tranche-system — — — controller
*-estimated-apr — legacy path only ✓ —

Tranches deliberately emit no legacy tvl: tranche TVL is a claim on the main vault's backing rather than additional protocol assets, and tvl is the label naive aggregates sum. Their tvl-c and pps come from controller-backed assets.

Querying Outputs

GraphQL API

The GraphQL API at /api/gql provides access to outputs through its timeseries resolver. Here's how to get a vault's tvl timerseries,

query Timeseries {
  timeseries(label: "tvl-c", component: "tvl", chainId: 1, address: "0xdA816459F1AB5631232FE5e97a05BBBb94970c95", limit: 1000) {
    chainId
    address
    label
    component
    value
    time
    period
  }
}

Note: The tvls resolver now uses tvl-c with component = 'tvl' filter.

Development Notes

Adding New Output Types

  1. Create timeseries hook at packages/ingest/abis/{protocol}/{version}/{contract}/timeseries/{label}/hook.ts
  2. Export outputLabel constant
  3. Implement process() function returning Output[]
  4. Test using graphql explorer
  5. Document in this file