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

package/dist/index.d.cts

@@ -177,9 +177,12 @@ export interface QuoteResult {
   token1Symbol: string;
   tokenInIsToken0: boolean;
   feeTier: number;
-  currentPrice?: BigNumber;
-  newPrice?: BigNumber;
-  priceImpact?: BigNumber;
+  /** Pool price before the trade, token out per token in (always set by `Quoting`). */
+  currentPrice: BigNumber;
+  /** Pool price after the trade, in the same orientation (always set by `Quoting`). */
+  newPrice: BigNumber;
+  /** `(newPrice - currentPrice) / currentPrice` as a fraction (`-0.01` is 1% adverse), always set by `Quoting`. */
+  priceImpact: BigNumber;
 }
 /** The executed trade as reported by the ApplyRequests result (contract Trade response). */
 export interface TradeExecution {
@@ -1311,6 +1314,11 @@ export declare const gswapErrorTemplates: { readonly [C in GSwapErrorCode]: stri
 export declare function renderGSwapErrorTemplate(template: string, params: Readonly<Record<string, unknown>>): string;
 //#endregion
 //#region src/types/token.d.ts
+/**
+ * The four parts of a GalaChain token class key, as the chain keys a token (for example
+ * `GALA|Unit|none|none` is collection `GALA`, category `Unit`, type `none`, additionalKey `none`).
+ * It carries no trading symbol: a collection and a symbol disagree for many tokens.
+ */
 export interface GalaChainTokenClassKey {
   collection: string;
   category: string;
@@ -1425,6 +1433,7 @@ export declare class GSwapSDKError<C extends GSwapErrorCode = GSwapErrorCode> ex
   readonly code: C;
   /** The named placeholders of the error: a flat object of primitives, safe to localize with. */
   readonly params: GSwapErrorParams<C>;
+  /** The server's `Retry-After` in milliseconds (a `RATE_LIMITED` answer), when it sent one. */
   readonly retryAfterMs: number | undefined;
   /** The HTTP status of the response that caused this error, when there was one. */
   readonly status: number | undefined;
@@ -1833,7 +1842,7 @@ export declare function createLazyPrivateKeySigner(getPrivateKey: PrivateKeyProv
  *
  * `scheme: 'personal-sign'` calls
  * `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])` and REQUIRES
- * a wallet build that contains wallet_extension commit 3ad7ae6 (strips the embedded `prefix`
+ * a wallet build that contains wallet_extension commit 34ca4e4 (strips the embedded `prefix`
  * field and hashes `prefix` + the prefix-less canonical body, the chain's scheme). Wallets
  * released before that fix hash the string with the `prefix` field still inside it and the
  * signature recovers to an address nobody holds, so only opt in once the fixed wallet is
@@ -1858,7 +1867,7 @@ export declare class GalaWalletSigner implements GalaChainSigner {
    * to the same check); a GalaChain id is `client|` plus 24 hex digits, or the bare 24 hex digits
    * frontend_v2 keeps for a direct `client|` login, and is passed through unchanged.
    * @param options - Select native signing (default) or personal-sign explicitly.
-   * `'personal-sign'` requires a Gala Wallet build with wallet_extension commit 3ad7ae6.
+   * `'personal-sign'` requires a Gala Wallet build with wallet_extension commit 34ca4e4.
    * `selectAddress` is the identity (`client|...` / `eth|...`) Gala Wallet is switched to with
    * `window.gala.setAddress` before every signature, when the wallet offers it.
    */
@@ -1917,6 +1926,7 @@ export declare class BrowserWalletSigner implements GalaChainSigner {
   constructor(provider: BrowserWalletProvider, walletAddress: string, options?: {
     scheme?: 'personal-sign' | 'eip712';
   });
+  /** The selected `0x` Ethereum account every signature is requested for. */
   readonly walletAddress: string;
   private readonly scheme;
   /**
@@ -1939,6 +1949,7 @@ export declare class BrowserWalletSigner implements GalaChainSigner {
 //#region src/classes/dex_fees.d.ts
 /** DEX methods the backend accepts a fee quote for (its allow-list enumerates the same six). */
 export declare const DEX_FEE_METHODS: readonly ['Swap', 'RequestTrade', 'AddLiquidity', 'RemoveLiquidity', 'CollectPositionFees', 'CreatePool'];
+/** A chain method whose network fee `DexFees.quote` can price (see `isDexFeeMethod`). */
 export type DexFeeMethod = (typeof DEX_FEE_METHODS)[number];
 /** Which pool contract the DTO being quoted targets: legacy (V3) or current (GalaChainDex). */
 export type DexFeeContract = 'dexv3-contract' | 'dex-contract';
@@ -2055,18 +2066,19 @@ export interface ShadowSubmitResult {
  *
  * - `SHADOW_UNAVAILABLE` (503): marking failed or infra not configured; retryable. Never fall back
  *   silently to a public swap.
- * - `SHADOW_DISABLED` (400): the feature is off for this environment.
  * - `SHADOW_UNSUPPORTED_TYPE` (400): shadow requested on a non-swap method.
  * - `SHADOW_RELAY_REJECTED`: terminal business rejection (slippage, balance, ...), not retryable;
  *   `message` is the gateway's verbatim string.
  */
-export declare const SHADOW_SUBMIT_CODES: readonly ['SHADOW_UNAVAILABLE', 'SHADOW_DISABLED', 'SHADOW_UNSUPPORTED_TYPE', 'SHADOW_RELAY_REJECTED'];
+export declare const SHADOW_SUBMIT_CODES: readonly ['SHADOW_UNAVAILABLE', 'SHADOW_UNSUPPORTED_TYPE', 'SHADOW_RELAY_REJECTED'];
 /** One member of {@link SHADOW_SUBMIT_CODES}. */
 export type ShadowSubmitCode = (typeof SHADOW_SUBMIT_CODES)[number];
 /**
  * Every `kind` of a failed {@link ShadowSubmitOutcome}, for an app that maps each to its own text
- * (`Record<ShadowFailureKind, string>`): `unavailable` (retryable), `disabled`, `rejected` (carries
- * the gateway's `message`) and `unknown`.
+ * (`Record<ShadowFailureKind, string>`): `unavailable` (retryable), `disabled` (the shadow route
+ * answered 400: the request is not a dark-swappable one, e.g. `SHADOW_UNSUPPORTED_TYPE`; Shadow
+ * Swaps themselves are enabled in every environment), `rejected` (carries the gateway's `message`)
+ * and `unknown`.
  */
 export declare const SHADOW_FAILURE_KINDS: readonly ['unavailable', 'disabled', 'rejected', 'unknown'];
 /** One member of {@link SHADOW_FAILURE_KINDS}. */
@@ -2123,7 +2135,7 @@ export declare function classifyShadowSubmitStatus(status: number): ShadowFailur
 /**
  * Prefers the body `code` (stable across status remaps) and falls back to the HTTP status.
  * `SHADOW_UNAVAILABLE` is the only retryable case; `SHADOW_RELAY_REJECTED` is a terminal gateway
- * rejection; the two other 400 codes and any unknown 400 map to "disabled".
+ * rejection; `SHADOW_UNSUPPORTED_TYPE` and any other 400 map to "disabled".
  */
 export declare function classifyShadowSubmitError(status: number, code?: string): ShadowFailureKind;
 /**
@@ -2196,9 +2208,13 @@ export type PositionConfirmationResult = {
 };
 /** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
 export declare class SubmittedTransaction<TConfirmation = AppliedTrade | Position | null> {
+  /** The chain method that was submitted (`RequestTrade`, `AddLiquidity`, ...). */
   readonly method: string;
+  /** The write's durable correlation key: persist it, and confirm from it alone later. */
   readonly uniqueKey: string;
+  /** The request transaction id the gateway reported, or `null` when it gave none. */
   readonly transactionId: string | null;
+  /** The block of the transaction, when the answer carried one; otherwise `null`. */
   readonly blockNumber: number | null;
   /** The gateway's `data.mode`: `'sync'` (executed, `result` is the chain result) or `'queued'`. */
   readonly mode: 'sync' | 'queued';
@@ -2358,7 +2374,9 @@ export declare class ChainGateway {
   private readonly chainCallTimeoutMs;
   private readonly isTransportFailure;
   private readonly answerOfRejectionHook;
+  /** The request timeout in milliseconds (`Infinity` when no timer is armed). */
   readonly requestTimeoutMs: number;
+  /** The swap backend base URL every request is sent to, without a trailing slash. */
   readonly dexBackendBaseUrl: string;
   /** Wire format shared by the read services built on this gateway. */
   readonly wire: WireOptions;
@@ -2383,7 +2401,7 @@ export declare class ChainGateway {
    *
    * Unlike `submit`, EVERY HTTP status resolves: the result is the raw `{ httpStatus, body }`,
    * because shadow failures are classified from the status together with the body's `code`
-   * (`SHADOW_UNAVAILABLE`, `SHADOW_DISABLED`, `SHADOW_UNSUPPORTED_TYPE`, `SHADOW_RELAY_REJECTED`);
+   * (`SHADOW_UNAVAILABLE`, `SHADOW_UNSUPPORTED_TYPE`, `SHADOW_RELAY_REJECTED`);
    * see `readShadowSubmitOutcome`. Only a failure to get an answer rejects, and it rejects with
    * `SUBMISSION_OUTCOME_UNKNOWN` (`params.reason` `'timeout'` or `'transport'`): the request may
    * have been accepted. Every error it throws has `error.shadow === true`, and a non-SDK object
@@ -2518,7 +2536,9 @@ export interface GdexSubscription {
 }
 /** A JSON-RPC error answered by the stream. */
 export declare class GdexStreamError extends Error {
+  /** The JSON-RPC error code. */
   readonly code: number;
+  /** The error's optional `data` member, as the server sent it. */
   readonly data?: unknown;
   constructor(code: number, message: string, data?: unknown);
 }
@@ -2556,17 +2576,26 @@ export declare class GdexStreamService {
   connect(): Promise<void>;
   /** Close the connection and stop reconnecting. */
   disconnect(): void;
+  /** `true` while the socket is open (false while connecting, reconnecting or after `disconnect()`). */
   isConnected(): boolean;
   /** Raw JSON-RPC escape hatch. */
   request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
   private send;
+  /** `gdex_serverInfo`: the server's own description of itself, as it sends it. */
   serverInfo(): Promise<Record<string, unknown>>;
+  /** `gdex_ping`: a round trip that answers `{ pong, serverTime }`. */
   ping(): Promise<{
     pong: boolean;
     serverTime: string;
   }>;
+  /** `gdex_getPool`: the current state of one pool, selected by its key or hash. */
   getPool(selector: GdexPoolSelector): Promise<Record<string, unknown>>;
+  /** `gdex_getBalance`: an owner's balances, or only the one of `tokenClassKey` when given. */
   getBalance(owner: string, tokenClassKey?: string): Promise<Record<string, unknown>>;
+  /**
+   * `gdex_getPositions`: an owner's positions, optionally in one pool, a page at a time. Pass the
+   * returned `bookmark` back in as `bookmark` for the next page.
+   */
   getPositions(opts: {
     owner: string;
     pool?: GdexPoolKey;
@@ -2577,10 +2606,12 @@ export declare class GdexStreamService {
     positions: Record<string, unknown>[];
     bookmark: string;
   }>;
+  /** `gdex_getBlockHeight`: the block number the server reports, with its timestamp. */
   getBlockHeight(): Promise<{
     blockNumber: number;
     timestamp: string;
   }>;
+  /** `gdex_quote`: a quote over the stream; give exactly one of `amountIn` or `amountOut`. */
   quote(params: {
     tokenIn: string;
     tokenOut: string;
@@ -2588,6 +2619,7 @@ export declare class GdexStreamService {
     amountIn?: string;
     amountOut?: string;
   }): Promise<Record<string, unknown>>;
+  /** `gdex_getToken`: the server's record of one token class, as it sends it. */
   getToken(tokenClassKey: string): Promise<Record<string, unknown>>;
   /** One event per committed swap. Omit the pool to receive every pool's swaps. */
   subscribeSwaps(cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
@@ -2933,10 +2965,22 @@ interface Branding<BrandT> {
 type Brand<T, BrandT> = T & Branding<BrandT>;
 //#endregion
 //#region src/types/amounts.d.ts
+/** A decimal amount: a string or a `BigNumber`, never a JavaScript number. */
 export type NumericAmount = string | BigNumber;
+/** A calculated square-root price (always a `BigNumber`, branded so it is never mistaken for a price). */
 export type SqrtPrice = Brand<BigNumber, 'SqrtPrice'>;
+/**
+ * A square-root price an API accepts: a calculated {@link SqrtPrice}, or a decimal string /
+ * `BigNumber` the caller brands with `as SqrtPriceIn` to declare what it is.
+ */
 export type SqrtPriceIn = Brand<NumericAmount, 'SqrtPriceIn'> | SqrtPrice;
+/** A calculated price (always a `BigNumber`, branded so it is never mistaken for a square-root price). */
 export type Price = Brand<BigNumber, 'Price'>;
+/**
+ * A price an API accepts (for example `addLiquidityByPrice`'s `minPrice` / `maxPrice`): a calculated
+ * {@link Price}, or a decimal string / `BigNumber` the caller brands with `as PriceIn` to declare
+ * what it is. An unbranded string does not compile.
+ */
 export type PriceIn = Brand<NumericAmount, 'PriceIn'> | Price;
 /**
  * What a swap trades: exactly one of `exactIn` (sell this much of the input token) or `exactOut`
@@ -3683,10 +3727,18 @@ export declare const GSWAP_ENVIRONMENTS: Readonly<Record<GSwapEnv, GSwapEnvironm
 //#region src/classes/gswap.d.ts
 /** Options for constructing a backend-routed SDK client. */
 export interface GSwapOptions {
+  /** Signs every write. Without one, reads work and any write throws `NO_SIGNER`. */
   signer?: GalaChainSigner | undefined;
+  /**
+   * The selected account, sent as `X-Wallet-Address` on writes (attribution only; the chain
+   * recovers the signer from the signature). Required for shadow writes.
+   */
   walletAddress?: string | undefined;
+  /** `'stage'` or `'prod'` swap backend preset; defaults to `'prod'`. */
   env?: GSwapEnv | undefined;
+  /** Overrides the preset's swap backend base URL (a test or private deployment). */
   dexBackendBaseUrl?: string | undefined;
+  /** HTTP transport for every request; defaults to the global `fetch`. */
   httpRequestor?: HttpRequestor | undefined;
   /** Request timeout in milliseconds (default 30 000); `Infinity` arms no timer. */
   chainCallTimeoutMs?: number | undefined;
@@ -3720,27 +3772,43 @@ export interface GSwapOptions {
    */
   uniqueKeyPrefix?: string | undefined;
 }
-/** Main entry point for the current GalaChainDex SDK. */
+/**
+ * Main entry point for the current GalaChainDex SDK: one client bundling the services that read
+ * and write through the swap backend (`quoting`, `swaps`, `pools`, `positions`, `assets`,
+ * `symbols`, `fees`, `stream`). See {@link GSwapOptions} for configuration.
+ */
 export declare class GSwap {
+  /** The swap backend base URL every request goes to, without a trailing slash. */
   readonly dexBackendBaseUrl: string;
+  /** The request timeout in milliseconds (default 30 000; `Infinity` arms no timer). */
   readonly chainCallTimeoutMs: number;
+  /** The signer given at construction, if any. */
   readonly signer: GalaChainSigner | undefined;
+  /** The account given at construction, if any. */
   readonly walletAddress: string | undefined;
+  /** The chain-gateway client every other service reads and writes through. */
   readonly gateway: ChainGateway;
+  /** The trading-symbol registry. */
   readonly symbols: Symbols;
+  /** Read-only exact-input and exact-output quotes. */
   readonly quoting: Quoting;
+  /** Pool, slot0 and composite-pool reads. */
   readonly pools: Pools;
+  /** Position reads, liquidity estimates and liquidity / pool-creation writes. */
   readonly positions: Positions;
+  /** Queued swaps (`RequestTrade`), dark swaps and swap confirmation. */
   readonly swaps: Swaps;
+  /** User token balances. */
   readonly assets: Assets;
   /** Network-fee quotes (DryRun) signed with this client's signer. */
   readonly fees: DexFees;
+  /** The realtime stream endpoint {@link GSwap.stream} connects to. */
   readonly dexBackendWsUrl: string;
   private readonly webSocketImpl;
   private readonly streamApiKey;
   private streamClient;
   /**
-   * Create an SDK client for prod or stage.
+   * Create an SDK client for prod (the default) or stage, or for a `dexBackendBaseUrl` of your own.
    *
    * @example
    * ```typescript
@@ -4468,6 +4536,7 @@ export declare function tokenClassDollarKey(token: Record<string, unknown> | nul
 export declare function canonicalDecimalString(value: string | number): string;
 //#endregion
 //#region src/utils/eip712.d.ts
+/** EIP-712 `types`: each struct name mapped to its ordered `{ name, type }` fields. */
 type EIP712Types = Record<string, Array<{
   name: string;
   type: string;
@@ -4558,8 +4627,9 @@ type RequestTradeInput = {
 /**
  * Builds the RequestTrade DTO: `exactIn` sells that much of the input token (`sell0Qty` or
  * `sell1Qty`), `exactOut` buys that much of the output token (`buy1Qty` or `buy0Qty`), plus the
- * side's slippage bound and an optional `priceLimit`. Key order: `token0, token1, fee, uniqueKey,
- * <quantity>, amountOutMinimum | amountInMaximum, priceLimit`.
+ * side's slippage bound and an optional `priceLimit`. Key order is
+ * `token0, token1, fee, uniqueKey`, then the one quantity, then the slippage bound, then
+ * `priceLimit`.
  *
  * @example
  * ```ts
@@ -4851,10 +4921,10 @@ export interface FailureClassification {
  * object, safe to mutate or freeze.
  *
  * `options.retryable: false` WITHHOLDS Retry from an outcome that would otherwise allow it: the
- * SDK's own `not_queued` for a refusal the gateway will repeat is `classification('not_queued',
- * { retryable: false })` (also exported, frozen, as {@link NOT_QUEUED_FINAL}). An app may take
- * Retry away from an outcome but never grant it to one that cannot have it, so only `false` is
- * accepted.
+ * SDK's own `not_queued` for a refusal the gateway will repeat is
+ * `classification('not_queued', { retryable: false })` (also exported, frozen, as
+ * {@link NOT_QUEUED_FINAL}). An app may take Retry away from an outcome but never grant it to one
+ * that cannot have it, so only `false` is accepted.
  *
  * @example
  * ```ts
@@ -5318,12 +5388,55 @@ export declare function frameSlot0(slot0: {
 export declare function isValidUniqueKey(uniqueKey: unknown): uniqueKey is string;
 //#endregion
 //#region src/utils/validation.d.ts
+/**
+ * Validates a decimal amount: a string or `BigNumber`, never a JavaScript number.
+ *
+ * @param amount - The amount to check.
+ * @param parameterName - The field name reported in the error's `params.field`.
+ * @param allowZero - Accept zero (default `false`).
+ * @throws GSwapSDKError `AMOUNT_IS_JS_NUMBER`, `AMOUNT_NOT_FINITE`, `AMOUNT_NOT_POSITIVE` (zero
+ * when `allowZero` is false) or `AMOUNT_NEGATIVE`.
+ */
 export declare function validateNumericAmount(amount: NumericAmount, parameterName: string, allowZero?: boolean): void;
+/**
+ * Validates a spot price and a lower/upper price range: none a JavaScript number, all positive and
+ * finite (a non-finite upper bound counts as an unbounded `1e18`), and `lowerPrice <= upperPrice`.
+ *
+ * @throws GSwapSDKError `PRICE_VALUES_IS_JS_NUMBER`, `INVALID_PRICE_VALUES` or `INVALID_PRICE_RANGE`.
+ */
 export declare function validatePriceValues(spotPrice: NumericAmount, lowerPrice: NumericAmount, upperPrice: NumericAmount): void;
+/**
+ * Validates a token's decimals: a non-negative integer.
+ *
+ * @throws GSwapSDKError `INVALID_TOKEN_DECIMALS` (`params.field` is `parameterName`).
+ */
 export declare function validateTokenDecimals(decimals: number, parameterName: string): void;
+/**
+ * Validates a position's tick range: two integers with `tickLower < tickUpper`, both within
+ * `GC_MIN_TICK`..`GC_MAX_TICK`. It does not check alignment to a fee tier's spacing (see
+ * `assertTickRange`).
+ *
+ * @throws GSwapSDKError `TICKS_NOT_INTEGERS`, `INVALID_TICK_RANGE` or `TICKS_OUT_OF_BOUNDS`.
+ */
 export declare function validateTickRange(tickLower: number, tickUpper: number): void;
+/**
+ * Asserts that `fee` is one of the fee tiers in `ALL_FEE_TIERS` (`0`, `500`, `3000`, `10000`).
+ *
+ * @throws GSwapSDKError `INVALID_FEE` (`params.field` `'fee'`, `params.allowed` the tiers).
+ */
 export declare function validateFee(fee: number): asserts fee is FEE_TIER;
+/**
+ * Validates a tick spacing: a positive integer.
+ *
+ * @throws GSwapSDKError `INVALID_TICK_SPACING`.
+ */
 export declare function validateTickSpacing(tickSpacing: number): void;
+/**
+ * Asserts that a wallet address was given and is a non-blank string. It does not check the address
+ * format.
+ *
+ * @throws GSwapSDKError `MISSING_WALLET_ADDRESS` (undefined) or `INVALID_WALLET_ADDRESS` (blank).
+ */
 export declare function validateWalletAddress(address?: string): asserts address is string;
 /**
  * True when `symbol` is acceptable to propose into the trading-symbol registry: ASCII letters and