@symmio/trading-core 3.0.0 → 3.1.0

package/dist/gasless/assert-gateway-coherence.d.ts

@@ -0,0 +1,20 @@
+import { SymmioGaslessConfig } from '../core/chains/types.js';
+import { Config } from '../core/config/index.js';
+/**
+ * Check, once per config and chain, that the configured GaslessLayer verifies
+ * operations against the same InstantLayer the chain config signs for.
+ *
+ * InstantLayer signatures are bound to the chain's `instantLayerAddress`
+ * (the EIP-712 `verifyingContract`), while the relay is verified by whichever
+ * InstantLayer the GaslessLayer points at. When the two differ, every relayed
+ * signature is rejected — after the user has already been prompted for it.
+ *
+ * @param config - The SDK config.
+ * @param chainId - The chain the relay targets.
+ * @param gasless - The chain's resolved gasless block.
+ * @throws {SymmError} `GASLESS_CONFIG_INCOHERENT` when the two InstantLayer addresses differ.
+ *
+ * @internal
+ */
+export declare function assertGaslessGatewayCoherence(config: Config, chainId: number, gasless: SymmioGaslessConfig): Promise<void>;
+//# sourceMappingURL=assert-gateway-coherence.d.ts.map

package/dist/gasless/assert-gateway-coherence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-gateway-coherence.d.ts","sourceRoot":"","sources":["../../src/gasless/assert-gateway-coherence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAO7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/gasless/assert-gateway-coherence.js

@@ -0,0 +1,26 @@
+import { gaslessLayerAbi as e } from "../symmio-contracts/abi/v0.8.6/gasless-layer.js";
+import { SymmError as t } from "../shared/errors/symm-error.js";
+import { isAddressEqual as n } from "viem";
+//#region src/gasless/assert-gateway-coherence.ts
+var r = /* @__PURE__ */ new WeakMap();
+function i(i, a, o) {
+	let s = r.get(i);
+	s || (s = /* @__PURE__ */ new Map(), r.set(i, s));
+	let c = s.get(a);
+	if (c) return c;
+	let l = (async () => {
+		let { addresses: r } = i.getChainConfig(a), s = await i.getClient({ chainId: a }).readContract({
+			address: o.gaslessLayerAddress,
+			abi: e,
+			functionName: "instantLayer"
+		});
+		if (!n(s, r.instantLayerAddress)) throw new t("config", "GASLESS_CONFIG_INCOHERENT", `Gasless: the configured GaslessLayer (${o.gaslessLayerAddress}) verifies operations against InstantLayer ${s}, but chain ${a} is configured with instantLayerAddress ${r.instantLayerAddress}. Relayed signatures would be rejected — align the two addresses (createConfig override) before using gasless execution.`);
+	})();
+	return s.set(a, l), l.catch(() => {
+		s.get(a) === l && s.delete(a);
+	}), l;
+}
+//#endregion
+export { i as assertGaslessGatewayCoherence };
+
+//# sourceMappingURL=assert-gateway-coherence.js.map

package/dist/gasless/assert-gateway-coherence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-gateway-coherence.js","names":[],"sources":["../../src/gasless/assert-gateway-coherence.ts"],"sourcesContent":["import { isAddressEqual } from \"viem\";\nimport type { SymmioGaslessConfig } from \"../core/chains/types\";\nimport type { Config } from \"../core/config\";\nimport { SymmError } from \"../shared/errors/symm-error\";\nimport { gaslessLayerAbi } from \"../symmio-contracts/abi/v0.8.6/gasless-layer\";\n\n/** One coherence probe per (config, chainId) — the gateway address is a config constant. */\nconst coherenceChecks = new WeakMap<Config, Map<number, Promise<void>>>();\n\n/**\n * Check, once per config and chain, that the configured GaslessLayer verifies\n * operations against the same InstantLayer the chain config signs for.\n *\n * InstantLayer signatures are bound to the chain's `instantLayerAddress`\n * (the EIP-712 `verifyingContract`), while the relay is verified by whichever\n * InstantLayer the GaslessLayer points at. When the two differ, every relayed\n * signature is rejected — after the user has already been prompted for it.\n *\n * @param config - The SDK config.\n * @param chainId - The chain the relay targets.\n * @param gasless - The chain's resolved gasless block.\n * @throws {SymmError} `GASLESS_CONFIG_INCOHERENT` when the two InstantLayer addresses differ.\n *\n * @internal\n */\nexport function assertGaslessGatewayCoherence(\n  config: Config,\n  chainId: number,\n  gasless: SymmioGaslessConfig,\n): Promise<void> {\n  let byChain = coherenceChecks.get(config);\n  if (!byChain) {\n    byChain = new Map();\n    coherenceChecks.set(config, byChain);\n  }\n  const cached = byChain.get(chainId);\n  if (cached) return cached;\n\n  const probe = (async () => {\n    const { addresses } = config.getChainConfig(chainId);\n    const client = config.getClient({ chainId });\n    const gatewayInstantLayer = await client.readContract({\n      address: gasless.gaslessLayerAddress,\n      abi: gaslessLayerAbi,\n      functionName: \"instantLayer\",\n    });\n    if (!isAddressEqual(gatewayInstantLayer, addresses.instantLayerAddress)) {\n      throw new SymmError(\n        \"config\",\n        \"GASLESS_CONFIG_INCOHERENT\",\n        `Gasless: the configured GaslessLayer (${gasless.gaslessLayerAddress}) verifies operations against InstantLayer ${gatewayInstantLayer}, but chain ${chainId} is configured with instantLayerAddress ${addresses.instantLayerAddress}. Relayed signatures would be rejected — align the two addresses (createConfig override) before using gasless execution.`,\n      );\n    }\n  })();\n  /**\n   * Cache the real probe, not a swallowed copy. A pre-swallowed promise would\n   * resolve for every caller that arrived while the first probe was still in\n   * flight, so a concurrent write would sail past the guard on a misconfigured\n   * chain and sign against an InstantLayer the gateway does not verify.\n   *\n   * The entry is dropped on rejection so a transient RPC failure cannot poison\n   * the config — the next write probes again.\n   */\n  byChain.set(chainId, probe);\n  probe.catch(() => {\n    if (byChain.get(chainId) === probe) byChain.delete(chainId);\n  });\n  return probe;\n}\n"],"mappings":";;;;AAOA,IAAM,oBAAkB,IAAI,QAA4C;AAkBxE,SAAgB,EACd,GACA,GACA,GACe;CACf,IAAI,IAAU,EAAgB,IAAI,CAAM;CACxC,AAAK,MACH,oBAAU,IAAI,IAAI,GAClB,EAAgB,IAAI,GAAQ,CAAO;CAErC,IAAM,IAAS,EAAQ,IAAI,CAAO;CAClC,IAAI,GAAQ,OAAO;CAEnB,IAAM,KAAS,YAAY;EACzB,IAAM,EAAE,iBAAc,EAAO,eAAe,CAAO,GAE7C,IAAsB,MADb,EAAO,UAAU,EAAE,WAAQ,CACR,EAAO,aAAa;GACpD,SAAS,EAAQ;GACjB,KAAK;GACL,cAAc;EAChB,CAAC;EACD,IAAI,CAAC,EAAe,GAAqB,EAAU,mBAAmB,GACpE,MAAM,IAAI,EACR,UACA,6BACA,yCAAyC,EAAQ,oBAAoB,6CAA6C,EAAoB,cAAc,EAAQ,0CAA0C,EAAU,oBAAoB,yHACtO;CAEJ,GAAG;CAcH,OAJA,EAAQ,IAAI,GAAS,CAAK,GAC1B,EAAM,YAAY;EAChB,AAAI,EAAQ,IAAI,CAAO,MAAM,KAAO,EAAQ,OAAO,CAAO;CAC5D,CAAC,GACM;AACT"}

package/dist/gasless/batch/calls.d.ts

@@ -0,0 +1,121 @@
+import { Abi, Hex } from 'viem';
+import { GaslessWalletCall } from '../gasless-wallet-execute/calls.js';
+/**
+ * A relayable write named by its function, which the SDK encodes with viem's
+ * `encodeFunctionData` — that throws on an arity or type mismatch, before any
+ * signature prompt or network call.
+ *
+ * The target contract is **not** given: the SDK resolves it from the encoded
+ * selector (the core diamond, the AccountLayer or the InstantLayer). The `abi`
+ * is optional too — every relayable write is a known SYMMIO function, so
+ * `{ functionName: "allocate", args: [amount] }` is enough. Pass an `abi` (the
+ * SDK's own `symmioAbi`, `accountLayerAbi` or `instantLayerAbi`) when you
+ * already hold it; the selector must still be a relayable write.
+ *
+ * `args` is deliberately `readonly unknown[]`, as for `GaslessWalletContractCall`.
+ * When you want compile-time-checked arguments, encode with viem yourself and
+ * pass the result as a {@link GaslessBatchRawCall}.
+ */
+export interface GaslessBatchContractCall {
+    /** ABI containing `functionName`. Omit it to use the SDK's own ABI for the relayable write of that name. */
+    abi?: Abi | readonly unknown[];
+    /** The relayable write to run — `"allocate"`, `"initiateWithdraw"`, `"grantDelegation"`, … */
+    functionName: string;
+    /** Arguments for `functionName`, in order. Omit for a no-argument function. */
+    args?: readonly unknown[];
+}
+/** A relayable write given as raw calldata; its selector decides the target contract. */
+export interface GaslessBatchRawCall {
+    /** Calldata of a relayable write. */
+    data: Hex;
+}
+/**
+ * A GaslessWallet `execute` entry: several calls the owner's deterministic
+ * wallet makes, authorized by **one** gateway-domain signature.
+ *
+ * The calls run **as the wallet contract**, not as the SYMMIO account — use it to
+ * move the wallet's own tokens (an ERC-20 `approve` followed by a bridge call,
+ * say), exactly as with `gaslessWalletExecute`.
+ */
+export interface GaslessBatchWalletExecute {
+    /** The calls the wallet makes, in order. Each is raw `data` or an `{ abi, functionName, args }` triple. */
+    walletCalls: readonly GaslessWalletCall[];
+    /**
+     * Which of the owner's GaslessWallets makes them. Defaults to `0n`, the
+     * original wallet. Each id is an independent wallet with its own address,
+     * balance and nonce stream.
+     */
+    walletId?: bigint;
+}
+/**
+ * One entry of a gasless batch: a relayable write — an ABI-level call
+ * ({@link GaslessBatchContractCall}) or raw calldata ({@link GaslessBatchRawCall}) —
+ * or a GaslessWallet `execute` ({@link GaslessBatchWalletExecute}). The forms mix
+ * freely in one batch.
+ *
+ * @example
+ * ```ts
+ * import type { GaslessBatchCall } from "@symmio/trading-core";
+ * import { erc20Abi } from "viem";
+ *
+ * const calls: GaslessBatchCall[] = [
+ *   { functionName: "allocate", args: [amount] },
+ *   { walletId: 1n, walletCalls: [{ target: usdc, abi: erc20Abi, functionName: "transfer", args: [to, value] }] },
+ * ];
+ * ```
+ */
+export type GaslessBatchCall = GaslessBatchContractCall | GaslessBatchRawCall | GaslessBatchWalletExecute;
+/**
+ * Whether a batch entry is a GaslessWallet `execute`.
+ *
+ * @internal
+ */
+export declare function isGaslessBatchWalletExecute(call: GaslessBatchCall): call is GaslessBatchWalletExecute;
+/**
+ * The calldata a relayable-write entry runs with — raw `data`, or the named
+ * call encoded against its own `abi` or, when it has none, the SDK's ABI for
+ * the relayable write of that name.
+ *
+ * @throws {SymmError} `GASLESS_NOT_RELAYABLE` when a call without an `abi` names no relayable write.
+ * @throws Viem's encoding error when the arguments do not encode.
+ *
+ * @internal
+ */
+export declare function gaslessBatchCallData(call: GaslessBatchContractCall | GaslessBatchRawCall): Hex;
+/**
+ * The 4-byte selector of a calldata blob, lowercased. Calldata shorter than a
+ * selector yields `0x00000000`, which no relayable write uses.
+ *
+ * @internal
+ */
+export declare function gaslessCallDataSelector(callData: Hex): Hex;
+/**
+ * The selectors a gasless batch runs — the delegation set a session key must
+ * hold to relay it on the batch's account: each relayable write's selector, and
+ * for every GaslessWallet entry the wallet-execution sentinel plus each inner
+ * call's selector. Lowercased and de-duplicated in first-seen order, because
+ * `grantDelegation` rejects a duplicate-bearing array.
+ *
+ * Selectors come from the **encoded** calldata, so an overloaded ABI resolves to
+ * the function that will actually run.
+ *
+ * A batch that contains `grantDelegation` must be owner-signed whatever this
+ * returns: the InstantLayer rejects a delegate-signed grant, so no delegation
+ * makes it relayable by a session key.
+ *
+ * @param calls - The batch, in any order.
+ * @returns The selector set, as `bytes4` hex.
+ * @throws Viem's encoding error when an ABI-level call does not encode.
+ *
+ * @example
+ * ```ts
+ * await grantDelegation(config, {
+ *   account: { addr: subAccount, isPartyB: false },
+ *   delegatedSigner: sessionKey,
+ *   selectors: getGaslessBatchSelectors(calls),
+ *   expiryTimestamp,
+ * });
+ * ```
+ */
+export declare function getGaslessBatchSelectors(calls: readonly GaslessBatchCall[]): readonly Hex[];
+//# sourceMappingURL=calls.d.ts.map

package/dist/gasless/batch/calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../../src/gasless/batch/calls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,GAAG,EAAoB,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAE7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAIzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,wBAAwB;IACvC,4GAA4G;IAC5G,GAAG,CAAC,EAAE,GAAG,GAAG,SAAS,OAAO,EAAE,CAAC;IAC/B,8FAA8F;IAC9F,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC3B;AAED,yFAAyF;AACzF,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,IAAI,EAAE,GAAG,CAAC;CACX;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,2GAA2G;IAC3G,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GAAG,wBAAwB,GAAG,mBAAmB,GAAG,yBAAyB,CAAC;AAE1G;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,IAAI,yBAAyB,CAErG;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,wBAAwB,GAAG,mBAAmB,GAAG,GAAG,CAI9F;AAcD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,GAAG,EAAE,CAmB3F"}

package/dist/gasless/batch/calls.js

@@ -0,0 +1,36 @@
+import { SymmError as e } from "../../shared/errors/symm-error.js";
+import { GASLESS_RELAYABLE_FUNCTIONS as t } from "../relayable-writes.js";
+import { getGaslessWalletExecuteSelectors as n } from "../gasless-wallet-execute/selectors.js";
+import { encodeFunctionData as r, size as i, slice as a } from "viem";
+//#region src/gasless/batch/calls.ts
+function o(e) {
+	return "walletCalls" in e;
+}
+function s(e) {
+	return "data" in e ? e.data : r({
+		abi: e.abi ?? [c(e.functionName)],
+		functionName: e.functionName,
+		args: e.args
+	});
+}
+function c(n) {
+	let r = t.get(n);
+	if (!r) throw new e("validation", "GASLESS_NOT_RELAYABLE", `Gasless: no relayable write is named "${n}". A batch carries the writes in GASLESS_RELAYABLE_SELECTORS; run any other call from the GaslessWallet as a \`walletCalls\` entry.`);
+	return r;
+}
+function l(e) {
+	return (i(e) < 4 ? "0x00000000" : a(e, 0, 4)).toLowerCase();
+}
+function u(e) {
+	let t = /* @__PURE__ */ new Set(), r = [], i = (e) => {
+		let n = e.toLowerCase();
+		t.has(n) || (t.add(n), r.push(n));
+	};
+	for (let t of e) if (o(t)) for (let e of n(t.walletCalls)) i(e);
+	else i(l(s(t)));
+	return r;
+}
+//#endregion
+export { s as gaslessBatchCallData, l as gaslessCallDataSelector, u as getGaslessBatchSelectors, o as isGaslessBatchWalletExecute };
+
+//# sourceMappingURL=calls.js.map

package/dist/gasless/batch/calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calls.js","names":[],"sources":["../../../src/gasless/batch/calls.ts"],"sourcesContent":["import { encodeFunctionData, size, slice, type Abi, type AbiFunction, type Hex } from \"viem\";\nimport { SymmError } from \"../../shared/errors/symm-error\";\nimport type { GaslessWalletCall } from \"../gasless-wallet-execute/calls\";\nimport { getGaslessWalletExecuteSelectors } from \"../gasless-wallet-execute/selectors\";\nimport { GASLESS_RELAYABLE_FUNCTIONS } from \"../relayable-writes\";\n\n/**\n * A relayable write named by its function, which the SDK encodes with viem's\n * `encodeFunctionData` — that throws on an arity or type mismatch, before any\n * signature prompt or network call.\n *\n * The target contract is **not** given: the SDK resolves it from the encoded\n * selector (the core diamond, the AccountLayer or the InstantLayer). The `abi`\n * is optional too — every relayable write is a known SYMMIO function, so\n * `{ functionName: \"allocate\", args: [amount] }` is enough. Pass an `abi` (the\n * SDK's own `symmioAbi`, `accountLayerAbi` or `instantLayerAbi`) when you\n * already hold it; the selector must still be a relayable write.\n *\n * `args` is deliberately `readonly unknown[]`, as for `GaslessWalletContractCall`.\n * When you want compile-time-checked arguments, encode with viem yourself and\n * pass the result as a {@link GaslessBatchRawCall}.\n */\nexport interface GaslessBatchContractCall {\n  /** ABI containing `functionName`. Omit it to use the SDK's own ABI for the relayable write of that name. */\n  abi?: Abi | readonly unknown[];\n  /** The relayable write to run — `\"allocate\"`, `\"initiateWithdraw\"`, `\"grantDelegation\"`, … */\n  functionName: string;\n  /** Arguments for `functionName`, in order. Omit for a no-argument function. */\n  args?: readonly unknown[];\n}\n\n/** A relayable write given as raw calldata; its selector decides the target contract. */\nexport interface GaslessBatchRawCall {\n  /** Calldata of a relayable write. */\n  data: Hex;\n}\n\n/**\n * A GaslessWallet `execute` entry: several calls the owner's deterministic\n * wallet makes, authorized by **one** gateway-domain signature.\n *\n * The calls run **as the wallet contract**, not as the SYMMIO account — use it to\n * move the wallet's own tokens (an ERC-20 `approve` followed by a bridge call,\n * say), exactly as with `gaslessWalletExecute`.\n */\nexport interface GaslessBatchWalletExecute {\n  /** The calls the wallet makes, in order. Each is raw `data` or an `{ abi, functionName, args }` triple. */\n  walletCalls: readonly GaslessWalletCall[];\n  /**\n   * Which of the owner's GaslessWallets makes them. Defaults to `0n`, the\n   * original wallet. Each id is an independent wallet with its own address,\n   * balance and nonce stream.\n   */\n  walletId?: bigint;\n}\n\n/**\n * One entry of a gasless batch: a relayable write — an ABI-level call\n * ({@link GaslessBatchContractCall}) or raw calldata ({@link GaslessBatchRawCall}) —\n * or a GaslessWallet `execute` ({@link GaslessBatchWalletExecute}). The forms mix\n * freely in one batch.\n *\n * @example\n * ```ts\n * import type { GaslessBatchCall } from \"@symmio/trading-core\";\n * import { erc20Abi } from \"viem\";\n *\n * const calls: GaslessBatchCall[] = [\n *   { functionName: \"allocate\", args: [amount] },\n *   { walletId: 1n, walletCalls: [{ target: usdc, abi: erc20Abi, functionName: \"transfer\", args: [to, value] }] },\n * ];\n * ```\n */\nexport type GaslessBatchCall = GaslessBatchContractCall | GaslessBatchRawCall | GaslessBatchWalletExecute;\n\n/**\n * Whether a batch entry is a GaslessWallet `execute`.\n *\n * @internal\n */\nexport function isGaslessBatchWalletExecute(call: GaslessBatchCall): call is GaslessBatchWalletExecute {\n  return \"walletCalls\" in call;\n}\n\n/**\n * The calldata a relayable-write entry runs with — raw `data`, or the named\n * call encoded against its own `abi` or, when it has none, the SDK's ABI for\n * the relayable write of that name.\n *\n * @throws {SymmError} `GASLESS_NOT_RELAYABLE` when a call without an `abi` names no relayable write.\n * @throws Viem's encoding error when the arguments do not encode.\n *\n * @internal\n */\nexport function gaslessBatchCallData(call: GaslessBatchContractCall | GaslessBatchRawCall): Hex {\n  if (\"data\" in call) return call.data;\n  const abi = call.abi ?? [relayableFunction(call.functionName)];\n  return encodeFunctionData({ abi: abi as Abi, functionName: call.functionName, args: call.args });\n}\n\nfunction relayableFunction(functionName: string): AbiFunction {\n  const item = GASLESS_RELAYABLE_FUNCTIONS.get(functionName);\n  if (!item) {\n    throw new SymmError(\n      \"validation\",\n      \"GASLESS_NOT_RELAYABLE\",\n      `Gasless: no relayable write is named \"${functionName}\". A batch carries the writes in GASLESS_RELAYABLE_SELECTORS; run any other call from the GaslessWallet as a \\`walletCalls\\` entry.`,\n    );\n  }\n  return item;\n}\n\n/**\n * The 4-byte selector of a calldata blob, lowercased. Calldata shorter than a\n * selector yields `0x00000000`, which no relayable write uses.\n *\n * @internal\n */\nexport function gaslessCallDataSelector(callData: Hex): Hex {\n  return (size(callData) < 4 ? \"0x00000000\" : slice(callData, 0, 4)).toLowerCase() as Hex;\n}\n\n/**\n * The selectors a gasless batch runs — the delegation set a session key must\n * hold to relay it on the batch's account: each relayable write's selector, and\n * for every GaslessWallet entry the wallet-execution sentinel plus each inner\n * call's selector. Lowercased and de-duplicated in first-seen order, because\n * `grantDelegation` rejects a duplicate-bearing array.\n *\n * Selectors come from the **encoded** calldata, so an overloaded ABI resolves to\n * the function that will actually run.\n *\n * A batch that contains `grantDelegation` must be owner-signed whatever this\n * returns: the InstantLayer rejects a delegate-signed grant, so no delegation\n * makes it relayable by a session key.\n *\n * @param calls - The batch, in any order.\n * @returns The selector set, as `bytes4` hex.\n * @throws Viem's encoding error when an ABI-level call does not encode.\n *\n * @example\n * ```ts\n * await grantDelegation(config, {\n *   account: { addr: subAccount, isPartyB: false },\n *   delegatedSigner: sessionKey,\n *   selectors: getGaslessBatchSelectors(calls),\n *   expiryTimestamp,\n * });\n * ```\n */\nexport function getGaslessBatchSelectors(calls: readonly GaslessBatchCall[]): readonly Hex[] {\n  const seen = new Set<Hex>();\n  const unique: Hex[] = [];\n  const add = (selector: Hex) => {\n    const normalized = selector.toLowerCase() as Hex;\n    if (seen.has(normalized)) return;\n    seen.add(normalized);\n    unique.push(normalized);\n  };\n\n  for (const call of calls) {\n    if (isGaslessBatchWalletExecute(call)) {\n      for (const selector of getGaslessWalletExecuteSelectors(call.walletCalls)) add(selector);\n    } else {\n      add(gaslessCallDataSelector(gaslessBatchCallData(call)));\n    }\n  }\n\n  return unique;\n}\n"],"mappings":";;;;;AAgFA,SAAgB,EAA4B,GAA2D;CACrG,OAAO,iBAAiB;AAC1B;AAYA,SAAgB,EAAqB,GAA2D;CAG9F,OAFI,UAAU,IAAa,EAAK,OAEzB,EAAmB;EAAO,KADrB,EAAK,OAAO,CAAC,EAAkB,EAAK,YAAY,CAAC;EAChB,cAAc,EAAK;EAAc,MAAM,EAAK;CAAK,CAAC;AACjG;AAEA,SAAS,EAAkB,GAAmC;CAC5D,IAAM,IAAO,EAA4B,IAAI,CAAY;CACzD,IAAI,CAAC,GACH,MAAM,IAAI,EACR,cACA,yBACA,yCAAyC,EAAa,oIACxD;CAEF,OAAO;AACT;AAQA,SAAgB,EAAwB,GAAoB;CAC1D,QAAQ,EAAK,CAAQ,IAAI,IAAI,eAAe,EAAM,GAAU,GAAG,CAAC,GAAG,YAAY;AACjF;AA8BA,SAAgB,EAAyB,GAAoD;CAC3F,IAAM,oBAAO,IAAI,IAAS,GACpB,IAAgB,CAAC,GACjB,KAAO,MAAkB;EAC7B,IAAM,IAAa,EAAS,YAAY;EACpC,EAAK,IAAI,CAAU,MACvB,EAAK,IAAI,CAAU,GACnB,EAAO,KAAK,CAAU;CACxB;CAEA,KAAK,IAAM,KAAQ,GACjB,IAAI,EAA4B,CAAI,GAClC,KAAK,IAAM,KAAY,EAAiC,EAAK,WAAW,GAAG,EAAI,CAAQ;MAEvF,EAAI,EAAwB,EAAqB,CAAI,CAAC,CAAC;CAI3D,OAAO;AACT"}

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

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

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

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

package/dist/gasless/batch/resolve-gasless-batch.d.ts

@@ -0,0 +1,118 @@
+import { Address, Hex } from 'viem';
+import { SymmioContractAddresses } from '../../core/chains/types.js';
+import { Config } from '../../core/config/index.js';
+import { SignedOperation } from '../../solvers/instant-open/shared/types.js';
+import { GaslessWalletCall } from '../gasless-wallet-execute/calls.js';
+import { GaslessBatchCall } from './calls.js';
+/** A relayable write, resolved to the contract the InstantLayer calls. @internal */
+export interface ResolvedGaslessInstantEntry {
+    type: "instant";
+    /** Contract the InstantLayer calls with `callData`. */
+    target: Address;
+    /** The write's calldata. */
+    callData: Hex;
+    /** The write's selector, lowercased. */
+    selector: Hex;
+    /** The write's stable workflow label (`"allocate"`, `"initiateWithdraw"`, …). */
+    operationType: string;
+}
+/** A GaslessWallet `execute` entry, encoded. @internal */
+export interface ResolvedGaslessWalletEntry {
+    type: "wallet";
+    /** The wallet id the entry executes from. */
+    walletId: bigint;
+    /** `GaslessWallet.execute(calls)` calldata. */
+    callData: Hex;
+    /** The inner calls, for the delegation pre-flight. */
+    walletCalls: readonly GaslessWalletCall[];
+}
+/** One batch entry, resolved and encoded, in relay order. @internal */
+export type ResolvedGaslessBatchEntry = ResolvedGaslessInstantEntry | ResolvedGaslessWalletEntry;
+/**
+ * Encode every batch entry and resolve each relayable write to its contract.
+ *
+ * Runs before any network call or signature prompt, so a malformed call, an
+ * invalid wallet id or a write the relayer cannot carry fails up front.
+ *
+ * @param addresses - The chain's contract addresses.
+ * @param calls - The batch, in relay order.
+ * @returns The resolved entries, in the same order.
+ * @throws {SymmError} `GASLESS_EMPTY_BATCH` for an empty batch.
+ * @throws {SymmError} `GASLESS_NOT_RELAYABLE` for a call whose selector is not a relayable write.
+ * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for a wallet id outside the `uint256` range.
+ * @throws Viem's encoding error when an ABI-level call does not encode.
+ *
+ * @internal
+ */
+export declare function resolveGaslessBatchEntries(addresses: SymmioContractAddresses, calls: readonly GaslessBatchCall[]): ResolvedGaslessBatchEntry[];
+/**
+ * The label a batch relays under by default: its entries' labels joined with
+ * `+` (`"approveOperationalFee+allocate"`), or `"gaslessBatch"` when that exceeds
+ * the service's 128 characters.
+ *
+ * @internal
+ */
+export declare function defaultGaslessBatchOperationType(entries: readonly ResolvedGaslessBatchEntry[]): string;
+/**
+ * The distinct wallet ids a batch's GaslessWallet entries execute from, in first-seen order.
+ *
+ * @internal
+ */
+export declare function distinctGaslessBatchWalletIds(entries: readonly ResolvedGaslessBatchEntry[]): bigint[];
+/**
+ * Read the address of each wallet a batch executes from — the signed `target`
+ * of its GaslessWallet entries.
+ *
+ * @param config - The SDK config.
+ * @param parameters - The chain, the wallets' owner, and the distinct wallet ids.
+ * @returns Each id's wallet address.
+ *
+ * @internal
+ */
+export declare function readGaslessBatchWalletTargets(config: Config, parameters: {
+    chainId: number;
+    owner: Address;
+    walletIds: readonly bigint[];
+}): Promise<Map<bigint, Address>>;
+/** Everything a batch's operations are built from, besides its entries. @internal */
+export interface GaslessBatchBuildContext {
+    /** The EIP-712 signer written into every operation. */
+    signer: Address;
+    /** The batch's account — every operation's `signerAccount.addr`. */
+    account: Address;
+    /** The signature deadline shared by every operation (unix seconds). */
+    deadline: bigint;
+    /** The InstantLayer nonce the account has consumed; the first relayable write signs `+ 1n`. */
+    instantNonce: bigint;
+    /** Each wallet id's address — the signed `target` of its entries. */
+    walletTargets: ReadonlyMap<bigint, Address>;
+    /** Each wallet id's consumed wallet-operation nonce; the first entry on it signs `+ 1n`. Omitted ids start at `0n`. */
+    walletNonces: ReadonlyMap<bigint, bigint>;
+    /** The replay salt of each operation, called once per operation in order. */
+    salt: () => Hex;
+}
+/** A batch's operations, ready to sign. @internal */
+export interface GaslessBatchOperations {
+    /** One operation per entry, in relay order. */
+    operations: SignedOperation[];
+    /** One wallet id per operation — `0n` for every relayable write. */
+    walletIds: bigint[];
+    /** The highest InstantLayer nonce the batch signs, or `null` when it has no relayable write. */
+    lastInstantNonce: bigint | null;
+    /** The highest wallet-operation nonce the batch signs on each wallet id. */
+    lastWalletNonces: Map<bigint, bigint>;
+}
+/**
+ * Build a batch's operations with sequential nonces on each stream: the
+ * relayable writes count up the account's InstantLayer stream, and each wallet
+ * id's entries count up that wallet's own stream.
+ *
+ * Every operation is the full InstantLayer `SignedOperation` shape — a wallet
+ * entry too, with no flex fields and `maxUses` 1, which is how the relay's ABI
+ * and wire format carry it. Only its **signature** covers the five-field
+ * gateway struct.
+ *
+ * @internal
+ */
+export declare function buildGaslessBatchOperations(entries: readonly ResolvedGaslessBatchEntry[], context: GaslessBatchBuildContext): GaslessBatchOperations;
+//# sourceMappingURL=resolve-gasless-batch.d.ts.map

package/dist/gasless/batch/resolve-gasless-batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-gasless-batch.d.ts","sourceRoot":"","sources":["../../../src/gasless/batch/resolve-gasless-batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAE/E,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAK5F,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,SAAS,CAAC;AAQjB,oFAAoF;AACpF,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,SAAS,CAAC;IAChB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,GAAG,CAAC;IACd,wCAAwC;IACxC,QAAQ,EAAE,GAAG,CAAC;IACd,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0DAA0D;AAC1D,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,GAAG,CAAC;IACd,sDAAsD;IACtD,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC3C;AAED,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GAAG,2BAA2B,GAAG,0BAA0B,CAAC;AAajG;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,uBAAuB,EAClC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GACjC,yBAAyB,EAAE,CAqC7B;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,SAAS,yBAAyB,EAAE,GAAG,MAAM,CAKtG;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,yBAAyB,EAAE,GAAG,MAAM,EAAE,CAErG;AAED;;;;;;;;;GASG;AACH,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,MAAM,EACd,UAAU,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC5E,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAM/B;AAED,qFAAqF;AACrF,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,uHAAuH;IACvH,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,IAAI,EAAE,MAAM,GAAG,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,oEAAoE;IACpE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gGAAgG;IAChG,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,4EAA4E;IAC5E,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,yBAAyB,EAAE,EAC7C,OAAO,EAAE,wBAAwB,GAChC,sBAAsB,CAuCxB"}

package/dist/gasless/batch/resolve-gasless-batch.js

@@ -0,0 +1,89 @@
+import { gaslessWalletAbi as e } from "../../symmio-contracts/abi/v0.8.6/gasless-wallet.js";
+import { SymmError as t } from "../../shared/errors/symm-error.js";
+import { buildSignedOperation as n } from "../../solvers/instant-open/shared/operations.js";
+import { assertGaslessWalletId as r } from "../wallet-id.js";
+import { GASLESS_RELAYABLE_WRITES as i } from "../relayable-writes.js";
+import { toWalletCallTuple as a } from "../gasless-wallet-execute/calls.js";
+import { gaslessBatchCallData as o, gaslessCallDataSelector as s, isGaslessBatchWalletExecute as c } from "./calls.js";
+import { getGaslessWalletAddress as l } from "../get-gasless-wallet-address/get-gasless-wallet-address.js";
+import { GASLESS_WALLET_EXECUTE_OPERATION_TYPE as u } from "../gasless-wallet-execute/gasless-wallet-execute.js";
+import { encodeFunctionData as d } from "viem";
+//#region src/gasless/batch/resolve-gasless-batch.ts
+var f = "gaslessBatch", p = 128;
+function m(e, t) {
+	switch (t) {
+		case "symmio": return e.symmioAddress;
+		case "accountLayer": return e.accountLayerAddress;
+		case "instantLayer": return e.instantLayerAddress;
+	}
+}
+function h(n, l) {
+	if (l.length === 0) throw new t("validation", "GASLESS_EMPTY_BATCH", "Gasless: a batch needs at least one call.");
+	return l.map((l, u) => {
+		if (c(l)) return {
+			type: "wallet",
+			walletId: r(l.walletId ?? 0n, `calls[${u}].walletId`),
+			callData: d({
+				abi: e,
+				functionName: "execute",
+				args: [l.walletCalls.map(a)]
+			}),
+			walletCalls: l.walletCalls
+		};
+		let f = o(l), p = s(f), h = i.get(p);
+		if (!h) throw new t("validation", "GASLESS_NOT_RELAYABLE", `Gasless: calls[${u}] (selector ${p}) is not a relayable write. A batch carries the writes in GASLESS_RELAYABLE_SELECTORS; run any other call from the GaslessWallet as a \`walletCalls\` entry.`);
+		return {
+			type: "instant",
+			target: m(n, h.target),
+			callData: f,
+			selector: p,
+			operationType: h.operationType
+		};
+	});
+}
+function g(e) {
+	let t = e.map((e) => e.type === "wallet" ? u : e.operationType).join("+");
+	return t.length <= p ? t : f;
+}
+function _(e) {
+	return [...new Set(e.flatMap((e) => e.type === "wallet" ? [e.walletId] : []))];
+}
+async function v(e, t) {
+	let { chainId: n, owner: r, walletIds: i } = t, a = await Promise.all(i.map((t) => l(e, {
+		chainId: n,
+		owner: r,
+		walletId: t
+	})));
+	return new Map(i.map((e, t) => [e, a[t]]));
+}
+function y(e, t) {
+	let r = [], i = [], a = null, o = /* @__PURE__ */ new Map();
+	for (let s of e) {
+		let e, c;
+		if (s.type === "instant") e = s.target, c = (a ?? t.instantNonce) + 1n, a = c, i.push(0n);
+		else {
+			let n = t.walletTargets.get(s.walletId);
+			if (n === void 0) throw Error(`gasless batch: no wallet address was resolved for wallet id ${s.walletId}.`);
+			e = n, c = (o.get(s.walletId) ?? t.walletNonces.get(s.walletId) ?? 0n) + 1n, o.set(s.walletId, c), i.push(s.walletId);
+		}
+		r.push(n({
+			signer: t.signer,
+			target: e,
+			callData: s.callData,
+			signerAccount: t.account,
+			deadline: t.deadline,
+			nonce: c,
+			salt: t.salt()
+		}));
+	}
+	return {
+		operations: r,
+		walletIds: i,
+		lastInstantNonce: a,
+		lastWalletNonces: o
+	};
+}
+//#endregion
+export { y as buildGaslessBatchOperations, g as defaultGaslessBatchOperationType, _ as distinctGaslessBatchWalletIds, v as readGaslessBatchWalletTargets, h as resolveGaslessBatchEntries };
+
+//# sourceMappingURL=resolve-gasless-batch.js.map

package/dist/gasless/batch/resolve-gasless-batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-gasless-batch.js","names":[],"sources":["../../../src/gasless/batch/resolve-gasless-batch.ts"],"sourcesContent":["import { encodeFunctionData, type Address, type Hex } from \"viem\";\nimport type { SymmioContractAddresses } from \"../../core/chains/types\";\nimport type { Config } from \"../../core/config\";\nimport { SymmError } from \"../../shared/errors/symm-error\";\nimport { buildSignedOperation } from \"../../solvers/instant-open/shared/operations\";\nimport type { SignedOperation } from \"../../solvers/instant-open/shared/types\";\nimport { gaslessWalletAbi } from \"../../symmio-contracts/abi/v0.8.6/gasless-wallet\";\nimport { toWalletCallTuple, type GaslessWalletCall } from \"../gasless-wallet-execute/calls\";\nimport { GASLESS_WALLET_EXECUTE_OPERATION_TYPE } from \"../gasless-wallet-execute/gasless-wallet-execute\";\nimport { getGaslessWalletAddress } from \"../get-gasless-wallet-address/get-gasless-wallet-address\";\nimport { GASLESS_RELAYABLE_WRITES, type GaslessRelayableTarget } from \"../relayable-writes\";\nimport { assertGaslessWalletId } from \"../wallet-id\";\nimport {\n  gaslessBatchCallData,\n  gaslessCallDataSelector,\n  isGaslessBatchWalletExecute,\n  type GaslessBatchCall,\n} from \"./calls\";\n\n/** The label a batch relays under when its entries' own labels do not fit the service's 128 characters. */\nconst GASLESS_BATCH_OPERATION_TYPE = \"gaslessBatch\";\n\n/** The service's limit on an `operationType` label. */\nconst GASLESS_OPERATION_TYPE_MAX_LENGTH = 128;\n\n/** A relayable write, resolved to the contract the InstantLayer calls. @internal */\nexport interface ResolvedGaslessInstantEntry {\n  type: \"instant\";\n  /** Contract the InstantLayer calls with `callData`. */\n  target: Address;\n  /** The write's calldata. */\n  callData: Hex;\n  /** The write's selector, lowercased. */\n  selector: Hex;\n  /** The write's stable workflow label (`\"allocate\"`, `\"initiateWithdraw\"`, …). */\n  operationType: string;\n}\n\n/** A GaslessWallet `execute` entry, encoded. @internal */\nexport interface ResolvedGaslessWalletEntry {\n  type: \"wallet\";\n  /** The wallet id the entry executes from. */\n  walletId: bigint;\n  /** `GaslessWallet.execute(calls)` calldata. */\n  callData: Hex;\n  /** The inner calls, for the delegation pre-flight. */\n  walletCalls: readonly GaslessWalletCall[];\n}\n\n/** One batch entry, resolved and encoded, in relay order. @internal */\nexport type ResolvedGaslessBatchEntry = ResolvedGaslessInstantEntry | ResolvedGaslessWalletEntry;\n\nfunction relayableTargetAddress(addresses: SymmioContractAddresses, target: GaslessRelayableTarget): Address {\n  switch (target) {\n    case \"symmio\":\n      return addresses.symmioAddress;\n    case \"accountLayer\":\n      return addresses.accountLayerAddress;\n    case \"instantLayer\":\n      return addresses.instantLayerAddress;\n  }\n}\n\n/**\n * Encode every batch entry and resolve each relayable write to its contract.\n *\n * Runs before any network call or signature prompt, so a malformed call, an\n * invalid wallet id or a write the relayer cannot carry fails up front.\n *\n * @param addresses - The chain's contract addresses.\n * @param calls - The batch, in relay order.\n * @returns The resolved entries, in the same order.\n * @throws {SymmError} `GASLESS_EMPTY_BATCH` for an empty batch.\n * @throws {SymmError} `GASLESS_NOT_RELAYABLE` for a call whose selector is not a relayable write.\n * @throws {SymmError} `GASLESS_WALLET_ID_INVALID` for a wallet id outside the `uint256` range.\n * @throws Viem's encoding error when an ABI-level call does not encode.\n *\n * @internal\n */\nexport function resolveGaslessBatchEntries(\n  addresses: SymmioContractAddresses,\n  calls: readonly GaslessBatchCall[],\n): ResolvedGaslessBatchEntry[] {\n  if (calls.length === 0) {\n    throw new SymmError(\"validation\", \"GASLESS_EMPTY_BATCH\", \"Gasless: a batch needs at least one call.\");\n  }\n\n  return calls.map((call, index): ResolvedGaslessBatchEntry => {\n    if (isGaslessBatchWalletExecute(call)) {\n      return {\n        type: \"wallet\",\n        walletId: assertGaslessWalletId(call.walletId ?? 0n, `calls[${index}].walletId`),\n        callData: encodeFunctionData({\n          abi: gaslessWalletAbi,\n          functionName: \"execute\",\n          args: [call.walletCalls.map(toWalletCallTuple)],\n        }),\n        walletCalls: call.walletCalls,\n      };\n    }\n\n    const callData = gaslessBatchCallData(call);\n    const selector = gaslessCallDataSelector(callData);\n    const write = GASLESS_RELAYABLE_WRITES.get(selector);\n    if (!write) {\n      throw new SymmError(\n        \"validation\",\n        \"GASLESS_NOT_RELAYABLE\",\n        `Gasless: calls[${index}] (selector ${selector}) is not a relayable write. A batch carries the writes in GASLESS_RELAYABLE_SELECTORS; run any other call from the GaslessWallet as a \\`walletCalls\\` entry.`,\n      );\n    }\n    return {\n      type: \"instant\",\n      target: relayableTargetAddress(addresses, write.target),\n      callData,\n      selector,\n      operationType: write.operationType,\n    };\n  });\n}\n\n/**\n * The label a batch relays under by default: its entries' labels joined with\n * `+` (`\"approveOperationalFee+allocate\"`), or `\"gaslessBatch\"` when that exceeds\n * the service's 128 characters.\n *\n * @internal\n */\nexport function defaultGaslessBatchOperationType(entries: readonly ResolvedGaslessBatchEntry[]): string {\n  const label = entries\n    .map((entry) => (entry.type === \"wallet\" ? GASLESS_WALLET_EXECUTE_OPERATION_TYPE : entry.operationType))\n    .join(\"+\");\n  return label.length <= GASLESS_OPERATION_TYPE_MAX_LENGTH ? label : GASLESS_BATCH_OPERATION_TYPE;\n}\n\n/**\n * The distinct wallet ids a batch's GaslessWallet entries execute from, in first-seen order.\n *\n * @internal\n */\nexport function distinctGaslessBatchWalletIds(entries: readonly ResolvedGaslessBatchEntry[]): bigint[] {\n  return [...new Set(entries.flatMap((entry) => (entry.type === \"wallet\" ? [entry.walletId] : [])))];\n}\n\n/**\n * Read the address of each wallet a batch executes from — the signed `target`\n * of its GaslessWallet entries.\n *\n * @param config - The SDK config.\n * @param parameters - The chain, the wallets' owner, and the distinct wallet ids.\n * @returns Each id's wallet address.\n *\n * @internal\n */\nexport async function readGaslessBatchWalletTargets(\n  config: Config,\n  parameters: { chainId: number; owner: Address; walletIds: readonly bigint[] },\n): Promise<Map<bigint, Address>> {\n  const { chainId, owner, walletIds } = parameters;\n  const addresses = await Promise.all(\n    walletIds.map((walletId) => getGaslessWalletAddress(config, { chainId, owner, walletId })),\n  );\n  return new Map(walletIds.map((walletId, index) => [walletId, addresses[index]!]));\n}\n\n/** Everything a batch's operations are built from, besides its entries. @internal */\nexport interface GaslessBatchBuildContext {\n  /** The EIP-712 signer written into every operation. */\n  signer: Address;\n  /** The batch's account — every operation's `signerAccount.addr`. */\n  account: Address;\n  /** The signature deadline shared by every operation (unix seconds). */\n  deadline: bigint;\n  /** The InstantLayer nonce the account has consumed; the first relayable write signs `+ 1n`. */\n  instantNonce: bigint;\n  /** Each wallet id's address — the signed `target` of its entries. */\n  walletTargets: ReadonlyMap<bigint, Address>;\n  /** Each wallet id's consumed wallet-operation nonce; the first entry on it signs `+ 1n`. Omitted ids start at `0n`. */\n  walletNonces: ReadonlyMap<bigint, bigint>;\n  /** The replay salt of each operation, called once per operation in order. */\n  salt: () => Hex;\n}\n\n/** A batch's operations, ready to sign. @internal */\nexport interface GaslessBatchOperations {\n  /** One operation per entry, in relay order. */\n  operations: SignedOperation[];\n  /** One wallet id per operation — `0n` for every relayable write. */\n  walletIds: bigint[];\n  /** The highest InstantLayer nonce the batch signs, or `null` when it has no relayable write. */\n  lastInstantNonce: bigint | null;\n  /** The highest wallet-operation nonce the batch signs on each wallet id. */\n  lastWalletNonces: Map<bigint, bigint>;\n}\n\n/**\n * Build a batch's operations with sequential nonces on each stream: the\n * relayable writes count up the account's InstantLayer stream, and each wallet\n * id's entries count up that wallet's own stream.\n *\n * Every operation is the full InstantLayer `SignedOperation` shape — a wallet\n * entry too, with no flex fields and `maxUses` 1, which is how the relay's ABI\n * and wire format carry it. Only its **signature** covers the five-field\n * gateway struct.\n *\n * @internal\n */\nexport function buildGaslessBatchOperations(\n  entries: readonly ResolvedGaslessBatchEntry[],\n  context: GaslessBatchBuildContext,\n): GaslessBatchOperations {\n  const operations: SignedOperation[] = [];\n  const walletIds: bigint[] = [];\n  let lastInstantNonce: bigint | null = null;\n  const lastWalletNonces = new Map<bigint, bigint>();\n\n  for (const entry of entries) {\n    let target: Address;\n    let nonce: bigint;\n    if (entry.type === \"instant\") {\n      target = entry.target;\n      nonce = (lastInstantNonce ?? context.instantNonce) + 1n;\n      lastInstantNonce = nonce;\n      walletIds.push(0n);\n    } else {\n      const walletTarget = context.walletTargets.get(entry.walletId);\n      if (walletTarget === undefined) {\n        throw new Error(`gasless batch: no wallet address was resolved for wallet id ${entry.walletId}.`);\n      }\n      target = walletTarget;\n      nonce = (lastWalletNonces.get(entry.walletId) ?? context.walletNonces.get(entry.walletId) ?? 0n) + 1n;\n      lastWalletNonces.set(entry.walletId, nonce);\n      walletIds.push(entry.walletId);\n    }\n\n    operations.push(\n      buildSignedOperation({\n        signer: context.signer,\n        target,\n        callData: entry.callData,\n        signerAccount: context.account,\n        deadline: context.deadline,\n        nonce,\n        salt: context.salt(),\n      }),\n    );\n  }\n\n  return { operations, walletIds, lastInstantNonce, lastWalletNonces };\n}\n"],"mappings":";;;;;;;;;;;AAoBA,IAAM,IAA+B,gBAG/B,IAAoC;AA6B1C,SAAS,EAAuB,GAAoC,GAAyC;CAC3G,QAAQ,GAAR;EACE,KAAK,UACH,OAAO,EAAU;EACnB,KAAK,gBACH,OAAO,EAAU;EACnB,KAAK,gBACH,OAAO,EAAU;CACrB;AACF;AAkBA,SAAgB,EACd,GACA,GAC6B;CAC7B,IAAI,EAAM,WAAW,GACnB,MAAM,IAAI,EAAU,cAAc,uBAAuB,2CAA2C;CAGtG,OAAO,EAAM,KAAK,GAAM,MAAqC;EAC3D,IAAI,EAA4B,CAAI,GAClC,OAAO;GACL,MAAM;GACN,UAAU,EAAsB,EAAK,YAAY,IAAI,SAAS,EAAM,WAAW;GAC/E,UAAU,EAAmB;IAC3B,KAAK;IACL,cAAc;IACd,MAAM,CAAC,EAAK,YAAY,IAAI,CAAiB,CAAC;GAChD,CAAC;GACD,aAAa,EAAK;EACpB;EAGF,IAAM,IAAW,EAAqB,CAAI,GACpC,IAAW,EAAwB,CAAQ,GAC3C,IAAQ,EAAyB,IAAI,CAAQ;EACnD,IAAI,CAAC,GACH,MAAM,IAAI,EACR,cACA,yBACA,kBAAkB,EAAM,cAAc,EAAS,6JACjD;EAEF,OAAO;GACL,MAAM;GACN,QAAQ,EAAuB,GAAW,EAAM,MAAM;GACtD;GACA;GACA,eAAe,EAAM;EACvB;CACF,CAAC;AACH;AASA,SAAgB,EAAiC,GAAuD;CACtG,IAAM,IAAQ,EACX,KAAK,MAAW,EAAM,SAAS,WAAW,IAAwC,EAAM,aAAc,EACtG,KAAK,GAAG;CACX,OAAO,EAAM,UAAU,IAAoC,IAAQ;AACrE;AAOA,SAAgB,EAA8B,GAAyD;CACrG,OAAO,CAAC,GAAG,IAAI,IAAI,EAAQ,SAAS,MAAW,EAAM,SAAS,WAAW,CAAC,EAAM,QAAQ,IAAI,CAAC,CAAE,CAAC,CAAC;AACnG;AAYA,eAAsB,EACpB,GACA,GAC+B;CAC/B,IAAM,EAAE,YAAS,UAAO,iBAAc,GAChC,IAAY,MAAM,QAAQ,IAC9B,EAAU,KAAK,MAAa,EAAwB,GAAQ;EAAE;EAAS;EAAO;CAAS,CAAC,CAAC,CAC3F;CACA,OAAO,IAAI,IAAI,EAAU,KAAK,GAAU,MAAU,CAAC,GAAU,EAAU,EAAO,CAAC,CAAC;AAClF;AA4CA,SAAgB,EACd,GACA,GACwB;CACxB,IAAM,IAAgC,CAAC,GACjC,IAAsB,CAAC,GACzB,IAAkC,MAChC,oBAAmB,IAAI,IAAoB;CAEjD,KAAK,IAAM,KAAS,GAAS;EAC3B,IAAI,GACA;EACJ,IAAI,EAAM,SAAS,WAIjB,AAHA,IAAS,EAAM,QACf,KAAS,KAAoB,EAAQ,gBAAgB,IACrD,IAAmB,GACnB,EAAU,KAAK,EAAE;OACZ;GACL,IAAM,IAAe,EAAQ,cAAc,IAAI,EAAM,QAAQ;GAC7D,IAAI,MAAiB,KAAA,GACnB,MAAU,MAAM,+DAA+D,EAAM,SAAS,EAAE;GAKlG,AAHA,IAAS,GACT,KAAS,EAAiB,IAAI,EAAM,QAAQ,KAAK,EAAQ,aAAa,IAAI,EAAM,QAAQ,KAAK,MAAM,IACnG,EAAiB,IAAI,EAAM,UAAU,CAAK,GAC1C,EAAU,KAAK,EAAM,QAAQ;EAC/B;EAEA,EAAW,KACT,EAAqB;GACnB,QAAQ,EAAQ;GAChB;GACA,UAAU,EAAM;GAChB,eAAe,EAAQ;GACvB,UAAU,EAAQ;GAClB;GACA,MAAM,EAAQ,KAAK;EACrB,CAAC,CACH;CACF;CAEA,OAAO;EAAE;EAAY;EAAW;EAAkB;CAAiB;AACrE"}

package/dist/gasless/classify-gasless-failure.d.ts

@@ -0,0 +1,99 @@
+import { Abi, DecodeErrorResultReturnType, Hex } from 'viem';
+/**
+ * Why a gasless action failed, in terms of what a UI can do about it.
+ *
+ * Deliberately coarser than the vendor's codes and finer than the HTTP status:
+ * `INSUFFICIENT_ALLOWANCE` and an `OperationalFee: Allowance exceeded` revert
+ * are the same problem with two wire shapes, while a `404` for an unknown
+ * instance and a `404` for an unknown request id are not the same problem at
+ * all.
+ *
+ * - `"payer-balance"` — the billing account cannot cover the fee. Top up its
+ *   SYMMIO collateral; raising the allowance alone does nothing.
+ * - `"fee-allowance"` — the payer's operational-fee allowance is too low.
+ *   Approve more with `approveOperationalFee`, then re-read.
+ * - `"free-quota"` — the daily free-operations quota is spent and the
+ *   deployment refuses paid ones. Wait for the UTC reset or use the wallet.
+ * - `"fee-limit"` — the fee policy refused the request for any other reason.
+ * - `"failed-operation"` — one entry of the batch reverted; decode it with
+ *   {@link decodeGaslessOperationFailure} to name the real cause.
+ * - `"nonce-or-deadline"` — the signature is stale. Refresh the nonce and
+ *   deadline and ask for a new one; never resend the old payload.
+ * - `"deposit-below-minimum"` — the deposit address holds less than the
+ *   settlement minimum, or the funds are not visible yet.
+ * - `"deposit-not-above-fees"` — the balance clears the minimum but not the
+ *   deposit and wallet-creation fees.
+ * - `"idempotency-conflict"` — the key belongs to another workflow; mint a new one.
+ * - `"client-schema"` — a `422`: the payload's shape is wrong. A client bug.
+ * - `"rate-limited"` / `"unauthorized"` / `"forbidden"` / `"unknown-instance"` /
+ *   `"gateway-unavailable"` — the gateway answered, before any service saw it.
+ * - `"submit-unconfirmed"` — the outcome is unknown and the request may be
+ *   executing. Replay it with `resubmitGaslessRequest`; never re-run the intent.
+ * - `"simulation-reverted"` — the service simulated the batch and it reverted
+ *   for a reason none of the above explains. Rebuild and re-sign.
+ * - `"unknown"` — nothing classified it.
+ */
+export type GaslessFailureReason = "payer-balance" | "fee-allowance" | "free-quota" | "fee-limit" | "failed-operation" | "nonce-or-deadline" | "deposit-below-minimum" | "deposit-not-above-fees" | "idempotency-conflict" | "client-schema" | "rate-limited" | "unauthorized" | "forbidden" | "unknown-instance" | "gateway-unavailable" | "submit-unconfirmed" | "simulation-reverted" | "unknown";
+/**
+ * Classify any gasless failure into the one reason a UI should act on.
+ *
+ * The order is deliberate: what the request *did* (unconfirmed, conflicting)
+ * outranks what the service *said*, which outranks what the gateway answered —
+ * a `400 SIMULATION_REVERTED` whose revert names an allowance shortfall is an
+ * allowance problem, not a "bad request".
+ *
+ * Works on the error a framework layer re-wrapped too, so a React hook's
+ * `SymmioRequestError` classifies exactly like the `SymmApiError` under it.
+ *
+ * @param err - Anything caught from a gasless action, or a polled record error.
+ * @returns The reason, or `"unknown"` when nothing identifies it.
+ *
+ * @example
+ * ```ts
+ * switch (classifyGaslessFailure(err)) {
+ *   case "fee-allowance":
+ *     return showApproveOperationalFee();
+ *   case "submit-unconfirmed":
+ *     return showReconcilePending(getGaslessUnconfirmedSubmit(err));
+ *   default:
+ *     return showDiagnostics(parseGaslessErrorDetail(err));
+ * }
+ * ```
+ */
+export declare function classifyGaslessFailure(err: unknown): GaslessFailureReason;
+/**
+ * The failing batch entry of an `OperationFailed` revert, with its inner revert
+ * decoded against the ABI you supplied.
+ */
+export interface GaslessDecodedOperationFailure {
+    /** Zero-based position of the failing operation in the submitted batch. */
+    index: number;
+    /** The inner revert data, exactly as the service reported it. */
+    revertData: Hex;
+    /** The decoded error, or `null` when the ABI does not describe it. */
+    decoded: DecodeErrorResultReturnType | null;
+}
+/**
+ * Identify the batch entry that reverted, and decode its inner revert.
+ *
+ * A relayed batch is atomic, so the InstantLayer reports an inner failure as
+ * `OperationFailed(operationIndex, revertData)` — which names a position, not a
+ * cause. Decoding `revertData` against the ABI of the contract that operation
+ * targeted turns it back into the error the user can act on
+ * (`InvalidNameLength`, `InsufficientBalance`, …).
+ *
+ * @param err - Anything caught from a gasless submit.
+ * @param abi - ABI of the contract the failing operation targeted.
+ * @returns The index, the raw revert data and the decoded error, or `null` when
+ *   the failure was not an `OperationFailed`.
+ *
+ * @example
+ * ```ts
+ * const failure = decodeGaslessOperationFailure(err, accountLayerAbi);
+ * if (failure) {
+ *   console.error(`operation ${failure.index} reverted:`, failure.decoded?.errorName ?? failure.revertData);
+ * }
+ * ```
+ */
+export declare function decodeGaslessOperationFailure(err: unknown, abi: Abi): GaslessDecodedOperationFailure | null;
+//# sourceMappingURL=classify-gasless-failure.d.ts.map

package/dist/gasless/classify-gasless-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-gasless-failure.d.ts","sourceRoot":"","sources":["../../src/gasless/classify-gasless-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,GAAG,EAAE,KAAK,2BAA2B,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAM/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,oBAAoB,GAC5B,eAAe,GACf,eAAe,GACf,YAAY,GACZ,WAAW,GACX,kBAAkB,GAClB,mBAAmB,GACnB,uBAAuB,GACvB,wBAAwB,GACxB,sBAAsB,GACtB,eAAe,GACf,cAAc,GACd,cAAc,GACd,WAAW,GACX,kBAAkB,GAClB,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,SAAS,CAAC;AAyEd;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CAkBzE;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,UAAU,EAAE,GAAG,CAAC;IAChB,sEAAsE;IACtE,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,8BAA8B,GAAG,IAAI,CAY3G"}