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

package/dist/index.d.cts

@@ -1,4 +1,37 @@
 import BigNumber from "bignumber.js";
+//#region src/types/confirm_options.d.ts
+/**
+ * Controls timeout, polling and cancellation of confirmation.
+ *
+ * - `timeoutMs` (default 60 000): overall deadline, counted from the `confirm()` call and
+ *   including `initialDelayMs`. At least one read is always made.
+ * - `pollIntervalMs` (default 2 000, minimum 500): base interval, doubled with jitter up to 8 s.
+ * - `initialDelayMs`: wait before the first read. Defaults to 3 000 for a queued RequestTrade
+ *   (the AutoApplier needs a few seconds) and 0 for liquidity writes (already executed).
+ * - `signal`: aborts the wait or an in-flight read. Confirmation then throws an error with code
+ *   `CONFIRMATION_ABORTED`; nothing is learned about the outcome, so confirm the same
+ *   `uniqueKey` again later.
+ */
+export interface ConfirmOptions {
+  timeoutMs?: number | undefined;
+  pollIntervalMs?: number | undefined;
+  initialDelayMs?: number | undefined;
+  signal?: AbortSignal | undefined;
+}
+//#endregion
+//#region src/types/http_requestor.d.ts
+type FetchReturnValue = Awaited<ReturnType<typeof fetch>>;
+interface HTTPResponse {
+  ok: FetchReturnValue['ok'];
+  status: FetchReturnValue['status'];
+  json: FetchReturnValue['json'];
+  text: FetchReturnValue['text'];
+  headers?: {
+    get(name: string): string | null;
+  } | Record<string, string | undefined>;
+}
+type HttpRequestor = (uri: string, options?: Parameters<typeof fetch>[1]) => Promise<HTTPResponse>;
+//#endregion
 //#region src/types/v2_results.d.ts
 /** Pool metadata returned by GalaChainDex. */
 export interface PoolInfo {
@@ -15,19 +48,26 @@ export interface PoolInfo {
   isPrivate?: boolean;
   flippedFromRequest?: boolean;
 }
-/** Pool summary returned by the backend pool-list route. */
+/**
+ * Pool summary returned by the backend pool-list route. Only the identity (`token0`, `token1`,
+ * `poolRef`) and `fee` are guaranteed; a row that lacks any other field is still a usable row, as
+ * the apps that list pools treat it.
+ */
 export interface PoolListInfo {
-  contractVersion: 'v2';
+  contractVersion?: 'v2' | undefined;
   token0: string;
   token1: string;
   token0CompositeKey?: string | undefined;
   token1CompositeKey?: string | undefined;
+  /** Registry image URL of token0 resolved by the backend; empty when the token is unregistered. */
+  token0Image?: string | undefined;
+  token1Image?: string | undefined;
   fee: number;
-  poolName: string;
+  poolName?: string | undefined;
   poolRef: string;
-  tickSpacing: number;
-  protocolFees: number;
-  tradingFees: number;
+  tickSpacing?: number | undefined;
+  protocolFees?: number | undefined;
+  tradingFees?: number | undefined;
   creator?: string | undefined;
   price?: string | undefined;
   sqrtPrice?: string | undefined;
@@ -103,6 +143,9 @@ export interface Position {
   token1Symbol: string;
   token0CompositeKey?: string;
   token1CompositeKey?: string;
+  /** Registry image URL of token0 resolved by the backend; empty when the token is unregistered. */
+  token0Image?: string;
+  token1Image?: string;
   fee: number;
   tickLower: number;
   tickUpper: number;
@@ -209,25 +252,189 @@ export interface ChainSubmissionResult {
   uniqueKey?: string;
 }
 //#endregion
-//#region src/types/http_requestor.d.ts
-type FetchReturnValue = Awaited<ReturnType<typeof fetch>>;
-interface HTTPResponse {
-  ok: FetchReturnValue['ok'];
-  status: FetchReturnValue['status'];
-  json: FetchReturnValue['json'];
-  text: FetchReturnValue['text'];
-  headers?: {
-    get(name: string): string | null;
-  } | Record<string, string | undefined>;
+//#region src/types/wire.d.ts
+/**
+ * How the SDK writes a read request on the wire. The defaults suit a server-side caller; an app
+ * that already issues the same requests from its own HTTP stack (frontend_v2, the Gala Wallet)
+ * sets these so the SDK's requests are indistinguishable from the ones it replaces.
+ *
+ * One object, carried by {@link ChainGateway}, so every service built on a gateway (symbols,
+ * pools, positions, quoting) shares it without per-service plumbing.
+ */
+export interface WireOptions {
+  /**
+   * Query-string encoding of GET parameters.
+   *
+   * - `'standard'` (default): `URLSearchParams` (`application/x-www-form-urlencoded`), where `$`
+   *   and `|` become `%24` and `%7C`.
+   * - `'readable'`: keeps `$ | : ,` and the RFC 3986 sub-delimiters `! ' ( ) *` unescaped, so a
+   *   composite key such as `GALA$Unit$none$none` or `client|abc` reads as written. Everything
+   *   that would change a query's meaning (`& = # % +`, space, non-ASCII, controls) is still
+   *   percent-encoded (a space is `+`), so the server decodes exactly the value that was passed.
+   *   This is the text frontend_v2's `formatUrl` produces for every value it can represent.
+   */
+  queryEncoding?: 'standard' | 'readable' | undefined;
+  /**
+   * The `User-Agent` request header. Defaults to `GalaChain-SDK/<version>`; `false` omits it
+   * (browsers forbid setting it, and an app whose own requests carry none can match them).
+   * `Content-Type` is only ever sent with a request body, never on a GET.
+   */
+  userAgent?: string | false | undefined;
+  /**
+   * Extra request headers for every read, sent after (and so able to replace) the defaults above;
+   * for example axios' `Accept: application/json, text/plain, *\/*`, so a request is the same as
+   * the one an app's own HTTP stack used to send.
+   */
+  headers?: Record<string, string> | undefined;
 }
-type HttpRequestor = (uri: string, options?: Parameters<typeof fetch>[1]) => Promise<HTTPResponse>;
+//#endregion
+//#region src/types/token.d.ts
+export interface GalaChainTokenClassKey {
+  collection: string;
+  category: string;
+  type: string;
+  additionalKey: string;
+}
+//#endregion
+//#region src/classes/gswap_sdk_error.d.ts
+/** Error raised by the SDK for validation, gateway, chain, or transaction failures. */
+export declare class GSwapSDKError extends Error {
+  readonly code: string;
+  readonly details?: Record<string, unknown> | undefined;
+  readonly chainMessage: string | undefined;
+  readonly retryAfterMs: number | undefined;
+  /** The HTTP status of the response that caused this error, when there was one. */
+  readonly status: number | undefined;
+  /**
+   * The response body parsed as JSON, when the failing response had one; `undefined` for a body
+   * that was not JSON (see {@link bodyText}). Never part of {@link message}.
+   */
+  readonly body: unknown;
+  /**
+   * The raw text of a failing response whose body was NOT JSON (a proxy's HTML 502, a WAF page,
+   * an empty body). It is kept here for diagnostics and is never copied into {@link message} or
+   * {@link userMessage}, so it cannot reach a user interface by accident.
+   */
+  readonly bodyText: string | undefined;
+  constructor(message: string, code: string, details?: Record<string, unknown> | undefined, chainMessage?: string, retryAfterMs?: number);
+  /**
+   * A message that is safe to show a user as is: the server's own message when it sent one
+   * (a gateway or chain rejection), a neutral line naming the status for an HTTP failure with no
+   * readable answer, and otherwise {@link message}. Apps that word these differently (a
+   * "network busy" line for a 502, say) branch on {@link code} and {@link status} instead.
+   */
+  get userMessage(): string;
+  /**
+   * True when the failure means "that market, pool or position does not exist" rather than
+   * "something went wrong": an HTTP 404, a pair with no pool at any fee tier
+   * (`NO_POOL_AVAILABLE`), or a token the DEX contract has no trading symbol for
+   * (`UNKNOWN_TOKEN`). A pool that exists but is too thin (`INSUFFICIENT_LIQUIDITY`) is NOT
+   * not-found.
+   */
+  get notFound(): boolean;
+  /** Create the standard missing-signer error. */
+  static noSignerError(): GSwapSDKError;
+  /** Create the error used when confirming a position write without a configured wallet address. */
+  static noWalletAddressError(): GSwapSDKError;
+  /**
+   * Create the error used when no pool can quote the requested pair. `source` is the backend
+   * answer that said so; its status, body and message are kept (the message as `chainMessage`,
+   * so {@link userMessage} is the server's own wording).
+   */
+  static noPoolAvailableError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number, source?: GSwapSDKError): GSwapSDKError;
+  /** Create the error used when a pool lacks liquidity for a quote. `source` as for {@link noPoolAvailableError}. */
+  static insufficientLiquidityError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number, source?: GSwapSDKError): GSwapSDKError;
+  /**
+   * The message the server put in a JSON answer (`message`, or `error.Message`), when this error
+   * came from an HTTP response that had one.
+   */
+  get serverMessage(): string | undefined;
+  /** Convert a chain-gateway bounce into a typed SDK error. */
+  static fromGatewayBounce(code: string, message: string, status: number, retryAfterMs?: number): GSwapSDKError;
+  /** Convert a GalaChain `Status: 0` response into a typed SDK error. */
+  static fromChainError(errorKey: string, message: string, details?: Record<string, unknown>): GSwapSDKError;
+  /** Create the error used when a token is not registered by the current DEX contract. */
+  static unknownTokenError(token: GalaChainTokenClassKey | string): GSwapSDKError;
+  /** Create the error used when apply-results confirmation does not arrive in time. */
+  static confirmationTimeoutError(uniqueKey: string, cause?: unknown): GSwapSDKError;
+  /** Convert an unexpected HTTP response into an SDK error. */
+  static fromErrorResponse(url: string, response: HTTPResponse): Promise<GSwapSDKError>;
+}
+/** Narrow an object property without trusting a cast at a network boundary. */
+export declare function getObjectProperty(value: unknown, property: string): Record<string, unknown> | undefined;
+/** Read a string property from an unknown object. */
+export declare function getStringProperty(value: unknown, property: string): string | undefined;
+/** Parse a response body, preserving non-JSON text for error reporting. */
+export declare function parseJson(text: string): unknown;
+//#endregion
+//#region src/classes/apply_results.d.ts
+/**
+ * The outcome of a queued RequestTrade that could not be delivered as an {@link AppliedTrade}.
+ * `code` says why:
+ *
+ * - `CONFIRMATION_TIMEOUT`: no terminal result before the deadline. The trade may still apply;
+ *   confirm the same `uniqueKey` again later and never resubmit.
+ * - `CONFIRMATION_ABORTED`: the caller's `signal` aborted. Nothing is known about the outcome.
+ * - `CONFIRMATION_FAILED`: the apply-results read itself failed (malformed key or body, a
+ *   non-retryable HTTP status). The outcome is unknown.
+ * - anything else: the chain REJECTED the trade; `code` is the chain `ErrorKey` (or
+ *   `CHAIN_ERROR`) and `chainMessage` is its message, which is also `message`.
+ *
+ * `details` always carries `uniqueKey` and, where known, `requestTransactionId`,
+ * `applyTransactionId`, `blockNumber`, `status`, `body`, `url` and the last transport `cause`.
+ */
+export declare class AppliedTradeError extends GSwapSDKError {
+  constructor(message: string, code: string, details?: Record<string, unknown>, chainMessage?: string);
+}
+/** The transport and backend a confirmation reads from. */
+export interface ApplyResultsClient {
+  /** Swap backend origin, e.g. `https://dex-backend-prod1.defi.gala.com` (no trailing path). */
+  dexBackendBaseUrl: string;
+  /** Defaults to the global `fetch`. */
+  httpRequestor?: HttpRequestor | undefined;
+  /** Per-read timeout in milliseconds (default 30 000). */
+  requestTimeoutMs?: number | undefined;
+  /** Request headers of the poll (`userAgent`, `headers`); see {@link WireOptions}. */
+  wire?: WireOptions | undefined;
+}
+/** What identifies the queued trade to confirm. */
+export interface AppliedTradeInput {
+  uniqueKey: string;
+  /** The transaction id of the queued request, carried through to the result; `null` if unknown. */
+  requestTransactionId: string | null;
+}
+/**
+ * Polls `GET /v1/chain/apply-results/{uniqueKey}?channel=asset&contract=dex-contract` until the
+ * queued RequestTrade reaches a terminal state.
+ *
+ * Pacing: wait `initialDelayMs` (default 3 s), then read; on 404, 429, 500, 502, 503, 504 or a
+ * transport error wait with jittered exponential backoff (`pollIntervalMs` doubling to 8 s,
+ * `Retry-After` honored as seconds or an HTTP date) until `timeoutMs`. Any other status is
+ * terminal. At least one read is always made.
+ *
+ * @returns The applied trade.
+ * @throws AppliedTradeError - see its documentation for every `code`.
+ * @example
+ * ```ts
+ * const applied = await confirmAppliedTrade(
+ *   { dexBackendBaseUrl: 'https://dex-backend-prod1.defi.gala.com' },
+ *   { uniqueKey, requestTransactionId: null },
+ *   { initialDelayMs: 0, timeoutMs: 60_000, signal: controller.signal },
+ * );
+ * ```
+ */
+export declare function confirmAppliedTrade(client: ApplyResultsClient, input: AppliedTradeInput, options?: ConfirmOptions): Promise<AppliedTrade>;
 //#endregion
 //#region src/classes/http_client.d.ts
 declare class HttpClient {
   private readonly httpRequestor;
   private readonly timeoutMs;
-  /** Create an HTTP client around fetch or an injected requestor. */
-  constructor(httpRequestor?: HttpRequestor, timeoutMs?: number);
+  private readonly wire;
+  /**
+   * Create an HTTP client around fetch or an injected requestor. `wire` selects the query
+   * encoding and the `User-Agent` (see {@link WireOptions}).
+   */
+  constructor(httpRequestor?: HttpRequestor, timeoutMs?: number, wire?: WireOptions);
   private sendRequest;
   /** Send a JSON POST request and decode its response. */
   sendPostRequest<TReturnType>(baseUrl: string, basePath: string, endpoint: string, body: unknown): Promise<TReturnType>;
@@ -262,96 +469,552 @@ export declare class Assets {
   getUserAssets(ownerAddress: string, page?: number, limit?: number): Promise<UserAssetsResult>;
 }
 //#endregion
-//#region src/classes/submitted_transaction.d.ts
-/** Result of one position-confirmation poll. */
-export type PositionConfirmationResult = {
-  confirmed: true;
-  position: Position | null;
-} | {
-  confirmed: false;
-  position?: Position | null;
+//#region src/classes/signers.d.ts
+/** The signing schemes supported by the Gala Wallet signer. */
+export type GalaWalletScheme = 'native' | 'personal-sign';
+/** The request surface used by an EIP-1193 browser wallet. */
+export interface BrowserWalletProvider {
+  request(args: {
+    method: string;
+    params?: unknown[];
+  }): Promise<unknown>;
+}
+type SignedDto<T extends Record<string, unknown>> = T & {
+  signature: string;
 };
-/** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
-export declare class SubmittedTransaction<TConfirmation = AppliedTrade | Position | null> {
-  readonly method: string;
-  readonly uniqueKey: string;
-  readonly transactionId: string | null;
-  readonly blockNumber: number | null;
-  readonly mode: 'sync' | 'queued';
-  /** The synchronous gateway result, or `undefined` when `mode === 'queued'`. */
-  readonly result: unknown;
-  private readonly backendBaseUrl;
-  private readonly requestor;
-  private readonly requestTimeoutMs;
-  private readonly positionConfirmation;
-  /** Construct a submitted transaction from a successful gateway response.
+/**
+ * A signer for complete GalaChain write bodies.
+ *
+ * Implementations return the DTO fields together with the signature that belongs in the
+ * gateway request body. Signer identity is recovered from that signature; implementations do
+ * not add signer hints, typed-data metadata, or a domain.
+ */
+export interface GalaChainSigner {
+  /**
+   * Signs a DTO for a named GalaChain contract method.
    *
    * @example
-   * ```ts
-   * const transaction = new SubmittedTransaction({
-   *   method: 'RequestTrade', mode: 'queued', uniqueKey: 'swap-1',
-   *   transactionId: 'request-tx', result: undefined,
-   *   dexBackendBaseUrl: 'https://dex.example', httpRequestor,
-   * });
+   * ```typescript
+   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
    * ```
    */
-  constructor(options: {
-    method: string;
-    uniqueKey: string;
-    transactionId: string | null;
-    mode: 'sync' | 'queued';
-    result: unknown;
-    dexBackendBaseUrl: string;
-    httpRequestor: HttpRequestor;
-    blockNumber?: number | null | undefined;
-    requestTimeoutMs?: number | undefined;
-    positionConfirmation?: ((signal: AbortSignal) => Promise<PositionConfirmationResult>) | undefined;
-  });
-  /** Confirm a queued RequestTrade or prove the affected position for a liquidity write.
-   *
-   * For RequestTrade, calling this method is required to learn the outcome: the queued
-   * acknowledgement proves acceptance, not execution.
+  signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
+}
+/**
+ * The `0x`-prefixed Ethereum address a Gala account is signed by, or `undefined` when the account
+ * names no key (a `client|` alias or a bare GalaChain id is not derivable from a key). Accepts
+ * `0x` plus 40 hex digits and `eth|` plus 40 hex digits, with or without `0x`; the caller's casing
+ * is kept. For {@link LazyPrivateKeySignerOptions.expectedAddress}, which should only be set for
+ * an account whose key can be checked.
+ *
+ * @example
+ * ```ts
+ * createLazyPrivateKeySigner(getKey, { expectedAddress: ethereumAddressOfAccount(account) });
+ * ```
+ */
+export declare function ethereumAddressOfAccount(account: string): string | undefined;
+/**
+ * A GalaChain native signer backed by a secp256k1 private key.
+ *
+ * Native signing produces the bare GalaChain signature format, without a personal-sign prefix
+ * or EIP-712 metadata. The private-key identity is recovered by the chain.
+ */
+export declare class PrivateKeySigner implements GalaChainSigner {
+  private readonly privateKey;
+  /**
+   * Creates a native signer from a hex or base64 secp256k1 private key.
    *
    * @example
-   * ```ts
-   * const applied = await submitted.confirm({ initialDelayMs: 3_000 });
+   * ```typescript
+   * const signer = new PrivateKeySigner('1'.padStart(64, '0'));
+   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
    * ```
    */
-  confirm(options?: ConfirmOptions): Promise<TConfirmation>;
-  private confirmApplied;
-  private readAppliedResult;
-  /** Confirm a liquidity write against the position's observable effect.
+  constructor(privateKey: string);
+  /**
+   * Signs the DTO with GalaChain native signing.
    *
-   * @returns The position after the write, or `null` for a confirmed full close.
    * @example
-   * ```ts
-   * const position = await submitted.confirm({ timeoutMs: 60_000 });
+   * ```typescript
+   * const signed = await signer.signObject('RequestTrade', {
+   *   token0: 'GALA',
+   *   token1: 'GUSDC',
+   *   fee: 3000,
+   * });
    * ```
    */
-  private confirmPosition;
+  signObject<T extends Record<string, unknown>>(_methodName: string, dto: T): Promise<SignedDto<T>>;
+}
+/** Supplies a private key at sign time: a hex/base64 string, possibly fetched asynchronously. */
+export type PrivateKeyProvider = () => Promise<string> | string;
+/** Options for {@link createLazyPrivateKeySigner}. */
+export interface LazyPrivateKeySignerOptions {
+  /**
+   * When set, every signature first checks that the fetched key belongs to this account (`0x...`
+   * or the Gala `eth|0x...` / `eth|<40 hex>` form, case-insensitive) and refuses to sign otherwise
+   * (`SIGNER_ADDRESS_MISMATCH`). Use it when the key lives in a slot another surface can switch
+   * between the moment a request was approved and the moment it is signed.
+   */
+  expectedAddress?: string | undefined;
 }
 /**
- * Controls timeout and polling behavior for confirmation.
+ * Creates the native-signing equivalent of {@link PrivateKeySigner} for apps that must not hold a
+ * key in a long-lived object (an extension that reads its session key at sign time).
  *
- * - `timeoutMs` (default 60 000): overall deadline, counted from the `confirm()` call and
- *   including `initialDelayMs`. At least one read is always made.
- * - `pollIntervalMs` (default 2 000, minimum 500): base interval, doubled with jitter up to 8 s.
- * - `initialDelayMs`: wait before the first read. Defaults to 3 000 for a queued RequestTrade
- *   (the AutoApplier needs a few seconds) and 0 for liquidity writes (already executed).
+ * `getPrivateKey` is called once per `signObject` call, never cached, never shared between calls
+ * (concurrent signatures each fetch their own key), and the normalized key bytes are zeroed
+ * before `signObject` settles, also on failure. A rejection or exception from `getPrivateKey` is
+ * passed through unchanged, so the app's own "wallet is locked" error reaches its caller; a key
+ * that is not a valid secp256k1 key string is a `VALIDATION_ERROR` (`INVALID_PRIVATE_KEY`).
+ * Signatures are byte-identical to `new PrivateKeySigner(key).signObject(...)`.
+ *
+ * A JavaScript string cannot be wiped; the provider owns the lifetime of the string it returns.
+ *
+ * @example
+ * ```typescript
+ * const signer = createLazyPrivateKeySigner(
+ *   () => SecurityHelper.getSessionSecret(SecurityHelper.SESSION_PRIVATE_KEY_KEY),
+ *   { expectedAddress: account.address },
+ * );
+ * const gswap = new GSwap({ signer });
+ * ```
  */
-export interface ConfirmOptions {
-  timeoutMs?: number | undefined;
-  pollIntervalMs?: number | undefined;
-  initialDelayMs?: number | undefined;
-}
-//#endregion
-//#region src/classes/gateway.d.ts
-/** Options for a chain-gateway client. */
-export interface ChainGatewayOptions {
-  dexBackendBaseUrl: string;
+export declare function createLazyPrivateKeySigner(getPrivateKey: PrivateKeyProvider, options?: LazyPrivateKeySignerOptions): GalaChainSigner;
+/**
+ * A Gala Wallet signer using native GalaChain signing, with an opt-in personal-sign mode.
+ *
+ * The selected Ethereum account is passed to Gala Wallet. There is NO automatic fallback: a
+ * wallet that rejects `native` surfaces its error to the caller, because the only alternative,
+ * `personal-sign`, silently recovers a phantom signer on every released Gala Wallet.
+ *
+ * `scheme: 'personal-sign'` calls
+ * `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])` and REQUIRES
+ * a wallet build that contains wallet_extension commit 3ad7ae6 (strips the embedded `prefix`
+ * field and hashes `prefix` + the prefix-less canonical body, the chain's scheme). Wallets
+ * released before that fix hash the string with the `prefix` field still inside it and the
+ * signature recovers to an address nobody holds, so only opt in once the fixed wallet is
+ * released. See SIGNING-PARITY.md.
+ */
+export declare class GalaWalletSigner implements GalaChainSigner {
+  /** The wallet address supplied to Gala Wallet for each signing request. */
+  readonly walletAddress: string;
+  /** The signing scheme used for every request; it never changes after construction. */
+  readonly scheme: GalaWalletScheme;
+  /**
+   * Creates a Gala Wallet signer.
+   *
+   * @example
+   * ```typescript
+   * const signer = new GalaWalletSigner('0x0123456789012345678901234567890123456789');
+   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
+   * ```
+   *
+   * @param walletAddress - The account passed to Gala Wallet as the signer address. An Ethereum
+   * account is `0x` plus 40 hex digits (Gala Wallet's `eth|...` form is normalized to it and held
+   * to the same check); a GalaChain id is `client|` plus 24 hex digits, or the bare 24 hex digits
+   * frontend_v2 keeps for a direct `client|` login, and is passed through unchanged.
+   * @param options - Select native signing (default) or personal-sign explicitly.
+   * `'personal-sign'` requires a Gala Wallet build with wallet_extension commit 3ad7ae6.
+   * `selectAddress` is the identity (`client|...` / `eth|...`) Gala Wallet is switched to with
+   * `window.gala.setAddress` before every signature, when the wallet offers it.
+   */
+  constructor(walletAddress: string, options?: {
+    scheme?: GalaWalletScheme | undefined;
+    selectAddress?: string | undefined;
+  });
+  /** The identity Gala Wallet is switched to before each signature, if one was given. */
+  readonly selectAddress: string | undefined;
+  /**
+   * Signs a DTO through `gala_signChainDto`.
+   *
+   * @example
+   * ```typescript
+   * const signed = await signer.signObject('AddLiquidity', {
+   *   token0: 'GALA',
+   *   token1: 'GUSDC',
+   *   tickLower: -60,
+   *   tickUpper: 60,
+   * });
+   * ```
+   */
+  signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
+}
+/**
+ * A personal-sign signer for MetaMask and other EIP-1193 browser wallets.
+ *
+ * The chain recovers this signature using the EIP-191 wrap applied by the wallet to
+ * `personal_sign`. This is the browser-wallet path used by the v2 frontend and resolves the
+ * bare `eth|` identity.
+ */
+export declare class BrowserWalletSigner implements GalaChainSigner {
+  private readonly provider;
+  /**
+   * Creates a browser-wallet signer.
+   *
+   * Defaults to `personal_sign` — unchanged from every existing integration, since it only ever
+   * resolves the bare `eth|` identity and changing that silently would be a real behavior
+   * break for anyone already depending on it. Pass `{ scheme: 'eip712' }` to correctly resolve
+   * a registered `client|` alias instead, for `RequestTrade`/`AddLiquidity`/`RemoveLiquidity`/
+   * `CollectPositionFees` (`EIP712_CAPABLE_METHODS`) — `CreatePool` and any other method still
+   * falls back to `personal_sign` even in `'eip712'` mode, since its EIP-712 signing is a
+   * separate, unsolved chain-side problem.
+   *
+   * @example
+   * ```typescript
+   * const signer = new BrowserWalletSigner(window.ethereum, '0x0123456789012345678901234567890123456789');
+   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
+   * ```
+   * @example
+   * ```typescript
+   * // Correctly resolves a registered client| alias instead of the bare eth| address.
+   * const signer = new BrowserWalletSigner(window.ethereum, walletAddress, { scheme: 'eip712' });
+   * ```
+   */
+  constructor(provider: BrowserWalletProvider, walletAddress: string, options?: {
+    scheme?: 'personal-sign' | 'eip712';
+  });
+  readonly walletAddress: string;
+  private readonly scheme;
+  /**
+   * Signs the DTO with `eth_signTypedData_v4` (when constructed with `{ scheme: 'eip712' }` and
+   * `methodName` is in `EIP712_CAPABLE_METHODS`) or the EIP-1193 `personal_sign` method
+   * (otherwise — the default).
+   *
+   * @example
+   * ```typescript
+   * const signed = await signer.signObject('RequestTrade', {
+   *   token0: 'GALA',
+   *   token1: 'GUSDC',
+   *   fee: 3000,
+   * });
+   * ```
+   */
+  signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
+}
+//#endregion
+//#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'];
+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';
+/** The chain method name the signed DryRun wrapper is signed under. */
+export declare const DRY_RUN_METHOD = "DryRun";
+/** `uniqueKey` prefix of the DryRun WRAPPER (distinct from the inner DTO's key). */
+export declare const DRY_RUN_UNIQUE_KEY_PREFIX = "galaconnect-operation-";
+/** True when `method` is a DEX method a fee can be quoted for. */
+export declare function isDexFeeMethod(method: unknown): method is DexFeeMethod;
+/** Current-contract typed DEX messages use trading symbols instead of TokenClassKey objects. */
+export declare function isCurrentContractDexMessage(message: Record<string, unknown> | null | undefined, method: unknown): boolean;
+/**
+ * The backend's response. It ALWAYS carries a usable `fees[0].feeInGala`: the backend decides what
+ * to serve when the chain cannot price the operation, so the client never invents a fee.
+ *
+ * `source` is informational: `'dry-run'` is simulated on chain and authoritative (possibly a
+ * legitimate `'0'`), `'default'` means the chain could not price it and the platform default was
+ * served.
+ */
+export interface DexFeeQuote {
+  fees: Array<{
+    feeInGala: string;
+  }>;
+  source: 'dry-run' | 'default';
+}
+/**
+ * Reduces an EIP-712 approval `message` to the DTO the chain actually receives: drops the signing
+ * envelope (`signature`, `prefix`, `types`, `domain`) and transport metadata (`trace`).
+ */
+export declare function toChainDto(message: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Signs the DryRun WRAPPER the gateway accepts for every contract:
+ * `{ callerPublicKey, method, dto: <inner DTO object>, uniqueKey, signature }`. The inner DTO
+ * travels unsigned and as an object; no `signerPublicKey` is sent because the signature already
+ * recovers it (the gateway rejects it as REDUNDANT_SIGNER_PUBLIC_KEY). The wrapper carries its own
+ * `uniqueKey`, distinct from the DTO's.
+ */
+export declare function buildDryRunWrapper(signer: GalaChainSigner, callerPublicKey: string, method: string, dto: Record<string, unknown>, uniqueKeyPrefix?: string): Promise<Record<string, unknown>>;
+/** The transport and backend a fee quote reads from. */
+export interface DexFeesClient {
+  /** Swap backend origin, e.g. `https://dex-backend-prod1.defi.gala.com`. */
+  dexBackendBaseUrl: string;
+  /** Defaults to the global `fetch`. */
+  httpRequestor?: HttpRequestor | undefined;
+  /** Per-request timeout in milliseconds (default 30 000). */
+  requestTimeoutMs?: number | undefined;
+  /**
+   * Request headers of the fee POST (`userAgent`, `headers`); see {@link WireOptions}. The SDK's
+   * `Accept: application/json` is a default that `wire.headers` may replace.
+   */
+  wire?: WireOptions | undefined;
+}
+/** Options for a single quote. */
+export interface DexFeeQuoteOptions {
+  /** GalaChain channel. Default `asset`. */
+  channel?: string | undefined;
+  /**
+   * Contract the DTO targets. Default `dexv3-contract` (what every legacy caller quotes against);
+   * a current-contract operation must pass `dex-contract` explicitly.
+   */
+  contract?: DexFeeContract | undefined;
+}
+/**
+ * Network-fee quote for GalaChain DEX methods, derived from a server-side DryRun.
+ *
+ * The client only SIGNS the DryRun wrapper (with whatever {@link GalaChainSigner} it is given) and
+ * the backend forwards it to the gateway, where the simulated writes carry the fee; the backend
+ * never holds a key. Intended for wallets: the DTO quoted is the typed message a dApp handed over.
+ *
+ * @example
+ * ```ts
+ * const fees = new DexFees({ dexBackendBaseUrl }, new PrivateKeySigner(sessionKey));
+ * const quote = await fees.quote(publicKey, 'RequestTrade', toChainDto(message), {
+ *   contract: 'dex-contract',
+ * });
+ * const feeInGala = quote?.fees[0]?.feeInGala;
+ * ```
+ */
+export declare class DexFees {
+  private readonly signer;
+  private readonly requestor;
+  private readonly baseUrl;
+  private readonly requestTimeoutMs;
+  private readonly wire;
+  constructor(client: DexFeesClient, signer: GalaChainSigner | undefined);
+  /**
+   * Quotes the network fee for `method` applied to `message`. The message is reduced with
+   * {@link toChainDto} first, so an EIP-712 approval message can be passed as is.
+   *
+   * Resolves `null` when the BACKEND could not be reached or answered unusably (offline, 4xx/5xx,
+   * malformed body): a transport outcome, not a fee. Deciding what to charge when the chain is
+   * silent is the backend's job (it serves `source: 'default'`), so the client never substitutes
+   * a fee of its own, with ONE exception that mirrors the wallet: a `dex-contract` quote answered
+   * 403 or 404 means the contract has no fee route yet and resolves `{ source: 'default', '0' }`.
+   * Never throws on transport, so a fee lookup cannot block or break a signing screen.
+   *
+   * @throws GSwapSDKError NO_SIGNER when constructed without a signer; any error the signer
+   * throws (for example a locked wallet) propagates unchanged.
+   */
+  quote(callerPublicKey: string, method: DexFeeMethod, message: Record<string, unknown>, options?: DexFeeQuoteOptions): Promise<DexFeeQuote | null>;
+}
+//#endregion
+//#region src/classes/shadow_submit.d.ts
+/** The raw answer to a shadow (dark) write: every HTTP status resolves. */
+export interface ShadowSubmitResult {
+  httpStatus: number;
+  /** Parsed JSON body, or the raw text when the body was not JSON. */
+  body: unknown;
+}
+/**
+ * Machine-readable codes defi-backend returns in a shadow failure body (`{ code, message }`, with
+ * no `statusCode`; the HTTP status carries the number).
+ *
+ * - `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 type ShadowSubmitCode = 'SHADOW_UNAVAILABLE' | 'SHADOW_DISABLED' | 'SHADOW_UNSUPPORTED_TYPE' | 'SHADOW_RELAY_REJECTED';
+/** The normalized outcome of a shadow write. */
+export type ShadowSubmitOutcome = {
+  ok: true;
+  /** The request transaction id (`''` when the gateway gave none). */
+  bundleId: string;
+  /** Present for a queued RequestTrade: confirm with `confirmAppliedTrade`. */
+  queued?: {
+    uniqueKey: string;
+    requestTransactionId: string | null;
+  };
+} | {
+  ok: false;
+  kind: 'unavailable';
+  retryable: true;
+} | {
+  ok: false;
+  kind: 'disabled';
+  retryable: false;
+} | {
+  ok: false;
+  kind: 'rejected';
+  retryable: false;
+  message: string;
+} | {
+  ok: false;
+  kind: 'unknown';
+  retryable: false;
+};
+type ShadowFailureKind = Exclude<ShadowSubmitOutcome, {
+  ok: true;
+}>['kind'];
+/** Maps an HTTP status to a failure kind: 503 retryable, 400 disabled, anything else unknown. */
+export declare function classifyShadowSubmitStatus(status: number): ShadowFailureKind;
+/**
+ * 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".
+ */
+export declare function classifyShadowSubmitError(status: number, code?: string): ShadowFailureKind;
+/**
+ * Normalizes a shadow write's raw answer.
+ *
+ * A 2xx envelope with `error === false` is a success when it is a queued RequestTrade that
+ * acknowledges the EXACT signed `uniqueKey`, or a synchronous (`mode: 'sync'`) liquidity write.
+ * Everything else is classified as a failure from the status and the body's `code`.
+ *
+ * @throws GSwapSDKError INVALID_GATEWAY_RESPONSE when a RequestTrade success does not queue the
+ * signed `uniqueKey` (a synchronous or mismatched answer must never be accepted as a swap).
+ */
+export declare function readShadowSubmitOutcome(method: string, signedBody: Record<string, unknown>, result: ShadowSubmitResult): ShadowSubmitOutcome;
+//#endregion
+//#region src/utils/submit_state.d.ts
+/**
+ * What a write's gateway answer says about the write, as one vocabulary for every app.
+ *
+ * The gateway answers `{ status, message, error, data }`. `data.mode` is `'sync'` for a liquidity
+ * write (its executed chain result is in `data.result`) and `'queued'` for a RequestTrade
+ * acknowledgement (accepted, NOT executed: the outcome is read from apply-results with
+ * `confirm()`). `error: true` is the gateway refusing the write.
+ *
+ * A {@link SubmittedTransaction} only exists for an answer the SDK accepted, so its
+ * {@link SubmitStatus} is `'executed'` or `'queued'`; a refused answer is a thrown
+ * {@link GSwapSDKError}. The predicates below classify a RAW envelope instead, for an app that
+ * holds one (`SubmittedTransaction.envelope`, `GSwapSDKError.body`, a stored answer) and for the
+ * answers that never became a transaction. They reproduce frontend_v2's `isV2SubmitSuccess` /
+ * `isV2SubmitQueued` / `isV2SubmitRejected` exactly, so the app can delete its own copies.
+ */
+/** The state of an accepted write: executed on chain (`mode: 'sync'`) or queued (`mode: 'queued'`). */
+export type SubmitStatus = 'executed' | 'queued';
+/**
+ * How a raw gateway envelope classifies:
+ *
+ * - `'executed'`: `error === false` and `data.mode === 'sync'` (the executed result came back).
+ * - `'queued'`: `error === false`, `data.mode === 'queued'` and `data.uniqueKey` is a string.
+ * - `'rejected'`: no envelope at all, or `error === true`: a DEFINITE failure.
+ * - `'unconfirmed'`: anything else (`error: false` with another or no `mode`, a queued answer
+ *   with no `uniqueKey`, an envelope with no boolean `error`): accepted, outcome not known. It is
+ *   NOT a rejection and must not be shown as one.
+ *
+ * The four are mutually exclusive and exhaustive.
+ */
+export type SubmitClassification = SubmitStatus | 'rejected' | 'unconfirmed';
+/** True when the envelope is a definite failure: absent, or `error === true`. */
+export declare function isSubmitRejected(envelope: unknown): boolean;
+/**
+ * True when the envelope carries an executed result: `error === false` and `data.mode === 'sync'`.
+ * A queued RequestTrade acknowledgement is deliberately NOT executed: its outcome is not known
+ * until apply-results resolves.
+ */
+export declare function isSubmitExecuted(envelope: unknown): boolean;
+/** True when the envelope acknowledges a `uniqueKey` as queued (`data.mode === 'queued'`). */
+export declare function isSubmitQueued(envelope: unknown): boolean;
+/** Classifies a raw gateway envelope; see {@link SubmitClassification}. */
+export declare function classifySubmitEnvelope(envelope: unknown): SubmitClassification;
+//#endregion
+//#region src/classes/submitted_transaction.d.ts
+/** Result of one position-confirmation poll. */
+export type PositionConfirmationResult = {
+  confirmed: true;
+  position: Position | null;
+} | {
+  confirmed: false;
+  position?: Position | null;
+};
+/** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
+export declare class SubmittedTransaction<TConfirmation = AppliedTrade | Position | null> {
+  readonly method: string;
+  readonly uniqueKey: string;
+  readonly transactionId: string | null;
+  readonly blockNumber: number | null;
+  /** The gateway's `data.mode`: `'sync'` (executed, `result` is the chain result) or `'queued'`. */
+  readonly mode: 'sync' | 'queued';
+  /**
+   * What the gateway's answer established: `'executed'` for `mode: 'sync'`, `'queued'` for
+   * `mode: 'queued'` (accepted, NOT executed: `await confirm()` for the outcome). A refused answer
+   * never becomes a transaction, so there is no `'rejected'` here; see {@link classifySubmitEnvelope}
+   * for classifying a raw envelope.
+   */
+  readonly status: SubmitStatus;
+  /** The synchronous gateway result, or `undefined` when `mode === 'queued'`. */
+  readonly result: unknown;
+  /**
+   * The gateway's whole JSON answer as it came (`{ status, message, error, data }`), for an app
+   * that hands the backend's own envelope to its callers; `undefined` for a transaction built from
+   * a uniqueKey alone.
+   */
+  readonly envelope: unknown;
+  private readonly backendBaseUrl;
+  private readonly requestor;
+  private readonly requestTimeoutMs;
+  private readonly wire;
+  private readonly positionConfirmation;
+  /** Construct a submitted transaction from a successful gateway response.
+   *
+   * @example
+   * ```ts
+   * const transaction = new SubmittedTransaction({
+   *   method: 'RequestTrade', mode: 'queued', uniqueKey: 'swap-1',
+   *   transactionId: 'request-tx', result: undefined,
+   *   dexBackendBaseUrl: 'https://dex.example', httpRequestor,
+   * });
+   * ```
+   */
+  constructor(options: {
+    method: string;
+    uniqueKey: string;
+    transactionId: string | null;
+    mode: 'sync' | 'queued';
+    result: unknown;
+    dexBackendBaseUrl: string;
+    httpRequestor: HttpRequestor;
+    blockNumber?: number | null | undefined;
+    envelope?: unknown;
+    requestTimeoutMs?: number | undefined;
+    /** Wire options of the apply-results polls `confirm()` makes. */
+    wire?: WireOptions | undefined;
+    positionConfirmation?: ((signal: AbortSignal) => Promise<PositionConfirmationResult>) | undefined;
+  });
+  /** Confirm a queued RequestTrade or prove the affected position for a liquidity write.
+   *
+   * For RequestTrade, calling this method is required to learn the outcome: the queued
+   * acknowledgement proves acceptance, not execution.
+   *
+   * @example
+   * ```ts
+   * const applied = await submitted.confirm({ initialDelayMs: 3_000 });
+   * ```
+   */
+  confirm(options?: ConfirmOptions): Promise<TConfirmation>;
+  private confirmApplied;
+  /** Confirm a liquidity write against the position's observable effect.
+   *
+   * @returns The position after the write, or `null` for a confirmed full close.
+   * @example
+   * ```ts
+   * const position = await submitted.confirm({ timeoutMs: 60_000 });
+   * ```
+   */
+  private confirmPosition;
+}
+//#endregion
+//#region src/classes/gateway.d.ts
+/** Options for a chain-gateway client. */
+export interface ChainGatewayOptions {
+  dexBackendBaseUrl: string;
   httpRequestor?: HttpRequestor | undefined;
   walletAddress?: string | undefined;
+  /**
+   * Timeout of every gateway request in milliseconds (default 30 000); also the per-read timeout
+   * of the services built on this gateway and of `confirm()`. `Infinity` arms no timer, for an
+   * app whose HTTP stack owns request lifetimes.
+   */
   chainCallTimeoutMs?: number | undefined;
+  /**
+   * Wire format of every request of this gateway and of the services built on it: the headers
+   * (`userAgent`, `headers`) of reads AND of the POSTs that submit writes, and the query encoding
+   * of reads. `X-Wallet-Address` and `X-Shadow` always win over a same-named `wire.headers` entry.
+   */
+  wire?: WireOptions | undefined;
 }
 /** Optional attribution and operation-specific confirmation hooks for a write. */
 export interface ChainSubmitOptions {
@@ -365,11 +1028,35 @@ export declare class ChainGateway {
   private readonly chainCallTimeoutMs;
   readonly requestTimeoutMs: number;
   readonly dexBackendBaseUrl: string;
+  /** Wire format shared by the read services built on this gateway. */
+  readonly wire: WireOptions;
   /** Create a chain gateway client. */
   constructor(options: ChainGatewayOptions);
   /** Submit a signed v2 DTO through the chain gateway. */
   submit(method: 'RequestTrade', signedBody: Record<string, unknown>, options?: ChainSubmitOptions): Promise<SubmittedTransaction<AppliedTrade>>;
   submit(method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions): Promise<SubmittedTransaction<Position | null>>;
+  /**
+   * Submit a signed v2 DTO as a SHADOW (dark) write: the same route and body as {@link submit},
+   * plus `X-Wallet-Address` and `X-Shadow: true`, so defi-backend marks the transaction private
+   * before it reaches the contract. The wallet address is required (the backend resolves the
+   * owner from it).
+   *
+   * Unlike `submit`, EVERY HTTP status resolves: the result is the raw `{ httpStatus, body }`,
+   * because shadow failures are classified from the status together with the body's `code`
+   * (`SHADOW_UNAVAILABLE`, `SHADOW_DISABLED`, `SHADOW_UNSUPPORTED_TYPE`, `SHADOW_RELAY_REJECTED`);
+   * see `readShadowSubmitOutcome`. Only a transport failure rejects, and a timeout rejects
+   * with `SUBMISSION_OUTCOME_UNKNOWN`.
+   *
+   * @example
+   * ```ts
+   * const result = await gateway.submitShadow('RequestTrade', signedDto, { walletAddress });
+   * const outcome = readShadowSubmitOutcome('RequestTrade', signedDto, result);
+   * ```
+   */
+  submitShadow(method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions): Promise<ShadowSubmitResult>;
+  private writeUrl;
+  /** POSTs a signed body; a timeout means the outcome is unknown, never "not submitted". */
+  private post;
   /** Expose the requestor for sibling read services that share this gateway transport. */
   get httpRequestor(): HttpRequestor;
 }
@@ -390,6 +1077,20 @@ export interface GdexStreamConfig {
    * global `WebSocket` (pass the one from the `ws` package).
    */
   webSocketImpl?: unknown;
+  /**
+   * Presents `x-api-key` on the WebSocket upgrade request, which defi-backend uses to serve the
+   * PRIVILEGED view (shadow swaps with the wallet unredacted). Without it, or with a wrong key, the
+   * connection is simply public: the server never says whether a privileged mode exists.
+   *
+   * It must travel as an HTTP header, because the server reads no other credential, and a browser
+   * `WebSocket` cannot set headers. So this option needs a constructor that accepts them as its
+   * third argument (`{ headers }`): the `ws` package on Node.js, or React Native's built-in
+   * `WebSocket`. It therefore REQUIRES `webSocketImpl` (the platform default is never assumed to
+   * honor headers, and a key that is silently dropped would look like a working privileged
+   * connection); the constructor throws otherwise. Use it from server-side code only: a key
+   * shipped inside a browser or app bundle is not a secret. Browser clients stay public.
+   */
+  apiKey?: string | undefined;
 }
 /** The channels of the realtime stream. */
 export type GdexChannel = 'pool' | 'balance' | 'poolCreated' | 'swap' | 'liquidity' | 'blocks';
@@ -482,6 +1183,7 @@ export declare class GdexStreamError extends Error {
 export declare class GdexStreamService {
   private readonly url;
   private readonly requestTimeoutMs;
+  private readonly apiKey;
   private readonly webSocketConstructor;
   private readonly backoff;
   private socket;
@@ -502,6 +1204,7 @@ export declare class GdexStreamService {
   isConnected(): boolean;
   /** Raw JSON-RPC escape hatch. */
   request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  private send;
   serverInfo(): Promise<Record<string, unknown>>;
   ping(): Promise<{
     pong: boolean;
@@ -595,13 +1298,31 @@ export declare const TICK_SPACING_BY_FEE: Readonly<Record<FEE_TIER, number>>;
 /** All fee tiers supported by the current GalaChainDex contract. */
 export declare const ALL_FEE_TIERS: readonly FEE_TIER[];
 //#endregion
-//#region src/types/token.d.ts
-export interface GalaChainTokenClassKey {
-  collection: string;
-  category: string;
-  type: string;
-  additionalKey: string;
+//#region src/utils/lenient.d.ts
+/** One row of a list answer that the SDK skipped because it was not usable. */
+interface InvalidEntry {
+  /** Which read the row came from. */
+  source: 'pools' | 'symbols' | 'positions';
+  /** Position of the row in the answer's array. */
+  index: number;
+  /** The row exactly as the backend sent it. */
+  entry: unknown;
+  /** Why it was skipped, in words. */
+  reason: string;
 }
+/**
+ * Called once per skipped row, in order, before the read resolves. It is a diagnostics hook: what it
+ * does, or throws, never changes the result of the read.
+ */
+type InvalidEntryHandler = (invalid: InvalidEntry) => void;
+/** The outcome of reading one row. */
+type EntryParse<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  reason: string;
+};
 //#endregion
 //#region src/utils/ordering.d.ts
 /** A symbol or a GalaChain token class key accepted by v2 operations. */
@@ -642,15 +1363,26 @@ export declare function parseTokenClassKey(tokenClassKey: TokenRef): GalaChainTo
 /** Symbol registry client for the current GalaChainDex contract. */
 export declare class Symbols {
   private readonly gateway;
+  private readonly options;
   private cachedSymbols;
   private cachedAt;
   private refreshInFlight;
   private readonly http;
-  /** Create a symbol service backed by the swap backend. */
+  /**
+   * Create a symbol service backed by the swap backend. `onInvalidEntry` is told about every
+   * registry row that was skipped as unusable (see {@link InvalidEntryHandler}).
+   */
   constructor(gateway: Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
     requestTimeoutMs?: number | undefined;
+    wire?: WireOptions | undefined;
+  }, options?: {
+    onInvalidEntry?: InvalidEntryHandler | undefined;
   });
-  /** List all registered GalaChainDex trading symbols, cached for 60 seconds. */
+  /**
+   * List all registered GalaChainDex trading symbols, cached for 60 seconds. A registry row that
+   * is not a usable symbol is skipped (and reported to `onInvalidEntry`) instead of failing the
+   * whole list.
+   */
   list(): Promise<TradingSymbol[]>;
   /** Invalidate the cached symbol registry after a write changes registration state.
    *
@@ -670,7 +1402,32 @@ export declare class Symbols {
   refresh(): Promise<TradingSymbol[]>;
   /** Resolve a symbol or token class key to its registered symbol metadata. */
   resolve(ref: TokenRef): Promise<TradingSymbol>;
-  /** Resolve and put two token references in canonical trading-symbol order. */
+  /**
+   * The trading symbol to put in a token's first CreatePool.
+   *
+   * 1. The symbol ALREADY registered for exactly this class key, if any: proposing another one
+   *    fails the gateway's registry-conflict check.
+   * 2. Otherwise `displaySymbol` (the token's curated symbol), when it is proposable
+   *    ({@link isProposableTradingSymbol}).
+   * 3. Otherwise a `VALIDATION_ERROR`: a symbol is never derived from the key (BNB's collection is
+   *    `GBNB`, a launchpad token's is the reserved word `Token`).
+   *
+   * `registryFailure: 'ignore'` treats an unreachable registry as an empty one and falls through
+   * to step 2 (the gateway still rejects a conflicting symbol); the default `'throw'` propagates
+   * the failure.
+   *
+   * @example
+   * ```ts
+   * const symbol = await gSwap.symbols.proposeSymbol(
+   *   { collection: 'GALA_TEST1', category: 'Unit', type: 'none', additionalKey: 'none' },
+   *   'GALATEST',
+   * );
+   * ```
+   */
+  proposeSymbol(classKey: GalaChainTokenClassKey, displaySymbol: string, options?: {
+    registryFailure?: 'throw' | 'ignore' | undefined;
+  }): Promise<string>;
+  /** Resolve and put two token references in canonical trading-symbol order. */
   orderPair(a: TokenRef, b: TokenRef): Promise<{
     token0: TradingSymbol;
     token1: TradingSymbol;
@@ -679,38 +1436,109 @@ export declare class Symbols {
 }
 /** Alias exported for callers that use the contract's shorter type name. */
 export type TokenClassKey = GalaChainTokenClassKey;
+/**
+ * What the services need from a token resolver: how a token reference becomes a trading symbol,
+ * and whether requests carry the caller's references untouched. {@link Symbols} is the registry
+ * resolver (one `GET /v2/trade/symbols`, cached); {@link CanonicalSymbols} is the offline one.
+ */
+export interface TokenResolver {
+  resolve(ref: TokenRef): Promise<TradingSymbol>;
+  /**
+   * True when reads send the caller's token references verbatim (a symbol, or a composite key as
+   * the caller wrote it) and let the backend resolve and orient the pair — no registry request
+   * and no client-side ordering or tick flip.
+   */
+  readonly passthrough?: boolean | undefined;
+}
+/** A token reference as the caller wrote it: a string verbatim, a class key as its `$` composite. */
+export declare function rawTokenOf(ref: TokenRef): string;
+/** The trading symbol of a reference, or `SYMBOL_NOT_FOUND` when the resolver has none. */
+export declare function tradingSymbolOf(resolver: TokenResolver, ref: TokenRef): Promise<string>;
+/** What a read request names a token by: the reference itself in pass-through mode, else its symbol. */
+export declare function queryTokenOf(resolver: TokenResolver, ref: TokenRef): Promise<string>;
+/**
+ * The offline resolver for apps that already hold the backend's canonical trading symbols (from
+ * `/quote`, `/add-liq-estimate`, a position row) and must not make a registry request of their own.
+ *
+ * - `resolve` accepts a bare trading symbol and returns it as is; a class key (object, `$` or `|`
+ *   form) is not a symbol and is refused as `UNKNOWN_TOKEN`. `createPool` relies on that refusal to
+ *   fall back to the symbols its caller supplies.
+ * - `orderPair` orders two symbols by plain string comparison, as the contract does.
+ * - Reads are pass-through (see {@link TokenResolver.passthrough}): the caller's references go on
+ *   the wire verbatim, composite keys included, and the backend orients the pair.
+ *
+ * @example
+ * ```ts
+ * const swaps = new Swaps(gateway, new CanonicalSymbols(), signer, walletAddress);
+ * await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '10' });
+ * ```
+ */
+export declare class CanonicalSymbols implements TokenResolver {
+  readonly passthrough = true;
+  /** Resolve a bare trading symbol to itself. */
+  resolve(ref: TokenRef): Promise<TradingSymbol>;
+  /** Put two symbols in canonical (string) order. */
+  orderPair(a: TokenRef, b: TokenRef): Promise<{
+    token0: TradingSymbol;
+    token1: TradingSymbol;
+    flipped: boolean;
+  }>;
+  /** There is no registry state to drop. */
+  invalidate(): void;
+}
 //#endregion
 //#region src/classes/pools.d.ts
 type PoolGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
   requestTimeoutMs?: number | undefined;
+  wire?: WireOptions | undefined;
 };
-type PoolSymbols = Pick<Symbols, 'resolve'>;
+/** The sort keys of `GET /v2/trade/pools`. */
+export type PoolSortBy = 'tvl' | 'volume1d' | 'volume30d';
+/** Options of {@link Pools.getPools}. Omit all of `search`, `sortBy`, `sortOrder`, `page`, `limit` for the full, unsorted list. */
+export interface PoolListOptions {
+  signal?: AbortSignal | undefined;
+  /** Case-insensitive match on the pair's symbols; `A/B` or `A B` matches either order. At most 64 characters. */
+  search?: string | undefined;
+  sortBy?: PoolSortBy | undefined;
+  sortOrder?: 'asc' | 'desc' | undefined;
+  /** 1-based page number; only meaningful together with `limit`. */
+  page?: number | undefined;
+  /** Rows per page, 1-1000; omitted returns every row. */
+  limit?: number | undefined;
+  /** Overrides the service-level handler for this call. */
+  onInvalidEntry?: InvalidEntryHandler | undefined;
+}
 /** Read-only pool and current-price access for the current GalaChainDex contract. */
 export declare class Pools {
   private readonly gateway;
   private readonly symbols;
+  private readonly options;
   /**
-   * Creates a pool service.
+   * Creates a pool service. `options.onInvalidEntry` is told about every pool row that was
+   * skipped as unusable (see {@link InvalidEntryHandler}).
    *
    * @example
    * ```ts
    * const pools = new Pools(gateway, symbols);
    * ```
    */
-  constructor(gateway: PoolGateway, symbols: PoolSymbols);
+  constructor(gateway: PoolGateway, symbols: TokenResolver, options?: {
+    onInvalidEntry?: InvalidEntryHandler | undefined;
+  });
   private readonly http;
   /**
-   * Fetches every current-contract pool from the swap backend.
+   * Fetches current-contract pools from the swap backend, optionally searched, sorted and paged
+   * by the backend. A row that is not a usable pool is skipped and reported to `onInvalidEntry`
+   * instead of failing the whole list; an answer that is not a list at all is
+   * `INVALID_CHAIN_RESPONSE`.
    *
    * @example
    * ```ts
-   * const pools = await service.getPools();
-   * console.log(pools.length);
+   * const top = await service.getPools({ sortBy: 'tvl', sortOrder: 'desc', page: 1, limit: 8 });
+   * console.log(top.length);
    * ```
    */
-  getPools(options?: {
-    signal?: AbortSignal | undefined;
-  }): Promise<PoolListInfo[]>;
+  getPools(options?: PoolListOptions): Promise<PoolListInfo[]>;
   /**
    * Fetches one pool from the backend, preserving whether the request order was flipped.
    *
@@ -745,237 +1573,342 @@ export declare class Pools {
   private getBackend;
 }
 //#endregion
-//#region src/classes/signers.d.ts
-/** The signing schemes supported by the Gala Wallet signer. */
-export type GalaWalletScheme = 'native' | 'personal-sign';
-/** The request surface used by an EIP-1193 browser wallet. */
-export interface BrowserWalletProvider {
-  request(args: {
-    method: string;
-    params?: unknown[];
-  }): Promise<unknown>;
+//#region src/types/branding.d.ts
+interface Branding<BrandT> {
+  _type: BrandT;
 }
-type SignedDto<T extends Record<string, unknown>> = T & {
-  signature: string;
+type Brand<T, BrandT> = T & Branding<BrandT>;
+//#endregion
+//#region src/types/amounts.d.ts
+export type NumericAmount = string | BigNumber;
+export type SqrtPrice = Brand<BigNumber, 'SqrtPrice'>;
+export type SqrtPriceIn = Brand<NumericAmount, 'SqrtPriceIn'> | SqrtPrice;
+export type Price = Brand<BigNumber, 'Price'>;
+export type PriceIn = Brand<NumericAmount, 'PriceIn'> | Price;
+/**
+ * What a swap trades: exactly one of `exactIn` (sell this much of the input token) or `exactOut`
+ * (receive this much of the output token), with that side's slippage bound and an optional
+ * sqrt-price limit.
+ */
+export type SwapAmount = {
+  exactIn: NumericAmount;
+  exactOut?: undefined;
+  amountOutMinimum?: NumericAmount | undefined;
+  amountInMaximum?: undefined;
+  /** Sqrt-price limit passed through to the chain as `priceLimit`; omitted when undefined. */
+  priceLimit?: NumericAmount | undefined;
+} | {
+  exactIn?: undefined;
+  exactOut: NumericAmount;
+  amountOutMinimum?: undefined;
+  amountInMaximum?: NumericAmount | undefined;
+  /** Sqrt-price limit passed through to the chain as `priceLimit`; omitted when undefined. */
+  priceLimit?: NumericAmount | undefined;
+};
+//#endregion
+//#region src/types/v2_dtos.d.ts
+/** Common identity fields for v2 pool writes. */
+export type V2PoolWriteBase = Record<'token0' | 'token1' | 'uniqueKey', string> & {
+  fee: FEE_TIER;
+};
+/** A v2 RequestTrade with exactly one selected trade-side quantity. */
+export type RequestTradeDTO = V2PoolWriteBase & ({
+  sell0Qty: string;
+  sell1Qty?: never;
+  buy0Qty?: never;
+  buy1Qty?: never;
+} | {
+  sell0Qty?: never;
+  sell1Qty: string;
+  buy0Qty?: never;
+  buy1Qty?: never;
+} | {
+  sell0Qty?: never;
+  sell1Qty?: never;
+  buy0Qty: string;
+  buy1Qty?: never;
+} | {
+  sell0Qty?: never;
+  sell1Qty?: never;
+  buy0Qty?: never;
+  buy1Qty: string;
+}) & {
+  amountOutMinimum?: string | undefined;
+  amountInMaximum?: string | undefined;
+  priceLimit?: string | undefined;
+};
+/** A v2 liquidity deposit with exactly one selected deposit quantity. */
+export type AddLiquidityDTO = V2PoolWriteBase & {
+  tickLower: number;
+  tickUpper: number;
+} & ({
+  depositQuantityToken0: string;
+  depositQuantityToken1?: never;
+} | {
+  depositQuantityToken0?: never;
+  depositQuantityToken1: string;
+});
+/** A v2 liquidity withdrawal; omitting both quantities closes the position. */
+export type RemoveLiquidityDTO = V2PoolWriteBase & {
+  tickLower: number;
+  tickUpper: number;
+} & ({
+  withdrawalQuantityToken0: string;
+  withdrawalQuantityToken1?: never;
+} | {
+  withdrawalQuantityToken0?: never;
+  withdrawalQuantityToken1: string;
+} | {
+  withdrawalQuantityToken0?: never;
+  withdrawalQuantityToken1?: never;
+});
+/** A v2 request to sweep all fees from one position. */
+export type CollectPositionFeesDTO = V2PoolWriteBase & {
+  tickLower: number;
+  tickUpper: number;
 };
+/** A v2 pool creation request with exactly one initial-price representation. */
+export type CreatePoolDTO = {
+  token0Key: GalaChainTokenClassKey;
+  token1Key: GalaChainTokenClassKey;
+  token0Symbol: string;
+  token1Symbol: string;
+  fee: FEE_TIER;
+  name?: string | undefined;
+  isPrivate?: boolean | undefined;
+  privateAccess?: string[] | undefined;
+  uniqueKey: string;
+} & ({
+  startingPrice: string;
+  startingSqrtPrice?: never;
+} | {
+  startingPrice?: never;
+  startingSqrtPrice: string;
+});
+/** Optional page cursor accepted by chain read methods. */
+export interface PageDTO {
+  limit?: number | undefined;
+  bookmark?: string | undefined;
+}
+/** Fetch all registered trading symbols. */
+export type FetchTokenTradingSymbolsDTO = PageDTO;
+/** Fetch a composite pool snapshot. */
+export interface FetchCompositePoolDataDTO {
+  token0: string;
+  token1: string;
+  fee: FEE_TIER;
+}
+/** Fetch one current trading price, or all prices when no pair is supplied. */
+export type FetchCurrentTradingPricesDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
+/** Fetch pools, optionally narrowed to one pair and paged. */
+export type FetchPoolsDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
+/** Fetch all liquidity positions, optionally narrowed to a pool reference. */
+export interface FetchLiquidityPositionsDTO extends PageDTO {
+  pool?: string | undefined;
+}
+//#endregion
+//#region src/utils/unique_key.d.ts
 /**
- * A signer for complete GalaChain write bodies.
+ * 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.
+ */
+export declare const DEFAULT_UNIQUE_KEY_PREFIX = "galaswap-operation-";
+/** Options shared by the services that mint `uniqueKey`s for writes. */
+export interface UniqueKeyOptions {
+  /**
+   * Prefix of every minted `uniqueKey` (`<prefix><uuid>`). Defaults to
+   * `DEFAULT_UNIQUE_KEY_PREFIX` (`galaswap-operation-`).
+   */
+  uniqueKeyPrefix?: string | undefined;
+}
+/**
+ * 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.
  *
- * Implementations return the DTO fields together with the signature that belongs in the
- * gateway request body. Signer identity is recovered from that signature; implementations do
- * not add signer hints, typed-data metadata, or a domain.
+ * @throws GSwapSDKError VALIDATION_ERROR when the prefix has characters outside `A-Za-z0-9._:-` or
+ * is longer than 92 characters.
  */
-export interface GalaChainSigner {
+export declare function resolveUniqueKeyPrefix(prefix: string | undefined): string;
+/**
+ * Validates a caller-supplied write `uniqueKey`: 1 to 128 characters of `A-Za-z0-9._:-`, the
+ * shape the apply-results route accepts, so the write's outcome can always be read back with
+ * `confirm()`. A key is one attempt's identity: reuse it only to retry that same attempt.
+ *
+ * @throws GSwapSDKError VALIDATION_ERROR otherwise.
+ */
+export declare function assertUniqueKey(uniqueKey: string): void;
+/** A fresh per-attempt key: `<prefix><random UUID>`. */
+export declare function createUniqueKey(prefix: string): string;
+//#endregion
+//#region src/classes/positions.d.ts
+type PositionGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
+  submit: (method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<SubmittedTransaction<Position | null>>;
+  requestTimeoutMs?: number | undefined;
+  wire?: WireOptions | undefined;
+};
+type PositionSymbols = TokenResolver & Pick<Symbols, 'orderPair'> & {
+  invalidate?: () => void;
+};
+/** Options of {@link Positions}: the `uniqueKey` prefix and a handler for skipped list rows. */
+export interface PositionsOptions extends UniqueKeyOptions {
+  /** Told about every position row of a list that was skipped as unusable. */
+  onInvalidEntry?: InvalidEntryHandler | undefined;
+}
+/** A write's optional attempt identity. */
+interface UniqueKeyArg {
   /**
-   * Signs a DTO for a named GalaChain contract method.
-   *
-   * @example
-   * ```typescript
-   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
-   * ```
+   * The attempt's `uniqueKey` (1-128 characters of `A-Za-z0-9._:-`). Default: a fresh
+   * `<uniqueKeyPrefix><uuid>`. Supply one to know the key before signing, or to retry the SAME
+   * attempt after a lost response; never reuse it for another write.
    */
-  signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
+  uniqueKey?: string | undefined;
+}
+/** Arguments of {@link Positions.addLiquidityByTicks} and {@link Positions.buildAddLiquidity}. */
+export interface AddLiquidityArgs extends UniqueKeyArg {
+  token0: TokenRef;
+  token1: TokenRef;
+  fee: FEE_TIER;
+  tickLower: number;
+  tickUpper: number;
+  amount: NumericAmount;
+  /** Whether `amount` is of `token0` as the caller passed it (not of the canonical token0). */
+  amountIsToken0: boolean;
+}
+/** Arguments of {@link Positions.removeLiquidity} and {@link Positions.buildRemoveLiquidity}. */
+export interface RemoveLiquidityArgs extends UniqueKeyArg {
+  token0: TokenRef;
+  token1: TokenRef;
+  fee: FEE_TIER;
+  tickLower: number;
+  tickUpper: number;
+  /** Withdraw this much of the caller's `token0`; give at most one of `amount0` / `amount1`. */
+  amount0?: NumericAmount | undefined;
+  amount1?: NumericAmount | undefined;
+}
+/** Arguments of {@link Positions.collectPositionFees} and {@link Positions.buildCollectPositionFees}. */
+export interface CollectPositionFeesArgs extends UniqueKeyArg {
+  token0: TokenRef;
+  token1: TokenRef;
+  fee: FEE_TIER;
+  tickLower: number;
+  tickUpper: number;
+}
+/** Arguments of {@link Positions.createPool} and {@link Positions.buildCreatePool}. */
+export interface CreatePoolArgs extends UniqueKeyArg {
+  token0: TokenRef;
+  token1: TokenRef;
+  token0Symbol?: string | undefined;
+  token1Symbol?: string | undefined;
+  fee: FEE_TIER;
+  startingPrice?: NumericAmount | undefined;
+  startingSqrtPrice?: NumericAmount | undefined;
+  /** Optional pool display name, sent as the DTO's `name`; omitted when undefined or empty. */
+  name?: string | undefined;
+  isPrivate?: boolean | undefined;
+  privateAccess?: string[] | undefined;
 }
 /**
- * A GalaChain native signer backed by a secp256k1 private key.
+ * The outcome of {@link Positions.readPosition}. Only `not_found` is chain-confirmed absence (the
+ * backend answers HTTP 404 only when the chain itself found no such position); `unknown` is "no
+ * evidence either way" — a transport failure, a gateway timeout, any other error status or an
+ * answer that is not a position — and must never be read as a removal.
+ */
+export type PositionRead = {
+  kind: 'found';
+  data: Position;
+} | {
+  kind: 'not_found';
+} | {
+  kind: 'unknown';
+  error: GSwapSDKError;
+};
+/**
+ * Manages current-contract concentrated-liquidity positions.
  *
- * Native signing produces the bare GalaChain signature format, without a personal-sign prefix
- * or EIP-712 metadata. The private-key identity is recovered by the chain.
+ * @example
+ * ```typescript
+ * const positions = gSwap.positions;
+ * const mine = await positions.getUserPositions('client|012345678901234567890123');
+ * console.log(mine.length);
+ * ```
  */
-export declare class PrivateKeySigner implements GalaChainSigner {
-  private readonly keyBuffer;
+export declare class Positions {
+  private readonly gateway;
+  private readonly symbols;
+  private readonly signer?;
+  private readonly walletAddress?;
+  constructor(gateway: PositionGateway, symbols: PositionSymbols, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined, options?: PositionsOptions);
+  private readonly http;
+  private readonly uniqueKeyPrefix;
+  private readonly onInvalidEntry;
   /**
-   * Creates a native signer from a hex or base64 secp256k1 private key.
+   * Gets all current-contract positions owned by an address.
    *
+   * @param owner - GalaChain owner identity.
+   * @returns Enriched positions from the v2 trade backend, token images included. A row that is
+   * not a usable position is skipped and reported to `onInvalidEntry`.
    * @example
    * ```typescript
-   * const signer = new PrivateKeySigner('1'.padStart(64, '0'));
-   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
+   * const positions = await gSwap.positions.getUserPositions('client|012345678901234567890123');
    * ```
    */
-  constructor(privateKey: string);
+  getUserPositions(owner: string): Promise<Position[]>;
   /**
-   * Signs the DTO with GalaChain native signing.
+   * Gets one position, normalizing a caller-supplied reversed pair to canonical symbol order.
+   * Reversed pairs also invert the price axis, so `[lower, upper]` becomes `[-upper, -lower]`.
    *
+   * @param args - Pair, owner, fee, and position tick range.
+   * @returns The position, or `null` when the backend returns 404.
    * @example
    * ```typescript
-   * const signed = await signer.signObject('RequestTrade', {
-   *   token0: 'GALA',
-   *   token1: 'GUSDC',
-   *   fee: 3000,
+   * const position = await gSwap.positions.getPosition({
+   *   token0: 'GALA', token1: 'GUSDC', owner: 'client|012345678901234567890123',
+   *   fee: 3000, tickLower: -19200, tickUpper: 12000,
    * });
    * ```
    */
-  signObject<T extends Record<string, unknown>>(_methodName: string, dto: T): Promise<SignedDto<T>>;
-}
-/**
- * A Gala Wallet signer using native GalaChain signing, with an opt-in personal-sign mode and
- * automatic fallback for older wallets.
- *
- * The selected Ethereum account is passed to Gala Wallet. Personal-sign resolves the bare
- * `eth|` identity; the legacy EIP-712 `eth_signTypedData` path is not used. The fallback calls
- * `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])`.
- */
-export declare class GalaWalletSigner implements GalaChainSigner {
-  /** The wallet address supplied to Gala Wallet for each signing request. */
-  readonly walletAddress: string;
-  /** The scheme currently used, including any automatic native-to-personal fallback. */
-  effectiveScheme: GalaWalletScheme;
-  /**
-   * Creates a Gala Wallet signer.
-   *
-   * @example
-   * ```typescript
-   * const signer = new GalaWalletSigner('0x0123456789012345678901234567890123456789');
-   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
-   * ```
-   *
-   * @param walletAddress - The selected Ethereum account (`0x` plus 40 hex digits); Gala Wallet's
-   * `eth|0x...` form is also accepted and normalized.
-   * @param options - Select native signing or personal-sign explicitly.
-   */
-  constructor(walletAddress: string, options?: {
-    scheme?: GalaWalletScheme | undefined;
-  });
-  /**
-   * Signs a DTO through `gala_signChainDto`.
-   *
-   * @example
-   * ```typescript
-   * const signed = await signer.signObject('AddLiquidity', {
-   *   token0: 'GALA',
-   *   token1: 'GUSDC',
-   *   tickLower: -60,
-   *   tickUpper: 60,
-   * });
-   * ```
-   */
-  signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
-}
-/**
- * A personal-sign signer for MetaMask and other EIP-1193 browser wallets.
- *
- * The chain recovers this signature using the EIP-191 wrap applied by the wallet to
- * `personal_sign`. This is the browser-wallet path used by the v2 frontend and resolves the
- * bare `eth|` identity.
- */
-export declare class BrowserWalletSigner implements GalaChainSigner {
-  private readonly provider;
-  /**
-   * Creates a browser-wallet signer.
-   *
-   * Defaults to `personal_sign` — unchanged from every existing integration, since it only ever
-   * resolves the bare `eth|` identity and changing that silently would be a real behavior
-   * break for anyone already depending on it. Pass `{ scheme: 'eip712' }` to correctly resolve
-   * a registered `client|` alias instead, for `RequestTrade`/`AddLiquidity`/`RemoveLiquidity`/
-   * `CollectPositionFees` (`EIP712_CAPABLE_METHODS`) — `CreatePool` and any other method still
-   * falls back to `personal_sign` even in `'eip712'` mode, since its EIP-712 signing is a
-   * separate, unsolved chain-side problem.
-   *
-   * @example
-   * ```typescript
-   * const signer = new BrowserWalletSigner(window.ethereum, '0x0123456789012345678901234567890123456789');
-   * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
-   * ```
-   * @example
-   * ```typescript
-   * // Correctly resolves a registered client| alias instead of the bare eth| address.
-   * const signer = new BrowserWalletSigner(window.ethereum, walletAddress, { scheme: 'eip712' });
-   * ```
-   */
-  constructor(provider: BrowserWalletProvider, walletAddress: string, options?: {
-    scheme?: 'personal-sign' | 'eip712';
-  });
-  readonly walletAddress: string;
-  private readonly scheme;
-  /**
-   * Signs the DTO with `eth_signTypedData_v4` (when constructed with `{ scheme: 'eip712' }` and
-   * `methodName` is in `EIP712_CAPABLE_METHODS`) or the EIP-1193 `personal_sign` method
-   * (otherwise — the default).
-   *
-   * @example
-   * ```typescript
-   * const signed = await signer.signObject('RequestTrade', {
-   *   token0: 'GALA',
-   *   token1: 'GUSDC',
-   *   fee: 3000,
-   * });
-   * ```
-   */
-  signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
-}
-//#endregion
-//#region src/types/branding.d.ts
-interface Branding<BrandT> {
-  _type: BrandT;
-}
-type Brand<T, BrandT> = T & Branding<BrandT>;
-//#endregion
-//#region src/types/amounts.d.ts
-export type NumericAmount = string | BigNumber;
-export type SqrtPrice = Brand<BigNumber, 'SqrtPrice'>;
-export type SqrtPriceIn = Brand<NumericAmount, 'SqrtPriceIn'> | SqrtPrice;
-export type Price = Brand<BigNumber, 'Price'>;
-export type PriceIn = Brand<NumericAmount, 'PriceIn'> | Price;
-//#endregion
-//#region src/classes/positions.d.ts
-type PositionGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
-  submit: (method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<SubmittedTransaction<Position | null>>;
-  requestTimeoutMs?: number | undefined;
-};
-type PositionSymbols = Pick<Symbols, 'resolve' | 'orderPair'> & {
-  invalidate?: () => void;
-};
-/**
- * Manages current-contract concentrated-liquidity positions.
- *
- * @example
- * ```typescript
- * const positions = gSwap.positions;
- * const mine = await positions.getUserPositions('client|012345678901234567890123');
- * console.log(mine.length);
- * ```
- */
-export declare class Positions {
-  private readonly gateway;
-  private readonly symbols;
-  private readonly signer?;
-  private readonly walletAddress?;
-  constructor(gateway: PositionGateway, symbols: PositionSymbols, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined);
-  private readonly http;
+  getPosition(args: {
+    token0: TokenRef;
+    token1: TokenRef;
+    fee: FEE_TIER;
+    owner: string;
+    tickLower: number;
+    tickUpper: number;
+  }, signal?: AbortSignal): Promise<Position | null>;
   /**
-   * Gets all current-contract positions owned by an address.
+   * Reads one position and classifies the outcome instead of throwing: `found` with the position
+   * (fees included), `not_found` (the backend's HTTP 404, which it sends only when the chain
+   * itself has no such position) or `unknown` (any other failure, carried as `error`). Use it
+   * to confirm a write: `unknown` is "no evidence either way", never a confirmed absence.
    *
-   * @param owner - GalaChain owner identity.
-   * @returns Enriched positions from the v2 trade backend.
-   * @example
-   * ```typescript
-   * const positions = await gSwap.positions.getUserPositions('client|012345678901234567890123');
-   * ```
-   */
-  getUserPositions(owner: string): Promise<Position[]>;
-  /**
-   * Gets one position, normalizing a caller-supplied reversed pair to canonical symbol order.
-   * Reversed pairs also invert the price axis, so `[lower, upper]` becomes `[-upper, -lower]`.
+   * Only the caller's own abort rethrows. With a pass-through resolver ({@link CanonicalSymbols})
+   * the pair and ticks go to the backend exactly as given and the backend orients them.
    *
-   * @param args - Pair, owner, fee, and position tick range.
-   * @returns The position, or `null` when the backend returns 404.
    * @example
    * ```typescript
-   * const position = await gSwap.positions.getPosition({
+   * const read = await gSwap.positions.readPosition({
    *   token0: 'GALA', token1: 'GUSDC', owner: 'client|012345678901234567890123',
    *   fee: 3000, tickLower: -19200, tickUpper: 12000,
    * });
+   * if (read.kind === 'found') console.log(read.data.fees0);
    * ```
    */
-  getPosition(args: {
+  readPosition(args: {
     token0: TokenRef;
     token1: TokenRef;
     fee: FEE_TIER;
     owner: string;
     tickLower: number;
     tickUpper: number;
-  }, signal?: AbortSignal): Promise<Position | null>;
+  }, signal?: AbortSignal): Promise<PositionRead>;
+  /**
+   * The `/position` query: canonical symbols and canonical ticks after a client-side flip, or,
+   * for a pass-through resolver, the caller's references and ticks untouched.
+   */
+  private positionParams;
   /**
    * Estimates the other token amount and resulting liquidity for a deposit.
    *
@@ -1033,15 +1966,28 @@ export declare class Positions {
    * await tx.confirm();
    * ```
    */
-  addLiquidityByTicks(args: {
-    token0: TokenRef;
-    token1: TokenRef;
-    fee: FEE_TIER;
-    tickLower: number;
-    tickUpper: number;
-    amount: NumericAmount;
-    amountIsToken0: boolean;
-  }): Promise<SubmittedTransaction<Position | null>>;
+  addLiquidityByTicks(args: AddLiquidityArgs): Promise<SubmittedTransaction<Position | null>>;
+  /**
+   * Builds the AddLiquidity DTO that {@link addLiquidityByTicks} would sign, without signing or
+   * sending it: to show in an approval popup, or to sign elsewhere. Submit exactly this DTO with
+   * {@link submitAddLiquidity}. The pure counterpart, with canonical inputs and no resolution,
+   * is `buildAddLiquidityDto`.
+   *
+   * @example
+   * ```typescript
+   * const dto = await gSwap.positions.buildAddLiquidity({
+   *   token0: 'GALA', token1: 'GUSDC', fee: 3000,
+   *   tickLower: -19200, tickUpper: 12000, amount: '100', amountIsToken0: true,
+   * });
+   * ```
+   */
+  buildAddLiquidity(args: AddLiquidityArgs): Promise<AddLiquidityDTO>;
+  /**
+   * Signs and submits a DTO built by {@link buildAddLiquidity} or `buildAddLiquidityDto`; it must
+   * be exactly what the builder produces. The returned transaction confirms by proving the
+   * position's liquidity grew.
+   */
+  submitAddLiquidity(dto: AddLiquidityDTO): Promise<SubmittedTransaction<Position | null>>;
   /**
    * Adds liquidity from prices, flooring the lower tick and ceiling the upper tick to fee spacing.
    * The resulting range is therefore no narrower than the requested price interval.
@@ -1064,6 +2010,8 @@ export declare class Positions {
     maxPrice: PriceIn;
     amount: NumericAmount;
     amountIsToken0: boolean;
+    /** The attempt's `uniqueKey`; default a fresh one (see {@link AddLiquidityArgs.uniqueKey}). */
+    uniqueKey?: string | undefined;
   }): Promise<SubmittedTransaction<Position | null>>;
   /**
    * Removes liquidity by withdrawing at most one canonical token quantity.
@@ -1079,15 +2027,19 @@ export declare class Positions {
    * });
    * ```
    */
-  removeLiquidity(args: {
-    token0: TokenRef;
-    token1: TokenRef;
-    fee: FEE_TIER;
-    tickLower: number;
-    tickUpper: number;
-    amount0?: NumericAmount | undefined;
-    amount1?: NumericAmount | undefined;
-  }): Promise<SubmittedTransaction<Position | null>>;
+  removeLiquidity(args: RemoveLiquidityArgs): Promise<SubmittedTransaction<Position | null>>;
+  /**
+   * Builds the RemoveLiquidity DTO that {@link removeLiquidity} would sign, without signing or
+   * sending it. Submit exactly this DTO with {@link submitRemoveLiquidity}. The pure counterpart
+   * is `buildRemoveLiquidityDto`.
+   */
+  buildRemoveLiquidity(args: RemoveLiquidityArgs): Promise<RemoveLiquidityDTO>;
+  /**
+   * Signs and submits a DTO built by {@link buildRemoveLiquidity} or `buildRemoveLiquidityDto`;
+   * it must be exactly what the builder produces. A DTO with no withdrawal quantity closes the
+   * position, and the returned transaction then confirms by proving the position is gone.
+   */
+  submitRemoveLiquidity(dto: RemoveLiquidityDTO): Promise<SubmittedTransaction<Position | null>>;
   /**
    * Collects all accrued fees for a position; the contract does not support partial collection.
    *
@@ -1101,13 +2053,18 @@ export declare class Positions {
    * });
    * ```
    */
-  collectPositionFees(args: {
-    token0: TokenRef;
-    token1: TokenRef;
-    fee: FEE_TIER;
-    tickLower: number;
-    tickUpper: number;
-  }): Promise<SubmittedTransaction<Position | null>>;
+  collectPositionFees(args: CollectPositionFeesArgs): Promise<SubmittedTransaction<Position | null>>;
+  /**
+   * Builds the CollectPositionFees DTO that {@link collectPositionFees} would sign, without
+   * signing or sending it. Submit exactly this DTO with {@link submitCollectPositionFees}. The
+   * pure counterpart is `buildCollectPositionFeesDto`.
+   */
+  buildCollectPositionFees(args: CollectPositionFeesArgs): Promise<CollectPositionFeesDTO>;
+  /**
+   * Signs and submits a DTO built by {@link buildCollectPositionFees} or
+   * `buildCollectPositionFeesDto`; it must be exactly what the builder produces.
+   */
+  submitCollectPositionFees(dto: CollectPositionFeesDTO): Promise<SubmittedTransaction<Position | null>>;
   /**
    * Creates a pool, resolving registered trading symbols.
    * Reversed symbol order inverts the supplied starting price or square-root price.
@@ -1129,17 +2086,20 @@ export declare class Positions {
    * });
    * ```
    */
-  createPool(args: {
-    token0: TokenRef;
-    token1: TokenRef;
-    token0Symbol?: string | undefined;
-    token1Symbol?: string | undefined;
-    fee: FEE_TIER;
-    startingPrice?: NumericAmount | undefined;
-    startingSqrtPrice?: NumericAmount | undefined;
-    isPrivate?: boolean | undefined;
-    privateAccess?: string[] | undefined;
-  }): Promise<SubmittedTransaction<Position | null>>;
+  createPool(args: CreatePoolArgs): Promise<SubmittedTransaction<Position | null>>;
+  /**
+   * Builds the CreatePool DTO that {@link createPool} would sign, without signing or sending it:
+   * symbols resolved or proposed, the pair put in canonical order and the price inverted when it
+   * was reversed. Submit exactly this DTO with {@link submitCreatePool}. The pure counterpart,
+   * with canonical inputs, is `buildCreatePoolDto`.
+   */
+  buildCreatePool(args: CreatePoolArgs): Promise<CreatePoolDTO>;
+  /**
+   * Signs and submits a DTO built by {@link buildCreatePool} or `buildCreatePoolDto`; it must be
+   * exactly what the builder produces. The returned transaction confirms by the pool existing, and
+   * the cached symbol registry is dropped, since the pool may have registered new symbols.
+   */
+  submitCreatePool(dto: CreatePoolDTO): Promise<SubmittedTransaction<Position | null>>;
   private submit;
   /**
    * Builds a confirmation closure that proves the write's own effect, not just that a
@@ -1157,32 +2117,35 @@ export declare class Positions {
   private get;
   private getNullable;
   private isNotFound;
-  private mapPosition;
-  private requestToken;
   private canonicalTicks;
   private tickSpacing;
   private rejectNumber;
-  private uniqueKey;
+  /** The caller's `uniqueKey` (validated), else a fresh one. */
+  private uniqueKeyFor;
   private resolveCreateToken;
   private tryParseClassKey;
 }
 //#endregion
 //#region src/classes/quoting.d.ts
-type QuoteSymbols = Pick<Symbols, 'resolve'>;
+/** The transport a quote service reads through: the same shape `Pools` and `Symbols` take. */
+type QuoteGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
+  requestTimeoutMs?: number | undefined;
+  wire?: WireOptions | undefined;
+};
 /** Read-only quote service backed by the v2 offline quote engine. */
 export declare class Quoting {
-  private readonly dexBackendBaseUrl;
-  private readonly http;
+  private readonly gateway;
   private readonly symbols;
   /**
    * Creates a quote service.
    *
    * @example
    * ```ts
-   * const quoting = new Quoting('https://swap-backend.stage.defi.ovh.gala.com', http, symbols);
+   * const quoting = new Quoting(gateway, symbols); // a ChainGateway, or any { dexBackendBaseUrl, httpRequestor }
    * ```
    */
-  constructor(dexBackendBaseUrl: string, http: HttpClient, symbols: QuoteSymbols);
+  constructor(gateway: QuoteGateway, symbols: TokenResolver);
+  private readonly http;
   /**
    * Quotes the output for a positive exact-input amount.
    *
@@ -1207,24 +2170,52 @@ export declare class Quoting {
 }
 //#endregion
 //#region src/classes/swaps.d.ts
-export type SwapAmount = {
-  exactIn: NumericAmount;
-  exactOut?: undefined;
-  amountOutMinimum?: NumericAmount | undefined;
-  amountInMaximum?: undefined;
-} | {
-  exactIn?: undefined;
-  exactOut: NumericAmount;
-  amountOutMinimum?: undefined;
-  amountInMaximum?: NumericAmount | undefined;
-};
 interface SwapGateway {
   submit: (method: 'RequestTrade', signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<SubmittedTransaction<AppliedTrade>>;
+  submitShadow: (method: 'RequestTrade', signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<ShadowSubmitResult>;
   readonly dexBackendBaseUrl: string;
   readonly httpRequestor: HttpRequestor;
   readonly requestTimeoutMs: number;
+  readonly wire?: WireOptions | undefined;
+}
+/** The canonical pool a swap trades in, as a quote names it. */
+export interface SwapPool {
+  token0: string;
+  token1: string;
+}
+/** Options of a swap. */
+export interface SwapOptions {
+  /**
+   * The attempt's `uniqueKey` (1-128 characters of `A-Za-z0-9._:-`). Default: a fresh
+   * `<uniqueKeyPrefix><uuid>`. Supply one to know the key before signing (to remember it, to
+   * show it), or to retry the SAME attempt after a lost response; never reuse it for another trade.
+   */
+  uniqueKey?: string | undefined;
+  /**
+   * Pin the pool: take `token0` / `token1` verbatim from the quote the user saw, instead of
+   * ordering `tokenIn` / `tokenOut` by string comparison. `tokenIn` and `tokenOut` must be exactly
+   * these two symbols, and `token0` must sort before `token1`. See {@link swapRouteFromQuote}.
+   */
+  pool?: SwapPool | undefined;
+}
+/** Everything {@link Swaps.swap} needs to trade in the pool a quote priced. */
+export interface SwapRoute {
+  tokenIn: string;
+  tokenOut: string;
+  fee: FEE_TIER;
+  pool: SwapPool;
 }
-type SwapSymbols = Pick<Symbols, 'resolve'>;
+/**
+ * The route of a quote: its fee tier and pool, with `tokenIn` / `tokenOut` taken from
+ * `tokenInIsToken0`, nothing re-derived. Use it to swap in exactly the pool a quote priced:
+ *
+ * @example
+ * ```ts
+ * const route = swapRouteFromQuote(quote);
+ * await swaps.swap(route.tokenIn, route.tokenOut, route.fee, { exactIn: '100' }, { pool: route.pool });
+ * ```
+ */
+export declare function swapRouteFromQuote(quote: Pick<QuoteResult, 'token0Symbol' | 'token1Symbol' | 'tokenInIsToken0' | 'fee'>): SwapRoute;
 /** Executes queued current-contract RequestTrade operations through the Chain Gateway. */
 export declare class Swaps {
   private readonly gateway;
@@ -1239,7 +2230,8 @@ export declare class Swaps {
    * const swaps = new Swaps(gateway, symbols, signer, 'client|alice');
    * ```
    */
-  constructor(gateway: SwapGateway, symbols: SwapSymbols, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined);
+  constructor(gateway: SwapGateway, symbols: TokenResolver, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined, options?: UniqueKeyOptions);
+  private readonly uniqueKeyPrefix;
   /**
    * Signs and submits an exact-input or exact-output RequestTrade DTO. The returned transaction
    * is QUEUED; call `await tx.confirm()` to obtain the executed trade or chain rejection.
@@ -1252,7 +2244,54 @@ export declare class Swaps {
    * });
    * ```
    */
-  swap(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount): Promise<SubmittedTransaction<AppliedTrade>>;
+  swap(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount, options?: SwapOptions): Promise<SubmittedTransaction<AppliedTrade>>;
+  /**
+   * Signs and submits a SHADOW (dark) swap: the same RequestTrade as {@link swap}, relayed with
+   * `X-Shadow: true` so defi-backend marks it private before it reaches the contract. Requires a
+   * `walletAddress`. Resolves the normalized outcome instead of throwing on a gateway refusal:
+   * `ok: false` carries `unavailable` (retryable), `disabled`, `rejected` (with the gateway's
+   * message) or `unknown`. A success carries `queued`, to be confirmed with
+   * `confirmSwap(queued.uniqueKey)`; never fall back to a public swap on failure.
+   *
+   * @example
+   * ```ts
+   * const outcome = await swaps.swapShadow('GALA', 'GUSDC', 3000, { exactIn: '100' });
+   * if (outcome.ok && outcome.queued) await swaps.confirmSwap(outcome.queued.uniqueKey);
+   * ```
+   */
+  swapShadow(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount, options?: SwapOptions): Promise<ShadowSubmitOutcome>;
+  /**
+   * Builds the RequestTrade DTO that {@link swap} would sign, without signing or sending it: to
+   * show in an approval popup, to remember its `uniqueKey`, or to sign elsewhere. Submit exactly
+   * this DTO with {@link submitSwap}. The pure counterpart, with canonical inputs and no
+   * resolution, is `buildRequestTradeDto`.
+   *
+   * @example
+   * ```ts
+   * const dto = await swaps.buildSwap('GALA', 'GUSDC', 3000, { exactIn: '100' });
+   * showApproval(dto);
+   * const submitted = await swaps.submitSwap(dto);
+   * ```
+   */
+  buildSwap(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount, options?: SwapOptions): Promise<RequestTradeDTO>;
+  /**
+   * Signs and submits a DTO built by {@link buildSwap} or `buildRequestTradeDto`. The DTO must be
+   * exactly what the builder produces (no signature, canonical decimals, builder key order), so
+   * what an app showed is what gets signed.
+   *
+   * @example
+   * ```ts
+   * const submitted = await swaps.submitSwap(dto);
+   * const applied = await submitted.confirm();
+   * ```
+   */
+  submitSwap(dto: RequestTradeDTO): Promise<SubmittedTransaction<AppliedTrade>>;
+  /** Signs and shadow-submits a DTO built by {@link buildSwap}; see {@link swapShadow}. */
+  submitSwapShadow(dto: RequestTradeDTO): Promise<ShadowSubmitOutcome>;
+  private submitOptions;
+  private signRequestTrade;
+  /** The pool's two symbols in contract order: the quote's own when pinned, else string order. */
+  private orientPool;
   /**
    * Confirm a swap by its durable `uniqueKey` without resubmitting it. This is the recovery
    * path after a `CONFIRMATION_TIMEOUT`, a `SUBMISSION_OUTCOME_UNKNOWN`, a `409` replay
@@ -1263,11 +2302,10 @@ export declare class Swaps {
    *
    * @example
    * ```ts
-   * const applied = await swaps.confirmSwap('gswap-sdk-2f1c…');
+   * const applied = await swaps.confirmSwap('galaswap-operation-2f1c…');
    * ```
    */
   confirmSwap(uniqueKey: string, options?: ConfirmOptions): Promise<AppliedTrade>;
-  private buildRequestTradeDto;
 }
 //#endregion
 //#region src/types/env.d.ts
@@ -1290,11 +2328,37 @@ export interface GSwapOptions {
   env?: GSwapEnv | undefined;
   dexBackendBaseUrl?: string | undefined;
   httpRequestor?: HttpRequestor | undefined;
+  /** Request timeout in milliseconds (default 30 000); `Infinity` arms no timer. */
   chainCallTimeoutMs?: number | undefined;
+  /** Query encoding and `User-Agent` of the read requests (see {@link WireOptions}). */
+  wire?: WireOptions | undefined;
+  /**
+   * How tokens are turned into trading symbols. `'registry'` (default) reads the symbol registry
+   * once (`GET /v2/trade/symbols`, cached) and accepts symbols or class keys. `'canonical'` makes
+   * no registry request: the caller passes the backend's canonical trading symbols (from a quote,
+   * an estimate or a position), reads send tokens and ticks exactly as given (composite keys
+   * included) and the backend orients the pair; see {@link CanonicalSymbols}.
+   */
+  symbolResolution?: 'registry' | 'canonical' | undefined;
+  /**
+   * Told about every row of a pool, symbol or position list that was skipped as unusable (see
+   * {@link InvalidEntryHandler}); without it such rows are skipped silently.
+   */
+  onInvalidEntry?: InvalidEntryHandler | undefined;
   /** Realtime stream endpoint. Defaults to the environment's, or is derived from `dexBackendBaseUrl`. */
   dexBackendWsUrl?: string | undefined;
   /** WebSocket constructor for the realtime stream; required on Node.js older than 22. */
   webSocketImpl?: unknown;
+  /**
+   * `x-api-key` for the privileged stream view; server-side only, and it requires `webSocketImpl`
+   * (see `GdexStreamConfig.apiKey`).
+   */
+  streamApiKey?: string | undefined;
+  /**
+   * Prefix of every write's `uniqueKey` (`<prefix><uuid>`). Defaults to `galaswap-operation-`,
+   * what frontend_v2 and wallet_extension send; defi-backend does not depend on it.
+   */
+  uniqueKeyPrefix?: string | undefined;
 }
 /** Main entry point for the current GalaChainDex SDK. */
 export declare class GSwap {
@@ -1309,8 +2373,11 @@ export declare class GSwap {
   readonly positions: Positions;
   readonly swaps: Swaps;
   readonly assets: Assets;
+  /** Network-fee quotes (DryRun) signed with this client's signer. */
+  readonly fees: DexFees;
   readonly dexBackendWsUrl: string;
   private readonly webSocketImpl;
+  private readonly streamApiKey;
   private streamClient;
   /**
    * Create an SDK client for prod or stage.
@@ -1336,141 +2403,583 @@ export declare class GSwap {
   get stream(): GdexStreamService;
 }
 //#endregion
-//#region src/classes/gswap_sdk_error.d.ts
-/** Error raised by the SDK for validation, gateway, chain, or transaction failures. */
-export declare class GSwapSDKError extends Error {
-  readonly code: string;
-  readonly details?: Record<string, unknown> | undefined;
-  readonly chainMessage: string | undefined;
-  readonly retryAfterMs: number | undefined;
-  constructor(message: string, code: string, details?: Record<string, unknown> | undefined, chainMessage?: string, retryAfterMs?: number);
-  /** Create the standard missing-signer error. */
-  static noSignerError(): GSwapSDKError;
-  /** Create the error used when confirming a position write without a configured wallet address. */
-  static noWalletAddressError(): GSwapSDKError;
-  /** Create the error used when no pool can quote the requested pair. */
-  static noPoolAvailableError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number): GSwapSDKError;
-  /** Create the error used when a pool lacks liquidity for a quote. */
-  static insufficientLiquidityError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number): GSwapSDKError;
-  /** Convert a chain-gateway bounce into a typed SDK error. */
-  static fromGatewayBounce(code: string, message: string, status: number, retryAfterMs?: number): GSwapSDKError;
-  /** Convert a GalaChain `Status: 0` response into a typed SDK error. */
-  static fromChainError(errorKey: string, message: string, details?: Record<string, unknown>): GSwapSDKError;
-  /** Create the error used when a token is not registered by the current DEX contract. */
-  static unknownTokenError(token: GalaChainTokenClassKey | string): GSwapSDKError;
-  /** Create the error used when apply-results confirmation does not arrive in time. */
-  static confirmationTimeoutError(uniqueKey: string, cause?: unknown): GSwapSDKError;
-  /** Convert an unexpected HTTP response into an SDK error. */
-  static fromErrorResponse(url: string, response: HTTPResponse): Promise<GSwapSDKError>;
+//#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;
+/**
+ * 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.
+ * - 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}).
+ */
+export interface StorageAdapter {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+}
+/** A RequestTrade that was accepted by the gateway but whose outcome has not been read yet. */
+export interface PendingSwap {
+  uniqueKey: string;
+  requestTransactionId: string | null;
+  /** The wallet (account) that submitted the swap; `list` filters by it. */
+  wallet: string;
+  token0Symbol: string;
+  token1Symbol: string;
+  /** Whether the swap was a shadow ("dark") swap. */
+  isDarkSwap: boolean;
+  /** Epoch milliseconds when the swap was queued. */
+  createdAt: number;
+}
+/** Options for {@link PendingSwapStore}. */
+export interface PendingSwapStoreOptions {
+  /** Storage key. Default {@link PENDING_SWAPS_STORAGE_KEY}. */
+  storageKey?: string | undefined;
+  /**
+   * The stored name of the dark-swap flag. `isDarkSwap` (default) is wallet_extension's shape;
+   * `shadow` is frontend_v2's. Entries are always exposed to callers as `isDarkSwap`.
+   */
+  darkFlagField?: 'isDarkSwap' | 'shadow' | undefined;
+  /**
+   * Where `remember` puts a new entry in the stored array: `end` (default, wallet_extension) or
+   * `start` (frontend_v2).
+   */
+  insertAt?: 'end' | 'start' | undefined;
+  /**
+   * The order of `list`: `stored` (default, wallet_extension: oldest first for `insertAt: 'end'`)
+   * or `newest-first` (frontend_v2).
+   */
+  listOrder?: 'stored' | 'newest-first' | undefined;
+  /** Clock, in epoch milliseconds. Defaults to `Date.now`. */
+  now?: (() => number) | undefined;
+}
+/**
+ * Remembers queued swaps so their outcome can be confirmed after the UI, popup or service worker
+ * that submitted them is gone (`confirmAppliedTrade` with the stored `uniqueKey`).
+ *
+ * Guarantees:
+ * - Persistence is best effort and NEVER throws: a failing or missing storage must not turn an
+ *   accepted request into a client-side resubmission. `list` resolves `[]` when storage fails.
+ * - Operations of one store instance are serialized, so concurrent `remember` / `forget` calls
+ *   cannot lose each other's write (read-modify-write over an async adapter). Two store instances
+ *   over the same storage (for example popup and service worker) are not coordinated.
+ * - Entries that do not match the expected shape are ignored and dropped on the next write.
+ * - Entries expire after seven days (an entry exactly seven days old is expired; frontend_v2
+ *   kept it for that one millisecond); `list` removes them from storage, which frontend_v2 never
+ *   did on read.
+ * - New entries go to the end (or `insertAt: 'start'`); `list` returns the wallet's entries in
+ *   stored order (or `listOrder: 'newest-first'`).
+ * - The stored shape is wallet_extension's by default; `storageKey`, `darkFlagField`, `insertAt`
+ *   and `listOrder` reproduce frontend_v2's. JSON key order inside an entry is not preserved.
+ *
+ * Passing no `storage` yields a store that remembers nothing.
+ *
+ * @example
+ * ```ts
+ * const store = new PendingSwapStore({
+ *   get: async (key) => (await chrome.storage.local.get(key))[key],
+ *   set: (key, value) => chrome.storage.local.set({ [key]: value }),
+ * });
+ * await store.remember({ uniqueKey, requestTransactionId, wallet, token0Symbol: 'GALA',
+ *   token1Symbol: 'GUSDC', isDarkSwap: false, createdAt: Date.now() });
+ * for (const swap of await store.list(wallet)) await confirmAppliedTrade(client, swap);
+ * ```
+ */
+export declare class PendingSwapStore {
+  private readonly storage;
+  private readonly storageKey;
+  private readonly darkFlagField;
+  private readonly insertAt;
+  private readonly listOrder;
+  private readonly now;
+  private queue;
+  constructor(storage: StorageAdapter | undefined, options?: PendingSwapStoreOptions);
+  /** Saves (or replaces, by `uniqueKey`) a pending swap. */
+  remember(swap: PendingSwap): Promise<void>;
+  /** Removes a pending swap once its outcome is known. */
+  forget(uniqueKey: string): Promise<void>;
+  /** The wallet's unexpired pending swaps (see `listOrder`). Expired entries are pruned. */
+  list(wallet: string): Promise<PendingSwap[]>;
+  private enqueue;
+  private read;
+  private readonly toStored;
+  private fromStored;
 }
-/** Narrow an object property without trusting a cast at a network boundary. */
-export declare function getObjectProperty(value: unknown, property: string): Record<string, unknown> | undefined;
-/** Read a string property from an unknown object. */
-export declare function getStringProperty(value: unknown, property: string): string | undefined;
-/** Parse a response body, preserving non-JSON text for error reporting. */
-export declare function parseJson(text: string): unknown;
 //#endregion
-//#region src/types/v2_dtos.d.ts
-/** Common identity fields for v2 pool writes. */
-export interface V2PoolWriteBase {
+//#region src/utils/signing.d.ts
+/**
+ * GalaChain's deterministic JSON: object keys sorted (UTF-16 code-unit order) at every depth, no
+ * whitespace, `undefined`/function members dropped, `toJSON()` honored. Byte-identical to
+ * `serialize` from `@gala-chain/api` / `json-stringify-deterministic` for every JSON-shaped
+ * value, which is all a DTO ever is.
+ *
+ * @throws TypeError for circular structures and BigInt values (as `JSON.stringify` does) and
+ * when the value itself has no JSON representation (`undefined`, a function, a symbol).
+ */
+export declare function serialize(value: unknown): string;
+/**
+ * The exact string GalaChain hashes for a DTO: the (optional, string) `prefix` field PREPENDED to
+ * the deterministic serialization of the DTO WITHOUT `signature`, `multisig`, `trace` and `prefix`.
+ * Equivalent to `@gala-chain/api` 3.x `getPayloadToSign` for every non-EIP-712 DTO.
+ */
+export declare function getPayloadToSign(dto: Record<string, unknown>): string;
+/**
+ * The EIP-191 header for `message`: `"\x19Ethereum Signed Message:\n"` + the message's UTF-8 BYTE
+ * length. This is what a wallet's `personal_sign` prepends, and what the chain recomputes when it
+ * recovers a personal-signed DTO.
+ */
+export declare function calculatePersonalSignPrefix(message: string): string;
+/**
+ * The EIP-191 header for `serialize(dto)` (any `prefix` already on the DTO is ignored). This is
+ * deliberately the same string the signers hand a wallet to sign, so the header's length can never
+ * disagree with the signed message. Wallet-neutral: it is the value both a browser wallet's
+ * `personal_sign` and Gala Wallet's `gala_signChainDto` (personal-sign scheme) prepend.
+ */
+export declare function personalSignPrefixFor(dto: Record<string, unknown>): string;
+/**
+ * The `@gala-chain/connect`-style prefix frontend_v2 puts in the body of an EIP-712 write: the
+ * EIP-191 header whose number counts the prefix string ITSELF plus the body (the UTF-8 length of
+ * `getPayloadToSign({ ...dto, prefix })`), found by fixpoint because adding the prefix changes the
+ * length (a body of 99 bytes settles on 101).
+ *
+ * It is NOT a personal-sign prefix (a personal-sign write with this value recovers a phantom
+ * signer; use `personalSignPrefixFor`). Under EIP-712 the field is an untyped extra that the
+ * typed-data hash ignores and defi-backend recomputes, so it only exists to keep the submitted
+ * body byte-identical to what frontend_v2 has always sent.
+ */
+export declare function fixpointPrefixFor(dto: Record<string, unknown>): string;
+/**
+ * Normalizes a secp256k1 private key to a fresh 32-byte array (the caller may zero it). Also
+ * accepts 32 raw bytes, which are validated and copied. For strings it accepts what `@gala-chain/api`'s
+ * `normalizePrivateKey` accepted for a usable key: 64 hex characters (optionally `0x`-prefixed;
+ * a 63-character hex key is left-padded with a zero) or a 44-character base64 string.
+ *
+ * @throws GSwapSDKError (`VALIDATION_ERROR`) for any other shape or an out-of-range scalar.
+ */
+export declare function normalizePrivateKey(input: string | Uint8Array): Uint8Array;
+/**
+ * The lowercase `0x` Ethereum address (last 20 bytes of keccak256 of the uncompressed public key)
+ * of a normalized private key. The Gala `eth|` identity of a key is this address.
+ */
+export declare function ethAddressOfPrivateKey(privateKey: Uint8Array): string;
+/**
+ * GalaChain NATIVE signature over an already-serialized DTO: keccak256 of the exact bytes, with no
+ * prefix and no signature envelope. The caller owns serialization, so the bytes shown to a user
+ * and the bytes signed can never diverge.
+ */
+export declare function signSerializedNative(privateKey: Uint8Array, serializedDto: string): string;
+/**
+ * GalaChain NATIVE signature for a DTO: keccak256 of `getPayloadToSign(dto)`, signed with
+ * secp256k1. Byte-identical to `signatures.getSignature` from `@gala-chain/api`.
+ */
+export declare function signNative(privateKey: Uint8Array, dto: Record<string, unknown>): string;
+/**
+ * Personal-sign hash and signature: keccak256(`prefix` + `message`), both hashed VERBATIM with no
+ * further EIP-191 wrapping. Passing `prefix = calculatePersonalSignPrefix(message)` reproduces a
+ * wallet's `personal_sign` of `message`. Gala Wallet's `gala_signChainDto` (personal-sign
+ * scheme) hashes `prefix` + the exact string it is handed, which can differ from the bare message
+ * (see the `signatureOverPrefixlessBody` vectors); that quirk is why the two inputs stay separate.
+ */
+export declare function signPersonalMessage(privateKey: Uint8Array, prefix: string, message: string): string;
+//#endregion
+//#region src/utils/chain_dto_signing.d.ts
+/** A secp256k1 private key as a hex/base64 string or as raw 32 bytes. */
+type PrivateKeyInput = string | Uint8Array;
+/**
+ * Runs `action` with a private normalized copy of the key, zeroed afterwards (also when `action`
+ * throws). Bytes given by the caller are copied, never modified: the caller owns them.
+ */
+export declare function withPrivateKey<T>(privateKey: PrivateKeyInput, action: (key: Uint8Array) => T): T;
+/**
+ * GalaChain NATIVE signature over an already-serialized DTO: keccak256 of the exact bytes with no
+ * prefix and no envelope (wallet `signChainDtoNative`). The caller owns serialization, so the
+ * bytes a user reviewed and the bytes signed cannot diverge.
+ *
+ * @returns 130 lowercase hex characters, `r || s || v` with `v` = `1b`/`1c`, no `0x`.
+ */
+export declare function signChainDtoNative(privateKey: PrivateKeyInput, serializedDto: string): string;
+/**
+ * The personal-sign hash primitive (wallet `signChainDtoHash`): keccak256(`prefix` + `message`),
+ * both verbatim, with no further EIP-191 wrap. `message` must be the DTO's serialization WITHOUT
+ * its `prefix` field; callers holding a dApp-supplied string go through `signChainDtoPersonalSign`,
+ * which derives both inputs from it.
+ */
+export declare function signChainDtoHash(privateKey: PrivateKeyInput, prefix: string, message: string): string;
+/** What a `gala_signChainDto` personal-sign request hashes. */
+interface PersonalSignChainDtoPayload {
+  /** The `prefix` the chain prepends: the DTO's own `prefix` field, or `''` when it has none. */
+  prefix: string;
+  /** The exact message hashed after `prefix`. */
+  message: string;
+}
+/**
+ * Derives what to hash for a `gala_signChainDto` personal-sign request from the exact string the
+ * dApp sent (and the approval card displayed): wallet `resolvePersonalSignChainDtoPayload`.
+ *
+ * The dApp submits `{ ...dto, prefix, signature }`, which the chain recovers from
+ * `keccak256(prefix + serialize(dto WITHOUT prefix))`. So when the string embeds a `prefix`
+ * field, that field is removed and the remainder re-serialized; the prefix used is the dApp's own
+ * value byte for byte. A string with no `prefix` field is hashed verbatim with an empty prefix
+ * (chain-equivalent to a native signature of that exact string).
+ *
+ * Fails closed (throws `GSwapSDKError` `INVALID_PERSONAL_SIGN_DTO`, message text identical to the
+ * wallet's) on: malformed JSON; JSON that is not a plain object; a `prefix` that is not an EIP-191
+ * "Ethereum Signed Message" header; any signing-envelope field (`signature`, `multisig`, `trace`,
+ * `types`, `domain`, `stringsInstructions`); and a string that is not already the canonical
+ * serialization of what it parses to (duplicate keys, lossy numbers, key-order tricks the card
+ * would render differently). Stripping `prefix` is therefore the ONLY byte change between the
+ * reviewed string and the signed message.
+ */
+export declare function resolvePersonalSignChainDtoPayload(data: string): PersonalSignChainDtoPayload;
+/**
+ * Signs a GalaChain personal-sign scheme DTO from the exact string a dApp sent through
+ * `gala_signChainDto` (wallet `signChainDtoPersonalSign`). See
+ * `resolvePersonalSignChainDtoPayload` for what is signed and what is refused; the signature
+ * recovers, under the chain's `getPayloadToSign`, to this key for the DTO the dApp submits with
+ * its `prefix`, and equals a `personal_sign` of the bare body when that prefix is the EIP-191
+ * header of the bare body's byte length.
+ *
+ * @throws GSwapSDKError (`INVALID_PERSONAL_SIGN_DTO`) before any signing when the input is refused.
+ */
+export declare function signChainDtoPersonalSign(privateKey: PrivateKeyInput, data: string): string;
+/**
+ * Raw object signing (wallet `signObject`), used for transfers, bridge and fee-dry-run DTOs the
+ * wallet signs itself. Removes ONLY `signature`, signs `keccak256(serialize(rest))` natively
+ * (no `prefix` handling, and `trace` / `multisig` stay in the signed bytes, unlike
+ * `signNative`), and returns `{ signature, ...rest }` with the signature as the FIRST key, exactly
+ * like the wallet. Callers that must not sign extra fields strip them first.
+ */
+export declare function signRawObject(privateKey: PrivateKeyInput, obj: Record<string, unknown>): {
+  signature: string;
+} & Record<string, unknown>;
+/**
+ * Drops the `EIP712Domain` entry from a dApp-supplied types map (a typed-data encoder derives the
+ * domain type itself and rejects an explicit one). The order of the remaining types is preserved.
+ */
+export declare function stripEip712DomainType<T>(types: Record<string, T>): Record<string, T>;
+/**
+ * `collection$category$type$additionalKey` for a token-class object (wallet `decodeTokenData`).
+ * Lenient on purpose: any missing or non-string part becomes `''`, so a display layer never
+ * throws on odd input.
+ */
+export declare function tokenClassDollarKey(token: Record<string, unknown> | null | undefined): string;
+/**
+ * A quantity in the form GalaChain's `IsBigNumber` validator accepts: FIXED notation, no leading
+ * zeros, no trailing decimal zeros (`BigNumber#toFixed()`; never `toString()`, which turns
+ * `0.00000001` into `1e-8`, and never a JS number in between).
+ *
+ * @throws GSwapSDKError (`VALIDATION_ERROR`) for a value that is not a finite number. The wallet's
+ * `cleanNumber` returned the string `'NaN'` there; signing that text can only fail on chain.
+ */
+export declare function canonicalDecimalString(value: string | number): string;
+//#endregion
+//#region src/utils/eip712.d.ts
+type EIP712Types = Record<string, Array<{
+  name: string;
+  type: string;
+}>>;
+/**
+ * Derives the EIP-712 `types` for a DTO from its runtime shape.
+ *
+ * The generated `types` travel with the signed payload and are what BOTH sides hash, so they
+ * must enumerate EVERY field the chain-side DTO will carry. GalaChain refuses any signature
+ * whose `types` leave a DTO field uncovered (`assertNoUnsignedFields`, the fix for the
+ * 2026-08-18 unsigned-field-injection drain); when that happens signature recovery fails
+ * outright and the chain reports "Missing signerPublicKey or signerAddress field in dto".
+ */
+export declare function generateEIP712Types(typeName: string, params: Record<string, unknown>): EIP712Types;
+/** The EIP-712 domain carried by a signed payload: GalaChain only uses `name` and `chainId`. */
+interface EIP712DomainValue {
+  name: string;
+  chainId: number;
+}
+/**
+ * Builds the EIP-712 domain from the wallet's LIVE `eth_chainId` result, exactly like frontend_v2
+ * (DEFI-1895): a wallet hashes whatever domain it is handed, and MetaMask refuses a `chainId` that
+ * differs from its active network, so a hardcoded `1` breaks every wallet that is not on Mainnet.
+ * defi-backend recovers the signer from the `domain` the payload carries (live-proven for chain
+ * ids 1, 56 and 11155111), so following the wallet is correct on every network.
+ *
+ * @param chainId - The raw `eth_chainId` result: a `0x` hex string (the JSON-RPC form) or an integer.
+ * @throws GSwapSDKError (`INVALID_CHAIN_ID`) when the wallet answers with anything else.
+ */
+export declare function eip712DomainFor(chainId: unknown): EIP712DomainValue;
+/**
+ * The four v2 operations proven to recover the signer correctly via genuine EIP-712: `RequestTrade`
+ * never had the problem (one numeric field). `AddLiquidity`/`RemoveLiquidity`/
+ * `CollectPositionFees` each need their `types` completed with a handful of fields their real
+ * server-side DTO always carries — see the `complete*Fields` functions below. `CreatePool` is a
+ * genuinely different, unsolved problem (nested `TokenClassKey` structs, not a flat
+ * missing-field gap) and is NOT in this set — callers must keep using `personal-sign` for it.
+ */
+export declare const EIP712_CAPABLE_METHODS: ReadonlySet<string>;
+/**
+ * Completes a DTO's fields for EIP-712 signing (a no-op for methods with no known gap, e.g.
+ * `RequestTrade`) and derives its `types`. Exported separately from the signing call itself so tests
+ * can assert on the exact payload without needing a live provider.
+ */
+export declare function buildEIP712Payload(methodName: string, dto: Record<string, unknown>): {
+  completedDto: Record<string, unknown>;
+  types: EIP712Types;
+};
+//#endregion
+//#region src/utils/typed_data.d.ts
+/** A typed-data payload as `eth_signTypedData_v4` carries it, minus `primaryType` (it is inferred). */
+interface TypedDataPayload {
+  domain: Record<string, unknown>;
+  /** Struct definitions WITHOUT `EIP712Domain` (see `stripEip712DomainType`). */
+  types: Record<string, readonly unknown[]>;
+  message: Record<string, unknown>;
+}
+/**
+ * The EIP-712 digest `keccak256(0x1901 || domainSeparator || hashStruct(primaryType, message))`
+ * that a wallet signs for `eth_signTypedData_v4`. The primary type is inferred, as ethers does.
+ *
+ * @throws GSwapSDKError (`INVALID_TYPED_DATA`) for any type graph or value it cannot encode
+ * exactly (see the module note on strictness).
+ */
+export declare function hashTypedData(payload: TypedDataPayload): Uint8Array;
+/**
+ * Signs a dApp's EIP-712 typed-data approval (the wallet's `signTypedMessage` path), replacing
+ * `new ethers.Wallet(key).signTypedData(domain, types, message)`. `types` must already have
+ * `EIP712Domain` removed (`stripEip712DomainType`).
+ *
+ * @returns `0x` + r + s + v with `v` = `0x1b`/`0x1c` (27/28): ethers' serialized signature form,
+ * recoverable with `verifyTypedData` / `eth_signTypedData_v4` verifiers. Rejects (never throws
+ * synchronously) on invalid input.
+ */
+export declare function signTypedDataPayload(privateKey: PrivateKeyInput, payload: TypedDataPayload): Promise<string>;
+//#endregion
+//#region src/utils/dto_builders.d.ts
+/** The pool a RequestTrade trades in, its fee tier, the `uniqueKey` and what is traded. */
+type RequestTradeInput = {
+  /** Canonical pool symbols: `token0 < token1`. Take them from a quote verbatim. */
   token0: string;
   token1: string;
-  fee: FEE_TIER;
+  fee: number;
+  /** Which side of the pool is sold: `true` when the input token is `token0`. */
+  tokenInIsToken0: boolean;
   uniqueKey: string;
-}
-/** A v2 RequestTrade with exactly one selected trade-side quantity. */
-export type RequestTradeDTO = V2PoolWriteBase & ({
-  sell0Qty: string;
-  sell1Qty?: never;
-  buy0Qty?: never;
-  buy1Qty?: never;
-} | {
-  sell0Qty?: never;
-  sell1Qty: string;
-  buy0Qty?: never;
-  buy1Qty?: never;
-} | {
-  sell0Qty?: never;
-  sell1Qty?: never;
-  buy0Qty: string;
-  buy1Qty?: never;
-} | {
-  sell0Qty?: never;
-  sell1Qty?: never;
-  buy0Qty?: never;
-  buy1Qty: string;
-}) & {
-  amountOutMinimum?: string | undefined;
-  amountInMaximum?: string | undefined;
-};
-/** A v2 liquidity deposit with exactly one selected deposit quantity. */
-export type AddLiquidityDTO = V2PoolWriteBase & {
-  tickLower: number;
-  tickUpper: number;
-} & ({
-  depositQuantityToken0: string;
-  depositQuantityToken1?: never;
-} | {
-  depositQuantityToken0?: never;
-  depositQuantityToken1: string;
-});
-/** A v2 liquidity withdrawal; omitting both quantities closes the position. */
-export type RemoveLiquidityDTO = V2PoolWriteBase & {
+} & SwapAmount;
+/**
+ * Builds the RequestTrade DTO: `exactIn` sells that much of the input token (`sell0Qty` or
+ * `sell1Qty`), `exactOut` buys that much of the output token (`buy1Qty` or `buy0Qty`), plus the
+ * side's slippage bound and an optional `priceLimit`. Key order: `token0, token1, fee, uniqueKey,
+ * <quantity>, amountOutMinimum | amountInMaximum, priceLimit`.
+ *
+ * @example
+ * ```ts
+ * const dto = buildRequestTradeDto({
+ *   token0: quote.token0Symbol, token1: quote.token1Symbol,
+ *   tokenInIsToken0: quote.tokenInIsToken0, fee: quote.fee,
+ *   uniqueKey: createUniqueKey('galaswap-operation-'),
+ *   exactIn: '100', amountOutMinimum: '14',
+ * });
+ * ```
+ */
+export declare function buildRequestTradeDto(input: RequestTradeInput): RequestTradeDTO;
+/** A canonical pool position: the pair, fee tier, tick range and the attempt's `uniqueKey`. */
+interface PoolPositionInput {
+  token0: string;
+  token1: string;
+  fee: number;
   tickLower: number;
   tickUpper: number;
-} & ({
-  withdrawalQuantityToken0: string;
-  withdrawalQuantityToken1?: never;
-} | {
-  withdrawalQuantityToken0?: never;
-  withdrawalQuantityToken1: string;
+  uniqueKey: string;
+}
+/** Exactly one canonical deposit side. */
+type AddLiquidityInput = PoolPositionInput & ({
+  depositQuantityToken0: NumericAmount;
+  depositQuantityToken1?: undefined;
 } | {
-  withdrawalQuantityToken0?: never;
-  withdrawalQuantityToken1?: never;
+  depositQuantityToken0?: undefined;
+  depositQuantityToken1: NumericAmount;
 });
-/** A v2 request to sweep all fees from one position. */
-export interface CollectPositionFeesDTO extends V2PoolWriteBase {
-  tickLower: number;
-  tickUpper: number;
-}
-/** A v2 pool creation request with exactly one initial-price representation. */
-export type CreatePoolDTO = {
+/**
+ * Builds the AddLiquidity DTO: exactly one of `depositQuantityToken0` / `depositQuantityToken1`
+ * (the other side is derived on chain). Key order: `token0, token1, fee, tickLower, tickUpper,
+ * uniqueKey, <deposit>`.
+ */
+export declare function buildAddLiquidityDto(input: AddLiquidityInput): AddLiquidityDTO;
+/** At most one canonical withdrawal side; neither closes the position. */
+type RemoveLiquidityInput = PoolPositionInput & {
+  withdrawalQuantityToken0?: NumericAmount | undefined;
+  withdrawalQuantityToken1?: NumericAmount | undefined;
+};
+/**
+ * Builds the RemoveLiquidity DTO: at most one of `withdrawalQuantityToken0` /
+ * `withdrawalQuantityToken1`; omitting both closes the position and sweeps its fees.
+ */
+export declare function buildRemoveLiquidityDto(input: RemoveLiquidityInput): RemoveLiquidityDTO;
+/** Builds the CollectPositionFees DTO (the contract sweeps all of a position's fees). */
+export declare function buildCollectPositionFeesDto(input: PoolPositionInput): CollectPositionFeesDTO;
+/** A CreatePool in canonical orientation, with exactly one starting price. */
+type CreatePoolInput = {
   token0Key: GalaChainTokenClassKey;
   token1Key: GalaChainTokenClassKey;
+  /** The symbols to register; `token0Symbol < token1Symbol` and both proposable. */
   token0Symbol: string;
   token1Symbol: string;
-  fee: FEE_TIER;
+  fee: number;
+  /** Optional display name; omitted when undefined or empty. */
+  name?: string | undefined;
   isPrivate?: boolean | undefined;
   privateAccess?: string[] | undefined;
   uniqueKey: string;
 } & ({
-  startingPrice: string;
-  startingSqrtPrice?: never;
+  startingPrice: NumericAmount;
+  startingSqrtPrice?: undefined;
 } | {
-  startingPrice?: never;
-  startingSqrtPrice: string;
+  startingPrice?: undefined;
+  startingSqrtPrice: NumericAmount;
 });
-/** Optional page cursor accepted by chain read methods. */
-export interface PageDTO {
-  limit?: number | undefined;
-  bookmark?: string | undefined;
+/**
+ * Builds the CreatePool DTO. Key order: `token0Key, token1Key, fee, startingPrice |
+ * startingSqrtPrice, token0Symbol, token1Symbol, uniqueKey, name, isPrivate, privateAccess`.
+ * Prices are those of the canonical pair (token1 per token0); a price quoted the other way round
+ * is inverted by the caller before it gets here.
+ */
+export declare function buildCreatePoolDto(input: CreatePoolInput): CreatePoolDTO;
+/** The methods whose DTOs the builders produce. */
+type V2WriteMethod = 'RequestTrade' | 'AddLiquidity' | 'RemoveLiquidity' | 'CollectPositionFees' | 'CreatePool';
+/**
+ * Asserts that `dto` is EXACTLY what the builder of `method` produces for its own fields — the
+ * same fields, canonical decimal text, builder key order, nothing extra (no `signature`). The
+ * `submit*` methods use it so that what an app showed a user (a DTO it built) is byte for byte
+ * what gets signed; a DTO edited by hand, or built elsewhere, is refused rather than signed.
+ *
+ * @throws GSwapSDKError VALIDATION_ERROR (`details.type` = `INVALID_DTO` or `DTO_NOT_CANONICAL`).
+ */
+export declare function assertCanonicalV2Dto(method: V2WriteMethod, dto: Record<string, unknown>): void;
+//#endregion
+//#region src/utils/axios_requestor.d.ts
+/** What the adapter reads of an axios response. */
+export interface AxiosLikeResponse {
+  status: number;
+  data?: unknown;
+  /** axios' `AxiosHeaders` (has `get`) or a plain header record. */
+  headers?: unknown;
 }
-/** Fetch all registered trading symbols. */
-export type FetchTokenTradingSymbolsDTO = PageDTO;
-/** Fetch a composite pool snapshot. */
-export interface FetchCompositePoolDataDTO {
-  token0: string;
-  token1: string;
-  fee: FEE_TIER;
+/** The request config the adapter hands to axios. */
+export interface AxiosLikeConfig {
+  headers: Record<string, string>;
+  signal?: AbortSignal;
+  validateStatus?: () => boolean;
 }
-/** Fetch one current trading price, or all prices when no pair is supplied. */
-export type FetchCurrentTradingPricesDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
-/** Fetch pools, optionally narrowed to one pair and paged. */
-export type FetchPoolsDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
-/** Fetch all liquidity positions, optionally narrowed to a pool reference. */
-export interface FetchLiquidityPositionsDTO extends PageDTO {
-  pool?: string | undefined;
+/**
+ * The part of an axios instance the adapter calls. Declared structurally, so the SDK takes no
+ * dependency on axios and any axios instance (with its interceptors) satisfies it.
+ */
+export interface AxiosLikeInstance {
+  get(url: string, config?: AxiosLikeConfig): Promise<unknown>;
+  post(url: string, data?: unknown, config?: AxiosLikeConfig): Promise<unknown>;
+}
+/** Options of {@link httpRequestorFromAxios}. */
+export interface AxiosRequestorOptions {
+  /**
+   * `true`: leave axios' default status validation alone, so a 4xx/5xx REJECTS through the
+   * instance's own interceptors and the SDK rethrows what the app's error handling produced.
+   * `false`: every HTTP status resolves, so the SDK classifies it itself (shadow submits,
+   * apply-results reads); transport failures still reject.
+   */
+  rejectOnHttpError: boolean;
+  /**
+   * Request headers NOT to hand to axios, matched case-insensitively. Default `['content-type']`:
+   * axios derives `Content-Type: application/json` from the object body it is given, and an
+   * interceptor may set its own, so the SDK's copy would only be a second opinion.
+   */
+  omitHeaders?: readonly string[] | undefined;
+}
+/**
+ * An SDK {@link HttpRequestor} over an axios instance, so the SDK's requests travel through the
+ * app's own base URL, interceptors and error handling.
+ *
+ * A POST's string body is parsed back to the object the SDK serialized it from (axios serializes
+ * again, and an interceptor may read the object); a GET goes through `instance.get`. The answer
+ * is an HTTP response whose `json()`/`text()` read `response.data`. An answer that is not an
+ * axios response is a `TRANSPORT_ERROR` rejection.
+ *
+ * Pair it with `ChainGateway`'s `dexBackendBaseUrl: ''` when the instance owns the base URL.
+ *
+ * @example
+ * ```ts
+ * const submitGateway = new ChainGateway({
+ *   dexBackendBaseUrl: '',
+ *   httpRequestor: httpRequestorFromAxios(chainGatewayInstance, { rejectOnHttpError: true }),
+ * });
+ * ```
+ */
+export declare function httpRequestorFromAxios(instance: AxiosLikeInstance, options: AxiosRequestorOptions): HttpRequestor;
+//#endregion
+//#region src/utils/ethers_provider.d.ts
+/**
+ * The part of an ethers v6 signer (`JsonRpcSigner`, `Wallet`) the adapter calls. Declared
+ * structurally, so the SDK takes no dependency on ethers and an ethers object satisfies it as is.
+ */
+export interface EthersLikeSigner {
+  signTypedData(domain: Record<string, unknown>, types: Record<string, Array<{
+    name: string;
+    type: string;
+  }>>, value: Record<string, unknown>): Promise<string>;
+  signMessage(message: string): Promise<string>;
+}
+/** The part of an ethers v6 provider (`BrowserProvider`) the adapter calls. */
+export interface EthersLikeProvider {
+  getSigner(): Promise<EthersLikeSigner>;
+  /** The raw JSON-RPC passthrough (`BrowserProvider.send`). */
+  send(method: string, params: unknown[]): Promise<unknown>;
+}
+/** Options of {@link eip1193ProviderFromEthers}. */
+export interface EthersEip1193Options {
+  /**
+   * Signs a `personal_sign` message when the provider cannot or should not: a wallet SDK that
+   * signs through its own object (TrustWallet's `web3Wallet.signMessage`). When set it answers
+   * every `personal_sign`, and the provider is not touched for it.
+   */
+  personalSign?: ((message: string) => Promise<string>) | undefined;
+  /**
+   * The message of the `WALLET_UNAVAILABLE` error raised when a request needs the provider and
+   * there is none (no wallet connected). Default: "No wallet is connected."
+   */
+  unavailableMessage?: string | undefined;
 }
+/**
+ * An EIP-1193 provider over an ethers v6 provider, for {@link BrowserWalletSigner}: apps whose
+ * wallet connection is an ethers `BrowserProvider` sign through the very ethers calls they always
+ * made, with no hand-written shim.
+ *
+ * - `eth_chainId` is `provider.send('eth_chainId', [])`: the wallet's LIVE chain. Never
+ *   `provider.getNetwork()`, which ethers caches and does not invalidate on `chainChanged`, so a
+ *   user who switches networks after connecting would sign against a stale chainId.
+ * - `eth_signTypedData_v4` parses the `[account, JSON]` params and calls
+ *   `signer.signTypedData(domain, types, message)` with `EIP712Domain` removed from `types`.
+ * - `personal_sign` is `options.personalSign(message)` when given, else `signer.signMessage`.
+ * - Anything else is `UNSUPPORTED_WALLET_METHOD`; a malformed request is
+ *   `MALFORMED_WALLET_REQUEST`; a missing provider is `WALLET_UNAVAILABLE`.
+ *
+ * `provider` may be `null`/`undefined` (nothing connected): a request that needs it then fails
+ * with `WALLET_UNAVAILABLE` rather than at construction, so a signer can be built before the
+ * connection state is known.
+ *
+ * @example
+ * ```ts
+ * const signer = new BrowserWalletSigner(eip1193ProviderFromEthers(browserProvider), account, {
+ *   scheme: 'eip712',
+ * });
+ * ```
+ */
+export declare function eip1193ProviderFromEthers(provider: EthersLikeProvider | null | undefined, options?: EthersEip1193Options): BrowserWalletProvider;
 //#endregion
 //#region src/utils/ticks.d.ts
 /** Minimum tick supported by GalaChainDex. */
@@ -1489,6 +2998,32 @@ export declare function alignTickDown(tick: number, spacing: number): number;
 export declare function alignTickUp(tick: number, spacing: number): number;
 /** Validate a position range against the global tick bounds and fee-tier spacing. */
 export declare function assertTickRange(lower: number, upper: number, fee: FEE_TIER): void;
+/** A pool's current price in the frame of the request that asked for it. */
+export interface FramedSlot0 {
+  /** The square-root price, token1 per token0 in the REQUESTED order. */
+  sqrtPrice: string;
+  /** The greatest tick whose square-root price is no greater than `sqrtPrice`. */
+  tick: number;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare function frameSlot0(slot0: {
+  sqrtPrice: string;
+  tick: number;
+  flippedFromRequest?: boolean | undefined;
+}): FramedSlot0;
 //#endregion
 //#region src/utils/validation.d.ts
 export declare function validateNumericAmount(amount: NumericAmount, parameterName: string, allowZero?: boolean): void;
@@ -1498,5 +3033,20 @@ export declare function validateTickRange(tickLower: number, tickUpper: number):
 export declare function validateFee(fee: number): asserts fee is FEE_TIER;
 export declare function validateTickSpacing(tickSpacing: number): void;
 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
+ * digits only, 1 to 32 characters, and not a reserved word (`Token`, `Unit`, `none`) — the rules
+ * the chain gateway enforces on a CreatePool symbol.
+ */
+export declare function isProposableTradingSymbol(symbol: string): boolean;
+/**
+ * Asserts that a pair is in the contract's canonical order (`token0 < token1` by plain string
+ * comparison), which every write DTO requires. A pair a caller took from a stale quote or
+ * position can be reversed; signing it would sign something other than what was priced.
+ *
+ * @throws GSwapSDKError VALIDATION_ERROR (`details.type` = `NON_CANONICAL_PAIR`) otherwise.
+ */
+export declare function assertCanonicalPair(token0: string, token1: string): void;
 //#endregion
+export type { AddLiquidityInput, CreatePoolInput, EIP712DomainValue, EIP712Types, EntryParse, InvalidEntry, InvalidEntryHandler, PersonalSignChainDtoPayload, PoolPositionInput, PrivateKeyInput, RemoveLiquidityInput, RequestTradeInput, TypedDataPayload, V2WriteMethod };
 //# sourceMappingURL=index.d.cts.map