@0xsequence/catapult 1.3.17 → 1.4.0

package/src/lib/core/loader.ts

@@ -7,6 +7,7 @@ import { parseConstants } from '../parsers/constants'
 
 export interface ProjectLoaderOptions {
   loadStdTemplates?: boolean
+  loadContracts?: boolean
 }
 
 export class ProjectLoader {
@@ -28,7 +29,9 @@ export class ProjectLoader {
 
   async load() {
     // Load all contracts from the project root first
-    await this.contractRepository.loadFrom(this.projectRoot)
+    if (this.options.loadContracts !== false) {
+      await this.contractRepository.loadFrom(this.projectRoot)
+    }
 
     // Load standard library templates (unless disabled)
     if (this.options.loadStdTemplates !== false) {
@@ -119,6 +122,9 @@ export class ProjectLoader {
           this.templates.set(template.name, template)
           continue
         }
+        if (raw && typeof raw === 'object' && (raw.type === 'source' || raw.type === 'constants')) {
+          continue
+        }
 
         const job = parseJob(content)
         job._path = filePath
@@ -244,4 +250,4 @@ export class ProjectLoader {
           return false
       }
   }
-}
+}

package/src/lib/core/resolver.ts

@@ -8,6 +8,8 @@ import {
   ComputeCreateValue,
   ComputeCreate2Value,
   ReadBalanceValue,
+  GetStorageAtValue,
+  ComputeSlotValue,
   BasicArithmeticValue,
   CallValue,
   ContractExistsValue,
@@ -197,6 +199,10 @@ export class ValueResolver {
         return this.resolveComputeCreate2(resolvedArgs as ComputeCreate2Value['arguments'])
       case 'read-balance':
         return this.resolveReadBalance(resolvedArgs as ReadBalanceValue['arguments'], context)
+      case 'get-storage-at':
+        return this.resolveGetStorageAt(resolvedArgs as GetStorageAtValue['arguments'], context)
+      case 'compute-slot':
+        return this.resolveComputeSlot(resolvedArgs as ComputeSlotValue['arguments'])
       case 'basic-arithmetic':
         return this.resolveBasicArithmetic(resolvedArgs as BasicArithmeticValue['arguments'])
       case 'call':
@@ -375,6 +381,116 @@ export class ValueResolver {
     return balance.toString()
   }
 
+  private async resolveGetStorageAt(args: GetStorageAtValue['arguments'], context: ExecutionContext): Promise<string> {
+    const { address, slot } = args
+
+    // Check if the address is a valid address
+    if (!isAddress(address)) {
+      throw new Error(`Invalid address: ${address}`)
+    }
+
+    // Normalize the slot to a BigInt
+    // After resolution, slot should be a string or number
+    const slotValue = ethers.toBigInt(slot as string | number)
+
+    const storageValue = await context.provider.getStorage(address, slotValue)
+    // getStorage returns a hex string, ensure it's 32 bytes (64 hex chars + 0x)
+    return ethers.hexlify(storageValue)
+  }
+
+  /**
+   * Computes EVM storage slots for the common Solidity storage layouts.
+   * Always returns a 32-byte, 0x-prefixed lowercase hex string so the result can
+   * be fed straight into `get-storage-at` or nested as the `slot` of another
+   * `compute-slot` (e.g. nested mappings, structs inside mappings, ...).
+   */
+  private resolveComputeSlot(args: ComputeSlotValue['arguments']): string {
+    if (!args || typeof args !== 'object' || typeof (args as any).kind !== 'string') {
+      throw new Error('compute-slot: "kind" is required')
+    }
+
+    switch (args.kind) {
+      case 'mapping': {
+        const { slot, key, keyType } = args
+        if (slot === undefined || slot === null) {
+          throw new Error('compute-slot (mapping): "slot" is required')
+        }
+        if (key === undefined || key === null) {
+          throw new Error('compute-slot (mapping): "key" is required')
+        }
+        const baseSlot = ethers.toBigInt(slot as string | number)
+        const type = (keyType as string) || 'uint256'
+        try {
+          // mapping value slot = keccak256(h(key) . p)
+          // Dynamic key types (string/bytes) are packed; value types are ABI-encoded (left-padded to 32 bytes).
+          if (type === 'string' || type === 'bytes') {
+            return ethers.solidityPackedKeccak256([type, 'uint256'], [key, baseSlot])
+          }
+          const encoded = ethers.AbiCoder.defaultAbiCoder().encode([type, 'uint256'], [key, baseSlot])
+          return ethers.keccak256(encoded)
+        } catch (error) {
+          throw new Error(`compute-slot (mapping): failed to encode key as "${type}": ${error instanceof Error ? error.message : String(error)}`)
+        }
+      }
+
+      case 'dynamic-array': {
+        const { slot, index, elementSize } = args
+        if (slot === undefined || slot === null) {
+          throw new Error('compute-slot (dynamic-array): "slot" is required')
+        }
+        const baseSlot = ethers.toBigInt(slot as string | number)
+        const idx = index === undefined || index === null ? 0n : ethers.toBigInt(index as string | number)
+        const size = elementSize === undefined || elementSize === null ? 1n : ethers.toBigInt(elementSize as string | number)
+        // element slot = keccak256(slot) + index * elementSize
+        const dataStart = ethers.toBigInt(ethers.keccak256(ethers.toBeHex(baseSlot, 32)))
+        return ethers.toBeHex(dataStart + idx * size, 32)
+      }
+
+      case 'struct-field': {
+        const { slot, offset } = args
+        if (slot === undefined || slot === null) {
+          throw new Error('compute-slot (struct-field): "slot" is required')
+        }
+        if (offset === undefined || offset === null) {
+          throw new Error('compute-slot (struct-field): "offset" is required')
+        }
+        const result = ethers.toBigInt(slot as string | number) + ethers.toBigInt(offset as string | number)
+        return ethers.toBeHex(result, 32)
+      }
+
+      case 'erc7201': {
+        const { id } = args
+        if (typeof id !== 'string' || id.length === 0) {
+          throw new Error('compute-slot (erc7201): "id" must be a non-empty string')
+        }
+        // keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))
+        const idHash = ethers.toBigInt(ethers.keccak256(ethers.toUtf8Bytes(id)))
+        const inner = ethers.keccak256(ethers.toBeHex(idHash - 1n, 32))
+        const mask = ((1n << 256n) - 1n) ^ 0xffn
+        return ethers.toBeHex(ethers.toBigInt(inner) & mask, 32)
+      }
+
+      case 'eip1967': {
+        const labels: Record<string, string> = {
+          implementation: 'eip1967.proxy.implementation',
+          admin: 'eip1967.proxy.admin',
+          beacon: 'eip1967.proxy.beacon',
+        }
+        const name = args.name as string
+        const label = labels[name]
+        if (!label) {
+          throw new Error(`compute-slot (eip1967): "name" must be one of implementation, admin, beacon (got "${name}")`)
+        }
+        // slot = keccak256("eip1967.proxy.<name>") - 1
+        const slot = ethers.toBigInt(ethers.keccak256(ethers.toUtf8Bytes(label))) - 1n
+        return ethers.toBeHex(slot, 32)
+      }
+
+      default:
+        throw new Error(`compute-slot: unknown kind "${(args as any).kind}"`)
+    }
+  }
+
   private resolveBasicArithmetic(args: BasicArithmeticValue['arguments']): string | boolean {
     if (!args.values || args.values.length < 2) {
       throw new Error(`basic-arithmetic requires at least 2 values, got ${args.values?.length ?? 0}`)

package/src/lib/deployer.ts

@@ -261,13 +261,37 @@ export class Deployer {
             }
 
             // Check job-level skip conditions before execution
-            if (job.skip_condition) {
-              const shouldSkip = await engine.evaluateSkipConditions(job.skip_condition, context, new Map())
+            // skip_if is a pure gate (no post-check), skip_condition has both pre-skip and post-check
+            const skipIfConditions = job.skip_if
+            const skipConditions = job.skip_condition
+            
+            if (skipIfConditions || skipConditions) {
+              // Evaluate skip_if first (pure gate)
+              let shouldSkip = false
+              let skipReason: string = 'skip_condition'
+              
+              if (skipIfConditions) {
+                const skipIfResult = await engine.evaluateSkipConditions(skipIfConditions, context, new Map())
+                if (skipIfResult) {
+                  shouldSkip = true
+                  skipReason = 'skip_if'
+                }
+              }
+              
+              // If not skipped by skip_if, check skip_condition
+              if (!shouldSkip && skipConditions) {
+                const skipConditionResult = await engine.evaluateSkipConditions(skipConditions, context, new Map())
+                if (skipConditionResult) {
+                  shouldSkip = true
+                  skipReason = 'skip_condition'
+                }
+              }
+              
               if (shouldSkip) {
                 // Store skipped result
                 this.results.get(job.name)!.outputs.set(network.chainId, {
                   status: 'skipped',
-                  data: `Job "${job.name}" skipped due to skip condition`
+                  data: `Job "${job.name}" skipped due to ${skipReason}`
                 })
 
                 this.events.emitEvent({
@@ -276,7 +300,7 @@ export class Deployer {
                   data: {
                     jobName: job.name,
                     networkName: network.name,
-                    reason: 'skip_condition'
+                    reason: skipReason
                   }
                 })
 

package/src/lib/index.ts

@@ -10,5 +10,8 @@ export * as parsers from './parsers'
 // Export the deployer
 export * from './deployer'
 
+// Export provenance helpers
+export * from './provenance'
+
 // This will be the main entry point for the lib
-// Additional functionality will be added here as the lib grows
+// Additional functionality will be added here as the lib grows

package/src/lib/parsers/__tests__/job.spec.ts

@@ -355,4 +355,85 @@ actions:
       arguments: { address: '0xabc' }
     })
   })
+
+  it('should parse job-level skip_if conditions', () => {
+    const yamlContent = `
+name: "job-with-skip-if"
+version: "1"
+skip_if:
+  - type: "contract-exists"
+    arguments:
+      address: "0xdef"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    const job = parseJob(yamlContent)
+    expect(job.skip_if).toHaveLength(1)
+    expect(job.skip_if?.[0]).toEqual({
+      type: 'contract-exists',
+      arguments: { address: '0xdef' }
+    })
+  })
+
+  it('should parse both skip_condition and skip_if on a job', () => {
+    const yamlContent = `
+name: "job-with-both"
+version: "1"
+skip_condition:
+  - type: "contract-exists"
+    arguments:
+      address: "0xabc"
+skip_if:
+  - type: "job-completed"
+    arguments:
+      job: "other-job"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    const job = parseJob(yamlContent)
+    expect(job.skip_condition).toHaveLength(1)
+    expect(job.skip_condition?.[0]).toEqual({
+      type: 'contract-exists',
+      arguments: { address: '0xabc' }
+    })
+    expect(job.skip_if).toHaveLength(1)
+    expect(job.skip_if?.[0]).toEqual({
+      type: 'job-completed',
+      arguments: { job: 'other-job' }
+    })
+  })
+
+  it('should throw when skip_if is not an array', () => {
+    const yamlContent = `
+name: "job-with-invalid-skip-if"
+version: "1"
+skip_if:
+  type: "contract-exists"
+  arguments:
+    address: "0xabc"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    expect(() => parseJob(yamlContent)).toThrow('"skip_if" must be an array if provided')
+  })
+
+  it('should throw when skip_if contains invalid condition', () => {
+    const yamlContent = `
+name: "job-with-invalid-skip-if"
+version: "1"
+skip_if:
+  - type: "invalid-type"
+actions:
+  - name: "a1"
+    template: "t1"
+    arguments: {}
+`
+    expect(() => parseJob(yamlContent)).toThrow('"skip_if" contains an invalid condition entry')
+  })
 })

package/src/lib/parsers/__tests__/source.spec.ts

@@ -0,0 +1,134 @@
+import { mergeSourceProvenance, parseSourceDocument } from '../source'
+
+describe('Source Provenance Parsing', () => {
+  it('should return null for non-source YAML documents', () => {
+    const result = parseSourceDocument(`
+type: constants
+constants:
+  value: 1
+`)
+
+    expect(result).toBeNull()
+  })
+
+  it('should parse source provenance documents', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    ref: "v3.0.0-rc.5"
+    commit: "0d9061f229da73edae890e6fdd1fbf753028df6d"
+    build: "forge build --build-info"
+    contracts:
+      "src/Stage1Module.sol:Stage1Module":
+        ref: "stage1-special"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info['./stage1.json'].repo).toBe('https://github.com/0xsequence/wallet-contracts-v3')
+    expect(result!.build_info['./stage1.json'].contracts?.['src/Stage1Module.sol:Stage1Module'].ref).toBe('stage1-special')
+  })
+
+  it('should require repo on each build-info provenance entry', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    ref: "v3.0.0-rc.5"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info).toEqual({})
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('build_info["./stage1.json"].repo')
+    ])
+  })
+
+  it('should validate optional string fields', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    commit: 123
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info).toEqual({})
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('commit')
+    ])
+  })
+
+  it('should reject unsupported fields', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    path: "contracts"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.build_info).toEqual({})
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('path is not supported')
+    ])
+  })
+
+  it('should quote build-info paths in validation errors', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    ref: "v3.0.0-rc.5"
+`)
+
+    expect(result).not.toBeNull()
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('build_info["./stage1.json"].repo')
+    ])
+  })
+
+  it('should keep valid entries when sibling entries are invalid', () => {
+    const result = parseSourceDocument(`
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+  "./bad.json":
+    typo_field: true
+`)
+
+    expect(result).not.toBeNull()
+    expect(Object.keys(result!.build_info)).toEqual(['./stage1.json'])
+    expect(result!.warnings).toEqual([
+      expect.stringContaining('typo_field is not supported')
+    ])
+  })
+
+  describe('mergeSourceProvenance', () => {
+    it('should merge contract overrides into build-info provenance', () => {
+      const result = mergeSourceProvenance({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'v3.0.0-rc.5',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d',
+        contracts: {
+          'src/Stage1Module.sol:Stage1Module': {
+            ref: 'stage1-special'
+          }
+        }
+      }, {
+        ref: 'stage1-special'
+      })
+
+      expect(result).toEqual({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'stage1-special',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d'
+      })
+      expect(result).not.toHaveProperty('contracts')
+    })
+  })
+})

package/src/lib/parsers/index.ts

@@ -3,3 +3,4 @@ export * from './template'
 export * from './job'
 export * from './buildinfo'
 export * from './constants'
+export * from './source'

package/src/lib/parsers/job.ts

@@ -110,7 +110,7 @@ export function parseJob(yamlContent: string): Job {
     throw new Error(`Invalid job "${rawObject.name}": "min_evm_version" must be a string if provided.`)
   }
 
-  // --- Optional: validate job-level skip_condition and constants ---
+  // --- Optional: validate job-level skip_condition and skip_if ---
   if (rawObject.skip_condition !== undefined) {
     if (!Array.isArray(rawObject.skip_condition)) {
       throw new Error(`Invalid job "${rawObject.name}": "skip_condition" must be an array if provided.`)
@@ -122,6 +122,17 @@ export function parseJob(yamlContent: string): Job {
     }
   }
 
+  if (rawObject.skip_if !== undefined) {
+    if (!Array.isArray(rawObject.skip_if)) {
+      throw new Error(`Invalid job "${rawObject.name}": "skip_if" must be an array if provided.`)
+    }
+    for (const condition of rawObject.skip_if) {
+      if (!isCondition(condition)) {
+        throw new Error(`Invalid job "${rawObject.name}": "skip_if" contains an invalid condition entry.`)
+      }
+    }
+  }
+
   if (rawObject.constants !== undefined) {
     if (typeof rawObject.constants !== 'object' || rawObject.constants === null || Array.isArray(rawObject.constants)) {
       throw new Error(`Invalid job "${rawObject.name}": "constants" field must be an object if provided.`)
@@ -141,8 +152,9 @@ export function parseJob(yamlContent: string): Job {
     min_evm_version: rawObject.min_evm_version,
     deprecated: rawObject.deprecated === true,
     skip_condition: rawObject.skip_condition as Condition[] | undefined,
+    skip_if: rawObject.skip_if as Condition[] | undefined,
     constants: rawObject.constants,
   }
 
   return job
-}
+}

package/src/lib/parsers/source.ts

@@ -0,0 +1,129 @@
+import { parse as parseYaml, YAMLParseError } from 'yaml'
+import { BuildInfoSourceProvenance, SourceDocument, SourceProvenance, SourceProvenanceOverride } from '../types'
+
+const STRING_FIELDS = ['repo', 'ref', 'commit', 'build'] as const
+const BUILD_INFO_FIELDS = new Set<string>([...STRING_FIELDS, 'contracts'])
+const CONTRACT_OVERRIDE_FIELDS = new Set<string>(STRING_FIELDS)
+
+function isPlainObject(value: any): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function buildInfoLabel(buildInfoPath: string): string {
+  return `build_info[${JSON.stringify(buildInfoPath)}]`
+}
+
+function contractOverrideLabel(buildInfoPath: string, contractName: string): string {
+  return `${buildInfoLabel(buildInfoPath)}.contracts[${JSON.stringify(contractName)}]`
+}
+
+function validateKnownFields(value: Record<string, any>, label: string, allowedFields: Set<string>): void {
+  for (const field of Object.keys(value)) {
+    if (!allowedFields.has(field)) {
+      throw new Error(`Invalid source: ${label}.${field} is not supported.`)
+    }
+  }
+}
+
+function validateStringFields(value: Record<string, any>, label: string, requiredRepo: boolean): void {
+  if (requiredRepo && (typeof value.repo !== 'string' || value.repo.length === 0)) {
+    throw new Error(`Invalid source: ${label}.repo field is required and must be a non-empty string.`)
+  }
+
+  for (const field of STRING_FIELDS) {
+    if (value[field] !== undefined && typeof value[field] !== 'string') {
+      throw new Error(`Invalid source: ${label}.${field} must be a string if provided.`)
+    }
+  }
+}
+
+function validateBuildInfoProvenance(buildInfoPath: string, provenance: unknown): BuildInfoSourceProvenance {
+  if (!isPlainObject(provenance)) {
+    throw new Error(`Invalid source: ${buildInfoLabel(buildInfoPath)} must be an object.`)
+  }
+
+  const label = buildInfoLabel(buildInfoPath)
+  validateKnownFields(provenance, label, BUILD_INFO_FIELDS)
+  validateStringFields(provenance, label, true)
+
+  if (provenance.contracts !== undefined) {
+    if (!isPlainObject(provenance.contracts)) {
+      throw new Error(`Invalid source: ${label}.contracts must be an object if provided.`)
+    }
+
+    for (const [contractName, override] of Object.entries(provenance.contracts)) {
+      if (!contractName || typeof contractName !== 'string') {
+        throw new Error(`Invalid source: ${label}.contracts keys must be non-empty strings.`)
+      }
+      if (!isPlainObject(override)) {
+        throw new Error(`Invalid source: ${contractOverrideLabel(buildInfoPath, contractName)} must be an object.`)
+      }
+      const overrideLabel = contractOverrideLabel(buildInfoPath, contractName)
+      validateKnownFields(override, overrideLabel, CONTRACT_OVERRIDE_FIELDS)
+      validateStringFields(override, overrideLabel, false)
+    }
+  }
+
+  return provenance as BuildInfoSourceProvenance
+}
+
+/**
+ * Parses a YAML source provenance document.
+ * Returns null for YAML documents that are not marked with `type: "source"`.
+ */
+export function parseSourceDocument(yamlContent: string): SourceDocument | null {
+  let rawObject: any
+  try {
+    rawObject = parseYaml(yamlContent)
+  } catch (e) {
+    if (e instanceof YAMLParseError) {
+      const line = (e as any).linePos?.[0]?.line ? ` at line ${(e as any).linePos[0].line}` : ''
+      throw new Error(`Failed to parse source YAML: ${e.message}${line}.`)
+    }
+    throw e
+  }
+
+  if (!rawObject || typeof rawObject !== 'object') {
+    return null
+  }
+
+  if (rawObject.type !== 'source') {
+    return null
+  }
+
+  if (!isPlainObject(rawObject.build_info)) {
+    throw new Error('Invalid source: "build_info" field is required and must be an object.')
+  }
+
+  const buildInfo: Record<string, BuildInfoSourceProvenance> = {}
+  const warnings: string[] = []
+
+  for (const [buildInfoPath, provenance] of Object.entries(rawObject.build_info)) {
+    if (!buildInfoPath || typeof buildInfoPath !== 'string') {
+      throw new Error('Invalid source: "build_info" keys must be non-empty strings.')
+    }
+
+    try {
+      buildInfo[buildInfoPath] = validateBuildInfoProvenance(buildInfoPath, provenance)
+    } catch (error) {
+      warnings.push(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  return {
+    type: 'source',
+    build_info: buildInfo,
+    warnings
+  }
+}
+
+export function mergeSourceProvenance(
+  base: BuildInfoSourceProvenance,
+  override?: SourceProvenanceOverride
+): SourceProvenance {
+  const { contracts, ...baseFields } = base
+  return {
+    ...baseFields,
+    ...(override || {})
+  }
+}