@symmio/trading-core 3.0.0 → 3.1.0

package/dist/gasless/dispatch/maybe-relay-as-gasless.js

@@ -0,0 +1,189 @@
+import { SymmApiError as e, SymmError as t } from "../../shared/errors/symm-error.js";
+import { getInstantLayerEip712Domain as n, signSignedOperation as r } from "../../solvers/instant-open/shared/eip712.js";
+import { buildSignedOperation as i } from "../../solvers/instant-open/shared/operations.js";
+import { getVirtualAccount as a } from "../../symmio-contracts/account-layer/actions/get-virtual-account.js";
+import { getInstantLayerNonce as o } from "../../symmio-contracts/instant-layer/actions/get-instant-layer-nonce.js";
+import { assertGaslessGatewayCoherence as s } from "../assert-gateway-coherence.js";
+import { findUndelegatedGaslessSelectors as c, getCachedGaslessAccountOwner as l } from "../delegation-preflight.js";
+import { fireGaslessEvent as u, toGaslessRecordBody as d } from "../events.js";
+import { resolveGaslessService as f, supportsGaslessService as p } from "../resolve-gasless.js";
+import { getGaslessUnconfirmedSubmit as m, isGaslessIdempotencyConflictError as h } from "../unconfirmed-submit.js";
+import { generateGaslessIdempotencyKey as g, isGaslessAcceptedInstanceMismatchError as _ } from "../http.js";
+import { GaslessRequestStatus as v } from "../types.js";
+import { isConfirmedGaslessFeeLimitError as y, isConfirmedGaslessUnavailableError as b } from "../fallback.js";
+import { isGaslessFreeQuotaExhaustedError as x } from "../get-gasless-fee-quote/fee-quote-errors.js";
+import { getGaslessFeeQuote as S } from "../get-gasless-fee-quote/get-gasless-fee-quote.js";
+import { waitForGaslessRequest as C } from "../wait-for-gasless-request/wait-for-gasless-request.js";
+import { blocksGaslessNonceStream as w, gaslessInstantNonceStreamKey as T, readGaslessStreamNonce as E, submitOnGaslessNonceStream as D, withGaslessNonceLock as O } from "../nonce-lock.js";
+import { relayInstantOperations as k } from "../relay-instant-operations/relay-instant-operations.js";
+import { GASLESS_RELAYABLE_WRITES as A } from "../relayable-writes.js";
+import { registerGaslessWriteRequest as j } from "../write-request-registry.js";
+//#region src/gasless/dispatch/maybe-relay-as-gasless.ts
+var M = 1200;
+function N(e, t) {
+	let n = t.gasless, r = typeof n == "boolean" ? { enabled: n } : n ?? {}, i = p(e, { chainId: t.chainId }), a = i ? f(e, { chainId: t.chainId }).execution ?? {} : {};
+	return r.enabled ?? a.mode === "gasless" ? i ? {
+		gasless: f(e, { chainId: t.chainId }),
+		options: r,
+		execution: a,
+		fallback: r.fallback ?? a.fallback ?? "error"
+	} : typeof n == "boolean" || n?.enabled !== void 0 ? "unconfigured-explicit" : "wallet" : "wallet";
+}
+async function P(p, P) {
+	let F = N(p, P);
+	if (F === "wallet") return null;
+	if (F === "unconfigured-explicit") return f(p, { chainId: P.chainId }), null;
+	let { gasless: I, options: L, execution: R, fallback: z } = F, B = P.calls.map((e) => A.get(e.callData.slice(0, 10).toLowerCase()));
+	if (B.some((e) => e === void 0)) {
+		if (L.enabled === !0) {
+			if (z === "wallet") return null;
+			throw new t("validation", "GASLESS_NOT_RELAYABLE", "Gasless: this write's calldata is not relayable through the gasless service.");
+		}
+		return null;
+	}
+	let V = B[0]?.operationType ?? "gaslessWrite", H = p.getChainConfig(P.chainId).chainId;
+	await s(p, H, I);
+	let U = L.account ?? P.signerAccount;
+	if (!U && P.accountMaybeVirtual) {
+		let e = await a(p, {
+			chainId: H,
+			account: P.accountMaybeVirtual
+		});
+		U = e.isExists ? e.parentAccount : P.accountMaybeVirtual;
+	}
+	if (!U) {
+		if (!P.virtualAccount) throw new t("validation", "GASLESS_ACCOUNT_UNRESOLVED", "Gasless: no sub-account to relay under — pass `gasless.account`.");
+		let e = await a(p, {
+			chainId: H,
+			account: P.virtualAccount
+		});
+		if (!e.isExists) throw new t("validation", "GASLESS_ACCOUNT_UNRESOLVED", `Gasless: ${P.virtualAccount} is not a known virtual account — pass \`gasless.account\` with the paying sub-account.`);
+		U = e.parentAccount;
+	}
+	let W = U, G = await p.getWalletClient({
+		chainId: H,
+		from: P.from
+	});
+	if (R.preflightDelegation ?? !0) {
+		let e = await c(p, {
+			chainId: H,
+			signer: G.account.address,
+			signerAccount: W,
+			selectors: P.calls.map((e) => e.callData.slice(0, 10).toLowerCase())
+		});
+		if (e.length > 0) {
+			if (z === "wallet") return null;
+			throw new t("validation", "GASLESS_SIGNER_NOT_DELEGATED", `Gasless: signer ${G.account.address} holds no active InstantLayer delegation from sub-account ${W} for selector(s) ${e.join(", ")}. Grant them to the session key (the selector set is built by getSessionKeySelectors) or sign this write with the sub-account's owner.`);
+		}
+	}
+	let K = n(p, { chainId: H }), q = R.onEvent, J = T(H, W), Y = await O(p, J, async () => {
+		let e = await E(p, J, () => o(p, {
+			chainId: H,
+			account: W
+		})), n = BigInt(Math.floor(Date.now() / 1e3) + M), a = P.calls.map((t, r) => i({
+			signer: G.account.address,
+			target: t.target,
+			callData: t.callData,
+			signerAccount: W,
+			deadline: n,
+			nonce: e + BigInt(r + 1)
+		}));
+		if (R.preflightFee ?? !0) try {
+			await S(p, {
+				chainId: H,
+				operations: a.map((e) => ({ operation: e }))
+			});
+		} catch (e) {
+			if (x(e)) {
+				if (z === "wallet") return "wallet";
+				throw e;
+			}
+			if (e instanceof t) throw e;
+		}
+		let s = [];
+		for (let e of a) s.push(await r(e, K, G));
+		let c = g(), u = await l(p, H, W).catch(() => null) ?? G.account.address;
+		try {
+			return {
+				receipt: await D(p, J, {
+					signedNonce: e + BigInt(a.length),
+					service: "operations",
+					chainId: H,
+					deadline: n
+				}, () => k(p, {
+					chainId: H,
+					userAddress: u,
+					operationType: V,
+					operations: a.map((e, t) => ({
+						operation: e,
+						signature: s[t]
+					})),
+					idempotencyKey: c
+				}), w),
+				owner: u
+			};
+		} catch (e) {
+			if (!(m(e) !== null || h(e) || _(e)) && (y(e) || b(e)) && z === "wallet") return "wallet";
+			throw e;
+		}
+	});
+	if (Y === "wallet") return null;
+	let { receipt: X, owner: Z } = Y;
+	u(q, {
+		type: "accepted",
+		requestId: X.requestId,
+		service: "operations",
+		chainId: H,
+		protocolInstance: I.protocolInstance ?? null,
+		operationType: V,
+		idempotencyKey: X.idempotencyKey,
+		owner: Z,
+		walletIds: X.walletIds
+	});
+	let Q = await C(p, {
+		chainId: H,
+		requestId: X.requestId,
+		until: "broadcast",
+		timeoutMs: L.broadcastTimeoutMs ?? R.broadcastTimeoutMs,
+		queuedPollMs: R.queuedPollMs,
+		submittedPollMs: R.submittedPollMs,
+		signal: L.signal,
+		onUpdate: (e) => {
+			e.txHash && u(q, {
+				type: "broadcast",
+				requestId: e.requestId,
+				txHash: e.txHash,
+				chainId: H
+			});
+		}
+	});
+	if (Q.txHash !== null) return j(p, {
+		requestId: X.requestId,
+		service: "operations",
+		chainId: H,
+		protocolInstance: I.protocolInstance ?? null,
+		broadcastHash: Q.txHash
+	}), Q.txHash;
+	u(q, {
+		type: "terminal",
+		requestId: Q.requestId,
+		status: Q.status,
+		txHash: Q.txHash,
+		chainId: H
+	});
+	let $ = new e({
+		code: Q.status === v.REJECTED ? "GASLESS_RELAY_REJECTED" : "GASLESS_RELAY_FAILED",
+		message: `Gasless: request ${Q.requestId} ended ${Q.status} before any broadcast${Q.errorMessage ? ` — ${Q.errorMessage}` : ""}.`,
+		status: 200,
+		statusText: "OK",
+		responseData: d(Q),
+		url: I.url,
+		method: "GET"
+	});
+	if (z === "wallet" && y($)) return null;
+	throw $;
+}
+//#endregion
+export { P as maybeRelayAsGasless };
+
+//# sourceMappingURL=maybe-relay-as-gasless.js.map

package/dist/gasless/dispatch/maybe-relay-as-gasless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maybe-relay-as-gasless.js","names":[],"sources":["../../../src/gasless/dispatch/maybe-relay-as-gasless.ts"],"sourcesContent":["import type { Address, Hash, Hex } from \"viem\";\nimport type { GaslessExecutionConfig, SymmioGaslessConfig } from \"../../core/chains/types\";\nimport type { Config } from \"../../core/config\";\nimport { SymmApiError, SymmError } from \"../../shared/errors/symm-error\";\nimport type { GaslessWriteOptions } from \"../../shared/types/properties\";\nimport { getInstantLayerEip712Domain, signSignedOperation } from \"../../solvers/instant-open/shared/eip712\";\nimport { buildSignedOperation } from \"../../solvers/instant-open/shared/operations\";\nimport { getVirtualAccount } from \"../../symmio-contracts/account-layer/actions/get-virtual-account\";\nimport { getInstantLayerNonce } from \"../../symmio-contracts/instant-layer/actions/get-instant-layer-nonce\";\nimport { assertGaslessGatewayCoherence } from \"../assert-gateway-coherence\";\nimport { findUndelegatedGaslessSelectors, getCachedGaslessAccountOwner } from \"../delegation-preflight\";\nimport { fireGaslessEvent, toGaslessRecordBody } from \"../events\";\nimport { isConfirmedGaslessFeeLimitError, isConfirmedGaslessUnavailableError } from \"../fallback\";\nimport { isGaslessFreeQuotaExhaustedError } from \"../get-gasless-fee-quote/fee-quote-errors\";\nimport { getGaslessFeeQuote } from \"../get-gasless-fee-quote/get-gasless-fee-quote\";\nimport { generateGaslessIdempotencyKey, isGaslessAcceptedInstanceMismatchError } from \"../http\";\nimport {\n  blocksGaslessNonceStream,\n  gaslessInstantNonceStreamKey,\n  readGaslessStreamNonce,\n  submitOnGaslessNonceStream,\n  withGaslessNonceLock,\n} from \"../nonce-lock\";\nimport { relayInstantOperations } from \"../relay-instant-operations/relay-instant-operations\";\nimport { GASLESS_RELAYABLE_WRITES } from \"../relayable-writes\";\nimport { resolveGaslessService, supportsGaslessService } from \"../resolve-gasless\";\nimport { GaslessRequestStatus, type GaslessSubmitReceipt } from \"../types\";\nimport { getGaslessUnconfirmedSubmit, isGaslessIdempotencyConflictError } from \"../unconfirmed-submit\";\nimport { waitForGaslessRequest } from \"../wait-for-gasless-request/wait-for-gasless-request\";\nimport { registerGaslessWriteRequest } from \"../write-request-registry\";\n\n/** How long a relayed operation's signature stays valid. */\nconst GASLESS_OPERATION_DEADLINE_SECONDS = 20 * 60;\n\n/** One inner call of a write the dispatcher may relay. @internal */\nexport interface GaslessDispatchCall {\n  /** Contract the calldata targets (core diamond or AccountLayer). */\n  target: Address;\n  /** Raw function calldata. */\n  callData: Hex;\n}\n\n/** Input the write seams hand to {@link maybeRelayAsGasless}. @internal */\nexport interface MaybeRelayAsGaslessParameters {\n  chainId?: number;\n  from?: Address;\n  /** The write's `gasless` parameter, verbatim. */\n  gasless: boolean | GaslessWriteOptions | undefined;\n  /** The calls, in execution order (a multi-call `_call` batch stays atomic as a relay batch). */\n  calls: readonly GaslessDispatchCall[];\n  /**\n   * The sub-account the operations run under. The `_call` seam knows it; the\n   * margin seam passes `virtualAccount` instead and the parent is resolved\n   * on-chain (or taken from `gasless.account`).\n   */\n  signerAccount?: Address;\n  /** The virtual account of a margin write, for parent-sub-account resolution. */\n  virtualAccount?: Address;\n  /**\n   * An account a write targets that may be either a sub-account or a virtual\n   * account — the deposit seams cannot tell the two apart from their parameters.\n   * A VA resolves to its parent sub-account (a VA has no balance of its own to\n   * bill); anything else is used as the billing account unchanged. Unlike\n   * {@link MaybeRelayAsGaslessParameters.virtualAccount} this never throws for a\n   * non-VA address.\n   */\n  accountMaybeVirtual?: Address;\n}\n\n/**\n * What the locked read-sign-submit section hands back: the acceptance and the\n * owner it was tracked under, or `\"wallet\"` when a definitive pre-broadcast\n * rejection sends the write down the wallet path.\n */\ntype GaslessDispatchSubmit = { receipt: GaslessSubmitReceipt; owner: Address } | \"wallet\";\n\ninterface ResolvedGaslessDispatch {\n  gasless: SymmioGaslessConfig;\n  options: GaslessWriteOptions;\n  execution: GaslessExecutionConfig;\n  fallback: \"error\" | \"wallet\";\n}\n\nfunction resolveDispatch(\n  config: Config,\n  parameters: MaybeRelayAsGaslessParameters,\n): ResolvedGaslessDispatch | \"wallet\" | \"unconfigured-explicit\" {\n  const raw = parameters.gasless;\n  const options: GaslessWriteOptions = typeof raw === \"boolean\" ? { enabled: raw } : (raw ?? {});\n\n  const supported = supportsGaslessService(config, { chainId: parameters.chainId });\n  const execution = supported ? (resolveGaslessService(config, { chainId: parameters.chainId }).execution ?? {}) : {};\n  const enabled = options.enabled ?? (execution.mode === \"gasless\" ? true : false);\n\n  if (!enabled) return \"wallet\";\n  if (!supported) {\n    /** Implicit (config-driven) mode degrades silently; an explicit `gasless: true` must not. */\n    return typeof raw === \"boolean\" || raw?.enabled !== undefined ? \"unconfigured-explicit\" : \"wallet\";\n  }\n\n  return {\n    gasless: resolveGaslessService(config, { chainId: parameters.chainId }),\n    options,\n    execution,\n    fallback: options.fallback ?? execution.fallback ?? \"error\",\n  };\n}\n\n/**\n * The transparent gasless dispatcher. Called by relayable write actions before\n * their wallet path: returns the relayer's broadcast transaction hash when the\n * write was relayed, or `null` when the caller must proceed on the normal\n * gas-paid wallet path (gasless off, unsupported selector, or a definitive\n * pre-broadcast rejection under `fallback: \"wallet\"`).\n *\n * The full policy lives in the docs; the load-bearing rules are:\n * - **202 is the point of no return** — after acceptance there is no wallet\n *   fallback ever, except a `rejected` terminal whose cause is a confirmed\n *   fee/quota limit (nothing was broadcast, so a wallet retry cannot\n *   double-execute).\n * - A user's signature rejection always propagates — the user said no.\n * - The returned hash behaves exactly like a wallet-submitted hash: the\n *   caller's receipt-wait and invalidation pipelines run unchanged.\n * - A signer that is not the sub-account's owner is checked against its\n *   InstantLayer delegations **before** the signature prompt\n *   (`execution.preflightDelegation`, default on): a session key missing a\n *   selector throws `GASLESS_SIGNER_NOT_DELEGATED` — the selector set to grant\n *   is the one `getSessionKeySelectors` builds. Under `fallback: \"wallet\"` that\n *   rejection returns `null` instead, exactly like an exhausted free quota; note\n *   the wallet path will then fail too for a session key, which holds no gas\n *   and is not the owner — guarding that is the caller's concern, not this\n *   dispatcher's.\n * - The fee quote runs **before** the signature prompt too\n *   (`execution.preflightFee`, default on). An exhausted daily free quota throws\n *   `GASLESS_FREE_QUOTA_EXHAUSTED` (or returns `null` under `fallback: \"wallet\"`);\n *   a quote the contract rejects throws `GASLESS_FEE_QUOTE_REVERTED` and a\n *   GaslessLayer without the multi-wallet interface throws\n *   `GASLESS_LAYER_INTERFACE_UNSUPPORTED`, neither with a fallback. A quote that\n *   fails for transport reasons does not block: the relayer's own simulation is\n *   authoritative.\n *\n * @internal\n */\nexport async function maybeRelayAsGasless(\n  config: Config,\n  parameters: MaybeRelayAsGaslessParameters,\n): Promise<Hash | null> {\n  const resolved = resolveDispatch(config, parameters);\n  if (resolved === \"wallet\") return null;\n  if (resolved === \"unconfigured-explicit\") {\n    /** Throws the precise typed error (not-configured vs wrong contracts version). */\n    resolveGaslessService(config, { chainId: parameters.chainId });\n    return null;\n  }\n  const { gasless, options, execution, fallback } = resolved;\n\n  /** Selector gate — any non-relayable call sends the whole write to the wallet path. */\n  const writes = parameters.calls.map((call) =>\n    GASLESS_RELAYABLE_WRITES.get(call.callData.slice(0, 10).toLowerCase() as Hex),\n  );\n  if (writes.some((write) => write === undefined)) {\n    if (options.enabled === true) {\n      if (fallback === \"wallet\") return null;\n      throw new SymmError(\n        \"validation\",\n        \"GASLESS_NOT_RELAYABLE\",\n        \"Gasless: this write's calldata is not relayable through the gasless service.\",\n      );\n    }\n    return null;\n  }\n  const operationType = writes[0]?.operationType ?? \"gaslessWrite\";\n\n  const chain = config.getChainConfig(parameters.chainId);\n  const chainId = chain.chainId;\n\n  await assertGaslessGatewayCoherence(config, chainId, gasless);\n\n  /** Billing/authority account: explicit override → seam-provided sub-account → VA parent. */\n  let signerAccount = options.account ?? parameters.signerAccount;\n  if (!signerAccount && parameters.accountMaybeVirtual) {\n    const detail = await getVirtualAccount(config, { chainId, account: parameters.accountMaybeVirtual });\n    signerAccount = detail.isExists ? detail.parentAccount : parameters.accountMaybeVirtual;\n  }\n  if (!signerAccount) {\n    if (!parameters.virtualAccount) {\n      throw new SymmError(\n        \"validation\",\n        \"GASLESS_ACCOUNT_UNRESOLVED\",\n        \"Gasless: no sub-account to relay under — pass `gasless.account`.\",\n      );\n    }\n    const detail = await getVirtualAccount(config, { chainId, account: parameters.virtualAccount });\n    if (!detail.isExists) {\n      throw new SymmError(\n        \"validation\",\n        \"GASLESS_ACCOUNT_UNRESOLVED\",\n        `Gasless: ${parameters.virtualAccount} is not a known virtual account — pass \\`gasless.account\\` with the paying sub-account.`,\n      );\n    }\n    signerAccount = detail.parentAccount;\n  }\n  const resolvedSignerAccount = signerAccount;\n\n  const walletClient = await config.getWalletClient({ chainId, from: parameters.from });\n\n  /**\n   * Delegation pre-flight, before any signature prompt. Without it a session key\n   * that was never granted a selector still signs, the relayer still accepts,\n   * and the InstantLayer reverts on-chain — the user pays a prompt for a write\n   * that could never land.\n   */\n  if (execution.preflightDelegation ?? true) {\n    const missing = await findUndelegatedGaslessSelectors(config, {\n      chainId,\n      signer: walletClient.account.address,\n      signerAccount: resolvedSignerAccount,\n      selectors: parameters.calls.map((call) => call.callData.slice(0, 10).toLowerCase() as Hex),\n    });\n    if (missing.length > 0) {\n      /** A definitive pre-acceptance rejection, so it honors `fallback: \"wallet\"` like the fee quota does. */\n      if (fallback === \"wallet\") return null;\n      throw new SymmError(\n        \"validation\",\n        \"GASLESS_SIGNER_NOT_DELEGATED\",\n        `Gasless: signer ${walletClient.account.address} holds no active InstantLayer delegation from sub-account ${resolvedSignerAccount} for selector(s) ${missing.join(\", \")}. Grant them to the session key (the selector set is built by getSessionKeySelectors) or sign this write with the sub-account's owner.`,\n      );\n    }\n  }\n\n  const domain = getInstantLayerEip712Domain(config, { chainId });\n  const events = execution.onEvent;\n  const streamKey = gaslessInstantNonceStreamKey(chainId, resolvedSignerAccount);\n\n  /**\n   * The lock spans read-sign-submit only. Holding it across the broadcast wait\n   * would stall every later write behind one slow relay; instead the signed\n   * nonce is recorded on the stream and the next caller waits for it lazily.\n   */\n  const submitted = await withGaslessNonceLock(config, streamKey, async (): Promise<GaslessDispatchSubmit> => {\n    /** Fresh sequential nonces, read inside the lock, immediately before signing. */\n    const currentNonce = await readGaslessStreamNonce(config, streamKey, () =>\n      getInstantLayerNonce(config, { chainId, account: resolvedSignerAccount }),\n    );\n    const deadline = BigInt(Math.floor(Date.now() / 1000) + GASLESS_OPERATION_DEADLINE_SECONDS);\n\n    const operations = parameters.calls.map((call, index) =>\n      buildSignedOperation({\n        signer: walletClient.account.address,\n        target: call.target,\n        callData: call.callData,\n        signerAccount: resolvedSignerAccount,\n        deadline,\n        nonce: currentNonce + BigInt(index + 1),\n      }),\n    );\n\n    /**\n     * Fee pre-flight before any signature prompt. Ordinary InstantLayer\n     * operations always relay with wallet id 0.\n     */\n    if (execution.preflightFee ?? true) {\n      try {\n        await getGaslessFeeQuote(config, { chainId, operations: operations.map((operation) => ({ operation })) });\n      } catch (err) {\n        /** A definitive pre-acceptance rejection — nothing was signed, so a wallet retry is safe. */\n        if (isGaslessFreeQuotaExhaustedError(err)) {\n          if (fallback === \"wallet\") return \"wallet\";\n          throw err;\n        }\n        /** A reverted quote or an unsupported GaslessLayer: the relay would fail the same way. */\n        if (err instanceof SymmError) throw err;\n        /**\n         * Anything else is inconclusive: a transport or RPC failure of the quote\n         * read itself, or an empty-data revert whose classifying read failed. The\n         * relayer simulates the full transaction before accepting it, so signing\n         * proceeds.\n         */\n      }\n    }\n\n    /** EIP-712 prompts — a user rejection propagates unwrapped, with no fallback. */\n    const signatures: Hex[] = [];\n    for (const operation of operations) {\n      signatures.push(await signSignedOperation(operation, domain, walletClient));\n    }\n\n    /**\n     * One key per signature: the operations above were just signed, so the key\n     * is minted here rather than taken from the caller. A caller-supplied key\n     * could only ever be reused for a different payload, which the service\n     * answers with `409 IDEMPOTENCY_KEY_CONFLICT`.\n     */\n    const idempotencyKey = generateGaslessIdempotencyKey();\n\n    /**\n     * `userAddress` is the service's tracking identity, and the vendor asks for\n     * a workflow to be persisted under its owner. The billing sub-account's\n     * owner is that identity — the signer may be a session key that owns\n     * nothing. An unreadable owner falls back to the signer rather than failing\n     * a write over a tracking label.\n     */\n    const owner =\n      (await getCachedGaslessAccountOwner(config, chainId, resolvedSignerAccount).catch(() => null)) ??\n      walletClient.account.address;\n\n    try {\n      const receipt = await submitOnGaslessNonceStream(\n        config,\n        streamKey,\n        {\n          signedNonce: currentNonce + BigInt(operations.length),\n          service: \"operations\",\n          chainId,\n          deadline,\n        },\n        () =>\n          relayInstantOperations(config, {\n            chainId,\n            userAddress: owner,\n            operationType,\n            operations: operations.map((operation, index) => ({ operation, signature: signatures[index]! })),\n            idempotencyKey,\n          }),\n        blocksGaslessNonceStream,\n      );\n      return { receipt, owner };\n    } catch (err) {\n      /**\n       * The two fallback predicates already exclude everything ambiguous, but\n       * the rule this guard encodes is the one that must never be re-derived\n       * wrong: an unconfirmed submit, an idempotency conflict and a `2xx` from\n       * the wrong instance all describe a request that may be executing right\n       * now. Paying for the same intent from the wallet would double-execute\n       * it, so they end the write here whatever `fallback` says.\n       */\n      const mayBeExecuting =\n        getGaslessUnconfirmedSubmit(err) !== null ||\n        isGaslessIdempotencyConflictError(err) ||\n        isGaslessAcceptedInstanceMismatchError(err);\n      const canFallBack =\n        !mayBeExecuting && (isConfirmedGaslessFeeLimitError(err) || isConfirmedGaslessUnavailableError(err));\n      if (canFallBack && fallback === \"wallet\") return \"wallet\";\n      throw err;\n    }\n  });\n\n  if (submitted === \"wallet\") return null;\n  const { receipt, owner } = submitted;\n\n  fireGaslessEvent(events, {\n    type: \"accepted\",\n    requestId: receipt.requestId,\n    service: \"operations\",\n    chainId,\n    protocolInstance: gasless.protocolInstance ?? null,\n    operationType,\n    idempotencyKey: receipt.idempotencyKey,\n    owner,\n    walletIds: receipt.walletIds,\n  });\n\n  const record = await waitForGaslessRequest(config, {\n    chainId,\n    requestId: receipt.requestId,\n    until: \"broadcast\",\n    timeoutMs: options.broadcastTimeoutMs ?? execution.broadcastTimeoutMs,\n    queuedPollMs: execution.queuedPollMs,\n    submittedPollMs: execution.submittedPollMs,\n    signal: options.signal,\n    onUpdate: (update) => {\n      if (update.txHash)\n        fireGaslessEvent(events, { type: \"broadcast\", requestId: update.requestId, txHash: update.txHash, chainId });\n    },\n  });\n\n  if (record.txHash !== null) {\n    /**\n     * The hash the write is about to return is only the *first* broadcast — the\n     * relayer replaces it on a gas bump or a stuck nonce. Registering it here is\n     * what lets the caller's receipt wait follow the request instead of a hash\n     * that may never mine (`getGaslessWriteRequest`).\n     */\n    registerGaslessWriteRequest(config, {\n      requestId: receipt.requestId,\n      service: \"operations\",\n      chainId,\n      protocolInstance: gasless.protocolInstance ?? null,\n      broadcastHash: record.txHash,\n    });\n    return record.txHash;\n  }\n\n  /** Terminal without a broadcast: rejected or failed before any transaction. */\n  fireGaslessEvent(events, {\n    type: \"terminal\",\n    requestId: record.requestId,\n    status: record.status,\n    txHash: record.txHash,\n    chainId,\n  });\n\n  const terminalError = new SymmApiError({\n    code: record.status === GaslessRequestStatus.REJECTED ? \"GASLESS_RELAY_REJECTED\" : \"GASLESS_RELAY_FAILED\",\n    message: `Gasless: request ${record.requestId} ended ${record.status} before any broadcast${record.errorMessage ? ` — ${record.errorMessage}` : \"\"}.`,\n    status: 200,\n    statusText: \"OK\",\n    responseData: toGaslessRecordBody(record),\n    url: gasless.url,\n    method: \"GET\",\n  });\n\n  /** A confirmed fee/quota rejection never broadcast — the one post-202 wallet fallback. */\n  if (fallback === \"wallet\" && isConfirmedGaslessFeeLimitError(terminalError)) return null;\n  throw terminalError;\n}\n"],"mappings":"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"}

package/dist/gasless/eip712.d.ts

@@ -0,0 +1,79 @@
+import { TypedDataDomain } from 'viem';
+import { Config } from '../core/config/index.js';
+/**
+ * EIP-712 domain name of the GaslessLayer.
+ *
+ * Deliberately the literal `"GaslessGateway"`: the contract was renamed to
+ * GaslessLayer, but the on-chain domain string was intentionally kept —
+ * "fixing" this constant breaks every wallet-operation signature.
+ */
+export declare const GASLESS_GATEWAY_EIP712_DOMAIN_NAME: "GaslessGateway";
+/** EIP-712 domain version of the GaslessLayer. */
+export declare const GASLESS_GATEWAY_EIP712_DOMAIN_VERSION: "1";
+/**
+ * EIP-712 type table for a **gasless-wallet operation** — the gateway-domain
+ * `SignedOperation`.
+ *
+ * NOT the InstantLayer table: this struct has **five** fields — no
+ * `flexFields`, no `maxUses`. The relay transport still requires
+ * `flexFields: []` and `maxUses: 1` in the JSON body, appended *after*
+ * signing; including them in the signed struct produces a digest the gateway
+ * rejects.
+ */
+export declare const GASLESS_WALLET_OPERATION_TYPES: {
+    readonly Account: readonly [{
+        readonly name: "addr";
+        readonly type: "address";
+    }, {
+        readonly name: "isPartyB";
+        readonly type: "bool";
+    }];
+    readonly ReplayAttackHeader: readonly [{
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }];
+    readonly SignedOperation: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "target";
+        readonly type: "address";
+    }, {
+        readonly name: "callData";
+        readonly type: "bytes";
+    }, {
+        readonly name: "signerAccount";
+        readonly type: "Account";
+    }, {
+        readonly name: "replayAttackHeader";
+        readonly type: "ReplayAttackHeader";
+    }];
+};
+/**
+ * Build the GaslessLayer's EIP-712 domain for a chain.
+ *
+ * `verifyingContract` is the **GaslessLayer** address (from the chain's
+ * `gasless` block) — while a wallet operation's `target` is the deterministic
+ * gasless wallet. The two are easy to swap; swapping them yields
+ * `InvalidWalletOperationTarget` from simulation.
+ *
+ * @param config - The SDK config.
+ * @param options - Optional chain override.
+ * @returns The typed-data domain for gateway-domain signatures.
+ * @throws {SymmError} `GASLESS_NOT_CONFIGURED` / `GASLESS_UNSUPPORTED_CONTRACTS_VERSION`.
+ *
+ * @example
+ * ```ts
+ * const domain = getGaslessGatewayEip712Domain(config, { chainId });
+ * ```
+ */
+export declare function getGaslessGatewayEip712Domain(config: Config, options?: {
+    chainId?: number;
+}): TypedDataDomain;
+//# sourceMappingURL=eip712.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eip712.d.ts","sourceRoot":"","sources":["../../src/gasless/eip712.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,EAAG,gBAAyB,CAAC;AAE5E,kDAAkD;AAClD,eAAO,MAAM,qCAAqC,EAAG,GAAY,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiBjC,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,eAAe,CASjH"}

package/dist/gasless/eip712.js

@@ -0,0 +1,60 @@
+import { resolveGaslessService as e } from "./resolve-gasless.js";
+//#region src/gasless/eip712.ts
+var t = "GaslessGateway", n = "1", r = {
+	Account: [{
+		name: "addr",
+		type: "address"
+	}, {
+		name: "isPartyB",
+		type: "bool"
+	}],
+	ReplayAttackHeader: [
+		{
+			name: "nonce",
+			type: "uint256"
+		},
+		{
+			name: "deadline",
+			type: "uint256"
+		},
+		{
+			name: "salt",
+			type: "bytes32"
+		}
+	],
+	SignedOperation: [
+		{
+			name: "signer",
+			type: "address"
+		},
+		{
+			name: "target",
+			type: "address"
+		},
+		{
+			name: "callData",
+			type: "bytes"
+		},
+		{
+			name: "signerAccount",
+			type: "Account"
+		},
+		{
+			name: "replayAttackHeader",
+			type: "ReplayAttackHeader"
+		}
+	]
+};
+function i(n, r = {}) {
+	let i = n.getChainConfig(r.chainId), a = e(n, { chainId: r.chainId });
+	return {
+		name: t,
+		version: "1",
+		chainId: i.chainId,
+		verifyingContract: a.gaslessLayerAddress
+	};
+}
+//#endregion
+export { t as GASLESS_GATEWAY_EIP712_DOMAIN_NAME, n as GASLESS_GATEWAY_EIP712_DOMAIN_VERSION, r as GASLESS_WALLET_OPERATION_TYPES, i as getGaslessGatewayEip712Domain };
+
+//# sourceMappingURL=eip712.js.map

package/dist/gasless/eip712.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eip712.js","names":[],"sources":["../../src/gasless/eip712.ts"],"sourcesContent":["import type { TypedDataDomain } from \"viem\";\nimport type { Config } from \"../core/config\";\nimport { resolveGaslessService } from \"./resolve-gasless\";\n\n/**\n * EIP-712 domain name of the GaslessLayer.\n *\n * Deliberately the literal `\"GaslessGateway\"`: the contract was renamed to\n * GaslessLayer, but the on-chain domain string was intentionally kept —\n * \"fixing\" this constant breaks every wallet-operation signature.\n */\nexport const GASLESS_GATEWAY_EIP712_DOMAIN_NAME = \"GaslessGateway\" as const;\n\n/** EIP-712 domain version of the GaslessLayer. */\nexport const GASLESS_GATEWAY_EIP712_DOMAIN_VERSION = \"1\" as const;\n\n/**\n * EIP-712 type table for a **gasless-wallet operation** — the gateway-domain\n * `SignedOperation`.\n *\n * NOT the InstantLayer table: this struct has **five** fields — no\n * `flexFields`, no `maxUses`. The relay transport still requires\n * `flexFields: []` and `maxUses: 1` in the JSON body, appended *after*\n * signing; including them in the signed struct produces a digest the gateway\n * rejects.\n */\nexport const GASLESS_WALLET_OPERATION_TYPES = {\n  Account: [\n    { name: \"addr\", type: \"address\" },\n    { name: \"isPartyB\", type: \"bool\" },\n  ],\n  ReplayAttackHeader: [\n    { name: \"nonce\", type: \"uint256\" },\n    { name: \"deadline\", type: \"uint256\" },\n    { name: \"salt\", type: \"bytes32\" },\n  ],\n  SignedOperation: [\n    { name: \"signer\", type: \"address\" },\n    { name: \"target\", type: \"address\" },\n    { name: \"callData\", type: \"bytes\" },\n    { name: \"signerAccount\", type: \"Account\" },\n    { name: \"replayAttackHeader\", type: \"ReplayAttackHeader\" },\n  ],\n} as const;\n\n/**\n * Build the GaslessLayer's EIP-712 domain for a chain.\n *\n * `verifyingContract` is the **GaslessLayer** address (from the chain's\n * `gasless` block) — while a wallet operation's `target` is the deterministic\n * gasless wallet. The two are easy to swap; swapping them yields\n * `InvalidWalletOperationTarget` from simulation.\n *\n * @param config - The SDK config.\n * @param options - Optional chain override.\n * @returns The typed-data domain for gateway-domain signatures.\n * @throws {SymmError} `GASLESS_NOT_CONFIGURED` / `GASLESS_UNSUPPORTED_CONTRACTS_VERSION`.\n *\n * @example\n * ```ts\n * const domain = getGaslessGatewayEip712Domain(config, { chainId });\n * ```\n */\nexport function getGaslessGatewayEip712Domain(config: Config, options: { chainId?: number } = {}): TypedDataDomain {\n  const chain = config.getChainConfig(options.chainId);\n  const gasless = resolveGaslessService(config, { chainId: options.chainId });\n  return {\n    name: GASLESS_GATEWAY_EIP712_DOMAIN_NAME,\n    version: GASLESS_GATEWAY_EIP712_DOMAIN_VERSION,\n    chainId: chain.chainId,\n    verifyingContract: gasless.gaslessLayerAddress,\n  };\n}\n"],"mappings":";;AAWA,IAAa,IAAqC,kBAGrC,IAAwC,KAYxC,IAAiC;CAC5C,SAAS,CACP;EAAE,MAAM;EAAQ,MAAM;CAAU,GAChC;EAAE,MAAM;EAAY,MAAM;CAAO,CACnC;CACA,oBAAoB;EAClB;GAAE,MAAM;GAAS,MAAM;EAAU;EACjC;GAAE,MAAM;GAAY,MAAM;EAAU;EACpC;GAAE,MAAM;GAAQ,MAAM;EAAU;CAClC;CACA,iBAAiB;EACf;GAAE,MAAM;GAAU,MAAM;EAAU;EAClC;GAAE,MAAM;GAAU,MAAM;EAAU;EAClC;GAAE,MAAM;GAAY,MAAM;EAAQ;EAClC;GAAE,MAAM;GAAiB,MAAM;EAAU;EACzC;GAAE,MAAM;GAAsB,MAAM;EAAqB;CAC3D;AACF;AAoBA,SAAgB,EAA8B,GAAgB,IAAgC,CAAC,GAAoB;CACjH,IAAM,IAAQ,EAAO,eAAe,EAAQ,OAAO,GAC7C,IAAU,EAAsB,GAAQ,EAAE,SAAS,EAAQ,QAAQ,CAAC;CAC1E,OAAO;EACL,MAAM;EACN,SAAA;EACA,SAAS,EAAM;EACf,mBAAmB,EAAQ;CAC7B;AACF"}

package/dist/gasless/errors.d.ts

@@ -0,0 +1,132 @@
+import { Hex } from 'viem';
+/**
+ * A decoded on-chain custom error the service extracted from a failed
+ * `eth_call` simulation and returned inside `details.contract_revert`.
+ */
+export interface GaslessContractRevert {
+    /** 4-byte error selector. */
+    selector: string;
+    /** Custom-error name, e.g. `"InvalidWalletOperationTarget"`. */
+    error: string;
+    /** Full error signature when the node supplied it. */
+    signature?: string;
+    /**
+     * Decoded argument values — a positional array, or an object keyed by
+     * parameter name. The vendor sends whichever its decoder produced, so both
+     * shapes reach a consumer and neither can be assumed; narrow with
+     * `Array.isArray` before indexing.
+     */
+    arguments?: readonly unknown[] | Record<string, unknown>;
+    /** Decoded arguments keyed by parameter name, when available. */
+    decoded?: Record<string, unknown> | string;
+}
+/**
+ * The batch entry an `OperationFailed(operationIndex, revertData)` revert
+ * blames, as the service reported it.
+ *
+ * The InstantLayer wraps every inner revert of a relayed batch in this error,
+ * so the generic simulation message never names the call that actually failed.
+ * Decode `revertData` against the failing target's ABI with
+ * {@link decodeGaslessOperationFailure} to get the real cause.
+ */
+export interface GaslessFailedOperation {
+    /** Zero-based position of the failing operation in the submitted batch. */
+    index: number;
+    /** The inner revert data, to decode against the target contract's ABI. */
+    revertData: Hex;
+}
+/**
+ * One request-validation failure from a FastAPI `422` response, whose body is
+ * `{ "detail": [{ "loc", "msg", "type" }] }`. The service rejected the
+ * payload's shape before acting on it, so a `422` is a client bug to fix, not a
+ * condition a user can resolve.
+ */
+export interface GaslessValidationIssue {
+    /** Path to the offending input, e.g. `["path", "request_id"]` or `["body", "signedOps", 0, "target"]`. */
+    loc: readonly (string | number)[];
+    /** Human-readable reason. */
+    msg: string;
+    /** Machine-readable failure type, e.g. `"uuid_parsing"` or `"missing"`. */
+    type: string;
+}
+/**
+ * The vendor's structured error detail, normalized from whichever envelope an
+ * HTTP error used: the service's `{ detail: { code, message, details } }`, the
+ * gateway's own `{ error }`, or a FastAPI `422` `{ detail: [...] }`.
+ */
+export interface GaslessErrorDetail {
+    /** Vendor error code, e.g. `"SIMULATION_REVERTED"`, `"INSUFFICIENT_ALLOWANCE"`. */
+    code: string | null;
+    /** Human-readable vendor message. */
+    message: string | null;
+    /** Safe diagnostic context; `contract_revert` is surfaced separately. */
+    details: Record<string, unknown> | null;
+    /** Decoded on-chain revert, when the node returned custom-error data. */
+    contractRevert: GaslessContractRevert | null;
+    /**
+     * The gateway's own error string, from its `{ "error": "…" }` envelope.
+     * The gateway answers authentication, routing and rate-limit failures itself
+     * before any service sees the request, e.g.
+     * `"Unknown or disabled protocol instance: …"` or `"Rate limit exceeded"`.
+     * `null` for errors the service returned.
+     */
+    gatewayError: string | null;
+    /** The request-validation issues of a FastAPI `422` response; `null` for any other error. */
+    validationErrors: readonly GaslessValidationIssue[] | null;
+    /**
+     * The node's plain revert string (`revert_message`), when the simulation
+     * produced one. Prefer it, `contractRevert` and {@link GaslessErrorDetail.failedOperation}
+     * over the generic `message` when deciding what the user can fix — an
+     * `"OperationalFee: Insufficient balance"` here names the payer's shortfall,
+     * which the simulation message does not.
+     */
+    revertMessage: string | null;
+    /** The service's own decoded view of the revert (`decoded_revert`), in whatever shape it sent. */
+    decodedRevert: unknown;
+    /** The nested JSON-RPC error (`rpc_error`) the node returned, when the failure came from the chain. */
+    rpcError: Record<string, unknown> | null;
+    /** The failing batch entry of an `OperationFailed` revert; `null` when the service named none. */
+    failedOperation: GaslessFailedOperation | null;
+}
+/**
+ * Every string the service offered about a revert, joined into one haystack.
+ *
+ * The same cause reaches the client under different keys depending on how far
+ * the service got decoding it — a custom-error name, a full signature, a
+ * decoded string, the node's `revert_message`, or only the generic message — so
+ * a predicate that reads one of them misses the other four.
+ *
+ * @param detail - A parsed vendor detail, or `null`.
+ * @returns The concatenated revert text, empty when there is none.
+ *
+ * @internal
+ */
+export declare function gaslessRevertText(detail: GaslessErrorDetail | null): string;
+/**
+ * Extract the vendor's error detail from any error a gasless action throws:
+ * the service's `{ code, message, details }` (including a decoded
+ * `contract_revert`, when present), the gateway's own `{ error }` string, or a
+ * FastAPI `422`'s validation issues.
+ *
+ * Gasless HTTP failures are thrown as `SymmApiError` with the raw response
+ * body preserved in `responseData`; this digs the vendor envelope out of it so
+ * UIs can branch on the vendor code (`FEE_POLICY_WOULD_REVERT`,
+ * `INSUFFICIENT_ALLOWANCE`, `SIMULATION_REVERTED`, …) without re-parsing.
+ * Also understands the flat `{ error_code, error_message }` shape stored on
+ * polled records.
+ *
+ * @param err - Anything caught from a gasless action or read from a record.
+ * @returns The normalized detail, or `null` when none can be extracted.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await relayInstantOperations(config, parameters);
+ * } catch (err) {
+ *   const detail = parseGaslessErrorDetail(err);
+ *   if (detail?.contractRevert) showRevert(detail.contractRevert.error);
+ * }
+ * ```
+ */
+export declare function parseGaslessErrorDetail(err: unknown): GaslessErrorDetail | null;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/gasless/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAGhC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,GAAG,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,0GAA0G;IAC1G,GAAG,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAClC,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,qCAAqC;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,yEAAyE;IACzE,cAAc,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC7C;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6FAA6F;IAC7F,gBAAgB,EAAE,SAAS,sBAAsB,EAAE,GAAG,IAAI,CAAC;IAC3D;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kGAAkG;IAClG,aAAa,EAAE,OAAO,CAAC;IACvB,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,kGAAkG;IAClG,eAAe,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,GAAG,MAAM,CAa3E;AAuHD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAqD/E"}

package/dist/gasless/errors.js

@@ -0,0 +1,110 @@
+import { SymmApiError as e, SymmError as t } from "../shared/errors/symm-error.js";
+//#region src/gasless/errors.ts
+function n(e) {
+	if (!e) return "";
+	let t = e.contractRevert;
+	return [
+		t?.error,
+		t?.signature,
+		typeof t?.decoded == "string" ? t.decoded : void 0,
+		e.revertMessage,
+		typeof e.decodedRevert == "string" ? e.decodedRevert : void 0,
+		e.message
+	].filter((e) => typeof e == "string").join(" | ");
+}
+function r(e) {
+	return typeof e == "object" && e && !Array.isArray(e) ? e : null;
+}
+function i(e) {
+	return e.flatMap((e) => {
+		if (typeof e == "string") return [{
+			loc: [],
+			msg: e,
+			type: ""
+		}];
+		let t = r(e);
+		return t ? [{
+			loc: Array.isArray(t.loc) ? t.loc.filter((e) => typeof e == "string" || typeof e == "number") : [],
+			msg: typeof t.msg == "string" ? t.msg : "",
+			type: typeof t.type == "string" ? t.type : ""
+		}] : [];
+	});
+}
+function a(e, ...t) {
+	for (let n of e) if (n) {
+		for (let e of t) if (n[e] !== void 0 && n[e] !== null) return n[e];
+	}
+}
+function o(e) {
+	if (typeof e == "number") return Number.isSafeInteger(e) && e >= 0 ? e : null;
+	if (typeof e == "bigint") return e >= 0n && e <= BigInt(2 ** 53 - 1) ? Number(e) : null;
+	if (typeof e == "string" && /^\d+$/.test(e)) {
+		let t = Number(e);
+		return Number.isSafeInteger(t) ? t : null;
+	}
+	return null;
+}
+function s(e) {
+	return typeof e == "string" && /^0x[0-9a-fA-F]*$/.test(e) ? e : null;
+}
+function c(e, t) {
+	let n = [r(a(e, "failed_operation", "failedOperation")), ...e];
+	for (let e of n) {
+		if (!e) continue;
+		let t = o(e.index ?? e.operation_index ?? e.operationIndex), n = s(e.revert_data ?? e.revertData);
+		if (t !== null && n !== null) return {
+			index: t,
+			revertData: n
+		};
+	}
+	if (t?.error !== "OperationFailed") return null;
+	let i = t.arguments;
+	if (Array.isArray(i)) {
+		let e = o(i[0]), t = s(i[1]);
+		return e !== null && t !== null ? {
+			index: e,
+			revertData: t
+		} : null;
+	}
+	let c = r(i) ?? r(t.decoded);
+	if (!c) return null;
+	let l = o(c.operationIndex ?? c.operation_index ?? c.index), u = s(c.revertData ?? c.revert_data);
+	return l !== null && u !== null ? {
+		index: l,
+		revertData: u
+	} : null;
+}
+function l(e) {
+	return typeof e == "object" && e && "responseData" in e ? e.responseData : e;
+}
+function u(n) {
+	let o = n instanceof e ? n.responseData : n instanceof t ? null : l(n);
+	if (o instanceof Error) return null;
+	let s = r(o);
+	if (!s) return null;
+	let u = typeof s.error == "string" ? s.error : null, d = Array.isArray(s.detail) ? i(s.detail) : [], f = d.length > 0 ? d : null, p = r(s.detail) ?? s, m = p.code ?? p.error_code, h = p.message ?? p.error_message, g = r(p.details), _ = r(a([p, g], "contract_revert", "contractRevert"));
+	if (m === void 0 && h === void 0 && !g && u === null && f === null) return null;
+	let v = _?.arguments, y = _ && typeof _.error == "string" ? {
+		selector: typeof _.selector == "string" ? _.selector : "0x",
+		error: _.error,
+		...typeof _.signature == "string" ? { signature: _.signature } : {},
+		...Array.isArray(v) || r(v) ? { arguments: v } : {},
+		..._.decoded === void 0 ? {} : { decoded: _.decoded }
+	} : null, b = [p, g], x = a(b, "revert_message", "revertMessage");
+	return {
+		code: typeof m == "string" ? m : null,
+		message: typeof h == "string" ? h : null,
+		details: g,
+		contractRevert: y,
+		gatewayError: u,
+		validationErrors: f,
+		revertMessage: typeof x == "string" ? x : null,
+		decodedRevert: a(b, "decoded_revert", "decodedRevert"),
+		rpcError: r(a(b, "rpc_error", "rpcError")),
+		failedOperation: c(b, y)
+	};
+}
+//#endregion
+export { n as gaslessRevertText, u as parseGaslessErrorDetail };
+
+//# sourceMappingURL=errors.js.map