@steerprotocol/sdk 3.2.8 → 3.3.1

package/dist/index.cjs

@@ -19647,6 +19647,365 @@ var VaultWithdrawClient = class {
 	}
 };
 //#endregion
+//#region src/base/vault/execution-context.ts
+const VAULT_REGISTRY_ABI = (0, viem.parseAbi)(["function getVaultDetails(address vault) view returns ((uint8 state,uint256 tokenId,uint256 vaultID,string payloadIpfs,address vaultAddress,string beaconName) details)", "function beaconAddresses(string beaconName) view returns (address)"]);
+const VAULT_EXECUTION_ABI = (0, viem.parseAbi)([
+	"function pool() view returns (address)",
+	"function getPositions() view returns (int24[] lowerTicks,int24[] upperTicks,uint16[] relativeWeights)",
+	"function getTotalAmounts() view returns (uint256 total0,uint256 total1)"
+]);
+const V4_VAULT_ABI = (0, viem.parseAbi)([
+	"function poolKey() view returns (address currency0,address currency1,uint24 fee,int24 tickSpacing,address hooks)",
+	"function getPositions() view returns (int24[] lowerTicks,int24[] upperTicks,uint16[] relativeWeights)",
+	"function getTotalAmounts() view returns (uint256 total0,uint256 total1)"
+]);
+const V3_POOL_ABI = (0, viem.parseAbi)([
+	"function factory() view returns (address)",
+	"function slot0() view returns (uint160 sqrtPriceX96,int24 tick,uint16 observationIndex,uint16 observationCardinality,uint16 observationCardinalityNext,uint8 feeProtocol,bool unlocked)",
+	"function tickSpacing() view returns (int24)"
+]);
+const AERODROME_POOL_ABI = (0, viem.parseAbi)([
+	"function factory() view returns (address)",
+	"function slot0() view returns (uint160 sqrtPriceX96,int24 tick,uint16 observationIndex,uint16 observationCardinality,uint16 observationCardinalityNext,bool unlocked)",
+	"function tickSpacing() view returns (int24)"
+]);
+const ALGEBRA_POOL_ABI = (0, viem.parseAbi)([
+	"function factory() view returns (address)",
+	"function globalState() view returns (uint160 price,int24 tick,int24 prevInitializedTick,uint16 fee,uint16 timepointIndex,uint8 communityFee,bool unlocked)",
+	"function tickSpacing() view returns (int24)"
+]);
+const ALGEBRA_INTEGRAL_POOL_ABI = (0, viem.parseAbi)([
+	"function factory() view returns (address)",
+	"function globalState() view returns (uint160 price,int24 tick,uint16 lastFee,uint8 pluginConfig,uint16 communityFee,bool unlocked)",
+	"function tickSpacing() view returns (int24)"
+]);
+const ALGEBRA_DIRECTIONAL_POOL_ABI = (0, viem.parseAbi)([
+	"function factory() view returns (address)",
+	"function globalState() view returns (uint160 price,int24 tick,uint16 feeZto,uint16 feeOtz,uint16 timepointIndex,uint8 communityFeeToken0,uint8 communityFeeToken1,bool unlocked)",
+	"function tickSpacing() view returns (int24)"
+]);
+const STATE_VIEW_ABI = (0, viem.parseAbi)(["function getSlot0(bytes32 poolId) view returns (uint160 sqrtPriceX96,int24 tick,uint24 protocolFee,uint24 lpFee)"]);
+const V4_DYNAMIC_FEE_FLAG = 8388608;
+const V4_MAX_STATIC_FEE = 1e6;
+const V4_MAX_TICK_SPACING = 32767;
+const V4_ALL_HOOK_MASK = (1n << 14n) - 1n;
+const V4_BEFORE_SWAP_FLAG = 1n << 7n;
+const V4_AFTER_SWAP_FLAG = 1n << 6n;
+const V4_AFTER_ADD_LIQUIDITY_FLAG = 1n << 10n;
+const V4_AFTER_REMOVE_LIQUIDITY_FLAG = 1n << 8n;
+const V4_BEFORE_SWAP_RETURNS_DELTA_FLAG = 1n << 3n;
+const V4_AFTER_SWAP_RETURNS_DELTA_FLAG = 1n << 2n;
+const V4_AFTER_ADD_LIQUIDITY_RETURNS_DELTA_FLAG = 1n << 1n;
+const V4_AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA_FLAG = 1n;
+var ExecutionContextError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+function resolvePoolFamily(protocol) {
+	if (isPoolSharkProtocol(protocol)) throw new ExecutionContextError(422, "PoolShark vault execution context is not supported.");
+	if (protocol === Protocol.UniswapV4) return "uniswap-v4";
+	if (isAlgebraDirectionProtocol(protocol)) return "algebra-directional";
+	if (isAlgebraIntegralProtocol(protocol)) return "algebra-integral";
+	if (isAlgebraProtocol(protocol)) return "algebra";
+	if (isAerodromeVault(protocol)) return "aerodrome-cl";
+	return "uniswap-v3-compatible";
+}
+function assertPoolKey(poolKey, invalidStatus = 400) {
+	if (!(0, viem.isAddress)(poolKey.currency0) || !(0, viem.isAddress)(poolKey.currency1) || !(0, viem.isAddress)(poolKey.hooks)) throw new ExecutionContextError(invalidStatus, "Uniswap v4 poolKey contains an invalid address.");
+	if (!Number.isInteger(poolKey.fee) || poolKey.fee < 0 || poolKey.fee > V4_MAX_STATIC_FEE && poolKey.fee !== V4_DYNAMIC_FEE_FLAG) throw new ExecutionContextError(invalidStatus, "Uniswap v4 poolKey fee must be at most 1000000 or the dynamic fee flag 0x800000.");
+	if (!Number.isInteger(poolKey.tickSpacing) || poolKey.tickSpacing <= 0 || poolKey.tickSpacing > V4_MAX_TICK_SPACING) throw new ExecutionContextError(invalidStatus, "Uniswap v4 poolKey tickSpacing must be between 1 and 32767.");
+	const normalized = {
+		currency0: (0, viem.getAddress)(poolKey.currency0),
+		currency1: (0, viem.getAddress)(poolKey.currency1),
+		fee: poolKey.fee,
+		tickSpacing: poolKey.tickSpacing,
+		hooks: (0, viem.getAddress)(poolKey.hooks)
+	};
+	if (BigInt(normalized.currency0) >= BigInt(normalized.currency1)) throw new ExecutionContextError(invalidStatus, "Uniswap v4 poolKey currencies are not canonically ordered.");
+	const hooks = BigInt(normalized.hooks);
+	const isDynamicFee = normalized.fee === V4_DYNAMIC_FEE_FLAG;
+	const hasFlag = (flag) => (hooks & flag) !== 0n;
+	if (!hasFlag(V4_BEFORE_SWAP_FLAG) && hasFlag(V4_BEFORE_SWAP_RETURNS_DELTA_FLAG) || !hasFlag(V4_AFTER_SWAP_FLAG) && hasFlag(V4_AFTER_SWAP_RETURNS_DELTA_FLAG) || !hasFlag(V4_AFTER_ADD_LIQUIDITY_FLAG) && hasFlag(V4_AFTER_ADD_LIQUIDITY_RETURNS_DELTA_FLAG) || !hasFlag(V4_AFTER_REMOVE_LIQUIDITY_FLAG) && hasFlag(V4_AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA_FLAG)) throw new ExecutionContextError(invalidStatus, "Uniswap v4 poolKey hook return-delta flags require their corresponding action flags.");
+	if (!(hooks === 0n ? !isDynamicFee : (hooks & V4_ALL_HOOK_MASK) !== 0n || isDynamicFee)) throw new ExecutionContextError(invalidStatus, "Uniswap v4 poolKey hook address is incompatible with its fee and permission flags.");
+	return normalized;
+}
+function normalizeRawPoolKey(raw) {
+	return assertPoolKey({
+		currency0: raw[0],
+		currency1: raw[1],
+		fee: Number(raw[2]),
+		tickSpacing: Number(raw[3]),
+		hooks: raw[4]
+	}, 422);
+}
+function poolKeysEqual(a, b) {
+	return (0, viem.getAddress)(a.currency0) === (0, viem.getAddress)(b.currency0) && (0, viem.getAddress)(a.currency1) === (0, viem.getAddress)(b.currency1) && a.fee === b.fee && a.tickSpacing === b.tickSpacing && (0, viem.getAddress)(a.hooks) === (0, viem.getAddress)(b.hooks);
+}
+function getPoolId(poolKey) {
+	return (0, viem.keccak256)((0, viem.encodeAbiParameters)([{
+		type: "tuple",
+		components: [
+			{
+				name: "currency0",
+				type: "address"
+			},
+			{
+				name: "currency1",
+				type: "address"
+			},
+			{
+				name: "fee",
+				type: "uint24"
+			},
+			{
+				name: "tickSpacing",
+				type: "int24"
+			},
+			{
+				name: "hooks",
+				type: "address"
+			}
+		]
+	}], [poolKey]));
+}
+function normalizePositions(raw) {
+	const [lowerTicks, upperTicks, relativeWeights] = raw;
+	if (lowerTicks.length !== upperTicks.length || lowerTicks.length !== relativeWeights.length) throw new ExecutionContextError(422, "Vault returned malformed position arrays.");
+	return lowerTicks.map((lowerTick, index) => ({
+		lowerTick: Number(lowerTick),
+		upperTick: Number(upperTicks[index]),
+		relativeWeight: Number(relativeWeights[index])
+	}));
+}
+function protocolFactory(protocol, chain, subgraphStudioKey) {
+	if (!chain) throw new ExecutionContextError(422, "Chain is absent from the SDK network registry.");
+	const address = getAmmConfig(subgraphStudioKey)[protocol]?.factoryAddress?.[chain];
+	if (!address || !(0, viem.isAddress)(address)) throw new ExecutionContextError(422, `${protocol} factory is missing from the SDK protocol registry on ${chain}.`);
+	return (0, viem.getAddress)(address);
+}
+async function readLastExecution(publicClient, chainId, vaultAddress, blockNumber, epochTimestamp) {
+	const pinnedBlock = await publicClient.getBlock({ blockNumber });
+	const timestampUpperBound = pinnedBlock.timestamp < epochTimestamp ? pinnedBlock.timestamp : epochTimestamp;
+	const subgraphUrl = getSubgraphUrlByChainId(chainId);
+	if (!subgraphUrl) throw new ExecutionContextError(422, `Chain ${chainId} has no Steer subgraph configuration.`);
+	const response = await fetch(subgraphUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ query: `{
+        vaultSnapshots(
+          where: { vaultAddress: "${vaultAddress.toLowerCase()}", timestamp_lte: "${timestampUpperBound}" }
+          orderDirection: desc
+          orderBy: timestamp
+          first: 1
+        ) { timestamp }
+      }` })
+	});
+	if (!response.ok) throw new ExecutionContextError(502, `Steer subgraph returned HTTP ${response.status}.`);
+	const result = await response.json();
+	if (result.errors?.length) throw new ExecutionContextError(502, `Steer subgraph error: ${result.errors[0].message}`);
+	const rawTimestamp = result.data?.vaultSnapshots?.[0]?.timestamp;
+	if (!rawTimestamp) return {
+		timestamp: null,
+		elapsed: null,
+		provenance: {
+			source: "steer-subgraph",
+			consistency: "timestamp-bounded",
+			status: "not-found",
+			blockNumber: null,
+			detail: `No indexed vaultSnapshot exists through timestamp ${timestampUpperBound}.`
+		}
+	};
+	let timestamp;
+	try {
+		timestamp = BigInt(rawTimestamp);
+	} catch {
+		throw new ExecutionContextError(502, "Steer subgraph returned a malformed vaultSnapshot timestamp.");
+	}
+	if (timestamp > timestampUpperBound) throw new ExecutionContextError(502, "Steer subgraph returned a vaultSnapshot beyond the query bound.");
+	return {
+		timestamp,
+		elapsed: epochTimestamp - timestamp,
+		provenance: {
+			source: "steer-subgraph",
+			consistency: "timestamp-bounded",
+			status: "indexed",
+			blockNumber: null,
+			detail: `Latest indexed vaultSnapshot bounded by epoch and pinned-block timestamp ${timestampUpperBound}; the entity does not expose its block number.`
+		}
+	};
+}
+/**
+* Builds the normalized read-only state consumed by strategy execution.
+* Every contract read is evaluated at `blockNumber`; `epochTimestamp` is the sole time reference.
+*/
+async function getVaultExecutionContext(params) {
+	try {
+		const { publicClient, blockNumber, epochTimestamp } = params;
+		if (blockNumber < 0n) throw new ExecutionContextError(400, "blockNumber must be non-negative.");
+		if (epochTimestamp < 0n) throw new ExecutionContextError(400, "epochTimestamp must be a non-negative Unix timestamp.");
+		if (!(0, viem.isAddress)(params.vaultAddress)) throw new ExecutionContextError(400, "vaultAddress must be a valid EVM address.");
+		const chainId = await publicClient.getChainId();
+		const chain = chainIdToName(chainId);
+		const network = getNetworkByChainId(chainId);
+		const vaultRegistry = getContractAddressByChainIdAndContractName(chainId, "VaultRegistry");
+		if (!chain || !network || !vaultRegistry || !(0, viem.isAddress)(vaultRegistry)) throw new ExecutionContextError(422, `Chain ${chainId} is missing required SDK deployment data.`);
+		if (blockNumber < BigInt(network.VaultRegistry.startBlock ?? 0)) throw new ExecutionContextError(400, "blockNumber predates the SDK VaultRegistry deployment.");
+		const vaultAddress = (0, viem.getAddress)(params.vaultAddress);
+		const details = await publicClient.readContract({
+			address: (0, viem.getAddress)(vaultRegistry),
+			abi: VAULT_REGISTRY_ABI,
+			functionName: "getVaultDetails",
+			args: [vaultAddress],
+			blockNumber
+		});
+		if (!details.vaultAddress || (0, viem.getAddress)(details.vaultAddress) !== vaultAddress) throw new ExecutionContextError(404, `${vaultAddress} is not registered in the chain VaultRegistry.`);
+		const protocol = getProtocolTypeByBeacon(details.beaconName);
+		if (!protocol) throw new ExecutionContextError(422, `Vault beacon "${details.beaconName}" is not mapped to a supported SDK protocol.`);
+		const beaconAddress = (0, viem.getAddress)(await publicClient.readContract({
+			address: (0, viem.getAddress)(vaultRegistry),
+			abi: VAULT_REGISTRY_ABI,
+			functionName: "beaconAddresses",
+			args: [details.beaconName],
+			blockNumber
+		}));
+		if (beaconAddress === "0x0000000000000000000000000000000000000000") throw new ExecutionContextError(422, `Vault beacon "${details.beaconName}" is not registered.`);
+		const family = resolvePoolFamily(protocol);
+		const explicitPoolKey = params.poolKey ? assertPoolKey(params.poolKey) : void 0;
+		const [rawPositions, rawTotals] = await Promise.all([publicClient.readContract({
+			address: vaultAddress,
+			abi: family === "uniswap-v4" ? V4_VAULT_ABI : VAULT_EXECUTION_ABI,
+			functionName: "getPositions",
+			blockNumber
+		}), publicClient.readContract({
+			address: vaultAddress,
+			abi: family === "uniswap-v4" ? V4_VAULT_ABI : VAULT_EXECUTION_ABI,
+			functionName: "getTotalAmounts",
+			blockNumber
+		})]);
+		let poolAddress = null;
+		let poolId = null;
+		let factoryAddress = null;
+		let poolManagerAddress = null;
+		let poolKey = null;
+		let currentTick;
+		let tickSpacing;
+		if (family === "uniswap-v4") {
+			let rawPoolKey;
+			try {
+				rawPoolKey = await publicClient.readContract({
+					address: vaultAddress,
+					abi: V4_VAULT_ABI,
+					functionName: "poolKey",
+					blockNumber
+				});
+			} catch {
+				throw new ExecutionContextError(422, "A complete Uniswap v4 pool key cannot be proven from vault poolKey(); refusing partial metadata.");
+			}
+			poolKey = normalizeRawPoolKey(rawPoolKey);
+			if (explicitPoolKey && !poolKeysEqual(explicitPoolKey, poolKey)) throw new ExecutionContextError(409, "The explicit Uniswap v4 poolKey does not match vault poolKey().");
+			poolId = getPoolId(poolKey);
+			const v4Config = getAmmConfig(params.subgraphStudioKey ?? "")[protocol];
+			const poolManager = v4Config?.PoolManager?.[chain];
+			const stateView = v4Config?.StateView?.[chain];
+			if (!poolManager || !stateView || !(0, viem.isAddress)(poolManager) || !(0, viem.isAddress)(stateView)) throw new ExecutionContextError(422, "Uniswap v4 PoolManager or StateView is missing from SDK config.");
+			poolManagerAddress = (0, viem.getAddress)(poolManager);
+			const slot0 = await publicClient.readContract({
+				address: (0, viem.getAddress)(stateView),
+				abi: STATE_VIEW_ABI,
+				functionName: "getSlot0",
+				args: [poolId],
+				blockNumber
+			});
+			if (slot0[0] === 0n) throw new ExecutionContextError(422, `Uniswap v4 pool ${poolId} is not initialized in the configured PoolManager.`);
+			currentTick = Number(slot0[1]);
+			tickSpacing = poolKey.tickSpacing;
+		} else {
+			poolAddress = (0, viem.getAddress)(await publicClient.readContract({
+				address: vaultAddress,
+				abi: VAULT_EXECUTION_ABI,
+				functionName: "pool",
+				blockNumber
+			}));
+			factoryAddress = protocolFactory(protocol, chain, params.subgraphStudioKey ?? "");
+			const poolAbi = family === "aerodrome-cl" ? AERODROME_POOL_ABI : family === "algebra-directional" ? ALGEBRA_DIRECTIONAL_POOL_ABI : family === "algebra-integral" ? ALGEBRA_INTEGRAL_POOL_ABI : family === "algebra" ? ALGEBRA_POOL_ABI : V3_POOL_ABI;
+			const stateFunction = family.startsWith("algebra") ? "globalState" : "slot0";
+			const [actualFactory, state, spacing] = await Promise.all([
+				publicClient.readContract({
+					address: poolAddress,
+					abi: poolAbi,
+					functionName: "factory",
+					blockNumber
+				}),
+				publicClient.readContract({
+					address: poolAddress,
+					abi: poolAbi,
+					functionName: stateFunction,
+					blockNumber
+				}),
+				publicClient.readContract({
+					address: poolAddress,
+					abi: poolAbi,
+					functionName: "tickSpacing",
+					blockNumber
+				})
+			]);
+			if ((0, viem.getAddress)(actualFactory) !== factoryAddress) throw new ExecutionContextError(409, `Pool factory ${actualFactory} does not match SDK ${protocol} factory ${factoryAddress}.`);
+			currentTick = Number(state[1]);
+			tickSpacing = Number(spacing);
+		}
+		const lastExecution = await readLastExecution(publicClient, chainId, vaultAddress, blockNumber, epochTimestamp);
+		const pinned = (detail) => ({
+			source: "onchain-contract",
+			consistency: "block-pinned",
+			status: "verified",
+			blockNumber: blockNumber.toString(),
+			detail
+		});
+		return {
+			success: true,
+			status: 200,
+			data: {
+				chainId,
+				blockNumber: blockNumber.toString(),
+				epochTimestamp: epochTimestamp.toString(),
+				vaultAddress,
+				protocol,
+				beaconName: details.beaconName,
+				beaconAddress,
+				poolFamily: family,
+				poolAddress,
+				poolId,
+				factoryAddress,
+				poolManagerAddress,
+				poolKey,
+				currentTick,
+				tickSpacing,
+				positions: normalizePositions(rawPositions),
+				totalAmount0: rawTotals[0].toString(),
+				totalAmount1: rawTotals[1].toString(),
+				lastExecutionTimestamp: lastExecution.timestamp?.toString() ?? null,
+				lastExecutionTimeSeconds: lastExecution.elapsed?.toString() ?? null,
+				provenance: {
+					identity: pinned("VaultRegistry getVaultDetails and SDK beacon mapping."),
+					poolState: pinned(family === "uniswap-v4" ? "Vault poolKey and SDK StateView getSlot0." : "Vault pool, SDK factory validation, pool state, and tickSpacing."),
+					positions: pinned("Vault getPositions."),
+					totals: pinned("Vault getTotalAmounts; pending uncollected fees follow vault contract semantics."),
+					lastExecution: lastExecution.provenance
+				}
+			}
+		};
+	} catch (error) {
+		return {
+			success: false,
+			status: error instanceof ExecutionContextError ? error.status : 500,
+			data: null,
+			error: error instanceof Error ? error.message : "Failed to build vault execution context."
+		};
+	}
+}
+//#endregion
 //#region src/base/VaultClient.ts
 const VAULT_ABI = abis.QuickSwapUniv3MultiPositionLiquidityManager;
 const REWARD_FUNCTIONS_ABI = [{
@@ -19768,6 +20127,17 @@ var VaultClient = class extends SubgraphClient {
 		this.subgraphVaultClient = new SubgraphVaultClient();
 		this.subgraphStudioKey = subgraphStudioKey || "";
 	}
+	/**
+	* Returns normalized strategy execution inputs from one explicitly pinned block.
+	* `epochTimestamp` is a Unix timestamp in seconds and is never derived from wall-clock time.
+	*/
+	async getExecutionContext(params) {
+		return getVaultExecutionContext({
+			publicClient: this.publicClient,
+			subgraphStudioKey: this.subgraphStudioKey,
+			...params
+		});
+	}
 	normalizeProtocolValue(value) {
 		return value.toLowerCase().replace(/[^a-z0-9]/g, "");
 	}
@@ -23856,6 +24226,7 @@ exports.getSwapRouterAddress = getSwapRouterAddress;
 exports.getTheGraphResolverUrl = getTheGraphResolverUrl;
 exports.getTickLensAddress = getTickLensAddress;
 exports.getUniswapV4BeaconSupportedChains = getUniswapV4BeaconSupportedChains;
+exports.getVaultExecutionContext = getVaultExecutionContext;
 exports.getVaultReserves = getVaultReserves;
 exports.glyphConfig = glyphConfig;
 exports.goerliAddresses = goerliAddresses;