Crate soroban_fork 

soroban-fork

Lazy-loading mainnet / testnet fork for Soroban tests.

Think Foundry’s Anvil, but for Stellar Soroban. When a test reads a ledger entry that isn’t cached, it’s fetched from the Soroban RPC on the fly. State changes are local only — the real network is never mutated. On drop, lazy-fetched entries can be persisted to disk in the standard stellar snapshot create format, so a second run is fully local.

use soroban_fork::ForkConfig;

let env = ForkConfig::new("https://soroban-testnet.stellar.org:443")
    .cache_file("fork_cache.json")
    .build()
    .expect("fork setup");

// `env` derefs to `soroban_sdk::Env`, backed by real network state.
env.mock_all_auths();

Error handling

ForkConfig::build returns Result<ForkedEnv, ForkError> so transport, cache, and XDR errors are all recoverable. Inside the VM loop — where the trait signature forbids returning errors — the source honors FetchMode::Strict (panic on transport failure) or FetchMode::Lenient (log + treat entry as missing).

Logging

The crate uses the log facade — no output appears unless the test binary initializes a logger (e.g. env_logger). Typical invocation:

RUST_LOG=soroban_fork=info cargo test

Re-exports

pub use auth_tree::AuthTree;

pub use trace::Trace;

pub use trace::TraceFrame;

pub use trace::TraceResult;

pub use workspace::workspace_wasm;

pub use workspace::workspace_wasm_in;

pub use workspace::workspace_wasm_with;

Modules

auth_tree

Authorization-tree introspection for forked environments.

fees

Live-network resource-fee computation for simulateTransaction.

test_accounts

Pre-funded deterministic accounts the fork mints at build time — ten Stellar accounts pre-loaded with XLM and a USDC trustline, ready to sign envelopes against.

trace

Call-tree tracing for forked environments.

workspace

Workspace contract WASM builder — closes the include_bytes! rebuild trap.

Structs

FetchedEntry

A single fetched ledger entry, with the live-until hint from the RPC.

ForkConfig

Builder for a ForkedEnv. All fields have sensible defaults — the only required input is the RPC URL.

ForkedEnv

A forked Soroban environment backed by real network state.

LatestLedger

Snapshot of the latest closed ledger as reported by the RPC.

NetworkMetadata

Network metadata from the getNetwork RPC response.

RpcClient

Typed RPC client. One instance per fork, reused across fetches so reqwest can pool connections to the RPC.

RpcConfig

Tuning for the RPC transport layer.

RpcSnapshotSource

A SnapshotSource backed by a Soroban RPC + local cache.

Enums

FetchMode

Policy for how the source reacts to transport failures inside the VM loop.

ForkError

The crate’s unified error type.

Type Aliases

Result

Convenience alias — every public API returns this.