@effectstream/midnight-contracts 0.100.0

package/src/midnight-env.ts

@@ -0,0 +1,90 @@
+import type { NetworkId } from "@midnight-ntwrk/wallet-sdk-abstractions";
+import { mnemonicToSeed } from "@scure/bip39";
+import { Buffer } from "node:buffer";
+import { getEnv } from "@effectstream/utils/runtime";
+
+const getEnvValue = (key: string): string | undefined => {
+  return getEnv(key);
+};
+
+const env = (key: string | string[], fallback?: string): string => {
+  if (typeof key === 'string') {
+    return getEnvValue(key)?.trim() || fallback || "";
+  }
+  if (Array.isArray(key)) {
+    return key.map((k) => getEnvValue(k)?.trim()).find((value) => !!value) ||
+    fallback ||
+    "";
+  }
+  throw new Error('Invalid key type');
+}
+
+type NetworkConfig = {
+    indexer: string;
+    indexerWS: string;
+    node: string;
+    proofServer: string;
+    networkId: NetworkId.NetworkId;
+    genesisWalletSeed: string;
+}
+
+// Midnight Network default configurations
+const undeployedNetworkConfig: NetworkConfig = {
+    indexer: "http://127.0.0.1:8088/api/v3/graphql",
+    indexerWS: "ws://127.0.0.1:8088/api/v3/graphql/ws",
+    node: "http://127.0.0.1:9944",
+    networkId: "undeployed" as NetworkId.NetworkId,
+    proofServer: "http://127.0.0.1:6300",
+    // In local mode, the Genesis Wallet Seed determines the initial funded wallet
+    genesisWalletSeed: "0000000000000000000000000000000000000000000000000000000000000001",
+} as const;
+
+const deployedNetworkConfig = (networkId: NetworkId.NetworkId): NetworkConfig => ({
+    indexer: `https://indexer.${networkId}.midnight.network/api/v3/graphql`,
+    indexerWS: `wss://indexer.${networkId}.midnight.network/api/v3/graphql/ws`,
+    node: `https://rpc.${networkId}.midnight.network`,
+    proofServer: "http://127.0.0.1:6300",
+    networkId,
+    genesisWalletSeed: '',
+});
+
+const networkId = env("MIDNIGHT_NETWORK_ID") || "undeployed";
+let selectedNetworkConfig: NetworkConfig;
+switch (networkId) {
+  case "undeployed":
+    selectedNetworkConfig = undeployedNetworkConfig;
+    break;
+  case "mainnet":
+  case "testnet":
+  case "devnet":
+  case "qanet":
+  case "preview":
+  case "preprod":
+  default:
+    selectedNetworkConfig = deployedNetworkConfig(networkId as NetworkId.NetworkId);
+    break;
+}
+
+let walletSeed: string;
+if (env("MIDNIGHT_WALLET_SEED")) {
+  walletSeed = env("MIDNIGHT_WALLET_SEED");
+} else if (env("MIDNIGHT_WALLET_MNEMONIC")) {
+  walletSeed = Buffer.from(await mnemonicToSeed(env("MIDNIGHT_WALLET_MNEMONIC"))).toString('hex');
+} else {
+  walletSeed = selectedNetworkConfig.genesisWalletSeed;
+}
+
+export const midnightNetworkConfig = {
+  id: selectedNetworkConfig.networkId,
+  indexer: env("MIDNIGHT_INDEXER_HTTP", selectedNetworkConfig.indexer),
+  indexerWS: env("MIDNIGHT_INDEXER_WS", selectedNetworkConfig.indexerWS),
+  node: env("MIDNIGHT_NODE_HTTP", selectedNetworkConfig.node),
+  proofServer: env(["MIDNIGHT_PROOF_SERVER_URL", "MIDNIGHT_PROOF_SERVER"], selectedNetworkConfig.proofServer),
+  walletSeed,
+};
+
+const isLocalProofServer = !!midnightNetworkConfig.proofServer.match(/(localhost|127\.0\.0\.1)/);
+export const isExternalProofServerConfigured = !isLocalProofServer;
+
+// Set this using MIDNIGHT_NETWORK_ID=<network-id>
+export type MidnightNetworkConfig = typeof midnightNetworkConfig;

package/src/mnemonicToSeed.ts

@@ -0,0 +1,19 @@
+import * as bip39 from '@scure/bip39';
+import { wordlist as english } from '@scure/bip39/wordlists/english.js';
+import { Buffer } from "node:buffer";
+
+// Use a BIP39 mnemonic to derive a seed.
+// This is compatible with Lace Wallets.
+export const mnemonicToSeed = async (mnemonic: string): Promise<Buffer> => {
+    const words = mnemonic.trim().split(/\s+/);
+    if (!bip39.validateMnemonic(words.join(' '), english)) {
+      throw new Error('Invalid mnemonic phrase');
+    }
+    // Use BIP39 standard seed derivation (PBKDF2)
+    // Produces 64 bytes. 
+    // hashes it (mixes it up) 2048 times using SHA-512
+    const seed = await bip39.mnemonicToSeed(words.join(' '));
+    return Buffer.from(seed);
+    // As hex string seed: 
+    // Buffer.from(await mnemonicToSeed(mnemonic)).toString('hex')
+  };

package/src/mod.ts

@@ -0,0 +1,29 @@
+export { deployMidnightContract } from "./deploy.ts";
+export type {
+    DeployConfig,
+    NetworkUrls,
+    WalletResult,
+    InitialOwner,
+} from "./types.ts";
+export {
+    resolveWalletSyncTimeoutMs,
+    safeStringifyProgress,
+    syncAndWaitForFunds,
+    buildWalletFacade,
+    getInitialShieldedState,
+    registerNightForDust,
+    getInitialDustState,
+    waitForDustFunds,
+    waitForDustFundsWithRetry,
+    saveDustState,
+    loadDustState,
+} from "./get-wallet-info.ts";
+export type { WalletSyncMode, DustSyncWithRetryOptions } from "./get-wallet-info.ts";
+export { CONSTANTS } from "./constants.ts";
+export { 
+    buildWalletAndWaitForFunds, 
+    extractInitialOwnerFromWallet,    
+} from "./build-wallet.ts";
+export { readMidnightContract } from "./read-contract.ts";
+export { configureMidnightNodeProviders } from "./providers.ts";
+export { midnightNetworkConfig } from "./midnight-env.ts";

package/src/providers.ts

@@ -0,0 +1,116 @@
+// ============================================================================
+// Provider Configuration
+// ============================================================================
+
+import { Buffer } from "node:buffer";
+import type { ZswapSecretKeys, DustSecretKey, CoinPublicKey, EncPublicKey, FinalizedTransaction, TransactionId } from "@midnight-ntwrk/ledger-v8";
+import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
+import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
+import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
+import { NodeZkConfigProvider } from "@midnight-ntwrk/midnight-js-node-zk-config-provider";
+import type { WalletProvider, MidnightProvider, MidnightProviders, UnboundTransaction } from "@midnight-ntwrk/midnight-js-types";
+import type { WalletFacade } from "@midnight-ntwrk/wallet-sdk-facade";
+import type { NetworkUrls } from "./types.ts";
+import type { UnshieldedKeystore } from "@midnight-ntwrk/wallet-sdk-unshielded-wallet";
+import { CONSTANTS } from "./constants.ts";
+// import { Contract } from "@midnight-ntwrk/compact-js";
+import { getEnv } from "@effectstream/utils/runtime";
+
+/**
+ * Create a TTL date for transactions
+ */
+function createTtl(): Date {
+    return new Date(Date.now() + CONSTANTS.TTL_DURATION_MS);
+  }
+
+/**
+ * Create wallet and midnight provider adapter for WalletFacade
+ *
+ * Implements the WalletProvider and MidnightProvider interfaces
+ * as defined in @midnight-ntwrk/midnight-js-types v3.x
+ */
+function createWalletAndMidnightProvider(
+    wallet: WalletFacade,
+    zswapSecretKeys: ZswapSecretKeys,
+    walletZswapSecretKeys: ZswapSecretKeys,
+    dustSecretKey: DustSecretKey,
+    walletDustSecretKey: DustSecretKey,
+    unshieldedKeystore: UnshieldedKeystore
+  ): WalletProvider & MidnightProvider {
+    return {
+      getCoinPublicKey(): CoinPublicKey {
+        console.log("✅ Getting coin public key", zswapSecretKeys.coinPublicKey);
+        return zswapSecretKeys.coinPublicKey;
+      },
+      getEncryptionPublicKey(): EncPublicKey {
+        console.log("✅ Getting encryption public key", zswapSecretKeys.encryptionPublicKey);
+        return zswapSecretKeys.encryptionPublicKey;
+      },
+      async balanceTx(
+        tx: UnboundTransaction,
+        ttl?: Date
+      ): Promise<FinalizedTransaction> {
+        console.log("✅ Balancing transaction", tx);
+        const bound = tx.bind();
+        const finalizedTransactionRecipe = await wallet.balanceFinalizedTransaction(bound, {
+          shieldedSecretKeys: zswapSecretKeys, 
+          dustSecretKey: dustSecretKey,
+         }, { ttl: ttl ?? createTtl() } );
+        const x = await wallet.signRecipe(finalizedTransactionRecipe, (payload) => unshieldedKeystore.signData(payload));
+        return wallet.finalizeRecipe(x);
+      },
+      submitTx(tx: FinalizedTransaction): Promise<TransactionId> {
+        console.log("✅ Submitting transaction", tx);
+        return wallet.submitTransaction(tx);
+      },
+    };
+  }
+  
+  /**
+   * Configure all providers needed for contract deployment
+   */
+  export function configureMidnightNodeProviders(
+    wallet: WalletFacade,
+    zswapSecretKeys: ZswapSecretKeys,
+    walletZswapSecretKeys: ZswapSecretKeys,
+    dustSecretKey: DustSecretKey,
+    walletDustSecretKey: DustSecretKey,
+    networkUrls: Required<Omit<NetworkUrls, "id">>,
+    privateStateStoreName: string,
+    zkConfigPath: string,
+    unshieldedKeystore: UnshieldedKeystore
+  ): MidnightProviders {
+    const signingKeyStoreName = `${privateStateStoreName}-signing-keys`;
+    const walletAndMidnightProvider = createWalletAndMidnightProvider(
+      wallet,
+      zswapSecretKeys,
+      walletZswapSecretKeys,
+      dustSecretKey,
+      walletDustSecretKey,
+      unshieldedKeystore
+    );
+    const zkConfigProvider = new NodeZkConfigProvider(zkConfigPath);
+    return {
+      // For deployment, we use full private state config because we may need to verify
+      // the deployed contract state. For batcher/transaction submission use cases,
+      // a minimal config with just walletProvider is sufficient and much faster:
+      //   levelPrivateStateProvider({ walletProvider })
+      // Omitting privateStateStoreName/midnightDbName avoids historical private state sync.
+      privateStateProvider: levelPrivateStateProvider({
+        midnightDbName: "midnight-level-db-deploy", // Use separate DB for deployment to avoid lock conflicts
+        privateStateStoreName,
+        signingKeyStoreName,
+        // walletProvider: walletAndMidnightProvider, // Use wallet's encryption key for private state
+        privateStoragePasswordProvider: async () => getEnv("MIDNIGHT_STORAGE_PASSWORD") ?? "YourPasswordMy1!",
+        accountId: Buffer.from(zswapSecretKeys.coinPublicKey).toString('hex'),
+      }), // Type assertion: runtime supports walletProvider even though types don't reflect it yet
+      publicDataProvider: indexerPublicDataProvider(
+        networkUrls.indexer,
+        networkUrls.indexerWS
+      ),
+      zkConfigProvider,
+      proofProvider: httpClientProofProvider(networkUrls.proofServer, zkConfigProvider),
+      walletProvider: walletAndMidnightProvider,
+      midnightProvider: walletAndMidnightProvider,
+    };
+  }

package/src/read-contract.ts

@@ -0,0 +1,439 @@
+// TODO Remove references to "src/managed" as this is not standard.
+
+import * as path from "node:path";
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import { getEnv, cwd, isNotFoundError, getRuntime } from "@effectstream/utils/runtime";
+
+/**
+* Information about a compiled Midnight contract
+*/
+export type MidnightContractCompilerInfo = {
+  /** Circuit definitions for the contract */
+  circuits: any[];
+  /** Witness definitions for the contract */
+  witnesses: any[];
+  /** Contract definitions */
+  contracts: any[];
+};
+
+/**
+* Address information for a deployed contract
+* Supports both legacy format (string) and new format (network-keyed object)
+*/
+export type MidnightContractAddressInfo = {
+  /** The deployed contract address - can be a string (legacy) or network-keyed object */
+  contractAddress: string
+};
+
+/**
+* Complete contract information combining address and compiler info
+*/
+export type MidnightContractInfo = {
+  /** The deployed contract address for the specified network */
+  contractAddress: string;
+  /** Compiler-generated contract information */
+  contractInfo: MidnightContractCompilerInfo;
+  zkConfigPath: string;
+  /** Directory where the contract file is located */
+  contractDir: string;
+};
+
+const cachedContractInfo: Record<string, MidnightContractInfo> = {};
+
+/**
+* Recursively searches for all files matching a name in a directory and its subdirectories.
+* @param dir - The directory to search in
+* @param fileName - The file name to search for
+* @param maxDepth - Maximum depth to search (default: 5)
+* @param currentDepth - Current search depth (internal use)
+* @returns Array of directories containing matching files
+*/
+function findAllFilesRecursive(
+  dir: string,
+  fileName: string,
+  maxDepth: number = 5,
+  currentDepth: number = 0
+): string[] {
+  const results: string[] = [];
+  
+  if (currentDepth > maxDepth) {
+    return results;
+  }
+  
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    
+    // First check if the file exists in the current directory
+    const hasFile = entries.some(entry =>
+      entry.isFile() && entry.name === fileName
+    );
+    
+    if (hasFile) {
+      results.push(dir);
+    }
+    
+    // Then recursively search subdirectories
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        // Skip common directories that are unlikely to contain contracts
+        const skipDirs = ["node_modules", ".git", "dist", "build", ".deno"];
+        if (skipDirs.includes(entry.name)) {
+          continue;
+        }
+        
+        const subDir = path.join(dir, entry.name);
+        const subResults = findAllFilesRecursive(subDir, fileName, maxDepth, currentDepth + 1);
+        results.push(...subResults);
+      }
+    }
+  } catch {
+    // Can't read directory, skip it
+  }
+  
+  return results;
+}
+
+/**
+* Validates that a directory contains a valid Midnight contract structure.
+* Checks if the contractName directory with src/managed/ exists.
+*/
+function isValidMidnightContractDir(dir: string, contractName: string): boolean {
+  const managedDir = path.join(dir, contractName, "src/managed");
+  try {
+    const stats = statSync(managedDir);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determine whether a directory contains the expected Midnight compiler artifacts.
+ */
+function hasManagedArtifacts(dir: string): boolean {
+  const requiredDirs = ["compiler", "contract"];
+  try {
+    return requiredDirs.every((entry) => {
+      const stats = statSync(path.join(dir, entry));
+      return stats.isDirectory();
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolves the directory that actually holds the managed compiler artifacts.
+ * Supports both nested structures (src/managed/<name>/...) and flattened ones
+ * (src/managed/...).
+ */
+function resolveManagedArtifactsDir(managedDir: string): string {
+  try {
+    for (const entry of readdirSync(managedDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(managedDir, entry.name);
+      if (hasManagedArtifacts(candidate)) {
+        return candidate;
+      }
+    }
+  } catch {
+    // handled below
+  }
+
+  if (hasManagedArtifacts(managedDir)) {
+    return managedDir;
+  }
+
+  throw new Error(
+    `Managed compiler artifacts not found under ${managedDir}. ` +
+      `Expected either src/managed/<subdir>/{contract,compiler,...} or ` +
+      `src/managed/{contract,compiler,...}.`
+  );
+}
+
+/**
+* Finds the directory containing a Midnight contract by searching for the contract directory structure.
+* This is used during deployment when the contract.json file doesn't exist yet.
+* Searches for directories matching {contractName}/src/managed/ pattern.
+*/
+export function findContractDirectoryForDeploy(
+  contractName: string,
+  baseDir?: string
+): string | null {
+  let startDir: string;
+  
+  if (baseDir) {
+    startDir = path.resolve(baseDir);
+  } else {
+    startDir = cwd();
+  }
+  
+  let currentDir = path.resolve(startDir);
+  const root = path.parse(currentDir).root;
+  
+  while (currentDir !== root) {
+    try {
+      const entries = readdirSync(currentDir, { withFileTypes: true });
+      
+      // Check if contract directory exists here
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name === contractName) {
+          // Validate it's a Midnight contract by checking for src/managed/
+          if (isValidMidnightContractDir(currentDir, contractName)) {
+            return currentDir;
+          }
+        }
+      }
+      
+      // Also search recursively in subdirectories (up to 3 levels deep)
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const skipDirs = ["node_modules", ".git", "dist", "build", ".deno"];
+          if (skipDirs.includes(entry.name)) {
+            continue;
+          }
+          
+          try {
+            const subDir = path.join(currentDir, entry.name);
+            const subEntries = readdirSync(subDir, { withFileTypes: true });
+            
+            // Check direct subdirectory
+            for (const subEntry of subEntries) {
+              if (subEntry.isDirectory() && subEntry.name === contractName) {
+                if (isValidMidnightContractDir(subDir, contractName)) {
+                  return subDir;
+                }
+              }
+            }
+            
+            // Check one more level deep
+            for (const subEntry of subEntries) {
+              if (subEntry.isDirectory() && !skipDirs.includes(subEntry.name)) {
+                const subSubDir = path.join(subDir, subEntry.name);
+                try {
+                  const subSubEntries = readdirSync(subSubDir, { withFileTypes: true });
+                  for (const subSubEntry of subSubEntries) {
+                    if (subSubEntry.isDirectory() && subSubEntry.name === contractName) {
+                      if (isValidMidnightContractDir(subSubDir, contractName)) {
+                        return subSubDir;
+                      }
+                    }
+                  }
+                } catch {
+                  // Skip if can't read
+                }
+              }
+            }
+          } catch {
+            // Skip if can't read
+          }
+        }
+      }
+      
+      currentDir = path.dirname(currentDir);
+    } catch {
+      currentDir = path.dirname(currentDir);
+    }
+  }
+  
+  return null;
+}
+
+/**
+* Finds the directory containing contract files by searching from a starting directory upward.
+* At each level, recursively searches downward for the contract file.
+* Validates that found contract.json files belong to Midnight contracts.
+* This prevents confusion with EVM contract.json files or other similarly named files.
+*/
+function findContractDirectory(
+  startDir: string,
+  contractFileName: string,
+  contractName: string
+): string | null {
+  let currentDir = path.resolve(startDir);
+  const root = path.parse(currentDir).root;
+  
+  while (currentDir !== root) {
+    // Recursively search from current directory downward for ALL matching files
+    const foundDirs = findAllFilesRecursive(currentDir, contractFileName);
+    
+    // Validate each found directory to ensure it's a Midnight contract
+    for (const found of foundDirs) {
+      if (isValidMidnightContractDir(found, contractName)) {
+        return found;
+      }
+      // If not valid, continue checking other found directories
+      // This handles cases where multiple contract.json files exist
+    }
+    
+    // Move up one directory
+    currentDir = path.dirname(currentDir);
+  }
+  
+  return null;
+}
+
+/**
+* Reads contract information from JSON files in a context-aware manner.
+* 
+* The function detects the directory containing contract files by searching
+* from the current working directory upward, or uses an explicit baseDir if provided.
+* This makes it work regardless of where the function is imported from.
+* 
+* @param contractName - The name of the contract directory (e.g., 'contract-eip-1155', 'contract-counter')
+* @param contractFileName - The name of the contract address file (default: 'contract.json')
+* @param options - Optional configuration: baseDir to override search location, networkId to select specific network
+* @returns The complete contract information including address and compiler data
+*/
+export function readMidnightContract(
+  contractName: string,
+  options?: { baseDir?: string; networkId?: string; contractFileName?: string }
+): MidnightContractInfo {
+  const baseDir = options?.baseDir;
+  const resolvedNetworkId = options?.networkId || "undeployed";
+  const networkFileName = `${contractName}.${resolvedNetworkId}.json`;
+  const candidateFileNames = [
+    networkFileName,
+    `${contractName}.json`,
+    "contract.json",
+  ];
+
+
+  let moduleDir: string;
+
+  if (baseDir) {
+    moduleDir = path.resolve(baseDir);
+  } else if (getRuntime().environment === 'backend') {
+    let foundDir: string | null = null;
+
+    for (const candidate of candidateFileNames) {
+      const dir = findContractDirectory(cwd(), candidate, contractName);
+      if (dir) {
+        foundDir = dir;
+        break;
+      }
+    }
+
+    if (!foundDir) {
+      throw new Error(
+        `Could not find Midnight contract directory for "${contractName}". ` +
+          `Searched for ${candidateFileNames.join(", ")} starting from ${path.resolve(cwd())}. ` +
+          `Please ensure you're running from a directory that contains or is a parent of the Midnight contract files, ` +
+          `or provide an explicit baseDir parameter. ` +
+          `Note: This function only finds Midnight contracts (with src/managed/ structure), not EVM contracts.`
+      );
+    }
+
+    moduleDir = foundDir;
+  } else {
+    const envContractAddress = getEnv("MIDNIGHT_CONTRACT_ADDRESS");
+    return {
+      contractAddress: envContractAddress || "",
+      contractInfo: { circuits: [], witnesses: [], contracts: [] },
+      zkConfigPath: "",
+      contractDir: "",
+    }; 
+  }
+
+  const normalizedModuleDir = path.resolve(moduleDir);
+  for (const candidate of candidateFileNames) {
+    const cacheKey = `${normalizedModuleDir}:${contractName}:${candidate}`;
+    if (cachedContractInfo[cacheKey]) return cachedContractInfo[cacheKey];
+  }
+
+  let contractAddressJson: string | undefined;
+  let actualContractFileName: string | undefined;
+
+  for (const candidate of candidateFileNames) {
+    const candidatePath = path.join(moduleDir, candidate);
+    try {
+      contractAddressJson = readFileSync(candidatePath, "utf-8");
+      actualContractFileName = candidate;
+      break;
+    } catch (err) {
+      if (isNotFoundError(err)) {
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  if (!contractAddressJson || !actualContractFileName) {
+    throw new Error(
+      `Contract files not found for "${contractName}". Tried: ${candidateFileNames.join(
+        ", ",
+      )} under ${moduleDir}. Please verify the compiler artifacts and contract JSON exist.`
+    );
+  }
+
+  let managedArtifactsDir = "";
+  try {
+    // Find the first directory inside the managed directory
+    const managedDir = path.join(moduleDir, contractName, "src/managed/");
+    try {
+      managedArtifactsDir = resolveManagedArtifactsDir(managedDir);
+    } catch (error) {
+      throw new Error(
+        `Managed directory not found or invalid: ${managedDir}. ${(error as Error).message}`
+      );
+    }
+
+    // Construct the full path to the contract info file using the resolved managed directory
+    const contractInfoPath = path.join(
+      managedArtifactsDir,
+      "compiler/contract-info.json"
+    );
+    const zkConfigPath = path.resolve(managedArtifactsDir);
+    const contractInfoJson = readFileSync(contractInfoPath, "utf-8");
+    const contractAddressInfo = JSON.parse(contractAddressJson) as MidnightContractAddressInfo;
+    const contractInfo = JSON.parse(contractInfoJson) as MidnightContractCompilerInfo;
+    
+    // Handle both legacy format (string) and new format (network-keyed object)
+    let contractAddress: string;
+    let contractAddresses: Record<string, string>;
+    
+    if (typeof contractAddressInfo.contractAddress === "string") {
+      // Legacy format - single string address
+      contractAddress = contractAddressInfo.contractAddress;
+      contractAddresses = { [resolvedNetworkId]: contractAddress };
+    } else {
+      contractAddresses = contractAddressInfo.contractAddress;
+      contractAddress = contractAddresses[resolvedNetworkId];
+      
+      if (!contractAddress) {
+        throw new Error(
+          `Contract address not found for network "${resolvedNetworkId}". ` +
+          `Available networks: ${Object.keys(contractAddresses).join(", ")}`
+        );
+      }
+    }
+    
+    // Override contract address if MIDNIGHT_CONTRACT_ADDRESS env var is set
+    const envContractAddress = getEnv("MIDNIGHT_CONTRACT_ADDRESS");
+    if (envContractAddress) {
+      contractAddress = envContractAddress;
+      contractAddresses[resolvedNetworkId] = envContractAddress;
+    }
+    
+    const cacheKey = `${normalizedModuleDir}:${contractName}:${actualContractFileName}`;
+    cachedContractInfo[cacheKey] = {
+      contractAddress,
+      contractInfo,
+      zkConfigPath,
+      contractDir: moduleDir,
+    };
+
+    return cachedContractInfo[cacheKey];
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      const fileList = candidateFileNames
+        .map((name) => path.join(moduleDir, name))
+        .join(", ");
+      throw new Error(
+        `Contract files not found - expected one of [${fileList}] and compiler artifacts under ${managedArtifactsDir}.`
+      );
+    }
+    throw new Error(`Failed to read contract files: ${String(err)}`);
+  }
+}
+