Saga Simulation Tests

testing framework for simulating DeFi vault operations on the Saga chain using both Anvil (Ethereum fork) and TEVM (TypeScript EVM) implementations.

🚀 Overview

This project provides two different approaches to simulate vault rebalancing operations:

1. Anvil Simulation (anvilSimulation.ts) - Uses Ethereum forking via Anvil to simulate transactions on a local fork of the Saga chain
2. TEVM Simulation (tevmSimulation.ts) - Uses TEVM (TypeScript EVM) for lightweight, fast simulation without forking

🏗️ Architecture

src/
├── anvilSimulation.ts      # Anvil-based simulation using Ethereum forking
├── tevmSimulation.ts       # TEVM-based simulation using TypeScript EVM
├── index.ts                # Main entry point with test functions
├── test-runner.ts          # Test orchestration and reporting
├── utils/
│   ├── fork-manager/       # Anvil fork management utilities
│   │   ├── anvil-manager.ts # Anvil process and fork management
│   │   ├── fork-manager.ts  # Main fork management interface
│   │   └── port-manager.ts  # Port availability checking
│   ├── contract-abils.ts    # Contract ABIs for various protocols
│   ├── tevmUtils.ts         # TEVM client utilities
│   ├── TransactionDebugger.ts # Enhanced transaction debugging
│   └── types/               # TypeScript type definitions
└── viem-config/            # Viem chain configuration

📋 Prerequisites

System Requirements

• Node.js >= 18.0.0
• Yarn package manager
• Anvil CLI (for Anvil simulations)

Install Anvil CLI

# macOS (using Homebrew)
brew install foundry

# Or install directly
curl -L https://foundry.paradigm.xyz | bash
foundryup

Install Dependencies

yarn install

🧪 Testing Commands

Quick Test Commands

# Test TEVM simulation only
yarn test:tevm

# Test Anvil simulation only  
yarn test:anvil

# Test both simulations
yarn test:both

# Run all simulations (default)
yarn test:simulations

Advanced Test Commands

# Use the test runner for detailed reporting
yarn test:runner

# Run specific test via runner
yarn test:runner:tevm
yarn test:runner:anvil

# Run Jest tests
yarn test
yarn test:watch

Development Commands

# Build TypeScript
yarn build

# Run in development mode
yarn dev

# Linting
yarn lint
yarn lint:fix

🔧 Configuration

Chain Configuration

The project is configured for the Saga chain (Chain ID: 5464) by default.

// src/utils/consts.ts
export enum ChainId {
  Saga = 5464,
}

RPC Configuration

• Anvil: Uses local fork of Saga RPC at https://sagaevm-archive.jsonrpc.sagarpc.io
• TEVM: Uses TEVM's built-in chain simulation

📊 Test Data

Default Test Parameters

// Vault Address
const vaultAddress = "0x6bc03924746062aef6a6f0c9d4ff1fff1eee1986";

// Orchestrator Address  
const orchestratorAddress = "0xE49eC79eBA9A523e8350Eb3d427C92b4273ACf46";

// Steer Periphery Address
const steerPeripheryAddress = "0x0F71cFFAd6F80Ff440ba368231126104091747Ae";

// Liquidity Positions
const liquidityPositions = {
  lowerTick: [-207728],
  upperTick: [-188268], 
  relativeWeight: [100],
};

🚀 Running Tests

1. TEVM Simulation Test

yarn test:tevm

What it does:

• Creates a TEVM memory client
• Simulates vault operations without forking
• Executes tend operation on the vault
• Returns vault snapshot with fees and balances

Expected Output:

🚀 Starting Saga chain simulation test...
[5464] 🚀 Starting vault supply check...
[5464] 📬 Processing vaults in batches...
✅ TEVM Simulation completed successfully!
📊 Results: [...]

2. Anvil Simulation Test

yarn test:anvil

What it does:

• Creates a local Anvil fork of the Saga chain
• Simulates vault operations on the forked chain
• Executes tend operation with full transaction simulation
• Returns detailed transaction logs and results

Expected Output:

🚀 Starting Anvil chain simulation test...
ℹ️ Using manually started Anvil at http://localhost:3000
🛠️ Manual Anvil mode enabled.
👉 Please run this in another terminal:
anvil --fork-url https://sagaevm-archive.jsonrpc.sagarpc.io --port 3000 --fork-block-number <block_number>
Proceeding assuming Anvil is or will be available on port 3000...
✅ Anvil Simulation completed successfully!

3. Both Simulations

yarn test:both

Runs both TEVM and Anvil simulations sequentially for comparison.

🔍 Manual Anvil Setup

The Anvil simulation requires manual setup due to the fork manager configuration:

Step 1: Start Anvil Fork

# In a separate terminal, run:
anvil --fork-url https://sagaevm-archive.jsonrpc.sagarpc.io --port 3000 --fork-block-number <block_number>

Parameters:

• --fork-url: Saga chain RPC endpoint
• --port: Local port (fixed to 3000)
• --fork-block-number: Block number to fork from (get current from RPC)

Step 2: Run Anvil Test

# In your main terminal:
yarn test:anvil

📈 Test Results

TEVM Results

Returns VaultSnapshot[] with:

• Vault address and chain ID
• Token amounts (totalAmount0, totalAmount1)
• Fees earned (fees0Earned, fees1Earned)
• Pool state (sqrtPriceX96, totalSupply)
• Block information (blockNumber, blockTimestamp)

Anvil Results

Returns transaction receipt with:

• Transaction hash and status
• Gas used and effective gas price
• Event logs (FeesEarned, Snapshot events)
• Detailed transaction execution data

🐛 Troubleshooting

Common Issues

1. Anvil Port Already in Use

# Check what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port (update anvil-manager.ts)

2. RPC Connection Issues

# Verify RPC endpoint is accessible
curl -X POST https://sagaevm-archive.jsonrpc.sagarpc.io \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

3. TEVM Client Issues

# Clear node_modules and reinstall
rm -rf node_modules yarn.lock
yarn install

Debug Mode

Enable detailed logging by setting environment variables:

DEBUG=* yarn test:anvil
DEBUG=* yarn test:tevm

🔧 Customization

Adding New Vaults

1. Update test parameters in src/index.ts
2. Ensure vault addresses are valid on Saga chain
3. Verify contract ABIs in src/utils/contract-abils.ts

Supporting New Chains

1. Add chain ID to src/utils/consts.ts
2. Update RPC endpoints in simulation files
3. Verify chain-specific contract addresses

Modifying Test Parameters

Edit the test data in the respective test functions:

• testSagaSimulation() for TEVM
• testAnvilSimulation() for Anvil

📚 API Reference

SimulateVaultRebalanceAnvil

class SimulateVaultRebalanceAnvil {
  constructor(chainId: number, protocol: string, orchestratorAddress: string, steerPeripheryAddress: string)
  
  async initializeForkManager(): Promise<void>
  async processVaultForSnapshot(vaultAddress: string, liquidityPositions: any): Promise<TendResult>
  async deleteFork(): Promise<void>
}

simulateTendWithTevm

async function simulateTendWithTevm(
  chainId: number, 
  textInputsTevmSimulation: TextInputsTevmSimulation
): Promise<VaultSnapshot[]>