@strkfarm/sdk 1.1.39 → 1.1.41

package/src/utils/math-utils.ts

@@ -0,0 +1,150 @@
+import { logger } from "@/utils";
+
+export async function binarySearch(
+  lowWei: bigint,
+  highWei: bigint,
+  callback: (mid: bigint) => Promise<'go_low' | 'go_high' | 'retry' | 'found'>
+): Promise<bigint | null> {
+  while (lowWei <= highWei) {
+    const diff = highWei - lowWei;
+    const mid = lowWei + (diff / 2n);
+    const result = await callback(mid);
+
+    if (result === 'found') {
+      return mid;
+    } else if (result == 'retry') {
+      // do nothing. 
+    } else if (result === 'go_low') {
+      highWei = mid - BigInt(1);
+    } else {
+      lowWei = mid + BigInt(1);
+    }
+  }
+
+  return null; // not found
+}
+
+interface SwapResult {
+  optimalInput: number;
+  actualOutput: number;
+  actualSlippage: number;
+  apiCallsUsed: number;
+}
+
+interface FindMaxInputOptions {
+  /** Function that calls your API: input amount -> output amount */
+  apiGetOutput: (inputAmount: number) => Promise<number>;
+  /** Maximum input amount you're willing to swap */
+  maxInput: number;
+  /** Maximum acceptable slippage in percent (e.g., 1.0 for 1%) */
+  maxSlippagePercent: number;
+  /** Convergence tolerance as fraction of maxInput */
+  tolerance: number;
+  /** Minimum input amount (default: 0) */
+  minInput?: number;
+  /** Reference amount multiplier for price calculation (default: 0.001) */
+  referenceAmountMultiplier?: number;
+  /** Reference rate for price calculation */
+  referenceRate?: number;
+}
+
+/**
+ * Find maximum input amount within slippage constraints using binary search
+ * 
+ * @returns Promise with optimal input, output, slippage, and API calls used
+ */
+export async function findMaxInputWithSlippage(
+  options: FindMaxInputOptions
+): Promise<SwapResult> {
+  const {
+    apiGetOutput,
+    maxInput,
+    maxSlippagePercent,
+    tolerance,
+    minInput = 0,
+    referenceAmountMultiplier = 0.001,
+    referenceRate = 0,
+  } = options;
+
+  let apiCalls = 0;
+
+  // one of referenceRate or referenceAmountMultiplier must be provided
+  if (!referenceRate && !referenceAmountMultiplier) {
+    throw new Error('One of referenceRate or referenceAmountMultiplier must be provided');
+  }
+  
+  let _referenceRate = referenceRate;
+  if (!_referenceRate) {
+    // Get reference rate at minimal amount for price calculation
+    const smallAmount = maxInput * referenceAmountMultiplier;
+    const referenceOutput = await apiGetOutput(smallAmount);
+    apiCalls++;
+    _referenceRate = referenceOutput / smallAmount;
+  }
+
+  /**
+   * Check if slippage is acceptable for given input amount
+   * Returns { acceptable: boolean, slippage: number, output: number }
+   */
+  async function checkSlippage(inputAmount: number) {
+    const actualOutput = await apiGetOutput(inputAmount);
+    apiCalls++;
+    
+    const expectedOutput = inputAmount * referenceRate;
+    const slippage = ((expectedOutput - actualOutput) / expectedOutput);
+    logger.verbose(`findMaxInputWithSlippage::checkSlippage inputAmount: ${inputAmount}, actualOutput: ${actualOutput}, slippage: ${slippage}, maxSlippagePercent: ${maxSlippagePercent}`);
+    
+    return {
+      acceptable: slippage <= maxSlippagePercent,
+      slippage,
+      output: actualOutput,
+    };
+  }
+
+  // Start from the top - try maxInput first
+  const maxCheck = await checkSlippage(maxInput);
+  if (maxCheck.acceptable) {
+    // Best case: maxInput is within slippage, return immediately
+    return {
+      optimalInput: maxInput,
+      actualOutput: maxCheck.output,
+      actualSlippage: maxCheck.slippage,
+      apiCallsUsed: apiCalls,
+    };
+  }
+
+  // Binary search between minInput and maxInput
+  let left = minInput;
+  let right = maxInput;
+  let bestInput = minInput;
+  let bestOutput = 0;
+  let bestSlippage = 0;
+
+  const convergenceThreshold = tolerance * maxInput;
+
+  while (right - left > convergenceThreshold) {
+    const mid = (left + right) / 2;
+    const midCheck = await checkSlippage(mid);
+
+    if (midCheck.acceptable) {
+      // Good slippage at mid, save it and try higher
+      bestInput = mid;
+      bestOutput = midCheck.output;
+      bestSlippage = midCheck.slippage;
+      left = mid; // Search in upper half [mid, right]
+    } else {
+      // Bad slippage at mid, try lower
+      right = mid; // Search in lower half [left, mid]
+    }
+  }
+
+  return {
+    optimalInput: bestInput,
+    actualOutput: bestOutput,
+    actualSlippage: bestSlippage,
+    apiCallsUsed: apiCalls,
+  };
+}
+
+
+