tapimo 0.7.2 → 0.9.0

package/src/apps/data/routes/earn.ts

@@ -5,6 +5,7 @@ import {
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
   ContractFunctionZeroDataError,
+  zeroAddress,
 } from 'viem'
 import * as z from 'zod/mini'
 
@@ -20,6 +21,7 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Store from '../../../internal/Store.js'
+import * as Tidx from '../../../internal/Tidx.js'
 import * as Timing from '../../../internal/Timing.js'
 import * as Ttl from '../../../internal/Ttl.js'
 import * as Value from '../../../internal/Value.js'
@@ -31,8 +33,31 @@ import * as Valuation from './valuation.js'
 const deployedSignature =
   'event EarnStackDeployed(address indexed earnVault,address indexed earnShare,address indexed earnFees,address engine,address asset,address owner,bytes32 deploymentId,address emergencyGuardian,address asyncJanitor,uint8 migrationMode,bytes32 earnShareSalt,bytes32 controlConfigHash,bytes32 feeConfigHash,bytes32 earnFeesSalt)'
 
+const depositedSignature =
+  'event Deposited(address indexed caller,address indexed receiver,uint256 assets,uint256 earnShares)'
+
+const redeemedSignature =
+  'event Redeemed(address indexed caller,address indexed receiver,uint256 earnShares,uint256 assets)'
+
+const withdrewExactSignature =
+  'event WithdrewExact(address indexed caller,address indexed receiver,uint256 assets,uint256 earnSharesBurned)'
+
+const redeemFinalizedSignature =
+  'event RedeemFinalized(bytes32 indexed requestId,address indexed receiver,uint256 earnShares,address asset,uint256 assets)'
+
+const redeemCancelledSignature =
+  'event RedeemCancelled(bytes32 indexed requestId,address indexed receiver,uint256 earnShares)'
+
+const redeemRequestedSignature =
+  'event RedeemRequested(bytes32 indexed requestId,address indexed requester,address indexed receiver,uint256 earnShares)'
+
+const venueSharesDepositedSignature =
+  'event VenueSharesDeposited(address indexed caller,address indexed receiver,uint256 requestedVenueShares,uint256 receivedVenueShares,uint256 earnShares)'
+
 const maxScannedDeployments = 250
 const scanLimit = 50
+/** Block boundary that includes all indexed history. */
+const beforeFirstBlockNumber = -1
 
 /** Vault TVL is reported in USD only; the API exposes no denomination parameter. */
 const tvlDenomination = 'USD'
@@ -300,6 +325,133 @@ export namespace schema {
     ),
   })
 
+  const earningsBase = z.strictObject({
+    account: Schema.Address.check(
+      z.describe('Account whose vault earnings were calculated.'),
+      z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] }),
+    ),
+    assetToken: Schema.TokenAddress.check(
+      z.describe('TIP-20 asset token accepted by the vault.'),
+      z.meta({ examples: ['0x20c000000000000000000000ff04042ee92fd449'] }),
+    ),
+    currentValue: Schema.DecimalString.check(
+      z.describe(
+        'Asset value of the account’s active Earn shares at the latest indexed block, in asset base units.',
+      ),
+      z.meta({ examples: ['600000'] }),
+    ),
+    id: Schema.Address.check(
+      z.describe('Stable resource ID for these vault earnings, equal to the account address.'),
+      z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] }),
+    ),
+  })
+
+  const earningsPeriod = z
+    .enum(['30d', 'active', 'lifetime'])
+    .check(
+      z.describe(
+        'Earnings period to calculate: trailing 30 days, shares still held, or lifetime history.',
+      ),
+      z.meta({ examples: ['lifetime'] }),
+    )
+
+  const earnings = z.union([
+    z.extend(earningsBase, {
+      lifetimeEarnings: z
+        .string()
+        .check(
+          z.regex(/^-?\d+$/),
+          z.describe(
+            'Current share value plus completed redemptions, exact withdrawals, and finalized async assets, minus asset deposits, at the latest indexed block.',
+          ),
+          z.meta({ examples: ['0'] }),
+        ),
+      period: z
+        .literal('lifetime')
+        .check(
+          z.describe('Returns lifetime net asset earnings.'),
+          z.meta({ examples: ['lifetime'] }),
+        ),
+      status: z
+        .literal('complete')
+        .check(
+          z.describe('Earnings include a complete asset-denominated cost basis.'),
+          z.meta({ examples: ['complete'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      activeEarnings: z
+        .string()
+        .check(
+          z.regex(/^-?\d+$/),
+          z.describe(
+            'Current share value minus the weighted-average asset cost basis of shares still held, at the latest indexed block.',
+          ),
+          z.meta({ examples: ['0'] }),
+        ),
+      period: z
+        .literal('active')
+        .check(
+          z.describe('Returns earnings on shares still held.'),
+          z.meta({ examples: ['active'] }),
+        ),
+      status: z
+        .literal('complete')
+        .check(
+          z.describe('Earnings include a complete asset-denominated cost basis.'),
+          z.meta({ examples: ['complete'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      period: z
+        .literal('30d')
+        .check(
+          z.describe('Returns cash-flow-adjusted earnings over the trailing 30 days.'),
+          z.meta({ examples: ['30d'] }),
+        ),
+      status: z
+        .literal('complete')
+        .check(
+          z.describe('Earnings include a complete asset-denominated cost basis.'),
+          z.meta({ examples: ['complete'] }),
+        ),
+      windowEarnings: z
+        .string()
+        .check(
+          z.regex(/^-?\d+$/),
+          z.describe(
+            'Ending share value plus realized assets, minus deposits and opening share value, over the trailing 30 days.',
+          ),
+          z.meta({ examples: ['0'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      period: earningsPeriod,
+      status: z
+        .literal('incomplete_cost_basis')
+        .check(
+          z.describe(
+            'Earnings are unavailable when indexed activity cannot reconstruct the asset cost basis for the requested period.',
+          ),
+          z.meta({ examples: ['incomplete_cost_basis'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      period: z
+        .enum(['30d', 'lifetime'])
+        .check(
+          z.describe('Earnings period with an unresolved async redemption.'),
+          z.meta({ examples: ['lifetime'] }),
+        ),
+      status: z
+        .literal('pending_redemption')
+        .check(
+          z.describe('Earnings are unavailable while an async redemption remains open.'),
+          z.meta({ examples: ['pending_redemption'] }),
+        ),
+    }),
+  ])
+
   const meta = z
     .object({
       valuation: z
@@ -428,6 +580,33 @@ export namespace schema {
       'Current asset and Earn-share balances, allowances, and asset value for an account in one Earn vault.',
     )
   }
+
+  /** Schemas for the getEarnVaultEarnings operation. */
+  export namespace getEarnVaultEarnings {
+    /** Path parameters identifying the Earn vault and account. */
+    export const Params = z
+      .strictObject({
+        address: Schema.Address.check(z.describe('Account whose vault earnings to read.')),
+        vaultId: Schema.address('0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a').check(
+          z.describe('Earn vault contract address.'),
+        ),
+      })
+      .check(z.describe('Path parameters identifying an Earn vault account.'))
+
+    /** Query parameters selecting the chain containing the vault. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        period: z._default(earningsPeriod, 'lifetime'),
+      })
+      .check(z.describe('Query parameters selecting an Earn vault account.'))
+
+    /** Earnings for one account and period in one Earn vault. */
+    export const Response = Schema.describe(
+      earnings,
+      'Indexed asset value and cost-basis-aware earnings for an account in one Earn vault.',
+    )
+  }
 }
 
 /** Creates the public Earn-vault handlers. */
@@ -452,7 +631,7 @@ export function earn(options: earn.Options = {}) {
             schema: schema.getEarnVaults.Response,
           },
         }),
-        summary: 'List Earn vaults',
+        summary: 'List vaults',
         tags: ['Earn'],
       }),
       // Live state and rate enrichment are embedded, so every vault read caches
@@ -560,7 +739,7 @@ export function earn(options: earn.Options = {}) {
             schema: schema.getEarnVaultPosition.Response,
           },
         }),
-        summary: 'Get vault position',
+        summary: 'Get account position',
         tags: ['Earn'],
       }),
       Cache.response<App.Environment>({
@@ -629,6 +808,101 @@ export function earn(options: earn.Options = {}) {
         }
       },
     )
+    .get(
+      '/v1/earn/vaults/:vaultId/earnings/:address',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnVaultEarnings.Params, {
+        code: 'earnings_invalid',
+        message: 'Invalid vault earnings',
+      }),
+      OpenApi.validate('query', schema.getEarnVaultEarnings.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Gets an account’s indexed asset value and earnings for lifetime history, the trailing 30 days, or shares still held.',
+        operationId: 'getEarnVaultEarnings',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'earnings_invalid',
+                'query_invalid',
+              ],
+            },
+            404: {
+              codes: ['earn_vault_not_found'],
+              description: 'No compatible Earn vault was found at this address.',
+            },
+            502: 'Could not read the Earn vault earnings.',
+          },
+          success: {
+            description: 'Cost-basis-aware earnings for one account in one vault.',
+            schema: schema.getEarnVaultEarnings.Response,
+          },
+        }),
+        summary: 'Get vault earnings',
+        tags: ['Earn'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
+        name: 'tempo-api:earn-vault-earnings:v3',
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_invalid',
+            message: 'Invalid chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: 'Unsupported chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'earnings_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const { address, vaultId } = c.req.valid('param')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const data = await getVaultEarnings(c, {
+            account: address,
+            chainId,
+            period: query.period,
+            vault: vaultId,
+          })
+          return c.json(Response.validated(schema.getEarnVaultEarnings.Response, data), 200)
+        } catch (cause) {
+          try {
+            await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId })
+          } catch (vaultCause) {
+            if (isIncompatible(vaultCause))
+              return Response.error(c, {
+                code: 'earn_vault_not_found',
+                message: 'Earn vault not found',
+                status: 404,
+              })
+          }
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .get(
       '/v1/earn/vaults/:vaultId',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -657,7 +931,7 @@ export function earn(options: earn.Options = {}) {
             schema: schema.getEarnVault.Response,
           },
         }),
-        summary: 'Get Earn vault',
+        summary: 'Get vault',
         tags: ['Earn'],
       }),
       Cache.response<App.Environment>({
@@ -711,6 +985,870 @@ export declare namespace earn {
   }
 }
 
+/** Reads one account's indexed value and returns earnings when the history is complete. */
+export async function getVaultEarnings(
+  c: Context<App.Environment>,
+  options: getVaultEarnings.Options,
+) {
+  const client = c.get('getClient')(options.chainId)
+  const tidx = c.get('getTidx')(options.chainId)
+  const block = await getLatestIndexedBlock(tidx)
+  const blockNumber = block.number
+  if (options.period === '30d')
+    return getWindowVaultEarnings(c, {
+      account: options.account,
+      blockNumber,
+      chainId: options.chainId,
+      period: options.period,
+      timestamp: block.timestamp,
+      vault: options.vault,
+    })
+  const position = client.earn.getPosition({
+    account: options.account,
+    blockNumber: BigInt(blockNumber),
+    vault: options.vault,
+  })
+  if (options.period === 'active') {
+    const current = await position
+    const base = {
+      account: options.account,
+      assetToken: current.assetToken,
+      currentValue: current.value.toString(),
+      id: options.account,
+      period: options.period,
+    }
+    const activeCostBasis = await getActiveCostBasis(tidx, {
+      account: options.account,
+      blockNumber,
+      shareBalance: current.shareBalance,
+      shareToken: current.shareToken,
+      vault: options.vault,
+    })
+    if (activeCostBasis === undefined) return { ...base, status: 'incomplete_cost_basis' as const }
+    return {
+      ...base,
+      activeEarnings: (current.value - activeCostBasis).toString(),
+      status: 'complete' as const,
+    }
+  }
+  const [history, current] = await Promise.all([
+    getVaultEarningsHistory(tidx, {
+      account: options.account,
+      blockNumber,
+      startBlockNumber: beforeFirstBlockNumber,
+      vault: options.vault,
+    }),
+    position,
+  ])
+  const externalShareTransfer = await hasExternalShareTransfer(tidx, {
+    account: options.account,
+    blockNumber,
+    shareToken: current.shareToken,
+    startBlockNumber: beforeFirstBlockNumber,
+    vault: options.vault,
+  })
+  const base = {
+    account: options.account,
+    assetToken: current.assetToken,
+    currentValue: current.value.toString(),
+    id: options.account,
+    period: options.period,
+  }
+  if (history.incompleteCostBasis || externalShareTransfer)
+    return { ...base, status: 'incomplete_cost_basis' as const }
+  if (history.pendingRedemption) return { ...base, status: 'pending_redemption' as const }
+  const lifetimeEarnings =
+    current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited
+  return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' as const }
+}
+
+/** Reads cash-flow-adjusted earnings over a trailing indexed window. */
+async function getWindowVaultEarnings(
+  c: Context<App.Environment>,
+  options: getWindowVaultEarnings.Options,
+) {
+  const client = c.get('getClient')(options.chainId)
+  const tidx = c.get('getTidx')(options.chainId)
+  const [current, startBlockNumber] = await Promise.all([
+    client.earn.getPosition({
+      account: options.account,
+      blockNumber: BigInt(options.blockNumber),
+      vault: options.vault,
+    }),
+    getWindowStartBlockNumber(tidx, { days: 30, timestamp: options.timestamp }),
+  ])
+  const [externalShareTransfer, history, opening] = await Promise.all([
+    hasExternalShareTransfer(tidx, {
+      account: options.account,
+      blockNumber: options.blockNumber,
+      shareToken: current.shareToken,
+      startBlockNumber,
+      vault: options.vault,
+    }),
+    getVaultEarningsHistory(tidx, {
+      account: options.account,
+      blockNumber: options.blockNumber,
+      startBlockNumber,
+      vault: options.vault,
+    }),
+    getWindowShareState(tidx, {
+      account: options.account,
+      blockNumber: options.blockNumber,
+      shareToken: current.shareToken,
+      startBlockNumber,
+      vault: options.vault,
+    }),
+  ])
+  const base = {
+    account: options.account,
+    assetToken: current.assetToken,
+    currentValue: current.value.toString(),
+    id: options.account,
+    period: options.period,
+  }
+  if (
+    opening === undefined ||
+    externalShareTransfer ||
+    history.incompleteCostBasis ||
+    opening.crossBoundaryRedemption ||
+    opening.endShares !== current.shareBalance
+  )
+    return { ...base, status: 'incomplete_cost_basis' as const }
+  if (history.pendingRedemption) return { ...base, status: 'pending_redemption' as const }
+  const openingValue =
+    opening.startShares === 0n
+      ? 0n
+      : await client.earn.getRedeemQuote({
+          blockNumber: BigInt(startBlockNumber),
+          shareAmount: opening.startShares,
+          vault: options.vault,
+        })
+  const windowEarnings = calculateWindowEarnings({
+    deposited: history.deposited,
+    endingValue: current.value,
+    finalized: history.finalized,
+    openingValue,
+    redeemed: history.redeemed,
+    withdrewExact: history.withdrewExact,
+  })
+  return { ...base, status: 'complete' as const, windowEarnings: windowEarnings.toString() }
+}
+
+declare namespace getWindowVaultEarnings {
+  /** Inputs identifying one account, vault, and indexed window end. */
+  type Options = {
+    /** Account whose earnings are calculated. */
+    account: z.output<typeof Schema.Address>
+    /** Latest indexed block number. */
+    blockNumber: number
+    /** Tempo chain containing the vault. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Trailing earnings period. */
+    period: '30d'
+    /** Latest indexed block timestamp. */
+    timestamp: string
+    /** Earn vault contract address. */
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Calculates cash-flow-adjusted earnings between two position snapshots. */
+export function calculateWindowEarnings(options: calculateWindowEarnings.Options) {
+  return (
+    options.endingValue +
+    options.redeemed +
+    options.withdrewExact +
+    options.finalized -
+    options.deposited -
+    options.openingValue
+  )
+}
+
+export declare namespace calculateWindowEarnings {
+  /** Asset-denominated values spanning one earnings window. */
+  type Options = {
+    /** Assets deposited during the window. */
+    deposited: bigint
+    /** Asset value of shares held at the ending boundary. */
+    endingValue: bigint
+    /** Assets received from async redemptions finalized during the window. */
+    finalized: bigint
+    /** Asset value of shares held at the opening boundary. */
+    openingValue: bigint
+    /** Assets received from redemptions during the window. */
+    redeemed: bigint
+    /** Assets received from exact withdrawals during the window. */
+    withdrewExact: bigint
+  }
+}
+
+export declare namespace getVaultEarnings {
+  /** Inputs identifying the account and vault to calculate. */
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    period: z.output<typeof schema.getEarnVaultEarnings.Query>['period']
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Reads the latest block whose indexed logs back the earnings calculation. */
+async function getLatestIndexedBlock(tidx: Tidx.Client) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: 'SELECT num, timestamp FROM blocks ORDER BY num DESC LIMIT 1' as string,
+  })
+  const number = Value.toNumber(result.rows[0]?.['num'])
+  const timestamp = Value.toIsoDateTime(result.rows[0]?.['timestamp'])
+  if (number === undefined || timestamp === undefined)
+    throw new Error('TIDX returned no indexed block.')
+  return { number, timestamp }
+}
+
+/** Resolves the last indexed block at or before a trailing-day boundary. */
+async function getWindowStartBlockNumber(
+  tidx: Tidx.Client,
+  options: getWindowStartBlockNumber.Options,
+) {
+  const cutoff = new Date(Date.parse(options.timestamp) - Ttl.days(options.days)).toISOString()
+  const result = await tidx.fetch({
+    query:
+      `SELECT num FROM blocks WHERE timestamp <= '${cutoff}' ORDER BY num DESC LIMIT 1` as string,
+  })
+  const row = result.rows[0]
+  if (!row) return beforeFirstBlockNumber
+  const blockNumber = Value.toNumber(row['num'])
+  if (blockNumber === undefined) throw new Error('TIDX returned no Earn earnings boundary.')
+  return blockNumber
+}
+
+declare namespace getWindowStartBlockNumber {
+  /** Inputs defining a trailing boundary from an indexed timestamp. */
+  type Options = {
+    /** Number of trailing days. */
+    days: number
+    /** Timestamp anchoring the end of the window. */
+    timestamp: string
+  }
+}
+
+/** Reads the indexed cash flows and exceptional states behind one earnings calculation. */
+async function getVaultEarningsHistory(
+  tidx: Tidx.Client,
+  options: getVaultEarningsHistory.Options,
+) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT
+        (
+          SELECT toString(sum(toUInt256(assets)))
+          FROM Deposited
+          WHERE address = '${options.vault}'
+            AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
+            AND block_num <= ${options.blockNumber}
+        ) AS deposited_assets,
+        (
+          SELECT toString(sum(toUInt256(finalized.assets)))
+          FROM RedeemFinalized AS finalized
+          INNER JOIN RedeemRequested AS requested
+            ON requested.address = finalized.address
+            AND requested."requestId" = finalized."requestId"
+          WHERE finalized.address = '${options.vault}'
+            AND requested.requester = '${options.account}'
+            AND finalized.block_num > ${options.startBlockNumber}
+            AND finalized.block_num <= ${options.blockNumber}
+            AND requested.block_num <= ${options.blockNumber}
+        ) AS finalized_assets,
+        (
+          SELECT count()
+          FROM RedeemRequested AS requested
+          LEFT ANTI JOIN RedeemFinalized AS finalized
+            ON finalized.address = requested.address
+            AND finalized."requestId" = requested."requestId"
+            AND finalized.block_num <= ${options.blockNumber}
+          LEFT ANTI JOIN RedeemCancelled AS cancelled
+            ON cancelled.address = requested.address
+            AND cancelled."requestId" = requested."requestId"
+            AND cancelled.block_num <= ${options.blockNumber}
+          WHERE requested.address = '${options.vault}'
+            AND requested.requester = '${options.account}'
+            AND requested.block_num <= ${options.blockNumber}
+        ) AS pending_redemptions,
+        (
+          SELECT toString(sum(toUInt256(assets)))
+          FROM Redeemed
+          WHERE address = '${options.vault}'
+            AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
+            AND block_num <= ${options.blockNumber}
+        ) AS redeemed_assets,
+        (
+          SELECT count()
+          FROM RedeemCancelled AS cancelled
+          INNER JOIN RedeemRequested AS requested
+            ON requested.address = cancelled.address
+            AND requested."requestId" = cancelled."requestId"
+          WHERE cancelled.address = '${options.vault}'
+            AND cancelled.block_num > ${options.startBlockNumber}
+            AND cancelled.block_num <= ${options.blockNumber}
+            AND requested.block_num <= ${options.blockNumber}
+            AND requested.requester != cancelled.receiver
+            AND (
+              requested.requester = '${options.account}'
+              OR cancelled.receiver = '${options.account}'
+            )
+        ) AS transferred_cancellations,
+        (
+          SELECT count()
+          FROM VenueSharesDeposited
+          WHERE address = '${options.vault}'
+            AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
+            AND block_num <= ${options.blockNumber}
+        ) AS venue_deposits,
+        (
+          SELECT toString(sum(toUInt256(assets)))
+          FROM WithdrewExact
+          WHERE address = '${options.vault}'
+            AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
+            AND block_num <= ${options.blockNumber}
+        ) AS withdrew_exact
+    ` as string,
+    signatures: [
+      depositedSignature,
+      redeemCancelledSignature,
+      redeemFinalizedSignature,
+      redeemRequestedSignature,
+      redeemedSignature,
+      venueSharesDepositedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  const row = result.rows[0]
+  const deposited = Value.toIntegerString(row?.['deposited_assets'])
+  const finalized = Value.toIntegerString(row?.['finalized_assets'])
+  const pendingRedemptions = Value.toNumber(row?.['pending_redemptions'])
+  const redeemed = Value.toIntegerString(row?.['redeemed_assets'])
+  const transferredCancellations = Value.toNumber(row?.['transferred_cancellations'])
+  const venueDeposits = Value.toNumber(row?.['venue_deposits'])
+  const withdrewExact = Value.toIntegerString(row?.['withdrew_exact'])
+  if (
+    deposited === undefined ||
+    finalized === undefined ||
+    pendingRedemptions === undefined ||
+    redeemed === undefined ||
+    transferredCancellations === undefined ||
+    venueDeposits === undefined ||
+    withdrewExact === undefined
+  )
+    throw new Error('TIDX returned invalid Earn earnings history.')
+  return {
+    deposited: BigInt(deposited),
+    finalized: BigInt(finalized),
+    incompleteCostBasis: transferredCancellations > 0 || venueDeposits > 0,
+    pendingRedemption: pendingRedemptions > 0,
+    redeemed: BigInt(redeemed),
+    withdrewExact: BigInt(withdrewExact),
+  }
+}
+
+declare namespace getVaultEarningsHistory {
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    startBlockNumber: number
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Reads share balances and cross-boundary redemptions for a trailing window. */
+async function getWindowShareState(tidx: Tidx.Client, options: getWindowShareState.Options) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "to" = '${options.account}'
+            AND block_num <= ${options.startBlockNumber}
+        ) AS received_start,
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "from" = '${options.account}'
+            AND block_num <= ${options.startBlockNumber}
+        ) AS sent_start,
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "to" = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS received_end,
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "from" = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS sent_end,
+        (
+          SELECT count()
+          FROM (
+            SELECT finalized."requestId"
+            FROM RedeemFinalized AS finalized
+            INNER JOIN RedeemRequested AS requested
+              ON requested.address = finalized.address
+              AND requested."requestId" = finalized."requestId"
+            WHERE finalized.address = '${options.vault}'
+              AND requested.requester = '${options.account}'
+              AND requested.block_num <= ${options.startBlockNumber}
+              AND finalized.block_num > ${options.startBlockNumber}
+              AND finalized.block_num <= ${options.blockNumber}
+            UNION ALL
+            SELECT cancelled."requestId"
+            FROM RedeemCancelled AS cancelled
+            INNER JOIN RedeemRequested AS requested
+              ON requested.address = cancelled.address
+              AND requested."requestId" = cancelled."requestId"
+            WHERE cancelled.address = '${options.vault}'
+              AND requested.requester = '${options.account}'
+              AND requested.block_num <= ${options.startBlockNumber}
+              AND cancelled.block_num > ${options.startBlockNumber}
+              AND cancelled.block_num <= ${options.blockNumber}
+          ) AS cross_boundary
+        ) AS cross_boundary_redemptions
+    ` as string,
+    signatures: [redeemCancelledSignature, redeemFinalizedSignature, redeemRequestedSignature],
+  })
+  const row = result.rows[0]
+  const crossBoundaryRedemptions = Value.toNumber(row?.['cross_boundary_redemptions'])
+  const receivedEnd = Value.toIntegerString(row?.['received_end'])
+  const receivedStart = Value.toIntegerString(row?.['received_start'])
+  const sentEnd = Value.toIntegerString(row?.['sent_end'])
+  const sentStart = Value.toIntegerString(row?.['sent_start'])
+  if (
+    crossBoundaryRedemptions === undefined ||
+    receivedEnd === undefined ||
+    receivedStart === undefined ||
+    sentEnd === undefined ||
+    sentStart === undefined
+  )
+    return undefined
+  const receivedEndValue = BigInt(receivedEnd)
+  const receivedStartValue = BigInt(receivedStart)
+  const sentEndValue = BigInt(sentEnd)
+  const sentStartValue = BigInt(sentStart)
+  if (sentEndValue > receivedEndValue || sentStartValue > receivedStartValue) return undefined
+  return {
+    crossBoundaryRedemption: crossBoundaryRedemptions > 0,
+    endShares: receivedEndValue - sentEndValue,
+    startShares: receivedStartValue - sentStartValue,
+  }
+}
+
+declare namespace getWindowShareState {
+  /** Inputs identifying one account's share history window. */
+  type Options = {
+    /** Account whose share history is read. */
+    account: z.output<typeof Schema.Address>
+    /** Ending indexed block number. */
+    blockNumber: number
+    /** Earn share token contract address. */
+    shareToken: z.output<typeof Schema.Address>
+    /** Opening indexed block number. */
+    startBlockNumber: number
+    /** Earn vault contract address. */
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Returns whether an account sent or received Earn shares outside known vault flows. */
+async function hasExternalShareTransfer(
+  tidx: Tidx.Client,
+  options: hasExternalShareTransfer.Options,
+) {
+  // Vault exits pull shares into the vault before burning. Reconcile counts by transaction and amount so unmatched direct sends remain external.
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT
+        (
+          SELECT count()
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND block_num > ${options.startBlockNumber}
+            AND block_num <= ${options.blockNumber}
+            AND (
+              ("from" = '${options.account}' AND "to" != '${options.vault}')
+              OR (
+                "to" = '${options.account}'
+                AND "from" != '${zeroAddress}'
+                AND "from" != '${options.vault}'
+              )
+            )
+        ) + (
+          SELECT count()
+          FROM (
+            SELECT tx_hash, toUInt256(amount) AS amount, count() AS transfer_count
+            FROM token_transfers
+            WHERE token = '${options.shareToken.toLowerCase()}'
+              AND "from" = '${options.account}'
+              AND "to" = '${options.vault}'
+              AND block_num > ${options.startBlockNumber}
+              AND block_num <= ${options.blockNumber}
+            GROUP BY tx_hash, amount
+          ) AS candidate
+          LEFT JOIN (
+            SELECT tx_hash, amount, count() AS exit_count
+            FROM (
+              SELECT tx_hash, toUInt256(earnShares) AS amount
+              FROM Redeemed
+              WHERE address = '${options.vault}'
+                AND caller = '${options.account}'
+                AND block_num > ${options.startBlockNumber}
+                AND block_num <= ${options.blockNumber}
+              UNION ALL
+              SELECT tx_hash, toUInt256(earnShares) AS amount
+              FROM RedeemRequested
+              WHERE address = '${options.vault}'
+                AND requester = '${options.account}'
+                AND block_num > ${options.startBlockNumber}
+                AND block_num <= ${options.blockNumber}
+              UNION ALL
+              SELECT tx_hash, toUInt256(earnSharesBurned) AS amount
+              FROM WithdrewExact
+              WHERE address = '${options.vault}'
+                AND caller = '${options.account}'
+                AND block_num > ${options.startBlockNumber}
+                AND block_num <= ${options.blockNumber}
+            ) AS protocol_exit
+            GROUP BY tx_hash, amount
+          ) AS matched
+            ON matched.tx_hash = candidate.tx_hash AND matched.amount = candidate.amount
+          WHERE candidate.transfer_count > coalesce(matched.exit_count, 0)
+        ) + (
+          SELECT count()
+          FROM (
+            SELECT tx_hash, toUInt256(amount) AS amount, count() AS transfer_count
+            FROM token_transfers
+            WHERE token = '${options.shareToken.toLowerCase()}'
+              AND "from" = '${options.vault}'
+              AND "to" = '${options.account}'
+              AND block_num > ${options.startBlockNumber}
+              AND block_num <= ${options.blockNumber}
+            GROUP BY tx_hash, amount
+          ) AS candidate
+          LEFT JOIN (
+            SELECT tx_hash, toUInt256(earnShares) AS amount, count() AS cancel_count
+            FROM RedeemCancelled
+            WHERE address = '${options.vault}'
+              AND receiver = '${options.account}'
+              AND block_num > ${options.startBlockNumber}
+              AND block_num <= ${options.blockNumber}
+            GROUP BY tx_hash, amount
+          ) AS matched
+            ON matched.tx_hash = candidate.tx_hash AND matched.amount = candidate.amount
+          WHERE candidate.transfer_count > coalesce(matched.cancel_count, 0)
+        ) AS count
+    ` as string,
+    signatures: [
+      redeemCancelledSignature,
+      redeemedSignature,
+      redeemRequestedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  const count = Value.toNumber(result.rows[0]?.['count'])
+  if (count === undefined) throw new Error('TIDX returned an invalid Earn-share transfer count.')
+  return count > 0
+}
+
+declare namespace hasExternalShareTransfer {
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    shareToken: z.output<typeof Schema.Address>
+    startBlockNumber: number
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Calculates the asset cost basis attached to an account's remaining Earn shares. */
+export function calculateActiveCostBasis(options: calculateActiveCostBasis.Options) {
+  const requests = new Map<string, { costBasis: bigint | undefined; shares: bigint }>()
+  let costBasis: bigint | undefined = 0n
+  let shares = 0n
+
+  const remove = (burned: bigint) => {
+    if (burned > shares || shares === 0n) return undefined
+    const removed = (() => {
+      if (costBasis === undefined) return undefined
+      return burned === shares ? costBasis : (costBasis * burned) / shares
+    })()
+    if (burned === shares) costBasis = 0n
+    else if (costBasis !== undefined && removed !== undefined) costBasis -= removed
+    shares -= burned
+    return { costBasis: removed }
+  }
+
+  for (const action of options.actions) {
+    if (action.kind === 'deposit') {
+      if (costBasis !== undefined) costBasis += action.assets
+      shares += action.shares
+      continue
+    }
+    if (action.kind === 'unknown') {
+      costBasis = undefined
+      shares += action.shares
+      continue
+    }
+    if (action.kind === 'cancel') {
+      const restored = requests.get(action.requestId)
+      if (restored === undefined || restored.shares !== action.shares) return undefined
+      if (costBasis === undefined || restored.costBasis === undefined) costBasis = undefined
+      else costBasis += restored.costBasis
+      shares += restored.shares
+      requests.delete(action.requestId)
+      continue
+    }
+    const removed = remove(action.shares)
+    if (removed === undefined) return undefined
+    if (action.kind === 'request')
+      requests.set(action.requestId, { costBasis: removed.costBasis, shares: action.shares })
+  }
+
+  return shares === options.shareBalance && costBasis !== undefined ? costBasis : undefined
+}
+
+export declare namespace calculateActiveCostBasis {
+  /** One indexed share or cost-basis mutation. */
+  export type Action =
+    | {
+        /** Action discriminator. */
+        kind: 'cancel'
+        /** Async redemption request being cancelled. */
+        requestId: string
+        /** Shares restored to the account. */
+        shares: bigint
+      }
+    | {
+        /** Assets added to the account's cost basis. */
+        assets: bigint
+        /** Action discriminator. */
+        kind: 'deposit'
+        /** Shares issued for the deposit. */
+        shares: bigint
+      }
+    | {
+        /** Action discriminator. */
+        kind: 'redeem'
+        /** Shares removed from the account. */
+        shares: bigint
+      }
+    | {
+        /** Action discriminator. */
+        kind: 'request'
+        /** Async redemption request holding the removed basis. */
+        requestId: string
+        /** Shares removed from the account. */
+        shares: bigint
+      }
+    | {
+        /** Action discriminator. */
+        kind: 'unknown'
+        /** Shares received without an asset-denominated cost basis. */
+        shares: bigint
+      }
+
+  /** Inputs for calculating the remaining cost basis. */
+  export type Options = {
+    /** Indexed mutations in chain order. */
+    actions: readonly Action[]
+    /** Share balance read at the same indexed block. */
+    shareBalance: bigint
+  }
+}
+
+/** Reads the active asset cost basis for shares held at one indexed block. */
+async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis.Options) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT kind, request_id, shares, assets
+      FROM (
+        SELECT
+          'deposit' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          toString(toUInt256(assets)) AS assets
+        FROM Deposited
+        WHERE address = '${options.vault}'
+          AND receiver = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'redeem' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          '0' AS assets
+        FROM Redeemed
+        WHERE address = '${options.vault}'
+          AND caller = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'redeem' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnSharesBurned)) AS shares,
+          '0' AS assets
+        FROM WithdrewExact
+        WHERE address = '${options.vault}'
+          AND caller = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'request' AS kind,
+          block_num,
+          log_idx,
+          "requestId" AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          '0' AS assets
+        FROM RedeemRequested
+        WHERE address = '${options.vault}'
+          AND requester = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'cancel' AS kind,
+          cancelled.block_num AS block_num,
+          cancelled.log_idx AS log_idx,
+          cancelled."requestId" AS request_id,
+          toString(toUInt256(cancelled.earnShares)) AS shares,
+          '0' AS assets
+        FROM RedeemCancelled AS cancelled
+        INNER JOIN RedeemRequested AS requested
+          ON requested.address = cancelled.address
+          AND requested."requestId" = cancelled."requestId"
+        WHERE cancelled.address = '${options.vault}'
+          AND requested.requester = '${options.account}'
+          AND cancelled.receiver = '${options.account}'
+          AND cancelled.block_num <= ${options.blockNumber}
+          AND requested.block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'unknown' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          '0' AS assets
+        FROM VenueSharesDeposited
+        WHERE address = '${options.vault}'
+          AND receiver = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'unknown' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(amount)) AS shares,
+          '0' AS assets
+        FROM token_transfers
+        WHERE token = '${options.shareToken.toLowerCase()}'
+          AND "to" = '${options.account}'
+          AND "from" != '${zeroAddress}'
+          AND "from" != '${options.vault}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'redeem' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(amount)) AS shares,
+          '0' AS assets
+        FROM token_transfers
+        WHERE token = '${options.shareToken.toLowerCase()}'
+          AND "from" = '${options.account}'
+          AND "to" != '${options.vault}'
+          AND block_num <= ${options.blockNumber}
+      ) AS actions
+      ORDER BY block_num, log_idx
+    ` as string,
+    signatures: [
+      depositedSignature,
+      redeemCancelledSignature,
+      redeemRequestedSignature,
+      redeemedSignature,
+      venueSharesDepositedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  const actions: calculateActiveCostBasis.Action[] = []
+  for (const row of result.rows) {
+    const kind = Value.toText(row['kind'])
+    if (kind === 'deposit') {
+      const assets = Value.toIntegerString(row['assets'])
+      const shares = Value.toIntegerString(row['shares'])
+      if (assets === undefined || shares === undefined) return undefined
+      actions.push({ assets: BigInt(assets), kind, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'redeem') {
+      const shares = Value.toIntegerString(row['shares'])
+      if (shares === undefined) return undefined
+      actions.push({ kind, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'cancel') {
+      const requestId = Value.toText(row['request_id'])
+      const shares = Value.toIntegerString(row['shares'])
+      if (requestId === undefined || shares === undefined) return undefined
+      actions.push({ kind, requestId, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'request') {
+      const requestId = Value.toText(row['request_id'])
+      const shares = Value.toIntegerString(row['shares'])
+      if (requestId === undefined || shares === undefined) return undefined
+      actions.push({ kind, requestId, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'unknown') {
+      const shares = Value.toIntegerString(row['shares'])
+      if (shares === undefined) return undefined
+      actions.push({ kind, shares: BigInt(shares) })
+      continue
+    }
+    return undefined
+  }
+  return calculateActiveCostBasis({ actions, shareBalance: options.shareBalance })
+}
+
+declare namespace getActiveCostBasis {
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    shareBalance: bigint
+    shareToken: z.output<typeof Schema.Address>
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
 /** Lists compatible deployed Earn vaults. */
 export async function listVaults(c: Context<App.Environment>, options: listVaults.Options) {
   const db = Db.get(c.get('dbCached'))