Configuration

Galene reads galene.toml from the working directory on galene start. Point it elsewhere with --config <file>. Everything is optional: with no config, Galene uses built-in defaults (mainnet, empty fork).

The file does two jobs. It sets the fork source, and it declares a starting sandbox.

The fork source

Oceanus, the copy-on-read layer, draws upstream state from this endpoint. Any tx or query that references an object or package not in the local store is fetched on demand from rpc, cached locally, and every read or write after that hits the local copy. Upstream is a read-only source of truth; your writes stay local. Galene forks each network’s latest state.

[fork]
network = "mainnet"
rpc = "https://fullnode.mainnet.sui.io:443"

The transport is negotiated per endpoint on first use. Galene prefers Sui’s gRPC interface (sui.rpc.v2) and falls back to JSON-RPC for self-hosted or older nodes. The same URL serves both, so no extra config is needed.

network is the Sui client env alias used by galene replay and galene graph when you don’t pass --network. It’s a label: the real fork source is whatever rpc URL you point at, so you can fork any Sui network or a private fullnode.

Only mainnet ships as a built-in default. For any other network you set rpc yourself; network is just the label Galene reports. To fork testnet instead of mainnet, swap the endpoint:

[fork]
network = "testnet"
rpc = "https://fullnode.testnet.sui.io:443"

A declarative starting sandbox (Thalassa)

Instead of firing cheatcodes by hand after boot, declare the starting state in galene.toml. Galene applies it on galene start, in order: clock, epoch, sender, packages, objects, mints, faucet, gas.

Each table maps to the matching cheatcode, so the declared state and the live API can never drift.

[clock]
timestamp_ms = 1750000000000   # set the on-chain Clock (0x6)
 
[epoch]
number = 42                    # advance the epoch to here (from genesis)
 
[sender]
address = "0x9f2e...d9f2e"     # the active (impersonated) sender
 
[[mint]]                       # mint a coin of an explicit type
type = "0x2::sui::SUI"
amount = 5000000000
recipient = "0x9f2e...d9f2e"
 
[[faucet]]                     # mint by known symbol (or full `coin = "..."`)
symbol = "USDC"
amount = 100000000
recipient = "0x9f2e...d9f2e"
 
[[object]]                     # seed a raw object
id = "0x3a7f...1f3a"
type = "0x6d8f...2d4f::pool::Pool"
owner = "0x9f2e...d9f2e"
 
[[gas]]                        # fund an address with a gas coin
address = "0x9f2e...d9f2e"
amount = 1000000000
 
[[package]]                    # override an existing package's bytecode
id = "0x6d8f...2d4f"
modules = { my_module = "<base64 bytecode>" }

Standalone scenarios

Keep the scenario in its own file and apply it with --scenario <file.toml>. It uses the same tables as above. A standalone scenario replaces the inline tables from galene.toml.

galene start --scenario whale-sandbox.toml

Reload a dumped fork

A scenario rebuilds state from declarations. To restore an exact fork instead, dump it with galene_dumpState and reload it on boot:

galene start --load-state fork.json