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

package/dist/index.mjs

@@ -1315,6 +1315,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;
@@ -1640,7 +1641,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.9";
+const SDK_VERSION = "1.2.0";
 
 //#endregion
 //#region src/utils/transport.ts
@@ -1701,7 +1702,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.9"}` });
+	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" });
@@ -2132,6 +2133,15 @@ function tickFromPrice(price, options = {}) {
 
 //#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;
@@ -2153,6 +2163,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,
@@ -2180,12 +2196,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,
@@ -2202,6 +2230,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",
@@ -2209,9 +2242,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", {
@@ -2694,9 +2738,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;
@@ -2818,7 +2866,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;
@@ -2892,7 +2942,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
@@ -3140,7 +3190,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);
@@ -3218,6 +3270,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;
@@ -3259,30 +3312,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 });
 	}
@@ -4348,8 +4412,9 @@ const decimalString = (amount) => new BigNumber(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
@@ -5537,21 +5602,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",
@@ -5568,12 +5633,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) {
@@ -5815,27 +5880,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
@@ -5920,10 +6001,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
@@ -7104,7 +7185,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
@@ -7129,7 +7210,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.
 	*/
@@ -7210,6 +7291,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;
 	/**
@@ -7308,7 +7390,7 @@ function webStorageAdapter(area) {
 *
 * 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.