@n1xyz/nord-ts 0.1.12 → 0.3.1

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

@@ -0,0 +1,379 @@
+import { Connection, PublicKey, Transaction, SendOptions } from "@solana/web3.js";
+import Decimal from "decimal.js";
+import { FillMode, Side, SPLTokenInfo, QuoteSize, TriggerKind } from "../../types";
+import * as proto from "../../gen/nord_pb";
+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: (x: Uint8Array) => Promise<Uint8Array>;
+    /** Function to sign messages with the user's session key */
+    sessionSignFn: (x: 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 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 object (for market-style placement) */
+    quoteSize?: QuoteSize;
+    /** The client order ID of the order. */
+    clientOrderId?: BigIntValue;
+}
+/**
+ * User class for interacting with the Nord protocol
+ */
+export declare class NordUser {
+    private readonly nord;
+    private readonly address;
+    private readonly walletSignFn;
+    private readonly sessionSignFn;
+    private readonly transactionSignFn;
+    private connection;
+    private sessionId?;
+    private sessionPubKey;
+    private publicKey;
+    private nonce;
+    /** 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[];
+    /** SPL token information */
+    splTokenInfos: SPLTokenInfo[];
+    /**
+     * Create a new NordUser instance
+     *
+     * @param address - User's Solana address (base58)
+     * @param nord - Shared Nord client instance
+     * @param publicKey - Engine account key belonging to the user
+     * @param sessionPubKey - Delegated session key used for actions
+     * @param walletSignFn - Signs wallet-scoped messages (create/revoke session)
+     * @param sessionSignFn - Signs delegated actions
+     * @param transactionSignFn - Signs raw Solana transactions (deposits, SPL ops)
+     * @param connection - Optional Solana connection to reuse
+     * @param sessionId - Optional existing session identifier
+     * @throws {NordError} If required parameters are missing
+     */
+    constructor({ address, nord, publicKey, sessionPubKey, sessionSignFn, transactionSignFn, walletSignFn, connection, sessionId, }: NordUserParams);
+    /**
+     * 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 app
+     *
+     * @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 app
+     *
+     * @param amount - Amount to deposit
+     * @param tokenId - Token ID
+     * @param recipient - Recipient address; defaults to the user's address
+     * @param sendOptions - Send options for .sendTransaction
+     * @returns Transaction signature
+     * @throws {NordError} If required parameters are missing or operation fails
+     */
+    deposit({ amount, tokenId, recipient, sendOptions, }: Readonly<{
+        amount: number;
+        tokenId: number;
+        recipient?: PublicKey;
+        sendOptions?: SendOptions;
+    }>): Promise<string>;
+    /**
+     * Get a new nonce for actions
+     *
+     * @returns Nonce as number
+     */
+    getNonce(): number;
+    private submitSessionAction;
+    /**
+     * 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 marketId - Market in which to place the order
+     * @param side - Bid or ask side
+     * @param fillMode - Limit/PO/IOC/FOK fill mode
+     * @param isReduceOnly - Whether the order can only reduce position
+     * @param size - Optional base size (Decimal)
+     * @param price - Optional limit price (Decimal)
+     * @param quoteSize - Optional quote-size helper for market orders
+     * @param accountId - Optional account identifier to debit
+     * @param clientOrderId - Optional client tracking id
+     * @returns Object containing actionId, orderId (if posted), fills, and clientOrderId
+     * @throws {NordError} If the operation fails
+     */
+    placeOrder(params: Readonly<{
+        marketId: number;
+        side: Side;
+        fillMode: FillMode;
+        isReduceOnly: boolean;
+        size?: Decimal.Value;
+        price?: Decimal.Value;
+        quoteSize?: QuoteSize;
+        accountId?: number;
+        clientOrderId?: BigIntValue;
+    }>): Promise<{
+        actionId: bigint;
+        orderId?: bigint;
+        fills: proto.Receipt_Trade[];
+    }>;
+    /**
+     * Cancel an order
+     *
+     * @param orderId - Order ID to cancel
+     * @param providedAccountId - Account ID that placed the order
+     * @returns Object containing actionId, cancelled orderId, and accountId
+     * @throws {NordError} If the operation fails
+     */
+    cancelOrder(orderId: BigIntValue, providedAccountId?: number): Promise<{
+        actionId: bigint;
+        orderId: bigint;
+        accountId: number;
+    }>;
+    /**
+     * Add a trigger for the current session
+     *
+     * @param marketId - Target market identifier
+     * @param side - Bid/ask direction the trigger will execute
+     * @param kind - Stop-loss or take-profit trigger kind
+     * @param triggerPrice - Price that arms the trigger (Decimal)
+     * @param limitPrice - Optional limit price used once armed
+     * @param accountId - Account identifier to use
+     * @returns Object containing the actionId of the submitted trigger
+     * @throws {NordError} If the operation fails
+     */
+    addTrigger(params: Readonly<{
+        marketId: number;
+        side: Side;
+        kind: TriggerKind;
+        triggerPrice: Decimal.Value;
+        limitPrice?: Decimal.Value;
+        accountId: number;
+    }>): Promise<{
+        actionId: bigint;
+    }>;
+    /**
+     * Remove a trigger for the current session
+     *
+     * @param marketId - Target market
+     * @param side - Bid/ask side of the trigger
+     * @param kind - Trigger kind to remove
+     * @param accountId - Optional account identifier to scope removal
+     * @returns Object containing the actionId of the removal action
+     * @throws {NordError} If the operation fails
+     */
+    removeTrigger(params: Readonly<{
+        marketId: number;
+        side: Side;
+        kind: TriggerKind;
+        accountId?: number;
+    }>): Promise<{
+        actionId: bigint;
+    }>;
+    /**
+     * Transfer tokens to another account
+     *
+     * @param to - Recipient NordUser
+     * @param tokenId - Token identifier to transfer
+     * @param amount - Amount to transfer (Decimal)
+     * @param fromAccountId - Account id debited
+     * @param toAccountId - Account id credited
+     * @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<{
+        actionId: bigint;
+        results: proto.Receipt_AtomicSubactionResultKind[];
+    }>;
+    /**
+     * 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;
+        };
+    }>;
+}