Self-Host Guide

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

Supported EntryPoint versions

Alto supports EntryPoint v0.6, v0.7, v0.8 and v0.9, and EIP-7702 user operations. Pass the EntryPoint contracts you want to serve to --entrypoints as a comma-separated list:

EIP-7702 support is on by default. To reject user operations that include an EIP-7702 authorization, run Alto with --eip-7702-support false.

Installation (Building from source)

Building Alto needs Node.js 24, pnpm and Foundry (to compile the contracts). To install and build Alto from source, run the following commands

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

And then to list all of Alto's options, 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.

Safe mode

By default, Alto runs in safe mode: it enforces all ERC-4337 validation rules, including the ERC-7562 opcode, storage access and reputation rules. These rules reject user operations that pass simulation but could behave differently on-chain, which protects a bundler that accepts user operations from anyone against denial-of-service attacks. To enforce them, Alto traces every validation with a JavaScript tracer, so safe mode needs an RPC that supports debug_traceCall with JavaScript tracers.

• Keep safe mode on if your bundler is publicly reachable or accepts user operations from parties you don't control, and point Alto at an RPC that supports debug_traceCall.
• Run with --safe-mode false if your RPC doesn't support debug_traceCall and your bundler only accepts user operations from your own app or other sources you trust. Alto then skips the ERC-7562 checks, so a malicious user operation could make the bundler submit bundles that revert and waste gas.

The examples below use --safe-mode false because most hosted RPCs don't support debug_traceCall.

Running

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

./alto \
    --entrypoints "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789,0x0000000071727De22E5E9d8BAf0edAc6f37da032,0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108" \
    --executor-private-keys "0x34e9a7...,0xb08d34...,0x163cbb..." \
    --utility-private-key "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": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789,0x0000000071727De22E5E9d8BAf0edAc6f37da032,0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108",
    "executor-private-keys": "0x34e9a7...,0xb08d34...,0x163cbb...",
    "utility-private-key": "0xe768f1...",
    "rpc-url": "http://localhost:8545",
    "safe-mode": false
}

Run Alto using alto-config.json configurations

./alto --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 --legacy-transactions ...

OP Stack Chains

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

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

Arbitrum Chains

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

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