@0xsequence/catapult 1.2.1 → 1.3.1

package/src/commands/etherscan.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander'
 import chalk from 'chalk'
 import { loadNetworks } from '../lib/network-loader'
+import { resolveSingleChainId } from '../lib/network-selection'
 import { projectOption, verbosityOption } from './common'
 import { setVerbosity } from '../index'
 import * as solc from 'solc'
@@ -22,7 +23,7 @@ function getEtherscanApiUrl(chainId: number): string {
 }
 
 type EtherscanSourceEnvelope = {
-  rawResult: Record<string, any>
+  rawResult: Record<string, unknown>
   parsedSource: unknown // standard-json object or flattened string
 }
 
@@ -81,7 +82,7 @@ async function fetchFromEtherscan(
     if (!Array.isArray(data.result) || data.result.length === 0) {
       throw new Error('Empty result from Etherscan')
     }
-    const first = (data.result as Array<{ SourceCode?: string }>)[0] as Record<string, any>
+    const first = (data.result as Array<{ SourceCode?: string }>)[0] as Record<string, unknown>
     const sourceCodeRaw = first?.SourceCode as string
     if (typeof sourceCodeRaw !== 'string' || sourceCodeRaw.length === 0) {
       throw new Error('No SourceCode found on Etherscan')
@@ -120,7 +121,7 @@ export function makeEtherscanCommand(): Command {
     verbosityOption(cmd)
     cmd
       .option('--etherscan-api-key <key>', 'Etherscan API key. Can also be set via ETHERSCAN_API_KEY env var.')
-      .option('-n, --network <chainId>', 'Target network chain ID (required to select proper Etherscan endpoint)')
+     .option('-n, --network <selector>', 'Target network (chain ID or name). When a name matches multiple networks, the first match is used.')
       .option('-a, --address <address>', 'Contract address to query', '')
       .option('--raw', 'Print raw response (no pretty JSON). Useful for piping.', false)
     return cmd
@@ -147,22 +148,15 @@ export function makeEtherscanCommand(): Command {
 
       // Determine chainId
       let chainId: number | undefined
+      const networks = await loadNetworks(options.project)
       if (options.network) {
-        const parsed = Number(options.network)
-        if (Number.isNaN(parsed)) {
-          console.error(chalk.red('Invalid --network value. Must be a chain ID number.'))
-          process.exit(1)
-        }
-        chainId = parsed
-      } else {
-        // If network not provided, try to infer: if only one network configured, use it
-        const networks = await loadNetworks(options.project)
-        if (networks.length === 1) {
-          chainId = networks[0].chainId
-        } else {
-          console.error(chalk.red('Please provide --network <chainId> (multiple or zero networks configured).'))
-          process.exit(1)
-        }
+        chainId = resolveSingleChainId(options.network, networks)
+      } else if (networks.length === 1) {
+        chainId = networks[0].chainId
+      }
+      if (!chainId) {
+        console.error(chalk.red('Please provide --network <selector>. When multiple networks are configured, selection is required.'))
+        process.exit(1)
       }
 
       const result = await fetchFromEtherscan(chainId!, apiKey, options.address, 'getabi')
@@ -201,21 +195,15 @@ export function makeEtherscanCommand(): Command {
 
       // Determine chainId
       let chainId: number | undefined
+      const networks2 = await loadNetworks(options.project)
       if (options.network) {
-        const parsed = Number(options.network)
-        if (Number.isNaN(parsed)) {
-          console.error(chalk.red('Invalid --network value. Must be a chain ID number.'))
-          process.exit(1)
-        }
-        chainId = parsed
-      } else {
-        const networks = await loadNetworks(options.project)
-        if (networks.length === 1) {
-          chainId = networks[0].chainId
-        } else {
-          console.error(chalk.red('Please provide --network <chainId> (multiple or zero networks configured).'))
-          process.exit(1)
-        }
+        chainId = resolveSingleChainId(options.network, networks2)
+      } else if (networks2.length === 1) {
+        chainId = networks2[0].chainId
+      }
+      if (!chainId) {
+        console.error(chalk.red('Please provide --network <selector>. When multiple networks are configured, selection is required.'))
+        process.exit(1)
       }
 
       const result = await fetchFromEtherscan(chainId!, apiKey, options.address, 'getsourcecode') as EtherscanSourceEnvelope
@@ -228,18 +216,29 @@ export function makeEtherscanCommand(): Command {
       const optimizationUsed = (raw?.OptimizationUsed as string | undefined) || ''
       const runsStr = (raw?.Runs as string | undefined) || ''
       const evmVersionRaw = (raw?.EVMVersion as string | undefined) || ''
-      const isStandardJson = parsed && typeof parsed === 'object' && (parsed as any).language && (parsed as any).sources
+      const isStandardJson = !!(parsed && typeof parsed === 'object' && 'language' in parsed && 'sources' in parsed)
 
       // If we have a standard JSON input, use it; otherwise build one from flattened source
-      let input: any
+      type SolcInput = {
+        language: string
+        sources: Record<string, { content?: string }>
+        settings?: {
+          optimizer?: { enabled?: boolean; runs?: number }
+          evmVersion?: string
+          outputSelection?: Record<string, Record<string, string[]>>
+          viaIR?: boolean
+          libraries?: Record<string, Record<string, string>>
+        }
+      }
+      let input: SolcInput
       if (isStandardJson) {
-        input = { ...(parsed as any) }
+        input = parsed as SolcInput
         // Ensure outputSelection includes required entries to get creation bytecode and metadata
-        const currentSel = input.settings?.outputSelection || {}
-        const mergedSel = {
+        const currentSel = (input.settings?.outputSelection ?? {}) as Record<string, Record<string, string[]>>
+        const mergedSel: Record<string, Record<string, string[]>> = {
           '*': {
-            '*': Array.from(new Set([
-              ...(currentSel?.['*']?.['*'] || []),
+            '*': Array.from(new Set<string>([
+              ...((currentSel?.['*']?.['*']) || []),
               'abi',
               'evm.bytecode',
               'evm.deployedBytecode',
@@ -295,8 +294,8 @@ export function makeEtherscanCommand(): Command {
       if (versionTag) {
         outputRaw = await new Promise<string>((resolve, reject) => {
           // @ts-ignore - loadRemoteVersion exists in solc js
-          solc.loadRemoteVersion(versionTag, (err: any, specificSolc: any) => {
-            if (err || !specificSolc) return reject(err || new Error('Failed to load solc version'))
+          solc.loadRemoteVersion(versionTag, (err: unknown, specificSolc: { compile: (input: string) => string } | undefined) => {
+            if (err || !specificSolc) return reject((err as Error) || new Error('Failed to load solc version'))
             try {
               resolve(specificSolc.compile(solcInput))
             } catch (e) {
@@ -314,7 +313,8 @@ export function makeEtherscanCommand(): Command {
 
       // Determine solc versions
       const solcLongVersion = (output?.compiler?.version as string | undefined) || (compilerVersion ? compilerVersion.replace(/^v/, '') : undefined)
-      const solcVersion = (solcLongVersion || '').split('+')[0] || (typeof (solc as any).version === 'function' ? (solc as any).version() : 'unknown')
+      const solcMaybe = solc as unknown as { version?: () => string }
+      const solcVersion = (solcLongVersion || '').split('+')[0] || (typeof solcMaybe.version === 'function' ? solcMaybe.version() : 'unknown')
 
       // Augment settings with defaults similar to reference format
       const basePath = process.cwd()

package/src/commands/run.ts

@@ -5,12 +5,13 @@ import { detectNetworkFromRpc, isValidRpcUrl } from '../lib/network-utils'
 import { deploymentEvents } from '../lib/events'
 import { Network } from '../lib/types'
 import { projectOption, dotenvOption, noStdOption, verbosityOption, loadDotenv } from './common'
+import { resolveSelectedChainIds } from '../lib/network-selection'
 import { setVerbosity } from '../index'
 
 interface RunOptions {
   project: string
   privateKey?: string
-  network?: string[]
+  network?: string
   rpcUrl?: string
   dotenv?: string
   std: boolean
@@ -27,7 +28,7 @@ export function makeRunCommand(): Command {
     .description('Run deployment jobs on specified networks')
     .argument('[jobs...]', 'Specific job names or patterns to run (and their dependencies). Supports wildcards like "sequence/*" or "job?". If not provided, all jobs are run.')
     .option('-k, --private-key <key>', 'Signer private key. Can also be set via PRIVATE_KEY env var.')
-    .option('-n, --network <chainIds...>', 'One or more network chain IDs to run on. If not provided, runs on all configured networks.')
+    .option('-n, --network <selectors>', 'Comma-separated network selectors (by chain ID or name). If not provided, runs on all configured networks.')
     .option('--rpc-url <url>', 'Custom RPC URL to run on. The system will automatically detect chainId and network information. This overrides networks.yaml configuration.')
     .option('--etherscan-api-key <key>', 'Etherscan API key for contract verification. Can also be set via ETHERSCAN_API_KEY env var.')
     .option('--fail-early', 'Stop execution as soon as any job fails. Default: false', false)
@@ -97,12 +98,13 @@ export function makeRunCommand(): Command {
         throw new Error('No networks configured. Please create a networks.yaml file in your project root or use --rpc-url to specify a custom network.')
       }
 
+      const selectedChainIds = resolveSelectedChainIds(options.network, networks)
       const deployerOptions: DeployerOptions = {
         projectRoot,
         privateKey,
         networks,
         runJobs: jobs.length > 0 ? jobs : undefined,
-        runOnNetworks: options.network?.map(Number),
+        runOnNetworks: selectedChainIds,
         etherscanApiKey,
         failEarly: options.failEarly,
         noPostCheckConditions: options.noPostCheckConditions,

package/src/commands/utils.ts

@@ -1,5 +1,7 @@
 import { Command } from 'commander'
 import chalk from 'chalk'
+import * as fs from 'fs'
+import * as path from 'path'
 import { projectOption, verbosityOption } from './common'
 import { loadNetworks } from '../lib/network-loader'
 import { setVerbosity } from '../index'
@@ -48,5 +50,166 @@ export function makeUtilsCommand(): Command {
 
   utils.addCommand(chainIdToName)
 
+  // utils gen-table <output-dir>
+  const genTable = new Command('gen-table')
+    .description('Generate a consolidated addresses table from an output directory')
+    .argument('<output-dir>', 'Directory containing job output JSON files (searches recursively)')
+    .option('--name', 'Include Name column', true)
+    .option('--key', 'Include Key column', false)
+    .option('--file', 'Include File column', false)
+    .option('--chain-ids, --chainIds', 'Include ChainIds column', false)
+    .option('--job', 'Include Job column', true)
+    .option('--address', 'Include Address column', true)
+    .option('--format <format>', "Output format: 'markdown' or 'ascii' (default)", 'ascii')
+    .action(async (outputDir: string, options: { name?: boolean; key?: boolean; file?: boolean; chainIds?: boolean; job?: boolean; address?: boolean; format?: string }) => {
+      try {
+        const absoluteDir = path.resolve(outputDir)
+        if (!fs.existsSync(absoluteDir) || !fs.statSync(absoluteDir).isDirectory()) {
+          console.error(chalk.red(`Output directory not found or not a directory: ${absoluteDir}`))
+          process.exit(1)
+        }
+
+        const jsonFiles: string[] = []
+        const walk = (dir: string) => {
+          for (const entry of fs.readdirSync(dir)) {
+            const full = path.join(dir, entry)
+            const stat = fs.statSync(full)
+            if (stat.isDirectory()) walk(full)
+            else if (stat.isFile() && entry.toLowerCase().endsWith('.json')) jsonFiles.push(full)
+          }
+        }
+        walk(absoluteDir)
+
+        type Row = { job: string; chainIds: string; name: string; address: string; key: string; file: string }
+        const rows: Row[] = []
+        const addressRegex = /^0x[a-fA-F0-9]{40}$/
+
+        const toTitleCase = (slug: string): string => slug.split(/[-_\s]+/).filter(Boolean).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('')
+        const extractVersionSuffix = (jobName: string): string => {
+          const m = jobName.match(/[-_]?v(\d+)/i)
+          return m ? `V${m[1]}` : ''
+        }
+        const deriveName = (jobName: string, key: string): string => {
+          const version = extractVersionSuffix(jobName)
+          const baseJob = jobName.replace(/[-_]?v\d+$/i, '')
+          const keyCore = key.replace(/\.address$/i, '')
+          // Prefer descriptive key name; if too generic like 'factory', prefix with job base
+          const isGeneric = /^(factory|address)$/i.test(keyCore)
+          const nameCore = isGeneric ? `${toTitleCase(baseJob)} ${toTitleCase(keyCore)}` : toTitleCase(keyCore)
+          return `${nameCore.replace(/\s+/g, '')}${version}`
+        }
+
+        for (const file of jsonFiles) {
+          try {
+            const raw = fs.readFileSync(file, 'utf8')
+            const data = JSON.parse(raw)
+            if (!data || typeof data !== 'object' || !Array.isArray(data.networks)) continue
+            const jobName: string = data.jobName ?? path.basename(file, '.json')
+            for (const net of data.networks) {
+              if (!net || typeof net !== 'object') continue
+              const outputs = net.outputs as Record<string, unknown> | undefined
+              if (!outputs) continue
+              const chainIds: string[] = Array.isArray(net.chainIds) ? net.chainIds : []
+              for (const [key, value] of Object.entries(outputs)) {
+                let address: string | undefined
+                if (typeof value === 'string' && addressRegex.test(value)) {
+                  address = value
+                } else if (value && typeof value === 'object' && 'address' in value && typeof value.address === 'string' && addressRegex.test(value.address)) {
+                  address = value.address
+                }
+                if (!address) continue
+                rows.push({
+                  job: jobName,
+                  chainIds: chainIds.join(','),
+                  name: deriveName(jobName, key),
+                  address,
+                  key,
+                  file
+                })
+              }
+            }
+          } catch {
+            // skip invalid JSON
+          }
+        }
+
+        rows.sort((a, b) => a.job.localeCompare(b.job) || a.name.localeCompare(b.name))
+
+        if (rows.length === 0) {
+          console.log(chalk.yellow('No address entries found.'))
+          return
+        }
+
+        // Determine which columns to show
+        const showJob = !!options.job
+        const showAddress = !!options.address
+        const showName = !!options.name
+        const showKey = !!options.key
+        const showChainIds = !!options.chainIds
+        const showFile = !!options.file
+
+        const selectedHeaders: (keyof Row)[] = []
+        if (showJob) selectedHeaders.push('job')
+        if (showChainIds) selectedHeaders.push('chainIds')
+        if (showName) selectedHeaders.push('name')
+        if (showAddress) selectedHeaders.push('address')
+        if (showKey) selectedHeaders.push('key')
+        if (showFile) selectedHeaders.push('file')
+
+        // Titles for columns
+        const titles: Record<keyof Row, string> = {
+          job: 'Job',
+          chainIds: 'ChainIds',
+          name: 'Name',
+          address: 'Address',
+          key: 'Key',
+          file: 'File'
+        }
+        const format = String(options.format || 'markdown').toLowerCase()
+        if (format !== 'markdown' && format !== 'ascii') {
+          console.error(chalk.red("Invalid format. Use 'markdown' or 'ascii'."))
+          process.exit(1)
+        }
+
+        if (format === 'markdown') {
+          const header = '| ' + selectedHeaders.map(h => titles[h]).join(' | ') + ' |'
+          const sepMd = '| ' + selectedHeaders.map(h => '-'.repeat(Math.max(3, String(titles[h]).length))).join(' | ') + ' |'
+          console.log(header)
+          console.log(sepMd)
+          for (const r of rows) {
+            console.log('| ' + selectedHeaders.map(h => String(r[h])).join(' | ') + ' |')
+          }
+        } else {
+          // ascii rendering with box-drawing characters
+          const widths: Record<string, number> = {}
+          for (const h of selectedHeaders) {
+            widths[h] = Math.max(titles[h].length, ...rows.map(r => String(r[h]).length))
+          }
+          const makeSep = (left: string, mid: string, right: string, fill: string) => {
+            return left + selectedHeaders.map(h => fill.repeat(widths[h] + 2)).join(mid) + right
+          }
+          const pad = (s: string, w: number) => s + ' '.repeat(Math.max(0, w - s.length))
+
+          const top = makeSep('┌', '┬', '┐', '─')
+          const sep = makeSep('├', '┼', '┤', '─')
+          const bot = makeSep('└', '┴', '┘', '─')
+          const headerLine = '│' + selectedHeaders.map(h => ' ' + pad(titles[h], widths[h]) + ' ').join('│') + '│'
+          const lines = rows.map(r => '│' + selectedHeaders.map(h => ' ' + pad(String(r[h]), widths[h]) + ' ').join('│') + '│')
+
+          console.log(top)
+          console.log(headerLine)
+          console.log(sep)
+          for (const line of lines) console.log(line)
+          console.log(bot)
+        }
+
+      } catch (error) {
+        console.error(chalk.red('Error generating table:'), error instanceof Error ? error.message : String(error))
+        process.exit(1)
+      }
+    })
+
+  utils.addCommand(genTable)
+
   return utils
 }

package/src/lib/__tests__/network-loader.spec.ts

@@ -84,7 +84,7 @@ describe('network-loader rpcUrl token replacement', () => {
     expect(networks[0].rpcUrl).toBe('https://node.example.com/XYZ')
   })
 
-  test('throws error when RPC token has no matching env var', async () => {
+  test('defaults to empty string when RPC token has no matching env var', async () => {
     const projectRoot = path.join(tmpDir, 'case5')
     delete process.env.RPC_MISSING
     const yaml = `
@@ -94,6 +94,7 @@ describe('network-loader rpcUrl token replacement', () => {
 `
     await writeNetworksYaml(projectRoot, yaml)
 
-    await expect(loadNetworks(projectRoot)).rejects.toThrow('Environment variable RPC_MISSING is not set')
+    const networks = await loadNetworks(projectRoot)
+    expect(networks[0].rpcUrl).toBe('https://node.example.com/')
   })
 })

package/src/lib/__tests__/network-selection.spec.ts

@@ -0,0 +1,41 @@
+import { resolveSelectedChainIds, resolveSingleChainId } from '../../lib/network-selection'
+import { Network } from '../../lib/types'
+
+describe('network-selection', () => {
+  const networks: Network[] = [
+    { name: 'Mainnet', chainId: 1, rpcUrl: 'https://mainnet' },
+    { name: 'Arbitrum One', chainId: 42161, rpcUrl: 'https://arb' },
+    { name: 'Polygon', chainId: 137, rpcUrl: 'https://polygon' },
+    { name: 'Mainnet', chainId: 10_000, rpcUrl: 'https://fork' },
+  ]
+
+  it('returns undefined for empty/undefined input', () => {
+    expect(resolveSelectedChainIds(undefined, networks)).toBeUndefined()
+    expect(resolveSelectedChainIds('', networks)).toBeUndefined()
+    expect(resolveSelectedChainIds('   ', networks)).toBeUndefined()
+  })
+
+  it('parses numeric IDs and removes duplicates', () => {
+    expect(resolveSelectedChainIds('1,1,42161', networks)).toEqual([1, 42161])
+  })
+
+  it('matches names case-insensitively and includes all with same name', () => {
+    expect(resolveSelectedChainIds('mainnet', networks)).toEqual([1, 10000])
+    expect(resolveSelectedChainIds('MAINNET,polygon', networks)).toEqual([1, 10000, 137])
+  })
+
+  it('preserves token order and then network order for name matches', () => {
+    expect(resolveSelectedChainIds('polygon,mainnet', networks)).toEqual([137, 1, 10000])
+  })
+
+  it('throws on unknown name', () => {
+    expect(() => resolveSelectedChainIds('unknown', networks)).toThrow(/Unknown network selector/)
+  })
+
+  it('resolveSingleChainId returns first match for name and first token for multi', () => {
+    expect(resolveSingleChainId('mainnet', networks)).toBe(1)
+    expect(resolveSingleChainId('137,1', networks)).toBe(137)
+  })
+})
+
+

package/src/lib/deployer.ts

@@ -158,6 +158,8 @@ export class Deployer {
       
       // Track if any jobs have failed
       let hasFailures = false
+      // Emit signer info once per network (chainId)
+      const signerInfoPrintedForChain = new Set<number>()
       
       for (const network of targetNetworks) {
         this.events.emitEvent({
@@ -168,7 +170,6 @@ export class Deployer {
             chainId: network.chainId
           }
         })
-        
         for (const jobName of jobsToRun) {
           const job = this.loader.jobs.get(jobName)!
           
@@ -204,6 +205,46 @@ export class Deployer {
               (context as unknown as { setJobConstants: (constants: unknown) => void }).setJobConstants(job.constants)
             }
             
+            // Emit signer info once per network using the first job's context
+            if (!signerInfoPrintedForChain.has(network.chainId)) {
+              try {
+                const getSignerFn = (context as unknown as {
+                  getResolvedSigner?: () => Promise<{ getAddress: () => Promise<string> }>
+                  signer?: { getAddress: () => Promise<string> }
+                }).getResolvedSigner
+                const signer = getSignerFn
+                  ? await getSignerFn.call(context)
+                  : (context as unknown as { signer?: { getAddress: () => Promise<string> } }).signer
+                if (signer && typeof signer.getAddress === 'function') {
+                  const address = await signer.getAddress()
+                  // provider may not exist on mocked contexts; guard for it
+                  const provider = (context as unknown as {
+                    provider?: { getBalance: (addr: string) => Promise<bigint | number | { toString: () => string }> }
+                  }).provider
+                  if (provider && typeof provider.getBalance === 'function') {
+                    const balanceBn = await provider.getBalance(address)
+                    const balanceWei = balanceBn.toString()
+                    const balanceEth = (Number(balanceBn) / 1e18).toString()
+                    this.events.emitEvent({
+                      type: 'network_signer_info',
+                      level: 'info',
+                      data: {
+                        networkName: network.name,
+                        chainId: network.chainId,
+                        address,
+                        balanceWei,
+                        balance: balanceEth
+                      }
+                    })
+                  }
+                }
+              } catch {
+                // ignore non-fatal signer info errors
+              } finally {
+                signerInfoPrintedForChain.add(network.chainId)
+              }
+            }
+
             // Populate context with outputs from previously executed dependent jobs
             this.populateContextWithDependentJobOutputs(job, context, network)
             
@@ -275,12 +316,32 @@ export class Deployer {
       // Check if any jobs failed and exit with error if so
       if (hasFailures) {
         const error = new Error('One or more jobs failed during execution')
+
+        // Build a flat list of failed jobs with network context and error messages
+        const failedJobs: Array<{ jobName: string; networkName: string; chainId: number; error: string }> = []
+        for (const [, result] of this.results) {
+          const job = result.job
+          for (const [chainId, netResult] of result.outputs) {
+            if (netResult.status === 'error') {
+              // Resolve network name from configured networks (fallback to chainId if missing)
+              const network = this.options.networks.find(n => n.chainId === chainId)
+              failedJobs.push({
+                jobName: job.name,
+                networkName: network?.name || `chain-${chainId}`,
+                chainId,
+                error: String(netResult.data)
+              })
+            }
+          }
+        }
+
         this.events.emitEvent({
           type: 'deployment_failed',
           level: 'error',
           data: {
             error: error.message,
-            stack: error.stack
+            stack: error.stack,
+            failedJobs
           }
         })
         throw error

package/src/lib/events/cli-adapter.ts

@@ -48,7 +48,7 @@ export class CLIEventAdapter {
     const level0Events = new Set([
       'deployment_started', 'deployment_completed', 'deployment_failed',
       'job_started', 'job_completed', 'job_skipped', 'job_execution_failed',
-      'network_started',
+      'network_started', 'network_signer_info',
       'duplicate_artifact_warning', 'missing_network_config_warning',
       'unhandled_rejection', 'uncaught_exception', 'cli_error',
       'verification_failed'
@@ -115,6 +115,11 @@ export class CLIEventAdapter {
         console.log(chalk.cyan.bold(`\nNetwork: ${event.data.networkName} (ChainID: ${event.data.chainId})`))
         break
 
+      case 'network_signer_info':
+        console.log(chalk.gray(`        Sender: ${event.data.address}`))
+        console.log(chalk.gray(`        Balance: ${event.data.balance} ETH (${event.data.balanceWei} wei)`))
+        break
+
       case 'job_started':
         console.log(chalk.cyan.bold(`\n🚀 Starting job: ${event.data.jobName} (v${event.data.jobVersion})`))
         break
@@ -197,10 +202,21 @@ export class CLIEventAdapter {
 
       case 'deployment_failed':
         console.error(chalk.red.bold('\n💥 DEPLOYMENT FAILED!'))
-        if (event.data.stack) {
-          console.error(chalk.red(event.data.stack))
-        } else {
-          console.error(chalk.red(event.data.error))
+        // Show concise failed jobs table if present
+        const failedJobs = (event as any).data?.failedJobs as Array<{ jobName: string; networkName: string; chainId: number; error: string }> | undefined
+        if (Array.isArray(failedJobs) && failedJobs.length > 0) {
+          console.error(chalk.red('   ✗ Failed jobs:'))
+          for (const f of failedJobs) {
+            const where = `${f.networkName} (ChainID: ${f.chainId})`
+            console.error(chalk.red(`     - ${f.jobName} on ${where}`))
+            console.error(chalk.red(`       Error: ${f.error}`))
+          }
+        }
+        // Always print the top-level error and stack last
+        if ((event as any).data?.stack) {
+          console.error(chalk.red((event as any).data.stack))
+        } else if ((event as any).data?.error) {
+          console.error(chalk.red((event as any).data.error))
         }
         break
 

package/src/lib/events/types.ts

@@ -29,6 +29,12 @@ export interface DeploymentFailedEvent extends BaseEvent {
   data: {
     error: string
     stack?: string
+    failedJobs?: Array<{
+      jobName: string
+      networkName: string
+      chainId: number
+      error: string
+    }>
   }
 }
 
@@ -312,6 +318,22 @@ export interface NetworkStartedEvent extends BaseEvent {
   }
 }
 
+/**
+ * Emitted right after a network run starts to inform which address will be used
+ * to send transactions and its current balance.
+ */
+export interface NetworkSignerInfoEvent extends BaseEvent {
+  type: 'network_signer_info'
+  level: 'info'
+  data: {
+    networkName: string
+    chainId: number
+    address: string
+    balanceWei: string
+    balance: string // formatted in ETH
+  }
+}
+
 // Process error events
 export interface UnhandledRejectionEvent extends BaseEvent {
   type: 'unhandled_rejection'
@@ -457,6 +479,7 @@ export type DeploymentEvent =
   | ContextDisposalWarningEvent
   | DeprecatedJobsSkippedEvent
   | NetworkStartedEvent
+  | NetworkSignerInfoEvent
   | UnhandledRejectionEvent
   | UncaughtExceptionEvent
   | CLIErrorEvent

package/src/lib/network-loader.ts

@@ -37,7 +37,8 @@ function resolveRpcUrlTokens(rpcUrl: string): string {
     }
     const value = process.env[varName]
     if (typeof value === 'undefined') {
-      throw new Error(`Environment variable ${varName} is not set but is required for rpcUrl token replacement`)
+      // Default to empty string if missing
+      return ''
     }
     return value
   })