tapimo 0.8.0 → 0.10.0

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

@@ -1,5 +1,6 @@
 import { type Context, Hono } from 'hono'
 import { Value as core_Value } from 'ox'
+import type { Actions } from 'viem/tempo'
 import {
   type Chain,
   ContractFunctionExecutionError,
@@ -57,6 +58,12 @@ const venueSharesDepositedSignature =
 const maxScannedDeployments = 250
 const scanLimit = 50
 
+// Concurrent metadata reads in one macrotask collapse into one deployless
+// multicall; an await between small chunks keeps each call under the RPC limit.
+const tokenReadChunkSize = 20
+/** 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'
 
@@ -155,7 +162,9 @@ export namespace schema {
           z.describe('Tokens accepted by private deposits.'),
           z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] }),
         ),
-      name: z.string().check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-e'] })),
+      name: z
+        .string()
+        .check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-moderato'] })),
       outputTokens: z
         .array(Schema.Address)
         .check(
@@ -228,7 +237,7 @@ export namespace schema {
       .nullable(value)
       .check(
         z.describe(
-          'Assets returned for one whole Earn share, in the asset display currency, or null when the engine cannot quote an exit.',
+          'Assets returned for one whole earn share, in the asset display currency, or null when the engine cannot quote an exit.',
         ),
       ),
     shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
@@ -253,7 +262,7 @@ export namespace schema {
     verified: z
       .boolean()
       .check(
-        z.describe('Whether this vault is in the curated Earn registry.'),
+        z.describe('Whether this vault is in the curated earn registry.'),
         z.meta({ examples: [true] }),
       ),
     zone: z
@@ -262,7 +271,7 @@ export namespace schema {
   })
 
   /** One compatible Earn vault resolved from current chain state. */
-  export const Vault = Schema.describe(vault, 'A compatible Earn vault resolved from chain state.')
+  export const Vault = Schema.describe(vault, 'A compatible earn vault resolved from chain state.')
 
   /** One registry-curated Earn vault. */
   export const VerifiedVault = Schema.describe(
@@ -277,16 +286,16 @@ export namespace schema {
       verified: z
         .literal(true)
         .check(
-          z.describe('This vault is in the curated Earn registry.'),
+          z.describe('This vault is in the curated earn registry.'),
           z.meta({ examples: [true] }),
         ),
     }),
-    'A registry-curated Earn vault resolved from chain state.',
+    'A registry-curated earn vault resolved from chain state.',
   )
 
   const position = z.strictObject({
     account: Schema.Address.check(
-      z.describe('Account whose Earn position was read.'),
+      z.describe('Account whose earn position was read.'),
       z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
     ),
     assetAllowance: Schema.DecimalString.check(
@@ -313,16 +322,49 @@ export namespace schema {
       z.meta({ examples: ['99500000'] }),
     ),
     shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(
-      z.describe('TIP-20 token representing Earn shares.'),
+      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.',
+        'Current asset value of this account’s earn shares, including fees, in asset base units.',
       ),
       z.meta({ examples: ['100000000'] }),
     ),
   })
 
+  const addressPosition = z.strictObject({
+    assetAmount: value.check(
+      z.describe('Current asset value of the held shares, including fees, in `assetToken` units.'),
+    ),
+    assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
+    id: Schema.Address.check(
+      z.describe('Stable resource ID for this position, equal to the vault address.'),
+      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+    ),
+    shareAmount: value.check(
+      z.describe('Earn share balance this account holds, in `shareToken` units.'),
+    ),
+    shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+    valuation: z
+      .optional(z.nullable(Valuation.schema.Value))
+      .check(
+        z.describe(
+          'The position’s nominal value when `valuation.currency` is requested, or `null` when ' +
+            'the asset token is unverified, its display currency has no rate, or rates were unavailable.',
+        ),
+      ),
+    vaultAddress: Schema.Address.check(
+      z.describe('Earn vault contract address holding this position.'),
+      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+    ),
+    verified: z
+      .boolean()
+      .check(
+        z.describe('Whether the vault is in the curated earn registry.'),
+        z.meta({ examples: [true] }),
+      ),
+  })
+
   const earningsBase = z.strictObject({
     account: Schema.Address.check(
       z.describe('Account whose vault earnings were calculated.'),
@@ -334,7 +376,7 @@ export namespace schema {
     ),
     currentValue: Schema.DecimalString.check(
       z.describe(
-        'Asset value of the account’s active Earn shares at the latest indexed block, in asset base units.',
+        'Asset value of the account’s active earn shares at the latest indexed block, in asset base units.',
       ),
       z.meta({ examples: ['600000'] }),
     ),
@@ -345,8 +387,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 +442,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
@@ -453,7 +523,7 @@ export namespace schema {
 
   const collectionQuery = z
     .extend(collectionFilters, { 'apy.window': EarnRates.schema.Window })
-    .check(z.describe('Query parameters for listing Earn vaults.'))
+    .check(z.describe('Query parameters for listing earn vaults.'))
 
   const vaultSelector = z.strictObject({
     chainId: Schema.ChainIdQuery,
@@ -470,11 +540,11 @@ export namespace schema {
       .strictObject({
         data: z
           .array(Vault)
-          .check(z.describe('Compatible deployed Earn vaults in deployment order.')),
+          .check(z.describe('Compatible deployed earn vaults in deployment order.')),
         meta: z.optional(meta),
         nextCursor: Schema.NextCursor,
       })
-      .check(z.describe('A page of compatible deployed Earn vaults.'))
+      .check(z.describe('A page of compatible deployed earn vaults.'))
   }
 
   /** Schemas for the getVerifiedEarnVaults operation. */
@@ -482,7 +552,7 @@ export namespace schema {
     /** Collection query without rates or valuation, for surfaces that cannot measure them. */
     export const BaseQuery = Schema.describe(
       z.extend(collectionFilters, { include: baseIncludeQuery }),
-      'Query parameters for listing Earn vaults.',
+      'Query parameters for listing earn vaults.',
     )
 
     /** Query parameters for registry-curated Earn vaults. */
@@ -493,37 +563,95 @@ export namespace schema {
       .strictObject({
         data: z
           .array(VerifiedVault)
-          .check(z.describe('Registry-curated Earn vaults ordered by vault address.')),
+          .check(z.describe('Registry-curated earn vaults ordered by vault address.')),
         meta: z.optional(meta),
         nextCursor: Schema.NextCursor,
       })
-      .check(z.describe('A page of registry-curated Earn vaults.'))
+      .check(z.describe('A page of registry-curated earn vaults.'))
+  }
+
+  /** Schemas for the getEarnAddressPositions operation. */
+  export namespace getEarnAddressPositions {
+    /** Path parameters identifying the account. */
+    export const Params = z
+      .strictObject({
+        address: Schema.Address.check(z.describe('Account whose earn positions to list.')),
+      })
+      .check(z.describe('Path parameters identifying an account with earn positions.'))
+
+    /** Query parameters for listing an account's earn positions. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        limit: Schema.Limit,
+        'valuation.currency': Schema.Denomination.check(
+          z.describe(
+            'When present, include each position’s nominal value in this denomination. ' +
+              'Case-insensitive and must be priced by the configured FX oracle.',
+          ),
+        ),
+        verified: z
+          .optional(Schema.booleanQuery())
+          .check(
+            z.describe(
+              'When `true`, include only positions in registry-curated (verified) earn vaults.',
+            ),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(z.describe('Query parameters for listing an account’s earn positions.'))
+
+    /** Page-level valuation rate provenance. */
+    export const Meta = z
+      .object({
+        valuation: z
+          .optional(Valuation.schema.Pricing)
+          .check(
+            z.describe(
+              'Rate provenance for row valuations. Present when conversion rates were ' +
+                'consulted; absent when every value was identity-valued or rates were unavailable.',
+            ),
+          ),
+      })
+      .check(z.describe('Page-level valuation rate provenance.'))
+
+    /** Paginated list of the account's earn vault positions. */
+    export const Response = z
+      .strictObject({
+        data: z
+          .array(addressPosition)
+          .check(z.describe('Vaults where the account holds earn shares.')),
+        meta: z.optional(Meta),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of the account’s earn vault positions.'))
   }
 
   /** Schemas for the getEarnVault operation. */
   export namespace getEarnVault {
-    /** Path parameters identifying one Earn vault. */
+    /** Path parameters identifying one earn vault. */
     export const Params = z
       .strictObject({
         vaultId: Schema.Address.check(z.describe('Earn vault contract address.')),
       })
-      .check(z.describe('Path parameters identifying one Earn vault.'))
+      .check(z.describe('Path parameters identifying one earn vault.'))
 
     /** Detail query without rates or valuation, for surfaces that cannot measure them. */
     export const BaseQuery = Schema.describe(
       z.extend(vaultSelector, { include: baseIncludeQuery }),
-      'Query parameters selecting one Earn vault.',
+      'Query parameters selecting one earn vault.',
     )
 
     /** Query parameters selecting the chain containing the vault. */
     export const Query = z
       .extend(vaultSelector, { 'apy.window': EarnRates.schema.Window })
-      .check(z.describe('Query parameters selecting one Earn vault.'))
+      .check(z.describe('Query parameters selecting one earn vault.'))
 
     /** One compatible Earn vault resolved directly from current chain state. */
     export const Response = Schema.describe(
       z.extend(vault, { meta: z.optional(meta) }),
-      'A compatible Earn vault resolved from chain state, with rate provenance for its valued fields.',
+      'A compatible earn vault resolved from chain state, with rate provenance for its valued fields.',
     )
   }
 
@@ -532,22 +660,22 @@ export namespace schema {
     /** Path parameters identifying the Earn vault and account. */
     export const Params = z
       .strictObject({
-        address: Schema.Address.check(z.describe('Account whose Earn position to read.')),
+        address: Schema.Address.check(z.describe('Account whose earn position to read.')),
         vaultId: Schema.address('0xdb48b00fb28d9a8db881fcd671c3fb1bf8c486b6').check(
           z.describe('Earn vault contract address.'),
         ),
       })
-      .check(z.describe('Path parameters identifying an Earn vault position.'))
+      .check(z.describe('Path parameters identifying an earn vault position.'))
 
     /** Query parameters selecting the chain containing the vault. */
     export const Query = z
       .strictObject({ chainId: Schema.ChainIdQuery })
-      .check(z.describe('Query parameters selecting an Earn vault position.'))
+      .check(z.describe('Query parameters selecting an earn vault position.'))
 
     /** Current asset and Earn-share state for one account in one vault. */
     export const Response = Schema.describe(
       position,
-      'Current asset and Earn-share balances, allowances, and asset value for an account in one Earn vault.',
+      'Current asset and earn-share balances, allowances, and asset value for an account in one earn vault.',
     )
   }
 
@@ -561,7 +689,7 @@ export namespace schema {
           z.describe('Earn vault contract address.'),
         ),
       })
-      .check(z.describe('Path parameters identifying an Earn vault account.'))
+      .check(z.describe('Path parameters identifying an earn vault account.'))
 
     /** Query parameters selecting the chain containing the vault. */
     export const Query = z
@@ -569,12 +697,12 @@ export namespace schema {
         chainId: Schema.ChainIdQuery,
         period: z._default(earningsPeriod, 'lifetime'),
       })
-      .check(z.describe('Query parameters selecting an Earn vault account.'))
+      .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.',
+      'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.',
     )
   }
 }
@@ -592,12 +720,12 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists compatible Earn vaults discovered from deployment events and resolved from current chain state.',
+          'Lists compatible earn vaults discovered from deployment events and resolved from current chain state.',
         operationId: 'getEarnVaults',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read Earn deployment or vault data.' },
+          errors: { 502: 'Could not read earn deployment or vault data.' },
           success: {
-            description: 'A page of compatible deployed Earn vaults.',
+            description: 'A page of compatible deployed earn vaults.',
             schema: schema.getEarnVaults.Response,
           },
         }),
@@ -638,12 +766,12 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists registry-curated Earn vaults after resolving their current onchain configuration.',
+          'Lists registry-curated earn vaults after resolving their current onchain configuration.',
         operationId: 'getVerifiedEarnVaults',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read curated Earn registry or vault data.' },
+          errors: { 502: 'Could not read curated earn registry or vault data.' },
           success: {
-            description: 'A page of registry-curated Earn vaults.',
+            description: 'A page of registry-curated earn vaults.',
             schema: schema.getVerifiedEarnVaults.Response,
           },
         }),
@@ -673,6 +801,86 @@ export function earn(options: earn.Options = {}) {
         }
       },
     )
+    .get(
+      '/v1/earn/addresses/:address/positions',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnAddressPositions.Params, {
+        code: 'positions_invalid',
+        message: 'Invalid address positions',
+      }),
+      OpenApi.validate('query', schema.getEarnAddressPositions.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Lists every earn vault where an account currently holds shares, with the current balance and value of each position.',
+        operationId: 'getEarnAddressPositions',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'positions_invalid',
+                'query_invalid',
+              ],
+            },
+            502: 'Could not read earn deployment or position data.',
+          },
+          success: {
+            description: 'A page of the account’s earn vault positions.',
+            schema: schema.getEarnAddressPositions.Response,
+          },
+        }),
+        summary: 'List account positions',
+        tags: ['Earn'],
+      }),
+      // `noStore` matches the address balances listing: account holdings must
+      // read fresh immediately after a deposit or redemption.
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        key: (c) => Cache.urlKey(c, schema.getEarnAddressPositions.Query),
+        name: 'tempo-api:earn-address-positions:v1',
+      }),
+      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: 'positions_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const { address } = c.req.valid('param')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const data = await listPositions(c, { ...query, address, chainId, oracle })
+          return c.json(Response.validated(schema.getEarnAddressPositions.Response, data), 200)
+        } catch (cause) {
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .get(
       '/v1/earn/vaults/:vaultId/positions/:address',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -686,7 +894,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Gets an account’s asset and Earn-share balances, allowances, and current asset value for one Earn vault.',
+          'Gets an account’s asset and earn-share balances, allowances, and current asset value for one earn vault.',
         operationId: 'getEarnVaultPosition',
         responses: OpenApi.responses({
           errors: {
@@ -700,12 +908,12 @@ export function earn(options: earn.Options = {}) {
             },
             404: {
               codes: ['earn_vault_not_found'],
-              description: 'No compatible Earn vault was found at the supplied vault address.',
+              description: 'No compatible earn vault was found at the supplied vault address.',
             },
-            502: 'Could not read the Earn vault position.',
+            502: 'Could not read the earn vault position.',
           },
           success: {
-            description: 'Current Earn position for one account in one vault.',
+            description: 'Current earn position for one account in one vault.',
             schema: schema.getEarnVaultPosition.Response,
           },
         }),
@@ -791,7 +999,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: {
@@ -805,9 +1013,9 @@ export function earn(options: earn.Options = {}) {
             },
             404: {
               codes: ['earn_vault_not_found'],
-              description: 'No compatible Earn vault was found at this address.',
+              description: 'No compatible earn vault was found at this address.',
             },
-            502: 'Could not read the Earn vault earnings.',
+            502: 'Could not read the earn vault earnings.',
           },
           success: {
             description: 'Cost-basis-aware earnings for one account in one vault.',
@@ -820,7 +1028,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)
@@ -886,18 +1094,18 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Resolves any compatible Earn vault directly from current chain state and enriches it when curated.',
+          'Resolves any compatible earn vault directly from current chain state and enriches it when curated.',
         operationId: 'getEarnVault',
         responses: OpenApi.responses({
           errors: {
             404: {
               codes: ['earn_vault_not_found'],
-              description: 'No compatible Earn vault was found at this address.',
+              description: 'No compatible earn vault was found at this address.',
             },
-            502: 'Could not read Earn vault data.',
+            502: 'Could not read earn vault data.',
           },
           success: {
-            description: 'One compatible Earn vault.',
+            description: 'One compatible earn vault.',
             schema: schema.getEarnVault.Response,
           },
         }),
@@ -962,7 +1170,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 +1213,7 @@ export async function getVaultEarnings(
     getVaultEarningsHistory(tidx, {
       account: options.account,
       blockNumber,
+      startBlockNumber: beforeFirstBlockNumber,
       vault: options.vault,
     }),
     position,
@@ -1003,6 +1222,7 @@ export async function getVaultEarnings(
     account: options.account,
     blockNumber,
     shareToken: current.shareToken,
+    startBlockNumber: beforeFirstBlockNumber,
     vault: options.vault,
   })
   const base = {
@@ -1020,6 +1240,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 +1371,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 +1424,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 +1435,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 +1459,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 +1469,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 +1483,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 +1491,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 +1537,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 +1661,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 +1679,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 +1690,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 +1753,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>
   }
 }
@@ -1699,6 +2218,270 @@ export declare namespace listVerifiedVaults {
   }
 }
 
+/** Lists every vault where an account holds earn shares, ordered by vault address. */
+export async function listPositions(c: Context<App.Environment>, options: listPositions.Options) {
+  const denomination = options['valuation.currency']
+  const db = Db.get(c.get('dbCached'))
+  const recordsPromise = core_EarnVaults.list(db, { chainId: options.chainId })
+  // The verified page needs no index: the registry is the candidate set.
+  const heldPromise = options.verified
+    ? undefined
+    : queryHeldVaults(c, { address: options.address, chainId: options.chainId })
+  // Observing these branches prevents unhandled rejections while the
+  // denomination validates; the later await still propagates them.
+  void recordsPromise.catch(() => undefined)
+  void heldPromise?.catch(() => undefined)
+  // Validation resolves before discovery results are consumed, so a dependency
+  // failure cannot mask a caller error.
+  if (denomination)
+    await Valuation.ratesFor(c, { currencies: [], denomination, oracle: options.oracle })
+  const [records, held] = await Promise.all([recordsPromise, heldPromise])
+  const registry = new Map(records.map((record) => [record.vaultAddress.toLowerCase(), record]))
+  const vaults = held ?? [...registry.keys()].sort()
+  const decoded = options.cursor ? Cursor.decode(options.cursor, ['address']) : undefined
+  const cursor = decoded?.[0]?.toString().toLowerCase()
+  const candidates = vaults.filter((vault) => !cursor || vault > cursor)
+  const matches: listPositions.Match[] = []
+
+  let offset = 0
+  // The deployment-scan bound also caps per-request position reads, so a long
+  // exited-position history pages through candidates instead of probing them all.
+  while (
+    offset < candidates.length &&
+    matches.length <= options.limit &&
+    offset < maxScannedDeployments
+  ) {
+    const batchSize = discoveryBatchLimit({
+      // Zero-share candidates are read and then rejected, so batches over-fetch.
+      filtered: true,
+      limit: options.limit,
+      matches: matches.length,
+      remaining: Math.min(candidates.length, maxScannedDeployments) - offset,
+    })
+    const batch = candidates.slice(offset, offset + batchSize)
+    offset += batch.length
+    const read = await Timing.time(c, 'earn_positions', () =>
+      Promise.all(
+        batch.map(async (vault) => {
+          const record = registry.get(vault)
+          try {
+            const position = await readPosition(c, {
+              address: options.address,
+              chainId: options.chainId,
+              vaultAddress: Schema.Address.parse(vault),
+            })
+            return { position, record, vaultAddress: vault }
+          } catch (cause) {
+            if (!record && isIncompatible(cause)) return undefined
+            throw cause
+          }
+        }),
+      ),
+    )
+    for (const match of read) {
+      if (!match || match.position.shareBalance === 0n) continue
+      matches.push(match)
+    }
+  }
+
+  const page = matches.slice(0, options.limit)
+  const [tokens, snapshot] = await Promise.all([
+    (async () => {
+      const addresses = [
+        ...new Set(page.flatMap(({ position }) => [position.assetToken, position.shareToken])),
+      ]
+      const groups: Tokens.resolveTokens.ReturnType[] = []
+      for (let index = 0; index < addresses.length; index += tokenReadChunkSize)
+        groups.push(
+          await Tokens.resolveTokens(c, {
+            addresses: addresses.slice(index, index + tokenReadChunkSize),
+            chainId: options.chainId,
+            include: ['token.verified'],
+          }),
+        )
+      return new Map(groups.flatMap((group) => [...group]))
+    })(),
+    denomination ? VerifiedTokens.snapshot(c, options.chainId) : undefined,
+  ])
+  const rates =
+    denomination && snapshot
+      ? await Valuation.ratesFor(c, {
+          currencies: page.flatMap(({ position }) => {
+            const currency = snapshot.byAddress.get(position.assetToken.toLowerCase())?.currency
+            return currency === undefined ? [] : [currency]
+          }),
+          denomination,
+          oracle: options.oracle,
+        })
+      : undefined
+  const last = matches[options.limit - 1]
+  // A scan-bound exit resumes from the last probed candidate so a truncated
+  // page never hides positions deeper in the candidate list.
+  const next =
+    matches.length > options.limit
+      ? last?.vaultAddress
+      : offset < candidates.length
+        ? candidates[offset - 1]
+        : undefined
+  return {
+    data: page.map((match) =>
+      serializePosition({
+        denomination,
+        position: match.position,
+        rates,
+        snapshot,
+        tokens,
+        vaultAddress: match.vaultAddress,
+        verified: match.record !== undefined,
+      }),
+    ),
+    ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
+    nextCursor: next ? Cursor.encode([next]) : null,
+  }
+}
+
+export declare namespace listPositions {
+  /** One candidate vault holding a non-zero position. */
+  type Match = {
+    position: Actions.earn.getPosition.ReturnValue
+    record?: RegistryRecord | undefined
+    vaultAddress: string
+  }
+
+  /** Options for listing an account's earn positions. */
+  type Options = z.output<typeof schema.getEarnAddressPositions.Query> & {
+    /** Account whose positions to list. */
+    address: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    /** FX rate oracle backing per-row valuation. */
+    oracle: FxOracle.Oracle
+  }
+}
+
+/** Finds vaults whose earn share token the account has ever held, by vault address. */
+async function queryHeldVaults(
+  c: Context<App.Environment>,
+  options: queryHeldVaults.Options,
+): Promise<readonly string[]> {
+  const tidx = c.get('getTidx')(options.chainId)
+  // Each vault's newest deployment binds its current share token; joining it
+  // against the account's holder deltas server-side turns holdings into vault
+  // candidates in one round trip, with no literal list to overflow the request.
+  // Earn shares are factory-minted TIP-20s, so the `0x20c0` prefix bounds the
+  // subquery. Stale delta rows are fine: the live read drops them.
+  const result = await Timing.time(c, 'earn_positions_discovery', () =>
+    tidx.fetch({
+      chainId: options.chainId,
+      engine: 'clickhouse',
+      query: `
+        SELECT "earnVault"
+        FROM (
+          SELECT
+            "earnVault",
+            "earnShare",
+            row_number() OVER (
+              PARTITION BY lower("earnVault")
+              ORDER BY block_num DESC, log_idx DESC
+            ) AS deployment_rank
+          FROM EarnStackDeployed
+        )
+        WHERE deployment_rank = 1 AND lower("earnShare") IN (
+          SELECT DISTINCT lower(token)
+          FROM address_holder_deltas
+          WHERE holder = '${options.address}' AND startsWith(token, '0x20c0')
+        )
+        ORDER BY lower("earnVault") ASC
+      ` as string,
+      signatures: [deployedSignature],
+    }),
+  )
+  const rows: readonly Record<string, unknown>[] = result.rows
+  return rows.flatMap((row) => {
+    const vault = Schema.Address.safeParse(Value.toText(row['earnVault']))
+    return vault.success ? [vault.data.toLowerCase()] : []
+  })
+}
+
+declare namespace queryHeldVaults {
+  /** Inputs selecting an account's held earn share tokens. */
+  type Options = {
+    address: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+  }
+}
+
+/** Reads one account's live position in one vault. */
+function readPosition(
+  c: Context<App.Environment>,
+  options: readPosition.Options,
+): Promise<Actions.earn.getPosition.ReturnValue> {
+  return c
+    .get('getClient')(options.chainId)
+    .earn.getPosition({ account: options.address, vault: options.vaultAddress })
+}
+
+declare namespace readPosition {
+  /** Inputs selecting one vault position. */
+  type Options = {
+    address: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    vaultAddress: z.output<typeof Schema.Address>
+  }
+}
+
+/** Serializes one live position into the address-scoped row contract. */
+function serializePosition(options: serializePosition.Options) {
+  const { position, tokens } = options
+  const assetToken = getToken(tokens, position.assetToken)
+  const shareToken = getToken(tokens, position.shareToken)
+  const vaultAddress = Schema.Address.parse(options.vaultAddress.toLowerCase())
+  return {
+    assetAmount: valueFor(position.value, assetToken),
+    assetToken,
+    id: vaultAddress,
+    shareAmount: valueFor(position.shareBalance, shareToken),
+    shareToken,
+    ...(options.denomination
+      ? {
+          valuation: Valuation.valuationFor({
+            amount: position.value,
+            denomination: options.denomination,
+            rates: options.rates,
+            token: options.snapshot?.byAddress.get(assetToken.address),
+          }),
+        }
+      : {}),
+    vaultAddress,
+    verified: options.verified,
+  }
+}
+
+declare namespace serializePosition {
+  /** Values used to serialize one account position row. */
+  type Options = {
+    /** Currency the row valuation is denominated in (uppercase). */
+    denomination?: string | undefined
+    position: Actions.earn.getPosition.ReturnValue
+    /** Consulted FX rate set, or undefined when unavailable or unnecessary. */
+    rates: Awaited<ReturnType<typeof Valuation.ratesFor>>
+    /** Curated token snapshot backing valuation, present when requested. */
+    snapshot?: VerifiedTokens.Snapshot | undefined
+    tokens: Tokens.resolveTokens.ReturnType
+    vaultAddress: string
+    verified: boolean
+  }
+}
+
+/** Renders a base-unit amount in the token's display currency and precision. */
+function valueFor(amount: bigint, token: z.output<typeof Tokens.schema.Token>) {
+  return {
+    amount: amount.toString(),
+    currency: token.currency,
+    decimals: token.decimals,
+    formatted: core_Value.format(amount, token.decimals),
+  }
+}
+
 /** Gets one compatible Earn vault. */
 export async function getVault(c: Context<App.Environment>, options: getVault.Options) {
   const db = Db.get(c.get('dbCached'))