@biconomy/ecosystem

@biconomy/ecosystem: Local Multichain Testing, Supercharged 🚀

@biconomy/ecosystem provides a robust, developer-friendly solution to deploy fully-featured local testing environments with Anvil chains, ERC-4337 bundlers, and Biconomy's Modular Execution Environment (MEE) Node in seconds. It's designed to dramatically boost productivity and enable comprehensive, reliable testing for AbstractJS projects and other Web3 applications, eliminating common frictions like testnet faucet hunting and CI/CD flakiness.

Important Architecture Note: The package deploys a single MEE Node instance on port 3000, which is designed to handle multiple Anvil chains simultaneously. This is an intentional design choice - you cannot and should not deploy multiple MEE Nodes. Instead, the single node efficiently manages all your test chains through a unified interface.

Prerequisites ⚠️

Docker is REQUIRED - This package relies on Docker to run the MEE Node:

• Docker must be installed and running on your machine
• Docker Compose V2 must be available
• Docker daemon must be running before using this package
• Port 3000 must be available (used by MEE Node)

If you don't have Docker installed:

• Install Docker Desktop (Mac/Windows)
• Or Install Docker Engine (Linux)

Core Features & Advantages ✨

• 🚀 Unified MEE Node Architecture: A single MEE Node instance (running on port 3000) manages multiple Anvil chains efficiently, providing a centralized point of control for your test environment
• 🔄 Multi-Chain Support: Deploy and manage multiple Anvil chains simultaneously, all connected to the same MEE Node instance
• 🌍 Realistic Network Forking: Test against real-world contract states by easily forking any EVM-compatible mainnet or testnet (e.g., Ethereum, Polygon, Base Sepolia).
• ⏱️ Full Time Control: Simulate the passage of time with block manipulation features inherent in Anvil, perfect for testing time-locked logic.
• 💰 Effortless Token & Account Management: Programmatically deal ERC20 tokens and manage pre-funded accounts on your local chains, bypassing unreliable public faucets.
• 🔄 Isolated & Predictable Environments: Achieve true test isolation with fresh, stateless Anvil instances. Enjoy reliable, near-instant transactions without public testnet gas puzzles or nonce collisions.
• 🛠️ Enhanced Debugging & CI/CD Ready: A cornerstone for robust CI/CD pipelines. Utilize account impersonation and replicate production bugs by forking exact states.
• 🛡️ Secure & Cost-Free: Test thoroughly without exposing real private keys or incurring transaction costs.

Installation

npm install @biconomy/ecosystem
# or
yarn add @biconomy/ecosystem
# or
bun add @biconomy/ecosystem

Usage

@biconomy/ecosystem is designed for programmatic use within your test scripts or automation tools. The primary way to use it involves setting up a local, forked environment for realistic testing.

Deploying a Local MEE Ecosystem

import { toEcosystem } from '@biconomy/ecosystem';
import type { Ecosystem } from '@biconomy/ecosystem';

async function main() {
  const forkUrl = "https://base-sepolia.g.alchemy.com/v2/EX-Rh8dvlZU3i-WJlp9gpK17PjzOWRlL";

  let ecosystem: Ecosystem | undefined;
  try {
    // Deploy a local ecosystem with 2 chains and MEE Node
    ecosystem = await toEcosystem({ 
      chainLength: 2,
      forkUrl,
      withMee: true // Enable MEE Node (disabled by default)
    });
    
    if (ecosystem.meeNode) {
      console.log('MEE Node deployed successfully');
    }
    
    ecosystem.infras.forEach((infra, index) => {
      console.log(`Chain ${index + 1} RPC: ${infra.network.rpcUrl}`);
      console.log(`Chain ${index + 1} Bundler: ${infra.bundler.url}`);
    });
    
    // Your tests and interactions here...
    
  } catch (error) {
    console.error("Error during ecosystem setup:", error);
  }
}

main().catch(console.error);

Testing Utilities

The package provides powerful testing utilities to make your test suite robust and easy to write:

Test Client & Token Dealing

import { createTestClient } from 'viem'
import { dealActions } from 'viem-deal'
import { http } from 'viem'

// Create a test client with dealing capabilities
const testClient = createTestClient({
  mode: "anvil",
  account: account,
  transport: http(rpcUrl)
}).extend(dealActions)

// Deal ERC20 tokens to accounts for testing
await testClient.deal({
  erc20: "0x036cbd53842c5426634e7929541ec2318f3dcf7e", // token address
  account: "0x...", // recipient address
  amount: 1000000000n // amount in wei
})

// Deal native tokens (ETH)
await testClient.setBalance({
  address: accountAddress,
  value: parseEther("1")
})

Test Setup Pattern

The package provides a clean way to set up test environments:

import { inject, describe, it, beforeAll } from 'vitest'

// Inject MEE Node configuration from setup
const { url, chains, rpcs, bundlers } = inject("meeNode")

describe("Your test suite", () => {
  // Use specific chains for this test file to avoid nonce conflicts
  const chain = chains[0]  // Use unique chain index per test file
  const rpc = rpcs[0]
  const bundler = bundlers[0]

  beforeAll(async () => {
    // Setup your test environment
    // Each test file should use different chain indices to avoid conflicts
  })

  it("should run your test", async () => {
    // Your test code here
  })
})

Best Practices

• Use a different chain for each test file to avoid nonce/state conflicts
• Leverage the dealing functionality to set up token balances
• Use the test client for local chain interactions
• Take advantage of the bundler's mock mode for testing: mock: true

API Reference

toEcosystem(parameters?)

Deploys a local testing ecosystem.

Parameters

• chainLength (optional): number - Number of local Anvil chains to deploy (default: 1)
• forkUrl (optional): string - HTTP RPC URL of an EVM network to fork. If provided, this will be used for each chain
• withMee (optional): boolean - Whether to deploy the MEE Node (default: false)

Returns

A Promise<Ecosystem> object:

• meeNode: MeeNode | undefined - The deployed MEE Node instance (undefined if withMee: false)

  • Contains configuration and connection details for the MEE Node

• infras: Infra[] - Array of infrastructure objects for each chain

  • network: Network details
    • rpcUrl: string - RPC URL for this chain
    • chain: Chain configuration object
  • bundler: Bundler details
    • url: string - URL for this chain's bundler

• clients: Clients[] - Array of Viem client instances configured for each chain

Running Examples

• Ensure Docker is installed and running (see Prerequisites section)
• Install dependencies: bun install
• Execute example scripts: bun run your-example-script.ts

Troubleshooting

• Port 3000 Usage:

  • The MEE Node MUST run on port 3000 - this is a core architectural requirement
  • Only one MEE Node instance can run at a time in your local environment
  • This is by design - a single MEE Node efficiently handles multiple Anvil chains
  • If port 3000 is in use, you must stop any existing MEE Node or other services using this port

• Docker Issues:

  • Ensure Docker is installed and running
  • Check that Docker Compose V2 is available
  • Verify Docker has permissions to create and manage containers

• Template Files Missing:

  • If you see "Template files not found" errors, ensure you've run the build process (bun run build)
  • The build process should copy necessary chain configuration files to dist/templates/chains-testnet/

• RPC Connection Issues:

  • If using a fork URL, ensure it's accessible and has sufficient rate limits
  • For Alchemy or other API providers, verify your API key is valid
  • Check your network connection if using external RPCs

• PRIVATE_KEY Warnings:

  • These warnings are informational and won't prevent basic functionality
  • If needed for specific features, set the PRIVATE_KEY environment variable

Contributing

Contributions are welcome! Please refer to the project's repository.

License

MIT