@0xsequence/catapult 1.3.17 → 1.4.0

package/src/lib/contracts/repository.ts

@@ -2,23 +2,26 @@ import * as fs from 'fs/promises'
 import * as path from 'path'
 import { createHash } from 'crypto'
 import { Contract } from '../types/contracts'
+import { BuildInfoSourceProvenance, SourceProvenance } from '../types/source'
 import { parseArtifact } from '../parsers/artifact'
 import { parseBuildInfo, isBuildInfoFile } from '../parsers/buildinfo'
+import { mergeSourceProvenance, parseSourceDocument } from '../parsers/source'
 
 export class ContractRepository {
   private contracts: Map<string, Contract> = new Map()
   private referenceMap: Map<string, string[]> = new Map()
   private ambiguousReferences: Set<string> = new Set()
+  private sourceProvenanceByBuildInfoPath: Map<string, BuildInfoSourceProvenance> = new Map()
 
   /**
    * Main entry point that orchestrates the discovery and hydration process
    */
   public async loadFrom(projectRoot: string): Promise<void> {
-    // Step 1: Discover all .json files
-    const files = await this.findContractFiles(projectRoot)
+    const files = await this.findProjectFiles(projectRoot)
 
-    // Step 2: Parse and hydrate contracts from all discovered files
-    for (const filePath of files) {
+    await this.loadSourceProvenanceFiles(files.sourceFiles)
+
+    for (const filePath of files.contractFiles) {
       try {
         const content = await fs.readFile(filePath, 'utf-8')
         await this.parseAndHydrateFromFile(content, filePath)
@@ -27,7 +30,6 @@ export class ContractRepository {
       }
     }
 
-    // Step 3: Build reference maps and identify ambiguous references
     this.disambiguateReferences()
   }
 
@@ -40,6 +42,7 @@ export class ContractRepository {
       const extractedContracts = parseBuildInfo(content, filePath)
       if (extractedContracts) {
         for (const extracted of extractedContracts) {
+          const sourceProvenance = this.getSourceProvenance(filePath, extracted.fullyQualifiedName)
           this.hydrateContract({
             creationCode: extracted.bytecode,
             runtimeBytecode: extracted.deployedBytecode,
@@ -49,6 +52,7 @@ export class ContractRepository {
             source: extracted.source,
             compiler: extracted.compiler,
             buildInfoId: extracted.buildInfoId,
+            sourceProvenance,
           }, filePath)
         }
         return
@@ -82,6 +86,7 @@ export class ContractRepository {
     source?: string
     compiler?: any
     buildInfoId?: string
+    sourceProvenance?: SourceProvenance
   }, sourceFilePath: string): void {
     // Validate that we have creation code for hashing (but allow empty string)
     if (data.creationCode === null || data.creationCode === undefined) {
@@ -97,7 +102,8 @@ export class ContractRepository {
       contract = {
         uniqueHash,
         creationCode: data.creationCode,
-        _sources: new Set<string>()
+        _sources: new Set<string>(),
+        _sourceProvenance: new Map<string, SourceProvenance>()
       }
       this.contracts.set(uniqueHash, contract)
     }
@@ -130,6 +136,28 @@ export class ContractRepository {
     if (data.buildInfoId && !contract.buildInfoId) {
       contract.buildInfoId = data.buildInfoId
     }
+    if (data.sourceProvenance) {
+      if (!contract._sourceProvenance) {
+        contract._sourceProvenance = new Map<string, SourceProvenance>()
+      }
+      contract._sourceProvenance.set(sourceFilePath, data.sourceProvenance)
+
+      contract.sourceProvenance = this.selectPreferredSourceProvenance(contract._sourceProvenance)
+    }
+  }
+
+  private getSourceProvenance(buildInfoPath: string, fullyQualifiedName: string): SourceProvenance | undefined {
+    const provenance = this.sourceProvenanceByBuildInfoPath.get(buildInfoPath)
+    if (!provenance) {
+      return undefined
+    }
+
+    return mergeSourceProvenance(provenance, provenance.contracts?.[fullyQualifiedName])
+  }
+
+  private selectPreferredSourceProvenance(sourceProvenance: Map<string, SourceProvenance>): SourceProvenance | undefined {
+    const firstEntry = Array.from(sourceProvenance.entries()).sort(([a], [b]) => a.localeCompare(b))[0]
+    return firstEntry?.[1]
   }
 
   /**
@@ -269,6 +297,7 @@ export class ContractRepository {
     source?: string
     compiler?: any
     buildInfoId?: string
+    sourceProvenance?: SourceProvenance
     _path: string
     _hash: string
   }): void {
@@ -281,17 +310,21 @@ export class ContractRepository {
       source: contractData.source,
       compiler: contractData.compiler,
       buildInfoId: contractData.buildInfoId,
+      sourceProvenance: contractData.sourceProvenance,
     }, contractData._path)
 
     // For testing, immediately disambiguate references after adding
     this.disambiguateReferences()
   }
 
-  /**
-   * Recursively finds all files that might contain contracts (e.g., .json files)
-   */
-  private async findContractFiles(dir: string, ignoreDirs: Set<string> = new Set(['node_modules', 'dist', '.git', '.idea', '.vscode'])): Promise<string[]> {
-    let results: string[] = []
+  private async findProjectFiles(
+    dir: string,
+    ignoreDirs: Set<string> = new Set(['node_modules', 'dist', '.git', '.idea', '.vscode'])
+  ): Promise<{ contractFiles: string[]; sourceFiles: string[] }> {
+    const results: { contractFiles: string[]; sourceFiles: string[] } = {
+      contractFiles: [],
+      sourceFiles: []
+    }
     try {
       const list = await fs.readdir(dir, { withFileTypes: true })
 
@@ -299,10 +332,14 @@ export class ContractRepository {
         const fullPath = path.resolve(dir, dirent.name)
         if (dirent.isDirectory()) {
           if (!ignoreDirs.has(dirent.name)) {
-            results = results.concat(await this.findContractFiles(fullPath, ignoreDirs))
+            const childResults = await this.findProjectFiles(fullPath, ignoreDirs)
+            results.contractFiles.push(...childResults.contractFiles)
+            results.sourceFiles.push(...childResults.sourceFiles)
           }
         } else if (dirent.isFile() && dirent.name.endsWith('.json')) {
-          results.push(fullPath)
+          results.contractFiles.push(fullPath)
+        } else if (dirent.isFile() && (dirent.name === 'source.yaml' || dirent.name === 'source.yml')) {
+          results.sourceFiles.push(fullPath)
         }
       }
     } catch (err) {
@@ -310,4 +347,65 @@ export class ContractRepository {
     }
     return results
   }
-}
+
+  private async loadSourceProvenanceFiles(sourceFiles: string[]): Promise<void> {
+    this.sourceProvenanceByBuildInfoPath.clear()
+
+    for (const sourceFilePath of sourceFiles) {
+      let sourceDocument
+      try {
+        const content = await fs.readFile(sourceFilePath, 'utf-8')
+        sourceDocument = parseSourceDocument(content)
+      } catch (error) {
+        this.warnSourceProvenance(`Skipping source provenance file ${sourceFilePath}: ${error instanceof Error ? error.message : String(error)}`)
+        continue
+      }
+
+      if (!sourceDocument) {
+        continue
+      }
+
+      for (const warning of sourceDocument.warnings || []) {
+        this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: ${warning}`)
+      }
+
+      const sourceDir = path.dirname(sourceFilePath)
+      for (const [buildInfoRef, provenance] of Object.entries(sourceDocument.build_info)) {
+        const buildInfoPath = path.resolve(sourceDir, buildInfoRef)
+        if (!isBuildInfoFile(buildInfoPath)) {
+          this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: "${buildInfoRef}" does not point to a build-info JSON file.`)
+          continue
+        }
+
+        if (!await this.pathExists(buildInfoPath)) {
+          this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: build-info file "${buildInfoRef}" does not exist.`)
+          continue
+        }
+
+        if (this.sourceProvenanceByBuildInfoPath.has(buildInfoPath)) {
+          this.warnSourceProvenance(`Skipping source provenance entry ${sourceFilePath}: duplicate provenance for build-info file "${buildInfoRef}".`)
+          continue
+        }
+
+        this.sourceProvenanceByBuildInfoPath.set(buildInfoPath, {
+          ...provenance,
+          sourceDocumentPath: sourceFilePath,
+          buildInfoPath
+        })
+      }
+    }
+  }
+
+  private async pathExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  private warnSourceProvenance(message: string): void {
+    console.warn(message)
+  }
+}

package/src/lib/core/__tests__/assert-action.spec.ts

@@ -0,0 +1,474 @@
+import { ExecutionEngine } from '../engine'
+import { ExecutionContext } from '../context'
+import { ContractRepository } from '../../contracts/repository'
+import { Action, Network } from '../../types'
+import { VerificationPlatformRegistry } from '../../verification/etherscan'
+
+describe('Assert Action', () => {
+  let engine: ExecutionEngine
+  let context: ExecutionContext
+  let mockNetwork: Network
+  let mockRegistry: ContractRepository
+  let templates: Map<string, any>
+
+  beforeEach(() => {
+    mockNetwork = { name: 'testnet', chainId: 999, rpcUrl: 'http://localhost:8545' }
+    mockRegistry = new ContractRepository()
+
+    // Create a mock context that doesn't require a real connection
+    context = {
+      getNetwork: () => mockNetwork,
+      setOutput: jest.fn(),
+      getOutput: jest.fn(),
+      setContextPath: jest.fn(),
+      getContextPath: jest.fn(),
+      dispose: jest.fn()
+    } as any
+
+    templates = new Map()
+    const verificationRegistry = new VerificationPlatformRegistry()
+    engine = new ExecutionEngine(templates, { verificationRegistry })
+  })
+
+  describe('assert primitive action', () => {
+    it('should pass when eq comparison is true', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-eq',
+        arguments: {
+          actual: '42',
+          eq: '42'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-eq.actual', '42')
+    })
+
+    it('should fail when eq comparison is false', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-fail',
+        arguments: {
+          actual: '42',
+          eq: '99'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*actual=42.*expected=99.*op=eq/)
+    })
+
+    it('should include custom message on failure', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-msg',
+        arguments: {
+          actual: '10',
+          eq: '20',
+          message: 'balance mismatch'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed: balance mismatch.*actual=10.*expected=20.*op=eq/)
+    })
+
+    it('should pass neq comparison', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-neq',
+        arguments: {
+          actual: '10',
+          neq: '20'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-neq.actual', '10')
+    })
+
+    it('should fail neq comparison when values are equal', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-neq-fail',
+        arguments: {
+          actual: '10',
+          neq: '10'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*op=neq/)
+    })
+
+    it('should pass gte comparison', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-gte',
+        arguments: {
+          actual: '100',
+          gte: '50'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-gte.actual', '100')
+    })
+
+    it('should pass gte when equal', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-gte-equal',
+        arguments: {
+          actual: '50',
+          gte: '50'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+    })
+
+    it('should fail gte when less', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-gte-fail',
+        arguments: {
+          actual: '10',
+          gte: '100'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*op=gte/)
+    })
+
+    it('should pass lt comparison', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-lt',
+        arguments: {
+          actual: '10',
+          lt: '100'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+    })
+
+    it('should fail lt when greater', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-lt-fail',
+        arguments: {
+          actual: '100',
+          lt: '10'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*op=lt/)
+    })
+
+    it('should pass lte comparison', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-lte',
+        arguments: {
+          actual: '10',
+          lte: '100'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+    })
+
+    it('should pass lte when equal', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-lte-equal',
+        arguments: {
+          actual: '100',
+          lte: '100'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+    })
+
+    it('should fail lte when greater', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-lte-fail',
+        arguments: {
+          actual: '100',
+          lte: '10'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*op=lte/)
+    })
+
+    it('should pass gt comparison', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-gt',
+        arguments: {
+          actual: '100',
+          gt: '10'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+    })
+
+    it('should fail gt when less', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-gt-fail',
+        arguments: {
+          actual: '10',
+          gt: '100'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*op=gt/)
+    })
+
+    it('should use `to` + `signature` form (call resolver)', async () => {
+      // Mock the resolver to simulate a call returning a value
+      const mockResolver = {
+        resolve: jest.fn(async (value: any, ctx: any, scope: any) => {
+          if (value.type === 'call') {
+            return '0xDepositManagerAddress'
+          }
+          if (value.type === 'basic-arithmetic') {
+            const [a, b] = value.arguments.values
+            if (value.arguments.operation === 'eq') {
+              return a === b
+            }
+          }
+          return value
+        })
+      }
+      ;(engine as any).resolver = mockResolver
+
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-call',
+        arguments: {
+          to: '0xSomeProxyAddress',
+          signature: 'depositManager() returns (address)',
+          eq: '0xDepositManagerAddress'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+
+      expect(mockResolver.resolve).toHaveBeenCalledWith(
+        { type: 'call', arguments: { to: '0xSomeProxyAddress', signature: 'depositManager() returns (address)', values: [] } },
+        context,
+        new Map()
+      )
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-call.actual', '0xDepositManagerAddress')
+    })
+
+    it('should use `actual` form with read-balance resolver', async () => {
+      // Mock the resolver to simulate a read-balance returning a value
+      const mockResolver = {
+        resolve: jest.fn(async (value: any, ctx: any, scope: any) => {
+          if (value.type === 'read-balance') {
+            return '1000000000000000000' // 1 ETH
+          }
+          if (value.type === 'basic-arithmetic') {
+            const [a, b] = value.arguments.values
+            if (value.arguments.operation === 'gte') {
+              return BigInt(a) >= BigInt(b)
+            }
+          }
+          return value
+        })
+      }
+      ;(engine as any).resolver = mockResolver
+
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-read-balance',
+        arguments: {
+          actual: { type: 'read-balance', arguments: { address: '0xDeployer' } },
+          gte: '1000000000000000000',
+          message: 'deployer underfunded'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+
+      expect(mockResolver.resolve).toHaveBeenCalledWith(
+        { type: 'read-balance', arguments: { address: '0xDeployer' } },
+        context,
+        new Map()
+      )
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-read-balance.actual', '1000000000000000000')
+    })
+
+    it('should not store outputs when action has no name', async () => {
+      const action: Action = {
+        type: 'assert',
+        arguments: {
+          actual: '42',
+          eq: '42'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+
+      expect(context.setOutput).not.toHaveBeenCalled()
+    })
+
+    it('should not store outputs when action has custom output', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-custom',
+        arguments: {
+          actual: '42',
+          eq: '42'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map(), true)
+
+      // With hasCustomOutput=true, the .actual output should not be stored by the assert case
+      // (the custom output handling is done elsewhere in executeAction)
+      const setOutputCalls = (context.setOutput as jest.Mock).mock.calls
+      const actualOutputs = setOutputCalls.filter((c: any[]) => c[0].includes('.actual'))
+      expect(actualOutputs.length).toBe(0)
+    })
+
+    it('should fail when no comparator key is provided', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-no-comparator',
+        arguments: {
+          actual: '42'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert must have exactly one of/)
+    })
+
+    it('should fail when more than one comparator key is provided', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-multi-comparator',
+        arguments: {
+          actual: '42',
+          eq: '42',
+          gte: '1'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert must have exactly one comparator, but got: eq, gte/)
+    })
+
+    it('should resolve values from context variables', async () => {
+      // Mock the resolver to simulate template variable resolution
+      // returning the same value for both actual and expected
+      const mockResolver = {
+        resolve: jest.fn(async (value: any, ctx: any, scope: any) => {
+          if (typeof value === 'string' && value.startsWith('{{') && value.endsWith('}}')) {
+            return 'resolved-value'
+          }
+          if (value.type === 'basic-arithmetic') {
+            const [a, b] = value.arguments.values
+            if (value.arguments.operation === 'eq') {
+              return a === b
+            }
+          }
+          return value
+        })
+      }
+      ;(engine as any).resolver = mockResolver
+
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-context',
+        arguments: {
+          actual: '{{myValue}}',
+          eq: '{{myExpected}}'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+
+      // Both {{myValue}} and {{myExpected}} resolve to 'resolved-value', so eq returns true
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-context.actual', 'resolved-value')
+    })
+
+    it('should handle boolean values in eq comparison', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-bool',
+        arguments: {
+          actual: true,
+          eq: true
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-bool.actual', true)
+    })
+
+    it('should handle large number comparisons', async () => {
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-large',
+        arguments: {
+          actual: '115792089237316195423570985008687907853269984665640564039457584007913129639935',
+          gte: '10000000000000000000000000000000000000000000000000000000000000000000000000000'
+        }
+      }
+
+      await (engine as any).executePrimitive(action, context, new Map())
+      expect(context.setOutput).toHaveBeenCalledWith('test-assert-large.actual', '115792089237316195423570985008687907853269984665640564039457584007913129639935')
+    })
+
+    it('should describe call form as signature in error message', async () => {
+      const mockResolver = {
+        resolve: jest.fn(async (value: any, ctx: any, scope: any) => {
+          if (value.type === 'call') return 'wrong-address'
+          if (value.type === 'basic-arithmetic') return false
+          return value
+        })
+      }
+      ;(engine as any).resolver = mockResolver
+
+      const action: Action = {
+        type: 'assert',
+        name: 'test-assert-call-desc',
+        arguments: {
+          to: '0xProxy',
+          signature: 'getOwner() returns (address)',
+          eq: '0xCorrectOwner'
+        }
+      }
+
+      await expect(
+        (engine as any).executePrimitive(action, context, new Map())
+      ).rejects.toThrow(/assert failed.*getOwner\(\) returns \(address\)/)
+    })
+  })
+})