@symmio/trading-core 3.0.0 → 3.1.0

package/dist/gasless/unconfirmed-submit.d.ts

@@ -0,0 +1,132 @@
+import { GaslessService } from './types.js';
+/**
+ * SDK error code of a submit whose outcome the SDK could not establish.
+ *
+ * @internal
+ */
+export declare const GASLESS_SUBMIT_UNCONFIRMED_CODE = "GASLESS_SUBMIT_UNCONFIRMED";
+/**
+ * The gateway paths a gasless **submit** POSTs to, with the service that stores
+ * the resulting workflow and the SDK error code its failures carry.
+ *
+ * A submit is the only kind of gasless request that can leave a side effect
+ * behind when its response is lost, so the retry, idempotency and
+ * "unconfirmed" machinery is keyed off this table rather than off a free-form
+ * path string.
+ *
+ * @internal
+ */
+export declare const GASLESS_SUBMIT_ROUTES: {
+    readonly "/gateway/relay-instant": {
+        readonly service: "operations";
+        readonly code: "GASLESS_RELAY_SUBMIT_FAILED";
+    };
+    readonly "/deposit-settlements/new-account": {
+        readonly service: "deposits";
+        readonly code: "GASLESS_SETTLEMENT_SUBMIT_FAILED";
+    };
+    readonly "/deposit-settlements/existing-account": {
+        readonly service: "deposits";
+        readonly code: "GASLESS_SETTLEMENT_SUBMIT_FAILED";
+    };
+};
+/**
+ * One of the three gateway paths a gasless submit POSTs to.
+ *
+ * Closed on purpose: a resubmit replays the recorded bytes against the same
+ * route, and an open string would let an arbitrary path be POSTed with a
+ * signed body.
+ */
+export type GaslessSubmitPath = keyof typeof GASLESS_SUBMIT_ROUTES;
+/**
+ * Everything needed to replay one gasless submit **byte-for-byte**, recovered
+ * from a `GASLESS_SUBMIT_UNCONFIRMED` error with
+ * {@link getGaslessUnconfirmedSubmit}.
+ *
+ * The vendor's contract is that resending the identical request under the same
+ * idempotency key either lands it or returns the record it already created, so
+ * a lost response is recoverable — but only if the exact JSON that was sent is
+ * still available. That is what this carries: `body` is the object that was
+ * serialized, not a rebuilt equivalent.
+ *
+ * Persist it next to the workflow you were submitting. Do **not** ship it to
+ * third-party logging: `body` holds the user's signed operations, and a
+ * signature the service never executed stays valid until its deadline.
+ */
+export interface GaslessUnconfirmedSubmit {
+    /** The chain the submit was made on. */
+    chainId: number;
+    /** The service that stores the workflow, derived from {@link GaslessUnconfirmedSubmit.path}. */
+    service: GaslessService;
+    /** The gateway path the body was POSTed to. */
+    path: GaslessSubmitPath;
+    /** The exact JSON body that was sent, to resend unchanged. */
+    body: unknown;
+    /** The idempotency key the submit carried, and that a resend must reuse. */
+    idempotencyKey: string;
+}
+/**
+ * The HTTP status an error reports, whatever error class carries it.
+ *
+ * Read structurally rather than through `instanceof SymmApiError`, so the
+ * gasless predicates keep working on the error a framework layer re-wrapped —
+ * `@symmio/trading-react`'s `SymmioRequestError` copies `status`,
+ * `responseData` and `code` off the API error and is what a hook consumer
+ * actually catches.
+ *
+ * @internal
+ */
+export declare function readGaslessErrorStatus(err: unknown): number | undefined;
+/** The SDK error code an error carries, read structurally. @internal */
+export declare function readGaslessErrorCode(err: unknown): string | undefined;
+/**
+ * Recover the replayable submit from a `GASLESS_SUBMIT_UNCONFIRMED` error.
+ *
+ * That error means the SDK could not establish whether the service accepted the
+ * request: the transport failed ambiguously and the same-key resend did not land
+ * either, however it was answered, or a `202` came back without a `request_id`.
+ * The relayed transaction may still execute, so the only safe recovery is to
+ * **resend the same bytes under the same key** with
+ * {@link resubmitGaslessRequest} — never to re-run the intent through the
+ * wallet.
+ *
+ * @param err - Anything caught from a gasless submit, including an error a
+ *   framework layer re-wrapped.
+ * @returns The replayable submit, or `null` when `err` is not an unconfirmed submit.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await relayInstantOperations(config, parameters);
+ * } catch (err) {
+ *   const submit = getGaslessUnconfirmedSubmit(err);
+ *   if (!submit) throw err;
+ *   await persistPendingSubmit(submit);
+ *   const receipt = await resubmitGaslessRequest(config, submit);
+ * }
+ * ```
+ */
+export declare function getGaslessUnconfirmedSubmit(err: unknown): GaslessUnconfirmedSubmit | null;
+/**
+ * Whether an error is the gateway's `409 IDEMPOTENCY_KEY_CONFLICT` — the key
+ * is already bound to a **different** wallet selection or workflow.
+ *
+ * It is a client bug, never a transport failure: the service refused to reuse
+ * the key for a payload that is not the one it first saw. Mint a fresh key for
+ * the new action; re-signing with the old key cannot succeed. It is also never
+ * grounds for a wallet-paid retry, because the workflow the key does belong to
+ * may still be executing.
+ *
+ * @param err - Anything caught from a gasless submit, including an error a
+ *   framework layer re-wrapped.
+ * @returns `true` only for that conflict.
+ *
+ * @example
+ * ```ts
+ * if (isGaslessIdempotencyConflictError(err)) {
+ *   // reconcile the workflow this key already created, then rebuild with a new key
+ * }
+ * ```
+ */
+export declare function isGaslessIdempotencyConflictError(err: unknown): boolean;
+//# sourceMappingURL=unconfirmed-submit.d.ts.map

package/dist/gasless/unconfirmed-submit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unconfirmed-submit.d.ts","sourceRoot":"","sources":["../../src/gasless/unconfirmed-submit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAK5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAI4C,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,qBAAqB,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,OAAO,EAAE,cAAc,CAAC;IACxB,+CAA+C;IAC/C,IAAI,EAAE,iBAAiB,CAAC;IACxB,8DAA8D;IAC9D,IAAI,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIvE;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,GAAG,IAAI,CAYzF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIvE"}

package/dist/gasless/unconfirmed-submit.js

@@ -0,0 +1,49 @@
+import { parseGaslessErrorDetail as e } from "./errors.js";
+//#region src/gasless/unconfirmed-submit.ts
+var t = "GASLESS_SUBMIT_UNCONFIRMED", n = "IDEMPOTENCY_KEY_CONFLICT", r = {
+	"/gateway/relay-instant": {
+		service: "operations",
+		code: "GASLESS_RELAY_SUBMIT_FAILED"
+	},
+	"/deposit-settlements/new-account": {
+		service: "deposits",
+		code: "GASLESS_SETTLEMENT_SUBMIT_FAILED"
+	},
+	"/deposit-settlements/existing-account": {
+		service: "deposits",
+		code: "GASLESS_SETTLEMENT_SUBMIT_FAILED"
+	}
+};
+function i(e) {
+	return typeof e == "object" && !!e && !Array.isArray(e);
+}
+function a(e) {
+	if (!i(e)) return;
+	let t = e.status;
+	return typeof t == "number" ? t : void 0;
+}
+function o(e) {
+	if (i(e)) return typeof e.code == "string" ? e.code : void 0;
+}
+function s(e) {
+	if (o(e) !== "GASLESS_SUBMIT_UNCONFIRMED") return null;
+	let t = i(e) ? e.responseData : void 0;
+	if (!i(t)) return null;
+	let { chainId: n, service: a, path: s, idempotencyKey: c } = t;
+	return typeof n != "number" || a !== "operations" && a !== "deposits" || typeof s != "string" || !(s in r) || typeof c != "string" || c.length === 0 ? null : {
+		chainId: n,
+		service: a,
+		path: s,
+		body: t.body,
+		idempotencyKey: c
+	};
+}
+function c(t) {
+	if (e(t)?.code !== n) return !1;
+	let r = a(t);
+	return r === void 0 || r === 409;
+}
+//#endregion
+export { r as GASLESS_SUBMIT_ROUTES, t as GASLESS_SUBMIT_UNCONFIRMED_CODE, s as getGaslessUnconfirmedSubmit, c as isGaslessIdempotencyConflictError, a as readGaslessErrorStatus };
+
+//# sourceMappingURL=unconfirmed-submit.js.map

package/dist/gasless/unconfirmed-submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unconfirmed-submit.js","names":[],"sources":["../../src/gasless/unconfirmed-submit.ts"],"sourcesContent":["import { parseGaslessErrorDetail } from \"./errors\";\nimport type { GaslessService } from \"./types\";\n\n/**\n * SDK error code of a submit whose outcome the SDK could not establish.\n *\n * @internal\n */\nexport const GASLESS_SUBMIT_UNCONFIRMED_CODE = \"GASLESS_SUBMIT_UNCONFIRMED\";\n\n/** Vendor code of a key already bound to a different wallet selection or workflow. */\nconst GASLESS_IDEMPOTENCY_CONFLICT_CODE = \"IDEMPOTENCY_KEY_CONFLICT\";\n\n/**\n * The gateway paths a gasless **submit** POSTs to, with the service that stores\n * the resulting workflow and the SDK error code its failures carry.\n *\n * A submit is the only kind of gasless request that can leave a side effect\n * behind when its response is lost, so the retry, idempotency and\n * \"unconfirmed\" machinery is keyed off this table rather than off a free-form\n * path string.\n *\n * @internal\n */\nexport const GASLESS_SUBMIT_ROUTES = {\n  \"/gateway/relay-instant\": { service: \"operations\", code: \"GASLESS_RELAY_SUBMIT_FAILED\" },\n  \"/deposit-settlements/new-account\": { service: \"deposits\", code: \"GASLESS_SETTLEMENT_SUBMIT_FAILED\" },\n  \"/deposit-settlements/existing-account\": { service: \"deposits\", code: \"GASLESS_SETTLEMENT_SUBMIT_FAILED\" },\n} as const satisfies Record<string, { service: GaslessService; code: string }>;\n\n/**\n * One of the three gateway paths a gasless submit POSTs to.\n *\n * Closed on purpose: a resubmit replays the recorded bytes against the same\n * route, and an open string would let an arbitrary path be POSTed with a\n * signed body.\n */\nexport type GaslessSubmitPath = keyof typeof GASLESS_SUBMIT_ROUTES;\n\n/**\n * Everything needed to replay one gasless submit **byte-for-byte**, recovered\n * from a `GASLESS_SUBMIT_UNCONFIRMED` error with\n * {@link getGaslessUnconfirmedSubmit}.\n *\n * The vendor's contract is that resending the identical request under the same\n * idempotency key either lands it or returns the record it already created, so\n * a lost response is recoverable — but only if the exact JSON that was sent is\n * still available. That is what this carries: `body` is the object that was\n * serialized, not a rebuilt equivalent.\n *\n * Persist it next to the workflow you were submitting. Do **not** ship it to\n * third-party logging: `body` holds the user's signed operations, and a\n * signature the service never executed stays valid until its deadline.\n */\nexport interface GaslessUnconfirmedSubmit {\n  /** The chain the submit was made on. */\n  chainId: number;\n  /** The service that stores the workflow, derived from {@link GaslessUnconfirmedSubmit.path}. */\n  service: GaslessService;\n  /** The gateway path the body was POSTed to. */\n  path: GaslessSubmitPath;\n  /** The exact JSON body that was sent, to resend unchanged. */\n  body: unknown;\n  /** The idempotency key the submit carried, and that a resend must reuse. */\n  idempotencyKey: string;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * The HTTP status an error reports, whatever error class carries it.\n *\n * Read structurally rather than through `instanceof SymmApiError`, so the\n * gasless predicates keep working on the error a framework layer re-wrapped —\n * `@symmio/trading-react`'s `SymmioRequestError` copies `status`,\n * `responseData` and `code` off the API error and is what a hook consumer\n * actually catches.\n *\n * @internal\n */\nexport function readGaslessErrorStatus(err: unknown): number | undefined {\n  if (!isRecord(err)) return undefined;\n  const status = err.status;\n  return typeof status === \"number\" ? status : undefined;\n}\n\n/** The SDK error code an error carries, read structurally. @internal */\nexport function readGaslessErrorCode(err: unknown): string | undefined {\n  if (!isRecord(err)) return undefined;\n  return typeof err.code === \"string\" ? err.code : undefined;\n}\n\n/**\n * Recover the replayable submit from a `GASLESS_SUBMIT_UNCONFIRMED` error.\n *\n * That error means the SDK could not establish whether the service accepted the\n * request: the transport failed ambiguously and the same-key resend did not land\n * either, however it was answered, or a `202` came back without a `request_id`.\n * The relayed transaction may still execute, so the only safe recovery is to\n * **resend the same bytes under the same key** with\n * {@link resubmitGaslessRequest} — never to re-run the intent through the\n * wallet.\n *\n * @param err - Anything caught from a gasless submit, including an error a\n *   framework layer re-wrapped.\n * @returns The replayable submit, or `null` when `err` is not an unconfirmed submit.\n *\n * @example\n * ```ts\n * try {\n *   await relayInstantOperations(config, parameters);\n * } catch (err) {\n *   const submit = getGaslessUnconfirmedSubmit(err);\n *   if (!submit) throw err;\n *   await persistPendingSubmit(submit);\n *   const receipt = await resubmitGaslessRequest(config, submit);\n * }\n * ```\n */\nexport function getGaslessUnconfirmedSubmit(err: unknown): GaslessUnconfirmedSubmit | null {\n  if (readGaslessErrorCode(err) !== GASLESS_SUBMIT_UNCONFIRMED_CODE) return null;\n  const data = isRecord(err) ? err.responseData : undefined;\n  if (!isRecord(data)) return null;\n\n  const { chainId, service, path, idempotencyKey } = data;\n  if (typeof chainId !== \"number\") return null;\n  if (service !== \"operations\" && service !== \"deposits\") return null;\n  if (typeof path !== \"string\" || !(path in GASLESS_SUBMIT_ROUTES)) return null;\n  if (typeof idempotencyKey !== \"string\" || idempotencyKey.length === 0) return null;\n\n  return { chainId, service, path: path as GaslessSubmitPath, body: data.body, idempotencyKey };\n}\n\n/**\n * Whether an error is the gateway's `409 IDEMPOTENCY_KEY_CONFLICT` — the key\n * is already bound to a **different** wallet selection or workflow.\n *\n * It is a client bug, never a transport failure: the service refused to reuse\n * the key for a payload that is not the one it first saw. Mint a fresh key for\n * the new action; re-signing with the old key cannot succeed. It is also never\n * grounds for a wallet-paid retry, because the workflow the key does belong to\n * may still be executing.\n *\n * @param err - Anything caught from a gasless submit, including an error a\n *   framework layer re-wrapped.\n * @returns `true` only for that conflict.\n *\n * @example\n * ```ts\n * if (isGaslessIdempotencyConflictError(err)) {\n *   // reconcile the workflow this key already created, then rebuild with a new key\n * }\n * ```\n */\nexport function isGaslessIdempotencyConflictError(err: unknown): boolean {\n  if (parseGaslessErrorDetail(err)?.code !== GASLESS_IDEMPOTENCY_CONFLICT_CODE) return false;\n  const status = readGaslessErrorStatus(err);\n  return status === undefined || status === 409;\n}\n"],"mappings":";;AAQA,IAAa,IAAkC,8BAGzC,IAAoC,4BAa7B,IAAwB;CACnC,0BAA0B;EAAE,SAAS;EAAc,MAAM;CAA8B;CACvF,oCAAoC;EAAE,SAAS;EAAY,MAAM;CAAmC;CACpG,yCAAyC;EAAE,SAAS;EAAY,MAAM;CAAmC;AAC3G;AAuCA,SAAS,EAAS,GAAkD;CAClE,OAAO,OAAO,KAAU,cAAY,KAAkB,CAAC,MAAM,QAAQ,CAAK;AAC5E;AAaA,SAAgB,EAAuB,GAAkC;CACvE,IAAI,CAAC,EAAS,CAAG,GAAG;CACpB,IAAM,IAAS,EAAI;CACnB,OAAO,OAAO,KAAW,WAAW,IAAS,KAAA;AAC/C;AAGA,SAAgB,EAAqB,GAAkC;CAChE,MAAS,CAAG,GACjB,OAAO,OAAO,EAAI,QAAS,WAAW,EAAI,OAAO,KAAA;AACnD;AA6BA,SAAgB,EAA4B,GAA+C;CACzF,IAAI,EAAqB,CAAG,MAAA,8BAAuC,OAAO;CAC1E,IAAM,IAAO,EAAS,CAAG,IAAI,EAAI,eAAe,KAAA;CAChD,IAAI,CAAC,EAAS,CAAI,GAAG,OAAO;CAE5B,IAAM,EAAE,YAAS,YAAS,SAAM,sBAAmB;CAMnD,OALI,OAAO,KAAY,YACnB,MAAY,gBAAgB,MAAY,cACxC,OAAO,KAAS,YAAY,EAAE,KAAQ,MACtC,OAAO,KAAmB,YAAY,EAAe,WAAW,IAAU,OAEvE;EAAE;EAAS;EAAe;EAA2B,MAAM,EAAK;EAAM;CAAe;AAC9F;AAuBA,SAAgB,EAAkC,GAAuB;CACvE,IAAI,EAAwB,CAAG,GAAG,SAAS,GAAmC,OAAO;CACrF,IAAM,IAAS,EAAuB,CAAG;CACzC,OAAO,MAAW,KAAA,KAAa,MAAW;AAC5C"}

package/dist/gasless/wait-for-gasless-request/index.d.ts

@@ -0,0 +1,2 @@
+export * from './wait-for-gasless-request.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gasless/wait-for-gasless-request/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/gasless/wait-for-gasless-request/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/gasless/wait-for-gasless-request/wait-for-gasless-request.d.ts

@@ -0,0 +1,114 @@
+import { Config } from '../../core/config/index.js';
+import { SymmError } from '../../shared/errors/symm-error.js';
+import { ChainIdParameter, Compute } from '../../shared/types/properties.js';
+import { GaslessStatusTransport } from '../observe-gasless-request.js';
+import { GaslessRequest, GaslessService } from '../types.js';
+/** Default overall wait budget. */
+export declare const GASLESS_WAIT_TIMEOUT_MS = 120000;
+/**
+ * Parameters for {@link waitForGaslessRequest}.
+ */
+export type WaitForGaslessRequestParameters = Compute<ChainIdParameter & {
+    /** Stable service tracking id returned by a gasless submit. */
+    requestId: string;
+    /** Which sub-service stores the request. Defaults to `"operations"`. */
+    service?: GaslessService;
+    /**
+     * When to resolve. `"broadcast"` resolves as soon as a transaction hash
+     * exists (status `submitted`, or a terminal that carries one);
+     * `"terminal"` (default) waits for `succeeded` / `reverted` / `failed` /
+     * `rejected`.
+     */
+    until?: "broadcast" | "terminal";
+    /** Overall wait budget in ms. Default {@link GASLESS_WAIT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Poll cadence while `queued`. Default {@link GASLESS_QUEUED_POLL_MS}. */
+    queuedPollMs?: number;
+    /** Poll cadence after `submitted`. Default {@link GASLESS_SUBMITTED_POLL_MS}. */
+    submittedPollMs?: number;
+    /**
+     * How long to let the stream settle before the first HTTP read. Ends early
+     * the moment the stream delivers, or reports that it will not. Ignored
+     * under `transport: "poll"`. Default {@link GASLESS_STREAM_SETTLE_MS}.
+     */
+    streamSettleMs?: number;
+    /**
+     * How long a delivering stream may report nothing about the workflow before
+     * one HTTP read is taken anyway. Default {@link GASLESS_STREAM_STALE_MS}.
+     */
+    streamStaleMs?: number;
+    /** Abort the wait (e.g. on unmount). The request itself keeps running server-side. */
+    signal?: AbortSignal;
+    /** Observer invoked with every fetched record, including the final one. */
+    onUpdate?: (request: GaslessRequest) => void;
+    /**
+     * Observer invoked for every transient read failure the loop absorbed —
+     * a `429`, a `503`, a dropped connection.
+     *
+     * Nothing is wrong with the workflow when this fires; only our view of it
+     * is stale. Surface it as "status unavailable, still running", never as a
+     * failed relay, and never as a reason to resubmit.
+     */
+    onTransportIssue?: (error: SymmError) => void;
+    /**
+     * How to follow the workflow. `"auto"` (default) subscribes to the
+     * gateway's status stream when the deployment enables it and polls only
+     * while the stream is not delivering; `"poll"` forces HTTP polling.
+     *
+     * The outcome is identical either way — the stream carries the same records
+     * the reads return, so a caller cannot tell which transport produced one.
+     */
+    transport?: GaslessStatusTransport;
+}>;
+/** Return type of {@link waitForGaslessRequest}. */
+export type WaitForGaslessRequestReturnType = GaslessRequest;
+/**
+ * Poll one gasless request until it broadcasts or reaches a terminal status.
+ *
+ * The relayer is fire-and-forget, so this loop is the client's half of the
+ * lifecycle. It resolves with the record — including for `reverted` / `failed`
+ * / `rejected` terminals, which are workflow outcomes, not transport failures;
+ * branch on `status` (only `succeeded` is success).
+ *
+ * **The stream leads; HTTP is the fallback.** Where the deployment serves a
+ * status stream, the wait subscribes and gives it `streamSettleMs` to deliver
+ * before reading over HTTP at all, so a healthy workflow costs no status reads.
+ * Polling resumes the moment the stream stops delivering, and one read is taken
+ * anyway whenever a live stream has said nothing about the workflow for
+ * `streamStaleMs` — a heartbeat proves the socket is alive, not that this
+ * workflow is being reported.
+ *
+ * **A failed read is not a failed request.** Once a `202` exists the workflow
+ * is running whether or not we can see it, so every transient transport
+ * failure — a dropped connection, a `408`, a `429`, a `5xx` — is absorbed:
+ * reported through `onTransportIssue`, then retried after
+ * `max(Retry-After, jittered 1 s → 30 s backoff)`, capped by whatever budget is
+ * left. Up to three consecutive `404`s are tolerated too, for the brief
+ * accept-vs-record race after a submit.
+ *
+ * It throws only when it can no longer answer the question it was asked: the
+ * budget ran out, the caller aborted, the record is still `404` on the fourth
+ * consecutive read, or the service gave a definitive answer (`401`, `403`,
+ * `422`, a service error code). A timeout carries the last transient failure as
+ * its `cause`, so a caller can tell "the relayer is slow" from "we went blind".
+ *
+ * @param config - The SDK config.
+ * @param parameters - Request id, wait target, cadence, budget, abort signal.
+ * @returns The record at broadcast (`until: "broadcast"`) or at terminal.
+ * @throws {SymmError} `GASLESS_BROADCAST_TIMEOUT` / `GASLESS_TERMINAL_TIMEOUT`
+ *   when the budget runs out — the request may still land later; keep the
+ *   `requestId` and keep watching, never re-submit through the wallet.
+ * @throws {SymmError} `GASLESS_WAIT_ABORTED` when `signal` aborts.
+ *
+ * @example
+ * ```ts
+ * const record = await waitForGaslessRequest(config, {
+ *   requestId,
+ *   until: "broadcast",
+ *   onTransportIssue: () => setDegraded(true),
+ * });
+ * if (record.txHash) await client.waitForTransactionReceipt({ hash: record.txHash });
+ * ```
+ */
+export declare function waitForGaslessRequest(config: Config, parameters: WaitForGaslessRequestParameters): Promise<WaitForGaslessRequestReturnType>;
+//# sourceMappingURL=wait-for-gasless-request.d.ts.map

package/dist/gasless/wait-for-gasless-request/wait-for-gasless-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-gasless-request.d.ts","sourceRoot":"","sources":["../../../src/gasless/wait-for-gasless-request/wait-for-gasless-request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAgB,SAAS,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAG/E,OAAO,EAA+B,KAAK,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAGtG,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAElB,mCAAmC;AACnC,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAO/C;;GAEG;AACH,MAAM,MAAM,+BAA+B,GAAG,OAAO,CACnD,gBAAgB,GAAG;IACjB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;IACjC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAC7C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC9C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC,CACF,CAAC;AAEF,oDAAoD;AACpD,MAAM,MAAM,+BAA+B,GAAG,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,+BAA+B,GAC1C,OAAO,CAAC,+BAA+B,CAAC,CA8J1C"}

package/dist/gasless/wait-for-gasless-request/wait-for-gasless-request.js

@@ -0,0 +1,77 @@
+import { SymmApiError as e, SymmError as t } from "../../shared/errors/symm-error.js";
+import { resolveGaslessService as n } from "../resolve-gasless.js";
+import { GaslessRequestStatus as r, isGaslessRequestTerminal as i } from "../types.js";
+import { gaslessSleep as a } from "../abortable-sleep.js";
+import { getGaslessRequest as o } from "../get-gasless-request/get-gasless-request.js";
+import { createGaslessStatusObserver as s } from "../observe-gasless-request.js";
+import { gaslessTransientReadDelay as c, isTransientGaslessReadError as l } from "../transient-read.js";
+//#region src/gasless/wait-for-gasless-request/wait-for-gasless-request.ts
+var u = 12e4, d = 3;
+async function f(n, f) {
+	let { chainId: m, requestId: h, service: g = "operations", until: _ = "terminal", timeoutMs: v = u, signal: y, onUpdate: b, onTransportIssue: x, transport: S = "auto" } = f, C = p(n, m), w = f.queuedPollMs ?? C.queuedPollMs ?? 1500, T = f.submittedPollMs ?? C.submittedPollMs ?? 3e3, E = f.streamSettleMs ?? C.streamSettleMs ?? 1e3, D = f.streamStaleMs ?? C.streamStaleMs ?? 15e3, O = Date.now() + v, k = S === "poll" ? null : s(n, {
+		chainId: m,
+		requestId: h,
+		service: g,
+		onTransportIssue: x
+	}), A = Date.now() + E, j = 0, M = 0, N, P = null, F = Date.now();
+	try {
+		for (;;) {
+			if (y?.aborted) throw new t("api", "GASLESS_WAIT_ABORTED", "Gasless: the status wait was aborted.");
+			let s = k?.take() ?? null;
+			if (s && (P = s, j = 0, M = 0, F = Date.now(), b?.(P), _ === "broadcast" && P.txHash !== null || i(P.status))) return P;
+			let u = P?.status === r.SUBMITTED ? T : w;
+			if (k) {
+				let e = k.state();
+				if (e === "live" && Date.now() - F < D) {
+					let e = O - Date.now();
+					if (e <= 0) throw I();
+					await k.wait(Math.min(u, e), y);
+					continue;
+				}
+				if (e === "pending" && Date.now() < A) {
+					let e = O - Date.now();
+					if (e <= 0) throw I();
+					await k.wait(Math.min(A - Date.now(), e), y);
+					continue;
+				}
+			}
+			try {
+				if (P = await o(n, {
+					chainId: m,
+					requestId: h,
+					service: g,
+					signal: y
+				}), j = 0, M = 0, F = Date.now(), b?.(P), _ === "broadcast" && P.txHash !== null || i(P.status)) return P;
+				u = P.status === r.SUBMITTED ? T : w;
+			} catch (n) {
+				if (y?.aborted) throw new t("api", "GASLESS_WAIT_ABORTED", "Gasless: the status wait was aborted.");
+				if (n instanceof e && n.status === 404) {
+					if (++j > d) throw n;
+				} else if (l(n)) {
+					if (N = n instanceof t ? n : void 0, u = c(M++, n), N) try {
+						x?.(N);
+					} catch {}
+				} else throw n;
+			}
+			let f = O - Date.now();
+			if (f <= 0) throw I();
+			await a(Math.min(u, f), y);
+		}
+	} finally {
+		k?.close();
+	}
+	function I() {
+		return new t("api", _ === "broadcast" ? "GASLESS_BROADCAST_TIMEOUT" : "GASLESS_TERMINAL_TIMEOUT", `Gasless: request ${h} did not reach ${_ === "broadcast" ? "broadcast" : "a terminal status"} within ${v} ms (last status: ${P?.status ?? "unknown"}). The request keeps running server-side — keep polling it; never re-submit through the wallet.`, { cause: N });
+	}
+}
+function p(e, t) {
+	try {
+		return n(e, { chainId: t }).execution ?? {};
+	} catch {
+		return {};
+	}
+}
+//#endregion
+export { u as GASLESS_WAIT_TIMEOUT_MS, f as waitForGaslessRequest };
+
+//# sourceMappingURL=wait-for-gasless-request.js.map

package/dist/gasless/wait-for-gasless-request/wait-for-gasless-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-gasless-request.js","names":[],"sources":["../../../src/gasless/wait-for-gasless-request/wait-for-gasless-request.ts"],"sourcesContent":["import type { GaslessExecutionConfig } from \"../../core/chains/types\";\nimport type { Config } from \"../../core/config\";\nimport { SymmApiError, SymmError } from \"../../shared/errors/symm-error\";\nimport type { ChainIdParameter, Compute } from \"../../shared/types/properties\";\nimport { gaslessSleep } from \"../abortable-sleep\";\nimport { getGaslessRequest } from \"../get-gasless-request/get-gasless-request\";\nimport { createGaslessStatusObserver, type GaslessStatusTransport } from \"../observe-gasless-request\";\nimport { resolveGaslessService } from \"../resolve-gasless\";\nimport { gaslessTransientReadDelay, isTransientGaslessReadError } from \"../transient-read\";\nimport {\n  GASLESS_QUEUED_POLL_MS,\n  GASLESS_STREAM_SETTLE_MS,\n  GASLESS_STREAM_STALE_MS,\n  GASLESS_SUBMITTED_POLL_MS,\n  GaslessRequestStatus,\n  isGaslessRequestTerminal,\n  type GaslessRequest,\n  type GaslessService,\n} from \"../types\";\n\n/** Default overall wait budget. */\nexport const GASLESS_WAIT_TIMEOUT_MS = 120_000;\n/**\n * Consecutive `404`s tolerated right after a `202`: the accepted workflow's\n * record may not be readable immediately (the accept-vs-record race).\n */\nconst NOT_FOUND_TOLERANCE = 3;\n\n/**\n * Parameters for {@link waitForGaslessRequest}.\n */\nexport type WaitForGaslessRequestParameters = Compute<\n  ChainIdParameter & {\n    /** Stable service tracking id returned by a gasless submit. */\n    requestId: string;\n    /** Which sub-service stores the request. Defaults to `\"operations\"`. */\n    service?: GaslessService;\n    /**\n     * When to resolve. `\"broadcast\"` resolves as soon as a transaction hash\n     * exists (status `submitted`, or a terminal that carries one);\n     * `\"terminal\"` (default) waits for `succeeded` / `reverted` / `failed` /\n     * `rejected`.\n     */\n    until?: \"broadcast\" | \"terminal\";\n    /** Overall wait budget in ms. Default {@link GASLESS_WAIT_TIMEOUT_MS}. */\n    timeoutMs?: number;\n    /** Poll cadence while `queued`. Default {@link GASLESS_QUEUED_POLL_MS}. */\n    queuedPollMs?: number;\n    /** Poll cadence after `submitted`. Default {@link GASLESS_SUBMITTED_POLL_MS}. */\n    submittedPollMs?: number;\n    /**\n     * How long to let the stream settle before the first HTTP read. Ends early\n     * the moment the stream delivers, or reports that it will not. Ignored\n     * under `transport: \"poll\"`. Default {@link GASLESS_STREAM_SETTLE_MS}.\n     */\n    streamSettleMs?: number;\n    /**\n     * How long a delivering stream may report nothing about the workflow before\n     * one HTTP read is taken anyway. Default {@link GASLESS_STREAM_STALE_MS}.\n     */\n    streamStaleMs?: number;\n    /** Abort the wait (e.g. on unmount). The request itself keeps running server-side. */\n    signal?: AbortSignal;\n    /** Observer invoked with every fetched record, including the final one. */\n    onUpdate?: (request: GaslessRequest) => void;\n    /**\n     * Observer invoked for every transient read failure the loop absorbed —\n     * a `429`, a `503`, a dropped connection.\n     *\n     * Nothing is wrong with the workflow when this fires; only our view of it\n     * is stale. Surface it as \"status unavailable, still running\", never as a\n     * failed relay, and never as a reason to resubmit.\n     */\n    onTransportIssue?: (error: SymmError) => void;\n    /**\n     * How to follow the workflow. `\"auto\"` (default) subscribes to the\n     * gateway's status stream when the deployment enables it and polls only\n     * while the stream is not delivering; `\"poll\"` forces HTTP polling.\n     *\n     * The outcome is identical either way — the stream carries the same records\n     * the reads return, so a caller cannot tell which transport produced one.\n     */\n    transport?: GaslessStatusTransport;\n  }\n>;\n\n/** Return type of {@link waitForGaslessRequest}. */\nexport type WaitForGaslessRequestReturnType = GaslessRequest;\n\n/**\n * Poll one gasless request until it broadcasts or reaches a terminal status.\n *\n * The relayer is fire-and-forget, so this loop is the client's half of the\n * lifecycle. It resolves with the record — including for `reverted` / `failed`\n * / `rejected` terminals, which are workflow outcomes, not transport failures;\n * branch on `status` (only `succeeded` is success).\n *\n * **The stream leads; HTTP is the fallback.** Where the deployment serves a\n * status stream, the wait subscribes and gives it `streamSettleMs` to deliver\n * before reading over HTTP at all, so a healthy workflow costs no status reads.\n * Polling resumes the moment the stream stops delivering, and one read is taken\n * anyway whenever a live stream has said nothing about the workflow for\n * `streamStaleMs` — a heartbeat proves the socket is alive, not that this\n * workflow is being reported.\n *\n * **A failed read is not a failed request.** Once a `202` exists the workflow\n * is running whether or not we can see it, so every transient transport\n * failure — a dropped connection, a `408`, a `429`, a `5xx` — is absorbed:\n * reported through `onTransportIssue`, then retried after\n * `max(Retry-After, jittered 1 s → 30 s backoff)`, capped by whatever budget is\n * left. Up to three consecutive `404`s are tolerated too, for the brief\n * accept-vs-record race after a submit.\n *\n * It throws only when it can no longer answer the question it was asked: the\n * budget ran out, the caller aborted, the record is still `404` on the fourth\n * consecutive read, or the service gave a definitive answer (`401`, `403`,\n * `422`, a service error code). A timeout carries the last transient failure as\n * its `cause`, so a caller can tell \"the relayer is slow\" from \"we went blind\".\n *\n * @param config - The SDK config.\n * @param parameters - Request id, wait target, cadence, budget, abort signal.\n * @returns The record at broadcast (`until: \"broadcast\"`) or at terminal.\n * @throws {SymmError} `GASLESS_BROADCAST_TIMEOUT` / `GASLESS_TERMINAL_TIMEOUT`\n *   when the budget runs out — the request may still land later; keep the\n *   `requestId` and keep watching, never re-submit through the wallet.\n * @throws {SymmError} `GASLESS_WAIT_ABORTED` when `signal` aborts.\n *\n * @example\n * ```ts\n * const record = await waitForGaslessRequest(config, {\n *   requestId,\n *   until: \"broadcast\",\n *   onTransportIssue: () => setDegraded(true),\n * });\n * if (record.txHash) await client.waitForTransactionReceipt({ hash: record.txHash });\n * ```\n */\nexport async function waitForGaslessRequest(\n  config: Config,\n  parameters: WaitForGaslessRequestParameters,\n): Promise<WaitForGaslessRequestReturnType> {\n  const {\n    chainId,\n    requestId,\n    service = \"operations\",\n    until = \"terminal\",\n    timeoutMs = GASLESS_WAIT_TIMEOUT_MS,\n    signal,\n    onUpdate,\n    onTransportIssue,\n    transport = \"auto\",\n  } = parameters;\n\n  /**\n   * Cadence and stream windows fall back to the deployment's `execution` block\n   * before the constants, so a gateway's own tuning reaches every wait —\n   * including the ones a caller only reaches indirectly, like the write tail's\n   * `confirmGaslessRequest`.\n   */\n  const execution = resolveWaitDefaults(config, chainId);\n  const queuedPollMs = parameters.queuedPollMs ?? execution.queuedPollMs ?? GASLESS_QUEUED_POLL_MS;\n  const submittedPollMs = parameters.submittedPollMs ?? execution.submittedPollMs ?? GASLESS_SUBMITTED_POLL_MS;\n  const streamSettleMs = parameters.streamSettleMs ?? execution.streamSettleMs ?? GASLESS_STREAM_SETTLE_MS;\n  const streamStaleMs = parameters.streamStaleMs ?? execution.streamStaleMs ?? GASLESS_STREAM_STALE_MS;\n\n  const deadline = Date.now() + timeoutMs;\n  /**\n   * The status stream, when this deployment has one. It delivers the same\n   * records the reads return, so the loop below prefers it and polls only while\n   * it is not delivering.\n   */\n  const observer =\n    transport === \"poll\"\n      ? null\n      : createGaslessStatusObserver(config, { chainId, requestId, service, onTransportIssue });\n  /**\n   * How long the stream has to answer before the first read. Fixed at the\n   * start, so this is a settle window and not a licence to stall: a stream that\n   * drops later sends the loop straight back to polling.\n   */\n  const settleUntil = Date.now() + streamSettleMs;\n  let notFoundStreak = 0;\n  let transientStreak = 0;\n  let lastTransient: SymmError | undefined;\n  let latest: GaslessRequest | null = null;\n  /** When the workflow was last seen over either transport — the stale backstop's clock. */\n  let lastRecordAt = Date.now();\n\n  try {\n    for (;;) {\n      if (signal?.aborted) {\n        throw new SymmError(\"api\", \"GASLESS_WAIT_ABORTED\", \"Gasless: the status wait was aborted.\");\n      }\n\n      /**\n       * Take a delivered record before reading the stream's health: one that\n       * landed just before the socket dropped is still the freshest thing we\n       * have, and discarding it would re-read what we were already told.\n       */\n      const streamed = observer?.take() ?? null;\n      if (streamed) {\n        latest = streamed;\n        notFoundStreak = 0;\n        transientStreak = 0;\n        lastRecordAt = Date.now();\n        onUpdate?.(latest);\n        if (until === \"broadcast\" && latest.txHash !== null) return latest;\n        if (isGaslessRequestTerminal(latest.status)) return latest;\n      }\n\n      /** The next poll's delay: the status cadence, or a backoff after a transient failure. */\n      let interval = latest?.status === GaslessRequestStatus.SUBMITTED ? submittedPollMs : queuedPollMs;\n\n      if (observer) {\n        const state = observer.state();\n        /**\n         * While the stream carries this workflow the poll stands down — unless\n         * it has carried nothing for `streamStaleMs`. Heartbeats keep the socket\n         * alive without saying anything about the workflow, so silence that long\n         * is settled with one read rather than trusted until the socket's own\n         * liveness timer fires.\n         */\n        if (state === \"live\" && Date.now() - lastRecordAt < streamStaleMs) {\n          const remainingWhileLive = deadline - Date.now();\n          if (remainingWhileLive <= 0) throw timeoutError();\n          await observer.wait(Math.min(interval, remainingWhileLive), signal);\n          continue;\n        }\n        /**\n         * Still settling: the subscription's first record is on its way and\n         * carries exactly what the read below would. Waiting for it costs one\n         * request fewer than racing it, and the wait ends the moment the stream\n         * delivers or reports that it cannot.\n         */\n        if (state === \"pending\" && Date.now() < settleUntil) {\n          const remainingWhileSettling = deadline - Date.now();\n          if (remainingWhileSettling <= 0) throw timeoutError();\n          await observer.wait(Math.min(settleUntil - Date.now(), remainingWhileSettling), signal);\n          continue;\n        }\n      }\n\n      try {\n        latest = await getGaslessRequest(config, { chainId, requestId, service, signal });\n        notFoundStreak = 0;\n        transientStreak = 0;\n        lastRecordAt = Date.now();\n        onUpdate?.(latest);\n\n        if (until === \"broadcast\" && latest.txHash !== null) return latest;\n        if (isGaslessRequestTerminal(latest.status)) return latest;\n        interval = latest.status === GaslessRequestStatus.SUBMITTED ? submittedPollMs : queuedPollMs;\n      } catch (err) {\n        /** An abort cancels the read in flight; that cancellation is not a transport issue. */\n        if (signal?.aborted) {\n          throw new SymmError(\"api\", \"GASLESS_WAIT_ABORTED\", \"Gasless: the status wait was aborted.\");\n        }\n        const isNotFound = err instanceof SymmApiError && err.status === 404;\n        if (isNotFound) {\n          if (++notFoundStreak > NOT_FOUND_TOLERANCE) throw err;\n        } else if (isTransientGaslessReadError(err)) {\n          /**\n           * The workflow is running whether or not we can read it. Report the\n           * blind spot and back off — treating this as a failure is what makes a\n           * caller resubmit an intent that is already executing.\n           */\n          lastTransient = err instanceof SymmError ? err : undefined;\n          interval = gaslessTransientReadDelay(transientStreak++, err);\n          if (lastTransient) {\n            try {\n              onTransportIssue?.(lastTransient);\n            } catch {\n              /** An observer must never break the wait it is observing. */\n            }\n          }\n        } else {\n          throw err;\n        }\n      }\n\n      const remaining = deadline - Date.now();\n      if (remaining <= 0) throw timeoutError();\n\n      /** Never sleep past the budget: a 30 s backoff must not hide a 5 s timeout. */\n      await gaslessSleep(Math.min(interval, remaining), signal);\n    }\n  } finally {\n    observer?.close();\n  }\n\n  function timeoutError(): SymmError {\n    return new SymmError(\n      \"api\",\n      until === \"broadcast\" ? \"GASLESS_BROADCAST_TIMEOUT\" : \"GASLESS_TERMINAL_TIMEOUT\",\n      `Gasless: request ${requestId} did not reach ${until === \"broadcast\" ? \"broadcast\" : \"a terminal status\"} within ${timeoutMs} ms (last status: ${latest?.status ?? \"unknown\"}). The request keeps running server-side — keep polling it; never re-submit through the wallet.`,\n      { cause: lastTransient },\n    );\n  }\n}\n\n/**\n * The deployment's execution defaults for a wait, or none.\n *\n * A wait may run for a chain with no gasless block at all — a caller holding a\n * request id from another chain, a config whose gasless service was never\n * declared — and a missing deployment is not a reason to fail a wait that the\n * constants can serve.\n */\nfunction resolveWaitDefaults(config: Config, chainId?: number): GaslessExecutionConfig {\n  try {\n    return resolveGaslessService(config, { chainId }).execution ?? {};\n  } catch {\n    return {};\n  }\n}\n"],"mappings":";;;;;;;;AAqBA,IAAa,IAA0B,MAKjC,IAAsB;AA+G5B,eAAsB,EACpB,GACA,GAC0C;CAC1C,IAAM,EACJ,YACA,cACA,aAAU,cACV,WAAQ,YACR,eAAY,GACZ,WACA,aACA,qBACA,eAAY,WACV,GAQE,IAAY,EAAoB,GAAQ,CAAO,GAC/C,IAAe,EAAW,gBAAgB,EAAU,gBAAA,MACpD,IAAkB,EAAW,mBAAmB,EAAU,mBAAA,KAC1D,IAAiB,EAAW,kBAAkB,EAAU,kBAAA,KACxD,IAAgB,EAAW,iBAAiB,EAAU,iBAAA,MAEtD,IAAW,KAAK,IAAI,IAAI,GAMxB,IACJ,MAAc,SACV,OACA,EAA4B,GAAQ;EAAE;EAAS;EAAW;EAAS;CAAiB,CAAC,GAMrF,IAAc,KAAK,IAAI,IAAI,GAC7B,IAAiB,GACjB,IAAkB,GAClB,GACA,IAAgC,MAEhC,IAAe,KAAK,IAAI;CAE5B,IAAI;EACF,SAAS;GACP,IAAI,GAAQ,SACV,MAAM,IAAI,EAAU,OAAO,wBAAwB,uCAAuC;GAQ5F,IAAM,IAAW,GAAU,KAAK,KAAK;GACrC,IAAI,MACF,IAAS,GACT,IAAiB,GACjB,IAAkB,GAClB,IAAe,KAAK,IAAI,GACxB,IAAW,CAAM,GACb,MAAU,eAAe,EAAO,WAAW,QAC3C,EAAyB,EAAO,MAAM,IAAG,OAAO;GAItD,IAAI,IAAW,GAAQ,WAAW,EAAqB,YAAY,IAAkB;GAErF,IAAI,GAAU;IACZ,IAAM,IAAQ,EAAS,MAAM;IAQ7B,IAAI,MAAU,UAAU,KAAK,IAAI,IAAI,IAAe,GAAe;KACjE,IAAM,IAAqB,IAAW,KAAK,IAAI;KAC/C,IAAI,KAAsB,GAAG,MAAM,EAAa;KAChD,MAAM,EAAS,KAAK,KAAK,IAAI,GAAU,CAAkB,GAAG,CAAM;KAClE;IACF;IAOA,IAAI,MAAU,aAAa,KAAK,IAAI,IAAI,GAAa;KACnD,IAAM,IAAyB,IAAW,KAAK,IAAI;KACnD,IAAI,KAA0B,GAAG,MAAM,EAAa;KACpD,MAAM,EAAS,KAAK,KAAK,IAAI,IAAc,KAAK,IAAI,GAAG,CAAsB,GAAG,CAAM;KACtF;IACF;GACF;GAEA,IAAI;IAQF,IAPA,IAAS,MAAM,EAAkB,GAAQ;KAAE;KAAS;KAAW;KAAS;IAAO,CAAC,GAChF,IAAiB,GACjB,IAAkB,GAClB,IAAe,KAAK,IAAI,GACxB,IAAW,CAAM,GAEb,MAAU,eAAe,EAAO,WAAW,QAC3C,EAAyB,EAAO,MAAM,GAAG,OAAO;IACpD,IAAW,EAAO,WAAW,EAAqB,YAAY,IAAkB;GAClF,SAAS,GAAK;IAEZ,IAAI,GAAQ,SACV,MAAM,IAAI,EAAU,OAAO,wBAAwB,uCAAuC;IAG5F,IADmB,aAAe,KAAgB,EAAI,WAAW;SAE3D,EAAE,IAAiB,GAAqB,MAAM;IAAA,OAC7C,IAAI,EAA4B,CAAG,GAQxC;SAFA,IAAgB,aAAe,IAAY,IAAM,KAAA,GACjD,IAAW,EAA0B,KAAmB,CAAG,GACvD,GACF,IAAI;MACF,IAAmB,CAAa;KAClC,QAAQ,CAER;WAGF,MAAM;GAEV;GAEA,IAAM,IAAY,IAAW,KAAK,IAAI;GACtC,IAAI,KAAa,GAAG,MAAM,EAAa;GAGvC,MAAM,EAAa,KAAK,IAAI,GAAU,CAAS,GAAG,CAAM;EAC1D;CACF,UAAU;EACR,GAAU,MAAM;CAClB;CAEA,SAAS,IAA0B;EACjC,OAAO,IAAI,EACT,OACA,MAAU,cAAc,8BAA8B,4BACtD,oBAAoB,EAAU,iBAAiB,MAAU,cAAc,cAAc,oBAAoB,UAAU,EAAU,oBAAoB,GAAQ,UAAU,UAAU,kGAC7K,EAAE,OAAO,EAAc,CACzB;CACF;AACF;AAUA,SAAS,EAAoB,GAAgB,GAA0C;CACrF,IAAI;EACF,OAAO,EAAsB,GAAQ,EAAE,WAAQ,CAAC,EAAE,aAAa,CAAC;CAClE,QAAQ;EACN,OAAO,CAAC;CACV;AACF"}

package/dist/gasless/wallet-id.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Validate a GaslessWallet id before it reaches an RPC call or a request body.
+ *
+ * Wallet ids are `uint256`: the GaslessLayer and the service accept `0` through
+ * `2^256 - 1`. JavaScript `number`s are rejected outright rather than coerced,
+ * because an id above `Number.MAX_SAFE_INTEGER` would silently lose precision.
+ *
+ * @param walletId - The candidate id.
+ * @param label - How the id is named in the error message.
+ * @returns The id, unchanged.
+ * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for a non-bigint or an out-of-range value.
+ *
+ * @internal
+ */
+export declare function assertGaslessWalletId(walletId: bigint, label?: string): bigint;
+/**
+ * Encode a wallet id for a GasLessQ JSON body: a decimal string, never a
+ * number, per the service's JSON rules.
+ *
+ * @param walletId - The id to encode.
+ * @returns The id as a decimal string, e.g. `"2"`.
+ * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for a non-bigint or an out-of-range value.
+ *
+ * @internal
+ */
+export declare function toGaslessWalletIdWire(walletId: bigint): string;
+/**
+ * Strictly parse a wallet id the service returned (`wallet_id`,
+ * `payload.wallet_ids[]`): a `bigint`, or a decimal string in range. Negative,
+ * fractional, boolean, hex, numeric and overflowing values are rejected, mirroring
+ * the service's own validation. A missing id is the caller's concern — historical
+ * records omit it and mean wallet `0`.
+ *
+ * @param value - The raw value.
+ * @param label - How the id is named in the error message.
+ * @returns The id as a `bigint`.
+ * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for anything else.
+ *
+ * @internal
+ */
+export declare function parseGaslessWalletId(value: unknown, label?: string): bigint;
+//# sourceMappingURL=wallet-id.d.ts.map

package/dist/gasless/wallet-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-id.d.ts","sourceRoot":"","sources":["../../src/gasless/wallet-id.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,CAGlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAa,GAAG,MAAM,CAM/E"}

package/dist/gasless/wallet-id.js

@@ -0,0 +1,25 @@
+import { SymmError as e } from "../shared/errors/symm-error.js";
+import { maxUint256 as t } from "viem";
+//#region src/gasless/wallet-id.ts
+var n = /^[0-9]+$/;
+function r(t, n) {
+	return new e("validation", "GASLESS_WALLET_ID_INVALID", `Gasless: ${n} ${typeof t == "bigint" ? `${t}n` : JSON.stringify(t) ?? String(t)} is not a valid wallet id — expected a bigint (or a decimal string on the wire) from 0 through 2^256 - 1.`);
+}
+function i(e, n = "walletId") {
+	if (typeof e != "bigint" || e < 0n || e > t) throw r(e, n);
+	return e;
+}
+function a(e) {
+	return i(e).toString();
+}
+function o(e, a = "walletId") {
+	if (typeof e == "bigint") return i(e, a);
+	if (typeof e != "string" || !n.test(e)) throw r(e, a);
+	let o = BigInt(e);
+	if (o > t) throw r(e, a);
+	return o;
+}
+//#endregion
+export { i as assertGaslessWalletId, o as parseGaslessWalletId, a as toGaslessWalletIdWire };
+
+//# sourceMappingURL=wallet-id.js.map

package/dist/gasless/wallet-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-id.js","names":[],"sources":["../../src/gasless/wallet-id.ts"],"sourcesContent":["import { maxUint256 } from \"viem\";\nimport { SymmError } from \"../shared/errors/symm-error\";\n\n/** A canonical unsigned decimal: digits only — no sign, whitespace, exponent, fraction, or `0x` prefix. */\nconst DECIMAL_WALLET_ID = /^[0-9]+$/;\n\nfunction invalidWalletId(value: unknown, label: string): SymmError {\n  const shown = typeof value === \"bigint\" ? `${value}n` : (JSON.stringify(value) ?? String(value));\n  return new SymmError(\n    \"validation\",\n    \"GASLESS_WALLET_ID_INVALID\",\n    `Gasless: ${label} ${shown} is not a valid wallet id — expected a bigint (or a decimal string on the wire) from 0 through 2^256 - 1.`,\n  );\n}\n\n/**\n * Validate a GaslessWallet id before it reaches an RPC call or a request body.\n *\n * Wallet ids are `uint256`: the GaslessLayer and the service accept `0` through\n * `2^256 - 1`. JavaScript `number`s are rejected outright rather than coerced,\n * because an id above `Number.MAX_SAFE_INTEGER` would silently lose precision.\n *\n * @param walletId - The candidate id.\n * @param label - How the id is named in the error message.\n * @returns The id, unchanged.\n * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for a non-bigint or an out-of-range value.\n *\n * @internal\n */\nexport function assertGaslessWalletId(walletId: bigint, label = \"walletId\"): bigint {\n  if (typeof walletId !== \"bigint\" || walletId < 0n || walletId > maxUint256) throw invalidWalletId(walletId, label);\n  return walletId;\n}\n\n/**\n * Encode a wallet id for a GasLessQ JSON body: a decimal string, never a\n * number, per the service's JSON rules.\n *\n * @param walletId - The id to encode.\n * @returns The id as a decimal string, e.g. `\"2\"`.\n * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for a non-bigint or an out-of-range value.\n *\n * @internal\n */\nexport function toGaslessWalletIdWire(walletId: bigint): string {\n  return assertGaslessWalletId(walletId).toString();\n}\n\n/**\n * Strictly parse a wallet id the service returned (`wallet_id`,\n * `payload.wallet_ids[]`): a `bigint`, or a decimal string in range. Negative,\n * fractional, boolean, hex, numeric and overflowing values are rejected, mirroring\n * the service's own validation. A missing id is the caller's concern — historical\n * records omit it and mean wallet `0`.\n *\n * @param value - The raw value.\n * @param label - How the id is named in the error message.\n * @returns The id as a `bigint`.\n * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for anything else.\n *\n * @internal\n */\nexport function parseGaslessWalletId(value: unknown, label = \"walletId\"): bigint {\n  if (typeof value === \"bigint\") return assertGaslessWalletId(value, label);\n  if (typeof value !== \"string\" || !DECIMAL_WALLET_ID.test(value)) throw invalidWalletId(value, label);\n  const walletId = BigInt(value);\n  if (walletId > maxUint256) throw invalidWalletId(value, label);\n  return walletId;\n}\n"],"mappings":";;;AAIA,IAAM,IAAoB;AAE1B,SAAS,EAAgB,GAAgB,GAA0B;CAEjE,OAAO,IAAI,EACT,cACA,6BACA,YAAY,EAAM,GAJN,OAAO,KAAU,WAAW,GAAG,EAAM,KAAM,KAAK,UAAU,CAAK,KAAK,OAAO,CAAK,EAIjE,0GAC7B;AACF;AAgBA,SAAgB,EAAsB,GAAkB,IAAQ,YAAoB;CAClF,IAAI,OAAO,KAAa,YAAY,IAAW,MAAM,IAAW,GAAY,MAAM,EAAgB,GAAU,CAAK;CACjH,OAAO;AACT;AAYA,SAAgB,EAAsB,GAA0B;CAC9D,OAAO,EAAsB,CAAQ,EAAE,SAAS;AAClD;AAgBA,SAAgB,EAAqB,GAAgB,IAAQ,YAAoB;CAC/E,IAAI,OAAO,KAAU,UAAU,OAAO,EAAsB,GAAO,CAAK;CACxE,IAAI,OAAO,KAAU,YAAY,CAAC,EAAkB,KAAK,CAAK,GAAG,MAAM,EAAgB,GAAO,CAAK;CACnG,IAAM,IAAW,OAAO,CAAK;CAC7B,IAAI,IAAW,GAAY,MAAM,EAAgB,GAAO,CAAK;CAC7D,OAAO;AACT"}

package/dist/gasless/wire-parse.d.ts

@@ -0,0 +1,33 @@
+import { GaslessRequestStatus } from './types.js';
+/**
+ * Parse an **acceptance** status tolerantly: anything outside the documented
+ * lifecycle becomes {@link GaslessRequestStatus.QUEUED}.
+ *
+ * A `202` means the workflow exists server-side and may execute. Throwing on an
+ * unrecognized acceptance status would discard the `request_id` with it, and a
+ * lost id is unrecoverable — there is no list-by-wallet endpoint. Queued is the
+ * only safe reading of "accepted, outcome unknown": the caller keeps polling
+ * and the stored record supplies the real status. Stored records are parsed
+ * strictly instead (`toGaslessRequestStatus`), where a loud failure costs
+ * nothing.
+ *
+ * @param raw - The wire `status` value.
+ * @returns The parsed status, or `queued` when it is not a known one.
+ *
+ * @internal
+ */
+export declare function toGaslessAcceptanceStatus(raw: unknown): GaslessRequestStatus;
+/**
+ * Parse an optional decimal-string amount into a `bigint`, or `null`.
+ *
+ * Every raw amount on the wire is optional and nullable, and a malformed one is
+ * a vendor bug rather than a reason to lose the record it travels with — so an
+ * unparseable value reads as "not reported" rather than throwing.
+ *
+ * @param value - The raw wire value.
+ * @returns The amount, or `null` when it is absent or not a plain decimal.
+ *
+ * @internal
+ */
+export declare function toGaslessOptionalAmount(value: unknown): bigint | null;
+//# sourceMappingURL=wire-parse.d.ts.map

package/dist/gasless/wire-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-parse.d.ts","sourceRoot":"","sources":["../../src/gasless/wire-parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAK/C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CAI5E;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIrE"}

package/dist/gasless/wire-parse.js

@@ -0,0 +1,14 @@
+import { GaslessRequestStatus as e } from "./types.js";
+//#region src/gasless/wire-parse.ts
+var t = new Set(Object.values(e));
+function n(n) {
+	return typeof n == "string" && t.has(n) ? n : e.QUEUED;
+}
+var r = /^[0-9]+$/;
+function i(e) {
+	return typeof e == "bigint" ? e : typeof e != "string" || !r.test(e) ? null : BigInt(e);
+}
+//#endregion
+export { n as toGaslessAcceptanceStatus, i as toGaslessOptionalAmount };
+
+//# sourceMappingURL=wire-parse.js.map

package/dist/gasless/wire-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-parse.js","names":[],"sources":["../../src/gasless/wire-parse.ts"],"sourcesContent":["import { GaslessRequestStatus } from \"./types\";\n\n/** Every value the lifecycle enum accepts, for tolerant inbound parsing. */\nconst STATUS_VALUES = new Set<string>(Object.values(GaslessRequestStatus));\n\n/**\n * Parse an **acceptance** status tolerantly: anything outside the documented\n * lifecycle becomes {@link GaslessRequestStatus.QUEUED}.\n *\n * A `202` means the workflow exists server-side and may execute. Throwing on an\n * unrecognized acceptance status would discard the `request_id` with it, and a\n * lost id is unrecoverable — there is no list-by-wallet endpoint. Queued is the\n * only safe reading of \"accepted, outcome unknown\": the caller keeps polling\n * and the stored record supplies the real status. Stored records are parsed\n * strictly instead (`toGaslessRequestStatus`), where a loud failure costs\n * nothing.\n *\n * @param raw - The wire `status` value.\n * @returns The parsed status, or `queued` when it is not a known one.\n *\n * @internal\n */\nexport function toGaslessAcceptanceStatus(raw: unknown): GaslessRequestStatus {\n  return typeof raw === \"string\" && STATUS_VALUES.has(raw)\n    ? (raw as GaslessRequestStatus)\n    : GaslessRequestStatus.QUEUED;\n}\n\n/** A canonical unsigned decimal amount: digits only, as the service reports amounts. */\nconst DECIMAL_AMOUNT = /^[0-9]+$/;\n\n/**\n * Parse an optional decimal-string amount into a `bigint`, or `null`.\n *\n * Every raw amount on the wire is optional and nullable, and a malformed one is\n * a vendor bug rather than a reason to lose the record it travels with — so an\n * unparseable value reads as \"not reported\" rather than throwing.\n *\n * @param value - The raw wire value.\n * @returns The amount, or `null` when it is absent or not a plain decimal.\n *\n * @internal\n */\nexport function toGaslessOptionalAmount(value: unknown): bigint | null {\n  if (typeof value === \"bigint\") return value;\n  if (typeof value !== \"string\" || !DECIMAL_AMOUNT.test(value)) return null;\n  return BigInt(value);\n}\n"],"mappings":";;AAGA,IAAM,IAAgB,IAAI,IAAY,OAAO,OAAO,CAAoB,CAAC;AAmBzE,SAAgB,EAA0B,GAAoC;CAC5E,OAAO,OAAO,KAAQ,YAAY,EAAc,IAAI,CAAG,IAClD,IACD,EAAqB;AAC3B;AAGA,IAAM,IAAiB;AAcvB,SAAgB,EAAwB,GAA+B;CAGrE,OAFI,OAAO,KAAU,WAAiB,IAClC,OAAO,KAAU,YAAY,CAAC,EAAe,KAAK,CAAK,IAAU,OAC9D,OAAO,CAAK;AACrB"}