tapimo 0.8.0 → 0.9.0

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

@@ -56,6 +56,8 @@ const venueSharesDepositedSignature =
 
 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'
@@ -345,8 +347,13 @@ export namespace schema {
   })
 
   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, {
@@ -395,22 +402,45 @@ export namespace schema {
           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.',
+            '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')
+        .enum(['30d', 'lifetime'])
         .check(
-          z.describe('Returns lifetime net asset earnings.'),
+          z.describe('Earnings period with an unresolved async redemption.'),
           z.meta({ examples: ['lifetime'] }),
         ),
       status: z
@@ -791,7 +821,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Gets an account’s indexed asset value and earnings for lifetime history or shares still held.',
+          '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: {
@@ -820,7 +850,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         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)
@@ -962,7 +992,17 @@ export async function getVaultEarnings(
 ) {
   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),
@@ -995,6 +1035,7 @@ export async function getVaultEarnings(
     getVaultEarningsHistory(tidx, {
       account: options.account,
       blockNumber,
+      startBlockNumber: beforeFirstBlockNumber,
       vault: options.vault,
     }),
     position,
@@ -1003,6 +1044,7 @@ export async function getVaultEarnings(
     account: options.account,
     blockNumber,
     shareToken: current.shareToken,
+    startBlockNumber: beforeFirstBlockNumber,
     vault: options.vault,
   })
   const base = {
@@ -1020,6 +1062,126 @@ export async function getVaultEarnings(
   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 = {
@@ -1031,16 +1193,45 @@ export declare namespace getVaultEarnings {
 }
 
 /** Reads the latest block whose indexed logs back the earnings calculation. */
-async function getLatestIndexedBlockNumber(tidx: Tidx.Client) {
+async function getLatestIndexedBlock(tidx: Tidx.Client) {
   const result = await tidx.fetch({
     engine: 'clickhouse',
-    query: 'SELECT num FROM blocks ORDER BY num DESC LIMIT 1' as string,
+    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 blockNumber = Value.toNumber(result.rows[0]?.['num'])
-  if (blockNumber === undefined) throw new Error('TIDX returned no indexed block.')
+  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,
@@ -1055,6 +1246,7 @@ async function getVaultEarningsHistory(
           FROM Deposited
           WHERE address = '${options.vault}'
             AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS deposited_assets,
         (
@@ -1065,6 +1257,7 @@ async function getVaultEarningsHistory(
             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,
@@ -1088,6 +1281,7 @@ async function getVaultEarningsHistory(
           FROM Redeemed
           WHERE address = '${options.vault}'
             AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS redeemed_assets,
         (
@@ -1097,6 +1291,7 @@ async function getVaultEarningsHistory(
             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
@@ -1110,6 +1305,7 @@ async function getVaultEarningsHistory(
           FROM VenueSharesDeposited
           WHERE address = '${options.vault}'
             AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS venue_deposits,
         (
@@ -1117,6 +1313,7 @@ async function getVaultEarningsHistory(
           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,
@@ -1162,6 +1359,112 @@ 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>
   }
 }
@@ -1180,10 +1483,15 @@ async function hasExternalShareTransfer(
           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()
@@ -1193,6 +1501,7 @@ async function hasExternalShareTransfer(
             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
@@ -1203,27 +1512,58 @@ async function hasExternalShareTransfer(
               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: [redeemedSignature, redeemRequestedSignature, withdrewExactSignature],
+    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.')
@@ -1235,6 +1575,7 @@ declare namespace hasExternalShareTransfer {
     account: z.output<typeof Schema.Address>
     blockNumber: number
     shareToken: z.output<typeof Schema.Address>
+    startBlockNumber: number
     vault: z.output<typeof Schema.Address>
   }
 }

package/src/apps/funding/App.ts

@@ -42,22 +42,37 @@ export declare namespace funding {
 
 const openapi = {
   tags: [
-    { name: 'Chains', description: 'Source chains and stablecoins supported for funding.' },
+    {
+      name: 'Chains',
+      description: 'Source chains and stablecoins supported for funding.',
+      'x-pagePath': 'funding/chains',
+    },
     {
       name: 'Deposit Addresses',
       description: 'Reusable funding addresses and deposits detected at those addresses.',
+      'x-pagePath': 'funding/deposit-addresses',
+    },
+    {
+      name: 'Providers',
+      description: 'Providers available for inbound funding.',
+      'x-pagePath': 'funding/providers',
+    },
+    {
+      name: 'Quotes',
+      description: 'Live quotes for funding Tempo from other chains.',
+      'x-pagePath': 'funding/quotes',
     },
-    { name: 'Providers', description: 'Providers available for inbound funding.' },
-    { name: 'Quotes', description: 'Live quotes for funding Tempo from other chains.' },
     {
-      name: 'Transfers',
+      name: 'Funding Transfers',
       description: 'Inbound funding transfers.',
+      'x-displayName': 'Transfers',
+      'x-pagePath': 'funding/transfers',
     },
   ],
   'x-tagGroups': [
     {
       name: 'Funding & Bridge API',
-      tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Transfers'],
+      tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Funding Transfers'],
     },
   ],
 } satisfies App.create.Metadata