diff --git a/Contributing/Overview.md b/Contributing/Overview.md
new file mode 100644
index 000000000..b3843aa24
--- /dev/null
+++ b/Contributing/Overview.md
@@ -0,0 +1,81 @@
+# Contributing Guide
+
+Thank you for your interest in contributing to the Chainlink Testing Framework (CTF)! We welcome contributions from the community to improve the framework, add features, fix bugs, and enhance documentation.
+
+---
+
+## How to Contribute
+
+1. **Fork the repository** and create your branch from `main`.
+2. **Open an issue** to discuss your proposed change if it's non-trivial.
+3. **Write clear, maintainable code** and add tests for new features or bug fixes.
+4. **Document your changes** in the code and/or wiki as appropriate.
+5. **Open a Pull Request (PR)** with a clear description of your changes and link to any relevant issues.
+6. **Participate in code review** and address feedback promptly.
+
+---
+
+## Code of Conduct
+
+We are committed to fostering a welcoming and inclusive environment. Please read and follow our [Code of Conduct](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/CODE_OF_CONDUCT.md).
+
+---
+
+## Development Setup
+
+1. **Clone the repository**
+ ```bash
+ git clone https://github.com/smartcontractkit/chainlink-testing-framework.git
+ cd chainlink-testing-framework
+ ```
+2. **Install dependencies**
+ - [Go](https://go.dev/doc/install) 1.21+
+ - [Docker](https://www.docker.com/)
+ - [direnv](https://direnv.net/) (optional, for environment management)
+ - [nix](https://nixos.org/manual/nix/stable/installation/installation.html) (optional, for dev environments)
+3. **Set up your environment**
+ ```bash
+ cp Getting-Started/Installation.md .
+ # Follow the installation instructions for your OS
+ ```
+4. **Run tests locally**
+ ```bash
+ CTF_CONFIGS=smoke.toml go test -v
+ ```
+5. **Lint and format your code**
+ ```bash
+ go fmt ./...
+ go vet ./...
+ golangci-lint run
+ ```
+
+---
+
+## Pull Request Process
+
+1. **Open a draft PR** early to get feedback.
+2. **Ensure all tests pass** and code is linted.
+3. **Describe your changes** clearly in the PR description.
+4. **Link to any related issues** (e.g., `Closes #123`).
+5. **Request review** from maintainers or relevant code owners.
+6. **Address review comments** and update your PR as needed.
+7. **Wait for approval and merge** (maintainers will handle merging).
+
+---
+
+## Getting Help
+
+- **Search issues**: [GitHub Issues](https://github.com/smartcontractkit/chainlink-testing-framework/issues)
+- **Ask in discussions**: [GitHub Discussions](https://github.com/smartcontractkit/chainlink-testing-framework/discussions)
+- **Open a new issue** for bugs, feature requests, or questions
+- **Contact maintainers** via GitHub if you need further assistance
+
+---
+
+## Resources
+- [Home](../Home)
+- [Installation Guide](../Getting-Started/Installation)
+- [API Reference](../Reference/API-Reference)
+- [Troubleshooting](../Reference/Troubleshooting)
+- [Code of Conduct](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/CODE_OF_CONDUCT.md)
+- [LICENSE](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/LICENSE)
\ No newline at end of file
diff --git a/Examples/Advanced-Examples.md b/Examples/Advanced-Examples.md
new file mode 100644
index 000000000..43faba9aa
--- /dev/null
+++ b/Examples/Advanced-Examples.md
@@ -0,0 +1,179 @@
+# Advanced Examples
+
+This page provides advanced and real-world test scenarios using the Chainlink Testing Framework (CTF). These examples demonstrate how to leverage CTF for complex, production-like workflows.
+
+---
+
+## 1. Multi-Chain Integration Test
+
+Test a system that interacts with multiple blockchains (e.g., Ethereum and Solana) and verifies cross-chain data flow.
+
+```toml
+[ethereum]
+ type = "geth"
+ image = "ethereum/client-go"
+ tag = "v1.12.0"
+ pull_image = true
+
+[solana]
+ type = "solana"
+ image = "solanalabs/solana"
+ tag = "v1.16.0"
+ pull_image = true
+
+[chainlink_node]
+ image = "public.ecr.aws/chainlink/chainlink"
+ tag = "2.7.0"
+ pull_image = true
+```
+
+```go
+func TestMultiChainIntegration(t *testing.T) {
+ type Config struct {
+ Ethereum *blockchain.Input `toml:"ethereum" validate:"required"`
+ Solana *blockchain.Input `toml:"solana" validate:"required"`
+ ChainlinkNode *clnode.Input `toml:"chainlink_node" validate:"required"`
+ }
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+ eth, err := blockchain.NewBlockchainNetwork(in.Ethereum)
+ require.NoError(t, err)
+ sol, err := blockchain.NewBlockchainNetwork(in.Solana)
+ require.NoError(t, err)
+ cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
+ require.NoError(t, err)
+ // ... deploy contracts, set up jobs, verify cross-chain data
+}
+```
+
+---
+
+## 2. Upgrade and Migration Test
+
+Test that a Chainlink node or contract can be upgraded without breaking existing functionality.
+
+```toml
+[chainlink_node]
+ image = "public.ecr.aws/chainlink/chainlink"
+ tag = "2.6.0"
+ pull_image = true
+```
+
+```go
+func TestUpgrade(t *testing.T) {
+ // Deploy with old version
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+ cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
+ require.NoError(t, err)
+ // ... run smoke test
+
+ // Upgrade node
+ in.ChainlinkNode.Tag = "2.7.0"
+ clUpgraded, err := clnode.NewChainlinkNode(in.ChainlinkNode)
+ require.NoError(t, err)
+ // ... verify data, jobs, and state are preserved
+}
+```
+
+---
+
+## 3. Chaos Engineering Test
+
+Inject failures and network issues to test system resilience using Havoc.
+
+```go
+func TestChaosResilience(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+ cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
+ require.NoError(t, err)
+ // Start chaos experiment
+ client, err := havoc.NewClient()
+ require.NoError(t, err)
+ chaos, err := havoc.NewChaos(client, createNetworkChaos())
+ require.NoError(t, err)
+ err = chaos.Create(context.Background())
+ require.NoError(t, err)
+ // ... run test logic while chaos is active
+ chaos.Delete(context.Background())
+}
+```
+
+---
+
+## 4. Performance and Load Test
+
+Use WASP to generate load and measure system performance under stress.
+
+```go
+func TestPerformance(t *testing.T) {
+ profile := wasp.NewProfile()
+ generator := wasp.NewGenerator(&wasp.Config{
+ T: 60 * time.Second,
+ RPS: 100,
+ LoadType: wasp.RPS,
+ Schedule: wasp.Plain(100, 60*time.Second),
+ })
+ generator.AddRequestFn(func(ctx context.Context) error {
+ // Simulate contract call or API request
+ return nil
+ })
+ profile.Add(generator)
+ _, err := profile.Run(true)
+ require.NoError(t, err)
+}
+```
+
+---
+
+## 5. End-to-End Oracle Test
+
+Test the full workflow from contract deployment to job fulfillment and data reporting.
+
+```go
+func TestOracleE2E(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+ cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
+ require.NoError(t, err)
+ // Deploy oracle contract
+ // Register job on Chainlink node
+ // Send request and verify fulfillment
+}
+```
+
+---
+
+## 6. Real-World: Staging Environment Reuse
+
+Reuse cached components and substitute staging URLs for persistent environment testing.
+
+```toml
+[blockchain_a]
+ type = "anvil"
+ use_cache = true
+ external_url = "https://staging-eth.example.com"
+
+[chainlink_node]
+ use_cache = true
+ external_url = "https://staging-cl.example.com"
+```
+
+```go
+func TestStagingReuse(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+ // Use staging URLs for integration tests
+}
+```
+
+---
+
+## More Examples
+- [WASP Load Testing](../Libraries/WASP)
+- [Havoc Chaos Testing](../Libraries/Havoc)
+- [Seth Ethereum Client](../Libraries/Seth)
+- [Framework Examples Directory](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/framework/examples/myproject)
\ No newline at end of file
diff --git a/Examples/Use-Cases.md b/Examples/Use-Cases.md
new file mode 100644
index 000000000..301270c42
--- /dev/null
+++ b/Examples/Use-Cases.md
@@ -0,0 +1,107 @@
+# Real-World Use Cases
+
+This page highlights real-world scenarios where the Chainlink Testing Framework (CTF) is used to ensure reliability, performance, and security in production systems.
+
+---
+
+## 1. Production-Grade End-to-End Testing
+
+**Scenario:**
+- A Chainlink-integrated DeFi protocol needs to verify that price feeds, job fulfillment, and contract upgrades work as expected across multiple networks.
+
+**How CTF Helps:**
+- Deploys ephemeral or persistent test environments that mirror production.
+- Runs full workflows: contract deployment, job registration, data requests, and fulfillment.
+- Validates on-chain and off-chain integration.
+
+---
+
+## 2. CI/CD Pipeline Integration
+
+**Scenario:**
+- Every pull request must pass a suite of integration, performance, and chaos tests before merging.
+
+**How CTF Helps:**
+- Runs in GitHub Actions or other CI systems.
+- Uses caching to speed up repeated test runs.
+- Fails fast on regressions, configuration errors, or performance degradations.
+- Exposes logs and metrics for debugging failed builds.
+
+---
+
+## 3. Protocol Upgrade and Migration Testing
+
+**Scenario:**
+- A new Chainlink node version or smart contract upgrade must be validated for backward compatibility and data integrity.
+
+**How CTF Helps:**
+- Spins up old and new versions side-by-side.
+- Runs upgrade and migration scripts.
+- Verifies that jobs, data, and state persist across upgrades.
+- Detects breaking changes before they reach production.
+
+---
+
+## 4. Cross-Chain and Multi-Network Testing
+
+**Scenario:**
+- A dApp or oracle service operates across Ethereum, Solana, and other chains, requiring cross-chain data flow validation.
+
+**How CTF Helps:**
+- Deploys multiple blockchains in parallel.
+- Simulates cross-chain requests and data propagation.
+- Validates data consistency and latency across networks.
+
+---
+
+## 5. Oracle Network Resilience and Chaos Engineering
+
+**Scenario:**
+- The reliability of a Chainlink DON (Decentralized Oracle Network) must be tested under network partitions, node failures, and resource exhaustion.
+
+**How CTF Helps:**
+- Uses Havoc to inject network latency, pod failures, and resource limits.
+- Monitors system health and recovery.
+- Validates that the DON continues to serve data or recovers gracefully.
+
+---
+
+## 6. Performance Benchmarking and Load Testing
+
+**Scenario:**
+- A new Chainlink job type or protocol feature must be benchmarked for throughput and latency under load.
+
+**How CTF Helps:**
+- Uses WASP to generate synthetic or user-based load.
+- Collects metrics via Prometheus and visualizes in Grafana.
+- Identifies bottlenecks and regression points.
+
+---
+
+## 7. Staging Environment Validation
+
+**Scenario:**
+- Before a mainnet release, the team wants to validate the full stack in a persistent staging environment.
+
+**How CTF Helps:**
+- Reuses cached components and substitutes staging URLs.
+- Runs upgrade, chaos, and performance tests against the staging stack.
+- Ensures production readiness with minimal manual intervention.
+
+---
+
+## 8. Custom Component and Plugin Testing
+
+**Scenario:**
+- A team develops a custom Chainlink external adapter or plugin and needs to validate it in a realistic environment.
+
+**How CTF Helps:**
+- Easily adds custom components to the test config.
+- Runs integration and chaos tests with the new plugin.
+- Validates compatibility with existing Chainlink nodes and contracts.
+
+---
+
+## More Use Cases
+- [Chainlink Blog: Testing at Scale](https://blog.chain.link/)
+- [Framework Examples Directory](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/framework/examples/myproject)
\ No newline at end of file
diff --git a/Getting-Started/First-Test.md b/Getting-Started/First-Test.md
new file mode 100644
index 000000000..49d78c35c
--- /dev/null
+++ b/Getting-Started/First-Test.md
@@ -0,0 +1,328 @@
+# Writing Your First Test
+
+This guide will walk you through creating your first test with the Chainlink Testing Framework (CTF). We'll start with a simple blockchain test and gradually build up to more complex scenarios.
+
+## Prerequisites
+
+Before starting, make sure you have:
+- [Installed CTF](Installation)
+- Docker running
+- A basic understanding of Go testing
+
+## Basic Test Structure
+
+CTF tests follow a simple pattern:
+1. **Configuration** - Define what components you need
+2. **Loading** - Load configuration into your test
+3. **Component Creation** - Create and start components
+4. **Testing** - Write your test logic
+5. **Cleanup** - Clean up resources (automatic with CTF)
+
+## Step 1: Create Configuration
+
+Create a `smoke.toml` file in your project root:
+
+```toml
+[blockchain_a]
+ type = "anvil"
+```
+
+This configuration tells CTF to create an Anvil blockchain instance. Anvil is a fast Ethereum development node that's perfect for testing.
+
+## Step 2: Write Your Test
+
+Create `smoke_test.go`:
+
+```go
+package mymodule_test
+
+import (
+ "github.com/smartcontractkit/chainlink-testing-framework/framework"
+ "github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+ "github.com/stretchr/testify/require"
+ "testing"
+)
+
+// Config defines the structure of your configuration file
+type Config struct {
+ BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+}
+
+func TestSmoke(t *testing.T) {
+ // Load configuration from TOML file
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+
+ // Create blockchain network
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+
+ // Your test logic goes here
+ t.Run("blockchain is running", func(t *testing.T) {
+ require.NotEmpty(t, bc.Nodes[0].ExternalHTTPUrl)
+ require.NotEmpty(t, bc.Nodes[0].InternalHTTPUrl)
+ })
+
+ t.Run("blockchain is accessible", func(t *testing.T) {
+ // Test that we can connect to the blockchain
+ client := bc.GetDefaultClient()
+ require.NotNil(t, client)
+
+ // Get the latest block number
+ blockNumber, err := client.BlockNumber(context.Background())
+ require.NoError(t, err)
+ require.GreaterOrEqual(t, blockNumber, uint64(0))
+ })
+}
+```
+
+## Step 3: Run Your Test
+
+```bash
+# Run the test
+CTF_CONFIGS=smoke.toml go test -v -run TestSmoke
+
+# Clean up containers when done
+ctf d rm
+```
+
+## Understanding the Test
+
+Let's break down what's happening:
+
+### Configuration Loading
+```go
+in, err := framework.Load[Config](t)
+```
+This loads your `smoke.toml` file and validates it against the `Config` struct. The `validate:"required"` tag ensures the blockchain configuration is present.
+
+### Component Creation
+```go
+bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+```
+This creates a blockchain network based on your configuration. CTF will:
+- Start a Docker container with Anvil
+- Configure networking
+- Wait for the service to be ready
+- Return a network object with connection details
+
+### Test Logic
+```go
+t.Run("blockchain is running", func(t *testing.T) {
+ require.NotEmpty(t, bc.Nodes[0].ExternalHTTPUrl)
+})
+```
+This tests that the blockchain is actually running and accessible. The `ExternalHTTPUrl` is the URL you can use to connect to the blockchain from your host machine.
+
+## Adding More Components
+
+Let's expand the test to include a Chainlink node:
+
+### Updated Configuration
+```toml
+[blockchain_a]
+ type = "anvil"
+
+[chainlink_node]
+ image = "public.ecr.aws/chainlink/chainlink"
+ tag = "2.7.0"
+ pull_image = true
+ node_config = """
+ [Log]
+ Level = "info"
+
+ [WebServer]
+ TLSListenPort = 0
+ Port = 6688
+
+ [Database]
+ URL = "postgresql://postgres:password@postgres:5432/chainlink?sslmode=disable"
+ """
+```
+
+### Updated Test
+```go
+package mymodule_test
+
+import (
+ "context"
+ "github.com/smartcontractkit/chainlink-testing-framework/framework"
+ "github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+ "github.com/smartcontractkit/chainlink-testing-framework/framework/components/clnode"
+ "github.com/stretchr/testify/require"
+ "testing"
+)
+
+type Config struct {
+ BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+ ChainlinkNode *clnode.Input `toml:"chainlink_node" validate:"required"`
+}
+
+func TestSmokeWithChainlink(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+
+ // Create blockchain network
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+
+ // Create Chainlink node
+ cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
+ require.NoError(t, err)
+
+ t.Run("blockchain is running", func(t *testing.T) {
+ require.NotEmpty(t, bc.Nodes[0].ExternalHTTPUrl)
+ })
+
+ t.Run("chainlink node is running", func(t *testing.T) {
+ require.NotEmpty(t, cl.ExternalURL)
+
+ // Test that the Chainlink API is accessible
+ resp, err := http.Get(cl.ExternalURL + "/health")
+ require.NoError(t, err)
+ require.Equal(t, http.StatusOK, resp.StatusCode)
+ })
+
+ t.Run("chainlink can connect to blockchain", func(t *testing.T) {
+ // This would typically involve setting up a job
+ // and verifying it can interact with the blockchain
+ require.NotEmpty(t, bc.Nodes[0].InternalHTTPUrl)
+ })
+}
+```
+
+## Test Patterns
+
+### Using Subtests
+CTF encourages the use of subtests (`t.Run`) to organize your test logic:
+
+```go
+func TestComprehensive(t *testing.T) {
+ // Setup
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+
+ // Test different aspects
+ t.Run("connectivity", func(t *testing.T) {
+ // Test network connectivity
+ })
+
+ t.Run("functionality", func(t *testing.T) {
+ // Test core functionality
+ })
+
+ t.Run("performance", func(t *testing.T) {
+ // Test performance characteristics
+ })
+}
+```
+
+### Parallel Testing
+You can run tests in parallel for faster execution:
+
+```go
+func TestParallel(t *testing.T) {
+ t.Parallel() // Enable parallel execution
+
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+ // ... rest of test
+}
+```
+
+### Test Cleanup
+CTF automatically handles cleanup of Docker containers, but you can add custom cleanup:
+
+```go
+func TestWithCleanup(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+
+ // Add custom cleanup
+ t.Cleanup(func() {
+ // Custom cleanup logic
+ log.Println("Cleaning up custom resources")
+ })
+
+ // Your test logic
+}
+```
+
+## Running Tests
+
+### Basic Test Execution
+```bash
+# Run all tests
+go test -v
+
+# Run specific test
+go test -v -run TestSmoke
+
+# Run tests with specific config
+CTF_CONFIGS=smoke.toml go test -v -run TestSmoke
+
+# Run tests multiple times
+go test -v -run TestSmoke -count 5
+```
+
+### Test Flags
+```bash
+# Run tests with timeout
+go test -v -timeout 10m -run TestSmoke
+
+# Run tests with race detection
+go test -v -race -run TestSmoke
+
+# Run tests with coverage
+go test -v -cover -run TestSmoke
+```
+
+### Environment Variables
+```bash
+# Set log level
+CTF_LOG_LEVEL=debug go test -v -run TestSmoke
+
+# Disable caching
+CTF_DISABLE_CACHE=true go test -v -run TestSmoke
+
+# Use specific Docker network
+CTF_NETWORK_NAME=my-network go test -v -run TestSmoke
+```
+
+## Next Steps
+
+Now that you've written your first test, you can:
+
+1. **Add more components** - Try adding databases, external services, or multiple blockchain networks
+2. **Learn about configuration** - Explore the [Configuration Guide](Configuration) for more options
+3. **Set up observability** - Add monitoring and logging with the [Environment Setup Guide](Environment-Setup)
+4. **Explore advanced patterns** - Check out the [Framework Test Patterns](../Framework/Test-Patterns)
+5. **Look at examples** - Browse the [Examples section](../Examples/Basic-Examples) for more complex scenarios
+
+## Common Issues
+
+### Test Fails to Start
+- Check that Docker is running
+- Verify your configuration file syntax
+- Ensure all required fields are present
+
+### Components Not Ready
+- CTF automatically waits for components to be ready
+- Check logs for component startup issues
+- Verify network connectivity
+
+### Port Conflicts
+- CTF automatically assigns ports to avoid conflicts
+- If you get port binding errors, check what's using the ports
+- Use `ctf d rm` to clean up existing containers
+
+### Memory Issues
+- Some components (like blockchain nodes) can be memory-intensive
+- Consider using OrbStack instead of Docker Desktop
+- Increase Docker memory limits if needed
\ No newline at end of file
diff --git a/Getting-Started/Installation.md b/Getting-Started/Installation.md
new file mode 100644
index 000000000..f2a9aa5bf
--- /dev/null
+++ b/Getting-Started/Installation.md
@@ -0,0 +1,277 @@
+# Installation Guide
+
+This guide will help you set up the Chainlink Testing Framework (CTF) on your local machine.
+
+## Prerequisites
+
+### Required Software
+
+1. **Docker**
+ - **Recommended**: [OrbStack](https://orbstack.dev/) (faster, smaller memory footprint)
+ - **Alternative**: [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+
+ Tested with:
+ ```
+ Docker version 27.3.1
+ OrbStack Version: 1.8.2 (1080200)
+ ```
+
+2. **Golang**
+ - Install the latest stable version from [go.dev](https://go.dev/doc/install)
+ - Minimum version: Go 1.21+
+ - Recommended: Go 1.22+
+
+3. **Git**
+ - Required for cloning repositories and managing dependencies
+
+### Optional Software
+
+- **[direnv](https://direnv.net/)** - Automatically load environment variables
+- **[nix](https://nixos.org/manual/nix/stable/installation/installation.html)** - For development dependencies (used by some libraries)
+
+## Installation Steps
+
+### 1. Install Docker
+
+#### macOS
+```bash
+# Install OrbStack (recommended)
+brew install --cask orbstack
+
+# Or install Docker Desktop
+brew install --cask docker
+```
+
+#### Linux
+```bash
+# Ubuntu/Debian
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+
+# Add user to docker group
+sudo usermod -aG docker $USER
+```
+
+#### Windows
+- Download and install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
+
+### 2. Install Golang
+
+#### macOS
+```bash
+# Using Homebrew
+brew install go
+
+# Or download from go.dev
+curl -L https://go.dev/dl/go1.22.0.darwin-amd64.pkg -o go.pkg
+sudo installer -pkg go.pkg -target /
+```
+
+#### Linux
+```bash
+# Download and install
+wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
+sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
+
+# Add to PATH
+echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
+source ~/.bashrc
+```
+
+#### Windows
+- Download from [go.dev](https://go.dev/dl/) and run the installer
+
+### 3. Download CTF CLI
+
+The CTF CLI provides helpful commands for managing test environments and observability stacks.
+
+#### macOS ARM64 (M1/M2/M3)
+```bash
+curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework/v0.1.8/framework-v0.1.8-darwin-arm64.tar.gz | tar -xz
+```
+
+#### macOS AMD64 (Intel)
+```bash
+curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework/v0.1.8/framework-v0.1.8-darwin-amd64.tar.gz | tar -xz
+```
+
+#### Linux ARM64
+```bash
+curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework/v0.1.8/framework-v0.1.8-linux-arm64.tar.gz | tar -xz
+```
+
+#### Linux AMD64
+```bash
+curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework/v0.1.8/framework-v0.1.8-linux-amd64.tar.gz | tar -xz
+```
+
+#### Windows
+```bash
+# Using PowerShell
+Invoke-WebRequest -Uri "https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework/v0.1.8/framework-v0.1.8-windows-amd64.tar.gz" -OutFile "framework.tar.gz"
+tar -xzf framework.tar.gz
+```
+
+### 4. Set Up Environment
+
+Create a `.envrc` file in your project directory:
+
+```bash
+# Create .envrc file
+cat > .envrc << EOF
+export TESTCONTAINERS_RYUK_DISABLED=true
+EOF
+
+# Load environment variables
+source .envrc
+```
+
+**Note**: If you have `direnv` installed, the environment variables will be automatically loaded when you enter the directory.
+
+### 5. Verify Installation
+
+Test that everything is working:
+
+```bash
+# Check Docker
+docker --version
+docker run hello-world
+
+# Check Go
+go version
+
+# Check CTF CLI
+./framework --help
+```
+
+## Project Setup
+
+### 1. Create a New Project
+
+```bash
+# Create project directory
+mkdir my-ctf-project
+cd my-ctf-project
+
+# Initialize Go module
+go mod init my-ctf-project
+
+# Add framework dependency
+go get github.com/smartcontractkit/chainlink-testing-framework/framework
+```
+
+### 2. Create Basic Configuration
+
+Create a `smoke.toml` file:
+
+```toml
+[blockchain_a]
+ type = "anvil"
+```
+
+### 3. Create Your First Test
+
+Create `smoke_test.go`:
+
+```go
+package mymodule_test
+
+import (
+ "github.com/smartcontractkit/chainlink-testing-framework/framework"
+ "github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+ "github.com/stretchr/testify/require"
+ "testing"
+)
+
+type Config struct {
+ BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+}
+
+func TestSmoke(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+
+ t.Run("blockchain is running", func(t *testing.T) {
+ require.NotEmpty(t, bc.Nodes[0].ExternalHTTPUrl)
+ })
+}
+```
+
+### 4. Run Your First Test
+
+```bash
+# Run the test
+CTF_CONFIGS=smoke.toml go test -v -run TestSmoke
+
+# Clean up containers
+ctf d rm
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Docker Permission Issues
+```bash
+# Add user to docker group (Linux)
+sudo usermod -aG docker $USER
+newgrp docker
+
+# Restart Docker Desktop (macOS/Windows)
+```
+
+#### Port Conflicts
+If you get port binding errors:
+```bash
+# Check what's using the port
+lsof -i :8545 # Example for Ethereum RPC port
+
+# Kill the process or change ports in your config
+```
+
+#### Memory Issues
+If you encounter memory issues with Docker:
+- Increase Docker memory limit in Docker Desktop settings
+- Use OrbStack instead of Docker Desktop (better performance)
+
+#### Go Module Issues
+```bash
+# Clean module cache
+go clean -modcache
+
+# Tidy dependencies
+go mod tidy
+```
+
+### Getting Help
+
+- Check the [Troubleshooting Guide](../Reference/Troubleshooting)
+- Search [existing issues](https://github.com/smartcontractkit/chainlink-testing-framework/issues)
+- Create a [new issue](https://github.com/smartcontractkit/chainlink-testing-framework/issues/new) with detailed information
+
+## Next Steps
+
+Now that you have CTF installed, you can:
+
+1. [Write your first test](First-Test)
+2. [Learn about configuration](Configuration)
+3. [Set up observability](Environment-Setup)
+4. [Explore the framework components](../Framework/Components)
+
+## System Requirements
+
+### Minimum Requirements
+- **CPU**: 2 cores
+- **RAM**: 4GB
+- **Storage**: 10GB free space
+- **OS**: macOS 10.15+, Ubuntu 18.04+, Windows 10+
+
+### Recommended Requirements
+- **CPU**: 4+ cores
+- **RAM**: 8GB+
+- **Storage**: 20GB+ free space
+- **OS**: Latest stable versions
+- **Docker**: OrbStack (macOS) or Docker Desktop with increased resources
\ No newline at end of file
diff --git a/Home.md b/Home.md
new file mode 100644
index 000000000..8ca3a1686
--- /dev/null
+++ b/Home.md
@@ -0,0 +1,218 @@
+# Chainlink Testing Framework (CTF) Wiki
+
+
+
+[](https://smartcontractkit.github.io/chainlink-testing-framework/overview.html)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
+
+[](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/test.yaml)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/linters.yml)
+
+[](https://goreportcard.com/report/github.com/smartcontractkit/chainlink-testing-framework)
+
+[](https://opensource.org/licenses/MIT)
+
+
+
+## Overview
+
+The **Chainlink Testing Framework (CTF)** is a comprehensive blockchain development framework written in Go, designed to help Chainlink developers create extensive integration, end-to-end, performance, and chaos tests to ensure the stability of the Chainlink project. It can also be helpful for developers who want to use Chainlink oracles in their projects or even for those not using Chainlink at all.
+
+## 🎯 Primary Goals
+
+- **Reduce complexity** of end-to-end testing
+- **Enable tests to run in any environment**
+- **Serve as a single source of truth** for system behavior
+- **Provide modular, data-driven testing** capabilities
+- **Support comprehensive observability** and monitoring
+
+## 🏗️ Architecture
+
+The CTF monorepository contains two major pieces:
+
+### 1. **Framework** - Core Testing Infrastructure
+- **Modular component system** for blockchain networks, Chainlink nodes, and other services
+- **Configuration-driven testing** with TOML-based configs
+- **Component isolation** and replaceability
+- **Integrated observability stack** (metrics, logs, traces, profiles)
+- **Caching system** for faster test development
+- **Quick local environments** (15-second setup with caching)
+
+### 2. **Libraries** - Specialized Testing Tools
+- **[WASP](Libraries/WASP)** - Scalable protocol-agnostic load testing library
+- **[Seth](Libraries/Seth)** - Reliable and debug-friendly Ethereum client
+- **[Havoc](Libraries/Havoc)** - Chaos testing library for Kubernetes environments
+
+## 🚀 Key Features
+
+### Framework Features
+- **Straightforward and sequential test composition** - Tests are readable with precise control
+- **Modular configuration** - No arcane knowledge required, config reflects components used
+- **Component isolation** - Components decoupled via input/output structs
+- **Replaceability and extensibility** - Any deployment component can be swapped
+- **Quick local environments** - Common setup in just 15 seconds
+- **Caching** - Skip setup for faster test development
+- **Integrated observability** - Metrics, logs, traces, and profiles
+
+### Library Features
+- **WASP**: Protocol-agnostic load testing with Grafana integration
+- **Seth**: Transaction decoding, tracing, gas bumping, and multi-key support
+- **Havoc**: Chaos engineering with Chaos Mesh integration
+
+## 📚 Quick Start
+
+### Prerequisites
+- **Docker** ([OrbStack](https://orbstack.dev/) recommended) or Docker Desktop
+- **Golang** (latest stable version)
+- **CTF CLI** (download from releases)
+
+### Basic Setup
+```bash
+# Create project directory
+mkdir my-ctf-project && cd my-ctf-project
+
+# Initialize Go module
+go mod init my-ctf-project
+
+# Add framework dependency
+go get github.com/smartcontractkit/chainlink-testing-framework/framework
+
+# Download CTF CLI (example for macOS ARM64)
+curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework/v0.1.8/framework-v0.1.8-darwin-arm64.tar.gz | tar -xz
+
+# Set up environment
+echo 'export TESTCONTAINERS_RYUK_DISABLED=true' > .envrc
+source .envrc
+```
+
+### Your First Test
+```toml
+# smoke.toml
+[blockchain_a]
+ type = "anvil"
+```
+
+```go
+// smoke_test.go
+package mymodule_test
+
+import (
+ "github.com/smartcontractkit/chainlink-testing-framework/framework"
+ "github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+ "github.com/stretchr/testify/require"
+ "testing"
+)
+
+type Config struct {
+ BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+}
+
+func TestMe(t *testing.T) {
+ in, err := framework.Load[Config](t)
+ require.NoError(t, err)
+
+ bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+ require.NoError(t, err)
+
+ t.Run("test something", func(t *testing.T) {
+ require.NotEmpty(t, bc.Nodes[0].ExternalHTTPUrl)
+ })
+}
+```
+
+```bash
+# Run the test
+CTF_CONFIGS=smoke.toml go test -v -run TestMe
+
+# Clean up
+ctf d rm
+```
+
+## 📖 Documentation Structure
+
+### Getting Started
+- [Installation Guide](Getting-Started/Installation)
+- [First Test](Getting-Started/First-Test)
+- [Configuration Basics](Getting-Started/Configuration)
+- [Environment Setup](Getting-Started/Environment-Setup)
+
+### Framework
+- [Framework Overview](Framework/Overview)
+- [Component System](Framework/Components)
+- [Configuration Management](Framework/Configuration)
+- [Observability Stack](Framework/Observability)
+- [Caching System](Framework/Caching)
+- [Test Patterns](Framework/Test-Patterns)
+
+### Libraries
+- [WASP - Load Testing](Libraries/WASP)
+- [Seth - Ethereum Client](Libraries/Seth)
+- [Havoc - Chaos Testing](Libraries/Havoc)
+
+### Advanced Topics
+- [Component Development](Advanced/Component-Development)
+- [Custom Components](Advanced/Custom-Components)
+- [Performance Testing](Advanced/Performance-Testing)
+- [Chaos Engineering](Advanced/Chaos-Engineering)
+- [CI/CD Integration](Advanced/CI-CD-Integration)
+
+### Examples & Tutorials
+- [Basic Examples](Examples/Basic-Examples)
+- [Advanced Examples](Examples/Advanced-Examples)
+- [Real-world Use Cases](Examples/Use-Cases)
+
+### Reference
+- [API Reference](Reference/API-Reference)
+- [Configuration Reference](Reference/Configuration-Reference)
+- [CLI Reference](Reference/CLI-Reference)
+- [Troubleshooting](Reference/Troubleshooting)
+
+## 🎯 Use Cases
+
+### For Chainlink Developers
+- **Integration Testing**: Test Chainlink nodes with various blockchain networks
+- **End-to-End Testing**: Complete workflow testing from contract deployment to oracle responses
+- **Performance Testing**: Load testing with WASP library
+- **Chaos Testing**: Failure scenario testing with Havoc
+- **Upgrade Testing**: Version compatibility and migration testing
+
+### For Blockchain Developers
+- **Smart Contract Testing**: Deploy and test contracts with Seth
+- **Multi-Chain Testing**: Support for Ethereum, Solana, TON, and more
+- **Network Simulation**: Local blockchain networks for development
+- **Gas Optimization**: Transaction tracing and gas analysis
+
+### For DevOps Engineers
+- **Infrastructure Testing**: Test deployment configurations
+- **Observability**: Integrated monitoring and logging
+- **CI/CD Integration**: Automated testing pipelines
+- **Environment Management**: Consistent test environments
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](Contributing/Overview) for details on:
+- Code of Conduct
+- Development Setup
+- Testing Guidelines
+- Pull Request Process
+- Issue Reporting
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/LICENSE) file for details.
+
+## 🔗 Links
+
+- **[Repository](https://github.com/smartcontractkit/chainlink-testing-framework)**
+- **[Documentation](https://smartcontractkit.github.io/chainlink-testing-framework/)**
+- **[Issues](https://github.com/smartcontractkit/chainlink-testing-framework/issues)**
+- **[Discussions](https://github.com/smartcontractkit/chainlink-testing-framework/discussions)**
+- **[Releases](https://github.com/smartcontractkit/chainlink-testing-framework/releases)**
+
+---
+
+*This wiki provides comprehensive documentation for the Chainlink Testing Framework. For the most up-to-date information, always refer to the [official documentation](https://smartcontractkit.github.io/chainlink-testing-framework/).*
\ No newline at end of file
diff --git a/Libraries/Havoc.md b/Libraries/Havoc.md
new file mode 100644
index 000000000..f99910c1b
--- /dev/null
+++ b/Libraries/Havoc.md
@@ -0,0 +1,751 @@
+# Havoc - Chaos Testing Library
+
+[](https://pkg.go.dev/github.com/smartcontractkit/chainlink-testing-framework/havoc)
+
+## Overview
+
+The `havoc` package is designed to facilitate chaos testing within [Kubernetes](https://kubernetes.io/) environments using [Chaos Mesh](https://chaos-mesh.org/). It offers a structured way to define, execute, and manage chaos experiments as code, directly integrated into Go applications or testing suites, simplifying the creation and control of Chaos Mesh experiments.
+
+## Goals
+
+- **Chaos Object Management** - Create, update, pause, resume, and delete chaos experiments using Go structures and methods
+- **Lifecycle Hooks** - Utilize chaos listeners to hook into the lifecycle of chaos experiments
+- **Different Experiments** - Create and manage different types of chaos experiments to affect network, IO, K8s pods, and more
+- **Active Monitoring** - Monitor and react to the status of chaos experiments programmatically
+- **Observability Integration** - Structured logging and Grafana annotations for chaos experiment monitoring
+
+## Key Features
+
+### 1. **Chaos Experiment Management**
+- Create and manage Chaos Mesh experiments programmatically
+- Full lifecycle control (create, pause, resume, delete)
+- Type-safe experiment configuration
+
+### 2. **Lifecycle Hooks**
+- Implement custom listeners for chaos experiment events
+- React to experiment state changes
+- Integrate with monitoring and alerting systems
+
+### 3. **Multiple Experiment Types**
+- **Network Chaos** - Network latency, packet loss, bandwidth limits
+- **Pod Chaos** - Pod failure, pod kill, container kill
+- **IO Chaos** - IO latency, IO error injection
+- **Kernel Chaos** - Kernel panic, memory corruption
+- **Time Chaos** - Clock skew, time manipulation
+- **DNS Chaos** - DNS error injection, DNS spoofing
+- **HTTP Chaos** - HTTP error injection, HTTP latency
+
+### 4. **Observability Integration**
+- Structured logging with [zerolog](https://github.com/rs/zerolog)
+- Grafana dashboard annotations
+- Prometheus metrics integration
+- Custom event listeners
+
+## Requirements
+
+- [Go](https://go.dev/) 1.21+
+- A Kubernetes cluster with [Chaos Mesh installed](https://chaos-mesh.org/docs/quick-start/)
+- [k8s.io/client-go](https://github.com/kubernetes/client-go) for Kubernetes API access
+
+## Installation
+
+### Using Go Modules
+```bash
+go get github.com/smartcontractkit/chainlink-testing-framework/havoc
+```
+
+### Dependencies
+```bash
+go get k8s.io/client-go
+go get k8s.io/apimachinery
+```
+
+## Quick Start
+
+### Basic Chaos Experiment
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+ "time"
+
+ "github.com/smartcontractkit/chainlink-testing-framework/havoc"
+ "github.com/smartcontractkit/chainlink-testing-framework/havoc/chaosmesh"
+)
+
+func main() {
+ // Create chaos client
+ client, err := havoc.NewClient()
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Define network chaos experiment
+ networkChaos := &chaosmesh.NetworkChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "network-latency-test",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.NetworkChaosSpec{
+ Action: chaosmesh.NetworkDelayAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{
+ "app": "my-app",
+ },
+ },
+ Delay: &chaosmesh.DelaySpec{
+ Latency: "100ms",
+ Correlation: "100",
+ Jitter: "0ms",
+ },
+ Duration: &chaosmesh.Duration{
+ Duration: "30s",
+ },
+ },
+ }
+
+ // Create chaos experiment
+ chaos, err := havoc.NewChaos(client, networkChaos)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Start the experiment
+ err = chaos.Create(context.Background())
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ log.Println("Chaos experiment started")
+
+ // Wait for experiment to complete
+ time.Sleep(35 * time.Second)
+
+ // Clean up
+ err = chaos.Delete(context.Background())
+ if err != nil {
+ log.Printf("Failed to delete chaos experiment: %v", err)
+ }
+}
+```
+
+### With Lifecycle Listeners
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+ "time"
+
+ "github.com/smartcontractkit/chainlink-testing-framework/havoc"
+ "github.com/smartcontractkit/chainlink-testing-framework/havoc/chaosmesh"
+)
+
+// Custom chaos listener
+type MyChaosListener struct{}
+
+func (l *MyChaosListener) OnChaosCreated(chaos *havoc.Chaos) {
+ log.Printf("Chaos experiment created: %s", chaos.Name())
+}
+
+func (l *MyChaosListener) OnChaosStarted(chaos *havoc.Chaos) {
+ log.Printf("Chaos experiment started: %s", chaos.Name())
+}
+
+func (l *MyChaosListener) OnChaosPaused(chaos *havoc.Chaos) {
+ log.Printf("Chaos experiment paused: %s", chaos.Name())
+}
+
+func (l *MyChaosListener) OnChaosResumed(chaos *havoc.Chaos) {
+ log.Printf("Chaos experiment resumed: %s", chaos.Name())
+}
+
+func (l *MyChaosListener) OnChaosDeleted(chaos *havoc.Chaos) {
+ log.Printf("Chaos experiment deleted: %s", chaos.Name())
+}
+
+func main() {
+ client, err := havoc.NewClient()
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Create pod chaos experiment
+ podChaos := &chaosmesh.PodChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "pod-failure-test",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.PodChaosSpec{
+ Action: chaosmesh.PodFailureAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{
+ "app": "my-app",
+ },
+ },
+ Duration: &chaosmesh.Duration{
+ Duration: "10s",
+ },
+ },
+ }
+
+ // Create chaos with listener
+ chaos, err := havoc.NewChaos(client, podChaos)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Add custom listener
+ chaos.AddListener(&MyChaosListener{})
+
+ // Start experiment
+ err = chaos.Create(context.Background())
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Wait and clean up
+ time.Sleep(15 * time.Second)
+ chaos.Delete(context.Background())
+}
+```
+
+## Experiment Types
+
+### Network Chaos
+
+```go
+// Network latency
+networkChaos := &chaosmesh.NetworkChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "network-latency",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.NetworkChaosSpec{
+ Action: chaosmesh.NetworkDelayAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{"app": "my-app"},
+ },
+ Delay: &chaosmesh.DelaySpec{
+ Latency: "200ms",
+ Correlation: "100",
+ Jitter: "50ms",
+ },
+ Duration: &chaosmesh.Duration{
+ Duration: "60s",
+ },
+ },
+}
+
+// Network packet loss
+networkChaos := &chaosmesh.NetworkChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "network-loss",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.NetworkChaosSpec{
+ Action: chaosmesh.NetworkLossAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{"app": "my-app"},
+ },
+ Loss: &chaosmesh.LossSpec{
+ Loss: "50",
+ Correlation: "100",
+ },
+ Duration: &chaosmesh.Duration{
+ Duration: "30s",
+ },
+ },
+}
+```
+
+### Pod Chaos
+
+```go
+// Pod failure
+podChaos := &chaosmesh.PodChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "pod-failure",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.PodChaosSpec{
+ Action: chaosmesh.PodFailureAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{"app": "my-app"},
+ },
+ Duration: &chaosmesh.Duration{
+ Duration: "30s",
+ },
+ },
+}
+
+// Pod kill
+podChaos := &chaosmesh.PodChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "pod-kill",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.PodChaosSpec{
+ Action: chaosmesh.PodKillAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{"app": "my-app"},
+ },
+ },
+}
+```
+
+### IO Chaos
+
+```go
+// IO latency
+ioChaos := &chaosmesh.IOChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "io-latency",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.IOChaosSpec{
+ Action: chaosmesh.IODelayAction,
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{"app": "my-app"},
+ },
+ Delay: "100ms",
+ Percent: 50,
+ Path: "/var/log",
+ Methods: []string{"read", "write"},
+ Duration: &chaosmesh.Duration{
+ Duration: "60s",
+ },
+ },
+}
+```
+
+### Time Chaos
+
+```go
+// Clock skew
+timeChaos := &chaosmesh.TimeChaos{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: "clock-skew",
+ Namespace: "default",
+ },
+ Spec: chaosmesh.TimeChaosSpec{
+ Mode: chaosmesh.OneMode,
+ Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"default"},
+ LabelSelectors: map[string]string{"app": "my-app"},
+ },
+ TimeOffset: "1h",
+ Duration: &chaosmesh.Duration{
+ Duration: "30s",
+ },
+ },
+}
+```
+
+## Observability Integration
+
+### Structured Logging
+
+Havoc provides structured logging using zerolog:
+
+```go
+import (
+ "github.com/rs/zerolog/log"
+)
+
+// Enable debug logging
+log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})
+
+// Chaos events are automatically logged
+chaos, err := havoc.NewChaos(client, networkChaos)
+if err != nil {
+ log.Fatal().Err(err).Msg("Failed to create chaos")
+}
+```
+
+### Grafana Annotations
+
+Integrate with Grafana dashboards:
+
+```go
+import (
+ "github.com/smartcontractkit/chainlink-testing-framework/havoc"
+)
+
+// Create Grafana annotator
+grafanaAnnotator := havoc.NewSingleLineGrafanaAnnotator(
+ "http://localhost:3000",
+ "your-token",
+ []string{"dashboard-uid"},
+)
+
+// Add to chaos experiment
+chaos.AddListener(grafanaAnnotator)
+
+// Start experiment (annotations will be created automatically)
+err = chaos.Create(context.Background())
+```
+
+### Range Annotations
+
+For experiments with duration, use range annotations:
+
+```go
+// Create range annotator
+rangeAnnotator := havoc.NewRangeGrafanaAnnotator(
+ "http://localhost:3000",
+ "your-token",
+ []string{"dashboard-uid"},
+)
+
+chaos.AddListener(rangeAnnotator)
+```
+
+## Advanced Usage
+
+### Multiple Experiments
+
+```go
+func runChaosSuite() error {
+ client, err := havoc.NewClient()
+ if err != nil {
+ return err
+ }
+
+ experiments := []chaosmesh.Chaos{
+ createNetworkLatency(),
+ createPodFailure(),
+ createIOChaos(),
+ }
+
+ for _, exp := range experiments {
+ chaos, err := havoc.NewChaos(client, exp)
+ if err != nil {
+ return err
+ }
+
+ // Start experiment
+ err = chaos.Create(context.Background())
+ if err != nil {
+ return err
+ }
+
+ // Wait for completion
+ time.Sleep(30 * time.Second)
+
+ // Clean up
+ chaos.Delete(context.Background())
+ }
+
+ return nil
+}
+```
+
+### Conditional Chaos
+
+```go
+func conditionalChaos(condition bool) error {
+ if !condition {
+ return nil
+ }
+
+ client, err := havoc.NewClient()
+ if err != nil {
+ return err
+ }
+
+ chaos, err := havoc.NewChaos(client, createPodChaos())
+ if err != nil {
+ return err
+ }
+
+ return chaos.Create(context.Background())
+}
+```
+
+### Chaos with Recovery
+
+```go
+func chaosWithRecovery() error {
+ client, err := havoc.NewClient()
+ if err != nil {
+ return err
+ }
+
+ chaos, err := havoc.NewChaos(client, createNetworkChaos())
+ if err != nil {
+ return err
+ }
+
+ // Start chaos
+ err = chaos.Create(context.Background())
+ if err != nil {
+ return err
+ }
+
+ // Monitor system health
+ go func() {
+ for {
+ if isSystemUnhealthy() {
+ // Pause chaos if system is unhealthy
+ chaos.Pause(context.Background())
+ break
+ }
+ time.Sleep(5 * time.Second)
+ }
+ }()
+
+ // Wait for experiment duration
+ time.Sleep(60 * time.Second)
+
+ // Clean up
+ return chaos.Delete(context.Background())
+}
+```
+
+## Testing Integration
+
+### With CTF Framework
+
+```go
+func TestChaosResilience(t *testing.T) {
+ // Setup your application
+ app := setupApplication(t)
+
+ // Create chaos client
+ client, err := havoc.NewClient()
+ require.NoError(t, err)
+
+ // Create chaos experiment
+ chaos, err := havoc.NewChaos(client, createPodChaos())
+ require.NoError(t, err)
+
+ // Start chaos
+ err = chaos.Create(context.Background())
+ require.NoError(t, err)
+
+ // Test application resilience
+ t.Run("application remains functional", func(t *testing.T) {
+ // Your resilience test logic here
+ require.True(t, app.IsHealthy())
+ })
+
+ // Clean up
+ chaos.Delete(context.Background())
+}
+```
+
+### With WASP Load Testing
+
+```go
+func TestChaosUnderLoad(t *testing.T) {
+ // Setup load test
+ profile := wasp.NewProfile()
+ generator := wasp.NewGenerator(&wasp.Config{
+ T: 60 * time.Second,
+ RPS: 100,
+ LoadType: wasp.RPS,
+ Schedule: wasp.Plain(100, 60*time.Second),
+ })
+
+ // Add load test logic
+ generator.AddRequestFn(func(ctx context.Context) error {
+ return performRequest(ctx)
+ })
+
+ profile.Add(generator)
+
+ // Start chaos in background
+ go func() {
+ client, _ := havoc.NewClient()
+ chaos, _ := havoc.NewChaos(client, createNetworkChaos())
+ chaos.Create(context.Background())
+ time.Sleep(30 * time.Second)
+ chaos.Delete(context.Background())
+ }()
+
+ // Run load test
+ _, err := profile.Run(true)
+ require.NoError(t, err)
+}
+```
+
+## Configuration
+
+### Kubernetes Client Configuration
+
+```go
+// Use default kubeconfig
+client, err := havoc.NewClient()
+
+// Use custom kubeconfig
+client, err := havoc.NewClientWithConfig(&rest.Config{
+ Host: "https://kubernetes.example.com",
+ BearerToken: "your-token",
+ TLSClientConfig: rest.TLSClientConfig{
+ Insecure: true,
+ },
+})
+```
+
+### Chaos Mesh Configuration
+
+```go
+// Configure Chaos Mesh namespace
+client, err := havoc.NewClient()
+if err != nil {
+ log.Fatal(err)
+}
+
+// Set Chaos Mesh namespace
+client.SetChaosMeshNamespace("chaos-mesh")
+
+// Configure experiment defaults
+client.SetDefaultDuration("30s")
+client.SetDefaultMode(chaosmesh.OneMode)
+```
+
+## Best Practices
+
+### 1. **Start Small**
+- Begin with simple experiments (pod kill, network latency)
+- Gradually increase complexity
+- Monitor system impact carefully
+
+### 2. **Use Appropriate Selectors**
+```go
+Selector: chaosmesh.PodSelectorSpec{
+ Namespaces: []string{"production"},
+ LabelSelectors: map[string]string{
+ "app": "my-app",
+ "tier": "backend",
+ },
+ // Use specific pod names for targeted testing
+ Pods: map[string][]string{
+ "production": {"my-app-1", "my-app-2"},
+ },
+},
+```
+
+### 3. **Monitor System Health**
+```go
+// Add health monitoring to chaos experiments
+chaos.AddListener(&HealthMonitor{
+ threshold: 0.8, // 80% health threshold
+ onUnhealthy: func() {
+ chaos.Pause(context.Background())
+ },
+})
+```
+
+### 4. **Use Appropriate Durations**
+```go
+Duration: &chaosmesh.Duration{
+ Duration: "30s", // Short for testing
+ // Duration: "5m", // Longer for stress testing
+},
+```
+
+### 5. **Clean Up Properly**
+```go
+defer func() {
+ if chaos != nil {
+ chaos.Delete(context.Background())
+ }
+}()
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Chaos Mesh Not Installed
+```bash
+# Check if Chaos Mesh is installed
+kubectl get pods -n chaos-mesh
+
+# Install Chaos Mesh if needed
+curl -sSL https://mirrors.chaos-mesh.org/v2.6.0/crd.yaml | kubectl apply -f -
+kubectl apply -f https://mirrors.chaos-mesh.org/v2.6.0/rbac.yaml
+kubectl apply -f https://mirrors.chaos-mesh.org/v2.6.0/chaos-mesh.yaml
+```
+
+#### Permission Issues
+```bash
+# Check RBAC permissions
+kubectl auth can-i create networkchaos --namespace default
+kubectl auth can-i create podchaos --namespace default
+
+# Create necessary RBAC rules
+kubectl apply -f rbac.yaml
+```
+
+#### Experiment Not Working
+```bash
+# Check experiment status
+kubectl get networkchaos -n default
+kubectl describe networkchaos network-latency-test
+
+# Check Chaos Mesh logs
+kubectl logs -n chaos-mesh -l app.kubernetes.io/name=chaos-mesh
+```
+
+### Debug Mode
+
+Enable debug logging:
+
+```go
+import (
+ "github.com/rs/zerolog"
+ "github.com/rs/zerolog/log"
+)
+
+// Enable debug logging
+zerolog.SetGlobalLevel(zerolog.DebugLevel)
+log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})
+```
+
+## Examples
+
+Check the [examples directory](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/havoc/examples) for comprehensive examples:
+
+- [Basic chaos experiments](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/havoc/examples/basic)
+- [Network chaos testing](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/havoc/examples/network)
+- [Pod chaos testing](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/havoc/examples/pod)
+- [Integration with CTF](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/havoc/examples/ctf-integration)
+
+## API Reference
+
+For detailed API documentation, see the [Go package documentation](https://pkg.go.dev/github.com/smartcontractkit/chainlink-testing-framework/havoc).
+
+## Contributing
+
+We welcome contributions! Please see the [Contributing Guide](../../Contributing/Overview) for details on:
+
+- Code of Conduct
+- Development Setup
+- Testing Guidelines
+- Pull Request Process
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/LICENSE) file for details.
\ No newline at end of file
diff --git a/Libraries/Seth.md b/Libraries/Seth.md
new file mode 100644
index 000000000..b2022f211
--- /dev/null
+++ b/Libraries/Seth.md
@@ -0,0 +1,708 @@
+# Seth - Ethereum Client Library
+
+[](https://goreportcard.com/report/github.com/smartcontractkit/chainlink-testing-framework/seth)
+[](https://github.com/smartcontractkit/seth/actions/workflows/test_decode.yml)
+[](https://github.com/smartcontractkit/seth/actions/workflows/test_trace.yml)
+[](https://github.com/smartcontractkit/seth/actions/workflows/test_cli.yml)
+[](https://github.com/smartcontractkit/seth/actions/workflows/test_api.yml)
+[](https://github.com/smartcontractkit/seth/actions/workflows/test_cli.yml)
+[](https://github.com/smartcontractkit/seth/actions/workflows/test_decode_testnet.yml)
+
+## Overview
+
+Seth is a reliable and debug-friendly Ethereum client library that provides a thin, debuggable wrapper on top of `go-ethereum`. It's designed to make Ethereum development and testing easier by automatically decoding transaction inputs/outputs/logs and providing advanced debugging capabilities.
+
+## Goals
+
+- **Thin wrapper** on top of `go-ethereum` with minimal overhead
+- **Debuggable** - comprehensive transaction decoding and tracing
+- **Battle tested** - extensive test coverage including testnet integration
+- **Automatic decoding** - decode all transaction inputs/outputs/logs for all ABIs
+- **Simple synchronous API** - easy to use and understand
+- **Resilient** - execute transactions even during gas spikes or RPC outages
+- **Well tested** - comprehensive e2e test suite for testnet integration
+
+## Key Features
+
+### ✅ Implemented Features
+
+- [x] **Decode named inputs** - Automatically decode function parameters
+- [x] **Decode named outputs** - Decode function return values
+- [x] **Decode anonymous outputs** - Handle unnamed return values
+- [x] **Decode logs** - Parse event logs with full context
+- [x] **Decode indexed logs** - Handle indexed event parameters
+- [x] **Decode old string reverts** - Parse legacy revert messages
+- [x] **Decode new typed reverts** - Handle modern revert types
+- [x] **EIP-1559 support** - Full support for London hard fork features
+- [x] **Multi-keys client support** - Use multiple private keys
+- [x] **CLI to manipulate test keys** - Command-line key management
+- [x] **Simple manual gas price estimation** - Built-in gas optimization
+- [x] **Decode collided event hashes** - Handle event signature collisions
+- [x] **Tracing support (4byte)** - Function signature tracing
+- [x] **Tracing support (callTracer)** - Call trace analysis
+- [x] **Tracing decoding** - Decode trace results
+- [x] **Tracing tests** - Comprehensive tracing test coverage
+- [x] **Saving deployed contracts mapping** - Track contract addresses
+- [x] **Reading deployed contracts mappings** - Load contract mappings
+- [x] **Automatic gas estimator** - Intelligent gas price estimation
+- [x] **Block stats CLI** - Block analysis tools
+- [x] **Pending nonce checking** - Prevent nonce conflicts
+- [x] **DOT graph output** - Visualize transaction traces
+- [x] **Gas bumping for slow transactions** - Automatic retry with gas increase
+
+### 🚧 Planned Features
+
+- [ ] **Fail over client logic** - Automatic RPC failover
+- [ ] **Tracing support (prestate)** - Pre-state tracing
+
+## Installation
+
+### Using Go Modules
+```bash
+go get github.com/smartcontractkit/chainlink-testing-framework/seth
+```
+
+### Using Nix (Recommended for Development)
+```bash
+# Install nix
+curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+
+# Enter development shell
+nix develop
+```
+
+## Quick Start
+
+### Basic Usage
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+
+ "github.com/smartcontractkit/chainlink-testing-framework/seth"
+)
+
+func main() {
+ // Create a new Seth client
+ client, err := seth.NewClient("http://localhost:8545")
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Get the latest block number
+ blockNumber, err := client.BlockNumber(context.Background())
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ log.Printf("Latest block: %d", blockNumber)
+}
+```
+
+### With Configuration
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+
+ "github.com/smartcontractkit/chainlink-testing-framework/seth"
+)
+
+func main() {
+ // Create configuration
+ cfg := seth.DefaultConfig("http://localhost:8545", []string{
+ "ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+ })
+
+ // Create client with configuration
+ client, err := seth.NewClientWithConfig(cfg)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Use the client
+ balance, err := client.BalanceAt(context.Background(), client.Addresses[0], nil)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ log.Printf("Balance: %s", balance.String())
+}
+```
+
+## Configuration
+
+### Simplified Configuration
+
+For basic use cases, you can use the simplified configuration:
+
+```go
+cfg := seth.DefaultConfig("ws://localhost:8546", []string{
+ "ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+})
+client, err := seth.NewClientWithConfig(cfg)
+```
+
+This uses reasonable defaults for:
+- Gas price estimation
+- Transaction timeout
+- RPC timeout
+- Gas limit estimation
+
+### TOML Configuration
+
+For more complex setups, use TOML configuration:
+
+```toml
+# seth.toml
+[networks.anvil]
+urls = ["http://localhost:8545"]
+private_keys = ["ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"]
+gas_price_estimation = true
+gas_limit_estimation = true
+gas_bump_percent = 10
+gas_bump_wei = 1000000000
+max_gas_price = 100000000000
+min_gas_price = 1000000000
+gas_bump_threshold = 3
+rpc_timeout = "30s"
+tx_timeout = "5m"
+```
+
+### Environment Variables
+
+Seth supports various environment variables for configuration:
+
+```bash
+# Network configuration
+SETH_NETWORK=anvil
+SETH_URL=http://localhost:8545
+SETH_PRIVATE_KEYS=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+
+# Gas configuration
+SETH_GAS_PRICE_ESTIMATION=true
+SETH_GAS_BUMP_PERCENT=10
+SETH_MAX_GAS_PRICE=100000000000
+
+# Timeout configuration
+SETH_RPC_TIMEOUT=30s
+SETH_TX_TIMEOUT=5m
+```
+
+## Transaction Decoding
+
+### Automatic Decoding
+
+Seth automatically decodes all transaction data when you have the corresponding ABI:
+
+```go
+// Deploy a contract
+contractAddress, tx, _, err := counter.DeployCounter(client.NewTXOpts(), client)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Decode the deployment transaction
+decodedTx, err := client.Decode(tx, nil)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Print decoded information
+fmt.Printf("Contract deployed at: %s\n", contractAddress.Hex())
+fmt.Printf("Gas used: %d\n", decodedTx.GasUsed)
+fmt.Printf("Gas price: %s\n", decodedTx.GasPrice.String())
+```
+
+### Function Call Decoding
+
+```go
+// Call a function
+tx, err := counter.Increment(client.NewTXOpts())
+if err != nil {
+ log.Fatal(err)
+}
+
+// Decode the transaction
+decodedTx, err := client.Decode(tx, nil)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Print function call details
+fmt.Printf("Function: %s\n", decodedTx.FunctionName)
+fmt.Printf("Inputs: %+v\n", decodedTx.Inputs)
+```
+
+### Event Log Decoding
+
+```go
+// Get logs for a specific event
+logs, err := client.FilterLogs(context.Background(), query)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Decode each log
+for _, log := range logs {
+ decodedLog, err := client.DecodeLog(log)
+ if err != nil {
+ continue
+ }
+
+ fmt.Printf("Event: %s\n", decodedLog.EventName)
+ fmt.Printf("Data: %+v\n", decodedLog.Data)
+}
+```
+
+## Transaction Tracing
+
+### Call Tracing
+
+```go
+// Trace a transaction
+trace, err := client.TraceTransaction(context.Background(), txHash)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Print trace information
+fmt.Printf("Trace type: %s\n", trace.Type)
+fmt.Printf("Gas used: %d\n", trace.Result.GasUsed)
+fmt.Printf("Calls: %d\n", len(trace.Result.Calls))
+```
+
+### Function Signature Tracing
+
+```go
+// Get function signature from 4byte database
+signature, err := client.GetFunctionSignature("0xa9059cbb")
+if err != nil {
+ log.Fatal(err)
+}
+
+fmt.Printf("Function signature: %s\n", signature)
+```
+
+### DOT Graph Generation
+
+```go
+// Generate DOT graph for transaction trace
+dotGraph, err := client.GenerateDOTGraph(txHash)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Save to file
+err = os.WriteFile("trace.dot", []byte(dotGraph), 0644)
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+## Gas Management
+
+### Automatic Gas Estimation
+
+```go
+// Enable automatic gas estimation
+cfg := seth.DefaultConfig("http://localhost:8545", []string{privateKey})
+cfg.GasPriceEstimation = true
+cfg.GasLimitEstimation = true
+
+client, err := seth.NewClientWithConfig(cfg)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Transactions will automatically use estimated gas
+tx, err := counter.Increment(client.NewTXOpts())
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### Manual Gas Price Estimation
+
+```go
+// Estimate gas price manually
+gasPrice, err := client.EstimateGasPrice(context.Background())
+if err != nil {
+ log.Fatal(err)
+}
+
+// Use estimated gas price
+opts := client.NewTXOpts()
+opts.GasPrice = gasPrice
+
+tx, err := counter.Increment(opts)
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### Gas Bumping
+
+```go
+// Configure gas bumping
+cfg := seth.DefaultConfig("http://localhost:8545", []string{privateKey})
+cfg.GasBumpPercent = 10
+cfg.GasBumpThreshold = 3
+
+client, err := seth.NewClientWithConfig(cfg)
+if err != nil {
+ log.Fatal(err)
+}
+
+// If transaction is slow, it will be automatically bumped
+tx, err := counter.Increment(client.NewTXOpts())
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+## Multi-Key Support
+
+### Using Multiple Keys
+
+```go
+// Create client with multiple keys
+cfg := seth.DefaultConfig("http://localhost:8545", []string{
+ "key1...",
+ "key2...",
+ "key3...",
+})
+
+client, err := seth.NewClientWithConfig(cfg)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Use specific key for transaction
+opts := client.NewTXKeyOpts(1) // Use second key
+tx, err := counter.Increment(opts)
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### Key Management CLI
+
+```bash
+# List all keys
+seth keys list
+
+# Add a new key
+seth keys add --private-key=0x...
+
+# Remove a key
+seth keys remove --index=0
+
+# Export a key
+seth keys export --index=0
+```
+
+## Contract Management
+
+### Contract Mapping
+
+```go
+// Save contract mapping
+err := client.SaveContractMapping("Counter", contractAddress, abi)
+if err != nil {
+ log.Fatal(err)
+}
+
+// Load contract mapping
+abi, err := client.LoadContractMapping("Counter", contractAddress)
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### ABI Finder
+
+```go
+// Find ABI by contract name
+abi, err := client.FindABI("Counter")
+if err != nil {
+ log.Fatal(err)
+}
+
+// Find ABI by address
+abi, err := client.FindABIByAddress(contractAddress)
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+## Block Analysis
+
+### Block Stats
+
+```go
+// Get block statistics
+stats, err := client.GetBlockStats(context.Background(), blockNumber)
+if err != nil {
+ log.Fatal(err)
+}
+
+fmt.Printf("Block %d:\n", stats.BlockNumber)
+fmt.Printf(" Transactions: %d\n", stats.TransactionCount)
+fmt.Printf(" Gas used: %d\n", stats.GasUsed)
+fmt.Printf(" Gas limit: %d\n", stats.GasLimit)
+fmt.Printf(" Base fee: %s\n", stats.BaseFee.String())
+```
+
+### Block Stats CLI
+
+```bash
+# Get stats for latest block
+seth block stats
+
+# Get stats for specific block
+seth block stats --block=12345
+
+# Get stats for range of blocks
+seth block stats --from=1000 --to=1010
+```
+
+## Advanced Features
+
+### Read-Only Mode
+
+```go
+// Create read-only client
+client, err := seth.NewReadOnlyClient("http://localhost:8545")
+if err != nil {
+ log.Fatal(err)
+}
+
+// Only read operations are allowed
+balance, err := client.BalanceAt(context.Background(), address, nil)
+if err != nil {
+ log.Fatal(err)
+}
+```
+
+### RPC Traffic Logging
+
+```go
+// Enable RPC traffic logging
+cfg := seth.DefaultConfig("http://localhost:8545", []string{privateKey})
+cfg.LogRPC = true
+
+client, err := seth.NewClientWithConfig(cfg)
+if err != nil {
+ log.Fatal(err)
+}
+
+// All RPC calls will be logged
+```
+
+### Bulk Transaction Tracing
+
+```go
+// Trace multiple transactions
+txHashes := []common.Hash{hash1, hash2, hash3}
+traces, err := client.TraceTransactions(context.Background(), txHashes)
+if err != nil {
+ log.Fatal(err)
+}
+
+for i, trace := range traces {
+ fmt.Printf("Transaction %d: %s\n", i, trace.Type)
+}
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run specific test suite
+make test_decode
+make test_trace
+make test_api
+make test_cli
+
+# Run tests on specific network
+make network=Anvil test
+make network=Geth test
+```
+
+### Testnet Integration
+
+```bash
+# Run tests on testnet
+make network=Sepolia test
+make network=Goerli test
+```
+
+## Examples
+
+Check the [examples directory](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/seth/examples) for comprehensive examples:
+
+- [Basic client usage](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/seth/examples/basic)
+- [Contract deployment and interaction](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/seth/examples/contracts)
+- [Transaction tracing](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/seth/examples/tracing)
+- [Gas optimization](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/seth/examples/gas)
+
+## CLI Reference
+
+### Basic Commands
+
+```bash
+# Get help
+seth --help
+
+# Get version
+seth version
+
+# Get network info
+seth network info
+```
+
+### Key Management
+
+```bash
+# List keys
+seth keys list
+
+# Add key
+seth keys add --private-key=0x...
+
+# Remove key
+seth keys remove --index=0
+
+# Export key
+seth keys export --index=0
+```
+
+### Block Analysis
+
+```bash
+# Get block stats
+seth block stats
+
+# Get block info
+seth block info --block=12345
+
+# Get transaction info
+seth tx info --hash=0x...
+```
+
+### Contract Management
+
+```bash
+# Save contract mapping
+seth contract save --name=Counter --address=0x... --abi=path/to/abi.json
+
+# Load contract mapping
+seth contract load --name=Counter --address=0x...
+
+# List contracts
+seth contract list
+```
+
+## Best Practices
+
+### 1. **Use Configuration Files**
+- Store network configurations in TOML files
+- Use environment variables for sensitive data
+- Version control your configurations
+
+### 2. **Handle Errors Gracefully**
+```go
+decodedTx, err := client.Decode(tx, nil)
+if err != nil {
+ // Log error but don't fail the test
+ log.Printf("Failed to decode transaction: %v", err)
+ return
+}
+```
+
+### 3. **Use Appropriate Timeouts**
+```go
+cfg := seth.DefaultConfig("http://localhost:8545", []string{privateKey})
+cfg.RPCTimeout = 30 * time.Second
+cfg.TxTimeout = 5 * time.Minute
+```
+
+### 4. **Monitor Gas Prices**
+```go
+// Check gas price before sending transaction
+gasPrice, err := client.SuggestGasPrice(context.Background())
+if err != nil {
+ log.Fatal(err)
+}
+
+if gasPrice.Cmp(big.NewInt(100000000000)) > 0 {
+ log.Printf("High gas price: %s", gasPrice.String())
+}
+```
+
+### 5. **Use Tracing for Debugging**
+```go
+// Enable tracing for complex transactions
+trace, err := client.TraceTransaction(context.Background(), txHash)
+if err != nil {
+ log.Printf("Failed to trace transaction: %v", err)
+} else {
+ log.Printf("Transaction trace: %+v", trace)
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Transaction Decoding Fails
+- Ensure you have the correct ABI for the contract
+- Check if the contract address is correct
+- Verify the transaction hash is valid
+
+#### Gas Estimation Issues
+- Check if the RPC node supports gas estimation
+- Verify the transaction parameters are valid
+- Consider using manual gas price estimation
+
+#### Tracing Not Available
+- Ensure your RPC node supports tracing
+- Check if tracing is enabled on the node
+- Use a different RPC endpoint if needed
+
+### Debug Mode
+
+Enable debug logging:
+
+```bash
+export SETH_LOG_LEVEL=debug
+go test -v
+```
+
+## API Reference
+
+For detailed API documentation, see the [Go package documentation](https://pkg.go.dev/github.com/smartcontractkit/chainlink-testing-framework/seth).
+
+## Contributing
+
+We welcome contributions! Please see the [Contributing Guide](../../Contributing/Overview) for details on:
+
+- Code of Conduct
+- Development Setup
+- Testing Guidelines
+- Pull Request Process
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/LICENSE) file for details.
\ No newline at end of file
diff --git a/Libraries/WASP.md b/Libraries/WASP.md
new file mode 100644
index 000000000..75f543122
--- /dev/null
+++ b/Libraries/WASP.md
@@ -0,0 +1,532 @@
+# WASP - Load Testing Library
+
+
+
+[](https://goreportcard.com/report/github.com/smartcontractkit/wasp)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/wasp-test.yml)
+[](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/wasp-test-e2e.yml)
+
+
+**Scalable protocol-agnostic load testing library for Go**
+
+