@gala-chain/gswap-sdk 1.1.0 → 1.2.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,37 @@
1
1
  import BigNumber from "bignumber.js";
2
+ //#region src/types/confirm_options.d.ts
3
+ /**
4
+ * Controls timeout, polling and cancellation of confirmation.
5
+ *
6
+ * - `timeoutMs` (default 60 000): overall deadline, counted from the `confirm()` call and
7
+ * including `initialDelayMs`. At least one read is always made.
8
+ * - `pollIntervalMs` (default 2 000, minimum 500): base interval, doubled with jitter up to 8 s.
9
+ * - `initialDelayMs`: wait before the first read. Defaults to 3 000 for a queued RequestTrade
10
+ * (the AutoApplier needs a few seconds) and 0 for liquidity writes (already executed).
11
+ * - `signal`: aborts the wait or an in-flight read. Confirmation then throws an error with code
12
+ * `CONFIRMATION_ABORTED`; nothing is learned about the outcome, so confirm the same
13
+ * `uniqueKey` again later.
14
+ */
15
+ export interface ConfirmOptions {
16
+ timeoutMs?: number | undefined;
17
+ pollIntervalMs?: number | undefined;
18
+ initialDelayMs?: number | undefined;
19
+ signal?: AbortSignal | undefined;
20
+ }
21
+ //#endregion
22
+ //#region src/types/http_requestor.d.ts
23
+ type FetchReturnValue = Awaited<ReturnType<typeof fetch>>;
24
+ interface HTTPResponse {
25
+ ok: FetchReturnValue['ok'];
26
+ status: FetchReturnValue['status'];
27
+ json: FetchReturnValue['json'];
28
+ text: FetchReturnValue['text'];
29
+ headers?: {
30
+ get(name: string): string | null;
31
+ } | Record<string, string | undefined>;
32
+ }
33
+ type HttpRequestor = (uri: string, options?: Parameters<typeof fetch>[1]) => Promise<HTTPResponse>;
34
+ //#endregion
2
35
  //#region src/types/v2_results.d.ts
3
36
  /** Pool metadata returned by GalaChainDex. */
4
37
  export interface PoolInfo {
@@ -15,19 +48,26 @@ export interface PoolInfo {
15
48
  isPrivate?: boolean;
16
49
  flippedFromRequest?: boolean;
17
50
  }
18
- /** Pool summary returned by the backend pool-list route. */
51
+ /**
52
+ * Pool summary returned by the backend pool-list route. Only the identity (`token0`, `token1`,
53
+ * `poolRef`) and `fee` are guaranteed; a row that lacks any other field is still a usable row, as
54
+ * the apps that list pools treat it.
55
+ */
19
56
  export interface PoolListInfo {
20
- contractVersion: 'v2';
57
+ contractVersion?: 'v2' | undefined;
21
58
  token0: string;
22
59
  token1: string;
23
60
  token0CompositeKey?: string | undefined;
24
61
  token1CompositeKey?: string | undefined;
62
+ /** Registry image URL of token0 resolved by the backend; empty when the token is unregistered. */
63
+ token0Image?: string | undefined;
64
+ token1Image?: string | undefined;
25
65
  fee: number;
26
- poolName: string;
66
+ poolName?: string | undefined;
27
67
  poolRef: string;
28
- tickSpacing: number;
29
- protocolFees: number;
30
- tradingFees: number;
68
+ tickSpacing?: number | undefined;
69
+ protocolFees?: number | undefined;
70
+ tradingFees?: number | undefined;
31
71
  creator?: string | undefined;
32
72
  price?: string | undefined;
33
73
  sqrtPrice?: string | undefined;
@@ -103,6 +143,9 @@ export interface Position {
103
143
  token1Symbol: string;
104
144
  token0CompositeKey?: string;
105
145
  token1CompositeKey?: string;
146
+ /** Registry image URL of token0 resolved by the backend; empty when the token is unregistered. */
147
+ token0Image?: string;
148
+ token1Image?: string;
106
149
  fee: number;
107
150
  tickLower: number;
108
151
  tickUpper: number;
@@ -209,25 +252,187 @@ export interface ChainSubmissionResult {
209
252
  uniqueKey?: string;
210
253
  }
211
254
  //#endregion
212
- //#region src/types/http_requestor.d.ts
213
- type FetchReturnValue = Awaited<ReturnType<typeof fetch>>;
214
- interface HTTPResponse {
215
- ok: FetchReturnValue['ok'];
216
- status: FetchReturnValue['status'];
217
- json: FetchReturnValue['json'];
218
- text: FetchReturnValue['text'];
219
- headers?: {
220
- get(name: string): string | null;
221
- } | Record<string, string | undefined>;
255
+ //#region src/types/token.d.ts
256
+ export interface GalaChainTokenClassKey {
257
+ collection: string;
258
+ category: string;
259
+ type: string;
260
+ additionalKey: string;
261
+ }
262
+ //#endregion
263
+ //#region src/classes/gswap_sdk_error.d.ts
264
+ /** Error raised by the SDK for validation, gateway, chain, or transaction failures. */
265
+ export declare class GSwapSDKError extends Error {
266
+ readonly code: string;
267
+ readonly details?: Record<string, unknown> | undefined;
268
+ readonly chainMessage: string | undefined;
269
+ readonly retryAfterMs: number | undefined;
270
+ /** The HTTP status of the response that caused this error, when there was one. */
271
+ readonly status: number | undefined;
272
+ /**
273
+ * The response body parsed as JSON, when the failing response had one; `undefined` for a body
274
+ * that was not JSON (see {@link bodyText}). Never part of {@link message}.
275
+ */
276
+ readonly body: unknown;
277
+ /**
278
+ * The raw text of a failing response whose body was NOT JSON (a proxy's HTML 502, a WAF page,
279
+ * an empty body). It is kept here for diagnostics and is never copied into {@link message} or
280
+ * {@link userMessage}, so it cannot reach a user interface by accident.
281
+ */
282
+ readonly bodyText: string | undefined;
283
+ constructor(message: string, code: string, details?: Record<string, unknown> | undefined, chainMessage?: string, retryAfterMs?: number);
284
+ /**
285
+ * A message that is safe to show a user as is: the server's own message when it sent one
286
+ * (a gateway or chain rejection), a neutral line naming the status for an HTTP failure with no
287
+ * readable answer, and otherwise {@link message}. Apps that word these differently (a
288
+ * "network busy" line for a 502, say) branch on {@link code} and {@link status} instead.
289
+ */
290
+ get userMessage(): string;
291
+ /**
292
+ * True when the failure means "that market, pool or position does not exist" rather than
293
+ * "something went wrong": an HTTP 404, a pair with no pool at any fee tier
294
+ * (`NO_POOL_AVAILABLE`), or a token the DEX contract has no trading symbol for
295
+ * (`UNKNOWN_TOKEN`). A pool that exists but is too thin (`INSUFFICIENT_LIQUIDITY`) is NOT
296
+ * not-found.
297
+ */
298
+ get notFound(): boolean;
299
+ /** Create the standard missing-signer error. */
300
+ static noSignerError(): GSwapSDKError;
301
+ /** Create the error used when confirming a position write without a configured wallet address. */
302
+ static noWalletAddressError(): GSwapSDKError;
303
+ /**
304
+ * Create the error used when no pool can quote the requested pair. `source` is the backend
305
+ * answer that said so; its status, body and message are kept (the message as `chainMessage`,
306
+ * so {@link userMessage} is the server's own wording).
307
+ */
308
+ static noPoolAvailableError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number, source?: GSwapSDKError): GSwapSDKError;
309
+ /** Create the error used when a pool lacks liquidity for a quote. `source` as for {@link noPoolAvailableError}. */
310
+ static insufficientLiquidityError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number, source?: GSwapSDKError): GSwapSDKError;
311
+ /**
312
+ * The message the server put in a JSON answer (`message`, or `error.Message`), when this error
313
+ * came from an HTTP response that had one.
314
+ */
315
+ get serverMessage(): string | undefined;
316
+ /** Convert a chain-gateway bounce into a typed SDK error. */
317
+ static fromGatewayBounce(code: string, message: string, status: number, retryAfterMs?: number): GSwapSDKError;
318
+ /** Convert a GalaChain `Status: 0` response into a typed SDK error. */
319
+ static fromChainError(errorKey: string, message: string, details?: Record<string, unknown>): GSwapSDKError;
320
+ /** Create the error used when a token is not registered by the current DEX contract. */
321
+ static unknownTokenError(token: GalaChainTokenClassKey | string): GSwapSDKError;
322
+ /** Create the error used when apply-results confirmation does not arrive in time. */
323
+ static confirmationTimeoutError(uniqueKey: string, cause?: unknown): GSwapSDKError;
324
+ /** Convert an unexpected HTTP response into an SDK error. */
325
+ static fromErrorResponse(url: string, response: HTTPResponse): Promise<GSwapSDKError>;
326
+ }
327
+ /** Narrow an object property without trusting a cast at a network boundary. */
328
+ export declare function getObjectProperty(value: unknown, property: string): Record<string, unknown> | undefined;
329
+ /** Read a string property from an unknown object. */
330
+ export declare function getStringProperty(value: unknown, property: string): string | undefined;
331
+ /** Parse a response body, preserving non-JSON text for error reporting. */
332
+ export declare function parseJson(text: string): unknown;
333
+ //#endregion
334
+ //#region src/classes/apply_results.d.ts
335
+ /**
336
+ * The outcome of a queued RequestTrade that could not be delivered as an {@link AppliedTrade}.
337
+ * `code` says why:
338
+ *
339
+ * - `CONFIRMATION_TIMEOUT`: no terminal result before the deadline. The trade may still apply;
340
+ * confirm the same `uniqueKey` again later and never resubmit.
341
+ * - `CONFIRMATION_ABORTED`: the caller's `signal` aborted. Nothing is known about the outcome.
342
+ * - `CONFIRMATION_FAILED`: the apply-results read itself failed (malformed key or body, a
343
+ * non-retryable HTTP status). The outcome is unknown.
344
+ * - anything else: the chain REJECTED the trade; `code` is the chain `ErrorKey` (or
345
+ * `CHAIN_ERROR`) and `chainMessage` is its message, which is also `message`.
346
+ *
347
+ * `details` always carries `uniqueKey` and, where known, `requestTransactionId`,
348
+ * `applyTransactionId`, `blockNumber`, `status`, `body`, `url` and the last transport `cause`.
349
+ */
350
+ export declare class AppliedTradeError extends GSwapSDKError {
351
+ constructor(message: string, code: string, details?: Record<string, unknown>, chainMessage?: string);
352
+ }
353
+ /** The transport and backend a confirmation reads from. */
354
+ export interface ApplyResultsClient {
355
+ /** Swap backend origin, e.g. `https://dex-backend-prod1.defi.gala.com` (no trailing path). */
356
+ dexBackendBaseUrl: string;
357
+ /** Defaults to the global `fetch`. */
358
+ httpRequestor?: HttpRequestor | undefined;
359
+ /** Per-read timeout in milliseconds (default 30 000). */
360
+ requestTimeoutMs?: number | undefined;
361
+ }
362
+ /** What identifies the queued trade to confirm. */
363
+ export interface AppliedTradeInput {
364
+ uniqueKey: string;
365
+ /** The transaction id of the queued request, carried through to the result; `null` if unknown. */
366
+ requestTransactionId: string | null;
367
+ }
368
+ /**
369
+ * Polls `GET /v1/chain/apply-results/{uniqueKey}?channel=asset&contract=dex-contract` until the
370
+ * queued RequestTrade reaches a terminal state.
371
+ *
372
+ * Pacing: wait `initialDelayMs` (default 3 s), then read; on 404, 429, 500, 502, 503, 504 or a
373
+ * transport error wait with jittered exponential backoff (`pollIntervalMs` doubling to 8 s,
374
+ * `Retry-After` honored as seconds or an HTTP date) until `timeoutMs`. Any other status is
375
+ * terminal. At least one read is always made.
376
+ *
377
+ * @returns The applied trade.
378
+ * @throws AppliedTradeError - see its documentation for every `code`.
379
+ * @example
380
+ * ```ts
381
+ * const applied = await confirmAppliedTrade(
382
+ * { dexBackendBaseUrl: 'https://dex-backend-prod1.defi.gala.com' },
383
+ * { uniqueKey, requestTransactionId: null },
384
+ * { initialDelayMs: 0, timeoutMs: 60_000, signal: controller.signal },
385
+ * );
386
+ * ```
387
+ */
388
+ export declare function confirmAppliedTrade(client: ApplyResultsClient, input: AppliedTradeInput, options?: ConfirmOptions): Promise<AppliedTrade>;
389
+ //#endregion
390
+ //#region src/types/wire.d.ts
391
+ /**
392
+ * How the SDK writes a read request on the wire. The defaults suit a server-side caller; an app
393
+ * that already issues the same requests from its own HTTP stack (frontend_v2, the Gala Wallet)
394
+ * sets these so the SDK's requests are indistinguishable from the ones it replaces.
395
+ *
396
+ * One object, carried by {@link ChainGateway}, so every service built on a gateway (symbols,
397
+ * pools, positions, quoting) shares it without per-service plumbing.
398
+ */
399
+ export interface WireOptions {
400
+ /**
401
+ * Query-string encoding of GET parameters.
402
+ *
403
+ * - `'standard'` (default): `URLSearchParams` (`application/x-www-form-urlencoded`), where `$`
404
+ * and `|` become `%24` and `%7C`.
405
+ * - `'readable'`: keeps `$ | : ,` and the RFC 3986 sub-delimiters `! ' ( ) *` unescaped, so a
406
+ * composite key such as `GALA$Unit$none$none` or `client|abc` reads as written. Everything
407
+ * that would change a query's meaning (`& = # % +`, space, non-ASCII, controls) is still
408
+ * percent-encoded (a space is `+`), so the server decodes exactly the value that was passed.
409
+ * This is the text frontend_v2's `formatUrl` produces for every value it can represent.
410
+ */
411
+ queryEncoding?: 'standard' | 'readable' | undefined;
412
+ /**
413
+ * The `User-Agent` request header. Defaults to `GalaChain-SDK/<version>`; `false` omits it
414
+ * (browsers forbid setting it, and an app whose own requests carry none can match them).
415
+ * `Content-Type` is only ever sent with a request body, never on a GET.
416
+ */
417
+ userAgent?: string | false | undefined;
418
+ /**
419
+ * Extra request headers for every read, sent after (and so able to replace) the defaults above;
420
+ * for example axios' `Accept: application/json, text/plain, *\/*`, so a request is the same as
421
+ * the one an app's own HTTP stack used to send.
422
+ */
423
+ headers?: Record<string, string> | undefined;
222
424
  }
223
- type HttpRequestor = (uri: string, options?: Parameters<typeof fetch>[1]) => Promise<HTTPResponse>;
224
425
  //#endregion
225
426
  //#region src/classes/http_client.d.ts
226
427
  declare class HttpClient {
227
428
  private readonly httpRequestor;
228
429
  private readonly timeoutMs;
229
- /** Create an HTTP client around fetch or an injected requestor. */
230
- constructor(httpRequestor?: HttpRequestor, timeoutMs?: number);
430
+ private readonly wire;
431
+ /**
432
+ * Create an HTTP client around fetch or an injected requestor. `wire` selects the query
433
+ * encoding and the `User-Agent` (see {@link WireOptions}).
434
+ */
435
+ constructor(httpRequestor?: HttpRequestor, timeoutMs?: number, wire?: WireOptions);
231
436
  private sendRequest;
232
437
  /** Send a JSON POST request and decode its response. */
233
438
  sendPostRequest<TReturnType>(baseUrl: string, basePath: string, endpoint: string, body: unknown): Promise<TReturnType>;
@@ -262,99 +467,477 @@ export declare class Assets {
262
467
  getUserAssets(ownerAddress: string, page?: number, limit?: number): Promise<UserAssetsResult>;
263
468
  }
264
469
  //#endregion
265
- //#region src/classes/submitted_transaction.d.ts
266
- /** Result of one position-confirmation poll. */
267
- export type PositionConfirmationResult = {
268
- confirmed: true;
269
- position: Position | null;
270
- } | {
271
- confirmed: false;
272
- position?: Position | null;
470
+ //#region src/classes/signers.d.ts
471
+ /** The signing schemes supported by the Gala Wallet signer. */
472
+ export type GalaWalletScheme = 'native' | 'personal-sign';
473
+ /** The request surface used by an EIP-1193 browser wallet. */
474
+ export interface BrowserWalletProvider {
475
+ request(args: {
476
+ method: string;
477
+ params?: unknown[];
478
+ }): Promise<unknown>;
479
+ }
480
+ type SignedDto<T extends Record<string, unknown>> = T & {
481
+ signature: string;
273
482
  };
274
- /** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
275
- export declare class SubmittedTransaction<TConfirmation = AppliedTrade | Position | null> {
276
- readonly method: string;
277
- readonly uniqueKey: string;
278
- readonly transactionId: string | null;
279
- readonly blockNumber: number | null;
280
- readonly mode: 'sync' | 'queued';
281
- /** The synchronous gateway result, or `undefined` when `mode === 'queued'`. */
282
- readonly result: unknown;
283
- private readonly backendBaseUrl;
284
- private readonly requestor;
285
- private readonly requestTimeoutMs;
286
- private readonly positionConfirmation;
287
- /** Construct a submitted transaction from a successful gateway response.
483
+ /**
484
+ * A signer for complete GalaChain write bodies.
485
+ *
486
+ * Implementations return the DTO fields together with the signature that belongs in the
487
+ * gateway request body. Signer identity is recovered from that signature; implementations do
488
+ * not add signer hints, typed-data metadata, or a domain.
489
+ */
490
+ export interface GalaChainSigner {
491
+ /**
492
+ * Signs a DTO for a named GalaChain contract method.
288
493
  *
289
494
  * @example
290
- * ```ts
291
- * const transaction = new SubmittedTransaction({
292
- * method: 'RequestTrade', mode: 'queued', uniqueKey: 'swap-1',
293
- * transactionId: 'request-tx', result: undefined,
294
- * dexBackendBaseUrl: 'https://dex.example', httpRequestor,
295
- * });
495
+ * ```typescript
496
+ * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
296
497
  * ```
297
498
  */
298
- constructor(options: {
299
- method: string;
300
- uniqueKey: string;
301
- transactionId: string | null;
302
- mode: 'sync' | 'queued';
303
- result: unknown;
304
- dexBackendBaseUrl: string;
305
- httpRequestor: HttpRequestor;
306
- blockNumber?: number | null | undefined;
307
- requestTimeoutMs?: number | undefined;
308
- positionConfirmation?: ((signal: AbortSignal) => Promise<PositionConfirmationResult>) | undefined;
309
- });
310
- /** Confirm a queued RequestTrade or prove the affected position for a liquidity write.
311
- *
312
- * For RequestTrade, calling this method is required to learn the outcome: the queued
313
- * acknowledgement proves acceptance, not execution.
499
+ signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
500
+ }
501
+ /**
502
+ * A GalaChain native signer backed by a secp256k1 private key.
503
+ *
504
+ * Native signing produces the bare GalaChain signature format, without a personal-sign prefix
505
+ * or EIP-712 metadata. The private-key identity is recovered by the chain.
506
+ */
507
+ export declare class PrivateKeySigner implements GalaChainSigner {
508
+ private readonly privateKey;
509
+ /**
510
+ * Creates a native signer from a hex or base64 secp256k1 private key.
314
511
  *
315
512
  * @example
316
- * ```ts
317
- * const applied = await submitted.confirm({ initialDelayMs: 3_000 });
513
+ * ```typescript
514
+ * const signer = new PrivateKeySigner('1'.padStart(64, '0'));
515
+ * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
318
516
  * ```
319
517
  */
320
- confirm(options?: ConfirmOptions): Promise<TConfirmation>;
321
- private confirmApplied;
322
- private readAppliedResult;
323
- /** Confirm a liquidity write against the position's observable effect.
518
+ constructor(privateKey: string);
519
+ /**
520
+ * Signs the DTO with GalaChain native signing.
324
521
  *
325
- * @returns The position after the write, or `null` for a confirmed full close.
326
522
  * @example
327
- * ```ts
328
- * const position = await submitted.confirm({ timeoutMs: 60_000 });
523
+ * ```typescript
524
+ * const signed = await signer.signObject('RequestTrade', {
525
+ * token0: 'GALA',
526
+ * token1: 'GUSDC',
527
+ * fee: 3000,
528
+ * });
329
529
  * ```
330
530
  */
331
- private confirmPosition;
531
+ signObject<T extends Record<string, unknown>>(_methodName: string, dto: T): Promise<SignedDto<T>>;
532
+ }
533
+ /** Supplies a private key at sign time: a hex/base64 string, possibly fetched asynchronously. */
534
+ export type PrivateKeyProvider = () => Promise<string> | string;
535
+ /** Options for {@link createLazyPrivateKeySigner}. */
536
+ export interface LazyPrivateKeySignerOptions {
537
+ /**
538
+ * When set, every signature first checks that the fetched key belongs to this account (`0x...`
539
+ * or the Gala `eth|0x...` form, case-insensitive) and refuses to sign otherwise
540
+ * (`SIGNER_ADDRESS_MISMATCH`). Use it when the key lives in a slot another surface can switch
541
+ * between the moment a request was approved and the moment it is signed.
542
+ */
543
+ expectedAddress?: string | undefined;
332
544
  }
333
545
  /**
334
- * Controls timeout and polling behavior for confirmation.
546
+ * Creates the native-signing equivalent of {@link PrivateKeySigner} for apps that must not hold a
547
+ * key in a long-lived object (an extension that reads its session key at sign time).
335
548
  *
336
- * - `timeoutMs` (default 60 000): overall deadline, counted from the `confirm()` call and
337
- * including `initialDelayMs`. At least one read is always made.
338
- * - `pollIntervalMs` (default 2 000, minimum 500): base interval, doubled with jitter up to 8 s.
339
- * - `initialDelayMs`: wait before the first read. Defaults to 3 000 for a queued RequestTrade
340
- * (the AutoApplier needs a few seconds) and 0 for liquidity writes (already executed).
549
+ * `getPrivateKey` is called once per `signObject` call, never cached, never shared between calls
550
+ * (concurrent signatures each fetch their own key), and the normalized key bytes are zeroed
551
+ * before `signObject` settles, also on failure. A rejection or exception from `getPrivateKey` is
552
+ * passed through unchanged, so the app's own "wallet is locked" error reaches its caller; a key
553
+ * that is not a valid secp256k1 key string is a `VALIDATION_ERROR` (`INVALID_PRIVATE_KEY`).
554
+ * Signatures are byte-identical to `new PrivateKeySigner(key).signObject(...)`.
555
+ *
556
+ * A JavaScript string cannot be wiped; the provider owns the lifetime of the string it returns.
557
+ *
558
+ * @example
559
+ * ```typescript
560
+ * const signer = createLazyPrivateKeySigner(
561
+ * () => SecurityHelper.getSessionSecret(SecurityHelper.SESSION_PRIVATE_KEY_KEY),
562
+ * { expectedAddress: account.address },
563
+ * );
564
+ * const gswap = new GSwap({ signer });
565
+ * ```
341
566
  */
342
- export interface ConfirmOptions {
343
- timeoutMs?: number | undefined;
344
- pollIntervalMs?: number | undefined;
345
- initialDelayMs?: number | undefined;
346
- }
347
- //#endregion
348
- //#region src/classes/gateway.d.ts
349
- /** Options for a chain-gateway client. */
350
- export interface ChainGatewayOptions {
351
- dexBackendBaseUrl: string;
352
- httpRequestor?: HttpRequestor | undefined;
353
- walletAddress?: string | undefined;
354
- chainCallTimeoutMs?: number | undefined;
355
- }
356
- /** Optional attribution and operation-specific confirmation hooks for a write. */
357
- export interface ChainSubmitOptions {
567
+ export declare function createLazyPrivateKeySigner(getPrivateKey: PrivateKeyProvider, options?: LazyPrivateKeySignerOptions): GalaChainSigner;
568
+ /**
569
+ * A Gala Wallet signer using native GalaChain signing, with an opt-in personal-sign mode.
570
+ *
571
+ * The selected Ethereum account is passed to Gala Wallet. There is NO automatic fallback: a
572
+ * wallet that rejects `native` surfaces its error to the caller, because the only alternative,
573
+ * `personal-sign`, silently recovers a phantom signer on every released Gala Wallet.
574
+ *
575
+ * `scheme: 'personal-sign'` calls
576
+ * `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])` and REQUIRES
577
+ * a wallet build that contains wallet_extension commit 3ad7ae6 (strips the embedded `prefix`
578
+ * field and hashes `prefix` + the prefix-less canonical body, the chain's scheme). Wallets
579
+ * released before that fix hash the string with the `prefix` field still inside it and the
580
+ * signature recovers to an address nobody holds, so only opt in once the fixed wallet is
581
+ * released. See SIGNING-PARITY.md.
582
+ */
583
+ export declare class GalaWalletSigner implements GalaChainSigner {
584
+ /** The wallet address supplied to Gala Wallet for each signing request. */
585
+ readonly walletAddress: string;
586
+ /** The signing scheme used for every request; it never changes after construction. */
587
+ readonly scheme: GalaWalletScheme;
588
+ /**
589
+ * Creates a Gala Wallet signer.
590
+ *
591
+ * @example
592
+ * ```typescript
593
+ * const signer = new GalaWalletSigner('0x0123456789012345678901234567890123456789');
594
+ * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
595
+ * ```
596
+ *
597
+ * @param walletAddress - The account passed to Gala Wallet as the signer address. An Ethereum
598
+ * account is `0x` plus 40 hex digits (Gala Wallet's `eth|...` form is normalized to it and held
599
+ * to the same check); a GalaChain id is `client|` plus 24 hex digits, or the bare 24 hex digits
600
+ * frontend_v2 keeps for a direct `client|` login, and is passed through unchanged.
601
+ * @param options - Select native signing (default) or personal-sign explicitly.
602
+ * `'personal-sign'` requires a Gala Wallet build with wallet_extension commit 3ad7ae6.
603
+ * `selectAddress` is the identity (`client|...` / `eth|...`) Gala Wallet is switched to with
604
+ * `window.gala.setAddress` before every signature, when the wallet offers it.
605
+ */
606
+ constructor(walletAddress: string, options?: {
607
+ scheme?: GalaWalletScheme | undefined;
608
+ selectAddress?: string | undefined;
609
+ });
610
+ /** The identity Gala Wallet is switched to before each signature, if one was given. */
611
+ readonly selectAddress: string | undefined;
612
+ /**
613
+ * Signs a DTO through `gala_signChainDto`.
614
+ *
615
+ * @example
616
+ * ```typescript
617
+ * const signed = await signer.signObject('AddLiquidity', {
618
+ * token0: 'GALA',
619
+ * token1: 'GUSDC',
620
+ * tickLower: -60,
621
+ * tickUpper: 60,
622
+ * });
623
+ * ```
624
+ */
625
+ signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
626
+ }
627
+ /**
628
+ * A personal-sign signer for MetaMask and other EIP-1193 browser wallets.
629
+ *
630
+ * The chain recovers this signature using the EIP-191 wrap applied by the wallet to
631
+ * `personal_sign`. This is the browser-wallet path used by the v2 frontend and resolves the
632
+ * bare `eth|` identity.
633
+ */
634
+ export declare class BrowserWalletSigner implements GalaChainSigner {
635
+ private readonly provider;
636
+ /**
637
+ * Creates a browser-wallet signer.
638
+ *
639
+ * Defaults to `personal_sign` — unchanged from every existing integration, since it only ever
640
+ * resolves the bare `eth|` identity and changing that silently would be a real behavior
641
+ * break for anyone already depending on it. Pass `{ scheme: 'eip712' }` to correctly resolve
642
+ * a registered `client|` alias instead, for `RequestTrade`/`AddLiquidity`/`RemoveLiquidity`/
643
+ * `CollectPositionFees` (`EIP712_CAPABLE_METHODS`) — `CreatePool` and any other method still
644
+ * falls back to `personal_sign` even in `'eip712'` mode, since its EIP-712 signing is a
645
+ * separate, unsolved chain-side problem.
646
+ *
647
+ * @example
648
+ * ```typescript
649
+ * const signer = new BrowserWalletSigner(window.ethereum, '0x0123456789012345678901234567890123456789');
650
+ * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
651
+ * ```
652
+ * @example
653
+ * ```typescript
654
+ * // Correctly resolves a registered client| alias instead of the bare eth| address.
655
+ * const signer = new BrowserWalletSigner(window.ethereum, walletAddress, { scheme: 'eip712' });
656
+ * ```
657
+ */
658
+ constructor(provider: BrowserWalletProvider, walletAddress: string, options?: {
659
+ scheme?: 'personal-sign' | 'eip712';
660
+ });
661
+ readonly walletAddress: string;
662
+ private readonly scheme;
663
+ /**
664
+ * Signs the DTO with `eth_signTypedData_v4` (when constructed with `{ scheme: 'eip712' }` and
665
+ * `methodName` is in `EIP712_CAPABLE_METHODS`) or the EIP-1193 `personal_sign` method
666
+ * (otherwise — the default).
667
+ *
668
+ * @example
669
+ * ```typescript
670
+ * const signed = await signer.signObject('RequestTrade', {
671
+ * token0: 'GALA',
672
+ * token1: 'GUSDC',
673
+ * fee: 3000,
674
+ * });
675
+ * ```
676
+ */
677
+ signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
678
+ }
679
+ //#endregion
680
+ //#region src/classes/dex_fees.d.ts
681
+ /** DEX methods the backend accepts a fee quote for (its allow-list enumerates the same six). */
682
+ export declare const DEX_FEE_METHODS: readonly ['Swap', 'RequestTrade', 'AddLiquidity', 'RemoveLiquidity', 'CollectPositionFees', 'CreatePool'];
683
+ export type DexFeeMethod = (typeof DEX_FEE_METHODS)[number];
684
+ /** Which pool contract the DTO being quoted targets: legacy (V3) or current (GalaChainDex). */
685
+ export type DexFeeContract = 'dexv3-contract' | 'dex-contract';
686
+ /** The chain method name the signed DryRun wrapper is signed under. */
687
+ export declare const DRY_RUN_METHOD = "DryRun";
688
+ /** `uniqueKey` prefix of the DryRun WRAPPER (distinct from the inner DTO's key). */
689
+ export declare const DRY_RUN_UNIQUE_KEY_PREFIX = "galaconnect-operation-";
690
+ /** True when `method` is a DEX method a fee can be quoted for. */
691
+ export declare function isDexFeeMethod(method: unknown): method is DexFeeMethod;
692
+ /** Current-contract typed DEX messages use trading symbols instead of TokenClassKey objects. */
693
+ export declare function isCurrentContractDexMessage(message: Record<string, unknown> | null | undefined, method: unknown): boolean;
694
+ /**
695
+ * The backend's response. It ALWAYS carries a usable `fees[0].feeInGala`: the backend decides what
696
+ * to serve when the chain cannot price the operation, so the client never invents a fee.
697
+ *
698
+ * `source` is informational: `'dry-run'` is simulated on chain and authoritative (possibly a
699
+ * legitimate `'0'`), `'default'` means the chain could not price it and the platform default was
700
+ * served.
701
+ */
702
+ export interface DexFeeQuote {
703
+ fees: Array<{
704
+ feeInGala: string;
705
+ }>;
706
+ source: 'dry-run' | 'default';
707
+ }
708
+ /**
709
+ * Reduces an EIP-712 approval `message` to the DTO the chain actually receives: drops the signing
710
+ * envelope (`signature`, `prefix`, `types`, `domain`) and transport metadata (`trace`).
711
+ */
712
+ export declare function toChainDto(message: Record<string, unknown>): Record<string, unknown>;
713
+ /**
714
+ * Signs the DryRun WRAPPER the gateway accepts for every contract:
715
+ * `{ callerPublicKey, method, dto: <inner DTO object>, uniqueKey, signature }`. The inner DTO
716
+ * travels unsigned and as an object; no `signerPublicKey` is sent because the signature already
717
+ * recovers it (the gateway rejects it as REDUNDANT_SIGNER_PUBLIC_KEY). The wrapper carries its own
718
+ * `uniqueKey`, distinct from the DTO's.
719
+ */
720
+ export declare function buildDryRunWrapper(signer: GalaChainSigner, callerPublicKey: string, method: string, dto: Record<string, unknown>, uniqueKeyPrefix?: string): Promise<Record<string, unknown>>;
721
+ /** The transport and backend a fee quote reads from. */
722
+ export interface DexFeesClient {
723
+ /** Swap backend origin, e.g. `https://dex-backend-prod1.defi.gala.com`. */
724
+ dexBackendBaseUrl: string;
725
+ /** Defaults to the global `fetch`. */
726
+ httpRequestor?: HttpRequestor | undefined;
727
+ /** Per-request timeout in milliseconds (default 30 000). */
728
+ requestTimeoutMs?: number | undefined;
729
+ }
730
+ /** Options for a single quote. */
731
+ export interface DexFeeQuoteOptions {
732
+ /** GalaChain channel. Default `asset`. */
733
+ channel?: string | undefined;
734
+ /**
735
+ * Contract the DTO targets. Default `dexv3-contract` (what every legacy caller quotes against);
736
+ * a current-contract operation must pass `dex-contract` explicitly.
737
+ */
738
+ contract?: DexFeeContract | undefined;
739
+ }
740
+ /**
741
+ * Network-fee quote for GalaChain DEX methods, derived from a server-side DryRun.
742
+ *
743
+ * The client only SIGNS the DryRun wrapper (with whatever {@link GalaChainSigner} it is given) and
744
+ * the backend forwards it to the gateway, where the simulated writes carry the fee; the backend
745
+ * never holds a key. Intended for wallets: the DTO quoted is the typed message a dApp handed over.
746
+ *
747
+ * @example
748
+ * ```ts
749
+ * const fees = new DexFees({ dexBackendBaseUrl }, new PrivateKeySigner(sessionKey));
750
+ * const quote = await fees.quote(publicKey, 'RequestTrade', toChainDto(message), {
751
+ * contract: 'dex-contract',
752
+ * });
753
+ * const feeInGala = quote?.fees[0]?.feeInGala;
754
+ * ```
755
+ */
756
+ export declare class DexFees {
757
+ private readonly signer;
758
+ private readonly requestor;
759
+ private readonly baseUrl;
760
+ private readonly requestTimeoutMs;
761
+ constructor(client: DexFeesClient, signer: GalaChainSigner | undefined);
762
+ /**
763
+ * Quotes the network fee for `method` applied to `message`. The message is reduced with
764
+ * {@link toChainDto} first, so an EIP-712 approval message can be passed as is.
765
+ *
766
+ * Resolves `null` when the BACKEND could not be reached or answered unusably (offline, 4xx/5xx,
767
+ * malformed body): a transport outcome, not a fee. Deciding what to charge when the chain is
768
+ * silent is the backend's job (it serves `source: 'default'`), so the client never substitutes
769
+ * a fee of its own, with ONE exception that mirrors the wallet: a `dex-contract` quote answered
770
+ * 403 or 404 means the contract has no fee route yet and resolves `{ source: 'default', '0' }`.
771
+ * Never throws on transport, so a fee lookup cannot block or break a signing screen.
772
+ *
773
+ * @throws GSwapSDKError NO_SIGNER when constructed without a signer; any error the signer
774
+ * throws (for example a locked wallet) propagates unchanged.
775
+ */
776
+ quote(callerPublicKey: string, method: DexFeeMethod, message: Record<string, unknown>, options?: DexFeeQuoteOptions): Promise<DexFeeQuote | null>;
777
+ }
778
+ //#endregion
779
+ //#region src/classes/shadow_submit.d.ts
780
+ /** The raw answer to a shadow (dark) write: every HTTP status resolves. */
781
+ export interface ShadowSubmitResult {
782
+ httpStatus: number;
783
+ /** Parsed JSON body, or the raw text when the body was not JSON. */
784
+ body: unknown;
785
+ }
786
+ /**
787
+ * Machine-readable codes defi-backend returns in a shadow failure body (`{ code, message }`, with
788
+ * no `statusCode`; the HTTP status carries the number).
789
+ *
790
+ * - `SHADOW_UNAVAILABLE` (503): marking failed or infra not configured; retryable. Never fall back
791
+ * silently to a public swap.
792
+ * - `SHADOW_DISABLED` (400): the feature is off for this environment.
793
+ * - `SHADOW_UNSUPPORTED_TYPE` (400): shadow requested on a non-swap method.
794
+ * - `SHADOW_RELAY_REJECTED`: terminal business rejection (slippage, balance, ...), not retryable;
795
+ * `message` is the gateway's verbatim string.
796
+ */
797
+ export type ShadowSubmitCode = 'SHADOW_UNAVAILABLE' | 'SHADOW_DISABLED' | 'SHADOW_UNSUPPORTED_TYPE' | 'SHADOW_RELAY_REJECTED';
798
+ /** The normalized outcome of a shadow write. */
799
+ export type ShadowSubmitOutcome = {
800
+ ok: true;
801
+ /** The request transaction id (`''` when the gateway gave none). */
802
+ bundleId: string;
803
+ /** Present for a queued RequestTrade: confirm with `confirmAppliedTrade`. */
804
+ queued?: {
805
+ uniqueKey: string;
806
+ requestTransactionId: string | null;
807
+ };
808
+ } | {
809
+ ok: false;
810
+ kind: 'unavailable';
811
+ retryable: true;
812
+ } | {
813
+ ok: false;
814
+ kind: 'disabled';
815
+ retryable: false;
816
+ } | {
817
+ ok: false;
818
+ kind: 'rejected';
819
+ retryable: false;
820
+ message: string;
821
+ } | {
822
+ ok: false;
823
+ kind: 'unknown';
824
+ retryable: false;
825
+ };
826
+ type ShadowFailureKind = Exclude<ShadowSubmitOutcome, {
827
+ ok: true;
828
+ }>['kind'];
829
+ /** Maps an HTTP status to a failure kind: 503 retryable, 400 disabled, anything else unknown. */
830
+ export declare function classifyShadowSubmitStatus(status: number): ShadowFailureKind;
831
+ /**
832
+ * Prefers the body `code` (stable across status remaps) and falls back to the HTTP status.
833
+ * `SHADOW_UNAVAILABLE` is the only retryable case; `SHADOW_RELAY_REJECTED` is a terminal gateway
834
+ * rejection; the two other 400 codes and any unknown 400 map to "disabled".
835
+ */
836
+ export declare function classifyShadowSubmitError(status: number, code?: string): ShadowFailureKind;
837
+ /**
838
+ * Normalizes a shadow write's raw answer.
839
+ *
840
+ * A 2xx envelope with `error === false` is a success when it is a queued RequestTrade that
841
+ * acknowledges the EXACT signed `uniqueKey`, or a synchronous (`mode: 'sync'`) liquidity write.
842
+ * Everything else is classified as a failure from the status and the body's `code`.
843
+ *
844
+ * @throws GSwapSDKError INVALID_GATEWAY_RESPONSE when a RequestTrade success does not queue the
845
+ * signed `uniqueKey` (a synchronous or mismatched answer must never be accepted as a swap).
846
+ */
847
+ export declare function readShadowSubmitOutcome(method: string, signedBody: Record<string, unknown>, result: ShadowSubmitResult): ShadowSubmitOutcome;
848
+ //#endregion
849
+ //#region src/classes/submitted_transaction.d.ts
850
+ /** Result of one position-confirmation poll. */
851
+ export type PositionConfirmationResult = {
852
+ confirmed: true;
853
+ position: Position | null;
854
+ } | {
855
+ confirmed: false;
856
+ position?: Position | null;
857
+ };
858
+ /** A submitted v2 transaction whose confirmation mode is explicit in the gateway response. */
859
+ export declare class SubmittedTransaction<TConfirmation = AppliedTrade | Position | null> {
860
+ readonly method: string;
861
+ readonly uniqueKey: string;
862
+ readonly transactionId: string | null;
863
+ readonly blockNumber: number | null;
864
+ readonly mode: 'sync' | 'queued';
865
+ /** The synchronous gateway result, or `undefined` when `mode === 'queued'`. */
866
+ readonly result: unknown;
867
+ /**
868
+ * The gateway's whole JSON answer as it came (`{ status, message, error, data }`), for an app
869
+ * that hands the backend's own envelope to its callers; `undefined` for a transaction built from
870
+ * a uniqueKey alone.
871
+ */
872
+ readonly envelope: unknown;
873
+ private readonly backendBaseUrl;
874
+ private readonly requestor;
875
+ private readonly requestTimeoutMs;
876
+ private readonly positionConfirmation;
877
+ /** Construct a submitted transaction from a successful gateway response.
878
+ *
879
+ * @example
880
+ * ```ts
881
+ * const transaction = new SubmittedTransaction({
882
+ * method: 'RequestTrade', mode: 'queued', uniqueKey: 'swap-1',
883
+ * transactionId: 'request-tx', result: undefined,
884
+ * dexBackendBaseUrl: 'https://dex.example', httpRequestor,
885
+ * });
886
+ * ```
887
+ */
888
+ constructor(options: {
889
+ method: string;
890
+ uniqueKey: string;
891
+ transactionId: string | null;
892
+ mode: 'sync' | 'queued';
893
+ result: unknown;
894
+ dexBackendBaseUrl: string;
895
+ httpRequestor: HttpRequestor;
896
+ blockNumber?: number | null | undefined;
897
+ envelope?: unknown;
898
+ requestTimeoutMs?: number | undefined;
899
+ positionConfirmation?: ((signal: AbortSignal) => Promise<PositionConfirmationResult>) | undefined;
900
+ });
901
+ /** Confirm a queued RequestTrade or prove the affected position for a liquidity write.
902
+ *
903
+ * For RequestTrade, calling this method is required to learn the outcome: the queued
904
+ * acknowledgement proves acceptance, not execution.
905
+ *
906
+ * @example
907
+ * ```ts
908
+ * const applied = await submitted.confirm({ initialDelayMs: 3_000 });
909
+ * ```
910
+ */
911
+ confirm(options?: ConfirmOptions): Promise<TConfirmation>;
912
+ private confirmApplied;
913
+ /** Confirm a liquidity write against the position's observable effect.
914
+ *
915
+ * @returns The position after the write, or `null` for a confirmed full close.
916
+ * @example
917
+ * ```ts
918
+ * const position = await submitted.confirm({ timeoutMs: 60_000 });
919
+ * ```
920
+ */
921
+ private confirmPosition;
922
+ }
923
+ //#endregion
924
+ //#region src/classes/gateway.d.ts
925
+ /** Options for a chain-gateway client. */
926
+ export interface ChainGatewayOptions {
927
+ dexBackendBaseUrl: string;
928
+ httpRequestor?: HttpRequestor | undefined;
929
+ walletAddress?: string | undefined;
930
+ /**
931
+ * Timeout of every gateway request in milliseconds (default 30 000); also the per-read timeout
932
+ * of the services built on this gateway and of `confirm()`. `Infinity` arms no timer, for an
933
+ * app whose HTTP stack owns request lifetimes.
934
+ */
935
+ chainCallTimeoutMs?: number | undefined;
936
+ /** Wire format of the read requests of every service built on this gateway. */
937
+ wire?: WireOptions | undefined;
938
+ }
939
+ /** Optional attribution and operation-specific confirmation hooks for a write. */
940
+ export interface ChainSubmitOptions {
358
941
  walletAddress?: string | undefined;
359
942
  positionConfirmation?: ((signal: AbortSignal) => Promise<PositionConfirmationResult>) | undefined;
360
943
  }
@@ -365,11 +948,35 @@ export declare class ChainGateway {
365
948
  private readonly chainCallTimeoutMs;
366
949
  readonly requestTimeoutMs: number;
367
950
  readonly dexBackendBaseUrl: string;
951
+ /** Wire format shared by the read services built on this gateway. */
952
+ readonly wire: WireOptions;
368
953
  /** Create a chain gateway client. */
369
954
  constructor(options: ChainGatewayOptions);
370
955
  /** Submit a signed v2 DTO through the chain gateway. */
371
956
  submit(method: 'RequestTrade', signedBody: Record<string, unknown>, options?: ChainSubmitOptions): Promise<SubmittedTransaction<AppliedTrade>>;
372
957
  submit(method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions): Promise<SubmittedTransaction<Position | null>>;
958
+ /**
959
+ * Submit a signed v2 DTO as a SHADOW (dark) write: the same route and body as {@link submit},
960
+ * plus `X-Wallet-Address` and `X-Shadow: true`, so defi-backend marks the transaction private
961
+ * before it reaches the contract. The wallet address is required (the backend resolves the
962
+ * owner from it).
963
+ *
964
+ * Unlike `submit`, EVERY HTTP status resolves: the result is the raw `{ httpStatus, body }`,
965
+ * because shadow failures are classified from the status together with the body's `code`
966
+ * (`SHADOW_UNAVAILABLE`, `SHADOW_DISABLED`, `SHADOW_UNSUPPORTED_TYPE`, `SHADOW_RELAY_REJECTED`);
967
+ * see `readShadowSubmitOutcome`. Only a transport failure rejects, and a timeout rejects
968
+ * with `SUBMISSION_OUTCOME_UNKNOWN`.
969
+ *
970
+ * @example
971
+ * ```ts
972
+ * const result = await gateway.submitShadow('RequestTrade', signedDto, { walletAddress });
973
+ * const outcome = readShadowSubmitOutcome('RequestTrade', signedDto, result);
974
+ * ```
975
+ */
976
+ submitShadow(method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions): Promise<ShadowSubmitResult>;
977
+ private writeUrl;
978
+ /** POSTs a signed body; a timeout means the outcome is unknown, never "not submitted". */
979
+ private post;
373
980
  /** Expose the requestor for sibling read services that share this gateway transport. */
374
981
  get httpRequestor(): HttpRequestor;
375
982
  }
@@ -390,6 +997,20 @@ export interface GdexStreamConfig {
390
997
  * global `WebSocket` (pass the one from the `ws` package).
391
998
  */
392
999
  webSocketImpl?: unknown;
1000
+ /**
1001
+ * Presents `x-api-key` on the WebSocket upgrade request, which defi-backend uses to serve the
1002
+ * PRIVILEGED view (shadow swaps with the wallet unredacted). Without it, or with a wrong key, the
1003
+ * connection is simply public: the server never says whether a privileged mode exists.
1004
+ *
1005
+ * It must travel as an HTTP header, because the server reads no other credential, and a browser
1006
+ * `WebSocket` cannot set headers. So this option needs a constructor that accepts them as its
1007
+ * third argument (`{ headers }`): the `ws` package on Node.js, or React Native's built-in
1008
+ * `WebSocket`. It therefore REQUIRES `webSocketImpl` (the platform default is never assumed to
1009
+ * honor headers, and a key that is silently dropped would look like a working privileged
1010
+ * connection); the constructor throws otherwise. Use it from server-side code only: a key
1011
+ * shipped inside a browser or app bundle is not a secret. Browser clients stay public.
1012
+ */
1013
+ apiKey?: string | undefined;
393
1014
  }
394
1015
  /** The channels of the realtime stream. */
395
1016
  export type GdexChannel = 'pool' | 'balance' | 'poolCreated' | 'swap' | 'liquidity' | 'blocks';
@@ -482,6 +1103,7 @@ export declare class GdexStreamError extends Error {
482
1103
  export declare class GdexStreamService {
483
1104
  private readonly url;
484
1105
  private readonly requestTimeoutMs;
1106
+ private readonly apiKey;
485
1107
  private readonly webSocketConstructor;
486
1108
  private readonly backoff;
487
1109
  private socket;
@@ -502,6 +1124,7 @@ export declare class GdexStreamService {
502
1124
  isConnected(): boolean;
503
1125
  /** Raw JSON-RPC escape hatch. */
504
1126
  request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
1127
+ private send;
505
1128
  serverInfo(): Promise<Record<string, unknown>>;
506
1129
  ping(): Promise<{
507
1130
  pong: boolean;
@@ -537,7 +1160,11 @@ export declare class GdexStreamService {
537
1160
  poolHash?: string;
538
1161
  transactionId?: string;
539
1162
  }): Promise<GdexSubscription>;
540
- /** State changes of one pool. */
1163
+ /**
1164
+ * State changes of one pool (price, tick, reserves, liquidity). These events carry no acting wallet:
1165
+ * on v2 `creator` is whoever created the pool, not whoever just traded or added liquidity. For
1166
+ * "who did it", use {@link subscribeLiquidity} (`owner`) or {@link subscribeSwaps} (`sender`).
1167
+ */
541
1168
  subscribePool(selector: GdexPoolSelector, cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions): Promise<GdexSubscription>;
542
1169
  /** Balance changes of one wallet. */
543
1170
  subscribeBalances(owner: string, cb: (event: Record<string, unknown>) => void, opts?: GdexSubscribeOptions & {
@@ -591,13 +1218,31 @@ export declare const TICK_SPACING_BY_FEE: Readonly<Record<FEE_TIER, number>>;
591
1218
  /** All fee tiers supported by the current GalaChainDex contract. */
592
1219
  export declare const ALL_FEE_TIERS: readonly FEE_TIER[];
593
1220
  //#endregion
594
- //#region src/types/token.d.ts
595
- export interface GalaChainTokenClassKey {
596
- collection: string;
597
- category: string;
598
- type: string;
599
- additionalKey: string;
1221
+ //#region src/utils/lenient.d.ts
1222
+ /** One row of a list answer that the SDK skipped because it was not usable. */
1223
+ interface InvalidEntry {
1224
+ /** Which read the row came from. */
1225
+ source: 'pools' | 'symbols' | 'positions';
1226
+ /** Position of the row in the answer's array. */
1227
+ index: number;
1228
+ /** The row exactly as the backend sent it. */
1229
+ entry: unknown;
1230
+ /** Why it was skipped, in words. */
1231
+ reason: string;
600
1232
  }
1233
+ /**
1234
+ * Called once per skipped row, in order, before the read resolves. It is a diagnostics hook: what it
1235
+ * does, or throws, never changes the result of the read.
1236
+ */
1237
+ type InvalidEntryHandler = (invalid: InvalidEntry) => void;
1238
+ /** The outcome of reading one row. */
1239
+ type EntryParse<T> = {
1240
+ ok: true;
1241
+ value: T;
1242
+ } | {
1243
+ ok: false;
1244
+ reason: string;
1245
+ };
601
1246
  //#endregion
602
1247
  //#region src/utils/ordering.d.ts
603
1248
  /** A symbol or a GalaChain token class key accepted by v2 operations. */
@@ -638,15 +1283,26 @@ export declare function parseTokenClassKey(tokenClassKey: TokenRef): GalaChainTo
638
1283
  /** Symbol registry client for the current GalaChainDex contract. */
639
1284
  export declare class Symbols {
640
1285
  private readonly gateway;
1286
+ private readonly options;
641
1287
  private cachedSymbols;
642
1288
  private cachedAt;
643
1289
  private refreshInFlight;
644
1290
  private readonly http;
645
- /** Create a symbol service backed by the swap backend. */
1291
+ /**
1292
+ * Create a symbol service backed by the swap backend. `onInvalidEntry` is told about every
1293
+ * registry row that was skipped as unusable (see {@link InvalidEntryHandler}).
1294
+ */
646
1295
  constructor(gateway: Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
647
1296
  requestTimeoutMs?: number | undefined;
1297
+ wire?: WireOptions | undefined;
1298
+ }, options?: {
1299
+ onInvalidEntry?: InvalidEntryHandler | undefined;
648
1300
  });
649
- /** List all registered GalaChainDex trading symbols, cached for 60 seconds. */
1301
+ /**
1302
+ * List all registered GalaChainDex trading symbols, cached for 60 seconds. A registry row that
1303
+ * is not a usable symbol is skipped (and reported to `onInvalidEntry`) instead of failing the
1304
+ * whole list.
1305
+ */
650
1306
  list(): Promise<TradingSymbol[]>;
651
1307
  /** Invalidate the cached symbol registry after a write changes registration state.
652
1308
  *
@@ -666,6 +1322,31 @@ export declare class Symbols {
666
1322
  refresh(): Promise<TradingSymbol[]>;
667
1323
  /** Resolve a symbol or token class key to its registered symbol metadata. */
668
1324
  resolve(ref: TokenRef): Promise<TradingSymbol>;
1325
+ /**
1326
+ * The trading symbol to put in a token's first CreatePool.
1327
+ *
1328
+ * 1. The symbol ALREADY registered for exactly this class key, if any: proposing another one
1329
+ * fails the gateway's registry-conflict check.
1330
+ * 2. Otherwise `displaySymbol` (the token's curated symbol), when it is proposable
1331
+ * ({@link isProposableTradingSymbol}).
1332
+ * 3. Otherwise a `VALIDATION_ERROR`: a symbol is never derived from the key (BNB's collection is
1333
+ * `GBNB`, a launchpad token's is the reserved word `Token`).
1334
+ *
1335
+ * `registryFailure: 'ignore'` treats an unreachable registry as an empty one and falls through
1336
+ * to step 2 (the gateway still rejects a conflicting symbol); the default `'throw'` propagates
1337
+ * the failure.
1338
+ *
1339
+ * @example
1340
+ * ```ts
1341
+ * const symbol = await gSwap.symbols.proposeSymbol(
1342
+ * { collection: 'GALA_TEST1', category: 'Unit', type: 'none', additionalKey: 'none' },
1343
+ * 'GALATEST',
1344
+ * );
1345
+ * ```
1346
+ */
1347
+ proposeSymbol(classKey: GalaChainTokenClassKey, displaySymbol: string, options?: {
1348
+ registryFailure?: 'throw' | 'ignore' | undefined;
1349
+ }): Promise<string>;
669
1350
  /** Resolve and put two token references in canonical trading-symbol order. */
670
1351
  orderPair(a: TokenRef, b: TokenRef): Promise<{
671
1352
  token0: TradingSymbol;
@@ -675,38 +1356,109 @@ export declare class Symbols {
675
1356
  }
676
1357
  /** Alias exported for callers that use the contract's shorter type name. */
677
1358
  export type TokenClassKey = GalaChainTokenClassKey;
678
- //#endregion
679
- //#region src/classes/pools.d.ts
1359
+ /**
1360
+ * What the services need from a token resolver: how a token reference becomes a trading symbol,
1361
+ * and whether requests carry the caller's references untouched. {@link Symbols} is the registry
1362
+ * resolver (one `GET /v2/trade/symbols`, cached); {@link CanonicalSymbols} is the offline one.
1363
+ */
1364
+ export interface TokenResolver {
1365
+ resolve(ref: TokenRef): Promise<TradingSymbol>;
1366
+ /**
1367
+ * True when reads send the caller's token references verbatim (a symbol, or a composite key as
1368
+ * the caller wrote it) and let the backend resolve and orient the pair — no registry request
1369
+ * and no client-side ordering or tick flip.
1370
+ */
1371
+ readonly passthrough?: boolean | undefined;
1372
+ }
1373
+ /** A token reference as the caller wrote it: a string verbatim, a class key as its `$` composite. */
1374
+ export declare function rawTokenOf(ref: TokenRef): string;
1375
+ /** The trading symbol of a reference, or `SYMBOL_NOT_FOUND` when the resolver has none. */
1376
+ export declare function tradingSymbolOf(resolver: TokenResolver, ref: TokenRef): Promise<string>;
1377
+ /** What a read request names a token by: the reference itself in pass-through mode, else its symbol. */
1378
+ export declare function queryTokenOf(resolver: TokenResolver, ref: TokenRef): Promise<string>;
1379
+ /**
1380
+ * The offline resolver for apps that already hold the backend's canonical trading symbols (from
1381
+ * `/quote`, `/add-liq-estimate`, a position row) and must not make a registry request of their own.
1382
+ *
1383
+ * - `resolve` accepts a bare trading symbol and returns it as is; a class key (object, `$` or `|`
1384
+ * form) is not a symbol and is refused as `UNKNOWN_TOKEN`. `createPool` relies on that refusal to
1385
+ * fall back to the symbols its caller supplies.
1386
+ * - `orderPair` orders two symbols by plain string comparison, as the contract does.
1387
+ * - Reads are pass-through (see {@link TokenResolver.passthrough}): the caller's references go on
1388
+ * the wire verbatim, composite keys included, and the backend orients the pair.
1389
+ *
1390
+ * @example
1391
+ * ```ts
1392
+ * const swaps = new Swaps(gateway, new CanonicalSymbols(), signer, walletAddress);
1393
+ * await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '10' });
1394
+ * ```
1395
+ */
1396
+ export declare class CanonicalSymbols implements TokenResolver {
1397
+ readonly passthrough = true;
1398
+ /** Resolve a bare trading symbol to itself. */
1399
+ resolve(ref: TokenRef): Promise<TradingSymbol>;
1400
+ /** Put two symbols in canonical (string) order. */
1401
+ orderPair(a: TokenRef, b: TokenRef): Promise<{
1402
+ token0: TradingSymbol;
1403
+ token1: TradingSymbol;
1404
+ flipped: boolean;
1405
+ }>;
1406
+ /** There is no registry state to drop. */
1407
+ invalidate(): void;
1408
+ }
1409
+ //#endregion
1410
+ //#region src/classes/pools.d.ts
680
1411
  type PoolGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
681
1412
  requestTimeoutMs?: number | undefined;
1413
+ wire?: WireOptions | undefined;
682
1414
  };
683
- type PoolSymbols = Pick<Symbols, 'resolve'>;
1415
+ /** The sort keys of `GET /v2/trade/pools`. */
1416
+ export type PoolSortBy = 'tvl' | 'volume1d' | 'volume30d';
1417
+ /** Options of {@link Pools.getPools}. Omit all of `search`, `sortBy`, `sortOrder`, `page`, `limit` for the full, unsorted list. */
1418
+ export interface PoolListOptions {
1419
+ signal?: AbortSignal | undefined;
1420
+ /** Case-insensitive match on the pair's symbols; `A/B` or `A B` matches either order. At most 64 characters. */
1421
+ search?: string | undefined;
1422
+ sortBy?: PoolSortBy | undefined;
1423
+ sortOrder?: 'asc' | 'desc' | undefined;
1424
+ /** 1-based page number; only meaningful together with `limit`. */
1425
+ page?: number | undefined;
1426
+ /** Rows per page, 1-1000; omitted returns every row. */
1427
+ limit?: number | undefined;
1428
+ /** Overrides the service-level handler for this call. */
1429
+ onInvalidEntry?: InvalidEntryHandler | undefined;
1430
+ }
684
1431
  /** Read-only pool and current-price access for the current GalaChainDex contract. */
685
1432
  export declare class Pools {
686
1433
  private readonly gateway;
687
1434
  private readonly symbols;
1435
+ private readonly options;
688
1436
  /**
689
- * Creates a pool service.
1437
+ * Creates a pool service. `options.onInvalidEntry` is told about every pool row that was
1438
+ * skipped as unusable (see {@link InvalidEntryHandler}).
690
1439
  *
691
1440
  * @example
692
1441
  * ```ts
693
1442
  * const pools = new Pools(gateway, symbols);
694
1443
  * ```
695
1444
  */
696
- constructor(gateway: PoolGateway, symbols: PoolSymbols);
1445
+ constructor(gateway: PoolGateway, symbols: TokenResolver, options?: {
1446
+ onInvalidEntry?: InvalidEntryHandler | undefined;
1447
+ });
697
1448
  private readonly http;
698
1449
  /**
699
- * Fetches every current-contract pool from the swap backend.
1450
+ * Fetches current-contract pools from the swap backend, optionally searched, sorted and paged
1451
+ * by the backend. A row that is not a usable pool is skipped and reported to `onInvalidEntry`
1452
+ * instead of failing the whole list; an answer that is not a list at all is
1453
+ * `INVALID_CHAIN_RESPONSE`.
700
1454
  *
701
1455
  * @example
702
1456
  * ```ts
703
- * const pools = await service.getPools();
704
- * console.log(pools.length);
1457
+ * const top = await service.getPools({ sortBy: 'tvl', sortOrder: 'desc', page: 1, limit: 8 });
1458
+ * console.log(top.length);
705
1459
  * ```
706
1460
  */
707
- getPools(options?: {
708
- signal?: AbortSignal | undefined;
709
- }): Promise<PoolListInfo[]>;
1461
+ getPools(options?: PoolListOptions): Promise<PoolListInfo[]>;
710
1462
  /**
711
1463
  * Fetches one pool from the backend, preserving whether the request order was flipped.
712
1464
  *
@@ -741,187 +1493,258 @@ export declare class Pools {
741
1493
  private getBackend;
742
1494
  }
743
1495
  //#endregion
744
- //#region src/classes/signers.d.ts
745
- /** The signing schemes supported by the Gala Wallet signer. */
746
- export type GalaWalletScheme = 'native' | 'personal-sign';
747
- /** The request surface used by an EIP-1193 browser wallet. */
748
- export interface BrowserWalletProvider {
749
- request(args: {
750
- method: string;
751
- params?: unknown[];
752
- }): Promise<unknown>;
1496
+ //#region src/types/branding.d.ts
1497
+ interface Branding<BrandT> {
1498
+ _type: BrandT;
753
1499
  }
754
- type SignedDto<T extends Record<string, unknown>> = T & {
755
- signature: string;
756
- };
1500
+ type Brand<T, BrandT> = T & Branding<BrandT>;
1501
+ //#endregion
1502
+ //#region src/types/amounts.d.ts
1503
+ export type NumericAmount = string | BigNumber;
1504
+ export type SqrtPrice = Brand<BigNumber, 'SqrtPrice'>;
1505
+ export type SqrtPriceIn = Brand<NumericAmount, 'SqrtPriceIn'> | SqrtPrice;
1506
+ export type Price = Brand<BigNumber, 'Price'>;
1507
+ export type PriceIn = Brand<NumericAmount, 'PriceIn'> | Price;
757
1508
  /**
758
- * A signer for complete GalaChain write bodies.
759
- *
760
- * Implementations return the DTO fields together with the signature that belongs in the
761
- * gateway request body. Signer identity is recovered from that signature; implementations do
762
- * not add signer hints, typed-data metadata, or a domain.
1509
+ * What a swap trades: exactly one of `exactIn` (sell this much of the input token) or `exactOut`
1510
+ * (receive this much of the output token), with that side's slippage bound and an optional
1511
+ * sqrt-price limit.
763
1512
  */
764
- export interface GalaChainSigner {
765
- /**
766
- * Signs a DTO for a named GalaChain contract method.
767
- *
768
- * @example
769
- * ```typescript
770
- * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
771
- * ```
772
- */
773
- signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
1513
+ export type SwapAmount = {
1514
+ exactIn: NumericAmount;
1515
+ exactOut?: undefined;
1516
+ amountOutMinimum?: NumericAmount | undefined;
1517
+ amountInMaximum?: undefined;
1518
+ /** Sqrt-price limit passed through to the chain as `priceLimit`; omitted when undefined. */
1519
+ priceLimit?: NumericAmount | undefined;
1520
+ } | {
1521
+ exactIn?: undefined;
1522
+ exactOut: NumericAmount;
1523
+ amountOutMinimum?: undefined;
1524
+ amountInMaximum?: NumericAmount | undefined;
1525
+ /** Sqrt-price limit passed through to the chain as `priceLimit`; omitted when undefined. */
1526
+ priceLimit?: NumericAmount | undefined;
1527
+ };
1528
+ //#endregion
1529
+ //#region src/types/v2_dtos.d.ts
1530
+ /** Common identity fields for v2 pool writes. */
1531
+ export type V2PoolWriteBase = Record<'token0' | 'token1' | 'uniqueKey', string> & {
1532
+ fee: FEE_TIER;
1533
+ };
1534
+ /** A v2 RequestTrade with exactly one selected trade-side quantity. */
1535
+ export type RequestTradeDTO = V2PoolWriteBase & ({
1536
+ sell0Qty: string;
1537
+ sell1Qty?: never;
1538
+ buy0Qty?: never;
1539
+ buy1Qty?: never;
1540
+ } | {
1541
+ sell0Qty?: never;
1542
+ sell1Qty: string;
1543
+ buy0Qty?: never;
1544
+ buy1Qty?: never;
1545
+ } | {
1546
+ sell0Qty?: never;
1547
+ sell1Qty?: never;
1548
+ buy0Qty: string;
1549
+ buy1Qty?: never;
1550
+ } | {
1551
+ sell0Qty?: never;
1552
+ sell1Qty?: never;
1553
+ buy0Qty?: never;
1554
+ buy1Qty: string;
1555
+ }) & {
1556
+ amountOutMinimum?: string | undefined;
1557
+ amountInMaximum?: string | undefined;
1558
+ priceLimit?: string | undefined;
1559
+ };
1560
+ /** A v2 liquidity deposit with exactly one selected deposit quantity. */
1561
+ export type AddLiquidityDTO = V2PoolWriteBase & {
1562
+ tickLower: number;
1563
+ tickUpper: number;
1564
+ } & ({
1565
+ depositQuantityToken0: string;
1566
+ depositQuantityToken1?: never;
1567
+ } | {
1568
+ depositQuantityToken0?: never;
1569
+ depositQuantityToken1: string;
1570
+ });
1571
+ /** A v2 liquidity withdrawal; omitting both quantities closes the position. */
1572
+ export type RemoveLiquidityDTO = V2PoolWriteBase & {
1573
+ tickLower: number;
1574
+ tickUpper: number;
1575
+ } & ({
1576
+ withdrawalQuantityToken0: string;
1577
+ withdrawalQuantityToken1?: never;
1578
+ } | {
1579
+ withdrawalQuantityToken0?: never;
1580
+ withdrawalQuantityToken1: string;
1581
+ } | {
1582
+ withdrawalQuantityToken0?: never;
1583
+ withdrawalQuantityToken1?: never;
1584
+ });
1585
+ /** A v2 request to sweep all fees from one position. */
1586
+ export type CollectPositionFeesDTO = V2PoolWriteBase & {
1587
+ tickLower: number;
1588
+ tickUpper: number;
1589
+ };
1590
+ /** A v2 pool creation request with exactly one initial-price representation. */
1591
+ export type CreatePoolDTO = {
1592
+ token0Key: GalaChainTokenClassKey;
1593
+ token1Key: GalaChainTokenClassKey;
1594
+ token0Symbol: string;
1595
+ token1Symbol: string;
1596
+ fee: FEE_TIER;
1597
+ name?: string | undefined;
1598
+ isPrivate?: boolean | undefined;
1599
+ privateAccess?: string[] | undefined;
1600
+ uniqueKey: string;
1601
+ } & ({
1602
+ startingPrice: string;
1603
+ startingSqrtPrice?: never;
1604
+ } | {
1605
+ startingPrice?: never;
1606
+ startingSqrtPrice: string;
1607
+ });
1608
+ /** Optional page cursor accepted by chain read methods. */
1609
+ export interface PageDTO {
1610
+ limit?: number | undefined;
1611
+ bookmark?: string | undefined;
774
1612
  }
1613
+ /** Fetch all registered trading symbols. */
1614
+ export type FetchTokenTradingSymbolsDTO = PageDTO;
1615
+ /** Fetch a composite pool snapshot. */
1616
+ export interface FetchCompositePoolDataDTO {
1617
+ token0: string;
1618
+ token1: string;
1619
+ fee: FEE_TIER;
1620
+ }
1621
+ /** Fetch one current trading price, or all prices when no pair is supplied. */
1622
+ export type FetchCurrentTradingPricesDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
1623
+ /** Fetch pools, optionally narrowed to one pair and paged. */
1624
+ export type FetchPoolsDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
1625
+ /** Fetch all liquidity positions, optionally narrowed to a pool reference. */
1626
+ export interface FetchLiquidityPositionsDTO extends PageDTO {
1627
+ pool?: string | undefined;
1628
+ }
1629
+ //#endregion
1630
+ //#region src/utils/unique_key.d.ts
775
1631
  /**
776
- * A GalaChain native signer backed by a secp256k1 private key.
777
- *
778
- * Native signing produces the bare GalaChain signature format, without a personal-sign prefix
779
- * or EIP-712 metadata. The private-key identity is recovered by the chain.
1632
+ * The `uniqueKey` prefix frontend_v2 and wallet_extension have always sent
1633
+ * (`galaswap-operation-<uuid>`). defi-backend does not depend on it: the chain-write verifier
1634
+ * only requires a non-empty key of at most 256 characters, and apply-results accepts
1635
+ * `[A-Za-z0-9._:-]{1,128}`; the only code that mints a prefixed key itself is the server-side v1
1636
+ * trade builder, which nothing reads back by prefix.
780
1637
  */
781
- export declare class PrivateKeySigner implements GalaChainSigner {
782
- private readonly keyBuffer;
1638
+ export declare const DEFAULT_UNIQUE_KEY_PREFIX = "galaswap-operation-";
1639
+ /** Options shared by the services that mint `uniqueKey`s for writes. */
1640
+ export interface UniqueKeyOptions {
783
1641
  /**
784
- * Creates a native signer from a hex or base64 secp256k1 private key.
785
- *
786
- * @example
787
- * ```typescript
788
- * const signer = new PrivateKeySigner('1'.padStart(64, '0'));
789
- * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
790
- * ```
791
- */
792
- constructor(privateKey: string);
793
- /**
794
- * Signs the DTO with GalaChain native signing.
795
- *
796
- * @example
797
- * ```typescript
798
- * const signed = await signer.signObject('RequestTrade', {
799
- * token0: 'GALA',
800
- * token1: 'GUSDC',
801
- * fee: 3000,
802
- * });
803
- * ```
1642
+ * Prefix of every minted `uniqueKey` (`<prefix><uuid>`). Defaults to
1643
+ * `DEFAULT_UNIQUE_KEY_PREFIX` (`galaswap-operation-`).
804
1644
  */
805
- signObject<T extends Record<string, unknown>>(_methodName: string, dto: T): Promise<SignedDto<T>>;
1645
+ uniqueKeyPrefix?: string | undefined;
806
1646
  }
807
1647
  /**
808
- * A Gala Wallet signer using native GalaChain signing, with an opt-in personal-sign mode and
809
- * automatic fallback for older wallets.
1648
+ * Validates a caller-supplied `uniqueKey` prefix. The whole key (`<prefix><uuid>`) must stay a
1649
+ * valid apply-results key, otherwise `confirm()` could never read the outcome of the write.
810
1650
  *
811
- * The selected Ethereum account is passed to Gala Wallet. Personal-sign resolves the bare
812
- * `eth|` identity; the legacy EIP-712 `eth_signTypedData` path is not used. The fallback calls
813
- * `gala_signChainDto([serialize({ ...dto, prefix }), walletAddress, methodName])`.
1651
+ * @throws GSwapSDKError VALIDATION_ERROR when the prefix has characters outside `A-Za-z0-9._:-` or
1652
+ * is longer than 92 characters.
814
1653
  */
815
- export declare class GalaWalletSigner implements GalaChainSigner {
816
- /** The wallet address supplied to Gala Wallet for each signing request. */
817
- readonly walletAddress: string;
818
- /** The scheme currently used, including any automatic native-to-personal fallback. */
819
- effectiveScheme: GalaWalletScheme;
820
- /**
821
- * Creates a Gala Wallet signer.
822
- *
823
- * @example
824
- * ```typescript
825
- * const signer = new GalaWalletSigner('0x0123456789012345678901234567890123456789');
826
- * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
827
- * ```
828
- *
829
- * @param walletAddress - The selected Ethereum account (`0x` plus 40 hex digits); Gala Wallet's
830
- * `eth|0x...` form is also accepted and normalized.
831
- * @param options - Select native signing or personal-sign explicitly.
832
- */
833
- constructor(walletAddress: string, options?: {
834
- scheme?: GalaWalletScheme | undefined;
835
- });
836
- /**
837
- * Signs a DTO through `gala_signChainDto`.
838
- *
839
- * @example
840
- * ```typescript
841
- * const signed = await signer.signObject('AddLiquidity', {
842
- * token0: 'GALA',
843
- * token1: 'GUSDC',
844
- * tickLower: -60,
845
- * tickUpper: 60,
846
- * });
847
- * ```
848
- */
849
- signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
850
- }
1654
+ export declare function resolveUniqueKeyPrefix(prefix: string | undefined): string;
851
1655
  /**
852
- * A personal-sign signer for MetaMask and other EIP-1193 browser wallets.
1656
+ * Validates a caller-supplied write `uniqueKey`: 1 to 128 characters of `A-Za-z0-9._:-`, the
1657
+ * shape the apply-results route accepts, so the write's outcome can always be read back with
1658
+ * `confirm()`. A key is one attempt's identity: reuse it only to retry that same attempt.
853
1659
  *
854
- * The chain recovers this signature using the EIP-191 wrap applied by the wallet to
855
- * `personal_sign`. This is the browser-wallet path used by the v2 frontend and resolves the
856
- * bare `eth|` identity.
1660
+ * @throws GSwapSDKError VALIDATION_ERROR otherwise.
857
1661
  */
858
- export declare class BrowserWalletSigner implements GalaChainSigner {
859
- private readonly provider;
860
- /**
861
- * Creates a browser-wallet signer.
862
- *
863
- * Defaults to `personal_sign` — unchanged from every existing integration, since it only ever
864
- * resolves the bare `eth|` identity and changing that silently would be a real behavior
865
- * break for anyone already depending on it. Pass `{ scheme: 'eip712' }` to correctly resolve
866
- * a registered `client|` alias instead, for `RequestTrade`/`AddLiquidity`/`RemoveLiquidity`/
867
- * `CollectPositionFees` (`EIP712_CAPABLE_METHODS`) — `CreatePool` and any other method still
868
- * falls back to `personal_sign` even in `'eip712'` mode, since its EIP-712 signing is a
869
- * separate, unsolved chain-side problem.
870
- *
871
- * @example
872
- * ```typescript
873
- * const signer = new BrowserWalletSigner(window.ethereum, '0x0123456789012345678901234567890123456789');
874
- * const signed = await signer.signObject('RequestTrade', { token0: 'GALA', token1: 'GUSDC' });
875
- * ```
876
- * @example
877
- * ```typescript
878
- * // Correctly resolves a registered client| alias instead of the bare eth| address.
879
- * const signer = new BrowserWalletSigner(window.ethereum, walletAddress, { scheme: 'eip712' });
880
- * ```
881
- */
882
- constructor(provider: BrowserWalletProvider, walletAddress: string, options?: {
883
- scheme?: 'personal-sign' | 'eip712';
884
- });
885
- readonly walletAddress: string;
886
- private readonly scheme;
887
- /**
888
- * Signs the DTO with `eth_signTypedData_v4` (when constructed with `{ scheme: 'eip712' }` and
889
- * `methodName` is in `EIP712_CAPABLE_METHODS`) or the EIP-1193 `personal_sign` method
890
- * (otherwise — the default).
891
- *
892
- * @example
893
- * ```typescript
894
- * const signed = await signer.signObject('RequestTrade', {
895
- * token0: 'GALA',
896
- * token1: 'GUSDC',
897
- * fee: 3000,
898
- * });
899
- * ```
900
- */
901
- signObject<T extends Record<string, unknown>>(methodName: string, dto: T): Promise<SignedDto<T>>;
902
- }
903
- //#endregion
904
- //#region src/types/branding.d.ts
905
- interface Branding<BrandT> {
906
- _type: BrandT;
907
- }
908
- type Brand<T, BrandT> = T & Branding<BrandT>;
909
- //#endregion
910
- //#region src/types/amounts.d.ts
911
- export type NumericAmount = string | BigNumber;
912
- export type SqrtPrice = Brand<BigNumber, 'SqrtPrice'>;
913
- export type SqrtPriceIn = Brand<NumericAmount, 'SqrtPriceIn'> | SqrtPrice;
914
- export type Price = Brand<BigNumber, 'Price'>;
915
- export type PriceIn = Brand<NumericAmount, 'PriceIn'> | Price;
1662
+ export declare function assertUniqueKey(uniqueKey: string): void;
1663
+ /** A fresh per-attempt key: `<prefix><random UUID>`. */
1664
+ export declare function createUniqueKey(prefix: string): string;
916
1665
  //#endregion
917
1666
  //#region src/classes/positions.d.ts
918
1667
  type PositionGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
919
1668
  submit: (method: string, signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<SubmittedTransaction<Position | null>>;
920
1669
  requestTimeoutMs?: number | undefined;
1670
+ wire?: WireOptions | undefined;
921
1671
  };
922
- type PositionSymbols = Pick<Symbols, 'resolve' | 'orderPair'> & {
1672
+ type PositionSymbols = TokenResolver & Pick<Symbols, 'orderPair'> & {
923
1673
  invalidate?: () => void;
924
1674
  };
1675
+ /** Options of {@link Positions}: the `uniqueKey` prefix and a handler for skipped list rows. */
1676
+ export interface PositionsOptions extends UniqueKeyOptions {
1677
+ /** Told about every position row of a list that was skipped as unusable. */
1678
+ onInvalidEntry?: InvalidEntryHandler | undefined;
1679
+ }
1680
+ /** A write's optional attempt identity. */
1681
+ interface UniqueKeyArg {
1682
+ /**
1683
+ * The attempt's `uniqueKey` (1-128 characters of `A-Za-z0-9._:-`). Default: a fresh
1684
+ * `<uniqueKeyPrefix><uuid>`. Supply one to know the key before signing, or to retry the SAME
1685
+ * attempt after a lost response; never reuse it for another write.
1686
+ */
1687
+ uniqueKey?: string | undefined;
1688
+ }
1689
+ /** Arguments of {@link Positions.addLiquidityByTicks} and {@link Positions.buildAddLiquidity}. */
1690
+ export interface AddLiquidityArgs extends UniqueKeyArg {
1691
+ token0: TokenRef;
1692
+ token1: TokenRef;
1693
+ fee: FEE_TIER;
1694
+ tickLower: number;
1695
+ tickUpper: number;
1696
+ amount: NumericAmount;
1697
+ /** Whether `amount` is of `token0` as the caller passed it (not of the canonical token0). */
1698
+ amountIsToken0: boolean;
1699
+ }
1700
+ /** Arguments of {@link Positions.removeLiquidity} and {@link Positions.buildRemoveLiquidity}. */
1701
+ export interface RemoveLiquidityArgs extends UniqueKeyArg {
1702
+ token0: TokenRef;
1703
+ token1: TokenRef;
1704
+ fee: FEE_TIER;
1705
+ tickLower: number;
1706
+ tickUpper: number;
1707
+ /** Withdraw this much of the caller's `token0`; give at most one of `amount0` / `amount1`. */
1708
+ amount0?: NumericAmount | undefined;
1709
+ amount1?: NumericAmount | undefined;
1710
+ }
1711
+ /** Arguments of {@link Positions.collectPositionFees} and {@link Positions.buildCollectPositionFees}. */
1712
+ export interface CollectPositionFeesArgs extends UniqueKeyArg {
1713
+ token0: TokenRef;
1714
+ token1: TokenRef;
1715
+ fee: FEE_TIER;
1716
+ tickLower: number;
1717
+ tickUpper: number;
1718
+ }
1719
+ /** Arguments of {@link Positions.createPool} and {@link Positions.buildCreatePool}. */
1720
+ export interface CreatePoolArgs extends UniqueKeyArg {
1721
+ token0: TokenRef;
1722
+ token1: TokenRef;
1723
+ token0Symbol?: string | undefined;
1724
+ token1Symbol?: string | undefined;
1725
+ fee: FEE_TIER;
1726
+ startingPrice?: NumericAmount | undefined;
1727
+ startingSqrtPrice?: NumericAmount | undefined;
1728
+ /** Optional pool display name, sent as the DTO's `name`; omitted when undefined or empty. */
1729
+ name?: string | undefined;
1730
+ isPrivate?: boolean | undefined;
1731
+ privateAccess?: string[] | undefined;
1732
+ }
1733
+ /**
1734
+ * The outcome of {@link Positions.readPosition}. Only `not_found` is chain-confirmed absence (the
1735
+ * backend answers HTTP 404 only when the chain itself found no such position); `unknown` is "no
1736
+ * evidence either way" — a transport failure, a gateway timeout, any other error status or an
1737
+ * answer that is not a position — and must never be read as a removal.
1738
+ */
1739
+ export type PositionRead = {
1740
+ kind: 'found';
1741
+ data: Position;
1742
+ } | {
1743
+ kind: 'not_found';
1744
+ } | {
1745
+ kind: 'unknown';
1746
+ error: GSwapSDKError;
1747
+ };
925
1748
  /**
926
1749
  * Manages current-contract concentrated-liquidity positions.
927
1750
  *
@@ -937,13 +1760,16 @@ export declare class Positions {
937
1760
  private readonly symbols;
938
1761
  private readonly signer?;
939
1762
  private readonly walletAddress?;
940
- constructor(gateway: PositionGateway, symbols: PositionSymbols, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined);
1763
+ constructor(gateway: PositionGateway, symbols: PositionSymbols, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined, options?: PositionsOptions);
941
1764
  private readonly http;
1765
+ private readonly uniqueKeyPrefix;
1766
+ private readonly onInvalidEntry;
942
1767
  /**
943
1768
  * Gets all current-contract positions owned by an address.
944
1769
  *
945
1770
  * @param owner - GalaChain owner identity.
946
- * @returns Enriched positions from the v2 trade backend.
1771
+ * @returns Enriched positions from the v2 trade backend, token images included. A row that is
1772
+ * not a usable position is skipped and reported to `onInvalidEntry`.
947
1773
  * @example
948
1774
  * ```typescript
949
1775
  * const positions = await gSwap.positions.getUserPositions('client|012345678901234567890123');
@@ -972,6 +1798,37 @@ export declare class Positions {
972
1798
  tickLower: number;
973
1799
  tickUpper: number;
974
1800
  }, signal?: AbortSignal): Promise<Position | null>;
1801
+ /**
1802
+ * Reads one position and classifies the outcome instead of throwing: `found` with the position
1803
+ * (fees included), `not_found` (the backend's HTTP 404, which it sends only when the chain
1804
+ * itself has no such position) or `unknown` (any other failure, carried as `error`). Use it
1805
+ * to confirm a write: `unknown` is "no evidence either way", never a confirmed absence.
1806
+ *
1807
+ * Only the caller's own abort rethrows. With a pass-through resolver ({@link CanonicalSymbols})
1808
+ * the pair and ticks go to the backend exactly as given and the backend orients them.
1809
+ *
1810
+ * @example
1811
+ * ```typescript
1812
+ * const read = await gSwap.positions.readPosition({
1813
+ * token0: 'GALA', token1: 'GUSDC', owner: 'client|012345678901234567890123',
1814
+ * fee: 3000, tickLower: -19200, tickUpper: 12000,
1815
+ * });
1816
+ * if (read.kind === 'found') console.log(read.data.fees0);
1817
+ * ```
1818
+ */
1819
+ readPosition(args: {
1820
+ token0: TokenRef;
1821
+ token1: TokenRef;
1822
+ fee: FEE_TIER;
1823
+ owner: string;
1824
+ tickLower: number;
1825
+ tickUpper: number;
1826
+ }, signal?: AbortSignal): Promise<PositionRead>;
1827
+ /**
1828
+ * The `/position` query: canonical symbols and canonical ticks after a client-side flip, or,
1829
+ * for a pass-through resolver, the caller's references and ticks untouched.
1830
+ */
1831
+ private positionParams;
975
1832
  /**
976
1833
  * Estimates the other token amount and resulting liquidity for a deposit.
977
1834
  *
@@ -1029,15 +1886,28 @@ export declare class Positions {
1029
1886
  * await tx.confirm();
1030
1887
  * ```
1031
1888
  */
1032
- addLiquidityByTicks(args: {
1033
- token0: TokenRef;
1034
- token1: TokenRef;
1035
- fee: FEE_TIER;
1036
- tickLower: number;
1037
- tickUpper: number;
1038
- amount: NumericAmount;
1039
- amountIsToken0: boolean;
1040
- }): Promise<SubmittedTransaction<Position | null>>;
1889
+ addLiquidityByTicks(args: AddLiquidityArgs): Promise<SubmittedTransaction<Position | null>>;
1890
+ /**
1891
+ * Builds the AddLiquidity DTO that {@link addLiquidityByTicks} would sign, without signing or
1892
+ * sending it: to show in an approval popup, or to sign elsewhere. Submit exactly this DTO with
1893
+ * {@link submitAddLiquidity}. The pure counterpart, with canonical inputs and no resolution,
1894
+ * is `buildAddLiquidityDto`.
1895
+ *
1896
+ * @example
1897
+ * ```typescript
1898
+ * const dto = await gSwap.positions.buildAddLiquidity({
1899
+ * token0: 'GALA', token1: 'GUSDC', fee: 3000,
1900
+ * tickLower: -19200, tickUpper: 12000, amount: '100', amountIsToken0: true,
1901
+ * });
1902
+ * ```
1903
+ */
1904
+ buildAddLiquidity(args: AddLiquidityArgs): Promise<AddLiquidityDTO>;
1905
+ /**
1906
+ * Signs and submits a DTO built by {@link buildAddLiquidity} or `buildAddLiquidityDto`; it must
1907
+ * be exactly what the builder produces. The returned transaction confirms by proving the
1908
+ * position's liquidity grew.
1909
+ */
1910
+ submitAddLiquidity(dto: AddLiquidityDTO): Promise<SubmittedTransaction<Position | null>>;
1041
1911
  /**
1042
1912
  * Adds liquidity from prices, flooring the lower tick and ceiling the upper tick to fee spacing.
1043
1913
  * The resulting range is therefore no narrower than the requested price interval.
@@ -1060,6 +1930,8 @@ export declare class Positions {
1060
1930
  maxPrice: PriceIn;
1061
1931
  amount: NumericAmount;
1062
1932
  amountIsToken0: boolean;
1933
+ /** The attempt's `uniqueKey`; default a fresh one (see {@link AddLiquidityArgs.uniqueKey}). */
1934
+ uniqueKey?: string | undefined;
1063
1935
  }): Promise<SubmittedTransaction<Position | null>>;
1064
1936
  /**
1065
1937
  * Removes liquidity by withdrawing at most one canonical token quantity.
@@ -1075,15 +1947,19 @@ export declare class Positions {
1075
1947
  * });
1076
1948
  * ```
1077
1949
  */
1078
- removeLiquidity(args: {
1079
- token0: TokenRef;
1080
- token1: TokenRef;
1081
- fee: FEE_TIER;
1082
- tickLower: number;
1083
- tickUpper: number;
1084
- amount0?: NumericAmount | undefined;
1085
- amount1?: NumericAmount | undefined;
1086
- }): Promise<SubmittedTransaction<Position | null>>;
1950
+ removeLiquidity(args: RemoveLiquidityArgs): Promise<SubmittedTransaction<Position | null>>;
1951
+ /**
1952
+ * Builds the RemoveLiquidity DTO that {@link removeLiquidity} would sign, without signing or
1953
+ * sending it. Submit exactly this DTO with {@link submitRemoveLiquidity}. The pure counterpart
1954
+ * is `buildRemoveLiquidityDto`.
1955
+ */
1956
+ buildRemoveLiquidity(args: RemoveLiquidityArgs): Promise<RemoveLiquidityDTO>;
1957
+ /**
1958
+ * Signs and submits a DTO built by {@link buildRemoveLiquidity} or `buildRemoveLiquidityDto`;
1959
+ * it must be exactly what the builder produces. A DTO with no withdrawal quantity closes the
1960
+ * position, and the returned transaction then confirms by proving the position is gone.
1961
+ */
1962
+ submitRemoveLiquidity(dto: RemoveLiquidityDTO): Promise<SubmittedTransaction<Position | null>>;
1087
1963
  /**
1088
1964
  * Collects all accrued fees for a position; the contract does not support partial collection.
1089
1965
  *
@@ -1097,13 +1973,18 @@ export declare class Positions {
1097
1973
  * });
1098
1974
  * ```
1099
1975
  */
1100
- collectPositionFees(args: {
1101
- token0: TokenRef;
1102
- token1: TokenRef;
1103
- fee: FEE_TIER;
1104
- tickLower: number;
1105
- tickUpper: number;
1106
- }): Promise<SubmittedTransaction<Position | null>>;
1976
+ collectPositionFees(args: CollectPositionFeesArgs): Promise<SubmittedTransaction<Position | null>>;
1977
+ /**
1978
+ * Builds the CollectPositionFees DTO that {@link collectPositionFees} would sign, without
1979
+ * signing or sending it. Submit exactly this DTO with {@link submitCollectPositionFees}. The
1980
+ * pure counterpart is `buildCollectPositionFeesDto`.
1981
+ */
1982
+ buildCollectPositionFees(args: CollectPositionFeesArgs): Promise<CollectPositionFeesDTO>;
1983
+ /**
1984
+ * Signs and submits a DTO built by {@link buildCollectPositionFees} or
1985
+ * `buildCollectPositionFeesDto`; it must be exactly what the builder produces.
1986
+ */
1987
+ submitCollectPositionFees(dto: CollectPositionFeesDTO): Promise<SubmittedTransaction<Position | null>>;
1107
1988
  /**
1108
1989
  * Creates a pool, resolving registered trading symbols.
1109
1990
  * Reversed symbol order inverts the supplied starting price or square-root price.
@@ -1125,17 +2006,20 @@ export declare class Positions {
1125
2006
  * });
1126
2007
  * ```
1127
2008
  */
1128
- createPool(args: {
1129
- token0: TokenRef;
1130
- token1: TokenRef;
1131
- token0Symbol?: string | undefined;
1132
- token1Symbol?: string | undefined;
1133
- fee: FEE_TIER;
1134
- startingPrice?: NumericAmount | undefined;
1135
- startingSqrtPrice?: NumericAmount | undefined;
1136
- isPrivate?: boolean | undefined;
1137
- privateAccess?: string[] | undefined;
1138
- }): Promise<SubmittedTransaction<Position | null>>;
2009
+ createPool(args: CreatePoolArgs): Promise<SubmittedTransaction<Position | null>>;
2010
+ /**
2011
+ * Builds the CreatePool DTO that {@link createPool} would sign, without signing or sending it:
2012
+ * symbols resolved or proposed, the pair put in canonical order and the price inverted when it
2013
+ * was reversed. Submit exactly this DTO with {@link submitCreatePool}. The pure counterpart,
2014
+ * with canonical inputs, is `buildCreatePoolDto`.
2015
+ */
2016
+ buildCreatePool(args: CreatePoolArgs): Promise<CreatePoolDTO>;
2017
+ /**
2018
+ * Signs and submits a DTO built by {@link buildCreatePool} or `buildCreatePoolDto`; it must be
2019
+ * exactly what the builder produces. The returned transaction confirms by the pool existing, and
2020
+ * the cached symbol registry is dropped, since the pool may have registered new symbols.
2021
+ */
2022
+ submitCreatePool(dto: CreatePoolDTO): Promise<SubmittedTransaction<Position | null>>;
1139
2023
  private submit;
1140
2024
  /**
1141
2025
  * Builds a confirmation closure that proves the write's own effect, not just that a
@@ -1153,32 +2037,35 @@ export declare class Positions {
1153
2037
  private get;
1154
2038
  private getNullable;
1155
2039
  private isNotFound;
1156
- private mapPosition;
1157
- private requestToken;
1158
2040
  private canonicalTicks;
1159
2041
  private tickSpacing;
1160
2042
  private rejectNumber;
1161
- private uniqueKey;
2043
+ /** The caller's `uniqueKey` (validated), else a fresh one. */
2044
+ private uniqueKeyFor;
1162
2045
  private resolveCreateToken;
1163
2046
  private tryParseClassKey;
1164
2047
  }
1165
2048
  //#endregion
1166
2049
  //#region src/classes/quoting.d.ts
1167
- type QuoteSymbols = Pick<Symbols, 'resolve'>;
2050
+ /** The transport a quote service reads through: the same shape `Pools` and `Symbols` take. */
2051
+ type QuoteGateway = Pick<ChainGateway, 'httpRequestor' | 'dexBackendBaseUrl'> & {
2052
+ requestTimeoutMs?: number | undefined;
2053
+ wire?: WireOptions | undefined;
2054
+ };
1168
2055
  /** Read-only quote service backed by the v2 offline quote engine. */
1169
2056
  export declare class Quoting {
1170
- private readonly dexBackendBaseUrl;
1171
- private readonly http;
2057
+ private readonly gateway;
1172
2058
  private readonly symbols;
1173
2059
  /**
1174
2060
  * Creates a quote service.
1175
2061
  *
1176
2062
  * @example
1177
2063
  * ```ts
1178
- * const quoting = new Quoting('https://swap-backend.stage.defi.ovh.gala.com', http, symbols);
2064
+ * const quoting = new Quoting(gateway, symbols); // a ChainGateway, or any { dexBackendBaseUrl, httpRequestor }
1179
2065
  * ```
1180
2066
  */
1181
- constructor(dexBackendBaseUrl: string, http: HttpClient, symbols: QuoteSymbols);
2067
+ constructor(gateway: QuoteGateway, symbols: TokenResolver);
2068
+ private readonly http;
1182
2069
  /**
1183
2070
  * Quotes the output for a positive exact-input amount.
1184
2071
  *
@@ -1203,24 +2090,51 @@ export declare class Quoting {
1203
2090
  }
1204
2091
  //#endregion
1205
2092
  //#region src/classes/swaps.d.ts
1206
- export type SwapAmount = {
1207
- exactIn: NumericAmount;
1208
- exactOut?: undefined;
1209
- amountOutMinimum?: NumericAmount | undefined;
1210
- amountInMaximum?: undefined;
1211
- } | {
1212
- exactIn?: undefined;
1213
- exactOut: NumericAmount;
1214
- amountOutMinimum?: undefined;
1215
- amountInMaximum?: NumericAmount | undefined;
1216
- };
1217
2093
  interface SwapGateway {
1218
2094
  submit: (method: 'RequestTrade', signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<SubmittedTransaction<AppliedTrade>>;
2095
+ submitShadow: (method: 'RequestTrade', signedBody: Record<string, unknown>, options?: ChainSubmitOptions) => Promise<ShadowSubmitResult>;
1219
2096
  readonly dexBackendBaseUrl: string;
1220
2097
  readonly httpRequestor: HttpRequestor;
1221
2098
  readonly requestTimeoutMs: number;
1222
2099
  }
1223
- type SwapSymbols = Pick<Symbols, 'resolve'>;
2100
+ /** The canonical pool a swap trades in, as a quote names it. */
2101
+ export interface SwapPool {
2102
+ token0: string;
2103
+ token1: string;
2104
+ }
2105
+ /** Options of a swap. */
2106
+ export interface SwapOptions {
2107
+ /**
2108
+ * The attempt's `uniqueKey` (1-128 characters of `A-Za-z0-9._:-`). Default: a fresh
2109
+ * `<uniqueKeyPrefix><uuid>`. Supply one to know the key before signing (to remember it, to
2110
+ * show it), or to retry the SAME attempt after a lost response; never reuse it for another trade.
2111
+ */
2112
+ uniqueKey?: string | undefined;
2113
+ /**
2114
+ * Pin the pool: take `token0` / `token1` verbatim from the quote the user saw, instead of
2115
+ * ordering `tokenIn` / `tokenOut` by string comparison. `tokenIn` and `tokenOut` must be exactly
2116
+ * these two symbols, and `token0` must sort before `token1`. See {@link swapRouteFromQuote}.
2117
+ */
2118
+ pool?: SwapPool | undefined;
2119
+ }
2120
+ /** Everything {@link Swaps.swap} needs to trade in the pool a quote priced. */
2121
+ export interface SwapRoute {
2122
+ tokenIn: string;
2123
+ tokenOut: string;
2124
+ fee: FEE_TIER;
2125
+ pool: SwapPool;
2126
+ }
2127
+ /**
2128
+ * The route of a quote: its fee tier and pool, with `tokenIn` / `tokenOut` taken from
2129
+ * `tokenInIsToken0`, nothing re-derived. Use it to swap in exactly the pool a quote priced:
2130
+ *
2131
+ * @example
2132
+ * ```ts
2133
+ * const route = swapRouteFromQuote(quote);
2134
+ * await swaps.swap(route.tokenIn, route.tokenOut, route.fee, { exactIn: '100' }, { pool: route.pool });
2135
+ * ```
2136
+ */
2137
+ export declare function swapRouteFromQuote(quote: Pick<QuoteResult, 'token0Symbol' | 'token1Symbol' | 'tokenInIsToken0' | 'fee'>): SwapRoute;
1224
2138
  /** Executes queued current-contract RequestTrade operations through the Chain Gateway. */
1225
2139
  export declare class Swaps {
1226
2140
  private readonly gateway;
@@ -1235,7 +2149,8 @@ export declare class Swaps {
1235
2149
  * const swaps = new Swaps(gateway, symbols, signer, 'client|alice');
1236
2150
  * ```
1237
2151
  */
1238
- constructor(gateway: SwapGateway, symbols: SwapSymbols, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined);
2152
+ constructor(gateway: SwapGateway, symbols: TokenResolver, signer?: GalaChainSigner | undefined, walletAddress?: string | undefined, options?: UniqueKeyOptions);
2153
+ private readonly uniqueKeyPrefix;
1239
2154
  /**
1240
2155
  * Signs and submits an exact-input or exact-output RequestTrade DTO. The returned transaction
1241
2156
  * is QUEUED; call `await tx.confirm()` to obtain the executed trade or chain rejection.
@@ -1248,7 +2163,54 @@ export declare class Swaps {
1248
2163
  * });
1249
2164
  * ```
1250
2165
  */
1251
- swap(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount): Promise<SubmittedTransaction<AppliedTrade>>;
2166
+ swap(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount, options?: SwapOptions): Promise<SubmittedTransaction<AppliedTrade>>;
2167
+ /**
2168
+ * Signs and submits a SHADOW (dark) swap: the same RequestTrade as {@link swap}, relayed with
2169
+ * `X-Shadow: true` so defi-backend marks it private before it reaches the contract. Requires a
2170
+ * `walletAddress`. Resolves the normalized outcome instead of throwing on a gateway refusal:
2171
+ * `ok: false` carries `unavailable` (retryable), `disabled`, `rejected` (with the gateway's
2172
+ * message) or `unknown`. A success carries `queued`, to be confirmed with
2173
+ * `confirmSwap(queued.uniqueKey)`; never fall back to a public swap on failure.
2174
+ *
2175
+ * @example
2176
+ * ```ts
2177
+ * const outcome = await swaps.swapShadow('GALA', 'GUSDC', 3000, { exactIn: '100' });
2178
+ * if (outcome.ok && outcome.queued) await swaps.confirmSwap(outcome.queued.uniqueKey);
2179
+ * ```
2180
+ */
2181
+ swapShadow(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount, options?: SwapOptions): Promise<ShadowSubmitOutcome>;
2182
+ /**
2183
+ * Builds the RequestTrade DTO that {@link swap} would sign, without signing or sending it: to
2184
+ * show in an approval popup, to remember its `uniqueKey`, or to sign elsewhere. Submit exactly
2185
+ * this DTO with {@link submitSwap}. The pure counterpart, with canonical inputs and no
2186
+ * resolution, is `buildRequestTradeDto`.
2187
+ *
2188
+ * @example
2189
+ * ```ts
2190
+ * const dto = await swaps.buildSwap('GALA', 'GUSDC', 3000, { exactIn: '100' });
2191
+ * showApproval(dto);
2192
+ * const submitted = await swaps.submitSwap(dto);
2193
+ * ```
2194
+ */
2195
+ buildSwap(tokenIn: TokenRef, tokenOut: TokenRef, fee: FEE_TIER, amount: SwapAmount, options?: SwapOptions): Promise<RequestTradeDTO>;
2196
+ /**
2197
+ * Signs and submits a DTO built by {@link buildSwap} or `buildRequestTradeDto`. The DTO must be
2198
+ * exactly what the builder produces (no signature, canonical decimals, builder key order), so
2199
+ * what an app showed is what gets signed.
2200
+ *
2201
+ * @example
2202
+ * ```ts
2203
+ * const submitted = await swaps.submitSwap(dto);
2204
+ * const applied = await submitted.confirm();
2205
+ * ```
2206
+ */
2207
+ submitSwap(dto: RequestTradeDTO): Promise<SubmittedTransaction<AppliedTrade>>;
2208
+ /** Signs and shadow-submits a DTO built by {@link buildSwap}; see {@link swapShadow}. */
2209
+ submitSwapShadow(dto: RequestTradeDTO): Promise<ShadowSubmitOutcome>;
2210
+ private submitOptions;
2211
+ private signRequestTrade;
2212
+ /** The pool's two symbols in contract order: the quote's own when pinned, else string order. */
2213
+ private orientPool;
1252
2214
  /**
1253
2215
  * Confirm a swap by its durable `uniqueKey` without resubmitting it. This is the recovery
1254
2216
  * path after a `CONFIRMATION_TIMEOUT`, a `SUBMISSION_OUTCOME_UNKNOWN`, a `409` replay
@@ -1259,11 +2221,10 @@ export declare class Swaps {
1259
2221
  *
1260
2222
  * @example
1261
2223
  * ```ts
1262
- * const applied = await swaps.confirmSwap('gswap-sdk-2f1c…');
2224
+ * const applied = await swaps.confirmSwap('galaswap-operation-2f1c…');
1263
2225
  * ```
1264
2226
  */
1265
2227
  confirmSwap(uniqueKey: string, options?: ConfirmOptions): Promise<AppliedTrade>;
1266
- private buildRequestTradeDto;
1267
2228
  }
1268
2229
  //#endregion
1269
2230
  //#region src/types/env.d.ts
@@ -1286,11 +2247,37 @@ export interface GSwapOptions {
1286
2247
  env?: GSwapEnv | undefined;
1287
2248
  dexBackendBaseUrl?: string | undefined;
1288
2249
  httpRequestor?: HttpRequestor | undefined;
2250
+ /** Request timeout in milliseconds (default 30 000); `Infinity` arms no timer. */
1289
2251
  chainCallTimeoutMs?: number | undefined;
2252
+ /** Query encoding and `User-Agent` of the read requests (see {@link WireOptions}). */
2253
+ wire?: WireOptions | undefined;
2254
+ /**
2255
+ * How tokens are turned into trading symbols. `'registry'` (default) reads the symbol registry
2256
+ * once (`GET /v2/trade/symbols`, cached) and accepts symbols or class keys. `'canonical'` makes
2257
+ * no registry request: the caller passes the backend's canonical trading symbols (from a quote,
2258
+ * an estimate or a position), reads send tokens and ticks exactly as given (composite keys
2259
+ * included) and the backend orients the pair; see {@link CanonicalSymbols}.
2260
+ */
2261
+ symbolResolution?: 'registry' | 'canonical' | undefined;
2262
+ /**
2263
+ * Told about every row of a pool, symbol or position list that was skipped as unusable (see
2264
+ * {@link InvalidEntryHandler}); without it such rows are skipped silently.
2265
+ */
2266
+ onInvalidEntry?: InvalidEntryHandler | undefined;
1290
2267
  /** Realtime stream endpoint. Defaults to the environment's, or is derived from `dexBackendBaseUrl`. */
1291
2268
  dexBackendWsUrl?: string | undefined;
1292
2269
  /** WebSocket constructor for the realtime stream; required on Node.js older than 22. */
1293
2270
  webSocketImpl?: unknown;
2271
+ /**
2272
+ * `x-api-key` for the privileged stream view; server-side only, and it requires `webSocketImpl`
2273
+ * (see `GdexStreamConfig.apiKey`).
2274
+ */
2275
+ streamApiKey?: string | undefined;
2276
+ /**
2277
+ * Prefix of every write's `uniqueKey` (`<prefix><uuid>`). Defaults to `galaswap-operation-`,
2278
+ * what frontend_v2 and wallet_extension send; defi-backend does not depend on it.
2279
+ */
2280
+ uniqueKeyPrefix?: string | undefined;
1294
2281
  }
1295
2282
  /** Main entry point for the current GalaChainDex SDK. */
1296
2283
  export declare class GSwap {
@@ -1305,8 +2292,11 @@ export declare class GSwap {
1305
2292
  readonly positions: Positions;
1306
2293
  readonly swaps: Swaps;
1307
2294
  readonly assets: Assets;
2295
+ /** Network-fee quotes (DryRun) signed with this client's signer. */
2296
+ readonly fees: DexFees;
1308
2297
  readonly dexBackendWsUrl: string;
1309
2298
  private readonly webSocketImpl;
2299
+ private readonly streamApiKey;
1310
2300
  private streamClient;
1311
2301
  /**
1312
2302
  * Create an SDK client for prod or stage.
@@ -1332,141 +2322,465 @@ export declare class GSwap {
1332
2322
  get stream(): GdexStreamService;
1333
2323
  }
1334
2324
  //#endregion
1335
- //#region src/classes/gswap_sdk_error.d.ts
1336
- /** Error raised by the SDK for validation, gateway, chain, or transaction failures. */
1337
- export declare class GSwapSDKError extends Error {
1338
- readonly code: string;
1339
- readonly details?: Record<string, unknown> | undefined;
1340
- readonly chainMessage: string | undefined;
1341
- readonly retryAfterMs: number | undefined;
1342
- constructor(message: string, code: string, details?: Record<string, unknown> | undefined, chainMessage?: string, retryAfterMs?: number);
1343
- /** Create the standard missing-signer error. */
1344
- static noSignerError(): GSwapSDKError;
1345
- /** Create the error used when confirming a position write without a configured wallet address. */
1346
- static noWalletAddressError(): GSwapSDKError;
1347
- /** Create the error used when no pool can quote the requested pair. */
1348
- static noPoolAvailableError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number): GSwapSDKError;
1349
- /** Create the error used when a pool lacks liquidity for a quote. */
1350
- static insufficientLiquidityError(tokenIn: GalaChainTokenClassKey | string, tokenOut: GalaChainTokenClassKey | string, fee?: number): GSwapSDKError;
1351
- /** Convert a chain-gateway bounce into a typed SDK error. */
1352
- static fromGatewayBounce(code: string, message: string, status: number, retryAfterMs?: number): GSwapSDKError;
1353
- /** Convert a GalaChain `Status: 0` response into a typed SDK error. */
1354
- static fromChainError(errorKey: string, message: string, details?: Record<string, unknown>): GSwapSDKError;
1355
- /** Create the error used when a token is not registered by the current DEX contract. */
1356
- static unknownTokenError(token: GalaChainTokenClassKey | string): GSwapSDKError;
1357
- /** Create the error used when apply-results confirmation does not arrive in time. */
1358
- static confirmationTimeoutError(uniqueKey: string, cause?: unknown): GSwapSDKError;
1359
- /** Convert an unexpected HTTP response into an SDK error. */
1360
- static fromErrorResponse(url: string, response: HTTPResponse): Promise<GSwapSDKError>;
2325
+ //#region src/classes/pending_swaps.d.ts
2326
+ /** Key the wallet_extension has always used; its storage value is a plain array of entries. */
2327
+ export declare const PENDING_SWAPS_STORAGE_KEY = "pendingSwaps.v1";
2328
+ /** Entries older than this are dropped the next time a wallet's swaps are listed. */
2329
+ export declare const PENDING_SWAP_EXPIRY_MS: number;
2330
+ /**
2331
+ * Async key/value storage the pending-swap store persists through. It stores STRUCTURED VALUES
2332
+ * (the store never serializes), so each platform decides how a value lands on disk:
2333
+ *
2334
+ * - `chrome.storage.local`: `get: async (k) => (await chrome.storage.local.get(k))[k]`,
2335
+ * `set: (k, v) => chrome.storage.local.set({ [k]: v })`. This is the wallet's stored shape.
2336
+ * - `localStorage` (frontend_v2): `get: async (k) => { const raw = localStorage.getItem(k);
2337
+ * if (raw === null) return undefined; try { return JSON.parse(raw); } catch { return raw; } }`,
2338
+ * `set: async (k, v) => localStorage.setItem(k, JSON.stringify(v))`. Corrupt JSON MUST come back
2339
+ * as a value (here the raw string), not as a rejection: a value that is not an array reads as
2340
+ * "no entries" and the next write repairs it, whereas a `get` that rejects forever makes every
2341
+ * `remember` a no-op.
2342
+ * - React Native: AsyncStorage with the same JSON wrapping and the same corrupt-JSON rule.
2343
+ *
2344
+ * `get` resolves `undefined` for a missing key. Either method may reject; the store treats that
2345
+ * as "storage unavailable" and never lets it surface (see {@link PendingSwapStore}).
2346
+ */
2347
+ export interface StorageAdapter {
2348
+ get(key: string): Promise<unknown>;
2349
+ set(key: string, value: unknown): Promise<void>;
2350
+ }
2351
+ /** A RequestTrade that was accepted by the gateway but whose outcome has not been read yet. */
2352
+ export interface PendingSwap {
2353
+ uniqueKey: string;
2354
+ requestTransactionId: string | null;
2355
+ /** The wallet (account) that submitted the swap; `list` filters by it. */
2356
+ wallet: string;
2357
+ token0Symbol: string;
2358
+ token1Symbol: string;
2359
+ /** Whether the swap was a shadow ("dark") swap. */
2360
+ isDarkSwap: boolean;
2361
+ /** Epoch milliseconds when the swap was queued. */
2362
+ createdAt: number;
2363
+ }
2364
+ /** Options for {@link PendingSwapStore}. */
2365
+ export interface PendingSwapStoreOptions {
2366
+ /** Storage key. Default {@link PENDING_SWAPS_STORAGE_KEY}. */
2367
+ storageKey?: string | undefined;
2368
+ /**
2369
+ * The stored name of the dark-swap flag. `isDarkSwap` (default) is wallet_extension's shape;
2370
+ * `shadow` is frontend_v2's. Entries are always exposed to callers as `isDarkSwap`.
2371
+ */
2372
+ darkFlagField?: 'isDarkSwap' | 'shadow' | undefined;
2373
+ /**
2374
+ * Where `remember` puts a new entry in the stored array: `end` (default, wallet_extension) or
2375
+ * `start` (frontend_v2).
2376
+ */
2377
+ insertAt?: 'end' | 'start' | undefined;
2378
+ /**
2379
+ * The order of `list`: `stored` (default, wallet_extension: oldest first for `insertAt: 'end'`)
2380
+ * or `newest-first` (frontend_v2).
2381
+ */
2382
+ listOrder?: 'stored' | 'newest-first' | undefined;
2383
+ /** Clock, in epoch milliseconds. Defaults to `Date.now`. */
2384
+ now?: (() => number) | undefined;
2385
+ }
2386
+ /**
2387
+ * Remembers queued swaps so their outcome can be confirmed after the UI, popup or service worker
2388
+ * that submitted them is gone (`confirmAppliedTrade` with the stored `uniqueKey`).
2389
+ *
2390
+ * Guarantees:
2391
+ * - Persistence is best effort and NEVER throws: a failing or missing storage must not turn an
2392
+ * accepted request into a client-side resubmission. `list` resolves `[]` when storage fails.
2393
+ * - Operations of one store instance are serialized, so concurrent `remember` / `forget` calls
2394
+ * cannot lose each other's write (read-modify-write over an async adapter). Two store instances
2395
+ * over the same storage (for example popup and service worker) are not coordinated.
2396
+ * - Entries that do not match the expected shape are ignored and dropped on the next write.
2397
+ * - Entries expire after seven days (an entry exactly seven days old is expired; frontend_v2
2398
+ * kept it for that one millisecond); `list` removes them from storage, which frontend_v2 never
2399
+ * did on read.
2400
+ * - New entries go to the end (or `insertAt: 'start'`); `list` returns the wallet's entries in
2401
+ * stored order (or `listOrder: 'newest-first'`).
2402
+ * - The stored shape is wallet_extension's by default; `storageKey`, `darkFlagField`, `insertAt`
2403
+ * and `listOrder` reproduce frontend_v2's. JSON key order inside an entry is not preserved.
2404
+ *
2405
+ * Passing no `storage` yields a store that remembers nothing.
2406
+ *
2407
+ * @example
2408
+ * ```ts
2409
+ * const store = new PendingSwapStore({
2410
+ * get: async (key) => (await chrome.storage.local.get(key))[key],
2411
+ * set: (key, value) => chrome.storage.local.set({ [key]: value }),
2412
+ * });
2413
+ * await store.remember({ uniqueKey, requestTransactionId, wallet, token0Symbol: 'GALA',
2414
+ * token1Symbol: 'GUSDC', isDarkSwap: false, createdAt: Date.now() });
2415
+ * for (const swap of await store.list(wallet)) await confirmAppliedTrade(client, swap);
2416
+ * ```
2417
+ */
2418
+ export declare class PendingSwapStore {
2419
+ private readonly storage;
2420
+ private readonly storageKey;
2421
+ private readonly darkFlagField;
2422
+ private readonly insertAt;
2423
+ private readonly listOrder;
2424
+ private readonly now;
2425
+ private queue;
2426
+ constructor(storage: StorageAdapter | undefined, options?: PendingSwapStoreOptions);
2427
+ /** Saves (or replaces, by `uniqueKey`) a pending swap. */
2428
+ remember(swap: PendingSwap): Promise<void>;
2429
+ /** Removes a pending swap once its outcome is known. */
2430
+ forget(uniqueKey: string): Promise<void>;
2431
+ /** The wallet's unexpired pending swaps (see `listOrder`). Expired entries are pruned. */
2432
+ list(wallet: string): Promise<PendingSwap[]>;
2433
+ private enqueue;
2434
+ private read;
2435
+ private readonly toStored;
2436
+ private fromStored;
1361
2437
  }
1362
- /** Narrow an object property without trusting a cast at a network boundary. */
1363
- export declare function getObjectProperty(value: unknown, property: string): Record<string, unknown> | undefined;
1364
- /** Read a string property from an unknown object. */
1365
- export declare function getStringProperty(value: unknown, property: string): string | undefined;
1366
- /** Parse a response body, preserving non-JSON text for error reporting. */
1367
- export declare function parseJson(text: string): unknown;
1368
2438
  //#endregion
1369
- //#region src/types/v2_dtos.d.ts
1370
- /** Common identity fields for v2 pool writes. */
1371
- export interface V2PoolWriteBase {
2439
+ //#region src/utils/signing.d.ts
2440
+ /**
2441
+ * GalaChain's deterministic JSON: object keys sorted (UTF-16 code-unit order) at every depth, no
2442
+ * whitespace, `undefined`/function members dropped, `toJSON()` honored. Byte-identical to
2443
+ * `serialize` from `@gala-chain/api` / `json-stringify-deterministic` for every JSON-shaped
2444
+ * value, which is all a DTO ever is.
2445
+ *
2446
+ * @throws TypeError for circular structures and BigInt values (as `JSON.stringify` does) and
2447
+ * when the value itself has no JSON representation (`undefined`, a function, a symbol).
2448
+ */
2449
+ export declare function serialize(value: unknown): string;
2450
+ /**
2451
+ * The exact string GalaChain hashes for a DTO: the (optional, string) `prefix` field PREPENDED to
2452
+ * the deterministic serialization of the DTO WITHOUT `signature`, `multisig`, `trace` and `prefix`.
2453
+ * Equivalent to `@gala-chain/api` 3.x `getPayloadToSign` for every non-EIP-712 DTO.
2454
+ */
2455
+ export declare function getPayloadToSign(dto: Record<string, unknown>): string;
2456
+ /**
2457
+ * The EIP-191 header for `message`: `"\x19Ethereum Signed Message:\n"` + the message's UTF-8 BYTE
2458
+ * length. This is what a wallet's `personal_sign` prepends, and what the chain recomputes when it
2459
+ * recovers a personal-signed DTO.
2460
+ */
2461
+ export declare function calculatePersonalSignPrefix(message: string): string;
2462
+ /**
2463
+ * The EIP-191 header for `serialize(dto)` (any `prefix` already on the DTO is ignored). This is
2464
+ * deliberately the same string the signers hand a wallet to sign, so the header's length can never
2465
+ * disagree with the signed message. Wallet-neutral: it is the value both a browser wallet's
2466
+ * `personal_sign` and Gala Wallet's `gala_signChainDto` (personal-sign scheme) prepend.
2467
+ */
2468
+ export declare function personalSignPrefixFor(dto: Record<string, unknown>): string;
2469
+ /**
2470
+ * The `@gala-chain/connect`-style prefix frontend_v2 puts in the body of an EIP-712 write: the
2471
+ * EIP-191 header whose number counts the prefix string ITSELF plus the body (the UTF-8 length of
2472
+ * `getPayloadToSign({ ...dto, prefix })`), found by fixpoint because adding the prefix changes the
2473
+ * length (a body of 99 bytes settles on 101).
2474
+ *
2475
+ * It is NOT a personal-sign prefix (a personal-sign write with this value recovers a phantom
2476
+ * signer; use `personalSignPrefixFor`). Under EIP-712 the field is an untyped extra that the
2477
+ * typed-data hash ignores and defi-backend recomputes, so it only exists to keep the submitted
2478
+ * body byte-identical to what frontend_v2 has always sent.
2479
+ */
2480
+ export declare function fixpointPrefixFor(dto: Record<string, unknown>): string;
2481
+ /**
2482
+ * Normalizes a secp256k1 private key to a fresh 32-byte array (the caller may zero it). Also
2483
+ * accepts 32 raw bytes, which are validated and copied. For strings it accepts what `@gala-chain/api`'s
2484
+ * `normalizePrivateKey` accepted for a usable key: 64 hex characters (optionally `0x`-prefixed;
2485
+ * a 63-character hex key is left-padded with a zero) or a 44-character base64 string.
2486
+ *
2487
+ * @throws GSwapSDKError (`VALIDATION_ERROR`) for any other shape or an out-of-range scalar.
2488
+ */
2489
+ export declare function normalizePrivateKey(input: string | Uint8Array): Uint8Array;
2490
+ /**
2491
+ * The lowercase `0x` Ethereum address (last 20 bytes of keccak256 of the uncompressed public key)
2492
+ * of a normalized private key. The Gala `eth|` identity of a key is this address.
2493
+ */
2494
+ export declare function ethAddressOfPrivateKey(privateKey: Uint8Array): string;
2495
+ /**
2496
+ * GalaChain NATIVE signature over an already-serialized DTO: keccak256 of the exact bytes, with no
2497
+ * prefix and no signature envelope. The caller owns serialization, so the bytes shown to a user
2498
+ * and the bytes signed can never diverge.
2499
+ */
2500
+ export declare function signSerializedNative(privateKey: Uint8Array, serializedDto: string): string;
2501
+ /**
2502
+ * GalaChain NATIVE signature for a DTO: keccak256 of `getPayloadToSign(dto)`, signed with
2503
+ * secp256k1. Byte-identical to `signatures.getSignature` from `@gala-chain/api`.
2504
+ */
2505
+ export declare function signNative(privateKey: Uint8Array, dto: Record<string, unknown>): string;
2506
+ /**
2507
+ * Personal-sign hash and signature: keccak256(`prefix` + `message`), both hashed VERBATIM with no
2508
+ * further EIP-191 wrapping. Passing `prefix = calculatePersonalSignPrefix(message)` reproduces a
2509
+ * wallet's `personal_sign` of `message`. Gala Wallet's `gala_signChainDto` (personal-sign
2510
+ * scheme) hashes `prefix` + the exact string it is handed, which can differ from the bare message
2511
+ * (see the `signatureOverPrefixlessBody` vectors); that quirk is why the two inputs stay separate.
2512
+ */
2513
+ export declare function signPersonalMessage(privateKey: Uint8Array, prefix: string, message: string): string;
2514
+ //#endregion
2515
+ //#region src/utils/chain_dto_signing.d.ts
2516
+ /** A secp256k1 private key as a hex/base64 string or as raw 32 bytes. */
2517
+ type PrivateKeyInput = string | Uint8Array;
2518
+ /**
2519
+ * Runs `action` with a private normalized copy of the key, zeroed afterwards (also when `action`
2520
+ * throws). Bytes given by the caller are copied, never modified: the caller owns them.
2521
+ */
2522
+ export declare function withPrivateKey<T>(privateKey: PrivateKeyInput, action: (key: Uint8Array) => T): T;
2523
+ /**
2524
+ * GalaChain NATIVE signature over an already-serialized DTO: keccak256 of the exact bytes with no
2525
+ * prefix and no envelope (wallet `signChainDtoNative`). The caller owns serialization, so the
2526
+ * bytes a user reviewed and the bytes signed cannot diverge.
2527
+ *
2528
+ * @returns 130 lowercase hex characters, `r || s || v` with `v` = `1b`/`1c`, no `0x`.
2529
+ */
2530
+ export declare function signChainDtoNative(privateKey: PrivateKeyInput, serializedDto: string): string;
2531
+ /**
2532
+ * The personal-sign hash primitive (wallet `signChainDtoHash`): keccak256(`prefix` + `message`),
2533
+ * both verbatim, with no further EIP-191 wrap. `message` must be the DTO's serialization WITHOUT
2534
+ * its `prefix` field; callers holding a dApp-supplied string go through `signChainDtoPersonalSign`,
2535
+ * which derives both inputs from it.
2536
+ */
2537
+ export declare function signChainDtoHash(privateKey: PrivateKeyInput, prefix: string, message: string): string;
2538
+ /** What a `gala_signChainDto` personal-sign request hashes. */
2539
+ interface PersonalSignChainDtoPayload {
2540
+ /** The `prefix` the chain prepends: the DTO's own `prefix` field, or `''` when it has none. */
2541
+ prefix: string;
2542
+ /** The exact message hashed after `prefix`. */
2543
+ message: string;
2544
+ }
2545
+ /**
2546
+ * Derives what to hash for a `gala_signChainDto` personal-sign request from the exact string the
2547
+ * dApp sent (and the approval card displayed): wallet `resolvePersonalSignChainDtoPayload`.
2548
+ *
2549
+ * The dApp submits `{ ...dto, prefix, signature }`, which the chain recovers from
2550
+ * `keccak256(prefix + serialize(dto WITHOUT prefix))`. So when the string embeds a `prefix`
2551
+ * field, that field is removed and the remainder re-serialized; the prefix used is the dApp's own
2552
+ * value byte for byte. A string with no `prefix` field is hashed verbatim with an empty prefix
2553
+ * (chain-equivalent to a native signature of that exact string).
2554
+ *
2555
+ * Fails closed (throws `GSwapSDKError` `INVALID_PERSONAL_SIGN_DTO`, message text identical to the
2556
+ * wallet's) on: malformed JSON; JSON that is not a plain object; a `prefix` that is not an EIP-191
2557
+ * "Ethereum Signed Message" header; any signing-envelope field (`signature`, `multisig`, `trace`,
2558
+ * `types`, `domain`, `stringsInstructions`); and a string that is not already the canonical
2559
+ * serialization of what it parses to (duplicate keys, lossy numbers, key-order tricks the card
2560
+ * would render differently). Stripping `prefix` is therefore the ONLY byte change between the
2561
+ * reviewed string and the signed message.
2562
+ */
2563
+ export declare function resolvePersonalSignChainDtoPayload(data: string): PersonalSignChainDtoPayload;
2564
+ /**
2565
+ * Signs a GalaChain personal-sign scheme DTO from the exact string a dApp sent through
2566
+ * `gala_signChainDto` (wallet `signChainDtoPersonalSign`). See
2567
+ * `resolvePersonalSignChainDtoPayload` for what is signed and what is refused; the signature
2568
+ * recovers, under the chain's `getPayloadToSign`, to this key for the DTO the dApp submits with
2569
+ * its `prefix`, and equals a `personal_sign` of the bare body when that prefix is the EIP-191
2570
+ * header of the bare body's byte length.
2571
+ *
2572
+ * @throws GSwapSDKError (`INVALID_PERSONAL_SIGN_DTO`) before any signing when the input is refused.
2573
+ */
2574
+ export declare function signChainDtoPersonalSign(privateKey: PrivateKeyInput, data: string): string;
2575
+ /**
2576
+ * Raw object signing (wallet `signObject`), used for transfers, bridge and fee-dry-run DTOs the
2577
+ * wallet signs itself. Removes ONLY `signature`, signs `keccak256(serialize(rest))` natively
2578
+ * (no `prefix` handling, and `trace` / `multisig` stay in the signed bytes, unlike
2579
+ * `signNative`), and returns `{ signature, ...rest }` with the signature as the FIRST key, exactly
2580
+ * like the wallet. Callers that must not sign extra fields strip them first.
2581
+ */
2582
+ export declare function signRawObject(privateKey: PrivateKeyInput, obj: Record<string, unknown>): {
2583
+ signature: string;
2584
+ } & Record<string, unknown>;
2585
+ /**
2586
+ * Drops the `EIP712Domain` entry from a dApp-supplied types map (a typed-data encoder derives the
2587
+ * domain type itself and rejects an explicit one). The order of the remaining types is preserved.
2588
+ */
2589
+ export declare function stripEip712DomainType<T>(types: Record<string, T>): Record<string, T>;
2590
+ /**
2591
+ * `collection$category$type$additionalKey` for a token-class object (wallet `decodeTokenData`).
2592
+ * Lenient on purpose: any missing or non-string part becomes `''`, so a display layer never
2593
+ * throws on odd input.
2594
+ */
2595
+ export declare function tokenClassDollarKey(token: Record<string, unknown> | null | undefined): string;
2596
+ /**
2597
+ * A quantity in the form GalaChain's `IsBigNumber` validator accepts: FIXED notation, no leading
2598
+ * zeros, no trailing decimal zeros (`BigNumber#toFixed()`; never `toString()`, which turns
2599
+ * `0.00000001` into `1e-8`, and never a JS number in between).
2600
+ *
2601
+ * @throws GSwapSDKError (`VALIDATION_ERROR`) for a value that is not a finite number. The wallet's
2602
+ * `cleanNumber` returned the string `'NaN'` there; signing that text can only fail on chain.
2603
+ */
2604
+ export declare function canonicalDecimalString(value: string | number): string;
2605
+ //#endregion
2606
+ //#region src/utils/eip712.d.ts
2607
+ type EIP712Types = Record<string, Array<{
2608
+ name: string;
2609
+ type: string;
2610
+ }>>;
2611
+ /**
2612
+ * Derives the EIP-712 `types` for a DTO from its runtime shape.
2613
+ *
2614
+ * The generated `types` travel with the signed payload and are what BOTH sides hash, so they
2615
+ * must enumerate EVERY field the chain-side DTO will carry. GalaChain refuses any signature
2616
+ * whose `types` leave a DTO field uncovered (`assertNoUnsignedFields`, the fix for the
2617
+ * 2026-08-18 unsigned-field-injection drain); when that happens signature recovery fails
2618
+ * outright and the chain reports "Missing signerPublicKey or signerAddress field in dto".
2619
+ */
2620
+ export declare function generateEIP712Types(typeName: string, params: Record<string, unknown>): EIP712Types;
2621
+ /** The EIP-712 domain carried by a signed payload: GalaChain only uses `name` and `chainId`. */
2622
+ interface EIP712DomainValue {
2623
+ name: string;
2624
+ chainId: number;
2625
+ }
2626
+ /**
2627
+ * Builds the EIP-712 domain from the wallet's LIVE `eth_chainId` result, exactly like frontend_v2
2628
+ * (DEFI-1895): a wallet hashes whatever domain it is handed, and MetaMask refuses a `chainId` that
2629
+ * differs from its active network, so a hardcoded `1` breaks every wallet that is not on Mainnet.
2630
+ * defi-backend recovers the signer from the `domain` the payload carries (live-proven for chain
2631
+ * ids 1, 56 and 11155111), so following the wallet is correct on every network.
2632
+ *
2633
+ * @param chainId - The raw `eth_chainId` result: a `0x` hex string (the JSON-RPC form) or an integer.
2634
+ * @throws GSwapSDKError (`INVALID_CHAIN_ID`) when the wallet answers with anything else.
2635
+ */
2636
+ export declare function eip712DomainFor(chainId: unknown): EIP712DomainValue;
2637
+ /**
2638
+ * The four v2 operations proven to recover the signer correctly via genuine EIP-712: `RequestTrade`
2639
+ * never had the problem (one numeric field). `AddLiquidity`/`RemoveLiquidity`/
2640
+ * `CollectPositionFees` each need their `types` completed with a handful of fields their real
2641
+ * server-side DTO always carries — see the `complete*Fields` functions below. `CreatePool` is a
2642
+ * genuinely different, unsolved problem (nested `TokenClassKey` structs, not a flat
2643
+ * missing-field gap) and is NOT in this set — callers must keep using `personal-sign` for it.
2644
+ */
2645
+ export declare const EIP712_CAPABLE_METHODS: ReadonlySet<string>;
2646
+ /**
2647
+ * Completes a DTO's fields for EIP-712 signing (a no-op for methods with no known gap, e.g.
2648
+ * `RequestTrade`) and derives its `types`. Exported separately from the signing call itself so tests
2649
+ * can assert on the exact payload without needing a live provider.
2650
+ */
2651
+ export declare function buildEIP712Payload(methodName: string, dto: Record<string, unknown>): {
2652
+ completedDto: Record<string, unknown>;
2653
+ types: EIP712Types;
2654
+ };
2655
+ //#endregion
2656
+ //#region src/utils/typed_data.d.ts
2657
+ /** A typed-data payload as `eth_signTypedData_v4` carries it, minus `primaryType` (it is inferred). */
2658
+ interface TypedDataPayload {
2659
+ domain: Record<string, unknown>;
2660
+ /** Struct definitions WITHOUT `EIP712Domain` (see `stripEip712DomainType`). */
2661
+ types: Record<string, readonly unknown[]>;
2662
+ message: Record<string, unknown>;
2663
+ }
2664
+ /**
2665
+ * The EIP-712 digest `keccak256(0x1901 || domainSeparator || hashStruct(primaryType, message))`
2666
+ * that a wallet signs for `eth_signTypedData_v4`. The primary type is inferred, as ethers does.
2667
+ *
2668
+ * @throws GSwapSDKError (`INVALID_TYPED_DATA`) for any type graph or value it cannot encode
2669
+ * exactly (see the module note on strictness).
2670
+ */
2671
+ export declare function hashTypedData(payload: TypedDataPayload): Uint8Array;
2672
+ /**
2673
+ * Signs a dApp's EIP-712 typed-data approval (the wallet's `signTypedMessage` path), replacing
2674
+ * `new ethers.Wallet(key).signTypedData(domain, types, message)`. `types` must already have
2675
+ * `EIP712Domain` removed (`stripEip712DomainType`).
2676
+ *
2677
+ * @returns `0x` + r + s + v with `v` = `0x1b`/`0x1c` (27/28): ethers' serialized signature form,
2678
+ * recoverable with `verifyTypedData` / `eth_signTypedData_v4` verifiers. Rejects (never throws
2679
+ * synchronously) on invalid input.
2680
+ */
2681
+ export declare function signTypedDataPayload(privateKey: PrivateKeyInput, payload: TypedDataPayload): Promise<string>;
2682
+ //#endregion
2683
+ //#region src/utils/dto_builders.d.ts
2684
+ /** The pool a RequestTrade trades in, its fee tier, the `uniqueKey` and what is traded. */
2685
+ type RequestTradeInput = {
2686
+ /** Canonical pool symbols: `token0 < token1`. Take them from a quote verbatim. */
1372
2687
  token0: string;
1373
2688
  token1: string;
1374
- fee: FEE_TIER;
2689
+ fee: number;
2690
+ /** Which side of the pool is sold: `true` when the input token is `token0`. */
2691
+ tokenInIsToken0: boolean;
1375
2692
  uniqueKey: string;
1376
- }
1377
- /** A v2 RequestTrade with exactly one selected trade-side quantity. */
1378
- export type RequestTradeDTO = V2PoolWriteBase & ({
1379
- sell0Qty: string;
1380
- sell1Qty?: never;
1381
- buy0Qty?: never;
1382
- buy1Qty?: never;
1383
- } | {
1384
- sell0Qty?: never;
1385
- sell1Qty: string;
1386
- buy0Qty?: never;
1387
- buy1Qty?: never;
1388
- } | {
1389
- sell0Qty?: never;
1390
- sell1Qty?: never;
1391
- buy0Qty: string;
1392
- buy1Qty?: never;
1393
- } | {
1394
- sell0Qty?: never;
1395
- sell1Qty?: never;
1396
- buy0Qty?: never;
1397
- buy1Qty: string;
1398
- }) & {
1399
- amountOutMinimum?: string | undefined;
1400
- amountInMaximum?: string | undefined;
1401
- };
1402
- /** A v2 liquidity deposit with exactly one selected deposit quantity. */
1403
- export type AddLiquidityDTO = V2PoolWriteBase & {
1404
- tickLower: number;
1405
- tickUpper: number;
1406
- } & ({
1407
- depositQuantityToken0: string;
1408
- depositQuantityToken1?: never;
1409
- } | {
1410
- depositQuantityToken0?: never;
1411
- depositQuantityToken1: string;
1412
- });
1413
- /** A v2 liquidity withdrawal; omitting both quantities closes the position. */
1414
- export type RemoveLiquidityDTO = V2PoolWriteBase & {
2693
+ } & SwapAmount;
2694
+ /**
2695
+ * Builds the RequestTrade DTO: `exactIn` sells that much of the input token (`sell0Qty` or
2696
+ * `sell1Qty`), `exactOut` buys that much of the output token (`buy1Qty` or `buy0Qty`), plus the
2697
+ * side's slippage bound and an optional `priceLimit`. Key order: `token0, token1, fee, uniqueKey,
2698
+ * <quantity>, amountOutMinimum | amountInMaximum, priceLimit`.
2699
+ *
2700
+ * @example
2701
+ * ```ts
2702
+ * const dto = buildRequestTradeDto({
2703
+ * token0: quote.token0Symbol, token1: quote.token1Symbol,
2704
+ * tokenInIsToken0: quote.tokenInIsToken0, fee: quote.fee,
2705
+ * uniqueKey: createUniqueKey('galaswap-operation-'),
2706
+ * exactIn: '100', amountOutMinimum: '14',
2707
+ * });
2708
+ * ```
2709
+ */
2710
+ export declare function buildRequestTradeDto(input: RequestTradeInput): RequestTradeDTO;
2711
+ /** A canonical pool position: the pair, fee tier, tick range and the attempt's `uniqueKey`. */
2712
+ interface PoolPositionInput {
2713
+ token0: string;
2714
+ token1: string;
2715
+ fee: number;
1415
2716
  tickLower: number;
1416
2717
  tickUpper: number;
1417
- } & ({
1418
- withdrawalQuantityToken0: string;
1419
- withdrawalQuantityToken1?: never;
1420
- } | {
1421
- withdrawalQuantityToken0?: never;
1422
- withdrawalQuantityToken1: string;
2718
+ uniqueKey: string;
2719
+ }
2720
+ /** Exactly one canonical deposit side. */
2721
+ type AddLiquidityInput = PoolPositionInput & ({
2722
+ depositQuantityToken0: NumericAmount;
2723
+ depositQuantityToken1?: undefined;
1423
2724
  } | {
1424
- withdrawalQuantityToken0?: never;
1425
- withdrawalQuantityToken1?: never;
2725
+ depositQuantityToken0?: undefined;
2726
+ depositQuantityToken1: NumericAmount;
1426
2727
  });
1427
- /** A v2 request to sweep all fees from one position. */
1428
- export interface CollectPositionFeesDTO extends V2PoolWriteBase {
1429
- tickLower: number;
1430
- tickUpper: number;
1431
- }
1432
- /** A v2 pool creation request with exactly one initial-price representation. */
1433
- export type CreatePoolDTO = {
2728
+ /**
2729
+ * Builds the AddLiquidity DTO: exactly one of `depositQuantityToken0` / `depositQuantityToken1`
2730
+ * (the other side is derived on chain). Key order: `token0, token1, fee, tickLower, tickUpper,
2731
+ * uniqueKey, <deposit>`.
2732
+ */
2733
+ export declare function buildAddLiquidityDto(input: AddLiquidityInput): AddLiquidityDTO;
2734
+ /** At most one canonical withdrawal side; neither closes the position. */
2735
+ type RemoveLiquidityInput = PoolPositionInput & {
2736
+ withdrawalQuantityToken0?: NumericAmount | undefined;
2737
+ withdrawalQuantityToken1?: NumericAmount | undefined;
2738
+ };
2739
+ /**
2740
+ * Builds the RemoveLiquidity DTO: at most one of `withdrawalQuantityToken0` /
2741
+ * `withdrawalQuantityToken1`; omitting both closes the position and sweeps its fees.
2742
+ */
2743
+ export declare function buildRemoveLiquidityDto(input: RemoveLiquidityInput): RemoveLiquidityDTO;
2744
+ /** Builds the CollectPositionFees DTO (the contract sweeps all of a position's fees). */
2745
+ export declare function buildCollectPositionFeesDto(input: PoolPositionInput): CollectPositionFeesDTO;
2746
+ /** A CreatePool in canonical orientation, with exactly one starting price. */
2747
+ type CreatePoolInput = {
1434
2748
  token0Key: GalaChainTokenClassKey;
1435
2749
  token1Key: GalaChainTokenClassKey;
2750
+ /** The symbols to register; `token0Symbol < token1Symbol` and both proposable. */
1436
2751
  token0Symbol: string;
1437
2752
  token1Symbol: string;
1438
- fee: FEE_TIER;
2753
+ fee: number;
2754
+ /** Optional display name; omitted when undefined or empty. */
2755
+ name?: string | undefined;
1439
2756
  isPrivate?: boolean | undefined;
1440
2757
  privateAccess?: string[] | undefined;
1441
2758
  uniqueKey: string;
1442
2759
  } & ({
1443
- startingPrice: string;
1444
- startingSqrtPrice?: never;
2760
+ startingPrice: NumericAmount;
2761
+ startingSqrtPrice?: undefined;
1445
2762
  } | {
1446
- startingPrice?: never;
1447
- startingSqrtPrice: string;
2763
+ startingPrice?: undefined;
2764
+ startingSqrtPrice: NumericAmount;
1448
2765
  });
1449
- /** Optional page cursor accepted by chain read methods. */
1450
- export interface PageDTO {
1451
- limit?: number | undefined;
1452
- bookmark?: string | undefined;
1453
- }
1454
- /** Fetch all registered trading symbols. */
1455
- export type FetchTokenTradingSymbolsDTO = PageDTO;
1456
- /** Fetch a composite pool snapshot. */
1457
- export interface FetchCompositePoolDataDTO {
1458
- token0: string;
1459
- token1: string;
1460
- fee: FEE_TIER;
1461
- }
1462
- /** Fetch one current trading price, or all prices when no pair is supplied. */
1463
- export type FetchCurrentTradingPricesDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
1464
- /** Fetch pools, optionally narrowed to one pair and paged. */
1465
- export type FetchPoolsDTO = Partial<FetchCompositePoolDataDTO> & PageDTO;
1466
- /** Fetch all liquidity positions, optionally narrowed to a pool reference. */
1467
- export interface FetchLiquidityPositionsDTO extends PageDTO {
1468
- pool?: string | undefined;
1469
- }
2766
+ /**
2767
+ * Builds the CreatePool DTO. Key order: `token0Key, token1Key, fee, startingPrice |
2768
+ * startingSqrtPrice, token0Symbol, token1Symbol, uniqueKey, name, isPrivate, privateAccess`.
2769
+ * Prices are those of the canonical pair (token1 per token0); a price quoted the other way round
2770
+ * is inverted by the caller before it gets here.
2771
+ */
2772
+ export declare function buildCreatePoolDto(input: CreatePoolInput): CreatePoolDTO;
2773
+ /** The methods whose DTOs the builders produce. */
2774
+ type V2WriteMethod = 'RequestTrade' | 'AddLiquidity' | 'RemoveLiquidity' | 'CollectPositionFees' | 'CreatePool';
2775
+ /**
2776
+ * Asserts that `dto` is EXACTLY what the builder of `method` produces for its own fields — the
2777
+ * same fields, canonical decimal text, builder key order, nothing extra (no `signature`). The
2778
+ * `submit*` methods use it so that what an app showed a user (a DTO it built) is byte for byte
2779
+ * what gets signed; a DTO edited by hand, or built elsewhere, is refused rather than signed.
2780
+ *
2781
+ * @throws GSwapSDKError VALIDATION_ERROR (`details.type` = `INVALID_DTO` or `DTO_NOT_CANONICAL`).
2782
+ */
2783
+ export declare function assertCanonicalV2Dto(method: V2WriteMethod, dto: Record<string, unknown>): void;
1470
2784
  //#endregion
1471
2785
  //#region src/utils/ticks.d.ts
1472
2786
  /** Minimum tick supported by GalaChainDex. */
@@ -1485,6 +2799,32 @@ export declare function alignTickDown(tick: number, spacing: number): number;
1485
2799
  export declare function alignTickUp(tick: number, spacing: number): number;
1486
2800
  /** Validate a position range against the global tick bounds and fee-tier spacing. */
1487
2801
  export declare function assertTickRange(lower: number, upper: number, fee: FEE_TIER): void;
2802
+ /** A pool's current price in the frame of the request that asked for it. */
2803
+ export interface FramedSlot0 {
2804
+ /** The square-root price, token1 per token0 in the REQUESTED order. */
2805
+ sqrtPrice: string;
2806
+ /** The greatest tick whose square-root price is no greater than `sqrtPrice`. */
2807
+ tick: number;
2808
+ }
2809
+ /**
2810
+ * Puts a `slot0` answer into the frame of the request. The backend always answers in the pool's
2811
+ * canonical order and says so with `flippedFromRequest`; when the caller asked for the reverse
2812
+ * order the price is inverted here (at 60 significant digits, so a very large or very small
2813
+ * reciprocal keeps its precision) and the tick is re-derived from the inverted price with the
2814
+ * contract's greatest-tick rule. Negating the tick instead is wrong for a price between ticks
2815
+ * (and `-t - 1` is wrong for a price exactly on a tick: sqrtPrice 1 / tick 0 stays 1 / 0).
2816
+ *
2817
+ * @example
2818
+ * ```ts
2819
+ * const slot0 = await gSwap.pools.getSlot0('A', 'B', 500);
2820
+ * const { sqrtPrice, tick } = frameSlot0(slot0);
2821
+ * ```
2822
+ */
2823
+ export declare function frameSlot0(slot0: {
2824
+ sqrtPrice: string;
2825
+ tick: number;
2826
+ flippedFromRequest?: boolean | undefined;
2827
+ }): FramedSlot0;
1488
2828
  //#endregion
1489
2829
  //#region src/utils/validation.d.ts
1490
2830
  export declare function validateNumericAmount(amount: NumericAmount, parameterName: string, allowZero?: boolean): void;
@@ -1494,5 +2834,20 @@ export declare function validateTickRange(tickLower: number, tickUpper: number):
1494
2834
  export declare function validateFee(fee: number): asserts fee is FEE_TIER;
1495
2835
  export declare function validateTickSpacing(tickSpacing: number): void;
1496
2836
  export declare function validateWalletAddress(address?: string): asserts address is string;
2837
+ /**
2838
+ * True when `symbol` is acceptable to propose into the trading-symbol registry: ASCII letters and
2839
+ * digits only, 1 to 32 characters, and not a reserved word (`Token`, `Unit`, `none`) — the rules
2840
+ * the chain gateway enforces on a CreatePool symbol.
2841
+ */
2842
+ export declare function isProposableTradingSymbol(symbol: string): boolean;
2843
+ /**
2844
+ * Asserts that a pair is in the contract's canonical order (`token0 < token1` by plain string
2845
+ * comparison), which every write DTO requires. A pair a caller took from a stale quote or
2846
+ * position can be reversed; signing it would sign something other than what was priced.
2847
+ *
2848
+ * @throws GSwapSDKError VALIDATION_ERROR (`details.type` = `NON_CANONICAL_PAIR`) otherwise.
2849
+ */
2850
+ export declare function assertCanonicalPair(token0: string, token1: string): void;
1497
2851
  //#endregion
2852
+ export type { AddLiquidityInput, CreatePoolInput, EIP712DomainValue, EIP712Types, EntryParse, InvalidEntry, InvalidEntryHandler, PersonalSignChainDtoPayload, PoolPositionInput, PrivateKeyInput, RemoveLiquidityInput, RequestTradeInput, TypedDataPayload, V2WriteMethod };
1498
2853
  //# sourceMappingURL=index.d.cts.map