@n1xyz/nord-ts 0.1.6 → 0.1.7

package/dist/client/NordUser.d.ts

@@ -0,0 +1,350 @@
+import { 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 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 {
+    readonly nord: Nord;
+    readonly sessionSignFn: (message: Uint8Array) => Promise<Uint8Array>;
+    readonly transactionSignFn: (tx: Transaction) => Promise<Transaction>;
+    sessionId?: bigint;
+    sessionPubKey: PublicKey;
+    publicKey: PublicKey;
+    lastTs: number;
+    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 nord - Nord client instance
+     * @param sessionSignFn - Function to sign messages with the user's session key
+     * @param transactionSignFn - Function to sign transactions with the user's wallet (optional)
+     * @param sessionId - Existing session identifier
+     * @param sessionPubKey - Session public key
+     * @param publicKey - Wallet public key
+     * @throws {NordError} If required parameters are missing
+     */
+    constructor({ nord, sessionSignFn, transactionSignFn, sessionId, sessionPubKey, publicKey, }: Readonly<{
+        nord: Nord;
+        sessionSignFn: (message: Uint8Array) => Promise<Uint8Array>;
+        transactionSignFn: (tx: Transaction) => Promise<Transaction>;
+        sessionId?: bigint;
+        sessionPubKey: Uint8Array;
+        publicKey: PublicKey;
+    }>);
+    /**
+     * Create a NordUser from a private key
+     *
+     * @param nord - Nord instance
+     * @param privateKey - Private key as string or Uint8Array
+     * @returns NordUser instance
+     * @throws {NordError} If the private key is invalid
+     */
+    static fromPrivateKey(nord: Nord, privateKey: string | Uint8Array): 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 - Target market identifier
+     * @param side - Order side
+     * @param fillMode - Fill mode (limit, market, etc.)
+     * @param isReduceOnly - Reduce-only flag
+     * @param size - Base size to place
+     * @param price - Limit price
+     * @param quoteSize - Quote-sized order representation
+     * @param accountId - Account executing the order
+     * @param clientOrderId - Optional client-specified identifier
+     * @returns Object containing actionId, orderId (if posted), fills, and clientOrderId
+     * @throws {NordError} If the operation fails
+     */
+    placeOrder({ marketId, side, fillMode, isReduceOnly, size, price, quoteSize, accountId, clientOrderId, }: 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 - Market to watch
+     * @param side - Order side for the trigger
+     * @param kind - Stop-loss or take-profit trigger type
+     * @param triggerPrice - Price that activates the trigger
+     * @param limitPrice - Limit price placed once the trigger fires
+     * @param accountId - Account executing the trigger
+     * @returns Object containing the actionId of the submitted trigger
+     * @throws {NordError} If the operation fails
+     */
+    addTrigger({ marketId, side, kind, triggerPrice, limitPrice, accountId, }: 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 - Market the trigger belongs to
+     * @param side - Order side for the trigger
+     * @param kind - Stop-loss or take-profit trigger type
+     * @param accountId - Account executing the trigger
+     * @returns Object containing the actionId of the removal action
+     * @throws {NordError} If the operation fails
+     */
+    removeTrigger({ marketId, side, kind, accountId, }: Readonly<{
+        marketId: number;
+        side: Side;
+        kind: TriggerKind;
+        accountId?: number;
+    }>): Promise<{
+        actionId: bigint;
+    }>;
+    /**
+     * Transfer tokens to another account
+     *
+     * @param tokenId - Token identifier to move
+     * @param amount - Amount to transfer
+     * @param fromAccountId - Source account id
+     * @param toAccountId - Destination account id
+     * @throws {NordError} If the operation fails
+     */
+    transferToAccount({ tokenId, amount, fromAccountId, toAccountId, }: Readonly<{
+        tokenId: number;
+        amount: Decimal.Value;
+        fromAccountId?: number;
+        toAccountId?: number;
+    }>): Promise<{
+        actionId: bigint;
+        newAccountId?: number;
+    }>;
+    /**
+     * 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;
+        };
+    }>;
+    protected submitSignedAction(kind: proto.Action["kind"], makeSignedMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<proto.Receipt>;
+}