tapimo 0.9.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,
@@ -56,6 +57,10 @@ 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
 
@@ -157,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(
@@ -230,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.')),
@@ -255,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
@@ -264,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(
@@ -279,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(
@@ -315,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.'),
@@ -336,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'] }),
     ),
@@ -483,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,
@@ -500,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. */
@@ -512,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. */
@@ -523,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.',
     )
   }
 
@@ -562,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.',
     )
   }
 
@@ -591,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
@@ -599,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.',
     )
   }
 }
@@ -622,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,
           },
         }),
@@ -668,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,
           },
         }),
@@ -703,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 }),
@@ -716,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: {
@@ -730,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,
           },
         }),
@@ -835,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.',
@@ -916,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,
           },
         }),
@@ -2040,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'))