Tenderly Virtual TestNet CI/CD

[dzimiks]

Description

The Tenderly/vnet-github-action automates provisioning of Virtual TestNets for smart contract CI/CD pipelines. Virtual TestNets are testing and staging infrastructure with built Mainnet State Sync, Unlimited Faucet, Debugger, and Public Block Explorer.

This action creates a new Virtual TestNet from your configuration and exposes its RPC URLs through environment variables, enabling automated testing and staging environments for Uniswap protocol.

This action enables:

• Continuous Integration with Hardhat: Run your Hardhat tests against a forked network and use the Tenderly debugger and Simulator to fix issues
• Protocol Staging with Hardhat and Foundry: Deploy and stage your protocols in an isolated, mainnet-like environment
• Contract Staging with Hardhat and Foundry: Use dedicated Virtual TestNets as staging environments for contract development

Quick Setup

Step 1: Configure GitHub Action

These are the different inputs that can be configured:

The example below will deploy Smart Contracts to Tenderly Virtual TestNet on ETH Mainnet network.

name: Deploy to Tenderly Virtual TestNet
on: [pull_request]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Tenderly Virtual TestNet
        uses: Tenderly/[email protected]
        with:
          access_key: ${{ secrets.TENDERLY_ACCESS_KEY }}
          project_name: ${{ vars.TENDERLY_PROJECT_SLUG }}
          account_name: ${{ vars.TENDERLY_ACCOUNT_SLUG }}
          testnet_name: 'Uniswap VNet CI/CD ${{ github.run_id }}'
          mode: 'CD'
          network_id: 1
          chain_id: 1
          block_number: 'latest'
          public_explorer: true
          verification_visibility: 'src'
          state_sync: false

Step 2: Set Your Secrets

GitHub Secrets (Settings → Secrets and variables → Actions → New repository secret):

• TENDERLY_ACCESS_KEY

  • Your Tenderly API access key for authentication
  • Generate at: https://dashboard.tenderly.co/account/authorization

• PRIVATE_KEY

  • Wallet private key for contract deployments
  • Don't use your main wallet - create a dedicated deployment wallet

• ETHERSCAN_API_KEY

  • Required for contract verification
  • Get from: https://etherscan.io/myapikey

GitHub Variables (Settings → Secrets and variables → Actions → Variables → New repository variable):

• TENDERLY_PROJECT_SLUG

  • Your Tenderly project identifier
  • Get from: https://docs.tenderly.co/account/projects/account-project-slug

• TENDERLY_ACCOUNT_SLUG

  • Your Tenderly account name
  • Get from: https://docs.tenderly.co/account/projects/account-project-slug

• ADMIN_WALLET

  • Ethereum address for contract ownership
  • Address that will own deployed contracts

This code example will fund your deployment wallet address with 1000 ETH and deploy the contracts using Deploy-all.s.sol Foundry script:

      - name: Fund Account
        env:
          TENDERLY_ADMIN_RPC_URL: ${{ env.TENDERLY_ADMIN_RPC_URL }}
          ADMIN_WALLET: ${{ vars.ADMIN_WALLET }}
        run: |
          curl $TENDERLY_ADMIN_RPC_URL \
            -X POST \
            -H "Content-Type: application/json" \
            -d '{
              "jsonrpc": "2.0",
              "method": "tenderly_setBalance",
              "params": [
                "${{ vars.ADMIN_WALLET }}",
                "0x3635c9adc5dea00000"
              ],
              "id": "1234"
            }'

      - name: Install Foundry
        uses: foundry-rs/foundry-toolchain@v1

      - name: Foundry Build
        run: |
          forge --version
          forge build --sizes

      - name: Deploy Contracts
        env:
          ETHERSCAN_API_KEY: ${{ secrets.ETHERSCAN_API_KEY }}
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
          FOUNDRY_ETH_RPC_URL: ${{ env.TENDERLY_PUBLIC_RPC_URL }}
          FOUNDRY_VERIFIER_URL: ${{ env.TENDERLY_FOUNDRY_VERIFICATION_URL }}
        run: |
          forge script script/deploy/Deploy-all.s.sol \
            --private-key $PRIVATE_KEY \
            --rpc-url $FOUNDRY_ETH_RPC_URL \
            --verifier-url $FOUNDRY_VERIFIER_URL \
            --slow \
            --broadcast \
            --verify

How Has This Been Tested?

Here's a concise setup overview for testing:

Prerequisites

1. Tenderly Account:

• Sign up at https://dashboard.tenderly.co/register
• Create a new project
• Generate access key

2. GitHub Setup:

Secrets (Settings → Secrets → Actions):
- TENDERLY_ACCESS_KEY        // From Tenderly dashboard
- PRIVATE_KEY               // Deploy wallet private key
- ETHERSCAN_API_KEY        // For contract verification

Variables (Settings → Variables → Actions):
- TENDERLY_PROJECT_SLUG     // From Tenderly URL
- TENDERLY_ACCOUNT_SLUG     // Your Tenderly username
- ADMIN_WALLET             // Deploy wallet address

Testing Process

Tests run automatically on PR creation:

1. Creates isolated Virtual TestNet environment
2. Funds test wallet with ETH
3. Deploys contracts
4. Verifies contract code

You can track test runs:

• GitHub Actions tab
• Tenderly Dashboard
• VNet Block Explorer

Multi-Network Testing

Need help? Drop an issue or check Tenderly Virtual TestNet Docs.

Checklist:

Before deployment

• 100% test and branch coverage
• check slither for severe issues
• fuzz and invariant tests (when applicable)
• formal verification (when applicable)
• deployment or upgrade scripts ready

After deployment

• transfer ownership after deployments (when applicable)
• complete upgrade (when applicable)
• generate deployment/upgrade log files

---

Considerations

• I have followed the contributing guidelines.
• My code follows the style guidelines of this project and I have run forge fmt and prettier to ensure the code style is valid
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional context

Add any other context about the pull request here.

[dzimiks]

@gretzke Here's the Tenderly Virtual TestNet GitHub Action workflow! I've tested it with a fork of Uniswap contracts (see example runs here: https://github.com/dzimiks/uniswap-contracts/actions).

The workflow is flexible - it's using ETH Mainnet (chain_id: 1) but you can customize it for your setup. You can find more details in the official docs.

Let me know if you need any help or have questions about customizing it for your needs! 🙌

[dzimiks]

@gretzke Here's the Tenderly Virtual TestNet GitHub Action workflow! I've tested it with a fork of Uniswap contracts (see example runs here: https://github.com/dzimiks/uniswap-contracts/actions).

The workflow is flexible - it's using ETH Mainnet (chain_id: 1) but you can customize it for your setup. You can find more details in the official docs.

Let me know if you need any help or have questions about customizing it for your needs! 🙌

Use matrix strategy to test your contracts across multiple networks in parallel. This is particularly useful for protocols that deploy across multiple chains and need to ensure consistent behavior. More info here: https://github.com/Tenderly/vnet-github-action?tab=readme-ov-file#advanced-configuration.

jobs:
  test:
    strategy:
      matrix:
        network: ['1', '137', '42161']  # Ethereum, Polygon, Arbitrum
    steps:
      - uses: Tenderly/[email protected]
        with:
          network_id: ${{ matrix.network }}
          chain_id: ${{ format('7357{0}', matrix.network) }}

[gretzke]

@dzimiks does this also handle EVMs that behave abnormally like zksync?

[dzimiks]

@dzimiks does this also handle EVMs that behave abnormally like zksync?

Hey @gretzke! Could you explain more about what you mean by that?

Just so you know - we support a wide range of networks including ETH, Polygon, Arbitrum, Optimism, Base, and others (full list here: https://docs.tenderly.co/supported-networks) and we're adding new ones almost weekly.

Our VNet's advanced config lets you customize chain behavior and handle various EVM quirks. Super interested to hear what specific behaviors you're looking to test!