@nadohq/shared 0.1.0-alpha.4

package/src/types/marketTypes.ts

@@ -0,0 +1,40 @@
+import { BigDecimal } from '../utils/math';
+import {
+  PerpProduct,
+  Product,
+  ProductEngineType,
+  SpotProduct,
+} from './productTypes';
+
+/**
+ * Shared properties of a market
+ */
+export interface Market {
+  productId: number;
+  type: ProductEngineType;
+  product: Product;
+  // Minimum order size to be placed on the book (i.e. not an IOC order)
+  minSize: BigDecimal;
+  // Price increment for the orderbook, order prices must be placed at multiples of this increment
+  priceIncrement: BigDecimal;
+  // Size increment for the orderbook, order sizes must be placed at multiples of this increment
+  sizeIncrement: BigDecimal;
+}
+
+/**
+ * Perp market with perp product info
+ */
+export interface PerpMarket extends Market {
+  type: ProductEngineType.PERP;
+  product: PerpProduct;
+}
+
+/**
+ * Spot market with spot product info
+ */
+export interface SpotMarket extends Market {
+  type: ProductEngineType.SPOT;
+  product: SpotProduct;
+}
+
+export type MarketWithProduct = PerpMarket | SpotMarket;

package/src/types/nadoContractTypes.ts

@@ -0,0 +1,14 @@
+import { NadoAbis, NadoContractName } from '../abis/nadoAbis';
+import { WriteableContractInstance } from './viemTypes';
+
+/**
+ * Encapsulates the set of Nado contracts required for querying and executing, assumes that a wallet client is connected
+ */
+export type NadoContracts = {
+  [name in NadoContractName]: WriteableContractInstance<NadoAbis[name]>;
+};
+
+// Utility types to bundle parameters with contracts
+export type WithContracts<T> = T & NadoContracts;
+export type WithContract<TContractName extends keyof NadoContracts, T> = T &
+  Pick<NadoContracts, TContractName>;

package/src/types/orderAppendixTypes.ts

@@ -0,0 +1,58 @@
+import { BigDecimalish } from '../utils/math';
+import { OrderExecutionType } from './OrderExecutionType';
+
+/**
+ * Encodes whether the order will be sent to the trigger service
+ */
+export type OrderAppendixTriggerType =
+  | 'price'
+  | 'twap'
+  // TWAP with specified order amounts, which will be specified in the Trigger Order itself
+  | 'twap_custom_amounts';
+
+/**
+ * Fields associated with a TWAP trigger order.
+ */
+export interface OrderAppendixTWAPFields {
+  /**
+   * Number of TWAP orders to be placed.
+   */
+  numOrders: number;
+  /**
+   * Maximum slippage on each TWAP order, based on the oracle price at time of order execution.
+   * Ex: 0.01 means 1% slippage.
+   */
+  slippageFrac: number;
+}
+
+/**
+ * Fields associated with an isolated order
+ */
+export interface OrderAppendixIsolatedFields {
+  /**
+   * Amount of margin to transfer into the isolated position.
+   */
+  margin: BigDecimalish;
+}
+
+/**
+ * All the fields encoded by the order appendix
+ */
+export interface OrderAppendix {
+  reduceOnly?: boolean;
+  orderExecutionType: OrderExecutionType;
+  /**
+   * Specify the type of trigger that will be used for the order if the order will be sent to the trigger service.
+   */
+  triggerType?: OrderAppendixTriggerType;
+  /**
+   * Specify if the order is for an isolated position
+   * An order CANNOT be both a TWAP order and an isolated order.
+   */
+  isolated?: OrderAppendixIsolatedFields;
+  /**
+   * Specify if the order is a TWAP order
+   * An order CANNOT be both a TWAP order and an isolated order.
+   */
+  twap?: OrderAppendixTWAPFields;
+}

package/src/types/productTypes.ts

@@ -0,0 +1,76 @@
+import { BigDecimal } from '../utils/math';
+
+/**
+ * Representation of the ProductEngineType enum used within the contract
+ * Enums do not get reflected in the ABI, so this must be manually defined
+ */
+export enum ProductEngineType {
+  SPOT,
+  PERP,
+}
+
+/**
+ * Maps a raw ProductEngineType enum value to the proper type
+ * @param val
+ */
+export function toProductEngineType(val: number): ProductEngineType {
+  switch (val) {
+    case 0:
+      return ProductEngineType.SPOT;
+    case 1:
+      return ProductEngineType.PERP;
+    default:
+      throw new Error(`Unknown product engine type: ${val}`);
+  }
+}
+
+/**
+ * Shared properties across products
+ */
+interface BaseProduct {
+  type: ProductEngineType;
+  productId: number;
+  // Latest price given by oracle
+  oraclePrice: BigDecimal;
+  // Weight used to calculate initial health for a long position
+  longWeightInitial: BigDecimal;
+  // Weight used to calculate initial health for a short position
+  shortWeightInitial: BigDecimal;
+  // Weight used to calculate maint. health for a long position
+  longWeightMaintenance: BigDecimal;
+  // Weight used to calculate maint. health for a short position
+  shortWeightMaintenance: BigDecimal;
+}
+
+/**
+ * Represents a product stored in PerpEngine
+ */
+export interface PerpProduct extends BaseProduct {
+  type: ProductEngineType.PERP;
+  // Current open interest
+  openInterest: BigDecimal;
+  cumulativeFundingLong: BigDecimal;
+  cumulativeFundingShort: BigDecimal;
+}
+
+/**
+ * Represents a product stored in SpotEngine.
+ *
+ * @see {@link calcBorrowRatePerSecond} for more details on the calculation and interest parameters
+ */
+export interface SpotProduct extends BaseProduct {
+  type: ProductEngineType.SPOT;
+  tokenAddr: string;
+  interestFloor: BigDecimal;
+  interestInflectionUtil: BigDecimal;
+  interestSmallCap: BigDecimal;
+  interestLargeCap: BigDecimal;
+  minDepositRate: BigDecimal;
+
+  // Total deposited for this product
+  totalDeposited: BigDecimal;
+  // Total borrowed for this product
+  totalBorrowed: BigDecimal;
+}
+
+export type Product = PerpProduct | SpotProduct;

package/src/types/subaccountTypes.ts

@@ -0,0 +1,13 @@
+import { Bytes } from './bytes';
+
+export type SubaccountBytes32 = Bytes;
+
+export type SubaccountNameBytes12 = Bytes;
+
+export interface Subaccount {
+  subaccountOwner: string;
+  /**
+   * If the subaccount is not a valid UTF-8 string, it will be the hex representation of the bytes
+   */
+  subaccountName: string;
+}

package/src/types/viemTypes.ts

@@ -0,0 +1,42 @@
+import {
+  Abi,
+  Account,
+  Chain,
+  GetContractReturnType,
+  PublicClient,
+  RpcSchema,
+  Transport,
+  WalletClient,
+} from 'viem';
+
+/**
+ * An account with its corresponding private key. Viem does not allow private keys to be accessible from an account
+ */
+export interface AccountWithPrivateKey {
+  account: Account;
+  privateKey: string;
+}
+
+/**
+ * A viem WalletClient that is fully initialized with a Transport, Chain, Account, and RpcSchema
+ */
+export type WalletClientWithAccount = WalletClient<
+  Transport,
+  Chain,
+  Account,
+  RpcSchema
+>;
+
+/**
+ * A viem contract instance that has a connected WalletClient, thus allowing write operations
+ */
+export type WriteableContractInstance<TAbi extends Abi = Abi> =
+  GetContractReturnType<TAbi, WalletClientWithAccount>;
+
+/**
+ * A viem contract instance that has a connected WalletClient or PublicClient
+ */
+export type ContractInstance<TAbi extends Abi = Abi> = GetContractReturnType<
+  TAbi,
+  WalletClient | PublicClient
+>;

package/src/utils/asyncResult.ts

@@ -0,0 +1,12 @@
+export type AsyncResult<TData, TError> =
+  | [data: undefined, error: TError]
+  | [data: TData, error: undefined];
+
+export function asyncResult<TData, TError = unknown>(
+  promise: Promise<TData>,
+): Promise<AsyncResult<TData, TError>> {
+  return Promise.resolve(promise).then(
+    (data) => [data, undefined] as [TData, undefined],
+    (error) => [undefined, error] as [undefined, TError],
+  );
+}

package/src/utils/balanceValue.ts

@@ -0,0 +1,42 @@
+import {
+  PerpBalanceWithProduct,
+  SpotBalanceWithProduct,
+} from '../types/balanceTypes';
+import { BigDecimal } from './math';
+
+/**
+ * Calculates the quote value of a spot balance, in terms of quote units
+ *
+ * @param balanceWithProduct
+ */
+export function calcSpotBalanceValue(
+  balanceWithProduct: SpotBalanceWithProduct,
+): BigDecimal {
+  return balanceWithProduct.amount.multipliedBy(balanceWithProduct.oraclePrice);
+}
+
+/**
+ * Calculates the notional value of a perp balance, in terms of quote units
+ *
+ * @param balanceWithProduct
+ */
+export function calcPerpBalanceNotionalValue(
+  balanceWithProduct: PerpBalanceWithProduct,
+): BigDecimal {
+  return balanceWithProduct.amount
+    .multipliedBy(balanceWithProduct.oraclePrice)
+    .abs();
+}
+
+/**
+ * Calculates the true quote value of a perp balance, which is the same as its unrealized pnl / unsettled quote, in terms of quote units
+ *
+ * @param balanceWithProduct
+ */
+export function calcPerpBalanceValue(
+  balanceWithProduct: PerpBalanceWithProduct,
+): BigDecimal {
+  return balanceWithProduct.amount
+    .multipliedBy(balanceWithProduct.oraclePrice)
+    .plus(balanceWithProduct.vQuoteBalance);
+}

package/src/utils/bytes32.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from '@jest/globals';
+import { Subaccount } from '../types/subaccountTypes';
+import {
+  subaccountFromBytes32,
+  subaccountFromHex,
+  subaccountNameBytesToStr,
+  subaccountNameToBytes12,
+  subaccountToBytes32,
+  subaccountToHex,
+} from './bytes32';
+
+const TEST_ADDRESS = '0xb92EFcF519EDC2f1FE60b4491Ef51d97Ed4d7685';
+
+describe('bytes32', () => {
+  it('converts a subaccount to bytes', () => {
+    const expectedBytes = new Uint8Array([
+      185, 46, 252, 245, 25, 237, 194, 241, 254, 96, 180, 73, 30, 245, 29, 151,
+      237, 77, 118, 133, 116, 101, 115, 116, 0, 0, 0, 0, 0, 0, 0, 0,
+    ]);
+    expect(
+      subaccountToBytes32({
+        subaccountName: 'test',
+        subaccountOwner: TEST_ADDRESS,
+      }),
+    ).toStrictEqual(expectedBytes);
+  });
+
+  it('converts bytes to a subaccount', () => {
+    const subaccountBytes = new Uint8Array([
+      185, 46, 252, 245, 25, 237, 194, 241, 254, 96, 180, 73, 30, 245, 29, 151,
+      237, 77, 118, 133, 116, 101, 115, 116, 0, 0, 0, 0, 0, 0, 0, 0,
+    ]);
+    const expectedSubaccount: Subaccount = {
+      subaccountOwner: TEST_ADDRESS,
+      subaccountName: 'test',
+    };
+    const convertedSubaccount = subaccountFromBytes32(subaccountBytes);
+
+    expect(convertedSubaccount.subaccountOwner.toLowerCase()).toBe(
+      expectedSubaccount.subaccountOwner.toLowerCase(),
+    );
+    expect(convertedSubaccount.subaccountName).toBe(
+      expectedSubaccount.subaccountName,
+    );
+  });
+
+  it('converts a string subaccount name to bytes', () => {
+    const nameBytes = subaccountNameToBytes12('test');
+
+    expect(nameBytes).toStrictEqual(
+      new Uint8Array([116, 101, 115, 116, 0, 0, 0, 0, 0, 0, 0, 0]),
+    );
+  });
+
+  it('converts a hex string subaccount name to bytes', () => {
+    // `test` in hex form
+    const nameBytes = subaccountNameToBytes12('0x74657374');
+
+    expect(nameBytes).toStrictEqual(
+      new Uint8Array([116, 101, 115, 116, 0, 0, 0, 0, 0, 0, 0, 0]),
+    );
+  });
+
+  it('converts a subaccount with a string subaccount name to a hex string', () => {
+    const subaccount: Subaccount = {
+      subaccountOwner: TEST_ADDRESS,
+      subaccountName: 'test',
+    };
+
+    expect(subaccountToHex(subaccount)).toBe(
+      '0xb92efcf519edc2f1fe60b4491ef51d97ed4d7685746573740000000000000000',
+    );
+  });
+
+  it('converts a subaccount with a hex subaccount name to a hex string', () => {
+    const subaccount: Subaccount = {
+      subaccountOwner: TEST_ADDRESS,
+      // `test` in hex form
+      subaccountName: '0x74657374',
+    };
+
+    expect(subaccountToHex(subaccount)).toBe(
+      '0xb92efcf519edc2f1fe60b4491ef51d97ed4d7685746573740000000000000000',
+    );
+  });
+
+  it('converts a hex string to a subaccount', () => {
+    const convertedSubaccount = subaccountFromHex(
+      '0xb92efcf519edc2f1fe60b4491ef51d97ed4d7685746573740000000000000000',
+    );
+
+    expect(convertedSubaccount.subaccountOwner.toLowerCase()).toBe(
+      TEST_ADDRESS.toLowerCase(),
+    );
+    expect(convertedSubaccount.subaccountName).toBe('test');
+  });
+
+  it('handles leading zero bytes in subaccount name properly', () => {
+    const subaccount: Subaccount = {
+      subaccountOwner: TEST_ADDRESS,
+      subaccountName: '\u0000\u0000\u0002\u0000iso\u0000',
+    };
+    const subaccountHex =
+      '0xb92efcf519edc2f1fe60b4491ef51d97ed4d76850000020069736f0000000000';
+
+    expect(subaccountToHex(subaccount)).toBe(subaccountHex);
+    // Trailing 0 bytes are trimmed
+    expect(subaccountFromHex(subaccountHex).subaccountName).toBe(
+      '\u0000\u0000\u0002\u0000iso',
+    );
+  });
+
+  it('handles converting non-utf8 byte sequences by converting bytes to a hex string', () => {
+    const invalidUtf8Array = new Uint8Array([0x80, 0x81, 0x82]);
+    expect(subaccountNameBytesToStr(invalidUtf8Array)).toBe('0x808182');
+  });
+});

package/src/utils/bytes32.ts

@@ -0,0 +1,110 @@
+import { bytesToString, Hex, toBytes, toHex } from 'viem';
+import { Bytes } from '../types/bytes';
+import {
+  Subaccount,
+  SubaccountBytes32,
+  SubaccountNameBytes12,
+} from '../types/subaccountTypes';
+
+/**
+ * Converts a subaccount object (owner + name) to its bytes32 representation.
+ * @param subaccount subaccount object (owner + name)
+ * @returns bytes32 representation of a subaccount
+ */
+export function subaccountToBytes32(subaccount: Subaccount): SubaccountBytes32 {
+  const address = toBytes(subaccount.subaccountOwner);
+
+  if (address.length != 20) {
+    throw new Error(`owner must be 20 bytes, but found ${address.length}`);
+  }
+
+  const nameBytes = subaccountNameToBytes12(subaccount.subaccountName);
+
+  const bytes32 = new Uint8Array(32);
+  for (let i = 0; i < address.length; i++) {
+    bytes32[i] = address[i];
+  }
+  for (let i = 0; i < nameBytes.length; i++) {
+    bytes32[i + 20] = nameBytes[i];
+  }
+
+  return bytes32;
+}
+
+/**
+ * Given a bytes32 representation of a subaccount, returns a subaccount object (owner + name)
+ * @param bytes bytes32 representaion of a subaccount where bytes[0:20]=owner & bytes[20:32]=subaccountName
+ * @returns subaccount object (owner + name)
+ */
+export function subaccountFromBytes32(bytes: SubaccountBytes32): Subaccount {
+  if (bytes.length != 32) {
+    throw new Error('input must be 32 bytes');
+  }
+
+  const address = new Uint8Array(20);
+  const name = new Uint8Array(12);
+
+  for (let i = 0; i < bytes.length; i++) {
+    if (i < 20) {
+      address[i] = bytes[i];
+    } else {
+      name[i - 20] = bytes[i];
+    }
+  }
+
+  return {
+    subaccountOwner: toHex(address),
+    subaccountName: subaccountNameBytesToStr(name),
+  };
+}
+
+/**
+ * When interacting with the contracts (e.g: deposit collateral);
+ * subaccount name is represented as bytes12.
+ * This util converts a subaccount name to it's bytes12 representation.
+ * @param name subaccount name
+ * @returns bytes12 representation of a subaccount name.
+ */
+export function subaccountNameToBytes12(name: string): SubaccountNameBytes12 {
+  return toBytes(name, {
+    size: 12,
+  });
+}
+
+/**
+ * When interacting with the engine, we need to send a hex string representation
+ * of the bytes32 of a subaccount for serialization reasons. This util
+ * converts a subaccount object (owner + name) to such hex representation.
+ * @param subaccount subaccount object (owner + name)
+ * @returns hex string representation of a subaccount
+ */
+export function subaccountToHex(subaccount: Subaccount): Hex {
+  return toHex(subaccountToBytes32(subaccount));
+}
+
+/**
+ * Converts a hex string representation of a bytes32 subaccount to a subaccount object (owner + name)
+ * @param subaccount hex string representation of a bytes32 subaccount.
+ * @returns subaccount object (owner + name)
+ */
+export function subaccountFromHex(subaccount: string): Subaccount {
+  return subaccountFromBytes32(toBytes(subaccount));
+}
+
+/**
+ * Converts Bytes to a string. If the bytes represent a valid UTF-8 string, then a string is returned, if not,
+ * then the hex representation is returned.
+ *
+ * @param input
+ */
+export function subaccountNameBytesToStr(input: Bytes): string {
+  // bytesToString will replace zero bytes with \0
+  // strip out any trailing bytes for a readable name
+  // however, we need to leave any leading bytes otherwise reverse conversion to bytes will not work
+  const toStringResult = bytesToString(input).replace(/\0*$/, '');
+  // bytesToString will replace invalid byte sequences with �, so default to converting to hex string if � is present
+  if (toStringResult.includes('�')) {
+    return toHex(input);
+  }
+  return toStringResult;
+}

package/src/utils/createDeterministicLinkedSignerPrivateKey.ts

@@ -0,0 +1,46 @@
+import { keccak256 } from 'viem';
+import { Subaccount } from '../types/subaccountTypes';
+import { WalletClientWithAccount } from '../types/viemTypes';
+import { getNadoEIP712Domain } from '../eip712/getNadoEIP712Domain';
+import { subaccountToHex } from './bytes32';
+
+interface Params extends Subaccount {
+  walletClient: WalletClientWithAccount;
+  chainId: number;
+  endpointAddress: string;
+}
+
+/**
+ * Deterministically creates a new private key from a predetermined EIP712 message. This is used to
+ * reliably create an authorized signer delegate for the subaccount across different clients. Used on the FE in order
+ * to have a consistent private key for the subaccount linked signer across different clients.
+ *
+ * @param params
+ */
+export async function createDeterministicLinkedSignerPrivateKey(
+  params: Params,
+) {
+  const {
+    chainId,
+    endpointAddress,
+    walletClient,
+    subaccountName,
+    subaccountOwner,
+  } = params;
+
+  const signedMessage = await walletClient.signTypedData({
+    domain: getNadoEIP712Domain(endpointAddress, chainId),
+    types: {
+      CreateLinkedSignerWallet: [{ name: 'subaccount', type: 'bytes32' }],
+    },
+    primaryType: 'CreateLinkedSignerWallet',
+    message: {
+      subaccount: subaccountToHex({
+        subaccountOwner,
+        subaccountName,
+      }),
+    },
+  });
+
+  return keccak256(signedMessage);
+}

package/src/utils/errors/WalletNotProvidedError.ts

@@ -0,0 +1,6 @@
+export class WalletNotProvidedError extends Error {
+  constructor() {
+    super('Wallet client not provided');
+    this.name = 'WalletNotProvidedError';
+  }
+}

package/src/utils/errors/index.ts

@@ -0,0 +1 @@
+export * from './WalletNotProvidedError';

package/src/utils/getValidatedAddress.ts

@@ -0,0 +1,13 @@
+import { Address, isAddress } from 'viem';
+
+/**
+ * Check if the given string is a valid address. Throws an error if not.
+ * @param maybeAddress
+ */
+export function getValidatedAddress(maybeAddress: string): Address {
+  if (!isAddress(maybeAddress)) {
+    throw new Error(`Invalid address: ${maybeAddress}`);
+  }
+
+  return maybeAddress;
+}

package/src/utils/getValidatedHex.ts

@@ -0,0 +1,13 @@
+import { Hex, isHex } from 'viem';
+
+/**
+ * Check if the given string is a valid hex string. Throws an error if not.
+ * @param maybeHex
+ */
+export function getValidatedHex(maybeHex: string): Hex {
+  if (!isHex(maybeHex)) {
+    throw new Error(`Invalid hex string: ${maybeHex}`);
+  }
+
+  return maybeHex;
+}

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+export * from './orders';
+export * from './interest';
+export * from './productTypeFilter';
+export * from './balanceValue';
+export * from './bytes32';
+export * from './createDeterministicLinkedSignerPrivateKey';
+export * from './isWriteableContract';
+export * from './errors';
+export * from './math';
+export * from './asyncResult';
+export * from './getValidatedAddress';
+export * from './getValidatedHex';
+export * from './mapValues';
+export * from './time';
+export * from './toPrintableObject';