E2E Testing Setup

Overview

This document describes the setup phase of end-to-end (E2E) testing for the vlayer system as implemented in the e2e-test.sh script. The setup phase initializes all necessary services, configurations, and components required for testing.

Key Components

1. Environment Configuration

The setup phase begins by configuring the environment:

# Environment variables setup
VLAYER_HOME=$(git rev-parse --show-toplevel)
export PATH="${VLAYER_HOME}/target/debug:${PATH}"

# Load environment variables
[ -f "${VLAYER_HOME}/.env.local" ] && source "${VLAYER_HOME}/.env.local"

# Set default values
VLAYER_ENV=${VLAYER_ENV:-dev}
BUILD_CLI=${BUILD_CLI:-1}

• VLAYER_HOME points to the root directory of the vlayer project
• Environment variables from .env.local are loaded if the file exists
• Default values are set for environment-specific configurations

2. Helper Scripts

The setup phase sources several helper scripts that provide utility functions:

source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
source "$(dirname "${BASH_SOURCE[0]}")/lib/examples.sh"
source "$(dirname "${BASH_SOURCE[0]}")/lib/proving_mode.sh"
source "$(dirname "${BASH_SOURCE[0]}")/lib/e2e.sh"
source "$(dirname "${BASH_SOURCE[0]}")/lib/build-packages.sh"

These scripts provide functions for the following stages of e2e testing:

1. Environment Setup:

   • set_proving_mode: Configures proving mode (dev/prod)
   • generate_ts_bindings: Generates TypeScript bindings for contracts
   • build_sdk: Builds the SDK package

2. Service Initialization:

   • ensure_services_built: Compiles the required service binaries (call_server, chain_server, worker, dns_server) if BUILD_SERVICES equals 1
   • startup_chain_worker: Starts chain worker processes
   • startup_chain_server: Starts the chain server for RPC communication
   • startup_vlayer: Starts the vlayer REST server
   • startup_vdns_server: Starts the DNS server
   • startup_chain_services: Coordinates starting all chain-related services
   • wait_for_port_and_pid: Waits for services to be ready on specific ports

   The service initialization follows a specific sequence: first ensure_services_built compiles all service binaries, then Docker services are started, followed by chain workers, chain server, vlayer server, and finally the DNS server.

3. Test Environment Preparation:

   • generate_vlayer_init_config: Creates configuration for vlayer initialization
   • ensure_cli_built: Ensures the CLI is built
   • init_template: Initializes the test template

4. Test Execution:

   • silent_unless_fails: Controls output of command execution
   • run_prover_script: Runs the prover script

5. Cleanup:

   • cleanup: Cleans up all services and temporary files
   • kill_service: Terminates specific services by PID

3. Proving Mode Configuration

set_proving_mode

The proving mode determines how proofs are generated and verified:

• dev mode uses fake proofs for faster testing
• prod mode uses production-grade proofs (Bonsai)

This configuration affects both the server and worker components:

• Sets SERVER_PROOF_ARG (fake/groth16)
• Sets WORKER_PROOF_ARG (fake/succinct)

4. TypeScript Bindings and SDK Generation

generate_ts_bindings
build_sdk

These steps ensure that:

• The TypeScript bindings for smart contracts are up-to-date
• The SDK is built with the latest changes

5. Service Startup

DOCKER_COMPOSE_SERVICES="anvil-l1 anvil-l2-op notary-server"
source ${VLAYER_HOME}/bash/run-services.sh

This starts the required services:

• anvil-l1: Local Ethereum L1 node
• anvil-l2-op: Local Optimism L2 node
• notary-server: Notary server

The service startup orchestrates:

1. Docker containers for blockchain nodes
2. Chain workers for precomputing chain proofs
3. Chain server for making chain proofs available over JSON-RPC
4. vlayer server for call proof generation

6. Chain Worker Configuration

Chain workers are configured based on the test environment:

• In devnet (Anvil), the worker connects to http://localhost:8545 with chain ID 31337
• In testnet, the worker connects to external RPC endpoints with their respective chain IDs

Workers are started with parameters:

RUST_LOG=${RUST_LOG:-info} ./target/debug/worker \
    --db-path "${db_path}" \
    --rpc-url "${rpc_url}" \
    --chain-id "${chain_id}" \
    --proof-mode "${WORKER_PROOF_ARG}" \
    --confirmations "${CONFIRMATIONS:-1}" \
    --max-head-blocks "${MAX_HEAD_BLOCKS:-10}" \
    --max-back-propagation-blocks "${MAX_BACK_PROPAGATION_BLOCKS:-10}"

7. Test Environment Preparation

cd $(mktemp -d)
generate_vlayer_init_config
ensure_cli_built
init_template

These steps:

1. Create a temporary directory for testing
2. Generate the vlayer initialization configuration (generate_vlayer_init_config)
3. Ensure the CLI tool is built (ensure_cli_built)
4. Initialize a test template with the example code (init_template)

Key Configurables

The following environment variables can be passed to the e2e-test.sh script to customize its behavior:

For prod mode with external chains, these additional variables are required:

Only one of QuickNode or Alchemy API key is required.

Optional Rollup (L2) Endpoint Overrides:

In the event the used chain endpoint does not support required L2 methods (optimism_outputAtBlock), an endpoint override is needed with an RPC provider that does support it.