@n1xyz/nord-ts 0.0.1 → 0.0.5

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,56 @@
+import { EventEmitter } from "events";
+import {
+  Account,
+  DeltaEvent,
+  OrderbookResponse,
+  SubscriberConfig,
+  Trade,
+  Trades,
+} 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 {
+    // TODO: Implement subscription logic
+  }
+}
+
+/**
+ * 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

@@ -17,14 +17,25 @@ export enum PeakTpsPeriodUnit {
   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;
@@ -391,3 +326,139 @@ export function fillModeToProtoFillMode(x: FillMode): proto.FillMode {
   if (x === FillMode.FillOrKill) return proto.FillMode.FILL_OR_KILL;
   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

@@ -9,8 +9,9 @@ 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 = 10n * 60n * 1000n * 10000n;
+export const SESSION_TTL: bigint = 60n * 60n * 24n * 30n;
 export const ZERO_DECIMAL = new Decimal(0);
 export const MAX_BUFFER_LEN = 10_000;
 
@@ -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);
+}