@strobelabs/perpcity-sdk 0.5.0 → 0.6.0

package/dist/{index.mjs → index.cjs}

@@ -1,3 +1,121 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BEACON_ABI: () => BEACON_ABI,
+  BIGINT_1E6: () => BIGINT_1E6,
+  ContractError: () => ContractError,
+  DEFAULT_MAKER_SLIPPAGE_TOLERANCE: () => DEFAULT_MAKER_SLIPPAGE_TOLERANCE,
+  ErrorCategory: () => ErrorCategory,
+  ErrorSource: () => ErrorSource,
+  INT256_THRESHOLD: () => INT256_THRESHOLD,
+  InsufficientFundsError: () => InsufficientFundsError,
+  MAX_PRICE: () => MAX_PRICE,
+  MAX_TICK: () => MAX_TICK,
+  MAX_UINT128: () => MAX_UINT128,
+  MIN_PRICE: () => MIN_PRICE,
+  MIN_TICK: () => MIN_TICK,
+  NUMBER_1E6: () => NUMBER_1E6,
+  OpenPosition: () => OpenPosition,
+  PERP_MANAGER_ABI: () => PERP_MANAGER_ABI,
+  PerpCityContext: () => PerpCityContext,
+  PerpCityError: () => PerpCityError,
+  Q96: () => Q96,
+  RPCError: () => RPCError,
+  TransactionRejectedError: () => TransactionRejectedError,
+  UINT256_MAX: () => UINT256_MAX,
+  ValidationError: () => ValidationError,
+  adjustMargin: () => adjustMargin,
+  adjustNotional: () => adjustNotional,
+  applySlippage: () => applySlippage,
+  approveUsdc: () => approveUsdc,
+  calculateAlignedTicks: () => calculateAlignedTicks,
+  calculateClosePositionParams: () => calculateClosePositionParams,
+  calculateEntryPrice: () => calculateEntryPrice,
+  calculateLeverage: () => calculateLeverage,
+  calculateLiquidationPrice: () => calculateLiquidationPrice,
+  calculateLiquidityForTargetRatio: () => calculateLiquidityForTargetRatio,
+  calculatePnlPercentage: () => calculatePnlPercentage,
+  calculatePositionSize: () => calculatePositionSize,
+  calculatePositionValue: () => calculatePositionValue,
+  closePosition: () => closePosition,
+  closePositionWithQuote: () => closePositionWithQuote,
+  convertFundingDiffX96ToPercentPerPeriod: () => convertFundingDiffX96ToPercentPerPeriod,
+  convertFundingPerSecondX96ToPercentPerDay: () => convertFundingPerSecondX96ToPercentPerDay,
+  convertFundingPerSecondX96ToPercentPerMinute: () => convertFundingPerSecondX96ToPercentPerMinute,
+  createPerp: () => createPerp,
+  estimateLiquidity: () => estimateLiquidity,
+  getFundingRate: () => getFundingRate,
+  getIndexTWAP: () => getIndexTWAP,
+  getIndexValue: () => getIndexValue,
+  getPerpBeacon: () => getPerpBeacon,
+  getPerpBounds: () => getPerpBounds,
+  getPerpFees: () => getPerpFees,
+  getPerpMark: () => getPerpMark,
+  getPerpTickSpacing: () => getPerpTickSpacing,
+  getPositionEffectiveMargin: () => getPositionEffectiveMargin,
+  getPositionFundingPayment: () => getPositionFundingPayment,
+  getPositionId: () => getPositionId,
+  getPositionIsLiquidatable: () => getPositionIsLiquidatable,
+  getPositionIsLong: () => getPositionIsLong,
+  getPositionIsMaker: () => getPositionIsMaker,
+  getPositionLiveDetails: () => getPositionLiveDetails,
+  getPositionLiveDetailsFromContract: () => getPositionLiveDetailsFromContract,
+  getPositionPerpId: () => getPositionPerpId,
+  getPositionPnl: () => getPositionPnl,
+  getRpcUrl: () => getRpcUrl,
+  getUsdcAllowance: () => getUsdcAllowance,
+  getUserOpenPositions: () => getUserOpenPositions,
+  getUserUsdcBalance: () => getUserUsdcBalance,
+  getUserWalletAddress: () => getUserWalletAddress,
+  marginRatioToLeverage: () => marginRatioToLeverage,
+  openMakerPosition: () => openMakerPosition,
+  openTakerPosition: () => openTakerPosition,
+  parseContractError: () => parseContractError,
+  priceToSqrtPriceX96: () => priceToSqrtPriceX96,
+  priceToTick: () => priceToTick,
+  quoteClosePosition: () => quoteClosePosition,
+  quoteOpenMakerPosition: () => quoteOpenMakerPosition,
+  quoteTakerPosition: () => quoteTakerPosition,
+  scale6Decimals: () => scale6Decimals,
+  scaleFrom6Decimals: () => scaleFrom6Decimals,
+  scaleFromX96: () => scaleFromX96,
+  scaleToX96: () => scaleToX96,
+  sqrtPriceX96ToPrice: () => sqrtPriceX96ToPrice,
+  tickToPrice: () => tickToPrice,
+  uint256ToInt256: () => uint256ToInt256,
+  withErrorHandling: () => withErrorHandling
+});
+module.exports = __toCommonJS(index_exports);
+
 // src/abis/beacon.ts
 var BEACON_ABI = [
   {
@@ -1777,19 +1895,14 @@ var PERP_MANAGER_ABI = [
         type: "int256"
       },
       {
-        internalType: "int256",
+        internalType: "uint256",
         name: "netMargin",
-        type: "int256"
+        type: "uint256"
       },
       {
         internalType: "bool",
         name: "wasLiquidated",
         type: "bool"
-      },
-      {
-        internalType: "uint256",
-        name: "notional",
-        type: "uint256"
       }
     ],
     stateMutability: "nonpayable",
@@ -2266,13 +2379,8 @@ var PERP_MANAGER_ABI = [
 ];
 
 // src/context.ts
-import TTLCache from "@isaacs/ttlcache";
-import {
-  createPublicClient,
-  erc20Abi as erc20Abi2,
-  formatUnits,
-  http
-} from "viem";
+var import_ttlcache = __toESM(require("@isaacs/ttlcache"), 1);
+var import_viem3 = require("viem");
 
 // src/abis/fees.ts
 var FEES_ABI = [
@@ -2353,13 +2461,22 @@ var MARGIN_RATIOS_ABI = [
 ];
 
 // src/utils/approve.ts
-import { erc20Abi } from "viem";
+var import_viem = require("viem");
 var DEFAULT_CONFIRMATIONS = 2;
+async function getUsdcAllowance(context, owner) {
+  const deployments = context.deployments();
+  return context.publicClient.readContract({
+    address: deployments.usdc,
+    abi: import_viem.erc20Abi,
+    functionName: "allowance",
+    args: [owner, deployments.perpManager]
+  });
+}
 async function approveUsdc(context, amount, confirmations = DEFAULT_CONFIRMATIONS) {
   const deployments = context.deployments();
   const { request } = await context.publicClient.simulateContract({
     address: deployments.usdc,
-    abi: erc20Abi,
+    abi: import_viem.erc20Abi,
     functionName: "approve",
     args: [deployments.perpManager, amount],
     account: context.walletClient.account
@@ -2375,6 +2492,12 @@ async function approveUsdc(context, amount, confirmations = DEFAULT_CONFIRMATION
 var NUMBER_1E6 = 1e6;
 var BIGINT_1E6 = 1000000n;
 var Q96 = 79228162514264337593543950336n;
+var MIN_TICK = -887272;
+var MAX_TICK = 887272;
+var MIN_PRICE = 1e-6;
+var MAX_PRICE = 1e6;
+var UINT256_MAX = (1n << 256n) - 1n;
+var INT256_THRESHOLD = 1n << 255n;
 
 // src/utils/conversions.ts
 function priceToSqrtPriceX96(price) {
@@ -2407,12 +2530,23 @@ function priceToTick(price, roundDown) {
   if (price <= 0) {
     throw new Error("Price must be positive");
   }
+  if (price < MIN_PRICE || price > MAX_PRICE) {
+    throw new Error(
+      `Price ${price} is outside the representable range [${MIN_PRICE}, ${MAX_PRICE}]`
+    );
+  }
   const logPrice = Math.log(price) / Math.log(1.0001);
   return roundDown ? Math.floor(logPrice) : Math.ceil(logPrice);
 }
 function tickToPrice(tick) {
   return 1.0001 ** tick;
 }
+function uint256ToInt256(value) {
+  if (value >= INT256_THRESHOLD) {
+    return value - UINT256_MAX - 1n;
+  }
+  return value;
+}
 function sqrtPriceX96ToPrice(sqrtPriceX96) {
   const priceX96 = sqrtPriceX96 * sqrtPriceX96 / Q96;
   return scaleFromX96(priceX96);
@@ -2428,7 +2562,7 @@ function scaleFrom6Decimals(value) {
 }
 
 // src/utils/errors.ts
-import { BaseError, ContractFunctionRevertedError } from "viem";
+var import_viem2 = require("viem");
 var ErrorCategory = /* @__PURE__ */ ((ErrorCategory2) => {
   ErrorCategory2["USER_ERROR"] = "USER_ERROR";
   ErrorCategory2["STATE_ERROR"] = "STATE_ERROR";
@@ -2486,9 +2620,9 @@ function parseContractError(error) {
   if (error instanceof PerpCityError) {
     return error;
   }
-  if (error instanceof BaseError) {
-    const revertError = error.walk((err) => err instanceof ContractFunctionRevertedError);
-    if (revertError instanceof ContractFunctionRevertedError) {
+  if (error instanceof import_viem2.BaseError) {
+    const revertError = error.walk((err) => err instanceof import_viem2.ContractFunctionRevertedError);
+    if (revertError instanceof import_viem2.ContractFunctionRevertedError) {
       const errorName = revertError.data?.errorName ?? "Unknown";
       const args = revertError.data?.args ?? [];
       const { message, debug } = formatContractError(errorName, args);
@@ -2653,7 +2787,7 @@ function formatContractError(errorName, args) {
       };
     case "MinimumAmountInsufficient":
       return {
-        message: `Minimum amount not met. Required: ${args[0]}, Received: ${args[1]}`,
+        message: "Slippage tolerance exceeded. The position's value moved unfavorably during execution. Try increasing your slippage tolerance.",
         debug: { source, category: "USER_ERROR" /* USER_ERROR */ }
       };
     case "PriceImpactTooHigh":
@@ -2932,6 +3066,23 @@ async function withErrorHandling(fn, context) {
   }
 }
 
+// src/utils/funding.ts
+var PRECISION = 10n ** 18n;
+function convertFundingDiffX96ToPercentPerPeriod(fundingDiffX96, interval, periodSeconds) {
+  const scaledRate = fundingDiffX96 * periodSeconds * PRECISION / (Q96 * interval);
+  return Number(scaledRate) / Number(PRECISION);
+}
+function convertFundingPerSecondX96ToPercentPerMinute(fundingPerSecondX96) {
+  const SECONDS_PER_MINUTE = 60n;
+  const scaledRate = fundingPerSecondX96 * SECONDS_PER_MINUTE * PRECISION / Q96;
+  return Number(scaledRate) / Number(PRECISION);
+}
+function convertFundingPerSecondX96ToPercentPerDay(fundingPerSecondX96) {
+  const SECONDS_PER_DAY = 86400n;
+  const scaledRate = fundingPerSecondX96 * SECONDS_PER_DAY * PRECISION / Q96;
+  return Number(scaledRate) / Number(PRECISION);
+}
+
 // src/utils/liquidity.ts
 async function estimateLiquidity(_context, tickLower, tickUpper, usdScaled) {
   if (tickLower >= tickUpper) {
@@ -3034,16 +3185,16 @@ function getRpcUrl(config = {}) {
 // src/context.ts
 var PerpCityContext = class {
   constructor(config) {
-    this.configCache = new TTLCache({ ttl: 5 * 60 * 1e3 });
+    this.configCache = new import_ttlcache.default({ ttl: 5 * 60 * 1e3 });
     this.walletClient = config.walletClient;
     if (!config.walletClient.chain?.id) {
       throw new Error(
         "PerpCityContext: walletClient.chain must be defined with a numeric id. Ensure your walletClient was created with a chain parameter."
       );
     }
-    this.publicClient = createPublicClient({
+    this.publicClient = (0, import_viem3.createPublicClient)({
       chain: config.walletClient.chain,
-      transport: http(config.rpcUrl, { batch: true })
+      transport: (0, import_viem3.http)(config.rpcUrl, { batch: true })
     });
     this._deployments = config.deployments;
   }
@@ -3125,8 +3276,7 @@ var PerpCityContext = class {
       const tickSpacing = Number(cfg.key.tickSpacing);
       let sqrtPriceX96;
       if (markPrice) {
-        const sqrtPrice = Math.sqrt(markPrice);
-        sqrtPriceX96 = BigInt(Math.floor(sqrtPrice * 2 ** 96));
+        sqrtPriceX96 = priceToSqrtPriceX96(markPrice);
       } else {
         sqrtPriceX96 = await this.publicClient.readContract({
           address: this.deployments().perpManager,
@@ -3211,7 +3361,7 @@ var PerpCityContext = class {
   async fetchUserData(userAddress, positions) {
     const usdcBalance = await this.publicClient.readContract({
       address: this.deployments().usdc,
-      abi: erc20Abi2,
+      abi: import_viem3.erc20Abi,
       functionName: "balanceOf",
       args: [userAddress]
     });
@@ -3229,7 +3379,7 @@ var PerpCityContext = class {
     );
     return {
       walletAddress: userAddress,
-      usdcBalance: Number(formatUnits(usdcBalance, 6)),
+      usdcBalance: Number((0, import_viem3.formatUnits)(usdcBalance, 6)),
       openPositions: openPositionsData
     };
   }
@@ -3248,9 +3398,10 @@ var PerpCityContext = class {
         );
       }
       return {
-        pnl: Number(formatUnits(pnl, 6)),
-        fundingPayment: Number(formatUnits(funding, 6)),
-        effectiveMargin: Number(formatUnits(netMargin, 6)),
+        pnl: Number((0, import_viem3.formatUnits)(pnl, 6)),
+        // Negate so positive = user receives funding
+        fundingPayment: -Number((0, import_viem3.formatUnits)(funding, 6)),
+        effectiveMargin: Number((0, import_viem3.formatUnits)(uint256ToInt256(netMargin), 6)),
         isLiquidatable: wasLiquidated
       };
     }, `fetchPositionLiveDetailsFromContract for position ${positionId}`);
@@ -3294,29 +3445,35 @@ var PerpCityContext = class {
         args: [positionId]
       });
       const resultArray = result;
-      const [perpId, margin, entryPerpDelta, entryUsdDelta, , , , marginRatios] = resultArray;
+      const [perpId, margin, entryPerpDelta, entryUsdDelta, , , , marginRatios, makerDetailsRaw] = resultArray;
       const zeroPerpId = `0x${"0".repeat(64)}`;
       if (perpId === zeroPerpId) {
         throw new Error(`Position ${positionId} does not exist`);
       }
+      const isMaker = makerDetailsRaw != null && (makerDetailsRaw.tickLower !== 0 || makerDetailsRaw.tickUpper !== 0);
       return {
         perpId,
         positionId,
-        margin: Number(formatUnits(margin, 6)),
+        margin: Number((0, import_viem3.formatUnits)(margin, 6)),
         entryPerpDelta,
         entryUsdDelta,
         marginRatios: {
           min: Number(marginRatios.min),
           max: Number(marginRatios.max),
           liq: Number(marginRatios.liq)
-        }
+        },
+        makerDetails: isMaker ? {
+          unlockTimestamp: Number(makerDetailsRaw.unlockTimestamp),
+          tickLower: makerDetailsRaw.tickLower,
+          tickUpper: makerDetailsRaw.tickUpper
+        } : null
       };
     }, `getPositionRawData for position ${positionId}`);
   }
 };
 
 // src/functions/open-position.ts
-import { decodeEventLog, formatUnits as formatUnits2 } from "viem";
+var import_viem4 = require("viem");
 var OpenPosition = class _OpenPosition {
   constructor(context, perpId, positionId, isLong, isMaker, txHash) {
     this.context = context;
@@ -3353,7 +3510,7 @@ var OpenPosition = class _OpenPosition {
         let _wasFullyClosed = false;
         for (const log of receipt.logs) {
           try {
-            const openedDecoded = decodeEventLog({
+            const openedDecoded = (0, import_viem4.decodeEventLog)({
               abi: PERP_MANAGER_ABI,
               data: log.data,
               topics: log.topics,
@@ -3367,7 +3524,7 @@ var OpenPosition = class _OpenPosition {
             }
           } catch (_e) {
             try {
-              const closedDecoded = decodeEventLog({
+              const closedDecoded = (0, import_viem4.decodeEventLog)({
                 abi: PERP_MANAGER_ABI,
                 data: log.data,
                 topics: log.topics,
@@ -3415,9 +3572,9 @@ var OpenPosition = class _OpenPosition {
         );
       }
       return {
-        pnl: Number(formatUnits2(pnl, 6)),
-        fundingPayment: Number(formatUnits2(funding, 6)),
-        effectiveMargin: Number(formatUnits2(netMargin, 6)),
+        pnl: Number((0, import_viem4.formatUnits)(pnl, 6)),
+        fundingPayment: Number((0, import_viem4.formatUnits)(funding, 6)),
+        effectiveMargin: Number((0, import_viem4.formatUnits)(uint256ToInt256(netMargin), 6)),
         isLiquidatable: wasLiquidated
       };
     }, `liveDetails for position ${this.positionId}`);
@@ -3425,6 +3582,8 @@ var OpenPosition = class _OpenPosition {
 };
 
 // src/functions/perp.ts
+var TWAVG_WINDOW = 3600;
+var INTERVAL = 86400n;
 function getPerpMark(perpData) {
   return perpData.mark;
 }
@@ -3440,9 +3599,58 @@ function getPerpFees(perpData) {
 function getPerpTickSpacing(perpData) {
   return perpData.tickSpacing;
 }
+async function getFundingRate(context, perpId) {
+  return withErrorHandling(async () => {
+    const perpManagerAddr = context.deployments().perpManager;
+    const cfg = await context.getPerpConfig(perpId);
+    const [twAvgSqrtMarkX96, twAvgIndexX96] = await Promise.all([
+      context.publicClient.readContract({
+        address: perpManagerAddr,
+        abi: PERP_MANAGER_ABI,
+        functionName: "timeWeightedAvgSqrtPriceX96",
+        args: [perpId, TWAVG_WINDOW]
+      }),
+      context.publicClient.readContract({
+        address: cfg.beacon,
+        abi: BEACON_ABI,
+        functionName: "twAvg",
+        args: [TWAVG_WINDOW]
+      })
+    ]);
+    const twAvgMarkX96 = twAvgSqrtMarkX96 * twAvgSqrtMarkX96 / Q96;
+    const fundingDiffX96 = twAvgMarkX96 - twAvgIndexX96;
+    const fundingPerSecondX96 = fundingDiffX96 / INTERVAL;
+    return {
+      ratePerDay: convertFundingDiffX96ToPercentPerPeriod(fundingDiffX96, INTERVAL, 86400n),
+      ratePerMinute: convertFundingDiffX96ToPercentPerPeriod(fundingDiffX96, INTERVAL, 60n),
+      rawX96: fundingPerSecondX96
+    };
+  }, `getFundingRate for perp ${perpId}`);
+}
+async function getIndexValue(context, perpId) {
+  return withErrorHandling(async () => {
+    const perpData = await context.getPerpData(perpId);
+    return await context.publicClient.readContract({
+      address: perpData.beacon,
+      abi: BEACON_ABI,
+      functionName: "index"
+    });
+  }, `getIndexValue for perp ${perpId}`);
+}
+async function getIndexTWAP(context, perpId, secondsAgo) {
+  return withErrorHandling(async () => {
+    const perpData = await context.getPerpData(perpId);
+    return await context.publicClient.readContract({
+      address: perpData.beacon,
+      abi: BEACON_ABI,
+      functionName: "twAvg",
+      args: [secondsAgo]
+    });
+  }, `getIndexTWAP for perp ${perpId}`);
+}
 
 // src/functions/perp-manager.ts
-import { decodeEventLog as decodeEventLog2, erc20Abi as erc20Abi3 } from "viem";
+var import_viem5 = require("viem");
 async function createPerp(context, params) {
   return withErrorHandling(async () => {
     const deployments = context.deployments();
@@ -3468,13 +3676,15 @@ async function createPerp(context, params) {
       account: context.walletClient.account
     });
     const txHash = await context.walletClient.writeContract(request);
-    const receipt = await context.publicClient.waitForTransactionReceipt({ hash: txHash });
+    const receipt = await context.publicClient.waitForTransactionReceipt({
+      hash: txHash
+    });
     if (receipt.status === "reverted") {
       throw new Error(`Transaction reverted. Hash: ${txHash}`);
     }
     for (const log of receipt.logs) {
       try {
-        const decoded = decodeEventLog2({
+        const decoded = (0, import_viem5.decodeEventLog)({
           abi: PERP_MANAGER_ABI,
           data: log.data,
           topics: log.topics,
@@ -3511,7 +3721,7 @@ async function openTakerPosition(context, perpId, params) {
     const requiredAmount = marginScaled + totalFees;
     const currentAllowance = await context.publicClient.readContract({
       address: context.deployments().usdc,
-      abi: erc20Abi3,
+      abi: import_viem5.erc20Abi,
       functionName: "allowance",
       args: [context.walletClient.account.address, context.deployments().perpManager],
       blockTag: "latest"
@@ -3535,14 +3745,16 @@ async function openTakerPosition(context, perpId, params) {
       account: context.walletClient.account
     });
     const txHash = await context.walletClient.writeContract(request);
-    const receipt = await context.publicClient.waitForTransactionReceipt({ hash: txHash });
+    const receipt = await context.publicClient.waitForTransactionReceipt({
+      hash: txHash
+    });
     if (receipt.status === "reverted") {
       throw new Error(`Transaction reverted. Hash: ${txHash}`);
     }
     let takerPosId = null;
     for (const log of receipt.logs) {
       try {
-        const decoded = decodeEventLog2({
+        const decoded = (0, import_viem5.decodeEventLog)({
           abi: PERP_MANAGER_ABI,
           data: log.data,
           topics: log.topics
@@ -3560,6 +3772,88 @@ async function openTakerPosition(context, perpId, params) {
     return new OpenPosition(context, perpId, takerPosId, params.isLong, false, txHash);
   }, "openTakerPosition");
 }
+function buildMakerContractParams(context, marginScaled, params, alignedTickLower, alignedTickUpper, maxAmt0In, maxAmt1In) {
+  return {
+    holder: context.walletClient.account.address,
+    margin: marginScaled,
+    liquidity: params.liquidity,
+    tickLower: alignedTickLower,
+    tickUpper: alignedTickUpper,
+    maxAmt0In,
+    maxAmt1In
+  };
+}
+function calculateAlignedTicks(priceLower, priceUpper, tickSpacing) {
+  const tickLower = priceToTick(priceLower, true);
+  const tickUpper = priceToTick(priceUpper, false);
+  const alignedTickLower = Math.floor(tickLower / tickSpacing) * tickSpacing;
+  const alignedTickUpper = Math.ceil(tickUpper / tickSpacing) * tickSpacing;
+  if (alignedTickLower < MIN_TICK) {
+    throw new Error(
+      `Lower tick ${alignedTickLower} is below MIN_TICK (${MIN_TICK}). Increase priceLower.`
+    );
+  }
+  if (alignedTickUpper > MAX_TICK) {
+    throw new Error(
+      `Upper tick ${alignedTickUpper} exceeds MAX_TICK (${MAX_TICK}). Decrease priceUpper.`
+    );
+  }
+  if (alignedTickLower === alignedTickUpper) {
+    throw new Error(
+      "Price range too narrow: lower and upper ticks are equal after alignment. Widen the range."
+    );
+  }
+  return { alignedTickLower, alignedTickUpper };
+}
+function alignMakerTicks(params, tickSpacing) {
+  return calculateAlignedTicks(params.priceLower, params.priceUpper, tickSpacing);
+}
+var DEFAULT_MAKER_SLIPPAGE_TOLERANCE = 0.01;
+var MAX_UINT128 = 2n ** 128n - 1n;
+async function quoteOpenMakerPosition(context, perpId, params) {
+  return withErrorHandling(async () => {
+    if (params.margin <= 0) {
+      throw new Error("Margin must be greater than 0");
+    }
+    if (params.priceLower >= params.priceUpper) {
+      throw new Error("priceLower must be less than priceUpper");
+    }
+    const marginScaled = scale6Decimals(params.margin);
+    const perpData = await context.getPerpData(perpId);
+    const { alignedTickLower, alignedTickUpper } = alignMakerTicks(params, perpData.tickSpacing);
+    const contractParams = buildMakerContractParams(
+      context,
+      marginScaled,
+      params,
+      alignedTickLower,
+      alignedTickUpper,
+      MAX_UINT128,
+      MAX_UINT128
+    );
+    const [unexpectedReason, perpDelta, usdDelta] = await context.publicClient.readContract({
+      address: context.deployments().perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "quoteOpenMakerPosition",
+      args: [perpId, contractParams]
+    });
+    if (unexpectedReason !== "0x") {
+      throw new Error(`Quote failed: ${unexpectedReason}`);
+    }
+    return { perpDelta, usdDelta };
+  }, "quoteOpenMakerPosition");
+}
+function applySlippage(delta, slippageTolerance, fallbackRef) {
+  const slippageBps = BigInt(Math.ceil(slippageTolerance * 1e4));
+  if (delta < 0n) {
+    const absDelta = -delta;
+    return absDelta + absDelta * slippageBps / 10000n;
+  }
+  if (fallbackRef !== void 0 && fallbackRef !== 0n) {
+    const absRef = fallbackRef < 0n ? -fallbackRef : fallbackRef;
+    return absRef * slippageBps / 10000n;
+  }
+  return 0n;
+}
 async function openMakerPosition(context, perpId, params) {
   return withErrorHandling(async () => {
     if (params.margin <= 0) {
@@ -3569,11 +3863,27 @@ async function openMakerPosition(context, perpId, params) {
       throw new Error("priceLower must be less than priceUpper");
     }
     const marginScaled = scale6Decimals(params.margin);
-    const maxAmt0InScaled = typeof params.maxAmt0In === "bigint" ? params.maxAmt0In : scale6Decimals(params.maxAmt0In);
-    const maxAmt1InScaled = typeof params.maxAmt1In === "bigint" ? params.maxAmt1In : scale6Decimals(params.maxAmt1In);
+    const perpData = await context.getPerpData(perpId);
+    const { alignedTickLower, alignedTickUpper } = alignMakerTicks(params, perpData.tickSpacing);
+    let maxAmt0In;
+    let maxAmt1In;
+    if (params.maxAmt0In === void 0 !== (params.maxAmt1In === void 0)) {
+      throw new Error(
+        "Both maxAmt0In and maxAmt1In must be provided together or neither. Omit both to use automatic quote-based slippage calculation."
+      );
+    }
+    if (params.maxAmt0In !== void 0 && params.maxAmt1In !== void 0) {
+      maxAmt0In = typeof params.maxAmt0In === "bigint" ? params.maxAmt0In : scale6Decimals(params.maxAmt0In);
+      maxAmt1In = typeof params.maxAmt1In === "bigint" ? params.maxAmt1In : scale6Decimals(params.maxAmt1In);
+    } else {
+      const quote = await quoteOpenMakerPosition(context, perpId, params);
+      const slippage = params.slippageTolerance ?? DEFAULT_MAKER_SLIPPAGE_TOLERANCE;
+      maxAmt0In = applySlippage(quote.perpDelta, slippage, quote.usdDelta);
+      maxAmt1In = applySlippage(quote.usdDelta, slippage, quote.perpDelta);
+    }
     const currentAllowance = await context.publicClient.readContract({
       address: context.deployments().usdc,
-      abi: erc20Abi3,
+      abi: import_viem5.erc20Abi,
       functionName: "allowance",
       args: [context.walletClient.account.address, context.deployments().perpManager],
       blockTag: "latest"
@@ -3581,21 +3891,15 @@ async function openMakerPosition(context, perpId, params) {
     if (currentAllowance < marginScaled) {
       await approveUsdc(context, marginScaled);
     }
-    const perpData = await context.getPerpData(perpId);
-    const tickLower = priceToTick(params.priceLower, true);
-    const tickUpper = priceToTick(params.priceUpper, false);
-    const tickSpacing = perpData.tickSpacing;
-    const alignedTickLower = Math.floor(tickLower / tickSpacing) * tickSpacing;
-    const alignedTickUpper = Math.ceil(tickUpper / tickSpacing) * tickSpacing;
-    const contractParams = {
-      holder: context.walletClient.account.address,
-      margin: marginScaled,
-      liquidity: params.liquidity,
-      tickLower: alignedTickLower,
-      tickUpper: alignedTickUpper,
-      maxAmt0In: maxAmt0InScaled,
-      maxAmt1In: maxAmt1InScaled
-    };
+    const contractParams = buildMakerContractParams(
+      context,
+      marginScaled,
+      params,
+      alignedTickLower,
+      alignedTickUpper,
+      maxAmt0In,
+      maxAmt1In
+    );
     const { request } = await context.publicClient.simulateContract({
       address: context.deployments().perpManager,
       abi: PERP_MANAGER_ABI,
@@ -3604,14 +3908,16 @@ async function openMakerPosition(context, perpId, params) {
       account: context.walletClient.account
     });
     const txHash = await context.walletClient.writeContract(request);
-    const receipt = await context.publicClient.waitForTransactionReceipt({ hash: txHash });
+    const receipt = await context.publicClient.waitForTransactionReceipt({
+      hash: txHash
+    });
     if (receipt.status === "reverted") {
       throw new Error(`Transaction reverted. Hash: ${txHash}`);
     }
     let makerPosId = null;
     for (const log of receipt.logs) {
       try {
-        const decoded = decodeEventLog2({
+        const decoded = (0, import_viem5.decodeEventLog)({
           abi: PERP_MANAGER_ABI,
           data: log.data,
           topics: log.topics
@@ -3629,9 +3935,109 @@ async function openMakerPosition(context, perpId, params) {
     return new OpenPosition(context, perpId, makerPosId, void 0, true, txHash);
   }, "openMakerPosition");
 }
+async function quoteTakerPosition(context, perpId, params) {
+  return withErrorHandling(async () => {
+    if (params.margin <= 0) {
+      throw new Error("Margin must be greater than 0");
+    }
+    if (params.leverage <= 0) {
+      throw new Error("Leverage must be greater than 0");
+    }
+    const marginScaled = scale6Decimals(params.margin);
+    const marginRatio = Math.floor(NUMBER_1E6 / params.leverage);
+    const result = await context.publicClient.simulateContract({
+      address: context.deployments().perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "quoteOpenTakerPosition",
+      args: [
+        perpId,
+        {
+          holder: params.holder,
+          isLong: params.isLong,
+          margin: marginScaled,
+          marginRatio,
+          unspecifiedAmountLimit: params.isLong ? 0n : (1n << 128n) - 1n
+        }
+      ],
+      account: params.holder
+    });
+    const [unexpectedReason, perpDelta, usdDelta] = result.result;
+    if (unexpectedReason && unexpectedReason !== "0x") {
+      let errorName = "Quote simulation failed";
+      try {
+        const decoded = (0, import_viem5.decodeErrorResult)({
+          abi: PERP_MANAGER_ABI,
+          data: unexpectedReason
+        });
+        errorName = decoded.errorName;
+      } catch {
+      }
+      throw new Error(errorName);
+    }
+    const absPerpDelta = perpDelta < 0n ? -perpDelta : perpDelta;
+    const absUsdDelta = usdDelta < 0n ? -usdDelta : usdDelta;
+    if (absPerpDelta === 0n) {
+      throw new Error("Zero position size");
+    }
+    const fillPrice = Number(absUsdDelta) / Number(absPerpDelta);
+    return { perpDelta, usdDelta, fillPrice };
+  }, "quoteTakerPosition");
+}
+async function adjustMargin(context, positionId, marginDelta) {
+  return withErrorHandling(async () => {
+    const deployments = context.deployments();
+    if (marginDelta > 0n) {
+      const currentAllowance = await context.publicClient.readContract({
+        address: deployments.usdc,
+        abi: import_viem5.erc20Abi,
+        functionName: "allowance",
+        args: [context.walletClient.account.address, deployments.perpManager],
+        blockTag: "latest"
+      });
+      if (currentAllowance < marginDelta) {
+        await approveUsdc(context, marginDelta);
+      }
+    }
+    const { request } = await context.publicClient.simulateContract({
+      address: deployments.perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "adjustMargin",
+      args: [{ posId: positionId, marginDelta }],
+      account: context.walletClient.account
+    });
+    const txHash = await context.walletClient.writeContract(request);
+    return { txHash };
+  }, `adjustMargin for position ${positionId}`);
+}
+async function adjustNotional(context, positionId, usdDelta, perpLimit) {
+  return withErrorHandling(async () => {
+    const deployments = context.deployments();
+    if (usdDelta > 0n) {
+      const currentAllowance = await context.publicClient.readContract({
+        address: deployments.usdc,
+        abi: import_viem5.erc20Abi,
+        functionName: "allowance",
+        args: [context.walletClient.account.address, deployments.perpManager],
+        blockTag: "latest"
+      });
+      if (currentAllowance < usdDelta) {
+        await approveUsdc(context, usdDelta);
+      }
+    }
+    const { request } = await context.publicClient.simulateContract({
+      address: deployments.perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "adjustNotional",
+      args: [{ posId: positionId, usdDelta, perpLimit }],
+      account: context.walletClient.account
+    });
+    const txHash = await context.walletClient.writeContract(request);
+    return { txHash };
+  }, `adjustNotional for position ${positionId}`);
+}
 
 // src/functions/position.ts
-import { decodeEventLog as decodeEventLog3, formatUnits as formatUnits3 } from "viem";
+var import_viem6 = require("viem");
 function getPositionPerpId(positionData) {
   return positionData.perpId;
 }
@@ -3659,6 +4065,131 @@ function getPositionEffectiveMargin(positionData) {
 function getPositionIsLiquidatable(positionData) {
   return positionData.liveDetails.isLiquidatable;
 }
+async function quoteClosePosition(context, positionId) {
+  return withErrorHandling(async () => {
+    const result = await context.publicClient.readContract({
+      address: context.deployments().perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "quoteClosePosition",
+      args: [positionId]
+    });
+    const [unexpectedReason, pnl, funding, netMargin, wasLiquidated] = result;
+    if (unexpectedReason && unexpectedReason !== "0x") {
+      let errorName = "Quote simulation failed";
+      try {
+        const decoded = (0, import_viem6.decodeErrorResult)({
+          abi: PERP_MANAGER_ABI,
+          data: unexpectedReason
+        });
+        errorName = decoded.errorName;
+      } catch {
+      }
+      throw new Error(errorName);
+    }
+    return {
+      pnl: Number((0, import_viem6.formatUnits)(pnl, 6)),
+      // Negate so positive = user receives funding, matching live details convention
+      funding: -Number((0, import_viem6.formatUnits)(funding, 6)),
+      netMargin: Number((0, import_viem6.formatUnits)(uint256ToInt256(netMargin), 6)),
+      wasLiquidated
+    };
+  }, `quoteClosePosition for position ${positionId}`);
+}
+async function closePositionWithQuote(context, _perpId, positionId, slippageTolerance = 0.01) {
+  return withErrorHandling(async () => {
+    const rawData = await context.getPositionRawData(positionId);
+    const isMaker = rawData.makerDetails !== null;
+    const result = await context.publicClient.readContract({
+      address: context.deployments().perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "quoteClosePosition",
+      args: [positionId]
+    });
+    const [unexpectedReason, quotePnl] = result;
+    if (unexpectedReason && unexpectedReason !== "0x") {
+      throw new Error("Quote failed \u2014 position may be invalid or already closed");
+    }
+    let contractParams = {
+      posId: positionId,
+      minAmt0Out: 0n,
+      minAmt1Out: 0n,
+      maxAmt1In: 0n
+    };
+    const canonicalPerpId = rawData.perpId;
+    if (!isMaker) {
+      const isLong = rawData.entryPerpDelta > 0n;
+      const slippageBps = BigInt(Math.ceil(slippageTolerance * 1e4));
+      const absEntryUsd = rawData.entryUsdDelta < 0n ? -rawData.entryUsdDelta : rawData.entryUsdDelta;
+      if (isLong) {
+        const swapRevenue = quotePnl + absEntryUsd;
+        const minOut = swapRevenue > 0n ? swapRevenue - swapRevenue * slippageBps / 10000n : 0n;
+        contractParams = {
+          posId: positionId,
+          minAmt0Out: 0n,
+          minAmt1Out: minOut,
+          maxAmt1In: 0n
+        };
+      } else {
+        const swapCost = absEntryUsd - quotePnl;
+        const maxIn = swapCost > 0n ? swapCost + swapCost * slippageBps / 10000n : 0n;
+        contractParams = {
+          posId: positionId,
+          minAmt0Out: 0n,
+          minAmt1Out: 0n,
+          maxAmt1In: maxIn
+        };
+      }
+    }
+    const { request } = await context.publicClient.simulateContract({
+      address: context.deployments().perpManager,
+      abi: PERP_MANAGER_ABI,
+      functionName: "closePosition",
+      args: [contractParams],
+      account: context.walletClient.account,
+      gas: 500000n
+    });
+    const txHash = await context.walletClient.writeContract(request);
+    const receipt = await context.publicClient.waitForTransactionReceipt({
+      hash: txHash
+    });
+    if (receipt.status === "reverted") {
+      throw new Error(`Transaction reverted. Hash: ${txHash}`);
+    }
+    let newPositionId = null;
+    for (const log of receipt.logs) {
+      try {
+        const decoded = (0, import_viem6.decodeEventLog)({
+          abi: PERP_MANAGER_ABI,
+          data: log.data,
+          topics: log.topics,
+          eventName: "PositionOpened"
+        });
+        const eventPerpId = decoded.args.perpId.toLowerCase();
+        const eventPosId = decoded.args.posId;
+        if (eventPerpId === canonicalPerpId.toLowerCase() && eventPosId !== positionId) {
+          newPositionId = eventPosId;
+          break;
+        }
+      } catch (_e) {
+      }
+    }
+    if (!newPositionId) {
+      return { position: null, txHash };
+    }
+    return {
+      position: {
+        perpId: canonicalPerpId,
+        positionId: newPositionId,
+        liveDetails: await getPositionLiveDetailsFromContract(
+          context,
+          canonicalPerpId,
+          newPositionId
+        )
+      },
+      txHash
+    };
+  }, `closePositionWithQuote for position ${positionId}`);
+}
 async function closePosition(context, perpId, positionId, params) {
   return withErrorHandling(async () => {
     const contractParams = {
@@ -3677,14 +4208,16 @@ async function closePosition(context, perpId, positionId, params) {
       // Provide explicit gas limit to avoid estimation issues
     });
     const txHash = await context.walletClient.writeContract(request);
-    const receipt = await context.publicClient.waitForTransactionReceipt({ hash: txHash });
+    const receipt = await context.publicClient.waitForTransactionReceipt({
+      hash: txHash
+    });
     if (receipt.status === "reverted") {
       throw new Error(`Transaction reverted. Hash: ${txHash}`);
     }
     let newPositionId = null;
     for (const log of receipt.logs) {
       try {
-        const decoded = decodeEventLog3({
+        const decoded = (0, import_viem6.decodeEventLog)({
           abi: PERP_MANAGER_ABI,
           data: log.data,
           topics: log.topics,
@@ -3727,9 +4260,10 @@ async function getPositionLiveDetailsFromContract(context, _perpId, positionId)
       );
     }
     return {
-      pnl: Number(formatUnits3(pnl, 6)),
-      fundingPayment: Number(formatUnits3(funding, 6)),
-      effectiveMargin: Number(formatUnits3(netMargin, 6)),
+      pnl: Number((0, import_viem6.formatUnits)(pnl, 6)),
+      // Negate so positive = user receives funding, matching quoteClosePosition convention
+      fundingPayment: -Number((0, import_viem6.formatUnits)(funding, 6)),
+      effectiveMargin: Number((0, import_viem6.formatUnits)(uint256ToInt256(netMargin), 6)),
       isLiquidatable: wasLiquidated
     };
   }, `getPositionLiveDetailsFromContract for position ${positionId}`);
@@ -3773,6 +4307,34 @@ function calculateLiquidationPrice(rawData, isLong) {
     return liqPrice;
   }
 }
+function calculatePnlPercentage(pnl, funding, margin) {
+  const totalPnl = pnl + funding;
+  const initialMargin = margin - totalPnl;
+  if (initialMargin <= 0) return 0;
+  return totalPnl / initialMargin * 100;
+}
+function calculateClosePositionParams(opts) {
+  if (opts.isMaker) {
+    return { minAmt0Out: 0, minAmt1Out: 0, maxAmt1In: 0 };
+  }
+  if (typeof opts.isLong !== "boolean") {
+    throw new Error("isLong must be explicitly set for taker positions");
+  }
+  const absNotional = Math.abs(opts.notional);
+  if (opts.isLong) {
+    return {
+      minAmt0Out: 0,
+      minAmt1Out: Math.max(0, absNotional * (1 - opts.slippagePercent / 100)),
+      maxAmt1In: 0
+    };
+  } else {
+    return {
+      minAmt0Out: 0,
+      minAmt1Out: 0,
+      maxAmt1In: absNotional * (1 + opts.slippagePercent / 100)
+    };
+  }
+}
 
 // src/functions/user.ts
 function getUserUsdcBalance(userData) {
@@ -3784,13 +4346,21 @@ function getUserOpenPositions(userData) {
 function getUserWalletAddress(userData) {
   return userData.walletAddress;
 }
-export {
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
   BEACON_ABI,
   BIGINT_1E6,
   ContractError,
+  DEFAULT_MAKER_SLIPPAGE_TOLERANCE,
   ErrorCategory,
   ErrorSource,
+  INT256_THRESHOLD,
   InsufficientFundsError,
+  MAX_PRICE,
+  MAX_TICK,
+  MAX_UINT128,
+  MIN_PRICE,
+  MIN_TICK,
   NUMBER_1E6,
   OpenPosition,
   PERP_MANAGER_ABI,
@@ -3799,17 +4369,31 @@ export {
   Q96,
   RPCError,
   TransactionRejectedError,
+  UINT256_MAX,
   ValidationError,
+  adjustMargin,
+  adjustNotional,
+  applySlippage,
   approveUsdc,
+  calculateAlignedTicks,
+  calculateClosePositionParams,
   calculateEntryPrice,
   calculateLeverage,
   calculateLiquidationPrice,
   calculateLiquidityForTargetRatio,
+  calculatePnlPercentage,
   calculatePositionSize,
   calculatePositionValue,
   closePosition,
+  closePositionWithQuote,
+  convertFundingDiffX96ToPercentPerPeriod,
+  convertFundingPerSecondX96ToPercentPerDay,
+  convertFundingPerSecondX96ToPercentPerMinute,
   createPerp,
   estimateLiquidity,
+  getFundingRate,
+  getIndexTWAP,
+  getIndexValue,
   getPerpBeacon,
   getPerpBounds,
   getPerpFees,
@@ -3826,6 +4410,7 @@ export {
   getPositionPerpId,
   getPositionPnl,
   getRpcUrl,
+  getUsdcAllowance,
   getUserOpenPositions,
   getUserUsdcBalance,
   getUserWalletAddress,
@@ -3835,12 +4420,16 @@ export {
   parseContractError,
   priceToSqrtPriceX96,
   priceToTick,
+  quoteClosePosition,
+  quoteOpenMakerPosition,
+  quoteTakerPosition,
   scale6Decimals,
   scaleFrom6Decimals,
   scaleFromX96,
   scaleToX96,
   sqrtPriceX96ToPrice,
   tickToPrice,
+  uint256ToInt256,
   withErrorHandling
-};
-//# sourceMappingURL=index.mjs.map
+});
+//# sourceMappingURL=index.cjs.map