@0xsequence/catapult 1.3.1 → 1.3.3

package/src/lib/core/engine.ts

@@ -8,6 +8,13 @@ import { createDefaultVerificationRegistry, VerificationPlatformRegistry } from
 import { BuildInfo } from '../types/buildinfo'
 import { ethers } from 'ethers'
 
+export type EngineOptions = {
+  eventEmitter?: DeploymentEventEmitter
+  verificationRegistry?: VerificationPlatformRegistry
+  noPostCheckConditions?: boolean
+  allowMultipleNicksMethodTests?: boolean
+}
+
 /**
  * The ExecutionEngine is the core component that runs jobs and their actions.
  * It interprets the declarative YAML files, resolves values, interacts with the
@@ -19,13 +26,16 @@ export class ExecutionEngine {
   private readonly events: DeploymentEventEmitter
   private readonly verificationRegistry: VerificationPlatformRegistry
   private readonly noPostCheckConditions: boolean
+  private readonly allowMultipleNicksMethodTests: boolean
+  private nicksMethodTested: boolean = false
 
-  constructor(templates: Map<string, Template>, eventEmitter?: DeploymentEventEmitter, verificationRegistry?: VerificationPlatformRegistry, noPostCheckConditions?: boolean) {
+  constructor(templates: Map<string, Template>, options?: EngineOptions) {
     this.resolver = new ValueResolver()
     this.templates = templates
-    this.events = eventEmitter || deploymentEvents
-    this.verificationRegistry = verificationRegistry || createDefaultVerificationRegistry()
-    this.noPostCheckConditions = noPostCheckConditions ?? false
+    this.events = options?.eventEmitter || deploymentEvents
+    this.verificationRegistry = options?.verificationRegistry || createDefaultVerificationRegistry()
+    this.noPostCheckConditions = options?.noPostCheckConditions ?? false
+    this.allowMultipleNicksMethodTests = options?.allowMultipleNicksMethodTests ?? false
   }
 
   /**
@@ -781,6 +791,18 @@ export class ExecutionEngine {
         break
       }
       case 'test-nicks-method': {
+        if (this.nicksMethodTested && !this.allowMultipleNicksMethodTests) {
+          try {
+            if (context.getOutput(`${action.name}.success`) === true) {
+              // Return previous result
+              break
+            }
+          } catch (e) {
+            throw new Error(`Nick's method test already performed this run`)
+          }
+        }
+        this.nicksMethodTested = true
+
         // Default bytecode if none provided
         const defaultBytecode = '0x608060405234801561001057600080fd5b5061013d806100206000396000f3fe60806040526004361061001e5760003560e01c80639c4ae2d014610023575b600080fd5b6100cb6004803603604081101561003957600080fd5b81019060208101813564010000000081111561005457600080fd5b82018360208201111561006657600080fd5b8035906020019184600183028401116401000000008311171561008857600080fd5b91908080601f01602080910402602001604051908101604052809392919081815260200183838082843760009201919091525092955050913592506100cd915050565b005b60008183516020850134f56040805173ffffffffffffffffffffffffffffffffffffffff83168152905191925081900360200190a050505056fea264697066735822122033609f614f03931b92d88c309d698449bb77efcd517328d341fa4f923c5d8c7964736f6c63430007060033'
         
@@ -1104,9 +1126,76 @@ export class ExecutionEngine {
       
       // Generate a valid ECDSA signature using Nick's method approach
       const result = await this.generateNicksMethodTransaction(bytecode, defaultGasPrice, defaultGasLimit)
-      const rawTx = result.rawTx
+      const {signedTx, unsignedTx} = result
       eoaAddress = result.eoaAddress
       wallet = result.wallet
+
+      // Simulate the contract creation transaction
+      try {
+        const simulationTx = {
+          ...unsignedTx,
+          from: eoaAddress,
+        };
+
+        if (unsignedTx.gasPrice) {
+          // Check gas price
+          const gasPrice = await context.provider.getFeeData().then(data => data.gasPrice)
+          if (!gasPrice) {
+            this.events.emitEvent({
+              type: "debug_info",
+              level: "debug",
+              data: {
+                message: `Legacy gas price not available.`,
+              },
+            });
+          } else if (BigInt(unsignedTx.gasPrice.toString()) < gasPrice) {
+            this.events.emitEvent({
+              type: "debug_info",
+              level: "warn",
+              data: {
+                message: `Gas price (${unsignedTx.gasPrice}) is lower than the current gas price (${gasPrice}). This may cause the transaction to not be mined.`,
+              },
+            });
+          }
+        }
+
+        if (simulationTx.gasLimit) {
+          // Simulate the transaction expected gas usage
+          const estimatedGas = await context.provider.estimateGas(simulationTx);
+          const estimatedGasStr = estimatedGas.toString();
+          const simulationTxGasLimitStr = simulationTx.gasLimit.toString();
+          if (estimatedGas > BigInt(simulationTxGasLimitStr)) {
+            this.events.emitEvent({
+              type: "debug_info",
+              level: "warn",
+              data: {
+                message: `Estimated gas (${estimatedGasStr}) is greater than gas provided in the transaction (${simulationTxGasLimitStr}). This may cause the transaction to revert.`,
+              },
+            });
+          } else {
+            this.events.emitEvent({
+              type: "debug_info",
+              level: "debug",
+              data: {
+                message: `Estimated gas: ${estimatedGasStr}, Gas provided: ${simulationTxGasLimitStr}`,
+              },
+            });
+          }
+        }
+      } catch (simulationError) {
+        this.events.emitEvent({
+          type: "debug_info",
+          level: "warn",
+          data: {
+            message: `Simulation failed: ${
+              simulationError instanceof Error
+                ? simulationError.message
+                : String(simulationError)
+            }`,
+          },
+        });
+        // Continue with the test even if simulation fails
+      }
       
       this.events.emitEvent({
         type: 'debug_info',
@@ -1199,11 +1288,11 @@ export class ExecutionEngine {
         type: 'debug_info',
         level: 'debug',
         data: {
-          message: `[NICK'S METHOD DEBUG] Broadcasting Nick's method transaction. RawTx: ${rawTx.substring(0, 100)}...`
+          message: `[NICK'S METHOD DEBUG] Broadcasting Nick's method transaction. RawTx: ${signedTx.substring(0, 100)}...`
         }
       })
       
-      const deployTx = await context.provider.broadcastTransaction(rawTx)
+      const deployTx = await context.provider.broadcastTransaction(signedTx)
       
       this.events.emitEvent({
         type: 'debug_info',
@@ -1300,7 +1389,7 @@ export class ExecutionEngine {
     bytecode: string,
     gasPrice: ethers.BigNumberish,
     gasLimit: ethers.BigNumberish
-  ): Promise<{ rawTx: string; eoaAddress: string; wallet: ethers.HDNodeWallet }> {
+  ): Promise<{ unsignedTx: ethers.TransactionRequest; signedTx: string; eoaAddress: string; wallet: ethers.HDNodeWallet }> {
     // Generate a random private key for the test
     const wallet = ethers.Wallet.createRandom()
     
@@ -1324,9 +1413,10 @@ export class ExecutionEngine {
     const eoaAddress = parsedTx.from!
     
     return {
-      rawTx: signedTx,
-      eoaAddress: eoaAddress,
-      wallet: wallet
+      unsignedTx,
+      signedTx,
+      eoaAddress,
+      wallet,
     }
   }
 
@@ -1350,9 +1440,26 @@ export class ExecutionEngine {
     const connectedWallet = wallet.connect(context.provider)
     
     // Estimate gas for a simple transfer
-    const gasPrice = await context.provider.getFeeData().then(data => data.gasPrice || ethers.parseUnits('20', 'gwei'))
+    const feeData = await context.provider.getFeeData()
+    const txGas = feeData.maxFeePerGas ? {
+      maxFeePerGas: feeData.maxFeePerGas,
+      maxPriorityFeePerGas: feeData.maxPriorityFeePerGas || ethers.parseUnits('20', 'gwei')
+    } : {
+      gasPrice: feeData.gasPrice || undefined,
+    }
+    const effectiveGasPrice = txGas.maxFeePerGas || txGas.gasPrice
+    if (!effectiveGasPrice) {
+      this.events.emitEvent({
+        type: 'action_failed',
+        level: 'error',
+        data: {
+          message: `No gas price available`
+        }
+      })
+      return
+    }
     const gasLimit = 21000n // Standard gas limit for ETH transfer
-    const gasCost = BigInt(gasPrice.toString()) * gasLimit
+    const gasCost = effectiveGasPrice * gasLimit
     
     // Check if we have enough balance to cover gas costs
     if (remainingBalance <= gasCost) {
@@ -1384,8 +1491,8 @@ export class ExecutionEngine {
     const returnTx = await connectedWallet.sendTransaction({
       to: await (await context.getResolvedSigner()).getAddress(),
       value: amountToSend,
-      gasPrice: gasPrice,
-      gasLimit: gasLimit
+      gasLimit: gasLimit,
+      ...txGas,
     })
     
     await returnTx.wait()

package/src/lib/deployer.ts

@@ -154,7 +154,11 @@ export class Deployer {
 
       // 4. Execute the plan.
       const verificationRegistry = createDefaultVerificationRegistry(this.options.etherscanApiKey)
-      const engine = new ExecutionEngine(this.loader.templates, this.events, verificationRegistry, this.noPostCheckConditions)
+      const engine = new ExecutionEngine(this.loader.templates, {
+        eventEmitter: this.events,
+        verificationRegistry,
+        noPostCheckConditions: this.noPostCheckConditions
+      })
       
       // Track if any jobs have failed
       let hasFailures = false

package/src/lib/events/__tests__/event-system.spec.ts

@@ -11,7 +11,7 @@ describe('Event System', () => {
   beforeEach(() => {
     eventEmitter = new DeploymentEventEmitter()
     cliAdapter = new CLIEventAdapter(eventEmitter, 3)
-    
+
     // Mock console methods
     consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
     consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
@@ -339,5 +339,54 @@ describe('Event System', () => {
 
       expect(handler).not.toHaveBeenCalled()
     })
+
+    it('should respect debug_info event level for verbosity filtering', () => {
+      // Test with verbosity 0 (default) - should NOT show any debug_info events
+      cliAdapter.setVerbosity(0)
+
+      eventEmitter.emitEvent({
+        type: 'debug_info',
+        level: 'warn',
+        data: {
+          message: 'This warning should NOT be shown at verbosity 0'
+        }
+      })
+
+      expect(consoleLogSpy).not.toHaveBeenCalled()
+
+      // Clear previous calls
+      consoleLogSpy.mockClear()
+
+      // Test with verbosity 3 - should show warn level with correct formatting
+      cliAdapter.setVerbosity(3)
+
+      eventEmitter.emitEvent({
+        type: 'debug_info',
+        level: 'warn',
+        data: {
+          message: 'This warning should be shown at verbosity 3'
+        }
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('[WARN] This warning should be shown at verbosity 3')
+      )
+
+      // Clear previous calls
+      consoleLogSpy.mockClear()
+
+      // Test with verbosity 3 - should show debug level with correct formatting
+      eventEmitter.emitEvent({
+        type: 'debug_info',
+        level: 'debug',
+        data: {
+          message: 'This debug message should be shown at verbosity 3'
+        }
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('[DEBUG] This debug message should be shown at verbosity 3')
+      )
+    })
   })
-}) 
+})

package/src/lib/events/cli-adapter.ts

@@ -5,7 +5,7 @@ import { DeploymentEventEmitter } from './emitter'
 /**
  * Verbosity levels for filtering console output:
  * 0 (default): Critical info only - errors, warnings, main deployment steps
- * 1 (-v): Add transaction details and verification steps  
+ * 1 (-v): Add transaction details and verification steps
  * 2 (-vv): Add action details and file operations
  * 3 (-vvv): Full debug - show everything including template transitions
  */
@@ -81,7 +81,7 @@ export class CLIEventAdapter {
     if (level1Events.has(eventType)) return 1
     if (level2Events.has(eventType)) return 2
     if (level3Events.has(eventType)) return 3
-    
+
     // Default to level 3 for any new events we haven't categorized
     return 3
   }
@@ -314,7 +314,11 @@ export class CLIEventAdapter {
         break
 
       case 'debug_info':
-        console.log(chalk.gray(`        [DEBUG] ${event.data.message}`))
+        const levelPrefix = event.level.toUpperCase()
+        const levelColor = event.level === 'warn' ? chalk.yellow :
+                          event.level === 'info' ? chalk.blue :
+                          chalk.gray
+        console.log(levelColor(`        [${levelPrefix}] ${event.data.message}`))
         break
 
       default:
@@ -338,4 +342,4 @@ export class CLIEventAdapter {
   public destroy(): void {
     this.emitter.removeAllListeners()
   }
-} 
+}

package/src/lib/events/types.ts

@@ -147,7 +147,7 @@ export interface ActionInfoEvent extends BaseEvent {
 
 export interface DebugInfoEvent extends BaseEvent {
   type: 'debug_info'
-  level: 'debug'
+  level: 'debug' | 'info' | 'warn'
   data: {
     message: string
   }

package/src/lib/std/templates/assured-deployment.yaml

@@ -13,17 +13,18 @@
 # code before the call data, hence the wrapping pattern.
 name: "assured-deployment"
 type: "template"
+description: "Wraps a factory call with a CREATE that runs a minimal assurance program"
 
 arguments:
-  # The address that is expected to exist after the factory call (e.g., CREATE2 result)
   targetAddress:
     type: "address"
-  # The factory that will perform the deployment
+    description: "The address that is expected to exist after the factory call (e.g., CREATE2 result)"
   factoryAddress:
     type: "address"
-  # Encoded call to the factory (e.g., abi-encoded deploy(...))
+    description: "The factory that will perform the deployment"
   callData:
     type: "bytes"
+    description: "The encoded call to the factory (e.g., abi-encoded deploy(...))"
 
 actions:
   - type: "create-contract"

package/src/lib/std/templates/era-evm-predeploy.yaml

@@ -0,0 +1,35 @@
+# Calls the EVM predeploy manager to deploy preapproved contracts to ZK Era chains.
+# The ZKSync Era predeploy manager is 0x0000000000000000000000000000000000008014.
+# https://github.com/matter-labs/era-contracts/blob/540762151e3b030cac8ea274284b249f549e2c2a/system-contracts/contracts/EvmPredeploysManager.sol
+name: "era-evm-predeploy"
+type: "template"
+description: "Deploy an approved predeployed contract to the EVM"
+
+arguments:
+  evmPredeployManager:
+    type: "address"
+    description: "The address of the EVM predeploy manager"
+  address:
+    type: "address"
+    description: "The address of the predeployed contract to deploy"
+  bytecode:
+    type: "bytes"
+    description: "The deployment bytecode of the predeployed contract to deploy"
+
+skip_condition:
+  - type: "contract-exists"
+    arguments:
+      address: "{{address}}"
+
+actions:
+  - name: "deploy"
+    type: "send-transaction"
+    arguments:
+      to: "{{evmPredeployManager}}"
+      data:
+        type: "abi-encode"
+        arguments:
+          signature: "deployPredeployedContract(address,bytes)"
+          values:
+            - "{{address}}"
+            - "{{bytecode}}"

package/src/lib/std/templates/erc-2470.yaml

@@ -7,12 +7,15 @@ type: "template"
 arguments:
   creationCode:
     type: "bytes"
+    description: "The creation code of the contract to deploy"
   salt:
     type: "bytes32"
+    description: "The salt for deployment"
 
 returns:
   address:
     type: "address"
+    description: "The address of the deployed contract"
 
 setup:
   skip_condition:

package/src/lib/std/templates/min-balance.yaml

@@ -1,11 +1,14 @@
 name: "min-balance"
 type: "template"
+description: "Ensures a minimum balance for any given address"
 
 arguments:
   address:
     type: "address"
+    description: "The address to check the balance of"
   balance:
     type: "uint256"
+    description: "The minimum balance required"
 
 actions:
   - type: "send-transaction"

package/src/lib/std/templates/nano-universal-deployer.yaml

@@ -7,10 +7,12 @@ type: "template"
 arguments:
   creationCode:
     type: "bytes"
+    description: "The creation code of the contract to deploy"
 
 returns:
   address:
     type: "address"
+    description: "The address of the deployed contract"
 
 setup:
   skip_condition:

package/src/lib/std/templates/raw-erc-2470.yaml

@@ -4,12 +4,15 @@ type: "template"
 arguments:
   creationCode:
     type: "bytes"
+    description: "The creation code of the contract to deploy"
   salt:
     type: "bytes32"
+    description: "The salt for deployment"
 
 returns:
   address:
     type: "address"
+    description: "The address of the deployed contract"
 
 setup:
   skip_condition:

package/src/lib/std/templates/raw-nano-universal-deployer.yaml

@@ -1,13 +1,16 @@
 name: "raw-nano-universal-deployer"
 type: "template"
+description: "Deploy a contract using the Nano Universal Deployer"
 
 arguments:
   creationCode:
     type: "bytes"
+    description: "The creation code of the contract to deploy"
 
 returns:
   address:
     type: "address"
+    description: "The address of the deployed contract"
 
 setup:
   skip_condition:

package/src/lib/std/templates/raw-sequence-universal-deployer-2.yaml

@@ -1,15 +1,19 @@
 name: "raw-sequence-universal-deployer-2"
 type: "template"
+description: "Deploy a contract using the Sequence Universal Deployer v2"
 
 arguments:
   creationCode:
     type: "bytes"
+    description: "The creation code of the contract to deploy"
   salt:
     type: "bytes32"
+    description: "The salt for deployment"
 
 returns:
   address:
     type: "address"
+    description: "The address of the deployed contract"
 
 setup:
   - type: "nano-universal-deployer"

package/src/lib/std/templates/sequence-universal-deployer-2.yaml

@@ -3,16 +3,20 @@
 # fails to deploy. This ensures that the gas estimation is accurate and the transaction won't silently fail with out of gas.
 name: "sequence-universal-deployer-2"
 type: "template"
+description: "Deploy a contract using the Sequence Universal Deployer v2"
 
 arguments:
   creationCode:
     type: "bytes"
+    description: "The creation code of the contract to deploy"
   salt:
     type: "bytes32"
+    description: "The salt for deployment"
 
 returns:
   address:
     type: "address"
+    description: "The address of the deployed contract"
 
 setup:
   - type: "nano-universal-deployer"