@panoptic-eng/sdk 1.0.4 → 1.0.6

package/dist/writes-CVCD6Ers.js

@@ -0,0 +1,4302 @@
+import { BatchValidationError, DEFAULT_VEGOID, InputListFailError, InvalidTickLimitsError, InvalidTokenIdParameterError, LEG_BITS, LEG_LIMITS, LEG_MASKS, LoanSlotExhaustedError, MaxRetriesExceededError, MissingPositionIdsError, NoLoanPositionsError, OracleRateLimitedError, PanopticError$1 as PanopticError, ProviderLagError, REORG_DEPTH, SCHEMA_VERSION, STORAGE_PREFIX, STRIKE_CONVERSION_FACTOR, SafeModeError, StaleDataError, SwapTokenMismatchError, SyncTimeoutError, TOKEN_ID_BITS, UnhealthyPoolError, calculatePositionGreeks, collateralTrackerV2Abi, createTxResult, decodeLeftRightUnsigned, getBlockMeta, getPool$1 as getPool, getPoolMetadata$1 as getPoolMetadata, getPositions, panopticErrorsAbi, panopticFactoryV3Abi, panopticFactoryV4Abi, panopticPoolV2Abi, parsePanopticError, submitWrite, tickLimits$1 as tickLimits } from "./position-FxaZi608.js";
+import { decodeFunctionData, decodeFunctionResult, encodeFunctionData, erc20Abi, toFunctionSelector } from "viem";
+
+//#region src/panoptic/v2/writes/broadcaster.ts
+/**
+* Default public broadcaster singleton.
+*
+* Note: This singleton requires a client to be provided via the broadcast call's context.
+* For standalone usage, use `createPublicBroadcaster(client)` instead.
+*
+* When used with write functions, the SDK handles client injection automatically.
+*/
+const publicBroadcaster = { async broadcast(signedTx) {
+	throw new Error("publicBroadcaster requires a client. Use createPublicBroadcaster(client) for standalone usage.");
+} };
+/**
+* Create a nonce manager for concurrent transaction submission.
+*
+* The nonce manager tracks pending nonces to allow multiple transactions
+* to be submitted without waiting for confirmation.
+*
+* @param client - The public client for querying nonces
+* @returns A NonceManager instance
+*
+* @example
+* ```typescript
+* const nonceManager = createNonceManager(client)
+* const nonce1 = await nonceManager.getNextNonce(account)
+* const nonce2 = await nonceManager.getNextNonce(account) // nonce1 + 1
+* // On failure, reset to re-fetch from chain:
+* nonceManager.reset(account)
+* ```
+*/
+function createNonceManager(client) {
+	const pendingNonces = new Map();
+	return {
+		async getNextNonce(account) {
+			const chainNonce = BigInt(await client.getTransactionCount({
+				address: account,
+				blockTag: "pending"
+			}));
+			const pending = pendingNonces.get(account);
+			const localNext = pending !== void 0 ? pending + 1n : chainNonce;
+			const nextNonce = localNext > chainNonce ? localNext : chainNonce;
+			pendingNonces.set(account, nextNonce);
+			return nextNonce;
+		},
+		reset(account) {
+			pendingNonces.delete(account);
+		}
+	};
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/approve.ts
+/**
+* Approve token spending for a collateral tracker.
+*
+* @param params - The approval parameters
+* @returns TxResult with hash and wait function
+*
+* @example
+* ```typescript
+* const result = await approve({
+*   client,
+*   walletClient,
+*   account,
+*   tokenAddress: WETH,
+*   spenderAddress: collateralToken0,
+*   amount: MaxUint256,
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function approve(params) {
+	const { client, walletClient, account, tokenAddress, spenderAddress, amount, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: tokenAddress,
+		abi: erc20Abi,
+		functionName: "approve",
+		args: [spenderAddress, amount],
+		txOverrides
+	});
+}
+/**
+* Approve token spending and wait for confirmation.
+*
+* @param params - The approval parameters
+* @returns TxReceipt after confirmation
+*/
+async function approveAndWait(params) {
+	const result = await approve(params);
+	return result.wait();
+}
+/**
+* Approve both tokens for a Panoptic pool.
+* Fetches collateral tracker addresses and underlying tokens, then approves both.
+*
+* @param params - The approval parameters
+* @returns Array of two TxResults
+*
+* @example
+* ```typescript
+* const [result0, result1] = await approvePool({
+*   client,
+*   walletClient,
+*   account,
+*   poolAddress,
+*   amount0: MaxUint256,
+*   amount1: MaxUint256,
+* })
+* await Promise.all([result0.wait(), result1.wait()])
+* ```
+*/
+async function approvePool(params) {
+	const { client, walletClient, account, poolAddress, amount0, amount1 } = params;
+	const [collateralToken0, collateralToken1] = await client.multicall({
+		contracts: [{
+			address: poolAddress,
+			abi: panopticPoolV2Abi,
+			functionName: "collateralToken0"
+		}, {
+			address: poolAddress,
+			abi: panopticPoolV2Abi,
+			functionName: "collateralToken1"
+		}],
+		allowFailure: false
+	});
+	const [token0, token1] = await client.multicall({
+		contracts: [{
+			address: collateralToken0,
+			abi: collateralTrackerV2Abi,
+			functionName: "asset"
+		}, {
+			address: collateralToken1,
+			abi: collateralTrackerV2Abi,
+			functionName: "asset"
+		}],
+		allowFailure: false
+	});
+	const [result0, result1] = await Promise.all([approve({
+		client,
+		walletClient,
+		account,
+		tokenAddress: token0,
+		spenderAddress: collateralToken0,
+		amount: amount0
+	}), approve({
+		client,
+		walletClient,
+		account,
+		tokenAddress: token1,
+		spenderAddress: collateralToken1,
+		amount: amount1
+	})]);
+	return [result0, result1];
+}
+/**
+* Check if approval is needed for a token transfer.
+*
+* @param params - The check parameters
+* @returns Approval status
+*/
+async function checkApproval(params) {
+	const { client, tokenAddress, owner, spender, amount } = params;
+	const currentAllowance = await client.readContract({
+		address: tokenAddress,
+		abi: erc20Abi,
+		functionName: "allowance",
+		args: [owner, spender]
+	});
+	return {
+		needsApproval: currentAllowance < amount,
+		currentAllowance,
+		requiredAmount: amount
+	};
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/vault.ts
+/**
+* Deposit assets into a collateral tracker.
+*
+* @param params - Deposit parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await deposit({
+*   client,
+*   walletClient,
+*   account,
+*   collateralTrackerAddress,
+*   assets: parseEther('1'),
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function deposit(params) {
+	const { client, walletClient, account, collateralTrackerAddress, assets, isNativeETH, receiver = account, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: collateralTrackerAddress,
+		abi: collateralTrackerV2Abi,
+		functionName: "deposit",
+		args: [assets, receiver],
+		value: isNativeETH ? assets : void 0,
+		txOverrides
+	});
+}
+/**
+* Deposit assets and wait for confirmation.
+*/
+async function depositAndWait(params) {
+	const result = await deposit(params);
+	return result.wait();
+}
+/**
+* Withdraw assets from a collateral tracker.
+*
+* @param params - Withdraw parameters
+* @returns TxResult
+*/
+async function withdraw(params) {
+	const { client, walletClient, account, collateralTrackerAddress, assets, receiver = account, owner = account, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: collateralTrackerAddress,
+		abi: collateralTrackerV2Abi,
+		functionName: "withdraw",
+		args: [
+			assets,
+			receiver,
+			owner
+		],
+		txOverrides
+	});
+}
+/**
+* Withdraw assets and wait for confirmation.
+*/
+async function withdrawAndWait(params) {
+	const result = await withdraw(params);
+	return result.wait();
+}
+/**
+* Withdraw assets with position list validation.
+* This overload validates that the withdrawal won't make positions undercollateralized.
+*
+* @param params - Withdraw parameters with positions
+* @returns TxResult
+*/
+async function withdrawWithPositions(params) {
+	const { client, walletClient, account, collateralTrackerAddress, assets, receiver = account, owner = account, positionIdList, usePremiaAsCollateral, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: collateralTrackerAddress,
+		abi: collateralTrackerV2Abi,
+		functionName: "withdraw",
+		args: [
+			assets,
+			receiver,
+			owner,
+			positionIdList,
+			usePremiaAsCollateral
+		],
+		txOverrides
+	});
+}
+/**
+* Withdraw with positions and wait for confirmation.
+*/
+async function withdrawWithPositionsAndWait(params) {
+	const result = await withdrawWithPositions(params);
+	return result.wait();
+}
+/**
+* Mint shares by depositing assets.
+*
+* @param params - Mint parameters
+* @returns TxResult
+*/
+async function mint(params) {
+	const { client, walletClient, account, collateralTrackerAddress, shares, receiver = account, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: collateralTrackerAddress,
+		abi: collateralTrackerV2Abi,
+		functionName: "mint",
+		args: [shares, receiver],
+		txOverrides
+	});
+}
+/**
+* Mint shares and wait for confirmation.
+*/
+async function mintAndWait(params) {
+	const result = await mint(params);
+	return result.wait();
+}
+/**
+* Redeem shares for assets.
+*
+* @param params - Redeem parameters
+* @returns TxResult
+*/
+async function redeem(params) {
+	const { client, walletClient, account, collateralTrackerAddress, shares, receiver = account, owner = account, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: collateralTrackerAddress,
+		abi: collateralTrackerV2Abi,
+		functionName: "redeem",
+		args: [
+			shares,
+			receiver,
+			owner
+		],
+		txOverrides
+	});
+}
+/**
+* Redeem shares and wait for confirmation.
+*/
+async function redeemAndWait(params) {
+	const result = await redeem(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/storage/fileStorage.ts
+/**
+* Creates a file-based storage adapter for Node.js environments.
+* Stores data as JSON files in the specified directory.
+*
+* The directory will be created if it doesn't exist.
+*
+* @param directory - Path to the storage directory
+*
+* @example
+* ```typescript
+* import { createFileStorage, createConfig } from 'panoptic-v2-sdk'
+*
+* // Node.js only
+* const config = createConfig({
+*   chainId: 1n,
+*   transport: http('...'),
+*   poolAddress: '0x...',
+*   storage: createFileStorage('./panoptic-cache'),
+* })
+* ```
+*/
+function createFileStorage(directory) {
+	let fsPromises = null;
+	let pathModule = null;
+	let initialized = false;
+	const ensureInitialized = async () => {
+		if (initialized) return;
+		fsPromises = await import("node:fs/promises");
+		pathModule = await import("node:path");
+		await fsPromises.mkdir(directory, { recursive: true });
+		initialized = true;
+	};
+	const getFilePath = (key) => {
+		if (!pathModule) throw new Error("File storage not initialized");
+		const safeKey = Buffer.from(key).toString("base64url");
+		return pathModule.join(directory, `${safeKey}.json`);
+	};
+	return {
+		async get(key) {
+			await ensureInitialized();
+			if (!fsPromises) throw new Error("File storage not initialized");
+			try {
+				const filePath = getFilePath(key);
+				const content = await fsPromises.readFile(filePath, "utf-8");
+				return content;
+			} catch (error) {
+				if (error.code === "ENOENT") return null;
+				throw error;
+			}
+		},
+		async set(key, value) {
+			await ensureInitialized();
+			if (!fsPromises) throw new Error("File storage not initialized");
+			const filePath = getFilePath(key);
+			await fsPromises.writeFile(filePath, value, "utf-8");
+		},
+		async delete(key) {
+			await ensureInitialized();
+			if (!fsPromises) throw new Error("File storage not initialized");
+			try {
+				const filePath = getFilePath(key);
+				await fsPromises.unlink(filePath);
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+			}
+		},
+		async has(key) {
+			await ensureInitialized();
+			if (!fsPromises) throw new Error("File storage not initialized");
+			try {
+				const filePath = getFilePath(key);
+				await fsPromises.access(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		async keys(prefix) {
+			await ensureInitialized();
+			if (!fsPromises || !pathModule) throw new Error("File storage not initialized");
+			const result = [];
+			try {
+				const files = await fsPromises.readdir(directory);
+				for (const file of files) if (file.endsWith(".json")) {
+					const safeKey = file.slice(0, -5);
+					try {
+						const key = Buffer.from(safeKey, "base64url").toString();
+						if (key.startsWith(prefix)) result.push(key);
+					} catch {}
+				}
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+			}
+			return result;
+		},
+		async clear(prefix) {
+			await ensureInitialized();
+			if (!fsPromises) throw new Error("File storage not initialized");
+			const keysToDelete = await this.keys(prefix);
+			for (const key of keysToDelete) await this.delete(key);
+		}
+	};
+}
+
+//#endregion
+//#region src/panoptic/v2/storage/keys.ts
+/**
+* Get the schema version key.
+*/
+function getSchemaVersionKey() {
+	return `${STORAGE_PREFIX}:schemaVersion`;
+}
+/**
+* Get the base prefix for a specific pool.
+*/
+function getPoolPrefix(chainId, poolAddress) {
+	return `${STORAGE_PREFIX}:v${SCHEMA_VERSION}:chain${chainId}:pool${poolAddress.toLowerCase()}`;
+}
+/**
+* Get the key for tracked position IDs.
+*/
+function getPositionsKey(chainId, poolAddress, account) {
+	return `${getPoolPrefix(chainId, poolAddress)}:positions:${account.toLowerCase()}`;
+}
+/**
+* Get the key for position mint metadata.
+*/
+function getPositionMetaKey(chainId, poolAddress, tokenId) {
+	return `${getPoolPrefix(chainId, poolAddress)}:positionMeta:${tokenId.toString()}`;
+}
+/**
+* Get the key for sync checkpoint.
+*/
+function getSyncCheckpointKey(chainId, poolAddress, account) {
+	return `${getPoolPrefix(chainId, poolAddress)}:sync:${account.toLowerCase()}`;
+}
+/**
+* Get the key for closed positions.
+*/
+function getClosedPositionsKey(chainId, poolAddress, account) {
+	return `${getPoolPrefix(chainId, poolAddress)}:closed:${account.toLowerCase()}`;
+}
+/**
+* Get the key for tracked chunks.
+*/
+function getTrackedChunksKey(chainId, poolAddress) {
+	return `${getPoolPrefix(chainId, poolAddress)}:chunks`;
+}
+/**
+* Get the key for pending positions.
+*/
+function getPendingPositionsKey(chainId, poolAddress, account) {
+	return `${getPoolPrefix(chainId, poolAddress)}:pending:${account.toLowerCase()}`;
+}
+/**
+* Get the key for pool metadata (tickSpacing, etc.).
+*/
+function getPoolMetaKey(chainId, poolAddress) {
+	return `${getPoolPrefix(chainId, poolAddress)}:poolMeta`;
+}
+
+//#endregion
+//#region src/panoptic/v2/storage/memoryStorage.ts
+/**
+* Creates an in-memory storage adapter.
+* Useful for testing and development.
+*
+* Data is lost when the process exits.
+*
+* @example
+* ```typescript
+* import { createMemoryStorage, createConfig } from 'panoptic-v2-sdk'
+*
+* const config = createConfig({
+*   chainId: 1n,
+*   transport: http('...'),
+*   poolAddress: '0x...',
+*   storage: createMemoryStorage(),
+* })
+* ```
+*/
+function createMemoryStorage() {
+	const store = new Map();
+	return {
+		async get(key) {
+			return store.get(key) ?? null;
+		},
+		async set(key, value) {
+			store.set(key, value);
+		},
+		async delete(key) {
+			store.delete(key);
+		},
+		async has(key) {
+			return store.has(key);
+		},
+		async keys(prefix) {
+			const result = [];
+			for (const key of store.keys()) if (key.startsWith(prefix)) result.push(key);
+			return result;
+		},
+		async clear(prefix) {
+			const keysToDelete = [];
+			for (const key of store.keys()) if (key.startsWith(prefix)) keysToDelete.push(key);
+			for (const key of keysToDelete) store.delete(key);
+		}
+	};
+}
+
+//#endregion
+//#region src/panoptic/v2/storage/serializer.ts
+/**
+* Type guard to check if a value is a tagged BigInt.
+*/
+function isBigIntTagged(value) {
+	return value !== null && typeof value === "object" && "__type" in value && value.__type === "bigint" && "value" in value && typeof value.value === "string";
+}
+/**
+* Replacer function for JSON.stringify that tags BigInt values.
+*/
+function replacer(_key, value) {
+	if (typeof value === "bigint") return {
+		__type: "bigint",
+		value: value.toString()
+	};
+	return value;
+}
+/**
+* Reviver function for JSON.parse that restores tagged BigInt values.
+*/
+function reviver(_key, value) {
+	if (isBigIntTagged(value)) return BigInt(value.value);
+	return value;
+}
+/**
+* BigInt-safe JSON serializer for the Panoptic v2 SDK.
+*
+* This serializer handles BigInt values by tagging them with a special format
+* that can be restored on parse. The format is compatible with superjson
+* patterns used in Next.js and Remix for SSR hydration.
+*
+* @example
+* ```typescript
+* import { jsonSerializer } from 'panoptic-v2-sdk'
+*
+* const data = { amount: 1000000000000000000n, nested: { value: 42n } }
+*
+* // Serialize to JSON string
+* const json = jsonSerializer.stringify(data)
+* // '{"amount":{"__type":"bigint","value":"1000000000000000000"},"nested":{"value":{"__type":"bigint","value":"42"}}}'
+*
+* // Parse back to original types
+* const parsed = jsonSerializer.parse(json)
+* // { amount: 1000000000000000000n, nested: { value: 42n } }
+* ```
+*/
+const jsonSerializer = {
+	stringify(value, space) {
+		return JSON.stringify(value, replacer, space);
+	},
+	parse(text) {
+		return JSON.parse(text, reviver);
+	}
+};
+
+//#endregion
+//#region src/panoptic/v2/sync/snapshotRecovery.ts
+/**
+* Recover position snapshot from the last dispatch transaction.
+* This is the primary recovery method - it finds the most recent dispatch()
+* call and extracts the finalPositionIdList from the calldata.
+*
+* @param params - Recovery parameters
+* @returns Snapshot recovery result
+*/
+async function recoverSnapshot(params) {
+	const { client, poolAddress, account, toBlock } = params;
+	const latestBlock = toBlock ?? await client.getBlockNumber();
+	const searchFromBlock = params.fromBlock ?? 0n;
+	const [mintEvents, burnEvents, forceExerciseEvents, liquidationEvents] = await Promise.all([
+		client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "OptionMinted",
+				inputs: [
+					{
+						type: "address",
+						name: "recipient",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "tokenId",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "balanceData",
+						indexed: false
+					}
+				]
+			},
+			args: { recipient: account },
+			fromBlock: searchFromBlock,
+			toBlock: latestBlock
+		}),
+		client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "OptionBurnt",
+				inputs: [
+					{
+						type: "address",
+						name: "recipient",
+						indexed: true
+					},
+					{
+						type: "uint128",
+						name: "positionSize",
+						indexed: false
+					},
+					{
+						type: "uint256",
+						name: "tokenId",
+						indexed: true
+					},
+					{
+						type: "int256[4]",
+						name: "premiaByLeg",
+						indexed: false
+					}
+				]
+			},
+			args: { recipient: account },
+			fromBlock: searchFromBlock,
+			toBlock: latestBlock
+		}),
+		client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "ForcedExercised",
+				inputs: [
+					{
+						type: "address",
+						name: "exercisor",
+						indexed: true
+					},
+					{
+						type: "address",
+						name: "user",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "tokenId",
+						indexed: true
+					},
+					{
+						type: "int256",
+						name: "exerciseFee",
+						indexed: false
+					}
+				]
+			},
+			args: { user: account },
+			fromBlock: searchFromBlock,
+			toBlock: latestBlock
+		}),
+		client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "AccountLiquidated",
+				inputs: [
+					{
+						type: "address",
+						name: "liquidator",
+						indexed: true
+					},
+					{
+						type: "address",
+						name: "liquidatee",
+						indexed: true
+					},
+					{
+						type: "int256",
+						name: "bonusAmounts",
+						indexed: false
+					}
+				]
+			},
+			args: { liquidatee: account },
+			fromBlock: searchFromBlock,
+			toBlock: latestBlock
+		})
+	]);
+	const allEvents = [
+		...mintEvents,
+		...burnEvents,
+		...forceExerciseEvents,
+		...liquidationEvents
+	].sort((a, b) => {
+		const blockDiff = Number(b.blockNumber - a.blockNumber);
+		if (blockDiff !== 0) return blockDiff;
+		return Number(b.logIndex - a.logIndex);
+	});
+	const seen = new Set();
+	const uniqueEvents = allEvents.filter((e) => {
+		if (seen.has(e.transactionHash)) return false;
+		seen.add(e.transactionHash);
+		return true;
+	});
+	for (const event of uniqueEvents) try {
+		const [tx, block] = await Promise.all([client.getTransaction({ hash: event.transactionHash }), client.getBlock({ blockNumber: event.blockNumber })]);
+		const decoded = decodeDispatchCalldata(tx.input);
+		if (!decoded) continue;
+		if (decoded.targetAccount && decoded.targetAccount.toLowerCase() !== account.toLowerCase()) continue;
+		return {
+			success: true,
+			positionIds: decoded.positionIds,
+			blockNumber: event.blockNumber,
+			blockHash: block.hash,
+			transactionHash: event.transactionHash
+		};
+	} catch {}
+	return null;
+}
+/**
+* Recover position snapshot from a specific dispatch transaction hash.
+*
+* This is an O(1) alternative to {@link recoverSnapshot} when you already
+* know the tx hash of the most recent dispatch. It fetches the transaction,
+* decodes the `finalPositionIdList` from the calldata, and returns the result
+* — no event scanning required.
+*
+* @param params - Recovery parameters including the transaction hash
+* @returns Snapshot recovery result, or null if the tx is not a dispatch call
+*
+* @example
+* ```typescript
+* const snapshot = await recoverSnapshotFromTx({
+*   client,
+*   transactionHash: '0xabc...',
+* })
+* if (snapshot) {
+*   console.log('Open positions:', snapshot.positionIds)
+* }
+* ```
+*/
+async function recoverSnapshotFromTx(params) {
+	const { client, transactionHash, account, pool } = params;
+	const tx = await client.getTransaction({ hash: transactionHash });
+	if (tx.blockNumber == null) return null;
+	if (pool && tx.to?.toLowerCase() !== pool.toLowerCase()) return null;
+	const decoded = decodeDispatchCalldata(tx.input);
+	if (!decoded) return null;
+	if (account) {
+		if (decoded.targetAccount) {
+			if (decoded.targetAccount.toLowerCase() !== account.toLowerCase()) return null;
+		} else if (tx.from.toLowerCase() !== account.toLowerCase()) return null;
+	}
+	const blockNumber = tx.blockNumber;
+	const block = await client.getBlock({ blockNumber });
+	return {
+		success: true,
+		positionIds: decoded.positionIds,
+		blockNumber,
+		blockHash: block.hash,
+		transactionHash
+	};
+}
+/**
+* Decode position IDs from dispatch calldata.
+*
+* @param input - Transaction input data
+* @returns Decoded dispatch data or null if not a dispatch call
+*/
+function decodeDispatchCalldata(input) {
+	const direct = decodeDirectDispatch(input);
+	if (direct) return direct;
+	return decodeWrappedDispatch(input);
+}
+/**
+* Try to decode input as a direct dispatch or dispatchFrom call.
+*/
+function decodeDirectDispatch(input) {
+	try {
+		const decoded = decodeFunctionData({
+			abi: panopticPoolV2Abi,
+			data: input
+		});
+		if (decoded.functionName === "dispatch") {
+			const args = decoded.args;
+			return { positionIds: [...args[1]] };
+		}
+		if (decoded.functionName === "dispatchFrom") {
+			const args = decoded.args;
+			return {
+				positionIds: [...args[3]],
+				targetAccount: args[1]
+			};
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* 4-byte function selectors for dispatch/dispatchFrom, derived from the generated ABI.
+* Used for scanning raw calldata inside smart contract wallet wrappers.
+*/
+const DISPATCH_SELECTOR = toFunctionSelector(panopticPoolV2Abi.find((e) => e.type === "function" && e.name === "dispatch")).slice(2);
+const DISPATCH_FROM_SELECTOR = toFunctionSelector(panopticPoolV2Abi.find((e) => e.type === "function" && e.name === "dispatchFrom")).slice(2);
+/**
+* Scan raw transaction input for embedded dispatch calldata.
+*
+* Smart contract wallets (Safe, Turnkey, ERC-4337) and vault managers
+* wrap dispatch calls inside executeBatch → manage → dispatch chains.
+* Instead of decoding each wrapper layer, we scan the raw hex for the
+* dispatch function selector and attempt to decode from that offset.
+*
+* This handles arbitrary nesting depth without knowing wrapper ABIs.
+*/
+function decodeWrappedDispatch(input) {
+	const hex = input.slice(2).toLowerCase();
+	const selectors = [DISPATCH_SELECTOR, DISPATCH_FROM_SELECTOR];
+	const results = [];
+	let offset = 0;
+	while (offset < hex.length) {
+		let earliestIdx = -1;
+		for (const selector of selectors) {
+			const idx = hex.indexOf(selector, offset);
+			if (idx !== -1 && (earliestIdx === -1 || idx < earliestIdx)) earliestIdx = idx;
+		}
+		if (earliestIdx === -1) break;
+		const candidate = `0x${hex.slice(earliestIdx)}`;
+		const result = decodeDirectDispatch(candidate);
+		if (result) results.push(result);
+		offset = earliestIdx + 8;
+	}
+	return results.length > 0 ? results[results.length - 1] : null;
+}
+
+//#endregion
+//#region src/panoptic/v2/sync/getTrackedPositionIds.ts
+/**
+* Get all tracked position IDs for an account from local cache.
+*
+* This function reads from the storage adapter without making RPC calls.
+* The positions returned may include closed positions if the cache is stale.
+* Use `getPositions()` for authoritative on-chain data.
+*
+* @param params - Query parameters
+* @returns Array of position token IDs
+*/
+async function getTrackedPositionIds(params) {
+	const { chainId, poolAddress, account, storage } = params;
+	const key = getPositionsKey(chainId, poolAddress, account);
+	const data = await storage.get(key);
+	if (!data) return [];
+	try {
+		const positionIds = jsonSerializer.parse(data);
+		return positionIds;
+	} catch {
+		return [];
+	}
+}
+/**
+* Check if a specific position ID is tracked.
+*
+* @param params - Query parameters
+* @param tokenId - Token ID to check
+* @returns Whether the position is tracked
+*/
+async function isPositionTracked(params, tokenId) {
+	const positionIds = await getTrackedPositionIds(params);
+	return positionIds.some((id) => id === tokenId);
+}
+/**
+* Clear all tracked positions for an account.
+*
+* @param params - Query parameters
+*/
+async function clearTrackedPositions(params) {
+	const { chainId, poolAddress, account, storage } = params;
+	const key = getPositionsKey(chainId, poolAddress, account);
+	await storage.delete(key);
+}
+/**
+* Get the authoritative list of open position IDs from the chain.
+*
+* Recovers the `finalPositionIdList` from the account's most recent
+* `dispatch()` transaction calldata. This is the on-chain–validated set of
+* open positions (verified against `s_positionsHash` by the contract) and
+* requires only a few RPC calls regardless of account history length.
+*
+* This is the recommended way to get position IDs for `existingPositionIds`
+* (openPosition) and `positionIdList` (closePosition).
+*
+* If `storage` is provided, the local cache is updated with the result.
+*
+* @param params - Query parameters
+* @returns Array of currently open position token IDs, or null if no snapshot was found
+*/
+async function getOpenPositionIds(params) {
+	const { client, chainId, poolAddress, account, storage, lastDispatchTxHash, fromBlock } = params;
+	let snapshot = null;
+	if (lastDispatchTxHash) try {
+		snapshot = await recoverSnapshotFromTx({
+			client,
+			transactionHash: lastDispatchTxHash,
+			account,
+			pool: poolAddress
+		});
+	} catch {
+		snapshot = null;
+	}
+	if (!snapshot) snapshot = await recoverSnapshot({
+		client,
+		poolAddress,
+		account,
+		fromBlock
+	});
+	if (!snapshot) return null;
+	if (storage) {
+		const key = getPositionsKey(chainId, poolAddress, account);
+		await storage.set(key, jsonSerializer.stringify(snapshot.positionIds));
+	}
+	return snapshot.positionIds;
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/position.ts
+/**
+* Resolve the position ID list: use the explicit param if provided,
+* otherwise read from storage. Throws if neither is available.
+*/
+async function resolvePositionIds$1(explicit, storage, chainId, poolAddress, account) {
+	if (explicit !== void 0) return explicit;
+	if (storage && chainId !== void 0) return getTrackedPositionIds({
+		chainId,
+		poolAddress,
+		account,
+		storage
+	});
+	throw new MissingPositionIdsError();
+}
+/**
+* Save a position ID list to storage.
+*/
+async function savePositionIds$1(storage, chainId, poolAddress, account, positionIds) {
+	const key = getPositionsKey(chainId, poolAddress, account);
+	await storage.set(key, jsonSerializer.stringify(positionIds));
+}
+/**
+* Open a new position using dispatch.
+*
+* @param params - Position parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* import { MIN_TICK, MAX_TICK } from '@panoptic/sdk'
+*
+* const result = await openPosition({
+*   client,
+*   walletClient,
+*   account,
+*   poolAddress,
+*   existingPositionIds: [], // Existing positions held before this mint
+*   tokenId,
+*   positionSize: 1n,
+*   tickLimitLow: MIN_TICK,
+*   tickLimitHigh: MAX_TICK,
+*   swapAtMint: false, // true for covered/single-sided exposure
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function openPosition(params) {
+	const { client, walletClient, account, poolAddress, existingPositionIds: explicitIds, tokenId, positionSize, tickLimitLow, tickLimitHigh, spreadLimit = 0n, swapAtMint = false, usePremiaAsCollateral = false, builderCode = 0n, storage, chainId, txOverrides } = params;
+	if (tickLimitLow > tickLimitHigh) throw new InvalidTickLimitsError(tickLimitLow, tickLimitHigh);
+	const existingPositionIds = await resolvePositionIds$1(explicitIds, storage, chainId, poolAddress, account);
+	const positionIdList = [tokenId];
+	const finalPositionIdList = [...existingPositionIds, tokenId];
+	const positionSizes = [positionSize];
+	const tickLimits$1 = swapAtMint ? [
+		Number(tickLimitHigh),
+		Number(tickLimitLow),
+		Number(spreadLimit)
+	] : [
+		Number(tickLimitLow),
+		Number(tickLimitHigh),
+		Number(spreadLimit)
+	];
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatch",
+		args: [
+			positionIdList,
+			finalPositionIdList,
+			positionSizes,
+			[tickLimits$1],
+			usePremiaAsCollateral,
+			builderCode
+		],
+		txOverrides
+	});
+}
+/**
+* Build the dispatch calldata for opening a position without executing.
+* Returns the target address and encoded calldata, suitable for manual
+* transaction construction (e.g. RFQ broadcast-reconstruct flow).
+*
+* @param params - Position parameters (existingPositionIds required, no storage resolution)
+* @returns { to, data } — contract address and encoded dispatch calldata
+*/
+function buildOpenPositionCalldata(params) {
+	const { poolAddress, existingPositionIds, tokenId, positionSize, tickLimitLow, tickLimitHigh, spreadLimit = 0n, swapAtMint = false, usePremiaAsCollateral = false, builderCode = 0n } = params;
+	if (tickLimitLow > tickLimitHigh) throw new InvalidTickLimitsError(tickLimitLow, tickLimitHigh);
+	const positionIdList = [tokenId];
+	const finalPositionIdList = [...existingPositionIds, tokenId];
+	const positionSizes = [positionSize];
+	const tickLimits$1 = swapAtMint ? [
+		Number(tickLimitHigh),
+		Number(tickLimitLow),
+		Number(spreadLimit)
+	] : [
+		Number(tickLimitLow),
+		Number(tickLimitHigh),
+		Number(spreadLimit)
+	];
+	const data = encodeFunctionData({
+		abi: panopticPoolV2Abi,
+		functionName: "dispatch",
+		args: [
+			positionIdList,
+			finalPositionIdList,
+			positionSizes,
+			[tickLimits$1],
+			usePremiaAsCollateral,
+			builderCode
+		]
+	});
+	return {
+		to: poolAddress,
+		data
+	};
+}
+/**
+* Open position and wait for confirmation.
+*/
+async function openPositionAndWait(params) {
+	const result = await openPosition(params);
+	const receipt = await result.wait();
+	const { storage, chainId, account, poolAddress, tokenId, existingPositionIds: explicitIds } = params;
+	if (storage && chainId !== void 0) {
+		const base = explicitIds ?? await getTrackedPositionIds({
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		await savePositionIds$1(storage, chainId, poolAddress, account, [...base, tokenId]);
+	}
+	return receipt;
+}
+/**
+* Close an existing position using dispatch.
+*
+* @param params - Close parameters
+* @returns TxResult
+*/
+async function closePosition(params) {
+	const { client, walletClient, account, poolAddress, positionIdList: explicitList, tokenId, tickLimitLow, tickLimitHigh, spreadLimit = 0n, swapAtMint = false, usePremiaAsCollateral = false, builderCode = 0n, storage, chainId, txOverrides } = params;
+	if (tickLimitLow > tickLimitHigh) throw new InvalidTickLimitsError(tickLimitLow, tickLimitHigh);
+	const positionIdList = await resolvePositionIds$1(explicitList, storage, chainId, poolAddress, account);
+	const finalPositionIdList = positionIdList.filter((id) => id !== tokenId);
+	const tickLimits$1 = swapAtMint ? [
+		Number(tickLimitHigh),
+		Number(tickLimitLow),
+		Number(spreadLimit)
+	] : [
+		Number(tickLimitLow),
+		Number(tickLimitHigh),
+		Number(spreadLimit)
+	];
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatch",
+		args: [
+			[tokenId],
+			finalPositionIdList,
+			[0n],
+			[tickLimits$1],
+			usePremiaAsCollateral,
+			builderCode
+		],
+		txOverrides
+	});
+}
+/**
+* Close position and wait for confirmation.
+*/
+async function closePositionAndWait(params) {
+	const result = await closePosition(params);
+	const receipt = await result.wait();
+	const { storage, chainId, account, poolAddress, tokenId, positionIdList: explicitList } = params;
+	if (storage && chainId !== void 0) {
+		const base = explicitList ?? await getTrackedPositionIds({
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		await savePositionIds$1(storage, chainId, poolAddress, account, base.filter((id) => id !== tokenId));
+	}
+	return receipt;
+}
+/**
+* Roll a position (close one, open another) in a single transaction.
+*
+* @param params - Roll parameters
+* @returns TxResult
+*/
+async function rollPosition(params) {
+	const { client, walletClient, account, poolAddress, positionIdList: explicitList, oldTokenId, oldPositionSize, newTokenId, newPositionSize, closeTickLimitLow, closeTickLimitHigh, closeSpreadLimit = 0n, closeSwapAtMint = false, openTickLimitLow, openTickLimitHigh, openSpreadLimit = 0n, openSwapAtMint = false, usePremiaAsCollateral = false, builderCode = 0n, storage, chainId, txOverrides } = params;
+	if (closeTickLimitLow > closeTickLimitHigh) throw new InvalidTickLimitsError(closeTickLimitLow, closeTickLimitHigh);
+	if (openTickLimitLow > openTickLimitHigh) throw new InvalidTickLimitsError(openTickLimitLow, openTickLimitHigh);
+	const positionIdList = await resolvePositionIds$1(explicitList, storage, chainId, poolAddress, account);
+	const finalPositionIdList = positionIdList.filter((id) => id !== oldTokenId).concat([newTokenId]);
+	const positionSizes = [oldPositionSize, newPositionSize];
+	const closeLimits = closeSwapAtMint ? [
+		Number(closeTickLimitHigh),
+		Number(closeTickLimitLow),
+		Number(closeSpreadLimit)
+	] : [
+		Number(closeTickLimitLow),
+		Number(closeTickLimitHigh),
+		Number(closeSpreadLimit)
+	];
+	const openLimits = openSwapAtMint ? [
+		Number(openTickLimitHigh),
+		Number(openTickLimitLow),
+		Number(openSpreadLimit)
+	] : [
+		Number(openTickLimitLow),
+		Number(openTickLimitHigh),
+		Number(openSpreadLimit)
+	];
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatch",
+		args: [
+			positionIdList,
+			finalPositionIdList,
+			positionSizes,
+			[closeLimits, openLimits],
+			usePremiaAsCollateral,
+			builderCode
+		],
+		txOverrides
+	});
+}
+/**
+* Roll position and wait for confirmation.
+*/
+async function rollPositionAndWait(params) {
+	const result = await rollPosition(params);
+	const receipt = await result.wait();
+	const { storage, chainId, account, poolAddress, oldTokenId, newTokenId, positionIdList: explicitList } = params;
+	if (storage && chainId !== void 0) {
+		const base = explicitList ?? await getTrackedPositionIds({
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		const updated = base.filter((id) => id !== oldTokenId).concat([newTokenId]);
+		await savePositionIds$1(storage, chainId, poolAddress, account, updated);
+	}
+	return receipt;
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/dispatch.ts
+/**
+* Execute a raw dispatch operation.
+* This is the low-level function for multi-position operations.
+*
+* @param params - Dispatch parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* // Open multiple positions atomically
+* const result = await dispatch({
+*   client,
+*   walletClient,
+*   account,
+*   poolAddress,
+*   positionIdList: [],
+*   finalPositionIdList: [tokenId1, tokenId2],
+*   positionSizes: [size1, size2],
+*   tickAndSpreadLimits: [limits1, limits2],
+* })
+* ```
+*/
+async function dispatch(params) {
+	const { client, walletClient, account, poolAddress, positionIdList, finalPositionIdList, positionSizes, tickAndSpreadLimits, usePremiaAsCollateral = false, builderCode = 0n, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatch",
+		args: [
+			positionIdList,
+			finalPositionIdList,
+			positionSizes.map((s) => BigInt(s)),
+			tickAndSpreadLimits.map((t) => [
+				Number(t[0]),
+				Number(t[1]),
+				Number(t[2])
+			]),
+			usePremiaAsCollateral,
+			builderCode
+		],
+		txOverrides
+	});
+}
+/**
+* Execute dispatch and wait for confirmation.
+*/
+async function dispatchAndWait(params) {
+	const result = await dispatch(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/batch/validate.ts
+/**
+* Run all batch-level and item-level validations.
+* Pure function; never throws. Empty array means "ready to build".
+*/
+function validateBatch(params) {
+	const { items, existingPositionIds } = params;
+	const diagnostics = [];
+	if (items.length === 0) {
+		diagnostics.push({
+			itemIndex: -1n,
+			tokenId: 0n,
+			code: "empty-batch",
+			message: "Batch is empty."
+		});
+		return diagnostics;
+	}
+	const head = items[0];
+	if (!head) return diagnostics;
+	const firstPool = head.poolAddress.toLowerCase();
+	const existing = new Set(existingPositionIds);
+	const seen = new Map();
+	items.forEach((item, idx) => {
+		const itemIndex = BigInt(idx);
+		if (item.poolAddress.toLowerCase() !== firstPool) diagnostics.push({
+			itemIndex,
+			tokenId: item.tokenId,
+			code: "cross-pool",
+			message: `Item ${idx} targets pool ${item.poolAddress}, expected ${head.poolAddress}.`
+		});
+		if (item.tickLimitLow > item.tickLimitHigh) diagnostics.push({
+			itemIndex,
+			tokenId: item.tokenId,
+			code: "invalid-tick-limits",
+			message: `Item ${idx} tickLimitLow (${item.tickLimitLow}) > tickLimitHigh (${item.tickLimitHigh}).`
+		});
+		if (item.kind === "mint") {
+			if (item.positionSize <= 0n) diagnostics.push({
+				itemIndex,
+				tokenId: item.tokenId,
+				code: "invalid-position-size",
+				message: `Mint at index ${idx} must have positionSize > 0.`
+			});
+			if (existing.has(item.tokenId)) diagnostics.push({
+				itemIndex,
+				tokenId: item.tokenId,
+				code: "mint-already-onchain",
+				message: `Mint at index ${idx} targets tokenId ${item.tokenId} which is already open on-chain.`
+			});
+		} else if (!existing.has(item.tokenId)) diagnostics.push({
+			itemIndex,
+			tokenId: item.tokenId,
+			code: "burn-not-found",
+			message: `Burn at index ${idx} targets tokenId ${item.tokenId} which is not in the account's positions.`
+		});
+		const prior = seen.get(item.tokenId);
+		if (prior !== void 0) diagnostics.push({
+			itemIndex,
+			tokenId: item.tokenId,
+			code: "duplicate-tokenid-in-batch",
+			message: `Item ${idx} duplicates tokenId ${item.tokenId} also at index ${prior}.`
+		});
+		else seen.set(item.tokenId, itemIndex);
+	});
+	return diagnostics;
+}
+
+//#endregion
+//#region src/panoptic/v2/batch/build.ts
+/**
+* Build dispatch() args from a list of batch ops + the account's current
+* on-chain positionIdList. Returns diagnostics instead of throwing so callers
+* (UIs, bots) can render conflicts before deciding what to do.
+*
+* The order in `items` is preserved as the operation order in `positionIdList`,
+* `positionSizes`, and `tickAndSpreadLimits`. `finalPositionIdList` is the
+* post-execution state: existing minus burns, plus mints.
+*/
+function buildBatchDispatchArgs(params) {
+	const { items, existingPositionIds, usePremiaAsCollateral = false, builderCode = 0n } = params;
+	const diagnostics = validateBatch({
+		items,
+		existingPositionIds
+	});
+	if (diagnostics.length > 0) return {
+		args: null,
+		diagnostics
+	};
+	const positionIdList = items.map((i) => i.tokenId);
+	const positionSizes = items.map((i) => i.kind === "mint" ? i.positionSize : 0n);
+	const tickAndSpreadLimits = items.map((i) => {
+		const low = i.tickLimitLow <= i.tickLimitHigh ? i.tickLimitLow : i.tickLimitHigh;
+		const high = i.tickLimitLow <= i.tickLimitHigh ? i.tickLimitHigh : i.tickLimitLow;
+		const spread = i.kind === "mint" ? i.spreadLimit : 0n;
+		return i.swapAtMint ? [
+			high,
+			low,
+			spread
+		] : [
+			low,
+			high,
+			spread
+		];
+	});
+	const mintIds = items.filter((i) => i.kind === "mint").map((i) => i.tokenId);
+	const burnIds = new Set(items.filter((i) => i.kind === "burn").map((i) => i.tokenId));
+	const mintIdSet = new Set(mintIds);
+	const finalPositionIdList = [...existingPositionIds.filter((id) => !burnIds.has(id) && !mintIdSet.has(id)), ...mintIds];
+	return {
+		args: {
+			positionIdList,
+			finalPositionIdList,
+			positionSizes,
+			tickAndSpreadLimits,
+			usePremiaAsCollateral,
+			builderCode
+		},
+		diagnostics: []
+	};
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/executeBatchDispatch.ts
+/**
+* Build dispatch args from a batch and submit them as a single transaction.
+*
+* Throws `BatchValidationError` (with the full diagnostics list) when the batch
+* fails validation. Callers that want to render diagnostics in UI should run
+* `buildBatchDispatchArgs` or `simulateBatchDispatch` first.
+*/
+async function executeBatchDispatch(params) {
+	const { client, walletClient, account, poolAddress, items, existingPositionIds, usePremiaAsCollateral = false, builderCode = 0n, txOverrides } = params;
+	const { args, diagnostics } = buildBatchDispatchArgs({
+		items,
+		existingPositionIds,
+		usePremiaAsCollateral,
+		builderCode
+	});
+	if (args === null) throw new BatchValidationError(diagnostics);
+	return dispatch({
+		client,
+		walletClient,
+		account,
+		poolAddress,
+		positionIdList: args.positionIdList,
+		finalPositionIdList: args.finalPositionIdList,
+		positionSizes: args.positionSizes,
+		tickAndSpreadLimits: args.tickAndSpreadLimits,
+		usePremiaAsCollateral: args.usePremiaAsCollateral,
+		builderCode: args.builderCode,
+		txOverrides
+	});
+}
+/**
+* Execute a batch dispatch and wait for confirmation.
+*/
+async function executeBatchDispatchAndWait(params) {
+	const result = await executeBatchDispatch(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/liquidate.ts
+/**
+* Liquidate an undercollateralized account using dispatchFrom.
+*
+* The liquidator calls dispatchFrom to close the liquidatee's positions
+* and receive a bonus.
+*
+* @param params - Liquidation parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await liquidate({
+*   client,
+*   walletClient,
+*   account: liquidatorAddress,
+*   poolAddress,
+*   liquidatee: undercollateralizedAccount,
+*   positionIdListFrom: liquidatorPositions,
+*   positionIdListTo: liquidateePositions,
+*   positionIdListToFinal: [], // Close all positions
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function liquidate(params) {
+	const { client, walletClient, account, poolAddress, liquidatee, positionIdListFrom, positionIdListTo, positionIdListToFinal, usePremiaAsCollateral = 0n, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatchFrom",
+		args: [
+			positionIdListFrom,
+			liquidatee,
+			positionIdListTo,
+			positionIdListToFinal,
+			usePremiaAsCollateral
+		],
+		txOverrides
+	});
+}
+/**
+* Liquidate and wait for confirmation.
+*/
+async function liquidateAndWait(params) {
+	const result = await liquidate(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/bot/index.ts
+/**
+* Assert that data is fresh (not stale).
+*
+* Throws StaleDataError if the data's block timestamp is older than maxAgeSeconds.
+*
+* @param data - Any SDK data with _meta field
+* @param maxAgeSeconds - Maximum allowed age in seconds
+* @param currentTimestamp - Current timestamp (defaults to Date.now() / 1000)
+* @throws StaleDataError if data is stale
+*
+* @example
+* ```typescript
+* const pool = await getPool({ client, poolAddress })
+* assertFresh(pool, 60) // Must be < 60 seconds old
+* ```
+*/
+function assertFresh(data, maxAgeSeconds, currentTimestamp) {
+	const maxAge = BigInt(maxAgeSeconds);
+	const now = currentTimestamp !== void 0 ? BigInt(currentTimestamp) : BigInt(Math.floor(Date.now() / 1e3));
+	const blockTimestamp = data._meta.blockTimestamp;
+	const age = now - blockTimestamp;
+	if (age > maxAge) throw new StaleDataError(blockTimestamp, now, age);
+}
+/**
+* Assert that a pool is healthy.
+*
+* Throws UnhealthyPoolError if the pool health status is not 'active'.
+*
+* @param pool - Pool data from getPool()
+* @throws UnhealthyPoolError if pool is unhealthy (low_liquidity or paused)
+*
+* @example
+* ```typescript
+* const pool = await getPool({ client, poolAddress })
+* assertHealthy(pool) // Throws if pool is paused or has low liquidity
+* ```
+*/
+function assertHealthy(pool) {
+	if (pool.healthStatus !== "active") throw new UnhealthyPoolError(pool.healthStatus);
+}
+/**
+* Assert that trading is allowed on a pool.
+*
+* Checks both pool health and safe mode status. Throws appropriate errors
+* if trading is restricted.
+*
+* @param pool - Pool data from getPool()
+* @param safeMode - Optional SafeModeState from getSafeMode()
+* @throws UnhealthyPoolError if pool is unhealthy
+* @throws SafeModeError if pool is in restricted or emergency safe mode
+*
+* @example
+* ```typescript
+* const pool = await getPool({ client, poolAddress })
+* const safeMode = await getSafeMode({ client, poolAddress })
+* assertTradeable(pool, safeMode)
+* ```
+*/
+function assertTradeable(pool, safeMode) {
+	assertHealthy(pool);
+	if (safeMode && safeMode.mode !== "normal") throw new SafeModeError(safeMode.mode, safeMode.reason ?? "Trading restricted");
+}
+/**
+* Assert that minting is allowed.
+*
+* @param safeMode - SafeModeState from getSafeMode()
+* @throws SafeModeError if minting is not allowed
+*
+* @example
+* ```typescript
+* const safeMode = await getSafeMode({ client, poolAddress })
+* assertCanMint(safeMode)
+* await openPosition({ ... })
+* ```
+*/
+function assertCanMint(safeMode) {
+	if (!safeMode.canMint) throw new SafeModeError(safeMode.mode, safeMode.reason ?? "Minting not allowed");
+}
+/**
+* Assert that burning is allowed.
+*
+* @param safeMode - SafeModeState from getSafeMode()
+* @throws SafeModeError if burning is not allowed
+*/
+function assertCanBurn(safeMode) {
+	if (!safeMode.canBurn) throw new SafeModeError(safeMode.mode, safeMode.reason ?? "Burning not allowed");
+}
+/**
+* Assert that liquidations are allowed.
+*
+* @param safeMode - SafeModeState from getSafeMode()
+* @throws SafeModeError if liquidations are not allowed
+*/
+function assertCanLiquidate(safeMode) {
+	if (!safeMode.canLiquidate) throw new SafeModeError(safeMode.mode, safeMode.reason ?? "Liquidations not allowed");
+}
+/**
+* Assert that force exercise is allowed.
+*
+* @param safeMode - SafeModeState from getSafeMode()
+* @throws SafeModeError if force exercise is not allowed
+*/
+function assertCanForceExercise(safeMode) {
+	if (!safeMode.canForceExercise) throw new SafeModeError(safeMode.mode, safeMode.reason ?? "Force exercise not allowed");
+}
+/**
+* Common retryable RPC error codes.
+*/
+const RETRYABLE_RPC_CODES = new Set([
+	-32e3,
+	-32001,
+	-32002,
+	-32003,
+	-32005,
+	-32097,
+	-32098,
+	-32099
+]);
+/**
+* Common retryable error message patterns.
+*/
+const RETRYABLE_PATTERNS = [
+	/timeout/i,
+	/timed out/i,
+	/rate limit/i,
+	/too many requests/i,
+	/429/i,
+	/503/i,
+	/504/i,
+	/502/i,
+	/connection refused/i,
+	/connection reset/i,
+	/network error/i,
+	/econnreset/i,
+	/econnrefused/i,
+	/etimedout/i,
+	/socket hang up/i,
+	/temporarily unavailable/i,
+	/service unavailable/i,
+	/server error/i,
+	/internal error/i,
+	/nonce too low/i,
+	/replacement transaction underpriced/i,
+	/already known/i
+];
+/**
+* Check if an error is a retryable RPC error.
+*
+* Returns true for transient errors that may succeed on retry:
+* - Timeouts
+* - Rate limits
+* - Connection errors
+* - Server errors (5xx)
+* - Nonce errors (recoverable with correct nonce)
+*
+* @param error - The error to check
+* @returns True if the error is likely retryable
+*
+* @example
+* ```typescript
+* try {
+*   await openPosition({ ... })
+* } catch (error) {
+*   if (isRetryableRpcError(error)) {
+*     // Wait and retry
+*     await sleep(1000)
+*     await openPosition({ ... })
+*   } else {
+*     throw error // Non-retryable, propagate
+*   }
+* }
+* ```
+*/
+function isRetryableRpcError(error) {
+	if (error === null || error === void 0) return false;
+	if (typeof error === "object") {
+		const errorObj = error;
+		if (typeof errorObj.code === "number" && RETRYABLE_RPC_CODES.has(errorObj.code)) return true;
+		if (errorObj.cause && isRetryableRpcError(errorObj.cause)) return true;
+		if (errorObj.details && typeof errorObj.details === "object") {
+			const details = errorObj.details;
+			if (typeof details.code === "number" && RETRYABLE_RPC_CODES.has(details.code)) return true;
+		}
+	}
+	const message = getErrorMessage(error);
+	if (message) {
+		for (const pattern of RETRYABLE_PATTERNS) if (pattern.test(message)) return true;
+	}
+	return false;
+}
+/**
+* Extract error message from various error types.
+*/
+function getErrorMessage(error) {
+	if (typeof error === "string") return error;
+	if (error instanceof Error) return error.message;
+	if (typeof error === "object" && error !== null) {
+		const errorObj = error;
+		if (typeof errorObj.message === "string") return errorObj.message;
+		if (typeof errorObj.shortMessage === "string") return errorObj.shortMessage;
+	}
+	return void 0;
+}
+/**
+* Check if an error is a nonce-related error that can be recovered.
+*
+* @param error - The error to check
+* @returns True if this is a nonce error
+*/
+function isNonceError(error) {
+	const message = getErrorMessage(error);
+	if (!message) return false;
+	return /nonce too low/i.test(message) || /nonce too high/i.test(message) || /already known/i.test(message);
+}
+/**
+* Check if an error is a gas-related error that can be recovered.
+*
+* @param error - The error to check
+* @returns True if this is a gas error
+*/
+function isGasError(error) {
+	const message = getErrorMessage(error);
+	if (!message) return false;
+	return /replacement transaction underpriced/i.test(message) || /gas too low/i.test(message) || /intrinsic gas too low/i.test(message) || /max fee per gas less than block base fee/i.test(message);
+}
+
+//#endregion
+//#region src/panoptic/v2/sync/reorgHandling.ts
+/**
+* Detect chain reorganization by comparing stored block hash with current chain.
+*
+* @param params - Detection parameters
+* @returns Reorg detection result
+*/
+async function detectReorg(params) {
+	const { client, chainId, poolAddress, account, storage } = params;
+	const checkpointKey = getSyncCheckpointKey(chainId, poolAddress, account);
+	const checkpointData = await storage.get(checkpointKey);
+	if (!checkpointData) return { detected: false };
+	const checkpoint = jsonSerializer.parse(checkpointData);
+	try {
+		const block = await client.getBlock({ blockNumber: checkpoint.lastBlock });
+		if (block.hash !== checkpoint.lastBlockHash) return {
+			detected: true,
+			reorgBlock: checkpoint.lastBlock,
+			expectedHash: checkpoint.lastBlockHash,
+			actualHash: block.hash,
+			blocksToResync: REORG_DEPTH
+		};
+		return { detected: false };
+	} catch (error) {
+		return {
+			detected: true,
+			reorgBlock: checkpoint.lastBlock,
+			expectedHash: checkpoint.lastBlockHash,
+			actualHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+			blocksToResync: REORG_DEPTH
+		};
+	}
+}
+/**
+* Calculate the safe resync block after a reorg.
+*
+* @param reorgBlock - Block where reorg was detected
+* @param reorgDepth - Number of blocks to roll back (default: REORG_DEPTH = 128)
+* @returns Safe block to resync from
+*/
+function calculateResyncBlock(reorgBlock, reorgDepth = REORG_DEPTH) {
+	if (reorgBlock <= reorgDepth) return 0n;
+	return reorgBlock - reorgDepth;
+}
+/**
+* Save a sync checkpoint.
+*
+* @param params - Checkpoint parameters
+*/
+async function saveCheckpoint(params) {
+	const { storage, chainId, poolAddress, account, lastBlock, lastBlockHash, positionIds } = params;
+	const checkpoint = {
+		chainId,
+		poolAddress,
+		account,
+		lastBlock,
+		lastBlockHash,
+		positionIds,
+		createdAt: BigInt(Math.floor(Date.now() / 1e3))
+	};
+	const key = getSyncCheckpointKey(chainId, poolAddress, account);
+	await storage.set(key, jsonSerializer.stringify(checkpoint));
+}
+/**
+* Load a sync checkpoint.
+*
+* @param storage - Storage adapter
+* @param chainId - Chain ID
+* @param poolAddress - Pool address
+* @param account - Account address
+* @returns Checkpoint or null if not found
+*/
+async function loadCheckpoint(storage, chainId, poolAddress, account) {
+	const key = getSyncCheckpointKey(chainId, poolAddress, account);
+	const data = await storage.get(key);
+	if (!data) return null;
+	return jsonSerializer.parse(data);
+}
+/**
+* Clear a sync checkpoint.
+*
+* @param storage - Storage adapter
+* @param chainId - Chain ID
+* @param poolAddress - Pool address
+* @param account - Account address
+*/
+async function clearCheckpoint(storage, chainId, poolAddress, account) {
+	const key = getSyncCheckpointKey(chainId, poolAddress, account);
+	await storage.delete(key);
+}
+/**
+* Verify block continuity for a range of blocks.
+* This checks that each block's parentHash matches the previous block's hash.
+*
+* @param client - viem public client
+* @param fromBlock - Starting block
+* @param toBlock - Ending block
+* @returns True if blocks form a valid chain
+*/
+async function verifyBlockContinuity(client, fromBlock, toBlock) {
+	if (fromBlock >= toBlock) return true;
+	const sampleSize = Math.min(5, Number(toBlock - fromBlock));
+	const step = (toBlock - fromBlock) / BigInt(sampleSize);
+	let previousHash = null;
+	for (let i = 0; i <= sampleSize; i++) {
+		const blockNumber = fromBlock + step * BigInt(i);
+		const block = await client.getBlock({ blockNumber });
+		if (previousHash !== null && i > 0) {}
+		previousHash = block.hash;
+	}
+	return true;
+}
+
+//#endregion
+//#region src/panoptic/v2/sync/syncPositions.ts
+/**
+* Synchronize positions for an account.
+*
+* This function:
+* 1. Checks for existing checkpoint
+* 2. If no checkpoint: recovers from dispatch() calldata or falls back to full event scan
+* 3. If checkpoint exists: detects reorgs and syncs incrementally
+* 4. Persists positions and checkpoint to storage
+*
+* @param params - Sync parameters
+* @returns Sync result with position count and sync metadata
+* @throws SyncTimeoutError if sync exceeds timeout
+* @throws ProviderLagError if provider is behind minBlockNumber
+* @throws PositionSnapshotNotFoundError if no positions found and no snapshot available
+*/
+async function syncPositions(params) {
+	const { client, chainId, poolAddress, account, storage, syncTimeout = 300000n, onUpdate, minBlockNumber, snapshotTxHash } = params;
+	const startTime = Date.now();
+	const checkTimeout = () => {
+		const elapsed = BigInt(Date.now() - startTime);
+		if (elapsed > syncTimeout) throw new SyncTimeoutError(elapsed, toBlock, 0n);
+	};
+	const latestBlock = await client.getBlockNumber();
+	const toBlock = params.toBlock ?? latestBlock;
+	if (minBlockNumber !== void 0 && latestBlock < minBlockNumber) throw new ProviderLagError(minBlockNumber, latestBlock);
+	const checkpoint = await loadCheckpoint(storage, chainId, poolAddress, account);
+	if (checkpoint) {
+		const reorgResult = await detectReorg({
+			client,
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		if (reorgResult.detected) onUpdate?.({
+			type: "reorg-detected",
+			blockNumber: reorgResult.reorgBlock ?? 0n
+		});
+	}
+	checkTimeout();
+	const snapshotResult = await getOpenPositionIds({
+		client,
+		chainId,
+		poolAddress,
+		account,
+		storage,
+		lastDispatchTxHash: snapshotTxHash,
+		fromBlock: checkpoint?.lastBlock ?? params.fromBlock
+	});
+	let positionIds;
+	if (snapshotResult === null && checkpoint && checkpoint.positionIds.length > 0) positionIds = checkpoint.positionIds;
+	else positionIds = snapshotResult ?? [];
+	if (positionIds.length === 0) {
+		const hasAnyEvents = await accountHasPositionEvents({
+			client,
+			poolAddress,
+			account,
+			fromBlock: params.fromBlock,
+			toBlock
+		});
+		if (!hasAnyEvents) {
+			const finalBlock$1 = await client.getBlock({ blockNumber: toBlock });
+			const poolMetaKey$1 = getPoolMetaKey(chainId, poolAddress);
+			const existingPoolMeta$1 = await storage.get(poolMetaKey$1);
+			if (!existingPoolMeta$1) await fetchAndStorePoolMeta(client, poolAddress, poolMetaKey$1, storage);
+			await saveCheckpoint({
+				storage,
+				chainId,
+				poolAddress,
+				account,
+				lastBlock: toBlock,
+				lastBlockHash: finalBlock$1.hash,
+				positionIds: []
+			});
+			const positionsKey$1 = getPositionsKey(chainId, poolAddress, account);
+			await storage.set(positionsKey$1, jsonSerializer.stringify([]));
+			return {
+				lastSyncedBlock: toBlock,
+				lastSyncedBlockHash: finalBlock$1.hash,
+				positionCount: 0n,
+				positionIds: [],
+				incremental: false,
+				durationMs: BigInt(Date.now() - startTime)
+			};
+		}
+	}
+	checkTimeout();
+	const finalBlock = await client.getBlock({ blockNumber: toBlock });
+	const poolMetaKey = getPoolMetaKey(chainId, poolAddress);
+	const existingPoolMeta = await storage.get(poolMetaKey);
+	if (!existingPoolMeta) await fetchAndStorePoolMeta(client, poolAddress, poolMetaKey, storage);
+	if (positionIds.length > 0) {
+		const { positions } = await getPositions({
+			client,
+			poolAddress,
+			owner: account,
+			tokenIds: positionIds,
+			blockNumber: toBlock
+		});
+		for (const pos of positions) {
+			const positionMetaKey = getPositionMetaKey(chainId, poolAddress, pos.tokenId);
+			const storedData = {
+				tokenId: pos.tokenId,
+				positionSize: pos.positionSize,
+				legs: pos.legs,
+				tickAtMint: pos.tickAtMint,
+				poolUtilization0AtMint: pos.poolUtilization0AtMint,
+				poolUtilization1AtMint: pos.poolUtilization1AtMint,
+				timestampAtMint: pos.timestampAtMint,
+				blockNumberAtMint: pos.blockNumberAtMint,
+				swapAtMint: pos.swapAtMint
+			};
+			await storage.set(positionMetaKey, jsonSerializer.stringify(storedData));
+		}
+	}
+	await saveCheckpoint({
+		storage,
+		chainId,
+		poolAddress,
+		account,
+		lastBlock: toBlock,
+		lastBlockHash: finalBlock.hash,
+		positionIds
+	});
+	const positionsKey = getPositionsKey(chainId, poolAddress, account);
+	await storage.set(positionsKey, jsonSerializer.stringify(positionIds));
+	return {
+		lastSyncedBlock: toBlock,
+		lastSyncedBlockHash: finalBlock.hash,
+		positionCount: BigInt(positionIds.length),
+		positionIds,
+		incremental: !!checkpoint,
+		durationMs: BigInt(Date.now() - startTime)
+	};
+}
+/**
+* Quick check if an account has ANY position events.
+* Checks OptionMinted, OptionBurnt, ForcedExercised (user), and AccountLiquidated (liquidatee).
+* All checked fields are indexed so this is fast.
+*
+* **Warning:** RPC index lag can cause false negatives for recently minted positions.
+* If the RPC node's event index is behind the chain tip, this function may return
+* `false` even though the account has just minted a position. Callers should either
+* wait a few blocks after minting before calling syncPositions, or skip this
+* optimization (by providing a `snapshotTxHash`) when freshness is critical.
+*
+* @param params - Check parameters
+* @returns true if account has any position events, false otherwise
+*/
+async function accountHasPositionEvents(params) {
+	const { client, poolAddress, account, fromBlock = 0n, toBlock } = params;
+	const [mintEvents, burnEvents, forceExerciseEvents, liquidationEvents] = await Promise.all([
+		withRetry(() => client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "OptionMinted",
+				inputs: [
+					{
+						type: "address",
+						name: "recipient",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "tokenId",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "balanceData",
+						indexed: false
+					}
+				]
+			},
+			args: { recipient: account },
+			fromBlock,
+			toBlock
+		})),
+		withRetry(() => client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "OptionBurnt",
+				inputs: [
+					{
+						type: "address",
+						name: "recipient",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "tokenId",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "positionSize",
+						indexed: false
+					},
+					{
+						type: "int256[4]",
+						name: "premiaByLeg",
+						indexed: false
+					}
+				]
+			},
+			args: { recipient: account },
+			fromBlock,
+			toBlock
+		})),
+		withRetry(() => client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "ForcedExercised",
+				inputs: [
+					{
+						type: "address",
+						name: "exercisor",
+						indexed: true
+					},
+					{
+						type: "address",
+						name: "user",
+						indexed: true
+					},
+					{
+						type: "uint256",
+						name: "tokenId",
+						indexed: true
+					},
+					{
+						type: "int256",
+						name: "exerciseFee",
+						indexed: false
+					}
+				]
+			},
+			args: { user: account },
+			fromBlock,
+			toBlock
+		})),
+		withRetry(() => client.getLogs({
+			address: poolAddress,
+			event: {
+				type: "event",
+				name: "AccountLiquidated",
+				inputs: [
+					{
+						type: "address",
+						name: "liquidator",
+						indexed: true
+					},
+					{
+						type: "address",
+						name: "liquidatee",
+						indexed: true
+					},
+					{
+						type: "int256",
+						name: "bonusAmounts",
+						indexed: false
+					}
+				]
+			},
+			args: { liquidatee: account },
+			fromBlock,
+			toBlock
+		}))
+	]);
+	return mintEvents.length > 0 || burnEvents.length > 0 || forceExerciseEvents.length > 0 || liquidationEvents.length > 0;
+}
+/**
+* Fetch full pool metadata and store it.
+* Uses getPoolMetadata to fetch all immutable pool data in minimal RPC calls.
+*/
+async function fetchAndStorePoolMeta(client, poolAddress, poolMetaKey, storage) {
+	const metadata = await getPoolMetadata({
+		client,
+		poolAddress
+	});
+	const poolMeta = {
+		tickSpacing: metadata.tickSpacing,
+		fee: metadata.fee,
+		poolId: metadata.poolId,
+		collateralToken0Address: metadata.collateralToken0Address,
+		collateralToken1Address: metadata.collateralToken1Address,
+		riskEngineAddress: metadata.riskEngineAddress,
+		token0Asset: metadata.token0Asset,
+		token1Asset: metadata.token1Asset,
+		token0Symbol: metadata.token0Symbol,
+		token1Symbol: metadata.token1Symbol,
+		token0Decimals: metadata.token0Decimals,
+		token1Decimals: metadata.token1Decimals
+	};
+	await storage.set(poolMetaKey, jsonSerializer.stringify(poolMeta));
+}
+/**
+* Retry helper with exponential backoff for transient RPC errors.
+*
+* @param fn - Async function to retry
+* @param maxRetries - Maximum number of retries (default: 3)
+* @returns The result of the function
+*/
+async function withRetry(fn, maxRetries = 3) {
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxRetries && isRetryableRpcError(error)) {
+			await new Promise((resolve) => setTimeout(resolve, 1e3 * 2 ** attempt));
+			continue;
+		}
+		throw error;
+	}
+	throw lastError;
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/forceExercise.ts
+/**
+* Force exercise an ITM (in-the-money) long position.
+*
+* The exercisor calls dispatchFrom to exercise another user's ITM long positions,
+* paying the exercise fee.
+*
+* @param params - Force exercise parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await forceExercise({
+*   client,
+*   walletClient,
+*   account: exercisorAddress,
+*   poolAddress,
+*   user: targetAccount,
+*   positionIdListFrom: exercisorPositions,
+*   positionIdListTo: targetPositions,
+*   positionIdListToFinal: [], // Exercise all ITM positions
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function forceExercise(params) {
+	const { client, walletClient, account, poolAddress, user, positionIdListFrom, positionIdListTo, positionIdListToFinal, usePremiaAsCollateral = 0n, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatchFrom",
+		args: [
+			positionIdListFrom,
+			user,
+			positionIdListTo,
+			positionIdListToFinal,
+			usePremiaAsCollateral
+		],
+		txOverrides
+	});
+}
+/**
+* Force exercise and wait for confirmation.
+*
+* When `storage` and `chainId` are provided, automatically syncs the
+* exercisor's positions after the transaction confirms.
+*/
+async function forceExerciseAndWait(params) {
+	const result = await forceExercise(params);
+	const receipt = await result.wait();
+	const { storage, chainId, client, poolAddress, account } = params;
+	if (storage && chainId !== void 0) await syncPositions({
+		client,
+		chainId,
+		poolAddress,
+		account,
+		storage
+	});
+	return receipt;
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/settle.ts
+/**
+* Settle accumulated premia on existing positions.
+*
+* This function triggers premium collection without changing position size.
+* It calls dispatch with unchanged position lists.
+*
+* @param params - Settlement parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await settleAccumulatedPremia({
+*   client,
+*   walletClient,
+*   account,
+*   poolAddress,
+*   positionIdList: existingPositions,
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function settleAccumulatedPremia(params) {
+	const { client, walletClient, account, poolAddress, positionIdList, usePremiaAsCollateral = false, builderCode = 0n, txOverrides } = params;
+	const positionSizes = positionIdList.map(() => 0n);
+	const tickAndSpreadLimits = positionIdList.map(() => [
+		-887272n,
+		887272n,
+		0n
+	]);
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "dispatch",
+		args: [
+			positionIdList,
+			positionIdList,
+			positionSizes.map((s) => BigInt(s)),
+			tickAndSpreadLimits.map((t) => [
+				Number(t[0]),
+				Number(t[1]),
+				Number(t[2])
+			]),
+			usePremiaAsCollateral,
+			builderCode
+		],
+		txOverrides
+	});
+}
+/**
+* Settle premia and wait for confirmation.
+*/
+async function settleAccumulatedPremiaAndWait(params) {
+	const result = await settleAccumulatedPremia(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/pokeOracle.ts
+/**
+* Poke the oracle to update its state.
+*
+* This function can be called to advance the oracle epoch.
+* Note: The oracle can only be poked once per epoch (64 seconds).
+*
+* @param params - Poke oracle parameters
+* @returns TxResult
+* @throws OracleRateLimitedError if checkRateLimit is true and oracle was recently poked
+*
+* @example
+* ```typescript
+* const result = await pokeOracle({
+*   client,
+*   walletClient,
+*   account,
+*   poolAddress,
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function pokeOracle(params) {
+	const { client, walletClient, account, poolAddress, checkRateLimit = false, txOverrides } = params;
+	if (checkRateLimit) {
+		const [oracleData, block] = await Promise.all([client.readContract({
+			address: poolAddress,
+			abi: panopticPoolV2Abi,
+			functionName: "getOracleTicks"
+		}), client.getBlock()]);
+		const oraclePack = oracleData[4];
+		const epoch = oraclePack >> 232n;
+		const currentEpoch = block.timestamp / 64n;
+		if (currentEpoch <= epoch) {
+			const lastUpdate = epoch * 64n;
+			throw new OracleRateLimitedError(lastUpdate, block.timestamp);
+		}
+	}
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "pokeOracle",
+		args: [],
+		txOverrides
+	});
+}
+/**
+* Poke oracle and wait for confirmation.
+*/
+async function pokeOracleAndWait(params) {
+	const result = await pokeOracle(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/factory.ts
+/**
+* Deploy a new Panoptic pool via the factory.
+*
+* @param params - Deployment parameters (versioned: 'v3' or 'v4')
+* @returns Transaction result with hash and wait function
+*/
+async function deployNewPool(params) {
+	const { client, walletClient, account, factoryAddress, riskEngine, salt, txOverrides } = params;
+	if (params.version === "v3") return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: factoryAddress,
+		abi: panopticFactoryV3Abi,
+		functionName: "deployNewPool",
+		args: [
+			params.token0,
+			params.token1,
+			params.fee,
+			riskEngine,
+			salt
+		],
+		txOverrides
+	});
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: factoryAddress,
+		abi: panopticFactoryV4Abi,
+		functionName: "deployNewPool",
+		args: [
+			{
+				currency0: params.poolKey.currency0,
+				currency1: params.poolKey.currency1,
+				fee: Number(params.poolKey.fee),
+				tickSpacing: Number(params.poolKey.tickSpacing),
+				hooks: params.poolKey.hooks
+			},
+			riskEngine,
+			salt
+		],
+		txOverrides
+	});
+}
+/**
+* Deploy a new Panoptic pool and wait for confirmation.
+*/
+async function deployNewPoolAndWait(params) {
+	const result = await deployNewPool(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/txManagement.ts
+/** Default gas price multiplier for replacement (12.5% bump = minimum for replacement) */
+const DEFAULT_GAS_PRICE_MULTIPLIER = 1.125;
+/**
+* Apply a multiplier to a bigint gas value.
+* Uses integer arithmetic to avoid floating point issues.
+*/
+function applyMultiplier(value, multiplier) {
+	const bps = BigInt(Math.ceil(multiplier * 1e4));
+	return value * bps / 10000n;
+}
+/**
+* Compute bumped gas parameters from the original transaction.
+*/
+function computeBumpedGas(originalMaxFeePerGas, originalMaxPriorityFeePerGas, explicitMaxFeePerGas, explicitMaxPriorityFeePerGas, multiplier) {
+	const maxFeePerGas = explicitMaxFeePerGas ?? applyMultiplier(originalMaxFeePerGas ?? 0n, multiplier);
+	const maxPriorityFeePerGas = explicitMaxPriorityFeePerGas ?? applyMultiplier(originalMaxPriorityFeePerGas ?? 0n, multiplier);
+	return {
+		maxFeePerGas,
+		maxPriorityFeePerGas
+	};
+}
+/**
+* Speed up a pending transaction by resubmitting with higher gas.
+*
+* Fetches the original transaction, extracts its parameters,
+* bumps the gas price, and resubmits with the same nonce.
+*
+* @param params - Speed up parameters
+* @returns TxResult for the replacement transaction
+* @throws Error if the original transaction is not found
+*
+* @example
+* ```typescript
+* // Speed up with default 12.5% bump
+* const result = await speedUpTransaction({
+*   client,
+*   walletClient,
+*   hash: pendingTxHash,
+* })
+*
+* // Speed up with explicit gas prices
+* const result = await speedUpTransaction({
+*   client,
+*   walletClient,
+*   hash: pendingTxHash,
+*   maxFeePerGas: 50_000_000_000n, // 50 gwei
+*   maxPriorityFeePerGas: 3_000_000_000n, // 3 gwei
+* })
+* ```
+*/
+async function speedUpTransaction(params) {
+	const { client, walletClient, hash, maxFeePerGas: explicitMaxFee, maxPriorityFeePerGas: explicitMaxPriority, gasPriceMultiplier = DEFAULT_GAS_PRICE_MULTIPLIER, broadcaster } = params;
+	const tx = await client.getTransaction({ hash });
+	const { maxFeePerGas, maxPriorityFeePerGas } = computeBumpedGas(tx.maxFeePerGas ?? void 0, tx.maxPriorityFeePerGas ?? void 0, explicitMaxFee, explicitMaxPriority, gasPriceMultiplier);
+	if (broadcaster) {
+		const request = await walletClient.prepareTransactionRequest({
+			account: tx.from,
+			to: tx.to ?? void 0,
+			data: tx.input,
+			value: tx.value,
+			nonce: tx.nonce,
+			gas: tx.gas,
+			maxFeePerGas,
+			maxPriorityFeePerGas,
+			chain: walletClient.chain
+		});
+		const signedTx = await walletClient.signTransaction({
+			...request,
+			account: tx.from
+		});
+		const replacementHash$1 = await broadcaster.broadcast(signedTx);
+		return createTxResult(client, replacementHash$1);
+	}
+	const replacementHash = await walletClient.sendTransaction({
+		account: tx.from,
+		to: tx.to ?? void 0,
+		data: tx.input,
+		value: tx.value,
+		nonce: tx.nonce,
+		gas: tx.gas,
+		maxFeePerGas,
+		maxPriorityFeePerGas,
+		chain: walletClient.chain
+	});
+	return createTxResult(client, replacementHash);
+}
+/**
+* Cancel a pending transaction by sending a 0-value self-transfer
+* with the same nonce and higher gas price.
+*
+* @param params - Cancel parameters
+* @returns TxResult for the cancellation transaction
+* @throws Error if the original transaction is not found
+*
+* @example
+* ```typescript
+* const result = await cancelTransaction({
+*   client,
+*   walletClient,
+*   account,
+*   hash: pendingTxHash,
+* })
+* await result.wait()
+* ```
+*/
+async function cancelTransaction(params) {
+	const { client, walletClient, account, hash, maxFeePerGas: explicitMaxFee, maxPriorityFeePerGas: explicitMaxPriority, gasPriceMultiplier = DEFAULT_GAS_PRICE_MULTIPLIER, broadcaster } = params;
+	const tx = await client.getTransaction({ hash });
+	const { maxFeePerGas, maxPriorityFeePerGas } = computeBumpedGas(tx.maxFeePerGas ?? void 0, tx.maxPriorityFeePerGas ?? void 0, explicitMaxFee, explicitMaxPriority, gasPriceMultiplier);
+	if (broadcaster) {
+		const request = await walletClient.prepareTransactionRequest({
+			account,
+			to: account,
+			value: 0n,
+			nonce: tx.nonce,
+			gas: 21000n,
+			maxFeePerGas,
+			maxPriorityFeePerGas,
+			chain: walletClient.chain
+		});
+		const signedTx = await walletClient.signTransaction({
+			...request,
+			account
+		});
+		const cancelHash$1 = await broadcaster.broadcast(signedTx);
+		return createTxResult(client, cancelHash$1);
+	}
+	const cancelHash = await walletClient.sendTransaction({
+		account,
+		to: account,
+		value: 0n,
+		nonce: tx.nonce,
+		gas: 21000n,
+		maxFeePerGas,
+		maxPriorityFeePerGas,
+		chain: walletClient.chain
+	});
+	return createTxResult(client, cancelHash);
+}
+
+//#endregion
+//#region src/panoptic/v2/tokenId/encoding.ts
+/**
+* Convert a signed strike tick to unsigned representation for encoding.
+*
+* @param strike - The signed strike tick
+* @returns The unsigned representation
+*/
+function convertStrikeToUnsigned(strike) {
+	if (strike < 0n) return STRIKE_CONVERSION_FACTOR + strike;
+	return strike;
+}
+/**
+* Convert an unsigned encoded strike back to signed representation.
+*
+* @param encodedStrike - The unsigned encoded strike
+* @returns The signed strike tick
+*/
+function convertStrikeToSigned(encodedStrike) {
+	if (encodedStrike > 2n ** 23n - 1n) return encodedStrike - STRIKE_CONVERSION_FACTOR;
+	return encodedStrike;
+}
+/**
+* Get the bit offset for a leg at the given index.
+*
+* @param legIndex - The leg index (0-3)
+* @returns The bit offset from the start of the legs section
+*/
+function getLegOffset(legIndex) {
+	return legIndex * TOKEN_ID_BITS.LEG_SIZE;
+}
+/**
+* Encode a pool ID from a Uniswap V3 pool address.
+*
+* The encoded PoolId structure: [16-bit tickSpacing][8-bit vegoid][40-bit pool address]
+*
+* @param address - The Uniswap V3 pool address
+* @param tickSpacing - The tick spacing of the pool
+* @param vegoid - The vegoid value (defaults to 4)
+* @returns The encoded pool ID
+*/
+function encodePoolId(address, tickSpacing, vegoid = DEFAULT_VEGOID) {
+	const addressHex = address.slice(2, 12).toLowerCase();
+	const bytes = [];
+	for (let i = 0; i < 10; i += 2) bytes.push(parseInt(addressHex.slice(i, i + 2), 16));
+	bytes.reverse();
+	let poolId = 0n;
+	for (let i = 0; i < bytes.length; i++) poolId |= BigInt(bytes[i]) << BigInt(i * 8);
+	poolId |= (vegoid & 0xffn) << TOKEN_ID_BITS.VEGOID_STARTING_BIT;
+	poolId |= (tickSpacing & 0xffffn) << TOKEN_ID_BITS.TICK_SPACING_STARTING_BIT;
+	return poolId;
+}
+/**
+* Encode a pool ID from a Uniswap V4 pool ID (bytes32).
+*
+* @param poolIdHex - The V4 pool ID (bytes32 hex string)
+* @param tickSpacing - The tick spacing of the pool
+* @param vegoid - The vegoid value (defaults to 4)
+* @returns The encoded pool ID
+*/
+function encodeV4PoolId(poolIdHex, tickSpacing, vegoid = DEFAULT_VEGOID) {
+	const hex = poolIdHex.slice(2);
+	const last5BytesHex = hex.slice(-10).toLowerCase();
+	const bytes = [];
+	for (let i = 0; i < 10; i += 2) bytes.push(parseInt(last5BytesHex.slice(i, i + 2), 16));
+	bytes.reverse();
+	let encodedPoolId = 0n;
+	for (let i = 0; i < bytes.length; i++) encodedPoolId |= BigInt(bytes[i]) << BigInt(i * 8);
+	encodedPoolId |= (vegoid & 0xffn) << TOKEN_ID_BITS.VEGOID_STARTING_BIT;
+	encodedPoolId |= (tickSpacing & 0xffffn) << TOKEN_ID_BITS.TICK_SPACING_STARTING_BIT;
+	return encodedPoolId;
+}
+/**
+* Decode the vegoid from a TokenId.
+*
+* @param tokenId - The TokenId to decode
+* @returns The vegoid value
+*/
+function decodeVegoid(tokenId) {
+	const poolId = tokenId & (1n << TOKEN_ID_BITS.POOL_ID_SIZE) - 1n;
+	return poolId >> TOKEN_ID_BITS.VEGOID_STARTING_BIT & (1n << TOKEN_ID_BITS.VEGOID_SIZE) - 1n;
+}
+/**
+* Decode the tick spacing from a TokenId.
+*
+* @param tokenId - The TokenId to decode
+* @returns The tick spacing
+*/
+function decodeTickSpacing(tokenId) {
+	const poolId = tokenId & (1n << TOKEN_ID_BITS.POOL_ID_SIZE) - 1n;
+	return poolId >> TOKEN_ID_BITS.TICK_SPACING_STARTING_BIT;
+}
+/**
+* Decode the pool ID portion from a TokenId.
+*
+* @param tokenId - The TokenId to decode
+* @returns The pool ID as a hex string
+*/
+function decodePoolId(tokenId) {
+	const poolId = tokenId & (1n << TOKEN_ID_BITS.POOL_ID_SIZE) - 1n;
+	let hex = poolId.toString(16);
+	while (hex.length < 16) hex = "0" + hex;
+	return `0x${hex}`;
+}
+/**
+* Encode a single leg field.
+*
+* @param value - The value to encode
+* @param bitPosition - The bit position within the leg
+* @param legIndex - The leg index
+* @returns The encoded value shifted to the correct position
+*/
+function encodeLegField(value, bitPosition, legIndex) {
+	return value << getLegOffset(legIndex) + bitPosition + TOKEN_ID_BITS.POOL_ID_SIZE;
+}
+/**
+* Encode a single leg into a TokenId.
+*
+* @param leg - The leg parameters
+* @returns The encoded leg value (to be ORed with existing TokenId)
+*/
+function encodeLeg(leg) {
+	const { index, asset, optionRatio, isLong, tokenType, riskPartner, strike, width } = leg;
+	return encodeLegField(asset & LEG_MASKS.ASSET, LEG_BITS.ASSET_BIT, index) | encodeLegField(optionRatio & LEG_MASKS.RATIO, LEG_BITS.RATIO_BIT, index) | encodeLegField(isLong & LEG_MASKS.IS_LONG, LEG_BITS.IS_LONG_BIT, index) | encodeLegField(tokenType & LEG_MASKS.TOKEN_TYPE, LEG_BITS.TOKEN_TYPE_BIT, index) | encodeLegField(riskPartner & LEG_MASKS.RISK_PARTNER, LEG_BITS.RISK_PARTNER_BIT, index) | encodeLegField(convertStrikeToUnsigned(strike) & LEG_MASKS.STRIKE, LEG_BITS.STRIKE_BIT, index) | encodeLegField(width & LEG_MASKS.WIDTH, LEG_BITS.WIDTH_BIT, index);
+}
+/**
+* Add a leg to an existing TokenId.
+*
+* @param tokenId - The existing TokenId (can be just poolId or partial TokenId)
+* @param leg - The leg parameters to add
+* @returns The TokenId with the leg added
+*/
+function addLegToTokenId(tokenId, leg) {
+	return tokenId | encodeLeg(leg);
+}
+/**
+* Decode a single leg from a TokenId.
+*
+* @param tokenId - The TokenId to decode
+* @param legIndex - The leg index (0-3)
+* @returns The decoded leg data
+*/
+function decodeLeg(tokenId, legIndex) {
+	const offset = getLegOffset(legIndex) + TOKEN_ID_BITS.POOL_ID_SIZE;
+	const leg = tokenId >> offset & LEG_MASKS.LEG;
+	const asset = leg & LEG_MASKS.ASSET;
+	const optionRatio = leg >> LEG_BITS.RATIO_BIT & LEG_MASKS.RATIO;
+	const isLong = (leg >> LEG_BITS.IS_LONG_BIT & LEG_MASKS.IS_LONG) === 1n;
+	const tokenType = leg >> LEG_BITS.TOKEN_TYPE_BIT & LEG_MASKS.TOKEN_TYPE;
+	const riskPartner = leg >> LEG_BITS.RISK_PARTNER_BIT & LEG_MASKS.RISK_PARTNER;
+	const encodedStrike = leg >> LEG_BITS.STRIKE_BIT & LEG_MASKS.STRIKE;
+	const strike = convertStrikeToSigned(encodedStrike);
+	const width = leg >> LEG_BITS.WIDTH_BIT & LEG_MASKS.WIDTH;
+	return {
+		index: legIndex,
+		asset,
+		optionRatio,
+		isLong,
+		tokenType,
+		riskPartner,
+		strike,
+		width
+	};
+}
+/**
+* Count the number of active legs in a TokenId.
+* A leg is active if its optionRatio > 0.
+*
+* @param tokenId - The TokenId to check
+* @returns The number of active legs
+*/
+function countLegs(tokenId) {
+	let count = 0n;
+	for (let i = 0n; i < TOKEN_ID_BITS.MAX_LEGS; i++) {
+		const leg = decodeLeg(tokenId, i);
+		if (leg.optionRatio > 0n) count++;
+	}
+	return count;
+}
+/**
+* Decode all active legs from a TokenId.
+*
+* @param tokenId - The TokenId to decode
+* @returns Array of decoded legs (only active legs with optionRatio > 0)
+*/
+function decodeAllLegs(tokenId) {
+	const legs = [];
+	for (let i = 0n; i < TOKEN_ID_BITS.MAX_LEGS; i++) {
+		const leg = decodeLeg(tokenId, i);
+		if (leg.optionRatio > 0n) legs.push(leg);
+	}
+	return legs;
+}
+
+//#endregion
+//#region src/panoptic/v2/tokenId/builder.ts
+/**
+* Create a TokenId builder from an encoded pool ID.
+*
+* Use the 64-bit poolId from `getPool().poolId` or `fetchPoolId()`.
+* For offline encoding, use `encodePoolId()` or `encodeV4PoolId()` first.
+*
+* @param poolId - The encoded 64-bit pool ID
+* @returns A TokenId builder instance
+*
+* @example
+* ```typescript
+* const pool = await getPool({ client, poolAddress, chainId })
+* const tokenId = createTokenIdBuilder(pool.poolId)
+*   .addCall({ strike: 100n, width: 10n, optionRatio: 1n, isLong: false })
+*   .addPut({ strike: -100n, width: 10n, optionRatio: 1n, isLong: false })
+*   .build()
+* ```
+*/
+function createTokenIdBuilder(poolId) {
+	let tokenId = poolId;
+	let currentLegIndex = 0n;
+	const validateLegConfig = (config, legIndex) => {
+		if (legIndex >= TOKEN_ID_BITS.MAX_LEGS) throw new InvalidTokenIdParameterError(0n);
+		if (config.optionRatio < 1n || config.optionRatio > LEG_LIMITS.MAX_RATIO) throw new InvalidTokenIdParameterError(1n);
+		if (config.width < 0n || config.width > LEG_LIMITS.MAX_WIDTH) throw new InvalidTokenIdParameterError(2n);
+		if (config.strike < LEG_LIMITS.MIN_STRIKE || config.strike > LEG_LIMITS.MAX_STRIKE) throw new InvalidTokenIdParameterError(3n);
+		if (config.asset !== 0n && config.asset !== 1n) throw new InvalidTokenIdParameterError(4n);
+		if (config.tokenType !== 0n && config.tokenType !== 1n) throw new InvalidTokenIdParameterError(5n);
+		const riskPartner = config.riskPartner ?? legIndex;
+		if (riskPartner < 0n || riskPartner > 3n) throw new InvalidTokenIdParameterError(6n);
+	};
+	const builder = {
+		addLeg(config) {
+			validateLegConfig(config, currentLegIndex);
+			const leg = {
+				index: currentLegIndex,
+				asset: config.asset,
+				optionRatio: config.optionRatio,
+				isLong: config.isLong ? 1n : 0n,
+				tokenType: config.tokenType,
+				riskPartner: config.riskPartner ?? currentLegIndex,
+				strike: config.strike,
+				width: config.width
+			};
+			tokenId = addLegToTokenId(tokenId, leg);
+			currentLegIndex++;
+			return builder;
+		},
+		addCall(config) {
+			const asset = config.asset ?? 0n;
+			return builder.addLeg({
+				...config,
+				tokenType: asset,
+				asset
+			});
+		},
+		addPut(config) {
+			const asset = config.asset ?? 0n;
+			return builder.addLeg({
+				...config,
+				tokenType: asset === 0n ? 1n : 0n,
+				asset
+			});
+		},
+		addLoan(config) {
+			return builder.addLeg({
+				asset: config.asset,
+				optionRatio: config.optionRatio ?? 1n,
+				isLong: false,
+				tokenType: config.tokenType,
+				riskPartner: config.riskPartner,
+				strike: config.strike,
+				width: 0n
+			});
+		},
+		addCredit(config) {
+			return builder.addLeg({
+				asset: config.asset,
+				optionRatio: config.optionRatio ?? 1n,
+				isLong: true,
+				tokenType: config.tokenType,
+				riskPartner: config.riskPartner,
+				strike: config.strike,
+				width: 0n
+			});
+		},
+		build() {
+			if (currentLegIndex === 0n) throw new InvalidTokenIdParameterError(7n);
+			return tokenId;
+		},
+		legCount() {
+			return currentLegIndex;
+		},
+		reset() {
+			tokenId = poolId;
+			currentLegIndex = 0n;
+			return builder;
+		}
+	};
+	return builder;
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/loanUtils.ts
+/** Maximum retry attempts on InputListFail */
+const MAX_RETRIES = 3;
+/**
+* Resolve token index (0 or 1) for the given token address against the pool.
+* Throws SwapTokenMismatchError if the token isn't in the pool.
+*/
+function resolveTokenIndex(tokenAddress, token0, token1) {
+	const lower = tokenAddress.toLowerCase();
+	if (lower === token0.toLowerCase()) return 0n;
+	if (lower === token1.toLowerCase()) return 1n;
+	throw new SwapTokenMismatchError(tokenAddress, token0, token1);
+}
+/**
+* Resolve existing position IDs from explicit param or storage.
+*/
+async function resolvePositionIds(explicit, storage, chainId, poolAddress, account) {
+	if (explicit !== void 0) return explicit;
+	if (storage) return getTrackedPositionIds({
+		chainId,
+		poolAddress,
+		account,
+		storage
+	});
+	throw new MissingPositionIdsError();
+}
+/**
+* Check if a caught error is an InputListFail contract revert.
+* Works with both raw viem errors and parsed PanopticError instances.
+*/
+function isInputListFailError(error) {
+	if (error instanceof InputListFailError) return true;
+	const parsed = parsePanopticError(error);
+	return parsed?.errorName === "InputListFail";
+}
+/**
+* Build a unique loan tokenId that doesn't collide with existing positions.
+* Bumps optionRatio (1-127) and returns adjusted size to maintain equivalent exposure.
+*
+* @param asset - Which token denominates the positionSize (0 or 1).
+*/
+function buildUniqueLoan(poolId, asset, tokenType, currentTick, tickSpacing, existingPositionIds, positionSize) {
+	const mod = currentTick % tickSpacing;
+	let strike = currentTick - (mod + tickSpacing) % tickSpacing;
+	for (let ratio = 1n; ratio <= 127n; ratio++) {
+		const tokenId = createTokenIdBuilder(poolId).addLoan({
+			asset,
+			tokenType,
+			strike,
+			optionRatio: ratio
+		}).build();
+		if (!existingPositionIds.includes(tokenId)) {
+			const adjustedSize = positionSize / ratio;
+			if (adjustedSize === 0n || positionSize % ratio !== 0n) continue;
+			return {
+				tokenId,
+				adjustedSize
+			};
+		}
+	}
+	const mod2 = currentTick % tickSpacing;
+	strike = currentTick - (mod2 + tickSpacing) % tickSpacing + tickSpacing;
+	for (let i = 0; i < 100; i++) {
+		const tokenId = createTokenIdBuilder(poolId).addLoan({
+			asset,
+			tokenType,
+			strike
+		}).build();
+		if (!existingPositionIds.includes(tokenId)) return {
+			tokenId,
+			adjustedSize: positionSize
+		};
+		strike += tickSpacing;
+	}
+	throw new LoanSlotExhaustedError();
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/swap.ts
+/**
+* Swap tokens using Panoptic's exact-output mechanism.
+*
+* Opens a loan with `swapAtMint=true` and immediately burns it with `swapAtMint=false`.
+* The user receives exactly `amountOut` of `tokenOut`.
+*
+* @param params - Swap parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await swapExactOut({
+*   client, walletClient, account, poolAddress,
+*   chainId: 11155111n,
+*   tokenOut: WETH_ADDRESS,
+*   amountOut: 5n * 10n**16n,  // 0.05 WETH
+*   slippageBps: 500n,         // 5% slippage
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function swapExactOut(params) {
+	const { client, walletClient, account, poolAddress, chainId, tokenOut, amountOut, slippageBps, existingPositionIds: explicitIds, storage, txOverrides } = params;
+	for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+		const [pool, positionIds] = await Promise.all([getPool({
+			client,
+			poolAddress,
+			chainId
+		}), resolvePositionIds(explicitIds, storage, chainId, poolAddress, account)]);
+		const token0 = pool.collateralTracker0.token;
+		const token1 = pool.collateralTracker1.token;
+		const tokenOutIndex = resolveTokenIndex(tokenOut, token0, token1);
+		const tokenType = tokenOutIndex === 0n ? 1n : 0n;
+		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
+		const { tokenId: loanTokenId, adjustedSize } = buildUniqueLoan(pool.poolId, tokenOutIndex, tokenType, pool.currentTick, pool.tickSpacing, positionIds, amountOut);
+		const mintTickLimits = [
+			Number(tickLimitHigh),
+			Number(tickLimitLow),
+			0
+		];
+		const burnTickLimits = [
+			Number(tickLimitLow),
+			Number(tickLimitHigh),
+			0
+		];
+		const positionIdList = [loanTokenId, loanTokenId];
+		const finalPositionIdList = [...positionIds];
+		const positionSizes = [adjustedSize, 0n];
+		try {
+			return await submitWrite({
+				client,
+				walletClient,
+				account,
+				address: poolAddress,
+				abi: panopticPoolV2Abi,
+				functionName: "dispatch",
+				args: [
+					positionIdList,
+					finalPositionIdList,
+					positionSizes,
+					[mintTickLimits, burnTickLimits],
+					false,
+					0n
+				],
+				txOverrides
+			});
+		} catch (error) {
+			if (isInputListFailError(error) && attempt < MAX_RETRIES - 1) continue;
+			throw error;
+		}
+	}
+	throw new MaxRetriesExceededError("swapExactOut");
+}
+/**
+* Swap exact output and wait for confirmation.
+*/
+async function swapExactOutAndWait(params) {
+	const result = await swapExactOut(params);
+	return result.wait();
+}
+/**
+* Swap tokens using Panoptic's exact-input mechanism.
+*
+* Opens a loan with `swapAtMint=false` (borrows tokenIn to wallet),
+* then burns with `swapAtMint=true` (swaps tokenIn back to repay).
+* The user spends exactly `amountIn` of `tokenIn`.
+*
+* @param params - Swap parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await swapExactIn({
+*   client, walletClient, account, poolAddress,
+*   chainId: 11155111n,
+*   tokenIn: USDC_ADDRESS,
+*   amountIn: 1000n * 10n**6n,  // 1000 USDC
+*   slippageBps: 500n,
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function swapExactIn(params) {
+	const { client, walletClient, account, poolAddress, chainId, tokenIn, amountIn, slippageBps, existingPositionIds: explicitIds, storage, txOverrides } = params;
+	for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+		const [pool, positionIds] = await Promise.all([getPool({
+			client,
+			poolAddress,
+			chainId
+		}), resolvePositionIds(explicitIds, storage, chainId, poolAddress, account)]);
+		const token0 = pool.collateralTracker0.token;
+		const token1 = pool.collateralTracker1.token;
+		const tokenInIndex = resolveTokenIndex(tokenIn, token0, token1);
+		const tokenType = tokenInIndex;
+		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
+		const { tokenId: loanTokenId, adjustedSize } = buildUniqueLoan(pool.poolId, tokenInIndex, tokenType, pool.currentTick, pool.tickSpacing, positionIds, amountIn);
+		const mintTickLimits = [
+			Number(tickLimitLow),
+			Number(tickLimitHigh),
+			0
+		];
+		const burnTickLimits = [
+			Number(tickLimitHigh),
+			Number(tickLimitLow),
+			0
+		];
+		const positionIdList = [loanTokenId, loanTokenId];
+		const finalPositionIdList = [...positionIds];
+		const positionSizes = [adjustedSize, 0n];
+		try {
+			return await submitWrite({
+				client,
+				walletClient,
+				account,
+				address: poolAddress,
+				abi: panopticPoolV2Abi,
+				functionName: "dispatch",
+				args: [
+					positionIdList,
+					finalPositionIdList,
+					positionSizes,
+					[mintTickLimits, burnTickLimits],
+					false,
+					0n
+				],
+				txOverrides
+			});
+		} catch (error) {
+			if (isInputListFailError(error) && attempt < MAX_RETRIES - 1) continue;
+			throw error;
+		}
+	}
+	throw new MaxRetriesExceededError("swapExactIn");
+}
+/**
+* Swap exact input and wait for confirmation.
+*/
+async function swapExactInAndWait(params) {
+	const result = await swapExactIn(params);
+	return result.wait();
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/wrap.ts
+/** Minimal ERC4626 surface used by the xStock wrappers. */
+const xstockWrapperAbi = [
+	{
+		type: "function",
+		name: "deposit",
+		stateMutability: "nonpayable",
+		inputs: [{
+			name: "assets",
+			type: "uint256"
+		}, {
+			name: "receiver",
+			type: "address"
+		}],
+		outputs: [{
+			name: "shares",
+			type: "uint256"
+		}]
+	},
+	{
+		type: "function",
+		name: "redeem",
+		stateMutability: "nonpayable",
+		inputs: [
+			{
+				name: "shares",
+				type: "uint256"
+			},
+			{
+				name: "receiver",
+				type: "address"
+			},
+			{
+				name: "owner",
+				type: "address"
+			}
+		],
+		outputs: [{
+			name: "assets",
+			type: "uint256"
+		}]
+	},
+	{
+		type: "function",
+		name: "asset",
+		stateMutability: "view",
+		inputs: [],
+		outputs: [{ type: "address" }]
+	},
+	{
+		type: "function",
+		name: "previewDeposit",
+		stateMutability: "view",
+		inputs: [{
+			name: "assets",
+			type: "uint256"
+		}],
+		outputs: [{
+			name: "shares",
+			type: "uint256"
+		}]
+	},
+	{
+		type: "function",
+		name: "previewRedeem",
+		stateMutability: "view",
+		inputs: [{
+			name: "shares",
+			type: "uint256"
+		}],
+		outputs: [{
+			name: "assets",
+			type: "uint256"
+		}]
+	},
+	{
+		type: "function",
+		name: "maxRedeem",
+		stateMutability: "view",
+		inputs: [{
+			name: "owner",
+			type: "address"
+		}],
+		outputs: [{
+			name: "maxShares",
+			type: "uint256"
+		}]
+	}
+];
+/**
+* Wrap an underlying xStock into its ERC4626 wrapper (`deposit`). Requires a
+* prior ERC20 approval of the underlying to the wrapper address.
+*
+* @returns TxResult with hash and wait function
+*/
+async function wrapXstock(params) {
+	const { client, walletClient, account, wrapper, assets, receiver = account, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: wrapper,
+		abi: xstockWrapperAbi,
+		functionName: "deposit",
+		args: [assets, receiver],
+		txOverrides
+	});
+}
+/** Wrap and wait for confirmation. */
+async function wrapXstockAndWait(params) {
+	const result = await wrapXstock(params);
+	return result.wait();
+}
+/**
+* Unwrap wrapper shares back into the underlying xStock (`redeem`). When
+* `owner` defaults to (or equals) `account` the caller burns their own shares
+* and no approval is needed. Passing a different `owner` redeems on its behalf
+* and requires that owner to have granted the caller an ERC-4626 share
+* allowance (`approve`), or the `redeem` call reverts.
+*
+* @returns TxResult with hash and wait function
+*/
+async function unwrapXstock(params) {
+	const { client, walletClient, account, wrapper, shares, receiver = account, owner = account, txOverrides } = params;
+	return submitWrite({
+		client,
+		walletClient,
+		account,
+		address: wrapper,
+		abi: xstockWrapperAbi,
+		functionName: "redeem",
+		args: [
+			shares,
+			receiver,
+			owner
+		],
+		txOverrides
+	});
+}
+/** Unwrap and wait for confirmation. */
+async function unwrapXstockAndWait(params) {
+	const result = await unwrapXstock(params);
+	return result.wait();
+}
+/**
+* Preview the wrapper shares minted for a given amount of underlying xStock.
+*/
+async function previewWrap(params) {
+	const { client, wrapper, amount } = params;
+	return client.readContract({
+		address: wrapper,
+		abi: xstockWrapperAbi,
+		functionName: "previewDeposit",
+		args: [amount]
+	});
+}
+/**
+* Preview the underlying xStock returned for a given amount of wrapper shares.
+*/
+async function previewUnwrap(params) {
+	const { client, wrapper, amount } = params;
+	return client.readContract({
+		address: wrapper,
+		abi: xstockWrapperAbi,
+		functionName: "previewRedeem",
+		args: [amount]
+	});
+}
+
+//#endregion
+//#region src/panoptic/v2/tokenId/decode.ts
+/**
+* Convert a DecodedLeg to TokenIdLeg format.
+*
+* @param leg - The decoded leg from encoding utils
+* @param tickSpacing - The tick spacing for calculating tick bounds
+* @returns The TokenIdLeg format
+*/
+function convertToTokenIdLeg(leg, tickSpacing) {
+	const halfWidth = leg.width * tickSpacing / 2n;
+	const tickLower = leg.strike - halfWidth;
+	const tickUpper = leg.strike + halfWidth;
+	return {
+		index: leg.index,
+		asset: leg.asset,
+		optionRatio: leg.optionRatio,
+		isLong: leg.isLong,
+		tokenType: leg.tokenType,
+		riskPartner: leg.riskPartner,
+		strike: leg.strike,
+		width: leg.width,
+		tickLower,
+		tickUpper
+	};
+}
+/**
+* Decode a TokenId into its component parts.
+*
+* @param tokenId - The TokenId to decode
+* @returns The decoded TokenId data
+*
+* @example
+* ```typescript
+* const decoded = decodeTokenId(tokenId)
+* console.log(decoded.legs) // Array of legs
+* console.log(decoded.tickSpacing) // Tick spacing
+* ```
+*/
+function decodeTokenId(tokenId) {
+	const poolId = decodePoolId(tokenId);
+	const vegoid = decodeVegoid(tokenId);
+	const tickSpacing = decodeTickSpacing(tokenId);
+	const rawLegs = decodeAllLegs(tokenId);
+	const numLegs = countLegs(tokenId);
+	const legs = rawLegs.map((leg) => convertToTokenIdLeg(leg, tickSpacing));
+	return {
+		tokenId,
+		poolId,
+		vegoid,
+		tickSpacing,
+		legs,
+		legCount: numLegs
+	};
+}
+/**
+* Validate that a TokenId has the expected pool ID.
+*
+* @param tokenId - The TokenId to validate
+* @param expectedPoolId - The expected pool ID
+* @returns True if the pool IDs match
+*/
+function validatePoolId(tokenId, expectedPoolId) {
+	const actualPoolId = tokenId & (1n << 64n) - 1n;
+	return actualPoolId === expectedPoolId;
+}
+/**
+* Check if a TokenId represents a long position (any leg is long).
+*
+* @param tokenId - The TokenId to check
+* @returns True if any leg is long
+*/
+function hasLongLeg(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	return legs.some((leg) => leg.isLong);
+}
+/**
+* Check if a TokenId represents a short-only position.
+*
+* @param tokenId - The TokenId to check
+* @returns True if all legs are short
+*/
+function isShortOnly(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	return legs.length > 0 && legs.every((leg) => !leg.isLong);
+}
+/**
+* Check if a TokenId represents a spread (legs with different risk partners).
+*
+* @param tokenId - The TokenId to check
+* @returns True if any leg has a different risk partner
+*/
+function isSpread(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	return legs.some((leg) => leg.riskPartner !== leg.index);
+}
+/**
+* Get the asset index for a TokenId (from the first leg).
+*
+* @param tokenId - The TokenId
+* @returns The asset index (0 or 1), or undefined if no legs
+*/
+function getAssetIndex(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	if (legs.length === 0) return void 0;
+	return legs[0].asset;
+}
+/**
+* Check if a leg is a loan (width=0 and isLong=false).
+*
+* Loans borrow liquidity from the pool at a specific strike price.
+*
+* @param leg - The decoded leg to check
+* @returns True if the leg is a loan
+*/
+function isLoanLeg(leg) {
+	return leg.width === 0n && !leg.isLong;
+}
+/**
+* Check if a leg is a credit (width=0 and isLong=true).
+*
+* Credits lend liquidity to the pool at a specific strike price.
+*
+* @param leg - The decoded leg to check
+* @returns True if the leg is a credit
+*/
+function isCreditLeg(leg) {
+	return leg.width === 0n && leg.isLong;
+}
+/**
+* Check if a TokenId is a pure loan (all legs are loans).
+*
+* @param tokenId - The TokenId to check
+* @returns True if all legs are loans
+*/
+function isLoan(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	return legs.length > 0 && legs.every(isLoanLeg);
+}
+/**
+* Check if a TokenId is a pure credit (all legs are credits).
+*
+* @param tokenId - The TokenId to check
+* @returns True if all legs are credits
+*/
+function isCredit(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	return legs.length > 0 && legs.every(isCreditLeg);
+}
+/**
+* Check if a TokenId contains loan or credit legs (width=0).
+*
+* @param tokenId - The TokenId to check
+* @returns True if any leg has width=0 (loan or credit)
+*/
+function hasLoanOrCredit(tokenId) {
+	const legs = decodeAllLegs(tokenId);
+	return legs.some((leg) => leg.width === 0n);
+}
+
+//#endregion
+//#region src/panoptic/v2/simulations/tokenFlow.ts
+/**
+* PanopticPool getAssetsOf ABI.
+* Returns collateral assets (shares converted to underlying) for an account.
+*/
+const getAssetsOfAbi = [{
+	type: "function",
+	name: "getAssetsOf",
+	inputs: [{
+		name: "account",
+		type: "address"
+	}],
+	outputs: [{
+		name: "assets0",
+		type: "uint256"
+	}, {
+		name: "assets1",
+		type: "uint256"
+	}],
+	stateMutability: "view"
+}];
+/**
+* PanopticPool multicall ABI (inherited from Uniswap).
+* Uses delegatecall, preserving msg.sender throughout the chain.
+*/
+const multicallAbi = [{
+	type: "function",
+	name: "multicall",
+	inputs: [{
+		name: "data",
+		type: "bytes[]"
+	}],
+	outputs: [{
+		name: "results",
+		type: "bytes[]"
+	}],
+	stateMutability: "nonpayable"
+}, ...panopticErrorsAbi];
+/**
+* Simulate a contract call and measure token flow using PanopticPool.multicall.
+*
+* This function uses PanopticPool's inherited multicall (delegatecall-based) to chain:
+* 1. getAssetsOf(user) - read collateral assets before
+* 2. getCurrentTick() - read pool tick before
+* 3. Execute the target call (e.g., dispatch)
+* 4. getCurrentTick() - read pool tick after
+* 5. getAssetsOf(user) - read collateral assets after
+*
+* ## Why PanopticPool.multicall instead of Multicall3?
+* - Measures **collateral assets** (shares → underlying), not raw wallet balances
+* - Uses **delegatecall**, preserving msg.sender throughout the chain
+* - Single contract interaction with PanopticPool
+* - Correctly reflects what happens during position operations
+*
+* ## Same-Block Guarantee
+* All operations execute within a single eth_call, ensuring atomic consistency.
+*
+* @param params - Simulation parameters
+* @returns Token flow result
+*
+* @example
+* ```typescript
+* const callData = encodeFunctionData({
+*   abi: panopticPoolV2Abi,
+*   functionName: 'dispatch',
+*   args: [positionIdList, finalPositionIdList, positionSizes, tickAndSpreadLimits, false, 0n],
+* })
+*
+* const result = await simulateWithTokenFlow({
+*   client,
+*   poolAddress,
+*   user: userAddress,
+*   callData,
+* })
+*
+* if (result.success) {
+*   console.log('Token 0 change:', result.tokenFlow.delta0)
+*   console.log('Token 1 change:', result.tokenFlow.delta1)
+* }
+* ```
+*/
+async function simulateWithTokenFlow(params) {
+	const { client, poolAddress, user, callData, blockNumber, postCallData, preCallData } = params;
+	const getAssetsOfCallData = encodeFunctionData({
+		abi: getAssetsOfAbi,
+		functionName: "getAssetsOf",
+		args: [user]
+	});
+	const getCurrentTickCallData = encodeFunctionData({
+		abi: panopticPoolV2Abi,
+		functionName: "getCurrentTick"
+	});
+	const preLen = preCallData?.length ?? 0;
+	const multicallData = [
+		getAssetsOfCallData,
+		getCurrentTickCallData,
+		...preCallData ?? [],
+		callData,
+		getCurrentTickCallData,
+		getAssetsOfCallData,
+		...postCallData ?? []
+	];
+	try {
+		const { result } = await client.simulateContract({
+			address: poolAddress,
+			abi: multicallAbi,
+			functionName: "multicall",
+			args: [multicallData],
+			account: user,
+			blockNumber
+		});
+		const decodeAssets = (data) => {
+			const decoded = decodeFunctionResult({
+				abi: getAssetsOfAbi,
+				functionName: "getAssetsOf",
+				data
+			});
+			return {
+				assets0: decoded[0],
+				assets1: decoded[1]
+			};
+		};
+		const decodeTick = (data) => {
+			return BigInt(decodeFunctionResult({
+				abi: panopticPoolV2Abi,
+				functionName: "getCurrentTick",
+				data
+			}));
+		};
+		const assetsBefore = decodeAssets(result[0]);
+		const tickBefore = decodeTick(result[1]);
+		const tickAfter = decodeTick(result[3 + preLen]);
+		const assetsAfter = decodeAssets(result[4 + preLen]);
+		const preCallResults = preLen > 0 ? result.slice(2, 2 + preLen) : void 0;
+		const postCallResults = postCallData && postCallData.length > 0 ? result.slice(5 + preLen) : void 0;
+		const delta0 = assetsAfter.assets0 - assetsBefore.assets0;
+		const delta1 = assetsAfter.assets1 - assetsBefore.assets1;
+		let gasEstimate = 0n;
+		try {
+			gasEstimate = await client.estimateGas({
+				account: user,
+				to: poolAddress,
+				data: callData,
+				blockNumber
+			});
+		} catch {}
+		return {
+			success: true,
+			tokenFlow: {
+				delta0,
+				delta1,
+				balanceBefore0: assetsBefore.assets0,
+				balanceBefore1: assetsBefore.assets1,
+				balanceAfter0: assetsAfter.assets0,
+				balanceAfter1: assetsAfter.assets1,
+				tickBefore,
+				tickAfter
+			},
+			gasEstimate,
+			postCallResults,
+			preCallResults
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : "Simulation failed",
+			rawError: error instanceof Error ? error : void 0,
+			gasEstimate: 0n
+		};
+	}
+}
+
+//#endregion
+//#region src/panoptic/v2/simulations/simulateOpenPosition.ts
+/**
+* Simulate opening a position.
+*
+* Uses PanopticPool.multicall with getAssetsOf-dispatch-getAssetsOf pattern
+* to measure exact collateral asset movements, then enriches with decoded
+* position data and client-side greeks.
+*
+* @param params - Simulation parameters
+* @returns Simulation result with position data or error
+*
+* @example
+* ```typescript
+* import { MIN_TICK, MAX_TICK } from '@panoptic/sdk'
+*
+* const result = await simulateOpenPosition({
+*   client,
+*   poolAddress,
+*   account,
+*   existingPositionIds: [],
+*   tokenId,
+*   positionSize: 1n,
+*   tickLimitLow: MIN_TICK,
+*   tickLimitHigh: MAX_TICK,
+*   swapAtMint: false,
+*   chainId: 11155111n, // Sepolia
+* })
+*
+* if (result.success) {
+*   console.log('Gas estimate:', result.gasEstimate)
+*   console.log('Token 0 required:', result.data.amount0Required)
+*   console.log('Token 1 required:', result.data.amount1Required)
+*   console.log('Delta:', result.data.greeks.delta)
+* } else {
+*   console.log('Error:', result.error)
+* }
+* ```
+*/
+async function simulateOpenPosition(params) {
+	const { client, poolAddress, account, existingPositionIds, tokenId, positionSize, tickLimitLow, tickLimitHigh, spreadLimit = 0n, swapAtMint = false, usePremiaAsCollateral = false, builderCode = 0n, chainId, blockNumber } = params;
+	const targetBlockNumber = blockNumber ?? await client.getBlockNumber();
+	const metaPromise = getBlockMeta({
+		client,
+		blockNumber: targetBlockNumber
+	});
+	const tickLimits$1 = swapAtMint ? [
+		Number(tickLimitHigh),
+		Number(tickLimitLow),
+		Number(spreadLimit)
+	] : [
+		Number(tickLimitLow),
+		Number(tickLimitHigh),
+		Number(spreadLimit)
+	];
+	try {
+		const positionIdList = [tokenId];
+		const finalPositionIdList = [...existingPositionIds, tokenId];
+		const callData = encodeFunctionData({
+			abi: panopticPoolV2Abi,
+			functionName: "dispatch",
+			args: [
+				positionIdList,
+				finalPositionIdList,
+				[BigInt(positionSize)],
+				[tickLimits$1],
+				usePremiaAsCollateral,
+				builderCode
+			]
+		});
+		const getFullPositionsDataCallData = encodeFunctionData({
+			abi: panopticPoolV2Abi,
+			functionName: "getFullPositionsData",
+			args: [
+				account,
+				false,
+				finalPositionIdList
+			]
+		});
+		const flowResult = await simulateWithTokenFlow({
+			client,
+			poolAddress,
+			user: account,
+			callData,
+			blockNumber: targetBlockNumber,
+			postCallData: [getFullPositionsDataCallData]
+		});
+		if (!flowResult.success || !flowResult.tokenFlow) throw flowResult.rawError ?? new PanopticError(flowResult.error || "Token flow simulation failed");
+		const tokenFlow = flowResult.tokenFlow;
+		let postMintCollateralReqToken0 = 0n;
+		let postMintCollateralReqToken1 = 0n;
+		const perPositionCollateralReqs = [];
+		if (flowResult.postCallResults?.[0]) try {
+			const decoded$1 = decodeFunctionResult({
+				abi: panopticPoolV2Abi,
+				functionName: "getFullPositionsData",
+				data: flowResult.postCallResults[0]
+			});
+			const collateralReqs = decoded$1[3];
+			if (collateralReqs.length > 0) for (const packed of collateralReqs) {
+				const req = decodeLeftRightUnsigned(packed);
+				postMintCollateralReqToken0 += req.right;
+				postMintCollateralReqToken1 += req.left;
+				perPositionCollateralReqs.push({
+					token0: req.right,
+					token1: req.left
+				});
+			}
+		} catch {}
+		const decoded = decodeTokenId(tokenId);
+		let currentTick = 0n;
+		let poolTickSpacing = decoded.tickSpacing;
+		let utilization0 = 0n;
+		let utilization1 = 0n;
+		if (chainId !== void 0) try {
+			const pool = await getPool({
+				client,
+				poolAddress,
+				chainId,
+				blockNumber: targetBlockNumber
+			});
+			currentTick = pool.currentTick;
+			poolTickSpacing = pool.tickSpacing;
+			utilization0 = pool.collateralTracker0.utilization;
+			utilization1 = pool.collateralTracker1.utilization;
+		} catch {}
+		const greeks = decoded.legs.length > 0 && (chainId !== void 0 || currentTick !== 0n) ? calculatePositionGreeks({
+			legs: decoded.legs,
+			currentTick,
+			mintTick: currentTick,
+			positionSize,
+			poolTickSpacing
+		}) : {
+			value: 0n,
+			delta: 0n,
+			gamma: 0n
+		};
+		const _meta = await metaPromise;
+		const amount0Required = -tokenFlow.delta0;
+		const amount1Required = -tokenFlow.delta1;
+		const data = {
+			position: {
+				tokenId,
+				positionSize,
+				owner: account,
+				poolAddress,
+				legs: decoded.legs,
+				poolUtilization0AtMint: utilization0,
+				poolUtilization1AtMint: utilization1,
+				tickAtMint: currentTick,
+				timestampAtMint: _meta.blockTimestamp,
+				blockNumberAtMint: _meta.blockNumber,
+				swapAtMint,
+				premiaOwed0: 0n,
+				premiaOwed1: 0n,
+				assetIndex: 0n,
+				_meta
+			},
+			greeks,
+			amount0Required,
+			amount1Required,
+			postCollateral0: tokenFlow.balanceAfter0,
+			postCollateral1: tokenFlow.balanceAfter1,
+			postMintCollateralReqToken0,
+			postMintCollateralReqToken1,
+			perPositionCollateralReqs,
+			commission0: null,
+			commission1: null
+		};
+		return {
+			success: true,
+			data,
+			gasEstimate: flowResult.gasEstimate,
+			tokenFlow,
+			_meta
+		};
+	} catch (error) {
+		const _meta = await metaPromise;
+		return {
+			success: false,
+			error: error instanceof PanopticError ? error : new PanopticError(error instanceof Error ? error.message : "Simulation failed", error instanceof Error ? error : void 0),
+			_meta
+		};
+	}
+}
+
+//#endregion
+//#region src/panoptic/v2/writes/lending.ts
+/**
+* Resolve collateral tracker address for a given token in the pool.
+*/
+async function resolveCollateralTracker(client, poolAddress, chainId, token) {
+	const pool = await getPool({
+		client,
+		poolAddress,
+		chainId
+	});
+	const tokenIndex = resolveTokenIndex(token, pool.collateralTracker0.token, pool.collateralTracker1.token);
+	return tokenIndex === 0n ? pool.collateralTracker0.address : pool.collateralTracker1.address;
+}
+/**
+* Save a position ID list to storage.
+*/
+async function savePositionIds(storage, chainId, poolAddress, account, positionIds) {
+	const key = getPositionsKey(chainId, poolAddress, account);
+	await storage.set(key, jsonSerializer.stringify(positionIds));
+}
+/**
+* Supply collateral into a pool.
+*
+* Resolves the correct collateral tracker from the token address,
+* then delegates to the low-level `deposit()`.
+*
+* @param params - Supply parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await supply({
+*   client, walletClient, account, poolAddress,
+*   chainId: 11155111n,
+*   token: WETH_ADDRESS,
+*   amount: 1n * 10n**18n,
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function supply(params) {
+	const { client, walletClient, account, poolAddress, chainId, token, amount, isNativeETH, txOverrides } = params;
+	const collateralTrackerAddress = await resolveCollateralTracker(client, poolAddress, chainId, token);
+	return deposit({
+		client,
+		walletClient,
+		account,
+		collateralTrackerAddress,
+		assets: amount,
+		isNativeETH,
+		txOverrides
+	});
+}
+/**
+* Supply collateral and wait for confirmation.
+*/
+async function supplyAndWait(params) {
+	const result = await supply(params);
+	return result.wait();
+}
+/**
+* Withdraw (unsupply) collateral from a pool.
+*
+* Resolves the correct collateral tracker from the token address,
+* then delegates to the low-level `withdraw()`.
+*
+* @param params - Unsupply parameters
+* @returns TxResult
+*/
+async function unsupply(params) {
+	const { client, walletClient, account, poolAddress, chainId, token, amount, txOverrides } = params;
+	const collateralTrackerAddress = await resolveCollateralTracker(client, poolAddress, chainId, token);
+	return withdraw({
+		client,
+		walletClient,
+		account,
+		collateralTrackerAddress,
+		assets: amount,
+		txOverrides
+	});
+}
+/**
+* Withdraw collateral and wait for confirmation.
+*/
+async function unsupplyAndWait(params) {
+	const result = await unsupply(params);
+	return result.wait();
+}
+/**
+* Borrow tokens from a pool via a loan position.
+*
+* Creates a loan tokenId and mints it via dispatch. The loan borrows the
+* specified token without swapping (ascending tick limits = no swap).
+*
+* @param params - Borrow parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* const result = await borrow({
+*   client, walletClient, account, poolAddress,
+*   chainId: 11155111n,
+*   token: USDC_ADDRESS,
+*   amount: 100n * 10n**6n,
+*   slippageBps: 500n,
+* })
+* const receipt = await result.wait()
+* ```
+*/
+async function borrow(params) {
+	const { client, walletClient, account, poolAddress, chainId, token, amount, slippageBps, existingPositionIds: explicitIds, builderCode = 0n, storage, txOverrides } = params;
+	for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+		const [pool, positionIds] = await Promise.all([getPool({
+			client,
+			poolAddress,
+			chainId
+		}), resolvePositionIds(explicitIds, storage, chainId, poolAddress, account)]);
+		const token0 = pool.collateralTracker0.token;
+		const token1 = pool.collateralTracker1.token;
+		const tokenIndex = resolveTokenIndex(token, token0, token1);
+		const { tokenId: loanTokenId, adjustedSize } = buildUniqueLoan(pool.poolId, tokenIndex, tokenIndex, pool.currentTick, pool.tickSpacing, positionIds, amount);
+		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
+		const mintTickLimits = [
+			Number(tickLimitLow),
+			Number(tickLimitHigh),
+			0
+		];
+		const positionIdList = [loanTokenId];
+		const finalPositionIdList = [...positionIds, loanTokenId];
+		const positionSizes = [adjustedSize];
+		try {
+			const txResult = await submitWrite({
+				client,
+				walletClient,
+				account,
+				address: poolAddress,
+				abi: panopticPoolV2Abi,
+				functionName: "dispatch",
+				args: [
+					positionIdList,
+					finalPositionIdList,
+					positionSizes,
+					[mintTickLimits],
+					false,
+					builderCode
+				],
+				txOverrides
+			});
+			return {
+				...txResult,
+				loanTokenId
+			};
+		} catch (error) {
+			if (isInputListFailError(error) && attempt < MAX_RETRIES - 1) continue;
+			throw error;
+		}
+	}
+	throw new MaxRetriesExceededError("borrow");
+}
+/**
+* Borrow tokens and wait for confirmation.
+* If storage is provided, auto-tracks the new loan position.
+*/
+async function borrowAndWait(params) {
+	const result = await borrow(params);
+	const receipt = await result.wait();
+	if (params.storage && params.chainId !== void 0) {
+		const { poolAddress, chainId, storage, account, existingPositionIds: explicitIds } = params;
+		const positionIds = explicitIds ?? await getTrackedPositionIds({
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		await savePositionIds(storage, chainId, poolAddress, account, [...positionIds, result.loanTokenId]);
+	}
+	return receipt;
+}
+/**
+* Preview a borrow without executing it.
+*
+* Builds the loan tokenId (same logic as `borrow`) and runs a
+* dry-run `simulateOpenPosition` to check feasibility and return
+* post-mint collateral requirements.
+*
+* @param params - Preview parameters
+* @returns Preview result with tokenId, size, and simulation data
+*/
+async function previewBorrow(params) {
+	const { client, poolAddress, chainId, token, amount, slippageBps, account, existingPositionIds } = params;
+	const pool = await getPool({
+		client,
+		poolAddress,
+		chainId
+	});
+	const token0 = pool.collateralTracker0.token;
+	const token1 = pool.collateralTracker1.token;
+	const tokenIndex = resolveTokenIndex(token, token0, token1);
+	const { tokenId: loanTokenId, adjustedSize } = buildUniqueLoan(pool.poolId, tokenIndex, tokenIndex, pool.currentTick, pool.tickSpacing, existingPositionIds, amount);
+	const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
+	const simulation = await simulateOpenPosition({
+		client,
+		poolAddress,
+		account,
+		existingPositionIds,
+		tokenId: loanTokenId,
+		positionSize: adjustedSize,
+		tickLimitLow: BigInt(tickLimitLow),
+		tickLimitHigh: BigInt(tickLimitHigh),
+		chainId
+	});
+	let collateralReqToken0 = null;
+	let collateralReqToken1 = null;
+	if (simulation.success) {
+		const reqs = simulation.data.perPositionCollateralReqs;
+		if (reqs.length > 0) {
+			const loanReq = reqs[reqs.length - 1];
+			collateralReqToken0 = loanReq.token0;
+			collateralReqToken1 = loanReq.token1;
+		}
+	}
+	return {
+		loanTokenId,
+		adjustedSize,
+		simulation,
+		collateralReqToken0,
+		collateralReqToken1
+	};
+}
+/**
+* Repay a loan position (full or partial).
+*
+* - Full repay (`amount >= currentSize`): Burns the loan position entirely.
+* - Partial repay (`amount < currentSize`): Uses roll-same-tokenId pattern
+*   to reduce the position size.
+*
+* @param params - Repay parameters
+* @returns TxResult
+*
+* @example
+* ```typescript
+* // Full repay
+* await repay({
+*   client, walletClient, account, poolAddress,
+*   chainId: 11155111n,
+*   loanTokenId,
+*   amount: MAX_UINT128, // repay all
+*   slippageBps: 500n,
+* })
+*
+* // Partial repay
+* await repay({
+*   client, walletClient, account, poolAddress,
+*   chainId: 11155111n,
+*   loanTokenId,
+*   amount: 50n * 10n**6n, // repay 50 USDC
+*   slippageBps: 500n,
+* })
+* ```
+*/
+async function repay(params) {
+	const { client, walletClient, account, poolAddress, chainId, loanTokenId, amount, slippageBps, existingPositionIds: explicitIds, builderCode = 0n, storage, txOverrides } = params;
+	for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+		const [positionIds, fullDataResult] = await Promise.all([resolvePositionIds(explicitIds, storage, chainId, poolAddress, account), client.readContract({
+			address: poolAddress,
+			abi: panopticPoolV2Abi,
+			functionName: "getFullPositionsData",
+			args: [
+				account,
+				false,
+				[loanTokenId]
+			]
+		})]);
+		const balanceRaw = fullDataResult[2][0];
+		const currentSize = balanceRaw & (1n << 128n) - 1n;
+		const pool = await getPool({
+			client,
+			poolAddress,
+			chainId
+		});
+		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
+		const ascendingLimits = [
+			Number(tickLimitLow),
+			Number(tickLimitHigh),
+			0
+		];
+		if (amount >= currentSize) {
+			const finalPositionIdList = positionIds.filter((id) => id !== loanTokenId);
+			try {
+				return await submitWrite({
+					client,
+					walletClient,
+					account,
+					address: poolAddress,
+					abi: panopticPoolV2Abi,
+					functionName: "dispatch",
+					args: [
+						[loanTokenId],
+						finalPositionIdList,
+						[0n],
+						[ascendingLimits],
+						false,
+						builderCode
+					],
+					txOverrides
+				});
+			} catch (error) {
+				if (isInputListFailError(error) && attempt < MAX_RETRIES - 1) continue;
+				throw error;
+			}
+		} else {
+			const newSize = currentSize - amount;
+			const finalPositionIdList = positionIds.filter((id) => id !== loanTokenId).concat([loanTokenId]);
+			try {
+				return await submitWrite({
+					client,
+					walletClient,
+					account,
+					address: poolAddress,
+					abi: panopticPoolV2Abi,
+					functionName: "dispatch",
+					args: [
+						[loanTokenId, loanTokenId],
+						finalPositionIdList,
+						[currentSize, newSize],
+						[ascendingLimits, ascendingLimits],
+						false,
+						builderCode
+					],
+					txOverrides
+				});
+			} catch (error) {
+				if (isInputListFailError(error) && attempt < MAX_RETRIES - 1) continue;
+				throw error;
+			}
+		}
+	}
+	throw new MaxRetriesExceededError("repay");
+}
+/**
+* Repay a loan and wait for confirmation.
+* If storage is provided, auto-updates the tracked positions (removes on full repay).
+*/
+async function repayAndWait(params) {
+	const result = await repay(params);
+	const receipt = await result.wait();
+	if (params.storage && params.chainId !== void 0) {
+		const { client, account, poolAddress, chainId, loanTokenId, storage, existingPositionIds: explicitIds } = params;
+		const fullDataResult = await client.readContract({
+			address: poolAddress,
+			abi: panopticPoolV2Abi,
+			functionName: "getFullPositionsData",
+			args: [
+				account,
+				false,
+				[loanTokenId]
+			]
+		});
+		const balanceRaw = fullDataResult[2][0];
+		const currentSize = balanceRaw & (1n << 128n) - 1n;
+		if (currentSize === 0n) {
+			const positionIds = explicitIds ?? await getTrackedPositionIds({
+				chainId,
+				poolAddress,
+				account,
+				storage
+			});
+			await savePositionIds(storage, chainId, poolAddress, account, positionIds.filter((id) => id !== loanTokenId));
+		}
+	}
+	return receipt;
+}
+/**
+* Identify loan tokenIds for a specific token and return their sizes.
+*/
+async function getLoanPositionsForToken(client, poolAddress, account, existingPositionIds, tokenIndex) {
+	const loanIds = existingPositionIds.filter((id) => {
+		if (!isLoan(id)) return false;
+		const legs = decodeAllLegs(id);
+		return legs.length > 0 && legs[0].tokenType === tokenIndex;
+	});
+	if (loanIds.length === 0) return [];
+	const fullData = await client.readContract({
+		address: poolAddress,
+		abi: panopticPoolV2Abi,
+		functionName: "getFullPositionsData",
+		args: [
+			account,
+			false,
+			loanIds
+		]
+	});
+	const balances = fullData[2];
+	return loanIds.map((tokenId, i) => {
+		const positionSize = balances[i] & (1n << 128n) - 1n;
+		const legs = decodeAllLegs(tokenId);
+		const optionRatio = legs[0].optionRatio;
+		const tokenAmount = positionSize * optionRatio;
+		return {
+			tokenId,
+			positionSize,
+			optionRatio,
+			tokenAmount
+		};
+	});
+}
+/**
+* Smart repay: burns all loan positions for a token and optionally re-opens a smaller one.
+*
+* Unlike `repay()` which targets a single loanTokenId, this function handles
+* multiple loans transparently. The user specifies a repay amount and the SDK:
+* 1. Finds all loan positions for the specified token
+* 2. Burns them all
+* 3. If repayAmount < totalDebt, opens a new loan for the remainder
+*
+* @param params - Smart repay parameters
+* @returns TxResult
+*/
+async function smartRepay(params) {
+	const { client, walletClient, account, poolAddress, chainId, token, amount, slippageBps, existingPositionIds, builderCode = 0n, txOverrides } = params;
+	for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+		const pool = await getPool({
+			client,
+			poolAddress,
+			chainId
+		});
+		const tokenIndex = resolveTokenIndex(token, pool.collateralTracker0.token, pool.collateralTracker1.token);
+		const loans = await getLoanPositionsForToken(client, poolAddress, account, existingPositionIds, tokenIndex);
+		if (loans.length === 0) throw new NoLoanPositionsError(token);
+		const totalDebt = loans.reduce((sum, l) => sum + l.tokenAmount, 0n);
+		const loanIds = loans.map((l) => l.tokenId);
+		const remainder = totalDebt > amount ? totalDebt - amount : 0n;
+		const { low: tickLimitLow, high: tickLimitHigh } = tickLimits(pool.currentTick, slippageBps);
+		const ascendingLimits = [
+			Number(tickLimitLow),
+			Number(tickLimitHigh),
+			0
+		];
+		const nonLoanIds = existingPositionIds.filter((id) => !loanIds.includes(id));
+		const opsPositionIds = [...loanIds];
+		const opsSizes = loanIds.map(() => 0n);
+		const opsLimits = loanIds.map(() => ascendingLimits);
+		let finalPositionIdList;
+		if (remainder > 0n) {
+			const { tokenId: newLoanId, adjustedSize } = buildUniqueLoan(pool.poolId, tokenIndex, tokenIndex, pool.currentTick, pool.tickSpacing, nonLoanIds, remainder);
+			opsPositionIds.push(newLoanId);
+			opsSizes.push(adjustedSize);
+			opsLimits.push(ascendingLimits);
+			finalPositionIdList = [...nonLoanIds, newLoanId];
+		} else finalPositionIdList = nonLoanIds;
+		try {
+			return await submitWrite({
+				client,
+				walletClient,
+				account,
+				address: poolAddress,
+				abi: panopticPoolV2Abi,
+				functionName: "dispatch",
+				args: [
+					opsPositionIds,
+					finalPositionIdList,
+					opsSizes,
+					opsLimits,
+					false,
+					builderCode
+				],
+				txOverrides
+			});
+		} catch (error) {
+			if (isInputListFailError(error) && attempt < MAX_RETRIES - 1) continue;
+			throw error;
+		}
+	}
+	throw new MaxRetriesExceededError("smartRepay");
+}
+/**
+* Smart repay and wait for confirmation.
+*/
+async function smartRepayAndWait(params) {
+	const result = await smartRepay(params);
+	const receipt = await result.wait();
+	if (params.storage && params.chainId !== void 0) {
+		const { client, account, poolAddress, chainId, token, amount, storage, existingPositionIds } = params;
+		const pool = await getPool({
+			client,
+			poolAddress,
+			chainId
+		});
+		const tokenIndex = resolveTokenIndex(token, pool.collateralTracker0.token, pool.collateralTracker1.token);
+		const loans = await getLoanPositionsForToken(client, poolAddress, account, existingPositionIds, tokenIndex);
+		const loanIds = loans.map((l) => l.tokenId);
+		const totalDebt = loans.reduce((sum, l) => sum + l.tokenAmount, 0n);
+		const remainder = totalDebt > amount ? totalDebt - amount : 0n;
+		const positionIds = existingPositionIds ?? await getTrackedPositionIds({
+			chainId,
+			poolAddress,
+			account,
+			storage
+		});
+		let updatedIds = positionIds.filter((id) => !loanIds.includes(id));
+		if (remainder > 0n) {
+			const nonLoanIds = existingPositionIds.filter((id) => !loanIds.includes(id));
+			const newLoan = buildUniqueLoan(pool.poolId, tokenIndex, tokenIndex, pool.currentTick, pool.tickSpacing, nonLoanIds, remainder);
+			updatedIds = [...updatedIds, newLoan.tokenId];
+		}
+		await savePositionIds(storage, chainId, poolAddress, account, updatedIds);
+	}
+	return receipt;
+}
+
+//#endregion
+export { addLegToTokenId, approve, approveAndWait, approvePool, assertCanBurn, assertCanForceExercise, assertCanLiquidate, assertCanMint, assertFresh, assertHealthy, assertTradeable, borrow, borrowAndWait, buildBatchDispatchArgs, buildOpenPositionCalldata, buildUniqueLoan, calculateResyncBlock, cancelTransaction, checkApproval, clearCheckpoint, clearTrackedPositions, closePosition, closePositionAndWait, countLegs, createFileStorage, createMemoryStorage, createNonceManager, createTokenIdBuilder, decodeAllLegs, decodeDispatchCalldata, decodeLeg, decodePoolId, decodeTickSpacing as decodeTickSpacing$1, decodeTokenId, decodeVegoid, deployNewPool, deployNewPoolAndWait, deposit, depositAndWait, detectReorg, dispatch, dispatchAndWait, encodeLeg, encodePoolId, encodeV4PoolId, executeBatchDispatch, executeBatchDispatchAndWait, forceExercise, forceExerciseAndWait, getAssetIndex, getClosedPositionsKey, getOpenPositionIds, getPendingPositionsKey, getPoolMetaKey, getPoolPrefix, getPositionMetaKey, getPositionsKey, getSchemaVersionKey, getSyncCheckpointKey, getTrackedChunksKey, getTrackedPositionIds, hasLoanOrCredit, hasLongLeg, isCredit, isCreditLeg, isGasError, isInputListFailError, isLoan, isLoanLeg, isNonceError, isPositionTracked, isRetryableRpcError, isShortOnly, isSpread, jsonSerializer, liquidate, liquidateAndWait, loadCheckpoint, mint, mintAndWait, openPosition, openPositionAndWait, pokeOracle, pokeOracleAndWait, previewBorrow, previewUnwrap, previewWrap, publicBroadcaster, recoverSnapshot, recoverSnapshotFromTx, redeem, redeemAndWait, repay, repayAndWait, resolveTokenIndex, rollPosition, rollPositionAndWait, saveCheckpoint, settleAccumulatedPremia, settleAccumulatedPremiaAndWait, simulateOpenPosition, simulateWithTokenFlow, smartRepay, smartRepayAndWait, speedUpTransaction, supply, supplyAndWait, swapExactIn, swapExactInAndWait, swapExactOut, swapExactOutAndWait, syncPositions, unsupply, unsupplyAndWait, unwrapXstock, unwrapXstockAndWait, validateBatch, validatePoolId, verifyBlockContinuity, withdraw, withdrawAndWait, withdrawWithPositions, withdrawWithPositionsAndWait, wrapXstock, wrapXstockAndWait, xstockWrapperAbi };
+//# sourceMappingURL=writes-CVCD6Ers.js.map