refactor: manifest object

feat: add "contractNames" in release type
feat: export global contract names
perf: simplify print scripts
refactor: generate version groups dynamically
refactor: rename release exports
refactor: flatten query getters
refactor: remove "isValidVersion"
refactor: throw error using winston logger

Author: PaulRBerg

biome.jsonc

@@ -20,7 +20,7 @@
     "enabled": true,
     "rules": {
       "correctness": {
-        "noUnusedImports": "error",
+        "noUnusedImports": "off",
         "noUnusedVariables": "error"
       },
       "recommended": true

scripts/check-broadcast.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import type { Sablier } from "@src/types";
 import { globby } from "globby";
 import type { Options as GlobbyOptions } from "globby";
-import { log } from "./logger";
+import { logInfo } from "./logger";
 
 const ROOT_DIR = path.join(__dirname, "..");
 
@@ -37,7 +37,7 @@ async function checkPath(
 
   if (!pathExists) {
     const relativePath = path.relative(ROOT_DIR, pathToCheck);
-    log("info", release, `No broadcasts for ${chain.name} at ${relativePath}`);
+    logInfo({ msg: `No broadcasts for ${chain.name} at ${relativePath}`, release });
     return null;
   }
 

scripts/logger.ts

@@ -71,8 +71,24 @@ const logger = winston.createLogger({
   transports,
 });
 
-export function log(level: "info" | "error", release: Sablier.Release, message: string): void {
-  logger[level](`${release.protocol}:${release.version}\t${message}`);
+export function logInfo(params: { msg: string; release?: Sablier.Release }): void {
+  const { msg, release } = params;
+  if (release) {
+    logger.info(`${formatRelease(release)}\t${msg}`);
+  } else {
+    logger.info(msg);
+  }
+}
+
+export function logAndThrow(params: { msg: string; release?: Sablier.Release }): never {
+  const { msg, release } = params;
+  const errorMsg = release ? `${formatRelease(release)}\t${msg}` : msg;
+  logger.error(errorMsg);
+  throw new Error(errorMsg);
+}
+
+function formatRelease(release: Sablier.Release): string {
+  return `${release.protocol}:${release.version}`;
 }
 
 export default logger;

scripts/print-aliases.ts

@@ -1,47 +1,41 @@
 import { releases } from "@src/releases";
 import _ from "lodash";
 import logger from "./logger";
-
 interface AliasRow {
   alias: string;
   contractName: string;
-  release: string;
+  releaseName: string;
 }
 
 async function main() {
   const rows: AliasRow[] = [];
 
   for (const release of releases) {
-    const aliases = release.aliases;
     const releaseName = `${release.protocol} ${release.version}`;
-
-    _.forOwn(aliases, (alias, key) => {
-      let contractName: string;
-
-      // Lockup v1.x has core/periphery structure, others are flat
-      if (release.kind === "lockupV1") {
-        // Type cast the manifest to ManifestLockupV1
-        const manifest = release.manifest;
-        contractName = _.get(manifest.core, key) || _.get(manifest.periphery, key) || key;
-      } else {
-        // For the array-based manifest, the key should be the contract name itself
-        contractName = key;
+    if (!release.aliases) {
+      logger.verbose(`Skipping ${releaseName} because it has no aliases`);
+      continue;
+    }
+
+    _.forOwn(release.aliases, (alias, contractName) => {
+      // Exclude the MerkleFactory from being printed twice in the table
+      if (release.protocol === "lockup" && alias.startsWith("MSF")) {
+        return;
       }
-
       rows.push({
         alias,
         contractName,
-        release: releaseName,
+        releaseName,
       });
     });
   }
 
   if (rows.length === 0) {
-    console.log("❌ No aliases found");
+    logger.info("❌ No aliases found");
     return;
   }
 
-  console.log(`✅ Found ${rows.length} total aliases\n`);
+  logger.info(`✅ Found ${rows.length} total aliases\n`);
 
   rows.sort((a, b) => a.alias.localeCompare(b.alias));
 
@@ -54,9 +48,9 @@ async function main() {
   console.log(sep);
 
   for (const row of rows) {
-    const vals = [row.alias, row.contractName, row.release];
-    const line = vals.map((v, i) => v.padEnd(colWidths[i])).join(" | ");
-    console.log(line);
+    const cellValues = [row.alias, row.contractName, row.releaseName];
+    const content = cellValues.map((v, i) => v.padEnd(colWidths[i])).join(" | ");
+    console.log(content);
   }
 }
 
@@ -65,5 +59,5 @@ main().catch((error) => {
   if (error.stack) {
     logger.error(error.stack);
   }
-  process.exit(1);
+  throw error;
 });

scripts/print-missing-broadcasts.ts

@@ -4,9 +4,9 @@
  * for all chains, only the ones listed in the releases.
  *
  * Usage:
- *   bun run scripts/missing-broadcasts.ts airdrops
- *   bun run scripts/missing-broadcasts.ts flow
- *   bun run scripts/missing-broadcasts.ts lockup
+ *   bun run scripts/print-missing-broadcasts.ts airdrops
+ *   bun run scripts/print-missing-broadcasts.ts flow
+ *   bun run scripts/print-missing-broadcasts.ts lockup
  */
 import { getChain } from "@src/chains";
 import { releasesByProtocol } from "@src/releases";
@@ -15,7 +15,6 @@ import _ from "lodash";
 import { checkBroadcast, checkZKBroadcast } from "./check-broadcast";
 import logger from "./logger";
 
-// Emojis for better visual output
 const EMOJIS = {
   check: "✅",
   cross: "❌",
@@ -26,25 +25,18 @@ const EMOJIS = {
   warning: "⚠️",
 } as const;
 
-type BroadcastType = Sablier.Protocol;
-
-function parseArgs(): BroadcastType {
-  const protocol = process.argv[2] as BroadcastType;
-  const validProtocols: BroadcastType[] = ["airdrops", "flow", "legacy", "lockup"];
+function parseArgs(): Sablier.Protocol {
+  const protocol = process.argv[2] as Sablier.Protocol;
+  const validProtocols: Sablier.Protocol[] = ["airdrops", "flow", "legacy", "lockup"];
   if (!protocol || !validProtocols.includes(protocol)) {
-    logger.error("Error: Please provide one of these protocols: airdrops, flow, legacy, lockup");
-    process.exit(1);
+    const msg = `Error: Please provide one of these protocols: ${validProtocols.join(", ")}`;
+    logger.error(msg);
+    throw new Error(msg);
   }
 
   return protocol;
 }
 
-// Get broadcast type from command line
-const protocol = parseArgs();
-
-/**
- * Prints a section header with a nice separator
- */
 function printSectionHeader(text: string): void {
   const separator = "═".repeat(50);
   console.log(`\n${separator}`);
@@ -54,11 +46,11 @@ function printSectionHeader(text: string): void {
 
 async function main(): Promise<void> {
   const missing: Record<string, Sablier.Chain[]> = {};
-  const releasesToCheck = releasesByProtocol[protocol];
+  const protocol = parseArgs();
 
-  console.log(`\n${EMOJIS.folder} Checking ${protocol} broadcasts...\n`);
+  logger.info(`\n${EMOJIS.folder} Checking ${protocol} broadcasts...\n`);
 
-  for (const release of releasesToCheck) {
+  for (const release of releasesByProtocol[protocol]) {
     for (const deployment of release.deployments) {
       const chain = getChain(deployment.chainId);
 
@@ -146,11 +138,10 @@ async function main(): Promise<void> {
   console.log(`${EMOJIS.testnet} Missing testnet broadcasts: ${testnetCount}\n`);
 }
 
-// Run the script
 main().catch((error) => {
   logger.error(`Error checking missing broadcasts: ${error.message}`);
   if (error.stack) {
     logger.error(error.stack);
   }
-  process.exit(1);
+  throw error;
 });

src/contracts/index.ts

@@ -0,0 +1 @@
+export { default as names } from "./names";

src/contracts/names.ts

@@ -0,0 +1,73 @@
+import airdropsV1_1 from "@src/releases/airdrops/v1.1/manifest";
+import airdropsV1_2 from "@src/releases/airdrops/v1.2/manifest";
+import airdropsV1_3 from "@src/releases/airdrops/v1.3/manifest";
+import flowV1_0 from "@src/releases/flow/v1.0/manifest";
+import flowV1_1 from "@src/releases/flow/v1.1/manifest";
+import legacyV1_0 from "@src/releases/legacy/v1.0/manifest";
+import legacyV1_1 from "@src/releases/legacy/v1.1/manifest";
+import lockupV1_0 from "@src/releases/lockup/v1.0/manifest";
+import lockupV1_1 from "@src/releases/lockup/v1.1/manifest";
+import lockupV1_2 from "@src/releases/lockup/v1.2/manifest";
+import lockupV2_0 from "@src/releases/lockup/v2.0/manifest";
+import type { Sablier } from "@src/types";
+import _ from "lodash";
+
+/**
+ * At runtime: for v1.x, merge `core` + `periphery`; for v2.0, use the top-level record directly.
+ */
+function flattenNames(manifest: Sablier.Manifest): Record<string, string> {
+  if ("core" in manifest && "periphery" in manifest) {
+    const lockupManifest = manifest as Sablier.Manifest.LockupV1;
+    return { ...lockupManifest.core, ...lockupManifest.periphery };
+  }
+  // v2.0 has no core/periphery nesting
+  return { ...manifest } as Record<string, string>;
+}
+
+/**
+ * Works at compile-time!
+ */
+type LeafKeys<T> = T extends { core: Record<string, unknown>; periphery: Record<string, unknown> }
+  ? keyof T["core"] | keyof T["periphery"]
+  : keyof T;
+
+type A1_1 = LeafKeys<typeof airdropsV1_1>;
+type A1_2 = LeafKeys<typeof airdropsV1_2>;
+type A1_3 = LeafKeys<typeof airdropsV1_3>;
+
+type F1_0 = LeafKeys<typeof flowV1_0>;
+type F1_1 = LeafKeys<typeof flowV1_1>;
+
+type LEGACY_1_0 = LeafKeys<typeof legacyV1_0>;
+type LEGACY_1_1 = LeafKeys<typeof legacyV1_1>;
+
+type L1_0 = LeafKeys<typeof lockupV1_0>;
+type L1_1 = LeafKeys<typeof lockupV1_1>;
+type L1_2 = LeafKeys<typeof lockupV1_2>;
+type L2_0 = LeafKeys<typeof lockupV2_0>;
+
+// Final exported type: only these known keys allowed
+export type ContractNames = Record<
+  A1_1 | A1_2 | A1_3 | F1_0 | F1_1 | LEGACY_1_0 | LEGACY_1_1 | L1_0 | L1_1 | L1_2 | L2_0,
+  string
+>;
+
+// Runtime: flatten & merge across all releases
+const manifests = [
+  airdropsV1_1,
+  airdropsV1_2,
+  airdropsV1_3,
+  flowV1_0,
+  flowV1_1,
+  legacyV1_0,
+  legacyV1_1,
+  lockupV1_0,
+  lockupV1_1,
+  lockupV1_2,
+  lockupV2_0,
+];
+const flattened = manifests.map(flattenNames);
+
+const names: ContractNames = _.merge({}, ...flattened) as ContractNames;
+
+export default names;

src/helpers.ts

@@ -1,7 +1,6 @@
 import { getChain } from "@src/chains";
 import _ from "lodash";
 import type { Sablier } from "./types";
-import Version from "./version";
 
 /**
  * Get the explorer URL for a contract. Compatible with Etherscan, Blockscout, etc.
@@ -13,23 +12,6 @@ export function getContractExplorerURL(explorerURL: string, contractAddress: Sab
   return `${explorerURL}/address/${contractAddress}`;
 }
 
-/**
- * Check if a version is valid for a given protocol
- * @see {@link Version}
- * @param protocol - The protocol to check (airdrops, flow, legacy, lockup)
- * @param version - The version to validate
- * @returns Whether the version is valid for the given protocol
- */
-export function isValidVersion(protocol: Sablier.Protocol, version: Sablier.Version): boolean {
-  const protocolMap = {
-    airdrops: Version.Airdrops,
-    flow: Version.Flow,
-    legacy: Version.Legacy,
-    lockup: Version.Lockup,
-  };
-  return _.some(_.values(protocolMap[protocol]), (v) => v === version);
-}
-
 export function sortChains<T extends { name: string }>(chains: T[]): T[] {
   return chains.sort((a, b) => a.name.localeCompare(b.name));
 }

src/index.ts

@@ -3,5 +3,6 @@ export * from "./helpers";
 export * from "./indexers";
 export * from "./releases";
 export * from "./types";
+export * as contracts from "./contracts";
 export * as nativeTokens from "./native-tokens";
 export { default as Version } from "./version";

src/releases/airdrops/index.ts

@@ -3,10 +3,6 @@ import { release as releaseV1_1 } from "./v1.1";
 import { release as releaseV1_2 } from "./v1.2";
 import { release as releaseV1_3 } from "./v1.3";
 
-export const airdrops: Sablier.Release[] = [releaseV1_1, releaseV1_2, releaseV1_3];
+const airdrops: Sablier.Release[] = [releaseV1_1, releaseV1_2, releaseV1_3];
 
-export const airdropsByVersion: Record<Sablier.Version.Airdrops, Sablier.Release> = {
-  "v1.1": releaseV1_1,
-  "v1.2": releaseV1_2,
-  "v1.3": releaseV1_3,
-};
+export default airdrops;