@strobelabs/perpcity-sdk 0.5.0 → 0.5.1

package/dist/index.d.mts

@@ -1825,8 +1825,13 @@ type OpenMakerPositionParams = {
     priceLower: number;
     priceUpper: number;
     liquidity: bigint;
-    maxAmt0In: number | bigint;
-    maxAmt1In: number | bigint;
+    slippageTolerance?: number;
+    maxAmt0In?: number | bigint;
+    maxAmt1In?: number | bigint;
+};
+type QuoteOpenMakerPositionResult = {
+    perpDelta: bigint;
+    usdDelta: bigint;
 };
 type CreatePerpParams = {
     beacon: Address;
@@ -6374,6 +6379,11 @@ declare function getPerpTickSpacing(perpData: PerpData): number;
 
 declare function createPerp(context: PerpCityContext, params: CreatePerpParams): Promise<Hex>;
 declare function openTakerPosition(context: PerpCityContext, perpId: Hex, params: OpenTakerPositionParams): Promise<OpenPosition>;
+declare function calculateAlignedTicks(priceLower: number, priceUpper: number, tickSpacing: number): {
+    alignedTickLower: number;
+    alignedTickUpper: number;
+};
+declare function quoteOpenMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<QuoteOpenMakerPositionResult>;
 declare function openMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<OpenPosition>;
 
 declare function getPositionPerpId(positionData: OpenPositionData): Hex;
@@ -6437,6 +6447,10 @@ declare function approveUsdc(context: PerpCityContext, amount: bigint, confirmat
 declare const NUMBER_1E6: number;
 declare const BIGINT_1E6: bigint;
 declare const Q96: bigint;
+declare const MIN_TICK = -887272;
+declare const MAX_TICK = 887272;
+declare const MIN_PRICE = 0.000001;
+declare const MAX_PRICE = 1000000;
 
 declare function priceToSqrtPriceX96(price: number): bigint;
 /**
@@ -6591,4 +6605,4 @@ interface RpcConfig {
  */
 declare function getRpcUrl(config?: RpcConfig): string;
 
-export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, InsufficientFundsError, type LiveDetails, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, RPCError, type RpcConfig, TransactionRejectedError, type UserData, ValidationError, approveUsdc, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePositionSize, calculatePositionValue, closePosition, createPerp, estimateLiquidity, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, withErrorHandling };
+export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, InsufficientFundsError, type LiveDetails, MAX_PRICE, MAX_TICK, MIN_PRICE, MIN_TICK, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, type QuoteOpenMakerPositionResult, RPCError, type RpcConfig, TransactionRejectedError, type UserData, ValidationError, approveUsdc, calculateAlignedTicks, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePositionSize, calculatePositionValue, closePosition, createPerp, estimateLiquidity, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, quoteOpenMakerPosition, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, withErrorHandling };

package/dist/index.d.ts

@@ -1825,8 +1825,13 @@ type OpenMakerPositionParams = {
     priceLower: number;
     priceUpper: number;
     liquidity: bigint;
-    maxAmt0In: number | bigint;
-    maxAmt1In: number | bigint;
+    slippageTolerance?: number;
+    maxAmt0In?: number | bigint;
+    maxAmt1In?: number | bigint;
+};
+type QuoteOpenMakerPositionResult = {
+    perpDelta: bigint;
+    usdDelta: bigint;
 };
 type CreatePerpParams = {
     beacon: Address;
@@ -6374,6 +6379,11 @@ declare function getPerpTickSpacing(perpData: PerpData): number;
 
 declare function createPerp(context: PerpCityContext, params: CreatePerpParams): Promise<Hex>;
 declare function openTakerPosition(context: PerpCityContext, perpId: Hex, params: OpenTakerPositionParams): Promise<OpenPosition>;
+declare function calculateAlignedTicks(priceLower: number, priceUpper: number, tickSpacing: number): {
+    alignedTickLower: number;
+    alignedTickUpper: number;
+};
+declare function quoteOpenMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<QuoteOpenMakerPositionResult>;
 declare function openMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<OpenPosition>;
 
 declare function getPositionPerpId(positionData: OpenPositionData): Hex;
@@ -6437,6 +6447,10 @@ declare function approveUsdc(context: PerpCityContext, amount: bigint, confirmat
 declare const NUMBER_1E6: number;
 declare const BIGINT_1E6: bigint;
 declare const Q96: bigint;
+declare const MIN_TICK = -887272;
+declare const MAX_TICK = 887272;
+declare const MIN_PRICE = 0.000001;
+declare const MAX_PRICE = 1000000;
 
 declare function priceToSqrtPriceX96(price: number): bigint;
 /**
@@ -6591,4 +6605,4 @@ interface RpcConfig {
  */
 declare function getRpcUrl(config?: RpcConfig): string;
 
-export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, InsufficientFundsError, type LiveDetails, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, RPCError, type RpcConfig, TransactionRejectedError, type UserData, ValidationError, approveUsdc, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePositionSize, calculatePositionValue, closePosition, createPerp, estimateLiquidity, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, withErrorHandling };
+export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, InsufficientFundsError, type LiveDetails, MAX_PRICE, MAX_TICK, MIN_PRICE, MIN_TICK, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, type QuoteOpenMakerPositionResult, RPCError, type RpcConfig, TransactionRejectedError, type UserData, ValidationError, approveUsdc, calculateAlignedTicks, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePositionSize, calculatePositionValue, closePosition, createPerp, estimateLiquidity, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, quoteOpenMakerPosition, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, withErrorHandling };

package/dist/index.js

@@ -36,6 +36,10 @@ __export(index_exports, {
   ErrorCategory: () => ErrorCategory,
   ErrorSource: () => ErrorSource,
   InsufficientFundsError: () => InsufficientFundsError,
+  MAX_PRICE: () => MAX_PRICE,
+  MAX_TICK: () => MAX_TICK,
+  MIN_PRICE: () => MIN_PRICE,
+  MIN_TICK: () => MIN_TICK,
   NUMBER_1E6: () => NUMBER_1E6,
   OpenPosition: () => OpenPosition,
   PERP_MANAGER_ABI: () => PERP_MANAGER_ABI,
@@ -46,6 +50,7 @@ __export(index_exports, {
   TransactionRejectedError: () => TransactionRejectedError,
   ValidationError: () => ValidationError,
   approveUsdc: () => approveUsdc,
+  calculateAlignedTicks: () => calculateAlignedTicks,
   calculateEntryPrice: () => calculateEntryPrice,
   calculateLeverage: () => calculateLeverage,
   calculateLiquidationPrice: () => calculateLiquidationPrice,
@@ -80,6 +85,7 @@ __export(index_exports, {
   parseContractError: () => parseContractError,
   priceToSqrtPriceX96: () => priceToSqrtPriceX96,
   priceToTick: () => priceToTick,
+  quoteOpenMakerPosition: () => quoteOpenMakerPosition,
   scale6Decimals: () => scale6Decimals,
   scaleFrom6Decimals: () => scaleFrom6Decimals,
   scaleFromX96: () => scaleFromX96,
@@ -2462,6 +2468,10 @@ 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;
 
 // src/utils/conversions.ts
 function priceToSqrtPriceX96(price) {
@@ -2494,6 +2504,11 @@ 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);
 }
@@ -3555,7 +3570,9 @@ 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}`);
     }
@@ -3622,7 +3639,9 @@ 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}`);
     }
@@ -3647,6 +3666,82 @@ 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) {
+  if (delta >= 0n) return 0n;
+  const absDelta = -delta;
+  const slippageBps = BigInt(Math.ceil(slippageTolerance * 1e4));
+  return absDelta + absDelta * slippageBps / 10000n;
+}
 async function openMakerPosition(context, perpId, params) {
   return withErrorHandling(async () => {
     if (params.margin <= 0) {
@@ -3656,8 +3751,24 @@ 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);
+      maxAmt1In = applySlippage(quote.usdDelta, slippage);
+    }
     const currentAllowance = await context.publicClient.readContract({
       address: context.deployments().usdc,
       abi: import_viem5.erc20Abi,
@@ -3668,21 +3779,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,
@@ -3691,7 +3796,9 @@ 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}`);
     }
@@ -3879,6 +3986,10 @@ function getUserWalletAddress(userData) {
   ErrorCategory,
   ErrorSource,
   InsufficientFundsError,
+  MAX_PRICE,
+  MAX_TICK,
+  MIN_PRICE,
+  MIN_TICK,
   NUMBER_1E6,
   OpenPosition,
   PERP_MANAGER_ABI,
@@ -3889,6 +4000,7 @@ function getUserWalletAddress(userData) {
   TransactionRejectedError,
   ValidationError,
   approveUsdc,
+  calculateAlignedTicks,
   calculateEntryPrice,
   calculateLeverage,
   calculateLiquidationPrice,
@@ -3923,6 +4035,7 @@ function getUserWalletAddress(userData) {
   parseContractError,
   priceToSqrtPriceX96,
   priceToTick,
+  quoteOpenMakerPosition,
   scale6Decimals,
   scaleFrom6Decimals,
   scaleFromX96,