feat: Adding Local node using Anvil (#594)

* chore: Add simple storage contract

* chore: Create client for integration tests

* chore: Add registry parsing

* chore: Add registry

* chore: Add mod file

* chore: Add integration mod

* feat: Add network tags and readiness validation

* chore: Apply fmt

* feat: Add network selection utils for integration tests

* chore: Use openzeppelin_relayer package

* feat: Create confirmation receipt helper

* feat: Implement basic transfer

* feat: Implement common api tests

* fix: Resolve relayer test race conditions with cleanup and serialization

* refactor: Clean up integration tests and extract EVM helpers

* feat: Add integration testing Docker setup and reorganize contracts

* chore: clean up broadcast logs and vendor dependencies in test fixtures

* chore: remove git submodules for vendor dependencies

* chore: Add integration test key

* fix: Update .env.integration.example with defaults

* chore: Moving TESTING.md file to README

* fix: Ignoring signer files

* fix: CodeRabbit suggestion

* fix: CodeRabbit suggestion

* fix: Improving logs for test cases

* fix: Docker fixes

* chore: Adding base sepolia

* fix: Fixing CI

* fix: Fixing test case

* fix: Splitting tests in different jobs

* fix: Fixing tests

* fix: Fixing CI report

* fix: Applying review suggestions

* chore: Adding feature flags for running tests

* chore: Adding job for integration tests

* chore: Adding aws kms key logic

* fix: Removing unnecessary test files

* fix: Improvements

* chore: Config files and readme improvements

* chore: Fix integration test workflow

* fix: Removing unused code

* fix: Settings for connecting to aws from actions

* fix: Fixing account id

* fix: Fixing actions

* fix: Fixing GH actions

* fix: Fixing actions

* fix: Fixing secrets

* fix: Fixing GH secrets

* fix: Fixing actions

* fix: Fixing error

* fix: Fixing docker compose

* fix: API_KEY improvements

* chore: Codecov fix

* chore: Fix integratio test yaml file

* fix: Improving registry logic to be branch agnostic

* fix: Creating configs files

* fix: Fixing workflow

* fix: Fixing config example

* fix: Re-organizing folder structure

* fix: Fixing config files

* fix: Removing tags and fixing workflow

* feat: Adding basic tests for apis

* fix: Trigger tests manually

* feat: Adding local node with Anvil

* fix: Improvements

* chore: Renaming file

* fix: Fixing integration test workflow

* fix: Fix CI workflow

* fix: Coderabbit suggestions

* fix: Improvements

* fix: Fix workflow

* fix: Fix codecov

* chore: Improving anvil local script

* chore: README improvements

* chore: README fix

* chore: README fix

* chore: Fix gitignore file

* refactor: Reading active relayers from API

* fix: Config files

* fix: Docker optimisation

* chore: Removing contract no longer needed

* fix: Applying suggestions

* fix: Fix workflow

* fix: Fix readme about anvil pk

* fix: Fix readme

* fix: Improvements

---------

Co-authored-by: Luis Urrutia <luis@urrutia.me>

Author: NicoMolinaOZ

.env.integration.example

@@ -1,23 +1,38 @@
 # Integration Test Environment Variables
 # Copy this file to .env.integration and fill in your values
 
+# ==============================================================================
+# Test Mode Configuration
+# ==============================================================================
+
+# MODE=local    # Use Anvil (default, no testnet funds needed)
+# MODE=testnet  # Use live testnets
+
 # ==============================================================================
 # Required Variables
 # ==============================================================================
 
 # API key for the relayer service
+# Local mode: any value works (e.g., "local-test-key")
+# Testnet mode: valid API key required
 API_KEY=your-api-key-here
 
 # Keystore passphrase for local signer
+# Local mode: empty (Anvil account has no passphrase)
+# Testnet mode: your keystore passphrase (not needed if using KMS)
 KEYSTORE_PASSPHRASE=your-keystore-passphrase-here
 
+# Use KMS signers instead of local keystore files
+# Set to "true" to skip keystore file checks in testnet mode
+# USE_KMS=true
+
 # Webhook signing key (can be any UUID)
 WEBHOOK_SIGNING_KEY=your-webhook-signing-key-here
 
 # ==============================================================================
 # Network Selection
 # ==============================================================================
-# Network selection is controlled via tests/integration/registry.json
+# Network selection is controlled via tests/integration/config/registry.json
 # Enable/disable networks by setting "enabled": true/false in registry.json
 
 # ==============================================================================

.github/workflows/integration-tests.yaml

@@ -28,23 +28,22 @@ jobs:
       - name: Create integration test config
         run: |
           cat > .env.integration << EOF
+          MODE=testnet
           API_KEY=${{ secrets.INTEGRATION_TESTS_API_KEY }}
           LOG_LEVEL=info
+          USE_KMS=true
           AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
           AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
           AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN}
           AWS_REGION=${{ vars.AWS_REGION_KMS_KEY }}
           EOF
-      - name: Create config files from examples
+      - name: Inject config files
+        env:
+          AWS_KMS_REGION: ${{ vars.AWS_REGION_KMS_KEY }}
+          AWS_KMS_KEY_ID: ${{ secrets.TESTNET_AWS_KMS_KEY_ID }}
         run: |
-          cp tests/integration/config/config.example.json tests/integration/config/config.json
-          cp tests/integration/config/registry.example.json tests/integration/config/registry.json
-      - name: Inject AWS KMS signer config
-        run: |
-          jq --arg region "${{ vars.AWS_REGION_KMS_KEY }}" \
-             --arg key_id "${{ secrets.TESTNET_AWS_KMS_KEY_ID }}" \
-             '.signers = [{"id": "local-signer", "type": "aws_kms", "config": {"region": $region, "key_id": $key_id}}]' \
-             tests/integration/config/config.json > tests/integration/config/config.tmp.json && \
-          mv tests/integration/config/config.tmp.json tests/integration/config/config.json
+          mkdir -p tests/integration/config/testnet
+          echo '${{ vars.INTEGRATION_CONFIG_JSON }}' | envsubst > tests/integration/config/testnet/config.json
+          echo '${{ vars.INTEGRATION_REGISTRY_JSON }}' > tests/integration/config/testnet/registry.json
       - name: Run Integration Tests
         run: ./scripts/run-integration-docker.sh

.gitignore

@@ -30,6 +30,16 @@ tests/integration/config/keys/*.json
 tests/integration/config/config.json
 tests/integration/config/registry.json
 
+# Local Anvil keystore
+tests/integration/config/local/keys/*.json
+!tests/integration/config/local/keys/.gitkeep
+
+# Standalone config (auto-generated)
+tests/integration/config/local-standalone/
+
+# Testnet configs
+tests/integration/config/testnet/
+
 !examples/**/*.json
 
 

Dockerfile.integration

@@ -19,17 +19,10 @@ WORKDIR /app
 # Copy manifests
 COPY Cargo.toml Cargo.lock ./
 
-# Create dummy source to cache dependencies
-RUN mkdir -p src/bin tests/integration && \
-    echo "fn main() {}" > src/bin/dummy.rs && \
-    echo "#[test] fn dummy() {}" > tests/integration.rs
-
-# Build dependencies (this layer will be cached)
+# Fetch dependencies (this layer will be cached)
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
-    --mount=type=cache,target=/app/target \
-    cargo build --features integration-tests --test integration --release 2>/dev/null || true && \
-    rm -rf src tests
+    cargo fetch --locked
 
 # Copy actual source
 COPY src ./src

Makefile.toml

@@ -16,3 +16,46 @@ script = [
   "chmod +x ./scripts/docker_compose.sh",
   "./scripts/docker_compose.sh down"
 ]
+
+[tasks.integration-test-local]
+description = "Run integration tests against local standalone Anvil"
+env = { "TEST_REGISTRY_PATH" = "tests/integration/config/local-standalone/registry.json" }
+command = "cargo"
+args = ["test", "--features", "integration-tests", "--test", "integration"]
+
+[tasks.integration-test-standalone]
+description = "Start Anvil if needed, check relayer, then run integration tests"
+script = '''
+#!/bin/bash
+set -e
+
+# Check if Anvil is running, start if not
+if ! docker ps --format '{{.Names}}' | grep -q "^standalone-anvil$"; then
+    echo "🔧 Anvil not running, starting it..."
+    ./scripts/anvil-local.sh start
+    echo ""
+fi
+
+# Load API_KEY from .env if it exists
+if [ -f .env ]; then
+    export $(grep -v '^#' .env | grep API_KEY | xargs)
+fi
+
+# Check if relayer is running (health endpoint)
+if ! curl -s -f -H "Authorization: Bearer ${API_KEY}" http://localhost:8080/api/v1/health > /dev/null 2>&1; then
+    echo "❌ Relayer not running!"
+    echo ""
+    echo "Please start the relayer in another terminal:"
+    echo "    cargo run"
+    echo ""
+    echo "Then re-run: cargo make integration-test-standalone"
+    exit 1
+fi
+
+echo "✅ Anvil running, relayer healthy. Running tests..."
+echo ""
+
+# Run tests
+TEST_REGISTRY_PATH=tests/integration/config/local-standalone/registry.json \
+    cargo test --features integration-tests --test integration
+'''

config/networks/local-anvil-docker.json

@@ -0,0 +1,16 @@
+{
+  "networks": [
+    {
+      "type": "evm",
+      "network": "localhost-anvil-docker",
+      "chain_id": 31337,
+      "required_confirmations": 1,
+      "symbol": "ETH",
+      "rpc_urls": ["http://anvil:8545"],
+      "explorer_urls": [],
+      "average_blocktime_ms": 1000,
+      "is_testnet": true,
+      "features": ["eip1559"]
+    }
+  ]
+}

config/networks/local-anvil.json

@@ -0,0 +1,16 @@
+{
+  "networks": [
+    {
+      "type": "evm",
+      "network": "localhost-anvil",
+      "chain_id": 31337,
+      "required_confirmations": 1,
+      "symbol": "ETH",
+      "rpc_urls": ["http://localhost:8545"],
+      "explorer_urls": [],
+      "average_blocktime_ms": 1000,
+      "is_testnet": true,
+      "features": ["eip1559"]
+    }
+  ]
+}

docker-compose.integration.yml

@@ -16,6 +16,33 @@ services:
       timeout: 2s
       retries: 5
       start_period: 5s
+  anvil:
+    profiles:
+      - local
+    image: ghcr.io/foundry-rs/foundry:stable
+    container_name: integration-anvil
+    entrypoint: ''
+    command:
+      - sh
+      - -c
+      - anvil --host 0.0.0.0 --chain-id 31337 --block-time 1
+    ports:
+      - 0.0.0.0:8545:8545
+    networks:
+      - integration
+    volumes:
+      - ./tests/integration/contracts:/contracts:ro
+    healthcheck:
+      test:
+        - CMD
+        - cast
+        - client
+        - --rpc-url
+        - http://localhost:8545
+      interval: 2s
+      timeout: 2s
+      retries: 10
+      start_period: 3s
   relayer:
     build:
       context: .
@@ -24,6 +51,9 @@ services:
     depends_on:
       redis:
         condition: service_healthy
+      anvil:
+        condition: service_healthy
+        required: false  # Only when local profile is active, but we handle startup order in script
     ports:
       - 8080:8080
     networks:
@@ -37,7 +67,7 @@ services:
       # This filters out verbose OpenTelemetry traces
       - RUST_LOG=warn,openzeppelin_relayer=warn,actix_web=warn,tracing_actix_web=error
     volumes:
-      - ./tests/integration/config:/app/config:ro
+      - ${CONFIG_SOURCE:-./tests/integration/config/local}:/app/config:ro
       - ./config/networks:/app/networks:ro
     healthcheck:
       test:
@@ -66,6 +96,8 @@ services:
       # Test logging configuration
       # Default to INFO level for clean output, can be overridden with RUST_LOG
       - RUST_LOG=${RUST_LOG:-info}
+      # Test registry path (tests discover relayers via API)
+      - TEST_REGISTRY_PATH=${TEST_REGISTRY_PATH:-tests/integration/config/registry.json}
     volumes:
       - ./tests/integration/config:/app/config:ro
       - ./config/networks:/app/networks:ro