@gala-chain/gswap-sdk 1.1.1 → 1.2.0-rc.2

package/dist/index.cjs

@@ -31,8 +31,66 @@ bignumber_js = __toESM(bignumber_js, 1);
 let decimal_js = require("decimal.js");
 let debug = require("debug");
 debug = __toESM(debug, 1);
-let _gala_chain_api = require("@gala-chain/api");
+let _noble_curves_secp256k1 = require("@noble/curves/secp256k1");
+let _noble_hashes_sha3 = require("@noble/hashes/sha3");
+let _noble_hashes_utils = require("@noble/hashes/utils");
 
+//#region src/utils/confirmation_schedule.ts
+const DEFAULT_TIMEOUT_MS = 6e4;
+const DEFAULT_POLL_INTERVAL_MS = 2e3;
+const MIN_POLL_INTERVAL_MS = 500;
+const MAX_BACKOFF_MS = 8e3;
+/**
+* Builds the schedule for one `confirm()` call. `abortError` creates the error thrown when
+* `options.signal` aborts, so each confirmation kind keeps its own error type and details.
+*/
+function createConfirmationSchedule(options, defaultInitialDelayMs, abortError) {
+	const timeoutMs = Math.max(0, (options === null || options === void 0 ? void 0 : options.timeoutMs) ?? DEFAULT_TIMEOUT_MS);
+	const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, (options === null || options === void 0 ? void 0 : options.pollIntervalMs) ?? DEFAULT_POLL_INTERVAL_MS);
+	const initialDelayMs = Math.max(0, (options === null || options === void 0 ? void 0 : options.initialDelayMs) ?? defaultInitialDelayMs);
+	const signal = options === null || options === void 0 ? void 0 : options.signal;
+	const deadline = Date.now() + timeoutMs;
+	let firstRead = true;
+	let attempt = 0;
+	return { async waitForRead(retryAfterMs) {
+		throwIfAborted(signal, abortError);
+		if (firstRead) {
+			firstRead = false;
+			const remaining = Math.max(0, deadline - Date.now());
+			await delay(Math.min(initialDelayMs, remaining), signal, abortError);
+			return true;
+		}
+		const backoff = Math.min(MAX_BACKOFF_MS, pollIntervalMs * 2 ** Math.min(attempt, 5));
+		attempt += 1;
+		const waitMs = retryAfterMs === void 0 ? jitter(backoff) : Math.max(0, retryAfterMs);
+		if (Date.now() + waitMs > deadline) return false;
+		await delay(waitMs, signal, abortError);
+		return true;
+	} };
+}
+/** Throws `abortError(signal.reason)` when the signal has aborted. */
+function throwIfAborted(signal, abortError) {
+	if ((signal === null || signal === void 0 ? void 0 : signal.aborted) === true) throw abortError(signal.reason);
+}
+function delay(milliseconds, signal, abortError) {
+	if ((signal === null || signal === void 0 ? void 0 : signal.aborted) === true) return Promise.reject(abortError(signal.reason));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(abortError(signal === null || signal === void 0 ? void 0 : signal.reason));
+		};
+		const timer = setTimeout(() => {
+			signal === null || signal === void 0 || signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, milliseconds);
+		signal === null || signal === void 0 || signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function jitter(milliseconds) {
+	return Math.max(0, Math.round(milliseconds * (.9 + Math.random() * .2)));
+}
+
+//#endregion
 //#region src/classes/gswap_sdk_error.ts
 /** Error raised by the SDK for validation, gateway, chain, or transaction failures. */
 var GSwapSDKError = class GSwapSDKError extends Error {
@@ -40,6 +98,19 @@ var GSwapSDKError = class GSwapSDKError extends Error {
 	details;
 	chainMessage;
 	retryAfterMs;
+	/** The HTTP status of the response that caused this error, when there was one. */
+	status;
+	/**
+	* The response body parsed as JSON, when the failing response had one; `undefined` for a body
+	* that was not JSON (see {@link bodyText}). Never part of {@link message}.
+	*/
+	body;
+	/**
+	* The raw text of a failing response whose body was NOT JSON (a proxy's HTML 502, a WAF page,
+	* an empty body). It is kept here for diagnostics and is never copied into {@link message} or
+	* {@link userMessage}, so it cannot reach a user interface by accident.
+	*/
+	bodyText;
 	constructor(message, code, details, chainMessage, retryAfterMs) {
 		super(message);
 		this.code = code;
@@ -47,6 +118,32 @@ var GSwapSDKError = class GSwapSDKError extends Error {
 		this.name = "GSwapSDKError";
 		this.chainMessage = chainMessage;
 		this.retryAfterMs = retryAfterMs;
+		const status = details === null || details === void 0 ? void 0 : details["status"];
+		this.status = typeof status === "number" ? status : void 0;
+		const body = details === null || details === void 0 ? void 0 : details["body"];
+		this.body = typeof body === "string" ? void 0 : body;
+		this.bodyText = typeof body === "string" ? body : void 0;
+	}
+	/**
+	* A message that is safe to show a user as is: the server's own message when it sent one
+	* (a gateway or chain rejection), a neutral line naming the status for an HTTP failure with no
+	* readable answer, and otherwise {@link message}. Apps that word these differently (a
+	* "network busy" line for a 502, say) branch on {@link code} and {@link status} instead.
+	*/
+	get userMessage() {
+		if (this.chainMessage !== void 0 && this.chainMessage !== "") return this.chainMessage;
+		if (this.code === "HTTP_ERROR" && this.status !== void 0) return `The server answered with an unexpected response (HTTP ${this.status}).`;
+		return this.message;
+	}
+	/**
+	* True when the failure means "that market, pool or position does not exist" rather than
+	* "something went wrong": an HTTP 404, a pair with no pool at any fee tier
+	* (`NO_POOL_AVAILABLE`), or a token the DEX contract has no trading symbol for
+	* (`UNKNOWN_TOKEN`). A pool that exists but is too thin (`INSUFFICIENT_LIQUIDITY`) is NOT
+	* not-found.
+	*/
+	get notFound() {
+		return this.status === 404 || this.code === "NO_POOL_AVAILABLE" || this.code === "UNKNOWN_TOKEN";
 	}
 	/** Create the standard missing-signer error. */
 	static noSignerError() {
@@ -56,21 +153,38 @@ var GSwapSDKError = class GSwapSDKError extends Error {
 	static noWalletAddressError() {
 		return new GSwapSDKError("Cannot confirm this write: no walletAddress was provided to the GSwap constructor, so the resulting position cannot be looked up to confirm it landed on chain.", "NO_WALLET_ADDRESS");
 	}
-	/** Create the error used when no pool can quote the requested pair. */
-	static noPoolAvailableError(tokenIn, tokenOut, fee) {
+	/**
+	* Create the error used when no pool can quote the requested pair. `source` is the backend
+	* answer that said so; its status, body and message are kept (the message as `chainMessage`,
+	* so {@link userMessage} is the server's own wording).
+	*/
+	static noPoolAvailableError(tokenIn, tokenOut, fee, source) {
 		return new GSwapSDKError("No pool is available for the requested pair.", "NO_POOL_AVAILABLE", {
 			tokenIn,
 			tokenOut,
-			...fee === void 0 ? {} : { fee }
-		});
+			...fee === void 0 ? {} : { fee },
+			...sourceDetails(source)
+		}, source === null || source === void 0 ? void 0 : source.serverMessage);
 	}
-	/** Create the error used when a pool lacks liquidity for a quote. */
-	static insufficientLiquidityError(tokenIn, tokenOut, fee) {
+	/** Create the error used when a pool lacks liquidity for a quote. `source` as for {@link noPoolAvailableError}. */
+	static insufficientLiquidityError(tokenIn, tokenOut, fee, source) {
 		return new GSwapSDKError("The selected pool has insufficient liquidity for the requested quote.", "INSUFFICIENT_LIQUIDITY", {
 			tokenIn,
 			tokenOut,
-			...fee === void 0 ? {} : { fee }
-		});
+			...fee === void 0 ? {} : { fee },
+			...sourceDetails(source)
+		}, source === null || source === void 0 ? void 0 : source.serverMessage);
+	}
+	/**
+	* The message the server put in a JSON answer (`message`, or `error.Message`), when this error
+	* came from an HTTP response that had one.
+	*/
+	get serverMessage() {
+		var _this$details;
+		const direct = (_this$details = this.details) === null || _this$details === void 0 ? void 0 : _this$details["message"];
+		if (typeof direct === "string") return direct;
+		const body = this.body;
+		return getStringProperty(body, "message") ?? getStringProperty(body, "Message") ?? getStringProperty(getObjectProperty(body, "error"), "Message");
 	}
 	/** Convert a chain-gateway bounce into a typed SDK error. */
 	static fromGatewayBounce(code, message, status, retryAfterMs) {
@@ -123,6 +237,15 @@ var GSwapSDKError = class GSwapSDKError extends Error {
 		});
 	}
 };
+/** The HTTP facts of the error a classified error was derived from. */
+function sourceDetails(source) {
+	if (source === void 0) return {};
+	return {
+		...source.status === void 0 ? {} : { status: source.status },
+		...source.body === void 0 ? {} : { body: source.body },
+		...source.bodyText === void 0 ? {} : { body: source.bodyText }
+	};
+}
 /** Narrow an object property without trusting a cast at a network boundary. */
 function getObjectProperty(value, property) {
 	if (typeof value !== "object" || value === null || !(property in value)) return void 0;
@@ -144,6 +267,308 @@ function parseJson(text) {
 	}
 }
 
+//#endregion
+//#region src/version.ts
+/** Package version embedded by the bundler, with a source-test fallback. */
+const SDK_VERSION = "1.2.0-rc.2";
+
+//#endregion
+//#region src/utils/transport.ts
+/**
+* Arms the abort timer for a request. `Infinity` means "never time out": `setTimeout` would turn
+* it into 1 ms, so no timer is armed at all. Returns a function that disarms it.
+*/
+function armTimeout(controller, timeoutMs) {
+	if (timeoutMs === Infinity) return () => void 0;
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	return () => clearTimeout(timer);
+}
+/**
+* Validates a request timeout in milliseconds: a positive finite number, or `Infinity` for none.
+*
+* @throws GSwapSDKError VALIDATION_ERROR otherwise.
+*/
+function validateTimeoutMs(timeoutMs, name) {
+	if (timeoutMs === Infinity || Number.isFinite(timeoutMs) && timeoutMs > 0) return timeoutMs;
+	throw new GSwapSDKError(`${name} must be a positive number of milliseconds, or Infinity for no timeout.`, "VALIDATION_ERROR", { [name]: timeoutMs });
+}
+const READABLE_QUERY_SAFE = /[A-Za-z0-9\-._~!'()*$|:,]/u;
+function encodeReadable(text) {
+	let out = "";
+	for (const char of text) if (char === " ") out += "+";
+	else if (READABLE_QUERY_SAFE.test(char)) out += char;
+	else out += encodeScalar(char);
+	return out;
+}
+/** Percent-encodes one code point; a lone surrogate becomes U+FFFD, as `URLSearchParams` does. */
+function encodeScalar(char) {
+	try {
+		return encodeURIComponent(char);
+	} catch {
+		return "%EF%BF%BD";
+	}
+}
+/** Serializes GET parameters, in insertion order, in the encoding the wire options select. */
+function buildQueryString(params, encoding = "standard") {
+	if (encoding === "readable") return Object.entries(params).map(([key, value]) => `${encodeReadable(key)}=${encodeReadable(value)}`).join("&");
+	return new URLSearchParams(params).toString();
+}
+/**
+* The request headers for ANY SDK request, GET or POST, from one place so the wire options reach
+* every request alike. Order, which is the order the requestor sees them in: `User-Agent`
+* (`wire.userAgent`, default `GalaChain-SDK/<version>`, `false` omits it), `parts.defaults`,
+* `wire.headers`, `Content-Type` (JSON bodies only), `parts.fixed`. A later entry replaces an
+* earlier one of the same name regardless of case, so a header is never sent twice.
+*/
+function buildRequestHeaders(wire, parts = {}) {
+	const entries = /* @__PURE__ */ new Map();
+	const put = (headers, last = false) => {
+		for (const [name, value] of Object.entries(headers ?? {})) {
+			if (last) entries.delete(name.toLowerCase());
+			entries.set(name.toLowerCase(), [name, value]);
+		}
+	};
+	if ((wire === null || wire === void 0 ? void 0 : wire.userAgent) !== false) put({ "User-Agent": (wire === null || wire === void 0 ? void 0 : wire.userAgent) ?? `GalaChain-SDK/${"1.2.0-rc.2"}` });
+	put(parts.defaults);
+	put(wire === null || wire === void 0 ? void 0 : wire.headers);
+	if (parts.json === true && !entries.has("content-type")) put({ "Content-Type": "application/json" });
+	put(parts.fixed, true);
+	return Object.fromEntries(entries.values());
+}
+async function requestWithTimeout(requestor, url, options, timeoutMs) {
+	const controller = new AbortController();
+	const disarm = armTimeout(controller, timeoutMs);
+	const externalSignal = options.signal;
+	const abortFromCaller = () => controller.abort();
+	externalSignal === null || externalSignal === void 0 || externalSignal.addEventListener("abort", abortFromCaller, { once: true });
+	try {
+		return await requestor(url, {
+			...options,
+			signal: controller.signal
+		});
+	} catch (error) {
+		if (controller.signal.aborted) throw new GSwapSDKError(`Request timed out after ${timeoutMs} ms.`, "REQUEST_TIMEOUT", {
+			url,
+			timeoutMs,
+			cause: error
+		});
+		throw error;
+	} finally {
+		disarm();
+		externalSignal === null || externalSignal === void 0 || externalSignal.removeEventListener("abort", abortFromCaller);
+	}
+}
+async function readResponseBody(response) {
+	const text = await response.text();
+	return parseJson(text) ?? text;
+}
+/** Read a case-insensitive response header from either supported header shape. */
+function readHeader(response, name) {
+	var _Object$entries$find;
+	const headers = response.headers;
+	if (headers === void 0) return void 0;
+	if (hasHeaderGetter(headers)) {
+		const value = headers.get(name);
+		return value === null || value === "" ? void 0 : value;
+	}
+	const value = (_Object$entries$find = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())) === null || _Object$entries$find === void 0 ? void 0 : _Object$entries$find[1];
+	return value === void 0 || value === "" ? void 0 : value;
+}
+/** Read a Retry-After header (delta-seconds or an HTTP date) as non-negative milliseconds. */
+function readRetryAfter(response) {
+	const raw = readHeader(response, "retry-after");
+	if (raw === void 0) return void 0;
+	const seconds = Number(raw);
+	if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+	const timestamp = Date.parse(raw);
+	return Number.isNaN(timestamp) ? void 0 : Math.max(0, timestamp - Date.now());
+}
+/** Read a non-negative integer block number header. */
+function readBlockNumberHeader(response, headerName = "x-block-number") {
+	const raw = readHeader(response, headerName);
+	if (raw === void 0) return void 0;
+	const blockNumber = Number(raw);
+	return Number.isInteger(blockNumber) && blockNumber >= 0 ? blockNumber : void 0;
+}
+function hasHeaderGetter(headers) {
+	return "get" in headers && typeof headers.get === "function";
+}
+
+//#endregion
+//#region src/classes/apply_results.ts
+/** The apply-results key constraint of the swap backend (`apply-results.dto.ts`). */
+const UNIQUE_KEY_PATTERN$1 = /^[A-Za-z0-9._:-]{1,128}$/u;
+/**
+* The AutoApplier waits at least 2 s before applying and the apply lands ~6-8 s after the
+* acknowledgement, so a read at t=0 is a guaranteed 404.
+*/
+const DEFAULT_INITIAL_DELAY_MS = 3e3;
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+/**
+* The outcome of a queued RequestTrade that could not be delivered as an {@link AppliedTrade}.
+* `code` says why:
+*
+* - `CONFIRMATION_TIMEOUT`: no terminal result before the deadline. The trade may still apply;
+*   confirm the same `uniqueKey` again later and never resubmit.
+* - `CONFIRMATION_ABORTED`: the caller's `signal` aborted. Nothing is known about the outcome.
+* - `CONFIRMATION_FAILED`: the apply-results read itself failed (malformed key or body, a
+*   non-retryable HTTP status). The outcome is unknown.
+* - anything else: the chain REJECTED the trade; `code` is the chain `ErrorKey` (or
+*   `CHAIN_ERROR`) and `chainMessage` is its message, which is also `message`.
+*
+* `details` always carries `uniqueKey` and, where known, `requestTransactionId`,
+* `applyTransactionId`, `blockNumber`, `status`, `body`, `url` and the last transport `cause`.
+*/
+var AppliedTradeError = class extends GSwapSDKError {
+	constructor(message, code, details = {}, chainMessage) {
+		super(message, code, details, chainMessage);
+		this.name = "AppliedTradeError";
+	}
+};
+/**
+* Polls `GET /v1/chain/apply-results/{uniqueKey}?channel=asset&contract=dex-contract` until the
+* queued RequestTrade reaches a terminal state.
+*
+* Pacing: wait `initialDelayMs` (default 3 s), then read; on 404, 429, 500, 502, 503, 504 or a
+* transport error wait with jittered exponential backoff (`pollIntervalMs` doubling to 8 s,
+* `Retry-After` honored as seconds or an HTTP date) until `timeoutMs`. Any other status is
+* terminal. At least one read is always made.
+*
+* @returns The applied trade.
+* @throws AppliedTradeError - see its documentation for every `code`.
+* @example
+* ```ts
+* const applied = await confirmAppliedTrade(
+*   { dexBackendBaseUrl: 'https://dex-backend-prod1.defi.gala.com' },
+*   { uniqueKey, requestTransactionId: null },
+*   { initialDelayMs: 0, timeoutMs: 60_000, signal: controller.signal },
+* );
+* ```
+*/
+async function confirmAppliedTrade(client, input, options) {
+	const { uniqueKey } = input;
+	if (!UNIQUE_KEY_PATTERN$1.test(uniqueKey)) throw new AppliedTradeError("uniqueKey must be 1-128 characters of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\".", "CONFIRMATION_FAILED", { uniqueKey });
+	const requestor = client.httpRequestor ?? fetch.bind(globalThis);
+	const requestTimeoutMs = client.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+	const signal = options === null || options === void 0 ? void 0 : options.signal;
+	const abortError = (cause) => new AppliedTradeError("Transaction confirmation was aborted.", "CONFIRMATION_ABORTED", {
+		uniqueKey,
+		...cause === void 0 ? {} : { cause }
+	});
+	const url = `${client.dexBackendBaseUrl.replace(/\/$/u, "")}/v1/chain/apply-results/${encodeURIComponent(uniqueKey)}?channel=asset&contract=dex-contract`;
+	const schedule = createConfirmationSchedule(options, DEFAULT_INITIAL_DELAY_MS, abortError);
+	await schedule.waitForRead();
+	let lastError;
+	while (true) {
+		throwIfAborted(signal, abortError);
+		let response;
+		let body;
+		try {
+			response = await requestWithTimeout(requestor, url, {
+				method: "GET",
+				headers: buildRequestHeaders(client.wire),
+				...signal === void 0 ? {} : { signal }
+			}, requestTimeoutMs);
+			body = await readResponseBody(response);
+		} catch (error) {
+			throwIfAborted(signal, abortError);
+			lastError = error;
+			if (!await schedule.waitForRead()) break;
+			continue;
+		}
+		throwIfAborted(signal, abortError);
+		if (response.status === 200) return readAppliedResult(input, response, body, url);
+		if (response.status === 404 || response.status === 429 || isTransient(response.status)) {
+			const retryAfter = response.status === 429 ? readRetryAfter(response) : void 0;
+			if (!await schedule.waitForRead(retryAfter)) break;
+			continue;
+		}
+		throw new AppliedTradeError(bodyMessage(body), "CONFIRMATION_FAILED", {
+			uniqueKey,
+			status: response.status,
+			body,
+			url
+		});
+	}
+	throw new AppliedTradeError("Transaction confirmation timed out; the trade may still apply. Confirm the same uniqueKey again later instead of resubmitting.", "CONFIRMATION_TIMEOUT", {
+		uniqueKey,
+		requestTransactionId: input.requestTransactionId,
+		url,
+		...lastError === void 0 ? {} : { cause: lastError }
+	});
+}
+function readAppliedResult(input, response, body, url) {
+	const { uniqueKey } = input;
+	const record = asRecord$2(body);
+	const responseKey = (record === null || record === void 0 ? void 0 : record["uniqueKey"]) ?? (record === null || record === void 0 ? void 0 : record["UniqueKey"]);
+	if (typeof responseKey === "string" && responseKey !== uniqueKey) throw malformed$1(input, response, body, url, "Apply result key did not match the requested key.");
+	const status = record === null || record === void 0 ? void 0 : record["Status"];
+	const applyTransactionId = readHeader(response, "x-apply-transaction-id") ?? null;
+	const blockNumber = readBlockNumberHeader(response, "x-apply-block-number") ?? null;
+	if (status === 0) {
+		const errorKey = getStringProperty(record, "ErrorKey") ?? "CHAIN_ERROR";
+		const chainMessage = getStringProperty(record, "Message") ?? "The chain rejected this trade.";
+		throw new AppliedTradeError(chainMessage, errorKey, {
+			uniqueKey,
+			requestTransactionId: input.requestTransactionId,
+			applyTransactionId,
+			blockNumber,
+			status: response.status,
+			body,
+			url,
+			errorKey,
+			message: chainMessage
+		}, chainMessage);
+	}
+	if (status !== 1) throw malformed$1(input, response, body, url);
+	const result = parseTradeExecution(record === null || record === void 0 ? void 0 : record["Data"]);
+	if (result === void 0) throw malformed$1(input, response, body, url);
+	return {
+		uniqueKey,
+		transactionId: applyTransactionId,
+		blockNumber,
+		requestTransactionId: input.requestTransactionId,
+		result
+	};
+}
+function malformed$1(input, response, body, url, message = "Transaction confirmation returned a malformed body") {
+	return new AppliedTradeError(message, "CONFIRMATION_FAILED", {
+		uniqueKey: input.uniqueKey,
+		status: response.status,
+		body,
+		url
+	});
+}
+function parseTradeExecution(value) {
+	const record = asRecord$2(value);
+	if (record === void 0 || typeof record["token0"] !== "string" || typeof record["token1"] !== "string" || typeof record["fee"] !== "number") return;
+	const optionalFields = [
+		"sell0Qty",
+		"sell1Qty",
+		"buy0Qty",
+		"buy1Qty",
+		"tradingFees",
+		"protocolFees",
+		"totalFees"
+	];
+	for (const field of optionalFields) if (field in record && typeof record[field] !== "string") return void 0;
+	return {
+		token0: record["token0"],
+		token1: record["token1"],
+		fee: record["fee"],
+		...Object.fromEntries(optionalFields.flatMap((field) => typeof record[field] === "string" ? [[field, record[field]]] : []))
+	};
+}
+function isTransient(status) {
+	return status === 500 || status === 502 || status === 503 || status === 504;
+}
+function bodyMessage(body) {
+	return getStringProperty(body, "message") ?? getStringProperty(body, "Message") ?? getStringProperty(getObjectProperty(body, "error"), "message") ?? getStringProperty(getObjectProperty(body, "error"), "Message") ?? "Transaction confirmation failed";
+}
+function asRecord$2(value) {
+	return typeof value === "object" && value !== null ? value : void 0;
+}
+
 //#endregion
 //#region src/types/fees.ts
 /**
@@ -236,6 +661,33 @@ function assertTickRange(lower, upper, fee) {
 function assertSpacing(spacing) {
 	if (!Number.isInteger(spacing) || spacing <= 0) throw new RangeError("Tick spacing must be positive");
 }
+/**
+* Puts a `slot0` answer into the frame of the request. The backend always answers in the pool's
+* canonical order and says so with `flippedFromRequest`; when the caller asked for the reverse
+* order the price is inverted here (at 60 significant digits, so a very large or very small
+* reciprocal keeps its precision) and the tick is re-derived from the inverted price with the
+* contract's greatest-tick rule. Negating the tick instead is wrong for a price between ticks
+* (and `-t - 1` is wrong for a price exactly on a tick: sqrtPrice 1 / tick 0 stays 1 / 0).
+*
+* @example
+* ```ts
+* const slot0 = await gSwap.pools.getSlot0('A', 'B', 500);
+* const { sqrtPrice, tick } = frameSlot0(slot0);
+* ```
+*/
+function frameSlot0(slot0) {
+	if (slot0.flippedFromRequest !== true) return {
+		sqrtPrice: slot0.sqrtPrice,
+		tick: slot0.tick
+	};
+	const inverted = new DexDecimal(1).dividedBy(new DexDecimal(slot0.sqrtPrice));
+	if (!inverted.isFinite() || inverted.lessThanOrEqualTo(0)) throw new GSwapSDKError("Cannot invert a non-positive sqrt price.", "VALIDATION_ERROR", { sqrtPrice: slot0.sqrtPrice });
+	const sqrtPrice = inverted.toString();
+	return {
+		sqrtPrice,
+		tick: sqrtPriceToTick(sqrtPrice)
+	};
+}
 
 //#endregion
 //#region src/utils/validation.ts
@@ -351,6 +803,36 @@ function validateWalletAddress(address) {
 		value: address
 	});
 }
+/** Words the chain gateway refuses as a trading symbol. */
+const RESERVED_TRADING_SYMBOLS = /* @__PURE__ */ new Set([
+	"Token",
+	"Unit",
+	"none"
+]);
+const TRADING_SYMBOL_PATTERN = /^[A-Za-z0-9]+$/u;
+const MAX_TRADING_SYMBOL_LENGTH = 32;
+/**
+* True when `symbol` is acceptable to propose into the trading-symbol registry: ASCII letters and
+* digits only, 1 to 32 characters, and not a reserved word (`Token`, `Unit`, `none`) — the rules
+* the chain gateway enforces on a CreatePool symbol.
+*/
+function isProposableTradingSymbol(symbol) {
+	return TRADING_SYMBOL_PATTERN.test(symbol) && symbol.length <= MAX_TRADING_SYMBOL_LENGTH && !RESERVED_TRADING_SYMBOLS.has(symbol);
+}
+/**
+* Asserts that a pair is in the contract's canonical order (`token0 < token1` by plain string
+* comparison), which every write DTO requires. A pair a caller took from a stale quote or
+* position can be reversed; signing it would sign something other than what was priced.
+*
+* @throws GSwapSDKError VALIDATION_ERROR (`details.type` = `NON_CANONICAL_PAIR`) otherwise.
+*/
+function assertCanonicalPair(token0, token1) {
+	if (!(token0 < token1)) throw new GSwapSDKError(`The pair ${token0}/${token1} is not in canonical order: token0 must sort before token1.`, "VALIDATION_ERROR", {
+		type: "NON_CANONICAL_PAIR",
+		token0,
+		token1
+	});
+}
 
 //#endregion
 //#region src/classes/assets.ts
@@ -411,62 +893,141 @@ function isRawUserAsset(value) {
 }
 
 //#endregion
-//#region src/utils/transport.ts
-async function requestWithTimeout(requestor, url, options, timeoutMs) {
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), timeoutMs);
-	const externalSignal = options.signal;
-	const abortFromCaller = () => controller.abort();
-	externalSignal === null || externalSignal === void 0 || externalSignal.addEventListener("abort", abortFromCaller, { once: true });
-	try {
-		return await requestor(url, {
-			...options,
-			signal: controller.signal
-		});
-	} catch (error) {
-		if (controller.signal.aborted) throw new GSwapSDKError(`Request timed out after ${timeoutMs} ms.`, "REQUEST_TIMEOUT", {
-			url,
-			timeoutMs,
-			cause: error
-		});
-		throw error;
-	} finally {
-		clearTimeout(timer);
-		externalSignal === null || externalSignal === void 0 || externalSignal.removeEventListener("abort", abortFromCaller);
-	}
+//#region src/classes/dex_fees.ts
+/** DEX methods the backend accepts a fee quote for (its allow-list enumerates the same six). */
+const DEX_FEE_METHODS = [
+	"Swap",
+	"RequestTrade",
+	"AddLiquidity",
+	"RemoveLiquidity",
+	"CollectPositionFees",
+	"CreatePool"
+];
+/** The chain method name the signed DryRun wrapper is signed under. */
+const DRY_RUN_METHOD = "DryRun";
+/** `uniqueKey` prefix of the DryRun WRAPPER (distinct from the inner DTO's key). */
+const DRY_RUN_UNIQUE_KEY_PREFIX = "galaconnect-operation-";
+/** True when `method` is a DEX method a fee can be quoted for. */
+function isDexFeeMethod(method) {
+	return typeof method === "string" && DEX_FEE_METHODS.includes(method);
 }
-async function readResponseBody(response) {
-	const text = await response.text();
-	return parseJson(text) ?? text;
+/** Current-contract typed DEX messages use trading symbols instead of TokenClassKey objects. */
+function isCurrentContractDexMessage(message, method) {
+	return isDexFeeMethod(method) && typeof (message === null || message === void 0 ? void 0 : message["token0"]) === "string" && typeof message["token1"] === "string";
 }
-/** Read a case-insensitive response header from either supported header shape. */
-function readHeader(response, name) {
-	var _Object$entries$find;
-	const headers = response.headers;
-	if (headers === void 0) return void 0;
-	if (hasHeaderGetter(headers)) {
-		const value = headers.get(name);
-		return value === null || value === "" ? void 0 : value;
-	}
-	const value = (_Object$entries$find = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())) === null || _Object$entries$find === void 0 ? void 0 : _Object$entries$find[1];
-	return value === void 0 || value === "" ? void 0 : value;
-}
-/** Read a non-negative Retry-After header as milliseconds. */
-function readRetryAfter(response) {
-	const raw = readHeader(response, "retry-after");
-	if (raw === void 0) return void 0;
-	const seconds = Number(raw);
-	return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1e3 : void 0;
+/**
+* Reduces an EIP-712 approval `message` to the DTO the chain actually receives: drops the signing
+* envelope (`signature`, `prefix`, `types`, `domain`) and transport metadata (`trace`).
+*/
+function toChainDto(message) {
+	const chainDto = { ...message };
+	for (const field of [
+		"signature",
+		"prefix",
+		"types",
+		"domain",
+		"trace"
+	]) delete chainDto[field];
+	return chainDto;
 }
-/** Read a non-negative integer block number header. */
-function readBlockNumberHeader(response, headerName = "x-block-number") {
-	const raw = readHeader(response, headerName);
-	if (raw === void 0) return void 0;
-	const blockNumber = Number(raw);
-	return Number.isInteger(blockNumber) && blockNumber >= 0 ? blockNumber : void 0;
+/**
+* Signs the DryRun WRAPPER the gateway accepts for every contract:
+* `{ callerPublicKey, method, dto: <inner DTO object>, uniqueKey, signature }`. The inner DTO
+* travels unsigned and as an object; no `signerPublicKey` is sent because the signature already
+* recovers it (the gateway rejects it as REDUNDANT_SIGNER_PUBLIC_KEY). The wrapper carries its own
+* `uniqueKey`, distinct from the DTO's.
+*/
+function buildDryRunWrapper(signer, callerPublicKey, method, dto, uniqueKeyPrefix = DRY_RUN_UNIQUE_KEY_PREFIX) {
+	return signer.signObject(DRY_RUN_METHOD, {
+		callerPublicKey,
+		method,
+		dto,
+		uniqueKey: `${uniqueKeyPrefix}${globalThis.crypto.randomUUID()}`
+	});
 }
-function hasHeaderGetter(headers) {
-	return "get" in headers && typeof headers.get === "function";
+/**
+* Network-fee quote for GalaChain DEX methods, derived from a server-side DryRun.
+*
+* The client only SIGNS the DryRun wrapper (with whatever {@link GalaChainSigner} it is given) and
+* the backend forwards it to the gateway, where the simulated writes carry the fee; the backend
+* never holds a key. Intended for wallets: the DTO quoted is the typed message a dApp handed over.
+*
+* @example
+* ```ts
+* const fees = new DexFees({ dexBackendBaseUrl }, new PrivateKeySigner(sessionKey));
+* const quote = await fees.quote(publicKey, 'RequestTrade', toChainDto(message), {
+*   contract: 'dex-contract',
+* });
+* const feeInGala = quote?.fees[0]?.feeInGala;
+* ```
+*/
+var DexFees = class {
+	signer;
+	requestor;
+	baseUrl;
+	requestTimeoutMs;
+	wire;
+	constructor(client, signer) {
+		this.signer = signer;
+		this.requestor = client.httpRequestor ?? fetch.bind(globalThis);
+		this.baseUrl = client.dexBackendBaseUrl.replace(/\/$/u, "");
+		this.requestTimeoutMs = client.requestTimeoutMs ?? 3e4;
+		this.wire = client.wire;
+	}
+	/**
+	* Quotes the network fee for `method` applied to `message`. The message is reduced with
+	* {@link toChainDto} first, so an EIP-712 approval message can be passed as is.
+	*
+	* Resolves `null` when the BACKEND could not be reached or answered unusably (offline, 4xx/5xx,
+	* malformed body): a transport outcome, not a fee. Deciding what to charge when the chain is
+	* silent is the backend's job (it serves `source: 'default'`), so the client never substitutes
+	* a fee of its own, with ONE exception that mirrors the wallet: a `dex-contract` quote answered
+	* 403 or 404 means the contract has no fee route yet and resolves `{ source: 'default', '0' }`.
+	* Never throws on transport, so a fee lookup cannot block or break a signing screen.
+	*
+	* @throws GSwapSDKError NO_SIGNER when constructed without a signer; any error the signer
+	* throws (for example a locked wallet) propagates unchanged.
+	*/
+	async quote(callerPublicKey, method, message, options = {}) {
+		if (this.signer === void 0) throw GSwapSDKError.noSignerError();
+		const channel = options.channel ?? "asset";
+		const contract = options.contract ?? "dexv3-contract";
+		const wrapper = await buildDryRunWrapper(this.signer, callerPublicKey, method, toChainDto(message));
+		const url = `${this.baseUrl}/wallet/connect/galachain/api/${encodeURIComponent(channel)}/${encodeURIComponent(contract)}/${encodeURIComponent(method)}/fee`;
+		let status;
+		let ok;
+		let body;
+		try {
+			const response = await requestWithTimeout(this.requestor, url, {
+				method: "POST",
+				headers: buildRequestHeaders(this.wire, {
+					json: true,
+					defaults: { Accept: "application/json" }
+				}),
+				body: JSON.stringify(wrapper)
+			}, this.requestTimeoutMs);
+			status = response.status;
+			ok = response.ok;
+			body = ok ? await readResponseBody(response) : void 0;
+		} catch {
+			return null;
+		}
+		if (!ok) {
+			if (contract === "dex-contract" && (status === 403 || status === 404)) return {
+				source: "default",
+				fees: [{ feeInGala: "0" }]
+			};
+			return null;
+		}
+		return readQuote(body);
+	}
+};
+function readQuote(body) {
+	var _fees$;
+	if (typeof body !== "object" || body === null) return null;
+	const fees = body.fees;
+	if (!Array.isArray(fees) || typeof ((_fees$ = fees[0]) === null || _fees$ === void 0 ? void 0 : _fees$.feeInGala) !== "string") return null;
+	return body;
 }
 
 //#endregion
@@ -477,12 +1038,27 @@ var SubmittedTransaction = class {
 	uniqueKey;
 	transactionId;
 	blockNumber;
+	/** The gateway's `data.mode`: `'sync'` (executed, `result` is the chain result) or `'queued'`. */
 	mode;
+	/**
+	* What the gateway's answer established: `'executed'` for `mode: 'sync'`, `'queued'` for
+	* `mode: 'queued'` (accepted, NOT executed: `await confirm()` for the outcome). A refused answer
+	* never becomes a transaction, so there is no `'rejected'` here; see {@link classifySubmitEnvelope}
+	* for classifying a raw envelope.
+	*/
+	status;
 	/** The synchronous gateway result, or `undefined` when `mode === 'queued'`. */
 	result;
+	/**
+	* The gateway's whole JSON answer as it came (`{ status, message, error, data }`), for an app
+	* that hands the backend's own envelope to its callers; `undefined` for a transaction built from
+	* a uniqueKey alone.
+	*/
+	envelope;
 	backendBaseUrl;
 	requestor;
 	requestTimeoutMs;
+	wire;
 	positionConfirmation;
 	/** Construct a submitted transaction from a successful gateway response.
 	*
@@ -501,10 +1077,13 @@ var SubmittedTransaction = class {
 		this.transactionId = options.transactionId;
 		this.blockNumber = options.blockNumber ?? null;
 		this.mode = options.mode;
+		this.status = options.mode === "queued" ? "queued" : "executed";
 		this.result = options.result;
+		this.envelope = options.envelope;
 		this.backendBaseUrl = options.dexBackendBaseUrl.replace(/\/$/u, "");
 		this.requestor = options.httpRequestor;
 		this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+		this.wire = options.wire;
 		this.positionConfirmation = options.positionConfirmation;
 	}
 	/** Confirm a queued RequestTrade or prove the affected position for a liquidity write.
@@ -521,63 +1100,16 @@ var SubmittedTransaction = class {
 		if (this.method === "RequestTrade") return this.confirmApplied(options);
 		return this.confirmPosition(options);
 	}
-	async confirmApplied(options) {
-		const schedule = createConfirmationSchedule(options, 3e3);
-		await schedule.waitForRead();
-		const url = `${this.backendBaseUrl}/v1/chain/apply-results/${encodeURIComponent(this.uniqueKey)}?channel=asset&contract=dex-contract`;
-		let lastError;
-		while (true) {
-			let response;
-			let body;
-			try {
-				response = await requestWithTimeout(this.requestor, url, { method: "GET" }, this.requestTimeoutMs);
-				body = await readResponseBody(response);
-			} catch (error) {
-				lastError = error;
-				if (!await schedule.waitForRead()) break;
-				continue;
-			}
-			if (response.status === 200) return this.readAppliedResult(response, body, url);
-			if (response.status === 404 || response.status === 429 || isTransient(response.status)) {
-				if (response.status === 429) {
-					const retryAfter = readRetryAfter(response);
-					if (retryAfter !== void 0) {
-						if (!await schedule.waitForRead(retryAfter)) break;
-						continue;
-					}
-				}
-			} else throw new GSwapSDKError(bodyMessage(body), "CONFIRMATION_FAILED", {
-				status: response.status,
-				body,
-				url
-			});
-			if (!await schedule.waitForRead()) break;
-		}
-		throw GSwapSDKError.confirmationTimeoutError(this.uniqueKey, lastError);
-	}
-	readAppliedResult(response, body, url) {
-		const record = asRecord$1(body);
-		const status = record === null || record === void 0 ? void 0 : record["Status"];
-		const applyTransactionId = readHeader(response, "x-apply-transaction-id") ?? null;
-		const blockNumber = readBlockNumberHeader(response, "x-apply-block-number") ?? null;
-		if (status === 0) throw GSwapSDKError.fromChainError(getStringProperty(record, "ErrorKey") ?? "CHAIN_ERROR", getStringProperty(record, "Message") ?? "The chain rejected this trade.", {
-			uniqueKey: this.uniqueKey,
-			applyTransactionId,
-			blockNumber,
-			status: response.status,
-			body,
-			url
-		});
-		if (status !== 1) throw malformedConfirmation(response, body, url);
-		const result = parseTradeExecution(record === null || record === void 0 ? void 0 : record["Data"]);
-		if (result === void 0) throw malformedConfirmation(response, body, url);
-		return {
+	confirmApplied(options) {
+		return confirmAppliedTrade({
+			dexBackendBaseUrl: this.backendBaseUrl,
+			httpRequestor: this.requestor,
+			requestTimeoutMs: this.requestTimeoutMs,
+			wire: this.wire
+		}, {
 			uniqueKey: this.uniqueKey,
-			transactionId: applyTransactionId,
-			blockNumber,
-			requestTransactionId: this.transactionId,
-			result
-		};
+			requestTransactionId: this.transactionId
+		}, options);
 	}
 	/** Confirm a liquidity write against the position's observable effect.
 	*
@@ -589,86 +1121,33 @@ var SubmittedTransaction = class {
 	*/
 	async confirmPosition(options) {
 		if (this.positionConfirmation === void 0) throw GSwapSDKError.noWalletAddressError();
-		const schedule = createConfirmationSchedule(options, 0);
+		const callerSignal = options === null || options === void 0 ? void 0 : options.signal;
+		const abortError = (cause) => new GSwapSDKError("Transaction confirmation was aborted.", "CONFIRMATION_ABORTED", {
+			uniqueKey: this.uniqueKey,
+			...cause === void 0 ? {} : { cause }
+		});
+		const schedule = createConfirmationSchedule(options, 0, abortError);
 		await schedule.waitForRead();
 		while (true) {
 			const controller = new AbortController();
-			const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+			const disarm = armTimeout(controller, this.requestTimeoutMs);
+			const forwardAbort = () => controller.abort();
+			callerSignal === null || callerSignal === void 0 || callerSignal.addEventListener("abort", forwardAbort, { once: true });
 			try {
 				const result = await this.positionConfirmation(controller.signal);
 				if (result.confirmed) return result.position;
+			} catch (error) {
+				throwIfAborted(callerSignal, abortError);
+				throw error;
 			} finally {
-				clearTimeout(timer);
+				disarm();
+				callerSignal === null || callerSignal === void 0 || callerSignal.removeEventListener("abort", forwardAbort);
 			}
 			if (!await schedule.waitForRead()) break;
 		}
 		throw GSwapSDKError.confirmationTimeoutError(this.uniqueKey);
 	}
 };
-function createConfirmationSchedule(options, defaultInitialDelayMs) {
-	const timeoutMs = Math.max(0, (options === null || options === void 0 ? void 0 : options.timeoutMs) ?? 6e4);
-	const pollIntervalMs = Math.max(500, (options === null || options === void 0 ? void 0 : options.pollIntervalMs) ?? 2e3);
-	const initialDelayMs = Math.max(0, (options === null || options === void 0 ? void 0 : options.initialDelayMs) ?? defaultInitialDelayMs);
-	const deadline = Date.now() + timeoutMs;
-	let firstRead = true;
-	let attempt = 0;
-	return { async waitForRead(retryAfterMs) {
-		if (firstRead) {
-			firstRead = false;
-			const remaining = Math.max(0, deadline - Date.now());
-			await delay(Math.min(initialDelayMs, remaining));
-			return true;
-		}
-		const backoff = Math.min(8e3, pollIntervalMs * 2 ** Math.min(attempt, 5));
-		attempt += 1;
-		const waitMs = retryAfterMs === void 0 ? jitter(backoff) : retryAfterMs;
-		if (Date.now() + waitMs > deadline) return false;
-		await delay(waitMs);
-		return true;
-	} };
-}
-function parseTradeExecution(value) {
-	const record = asRecord$1(value);
-	if (record === void 0 || typeof record["token0"] !== "string" || typeof record["token1"] !== "string" || typeof record["fee"] !== "number") return;
-	const optionalFields = [
-		"sell0Qty",
-		"sell1Qty",
-		"buy0Qty",
-		"buy1Qty",
-		"tradingFees",
-		"protocolFees",
-		"totalFees"
-	];
-	for (const field of optionalFields) if (field in record && typeof record[field] !== "string") return void 0;
-	return {
-		token0: record["token0"],
-		token1: record["token1"],
-		fee: record["fee"],
-		...Object.fromEntries(optionalFields.flatMap((field) => typeof record[field] === "string" ? [[field, record[field]]] : []))
-	};
-}
-function malformedConfirmation(response, body, url) {
-	return new GSwapSDKError("Transaction confirmation returned a malformed body", "CONFIRMATION_FAILED", {
-		status: response.status,
-		body,
-		url
-	});
-}
-function isTransient(status) {
-	return status === 500 || status === 502 || status === 503 || status === 504;
-}
-function bodyMessage(body) {
-	return getStringProperty(body, "message") ?? getStringProperty(body, "Message") ?? getStringProperty(getObjectProperty(body, "error"), "message") ?? getStringProperty(getObjectProperty(body, "error"), "Message") ?? (typeof body === "string" ? body : "Transaction confirmation failed");
-}
-function asRecord$1(value) {
-	return typeof value === "object" && value !== null ? value : void 0;
-}
-function delay(milliseconds) {
-	return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
-function jitter(milliseconds) {
-	return Math.max(0, Math.round(milliseconds * (.9 + Math.random() * .2)));
-}
 
 //#endregion
 //#region src/classes/gateway.ts
@@ -679,38 +1158,36 @@ var ChainGateway = class {
 	chainCallTimeoutMs;
 	requestTimeoutMs;
 	dexBackendBaseUrl;
+	/** Wire format shared by the read services built on this gateway. */
+	wire;
 	/** Create a chain gateway client. */
 	constructor(options) {
 		this.dexBackendBaseUrl = trimTrailingSlash$1(options.dexBackendBaseUrl);
 		this.requestor = options.httpRequestor ?? fetch.bind(globalThis);
 		this.walletAddress = options.walletAddress;
-		this.chainCallTimeoutMs = options.chainCallTimeoutMs ?? 3e4;
+		this.chainCallTimeoutMs = validateTimeoutMs(options.chainCallTimeoutMs ?? 3e4, "chainCallTimeoutMs");
 		this.requestTimeoutMs = this.chainCallTimeoutMs;
+		this.wire = options.wire ?? {};
 	}
 	async submit(method, signedBody, options) {
 		if (method === "Trade") throw new GSwapSDKError("The synchronous Trade method was removed; swaps are queued through RequestTrade.", "METHOD_NOT_SUPPORTED", { method });
-		const url = `${this.dexBackendBaseUrl}/v1/chain/asset/dex-contract/${method}`;
-		const headers = { "content-type": "application/json" };
+		const url = this.writeUrl(method);
 		const walletAddress = (options === null || options === void 0 ? void 0 : options.walletAddress) ?? this.walletAddress;
-		if (walletAddress !== void 0) headers["X-Wallet-Address"] = walletAddress;
-		let response;
-		try {
-			response = await requestWithTimeout(this.requestor, url, {
-				method: "POST",
-				headers,
-				body: JSON.stringify(signedBody)
-			}, this.chainCallTimeoutMs);
-		} catch (error) {
-			if (error instanceof GSwapSDKError && error.code === "REQUEST_TIMEOUT") throw new GSwapSDKError("The submission outcome is unknown because the gateway request timed out. Confirm before retrying.", "SUBMISSION_OUTCOME_UNKNOWN", {
-				uniqueKey: getStringProperty(signedBody, "uniqueKey") ?? "",
-				cause: error
-			});
-			throw error;
-		}
+		const headers = buildRequestHeaders(this.wire, {
+			json: true,
+			fixed: walletAddress === void 0 ? {} : { "X-Wallet-Address": walletAddress }
+		});
+		const response = await this.post(url, headers, signedBody);
 		const body = await readResponseBody(response);
 		if (!response.ok) throw gatewayError(response, body, url);
-		const envelope = asRecord(body);
-		const data = asRecord((envelope === null || envelope === void 0 ? void 0 : envelope["data"]) ?? (envelope === null || envelope === void 0 ? void 0 : envelope["Data"]));
+		const envelope = asRecord$1(body);
+		if ((envelope === null || envelope === void 0 ? void 0 : envelope["error"]) === true) throw new GSwapSDKError(getStringProperty(envelope, "message") || "The gateway reported an error for this write.", "INVALID_GATEWAY_RESPONSE", {
+			status: response.status,
+			body,
+			url,
+			type: "GATEWAY_REPORTED_ERROR"
+		});
+		const data = asRecord$1((envelope === null || envelope === void 0 ? void 0 : envelope["data"]) ?? (envelope === null || envelope === void 0 ? void 0 : envelope["Data"]));
 		if (data === void 0) throw invalidGatewayResponse(response, body, url, "Expected a data object.");
 		const transactionId = getStringProperty(data, "transactionId");
 		const mode = getStringProperty(data, "mode");
@@ -720,12 +1197,10 @@ var ChainGateway = class {
 		if (mode !== "sync" && mode !== "queued") throw invalidGatewayResponse(response, body, url, invalidModeMessage);
 		if ("transactionId" in data && typeof rawTransactionId !== "string" || bodyBlockNumber !== void 0 && bodyBlockNumber !== null && !isBlockNumber(bodyBlockNumber)) throw invalidGatewayResponse(response, body, url, invalidModeMessage);
 		if (method === "RequestTrade" && mode === "sync") throw invalidGatewayResponse(response, body, url, "The gateway executed RequestTrade synchronously, which this SDK refuses; RequestTrade must be queued.");
-		if (method === "RequestTrade" && mode === "queued") {
-			const signedUniqueKey = getStringProperty(signedBody, "uniqueKey");
-			if ("uniqueKey" in data && (typeof data["uniqueKey"] !== "string" || data["uniqueKey"] !== signedUniqueKey)) throw invalidGatewayResponse(response, body, url, "Gateway response data.uniqueKey must match the signed RequestTrade uniqueKey.");
-		} else if (mode === "queued" || !("result" in data)) throw invalidGatewayResponse(response, body, url, invalidModeMessage);
+		if (method === "RequestTrade" && mode === "queued") assertQueuedUnderSignedKey(response, body, url, data, signedBody);
+		else if (mode === "queued" || !("result" in data)) throw invalidGatewayResponse(response, body, url, invalidModeMessage);
 		if (mode === "sync") {
-			const embeddedResult = asRecord(data["result"]);
+			const embeddedResult = asRecord$1(data["result"]);
 			if (embeddedResult !== void 0) {
 				const resultStatus = embeddedResult["Status"];
 				if (resultStatus !== void 0 && resultStatus !== 1) throw GSwapSDKError.fromChainError(getStringProperty(embeddedResult, "ErrorKey") ?? "CHAIN_ERROR", getStringProperty(embeddedResult, "Message") ?? "The chain rejected this write.", {
@@ -746,12 +1221,68 @@ var ChainGateway = class {
 			blockNumber: blockNumber ?? null,
 			mode,
 			result: mode === "queued" ? void 0 : data["result"],
+			envelope: body,
 			dexBackendBaseUrl: this.dexBackendBaseUrl,
 			httpRequestor: this.requestor,
 			requestTimeoutMs: this.chainCallTimeoutMs,
+			wire: this.wire,
 			...(options === null || options === void 0 ? void 0 : options.positionConfirmation) === void 0 ? {} : { positionConfirmation: options.positionConfirmation }
 		});
 	}
+	/**
+	* Submit a signed v2 DTO as a SHADOW (dark) write: the same route and body as {@link submit},
+	* plus `X-Wallet-Address` and `X-Shadow: true`, so defi-backend marks the transaction private
+	* before it reaches the contract. The wallet address is required (the backend resolves the
+	* owner from it).
+	*
+	* Unlike `submit`, EVERY HTTP status resolves: the result is the raw `{ httpStatus, body }`,
+	* because shadow failures are classified from the status together with the body's `code`
+	* (`SHADOW_UNAVAILABLE`, `SHADOW_DISABLED`, `SHADOW_UNSUPPORTED_TYPE`, `SHADOW_RELAY_REJECTED`);
+	* see `readShadowSubmitOutcome`. Only a transport failure rejects, and a timeout rejects
+	* with `SUBMISSION_OUTCOME_UNKNOWN`.
+	*
+	* @example
+	* ```ts
+	* const result = await gateway.submitShadow('RequestTrade', signedDto, { walletAddress });
+	* const outcome = readShadowSubmitOutcome('RequestTrade', signedDto, result);
+	* ```
+	*/
+	async submitShadow(method, signedBody, options) {
+		if (method === "Trade") throw new GSwapSDKError("The synchronous Trade method was removed; swaps are queued through RequestTrade.", "METHOD_NOT_SUPPORTED", { method });
+		const walletAddress = (options === null || options === void 0 ? void 0 : options.walletAddress) ?? this.walletAddress;
+		if (walletAddress === void 0) throw new GSwapSDKError("A shadow submission needs a walletAddress (the X-Wallet-Address header): pass one to the GSwap constructor or to this call.", "NO_WALLET_ADDRESS");
+		const headers = buildRequestHeaders(this.wire, {
+			json: true,
+			fixed: {
+				"X-Wallet-Address": walletAddress,
+				"X-Shadow": "true"
+			}
+		});
+		const response = await this.post(this.writeUrl(method), headers, signedBody);
+		return {
+			httpStatus: response.status,
+			body: await readResponseBody(response)
+		};
+	}
+	writeUrl(method) {
+		return `${this.dexBackendBaseUrl}/v1/chain/asset/dex-contract/${method}`;
+	}
+	/** POSTs a signed body; a timeout means the outcome is unknown, never "not submitted". */
+	async post(url, headers, signedBody) {
+		try {
+			return await requestWithTimeout(this.requestor, url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(signedBody)
+			}, this.chainCallTimeoutMs);
+		} catch (error) {
+			if (error instanceof GSwapSDKError && error.code === "REQUEST_TIMEOUT") throw new GSwapSDKError("The submission outcome is unknown because the gateway request timed out. Confirm before retrying.", "SUBMISSION_OUTCOME_UNKNOWN", {
+				uniqueKey: getStringProperty(signedBody, "uniqueKey") ?? "",
+				cause: error
+			});
+			throw error;
+		}
+	}
 	/** Expose the requestor for sibling read services that share this gateway transport. */
 	get httpRequestor() {
 		return this.requestor;
@@ -767,11 +1298,34 @@ function invalidGatewayResponse(response, body, url, message) {
 		url
 	});
 }
+/**
+* A queued RequestTrade acknowledgement is a swap only if it names the exact key that was signed:
+* the key is the only handle `confirm()` and every recovery path have on the trade, so an
+* acknowledgement without it (or with another) proves nothing about THIS request. Fails closed:
+* an absent echo is as unacceptable as a wrong one. `INVALID_GATEWAY_RESPONSE`, `details.type` is
+* `MISSING_UNIQUE_KEY` or `UNIQUE_KEY_MISMATCH`, `details.uniqueKey` the signed key.
+*
+* Only RequestTrade is checked: a synchronous write is proven by its own executed chain result,
+* and the apps never required an echo for it.
+*/
+function assertQueuedUnderSignedKey(response, body, url, data, signedBody) {
+	const signedUniqueKey = getStringProperty(signedBody, "uniqueKey") ?? "";
+	const echoed = data["uniqueKey"];
+	if (typeof echoed === "string" && echoed !== "" && echoed === signedUniqueKey) return;
+	const missing = echoed === void 0 || echoed === null || echoed === "";
+	throw new GSwapSDKError(missing ? "The gateway acknowledged RequestTrade without echoing its uniqueKey, so it cannot be tied to the signed request." : "Gateway response data.uniqueKey must match the signed RequestTrade uniqueKey.", "INVALID_GATEWAY_RESPONSE", {
+		status: response.status,
+		body,
+		url,
+		type: missing ? "MISSING_UNIQUE_KEY" : "UNIQUE_KEY_MISMATCH",
+		uniqueKey: signedUniqueKey
+	});
+}
 function gatewayError(response, body, url) {
-	const object = asRecord(body);
+	const object = asRecord$1(body);
 	const nested = getObjectProperty(body, "error");
 	const code = getStringProperty(object, "code") ?? getStringProperty(nested, "code") ?? getStringProperty(nested, "ErrorKey") ?? "HTTP_ERROR";
-	const message = getStringProperty(object, "message") ?? getStringProperty(nested, "message") ?? getStringProperty(nested, "Message") ?? (typeof body === "string" ? body : `Gateway request failed with HTTP ${response.status}`);
+	const message = getStringProperty(object, "message") ?? getStringProperty(nested, "message") ?? getStringProperty(nested, "Message") ?? `Gateway request failed with HTTP ${response.status}`;
 	const retryAfterMs = response.status === 429 ? readRetryAfter(response) : void 0;
 	if (code === "HTTP_ERROR") return new GSwapSDKError(message, code, {
 		status: response.status,
@@ -780,7 +1334,7 @@ function gatewayError(response, body, url) {
 	});
 	return GSwapSDKError.fromGatewayBounce(code, message, response.status, retryAfterMs);
 }
-function asRecord(value) {
+function asRecord$1(value) {
 	return typeof value === "object" && value !== null ? value : void 0;
 }
 function isBlockNumber(value) {
@@ -871,6 +1425,11 @@ var GdexStreamError = class extends Error {
 		if (data !== void 0) this.data = data;
 	}
 };
+function readSubscriptionId(value) {
+	const id = typeof value === "object" && value !== null ? value.subscriptionId : void 0;
+	if (typeof id !== "string") throw new GdexStreamError(-32603, "GDEX subscribe response is missing its subscriptionId");
+	return id;
+}
 /**
 * Client for the gSwap realtime stream (gdex WebSocket Protocol v1): JSON-RPC 2.0 over one raw
 * WebSocket, with automatic reconnect and resubscribe.
@@ -887,6 +1446,7 @@ var GdexStreamError = class extends Error {
 var GdexStreamService = class {
 	url;
 	requestTimeoutMs;
+	apiKey;
 	webSocketConstructor;
 	backoff;
 	socket;
@@ -909,6 +1469,10 @@ var GdexStreamService = class {
 		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;
+		if (config.apiKey !== void 0) {
+			if (config.apiKey === "" || config.webSocketImpl === void 0) throw new GSwapSDKError("GdexStreamConfig.apiKey needs a non-empty key and an explicit webSocketImpl that accepts upgrade headers as its third argument (the \"ws\" package, or React Native). A browser WebSocket cannot send x-api-key, so the key would be silently dropped.", "VALIDATION_ERROR");
+			this.apiKey = config.apiKey;
+		}
 	}
 	/** Open the connection. Resolves at once when already connected. */
 	connect() {
@@ -936,6 +1500,9 @@ var GdexStreamService = class {
 	}
 	/** Raw JSON-RPC escape hatch. */
 	request(method, params) {
+		return this.send(method, params);
+	}
+	send(method, params, onResult) {
 		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 = {
@@ -952,7 +1519,8 @@ var GdexStreamService = class {
 			this.pending.set(id, {
 				resolve: (value) => resolve(value),
 				reject,
-				timeout
+				timeout,
+				onResult
 			});
 			try {
 				var _this$socket2;
@@ -1037,7 +1605,7 @@ var GdexStreamService = class {
 	openSocket() {
 		return new Promise((resolve, reject) => {
 			let opened = false;
-			const socket = new this.webSocketConstructor(this.url, GDEX_SUBPROTOCOL);
+			const socket = this.apiKey === void 0 ? new this.webSocketConstructor(this.url, GDEX_SUBPROTOCOL) : new this.webSocketConstructor(this.url, GDEX_SUBPROTOCOL, { headers: { "x-api-key": this.apiKey } });
 			this.socket = socket;
 			socket.onopen = () => {
 				if (this.socket !== socket) return;
@@ -1082,7 +1650,16 @@ var GdexStreamService = class {
 				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);
+			} else {
+				try {
+					var _pending$onResult;
+					(_pending$onResult = pending.onResult) === null || _pending$onResult === void 0 || _pending$onResult.call(pending, message.result);
+				} catch (error) {
+					pending.reject(error instanceof Error ? error : new Error(String(error)));
+					return;
+				}
+				pending.resolve(message.result);
+			}
 			return;
 		}
 		if (message.method !== "gdex_subscription" || !this.isRecord(message.params)) return;
@@ -1102,21 +1679,24 @@ var GdexStreamService = class {
 			channel,
 			...options
 		};
-		const result = await this.request("gdex_subscribe", params);
-		let active;
 		const handle = {
-			subscriptionId: result.subscriptionId,
-			unsubscribe: async () => this.unsubscribe(active)
+			subscriptionId: "",
+			unsubscribe: async () => this.unsubscribe(subscription)
 		};
-		active = {
-			serverId: result.subscriptionId,
+		const subscription = {
+			serverId: "",
 			params,
 			callback,
 			handle,
 			active: true
 		};
-		this.activeSubscriptions.add(active);
-		this.subscriptionsByServerId.set(active.serverId, active);
+		await this.send("gdex_subscribe", params, (value) => {
+			const serverId = readSubscriptionId(value);
+			subscription.serverId = serverId;
+			handle.subscriptionId = serverId;
+			this.activeSubscriptions.add(subscription);
+			this.subscriptionsByServerId.set(serverId, subscription);
+		});
 		return handle;
 	}
 	async unsubscribe(subscription) {
@@ -1159,19 +1739,19 @@ var GdexStreamService = class {
 				...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);
+			const result = await this.resubscribeWithRateLimitRetry(params, (value) => {
+				const serverId = readSubscriptionId(value);
+				if (!subscription.active) return;
+				subscription.serverId = serverId;
+				subscription.handle.subscriptionId = serverId;
+				this.subscriptionsByServerId.set(serverId, subscription);
+			});
+			if (!subscription.active) await this.request("gdex_unsubscribe", { subscriptionId: result.subscriptionId });
 		}
 	}
-	async resubscribeWithRateLimitRetry(params) {
+	async resubscribeWithRateLimitRetry(params, onResult) {
 		for (let attempt = 0;; attempt++) try {
-			return await this.request("gdex_subscribe", params);
+			return await this.send("gdex_subscribe", params, onResult);
 		} catch (error) {
 			if (!(error instanceof GdexStreamError) || error.code !== RATE_LIMITED || attempt >= MAX_RESUBSCRIBE_RATE_RETRIES) throw error;
 			const retryAfterMs = this.readRetryAfterMs(error.data);
@@ -1212,31 +1792,29 @@ var GdexStreamService = class {
 	}
 };
 
-//#endregion
-//#region src/version.ts
-/** Package version embedded by the bundler, with a source-test fallback. */
-const SDK_VERSION = "1.1.1";
-
 //#endregion
 //#region src/classes/http_client.ts
 var HttpClient = class {
 	httpRequestor;
 	timeoutMs;
-	/** Create an HTTP client around fetch or an injected requestor. */
-	constructor(httpRequestor = fetch, timeoutMs = 3e4) {
+	wire;
+	/**
+	* Create an HTTP client around fetch or an injected requestor. `wire` selects the query
+	* encoding and the `User-Agent` (see {@link WireOptions}).
+	*/
+	constructor(httpRequestor = fetch, timeoutMs = 3e4, wire = {}) {
 		this.httpRequestor = httpRequestor;
 		this.timeoutMs = timeoutMs;
+		this.wire = wire;
 	}
 	async sendRequest(method, baseUrl, basePath, endpoint, body, options) {
 		const url = `${baseUrl}${basePath}${endpoint}`;
 		debugLog(`Sending request to ${url} with body:`, body);
+		const hasBody = Boolean(body);
 		const response = await requestWithTimeout(this.httpRequestor, url, {
 			method,
-			headers: {
-				"Content-Type": "application/json",
-				"User-Agent": `GalaChain-SDK/${SDK_VERSION}`
-			},
-			...body ? { body: JSON.stringify(body) } : {},
+			headers: buildRequestHeaders(this.wire, { json: hasBody }),
+			...hasBody ? { body: JSON.stringify(body) } : {},
 			...(options === null || options === void 0 ? void 0 : options.signal) === void 0 ? {} : { signal: options.signal }
 		}, this.timeoutMs);
 		if (!response.ok) throw await GSwapSDKError.fromErrorResponse(url, response);
@@ -1250,12 +1828,65 @@ var HttpClient = class {
 	}
 	/** Send a GET request with URL-encoded query parameters and decode its response. */
 	async sendGetRequest(baseUrl, basePath, endpoint, params, options) {
-		const searchParams = params ? new URLSearchParams(params) : void 0;
-		const endpointWithParams = searchParams ? `${endpoint}?${searchParams.toString()}` : endpoint;
+		const endpointWithParams = params ? `${endpoint}?${buildQueryString(params, this.wire.queryEncoding)}` : endpoint;
 		return this.sendRequest("GET", baseUrl, basePath, endpointWithParams, void 0, options);
 	}
 };
 
+//#endregion
+//#region src/utils/lenient.ts
+/** A usable row. */
+function entryOk(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+/** An unusable row, with the reason it is reported under. */
+function entryRejected(reason) {
+	return {
+		ok: false,
+		reason
+	};
+}
+/**
+* Reads a list answer row by row: a row that cannot be used is skipped and reported, instead of
+* rejecting the whole list because of one bad row. An answer that is not a list at all is still
+* `INVALID_CHAIN_RESPONSE`: nothing in it can be trusted.
+*/
+function readEntries(source, data, parse, onInvalidEntry) {
+	if (!Array.isArray(data)) throw new GSwapSDKError(`Backend returned an invalid ${source} list.`, "INVALID_CHAIN_RESPONSE", { data });
+	const rows = [];
+	data.forEach((entry, index) => {
+		const parsed = parse(entry);
+		if (parsed.ok) {
+			rows.push(parsed.value);
+			return;
+		}
+		try {
+			onInvalidEntry === null || onInvalidEntry === void 0 || onInvalidEntry({
+				source,
+				index,
+				entry,
+				reason: parsed.reason
+			});
+		} catch {}
+	});
+	return rows;
+}
+/** A plain JSON object (not null, not an array). */
+function asEntryRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** A finite number, or a non-empty numeric string, as a number; otherwise `undefined`. */
+function finiteNumberOf(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+
 //#endregion
 //#region src/utils/ordering.ts
 /** Return two trading symbols in the contract's plain-string order. */
@@ -1335,41 +1966,252 @@ function parseTokenClassKey(tokenClassKey) {
 }
 
 //#endregion
-//#region src/classes/pools.ts
-/** Read-only pool and current-price access for the current GalaChainDex contract. */
-var Pools = class {
+//#region src/classes/symbols.ts
+const SYMBOL_CACHE_TTL_MS = 6e4;
+/** Symbol registry client for the current GalaChainDex contract. */
+var Symbols = class {
 	gateway;
-	symbols;
+	options;
+	cachedSymbols;
+	cachedAt = 0;
+	refreshInFlight;
+	http;
 	/**
-	* Creates a pool service.
-	*
-	* @example
-	* ```ts
-	* const pools = new Pools(gateway, symbols);
-	* ```
+	* Create a symbol service backed by the swap backend. `onInvalidEntry` is told about every
+	* registry row that was skipped as unusable (see {@link InvalidEntryHandler}).
 	*/
-	constructor(gateway, symbols) {
+	constructor(gateway, options = {}) {
 		this.gateway = gateway;
-		this.symbols = symbols;
-		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs ?? 3e4);
+		this.options = options;
+		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs, gateway.wire);
 	}
-	http;
 	/**
-	* Fetches every current-contract pool from the swap backend.
+	* List all registered GalaChainDex trading symbols, cached for 60 seconds. A registry row that
+	* is not a usable symbol is skipped (and reported to `onInvalidEntry`) instead of failing the
+	* whole list.
+	*/
+	async list() {
+		if (this.cachedSymbols !== void 0 && Date.now() - this.cachedAt < SYMBOL_CACHE_TTL_MS) return this.cachedSymbols;
+		if (this.refreshInFlight !== void 0) return this.refreshInFlight;
+		this.refreshInFlight = this.http.sendGetRequest(this.gateway.dexBackendBaseUrl, "/v2/trade", "/symbols").then((response) => readEntries("symbols", response.data, parseTradingSymbol, this.options.onInvalidEntry)).then((symbols) => {
+			this.cachedSymbols = symbols;
+			this.cachedAt = Date.now();
+			return symbols;
+		}).finally(() => {
+			this.refreshInFlight = void 0;
+		});
+		return this.refreshInFlight;
+	}
+	/** Invalidate the cached symbol registry after a write changes registration state.
 	*
 	* @example
 	* ```ts
-	* const pools = await service.getPools();
-	* console.log(pools.length);
+	* gSwap.symbols.invalidate();
 	* ```
 	*/
-	async getPools(options) {
-		const response = await this.http.sendGetRequest(this.gateway.dexBackendBaseUrl, "/v2/trade", "/pools", void 0, (options === null || options === void 0 ? void 0 : options.signal) === void 0 ? void 0 : { signal: options.signal });
-		if (!Array.isArray(response.data) || !response.data.every(isPoolListInfo)) throw new GSwapSDKError("Backend returned an invalid pool list.", "INVALID_CHAIN_RESPONSE", { data: response.data });
-		return response.data;
+	invalidate() {
+		this.cachedSymbols = void 0;
+		this.cachedAt = 0;
 	}
-	/**
-	* Fetches one pool from the backend, preserving whether the request order was flipped.
+	/** Force one registry refresh, bypassing the cache.
+	*
+	* @example
+	* ```ts
+	* const symbols = await gSwap.symbols.refresh();
+	* ```
+	*/
+	async refresh() {
+		this.invalidate();
+		this.refreshInFlight = void 0;
+		return this.list();
+	}
+	/** Resolve a symbol or token class key to its registered symbol metadata. */
+	async resolve(ref) {
+		let symbols = await this.list();
+		const composite = typeof ref === "string" ? isCompositeKey(ref) ? compositeKeyOf(parseTokenClassKey(ref)) : void 0 : compositeKeyOf(ref);
+		const resolved = symbols.find((entry) => entry.symbol === ref || composite !== void 0 && compositeKeyOf(entry) === composite);
+		if (resolved === void 0) {
+			symbols = await this.refresh();
+			const refreshed = symbols.find((entry) => entry.symbol === ref || composite !== void 0 && compositeKeyOf(entry) === composite);
+			if (refreshed === void 0) throw GSwapSDKError.unknownTokenError(ref);
+			return refreshed;
+		}
+		return resolved;
+	}
+	/**
+	* The trading symbol to put in a token's first CreatePool.
+	*
+	* 1. The symbol ALREADY registered for exactly this class key, if any: proposing another one
+	*    fails the gateway's registry-conflict check.
+	* 2. Otherwise `displaySymbol` (the token's curated symbol), when it is proposable
+	*    ({@link isProposableTradingSymbol}).
+	* 3. Otherwise a `VALIDATION_ERROR`: a symbol is never derived from the key (BNB's collection is
+	*    `GBNB`, a launchpad token's is the reserved word `Token`).
+	*
+	* `registryFailure: 'ignore'` treats an unreachable registry as an empty one and falls through
+	* to step 2 (the gateway still rejects a conflicting symbol); the default `'throw'` propagates
+	* the failure.
+	*
+	* @example
+	* ```ts
+	* const symbol = await gSwap.symbols.proposeSymbol(
+	*   { collection: 'GALA_TEST1', category: 'Unit', type: 'none', additionalKey: 'none' },
+	*   'GALATEST',
+	* );
+	* ```
+	*/
+	async proposeSymbol(classKey, displaySymbol, options = {}) {
+		let registry = [];
+		try {
+			registry = await this.list();
+		} catch (error) {
+			if (options.registryFailure !== "ignore") throw error;
+		}
+		const wanted = compositeKeyOf(classKey);
+		const registered = registry.find((entry) => entry.collection === classKey.collection && entry.category === classKey.category && entry.type === classKey.type && entry.additionalKey === classKey.additionalKey);
+		if (registered !== void 0) return registered.symbol;
+		if (isProposableTradingSymbol(displaySymbol)) return displaySymbol;
+		throw new GSwapSDKError(`No valid trading symbol for token class ${wanted}: "${displaySymbol}" is not an acceptable symbol and none is registered`, "VALIDATION_ERROR", {
+			classKey,
+			displaySymbol
+		});
+	}
+	/** Resolve and put two token references in canonical trading-symbol order. */
+	async orderPair(a, b) {
+		const [resolvedA, resolvedB] = await Promise.all([this.resolve(a), this.resolve(b)]);
+		const [token0Symbol, token1Symbol] = orderSymbols(resolvedA.symbol, resolvedB.symbol);
+		return {
+			token0: token0Symbol === resolvedA.symbol ? resolvedA : resolvedB,
+			token1: token1Symbol === resolvedB.symbol ? resolvedB : resolvedA,
+			flipped: token0Symbol !== resolvedA.symbol
+		};
+	}
+};
+/** Reads one registry row: all four class-key parts, a symbol and non-negative integer decimals. */
+function parseTradingSymbol(value) {
+	const entry = asEntryRecord(value);
+	if (entry === void 0) return entryRejected("the row is not an object");
+	const { symbol, collection, category, type, additionalKey, decimals } = entry;
+	if (typeof symbol !== "string") return entryRejected("symbol is not a string");
+	if (symbol.length === 0) return entryRejected("symbol is empty");
+	if (typeof collection !== "string") return entryRejected("collection is not a string");
+	if (typeof category !== "string") return entryRejected("category is not a string");
+	if (typeof type !== "string") return entryRejected("type is not a string");
+	if (typeof additionalKey !== "string") return entryRejected("additionalKey is not a string");
+	if (typeof decimals !== "number" || !Number.isInteger(decimals) || decimals < 0) return entryRejected("decimals is not a non-negative integer");
+	return entryOk({
+		symbol,
+		collection,
+		category,
+		type,
+		additionalKey,
+		decimals
+	});
+}
+function isCompositeKey(ref) {
+	return ref.includes("|") || ref.includes("$");
+}
+/** A token reference as the caller wrote it: a string verbatim, a class key as its `$` composite. */
+function rawTokenOf(ref) {
+	return typeof ref === "string" ? ref : compositeKeyOf(ref);
+}
+/** The trading symbol of a reference, or `SYMBOL_NOT_FOUND` when the resolver has none. */
+async function tradingSymbolOf(resolver, ref) {
+	const resolved = await resolver.resolve(ref);
+	if (resolved.symbol.length > 0) return resolved.symbol;
+	throw new GSwapSDKError("Token could not be resolved to a trading symbol.", "SYMBOL_NOT_FOUND", { token: ref });
+}
+/** What a read request names a token by: the reference itself in pass-through mode, else its symbol. */
+async function queryTokenOf(resolver, ref) {
+	return resolver.passthrough === true ? rawTokenOf(ref) : tradingSymbolOf(resolver, ref);
+}
+/**
+* The offline resolver for apps that already hold the backend's canonical trading symbols (from
+* `/quote`, `/add-liq-estimate`, a position row) and must not make a registry request of their own.
+*
+* - `resolve` accepts a bare trading symbol and returns it as is; a class key (object, `$` or `|`
+*   form) is not a symbol and is refused as `UNKNOWN_TOKEN`. `createPool` relies on that refusal to
+*   fall back to the symbols its caller supplies.
+* - `orderPair` orders two symbols by plain string comparison, as the contract does.
+* - Reads are pass-through (see {@link TokenResolver.passthrough}): the caller's references go on
+*   the wire verbatim, composite keys included, and the backend orients the pair.
+*
+* @example
+* ```ts
+* const swaps = new Swaps(gateway, new CanonicalSymbols(), signer, walletAddress);
+* await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '10' });
+* ```
+*/
+var CanonicalSymbols = class {
+	passthrough = true;
+	/** Resolve a bare trading symbol to itself. */
+	resolve(ref) {
+		if (typeof ref === "string" && !isCompositeKey(ref)) return Promise.resolve({
+			symbol: ref,
+			collection: "",
+			category: "",
+			type: "",
+			additionalKey: "",
+			decimals: 0
+		});
+		return Promise.reject(GSwapSDKError.unknownTokenError(ref));
+	}
+	/** Put two symbols in canonical (string) order. */
+	async orderPair(a, b) {
+		const [resolvedA, resolvedB] = await Promise.all([this.resolve(a), this.resolve(b)]);
+		const [first] = orderSymbols(resolvedA.symbol, resolvedB.symbol);
+		const flipped = first !== resolvedA.symbol;
+		return {
+			token0: flipped ? resolvedB : resolvedA,
+			token1: flipped ? resolvedA : resolvedB,
+			flipped
+		};
+	}
+	/** There is no registry state to drop. */
+	invalidate() {}
+};
+
+//#endregion
+//#region src/classes/pools.ts
+/** Read-only pool and current-price access for the current GalaChainDex contract. */
+var Pools = class {
+	gateway;
+	symbols;
+	options;
+	/**
+	* Creates a pool service. `options.onInvalidEntry` is told about every pool row that was
+	* skipped as unusable (see {@link InvalidEntryHandler}).
+	*
+	* @example
+	* ```ts
+	* const pools = new Pools(gateway, symbols);
+	* ```
+	*/
+	constructor(gateway, symbols, options = {}) {
+		this.gateway = gateway;
+		this.symbols = symbols;
+		this.options = options;
+		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs ?? 3e4, gateway.wire);
+	}
+	http;
+	/**
+	* Fetches current-contract pools from the swap backend, optionally searched, sorted and paged
+	* by the backend. A row that is not a usable pool is skipped and reported to `onInvalidEntry`
+	* instead of failing the whole list; an answer that is not a list at all is
+	* `INVALID_CHAIN_RESPONSE`.
+	*
+	* @example
+	* ```ts
+	* const top = await service.getPools({ sortBy: 'tvl', sortOrder: 'desc', page: 1, limit: 8 });
+	* console.log(top.length);
+	* ```
+	*/
+	async getPools(options) {
+		const response = await this.http.sendGetRequest(this.gateway.dexBackendBaseUrl, "/v2/trade", "/pools", poolListParams(options), (options === null || options === void 0 ? void 0 : options.signal) === void 0 ? void 0 : { signal: options.signal });
+		return readEntries("pools", response.data, parsePoolListInfo, (options === null || options === void 0 ? void 0 : options.onInvalidEntry) ?? this.options.onInvalidEntry);
+	}
+	/**
+	* Fetches one pool from the backend, preserving whether the request order was flipped.
 	*
 	* @example
 	* ```ts
@@ -1405,8 +2247,13 @@ var Pools = class {
 	*/
 	async getCompositePool(token0, token1, fee) {
 		validateFee(fee);
-		const first = await resolveSymbol$2(this.symbols, token0);
-		const second = await resolveSymbol$2(this.symbols, token1);
+		if (this.symbols.passthrough === true) return this.getBackend("/composite-pool", {
+			token0: rawTokenOf(token0),
+			token1: rawTokenOf(token1),
+			fee: String(fee)
+		});
+		const first = await tradingSymbolOf(this.symbols, token0);
+		const second = await tradingSymbolOf(this.symbols, token1);
 		const ordered = readOrderedSymbols(orderSymbols(first, second));
 		return this.getBackend("/composite-pool", {
 			token0: ordered.token0,
@@ -1416,8 +2263,8 @@ var Pools = class {
 	}
 	async backendParams(token0, token1, fee) {
 		return {
-			token0: await resolveSymbol$2(this.symbols, token0),
-			token1: await resolveSymbol$2(this.symbols, token1),
+			token0: await queryTokenOf(this.symbols, token0),
+			token1: await queryTokenOf(this.symbols, token1),
 			fee: String(fee)
 		};
 	}
@@ -1430,52 +2277,448 @@ var Pools = class {
 		}
 	}
 };
-async function resolveSymbol$2(symbols, token) {
-	const resolved = await symbols.resolve(token);
-	if (resolved.symbol.length > 0) return resolved.symbol;
-	throw new GSwapSDKError("Token could not be resolved to a trading symbol.", "SYMBOL_NOT_FOUND", { token });
+const SORT_KEYS = [
+	"tvl",
+	"volume1d",
+	"volume30d"
+];
+const MAX_SEARCH_LENGTH = 64;
+const MAX_PAGE_SIZE = 1e3;
+/** The pool-list query, in the order the apps write it: search, sortBy, sortOrder, page, limit. */
+function poolListParams(options) {
+	if (options === void 0) return void 0;
+	const params = {};
+	if (options.search !== void 0) {
+		if (options.search.length > MAX_SEARCH_LENGTH) throw new GSwapSDKError(`search must be at most ${MAX_SEARCH_LENGTH} characters.`, "VALIDATION_ERROR", { search: options.search });
+		params["search"] = options.search;
+	}
+	if (options.sortBy !== void 0) {
+		if (!SORT_KEYS.includes(options.sortBy)) throw new GSwapSDKError(`sortBy must be one of ${SORT_KEYS.join(", ")}.`, "VALIDATION_ERROR", { sortBy: options.sortBy });
+		params["sortBy"] = options.sortBy;
+	}
+	if (options.sortOrder !== void 0) {
+		if (options.sortOrder !== "asc" && options.sortOrder !== "desc") throw new GSwapSDKError("sortOrder must be asc or desc.", "VALIDATION_ERROR", { sortOrder: options.sortOrder });
+		params["sortOrder"] = options.sortOrder;
+	}
+	if (options.page !== void 0) {
+		if (!Number.isInteger(options.page) || options.page < 1) throw new GSwapSDKError("page must be an integer of at least 1.", "VALIDATION_ERROR", { page: options.page });
+		params["page"] = String(options.page);
+	}
+	if (options.limit !== void 0) {
+		if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > MAX_PAGE_SIZE) throw new GSwapSDKError(`limit must be an integer from 1 to ${MAX_PAGE_SIZE}.`, "VALIDATION_ERROR", { limit: options.limit });
+		params["limit"] = String(options.limit);
+	}
+	return Object.keys(params).length === 0 ? void 0 : params;
 }
-function isPoolListInfo(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const row = value;
-	return row["contractVersion"] === "v2" && typeof row["token0"] === "string" && typeof row["token1"] === "string" && typeof row["poolName"] === "string" && typeof row["poolRef"] === "string" && [
-		"fee",
-		"tickSpacing",
-		"protocolFees",
-		"tradingFees"
-	].every((key) => isFiniteNumber(row[key])) && [
-		"token0CompositeKey",
-		"token1CompositeKey",
-		"creator",
-		"price",
-		"sqrtPrice",
-		"token0Tvl",
-		"token1Tvl"
-	].every((key) => isOptionalString(row[key])) && [
-		"tick",
-		"tvlUsd",
-		"volume1d",
-		"volume7d",
-		"volume30d",
-		"trades1d",
-		"fee24h",
-		"apr1d",
-		"token0Price",
-		"token1Price"
-	].every((key) => isOptionalNumber(row[key]));
-}
-function isFiniteNumber(value) {
-	return typeof value === "number" && Number.isFinite(value);
-}
-function isOptionalString(value) {
-	return value === void 0 || typeof value === "string";
-}
-function isOptionalNumber(value) {
-	return value === void 0 || isFiniteNumber(value);
+const OPTIONAL_POOL_STRINGS = [
+	"poolName",
+	"token0CompositeKey",
+	"token1CompositeKey",
+	"token0Image",
+	"token1Image",
+	"creator",
+	"price",
+	"sqrtPrice",
+	"token0Tvl",
+	"token1Tvl"
+];
+const OPTIONAL_POOL_NUMBERS = [
+	"tickSpacing",
+	"protocolFees",
+	"tradingFees",
+	"tick",
+	"volume1d",
+	"volume7d",
+	"volume30d",
+	"trades1d",
+	"fee24h",
+	"token0Price",
+	"token1Price"
+];
+/** Fields the apps accept as a number or a numeric string (the wallet does `Number(row.x)`). */
+const NUMERIC_POOL_FIELDS = [
+	"fee",
+	"tvlUsd",
+	"apr1d"
+];
+/**
+* Reads one pool-list row the way the apps do: the identity (`token0`, `token1`, `poolRef`) and
+* `fee` must be usable, every other field is optional but, when present, must have its type.
+* `fee`, `tvlUsd` and `apr1d` may arrive as numeric strings and are returned as numbers. Fields
+* the SDK does not know are kept.
+*/
+function parsePoolListInfo(entry) {
+	const row = asEntryRecord(entry);
+	if (row === void 0) return entryRejected("the row is not an object");
+	for (const key of [
+		"token0",
+		"token1",
+		"poolRef"
+	]) if (typeof row[key] !== "string") return entryRejected(`${key} is not a string`);
+	if (row["contractVersion"] !== void 0 && row["contractVersion"] !== "v2") return entryRejected("contractVersion is not v2");
+	const normalized = { ...row };
+	for (const key of NUMERIC_POOL_FIELDS) {
+		const raw = row[key];
+		if (raw === void 0 && key !== "fee") continue;
+		const value = finiteNumberOf(raw);
+		if (value === void 0) return entryRejected(`${key} is not a number`);
+		normalized[key] = value;
+	}
+	for (const key of OPTIONAL_POOL_STRINGS) if (row[key] !== void 0 && typeof row[key] !== "string") return entryRejected(`${key} is not a string`);
+	for (const key of OPTIONAL_POOL_NUMBERS) {
+		const value = row[key];
+		if (value !== void 0 && (typeof value !== "number" || !Number.isFinite(value))) return entryRejected(`${key} is not a number`);
+	}
+	return entryOk(normalized);
+}
+
+//#endregion
+//#region src/utils/unique_key.ts
+/**
+* The `uniqueKey` prefix frontend_v2 and wallet_extension have always sent
+* (`galaswap-operation-<uuid>`). defi-backend does not depend on it: the chain-write verifier
+* only requires a non-empty key of at most 256 characters, and apply-results accepts
+* `[A-Za-z0-9._:-]{1,128}`; the only code that mints a prefixed key itself is the server-side v1
+* trade builder, which nothing reads back by prefix.
+*/
+const DEFAULT_UNIQUE_KEY_PREFIX = "galaswap-operation-";
+/** A canonical UUID is 36 characters; the apply-results key limit is 128. */
+const MAX_UNIQUE_KEY_PREFIX_LENGTH = 92;
+const UNIQUE_KEY_PREFIX_PATTERN = /^[A-Za-z0-9._:-]*$/u;
+/**
+* Validates a caller-supplied `uniqueKey` prefix. The whole key (`<prefix><uuid>`) must stay a
+* valid apply-results key, otherwise `confirm()` could never read the outcome of the write.
+*
+* @throws GSwapSDKError VALIDATION_ERROR when the prefix has characters outside `A-Za-z0-9._:-` or
+* is longer than 92 characters.
+*/
+function resolveUniqueKeyPrefix(prefix) {
+	if (prefix === void 0) return DEFAULT_UNIQUE_KEY_PREFIX;
+	if (!UNIQUE_KEY_PREFIX_PATTERN.test(prefix) || prefix.length > MAX_UNIQUE_KEY_PREFIX_LENGTH) throw new GSwapSDKError(`uniqueKeyPrefix must be at most ${MAX_UNIQUE_KEY_PREFIX_LENGTH} characters of A-Z, a-z, 0-9, ".", "_", ":" or "-".`, "VALIDATION_ERROR", { uniqueKeyPrefix: prefix });
+	return prefix;
+}
+/** The swap backend's apply-results key constraint (`apply-results.dto.ts`). */
+const UNIQUE_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/u;
+/**
+* Validates a caller-supplied write `uniqueKey`: 1 to 128 characters of `A-Za-z0-9._:-`, the
+* shape the apply-results route accepts, so the write's outcome can always be read back with
+* `confirm()`. A key is one attempt's identity: reuse it only to retry that same attempt.
+*
+* @throws GSwapSDKError VALIDATION_ERROR otherwise.
+*/
+function assertUniqueKey(uniqueKey) {
+	if (typeof uniqueKey !== "string" || !UNIQUE_KEY_PATTERN.test(uniqueKey)) throw new GSwapSDKError("uniqueKey must be 1-128 characters of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\".", "VALIDATION_ERROR", { uniqueKey });
+}
+/** A fresh per-attempt key: `<prefix><random UUID>`. */
+function createUniqueKey(prefix) {
+	return `${prefix}${globalThis.crypto.randomUUID()}`;
+}
+
+//#endregion
+//#region src/utils/dto_builders.ts
+const decimalString = (amount) => new bignumber_js.default(amount).toFixed();
+/**
+* Builds the RequestTrade DTO: `exactIn` sells that much of the input token (`sell0Qty` or
+* `sell1Qty`), `exactOut` buys that much of the output token (`buy1Qty` or `buy0Qty`), plus the
+* side's slippage bound and an optional `priceLimit`. Key order: `token0, token1, fee, uniqueKey,
+* <quantity>, amountOutMinimum | amountInMaximum, priceLimit`.
+*
+* @example
+* ```ts
+* const dto = buildRequestTradeDto({
+*   token0: quote.token0Symbol, token1: quote.token1Symbol,
+*   tokenInIsToken0: quote.tokenInIsToken0, fee: quote.fee,
+*   uniqueKey: createUniqueKey('galaswap-operation-'),
+*   exactIn: '100', amountOutMinimum: '14',
+* });
+* ```
+*/
+function buildRequestTradeDto(input) {
+	validateFee(input.fee);
+	assertCanonicalPair(input.token0, input.token1);
+	assertUniqueKey(input.uniqueKey);
+	const dto = {
+		token0: input.token0,
+		token1: input.token1,
+		fee: input.fee,
+		uniqueKey: input.uniqueKey
+	};
+	if ("exactIn" in input) {
+		const exactIn = input.exactIn;
+		if (exactIn === void 0) throw new GSwapSDKError("exactIn is required for an exact-input swap.", "VALIDATION_ERROR");
+		validateNumericAmount(exactIn, "exactIn");
+		dto[input.tokenInIsToken0 ? "sell0Qty" : "sell1Qty"] = decimalString(exactIn);
+		if (input.amountOutMinimum !== void 0) {
+			validateNumericAmount(input.amountOutMinimum, "amountOutMinimum", true);
+			dto["amountOutMinimum"] = decimalString(input.amountOutMinimum);
+		}
+	} else {
+		const exactOut = input.exactOut;
+		if (exactOut === void 0) throw new GSwapSDKError("exactOut is required for an exact-output swap.", "VALIDATION_ERROR");
+		validateNumericAmount(exactOut, "exactOut");
+		dto[input.tokenInIsToken0 ? "buy1Qty" : "buy0Qty"] = decimalString(exactOut);
+		if (input.amountInMaximum !== void 0) {
+			validateNumericAmount(input.amountInMaximum, "amountInMaximum", true);
+			dto["amountInMaximum"] = decimalString(input.amountInMaximum);
+		}
+	}
+	if (input.priceLimit !== void 0) {
+		validateNumericAmount(input.priceLimit, "priceLimit");
+		dto["priceLimit"] = decimalString(input.priceLimit);
+	}
+	return dto;
+}
+function assertPoolPosition(input) {
+	validateFee(input.fee);
+	assertCanonicalPair(input.token0, input.token1);
+	assertTickRange(input.tickLower, input.tickUpper, input.fee);
+	assertUniqueKey(input.uniqueKey);
+}
+/**
+* Builds the AddLiquidity DTO: exactly one of `depositQuantityToken0` / `depositQuantityToken1`
+* (the other side is derived on chain). Key order: `token0, token1, fee, tickLower, tickUpper,
+* uniqueKey, <deposit>`.
+*/
+function buildAddLiquidityDto(input) {
+	assertPoolPosition(input);
+	const side = onlyOne(input.depositQuantityToken0, input.depositQuantityToken1, "depositQuantityToken0", "depositQuantityToken1");
+	if (side === void 0) throw new GSwapSDKError("Provide exactly one of depositQuantityToken0 or depositQuantityToken1.", "VALIDATION_ERROR");
+	validateNumericAmount(side.amount, side.name);
+	return {
+		token0: input.token0,
+		token1: input.token1,
+		fee: input.fee,
+		tickLower: input.tickLower,
+		tickUpper: input.tickUpper,
+		uniqueKey: input.uniqueKey,
+		[side.name]: decimalString(side.amount)
+	};
+}
+/**
+* Builds the RemoveLiquidity DTO: at most one of `withdrawalQuantityToken0` /
+* `withdrawalQuantityToken1`; omitting both closes the position and sweeps its fees.
+*/
+function buildRemoveLiquidityDto(input) {
+	assertPoolPosition(input);
+	const side = onlyOne(input.withdrawalQuantityToken0, input.withdrawalQuantityToken1, "withdrawalQuantityToken0", "withdrawalQuantityToken1", true);
+	if (side !== void 0) validateNumericAmount(side.amount, side.name);
+	return {
+		token0: input.token0,
+		token1: input.token1,
+		fee: input.fee,
+		tickLower: input.tickLower,
+		tickUpper: input.tickUpper,
+		uniqueKey: input.uniqueKey,
+		...side === void 0 ? {} : { [side.name]: decimalString(side.amount) }
+	};
+}
+/** Builds the CollectPositionFees DTO (the contract sweeps all of a position's fees). */
+function buildCollectPositionFeesDto(input) {
+	assertPoolPosition(input);
+	return {
+		token0: input.token0,
+		token1: input.token1,
+		fee: input.fee,
+		tickLower: input.tickLower,
+		tickUpper: input.tickUpper,
+		uniqueKey: input.uniqueKey
+	};
+}
+/**
+* Builds the CreatePool DTO. Key order: `token0Key, token1Key, fee, startingPrice |
+* startingSqrtPrice, token0Symbol, token1Symbol, uniqueKey, name, isPrivate, privateAccess`.
+* Prices are those of the canonical pair (token1 per token0); a price quoted the other way round
+* is inverted by the caller before it gets here.
+*/
+function buildCreatePoolDto(input) {
+	validateFee(input.fee);
+	assertUniqueKey(input.uniqueKey);
+	assertCanonicalPair(input.token0Symbol, input.token1Symbol);
+	for (const symbol of [input.token0Symbol, input.token1Symbol]) if (!isProposableTradingSymbol(symbol)) throw new GSwapSDKError("Invalid trading symbol: must be 1-32 ASCII letters and digits and not a reserved word (Token, Unit, none).", "VALIDATION_ERROR", { symbol });
+	for (const key of [input.token0Key, input.token1Key]) assertClassKey(key);
+	const price = onlyOne(input.startingPrice, input.startingSqrtPrice, "startingPrice", "startingSqrtPrice");
+	if (price === void 0) throw new GSwapSDKError("Provide exactly one of startingPrice or startingSqrtPrice.", "VALIDATION_ERROR");
+	if (typeof price.amount === "number") throw new GSwapSDKError(`Invalid ${price.name}: use a decimal string or BigNumber, not a JavaScript number`, "VALIDATION_ERROR");
+	const parsed = new bignumber_js.default(price.amount);
+	if (!parsed.isFinite() || parsed.isLessThanOrEqualTo(0)) throw new GSwapSDKError("Starting price must be finite and positive.", "VALIDATION_ERROR");
+	return {
+		token0Key: input.token0Key,
+		token1Key: input.token1Key,
+		fee: input.fee,
+		[price.name]: parsed.toFixed(),
+		token0Symbol: input.token0Symbol,
+		token1Symbol: input.token1Symbol,
+		uniqueKey: input.uniqueKey,
+		...input.name === void 0 || input.name === "" ? {} : { name: input.name },
+		...input.isPrivate === void 0 ? {} : { isPrivate: input.isPrivate },
+		...input.privateAccess === void 0 ? {} : { privateAccess: input.privateAccess }
+	};
+}
+function assertClassKey(key) {
+	for (const part of [
+		"collection",
+		"category",
+		"type",
+		"additionalKey"
+	]) if (typeof key[part] !== "string" || key[part].length === 0) throw new GSwapSDKError(`Token class key is missing ${part}.`, "VALIDATION_ERROR", { key });
+}
+/**
+* Of two mutually exclusive fields, the one that is set (`undefined` when neither is);
+* both set is a `VALIDATION_ERROR`, and so is neither unless `allowNeither`.
+*/
+function onlyOne(first, second, firstName, secondName, allowNeither = false) {
+	if (first !== void 0 && second !== void 0) throw new GSwapSDKError(allowNeither ? `Provide at most one of ${firstName} or ${secondName}.` : `Provide exactly one of ${firstName} or ${secondName}.`, "VALIDATION_ERROR");
+	if (first !== void 0) return {
+		name: firstName,
+		amount: first
+	};
+	if (second !== void 0) return {
+		name: secondName,
+		amount: second
+	};
+}
+function invalidDto(method, field, expected) {
+	return new GSwapSDKError(`${method} DTO field ${field} must be ${expected}.`, "VALIDATION_ERROR", {
+		type: "INVALID_DTO",
+		method,
+		field
+	});
+}
+/**
+* Rebuilds a DTO from its own fields with the builder of its method: the canonical form of the
+* DTO, with the same validation. Key order and decimal text are the builder's.
+*/
+function rebuildV2Dto(method, dto) {
+	const text = (field) => {
+		const value = dto[field];
+		if (typeof value !== "string") throw invalidDto(method, field, "a string");
+		return value;
+	};
+	const integer = (field) => {
+		const value = dto[field];
+		if (typeof value !== "number") throw invalidDto(method, field, "a number");
+		return value;
+	};
+	const optionalText = (field) => dto[field] === void 0 ? void 0 : text(field);
+	const classKey = (field) => {
+		const value = dto[field];
+		if (typeof value !== "object" || value === null) throw invalidDto(method, field, "a class key");
+		const key = value;
+		const part = (name) => {
+			if (typeof key[name] !== "string") throw invalidDto(method, `${field}.${name}`, "a string");
+			return key[name];
+		};
+		return {
+			collection: part("collection"),
+			category: part("category"),
+			type: part("type"),
+			additionalKey: part("additionalKey")
+		};
+	};
+	const base = () => ({
+		token0: text("token0"),
+		token1: text("token1"),
+		fee: integer("fee")
+	});
+	const uniqueKey = text("uniqueKey");
+	const position = () => ({
+		...base(),
+		uniqueKey,
+		tickLower: integer("tickLower"),
+		tickUpper: integer("tickUpper")
+	});
+	switch (method) {
+		case "RequestTrade": {
+			const qty = [
+				"sell0Qty",
+				"sell1Qty",
+				"buy0Qty",
+				"buy1Qty"
+			].filter((f) => dto[f] !== void 0);
+			const [field] = qty;
+			if (qty.length !== 1 || field === void 0) throw invalidDto(method, "sell0Qty|sell1Qty|buy0Qty|buy1Qty", "present exactly once");
+			const tokenInIsToken0 = field === "sell0Qty" || field === "buy1Qty";
+			const shared = {
+				...base(),
+				uniqueKey,
+				tokenInIsToken0
+			};
+			const priceLimit = optionalText("priceLimit");
+			return field.startsWith("sell") ? buildRequestTradeDto({
+				...shared,
+				exactIn: text(field),
+				amountOutMinimum: optionalText("amountOutMinimum"),
+				priceLimit
+			}) : buildRequestTradeDto({
+				...shared,
+				exactOut: text(field),
+				amountInMaximum: optionalText("amountInMaximum"),
+				priceLimit
+			});
+		}
+		case "AddLiquidity": {
+			const token0Side = optionalText("depositQuantityToken0");
+			const token1Side = optionalText("depositQuantityToken1");
+			return buildAddLiquidityDto({
+				...position(),
+				...token0Side === void 0 ? { depositQuantityToken1: token1Side } : { depositQuantityToken0: token0Side }
+			});
+		}
+		case "RemoveLiquidity": return buildRemoveLiquidityDto({
+			...position(),
+			withdrawalQuantityToken0: optionalText("withdrawalQuantityToken0"),
+			withdrawalQuantityToken1: optionalText("withdrawalQuantityToken1")
+		});
+		case "CollectPositionFees": return buildCollectPositionFeesDto(position());
+		case "CreatePool": {
+			const price = optionalText("startingPrice");
+			const sqrtPrice = optionalText("startingSqrtPrice");
+			const privateAccess = dto["privateAccess"];
+			if (privateAccess !== void 0 && (!Array.isArray(privateAccess) || privateAccess.some((entry) => typeof entry !== "string"))) throw invalidDto(method, "privateAccess", "an array of strings");
+			if (dto["isPrivate"] !== void 0 && typeof dto["isPrivate"] !== "boolean") throw invalidDto(method, "isPrivate", "a boolean");
+			return buildCreatePoolDto({
+				token0Key: classKey("token0Key"),
+				token1Key: classKey("token1Key"),
+				token0Symbol: text("token0Symbol"),
+				token1Symbol: text("token1Symbol"),
+				fee: integer("fee"),
+				uniqueKey,
+				name: optionalText("name"),
+				isPrivate: dto["isPrivate"],
+				privateAccess,
+				...price === void 0 ? { startingSqrtPrice: sqrtPrice } : { startingPrice: price }
+			});
+		}
+	}
+}
+/**
+* Asserts that `dto` is EXACTLY what the builder of `method` produces for its own fields — the
+* same fields, canonical decimal text, builder key order, nothing extra (no `signature`). The
+* `submit*` methods use it so that what an app showed a user (a DTO it built) is byte for byte
+* what gets signed; a DTO edited by hand, or built elsewhere, is refused rather than signed.
+*
+* @throws GSwapSDKError VALIDATION_ERROR (`details.type` = `INVALID_DTO` or `DTO_NOT_CANONICAL`).
+*/
+function assertCanonicalV2Dto(method, dto) {
+	const rebuilt = rebuildV2Dto(method, dto);
+	if (JSON.stringify(rebuilt) !== JSON.stringify(dto)) throw new GSwapSDKError(`The ${method} DTO is not in the form the SDK builders produce; build it with the matching build function and submit that.`, "VALIDATION_ERROR", {
+		type: "DTO_NOT_CANONICAL",
+		method
+	});
 }
 
 //#endregion
 //#region src/classes/positions.ts
+/** The pool position a liquidity DTO names, as its confirmation needs it. */
+function identityOf(dto) {
+	return {
+		token0: dto.token0,
+		token1: dto.token1,
+		fee: dto.fee,
+		tickLower: dto.tickLower,
+		tickUpper: dto.tickUpper
+	};
+}
 /**
 * Manages current-contract concentrated-liquidity positions.
 *
@@ -1491,26 +2734,32 @@ var Positions = class {
 	symbols;
 	signer;
 	walletAddress;
-	constructor(gateway, symbols, signer, walletAddress) {
+	constructor(gateway, symbols, signer, walletAddress, options = {}) {
 		this.gateway = gateway;
 		this.symbols = symbols;
 		this.signer = signer;
 		this.walletAddress = walletAddress;
-		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs ?? 3e4);
+		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs ?? 3e4, gateway.wire);
+		this.uniqueKeyPrefix = resolveUniqueKeyPrefix(options.uniqueKeyPrefix);
+		this.onInvalidEntry = options.onInvalidEntry;
 	}
 	http;
+	uniqueKeyPrefix;
+	onInvalidEntry;
 	/**
 	* Gets all current-contract positions owned by an address.
 	*
 	* @param owner - GalaChain owner identity.
-	* @returns Enriched positions from the v2 trade backend.
+	* @returns Enriched positions from the v2 trade backend, token images included. A row that is
+	* not a usable position is skipped and reported to `onInvalidEntry`.
 	* @example
 	* ```typescript
 	* const positions = await gSwap.positions.getUserPositions('client|012345678901234567890123');
 	* ```
 	*/
 	async getUserPositions(owner) {
-		return (await this.get("/positions", { user: owner })).data.map((position) => this.mapPosition(position));
+		const response = await this.get("/positions", { user: owner });
+		return readEntries("positions", response.data, parsePosition, this.onInvalidEntry);
 	}
 	/**
 	* Gets one position, normalizing a caller-supplied reversed pair to canonical symbol order.
@@ -1527,17 +2776,65 @@ var Positions = class {
 	* ```
 	*/
 	async getPosition(args, signal) {
+		const response = await this.getNullable("/position", await this.positionParams(args), signal);
+		return response === null ? null : readPositionBody(response.data);
+	}
+	/**
+	* Reads one position and classifies the outcome instead of throwing: `found` with the position
+	* (fees included), `not_found` (the backend's HTTP 404, which it sends only when the chain
+	* itself has no such position) or `unknown` (any other failure, carried as `error`). Use it
+	* to confirm a write: `unknown` is "no evidence either way", never a confirmed absence.
+	*
+	* Only the caller's own abort rethrows. With a pass-through resolver ({@link CanonicalSymbols})
+	* the pair and ticks go to the backend exactly as given and the backend orients them.
+	*
+	* @example
+	* ```typescript
+	* const read = await gSwap.positions.readPosition({
+	*   token0: 'GALA', token1: 'GUSDC', owner: 'client|012345678901234567890123',
+	*   fee: 3000, tickLower: -19200, tickUpper: 12000,
+	* });
+	* if (read.kind === 'found') console.log(read.data.fees0);
+	* ```
+	*/
+	async readPosition(args, signal) {
+		try {
+			const position = await this.getPosition(args, signal);
+			return position === null ? { kind: "not_found" } : {
+				kind: "found",
+				data: position
+			};
+		} catch (error) {
+			if ((signal === null || signal === void 0 ? void 0 : signal.aborted) === true) throw error;
+			return {
+				kind: "unknown",
+				error: error instanceof GSwapSDKError ? error : new GSwapSDKError("Position request failed.", "HTTP_ERROR", { cause: error })
+			};
+		}
+	}
+	/**
+	* The `/position` query: canonical symbols and canonical ticks after a client-side flip, or,
+	* for a pass-through resolver, the caller's references and ticks untouched.
+	*/
+	async positionParams(args) {
+		if (this.symbols.passthrough === true) return {
+			token0: rawTokenOf(args.token0),
+			token1: rawTokenOf(args.token1),
+			fee: `${args.fee}`,
+			owner: args.owner,
+			tickLower: `${args.tickLower}`,
+			tickUpper: `${args.tickUpper}`
+		};
 		const pair = await this.symbols.orderPair(args.token0, args.token1);
 		const ticks = this.canonicalTicks(args.tickLower, args.tickUpper, pair.flipped);
-		const response = await this.getNullable("/position", {
+		return {
 			token0: pair.token0.symbol,
 			token1: pair.token1.symbol,
 			fee: `${args.fee}`,
 			owner: args.owner,
 			tickLower: `${ticks.tickLower}`,
 			tickUpper: `${ticks.tickUpper}`
-		}, signal);
-		return response === null ? null : this.mapPosition(response.data);
+		};
 	}
 	/**
 	* Estimates the other token amount and resulting liquidity for a deposit.
@@ -1555,8 +2852,8 @@ var Positions = class {
 	async estimateAddLiquidity(args) {
 		validateNumericAmount(args.amount, "amount");
 		return (await this.get("/add-liq-estimate", {
-			token0: this.requestToken(args.token0),
-			token1: this.requestToken(args.token1),
+			token0: rawTokenOf(args.token0),
+			token1: rawTokenOf(args.token1),
 			fee: `${args.fee}`,
 			tickLower: `${args.tickLower}`,
 			tickUpper: `${args.tickUpper}`,
@@ -1580,8 +2877,8 @@ var Positions = class {
 	async estimateRemoveLiquidity(args) {
 		validateNumericAmount(args.liquidity, "liquidity");
 		return (await this.get("/remove-liq-estimate", {
-			token0: this.requestToken(args.token0),
-			token1: this.requestToken(args.token1),
+			token0: rawTokenOf(args.token0),
+			token1: rawTokenOf(args.token1),
 			fee: `${args.fee}`,
 			tickLower: `${args.tickLower}`,
 			tickUpper: `${args.tickUpper}`,
@@ -1603,30 +2900,54 @@ var Positions = class {
 	* ```
 	*/
 	async addLiquidityByTicks(args) {
+		return this.submitAddLiquidity(await this.buildAddLiquidity(args));
+	}
+	/**
+	* Builds the AddLiquidity DTO that {@link addLiquidityByTicks} would sign, without signing or
+	* sending it: to show in an approval popup, or to sign elsewhere. Submit exactly this DTO with
+	* {@link submitAddLiquidity}. The pure counterpart, with canonical inputs and no resolution,
+	* is `buildAddLiquidityDto`.
+	*
+	* @example
+	* ```typescript
+	* const dto = await gSwap.positions.buildAddLiquidity({
+	*   token0: 'GALA', token1: 'GUSDC', fee: 3000,
+	*   tickLower: -19200, tickUpper: 12000, amount: '100', amountIsToken0: true,
+	* });
+	* ```
+	*/
+	async buildAddLiquidity(args) {
 		validateFee(args.fee);
 		const pair = await this.symbols.orderPair(args.token0, args.token1);
 		const ticks = this.canonicalTicks(args.tickLower, args.tickUpper, pair.flipped);
 		assertTickRange(ticks.tickLower, ticks.tickUpper, args.fee);
 		validateNumericAmount(args.amount, "amount");
-		const amount = new bignumber_js.default(args.amount).toFixed();
-		const dto = {
+		const base = {
 			token0: pair.token0.symbol,
 			token1: pair.token1.symbol,
 			fee: args.fee,
 			tickLower: ticks.tickLower,
 			tickUpper: ticks.tickUpper,
-			uniqueKey: this.uniqueKey(),
-			...pair.flipped !== args.amountIsToken0 ? { depositQuantityToken0: amount } : { depositQuantityToken1: amount }
+			uniqueKey: this.uniqueKeyFor(args.uniqueKey)
 		};
+		return pair.flipped !== args.amountIsToken0 ? buildAddLiquidityDto({
+			...base,
+			depositQuantityToken0: args.amount
+		}) : buildAddLiquidityDto({
+			...base,
+			depositQuantityToken1: args.amount
+		});
+	}
+	/**
+	* Signs and submits a DTO built by {@link buildAddLiquidity} or `buildAddLiquidityDto`; it must
+	* be exactly what the builder produces. The returned transaction confirms by proving the
+	* position's liquidity grew.
+	*/
+	async submitAddLiquidity(dto) {
+		assertCanonicalV2Dto("AddLiquidity", dto);
 		return this.submit("AddLiquidity", dto, {
 			kind: "add",
-			identity: {
-				token0: pair.token0.symbol,
-				token1: pair.token1.symbol,
-				fee: args.fee,
-				tickLower: ticks.tickLower,
-				tickUpper: ticks.tickUpper
-			}
+			identity: identityOf(dto)
 		});
 	}
 	/**
@@ -1661,7 +2982,8 @@ var Positions = class {
 			tickLower,
 			tickUpper,
 			amount: args.amount,
-			amountIsToken0: args.amountIsToken0
+			amountIsToken0: args.amountIsToken0,
+			uniqueKey: args.uniqueKey
 		});
 	}
 	/**
@@ -1679,6 +3001,14 @@ var Positions = class {
 	* ```
 	*/
 	async removeLiquidity(args) {
+		return this.submitRemoveLiquidity(await this.buildRemoveLiquidity(args));
+	}
+	/**
+	* Builds the RemoveLiquidity DTO that {@link removeLiquidity} would sign, without signing or
+	* sending it. Submit exactly this DTO with {@link submitRemoveLiquidity}. The pure counterpart
+	* is `buildRemoveLiquidityDto`.
+	*/
+	async buildRemoveLiquidity(args) {
 		validateFee(args.fee);
 		const pair = await this.symbols.orderPair(args.token0, args.token1);
 		const ticks = this.canonicalTicks(args.tickLower, args.tickUpper, pair.flipped);
@@ -1686,26 +3016,29 @@ var Positions = class {
 		if (args.amount0 !== void 0 && args.amount1 !== void 0) throw new GSwapSDKError("Provide at most one of amount0 or amount1.", "VALIDATION_ERROR");
 		if (args.amount0 !== void 0) validateNumericAmount(args.amount0, "amount0");
 		if (args.amount1 !== void 0) validateNumericAmount(args.amount1, "amount1");
-		const withdrawal = args.amount0 !== void 0 ? pair.flipped ? { withdrawalQuantityToken1: new bignumber_js.default(args.amount0).toFixed() } : { withdrawalQuantityToken0: new bignumber_js.default(args.amount0).toFixed() } : args.amount1 !== void 0 ? pair.flipped ? { withdrawalQuantityToken0: new bignumber_js.default(args.amount1).toFixed() } : { withdrawalQuantityToken1: new bignumber_js.default(args.amount1).toFixed() } : {};
-		const dto = {
+		const [canonical0, canonical1] = pair.flipped ? [args.amount1, args.amount0] : [args.amount0, args.amount1];
+		return buildRemoveLiquidityDto({
 			token0: pair.token0.symbol,
 			token1: pair.token1.symbol,
 			fee: args.fee,
 			tickLower: ticks.tickLower,
 			tickUpper: ticks.tickUpper,
-			uniqueKey: this.uniqueKey(),
-			...withdrawal
-		};
-		const isFullClose = args.amount0 === void 0 && args.amount1 === void 0;
+			uniqueKey: this.uniqueKeyFor(args.uniqueKey),
+			withdrawalQuantityToken0: canonical0,
+			withdrawalQuantityToken1: canonical1
+		});
+	}
+	/**
+	* Signs and submits a DTO built by {@link buildRemoveLiquidity} or `buildRemoveLiquidityDto`;
+	* it must be exactly what the builder produces. A DTO with no withdrawal quantity closes the
+	* position, and the returned transaction then confirms by proving the position is gone.
+	*/
+	async submitRemoveLiquidity(dto) {
+		assertCanonicalV2Dto("RemoveLiquidity", dto);
+		const isFullClose = dto.withdrawalQuantityToken0 === void 0 && dto.withdrawalQuantityToken1 === void 0;
 		return this.submit("RemoveLiquidity", dto, {
 			kind: isFullClose ? "removeFull" : "removePartial",
-			identity: {
-				token0: pair.token0.symbol,
-				token1: pair.token1.symbol,
-				fee: args.fee,
-				tickLower: ticks.tickLower,
-				tickUpper: ticks.tickUpper
-			}
+			identity: identityOf(dto)
 		});
 	}
 	/**
@@ -1722,27 +3055,36 @@ var Positions = class {
 	* ```
 	*/
 	async collectPositionFees(args) {
+		return this.submitCollectPositionFees(await this.buildCollectPositionFees(args));
+	}
+	/**
+	* Builds the CollectPositionFees DTO that {@link collectPositionFees} would sign, without
+	* signing or sending it. Submit exactly this DTO with {@link submitCollectPositionFees}. The
+	* pure counterpart is `buildCollectPositionFeesDto`.
+	*/
+	async buildCollectPositionFees(args) {
 		validateFee(args.fee);
 		const pair = await this.symbols.orderPair(args.token0, args.token1);
 		const ticks = this.canonicalTicks(args.tickLower, args.tickUpper, pair.flipped);
 		assertTickRange(ticks.tickLower, ticks.tickUpper, args.fee);
-		const dto = {
+		return buildCollectPositionFeesDto({
 			token0: pair.token0.symbol,
 			token1: pair.token1.symbol,
 			fee: args.fee,
 			tickLower: ticks.tickLower,
 			tickUpper: ticks.tickUpper,
-			uniqueKey: this.uniqueKey()
-		};
+			uniqueKey: this.uniqueKeyFor(args.uniqueKey)
+		});
+	}
+	/**
+	* Signs and submits a DTO built by {@link buildCollectPositionFees} or
+	* `buildCollectPositionFeesDto`; it must be exactly what the builder produces.
+	*/
+	async submitCollectPositionFees(dto) {
+		assertCanonicalV2Dto("CollectPositionFees", dto);
 		return this.submit("CollectPositionFees", dto, {
 			kind: "collect",
-			identity: {
-				token0: pair.token0.symbol,
-				token1: pair.token1.symbol,
-				fee: args.fee,
-				tickLower: ticks.tickLower,
-				tickUpper: ticks.tickUpper
-			}
+			identity: identityOf(dto)
 		});
 	}
 	/**
@@ -1767,7 +3109,15 @@ var Positions = class {
 	* ```
 	*/
 	async createPool(args) {
-		var _this$symbols$invalid, _this$symbols;
+		return this.submitCreatePool(await this.buildCreatePool(args));
+	}
+	/**
+	* Builds the CreatePool DTO that {@link createPool} would sign, without signing or sending it:
+	* symbols resolved or proposed, the pair put in canonical order and the price inverted when it
+	* was reversed. Submit exactly this DTO with {@link submitCreatePool}. The pure counterpart,
+	* with canonical inputs, is `buildCreatePoolDto`.
+	*/
+	async buildCreatePool(args) {
 		const hasPrice = args.startingPrice !== void 0;
 		if (hasPrice === (args.startingSqrtPrice !== void 0)) throw new GSwapSDKError("Provide exactly one of startingPrice or startingSqrtPrice.", "VALIDATION_ERROR");
 		validateFee(args.fee);
@@ -1779,22 +3129,38 @@ var Positions = class {
 		const sourcePrice = new bignumber_js.default(sourcePriceInput);
 		if (!sourcePrice.isFinite() || sourcePrice.isLessThanOrEqualTo(0)) throw new GSwapSDKError("Starting price must be finite and positive.", "VALIDATION_ERROR");
 		const canonicalPrice = flipped ? new bignumber_js.default(1).dividedBy(sourcePrice) : sourcePrice;
-		const dto = {
+		const shared = {
 			token0Key: token0.classKey,
 			token1Key: token1.classKey,
 			token0Symbol: token0.symbol,
 			token1Symbol: token1.symbol,
 			fee: args.fee,
-			uniqueKey: this.uniqueKey(),
-			...hasPrice ? { startingPrice: canonicalPrice.toFixed() } : { startingSqrtPrice: canonicalPrice.toFixed() },
-			...args.isPrivate === void 0 ? {} : { isPrivate: args.isPrivate },
-			...args.privateAccess === void 0 ? {} : { privateAccess: args.privateAccess }
+			uniqueKey: this.uniqueKeyFor(args.uniqueKey),
+			name: args.name,
+			isPrivate: args.isPrivate,
+			privateAccess: args.privateAccess
 		};
+		return hasPrice ? buildCreatePoolDto({
+			...shared,
+			startingPrice: canonicalPrice
+		}) : buildCreatePoolDto({
+			...shared,
+			startingSqrtPrice: canonicalPrice
+		});
+	}
+	/**
+	* Signs and submits a DTO built by {@link buildCreatePool} or `buildCreatePoolDto`; it must be
+	* exactly what the builder produces. The returned transaction confirms by the pool existing, and
+	* the cached symbol registry is dropped, since the pool may have registered new symbols.
+	*/
+	async submitCreatePool(dto) {
+		var _this$symbols$invalid, _this$symbols;
+		assertCanonicalV2Dto("CreatePool", dto);
 		const transaction = await this.submit("CreatePool", dto, {
 			kind: "createPool",
-			token0: token0.symbol,
-			token1: token1.symbol,
-			fee: args.fee
+			token0: dto.token0Symbol,
+			token1: dto.token1Symbol,
+			fee: dto.fee
 		});
 		(_this$symbols$invalid = (_this$symbols = this.symbols).invalidate) === null || _this$symbols$invalid === void 0 || _this$symbols$invalid.call(_this$symbols);
 		return transaction;
@@ -1900,30 +3266,6 @@ var Positions = class {
 		if (!(error instanceof GSwapSDKError) || error.details === void 0) return false;
 		return error.details["status"] === 404;
 	}
-	mapPosition(position) {
-		return {
-			token0Symbol: position.token0Symbol,
-			token1Symbol: position.token1Symbol,
-			...position.token0CompositeKey === void 0 ? {} : { token0CompositeKey: position.token0CompositeKey },
-			...position.token1CompositeKey === void 0 ? {} : { token1CompositeKey: position.token1CompositeKey },
-			fee: position.fee,
-			tickLower: position.tickLower,
-			tickUpper: position.tickUpper,
-			liquidity: position.liquidity,
-			amount0: position.amount0,
-			amount1: position.amount1,
-			inRange: position.inRange,
-			...position.currentTick === void 0 ? {} : { currentTick: position.currentTick },
-			...position.sqrtPrice === void 0 ? {} : { sqrtPrice: position.sqrtPrice },
-			pool: position.poolRef ?? position.pool ?? "",
-			owner: position.owner,
-			...position.fees0 === void 0 ? {} : { fees0: position.fees0 },
-			...position.fees1 === void 0 ? {} : { fees1: position.fees1 }
-		};
-	}
-	requestToken(ref) {
-		return typeof ref === "string" ? ref : compositeKeyOf(ref);
-	}
 	canonicalTicks(tickLower, tickUpper, flipped) {
 		return flipped ? {
 			tickLower: -tickUpper,
@@ -1941,8 +3283,11 @@ var Positions = class {
 	rejectNumber(value, parameterName) {
 		if (typeof value === "number") throw new GSwapSDKError(`Invalid ${parameterName}: use a decimal string or BigNumber, not a JavaScript number`, "VALIDATION_ERROR");
 	}
-	uniqueKey() {
-		return `gswap-sdk-${globalThis.crypto.randomUUID()}`;
+	/** The caller's `uniqueKey` (validated), else a fresh one. */
+	uniqueKeyFor(supplied) {
+		if (supplied === void 0) return createUniqueKey(this.uniqueKeyPrefix);
+		assertUniqueKey(supplied);
+		return supplied;
 	}
 	async resolveCreateToken(ref, symbolOverride) {
 		try {
@@ -1954,6 +3299,7 @@ var Positions = class {
 				registeredSymbol: resolved.symbol
 			});
 			const suppliedClassKey = this.tryParseClassKey(ref);
+			if (suppliedClassKey === void 0 && resolved.collection === "") throw new GSwapSDKError("createPool needs each token as a class key; a bare trading symbol does not carry one.", "VALIDATION_ERROR", { token: ref });
 			return {
 				symbol: resolved.symbol,
 				classKey: suppliedClassKey ?? parseTokenClassKey({
@@ -1972,7 +3318,7 @@ var Positions = class {
 				throw error;
 			}
 			if (symbolOverride === void 0 || symbolOverride === "") throw new GSwapSDKError("Token is not registered in the trading-symbol registry yet; pass token0Symbol/token1Symbol (the token class symbol) to propose one. A symbol cannot be derived from a class key.", "VALIDATION_ERROR", { token: ref });
-			if (!/^[A-Za-z0-9]+$/u.test(symbolOverride)) throw new GSwapSDKError("Invalid trading symbol: must be ASCII letters and digits only.", "VALIDATION_ERROR", { symbol: symbolOverride });
+			if (!isProposableTradingSymbol(symbolOverride)) throw new GSwapSDKError("Invalid trading symbol: must be 1-32 ASCII letters and digits and not a reserved word (Token, Unit, none).", "VALIDATION_ERROR", { symbol: symbolOverride });
 			return {
 				symbol: symbolOverride,
 				classKey
@@ -1987,27 +3333,94 @@ var Positions = class {
 		}
 	}
 };
+const REQUIRED_POSITION_STRINGS = [
+	"token0Symbol",
+	"token1Symbol",
+	"owner",
+	"liquidity",
+	"amount0",
+	"amount1"
+];
+const REQUIRED_POSITION_NUMBERS = [
+	"fee",
+	"tickLower",
+	"tickUpper"
+];
+const OPTIONAL_POSITION_STRINGS = [
+	"token0CompositeKey",
+	"token1CompositeKey",
+	"token0Image",
+	"token1Image",
+	"sqrtPrice",
+	"fees0",
+	"fees1"
+];
+/**
+* Reads one position row of `/positions` or `/position`: the pair, owner, range, liquidity and
+* amounts must be usable; the composite keys, token images, current tick and price, and the
+* escrowed fees are carried when present. `pool` is the pool reference (`poolRef` wins over
+* `pool`; `''` when the row names neither).
+*/
+function parsePosition(value) {
+	const wire = asEntryRecord(value);
+	if (wire === void 0) return entryRejected("the row is not an object");
+	for (const key of REQUIRED_POSITION_STRINGS) if (typeof wire[key] !== "string") return entryRejected(`${key} is not a string`);
+	for (const key of REQUIRED_POSITION_NUMBERS) {
+		const number = wire[key];
+		if (typeof number !== "number" || !Number.isFinite(number)) return entryRejected(`${key} is not a number`);
+	}
+	if (typeof wire["inRange"] !== "boolean") return entryRejected("inRange is not a boolean");
+	for (const key of OPTIONAL_POSITION_STRINGS) if (wire[key] !== void 0 && typeof wire[key] !== "string") return entryRejected(`${key} is not a string`);
+	const currentTick = wire["currentTick"];
+	if (currentTick !== void 0 && (typeof currentTick !== "number" || !Number.isFinite(currentTick))) return entryRejected("currentTick is not a number");
+	const pool = wire["poolRef"] ?? wire["pool"] ?? "";
+	if (typeof pool !== "string") return entryRejected("pool is not a string");
+	const optional = Object.fromEntries([...OPTIONAL_POSITION_STRINGS, "currentTick"].flatMap((key) => wire[key] === void 0 ? [] : [[key, wire[key]]]));
+	return entryOk({
+		token0Symbol: wire["token0Symbol"],
+		token1Symbol: wire["token1Symbol"],
+		fee: wire["fee"],
+		tickLower: wire["tickLower"],
+		tickUpper: wire["tickUpper"],
+		liquidity: wire["liquidity"],
+		amount0: wire["amount0"],
+		amount1: wire["amount1"],
+		inRange: wire["inRange"],
+		pool,
+		owner: wire["owner"],
+		...optional
+	});
+}
+/** The position inside a `/position` answer, or `INVALID_CHAIN_RESPONSE` when it is not one. */
+function readPositionBody(data) {
+	const parsed = parsePosition(data);
+	if (parsed.ok) return parsed.value;
+	throw new GSwapSDKError("Backend returned an invalid position.", "INVALID_CHAIN_RESPONSE", {
+		data,
+		reason: parsed.reason
+	});
+}
 
 //#endregion
 //#region src/classes/quoting.ts
 /** Read-only quote service backed by the v2 offline quote engine. */
 var Quoting = class {
-	dexBackendBaseUrl;
-	http;
+	gateway;
 	symbols;
 	/**
 	* Creates a quote service.
 	*
 	* @example
 	* ```ts
-	* const quoting = new Quoting('https://swap-backend.stage.defi.ovh.gala.com', http, symbols);
+	* const quoting = new Quoting(gateway, symbols); // a ChainGateway, or any { dexBackendBaseUrl, httpRequestor }
 	* ```
 	*/
-	constructor(dexBackendBaseUrl, http, symbols) {
-		this.dexBackendBaseUrl = dexBackendBaseUrl;
-		this.http = http;
+	constructor(gateway, symbols) {
+		this.gateway = gateway;
 		this.symbols = symbols;
+		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs ?? 3e4, gateway.wire);
 	}
+	http;
 	/**
 	* Quotes the output for a positive exact-input amount.
 	*
@@ -2019,7 +3432,7 @@ var Quoting = class {
 	*/
 	async quoteExactInput(tokenIn, tokenOut, amountIn, fee) {
 		validateNumericAmount(amountIn, "amountIn");
-		return this.quote(tokenIn, tokenOut, { amountIn: toDecimalString$1(amountIn) }, fee);
+		return this.quote(tokenIn, tokenOut, { amountIn: toDecimalString(amountIn) }, fee);
 	}
 	/**
 	* Quotes the input for a positive exact-output amount.
@@ -2032,18 +3445,18 @@ var Quoting = class {
 	*/
 	async quoteExactOutput(tokenIn, tokenOut, amountOut, fee) {
 		validateNumericAmount(amountOut, "amountOut");
-		return this.quote(tokenIn, tokenOut, { amountOut: toDecimalString$1(amountOut) }, fee);
+		return this.quote(tokenIn, tokenOut, { amountOut: toDecimalString(amountOut) }, fee);
 	}
 	async quote(tokenIn, tokenOut, amount, fee) {
 		validateOptionalFee(fee);
 		const params = {
-			tokenIn: await resolveSymbol$1(this.symbols, tokenIn),
-			tokenOut: await resolveSymbol$1(this.symbols, tokenOut),
+			tokenIn: await queryTokenOf(this.symbols, tokenIn),
+			tokenOut: await queryTokenOf(this.symbols, tokenOut),
 			...amount
 		};
 		if (fee !== void 0) params["fee"] = String(fee);
 		try {
-			return mapQuote((await this.http.sendGetRequest(this.dexBackendBaseUrl, "/v2/trade", "/quote", params)).data);
+			return mapQuote((await this.http.sendGetRequest(this.gateway.dexBackendBaseUrl, "/v2/trade", "/quote", params)).data);
 		} catch (error) {
 			throw mapQuoteError(error, tokenIn, tokenOut, fee);
 		}
@@ -2105,12 +3518,19 @@ function optionalPositiveDecimal(value) {
 		return false;
 	}
 }
+/**
+* The ways the backend says a pair has no market at all: a token the DEX contract never
+* registered ("has no trading symbol on the new DEX contract"), no pool at ANY fee tier ("No
+* pools found with sufficient liquidity"), or a missing pool ("Pool does not exist on the new
+* DEX contract"). A pool that exists but is too thin says "Insufficient liquidity: ..." instead.
+*/
+const NO_MARKET_MESSAGE = /no pool|no pools|pool does not exist|has no trading symbol on the new DEX contract/iu;
 function mapQuoteError(error, tokenIn, tokenOut, fee) {
 	if (error instanceof GSwapSDKError) {
 		const status = readStatus(error.details);
 		const message = readMessage(error.details) ?? error.message;
-		if (status === 404 || /no pool|no pools|pool does not exist/iu.test(message)) return GSwapSDKError.noPoolAvailableError(tokenIn, tokenOut, fee);
-		if (status === 400 && /insufficient liquidity/iu.test(message)) return GSwapSDKError.insufficientLiquidityError(tokenIn, tokenOut, fee);
+		if (status === 404 || NO_MARKET_MESSAGE.test(message)) return GSwapSDKError.noPoolAvailableError(tokenIn, tokenOut, fee, error);
+		if (status === 400 && /insufficient liquidity/iu.test(message)) return GSwapSDKError.insufficientLiquidityError(tokenIn, tokenOut, fee, error);
 		return error;
 	}
 	return new GSwapSDKError("Quote request failed.", "HTTP_ERROR", {
@@ -2135,107 +3555,112 @@ function readMessage(details) {
 function validateOptionalFee(fee) {
 	if (fee !== void 0 && !ALL_FEE_TIERS.some((tier) => Number(tier) === Number(fee))) throw new GSwapSDKError(`Invalid fee tier: ${fee}`, "VALIDATION_ERROR", { fee });
 }
-function toDecimalString$1(amount) {
+function toDecimalString(amount) {
 	return new bignumber_js.default(amount).toFixed();
 }
-async function resolveSymbol$1(symbols, token) {
-	const resolved = await symbols.resolve(token);
-	if (resolved.symbol.length > 0) return resolved.symbol;
-	throw new GSwapSDKError("Token could not be resolved to a trading symbol.", "SYMBOL_NOT_FOUND", { token });
-}
 
 //#endregion
-//#region src/classes/symbols.ts
-const SYMBOL_CACHE_TTL_MS = 6e4;
-/** Symbol registry client for the current GalaChainDex contract. */
-var Symbols = class {
-	gateway;
-	cachedSymbols;
-	cachedAt = 0;
-	refreshInFlight;
-	http;
-	/** Create a symbol service backed by the swap backend. */
-	constructor(gateway) {
-		this.gateway = gateway;
-		this.http = new HttpClient(gateway.httpRequestor, gateway.requestTimeoutMs);
-	}
-	/** List all registered GalaChainDex trading symbols, cached for 60 seconds. */
-	async list() {
-		if (this.cachedSymbols !== void 0 && Date.now() - this.cachedAt < SYMBOL_CACHE_TTL_MS) return this.cachedSymbols;
-		if (this.refreshInFlight !== void 0) return this.refreshInFlight;
-		this.refreshInFlight = this.http.sendGetRequest(this.gateway.dexBackendBaseUrl, "/v2/trade", "/symbols").then((response) => parseSymbols(response.data)).then((symbols) => {
-			this.cachedSymbols = symbols;
-			this.cachedAt = Date.now();
-			return symbols;
-		}).finally(() => {
-			this.refreshInFlight = void 0;
-		});
-		return this.refreshInFlight;
-	}
-	/** Invalidate the cached symbol registry after a write changes registration state.
-	*
-	* @example
-	* ```ts
-	* gSwap.symbols.invalidate();
-	* ```
-	*/
-	invalidate() {
-		this.cachedSymbols = void 0;
-		this.cachedAt = 0;
-	}
-	/** Force one registry refresh, bypassing the cache.
-	*
-	* @example
-	* ```ts
-	* const symbols = await gSwap.symbols.refresh();
-	* ```
-	*/
-	async refresh() {
-		this.invalidate();
-		this.refreshInFlight = void 0;
-		return this.list();
-	}
-	/** Resolve a symbol or token class key to its registered symbol metadata. */
-	async resolve(ref) {
-		let symbols = await this.list();
-		const composite = typeof ref === "string" ? isCompositeKey(ref) ? compositeKeyOf(parseTokenClassKey(ref)) : void 0 : compositeKeyOf(ref);
-		const resolved = symbols.find((entry) => entry.symbol === ref || composite !== void 0 && compositeKeyOf(entry) === composite);
-		if (resolved === void 0) {
-			symbols = await this.refresh();
-			const refreshed = symbols.find((entry) => entry.symbol === ref || composite !== void 0 && compositeKeyOf(entry) === composite);
-			if (refreshed === void 0) throw GSwapSDKError.unknownTokenError(ref);
-			return refreshed;
+//#region src/classes/shadow_submit.ts
+/** Maps an HTTP status to a failure kind: 503 retryable, 400 disabled, anything else unknown. */
+function classifyShadowSubmitStatus(status) {
+	if (status === 503) return "unavailable";
+	if (status === 400) return "disabled";
+	return "unknown";
+}
+/**
+* Prefers the body `code` (stable across status remaps) and falls back to the HTTP status.
+* `SHADOW_UNAVAILABLE` is the only retryable case; `SHADOW_RELAY_REJECTED` is a terminal gateway
+* rejection; the two other 400 codes and any unknown 400 map to "disabled".
+*/
+function classifyShadowSubmitError(status, code) {
+	if (code === "SHADOW_UNAVAILABLE") return "unavailable";
+	if (code === "SHADOW_RELAY_REJECTED") return "rejected";
+	if (code === "SHADOW_DISABLED" || code === "SHADOW_UNSUPPORTED_TYPE") return "disabled";
+	return classifyShadowSubmitStatus(status);
+}
+/**
+* Normalizes a shadow write's raw answer.
+*
+* A 2xx envelope with `error === false` is a success when it is a queued RequestTrade that
+* acknowledges the EXACT signed `uniqueKey`, or a synchronous (`mode: 'sync'`) liquidity write.
+* Everything else is classified as a failure from the status and the body's `code`.
+*
+* @throws GSwapSDKError INVALID_GATEWAY_RESPONSE when a RequestTrade success does not queue the
+* signed `uniqueKey` (a synchronous or mismatched answer must never be accepted as a swap).
+*/
+function readShadowSubmitOutcome(method, signedBody, result) {
+	const { httpStatus, body } = result;
+	const envelope = asRecord(body);
+	if (httpStatus >= 200 && httpStatus < 300 && (envelope === null || envelope === void 0 ? void 0 : envelope["error"]) === false) {
+		const data = asRecord(envelope["data"]);
+		const rawTransactionId = typeof (data === null || data === void 0 ? void 0 : data["transactionId"]) === "string" ? data["transactionId"] : void 0;
+		if (method === "RequestTrade") {
+			const requestedKey = signedBody["uniqueKey"];
+			if ((data === null || data === void 0 ? void 0 : data["mode"]) !== "queued" || typeof requestedKey !== "string" || data["uniqueKey"] !== requestedKey) throw new GSwapSDKError(`The swap backend did not queue the request ${typeof requestedKey === "string" ? requestedKey : ""}.`, "INVALID_GATEWAY_RESPONSE", {
+				httpStatus,
+				body
+			});
+			return {
+				ok: true,
+				bundleId: rawTransactionId ?? "",
+				queued: {
+					uniqueKey: requestedKey,
+					requestTransactionId: rawTransactionId ?? null
+				}
+			};
 		}
-		return resolved;
-	}
-	/** Resolve and put two token references in canonical trading-symbol order. */
-	async orderPair(a, b) {
-		const [resolvedA, resolvedB] = await Promise.all([this.resolve(a), this.resolve(b)]);
-		const [token0Symbol, token1Symbol] = orderSymbols(resolvedA.symbol, resolvedB.symbol);
-		return {
-			token0: token0Symbol === resolvedA.symbol ? resolvedA : resolvedB,
-			token1: token1Symbol === resolvedB.symbol ? resolvedB : resolvedA,
-			flipped: token0Symbol !== resolvedA.symbol
+		if ((data === null || data === void 0 ? void 0 : data["mode"]) === "sync") return {
+			ok: true,
+			bundleId: rawTransactionId ?? ""
 		};
 	}
-};
-function parseSymbols(value) {
-	if (!Array.isArray(value) || !value.every(isTradingSymbol)) throw new GSwapSDKError("Backend returned an invalid symbol list.", "INVALID_CHAIN_RESPONSE", { data: value });
-	return value;
-}
-function isTradingSymbol(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const entry = value;
-	return typeof entry["symbol"] === "string" && typeof entry["collection"] === "string" && typeof entry["category"] === "string" && typeof entry["type"] === "string" && typeof entry["additionalKey"] === "string" && typeof entry["decimals"] === "number" && Number.isInteger(entry["decimals"]) && entry["decimals"] >= 0;
+	const kind = classifyShadowSubmitError(httpStatus, getStringProperty(body, "code"));
+	if (kind === "rejected") return {
+		ok: false,
+		kind: "rejected",
+		retryable: false,
+		message: getStringProperty(body, "message") ?? ""
+	};
+	return kind === "unavailable" ? {
+		ok: false,
+		kind,
+		retryable: true
+	} : {
+		ok: false,
+		kind,
+		retryable: false
+	};
 }
-function isCompositeKey(ref) {
-	return ref.includes("|") || ref.includes("$");
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : void 0;
 }
 
 //#endregion
 //#region src/classes/swaps.ts
-/** The swap backend's apply-results key constraint (`apply-results.dto.ts`). */
-const UNIQUE_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/u;
+/**
+* The route of a quote: its fee tier and pool, with `tokenIn` / `tokenOut` taken from
+* `tokenInIsToken0`, nothing re-derived. Use it to swap in exactly the pool a quote priced:
+*
+* @example
+* ```ts
+* const route = swapRouteFromQuote(quote);
+* await swaps.swap(route.tokenIn, route.tokenOut, route.fee, { exactIn: '100' }, { pool: route.pool });
+* ```
+*/
+function swapRouteFromQuote(quote) {
+	validateFee(quote.fee);
+	assertCanonicalPair(quote.token0Symbol, quote.token1Symbol);
+	const [tokenIn, tokenOut] = quote.tokenInIsToken0 ? [quote.token0Symbol, quote.token1Symbol] : [quote.token1Symbol, quote.token0Symbol];
+	return {
+		tokenIn,
+		tokenOut,
+		fee: quote.fee,
+		pool: {
+			token0: quote.token0Symbol,
+			token1: quote.token1Symbol
+		}
+	};
+}
 /** Executes queued current-contract RequestTrade operations through the Chain Gateway. */
 var Swaps = class {
 	gateway;
@@ -2250,12 +3675,14 @@ var Swaps = class {
 	* const swaps = new Swaps(gateway, symbols, signer, 'client|alice');
 	* ```
 	*/
-	constructor(gateway, symbols, signer, walletAddress) {
+	constructor(gateway, symbols, signer, walletAddress, options = {}) {
 		this.gateway = gateway;
 		this.symbols = symbols;
 		this.signer = signer;
 		this.walletAddress = walletAddress;
+		this.uniqueKeyPrefix = resolveUniqueKeyPrefix(options.uniqueKeyPrefix);
 	}
+	uniqueKeyPrefix;
 	/**
 	* Signs and submits an exact-input or exact-output RequestTrade DTO. The returned transaction
 	* is QUEUED; call `await tx.confirm()` to obtain the executed trade or chain rejection.
@@ -2268,13 +3695,97 @@ var Swaps = class {
 	* });
 	* ```
 	*/
-	async swap(tokenIn, tokenOut, fee, amount) {
+	async swap(tokenIn, tokenOut, fee, amount, options) {
+		return this.submitSwap(await this.buildSwap(tokenIn, tokenOut, fee, amount, options));
+	}
+	/**
+	* Signs and submits a SHADOW (dark) swap: the same RequestTrade as {@link swap}, relayed with
+	* `X-Shadow: true` so defi-backend marks it private before it reaches the contract. Requires a
+	* `walletAddress`. Resolves the normalized outcome instead of throwing on a gateway refusal:
+	* `ok: false` carries `unavailable` (retryable), `disabled`, `rejected` (with the gateway's
+	* message) or `unknown`. A success carries `queued`, to be confirmed with
+	* `confirmSwap(queued.uniqueKey)`; never fall back to a public swap on failure.
+	*
+	* @example
+	* ```ts
+	* const outcome = await swaps.swapShadow('GALA', 'GUSDC', 3000, { exactIn: '100' });
+	* if (outcome.ok && outcome.queued) await swaps.confirmSwap(outcome.queued.uniqueKey);
+	* ```
+	*/
+	async swapShadow(tokenIn, tokenOut, fee, amount, options) {
+		return this.submitSwapShadow(await this.buildSwap(tokenIn, tokenOut, fee, amount, options));
+	}
+	/**
+	* Builds the RequestTrade DTO that {@link swap} would sign, without signing or sending it: to
+	* show in an approval popup, to remember its `uniqueKey`, or to sign elsewhere. Submit exactly
+	* this DTO with {@link submitSwap}. The pure counterpart, with canonical inputs and no
+	* resolution, is `buildRequestTradeDto`.
+	*
+	* @example
+	* ```ts
+	* const dto = await swaps.buildSwap('GALA', 'GUSDC', 3000, { exactIn: '100' });
+	* showApproval(dto);
+	* const submitted = await swaps.submitSwap(dto);
+	* ```
+	*/
+	async buildSwap(tokenIn, tokenOut, fee, amount, options) {
 		validateFee(fee);
-		const dto = await this.buildRequestTradeDto(tokenIn, tokenOut, fee, amount);
+		const uniqueKey = (options === null || options === void 0 ? void 0 : options.uniqueKey) ?? createUniqueKey(this.uniqueKeyPrefix);
+		assertUniqueKey(uniqueKey);
+		const tokenInSymbol = await tradingSymbolOf(this.symbols, tokenIn);
+		const tokenOutSymbol = await tradingSymbolOf(this.symbols, tokenOut);
+		const ordered = this.orientPool(tokenInSymbol, tokenOutSymbol, options === null || options === void 0 ? void 0 : options.pool);
+		return buildRequestTradeDto({
+			token0: ordered.token0,
+			token1: ordered.token1,
+			fee,
+			tokenInIsToken0: tokenInSymbol === ordered.token0,
+			uniqueKey,
+			...amount
+		});
+	}
+	/**
+	* Signs and submits a DTO built by {@link buildSwap} or `buildRequestTradeDto`. The DTO must be
+	* exactly what the builder produces (no signature, canonical decimals, builder key order), so
+	* what an app showed is what gets signed.
+	*
+	* @example
+	* ```ts
+	* const submitted = await swaps.submitSwap(dto);
+	* const applied = await submitted.confirm();
+	* ```
+	*/
+	async submitSwap(dto) {
+		const signed = await this.signRequestTrade(dto);
+		return this.gateway.submit("RequestTrade", signed, this.submitOptions());
+	}
+	/** Signs and shadow-submits a DTO built by {@link buildSwap}; see {@link swapShadow}. */
+	async submitSwapShadow(dto) {
+		const signed = await this.signRequestTrade(dto);
+		const result = await this.gateway.submitShadow("RequestTrade", signed, this.submitOptions());
+		return readShadowSubmitOutcome("RequestTrade", signed, result);
+	}
+	submitOptions() {
+		return this.walletAddress === void 0 ? {} : { walletAddress: this.walletAddress };
+	}
+	async signRequestTrade(dto) {
+		assertCanonicalV2Dto("RequestTrade", dto);
 		if (this.signer === void 0) throw GSwapSDKError.noSignerError();
-		const signedDto = await this.signer.signObject("RequestTrade", dto);
-		const submitOptions = this.walletAddress === void 0 ? {} : { walletAddress: this.walletAddress };
-		return this.gateway.submit("RequestTrade", signedDto, submitOptions);
+		return this.signer.signObject("RequestTrade", dto);
+	}
+	/** The pool's two symbols in contract order: the quote's own when pinned, else string order. */
+	orientPool(tokenInSymbol, tokenOutSymbol, pool) {
+		if (pool === void 0) return readOrderedSymbols(orderSymbols(tokenInSymbol, tokenOutSymbol));
+		if (!(tokenInSymbol === pool.token0 && tokenOutSymbol === pool.token1 || tokenInSymbol === pool.token1 && tokenOutSymbol === pool.token0)) throw new GSwapSDKError("tokenIn and tokenOut must be the two tokens of the pinned pool.", "VALIDATION_ERROR", {
+			type: "POOL_MISMATCH",
+			tokenIn: tokenInSymbol,
+			tokenOut: tokenOutSymbol,
+			pool
+		});
+		return {
+			token0: pool.token0,
+			token1: pool.token1
+		};
 	}
 	/**
 	* Confirm a swap by its durable `uniqueKey` without resubmitting it. This is the recovery
@@ -2286,11 +3797,11 @@ var Swaps = class {
 	*
 	* @example
 	* ```ts
-	* const applied = await swaps.confirmSwap('gswap-sdk-2f1c…');
+	* const applied = await swaps.confirmSwap('galaswap-operation-2f1c…');
 	* ```
 	*/
 	async confirmSwap(uniqueKey, options) {
-		if (!UNIQUE_KEY_PATTERN.test(uniqueKey)) throw new GSwapSDKError("uniqueKey must be 1-128 characters of A-Z, a-z, 0-9, \".\", \"_\", \":\" or \"-\".", "VALIDATION_ERROR", { uniqueKey });
+		assertUniqueKey(uniqueKey);
 		return new SubmittedTransaction({
 			method: "RequestTrade",
 			uniqueKey,
@@ -2299,53 +3810,14 @@ var Swaps = class {
 			result: void 0,
 			dexBackendBaseUrl: this.gateway.dexBackendBaseUrl,
 			httpRequestor: this.gateway.httpRequestor,
-			requestTimeoutMs: this.gateway.requestTimeoutMs
+			requestTimeoutMs: this.gateway.requestTimeoutMs,
+			wire: this.gateway.wire
 		}).confirm({
 			initialDelayMs: 0,
 			...options
 		});
 	}
-	async buildRequestTradeDto(tokenIn, tokenOut, fee, amount) {
-		const tokenInSymbol = await resolveSymbol(this.symbols, tokenIn);
-		const tokenOutSymbol = await resolveSymbol(this.symbols, tokenOut);
-		const ordered = readOrderedSymbols(orderSymbols(tokenInSymbol, tokenOutSymbol));
-		const tokenInIsToken0 = tokenInSymbol === ordered.token0;
-		const dto = {
-			token0: ordered.token0,
-			token1: ordered.token1,
-			fee,
-			uniqueKey: `gswap-sdk-${globalThis.crypto.randomUUID()}`
-		};
-		if ("exactIn" in amount) {
-			const exactIn = amount.exactIn;
-			if (exactIn === void 0) throw new GSwapSDKError("exactIn is required for an exact-input swap.", "VALIDATION_ERROR");
-			validateNumericAmount(exactIn, "exactIn");
-			dto[tokenInIsToken0 ? "sell0Qty" : "sell1Qty"] = toDecimalString(exactIn);
-			if (amount.amountOutMinimum !== void 0) {
-				validateNumericAmount(amount.amountOutMinimum, "amountOutMinimum", true);
-				dto["amountOutMinimum"] = toDecimalString(amount.amountOutMinimum);
-			}
-		} else {
-			const exactOut = amount.exactOut;
-			if (exactOut === void 0) throw new GSwapSDKError("exactOut is required for an exact-output swap.", "VALIDATION_ERROR");
-			validateNumericAmount(exactOut, "exactOut");
-			dto[tokenInIsToken0 ? "buy1Qty" : "buy0Qty"] = toDecimalString(exactOut);
-			if (amount.amountInMaximum !== void 0) {
-				validateNumericAmount(amount.amountInMaximum, "amountInMaximum", true);
-				dto["amountInMaximum"] = toDecimalString(amount.amountInMaximum);
-			}
-		}
-		return dto;
-	}
 };
-function toDecimalString(amount) {
-	return new bignumber_js.default(amount).toFixed();
-}
-async function resolveSymbol(symbols, token) {
-	const resolved = await symbols.resolve(token);
-	if (resolved.symbol.length > 0) return resolved.symbol;
-	throw new GSwapSDKError("Token could not be resolved to a trading symbol.", "SYMBOL_NOT_FOUND", { token });
-}
 
 //#endregion
 //#region src/classes/gswap.ts
@@ -2362,8 +3834,11 @@ var GSwap = class {
 	positions;
 	swaps;
 	assets;
+	/** Network-fee quotes (DryRun) signed with this client's signer. */
+	fees;
 	dexBackendWsUrl;
 	webSocketImpl;
+	streamApiKey;
 	streamClient;
 	/**
 	* Create an SDK client for prod or stage.
@@ -2380,21 +3855,30 @@ var GSwap = class {
 		this.chainCallTimeoutMs = (options === null || options === void 0 ? void 0 : options.chainCallTimeoutMs) ?? 3e4;
 		this.signer = options === null || options === void 0 ? void 0 : options.signer;
 		this.walletAddress = options === null || options === void 0 ? void 0 : options.walletAddress;
-		const httpClient = new HttpClient(options === null || options === void 0 ? void 0 : options.httpRequestor, this.chainCallTimeoutMs);
+		const httpClient = new HttpClient(options === null || options === void 0 ? void 0 : options.httpRequestor, this.chainCallTimeoutMs, options === null || options === void 0 ? void 0 : options.wire);
 		this.gateway = new ChainGateway({
 			dexBackendBaseUrl: this.dexBackendBaseUrl,
 			chainCallTimeoutMs: this.chainCallTimeoutMs,
+			...(options === null || options === void 0 ? void 0 : options.wire) === void 0 ? {} : { wire: options.wire },
 			...(options === null || options === void 0 ? void 0 : options.httpRequestor) === void 0 ? {} : { httpRequestor: options.httpRequestor },
 			...this.walletAddress === void 0 ? {} : { walletAddress: this.walletAddress }
 		});
-		this.symbols = new Symbols(this.gateway);
-		this.quoting = new Quoting(this.dexBackendBaseUrl, httpClient, this.symbols);
-		this.pools = new Pools(this.gateway, this.symbols);
-		this.positions = new Positions(this.gateway, this.symbols, this.signer, this.walletAddress);
-		this.swaps = new Swaps(this.gateway, this.symbols, this.signer, this.walletAddress);
+		const lenient = { onInvalidEntry: options === null || options === void 0 ? void 0 : options.onInvalidEntry };
+		this.symbols = new Symbols(this.gateway, lenient);
+		const resolver = (options === null || options === void 0 ? void 0 : options.symbolResolution) === "canonical" ? new CanonicalSymbols() : this.symbols;
+		this.quoting = new Quoting(this.gateway, resolver);
+		this.pools = new Pools(this.gateway, resolver, lenient);
+		const keyOptions = {
+			uniqueKeyPrefix: options === null || options === void 0 ? void 0 : options.uniqueKeyPrefix,
+			...lenient
+		};
+		this.positions = new Positions(this.gateway, resolver, this.signer, this.walletAddress, keyOptions);
+		this.swaps = new Swaps(this.gateway, resolver, this.signer, this.walletAddress, keyOptions);
 		this.assets = new Assets(this.dexBackendBaseUrl, httpClient);
+		this.fees = new DexFees(this.gateway, this.signer);
 		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;
+		this.streamApiKey = options === null || options === void 0 ? void 0 : options.streamApiKey;
 	}
 	/**
 	* The realtime stream client for this environment (created on first use, not connected until you
@@ -2410,7 +3894,8 @@ var GSwap = class {
 	get stream() {
 		this.streamClient ??= new GdexStreamService({
 			url: this.dexBackendWsUrl,
-			...this.webSocketImpl === void 0 ? {} : { webSocketImpl: this.webSocketImpl }
+			...this.webSocketImpl === void 0 ? {} : { webSocketImpl: this.webSocketImpl },
+			...this.streamApiKey === void 0 ? {} : { apiKey: this.streamApiKey }
 		});
 		return this.streamClient;
 	}
@@ -2419,9 +3904,149 @@ function trimTrailingSlash(value) {
 	return value.replace(/\/$/u, "");
 }
 
+//#endregion
+//#region src/classes/pending_swaps.ts
+/** Key the wallet_extension has always used; its storage value is a plain array of entries. */
+const PENDING_SWAPS_STORAGE_KEY = "pendingSwaps.v1";
+/** Entries older than this are dropped the next time a wallet's swaps are listed. */
+const PENDING_SWAP_EXPIRY_MS = 6048e5;
+/**
+* Remembers queued swaps so their outcome can be confirmed after the UI, popup or service worker
+* that submitted them is gone (`confirmAppliedTrade` with the stored `uniqueKey`).
+*
+* Guarantees:
+* - Persistence is best effort and NEVER throws: a failing or missing storage must not turn an
+*   accepted request into a client-side resubmission. `list` resolves `[]` when storage fails.
+* - Operations of one store instance are serialized, so concurrent `remember` / `forget` calls
+*   cannot lose each other's write (read-modify-write over an async adapter). Two store instances
+*   over the same storage (for example popup and service worker) are not coordinated.
+* - Entries that do not match the expected shape are ignored and dropped on the next write.
+* - Entries expire after seven days (an entry exactly seven days old is expired; frontend_v2
+*   kept it for that one millisecond); `list` removes them from storage, which frontend_v2 never
+*   did on read.
+* - New entries go to the end (or `insertAt: 'start'`); `list` returns the wallet's entries in
+*   stored order (or `listOrder: 'newest-first'`).
+* - The stored shape is wallet_extension's by default; `storageKey`, `darkFlagField`, `insertAt`
+*   and `listOrder` reproduce frontend_v2's. JSON key order inside an entry is not preserved.
+*
+* Passing no `storage` yields a store that remembers nothing.
+*
+* @example
+* ```ts
+* const store = new PendingSwapStore({
+*   get: async (key) => (await chrome.storage.local.get(key))[key],
+*   set: (key, value) => chrome.storage.local.set({ [key]: value }),
+* });
+* await store.remember({ uniqueKey, requestTransactionId, wallet, token0Symbol: 'GALA',
+*   token1Symbol: 'GUSDC', isDarkSwap: false, createdAt: Date.now() });
+* for (const swap of await store.list(wallet)) await confirmAppliedTrade(client, swap);
+* ```
+*/
+var PendingSwapStore = class {
+	storage;
+	storageKey;
+	darkFlagField;
+	insertAt;
+	listOrder;
+	now;
+	queue = Promise.resolve();
+	constructor(storage, options = {}) {
+		this.storage = storage;
+		this.storageKey = options.storageKey ?? "pendingSwaps.v1";
+		this.darkFlagField = options.darkFlagField ?? "isDarkSwap";
+		this.insertAt = options.insertAt ?? "end";
+		this.listOrder = options.listOrder ?? "stored";
+		this.now = options.now ?? Date.now;
+	}
+	/** Saves (or replaces, by `uniqueKey`) a pending swap. */
+	remember(swap) {
+		return this.enqueue(async (storage) => {
+			const others = (await this.read(storage)).filter((entry) => entry.uniqueKey !== swap.uniqueKey).map(this.toStored);
+			const stored = this.toStored(swap);
+			await storage.set(this.storageKey, this.insertAt === "end" ? [...others, stored] : [stored, ...others]);
+		});
+	}
+	/** Removes a pending swap once its outcome is known. */
+	forget(uniqueKey) {
+		return this.enqueue(async (storage) => {
+			const current = await this.read(storage);
+			await storage.set(this.storageKey, current.filter((entry) => entry.uniqueKey !== uniqueKey).map(this.toStored));
+		});
+	}
+	/** The wallet's unexpired pending swaps (see `listOrder`). Expired entries are pruned. */
+	async list(wallet) {
+		return await this.enqueue(async (storage) => {
+			const current = await this.read(storage);
+			const now = this.now();
+			const fresh = current.filter((entry) => now - entry.createdAt < 6048e5);
+			if (fresh.length !== current.length) await storage.set(this.storageKey, fresh.map(this.toStored));
+			const mine = fresh.filter((entry) => entry.wallet === wallet);
+			return this.listOrder === "newest-first" ? mine.sort((left, right) => right.createdAt - left.createdAt) : mine;
+		}) ?? [];
+	}
+	enqueue(operation) {
+		const storage = this.storage;
+		if (storage === void 0) return Promise.resolve(void 0);
+		const run = this.queue.then(async () => {
+			try {
+				return await operation(storage);
+			} catch {
+				return;
+			}
+		});
+		this.queue = run;
+		return run;
+	}
+	async read(storage) {
+		const value = await storage.get(this.storageKey);
+		if (!Array.isArray(value)) return [];
+		const entries = [];
+		for (const item of value) {
+			const entry = this.fromStored(item);
+			if (entry !== void 0) entries.push(entry);
+		}
+		return entries;
+	}
+	toStored = (swap) => ({
+		uniqueKey: swap.uniqueKey,
+		requestTransactionId: swap.requestTransactionId,
+		wallet: swap.wallet,
+		token0Symbol: swap.token0Symbol,
+		token1Symbol: swap.token1Symbol,
+		[this.darkFlagField]: swap.isDarkSwap,
+		createdAt: swap.createdAt
+	});
+	fromStored(value) {
+		if (value === null || typeof value !== "object") return void 0;
+		const entry = value;
+		const flag = entry[this.darkFlagField];
+		const { uniqueKey, requestTransactionId, wallet, token0Symbol, token1Symbol, createdAt } = entry;
+		if (typeof uniqueKey !== "string" || !(typeof requestTransactionId === "string" || requestTransactionId === null) || typeof wallet !== "string" || typeof token0Symbol !== "string" || typeof token1Symbol !== "string" || typeof flag !== "boolean" || typeof createdAt !== "number" || !Number.isFinite(createdAt)) return;
+		return {
+			uniqueKey,
+			requestTransactionId,
+			wallet,
+			token0Symbol,
+			token1Symbol,
+			isDarkSwap: flag,
+			createdAt
+		};
+	}
+};
+
 //#endregion
 //#region src/utils/eip712.ts
 /**
+* Genuine EIP-712 typed-data signing for the four v2 dex-contract operations proven (2026-09-16,
+* live bisection against stage — see defi-backend's `chain-findings-artifact` memory /
+* https://claude.ai/artifact/3N9MevSjoQdU7gqnVB3dfU) to recover the `client|` identity correctly
+* via `eth_signTypedData_v4`, unlike `personal_sign` (which only ever resolves the bare `eth|`
+* form — see `BrowserWalletSigner`'s own doc comment). Mirrors frontend_v2's
+* `src/Services/eip712Types.ts` + `readWriteUtilsV2.ts`'s `EIP712_FIELD_COMPLETERS` exactly —
+* ported here rather than shared as a package because gswap-sdk has no frontend_v2 dependency
+* and should not gain one for four small functions.
+*/
+/**
 * Derives the EIP-712 `types` for a DTO from its runtime shape.
 *
 * The generated `types` travel with the signed payload and are what BOTH sides hash, so they
@@ -2486,11 +4111,24 @@ function generateEIP712Types(typeName, params) {
 	});
 	return types;
 }
-/** Matches every genuine-EIP-712 probe that has actually recovered `client|` on stage. */
-const EIP712_DOMAIN = {
-	name: "ethereum",
-	chainId: 1
-};
+/**
+* Builds the EIP-712 domain from the wallet's LIVE `eth_chainId` result, exactly like frontend_v2
+* (DEFI-1895): a wallet hashes whatever domain it is handed, and MetaMask refuses a `chainId` that
+* differs from its active network, so a hardcoded `1` breaks every wallet that is not on Mainnet.
+* defi-backend recovers the signer from the `domain` the payload carries (live-proven for chain
+* ids 1, 56 and 11155111), so following the wallet is correct on every network.
+*
+* @param chainId - The raw `eth_chainId` result: a `0x` hex string (the JSON-RPC form) or an integer.
+* @throws GSwapSDKError (`INVALID_CHAIN_ID`) when the wallet answers with anything else.
+*/
+function eip712DomainFor(chainId) {
+	const parsed = typeof chainId === "string" && /^0x[0-9a-fA-F]+$/u.test(chainId) ? Number(chainId) : typeof chainId === "number" ? chainId : NaN;
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new GSwapSDKError("Wallet returned an invalid chain id.", "INVALID_CHAIN_ID", { chainId });
+	return {
+		name: "ethereum",
+		chainId: parsed
+	};
+}
 /**
 * The four v2 operations proven to recover the signer correctly via genuine EIP-712: `RequestTrade`
 * never had the problem (one numeric field). `AddLiquidity`/`RemoveLiquidity`/
@@ -2587,15 +4225,216 @@ function buildEIP712Payload(methodName, dto) {
 }
 
 //#endregion
-//#region src/classes/signers.ts
+//#region src/utils/signing.ts
+/**
+* SDK-owned signing primitives.
+*
+* Everything the SDK needs to produce a GalaChain signature lives here, with no dependency on
+* `@gala-chain/api` (which drags `secp256k1` native bindings, `reflect-metadata`, `class-validator`
+* and its own `bignumber.js` major into every consumer). The only runtime dependencies are the
+* audited, pure-JS `@noble/curves` (secp256k1) and `@noble/hashes` (keccak256), which run
+* unchanged in browsers, MV3 service workers, Node and React Native/Hermes.
+*
+* Every function here is pinned byte-for-byte to the signatures produced by `@gala-chain/api`
+* (`serialize`, `signatures.getSignature`), `@gala-chain/connect`, the Gala Wallet extension and
+* frontend_v2 by the golden-vector suite in `tests/signing-golden.test.ts`.
+*/
+const textEncoder$1 = new TextEncoder();
+function toDeterministicNode(node) {
+	if (node === null || node === void 0) return node;
+	if (node instanceof RegExp) return node.toString();
+	const candidate = node;
+	return typeof candidate.toJSON === "function" ? Reflect.apply(candidate.toJSON, node, []) : node;
+}
+function deterministicNode(rawNode) {
+	const node = toDeterministicNode(rawNode);
+	if (node === void 0) return void 0;
+	if (typeof node !== "object" || node === null) return JSON.stringify(node);
+	if (Array.isArray(node)) return `[${node.map((item) => deterministicNode(item) ?? "null").join(",")}]`;
+	const record = node;
+	const members = [];
+	for (const key of Object.keys(record).sort()) {
+		const value = deterministicNode(record[key]);
+		if (value === void 0) continue;
+		members.push(`${JSON.stringify(key)}:${value}`);
+	}
+	return `{${members.join(",")}}`;
+}
+/**
+* GalaChain's deterministic JSON: object keys sorted (UTF-16 code-unit order) at every depth, no
+* whitespace, `undefined`/function members dropped, `toJSON()` honored. Byte-identical to
+* `serialize` from `@gala-chain/api` / `json-stringify-deterministic` for every JSON-shaped
+* value, which is all a DTO ever is.
+*
+* @throws TypeError for circular structures and BigInt values (as `JSON.stringify` does) and
+* when the value itself has no JSON representation (`undefined`, a function, a symbol).
+*/
+function serialize(value) {
+	JSON.stringify(value);
+	const result = deterministicNode(value);
+	if (result === void 0) throw new TypeError("Cannot serialize a value with no JSON representation.");
+	return result;
+}
+/**
+* The exact string GalaChain hashes for a DTO: the (optional, string) `prefix` field PREPENDED to
+* the deterministic serialization of the DTO WITHOUT `signature`, `multisig`, `trace` and `prefix`.
+* Equivalent to `@gala-chain/api` 3.x `getPayloadToSign` for every non-EIP-712 DTO.
+*/
+function getPayloadToSign(dto) {
+	const { prefix, ...rest } = dto;
+	delete rest["signature"];
+	delete rest["multisig"];
+	delete rest["trace"];
+	return (typeof prefix === "string" ? prefix : "") + serialize(rest);
+}
 const ETHEREUM_SIGNED_MESSAGE = String.fromCharCode(25) + "Ethereum Signed Message:\n";
-/** The EIP-191 header for `dto`'s canonical JSON (UTF-8 byte length; any `prefix` on it is ignored). */
+/**
+* The EIP-191 header for `message`: `"\x19Ethereum Signed Message:\n"` + the message's UTF-8 BYTE
+* length. This is what a wallet's `personal_sign` prepends, and what the chain recomputes when it
+* recovers a personal-signed DTO.
+*/
+function calculatePersonalSignPrefix(message) {
+	return ETHEREUM_SIGNED_MESSAGE + String(textEncoder$1.encode(message).length);
+}
+/**
+* The EIP-191 header for `serialize(dto)` (any `prefix` already on the DTO is ignored). This is
+* deliberately the same string the signers hand a wallet to sign, so the header's length can never
+* disagree with the signed message. Wallet-neutral: it is the value both a browser wallet's
+* `personal_sign` and Gala Wallet's `gala_signChainDto` (personal-sign scheme) prepend.
+*/
 function personalSignPrefixFor(dto) {
 	const withoutPrefix = { ...dto };
 	delete withoutPrefix["prefix"];
-	const message = (0, _gala_chain_api.serialize)(withoutPrefix);
-	return ETHEREUM_SIGNED_MESSAGE + String(new TextEncoder().encode(message).length);
+	return calculatePersonalSignPrefix(serialize(withoutPrefix));
+}
+/**
+* The `@gala-chain/connect`-style prefix frontend_v2 puts in the body of an EIP-712 write: the
+* EIP-191 header whose number counts the prefix string ITSELF plus the body (the UTF-8 length of
+* `getPayloadToSign({ ...dto, prefix })`), found by fixpoint because adding the prefix changes the
+* length (a body of 99 bytes settles on 101).
+*
+* It is NOT a personal-sign prefix (a personal-sign write with this value recovers a phantom
+* signer; use `personalSignPrefixFor`). Under EIP-712 the field is an untyped extra that the
+* typed-data hash ignores and defi-backend recomputes, so it only exists to keep the submitted
+* body byte-identical to what frontend_v2 has always sent.
+*/
+function fixpointPrefixFor(dto) {
+	const withoutPrefix = { ...dto };
+	delete withoutPrefix["prefix"];
+	let payloadLength = textEncoder$1.encode(getPayloadToSign(withoutPrefix)).length;
+	let prefix = ETHEREUM_SIGNED_MESSAGE + String(payloadLength);
+	let previousLength = -1;
+	while (payloadLength !== previousLength) {
+		previousLength = payloadLength;
+		prefix = ETHEREUM_SIGNED_MESSAGE + String(payloadLength);
+		payloadLength = textEncoder$1.encode(getPayloadToSign({
+			...withoutPrefix,
+			prefix
+		})).length;
+	}
+	return prefix;
+}
+function invalidPrivateKey(reason) {
+	return new GSwapSDKError(`Invalid private key: ${reason}`, "VALIDATION_ERROR", { type: "INVALID_PRIVATE_KEY" });
+}
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function decodeBase64(input) {
+	if (!/^[A-Za-z0-9+/]+={0,2}$/u.test(input) || input.length % 4 !== 0) return void 0;
+	const unpadded = input.replace(/=+$/u, "");
+	const bytes = [];
+	let buffer = 0;
+	let bits = 0;
+	for (const char of unpadded) {
+		buffer = buffer << 6 | BASE64_ALPHABET.indexOf(char);
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes.push(buffer >> bits & 255);
+		}
+	}
+	return Uint8Array.from(bytes);
 }
+function decodeHex(input) {
+	const bytes = new Uint8Array(input.length / 2);
+	for (let index = 0; index < bytes.length; index += 1) bytes[index] = parseInt(input.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+}
+/**
+* Normalizes a secp256k1 private key to a fresh 32-byte array (the caller may zero it). Also
+* accepts 32 raw bytes, which are validated and copied. For strings it accepts what `@gala-chain/api`'s
+* `normalizePrivateKey` accepted for a usable key: 64 hex characters (optionally `0x`-prefixed;
+* a 63-character hex key is left-padded with a zero) or a 44-character base64 string.
+*
+* @throws GSwapSDKError (`VALIDATION_ERROR`) for any other shape or an out-of-range scalar.
+*/
+function normalizePrivateKey(input) {
+	if (typeof input !== "string") {
+		if (!(input instanceof Uint8Array) || input.length !== 32) throw invalidPrivateKey("expected exactly 32 bytes.");
+		if (!_noble_curves_secp256k1.secp256k1.utils.isValidSecretKey(input)) throw invalidPrivateKey("not a valid secp256k1 scalar.");
+		return Uint8Array.from(input);
+	}
+	const withoutPrefix = input.startsWith("0x") ? input.slice(2) : input;
+	let key;
+	if (/^[0-9a-fA-F]{63,64}$/u.test(withoutPrefix)) key = decodeHex(withoutPrefix.length === 63 ? `0${withoutPrefix}` : withoutPrefix);
+	else if (withoutPrefix.length === 44) key = decodeBase64(withoutPrefix);
+	if ((key === null || key === void 0 ? void 0 : key.length) !== 32) throw invalidPrivateKey("expected 64 hex characters or a 44-character base64 string.");
+	if (!_noble_curves_secp256k1.secp256k1.utils.isValidSecretKey(key)) throw invalidPrivateKey("not a valid secp256k1 scalar.");
+	return key;
+}
+/**
+* Signs a 32-byte keccak256 hash and returns GalaChain's recoverable signature: 64 hex `r` +
+* 64 hex `s` + `1b`/`1c` (`v`), lowercase, no `0x`. Deterministic (RFC 6979) and low-S, exactly
+* what `@gala-chain/api` and the Gala Wallet produce. A DER signature carries no recovery byte
+* and cannot be used: the chain RECOVERS the signer from the signature.
+*/
+function signHash(privateKey, hash) {
+	if (hash.length !== 32) throw new GSwapSDKError(`secp256k1 can only sign a 32-byte hash (got ${hash.length}).`, "VALIDATION_ERROR");
+	const signature = _noble_curves_secp256k1.secp256k1.sign(hash, privateKey, {
+		prehash: false,
+		lowS: true
+	});
+	return (0, _noble_hashes_utils.bytesToHex)(signature.toBytes("compact")) + (signature.recovery === 1 ? "1c" : "1b");
+}
+/**
+* The lowercase `0x` Ethereum address (last 20 bytes of keccak256 of the uncompressed public key)
+* of a normalized private key. The Gala `eth|` identity of a key is this address.
+*/
+function ethAddressOfPrivateKey(privateKey) {
+	const publicKey = _noble_curves_secp256k1.secp256k1.getPublicKey(privateKey, false);
+	return `0x${(0, _noble_hashes_utils.bytesToHex)((0, _noble_hashes_sha3.keccak_256)(publicKey.slice(1)).slice(-20))}`;
+}
+/** keccak256 of a string's UTF-8 bytes. */
+function keccak256Utf8(data) {
+	return (0, _noble_hashes_sha3.keccak_256)(textEncoder$1.encode(data));
+}
+/**
+* GalaChain NATIVE signature over an already-serialized DTO: keccak256 of the exact bytes, with no
+* prefix and no signature envelope. The caller owns serialization, so the bytes shown to a user
+* and the bytes signed can never diverge.
+*/
+function signSerializedNative(privateKey, serializedDto) {
+	return signHash(privateKey, keccak256Utf8(serializedDto));
+}
+/**
+* GalaChain NATIVE signature for a DTO: keccak256 of `getPayloadToSign(dto)`, signed with
+* secp256k1. Byte-identical to `signatures.getSignature` from `@gala-chain/api`.
+*/
+function signNative(privateKey, dto) {
+	return signSerializedNative(privateKey, getPayloadToSign(dto));
+}
+/**
+* Personal-sign hash and signature: keccak256(`prefix` + `message`), both hashed VERBATIM with no
+* further EIP-191 wrapping. Passing `prefix = calculatePersonalSignPrefix(message)` reproduces a
+* wallet's `personal_sign` of `message`. Gala Wallet's `gala_signChainDto` (personal-sign
+* scheme) hashes `prefix` + the exact string it is handed, which can differ from the bare message
+* (see the `signatureOverPrefixlessBody` vectors); that quirk is why the two inputs stay separate.
+*/
+function signPersonalMessage(privateKey, prefix, message) {
+	return signHash(privateKey, keccak256Utf8(prefix + message));
+}
+
+//#endregion
+//#region src/classes/signers.ts
 function getWalletProvider() {
 	var _globalObject$window;
 	const wallet = (_globalObject$window = globalThis.window) === null || _globalObject$window === void 0 ? void 0 : _globalObject$window.gala;
@@ -2604,32 +4443,77 @@ function getWalletProvider() {
 }
 function getNativeSignature(value) {
 	if (typeof value !== "string") throw new GSwapSDKError("Wallet returned an invalid signature.", "INVALID_SIGNATURE");
-	if (!/^[0-9a-fA-F]{130}$/u.test(value)) throw new GSwapSDKError("Wallet returned an invalid native signature.", "INVALID_SIGNATURE");
+	if (!/^(?:0x)?[0-9a-fA-F]{130}$/u.test(value)) throw new GSwapSDKError("Wallet returned an invalid native signature.", "INVALID_SIGNATURE");
 	return value;
 }
 function getPersonalSignature(value) {
 	if (typeof value !== "string" || !/^(?:0x)?[0-9a-fA-F]{130}$/u.test(value)) throw new GSwapSDKError("Wallet returned an invalid personal-sign signature.", "INVALID_SIGNATURE");
 	return value;
 }
+/**
+* The `0x`-prefixed Ethereum address a Gala account is signed by, or `undefined` when the account
+* names no key (a `client|` alias or a bare GalaChain id is not derivable from a key). Accepts
+* `0x` plus 40 hex digits and `eth|` plus 40 hex digits, with or without `0x`; the caller's casing
+* is kept. For {@link LazyPrivateKeySignerOptions.expectedAddress}, which should only be set for
+* an account whose key can be checked.
+*
+* @example
+* ```ts
+* createLazyPrivateKeySigner(getKey, { expectedAddress: ethereumAddressOfAccount(account) });
+* ```
+*/
+function ethereumAddressOfAccount(account) {
+	const match = /^(?:eth\|(?:0x)?|0x)([0-9a-fA-F]{40})$/u.exec(account);
+	return (match === null || match === void 0 ? void 0 : match[1]) === void 0 ? void 0 : `0x${match[1]}`;
+}
 function normalizeEthereumAccount(address, allowGalaPrefix) {
-	const normalized = allowGalaPrefix && address.startsWith("eth|") ? address.slice(4) : address;
+	const normalized = allowGalaPrefix ? ethereumAddressOfAccount(address) ?? address : address;
 	if (!/^0x[0-9a-fA-F]{40}$/u.test(normalized)) throw new GSwapSDKError("Wallet address must be the selected Ethereum account in 0x-prefixed form.", "VALIDATION_ERROR", {
 		type: "INVALID_WALLET_ADDRESS",
 		value: address
 	});
-	return `0x${normalized.slice(2).toLowerCase()}`;
+	return normalized;
 }
-function getErrorMessage(error) {
-	if (error instanceof Error) return error.message;
-	if (typeof error === "string") return error;
-	if (typeof error === "object" && error !== null && "message" in error) {
-		const message = error.message;
-		return typeof message === "string" ? message : "";
-	}
-	return "";
+/**
+* The account handed to Gala Wallet as the signer address. An Ethereum account is held to the
+* same strict check as ever (`0x` plus 40 hex digits; `eth|` plus 40 hex digits, with or without
+* `0x`, is normalized to it). A GalaChain id the wallet can also be asked to sign for is passed
+* through verbatim: `client|` plus 24 hex digits, or the bare 24 hex digits that frontend_v2 keeps
+* in `state.user.wallet` after a direct `client|` login. Nothing else is accepted.
+*/
+function normalizeGalaWalletAccount(address) {
+	const eth = /^eth\|(?:0x)?([0-9a-fA-F]{40})$/u.exec(address);
+	if ((eth === null || eth === void 0 ? void 0 : eth[1]) !== void 0) return `0x${eth[1]}`;
+	if (/^0x[0-9a-fA-F]{40}$/u.test(address) || /^(?:client\|)?[0-9a-fA-F]{24}$/u.test(address)) return address;
+	throw new GSwapSDKError("Wallet address must be the selected Ethereum account (0x plus 40 hex digits, or eth|...) or a GalaChain id (client|... or 24 hex digits).", "VALIDATION_ERROR", {
+		type: "INVALID_WALLET_ADDRESS",
+		value: address
+	});
+}
+/** An identity Gala Wallet can act as: an account form above, any `eth|`/`client|` alias, verbatim. */
+function assertWalletIdentity(identity) {
+	if (!/^(?:eth\|(?:0x)?[0-9a-fA-F]{40}|0x[0-9a-fA-F]{40}|(?:client\|)?[0-9a-fA-F]{24})$/u.test(identity)) throw new GSwapSDKError("selectAddress must be an eth| or client| identity, or an account in one of the accepted forms.", "VALIDATION_ERROR", {
+		type: "INVALID_WALLET_ADDRESS",
+		value: identity
+	});
 }
-function isUnsupportedNativeSchemeError(error) {
-	return /unsupported|unknown scheme/i.test(getErrorMessage(error));
+/** Provider-wide queue: `setAddress` + the signature request must not interleave across signers. */
+const walletIdentityQueue = /* @__PURE__ */ new WeakMap();
+/**
+* Runs `signWith` with `identity` selected on a Gala Wallet that supports `setAddress`. Gala
+* Wallet holds ONE current account, so two signatures for different identities in flight at once
+* would sign as whichever selection came last; the pair (select, sign) is therefore serialized
+* per provider. A failed selection fails the signature (nothing is requested).
+*/
+function withSelectedIdentity(wallet, identity, signWith) {
+	const { setAddress } = wallet;
+	if (identity === void 0 || typeof setAddress !== "function") return signWith();
+	const run = (walletIdentityQueue.get(wallet) ?? Promise.resolve()).catch(() => void 0).then(async () => {
+		await setAddress.call(wallet, identity);
+		return signWith();
+	});
+	walletIdentityQueue.set(wallet, run);
+	return run;
 }
 function personalSign(provider, dto, walletAddress, methodName) {
 	const prefix = personalSignPrefixFor(dto);
@@ -2638,10 +4522,10 @@ function personalSign(provider, dto, walletAddress, methodName) {
 		prefix
 	};
 	const params = methodName !== void 0 ? [
-		(0, _gala_chain_api.serialize)(payload),
+		serialize(payload),
 		walletAddress,
 		methodName
-	] : [(0, _gala_chain_api.serialize)(dto), walletAddress];
+	] : [serialize(dto), walletAddress];
 	return provider.request({
 		method: methodName !== void 0 ? "gala_signChainDto" : "personal_sign",
 		params
@@ -2660,9 +4544,13 @@ function personalSign(provider, dto, walletAddress, methodName) {
 * byte-for-byte equivalent (same recovered address from the same signature against both
 * constructions) before this shipped, since gswap-sdk deliberately has no ethers dependency.
 */
-function signEIP712(provider, methodName, dto, walletAddress) {
+async function signEIP712(provider, methodName, dto, walletAddress) {
 	const { completedDto, types } = buildEIP712Payload(methodName, dto);
-	const prefix = personalSignPrefixFor(completedDto);
+	const domain = eip712DomainFor(await provider.request({
+		method: "eth_chainId",
+		params: []
+	}));
+	const prefix = fixpointPrefixFor(completedDto);
 	const message = {
 		...completedDto,
 		prefix
@@ -2675,7 +4563,7 @@ function signEIP712(provider, methodName, dto, walletAddress) {
 		type: "uint256"
 	}];
 	const payload = {
-		domain: EIP712_DOMAIN,
+		domain,
 		types: {
 			...types,
 			EIP712Domain: eip712Domain
@@ -2683,15 +4571,16 @@ function signEIP712(provider, methodName, dto, walletAddress) {
 		primaryType: methodName,
 		message
 	};
-	return provider.request({
+	const value = await provider.request({
 		method: "eth_signTypedData_v4",
 		params: [walletAddress, JSON.stringify(payload)]
-	}).then((value) => ({
+	});
+	return {
 		...message,
+		signature: getPersonalSignature(value),
 		types,
-		domain: EIP712_DOMAIN,
-		signature: getPersonalSignature(value)
-	}));
+		domain
+	};
 }
 /**
 * A GalaChain native signer backed by a secp256k1 private key.
@@ -2700,7 +4589,7 @@ function signEIP712(provider, methodName, dto, walletAddress) {
 * or EIP-712 metadata. The private-key identity is recovered by the chain.
 */
 var PrivateKeySigner = class {
-	keyBuffer;
+	privateKey;
 	/**
 	* Creates a native signer from a hex or base64 secp256k1 private key.
 	*
@@ -2711,7 +4600,7 @@ var PrivateKeySigner = class {
 	* ```
 	*/
 	constructor(privateKey) {
-		this.keyBuffer = _gala_chain_api.signatures.normalizePrivateKey(privateKey);
+		this.privateKey = normalizePrivateKey(privateKey);
 	}
 	/**
 	* Signs the DTO with GalaChain native signing.
@@ -2726,7 +4615,7 @@ var PrivateKeySigner = class {
 	* ```
 	*/
 	signObject(_methodName, dto) {
-		const signature = _gala_chain_api.signatures.getSignature(dto, this.keyBuffer);
+		const signature = signNative(this.privateKey, dto);
 		return Promise.resolve({
 			...dto,
 			signature
@@ -2734,18 +4623,65 @@ var PrivateKeySigner = class {
 	}
 };
 /**
-* A Gala Wallet signer using native GalaChain signing, with an opt-in personal-sign mode and
-* automatic fallback for older wallets.
+* Creates the native-signing equivalent of {@link PrivateKeySigner} for apps that must not hold a
+* key in a long-lived object (an extension that reads its session key at sign time).
 *
-* The selected Ethereum account is passed to Gala Wallet. Personal-sign resolves the bare
-* `eth|` identity; the legacy EIP-712 `eth_signTypedData` path is not used. The fallback calls
-* `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])`.
+* `getPrivateKey` is called once per `signObject` call, never cached, never shared between calls
+* (concurrent signatures each fetch their own key), and the normalized key bytes are zeroed
+* before `signObject` settles, also on failure. A rejection or exception from `getPrivateKey` is
+* passed through unchanged, so the app's own "wallet is locked" error reaches its caller; a key
+* that is not a valid secp256k1 key string is a `VALIDATION_ERROR` (`INVALID_PRIVATE_KEY`).
+* Signatures are byte-identical to `new PrivateKeySigner(key).signObject(...)`.
+*
+* A JavaScript string cannot be wiped; the provider owns the lifetime of the string it returns.
+*
+* @example
+* ```typescript
+* const signer = createLazyPrivateKeySigner(
+*   () => SecurityHelper.getSessionSecret(SecurityHelper.SESSION_PRIVATE_KEY_KEY),
+*   { expectedAddress: account.address },
+* );
+* const gswap = new GSwap({ signer });
+* ```
+*/
+function createLazyPrivateKeySigner(getPrivateKey, options = {}) {
+	const expected = options.expectedAddress;
+	const expectedLower = expected === void 0 ? void 0 : normalizeEthereumAccount(expected, true).toLowerCase();
+	return { async signObject(_methodName, dto) {
+		const provided = await getPrivateKey();
+		if (typeof provided !== "string") throw new GSwapSDKError("Invalid private key: the provider returned no key.", "VALIDATION_ERROR", { type: "INVALID_PRIVATE_KEY" });
+		const key = normalizePrivateKey(provided);
+		try {
+			if (expectedLower !== void 0 && ethAddressOfPrivateKey(key) !== expectedLower) throw new GSwapSDKError("The signing key does not belong to the expected account.", "SIGNER_ADDRESS_MISMATCH");
+			return {
+				...dto,
+				signature: signNative(key, dto)
+			};
+		} finally {
+			key.fill(0);
+		}
+	} };
+}
+/**
+* A Gala Wallet signer using native GalaChain signing, with an opt-in personal-sign mode.
+*
+* The selected Ethereum account is passed to Gala Wallet. There is NO automatic fallback: a
+* wallet that rejects `native` surfaces its error to the caller, because the only alternative,
+* `personal-sign`, silently recovers a phantom signer on every released Gala Wallet.
+*
+* `scheme: 'personal-sign'` calls
+* `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])` and REQUIRES
+* a wallet build that contains wallet_extension commit 3ad7ae6 (strips the embedded `prefix`
+* field and hashes `prefix` + the prefix-less canonical body, the chain's scheme). Wallets
+* released before that fix hash the string with the `prefix` field still inside it and the
+* signature recovers to an address nobody holds, so only opt in once the fixed wallet is
+* released. See SIGNING-PARITY.md.
 */
 var GalaWalletSigner = class {
 	/** The wallet address supplied to Gala Wallet for each signing request. */
 	walletAddress;
-	/** The scheme currently used, including any automatic native-to-personal fallback. */
-	effectiveScheme;
+	/** The signing scheme used for every request; it never changes after construction. */
+	scheme;
 	/**
 	* Creates a Gala Wallet signer.
 	*
@@ -2755,14 +4691,23 @@ var GalaWalletSigner = class {
 	* const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
 	* ```
 	*
-	* @param walletAddress - The selected Ethereum account (`0x` plus 40 hex digits); Gala Wallet's
-	* `eth|0x...` form is also accepted and normalized.
-	* @param options - Select native signing or personal-sign explicitly.
+	* @param walletAddress - The account passed to Gala Wallet as the signer address. An Ethereum
+	* account is `0x` plus 40 hex digits (Gala Wallet's `eth|...` form is normalized to it and held
+	* to the same check); a GalaChain id is `client|` plus 24 hex digits, or the bare 24 hex digits
+	* frontend_v2 keeps for a direct `client|` login, and is passed through unchanged.
+	* @param options - Select native signing (default) or personal-sign explicitly.
+	* `'personal-sign'` requires a Gala Wallet build with wallet_extension commit 3ad7ae6.
+	* `selectAddress` is the identity (`client|...` / `eth|...`) Gala Wallet is switched to with
+	* `window.gala.setAddress` before every signature, when the wallet offers it.
 	*/
 	constructor(walletAddress, options = {}) {
-		this.walletAddress = normalizeEthereumAccount(walletAddress, true);
-		this.effectiveScheme = options.scheme ?? "native";
+		this.walletAddress = normalizeGalaWalletAccount(walletAddress);
+		this.scheme = options.scheme ?? "native";
+		if (options.selectAddress !== void 0) assertWalletIdentity(options.selectAddress);
+		this.selectAddress = options.selectAddress;
 	}
+	/** The identity Gala Wallet is switched to before each signature, if one was given. */
+	selectAddress;
 	/**
 	* Signs a DTO through `gala_signChainDto`.
 	*
@@ -2778,12 +4723,12 @@ var GalaWalletSigner = class {
 	*/
 	async signObject(methodName, dto) {
 		const wallet = getWalletProvider();
-		if (this.effectiveScheme === "personal-sign") return personalSign(wallet, dto, this.walletAddress, methodName);
-		try {
+		return withSelectedIdentity(wallet, this.selectAddress, async () => {
+			if (this.scheme === "personal-sign") return personalSign(wallet, dto, this.walletAddress, methodName);
 			const signature = await wallet.request({
 				method: "gala_signChainDto",
 				params: [
-					(0, _gala_chain_api.serialize)(dto),
+					serialize(dto),
 					this.walletAddress,
 					methodName,
 					"native"
@@ -2793,11 +4738,7 @@ var GalaWalletSigner = class {
 				...dto,
 				signature: getNativeSignature(signature)
 			};
-		} catch (error) {
-			if (!isUnsupportedNativeSchemeError(error)) throw error;
-			this.effectiveScheme = "personal-sign";
-			return personalSign(wallet, dto, this.walletAddress, methodName);
-		}
+		});
 	}
 };
 /**
@@ -2858,11 +4799,683 @@ var BrowserWalletSigner = class {
 	}
 };
 
+//#endregion
+//#region src/utils/chain_dto_signing.ts
+/**
+* String-key signing entry points for apps that hold a private key only briefly (the Gala Wallet
+* extension reads its session key at sign time and must not keep it in a long-lived object).
+*
+* These are thin, byte-exact ports of the functions the wallet shipped in
+* `wallet_extension/src/helpers/wallet/signing.ts` (including the fail-closed personal-sign
+* payload resolver from its commit 3ad7ae6), re-expressed over the SDK's own primitives. Every
+* function takes the key as a string (`0x`-optional hex, or base64) or as bytes, normalizes it per
+* call, and zeroes the normalized copy before returning, so nothing in this module retains a key.
+* A JavaScript string cannot be wiped; the caller owns the lifetime of the string it passes in.
+*/
+/**
+* Runs `action` with a private normalized copy of the key, zeroed afterwards (also when `action`
+* throws). Bytes given by the caller are copied, never modified: the caller owns them.
+*/
+function withPrivateKey(privateKey, action) {
+	const key = normalizePrivateKey(privateKey);
+	try {
+		return action(key);
+	} finally {
+		key.fill(0);
+	}
+}
+/**
+* GalaChain NATIVE signature over an already-serialized DTO: keccak256 of the exact bytes with no
+* prefix and no envelope (wallet `signChainDtoNative`). The caller owns serialization, so the
+* bytes a user reviewed and the bytes signed cannot diverge.
+*
+* @returns 130 lowercase hex characters, `r || s || v` with `v` = `1b`/`1c`, no `0x`.
+*/
+function signChainDtoNative(privateKey, serializedDto) {
+	return withPrivateKey(privateKey, (key) => signSerializedNative(key, serializedDto));
+}
+/**
+* The personal-sign hash primitive (wallet `signChainDtoHash`): keccak256(`prefix` + `message`),
+* both verbatim, with no further EIP-191 wrap. `message` must be the DTO's serialization WITHOUT
+* its `prefix` field; callers holding a dApp-supplied string go through `signChainDtoPersonalSign`,
+* which derives both inputs from it.
+*/
+function signChainDtoHash(privateKey, prefix, message) {
+	return withPrivateKey(privateKey, (key) => signPersonalMessage(key, prefix, message));
+}
+const PERSONAL_SIGN_HEADER = String.fromCharCode(25) + "Ethereum Signed Message:\n";
+const PERSONAL_SIGN_LENGTH_PATTERN = /^(?:0|[1-9][0-9]*)$/u;
+function isPersonalSignHeader(prefix) {
+	return prefix.startsWith(PERSONAL_SIGN_HEADER) && PERSONAL_SIGN_LENGTH_PATTERN.test(prefix.slice(26));
+}
+/**
+* Top-level fields that would make the chain (`getPayloadToSign`) or defi-backend's personal-sign
+* verifier hash something other than `prefix + serialize(dto minus prefix)`. An unsigned DTO from
+* a dApp never legitimately carries any of them, so they fail closed. Order is part of the error
+* message the wallet shows its user.
+*/
+const PERSONAL_SIGN_FORBIDDEN_FIELDS = [
+	"signature",
+	"multisig",
+	"trace",
+	"types",
+	"domain",
+	"stringsInstructions"
+];
+function refusePersonalSign(message, type) {
+	throw new GSwapSDKError(message, "INVALID_PERSONAL_SIGN_DTO", { type });
+}
+/**
+* Derives what to hash for a `gala_signChainDto` personal-sign request from the exact string the
+* dApp sent (and the approval card displayed): wallet `resolvePersonalSignChainDtoPayload`.
+*
+* The dApp submits `{ ...dto, prefix, signature }`, which the chain recovers from
+* `keccak256(prefix + serialize(dto WITHOUT prefix))`. So when the string embeds a `prefix`
+* field, that field is removed and the remainder re-serialized; the prefix used is the dApp's own
+* value byte for byte. A string with no `prefix` field is hashed verbatim with an empty prefix
+* (chain-equivalent to a native signature of that exact string).
+*
+* Fails closed (throws `GSwapSDKError` `INVALID_PERSONAL_SIGN_DTO`, message text identical to the
+* wallet's) on: malformed JSON; JSON that is not a plain object; a `prefix` that is not an EIP-191
+* "Ethereum Signed Message" header; any signing-envelope field (`signature`, `multisig`, `trace`,
+* `types`, `domain`, `stringsInstructions`); and a string that is not already the canonical
+* serialization of what it parses to (duplicate keys, lossy numbers, key-order tricks the card
+* would render differently). Stripping `prefix` is therefore the ONLY byte change between the
+* reviewed string and the signed message.
+*/
+function resolvePersonalSignChainDtoPayload(data) {
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		return refusePersonalSign("Personal-sign DTO is not valid JSON", "NOT_JSON");
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return refusePersonalSign("Personal-sign DTO must be a JSON object", "NOT_OBJECT");
+	const dto = parsed;
+	if (!Object.prototype.hasOwnProperty.call(dto, "prefix")) return {
+		prefix: "",
+		message: data
+	};
+	const { prefix, ...withoutPrefix } = dto;
+	if (typeof prefix !== "string" || !isPersonalSignHeader(prefix)) return refusePersonalSign("Personal-sign DTO prefix is not an EIP-191 \"Ethereum Signed Message\" header", "BAD_PREFIX");
+	const forbidden = PERSONAL_SIGN_FORBIDDEN_FIELDS.filter((field) => Object.prototype.hasOwnProperty.call(withoutPrefix, field));
+	if (forbidden.length > 0) return refusePersonalSign(`Personal-sign DTO carries signing-envelope field(s): ${forbidden.join(", ")}`, "ENVELOPE_FIELDS");
+	if (serialize(dto) !== data) return refusePersonalSign("Personal-sign DTO is not in canonical serialized form", "NOT_CANONICAL");
+	return {
+		prefix,
+		message: serialize(withoutPrefix)
+	};
+}
+/**
+* Signs a GalaChain personal-sign scheme DTO from the exact string a dApp sent through
+* `gala_signChainDto` (wallet `signChainDtoPersonalSign`). See
+* `resolvePersonalSignChainDtoPayload` for what is signed and what is refused; the signature
+* recovers, under the chain's `getPayloadToSign`, to this key for the DTO the dApp submits with
+* its `prefix`, and equals a `personal_sign` of the bare body when that prefix is the EIP-191
+* header of the bare body's byte length.
+*
+* @throws GSwapSDKError (`INVALID_PERSONAL_SIGN_DTO`) before any signing when the input is refused.
+*/
+function signChainDtoPersonalSign(privateKey, data) {
+	const { prefix, message } = resolvePersonalSignChainDtoPayload(data);
+	return signChainDtoHash(privateKey, prefix, message);
+}
+/**
+* Raw object signing (wallet `signObject`), used for transfers, bridge and fee-dry-run DTOs the
+* wallet signs itself. Removes ONLY `signature`, signs `keccak256(serialize(rest))` natively
+* (no `prefix` handling, and `trace` / `multisig` stay in the signed bytes, unlike
+* `signNative`), and returns `{ signature, ...rest }` with the signature as the FIRST key, exactly
+* like the wallet. Callers that must not sign extra fields strip them first.
+*/
+function signRawObject(privateKey, obj) {
+	const rest = { ...obj };
+	delete rest["signature"];
+	return {
+		signature: signChainDtoNative(privateKey, serialize(rest)),
+		...rest
+	};
+}
+/**
+* Drops the `EIP712Domain` entry from a dApp-supplied types map (a typed-data encoder derives the
+* domain type itself and rejects an explicit one). The order of the remaining types is preserved.
+*/
+function stripEip712DomainType(types) {
+	const stripped = {};
+	for (const typeName of Object.keys(types)) if (typeName !== "EIP712Domain") stripped[typeName] = types[typeName];
+	return stripped;
+}
+/**
+* `collection$category$type$additionalKey` for a token-class object (wallet `decodeTokenData`).
+* Lenient on purpose: any missing or non-string part becomes `''`, so a display layer never
+* throws on odd input.
+*/
+function tokenClassDollarKey(token) {
+	const part = (field) => {
+		const value = token === null || token === void 0 ? void 0 : token[field];
+		return typeof value === "string" ? value : "";
+	};
+	return `${part("collection")}$${part("category")}$${part("type")}$${part("additionalKey")}`;
+}
+/**
+* A quantity in the form GalaChain's `IsBigNumber` validator accepts: FIXED notation, no leading
+* zeros, no trailing decimal zeros (`BigNumber#toFixed()`; never `toString()`, which turns
+* `0.00000001` into `1e-8`, and never a JS number in between).
+*
+* @throws GSwapSDKError (`VALIDATION_ERROR`) for a value that is not a finite number. The wallet's
+* `cleanNumber` returned the string `'NaN'` there; signing that text can only fail on chain.
+*/
+function canonicalDecimalString(value) {
+	let parsed = new bignumber_js.default(NaN);
+	try {
+		parsed = new bignumber_js.default(value);
+	} catch {}
+	if (!parsed.isFinite()) throw new GSwapSDKError(`Invalid decimal quantity: ${String(value)}`, "VALIDATION_ERROR", { type: "INVALID_DECIMAL" });
+	return parsed.toFixed();
+}
+
+//#endregion
+//#region src/utils/typed_data.ts
+/**
+* EIP-712 (`eth_signTypedData_v4`) hashing and signing for ARBITRARY dApp typed data, built on the
+* SDK's own primitives (`@noble/curves`, `@noble/hashes`) so a wallet can sign a dApp's typed-data
+* approval without ethers. It replaces the wallet's `new ethers.Wallet(key).signTypedData(...)`
+* and is pinned to it: the golden suite reproduces every fixture signature exactly and a seeded
+* differential fuzz compares the digest and signature with ethers for every supported type.
+*
+* Compared with ethers this encoder is deliberately STRICTER (it fails closed rather than coerce):
+* `bool` accepts only a boolean, numbers accept only safe integers / decimal or `0x` strings,
+* strings must be well-formed UTF-16, struct values must be objects whose fields are their own
+* properties, and every struct, field and type name must be a plain identifier. Anything ethers
+* accepts that is NOT in that set is refused here instead of being signed in a different shape
+* from what a user reviewed.
+*/
+const textEncoder = new TextEncoder();
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+const TYPE_SYNTAX = /^([A-Za-z_$][A-Za-z0-9_$]*)((?:\[(?:0|[1-9][0-9]*)?\])*)$/u;
+const BIGINT_DECIMAL = /^-?[0-9]+$/u;
+const BIGINT_HEX = /^-?0x[0-9a-fA-F]+$/u;
+const MAX_UINT256 = (1n << 256n) - 1n;
+/** The EIP-712 domain members and their types, in the order ethers (and the spec) hash them. */
+const DOMAIN_FIELDS = [
+	{
+		name: "name",
+		type: "string"
+	},
+	{
+		name: "version",
+		type: "string"
+	},
+	{
+		name: "chainId",
+		type: "uint256"
+	},
+	{
+		name: "verifyingContract",
+		type: "address"
+	},
+	{
+		name: "salt",
+		type: "bytes32"
+	}
+];
+function refuse(message, details) {
+	throw new GSwapSDKError(`Invalid typed data: ${message}`, "INVALID_TYPED_DATA", details);
+}
+function concat(parts) {
+	const out = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+function bigintToWord(value) {
+	const word = /* @__PURE__ */ new Uint8Array(32);
+	let rest = value < 0n ? value + (1n << 256n) : value;
+	if (rest < 0n || rest > MAX_UINT256) return refuse("integer does not fit in 256 bits");
+	for (let index = 31; index >= 0; index -= 1) {
+		word[index] = Number(rest & 255n);
+		rest >>= 8n;
+	}
+	return word;
+}
+function hexToBytes(hex) {
+	const body = hex.slice(2);
+	const out = new Uint8Array(body.length / 2);
+	for (let index = 0; index < out.length; index += 1) out[index] = parseInt(body.slice(index * 2, index * 2 + 2), 16);
+	return out;
+}
+function toBytes(value, what) {
+	if (value instanceof Uint8Array) return value;
+	if (typeof value === "string" && /^0x(?:[0-9a-fA-F]{2})*$/u.test(value)) return hexToBytes(value);
+	return refuse(`${what} must be an even-length 0x hex string`);
+}
+function toBigInt(value, what) {
+	if (typeof value === "bigint") return value;
+	if (typeof value === "number") {
+		if (!Number.isSafeInteger(value)) return refuse(`${what} must be a safe integer`);
+		return BigInt(value);
+	}
+	if (typeof value === "string") {
+		if (BIGINT_DECIMAL.test(value)) return BigInt(value);
+		if (BIGINT_HEX.test(value)) return value.startsWith("-") ? -BigInt(value.slice(1)) : BigInt(value);
+	}
+	return refuse(`${what} must be an integer`);
+}
+function utf8(value, what) {
+	if (typeof value !== "string") return refuse(`${what} must be a string`);
+	for (let index = 0; index < value.length; index += 1) {
+		const unit = value.charCodeAt(index);
+		if (unit >= 55296 && unit <= 56319) {
+			const next = value.charCodeAt(index + 1);
+			if (!(next >= 56320 && next <= 57343)) return refuse(`${what} has an unpaired surrogate`);
+			index += 1;
+		} else if (unit >= 56320 && unit <= 57343) return refuse(`${what} has an unpaired surrogate`);
+	}
+	return textEncoder.encode(value);
+}
+/** EIP-55: a mixed-case address must carry the right checksum; all-lower / all-upper is accepted. */
+function addressBytes(value) {
+	if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/u.test(value)) return refuse("address must be 0x followed by 40 hex digits");
+	const digits = value.slice(2);
+	if (/[A-F]/u.test(digits) && /[a-f]/u.test(digits)) {
+		const hash = (0, _noble_hashes_sha3.keccak_256)(textEncoder.encode(digits.toLowerCase()));
+		for (let index = 0; index < 40; index += 1) {
+			const nibble = hash[index >> 1] >> (index % 2 === 0 ? 4 : 0) & 15;
+			const char = digits.charAt(index);
+			if (char !== (nibble >= 8 ? char.toUpperCase() : char.toLowerCase())) return refuse("address has a bad checksum");
+		}
+	}
+	return hexToBytes(value);
+}
+/** The encoder for a non-struct, non-array type, or undefined when `base` is not one. */
+function leafEncoder(base) {
+	if (base === "string") return (value) => (0, _noble_hashes_sha3.keccak_256)(utf8(value, "string"));
+	if (base === "bytes") return (value) => (0, _noble_hashes_sha3.keccak_256)(toBytes(value, "bytes"));
+	if (base === "bool") return (value) => {
+		if (typeof value !== "boolean") return refuse("bool must be a boolean");
+		return bigintToWord(value ? 1n : 0n);
+	};
+	if (base === "address") return (value) => concat([/* @__PURE__ */ new Uint8Array(12), addressBytes(value)]);
+	const fixed = /^bytes([1-9][0-9]?)$/u.exec(base);
+	if (fixed !== null) {
+		const width = Number(fixed[1]);
+		if (width > 32 || String(width) !== fixed[1]) return void 0;
+		return (value) => {
+			const bytes = toBytes(value, base);
+			if (bytes.length !== width) return refuse(`${base} must be exactly ${width} bytes`);
+			return concat([bytes, new Uint8Array(32 - width)]);
+		};
+	}
+	const integer = /^(u?)int([1-9][0-9]*)$/u.exec(base);
+	if (integer !== null) {
+		const width = Number(integer[2]);
+		if (width % 8 !== 0 || width > 256 || String(width) !== integer[2]) return void 0;
+		const signed = integer[1] === "";
+		const lower = signed ? -(1n << BigInt(width - 1)) : 0n;
+		const upper = signed ? (1n << BigInt(width - 1)) - 1n : (1n << BigInt(width)) - 1n;
+		return (value) => {
+			const number = toBigInt(value, base);
+			if (number < lower || number > upper) return refuse(`value out of bounds for ${base}`);
+			return bigintToWord(number);
+		};
+	}
+}
+function parseType(type) {
+	const match = TYPE_SYNTAX.exec(type);
+	if (match === null) return refuse(`unsupported type "${type}"`);
+	const dimensions = [...(match[2] ?? "").matchAll(/\[([0-9]*)\]/gu)].map((dimension) => dimension[1] === "" ? -1 : Number(dimension[1]));
+	return {
+		base: match[1],
+		dimensions
+	};
+}
+function parseFields(typeName, rawFields) {
+	if (!Array.isArray(rawFields)) return refuse(`type ${typeName} must be a list of fields`);
+	const seen = /* @__PURE__ */ new Set();
+	return rawFields.map((raw) => {
+		const field = raw;
+		if (typeof (field === null || field === void 0 ? void 0 : field.name) !== "string" || typeof field.type !== "string") return refuse(`type ${typeName} has a field without a string name and type`);
+		if (!IDENTIFIER.test(field.name)) return refuse(`invalid field name "${field.name}"`);
+		if (seen.has(field.name)) return refuse(`duplicate field "${field.name}" in ${typeName}`);
+		seen.add(field.name);
+		const parsed = parseType(field.type);
+		const base = parsed.base === "uint" || parsed.base === "int" ? `${parsed.base}256` : parsed.base;
+		return {
+			name: field.name,
+			type: base + field.type.slice(parsed.base.length)
+		};
+	});
+}
+/**
+* Builds the struct encoder for a set of type definitions: validates the type graph (unknown or
+* circular references, duplicate fields) and infers the primary type as the single type no other
+* type references, exactly like ethers' `TypedDataEncoder`.
+*/
+function createStructEncoder(rawTypes) {
+	const names = Object.keys(rawTypes);
+	const fields = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		if (!IDENTIFIER.test(name)) return refuse(`invalid type name "${name}"`);
+		fields.set(name, parseFields(name, rawTypes[name]));
+	}
+	const children = /* @__PURE__ */ new Map();
+	const parents = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		children.set(name, /* @__PURE__ */ new Set());
+		parents.set(name, /* @__PURE__ */ new Set());
+	}
+	for (const [name, list] of fields) for (const field of list) {
+		var _children$get, _parents$get;
+		const { base } = parseType(field.type);
+		if (base === name) return refuse(`circular type reference in ${name}`);
+		if (leafEncoder(base) !== void 0) continue;
+		if (!fields.has(base)) return refuse(`unknown type "${base}" in ${name}`);
+		(_children$get = children.get(name)) === null || _children$get === void 0 || _children$get.add(base);
+		(_parents$get = parents.get(base)) === null || _parents$get === void 0 || _parents$get.add(name);
+	}
+	const roots = names.filter((name) => {
+		var _parents$get2;
+		return ((_parents$get2 = parents.get(name)) === null || _parents$get2 === void 0 ? void 0 : _parents$get2.size) === 0;
+	});
+	if (roots.length === 0) return refuse("missing primary type");
+	if (roots.length > 1) return refuse("ambiguous primary types or unused types", { roots });
+	const primaryType = roots[0];
+	const visiting = /* @__PURE__ */ new Set();
+	const checked = /* @__PURE__ */ new Set();
+	const checkCircular = (name) => {
+		if (visiting.has(name)) return refuse(`circular type reference at ${name}`);
+		if (checked.has(name)) return;
+		visiting.add(name);
+		for (const child of children.get(name) ?? []) checkCircular(child);
+		visiting.delete(name);
+		checked.add(name);
+	};
+	checkCircular(primaryType);
+	const dependencies = (name, found) => {
+		for (const child of children.get(name) ?? []) if (!found.has(child)) {
+			found.add(child);
+			dependencies(child, found);
+		}
+		return found;
+	};
+	const encodeOne = (name) => `${name}(${(fields.get(name) ?? []).map((field) => `${field.type} ${field.name}`).join(",")})`;
+	const typeHashes = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		const sorted = [...dependencies(name, /* @__PURE__ */ new Set())].filter((dep) => dep !== name).sort();
+		typeHashes.set(name, (0, _noble_hashes_sha3.keccak_256)(textEncoder.encode([name, ...sorted].map(encodeOne).join(""))));
+	}
+	const encodeValue = (parsed, value, depth) => {
+		const dimension = parsed.dimensions[parsed.dimensions.length - 1 - depth];
+		if (dimension !== void 0) {
+			if (!Array.isArray(value)) return refuse(`${parsed.base} array value must be an array`);
+			if (dimension !== -1 && dimension !== value.length) return refuse("array length mismatch");
+			return (0, _noble_hashes_sha3.keccak_256)(concat(value.map((item) => encodeValue(parsed, item, depth + 1))));
+		}
+		const leaf = leafEncoder(parsed.base);
+		if (leaf !== void 0) return leaf(value);
+		return hashStruct(parsed.base, value);
+	};
+	function hashStruct(typeName, value) {
+		const list = fields.get(typeName);
+		const typeHash = typeHashes.get(typeName);
+		if (list === void 0 || typeHash === void 0) return refuse(`unknown type "${typeName}"`);
+		if (value === null || typeof value !== "object" || Array.isArray(value)) return refuse(`${typeName} value must be an object`);
+		const record = value;
+		const words = list.map((field) => {
+			if (!Object.prototype.hasOwnProperty.call(record, field.name)) return refuse(`${typeName} value is missing field "${field.name}"`);
+			return encodeValue(parseType(field.type), record[field.name], 0);
+		});
+		return (0, _noble_hashes_sha3.keccak_256)(concat([typeHash, ...words]));
+	}
+	return {
+		primaryType,
+		hashStruct
+	};
+}
+function hashDomain(domain) {
+	if (domain === null || typeof domain !== "object" || Array.isArray(domain)) return refuse("domain must be an object");
+	for (const key of Object.keys(domain)) if (!DOMAIN_FIELDS.some((field) => field.name === key)) return refuse(`invalid typed-data domain key ${JSON.stringify(key)}`);
+	return createStructEncoder({ EIP712Domain: DOMAIN_FIELDS.filter((field) => Object.prototype.hasOwnProperty.call(domain, field.name)) }).hashStruct("EIP712Domain", domain);
+}
+/**
+* The EIP-712 digest `keccak256(0x1901 || domainSeparator || hashStruct(primaryType, message))`
+* that a wallet signs for `eth_signTypedData_v4`. The primary type is inferred, as ethers does.
+*
+* @throws GSwapSDKError (`INVALID_TYPED_DATA`) for any type graph or value it cannot encode
+* exactly (see the module note on strictness).
+*/
+function hashTypedData(payload) {
+	const domainHash = hashDomain(payload.domain);
+	const encoder = createStructEncoder(payload.types);
+	const structHash = encoder.hashStruct(encoder.primaryType, payload.message);
+	return (0, _noble_hashes_sha3.keccak_256)(concat([
+		Uint8Array.of(25, 1),
+		domainHash,
+		structHash
+	]));
+}
+/**
+* Signs a dApp's EIP-712 typed-data approval (the wallet's `signTypedMessage` path), replacing
+* `new ethers.Wallet(key).signTypedData(domain, types, message)`. `types` must already have
+* `EIP712Domain` removed (`stripEip712DomainType`).
+*
+* @returns `0x` + r + s + v with `v` = `0x1b`/`0x1c` (27/28): ethers' serialized signature form,
+* recoverable with `verifyTypedData` / `eth_signTypedData_v4` verifiers. Rejects (never throws
+* synchronously) on invalid input.
+*/
+async function signTypedDataPayload(privateKey, payload) {
+	const digest = hashTypedData(payload);
+	return withPrivateKey(privateKey, (key) => `0x${signHash(key, digest)}`);
+}
+
+//#endregion
+//#region src/utils/axios_requestor.ts
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* An axios interceptor may resolve something that is not a response at all (for example a string
+* for ECONNREFUSED). That is a transport failure, not an HTTP answer.
+*/
+function isAxiosLikeResponse(value) {
+	return isRecord$1(value) && typeof value["status"] === "number";
+}
+function readAxiosHeader(headers, name) {
+	if (!isRecord$1(headers)) return null;
+	const getter = headers["get"];
+	if (typeof getter === "function") {
+		const value = getter.call(headers, name);
+		return typeof value === "string" ? value : null;
+	}
+	const match = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase());
+	return typeof (match === null || match === void 0 ? void 0 : match[1]) === "string" ? match[1] : null;
+}
+function toHttpResponse(answer, url) {
+	if (!isAxiosLikeResponse(answer)) throw new GSwapSDKError("The request failed before the server answered.", "TRANSPORT_ERROR", { url });
+	const { status, data, headers } = answer;
+	return {
+		ok: status >= 200 && status < 300,
+		status,
+		json: () => Promise.resolve(data),
+		text: () => Promise.resolve(typeof data === "string" ? data : JSON.stringify(data)),
+		headers: { get: (name) => readAxiosHeader(headers, name) }
+	};
+}
+function headersFor(init, omit) {
+	const omitted = new Set(omit.map((name) => name.toLowerCase()));
+	const raw = init === null || init === void 0 ? void 0 : init.headers;
+	const entries = raw === void 0 ? [] : raw instanceof Headers ? [...raw.entries()] : Array.isArray(raw) ? raw.map(([name, value]) => [String(name), String(value)]) : Object.entries(raw).map(([name, value]) => [name, String(value)]);
+	return Object.fromEntries(entries.filter(([name]) => !omitted.has(name.toLowerCase())));
+}
+/**
+* An SDK {@link HttpRequestor} over an axios instance, so the SDK's requests travel through the
+* app's own base URL, interceptors and error handling.
+*
+* A POST's string body is parsed back to the object the SDK serialized it from (axios serializes
+* again, and an interceptor may read the object); a GET goes through `instance.get`. The answer
+* is an HTTP response whose `json()`/`text()` read `response.data`. An answer that is not an
+* axios response is a `TRANSPORT_ERROR` rejection.
+*
+* Pair it with `ChainGateway`'s `dexBackendBaseUrl: ''` when the instance owns the base URL.
+*
+* @example
+* ```ts
+* const submitGateway = new ChainGateway({
+*   dexBackendBaseUrl: '',
+*   httpRequestor: httpRequestorFromAxios(chainGatewayInstance, { rejectOnHttpError: true }),
+* });
+* ```
+*/
+function httpRequestorFromAxios(instance, options) {
+	const omit = options.omitHeaders ?? ["content-type"];
+	return async (uri, init) => {
+		const signal = (init === null || init === void 0 ? void 0 : init.signal) ?? void 0;
+		const config = {
+			headers: headersFor(init, omit),
+			...signal ? { signal } : {},
+			...options.rejectOnHttpError ? {} : { validateStatus: () => true }
+		};
+		if (((init === null || init === void 0 ? void 0 : init.method) ?? "GET").toUpperCase() === "POST") {
+			const body = typeof (init === null || init === void 0 ? void 0 : init.body) === "string" ? JSON.parse(init.body) : void 0;
+			return toHttpResponse(await instance.post(uri, body, config), uri);
+		}
+		return toHttpResponse(await instance.get(uri, config), uri);
+	};
+}
+
+//#endregion
+//#region src/utils/ethers_provider.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTypedDataTypes(value) {
+	return isRecord(value) && Object.values(value).every((fields) => Array.isArray(fields) && fields.every((field) => isRecord(field) && typeof field["name"] === "string" && typeof field["type"] === "string"));
+}
+function malformed(method) {
+	return new GSwapSDKError(`Wallet ${method} request is malformed.`, "MALFORMED_WALLET_REQUEST", { method });
+}
+/** Splits `eth_signTypedData_v4` params (`[account, JSON payload]`) into what ethers' signer takes. */
+function readTypedDataRequest(params) {
+	const raw = params === null || params === void 0 ? void 0 : params[1];
+	let payload;
+	try {
+		payload = typeof raw === "string" ? JSON.parse(raw) : raw;
+	} catch {
+		throw malformed("eth_signTypedData_v4");
+	}
+	if (!isRecord(payload)) throw malformed("eth_signTypedData_v4");
+	const { domain, types, message } = payload;
+	if (!isRecord(domain) || !isTypedDataTypes(types) || !isRecord(message)) throw malformed("eth_signTypedData_v4");
+	return {
+		domain,
+		types: stripEip712DomainType(types),
+		message
+	};
+}
+/**
+* An EIP-1193 provider over an ethers v6 provider, for {@link BrowserWalletSigner}: apps whose
+* wallet connection is an ethers `BrowserProvider` sign through the very ethers calls they always
+* made, with no hand-written shim.
+*
+* - `eth_chainId` is `provider.send('eth_chainId', [])`: the wallet's LIVE chain. Never
+*   `provider.getNetwork()`, which ethers caches and does not invalidate on `chainChanged`, so a
+*   user who switches networks after connecting would sign against a stale chainId.
+* - `eth_signTypedData_v4` parses the `[account, JSON]` params and calls
+*   `signer.signTypedData(domain, types, message)` with `EIP712Domain` removed from `types`.
+* - `personal_sign` is `options.personalSign(message)` when given, else `signer.signMessage`.
+* - Anything else is `UNSUPPORTED_WALLET_METHOD`; a malformed request is
+*   `MALFORMED_WALLET_REQUEST`; a missing provider is `WALLET_UNAVAILABLE`.
+*
+* `provider` may be `null`/`undefined` (nothing connected): a request that needs it then fails
+* with `WALLET_UNAVAILABLE` rather than at construction, so a signer can be built before the
+* connection state is known.
+*
+* @example
+* ```ts
+* const signer = new BrowserWalletSigner(eip1193ProviderFromEthers(browserProvider), account, {
+*   scheme: 'eip712',
+* });
+* ```
+*/
+function eip1193ProviderFromEthers(provider, options = {}) {
+	const connected = () => {
+		if (provider === null || provider === void 0) throw new GSwapSDKError(options.unavailableMessage ?? "No wallet is connected.", "WALLET_UNAVAILABLE");
+		return provider;
+	};
+	return { request: async ({ method, params }) => {
+		switch (method) {
+			case "eth_chainId": return connected().send("eth_chainId", []);
+			case "eth_signTypedData_v4": {
+				const wallet = connected();
+				const { domain, types, message } = readTypedDataRequest(params);
+				return (await wallet.getSigner()).signTypedData(domain, types, message);
+			}
+			case "personal_sign": {
+				const message = params === null || params === void 0 ? void 0 : params[0];
+				if (typeof message !== "string") throw malformed("personal_sign");
+				if (options.personalSign !== void 0) return options.personalSign(message);
+				return (await connected().getSigner()).signMessage(message);
+			}
+			default: throw new GSwapSDKError(`Unsupported wallet method ${method}.`, "UNSUPPORTED_WALLET_METHOD", { method });
+		}
+	} };
+}
+
+//#endregion
+//#region src/utils/submit_state.ts
+/** The `mode` of `envelope.data`, or `undefined` when there is no such field. */
+function modeOf(envelope) {
+	const data = envelope["data"];
+	return typeof data === "object" && data !== null ? data["mode"] : void 0;
+}
+function recordOf(value) {
+	return typeof value === "object" && value !== null ? value : void 0;
+}
+/** True when the envelope is a definite failure: absent, or `error === true`. */
+function isSubmitRejected(envelope) {
+	var _recordOf;
+	if (!envelope) return true;
+	return ((_recordOf = recordOf(envelope)) === null || _recordOf === void 0 ? void 0 : _recordOf["error"]) === true;
+}
+/**
+* True when the envelope carries an executed result: `error === false` and `data.mode === 'sync'`.
+* A queued RequestTrade acknowledgement is deliberately NOT executed: its outcome is not known
+* until apply-results resolves.
+*/
+function isSubmitExecuted(envelope) {
+	const record = recordOf(envelope);
+	return (record === null || record === void 0 ? void 0 : record["error"]) === false && modeOf(record) === "sync";
+}
+/** True when the envelope acknowledges a `uniqueKey` as queued (`data.mode === 'queued'`). */
+function isSubmitQueued(envelope) {
+	var _recordOf2;
+	const record = recordOf(envelope);
+	if ((record === null || record === void 0 ? void 0 : record["error"]) !== false || modeOf(record) !== "queued") return false;
+	return typeof ((_recordOf2 = recordOf(record["data"])) === null || _recordOf2 === void 0 ? void 0 : _recordOf2["uniqueKey"]) === "string";
+}
+/** Classifies a raw gateway envelope; see {@link SubmitClassification}. */
+function classifySubmitEnvelope(envelope) {
+	if (isSubmitRejected(envelope)) return "rejected";
+	if (isSubmitExecuted(envelope)) return "executed";
+	if (isSubmitQueued(envelope)) return "queued";
+	return "unconfirmed";
+}
+
 //#endregion
 exports.ALL_FEE_TIERS = ALL_FEE_TIERS;
+exports.AppliedTradeError = AppliedTradeError;
 exports.Assets = Assets;
 exports.BrowserWalletSigner = BrowserWalletSigner;
+exports.CanonicalSymbols = CanonicalSymbols;
 exports.ChainGateway = ChainGateway;
+exports.DEFAULT_UNIQUE_KEY_PREFIX = DEFAULT_UNIQUE_KEY_PREFIX;
+exports.DEX_FEE_METHODS = DEX_FEE_METHODS;
+exports.DRY_RUN_METHOD = DRY_RUN_METHOD;
+exports.DRY_RUN_UNIQUE_KEY_PREFIX = DRY_RUN_UNIQUE_KEY_PREFIX;
+exports.DexFees = DexFees;
+exports.EIP712_CAPABLE_METHODS = EIP712_CAPABLE_METHODS;
 exports.FEE_TIER = FEE_TIER;
 exports.GC_MAX_TICK = GC_MAX_TICK;
 exports.GC_MIN_TICK = GC_MIN_TICK;
@@ -2872,6 +5485,9 @@ exports.GSwapSDKError = GSwapSDKError;
 exports.GalaWalletSigner = GalaWalletSigner;
 exports.GdexStreamError = GdexStreamError;
 exports.GdexStreamService = GdexStreamService;
+exports.PENDING_SWAPS_STORAGE_KEY = PENDING_SWAPS_STORAGE_KEY;
+exports.PENDING_SWAP_EXPIRY_MS = PENDING_SWAP_EXPIRY_MS;
+exports.PendingSwapStore = PendingSwapStore;
 exports.Pools = Pools;
 exports.Positions = Positions;
 exports.PrivateKeySigner = PrivateKeySigner;
@@ -2882,18 +5498,73 @@ exports.Symbols = Symbols;
 exports.TICK_SPACING_BY_FEE = TICK_SPACING_BY_FEE;
 exports.alignTickDown = alignTickDown;
 exports.alignTickUp = alignTickUp;
+exports.assertCanonicalPair = assertCanonicalPair;
+exports.assertCanonicalV2Dto = assertCanonicalV2Dto;
 exports.assertTickRange = assertTickRange;
+exports.assertUniqueKey = assertUniqueKey;
+exports.buildAddLiquidityDto = buildAddLiquidityDto;
+exports.buildCollectPositionFeesDto = buildCollectPositionFeesDto;
+exports.buildCreatePoolDto = buildCreatePoolDto;
+exports.buildDryRunWrapper = buildDryRunWrapper;
+exports.buildEIP712Payload = buildEIP712Payload;
+exports.buildRemoveLiquidityDto = buildRemoveLiquidityDto;
+exports.buildRequestTradeDto = buildRequestTradeDto;
+exports.calculatePersonalSignPrefix = calculatePersonalSignPrefix;
+exports.canonicalDecimalString = canonicalDecimalString;
+exports.classifyShadowSubmitError = classifyShadowSubmitError;
+exports.classifyShadowSubmitStatus = classifyShadowSubmitStatus;
+exports.classifySubmitEnvelope = classifySubmitEnvelope;
 exports.compositeKeyOf = compositeKeyOf;
+exports.confirmAppliedTrade = confirmAppliedTrade;
+exports.createLazyPrivateKeySigner = createLazyPrivateKeySigner;
+exports.createUniqueKey = createUniqueKey;
+exports.eip1193ProviderFromEthers = eip1193ProviderFromEthers;
+exports.eip712DomainFor = eip712DomainFor;
+exports.ethAddressOfPrivateKey = ethAddressOfPrivateKey;
+exports.ethereumAddressOfAccount = ethereumAddressOfAccount;
+exports.fixpointPrefixFor = fixpointPrefixFor;
+exports.frameSlot0 = frameSlot0;
+exports.generateEIP712Types = generateEIP712Types;
 exports.getObjectProperty = getObjectProperty;
+exports.getPayloadToSign = getPayloadToSign;
 exports.getStringProperty = getStringProperty;
+exports.hashTypedData = hashTypedData;
+exports.httpRequestorFromAxios = httpRequestorFromAxios;
+exports.isCurrentContractDexMessage = isCurrentContractDexMessage;
+exports.isDexFeeMethod = isDexFeeMethod;
 exports.isGdexLiquidityEvent = isGdexLiquidityEvent;
+exports.isProposableTradingSymbol = isProposableTradingSymbol;
+exports.isSubmitExecuted = isSubmitExecuted;
+exports.isSubmitQueued = isSubmitQueued;
+exports.isSubmitRejected = isSubmitRejected;
+exports.normalizePrivateKey = normalizePrivateKey;
 exports.orderSymbols = orderSymbols;
 exports.parseJson = parseJson;
 exports.parseTokenClassKey = parseTokenClassKey;
+exports.personalSignPrefixFor = personalSignPrefixFor;
+exports.queryTokenOf = queryTokenOf;
+exports.rawTokenOf = rawTokenOf;
 exports.readOrderedSymbols = readOrderedSymbols;
+exports.readShadowSubmitOutcome = readShadowSubmitOutcome;
+exports.resolvePersonalSignChainDtoPayload = resolvePersonalSignChainDtoPayload;
+exports.resolveUniqueKeyPrefix = resolveUniqueKeyPrefix;
+exports.serialize = serialize;
+exports.signChainDtoHash = signChainDtoHash;
+exports.signChainDtoNative = signChainDtoNative;
+exports.signChainDtoPersonalSign = signChainDtoPersonalSign;
+exports.signNative = signNative;
+exports.signPersonalMessage = signPersonalMessage;
+exports.signRawObject = signRawObject;
+exports.signSerializedNative = signSerializedNative;
+exports.signTypedDataPayload = signTypedDataPayload;
 exports.sqrtPriceToTick = sqrtPriceToTick;
+exports.stripEip712DomainType = stripEip712DomainType;
+exports.swapRouteFromQuote = swapRouteFromQuote;
 exports.tickFromPrice = tickFromPrice;
 exports.tickToSqrtPrice = tickToSqrtPrice;
+exports.toChainDto = toChainDto;
+exports.tokenClassDollarKey = tokenClassDollarKey;
+exports.tradingSymbolOf = tradingSymbolOf;
 exports.validateFee = validateFee;
 exports.validateNumericAmount = validateNumericAmount;
 exports.validatePriceValues = validatePriceValues;
@@ -2901,4 +5572,5 @@ exports.validateTickRange = validateTickRange;
 exports.validateTickSpacing = validateTickSpacing;
 exports.validateTokenDecimals = validateTokenDecimals;
 exports.validateWalletAddress = validateWalletAddress;
+exports.withPrivateKey = withPrivateKey;
 //# sourceMappingURL=index.cjs.map