@panoptic-eng/sdk 1.0.67 → 1.0.69

package/dist/{router-BW6TqwOO.js → router-ChMhfTqT.js}

@@ -1,8 +1,8 @@
 import { StateViewAbi } from "./StateView-q4yMpBY6.js";
-import { PanopticError, getBlockMeta, getPoolMetadata, stateViewAbi, submitWrite, uniswapV3PoolAbi } from "./rates-BHS-Qiu7.js";
-import { tickToSqrtPriceX96 } from "./greeks-CGtgLUyh.js";
-import { decodeAllLegs, decodeTokenId } from "./writes-CG612Vuk.js";
-import { BaseError, ContractFunctionRevertedError, ExecutionRevertedError, encodeAbiParameters, encodeFunctionData, encodePacked, isAddressEqual, toHex, zeroAddress } from "viem";
+import { PanopticError, getBlockMeta, getPool, getPoolMetadata, stateViewAbi, submitWrite, uniswapV3PoolAbi } from "./rates-B-eRYOTS.js";
+import { getLegLiquidityRange, tickToSqrtPriceX96 } from "./greeks-DNPP24KL.js";
+import { decodeAllLegs, decodeTokenId } from "./writes-D53wWDT-.js";
+import { BaseError, ContractFunctionRevertedError, ExecutionRevertedError, encodeAbiParameters, encodeFunctionData, encodePacked, erc20Abi, isAddressEqual, maxUint256, toHex, zeroAddress } from "viem";
 import Decimal from "decimal.js";
 
 //#region src/panoptic/v2/reads/priceHistory.ts
@@ -424,14 +424,7 @@ function preparePositionGamma({ tokenId, positionSize, quoteIsToken0, quoteDecim
 	const decoded = decodeTokenId(tokenId);
 	const chunks = decoded.legs.flatMap((leg) => {
 		if (leg.width === 0n) return [];
-		const width = leg.width * decoded.tickSpacing;
-		const lowerTick = leg.strike - width / 2n;
-		const upperTick = leg.strike + (width + 1n) / 2n;
-		if (lowerTick < -887272n || upperTick > 887272n || lowerTick >= upperTick) throw new RangeError("Invalid position range");
-		const lower = tickToSqrtPriceX96(lowerTick);
-		const upper = tickToSqrtPriceX96(upperTick);
-		const amount = positionSize * leg.optionRatio;
-		const liquidity = leg.asset === 0n ? amount * (lower * upper / Q96) / (upper - lower) : amount * Q96 / (upper - lower);
+		const { lowerTick, upperTick, liquidity } = getLegLiquidityRange(leg, positionSize, decoded.tickSpacing);
 		if (liquidity >= 1n << 128n) throw new RangeError("Liquidity exceeds uint128");
 		return [{
 			lowerTick: Number(lowerTick),
@@ -675,7 +668,7 @@ const V3_SWAP_EXACT_OUT = 1;
 * `msg.sender` (the `execute` caller). Uniswap `Constants.MSG_SENDER`.
 */
 const MSG_SENDER = "0x0000000000000000000000000000000000000001";
-const UINT128_MAX$1 = (1n << 128n) - 1n;
+const UINT128_MAX$4 = (1n << 128n) - 1n;
 const v3ExactInInputAbi = [
 	{
 		name: "recipient",
@@ -698,8 +691,8 @@ const v3ExactInInputAbi = [
 		type: "bool"
 	}
 ];
-function assertUint128(amount) {
-	if (amount < 0n || amount > UINT128_MAX$1) throw new AmountExceedsUint128Error(amount);
+function assertUint128$1(amount) {
+	if (amount < 0n || amount > UINT128_MAX$4) throw new AmountExceedsUint128Error(amount);
 }
 /**
 * Encode the packed v3 single-hop path `tokenIn ++ fee(uint24) ++ tokenOut`.
@@ -723,8 +716,8 @@ function encodeV3Path(tokenIn, fee, tokenOut) {
 function buildV3SwapExecuteArgs(args) {
 	const { tokenIn, tokenOut, fee, amountIn, amountOutMinimum, deadline } = args;
 	if (tokenIn === zeroAddress || tokenOut === zeroAddress) throw new PanopticError("native ETH is not supported by the v3 exact-in router builder");
-	assertUint128(amountIn);
-	assertUint128(amountOutMinimum);
+	assertUint128$1(amountIn);
+	assertUint128$1(amountOutMinimum);
 	const path = encodeV3Path(tokenIn, fee, tokenOut);
 	const input = encodeAbiParameters(v3ExactInInputAbi, [
 		MSG_SENDER,
@@ -788,8 +781,8 @@ const v3ExactOutInputAbi = [
 function buildV3ExactOutSwapExecuteArgs(args) {
 	const { tokenIn, tokenOut, fee, amountOut, amountInMaximum, deadline } = args;
 	if (tokenIn === zeroAddress || tokenOut === zeroAddress) throw new PanopticError("native ETH is not supported by the v3 exact-out router builder");
-	assertUint128(amountOut);
-	assertUint128(amountInMaximum);
+	assertUint128$1(amountOut);
+	assertUint128$1(amountInMaximum);
 	const path = encodeV3Path(tokenOut, fee, tokenIn);
 	const input = encodeAbiParameters(v3ExactOutInputAbi, [
 		MSG_SENDER,
@@ -930,8 +923,8 @@ const quoterV2Abi = [{
 
 //#endregion
 //#region src/uniswap/v3/router/quote.ts
-const BPS_DENOMINATOR = 10000n;
-const UINT128_MAX = (1n << 128n) - 1n;
+const BPS_DENOMINATOR$2 = 10000n;
+const UINT128_MAX$3 = (1n << 128n) - 1n;
 /**
 * Quote an exact-in v3 swap. Returns `null` when the quote reverts (e.g. the
 * pool does not exist / has no liquidity) so callers can skip that pool when
@@ -939,8 +932,8 @@ const UINT128_MAX = (1n << 128n) - 1n;
 */
 async function quoteV3ExactIn(params) {
 	const { client, chainId, tokenIn, tokenOut, fee, amountIn, slippageBps, blockNumber } = params;
-	if (amountIn < 0n || amountIn > UINT128_MAX) throw new PanopticError(`amountIn ${amountIn} exceeds uint128 maximum`);
-	assertSlippageBps(slippageBps);
+	if (amountIn < 0n || amountIn > UINT128_MAX$3) throw new PanopticError(`amountIn ${amountIn} exceeds uint128 maximum`);
+	assertSlippageBps$1(slippageBps);
 	const { quoterV2 } = getUniswapV3Addresses(chainId, params.addresses);
 	try {
 		const { result } = await client.simulateContract({
@@ -957,14 +950,14 @@ async function quoteV3ExactIn(params) {
 			}]
 		});
 		const [amountOut, , , gasEstimate] = result;
-		const amountOutMinimum = amountOut * (BPS_DENOMINATOR - slippageBps) / BPS_DENOMINATOR;
+		const amountOutMinimum = amountOut * (BPS_DENOMINATOR$2 - slippageBps) / BPS_DENOMINATOR$2;
 		return {
 			amountOut,
 			amountOutMinimum,
 			gasEstimate
 		};
 	} catch (err) {
-		if (isRevert(err)) return null;
+		if (isRevert$1(err)) return null;
 		throw err;
 	}
 }
@@ -973,8 +966,8 @@ async function quoteV3ExactIn(params) {
 */
 async function quoteV3ExactOut(params) {
 	const { client, chainId, tokenIn, tokenOut, fee, amountOut, slippageBps, blockNumber } = params;
-	if (amountOut < 0n || amountOut > UINT128_MAX) throw new PanopticError(`amountOut ${amountOut} exceeds uint128 maximum`);
-	assertSlippageBps(slippageBps);
+	if (amountOut < 0n || amountOut > UINT128_MAX$3) throw new PanopticError(`amountOut ${amountOut} exceeds uint128 maximum`);
+	assertSlippageBps$1(slippageBps);
 	const { quoterV2 } = getUniswapV3Addresses(chainId, params.addresses);
 	try {
 		const { result } = await client.simulateContract({
@@ -991,21 +984,21 @@ async function quoteV3ExactOut(params) {
 			}]
 		});
 		const [amountIn, , , gasEstimate] = result;
-		const amountInMaximum = (amountIn * (BPS_DENOMINATOR + slippageBps) + BPS_DENOMINATOR - 1n) / BPS_DENOMINATOR;
+		const amountInMaximum = (amountIn * (BPS_DENOMINATOR$2 + slippageBps) + BPS_DENOMINATOR$2 - 1n) / BPS_DENOMINATOR$2;
 		return {
 			amountIn,
 			amountInMaximum,
 			gasEstimate
 		};
 	} catch (err) {
-		if (isRevert(err)) return null;
+		if (isRevert$1(err)) return null;
 		throw err;
 	}
 }
-function assertSlippageBps(slippageBps) {
-	if (slippageBps < 0n || slippageBps > BPS_DENOMINATOR) throw new PanopticError(`invalid slippageBps ${slippageBps}, must be 0..10000`);
+function assertSlippageBps$1(slippageBps) {
+	if (slippageBps < 0n || slippageBps > BPS_DENOMINATOR$2) throw new PanopticError(`invalid slippageBps ${slippageBps}, must be 0..10000`);
 }
-function isRevert(err) {
+function isRevert$1(err) {
 	return err instanceof BaseError && err.walk((e) => e instanceof ContractFunctionRevertedError) instanceof ContractFunctionRevertedError;
 }
 
@@ -1032,7 +1025,7 @@ async function resolveV3SwapRoute(params) {
 
 //#endregion
 //#region src/uniswap/v3/router/quoteViaRouter.ts
-const FALLBACK_META = {
+const FALLBACK_META$1 = {
 	blockNumber: 0n,
 	blockTimestamp: 0n,
 	blockHash: "0x0"
@@ -1080,7 +1073,7 @@ async function quoteSwapExactInViaV3Router(params) {
 		return {
 			success: false,
 			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Quote failed", error instanceof Error ? error : void 0),
-			_meta: FALLBACK_META
+			_meta: FALLBACK_META$1
 		};
 	}
 }
@@ -1127,7 +1120,7 @@ async function quoteSwapExactOutViaV3Router(params) {
 		return {
 			success: false,
 			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Quote failed", error instanceof Error ? error : void 0),
-			_meta: FALLBACK_META
+			_meta: FALLBACK_META$1
 		};
 	}
 }
@@ -1183,7 +1176,7 @@ function getUniswapV4Addresses(chainId, overrides) {
 
 //#endregion
 //#region src/uniswap/v3/router/swap.ts
-const DEFAULT_DEADLINE_SECONDS = 1800n;
+const DEFAULT_DEADLINE_SECONDS$1 = 1800n;
 async function swapExactInViaV3Router(params) {
 	const { client, walletClient, account, poolAddress, chainId, tokenIn, amountIn, slippageBps, deadline, recipient, txOverrides, addresses } = params;
 	if (recipient !== void 0 && !isAddressEqual(recipient, account)) throw new PanopticError("Custom recipient is not supported yet; output goes to the sender");
@@ -1204,7 +1197,7 @@ async function swapExactInViaV3Router(params) {
 		addresses
 	});
 	if (!quote) throw new PanopticError("v3 quote failed (pool may have no liquidity)");
-	const resolvedDeadline = deadline ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_DEADLINE_SECONDS;
+	const resolvedDeadline = deadline ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_DEADLINE_SECONDS$1;
 	const { args, value } = buildV3SwapExecuteArgs({
 		tokenIn: route.tokenIn,
 		tokenOut: route.tokenOut,
@@ -1245,7 +1238,7 @@ async function swapExactOutViaV3Router(params) {
 		addresses
 	});
 	if (!quote) throw new PanopticError("v3 quote failed (pool may have no liquidity)");
-	const resolvedDeadline = deadline ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_DEADLINE_SECONDS;
+	const resolvedDeadline = deadline ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_DEADLINE_SECONDS$1;
 	const { args, value } = buildV3ExactOutSwapExecuteArgs({
 		tokenIn: route.tokenIn,
 		tokenOut: route.tokenOut,
@@ -1268,4 +1261,941 @@ async function swapExactOutViaV3Router(params) {
 }
 
 //#endregion
-export { AmountExceedsUint128Error, InvalidSwapTokenError, MSG_SENDER, MissingSweepRecipientError, PERMIT2_ADDRESS, QuoterUnavailableError, UNISWAP_V3_ADDRESSES, UNISWAP_V4_ADDRESSES, UnsupportedChainError, V3_SWAP_EXACT_IN, V3_SWAP_EXACT_OUT, buildV3ExactOutSwapExecuteArgs, buildV3ExactOutSwapExecuteCalldata, buildV3SwapExecuteArgs, buildV3SwapExecuteCalldata, calculatePositionVolatilityMetrics, encodeV3Path, feesFromFeeGrowthDelta, getLpDepositAmounts, getLpDepositBreakdown, getLpFundingDeposit, getLpPositionFunding, getMaxLpPositionSize, getPriceHistory, getUnhedgedLpRanges, getUniswapV3Addresses, getUniswapV3LpPositionState, getUniswapV4Addresses, getUniswapV4LpPositionState, prepareLiquidityGamma, preparePositionGamma, quoteSwapExactInViaV3Router, quoteSwapExactOutViaV3Router, quoteV3ExactIn, quoteV3ExactOut, resolveV3SwapRoute, swapExactInViaV3Router, swapExactOutViaV3Router, universalRouterAbi, valuePositionAccrual };
+//#region src/uniswap/v4/router/encodeSwap.ts
+/** Universal Router command byte for a v4 swap. */
+const V4_SWAP = 16;
+/** v4 action: exact-in single-hop swap. */
+const SWAP_EXACT_IN_SINGLE = 6;
+/** v4 action: pay all of the input currency owed. */
+const SETTLE_ALL = 12;
+/** v4 action: take all of the output currency owed. */
+const TAKE_ALL = 15;
+/** v4 action: take an output currency to an explicit recipient. */
+const TAKE = 14;
+/** v4 action: exact-out single-hop swap. */
+const SWAP_EXACT_OUT_SINGLE = 8;
+/** Universal Router command: sweep the router's token balance to a recipient. */
+const SWEEP = 4;
+/** v4 sentinel: take the full positive currency delta (used with TAKE). */
+const OPEN_DELTA = 0n;
+const UINT128_MAX$2 = (1n << 128n) - 1n;
+const poolKeyComponents = [
+	{
+		name: "currency0",
+		type: "address"
+	},
+	{
+		name: "currency1",
+		type: "address"
+	},
+	{
+		name: "fee",
+		type: "uint24"
+	},
+	{
+		name: "tickSpacing",
+		type: "int24"
+	},
+	{
+		name: "hooks",
+		type: "address"
+	}
+];
+const exactInputSingleParamsAbi = [{
+	type: "tuple",
+	components: [
+		{
+			name: "poolKey",
+			type: "tuple",
+			components: poolKeyComponents
+		},
+		{
+			name: "zeroForOne",
+			type: "bool"
+		},
+		{
+			name: "amountIn",
+			type: "uint128"
+		},
+		{
+			name: "amountOutMinimum",
+			type: "uint128"
+		},
+		{
+			name: "hookData",
+			type: "bytes"
+		}
+	]
+}];
+const exactOutputSingleParamsAbi = [{
+	type: "tuple",
+	components: [
+		{
+			name: "poolKey",
+			type: "tuple",
+			components: poolKeyComponents
+		},
+		{
+			name: "zeroForOne",
+			type: "bool"
+		},
+		{
+			name: "amountOut",
+			type: "uint128"
+		},
+		{
+			name: "amountInMaximum",
+			type: "uint128"
+		},
+		{
+			name: "hookData",
+			type: "bytes"
+		}
+	]
+}];
+const currencyAmountAbi = [{
+	name: "currency",
+	type: "address"
+}, {
+	name: "amount",
+	type: "uint256"
+}];
+const takeToRecipientAbi = [
+	{
+		name: "currency",
+		type: "address"
+	},
+	{
+		name: "recipient",
+		type: "address"
+	},
+	{
+		name: "amount",
+		type: "uint256"
+	}
+];
+const sweepParamsAbi = [
+	{
+		name: "token",
+		type: "address"
+	},
+	{
+		name: "recipient",
+		type: "address"
+	},
+	{
+		name: "amountMin",
+		type: "uint256"
+	}
+];
+function assertUint128(amount) {
+	if (amount < 0n || amount > UINT128_MAX$2) throw new AmountExceedsUint128Error(amount);
+}
+/**
+* Encode the input for a Universal Router `SWEEP` command that forwards the
+* router's full native-ETH balance (above `amountMin = 0`) to `recipient`.
+*/
+function encodeEthSweepInput(recipient) {
+	return encodeAbiParameters(sweepParamsAbi, [
+		zeroAddress,
+		recipient,
+		0n
+	]);
+}
+/**
+* Build the output-take v4 action byte + param.
+*
+* Native-ETH output is taken with the explicit-recipient `TAKE` action so the
+* router forwards the ETH straight to `recipient` (the implicit-`msgSender`
+* `TAKE_ALL` leaves native ETH held by the router). ERC20 output uses
+* `TAKE_ALL`, which already credits the caller.
+*
+* @param nativeAmount - TAKE amount for native-ETH output: `OPEN_DELTA` (0) to
+*   take the full credit (exact-in, protected by the swap's min) or the exact
+*   output (exact-out).
+* @param erc20Amount - TAKE_ALL min/amount for ERC20 output: `amountOutMinimum`
+*   (exact-in) or the exact output (exact-out).
+*/
+function buildOutputTake(tokenOut, recipient, nativeAmount, erc20Amount) {
+	if (tokenOut === zeroAddress) {
+		if (recipient === void 0) throw new MissingSweepRecipientError();
+		return {
+			action: TAKE,
+			param: encodeAbiParameters(takeToRecipientAbi, [
+				zeroAddress,
+				recipient,
+				nativeAmount
+			])
+		};
+	}
+	return {
+		action: TAKE_ALL,
+		param: encodeAbiParameters(currencyAmountAbi, [tokenOut, erc20Amount])
+	};
+}
+/**
+* Build the typed `execute(...)` args + msg.value for an exact-in single-hop v4
+* swap. Use this when submitting via viem (`writeContract` / `submitWrite`).
+*
+* When `tokenOut` is native ETH the explicit-recipient `TAKE` action forwards
+* the bought ETH to `recipient` (no trailing SWEEP is needed for exact-in).
+*
+* @returns `args` ready to spread into `execute` and the ETH `value` to send
+*   (= `amountIn` for native-ETH input, otherwise `0n`).
+*/
+function buildV4SwapExecuteArgs(args) {
+	const { poolKey, zeroForOne, amountIn, amountOutMinimum, tokenIn, tokenOut, deadline, recipient, hookData = "0x" } = args;
+	assertUint128(amountIn);
+	assertUint128(amountOutMinimum);
+	const swapParam = encodeAbiParameters(exactInputSingleParamsAbi, [{
+		poolKey: {
+			currency0: poolKey.currency0,
+			currency1: poolKey.currency1,
+			fee: Number(poolKey.fee),
+			tickSpacing: Number(poolKey.tickSpacing),
+			hooks: poolKey.hooks
+		},
+		zeroForOne,
+		amountIn,
+		amountOutMinimum,
+		hookData
+	}]);
+	const settleParam = encodeAbiParameters(currencyAmountAbi, [tokenIn, amountIn]);
+	const take = buildOutputTake(tokenOut, recipient, OPEN_DELTA, amountOutMinimum);
+	const actions = encodePacked([
+		"uint8",
+		"uint8",
+		"uint8"
+	], [
+		SWAP_EXACT_IN_SINGLE,
+		SETTLE_ALL,
+		take.action
+	]);
+	const v4Input = encodeAbiParameters([{
+		name: "actions",
+		type: "bytes"
+	}, {
+		name: "params",
+		type: "bytes[]"
+	}], [actions, [
+		swapParam,
+		settleParam,
+		take.param
+	]]);
+	const commands = encodePacked(["uint8"], [V4_SWAP]);
+	const value = tokenIn === zeroAddress ? amountIn : 0n;
+	return {
+		args: [
+			commands,
+			[v4Input],
+			deadline
+		],
+		value
+	};
+}
+/**
+* Build the `execute(commands, inputs, deadline)` calldata + msg.value for an
+* exact-in single-hop v4 swap.
+*
+* @returns The encoded calldata and the ETH `value` to send.
+*/
+function buildV4SwapExecuteCalldata(args) {
+	const { args: executeArgs, value } = buildV4SwapExecuteArgs(args);
+	const data = encodeFunctionData({
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args: executeArgs
+	});
+	return {
+		data,
+		value
+	};
+}
+/**
+* Build the typed `execute(...)` args + msg.value for an exact-out single-hop v4
+* swap. Use this when submitting via viem (`writeContract` / `submitWrite`).
+*
+* For native-ETH input, `value` is `amountInMaximum` (an overpay) and a trailing
+* `SWEEP` action refunds the unused ETH to `recipient`. For ERC20 input, Permit2
+* pulls only the settled amount, so no SWEEP is appended and `value` is `0n`.
+*
+* @returns `args` ready to spread into `execute` and the ETH `value` to send.
+*/
+function buildV4ExactOutSwapExecuteArgs(args) {
+	const { poolKey, zeroForOne, amountOut, amountInMaximum, tokenIn, tokenOut, deadline, recipient, hookData = "0x" } = args;
+	assertUint128(amountOut);
+	assertUint128(amountInMaximum);
+	const swapParam = encodeAbiParameters(exactOutputSingleParamsAbi, [{
+		poolKey: {
+			currency0: poolKey.currency0,
+			currency1: poolKey.currency1,
+			fee: Number(poolKey.fee),
+			tickSpacing: Number(poolKey.tickSpacing),
+			hooks: poolKey.hooks
+		},
+		zeroForOne,
+		amountOut,
+		amountInMaximum,
+		hookData
+	}]);
+	const settleParam = encodeAbiParameters(currencyAmountAbi, [tokenIn, amountInMaximum]);
+	const take = buildOutputTake(tokenOut, recipient, amountOut, amountOut);
+	const actions = encodePacked([
+		"uint8",
+		"uint8",
+		"uint8"
+	], [
+		SWAP_EXACT_OUT_SINGLE,
+		SETTLE_ALL,
+		take.action
+	]);
+	const v4Input = encodeAbiParameters([{
+		name: "actions",
+		type: "bytes"
+	}, {
+		name: "params",
+		type: "bytes[]"
+	}], [actions, [
+		swapParam,
+		settleParam,
+		take.param
+	]]);
+	const isNativeIn = tokenIn === zeroAddress;
+	const commandList = [V4_SWAP];
+	const inputs = [v4Input];
+	if (isNativeIn) {
+		commandList.push(SWEEP);
+		inputs.push(encodeEthSweepInput(recipient));
+	}
+	const commands = encodePacked(commandList.map(() => "uint8"), commandList);
+	const value = isNativeIn ? amountInMaximum : 0n;
+	return {
+		args: [
+			commands,
+			inputs,
+			deadline
+		],
+		value
+	};
+}
+/**
+* Build the `execute(commands, inputs, deadline)` calldata + msg.value for an
+* exact-out single-hop v4 swap.
+*
+* @returns The encoded calldata and the ETH `value` to send.
+*/
+function buildV4ExactOutSwapExecuteCalldata(args) {
+	const { args: executeArgs, value } = buildV4ExactOutSwapExecuteArgs(args);
+	const data = encodeFunctionData({
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args: executeArgs
+	});
+	return {
+		data,
+		value
+	};
+}
+
+//#endregion
+//#region src/uniswap/v4/abis/permit2.ts
+/**
+* Minimal Permit2 ABI (`IAllowanceTransfer` subset: `approve` + `allowance`).
+* @module uniswap/v4/abis/permit2
+*/
+const permit2Abi = [{
+	type: "function",
+	name: "approve",
+	stateMutability: "nonpayable",
+	inputs: [
+		{
+			name: "token",
+			type: "address"
+		},
+		{
+			name: "spender",
+			type: "address"
+		},
+		{
+			name: "amount",
+			type: "uint160"
+		},
+		{
+			name: "expiration",
+			type: "uint48"
+		}
+	],
+	outputs: []
+}, {
+	type: "function",
+	name: "allowance",
+	stateMutability: "view",
+	inputs: [
+		{
+			name: "user",
+			type: "address"
+		},
+		{
+			name: "token",
+			type: "address"
+		},
+		{
+			name: "spender",
+			type: "address"
+		}
+	],
+	outputs: [
+		{
+			name: "amount",
+			type: "uint160"
+		},
+		{
+			name: "expiration",
+			type: "uint48"
+		},
+		{
+			name: "nonce",
+			type: "uint48"
+		}
+	]
+}];
+
+//#endregion
+//#region src/uniswap/v4/router/permit2.ts
+/** uint160 max — the largest Permit2 allowance amount. */
+const UINT160_MAX = (1n << 160n) - 1n;
+/** Default Permit2 allowance expiration window (30 days). */
+const DEFAULT_EXPIRATION_SECONDS = 2592000n;
+/** uint48 max — the largest Permit2 expiration. */
+const UINT48_MAX = (1n << 48n) - 1n;
+/**
+* Check whether the ERC20 → Permit2 → Universal Router allowance chain is
+* sufficient for an exact-in swap of `amount`.
+*/
+async function checkRouterApproval(params) {
+	const { client, chainId, tokenIn, owner, amount, addresses } = params;
+	const { permit2, universalRouter } = getUniswapV4Addresses(chainId, addresses);
+	const [erc20Allowance, permit2Allowance, blockMeta] = await Promise.all([
+		client.readContract({
+			address: tokenIn,
+			abi: erc20Abi,
+			functionName: "allowance",
+			args: [owner, permit2]
+		}),
+		client.readContract({
+			address: permit2,
+			abi: permit2Abi,
+			functionName: "allowance",
+			args: [
+				owner,
+				tokenIn,
+				universalRouter
+			]
+		}),
+		getBlockMeta({ client })
+	]);
+	const [permit2Amount, permit2Expiration] = permit2Allowance;
+	const needsErc20Approval = erc20Allowance < amount;
+	const needsPermit2Approval = permit2Amount < amount || BigInt(permit2Expiration) <= blockMeta.blockTimestamp;
+	return {
+		needsErc20Approval,
+		needsPermit2Approval,
+		erc20Allowance,
+		permit2Amount,
+		permit2Expiration: BigInt(permit2Expiration)
+	};
+}
+/**
+* Step 1: approve the ERC20 token to Permit2 (defaults to unlimited).
+*/
+async function approveErc20ForPermit2(params) {
+	const { client, walletClient, account, chainId, tokenIn, amount = maxUint256, txOverrides, addresses } = params;
+	const { permit2 } = getUniswapV4Addresses(chainId, addresses);
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: tokenIn,
+		abi: erc20Abi,
+		functionName: "approve",
+		args: [permit2, amount],
+		txOverrides
+	});
+}
+/**
+* Step 1 (and wait): approve the ERC20 token to Permit2.
+*/
+async function approveErc20ForPermit2AndWait(params) {
+	const result = await approveErc20ForPermit2(params);
+	return result.wait();
+}
+/**
+* Step 2: approve the Universal Router as a Permit2 spender for the token.
+*/
+async function approveRouterViaPermit2(params) {
+	const { client, walletClient, account, chainId, tokenIn, amount = UINT160_MAX, expiration, txOverrides, addresses } = params;
+	const { permit2, universalRouter } = getUniswapV4Addresses(chainId, addresses);
+	const resolvedExpiration = expiration ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_EXPIRATION_SECONDS;
+	const cappedExpiration = resolvedExpiration > UINT48_MAX ? UINT48_MAX : resolvedExpiration;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: permit2,
+		abi: permit2Abi,
+		functionName: "approve",
+		args: [
+			tokenIn,
+			universalRouter,
+			amount,
+			cappedExpiration
+		],
+		txOverrides
+	});
+}
+/**
+* Step 2 (and wait): approve the Universal Router via Permit2.
+*/
+async function approveRouterViaPermit2AndWait(params) {
+	const result = await approveRouterViaPermit2(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/uniswap/v4/abis/v4Quoter.ts
+/**
+* Minimal V4Quoter ABI (`quoteExactInputSingle`, `quoteExactOutputSingle`).
+*
+* Note: neither function is `view` — they mutate state internally and are
+* intended to be called via `eth_call` / viem `simulateContract`, never
+* `readContract`.
+*
+* @module uniswap/v4/abis/v4Quoter
+*/
+const quoteExactSingleParams = {
+	name: "params",
+	type: "tuple",
+	components: [
+		{
+			name: "poolKey",
+			type: "tuple",
+			components: [
+				{
+					name: "currency0",
+					type: "address"
+				},
+				{
+					name: "currency1",
+					type: "address"
+				},
+				{
+					name: "fee",
+					type: "uint24"
+				},
+				{
+					name: "tickSpacing",
+					type: "int24"
+				},
+				{
+					name: "hooks",
+					type: "address"
+				}
+			]
+		},
+		{
+			name: "zeroForOne",
+			type: "bool"
+		},
+		{
+			name: "exactAmount",
+			type: "uint128"
+		},
+		{
+			name: "hookData",
+			type: "bytes"
+		}
+	]
+};
+const v4QuoterAbi = [{
+	type: "function",
+	name: "quoteExactInputSingle",
+	stateMutability: "nonpayable",
+	inputs: [quoteExactSingleParams],
+	outputs: [{
+		name: "amountOut",
+		type: "uint256"
+	}, {
+		name: "gasEstimate",
+		type: "uint256"
+	}]
+}, {
+	type: "function",
+	name: "quoteExactOutputSingle",
+	stateMutability: "nonpayable",
+	inputs: [quoteExactSingleParams],
+	outputs: [{
+		name: "amountIn",
+		type: "uint256"
+	}, {
+		name: "gasEstimate",
+		type: "uint256"
+	}]
+}];
+
+//#endregion
+//#region src/uniswap/v4/router/resolvePoolKey.ts
+/**
+* Resolve the PoolKey, swap direction, and output token metadata for a swap.
+*
+* @throws {InvalidSwapTokenError} when `tokenIn` is not part of the pool.
+*/
+async function resolveSwapRoute(params) {
+	const { client, poolAddress, chainId, tokenIn, blockNumber } = params;
+	const pool = await getPool({
+		client,
+		poolAddress,
+		chainId,
+		blockNumber
+	});
+	const { poolKey } = pool;
+	const isCurrency0 = isAddressEqual(tokenIn, poolKey.currency0);
+	const isCurrency1 = isAddressEqual(tokenIn, poolKey.currency1);
+	if (!isCurrency0 && !isCurrency1) throw new InvalidSwapTokenError(tokenIn, poolKey.currency0, poolKey.currency1);
+	const zeroForOne = isCurrency0;
+	const tokenOut = zeroForOne ? poolKey.currency1 : poolKey.currency0;
+	const outTracker = zeroForOne ? pool.collateralTracker1 : pool.collateralTracker0;
+	return {
+		poolKey,
+		zeroForOne,
+		tokenOut,
+		tokenOutDecimals: outTracker.decimals,
+		tokenOutSymbol: outTracker.symbol
+	};
+}
+
+//#endregion
+//#region src/uniswap/v4/router/quote.ts
+const BPS_DENOMINATOR$1 = 10000n;
+const UINT128_MAX$1 = (1n << 128n) - 1n;
+/** Reject out-of-range slippage so the min/max amount math can't underflow/overflow. */
+function assertSlippageBps(slippageBps) {
+	if (slippageBps < 0n || slippageBps > BPS_DENOMINATOR$1) throw new PanopticError(`invalid slippageBps ${slippageBps}, must be 0..10000`);
+}
+const FALLBACK_META = {
+	blockNumber: 0n,
+	blockTimestamp: 0n,
+	blockHash: "0x0"
+};
+/**
+* Quote an exact-in spot swap against the underlying Uniswap v4 pool.
+*
+* Uses the V4Quoter `quoteExactInputSingle` via `eth_call` (the quoter is
+* state-mutating / revert-based, so it must be simulated, not read). Returns a
+* `SimulationResult` so failures carry a structured error rather than throwing.
+*/
+async function quoteSwapExactInViaRouter(params) {
+	const { client, poolAddress, chainId, tokenIn, amountIn, slippageBps, blockNumber, addresses } = params;
+	try {
+		if (amountIn < 0n || amountIn > UINT128_MAX$1) throw new PanopticError(`amountIn ${amountIn} exceeds uint128 maximum`);
+		assertSlippageBps(slippageBps);
+		const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+		const metaPromise = getBlockMeta({
+			client,
+			blockNumber: targetBlockNumber
+		});
+		const { v4Quoter } = getUniswapV4Addresses(chainId, addresses);
+		if (v4Quoter === zeroAddress) throw new QuoterUnavailableError(chainId);
+		const route = await resolveSwapRoute({
+			client,
+			poolAddress,
+			chainId,
+			tokenIn,
+			blockNumber: targetBlockNumber
+		});
+		const { result } = await client.simulateContract({
+			address: v4Quoter,
+			abi: v4QuoterAbi,
+			functionName: "quoteExactInputSingle",
+			blockNumber: targetBlockNumber,
+			args: [{
+				poolKey: {
+					currency0: route.poolKey.currency0,
+					currency1: route.poolKey.currency1,
+					fee: Number(route.poolKey.fee),
+					tickSpacing: Number(route.poolKey.tickSpacing),
+					hooks: route.poolKey.hooks
+				},
+				zeroForOne: route.zeroForOne,
+				exactAmount: amountIn,
+				hookData: "0x"
+			}]
+		});
+		const [amountOut, gasEstimate] = result;
+		const amountOutMinimum = amountOut * (BPS_DENOMINATOR$1 - slippageBps) / BPS_DENOMINATOR$1;
+		const _meta = await metaPromise;
+		return {
+			success: true,
+			data: {
+				amountOut,
+				amountOutMinimum,
+				zeroForOne: route.zeroForOne,
+				tokenOut: route.tokenOut,
+				poolKey: route.poolKey,
+				gasEstimate
+			},
+			gasEstimate,
+			_meta
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Quote failed", error instanceof Error ? error : void 0),
+			_meta: FALLBACK_META
+		};
+	}
+}
+/**
+* Quote an exact-out spot swap against the underlying Uniswap v4 pool.
+*
+* Uses the V4Quoter `quoteExactOutputSingle` via `eth_call` (the quoter is
+* state-mutating / revert-based, so it must be simulated, not read). Returns a
+* `SimulationResult` so failures carry a structured error rather than throwing.
+*/
+async function quoteSwapExactOutViaRouter(params) {
+	const { client, poolAddress, chainId, tokenIn, amountOut, slippageBps, blockNumber, addresses } = params;
+	try {
+		if (amountOut < 0n || amountOut > UINT128_MAX$1) throw new PanopticError(`amountOut ${amountOut} exceeds uint128 maximum`);
+		assertSlippageBps(slippageBps);
+		const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+		const metaPromise = getBlockMeta({
+			client,
+			blockNumber: targetBlockNumber
+		});
+		const { v4Quoter } = getUniswapV4Addresses(chainId, addresses);
+		if (v4Quoter === zeroAddress) throw new QuoterUnavailableError(chainId);
+		const route = await resolveSwapRoute({
+			client,
+			poolAddress,
+			chainId,
+			tokenIn,
+			blockNumber: targetBlockNumber
+		});
+		const { result } = await client.simulateContract({
+			address: v4Quoter,
+			abi: v4QuoterAbi,
+			functionName: "quoteExactOutputSingle",
+			blockNumber: targetBlockNumber,
+			args: [{
+				poolKey: {
+					currency0: route.poolKey.currency0,
+					currency1: route.poolKey.currency1,
+					fee: Number(route.poolKey.fee),
+					tickSpacing: Number(route.poolKey.tickSpacing),
+					hooks: route.poolKey.hooks
+				},
+				zeroForOne: route.zeroForOne,
+				exactAmount: amountOut,
+				hookData: "0x"
+			}]
+		});
+		const [amountIn, gasEstimate] = result;
+		const amountInMaximum = (amountIn * (BPS_DENOMINATOR$1 + slippageBps) + BPS_DENOMINATOR$1 - 1n) / BPS_DENOMINATOR$1;
+		const _meta = await metaPromise;
+		return {
+			success: true,
+			data: {
+				amountIn,
+				amountInMaximum,
+				zeroForOne: route.zeroForOne,
+				tokenOut: route.tokenOut,
+				poolKey: route.poolKey,
+				gasEstimate
+			},
+			gasEstimate,
+			_meta
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Quote failed", error instanceof Error ? error : void 0),
+			_meta: FALLBACK_META
+		};
+	}
+}
+
+//#endregion
+//#region src/uniswap/v4/router/quoteByPoolKey.ts
+const BPS_DENOMINATOR = 10000n;
+const UINT128_MAX = (1n << 128n) - 1n;
+/**
+* Quote an exact-in v4 swap for a specific PoolKey. Returns `null` when the
+* quote reverts (pool missing / no liquidity) so callers can skip that pool when
+* ranking venues rather than aborting the cycle.
+*/
+async function quoteV4ExactInByPoolKey(params) {
+	const { client, chainId, poolKey, zeroForOne, amountIn, slippageBps, blockNumber } = params;
+	if (amountIn < 0n || amountIn > UINT128_MAX) throw new PanopticError(`amountIn ${amountIn} exceeds uint128 maximum`);
+	if (slippageBps < 0n || slippageBps > BPS_DENOMINATOR) throw new PanopticError(`invalid slippageBps ${slippageBps}, must be 0..10000`);
+	const { v4Quoter } = getUniswapV4Addresses(chainId, params.addresses);
+	try {
+		const { result } = await client.simulateContract({
+			address: v4Quoter,
+			abi: v4QuoterAbi,
+			functionName: "quoteExactInputSingle",
+			blockNumber,
+			args: [{
+				poolKey: {
+					currency0: poolKey.currency0,
+					currency1: poolKey.currency1,
+					fee: Number(poolKey.fee),
+					tickSpacing: Number(poolKey.tickSpacing),
+					hooks: poolKey.hooks
+				},
+				zeroForOne,
+				exactAmount: amountIn,
+				hookData: "0x"
+			}]
+		});
+		const [amountOut, gasEstimate] = result;
+		const amountOutMinimum = amountOut * (BPS_DENOMINATOR - slippageBps) / BPS_DENOMINATOR;
+		return {
+			amountOut,
+			amountOutMinimum,
+			gasEstimate
+		};
+	} catch (err) {
+		if (isRevert(err)) return null;
+		throw err;
+	}
+}
+/** True only for genuine contract reverts (missing pool / no liquidity). */
+function isRevert(err) {
+	return err instanceof BaseError && err.walk((e) => e instanceof ContractFunctionRevertedError) instanceof ContractFunctionRevertedError;
+}
+
+//#endregion
+//#region src/uniswap/v4/router/swap.ts
+/** Default swap deadline window (30 minutes) when no deadline is provided. */
+const DEFAULT_DEADLINE_SECONDS = 1800n;
+/**
+* Execute an exact-in spot swap via the Universal Router.
+*
+* @param params - Swap parameters.
+* @returns TxResult with hash + wait().
+*
+* @example
+* ```typescript
+* const result = await swapExactInViaRouter({
+*   client, walletClient, account, poolAddress,
+*   chainId: 1n,
+*   tokenIn: ZERO_ADDRESS,        // native ETH
+*   amountIn: 10n ** 17n,         // 0.1 ETH
+*   slippageBps: 50n,             // 0.5%
+* })
+* await result.wait()
+* ```
+*/
+async function swapExactInViaRouter(params) {
+	const { client, walletClient, account, poolAddress, chainId, tokenIn, amountIn, slippageBps, deadline, recipient, txOverrides, addresses } = params;
+	if (recipient !== void 0 && !isAddressEqual(recipient, account)) throw new PanopticError("Custom recipient is not supported yet; output goes to the sender");
+	const resolved = getUniswapV4Addresses(chainId, addresses);
+	const quote = await quoteSwapExactInViaRouter({
+		client,
+		poolAddress,
+		chainId,
+		tokenIn,
+		amountIn,
+		slippageBps,
+		addresses
+	});
+	if (!quote.success) throw quote.error;
+	const resolvedDeadline = deadline ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_DEADLINE_SECONDS;
+	if (!quote.data.poolKey) throw new PanopticError("v4 swap requires a poolKey from the quote");
+	const { args, value } = buildV4SwapExecuteArgs({
+		poolKey: quote.data.poolKey,
+		zeroForOne: quote.data.zeroForOne,
+		amountIn,
+		amountOutMinimum: quote.data.amountOutMinimum,
+		tokenIn,
+		tokenOut: quote.data.tokenOut,
+		deadline: resolvedDeadline,
+		recipient: account
+	});
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: resolved.universalRouter,
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args,
+		value,
+		txOverrides
+	});
+}
+/**
+* Execute an exact-in swap via the Universal Router and wait for confirmation.
+*/
+async function swapExactInViaRouterAndWait(params) {
+	const result = await swapExactInViaRouter(params);
+	return result.wait();
+}
+/**
+* Execute an exact-out spot swap via the Universal Router.
+*
+* The caller specifies the exact `amountOut` to receive; the input (pay) amount
+* is quoted and capped at `amountInMaximum`. For native-ETH input the router is
+* funded with `amountInMaximum` and the unused surplus is swept back to the
+* sender.
+*
+* @param params - Swap parameters.
+* @returns TxResult with hash + wait().
+*/
+async function swapExactOutViaRouter(params) {
+	const { client, walletClient, account, poolAddress, chainId, tokenIn, amountOut, slippageBps, deadline, recipient, txOverrides, addresses } = params;
+	if (recipient !== void 0 && !isAddressEqual(recipient, account)) throw new PanopticError("Custom recipient is not supported yet; output goes to the sender");
+	const resolved = getUniswapV4Addresses(chainId, addresses);
+	const quote = await quoteSwapExactOutViaRouter({
+		client,
+		poolAddress,
+		chainId,
+		tokenIn,
+		amountOut,
+		slippageBps,
+		addresses
+	});
+	if (!quote.success) throw quote.error;
+	const resolvedDeadline = deadline ?? (await getBlockMeta({ client })).blockTimestamp + DEFAULT_DEADLINE_SECONDS;
+	if (!quote.data.poolKey) throw new PanopticError("v4 swap requires a poolKey from the quote");
+	const { args, value } = buildV4ExactOutSwapExecuteArgs({
+		poolKey: quote.data.poolKey,
+		zeroForOne: quote.data.zeroForOne,
+		amountOut,
+		amountInMaximum: quote.data.amountInMaximum,
+		tokenIn,
+		tokenOut: quote.data.tokenOut,
+		deadline: resolvedDeadline,
+		recipient: account
+	});
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: resolved.universalRouter,
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args,
+		value,
+		txOverrides
+	});
+}
+/**
+* Execute an exact-out swap via the Universal Router and wait for confirmation.
+*/
+async function swapExactOutViaRouterAndWait(params) {
+	const result = await swapExactOutViaRouter(params);
+	return result.wait();
+}
+
+//#endregion
+export { AmountExceedsUint128Error, InvalidSwapTokenError, MSG_SENDER, MissingSweepRecipientError, PERMIT2_ADDRESS, QuoterUnavailableError, SETTLE_ALL, SWAP_EXACT_IN_SINGLE, SWAP_EXACT_OUT_SINGLE, SWEEP, TAKE_ALL, UNISWAP_V3_ADDRESSES, UNISWAP_V4_ADDRESSES, UnsupportedChainError, V3_SWAP_EXACT_IN, V3_SWAP_EXACT_OUT, V4_SWAP, approveErc20ForPermit2, approveErc20ForPermit2AndWait, approveRouterViaPermit2, approveRouterViaPermit2AndWait, buildV3ExactOutSwapExecuteArgs, buildV3ExactOutSwapExecuteCalldata, buildV3SwapExecuteArgs, buildV3SwapExecuteCalldata, buildV4ExactOutSwapExecuteArgs, buildV4ExactOutSwapExecuteCalldata, buildV4SwapExecuteArgs, buildV4SwapExecuteCalldata, calculatePositionVolatilityMetrics, checkRouterApproval, encodeV3Path, feesFromFeeGrowthDelta, getLpDepositAmounts, getLpDepositBreakdown, getLpFundingDeposit, getLpPositionFunding, getMaxLpPositionSize, getPriceHistory, getUnhedgedLpRanges, getUniswapV3Addresses, getUniswapV3LpPositionState, getUniswapV4Addresses, getUniswapV4LpPositionState, prepareLiquidityGamma, preparePositionGamma, quoteSwapExactInViaRouter, quoteSwapExactInViaV3Router, quoteSwapExactOutViaRouter, quoteSwapExactOutViaV3Router, quoteV3ExactIn, quoteV3ExactOut, quoteV4ExactInByPoolKey, resolveSwapRoute, resolveV3SwapRoute, swapExactInViaRouter, swapExactInViaRouterAndWait, swapExactInViaV3Router, swapExactOutViaRouter, swapExactOutViaRouterAndWait, swapExactOutViaV3Router, valuePositionAccrual };