@gala-chain/gswap-sdk 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -787,14 +787,431 @@ function isBlockNumber(value) {
 	return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
 
+//#endregion
+//#region src/types/env.ts
+/** Built-in GalaSwap deployment environments. */
+const GSWAP_ENVIRONMENTS = {
+	prod: {
+		dexBackendBaseUrl: "https://dex-backend-prod1.defi.gala.com",
+		dexBackendWsUrl: "wss://dex-backend-prod1.defi.gala.com/ws"
+	},
+	stage: {
+		dexBackendBaseUrl: "https://swap-backend.stage.defi.ovh.gala.com",
+		dexBackendWsUrl: "wss://swap-backend.stage.defi.ovh.gala.com/ws"
+	}
+};
+
 //#endregion
 //#region src/utils/debug.ts
 const debugLog = (0, debug.default)("GSWAP_SDK");
 
+//#endregion
+//#region src/utils/reconnection.ts
+/** Counts reconnect attempts and doubles the delay between them, up to a ceiling. */
+var ReconnectionBackoff = class {
+	options;
+	attempts = 0;
+	delayMs;
+	maxDelayMs;
+	constructor(options) {
+		this.options = options;
+		this.delayMs = options.baseDelayMs;
+		this.maxDelayMs = options.maxDelayMs ?? 3e4;
+	}
+	/** Whether another attempt is allowed. */
+	shouldRetry() {
+		return this.attempts < this.options.maxAttempts;
+	}
+	/** The delay to wait before the next attempt. */
+	nextDelayMs() {
+		return this.delayMs;
+	}
+	/** Record that an attempt is being made, and double the next delay. */
+	recordAttempt() {
+		this.attempts += 1;
+		this.delayMs = Math.min(this.delayMs * 2, this.maxDelayMs);
+	}
+	/** Forget every attempt: the connection is healthy again. */
+	reset() {
+		this.attempts = 0;
+		this.delayMs = this.options.baseDelayMs;
+	}
+	get attemptCount() {
+		return this.attempts;
+	}
+	get maxAttempts() {
+		return this.options.maxAttempts;
+	}
+};
+
+//#endregion
+//#region src/classes/gdex_stream.ts
+const GDEX_SUBPROTOCOL = "gdex.jsonrpc.v1";
+const RATE_LIMITED = -32003;
+const MAX_RESUBSCRIBE_RATE_RETRIES = 5;
+const WEBSOCKET_OPEN = 1;
+const LIQUIDITY_ACTIONS = [
+	"add",
+	"remove",
+	"collect"
+];
+/** Whether a stream payload carries every field of a {@link GdexLiquidityEvent}. */
+function isGdexLiquidityEvent(value) {
+	const { pool } = value;
+	return (value["version"] === "v1" || value["version"] === "v2") && typeof pool === "object" && pool !== null && typeof value["poolHash"] === "string" && typeof value["transactionId"] === "string" && LIQUIDITY_ACTIONS.includes(value["action"]) && typeof value["owner"] === "string" && typeof value["amount0"] === "string" && typeof value["amount1"] === "string" && typeof value["blockNumber"] === "number" && typeof value["timestamp"] === "string";
+}
+/** A JSON-RPC error answered by the stream. */
+var GdexStreamError = class extends Error {
+	code;
+	data;
+	constructor(code, message, data) {
+		super(message);
+		this.name = "GdexStreamError";
+		this.code = code;
+		if (data !== void 0) this.data = data;
+	}
+};
+/**
+* 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',
+* });
+* ```
+*/
+var GdexStreamService = class {
+	url;
+	requestTimeoutMs;
+	webSocketConstructor;
+	backoff;
+	socket;
+	connectPromise;
+	nextRequestId = 0;
+	pending = /* @__PURE__ */ new Map();
+	subscriptionsByServerId = /* @__PURE__ */ new Map();
+	activeSubscriptions = /* @__PURE__ */ new Set();
+	intentionalClose = false;
+	reconnecting = false;
+	reconnectTimer;
+	reconnectDelayResolve;
+	constructor(config = {}) {
+		this.url = config.url ?? GSWAP_ENVIRONMENTS.prod.dexBackendWsUrl;
+		this.requestTimeoutMs = config.requestTimeoutMs ?? 15e3;
+		this.backoff = new ReconnectionBackoff({
+			maxAttempts: config.reconnectAttempts ?? 5,
+			baseDelayMs: config.reconnectDelayMs ?? 2e3
+		});
+		const implementation = config.webSocketImpl ?? globalThis.WebSocket;
+		if (typeof implementation !== "function") throw new Error("GdexStreamService requires a standards-compatible WebSocket constructor. Node.js versions before 22 must provide one with config.webSocketImpl (for example, from the \"ws\" package).");
+		this.webSocketConstructor = implementation;
+	}
+	/** Open the connection. Resolves at once when already connected. */
+	connect() {
+		if (this.isConnected()) return Promise.resolve();
+		if (this.connectPromise) return this.connectPromise;
+		this.intentionalClose = false;
+		this.clearReconnectTimer();
+		this.connectPromise = this.openSocket();
+		return this.connectPromise;
+	}
+	/** Close the connection and stop reconnecting. */
+	disconnect() {
+		this.intentionalClose = true;
+		this.reconnecting = false;
+		this.clearReconnectTimer();
+		this.rejectPending(/* @__PURE__ */ new Error("GDEX stream disconnected"));
+		const socket = this.socket;
+		this.socket = void 0;
+		this.connectPromise = void 0;
+		socket === null || socket === void 0 || socket.close(1e3, "client disconnect");
+	}
+	isConnected() {
+		var _this$socket;
+		return ((_this$socket = this.socket) === null || _this$socket === void 0 ? void 0 : _this$socket.readyState) === WEBSOCKET_OPEN;
+	}
+	/** Raw JSON-RPC escape hatch. */
+	request(method, params) {
+		if (!this.isConnected() || !this.socket) return Promise.reject(/* @__PURE__ */ new Error("GDEX stream is not connected. Call connect() first."));
+		const id = ++this.nextRequestId;
+		const frame = {
+			jsonrpc: "2.0",
+			id,
+			method
+		};
+		if (params !== void 0) frame["params"] = params;
+		return new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`GDEX request "${method}" timed out after ${this.requestTimeoutMs}ms`));
+			}, this.requestTimeoutMs);
+			this.pending.set(id, {
+				resolve: (value) => resolve(value),
+				reject,
+				timeout
+			});
+			try {
+				var _this$socket2;
+				(_this$socket2 = this.socket) === null || _this$socket2 === void 0 || _this$socket2.send(JSON.stringify(frame));
+			} catch (error) {
+				clearTimeout(timeout);
+				this.pending.delete(id);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			}
+		});
+	}
+	serverInfo() {
+		return this.request("gdex_serverInfo");
+	}
+	ping() {
+		return this.request("gdex_ping");
+	}
+	getPool(selector) {
+		return this.request("gdex_getPool", selector);
+	}
+	getBalance(owner, tokenClassKey) {
+		return this.request("gdex_getBalance", tokenClassKey === void 0 ? { owner } : {
+			owner,
+			tokenClassKey
+		});
+	}
+	getPositions(opts) {
+		return this.request("gdex_getPositions", opts);
+	}
+	getBlockHeight() {
+		return this.request("gdex_getBlockHeight");
+	}
+	quote(params) {
+		return this.request("gdex_quote", params);
+	}
+	getToken(tokenClassKey) {
+		return this.request("gdex_getToken", { tokenClassKey });
+	}
+	/** One event per committed swap. Omit the pool to receive every pool's swaps. */
+	subscribeSwaps(cb, opts = {}) {
+		return this.subscribe("swap", cb, opts);
+	}
+	/** State changes of one pool. */
+	subscribePool(selector, cb, opts = {}) {
+		return this.subscribe("pool", cb, {
+			...selector,
+			...opts
+		});
+	}
+	/** Balance changes of one wallet. */
+	subscribeBalances(owner, cb, opts = {}) {
+		return this.subscribe("balance", cb, {
+			owner,
+			...opts
+		});
+	}
+	/** Each newly created pool. */
+	subscribePoolCreated(cb, opts = {}) {
+		return this.subscribe("poolCreated", cb, opts);
+	}
+	/**
+	* 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, opts = {}) {
+		return this.subscribe("liquidity", (event) => {
+			if (isGdexLiquidityEvent(event)) cb(event);
+			else debugLog("Ignoring a malformed liquidity event from the GDEX stream");
+		}, opts);
+	}
+	/** Each block-height advance. */
+	subscribeBlocks(cb, opts = {}) {
+		return this.subscribe("blocks", cb, opts);
+	}
+	openSocket() {
+		return new Promise((resolve, reject) => {
+			let opened = false;
+			const socket = new this.webSocketConstructor(this.url, GDEX_SUBPROTOCOL);
+			this.socket = socket;
+			socket.onopen = () => {
+				if (this.socket !== socket) return;
+				opened = true;
+				this.connectPromise = void 0;
+				if (!this.reconnecting) this.backoff.reset();
+				debugLog("Connected to GDEX stream");
+				resolve();
+			};
+			socket.onmessage = (event) => this.handleMessage(event.data);
+			socket.onerror = () => {
+				if (!opened) reject(/* @__PURE__ */ new Error(`Failed to connect to GDEX stream at ${this.url}`));
+			};
+			socket.onclose = (event) => {
+				if (this.socket !== socket) return;
+				this.socket = void 0;
+				this.connectPromise = void 0;
+				if (!opened) reject(/* @__PURE__ */ new Error(`GDEX stream closed before connecting (code ${event.code ?? 0})`));
+				this.rejectPending(/* @__PURE__ */ new Error(`GDEX stream connection closed (code ${event.code ?? 0})`));
+				if (!this.intentionalClose && !this.reconnecting) this.startReconnectLoop();
+			};
+		});
+	}
+	handleMessage(data) {
+		if (typeof data !== "string") {
+			debugLog("Ignoring non-text GDEX WebSocket frame");
+			return;
+		}
+		let message;
+		try {
+			message = JSON.parse(data);
+		} catch {
+			debugLog("Ignoring invalid JSON from GDEX stream");
+			return;
+		}
+		if (typeof message.id === "number") {
+			const pending = this.pending.get(message.id);
+			if (!pending) return;
+			clearTimeout(pending.timeout);
+			this.pending.delete(message.id);
+			if (message.error) {
+				const code = typeof message.error.code === "number" ? message.error.code : -32603;
+				const errorMessage = typeof message.error.message === "string" ? message.error.message : "GDEX request failed";
+				pending.reject(new GdexStreamError(code, errorMessage, message.error.data));
+			} else pending.resolve(message.result);
+			return;
+		}
+		if (message.method !== "gdex_subscription" || !this.isRecord(message.params)) return;
+		const subscriptionId = message.params["subscription"];
+		const result = message.params["result"];
+		if (typeof subscriptionId !== "string" || !this.isRecord(result)) return;
+		const subscription = this.subscriptionsByServerId.get(subscriptionId);
+		if (!(subscription === null || subscription === void 0 ? void 0 : subscription.active)) return;
+		try {
+			subscription.callback(result);
+		} catch (error) {
+			debugLog("GDEX subscription callback failed", error);
+		}
+	}
+	async subscribe(channel, callback, options) {
+		const params = {
+			channel,
+			...options
+		};
+		const result = await this.request("gdex_subscribe", params);
+		let active;
+		const handle = {
+			subscriptionId: result.subscriptionId,
+			unsubscribe: async () => this.unsubscribe(active)
+		};
+		active = {
+			serverId: result.subscriptionId,
+			params,
+			callback,
+			handle,
+			active: true
+		};
+		this.activeSubscriptions.add(active);
+		this.subscriptionsByServerId.set(active.serverId, active);
+		return handle;
+	}
+	async unsubscribe(subscription) {
+		if (!subscription.active) return;
+		subscription.active = false;
+		this.activeSubscriptions.delete(subscription);
+		this.subscriptionsByServerId.delete(subscription.serverId);
+		if (this.isConnected()) await this.request("gdex_unsubscribe", { subscriptionId: subscription.serverId });
+	}
+	startReconnectLoop() {
+		if (this.reconnecting || this.intentionalClose) return;
+		this.reconnecting = true;
+		this.reconnectLoop();
+	}
+	async reconnectLoop() {
+		while (!this.intentionalClose && this.backoff.shouldRetry()) {
+			const delay = this.backoff.nextDelayMs();
+			this.backoff.recordAttempt();
+			debugLog(`GDEX reconnect attempt ${this.backoff.attemptCount}/${this.backoff.maxAttempts} in ${delay}ms`);
+			await this.waitForReconnectDelay(delay);
+			if (this.intentionalClose) break;
+			try {
+				await this.openSocket();
+				await this.resubscribeAll();
+				this.backoff.reset();
+				this.reconnecting = false;
+				return;
+			} catch (error) {
+				debugLog(`GDEX reconnect failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		this.reconnecting = false;
+		if (!this.intentionalClose) debugLog("GDEX reconnection attempts exhausted");
+	}
+	async resubscribeAll() {
+		this.subscriptionsByServerId.clear();
+		for (const subscription of this.activeSubscriptions) {
+			if (!subscription.active) continue;
+			const params = {
+				...subscription.params,
+				snapshot: true
+			};
+			const result = await this.resubscribeWithRateLimitRetry(params);
+			if (!subscription.active) {
+				await this.request("gdex_unsubscribe", { subscriptionId: result.subscriptionId });
+				continue;
+			}
+			subscription.serverId = result.subscriptionId;
+			subscription.handle.subscriptionId = result.subscriptionId;
+			this.subscriptionsByServerId.set(result.subscriptionId, subscription);
+		}
+	}
+	async resubscribeWithRateLimitRetry(params) {
+		for (let attempt = 0;; attempt++) try {
+			return await this.request("gdex_subscribe", params);
+		} catch (error) {
+			if (!(error instanceof GdexStreamError) || error.code !== RATE_LIMITED || attempt >= MAX_RESUBSCRIBE_RATE_RETRIES) throw error;
+			const retryAfterMs = this.readRetryAfterMs(error.data);
+			debugLog(`GDEX resubscribe rate limited; retrying in ${retryAfterMs}ms`);
+			await new Promise((resolve) => setTimeout(resolve, retryAfterMs));
+		}
+	}
+	waitForReconnectDelay(delay) {
+		return new Promise((resolve) => {
+			this.reconnectTimer = setTimeout(() => {
+				this.reconnectTimer = void 0;
+				this.reconnectDelayResolve = void 0;
+				resolve();
+			}, delay);
+			this.reconnectDelayResolve = resolve;
+		});
+	}
+	clearReconnectTimer() {
+		if (this.reconnectTimer !== void 0) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = void 0;
+		const resolve = this.reconnectDelayResolve;
+		this.reconnectDelayResolve = void 0;
+		resolve === null || resolve === void 0 || resolve();
+	}
+	rejectPending(error) {
+		for (const pending of this.pending.values()) {
+			clearTimeout(pending.timeout);
+			pending.reject(error);
+		}
+		this.pending.clear();
+	}
+	readRetryAfterMs(data) {
+		if (!this.isRecord(data) || typeof data["retryAfterMs"] !== "number" || data["retryAfterMs"] < 0) return 1e3;
+		return data["retryAfterMs"];
+	}
+	isRecord(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+};
+
 //#endregion
 //#region src/version.ts
 /** Package version embedded by the bundler, with a source-test fallback. */
-const SDK_VERSION = "1.0.0";
+const SDK_VERSION = "1.1.0";
 
 //#endregion
 //#region src/classes/http_client.ts
@@ -1926,14 +2343,6 @@ async function resolveSymbol(symbols, token) {
 	throw new GSwapSDKError("Token could not be resolved to a trading symbol.", "SYMBOL_NOT_FOUND", { token });
 }
 
-//#endregion
-//#region src/types/env.ts
-/** Built-in GalaSwap deployment environments. */
-const GSWAP_ENVIRONMENTS = {
-	prod: { dexBackendBaseUrl: "https://dex-backend-prod1.defi.gala.com" },
-	stage: { dexBackendBaseUrl: "https://swap-backend.stage.defi.ovh.gala.com" }
-};
-
 //#endregion
 //#region src/classes/gswap.ts
 /** Main entry point for the current GalaChainDex SDK. */
@@ -1949,6 +2358,9 @@ var GSwap = class {
 	positions;
 	swaps;
 	assets;
+	dexBackendWsUrl;
+	webSocketImpl;
+	streamClient;
 	/**
 	* Create an SDK client for prod or stage.
 	*
@@ -1977,6 +2389,26 @@ var GSwap = class {
 		this.positions = new Positions(this.gateway, this.symbols, this.signer, this.walletAddress);
 		this.swaps = new Swaps(this.gateway, this.symbols, this.signer, this.walletAddress);
 		this.assets = new Assets(this.dexBackendBaseUrl, httpClient);
+		this.dexBackendWsUrl = (options === null || options === void 0 ? void 0 : options.dexBackendWsUrl) ?? ((options === null || options === void 0 ? void 0 : options.dexBackendBaseUrl) === void 0 ? environment.dexBackendWsUrl : `${this.dexBackendBaseUrl.replace(/^http/u, "ws")}/ws`);
+		this.webSocketImpl = options === null || options === void 0 ? void 0 : options.webSocketImpl;
+	}
+	/**
+	* 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() {
+		this.streamClient ??= new GdexStreamService({
+			url: this.dexBackendWsUrl,
+			...this.webSocketImpl === void 0 ? {} : { webSocketImpl: this.webSocketImpl }
+		});
+		return this.streamClient;
 	}
 };
 function trimTrailingSlash(value) {
@@ -2434,6 +2866,8 @@ exports.GSWAP_ENVIRONMENTS = GSWAP_ENVIRONMENTS;
 exports.GSwap = GSwap;
 exports.GSwapSDKError = GSwapSDKError;
 exports.GalaWalletSigner = GalaWalletSigner;
+exports.GdexStreamError = GdexStreamError;
+exports.GdexStreamService = GdexStreamService;
 exports.Pools = Pools;
 exports.Positions = Positions;
 exports.PrivateKeySigner = PrivateKeySigner;
@@ -2448,6 +2882,7 @@ exports.assertTickRange = assertTickRange;
 exports.compositeKeyOf = compositeKeyOf;
 exports.getObjectProperty = getObjectProperty;
 exports.getStringProperty = getStringProperty;
+exports.isGdexLiquidityEvent = isGdexLiquidityEvent;
 exports.orderSymbols = orderSymbols;
 exports.parseJson = parseJson;
 exports.parseTokenClassKey = parseTokenClassKey;