tapimo 0.8.0 → 0.9.0

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

@@ -31,6 +31,8 @@ const redeemRequestedSignature = 'event RedeemRequested(bytes32 indexed requestI
 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. */
@@ -170,8 +172,8 @@ export var schema;
         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(['active', 'lifetime'])
-        .check(z.describe('Earnings period to calculate.'), z.meta({ examples: ['lifetime'] }));
+        .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
@@ -195,16 +197,27 @@ export var schema;
                 .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 remaining asset cost basis.'), z.meta({ examples: ['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
-                .literal('lifetime')
-                .check(z.describe('Returns lifetime net asset earnings.'), z.meta({ examples: ['lifetime'] })),
+                .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'] })),
@@ -510,7 +523,7 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Gets an account’s indexed asset value and earnings for lifetime history or shares still held.',
+        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: {
@@ -538,7 +551,7 @@ export function earn(options = {}) {
     }), Cache.response({
         cacheControl: Cache.policies.state,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
-        name: 'tempo-api:earn-vault-earnings:v2',
+        name: 'tempo-api:earn-vault-earnings:v3',
     }), async (c) => {
         if (Auth.narrowAccess)
             return Auth.paidAccessError(c);
@@ -660,7 +673,17 @@ export function earn(options = {}) {
 export async function getVaultEarnings(c, options) {
     const client = c.get('getClient')(options.chainId);
     const tidx = c.get('getTidx')(options.chainId);
-    const blockNumber = await getLatestIndexedBlockNumber(tidx);
+    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),
@@ -694,6 +717,7 @@ export async function getVaultEarnings(c, options) {
         getVaultEarningsHistory(tidx, {
             account: options.account,
             blockNumber,
+            startBlockNumber: beforeFirstBlockNumber,
             vault: options.vault,
         }),
         position,
@@ -702,6 +726,7 @@ export async function getVaultEarnings(c, options) {
         account: options.account,
         blockNumber,
         shareToken: current.shareToken,
+        startBlockNumber: beforeFirstBlockNumber,
         vault: options.vault,
     });
     const base = {
@@ -718,15 +743,105 @@ export async function getVaultEarnings(c, options) {
     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 getLatestIndexedBlockNumber(tidx) {
+async function getLatestIndexedBlock(tidx) {
     const result = await tidx.fetch({
         engine: 'clickhouse',
-        query: 'SELECT num FROM blocks ORDER BY num DESC LIMIT 1',
+        query: 'SELECT num, timestamp FROM blocks ORDER BY num DESC LIMIT 1',
     });
-    const blockNumber = Value.toNumber(result.rows[0]?.['num']);
-    if (blockNumber === undefined)
+    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. */
@@ -740,6 +855,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM Deposited
           WHERE address = '${options.vault}'
             AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS deposited_assets,
         (
@@ -750,6 +866,7 @@ async function getVaultEarningsHistory(tidx, options) {
             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,
@@ -773,6 +890,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM Redeemed
           WHERE address = '${options.vault}'
             AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS redeemed_assets,
         (
@@ -782,6 +900,7 @@ async function getVaultEarningsHistory(tidx, options) {
             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
@@ -795,6 +914,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM VenueSharesDeposited
           WHERE address = '${options.vault}'
             AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS venue_deposits,
         (
@@ -802,6 +922,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM WithdrewExact
           WHERE address = '${options.vault}'
             AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS withdrew_exact
     `,
@@ -840,6 +961,93 @@ async function getVaultEarningsHistory(tidx, options) {
         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.
@@ -851,10 +1059,15 @@ async function hasExternalShareTransfer(tidx, options) {
           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}')
+              OR (
+                "to" = '${options.account}'
+                AND "from" != '${zeroAddress}'
+                AND "from" != '${options.vault}'
+              )
             )
         ) + (
           SELECT count()
@@ -864,6 +1077,7 @@ async function hasExternalShareTransfer(tidx, options) {
             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
@@ -874,27 +1088,58 @@ async function hasExternalShareTransfer(tidx, options) {
               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: [redeemedSignature, redeemRequestedSignature, withdrewExactSignature],
+        signatures: [
+            redeemCancelledSignature,
+            redeemedSignature,
+            redeemRequestedSignature,
+            withdrewExactSignature,
+        ],
     });
     const count = Value.toNumber(result.rows[0]?.['count']);
     if (count === undefined)