@n1xyz/nord-ts 0.0.1

package/src/types.ts

@@ -0,0 +1,393 @@
+import * as proto from "./gen/nord";
+
+/**
+ * The peak TPS rate is queried over the specified period.
+ * The period is specified in units of: {hour, day, week, month, year}.
+ * Example inputs:
+ *  1. AggregateMetrics.txPeakTpsPeriod = 3,
+ *     AggregateMetrics.txPeakTpsPeriodUnit = "d" => Peak TPS over last 3 days.
+ *  1. AggregateMetrics.txPeakTpsPeriod = 1,
+ *     AggregateMetrics.txPeakTpsPeriodUnit = "w" => Peak TPS over last week.
+ */
+export enum PeakTpsPeriodUnit {
+  Hour = "h",
+  Day = "d",
+  Week = "w",
+  Month = "m",
+  Year = "y",
+}
+
+export interface NordConfig {
+  evmUrl: string;
+  webServerUrl: string;
+  contractAddress: string;
+  tokenInfos: ERC20TokenInfo[];
+}
+
+export interface ERC20TokenInfo {
+  address: string;
+  precision: number;
+  tokenId: number;
+  name: string;
+}
+
+export interface Order {
+  orderId: number;
+  isLong: boolean;
+  size: number;
+  price: number;
+  marketId: number;
+}
+
+export enum KeyType {
+  Ed25519,
+  Secp256k1,
+  Bls12_381,
+}
+
+export enum Side {
+  Ask,
+  Bid,
+}
+
+export enum FillMode {
+  Limit,
+  PostOnly,
+  ImmediateOrCancel,
+  FillOrKill,
+}
+
+export interface SubscriberConfig {
+  streamURL: string;
+  maxBufferLen?: number;
+}
+
+export interface Market {
+  symbol: string;
+  baseTokenId: number;
+  quoteTokenId: number;
+  priceDecimals: number;
+  sizeDecimals: number;
+}
+
+export interface Token {
+  symbol: string;
+  ethAddr: string;
+  decimals: number;
+  tokenId: number;
+}
+
+export interface Info {
+  markets: Market[];
+  tokens: Token[];
+}
+
+export interface DeltaEvent {
+  last_update_id: number;
+  update_id: number;
+  market_symbol: string;
+  asks: [number, number];
+  bids: [number, number];
+}
+
+export interface Trade {
+  side: Side;
+  price: number;
+  size: number;
+  order_id: number;
+}
+
+export interface Trades {
+  last_update_id: number;
+  update_id: number;
+  market_symbol: string;
+  trades: Trade[];
+}
+
+export interface OrderInfo {
+  id: number;
+  reduce_only: boolean;
+  imit_price: number;
+  size: number;
+  account_id: number;
+}
+
+interface HashMap<T> {
+  [key: number]: T;
+}
+
+export interface Account {
+  last_update_id: number;
+  update_id: number;
+  account_id: number;
+  fills: HashMap<FillMode>;
+  places: HashMap<OrderInfo>;
+  cancels: HashMap<OrderInfo>;
+  balances: HashMap<number>;
+}
+
+/**
+ * Query the transactions in the specified L2 block.
+ * @field {number} block_number specifies the block number to query.
+ *                 If not specified, transactions from latest block
+ *                 are returned.
+ */
+export interface BlockQuery {
+  block_number?: number;
+}
+
+/**
+ * Response for BlockQuery.
+ * @field {number} block_number specifies the block number being returned.
+ * @field {BlockActions} actions are the list of transactions from the block.
+ */
+export interface BlockResponse {
+  block_number: number;
+  actions: ActionInfo[];
+}
+
+/**
+ * Response for BlockSummaryQuery.
+ * @field {BlockSummary} block_summary is the summary of upto the last N blocks.
+ *                       The server can return fewer than last_n block summary if
+ *                       fewer blocks are available or if it exceeds a max cap.
+ */
+export interface BlockSummaryResponse {
+  block_summary: BlockSummary[];
+}
+
+/**
+ * Query the action for the specified action id.
+ * @field {number} action_id specifies the action to query.
+ */
+export interface ActionQuery {
+  action_id: number;
+}
+
+/**
+ * Response for ActionQuery.
+ * @field {number} block_number the block the action is part of.
+ *                 If the action is not yet included in any block,
+ *                 null is returned.
+ * @field {Action} the transaction.
+ */
+export interface ActionResponse {
+  block_number?: number;
+  action: proto.Action;
+}
+
+/**
+ * Query the recent actions
+ * @field {number} last_n requests last N actions.
+ * @field {number} action_id specifies the action to query.
+ */
+export interface ActionsQuery {
+  last_n: number;
+}
+
+/**
+ * Response for ActionsQuery.
+ * @field {ActionsExtendedInfo} actions returns upto the last N actions.
+ *                       The server can return fewer than last_n actions if
+ *                       fewer actions are available or if it exceeds a max cap.
+ */
+export interface ActionsResponse {
+  actions: ActionsExtendedInfo[];
+}
+
+/**
+ * Block summary.
+ * @field {number} block_number Block number.
+ * @field {Action} from First action_id in the block.
+ * @field {Action} to Last action_id in the block.
+ */
+export interface BlockSummary {
+  block_number: number;
+  from_action_id: number;
+  to_action_id: number;
+}
+
+/**
+ * Info about the block transaction.
+ * @field {number} action_id is the action identifier.
+ * @field {Action} action in protobuf format.
+ * @field {number} exec_timestamp is the execution timestamp.
+ */
+export interface ActionInfo {
+  action_id: number;
+  action: proto.Action;
+  exec_timestamp: number;
+}
+
+/**
+ * Extended info about the block transaction.
+ * @field {number} block_number the block the action is part of.
+ *                 If the action is not yet included in any block,
+ *                 null is returned.
+ * @field {number} action_id of the action.
+ * @field {Action} action the transaction.
+ */
+export interface ActionsExtendedInfo {
+  block_number?: number;
+  action_id: number;
+  action: proto.Action;
+}
+
+/**
+ * Aggregate metrics
+ * @field {number} blocks_total: Total number of L2 blocks.
+ * @field {number} tx_total: Total number of transactions.
+ * @field {number} tx_tps: Transaction throughput.
+ * @field {number} tx_tps_peak: Peak transaction throughput.
+ * @field {number} request_latency_average: Average request latency.
+ */
+export interface AggregateMetrics {
+  blocks_total: number;
+  tx_total: number;
+  tx_tps: number;
+  tx_tps_peak: number;
+  request_latency_average: number;
+}
+
+/**
+ * Parameters for querying trades
+ * @field {number} accountId - ID of target account
+ * @field {string} [since] - Start with this timestamp (RFC3339); defaults to UNIX epoch start
+ * @field {string} [until] - End with this timestamp (RFC3339); defaults to current date-time
+ * @field {string} [pageId] - Fetch results starting with this page
+ */
+export interface TradesQueryParams {
+  accountId: number;
+  since?: string;
+  until?: string;
+  pageId?: string;
+}
+
+/**
+ * Trade information
+ * @field {string} id - Trade ID
+ * @field {string} timestamp - Trade timestamp (RFC3339)
+ * @field {string} symbol - Market symbol
+ * @field {string} side - Trade side (buy/sell)
+ * @field {number} price - Trade price
+ * @field {number} size - Trade size
+ * @field {number} fee - Trade fee
+ * @field {string} feeCurrency - Fee currency
+ * @field {number} orderId - Order ID
+ */
+export interface TradeInfo {
+  id: string;
+  timestamp: string;
+  symbol: string;
+  side: string;
+  price: number;
+  size: number;
+  fee: number;
+  feeCurrency: string;
+  orderId: number;
+}
+
+/**
+ * Response for trades query
+ * @field {number} accountId - Account ID
+ * @field {string} since - Start timestamp (RFC3339)
+ * @field {string} until - End timestamp (RFC3339)
+ * @field {string} [nextPageId] - ID for the next page of results
+ * @field {TradeInfo[]} trades - Array of trades
+ */
+export interface TradesResponse {
+  accountId: number;
+  since: string;
+  until: string;
+  nextPageId?: string;
+  trades: TradeInfo[];
+}
+
+/**
+ * Order in the orderbook
+ * @field {number} price - Order price
+ * @field {number} size - Order size
+ */
+export interface OrderbookOrder {
+  price: number;
+  size: number;
+}
+
+/**
+ * Response for orderbook query
+ * @field {string} symbol - Market symbol
+ * @field {number} timestamp - Orderbook timestamp
+ * @field {OrderbookOrder[]} bids - Array of bid orders
+ * @field {OrderbookOrder[]} asks - Array of ask orders
+ */
+export interface OrderbookResponse {
+  symbol: string;
+  timestamp: number;
+  bids: OrderbookOrder[];
+  asks: OrderbookOrder[];
+}
+
+// The JSON types returned by rollman, that need to be translated to TS format.
+export interface RollmanBlockResponse {
+  block_number: number;
+  actions: RollmanActionInfo[];
+}
+
+export interface RollmanActionResponse {
+  block_number?: number;
+  action_pb: Uint8Array;
+  exec_timestamp: number;
+}
+
+export interface RollmanActionsResponse {
+  actions: RollmanActionExtendedInfo[];
+}
+
+export interface RollmanActionInfo {
+  action_id: number;
+  action_pb: Uint8Array;
+  exec_timestamp: number;
+}
+
+export interface RollmanActionExtendedInfo {
+  block_number?: number;
+  action_id: number;
+  action_pb: Uint8Array;
+}
+
+export interface MarketsStatsResponse {
+  markets: MarketStats[];
+}
+
+export interface MarketStats {
+  market_id: number;
+  index_price: [number, number];
+  volume_24h: number;
+  high_24h: number;
+  low_24h: number;
+  perp_stats?: PerpMarketStats;
+}
+
+export interface PerpMarketStats {
+  mark_price?: number;
+  funding_rate?: number;
+  next_funding_time?: Date;
+  open_interest?: number;
+}
+
+/**
+ * Converts a `FillMode` enum to its corresponding protobuf representation.
+ *
+ * @param x - The fill mode to convert.
+ * @returns The corresponding protobuf fill mode.
+ * @throws Will throw an error if provided with an invalid fill mode.
+ */
+export function fillModeToProtoFillMode(x: FillMode): proto.FillMode {
+  if (x === FillMode.Limit) return proto.FillMode.LIMIT;
+  if (x === FillMode.PostOnly) return proto.FillMode.POST_ONLY;
+  if (x === FillMode.ImmediateOrCancel) {
+    return proto.FillMode.IMMEDIATE_OR_CANCEL;
+  }
+  if (x === FillMode.FillOrKill) return proto.FillMode.FILL_OR_KILL;
+  throw new Error("Invalid fill mode");
+}

package/src/utils.ts

@@ -0,0 +1,300 @@
+import { Decimal } from "decimal.js";
+import { ed25519 } from "@noble/curves/ed25519";
+import { bls12_381 as bls } from "@noble/curves/bls12-381";
+import { secp256k1 as secp } from "@noble/curves/secp256k1";
+import { sha256 } from "@noble/hashes/sha256";
+import { KeyType, type Market, type Token } from "./types";
+import * as proto from "./gen/nord";
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+import { ethers } from "ethers";
+import fetch from "node-fetch";
+import { RequestInfo, RequestInit, Response } from "node-fetch";
+
+export const SESSION_TTL: bigint = 10n * 60n * 1000n * 10000n;
+export const ZERO_DECIMAL = new Decimal(0);
+export const MAX_BUFFER_LEN = 10_000;
+
+const MAX_PAYLOAD_SIZE = 100 * 1024; // 100 kB
+
+/** Any type convertible to bigint */
+export type BigIntValue = bigint | number | string;
+
+export function panic(message: string): never {
+  throw new Error(message);
+}
+
+export function assert(predicate: boolean, message?: string): void {
+  if (!predicate) panic(message ?? "Assertion violated");
+}
+/**
+ * Extracts value out of optional if it's defined, or throws error if it's not
+ * @param value   Optional value to unwrap
+ * @param message Error message
+ * @returns       Unwrapped value
+ */
+export function optExpect<T>(value: T | undefined, message: string): T {
+  if (value === undefined) throw new Error(message);
+  return value as T;
+}
+/**
+ * Unwraps optional value with default error message
+ * @param value
+ * @returns
+ */
+export function optUnwrap<T>(value: T | undefined): T {
+  return optExpect(value, "Optional contains no value");
+}
+/**
+ * Applies function to value if it's defined, or passes `undefined` through
+ * @param value Optional value to map
+ * @param mapFn Mapper function
+ * @returns     Either mapped value or undefined
+ */
+export function optMap<T, U>(
+  value: T | undefined,
+  mapFn: (arg: T) => U,
+): U | undefined {
+  return value !== undefined ? mapFn(value) : undefined;
+}
+/** Behaves same as `node-fetch/fetch` but throws if response is a failure
+ *
+ * @param url   Request HTTP URL
+ * @param init  Request parameters
+ * @returns     Raw response if fetch succeeded
+ * @throws      If response wasn't Ok
+ */
+export async function checkedFetch(
+  url: RequestInfo,
+  init?: RequestInit,
+): Promise<Response> {
+  const resp = await fetch(url, init);
+  assert(resp.ok, `Request failed with ${resp.status}: ${resp.statusText}`);
+  return resp;
+}
+
+/**
+ * Signs an action using the specified secret key and key type.
+ * @param action - The action data to be signed.
+ * @param sk - Secret key used for signing the action.
+ * @param keyType - Type of the key used for signing.
+ * @returns A new Uint8Array containing the action followed by its signature.
+ */
+export function signAction(
+  action: Uint8Array,
+  sk: Uint8Array,
+  keyType: KeyType,
+): Uint8Array {
+  let sig: Uint8Array;
+  if (keyType === KeyType.Ed25519) {
+    sig = ed25519.sign(action, sk);
+  } else if (keyType === KeyType.Bls12_381) {
+    sig = bls.sign(action, sk);
+  } else if (keyType === KeyType.Secp256k1) {
+    sig = secp.sign(sha256(action), sk).toCompactRawBytes();
+  } else {
+    throw new Error("Invalid key type");
+  }
+  return new Uint8Array([...action, ...sig]);
+}
+
+/**
+ * Constructs wallet signing function, usable with `NordUser` type
+ *
+ * @param walletKey   Either raw signing key as bytes array or hex string prefixed with `"0x"`
+ * @returns           Async function which accepts arbitrary message, generates its digets,
+ *                    then signs it with provided user wallet key and returns signature
+ *                    as hex string prefixed with `"0x"`
+ */
+export function makeWalletSignFn(
+  walletKey: ethers.BytesLike,
+): (message: Uint8Array | string) => Promise<string> {
+  const signingKey = new ethers.SigningKey(walletKey);
+  return async (message) =>
+    signingKey.sign(ethers.hashMessage(message)).serialized;
+}
+
+function makeToScaledBigUint(params: {
+  precision: number;
+  exponent: number;
+  bits: number;
+}): (x: Decimal.Value, decimals: number) => bigint {
+  const Dec = Decimal.clone({
+    precision: params.precision,
+    toExpPos: params.exponent,
+    toExpNeg: -params.exponent,
+  });
+
+  const Ten = new Dec(10);
+
+  const Max = new Dec(((1n << BigInt(params.bits)) - 1n).toString());
+
+  return (x, decimals) => {
+    const dec = new Dec(x);
+
+    if (dec.isZero()) {
+      return 0n;
+    }
+
+    if (dec.isNeg()) {
+      throw new Error(`Number is negative`);
+    }
+
+    const scaled = Ten.pow(decimals).mul(dec).truncated();
+    if (scaled.isZero()) {
+      throw new Error(
+        `Precision loss when converting ${dec} to scaled integer`,
+      );
+    }
+
+    if (scaled.greaterThan(Max)) {
+      throw new Error(
+        `Integer is out of range: ${scaled} exceeds limit ${Max}`,
+      );
+    }
+
+    return BigInt(scaled.toString());
+  };
+}
+/**
+ * Converts decimal value into rescaled 64-bit unsigned integer
+ * by scaling it up by specified number of decimal digits.
+ *
+ * Ensures that number won't accidentally become zero
+ * or exceed U64's value range
+ *
+ * @param x         Decimal value to rescale
+ * @param decimals  Number of decimal digits
+ * @returns         Rescaled unsigned integer
+ */
+export const toScaledU64 = makeToScaledBigUint({
+  bits: 64,
+  precision: 20,
+  exponent: 28,
+});
+/**
+ * Converts decimal value into rescaled 128-bit unsigned integer
+ * by scaling it up by specified number of decimal digits.
+ *
+ * Ensures that number won't accidentally become zero
+ * or exceed U128's value range
+ *
+ * @param x         Decimal value to rescale
+ * @param decimals  Number of decimal digits
+ * @returns         Rescaled unsigned integer
+ */
+export const toScaledU128 = makeToScaledBigUint({
+  bits: 128,
+  precision: 40,
+  exponent: 56,
+});
+
+const U64_MAX = (1n << 64n) - 1n;
+const U128_MAX = (1n << 128n) - 1n;
+/**
+ * Converts U128 into pair of U64 numbers, to pass it through protobuf
+ * @param value integer, must fit U128 limits
+ * @returns     Pair of U64 integers which represent original number split in two
+ */
+export function bigIntToProtoU128(value: bigint): proto.U128 {
+  if (value < 0n) {
+    throw new Error(`Negative number (${value})`);
+  }
+
+  if (value > U128_MAX) {
+    throw new Error(`U128 overflow (${value})`);
+  }
+
+  return {
+    lo: value & U64_MAX,
+    hi: (value >> 64n) & U64_MAX,
+  };
+}
+
+/**
+ * Encodes any protobuf message into a length-delimited format,
+ * i.e. prefixed with its length encoded as varint
+ * @param   message message object
+ * @param   coder   associated coder object which implements `MessageFns` interface
+ * @returns         Encoded message as Uint8Array, prefixed with its length
+ */
+export function encodeLengthDelimited<T, M extends proto.MessageFns<T>>(
+  message: T,
+  coder: M,
+): Uint8Array {
+  const encoded = coder.encode(message).finish();
+  if (encoded.byteLength > MAX_PAYLOAD_SIZE) {
+    throw new Error(
+      `Encoded message size (${encoded.byteLength} bytes) is greater than max payload size (${MAX_PAYLOAD_SIZE} bytes).`,
+    );
+  }
+  const encodedLength = new BinaryWriter().uint32(encoded.byteLength).finish();
+  return new Uint8Array([...encodedLength, ...encoded]);
+}
+
+/**
+ * Decodes any protobuf message from a length-delimited format,
+ * i.e. prefixed with its length encoded as varint
+ *
+ * NB: Please note that due to limitations of Typescript type inference
+ * it requires to specify variable type explicitly:
+ *
+ * ```
+ * const foo: proto.Bar = decodeLengthDelimited(bytes, proto.Bar);
+ * ```
+ *
+ * @param   bytes Byte array with encoded message
+ * @param   coder associated coder object which implements `MessageFns` interface
+ * @returns       Decoded Action as Uint8Array.
+ */
+export function decodeLengthDelimited<T, M extends proto.MessageFns<T>>(
+  bytes: Uint8Array,
+  coder: M,
+): T {
+  const lengthReader = new BinaryReader(bytes);
+  const msgLength = lengthReader.uint32();
+  const startsAt = lengthReader.pos;
+
+  if (msgLength > MAX_PAYLOAD_SIZE) {
+    throw new Error(
+      `Encoded message size (${msgLength} bytes) is greater than max payload size (${MAX_PAYLOAD_SIZE} bytes).`,
+    );
+  }
+
+  if (startsAt + msgLength > bytes.byteLength) {
+    throw new Error(
+      `Encoded message size (${msgLength} bytes) is greater than remaining buffer size (${bytes.byteLength - startsAt} bytes).`,
+    );
+  }
+
+  return coder.decode(bytes.slice(startsAt, startsAt + msgLength));
+}
+
+export function checkPubKeyLength(keyType: KeyType, len: number): void {
+  if (keyType === KeyType.Bls12_381) {
+    throw new Error(
+      "Cannot create a user using Bls12_381, use Ed25119 or Secp256k1 instead.",
+    );
+  }
+
+  if (len !== 32 && keyType === KeyType.Ed25519) {
+    throw new Error("Ed25519 pubkeys must be 32 length.");
+  }
+
+  if (len !== 33 && keyType === KeyType.Secp256k1) {
+    throw new Error("Secp256k1 pubkeys must be 33 length.");
+  }
+}
+
+export function findMarket(markets: Market[], marketId: number): Market {
+  if (marketId < 0 || markets.length - 1 < marketId) {
+    throw new Error(`The market with marketId=${marketId} not found`);
+  }
+  return markets[marketId];
+}
+
+export function findToken(tokens: Token[], tokenId: number): Token {
+  if (tokenId < 0 || tokens.length - 1 < tokenId) {
+    throw new Error(`The token with tokenId=${tokenId} not found`);
+  }
+  return tokens[tokenId];
+}