@flashnet/sdk 0.4.4 → 0.5.0

package/dist/esm/src/utils/tick-math.js

@@ -0,0 +1,287 @@
+/**
+ * V3 Concentrated Liquidity Tick Math Utilities
+ *
+ * In V3 AMMs, price is represented as ticks where: price = 1.0001^tick
+ * Each tick represents a 0.01% (1 basis point) price change.
+ *
+ * Pool price convention: "amount of asset B per 1 unit of asset A" (in smallest units)
+ * For a USDB/BTC pool (A=USDB, B=BTC): price = sats per microUSDB
+ */
+// Constants
+const LOG_BASE = Math.log(1.0001);
+const MIN_TICK = -887272;
+const MAX_TICK = 887272;
+/**
+ * Convert a raw pool price to a tick.
+ *
+ * @param price - Pool price (amount of asset B per unit of asset A in smallest units)
+ * @returns The tick value
+ *
+ * @example
+ * // For USDB/BTC pool at ~$90k: price = 0.00111 sats per microUSDB
+ * priceToTick(0.00111) // returns approximately -68038
+ */
+function priceToTick(price) {
+    const priceNum = typeof price === "string" ? parseFloat(price) : price;
+    if (priceNum <= 0) {
+        throw new Error("Price must be positive");
+    }
+    const tick = Math.log(priceNum) / LOG_BASE;
+    return Math.round(tick);
+}
+/**
+ * Convert a tick to a raw pool price.
+ *
+ * @param tick - The tick value
+ * @returns Pool price as a string (for precision)
+ *
+ * @example
+ * tickToPrice(-68038) // returns "0.001109..." (sats per microUSDB)
+ */
+function tickToPrice(tick) {
+    if (tick < MIN_TICK || tick > MAX_TICK) {
+        throw new Error(`Tick must be between ${MIN_TICK} and ${MAX_TICK}`);
+    }
+    const price = 1.0001 ** tick;
+    return price.toString();
+}
+/**
+ * Round a tick down to the nearest valid tick (multiple of tick spacing).
+ *
+ * @param tick - The tick to round
+ * @param tickSpacing - The pool's tick spacing (e.g., 60)
+ * @returns Rounded tick
+ */
+function roundTickDown(tick, tickSpacing) {
+    return Math.floor(tick / tickSpacing) * tickSpacing;
+}
+/**
+ * Round a tick up to the nearest valid tick (multiple of tick spacing).
+ *
+ * @param tick - The tick to round
+ * @param tickSpacing - The pool's tick spacing (e.g., 60)
+ * @returns Rounded tick
+ */
+function roundTickUp(tick, tickSpacing) {
+    return Math.ceil(tick / tickSpacing) * tickSpacing;
+}
+/**
+ * Round a tick to the nearest valid tick (multiple of tick spacing).
+ *
+ * @param tick - The tick to round
+ * @param tickSpacing - The pool's tick spacing (e.g., 60)
+ * @returns Rounded tick
+ */
+function roundTick(tick, tickSpacing) {
+    return Math.round(tick / tickSpacing) * tickSpacing;
+}
+/**
+ * Convert a human-readable price to a V3 tick.
+ *
+ * This is the most user-friendly function for calculating ticks.
+ * Express your price as "quote per base" (e.g., "$90,000 per BTC").
+ *
+ * @example
+ * // BTC at $90,000, pool has USDB (6 decimals) as A, BTC (8 decimals) as B
+ * humanPriceToTick({
+ *   humanPrice: 90000,
+ *   baseDecimals: 8,      // BTC
+ *   quoteDecimals: 6,     // USD
+ *   baseIsAssetA: false,  // BTC is asset B (default)
+ *   tickSpacing: 60
+ * }) // returns -68040
+ *
+ * @example
+ * // Get tick range for $80,000 to $100,000
+ * const tickLower = humanPriceToTick({ humanPrice: 100000, baseDecimals: 8, quoteDecimals: 6, tickSpacing: 60 });
+ * const tickUpper = humanPriceToTick({ humanPrice: 80000, baseDecimals: 8, quoteDecimals: 6, tickSpacing: 60 });
+ * // Note: higher price = lower tick for this pool configuration
+ */
+function humanPriceToTick(options) {
+    const { humanPrice, baseDecimals, quoteDecimals, baseIsAssetA = false, tickSpacing, } = options;
+    if (humanPrice <= 0) {
+        throw new Error("Human price must be positive");
+    }
+    // Pool price is "amount of B per unit of A" in smallest units
+    // Human price is "quote per base"
+    // If base is asset B (common case: BTC/USD pool where BTC is B):
+    //   pool_price = 10^(baseDecimals - quoteDecimals) / humanPrice
+    // If base is asset A:
+    //   pool_price = humanPrice * 10^(quoteDecimals - baseDecimals)
+    let poolPrice;
+    if (baseIsAssetA) {
+        // Base is A, so human price is "B per A" which is the same direction as pool price
+        poolPrice = humanPrice * 10 ** (quoteDecimals - baseDecimals);
+    }
+    else {
+        // Base is B, so human price is "A per B", need to invert
+        poolPrice = 10 ** (baseDecimals - quoteDecimals) / humanPrice;
+    }
+    let tick = priceToTick(poolPrice);
+    if (tickSpacing) {
+        tick = roundTick(tick, tickSpacing);
+    }
+    return tick;
+}
+/**
+ * Convert a V3 tick to a human-readable price.
+ *
+ * @example
+ * // Tick -68040 in a USDB/BTC pool
+ * tickToHumanPrice({
+ *   tick: -68040,
+ *   baseDecimals: 8,      // BTC
+ *   quoteDecimals: 6,     // USD
+ *   baseIsAssetA: false   // BTC is asset B
+ * }) // returns approximately 90000 (dollars per BTC)
+ */
+function tickToHumanPrice(options) {
+    const { tick, baseDecimals, quoteDecimals, baseIsAssetA = false } = options;
+    const poolPrice = parseFloat(tickToPrice(tick));
+    // Reverse the conversion from humanPriceToTick
+    if (baseIsAssetA) {
+        return poolPrice / 10 ** (quoteDecimals - baseDecimals);
+    }
+    else {
+        return 10 ** (baseDecimals - quoteDecimals) / poolPrice;
+    }
+}
+/**
+ * Get a tick range from human-readable price bounds.
+ *
+ * Automatically handles the conversion and ensures tickLower < tickUpper.
+ *
+ * @example
+ * // Get tick range for $80,000 to $100,000 BTC price
+ * const range = tickRangeFromPrices({
+ *   priceLower: 80000,
+ *   priceUpper: 100000,
+ *   baseDecimals: 8,
+ *   quoteDecimals: 6,
+ *   tickSpacing: 60
+ * });
+ * // returns { tickLower: -69120, tickUpper: -66840, actualPriceLower: 80180, actualPriceUpper: 99820 }
+ */
+function tickRangeFromPrices(options) {
+    const { priceLower, priceUpper, baseDecimals, quoteDecimals, baseIsAssetA = false, tickSpacing, } = options;
+    if (priceLower >= priceUpper) {
+        throw new Error("priceLower must be less than priceUpper");
+    }
+    const tick1 = humanPriceToTick({
+        humanPrice: priceLower,
+        baseDecimals,
+        quoteDecimals,
+        baseIsAssetA,
+        tickSpacing,
+    });
+    const tick2 = humanPriceToTick({
+        humanPrice: priceUpper,
+        baseDecimals,
+        quoteDecimals,
+        baseIsAssetA,
+        tickSpacing,
+    });
+    // Ensure tickLower < tickUpper (tick direction depends on baseIsAssetA)
+    const tickLower = Math.min(tick1, tick2);
+    const tickUpper = Math.max(tick1, tick2);
+    // Calculate actual prices at the rounded ticks
+    const actualPriceLower = tickToHumanPrice({
+        tick: baseIsAssetA ? tickLower : tickUpper,
+        baseDecimals,
+        quoteDecimals,
+        baseIsAssetA,
+    });
+    const actualPriceUpper = tickToHumanPrice({
+        tick: baseIsAssetA ? tickUpper : tickLower,
+        baseDecimals,
+        quoteDecimals,
+        baseIsAssetA,
+    });
+    return {
+        tickLower,
+        tickUpper,
+        actualPriceLower,
+        actualPriceUpper,
+    };
+}
+//
+// Pool Price Calculation from Amount
+//
+/**
+ * Calculate the pool price needed for a given position configuration.
+ *
+ * @param humanPrice - Human-readable price (e.g., 90000 for $90k/BTC)
+ * @param baseDecimals - Decimals of base token
+ * @param quoteDecimals - Decimals of quote token
+ * @param baseIsAssetA - Whether base is asset A (default: false)
+ * @returns Pool price string suitable for createConcentratedPool's initialPrice
+ */
+function humanPriceToPoolPrice(humanPrice, baseDecimals, quoteDecimals, baseIsAssetA = false) {
+    if (humanPrice <= 0) {
+        throw new Error("Human price must be positive");
+    }
+    let poolPrice;
+    if (baseIsAssetA) {
+        poolPrice = humanPrice * 10 ** (quoteDecimals - baseDecimals);
+    }
+    else {
+        poolPrice = 10 ** (baseDecimals - quoteDecimals) / humanPrice;
+    }
+    return poolPrice.toPrecision(10);
+}
+/**
+ * Convert pool price to human-readable price.
+ *
+ * @param poolPrice - Pool price (amount of B per unit of A in smallest units)
+ * @param baseDecimals - Decimals of base token
+ * @param quoteDecimals - Decimals of quote token
+ * @param baseIsAssetA - Whether base is asset A (default: false)
+ * @returns Human-readable price
+ */
+function poolPriceToHumanPrice(poolPrice, baseDecimals, quoteDecimals, baseIsAssetA = false) {
+    const price = typeof poolPrice === "string" ? parseFloat(poolPrice) : poolPrice;
+    if (baseIsAssetA) {
+        return price / 10 ** (quoteDecimals - baseDecimals);
+    }
+    else {
+        return 10 ** (baseDecimals - quoteDecimals) / price;
+    }
+}
+//
+// Convenience exports
+//
+/**
+ * V3 tick math utilities namespace for cleaner imports.
+ *
+ * @example
+ * import { V3TickMath } from "@flashnet/sdk";
+ *
+ * const tick = V3TickMath.fromHumanPrice({
+ *   humanPrice: 90000,
+ *   baseDecimals: 8,
+ *   quoteDecimals: 6,
+ *   tickSpacing: 60
+ * });
+ */
+const V3TickMath = {
+    // Core conversions
+    priceToTick,
+    tickToPrice,
+    // Tick spacing
+    roundTickDown,
+    roundTickUp,
+    roundTick,
+    // Human-readable conversions
+    fromHumanPrice: humanPriceToTick,
+    toHumanPrice: tickToHumanPrice,
+    rangeFromPrices: tickRangeFromPrices,
+    // Pool price conversions
+    humanPriceToPoolPrice,
+    poolPriceToHumanPrice,
+    // Constants
+    MIN_TICK,
+    MAX_TICK,
+};
+
+export { V3TickMath, humanPriceToPoolPrice, humanPriceToTick, poolPriceToHumanPrice, priceToTick, roundTick, roundTickDown, roundTickUp, tickRangeFromPrices, tickToHumanPrice, tickToPrice };
+//# sourceMappingURL=tick-math.js.map

package/dist/esm/src/utils/tick-math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-math.js","sources":["../../../../../../src/utils/tick-math.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;AAQG;AAEH;AACA,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;AACjC,MAAM,QAAQ,GAAG,OAAO;AACxB,MAAM,QAAQ,GAAG,MAAM;AAEvB;;;;;;;;;AASG;AACG,SAAU,WAAW,CAAC,KAAsB,EAAA;AAChD,IAAA,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,KAAK;AAEtE,IAAA,IAAI,QAAQ,IAAI,CAAC,EAAE;AACjB,QAAA,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC;IAC3C;IAEA,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,QAAQ;AAC1C,IAAA,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;AACzB;AAEA;;;;;;;;AAQG;AACG,SAAU,WAAW,CAAC,IAAY,EAAA;IACtC,IAAI,IAAI,GAAG,QAAQ,IAAI,IAAI,GAAG,QAAQ,EAAE;QACtC,MAAM,IAAI,KAAK,CAAC,CAAA,qBAAA,EAAwB,QAAQ,CAAA,KAAA,EAAQ,QAAQ,CAAA,CAAE,CAAC;IACrE;AAEA,IAAA,MAAM,KAAK,GAAG,MAAM,IAAI,IAAI;AAC5B,IAAA,OAAO,KAAK,CAAC,QAAQ,EAAE;AACzB;AAEA;;;;;;AAMG;AACG,SAAU,aAAa,CAAC,IAAY,EAAE,WAAmB,EAAA;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,WAAW,CAAC,GAAG,WAAW;AACrD;AAEA;;;;;;AAMG;AACG,SAAU,WAAW,CAAC,IAAY,EAAE,WAAmB,EAAA;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,GAAG,WAAW;AACpD;AAEA;;;;;;AAMG;AACG,SAAU,SAAS,CAAC,IAAY,EAAE,WAAmB,EAAA;IACzD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,WAAW,CAAC,GAAG,WAAW;AACrD;AAsCA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAU,gBAAgB,CAAC,OAAgC,EAAA;AAC/D,IAAA,MAAM,EACJ,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,GAAG,KAAK,EACpB,WAAW,GACZ,GAAG,OAAO;AAEX,IAAA,IAAI,UAAU,IAAI,CAAC,EAAE;AACnB,QAAA,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC;IACjD;;;;;;;AAUA,IAAA,IAAI,SAAiB;IACrB,IAAI,YAAY,EAAE;;QAEhB,SAAS,GAAG,UAAU,GAAG,EAAE,KAAK,aAAa,GAAG,YAAY,CAAC;IAC/D;SAAO;;QAEL,SAAS,GAAG,EAAE,KAAK,YAAY,GAAG,aAAa,CAAC,GAAG,UAAU;IAC/D;AAEA,IAAA,IAAI,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC;IAEjC,IAAI,WAAW,EAAE;AACf,QAAA,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC;IACrC;AAEA,IAAA,OAAO,IAAI;AACb;AA0BA;;;;;;;;;;;AAWG;AACG,SAAU,gBAAgB,CAAC,OAAgC,EAAA;AAC/D,IAAA,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,GAAG,KAAK,EAAE,GAAG,OAAO;IAE3E,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;;IAG/C,IAAI,YAAY,EAAE;QAChB,OAAO,SAAS,GAAG,EAAE,KAAK,aAAa,GAAG,YAAY,CAAC;IACzD;SAAO;QACL,OAAO,EAAE,KAAK,YAAY,GAAG,aAAa,CAAC,GAAG,SAAS;IACzD;AACF;AAmDA;;;;;;;;;;;;;;;AAeG;AACG,SAAU,mBAAmB,CACjC,OAAmC,EAAA;AAEnC,IAAA,MAAM,EACJ,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,GAAG,KAAK,EACpB,WAAW,GACZ,GAAG,OAAO;AAEX,IAAA,IAAI,UAAU,IAAI,UAAU,EAAE;AAC5B,QAAA,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC;IAC5D;IAEA,MAAM,KAAK,GAAG,gBAAgB,CAAC;AAC7B,QAAA,UAAU,EAAE,UAAU;QACtB,YAAY;QACZ,aAAa;QACb,YAAY;QACZ,WAAW;AACZ,KAAA,CAAC;IAEF,MAAM,KAAK,GAAG,gBAAgB,CAAC;AAC7B,QAAA,UAAU,EAAE,UAAU;QACtB,YAAY;QACZ,aAAa;QACb,YAAY;QACZ,WAAW;AACZ,KAAA,CAAC;;IAGF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;;IAGxC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;QACxC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS;QAC1C,YAAY;QACZ,aAAa;QACb,YAAY;AACb,KAAA,CAAC;IAEF,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;QACxC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS;QAC1C,YAAY;QACZ,aAAa;QACb,YAAY;AACb,KAAA,CAAC;IAEF,OAAO;QACL,SAAS;QACT,SAAS;QACT,gBAAgB;QAChB,gBAAgB;KACjB;AACH;AAEA;AACA;AACA;AAEA;;;;;;;;AAQG;AACG,SAAU,qBAAqB,CACnC,UAAkB,EAClB,YAAoB,EACpB,aAAqB,EACrB,YAAY,GAAG,KAAK,EAAA;AAEpB,IAAA,IAAI,UAAU,IAAI,CAAC,EAAE;AACnB,QAAA,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC;IACjD;AAEA,IAAA,IAAI,SAAiB;IACrB,IAAI,YAAY,EAAE;QAChB,SAAS,GAAG,UAAU,GAAG,EAAE,KAAK,aAAa,GAAG,YAAY,CAAC;IAC/D;SAAO;QACL,SAAS,GAAG,EAAE,KAAK,YAAY,GAAG,aAAa,CAAC,GAAG,UAAU;IAC/D;AAEA,IAAA,OAAO,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;AAClC;AAEA;;;;;;;;AAQG;AACG,SAAU,qBAAqB,CACnC,SAA0B,EAC1B,YAAoB,EACpB,aAAqB,EACrB,YAAY,GAAG,KAAK,EAAA;AAEpB,IAAA,MAAM,KAAK,GACT,OAAO,SAAS,KAAK,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,SAAS;IAEnE,IAAI,YAAY,EAAE;QAChB,OAAO,KAAK,GAAG,EAAE,KAAK,aAAa,GAAG,YAAY,CAAC;IACrD;SAAO;QACL,OAAO,EAAE,KAAK,YAAY,GAAG,aAAa,CAAC,GAAG,KAAK;IACrD;AACF;AAEA;AACA;AACA;AAEA;;;;;;;;;;;;AAYG;AACI,MAAM,UAAU,GAAG;;IAExB,WAAW;IACX,WAAW;;IAGX,aAAa;IACb,WAAW;IACX,SAAS;;AAGT,IAAA,cAAc,EAAE,gBAAgB;AAChC,IAAA,YAAY,EAAE,gBAAgB;AAC9B,IAAA,eAAe,EAAE,mBAAmB;;IAGpC,qBAAqB;IACrB,qBAAqB;;IAGrB,QAAQ;IACR,QAAQ;;;;;"}

package/dist/esm/src/utils/tokenAddress.js

@@ -60,7 +60,7 @@ function decodeSparkHumanReadableTokenIdentifier(humanReadableTokenIdentifier, n
         throw new Error("Failed to decode Spark human readable token identifier");
     }
 }
-// ===== BACKWARD COMPATIBILITY LAYER =====
+// BACKWARD COMPATIBILITY LAYER
 /**
  * @deprecated Use SparkHumanReadableTokenIdentifierNetworkPrefix instead
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flashnet/sdk",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
@@ -54,6 +54,9 @@
     "test:cjs": "node tests/test-cjs.cjs",
     "test:bun": "bun tests/test-bun.js",
     "test:modular": "node tests/test-modular.mjs",
+    "test:e2e": "npx tsx tests/e2e.ts",
+    "test:e2e:v3": "npx tsx tests/e2e-concentrated-liquidity-sdk.ts",
+    "test:e2e:all": "npm run test:e2e && npm run test:e2e:v3",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
@@ -62,8 +65,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.0.5",
-    "@buildonspark/issuer-sdk": "^0.1.0",
-    "@buildonspark/spark-sdk": "^0.5.0",
+    "@buildonspark/issuer-sdk": "^0.1.4",
+    "@buildonspark/spark-sdk": "^0.5.4",
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/bun": "latest",
     "@types/jest": "^30.0.0",