Self-Host Guide

This guide holds all information related to self hosting your own Alto bundler instance. Including installation, setting up, running, and troubleshooting.

Installation (Building from source)

To install and build Alto from source, run the following commands

git clone https://github.com/pimlicolabs/alto.git
pnpm install
pnpm build

And then to start Alto, run

./alto help

Setup And Prerequisites

Alto manages multiple executor wallets. If any wallet's balance falls below a set minimum, its balance is automatically refilled using funds from the utility wallet. The utility wallet needs to be funded before starting Alto.

By default, Alto will run in safe mode. This means that it will validate all userOps against the ERC-7562 validation rules. In safe mode, you will need a RPC that supports the debug_traceCall endpoint. It is reccomended to run Alto with this flag disabled by setting --safe-mode false.

Running

Once all the prerequisite conditions are met, Alto can be started using

./alto run
    --entrypoints "0x0000000071727De22E5E9d8BAf0edAc6f37da032,0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
    --executor-private-keys "0x34e9a7...,0xb08d34...,0x163cbb..."
    --utility-private-keys "0xe768f1..."
    --rpc-url "http://localhost:8545"
    --safe-mode false

Running Alto using JSON configurations

Alto can also be ran using configurations from a JSON file

Create and setup alto-config.json

{
    "entrypoints": "0x0000000071727De22E5E9d8BAf0edAc6f37da032,0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
    "executor-private-keys": "0x34e9a7...,0xb08d34...,0x163cbb...",
    "utility-private-keys": "0xe768f1...",
    "rpc-url": "http://localhost:8545",
    "safe-mode": false
}

Run Alto using alto-config.json configurations

./alto run --config "alto-config.json"

compatibility

Some chains have certain compatibility restrictions that require Alto to be ran with special flags.

Legacy Transaction Chains

For chains that only support pre EIP-1559 transactions, alto needs to be ran with the flag

./alto run --legacy-transactions ...

OP Stack Chains

For chains that are deployed using the OP Stack, alto needs to be ran with the flag

./alto run --chain-type "op-stack" ...

Arbitrum Chains

For chains that are deployed using Arbitrum, alto needs to be ran with the flag

./alto run --chain-type "arbitrum" ...