@gala-chain/gswap-sdk 1.2.0-rc.8 → 1.2.0

package/dist/index.cjs

@@ -1345,6 +1345,7 @@ var GSwapSDKError = class GSwapSDKError extends Error {
 	code;
 	/** The named placeholders of the error: a flat object of primitives, safe to localize with. */
 	params;
+	/** The server's `Retry-After` in milliseconds (a `RATE_LIMITED` answer), when it sent one. */
 	retryAfterMs;
 	/** The HTTP status of the response that caused this error, when there was one. */
 	status;
@@ -1670,7 +1671,7 @@ 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.8";
+const SDK_VERSION = "1.2.0";
 
 //#endregion
 //#region src/utils/transport.ts
@@ -1731,7 +1732,7 @@ function buildRequestHeaders(wire, parts = {}) {
 			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.8"}` });
+	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"}` });
 	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" });
@@ -2035,7 +2036,54 @@ const ALL_FEE_TIERS = [
 ];
 
 //#endregion
-//#region src/utils/ticks.ts
+//#region src/utils/tick_range.ts
+function integerTickOf(tick) {
+	if (typeof tick === "string") return tick.trim() === "" ? NaN : Number(tick);
+	return tick;
+}
+/**
+* True when a position over `[tickLower, tickUpper)` is IN RANGE at `currentTick`: the lower tick
+* is INCLUSIVE and the upper tick is EXCLUSIVE. That is the GalaChainDex contract's rule
+* (`DexV3Pool`: `tickCurrent >= tickLower && tickCurrent < tickUpper` is the case in which a
+* position holds both tokens and earns fees). A pool whose tick equals `tickUpper` is already out
+* of range: the position is entirely token1 there, and a swap through the tick has crossed it.
+*
+* `currentTick` is the pool's tick (`slot0.tick`, the greatest tick whose price is no greater than
+* the pool's price), not a rounded display value. A tick may be a number or the decimal string a
+* backend returns. Anything that is not an integer (`NaN`, `undefined`-like, an empty string, a
+* fraction) makes the answer `false`: an app that must tell "not loaded yet" from "out of range"
+* checks for the missing value itself first.
+*
+* Do NOT decide range by comparing a price with a tick's price (`tickToPrice`) using `<=` on both
+* ends, or by mixing a square-root price with a price. A price exactly on a tick's boundary is
+* then in range at the upper edge (the contract says it is not), and two representations of the
+* same boundary can round to opposite sides. For a pool price use {@link isSqrtPriceInRange}, which
+* derives the tick the way the contract does and then applies this rule.
+*
+* @example
+* ```ts
+* isTickInRange(-60, -60, 60); // true: the lower tick is inclusive
+* isTickInRange(60, -60, 60); // false: the upper tick is exclusive
+* ```
+*/
+function isTickInRange(currentTick, tickLower, tickUpper) {
+	const current = integerTickOf(currentTick);
+	const lower = integerTickOf(tickLower);
+	const upper = integerTickOf(tickUpper);
+	if (!Number.isInteger(current) || !Number.isInteger(lower) || !Number.isInteger(upper)) return false;
+	return current >= lower && current < upper;
+}
+
+//#endregion
+//#region src/utils/tick_math.ts
+/**
+* Tick and price arithmetic that never throws an SDK error: the contract's tick bounds, the
+* conversions between ticks and prices, and nothing that validates a range. It imports only the
+* two number libraries it computes with, never the `GSwapSDKError` class or the error catalog
+* (functions that must throw, `alignTickDown` and `assertTickRange`, are in `ticks.ts`), so an
+* app shell that prices a tick pays for the libraries and these few functions, not for ~25 kB of
+* error templates. A value that cannot be computed is `NaN`, never an exception.
+*/
 /** Minimum tick supported by GalaChainDex. */
 const GC_MIN_TICK = -887272;
 /** Maximum tick supported by GalaChainDex. */
@@ -2044,6 +2092,7 @@ const DexMath = bignumber_js.default.clone({
 	DECIMAL_PLACES: 60,
 	ROUNDING_MODE: bignumber_js.default.ROUND_DOWN
 });
+/** `decimal.js` at the 60 significant digits the contract's price math is exact to. */
 const DexDecimal = decimal_js.Decimal.clone({ precision: 60 });
 /** Convert a tick to the corresponding square-root price. */
 function tickToSqrtPrice(tick) {
@@ -2078,6 +2127,26 @@ function tickToPrice(tick) {
 	return new bignumber_js.default(new DexDecimal(1.0001).pow(tick).toString());
 }
 /**
+* {@link isTickInRange} for a pool's square-root price instead of its tick (a position row that
+* carries `sqrtPrice`, `tickLower` and `tickUpper`). The tick is derived from the price exactly as
+* the contract does (`sqrtPriceToTick`: the greatest tick whose square-root price is no greater
+* than the price, exact to 60 digits), then the contract's rule applies: lower tick inclusive,
+* upper tick exclusive. So a pool sitting exactly on `tickLower`'s price is in range, and exactly
+* on `tickUpper`'s price is not, and no float rounding can flip either.
+*
+* `false` for a price that is not positive and finite (not loaded, zero, `NaN`): it says nothing
+* about the position, so an app that must show a neutral state checks for the missing price
+* itself first. `tickLower` and `tickUpper` follow {@link isTickInRange}.
+*
+* @example
+* ```ts
+* const inRange = isSqrtPriceInRange(position.sqrtPrice, position.tickLower, position.tickUpper);
+* ```
+*/
+function isSqrtPriceInRange(sqrtPrice, tickLower, tickUpper) {
+	return isTickInRange(sqrtPriceToTick(sqrtPrice), tickLower, tickUpper);
+}
+/**
 * Return the integer tick for a token1/token0 `price`: by default the greatest tick whose price
 * is no greater than `price`; `{ rounding: 'nearest' }` the closest tick. `NaN` for a price that
 * is not positive and finite.
@@ -2091,77 +2160,18 @@ function tickFromPrice(price, options = {}) {
 	const tick = (options.rounding === "nearest" ? exact.round() : exact.floor()).toNumber();
 	return Number.isFinite(tick) ? tick : NaN;
 }
-/** Align a tick down to the nearest multiple of a positive spacing. */
-function alignTickDown(tick, spacing) {
-	assertSpacing(spacing);
-	return Math.floor(tick / spacing) * spacing;
-}
-/** Align a tick up to the nearest multiple of a positive spacing. */
-function alignTickUp(tick, spacing) {
-	assertSpacing(spacing);
-	return Math.ceil(tick / spacing) * spacing;
-}
-/** Validate a position range against the global tick bounds and fee-tier spacing. */
-function assertTickRange(lower, upper, fee) {
-	const spacing = TICK_SPACING_BY_FEE[fee];
-	if (spacing === void 0) throw new GSwapSDKError("INVALID_FEE", {
-		field: "fee",
-		value: fee,
-		allowed: ALLOWED_FEE_TIERS_TEXT
-	});
-	if (!Number.isInteger(lower) || !Number.isInteger(upper)) throw new GSwapSDKError("TICKS_NOT_INTEGERS", {
-		tickLower: lower,
-		tickUpper: upper
-	});
-	if (lower >= upper) throw new GSwapSDKError("INVALID_TICK_RANGE", {
-		tickLower: lower,
-		tickUpper: upper
-	});
-	if (lower < -887272 || upper > 887272) throw new GSwapSDKError("TICKS_OUT_OF_BOUNDS", {
-		tickLower: lower,
-		tickUpper: upper,
-		minTick: GC_MIN_TICK,
-		maxTick: GC_MAX_TICK
-	});
-	if (lower % spacing !== 0 || upper % spacing !== 0) throw new GSwapSDKError("TICKS_NOT_ALIGNED", {
-		tickLower: lower,
-		tickUpper: upper,
-		spacing
-	});
-}
-function assertSpacing(spacing) {
-	if (!Number.isInteger(spacing) || spacing <= 0) throw new GSwapSDKError("INVALID_TICK_SPACING", { value: spacing });
-}
-/**
-* 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("INVALID_SQRT_PRICE", { sqrtPrice: slot0.sqrtPrice });
-	const sqrtPrice = inverted.toString();
-	return {
-		sqrtPrice,
-		tick: sqrtPriceToTick(sqrtPrice)
-	};
-}
 
 //#endregion
 //#region src/utils/validation.ts
+/**
+* Validates a decimal amount: a string or `BigNumber`, never a JavaScript number.
+*
+* @param amount - The amount to check.
+* @param parameterName - The field name reported in the error's `params.field`.
+* @param allowZero - Accept zero (default `false`).
+* @throws GSwapSDKError `AMOUNT_IS_JS_NUMBER`, `AMOUNT_NOT_FINITE`, `AMOUNT_NOT_POSITIVE` (zero
+* when `allowZero` is false) or `AMOUNT_NEGATIVE`.
+*/
 function validateNumericAmount(amount, parameterName, allowZero = false) {
 	if (typeof amount === "number") throw new GSwapSDKError("AMOUNT_IS_JS_NUMBER", { field: parameterName });
 	let bnAmount;
@@ -2183,6 +2193,12 @@ function validateNumericAmount(amount, parameterName, allowZero = false) {
 		value: String(amount)
 	});
 }
+/**
+* Validates a spot price and a lower/upper price range: none a JavaScript number, all positive and
+* finite (a non-finite upper bound counts as an unbounded `1e18`), and `lowerPrice <= upperPrice`.
+*
+* @throws GSwapSDKError `PRICE_VALUES_IS_JS_NUMBER`, `INVALID_PRICE_VALUES` or `INVALID_PRICE_RANGE`.
+*/
 function validatePriceValues(spotPrice, lowerPrice, upperPrice) {
 	if ([
 		spotPrice,
@@ -2210,12 +2226,24 @@ function validatePriceValues(spotPrice, lowerPrice, upperPrice) {
 		upperPrice: String(upperPrice)
 	});
 }
+/**
+* Validates a token's decimals: a non-negative integer.
+*
+* @throws GSwapSDKError `INVALID_TOKEN_DECIMALS` (`params.field` is `parameterName`).
+*/
 function validateTokenDecimals(decimals, parameterName) {
 	if (decimals < 0 || !Number.isInteger(decimals)) throw new GSwapSDKError("INVALID_TOKEN_DECIMALS", {
 		field: parameterName,
 		value: decimals
 	});
 }
+/**
+* Validates a position's tick range: two integers with `tickLower < tickUpper`, both within
+* `GC_MIN_TICK`..`GC_MAX_TICK`. It does not check alignment to a fee tier's spacing (see
+* `assertTickRange`).
+*
+* @throws GSwapSDKError `TICKS_NOT_INTEGERS`, `INVALID_TICK_RANGE` or `TICKS_OUT_OF_BOUNDS`.
+*/
 function validateTickRange(tickLower, tickUpper) {
 	if (!Number.isInteger(tickLower) || !Number.isInteger(tickUpper)) throw new GSwapSDKError("TICKS_NOT_INTEGERS", {
 		tickLower,
@@ -2232,6 +2260,11 @@ function validateTickRange(tickLower, tickUpper) {
 		maxTick: GC_MAX_TICK
 	});
 }
+/**
+* Asserts that `fee` is one of the fee tiers in `ALL_FEE_TIERS` (`0`, `500`, `3000`, `10000`).
+*
+* @throws GSwapSDKError `INVALID_FEE` (`params.field` `'fee'`, `params.allowed` the tiers).
+*/
 function validateFee(fee) {
 	if (!ALL_FEE_TIERS.some((tier) => Number(tier) === fee)) throw new GSwapSDKError("INVALID_FEE", {
 		field: "fee",
@@ -2239,9 +2272,20 @@ function validateFee(fee) {
 		allowed: ALLOWED_FEE_TIERS_TEXT
 	});
 }
+/**
+* Validates a tick spacing: a positive integer.
+*
+* @throws GSwapSDKError `INVALID_TICK_SPACING`.
+*/
 function validateTickSpacing(tickSpacing) {
 	if (!Number.isInteger(tickSpacing) || tickSpacing <= 0) throw new GSwapSDKError("INVALID_TICK_SPACING", { value: tickSpacing });
 }
+/**
+* Asserts that a wallet address was given and is a non-blank string. It does not check the address
+* format.
+*
+* @throws GSwapSDKError `MISSING_WALLET_ADDRESS` (undefined) or `INVALID_WALLET_ADDRESS` (blank).
+*/
 function validateWalletAddress(address) {
 	if (address === void 0) throw new GSwapSDKError("MISSING_WALLET_ADDRESS", {});
 	if (!address || typeof address !== "string" || address.trim().length === 0) throw new GSwapSDKError("INVALID_WALLET_ADDRESS", {
@@ -2724,9 +2768,13 @@ async function shadowFailures(run) {
 //#region src/classes/submitted_transaction.ts
 /** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
 var SubmittedTransaction = class {
+	/** The chain method that was submitted (`RequestTrade`, `AddLiquidity`, ...). */
 	method;
+	/** The write's durable correlation key: persist it, and confirm from it alone later. */
 	uniqueKey;
+	/** The request transaction id the gateway reported, or `null` when it gave none. */
 	transactionId;
+	/** The block of the transaction, when the answer carried one; otherwise `null`. */
 	blockNumber;
 	/** The gateway's `data.mode`: `'sync'` (executed, `result` is the chain result) or `'queued'`. */
 	mode;
@@ -2848,7 +2896,9 @@ var ChainGateway = class {
 	chainCallTimeoutMs;
 	isTransportFailure;
 	answerOfRejectionHook;
+	/** The request timeout in milliseconds (`Infinity` when no timer is armed). */
 	requestTimeoutMs;
+	/** The swap backend base URL every request is sent to, without a trailing slash. */
 	dexBackendBaseUrl;
 	/** Wire format shared by the read services built on this gateway. */
 	wire;
@@ -2922,7 +2972,7 @@ var ChainGateway = class {
 	*
 	* 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`);
+	* (`SHADOW_UNAVAILABLE`, `SHADOW_UNSUPPORTED_TYPE`, `SHADOW_RELAY_REJECTED`);
 	* see `readShadowSubmitOutcome`. Only a failure to get an answer rejects, and it rejects with
 	* `SUBMISSION_OUTCOME_UNKNOWN` (`params.reason` `'timeout'` or `'transport'`): the request may
 	* have been accepted. Every error it throws has `error.shadow === true`, and a non-SDK object
@@ -3170,7 +3220,9 @@ function isGdexLiquidityEvent(value) {
 }
 /** A JSON-RPC error answered by the stream. */
 var GdexStreamError = class extends Error {
+	/** The JSON-RPC error code. */
 	code;
+	/** The error's optional `data` member, as the server sent it. */
 	data;
 	constructor(code, message, data) {
 		super(message);
@@ -3248,6 +3300,7 @@ var GdexStreamService = class {
 		this.connectPromise = void 0;
 		socket === null || socket === void 0 || socket.close(1e3, "client disconnect");
 	}
+	/** `true` while the socket is open (false while connecting, reconnecting or after `disconnect()`). */
 	isConnected() {
 		var _this$socket;
 		return ((_this$socket = this.socket) === null || _this$socket === void 0 ? void 0 : _this$socket.readyState) === WEBSOCKET_OPEN;
@@ -3289,30 +3342,41 @@ var GdexStreamService = class {
 			}
 		});
 	}
+	/** `gdex_serverInfo`: the server's own description of itself, as it sends it. */
 	serverInfo() {
 		return this.request("gdex_serverInfo");
 	}
+	/** `gdex_ping`: a round trip that answers `{ pong, serverTime }`. */
 	ping() {
 		return this.request("gdex_ping");
 	}
+	/** `gdex_getPool`: the current state of one pool, selected by its key or hash. */
 	getPool(selector) {
 		return this.request("gdex_getPool", selector);
 	}
+	/** `gdex_getBalance`: an owner's balances, or only the one of `tokenClassKey` when given. */
 	getBalance(owner, tokenClassKey) {
 		return this.request("gdex_getBalance", tokenClassKey === void 0 ? { owner } : {
 			owner,
 			tokenClassKey
 		});
 	}
+	/**
+	* `gdex_getPositions`: an owner's positions, optionally in one pool, a page at a time. Pass the
+	* returned `bookmark` back in as `bookmark` for the next page.
+	*/
 	getPositions(opts) {
 		return this.request("gdex_getPositions", opts);
 	}
+	/** `gdex_getBlockHeight`: the block number the server reports, with its timestamp. */
 	getBlockHeight() {
 		return this.request("gdex_getBlockHeight");
 	}
+	/** `gdex_quote`: a quote over the stream; give exactly one of `amountIn` or `amountOut`. */
 	quote(params) {
 		return this.request("gdex_quote", params);
 	}
+	/** `gdex_getToken`: the server's record of one token class, as it sends it. */
 	getToken(tokenClassKey) {
 		return this.request("gdex_getToken", { tokenClassKey });
 	}
@@ -3645,39 +3709,13 @@ function finiteNumberOf(value) {
 }
 
 //#endregion
-//#region src/utils/ordering.ts
-/** Return two trading symbols in the contract's plain-string order. */
-function orderSymbols(a, b) {
-	return a < b ? [a, b] : [b, a];
-}
-/** Read an ordered symbol pair from a tuple or object returned by a boundary helper.
-*
-* @example
-* ```ts
-* const pair = readOrderedSymbols(['GALA', 'GUSDC']);
-* console.log(pair.token0);
-* ```
+//#region src/utils/class_key.ts
+/**
+* Token class keys that never throw: the `$`-joined composite key and the non-throwing parsers.
+* This module imports nothing at run time (the key type is erased), so an app shell that reads a
+* stored key pays for a few hundred bytes, never for the error class or the catalog. The parser
+* that THROWS an SDK error on a bad key (`parseTokenClassKey`) lives in `ordering.ts`.
 */
-function readOrderedSymbols(value) {
-	if (Array.isArray(value) && value.length >= 2) {
-		const token0 = value[0];
-		const token1 = value[1];
-		if (typeof token0 === "string" && typeof token1 === "string") return {
-			token0,
-			token1
-		};
-	}
-	if (typeof value === "object" && value !== null) {
-		const record = value;
-		const token0 = record["token0"];
-		const token1 = record["token1"];
-		if (typeof token0 === "string" && typeof token1 === "string") return {
-			token0,
-			token1
-		};
-	}
-	throw new GSwapSDKError("UNORDERABLE_SYMBOLS", { received: Array.isArray(value) ? "array" : value === null ? "null" : typeof value });
-}
 /** Return the `$`-joined composite key used by GalaChain object identities. */
 function compositeKeyOf(token) {
 	return [
@@ -3688,33 +3726,14 @@ function compositeKeyOf(token) {
 	].join("$");
 }
 /**
-* Parse a pipe- or dollar-separated token class key.
+* Splits `collection<d>category<d>type<d>additionalKey` from the right, or `undefined` when there
+* are fewer than four segments or any of the four is empty. The one place the split is written;
+* the strict `parseTokenClassKey` calls it too.
 *
 * The LAST three segments are always `category`, `type` and `additionalKey`; everything before
 * them is the `collection`. Parsing from the right is required because real collections contain
 * the `$` delimiter themselves (for example `$GMUSIC`), so a plain left-to-right `split('$')`
-* shifts every field. Nothing here says anything about the token's symbol: a class key carries
-* no symbol, which must come from the token class or trading-symbol registry.
-*
-* @example
-* ```ts
-* parseTokenClassKey('$GMUSIC$Unit$none$none').collection; // '$GMUSIC'
-* ```
-*/
-function parseTokenClassKey(tokenClassKey) {
-	if (typeof tokenClassKey === "object") return {
-		collection: tokenClassKey.collection,
-		category: tokenClassKey.category,
-		type: tokenClassKey.type,
-		additionalKey: tokenClassKey.additionalKey
-	};
-	const parsed = splitClassKey(tokenClassKey, tokenClassKey.includes("|") ? "|" : "$");
-	if (parsed === void 0) throw new GSwapSDKError("INVALID_TOKEN_CLASS_KEY", { tokenClassKey });
-	return parsed;
-}
-/**
-* Splits `collection<d>category<d>type<d>additionalKey` from the right, or `undefined` when there
-* are fewer than four segments or any of the four is empty. The one place the split is written.
+* shifts every field.
 */
 function splitClassKey(key, delimiter) {
 	const segments = key.split(delimiter);
@@ -3730,7 +3749,7 @@ function splitClassKey(key, delimiter) {
 	};
 }
 /**
-* The non-throwing {@link parseTokenClassKey}: the class key, or `undefined` when `value` is not
+* The non-throwing `parseTokenClassKey`: the class key, or `undefined` when `value` is not
 * one. A string is split exactly as `parseTokenClassKey` splits it (`|` form when it contains a
 * `|`, else `$`, from the right, all four parts non-empty). Unlike `parseTokenClassKey`, an
 * object is VALIDATED, not just copied: all four fields must be non-empty strings. Anything else
@@ -3783,6 +3802,66 @@ function tryParseCompositeKey(value) {
 	return typeof value === "string" ? splitClassKey(value, "$") : void 0;
 }
 
+//#endregion
+//#region src/utils/ordering.ts
+/** Return two trading symbols in the contract's plain-string order. */
+function orderSymbols(a, b) {
+	return a < b ? [a, b] : [b, a];
+}
+/** Read an ordered symbol pair from a tuple or object returned by a boundary helper.
+*
+* @example
+* ```ts
+* const pair = readOrderedSymbols(['GALA', 'GUSDC']);
+* console.log(pair.token0);
+* ```
+*/
+function readOrderedSymbols(value) {
+	if (Array.isArray(value) && value.length >= 2) {
+		const token0 = value[0];
+		const token1 = value[1];
+		if (typeof token0 === "string" && typeof token1 === "string") return {
+			token0,
+			token1
+		};
+	}
+	if (typeof value === "object" && value !== null) {
+		const record = value;
+		const token0 = record["token0"];
+		const token1 = record["token1"];
+		if (typeof token0 === "string" && typeof token1 === "string") return {
+			token0,
+			token1
+		};
+	}
+	throw new GSwapSDKError("UNORDERABLE_SYMBOLS", { received: Array.isArray(value) ? "array" : value === null ? "null" : typeof value });
+}
+/**
+* Parse a pipe- or dollar-separated token class key.
+*
+* The LAST three segments are always `category`, `type` and `additionalKey`; everything before
+* them is the `collection`. Parsing from the right is required because real collections contain
+* the `$` delimiter themselves (for example `$GMUSIC`), so a plain left-to-right `split('$')`
+* shifts every field. Nothing here says anything about the token's symbol: a class key carries
+* no symbol, which must come from the token class or trading-symbol registry.
+*
+* @example
+* ```ts
+* parseTokenClassKey('$GMUSIC$Unit$none$none').collection; // '$GMUSIC'
+* ```
+*/
+function parseTokenClassKey(tokenClassKey) {
+	if (typeof tokenClassKey === "object") return {
+		collection: tokenClassKey.collection,
+		category: tokenClassKey.category,
+		type: tokenClassKey.type,
+		additionalKey: tokenClassKey.additionalKey
+	};
+	const parsed = splitClassKey(tokenClassKey, tokenClassKey.includes("|") ? "|" : "$");
+	if (parsed === void 0) throw new GSwapSDKError("INVALID_TOKEN_CLASS_KEY", { tokenClassKey });
+	return parsed;
+}
+
 //#endregion
 //#region src/classes/symbols.ts
 const SYMBOL_CACHE_TTL_MS = 6e4;
@@ -4201,37 +4280,151 @@ function parsePoolListInfo(entry) {
 }
 
 //#endregion
-//#region src/utils/unique_key.ts
+//#region src/utils/tick_align.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.
+* Aligning a tick to a pool's tick spacing without throwing. This module imports nothing, so an
+* app shell (a price input that snaps to a tick) pays for a few dozen bytes, not for the error
+* class and catalog that `alignTickDown` and `alignTickUp` (in `ticks.ts`) carry because they
+* throw `INVALID_TICK_SPACING` for a spacing that is not a positive integer.
 */
-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;
+/** True for a tick spacing the contract can use: a positive integer. The one definition. */
+function hasValidSpacing(spacing) {
+	return Number.isInteger(spacing) && spacing > 0;
+}
 /**
-* 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.
+* {@link alignTickDown} that answers `NaN` instead of throwing: the greatest multiple of `spacing`
+* that is no greater than `tick`, or `NaN` when `spacing` is not a positive integer (a pool whose
+* spacing has not loaded yet) or `tick` is not a number. For an app shell and for a drag handler,
+* which must not throw while the spacing is missing. `alignTickDown` (the SDK's own call sites use
+* it) gives the same value and throws for the bad spacing.
 *
-* @throws GSwapSDKError `INVALID_UNIQUE_KEY_PREFIX` when the prefix has characters outside
-* `A-Za-z0-9._:-` or is longer than 92 characters.
+* @example
+* ```ts
+* alignTickDownOrNaN(-61, 60); // -120: it floors, it does not truncate toward zero
+* alignTickDownOrNaN(100, 0); // NaN
+* ```
 */
-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("INVALID_UNIQUE_KEY_PREFIX", {
-		uniqueKeyPrefix: prefix,
-		maxLength: MAX_UNIQUE_KEY_PREFIX_LENGTH
-	});
-	return prefix;
+function alignTickDownOrNaN(tick, spacing) {
+	return hasValidSpacing(spacing) ? Math.floor(tick / spacing) * spacing : NaN;
 }
 /**
-* 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.
+* {@link alignTickUp} that answers `NaN` instead of throwing: the least multiple of `spacing` that
+* is no less than `tick`, or `NaN` for a spacing that is not a positive integer. See
+* {@link alignTickDownOrNaN}.
+*/
+function alignTickUpOrNaN(tick, spacing) {
+	return hasValidSpacing(spacing) ? Math.ceil(tick / spacing) * spacing : NaN;
+}
+
+//#endregion
+//#region src/utils/ticks.ts
+/**
+* The tick functions that THROW an SDK error on a bad input (`alignTickDown`, `alignTickUp`,
+* `assertTickRange`, `frameSlot0`). The arithmetic that never throws (`tickToPrice`,
+* `tickFromPrice`, `tickToSqrtPrice`, `sqrtPriceToTick`, the bounds) is in `tick_math.ts`, which
+* does not import the error class or the catalog; import it from the package entry as usual.
+*/
+/** Align a tick down to the nearest multiple of a positive spacing. */
+function alignTickDown(tick, spacing) {
+	assertSpacing(spacing);
+	return alignTickDownOrNaN(tick, spacing);
+}
+/** Align a tick up to the nearest multiple of a positive spacing. */
+function alignTickUp(tick, spacing) {
+	assertSpacing(spacing);
+	return alignTickUpOrNaN(tick, spacing);
+}
+/** Validate a position range against the global tick bounds and fee-tier spacing. */
+function assertTickRange(lower, upper, fee) {
+	const spacing = TICK_SPACING_BY_FEE[fee];
+	if (spacing === void 0) throw new GSwapSDKError("INVALID_FEE", {
+		field: "fee",
+		value: fee,
+		allowed: ALLOWED_FEE_TIERS_TEXT
+	});
+	if (!Number.isInteger(lower) || !Number.isInteger(upper)) throw new GSwapSDKError("TICKS_NOT_INTEGERS", {
+		tickLower: lower,
+		tickUpper: upper
+	});
+	if (lower >= upper) throw new GSwapSDKError("INVALID_TICK_RANGE", {
+		tickLower: lower,
+		tickUpper: upper
+	});
+	if (lower < -887272 || upper > 887272) throw new GSwapSDKError("TICKS_OUT_OF_BOUNDS", {
+		tickLower: lower,
+		tickUpper: upper,
+		minTick: GC_MIN_TICK,
+		maxTick: GC_MAX_TICK
+	});
+	if (lower % spacing !== 0 || upper % spacing !== 0) throw new GSwapSDKError("TICKS_NOT_ALIGNED", {
+		tickLower: lower,
+		tickUpper: upper,
+		spacing
+	});
+}
+function assertSpacing(spacing) {
+	if (!hasValidSpacing(spacing)) throw new GSwapSDKError("INVALID_TICK_SPACING", { value: spacing });
+}
+/**
+* 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("INVALID_SQRT_PRICE", { sqrtPrice: slot0.sqrtPrice });
+	const sqrtPrice = inverted.toString();
+	return {
+		sqrtPrice,
+		tick: sqrtPriceToTick(sqrtPrice)
+	};
+}
+
+//#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 `INVALID_UNIQUE_KEY_PREFIX` 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("INVALID_UNIQUE_KEY_PREFIX", {
+		uniqueKeyPrefix: prefix,
+		maxLength: MAX_UNIQUE_KEY_PREFIX_LENGTH
+	});
+	return prefix;
+}
+/**
+* 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 `INVALID_UNIQUE_KEY` otherwise.
 */
@@ -4249,8 +4442,9 @@ 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`.
+* side's slippage bound and an optional `priceLimit`. Key order is
+* `token0, token1, fee, uniqueKey`, then the one quantity, then the slippage bound, then
+* `priceLimit`.
 *
 * @example
 * ```ts
@@ -5438,21 +5632,21 @@ function toDecimalString(amount) {
 *
 * - `SHADOW_UNAVAILABLE` (503): marking failed or infra not configured; retryable. Never fall back
 *   silently to a public swap.
-* - `SHADOW_DISABLED` (400): the feature is off for this environment.
 * - `SHADOW_UNSUPPORTED_TYPE` (400): shadow requested on a non-swap method.
 * - `SHADOW_RELAY_REJECTED`: terminal business rejection (slippage, balance, ...), not retryable;
 *   `message` is the gateway's verbatim string.
 */
 const SHADOW_SUBMIT_CODES = [
 	"SHADOW_UNAVAILABLE",
-	"SHADOW_DISABLED",
 	"SHADOW_UNSUPPORTED_TYPE",
 	"SHADOW_RELAY_REJECTED"
 ];
 /**
 * Every `kind` of a failed {@link ShadowSubmitOutcome}, for an app that maps each to its own text
-* (`Record<ShadowFailureKind, string>`): `unavailable` (retryable), `disabled`, `rejected` (carries
-* the gateway's `message`) and `unknown`.
+* (`Record<ShadowFailureKind, string>`): `unavailable` (retryable), `disabled` (the shadow route
+* answered 400: the request is not a dark-swappable one, e.g. `SHADOW_UNSUPPORTED_TYPE`; Shadow
+* Swaps themselves are enabled in every environment), `rejected` (carries the gateway's `message`)
+* and `unknown`.
 */
 const SHADOW_FAILURE_KINDS = [
 	"unavailable",
@@ -5469,12 +5663,12 @@ function classifyShadowSubmitStatus(status) {
 /**
 * 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".
+* rejection; `SHADOW_UNSUPPORTED_TYPE` and any other 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";
+	if (code === "SHADOW_UNSUPPORTED_TYPE") return "disabled";
 	return classifyShadowSubmitStatus(status);
 }
 function readShadowSubmitOutcome(method, signedBody, result) {
@@ -5716,27 +5910,43 @@ var Swaps = class {
 
 //#endregion
 //#region src/classes/gswap.ts
-/** Main entry point for the current GalaChainDex SDK. */
+/**
+* Main entry point for the current GalaChainDex SDK: one client bundling the services that read
+* and write through the swap backend (`quoting`, `swaps`, `pools`, `positions`, `assets`,
+* `symbols`, `fees`, `stream`). See {@link GSwapOptions} for configuration.
+*/
 var GSwap = class {
+	/** The swap backend base URL every request goes to, without a trailing slash. */
 	dexBackendBaseUrl;
+	/** The request timeout in milliseconds (default 30 000; `Infinity` arms no timer). */
 	chainCallTimeoutMs;
+	/** The signer given at construction, if any. */
 	signer;
+	/** The account given at construction, if any. */
 	walletAddress;
+	/** The chain-gateway client every other service reads and writes through. */
 	gateway;
+	/** The trading-symbol registry. */
 	symbols;
+	/** Read-only exact-input and exact-output quotes. */
 	quoting;
+	/** Pool, slot0 and composite-pool reads. */
 	pools;
+	/** Position reads, liquidity estimates and liquidity / pool-creation writes. */
 	positions;
+	/** Queued swaps (`RequestTrade`), dark swaps and swap confirmation. */
 	swaps;
+	/** User token balances. */
 	assets;
 	/** Network-fee quotes (DryRun) signed with this client's signer. */
 	fees;
+	/** The realtime stream endpoint {@link GSwap.stream} connects to. */
 	dexBackendWsUrl;
 	webSocketImpl;
 	streamApiKey;
 	streamClient;
 	/**
-	* Create an SDK client for prod or stage.
+	* Create an SDK client for prod (the default) or stage, or for a `dexBackendBaseUrl` of your own.
 	*
 	* @example
 	* ```typescript
@@ -5800,10 +6010,10 @@ function trimTrailingSlash(value) {
 }
 
 //#endregion
-//#region src/utils/failure_classification.ts
+//#region src/utils/classification.ts
 /**
 * The SDK's default Retry answer for each outcome. A decision that departs from it (a refusal the
-* gateway will repeat, `SHADOW_NOT_QUEUED`) is written out in the table below.
+* gateway will repeat, `SHADOW_NOT_QUEUED`) is written out in the table of `classifyFailure`.
 */
 const DEFAULT_RETRYABLE = {
 	rejected: true,
@@ -5821,10 +6031,10 @@ const DEFAULT_RETRYABLE = {
 * object, safe to mutate or freeze.
 *
 * `options.retryable: false` WITHHOLDS Retry from an outcome that would otherwise allow it: the
-* SDK's own `not_queued` for a refusal the gateway will repeat is `classification('not_queued',
-* { retryable: false })` (also exported, frozen, as {@link NOT_QUEUED_FINAL}). An app may take
-* Retry away from an outcome but never grant it to one that cannot have it, so only `false` is
-* accepted.
+* SDK's own `not_queued` for a refusal the gateway will repeat is
+* `classification('not_queued', { retryable: false })` (also exported, frozen, as
+* {@link NOT_QUEUED_FINAL}). An app may take Retry away from an outcome but never grant it to one
+* that cannot have it, so only `false` is accepted.
 *
 * @example
 * ```ts
@@ -5855,6 +6065,15 @@ const NOT_QUEUED_FINAL = Object.freeze(classification("not_queued", { retryable:
 function notSentClassification() {
 	return classification("not_sent");
 }
+
+//#endregion
+//#region src/utils/failure_classification.ts
+/**
+* `classifyFailure` and `mayHaveBeenQueued`: the one module that holds the decision for every
+* catalog code (~135 names, a floor no minifier can remove). It needs the code table and nothing
+* else: the classification values live in `classification.ts`, the yes/no guards in
+* `failure_guards.ts`, and the error class and catalog are only named as types.
+*/
 const REJECTED = classification("rejected");
 const UNKNOWN = classification("unknown");
 const NOT_QUEUED = classification("not_queued");
@@ -5954,90 +6173,6 @@ function classifyChainDispatchFailed(view) {
 	return status === 422 ? REJECTED : NOT_QUEUED;
 }
 /**
-* True when the gateway answered that the write's `uniqueKey` was ALREADY CONSUMED: a
-* `CHAIN_DISPATCH_FAILED` with HTTP status 409. The first attempt under that key may be applied
-* (`classifyFailure` says `unknown`), so the app confirms the key it holds instead of submitting
-* again or showing the server's text. It replaces `error.code === 'CHAIN_DISPATCH_FAILED' &&
-* error.status === 409` and the regex on "already saved". Accepts an SDK error or a plain-object
-* view ({@link FailureView}: `code` and `status`); every other value is `false`.
-*
-* @example
-* ```ts
-* if (isUniqueKeyConsumed(error)) return confirmAndShowResult(error.uniqueKey);
-* ```
-*/
-function isUniqueKeyConsumed(error) {
-	const view = toFailureView(error);
-	return (view === null || view === void 0 ? void 0 : view.code) === "CHAIN_DISPATCH_FAILED" && view.status === 409;
-}
-const UNPROVEN_ACKNOWLEDGEMENT_CODES = [
-	"GATEWAY_DATA_MISSING",
-	"GATEWAY_MODE_INVALID",
-	"GATEWAY_SYNC_REQUEST_TRADE",
-	"MISSING_UNIQUE_KEY",
-	"UNIQUE_KEY_MISMATCH"
-];
-/**
-* True when a write got a 2xx answer that does NOT prove it was queued under the signed key: no
-* `data`, an unreadable `mode`, a synchronous RequestTrade, or a missing or foreign `uniqueKey`.
-* The outcome is `unknown` (it may have been queued: confirm `error.uniqueKey`), and the copy an
-* app shows is one line for all five ("the backend did not confirm it queued the request"), so
-* the app asks this instead of keeping its own list of the codes. A gateway that says
-* `error: true` (`GATEWAY_REPORTED_ERROR`) is a refusal with its own message, not in this set.
-*
-* @example
-* ```ts
-* if (isUnprovenAcknowledgement(error)) keepPendingAndConfirm(error.uniqueKey);
-* ```
-*/
-function isUnprovenAcknowledgement(error) {
-	return hasCodeIn(error, UNPROVEN_ACKNOWLEDGEMENT_CODES);
-}
-/** True when `code` is one of `codes` (a list of catalog codes), by exact spelling. */
-function isCodeIn(code, codes) {
-	return codes.some((known) => known === code);
-}
-/**
-* True when `error` is an SDK error OR a plain-object view of one (see {@link FailureView}) whose
-* `code` is one of `codes`. The code is compared with the catalog's own spelling, so a wallet
-* error (`{ code: 'ACTION_REJECTED' }`, a numeric `4001`) is never a member.
-*/
-function hasCodeIn(error, codes) {
-	const view = toFailureView(error);
-	return view !== void 0 && isCodeIn(view.code, codes);
-}
-/**
-* The codes whose `params.serverMessage` is the gateway's own answer to THIS write, which an app
-* may show as it is (and falls back to its own line when it is empty): a refusal the gateway made
-* (`GATEWAY_REPORTED_ERROR`, a 2xx with `error: true`) or a bounce it named (the gateway codes the
-* SDK knows, and `GATEWAY_REJECTED` for one it does not).
-*/
-const RELAYABLE_REFUSAL_CODES = [
-	"GATEWAY_REPORTED_ERROR",
-	"METHOD_NOT_ALLOWED",
-	"SIGNATURE_INVALID",
-	"SIGNER_MISMATCH",
-	"DTO_INVALID",
-	"BOUNDS_VIOLATION",
-	"SYMBOL_CONFLICT",
-	"RATE_LIMITED",
-	"CHAIN_DISPATCH_FAILED",
-	"GATEWAY_REJECTED"
-];
-function isRelayableRefusal(error) {
-	return hasCodeIn(error, RELAYABLE_REFUSAL_CODES);
-}
-/**
-* True when a write got a 2xx answer the SDK refused to interpret, so the answer itself is in
-* `error.body` (or `error.bodyText`) for the app to read: the five unproven acknowledgements
-* (`isUnprovenAcknowledgement`) and `GATEWAY_REPORTED_ERROR` (a gateway that says `error: true`).
-* The outcome is `unknown` for all six. It replaces the app's own
-* `isUnprovenAcknowledgement(e) || isGSwapError(e, 'GATEWAY_REPORTED_ERROR')` pair.
-*/
-function isUninterpretedAnswer(error) {
-	return isUnprovenAcknowledgement(error) || hasCodeIn(error, ["GATEWAY_REPORTED_ERROR"]);
-}
-/**
 * Classifies any thrown value from its code (and, for two codes, its HTTP status), never from
 * message text, so an app does not have to re-derive "may I offer Retry?" and "is the outcome
 * unknown?" for every code. The decision for each code is in this module's table; a new catalog
@@ -6114,34 +6249,6 @@ function classifyView(view) {
 	if (code === "INVALID_PRIVATE_KEY") return { ...classifyInvalidPrivateKey(view) };
 	return { ...BY_CODE[code] ?? INVALID_INPUT };
 }
-/** Codes that mean "there is no market for this" however the app reached them. */
-const NO_MARKET_CODES = [
-	"NO_POOL_AVAILABLE",
-	"INSUFFICIENT_LIQUIDITY",
-	"UNKNOWN_TOKEN"
-];
-/**
-* True when a failure means "there is no market to trade this pair": `NO_POOL_AVAILABLE` (no pool
-* at any fee tier), `INSUFFICIENT_LIQUIDITY` (a pool too thin to quote), `UNKNOWN_TOKEN` (the DEX
-* has no trading symbol for the token), or a READ that was answered 404 (a quote the backend
-* cannot find, `error.notFound`). It replaces an app's own `code === ... || code === ... ||
-* notFound` list, so the empty-state ("No market for this pair") has one definition.
-*
-* A write that was answered 404 (it carries a `uniqueKey`) is a missing route, not a missing
-* market, and is not this. Accepts an SDK error or a plain-object view ({@link FailureView}); every
-* other value is `false`.
-*
-* @example
-* ```ts
-* if (isNoMarket(error)) showEmptyState(t('swap.noMarket')); else showError(error);
-* ```
-*/
-function isNoMarket(error) {
-	const view = toFailureView(error);
-	if (view === void 0) return false;
-	if (isCodeIn(view.code, NO_MARKET_CODES)) return true;
-	return !isWriteView(view) && (view.notFound === true || view.status === 404);
-}
 /**
 * True when the failed call was a WRITE that may nevertheless have been queued: its outcome is
 * `unknown` (`classifyFailure(error).outcome === 'unknown'`: a timeout or broken connection after
@@ -6168,59 +6275,7 @@ function mayHaveBeenQueued(error) {
 }
 
 //#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;
-/**
-* A {@link StorageAdapter} over a `chrome.storage` area, the shape the wallet stores pending swaps
-* in: the value lands under the key as the structured value it is (the browser clones it; nothing
-* is serialized here). A missing key resolves `undefined`; a rejection of the area reaches the
-* store, which treats it as "storage unavailable".
-*
-* Pass a FUNCTION that returns the area to look it up at each call instead of when the adapter is
-* built: a module that is imported where `chrome` does not exist yet (a test, a closing extension
-* context) then fails only when the store touches storage, and that failure (a throw inside the
-* function) is the same "storage unavailable" rejection.
-*
-* @example
-* ```ts
-* const store = new PendingSwapStore(storageAdapterFromChromeStorage(chrome.storage.local));
-* const lazy = new PendingSwapStore(storageAdapterFromChromeStorage(() => chrome.storage.local));
-* ```
-*/
-function storageAdapterFromChromeStorage(area) {
-	const areaNow = () => typeof area === "function" ? area() : area;
-	return {
-		async get(key) {
-			const items = await areaNow().get(key);
-			return Object.hasOwn(items, key) ? items[key] : void 0;
-		},
-		async set(key, value) {
-			await areaNow().set({ [key]: value });
-		}
-	};
-}
-/**
-* Why the store dropped a pending swap (the `reason` of {@link PrunedPendingSwap}).
-*
-* - `expired`: older than {@link PENDING_SWAP_EXPIRY_MS}.
-* - `invalid_unique_key`: its `uniqueKey` is not a valid apply-results key (1 to 128 characters
-*   of `A-Za-z0-9._:-`). `confirmAppliedTrade` refuses such a key with `INVALID_UNIQUE_KEY`
-*   before reading anything and always will, so keeping the entry would retry it forever. The
-*   SDK never signs such a key; an entry like this is corrupt or foreign.
-* - `chain_rejected`: {@link PendingSwapStore.settle} dropped it because a confirmation proved the
-*   chain REFUSED the trade (`pendingSwapFateFor` is `forget`): it did not happen.
-* - `unconfirmable`: {@link PendingSwapStore.settle} dropped it because a confirmation failed in a
-*   way that never changes (`forget_quietly`: the key itself is refused): nothing can be learned.
-*/
-const PENDING_SWAP_PRUNE_REASONS = [
-	"expired",
-	"invalid_unique_key",
-	"chain_rejected",
-	"unconfirmable"
-];
+//#region src/classes/pending_swap_fate.ts
 /**
 * What to do with a pending swap after confirming it failed (the answer of
 * {@link pendingSwapFateFor}).
@@ -6230,6 +6285,9 @@ const PENDING_SWAP_PRUNE_REASONS = [
 *   Drop it without claiming anything about the trade.
 * - `keep`: the trade may still have been applied (a timeout, a broken connection, a gateway
 *   hiccup, anything not proven). Leave it pending and look again later.
+*
+* This module holds the decision and nothing of the store, so an app shell that only needs the
+* fate pays for `classifyFailure` and this table, not for `PendingSwapStore`.
 */
 const PENDING_SWAP_FATES = [
 	"forget",
@@ -6278,6 +6336,32 @@ function pendingSwapFateOfOutcome(outcome) {
 function pendingSwapFateFor(error) {
 	return pendingSwapFateOfOutcome(classifyFailure(error, { afterQueued: true }).outcome);
 }
+
+//#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;
+/**
+* Why the store dropped a pending swap (the `reason` of {@link PrunedPendingSwap}).
+*
+* - `expired`: older than {@link PENDING_SWAP_EXPIRY_MS}.
+* - `invalid_unique_key`: its `uniqueKey` is not a valid apply-results key (1 to 128 characters
+*   of `A-Za-z0-9._:-`). `confirmAppliedTrade` refuses such a key with `INVALID_UNIQUE_KEY`
+*   before reading anything and always will, so keeping the entry would retry it forever. The
+*   SDK never signs such a key; an entry like this is corrupt or foreign.
+* - `chain_rejected`: {@link PendingSwapStore.settle} dropped it because a confirmation proved the
+*   chain REFUSED the trade (`pendingSwapFateFor` is `forget`): it did not happen.
+* - `unconfirmable`: {@link PendingSwapStore.settle} dropped it because a confirmation failed in a
+*   way that never changes (`forget_quietly`: the key itself is refused): nothing can be learned.
+*/
+const PENDING_SWAP_PRUNE_REASONS = [
+	"expired",
+	"invalid_unique_key",
+	"chain_rejected",
+	"unconfirmable"
+];
 /**
 * 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`).
@@ -7131,7 +7215,7 @@ function createLazyPrivateKeySigner(getPrivateKey, options = {}) {
 *
 * `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`
+* a wallet build that contains wallet_extension commit 34ca4e4 (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
@@ -7156,7 +7240,7 @@ var GalaWalletSigner = class {
 	* 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.
+	* `'personal-sign'` requires a Gala Wallet build with wallet_extension commit 34ca4e4.
 	* `selectAddress` is the identity (`client|...` / `eth|...`) Gala Wallet is switched to with
 	* `window.gala.setAddress` before every signature, when the wallet offers it.
 	*/
@@ -7237,6 +7321,7 @@ var BrowserWalletSigner = class {
 		this.walletAddress = normalizeEthereumAccount(walletAddress, false);
 		this.scheme = options.scheme ?? "personal-sign";
 	}
+	/** The selected `0x` Ethereum account every signature is requested for. */
 	walletAddress;
 	scheme;
 	/**
@@ -7259,6 +7344,74 @@ var BrowserWalletSigner = class {
 	}
 };
 
+//#endregion
+//#region src/classes/storage_adapters.ts
+/**
+* A {@link StorageAdapter} over a `chrome.storage` area, the shape the wallet stores pending swaps
+* in: the value lands under the key as the structured value it is (the browser clones it; nothing
+* is serialized here). A missing key resolves `undefined`; a rejection of the area reaches the
+* store, which treats it as "storage unavailable".
+*
+* Pass a FUNCTION that returns the area to look it up at each call instead of when the adapter is
+* built: a module that is imported where `chrome` does not exist yet (a test, a closing extension
+* context) then fails only when the store touches storage, and that failure (a throw inside the
+* function) is the same "storage unavailable" rejection.
+*
+* @example
+* ```ts
+* const store = new PendingSwapStore(storageAdapterFromChromeStorage(chrome.storage.local));
+* const lazy = new PendingSwapStore(storageAdapterFromChromeStorage(() => chrome.storage.local));
+* ```
+*/
+function storageAdapterFromChromeStorage(area) {
+	const areaNow = () => typeof area === "function" ? area() : area;
+	return {
+		async get(key) {
+			const items = await areaNow().get(key);
+			return Object.hasOwn(items, key) ? items[key] : void 0;
+		},
+		async set(key, value) {
+			await areaNow().set({ [key]: value });
+		}
+	};
+}
+/**
+* A {@link StorageAdapter} over a Web Storage area (`localStorage`, `sessionStorage`), the shape
+* frontend_v2 stores pending swaps in: the value lands under the key as JSON text. A missing key
+* resolves `undefined`. CORRUPT JSON resolves as the raw string, never a rejection (the store
+* reads a value that is not an array as "no entries" and the next write repairs it, whereas a
+* `get` that rejects forever would make every `remember` a no-op). A throwing area (storage blocked
+* by the browser, quota exceeded on `setItem`) rejects, which the store treats as "storage
+* unavailable".
+*
+* Pass a FUNCTION that returns the area to look it up at each call instead of when the adapter is
+* built: where `localStorage` does not exist (server rendering, a test, a blocked context)
+* the access throws inside the function, which is the same "storage unavailable" rejection, and
+* the module that builds the adapter still loads.
+*
+* @example
+* ```ts
+* const store = new PendingSwapStore(webStorageAdapter(() => localStorage));
+* ```
+*/
+function webStorageAdapter(area) {
+	const areaNow = () => typeof area === "function" ? area() : area;
+	return {
+		async get(key) {
+			const raw = areaNow().getItem(key);
+			if (raw === null) return void 0;
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return raw;
+			}
+		},
+		async set(key, value) {
+			areaNow().setItem(key, JSON.stringify(value));
+		}
+	};
+}
+
 //#endregion
 //#region src/utils/chain_dto_signing.ts
 /**
@@ -7267,7 +7420,7 @@ var BrowserWalletSigner = class {
 *
 * 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
+* payload resolver from its commit 34ca4e4), 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.
@@ -7988,6 +8141,152 @@ function isFetchTransportFailure(error) {
 	}
 }
 
+//#endregion
+//#region src/utils/failure_guards.ts
+/**
+* The yes/no questions an app asks about a failure from its CODE alone. They read only the failure
+* view and a short list of codes: no table of every code (that is `classifyFailure`'s, in
+* `failure_classification.ts`), no error class and no catalog (the imports above are types, erased
+* at build time). An app shell that imports one of them pays for this module and nothing else.
+*/
+/**
+* True when the gateway answered that the write's `uniqueKey` was ALREADY CONSUMED: a
+* `CHAIN_DISPATCH_FAILED` with HTTP status 409. The first attempt under that key may be applied
+* (`classifyFailure` says `unknown`), so the app confirms the key it holds instead of submitting
+* again or showing the server's text. It replaces `error.code === 'CHAIN_DISPATCH_FAILED' &&
+* error.status === 409` and the regex on "already saved". Accepts an SDK error or a plain-object
+* view ({@link FailureView}: `code` and `status`); every other value is `false`.
+*
+* @example
+* ```ts
+* if (isUniqueKeyConsumed(error)) return confirmAndShowResult(error.uniqueKey);
+* ```
+*/
+function isUniqueKeyConsumed(error) {
+	const view = toFailureView(error);
+	return (view === null || view === void 0 ? void 0 : view.code) === "CHAIN_DISPATCH_FAILED" && view.status === 409;
+}
+const UNPROVEN_ACKNOWLEDGEMENT_CODES = [
+	"GATEWAY_DATA_MISSING",
+	"GATEWAY_MODE_INVALID",
+	"GATEWAY_SYNC_REQUEST_TRADE",
+	"MISSING_UNIQUE_KEY",
+	"UNIQUE_KEY_MISMATCH"
+];
+/**
+* True when a write got a 2xx answer that does NOT prove it was queued under the signed key: no
+* `data`, an unreadable `mode`, a synchronous RequestTrade, or a missing or foreign `uniqueKey`.
+* The outcome is `unknown` (it may have been queued: confirm `error.uniqueKey`), and the copy an
+* app shows is one line for all five ("the backend did not confirm it queued the request"), so
+* the app asks this instead of keeping its own list of the codes. A gateway that says
+* `error: true` (`GATEWAY_REPORTED_ERROR`) is a refusal with its own message, not in this set.
+*
+* @example
+* ```ts
+* if (isUnprovenAcknowledgement(error)) keepPendingAndConfirm(error.uniqueKey);
+* ```
+*/
+function isUnprovenAcknowledgement(error) {
+	return hasCodeIn(error, UNPROVEN_ACKNOWLEDGEMENT_CODES);
+}
+/** True when `code` is one of `codes` (a list of catalog codes), by exact spelling. */
+function isCodeIn(code, codes) {
+	return codes.some((known) => known === code);
+}
+/**
+* True when `error` is an SDK error OR a plain-object view of one (see {@link FailureView}) whose
+* `code` is one of `codes`. The code is compared with the catalog's own spelling, so a wallet
+* error (`{ code: 'ACTION_REJECTED' }`, a numeric `4001`) is never a member.
+*/
+function hasCodeIn(error, codes) {
+	const view = toFailureView(error);
+	return view !== void 0 && isCodeIn(view.code, codes);
+}
+/**
+* The codes whose `params.serverMessage` is the gateway's own answer to THIS write, which an app
+* may show as it is (and falls back to its own line when it is empty): a refusal the gateway made
+* (`GATEWAY_REPORTED_ERROR`, a 2xx with `error: true`) or a bounce it named (the gateway codes the
+* SDK knows, and `GATEWAY_REJECTED` for one it does not).
+*/
+const RELAYABLE_REFUSAL_CODES = [
+	"GATEWAY_REPORTED_ERROR",
+	"METHOD_NOT_ALLOWED",
+	"SIGNATURE_INVALID",
+	"SIGNER_MISMATCH",
+	"DTO_INVALID",
+	"BOUNDS_VIOLATION",
+	"SYMBOL_CONFLICT",
+	"RATE_LIMITED",
+	"CHAIN_DISPATCH_FAILED",
+	"GATEWAY_REJECTED"
+];
+function isRelayableRefusal(error) {
+	return hasCodeIn(error, RELAYABLE_REFUSAL_CODES);
+}
+/**
+* True when a write got a 2xx answer the SDK refused to interpret, so the answer itself is in
+* `error.body` (or `error.bodyText`) for the app to read: the five unproven acknowledgements
+* (`isUnprovenAcknowledgement`) and `GATEWAY_REPORTED_ERROR` (a gateway that says `error: true`).
+* The outcome is `unknown` for all six. It replaces the app's own
+* `isUnprovenAcknowledgement(e) || isGSwapError(e, 'GATEWAY_REPORTED_ERROR')` pair.
+*/
+function isUninterpretedAnswer(error) {
+	return isUnprovenAcknowledgement(error) || hasCodeIn(error, ["GATEWAY_REPORTED_ERROR"]);
+}
+/**
+* The chain's own machine-readable `ErrorKey` of a failure (`'TOKEN_NOT_FOUND'`,
+* `'NOT_ENOUGH_LIQUIDITY'`, ...), for an app that maps a chain refusal to its own copy: the
+* `params.errorKey` of a `CHAIN_REJECTED` (an apply result, or a body that carries the chain's
+* error) and of a `CHAIN_DISPATCH_FAILED` (the gateway adds the chain's key to the body it
+* answered). `undefined` when the failure is neither, or when it carries no key (the gateway sent
+* none: the SDK writes `''`, which is not a key). Map the KEY, never the message text.
+*
+* Accepts an SDK error or a plain-object view ({@link FailureView}: `code` and `params`); every
+* other value is `undefined`. Other codes are `undefined` even when they have an `errorKey`-named
+* param, so a stray field cannot pass for a chain verdict.
+*
+* @example
+* ```ts
+* const key = chainErrorKeyOf(error);
+* if (key === 'NOT_ENOUGH_LIQUIDITY') showTooThin(); else showGeneric(error);
+* ```
+*/
+function chainErrorKeyOf(error) {
+	const view = toFailureView(error);
+	if (view === void 0) return void 0;
+	if (view.code !== "CHAIN_REJECTED" && view.code !== "CHAIN_DISPATCH_FAILED") return void 0;
+	const errorKey = stringParamOf(view, "errorKey");
+	return errorKey === void 0 || errorKey === "" ? void 0 : errorKey;
+}
+/** Codes that mean "there is no market for this" however the app reached them. */
+const NO_MARKET_CODES = [
+	"NO_POOL_AVAILABLE",
+	"INSUFFICIENT_LIQUIDITY",
+	"UNKNOWN_TOKEN"
+];
+/**
+* True when a failure means "there is no market to trade this pair": `NO_POOL_AVAILABLE` (no pool
+* at any fee tier), `INSUFFICIENT_LIQUIDITY` (a pool too thin to quote), `UNKNOWN_TOKEN` (the DEX
+* has no trading symbol for the token), or a READ that was answered 404 (a quote the backend
+* cannot find, `error.notFound`). It replaces an app's own `code === ... || code === ... ||
+* notFound` list, so the empty-state ("No market for this pair") has one definition.
+*
+* A write that was answered 404 (it carries a `uniqueKey`) is a missing route, not a missing
+* market, and is not this. Accepts an SDK error or a plain-object view ({@link FailureView}); every
+* other value is `false`.
+*
+* @example
+* ```ts
+* if (isNoMarket(error)) showEmptyState(t('swap.noMarket')); else showError(error);
+* ```
+*/
+function isNoMarket(error) {
+	const view = toFailureView(error);
+	if (view === void 0) return false;
+	if (isCodeIn(view.code, NO_MARKET_CODES)) return true;
+	return !isWriteView(view) && (view.notFound === true || view.status === 404);
+}
+
 //#endregion
 //#region src/utils/submit_state.ts
 /** The `mode` of `envelope.data`, or `undefined` when there is no such field. */
@@ -8075,7 +8374,9 @@ exports.Symbols = Symbols;
 exports.TICK_SPACING_BY_FEE = TICK_SPACING_BY_FEE;
 exports.UPDATE_REQUIRED_STATUS = UPDATE_REQUIRED_STATUS;
 exports.alignTickDown = alignTickDown;
+exports.alignTickDownOrNaN = alignTickDownOrNaN;
 exports.alignTickUp = alignTickUp;
+exports.alignTickUpOrNaN = alignTickUpOrNaN;
 exports.assertCanonicalPair = assertCanonicalPair;
 exports.assertCanonicalV2Dto = assertCanonicalV2Dto;
 exports.assertTickRange = assertTickRange;
@@ -8089,6 +8390,7 @@ exports.buildRemoveLiquidityDto = buildRemoveLiquidityDto;
 exports.buildRequestTradeDto = buildRequestTradeDto;
 exports.calculatePersonalSignPrefix = calculatePersonalSignPrefix;
 exports.canonicalDecimalString = canonicalDecimalString;
+exports.chainErrorKeyOf = chainErrorKeyOf;
 exports.classification = classification;
 exports.classifyFailure = classifyFailure;
 exports.classifyShadowSubmitError = classifyShadowSubmitError;
@@ -8125,9 +8427,11 @@ exports.isPreSendError = isPreSendError;
 exports.isProposableTradingSymbol = isProposableTradingSymbol;
 exports.isRelayableRefusal = isRelayableRefusal;
 exports.isShadowError = isShadowError;
+exports.isSqrtPriceInRange = isSqrtPriceInRange;
 exports.isSubmitExecuted = isSubmitExecuted;
 exports.isSubmitQueued = isSubmitQueued;
 exports.isSubmitRejected = isSubmitRejected;
+exports.isTickInRange = isTickInRange;
 exports.isUninterpretedAnswer = isUninterpretedAnswer;
 exports.isUniqueKeyConsumed = isUniqueKeyConsumed;
 exports.isUnprovenAcknowledgement = isUnprovenAcknowledgement;
@@ -8180,5 +8484,6 @@ exports.validateTickSpacing = validateTickSpacing;
 exports.validateTokenDecimals = validateTokenDecimals;
 exports.validateWalletAddress = validateWalletAddress;
 exports.walletDeclineCode = walletDeclineCode;
+exports.webStorageAdapter = webStorageAdapter;
 exports.withPrivateKey = withPrivateKey;
 //# sourceMappingURL=index.cjs.map