🛡️ Soroban Budget Assert
Protocol 22 • soroban-sdk v22.0.0

Stop Guessing Smart Contract Costs.
Empirical Budget Assertions for Soroban.

Local Soroban resource estimates do not match real network costs. In empirical testnet benchmarks, local Rust estimates ran ~81% under actual costs, while WASM-mode estimates swung from ~8% under to ~19% over.
soroban-budget-assert provides empirical budget certainty before on-chain execution.

Get Started Read Documentation Join Discord

The Cost-Gap Problem

Real measured figures comparing local estimates against Soroban Testnet ground truth for do_expensive_work(10_000).

Native Rust Estimate
143,887
−81.0% vs Network

Native Rust test execution (no WASM). Unreliable for budget decisions.

WASM Release Profile
767,049
−7.8% vs Network

Compiled with Cargo's default release profile (opt-level=3).

WASM Size-Opt Profile
901,816
+19.2% vs Network

Compiled with size optimization (opt-level="z", LTO enabled).

Soroban Testnet Ground Truth
756,678
Network Baseline

Actual CPU instructions returned by simulateTransaction on testnet.

⚠️
Why this matters: A developer trusting unverified local numbers either deploys a contract that exhausts its budget on the public network, or over-provisions against costs that aren't real. The only trustworthy figure is a network simulation of the exact WASM you deploy.

Two-Tier Defense System

Combine fast local test assertion gates with network-verified workspace reporting.

Tier A • Fast & Local

budget-macros

Local, Fast, CI-Blocking Assertion Macros

Rust attribute macros (#[budget_cpu_lt(N)], #[budget_mem_lt(N)]) applied directly to your test functions.

  • Fails cargo test the moment cost crosses pinned limit
  • Catches cost regressions locally in CI before deploying
  • Reads env.cost_estimate().budget() automatically
Tier B • Network-Verified

cargo-budget-report

CLI Workspace Discovery & Network Verification

A CLI tool that discovers contracts, compiles WASM, and simulates execution against Soroban Testnet.

  • Automatically discovers all contracts in your workspace
  • Simulates execution on Testnet via simulateTransaction
  • Reports execution resources (CPU instructions, read/write bytes)
  • Configurable via central budget.toml

Quick Start

Get up and running in under a minute.

💻 1. Install CLI Tool 
# Install cargo-budget-report from repository root
cargo install --path cargo-budget-report

# Run report across workspace
cargo budget-report
⚙️ 2. Configure budget.toml 
network = "testnet"
source = "alice"

[functions.do_expensive_work]
args = ["--n", "10000"]
🦀 3. Add Macro Assertions in Tests 
use budget_macros::{budget_cpu_lt, budget_mem_lt};
use soroban_sdk::Env;

#[test]
#[budget_cpu_lt(950000)] // Fails test if CPU instruction budget exceeds limit
fn test_cpu_budget() {
    let env = Env::default();
    let wasm = std::fs::read("../target/wasm32v1-none/release/my_contract.wasm")
        .expect("build the WASM first");
    let contract_id = env.register_contract_wasm(None, wasm.as_slice());
    let client = MyContractClient::new(&env, &contract_id);

    env.cost_estimate().budget().reset_unlimited();
    client.do_expensive_work(&10_000);
}

See It in Action

Watch cargo budget-report simulate and report execution resources across workspace contracts.

Having trouble viewing the embedded demo? Watch the terminal recording on Asciinema.