@morpho-org/blue-sdk 1.0.1 → 1.0.3

package/src/helpers/format/format.ts

@@ -0,0 +1,416 @@
+import { parseUnits } from "ethers";
+
+import { getEnUSNumberToLocalParts } from "../locale";
+
+enum Format {
+  number = "number",
+  commas = "commas",
+  short = "short",
+  hex = "hex",
+  percent = "percent",
+}
+
+interface BaseFormatOptions {
+  format: Format;
+  digits?: number;
+  removeTrailingZero?: boolean;
+  min?: number;
+  max?: number;
+  sign?: boolean;
+  unit?: string;
+  readable?: boolean;
+  locale?: string;
+}
+
+interface FormatShortOptions extends BaseFormatOptions {
+  format: Format.short;
+  smallValuesWithCommas?: boolean;
+}
+interface FormatHexOptions {
+  format: Format.hex;
+}
+interface FormatCommasOptions extends BaseFormatOptions {
+  format: Format.commas;
+}
+interface FormatNumberOptions extends BaseFormatOptions {
+  format: Format.number;
+}
+
+interface FormatPercentOptions extends BaseFormatOptions {
+  format: Format.percent;
+}
+
+type FormatOptions =
+  | FormatHexOptions
+  | FormatShortOptions
+  | FormatNumberOptions
+  | FormatCommasOptions
+  | FormatPercentOptions;
+
+declare global {
+  interface String {
+    insert(index: number, substr: string, fillWith?: string): string;
+  }
+}
+
+String.prototype.insert = function (index, substr, fillWith) {
+  if (index < 0) index = this.length + index;
+
+  let filler = "";
+  if (index < 0) {
+    if (fillWith) filler = fillWith.repeat(-index).slice(index);
+    index = 0;
+  }
+  return this.slice(0, index) + substr + filler + this.slice(index);
+};
+
+const RANGES = [
+  {
+    minDecimals: 24,
+    symbol: "Y",
+  },
+  {
+    minDecimals: 21,
+    symbol: "Z",
+  },
+  {
+    minDecimals: 18,
+    symbol: "E",
+  },
+  {
+    minDecimals: 15,
+    symbol: "P",
+  },
+  {
+    minDecimals: 12,
+    symbol: "T",
+  },
+  {
+    minDecimals: 9,
+    symbol: "B",
+  },
+  {
+    minDecimals: 6,
+    symbol: "M",
+  },
+  {
+    minDecimals: 4,
+    power: 3,
+    symbol: "k",
+  },
+];
+const _formatShort = (
+  bi: bigint,
+  decimals: number,
+  formatOptions: Omit<FormatShortOptions, "format">
+) => {
+  const stringValue = bi.toString();
+  const params = RANGES.find(
+    (range) => stringValue.length > range.minDecimals + decimals
+  );
+  if (params) {
+    return (
+      _applyOptions(
+        stringValue.insert(
+          -((params.power ?? params.minDecimals) + decimals),
+          ".",
+          "0"
+        ),
+        formatOptions
+      ) + params.symbol
+    );
+  }
+  if (formatOptions.smallValuesWithCommas) {
+    return _formatCommas(bi, decimals, formatOptions);
+  }
+  return _applyOptions(stringValue.insert(-decimals, ".", "0"), formatOptions);
+};
+
+const _formatCommas = (
+  bi: bigint,
+  decimals: number,
+  formatOptions: Omit<FormatCommasOptions, "format">
+) => {
+  const stringValue = decimals
+    ? bi.toString().insert(-decimals, ".", "0")
+    : bi.toString();
+
+  const [wholePart, decimalPart] = stringValue.split(".");
+
+  return _applyOptions(
+    wholePart!
+      .split("")
+      .reduce(
+        (formattedNumber, digit, i, arr) =>
+          `${formattedNumber}${!i || (arr.length - i) % 3 ? "" : ","}${digit}`,
+        ""
+      ) + (decimalPart ? "." + decimalPart : ""),
+    formatOptions
+  );
+};
+
+const _formatNumber = (
+  bi: bigint,
+  decimals: number,
+  formatOptions: Omit<FormatNumberOptions, "format">
+) => {
+  if (decimals === 0) return _applyOptions(bi.toString(), formatOptions);
+  return _applyOptions(
+    bi.toString().insert(-decimals, ".", "0"),
+    formatOptions
+  );
+};
+
+const _withUnit = (value: string, unit: string) => {
+  switch (unit) {
+    case "$":
+      return `$${value}`;
+    case "":
+    case "%":
+      return `${value}${unit}`;
+    default:
+      return `${value} ${unit}`;
+  }
+};
+
+const _applyOptions = (
+  value: string,
+  formatOptions: Omit<BaseFormatOptions, "format">
+) => {
+  let [wholePart, decimalPart = ""] = value.split(".");
+  const isZero = value.match(/[1-9]/)?.index === undefined;
+
+  if (formatOptions.digits !== undefined) {
+    decimalPart = decimalPart + "0".repeat(formatOptions.digits);
+    decimalPart = decimalPart.slice(0, formatOptions.digits);
+  }
+
+  if (formatOptions.removeTrailingZero) {
+    decimalPart = decimalPart.replace(/\.?0+$/, "");
+  }
+
+  value = (wholePart || "0") + (decimalPart ? "." + decimalPart : "");
+
+  const { value: _value, decimalSymbol } = getEnUSNumberToLocalParts(
+    value,
+    formatOptions.locale
+  );
+  value = _value;
+
+  const firstNonZero = value.match(/[1-9]/);
+  if (
+    firstNonZero?.index === undefined &&
+    formatOptions.digits &&
+    !isZero &&
+    formatOptions.readable
+  )
+    return `< 0${decimalSymbol}${"0".repeat(formatOptions.digits - 1)}1`;
+
+  return value;
+};
+
+function formatBI(
+  bi: bigint,
+  decimals: number,
+  formatOptions: FormatOptions = { format: Format.hex }
+): string {
+  if (formatOptions.format === Format.hex) return bi.toString(16);
+
+  const maxBI =
+    formatOptions.max !== undefined &&
+    parseUnits(formatOptions.max.toString(), decimals);
+  if (maxBI && bi > maxBI) {
+    return `> ${formatBI(maxBI, decimals, formatOptions)}`;
+  }
+  const minBI =
+    formatOptions.min !== undefined &&
+    parseUnits(formatOptions.min.toString(), decimals);
+  if (minBI !== false && bi < minBI && bi !== 0n) {
+    return `< ${formatBI(minBI, decimals, formatOptions)}`;
+  }
+
+  let value: string;
+  const isNegative = bi < 0n;
+  const absBI = bi > 0n ? bi : -bi;
+
+  switch (formatOptions.format) {
+    case Format.commas:
+      value = _formatCommas(absBI, decimals, formatOptions);
+      break;
+    case Format.number:
+      value = _formatNumber(absBI, decimals, formatOptions);
+      break;
+    case Format.short:
+      value = _formatShort(absBI, decimals, formatOptions);
+      break;
+    case Format.percent:
+      value = _formatNumber(absBI * 100n, decimals, formatOptions);
+      break;
+  }
+
+  const formattedValue =
+    (isNegative && !/^0\.0+$/.test(value)
+      ? "-"
+      : formatOptions.sign
+      ? "+"
+      : "") + value;
+
+  if (formatOptions.unit) {
+    return _withUnit(formattedValue, formatOptions.unit);
+  }
+
+  return formattedValue;
+}
+
+/**
+ * returns a string representation of a number, always in a decimal format (avoid the 1.34e-15 format for small numbers)
+ * @param number
+ */
+const safeNumberToString = (number: number) => {
+  const str = number.toString();
+
+  const [a, n] = str.split(/[eE]/);
+  if (a == null || n == null) return str;
+
+  if (n[0] === "+") {
+    const [whole, decimal = ""] = a.split(".");
+    return whole + decimal + "0".repeat(+n - decimal.length);
+  }
+
+  if (n[0] === "-") {
+    const isNegative = a[0] === "-";
+    return (
+      (isNegative ? "-" : "") +
+      "0." +
+      "0".repeat(-+n - 1) +
+      (isNegative ? a.slice(1) : a).split(".").join("")
+    );
+  }
+
+  throw new Error(`Unhandled case: ${str}`);
+};
+
+export abstract class BaseFormatter {
+  protected abstract _options: FormatOptions;
+
+  constructor() {}
+
+  of(value: bigint, decimals: number): string;
+  of(value: number): string;
+  of(value: bigint | number, decimals?: number) {
+    let _decimals: number;
+
+    if (typeof value === "number") {
+      const strNumber = safeNumberToString(value);
+      let [, d = ""] = strNumber.split(".");
+      _decimals = d.length;
+      value = parseUnits(strNumber, _decimals);
+    } else {
+      _decimals = decimals!;
+    }
+
+    return formatBI(value, _decimals, this._options);
+  }
+}
+
+export class HexFormatter extends BaseFormatter {
+  protected _options = { format: Format.hex };
+}
+
+export abstract class CommonFormatter extends BaseFormatter {
+  protected abstract _options: BaseFormatOptions;
+
+  digits(_d: number) {
+    this._options.digits = _d;
+    return this;
+  }
+
+  removeTrailingZero() {
+    this._options.removeTrailingZero = true;
+    return this;
+  }
+
+  readable() {
+    this._options.readable = true;
+    return this;
+  }
+
+  min(_m: number) {
+    this._options.min = _m;
+    return this;
+  }
+
+  max(_m: number) {
+    this._options.max = _m;
+    return this;
+  }
+
+  sign() {
+    this._options.sign = true;
+    return this;
+  }
+
+  unit(_u: string) {
+    this._options.unit = _u;
+    return this;
+  }
+
+  locale(_l: string) {
+    this._options.locale = _l;
+    return this;
+  }
+}
+
+export class NumberFormatter extends CommonFormatter {
+  protected _options: FormatNumberOptions = { format: Format.number };
+}
+
+export class CommasFormatter extends CommonFormatter {
+  protected _options: FormatCommasOptions = { format: Format.commas };
+}
+
+export class ShortFormatter extends CommonFormatter {
+  protected _options: FormatShortOptions = { format: Format.short };
+
+  smallValuesWithCommas() {
+    this._options.smallValuesWithCommas = true;
+    return this;
+  }
+}
+
+export class PercentFormatter extends CommonFormatter {
+  protected _options: FormatPercentOptions = { format: Format.percent };
+}
+
+export const format = {
+  /**
+   * Return the value as an integer in hex format
+   */
+  get hex() {
+    return new HexFormatter();
+  },
+  /**
+   * Return the value as a stringified number (12345.6789)
+   */
+  get number() {
+    return new NumberFormatter();
+  },
+  /**
+   * Return the value as a commas-separated stringified number (12,345.6789)
+   */
+  get commas() {
+    return new CommasFormatter();
+  },
+  /**
+   * Return the value as a shorted stringified number (12.3456789k)
+   */
+  get short() {
+    return new ShortFormatter();
+  },
+  /**
+   * Return the value as a percent based stringified number (10.00 instead of 0.1)
+   */
+  get percent() {
+    return new PercentFormatter();
+  },
+};

package/src/helpers/getChecksumedAddress.ts

@@ -0,0 +1,15 @@
+import { AddressLike, getAddress as _getAddress } from "ethers";
+
+/**
+ * Transform an AddressLike into a checksumed address
+ *
+ * @param address Address to transform
+ */
+export const getChecksumedAddress = async (address: AddressLike) => {
+  const awaited = await address;
+  // Ethers getAddress function is throwing an error if the address is already checksumed
+
+  if (typeof awaited === "string") return _getAddress(awaited.toLowerCase());
+
+  return _getAddress((await awaited.getAddress()).toLowerCase());
+};

package/{lib/helpers/isZeroAddressOrUnset.d.ts → src/helpers/isZeroAddressOrUnset.ts}

@@ -1,7 +1,13 @@
+import { ZeroAddress } from "ethers";
+
 /**
  * Check if an address is the zero address, null, or undefined.
  *
  * @param address - The address to check, which can be a valid address, null, or undefined.
  * @returns True if the address is zero, null, or undefined; otherwise, false.
  */
-export declare function isZeroAddressOrUnset(address: string | null | undefined): boolean;
+export function isZeroAddressOrUnset(
+  address: string | null | undefined
+): boolean {
+  return address === undefined || address === null || address === ZeroAddress;
+}

package/src/helpers/locale.ts

@@ -0,0 +1,108 @@
+type LocaleSymbols = {
+  decimalSymbol: string;
+  groupSymbol: string;
+  locale: string;
+};
+
+export type LocaleParts = LocaleSymbols & {
+  value: string;
+};
+
+const _convertEnNumStrToLocale = (
+  numStr: string,
+  localSymbols: LocaleSymbols
+) => {
+  return numStr
+    .replaceAll(",", "#TEMP#")
+    .replaceAll(".", localSymbols.decimalSymbol)
+    .replaceAll("#TEMP#", localSymbols.groupSymbol);
+};
+
+/**
+ * @returns the locale symbols for the given locale defaulting to en-US
+ */
+export const getLocaleSymbols = (locale: string): LocaleSymbols => {
+  let formatter: Intl.NumberFormat;
+  const formatterOptions = {
+    useGrouping: true,
+    maximumFractionDigits: 1,
+    minimumFractionDigits: 1,
+  };
+
+  try {
+    formatter = new Intl.NumberFormat(locale, formatterOptions);
+  } catch {
+    formatter = new Intl.NumberFormat("en-US", formatterOptions);
+  }
+
+  const parts = formatter.formatToParts(12345.6);
+
+  const decimalSymbol = parts.find((part) => part.type === "decimal")!.value;
+  const groupSymbol = parts.find((part) => part.type === "group")!.value;
+
+  return { decimalSymbol, groupSymbol, locale };
+};
+
+/**
+ * @returns the effective browser locale
+ */
+export const getEffectiveLocale = () => {
+  if (typeof window !== "undefined") {
+    try {
+      const locale =
+        navigator?.language || document?.documentElement?.lang || "en-US";
+      new Intl.NumberFormat(locale);
+      return locale;
+    } catch (e) {
+      return "en-US";
+    }
+  }
+  return "en-US";
+};
+
+/**
+ * @returns the value as a string with the given locale symbols
+ * @param numStr the number as a string in the "from" locale (e.g. "1,2345.6" for en-US)
+ * @param from the locale the numStr is in (e.g. "en-US")
+ * @param to the locale to convert to (e.g. "fr-FR")
+ */
+export const convertNumStrToLocal = (
+  numStr: string,
+  from: string,
+  to: string
+) => {
+  const fromSymbols = getLocaleSymbols(from);
+  const toSymbols = getLocaleSymbols(to);
+
+  return numStr
+    .replaceAll(fromSymbols.groupSymbol, "#GROUP#")
+    .replaceAll(fromSymbols.decimalSymbol, "#DECIMAL#")
+    .replaceAll("#GROUP#", toSymbols.groupSymbol)
+    .replaceAll("#DECIMAL#", toSymbols.decimalSymbol);
+};
+
+/**
+ * @returns the value as a string in the effective browser locale
+ * @param numStr the number as a string in the effective browser locale (e.g. "1,2345.6" for en-US)
+ * @param to the locale to use (e.g. "fr-FR")
+ */
+export const convertNumStrFromEffectiveTo = (numStr: string, to: string) => {
+  const from = getEffectiveLocale();
+  return convertNumStrToLocal(numStr, from, to);
+};
+
+/**
+ * @returns the value as a string with the given locale symbols either from the given locale or the effective browser locale
+ * @param numStr the number as a string in english format (e.g. "1,2345.6")
+ * @param locale optional - the locale to use (e.g. "fr-FR")
+ */
+export const getEnUSNumberToLocalParts = (
+  numStr: string,
+  locale?: string
+): LocaleParts => {
+  const _locale = locale || getEffectiveLocale();
+  const localSymbols = getLocaleSymbols(_locale);
+  const value = _convertEnNumStrToLocale(numStr, localSymbols);
+
+  return { ...localSymbols, value };
+};

package/src/holding/Holding.ts

@@ -0,0 +1,109 @@
+import { BigNumberish, toBigInt } from "ethers";
+
+import { entries, fromEntries } from "@morpho-org/morpho-ts";
+
+import { AddressLabel, NATIVE_ADDRESS } from "../addresses";
+import { Address } from "../types";
+
+export const ERC20_ALLOWANCE_RECIPIENTS = [
+  "morpho",
+  "permit2",
+  "bundler",
+] as const satisfies readonly AddressLabel[];
+
+export const PERMIT2_ALLOWANCE_RECIPIENTS = [
+  "morpho",
+  "bundler",
+] as const satisfies readonly Exclude<AddressLabel, "permit2">[];
+
+export type Erc20AllowanceRecipient =
+  (typeof ERC20_ALLOWANCE_RECIPIENTS)[number];
+
+export type Permit2AllowanceRecipient =
+  (typeof PERMIT2_ALLOWANCE_RECIPIENTS)[number];
+
+export interface Permit2Allowance {
+  amount: bigint;
+  expiration: bigint;
+  nonce: bigint;
+}
+
+export interface InputHolding {
+  user: Address;
+  token: Address;
+  erc20Allowances: {
+    [key in Erc20AllowanceRecipient]: BigNumberish;
+  };
+  permit2Allowances: {
+    [key in Permit2AllowanceRecipient]: Permit2Allowance;
+  };
+  erc2612Nonce?: BigNumberish;
+  canTransfer?: boolean;
+  balance: BigNumberish;
+}
+
+export class Holding implements InputHolding {
+  /**
+   * The user of this holding.
+   */
+  public readonly user: Address;
+
+  /**
+   * The token in which this holding is denominated.
+   */
+  public readonly token: Address;
+
+  /**
+   * The balance of the user for this token.
+   */
+  public balance: bigint;
+
+  /**
+   * Whether the user is allowed to transfer this holding's balance.
+   */
+  public canTransfer?: boolean;
+
+  /**
+   * ERC20 allowance for this token from the user to the allowance recipient.
+   */
+  public readonly erc20Allowances: {
+    [key in Erc20AllowanceRecipient]: bigint;
+  };
+
+  /**
+   * Permit2 allowance for this token from the user to the allowance recipient.
+   */
+  public readonly permit2Allowances: {
+    [key in Permit2AllowanceRecipient]: Permit2Allowance;
+  };
+
+  /**
+   * ERC-2612 Permit nonce of the user for this token.
+   * `undefined` if the token does not support ERC-2612.
+   */
+  public erc2612Nonce?: bigint;
+
+  constructor({
+    user,
+    token,
+    erc20Allowances,
+    permit2Allowances,
+    balance,
+    erc2612Nonce,
+    canTransfer = true,
+  }: InputHolding) {
+    this.user = user;
+    this.token = token;
+    this.balance = toBigInt(balance);
+    this.canTransfer = token === NATIVE_ADDRESS || canTransfer;
+    this.erc20Allowances = fromEntries(
+      entries(erc20Allowances).map(([address, allowance]) => [
+        address,
+        toBigInt(allowance),
+      ])
+    );
+    this.permit2Allowances = permit2Allowances;
+
+    if (erc2612Nonce != null) this.erc2612Nonce = toBigInt(erc2612Nonce);
+  }
+}