tapimo 0.7.0 → 0.7.2

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

@@ -0,0 +1,947 @@
+import { Hono } from 'hono';
+import { Value as core_Value } from 'ox';
+import { ContractFunctionExecutionError, ContractFunctionRevertedError, ContractFunctionZeroDataError, } from 'viem';
+import * as z from 'zod/mini';
+import * as Db from '../../../db/Db.js';
+import * as core_EarnVaults from '../../../db/tables/earnVaults.js';
+import * as Auth from '../../../internal/Auth.js';
+import * as Cache from '../../../internal/Cache.js';
+import * as Cursor from '../../../internal/Cursor.js';
+import * as EarnRates from '../../../internal/EarnRates.js';
+import * as EarnVaults from '../../../internal/EarnVaults.js';
+import * as OpenApi from '../../../internal/OpenApi.js';
+import * as Response from '../../../internal/Response.js';
+import * as Schema from '../../../internal/Schema.js';
+import * as Store from '../../../internal/Store.js';
+import * as Timing from '../../../internal/Timing.js';
+import * as Ttl from '../../../internal/Ttl.js';
+import * as Value from '../../../internal/Value.js';
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js';
+import * as FxOracle from '../FxOracle.js';
+import * as Tokens from './tokens.js';
+import * as Valuation from './valuation.js';
+const deployedSignature = 'event EarnStackDeployed(address indexed earnVault,address indexed earnShare,address indexed earnFees,address engine,address asset,address owner,bytes32 deploymentId,address emergencyGuardian,address asyncJanitor,uint8 migrationMode,bytes32 earnShareSalt,bytes32 controlConfigHash,bytes32 feeConfigHash,bytes32 earnFeesSalt)';
+const maxScannedDeployments = 250;
+const scanLimit = 50;
+/** 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. */
+const tvlDecimals = 6;
+/** Returns the smallest useful live-discovery batch. */
+export function discoveryBatchLimit(options) {
+    const needed = options.limit + 1 - options.matches;
+    return Math.min(options.filtered ? needed * 2 : needed, options.remaining, scanLimit);
+}
+/** Zod schemas owned by the public Earn-vault resource. */
+export var schema;
+(function (schema) {
+    const capability = z
+        .enum([
+        'asyncRedeem',
+        'boundedRedeem',
+        'deposit',
+        'exactWithdraw',
+        'inKindDeposit',
+        'privateRouting',
+        'redeem',
+        'routerSwaps',
+    ])
+        .check(z.describe('Vault capability required by the request.'));
+    const engineType = z
+        .enum(['erc4626', 'veda'])
+        .check(z.describe('Inferred vault engine type.'), z.meta({ examples: ['erc4626'] }));
+    const engine = Schema.describe(z.strictObject({
+        address: Schema.Address.check(z.describe('Current vault engine contract address.'), z.meta({ examples: ['0xd85fc943333a6cd7c0e3391acd54fc4e572f0baf'] })),
+        type: z
+            .nullable(engineType)
+            .check(z.describe('Inferred engine type, or null when it is unknown.')),
+        venue: z
+            .nullable(Schema.Address.check(z.describe('Yield venue contract bound to the engine.'), z.meta({ examples: ['0xa8b4f0e69cd4b0e56b676343f02acd8c3b355322'] })))
+            .check(z.describe('Yield venue, or null when the engine does not expose one.')),
+    }), 'Current vault engine.');
+    const include = z
+        .enum(['access', 'apy', 'capabilities', 'token.logoUri', 'tvl', 'zone'])
+        .check(z.describe('Optional vault fields to embed via `include`.'));
+    const includeQuery = Schema.includeQuery(include, 'Comma-separated vault fields to include, such as `apy,tvl`.');
+    // `apy` and `tvl` need indexer and FX access, so surfaces lacking either
+    // select from this reduced set instead.
+    const baseInclude = z
+        .enum(['access', 'capabilities', 'token.logoUri', 'zone'])
+        .check(z.describe('Optional vault fields to embed via `include`.'));
+    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] })),
+        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'] })),
+        outputTokens: z
+            .array(Schema.Address)
+            .check(z.describe('Tokens supported by private redemptions.'), z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] })),
+    })
+        .check(z.describe('Private Zone route configured for a verified vault.'));
+    const value = z.strictObject({
+        amount: Schema.DecimalString.check(z.describe('Value in base units at `decimals` precision.'), z.meta({ examples: ['125288750000'] })),
+        currency: z
+            .string()
+            .check(z.describe('Display currency of this value.'), z.meta({ examples: ['USD'] })),
+        decimals: z
+            .number()
+            .check(z.int(), z.nonnegative(), z.describe('Decimal places used to convert `amount` into `formatted`.'), z.meta({ examples: [6] })),
+        formatted: z
+            .string()
+            .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Value rendered in whole units.'), z.meta({ examples: ['125288.75'] })),
+    });
+    const vault = z.strictObject({
+        access: z
+            .optional(EarnVaults.schema.Discovery.shape.access)
+            .check(z.describe('Vault share-token access, when requested.')),
+        apy: z
+            .optional(z.nullable(EarnRates.schema.Apy))
+            .check(z.describe('Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.')),
+        assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
+        capabilities: z
+            .optional(EarnVaults.schema.Discovery.shape.capabilities)
+            .check(z.describe('Vault capabilities, when requested.')),
+        description: z
+            .nullable(z.string())
+            .check(z.describe('Curated vault description, or null when the vault is not verified.'), z.meta({ examples: ['Bridge test PATHUSD deposited into Tempo Earn.'] })),
+        engine,
+        id: Schema.Address.check(z.describe('Stable vault id, equal to the lowercase vault address.'), z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] })),
+        instantLiquidity: EarnVaults.schema.Discovery.shape.instantLiquidity.check(z.describe('Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.')),
+        label: z
+            .string()
+            .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.')),
+        shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+        slug: z
+            .nullable(z.string())
+            .check(z.describe('Curated URL slug, or null when the vault is not verified.'), z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] })),
+        state: EarnVaults.schema.Discovery.shape.state,
+        tvl: z
+            .optional(z.nullable(value))
+            .check(z.describe('Total assets valued in USD, when requested via `include=tvl`, or null when the asset has no priced display currency.')),
+        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] })),
+        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.');
+    /** One registry-curated Earn vault. */
+    schema.VerifiedVault = Schema.describe(z.extend(vault, {
+        engine: z.extend(engine, { type: engineType }),
+        slug: z
+            .string()
+            .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.');
+    const position = z.strictObject({
+        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'] })),
+    });
+    const meta = z
+        .object({
+        valuation: z
+            .optional(Valuation.schema.Pricing)
+            .check(z.describe('Rate provenance for valued fields. Present when `include=tvl` consulted conversion rates; absent when TVL was not requested, every value was identity-valued, or rates were unavailable.')),
+    })
+        .check(z.describe('Rate provenance for valued fields.'));
+    const collectionFilters = z.strictObject({
+        asset: z
+            .optional(Schema.Address)
+            .check(z.describe('Only include vaults accepting this asset address.')),
+        capability: Schema.includeQuery(capability, 'Comma-separated capabilities that every returned vault must support.'),
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        'engine.type': z
+            .optional(engineType)
+            .check(z.describe('Only include vaults with this inferred engine type.')),
+        include: includeQuery,
+        limit: Schema.Limit,
+    });
+    const collectionQuery = z
+        .extend(collectionFilters, { 'apy.window': EarnRates.schema.Window })
+        .check(z.describe('Query parameters for listing Earn vaults.'));
+    const vaultSelector = z.strictObject({
+        chainId: Schema.ChainIdQuery,
+        include: includeQuery,
+    });
+    /** Schemas for the getEarnVaults operation. */
+    let getEarnVaults;
+    (function (getEarnVaults) {
+        /** Query parameters for all compatible deployed Earn vaults. */
+        getEarnVaults.Query = collectionQuery;
+        /** Paginated list of compatible deployed Earn vaults. */
+        getEarnVaults.Response = z
+            .strictObject({
+            data: z
+                .array(schema.Vault)
+                .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.'));
+    })(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.');
+        /** Query parameters for registry-curated Earn vaults. */
+        getVerifiedEarnVaults.Query = collectionQuery;
+        /** Paginated list of registry-curated Earn vaults. */
+        getVerifiedEarnVaults.Response = z
+            .strictObject({
+            data: z
+                .array(schema.VerifiedVault)
+                .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.'));
+    })(getVerifiedEarnVaults = schema.getVerifiedEarnVaults || (schema.getVerifiedEarnVaults = {}));
+    /** Schemas for the getEarnVault operation. */
+    let getEarnVault;
+    (function (getEarnVault) {
+        /** 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.'));
+        /** 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.');
+        /** 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.'));
+        /** 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 = schema.getEarnVault || (schema.getEarnVault = {}));
+    /** Schemas for the getEarnVaultPosition operation. */
+    let getEarnVaultPosition;
+    (function (getEarnVaultPosition) {
+        /** Path parameters identifying the Earn vault and account. */
+        getEarnVaultPosition.Params = z
+            .strictObject({
+            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.'));
+        /** 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.'));
+        /** 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 = schema.getEarnVaultPosition || (schema.getEarnVaultPosition = {}));
+})(schema || (schema = {}));
+/** Creates the public Earn-vault handlers. */
+export function earn(options = {}) {
+    const oracle = options.fx?.oracle ?? FxOracle.ecb();
+    return new Hono()
+        .get('/v1/earn/vaults', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getEarnVaults.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        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.' },
+            success: {
+                description: 'A page of compatible deployed Earn vaults.',
+                schema: schema.getEarnVaults.Response,
+            },
+        }),
+        summary: 'List Earn vaults',
+        tags: ['Earn'],
+    }), 
+    // Live state and rate enrichment are embedded, so every vault read caches
+    // as current-state rather than slow-changing metadata.
+    Cache.response({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaults.Query),
+        name: 'tempo-api:earn-vaults:v2',
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const query = c.req.valid('query');
+        try {
+            const chainId = query.chainId ?? c.get('chainId');
+            const data = await listVaults(c, { ...query, chainId, oracle });
+            return c.json(Response.validated(schema.getEarnVaults.Response, data), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/v1/earn/vaults/verified', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getVerifiedEarnVaults.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        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.' },
+            success: {
+                description: 'A page of registry-curated Earn vaults.',
+                schema: schema.getVerifiedEarnVaults.Response,
+            },
+        }),
+        summary: 'List verified vaults',
+        tags: ['Earn'],
+    }), Cache.response({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getVerifiedEarnVaults.Query),
+        name: 'tempo-api:earn-vaults:v2',
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const query = c.req.valid('query');
+        try {
+            const chainId = query.chainId ?? c.get('chainId');
+            const data = await listVerifiedVaults(c, { ...query, chainId, oracle });
+            return c.json(Response.validated(schema.getVerifiedEarnVaults.Response, data), 200);
+        }
+        catch (cause) {
+            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',
+        message: 'Invalid vault position',
+    }), OpenApi.validate('query', schema.getEarnVaultPosition.Query, {
+        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.',
+        operationId: 'getEarnVaultPosition',
+        responses: OpenApi.responses({
+            errors: {
+                400: {
+                    codes: [
+                        'chain_id_invalid',
+                        'chain_id_unsupported',
+                        'position_invalid',
+                        'query_invalid',
+                    ],
+                },
+                404: {
+                    codes: ['earn_vault_not_found'],
+                    description: 'No compatible Earn vault was found at the supplied vault address.',
+                },
+                502: 'Could not read the Earn vault position.',
+            },
+            success: {
+                description: 'Current Earn position for one account in one vault.',
+                schema: schema.getEarnVaultPosition.Response,
+            },
+        }),
+        summary: 'Get vault position',
+        tags: ['Earn'],
+    }), Cache.response({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaultPosition.Query),
+        name: 'tempo-api:earn-vault-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: 'position_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const { address, vaultId } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const chainId = query.chainId ?? c.get('chainId');
+        try {
+            const position = await c
+                .get('getClient')(chainId)
+                .earn.getPosition({ account: address, vault: vaultId });
+            return c.json(Response.validated(schema.getEarnVaultPosition.Response, {
+                account: address,
+                assetAllowance: position.assetAllowance.toString(),
+                assetBalance: position.assetBalance.toString(),
+                assetToken: position.assetToken,
+                id: address,
+                shareAllowance: position.shareAllowance.toString(),
+                shareBalance: position.shareBalance.toString(),
+                shareToken: position.shareToken,
+                value: position.value.toString(),
+            }), 200);
+        }
+        catch (cause) {
+            try {
+                await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId });
+            }
+            catch (vaultCause) {
+                if (isIncompatible(vaultCause))
+                    return Response.error(c, {
+                        code: 'earn_vault_not_found',
+                        message: 'Earn vault not found',
+                        status: 404,
+                    });
+            }
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/v1/earn/vaults/:vaultId', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getEarnVault.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+    }), OpenApi.validate('query', schema.getEarnVault.Query, {
+        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.',
+        operationId: 'getEarnVault',
+        responses: OpenApi.responses({
+            errors: {
+                404: {
+                    codes: ['earn_vault_not_found'],
+                    description: 'No compatible Earn vault was found at this address.',
+                },
+                502: 'Could not read Earn vault data.',
+            },
+            success: {
+                description: 'One compatible Earn vault.',
+                schema: schema.getEarnVault.Response,
+            },
+        }),
+        summary: 'Get Earn vault',
+        tags: ['Earn'],
+    }), Cache.response({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVault.Query),
+        name: 'tempo-api:earn-vaults:v2',
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'vault_id_invalid',
+                message: 'Invalid request parameters',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid request parameters',
+            });
+        const { vaultId } = c.req.valid('param');
+        const query = c.req.valid('query');
+        try {
+            const chainId = query.chainId ?? c.get('chainId');
+            const data = await getVault(c, {
+                'apy.window': query['apy.window'],
+                chainId,
+                include: query.include,
+                oracle,
+                vaultAddress: vaultId,
+            });
+            return c.json(Response.validated(schema.getEarnVault.Response, data), 200);
+        }
+        catch (cause) {
+            if (cause instanceof NotFoundError)
+                return Response.error(c, {
+                    code: 'earn_vault_not_found',
+                    message: 'Earn vault not found',
+                    status: 404,
+                });
+            return Response.upstream(c, cause);
+        }
+    });
+}
+/** Lists compatible deployed Earn vaults. */
+export async function listVaults(c, options) {
+    const db = Db.get(c.get('dbCached'));
+    const [records, snapshot] = await Promise.all([
+        core_EarnVaults.list(db, { chainId: options.chainId }),
+        VerifiedTokens.snapshot(c, options.chainId),
+    ]);
+    const registry = new Map(records.map((record) => [record.vaultAddress.toLowerCase(), record]));
+    const decoded = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined;
+    let position = decoded
+        ? [Number(decoded[0]), Number(decoded[1])]
+        : undefined;
+    let hasMore = false;
+    let scanned = 0;
+    const matches = [];
+    while (matches.length <= options.limit && scanned < maxScannedDeployments) {
+        const page = await queryDeployments(c, {
+            asset: options.asset,
+            chainId: options.chainId,
+            cursor: position,
+            limit: discoveryBatchLimit({
+                filtered: options.capability.length > 0 || options['engine.type'] !== undefined,
+                limit: options.limit,
+                matches: matches.length,
+                remaining: maxScannedDeployments - scanned,
+            }),
+        });
+        hasMore = page.hasMore;
+        if (page.items.length === 0) {
+            hasMore = false;
+            break;
+        }
+        scanned += page.items.length;
+        const discovered = await Promise.all(page.items.map(async (item) => {
+            const record = registry.get(item.vaultAddress.toLowerCase());
+            try {
+                const discovery = await resolveVaultDiscovery(c, {
+                    chainId: options.chainId,
+                    include: discoveryInclude(options),
+                    vaultAddress: item.vaultAddress,
+                });
+                return { discovery, position: item.position, record };
+            }
+            catch (cause) {
+                if (!record && isIncompatible(cause))
+                    return undefined;
+                throw cause;
+            }
+        }));
+        for (const match of discovered) {
+            if (!match || !matchesVaultFilters(match.discovery, options))
+                continue;
+            matches.push(match);
+        }
+        position = page.items.at(-1).position;
+        if (!hasMore)
+            break;
+    }
+    const page = matches.slice(0, options.limit);
+    const discoveries = page.map(({ discovery }) => discovery);
+    const include = vaultInclude(options);
+    const [apy, rates, tokens] = await Promise.all([
+        resolvePageApy(c, {
+            chainId: options.chainId,
+            discoveries,
+            include,
+            window: options['apy.window'],
+        }),
+        resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+        resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
+    ]);
+    const data = page.map((match) => resolveVault(c, { ...match, apy, include, rates, snapshot, tokens }));
+    const last = matches[options.limit - 1];
+    const nextPosition = matches.length > options.limit ? last?.position : hasMore ? position : undefined;
+    return {
+        data,
+        ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
+        nextCursor: nextPosition ? Cursor.encode(nextPosition) : null,
+    };
+}
+/** Lists registry-curated Earn vaults. */
+export async function listVerifiedVaults(c, options) {
+    const db = Db.get(c.get('dbCached'));
+    const [records, snapshot] = await Promise.all([
+        core_EarnVaults.list(db, { chainId: options.chainId }),
+        VerifiedTokens.snapshot(c, options.chainId),
+    ]);
+    const decoded = options.cursor ? Cursor.decode(options.cursor, ['address']) : undefined;
+    const cursor = decoded?.[0]?.toString().toLowerCase();
+    const candidates = records.filter((record) => !cursor || record.vaultAddress.toLowerCase() > cursor);
+    const matches = [];
+    let offset = 0;
+    while (offset < candidates.length && matches.length <= options.limit) {
+        const batchSize = discoveryBatchLimit({
+            filtered: options.capability.length > 0 || options['engine.type'] !== undefined,
+            limit: options.limit,
+            matches: matches.length,
+            remaining: candidates.length - offset,
+        });
+        const batch = candidates.slice(offset, offset + batchSize);
+        offset += batch.length;
+        const discovered = await Promise.all(batch.map(async (record) => ({
+            discovery: await resolveVaultDiscovery(c, {
+                chainId: options.chainId,
+                include: discoveryInclude(options),
+                vaultAddress: Schema.Address.parse(record.vaultAddress.toLowerCase()),
+            }),
+            record,
+        })));
+        for (const match of discovered) {
+            if (!matchesVaultFilters(match.discovery, options))
+                continue;
+            matches.push(match);
+        }
+    }
+    const page = matches.slice(0, options.limit);
+    const discoveries = page.map(({ discovery }) => discovery);
+    const include = vaultInclude(options);
+    const [apy, rates, tokens] = await Promise.all([
+        resolvePageApy(c, {
+            chainId: options.chainId,
+            discoveries,
+            include,
+            window: options['apy.window'],
+        }),
+        resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+        resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
+    ]);
+    const data = page.map((match) => Response.validated(schema.VerifiedVault, resolveVault(c, { ...match, apy, include, rates, snapshot, tokens })));
+    const last = matches[options.limit - 1];
+    return {
+        data,
+        ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
+        nextCursor: matches.length > options.limit && last ? Cursor.encode([last.record.vaultAddress]) : null,
+    };
+}
+/** Gets one compatible Earn vault. */
+export async function getVault(c, options) {
+    const db = Db.get(c.get('dbCached'));
+    const [record, snapshot] = await Promise.all([
+        core_EarnVaults.get(db, {
+            chainId: options.chainId,
+            vaultAddress: options.vaultAddress,
+        }),
+        VerifiedTokens.snapshot(c, options.chainId),
+    ]);
+    try {
+        const discovery = await resolveVaultDiscovery(c, {
+            chainId: options.chainId,
+            include: discoveryInclude({ capability: [], include: options.include }),
+            vaultAddress: options.vaultAddress,
+        });
+        const discoveries = [discovery];
+        const include = vaultInclude(options);
+        const [apy, rates, tokens] = await Promise.all([
+            resolvePageApy(c, {
+                chainId: options.chainId,
+                discoveries,
+                include,
+                window: options['apy.window'],
+            }),
+            resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+            resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
+        ]);
+        return {
+            ...resolveVault(c, {
+                apy,
+                discovery,
+                include,
+                rates,
+                record,
+                snapshot,
+                tokens,
+            }),
+            ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
+        };
+    }
+    catch (cause) {
+        if (cause instanceof EarnVaults.NotFoundError || (!record && isIncompatible(cause)))
+            throw new NotFoundError();
+        throw cause;
+    }
+}
+// Selecting a rate window is a request for the rate it measures, mirroring how
+// a capability filter promotes `capabilities`.
+function vaultInclude(options) {
+    const { include } = options;
+    if (options['apy.window'] === undefined || include.includes('apy'))
+        return include;
+    return [...include, 'apy'];
+}
+function discoveryInclude(options) {
+    const includeCapabilities = options.include.includes('capabilities') ||
+        options.include.includes('zone') ||
+        options.capability.length > 0;
+    return [
+        ...(options.include.includes('access') ? ['access'] : []),
+        ...(includeCapabilities ? ['capabilities'] : []),
+    ];
+}
+async function resolveVaultDiscovery(c, options) {
+    return Store.memoize(() => Timing.time(c, 'earn_vault_discovery', () => EarnVaults.resolve({
+        getClient: c.get('getClient'),
+        include: options.include,
+        input: {
+            chainId: options.chainId,
+            vaultAddress: options.vaultAddress,
+        },
+        zones: [...c.get('zones').values()],
+    })), {
+        key: `earn-vault:v3:${options.chainId}:${options.vaultAddress.toLowerCase()}:include:${options.include.join(',') || 'base'}`,
+        store: c.get('store'),
+        // Matches the routes' `state` policy `max-age` so the two cache layers do
+        // not compound staleness on live vault state.
+        ttl: Ttl.seconds(30),
+    });
+}
+// Measuring a rate costs indexer boundary queries plus historical quotes against
+// an archive node, so an unrequested rate reaches neither.
+function resolvePageApy(c, options) {
+    if (!options.include.includes('apy'))
+        return undefined;
+    return Timing.time(c, 'earn_apy', () => EarnRates.resolve({
+        chainId: options.chainId,
+        getClient: c.get('getClient'),
+        getTidx: c.get('getTidx'),
+        store: c.get('store'),
+        vaults: options.discoveries.map(({ vaultAddress }) => vaultAddress),
+        window: options.window,
+    }));
+}
+// The TVL denomination is a fixed constant, not caller input, so a rate set
+// lacking it leaves `tvl` unpriced instead of failing the whole vault read.
+function resolvePageRates(c, options) {
+    // Valuing total assets is the only reason this read consults the oracle.
+    if (!options.include.includes('tvl'))
+        return undefined;
+    return Valuation.ratesFor(c, {
+        currencies: options.discoveries.flatMap((discovery) => {
+            const currency = options.snapshot.byAddress.get(discovery.assetToken.address)?.currency;
+            return currency === undefined ? [] : [currency];
+        }),
+        denomination: tvlDenomination,
+        oracle: options.oracle,
+    }).catch((cause) => {
+        if (cause instanceof Valuation.UnsupportedDenominationError)
+            return undefined;
+        throw cause;
+    });
+}
+async function resolvePageTokens(c, options) {
+    const metadata = new Map(options.discoveries.flatMap(({ assetToken, shareToken }) => [
+        [Schema.Address.parse(assetToken.address.toLowerCase()), assetToken],
+        [Schema.Address.parse(shareToken.address.toLowerCase()), shareToken],
+    ]));
+    return Tokens.resolveTokens(c, {
+        addresses: [...metadata.keys()],
+        chainId: options.chainId,
+        include: [
+            'token.verified',
+            ...(options.include.includes('token.logoUri') ? ['token.logoUri'] : []),
+        ],
+        metadata,
+        snapshot: options.snapshot,
+    });
+}
+function resolveVault(c, options) {
+    const { discovery, record } = options;
+    const valued = options.include.includes('tvl')
+        ? Valuation.valuationFor({
+            amount: BigInt(discovery.state.totalAssets),
+            denomination: tvlDenomination,
+            rates: options.rates,
+            token: options.snapshot.byAddress.get(discovery.assetToken.address),
+        })
+        : undefined;
+    return serializeVault({
+        apy: options.apy?.get(discovery.vaultAddress) ?? null,
+        assetToken: getToken(options.tokens, discovery.assetToken.address),
+        discovery,
+        include: options.include,
+        record,
+        shareToken: getToken(options.tokens, discovery.shareToken.address),
+        tvl: valued
+            ? {
+                amount: core_Value.from(valued.amount, tvlDecimals).toString(),
+                currency: valued.currency,
+                decimals: tvlDecimals,
+                formatted: valued.amount,
+            }
+            : null,
+        zones: [...c.get('zones').values()],
+    });
+}
+/** Serializes resolved onchain and curated fields into the shared vault contract. */
+export function serializeVault(options) {
+    const { discovery, record } = options;
+    if (options.include.includes('access') && !discovery.access)
+        throw new Error('Earn vault access was not resolved.');
+    if (options.include.includes('capabilities') && !discovery.capabilities)
+        throw new Error('Earn vault capabilities were not resolved.');
+    const vaultAddress = Schema.Address.parse(discovery.vaultAddress.toLowerCase());
+    return Response.validated(schema.Vault, {
+        ...(options.include.includes('access') ? { access: discovery.access } : {}),
+        ...(options.include.includes('apy') ? { apy: options.apy } : {}),
+        assetToken: options.assetToken,
+        ...(options.include.includes('capabilities') ? { capabilities: discovery.capabilities } : {}),
+        description: record?.description ?? null,
+        engine: {
+            address: discovery.engine.address.toLowerCase(),
+            type: discovery.engine.type,
+            venue: discovery.engine.venue?.toLowerCase() ?? null,
+        },
+        id: vaultAddress,
+        instantLiquidity: discovery.instantLiquidity,
+        label: record?.label ?? options.shareToken.name,
+        sharePrice: discovery.sharePrice === null
+            ? null
+            : {
+                amount: discovery.sharePrice,
+                currency: options.assetToken.currency,
+                decimals: options.assetToken.decimals,
+                formatted: core_Value.format(BigInt(discovery.sharePrice), options.assetToken.decimals),
+            },
+        shareToken: options.shareToken,
+        slug: record?.slug ?? null,
+        state: discovery.state,
+        ...(options.include.includes('tvl') ? { tvl: options.tvl } : {}),
+        vaultAddress,
+        verified: record !== undefined,
+        ...(options.include.includes('zone')
+            ? { zone: record ? resolveZone({ discovery, record, zones: options.zones }) : null }
+            : {}),
+    });
+}
+function resolveZone(options) {
+    if (!options.discovery.capabilities?.privateRouting)
+        return null;
+    const hasInputs = options.record.privateInputTokens.length > 0;
+    const hasOutputs = options.record.privateOutputTokens.length > 0;
+    if (!hasInputs && !hasOutputs)
+        return null;
+    if (hasInputs !== hasOutputs)
+        throw new Error('Private input and output tokens must both be configured.');
+    const configured = options.zones.filter((zone) => zone.sourceId === options.record.chainId);
+    if (configured.length !== 1)
+        throw new Error(`Expected one Earn Zone for chain ${options.record.chainId}.`);
+    const zone = configured[0];
+    return {
+        chainId: zone.id,
+        inputTokens: options.record.privateInputTokens.map((token) => Schema.Address.parse(token.toLowerCase())),
+        name: zone.name,
+        outputTokens: options.record.privateOutputTokens.map((token) => Schema.Address.parse(token.toLowerCase())),
+    };
+}
+function getToken(tokens, address) {
+    const token = tokens.get(Schema.Address.parse(address.toLowerCase()));
+    if (!token)
+        throw new Error(`Token metadata was not resolved for ${address}.`);
+    return Response.validated(Tokens.schema.Token, token);
+}
+async function queryDeployments(c, options) {
+    const filters = ['deployment_rank = 1'];
+    if (options.asset)
+        filters.push(`lower(asset) = '${options.asset.toLowerCase()}'`);
+    if (options.cursor)
+        filters.push(Cursor.keyset([
+            {
+                literal: Cursor.literal(options.cursor[0], 'int'),
+                name: 'block_num',
+                order: 'desc',
+            },
+            {
+                literal: Cursor.literal(options.cursor[1], 'int'),
+                name: 'log_idx',
+                order: 'desc',
+            },
+        ]));
+    // ClickHouse supports ordering and windowing over decoded event CTEs.
+    const result = await c
+        .get('getTidx')(options.chainId)
+        .fetch({
+        chainId: options.chainId,
+        engine: 'clickhouse',
+        query: `
+      SELECT "earnVault", asset, block_num, log_idx
+      FROM (
+        SELECT
+          "earnVault",
+          asset,
+          block_num,
+          log_idx,
+          row_number() OVER (
+            PARTITION BY lower("earnVault")
+            ORDER BY block_num DESC, log_idx DESC
+          ) AS deployment_rank
+        FROM EarnStackDeployed
+      )
+      WHERE ${filters.join(' AND ')}
+      ORDER BY block_num DESC, log_idx DESC
+      LIMIT ${options.limit + 1}
+    `,
+        signatures: [deployedSignature],
+    });
+    const rows = result.rows;
+    const items = rows.slice(0, options.limit).map((row) => {
+        const vaultAddress = Schema.Address.safeParse(Value.toText(row['earnVault']));
+        const asset = Schema.Address.safeParse(Value.toText(row['asset']));
+        const blockNumber = Value.toNumber(row['block_num']);
+        const logIndex = Value.toNumber(row['log_idx']);
+        if (!vaultAddress.success ||
+            !asset.success ||
+            blockNumber === undefined ||
+            logIndex === undefined)
+            throw new Error('TIDX returned an invalid Earn deployment row.');
+        return {
+            asset: asset.data,
+            position: [blockNumber, logIndex],
+            vaultAddress: vaultAddress.data,
+        };
+    });
+    return { hasMore: rows.length > options.limit, items };
+}
+/** Tests live vault state against the shared collection filters. */
+export function matchesVaultFilters(discovery, options) {
+    if (options.asset && discovery.assetToken.address.toLowerCase() !== options.asset.toLowerCase())
+        return false;
+    const capabilities = discovery.capabilities;
+    if (options.capability.length > 0 && !capabilities)
+        throw new Error('Earn vault capabilities were not resolved.');
+    if (capabilities && !options.capability.every((name) => capabilities[name]))
+        return false;
+    if (options['engine.type'] && discovery.engine.type !== options['engine.type'])
+        return false;
+    return true;
+}
+/** Returns whether a failed read proves the address is not a compatible Earn vault. */
+export function isIncompatible(cause) {
+    if (cause instanceof EarnVaults.NotFoundError)
+        return true;
+    if (cause instanceof EarnVaults.VerificationError)
+        return cause.result.status === 'mismatch';
+    if (!(cause instanceof ContractFunctionExecutionError))
+        return false;
+    return Boolean(cause.walk((error) => error instanceof ContractFunctionRevertedError ||
+        error instanceof ContractFunctionZeroDataError));
+}
+/** Thrown when no compatible Earn vault exists at the requested address. */
+export class NotFoundError extends Error {
+    name = 'Earn.NotFoundError';
+}
+//# sourceMappingURL=earn.js.map