@0xsequence/catapult 1.1.0

package/src/lib/events/emitter.ts

@@ -0,0 +1,62 @@
+import { EventEmitter } from 'events'
+import { DeploymentEvent } from './types'
+
+/**
+ * Type-safe event emitter for deployment events.
+ * Extends Node.js EventEmitter with typed event methods.
+ */
+export class DeploymentEventEmitter extends EventEmitter {
+  /**
+   * Emits a deployment event with automatic timestamp injection.
+   */
+  public emitEvent(event: any): void {
+    const fullEvent = {
+      ...event,
+      timestamp: new Date()
+    }
+
+    // Emit on both the specific event type and a general 'event' channel
+    this.emit(event.type, fullEvent)
+    this.emit('event', fullEvent)
+  }
+
+  /**
+   * Type-safe event listener registration.
+   */
+  public onEvent<T extends DeploymentEvent>(
+    eventType: T['type'],
+    listener: (event: T) => void
+  ): this {
+    return this.on(eventType, listener)
+  }
+
+  /**
+   * Listen to all events.
+   */
+  public onAnyEvent(listener: (event: DeploymentEvent) => void): this {
+    return this.on('event', listener)
+  }
+
+  /**
+   * One-time event listener.
+   */
+  public onceEvent<T extends DeploymentEvent>(
+    eventType: T['type'],
+    listener: (event: T) => void
+  ): this {
+    return this.once(eventType, listener)
+  }
+
+  /**
+   * Remove event listener.
+   */
+  public offEvent<T extends DeploymentEvent>(
+    eventType: T['type'],
+    listener: (event: T) => void
+  ): this {
+    return this.off(eventType, listener)
+  }
+}
+
+// Singleton instance for global access
+export const deploymentEvents = new DeploymentEventEmitter() 

package/src/lib/events/index.ts

@@ -0,0 +1,3 @@
+export * from './types'
+export * from './emitter'
+export * from './cli-adapter' 

package/src/lib/events/types.ts

@@ -0,0 +1,469 @@
+/**
+ * Event system for structured logging throughout the deployment process.
+ * Replaces direct console.log calls with rich, structured events.
+ */
+
+export interface BaseEvent {
+  type: string
+  timestamp: Date
+  level: 'info' | 'warn' | 'error' | 'debug'
+}
+
+// Deployment lifecycle events
+export interface DeploymentStartedEvent extends BaseEvent {
+  type: 'deployment_started'
+  level: 'info'
+  data: {
+    projectRoot: string
+  }
+}
+
+export interface DeploymentCompletedEvent extends BaseEvent {
+  type: 'deployment_completed'
+  level: 'info'
+}
+
+export interface DeploymentFailedEvent extends BaseEvent {
+  type: 'deployment_failed'
+  level: 'error'
+  data: {
+    error: string
+    stack?: string
+  }
+}
+
+// Project loading events
+export interface ProjectLoadingStartedEvent extends BaseEvent {
+  type: 'project_loading_started'
+  level: 'info'
+  data: {
+    projectRoot: string
+  }
+}
+
+export interface ProjectLoadedEvent extends BaseEvent {
+  type: 'project_loaded'
+  level: 'info'
+  data: {
+    jobCount: number
+    templateCount: number
+  }
+}
+
+// Execution plan events
+export interface ExecutionPlanEvent extends BaseEvent {
+  type: 'execution_plan'
+  level: 'info'
+  data: {
+    targetNetworks: Array<{
+      name: string
+      chainId: number
+    }>
+    jobExecutionOrder: string[]
+  }
+}
+
+// Job execution events
+export interface JobStartedEvent extends BaseEvent {
+  type: 'job_started'
+  level: 'info'
+  data: {
+    jobName: string
+    jobVersion: string
+    networkName: string
+    chainId: number
+  }
+}
+
+export interface JobCompletedEvent extends BaseEvent {
+  type: 'job_completed'
+  level: 'info'
+  data: {
+    jobName: string
+    networkName: string
+    chainId: number
+  }
+}
+
+export interface JobSkippedEvent extends BaseEvent {
+  type: 'job_skipped'
+  level: 'warn'
+  data: {
+    jobName: string
+    networkName: string
+    reason: string
+  }
+}
+
+// Action execution events
+export interface ActionStartedEvent extends BaseEvent {
+  type: 'action_started'
+  level: 'info'
+  data: {
+    actionName: string
+    jobName: string
+  }
+}
+
+export interface ActionSkippedEvent extends BaseEvent {
+  type: 'action_skipped'
+  level: 'info'
+  data: {
+    actionName: string
+    reason: string
+  }
+}
+
+export interface ActionCompletedEvent extends BaseEvent {
+  type: 'action_completed'
+  level: 'info'
+  data: {
+    actionName: string
+    result: string
+  }
+}
+
+export interface ActionFailedEvent extends BaseEvent {
+  type: 'action_failed'
+  level: 'error'
+  data: {
+    message: string
+  }
+}
+
+export interface ActionInfoEvent extends BaseEvent {
+  type: 'action_info'
+  level: 'debug'
+  data: {
+    message: string
+  }
+}
+
+export interface DebugInfoEvent extends BaseEvent {
+  type: 'debug_info'
+  level: 'debug'
+  data: {
+    message: string
+  }
+}
+
+// Template execution events
+export interface TemplateEnteredEvent extends BaseEvent {
+  type: 'template_entered'
+  level: 'debug'
+  data: {
+    templateName: string
+  }
+}
+
+export interface TemplateExitedEvent extends BaseEvent {
+  type: 'template_exited'
+  level: 'debug'
+  data: {
+    templateName: string
+  }
+}
+
+export interface TemplateSetupStartedEvent extends BaseEvent {
+  type: 'template_setup_started'
+  level: 'debug'
+  data: {
+    templateName: string
+  }
+}
+
+export interface TemplateSetupCompletedEvent extends BaseEvent {
+  type: 'template_setup_completed'
+  level: 'debug'
+  data: {
+    templateName: string
+  }
+}
+
+export interface TemplateSetupSkippedEvent extends BaseEvent {
+  type: 'template_setup_skipped'
+  level: 'info'
+  data: {
+    templateName: string
+    reason: string
+  }
+}
+
+export interface TemplateSkippedEvent extends BaseEvent {
+  type: 'template_skipped'
+  level: 'info'
+  data: {
+    templateName: string
+    reason: string
+  }
+}
+
+// Transaction events
+export interface PrimitiveActionEvent extends BaseEvent {
+  type: 'primitive_action'
+  level: 'debug'
+  data: {
+    actionType: string
+  }
+}
+
+export interface TransactionSentEvent extends BaseEvent {
+  type: 'transaction_sent'
+  level: 'info'
+  data: {
+    to: string
+    value: string
+    dataPreview: string
+    txHash: string
+  }
+}
+
+export interface TransactionConfirmedEvent extends BaseEvent {
+  type: 'transaction_confirmed'
+  level: 'info'
+  data: {
+    txHash: string
+    blockNumber: number
+  }
+}
+
+// Contract lifecycle events
+export interface ContractCreatedEvent extends BaseEvent {
+  type: 'contract_created'
+  level: 'info'
+  data: {
+    contractAddress: string
+    txHash: string
+    blockNumber: number
+  }
+}
+
+// Output events
+export interface OutputStoredEvent extends BaseEvent {
+  type: 'output_stored'
+  level: 'debug'
+  data: {
+    outputKey: string
+    value: any
+  }
+}
+
+export interface OutputFileWrittenEvent extends BaseEvent {
+  type: 'output_file_written'
+  level: 'info'
+  data: {
+    relativePath: string
+  }
+}
+
+export interface NoOutputsEvent extends BaseEvent {
+  type: 'no_outputs'
+  level: 'warn'
+}
+
+export interface OutputWritingStartedEvent extends BaseEvent {
+  type: 'output_writing_started'
+  level: 'info'
+}
+
+// Warning events
+export interface DuplicateArtifactWarningEvent extends BaseEvent {
+  type: 'duplicate_artifact_warning'
+  level: 'warn'
+  data: {
+    contractName: string
+    path: string
+  }
+}
+
+export interface MissingNetworkConfigWarningEvent extends BaseEvent {
+  type: 'missing_network_config_warning'
+  level: 'warn'
+  data: {
+    missingChainIds: number[]
+  }
+}
+
+export interface ContextDisposalWarningEvent extends BaseEvent {
+  type: 'context_disposal_warning'
+  level: 'warn'
+  data: {
+    jobName: string
+    networkName: string
+    error: string
+  }
+}
+
+export interface DeprecatedJobsSkippedEvent extends BaseEvent {
+  type: 'deprecated_jobs_skipped'
+  level: 'warn'
+  data: {
+    jobs: string[] | { name: string }[]
+  }
+}
+
+// Network events
+export interface NetworkStartedEvent extends BaseEvent {
+  type: 'network_started'
+  level: 'info'
+  data: {
+    networkName: string
+    chainId: number
+  }
+}
+
+// Process error events
+export interface UnhandledRejectionEvent extends BaseEvent {
+  type: 'unhandled_rejection'
+  level: 'error'
+  data: {
+    error: string
+    origin: string
+  }
+}
+
+export interface UncaughtExceptionEvent extends BaseEvent {
+  type: 'uncaught_exception'
+  level: 'error'
+  data: {
+    error: Error
+  }
+}
+
+export interface CLIErrorEvent extends BaseEvent {
+  type: 'cli_error'
+  level: 'error'
+  data: {
+    message: string
+  }
+}
+
+export interface JobExecutionFailedEvent extends BaseEvent {
+  type: 'job_execution_failed'
+  level: 'error'
+  data: {
+    jobName: string
+    networkName: string
+    chainId: number
+    error: string
+  }
+}
+
+export interface VerificationStartedEvent extends BaseEvent {
+  type: 'verification_started'
+  level: 'info'
+  data: {
+    actionName: string
+    address: string
+    contractName: string
+    platform: string
+    networkName: string
+  }
+}
+
+export interface VerificationSubmittedEvent extends BaseEvent {
+  type: 'verification_submitted'
+  level: 'info'
+  data: {
+    actionName: string
+    platform: string
+    guid: string
+    message: string
+  }
+}
+
+export interface VerificationCompletedEvent extends BaseEvent {
+  type: 'verification_completed'
+  level: 'info'
+  data: {
+    actionName: string
+    address: string
+    contractName: string
+    platform: string
+    message: string
+  }
+}
+
+export interface VerificationFailedEvent extends BaseEvent {
+  type: 'verification_failed'
+  level: 'error'
+  data: {
+    actionName: string
+    address: string
+    contractName: string
+    platform: string
+    error: string
+  }
+}
+
+export interface VerificationRetryEvent extends BaseEvent {
+  type: 'verification_retry'
+  level: 'info'
+  data: {
+    platform: string
+    attempt: number
+    maxRetries: number
+    error: string
+  }
+}
+
+// End-of-run summary
+export interface RunSummaryEvent extends BaseEvent {
+  type: 'run_summary'
+  level: 'info' | 'warn'
+  data: {
+    networkCount: number
+    jobCount: number
+    successCount: number
+    failedCount: number
+    skippedCount: number
+    keyContracts: Array<{ job: string; action: string; address: string }>
+  }
+}
+
+// Union type of all events
+export type DeploymentEvent =
+  | DeploymentStartedEvent
+  | DeploymentCompletedEvent
+  | DeploymentFailedEvent
+  | ProjectLoadingStartedEvent
+  | ProjectLoadedEvent
+  | ExecutionPlanEvent
+  | JobStartedEvent
+  | JobCompletedEvent
+  | JobSkippedEvent
+  | ActionStartedEvent
+  | ActionSkippedEvent
+  | ActionCompletedEvent
+  | ActionFailedEvent
+  | ActionInfoEvent
+  | DebugInfoEvent
+  | TemplateEnteredEvent
+  | TemplateExitedEvent
+  | TemplateSetupStartedEvent
+  | TemplateSetupCompletedEvent
+  | TemplateSetupSkippedEvent
+  | TemplateSkippedEvent
+  | PrimitiveActionEvent
+  | TransactionSentEvent
+  | TransactionConfirmedEvent
+  | ContractCreatedEvent
+  | OutputStoredEvent
+  | OutputFileWrittenEvent
+  | NoOutputsEvent
+  | OutputWritingStartedEvent
+  | DuplicateArtifactWarningEvent
+  | MissingNetworkConfigWarningEvent
+  | ContextDisposalWarningEvent
+  | DeprecatedJobsSkippedEvent
+  | NetworkStartedEvent
+  | UnhandledRejectionEvent
+  | UncaughtExceptionEvent
+  | CLIErrorEvent
+  | JobExecutionFailedEvent
+  | VerificationStartedEvent
+  | VerificationSubmittedEvent
+  | VerificationCompletedEvent
+  | VerificationFailedEvent
+  | VerificationRetryEvent 
+  | RunSummaryEvent

package/src/lib/index.ts

@@ -0,0 +1,14 @@
+// Export all types
+export * from './types'
+
+// Export core classes
+export * from './contracts/repository'
+
+// Export all parsers
+export * as parsers from './parsers'
+
+// Export the deployer
+export * from './deployer'
+
+// This will be the main entry point for the lib
+// Additional functionality will be added here as the lib grows

package/src/lib/network-loader.ts

@@ -0,0 +1,59 @@
+import * as fs from 'fs/promises'
+import * as path from 'path'
+import { parse as parseYaml } from 'yaml'
+import { Network } from './types'
+
+function isValidNetwork(obj: unknown): obj is Network {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'name' in obj &&
+    'chainId' in obj &&
+    'rpcUrl' in obj &&
+    typeof (obj as Record<string, unknown>).name === 'string' &&
+    typeof (obj as Record<string, unknown>).chainId === 'number' &&
+    typeof (obj as Record<string, unknown>).rpcUrl === 'string' &&
+    // supports field is optional and should be an array of strings if present
+    (!('supports' in obj) ||
+     (Array.isArray((obj as Record<string, unknown>).supports) &&
+      ((obj as Record<string, unknown>).supports as unknown[]).every((item: unknown) => typeof item === 'string'))) &&
+    // gasLimit field is optional and should be a number if present
+    (!('gasLimit' in obj) || typeof (obj as Record<string, unknown>).gasLimit === 'number') &&
+    // testnet field is optional and should be a boolean if present
+    (!('testnet' in obj) || typeof (obj as Record<string, unknown>).testnet === 'boolean')
+  )
+}
+
+/**
+ * Loads and validates network configurations from a `networks.yaml` file in the project root.
+ * @param projectRoot The root directory of the project.
+ * @returns A promise that resolves to an array of Network objects.
+ * @throws An error if the file exists but is malformed or contains invalid network data.
+ */
+export async function loadNetworks(projectRoot: string): Promise<Network[]> {
+  const filePath = path.join(projectRoot, 'networks.yaml')
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    const parsed = parseYaml(content)
+
+    if (!Array.isArray(parsed)) {
+      throw new Error('networks.yaml must contain an array of network configurations.')
+    }
+
+    const networks: Network[] = []
+    for (const item of parsed) {
+      if (!isValidNetwork(item)) {
+        throw new Error(`Invalid network configuration found in networks.yaml: ${JSON.stringify(item)}`)
+      }
+      networks.push(item)
+    }
+    return networks
+  } catch (error: unknown) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      // It's okay if the file doesn't exist, just return an empty array.
+      return []
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Failed to load or parse networks.yaml: ${message}`)
+  }
+}

package/src/lib/network-utils.ts

@@ -0,0 +1,64 @@
+import { ethers } from 'ethers'
+import { Network } from './types'
+
+/**
+ * Attempts to detect network information from an RPC URL
+ * @param rpcUrl The RPC URL to query
+ * @returns Promise that resolves with detected network information
+ */
+export async function detectNetworkFromRpc(rpcUrl: string): Promise<Partial<Network>> {
+  // Detect network information from RPC URL
+  
+  try {
+    const provider = new ethers.JsonRpcProvider(rpcUrl)
+    
+    // Create provider and get network information
+    const network = await provider.getNetwork()
+    
+    // Network detected successfully
+    
+    return {
+      name: network.name,
+      chainId: Number(network.chainId),
+      rpcUrl: rpcUrl
+    }
+  } catch (error) {
+    // Failed to detect network
+    throw new Error(`Failed to detect network from RPC URL "${rpcUrl}": ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/**
+ * Validates if a string is a valid RPC URL
+ * @param url The URL to validate
+ * @returns True if the URL appears to be a valid RPC URL
+ */
+export function isValidRpcUrl(url: string): boolean {
+  try {
+    // Basic URL validation
+    const urlObj = new URL(url)
+    
+    // Check if it's http/https or a common RPC protocol
+    const isValidProtocol = urlObj.protocol === 'http:' || 
+                           urlObj.protocol === 'https:' ||
+                           url.startsWith('ws://') || 
+                           url.startsWith('wss://')
+    
+    if (!isValidProtocol) {
+      // Invalid protocol
+      return false
+    }
+    
+    // Check if it has a hostname
+    if (!urlObj.hostname) {
+      // Missing hostname
+      return false
+    }
+    
+    // Valid RPC URL format
+    return true
+  } catch {
+    // Invalid RPC URL format
+    return false
+  }
+}