@nadohq/shared 0.1.0-alpha.4

package/src/utils/interest.ts

@@ -0,0 +1,133 @@
+import { SpotProduct } from '../types/productTypes';
+import {
+  BigDecimal,
+  BigDecimalish,
+  BigDecimals,
+  removeDecimals,
+  toBigDecimal,
+} from './math';
+import { TimeInSeconds } from './time';
+
+/**
+ * Calculate amount total borrowed for a product
+ */
+export function calcTotalBorrowed(
+  totalBorrowsNormalized: BigDecimalish,
+  cumulativeBorrowsMultiplierX18: BigDecimalish,
+): BigDecimal {
+  return toBigDecimal(totalBorrowsNormalized).multipliedBy(
+    removeDecimals(cumulativeBorrowsMultiplierX18),
+  );
+}
+
+/**
+ * Calculate amount total deposited for a product.
+ */
+export function calcTotalDeposited(
+  totalDepositsNormalized: BigDecimalish,
+  cumulativeDepositsMultiplierX18: BigDecimalish,
+): BigDecimal {
+  return toBigDecimal(totalDepositsNormalized).multipliedBy(
+    removeDecimals(cumulativeDepositsMultiplierX18),
+  );
+}
+
+/**
+ * Calculates utilization ratio = abs(total borrowed / total deposited)
+ *
+ * @param product Spot product
+ */
+export function calcUtilizationRatio(product: SpotProduct) {
+  if (product.totalDeposited.eq(0) || product.totalBorrowed.eq(0)) {
+    return toBigDecimal(0);
+  }
+  return product.totalBorrowed.abs().div(product.totalDeposited);
+}
+
+/**
+ * Calculates per-second borrow interest rate for a product. For example, a returned rate of 0.1 indicates 10% borrower
+ * interest. The calculation for interest rate is as follows:
+ *
+ * If utilization ratio > inflection:
+ *  annual rate = (1 - utilization ratio) / (1 - inflection) * interestLargeCap + interestFloor + interestSmallCap
+ *
+ * If utilization ratio < inflection:
+ *  annual rate = utilization * interestSmallCap / inflection + utilization
+ *
+ * The returned rate is annual rate / 31536000 seconds per year.
+ *
+ * @param product Spot product
+ */
+export function calcBorrowRatePerSecond(product: SpotProduct) {
+  const {
+    interestFloor,
+    interestInflectionUtil,
+    interestSmallCap,
+    interestLargeCap,
+  } = product;
+  const utilization = calcUtilizationRatio(product);
+  if (utilization.eq(0)) {
+    return toBigDecimal(0);
+  }
+  const pastInflection = utilization.gt(interestInflectionUtil);
+
+  let annualRate: BigDecimal;
+  if (pastInflection) {
+    const utilizationTerm = interestLargeCap.times(
+      toBigDecimal(utilization)
+        .minus(interestInflectionUtil)
+        .div(BigDecimals.ONE.minus(interestInflectionUtil)),
+    );
+    annualRate = interestFloor.plus(interestSmallCap).plus(utilizationTerm);
+  } else {
+    const utilizationTerm = utilization
+      .div(interestInflectionUtil)
+      .times(interestSmallCap);
+    annualRate = interestFloor.plus(utilizationTerm);
+  }
+
+  return annualRate.div(TimeInSeconds.YEAR);
+}
+
+/**
+ * Calculates borrower interest rate compounded for a period of time.
+ *
+ * @param product Spot product
+ * @param seconds Number of seconds for the time period
+ */
+export function calcBorrowRateForTimeRange(
+  product: SpotProduct,
+  seconds: BigDecimalish,
+  minDepositRate: BigDecimalish,
+) {
+  const borrowRatePerSecond = calcBorrowRatePerSecond(product);
+
+  // Convert to number for this, with some loss of precision, but using `.pow()` causes us to hit browser resource limits
+  const borrowRateForTime =
+    borrowRatePerSecond.plus(1).toNumber() ** toBigDecimal(seconds).toNumber() -
+    1;
+  return toBigDecimal(borrowRateForTime).plus(toBigDecimal(minDepositRate));
+}
+
+/**
+ * Calculate depositor interest rate compounded for a period of time.
+ *
+ * @param product Spot product
+ * @param seconds Number of seconds for the time period
+ * @param interestFeeFrac Fraction of paid borrower interest that is paid as a fee (0.2 = 20% fee)
+ */
+export function calcRealizedDepositRateForTimeRange(
+  product: SpotProduct,
+  seconds: BigDecimalish,
+  interestFeeFrac: BigDecimalish,
+  minDepositRate: BigDecimalish,
+) {
+  const utilization = calcUtilizationRatio(product);
+  if (utilization.eq(0)) {
+    return toBigDecimal(0);
+  }
+  return utilization
+    .times(calcBorrowRateForTimeRange(product, seconds, toBigDecimal(0)))
+    .times(BigDecimals.ONE.minus(toBigDecimal(interestFeeFrac)))
+    .plus(toBigDecimal(minDepositRate));
+}

package/src/utils/isWriteableContract.ts

@@ -0,0 +1,11 @@
+import { Abi } from 'viem';
+import {
+  ContractInstance,
+  WriteableContractInstance,
+} from '../types/viemTypes';
+
+export function isWriteableContract<TAbi extends Abi>(
+  contract: ContractInstance<TAbi>,
+): contract is WriteableContractInstance<TAbi> {
+  return 'write' in contract;
+}

package/src/utils/mapValues.ts

@@ -0,0 +1,18 @@
+/**
+ * Map values of an object given mapFn. Avoids needing to pull in lodash
+ */
+export function mapValues<
+  TKey extends string | number | symbol,
+  TValue,
+  TNewValue,
+>(
+  obj: Record<TKey, TValue>,
+  mapFn: (value: TValue, key: TKey, index: number) => TNewValue,
+): Record<TKey, TNewValue> {
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value], index) => [
+      key,
+      mapFn(value as TValue, key as TKey, index),
+    ]),
+  ) as Record<TKey, TNewValue>;
+}

package/src/utils/math/BigDecimals.ts

@@ -0,0 +1,8 @@
+import { toBigDecimal } from './bigDecimal';
+
+export const BigDecimals = Object.freeze({
+  ZERO: toBigDecimal(0),
+  ONE: toBigDecimal(1),
+  INF: toBigDecimal(Infinity),
+  MAX_I128: toBigDecimal('170141183460469231731687303715884105727'),
+});

package/src/utils/math/bigDecimal.ts

@@ -0,0 +1,32 @@
+import { default as BigDecimal } from 'bignumber.js';
+
+// Renames `BigNumber` type from `bignumber.js`.
+export { default as BigDecimal } from 'bignumber.js';
+
+/**
+ * BigDecimal is a renamed `BigNumber` type from `bignumber.js`.
+ * Includes valid values & instances for BigDecimal.
+ *
+ * @see https://mikemcl.github.io/bignumber.js/
+ */
+export type BigDecimalish = BigDecimal | BigDecimal.Value | bigint;
+
+/**
+ * Converts a value to an instance of BigDecimal
+ *
+ * @param val
+ */
+export function toBigDecimal(val: BigDecimalish): BigDecimal {
+  const bnConstructorVal = (() => {
+    if (val instanceof BigDecimal) {
+      return val;
+    } else if (typeof val === 'string' || typeof val === 'number') {
+      return val;
+    } else if (typeof val === 'bigint') {
+      return val.toString();
+    }
+    // This is unlikely to occur, but it's here for completeness. Uses the suggestion here: https://typescript-eslint.io/rules/no-base-to-string/#alternatives
+    return JSON.stringify(val);
+  })();
+  return new BigDecimal(bnConstructorVal);
+}

package/src/utils/math/clamp.ts

@@ -0,0 +1,26 @@
+import { BigDecimal } from './bigDecimal';
+
+interface ClampOptions {
+  // Inclusive minimum value
+  min?: BigDecimal;
+  // Inclusive maximum value
+  max?: BigDecimal;
+}
+
+/**
+ * Clamps a value between optional minimum and maximum values.
+ *
+ * @param val
+ * @param opts Clamp options
+ */
+export function clampBigDecimal(
+  val: BigDecimal,
+  opts: ClampOptions,
+): BigDecimal {
+  if (opts.min != null && val.lt(opts.min)) {
+    return opts.min;
+  } else if (opts.max != null && val.gt(opts.max)) {
+    return opts.max;
+  }
+  return val;
+}

package/src/utils/math/decimalAdjustment.ts

@@ -0,0 +1,65 @@
+import { BigDecimal, BigDecimalish, toBigDecimal } from './bigDecimal';
+
+/**
+ * All Nado balances have 18 decimals. Ex. 1e18 = 1.0
+ */
+export const NADO_PRODUCT_DECIMALS = 18;
+
+/**
+ * Determines the result type after adjusting decimals based on the input type `T`.
+ *
+ * - If `T` is `undefined`, the result is `undefined`.
+ * - If `T` is a `number`, the result is a `number`.
+ * - Otherwise, the result is a `BigDecimal`.
+ */
+type AdjustDecimalsResult<T extends BigDecimalish | undefined> =
+  T extends undefined ? undefined : T extends number ? number : BigDecimal;
+
+/**
+ * Adds the specified # of decimals to the number. For example, value = 1, decimals = 2, returns 100.
+ *
+ * @param value can be undefined for better developer experience. If undefined, returns undefined.
+ * @param decimals number of decimal places to add, defaults to 18, which is the standard within Nado
+ */
+
+export function addDecimals<T extends BigDecimalish | undefined>(
+  value: T,
+  decimals: number = NADO_PRODUCT_DECIMALS,
+): AdjustDecimalsResult<T> {
+  const getResult = () => {
+    if (value == null) {
+      return undefined;
+    }
+
+    const adjustedValue = toBigDecimal(value).multipliedBy(
+      toBigDecimal(10).pow(decimals),
+    );
+    return typeof value === 'number' ? adjustedValue.toNumber() : adjustedValue;
+  };
+
+  return getResult() as AdjustDecimalsResult<T>;
+}
+
+/**
+ * Removes the specified # of decimals from the number. For example, value = 100, decimals = 2, returns 1.
+ *
+ * @param value can be undefined for better developer experience. If undefined, returns undefined.
+ * @param decimals number of decimal places to remove, defaults to 18, which is the standard within Nado
+ */
+export function removeDecimals<T extends BigDecimalish | undefined>(
+  value: T,
+  decimals: number = NADO_PRODUCT_DECIMALS,
+): AdjustDecimalsResult<T> {
+  const getResult = () => {
+    if (value == null) {
+      return undefined;
+    }
+
+    const adjustedValue = toBigDecimal(value).dividedBy(
+      toBigDecimal(10).pow(decimals),
+    );
+    return typeof value === 'number' ? adjustedValue.toNumber() : adjustedValue;
+  };
+
+  return getResult() as AdjustDecimalsResult<T>;
+}

package/src/utils/math/index.ts

@@ -0,0 +1,7 @@
+export * from './bigDecimal';
+export * from './toIntegerString';
+export * from './toBigInt';
+export * from './clamp';
+export * from './sumBigDecimalBy';
+export * from './decimalAdjustment';
+export * from './BigDecimals';

package/src/utils/math/sumBigDecimalBy.ts

@@ -0,0 +1,18 @@
+import { BigDecimal } from './bigDecimal';
+import { BigDecimals } from './BigDecimals';
+
+/**
+ * Util function to sum BigDecimal values, inspired by Lodash
+ * @param collection
+ * @param iteratee
+ */
+export function sumBigDecimalBy<T>(
+  collection: T[] | null | undefined,
+  iteratee: (value: T) => BigDecimal.Value,
+): BigDecimal {
+  return (
+    collection?.reduce((total, item) => {
+      return total.plus(iteratee(item));
+    }, BigDecimals.ZERO) ?? BigDecimals.ZERO
+  );
+}

package/src/utils/math/toBigInt.ts

@@ -0,0 +1,11 @@
+import { BigDecimalish } from './bigDecimal';
+import { toIntegerString } from './toIntegerString';
+
+/**
+ * Converts a BigDecimalish value to bigint
+ *
+ * @param val
+ */
+export function toBigInt(val: BigDecimalish): bigint {
+  return BigInt(toIntegerString(val));
+}

package/src/utils/math/toIntegerString.ts

@@ -0,0 +1,11 @@
+import { BigDecimalish, toBigDecimal } from './bigDecimal';
+
+/**
+ * Converts a BigDecimalish value to string
+ *
+ * @param val
+ */
+export function toIntegerString(val: BigDecimalish): string {
+  // toFixed is required as toString gives values with `e`
+  return toBigDecimal(val).toFixed(0);
+}

package/src/utils/orders/appendix/appendixTWAPValue.ts

@@ -0,0 +1,51 @@
+import { OrderAppendixTWAPFields } from '../../../types/orderAppendixTypes';
+import { addDecimals, removeDecimals, toBigInt } from '../../math';
+
+/**
+ * Packs the provided fields into a single 96-bit bigint.
+ *
+ * Bit layout (MSB → LSB):
+ * |   times   | slippage_x6 | reserved |
+ * |-----------|-------------|----------|
+ * | 95..64    | 63..32      | 31..0    |
+ * | 32 bits   | 32 bits     | 32 bits  |
+ *
+ * - `times` occupies bits 95..64 (most significant 32 bits)
+ * - `slippage_x6` occupies bits 63..32 (middle 32 bits)
+ * - `reserved` occupies bits 31..0 (least significant 32 bits)
+ */
+export function packTWAPOrderAppendixValue({
+  numOrders,
+  slippageFrac,
+}: OrderAppendixTWAPFields): bigint {
+  const numOrdersBigInt = toBigInt(numOrders);
+  const slippageX6BigInt = toBigInt(addDecimals(slippageFrac, 6));
+
+  return (
+    ((numOrdersBigInt & 0xffffffffn) << 64n) |
+    ((slippageX6BigInt & 0xffffffffn) << 32n) |
+    // The last reserved 32 bits are set to 0
+    (0n & 0xffffffffn)
+  );
+}
+
+/**
+ * Unpacks a 96-bit bigint into its component fields for TWAP orders.
+ *
+ * @param value 96-bit bigint to unpack
+ * @returns Object with:
+ *   - times: number, from bits 95..64
+ *   - slippage_x6: number, from bits 63..32
+ *   - reserved: number, from bits 31..0
+ */
+export function unpackTWAPOrderAppendixValue(
+  value: bigint,
+): OrderAppendixTWAPFields {
+  const numOrders = (value >> 64n) & 0xffffffffn;
+  const slippageX6 = (value >> 32n) & 0xffffffffn;
+
+  return {
+    numOrders: Number(numOrders),
+    slippageFrac: removeDecimals(slippageX6, 6).toNumber(),
+  };
+}

package/src/utils/orders/appendix/bitMaskValue.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns the value masked to the specified bit width.
+ *
+ * @param {bigint} value - The value to be masked.
+ * @param {number} bitWidth - The bit width for masking.
+ * @returns {bigint} - The masked value.
+ */
+export function bitMaskValue(value: bigint | number, bitWidth: number): bigint {
+  const bitMask = (1n << BigInt(bitWidth)) - 1n;
+  return BigInt(value) & bitMask;
+}

package/src/utils/orders/appendix/index.ts

@@ -0,0 +1,5 @@
+export * from './appendixTWAPValue';
+export * from './unpackOrderAppendix';
+export * from './packOrderAppendix';
+export * from './types';
+export * from './bitMaskValue';

package/src/utils/orders/appendix/orderAppendix.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from '@jest/globals';
+import { OrderAppendix, OrderExecutionType } from '../../../types';
+import { packOrderAppendix } from './packOrderAppendix';
+import { unpackOrderAppendix } from './unpackOrderAppendix';
+
+describe('OrderAppendix packing/unpacking', () => {
+  it('should pack and unpack an order appendix without iso/twap values', () => {
+    const appendix: OrderAppendix = {
+      orderExecutionType: 'default',
+      triggerType: 'price',
+    };
+    const packed = packOrderAppendix(appendix);
+    const unpacked = unpackOrderAppendix(packed);
+    expect(packed).toBe(4096n);
+    expect(unpacked.orderExecutionType).toBe(appendix.orderExecutionType);
+    expect(unpacked.triggerType).toBe(appendix.triggerType);
+    expect(unpacked.reduceOnly).toBeFalsy();
+  });
+
+  it('should handle reduceOnly true', () => {
+    const appendix: OrderAppendix = {
+      orderExecutionType: 'default',
+      triggerType: 'price',
+      reduceOnly: true,
+    };
+    const packed = packOrderAppendix(appendix);
+    const unpacked = unpackOrderAppendix(packed);
+    expect(packed).toBe(6144n);
+    expect(unpacked.reduceOnly).toBe(true);
+  });
+
+  it('should handle all orderExecutionType values', () => {
+    const types: OrderExecutionType[] = ['default', 'ioc', 'fok', 'post_only'];
+    for (const type of types) {
+      const appendix: OrderAppendix = {
+        orderExecutionType: type,
+        triggerType: 'price',
+      };
+      const packed = packOrderAppendix(appendix);
+      const unpacked = unpackOrderAppendix(packed);
+      expect(unpacked.orderExecutionType).toBe(type);
+    }
+  });
+
+  it('should handle all triggerType values', () => {
+    const triggers = ['price', 'twap', 'twap_custom_amounts'] as const;
+    for (const trigger of triggers) {
+      const appendix: OrderAppendix = {
+        orderExecutionType: 'default',
+        triggerType: trigger,
+      };
+      const packed = packOrderAppendix(appendix);
+      const unpacked = unpackOrderAppendix(packed);
+      expect(unpacked.triggerType).toBe(trigger);
+    }
+  });
+
+  it('should handle isolated margin', () => {
+    const appendix: OrderAppendix = {
+      orderExecutionType: 'default',
+      triggerType: 'price',
+
+      isolated: { margin: 123456789012345678901234n },
+    };
+    const packed = packOrderAppendix(appendix);
+    const unpacked = unpackOrderAppendix(packed);
+    expect(packed).toBe(530242871277196831127717244047616n);
+    expect(unpacked.isolated?.margin).toBe(123456789012345678901234n);
+  });
+
+  it('should handle TWAP fields', () => {
+    const appendix: OrderAppendix = {
+      orderExecutionType: 'default',
+      triggerType: 'twap',
+
+      twap: { numOrders: 10, slippageFrac: 0.005 },
+    };
+    const packed = packOrderAppendix(appendix);
+    const unpacked = unpackOrderAppendix(packed);
+    expect(packed).toBe(792281717376363744483197591552n);
+    expect(unpacked.twap).toMatchObject({ numOrders: 10, slippageFrac: 0.005 });
+  });
+
+  it('should handle max values for all fields for iso orders', () => {
+    const appendix: OrderAppendix = {
+      orderExecutionType: 'post_only',
+      triggerType: undefined,
+      reduceOnly: true,
+      isolated: { margin: 79228162514264337593543950335n }, // 2^96-1
+    };
+    const packed = packOrderAppendix(appendix);
+    const unpacked = unpackOrderAppendix(packed);
+    expect(unpacked.orderExecutionType).toBe(appendix.orderExecutionType);
+    expect(unpacked.triggerType).toBe(appendix.triggerType);
+    expect(unpacked.reduceOnly).toBe(appendix.reduceOnly);
+    expect(unpacked.isolated?.margin).toBe(79228162514264337593543950335n);
+    expect(unpacked.twap).toBe(undefined);
+    expect(packed).toBe(340282366920938463463374607427473248000n);
+  });
+
+  it('should handle max values for all fields for TWAP orders', () => {
+    const appendix: OrderAppendix = {
+      orderExecutionType: 'post_only',
+      triggerType: 'twap_custom_amounts',
+      reduceOnly: true,
+      twap: {
+        // max 32-bit unsigned int
+        numOrders: 4294967295,
+        slippageFrac: 0.000001,
+      },
+    };
+    const packed = packOrderAppendix(appendix);
+    const unpacked = unpackOrderAppendix(packed);
+    expect(unpacked.orderExecutionType).toBe(appendix.orderExecutionType);
+    expect(unpacked.triggerType).toBe(appendix.triggerType);
+    expect(unpacked.reduceOnly).toBe(appendix.reduceOnly);
+    expect(unpacked.twap?.slippageFrac).toBe(0.000001);
+    expect(unpacked.twap?.numOrders).toBe(4294967295);
+    expect(packed).toBe(340282366841710300967557013911933828608n);
+  });
+});

package/src/utils/orders/appendix/packOrderAppendix.ts

@@ -0,0 +1,71 @@
+import { OrderAppendix } from '../../../types/orderAppendixTypes';
+import { toBigInt } from '../../math/toBigInt';
+import { packTWAPOrderAppendixValue } from './appendixTWAPValue';
+import { bitMaskValue } from './bitMaskValue';
+import { PackedOrderAppendixBits } from './types';
+
+function mapOrderAppendixToBitValues(
+  appendix: OrderAppendix,
+): PackedOrderAppendixBits {
+  const value = (() => {
+    if (appendix.twap) {
+      return packTWAPOrderAppendixValue(appendix.twap);
+    }
+    if (appendix.isolated) {
+      return toBigInt(appendix.isolated.margin);
+    }
+    return 0n;
+  })();
+  const trigger = (() => {
+    switch (appendix.triggerType) {
+      case 'price':
+        return 1;
+      case 'twap':
+        return 2;
+      case 'twap_custom_amounts':
+        return 3;
+      default:
+        return 0;
+    }
+  })();
+  const orderType = (() => {
+    switch (appendix.orderExecutionType) {
+      case 'default':
+        return 0;
+      case 'ioc':
+        return 1;
+      case 'fok':
+        return 2;
+      case 'post_only':
+        return 3;
+    }
+  })();
+
+  return {
+    value,
+    reserved: 0,
+    trigger,
+    reduceOnly: appendix.reduceOnly ? 1 : 0,
+    orderType,
+    isolated: appendix.isolated ? 1 : 0,
+    version: 0,
+  };
+}
+
+/**
+ * Pack the OrderAppendix fields into a single bigint.
+ * @param appendix
+ */
+export function packOrderAppendix(appendix: OrderAppendix): bigint {
+  const bits = mapOrderAppendixToBitValues(appendix);
+
+  // Ensure value is within 96 bits
+  let packed = bitMaskValue(bits.value, 96);
+  packed = (packed << 18n) | bitMaskValue(bits.reserved, 18);
+  packed = (packed << 2n) | bitMaskValue(bits.trigger, 2);
+  packed = (packed << 1n) | bitMaskValue(bits.reduceOnly, 1);
+  packed = (packed << 2n) | bitMaskValue(bits.orderType, 2);
+  packed = (packed << 1n) | bitMaskValue(bits.isolated, 1);
+  packed = (packed << 8n) | bitMaskValue(bits.version, 8);
+  return packed;
+}

package/src/utils/orders/appendix/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Bit layout for OrderAppendix packing (MSB → LSB):
+ *
+ * |   value   | reserved | trigger | reduceOnly | orderType | isolated | version |
+ * |-----------|----------|---------|------------|-----------|----------|---------|
+ * | 127..32   | 31..14   | 13..12  | 11         | 10..9     | 8        | 7..0    |
+ * |  96 bits  | 18 bits  | 2 bits  | 1 bit      | 2 bits    | 1 bit    | 8 bits  |
+ */
+export interface PackedOrderAppendixBits {
+  value: bigint; // 96 bits
+  reserved: number; // 18 bits, set to 0
+  trigger: number; // 2 bits
+  reduceOnly: number; // 1 bit
+  orderType: number; // 2 bits
+  isolated: number; // 1 bit
+  version: number; // 8 bits, set to 0
+}