@steerprotocol/sdk 4.0.0-next.2 → 4.0.0-next.4

package/README.md

@@ -52,7 +52,7 @@ SDK integration code owns Steer's per-network contracts and data adapters.
 
 ## Vault discovery
 
-List indexed vault addresses, then load a result through the normal identity-verified resolver:
+List indexed vault metadata, then load a result through the identity-verified resolver:
 
 ```ts
 const page = await steer.listVaults({
@@ -62,12 +62,13 @@ const page = await steer.listVaults({
   limit: 20,
 });
 
-for (const address of page.items) {
-  const vault = await steer.getVault(ChainId.Base, address);
+for (const metadata of page.items) {
+  const vault = await steer.getVault(ChainId.Base, metadata.id);
+  vault.metadata.name; // Complete indexed metadata, separate from verified accounting.
 }
 
 // Load a page or any explicit address list through the same resolver.
-const vaults = await steer.getVaults(ChainId.Base, page.items);
+const vaults = await steer.getVaults(ChainId.Base, page.items.map((metadata) => metadata.id));
 
 if (page.nextCursor) {
   const next = await steer.listVaults({
@@ -78,6 +79,41 @@ if (page.nextCursor) {
 }
 ```
 
+`listVaults()` returns `Page<VaultMetadata>` with immutable indexed records:
+
+```ts
+interface VaultMetadata {
+  readonly id: Address;
+  readonly name: string | null;
+  readonly symbol: string | null;
+  readonly decimals: string | null;
+  readonly beaconName: string;
+  readonly createdAt: string;
+  readonly state: string | null;
+  readonly pool: Address | null;
+  readonly poolKey?: string | null;
+  readonly token0: Address | null;
+  readonly token1: Address | null;
+  readonly payloadIpfs: string | null;
+  readonly strategyToken: { readonly id: string } | null;
+}
+```
+
+This replaces address-only pages. Use `item.id` when passing a listed result to a vault getter.
+`decimals` and `createdAt` retain their indexed string representation. Null fields remain null;
+`poolKey` is omitted when the subgraph schema does not expose it. Only an explicit rejection of
+that optional field permits querying without it; other GraphQL and transport errors propagate.
+
+Every loaded `SteerVault` exposes the same model as `vault.metadata`. Vault construction loads
+indexed metadata once per resolution/snapshot batch, preserving input order and duplicates.
+Loading a vault, including internal construction during bulk snapshots, now requires indexed
+metadata in addition to RPC identity verification. Missing records and indexer failures propagate.
+Existing resolved vault operations retain that metadata snapshot. It reflects the indexer's head
+at construction, independently of an explicitly selected RPC block; state, pool and token hints
+never replace the verified underlying references or accounting used by vault methods.
+Custom Steer data adapters implement `getVaultMetadata(addresses, options)` as well as listing;
+custom vault constructors pass `context.metadata` to the base constructor.
+
 `amm` and `token` are optional. Token filters accept `address`, `symbol`, and `name`;
 symbol and token name use case-insensitive substring matches. Combined criteria must match
 the same token on either side. `name` refers to the underlying token, not the vault's name.
@@ -86,9 +122,10 @@ AMM selection uses the same typed protocol/version/deployment selectors and ambi
 on Base, plus Polygon Uniswap V3, SushiSwap V3, Retro V3, QuickSwap V3 and QuickSwap V4.
 Other AMM filters fail explicitly until their exact indexed beacon mappings are qualified.
 
-Listing costs zero RPC requests: two HTTP requests for the first page (snapshot and vaults),
-then one per continuation. Cursors retain filters and pin every page to the indexed block and
-subgraph deployment. If supplied again, filters must agree with the cursor. Results are indexed
+Unfiltered listing costs zero RPC requests: two HTTP requests for the first page (snapshot and vaults),
+then one per continuation. An older schema without poolKey adds one HTTP request for field negotiation.
+AMM filters with factory qualification also perform RPC checks at the indexed block. Cursors retain filters and pin every page to the indexed block and
+subgraph deployment. If supplied again, filters must agree with the cursor. Results contain indexed metadata for
 candidates, which may include implementations unsupported by `getVault()`; listing does not
 establish current onchain identity or add resolver support. Indexing, HTTP, and GraphQL errors propagate.
 
@@ -97,6 +134,23 @@ entry points honor client `indexers`/`http` configuration and accept per-request
 timeout, and cancellation overrides as the second argument. The existing `getVault()` API and
 its onchain identity checks remain the loading path.
 
+When catalog records are already available, supply them through the optional `VaultLoadOptions.metadata` field:
+
+```ts
+const vaults = await steer.getVaults(ChainId.Base, records.map((record) => record.id), {
+  blockNumber: 100000n,
+  metadata: records,
+});
+```
+
+This skips metadata subgraph requests while retaining all onchain registration, implementation,
+protocol and pool checks. Records are matched by address case-insensitively and copied before IO.
+Supply one complete record per unique requested address. Missing, duplicate, unrequested or malformed
+records fail without a metadata fetch. Results preserve requested order and duplicate addresses.
+Omit `metadata` to retain the existing subgraph lookup. The same options work on `getVault`, typed
+vault getters and the connected-network loading methods. Metadata remains descriptive and is never
+forwarded to viem/RPC or used to establish verified identity. Snapshot/accounting options are unchanged.
+
 `getVaults(chainId, addresses, options)` returns the same resolved vault objects as `getVault()`
 in input order, including duplicate inputs. Base V3/Integral resolution uses a bulk Solidity reader:
 **two RPC requests per page of at most 64 vaults** at a pinned block. Latest reads add one shared
@@ -500,6 +554,9 @@ shared internally; no snapshot is preloaded or passed through discovery. Each op
 the RPC chain, with no cross-operation identity cache or additional consumer options.
 
 Quotes read pool identity, the token pair and fee, verify factory registration, and call QuoterV2.
+V3 and Aerodrome Slipstream quotes reject results at either default price boundary because
+QuoterV2 does not establish the consumed input there. Requests that cannot establish full input
+consumption fail explicitly.
 They don't load token decimals, balances, ticks, or liquidity. Discovering a pool and then quoting
 at its block uses 9 RPC calls in total. Counts exclude retries and provider-specific transport
 behavior.

package/dist/index.cjs

@@ -2063,6 +2063,7 @@ var AerodromeSlipstreamAdapter = class extends AmmAdapter {
 			blockNumber: context.blockNumber,
 			...captured.account ? { account: captured.account } : {}
 		});
+		if (result[1] <= sqrtRatioAtTick(-887272) + 1n || result[1] >= sqrtRatioAtTick(887272) - 1n) throw new Error("Slipstream quote reached the price limit; full input consumption is not established");
 		return Object.freeze({
 			amountIn: input.amountIn,
 			amountOut: result[0]
@@ -2103,6 +2104,9 @@ var SteerDataAdapter = class extends DataAdapter {
 	async listUserVaults(_request, _options) {
 		throw new Error("User vault discovery is not configured for this data adapter");
 	}
+	async getVaultMetadata(_addresses, _options) {
+		throw new Error("Vault metadata is not configured for this data adapter");
+	}
 };
 //#endregion
 //#region src/data/subgraph.ts
@@ -7743,6 +7747,7 @@ var RpcUniswapV3Adapter = class RpcUniswapV3Adapter extends UniswapV3Adapter {
 			fee: pool.fee,
 			sqrtPriceLimitX96: 0n
 		}]);
+		if (result[1] <= sqrtRatioAtTick(-887272) + 1n || result[1] >= sqrtRatioAtTick(887272) - 1n) throw new Error("V3 quote reached the price limit; full input consumption is not established");
 		return {
 			amountIn: request.amountIn,
 			amountOut: result[0]
@@ -11399,6 +11404,50 @@ var DeploymentRegistry = class {
 	}
 };
 //#endregion
+//#region src/vault/metadata.ts
+function nullableString(value) {
+	if (value === null || typeof value === "string") return value;
+	throw new Error("Malformed vault metadata string");
+}
+/** Validate and detach indexed data, preserving nulls and optional pool keys. */
+function vaultMetadata(value) {
+	const row = record(value);
+	if (typeof row.beaconName !== "string" || !row.beaconName || typeof row.createdAt !== "string" || !/^\d+$/.test(row.createdAt)) throw new Error("Malformed vault metadata identity");
+	const decimals = nullableString(row.decimals);
+	if (decimals !== null && !/^\d+$/.test(decimals)) throw new Error("Malformed vault metadata decimals");
+	const strategy = row.strategyToken === null ? null : record(row.strategyToken);
+	if (strategy !== null && (typeof strategy.id !== "string" || !strategy.id)) throw new Error("Malformed vault strategy token");
+	return Object.freeze({
+		id: indexedAddress(row.id),
+		name: nullableString(row.name),
+		symbol: nullableString(row.symbol),
+		decimals,
+		beaconName: row.beaconName,
+		createdAt: row.createdAt,
+		state: nullableString(row.state),
+		pool: row.pool === null ? null : indexedAddress(row.pool, true),
+		...row.poolKey === void 0 ? {} : { poolKey: nullableString(row.poolKey) },
+		token0: row.token0 === null ? null : indexedAddress(row.token0, true),
+		token1: row.token1 === null ? null : indexedAddress(row.token1, true),
+		payloadIpfs: nullableString(row.payloadIpfs),
+		strategyToken: strategy === null ? null : Object.freeze({ id: String(strategy.id) })
+	});
+}
+/** Validate and detach caller-owned metadata before any asynchronous resolution. */
+function captureVaultMetadata(addresses, values) {
+	if (!Array.isArray(values)) throw new Error("Supplied vault metadata must be an array");
+	const requested = new Set(addresses.map((address) => address.toLowerCase()));
+	const records = /* @__PURE__ */ new Map();
+	for (const value of values) {
+		const metadata = vaultMetadata(value);
+		if (!requested.has(metadata.id)) throw new Error(`Supplied vault metadata contains an unrequested address: ${metadata.id}`);
+		if (records.has(metadata.id)) throw new Error(`Supplied vault metadata contains a duplicate address: ${metadata.id}`);
+		records.set(metadata.id, metadata);
+	}
+	for (const address of requested) if (!records.has(address)) throw new Error(`Supplied vault metadata is missing address: ${address}`);
+	return records;
+}
+//#endregion
 //#region src/vault/resolver-types.ts
 let ProtocolContractRole = /* @__PURE__ */ function(ProtocolContractRole) {
 	ProtocolContractRole["AmmFactory"] = "amm-factory";
@@ -11786,18 +11835,25 @@ async function filterVaultsByFactory(context, vaults, factory, blockNumber) {
 //#endregion
 //#region src/vault/data-adapter.ts
 const nonShareBeacons = ["ScheduledJobs", "DynamicJobs"];
-const vaultsQuery = `query Vaults($first: Int!, $where: Vault_filter!, $block: Int!) {
+const metadataFields = `id name symbol decimals beaconName createdAt state pool poolKey token0 token1 payloadIpfs strategyToken { id }`;
+const metadataQuery = `query VaultMetadata($ids: [ID!]!, $first: Int!) {
+  vaults(first: $first, orderBy: id, orderDirection: asc, where: {id_in: $ids}) { ${metadataFields} }
+  _meta { ${metaFields} }
+}`;
+const vaultsQuery = (balances) => `query Vaults($first: Int!, $where: Vault_filter!, $block: Int!) {
   vaults(first: $first, orderBy: id, orderDirection: asc, where: $where, block: {number: $block}) {
-    id beaconName token0 token1 token0Symbol token1Symbol token0Name token1Name
+    ${balances ? "id beaconName token0 token1" : metadataFields}
+    token0Symbol token1Symbol token0Name token1Name
   }
   _meta(block: {number: $block}) { ${metaFields} }
 }`;
 function matchesToken(row, token, side) {
-	const address = indexedAddress(row[`token${side}`]);
+	if (row[`token${side}`] === null) return false;
+	const address = indexedAddress(row[`token${side}`], true);
 	const symbol = row[`token${side}Symbol`];
 	const name = row[`token${side}Name`];
-	if (typeof symbol !== "string" || typeof name !== "string") throw new Error("Malformed vault token metadata");
-	return (!token.address || token.address === address) && (!token.symbol || symbol.toLowerCase().includes(token.symbol)) && (!token.name || name.toLowerCase().includes(token.name));
+	if (symbol !== null && typeof symbol !== "string" || name !== null && typeof name !== "string") throw new Error("Malformed vault token metadata");
+	return (!token.address || token.address === address) && (!token.symbol || typeof symbol === "string" && symbol.toLowerCase().includes(token.symbol)) && (!token.name || typeof name === "string" && name.toLowerCase().includes(token.name));
 }
 function vaultFilter(token, after, beacons, balances) {
 	const base = {
@@ -11886,7 +11942,7 @@ var CatalogSteerDataAdapter = class extends SteerDataAdapter {
 			...cursor === void 0 ? {} : { cursor },
 			limit: input.limit ?? 1e3
 		}, options, true);
-		const items = await scanVaultBalances(this.#context, page.items, input.account, page.indexedBlock);
+		const items = await scanVaultBalances(this.#context, page.items.map((row) => indexedAddress(row.id)), input.account, page.indexedBlock);
 		return Object.freeze({
 			items,
 			indexedBlock: page.indexedBlock,
@@ -11897,9 +11953,44 @@ var CatalogSteerDataAdapter = class extends SteerDataAdapter {
 			}) } : {}
 		});
 	}
+	async #metadataQuery(query, variables, options) {
+		try {
+			return await this.#query(query, variables, options);
+		} catch (error) {
+			const errors = error instanceof Error ? error.cause : void 0;
+			if (!query.includes("poolKey") || !Array.isArray(errors) || !errors.length || !errors.every((value) => typeof value?.message === "string" && /^Cannot query field "poolKey" on type "Vault"\.(?: Did you mean .*\?)?$/.test(value.message))) throw error;
+			return this.#query(query.replace(/\bpoolKey\b/g, ""), variables, options);
+		}
+	}
+	async getVaultMetadata(addresses, options = {}) {
+		const ids = addresses.map((address) => indexedAddress(address));
+		const unique = [...new Set(ids)];
+		if (!unique.length) return Object.freeze([]);
+		if (unique.length > 1e3) throw new Error("Vault metadata lookup supports at most 1000 addresses");
+		const data = await this.#metadataQuery(metadataQuery, {
+			ids: unique,
+			first: unique.length
+		}, options);
+		snapshot(data);
+		if (!Array.isArray(data.vaults) || data.vaults.length > unique.length) throw new Error("Malformed vault metadata response");
+		const records = /* @__PURE__ */ new Map();
+		for (const value of data.vaults) {
+			const metadata = vaultMetadata(value);
+			if (!unique.includes(metadata.id) || records.has(metadata.id)) throw new Error("Unexpected or duplicate vault metadata");
+			records.set(metadata.id, metadata);
+		}
+		return Object.freeze(ids.map((id) => {
+			const metadata = records.get(id);
+			if (!metadata) throw new Error("Vault metadata is not indexed");
+			return metadata;
+		}));
+	}
 	async listVaults(request = {}, options = {}) {
-		const { indexedBlock: _, ...page } = await this.#listVaults(request, options, false);
-		return Object.freeze(page);
+		const { indexedBlock: _, items, ...page } = await this.#listVaults(request, options, false);
+		return Object.freeze({
+			...page,
+			items: Object.freeze(items.map(vaultMetadata))
+		});
 	}
 	async #listVaults(request = {}, options = {}, balances = false) {
 		const limit = request.limit ?? 100;
@@ -11932,7 +12023,7 @@ var CatalogSteerDataAdapter = class extends SteerDataAdapter {
 			} });
 		} else expected = snapshot(await this.#query(snapshotQuery, {}, options));
 		const beacons = amm ? this.#beacons.get(amm) : void 0;
-		const data = await this.#query(vaultsQuery, {
+		const data = await this.#metadataQuery(vaultsQuery(balances), {
 			first: limit,
 			where: vaultFilter(token, after, beacons, balances),
 			block: expected.block
@@ -11949,13 +12040,15 @@ var CatalogSteerDataAdapter = class extends SteerDataAdapter {
 			if (balances && (typeof row.beaconName !== "string" || nonShareBeacons.includes(row.beaconName))) throw new Error("User vault listing returned a non-share deployment");
 			if (beacons && (typeof row.beaconName !== "string" || !beacons.includes(row.beaconName))) throw new Error("Vault listing does not match the AMM beacon mapping");
 			if (token && !matchesToken(row, token, 0) && !matchesToken(row, token, 1)) throw new Error("Vault listing does not match the token filter");
-			return address;
+			if (!balances) vaultMetadata(row);
+			return row;
 		});
-		const last = items.at(-1);
+		const last = items.at(-1)?.id;
 		const factory = amm ? this.#factories.get(amm) : void 0;
-		const filtered = factory ? await filterVaultsByFactory(this.#context, items, factory, BigInt(expected.block)) : items;
+		const filtered = factory ? await filterVaultsByFactory(this.#context, items.map((row) => indexedAddress(row.id)), factory, BigInt(expected.block)) : items.map((row) => indexedAddress(row.id));
+		const included = new Set(filtered);
 		return Object.freeze({
-			items: Object.freeze(filtered),
+			items: Object.freeze(items.filter((row) => included.has(indexedAddress(row.id)))),
 			indexedBlock: BigInt(expected.block),
 			...items.length === limit && last ? { nextCursor: JSON.stringify({
 				version: 1,
@@ -13759,10 +13852,13 @@ var SteerVault = class {
 	chain;
 	steer;
 	underlying;
-	constructor(address, chain, steer, underlying) {
+	metadata;
+	constructor(address, chain, steer, underlying, metadata) {
 		this.address = address;
 		this.chain = chain;
 		this.steer = steer;
+		this.metadata = vaultMetadata(metadata);
+		if (this.metadata.id !== address.toLowerCase()) throw new Error("Vault metadata belongs to another vault");
 		this.underlying = Object.freeze([...underlying]);
 	}
 };
@@ -14424,7 +14520,7 @@ var AerodromeVault = class extends LiquidityVault {
 	#positionManager;
 	/** @internal */
 	constructor(context, identity) {
-		super(context.address, context.steer.context, context.steer, context.underlying);
+		super(context.address, context.steer.context, context.steer, context.underlying, context.metadata);
 		const underlying = context.underlying[0];
 		if (context.underlying.length !== 1 || underlying?.kind !== "liquidity" || !(underlying.amm instanceof AerodromeSlipstreamAdapter) || typeof underlying.pool !== "string") identityMismatch("Expected one Aerodrome vault pool");
 		requireAddress(underlying.pool);
@@ -14528,6 +14624,7 @@ async function readAerodromeBulkSnapshot(vault, data, rpc, beacon) {
 		steer: vault.steer,
 		address: vault.address,
 		underlying: vault.underlying,
+		metadata: vault.metadata,
 		blockNumber: rpc.blockNumber
 	}, identity, {
 		raw: decodeAerodromeSnapshot(data),
@@ -15567,6 +15664,7 @@ async function readIntegralBulkSnapshot(vault, data, rpc) {
 		steer: vault.steer,
 		address: vault.address,
 		underlying: vault.underlying,
+		metadata: vault.metadata,
 		blockNumber: rpc.blockNumber
 	}, {
 		raw,
@@ -15580,7 +15678,7 @@ var AlgebraIntegralVault = class extends LiquidityVault {
 	amm;
 	pool;
 	constructor(context) {
-		super(context.address, context.steer.context, context.steer, context.underlying);
+		super(context.address, context.steer.context, context.steer, context.underlying, context.metadata);
 		const underlying = context.underlying[0];
 		if (context.underlying.length !== 1 || underlying?.kind !== "liquidity" || !isAlgebraIntegralAdapter(underlying.amm) || typeof underlying.pool !== "string") identityMismatch("Expected one Integral vault pool");
 		requireAddress(underlying.pool);
@@ -17179,6 +17277,7 @@ async function readV3BulkSnapshot(vault, data, rpc) {
 		steer: vault.steer,
 		address: vault.address,
 		underlying: vault.underlying,
+		metadata: vault.metadata,
 		blockNumber: rpc.blockNumber
 	}, {
 		raw,
@@ -17192,7 +17291,7 @@ var UniswapV3Vault = class extends LiquidityVault {
 	amm;
 	pool;
 	constructor(context) {
-		super(context.address, context.steer.context, context.steer, context.underlying);
+		super(context.address, context.steer.context, context.steer, context.underlying, context.metadata);
 		const underlying = context.underlying[0];
 		if (context.underlying.length !== 1 || underlying?.kind !== "liquidity" || !isUniswapV3Adapter(underlying.amm) || typeof underlying.pool !== "string") identityMismatch("Expected one V3 vault pool");
 		requireAddress(underlying.pool);
@@ -18825,7 +18924,7 @@ var UniswapV4Vault = class extends LiquidityVault {
 	amm;
 	pool;
 	constructor(context) {
-		super(context.address, context.steer.context, context.steer, context.underlying);
+		super(context.address, context.steer.context, context.steer, context.underlying, context.metadata);
 		const underlying = context.underlying[0];
 		if (context.underlying.length !== 1 || underlying?.kind !== "liquidity" || !(underlying.amm instanceof UniswapV4Adapter) || !isLiquidityPool(underlying.pool) || typeof underlying.pool === "string") identityMismatch("Expected one standalone V4 vault pool");
 		this.amm = underlying.amm;
@@ -20205,6 +20304,7 @@ async function readLegacyBulkSnapshot(vault, data, rpc, beacon) {
 		steer: vault.steer,
 		address: vault.address,
 		underlying: vault.underlying,
+		metadata: vault.metadata,
 		blockNumber: rpc.blockNumber
 	}, {
 		raw,
@@ -20218,7 +20318,7 @@ var AlgebraLegacyVault = class extends LiquidityVault {
 	amm;
 	pool;
 	constructor(context) {
-		super(context.address, context.steer.context, context.steer, context.underlying);
+		super(context.address, context.steer.context, context.steer, context.underlying, context.metadata);
 		const underlying = context.underlying[0];
 		if (context.underlying.length !== 1 || underlying?.kind !== "liquidity" || !isAlgebraLegacyAdapter(underlying.amm) || typeof underlying.pool !== "string") identityMismatch("Expected one Legacy vault pool");
 		requireAddress(underlying.pool);
@@ -20825,7 +20925,7 @@ var VaultResolver = class {
 		if (!vault) throw new Error("Missing resolved vault");
 		return vault;
 	}
-	async #createVault(context, identity, verified) {
+	async #createVault(context, identity, loadMetadata, verified) {
 		const { steer, address } = context;
 		if (!identity) throw new VaultResolutionError("not-registered", "Vault is not registered with Steer");
 		if (identity.chainId !== steer.context.chainId || addressKey(identity.vaultAddress) !== addressKey(address) || addressKey(identity.registryAddress) !== addressKey(steer.contracts.VaultRegistry.address) || addressKey(identity.beaconAddress) !== addressKey(identity.proxyBeaconAddress)) throw new VaultResolutionError("identity-mismatch", "Vault identity does not match the request");
@@ -20837,9 +20937,12 @@ var VaultResolver = class {
 			lending: /* @__PURE__ */ new Map()
 		};
 		const resolvedUnderlying = Object.freeze(underlying.map((position) => this.#resolveUnderlying(position, adapters)));
+		const metadata = await loadMetadata();
+		if (metadata.id.toLowerCase() !== address.toLowerCase()) throw new Error("Vault metadata belongs to another vault");
 		const resolved = Object.freeze({
 			...context,
-			underlying: resolvedUnderlying
+			underlying: resolvedUnderlying,
+			metadata
 		});
 		const vault = binding.createVault(resolved);
 		this.#validateVault(vault, binding, resolved);
@@ -20859,21 +20962,39 @@ var VaultResolver = class {
 			steer: vault.steer,
 			address: vault.address,
 			underlying: vault.underlying,
+			metadata: vault.metadata,
 			blockNumber
 		});
 		if (snapshot.blockNumber !== blockNumber || !vault.underlying.some((position) => position.kind === "liquidity" && sameLiquidityPool(position.pool, snapshot.pool))) throw new Error("Vault returned another accounting snapshot");
 		return readValidatedVaultSnapshot(vault, snapshot, vault.steer.context);
 	}
+	#metadata(steer, addresses, supplied) {
+		let pending;
+		return async (address) => {
+			if (supplied) {
+				const metadata = supplied.get(address.toLowerCase());
+				if (!metadata) throw new Error(`Supplied vault metadata is missing address: ${address}`);
+				return metadata;
+			}
+			pending ??= steer.dataAdapter.getVaultMetadata(addresses);
+			const metadata = (await pending).find((record) => record.id.toLowerCase() === address.toLowerCase());
+			if (!metadata) throw new Error("Vault metadata is not indexed");
+			return metadata;
+		};
+	}
 	/** Bounded bulk identity pages at one block; compatibility uses four active loads. */
 	async resolveMany(steer, addresses, options) {
 		const inputs = [...addresses];
 		for (const address of inputs) addressKey(address);
+		const supplied = options?.metadata;
+		const metadata = supplied === void 0 ? void 0 : captureVaultMetadata(inputs, supplied);
 		if (!inputs.length) return Object.freeze([]);
 		const blockNumber = await this.#blockNumber(steer, options);
 		const result = [];
 		let bulkSupported = !!this.#reader.readMany;
 		for (let start = 0; start < inputs.length; start += 64) {
 			const batch = inputs.slice(start, start + 64);
+			const loadMetadata = this.#metadata(steer, batch, metadata);
 			const contexts = batch.map((address) => Object.freeze({
 				steer,
 				address,
@@ -20885,13 +21006,13 @@ var VaultResolver = class {
 				for (const [i, context] of contexts.entries()) {
 					const read = reads[i];
 					if (!read) throw new VaultResolutionError("identity-mismatch", "Missing bulk vault identity");
-					result.push((await this.#createVault(context, read.identity, read)).vault);
+					result.push((await this.#createVault(context, read.identity, () => loadMetadata(context.address), read)).vault);
 				}
 			} else {
 				bulkSupported = false;
 				for (let i = 0; i < batch.length; i += 4) result.push(...await Promise.all(contexts.slice(i, i + 4).map(async (context) => {
 					const identity = await this.#reader.readIdentity(context);
-					return (await this.#createVault(context, identity)).vault;
+					return (await this.#createVault(context, identity, () => loadMetadata(context.address))).vault;
 				})));
 			}
 		}
@@ -20907,6 +21028,7 @@ var VaultResolver = class {
 		let bulkSupported = !!this.#reader.readSnapshots;
 		for (let start = 0; start < inputs.length; start += 16) {
 			const batch = inputs.slice(start, start + 16);
+			const loadMetadata = this.#metadata(steer, batch);
 			const contexts = batch.map((address) => Object.freeze({
 				steer,
 				address,
@@ -20918,7 +21040,7 @@ var VaultResolver = class {
 				for (const [i, context] of contexts.entries()) {
 					const read = reads[i];
 					if (!read) throw new Error("Missing bulk vault snapshot");
-					const { vault } = await this.#createVault(context, read.identity, read);
+					const { vault } = await this.#createVault(context, read.identity, () => loadMetadata(context.address), read);
 					if (vault.kind !== "liquidity") throw new VaultResolutionError("invalid-vault", "Vault does not support liquidity snapshots");
 					result.push(await read.readSnapshot(vault));
 				}
@@ -20931,7 +21053,7 @@ var VaultResolver = class {
 						blockNumber
 					});
 					const identity = await this.#reader.readIdentity(context);
-					const { vault, binding, context: resolved } = await this.#createVault(context, identity);
+					const { vault, binding, context: resolved } = await this.#createVault(context, identity, () => loadMetadata(context.address));
 					if (vault.kind !== "liquidity") throw new VaultResolutionError("invalid-vault", "Vault does not support liquidity snapshots");
 					if (!binding.readSnapshot) throw new VaultResolutionError("not-configured", "No verified snapshot reader configured for vault implementation");
 					const snapshot = await binding.readSnapshot(resolved);
@@ -21029,7 +21151,10 @@ var SteerNetwork = class {
 		return this.#vaultResolver().resolve(this, address, options);
 	}
 	async getVaults(addresses, options) {
-		if (!addresses.length) return Object.freeze([]);
+		if (!addresses.length) {
+			if (options?.metadata !== void 0) captureVaultMetadata(addresses, options.metadata);
+			return Object.freeze([]);
+		}
 		return this.#vaultResolver().resolveMany(this, addresses, options);
 	}
 	getVaultSnapshots(addresses, options) {