@panoptic-eng/sdk 1.0.40 → 1.0.42

package/dist/{v2-DG7qG6di.js → v2-Djy0rVdh.js}

@@ -1,7 +1,7 @@
 import { StateViewAbi, formatTokenAmount, getAccountCollateral, panopticQueryAbi$1 as panopticQueryAbi, parseTokenAmount, readBlockAndAggregate, requireReturnData } from "./irm-SPC2KxLA.js";
-import { AccountInsolventError, ChunkLimitError, DEFAULT_VEGOID, InvalidHistoryRangeError, NotEnoughTokensError, PanopticError, PanopticValidationError, SafeModeError, StaleDataError, StorageDataNotFoundError, UnhealthyPoolError, WrongUniswapPoolError, collateralTrackerV2Abi, decodeLeftRightSigned, decodeLeftRightUnsigned, decodePosition, decodePositionBalance, decodeTickSpacing, getBlockMeta, getClosedPositionsKey, getPendingPositionsKey, getPool, getPoolMetaKey, getPositionMetaKey, getPositionsKey, getTrackedChunksKey, getTrackedPositionIds, jsonSerializer, mintableAfterBuffer, panopticFactoryV3Abi, panopticFactoryV4Abi, panopticGuardianAbi, panopticPoolV2Abi, panopticQueryAbi as panopticQueryAbi$1, parsePanopticError, riskEngineAbi, semiFungiblePositionManagerV3Abi, semiFungiblePositionManagerV4Abi, stateViewAbi, uniswapV3PoolAbi } from "./getTrackedPositionIds-ms3W9dYB.js";
+import { AccountInsolventError, ChunkLimitError, DEFAULT_VEGOID, InvalidHistoryRangeError, LEG_LIMITS, NotEnoughTokensError, PanopticError, PanopticValidationError, SafeModeError, StaleDataError, StorageDataNotFoundError, TOKEN_ID_BITS, UnhealthyPoolError, WrongUniswapPoolError, collateralTrackerV2Abi, decodeLeftRightSigned, decodeLeftRightUnsigned, decodePosition, decodePositionBalance, decodeTickSpacing, getBlockMeta, getClosedPositionsKey, getPendingPositionsKey, getPool, getPoolMetaKey, getPositionMetaKey, getPositionsKey, getTrackedChunksKey, getTrackedPositionIds, jsonSerializer, mintableAfterBuffer, panopticFactoryV3Abi, panopticFactoryV4Abi, panopticGuardianAbi, panopticPoolV2Abi, panopticQueryAbi as panopticQueryAbi$1, parsePanopticError, riskEngineAbi, semiFungiblePositionManagerV3Abi, semiFungiblePositionManagerV4Abi, stateViewAbi, uniswapV3PoolAbi } from "./getTrackedPositionIds-ms3W9dYB.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, buildBatchDispatchArgs, buildUniqueCredit, countLegs, createTokenIdBuilder, decodeAllLegs, decodeTokenId, getPoolTokensForSimulation, loadCheckpoint, resolveTokenIndex, simulateOpenPosition, simulateWithTokenFlow } from "./writes-Xp9Wa8GQ.js";
+import { addLegToTokenId, buildBatchDispatchArgs, buildUniqueCredit, buildUniqueLoan, countLegs, createTokenIdBuilder, decodeAllLegs, decodeTokenId, getCurrentPositionSizes, getPoolTokensForSimulation, loadCheckpoint, resolveTokenIndex, simulateOpenPosition, simulateWithTokenFlow } from "./writes-_gfkBizf.js";
 import { BaseError, ContractFunctionExecutionError, ContractFunctionRevertedError, ExecutionRevertedError, decodeFunctionResult, encodeAbiParameters, encodeFunctionData, getAddress, keccak256, toHex, zeroAddress } from "viem";
 import { multicall } from "viem/actions";
 
@@ -203,6 +203,165 @@ function interpolateBlocks(startBlock, endBlock, points) {
 	return Array.from({ length: points }, (_, i) => startBlock + range * BigInt(i) / BigInt(points - 1));
 }
 
+//#endregion
+//#region src/panoptic/v2/tokenId/deriveUniqueTokenId.ts
+const POOL_ID_MASK$2 = (1n << 64n) - 1n;
+const MAX_LEGS = TOKEN_ID_BITS.MAX_LEGS;
+const MAX_OPTION_RATIO = LEG_LIMITS.MAX_RATIO;
+const Q192$2 = 1n << 192n;
+/**
+* Floor integer square root for bigints (Newton's method). Mirrors the isqrt
+* used in reads/collateralEstimate.ts (buildNeutralLeg).
+*/
+function isqrt$1(value) {
+	if (value < 0n) throw new PanopticError("isqrt of negative number");
+	if (value < 2n) return value;
+	let x = value;
+	let y = x + 1n >> 1n;
+	while (y < x) {
+		x = y;
+		y = x + value / x >> 1n;
+	}
+	return x;
+}
+const DEFAULT_TICK_SPACING = 200n;
+/**
+* Target notional (in wei of the tokenType-side asset) for the appended
+* tiny credit leg. Chosen at 10 wei — small enough to be economically
+* meaningless against any real position size, large enough to safely
+* clear rounding on the SFPM's width-2 internal chunk math without any
+* risk of underflowing to zero (which would revert ChunkHasZeroLiquidity).
+*/
+const TINY_CREDIT_TARGET_NOTIONAL_WEI = 10n;
+/**
+* Pick a signedStrike for the appended width=0 credit leg such that:
+*   1. positionSize · 1.0001^signedStrike ≈ TINY_CREDIT_TARGET_NOTIONAL_WEI
+*      (~10 wei — economically meaningless but comfortably above any
+*      SFPM width-2 chunk rounding);
+*   2. the leg's tick range (SFPM internally treats width=0 as width=2, so
+*      the range is `strike ± tickSpacing`) stays strictly inside
+*      `[MIN_POOL_TICK, MAX_POOL_TICK]` — otherwise the getSqrtRatioAtTick
+*      call reverts with `InvalidTick`.
+*
+* Closed form: `1.0001^signedStrike = target/positionSize`, so
+* `sqrtKrawX96 = isqrt(target · 2^192 / positionSize)` and
+* `signedStrike = sqrtPriceX96ToTick(sqrtKrawX96)`. If the notional-optimal
+* strike falls outside the safe range, we clamp inward. Clamping raises the
+* notional but keeps it << position size for any reasonable strike.
+*/
+function computeTinyCreditSignedStrike(positionSize, tickSpacing) {
+	if (positionSize <= 0n) throw new PanopticError("computeTinyCreditSignedStrike: positionSize must be > 0");
+	const minSafe = MIN_TICK + tickSpacing + 1n;
+	const maxSafe = MAX_TICK - tickSpacing - 1n;
+	let signedStrike;
+	try {
+		const sqrtKrawX96 = isqrt$1(TINY_CREDIT_TARGET_NOTIONAL_WEI * Q192$2 / positionSize);
+		signedStrike = sqrtPriceX96ToTick(sqrtKrawX96);
+	} catch {
+		signedStrike = minSafe;
+	}
+	if (signedStrike < minSafe) return minSafe;
+	if (signedStrike > maxSafe) return maxSafe;
+	return signedStrike;
+}
+/**
+* Assemble the tiny credit leg struct, picking a strike that avoids
+* colliding with any existing width=0 credit leg on the same (asset,
+* tokenType) pair.
+*
+* The encoded strike stored in the tokenId is
+* `asset === 0 ? signedStrike : -signedStrike` (mirrors
+* {@link buildNeutralLeg} in reads/collateralEstimate.ts).
+*/
+function pickUniqueTinyCreditLeg(baseTokenId, legIndex, positionSize, tickSpacing) {
+	const asset = 1n;
+	const tokenType = 0n;
+	const existingLegs = decodeAllLegs(baseTokenId);
+	const maxSafe = MAX_TICK - tickSpacing - 1n;
+	let signedStrike = computeTinyCreditSignedStrike(positionSize, tickSpacing);
+	while (signedStrike <= maxSafe) {
+		const candidate = asset === 0n ? signedStrike : -signedStrike;
+		let collides = false;
+		for (const leg of existingLegs) if (leg.width === 0n && leg.isLong && leg.asset === asset && leg.tokenType === tokenType && leg.strike === candidate) {
+			collides = true;
+			break;
+		}
+		if (!collides) break;
+		signedStrike += 1n;
+	}
+	if (signedStrike > maxSafe) throw new PanopticError("deriveUniqueTokenId: exhausted strike space picking a unique tiny credit leg");
+	const encodedStrike = asset === 0n ? signedStrike : -signedStrike;
+	return {
+		index: legIndex,
+		asset,
+		tokenType,
+		optionRatio: 1n,
+		isLong: 1n,
+		riskPartner: legIndex,
+		strike: encodedStrike,
+		width: 0n
+	};
+}
+function appendTinyCreditLeg(baseTokenId, baseLegCount, positionSize, tickSpacing) {
+	const newLeg = pickUniqueTinyCreditLeg(baseTokenId, baseLegCount, positionSize, tickSpacing);
+	return addLegToTokenId(baseTokenId, newLeg);
+}
+function scaleRatios(baseTokenId, targetPositionSize) {
+	const legs = decodeAllLegs(baseTokenId);
+	const maxRatio = legs.reduce((m, leg) => leg.optionRatio > m ? leg.optionRatio : m, 0n);
+	const N = MAX_OPTION_RATIO / maxRatio;
+	if (N < 2n) throw new PanopticError("deriveUniqueTokenId: cannot derive a unique tokenId — all 4 leg slots used and optionRatios already near the 127 ceiling");
+	const newPositionSize = (targetPositionSize + N - 1n) / N;
+	const poolId = baseTokenId & POOL_ID_MASK$2;
+	let out = poolId;
+	for (const leg of legs) out = addLegToTokenId(out, {
+		index: leg.index,
+		asset: leg.asset,
+		tokenType: leg.tokenType,
+		optionRatio: leg.optionRatio * N,
+		isLong: leg.isLong ? 1n : 0n,
+		riskPartner: leg.riskPartner,
+		strike: leg.strike,
+		width: leg.width
+	});
+	return {
+		newTokenId: out,
+		newPositionSize,
+		effectivePositionSize: newPositionSize * N,
+		strategy: "ratio-scale"
+	};
+}
+/**
+* Derive a tokenId unique from `baseTokenId` for a partial reduction.
+*
+* Prefers a tiny-credit-leg extension (arbitrary new size). Falls back to
+* optionRatio scaling only when the base tokenId already occupies all 4 leg
+* slots.
+*/
+function deriveUniqueTokenId(params) {
+	const { baseTokenId, targetPositionSize, tickSpacing = DEFAULT_TICK_SPACING } = params;
+	if (targetPositionSize <= 0n) throw new PanopticError("deriveUniqueTokenId: targetPositionSize must be > 0");
+	const legCount = countLegs(baseTokenId);
+	if (legCount === 0n) throw new PanopticError("deriveUniqueTokenId: baseTokenId has no legs");
+	if (legCount < MAX_LEGS) {
+		const newTokenId = appendTinyCreditLeg(baseTokenId, legCount, targetPositionSize, tickSpacing);
+		return {
+			newTokenId,
+			newPositionSize: targetPositionSize,
+			effectivePositionSize: targetPositionSize,
+			strategy: "tiny-credit"
+		};
+	}
+	return scaleRatios(baseTokenId, targetPositionSize);
+}
+/**
+* Re-export decoded leg count so callers can gate UI on the strategy that
+* would be chosen (e.g. show a divisibility hint on ratio-scale positions).
+*/
+function planDeriveStrategy(baseTokenId) {
+	return countLegs(baseTokenId) < MAX_LEGS ? "tiny-credit" : "ratio-scale";
+}
+
 //#endregion
 //#region src/panoptic/v2/sfpmSwap/calldata.ts
 /**
@@ -1474,7 +1633,7 @@ async function simulateDispatch(params) {
 
 //#endregion
 //#region src/panoptic/v2/simulations/tokenShortfallRecovery.ts
-const BPS_DENOMINATOR$1 = 10000n;
+const BPS_DENOMINATOR$2 = 10000n;
 const MAX_RECOVERY_QUOTE_ATTEMPTS = 8;
 /**
 * Wrap a dispatch with a temporary credit leg that sources the shortfall.
@@ -1524,7 +1683,7 @@ function getNotEnoughTokensError(error) {
 }
 function maximumAmountIn(estimatedAmountIn, slippageBps) {
 	if (slippageBps < 0n) throw new PanopticError("slippageBps must be non-negative");
-	return (estimatedAmountIn * (BPS_DENOMINATOR$1 + slippageBps) + BPS_DENOMINATOR$1 - 1n) / BPS_DENOMINATOR$1;
+	return (estimatedAmountIn * (BPS_DENOMINATOR$2 + slippageBps) + BPS_DENOMINATOR$2 - 1n) / BPS_DENOMINATOR$2;
 }
 function ceilDiv(numerator, denominator) {
 	return (numerator + denominator - 1n) / denominator;
@@ -1552,10 +1711,10 @@ async function quoteTokenShortfallRecovery(params) {
 		reason: "invalid-shortfall",
 		detail: `requested=${shortfallError.assetsRequested} <= balance=${shortfallError.assetBalance}`
 	};
-	if (params.slippageBps < 0n || params.slippageBps > BPS_DENOMINATOR$1) return {
+	if (params.slippageBps < 0n || params.slippageBps > BPS_DENOMINATOR$2) return {
 		available: false,
 		reason: "invalid-slippage",
-		detail: `slippageBps=${params.slippageBps} is outside [0, ${BPS_DENOMINATOR$1}]`
+		detail: `slippageBps=${params.slippageBps} is outside [0, ${BPS_DENOMINATOR$2}]`
 	};
 	const targetBlockNumber = params.blockNumber ?? await params.client.getBlockNumber();
 	const pool = await getPool({
@@ -1703,8 +1862,9 @@ async function quoteTokenShortfallRecovery(params) {
 			error: new PanopticError("Could not size the prefixed recovery swap")
 		};
 	};
+	let creditOutSize = amountOut;
 	for (let attempt = 0; attempt < MAX_RECOVERY_QUOTE_ATTEMPTS; attempt++) {
-		const credit = buildUniqueCredit(pool.poolId, tokenOutIndex, tokenOutIndex, pool.currentTick, pool.tickSpacing, collisionIds, amountOut);
+		const credit = buildUniqueCredit(pool.poolId, tokenOutIndex, tokenOutIndex, pool.currentTick, pool.tickSpacing, collisionIds, creditOutSize);
 		const recoveredDispatch = buildTokenShortfallRecoveryDispatch({
 			dispatch: params.dispatch,
 			creditTokenId: credit.tokenId,
@@ -1748,10 +1908,14 @@ async function quoteTokenShortfallRecovery(params) {
 		const maxAmountIn = maximumAmountIn(estimatedAmountIn, params.slippageBps);
 		const swapOutput = getOutputAmount(swapSimulation.tokenFlow, tokenOutIndex);
 		const sourceBalance = getBalanceBefore(swapSimulation.tokenFlow, tokenInIndex);
-		if (swapOutput < amountOut || sourceBalance < maxAmountIn) return {
+		if (swapOutput < amountOut) {
+			creditOutSize = swapOutput > 0n ? ceilDiv(creditOutSize * amountOut, swapOutput) + 1n : creditOutSize * 2n;
+			continue;
+		}
+		if (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})`,
+			detail: `source balance ${sourceBalance} < maximumAmountIn ${maxAmountIn} (estimated ${estimatedAmountIn}, slippageBps ${params.slippageBps})`,
 			error: new PanopticError("Insufficient source collateral for the recovery swap")
 		};
 		const recoverySimulation = await simulateDispatch({
@@ -1803,6 +1967,7 @@ async function quoteTokenShortfallRecovery(params) {
 		const decodedShortfall = remainingShortfall.assetsRequested - remainingShortfall.assetBalance;
 		const additionalAmountOut = decodedShortfall > 0n ? decodedShortfall : amountOut;
 		amountOut += additionalAmountOut;
+		creditOutSize = swapOutput > 0n ? ceilDiv(creditOutSize * amountOut, swapOutput) + 1n : creditOutSize * 2n;
 	}
 	return {
 		available: false,
@@ -1829,6 +1994,7 @@ const MAX_EFFECTIVE_LIQUIDITY_LIMIT = 8388607;
 * returned value must be scaled down to the caller's actual `positionSize`.
 */
 const MAX_UINT64$1 = 2n ** 64n - 1n;
+const FP96$1 = 1n << 96n;
 /**
 * `getRequiredBase` returns `type(uint128).max` as an error sentinel (invalid
 * tokenId or reverting `getMargin`). Detect it so we don't scale a garbage value.
@@ -1841,7 +2007,9 @@ const REQUIRED_BASE_ERROR_SENTINEL = 2n ** 128n - 1n;
 * computes the requirement at `type(uint64).max` size and 0% utilization. Since
 * the requirement is linear in size, the raw result is scaled by
 * `positionSize / type(uint64).max` to yield the requirement for the requested
-* size. Returns collateral requirement in terms of token0.
+* size. `PanopticQuery.getRequiredBase` returns the cross-margin requirement in
+* the higher-precision raw token at `atTick`; this function places that amount
+* in the matching `required0` or `required1` field.
 *
 * @param params - The parameters
 * @returns Estimated collateral requirements with block metadata
@@ -1860,7 +2028,7 @@ async function estimateCollateralRequired(params) {
 		});
 		effectiveTick = BigInt(currentTickResult);
 	}
-	const [required0, _meta] = await Promise.all([client.readContract({
+	const [requiredBase, _meta] = await Promise.all([client.readContract({
 		address: queryAddress,
 		abi: panopticQueryAbi,
 		functionName: "getRequiredBase",
@@ -1874,10 +2042,11 @@ async function estimateCollateralRequired(params) {
 		client,
 		blockNumber: targetBlockNumber
 	})]);
-	const scaled0 = required0 >= REQUIRED_BASE_ERROR_SENTINEL ? required0 : required0 * positionSize / MAX_UINT64$1;
+	const scaledRequirement = requiredBase >= REQUIRED_BASE_ERROR_SENTINEL ? requiredBase : requiredBase * positionSize / MAX_UINT64$1;
+	const denominatedInToken0 = tickToSqrtPriceX96(effectiveTick) < FP96$1;
 	return {
-		required0: scaled0,
-		required1: 0n,
+		required0: denominatedInToken0 ? scaledRequirement : 0n,
+		required1: denominatedInToken0 ? 0n : scaledRequirement,
 		_meta
 	};
 }
@@ -5089,7 +5258,9 @@ async function getStreamiaHistory(params) {
 			_meta: _meta$1
 		};
 	}
-	const premiaRequests = blockNumbers.map((bn) => client.readContract({
+	const _meta = params._meta ?? await getBlockMeta({ client });
+	const resolvedBlockNumbers = blockNumbers.map((blockNumber) => blockNumber ?? _meta.blockNumber);
+	const premiaRequests = resolvedBlockNumbers.map((blockNumber) => client.readContract({
 		address: panopticPoolAddress,
 		abi: panopticPoolV2Abi,
 		functionName: "getFullPositionsData",
@@ -5098,18 +5269,36 @@ async function getStreamiaHistory(params) {
 			true,
 			[tokenId]
 		],
-		blockNumber: bn
+		blockNumber
 	}));
-	const uniswapDataPromise = includeUniswapFees && legs.length > 0 ? fetchUniswapFeeData(client, blockNumbers, legs, poolConfig) : void 0;
-	const [premiaResults, uniswapData, _meta] = await Promise.all([
-		Promise.all(premiaRequests),
-		uniswapDataPromise ?? Promise.resolve(void 0),
-		params._meta ? Promise.resolve(params._meta) : getBlockMeta({ client })
-	]);
-	const sortedSettled = settledEvents ? [...settledEvents].sort((a, b) => a.blockNumber < b.blockNumber ? -1 : 1) : [];
+	const uniswapDataPromise = includeUniswapFees && legs.length > 0 ? fetchUniswapFeeData(client, resolvedBlockNumbers, legs, poolConfig) : void 0;
+	const [premiaResults, uniswapData] = await Promise.all([Promise.all(premiaRequests), uniswapDataPromise ?? Promise.resolve(void 0)]);
+	const sortedSettled = settledEvents ? [...settledEvents].sort((a, b) => a.blockNumber === b.blockNumber ? 0 : a.blockNumber < b.blockNumber ? -1 : 1) : [];
 	let settledIdx = 0;
 	let accSettled0 = 0n;
 	let accSettled1 = 0n;
+	const cumulativePremiaByInputIndex = Array.from({ length: blockNumbers.length }, () => ({
+		token0: 0n,
+		token1: 0n
+	}));
+	const chronologicalInputs = resolvedBlockNumbers.map((blockNumber, inputIndex) => ({
+		blockNumber,
+		inputIndex
+	})).sort((a, b) => a.blockNumber === b.blockNumber ? a.inputIndex - b.inputIndex : a.blockNumber < b.blockNumber ? -1 : 1);
+	for (const { blockNumber, inputIndex } of chronologicalInputs) {
+		while (settledIdx < sortedSettled.length && sortedSettled[settledIdx].blockNumber <= blockNumber) {
+			accSettled0 += sortedSettled[settledIdx].settled0;
+			accSettled1 += sortedSettled[settledIdx].settled1;
+			settledIdx++;
+		}
+		const result = premiaResults[inputIndex];
+		const premia0 = (result[0] & MASK_128) - (result[1] & MASK_128);
+		const premia1 = (result[0] >> 128n) - (result[1] >> 128n);
+		cumulativePremiaByInputIndex[inputIndex] = {
+			token0: premia0 + accSettled0,
+			token1: premia1 + accSettled1
+		};
+	}
 	let initialUniswapFees0 = null;
 	let initialUniswapFees1 = null;
 	const snapshots = premiaResults.map((result, i) => {
@@ -5120,14 +5309,8 @@ async function getStreamiaHistory(params) {
 		const short1 = shortPacked >> 128n;
 		const long0 = longPacked & MASK_128;
 		const long1 = longPacked >> 128n;
-		const effectiveBn = bn ?? BigInt(Number.MAX_SAFE_INTEGER);
-		while (settledIdx < sortedSettled.length && sortedSettled[settledIdx].blockNumber <= effectiveBn) {
-			accSettled0 += sortedSettled[settledIdx].settled0;
-			accSettled1 += sortedSettled[settledIdx].settled1;
-			settledIdx++;
-		}
-		const premia0 = short0 - long0 - accSettled0;
-		const premia1 = short1 - long1 - accSettled1;
+		const premia0 = short0 - long0;
+		const premia1 = short1 - long1;
 		let uniswapFees0 = 0n;
 		let uniswapFees1 = 0n;
 		if (uniswapData) {
@@ -5146,6 +5329,7 @@ async function getStreamiaHistory(params) {
 				token0: premia0,
 				token1: premia1
 			},
+			cumulativePanopticPremia: cumulativePremiaByInputIndex[i],
 			uniswapFees: {
 				token0: uniswapFees0,
 				token1: uniswapFees1
@@ -5612,7 +5796,7 @@ const nfpmAbi = [{
 	}],
 	stateMutability: "payable"
 }];
-const MAX_UINT128 = 2n ** 128n - 1n;
+const MAX_UINT128$1 = 2n ** 128n - 1n;
 const MAX_UINT256 = 2n ** 256n - 1n;
 const Q128 = 2n ** 128n;
 /**
@@ -5654,8 +5838,8 @@ async function getUniswapV3LpPositionState(params) {
 			args: [{
 				tokenId,
 				recipient: owner,
-				amount0Max: MAX_UINT128,
-				amount1Max: MAX_UINT128
+				amount0Max: MAX_UINT128$1,
+				amount1Max: MAX_UINT128$1
 			}],
 			account: owner,
 			blockNumber: _meta.blockNumber
@@ -6932,14 +7116,21 @@ const multicallAbi = [{
 * @returns Simulation result with settlement data or error
 */
 async function simulateSettle(params) {
-	const { client, poolAddress, account, positionIdList, tokenId, blockNumber } = params;
+	const { client, poolAddress, account, positionIdList, finalPositionIdList, positionSizes: providedSizes, tokenId, blockNumber } = params;
 	const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
 	const metaPromise = getBlockMeta({
 		client,
 		blockNumber: targetBlockNumber
 	});
 	try {
-		const positionSizes = positionIdList.map(() => 0n);
+		if (providedSizes && providedSizes.length !== positionIdList.length) throw new PanopticError("simulateSettle: positionSizes length must match positionIdList");
+		const positionSizes = providedSizes ?? await getCurrentPositionSizes({
+			client,
+			poolAddress,
+			account,
+			positionIdList,
+			blockNumber: targetBlockNumber
+		});
 		const tickAndSpreadLimits = positionIdList.map(() => [
 			-887272n,
 			887272n,
@@ -6950,7 +7141,7 @@ async function simulateSettle(params) {
 			functionName: "dispatch",
 			args: [
 				positionIdList,
-				positionIdList,
+				finalPositionIdList ?? positionIdList,
 				positionSizes.map((s) => BigInt(s)),
 				tickAndSpreadLimits.map((t) => [
 					Number(t[0]),
@@ -6982,8 +7173,8 @@ async function simulateSettle(params) {
 		});
 		const _meta = await metaPromise;
 		const data = {
-			premiaReceived0: tokenFlow.delta0 > 0n ? tokenFlow.delta0 : 0n,
-			premiaReceived1: tokenFlow.delta1 > 0n ? tokenFlow.delta1 : 0n,
+			premiaReceived0: tokenFlow.delta0,
+			premiaReceived1: tokenFlow.delta1,
 			postCollateral0: tokenFlow.balanceAfter0,
 			postCollateral1: tokenFlow.balanceAfter1,
 			forfeitAmounts
@@ -7495,7 +7686,7 @@ async function simulateSwapExactIn(params) {
 
 //#endregion
 //#region src/panoptic/v2/simulations/oneTokenFlow.ts
-const BPS_DENOMINATOR = 10000n;
+const BPS_DENOMINATOR$1 = 10000n;
 /**
 * Default {@link OneTokenFlowQuoteParams.minSwapRatioBps}: 0.5%.
 *
@@ -7515,7 +7706,7 @@ function abs(value) {
 	return value < 0n ? -value : value;
 }
 function padForSlippage(amount, slippageBps) {
-	return (amount * (BPS_DENOMINATOR + slippageBps) + BPS_DENOMINATOR - 1n) / BPS_DENOMINATOR;
+	return (amount * (BPS_DENOMINATOR$1 + slippageBps) + BPS_DENOMINATOR$1 - 1n) / BPS_DENOMINATOR$1;
 }
 /**
 * Quote a dispatch wrapped so its net flow lands in `targetTokenIndex` only.
@@ -7535,10 +7726,10 @@ async function quoteOneTokenFlow(params) {
 		reason: "invalid-target-token",
 		detail: `targetTokenIndex=${targetTokenIndex} is neither 0 nor 1`
 	};
-	if (params.slippageBps < 0n || params.slippageBps > BPS_DENOMINATOR) return {
+	if (params.slippageBps < 0n || params.slippageBps > BPS_DENOMINATOR$1) return {
 		available: false,
 		reason: "invalid-slippage",
-		detail: `slippageBps=${params.slippageBps} is outside [0, ${BPS_DENOMINATOR}]`
+		detail: `slippageBps=${params.slippageBps} is outside [0, ${BPS_DENOMINATOR$1}]`
 	};
 	const tickLimitLow = params.tickLimitLow ?? MIN_TICK;
 	const tickLimitHigh = params.tickLimitHigh ?? MAX_TICK;
@@ -7646,7 +7837,7 @@ async function quoteOneTokenFlow(params) {
 	}
 	if (baseTargetDelta !== null && minSwapRatioBps > 0n) {
 		const swapInTargetTerms = convertToTokenIndex(swapAmount, otherTokenIndex, targetTokenIndex, pool.sqrtPriceX96);
-		if (swapInTargetTerms * BPS_DENOMINATOR < minSwapRatioBps * abs(baseTargetDelta)) return {
+		if (swapInTargetTerms * BPS_DENOMINATOR$1 < minSwapRatioBps * abs(baseTargetDelta)) return {
 			available: false,
 			reason: "below-threshold",
 			detail: `non-target flow ${swapInTargetTerms} (in target token terms) is below ${minSwapRatioBps}bps of the target flow ${abs(baseTargetDelta)}`
@@ -7738,6 +7929,200 @@ async function quoteOneTokenFlow(params) {
 	};
 }
 
+//#endregion
+//#region src/panoptic/v2/simulations/temporaryLoanRecovery.ts
+const BPS_DENOMINATOR = 10000n;
+const MAX_RECOVERY_ATTEMPTS = 8n;
+const MAX_UINT128 = (1n << 128n) - 1n;
+const LOAN_GROWTH_DENOMINATOR = 20n;
+/**
+* Wrap a dispatch with `loan mint -> user operations -> swapped loan burn`.
+* The repeated tokenId is intentional: the first occurrence mints it and the
+* last occurrence burns it after the user's operations have settled.
+*/
+function buildTemporaryLoanRecoveryDispatch(params) {
+	const low = params.tickLimitLow <= params.tickLimitHigh ? params.tickLimitLow : params.tickLimitHigh;
+	const high = params.tickLimitLow <= params.tickLimitHigh ? params.tickLimitHigh : params.tickLimitLow;
+	return {
+		positionIdList: [
+			params.loanTokenId,
+			...params.dispatch.positionIdList,
+			params.loanTokenId
+		],
+		finalPositionIdList: [...params.dispatch.finalPositionIdList],
+		positionSizes: [
+			params.loanPositionSize,
+			...params.dispatch.positionSizes,
+			0n
+		],
+		tickAndSpreadLimits: [
+			[
+				low,
+				high,
+				0n
+			],
+			...params.dispatch.tickAndSpreadLimits,
+			[
+				high,
+				low,
+				0n
+			]
+		],
+		usePremiaAsCollateral: params.dispatch.usePremiaAsCollateral,
+		builderCode: params.dispatch.builderCode
+	};
+}
+/**
+* Quotes and simulates an atomic temporary loan around a full-close dispatch.
+*
+* @param params - Chain client, account, failed dispatch, shortfall error, and quote limits.
+* @returns An executable quote when recovery succeeds, otherwise a categorized unavailable result.
+* @throws {PanopticError} When the dispatch is not a full close or required RPC reads fail.
+*/
+async function quoteTemporaryLoanRecovery(params) {
+	const initialShortfall = getNotEnoughTokensError(params.error);
+	if (initialShortfall === null) return {
+		available: false,
+		reason: "not-token-shortfall"
+	};
+	let loanAmount = initialShortfall.assetsRequested - initialShortfall.assetBalance;
+	if (loanAmount <= 0n) return {
+		available: false,
+		reason: "invalid-shortfall",
+		detail: `requested=${initialShortfall.assetsRequested} <= balance=${initialShortfall.assetBalance}`
+	};
+	if (params.slippageBps <= 0n || params.slippageBps > BPS_DENOMINATOR) return {
+		available: false,
+		reason: "invalid-slippage",
+		detail: `slippageBps=${params.slippageBps} is outside (0, ${BPS_DENOMINATOR}]`
+	};
+	if (params.dispatch.finalPositionIdList.length !== 0) throw new PanopticError("Temporary-loan recovery requires a full-close dispatch with an empty finalPositionIdList");
+	let targetBlockNumber;
+	try {
+		targetBlockNumber = params.blockNumber ?? await params.client.getBlockNumber();
+	} catch (error) {
+		if (error instanceof PanopticError) throw error;
+		throw new PanopticError("Failed to resolve the block for temporary-loan recovery", error instanceof Error ? error : new Error(String(error)));
+	}
+	let pool;
+	try {
+		pool = await getPool({
+			client: params.client,
+			poolAddress: params.poolAddress,
+			chainId: params.chainId,
+			blockNumber: targetBlockNumber
+		});
+	} catch (error) {
+		if (error instanceof PanopticError) throw error;
+		throw new PanopticError("Failed to load the pool for temporary-loan recovery", error instanceof Error ? error : new Error(String(error)));
+	}
+	const defaultLimits = tickLimits(pool.currentTick, params.slippageBps);
+	const tickLimitLow = params.tickLimitLow ?? defaultLimits.low;
+	const tickLimitHigh = params.tickLimitHigh ?? defaultLimits.high;
+	if (tickLimitLow >= tickLimitHigh) return {
+		available: false,
+		reason: "invalid-tick-limits",
+		detail: `tickLimitLow=${tickLimitLow} >= tickLimitHigh=${tickLimitHigh}`
+	};
+	const token0 = pool.collateralTracker0.token;
+	const token1 = pool.collateralTracker1.token;
+	const tokenIndexFor = (address) => {
+		const normalized = address.toLowerCase();
+		if (normalized === token0.toLowerCase() || normalized === pool.collateralTracker0.address.toLowerCase()) return 0n;
+		if (normalized === token1.toLowerCase() || normalized === pool.collateralTracker1.address.toLowerCase()) return 1n;
+		return null;
+	};
+	const loanTokenIndex = tokenIndexFor(initialShortfall.tokenAddress);
+	if (loanTokenIndex === null) return {
+		available: false,
+		reason: "unsupported-token",
+		detail: `${initialShortfall.tokenAddress} is neither collateral token of ${params.poolAddress}`
+	};
+	const repaymentTokenIndex = loanTokenIndex === 0n ? 1n : 0n;
+	const loanToken = loanTokenIndex === 0n ? token0 : token1;
+	const repaymentToken = repaymentTokenIndex === 0n ? token0 : token1;
+	const collisionIds = Array.from(new Set([
+		...params.existingPositionIds,
+		...params.dispatch.positionIdList,
+		...params.dispatch.finalPositionIdList
+	]));
+	for (let attempt = 0n; attempt < MAX_RECOVERY_ATTEMPTS; attempt += 1n) {
+		if (loanAmount > MAX_UINT128) return {
+			available: false,
+			reason: "recovery-unavailable",
+			detail: `required loan amount ${loanAmount} exceeds uint128`
+		};
+		const loan = buildUniqueLoan(pool.poolId, loanTokenIndex, loanTokenIndex, pool.currentTick, pool.tickSpacing, collisionIds, loanAmount);
+		const recoveredDispatch = buildTemporaryLoanRecoveryDispatch({
+			dispatch: params.dispatch,
+			loanTokenId: loan.tokenId,
+			loanPositionSize: loan.adjustedSize,
+			tickLimitLow,
+			tickLimitHigh
+		});
+		const simulation = await simulateDispatch({
+			client: params.client,
+			poolAddress: params.poolAddress,
+			account: params.account,
+			existingPositionIdList: params.existingPositionIds,
+			...recoveredDispatch,
+			blockNumber: targetBlockNumber
+		});
+		if (simulation.success && simulation.tokenFlow !== void 0) {
+			const tokenFlow = simulation.tokenFlow;
+			return {
+				available: true,
+				quote: {
+					loanToken,
+					repaymentToken,
+					loanTokenIndex,
+					loanAmount,
+					loanPositionSize: loan.adjustedSize,
+					loanTokenId: loan.tokenId,
+					slippageBps: params.slippageBps,
+					netLoanTokenChange: loanTokenIndex === 0n ? tokenFlow.delta0 : tokenFlow.delta1,
+					netRepaymentTokenChange: repaymentTokenIndex === 0n ? tokenFlow.delta0 : tokenFlow.delta1,
+					dispatch: recoveredDispatch,
+					simulation: {
+						...simulation,
+						tokenFlow
+					},
+					tokenFlow,
+					_meta: simulation._meta
+				}
+			};
+		}
+		if (simulation.success) return {
+			available: false,
+			reason: "recovery-unavailable",
+			detail: "temporary-loan simulation returned no token flow"
+		};
+		const shortfall = getNotEnoughTokensError(simulation.error);
+		if (shortfall === null) return {
+			available: false,
+			reason: "recovery-unavailable",
+			detail: `temporary-loan dispatch reverted: ${simulation.error.message}`,
+			error: simulation.error
+		};
+		const shortfallIndex = tokenIndexFor(shortfall.tokenAddress);
+		if (shortfallIndex !== loanTokenIndex) return {
+			available: false,
+			reason: "repayment-token-shortfall",
+			detail: `repayment token ${shortfall.tokenAddress} requested ${shortfall.assetsRequested}, balance ${shortfall.assetBalance}`,
+			error: simulation.error
+		};
+		const residual = shortfall.assetsRequested - shortfall.assetBalance;
+		const geometricGrowth = (loanAmount + LOAN_GROWTH_DENOMINATOR - 1n) / LOAN_GROWTH_DENOMINATOR;
+		loanAmount += residual > geometricGrowth ? residual : geometricGrowth;
+	}
+	return {
+		available: false,
+		reason: "recovery-unavailable",
+		detail: `temporary-loan recovery remained short after ${MAX_RECOVERY_ATTEMPTS} attempts`,
+		error: new PanopticError("Could not size the temporary loan within the quote attempt limit")
+	};
+}
+
 //#endregion
 //#region src/panoptic/v2/abis/poolManager.ts
 /**
@@ -9100,4 +9485,4 @@ function isGasError(error) {
 }
 
 //#endregion
-export { DEFAULT_MIN_SWAP_RATIO_BPS, DEFAULT_RECONNECT_CONFIG, REQUIRED_BASE_ERROR_SENTINEL, addPendingPosition, addTrackedChunks, apportion, assertCanBurn, assertCanForceExercise, assertCanLiquidate, assertCanMint, assertFresh, assertHealthy, assertTradeable, buildCreditWrappedDispatch, buildSfpmSwapCalldata, buildSfpmSwapPlan, buildTokenShortfallRecoveryDispatch, calculateAccountGreeksPure, calculateSpreadWad, checkCollateralAcrossTicks, classifyStrategyGroups, cleanupStalePendingPositions, clearPendingPositions, clearTrackedChunks, clearTradeHistory, collateralRuleKindFor, computeV4PoolId, confirmPendingPosition, convertToAssets, convertToShares, createEventPoller, createEventSubscription, createFlowNeutralTokenId, createPoolFormatters, decodePanopticTokenURI, encodePoolKeyBytes, encodeV3PoolKeyBytes, ensureSfpmV3PoolInitialized, estimateBlockNumbers, estimateCollateralBreakdown, estimateCollateralRequired, failPendingPosition, feesFromFeeGrowthDelta, fetchSfpmV3PoolId, 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, getPoolDisplayId, getPoolLiquidities, getPortfolioValue, getPositionChunkData, getPositionEnrichmentData, getPositionsWithPremia, getPriceHistory, getRealizedPnL, getRequiredCreditForITM, getSafeMode, getStreamiaHistory, getSyncStatus, getTokenListId, getTrackedChunks, getTradeHistory, getUniswapFeeHistory, getUniswapV3LpPositionState, getUniswapV3PoolFromId, getUniswapV3PoolInfo, getUniswapV3PoolLiquidities, getUniswapV4LpPositionState, getUniswapV4PoolBasicState, getUniswapV4PoolInfo, getUniswapV4PoolKeyFromId, getUniswapV4PoolLiquidities, interpolateBlocks, isGasError, isNonceError, isRetryableRpcError, isolateGroupTokenId, minePoolAddress, minePoolAddressLocalAsync, multicallRead, optimizeTokenIdRiskPartners, parseBps, parseCollateralLog, parsePoolLog, parseTokenListId, previewDeposit, previewMint, previewRedeem, previewWithdraw, quoteOneTokenFlow, quoteSfpmSwap, quoteTokenShortfallRecovery, removeTrackedChunks, resolveBlockNumbers, resolvePanopticPoolFromPoolId, resolveUniswapV4PoolKey, saveClosedPosition, scanChunks, simulateBatchDispatch, simulateClosePosition, simulateDeployNewPool, simulateDeposit, simulateDispatch, simulateForceExercise, simulateLiquidate, simulateSFPMBurn, simulateSFPMMint, simulateSettle, simulateSwapExactIn, simulateSwapExactOut, simulateWithdraw, slippageBpsToTickDistance, truncateAddress, watchEvents };
+export { DEFAULT_MIN_SWAP_RATIO_BPS, DEFAULT_RECONNECT_CONFIG, REQUIRED_BASE_ERROR_SENTINEL, addPendingPosition, addTrackedChunks, apportion, assertCanBurn, assertCanForceExercise, assertCanLiquidate, assertCanMint, assertFresh, assertHealthy, assertTradeable, buildCreditWrappedDispatch, buildSfpmSwapCalldata, buildSfpmSwapPlan, buildTemporaryLoanRecoveryDispatch, buildTokenShortfallRecoveryDispatch, calculateAccountGreeksPure, calculateSpreadWad, checkCollateralAcrossTicks, classifyStrategyGroups, cleanupStalePendingPositions, clearPendingPositions, clearTrackedChunks, clearTradeHistory, collateralRuleKindFor, computeV4PoolId, confirmPendingPosition, convertToAssets, convertToShares, createEventPoller, createEventSubscription, createFlowNeutralTokenId, createPoolFormatters, decodePanopticTokenURI, deriveUniqueTokenId, encodePoolKeyBytes, encodeV3PoolKeyBytes, ensureSfpmV3PoolInitialized, estimateBlockNumbers, estimateCollateralBreakdown, estimateCollateralRequired, failPendingPosition, feesFromFeeGrowthDelta, fetchSfpmV3PoolId, 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, getPoolDisplayId, getPoolLiquidities, getPortfolioValue, getPositionChunkData, getPositionEnrichmentData, getPositionsWithPremia, getPriceHistory, getRealizedPnL, getRequiredCreditForITM, getSafeMode, getStreamiaHistory, getSyncStatus, getTokenListId, getTrackedChunks, getTradeHistory, getUniswapFeeHistory, getUniswapV3LpPositionState, getUniswapV3PoolFromId, getUniswapV3PoolInfo, getUniswapV3PoolLiquidities, getUniswapV4LpPositionState, getUniswapV4PoolBasicState, getUniswapV4PoolInfo, getUniswapV4PoolKeyFromId, getUniswapV4PoolLiquidities, interpolateBlocks, isGasError, isNonceError, isRetryableRpcError, isolateGroupTokenId, minePoolAddress, minePoolAddressLocalAsync, multicallRead, optimizeTokenIdRiskPartners, parseBps, parseCollateralLog, parsePoolLog, parseTokenListId, planDeriveStrategy, previewDeposit, previewMint, previewRedeem, previewWithdraw, quoteOneTokenFlow, quoteSfpmSwap, quoteTemporaryLoanRecovery, quoteTokenShortfallRecovery, removeTrackedChunks, resolveBlockNumbers, resolvePanopticPoolFromPoolId, resolveUniswapV4PoolKey, saveClosedPosition, scanChunks, simulateBatchDispatch, simulateClosePosition, simulateDeployNewPool, simulateDeposit, simulateDispatch, simulateForceExercise, simulateLiquidate, simulateSFPMBurn, simulateSFPMMint, simulateSettle, simulateSwapExactIn, simulateSwapExactOut, simulateWithdraw, slippageBpsToTickDistance, truncateAddress, watchEvents };