@steerprotocol/sdk 4.0.0-next.10 → 4.0.0-next.11

package/README.md

@@ -50,6 +50,76 @@ Base V3/Integral and Polygon V3/Legacy/Integral vault reads are implemented belo
 implementations. The Steer catalog supplies network metadata and indexed vault discovery. Networks without resolver bindings report `NotConfigured` when loading a vault. Consumers don't assemble a chain or pass a `steer: steerBase` setting.
 SDK integration code owns Steer's per-network contracts and data adapters.
 
+## App and data-connector loader dependencies
+
+The SDK installs exact runtime dependencies `@steerprotocol/app-loader@3.2.6` and
+`@steerprotocol/data-connector-loader@4.1.0`. Their APIs remain separate from `SteerClient`;
+they are not re-exported from the SDK root.
+
+Both loader packages support ESM imports. The published connector loader's CommonJS entry
+fails because its CommonJS `.js` files are inside a package marked `type: module`; use its
+ESM entry. The app loader supports both ESM and CommonJS. The connector loader declares a
+stable 3.x SDK dependency (3.8.1 in this lockfile), used for its execution-context types;
+its emitted JavaScript does not import SDK readers. The SDK's portable root does not import
+either loader.
+
+## Vault execution context
+
+Liquidity vaults expose strategy inputs through the existing vault object:
+
+```ts
+const blockNumber = 12345678n; // Caller-selected operation block.
+const vault = await steer.getLiquidityVault(chainId, vaultAddress, { blockNumber });
+const context = await vault.getExecutionContext({
+  blockNumber,
+  epochTimestamp: 1793577600n, // Explicit Unix seconds, independent of the wall clock.
+});
+```
+
+The immutable, JSON-safe `VaultExecutionContext` contains vault/beacon/AMM identity,
+address-based or V4 key/ID/manager pool identity, current tick/spacing, configured strategy
+ranges with relative weights, original contract totals as decimal strings, and indexed
+last-execution/elapsed seconds. It has no `provenance` field. V4 never fabricates a pool address;
+unused pool identity fields are `null`. Configured ranges are independent of active NFT inventory.
+
+Each call revalidates the native vault binding and dispatches registered vault/AMM overrides.
+All onchain reads use the explicit block. `totalAmount0`/`totalAmount1` come from the original
+vault's `getTotalAmounts()` without poke, matching the prior execution-context semantics;
+they are not aliases for the fee-adjusted `getSnapshot().total` accounting fields.
+
+The Steer data adapter queries the latest indexed `vaultSnapshot` at that block, bounded by
+the earlier of the block timestamp and execution epoch. Its timestamp is the history source,
+not proof that the indexer has captured every execution. An empty history returns `null`
+for both history fields. Unsupported history adapters, unavailable blocks, indexing errors,
+malformed responses and RPC/HTTP failures throw instead of fabricating zero elapsed time.
+Block numbers must fit the indexer's nonnegative GraphQL Int range. The optional second
+argument accepts the existing per-request HTTP overrides for the history query.
+
+Custom Steer data adapters can implement `getLastVaultExecution(request, options)` to supply
+history without a subgraph. The request contains `vaultAddress`, `blockNumber` and the bounded
+`timestamp`; return a nonnegative bigint no later than that timestamp, or `null`.
+
+The installed connector loader's runtime mapper accepts this provenance-free shape. Its
+published TypeScript declarations still require the legacy SDK's context, including legacy
+protocol types and `provenance`. Updating that upstream type contract is required for direct
+typed `executeWithContext` integration; this SDK does not invent provenance or cast away that
+mismatch. The offline test verifies runtime mapping, not a full WASM strategy execution.
+
+Read-only live verification on November 2, 2026 passed 13 fixtures across six chains:
+Base Uniswap V3, Base QuickSwap Integral, all three Base Aerodrome generations, Polygon
+QuickSwap Legacy, Arbitrum Camelot, Avalanche Blackhole, BSC Pancake V3, and ERC20/native
+standalone V4 vaults on both BSC and Robinhood. Each context was compared with independent
+same-block original contract totals, configured ranges, registry/beacon identity, pool
+tick/spacing and identity, and a separate indexed history query. This qualifies those
+fixtures, not every deployment or full WASM strategy execution. Blackhole execution pool
+reads retain the custom deployer from the verified vault layout.
+
+Reproduce with the explicit RPC/indexer settings in `.env.integration`:
+
+```sh
+npm run test:integration -- tests/integration/vault/execution-context.multichain.test.ts --reporter=verbose
+```
+
 ## Vault discovery
 
 List indexed vault metadata, then load a result through the identity-verified resolver:

package/dist/index.cjs

@@ -2303,6 +2303,10 @@ var DataAdapter = class {
 var PoolDataAdapter = class extends DataAdapter {};
 var LendingDataAdapter = class extends DataAdapter {};
 var SteerDataAdapter = class extends DataAdapter {
+	/** Latest indexed execution through the requested block and timestamp, or null if absent. */
+	async getLastVaultExecution(_request, _options) {
+		throw new Error("Vault execution history is not configured for this data adapter");
+	}
 	async listUserVaults(_request, _options) {
 		throw new Error("User vault discovery is not configured for this data adapter");
 	}
@@ -12778,6 +12782,29 @@ var CatalogSteerDataAdapter = class extends SteerDataAdapter {
 	#factories = /* @__PURE__ */ new Map();
 	#identity;
 	#context;
+	async getLastVaultExecution(request, options) {
+		const vaultAddress = indexedAddress(request.vaultAddress);
+		const { blockNumber, timestamp } = request;
+		if (typeof blockNumber !== "bigint" || blockNumber < 0n || blockNumber > 2147483647n) throw new Error("Execution history block must fit a nonnegative GraphQL Int");
+		if (typeof timestamp !== "bigint" || timestamp < 0n) throw new Error("Execution history timestamp must be nonnegative");
+		const data = await this.#query(`query VaultExecutionHistory($vault: String!, $timestamp: BigInt!, $block: Int!) {
+        vaultSnapshots(first: 1, orderBy: timestamp, orderDirection: desc,
+          block: {number: $block}, where: {vaultAddress: $vault, timestamp_lte: $timestamp}) {
+          timestamp
+        }
+        _meta(block: {number: $block}) { ${metaFields} }
+      }`, {
+			vault: vaultAddress,
+			timestamp: timestamp.toString(),
+			block: Number(blockNumber)
+		}, options);
+		if (BigInt(snapshot$1(data).block) !== blockNumber) throw new Error("Execution history returned another block");
+		if (!Array.isArray(data.vaultSnapshots) || data.vaultSnapshots.length > 1) throw new Error("Malformed vault execution history");
+		if (data.vaultSnapshots.length === 0) return null;
+		const value = record(data.vaultSnapshots[0]).timestamp;
+		if (typeof value !== "string" || !/^\d+$/.test(value) || BigInt(value) > timestamp) throw new Error("Invalid vault execution timestamp");
+		return BigInt(value);
+	}
 	constructor(definition, context, mappings) {
 		super(definition.dataAdapter);
 		if (definition.dataAdapter.kind !== "subgraph") throw new Error("Steer vault listing requires a subgraph endpoint");
@@ -13428,7 +13455,7 @@ function captureAsset$1({ asset, amount }, allowNative = false) {
 		amount
 	});
 }
-function captureRequest(input, allowNative) {
+function captureRequest$1(input, allowNative) {
 	const { account, receiver } = input;
 	requireAddress(account);
 	requireAddress(receiver);
@@ -13486,7 +13513,7 @@ function buildPreview(snapshot, state, desired0, desired1, minimumInitialShares,
 	});
 }
 async function previewLiquidityDeposit(vault, input, minimumInitialShares, options, accounting = defaultAccounting) {
-	const request = captureRequest(input, accounting.allowNative);
+	const request = captureRequest$1(input, accounting.allowNative);
 	const { snapshot, state, desired0, desired1 } = await readDepositInput(vault, request.assets, options, void 0, accounting, request.receiver);
 	return buildPreview(snapshot, state, desired0, desired1, minimumInitialShares, accounting.singleSidedRounding);
 }
@@ -13508,7 +13535,7 @@ async function quoteLiquidityDeposit(vault, input, options, accounting = default
 	});
 }
 async function prepareLiquidityDeposit(vault, input, minimumInitialShares, options, accounting = defaultAccounting) {
-	const request = captureRequest(input, accounting.allowNative);
+	const request = captureRequest$1(input, accounting.allowNative);
 	const slippageBps = input.slippageBps;
 	if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > 1e4) throw new Error("Deposit slippageBps must be an integer from 0 through 10000");
 	const { snapshot, state, desired0, desired1 } = await readDepositInput(vault, request.assets, options, request.account, accounting, request.receiver);
@@ -14103,6 +14130,10 @@ var SteerVault = class {
 };
 var LiquidityVault = class extends SteerVault {
 	kind = "liquidity";
+	/** Read strategy inputs at an explicit block, with timestamp-bounded indexed execution history. */
+	getExecutionContext(request, options) {
+		return this.steer.readVaultExecutionContext(this, request, options);
+	}
 	/** Simulates the original withdrawal as account at one verified block. Never submits. */
 	previewWithdraw(request, options) {
 		return previewLiquidityWithdraw(this, request, options);
@@ -25385,6 +25416,133 @@ function createIndexerRequest(config, defaults) {
 	});
 }
 //#endregion
+//#region src/vault/adapters/blackhole/execution.ts
+/** Custom-pool routing comes from the qualified vault layout, never an address-only guess. */
+async function readBlackholeExecutionPool(vault, blockNumber) {
+	const { target } = await readBlackholePool({
+		steer: vault.steer,
+		address: vault.address,
+		blockNumber
+	});
+	if (!sameAddress(target.address, vault.pool)) throw new Error("Blackhole vault pool changed");
+	const pool = await vault.amm.getPool(Object.freeze({ ...target }), Object.freeze({ blockNumber }));
+	if (!sameAddress(pool.deployer, target.deployer)) throw new Error("Blackhole execution pool deployer does not match the vault");
+	return pool;
+}
+//#endregion
+//#region src/vault/execution-pool.ts
+function validatePoolState(block, tick, spacing, expected) {
+	if (block !== expected || !Number.isInteger(tick) || tick < -887272 || tick > 887272 || !Number.isInteger(spacing) || spacing <= 0 || spacing > 8388607) throw new Error("Invalid execution pool state or block");
+}
+/** Dispatch actual registered adapters, then check the result against the verified vault pool. */
+async function readExecutionPool(vault, snapshot) {
+	const amm = vault.amm;
+	const options = Object.freeze({ blockNumber: snapshot.blockNumber });
+	if (amm.context.chainId !== vault.chain.chainId || amm.context.transport !== vault.chain.transport) throw new Error("Execution AMM belongs to another chain or transport");
+	if (typeof snapshot.pool !== "string") {
+		if (!isUniswapV4Adapter(amm)) throw new Error("Execution pool requires a V4 adapter");
+		const pool = await amm.getPool(snapshot.pool.key, options);
+		validatePoolState(pool.blockNumber, pool.tick, pool.key.tickSpacing, snapshot.blockNumber);
+		if (!sameLiquidityPool(snapshot.pool, {
+			poolId: pool.poolId,
+			poolManager: pool.poolManager,
+			key: pool.key
+		}) || !sameAddress(pool.poolManager, amm.contracts.poolManager.address) || !sameAddress(pool.key.currency0, snapshot.token0) || !sameAddress(pool.key.currency1, snapshot.token1)) throw new Error("Execution pool identity does not match the vault");
+		return Object.freeze({
+			poolFamily: "uniswap-v4",
+			poolAddress: null,
+			factoryAddress: null,
+			poolId: pool.poolId,
+			poolManagerAddress: pool.poolManager,
+			poolKey: Object.freeze({ ...pool.key }),
+			currentTick: pool.tick,
+			tickSpacing: pool.key.tickSpacing
+		});
+	}
+	if (!isUniswapV3Adapter(amm) && !isAlgebraLegacyAdapter(amm) && !isAlgebraIntegralAdapter(amm) && !(amm instanceof AerodromeSlipstreamAdapter)) throw new Error("Unsupported execution pool family");
+	const factory = amm.contracts.factory.address;
+	const pool = vault instanceof BlackholeVault ? await readBlackholeExecutionPool(vault, snapshot.blockNumber) : await amm.getPool(snapshot.pool, options);
+	validatePoolState(pool.blockNumber, pool.tick, pool.tickSpacing, snapshot.blockNumber);
+	if (!sameAddress(pool.address, snapshot.pool) || !sameAddress(pool.factory, factory) || !sameAddress(pool.token0, snapshot.token0) || !sameAddress(pool.token1, snapshot.token1)) throw new Error("Execution pool identity does not match the vault");
+	const poolFamily = isUniswapV3Adapter(amm) ? "uniswap-v3-compatible" : isAlgebraLegacyAdapter(amm) ? amm instanceof AlgebraDirectionalAdapter ? "algebra-directional" : "algebra" : isAlgebraIntegralAdapter(amm) ? "algebra-integral" : "aerodrome-cl";
+	return Object.freeze({
+		poolFamily,
+		poolAddress: pool.address,
+		factoryAddress: pool.factory,
+		poolId: null,
+		poolManagerAddress: null,
+		poolKey: null,
+		currentTick: pool.tick,
+		tickSpacing: pool.tickSpacing
+	});
+}
+//#endregion
+//#region src/vault/execution-context.ts
+function captureRequest(request) {
+	const { blockNumber, epochTimestamp } = request;
+	if (typeof blockNumber !== "bigint" || blockNumber < 0n || blockNumber > 2147483647n) throw new Error("Execution block must fit a nonnegative GraphQL Int");
+	if (typeof epochTimestamp !== "bigint" || epochTimestamp < 0n) throw new Error("Execution timestamp must be nonnegative Unix seconds");
+	return Object.freeze({
+		blockNumber,
+		epochTimestamp
+	});
+}
+function executionPositions(snapshot) {
+	const seen = /* @__PURE__ */ new Set();
+	return Object.freeze((snapshot.configuredPositions ?? snapshot.positions).map(({ lowerTick, upperTick, relativeWeight }) => {
+		const key = `${lowerTick}:${upperTick}`;
+		if (!Number.isInteger(lowerTick) || !Number.isInteger(upperTick) || lowerTick < -887272 || upperTick > 887272 || lowerTick >= upperTick || !Number.isInteger(relativeWeight) || relativeWeight < 0 || relativeWeight > 65535 || seen.has(key)) throw new Error("Invalid configured execution ranges");
+		seen.add(key);
+		return Object.freeze({
+			lowerTick,
+			upperTick,
+			relativeWeight
+		});
+	}));
+}
+/** Keep original contract totals separate from the SDK's net-fee accounting snapshot. */
+async function readLiquidityExecutionContext(vault, beaconAddress, input, options) {
+	const { blockNumber, epochTimestamp } = captureRequest(input);
+	const { address: vaultAddress, chain, steer, metadata, amm } = vault;
+	const beaconName = metadata.beaconName;
+	const protocol = amm.protocol;
+	const rpc = await vaultReadContext(chain, { blockNumber });
+	const client = rpcClient(rpc.transport);
+	const snapshot = await steer.readVaultSnapshot(vault, { blockNumber });
+	const positions = executionPositions(snapshot);
+	const pool = await readExecutionPool(vault, snapshot);
+	const totals = await client.readContract({
+		address: vaultAddress,
+		abi: depositAbi,
+		functionName: "getTotalAmounts",
+		blockNumber
+	});
+	const block = await client.getBlock({ blockNumber });
+	if (block.number !== blockNumber || typeof block.timestamp !== "bigint" || block.timestamp < 0n) throw new Error("Execution RPC returned an invalid block");
+	const timestamp = block.timestamp < epochTimestamp ? block.timestamp : epochTimestamp;
+	const lastExecution = await steer.dataAdapter.getLastVaultExecution({
+		vaultAddress,
+		blockNumber,
+		timestamp
+	}, options);
+	if (lastExecution !== null && (typeof lastExecution !== "bigint" || lastExecution < 0n || lastExecution > timestamp)) throw new Error("Invalid vault execution timestamp");
+	return Object.freeze({
+		chainId: rpc.chainId,
+		blockNumber: blockNumber.toString(),
+		epochTimestamp: epochTimestamp.toString(),
+		vaultAddress,
+		protocol,
+		beaconName,
+		beaconAddress,
+		...pool,
+		positions,
+		totalAmount0: totals[0].toString(),
+		totalAmount1: totals[1].toString(),
+		lastExecutionTimestamp: lastExecution?.toString() ?? null,
+		lastExecutionTimeSeconds: lastExecution === null ? null : (epochTimestamp - lastExecution).toString()
+	});
+}
+//#endregion
 //#region src/vault/resolver.ts
 function addressKey(address) {
 	if (!/^0x[0-9a-fA-F]{40}$/.test(address) || /^0x0{40}$/i.test(address)) throw new VaultResolutionError("identity-mismatch", "Invalid identity address");
@@ -25484,6 +25642,12 @@ var VaultResolver = class {
 		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);
 	}
+	/** @internal The native snapshot reader revalidates this binding at the requested block. */
+	executionContext(vault, request, options) {
+		const binding = this.#snapshotBindings.get(vault);
+		if (!binding?.readSnapshot) throw new Error("No verified execution reader configured for vault");
+		return readLiquidityExecutionContext(vault, binding.beaconAddress, request, options);
+	}
 	#snapshotImplementation(snapshot, binding, beaconName) {
 		const { implementation: _implementation, ...accounting } = snapshot;
 		return Object.freeze({
@@ -25761,6 +25925,11 @@ var SteerNetwork = class {
 		if (vault.steer !== this) throw new VaultResolutionError("identity-mismatch", "Vault belongs to another Steer deployment");
 		return this.#vaultResolver().snapshot(vault, options);
 	}
+	/** @internal Retain the resolved vault's exact binding and registered overrides. */
+	readVaultExecutionContext(vault, request, options) {
+		if (vault.steer !== this) throw new Error("Vault belongs to another Steer deployment");
+		return this.#vaultResolver().executionContext(vault, request, options);
+	}
 	#vaultResolver() {
 		if (!this.#resolver) throw new VaultResolutionError("not-configured", "No vault resolver configured for this Steer deployment");
 		return this.#resolver;