@0xsequence/catapult 1.1.0

package/src/commands/dry.ts

@@ -0,0 +1,208 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { loadProject } from './common'
+import { loadNetworks } from '../lib/network-loader'
+import { DependencyGraph } from '../lib/core/graph'
+import { projectOption, noStdOption, verbosityOption } from './common'
+import { validateContractReferences, extractUsedContractReferences } from '../lib/validation/contract-references'
+import { setVerbosity } from '../index'
+import { Template } from '../lib/types'
+
+interface DryRunOptions {
+  project: string
+  std: boolean
+  network?: string[]
+  verbose: number
+}
+
+/**
+ * Extract only constant-like placeholders from a value, using template metadata when available.
+ * A placeholder is treated as a constant candidate if:
+ * - It is a bare identifier (no dot, no parentheses), AND
+ * - It is NOT declared as a template argument in the current template (when template context provided)
+ */
+function extractConstantRefs(value: unknown, refs: string[], templateCtx?: Template) {
+  if (typeof value === 'string') {
+    const m = value.match(/^{{(.*)}}$/)
+    if (m) {
+      const expr = m[1].trim()
+
+      // Skip outputs or function-like references
+      if (expr.includes('.') || expr.includes('(') || expr.includes(')')) return
+
+      // If we have a template context, and the expr matches a declared argument, it's NOT a constant
+      if (templateCtx?.arguments && Object.prototype.hasOwnProperty.call(templateCtx.arguments, expr)) {
+        return
+      }
+
+      // Otherwise, treat as a constant candidate
+      refs.push(expr)
+    }
+  } else if (Array.isArray(value)) {
+    for (const v of value) extractConstantRefs(v, refs, templateCtx)
+  } else if (value && typeof value === 'object') {
+    for (const v of Object.values(value)) extractConstantRefs(v, refs, templateCtx)
+  }
+}
+
+export function makeDryRunCommand(): Command {
+  const dryRun = new Command('dry-run')
+    .description('Validate project configuration and show execution plan without running transactions')
+    .argument('[jobs...]', 'Specific job names to validate (and their dependencies).')
+    .option('-n, --network <chainIds...>', 'One or more network chain IDs to simulate running on.')
+  
+  projectOption(dryRun)
+  noStdOption(dryRun)
+  verbosityOption(dryRun)
+  
+  dryRun.action(async (jobs: string[], options: DryRunOptions) => {
+    try {
+      // Set verbosity level for logging
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+      
+      console.log(chalk.bold.inverse(' DRY-RUN MODE '))
+      const projectRoot = options.project
+      const loader = await loadProject(projectRoot, {
+        loadStdTemplates: options.std !== false
+      })
+      const allNetworks = await loadNetworks(projectRoot)
+
+      console.log(chalk.blue('\nBuilding dependency graph...'))
+      const graph = new DependencyGraph(loader.jobs, loader.templates)
+      const fullOrder = graph.getExecutionOrder()
+      console.log(chalk.green('   - Dependency graph built successfully.'))
+      
+      console.log(chalk.blue('\nContract Repository:'))
+      console.log(chalk.green(`   - Found ${loader.contractRepository.getAll().length} unique contracts.`))
+      
+      // Check for ambiguous references that are actually being used
+      const usedRefs = await extractUsedContractReferences(loader)
+      const allAmbiguousRefs = loader.contractRepository.getAmbiguousReferences()
+      const usedRefNames = usedRefs.map(ref => ref.reference)
+      const usedAmbiguousRefs = allAmbiguousRefs.filter(ref => usedRefNames.includes(ref))
+      
+      if (usedAmbiguousRefs.length > 0) {
+        console.log(chalk.red('\n   - Found ambiguous contract references being used:'))
+        for (const ref of usedAmbiguousRefs) {
+          console.log(chalk.red(`     ✗ "${ref}" could refer to multiple contracts`))
+        }
+        throw new Error(`Found ${usedAmbiguousRefs.length} ambiguous contract reference(s) being used. Please use more specific references to resolve ambiguity.`)
+      }
+      console.log(chalk.green('   - All used contract references are unambiguous.'))
+      
+      // Validate that all Contract() references point to existing contracts
+      console.log(chalk.blue('\nValidating contract references...'))
+      const missingRefs = await validateContractReferences(loader)
+      if (missingRefs.length > 0) {
+        console.log(chalk.red('\n   - Found missing contract references:'))
+        for (const ref of missingRefs) {
+          console.log(chalk.red(`     ✗ ${ref.reference} in ${ref.location}`))
+        }
+        throw new Error(`Found ${missingRefs.length} missing contract reference(s). Please ensure all referenced contracts exist.`)
+      }
+      console.log(chalk.green('   - All contract references are valid.'))
+
+      // Validate constant references exist
+      console.log(chalk.blue('\nValidating constant references...'))
+      const topLevelConstants = loader.constants
+      const missingConstantRefs: Array<{ ref: string; location: string }> = []
+
+      // Check jobs (arguments and outputs within templates are resolved at runtime; here we just check expressions)
+      for (const [jobName, job] of loader.jobs.entries()) {
+        // Collect refs in job actions
+        for (let i = 0; i < job.actions.length; i++) {
+          const action = job.actions[i]
+          const refs: string[] = []
+          extractConstantRefs(action.arguments, refs)
+          const jobConstants = job.constants || {}
+          for (const r of refs) {
+            if (!(r in jobConstants) && !topLevelConstants.has(r)) {
+              missingConstantRefs.push({ ref: r, location: `job '${jobName}', action ${i + 1}${action.name ? ` '${action.name}'` : ''}` })
+            }
+          }
+        }
+      }
+
+      // Check templates (setup/actions/outputs)
+      for (const [templateName, template] of loader.templates.entries()) {
+        // actions
+        for (let i = 0; i < template.actions.length; i++) {
+          const action = template.actions[i]
+          const refs: string[] = []
+          extractConstantRefs(action.arguments, refs, template)
+          for (const r of refs) {
+            if (!topLevelConstants.has(r)) {
+              missingConstantRefs.push({ ref: r, location: `template '${templateName}', action ${i + 1}${action.name ? ` '${action.name}'` : ''}` })
+            }
+          }
+        }
+        // setup actions
+        if (template.setup?.actions) {
+          for (let i = 0; i < (template.setup.actions?.length || 0); i++) {
+            const action = template.setup.actions![i]
+            const refs: string[] = []
+            extractConstantRefs(action.arguments, refs, template)
+            for (const r of refs) {
+              if (!topLevelConstants.has(r)) {
+                missingConstantRefs.push({ ref: r, location: `template '${templateName}' setup, action ${i + 1}${action.name ? ` '${action.name}'` : ''}` })
+              }
+            }
+          }
+        }
+        // outputs
+        if (template.outputs) {
+          const refs: string[] = []
+          extractConstantRefs(template.outputs, refs, template)
+          for (const r of refs) {
+            if (!topLevelConstants.has(r)) {
+              missingConstantRefs.push({ ref: r, location: `template '${templateName}' outputs` })
+            }
+          }
+        }
+      }
+
+      if (missingConstantRefs.length > 0) {
+        console.log(chalk.red('\n   - Found missing constant references:'))
+        for (const m of missingConstantRefs) {
+          console.log(chalk.red(`     ✗ ${m.ref} in ${m.location}`))
+        }
+        throw new Error(`Found ${missingConstantRefs.length} missing constant reference(s). Ensure they are defined at top-level or in the job's constants.`)
+      }
+      console.log(chalk.green('   - All constant references are valid.'))
+      
+      const runJobs = jobs.length > 0 ? jobs : undefined
+      const runOnNetworks = options.network?.map(Number)
+
+      const jobsToRun = new Set<string>()
+      if (runJobs) {
+        for (const jobName of runJobs) {
+          if (!loader.jobs.has(jobName)) {
+            throw new Error(`Specified job "${jobName}" not found in project.`)
+          }
+          jobsToRun.add(jobName)
+          graph.getDependencies(jobName).forEach(dep => jobsToRun.add(dep))
+        }
+      } else {
+        fullOrder.forEach(j => jobsToRun.add(j))
+      }
+
+      const jobExecutionPlan = fullOrder.filter(jobName => jobsToRun.has(jobName))
+      const targetNetworks = runOnNetworks
+        ? allNetworks.filter(n => runOnNetworks.includes(n.chainId))
+        : allNetworks
+
+      console.log(chalk.blue('\nExecution Plan:'))
+      console.log(chalk.gray(`   - Target Networks: ${targetNetworks.map(n => `${n.name} (ChainID: ${n.chainId})`).join(', ')}`))
+      console.log(chalk.gray(`   - Job Execution Order: ${jobExecutionPlan.join(' -> ')}`))
+      
+      console.log(chalk.green.bold('\n✅ Dry run successful. All job and template definitions appear to be valid.'))
+      
+    } catch (error) {
+      console.error(chalk.red.bold('\n💥 DRY RUN FAILED!'))
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)))
+      process.exit(1)
+    }
+  })
+
+  return dryRun
+}

package/src/commands/etherscan.ts

@@ -0,0 +1,360 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { loadNetworks } from '../lib/network-loader'
+import { projectOption, verbosityOption } from './common'
+import { setVerbosity } from '../index'
+import * as solc from 'solc'
+import { createHash } from 'crypto'
+
+type ApiAction = 'getsourcecode' | 'getabi'
+
+interface EtherscanCmdBase {
+  project: string
+  verbose: number
+  etherscanApiKey?: string
+  network?: string
+  address: string
+  raw?: boolean
+}
+
+function getEtherscanApiUrl(chainId: number): string {
+  return `https://api.etherscan.io/v2/api?chainid=${chainId}`
+}
+
+type EtherscanSourceEnvelope = {
+  rawResult: Record<string, any>
+  parsedSource: unknown // standard-json object or flattened string
+}
+
+async function fetchFromEtherscan(
+  chainId: number,
+  apiKey: string,
+  address: string,
+  action: ApiAction
+): Promise<unknown | EtherscanSourceEnvelope> {
+  const apiUrl = getEtherscanApiUrl(chainId)
+  const params = new URLSearchParams({
+    module: 'contract',
+    action,
+    apikey: apiKey,
+    address
+  })
+  const resp = await fetch(`${apiUrl}&${params.toString()}`, {
+    method: 'GET',
+    signal: AbortSignal.timeout(20000)
+  })
+  if (!resp.ok) {
+    throw new Error(`HTTP ${resp.status}: ${resp.statusText}`)
+  }
+  const data = await resp.json() as {
+    status: string
+    message?: string
+    result:
+      | string
+      | Array<{
+          SourceCode?: string
+          ABI?: string
+          [key: string]: unknown
+        }>
+  }
+
+  if (data.status !== '1') {
+    // Etherscan v2 returns status "0" with message in result
+    const msg = typeof data.result === 'string' ? data.result : JSON.stringify(data.result)
+    throw new Error(msg || 'Unknown Etherscan error')
+  }
+
+  if (action === 'getabi') {
+    // data.result is a JSON-encoded string for ABI, parse and return as object
+    if (typeof data.result !== 'string') {
+      throw new Error('Unexpected ABI result format from Etherscan')
+    }
+    try {
+      return JSON.parse(data.result as string)
+    } catch (_e) {
+      throw new Error('Failed to parse ABI JSON returned by Etherscan')
+    }
+  }
+
+  if (action === 'getsourcecode') {
+    // data.result[0].SourceCode is a string; when standard-json it is wrapped with a leading and trailing character
+    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 sourceCodeRaw = first?.SourceCode as string
+    if (typeof sourceCodeRaw !== 'string' || sourceCodeRaw.length === 0) {
+      throw new Error('No SourceCode found on Etherscan')
+    }
+
+    // The SourceCode may be:
+    // 1) a raw source (flattened) string
+    // 2) a JSON string that may be double-wrapped like: "{...}" or "{{...}}"
+    // Try to normalize to a parsed JSON object when possible, otherwise return the raw string.
+    const trimmed = sourceCodeRaw.trim()
+    // Heuristic: if it starts with '{{' and ends with '}}', strip one layer
+    const cleaned = trimmed.startsWith('{{') && trimmed.endsWith('}}')
+      ? trimmed.slice(1, -1)
+      : trimmed
+
+    // Try to parse JSON; if it fails, return string
+    try {
+      const parsed = JSON.parse(cleaned)
+      return { rawResult: first, parsedSource: parsed }
+    } catch {
+      // Not JSON, return as-is string
+      return { rawResult: first, parsedSource: sourceCodeRaw }
+    }
+  }
+
+  return data.result
+}
+
+export function makeEtherscanCommand(): Command {
+  const etherscan = new Command('etherscan')
+    .description('Etherscan helper commands (ABI/source fetch)')
+
+  // Common options builder
+  const withCommon = (cmd: Command) => {
+    projectOption(cmd)
+    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('-a, --address <address>', 'Contract address to query', '')
+      .option('--raw', 'Print raw response (no pretty JSON). Useful for piping.', false)
+    return cmd
+  }
+
+  // etherscan abi
+  const abi = new Command('abi')
+    .description('Fetch contract ABI from Etherscan and print to stdout')
+  withCommon(abi)
+  abi.action(async (options: EtherscanCmdBase) => {
+    try {
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+
+      const apiKey = options.etherscanApiKey || process.env.ETHERSCAN_API_KEY
+      if (!apiKey) {
+        console.error(chalk.red('Etherscan API key is required. Use --etherscan-api-key or set ETHERSCAN_API_KEY.'))
+        process.exit(1)
+      }
+
+      if (!options.address) {
+        console.error(chalk.red('Missing required --address option'))
+        process.exit(1)
+      }
+
+      // Determine chainId
+      let chainId: number | undefined
+      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)
+        }
+      }
+
+      const result = await fetchFromEtherscan(chainId!, apiKey, options.address, 'getabi')
+
+      if (options.raw) {
+        // raw: output minified JSON
+        process.stdout.write(JSON.stringify(result))
+      } else {
+        // pretty
+        console.log(JSON.stringify(result, null, 2))
+      }
+    } catch (error) {
+      console.error(chalk.red('Error fetching ABI from Etherscan:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  // etherscan source
+  const source = new Command('source')
+    .description('Fetch contract source and emit a self-contained build-info JSON suitable for verification')
+  withCommon(source)
+  source.action(async (options: EtherscanCmdBase) => {
+    try {
+      setVerbosity(options.verbose as 0 | 1 | 2 | 3)
+
+      const apiKey = options.etherscanApiKey || process.env.ETHERSCAN_API_KEY
+      if (!apiKey) {
+        console.error(chalk.red('Etherscan API key is required. Use --etherscan-api-key or set ETHERSCAN_API_KEY.'))
+        process.exit(1)
+      }
+
+      if (!options.address) {
+        console.error(chalk.red('Missing required --address option'))
+        process.exit(1)
+      }
+
+      // Determine chainId
+      let chainId: number | undefined
+      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)
+        }
+      }
+
+      const result = await fetchFromEtherscan(chainId!, apiKey, options.address, 'getsourcecode') as EtherscanSourceEnvelope
+
+      const raw = result.rawResult
+      const parsed = result.parsedSource
+
+      // Extract compiler version with commit from metadata when available
+      const compilerVersion = (raw?.CompilerVersion as string | undefined) || ''
+      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
+
+      // If we have a standard JSON input, use it; otherwise build one from flattened source
+      let input: any
+      if (isStandardJson) {
+        input = { ...(parsed as any) }
+        // Ensure outputSelection includes required entries to get creation bytecode and metadata
+        const currentSel = input.settings?.outputSelection || {}
+        const mergedSel = {
+          '*': {
+            '*': Array.from(new Set([
+              ...(currentSel?.['*']?.['*'] || []),
+              'abi',
+              'evm.bytecode',
+              'evm.deployedBytecode',
+              'metadata',
+              'userdoc',
+              'devdoc',
+              'evm.methodIdentifiers'
+            ]))
+          }
+        }
+        input.settings = {
+          ...(input.settings || {}),
+          outputSelection: mergedSel
+        }
+      } else {
+        // Build a minimal standard JSON input from flattened source
+        const flattened = String(parsed || '')
+        input = {
+          language: 'Solidity',
+          sources: {
+            'Flattened.sol': { content: flattened }
+          },
+          settings: {
+            optimizer: {
+              enabled: optimizationUsed === '1',
+              runs: Number.isFinite(Number(runsStr)) ? Number(runsStr) : 200
+            },
+            evmVersion: evmVersionRaw && evmVersionRaw !== 'default' ? evmVersionRaw : undefined,
+            outputSelection: {
+              '*': {
+                '*': [
+                  'abi',
+                  'evm.bytecode.object',
+                  'evm.bytecode.sourceMap',
+                  'evm.bytecode.linkReferences',
+                  'evm.deployedBytecode.object',
+                  'evm.deployedBytecode.sourceMap',
+                  'evm.deployedBytecode.linkReferences',
+                  'evm.deployedBytecode.immutableReferences',
+                  'evm.methodIdentifiers',
+                  'metadata'
+                ]
+              }
+            }
+          }
+        }
+      }
+
+      // Compile with exact solc version when possible
+      const solcInput = JSON.stringify(input)
+      const versionTag = compilerVersion && compilerVersion.startsWith('v') ? compilerVersion : (compilerVersion ? `v${compilerVersion}` : '')
+      let outputRaw: string
+      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'))
+            try {
+              resolve(specificSolc.compile(solcInput))
+            } catch (e) {
+              reject(e)
+            }
+          })
+        })
+      } else {
+        outputRaw = solc.compile(solcInput)
+      }
+      const output = JSON.parse(outputRaw)
+
+      // Build build-info id as hex of sha1 of input
+      const id = createHash('sha1').update(solcInput).digest('hex')
+
+      // 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')
+
+      // Augment settings with defaults similar to reference format
+      const basePath = process.cwd()
+      const includePaths = [basePath]
+      const allowPaths = includePaths
+
+      const buildInfo = {
+        id,
+        source_id_to_path: Object.fromEntries(Object.keys(input.sources).map((p, i) => [String(i), p])),
+        language: input.language,
+        _format: 'ethers-rs-sol-build-info-1',
+        input: {
+          version: solcVersion,
+          language: input.language,
+          sources: input.sources,
+          settings: input.settings,
+          evmVersion: input.settings?.evmVersion || 'cancun',
+          viaIR: input.settings?.viaIR || false,
+          libraries: input.settings?.libraries || {}
+        },
+        allowPaths,
+        basePath,
+        includePaths,
+        output: {
+          contracts: output.contracts || {},
+          sources: output.sources || {}
+        },
+        solcLongVersion: solcLongVersion || solcVersion,
+        solcVersion: solcVersion
+      }
+
+      // Print build-info JSON
+      console.log(options.raw ? JSON.stringify(buildInfo) : JSON.stringify(buildInfo, null, 2))
+    } catch (error) {
+      console.error(chalk.red('Error fetching source from Etherscan:'), error instanceof Error ? error.message : String(error))
+      process.exit(1)
+    }
+  })
+
+  etherscan.addCommand(abi)
+  etherscan.addCommand(source)
+  return etherscan
+}

package/src/commands/index.ts

@@ -0,0 +1,5 @@
+export * from './run'
+export * from './dry'
+export * from './list'
+export * from './utils'
+export * from './etherscan'