@panoptic-eng/sdk 1.0.30 → 1.0.32

package/dist/{v2-BSV35bpu.js → v2-DHJxPCAp.js}

@@ -1,7 +1,7 @@
-import { formatTokenAmount$1 as formatTokenAmount, getAccountCollateral$1 as getAccountCollateral, panopticQueryAbi$1 as panopticQueryAbi, parseTokenAmount$1 as parseTokenAmount, readBlockAndAggregate, requireReturnData } from "./irm-IcePQm1r.js";
-import { AccountInsolventError$1 as AccountInsolventError, ChunkLimitError$1 as ChunkLimitError, DEFAULT_VEGOID$1 as DEFAULT_VEGOID, InvalidHistoryRangeError$1 as InvalidHistoryRangeError, NotEnoughTokensError$1 as NotEnoughTokensError, PanopticError, PanopticValidationError$1 as PanopticValidationError, StorageDataNotFoundError, SwapTokenMismatchError$1 as SwapTokenMismatchError, collateralTrackerV2Abi, decodeLeftRightSigned$1 as decodeLeftRightSigned, decodeLeftRightUnsigned$1 as decodeLeftRightUnsigned, decodePosition, decodePositionBalance, decodeTickSpacing$1 as decodeTickSpacing, getBlockMeta$1 as getBlockMeta, getPool, panopticFactoryV3Abi, panopticFactoryV4Abi, panopticGuardianAbi, panopticPoolV2Abi, panopticQueryAbi as panopticQueryAbi$1, parsePanopticError$1 as parsePanopticError, riskEngineAbi, semiFungiblePositionManagerV3Abi, semiFungiblePositionManagerV4Abi, stateViewAbi, uniswapV3PoolAbi } from "./position-UL1gOvqZ.js";
+import { formatTokenAmount$1 as formatTokenAmount, getAccountCollateral$1 as getAccountCollateral, panopticQueryAbi, parseTokenAmount$1 as parseTokenAmount, readBlockAndAggregate, requireReturnData } from "./irm-iAI9hTYQ.js";
+import { AccountInsolventError$1 as AccountInsolventError, ChunkLimitError$1 as ChunkLimitError, DEFAULT_VEGOID$1 as DEFAULT_VEGOID, InvalidHistoryRangeError$1 as InvalidHistoryRangeError, NotEnoughTokensError$1 as NotEnoughTokensError, PanopticError, PanopticValidationError$1 as PanopticValidationError, StorageDataNotFoundError, collateralTrackerV2Abi, decodeLeftRightSigned$1 as decodeLeftRightSigned, decodeLeftRightUnsigned$1 as decodeLeftRightUnsigned, decodePosition, decodePositionBalance, decodeTickSpacing$1 as decodeTickSpacing, getBlockMeta$1 as getBlockMeta, getPool, panopticFactoryV3Abi, panopticFactoryV4Abi, panopticGuardianAbi, panopticPoolV2Abi, panopticQueryAbi$1, parsePanopticError$1 as parsePanopticError, riskEngineAbi, semiFungiblePositionManagerV3Abi, semiFungiblePositionManagerV4Abi, stateViewAbi, uniswapV3PoolAbi } from "./position-ClU7GrTa.js";
 import { MAX_TICK, MAX_TRACKED_CHUNKS, MIN_TICK, WAD, calculatePositionDelta, calculatePositionGamma, calculatePositionValue, priceToTick, sqrtPriceX96ToTick, tickLimits, tickToPrice, tickToPriceDecimalScaled, tickToSqrtPriceX96 } from "./greeks-GysWXct-.js";
-import { addLegToTokenId$1 as addLegToTokenId, buildBatchDispatchArgs$1 as buildBatchDispatchArgs, countLegs$1 as countLegs, createTokenIdBuilder$1 as createTokenIdBuilder, decodeAllLegs$1 as decodeAllLegs, decodeTokenId$1 as decodeTokenId, getClosedPositionsKey$1 as getClosedPositionsKey, getPendingPositionsKey$1 as getPendingPositionsKey, getPoolMetaKey$1 as getPoolMetaKey, getPositionMetaKey$1 as getPositionMetaKey, getPositionsKey$1 as getPositionsKey, getTrackedChunksKey$1 as getTrackedChunksKey, getTrackedPositionIds$1 as getTrackedPositionIds, jsonSerializer$1 as jsonSerializer, loadCheckpoint$1 as loadCheckpoint, simulateOpenPosition$1 as simulateOpenPosition, simulateWithTokenFlow } from "./writes-RyS0kHpB.js";
+import { addLegToTokenId$1 as addLegToTokenId, buildBatchDispatchArgs$1 as buildBatchDispatchArgs, buildUniqueCredit$1 as buildUniqueCredit, countLegs$1 as countLegs, decodeAllLegs$1 as decodeAllLegs, decodeTokenId$1 as decodeTokenId, getClosedPositionsKey$1 as getClosedPositionsKey, getPendingPositionsKey$1 as getPendingPositionsKey, getPoolMetaKey$1 as getPoolMetaKey, getPositionMetaKey$1 as getPositionMetaKey, getPositionsKey$1 as getPositionsKey, getTrackedChunksKey$1 as getTrackedChunksKey, getTrackedPositionIds$1 as getTrackedPositionIds, jsonSerializer$1 as jsonSerializer, loadCheckpoint$1 as loadCheckpoint, resolveTokenIndex$1 as resolveTokenIndex, simulateOpenPosition$1 as simulateOpenPosition, simulateWithTokenFlow } from "./writes-DQLGdkJ5.js";
 import { ContractFunctionExecutionError, decodeFunctionResult, encodeAbiParameters, encodeFunctionData, getAddress, keccak256, zeroAddress } from "viem";
 import { multicall } from "viem/actions";
 
@@ -1596,6 +1596,35 @@ async function getMaxWithdrawable(params) {
 	};
 }
 /**
+* Read the maximum number of shares an account can redeem from a CollateralTracker.
+*
+* This is the ERC4626 `maxRedeem(owner)`, i.e. `min(availableShares, balanceOf(owner))`,
+* and returns 0 when the account has open positions (legs). Redeeming exactly this many
+* shares burns the account's full (available) share balance, so a MAX withdraw leaves no
+* rounding dust — unlike an assets-based `withdraw`, which round-trips shares↔assets.
+*
+* @param params - The parameters
+* @returns Maximum redeemable shares with block metadata
+*/
+async function getMaxRedeem(params) {
+	const { client, collateralTrackerAddress, account, blockNumber } = params;
+	const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+	const [maxRedeem, _meta] = await Promise.all([client.readContract({
+		address: collateralTrackerAddress,
+		abi: collateralTrackerV2Abi,
+		functionName: "maxRedeem",
+		args: [account],
+		blockNumber: targetBlockNumber
+	}), getBlockMeta({
+		client,
+		blockNumber: targetBlockNumber
+	})]);
+	return {
+		maxRedeem,
+		_meta
+	};
+}
+/**
 * Try to simulate a solvency-checked withdraw with the given amount.
 */
 async function tryWithdrawSimulation(params) {
@@ -2849,6 +2878,17 @@ const MIN_TICK$1 = -887272n;
 const MAX_TICK$1 = 887272n;
 const FP96 = 1n << 96n;
 const Q128$1 = 1n << 128n;
+/** Cap for a usage ratio with no collateral behind it. */
+const MAX_USAGE_BPS = 1000000n;
+const bigintMax = (a, b) => a > b ? a : b;
+const bigintMin = (a, b) => a < b ? a : b;
+/**
+* `RiskEngine.BP_DECREASE_BUFFER` over `PanopticPool.NO_BUFFER` — the extra
+* margin the solvency check demands at mint (and on collateral withdrawal),
+* above the maintenance requirement that governs liquidation.
+*/
+const MINT_BUFFER = 10666667n;
+const MINT_BUFFER_DENOMINATOR = 10000000n;
 /**
 * Convert a token0 amount to its token1-equivalent at the given sqrtPriceX96.
 *
@@ -2960,6 +3000,19 @@ async function getMarginBuffer(params) {
 			]
 		})
 	});
+	const checkCollateralIndex = hasPositions ? calls.length : null;
+	if (checkCollateralIndex !== null) calls.push({
+		target: queryAddress,
+		callData: encodeFunctionData({
+			abi: panopticQueryAbi,
+			functionName: "checkCollateral",
+			args: [
+				poolAddress,
+				account,
+				tokenIds
+			]
+		})
+	});
 	const { _meta, results } = await readBlockAndAggregate({
 		client,
 		calls,
@@ -2991,6 +3044,34 @@ async function getMarginBuffer(params) {
 		functionName: "getLiquidationPrices",
 		data: requireReturnData(results, liqPricesIndex, "PanopticQuery.getLiquidationPrices")
 	});
+	const checkCollateralResult = checkCollateralIndex === null ? null : decodeFunctionResult({
+		abi: panopticQueryAbi,
+		functionName: "checkCollateral",
+		data: requireReturnData(results, checkCollateralIndex, "PanopticQuery.checkCollateral")
+	});
+	let usageBps0 = null;
+	let usageBps1 = null;
+	let crossMarginUsageBps = null;
+	let mintableMarginBinding = null;
+	if (checkCollateralResult) {
+		const [balances0, requireds0, balances1, requireds1] = checkCollateralResult;
+		const ratio = (required, balance) => {
+			if (required === void 0 || balance === void 0) return null;
+			if (balance === 0n) return required > 0n ? MAX_USAGE_BPS : 0n;
+			return required * 10000n / balance;
+		};
+		usageBps0 = ratio(requireds0[0], balances0[0]);
+		usageBps1 = ratio(requireds1[0], balances1[0]);
+		if (usageBps0 !== null || usageBps1 !== null) crossMarginUsageBps = usageBps0 === null ? usageBps1 : usageBps1 === null ? usageBps0 : bigintMax(usageBps0, usageBps1);
+		const mintable = (balance, required) => {
+			if (balance === void 0 || required === void 0) return null;
+			const requiredAtMint = (required * MINT_BUFFER + MINT_BUFFER_DENOMINATOR - 1n) / MINT_BUFFER_DENOMINATOR;
+			return balance > requiredAtMint ? balance - requiredAtMint : 0n;
+		};
+		const mintable0 = mintable(balances0[0], requireds0[0]);
+		const mintable1 = mintable(balances1[0], requireds1[0]);
+		if (mintable0 !== null || mintable1 !== null) mintableMarginBinding = mintable0 === null ? mintable1 : mintable1 === null ? mintable0 : bigintMin(mintable0, mintable1);
+	}
 	let required0Native = 0n;
 	let required1Native = 0n;
 	if (positionDataResult) {
@@ -3039,6 +3120,10 @@ async function getMarginBuffer(params) {
 		liquidationDistance,
 		lowerLiquidationTick,
 		upperLiquidationTick,
+		crossMarginUsageBps,
+		usageBps0,
+		usageBps1,
+		mintableMarginBinding,
 		currentTick,
 		_meta
 	};
@@ -3419,6 +3504,365 @@ async function getAccountBuyingPower(params) {
 	};
 }
 
+//#endregion
+//#region src/panoptic/v2/simulations/simulateDispatch.ts
+/**
+* Simulate a raw dispatch operation.
+*
+* Uses PanopticPool.multicall with getAssetsOf-dispatch-getAssetsOf pattern
+* to measure exact collateral asset movements.
+*
+* @param params - Simulation parameters
+* @returns Simulation result with dispatch data or error
+*/
+async function simulateDispatch(params) {
+	const { client, poolAddress, account, positionIdList, finalPositionIdList, positionSizes, tickAndSpreadLimits, usePremiaAsCollateral = false, builderCode = 0n, blockNumber, existingPositionIdList } = params;
+	const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+	const metaPromise = getBlockMeta({
+		client,
+		blockNumber: targetBlockNumber
+	});
+	try {
+		const callData = encodeFunctionData({
+			abi: panopticPoolV2Abi,
+			functionName: "dispatch",
+			args: [
+				positionIdList,
+				finalPositionIdList,
+				positionSizes,
+				tickAndSpreadLimits.map((t) => [
+					Number(t[0]),
+					Number(t[1]),
+					Number(t[2])
+				]),
+				usePremiaAsCollateral,
+				builderCode
+			]
+		});
+		const preFullPositionsCallData = existingPositionIdList !== void 0 ? encodeFunctionData({
+			abi: panopticPoolV2Abi,
+			functionName: "getFullPositionsData",
+			args: [
+				account,
+				false,
+				existingPositionIdList
+			]
+		}) : void 0;
+		const postFullPositionsCallData = encodeFunctionData({
+			abi: panopticPoolV2Abi,
+			functionName: "getFullPositionsData",
+			args: [
+				account,
+				false,
+				finalPositionIdList
+			]
+		});
+		const flowResult = await simulateWithTokenFlow({
+			client,
+			poolAddress,
+			user: account,
+			callData,
+			blockNumber: targetBlockNumber,
+			preCallData: preFullPositionsCallData ? [preFullPositionsCallData] : void 0,
+			postCallData: [postFullPositionsCallData]
+		});
+		if (!flowResult.success || !flowResult.tokenFlow) throw flowResult.rawError ?? new PanopticError(flowResult.error || "Token flow simulation failed");
+		const tokenFlow = flowResult.tokenFlow;
+		const preSnapshot = existingPositionIdList ?? [];
+		const positionsCreated = finalPositionIdList.filter((id) => !preSnapshot.includes(id));
+		const positionsClosed = preSnapshot.filter((id) => !finalPositionIdList.includes(id));
+		const sumCollateralReq = (data$1) => {
+			if (!data$1) return null;
+			try {
+				const decoded = decodeFunctionResult({
+					abi: panopticPoolV2Abi,
+					functionName: "getFullPositionsData",
+					data: data$1
+				});
+				const reqs = decoded[3];
+				let token0 = 0n;
+				let token1 = 0n;
+				for (const packed of reqs) {
+					const r = decodeLeftRightUnsigned(packed);
+					token0 += r.right;
+					token1 += r.left;
+				}
+				return {
+					token0,
+					token1
+				};
+			} catch {
+				return null;
+			}
+		};
+		const preReq = sumCollateralReq(flowResult.preCallResults?.[0]);
+		const postReq = sumCollateralReq(flowResult.postCallResults?.[0]);
+		const _meta = await metaPromise;
+		const data = {
+			netAmount0: tokenFlow.delta0,
+			netAmount1: tokenFlow.delta1,
+			positionsCreated,
+			positionsClosed,
+			postCollateral0: tokenFlow.balanceAfter0,
+			postCollateral1: tokenFlow.balanceAfter1,
+			preMarginExcess0: preReq ? tokenFlow.balanceBefore0 - preReq.token0 : null,
+			preMarginExcess1: preReq ? tokenFlow.balanceBefore1 - preReq.token1 : null,
+			postMarginExcess0: postReq ? tokenFlow.balanceAfter0 - postReq.token0 : null,
+			postMarginExcess1: postReq ? tokenFlow.balanceAfter1 - postReq.token1 : null
+		};
+		return {
+			success: true,
+			data,
+			gasEstimate: flowResult.gasEstimate,
+			tokenFlow,
+			_meta
+		};
+	} catch (error) {
+		const _meta = await metaPromise;
+		return {
+			success: false,
+			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Simulation failed", error instanceof Error ? error : void 0),
+			_meta
+		};
+	}
+}
+
+//#endregion
+//#region src/panoptic/v2/simulations/tokenShortfallRecovery.ts
+const BPS_DENOMINATOR = 10000n;
+const MAX_RECOVERY_QUOTE_ATTEMPTS = 8;
+/**
+* Wrap a dispatch with a temporary credit leg that sources the shortfall.
+*
+* Exact-output construction: mint the credit with `swapAtMint=true` (paying a
+* swapped amount of the token the account has), run the user's operations, then
+* burn it with `swapAtMint=false` to receive exactly the missing token.
+*
+* A credit rather than a loan so the recovery is never capped by the shortfall
+* token's utilization — the case that fails today on a >94% utilized tracker.
+*/
+function buildTokenShortfallRecoveryDispatch(params) {
+	const { dispatch, creditTokenId, creditPositionSize, tickLimitLow, tickLimitHigh } = params;
+	const low = tickLimitLow <= tickLimitHigh ? tickLimitLow : tickLimitHigh;
+	const high = tickLimitLow <= tickLimitHigh ? tickLimitHigh : tickLimitLow;
+	const mintLimits = [
+		high,
+		low,
+		0n
+	];
+	const burnLimits = [
+		low,
+		high,
+		0n
+	];
+	return {
+		positionIdList: [
+			creditTokenId,
+			...dispatch.positionIdList,
+			creditTokenId
+		],
+		finalPositionIdList: [...dispatch.finalPositionIdList],
+		positionSizes: [
+			creditPositionSize,
+			...dispatch.positionSizes,
+			0n
+		],
+		tickAndSpreadLimits: [
+			mintLimits,
+			...dispatch.tickAndSpreadLimits,
+			burnLimits
+		],
+		usePremiaAsCollateral: dispatch.usePremiaAsCollateral,
+		builderCode: dispatch.builderCode
+	};
+}
+/**
+* Extract a fully-decoded `NotEnoughTokens` revert from an arbitrary error.
+*
+* Returns `null` when the error is something else, or when only the 4-byte
+* selector could be matched (the parser's fallback path constructs the error
+* with undefined args, which is not actionable).
+*/
+function getNotEnoughTokensError(error) {
+	let candidate = null;
+	if (error instanceof NotEnoughTokensError) candidate = error;
+	else {
+		const parsed = parsePanopticError(error);
+		if (parsed?.error instanceof NotEnoughTokensError) candidate = parsed.error;
+	}
+	if (candidate === null) return null;
+	const args = candidate;
+	if (args.tokenAddress === void 0 || args.assetsRequested === void 0 || args.assetBalance === void 0) return null;
+	return candidate;
+}
+function maximumAmountIn(estimatedAmountIn, slippageBps) {
+	if (slippageBps < 0n) throw new PanopticError("slippageBps must be non-negative");
+	return (estimatedAmountIn * (BPS_DENOMINATOR + slippageBps) + BPS_DENOMINATOR - 1n) / BPS_DENOMINATOR;
+}
+function getInputAmount(tokenFlow, tokenInIndex) {
+	const delta = tokenInIndex === 0n ? tokenFlow.delta0 : tokenFlow.delta1;
+	return delta < 0n ? -delta : delta;
+}
+function getBalanceBefore(tokenFlow, tokenIndex) {
+	return tokenIndex === 0n ? tokenFlow.balanceBefore0 : tokenFlow.balanceBefore1;
+}
+function getOutputAmount(tokenFlow, tokenOutIndex) {
+	const delta = tokenOutIndex === 0n ? tokenFlow.delta0 : tokenFlow.delta1;
+	return delta > 0n ? delta : 0n;
+}
+async function quoteTokenShortfallRecovery(params) {
+	const shortfallError = getNotEnoughTokensError(params.error);
+	if (shortfallError === null) return {
+		available: false,
+		reason: "not-token-shortfall"
+	};
+	let amountOut = shortfallError.assetsRequested - shortfallError.assetBalance;
+	if (amountOut <= 0n) return {
+		available: false,
+		reason: "invalid-shortfall",
+		detail: `requested=${shortfallError.assetsRequested} <= balance=${shortfallError.assetBalance}`
+	};
+	if (params.slippageBps < 0n || params.slippageBps > BPS_DENOMINATOR) return {
+		available: false,
+		reason: "invalid-slippage",
+		detail: `slippageBps=${params.slippageBps} is outside [0, ${BPS_DENOMINATOR}]`
+	};
+	const tickLimitLow = params.tickLimitLow ?? MIN_TICK;
+	const tickLimitHigh = params.tickLimitHigh ?? MAX_TICK;
+	if (tickLimitLow >= tickLimitHigh) return {
+		available: false,
+		reason: "invalid-tick-limits",
+		detail: `tickLimitLow=${tickLimitLow} >= tickLimitHigh=${tickLimitHigh}`
+	};
+	const targetBlockNumber = params.blockNumber ?? await params.client.getBlockNumber();
+	const pool = await getPool({
+		client: params.client,
+		poolAddress: params.poolAddress,
+		chainId: params.chainId,
+		blockNumber: targetBlockNumber
+	});
+	const token0 = pool.collateralTracker0.token;
+	const token1 = pool.collateralTracker1.token;
+	const normalizedShortfallToken = shortfallError.tokenAddress.toLowerCase();
+	const isToken0Shortfall = normalizedShortfallToken === token0.toLowerCase() || normalizedShortfallToken === pool.collateralTracker0.address.toLowerCase();
+	const isToken1Shortfall = normalizedShortfallToken === token1.toLowerCase() || normalizedShortfallToken === pool.collateralTracker1.address.toLowerCase();
+	const tokenOutIndex = isToken0Shortfall ? 0n : isToken1Shortfall ? 1n : null;
+	if (tokenOutIndex === null) return {
+		available: false,
+		reason: "unsupported-token",
+		detail: `${shortfallError.tokenAddress} is neither collateral token of ${params.poolAddress}`
+	};
+	const tokenInIndex = tokenOutIndex === 0n ? 1n : 0n;
+	const tokenOut = tokenOutIndex === 0n ? token0 : token1;
+	const tokenIn = tokenInIndex === 0n ? token0 : token1;
+	const collisionIds = Array.from(new Set([
+		...params.existingPositionIds,
+		...params.dispatch.positionIdList,
+		...params.dispatch.finalPositionIdList
+	]));
+	for (let attempt = 0; attempt < MAX_RECOVERY_QUOTE_ATTEMPTS; attempt++) {
+		const credit = buildUniqueCredit(pool.poolId, tokenOutIndex, tokenOutIndex, pool.currentTick, pool.tickSpacing, collisionIds, amountOut);
+		const recoveredDispatch = buildTokenShortfallRecoveryDispatch({
+			dispatch: params.dispatch,
+			creditTokenId: credit.tokenId,
+			creditPositionSize: credit.adjustedSize,
+			tickLimitLow,
+			tickLimitHigh
+		});
+		const swapDispatch = buildTokenShortfallRecoveryDispatch({
+			dispatch: {
+				positionIdList: [],
+				finalPositionIdList: [...params.existingPositionIds],
+				positionSizes: [],
+				tickAndSpreadLimits: [],
+				usePremiaAsCollateral: false,
+				builderCode: 0n
+			},
+			creditTokenId: credit.tokenId,
+			creditPositionSize: credit.adjustedSize,
+			tickLimitLow,
+			tickLimitHigh
+		});
+		const swapSimulation = await simulateDispatch({
+			client: params.client,
+			poolAddress: params.poolAddress,
+			account: params.account,
+			existingPositionIdList: params.existingPositionIds,
+			...swapDispatch,
+			blockNumber: targetBlockNumber
+		});
+		if (!swapSimulation.success || swapSimulation.tokenFlow === void 0) return {
+			available: false,
+			reason: "swap-unavailable",
+			detail: swapSimulation.success ? "swap-only simulation returned no token flow" : `swap-only simulation reverted: ${swapSimulation.error.message}`,
+			error: swapSimulation.success ? void 0 : swapSimulation.error
+		};
+		const estimatedAmountIn = getInputAmount(swapSimulation.tokenFlow, tokenInIndex);
+		const maxAmountIn = maximumAmountIn(estimatedAmountIn, params.slippageBps);
+		const swapOutput = getOutputAmount(swapSimulation.tokenFlow, tokenOutIndex);
+		const sourceBalance = getBalanceBefore(swapSimulation.tokenFlow, tokenInIndex);
+		if (swapOutput < amountOut || sourceBalance < maxAmountIn) return {
+			available: false,
+			reason: "swap-unavailable",
+			detail: swapOutput < amountOut ? `swap output ${swapOutput} < required ${amountOut}` : `source balance ${sourceBalance} < maximumAmountIn ${maxAmountIn} (estimated ${estimatedAmountIn}, slippageBps ${params.slippageBps})`,
+			error: new PanopticError("Insufficient source collateral for the recovery swap")
+		};
+		const recoverySimulation = await simulateDispatch({
+			client: params.client,
+			poolAddress: params.poolAddress,
+			account: params.account,
+			existingPositionIdList: params.existingPositionIds,
+			...recoveredDispatch,
+			blockNumber: targetBlockNumber
+		});
+		if (recoverySimulation.success) {
+			if (recoverySimulation.tokenFlow !== void 0) return {
+				available: true,
+				quote: {
+					tokenIn,
+					tokenOut,
+					amountOut,
+					estimatedAmountIn,
+					maximumAmountIn: maxAmountIn,
+					slippageBps: params.slippageBps,
+					netTokenInChange: tokenInIndex === 0n ? recoverySimulation.tokenFlow.delta0 : recoverySimulation.tokenFlow.delta1,
+					netTokenOutChange: tokenOutIndex === 0n ? recoverySimulation.tokenFlow.delta0 : recoverySimulation.tokenFlow.delta1,
+					creditTokenId: credit.tokenId,
+					dispatch: recoveredDispatch,
+					simulation: {
+						...recoverySimulation,
+						tokenFlow: recoverySimulation.tokenFlow
+					},
+					tokenFlow: recoverySimulation.tokenFlow,
+					_meta: recoverySimulation._meta
+				}
+			};
+			return {
+				available: false,
+				reason: "recovery-unavailable",
+				detail: "wrapped dispatch simulation returned no token flow",
+				error: new PanopticError("Recovery simulation did not return token flow")
+			};
+		}
+		const remainingShortfall = getNotEnoughTokensError(recoverySimulation.error);
+		if (remainingShortfall === null || remainingShortfall.tokenAddress.toLowerCase() !== normalizedShortfallToken) return {
+			available: false,
+			reason: "recovery-unavailable",
+			detail: `wrapped dispatch reverted with a non-shortfall error: ${recoverySimulation.error.message}`,
+			error: recoverySimulation.error
+		};
+		const decodedShortfall = remainingShortfall.assetsRequested - remainingShortfall.assetBalance;
+		const additionalAmountOut = decodedShortfall > 0n ? decodedShortfall : amountOut;
+		amountOut += additionalAmountOut;
+	}
+	return {
+		available: false,
+		reason: "recovery-unavailable",
+		detail: `still short after ${MAX_RECOVERY_QUOTE_ATTEMPTS} sizing attempts (last target ${amountOut})`,
+		error: new PanopticError("Could not cover recovery swap costs within the quote attempt limit")
+	};
+}
+
 //#endregion
 //#region src/panoptic/v2/reads/openPositionPreview.ts
 /**
@@ -3456,16 +3900,19 @@ async function getOpenPositionPreview(params) {
 		blockNumber
 	})]);
 	let isSolvent = true;
+	let tokenShortfall = null;
 	if (!simulation.success) {
 		const parsed = parsePanopticError(simulation.error);
 		const err = parsed?.error ?? simulation.error;
-		isSolvent = !(err instanceof AccountInsolventError || err instanceof NotEnoughTokensError);
+		isSolvent = !(err instanceof AccountInsolventError);
+		tokenShortfall = getNotEnoughTokensError(err);
 	}
 	const data = simulation.success ? simulation.data : null;
 	return {
 		currentBuyingPower,
 		simulation,
 		isSolvent,
+		tokenShortfall,
 		amount0Required: data?.amount0Required ?? null,
 		amount1Required: data?.amount1Required ?? null,
 		postCollateral0: data?.postCollateral0 ?? null,
@@ -4102,6 +4549,7 @@ async function getUniswapV4PoolBasicState(params) {
 		poolId,
 		sqrtPriceX96: slot0[0],
 		currentTick: Number(slot0[1]),
+		protocolFee: BigInt(slot0[2]),
 		lpFee: Number(slot0[3]),
 		liquidity,
 		_meta
@@ -4187,6 +4635,7 @@ async function getUniswapV4PoolInfo(params) {
 		hooks: poolKey.hooks,
 		currentTick: Number(slot0[1]),
 		sqrtPriceX96: slot0[0],
+		protocolFee: BigInt(slot0[2]),
 		liquidity,
 		_meta
 	};
@@ -5214,129 +5663,6 @@ async function getPoolDeploymentBlock(client, poolAddress) {
 	return foundBlock;
 }
 
-//#endregion
-//#region src/panoptic/v2/simulations/simulateDispatch.ts
-/**
-* Simulate a raw dispatch operation.
-*
-* Uses PanopticPool.multicall with getAssetsOf-dispatch-getAssetsOf pattern
-* to measure exact collateral asset movements.
-*
-* @param params - Simulation parameters
-* @returns Simulation result with dispatch data or error
-*/
-async function simulateDispatch(params) {
-	const { client, poolAddress, account, positionIdList, finalPositionIdList, positionSizes, tickAndSpreadLimits, usePremiaAsCollateral = false, builderCode = 0n, blockNumber, existingPositionIdList } = params;
-	const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
-	const metaPromise = getBlockMeta({
-		client,
-		blockNumber: targetBlockNumber
-	});
-	try {
-		const callData = encodeFunctionData({
-			abi: panopticPoolV2Abi,
-			functionName: "dispatch",
-			args: [
-				positionIdList,
-				finalPositionIdList,
-				positionSizes,
-				tickAndSpreadLimits.map((t) => [
-					Number(t[0]),
-					Number(t[1]),
-					Number(t[2])
-				]),
-				usePremiaAsCollateral,
-				builderCode
-			]
-		});
-		const preFullPositionsCallData = existingPositionIdList !== void 0 ? encodeFunctionData({
-			abi: panopticPoolV2Abi,
-			functionName: "getFullPositionsData",
-			args: [
-				account,
-				false,
-				existingPositionIdList
-			]
-		}) : void 0;
-		const postFullPositionsCallData = encodeFunctionData({
-			abi: panopticPoolV2Abi,
-			functionName: "getFullPositionsData",
-			args: [
-				account,
-				false,
-				finalPositionIdList
-			]
-		});
-		const flowResult = await simulateWithTokenFlow({
-			client,
-			poolAddress,
-			user: account,
-			callData,
-			blockNumber: targetBlockNumber,
-			preCallData: preFullPositionsCallData ? [preFullPositionsCallData] : void 0,
-			postCallData: [postFullPositionsCallData]
-		});
-		if (!flowResult.success || !flowResult.tokenFlow) throw flowResult.rawError ?? new PanopticError(flowResult.error || "Token flow simulation failed");
-		const tokenFlow = flowResult.tokenFlow;
-		const preSnapshot = existingPositionIdList ?? [];
-		const positionsCreated = finalPositionIdList.filter((id) => !preSnapshot.includes(id));
-		const positionsClosed = preSnapshot.filter((id) => !finalPositionIdList.includes(id));
-		const sumCollateralReq = (data$1) => {
-			if (!data$1) return null;
-			try {
-				const decoded = decodeFunctionResult({
-					abi: panopticPoolV2Abi,
-					functionName: "getFullPositionsData",
-					data: data$1
-				});
-				const reqs = decoded[3];
-				let token0 = 0n;
-				let token1 = 0n;
-				for (const packed of reqs) {
-					const r = decodeLeftRightUnsigned(packed);
-					token0 += r.right;
-					token1 += r.left;
-				}
-				return {
-					token0,
-					token1
-				};
-			} catch {
-				return null;
-			}
-		};
-		const preReq = sumCollateralReq(flowResult.preCallResults?.[0]);
-		const postReq = sumCollateralReq(flowResult.postCallResults?.[0]);
-		const _meta = await metaPromise;
-		const data = {
-			netAmount0: tokenFlow.delta0,
-			netAmount1: tokenFlow.delta1,
-			positionsCreated,
-			positionsClosed,
-			postCollateral0: tokenFlow.balanceAfter0,
-			postCollateral1: tokenFlow.balanceAfter1,
-			preMarginExcess0: preReq ? tokenFlow.balanceBefore0 - preReq.token0 : null,
-			preMarginExcess1: preReq ? tokenFlow.balanceBefore1 - preReq.token1 : null,
-			postMarginExcess0: postReq ? tokenFlow.balanceAfter0 - postReq.token0 : null,
-			postMarginExcess1: postReq ? tokenFlow.balanceAfter1 - postReq.token1 : null
-		};
-		return {
-			success: true,
-			data,
-			gasEstimate: flowResult.gasEstimate,
-			tokenFlow,
-			_meta
-		};
-	} catch (error) {
-		const _meta = await metaPromise;
-		return {
-			success: false,
-			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Simulation failed", error instanceof Error ? error : void 0),
-			_meta
-		};
-	}
-}
-
 //#endregion
 //#region src/panoptic/v2/simulations/simulateBatchDispatch.ts
 /**
@@ -6103,47 +6429,19 @@ async function simulateSFPMBurn(params) {
 //#endregion
 //#region src/panoptic/v2/simulations/simulateSwap.ts
 /**
-* Resolve token index, throwing SwapTokenMismatchError on mismatch.
-*/
-function resolveTokenIndex(tokenAddress, token0, token1) {
-	const lower = tokenAddress.toLowerCase();
-	if (lower === token0.toLowerCase()) return 0n;
-	if (lower === token1.toLowerCase()) return 1n;
-	throw new SwapTokenMismatchError(tokenAddress, token0, token1);
-}
-/**
-* Build a unique loan tokenId.
-*/
-function buildUniqueLoan(poolId, asset, tokenType, currentTick, tickSpacing, existingPositionIds) {
-	const mod = currentTick % tickSpacing;
-	let strike = currentTick - (mod + tickSpacing) % tickSpacing;
-	const step = tickSpacing;
-	const existingSet = new Set(existingPositionIds);
-	for (let attempt = 0; attempt < 1e3; attempt++) {
-		const tokenId = createTokenIdBuilder(poolId).addLoan({
-			asset,
-			tokenType,
-			strike
-		}).build();
-		if (!existingSet.has(tokenId)) return tokenId;
-		strike += step;
-	}
-	throw new PanopticError("Could not build unique loan tokenId after 1000 attempts");
-}
-/**
 * Build dispatch calldata for swap simulation.
 */
-function buildSwapCallData(loanTokenId, existingPositionIds, amount, mintTickLimits, burnTickLimits) {
+function buildSwapCallData(creditTokenId, existingPositionIds, amount, mintTickLimits, burnTickLimits, builderCode) {
 	return encodeFunctionData({
 		abi: panopticPoolV2Abi,
 		functionName: "dispatch",
 		args: [
-			[loanTokenId, loanTokenId],
+			[creditTokenId, creditTokenId],
 			[...existingPositionIds],
 			[amount, 0n],
 			[mintTickLimits, burnTickLimits],
 			false,
-			0n
+			builderCode
 		]
 	});
 }
@@ -6171,7 +6469,7 @@ function buildSwapResult(tokenFlow, tokenOutIndex) {
 * @returns Simulation result with swap data or error
 */
 async function simulateSwapExactOut(params) {
-	const { client, poolAddress, account, chainId, tokenOut, amountOut, slippageBps, existingPositionIds, blockNumber } = params;
+	const { client, poolAddress, account, chainId, tokenOut, amountOut, slippageBps, existingPositionIds, builderCode = 0n, blockNumber } = params;
 	try {
 		const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
 		const metaPromise = getBlockMeta({
@@ -6187,9 +6485,9 @@ async function simulateSwapExactOut(params) {
 		const token0 = pool.collateralTracker0.token;
 		const token1 = pool.collateralTracker1.token;
 		const tokenOutIndex = resolveTokenIndex(tokenOut, token0, token1);
-		const tokenType = tokenOutIndex === 0n ? 1n : 0n;
+		const tokenType = tokenOutIndex;
 		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
-		const loanTokenId = buildUniqueLoan(pool.poolId, tokenOutIndex, tokenType, pool.currentTick, pool.tickSpacing, existingPositionIds);
+		const { tokenId: creditTokenId, adjustedSize } = buildUniqueCredit(pool.poolId, tokenOutIndex, tokenType, pool.currentTick, pool.tickSpacing, existingPositionIds, amountOut);
 		const mintTickLimits = [
 			Number(tickLimitHigh),
 			Number(tickLimitLow),
@@ -6200,7 +6498,7 @@ async function simulateSwapExactOut(params) {
 			Number(tickLimitHigh),
 			0
 		];
-		const callData = buildSwapCallData(loanTokenId, existingPositionIds, amountOut, mintTickLimits, burnTickLimits);
+		const callData = buildSwapCallData(creditTokenId, existingPositionIds, adjustedSize, mintTickLimits, burnTickLimits, builderCode);
 		const flowResult = await simulateWithTokenFlow({
 			client,
 			poolAddress,
@@ -6238,7 +6536,7 @@ async function simulateSwapExactOut(params) {
 * @returns Simulation result with swap data or error
 */
 async function simulateSwapExactIn(params) {
-	const { client, poolAddress, account, chainId, tokenIn, amountIn, slippageBps, existingPositionIds, blockNumber } = params;
+	const { client, poolAddress, account, chainId, tokenIn, amountIn, slippageBps, existingPositionIds, builderCode = 0n, blockNumber } = params;
 	try {
 		const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
 		const metaPromise = getBlockMeta({
@@ -6256,7 +6554,7 @@ async function simulateSwapExactIn(params) {
 		const tokenInIndex = resolveTokenIndex(tokenIn, token0, token1);
 		const tokenType = tokenInIndex;
 		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
-		const loanTokenId = buildUniqueLoan(pool.poolId, tokenInIndex, tokenType, pool.currentTick, pool.tickSpacing, existingPositionIds);
+		const { tokenId: creditTokenId, adjustedSize } = buildUniqueCredit(pool.poolId, tokenInIndex, tokenType, pool.currentTick, pool.tickSpacing, existingPositionIds, amountIn);
 		const mintTickLimits = [
 			Number(tickLimitLow),
 			Number(tickLimitHigh),
@@ -6268,7 +6566,7 @@ async function simulateSwapExactIn(params) {
 			0
 		];
 		const tokenOutIndex = tokenInIndex === 0n ? 1n : 0n;
-		const callData = buildSwapCallData(loanTokenId, existingPositionIds, amountIn, mintTickLimits, burnTickLimits);
+		const callData = buildSwapCallData(creditTokenId, existingPositionIds, adjustedSize, mintTickLimits, burnTickLimits, builderCode);
 		const flowResult = await simulateWithTokenFlow({
 			client,
 			poolAddress,
@@ -7434,5 +7732,5 @@ function createEventPoller(params) {
 }
 
 //#endregion
-export { DEFAULT_RECONNECT_CONFIG, REQUIRED_BASE_ERROR_SENTINEL, addPendingPosition, addTrackedChunks, calculateAccountGreeksPure, calculateSpreadWad, checkCollateralAcrossTicks, cleanupStalePendingPositions, clearPendingPositions, clearTrackedChunks, clearTradeHistory, computeV4PoolId, confirmPendingPosition, convertToAssets, convertToShares, createEventPoller, createEventSubscription, createFlowNeutralTokenId, createPoolFormatters, decodePanopticTokenURI, encodePoolKeyBytes, encodeV3PoolKeyBytes, estimateBlockNumbers, estimateCollateralRequired, failPendingPosition, formatBlockNumber, formatBps, formatCompact, formatDatetime, formatDuration, formatDurationSeconds, formatFeeTier, formatGas, formatGwei, formatPoolIdHex, formatRatioPercent, formatTimestamp, formatTimestampLocale, formatTokenIdHex, formatTokenIdShort, formatTxHash, formatUtilization, formatWei, getAccountBuyingPower, getAccountGreeks, getAccountHistory, getAccountPremia, getChunkLiquidities, getChunkSpreads, getClosedPositions, getCollateralSharePrices, getCollateralTotalAssetsBatch, getDeltaHedgeParams, getEnforcedTickLimits, getFactoryConstructMetadata, getFactoryOwnerOf, getFactoryTokenURI, getGuardianUnlockState, getItmAmounts, getMarginBuffer, getMaxPositionSize, getMaxWithdrawable, getNativeTokenPrice, getOpenPositionPreview, getPanopticPoolAddress, getPanopticPoolFromPoolId, getPendingPositions, getPoolDeploymentBlock, getPoolDisplayId, getPoolLiquidities, getPortfolioValue, getPositionChunkData, getPositionEnrichmentData, getPositionsWithPremia, getPriceHistory, getRealizedPnL, getRequiredCreditForITM, getSafeMode, getStreamiaHistory, getSyncStatus, getTokenListId, getTrackedChunks, getTradeHistory, getUniswapFeeHistory, getUniswapV3PoolFromId, getUniswapV3PoolInfo, getUniswapV3PoolLiquidities, getUniswapV4PoolBasicState, getUniswapV4PoolInfo, getUniswapV4PoolKeyFromId, getUniswapV4PoolLiquidities, interpolateBlocks, minePoolAddress, minePoolAddressLocalAsync, multicallRead, optimizeTokenIdRiskPartners, parseBps, parseCollateralLog, parsePoolLog, parseTokenListId, previewDeposit, previewMint, previewRedeem, previewWithdraw, reconstructFromEvents, removeTrackedChunks, resolveBlockNumbers, resolvePanopticPoolFromPoolId, resolveUniswapV4PoolKey, saveClosedPosition, scanChunks, simulateBatchDispatch, simulateClosePosition, simulateDeployNewPool, simulateDeposit, simulateDispatch, simulateForceExercise, simulateLiquidate, simulateSFPMBurn, simulateSFPMMint, simulateSettle, simulateSwapExactIn, simulateSwapExactOut, simulateWithdraw, truncateAddress, watchEvents };
-//# sourceMappingURL=v2-BSV35bpu.js.map
+export { DEFAULT_RECONNECT_CONFIG, REQUIRED_BASE_ERROR_SENTINEL, addPendingPosition, addTrackedChunks, buildTokenShortfallRecoveryDispatch, calculateAccountGreeksPure, calculateSpreadWad, checkCollateralAcrossTicks, cleanupStalePendingPositions, clearPendingPositions, clearTrackedChunks, clearTradeHistory, computeV4PoolId, confirmPendingPosition, convertToAssets, convertToShares, createEventPoller, createEventSubscription, createFlowNeutralTokenId, createPoolFormatters, decodePanopticTokenURI, encodePoolKeyBytes, encodeV3PoolKeyBytes, estimateBlockNumbers, estimateCollateralRequired, failPendingPosition, formatBlockNumber, formatBps, formatCompact, formatDatetime, formatDuration, formatDurationSeconds, formatFeeTier, formatGas, formatGwei, formatPoolIdHex, formatRatioPercent, formatTimestamp, formatTimestampLocale, formatTokenIdHex, formatTokenIdShort, formatTxHash, formatUtilization, formatWei, getAccountBuyingPower, getAccountGreeks, getAccountHistory, getAccountPremia, getChunkLiquidities, getChunkSpreads, getClosedPositions, getCollateralSharePrices, getCollateralTotalAssetsBatch, getDeltaHedgeParams, getEnforcedTickLimits, getFactoryConstructMetadata, getFactoryOwnerOf, getFactoryTokenURI, getGuardianUnlockState, getItmAmounts, getMarginBuffer, getMaxPositionSize, getMaxRedeem, getMaxWithdrawable, getNativeTokenPrice, getNotEnoughTokensError, getOpenPositionPreview, getPanopticPoolAddress, getPanopticPoolFromPoolId, getPendingPositions, getPoolDeploymentBlock, getPoolDisplayId, getPoolLiquidities, getPortfolioValue, getPositionChunkData, getPositionEnrichmentData, getPositionsWithPremia, getPriceHistory, getRealizedPnL, getRequiredCreditForITM, getSafeMode, getStreamiaHistory, getSyncStatus, getTokenListId, getTrackedChunks, getTradeHistory, getUniswapFeeHistory, getUniswapV3PoolFromId, getUniswapV3PoolInfo, getUniswapV3PoolLiquidities, getUniswapV4PoolBasicState, getUniswapV4PoolInfo, getUniswapV4PoolKeyFromId, getUniswapV4PoolLiquidities, interpolateBlocks, minePoolAddress, minePoolAddressLocalAsync, multicallRead, optimizeTokenIdRiskPartners, parseBps, parseCollateralLog, parsePoolLog, parseTokenListId, previewDeposit, previewMint, previewRedeem, previewWithdraw, quoteTokenShortfallRecovery, reconstructFromEvents, removeTrackedChunks, resolveBlockNumbers, resolvePanopticPoolFromPoolId, resolveUniswapV4PoolKey, saveClosedPosition, scanChunks, simulateBatchDispatch, simulateClosePosition, simulateDeployNewPool, simulateDeposit, simulateDispatch, simulateForceExercise, simulateLiquidate, simulateSFPMBurn, simulateSFPMMint, simulateSettle, simulateSwapExactIn, simulateSwapExactOut, simulateWithdraw, truncateAddress, watchEvents };
+//# sourceMappingURL=v2-DHJxPCAp.js.map