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

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import BigNumber from "bignumber.js";
+import "decimal.js";
 //#region src/types/confirm_options.d.ts
 /**
  * Controls timeout, polling and cancellation of confirmation.
@@ -176,9 +177,12 @@ export interface QuoteResult {
   token1Symbol: string;
   tokenInIsToken0: boolean;
   feeTier: number;
-  currentPrice?: BigNumber;
-  newPrice?: BigNumber;
-  priceImpact?: BigNumber;
+  /** Pool price before the trade, token out per token in (always set by `Quoting`). */
+  currentPrice: BigNumber;
+  /** Pool price after the trade, in the same orientation (always set by `Quoting`). */
+  newPrice: BigNumber;
+  /** `(newPrice - currentPrice) / currentPrice` as a fraction (`-0.01` is 1% adverse), always set by `Quoting`. */
+  priceImpact: BigNumber;
 }
 /** The executed trade as reported by the ApplyRequests result (contract Trade response). */
 export interface TradeExecution {
@@ -1310,6 +1314,11 @@ export declare const gswapErrorTemplates: { readonly [C in GSwapErrorCode]: stri
 export declare function renderGSwapErrorTemplate(template: string, params: Readonly<Record<string, unknown>>): string;
 //#endregion
 //#region src/types/token.d.ts
+/**
+ * The four parts of a GalaChain token class key, as the chain keys a token (for example
+ * `GALA|Unit|none|none` is collection `GALA`, category `Unit`, type `none`, additionalKey `none`).
+ * It carries no trading symbol: a collection and a symbol disagree for many tokens.
+ */
 export interface GalaChainTokenClassKey {
   collection: string;
   category: string;
@@ -1424,6 +1433,7 @@ export declare class GSwapSDKError<C extends GSwapErrorCode = GSwapErrorCode> ex
   readonly code: C;
   /** The named placeholders of the error: a flat object of primitives, safe to localize with. */
   readonly params: GSwapErrorParams<C>;
+  /** The server's `Retry-After` in milliseconds (a `RATE_LIMITED` answer), when it sent one. */
   readonly retryAfterMs: number | undefined;
   /** The HTTP status of the response that caused this error, when there was one. */
   readonly status: number | undefined;
@@ -1832,7 +1842,7 @@ export declare function createLazyPrivateKeySigner(getPrivateKey: PrivateKeyProv
  *
  * `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
@@ -1857,7 +1867,7 @@ export declare class GalaWalletSigner implements GalaChainSigner {
    * 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.
    */
@@ -1916,6 +1926,7 @@ export declare class BrowserWalletSigner implements GalaChainSigner {
   constructor(provider: BrowserWalletProvider, walletAddress: string, options?: {
     scheme?: 'personal-sign' | 'eip712';
   });
+  /** The selected `0x` Ethereum account every signature is requested for. */
   readonly walletAddress: string;
   private readonly scheme;
   /**
@@ -1938,6 +1949,7 @@ export declare class BrowserWalletSigner implements GalaChainSigner {
 //#region src/classes/dex_fees.d.ts
 /** DEX methods the backend accepts a fee quote for (its allow-list enumerates the same six). */
 export declare const DEX_FEE_METHODS: readonly ['Swap', 'RequestTrade', 'AddLiquidity', 'RemoveLiquidity', 'CollectPositionFees', 'CreatePool'];
+/** A chain method whose network fee `DexFees.quote` can price (see `isDexFeeMethod`). */
 export type DexFeeMethod = (typeof DEX_FEE_METHODS)[number];
 /** Which pool contract the DTO being quoted targets: legacy (V3) or current (GalaChainDex). */
 export type DexFeeContract = 'dexv3-contract' | 'dex-contract';
@@ -2054,18 +2066,19 @@ export interface ShadowSubmitResult {
  *
  * - `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.
  */
-export declare const SHADOW_SUBMIT_CODES: readonly ['SHADOW_UNAVAILABLE', 'SHADOW_DISABLED', 'SHADOW_UNSUPPORTED_TYPE', 'SHADOW_RELAY_REJECTED'];
+export declare const SHADOW_SUBMIT_CODES: readonly ['SHADOW_UNAVAILABLE', 'SHADOW_UNSUPPORTED_TYPE', 'SHADOW_RELAY_REJECTED'];
 /** One member of {@link SHADOW_SUBMIT_CODES}. */
 export type ShadowSubmitCode = (typeof SHADOW_SUBMIT_CODES)[number];
 /**
  * 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`.
  */
 export declare const SHADOW_FAILURE_KINDS: readonly ['unavailable', 'disabled', 'rejected', 'unknown'];
 /** One member of {@link SHADOW_FAILURE_KINDS}. */
@@ -2122,7 +2135,7 @@ export declare function classifyShadowSubmitStatus(status: number): ShadowFailur
 /**
  * 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".
  */
 export declare function classifyShadowSubmitError(status: number, code?: string): ShadowFailureKind;
 /**
@@ -2195,9 +2208,13 @@ export type PositionConfirmationResult = {
 };
 /** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
 export declare class SubmittedTransaction<TConfirmation = AppliedTrade | Position | null> {
+  /** The chain method that was submitted (`RequestTrade`, `AddLiquidity`, ...). */
   readonly method: string;
+  /** The write's durable correlation key: persist it, and confirm from it alone later. */
   readonly uniqueKey: string;
+  /** The request transaction id the gateway reported, or `null` when it gave none. */
   readonly transactionId: string | null;
+  /** The block of the transaction, when the answer carried one; otherwise `null`. */
   readonly blockNumber: number | null;
   /** The gateway's `data.mode`: `'sync'` (executed, `result` is the chain result) or `'queued'`. */
   readonly mode: 'sync' | 'queued';
@@ -2357,7 +2374,9 @@ export declare class ChainGateway {
   private readonly chainCallTimeoutMs;
   private readonly isTransportFailure;
   private readonly answerOfRejectionHook;
+  /** The request timeout in milliseconds (`Infinity` when no timer is armed). */
   readonly requestTimeoutMs: number;
+  /** The swap backend base URL every request is sent to, without a trailing slash. */
   readonly dexBackendBaseUrl: string;
   /** Wire format shared by the read services built on this gateway. */
   readonly wire: WireOptions;
@@ -2382,7 +2401,7 @@ export declare class ChainGateway {
    *
    * 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
@@ -2517,7 +2536,9 @@ export interface GdexSubscription {
 }
 /** A JSON-RPC error answered by the stream. */
 export declare class GdexStreamError extends Error {
+  /** The JSON-RPC error code. */
   readonly code: number;
+  /** The error's optional `data` member, as the server sent it. */
   readonly data?: unknown;
   constructor(code: number, message: string, data?: unknown);
 }
@@ -2555,17 +2576,26 @@ export declare class GdexStreamService {
   connect(): Promise<void>;
   /** Close the connection and stop reconnecting. */
   disconnect(): void;
+  /** `true` while the socket is open (false while connecting, reconnecting or after `disconnect()`). */
   isConnected(): boolean;
   /** Raw JSON-RPC escape hatch. */
   request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
   private send;
+  /** `gdex_serverInfo`: the server's own description of itself, as it sends it. */
   serverInfo(): Promise<Record<string, unknown>>;
+  /** `gdex_ping`: a round trip that answers `{ pong, serverTime }`. */
   ping(): Promise<{
     pong: boolean;
     serverTime: string;
   }>;
+  /** `gdex_getPool`: the current state of one pool, selected by its key or hash. */
   getPool(selector: GdexPoolSelector): Promise<Record<string, unknown>>;
+  /** `gdex_getBalance`: an owner's balances, or only the one of `tokenClassKey` when given. */
   getBalance(owner: string, tokenClassKey?: string): Promise<Record<string, unknown>>;
+  /**
+   * `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: {
     owner: string;
     pool?: GdexPoolKey;
@@ -2576,10 +2606,12 @@ export declare class GdexStreamService {
     positions: Record<string, unknown>[];
     bookmark: string;
   }>;
+  /** `gdex_getBlockHeight`: the block number the server reports, with its timestamp. */
   getBlockHeight(): Promise<{
     blockNumber: number;
     timestamp: string;
   }>;
+  /** `gdex_quote`: a quote over the stream; give exactly one of `amountIn` or `amountOut`. */
   quote(params: {
     tokenIn: string;
     tokenOut: string;
@@ -2587,6 +2619,7 @@ export declare class GdexStreamService {
     amountIn?: string;
     amountOut?: string;
   }): Promise<Record<string, unknown>>;
+  /** `gdex_getToken`: the server's record of one token class, as it sends it. */
   getToken(tokenClassKey: string): Promise<Record<string, unknown>>;
   /** One event per committed swap. Omit the pool to receive every pool's swaps. */
   subscribeSwaps(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
@@ -2695,8 +2728,6 @@ export declare function readOrderedSymbols(value: unknown): {
   token0: string;
   token1: string;
 };
-/** Return the `$`-joined composite key used by GalaChain object identities. */
-export declare function compositeKeyOf(token: GalaChainTokenClassKey): string;
 /**
  * Parse a pipe- or dollar-separated token class key.
  *
@@ -2712,42 +2743,6 @@ export declare function compositeKeyOf(token: GalaChainTokenClassKey): string;
  * ```
  */
 export declare function parseTokenClassKey(tokenClassKey: TokenRef): GalaChainTokenClassKey;
-/**
- * The non-throwing {@link 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
- * (`undefined`, `null`, a number, an array) is `undefined`, so it is safe on untrusted input (a
- * stored token, a URL parameter, a wallet row) without a `try`/`catch`.
- *
- * Use {@link tryParseCompositeKey} instead when only the `$` form is valid input.
- *
- * @example
- * ```ts
- * const key = tryParseTokenClassKey(row.compositeKey);
- * if (key === undefined) return failClosed(); // no class is known: never invent one from a symbol
- * ```
- */
-export declare function tryParseTokenClassKey(value: unknown): GalaChainTokenClassKey | undefined;
-/**
- * Parses a `$`-joined composite key (`Collection$Category$Type$AdditionalKey`, what
- * {@link compositeKeyOf} writes) and nothing else, or `undefined`. It is {@link tryParseTokenClassKey}
- * for a string that may ONLY be in the `$` form: a key that contains `|` is NOT read as the pipe
- * form here (it stays part of a segment), and only a string is accepted. The split is from the
- * right, so a collection that itself contains `$` (production's `$GMUSIC`, stage's
- * `$GMUSIC_TEST1`) stays whole; `'GALA'`, `'GALA$Unit$none'`, `'ETIME$$$'`, `'GALA$Unit$none$'` and
- * `'$$$$'` are `undefined`.
- *
- * It replaces an app's own `parseCompositeKey(key): Components | null` (`?? null`), which had
- * exactly these semantics.
- *
- * @example
- * ```ts
- * tryParseCompositeKey('$GMUSIC_TEST1$Unit$none$none')?.collection; // '$GMUSIC_TEST1'
- * tryParseCompositeKey('GALA$Unit$none'); // undefined
- * ```
- */
-export declare function tryParseCompositeKey(value: unknown): GalaChainTokenClassKey | undefined;
 //#endregion
 //#region src/classes/symbols.d.ts
 /** Symbol registry client for the current GalaChainDex contract. */
@@ -2970,10 +2965,22 @@ interface Branding<BrandT> {
 type Brand<T, BrandT> = T & Branding<BrandT>;
 //#endregion
 //#region src/types/amounts.d.ts
+/** A decimal amount: a string or a `BigNumber`, never a JavaScript number. */
 export type NumericAmount = string | BigNumber;
+/** A calculated square-root price (always a `BigNumber`, branded so it is never mistaken for a price). */
 export type SqrtPrice = Brand<BigNumber, 'SqrtPrice'>;
+/**
+ * A square-root price an API accepts: a calculated {@link SqrtPrice}, or a decimal string /
+ * `BigNumber` the caller brands with `as SqrtPriceIn` to declare what it is.
+ */
 export type SqrtPriceIn = Brand<NumericAmount, 'SqrtPriceIn'> | SqrtPrice;
+/** A calculated price (always a `BigNumber`, branded so it is never mistaken for a square-root price). */
 export type Price = Brand<BigNumber, 'Price'>;
+/**
+ * A price an API accepts (for example `addLiquidityByPrice`'s `minPrice` / `maxPrice`): a calculated
+ * {@link Price}, or a decimal string / `BigNumber` the caller brands with `as PriceIn` to declare
+ * what it is. An unbranded string does not compile.
+ */
 export type PriceIn = Brand<NumericAmount, 'PriceIn'> | Price;
 /**
  * What a swap trades: exactly one of `exactIn` (sell this much of the input token) or `exactOut`
@@ -3720,10 +3727,18 @@ export declare const GSWAP_ENVIRONMENTS: Readonly<Record<GSwapEnv, GSwapEnvironm
 //#region src/classes/gswap.d.ts
 /** Options for constructing a backend-routed SDK client. */
 export interface GSwapOptions {
+  /** Signs every write. Without one, reads work and any write throws `NO_SIGNER`. */
   signer?: GalaChainSigner | undefined;
+  /**
+   * The selected account, sent as `X-Wallet-Address` on writes (attribution only; the chain
+   * recovers the signer from the signature). Required for shadow writes.
+   */
   walletAddress?: string | undefined;
+  /** `'stage'` or `'prod'` swap backend preset; defaults to `'prod'`. */
   env?: GSwapEnv | undefined;
+  /** Overrides the preset's swap backend base URL (a test or private deployment). */
   dexBackendBaseUrl?: string | undefined;
+  /** HTTP transport for every request; defaults to the global `fetch`. */
   httpRequestor?: HttpRequestor | undefined;
   /** Request timeout in milliseconds (default 30 000); `Infinity` arms no timer. */
   chainCallTimeoutMs?: number | undefined;
@@ -3757,27 +3772,43 @@ export interface GSwapOptions {
    */
   uniqueKeyPrefix?: string | undefined;
 }
-/** 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.
+ */
 export declare class GSwap {
+  /** The swap backend base URL every request goes to, without a trailing slash. */
   readonly dexBackendBaseUrl: string;
+  /** The request timeout in milliseconds (default 30 000; `Infinity` arms no timer). */
   readonly chainCallTimeoutMs: number;
+  /** The signer given at construction, if any. */
   readonly signer: GalaChainSigner | undefined;
+  /** The account given at construction, if any. */
   readonly walletAddress: string | undefined;
+  /** The chain-gateway client every other service reads and writes through. */
   readonly gateway: ChainGateway;
+  /** The trading-symbol registry. */
   readonly symbols: Symbols;
+  /** Read-only exact-input and exact-output quotes. */
   readonly quoting: Quoting;
+  /** Pool, slot0 and composite-pool reads. */
   readonly pools: Pools;
+  /** Position reads, liquidity estimates and liquidity / pool-creation writes. */
   readonly positions: Positions;
+  /** Queued swaps (`RequestTrade`), dark swaps and swap confirmation. */
   readonly swaps: Swaps;
+  /** User token balances. */
   readonly assets: Assets;
   /** Network-fee quotes (DryRun) signed with this client's signer. */
   readonly fees: DexFees;
+  /** The realtime stream endpoint {@link GSwap.stream} connects to. */
   readonly dexBackendWsUrl: string;
   private readonly webSocketImpl;
   private readonly streamApiKey;
   private 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
@@ -4058,27 +4089,66 @@ export declare const GSWAP_ERROR_PHASE_BY_CODE: {
   readonly INVALID_LIMIT: 'pre_send';
 };
 //#endregion
-//#region src/classes/pending_swaps.d.ts
-/** Key the wallet_extension has always used; its storage value is a plain array of entries. */
-export declare const PENDING_SWAPS_STORAGE_KEY = "pendingSwaps.v1";
-/** Entries older than this are dropped the next time a wallet's swaps are listed. */
-export declare const PENDING_SWAP_EXPIRY_MS: number;
+//#region src/classes/pending_swap_fate.d.ts
+/**
+ * What to do with a pending swap after confirming it failed (the answer of
+ * {@link pendingSwapFateFor}).
+ *
+ * - `forget`: the chain REFUSED the trade, so it did not happen. Drop it AND tell the user.
+ * - `forget_quietly`: the confirmation can never succeed (the key is refused: `invalid_input`).
+ *   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`.
+ */
+export declare const PENDING_SWAP_FATES: readonly ['forget', 'forget_quietly', 'keep'];
+/** One member of {@link PENDING_SWAP_FATES}. */
+export type PendingSwapFate = (typeof PENDING_SWAP_FATES)[number];
+/**
+ * {@link pendingSwapFateFor} from an outcome the app already holds (for example the
+ * `classifyFailure(error).outcome` it stored on its own failure wrapper). An outcome this SDK
+ * version does not know (a newer SDK at run time) is `keep`: never forget what may have happened.
+ */
+export declare function pendingSwapFateOfOutcome(outcome: FailureOutcome): PendingSwapFate;
+/**
+ * The fate of a queued swap whose confirmation (`confirmAppliedTrade`) just failed with `error`,
+ * from the SDK's classification alone: `forget` for a chain rejection (`rejected`), `forget_quietly`
+ * for a key that can never be confirmed (`invalid_input`), `keep` for every other outcome
+ * (`unknown`, `not_queued`, `not_sent`, `transient`) and for any value the SDK cannot judge. It
+ * accepts an SDK error or a plain-object view of one (see `FailureView`). It replaces the wallet's
+ * `pendingSwapActionFor` and frontend_v2's `confirmationStanceOf`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await confirmAppliedTrade(client, swap);
+ * } catch (error) {
+ *   if ((await store.settle(swap.uniqueKey, error)) === 'forget') tellTheUserItFailed();
+ * }
+ * ```
+ */
+export declare function pendingSwapFateFor(error: unknown): PendingSwapFate;
+//#endregion
+//#region src/classes/storage_adapters.d.ts
 /**
  * Async key/value storage the pending-swap store persists through. It stores STRUCTURED VALUES
  * (the store never serializes), so each platform decides how a value lands on disk:
  *
  * - `chrome.storage.local`: `get: async (k) => (await chrome.storage.local.get(k))[k]`,
  *   `set: (k, v) => chrome.storage.local.set({ [k]: v })`. This is the wallet's stored shape.
- * - `localStorage` (frontend_v2): `get: async (k) => { const raw = localStorage.getItem(k);
- *   if (raw === null) return undefined; try { return JSON.parse(raw); } catch { return raw; } }`,
- *   `set: async (k, v) => localStorage.setItem(k, JSON.stringify(v))`. Corrupt JSON MUST come back
- *   as a value (here the raw string), not as a rejection: a value that is not an array reads as
- *   "no entries" and the next write repairs it, whereas a `get` that rejects forever makes every
- *   `remember` a no-op.
+ *   {@link storageAdapterFromChromeStorage} builds it.
+ * - `localStorage` (frontend_v2): JSON text under the key. {@link webStorageAdapter} builds it,
+ *   and returns CORRUPT JSON as a value (the raw string), not as a rejection: a value that is not
+ *   an array reads as "no entries" and the next write repairs it, whereas a `get` that rejects
+ *   forever makes every `remember` a no-op.
  * - React Native: AsyncStorage with the same JSON wrapping and the same corrupt-JSON rule.
  *
  * `get` resolves `undefined` for a missing key. Either method may reject; the store treats that
- * as "storage unavailable" and never lets it surface (see {@link PendingSwapStore}).
+ * as "storage unavailable" and never lets it surface (see `PendingSwapStore`).
+ *
+ * This module imports nothing, so an app shell that only builds an adapter pays for the adapter.
  */
 export interface StorageAdapter {
   get(key: string): Promise<unknown>;
@@ -4113,6 +4183,41 @@ export interface ChromeStorageAreaLike {
  * ```
  */
 export declare function storageAdapterFromChromeStorage(area: ChromeStorageAreaLike | (() => ChromeStorageAreaLike)): StorageAdapter;
+/**
+ * The part of a Web Storage area ({@link webStorageAdapter}) the adapter uses, written
+ * structurally so the SDK needs no DOM types: `localStorage`, `sessionStorage` and any object with
+ * these two synchronous methods (a React Native MMKV wrapper, a test double) satisfy it.
+ */
+export interface WebStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+/**
+ * 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));
+ * ```
+ */
+export declare function webStorageAdapter(area: WebStorageLike | (() => WebStorageLike)): StorageAdapter;
+//#endregion
+//#region src/classes/pending_swaps.d.ts
+/** Key the wallet_extension has always used; its storage value is a plain array of entries. */
+export declare const PENDING_SWAPS_STORAGE_KEY = "pendingSwaps.v1";
+/** Entries older than this are dropped the next time a wallet's swaps are listed. */
+export declare const PENDING_SWAP_EXPIRY_MS: number;
 /** A RequestTrade that was accepted by the gateway but whose outcome has not been read yet. */
 export interface PendingSwap {
   uniqueKey: string;
@@ -4142,43 +4247,6 @@ export interface PendingSwap {
 export declare const PENDING_SWAP_PRUNE_REASONS: readonly ['expired', 'invalid_unique_key', 'chain_rejected', 'unconfirmable'];
 /** One member of {@link PENDING_SWAP_PRUNE_REASONS}. */
 export type PendingSwapPruneReason = (typeof PENDING_SWAP_PRUNE_REASONS)[number];
-/**
- * What to do with a pending swap after confirming it failed (the answer of
- * {@link pendingSwapFateFor}).
- *
- * - `forget`: the chain REFUSED the trade, so it did not happen. Drop it AND tell the user.
- * - `forget_quietly`: the confirmation can never succeed (the key is refused: `invalid_input`).
- *   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.
- */
-export declare const PENDING_SWAP_FATES: readonly ['forget', 'forget_quietly', 'keep'];
-/** One member of {@link PENDING_SWAP_FATES}. */
-export type PendingSwapFate = (typeof PENDING_SWAP_FATES)[number];
-/**
- * {@link pendingSwapFateFor} from an outcome the app already holds (for example the
- * `classifyFailure(error).outcome` it stored on its own failure wrapper). An outcome this SDK
- * version does not know (a newer SDK at run time) is `keep`: never forget what may have happened.
- */
-export declare function pendingSwapFateOfOutcome(outcome: FailureOutcome): PendingSwapFate;
-/**
- * The fate of a queued swap whose confirmation (`confirmAppliedTrade`) just failed with `error`,
- * from the SDK's classification alone: `forget` for a chain rejection (`rejected`), `forget_quietly`
- * for a key that can never be confirmed (`invalid_input`), `keep` for every other outcome
- * (`unknown`, `not_queued`, `not_sent`, `transient`) and for any value the SDK cannot judge. It
- * accepts an SDK error or a plain-object view of one (see `FailureView`). It replaces the wallet's
- * `pendingSwapActionFor` and frontend_v2's `confirmationStanceOf`.
- *
- * @example
- * ```ts
- * try {
- *   await confirmAppliedTrade(client, swap);
- * } catch (error) {
- *   if ((await store.settle(swap.uniqueKey, error)) === 'forget') tellTheUserItFailed();
- * }
- * ```
- */
-export declare function pendingSwapFateFor(error: unknown): PendingSwapFate;
 /** A pending swap the store dropped, and why. */
 export interface PrunedPendingSwap {
   swap: PendingSwap;
@@ -4468,6 +4536,7 @@ export declare function tokenClassDollarKey(token: Record<string, unknown> | nul
 export declare function canonicalDecimalString(value: string | number): string;
 //#endregion
 //#region src/utils/eip712.d.ts
+/** EIP-712 `types`: each struct name mapped to its ordered `{ name, type }` fields. */
 type EIP712Types = Record<string, Array<{
   name: string;
   type: string;
@@ -4558,8 +4627,9 @@ type RequestTradeInput = {
 /**
  * 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
@@ -4824,8 +4894,14 @@ export declare function isConfirmationTimeout(error: unknown): boolean;
  */
 export declare function isFetchTransportFailure(error: unknown): boolean;
 //#endregion
-//#region src/utils/failure_classification.d.ts
-/** The result of {@link classifyFailure}. */
+//#region src/utils/classification.d.ts
+/**
+ * The classification values an app shell may need on their own: what an outcome allows. This module
+ * is deliberately tiny and imports nothing at run time (the outcome type is erased), so an app
+ * shell that builds `classification('not_sent')` or reads `NOT_QUEUED_FINAL` loads a few hundred
+ * bytes, not the table of error codes that lives with `classifyFailure`.
+ */
+/** The result of `classifyFailure`. */
 export interface FailureClassification {
   readonly outcome: FailureOutcome;
   /**
@@ -4845,10 +4921,10 @@ export interface FailureClassification {
  * 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
@@ -4874,6 +4950,105 @@ export declare const NOT_QUEUED_FINAL: Readonly<FailureClassification>;
  * sent (a quote refresh, a balance read), so nothing is pending and a repeat is safe.
  */
 export declare function notSentClassification(): FailureClassification;
+//#endregion
+//#region src/utils/failure_classification.d.ts
+/**
+ * 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
+ * code cannot be added without one.
+ *
+ * A failure BEFORE the request left (`error.phase === 'pre_send'`, `isPreSendError`) can never be
+ * `unknown` or `rejected`: it is `invalid_input` (the input has to change) or `not_sent` (nothing
+ * was transmitted; a repeat is safe). Every app-supplied callback the SDK calls before it sends
+ * (the signer, the key provider, a token resolver) has its failure wrapped into such an error
+ * (`SIGNING_FAILED`, `KEY_PROVIDER_FAILED`, `TOKEN_RESOLUTION_FAILED`, the original as `cause`),
+ * so an app NEVER needs an error class of its own to say "nothing was sent": a locked wallet,
+ * a declined signature and a failed lookup all arrive as `not_sent`, retryable.
+ *
+ * It accepts a `GSwapSDKError` or a plain-object VIEW of one ({@link FailureView}: `{ code,
+ * params?, status?, uniqueKey?, ... }`, the shape of the wrapper an app builds from an SDK error;
+ * `toFailureView` reads any value), and decides from the same fields, so an app does not need to
+ * keep the original error to ask. `{ afterQueued: true }` says the write is already queued (the
+ * step being classified is a confirmation): `retryable` is then always `false`.
+ *
+ * Anything that is not an SDK error or such a view, or a view whose `code` the catalog does not
+ * define, is `{ outcome: 'unknown', retryable: false }`: the SDK
+ * cannot say what happened, and refusing Retry is the safe answer. That is only what escapes AFTER
+ * the request left (an app requestor that rejects with its own error, a callback of yours that
+ * throws once bytes were sent). An error your own code raises BEFORE it calls the SDK says so
+ * itself: give it a code of its own and `outcome` (`{ code: 'POSITION_STALE', outcome: 'not_sent'
+ * }`), and the SDK answers with that outcome's classification and `mayHaveBeenQueued` is `false`.
+ * The declared `outcome` is read only for a code the catalog does not define.
+ *
+ * A failure is a WRITE's unless it states `write: false` (`GSwapSDKError.write`, set for every
+ * SDK read): see {@link FailureView}. A view that lost its `uniqueKey` is therefore still judged as
+ * a write (a 5xx stays `unknown`), never as a retryable read.
+ *
+ * To learn that a failure came from the dark (shadow) path, read `error.shadow` (a typed field of
+ * every `GSwapSDKError`) or call `isShadowError(error)`, which also covers a non-SDK object that
+ * escaped `swapShadow` / `submitSwapShadow` / `ChainGateway.submitShadow`. The classification is
+ * the same as on the public path; an app that withholds Retry or a public fallback after a dark
+ * swap applies that policy on top of `retryable`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '100' });
+ * } catch (error) {
+ *   const { outcome, retryable } = classifyFailure(error);
+ *   if (outcome === 'unknown') keepPendingAndConfirm(error); // never a second swap
+ *   else if (retryable) offerRetry(); // a new request under a fresh key
+ * }
+ * ```
+ */
+export declare function classifyFailure(error: unknown, options?: ClassifyFailureOptions): FailureClassification;
+/** Options of {@link classifyFailure}. */
+export interface ClassifyFailureOptions {
+  /**
+   * The write is ALREADY queued (the gateway acknowledged it with this `uniqueKey`), and what is
+   * being classified is a later step: confirming it, reading its apply result. Whatever the
+   * outcome, `retryable` is then `false`: a NEW request would be a second trade, so the app
+   * confirms the same key (or forgets it) and never offers "Try again". `outcome` is unchanged.
+   *
+   * The one exception is `rejected`: the chain evaluated the queued write and refused it (an
+   * apply result of `Status: 0`, `CHAIN_REJECTED`; a 422 dispatch). That PROVES it was not
+   * applied, so a new request under a fresh key cannot make a second trade, and `retryable`
+   * keeps the answer it has without this option (`true`). Every outcome that does not prove
+   * "not applied" (`unknown`, `transient`, `not_queued`, ...) is `false`.
+   */
+  afterQueued?: boolean | undefined;
+}
+/**
+ * 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
+ * the request left, an acknowledgement that proves nothing, a gateway 409 or 5xx, a failed
+ * confirmation). The app must keep `error.uniqueKey` and confirm it, and must NOT submit again
+ * under a fresh key. Every other outcome (`rejected`, `not_queued`, `not_sent`, `invalid_input`,
+ * `transient`) proves the write is not pending.
+ *
+ * A value the SDK cannot judge (an app requestor's own rejection after the request left) is
+ * `unknown` too, so it is `true`; handle errors your own code raised BEFORE calling the SDK first.
+ * Meant for the catch of a write; a read never has a pending key to keep.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '100' });
+ * } catch (error) {
+ *   if (mayHaveBeenQueued(error)) keepPendingAndConfirm(error);
+ * }
+ * ```
+ */
+export declare function mayHaveBeenQueued(error: unknown): boolean;
+//#endregion
+//#region src/utils/failure_guards.d.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
@@ -4940,72 +5115,24 @@ export type RelayableCode = 'GATEWAY_REPORTED_ERROR' | 'METHOD_NOT_ALLOWED' | 'S
  */
 export declare function isUninterpretedAnswer(error: unknown): boolean;
 /**
- * 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
- * code cannot be added without one.
- *
- * A failure BEFORE the request left (`error.phase === 'pre_send'`, `isPreSendError`) can never be
- * `unknown` or `rejected`: it is `invalid_input` (the input has to change) or `not_sent` (nothing
- * was transmitted; a repeat is safe). Every app-supplied callback the SDK calls before it sends
- * (the signer, the key provider, a token resolver) has its failure wrapped into such an error
- * (`SIGNING_FAILED`, `KEY_PROVIDER_FAILED`, `TOKEN_RESOLUTION_FAILED`, the original as `cause`),
- * so an app NEVER needs an error class of its own to say "nothing was sent": a locked wallet,
- * a declined signature and a failed lookup all arrive as `not_sent`, retryable.
- *
- * It accepts a `GSwapSDKError` or a plain-object VIEW of one ({@link FailureView}: `{ code,
- * params?, status?, uniqueKey?, ... }`, the shape of the wrapper an app builds from an SDK error;
- * `toFailureView` reads any value), and decides from the same fields, so an app does not need to
- * keep the original error to ask. `{ afterQueued: true }` says the write is already queued (the
- * step being classified is a confirmation): `retryable` is then always `false`.
- *
- * Anything that is not an SDK error or such a view, or a view whose `code` the catalog does not
- * define, is `{ outcome: 'unknown', retryable: false }`: the SDK
- * cannot say what happened, and refusing Retry is the safe answer. That is only what escapes AFTER
- * the request left (an app requestor that rejects with its own error, a callback of yours that
- * throws once bytes were sent). An error your own code raises BEFORE it calls the SDK says so
- * itself: give it a code of its own and `outcome` (`{ code: 'POSITION_STALE', outcome: 'not_sent'
- * }`), and the SDK answers with that outcome's classification and `mayHaveBeenQueued` is `false`.
- * The declared `outcome` is read only for a code the catalog does not define.
+ * 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.
  *
- * A failure is a WRITE's unless it states `write: false` (`GSwapSDKError.write`, set for every
- * SDK read): see {@link FailureView}. A view that lost its `uniqueKey` is therefore still judged as
- * a write (a 5xx stays `unknown`), never as a retryable read.
- *
- * To learn that a failure came from the dark (shadow) path, read `error.shadow` (a typed field of
- * every `GSwapSDKError`) or call `isShadowError(error)`, which also covers a non-SDK object that
- * escaped `swapShadow` / `submitSwapShadow` / `ChainGateway.submitShadow`. The classification is
- * the same as on the public path; an app that withholds Retry or a public fallback after a dark
- * swap applies that policy on top of `retryable`.
+ * 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
- * try {
- *   await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '100' });
- * } catch (error) {
- *   const { outcome, retryable } = classifyFailure(error);
- *   if (outcome === 'unknown') keepPendingAndConfirm(error); // never a second swap
- *   else if (retryable) offerRetry(); // a new request under a fresh key
- * }
+ * const key = chainErrorKeyOf(error);
+ * if (key === 'NOT_ENOUGH_LIQUIDITY') showTooThin(); else showGeneric(error);
  * ```
  */
-export declare function classifyFailure(error: unknown, options?: ClassifyFailureOptions): FailureClassification;
-/** Options of {@link classifyFailure}. */
-export interface ClassifyFailureOptions {
-  /**
-   * The write is ALREADY queued (the gateway acknowledged it with this `uniqueKey`), and what is
-   * being classified is a later step: confirming it, reading its apply result. Whatever the
-   * outcome, `retryable` is then `false`: a NEW request would be a second trade, so the app
-   * confirms the same key (or forgets it) and never offers "Try again". `outcome` is unchanged.
-   *
-   * The one exception is `rejected`: the chain evaluated the queued write and refused it (an
-   * apply result of `Status: 0`, `CHAIN_REJECTED`; a 422 dispatch). That PROVES it was not
-   * applied, so a new request under a fresh key cannot make a second trade, and `retryable`
-   * keeps the answer it has without this option (`true`). Every outcome that does not prove
-   * "not applied" (`unknown`, `transient`, `not_queued`, ...) is `false`.
-   */
-  afterQueued?: boolean | undefined;
-}
+export declare function chainErrorKeyOf(error: unknown): string | undefined;
 /**
  * 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
@@ -5023,28 +5150,52 @@ export interface ClassifyFailureOptions {
  * ```
  */
 export declare function isNoMarket(error: unknown): boolean;
+//#endregion
+//#region src/utils/class_key.d.ts
 /**
- * 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
- * the request left, an acknowledgement that proves nothing, a gateway 409 or 5xx, a failed
- * confirmation). The app must keep `error.uniqueKey` and confirm it, and must NOT submit again
- * under a fresh key. Every other outcome (`rejected`, `not_queued`, `not_sent`, `invalid_input`,
- * `transient`) proves the write is not pending.
+ * 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`.
+ */
+/** Return the `$`-joined composite key used by GalaChain object identities. */
+export declare function compositeKeyOf(token: GalaChainTokenClassKey): string;
+/**
+ * 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
+ * (`undefined`, `null`, a number, an array) is `undefined`, so it is safe on untrusted input (a
+ * stored token, a URL parameter, a wallet row) without a `try`/`catch`.
  *
- * A value the SDK cannot judge (an app requestor's own rejection after the request left) is
- * `unknown` too, so it is `true`; handle errors your own code raised BEFORE calling the SDK first.
- * Meant for the catch of a write; a read never has a pending key to keep.
+ * Use {@link tryParseCompositeKey} instead when only the `$` form is valid input.
  *
  * @example
  * ```ts
- * try {
- *   await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '100' });
- * } catch (error) {
- *   if (mayHaveBeenQueued(error)) keepPendingAndConfirm(error);
- * }
+ * const key = tryParseTokenClassKey(row.compositeKey);
+ * if (key === undefined) return failClosed(); // no class is known: never invent one from a symbol
  * ```
  */
-export declare function mayHaveBeenQueued(error: unknown): boolean;
+export declare function tryParseTokenClassKey(value: unknown): GalaChainTokenClassKey | undefined;
+/**
+ * Parses a `$`-joined composite key (`Collection$Category$Type$AdditionalKey`, what
+ * {@link compositeKeyOf} writes) and nothing else, or `undefined`. It is {@link tryParseTokenClassKey}
+ * for a string that may ONLY be in the `$` form: a key that contains `|` is NOT read as the pipe
+ * form here (it stays part of a segment), and only a string is accepted. The split is from the
+ * right, so a collection that itself contains `$` (production's `$GMUSIC`, stage's
+ * `$GMUSIC_TEST1`) stays whole; `'GALA'`, `'GALA$Unit$none'`, `'ETIME$$$'`, `'GALA$Unit$none$'` and
+ * `'$$$$'` are `undefined`.
+ *
+ * It replaces an app's own `parseCompositeKey(key): Components | null` (`?? null`), which had
+ * exactly these semantics.
+ *
+ * @example
+ * ```ts
+ * tryParseCompositeKey('$GMUSIC_TEST1$Unit$none$none')?.collection; // '$GMUSIC_TEST1'
+ * tryParseCompositeKey('GALA$Unit$none'); // undefined
+ * ```
+ */
+export declare function tryParseCompositeKey(value: unknown): GalaChainTokenClassKey | undefined;
 //#endregion
 //#region src/utils/shadow_errors.d.ts
 /**
@@ -5065,7 +5216,71 @@ export declare function mayHaveBeenQueued(error: unknown): boolean;
  */
 export declare function isShadowError(value: unknown): boolean;
 //#endregion
-//#region src/utils/ticks.d.ts
+//#region src/utils/tick_align.d.ts
+/**
+ * {@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.
+ *
+ * @example
+ * ```ts
+ * alignTickDownOrNaN(-61, 60); // -120: it floors, it does not truncate toward zero
+ * alignTickDownOrNaN(100, 0); // NaN
+ * ```
+ */
+export declare function alignTickDownOrNaN(tick: number, spacing: number): number;
+/**
+ * {@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}.
+ */
+export declare function alignTickUpOrNaN(tick: number, spacing: number): number;
+//#endregion
+//#region src/utils/tick_range.d.ts
+/**
+ * Whether a pool's current tick lies inside a position's range, by the contract's own rule. This
+ * module imports nothing, so an app shell (a position badge, a filter) pays for a few dozen bytes.
+ */
+/** A tick as the chain and the backends write it: a number, or the decimal string of one. */
+type TickInput = number | string;
+/**
+ * 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
+ * ```
+ */
+export declare function isTickInRange(currentTick: TickInput, tickLower: TickInput, tickUpper: TickInput): boolean;
+//#endregion
+//#region src/utils/tick_math.d.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. */
 export declare const GC_MIN_TICK = -887272;
 /** Maximum tick supported by GalaChainDex. */
@@ -5084,8 +5299,26 @@ export declare function sqrtPriceToTick(sqrtPrice: BigNumber.Value): number;
  * the last digits of a double: that expression multiplies in floating point first).
  */
 export declare function tickToPrice(tick: number): BigNumber;
+/**
+ * {@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);
+ * ```
+ */
+export declare function isSqrtPriceInRange(sqrtPrice: BigNumber.Value, tickLower: TickInput, tickUpper: TickInput): boolean;
 /** How {@link tickFromPrice} turns the exact logarithm into an integer tick. */
-export interface TickFromPriceOptions {
+interface TickFromPriceOptions {
   /**
    * `'floor'` (default): the greatest tick whose price is no greater than `price`, which is how
    * the contract places a price. `'nearest'`: the closest tick, a half rounding away from zero.
@@ -5100,6 +5333,14 @@ export interface TickFromPriceOptions {
  * is not positive and finite.
  */
 export declare function tickFromPrice(price: BigNumber.Value, options?: TickFromPriceOptions): number;
+//#endregion
+//#region src/utils/ticks.d.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. */
 export declare function alignTickDown(tick: number, spacing: number): number;
 /** Align a tick up to the nearest multiple of a positive spacing. */
@@ -5147,12 +5388,55 @@ export declare function frameSlot0(slot0: {
 export declare function isValidUniqueKey(uniqueKey: unknown): uniqueKey is string;
 //#endregion
 //#region src/utils/validation.d.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`.
+ */
 export declare function validateNumericAmount(amount: NumericAmount, parameterName: string, allowZero?: boolean): void;
+/**
+ * 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`.
+ */
 export declare function validatePriceValues(spotPrice: NumericAmount, lowerPrice: NumericAmount, upperPrice: NumericAmount): void;
+/**
+ * Validates a token's decimals: a non-negative integer.
+ *
+ * @throws GSwapSDKError `INVALID_TOKEN_DECIMALS` (`params.field` is `parameterName`).
+ */
 export declare function validateTokenDecimals(decimals: number, parameterName: string): void;
+/**
+ * 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`.
+ */
 export declare function validateTickRange(tickLower: number, tickUpper: number): void;
+/**
+ * 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).
+ */
 export declare function validateFee(fee: number): asserts fee is FEE_TIER;
+/**
+ * Validates a tick spacing: a positive integer.
+ *
+ * @throws GSwapSDKError `INVALID_TICK_SPACING`.
+ */
 export declare function validateTickSpacing(tickSpacing: number): void;
+/**
+ * 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).
+ */
 export declare function validateWalletAddress(address?: string): asserts address is string;
 /**
  * True when `symbol` is acceptable to propose into the trading-symbol registry: ASCII letters and
@@ -5221,5 +5505,5 @@ export declare function isWalletUserRejection(value: unknown): boolean;
  */
 export declare function walletDeclineCode(value: unknown): number | string | undefined;
 //#endregion
-export type { AddLiquidityInput, ConfirmationState, CreatePoolInput, EIP712DomainValue, EIP712Types, EntryParse, FailureOutcome, FailureView, GSwapErrorCode, GSwapErrorParams, GSwapErrorPhase, GSwapErrorShape, InvalidEntry, InvalidEntryHandler, InvalidPrivateKeyReason, PersonalSignChainDtoPayload, PoolPositionInput, PrivateKeyInput, RemoveLiquidityInput, RequestTradeInput, SigningFailureReason, SubmissionOutcomeUnknownReason, TypedDataPayload, V2WriteMethod };
+export type { AddLiquidityInput, ConfirmationState, CreatePoolInput, EIP712DomainValue, EIP712Types, EntryParse, FailureOutcome, FailureView, GSwapErrorCode, GSwapErrorParams, GSwapErrorPhase, GSwapErrorShape, InvalidEntry, InvalidEntryHandler, InvalidPrivateKeyReason, PersonalSignChainDtoPayload, PoolPositionInput, PrivateKeyInput, RemoveLiquidityInput, RequestTradeInput, SigningFailureReason, SubmissionOutcomeUnknownReason, TickFromPriceOptions, TickInput, TypedDataPayload, V2WriteMethod };
 //# sourceMappingURL=index.d.cts.map