@metamask/snap-networks-utils 1.0.0 → 2.0.0

package/dist/utils/state/InMemoryState.mjs

@@ -0,0 +1,38 @@
+import $lodash from "lodash";
+const { get, set, unset } = $lodash;
+/**
+ * A simple implementation of the `IStateManager` interface that relies on an in-memory
+ * state. Intended for tests.
+ */
+export class InMemoryState {
+    #state;
+    constructor(initialState) {
+        this.#state = initialState;
+    }
+    async get() {
+        return this.#state;
+    }
+    async getKey(key) {
+        return get(this.#state, key);
+    }
+    async setKey(key, value) {
+        set(this.#state, key, value);
+    }
+    async setKeyWith(key, updater) {
+        const oldValue = get(this.#state, key);
+        set(this.#state, key, updater(oldValue));
+    }
+    async update(callback) {
+        this.#state = callback(this.#state);
+        return this.#state;
+    }
+    async deleteKey(key) {
+        unset(this.#state, key);
+    }
+    async deleteKeys(keys) {
+        keys.forEach((key) => {
+            unset(this.#state, key);
+        });
+    }
+}
+//# sourceMappingURL=InMemoryState.mjs.map

package/dist/utils/state/InMemoryState.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryState.mjs","sourceRoot":"","sources":["../../../src/utils/state/InMemoryState.ts"],"names":[],"mappings":";;AAKA;;;GAGG;AACH,MAAM,OAAO,aAAa;IAGxB,MAAM,CAAc;IAEpB,YAAY,YAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,MAAM,CACV,GAAW;QAEX,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAA0B,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,KAAmB;QAC3C,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,UAAU,CACd,GAAW,EACX,OAAqD;QAErD,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAuB,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,MAAM,CACV,QAA6C;QAE7C,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,GAAW;QACzB,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,IAAc;QAC7B,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YACnB,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import { get, set, unset } from 'lodash';\n\nimport type { Serializable } from '../serialization/types';\nimport type { IStateManager } from './IStateManager';\n\n/**\n * A simple implementation of the `IStateManager` interface that relies on an in-memory\n * state. Intended for tests.\n */\nexport class InMemoryState<\n  TStateValue extends Record<string, Serializable>,\n> implements IStateManager<TStateValue> {\n  #state: TStateValue;\n\n  constructor(initialState: TStateValue) {\n    this.#state = initialState;\n  }\n\n  async get(): Promise<TStateValue> {\n    return this.#state;\n  }\n\n  async getKey<TResponse extends Serializable>(\n    key: string,\n  ): Promise<TResponse | undefined> {\n    return get(this.#state, key) as TResponse | undefined;\n  }\n\n  async setKey(key: string, value: Serializable): Promise<void> {\n    set(this.#state, key, value);\n  }\n\n  async setKeyWith<TValue extends Serializable>(\n    key: string,\n    updater: (currentValue: TValue | undefined) => TValue,\n  ): Promise<void> {\n    const oldValue = get(this.#state, key) as TValue | undefined;\n    set(this.#state, key, updater(oldValue));\n  }\n\n  async update(\n    callback: (state: TStateValue) => TStateValue,\n  ): Promise<TStateValue> {\n    this.#state = callback(this.#state);\n    return this.#state;\n  }\n\n  async deleteKey(key: string): Promise<void> {\n    unset(this.#state, key);\n  }\n\n  async deleteKeys(keys: string[]): Promise<void> {\n    keys.forEach((key) => {\n      unset(this.#state, key);\n    });\n  }\n}\n"]}

package/dist/utils/state/State.cjs

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.State = void 0;
+const async_mutex_1 = require("async-mutex");
+const lodash_1 = require("lodash");
+const safeMerge_1 = require("../safeMerge/safeMerge.cjs");
+const serialization_1 = require("../serialization/serialization.cjs");
+/**
+ * Resolves the Snap RPC client from the global `snap` object provided by the Snap runtime.
+ *
+ * @returns The Snap `request` function.
+ */
+const getSnapRequest = () => globalThis.snap.request;
+/**
+ * Because we use both snap_manageState and snap_setState, we must protect against them
+ * being used at the same time. We must also protect against multiple parallel requests
+ * to snap_manageState.
+ *
+ * Path writes (`setKey` / `setKeyWith`) are serialized with a dedicated write mutex so
+ * concurrent read-modify-write updates cannot interleave. Path reads may still run in
+ * parallel with each other. A blob (`snap_manageState`) operation waits for in-flight path
+ * operations to finish and blocks new ones from starting until it completes.
+ */
+class StateLock {
+    // Gate every operation must pass through to start. Path operations hold it only while
+    // registering; a blob operation holds it for its whole duration, so no path operation
+    // can start after a blob operation begins waiting for in-flight ones to finish.
+    #operationAdmissionMutex = new async_mutex_1.Mutex();
+    // Held while at least one path operation is in flight.
+    #regularStateUpdateMutex = new async_mutex_1.Mutex();
+    #regularStateWriteMutex = new async_mutex_1.Mutex();
+    #pendingRegularStateUpdates = 0;
+    #releaseRegularStateUpdateMutex = null;
+    async #acquireRegularStateUpdateMutex() {
+        if (!this.#regularStateUpdateMutex.isLocked()) {
+            this.#releaseRegularStateUpdateMutex =
+                await this.#regularStateUpdateMutex.acquire();
+        }
+    }
+    async wrapRegularStateOperation(callback) {
+        await this.#operationAdmissionMutex.runExclusive(async () => {
+            await this.#acquireRegularStateUpdateMutex();
+            this.#pendingRegularStateUpdates += 1;
+        });
+        try {
+            return await callback();
+        }
+        finally {
+            this.#pendingRegularStateUpdates -= 1;
+            if (this.#pendingRegularStateUpdates === 0 &&
+                this.#releaseRegularStateUpdateMutex) {
+                this.#releaseRegularStateUpdateMutex();
+                this.#releaseRegularStateUpdateMutex = null;
+            }
+        }
+    }
+    async wrapRegularStateWriteOperation(callback) {
+        return await this.#regularStateWriteMutex.runExclusive(async () => this.wrapRegularStateOperation(callback));
+    }
+    async wrapManageStateOperation(callback) {
+        return await this.#operationAdmissionMutex.runExclusive(async () => {
+            await this.#regularStateUpdateMutex.waitForUnlock();
+            return await callback();
+        });
+    }
+}
+/**
+ * Layer on top of `snap_manageState` / `snap_getState` / `snap_setState`:
+ *
+ * - Serializes values before storing them and deserializes after reading.
+ * - Merges `defaultState` on full-blob reads via `safeMerge`.
+ * - Serializes path writes and full-blob updates (lock strategy B).
+ */
+class State {
+    #lock = new StateLock();
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Reads and deserializes the value at `key`, or the whole state blob when `key` is omitted.
+     *
+     * @param key - The JSON-path key to read. Omit to read the whole blob.
+     * @returns The deserialized value, or `undefined` when the key is absent.
+     */
+    async #read(key) {
+        const value = await getSnapRequest()({
+            method: 'snap_getState',
+            params: {
+                ...(key === undefined ? {} : { key }),
+                encrypted: this.#config.encrypted,
+            },
+        });
+        return value === null || value === undefined
+            ? undefined
+            : (0, serialization_1.deserialize)(value);
+    }
+    /**
+     * Serializes `value` and writes it to `key`.
+     *
+     * @param key - The JSON-path key to write.
+     * @param value - The value to store.
+     */
+    async #write(key, value) {
+        await getSnapRequest()({
+            method: 'snap_setState',
+            params: {
+                key,
+                value: (0, serialization_1.serialize)(value),
+                encrypted: this.#config.encrypted,
+            },
+        });
+    }
+    async #unsafeGet() {
+        const state = (await this.#read()) ?? {};
+        // Clone the defaults so updaters that mutate the returned state (e.g. `deleteKey`
+        // via lodash `unset`) never leak into the shared `defaultState` object.
+        return (0, safeMerge_1.safeMerge)((0, lodash_1.cloneDeep)(this.#config.defaultState), state);
+    }
+    async get() {
+        return this.#lock.wrapRegularStateOperation(async () => this.#unsafeGet());
+    }
+    async getKey(key) {
+        return this.#lock.wrapRegularStateOperation(async () => this.#read(key));
+    }
+    async setKey(key, value) {
+        await this.#lock.wrapRegularStateWriteOperation(async () => this.#write(key, value));
+    }
+    async setKeyWith(key, updater) {
+        await this.#lock.wrapRegularStateWriteOperation(async () => this.#write(key, updater(await this.#read(key))));
+    }
+    async update(updaterFunction) {
+        return await this.#lock.wrapManageStateOperation(async () => {
+            const newState = updaterFunction(await this.#unsafeGet());
+            await getSnapRequest()({
+                method: 'snap_manageState',
+                params: {
+                    operation: 'update',
+                    newState: (0, serialization_1.serialize)(newState),
+                    encrypted: this.#config.encrypted,
+                },
+            });
+            return newState;
+        });
+    }
+    async deleteKey(key) {
+        await this.deleteKeys([key]);
+    }
+    async deleteKeys(keys) {
+        await this.update((state) => {
+            keys.forEach((key) => {
+                (0, lodash_1.unset)(state, key);
+            });
+            return state;
+        });
+    }
+}
+exports.State = State;
+//# sourceMappingURL=State.cjs.map

package/dist/utils/state/State.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.cjs","sourceRoot":"","sources":["../../../src/utils/state/State.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Json, SnapsProvider } from '@metamask/snaps-sdk';\nimport type { MutexInterface } from 'async-mutex';\nimport { Mutex } from 'async-mutex';\nimport { cloneDeep, unset } from 'lodash';\n\nimport { safeMerge } from '../safeMerge/safeMerge';\nimport { deserialize, serialize } from '../serialization/serialization';\nimport type { Serializable } from '../serialization/types';\nimport type { IStateManager } from './IStateManager';\n\nexport type StateConfig<TValue extends Record<string, Serializable>> = {\n  encrypted: boolean;\n  defaultState: TValue;\n};\n\n/**\n * Resolves the Snap RPC client from the global `snap` object provided by the Snap runtime.\n *\n * @returns The Snap `request` function.\n */\nconst getSnapRequest = (): SnapsProvider['request'] =>\n  (globalThis as typeof globalThis & { snap: SnapsProvider }).snap.request;\n\n/**\n * Because we use both snap_manageState and snap_setState, we must protect against them\n * being used at the same time. We must also protect against multiple parallel requests\n * to snap_manageState.\n *\n * Path writes (`setKey` / `setKeyWith`) are serialized with a dedicated write mutex so\n * concurrent read-modify-write updates cannot interleave. Path reads may still run in\n * parallel with each other. A blob (`snap_manageState`) operation waits for in-flight path\n * operations to finish and blocks new ones from starting until it completes.\n */\nclass StateLock {\n  // Gate every operation must pass through to start. Path operations hold it only while\n  // registering; a blob operation holds it for its whole duration, so no path operation\n  // can start after a blob operation begins waiting for in-flight ones to finish.\n  readonly #operationAdmissionMutex = new Mutex();\n\n  // Held while at least one path operation is in flight.\n  readonly #regularStateUpdateMutex = new Mutex();\n\n  readonly #regularStateWriteMutex = new Mutex();\n\n  #pendingRegularStateUpdates = 0;\n\n  #releaseRegularStateUpdateMutex: MutexInterface.Releaser | null = null;\n\n  async #acquireRegularStateUpdateMutex(): Promise<void> {\n    if (!this.#regularStateUpdateMutex.isLocked()) {\n      this.#releaseRegularStateUpdateMutex =\n        await this.#regularStateUpdateMutex.acquire();\n    }\n  }\n\n  async wrapRegularStateOperation<ReturnType>(\n    callback: MutexInterface.Worker<ReturnType>,\n  ): Promise<ReturnType> {\n    await this.#operationAdmissionMutex.runExclusive(async () => {\n      await this.#acquireRegularStateUpdateMutex();\n      this.#pendingRegularStateUpdates += 1;\n    });\n\n    try {\n      return await callback();\n    } finally {\n      this.#pendingRegularStateUpdates -= 1;\n\n      if (\n        this.#pendingRegularStateUpdates === 0 &&\n        this.#releaseRegularStateUpdateMutex\n      ) {\n        this.#releaseRegularStateUpdateMutex();\n        this.#releaseRegularStateUpdateMutex = null;\n      }\n    }\n  }\n\n  async wrapRegularStateWriteOperation<ReturnType>(\n    callback: MutexInterface.Worker<ReturnType>,\n  ): Promise<ReturnType> {\n    return await this.#regularStateWriteMutex.runExclusive(async () =>\n      this.wrapRegularStateOperation(callback),\n    );\n  }\n\n  async wrapManageStateOperation<ReturnType>(\n    callback: MutexInterface.Worker<ReturnType>,\n  ): Promise<ReturnType> {\n    return await this.#operationAdmissionMutex.runExclusive(async () => {\n      await this.#regularStateUpdateMutex.waitForUnlock();\n\n      return await callback();\n    });\n  }\n}\n\n/**\n * Layer on top of `snap_manageState` / `snap_getState` / `snap_setState`:\n *\n * - Serializes values before storing them and deserializes after reading.\n * - Merges `defaultState` on full-blob reads via `safeMerge`.\n * - Serializes path writes and full-blob updates (lock strategy B).\n */\nexport class State<\n  TStateValue extends Record<string, Serializable>,\n> implements IStateManager<TStateValue> {\n  readonly #lock = new StateLock();\n\n  readonly #config: StateConfig<TStateValue>;\n\n  constructor(config: StateConfig<TStateValue>) {\n    this.#config = config;\n  }\n\n  /**\n   * Reads and deserializes the value at `key`, or the whole state blob when `key` is omitted.\n   *\n   * @param key - The JSON-path key to read. Omit to read the whole blob.\n   * @returns The deserialized value, or `undefined` when the key is absent.\n   */\n  async #read<TValue extends Serializable>(\n    key?: string,\n  ): Promise<TValue | undefined> {\n    const value = await getSnapRequest()({\n      method: 'snap_getState',\n      params: {\n        ...(key === undefined ? {} : { key }),\n        encrypted: this.#config.encrypted,\n      },\n    });\n\n    return value === null || value === undefined\n      ? undefined\n      : (deserialize(value) as TValue);\n  }\n\n  /**\n   * Serializes `value` and writes it to `key`.\n   *\n   * @param key - The JSON-path key to write.\n   * @param value - The value to store.\n   */\n  async #write(key: string, value: Serializable): Promise<void> {\n    await getSnapRequest()({\n      method: 'snap_setState',\n      params: {\n        key,\n        value: serialize(value),\n        encrypted: this.#config.encrypted,\n      },\n    });\n  }\n\n  async #unsafeGet(): Promise<TStateValue> {\n    const state = (await this.#read<TStateValue>()) ?? ({} as TStateValue);\n\n    // Clone the defaults so updaters that mutate the returned state (e.g. `deleteKey`\n    // via lodash `unset`) never leak into the shared `defaultState` object.\n    return safeMerge(cloneDeep(this.#config.defaultState), state);\n  }\n\n  async get(): Promise<TStateValue> {\n    return this.#lock.wrapRegularStateOperation(async () => this.#unsafeGet());\n  }\n\n  async getKey<TResponse extends Serializable>(\n    key: string,\n  ): Promise<TResponse | undefined> {\n    return this.#lock.wrapRegularStateOperation(async () =>\n      this.#read<TResponse>(key),\n    );\n  }\n\n  async setKey(key: string, value: Serializable): Promise<void> {\n    await this.#lock.wrapRegularStateWriteOperation(async () =>\n      this.#write(key, value),\n    );\n  }\n\n  async setKeyWith<TValue extends Serializable>(\n    key: string,\n    updater: (currentValue: TValue | undefined) => TValue,\n  ): Promise<void> {\n    await this.#lock.wrapRegularStateWriteOperation(async () =>\n      this.#write(key, updater(await this.#read<TValue>(key))),\n    );\n  }\n\n  async update(\n    updaterFunction: (state: TStateValue) => TStateValue,\n  ): Promise<TStateValue> {\n    return await this.#lock.wrapManageStateOperation(async () => {\n      const newState = updaterFunction(await this.#unsafeGet());\n\n      await getSnapRequest()({\n        method: 'snap_manageState',\n        params: {\n          operation: 'update',\n          newState: serialize(newState) as Record<string, Json>,\n          encrypted: this.#config.encrypted,\n        },\n      });\n\n      return newState;\n    });\n  }\n\n  async deleteKey(key: string): Promise<void> {\n    await this.deleteKeys([key]);\n  }\n\n  async deleteKeys(keys: string[]): Promise<void> {\n    await this.update((state) => {\n      keys.forEach((key) => {\n        unset(state, key);\n      });\n      return state;\n    });\n  }\n}\n"]}

package/dist/utils/state/State.d.cts

@@ -0,0 +1,25 @@
+import type { Serializable } from "../serialization/types.cjs";
+import type { IStateManager } from "./IStateManager.cjs";
+export type StateConfig<TValue extends Record<string, Serializable>> = {
+    encrypted: boolean;
+    defaultState: TValue;
+};
+/**
+ * Layer on top of `snap_manageState` / `snap_getState` / `snap_setState`:
+ *
+ * - Serializes values before storing them and deserializes after reading.
+ * - Merges `defaultState` on full-blob reads via `safeMerge`.
+ * - Serializes path writes and full-blob updates (lock strategy B).
+ */
+export declare class State<TStateValue extends Record<string, Serializable>> implements IStateManager<TStateValue> {
+    #private;
+    constructor(config: StateConfig<TStateValue>);
+    get(): Promise<TStateValue>;
+    getKey<TResponse extends Serializable>(key: string): Promise<TResponse | undefined>;
+    setKey(key: string, value: Serializable): Promise<void>;
+    setKeyWith<TValue extends Serializable>(key: string, updater: (currentValue: TValue | undefined) => TValue): Promise<void>;
+    update(updaterFunction: (state: TStateValue) => TStateValue): Promise<TStateValue>;
+    deleteKey(key: string): Promise<void>;
+    deleteKeys(keys: string[]): Promise<void>;
+}
+//# sourceMappingURL=State.d.cts.map

package/dist/utils/state/State.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.d.cts","sourceRoot":"","sources":["../../../src/utils/state/State.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,4BAAwB;AAErD,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAoFF;;;;;;GAMG;AACH,qBAAa,KAAK,CAChB,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAChD,YAAW,aAAa,CAAC,WAAW,CAAC;;gBAKzB,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC;IAmDtC,GAAG,IAAI,OAAO,CAAC,WAAW,CAAC;IAI3B,MAAM,CAAC,SAAS,SAAS,YAAY,EACzC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAM3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD,UAAU,CAAC,MAAM,SAAS,YAAY,EAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GACpD,OAAO,CAAC,IAAI,CAAC;IAMV,MAAM,CACV,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,GACnD,OAAO,CAAC,WAAW,CAAC;IAiBjB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQhD"}

package/dist/utils/state/State.d.mts

@@ -0,0 +1,25 @@
+import type { Serializable } from "../serialization/types.mjs";
+import type { IStateManager } from "./IStateManager.mjs";
+export type StateConfig<TValue extends Record<string, Serializable>> = {
+    encrypted: boolean;
+    defaultState: TValue;
+};
+/**
+ * Layer on top of `snap_manageState` / `snap_getState` / `snap_setState`:
+ *
+ * - Serializes values before storing them and deserializes after reading.
+ * - Merges `defaultState` on full-blob reads via `safeMerge`.
+ * - Serializes path writes and full-blob updates (lock strategy B).
+ */
+export declare class State<TStateValue extends Record<string, Serializable>> implements IStateManager<TStateValue> {
+    #private;
+    constructor(config: StateConfig<TStateValue>);
+    get(): Promise<TStateValue>;
+    getKey<TResponse extends Serializable>(key: string): Promise<TResponse | undefined>;
+    setKey(key: string, value: Serializable): Promise<void>;
+    setKeyWith<TValue extends Serializable>(key: string, updater: (currentValue: TValue | undefined) => TValue): Promise<void>;
+    update(updaterFunction: (state: TStateValue) => TStateValue): Promise<TStateValue>;
+    deleteKey(key: string): Promise<void>;
+    deleteKeys(keys: string[]): Promise<void>;
+}
+//# sourceMappingURL=State.d.mts.map

package/dist/utils/state/State.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.d.mts","sourceRoot":"","sources":["../../../src/utils/state/State.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,4BAAwB;AAErD,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAoFF;;;;;;GAMG;AACH,qBAAa,KAAK,CAChB,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAChD,YAAW,aAAa,CAAC,WAAW,CAAC;;gBAKzB,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC;IAmDtC,GAAG,IAAI,OAAO,CAAC,WAAW,CAAC;IAI3B,MAAM,CAAC,SAAS,SAAS,YAAY,EACzC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAM3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD,UAAU,CAAC,MAAM,SAAS,YAAY,EAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GACpD,OAAO,CAAC,IAAI,CAAC;IAMV,MAAM,CACV,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,GACnD,OAAO,CAAC,WAAW,CAAC;IAiBjB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQhD"}

package/dist/utils/state/State.mjs

@@ -0,0 +1,156 @@
+import { Mutex } from "async-mutex";
+import $lodash from "lodash";
+const { cloneDeep, unset } = $lodash;
+import { safeMerge } from "../safeMerge/safeMerge.mjs";
+import { deserialize, serialize } from "../serialization/serialization.mjs";
+/**
+ * Resolves the Snap RPC client from the global `snap` object provided by the Snap runtime.
+ *
+ * @returns The Snap `request` function.
+ */
+const getSnapRequest = () => globalThis.snap.request;
+/**
+ * Because we use both snap_manageState and snap_setState, we must protect against them
+ * being used at the same time. We must also protect against multiple parallel requests
+ * to snap_manageState.
+ *
+ * Path writes (`setKey` / `setKeyWith`) are serialized with a dedicated write mutex so
+ * concurrent read-modify-write updates cannot interleave. Path reads may still run in
+ * parallel with each other. A blob (`snap_manageState`) operation waits for in-flight path
+ * operations to finish and blocks new ones from starting until it completes.
+ */
+class StateLock {
+    // Gate every operation must pass through to start. Path operations hold it only while
+    // registering; a blob operation holds it for its whole duration, so no path operation
+    // can start after a blob operation begins waiting for in-flight ones to finish.
+    #operationAdmissionMutex = new Mutex();
+    // Held while at least one path operation is in flight.
+    #regularStateUpdateMutex = new Mutex();
+    #regularStateWriteMutex = new Mutex();
+    #pendingRegularStateUpdates = 0;
+    #releaseRegularStateUpdateMutex = null;
+    async #acquireRegularStateUpdateMutex() {
+        if (!this.#regularStateUpdateMutex.isLocked()) {
+            this.#releaseRegularStateUpdateMutex =
+                await this.#regularStateUpdateMutex.acquire();
+        }
+    }
+    async wrapRegularStateOperation(callback) {
+        await this.#operationAdmissionMutex.runExclusive(async () => {
+            await this.#acquireRegularStateUpdateMutex();
+            this.#pendingRegularStateUpdates += 1;
+        });
+        try {
+            return await callback();
+        }
+        finally {
+            this.#pendingRegularStateUpdates -= 1;
+            if (this.#pendingRegularStateUpdates === 0 &&
+                this.#releaseRegularStateUpdateMutex) {
+                this.#releaseRegularStateUpdateMutex();
+                this.#releaseRegularStateUpdateMutex = null;
+            }
+        }
+    }
+    async wrapRegularStateWriteOperation(callback) {
+        return await this.#regularStateWriteMutex.runExclusive(async () => this.wrapRegularStateOperation(callback));
+    }
+    async wrapManageStateOperation(callback) {
+        return await this.#operationAdmissionMutex.runExclusive(async () => {
+            await this.#regularStateUpdateMutex.waitForUnlock();
+            return await callback();
+        });
+    }
+}
+/**
+ * Layer on top of `snap_manageState` / `snap_getState` / `snap_setState`:
+ *
+ * - Serializes values before storing them and deserializes after reading.
+ * - Merges `defaultState` on full-blob reads via `safeMerge`.
+ * - Serializes path writes and full-blob updates (lock strategy B).
+ */
+export class State {
+    #lock = new StateLock();
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Reads and deserializes the value at `key`, or the whole state blob when `key` is omitted.
+     *
+     * @param key - The JSON-path key to read. Omit to read the whole blob.
+     * @returns The deserialized value, or `undefined` when the key is absent.
+     */
+    async #read(key) {
+        const value = await getSnapRequest()({
+            method: 'snap_getState',
+            params: {
+                ...(key === undefined ? {} : { key }),
+                encrypted: this.#config.encrypted,
+            },
+        });
+        return value === null || value === undefined
+            ? undefined
+            : deserialize(value);
+    }
+    /**
+     * Serializes `value` and writes it to `key`.
+     *
+     * @param key - The JSON-path key to write.
+     * @param value - The value to store.
+     */
+    async #write(key, value) {
+        await getSnapRequest()({
+            method: 'snap_setState',
+            params: {
+                key,
+                value: serialize(value),
+                encrypted: this.#config.encrypted,
+            },
+        });
+    }
+    async #unsafeGet() {
+        const state = (await this.#read()) ?? {};
+        // Clone the defaults so updaters that mutate the returned state (e.g. `deleteKey`
+        // via lodash `unset`) never leak into the shared `defaultState` object.
+        return safeMerge(cloneDeep(this.#config.defaultState), state);
+    }
+    async get() {
+        return this.#lock.wrapRegularStateOperation(async () => this.#unsafeGet());
+    }
+    async getKey(key) {
+        return this.#lock.wrapRegularStateOperation(async () => this.#read(key));
+    }
+    async setKey(key, value) {
+        await this.#lock.wrapRegularStateWriteOperation(async () => this.#write(key, value));
+    }
+    async setKeyWith(key, updater) {
+        await this.#lock.wrapRegularStateWriteOperation(async () => this.#write(key, updater(await this.#read(key))));
+    }
+    async update(updaterFunction) {
+        return await this.#lock.wrapManageStateOperation(async () => {
+            const newState = updaterFunction(await this.#unsafeGet());
+            await getSnapRequest()({
+                method: 'snap_manageState',
+                params: {
+                    operation: 'update',
+                    newState: serialize(newState),
+                    encrypted: this.#config.encrypted,
+                },
+            });
+            return newState;
+        });
+    }
+    async deleteKey(key) {
+        await this.deleteKeys([key]);
+    }
+    async deleteKeys(keys) {
+        await this.update((state) => {
+            keys.forEach((key) => {
+                unset(state, key);
+            });
+            return state;
+        });
+    }
+}
+//# sourceMappingURL=State.mjs.map

package/dist/utils/state/State.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.mjs","sourceRoot":"","sources":["../../../src/utils/state/State.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Json, SnapsProvider } from '@metamask/snaps-sdk';\nimport type { MutexInterface } from 'async-mutex';\nimport { Mutex } from 'async-mutex';\nimport { cloneDeep, unset } from 'lodash';\n\nimport { safeMerge } from '../safeMerge/safeMerge';\nimport { deserialize, serialize } from '../serialization/serialization';\nimport type { Serializable } from '../serialization/types';\nimport type { IStateManager } from './IStateManager';\n\nexport type StateConfig<TValue extends Record<string, Serializable>> = {\n  encrypted: boolean;\n  defaultState: TValue;\n};\n\n/**\n * Resolves the Snap RPC client from the global `snap` object provided by the Snap runtime.\n *\n * @returns The Snap `request` function.\n */\nconst getSnapRequest = (): SnapsProvider['request'] =>\n  (globalThis as typeof globalThis & { snap: SnapsProvider }).snap.request;\n\n/**\n * Because we use both snap_manageState and snap_setState, we must protect against them\n * being used at the same time. We must also protect against multiple parallel requests\n * to snap_manageState.\n *\n * Path writes (`setKey` / `setKeyWith`) are serialized with a dedicated write mutex so\n * concurrent read-modify-write updates cannot interleave. Path reads may still run in\n * parallel with each other. A blob (`snap_manageState`) operation waits for in-flight path\n * operations to finish and blocks new ones from starting until it completes.\n */\nclass StateLock {\n  // Gate every operation must pass through to start. Path operations hold it only while\n  // registering; a blob operation holds it for its whole duration, so no path operation\n  // can start after a blob operation begins waiting for in-flight ones to finish.\n  readonly #operationAdmissionMutex = new Mutex();\n\n  // Held while at least one path operation is in flight.\n  readonly #regularStateUpdateMutex = new Mutex();\n\n  readonly #regularStateWriteMutex = new Mutex();\n\n  #pendingRegularStateUpdates = 0;\n\n  #releaseRegularStateUpdateMutex: MutexInterface.Releaser | null = null;\n\n  async #acquireRegularStateUpdateMutex(): Promise<void> {\n    if (!this.#regularStateUpdateMutex.isLocked()) {\n      this.#releaseRegularStateUpdateMutex =\n        await this.#regularStateUpdateMutex.acquire();\n    }\n  }\n\n  async wrapRegularStateOperation<ReturnType>(\n    callback: MutexInterface.Worker<ReturnType>,\n  ): Promise<ReturnType> {\n    await this.#operationAdmissionMutex.runExclusive(async () => {\n      await this.#acquireRegularStateUpdateMutex();\n      this.#pendingRegularStateUpdates += 1;\n    });\n\n    try {\n      return await callback();\n    } finally {\n      this.#pendingRegularStateUpdates -= 1;\n\n      if (\n        this.#pendingRegularStateUpdates === 0 &&\n        this.#releaseRegularStateUpdateMutex\n      ) {\n        this.#releaseRegularStateUpdateMutex();\n        this.#releaseRegularStateUpdateMutex = null;\n      }\n    }\n  }\n\n  async wrapRegularStateWriteOperation<ReturnType>(\n    callback: MutexInterface.Worker<ReturnType>,\n  ): Promise<ReturnType> {\n    return await this.#regularStateWriteMutex.runExclusive(async () =>\n      this.wrapRegularStateOperation(callback),\n    );\n  }\n\n  async wrapManageStateOperation<ReturnType>(\n    callback: MutexInterface.Worker<ReturnType>,\n  ): Promise<ReturnType> {\n    return await this.#operationAdmissionMutex.runExclusive(async () => {\n      await this.#regularStateUpdateMutex.waitForUnlock();\n\n      return await callback();\n    });\n  }\n}\n\n/**\n * Layer on top of `snap_manageState` / `snap_getState` / `snap_setState`:\n *\n * - Serializes values before storing them and deserializes after reading.\n * - Merges `defaultState` on full-blob reads via `safeMerge`.\n * - Serializes path writes and full-blob updates (lock strategy B).\n */\nexport class State<\n  TStateValue extends Record<string, Serializable>,\n> implements IStateManager<TStateValue> {\n  readonly #lock = new StateLock();\n\n  readonly #config: StateConfig<TStateValue>;\n\n  constructor(config: StateConfig<TStateValue>) {\n    this.#config = config;\n  }\n\n  /**\n   * Reads and deserializes the value at `key`, or the whole state blob when `key` is omitted.\n   *\n   * @param key - The JSON-path key to read. Omit to read the whole blob.\n   * @returns The deserialized value, or `undefined` when the key is absent.\n   */\n  async #read<TValue extends Serializable>(\n    key?: string,\n  ): Promise<TValue | undefined> {\n    const value = await getSnapRequest()({\n      method: 'snap_getState',\n      params: {\n        ...(key === undefined ? {} : { key }),\n        encrypted: this.#config.encrypted,\n      },\n    });\n\n    return value === null || value === undefined\n      ? undefined\n      : (deserialize(value) as TValue);\n  }\n\n  /**\n   * Serializes `value` and writes it to `key`.\n   *\n   * @param key - The JSON-path key to write.\n   * @param value - The value to store.\n   */\n  async #write(key: string, value: Serializable): Promise<void> {\n    await getSnapRequest()({\n      method: 'snap_setState',\n      params: {\n        key,\n        value: serialize(value),\n        encrypted: this.#config.encrypted,\n      },\n    });\n  }\n\n  async #unsafeGet(): Promise<TStateValue> {\n    const state = (await this.#read<TStateValue>()) ?? ({} as TStateValue);\n\n    // Clone the defaults so updaters that mutate the returned state (e.g. `deleteKey`\n    // via lodash `unset`) never leak into the shared `defaultState` object.\n    return safeMerge(cloneDeep(this.#config.defaultState), state);\n  }\n\n  async get(): Promise<TStateValue> {\n    return this.#lock.wrapRegularStateOperation(async () => this.#unsafeGet());\n  }\n\n  async getKey<TResponse extends Serializable>(\n    key: string,\n  ): Promise<TResponse | undefined> {\n    return this.#lock.wrapRegularStateOperation(async () =>\n      this.#read<TResponse>(key),\n    );\n  }\n\n  async setKey(key: string, value: Serializable): Promise<void> {\n    await this.#lock.wrapRegularStateWriteOperation(async () =>\n      this.#write(key, value),\n    );\n  }\n\n  async setKeyWith<TValue extends Serializable>(\n    key: string,\n    updater: (currentValue: TValue | undefined) => TValue,\n  ): Promise<void> {\n    await this.#lock.wrapRegularStateWriteOperation(async () =>\n      this.#write(key, updater(await this.#read<TValue>(key))),\n    );\n  }\n\n  async update(\n    updaterFunction: (state: TStateValue) => TStateValue,\n  ): Promise<TStateValue> {\n    return await this.#lock.wrapManageStateOperation(async () => {\n      const newState = updaterFunction(await this.#unsafeGet());\n\n      await getSnapRequest()({\n        method: 'snap_manageState',\n        params: {\n          operation: 'update',\n          newState: serialize(newState) as Record<string, Json>,\n          encrypted: this.#config.encrypted,\n        },\n      });\n\n      return newState;\n    });\n  }\n\n  async deleteKey(key: string): Promise<void> {\n    await this.deleteKeys([key]);\n  }\n\n  async deleteKeys(keys: string[]): Promise<void> {\n    await this.update((state) => {\n      keys.forEach((key) => {\n        unset(state, key);\n      });\n      return state;\n    });\n  }\n}\n"]}

package/dist/utils/transactionType/transactionType.cjs

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFlowTransactionType = void 0;
+exports.resolveUnifiedSwapTransactionType = resolveUnifiedSwapTransactionType;
+const keyring_api_1 = require("@metamask/keyring-api");
+const utils_1 = require("@metamask/utils");
+/**
+ * Resolves the transaction type for a unified swap or bridge flow.
+ *
+ * @param options - The source and destination asset ids.
+ * @param options.sourceAssetId - The source asset id.
+ * @param options.destAssetId - The destination asset id.
+ * @returns `swap` for assets on the same chain, `bridgeSend` for assets on
+ * different chains, or `undefined` when either asset id is missing or invalid.
+ */
+function resolveUnifiedSwapTransactionType({ sourceAssetId, destAssetId, }) {
+    if (sourceAssetId === undefined || destAssetId === undefined) {
+        return undefined;
+    }
+    try {
+        const { chainId: sourceChainId } = (0, utils_1.parseCaipAssetType)(sourceAssetId);
+        const { chainId: destChainId } = (0, utils_1.parseCaipAssetType)(destAssetId);
+        return sourceChainId === destChainId
+            ? keyring_api_1.TransactionType.Swap
+            : keyring_api_1.TransactionType.BridgeSend;
+    }
+    catch {
+        return undefined;
+    }
+}
+exports.resolveFlowTransactionType = resolveUnifiedSwapTransactionType;
+//# sourceMappingURL=transactionType.cjs.map

package/dist/utils/transactionType/transactionType.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionType.cjs","sourceRoot":"","sources":["../../../src/utils/transactionType/transactionType.ts"],"names":[],"mappings":";;;AAaA,8EAqBC;AAlCD,uDAAwD;AAExD,2CAAqD;AAErD;;;;;;;;GAQG;AACH,SAAgB,iCAAiC,CAAC,EAChD,aAAa,EACb,WAAW,GAIZ;IACC,IAAI,aAAa,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,IAAA,0BAAkB,EAAC,aAAa,CAAC,CAAC;QACrE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAA,0BAAkB,EAAC,WAAW,CAAC,CAAC;QAEjE,OAAO,aAAa,KAAK,WAAW;YAClC,CAAC,CAAC,6BAAe,CAAC,IAAI;YACtB,CAAC,CAAC,6BAAe,CAAC,UAAU,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAEY,QAAA,0BAA0B,GAAG,iCAAiC,CAAC","sourcesContent":["import { TransactionType } from '@metamask/keyring-api';\nimport type { CaipAssetType } from '@metamask/utils';\nimport { parseCaipAssetType } from '@metamask/utils';\n\n/**\n * Resolves the transaction type for a unified swap or bridge flow.\n *\n * @param options - The source and destination asset ids.\n * @param options.sourceAssetId - The source asset id.\n * @param options.destAssetId - The destination asset id.\n * @returns `swap` for assets on the same chain, `bridgeSend` for assets on\n * different chains, or `undefined` when either asset id is missing or invalid.\n */\nexport function resolveUnifiedSwapTransactionType({\n  sourceAssetId,\n  destAssetId,\n}: {\n  sourceAssetId?: CaipAssetType;\n  destAssetId?: CaipAssetType;\n}): TransactionType | undefined {\n  if (sourceAssetId === undefined || destAssetId === undefined) {\n    return undefined;\n  }\n\n  try {\n    const { chainId: sourceChainId } = parseCaipAssetType(sourceAssetId);\n    const { chainId: destChainId } = parseCaipAssetType(destAssetId);\n\n    return sourceChainId === destChainId\n      ? TransactionType.Swap\n      : TransactionType.BridgeSend;\n  } catch {\n    return undefined;\n  }\n}\n\nexport const resolveFlowTransactionType = resolveUnifiedSwapTransactionType;\n"]}

package/dist/utils/transactionType/transactionType.d.cts

@@ -0,0 +1,17 @@
+import { TransactionType } from "@metamask/keyring-api";
+import type { CaipAssetType } from "@metamask/utils";
+/**
+ * Resolves the transaction type for a unified swap or bridge flow.
+ *
+ * @param options - The source and destination asset ids.
+ * @param options.sourceAssetId - The source asset id.
+ * @param options.destAssetId - The destination asset id.
+ * @returns `swap` for assets on the same chain, `bridgeSend` for assets on
+ * different chains, or `undefined` when either asset id is missing or invalid.
+ */
+export declare function resolveUnifiedSwapTransactionType({ sourceAssetId, destAssetId, }: {
+    sourceAssetId?: CaipAssetType;
+    destAssetId?: CaipAssetType;
+}): TransactionType | undefined;
+export declare const resolveFlowTransactionType: typeof resolveUnifiedSwapTransactionType;
+//# sourceMappingURL=transactionType.d.cts.map

package/dist/utils/transactionType/transactionType.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionType.d.cts","sourceRoot":"","sources":["../../../src/utils/transactionType/transactionType.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,8BAA8B;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB;AAGrD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,EAChD,aAAa,EACb,WAAW,GACZ,EAAE;IACD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,GAAG,eAAe,GAAG,SAAS,CAe9B;AAED,eAAO,MAAM,0BAA0B,0CAAoC,CAAC"}

package/dist/utils/transactionType/transactionType.d.mts

@@ -0,0 +1,17 @@
+import { TransactionType } from "@metamask/keyring-api";
+import type { CaipAssetType } from "@metamask/utils";
+/**
+ * Resolves the transaction type for a unified swap or bridge flow.
+ *
+ * @param options - The source and destination asset ids.
+ * @param options.sourceAssetId - The source asset id.
+ * @param options.destAssetId - The destination asset id.
+ * @returns `swap` for assets on the same chain, `bridgeSend` for assets on
+ * different chains, or `undefined` when either asset id is missing or invalid.
+ */
+export declare function resolveUnifiedSwapTransactionType({ sourceAssetId, destAssetId, }: {
+    sourceAssetId?: CaipAssetType;
+    destAssetId?: CaipAssetType;
+}): TransactionType | undefined;
+export declare const resolveFlowTransactionType: typeof resolveUnifiedSwapTransactionType;
+//# sourceMappingURL=transactionType.d.mts.map

package/dist/utils/transactionType/transactionType.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionType.d.mts","sourceRoot":"","sources":["../../../src/utils/transactionType/transactionType.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,8BAA8B;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB;AAGrD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,EAChD,aAAa,EACb,WAAW,GACZ,EAAE;IACD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,GAAG,eAAe,GAAG,SAAS,CAe9B;AAED,eAAO,MAAM,0BAA0B,0CAAoC,CAAC"}

package/dist/utils/transactionType/transactionType.mjs

@@ -0,0 +1,28 @@
+import { TransactionType } from "@metamask/keyring-api";
+import { parseCaipAssetType } from "@metamask/utils";
+/**
+ * Resolves the transaction type for a unified swap or bridge flow.
+ *
+ * @param options - The source and destination asset ids.
+ * @param options.sourceAssetId - The source asset id.
+ * @param options.destAssetId - The destination asset id.
+ * @returns `swap` for assets on the same chain, `bridgeSend` for assets on
+ * different chains, or `undefined` when either asset id is missing or invalid.
+ */
+export function resolveUnifiedSwapTransactionType({ sourceAssetId, destAssetId, }) {
+    if (sourceAssetId === undefined || destAssetId === undefined) {
+        return undefined;
+    }
+    try {
+        const { chainId: sourceChainId } = parseCaipAssetType(sourceAssetId);
+        const { chainId: destChainId } = parseCaipAssetType(destAssetId);
+        return sourceChainId === destChainId
+            ? TransactionType.Swap
+            : TransactionType.BridgeSend;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const resolveFlowTransactionType = resolveUnifiedSwapTransactionType;
+//# sourceMappingURL=transactionType.mjs.map

package/dist/utils/transactionType/transactionType.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionType.mjs","sourceRoot":"","sources":["../../../src/utils/transactionType/transactionType.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,8BAA8B;AAExD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB;AAErD;;;;;;;;GAQG;AACH,MAAM,UAAU,iCAAiC,CAAC,EAChD,aAAa,EACb,WAAW,GAIZ;IACC,IAAI,aAAa,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;QACrE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAEjE,OAAO,aAAa,KAAK,WAAW;YAClC,CAAC,CAAC,eAAe,CAAC,IAAI;YACtB,CAAC,CAAC,eAAe,CAAC,UAAU,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,iCAAiC,CAAC","sourcesContent":["import { TransactionType } from '@metamask/keyring-api';\nimport type { CaipAssetType } from '@metamask/utils';\nimport { parseCaipAssetType } from '@metamask/utils';\n\n/**\n * Resolves the transaction type for a unified swap or bridge flow.\n *\n * @param options - The source and destination asset ids.\n * @param options.sourceAssetId - The source asset id.\n * @param options.destAssetId - The destination asset id.\n * @returns `swap` for assets on the same chain, `bridgeSend` for assets on\n * different chains, or `undefined` when either asset id is missing or invalid.\n */\nexport function resolveUnifiedSwapTransactionType({\n  sourceAssetId,\n  destAssetId,\n}: {\n  sourceAssetId?: CaipAssetType;\n  destAssetId?: CaipAssetType;\n}): TransactionType | undefined {\n  if (sourceAssetId === undefined || destAssetId === undefined) {\n    return undefined;\n  }\n\n  try {\n    const { chainId: sourceChainId } = parseCaipAssetType(sourceAssetId);\n    const { chainId: destChainId } = parseCaipAssetType(destAssetId);\n\n    return sourceChainId === destChainId\n      ? TransactionType.Swap\n      : TransactionType.BridgeSend;\n  } catch {\n    return undefined;\n  }\n}\n\nexport const resolveFlowTransactionType = resolveUnifiedSwapTransactionType;\n"]}