@panoptic-eng/sdk 1.0.49 → 1.0.50

package/dist/router-BSS7HKd2.js

@@ -0,0 +1,837 @@
+import { PanopticError, getBlockMeta, getPoolMetadata, submitWrite } from "./rates-COAJpKRd.js";
+import { tickToSqrtPriceX96 } from "./greeks-CNi1-cnp.js";
+import { decodeAllLegs } from "./writes-D1zN0v9x.js";
+import { BaseError, ContractFunctionRevertedError, encodeAbiParameters, encodeFunctionData, encodePacked, isAddressEqual, zeroAddress } from "viem";
+
+//#region src/uniswap/lpDeposit.ts
+const Q96 = 1n << 96n;
+const ceilDiv = (n, d) => (n + d - 1n) / d;
+/** Uniswap mint principal in raw token units, rounded up per leg, plus 5% headroom. */
+function getLpDepositAmounts(ranges, sqrtPriceX96) {
+	return getLpDepositBreakdown(ranges, sqrtPriceX96).total;
+}
+/** Principal and separately identified funding headroom, in native token units. */
+function getLpDepositBreakdown(ranges, sqrtPriceX96) {
+	if (sqrtPriceX96 <= 0n) throw new Error("Invalid pool price");
+	let amount0 = 0n;
+	let amount1 = 0n;
+	for (const { tickLower, tickUpper, liquidity } of ranges) {
+		if (!Number.isInteger(tickLower) || !Number.isInteger(tickUpper) || tickLower < -887272 || tickUpper > 887272 || tickLower >= tickUpper || liquidity < 0n) throw new Error("Invalid LP range");
+		const lower = tickToSqrtPriceX96(BigInt(tickLower));
+		const upper = tickToSqrtPriceX96(BigInt(tickUpper));
+		const price = sqrtPriceX96 < lower ? lower : sqrtPriceX96 > upper ? upper : sqrtPriceX96;
+		amount0 += ceilDiv(liquidity * Q96 * (upper - price), upper * price);
+		amount1 += ceilDiv(liquidity * (price - lower), Q96);
+	}
+	const buffer = {
+		amount0: ceilDiv(amount0 * 5n, 100n),
+		amount1: ceilDiv(amount1 * 5n, 100n)
+	};
+	return {
+		principal: {
+			amount0,
+			amount1
+		},
+		buffer,
+		total: {
+			amount0: amount0 + buffer.amount0,
+			amount1: amount1 + buffer.amount1
+		}
+	};
+}
+/** Full deployed liquidity value; never a leveraged protocol margin estimate. */
+function getLpPositionFunding(params) {
+	const { tokenId, positionSize, tickSpacing, sqrtPriceX96, valuationSqrtPriceX96, quoteTokenIndex } = params;
+	if (positionSize < 0n || tickSpacing <= 0n || valuationSqrtPriceX96 <= 0n) throw new Error("Invalid LP funding input");
+	const legs = decodeAllLegs(tokenId);
+	if (legs.length === 0 || legs.some((leg) => leg.isLong || leg.width === 0n)) throw new Error("AMM Liquidity requires short liquidity legs without loans or credits");
+	const ranges = legs.map((leg) => {
+		const width = leg.width * tickSpacing;
+		const tickLower = leg.strike - width / 2n;
+		const tickUpper = leg.strike + (width + 1n) / 2n;
+		const lower = tickToSqrtPriceX96(tickLower);
+		const upper = tickToSqrtPriceX96(tickUpper);
+		const amount = positionSize * leg.optionRatio;
+		const liquidity = leg.asset === 0n ? amount * (lower * upper / Q96) / (upper - lower) : amount * Q96 / (upper - lower);
+		return {
+			tickLower: Number(tickLower),
+			tickUpper: Number(tickUpper),
+			liquidity
+		};
+	});
+	const breakdown = getLpDepositBreakdown(ranges, sqrtPriceX96);
+	const priceSquared = valuationSqrtPriceX96 * valuationSqrtPriceX96;
+	const value = ({ amount0, amount1 }) => quoteTokenIndex === 0 ? amount0 + ceilDiv(amount1 * Q96 * Q96, priceSquared) : amount1 + ceilDiv(amount0 * priceSquared, Q96 * Q96);
+	const principalInQuote = value(breakdown.principal);
+	const totalInQuote = value(breakdown.total);
+	return {
+		...breakdown,
+		principalInQuote,
+		bufferInQuote: totalInQuote - principalInQuote,
+		totalInQuote
+	};
+}
+/** Remaining deposit in the requested token mix, rounded up to cover the shortfall. */
+function getLpFundingDeposit({ funding, availableInQuote, minimumInQuote = 0n, quoteTokenIndex, valuationSqrtPriceX96, quotePercent }) {
+	if (valuationSqrtPriceX96 <= 0n || quotePercent !== void 0 && (quotePercent < 0n || quotePercent > 100n)) throw new Error("Invalid LP funding split");
+	const requiredInQuote = minimumInQuote > funding.totalInQuote ? minimumInQuote : funding.totalInQuote;
+	const shortfallInQuote = requiredInQuote > availableInQuote ? requiredInQuote - availableInQuote : 0n;
+	const defaultQuotePercent = funding.totalInQuote > 0n ? (quoteTokenIndex === 0 ? funding.total.amount0 : funding.total.amount1) * 100n / funding.totalInQuote : 100n;
+	if (quotePercent === void 0) return {
+		requiredInQuote,
+		shortfallInQuote,
+		defaultQuotePercent,
+		amount0: funding.totalInQuote > 0n ? ceilDiv(funding.total.amount0 * shortfallInQuote, funding.totalInQuote) : 0n,
+		amount1: funding.totalInQuote > 0n ? ceilDiv(funding.total.amount1 * shortfallInQuote, funding.totalInQuote) : 0n
+	};
+	const quoteAmount = shortfallInQuote * quotePercent / 100n;
+	const assetValue = shortfallInQuote - quoteAmount;
+	const priceSquared = valuationSqrtPriceX96 * valuationSqrtPriceX96;
+	return {
+		requiredInQuote,
+		shortfallInQuote,
+		defaultQuotePercent,
+		amount0: quoteTokenIndex === 0 ? quoteAmount : ceilDiv(assetValue * Q96 * Q96, priceSquared),
+		amount1: quoteTokenIndex === 1 ? quoteAmount : ceilDiv(assetValue * priceSquared, Q96 * Q96)
+	};
+}
+/** Largest raw size funded by available collateral, including native-token rounding. */
+function getMaxLpPositionSize(params) {
+	if (params.minimumRequirement && (params.minimumRequirement.referenceSize <= 0n || params.minimumRequirement.requiredInQuote < 0n)) throw new Error("Invalid reference requirement");
+	if (params.availableInQuote <= 0n) return 0n;
+	let low = 0n;
+	let high = (1n << 128n) - 1n;
+	while (low < high) {
+		const mid = (low + high + 1n) / 2n;
+		const funding = getLpPositionFunding({
+			...params,
+			positionSize: mid
+		});
+		const minimum = params.minimumRequirement ? ceilDiv(params.minimumRequirement.requiredInQuote * mid, params.minimumRequirement.referenceSize) : 0n;
+		if (funding.totalInQuote <= params.availableInQuote && minimum <= params.availableInQuote) low = mid;
+		else high = mid - 1n;
+	}
+	return low;
+}
+
+//#endregion
+//#region src/uniswap/v4/router/errors.ts
+/**
+* The chain has no configured Uniswap v4 addresses and none were supplied via
+* overrides.
+*/
+var UnsupportedChainError = class extends PanopticError {
+	name = "UnsupportedChainError";
+	constructor(chainId, cause) {
+		super(`Uniswap v4 router not configured for chain ${chainId}`, cause);
+		this.chainId = chainId;
+	}
+};
+/**
+* `tokenIn` is neither `currency0` nor `currency1` of the resolved pool.
+*/
+var InvalidSwapTokenError = class extends PanopticError {
+	name = "InvalidSwapTokenError";
+	constructor(token, currency0, currency1, cause) {
+		super(`Token ${token} is not part of the pool (currency0=${currency0}, currency1=${currency1})`, cause);
+		this.token = token;
+		this.currency0 = currency0;
+		this.currency1 = currency1;
+	}
+};
+/**
+* An amount exceeds the uint128 range required by the v4 swap encoding.
+*/
+var AmountExceedsUint128Error = class extends PanopticError {
+	name = "AmountExceedsUint128Error";
+	constructor(amount, cause) {
+		super(`Amount ${amount} exceeds uint128 maximum`, cause);
+		this.amount = amount;
+	}
+};
+/**
+* A native-ETH swap needs a trailing Universal Router SWEEP to deliver the ETH
+* output (or refund the input overpay), but no `recipient` was supplied.
+*/
+var MissingSweepRecipientError = class extends PanopticError {
+	name = "MissingSweepRecipientError";
+	constructor(cause) {
+		super("A recipient is required to sweep native ETH back to the user", cause);
+	}
+};
+/**
+* The V4Quoter is not available for the chain (no fallback in v1).
+*/
+var QuoterUnavailableError = class extends PanopticError {
+	name = "QuoterUnavailableError";
+	constructor(chainId, cause) {
+		super(`V4Quoter unavailable for chain ${chainId}`, cause);
+		this.chainId = chainId;
+	}
+};
+
+//#endregion
+//#region src/uniswap/v3/addresses.ts
+/**
+* Verified Uniswap v3 QuoterV2 addresses keyed by chainId. Add a chain only
+* after verifying against the canonical Uniswap v3 deployment listing.
+*/
+const UNISWAP_V3_ADDRESSES = {
+	1: {
+		quoterV2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+		nonfungiblePositionManager: "0xC36442b4a4522E871399CD717aBDD847Ab11FE88"
+	},
+	4663: {
+		quoterV2: "0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7",
+		nonfungiblePositionManager: "0x73991a25c818bf1f1128deaab1492d45638de0d3"
+	}
+};
+/**
+* Resolve Uniswap v3 addresses for a chain, applying optional overrides.
+*
+* @throws {UnsupportedChainError} when the chain is not listed and overrides do
+*   not supply every required address.
+*/
+function getUniswapV3Addresses(chainId, overrides) {
+	const id = Number(chainId);
+	const base = UNISWAP_V3_ADDRESSES[id];
+	const merged = {
+		...base,
+		...overrides
+	};
+	if (!merged.quoterV2 || !merged.nonfungiblePositionManager) throw new UnsupportedChainError(BigInt(id));
+	return merged;
+}
+
+//#endregion
+//#region src/uniswap/v4/abis/universalRouter.ts
+/**
+* Minimal Universal Router ABI (only the `execute` overload we use).
+* @module uniswap/v4/abis/universalRouter
+*/
+const universalRouterAbi = [{
+	type: "function",
+	name: "execute",
+	stateMutability: "payable",
+	inputs: [
+		{
+			name: "commands",
+			type: "bytes"
+		},
+		{
+			name: "inputs",
+			type: "bytes[]"
+		},
+		{
+			name: "deadline",
+			type: "uint256"
+		}
+	],
+	outputs: []
+}];
+
+//#endregion
+//#region src/uniswap/v3/router/encodeSwap.ts
+/** Universal Router command byte for a v3 exact-in swap. */
+const V3_SWAP_EXACT_IN = 0;
+/** Universal Router command byte for a v3 exact-out swap. */
+const V3_SWAP_EXACT_OUT = 1;
+/**
+* Universal Router recipient sentinel: the router maps `address(1)` to
+* `msg.sender` (the `execute` caller). Uniswap `Constants.MSG_SENDER`.
+*/
+const MSG_SENDER = "0x0000000000000000000000000000000000000001";
+const UINT128_MAX$1 = (1n << 128n) - 1n;
+const v3ExactInInputAbi = [
+	{
+		name: "recipient",
+		type: "address"
+	},
+	{
+		name: "amountIn",
+		type: "uint256"
+	},
+	{
+		name: "amountOutMinimum",
+		type: "uint256"
+	},
+	{
+		name: "path",
+		type: "bytes"
+	},
+	{
+		name: "payerIsUser",
+		type: "bool"
+	}
+];
+function assertUint128(amount) {
+	if (amount < 0n || amount > UINT128_MAX$1) throw new AmountExceedsUint128Error(amount);
+}
+/**
+* Encode the packed v3 single-hop path `tokenIn ++ fee(uint24) ++ tokenOut`.
+*/
+function encodeV3Path(tokenIn, fee, tokenOut) {
+	if (fee < 0n || fee > 0xffffffn) throw new PanopticError(`v3 fee ${fee} exceeds uint24`);
+	return encodePacked([
+		"address",
+		"uint24",
+		"address"
+	], [
+		tokenIn,
+		Number(fee),
+		tokenOut
+	]);
+}
+/**
+* Build the typed `execute(...)` args for an exact-in single-hop v3 swap whose
+* output is delivered to the `execute` caller (recipient = MSG_SENDER).
+*/
+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);
+	const path = encodeV3Path(tokenIn, fee, tokenOut);
+	const input = encodeAbiParameters(v3ExactInInputAbi, [
+		MSG_SENDER,
+		amountIn,
+		amountOutMinimum,
+		path,
+		true
+	]);
+	const commands = encodePacked(["uint8"], [V3_SWAP_EXACT_IN]);
+	return {
+		args: [
+			commands,
+			[input],
+			deadline
+		],
+		value: 0n
+	};
+}
+/**
+* Build the `execute(commands, inputs, deadline)` calldata for an exact-in
+* single-hop v3 swap.
+*/
+function buildV3SwapExecuteCalldata(args) {
+	const { args: executeArgs, value } = buildV3SwapExecuteArgs(args);
+	const data = encodeFunctionData({
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args: executeArgs
+	});
+	return {
+		data,
+		value
+	};
+}
+const v3ExactOutInputAbi = [
+	{
+		name: "recipient",
+		type: "address"
+	},
+	{
+		name: "amountOut",
+		type: "uint256"
+	},
+	{
+		name: "amountInMaximum",
+		type: "uint256"
+	},
+	{
+		name: "path",
+		type: "bytes"
+	},
+	{
+		name: "payerIsUser",
+		type: "bool"
+	}
+];
+/**
+* Build the typed `execute(...)` args for an exact-out single-hop v3 swap.
+* The v3 exact-out path is reversed: `tokenOut ++ fee ++ tokenIn`.
+*/
+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);
+	const path = encodeV3Path(tokenOut, fee, tokenIn);
+	const input = encodeAbiParameters(v3ExactOutInputAbi, [
+		MSG_SENDER,
+		amountOut,
+		amountInMaximum,
+		path,
+		true
+	]);
+	const commands = encodePacked(["uint8"], [V3_SWAP_EXACT_OUT]);
+	return {
+		args: [
+			commands,
+			[input],
+			deadline
+		],
+		value: 0n
+	};
+}
+function buildV3ExactOutSwapExecuteCalldata(args) {
+	const { args: executeArgs, value } = buildV3ExactOutSwapExecuteArgs(args);
+	const data = encodeFunctionData({
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args: executeArgs
+	});
+	return {
+		data,
+		value
+	};
+}
+
+//#endregion
+//#region src/uniswap/v3/abis/quoterV2.ts
+/**
+* Minimal Uniswap v3 QuoterV2 ABI.
+*
+* QuoterV2 is revert/staticcall-based (nonpayable but intended for `eth_call` /
+* `simulateContract`), so it must be simulated, not read.
+* @module uniswap/v3/abis/quoterV2
+*/
+const quoterV2Abi = [{
+	type: "function",
+	name: "quoteExactInputSingle",
+	stateMutability: "nonpayable",
+	inputs: [{
+		name: "params",
+		type: "tuple",
+		components: [
+			{
+				name: "tokenIn",
+				type: "address"
+			},
+			{
+				name: "tokenOut",
+				type: "address"
+			},
+			{
+				name: "amountIn",
+				type: "uint256"
+			},
+			{
+				name: "fee",
+				type: "uint24"
+			},
+			{
+				name: "sqrtPriceLimitX96",
+				type: "uint160"
+			}
+		]
+	}],
+	outputs: [
+		{
+			name: "amountOut",
+			type: "uint256"
+		},
+		{
+			name: "sqrtPriceX96After",
+			type: "uint160"
+		},
+		{
+			name: "initializedTicksCrossed",
+			type: "uint32"
+		},
+		{
+			name: "gasEstimate",
+			type: "uint256"
+		}
+	]
+}, {
+	type: "function",
+	name: "quoteExactOutputSingle",
+	stateMutability: "nonpayable",
+	inputs: [{
+		name: "params",
+		type: "tuple",
+		components: [
+			{
+				name: "tokenIn",
+				type: "address"
+			},
+			{
+				name: "tokenOut",
+				type: "address"
+			},
+			{
+				name: "amount",
+				type: "uint256"
+			},
+			{
+				name: "fee",
+				type: "uint24"
+			},
+			{
+				name: "sqrtPriceLimitX96",
+				type: "uint160"
+			}
+		]
+	}],
+	outputs: [
+		{
+			name: "amountIn",
+			type: "uint256"
+		},
+		{
+			name: "sqrtPriceX96After",
+			type: "uint160"
+		},
+		{
+			name: "initializedTicksCrossed",
+			type: "uint32"
+		},
+		{
+			name: "gasEstimate",
+			type: "uint256"
+		}
+	]
+}];
+
+//#endregion
+//#region src/uniswap/v3/router/quote.ts
+const BPS_DENOMINATOR = 10000n;
+const UINT128_MAX = (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
+* ranking venues, rather than aborting the whole cycle.
+*/
+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);
+	const { quoterV2 } = getUniswapV3Addresses(chainId, params.addresses);
+	try {
+		const { result } = await client.simulateContract({
+			address: quoterV2,
+			abi: quoterV2Abi,
+			functionName: "quoteExactInputSingle",
+			blockNumber,
+			args: [{
+				tokenIn,
+				tokenOut,
+				amountIn,
+				fee: Number(fee),
+				sqrtPriceLimitX96: 0n
+			}]
+		});
+		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;
+	}
+}
+/**
+* Quote an exact-out v3 swap. Returns `null` on revert (no pool / no liquidity).
+*/
+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);
+	const { quoterV2 } = getUniswapV3Addresses(chainId, params.addresses);
+	try {
+		const { result } = await client.simulateContract({
+			address: quoterV2,
+			abi: quoterV2Abi,
+			functionName: "quoteExactOutputSingle",
+			blockNumber,
+			args: [{
+				tokenIn,
+				tokenOut,
+				amount: amountOut,
+				fee: Number(fee),
+				sqrtPriceLimitX96: 0n
+			}]
+		});
+		const [amountIn, , , gasEstimate] = result;
+		const amountInMaximum = (amountIn * (BPS_DENOMINATOR + slippageBps) + BPS_DENOMINATOR - 1n) / BPS_DENOMINATOR;
+		return {
+			amountIn,
+			amountInMaximum,
+			gasEstimate
+		};
+	} catch (err) {
+		if (isRevert(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 isRevert(err) {
+	return err instanceof BaseError && err.walk((e) => e instanceof ContractFunctionRevertedError) instanceof ContractFunctionRevertedError;
+}
+
+//#endregion
+//#region src/uniswap/v3/router/resolveRoute.ts
+async function resolveV3SwapRoute(params) {
+	const { client, poolAddress, tokenIn } = params;
+	const meta = await getPoolMetadata({
+		client,
+		poolAddress
+	});
+	if (meta.isV4) throw new PanopticError("resolveV3SwapRoute called on a v4 pool");
+	const isToken0 = isAddressEqual(tokenIn, meta.token0Asset);
+	const isToken1 = isAddressEqual(tokenIn, meta.token1Asset);
+	if (!isToken0 && !isToken1) throw new InvalidSwapTokenError(tokenIn, meta.token0Asset, meta.token1Asset);
+	const zeroForOne = isToken0;
+	return {
+		tokenIn,
+		tokenOut: zeroForOne ? meta.token1Asset : meta.token0Asset,
+		fee: meta.fee,
+		zeroForOne
+	};
+}
+
+//#endregion
+//#region src/uniswap/v3/router/quoteViaRouter.ts
+const FALLBACK_META = {
+	blockNumber: 0n,
+	blockTimestamp: 0n,
+	blockHash: "0x0"
+};
+async function quoteSwapExactInViaV3Router(params) {
+	const { client, poolAddress, chainId, tokenIn, amountIn, slippageBps, blockNumber, addresses } = params;
+	try {
+		const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+		const metaPromise = getBlockMeta({
+			client,
+			blockNumber: targetBlockNumber
+		});
+		metaPromise.catch(() => void 0);
+		const route = await resolveV3SwapRoute({
+			client,
+			poolAddress,
+			tokenIn
+		});
+		const quote = await quoteV3ExactIn({
+			client,
+			chainId,
+			tokenIn: route.tokenIn,
+			tokenOut: route.tokenOut,
+			fee: route.fee,
+			amountIn,
+			slippageBps,
+			blockNumber: targetBlockNumber,
+			addresses
+		});
+		if (!quote) throw new PanopticError("v3 quote returned no result (pool may have no liquidity)");
+		const _meta = await metaPromise;
+		return {
+			success: true,
+			data: {
+				amountOut: quote.amountOut,
+				amountOutMinimum: quote.amountOutMinimum,
+				zeroForOne: route.zeroForOne,
+				tokenOut: route.tokenOut,
+				gasEstimate: quote.gasEstimate
+			},
+			gasEstimate: quote.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
+		};
+	}
+}
+async function quoteSwapExactOutViaV3Router(params) {
+	const { client, poolAddress, chainId, tokenIn, amountOut, slippageBps, blockNumber, addresses } = params;
+	try {
+		const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+		const metaPromise = getBlockMeta({
+			client,
+			blockNumber: targetBlockNumber
+		});
+		metaPromise.catch(() => void 0);
+		const route = await resolveV3SwapRoute({
+			client,
+			poolAddress,
+			tokenIn
+		});
+		const quote = await quoteV3ExactOut({
+			client,
+			chainId,
+			tokenIn: route.tokenIn,
+			tokenOut: route.tokenOut,
+			fee: route.fee,
+			amountOut,
+			slippageBps,
+			blockNumber: targetBlockNumber,
+			addresses
+		});
+		if (!quote) throw new PanopticError("v3 quote returned no result (pool may have no liquidity)");
+		const _meta = await metaPromise;
+		return {
+			success: true,
+			data: {
+				amountIn: quote.amountIn,
+				amountInMaximum: quote.amountInMaximum,
+				zeroForOne: route.zeroForOne,
+				tokenOut: route.tokenOut,
+				gasEstimate: quote.gasEstimate
+			},
+			gasEstimate: quote.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/addresses.ts
+/**
+* Canonical Permit2, identical across all chains.
+*/
+const PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+/**
+* Verified Uniswap v4 deployment addresses keyed by chainId.
+*
+* Sourced from the official Uniswap v4 deployments. Add a chain here only after
+* verifying each address against the canonical Uniswap deployment listing —
+* Universal Router in particular is NOT the same address across chains.
+*/
+const UNISWAP_V4_ADDRESSES = {
+	1: {
+		universalRouter: "0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af",
+		v4Quoter: "0x52F0E24D1c21C8A0cB1e5a5dD6198556BD9E1203",
+		poolManager: "0x000000000004444c5dc75cB358380D2e3dE08A90",
+		positionManager: "0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e",
+		permit2: PERMIT2_ADDRESS
+	},
+	4663: {
+		universalRouter: "0x8876789976decbfcbbbe364623c63652db8c0904",
+		v4Quoter: "0x8dc178efb8111bb0973dd9d722ebeff267c98f94",
+		poolManager: "0x8366a39cc670b4001a1121b8f6a443a643e40951",
+		positionManager: "0x58daec3116aae6d93017baaea7749052e8a04fa7",
+		permit2: PERMIT2_ADDRESS
+	}
+};
+/**
+* Resolve the Uniswap v4 addresses for a chain, applying optional overrides.
+*
+* @param chainId - Target chain ID.
+* @param overrides - Partial override of any address (e.g. for fork tests).
+* @returns Fully-resolved {@link UniswapV4Addresses}.
+* @throws {UnsupportedChainError} when the chain is not listed and the
+*   overrides do not supply every required address.
+*/
+function getUniswapV4Addresses(chainId, overrides) {
+	const base = UNISWAP_V4_ADDRESSES[Number(chainId)];
+	const merged = {
+		...base,
+		...overrides,
+		permit2: overrides?.permit2 ?? base?.permit2 ?? PERMIT2_ADDRESS
+	};
+	if (merged.universalRouter === void 0 || merged.v4Quoter === void 0 || merged.poolManager === void 0 || merged.positionManager === void 0 || merged.permit2 === void 0) throw new UnsupportedChainError(chainId);
+	return merged;
+}
+
+//#endregion
+//#region src/uniswap/v3/router/swap.ts
+const DEFAULT_DEADLINE_SECONDS = 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");
+	const resolved = getUniswapV4Addresses(chainId, addresses);
+	const route = await resolveV3SwapRoute({
+		client,
+		poolAddress,
+		tokenIn
+	});
+	const quote = await quoteV3ExactIn({
+		client,
+		chainId,
+		tokenIn: route.tokenIn,
+		tokenOut: route.tokenOut,
+		fee: route.fee,
+		amountIn,
+		slippageBps,
+		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 { args, value } = buildV3SwapExecuteArgs({
+		tokenIn: route.tokenIn,
+		tokenOut: route.tokenOut,
+		fee: route.fee,
+		amountIn,
+		amountOutMinimum: quote.amountOutMinimum,
+		deadline: resolvedDeadline
+	});
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: resolved.universalRouter,
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args,
+		value,
+		txOverrides
+	});
+}
+async function swapExactOutViaV3Router(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 route = await resolveV3SwapRoute({
+		client,
+		poolAddress,
+		tokenIn
+	});
+	const quote = await quoteV3ExactOut({
+		client,
+		chainId,
+		tokenIn: route.tokenIn,
+		tokenOut: route.tokenOut,
+		fee: route.fee,
+		amountOut,
+		slippageBps,
+		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 { args, value } = buildV3ExactOutSwapExecuteArgs({
+		tokenIn: route.tokenIn,
+		tokenOut: route.tokenOut,
+		fee: route.fee,
+		amountOut,
+		amountInMaximum: quote.amountInMaximum,
+		deadline: resolvedDeadline
+	});
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: resolved.universalRouter,
+		abi: universalRouterAbi,
+		functionName: "execute",
+		args,
+		value,
+		txOverrides
+	});
+}
+
+//#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, encodeV3Path, getLpDepositAmounts, getLpDepositBreakdown, getLpFundingDeposit, getLpPositionFunding, getMaxLpPositionSize, getUniswapV3Addresses, getUniswapV4Addresses, quoteSwapExactInViaV3Router, quoteSwapExactOutViaV3Router, quoteV3ExactIn, quoteV3ExactOut, resolveV3SwapRoute, swapExactInViaV3Router, swapExactOutViaV3Router, universalRouterAbi };