tapimo 0.7.2 → 0.9.0

package/dist/apps/data/routes/earn.js

@@ -1,6 +1,6 @@
 import { Hono } from 'hono';
 import { Value as core_Value } from 'ox';
-import { ContractFunctionExecutionError, ContractFunctionRevertedError, ContractFunctionZeroDataError, } from 'viem';
+import { ContractFunctionExecutionError, ContractFunctionRevertedError, ContractFunctionZeroDataError, zeroAddress, } from 'viem';
 import * as z from 'zod/mini';
 import * as Db from '../../../db/Db.js';
 import * as core_EarnVaults from '../../../db/tables/earnVaults.js';
@@ -13,6 +13,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';
@@ -21,8 +22,17 @@ import * as FxOracle from '../FxOracle.js';
 import * as Tokens from './tokens.js';
 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';
 /** `Valuation.valuationFor` floors to 6 dp, so 6 is the precision a valued amount carries. */
@@ -155,6 +165,64 @@ export var schema;
         shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(z.describe('TIP-20 token representing Earn shares.')),
         value: Schema.DecimalString.check(z.describe('Current asset value of this account’s Earn shares, including fees, in asset base units.'), z.meta({ examples: ['100000000'] })),
     });
+    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
@@ -251,6 +319,26 @@ export var schema;
         /** Current asset and Earn-share state for one account in one vault. */
         getEarnVaultPosition.Response = Schema.describe(position, 'Current asset and Earn-share balances, allowances, and asset value for an account in one Earn vault.');
     })(getEarnVaultPosition = schema.getEarnVaultPosition || (schema.getEarnVaultPosition = {}));
+    /** Schemas for the getEarnVaultEarnings operation. */
+    let getEarnVaultEarnings;
+    (function (getEarnVaultEarnings) {
+        /** Path parameters identifying the Earn vault and account. */
+        getEarnVaultEarnings.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. */
+        getEarnVaultEarnings.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. */
+        getEarnVaultEarnings.Response = Schema.describe(earnings, 'Indexed asset value and cost-basis-aware earnings for an account in one Earn vault.');
+    })(getEarnVaultEarnings = schema.getEarnVaultEarnings || (schema.getEarnVaultEarnings = {}));
 })(schema || (schema = {}));
 /** Creates the public Earn-vault handlers. */
 export function earn(options = {}) {
@@ -269,7 +357,7 @@ export function 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
@@ -363,7 +451,7 @@ export function earn(options = {}) {
                 schema: schema.getEarnVaultPosition.Response,
             },
         }),
-        summary: 'Get vault position',
+        summary: 'Get account position',
         tags: ['Earn'],
     }), Cache.response({
         cacheControl: Cache.policies.state,
@@ -427,6 +515,94 @@ export function earn(options = {}) {
             }
             return Response.upstream(c, cause);
         }
+    })
+        .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({
+        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 }), OpenApi.validate('param', schema.getEarnVault.Params, {
         code: 'vault_id_invalid',
@@ -450,7 +626,7 @@ export function earn(options = {}) {
                 schema: schema.getEarnVault.Response,
             },
         }),
-        summary: 'Get Earn vault',
+        summary: 'Get vault',
         tags: ['Earn'],
     }), Cache.response({
         cacheControl: Cache.policies.state,
@@ -493,6 +669,702 @@ export function earn(options = {}) {
         }
     });
 }
+/** Reads one account's indexed value and returns earnings when the history is complete. */
+export async function getVaultEarnings(c, 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' };
+        return {
+            ...base,
+            activeEarnings: (current.value - activeCostBasis).toString(),
+            status: 'complete',
+        };
+    }
+    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' };
+    if (history.pendingRedemption)
+        return { ...base, status: 'pending_redemption' };
+    const lifetimeEarnings = current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited;
+    return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' };
+}
+/** Reads cash-flow-adjusted earnings over a trailing indexed window. */
+async function getWindowVaultEarnings(c, 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' };
+    if (history.pendingRedemption)
+        return { ...base, status: 'pending_redemption' };
+    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', windowEarnings: windowEarnings.toString() };
+}
+/** Calculates cash-flow-adjusted earnings between two position snapshots. */
+export function calculateWindowEarnings(options) {
+    return (options.endingValue +
+        options.redeemed +
+        options.withdrewExact +
+        options.finalized -
+        options.deposited -
+        options.openingValue);
+}
+/** Reads the latest block whose indexed logs back the earnings calculation. */
+async function getLatestIndexedBlock(tidx) {
+    const result = await tidx.fetch({
+        engine: 'clickhouse',
+        query: 'SELECT num, timestamp FROM blocks ORDER BY num DESC LIMIT 1',
+    });
+    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, 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`,
+    });
+    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;
+}
+/** Reads the indexed cash flows and exceptional states behind one earnings calculation. */
+async function getVaultEarningsHistory(tidx, 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
+    `,
+        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),
+    };
+}
+/** Reads share balances and cross-boundary redemptions for a trailing window. */
+async function getWindowShareState(tidx, 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
+    `,
+        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,
+    };
+}
+/** Returns whether an account sent or received Earn shares outside known vault flows. */
+async function hasExternalShareTransfer(tidx, 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
+    `,
+        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;
+}
+/** Calculates the asset cost basis attached to an account's remaining Earn shares. */
+export function calculateActiveCostBasis(options) {
+    const requests = new Map();
+    let costBasis = 0n;
+    let shares = 0n;
+    const remove = (burned) => {
+        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;
+}
+/** Reads the active asset cost basis for shares held at one indexed block. */
+async function getActiveCostBasis(tidx, 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
+    `,
+        signatures: [
+            depositedSignature,
+            redeemCancelledSignature,
+            redeemRequestedSignature,
+            redeemedSignature,
+            venueSharesDepositedSignature,
+            withdrewExactSignature,
+        ],
+    });
+    const actions = [];
+    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 });
+}
 /** Lists compatible deployed Earn vaults. */
 export async function listVaults(c, options) {
     const db = Db.get(c.get('dbCached'));