# Bunsan RPC Loadbalancer

![Dynamic TOML Badge](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fronnakamoto%2Fbunsan%2Frefs%2Fheads%2Fmaster%2FCargo.toml&query=%24.package.version&style=for-the-badge&label=crates.io%20-%20bunsan) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ronnakamoto/bunsan/release.yml?style=for-the-badge)


Bunsan(分散) is a high-performance, multi-chain RPC (Remote Procedure Call) load balancer designed for Ethereum and other EVM-compatible blockchain networks. It efficiently distributes incoming RPC requests across multiple nodes, ensuring optimal resource utilization and improved reliability for blockchain applications.

## Features

- **Multi-Chain Support**: Seamlessly handle requests for multiple EVM-compatible chains (e.g., Ethereum, Aurora, Optimism, Arbitrum, BNB Smart Chain, etc.).
- **Flexible Chain Selection**: Support multiple methods for specifying the target chain in requests.
- **Connection Pooling**: Efficiently manage and reuse connections to improve performance and reduce overhead.
- **Dynamic Load Balancing**: Choose from multiple load balancing strategies (Round Robin, Least Connections, Random) for each chain.
- **Highly Extensible via Extensions**: Bunsan supports extension that add capabilities to Bunsan's http layer. Eg. [near-mpc-accounts](https://github.com/ronnakamoto/bunsan-extensions/tree/main/near-mpc-accounts) brings Chain Abstraction via NEAR's MPC into Bunsan.
- **Health Checking**: Continuously monitor node health and automatically route traffic to healthy nodes.
- **Configuration Hot-Reloading**: Update configuration without restarting the service.
- **Detailed Metrics**: Access real-time health and performance metrics for all configured chains and nodes.
- **Benchmarking Tools**: Evaluate and compare the performance of different load balancing strategies.

## Supported Chains
Bunsan supports the following chains out of the box:

- Ethereum Mainnet (Chain ID: 1)
- Aurora Testnet (Chain ID: 1313161555)
- Optimism (Chain ID: 10)
- Arbitrum One (Chain ID: 42161)
- BNB Smart Chain (Chain ID: 56)
- BNB Smart Chain Testnet (Chain ID: 97)
- Sepolia Testnet (Chain ID: 11155111)
- OP Sepolia Testnet (Chain ID: 11155420)
- Arbitrum Sepolia Testnet (Chain ID: 421614)
- Base Sepolia Testnet (Chain ID: 84532)
- Base (Chain ID: 8453)
- Polygon Mainnet (Chain ID: 137)
- Polygon zkEVM (Chain ID: 1101)
- Polygon Amoy (Chain ID: 80002)
- Polygon zkEVM Testnet (Chain ID: 1442)
- Scroll (Chain ID: 534352)
- Scroll Sepolia Testnet (Chain ID: 534351)
- Taiko Mainnet (Chain ID: 167000)
- Neon EVM Mainnet (Chain ID: 245022934)
- Neon EVM Devnet (Chain ID: 245022926)

## Detailed Documentation

Visit Bunsan's Github Wiki page for detailed documentation - https://github.com/ronnakamoto/bunsan/wiki

## Installation

### Using Cargo

If you have Rust installed on your system, you can globally install Bunsan via

```bash
cargo install bunsan
```

### Pre-built Binaries

You can download pre-built binaries for Bunsan from the [Releases](https://github.com/ronnakamoto/bunsan/releases) page. We provide binaries for:

- Linux (x86_64)
- Windows (x86_64)
- macOS (x86_64 / Intel)
- macOS (arm64 / Apple Silicon)

Download the appropriate binary for your system and make it executable (on Unix-based systems):

```bash
chmod +x bunsan-*
```

### Building from Source

1. Clone the repository:
   ```
   git clone https://github.com/ronnakamoto/bunsan.git
   cd bunsan
   ```

2. Build the project:
   ```
   cargo build --release
   ```

3. The compiled binary will be available at `target/release/bunsan`.

## Configuration

Bunsan uses a TOML configuration file. By default, it looks for `config.toml` in the current directory. You can specify a custom configuration file path using the `--config` option.

Example configuration:

```toml
server_addr = "127.0.0.1:8080"
update_interval = 60

[connection_pool]
max_size = 100
min_idle = 10
max_lifetime = 3600       # in seconds
idle_timeout = 600        # in seconds
connection_timeout = 5000 # in milliseconds

[[chains]]
name = "Ethereum"
chain_id = 1
chain = "Ethereum"
load_balancing_strategy = "LeastConnections"
nodes = [
    "https://1rpc.io/eth",
    "https://eth.drpc.org",
    "https://eth.llamarpc.com",
    "https://ethereum.blockpi.network/v1/rpc/public",
]

[[chains]]
name = "Aurora Testnet"
chain_id = 1313161555
chain = "AuroraTestnet"
load_balancing_strategy = "LeastConnections"
nodes = [
    "https://testnet.aurora.dev",
    "https://endpoints.omniatech.io/v1/aurora/testnet/public",
    "https://aurora-testnet.drpc.org",
]

[[chains]]
name = "Arbitrum One"
chain_id = 42161
chain = "Arbitrum"
load_balancing_strategy = "Random"
nodes = [
    "https://1rpc.io/arb",
    "https://arbitrum.blockpi.network/v1/rpc/public",
]

[[chains]]
name = "BNB Smart Chain Mainnet"
chain_id = 56
chain = "BNBSmartChain"
load_balancing_strategy = "LeastConnections"
nodes = ["https://1rpc.io/bnb", "https://bsc.blockpi.network/v1/rpc/public"]
```

## Usage

### Starting the Server

To start the Bunsan RPC Loadbalancer:

```
./bunsan start
```

Or with a custom configuration file:

```
./bunsan start --config /path/to/your/config.toml
```

### Command-Line Interface

Bunsan provides several CLI commands for management and monitoring:

- `start`: Start the RPC loadbalancer server
- `health`: Check the health of all configured nodes
- `config`: Display the current configuration
- `validate`: Validate the configuration file
- `nodes`: List all connected nodes and their status
- `benchmark`: Run performance benchmarks
- `tx`: Retrieve transaction details
- `install-extension`: Install a new extension
- `list-extensions`: List all installed extensions
- `uninstall-extension`: Remove an installed extension
- `run-extension`: Execute a command from an installed extension

For more information on each command, use the `--help` option:

```
./bunsan --help
```

If you plan to run the benchmarks, please make sure to first auto-generate the config by running Bunsan first via `start` option.

### Making RPC Requests

Bunsan supports multiple methods for specifying the target chain in your RPC requests:

1. **Chain-specific endpoints**: Use dedicated endpoints for each chain.
   ```
   POST http://localhost:8080/eth
   POST http://localhost:8080/aurora-testnet
   POST http://localhost:8080/arb
   POST http://localhost:8080/bnb
   ```

2. **General endpoint with chain parameter**: Specify the chain in the URL path.
   ```
   POST http://localhost:8080/ethereum
   POST http://localhost:8080/optimism
   POST http://localhost:8080/arbitrum
   POST http://localhost:8080/bnbsmartchain
   ```

3. **Custom header**: Use the `X-Chain-ID` header to specify the chain.
   ```
   POST http://localhost:8080
   X-Chain-ID: ethereum
   ```
   ```
   POST http://localhost:8080
   X-Chain-ID: aurora-testnet
   ```
4. **Default chain**: If no chain is specified, Bunsan defaults to Ethereum.
   ```
   POST http://localhost:8080
   ```

Example using curl:

```bash
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:8080/eth
```

### Retrieving Transaction Details

To retrieve transaction details, use the `tx` command:

```bash
./bunsan tx <TRANSACTION_HASH> [--chain <CHAIN_NAME> | -n <CHAIN_NAME>] [--fields <COMMA_SEPARATED_FIELDS>]
```

`<TRANSACTION_HASH>`: The transaction hash (required)
`--chain` or `-n`: The chain name (optional, defaults to Ethereum)
`--fields`: Comma-separated list of fields to include in the response (optional)

Example:

```bash
./bunsan tx 0x951455413adad08c7062e8179d13df599210c3af264b83fad519319de82458d4 -n base
```

## Load Balancing Strategies

Bunsan supports the following load balancing strategies:

1. **Round Robin**: Distributes requests evenly across all healthy nodes in a circular order.
2. **Least Connections**: Sends new requests to the node with the fewest active connections.
3. **Random**: Randomly selects a healthy node for each request.

You can configure different strategies for each chain in the configuration file.

## Using Extensions

Bunsan supports extensions to enhance its functionality. Here's how you can work with extensions:

### Installing Extensions

To install an extension, use the following command:

```bash
bunsan install-extension <extension-name>
```

This command will download and install the specified extension from the Bunsan extensions repository.

Bunsan extensions are hosted on a [GitHub repository](https://github.com/ronnakamoto/bunsan-extensions).
The first extension available is `near-mpc-accounts`, that exposes HTTP endpoints via Bunsan to allow developers leverage NEAR's Chain Abstraction via Chain Signatures, easily.
Checkout the [near-mpc-accounts extension's documentation](https://github.com/ronnakamoto/bunsan-extensions/tree/main/near-mpc-accounts) for more details.

### Listing Installed Extensions

To see a list of all installed extensions, use:

```bash
bunsan list-extensions
```

This will display the name, version, and description of each installed extension.

### Uninstalling Extensions

To remove an installed extension, use:

```bash
bunsan uninstall-extension <extension-name>
```

### Running Extension Commands

To run a command provided by an installed extension, use:

```bash
bunsan run-extension <extension-name> <command> [args...]
```

Replace `<extension-name>` with the name of the extension, `<command>` with the specific command you want to run, and `[args...]` with any additional arguments required by the command.

## Benchmarking

To run benchmarks and compare the performance of different load balancing strategies:

```
./bunsan benchmark --duration 60 --requests-per-second 100
```

This will simulate load on all configured chains and strategies, providing detailed performance metrics.

## Monitoring and Metrics

Bunsan exposes a `/health` endpoint that provides real-time information about the status of all chains and nodes. You can access this endpoint using a GET request:

```
curl http://localhost:8080/health
```

## License

Bunsan is released under the MIT License. See the `LICENSE` file for details.

## Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

---

Thank you for using Bunsan RPC Loadbalancer!