tapimo 0.8.0 → 0.10.0

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

@@ -31,6 +31,11 @@ const redeemRequestedSignature = 'event RedeemRequested(bytes32 indexed requestI
 const venueSharesDepositedSignature = 'event VenueSharesDeposited(address indexed caller,address indexed receiver,uint256 requestedVenueShares,uint256 receivedVenueShares,uint256 earnShares)';
 const maxScannedDeployments = 250;
 const scanLimit = 50;
+// 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';
 /** `Valuation.valuationFor` floors to 6 dp, so 6 is the precision a valued amount carries. */
@@ -83,7 +88,9 @@ export var schema;
         inputTokens: z
             .array(Schema.Address)
             .check(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(z.describe('Tokens supported by private redemptions.'), z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] })),
@@ -123,7 +130,7 @@ export var schema;
             .check(z.describe('Vault display label.'), z.meta({ examples: ['btPATHUSD Earn'] })),
         sharePrice: z
             .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.')),
+            .check(z.describe('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.')),
         slug: z
             .nullable(z.string())
@@ -135,13 +142,13 @@ export var schema;
         vaultAddress: Schema.Address.check(z.describe('Earn vault contract address.'), z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] })),
         verified: z
             .boolean()
-            .check(z.describe('Whether this vault is in the curated Earn registry.'), z.meta({ examples: [true] })),
+            .check(z.describe('Whether this vault is in the curated earn registry.'), z.meta({ examples: [true] })),
         zone: z
             .optional(z.nullable(zone))
             .check(z.describe('Curated private Zone route, when requested, or null when absent.')),
     });
     /** One compatible Earn vault resolved from current chain state. */
-    schema.Vault = Schema.describe(vault, 'A compatible Earn vault resolved from chain state.');
+    schema.Vault = Schema.describe(vault, 'A compatible earn vault resolved from chain state.');
     /** One registry-curated Earn vault. */
     schema.VerifiedVault = Schema.describe(z.extend(vault, {
         engine: z.extend(engine, { type: engineType }),
@@ -150,28 +157,43 @@ export var schema;
             .check(z.describe('Stable curated vault slug.'), z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] })),
         verified: z
             .literal(true)
-            .check(z.describe('This vault is in the curated Earn registry.'), z.meta({ examples: [true] })),
-    }), 'A registry-curated Earn vault resolved from chain state.');
+            .check(z.describe('This vault is in the curated earn registry.'), z.meta({ examples: [true] })),
+    }), '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.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] })),
+        account: Schema.Address.check(z.describe('Account whose earn position was read.'), z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] })),
         assetAllowance: Schema.DecimalString.check(z.describe('Assets the vault may spend from this account, in asset base units.'), z.meta({ examples: ['0'] })),
         assetBalance: Schema.DecimalString.check(z.describe('Assets this account currently holds, in asset base units.'), z.meta({ examples: ['250000000'] })),
         assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(z.describe('TIP-20 asset token accepted by the vault.')),
         id: Schema.Address.check(z.describe('Stable resource ID for this vault position, equal to the account address.'), z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] })),
         shareAllowance: Schema.DecimalString.check(z.describe('Earn shares the vault may spend from this account, in share base units.'), z.meta({ examples: ['0'] })),
         shareBalance: Schema.DecimalString.check(z.describe('Earn shares this account currently holds, in share base units.'), z.meta({ examples: ['99500000'] })),
-        shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(z.describe('TIP-20 token representing Earn shares.')),
-        value: Schema.DecimalString.check(z.describe('Current asset value of this account’s Earn shares, including fees, in asset base units.'), z.meta({ examples: ['100000000'] })),
+        shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(z.describe('TIP-20 token representing earn shares.')),
+        value: Schema.DecimalString.check(z.describe('Current asset value of this account’s earn shares, including fees, in asset base units.'), z.meta({ examples: ['100000000'] })),
+    });
+    const 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.'), z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] })),
         assetToken: Schema.TokenAddress.check(z.describe('TIP-20 asset token accepted by the vault.'), z.meta({ examples: ['0x20c000000000000000000000ff04042ee92fd449'] })),
-        currentValue: Schema.DecimalString.check(z.describe('Asset value of the account’s active Earn shares at the latest indexed block, in asset base units.'), z.meta({ examples: ['600000'] })),
+        currentValue: Schema.DecimalString.check(z.describe('Asset value of the account’s active earn shares at the latest indexed block, in asset base units.'), z.meta({ examples: ['600000'] })),
         id: Schema.Address.check(z.describe('Stable resource ID for these vault earnings, equal to the account address.'), z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] })),
     });
     const earningsPeriod = z
-        .enum(['active', 'lifetime'])
-        .check(z.describe('Earnings period to calculate.'), z.meta({ examples: ['lifetime'] }));
+        .enum(['30d', 'active', 'lifetime'])
+        .check(z.describe('Earnings period to calculate: trailing 30 days, shares still held, or lifetime history.'), z.meta({ examples: ['lifetime'] }));
     const earnings = z.union([
         z.extend(earningsBase, {
             lifetimeEarnings: z
@@ -195,16 +217,27 @@ export var schema;
                 .literal('complete')
                 .check(z.describe('Earnings include a complete asset-denominated cost basis.'), z.meta({ examples: ['complete'] })),
         }),
+        z.extend(earningsBase, {
+            period: z
+                .literal('30d')
+                .check(z.describe('Returns cash-flow-adjusted earnings over the trailing 30 days.'), z.meta({ examples: ['30d'] })),
+            status: z
+                .literal('complete')
+                .check(z.describe('Earnings include a complete asset-denominated cost basis.'), z.meta({ examples: ['complete'] })),
+            windowEarnings: z
+                .string()
+                .check(z.regex(/^-?\d+$/), z.describe('Ending share value plus realized assets, minus deposits and opening share value, over the trailing 30 days.'), z.meta({ examples: ['0'] })),
+        }),
         z.extend(earningsBase, {
             period: earningsPeriod,
             status: z
                 .literal('incomplete_cost_basis')
-                .check(z.describe('Earnings are unavailable when indexed activity cannot reconstruct the remaining asset cost basis.'), z.meta({ examples: ['incomplete_cost_basis'] })),
+                .check(z.describe('Earnings are unavailable when indexed activity cannot reconstruct the asset cost basis for the requested period.'), z.meta({ examples: ['incomplete_cost_basis'] })),
         }),
         z.extend(earningsBase, {
             period: z
-                .literal('lifetime')
-                .check(z.describe('Returns lifetime net asset earnings.'), z.meta({ examples: ['lifetime'] })),
+                .enum(['30d', 'lifetime'])
+                .check(z.describe('Earnings period with an unresolved async redemption.'), z.meta({ examples: ['lifetime'] })),
             status: z
                 .literal('pending_redemption')
                 .check(z.describe('Earnings are unavailable while an async redemption remains open.'), z.meta({ examples: ['pending_redemption'] })),
@@ -232,7 +265,7 @@ export var 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,
         include: includeQuery,
@@ -247,17 +280,17 @@ export var schema;
             .strictObject({
             data: z
                 .array(schema.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.'));
     })(getEarnVaults = schema.getEarnVaults || (schema.getEarnVaults = {}));
     /** Schemas for the getVerifiedEarnVaults operation. */
     let getVerifiedEarnVaults;
     (function (getVerifiedEarnVaults) {
         /** Collection query without rates or valuation, for surfaces that cannot measure them. */
-        getVerifiedEarnVaults.BaseQuery = Schema.describe(z.extend(collectionFilters, { include: baseIncludeQuery }), 'Query parameters for listing Earn vaults.');
+        getVerifiedEarnVaults.BaseQuery = Schema.describe(z.extend(collectionFilters, { include: baseIncludeQuery }), 'Query parameters for listing earn vaults.');
         /** Query parameters for registry-curated Earn vaults. */
         getVerifiedEarnVaults.Query = collectionQuery;
         /** Paginated list of registry-curated Earn vaults. */
@@ -265,29 +298,71 @@ export var schema;
             .strictObject({
             data: z
                 .array(schema.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.'));
     })(getVerifiedEarnVaults = schema.getVerifiedEarnVaults || (schema.getVerifiedEarnVaults = {}));
+    /** Schemas for the getEarnAddressPositions operation. */
+    let getEarnAddressPositions;
+    (function (getEarnAddressPositions) {
+        /** Path parameters identifying the account. */
+        getEarnAddressPositions.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. */
+        getEarnAddressPositions.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. */
+        getEarnAddressPositions.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. */
+        getEarnAddressPositions.Response = z
+            .strictObject({
+            data: z
+                .array(addressPosition)
+                .check(z.describe('Vaults where the account holds earn shares.')),
+            meta: z.optional(getEarnAddressPositions.Meta),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of the account’s earn vault positions.'));
+    })(getEarnAddressPositions = schema.getEarnAddressPositions || (schema.getEarnAddressPositions = {}));
     /** Schemas for the getEarnVault operation. */
     let getEarnVault;
     (function (getEarnVault) {
-        /** Path parameters identifying one Earn vault. */
+        /** Path parameters identifying one earn vault. */
         getEarnVault.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. */
-        getEarnVault.BaseQuery = Schema.describe(z.extend(vaultSelector, { include: baseIncludeQuery }), 'Query parameters selecting one Earn vault.');
+        getEarnVault.BaseQuery = Schema.describe(z.extend(vaultSelector, { include: baseIncludeQuery }), 'Query parameters selecting one earn vault.');
         /** Query parameters selecting the chain containing the vault. */
         getEarnVault.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. */
-        getEarnVault.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.');
+        getEarnVault.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.');
     })(getEarnVault = schema.getEarnVault || (schema.getEarnVault = {}));
     /** Schemas for the getEarnVaultPosition operation. */
     let getEarnVaultPosition;
@@ -295,16 +370,16 @@ export var schema;
         /** Path parameters identifying the Earn vault and account. */
         getEarnVaultPosition.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. */
         getEarnVaultPosition.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. */
-        getEarnVaultPosition.Response = Schema.describe(position, 'Current asset and Earn-share balances, allowances, and asset value for an account in one Earn vault.');
+        getEarnVaultPosition.Response = Schema.describe(position, 'Current asset and earn-share balances, allowances, and asset value for an account in one earn vault.');
     })(getEarnVaultPosition = schema.getEarnVaultPosition || (schema.getEarnVaultPosition = {}));
     /** Schemas for the getEarnVaultEarnings operation. */
     let getEarnVaultEarnings;
@@ -315,16 +390,16 @@ export var schema;
             address: Schema.Address.check(z.describe('Account whose vault earnings to read.')),
             vaultId: Schema.address('0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a').check(z.describe('Earn vault contract address.')),
         })
-            .check(z.describe('Path parameters identifying an Earn vault account.'));
+            .check(z.describe('Path parameters identifying an earn vault account.'));
         /** Query parameters selecting the chain containing the vault. */
         getEarnVaultEarnings.Query = z
             .strictObject({
             chainId: Schema.ChainIdQuery,
             period: z._default(earningsPeriod, 'lifetime'),
         })
-            .check(z.describe('Query parameters selecting an Earn vault account.'));
+            .check(z.describe('Query parameters selecting an earn vault account.'));
         /** Earnings for one account and period in one Earn vault. */
-        getEarnVaultEarnings.Response = Schema.describe(earnings, 'Indexed asset value and cost-basis-aware earnings for an account in one Earn vault.');
+        getEarnVaultEarnings.Response = Schema.describe(earnings, 'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.');
     })(getEarnVaultEarnings = schema.getEarnVaultEarnings || (schema.getEarnVaultEarnings = {}));
 })(schema || (schema = {}));
 /** Creates the public Earn-vault handlers. */
@@ -335,12 +410,12 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Lists compatible Earn vaults discovered from deployment events and resolved from current chain state.',
+        description: '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,
             },
         }),
@@ -375,12 +450,12 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Lists registry-curated Earn vaults after resolving their current onchain configuration.',
+        description: '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,
             },
         }),
@@ -407,6 +482,79 @@ export function earn(options = {}) {
         catch (cause) {
             return Response.upstream(c, cause);
         }
+    })
+        .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({
+        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 }), OpenApi.validate('param', schema.getEarnVaultPosition.Params, {
         code: 'position_invalid',
@@ -415,7 +563,7 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Gets an account’s asset and Earn-share balances, allowances, and current asset value for one Earn vault.',
+        description: 'Gets an account’s asset and earn-share balances, allowances, and current asset value for one earn vault.',
         operationId: 'getEarnVaultPosition',
         responses: OpenApi.responses({
             errors: {
@@ -429,12 +577,12 @@ export function 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,
             },
         }),
@@ -510,7 +658,7 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Gets an account’s indexed asset value and earnings for lifetime history or shares still held.',
+        description: 'Gets an account’s indexed asset value and earnings for lifetime history, the trailing 30 days, or shares still held.',
         operationId: 'getEarnVaultEarnings',
         responses: OpenApi.responses({
             errors: {
@@ -524,9 +672,9 @@ export function 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.',
@@ -538,7 +686,7 @@ export function earn(options = {}) {
     }), Cache.response({
         cacheControl: Cache.policies.state,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
-        name: 'tempo-api:earn-vault-earnings:v2',
+        name: 'tempo-api:earn-vault-earnings:v3',
     }), async (c) => {
         if (Auth.narrowAccess)
             return Auth.paidAccessError(c);
@@ -598,18 +746,18 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Resolves any compatible Earn vault directly from current chain state and enriches it when curated.',
+        description: '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,
             },
         }),
@@ -660,7 +808,17 @@ export function earn(options = {}) {
 export async function getVaultEarnings(c, options) {
     const client = c.get('getClient')(options.chainId);
     const tidx = c.get('getTidx')(options.chainId);
-    const blockNumber = await getLatestIndexedBlockNumber(tidx);
+    const block = await getLatestIndexedBlock(tidx);
+    const blockNumber = block.number;
+    if (options.period === '30d')
+        return getWindowVaultEarnings(c, {
+            account: options.account,
+            blockNumber,
+            chainId: options.chainId,
+            period: options.period,
+            timestamp: block.timestamp,
+            vault: options.vault,
+        });
     const position = client.earn.getPosition({
         account: options.account,
         blockNumber: BigInt(blockNumber),
@@ -694,6 +852,7 @@ export async function getVaultEarnings(c, options) {
         getVaultEarningsHistory(tidx, {
             account: options.account,
             blockNumber,
+            startBlockNumber: beforeFirstBlockNumber,
             vault: options.vault,
         }),
         position,
@@ -702,6 +861,7 @@ export async function getVaultEarnings(c, options) {
         account: options.account,
         blockNumber,
         shareToken: current.shareToken,
+        startBlockNumber: beforeFirstBlockNumber,
         vault: options.vault,
     });
     const base = {
@@ -718,15 +878,105 @@ export async function getVaultEarnings(c, options) {
     const lifetimeEarnings = current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited;
     return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' };
 }
+/** Reads cash-flow-adjusted earnings over a trailing indexed window. */
+async function getWindowVaultEarnings(c, options) {
+    const client = c.get('getClient')(options.chainId);
+    const tidx = c.get('getTidx')(options.chainId);
+    const [current, startBlockNumber] = await Promise.all([
+        client.earn.getPosition({
+            account: options.account,
+            blockNumber: BigInt(options.blockNumber),
+            vault: options.vault,
+        }),
+        getWindowStartBlockNumber(tidx, { days: 30, timestamp: options.timestamp }),
+    ]);
+    const [externalShareTransfer, history, opening] = await Promise.all([
+        hasExternalShareTransfer(tidx, {
+            account: options.account,
+            blockNumber: options.blockNumber,
+            shareToken: current.shareToken,
+            startBlockNumber,
+            vault: options.vault,
+        }),
+        getVaultEarningsHistory(tidx, {
+            account: options.account,
+            blockNumber: options.blockNumber,
+            startBlockNumber,
+            vault: options.vault,
+        }),
+        getWindowShareState(tidx, {
+            account: options.account,
+            blockNumber: options.blockNumber,
+            shareToken: current.shareToken,
+            startBlockNumber,
+            vault: options.vault,
+        }),
+    ]);
+    const base = {
+        account: options.account,
+        assetToken: current.assetToken,
+        currentValue: current.value.toString(),
+        id: options.account,
+        period: options.period,
+    };
+    if (opening === undefined ||
+        externalShareTransfer ||
+        history.incompleteCostBasis ||
+        opening.crossBoundaryRedemption ||
+        opening.endShares !== current.shareBalance)
+        return { ...base, status: 'incomplete_cost_basis' };
+    if (history.pendingRedemption)
+        return { ...base, status: 'pending_redemption' };
+    const openingValue = opening.startShares === 0n
+        ? 0n
+        : await client.earn.getRedeemQuote({
+            blockNumber: BigInt(startBlockNumber),
+            shareAmount: opening.startShares,
+            vault: options.vault,
+        });
+    const windowEarnings = calculateWindowEarnings({
+        deposited: history.deposited,
+        endingValue: current.value,
+        finalized: history.finalized,
+        openingValue,
+        redeemed: history.redeemed,
+        withdrewExact: history.withdrewExact,
+    });
+    return { ...base, status: 'complete', windowEarnings: windowEarnings.toString() };
+}
+/** Calculates cash-flow-adjusted earnings between two position snapshots. */
+export function calculateWindowEarnings(options) {
+    return (options.endingValue +
+        options.redeemed +
+        options.withdrewExact +
+        options.finalized -
+        options.deposited -
+        options.openingValue);
+}
 /** Reads the latest block whose indexed logs back the earnings calculation. */
-async function getLatestIndexedBlockNumber(tidx) {
+async function getLatestIndexedBlock(tidx) {
     const result = await tidx.fetch({
         engine: 'clickhouse',
-        query: 'SELECT num FROM blocks ORDER BY num DESC LIMIT 1',
+        query: 'SELECT num, timestamp FROM blocks ORDER BY num DESC LIMIT 1',
     });
-    const blockNumber = Value.toNumber(result.rows[0]?.['num']);
-    if (blockNumber === undefined)
+    const number = Value.toNumber(result.rows[0]?.['num']);
+    const timestamp = Value.toIsoDateTime(result.rows[0]?.['timestamp']);
+    if (number === undefined || timestamp === undefined)
         throw new Error('TIDX returned no indexed block.');
+    return { number, timestamp };
+}
+/** Resolves the last indexed block at or before a trailing-day boundary. */
+async function getWindowStartBlockNumber(tidx, options) {
+    const cutoff = new Date(Date.parse(options.timestamp) - Ttl.days(options.days)).toISOString();
+    const result = await tidx.fetch({
+        query: `SELECT num FROM blocks WHERE timestamp <= '${cutoff}' ORDER BY num DESC LIMIT 1`,
+    });
+    const row = result.rows[0];
+    if (!row)
+        return beforeFirstBlockNumber;
+    const blockNumber = Value.toNumber(row['num']);
+    if (blockNumber === undefined)
+        throw new Error('TIDX returned no Earn earnings boundary.');
     return blockNumber;
 }
 /** Reads the indexed cash flows and exceptional states behind one earnings calculation. */
@@ -740,6 +990,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM Deposited
           WHERE address = '${options.vault}'
             AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS deposited_assets,
         (
@@ -750,6 +1001,7 @@ async function getVaultEarningsHistory(tidx, options) {
             AND requested."requestId" = finalized."requestId"
           WHERE finalized.address = '${options.vault}'
             AND requested.requester = '${options.account}'
+            AND finalized.block_num > ${options.startBlockNumber}
             AND finalized.block_num <= ${options.blockNumber}
             AND requested.block_num <= ${options.blockNumber}
         ) AS finalized_assets,
@@ -773,6 +1025,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM Redeemed
           WHERE address = '${options.vault}'
             AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS redeemed_assets,
         (
@@ -782,6 +1035,7 @@ async function getVaultEarningsHistory(tidx, options) {
             ON requested.address = cancelled.address
             AND requested."requestId" = cancelled."requestId"
           WHERE cancelled.address = '${options.vault}'
+            AND cancelled.block_num > ${options.startBlockNumber}
             AND cancelled.block_num <= ${options.blockNumber}
             AND requested.block_num <= ${options.blockNumber}
             AND requested.requester != cancelled.receiver
@@ -795,6 +1049,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM VenueSharesDeposited
           WHERE address = '${options.vault}'
             AND receiver = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS venue_deposits,
         (
@@ -802,6 +1057,7 @@ async function getVaultEarningsHistory(tidx, options) {
           FROM WithdrewExact
           WHERE address = '${options.vault}'
             AND caller = '${options.account}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
         ) AS withdrew_exact
     `,
@@ -840,6 +1096,93 @@ async function getVaultEarningsHistory(tidx, options) {
         withdrewExact: BigInt(withdrewExact),
     };
 }
+/** Reads share balances and cross-boundary redemptions for a trailing window. */
+async function getWindowShareState(tidx, options) {
+    const result = await tidx.fetch({
+        engine: 'clickhouse',
+        query: `
+      SELECT
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "to" = '${options.account}'
+            AND block_num <= ${options.startBlockNumber}
+        ) AS received_start,
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "from" = '${options.account}'
+            AND block_num <= ${options.startBlockNumber}
+        ) AS sent_start,
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "to" = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS received_end,
+        (
+          SELECT toString(sum(toUInt256(amount)))
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND "from" = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS sent_end,
+        (
+          SELECT count()
+          FROM (
+            SELECT finalized."requestId"
+            FROM RedeemFinalized AS finalized
+            INNER JOIN RedeemRequested AS requested
+              ON requested.address = finalized.address
+              AND requested."requestId" = finalized."requestId"
+            WHERE finalized.address = '${options.vault}'
+              AND requested.requester = '${options.account}'
+              AND requested.block_num <= ${options.startBlockNumber}
+              AND finalized.block_num > ${options.startBlockNumber}
+              AND finalized.block_num <= ${options.blockNumber}
+            UNION ALL
+            SELECT cancelled."requestId"
+            FROM RedeemCancelled AS cancelled
+            INNER JOIN RedeemRequested AS requested
+              ON requested.address = cancelled.address
+              AND requested."requestId" = cancelled."requestId"
+            WHERE cancelled.address = '${options.vault}'
+              AND requested.requester = '${options.account}'
+              AND requested.block_num <= ${options.startBlockNumber}
+              AND cancelled.block_num > ${options.startBlockNumber}
+              AND cancelled.block_num <= ${options.blockNumber}
+          ) AS cross_boundary
+        ) AS cross_boundary_redemptions
+    `,
+        signatures: [redeemCancelledSignature, redeemFinalizedSignature, redeemRequestedSignature],
+    });
+    const row = result.rows[0];
+    const crossBoundaryRedemptions = Value.toNumber(row?.['cross_boundary_redemptions']);
+    const receivedEnd = Value.toIntegerString(row?.['received_end']);
+    const receivedStart = Value.toIntegerString(row?.['received_start']);
+    const sentEnd = Value.toIntegerString(row?.['sent_end']);
+    const sentStart = Value.toIntegerString(row?.['sent_start']);
+    if (crossBoundaryRedemptions === undefined ||
+        receivedEnd === undefined ||
+        receivedStart === undefined ||
+        sentEnd === undefined ||
+        sentStart === undefined)
+        return undefined;
+    const receivedEndValue = BigInt(receivedEnd);
+    const receivedStartValue = BigInt(receivedStart);
+    const sentEndValue = BigInt(sentEnd);
+    const sentStartValue = BigInt(sentStart);
+    if (sentEndValue > receivedEndValue || sentStartValue > receivedStartValue)
+        return undefined;
+    return {
+        crossBoundaryRedemption: crossBoundaryRedemptions > 0,
+        endShares: receivedEndValue - sentEndValue,
+        startShares: receivedStartValue - sentStartValue,
+    };
+}
 /** Returns whether an account sent or received Earn shares outside known vault flows. */
 async function hasExternalShareTransfer(tidx, options) {
     // Vault exits pull shares into the vault before burning. Reconcile counts by transaction and amount so unmatched direct sends remain external.
@@ -851,10 +1194,15 @@ async function hasExternalShareTransfer(tidx, options) {
           SELECT count()
           FROM token_transfers
           WHERE token = '${options.shareToken.toLowerCase()}'
+            AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
             AND (
               ("from" = '${options.account}' AND "to" != '${options.vault}')
-              OR ("to" = '${options.account}' AND "from" != '${zeroAddress}')
+              OR (
+                "to" = '${options.account}'
+                AND "from" != '${zeroAddress}'
+                AND "from" != '${options.vault}'
+              )
             )
         ) + (
           SELECT count()
@@ -864,6 +1212,7 @@ async function hasExternalShareTransfer(tidx, options) {
             WHERE token = '${options.shareToken.toLowerCase()}'
               AND "from" = '${options.account}'
               AND "to" = '${options.vault}'
+              AND block_num > ${options.startBlockNumber}
               AND block_num <= ${options.blockNumber}
             GROUP BY tx_hash, amount
           ) AS candidate
@@ -874,27 +1223,58 @@ async function hasExternalShareTransfer(tidx, options) {
               FROM Redeemed
               WHERE address = '${options.vault}'
                 AND caller = '${options.account}'
+                AND block_num > ${options.startBlockNumber}
                 AND block_num <= ${options.blockNumber}
               UNION ALL
               SELECT tx_hash, toUInt256(earnShares) AS amount
               FROM RedeemRequested
               WHERE address = '${options.vault}'
                 AND requester = '${options.account}'
+                AND block_num > ${options.startBlockNumber}
                 AND block_num <= ${options.blockNumber}
               UNION ALL
               SELECT tx_hash, toUInt256(earnSharesBurned) AS amount
               FROM WithdrewExact
               WHERE address = '${options.vault}'
                 AND caller = '${options.account}'
+                AND block_num > ${options.startBlockNumber}
                 AND block_num <= ${options.blockNumber}
             ) AS protocol_exit
             GROUP BY tx_hash, amount
           ) AS matched
             ON matched.tx_hash = candidate.tx_hash AND matched.amount = candidate.amount
           WHERE candidate.transfer_count > coalesce(matched.exit_count, 0)
+        ) + (
+          SELECT count()
+          FROM (
+            SELECT tx_hash, toUInt256(amount) AS amount, count() AS transfer_count
+            FROM token_transfers
+            WHERE token = '${options.shareToken.toLowerCase()}'
+              AND "from" = '${options.vault}'
+              AND "to" = '${options.account}'
+              AND block_num > ${options.startBlockNumber}
+              AND block_num <= ${options.blockNumber}
+            GROUP BY tx_hash, amount
+          ) AS candidate
+          LEFT JOIN (
+            SELECT tx_hash, toUInt256(earnShares) AS amount, count() AS cancel_count
+            FROM RedeemCancelled
+            WHERE address = '${options.vault}'
+              AND receiver = '${options.account}'
+              AND block_num > ${options.startBlockNumber}
+              AND block_num <= ${options.blockNumber}
+            GROUP BY tx_hash, amount
+          ) AS matched
+            ON matched.tx_hash = candidate.tx_hash AND matched.amount = candidate.amount
+          WHERE candidate.transfer_count > coalesce(matched.cancel_count, 0)
         ) AS count
     `,
-        signatures: [redeemedSignature, redeemRequestedSignature, withdrewExactSignature],
+        signatures: [
+            redeemCancelledSignature,
+            redeemedSignature,
+            redeemRequestedSignature,
+            withdrewExactSignature,
+        ],
     });
     const count = Value.toNumber(result.rows[0]?.['count']);
     if (count === undefined)
@@ -1256,6 +1636,195 @@ export async function listVerifiedVaults(c, options) {
         nextCursor: matches.length > options.limit && last ? Cursor.encode([last.record.vaultAddress]) : null,
     };
 }
+/** Lists every vault where an account holds earn shares, ordered by vault address. */
+export async function listPositions(c, 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 = [];
+    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 = [];
+            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,
+    };
+}
+/** Finds vaults whose earn share token the account has ever held, by vault address. */
+async function queryHeldVaults(c, options) {
+    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
+      `,
+        signatures: [deployedSignature],
+    }));
+    const rows = result.rows;
+    return rows.flatMap((row) => {
+        const vault = Schema.Address.safeParse(Value.toText(row['earnVault']));
+        return vault.success ? [vault.data.toLowerCase()] : [];
+    });
+}
+/** Reads one account's live position in one vault. */
+function readPosition(c, options) {
+    return c
+        .get('getClient')(options.chainId)
+        .earn.getPosition({ account: options.address, vault: options.vaultAddress });
+}
+/** Serializes one live position into the address-scoped row contract. */
+function 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,
+    };
+}
+/** Renders a base-unit amount in the token's display currency and precision. */
+function valueFor(amount, 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, options) {
     const db = Db.get(c.get('dbCached'));