@0xsequence/catapult 1.1.0

package/src/lib/types/project.ts

@@ -0,0 +1,9 @@
+import { Network } from './network'
+
+/**
+ * Represents a deployment project with its associated networks
+ */
+export interface Project {
+  /** List of networks available for this project */
+  networks: Network[]
+} 

package/src/lib/types/task.ts

@@ -0,0 +1,9 @@
+import { Action } from './actions'
+import { Condition } from './conditions'
+
+export interface Task {
+  name: string
+  description?: string
+  action: Action
+  checks: Condition[]
+} 

package/src/lib/types/values.ts

@@ -0,0 +1,116 @@
+/**
+ * Represents a reference to another value in the scope, e.g., "{{var.name}}".
+ * The parser will be responsible for resolving this string into a concrete value.
+ */
+export type Reference = string;
+
+// --- Value Resolver Types ---
+// These are declarative objects that describe how to compute a value at runtime.
+
+export interface AbiEncodeValue {
+  type: 'abi-encode';
+  arguments: {
+    signature: Value<string>;
+    values: Value<any>[];
+  };
+}
+
+export interface AbiPackValue {
+  type: 'abi-pack';
+  arguments: {
+    types: Value<string>[];
+    values: Value<any>[];
+  };
+}
+
+export interface ConstructorEncodeValue {
+  type: 'constructor-encode';
+  arguments: {
+    creationCode?: Value<string>;
+    types: Value<string>[];
+    values: Value<any>[];
+  };
+}
+
+export interface ComputeCreate2Value {
+  type: 'compute-create2';
+  arguments: {
+    deployerAddress: AddressValue;
+    salt: BytesValue;
+    initCode: BytesValue;
+  };
+}
+
+export interface ReadBalanceValue {
+  type: 'read-balance';
+  arguments: {
+    address: AddressValue;
+  };
+}
+
+export interface BasicArithmeticValue {
+  type: 'basic-arithmetic';
+  arguments: {
+    operation: 'add' | 'sub' | 'mul' | 'div' | 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte';
+    values: Value<any>[];
+  };
+}
+
+export interface CallValue {
+    type: 'call';
+    arguments: {
+        to?: AddressValue; // Optional, can be inferred from context by the parser
+        signature: Value<string>;
+        values: Value<any>[];
+    };
+}
+
+export interface ContractExistsValue {
+    type: 'contract-exists';
+    arguments: {
+        address: AddressValue;
+    };
+}
+
+export interface JobCompletedValue {
+    type: 'job-completed';
+    arguments: {
+        job: Value<string>;
+    };
+}
+
+export interface ReadJsonValue {
+    type: 'read-json';
+    arguments: {
+        json: Value<any>; // The JSON object to read from
+        path: Value<string>; // The path to the value (e.g., "txs.data" or "user.profile.name")
+    };
+}
+
+/**
+ * A union of all possible value-resolver objects.
+ */
+export type ValueResolver =
+  | AbiEncodeValue
+  | AbiPackValue
+  | ConstructorEncodeValue
+  | ComputeCreate2Value
+  | ReadBalanceValue
+  | BasicArithmeticValue
+  | CallValue
+  | ContractExistsValue
+  | JobCompletedValue
+  | ReadJsonValue;
+
+/**
+ * A generic value type that can be a primitive literal (string, number, boolean),
+ * a reference to another value, or a value-resolver object.
+ * This accurately models the flexibility of your YAML arguments.
+ */
+export type Value<T = string | number | boolean> = T | Reference | ValueResolver;
+
+// --- Specific Value Types for clarity and type-safety ---
+export type BytesValue = Value<string>;
+export type AddressValue = Value<string>;
+export type Uint256Value = Value<string | number>;
+export type BooleanValue = Value<boolean>;

package/src/lib/utils/validation.ts

@@ -0,0 +1,116 @@
+/**
+ * Validation utilities for type checking and conversion of resolved values.
+ * These functions provide runtime type safety for values resolved from YAML configurations.
+ */
+
+/**
+ * Validates and converts a value to a valid Ethereum address.
+ */
+export function validateAddress(value: unknown, actionName: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid 'to' address for action "${actionName}": expected string, got ${typeof value}`)
+  }
+  
+  // Basic Ethereum address validation (0x followed by 40 hex characters)
+  if (!/^0x[a-fA-F0-9]{40}$/.test(value)) {
+    throw new Error(`Invalid 'to' address format for action "${actionName}": ${value}`)
+  }
+  
+  return value
+}
+
+/**
+ * Validates and converts a value to hex data string.
+ */
+export function validateHexData(value: unknown, actionName: string, fieldName: string): string {
+  if (value === null || value === undefined) {
+    return '0x'
+  }
+  
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid '${fieldName}' for action "${actionName}": expected string, got ${typeof value}`)
+  }
+  
+  // Ensure it starts with 0x
+  if (!value.startsWith('0x')) {
+    throw new Error(`Invalid '${fieldName}' format for action "${actionName}": must start with '0x', got ${value}`)
+  }
+  
+  // Validate hex characters (allow empty data as '0x')
+  if (value.length > 2 && !/^0x[a-fA-F0-9]*$/.test(value)) {
+    throw new Error(`Invalid '${fieldName}' format for action "${actionName}": contains non-hex characters: ${value}`)
+  }
+  
+  return value
+}
+
+/**
+ * Validates and converts a value to a BigNumberish (number, string, or BigInt).
+ */
+export function validateBigNumberish(value: unknown, actionName: string, fieldName: string): string | number | bigint {
+  if (value === null || value === undefined) {
+    return 0
+  }
+  
+  // Handle different input types
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error(`Invalid '${fieldName}' for action "${actionName}": must be a non-negative integer, got ${value}`)
+    }
+    return value
+  }
+  
+  if (typeof value === 'string') {
+    // Handle hex strings
+    if (value.startsWith('0x')) {
+      if (!/^0x[a-fA-F0-9]+$/.test(value)) {
+        throw new Error(`Invalid '${fieldName}' hex format for action "${actionName}": ${value}`)
+      }
+      return value
+    }
+    
+    // Handle decimal strings
+    if (!/^\d+$/.test(value)) {
+      throw new Error(`Invalid '${fieldName}' format for action "${actionName}": must be a number or hex string, got ${value}`)
+    }
+    return value
+  }
+  
+  if (typeof value === 'bigint') {
+    if (value < 0n) {
+      throw new Error(`Invalid '${fieldName}' for action "${actionName}": must be non-negative, got ${value}`)
+    }
+    return value
+  }
+  
+  throw new Error(`Invalid '${fieldName}' type for action "${actionName}": expected number, string, or bigint, got ${typeof value}`)
+}
+
+/**
+ * Validates that a value is a valid raw transaction string.
+ */
+export function validateRawTransaction(value: unknown, actionName: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid raw transaction for action "${actionName}": expected string, got ${typeof value}`)
+  }
+
+  // Normalize: trim whitespace and allow with or without 0x prefix
+  const trimmed = value.trim()
+  const withoutPrefix = trimmed.startsWith('0x') ? trimmed.slice(2) : trimmed
+
+  if (withoutPrefix.length === 0) {
+    // Empty data is allowed as '0x'
+    return '0x'
+  }
+
+  // Validate hex characters only
+  if (!/^[a-fA-F0-9]+$/.test(withoutPrefix)) {
+    // Pinpoint first invalid character for easier debugging
+    const idx = withoutPrefix.search(/[^a-fA-F0-9]/)
+    const marker = idx >= 0 ? ` at index ${idx} ('${withoutPrefix[idx]}')` : ''
+    throw new Error(`Invalid raw transaction format for action "${actionName}": contains non-hex characters${marker}: ${value}`)
+  }
+
+  // Ensure canonical 0x-prefixed output
+  return '0x' + withoutPrefix
+}

package/src/lib/validation/contract-references.ts

@@ -0,0 +1,210 @@
+import { ProjectLoader } from '../core/loader'
+import { Action, Template, Job, JobAction, Value } from '../types'
+
+export interface MissingContractReference {
+  reference: string
+  location: string
+}
+
+export interface UsedContractReference {
+  reference: string
+  location: string
+}
+
+/**
+ * Extracts all Contract() references actually used in the project
+ */
+export async function extractUsedContractReferences(loader: ProjectLoader): Promise<UsedContractReference[]> {
+  const usedRefs: UsedContractReference[] = []
+  
+  // Extract from jobs
+  for (const [jobName, job] of loader.jobs.entries()) {
+    extractJobActionsContractReferences(job.actions, `job '${jobName}'`, job._path, usedRefs)
+  }
+  
+  // Extract from templates
+  for (const [templateName, template] of loader.templates.entries()) {
+    extractActionsContractReferences(template.actions, `template '${templateName}'`, template._path, usedRefs)
+    
+    // Extract from template setup actions if they exist
+    if (template.setup?.actions) {
+      extractActionsContractReferences(template.setup.actions, `template '${templateName}' setup`, template._path, usedRefs)
+    }
+    
+    // Extract from template outputs
+    if (template.outputs) {
+      extractValueContractReferences(template.outputs, `template '${templateName}' outputs`, template._path, usedRefs)
+    }
+  }
+  
+  return usedRefs
+}
+
+/**
+ * Validates that all Contract() references in the project point to existing contracts
+ */
+export async function validateContractReferences(loader: ProjectLoader): Promise<MissingContractReference[]> {
+  const missingRefs: MissingContractReference[] = []
+  
+  // Validate jobs
+  for (const [jobName, job] of loader.jobs.entries()) {
+    validateJobActionsForMissingContracts(job.actions, `job '${jobName}'`, job._path, loader, missingRefs)
+  }
+  
+  // Validate templates
+  for (const [templateName, template] of loader.templates.entries()) {
+    validateActionsForMissingContracts(template.actions, `template '${templateName}'`, template._path, loader, missingRefs)
+    
+    // Validate template setup actions if they exist
+    if (template.setup?.actions) {
+      validateActionsForMissingContracts(template.setup.actions, `template '${templateName}' setup`, template._path, loader, missingRefs)
+    }
+    
+    // Validate template outputs
+    if (template.outputs) {
+      validateValueForMissingContracts(template.outputs, `template '${templateName}' outputs`, template._path, loader, missingRefs)
+    }
+  }
+  
+  return missingRefs
+}
+
+/**
+ * Extracts contract references from job actions
+ */
+function extractJobActionsContractReferences(
+  actions: JobAction[], 
+  locationPrefix: string, 
+  contextPath: string | undefined,
+  usedRefs: UsedContractReference[]
+): void {
+  for (let i = 0; i < actions.length; i++) {
+    const action = actions[i]
+    const actionLocation = `${locationPrefix}, action ${i + 1}${action.name ? ` '${action.name}'` : ''}`
+    
+    extractValueContractReferences(action.arguments, actionLocation, contextPath, usedRefs)
+  }
+}
+
+/**
+ * Extracts contract references from template actions
+ */
+function extractActionsContractReferences(
+  actions: Action[], 
+  locationPrefix: string, 
+  contextPath: string | undefined,
+  usedRefs: UsedContractReference[]
+): void {
+  for (let i = 0; i < actions.length; i++) {
+    const action = actions[i]
+    const actionLocation = `${locationPrefix}, action ${i + 1}${action.name ? ` '${action.name}'` : ''}`
+    
+    extractValueContractReferences(action.arguments, actionLocation, contextPath, usedRefs)
+  }
+}
+
+/**
+ * Recursively extracts contract references from a value (or nested object/array)
+ */
+function extractValueContractReferences(
+  value: any, 
+  location: string, 
+  contextPath: string | undefined,
+  usedRefs: UsedContractReference[]
+): void {
+  if (typeof value === 'string') {
+    // Check for Contract() expressions
+    const contractMatch = value.match(/^{{Contract\((.*?)\)(?:\.\w+)?}}$/)
+    if (contractMatch) {
+      const reference = contractMatch[1].trim()
+      usedRefs.push({
+        reference,
+        location: `${location}, Contract(${reference})`
+      })
+    }
+  } else if (Array.isArray(value)) {
+    // Recursively check array elements
+    for (let i = 0; i < value.length; i++) {
+      extractValueContractReferences(value[i], `${location}[${i}]`, contextPath, usedRefs)
+    }
+  } else if (typeof value === 'object' && value !== null) {
+    // Recursively check object properties
+    for (const [key, val] of Object.entries(value)) {
+      extractValueContractReferences(val, `${location}.${key}`, contextPath, usedRefs)
+    }
+  }
+}
+
+/**
+ * Validates a list of job actions for missing contract references
+ */
+function validateJobActionsForMissingContracts(
+  actions: JobAction[], 
+  locationPrefix: string, 
+  contextPath: string | undefined,
+  loader: ProjectLoader, 
+  missingRefs: MissingContractReference[]
+): void {
+  for (let i = 0; i < actions.length; i++) {
+    const action = actions[i]
+    const actionLocation = `${locationPrefix}, action ${i + 1}${action.name ? ` '${action.name}'` : ''}`
+    
+    validateValueForMissingContracts(action.arguments, actionLocation, contextPath, loader, missingRefs)
+  }
+}
+
+/**
+ * Validates a list of template actions for missing contract references
+ */
+function validateActionsForMissingContracts(
+  actions: Action[], 
+  locationPrefix: string, 
+  contextPath: string | undefined,
+  loader: ProjectLoader, 
+  missingRefs: MissingContractReference[]
+): void {
+  for (let i = 0; i < actions.length; i++) {
+    const action = actions[i]
+    const actionLocation = `${locationPrefix}, action ${i + 1}${action.name ? ` '${action.name}'` : ''}`
+    
+    validateValueForMissingContracts(action.arguments, actionLocation, contextPath, loader, missingRefs)
+  }
+}
+
+/**
+ * Recursively validates a value (or nested object/array) for missing contract references
+ */
+function validateValueForMissingContracts(
+  value: any, 
+  location: string, 
+  contextPath: string | undefined,
+  loader: ProjectLoader, 
+  missingRefs: MissingContractReference[]
+): void {
+  if (typeof value === 'string') {
+    // Check for Contract() expressions
+    const contractMatch = value.match(/^{{Contract\((.*?)\)(?:\.\w+)?}}$/)
+    if (contractMatch) {
+      const reference = contractMatch[1].trim()
+      
+      // Try to lookup the contract
+      const contract = loader.contractRepository.lookup(reference, contextPath)
+      if (!contract) {
+        missingRefs.push({
+          reference,
+          location: `${location}, Contract(${reference})`
+        })
+      }
+    }
+  } else if (Array.isArray(value)) {
+    // Recursively check array elements
+    for (let i = 0; i < value.length; i++) {
+      validateValueForMissingContracts(value[i], `${location}[${i}]`, contextPath, loader, missingRefs)
+    }
+  } else if (typeof value === 'object' && value !== null) {
+    // Recursively check object properties
+    for (const [key, val] of Object.entries(value)) {
+      validateValueForMissingContracts(val, `${location}.${key}`, contextPath, loader, missingRefs)
+    }
+  }
+}

package/src/lib/validation/index.ts

@@ -0,0 +1 @@
+// No exports - validation logic is now integrated into ContractRepository