@n1xyz/nord-ts 0.0.19 → 0.0.21

package/dist/nord/models/Subscriber.d.ts

@@ -0,0 +1,37 @@
+import { EventEmitter } from "events";
+import { Account, DeltaEvent, OrderbookResponse, SubscriberConfig, StreamTrade, Trades } from "../../types";
+/**
+ * Subscriber class for handling WebSocket subscriptions
+ */
+export declare class Subscriber {
+    streamURL: string;
+    buffer: (DeltaEvent | Trades | Account)[];
+    maxBufferLen: number;
+    /**
+     * Create a new Subscriber instance
+     * @param config Subscriber configuration
+     */
+    constructor(config: SubscriberConfig);
+    /**
+     * Subscribe to WebSocket events
+     */
+    subscribe(): void;
+}
+/**
+ * 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: StreamTrade[]) => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+    close(): void;
+    removeAllListeners(event?: string): this;
+}

package/dist/nord/models/Subscriber.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Subscriber = void 0;
+const utils_1 = require("../../utils");
+/**
+ * Subscriber class for handling WebSocket subscriptions
+ */
+class Subscriber {
+    /**
+     * Create a new Subscriber instance
+     * @param config Subscriber configuration
+     */
+    constructor(config) {
+        this.streamURL = config.streamURL;
+        this.buffer = [];
+        this.maxBufferLen = config.maxBufferLen ?? utils_1.MAX_BUFFER_LEN;
+    }
+    /**
+     * Subscribe to WebSocket events
+     */
+    subscribe() {
+        // TODO: Implement subscription logic
+    }
+}
+exports.Subscriber = Subscriber;

package/dist/nord/utils/NordError.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare class NordError extends Error {
+    /** The original error that caused this error */
+    readonly cause?: unknown;
+    /** HTTP status code (if applicable) */
+    readonly statusCode?: number;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    /**
+     * Create a new NordError
+     *
+     * @param message - Error message
+     * @param options - Error options
+     */
+    constructor(message: string, options?: NordErrorOptions);
+    /**
+     * Convert the error to a string representation
+     *
+     * @returns String representation of the error
+     */
+    toString(): string;
+}

package/dist/nord/utils/NordError.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NordError = void 0;
+/**
+ * Custom error class for Nord-related errors
+ */
+class NordError extends Error {
+    /**
+     * Create a new NordError
+     *
+     * @param message - Error message
+     * @param options - Error options
+     */
+    constructor(message, options = {}) {
+        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() {
+        let result = `${this.name}: ${this.message}`;
+        if (this.statusCode) {
+            result += `  \nstatus: ${this.statusCode}`;
+        }
+        if (this.details && Object.keys(this.details).length > 0) {
+            result += `  \ndetails: ${JSON.stringify(this.details, null, 2)}`;
+        }
+        if (this.cause) {
+            result += `  \ncause: ${this.cause.toString()}`;
+        }
+        return result;
+    }
+}
+exports.NordError = NordError;

package/dist/types.d.ts

@@ -0,0 +1,251 @@
+import * as proto from "./gen/nord";
+import type { components } from "./gen/openapi.ts";
+/**
+ * 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 declare enum PeakTpsPeriodUnit {
+    Hour = "h",
+    Day = "d",
+    Week = "w",
+    Month = "m",
+    Year = "y"
+}
+/**
+ * Nord subscription type for trades or deltas
+ */
+export type SubscriptionType = "trades" | "deltas" | "account";
+/**
+ * Pattern for a valid Nord subscription
+ * Format should be: "<type>@<parameter>"
+ * Examples: "trades@BTCUSDC", "deltas@ETHUSDC", "account@42"
+ */
+export type SubscriptionPattern = `${SubscriptionType}@${string}` | string;
+/**
+ * Configuration options for the Nord client
+ */
+export interface NordConfig {
+    /** Base URL for the Nord web server */
+    webServerUrl: string;
+    /** Bridge verification key */
+    bridgeVk: string;
+    /** Solana cluster URL */
+    solanaUrl: string;
+    /**
+     * Whether to initialize WebSockets on creation, defaults to true
+     * @deprecated this is a funky api we're gonna be removing it
+     */
+    initWebSockets?: boolean;
+}
+export type Info = components["schemas"]["Info2"];
+export type Market = Info["markets"][number];
+export type Token = Info["tokens"][number];
+export type Account = components["schemas"]["Account"];
+export type TradesResponse = components["schemas"]["PageResult_for_String_and_Trade"];
+export type User = components["schemas"]["User"];
+export type OrderbookResponse = components["schemas"]["OrderbookInfo"];
+export type MarketStats = components["schemas"]["MarketStats"];
+export type OrderbookInfo = components["schemas"]["OrderbookInfo"];
+export type MarketStatsFromApi = components["schemas"]["MarketStats"];
+export type TradeFromApi = components["schemas"]["Trade"];
+export type PageResult<K extends string, V extends string> = K extends "String" ? V extends "OrderInfo" ? components["schemas"]["PageResult_for_String_and_OrderInfo"] : V extends "Trade" ? components["schemas"]["PageResult_for_String_and_Trade"] : never : never;
+export type PageResultStringOrderInfo = components["schemas"]["PageResult_for_String_and_OrderInfo"];
+export type PageResultStringTrade = components["schemas"]["PageResult_for_String_and_Trade"];
+export type OrderInfoFromApi = components["schemas"]["OrderInfo"];
+export type OpenOrder = components["schemas"]["OpenOrder"];
+export type Balance = components["schemas"]["Balance"];
+export type PositionSummary = components["schemas"]["PositionSummary"];
+export type PerpPosition = components["schemas"]["PerpPosition"];
+export type AccountMarginsView = components["schemas"]["AccountMarginsView"];
+export type SideSummary = components["schemas"]["SideSummary"];
+export type UserSession = components["schemas"]["UserSession"];
+export type ActionsItem = components["schemas"]["ActionsItem"];
+export type FillRole = components["schemas"]["FillRole"];
+export type PerpMarketStatsFromApi = components["schemas"]["PerpMarketStats"];
+export type SideFromApi = components["schemas"]["Side"];
+export type FillModeFromApi = components["schemas"]["FillMode"];
+export type PlacementOrigin = components["schemas"]["PlacementOrigin"];
+export type FinalizationReason = components["schemas"]["FinalizationReason"];
+/**
+ * Configuration options for the Nord client
+ */
+export interface TokenInfo {
+    address: string;
+    precision: number;
+    tokenId: number;
+    name: string;
+}
+export interface Order {
+    orderId: number;
+    isLong: boolean;
+    size: number;
+    price: number;
+    marketId: number;
+}
+export declare enum KeyType {
+    Ed25519 = 0,
+    Secp256k1 = 1,
+    Bls12_381 = 2
+}
+export declare enum Side {
+    Ask = 0,
+    Bid = 1
+}
+export declare enum FillMode {
+    Limit = 0,
+    PostOnly = 1,
+    ImmediateOrCancel = 2,
+    FillOrKill = 3
+}
+export interface SubscriberConfig {
+    streamURL: string;
+    maxBufferLen?: number;
+}
+export interface DeltaEvent {
+    last_update_id: number;
+    update_id: number;
+    market_symbol: string;
+    asks: OrderbookEntry[];
+    bids: OrderbookEntry[];
+}
+export interface StreamTrade {
+    side: Side;
+    price: number;
+    size: number;
+    order_id: number;
+}
+export interface Trades {
+    last_update_id: number;
+    update_id: number;
+    market_symbol: string;
+    trades: StreamTrade[];
+}
+export interface LocalOrderInfo {
+    id: number;
+    reduce_only: boolean;
+    limit_price: number;
+    size: number;
+    account_id: number;
+    sender_tracking_id?: number;
+}
+export interface HashMap<T> {
+    [key: number]: T;
+}
+export interface ActionResponse {
+    actionId: number;
+    action: proto.Action;
+    physicalExecTime: Date;
+}
+/**
+ * Block summary.
+ * block_number Block number.
+ * from_action_id First action_id in the block.
+ * to_action_id Last action_id in the block.
+ */
+export interface BlockSummary {
+    block_number: number;
+    from_action_id: number;
+    to_action_id: number;
+}
+/**
+ * Aggregate metrics
+ * blocks_total: Total number of L2 blocks.
+ * tx_total: Total number of transactions.
+ * tx_tps: Transaction throughput.
+ * tx_tps_peak: Peak transaction throughput.
+ * 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;
+}
+/**
+ * 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 declare function fillModeToProtoFillMode(x: FillMode): proto.FillMode;
+/**
+ * Orderbook entry representing price and size
+ */
+export interface OrderbookEntry {
+    price: number;
+    size: 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;
+}
+/**
+ * Response for action nonce query
+ */
+export interface ActionNonceResponse {
+    nonce: number;
+}
+/**
+ * WebSocket message types
+ */
+export declare enum WebSocketMessageType {
+    TradeUpdate = "trades",
+    DeltaUpdate = "delta",
+    AccountUpdate = "account"
+}
+/**
+ * WebSocket trade update message
+ */
+export interface WebSocketTradeUpdate {
+    e: WebSocketMessageType.TradeUpdate;
+    symbol: string;
+    trades: StreamTrade[];
+    timestamp: number;
+}
+/**
+ * WebSocket delta update message
+ */
+export interface WebSocketDeltaUpdate {
+    e: WebSocketMessageType.DeltaUpdate;
+    last_update_id: number;
+    update_id: number;
+    market_symbol: string;
+    asks: OrderbookEntry[];
+    bids: OrderbookEntry[];
+    timestamp: number;
+}
+/**
+ * WebSocket user update message
+ */
+export interface WebSocketAccountUpdate {
+    e: WebSocketMessageType.AccountUpdate;
+    accountId: number;
+    account: Account;
+    timestamp: number;
+}
+export type WebSocketMessage = WebSocketTradeUpdate | WebSocketDeltaUpdate | WebSocketAccountUpdate;
+export interface SPLTokenInfo {
+    mint: string;
+    precision: number;
+    tokenId: number;
+    name: string;
+}

package/dist/types.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketMessageType = exports.FillMode = exports.Side = exports.KeyType = exports.PeakTpsPeriodUnit = void 0;
+exports.fillModeToProtoFillMode = fillModeToProtoFillMode;
+const proto = __importStar(require("./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.
+ */
+var PeakTpsPeriodUnit;
+(function (PeakTpsPeriodUnit) {
+    PeakTpsPeriodUnit["Hour"] = "h";
+    PeakTpsPeriodUnit["Day"] = "d";
+    PeakTpsPeriodUnit["Week"] = "w";
+    PeakTpsPeriodUnit["Month"] = "m";
+    PeakTpsPeriodUnit["Year"] = "y";
+})(PeakTpsPeriodUnit || (exports.PeakTpsPeriodUnit = PeakTpsPeriodUnit = {}));
+var KeyType;
+(function (KeyType) {
+    KeyType[KeyType["Ed25519"] = 0] = "Ed25519";
+    KeyType[KeyType["Secp256k1"] = 1] = "Secp256k1";
+    KeyType[KeyType["Bls12_381"] = 2] = "Bls12_381";
+})(KeyType || (exports.KeyType = KeyType = {}));
+var Side;
+(function (Side) {
+    Side[Side["Ask"] = 0] = "Ask";
+    Side[Side["Bid"] = 1] = "Bid";
+})(Side || (exports.Side = Side = {}));
+var FillMode;
+(function (FillMode) {
+    FillMode[FillMode["Limit"] = 0] = "Limit";
+    FillMode[FillMode["PostOnly"] = 1] = "PostOnly";
+    FillMode[FillMode["ImmediateOrCancel"] = 2] = "ImmediateOrCancel";
+    FillMode[FillMode["FillOrKill"] = 3] = "FillOrKill";
+})(FillMode || (exports.FillMode = FillMode = {}));
+/**
+ * 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.
+ */
+function fillModeToProtoFillMode(x) {
+    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");
+}
+/**
+ * WebSocket message types
+ */
+var WebSocketMessageType;
+(function (WebSocketMessageType) {
+    WebSocketMessageType["TradeUpdate"] = "trades";
+    WebSocketMessageType["DeltaUpdate"] = "delta";
+    WebSocketMessageType["AccountUpdate"] = "account";
+})(WebSocketMessageType || (exports.WebSocketMessageType = WebSocketMessageType = {}));

package/dist/utils.d.ts

@@ -0,0 +1,98 @@
+import { Decimal } from "decimal.js";
+import { KeyType, type Market, type Token } from "./types";
+import * as proto from "./gen/nord";
+import { ethers } from "ethers";
+import { RequestInfo, RequestInit, Response } from "node-fetch";
+import { Keypair } from "@solana/web3.js";
+export declare const SESSION_TTL: bigint;
+export declare const ZERO_DECIMAL: Decimal;
+export declare const MAX_BUFFER_LEN = 10000;
+/** Any type convertible to bigint */
+export type BigIntValue = bigint | number | string;
+export declare function panic(message: string): never;
+export declare function isRfc3339(s: string): boolean;
+export declare function assert(predicate: boolean, message?: string): void;
+/**
+ * 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 declare function optExpect<T>(value: T | undefined, message: string): T;
+/** 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 declare function checkedFetch(url: RequestInfo, init?: RequestInit): Promise<Response>;
+/**
+ * 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 declare function signAction(action: Uint8Array, sk: Uint8Array, keyType: KeyType): Uint8Array;
+/**
+ * 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 declare function makeWalletSignFn(walletKey: ethers.BytesLike): (message: Uint8Array | string) => Promise<string>;
+/**
+ * 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 declare const toScaledU64: (x: Decimal.Value, decimals: number) => bigint;
+/**
+ * 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 declare const toScaledU128: (x: Decimal.Value, decimals: number) => bigint;
+/**
+ * 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 declare function encodeLengthDelimited<T, M extends proto.MessageFns<T>>(message: T, coder: M): Uint8Array;
+/**
+ * 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 declare function decodeLengthDelimited<T, M extends proto.MessageFns<T>>(bytes: Uint8Array, coder: M): T;
+export declare function checkPubKeyLength(keyType: KeyType, len: number): void;
+export declare function findMarket(markets: Market[], marketId: number): Market;
+export declare function findToken(tokens: Token[], tokenId: number): Token;
+export declare function keypairFromPrivateKey(privateKey: string | Uint8Array): Keypair;