@n1xyz/nord-ts 0.0.1 → 0.0.4

package/src/nord/index.ts

@@ -1,2 +1,16 @@
-export { NordUser } from "./NordUser";
-export { Nord, createWebSocketSubscription, Subscriber } from "./Nord";
+// Export main client classes
+export { Nord } from './client/Nord';
+export { NordUser } from './client/NordUser';
+
+// Export utility classes
+export { NordError } from './utils/NordError';
+
+// Export API modules
+export * from './api/core';
+export * from './api/metrics';
+export * from './api/queries';
+export * from './api/market';
+export * from './api/actions';
+
+// Export models
+export * from './models/Subscriber';

package/src/nord/models/Subscriber.ts

@@ -0,0 +1,57 @@
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import {
+  DeltaEvent,
+  Trades,
+  Account,
+  SubscriberConfig,
+  OrderbookResponse,
+  Trade,
+} from '../../types';
+import { MAX_BUFFER_LEN } from '../../utils';
+
+/**
+ * Subscriber class for handling WebSocket subscriptions
+ */
+export class Subscriber {
+  streamURL: string;
+  buffer: (DeltaEvent | Trades | Account)[];
+  maxBufferLen: number;
+
+  /**
+   * Create a new Subscriber instance
+   * @param config Subscriber configuration
+   */
+  constructor(config: SubscriberConfig) {
+    this.streamURL = config.streamURL;
+    this.buffer = [];
+    this.maxBufferLen = config.maxBufferLen ?? MAX_BUFFER_LEN;
+  }
+
+  /**
+   * Subscribe to WebSocket events
+   */
+  subscribe(): void {
+    const ws = new WebSocket(this.streamURL);
+  }
+}
+
+/**
+ * Interface for orderbook subscription
+ */
+export interface OrderbookSubscription extends EventEmitter {
+  on(event: 'message', listener: (data: OrderbookResponse) => void): this;
+  on(event: 'error', listener: (error: Error) => void): this;
+  close(): void;
+  removeAllListeners(event?: string): this;
+}
+
+/**
+ * Interface for trade subscription
+ */
+export interface TradeSubscription extends EventEmitter {
+  on(event: 'message', listener: (data: Trade[]) => void): this;
+  on(event: 'error', listener: (error: Error) => void): this;
+  close(): void;
+  removeAllListeners(event?: string): this;
+}

package/src/nord/utils/NordError.ts

@@ -0,0 +1,72 @@
+/**
+ * Options for creating a NordError
+ */
+export interface NordErrorOptions {
+  /** The original error that caused this error */
+  cause?: unknown;
+
+  /** HTTP status code (if applicable) */
+  statusCode?: number;
+
+  /** Additional error details */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Custom error class for Nord-related errors
+ */
+export class NordError extends Error {
+  /** The original error that caused this error */
+  public readonly cause?: unknown;
+
+  /** HTTP status code (if applicable) */
+  public readonly statusCode?: number;
+
+  /** Additional error details */
+  public readonly details?: Record<string, unknown>;
+
+  /**
+   * Create a new NordError
+   *
+   * @param message - Error message
+   * @param options - Error options
+   */
+  constructor(message: string, options: NordErrorOptions = {}) {
+    super(message);
+
+    this.name = 'NordError';
+    this.cause = options.cause;
+    this.statusCode = options.statusCode;
+    this.details = options.details;
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, NordError);
+    }
+
+    // Handle nested errors
+    if (this.cause instanceof Error) {
+      this.stack =
+        this.stack + '\nCaused by: ' + (this.cause.stack || this.cause.message);
+    }
+  }
+
+  /**
+   * Convert the error to a string representation
+   *
+   * @returns String representation of the error
+   */
+  toString(): string {
+    let result = `${this.name}: ${this.message}`;
+
+    if (this.statusCode) {
+      result += ` (Status: ${this.statusCode})`;
+    }
+
+    if (this.details && Object.keys(this.details).length > 0) {
+      result += `\nDetails: ${JSON.stringify(this.details, null, 2)}`;
+    }
+
+    return result;
+  }
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-import * as proto from "./gen/nord";
+import * as proto from './gen/nord';
 
 /**
  * The peak TPS rate is queried over the specified period.
@@ -10,21 +10,32 @@ import * as proto from "./gen/nord";
  *     AggregateMetrics.txPeakTpsPeriodUnit = "w" => Peak TPS over last week.
  */
 export enum PeakTpsPeriodUnit {
-  Hour = "h",
-  Day = "d",
-  Week = "w",
-  Month = "m",
-  Year = "y",
+  Hour = 'h',
+  Day = 'd',
+  Week = 'w',
+  Month = 'm',
+  Year = 'y',
 }
 
+/**
+ * Configuration options for the Nord client
+ */
 export interface NordConfig {
-  evmUrl: string;
+  /** Base URL for the Nord web server */
   webServerUrl: string;
-  contractAddress: string;
-  tokenInfos: ERC20TokenInfo[];
-}
-
-export interface ERC20TokenInfo {
+  /** Solana program ID */
+  solanaProgramId: string;
+  /** Solana cluster URL */
+  solanaUrl: string;
+  /** Whether to initialize WebSockets on creation, defaults to true */
+  initWebSockets?: boolean;
+  /** Initial subscriptions for the trades WebSocket (e.g., ["trades@BTCUSDC"]) */
+  tradesSubscriptions?: string[];
+  /** Initial subscriptions for the deltas WebSocket (e.g., ["deltas@BTCUSDC"]) */
+  deltasSubscriptions?: string[];
+}
+
+export interface TokenInfo {
   address: string;
   precision: number;
   tokenId: number;
@@ -63,18 +74,20 @@ export interface SubscriberConfig {
 }
 
 export interface Market {
+  marketId: number;
   symbol: string;
-  baseTokenId: number;
-  quoteTokenId: number;
   priceDecimals: number;
   sizeDecimals: number;
+  baseTokenId: number;
+  quoteTokenId: number;
+  frozen: boolean;
 }
 
 export interface Token {
+  tokenId: number;
   symbol: string;
-  ethAddr: string;
   decimals: number;
-  tokenId: number;
+  mintAddr: string;
 }
 
 export interface Info {
@@ -86,8 +99,8 @@ export interface DeltaEvent {
   last_update_id: number;
   update_id: number;
   market_symbol: string;
-  asks: [number, number];
-  bids: [number, number];
+  asks: OrderbookEntry[];
+  bids: OrderbookEntry[];
 }
 
 export interface Trade {
@@ -107,7 +120,7 @@ export interface Trades {
 export interface OrderInfo {
   id: number;
   reduce_only: boolean;
-  imit_price: number;
+  limit_price: number;
   size: number;
   account_id: number;
 }
@@ -120,7 +133,7 @@ export interface Account {
   last_update_id: number;
   update_id: number;
   account_id: number;
-  fills: HashMap<FillMode>;
+  fills: HashMap<number>;
   places: HashMap<OrderInfo>;
   cancels: HashMap<OrderInfo>;
   balances: HashMap<number>;
@@ -249,84 +262,6 @@ export interface AggregateMetrics {
   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;
@@ -389,5 +324,141 @@ export function fillModeToProtoFillMode(x: FillMode): proto.FillMode {
     return proto.FillMode.IMMEDIATE_OR_CANCEL;
   }
   if (x === FillMode.FillOrKill) return proto.FillMode.FILL_OR_KILL;
-  throw new Error("Invalid fill mode");
+  throw new Error('Invalid fill mode');
+}
+
+/**
+ * Response for trades query with pagination support
+ */
+export interface TradesResponse {
+  trades: Trade[];
+  accountId: number;
+  since?: string; // RFC3339 timestamp
+  until?: string; // RFC3339 timestamp
+  nextPageId?: string;
+}
+
+/**
+ * Query parameters for trades endpoint
+ */
+export interface TradesQuery {
+  accountId: number;
+  since?: string; // RFC3339 timestamp
+  until?: string; // RFC3339 timestamp
+  pageId?: string;
+}
+
+/**
+ * Response for user account IDs query
+ */
+export interface UserAccountIdsResponse {
+  accountIds: number[];
+}
+
+/**
+ * Query parameters for user account IDs
+ */
+export interface UserAccountIdsQuery {
+  pubkey: string; // secp256k1 public key in hex format
+}
+
+/**
+ * Orderbook entry representing price and size
+ */
+export interface OrderbookEntry {
+  price: number;
+  size: number;
+}
+
+/**
+ * Response for orderbook query
+ */
+export interface OrderbookResponse {
+  symbol: string;
+  asks: OrderbookEntry[];
+  bids: OrderbookEntry[];
+  timestamp: number;
+}
+
+/**
+ * Query parameters for orderbook
+ *
+ * Note: While you can provide either symbol or market_id, the API endpoint only accepts market_id.
+ * If you provide a symbol, it will be converted to a market_id internally.
+ */
+export interface OrderbookQuery {
+  symbol?: string;
+  market_id?: number;
+}
+
+/**
+ * Response for timestamp query
+ */
+export interface TimestampResponse {
+  timestamp: number; // engine's current logical timestamp
+}
+
+/**
+ * Response for action nonce query
+ */
+export interface ActionNonceResponse {
+  nonce: number; // next expected action nonce
+}
+
+/**
+ * WebSocket message types
+ */
+export enum WebSocketMessageType {
+  Subscribe = 'subscribe',
+  Unsubscribe = 'unsubscribe',
+  TradeUpdate = 'trade',
+  DeltaUpdate = 'delta',
+  UserUpdate = 'user',
+}
+
+/**
+ * WebSocket subscription request
+ */
+export interface WebSocketSubscription {
+  type: WebSocketMessageType;
+  streams: string[]; // Array of streams to subscribe/unsubscribe (e.g. ["trades@BTCUSDC", "deltas@BTCUSDC"])
 }
+
+/**
+ * WebSocket trade update message
+ */
+export interface WebSocketTradeUpdate {
+  type: WebSocketMessageType.TradeUpdate;
+  symbol: string;
+  trades: Trade[];
+  timestamp: number;
+}
+
+/**
+ * WebSocket delta update message
+ */
+export interface WebSocketDeltaUpdate {
+  type: WebSocketMessageType.DeltaUpdate;
+  last_update_id: number;
+  update_id: number;
+  market_symbol: string;
+  asks: OrderbookEntry[];
+  bids: OrderbookEntry[];
+  timestamp: number;
+}
+
+/**
+ * WebSocket user update message
+ */
+export interface WebSocketUserUpdate {
+  type: WebSocketMessageType.UserUpdate;
+  userId: number;
+  account: Account;
+  timestamp: number;
+}
+
+export type WebSocketMessage =
+  | WebSocketSubscription
+  | WebSocketTradeUpdate
+  | WebSocketDeltaUpdate
+  | WebSocketUserUpdate;

package/src/utils.ts

@@ -1,16 +1,17 @@
-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;
+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';
+import { BN } from '@coral-xyz/anchor';
+
+export const SESSION_TTL: bigint = 60n * 60n * 24n * 30n;
 export const ZERO_DECIMAL = new Decimal(0);
 export const MAX_BUFFER_LEN = 10_000;
 
@@ -24,7 +25,7 @@ export function panic(message: string): never {
 }
 
 export function assert(predicate: boolean, message?: string): void {
-  if (!predicate) panic(message ?? "Assertion violated");
+  if (!predicate) panic(message ?? 'Assertion violated');
 }
 /**
  * Extracts value out of optional if it's defined, or throws error if it's not
@@ -42,7 +43,7 @@ export function optExpect<T>(value: T | undefined, message: string): T {
  * @returns
  */
 export function optUnwrap<T>(value: T | undefined): T {
-  return optExpect(value, "Optional contains no value");
+  return optExpect(value, 'Optional contains no value');
 }
 /**
  * Applies function to value if it's defined, or passes `undefined` through
@@ -92,7 +93,7 @@ export function signAction(
   } else if (keyType === KeyType.Secp256k1) {
     sig = secp.sign(sha256(action), sk).toCompactRawBytes();
   } else {
-    throw new Error("Invalid key type");
+    throw new Error('Invalid key type');
   }
   return new Uint8Array([...action, ...sig]);
 }
@@ -272,16 +273,16 @@ export function decodeLengthDelimited<T, M extends proto.MessageFns<T>>(
 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.",
+      '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.");
+    throw new Error('Ed25519 pubkeys must be 32 length.');
   }
 
   if (len !== 33 && keyType === KeyType.Secp256k1) {
-    throw new Error("Secp256k1 pubkeys must be 33 length.");
+    throw new Error('Secp256k1 pubkeys must be 33 length.');
   }
 }
 
@@ -298,3 +299,23 @@ export function findToken(tokens: Token[], tokenId: number): Token {
   }
   return tokens[tokenId];
 }
+
+/**
+ * Convert a number to a BN with the specified number of decimals
+ *
+ * @param amount Amount as a number
+ * @param decimals Number of decimal places
+ * @returns Amount as a BN
+ */
+export function toBN(amount: number, decimals: number): BN {
+  const amountString = amount.toFixed(decimals);
+  const [whole, fraction] = amountString.split('.');
+
+  // Convert to smallest units (no decimals)
+  const wholeBN = new BN(whole).mul(new BN(10).pow(new BN(decimals)));
+  const fractionBN = fraction
+    ? new BN(fraction.padEnd(decimals, '0').slice(0, decimals))
+    : new BN(0);
+
+  return wholeBN.add(fractionBN);
+}