tapimo 0.9.0 → 0.10.1

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

@@ -31,6 +31,9 @@ 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. */
@@ -81,11 +84,13 @@ export var schema;
     const baseIncludeQuery = Schema.includeQuery(baseInclude, 'Comma-separated vault fields to include, such as `access,zone`.');
     const zone = z
         .strictObject({
-        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [421700001] })),
+        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [1424310001] })),
         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-internal'] })),
         outputTokens: z
             .array(Schema.Address)
             .check(z.describe('Tokens supported by private redemptions.'), z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] })),
@@ -125,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())
@@ -137,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 }),
@@ -152,23 +157,38 @@ 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
@@ -245,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,
@@ -260,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. */
@@ -278,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;
@@ -308,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;
@@ -328,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. */
@@ -348,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,
             },
         }),
@@ -388,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,
             },
         }),
@@ -420,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',
@@ -428,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: {
@@ -442,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,
             },
         }),
@@ -537,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.',
@@ -611,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,
             },
         }),
@@ -1501,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'));