@gala-chain/gswap-sdk 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -374,6 +374,204 @@ export declare class ChainGateway {
   get httpRequestor(): HttpRequestor;
 }
 //#endregion
+//#region src/classes/gdex_stream.d.ts
+/** Options for {@link GdexStreamService}. */
+export interface GdexStreamConfig {
+  /** Stream endpoint. Defaults to production (`wss://dex-backend-prod1.defi.gala.com/ws`). */
+  url?: string | undefined;
+  /** Reconnect attempts after an unexpected close. Default 5. */
+  reconnectAttempts?: number | undefined;
+  /** Delay before the first reconnect attempt; doubles each attempt. Default 2000 ms. */
+  reconnectDelayMs?: number | undefined;
+  /** How long a request waits for its response. Default 15000 ms. */
+  requestTimeoutMs?: number | undefined;
+  /**
+   * A standards-compatible WebSocket constructor. Required on Node.js older than 22, which has no
+   * global `WebSocket` (pass the one from the `ws` package).
+   */
+  webSocketImpl?: unknown;
+}
+/** The channels of the realtime stream. */
+export type GdexChannel = 'pool' | 'balance' | 'poolCreated' | 'swap' | 'liquidity' | 'blocks';
+/** A pool named by its two token class keys (pipe form) and fee tier. */
+export interface GdexPoolKey {
+  token0ClassKey: string;
+  token1ClassKey: string;
+  fee: number;
+}
+/** A pool named either by its key or by its hash (`v2:<poolRef>` for a v2 pool). */
+export type GdexPoolSelector = {
+  pool: GdexPoolKey;
+} | {
+  poolHash: string;
+};
+/** Options common to every subscription. */
+export interface GdexSubscribeOptions {
+  /** Send the current state right after the subscribe response. */
+  snapshot?: boolean | undefined;
+  /** Trim each event to these fields; identity and envelope fields always stay. */
+  fields?: string[] | undefined;
+}
+/** Filters for {@link GdexStreamService.subscribeLiquidity}; all optional. */
+export interface GdexLiquidityFilter {
+  /** Only this pool, named by its key. */
+  pool?: GdexPoolKey | undefined;
+  /** Only this pool, named by its hash (`v2:<poolRef>` for a v2 pool). */
+  poolHash?: string | undefined;
+  /** Only events for this LP wallet (the position's owner). */
+  owner?: string | undefined;
+  /** Only this transaction. */
+  transactionId?: string | undefined;
+  /** Contract version filter. */
+  version?: 'v1' | 'v2' | 'all' | undefined;
+}
+/** One committed add, remove or collect, as the `liquidity` channel reports it. */
+export interface GdexLiquidityEvent {
+  version: 'v1' | 'v2';
+  pool: GdexPoolKey;
+  poolHash: string;
+  transactionId: string;
+  /** `add`, `remove` or `collect`. */
+  action: 'add' | 'remove' | 'collect';
+  /** The position's owner (the LP wallet). */
+  owner: string;
+  /** v1: the position id. v2: the chain position key `<pool>|<tickLow>|<tickHigh>|<owner>`. */
+  positionId?: string;
+  tickLower?: number;
+  tickUpper?: number;
+  /** v2 only: the position's liquidity after the operation; `"0"` means it is closed. */
+  liquidityAfter?: string;
+  /** Principal moved: deposited by an add, withdrawn by a remove, `"0"` for a collect. */
+  amount0: string;
+  amount1: string;
+  /** Fees paid out. v2: always present (`"0"` for an add). v1: present on a collect only. */
+  fees0?: string;
+  fees1?: string;
+  /** v2 only. */
+  token0Symbol?: string;
+  token1Symbol?: string;
+  blockNumber: number;
+  timestamp: string;
+}
+/** Whether a stream payload carries every field of a {@link GdexLiquidityEvent}. */
+export declare function isGdexLiquidityEvent(value: Record<string, unknown>): value is Record<string, unknown> & GdexLiquidityEvent;
+/** A live subscription. */
+export interface GdexSubscription {
+  subscriptionId: string;
+  unsubscribe(): Promise<void>;
+}
+/** A JSON-RPC error answered by the stream. */
+export declare class GdexStreamError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+  constructor(code: number, message: string, data?: unknown);
+}
+/**
+ * Client for the gSwap realtime stream (gdex WebSocket Protocol v1): JSON-RPC 2.0 over one raw
+ * WebSocket, with automatic reconnect and resubscribe.
+ *
+ * @example
+ * ```typescript
+ * const stream = new GdexStreamService();
+ * await stream.connect();
+ * await stream.subscribeLiquidity(event => console.log(event.action, event.owner), {
+ *   owner: 'client|618ae395c1c653111d3315be',
+ * });
+ * ```
+ */
+export declare class GdexStreamService {
+  private readonly url;
+  private readonly requestTimeoutMs;
+  private readonly webSocketConstructor;
+  private readonly backoff;
+  private socket;
+  private connectPromise;
+  private nextRequestId;
+  private readonly pending;
+  private readonly subscriptionsByServerId;
+  private readonly activeSubscriptions;
+  private intentionalClose;
+  private reconnecting;
+  private reconnectTimer;
+  private reconnectDelayResolve;
+  constructor(config?: GdexStreamConfig);
+  /** Open the connection. Resolves at once when already connected. */
+  connect(): Promise<void>;
+  /** Close the connection and stop reconnecting. */
+  disconnect(): void;
+  isConnected(): boolean;
+  /** Raw JSON-RPC escape hatch. */
+  request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  serverInfo(): Promise<Record<string, unknown>>;
+  ping(): Promise<{
+    pong: boolean;
+    serverTime: string;
+  }>;
+  getPool(selector: GdexPoolSelector): Promise<Record<string, unknown>>;
+  getBalance(owner: string, tokenClassKey?: string): Promise<Record<string, unknown>>;
+  getPositions(opts: {
+    owner: string;
+    pool?: GdexPoolKey;
+    poolHash?: string;
+    limit?: number;
+    bookmark?: string;
+  }): Promise<{
+    positions: Record<string, unknown>[];
+    bookmark: string;
+  }>;
+  getBlockHeight(): Promise<{
+    blockNumber: number;
+    timestamp: string;
+  }>;
+  quote(params: {
+    tokenIn: string;
+    tokenOut: string;
+    fee?: number;
+    amountIn?: string;
+    amountOut?: string;
+  }): Promise<Record<string, unknown>>;
+  getToken(tokenClassKey: string): Promise<Record<string, unknown>>;
+  /** One event per committed swap. Omit the pool to receive every pool's swaps. */
+  subscribeSwaps(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
+    pool?: GdexPoolKey;
+    poolHash?: string;
+    transactionId?: string;
+  }): Promise<GdexSubscription>;
+  /** State changes of one pool. */
+  subscribePool(selector: GdexPoolSelector, cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions): Promise<GdexSubscription>;
+  /** Balance changes of one wallet. */
+  subscribeBalances(owner: string, cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
+    tokenClassKey?: string;
+  }): Promise<GdexSubscription>;
+  /** Each newly created pool. */
+  subscribePoolCreated(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
+    tokenClassKey?: string;
+  }): Promise<GdexSubscription>;
+  /**
+   * One event per committed AddLiquidity, RemoveLiquidity and CollectPositionFees, on both contract
+   * versions. Every filter is optional; with none, every liquidity event arrives. These events never
+   * appear on {@link subscribeSwaps}. There is no snapshot: read positions with {@link getPositions}.
+   * Deduplicate by `transactionId` plus `positionId`: a v1 BatchSubmit can hold several operations
+   * under one transaction id.
+   */
+  subscribeLiquidity(cb: (event: GdexLiquidityEvent) => void, opts?: GdexSubscribeOptions & GdexLiquidityFilter): Promise<GdexSubscription>;
+  /** Each block-height advance. */
+  subscribeBlocks(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions): Promise<GdexSubscription>;
+  private openSocket;
+  private handleMessage;
+  private subscribe;
+  private unsubscribe;
+  private startReconnectLoop;
+  private reconnectLoop;
+  private resubscribeAll;
+  private resubscribeWithRateLimitRetry;
+  private waitForReconnectDelay;
+  private clearReconnectTimer;
+  private rejectPending;
+  private readRetryAfterMs;
+  private isRecord;
+}
+//#endregion
 //#region src/types/fees.d.ts
 /**
  * Fee tiers for pools.
@@ -1071,9 +1269,11 @@ export declare class Swaps {
 //#region src/types/env.d.ts
 /** SDK deployment environment. */
 export type GSwapEnv = 'prod' | 'stage';
-/** Backend URL used by one SDK deployment environment. */
+/** Backend URLs used by one SDK deployment environment. */
 export interface GSwapEnvironmentConfig {
   dexBackendBaseUrl: string;
+  /** The realtime stream endpoint (raw WebSocket, JSON-RPC 2.0). */
+  dexBackendWsUrl: string;
 }
 /** Built-in GalaSwap deployment environments. */
 export declare const GSWAP_ENVIRONMENTS: Readonly<Record<GSwapEnv, GSwapEnvironmentConfig>>;
@@ -1087,6 +1287,10 @@ export interface GSwapOptions {
   dexBackendBaseUrl?: string | undefined;
   httpRequestor?: HttpRequestor | undefined;
   chainCallTimeoutMs?: number | undefined;
+  /** Realtime stream endpoint. Defaults to the environment's, or is derived from `dexBackendBaseUrl`. */
+  dexBackendWsUrl?: string | undefined;
+  /** WebSocket constructor for the realtime stream; required on Node.js older than 22. */
+  webSocketImpl?: unknown;
 }
 /** Main entry point for the current GalaChainDex SDK. */
 export declare class GSwap {
@@ -1101,6 +1305,9 @@ export declare class GSwap {
   readonly positions: Positions;
   readonly swaps: Swaps;
   readonly assets: Assets;
+  readonly dexBackendWsUrl: string;
+  private readonly webSocketImpl;
+  private streamClient;
   /**
    * Create an SDK client for prod or stage.
    *
@@ -1111,6 +1318,18 @@ export declare class GSwap {
    * ```
    */
   constructor(options?: GSwapOptions);
+  /**
+   * The realtime stream client for this environment (created on first use, not connected until you
+   * call `connect()`).
+   *
+   * @example
+   * ```typescript
+   * const gSwap = new GSwap({ env: 'stage' });
+   * await gSwap.stream.connect();
+   * await gSwap.stream.subscribeLiquidity((event) => console.log(event.action, event.amount0));
+   * ```
+   */
+  get stream(): GdexStreamService;
 }
 //#endregion
 //#region src/classes/gswap_sdk_error.d.ts

package/dist/index.d.ts

@@ -374,6 +374,204 @@ export declare class ChainGateway {
   get httpRequestor(): HttpRequestor;
 }
 //#endregion
+//#region src/classes/gdex_stream.d.ts
+/** Options for {@link GdexStreamService}. */
+export interface GdexStreamConfig {
+  /** Stream endpoint. Defaults to production (`wss://dex-backend-prod1.defi.gala.com/ws`). */
+  url?: string | undefined;
+  /** Reconnect attempts after an unexpected close. Default 5. */
+  reconnectAttempts?: number | undefined;
+  /** Delay before the first reconnect attempt; doubles each attempt. Default 2000 ms. */
+  reconnectDelayMs?: number | undefined;
+  /** How long a request waits for its response. Default 15000 ms. */
+  requestTimeoutMs?: number | undefined;
+  /**
+   * A standards-compatible WebSocket constructor. Required on Node.js older than 22, which has no
+   * global `WebSocket` (pass the one from the `ws` package).
+   */
+  webSocketImpl?: unknown;
+}
+/** The channels of the realtime stream. */
+export type GdexChannel = 'pool' | 'balance' | 'poolCreated' | 'swap' | 'liquidity' | 'blocks';
+/** A pool named by its two token class keys (pipe form) and fee tier. */
+export interface GdexPoolKey {
+  token0ClassKey: string;
+  token1ClassKey: string;
+  fee: number;
+}
+/** A pool named either by its key or by its hash (`v2:<poolRef>` for a v2 pool). */
+export type GdexPoolSelector = {
+  pool: GdexPoolKey;
+} | {
+  poolHash: string;
+};
+/** Options common to every subscription. */
+export interface GdexSubscribeOptions {
+  /** Send the current state right after the subscribe response. */
+  snapshot?: boolean | undefined;
+  /** Trim each event to these fields; identity and envelope fields always stay. */
+  fields?: string[] | undefined;
+}
+/** Filters for {@link GdexStreamService.subscribeLiquidity}; all optional. */
+export interface GdexLiquidityFilter {
+  /** Only this pool, named by its key. */
+  pool?: GdexPoolKey | undefined;
+  /** Only this pool, named by its hash (`v2:<poolRef>` for a v2 pool). */
+  poolHash?: string | undefined;
+  /** Only events for this LP wallet (the position's owner). */
+  owner?: string | undefined;
+  /** Only this transaction. */
+  transactionId?: string | undefined;
+  /** Contract version filter. */
+  version?: 'v1' | 'v2' | 'all' | undefined;
+}
+/** One committed add, remove or collect, as the `liquidity` channel reports it. */
+export interface GdexLiquidityEvent {
+  version: 'v1' | 'v2';
+  pool: GdexPoolKey;
+  poolHash: string;
+  transactionId: string;
+  /** `add`, `remove` or `collect`. */
+  action: 'add' | 'remove' | 'collect';
+  /** The position's owner (the LP wallet). */
+  owner: string;
+  /** v1: the position id. v2: the chain position key `<pool>|<tickLow>|<tickHigh>|<owner>`. */
+  positionId?: string;
+  tickLower?: number;
+  tickUpper?: number;
+  /** v2 only: the position's liquidity after the operation; `"0"` means it is closed. */
+  liquidityAfter?: string;
+  /** Principal moved: deposited by an add, withdrawn by a remove, `"0"` for a collect. */
+  amount0: string;
+  amount1: string;
+  /** Fees paid out. v2: always present (`"0"` for an add). v1: present on a collect only. */
+  fees0?: string;
+  fees1?: string;
+  /** v2 only. */
+  token0Symbol?: string;
+  token1Symbol?: string;
+  blockNumber: number;
+  timestamp: string;
+}
+/** Whether a stream payload carries every field of a {@link GdexLiquidityEvent}. */
+export declare function isGdexLiquidityEvent(value: Record<string, unknown>): value is Record<string, unknown> & GdexLiquidityEvent;
+/** A live subscription. */
+export interface GdexSubscription {
+  subscriptionId: string;
+  unsubscribe(): Promise<void>;
+}
+/** A JSON-RPC error answered by the stream. */
+export declare class GdexStreamError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+  constructor(code: number, message: string, data?: unknown);
+}
+/**
+ * Client for the gSwap realtime stream (gdex WebSocket Protocol v1): JSON-RPC 2.0 over one raw
+ * WebSocket, with automatic reconnect and resubscribe.
+ *
+ * @example
+ * ```typescript
+ * const stream = new GdexStreamService();
+ * await stream.connect();
+ * await stream.subscribeLiquidity(event => console.log(event.action, event.owner), {
+ *   owner: 'client|618ae395c1c653111d3315be',
+ * });
+ * ```
+ */
+export declare class GdexStreamService {
+  private readonly url;
+  private readonly requestTimeoutMs;
+  private readonly webSocketConstructor;
+  private readonly backoff;
+  private socket;
+  private connectPromise;
+  private nextRequestId;
+  private readonly pending;
+  private readonly subscriptionsByServerId;
+  private readonly activeSubscriptions;
+  private intentionalClose;
+  private reconnecting;
+  private reconnectTimer;
+  private reconnectDelayResolve;
+  constructor(config?: GdexStreamConfig);
+  /** Open the connection. Resolves at once when already connected. */
+  connect(): Promise<void>;
+  /** Close the connection and stop reconnecting. */
+  disconnect(): void;
+  isConnected(): boolean;
+  /** Raw JSON-RPC escape hatch. */
+  request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  serverInfo(): Promise<Record<string, unknown>>;
+  ping(): Promise<{
+    pong: boolean;
+    serverTime: string;
+  }>;
+  getPool(selector: GdexPoolSelector): Promise<Record<string, unknown>>;
+  getBalance(owner: string, tokenClassKey?: string): Promise<Record<string, unknown>>;
+  getPositions(opts: {
+    owner: string;
+    pool?: GdexPoolKey;
+    poolHash?: string;
+    limit?: number;
+    bookmark?: string;
+  }): Promise<{
+    positions: Record<string, unknown>[];
+    bookmark: string;
+  }>;
+  getBlockHeight(): Promise<{
+    blockNumber: number;
+    timestamp: string;
+  }>;
+  quote(params: {
+    tokenIn: string;
+    tokenOut: string;
+    fee?: number;
+    amountIn?: string;
+    amountOut?: string;
+  }): Promise<Record<string, unknown>>;
+  getToken(tokenClassKey: string): Promise<Record<string, unknown>>;
+  /** One event per committed swap. Omit the pool to receive every pool's swaps. */
+  subscribeSwaps(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
+    pool?: GdexPoolKey;
+    poolHash?: string;
+    transactionId?: string;
+  }): Promise<GdexSubscription>;
+  /** State changes of one pool. */
+  subscribePool(selector: GdexPoolSelector, cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions): Promise<GdexSubscription>;
+  /** Balance changes of one wallet. */
+  subscribeBalances(owner: string, cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
+    tokenClassKey?: string;
+  }): Promise<GdexSubscription>;
+  /** Each newly created pool. */
+  subscribePoolCreated(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
+    tokenClassKey?: string;
+  }): Promise<GdexSubscription>;
+  /**
+   * One event per committed AddLiquidity, RemoveLiquidity and CollectPositionFees, on both contract
+   * versions. Every filter is optional; with none, every liquidity event arrives. These events never
+   * appear on {@link subscribeSwaps}. There is no snapshot: read positions with {@link getPositions}.
+   * Deduplicate by `transactionId` plus `positionId`: a v1 BatchSubmit can hold several operations
+   * under one transaction id.
+   */
+  subscribeLiquidity(cb: (event: GdexLiquidityEvent) => void, opts?: GdexSubscribeOptions & GdexLiquidityFilter): Promise<GdexSubscription>;
+  /** Each block-height advance. */
+  subscribeBlocks(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions): Promise<GdexSubscription>;
+  private openSocket;
+  private handleMessage;
+  private subscribe;
+  private unsubscribe;
+  private startReconnectLoop;
+  private reconnectLoop;
+  private resubscribeAll;
+  private resubscribeWithRateLimitRetry;
+  private waitForReconnectDelay;
+  private clearReconnectTimer;
+  private rejectPending;
+  private readRetryAfterMs;
+  private isRecord;
+}
+//#endregion
 //#region src/types/fees.d.ts
 /**
  * Fee tiers for pools.
@@ -1071,9 +1269,11 @@ export declare class Swaps {
 //#region src/types/env.d.ts
 /** SDK deployment environment. */
 export type GSwapEnv = 'prod' | 'stage';
-/** Backend URL used by one SDK deployment environment. */
+/** Backend URLs used by one SDK deployment environment. */
 export interface GSwapEnvironmentConfig {
   dexBackendBaseUrl: string;
+  /** The realtime stream endpoint (raw WebSocket, JSON-RPC 2.0). */
+  dexBackendWsUrl: string;
 }
 /** Built-in GalaSwap deployment environments. */
 export declare const GSWAP_ENVIRONMENTS: Readonly<Record<GSwapEnv, GSwapEnvironmentConfig>>;
@@ -1087,6 +1287,10 @@ export interface GSwapOptions {
   dexBackendBaseUrl?: string | undefined;
   httpRequestor?: HttpRequestor | undefined;
   chainCallTimeoutMs?: number | undefined;
+  /** Realtime stream endpoint. Defaults to the environment's, or is derived from `dexBackendBaseUrl`. */
+  dexBackendWsUrl?: string | undefined;
+  /** WebSocket constructor for the realtime stream; required on Node.js older than 22. */
+  webSocketImpl?: unknown;
 }
 /** Main entry point for the current GalaChainDex SDK. */
 export declare class GSwap {
@@ -1101,6 +1305,9 @@ export declare class GSwap {
   readonly positions: Positions;
   readonly swaps: Swaps;
   readonly assets: Assets;
+  readonly dexBackendWsUrl: string;
+  private readonly webSocketImpl;
+  private streamClient;
   /**
    * Create an SDK client for prod or stage.
    *
@@ -1111,6 +1318,18 @@ export declare class GSwap {
    * ```
    */
   constructor(options?: GSwapOptions);
+  /**
+   * The realtime stream client for this environment (created on first use, not connected until you
+   * call `connect()`).
+   *
+   * @example
+   * ```typescript
+   * const gSwap = new GSwap({ env: 'stage' });
+   * await gSwap.stream.connect();
+   * await gSwap.stream.subscribeLiquidity((event) => console.log(event.action, event.amount0));
+   * ```
+   */
+  get stream(): GdexStreamService;
 }
 //#endregion
 //#region src/classes/gswap_sdk_error.d.ts