@earnforge/sdk 0.1.0

package/dist/cjs/index.cjs

@@ -0,0 +1,1350 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/schemas/vault.ts
+/** Protocol info — always has name + url */
+const ProtocolSchema = zod.z.object({
+	name: zod.z.string(),
+	url: zod.z.string()
+});
+/** Underlying token — symbol, address, decimals */
+const UnderlyingTokenSchema = zod.z.object({
+	symbol: zod.z.string(),
+	address: zod.z.string(),
+	decimals: zod.z.number()
+});
+/** Pack (deposit or redeem method) */
+const PackSchema = zod.z.object({
+	name: zod.z.string(),
+	stepsType: zod.z.string()
+});
+/**
+* APY — base and total always present.
+* reward: Morpho returns 0, Euler/Aave return null. Normalize to 0.
+* (Pitfall #17)
+*/
+const ApySchema = zod.z.object({
+	base: zod.z.number(),
+	total: zod.z.number(),
+	reward: zod.z.number().nullable().transform((v) => v ?? 0)
+});
+/**
+* TVL — usd is always a string from the API.
+* We parse it into { raw, parsed, bigint } at the boundary.
+* (Pitfall #8)
+*/
+const TvlSchema = zod.z.object({ usd: zod.z.string() });
+function parseTvl(tvl) {
+	const integerPart = tvl.usd.split(".")[0] ?? "0";
+	return {
+		raw: tvl.usd,
+		parsed: Number(tvl.usd),
+		bigint: BigInt(integerPart)
+	};
+}
+/**
+* Analytics — apy1d, apy7d, apy30d can all be null.
+* Fallback chain: apy.total → apy30d → apy7d → apy1d
+* (Pitfalls #7, #18)
+*/
+const AnalyticsSchema = zod.z.object({
+	apy: ApySchema,
+	tvl: TvlSchema,
+	apy1d: zod.z.number().nullable(),
+	apy7d: zod.z.number().nullable(),
+	apy30d: zod.z.number().nullable(),
+	updatedAt: zod.z.string()
+});
+/**
+* Get best available APY with fallback chain.
+* Order: apy.total → apy30d → apy7d → apy1d
+*/
+function getBestApy(analytics) {
+	if (analytics.apy.total !== 0) return analytics.apy.total;
+	return analytics.apy30d ?? analytics.apy7d ?? analytics.apy1d ?? 0;
+}
+/**
+* Vault schema — generated from real fixture (earn.li.fi, Apr 11 2026).
+*
+* Key edge cases handled:
+* - description is optional (~14% of vaults have it) (Pitfall #16)
+* - underlyingTokens can be empty array (Pitfall #15)
+* - apy.reward null → 0 (Pitfall #17)
+* - apy1d/apy7d/apy30d nullable (Pitfall #18)
+* - tvl.usd is a string (Pitfall #8)
+*/
+const VaultSchema = zod.z.object({
+	address: zod.z.string(),
+	chainId: zod.z.number(),
+	name: zod.z.string(),
+	slug: zod.z.string(),
+	network: zod.z.string(),
+	description: zod.z.string().optional(),
+	protocol: ProtocolSchema,
+	provider: zod.z.string(),
+	syncedAt: zod.z.string(),
+	tags: zod.z.array(zod.z.string()),
+	underlyingTokens: zod.z.array(UnderlyingTokenSchema),
+	lpTokens: zod.z.array(zod.z.unknown()),
+	analytics: AnalyticsSchema,
+	isTransactional: zod.z.boolean(),
+	isRedeemable: zod.z.boolean(),
+	depositPacks: zod.z.array(PackSchema),
+	redeemPacks: zod.z.array(PackSchema)
+});
+/** Paginated vault list response */
+const VaultListResponseSchema = zod.z.object({
+	data: zod.z.array(VaultSchema),
+	nextCursor: zod.z.string().nullable().optional(),
+	total: zod.z.number()
+});
+//#endregion
+//#region src/schemas/chain.ts
+/** Chain schema — from GET /v1/earn/chains */
+const ChainSchema = zod.z.object({
+	chainId: zod.z.number(),
+	name: zod.z.string(),
+	networkCaip: zod.z.string()
+});
+const ChainListResponseSchema = zod.z.array(ChainSchema);
+//#endregion
+//#region src/schemas/protocol.ts
+/** Protocol schema — from GET /v1/earn/protocols */
+const ProtocolDetailSchema = zod.z.object({
+	name: zod.z.string(),
+	url: zod.z.string()
+});
+const ProtocolListResponseSchema = zod.z.array(ProtocolDetailSchema);
+//#endregion
+//#region src/schemas/portfolio.ts
+/** Position asset */
+const PositionAssetSchema = zod.z.object({
+	address: zod.z.string(),
+	name: zod.z.string(),
+	symbol: zod.z.string(),
+	decimals: zod.z.number()
+});
+/** Single portfolio position */
+const PositionSchema = zod.z.object({
+	chainId: zod.z.number(),
+	protocolName: zod.z.string(),
+	asset: PositionAssetSchema,
+	balanceUsd: zod.z.string(),
+	balanceNative: zod.z.string()
+});
+/** Portfolio response */
+const PortfolioResponseSchema = zod.z.object({ positions: zod.z.array(PositionSchema) });
+//#endregion
+//#region src/schemas/quote.ts
+/** Token info in Composer responses */
+const ComposerTokenSchema = zod.z.object({
+	address: zod.z.string(),
+	chainId: zod.z.number(),
+	symbol: zod.z.string(),
+	decimals: zod.z.number(),
+	name: zod.z.string(),
+	coinKey: zod.z.string().optional(),
+	logoURI: zod.z.string().optional(),
+	priceUSD: zod.z.string().optional(),
+	tags: zod.z.array(zod.z.string()).optional(),
+	verificationStatus: zod.z.string().optional(),
+	verificationStatusBreakdown: zod.z.array(zod.z.unknown()).optional()
+});
+/** Tool details */
+const ToolDetailsSchema = zod.z.object({
+	key: zod.z.string(),
+	name: zod.z.string(),
+	logoURI: zod.z.string().optional()
+});
+/** Fee split */
+const FeeSplitSchema = zod.z.object({
+	integratorFee: zod.z.string(),
+	lifiFee: zod.z.string()
+});
+/** Fee cost */
+const FeeCostSchema = zod.z.object({
+	name: zod.z.string(),
+	description: zod.z.string().optional(),
+	token: ComposerTokenSchema,
+	amount: zod.z.string(),
+	amountUSD: zod.z.string(),
+	percentage: zod.z.string(),
+	included: zod.z.boolean(),
+	feeSplit: FeeSplitSchema.optional()
+});
+/** Gas cost */
+const GasCostSchema = zod.z.object({
+	type: zod.z.string(),
+	price: zod.z.string().optional(),
+	estimate: zod.z.string().optional(),
+	limit: zod.z.string().optional(),
+	amount: zod.z.string(),
+	amountUSD: zod.z.string(),
+	token: ComposerTokenSchema
+});
+/** Quote action */
+const QuoteActionSchema = zod.z.object({
+	fromToken: ComposerTokenSchema,
+	fromAmount: zod.z.string(),
+	toToken: ComposerTokenSchema,
+	fromChainId: zod.z.number(),
+	toChainId: zod.z.number(),
+	slippage: zod.z.number(),
+	fromAddress: zod.z.string(),
+	toAddress: zod.z.string()
+});
+/** Quote estimate */
+const QuoteEstimateSchema = zod.z.object({
+	tool: zod.z.string(),
+	approvalAddress: zod.z.string().optional(),
+	toAmountMin: zod.z.string(),
+	toAmount: zod.z.string(),
+	fromAmount: zod.z.string(),
+	feeCosts: zod.z.array(FeeCostSchema).optional(),
+	gasCosts: zod.z.array(GasCostSchema).optional(),
+	executionDuration: zod.z.number(),
+	fromAmountUSD: zod.z.string().optional(),
+	toAmountUSD: zod.z.string().optional()
+});
+/** Transaction request — ready to sign */
+const TransactionRequestSchema = zod.z.object({
+	to: zod.z.string(),
+	data: zod.z.string(),
+	value: zod.z.string(),
+	chainId: zod.z.number(),
+	gasPrice: zod.z.string().optional(),
+	gasLimit: zod.z.string().optional(),
+	from: zod.z.string().optional()
+});
+/** Included step */
+const IncludedStepSchema = zod.z.object({
+	id: zod.z.string(),
+	type: zod.z.string(),
+	tool: zod.z.string(),
+	toolDetails: ToolDetailsSchema.optional(),
+	action: zod.z.record(zod.z.unknown()),
+	estimate: zod.z.record(zod.z.unknown())
+});
+/** Full Composer quote response */
+const QuoteResponseSchema = zod.z.object({
+	type: zod.z.string(),
+	id: zod.z.string(),
+	tool: zod.z.string(),
+	toolDetails: ToolDetailsSchema.optional(),
+	action: QuoteActionSchema,
+	estimate: QuoteEstimateSchema,
+	includedSteps: zod.z.array(IncludedStepSchema).optional(),
+	integrator: zod.z.string().optional(),
+	transactionRequest: TransactionRequestSchema,
+	transactionId: zod.z.string().optional()
+});
+//#endregion
+//#region src/errors.ts
+var EarnForgeError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "EarnForgeError";
+	}
+};
+var EarnApiError = class extends EarnForgeError {
+	constructor(message, status, url) {
+		super(message, "EARN_API_ERROR");
+		this.status = status;
+		this.url = url;
+		this.name = "EarnApiError";
+	}
+};
+var ComposerError = class extends EarnForgeError {
+	constructor(message, status) {
+		super(message, "COMPOSER_ERROR");
+		this.status = status;
+		this.name = "ComposerError";
+	}
+};
+var PreflightError = class extends EarnForgeError {
+	constructor(message, issues) {
+		super(message, "PREFLIGHT_ERROR");
+		this.issues = issues;
+		this.name = "PreflightError";
+	}
+};
+var RateLimitError = class extends EarnForgeError {
+	constructor(retryAfter) {
+		super(`Rate limited. Retry after ${retryAfter}ms`, "RATE_LIMIT");
+		this.retryAfter = retryAfter;
+		this.name = "RateLimitError";
+	}
+};
+//#endregion
+//#region src/rate-limiter.ts
+/**
+* Token-bucket rate limiter with queued async acquisition.
+* Default: 100 requests per minute for Earn Data API (Pitfall #14).
+*/
+var TokenBucketRateLimiter = class {
+	tokens;
+	lastRefill;
+	maxTokens;
+	refillRate;
+	_queue = Promise.resolve();
+	constructor(maxRequestsPerMinute = 100) {
+		this.maxTokens = maxRequestsPerMinute;
+		this.tokens = maxRequestsPerMinute;
+		this.refillRate = maxRequestsPerMinute / 6e4;
+		this.lastRefill = Date.now();
+	}
+	refill() {
+		const now = Date.now();
+		const elapsed = now - this.lastRefill;
+		this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
+		this.lastRefill = now;
+	}
+	acquire() {
+		this.refill();
+		if (this.tokens < 1) throw new RateLimitError(Math.ceil((1 - this.tokens) / this.refillRate));
+		this.tokens -= 1;
+	}
+	/**
+	* Queued async acquire — serializes concurrent callers to prevent
+	* race conditions where multiple callers pass the token check simultaneously.
+	*/
+	async acquireAsync() {
+		this._queue = this._queue.then(() => this._acquireInternal());
+		return this._queue;
+	}
+	async _acquireInternal() {
+		this.refill();
+		if (this.tokens < 1) {
+			const waitMs = Math.ceil((1 - this.tokens) / this.refillRate);
+			await new Promise((resolve) => setTimeout(resolve, waitMs));
+			this.refill();
+		}
+		this.tokens -= 1;
+	}
+	get remaining() {
+		this.refill();
+		return Math.floor(this.tokens);
+	}
+};
+//#endregion
+//#region src/cache.ts
+/**
+* In-memory LRU cache with configurable TTL.
+* Evicts least-recently-used entries when capacity is reached.
+*/
+var LRUCache = class {
+	map = /* @__PURE__ */ new Map();
+	maxSize;
+	ttl;
+	constructor(options = {}) {
+		this.maxSize = options.maxSize ?? 256;
+		this.ttl = options.ttl ?? 6e4;
+	}
+	get(key) {
+		const entry = this.map.get(key);
+		if (!entry) return void 0;
+		if (Date.now() > entry.expiresAt) {
+			this.map.delete(key);
+			return;
+		}
+		this.map.delete(key);
+		this.map.set(key, entry);
+		return entry.value;
+	}
+	set(key, value) {
+		this.map.delete(key);
+		if (this.map.size >= this.maxSize) {
+			const firstKey = this.map.keys().next().value;
+			if (firstKey !== void 0) this.map.delete(firstKey);
+		}
+		this.map.set(key, {
+			value,
+			expiresAt: Date.now() + this.ttl
+		});
+	}
+	has(key) {
+		return this.get(key) !== void 0;
+	}
+	clear() {
+		this.map.clear();
+	}
+	get size() {
+		return this.map.size;
+	}
+};
+//#endregion
+//#region src/retry.ts
+const DEFAULTS = {
+	maxRetries: 3,
+	baseDelay: 1e3,
+	maxDelay: 1e4
+};
+/**
+* Retry with exponential backoff on 429 / 5xx / network errors.
+*/
+async function withRetry(fn, options) {
+	const opts = {
+		...DEFAULTS,
+		...options
+	};
+	let lastError;
+	for (let attempt = 0; attempt <= opts.maxRetries; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt === opts.maxRetries) break;
+		if (!isRetryable(error)) throw error;
+		const delay = Math.min(opts.baseDelay * 2 ** attempt + Math.random() * 200, opts.maxDelay);
+		await new Promise((resolve) => setTimeout(resolve, delay));
+	}
+	throw lastError;
+}
+function isRetryable(error) {
+	if (error instanceof EarnApiError) return error.status === 429 || error.status >= 500;
+	if (error instanceof ComposerError) return error.status === 429 || error.status >= 500;
+	if (error instanceof Error) {
+		const msg = error.message.toLowerCase();
+		if (msg.includes("rate limit") || msg.includes("429")) return true;
+		if (msg.includes("network") || msg.includes("fetch") || msg.includes("econnreset")) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/clients/earn-data-client.ts
+/**
+* Earn Data API base URL — earn.li.fi (Pitfall #1).
+* No auth required (Pitfall #2).
+*/
+const DEFAULT_BASE_URL$1 = "https://earn.li.fi";
+var EarnDataClient = class {
+	baseUrl;
+	cache;
+	rateLimiter;
+	retryOpts;
+	constructor(options = {}) {
+		this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL$1;
+		this.cache = new LRUCache(options.cache);
+		this.rateLimiter = new TokenBucketRateLimiter(options.rateLimiter?.maxPerMinute ?? 100);
+		this.retryOpts = options.retry ?? {};
+	}
+	/**
+	* Low-level fetch with rate limiting, caching, retry.
+	* No auth header — Earn Data API is public (Pitfall #2).
+	*/
+	async fetch(path, cacheKey, parse) {
+		const cached = this.cache.get(cacheKey);
+		if (cached !== void 0) return cached;
+		await this.rateLimiter.acquireAsync();
+		const result = await withRetry(async () => {
+			const url = `${this.baseUrl}${path}`;
+			const res = await globalThis.fetch(url);
+			if (!res.ok) {
+				const body = await res.text().catch(() => "");
+				throw new EarnApiError(`Earn API error: ${res.status} ${res.statusText}. ${body}`.trim(), res.status, url);
+			}
+			return parse(await res.json());
+		}, this.retryOpts);
+		this.cache.set(cacheKey, result);
+		return result;
+	}
+	/** Fetch a single page of vaults */
+	async listVaults(params = {}) {
+		const searchParams = new URLSearchParams();
+		if (params.chainId !== void 0) searchParams.set("chainId", String(params.chainId));
+		if (params.asset) searchParams.set("asset", params.asset);
+		if (params.minTvl !== void 0) searchParams.set("minTvl", String(params.minTvl));
+		if (params.sortBy) searchParams.set("sortBy", params.sortBy);
+		if (params.cursor) searchParams.set("cursor", params.cursor);
+		const qs = searchParams.toString();
+		const path = `/v1/earn/vaults${qs ? `?${qs}` : ""}`;
+		return this.fetch(path, `vaults:${qs}`, (data) => VaultListResponseSchema.parse(data));
+	}
+	/**
+	* Async iterator for all vaults with auto-pagination via nextCursor.
+	* Page size is 50 (API default).
+	* (Pitfall #6)
+	*/
+	async *listAllVaults(params = {}) {
+		let cursor;
+		do {
+			const response = await this.listVaults({
+				...params,
+				cursor
+			});
+			for (const vault of response.data) yield vault;
+			cursor = response.nextCursor ?? void 0;
+		} while (cursor);
+	}
+	/**
+	* Get a single vault by chainId + address.
+	* chainId MUST be a number, not chain name (Pitfall — /vaults/Base/0x... returns 400).
+	*/
+	async getVault(chainId, address) {
+		if (!/^0x[0-9a-fA-F]{40}$/.test(address)) throw new EarnApiError(`Invalid vault address format: "${address}"`, 400, address);
+		const path = `/v1/earn/vaults/${chainId}/${encodeURIComponent(address)}`;
+		return this.fetch(path, `vault:${chainId}:${address}`, (data) => VaultSchema.parse(data));
+	}
+	/** Get a vault by slug (e.g., "8453-0xbeef...") */
+	async getVaultBySlug(slug) {
+		const dashIdx = slug.indexOf("-");
+		if (dashIdx === -1) throw new EarnApiError("Invalid slug format", 400, slug);
+		const chainId = Number(slug.slice(0, dashIdx));
+		const address = slug.slice(dashIdx + 1);
+		if (Number.isNaN(chainId)) throw new EarnApiError("Invalid chainId in slug", 400, slug);
+		if (!/^0x[0-9a-fA-F]{40}$/.test(address)) throw new EarnApiError(`Invalid address in slug: "${address}"`, 400, slug);
+		return this.getVault(chainId, address);
+	}
+	/** List supported chains */
+	async listChains() {
+		return this.fetch("/v1/earn/chains", "chains", (data) => ChainListResponseSchema.parse(data));
+	}
+	/** List supported protocols */
+	async listProtocols() {
+		return this.fetch("/v1/earn/protocols", "protocols", (data) => ProtocolListResponseSchema.parse(data));
+	}
+	/** Get portfolio positions for a wallet */
+	async getPortfolio(walletAddress) {
+		const path = `/v1/earn/portfolio/${walletAddress}/positions`;
+		return this.fetch(path, `portfolio:${walletAddress}`, (data) => PortfolioResponseSchema.parse(data));
+	}
+	/** Rate limiter remaining tokens */
+	get rateLimitRemaining() {
+		return this.rateLimiter.remaining;
+	}
+	/** Clear cache */
+	clearCache() {
+		this.cache.clear();
+	}
+};
+//#endregion
+//#region src/clients/composer-client.ts
+/**
+* Composer base URL — li.quest (Pitfall #1).
+* Requires x-lifi-api-key header (Pitfall #3).
+* Endpoint is GET, not POST (Pitfall #4).
+*/
+const DEFAULT_BASE_URL = "https://li.quest";
+var ComposerClient = class {
+	baseUrl;
+	apiKey;
+	retryOpts;
+	constructor(options) {
+		if (!options.apiKey) throw new ComposerError("Missing Composer API key. Set LIFI_API_KEY environment variable or pass composerApiKey to createEarnForge().", 401);
+		this.apiKey = options.apiKey;
+		this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+		this.retryOpts = options.retry ?? {};
+	}
+	/**
+	* Get a deposit/swap/bridge quote.
+	* Uses GET, not POST (Pitfall #4).
+	* Sends x-lifi-api-key header (Pitfall #3).
+	*/
+	async getQuote(params) {
+		return withRetry(async () => {
+			const searchParams = new URLSearchParams({
+				fromChain: String(params.fromChain),
+				toChain: String(params.toChain),
+				fromToken: params.fromToken,
+				toToken: params.toToken,
+				fromAddress: params.fromAddress,
+				toAddress: params.toAddress,
+				fromAmount: params.fromAmount
+			});
+			if (params.slippage !== void 0) searchParams.set("slippage", String(params.slippage));
+			if (params.fromAmountForGas) searchParams.set("fromAmountForGas", params.fromAmountForGas);
+			const url = `${this.baseUrl}/v1/quote?${searchParams.toString()}`;
+			const res = await globalThis.fetch(url, {
+				method: "GET",
+				headers: { "x-lifi-api-key": this.apiKey }
+			});
+			if (!res.ok) {
+				const body = await res.text().catch(() => "");
+				throw new ComposerError(`Composer error: ${res.status} ${res.statusText}. ${body}`, res.status);
+			}
+			const json = await res.json();
+			return QuoteResponseSchema.parse(json);
+		}, this.retryOpts);
+	}
+};
+//#endregion
+//#region src/build-deposit-quote.ts
+/**
+* Build a deposit quote with all 18 pitfalls handled:
+*
+* - toToken = vault.address (Pitfall #5)
+* - Uses correct decimals from underlyingTokens (Pitfall #9)
+* - Validates isTransactional (Pitfall #13)
+* - Validates underlyingTokens is non-empty (Pitfall #15)
+* - GET request via ComposerClient (Pitfall #4)
+* - API key in header via ComposerClient (Pitfall #3)
+*/
+async function buildDepositQuote(vault, options, composer) {
+	if (!/^0x[0-9a-fA-F]{40}$/.test(options.wallet)) throw new EarnForgeError(`Invalid wallet address: "${options.wallet}". Must be a 0x-prefixed 40-hex-char address.`, "INVALID_WALLET");
+	if (!vault.isTransactional) throw new EarnForgeError(`Vault ${vault.slug} is not transactional — deposits are not supported.`, "NOT_TRANSACTIONAL");
+	if (vault.underlyingTokens.length === 0 && !options.fromToken) throw new EarnForgeError(`Vault ${vault.slug} has no underlyingTokens. You must specify fromToken explicitly.`, "NO_UNDERLYING_TOKENS");
+	const fromTokenAddr = options.fromToken ?? vault.underlyingTokens[0]?.address;
+	if (!fromTokenAddr) throw new EarnForgeError("Cannot determine fromToken — vault has no underlyingTokens and none was provided.", "NO_FROM_TOKEN");
+	const fromChain = options.fromChain ?? vault.chainId;
+	if (fromChain !== vault.chainId && !options.fromToken) throw new EarnForgeError(`Cross-chain deposits require an explicit fromToken. The vault's underlyingTokens are on chain ${vault.chainId}, not chain ${fromChain}.`, "CROSS_CHAIN_FROM_TOKEN_REQUIRED");
+	const decimals = vault.underlyingTokens.find((t) => t.address.toLowerCase() === fromTokenAddr.toLowerCase())?.decimals ?? 18;
+	const rawAmount = toSmallestUnit(options.fromAmount, decimals);
+	const quoteParams = {
+		fromChain,
+		toChain: vault.chainId,
+		fromToken: fromTokenAddr,
+		toToken: vault.address,
+		fromAddress: options.wallet,
+		toAddress: options.wallet,
+		fromAmount: rawAmount,
+		slippage: options.slippage,
+		fromAmountForGas: options.fromAmountForGas
+	};
+	return {
+		quote: await composer.getQuote(quoteParams),
+		vault,
+		humanAmount: options.fromAmount,
+		rawAmount,
+		decimals
+	};
+}
+/**
+* Convert a human-readable amount to the smallest unit.
+* e.g., "1" with 6 decimals → "1000000" (Pitfall #9)
+*/
+function toSmallestUnit(amount, decimals) {
+	if (!amount || !/^\d+(\.\d+)?$/.test(amount)) throw new EarnForgeError(`Invalid amount "${amount}". Must be a positive numeric string (e.g., "100" or "1.5").`, "INVALID_AMOUNT");
+	const parts = amount.split(".");
+	const whole = parts[0] ?? "0";
+	let fractional = parts[1] ?? "";
+	if (fractional.length > decimals) fractional = fractional.slice(0, decimals);
+	else fractional = fractional.padEnd(decimals, "0");
+	return `${whole}${fractional}`.replace(/^0+/, "") || "0";
+}
+/**
+* Convert smallest unit to human-readable amount.
+*/
+function fromSmallestUnit(rawAmount, decimals) {
+	if (decimals === 0) return rawAmount;
+	const padded = rawAmount.padStart(decimals + 1, "0");
+	const whole = padded.slice(0, padded.length - decimals);
+	const fractional = padded.slice(padded.length - decimals).replace(/0+$/, "");
+	return fractional ? `${whole}.${fractional}` : whole;
+}
+//#endregion
+//#region src/build-redeem-quote.ts
+/**
+* Build a withdrawal/redeem quote.
+*
+* Withdrawal is the reverse of deposit:
+* - fromToken = vault.address (the vault share token)
+* - toToken = underlying token address (what you get back)
+*
+* Uses the same Composer /v1/quote endpoint — just swapped tokens.
+*/
+async function buildRedeemQuote(vault, options, composer) {
+	if (!/^0x[0-9a-fA-F]{40}$/.test(options.wallet)) throw new EarnForgeError(`Invalid wallet address: "${options.wallet}".`, "INVALID_WALLET");
+	if (!vault.isRedeemable) throw new EarnForgeError(`Vault ${vault.slug} is not redeemable — withdrawals are not supported.`, "NOT_REDEEMABLE");
+	const rawAmount = toSmallestUnit(options.fromAmount, 18);
+	const toToken = options.toToken ?? vault.underlyingTokens[0]?.address;
+	if (!toToken) throw new EarnForgeError("Cannot determine toToken for redeem — vault has no underlyingTokens and none was provided.", "NO_TO_TOKEN");
+	const toChain = options.toChain ?? vault.chainId;
+	if (toChain !== vault.chainId && !options.toToken) throw new EarnForgeError(`Cross-chain redeems require an explicit toToken address on the destination chain.`, "CROSS_CHAIN_TO_TOKEN_REQUIRED");
+	const quoteParams = {
+		fromChain: vault.chainId,
+		toChain,
+		fromToken: vault.address,
+		toToken,
+		fromAddress: options.wallet,
+		toAddress: options.wallet,
+		fromAmount: rawAmount,
+		slippage: options.slippage
+	};
+	return {
+		quote: await composer.getQuote(quoteParams),
+		vault,
+		humanAmount: options.fromAmount,
+		rawAmount
+	};
+}
+//#endregion
+//#region src/preflight.ts
+/**
+* Run preflight checks before a deposit:
+* - isTransactional check (Pitfall #13)
+* - Chain mismatch check (Pitfall #12) — warning for cross-chain, error for same-chain
+* - Gas token balance check (Pitfall #11)
+* - Token balance check (uses string-based toSmallestUnit to avoid float precision loss)
+* - underlyingTokens existence (Pitfall #15)
+* - isRedeemable warning
+*/
+function preflight(vault, wallet, options = {}) {
+	const issues = [];
+	if (!vault.isTransactional) issues.push({
+		code: "NOT_TRANSACTIONAL",
+		message: `Vault ${vault.slug} is not transactional — cannot deposit.`,
+		severity: "error"
+	});
+	if (options.walletChainId !== void 0 && options.walletChainId !== vault.chainId) issues.push({
+		code: "CHAIN_MISMATCH",
+		message: `Wallet is on chain ${options.walletChainId} but vault is on chain ${vault.chainId}. ${options.crossChain ? "Composer will handle cross-chain bridging." : "Switch network or use cross-chain deposit."}`,
+		severity: "warning"
+	});
+	if (options.nativeBalance !== void 0 && options.nativeBalance === 0n) issues.push({
+		code: "NO_GAS",
+		message: "Wallet has 0 native gas token. Transaction will fail.",
+		severity: "error"
+	});
+	if (vault.underlyingTokens.length === 0) issues.push({
+		code: "NO_UNDERLYING_TOKENS",
+		message: "Vault has no underlyingTokens metadata. You must specify fromToken manually.",
+		severity: "warning"
+	});
+	if (options.tokenBalance !== void 0 && options.depositAmount !== void 0) {
+		const decimals = options.tokenDecimals ?? vault.underlyingTokens[0]?.decimals ?? 18;
+		const requiredRaw = BigInt(toSmallestUnit(options.depositAmount, decimals));
+		if (options.tokenBalance < requiredRaw) issues.push({
+			code: "INSUFFICIENT_BALANCE",
+			message: `Insufficient token balance. Have: ${options.tokenBalance}, need: ${requiredRaw}`,
+			severity: "error"
+		});
+	}
+	if (!vault.isRedeemable) issues.push({
+		code: "NOT_REDEEMABLE",
+		message: "Vault is not redeemable — you may not be able to withdraw.",
+		severity: "warning"
+	});
+	return {
+		ok: issues.filter((i) => i.severity === "error").length === 0,
+		issues,
+		vault,
+		wallet
+	};
+}
+//#endregion
+//#region src/risk-scorer.ts
+/** Blue-chip / mature protocol tiers */
+const PROTOCOL_TIERS = {
+	"aave-v3": 9,
+	"morpho-v1": 9,
+	"euler-v2": 7,
+	"pendle": 7,
+	"maple": 6,
+	"ethena-usde": 7,
+	"ether.fi-liquid": 7,
+	"ether.fi-stake": 7,
+	"upshift": 5,
+	"neverland": 4,
+	"yo-protocol": 4
+};
+/**
+* Compute a composite 0–10 risk score for a vault.
+*
+* Dimensions:
+* - TVL magnitude: higher TVL = lower risk
+* - APY stability: small divergence between apy1d/apy30d/total = more stable
+* - Protocol maturity: known blue-chip protocols score higher
+* - Redeemability: non-redeemable = liquidity risk
+* - Asset type: stablecoin tag = lower asset risk
+*/
+function riskScore(vault) {
+	const tvlScore = scoreTvl(vault);
+	const apyScore = scoreApyStability(vault);
+	const protocolScore = scoreProtocol(vault);
+	const redeemScore = vault.isRedeemable ? 10 : 3;
+	const assetScore = vault.tags.includes("stablecoin") ? 9 : 5;
+	const weights = {
+		tvl: .25,
+		apy: .2,
+		protocol: .25,
+		redeem: .15,
+		asset: .15
+	};
+	const score = tvlScore * weights.tvl + apyScore * weights.apy + protocolScore * weights.protocol + redeemScore * weights.redeem + assetScore * weights.asset;
+	const rounded = Math.round(score * 10) / 10;
+	return {
+		score: rounded,
+		breakdown: {
+			tvl: tvlScore,
+			apyStability: apyScore,
+			protocol: protocolScore,
+			redeemability: redeemScore,
+			assetType: assetScore
+		},
+		label: rounded >= 7 ? "low" : rounded >= 4 ? "medium" : "high"
+	};
+}
+function scoreTvl(vault) {
+	const tvl = parseTvl(vault.analytics.tvl);
+	if (tvl.parsed >= 1e8) return 10;
+	if (tvl.parsed >= 5e7) return 9;
+	if (tvl.parsed >= 1e7) return 8;
+	if (tvl.parsed >= 5e6) return 7;
+	if (tvl.parsed >= 1e6) return 5;
+	if (tvl.parsed >= 1e5) return 3;
+	return 1;
+}
+function scoreApyStability(vault) {
+	const { apy, apy1d, apy30d } = vault.analytics;
+	const total = apy.total;
+	if (apy30d === null && apy1d === null) return 5;
+	const ref = apy30d ?? apy1d ?? total;
+	if (ref === 0 || total === 0) return 5;
+	const divergence = Math.abs(total - ref) / Math.max(total, ref);
+	if (divergence < .05) return 10;
+	if (divergence < .1) return 8;
+	if (divergence < .2) return 6;
+	if (divergence < .5) return 4;
+	return 2;
+}
+function scoreProtocol(vault) {
+	return PROTOCOL_TIERS[vault.protocol.name] ?? 3;
+}
+const STRATEGIES = {
+	conservative: {
+		name: "conservative",
+		description: "Stablecoin-tagged, TVL > $50M, APY 3-7%, blue-chip protocols only",
+		filters: {
+			tags: ["stablecoin"],
+			minTvlUsd: 5e7,
+			protocols: [
+				"aave-v3",
+				"morpho-v1",
+				"euler-v2",
+				"pendle",
+				"maple"
+			]
+		},
+		sort: "apy",
+		sortDirection: "desc"
+	},
+	"max-apy": {
+		name: "max-apy",
+		description: "Sort by APY descending, no TVL floor",
+		filters: {},
+		sort: "apy",
+		sortDirection: "desc"
+	},
+	diversified: {
+		name: "diversified",
+		description: "Spread across 3+ chains, 3+ protocols, mix of stablecoin + LST",
+		filters: { minTvlUsd: 1e6 },
+		sort: "apy",
+		sortDirection: "desc"
+	},
+	"risk-adjusted": {
+		name: "risk-adjusted",
+		description: "Filter by risk score >= 7, then sort by APY",
+		filters: { minRiskScore: 7 },
+		sort: "apy",
+		sortDirection: "desc"
+	}
+};
+function getStrategy(preset) {
+	return STRATEGIES[preset];
+}
+//#endregion
+//#region src/suggest.ts
+/**
+* Portfolio allocation engine.
+* Uses a risk-adjusted score: score = apy / (11 - riskScore)
+* to weight allocations proportionally.
+* Enforces maxChains diversification constraint.
+*/
+function suggest(vaults, params) {
+	const maxVaults = params.maxVaults ?? 5;
+	const maxChains = params.maxChains ?? 5;
+	let candidates = params.asset ? vaults.filter((v) => v.underlyingTokens.some((t) => t.symbol.toUpperCase() === params.asset?.toUpperCase())) : [...vaults];
+	candidates = candidates.filter((v) => v.isTransactional);
+	if (params.strategy) {
+		const strategy = STRATEGIES[params.strategy];
+		if (strategy) {
+			if (strategy.filters.minTvlUsd) {
+				const minTvl = strategy.filters.minTvlUsd;
+				candidates = candidates.filter((v) => parseTvl(v.analytics.tvl).parsed >= minTvl);
+			}
+			if (strategy.filters.tags?.length) {
+				const requiredTags = strategy.filters.tags;
+				candidates = candidates.filter((v) => requiredTags.some((t) => v.tags.includes(t)));
+			}
+			if (strategy.filters.protocols?.length) {
+				const allowedProtocols = strategy.filters.protocols;
+				candidates = candidates.filter((v) => allowedProtocols.includes(v.protocol.name));
+			}
+			if (strategy.filters.minRiskScore) {
+				const minScore = strategy.filters.minRiskScore;
+				candidates = candidates.filter((v) => riskScore(v).score >= minScore);
+			}
+		}
+	}
+	const scored = candidates.map((vault) => {
+		const risk = riskScore(vault);
+		const apy = vault.analytics.apy.total;
+		return {
+			vault,
+			risk,
+			apy,
+			allocationScore: apy * (risk.score / 10)
+		};
+	});
+	scored.sort((a, b) => b.allocationScore - a.allocationScore);
+	const selectedChains = /* @__PURE__ */ new Set();
+	const selected = [];
+	for (const item of scored) {
+		if (selected.length >= maxVaults) break;
+		if (selectedChains.size >= maxChains && !selectedChains.has(item.vault.chainId)) continue;
+		selectedChains.add(item.vault.chainId);
+		selected.push(item);
+	}
+	if (selected.length === 0) return {
+		totalAmount: params.amount,
+		expectedApy: 0,
+		allocations: []
+	};
+	const totalScore = selected.reduce((sum, s) => sum + s.allocationScore, 0);
+	const allocations = selected.map((s) => {
+		const percentage = totalScore > 0 ? s.allocationScore / totalScore * 100 : 100 / selected.length;
+		return {
+			vault: s.vault,
+			risk: s.risk,
+			percentage: Math.round(percentage * 10) / 10,
+			amount: Math.round(percentage / 100 * params.amount * 100) / 100,
+			apy: s.apy
+		};
+	});
+	const expectedApy = allocations.reduce((sum, a) => sum + a.apy * (a.percentage / 100), 0);
+	return {
+		totalAmount: params.amount,
+		expectedApy: Math.round(expectedApy * 100) / 100,
+		allocations
+	};
+}
+//#endregion
+//#region src/gas-optimizer.ts
+const CHAIN_NAMES = {
+	1: "Ethereum",
+	10: "Optimism",
+	56: "BSC",
+	100: "Gnosis",
+	130: "Unichain",
+	137: "Polygon",
+	143: "Monad",
+	146: "Sonic",
+	5e3: "Mantle",
+	8453: "Base",
+	42161: "Arbitrum",
+	42220: "Celo",
+	43114: "Avalanche",
+	59144: "Linea",
+	80094: "Berachain",
+	747474: "Katana"
+};
+/**
+* Compare deposit routes from multiple source chains.
+* Returns routes sorted by total cost (cheapest first).
+* Integrates LI.Fuel via fromAmountForGas parameter.
+*/
+async function optimizeGasRoutes(vault, composer, options) {
+	const fromChains = options.fromChains ?? [vault.chainId];
+	const decimals = vault.underlyingTokens[0]?.decimals ?? 18;
+	const rawAmount = toSmallestUnit(options.fromAmount, decimals);
+	const defaultFromToken = options.fromToken ?? vault.underlyingTokens[0]?.address;
+	if (!defaultFromToken && !options.fromTokens) return [];
+	const routePromises = fromChains.map(async (fromChain) => {
+		try {
+			const fromToken = options.fromTokens?.[fromChain] ?? (fromChain === vault.chainId ? defaultFromToken : void 0);
+			if (!fromToken) return null;
+			const quote = await composer.getQuote({
+				fromChain,
+				toChain: vault.chainId,
+				fromToken,
+				toToken: vault.address,
+				fromAddress: options.wallet,
+				toAddress: options.wallet,
+				fromAmount: rawAmount,
+				fromAmountForGas: options.fromAmountForGas
+			});
+			const gasCostUsd = (quote.estimate.gasCosts ?? []).reduce((sum, g) => sum + Number(g.amountUSD), 0);
+			const feeCostUsd = (quote.estimate.feeCosts ?? []).reduce((sum, f) => sum + Number(f.amountUSD), 0);
+			return {
+				fromChain,
+				fromChainName: CHAIN_NAMES[fromChain] ?? `Chain ${fromChain}`,
+				quote,
+				totalCostUsd: gasCostUsd + feeCostUsd,
+				gasCostUsd,
+				feeCostUsd,
+				executionDuration: quote.estimate.executionDuration
+			};
+		} catch {
+			return null;
+		}
+	});
+	return (await Promise.all(routePromises)).filter((r) => r !== null).sort((a, b) => a.totalCostUsd - b.totalCostUsd);
+}
+//#endregion
+//#region src/watch.ts
+/**
+* Watch a vault for APY/TVL changes.
+* Returns an AsyncGenerator that yields events.
+* Supports cancellation via AbortSignal and maxIterations.
+*/
+async function* watch(client, vaultSlug, options = {}) {
+	const interval = options.interval ?? 6e4;
+	const apyThreshold = options.apyDropPercent ?? 20;
+	const tvlThreshold = options.tvlDropPercent ?? 30;
+	const maxIter = options.maxIterations ?? 0;
+	let previous = null;
+	let iteration = 0;
+	while (true) {
+		if (options.signal?.aborted) return;
+		if (maxIter > 0 && iteration >= maxIter) return;
+		iteration++;
+		const vault = await client.getVaultBySlug(vaultSlug);
+		const currentApy = vault.analytics.apy.total;
+		const currentTvl = parseTvl(vault.analytics.tvl).parsed;
+		const current = {
+			apy: currentApy,
+			tvlUsd: currentTvl
+		};
+		if (previous) {
+			if (previous.apy > 0) {
+				if ((previous.apy - currentApy) / previous.apy * 100 >= apyThreshold) yield {
+					type: "apy-drop",
+					vault,
+					previous,
+					current,
+					timestamp: /* @__PURE__ */ new Date()
+				};
+			}
+			if (previous.tvlUsd > 0) {
+				if ((previous.tvlUsd - currentTvl) / previous.tvlUsd * 100 >= tvlThreshold) yield {
+					type: "tvl-drop",
+					vault,
+					previous,
+					current,
+					timestamp: /* @__PURE__ */ new Date()
+				};
+			}
+			yield {
+				type: "update",
+				vault,
+				previous,
+				current,
+				timestamp: /* @__PURE__ */ new Date()
+			};
+		} else yield {
+			type: "update",
+			vault,
+			previous: null,
+			current,
+			timestamp: /* @__PURE__ */ new Date()
+		};
+		previous = current;
+		if (options.signal?.aborted) return;
+		await new Promise((resolve) => {
+			const timer = setTimeout(resolve, interval);
+			options.signal?.addEventListener("abort", () => {
+				clearTimeout(timer);
+				resolve();
+			}, { once: true });
+		});
+	}
+}
+//#endregion
+//#region src/apy-history.ts
+/**
+* DeFiLlama protocol name mapping.
+* LI.FI uses names like "morpho-v1", DeFiLlama uses the same.
+* Some need explicit mapping.
+*/
+const LIFI_TO_LLAMA_PROJECT = {
+	"aave-v3": "aave-v3",
+	"morpho-v1": "morpho-v1",
+	"euler-v2": "euler-v2",
+	"pendle": "pendle",
+	"maple": "maple-finance",
+	"ethena-usde": "ethena",
+	"ether.fi-liquid": "ether.fi",
+	"ether.fi-stake": "ether.fi-stake",
+	"upshift": "upshift",
+	"neverland": "neverland",
+	"yo-protocol": "yo-protocol"
+};
+const CHAIN_ID_TO_LLAMA = {
+	1: "Ethereum",
+	10: "Optimism",
+	56: "BSC",
+	100: "Gnosis",
+	130: "Unichain",
+	137: "Polygon",
+	143: "Monad",
+	146: "Sonic",
+	5e3: "Mantle",
+	8453: "Base",
+	42161: "Arbitrum",
+	42220: "Celo",
+	43114: "Avalanche",
+	59144: "Linea",
+	80094: "Berachain",
+	747474: "Katana"
+};
+const poolsCache = new LRUCache({
+	ttl: 36e5,
+	maxSize: 1
+});
+/**
+* Fetch the DeFiLlama pools list with caching (1 hour TTL).
+* The pools endpoint returns ~16K pools, ~10MB. We cache it to avoid
+* fetching it on every call.
+*/
+async function fetchPools() {
+	const cached = poolsCache.get("all");
+	if (cached) return cached;
+	const res = await globalThis.fetch("https://yields.llama.fi/pools");
+	if (!res.ok) return [];
+	const pools = (await res.json()).data ?? [];
+	poolsCache.set("all", pools);
+	return pools;
+}
+/**
+* Match a LI.FI vault to a DeFiLlama pool.
+*
+* DeFiLlama pools have UUID IDs (not addresses). Matching strategy:
+* 1. Filter by project name (LI.FI "morpho-v1" → DeFiLlama "morpho-v1")
+* 2. Filter by chain name
+* 3. Filter by underlying token address (the deposit token)
+* 4. Match by symbol (vault name)
+* 5. If multiple matches, pick the one with closest TVL to the LI.FI vault
+*/
+function matchPool(vault, pools) {
+	const chainName = CHAIN_ID_TO_LLAMA[vault.chainId];
+	if (!chainName) return null;
+	const llamaProject = LIFI_TO_LLAMA_PROJECT[vault.protocol.name];
+	if (!llamaProject) return null;
+	let candidates = pools.filter((p) => p.project === llamaProject && p.chain === chainName);
+	if (candidates.length === 0) return null;
+	if (vault.underlyingTokens.length > 0) {
+		const underlyingAddr = vault.underlyingTokens[0].address.toLowerCase();
+		const withToken = candidates.filter((p) => p.underlyingTokens?.some((t) => t.toLowerCase() === underlyingAddr));
+		if (withToken.length > 0) candidates = withToken;
+	}
+	const vaultName = vault.name.toUpperCase();
+	const bySymbol = candidates.filter((p) => p.symbol.toUpperCase() === vaultName);
+	if (bySymbol.length > 0) candidates = bySymbol;
+	if (candidates.length === 0) return null;
+	const vaultTvl = Number(vault.analytics.tvl.usd);
+	candidates.sort((a, b) => Math.abs(a.tvlUsd - vaultTvl) - Math.abs(b.tvlUsd - vaultTvl));
+	return candidates[0] ?? null;
+}
+async function getApyHistory(vaultOrAddress, chainId) {
+	try {
+		const pools = await fetchPools();
+		if (pools.length === 0) return [];
+		let pool = null;
+		if (typeof vaultOrAddress === "string") {
+			const chainName = CHAIN_ID_TO_LLAMA[chainId];
+			if (!chainName) return [];
+			const addr = vaultOrAddress.toLowerCase();
+			pool = pools.find((p) => p.chain === chainName && p.underlyingTokens?.some((t) => t.toLowerCase() === addr)) ?? null;
+		} else pool = matchPool(vaultOrAddress, pools);
+		if (!pool) return [];
+		const chartRes = await globalThis.fetch(`https://yields.llama.fi/chart/${pool.pool}`);
+		if (!chartRes.ok) return [];
+		return ((await chartRes.json()).data ?? []).slice(-30).map((d) => ({
+			timestamp: d.timestamp,
+			apy: d.apy ?? 0,
+			tvlUsd: d.tvlUsd ?? 0
+		}));
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/allowance.ts
+const ALLOWANCE_SELECTOR = "0xdd62ed3e";
+const APPROVE_SELECTOR = "0x095ea7b3";
+/**
+* Check the ERC-20 allowance for a token.
+*
+* @param rpcUrl - JSON-RPC endpoint for the chain
+* @param tokenAddress - ERC-20 token contract address
+* @param owner - Wallet address (token holder)
+* @param spender - Address to check allowance for (from quote.estimate.approvalAddress)
+* @param requiredAmount - Amount needed in smallest unit
+*/
+async function checkAllowance(rpcUrl, tokenAddress, owner, spender, requiredAmount) {
+	const calldata = `${ALLOWANCE_SELECTOR}${owner.slice(2).toLowerCase().padStart(64, "0")}${spender.slice(2).toLowerCase().padStart(64, "0")}`;
+	const json = await (await globalThis.fetch(rpcUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			jsonrpc: "2.0",
+			method: "eth_call",
+			params: [{
+				to: tokenAddress,
+				data: calldata
+			}, "latest"],
+			id: 1
+		})
+	})).json();
+	if (json.error || !json.result) return {
+		allowance: 0n,
+		sufficient: false,
+		requiredAmount
+	};
+	const allowance = BigInt(json.result);
+	return {
+		allowance,
+		sufficient: allowance >= requiredAmount,
+		requiredAmount
+	};
+}
+/**
+* Build an ERC-20 approve transaction.
+*
+* @param tokenAddress - ERC-20 token contract
+* @param spender - Address to approve (from quote.estimate.approvalAddress)
+* @param amount - Amount to approve in smallest unit (use MaxUint256 for unlimited)
+* @param chainId - Chain ID for the transaction
+*/
+function buildApprovalTx(tokenAddress, spender, amount, chainId) {
+	return {
+		to: tokenAddress,
+		data: `${APPROVE_SELECTOR}${spender.slice(2).toLowerCase().padStart(64, "0")}${amount.toString(16).padStart(64, "0")}`,
+		value: "0x0",
+		chainId
+	};
+}
+/** MaxUint256 for unlimited approval */
+const MAX_UINT256 = 2n ** 256n - 1n;
+//#endregion
+//#region src/index.ts
+/**
+* Create an EarnForge instance — the main entry point.
+*
+* ```ts
+* const forge = createEarnForge({ composerApiKey: process.env.LIFI_API_KEY });
+* for await (const vault of forge.vaults.listAll({ chainId: 8453 })) {
+*   console.log(vault.name, vault.analytics.apy.total);
+* }
+* ```
+*/
+function createEarnForge(options = {}) {
+	const earnData = new EarnDataClient({
+		cache: options.cache,
+		...options.earnData
+	});
+	const composer = options.composerApiKey ? new ComposerClient({
+		apiKey: options.composerApiKey,
+		baseUrl: options.composerBaseUrl
+	}) : null;
+	function requireComposer() {
+		if (!composer) throw new Error("Composer API key required. Pass composerApiKey to createEarnForge() or set LIFI_API_KEY.");
+		return composer;
+	}
+	async function getTopVaults(params = {}) {
+		const limit = params.limit ?? 10;
+		const strategy = params.strategy ? STRATEGIES[params.strategy] : null;
+		const vaults = [];
+		for await (const vault of earnData.listAllVaults({
+			chainId: params.chainId,
+			asset: params.asset,
+			minTvl: params.minTvl
+		})) {
+			if (strategy) {
+				const tvlUsd = parseTvl(vault.analytics.tvl).parsed;
+				if (strategy.filters.minTvlUsd && tvlUsd < strategy.filters.minTvlUsd) continue;
+				if (strategy.filters.tags && !strategy.filters.tags.some((t) => vault.tags.includes(t))) continue;
+				if (strategy.filters.protocols && !strategy.filters.protocols.includes(vault.protocol.name)) continue;
+				if (strategy.filters.minRiskScore && riskScore(vault).score < strategy.filters.minRiskScore) continue;
+			}
+			vaults.push(vault);
+			if (vaults.length >= limit * 3) break;
+		}
+		vaults.sort((a, b) => b.analytics.apy.total - a.analytics.apy.total);
+		return vaults.slice(0, limit);
+	}
+	return {
+		vaults: {
+			list: (params) => earnData.listVaults(params),
+			listAll: (params) => earnData.listAllVaults(params),
+			get: (slug) => earnData.getVaultBySlug(slug),
+			top: getTopVaults
+		},
+		chains: { list: () => earnData.listChains() },
+		protocols: { list: () => earnData.listProtocols() },
+		portfolio: { get: (wallet) => earnData.getPortfolio(wallet) },
+		buildDepositQuote: (vault, opts) => buildDepositQuote(vault, opts, requireComposer()),
+		buildRedeemQuote: (vault, opts) => buildRedeemQuote(vault, opts, requireComposer()),
+		preflight: (vault, wallet, opts) => preflight(vault, wallet, opts),
+		riskScore: (vault) => riskScore(vault),
+		suggest: async (params) => {
+			const vaults = params.vaults ?? [];
+			if (vaults.length === 0) {
+				const allVaults = [];
+				for await (const v of earnData.listAllVaults({ asset: params.asset })) allVaults.push(v);
+				return suggest(allVaults, params);
+			}
+			return suggest(vaults, params);
+		},
+		optimizeGasRoutes: (vault, opts) => optimizeGasRoutes(vault, requireComposer(), opts),
+		watch: (slug, opts) => watch(earnData, slug, opts),
+		getApyHistory,
+		earnDataClient: earnData,
+		composerClient: composer
+	};
+}
+//#endregion
+exports.AnalyticsSchema = AnalyticsSchema;
+exports.ApySchema = ApySchema;
+exports.ChainListResponseSchema = ChainListResponseSchema;
+exports.ChainSchema = ChainSchema;
+exports.ComposerClient = ComposerClient;
+exports.ComposerError = ComposerError;
+exports.ComposerTokenSchema = ComposerTokenSchema;
+exports.EarnApiError = EarnApiError;
+exports.EarnDataClient = EarnDataClient;
+exports.EarnForgeError = EarnForgeError;
+exports.FeeCostSchema = FeeCostSchema;
+exports.FeeSplitSchema = FeeSplitSchema;
+exports.GasCostSchema = GasCostSchema;
+exports.IncludedStepSchema = IncludedStepSchema;
+exports.LRUCache = LRUCache;
+exports.MAX_UINT256 = MAX_UINT256;
+exports.PackSchema = PackSchema;
+exports.PortfolioResponseSchema = PortfolioResponseSchema;
+exports.PositionAssetSchema = PositionAssetSchema;
+exports.PositionSchema = PositionSchema;
+exports.PreflightError = PreflightError;
+exports.ProtocolDetailSchema = ProtocolDetailSchema;
+exports.ProtocolListResponseSchema = ProtocolListResponseSchema;
+exports.ProtocolSchema = ProtocolSchema;
+exports.QuoteActionSchema = QuoteActionSchema;
+exports.QuoteEstimateSchema = QuoteEstimateSchema;
+exports.QuoteResponseSchema = QuoteResponseSchema;
+exports.RateLimitError = RateLimitError;
+exports.STRATEGIES = STRATEGIES;
+exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
+exports.ToolDetailsSchema = ToolDetailsSchema;
+exports.TransactionRequestSchema = TransactionRequestSchema;
+exports.TvlSchema = TvlSchema;
+exports.UnderlyingTokenSchema = UnderlyingTokenSchema;
+exports.VaultListResponseSchema = VaultListResponseSchema;
+exports.VaultSchema = VaultSchema;
+exports.buildApprovalTx = buildApprovalTx;
+exports.buildDepositQuote = buildDepositQuote;
+exports.buildRedeemQuote = buildRedeemQuote;
+exports.checkAllowance = checkAllowance;
+exports.createEarnForge = createEarnForge;
+exports.fromSmallestUnit = fromSmallestUnit;
+exports.getApyHistory = getApyHistory;
+exports.getBestApy = getBestApy;
+exports.getStrategy = getStrategy;
+exports.isRetryable = isRetryable;
+exports.optimizeGasRoutes = optimizeGasRoutes;
+exports.parseTvl = parseTvl;
+exports.preflight = preflight;
+exports.riskScore = riskScore;
+exports.suggest = suggest;
+exports.toSmallestUnit = toSmallestUnit;
+exports.watch = watch;
+exports.withRetry = withRetry;