🛡️ Soroban Budget Assert

Empirical cost measurement and assertion tooling for Soroban smart contracts.

Documentation · Demo

---

📖 Overview

soroban-budget-assert is a developer tool that measures the gap between local Soroban test estimates and real network costs. It allows developers to assert budget limits during testing and automatically generate detailed cost reports across an entire workspace.

🏗️ Architecture

The tool is split into two primary components:

1. budget-macros (Tier A - Local, Fast, CI-Blocking)

   • Rust macros (#[budget_cpu_lt(N)], #[budget_mem_lt(N)]) applied directly to your test functions.
   • Fails the test the moment measured cost crosses your pinned limit, so cost regressions are caught in CI instead of on the network.

2. cargo-budget-report (Tier B - Network-Verified, Reporting)

   • A CLI tool that automatically discovers all contracts in your workspace.
   • Compiles WASM, simulates execution on testnet, and reports actual non-refundable costs (CPU instructions, read/write bytes).
   • Configurable via a central budget.toml file.

---

🚀 Quick Start

1. Installation

Install the CLI tool locally from the repository root:

cargo install --path cargo-budget-report

2. Configuration

Create a budget.toml in your workspace root:

network = "testnet"
source = "alice"

[functions.do_expensive_work]
args = ["--n", "10000"]

3. Usage

Generate a Workspace Report:

cargo budget-report

Use Macros in Tests:

use budget_macros::budget_cpu_lt;

#[test]
#[budget_cpu_lt(800000)]
fn test_expensive_function() {
    let env = Env::default();
    // ... test logic ...
}

---

🤝 Community & Maintainers

Join the discussion and get support:

• Community Link: Stellar Developer Discord

Maintainer	Role	Telegram
Tollcraft Team	Core Developers	@tollcraft

---

🛠️ Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details on how to get started, and our SECURITY.md for reporting vulnerabilities.

🧑‍💻 Contributors