Feature: Multiple deployments functions

eslint.config.mjs

@@ -1,16 +1,13 @@
-import eslint from "@eslint/js";
-import tseslint from "typescript-eslint";
-import prettier from "eslint-plugin-prettier/recommended";
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettier from 'eslint-plugin-prettier/recommended';
 
 export default [
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   {
     rules: {
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { ignoreRestSiblings: true },
-      ],
+      '@typescript-eslint/no-unused-vars': ['error', { ignoreRestSiblings: true }],
     },
   },
   prettier,

src/__tests__/assets.test.ts

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import { SingletonDeploymentJSON } from '../types';
+import { SingletonDeploymentJSON, AddressType } from '../types';
 
-const KNOWN_ADDRESS_TYPES = ['canonical', 'eip155', 'zksync'];
+const KNOWN_ADDRESS_TYPES: AddressType[] = ['canonical', 'eip155', 'zksync'];
 
 function assetPath(...paths: string[]) {
   return path.join(__dirname, '..', 'assets', ...paths);
@@ -45,7 +45,7 @@ describe('assets/', () => {
               expect(keys).toEqual(sorted);
             });
 
-            it('networks should only contain canonical address types', async () => {
+            it('networks should only contain known address types', async () => {
               const deploymentJson = await readAssetJSON(version, file);
               if (!deploymentJson) {
                 throw new Error(`Failed to read asset ${version}/${file}`);

src/accessors.ts

@@ -1,12 +1,23 @@
-import SimulateTxAccessor130 from './assets/v1.3.0/simulate_tx_accessor.json';
-import SimulateTxAccessor141 from './assets/v1.4.1/simulate_tx_accessor.json';
-
-import { DeploymentFilter, SingletonDeploymentJSON, SingletonDeployment } from './types';
+import { DeploymentFilter, SingletonDeployment, DeploymentFormats, SingletonDeploymentV2 } from './types';
 import { findDeployment } from './utils';
+import { _ACCESSOR_DEPLOYMENTS } from './deployments';
 
-// This is a sorted array (newest to oldest)
-const accessorDeployments: SingletonDeploymentJSON[] = [SimulateTxAccessor141, SimulateTxAccessor130];
-
+/**
+ * Retrieves a single simulate transaction accessor deployment based on the provided filter.
+ *
+ * @param {DeploymentFilter} [filter] - Optional filter to apply when searching for the deployment.
+ * @returns {SingletonDeployment | undefined} - The found deployment or undefined if no deployment matches the filter.
+ */
 export const getSimulateTxAccessorDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, accessorDeployments);
+  return findDeployment(filter, _ACCESSOR_DEPLOYMENTS);
+};
+
+/**
+ * Retrieves multiple simulate transaction accessor deployments based on the provided filter.
+ *
+ * @param {DeploymentFilter} [filter] - Optional filter to apply when searching for the deployments.
+ * @returns {SingletonDeploymentV2 | undefined} - The found deployments in the specified format or undefined if no deployments match the filter.
+ */
+export const getSimulateTxAccessorDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _ACCESSOR_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
 };

src/deployments.ts

@@ -0,0 +1,90 @@
+import { SingletonDeploymentJSON } from './types';
+
+// This is a file where all the deployments are consolidated
+// We do it in a separate file so we don't have to repeat comments about the array order and the type casting.
+// We use some specific types (like `AddressType`) in the `SingletonDeploymentJSON` type, but the TypeScript cannot infer that from the JSON files.
+// So we need to cast them to `SingletonDeploymentJSON` manually. The casting is valid because we have a test in `__tests__/assets.test.ts` that checks that the JSON files are valid.
+// The arrays are sorted by preference, which at the moment means from the most recent version to the oldest.
+// The arrays are prefixed with an underscore because they are not meant to be imported directly.
+
+import SimulateTxAccessor130 from './assets/v1.3.0/simulate_tx_accessor.json';
+import SimulateTxAccessor141 from './assets/v1.4.1/simulate_tx_accessor.json';
+
+const _ACCESSOR_DEPLOYMENTS = [SimulateTxAccessor141, SimulateTxAccessor130] as SingletonDeploymentJSON[];
+
+import ProxyFactory100 from './assets/v1.0.0/proxy_factory.json';
+import ProxyFactory111 from './assets/v1.1.1/proxy_factory.json';
+import ProxyFactory130 from './assets/v1.3.0/proxy_factory.json';
+import SafeProxyFactory141 from './assets/v1.4.1/safe_proxy_factory.json';
+
+const _FACTORY_DEPLOYMENTS = [
+  SafeProxyFactory141,
+  ProxyFactory130,
+  ProxyFactory111,
+  ProxyFactory100,
+] as SingletonDeploymentJSON[];
+
+import DefaultCallbackHandler130 from './assets/v1.1.1/default_callback_handler.json';
+
+const _DEFAULT_CALLBACK_HANDLER_DEPLOYMENTS = [DefaultCallbackHandler130] as SingletonDeploymentJSON[];
+
+import CompatibilityFallbackHandler130 from './assets/v1.3.0/compatibility_fallback_handler.json';
+import CompatibilityFallbackHandler141 from './assets/v1.4.1/compatibility_fallback_handler.json';
+
+const _COMPAT_FALLBACK_HANDLER_DEPLOYMENTS = [
+  CompatibilityFallbackHandler141,
+  CompatibilityFallbackHandler130,
+] as SingletonDeploymentJSON[];
+
+import Safe141 from './assets/v1.4.1/safe.json';
+import GnosisSafe130 from './assets/v1.3.0/gnosis_safe.json';
+import GnosisSafe120 from './assets/v1.2.0/gnosis_safe.json';
+import GnosisSafe111 from './assets/v1.1.1/gnosis_safe.json';
+import GnosisSafe100 from './assets/v1.0.0/gnosis_safe.json';
+
+const _SAFE_DEPLOYMENTS = [
+  Safe141,
+  GnosisSafe130,
+  GnosisSafe120,
+  GnosisSafe111,
+  GnosisSafe100,
+] as SingletonDeploymentJSON[];
+
+import SafeL2141 from './assets/v1.4.1/safe_l2.json';
+import GnosisSafeL2130 from './assets/v1.3.0/gnosis_safe_l2.json';
+
+const _SAFE_L2_DEPLOYMENTS = [SafeL2141, GnosisSafeL2130] as SingletonDeploymentJSON[];
+
+import MultiSend111 from './assets/v1.1.1/multi_send.json';
+import MultiSend130 from './assets/v1.3.0/multi_send.json';
+import MultiSend141 from './assets/v1.4.1/multi_send.json';
+
+const _MULTI_SEND_DEPLOYMENTS = [MultiSend141, MultiSend130, MultiSend111] as SingletonDeploymentJSON[];
+
+import MultiSendCallOnly130 from './assets/v1.3.0/multi_send_call_only.json';
+import MultiSendCallOnly141 from './assets/v1.4.1/multi_send_call_only.json';
+
+const _MULTI_SEND_CALL_ONLY_DEPLOYMENTS = [MultiSendCallOnly141, MultiSendCallOnly130] as SingletonDeploymentJSON[];
+
+import CreateCall130 from './assets/v1.3.0/create_call.json';
+import CreateCall141 from './assets/v1.4.1/create_call.json';
+
+const _CREATE_CALL_DEPLOYMENTS = [CreateCall141, CreateCall130] as SingletonDeploymentJSON[];
+
+import SignMessageLib130 from './assets/v1.3.0/sign_message_lib.json';
+import SignMessageLib141 from './assets/v1.4.1/sign_message_lib.json';
+
+const _SIGN_MESSAGE_LIB_DEPLOYMENTS = [SignMessageLib141, SignMessageLib130] as SingletonDeploymentJSON[];
+
+export {
+  _ACCESSOR_DEPLOYMENTS,
+  _FACTORY_DEPLOYMENTS,
+  _DEFAULT_CALLBACK_HANDLER_DEPLOYMENTS,
+  _COMPAT_FALLBACK_HANDLER_DEPLOYMENTS,
+  _SAFE_DEPLOYMENTS,
+  _SAFE_L2_DEPLOYMENTS,
+  _MULTI_SEND_DEPLOYMENTS,
+  _MULTI_SEND_CALL_ONLY_DEPLOYMENTS,
+  _CREATE_CALL_DEPLOYMENTS,
+  _SIGN_MESSAGE_LIB_DEPLOYMENTS,
+};

src/factories.ts

@@ -1,19 +1,21 @@
-import ProxyFactory100 from './assets/v1.0.0/proxy_factory.json';
-import ProxyFactory111 from './assets/v1.1.1/proxy_factory.json';
-import ProxyFactory130 from './assets/v1.3.0/proxy_factory.json';
-import SafeProxyFactory141 from './assets/v1.4.1/safe_proxy_factory.json';
-
-import { DeploymentFilter, SingletonDeployment, SingletonDeploymentJSON } from './types';
+import { DeploymentFilter, DeploymentFormats, SingletonDeployment, SingletonDeploymentV2 } from './types';
 import { findDeployment } from './utils';
+import { _FACTORY_DEPLOYMENTS } from './deployments';
 
-// This is a sorted array (newest to oldest)
-const factoryDeployments: SingletonDeploymentJSON[] = [
-  SafeProxyFactory141,
-  ProxyFactory130,
-  ProxyFactory111,
-  ProxyFactory100,
-];
-
+/**
+ * Finds the latest proxy factory deployment that matches the given filter.
+ * @param {DeploymentFilter} [filter] - The filter to apply when searching for the deployment.
+ * @returns {SingletonDeployment | undefined} - The found deployment or undefined if no deployment matches the filter.
+ */
 export const getProxyFactoryDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, factoryDeployments);
+  return findDeployment(filter, _FACTORY_DEPLOYMENTS);
+};
+
+/**
+ * Finds all proxy factory deployments that match the given filter.
+ * @param {DeploymentFilter} [filter] - The filter to apply when searching for the deployments.
+ * @returns {SingletonDeploymentV2 | undefined} - The found deployments or undefined if no deployments match the filter.
+ */
+export const getProxyFactoryDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _FACTORY_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
 };

src/handler.ts

@@ -1,35 +1,68 @@
-import DefaultCallbackHandler130 from './assets/v1.1.1/default_callback_handler.json';
-import CompatibilityFallbackHandler130 from './assets/v1.3.0/compatibility_fallback_handler.json';
-import CompatibilityFallbackHandler141 from './assets/v1.4.1/compatibility_fallback_handler.json';
-import { DeploymentFilter, SingletonDeployment, SingletonDeploymentJSON } from './types';
+import { DeploymentFilter, DeploymentFormats, SingletonDeployment, SingletonDeploymentV2 } from './types';
 import { findDeployment } from './utils';
+import { _DEFAULT_CALLBACK_HANDLER_DEPLOYMENTS, _COMPAT_FALLBACK_HANDLER_DEPLOYMENTS } from './deployments';
 
-// This is a sorted array (by preference)
-const defaultCallbackHandlerDeployments: SingletonDeploymentJSON[] = [DefaultCallbackHandler130];
-
+/**
+ * Get the default callback handler deployment based on the provided filter.
+ * @param {DeploymentFilter} [filter] - Optional filter to apply to the deployment search.
+ * @returns {SingletonDeployment | undefined} - The found deployment or undefined if not found.
+ */
 export const getDefaultCallbackHandlerDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, defaultCallbackHandlerDeployments);
+  return findDeployment(filter, _DEFAULT_CALLBACK_HANDLER_DEPLOYMENTS);
 };
 
-// This is a sorted array (by preference)
-const compatFallbackHandlerDeployments: SingletonDeploymentJSON[] = [
-  CompatibilityFallbackHandler141,
-  CompatibilityFallbackHandler130,
-];
+/**
+ * Get all default callback handler deployments based on the provided filter.
+ * @param {DeploymentFilter} [filter] - Optional filter to apply to the deployment search.
+ * @returns {SingletonDeploymentV2 | undefined} - The found deployments in version 2 format or undefined if not found.
+ */
+export const getDefaultCallbackHandlerDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _DEFAULT_CALLBACK_HANDLER_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
+};
 
+/**
+ * Get the compatibility fallback handler deployment based on the provided filter.
+ * @param {DeploymentFilter} [filter] - Optional filter to apply to the deployment search.
+ * @returns {SingletonDeployment | undefined} - The found deployment or undefined if not found.
+ */
 export const getCompatibilityFallbackHandlerDeployment = (
   filter?: DeploymentFilter,
 ): SingletonDeployment | undefined => {
-  return findDeployment(filter, compatFallbackHandlerDeployments);
+  return findDeployment(filter, _COMPAT_FALLBACK_HANDLER_DEPLOYMENTS);
 };
 
-// This is a sorted array (by preference)
-const fallbackHandlerDeployments: SingletonDeploymentJSON[] = [
-  CompatibilityFallbackHandler141,
-  CompatibilityFallbackHandler130,
-  DefaultCallbackHandler130,
-];
-
-export const getFallbackHandlerDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, fallbackHandlerDeployments);
+/**
+ * Get all compatibility fallback handler deployments based on the provided filter.
+ * @param {DeploymentFilter} [filter] - Optional filter to apply to the deployment search.
+ * @returns {SingletonDeploymentV2 | undefined} - The found deployments in version 2 format or undefined if not found.
+ */
+export const getCompatibilityFallbackHandlerDeployments = (
+  filter?: DeploymentFilter,
+): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _COMPAT_FALLBACK_HANDLER_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
 };
+
+/**
+ * Get the fallback handler deployment based on the provided filter. This method is an alias for `getCompatibilityFallbackHandlerDeployment`.
+ * Kept for backwards compatibility.
+ * @param {DeploymentFilter} [filter] - Optional filter to apply to the deployment search.
+ * @returns {SingletonDeployment | undefined} - The found deployment or undefined if not found.
+ */
+export const getFallbackHandlerDeployment = getCompatibilityFallbackHandlerDeployment;
+// Leaving the comment here so it's not a part of the JSDoc
+// Previously, the function code was this:
+// // This is a sorted array (by preference)
+// const fallbackHandlerDeployments: SingletonDeploymentJSON[] = [
+//   CompatibilityFallbackHandler141,
+//   CompatibilityFallbackHandler130,
+//   DefaultCallbackHandler130,
+// ];
+// export const getFallbackHandlerDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
+//   return findDeployment(filter, fallbackHandlerDeployments);
+// };
+// The problem with the function is that there’s no possible filter that would make the function return the last element of the array
+// (DefaultCallbackHandler130 ), since we only allow to filter by version, networks and released flag. The only possible way is to have
+// the default callback handler deployed to a network where the compatibility fallback handler isn’t deployed, but we require the whole
+// suite of the contracts be deployed to a network.
+// Since we didn't want to enforce a preferred fallback handler on the deployments package level,
+// we decided to alias it to getCompatibilityFallbackHandlerDeployment (previously returned value)

src/libs.ts

@@ -1,38 +1,80 @@
-import CreateCall130 from './assets/v1.3.0/create_call.json';
-import CreateCall141 from './assets/v1.4.1/create_call.json';
-import MultiSend111 from './assets/v1.1.1/multi_send.json';
-import MultiSend130 from './assets/v1.3.0/multi_send.json';
-import MultiSend141 from './assets/v1.4.1/multi_send.json';
-import MultiSendCallOnly130 from './assets/v1.3.0/multi_send_call_only.json';
-import MultiSendCallOnly141 from './assets/v1.4.1/multi_send_call_only.json';
-import SignMessageLib130 from './assets/v1.3.0/sign_message_lib.json';
-import SignMessageLib141 from './assets/v1.4.1/sign_message_lib.json';
-import { DeploymentFilter, SingletonDeployment, SingletonDeploymentJSON } from './types';
+import {
+  _CREATE_CALL_DEPLOYMENTS,
+  _MULTI_SEND_CALL_ONLY_DEPLOYMENTS,
+  _MULTI_SEND_DEPLOYMENTS,
+  _SIGN_MESSAGE_LIB_DEPLOYMENTS,
+} from './deployments';
+import { DeploymentFilter, DeploymentFormats, SingletonDeployment, SingletonDeploymentV2 } from './types';
 import { findDeployment } from './utils';
 
-// This is a sorted array (by preference, currently we use 111 in most cases)
-const multiSendDeployments: SingletonDeploymentJSON[] = [MultiSend141, MultiSend130, MultiSend111];
-
+/**
+ * Get the MultiSend deployment based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployment.
+ * @returns {SingletonDeployment | undefined} - The matched deployment or undefined if not found.
+ */
 export const getMultiSendDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, multiSendDeployments);
+  return findDeployment(filter, _MULTI_SEND_DEPLOYMENTS);
 };
 
-// This is a sorted array (by preference)
-const multiSendCallOnlyDeployments: SingletonDeploymentJSON[] = [MultiSendCallOnly141, MultiSendCallOnly130];
+/**
+ * Get all MultiSend deployments based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployments.
+ * @returns {SingletonDeploymentV2 | undefined} - The matched deployments or undefined if not found.
+ */
+export const getMultiSendDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _MULTI_SEND_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
+};
 
+/**
+ * Get the MultiSendCallOnly deployment based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployment.
+ * @returns {SingletonDeployment | undefined} - The matched deployment or undefined if not found.
+ */
 export const getMultiSendCallOnlyDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, multiSendCallOnlyDeployments);
+  return findDeployment(filter, _MULTI_SEND_CALL_ONLY_DEPLOYMENTS);
 };
 
-// This is a sorted array (by preference)
-const createCallDeployments: SingletonDeploymentJSON[] = [CreateCall141, CreateCall130];
+/**
+ * Get all MultiSendCallOnly deployments based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployments.
+ * @returns {SingletonDeploymentV2 | undefined} - The matched deployments or undefined if not found.
+ */
+export const getMultiSendCallOnlyDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _MULTI_SEND_CALL_ONLY_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
+};
 
+/**
+ * Get the CreateCall deployment based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployment.
+ * @returns {SingletonDeployment | undefined} - The matched deployment or undefined if not found.
+ */
 export const getCreateCallDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, createCallDeployments);
+  return findDeployment(filter, _CREATE_CALL_DEPLOYMENTS);
 };
 
-const signMessageLibDeployments: SingletonDeploymentJSON[] = [SignMessageLib141, SignMessageLib130];
+/**
+ * Get all CreateCall deployments based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployments.
+ * @returns {SingletonDeploymentV2 | undefined} - The matched deployments or undefined if not found.
+ */
+export const getCreateCallDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _CREATE_CALL_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
+};
 
+/**
+ * Get the SignMessageLib deployment based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployment.
+ * @returns {SingletonDeployment | undefined} - The matched deployment or undefined if not found.
+ */
 export const getSignMessageLibDeployment = (filter?: DeploymentFilter): SingletonDeployment | undefined => {
-  return findDeployment(filter, signMessageLibDeployments);
+  return findDeployment(filter, _SIGN_MESSAGE_LIB_DEPLOYMENTS);
+};
+
+/**
+ * Get all SignMessageLib deployments based on the provided filter.
+ * @param {DeploymentFilter} [filter] - The filter criteria for the deployments.
+ * @returns {SingletonDeploymentV2 | undefined} - The matched deployments or undefined if not found.
+ */
+export const getSignMessageLibDeployments = (filter?: DeploymentFilter): SingletonDeploymentV2 | undefined => {
+  return findDeployment(filter, _SIGN_MESSAGE_LIB_DEPLOYMENTS, DeploymentFormats.MULTIPLE);
 };