@n1xyz/nord-ts 0.0.19 → 0.0.21

package/dist/nord/client/NordUser.d.ts

@@ -0,0 +1,340 @@
+import { Connection, PublicKey, Transaction } from "@solana/web3.js";
+import Decimal from "decimal.js";
+import { FillMode, Side, SPLTokenInfo } from "../../types";
+import * as proto from "../../gen/nord";
+import { BigIntValue } from "../../utils";
+import { Nord } from "./Nord";
+/**
+ * Parameters for creating a NordUser instance
+ */
+export interface NordUserParams {
+    /** Nord client instance */
+    nord: Nord;
+    /** User's blockchain address */
+    address: string;
+    /** Function to sign messages with the user's wallet */
+    walletSignFn: (message: Uint8Array | string) => Promise<Uint8Array>;
+    /** Function to sign messages with the user's session key */
+    sessionSignFn: (message: Uint8Array) => Promise<Uint8Array>;
+    /** Function to sign transactions with the user's wallet (optional) */
+    transactionSignFn: <T extends Transaction>(tx: T) => Promise<T>;
+    /** Solana connection (optional) */
+    connection?: Connection;
+    /** Session ID (optional) */
+    sessionId?: bigint;
+    /** Session public key (required) */
+    sessionPubKey: Uint8Array;
+    /** Session public key (required) */
+    publicKey: PublicKey;
+}
+/**
+ * Parameters for placing an order
+ */
+export interface PlaceOrderParams {
+    /** Market ID */
+    marketId: number;
+    /** Order side (bid or ask) */
+    side: Side;
+    /** Fill mode (limit, market, etc.) */
+    fillMode: FillMode;
+    /** Whether the order is reduce-only */
+    isReduceOnly: boolean;
+    /** Order size */
+    size?: Decimal.Value;
+    /** Order price */
+    price?: Decimal.Value;
+    /** Quote size (for market orders) */
+    quoteSize?: Decimal.Value;
+    /** Account ID to place the order from */
+    accountId?: number;
+}
+/**
+ * Parameters for transferring tokens between accounts
+ */
+export interface TransferParams {
+    /** Recipient user */
+    to: NordUser;
+    /** Token ID to transfer */
+    tokenId: number;
+    /** Amount to transfer */
+    amount: Decimal.Value;
+    /** Source account ID */
+    fromAccountId: number;
+    /** Destination account ID */
+    toAccountId: number;
+}
+/**
+ * Parameters for individual atomic subactions (user-friendly version)
+ */
+export interface UserAtomicSubaction {
+    /** The type of action to perform. */
+    kind: "place" | "cancel";
+    /** The market ID to place the order in. */
+    marketId?: number;
+    /** The order ID to cancel. */
+    orderId?: BigIntValue;
+    /** Order side (bid or ask) */
+    side?: Side;
+    /** Fill mode (limit, market, etc.) */
+    fillMode?: FillMode;
+    /** Whether the order is reduce-only. */
+    isReduceOnly?: boolean;
+    /** The size of the order. */
+    size?: Decimal.Value;
+    /** Order price */
+    price?: Decimal.Value;
+    /** Quote size (for market orders) */
+    quoteSize?: Decimal.Value;
+    /** The client order ID of the order. */
+    clientOrderId?: BigIntValue;
+}
+/**
+ * User class for interacting with the Nord protocol
+ */
+export declare class NordUser {
+    /** Nord client instance */
+    readonly nord: Nord;
+    /** User's blockchain address */
+    readonly address: PublicKey;
+    /** Function to sign messages with the user's wallet */
+    readonly walletSignFn: (message: Uint8Array | string) => Promise<Uint8Array>;
+    /** Function to sign messages with the user's session key */
+    readonly sessionSignFn: (message: Uint8Array) => Promise<Uint8Array>;
+    /** Function to sign transactions with the user's wallet */
+    readonly transactionSignFn: <T extends Transaction>(tx: T) => Promise<T>;
+    /** User balances by token symbol */
+    balances: {
+        [key: string]: {
+            accountId: number;
+            balance: number;
+            symbol: string;
+        }[];
+    };
+    /** User positions by account ID */
+    positions: {
+        [key: string]: {
+            marketId: number;
+            openOrders: number;
+            perp?: {
+                baseSize: number;
+                price: number;
+                updatedFundingRateIndex: number;
+                fundingPaymentPnl: number;
+                sizePricePnl: number;
+                isLong: boolean;
+            };
+            actionId: number;
+        }[];
+    };
+    /** User margins by account ID */
+    margins: {
+        [key: string]: {
+            omf: number;
+            mf: number;
+            imf: number;
+            cmf: number;
+            mmf: number;
+            pon: number;
+            pn: number;
+            bankruptcy: boolean;
+        };
+    };
+    /** User's account IDs */
+    accountIds?: number[];
+    /** Current session ID */
+    sessionId?: bigint;
+    /** User's public key */
+    publicKey: PublicKey;
+    /** Session public key */
+    sessionPubKey: Uint8Array;
+    /** Last timestamp used */
+    lastTs: number;
+    /** Last nonce used */
+    lastNonce: number;
+    /** Solana connection */
+    connection: Connection;
+    /** SPL token information */
+    splTokenInfos: SPLTokenInfo[];
+    /**
+     * Create a new NordUser instance
+     *
+     * @param params - Parameters for creating a NordUser
+     * @throws {NordError} If required parameters are missing
+     */
+    constructor({ address, nord, publicKey, sessionPubKey, sessionSignFn, transactionSignFn, walletSignFn, connection, sessionId, }: NordUserParams);
+    /**
+     * Create a clone of this NordUser instance
+     *
+     * @returns A new NordUser instance with the same properties
+     */
+    clone(): NordUser;
+    /**
+     * Create a NordUser from a private key
+     *
+     * @param nord - Nord instance
+     * @param privateKey - Private key as string or Uint8Array
+     * @param connection - Solana connection (optional)
+     * @returns NordUser instance
+     * @throws {NordError} If the private key is invalid
+     */
+    static fromPrivateKey(nord: Nord, privateKey: string | Uint8Array, connection?: Connection): NordUser;
+    /**
+     * Get the associated token account for a token mint
+     *
+     * @param mint - Token mint address
+     * @returns Associated token account address
+     * @throws {NordError} If required parameters are missing or operation fails
+     */
+    getAssociatedTokenAccount(mint: PublicKey): Promise<PublicKey>;
+    /**
+     * Deposit SPL tokens to the bridge
+     *
+     * @param amount - Amount to deposit
+     * @param tokenId - Token ID
+     * @param recipient - Recipient address; defaults to the user's address
+     * @returns Transaction signature
+     * @deprecated Use deposit instead
+     * @throws {NordError} If required parameters are missing or operation fails
+     */
+    depositSpl(amount: number, tokenId: number, recipient?: PublicKey): Promise<string>;
+    /**
+     * Deposit SPL tokens to the bridge
+     *
+     * @param amount - Amount to deposit
+     * @param tokenId - Token ID
+     * @param recipient - Recipient address; defaults to the user's address
+     * @returns Transaction signature
+     * @throws {NordError} If required parameters are missing or operation fails
+     */
+    deposit({ amount, tokenId, recipient, }: Readonly<{
+        amount: number;
+        tokenId: number;
+        recipient?: PublicKey;
+    }>): Promise<string>;
+    /**
+     * Get a new nonce for actions
+     *
+     * @returns Nonce as number
+     */
+    getNonce(): number;
+    /**
+     * Update account IDs for this user
+     *
+     * @throws {NordError} If the operation fails
+     */
+    updateAccountId(): Promise<void>;
+    /**
+     * Fetch user information including balances and orders
+     *
+     * @throws {NordError} If the operation fails
+     */
+    fetchInfo(): Promise<void>;
+    /**
+     * Refresh the user's session
+     *
+     * @throws {NordError} If the operation fails
+     */
+    refreshSession(): Promise<void>;
+    /**
+     * Revoke a session
+     *
+     * @param sessionId - Session ID to revoke
+     * @throws {NordError} If the operation fails
+     */
+    revokeSession(sessionId: BigIntValue): Promise<void>;
+    /**
+     * Checks if the session is valid
+     * @private
+     * @throws {NordError} If the session is not valid
+     */
+    private checkSessionValidity;
+    /**
+     * Withdraw tokens from the exchange
+     *
+     * @param tokenId - Token ID to withdraw
+     * @param amount - Amount to withdraw
+     * @throws {NordError} If the operation fails
+     */
+    withdraw({ amount, tokenId, }: Readonly<{
+        tokenId: number;
+        amount: number;
+    }>): Promise<{
+        actionId: bigint;
+    }>;
+    /**
+     * Place an order on the exchange
+     *
+     * @param params - Order parameters
+     * @returns Order ID if successful
+     * @throws {NordError} If the operation fails
+     */
+    placeOrder(params: PlaceOrderParams): Promise<bigint | undefined>;
+    /**
+     * Cancel an order
+     *
+     * @param orderId - Order ID to cancel
+     * @param providedAccountId - Account ID that placed the order
+     * @returns Action ID if successful
+     * @throws {NordError} If the operation fails
+     */
+    cancelOrder(orderId: BigIntValue, providedAccountId?: number): Promise<bigint>;
+    /**
+     * Transfer tokens to another account
+     *
+     * @param params - Transfer parameters
+     * @throws {NordError} If the operation fails
+     */
+    transferToAccount(params: TransferParams): Promise<void>;
+    /**
+     * Execute up to four place/cancel operations atomically.
+     * Per Market:
+     * 1. cancels can only be in the start (one cannot predict future order ids)
+     * 2. intermediate trades can trade only
+     * 3. placements go last
+     *
+     * Across Markets, order action can be any
+     *
+     * @param userActions array of user-friendly subactions
+     * @param providedAccountId optional account performing the action (defaults to first account)
+     */
+    atomic(userActions: UserAtomicSubaction[], providedAccountId?: number): Promise<proto.Receipt_AtomicResult>;
+    /**
+     * Helper function to retry a promise with exponential backoff
+     *
+     * @param fn - Function to retry
+     * @param maxRetries - Maximum number of retries
+     * @param initialDelay - Initial delay in milliseconds
+     * @returns Promise result
+     */
+    private retryWithBackoff;
+    /**
+     * Get user's token balances on Solana chain using mintAddr
+     *
+     * @param options - Optional parameters
+     * @param options.includeZeroBalances - Whether to include tokens with zero balance (default: true)
+     * @param options.includeTokenAccounts - Whether to include token account addresses in the result (default: false)
+     * @param options.maxConcurrent - Maximum number of concurrent requests (default: 5)
+     * @param options.maxRetries - Maximum number of retries for rate-limited requests (default: 3)
+     * @returns Object with token balances and optional token account addresses
+     * @throws {NordError} If required parameters are missing or operation fails
+     */
+    getSolanaBalances(options?: {
+        includeZeroBalances?: boolean;
+        includeTokenAccounts?: boolean;
+        maxConcurrent?: number;
+        maxRetries?: number;
+    }): Promise<{
+        balances: {
+            [symbol: string]: number;
+        };
+        tokenAccounts?: {
+            [symbol: string]: string;
+        };
+    }>;
+    /**
+     * Get the Solana public key derived from the address
+     *
+     * @returns The Solana public key
+     */
+    getSolanaPublicKey(): PublicKey;
+}