Budget Assert Overview

Tier 2 • Detect

Empirical runtime cost enforcement for Soroban smart contracts — simulate invocations against live network metering inside cargo test and gate pull requests against resource regressions.

Part of the Tollcraft initiative:

• Tier 1: Prevent — Cost Linter: Catch structurally expensive anti-patterns before compilation.
• Tier 2: Detect — Budget Assert: Measure network-simulated costs and enforce budgets in CI.
• Tier 3: Diagnose — Cost Profiler: Trace execution and generate visual flamegraphs down to Rust lines.

---

The Divergence Problem

soroban-budget-assert solves a critical failure mode in Soroban smart contract engineering: local resource estimates do not match real network costs, and the error can point in either direction.

Measured on an example contract (do_expensive_work(10_000)):

Empirical Resource Divergence vs. Network Truth

RAW RUST TEST

-81%

143,887 inst. (Dangerously under-estimates CPU!)

SIZE-OPT WASM

+19%

901,816 inst. (Over-provisions against phantom costs)

TESTNET GROUND TRUTH

756,678

Exact Protocol 22 Network Simulation

The only trustworthy number is a live network simulation

A developer who trusts local numbers either deploys a contract that exhausts its budget on the public network, or over-provisions against costs that aren't real. Both mistakes come from the same root cause: mock environments do not execute the exact Stellar Core metering VM.

---

The Solution: Two-Tier Verification

soroban-budget-assert gives you the best of both worlds:

1. Tier A (Local Fast Assertions): Deterministic test assertions via #[budget_cpu_lt(N)] that run in milliseconds in your normal cargo test suite.
2. Tier B (Network-Verified CI Gating): cargo budget-report deploys the exact compiled WASM to a test network, simulates RPC invocations, and fails CI on any regression beyond a configured tolerance threshold.

# Check your workspace against budget limits
cargo budget-report --check --network testnet

---

Documentation Navigation

Getting Started

To wire assertions into your test suite, start with the End-User Guide. To set up automated CI budget gating, see the CI/CD Integration Guide.

• End-User Guide — Step-by-step walkthrough of macros, baseline snapshots, and commands
• Complete CLI & Config Reference — All flags, budget.toml schema, and environment variables
• Deriving Limits — How to calculate safe Tier A local limits from Tier B network measurements
• CI/CD Integration Guide — GitHub Actions workflow and PR summary generation
• Testnet Troubleshooting — Handling RPC timeouts, sequence numbers, and funding
• Developer Guide — Architecture, internals, and building from source