> For the complete documentation index, see [llms.txt](https://tollcraft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tollcraft.gitbook.io/docs/budget-assert/readme.md).

# Introduction

`soroban-budget-assert` solves a specific problem in the Stellar ecosystem: local resource estimates do not match real network costs, and the error can point in either direction.

Measured on this repo's example contract (`do_expensive_work(10_000)`, testnet ground truth 756,678 CPU instructions):

* Raw Rust test estimates ran **\~81% under** the network cost (143,887 locally).
* WASM-mode estimates depend on the build profile: with Cargo's default release profile they ran \~8% *under* the network cost of that build (767,049 vs 832,006), and with the standard Soroban size-optimization profile they run **\~19% over** (901,816 vs 756,678).

{% hint style="warning" %}
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: the only trustworthy number is a network simulation of the exact WASM you deploy.
{% endhint %}

This tool provides both halves of the fix: `cargo budget-report` measures network-simulated resource usage across a whole workspace, and the `budget_macros` assertions pin measured costs into `cargo test` so a cost regression fails CI before it fails on-chain.

{% hint style="info" %}
Scope: the report covers execution resources — CPU instructions and ledger read/write bytes. Those are inputs to the non-refundable resource fee, not a total transaction fee: rent, refundable fees, transaction size, footprint entry counts, and the inclusion fee are not measured. [Measurement scope](/docs/budget-assert/reference.md#measurement-scope) sets out the boundary and points at where to find the rest.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tollcraft.gitbook.io/docs/budget-assert/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.