@0xsequence/catapult 1.2.1 → 1.3.2

package/src/lib/network-selection.ts

@@ -0,0 +1,73 @@
+import { Network } from './types'
+
+/**
+ * Parses a comma-separated selector string into chain IDs, supporting numeric IDs and network names.
+ * - Numeric tokens (e.g., "1") are treated as chain IDs
+ * - String tokens (e.g., "mainnet") are matched against Network.name case-insensitively
+ * - When a name matches multiple networks, all of them are included
+ * - Order is preserved by token then by appearance order in `networks`
+ * - Duplicates are removed
+ *
+ * Throws if any token cannot be resolved to at least one chain ID.
+ */
+export function resolveSelectedChainIds(
+  selectors: string | undefined,
+  networks: Network[]
+): number[] | undefined {
+  if (selectors == null) return undefined
+  const normalized = String(selectors).trim()
+  if (normalized.length === 0) return undefined
+
+  const tokens = normalized
+    .split(',')
+    .map(t => t.trim())
+    .filter(t => t.length > 0)
+
+  if (tokens.length === 0) return undefined
+
+  const result: number[] = []
+  const seen = new Set<number>()
+
+  for (const token of tokens) {
+    if (/^\d+$/.test(token)) {
+      const id = Number(token)
+      if (!seen.has(id)) {
+        seen.add(id)
+        result.push(id)
+      }
+      continue
+    }
+
+    const tokenLc = token.toLowerCase()
+    const matches = networks.filter(n => n.name.toLowerCase() === tokenLc)
+    if (matches.length === 0) {
+      const available = Array.from(new Set(networks.map(n => n.name))).sort()
+      throw new Error(
+        `Unknown network selector "${token}". Use a chain ID (e.g., 1) or a network name. Available names: ${available.join(', ')}`
+      )
+    }
+    for (const net of matches) {
+      if (!seen.has(net.chainId)) {
+        seen.add(net.chainId)
+        result.push(net.chainId)
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Resolves a single selector into one chain ID. If a name maps to multiple networks,
+ * returns the first matching network in the order provided.
+ */
+export function resolveSingleChainId(
+  selector: string | undefined,
+  networks: Network[]
+): number | undefined {
+  const ids = resolveSelectedChainIds(selector, networks)
+  if (!ids || ids.length === 0) return undefined
+  return ids[0]
+}
+
+

package/CONCEPT.md

@@ -1,24 +0,0 @@
-# Concept document - loosely defined idea
-
-The idea of this project is to create a contract deployment and management framework. It is not intended to be authenticated; it is intended to replay contract deployments or pre-signed transactions, and more generally unauthenticated actions. The need for this project is that Sequence has a multitude of contracts, migrations, factories, etc., that need to be deployed every time a new chain pops up (or local testing is needed), and keeping track of all these chains and their current deployment status is tricky. This project allows for the creation of a single repository of YAML files that define what needs to be deployed, in what order, and what depends on what.
-
-There should be two kinds of “actions” that can be defined for a deployment. One kind is “built-in” actions; these are defined by code. They include things like sending a transaction, sending a pre-signed transaction, calling the key machine, verifying a contract, calling a service, etc. They should be basic and primitive. Actions may return values—for example, a transaction hash when sending a transaction, or an ok/not-ok when verifying a contract, etc.
-
-Another primitive should be “modifiers” or “composite values.” These are also implemented with code in the project. They include doing ABI encode, constructor-arg encode, comparing whether a value is high enough, performing math, etc. These are required because sometimes operations depend on a formula derived from another operation (let’s say a universal deployer needs to have X funds to deploy the factory using Nick’s method; you need to compute how much you have to transfer to reach the threshold, etc.). A more common scenario is having to do ABI.encode or constructors.
-
-Ideally, these methods are pretty low-level, and most of the heavy lifting is done by “templates.” Templates are also actions, but they can be reused by other actions. For example, Sequence has its own factory contracts and deployers; we don’t want to define them in the project one by one. Instead, it would be best if these could be defined as templates and later reused, so adding more factory kinds does not require modifying this project and doing another release. It should be noted that sometimes factories themselves have to be deployed—for example, when we deploy the Sequence v1 factory we first have to deploy the universal deployer 2, and when we deploy the universal deployer 2 we first need the nano deployer, etc. So templates by themselves have a sort of “setup” factory.
-
-Jobs are a collection of actions. Some jobs may depend on other jobs; some actions within a job may depend on actions from within the same job, but no actions from one job can depend on actions from another job (the whole job has to depend). Actions can reference output values from other jobs as long as they depend on them. This defines a sort of order graph on which jobs and actions need to be executed. Some jobs and some actions may be 100% independent of each other.
-
-Networks can be defined in a `networks.yaml` file (or a directory with many networks; I am not sure yet). Each network has a name, explorer, chainId, and RPC. Networks may have modifiers, like how much gas has to be sent, etc., but by default the program should try to “guess it” by looking at past blocks. Jobs run by default on all networks unless some networks are excluded (`skip_networks`) or only some networks are requested (`only_networks`). These are arrays of chainIds in the YAML file.
-
-Signers are abstracted with the idea that eventually this can run in a browser and a MetaMask-like wallet could perform the transactions (acting as the relayer or the sender), but for now we just implement an EOA signer, a private key that has to be passed, and it is expected to have the funds needed to execute all the transactions and fund everything that needs to be funded. The CLI just takes that as an ENV variable or a CLI argument.
-
-One important aspect of the project is that it should simplify dealing with build artifacts, so it does not require too much manual work. The project should be able to reference any build artifact either by using the hash of the artifact (a hash that can be obtained with the command `bin artifacts hashes`) or by using the path to the artifact. Ideally, artifacts can be provided in different formats and the program just takes care of it; they could be JSON files, nested directories, JS files, etc. It should try to be as smart as possible in the sense that it just figures out the format.
-
-Running the CLI generates an `output` directory with job results. This contains the latest run date, the list of chainIds where everything has been successful, and the outputs of all actions and templates that ran on those jobs; each job has its own file. If there have been any errors, no output is generated, and instead the CLI fails. The CLI can run any number of jobs at the same time, and it just figures it out.
-
-The CLI also has methods to:
-
-* dry-run and verify the correctness of the YAML definitions of a project
-* obtain all the artifacts detected and their hashes