@n1xyz/nord-ts 0.0.17 → 0.0.18

package/src/nord/client/NordUser.ts

@@ -9,15 +9,15 @@ import Decimal from "decimal.js";
 import * as ed from "@noble/ed25519";
 import { sha512 } from "@noble/hashes/sha512";
 ed.etc.sha512Sync = sha512;
-import { SPLTokenInfo, DepositSplParams } from "@n1xyz/proton";
-import { FillMode, Order, Side } from "../../types";
+import { floatToScaledBigIntLossy } from "@n1xyz/proton";
+import { FillMode, Order, Side, SPLTokenInfo } from "../../types";
+import * as proto from "../../gen/nord";
 import {
   BigIntValue,
   checkedFetch,
   findMarket,
   findToken,
   optExpect,
-  toBN as utilsToBN,
   keypairFromPrivateKey,
 } from "../../utils";
 import {
@@ -27,6 +27,8 @@ import {
   revokeSession,
   transfer,
   withdraw,
+  atomic as atomicAction,
+  AtomicSubaction as ApiAtomicSubaction,
 } from "../api/actions";
 import { NordError } from "../utils/NordError";
 import { Nord } from "./Nord";
@@ -48,7 +50,7 @@ export interface NordUserParams {
   sessionSignFn: (message: Uint8Array) => Promise<Uint8Array>;
 
   /** Function to sign transactions with the user's wallet (optional) */
-  transactionSignFn: (transaction: any) => Promise<any>;
+  transactionSignFn: <T extends Transaction>(tx: T) => Promise<T>;
 
   /** Solana connection (optional) */
   connection?: Connection;
@@ -112,6 +114,41 @@ export interface TransferParams {
   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
  */
@@ -131,16 +168,15 @@ export class NordUser {
   public readonly sessionSignFn: (message: Uint8Array) => Promise<Uint8Array>;
 
   /** Function to sign transactions with the user's wallet */
-  public readonly transactionSignFn: (transaction: any) => Promise<any>;
+  public readonly transactionSignFn: <T extends Transaction>(
+    tx: T,
+  ) => Promise<T>;
 
   /** User balances by token symbol */
   public balances: {
     [key: string]: { accountId: number; balance: number; symbol: string }[];
   } = {};
 
-  /** User orders by market symbol */
-  public orders: { [key: string]: Order[] } = {};
-
   /** User positions by account ID */
   public positions: {
     [key: string]: {
@@ -276,7 +312,6 @@ export class NordUser {
 
     // Copy other properties
     cloned.balances = { ...this.balances };
-    cloned.orders = { ...this.orders };
     cloned.positions = { ...this.positions };
     cloned.margins = { ...this.margins };
     cloned.accountIds = this.accountIds ? [...this.accountIds] : undefined;
@@ -417,10 +452,37 @@ export class NordUser {
    *
    * @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
    */
-  async depositSpl(amount: number, tokenId: number): Promise<string> {
+  async depositSpl(
+    amount: number,
+    tokenId: number,
+    recipient?: PublicKey,
+  ): Promise<string> {
+    return this.deposit({ amount, tokenId, recipient });
+  }
+
+  /**
+   * 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
+   */
+  async deposit({
+    amount,
+    tokenId,
+    recipient,
+  }: Readonly<{
+    amount: number;
+    tokenId: number;
+    recipient?: PublicKey;
+  }>): Promise<string> {
     try {
       // Find the token info
       const tokenInfo = this.splTokenInfos.find((t) => t.tokenId === tokenId);
@@ -429,35 +491,28 @@ export class NordUser {
       }
 
       const mint = new PublicKey(tokenInfo.mint);
-      // Get the user's token account
       const fromAccount = await this.getAssociatedTokenAccount(mint);
+      const payer = this.getSolanaPublicKey();
 
-      // Convert amount to BN with proper decimals
-      const amountBN = utilsToBN(amount, tokenInfo.precision);
-
-      // Create deposit parameters
-      const depositParams: DepositSplParams = {
-        amount: amountBN,
+      const { ix, extraSigner } = await this.nord.protonClient.buildDepositIx({
+        payer,
+        recipient: recipient ?? payer,
+        quantAmount: floatToScaledBigIntLossy(amount, tokenInfo.precision),
         mint,
-        fromAccount,
-      };
-
-      // Build the deposit transaction using proton client
-      const depositTx = await this.nord.protonClient.buildDepositTx(
-        depositParams,
-        this.getSolanaPublicKey(),
-        this.connection,
-      );
+        sourceTokenAccount: fromAccount,
+      });
 
-      const { blockhash } = await this.connection.getLatestBlockhash();
+      const { blockhash } =
+        await this.connection.getLatestBlockhash("confirmed");
+      const tx = new Transaction();
 
-      depositTx.recentBlockhash = blockhash;
-      depositTx.feePayer = this.getSolanaPublicKey();
+      tx.add(ix);
+      tx.recentBlockhash = blockhash;
+      tx.feePayer = payer;
 
-      const signedTx = await this.transactionSignFn(depositTx);
+      const signedTx = await this.transactionSignFn(tx);
+      signedTx.partialSign(extraSigner);
 
-      // TODO: should use `VersionedTransaction` and remove any for `transactionSignFn`,
-      // this is incredibly annoying to debug and i could've saved 30 mins.
       const signature = await this.connection.sendRawTransaction(
         signedTx.serialize(),
       );
@@ -491,10 +546,14 @@ export class NordUser {
         throw new NordError("Public key is required to update account ID");
       }
 
-      const resp = await this.nord.getUserAccountIds({
+      const resp = await this.nord.getUser({
         pubkey: this.publicKey.toBase58(),
       });
 
+      if (!resp) {
+        throw new NordError(`User ${this.publicKey.toBase58()} not found`);
+      }
+
       this.accountIds = resp.accountIds;
     } catch (error) {
       throw new NordError("Failed to update account ID", { cause: error });
@@ -583,19 +642,6 @@ export class NordUser {
           });
         }
 
-        // Process orders
-        this.orders[accountData.accountId] = accountData.orders.map(
-          (order: OpenOrder) => {
-            return {
-              orderId: order.orderId,
-              isLong: order.side === "bid",
-              size: order.size,
-              price: order.price,
-              marketId: order.marketId,
-            };
-          },
-        );
-
         // Process positions
         this.positions[accountData.accountId] = accountData.positions;
 
@@ -611,7 +657,6 @@ export class NordUser {
    * @throws {NordError} If the operation fails
    */
   async refreshSession(): Promise<void> {
-    console.log(this.publicKey);
     this.sessionId = await createSession(
       this.nord.webServerUrl,
       this.walletSignFn,
@@ -667,10 +712,13 @@ export class NordUser {
    * @param amount - Amount to withdraw
    * @throws {NordError} If the operation fails
    */
-  async withdraw(
-    tokenId: number,
-    amount: number,
-  ): Promise<{ actionId: bigint }> {
+  async withdraw({
+    amount,
+    tokenId,
+  }: Readonly<{
+    tokenId: number;
+    amount: number;
+  }>): Promise<{ actionId: bigint }> {
     try {
       this.checkSessionValidity();
       const { actionId } = await withdraw(
@@ -797,6 +845,78 @@ export class NordUser {
     }
   }
 
+  /**
+   * 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)
+   */
+  async atomic(
+    userActions: UserAtomicSubaction[],
+    providedAccountId?: number,
+  ): Promise<proto.Receipt_AtomicResult> {
+    try {
+      this.checkSessionValidity();
+
+      const accountId =
+        providedAccountId != null ? providedAccountId : this.accountIds?.[0];
+
+      if (accountId == null) {
+        throw new NordError(
+          "Account ID is undefined. Make sure to call updateAccountId() before atomic operations.",
+        );
+      }
+
+      const apiActions: ApiAtomicSubaction[] = userActions.map((act) => {
+        if (act.kind === "place") {
+          const market = findMarket(this.nord.markets, act.marketId!);
+          if (!market) {
+            throw new NordError(`Market ${act.marketId} not found`);
+          }
+          return {
+            kind: "place",
+            marketId: act.marketId,
+            side: act.side,
+            fillMode: act.fillMode,
+            isReduceOnly: act.isReduceOnly,
+            sizeDecimals: market.sizeDecimals,
+            priceDecimals: market.priceDecimals,
+            size: act.size,
+            price: act.price,
+            quoteSizeSize: act.quoteSize, // treated as quote size; we pass only size component
+            quoteSizePrice: undefined,
+            clientOrderId: act.clientOrderId,
+          } as ApiAtomicSubaction;
+        }
+        return {
+          kind: "cancel",
+          orderId: act.orderId,
+        } as ApiAtomicSubaction;
+      });
+
+      const result = await atomicAction(
+        this.nord.webServerUrl,
+        this.sessionSignFn,
+        await this.nord.getTimestamp(),
+        this.getNonce(),
+        {
+          sessionId: optExpect(this.sessionId, "No session"),
+          accountId: accountId,
+          actions: apiActions,
+        },
+      );
+      return result;
+    } catch (error) {
+      throw new NordError("Atomic operation failed", { cause: error });
+    }
+  }
+
   /**
    * Helper function to retry a promise with exponential backoff
    *

package/src/nord/index.ts

@@ -8,8 +8,6 @@ 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

package/src/nord/models/Subscriber.ts

@@ -4,7 +4,7 @@ import {
   DeltaEvent,
   OrderbookResponse,
   SubscriberConfig,
-  Trade,
+  StreamTrade,
   Trades,
 } from "../../types";
 import { MAX_BUFFER_LEN } from "../../utils";
@@ -49,7 +49,7 @@ export interface OrderbookSubscription extends EventEmitter {
  * Interface for trade subscription
  */
 export interface TradeSubscription extends EventEmitter {
-  on(event: "message", listener: (data: Trade[]) => void): this;
+  on(event: "message", listener: (data: StreamTrade[]) => void): this;
   on(event: "error", listener: (error: Error) => void): this;
   close(): void;
   removeAllListeners(event?: string): this;

package/src/types.ts

@@ -1,4 +1,5 @@
 import * as proto from "./gen/nord";
+import type { components } from "./gen/openapi.ts";
 
 /**
  * The peak TPS rate is queried over the specified period.
@@ -46,6 +47,46 @@ export interface NordConfig {
   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"];
+// Generic PageResult type - note that K and V must match existing schema keys
+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
  */
@@ -87,28 +128,6 @@ export interface SubscriberConfig {
   maxBufferLen?: number;
 }
 
-export interface Market {
-  marketId: number;
-  symbol: string;
-  priceDecimals: number;
-  sizeDecimals: number;
-  baseTokenId: number;
-  quoteTokenId: number;
-  frozen: boolean;
-}
-
-export interface Token {
-  tokenId: number;
-  symbol: string;
-  decimals: number;
-  mintAddr: string;
-}
-
-export interface Info {
-  markets: Market[];
-  tokens: Token[];
-}
-
 export interface DeltaEvent {
   last_update_id: number;
   update_id: number;
@@ -117,7 +136,7 @@ export interface DeltaEvent {
   bids: OrderbookEntry[];
 }
 
-export interface Trade {
+export interface StreamTrade {
   side: Side;
   price: number;
   size: number;
@@ -128,95 +147,26 @@ export interface Trades {
   last_update_id: number;
   update_id: number;
   market_symbol: string;
-  trades: Trade[];
+  trades: StreamTrade[];
 }
 
-export interface OrderInfo {
+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 Account {
-  last_update_id: number;
-  update_id: number;
-  account_id: number;
-  fills: HashMap<number>;
-  places: HashMap<OrderInfo>;
-  cancels: HashMap<OrderInfo>;
-  balances: HashMap<number>;
-}
-
-/**
- * Query the transactions in the specified L2 block.
- * block_number specifies the block number to query.
- * If not specified, transactions from latest block are returned.
- */
-export interface BlockQuery {
-  block_number?: number;
-}
-
-/**
- * Response for BlockQuery.
- * block_number specifies the block number being returned.
- * actions are the list of transactions from the block.
- */
-export interface BlockResponse {
-  block_number: number;
-  actions: ActionInfo[];
-}
-
-/**
- * Response for BlockSummaryQuery.
- * block_summary is the summary of upto the last N blocks.
- * The server can return fewer than last_n block summary if
- * fewer blocks are available or if it exceeds a max cap.
- */
-export interface BlockSummaryResponse {
-  block_summary: BlockSummary[];
-}
-
-/**
- * Query the action for the specified action id.
- * action_id specifies the action to query.
- */
-export interface ActionQuery {
-  action_id: number;
-}
-
-/**
- * Response for ActionQuery.
- * block_number the block the action is part of.
- * If the action is not yet included in any block, null is returned.
- * action the transaction.
- */
 export interface ActionResponse {
-  block_number?: number;
+  actionId: number;
   action: proto.Action;
-}
-
-/**
- * Query the recent actions
- * last_n requests last N actions.
- */
-export interface ActionsQuery {
-  last_n: number;
-}
-
-/**
- * Response for ActionsQuery.
- * actions returns upto the last N actions.
- * The server can return fewer than last_n actions if
- * fewer actions are available or if it exceeds a max cap.
- */
-export interface ActionsResponse {
-  actions: ActionsExtendedInfo[];
+  physicalExecTime: Date;
 }
 
 /**
@@ -231,31 +181,6 @@ export interface BlockSummary {
   to_action_id: number;
 }
 
-/**
- * Info about the block transaction.
- * action_id is the action identifier.
- * action in protobuf format.
- * exec_timestamp is the execution timestamp.
- */
-export interface ActionInfo {
-  action_id: number;
-  action: proto.Action;
-  exec_timestamp: number;
-}
-
-/**
- * Extended info about the block transaction.
- * block_number the block the action is part of.
- * If the action is not yet included in any block, null is returned.
- * action_id of the action.
- * action the transaction.
- */
-export interface ActionsExtendedInfo {
-  block_number?: number;
-  action_id: number;
-  action: proto.Action;
-}
-
 /**
  * Aggregate metrics
  * blocks_total: Total number of L2 blocks.
@@ -272,54 +197,6 @@ export interface AggregateMetrics {
   request_latency_average: number;
 }
 
-// The JSON types returned by rollman, that need to be translated to TS format.
-export interface RollmanBlockResponse {
-  block_number: number;
-  actions: RollmanActionInfo[];
-}
-
-export interface RollmanActionResponse {
-  block_number?: number;
-  action_pb: Uint8Array;
-  exec_timestamp: number;
-}
-
-export interface RollmanActionsResponse {
-  actions: RollmanActionExtendedInfo[];
-}
-
-export interface RollmanActionInfo {
-  action_id: number;
-  action_pb: Uint8Array;
-  exec_timestamp: number;
-}
-
-export interface RollmanActionExtendedInfo {
-  block_number?: number;
-  action_id: number;
-  action_pb: Uint8Array;
-}
-
-export interface MarketsStatsResponse {
-  markets: MarketStats[];
-}
-
-export interface MarketStats {
-  market_id: number;
-  index_price: [number, number];
-  volume_24h: number;
-  high_24h: number;
-  low_24h: number;
-  perp_stats?: PerpMarketStats;
-}
-
-export interface PerpMarketStats {
-  mark_price?: number;
-  funding_rate?: number;
-  next_funding_time?: Date;
-  open_interest?: number;
-}
-
 /**
  * Converts a `FillMode` enum to its corresponding protobuf representation.
  *
@@ -337,41 +214,6 @@ export function fillModeToProtoFillMode(x: FillMode): proto.FillMode {
   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
  */
@@ -380,16 +222,6 @@ export interface OrderbookEntry {
   size: number;
 }
 
-/**
- * Response for orderbook query
- */
-export interface OrderbookResponse {
-  symbol: string;
-  asks: OrderbookEntry[];
-  bids: OrderbookEntry[];
-  timestamp: number;
-}
-
 /**
  * Query parameters for orderbook
  *
@@ -440,7 +272,7 @@ export interface WebSocketSubscription {
 export interface WebSocketTradeUpdate {
   e: WebSocketMessageType.TradeUpdate;
   symbol: string;
-  trades: Trade[];
+  trades: StreamTrade[];
   timestamp: number;
 }
 
@@ -472,3 +304,10 @@ export type WebSocketMessage =
   | WebSocketTradeUpdate
   | WebSocketDeltaUpdate
   | WebSocketAccountUpdate;
+
+export interface SPLTokenInfo {
+  mint: string;
+  precision: number;
+  tokenId: number;
+  name: string;
+}