@symmio/trading-core 3.0.0 → 3.1.0

package/dist/gasless/http.js

@@ -0,0 +1,165 @@
+import { readHttpHeader as e } from "../shared/utils/http-header.js";
+import { SymmApiError as t, SymmError as n } from "../shared/errors/symm-error.js";
+import { parseGaslessErrorDetail as r } from "./errors.js";
+import { toSanitizedApiError as i } from "../shared/errors/sanitized-api-error.js";
+import { assertGaslessUrlServes as a, parseGaslessUrl as o } from "./gasless-url.js";
+import { resolveGaslessService as s } from "./resolve-gasless.js";
+import { GASLESS_SUBMIT_ROUTES as c, GASLESS_SUBMIT_UNCONFIRMED_CODE as l, readGaslessErrorStatus as u } from "./unconfirmed-submit.js";
+import d, { isAxiosError as f } from "axios";
+var p = "x-gaslessq-protocol-instance";
+function m(e, t) {
+	let n = e.getChainConfig(t.chainId), r = s(e, { chainId: t.chainId });
+	return h(n.chainId, r, t.service);
+}
+function h(e, t, n) {
+	let r = o(e, t);
+	a(e, r, n);
+	let i = { Accept: "application/json" }, s = t.apiKey?.trim();
+	return s && (i.Authorization = `Bearer ${s}`), {
+		baseURL: r.form === "origin" ? `${r.url}/v1/instances/${encodeURIComponent(r.protocolInstance)}/${n}` : r.form === "service-base" ? r.url : `${r.url}/${n}`,
+		headers: i,
+		protocolInstance: r.protocolInstance,
+		requireInstanceHeader: r.form !== "proxy-root",
+		submitTimeoutMs: t.execution?.submitTimeoutMs ?? 3e4,
+		chainId: e
+	};
+}
+function g(e, t) {
+	let r = _(e, t);
+	if (r !== null) throw new n("api", "GASLESS_INSTANCE_MISMATCH", v(e, r));
+}
+function _(t, n) {
+	let r = t.protocolInstance;
+	if (!r) return null;
+	let i = e(n.headers, p);
+	return i === void 0 && !t.requireInstanceHeader || i === r ? null : i ?? "<missing>";
+}
+function v(e, t) {
+	return `Gasless: the response came from protocol instance "${t}", but chain ${e.chainId} expects "${e.protocolInstance}". Check the gasless url / protocolInstance pairing.`;
+}
+function y(e) {
+	return !(e instanceof t) || e.code !== "GASLESS_INSTANCE_MISMATCH" ? !1 : e.status >= 200 && e.status < 300;
+}
+async function b(e, t, n, r = {}) {
+	try {
+		let n = await d.get(t, {
+			baseURL: e.baseURL,
+			headers: e.headers,
+			signal: r.signal
+		});
+		return g(e, n), n.data;
+	} catch (t) {
+		throw E(t, e, n);
+	}
+}
+function x(e) {
+	return new Promise((t) => setTimeout(t, e));
+}
+function S(e, t = Math.random) {
+	return Math.max(e ?? 0, 1e3 + Math.floor(t() * 1e3));
+}
+async function C(e, t, n, r) {
+	try {
+		return await d.post(t, n, {
+			baseURL: e.baseURL,
+			headers: {
+				...e.headers,
+				"Content-Type": "application/json"
+			},
+			timeout: e.submitTimeoutMs
+		});
+	} catch (t) {
+		throw E(t, e, r);
+	}
+}
+async function w(e, n, r, i) {
+	let { service: a, code: o } = c[n], s = Date.now() + e.submitTimeoutMs, l = 0, u = !1;
+	for (;;) {
+		let c;
+		try {
+			c = await C(e, n, r, o);
+		} catch (o) {
+			let c = D(o);
+			if (c === "rate-limited" || c === "gateway-not-ready") {
+				let e = S(o instanceof t ? o.retryAfterMs : null);
+				if (l < 2 && Date.now() + e <= s) {
+					l += 1, await x(e);
+					continue;
+				}
+			}
+			if (u) throw T(e, {
+				service: a,
+				path: n,
+				body: r,
+				idempotencyKey: i
+			}, o);
+			if (c !== "ambiguous") throw o;
+			u = !0, await x(S(null));
+			continue;
+		}
+		let d = _(e, c);
+		if (d !== null) throw new t({
+			code: "GASLESS_INSTANCE_MISMATCH",
+			message: `${v(e, d)} The submit was accepted there, so reconcile the request id in responseData before submitting anything else.`,
+			status: c.status,
+			statusText: c.statusText,
+			responseData: c.data,
+			url: `${e.baseURL}${n}`,
+			method: "POST"
+		});
+		let f = c.data?.request_id;
+		if (typeof f != "string" || f.length === 0) throw T(e, {
+			service: a,
+			path: n,
+			body: r,
+			idempotencyKey: i
+		});
+		return c.data;
+	}
+}
+function T(e, n, r) {
+	let i = u(r) ?? 0;
+	return new t({
+		code: l,
+		message: `Gasless: the submit to ${n.path} on chain ${e.chainId} could not be confirmed${i === 0 ? " (no response)" : ` (last status ${i})`}, so the service may already be executing it. Resend the recorded body under idempotency key ${n.idempotencyKey} with resubmitGaslessRequest — never re-run this intent through the wallet.`,
+		status: i,
+		statusText: r instanceof t ? r.statusText : "",
+		responseData: {
+			chainId: e.chainId,
+			...n
+		},
+		url: `${e.baseURL}${n.path}`,
+		method: "POST",
+		cause: r instanceof Error ? r : void 0
+	});
+}
+function E(e, t, r) {
+	return e instanceof n ? e : f(e) ? i(e, {
+		code: r,
+		baseURL: t.baseURL
+	}) : new n("api", r, `Gasless request failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e instanceof Error ? e : void 0 });
+}
+function D(e) {
+	let t = u(e);
+	if (t === void 0) return null;
+	let n = typeof r(e)?.gatewayError == "string";
+	switch (t) {
+		case 0:
+		case 408: return "ambiguous";
+		case 401: return "unauthorized";
+		case 403: return "forbidden";
+		case 422: return "client-schema";
+		case 429: return "rate-limited";
+		case 400: return n ? "selector-conflict" : "service";
+		case 404: return n ? "unknown-instance" : "service";
+		case 503: return n ? "gateway-not-ready" : "ambiguous";
+		default: return t >= 500 ? "ambiguous" : "service";
+	}
+}
+function O() {
+	return globalThis.crypto.randomUUID();
+}
+//#endregion
+export { D as classifyGaslessHttpStatus, b as gaslessGet, O as generateGaslessIdempotencyKey, y as isGaslessAcceptedInstanceMismatchError, w as postGaslessSubmit, m as resolveGaslessHttp };
+
+//# sourceMappingURL=http.js.map

package/dist/gasless/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":[],"sources":["../../src/gasless/http.ts"],"sourcesContent":["import axios, { isAxiosError, type AxiosResponse } from \"axios\";\nimport type { SymmioGaslessConfig } from \"../core/chains/types\";\nimport type { Config } from \"../core/config\";\nimport { toSanitizedApiError } from \"../shared/errors/sanitized-api-error\";\nimport { SymmApiError, SymmError } from \"../shared/errors/symm-error\";\nimport { readHttpHeader } from \"../shared/utils/http-header\";\nimport { parseGaslessErrorDetail } from \"./errors\";\nimport { assertGaslessUrlServes, parseGaslessUrl } from \"./gasless-url\";\nimport { resolveGaslessService } from \"./resolve-gasless\";\nimport type { GaslessService } from \"./types\";\nimport {\n  GASLESS_SUBMIT_ROUTES,\n  GASLESS_SUBMIT_UNCONFIRMED_CODE,\n  readGaslessErrorStatus,\n  type GaslessSubmitPath,\n  type GaslessUnconfirmedSubmit,\n} from \"./unconfirmed-submit\";\n\n/** Default HTTP timeout for a gasless submit (`execution.submitTimeoutMs`). @internal */\nexport const GASLESS_SUBMIT_TIMEOUT_MS = 30_000;\n\n/**\n * How many times a submit the gateway itself refused (`429`, or a `503`\n * carrying its `{ error }` envelope) is retried under the same idempotency key.\n * Both mean the request never reached the service, so a retry cannot duplicate\n * anything — the bound exists to keep a submit from outliving its caller.\n *\n * @internal\n */\nexport const GASLESS_SUBMIT_THROTTLE_RETRIES = 2;\n\n/** The response header the gateway stamps with the protocol instance that answered. @internal */\nexport const GASLESS_PROTOCOL_INSTANCE_HEADER = \"x-gaslessq-protocol-instance\";\n\n/**\n * A resolved gasless HTTP context for one `(chain, service)` pair: the final\n * per-service base URL, the request headers, and the protocol instance the\n * responses must come from.\n *\n * @internal\n */\nexport interface GaslessHttpContext {\n  /** Final service base, e.g. `…/v1/instances/<protocol-instance>/operations`. */\n  baseURL: string;\n  /** Request headers: `Accept`, plus `Authorization: Bearer …` only when an `apiKey` is configured. */\n  headers: Record<string, string>;\n  /**\n   * The protocol instance responses are asserted against, or `null` when the\n   * config names none (a proxy root without `protocolInstance`).\n   */\n  protocolInstance: string | null;\n  /**\n   * Whether a response must carry the instance header. `true` for the gateway\n   * URL forms, where the gateway itself stamps every routed response; `false`\n   * for a proxy root, which may not forward the header, so only a header that\n   * is present is checked.\n   */\n  requireInstanceHeader: boolean;\n  /** HTTP timeout applied to submits (POSTs), in ms. */\n  submitTimeoutMs: number;\n  /** The chain the context was resolved for (for error messages and events). */\n  chainId: number;\n}\n\n/**\n * Derive the per-service base URL from a chain's gasless config.\n *\n * The `url` forms are parsed by `parseGaslessUrl`:\n * - a gateway **origin** — the SDK appends\n *   `/v1/instances/{protocolInstance}/{service}`;\n * - an **instance root** — the SDK appends `/{service}`;\n * - an instance-pinned **service base** — used as-is, and it must match the\n *   requested service;\n * - a **proxy root** — the SDK appends `/{service}`.\n *\n * @internal\n */\nexport function resolveGaslessHttp(\n  config: Config,\n  parameters: { chainId?: number; service: GaslessService },\n): GaslessHttpContext {\n  const chain = config.getChainConfig(parameters.chainId);\n  const gasless = resolveGaslessService(config, { chainId: parameters.chainId });\n  return buildGaslessHttpContext(chain.chainId, gasless, parameters.service);\n}\n\n/**\n * Build a {@link GaslessHttpContext} from an already-resolved gasless block.\n *\n * Anonymous access is the default: the `Authorization` header is omitted\n * entirely unless a non-blank `apiKey` is configured.\n *\n * @internal\n */\nexport function buildGaslessHttpContext(\n  chainId: number,\n  gasless: SymmioGaslessConfig,\n  service: GaslessService,\n): GaslessHttpContext {\n  const url = parseGaslessUrl(chainId, gasless);\n  assertGaslessUrlServes(chainId, url, service);\n\n  const headers: Record<string, string> = { Accept: \"application/json\" };\n  const apiKey = gasless.apiKey?.trim();\n  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;\n\n  const baseURL =\n    url.form === \"origin\"\n      ? `${url.url}/v1/instances/${encodeURIComponent(url.protocolInstance)}/${service}`\n      : url.form === \"service-base\"\n        ? url.url\n        : `${url.url}/${service}`;\n\n  return {\n    baseURL,\n    headers,\n    protocolInstance: url.protocolInstance,\n    requireInstanceHeader: url.form !== \"proxy-root\",\n    submitTimeoutMs: gasless.execution?.submitTimeoutMs ?? GASLESS_SUBMIT_TIMEOUT_MS,\n    chainId,\n  };\n}\n\n/**\n * Assert that a successful response came from the expected protocol instance.\n * The gateway stamps `X-GasLessQ-Protocol-Instance` on every response it\n * routes. A mismatch means a different deployment answered (a\n * staging/production cross-wire), and the response must not be trusted.\n *\n * Gateway URL forms fail closed on a missing header too. A proxy root only\n * fails on a header that is present and wrong, since a proxy may not forward\n * it.\n *\n * @internal\n * @throws {SymmError} `GASLESS_INSTANCE_MISMATCH`\n */\nexport function assertGaslessInstance(context: GaslessHttpContext, response: AxiosResponse): void {\n  const actual = readGaslessInstanceMismatch(context, response);\n  if (actual === null) return;\n  throw new SymmError(\"api\", \"GASLESS_INSTANCE_MISMATCH\", gaslessInstanceMismatchMessage(context, actual));\n}\n\n/**\n * The instance a response was stamped with when it is **not** the expected one,\n * or `null` when the response is trustworthy. `\"<missing>\"` stands for a\n * gateway response that carried no header at all.\n */\nfunction readGaslessInstanceMismatch(context: GaslessHttpContext, response: AxiosResponse): string | null {\n  const expected = context.protocolInstance;\n  if (!expected) return null;\n  const actual = readHttpHeader(response.headers, GASLESS_PROTOCOL_INSTANCE_HEADER);\n  if (actual === undefined && !context.requireInstanceHeader) return null;\n  return actual === expected ? null : (actual ?? \"<missing>\");\n}\n\nfunction gaslessInstanceMismatchMessage(context: GaslessHttpContext, actual: string): string {\n  return `Gasless: the response came from protocol instance \"${actual}\", but chain ${context.chainId} expects \"${context.protocolInstance}\". Check the gasless url / protocolInstance pairing.`;\n}\n\n/**\n * Whether an error is a `GASLESS_INSTANCE_MISMATCH` on a response the gateway\n * **accepted** (a `2xx`) — the submit created a workflow somewhere, on a\n * deployment this config does not address.\n *\n * Nothing about it can be trusted except that it happened, so it is never\n * grounds for a wallet-paid retry, and any signature it consumed must be\n * treated as spent.\n *\n * @internal\n */\nexport function isGaslessAcceptedInstanceMismatchError(err: unknown): boolean {\n  if (!(err instanceof SymmApiError) || err.code !== \"GASLESS_INSTANCE_MISMATCH\") return false;\n  return err.status >= 200 && err.status < 300;\n}\n\n/**\n * Perform a gasless GET and normalize failures into the house error shape.\n *\n * @param context - The resolved HTTP context for the call's service.\n * @param path - The path under the service base.\n * @param code - The SDK error code a failure is reported under.\n * @param options - `signal` cancels the request in flight — pass TanStack's\n *   query signal, or the caller's own, so a poll nobody is waiting for stops\n *   spending the deployment's shared request budget.\n *\n * @internal\n */\nexport async function gaslessGet<data>(\n  context: GaslessHttpContext,\n  path: string,\n  code: string,\n  options: { signal?: AbortSignal } = {},\n): Promise<data> {\n  try {\n    const response = await axios.get<data>(path, {\n      baseURL: context.baseURL,\n      headers: context.headers,\n      signal: options.signal,\n    });\n    assertGaslessInstance(context, response);\n    return response.data;\n  } catch (err) {\n    throw toGaslessError(err, context, code);\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * How long to wait before resending a submit, whether the gateway refused it or\n * its outcome is unknown.\n *\n * `Retry-After` is honored when the gateway sent one and the browser was\n * allowed to read it, but never trusted as a floor of zero: a cross-origin page\n * usually sees `null`, and hammering a throttled gateway is what earned the\n * `429`. So the wait is at least a jittered second, and the jitter keeps a\n * page's concurrent workflows from retrying in lockstep.\n *\n * @param retryAfterMs - The server's requested delay, or `null` when unknown.\n * @param random - Injectable `Math.random`, for deterministic tests.\n * @returns The delay in ms.\n *\n * @internal\n */\nexport function gaslessSubmitRetryDelay(retryAfterMs: number | null, random: () => number = Math.random): number {\n  return Math.max(retryAfterMs ?? 0, 1_000 + Math.floor(random() * 1_000));\n}\n\n/** One POST attempt: the axios call plus the house error normalization. */\nasync function postGaslessOnce<data>(\n  context: GaslessHttpContext,\n  path: string,\n  body: unknown,\n  code: string,\n): Promise<AxiosResponse<data>> {\n  try {\n    return await axios.post<data>(path, body, {\n      baseURL: context.baseURL,\n      headers: { ...context.headers, \"Content-Type\": \"application/json\" },\n      timeout: context.submitTimeoutMs,\n    });\n  } catch (err) {\n    throw toGaslessError(err, context, code);\n  }\n}\n\n/**\n * POST one gasless **submit** — the only gasless call that can leave a side\n * effect behind when its response is lost — and decide, for every outcome,\n * whether the service can have accepted it.\n *\n * Three dispositions, all under the caller's single idempotency key (the vendor\n * returns the existing record for a byte-identical resend, so reusing the key\n * can never double-execute; a *changed* payload needs a fresh one):\n *\n * - **Refused by the gateway** (`429`, or a `503` carrying its `{ error }`\n *   envelope): the request never reached the service. Resent up to\n *   {@link GASLESS_SUBMIT_THROTTLE_RETRIES} times after\n *   {@link gaslessSubmitRetryDelay}, while the wait still fits inside\n *   `execution.submitTimeoutMs`. Exhausted, the gateway's own error is thrown —\n *   the one submit failure that is provably *not* accepted, and so the only one\n *   a wallet-paid retry may follow.\n * - **Ambiguous** (no response, a timeout, or a `5xx` without the gateway\n *   envelope): the service may or may not have accepted it. Resent **once**,\n *   after a {@link gaslessSubmitRetryDelay} backoff, then thrown as\n *   `GASLESS_SUBMIT_UNCONFIRMED` carrying the exact bytes that were sent, so the\n *   caller can persist them and replay them later with `resubmitGaslessRequest`.\n *   Never a rejection, and never grounds for a wallet retry. The backoff is the\n *   vendor's: a resend that races the first attempt's insert can be answered with\n *   a `5xx` instead of the record that insert created.\n * - **Answered** (any other status, or a `2xx`): thrown as-is, or returned. A\n *   `2xx` without a `request_id` is unconfirmed too — the workflow exists and\n *   nothing identifies it. A `2xx` from the wrong protocol instance throws\n *   `GASLESS_INSTANCE_MISMATCH` with the parsed body kept in `responseData`,\n *   because the `request_id` in it is the only handle on a request that was\n *   accepted somewhere.\n *\n * An ambiguous attempt decides every failure after it. A gateway refusal of the\n * resend, or a service verdict on it, describes only the resend — the first\n * attempt may already be executing — so it is thrown as\n * `GASLESS_SUBMIT_UNCONFIRMED` with that failure as its `cause`. Thrown as-is,\n * a `429` would read as provably not accepted, and a wallet-paid retry would\n * execute the intent twice.\n *\n * @param context - The resolved HTTP context for the submit's service.\n * @param path - The submit route (see {@link GASLESS_SUBMIT_ROUTES}).\n * @param body - The exact JSON body to send.\n * @param idempotencyKey - The key inside `body`, recorded on an unconfirmed submit.\n * @returns The acceptance body.\n *\n * @internal\n */\nexport async function postGaslessSubmit<data extends { request_id?: string | null }>(\n  context: GaslessHttpContext,\n  path: GaslessSubmitPath,\n  body: unknown,\n  idempotencyKey: string,\n): Promise<data> {\n  const { service, code } = GASLESS_SUBMIT_ROUTES[path];\n  const retriesEndAt = Date.now() + context.submitTimeoutMs;\n  let throttleRetries = 0;\n  /** Set once an attempt failed ambiguously: the service may hold that attempt. */\n  let mayBeAccepted = false;\n\n  for (;;) {\n    let response: AxiosResponse<data>;\n    try {\n      response = await postGaslessOnce<data>(context, path, body, code);\n    } catch (err) {\n      const failure = classifyGaslessHttpStatus(err);\n\n      if (failure === \"rate-limited\" || failure === \"gateway-not-ready\") {\n        const delay = gaslessSubmitRetryDelay(err instanceof SymmApiError ? err.retryAfterMs : null);\n        if (throttleRetries < GASLESS_SUBMIT_THROTTLE_RETRIES && Date.now() + delay <= retriesEndAt) {\n          throttleRetries += 1;\n          await sleep(delay);\n          continue;\n        }\n      }\n\n      /**\n       * An answer speaks only for the attempt it came back for. Once an\n       * earlier attempt was ambiguous, that attempt may be executing whatever\n       * this one was told, so the failure is unconfirmed, never a rejection.\n       */\n      if (mayBeAccepted) throw unconfirmedGaslessSubmitError(context, { service, path, body, idempotencyKey }, err);\n      if (failure !== \"ambiguous\") throw err;\n\n      /**\n       * The vendor's prescribed recovery for a lost response: resend the\n       * identical request under the same key, after a backoff, which either\n       * lands it or returns the record it already created.\n       */\n      mayBeAccepted = true;\n      await sleep(gaslessSubmitRetryDelay(null));\n      continue;\n    }\n\n    const mismatch = readGaslessInstanceMismatch(context, response);\n    if (mismatch !== null) {\n      throw new SymmApiError({\n        code: \"GASLESS_INSTANCE_MISMATCH\",\n        message: `${gaslessInstanceMismatchMessage(context, mismatch)} The submit was accepted there, so reconcile the request id in responseData before submitting anything else.`,\n        status: response.status,\n        statusText: response.statusText,\n        responseData: response.data,\n        url: `${context.baseURL}${path}`,\n        method: \"POST\",\n      });\n    }\n\n    const requestId = response.data?.request_id;\n    if (typeof requestId !== \"string\" || requestId.length === 0) {\n      throw unconfirmedGaslessSubmitError(context, { service, path, body, idempotencyKey });\n    }\n    return response.data;\n  }\n}\n\n/**\n * Build the `GASLESS_SUBMIT_UNCONFIRMED` error, whose `responseData` is the\n * replayable {@link GaslessUnconfirmedSubmit} rather than a response body —\n * there is no trustworthy response body, and the bytes that were sent are the\n * only thing that can recover the workflow.\n */\nfunction unconfirmedGaslessSubmitError(\n  context: GaslessHttpContext,\n  submit: Omit<GaslessUnconfirmedSubmit, \"chainId\">,\n  cause?: unknown,\n): SymmApiError {\n  const status = readGaslessErrorStatus(cause) ?? 0;\n  return new SymmApiError({\n    code: GASLESS_SUBMIT_UNCONFIRMED_CODE,\n    message: `Gasless: the submit to ${submit.path} on chain ${context.chainId} could not be confirmed${status === 0 ? \" (no response)\" : ` (last status ${status})`}, so the service may already be executing it. Resend the recorded body under idempotency key ${submit.idempotencyKey} with resubmitGaslessRequest — never re-run this intent through the wallet.`,\n    status,\n    statusText: cause instanceof SymmApiError ? cause.statusText : \"\",\n    responseData: { chainId: context.chainId, ...submit } satisfies GaslessUnconfirmedSubmit,\n    url: `${context.baseURL}${submit.path}`,\n    method: \"POST\",\n    cause: cause instanceof Error ? cause : undefined,\n  });\n}\n\n/**\n * The canonical 3-branch error normalization every gasless HTTP call shares.\n *\n * An axios failure becomes a `SymmApiError` whose `cause` is a sanitized\n * snapshot (see `toSanitizedApiError`), never the axios error itself. That\n * error's request config holds the `Authorization` header and the signed body,\n * so the `apiKey` cannot leak through a logged or serialized error.\n * `responseData` stays the raw response body.\n *\n * @internal\n */\nexport function toGaslessError(err: unknown, context: GaslessHttpContext, code: string): Error {\n  if (err instanceof SymmError) return err;\n  if (isAxiosError(err)) return toSanitizedApiError(err, { code, baseURL: context.baseURL });\n  return new SymmError(\"api\", code, `Gasless request failed: ${err instanceof Error ? err.message : String(err)}`, {\n    cause: err instanceof Error ? err : undefined,\n  });\n}\n\n/**\n * How a failed gasless HTTP call was disposed of, from the status and, where\n * the gateway overloads a status, from the body: the gateway's own\n * `{ \"error\": \"…\" }` envelope versus a service `{ \"detail\": … }` body.\n *\n * - `\"rate-limited\"` — `429`: dropped at the gateway, never forwarded.\n * - `\"gateway-not-ready\"` — `503` with the gateway envelope: its configuration is not ready.\n * - `\"unauthorized\"` / `\"forbidden\"` — `401` / `403`: credentials rejected, or not allowed for this instance or service.\n * - `\"unknown-instance\"` — `404` with the gateway envelope: no such instance or service route.\n * - `\"selector-conflict\"` — `400` with the gateway envelope: the URL and the instance selector disagree.\n * - `\"client-schema\"` — `422`: the service rejected the payload shape (a client bug).\n * - `\"ambiguous\"` — no response (network failure or timeout), `408`, or any other `5xx`: the request may or may not have reached the service.\n * - `\"service\"` — any other status: the service answered with its own verdict (`detail.code`).\n *\n * @internal\n */\nexport type GaslessHttpFailureClass =\n  | \"rate-limited\"\n  | \"gateway-not-ready\"\n  | \"unauthorized\"\n  | \"forbidden\"\n  | \"unknown-instance\"\n  | \"selector-conflict\"\n  | \"client-schema\"\n  | \"ambiguous\"\n  | \"service\";\n\n/**\n * Classify a failed gasless HTTP call — see {@link GaslessHttpFailureClass}.\n *\n * The status is read structurally, so an error a framework layer re-wrapped\n * (`@symmio/trading-react`'s `SymmioRequestError`, which copies `status` and\n * `responseData`) classifies exactly like the `SymmApiError` underneath it.\n *\n * @param err - Anything caught from a gasless HTTP call.\n * @returns The class, or `null` when `err` carries no HTTP status.\n *\n * @internal\n */\nexport function classifyGaslessHttpStatus(err: unknown): GaslessHttpFailureClass | null {\n  const status = readGaslessErrorStatus(err);\n  if (status === undefined) return null;\n  const fromGateway = typeof parseGaslessErrorDetail(err)?.gatewayError === \"string\";\n  switch (status) {\n    case 0:\n    case 408:\n      return \"ambiguous\";\n    case 401:\n      return \"unauthorized\";\n    case 403:\n      return \"forbidden\";\n    case 422:\n      return \"client-schema\";\n    case 429:\n      return \"rate-limited\";\n    case 400:\n      return fromGateway ? \"selector-conflict\" : \"service\";\n    case 404:\n      return fromGateway ? \"unknown-instance\" : \"service\";\n    case 503:\n      return fromGateway ? \"gateway-not-ready\" : \"ambiguous\";\n    default:\n      return status >= 500 ? \"ambiguous\" : \"service\";\n  }\n}\n\n/**\n * Generate a random idempotency key for one gasless submit. Reuse the same key\n * only when retrying the byte-identical request; any change to the payload\n * needs a fresh key.\n */\nexport function generateGaslessIdempotencyKey(): string {\n  return globalThis.crypto.randomUUID();\n}\n"],"mappings":"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"}

package/dist/gasless/index.d.ts

@@ -0,0 +1,34 @@
+export * from './batch/index.js';
+export * from './classify-gasless-failure.js';
+export * from './confirm-gasless-request/index.js';
+export * from './constants.js';
+export * from './eip712.js';
+export * from './errors.js';
+export * from './fallback.js';
+export * from './format-gasless-operation.js';
+export * from './gasless-wallet-execute/index.js';
+export * from './get-gasless-batch-fee-quote/index.js';
+export * from './get-gasless-deposit-policy/index.js';
+export * from './get-gasless-fee-quote/index.js';
+export * from './get-gasless-request/index.js';
+export * from './get-gasless-request-transactions/index.js';
+export * from './get-gasless-wallet-address/index.js';
+export * from './get-gasless-wallet-creation-fee/index.js';
+export * from './get-gasless-wallet-nonce/index.js';
+export * from './get-session-key-selectors.js';
+export * from './is-newer-gasless-request.js';
+export * from './observe-gasless-request.js';
+export * from './relay-gasless-batch/index.js';
+export * from './relay-grant-delegation/index.js';
+export * from './relay-instant-operations/index.js';
+export * from './relayable-writes.js';
+export * from './resolve-gasless.js';
+export * from './resubmit-gasless-request/index.js';
+export * from './settle-gasless-deposit-existing-account/index.js';
+export * from './settle-gasless-deposit-new-account/index.js';
+export * from './types.js';
+export * from './unconfirmed-submit.js';
+export * from './wait-for-gasless-request/index.js';
+export * from './wire-types.js';
+export * from './write-request-registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gasless/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gasless/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC"}

package/dist/gasless/is-newer-gasless-request.d.ts

@@ -0,0 +1,32 @@
+import { GaslessRequest } from './types.js';
+/**
+ * Whether `next` is a later view of a request than `prev` — the stale-response
+ * guard for anything that writes a polled record somewhere shared (a query
+ * cache, a progress state, a stored row).
+ *
+ * Status reads are concurrent by construction: a poll, a retry after a
+ * transient failure and a stream snapshot can all be in flight at once, and
+ * they do not answer in the order they were sent. Without this guard a slow
+ * `queued` response that lands after the `succeeded` one repaints a finished
+ * workflow as pending, which is exactly the "it looks stuck, submit it again"
+ * bug the lifecycle contract forbids.
+ *
+ * The order is the lifecycle first — `queued` < `submitted` < terminal, with
+ * **terminal sticky**: a terminal record is immutable, so nothing non-terminal
+ * ever replaces one. Within the same rank, `updatedAt` decides; when either
+ * record does not carry one, `next` wins, because a record with no timestamp
+ * cannot be proven stale and the newer fetch is the better guess.
+ *
+ * @param prev - The record currently held, or `undefined` when there is none.
+ * @param next - The record that just arrived.
+ * @returns `true` when `next` should replace `prev`.
+ *
+ * @example
+ * ```ts
+ * queryClient.setQueryData(key, (prev?: GaslessRequest) =>
+ *   isNewerGaslessRequest(prev, incoming) ? incoming : prev,
+ * );
+ * ```
+ */
+export declare function isNewerGaslessRequest(prev: GaslessRequest | undefined, next: GaslessRequest): boolean;
+//# sourceMappingURL=is-newer-gasless-request.d.ts.map

package/dist/gasless/is-newer-gasless-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-newer-gasless-request.d.ts","sourceRoot":"","sources":["../../src/gasless/is-newer-gasless-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkD,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAkB9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAYrG"}

package/dist/gasless/is-newer-gasless-request.js

@@ -0,0 +1,21 @@
+import { GaslessRequestStatus as e, isGaslessRequestTerminal as t } from "./types.js";
+//#region src/gasless/is-newer-gasless-request.ts
+function n(n) {
+	return t(n) ? 2 : +(n === e.SUBMITTED);
+}
+function r(e) {
+	if (!e.updatedAt) return null;
+	let t = Date.parse(e.updatedAt);
+	return Number.isNaN(t) ? null : t;
+}
+function i(e, t) {
+	if (!e || e.requestId !== t.requestId) return !0;
+	let i = n(e.status), a = n(t.status);
+	if (a !== i) return a > i;
+	let o = r(e), s = r(t);
+	return o === null || s === null ? !0 : s >= o;
+}
+//#endregion
+export { i as isNewerGaslessRequest };
+
+//# sourceMappingURL=is-newer-gasless-request.js.map

package/dist/gasless/is-newer-gasless-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-newer-gasless-request.js","names":[],"sources":["../../src/gasless/is-newer-gasless-request.ts"],"sourcesContent":["import { GaslessRequestStatus, isGaslessRequestTerminal, type GaslessRequest } from \"./types\";\n\n/**\n * How far along the lifecycle a status is. Terminal statuses share the top rank\n * — none of them can be superseded by another.\n */\nfunction statusRank(status: GaslessRequestStatus): number {\n  if (isGaslessRequestTerminal(status)) return 2;\n  return status === GaslessRequestStatus.SUBMITTED ? 1 : 0;\n}\n\n/** The record's `updatedAt` as epoch ms, or `null` when it is missing or unparseable. */\nfunction updatedAtMs(request: GaslessRequest): number | null {\n  if (!request.updatedAt) return null;\n  const parsed = Date.parse(request.updatedAt);\n  return Number.isNaN(parsed) ? null : parsed;\n}\n\n/**\n * Whether `next` is a later view of a request than `prev` — the stale-response\n * guard for anything that writes a polled record somewhere shared (a query\n * cache, a progress state, a stored row).\n *\n * Status reads are concurrent by construction: a poll, a retry after a\n * transient failure and a stream snapshot can all be in flight at once, and\n * they do not answer in the order they were sent. Without this guard a slow\n * `queued` response that lands after the `succeeded` one repaints a finished\n * workflow as pending, which is exactly the \"it looks stuck, submit it again\"\n * bug the lifecycle contract forbids.\n *\n * The order is the lifecycle first — `queued` < `submitted` < terminal, with\n * **terminal sticky**: a terminal record is immutable, so nothing non-terminal\n * ever replaces one. Within the same rank, `updatedAt` decides; when either\n * record does not carry one, `next` wins, because a record with no timestamp\n * cannot be proven stale and the newer fetch is the better guess.\n *\n * @param prev - The record currently held, or `undefined` when there is none.\n * @param next - The record that just arrived.\n * @returns `true` when `next` should replace `prev`.\n *\n * @example\n * ```ts\n * queryClient.setQueryData(key, (prev?: GaslessRequest) =>\n *   isNewerGaslessRequest(prev, incoming) ? incoming : prev,\n * );\n * ```\n */\nexport function isNewerGaslessRequest(prev: GaslessRequest | undefined, next: GaslessRequest): boolean {\n  if (!prev) return true;\n  if (prev.requestId !== next.requestId) return true;\n\n  const prevRank = statusRank(prev.status);\n  const nextRank = statusRank(next.status);\n  if (nextRank !== prevRank) return nextRank > prevRank;\n\n  const prevAt = updatedAtMs(prev);\n  const nextAt = updatedAtMs(next);\n  if (prevAt === null || nextAt === null) return true;\n  return nextAt >= prevAt;\n}\n"],"mappings":";;AAMA,SAAS,EAAW,GAAsC;CAExD,OADI,EAAyB,CAAM,IAAU,IACtC,QAAW,EAAqB;AACzC;AAGA,SAAS,EAAY,GAAwC;CAC3D,IAAI,CAAC,EAAQ,WAAW,OAAO;CAC/B,IAAM,IAAS,KAAK,MAAM,EAAQ,SAAS;CAC3C,OAAO,OAAO,MAAM,CAAM,IAAI,OAAO;AACvC;AA+BA,SAAgB,EAAsB,GAAkC,GAA+B;CAErG,IADI,CAAC,KACD,EAAK,cAAc,EAAK,WAAW,OAAO;CAE9C,IAAM,IAAW,EAAW,EAAK,MAAM,GACjC,IAAW,EAAW,EAAK,MAAM;CACvC,IAAI,MAAa,GAAU,OAAO,IAAW;CAE7C,IAAM,IAAS,EAAY,CAAI,GACzB,IAAS,EAAY,CAAI;CAE/B,OADI,MAAW,QAAQ,MAAW,OAAa,KACxC,KAAU;AACnB"}

package/dist/gasless/nonce-lock.d.ts

@@ -0,0 +1,180 @@
+import { Config } from '../core/config/index.js';
+import { GaslessService } from './types.js';
+/**
+ * The lock/stream key of an account's **InstantLayer** operation nonces, which
+ * the contract counts per `signerAccount`.
+ *
+ * @param chainId - The chain the operation relays on.
+ * @param signerAccount - The operation's `signerAccount.addr`.
+ * @returns The stream key.
+ *
+ * @internal
+ */
+export declare function gaslessInstantNonceStreamKey(chainId: number, signerAccount: string): string;
+/**
+ * The lock/stream key of a **gasless-wallet operation** nonce stream.
+ *
+ * The two shapes mirror the contract's own storage. Wallet `0` counts in
+ * `_legacyWalletOperationNonces[signerAccount]`, one stream per signer account
+ * across every owner, so its key deliberately omits the owner — keying it by
+ * owner would let two owners' relays sign the same legacy nonce. Every positive
+ * id counts in `walletNonces[wallet][signerAccount]`, so its key carries both
+ * the id and the owner that derives the wallet.
+ *
+ * @param chainId - The chain the operation relays on.
+ * @param walletId - The selected wallet id.
+ * @param owner - The wallet's owner.
+ * @param signerAccount - The operation's `signerAccount.addr`.
+ * @returns The stream key.
+ *
+ * @internal
+ */
+export declare function gaslessWalletNonceStreamKey(chainId: number, walletId: bigint, owner: string, signerAccount: string): string;
+/**
+ * Run `task` exclusively for one nonce stream. Queued tasks run in FIFO order;
+ * a failed task never blocks the next one, and the map entry is cleared once
+ * the last queued task settles.
+ *
+ * @param config - The SDK config the locks belong to.
+ * @param key - A stream key from {@link gaslessInstantNonceStreamKey} or {@link gaslessWalletNonceStreamKey}.
+ * @param task - The read-sign-submit critical section.
+ *
+ * @internal
+ */
+export declare function withGaslessNonceLock<result>(config: Config, key: string, task: () => Promise<result>): Promise<result>;
+/**
+ * Run `task` exclusively for **several** nonce streams at once — a batch that
+ * signs on more than one stream (an account's InstantLayer stream plus one
+ * stream per GaslessWallet id). The single-stream {@link withGaslessNonceLock}
+ * is the one-key case.
+ *
+ * The task joins every stream's queue in the same synchronous step and starts
+ * once all of their earlier tasks have settled. A task therefore only ever
+ * waits on tasks queued before it, so two batches that share streams — in any
+ * order — can never each hold one stream while waiting for the other's.
+ *
+ * @param config - The SDK config the locks belong to.
+ * @param keys - The stream keys the task signs on; duplicates are ignored.
+ * @param task - The read-sign-submit critical section.
+ *
+ * @internal
+ */
+export declare function withGaslessNonceLocks<result>(config: Config, keys: readonly string[], task: () => Promise<result>): Promise<result>;
+/** Forget a stream's pending signature. @internal */
+export declare function clearGaslessPendingNonce(config: Config, key: string): void;
+/**
+ * Whether a thrown submit error leaves the stream's signed nonce **possibly or
+ * certainly consumed**, so the next caller must wait for it instead of signing
+ * it again.
+ *
+ * Three shapes qualify, and the submit path narrows every ambiguity down to
+ * them before they get here:
+ *
+ * - `GASLESS_SUBMIT_UNCONFIRMED` — the transport failed ambiguously, or a
+ *   `202` carried no `request_id`. Either way the batch may be executing.
+ * - `GASLESS_ACCEPTANCE_INVALID` — the parser's own guard for that second case;
+ *   acceptance is certain and only the handle was lost, which makes the nonce
+ *   more likely to be consumed, not less.
+ * - A `2xx` from the wrong protocol instance — accepted somewhere, so the
+ *   signature must be treated as spent.
+ *
+ * Every other failure is a rejection that consumed nothing: the gateway refused
+ * the request before the service saw it, or the service answered with a verdict.
+ *
+ * @param err - Anything caught from a gasless submit.
+ * @returns `true` when the stream must stay blocked until the nonce moves or the signature expires.
+ *
+ * @internal
+ */
+export declare function blocksGaslessNonceStream(err: unknown): boolean;
+/**
+ * Submit a relay while keeping the stream's pending-signature record honest.
+ *
+ * The lock only spans the submit, so the nonce a released lock leaves behind is
+ * still unconsumed on-chain for as long as the relayer takes to broadcast. This
+ * records what was signed so the **next** caller on the stream can wait for it
+ * instead of signing the same nonce again.
+ *
+ * A blocking failure records `requestId: null`: the batch may have been
+ * accepted (an ambiguous transport failure) or is known to have been accepted
+ * without a trackable id, so the stream stays blocked until the nonce is seen
+ * consumed or the signature expires. A definitive rejection records nothing —
+ * nothing was accepted, so the nonce is free immediately.
+ *
+ * @param config - The SDK config.
+ * @param key - The stream key the submit was signed on.
+ * @param pending - What was signed: the highest nonce, the service, the chain and the signature deadline (seconds).
+ * @param submit - Performs the POST and returns the acceptance receipt.
+ * @param blocksStream - Whether a thrown error leaves the signed nonce possibly or certainly consumed; pass {@link blocksGaslessNonceStream}.
+ * @returns Whatever `submit` resolved with.
+ *
+ * @internal
+ */
+export declare function submitOnGaslessNonceStream<result extends {
+    requestId: string;
+}>(config: Config, key: string, pending: {
+    signedNonce: bigint;
+    service: GaslessService;
+    chainId: number;
+    deadline: bigint;
+}, submit: () => Promise<result>, blocksStream: (err: unknown) => boolean): Promise<result>;
+/**
+ * {@link submitOnGaslessNonceStream} for a submit that signed on **several**
+ * streams — one relay request carrying an InstantLayer operation and a
+ * GaslessWallet operation, say. Every stream records the same request, because
+ * one request consumes all of them or none; each keeps its own highest signed
+ * nonce.
+ *
+ * @param config - The SDK config.
+ * @param streams - Each stream the submit signed on, with the highest nonce it signed there.
+ * @param pending - The service, the chain and the signature deadline (seconds), shared by every stream.
+ * @param submit - Performs the POST and returns the acceptance receipt.
+ * @param blocksStream - Whether a thrown error leaves the signed nonces possibly or certainly consumed; pass {@link blocksGaslessNonceStream}.
+ * @returns Whatever `submit` resolved with.
+ *
+ * @internal
+ */
+export declare function submitOnGaslessNonceStreams<result extends {
+    requestId: string;
+}>(config: Config, streams: readonly {
+    key: string;
+    signedNonce: bigint;
+}[], pending: {
+    service: GaslessService;
+    chainId: number;
+    deadline: bigint;
+}, submit: () => Promise<result>, blocksStream: (err: unknown) => boolean): Promise<result>;
+/**
+ * Read a stream's consumed nonce, waiting first for anything this SDK already
+ * signed on it and has not seen land.
+ *
+ * The relayer forwards signed nonces; it never reserves, replaces or repairs
+ * them. So signing `consumed + 1` while an earlier signature for that same
+ * nonce is still in flight guarantees that one of the two reverts. Rather than
+ * hold the lock for the whole broadcast (which would stall every later write
+ * behind a slow relay), the lock is released at the `202` and the wait happens
+ * lazily here, only when a new caller actually needs the stream.
+ *
+ * Waiting ends as soon as the pending request reaches **any** terminal status —
+ * a failed one frees the nonce, a successful one advances it — or as soon as
+ * the nonce is observed to have moved past what was signed. The budget is
+ * `min(signature deadline, 120 s)`: past the deadline the signature can never
+ * land, so the nonce is free.
+ *
+ * A successful terminal advances the stream without waiting for this RPC to
+ * see the block. `succeeded` is the relayer's node's view and a public RPC can
+ * trail it, so the signed nonce becomes a floor under every later read on the
+ * stream; the relayer simulates the next submit against its own node, which
+ * already has the block.
+ *
+ * @param config - The SDK config.
+ * @param key - The stream key.
+ * @param readConsumedNonce - Reads the stream's consumed nonce on-chain.
+ * @returns The consumed nonce to sign from (sign `+ 1n`).
+ * @throws {SymmError} `GASLESS_NONCE_STREAM_BUSY` when the budget runs out with a signature
+ *   still unaccounted for — signing now would collide with it.
+ *
+ * @internal
+ */
+export declare function readGaslessStreamNonce(config: Config, key: string, readConsumedNonce: () => Promise<bigint>): Promise<bigint>;
+//# sourceMappingURL=nonce-lock.d.ts.map

package/dist/gasless/nonce-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-lock.d.ts","sourceRoot":"","sources":["../../src/gasless/nonce-lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAI7C,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAiBzF;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,MAAM,CAKR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAkDD,qDAAqD;AACrD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAE1E;AAiBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAM9D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,SAAS;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC7E,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC5F,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC7B,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GACtC,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAAC,MAAM,SAAS;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EACpF,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,EACxD,OAAO,EAAE;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACvE,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC7B,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GACtC,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAkEjB"}

package/dist/gasless/nonce-lock.js

@@ -0,0 +1,102 @@
+import { SymmError as e } from "../shared/errors/symm-error.js";
+import { getGaslessUnconfirmedSubmit as t } from "./unconfirmed-submit.js";
+import { isGaslessAcceptedInstanceMismatchError as n } from "./http.js";
+import { GaslessRequestStatus as r } from "./types.js";
+import { isGaslessAcceptanceInvalidError as i } from "./to-gasless-submit-receipt.js";
+import { waitForGaslessRequest as a } from "./wait-for-gasless-request/wait-for-gasless-request.js";
+//#region src/gasless/nonce-lock.ts
+var o = /* @__PURE__ */ new WeakMap();
+function s(e, t) {
+	return `${e}:instant:${t.toLowerCase()}`;
+}
+function c(e, t, n, r) {
+	let i = r.toLowerCase();
+	return t === 0n ? `${e}:wallet:0:${i}` : `${e}:wallet:${t}:${n.toLowerCase()}:${i}`;
+}
+function l(e, t, n) {
+	return u(e, [t], n);
+}
+function u(e, t, n) {
+	let r = o.get(e);
+	r || (r = /* @__PURE__ */ new Map(), o.set(e, r));
+	let i = r, a = [...new Set(t)], s = Promise.all(a.map((e) => i.get(e) ?? Promise.resolve())).then(n, n), c = s.then(() => void 0, () => void 0);
+	for (let e of a) i.set(e, c);
+	return c.then(() => {
+		for (let e of a) i.get(e) === c && i.delete(e);
+	}), s;
+}
+var d = /* @__PURE__ */ new WeakMap(), f = /* @__PURE__ */ new WeakMap(), p = 12e4, m = 1500;
+function h(e) {
+	let t = d.get(e);
+	return t || (t = /* @__PURE__ */ new Map(), d.set(e, t)), t;
+}
+function g(e, t) {
+	d.get(e)?.delete(t);
+}
+function _(e, t, n) {
+	let r = f.get(e);
+	r || (r = /* @__PURE__ */ new Map(), f.set(e, r));
+	let i = r.get(t);
+	(i === void 0 || n > i) && r.set(t, n);
+}
+function v(e) {
+	return new Promise((t) => setTimeout(t, e));
+}
+function y(e) {
+	return t(e) !== null || i(e) || n(e);
+}
+function b(e, t, n, r, i) {
+	return x(e, [{
+		key: t,
+		signedNonce: n.signedNonce
+	}], n, r, i);
+}
+async function x(e, t, n, r, i) {
+	let a = Number(n.deadline) * 1e3, o = (r) => {
+		for (let i of t) h(e).set(i.key, {
+			signedNonce: i.signedNonce,
+			requestId: r,
+			service: n.service,
+			chainId: n.chainId,
+			expiresAtMs: a
+		});
+	}, s;
+	try {
+		s = await r();
+	} catch (e) {
+		throw i(e) && o(null), e;
+	}
+	return o(s.requestId), s;
+}
+async function S(t, n, i) {
+	let o = async () => {
+		let e = await i(), r = f.get(t)?.get(n);
+		return r !== void 0 && r > e ? r : e;
+	}, s = await o(), c = h(t).get(n);
+	if (!c) return s;
+	let l = Math.min(c.expiresAtMs, Date.now() + p);
+	if (c.signedNonce <= s || l <= Date.now()) return g(t, n), s;
+	if (c.requestId !== null) {
+		let e = null;
+		try {
+			e = await a(t, {
+				chainId: c.chainId,
+				requestId: c.requestId,
+				service: c.service,
+				until: "terminal",
+				timeoutMs: l - Date.now()
+			});
+		} catch {}
+		if (e !== null) return e.status === r.SUCCEEDED && _(t, n, c.signedNonce), g(t, n), await o();
+	}
+	for (; Date.now() < l;) {
+		await v(m);
+		let e = await o();
+		if (e >= c.signedNonce) return g(t, n), e;
+	}
+	throw new e("api", "GASLESS_NONCE_STREAM_BUSY", `Gasless: nonce ${c.signedNonce} was signed on this stream${c.requestId ? ` for request ${c.requestId}` : " for a submit that returned no trackable request id"} and has not landed yet. Signing now would collide with it — wait for that request to finish, or for its deadline to pass, before retrying.`);
+}
+//#endregion
+export { y as blocksGaslessNonceStream, s as gaslessInstantNonceStreamKey, c as gaslessWalletNonceStreamKey, S as readGaslessStreamNonce, b as submitOnGaslessNonceStream, x as submitOnGaslessNonceStreams, l as withGaslessNonceLock, u as withGaslessNonceLocks };
+
+//# sourceMappingURL=nonce-lock.js.map