@pancakeswap/swap-sdk-core 1.6.0 → 1.6.1

package/dist/index.d.ts

@@ -363,4 +363,101 @@ declare function getCurrencyAddress(currency: Currency): `0x${string}`;
 declare function getUnifiedCurrencyAddress(currency: UnifiedCurrency): string;
 declare function getMatchedCurrency(currency: Currency, list: Currency[], matchWrappedCurrency?: boolean): Currency | undefined;
 
-export { BaseCurrency, BigintIsh, Currency, CurrencyAmount, FIVE, Fraction, InsufficientInputAmountError, InsufficientReservesError, MINIMUM_LIQUIDITY, MaxUint256, NativeCurrency, ONE, Percent, Price, Rounding, SPLNativeCurrency, SPLToken, SerializedSPLToken, SerializedToken, TEN, THREE, TWO, Token, TradeType, UnifiedCurrency, UnifiedCurrencyAmount, UnifiedNativeCurrency, UnifiedToken, VMType, VM_TYPE_MAXIMA, ZERO, ZERO_ADDRESS, _100, _10000, _9975, computePriceImpact, getCurrencyAddress, getMatchedCurrency, getTokenComparator, getUnifiedCurrencyAddress, isCurrencySorted, isUnifiedCurrencySorted, sortCurrencies, sortUnifiedCurrencies, sortedInsert, sqrt, validateVMTypeInstance };
+/**
+ * Multiplier precision: ERC-8056 fixes this at 18 decimals. No precision-query function
+ * exists in the spec; do not query from chain or token metadata.
+ */
+declare const SCALED_UI_MULTIPLIER_DECIMALS: 18;
+/**
+ * Denominator for all multiplier math (`10n ** 18n`). Equivalent to a multiplier of `1.0×`.
+ */
+declare const SCALED_UI_DENOMINATOR: bigint;
+/**
+ * Branded type marking a `bigint` as a RAW on-chain token amount.
+ *
+ * Use `asRawAmount(n)` to mark an unbranded bigint. The math functions in this module
+ * accept plain `bigint` for ergonomic interop with the rest of the codebase; this brand
+ * exists as opt-in documentation at boundaries that want extra type-level discipline.
+ */
+type RawAmount = bigint & {
+    readonly __brand: 'ScaledUI.RawAmount';
+};
+/**
+ * Branded type marking a `bigint` as a UI-display token amount (post-multiplier).
+ *
+ * See `RawAmount` for usage notes — this brand exists for boundary discipline, not
+ * enforced runtime checking.
+ */
+type UiAmount = bigint & {
+    readonly __brand: 'ScaledUI.UiAmount';
+};
+declare const asRawAmount: (n: bigint) => RawAmount;
+declare const asUiAmount: (n: bigint) => UiAmount;
+/**
+ * Returns true if the multiplier represents the identity transform (`1.0×` = `1e18`).
+ * Use this for fast-path short-circuits in hot rendering paths (tokenlist render etc.).
+ */
+declare function isIdentityScaledUIMultiplier(multiplier: bigint): boolean;
+/**
+ * Convert a raw on-chain amount to its UI-display equivalent by applying the multiplier.
+ *
+ *     uiAmount = (rawAmount × multiplier) / 1e18
+ *
+ * For non-scaled tokens (`multiplier === 1e18`), this is the identity function and
+ * short-circuits without bigint mul/div.
+ *
+ * Prefer the on-chain helper `toUIAmount(rawAmount)` when the contract supports it
+ * (interface ID `0xa60bf13d`) for exact rounding-match with the contract. Use this
+ * JS implementation as a fallback when the contract lacks the helper, or in pure-math
+ * contexts (router, server-side, tests).
+ *
+ * @param rawAmount  the on-chain token amount (as returned by `balanceOf`, transfer events, etc.)
+ * @param multiplier the ERC-8056 multiplier (18-decimal fixed point; `1e18 = 1.0×`)
+ * @returns the UI-display equivalent
+ */
+declare function toScaledUIAmount(rawAmount: bigint, multiplier: bigint): bigint;
+/**
+ * Convert a UI-display amount back to its raw on-chain equivalent.
+ *
+ *     rawAmount = (uiAmount × 1e18) / multiplier
+ *
+ * For non-scaled tokens (`multiplier === 1e18`), this is the identity function and
+ * short-circuits without bigint mul/div.
+ *
+ * Prefer the on-chain helper `fromUIAmount(uiAmount)` when the contract supports it
+ * (interface ID `0xa60bf13d`) for exact rounding-match with the contract. Use this
+ * JS implementation as a fallback when the contract lacks the helper.
+ *
+ * @param uiAmount   the user-facing amount (post-multiplier)
+ * @param multiplier the ERC-8056 multiplier (18-decimal fixed point; `1e18 = 1.0×`)
+ * @returns the raw on-chain equivalent (safe to pass to `transfer`/`approve`/router calldata)
+ */
+declare function fromScaledUIAmount(uiAmount: bigint, multiplier: bigint): bigint;
+/**
+ * Convert a RAW pool price to its UI-display equivalent.
+ *
+ * A price is "quote per base". Each side scales by its own token's multiplier, so the
+ * displayed ratio scales by `quoteMultiplier / baseMultiplier`:
+ *
+ *     uiPrice = rawPrice × (quoteMultiplier / baseMultiplier)
+ *
+ * Implemented on the underlying fraction (`numerator × mQuote`, `denominator × mBase`), so the
+ * decimal `scalar` is untouched — the multiplier is a pure ratio on the human amount and is
+ * decimal-agnostic. For an all-identity pair this returns the input Price unchanged (no alloc).
+ *
+ * Mirror of `toScaledUIAmount` for the two-sided price case. Used by the add-liquidity current
+ * price / range / rate displays and the swap execution-price display.
+ */
+declare function toScaledUIPrice<TBase extends UnifiedCurrency, TQuote extends UnifiedCurrency>(price: Price<TBase, TQuote>, baseMultiplier: bigint, quoteMultiplier: bigint): Price<TBase, TQuote>;
+/**
+ * Convert a UI-display price back to its RAW equivalent — the inverse of `toScaledUIPrice`:
+ *
+ *     rawPrice = uiPrice × (baseMultiplier / quoteMultiplier)
+ *
+ * Used at the range-input boundary: a user types a UI price into the min/max boxes, which must
+ * be converted to the raw price before it feeds tick math. For an all-identity pair this returns
+ * the input Price unchanged.
+ */
+declare function fromScaledUIPrice<TBase extends UnifiedCurrency, TQuote extends UnifiedCurrency>(price: Price<TBase, TQuote>, baseMultiplier: bigint, quoteMultiplier: bigint): Price<TBase, TQuote>;
+
+export { BaseCurrency, BigintIsh, Currency, CurrencyAmount, FIVE, Fraction, InsufficientInputAmountError, InsufficientReservesError, MINIMUM_LIQUIDITY, MaxUint256, NativeCurrency, ONE, Percent, Price, RawAmount, Rounding, SCALED_UI_DENOMINATOR, SCALED_UI_MULTIPLIER_DECIMALS, SPLNativeCurrency, SPLToken, SerializedSPLToken, SerializedToken, TEN, THREE, TWO, Token, TradeType, UiAmount, UnifiedCurrency, UnifiedCurrencyAmount, UnifiedNativeCurrency, UnifiedToken, VMType, VM_TYPE_MAXIMA, ZERO, ZERO_ADDRESS, _100, _10000, _9975, asRawAmount, asUiAmount, computePriceImpact, fromScaledUIAmount, fromScaledUIPrice, getCurrencyAddress, getMatchedCurrency, getTokenComparator, getUnifiedCurrencyAddress, isCurrencySorted, isIdentityScaledUIMultiplier, isUnifiedCurrencySorted, sortCurrencies, sortUnifiedCurrencies, sortedInsert, sqrt, toScaledUIAmount, toScaledUIPrice, validateVMTypeInstance };

package/dist/index.js

@@ -699,6 +699,40 @@ function getMatchedCurrency(currency, list, matchWrappedCurrency = true) {
   return void 0;
 }
 
+// src/scaledUIAmount.ts
+var SCALED_UI_MULTIPLIER_DECIMALS = 18;
+var SCALED_UI_DENOMINATOR = 10n ** 18n;
+var asRawAmount = (n) => n;
+var asUiAmount = (n) => n;
+function isIdentityScaledUIMultiplier(multiplier) {
+  return multiplier === SCALED_UI_DENOMINATOR;
+}
+function toScaledUIAmount(rawAmount, multiplier) {
+  if (multiplier === 0n)
+    return rawAmount;
+  return isIdentityScaledUIMultiplier(multiplier) ? rawAmount : rawAmount * multiplier / SCALED_UI_DENOMINATOR;
+}
+function fromScaledUIAmount(uiAmount, multiplier) {
+  if (multiplier === 0n)
+    return uiAmount;
+  return isIdentityScaledUIMultiplier(multiplier) ? uiAmount : uiAmount * SCALED_UI_DENOMINATOR / multiplier;
+}
+var sanitizeMultiplier = (m) => m === 0n ? SCALED_UI_DENOMINATOR : m;
+function toScaledUIPrice(price, baseMultiplier, quoteMultiplier) {
+  const mBase = sanitizeMultiplier(baseMultiplier);
+  const mQuote = sanitizeMultiplier(quoteMultiplier);
+  if (isIdentityScaledUIMultiplier(mBase) && isIdentityScaledUIMultiplier(mQuote))
+    return price;
+  return new Price(price.baseCurrency, price.quoteCurrency, price.denominator * mBase, price.numerator * mQuote);
+}
+function fromScaledUIPrice(price, baseMultiplier, quoteMultiplier) {
+  const mBase = sanitizeMultiplier(baseMultiplier);
+  const mQuote = sanitizeMultiplier(quoteMultiplier);
+  if (isIdentityScaledUIMultiplier(mBase) && isIdentityScaledUIMultiplier(mQuote))
+    return price;
+  return new Price(price.baseCurrency, price.quoteCurrency, price.denominator * mQuote, price.numerator * mBase);
+}
+
 exports.BaseCurrency = BaseCurrency;
 exports.CurrencyAmount = CurrencyAmount;
 exports.FIVE = FIVE;
@@ -712,6 +746,8 @@ exports.ONE = ONE;
 exports.Percent = Percent;
 exports.Price = Price;
 exports.Rounding = Rounding;
+exports.SCALED_UI_DENOMINATOR = SCALED_UI_DENOMINATOR;
+exports.SCALED_UI_MULTIPLIER_DECIMALS = SCALED_UI_MULTIPLIER_DECIMALS;
 exports.SPLNativeCurrency = SPLNativeCurrency;
 exports.SPLToken = SPLToken;
 exports.TEN = TEN;
@@ -727,15 +763,22 @@ exports.ZERO_ADDRESS = ZERO_ADDRESS;
 exports._100 = _100;
 exports._10000 = _10000;
 exports._9975 = _9975;
+exports.asRawAmount = asRawAmount;
+exports.asUiAmount = asUiAmount;
 exports.computePriceImpact = computePriceImpact;
+exports.fromScaledUIAmount = fromScaledUIAmount;
+exports.fromScaledUIPrice = fromScaledUIPrice;
 exports.getCurrencyAddress = getCurrencyAddress;
 exports.getMatchedCurrency = getMatchedCurrency;
 exports.getTokenComparator = getTokenComparator;
 exports.getUnifiedCurrencyAddress = getUnifiedCurrencyAddress;
 exports.isCurrencySorted = isCurrencySorted;
+exports.isIdentityScaledUIMultiplier = isIdentityScaledUIMultiplier;
 exports.isUnifiedCurrencySorted = isUnifiedCurrencySorted;
 exports.sortCurrencies = sortCurrencies;
 exports.sortUnifiedCurrencies = sortUnifiedCurrencies;
 exports.sortedInsert = sortedInsert;
 exports.sqrt = sqrt;
+exports.toScaledUIAmount = toScaledUIAmount;
+exports.toScaledUIPrice = toScaledUIPrice;
 exports.validateVMTypeInstance = validateVMTypeInstance;

package/dist/index.mjs

@@ -689,4 +689,38 @@ function getMatchedCurrency(currency, list, matchWrappedCurrency = true) {
   return void 0;
 }
 
-export { BaseCurrency, CurrencyAmount, FIVE, Fraction, InsufficientInputAmountError, InsufficientReservesError, MINIMUM_LIQUIDITY, MaxUint256, NativeCurrency, ONE, Percent, Price, Rounding, SPLNativeCurrency, SPLToken, TEN, THREE, TWO, Token, TradeType, UnifiedCurrencyAmount, VMType, VM_TYPE_MAXIMA, ZERO, ZERO_ADDRESS, _100, _10000, _9975, computePriceImpact, getCurrencyAddress, getMatchedCurrency, getTokenComparator, getUnifiedCurrencyAddress, isCurrencySorted, isUnifiedCurrencySorted, sortCurrencies, sortUnifiedCurrencies, sortedInsert, sqrt, validateVMTypeInstance };
+// src/scaledUIAmount.ts
+var SCALED_UI_MULTIPLIER_DECIMALS = 18;
+var SCALED_UI_DENOMINATOR = 10n ** 18n;
+var asRawAmount = (n) => n;
+var asUiAmount = (n) => n;
+function isIdentityScaledUIMultiplier(multiplier) {
+  return multiplier === SCALED_UI_DENOMINATOR;
+}
+function toScaledUIAmount(rawAmount, multiplier) {
+  if (multiplier === 0n)
+    return rawAmount;
+  return isIdentityScaledUIMultiplier(multiplier) ? rawAmount : rawAmount * multiplier / SCALED_UI_DENOMINATOR;
+}
+function fromScaledUIAmount(uiAmount, multiplier) {
+  if (multiplier === 0n)
+    return uiAmount;
+  return isIdentityScaledUIMultiplier(multiplier) ? uiAmount : uiAmount * SCALED_UI_DENOMINATOR / multiplier;
+}
+var sanitizeMultiplier = (m) => m === 0n ? SCALED_UI_DENOMINATOR : m;
+function toScaledUIPrice(price, baseMultiplier, quoteMultiplier) {
+  const mBase = sanitizeMultiplier(baseMultiplier);
+  const mQuote = sanitizeMultiplier(quoteMultiplier);
+  if (isIdentityScaledUIMultiplier(mBase) && isIdentityScaledUIMultiplier(mQuote))
+    return price;
+  return new Price(price.baseCurrency, price.quoteCurrency, price.denominator * mBase, price.numerator * mQuote);
+}
+function fromScaledUIPrice(price, baseMultiplier, quoteMultiplier) {
+  const mBase = sanitizeMultiplier(baseMultiplier);
+  const mQuote = sanitizeMultiplier(quoteMultiplier);
+  if (isIdentityScaledUIMultiplier(mBase) && isIdentityScaledUIMultiplier(mQuote))
+    return price;
+  return new Price(price.baseCurrency, price.quoteCurrency, price.denominator * mQuote, price.numerator * mBase);
+}
+
+export { BaseCurrency, CurrencyAmount, FIVE, Fraction, InsufficientInputAmountError, InsufficientReservesError, MINIMUM_LIQUIDITY, MaxUint256, NativeCurrency, ONE, Percent, Price, Rounding, SCALED_UI_DENOMINATOR, SCALED_UI_MULTIPLIER_DECIMALS, SPLNativeCurrency, SPLToken, TEN, THREE, TWO, Token, TradeType, UnifiedCurrencyAmount, VMType, VM_TYPE_MAXIMA, ZERO, ZERO_ADDRESS, _100, _10000, _9975, asRawAmount, asUiAmount, computePriceImpact, fromScaledUIAmount, fromScaledUIPrice, getCurrencyAddress, getMatchedCurrency, getTokenComparator, getUnifiedCurrencyAddress, isCurrencySorted, isIdentityScaledUIMultiplier, isUnifiedCurrencySorted, sortCurrencies, sortUnifiedCurrencies, sortedInsert, sqrt, toScaledUIAmount, toScaledUIPrice, validateVMTypeInstance };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pancakeswap/swap-sdk-core",
   "license": "MIT",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "🛠 An SDK for building applications on top of Pancakeswap.",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",