tollcraft. /soroban-cost-profiler

soroban cost awareness

Stop guessing your gas bill.

A three-tier cost pipeline for Stellar smart contracts. Lint at compile time, assert at test time, profile when the budget fails, so every CPU instruction and storage byte is accounted for before mainnet.

explore the pipeline view on github
▸ 3 open tools ▸ zero instrumentation ▸ dwarf source mapping
~/contracts/swap-pool / linter
soroban-cost-linter check src/
▸ analyzing 42 functions … done 14ms
[!] WARNING: Unbounded loop detected Function: `process_all_users` Location: src/lib.rs:42 Details: loop lacks budget constraint or max iterations
[!] WARNING: High instantiation cost Function: `init_heavy_struct` Location: src/lib.rs:105 Details: struct size exceeds 4KB, will cause high gas on heap alloc
~/contracts/swap-pool / tests
cargo test test_swap_budget
▸ running 1 test test test_swap_budget ... FAILED
failures:
---- test_swap_budget ---- BudgetAssertionError: Expected max CPU instructions: 10,000,000 Actual CPU instructions: 12,450,192 Overage: +24.5%
Failed at src/test.rs:88
8.4M instructions traced
source-mapped to rust
~/contracts/swap-pool / profiler
soroban-cost-profiler --trace swap_pool.wasm ▸ tracing wasm execution … done 412ms ▸ mapping dwarf → source … done 89ms
8,431,720 cpu instructions total 1,092 host function calls 97.4% spent in 3 functions
swap_depth_loop 61%
nested_auth_check 22%
ledger_write_every 13%
other 4%
swap_depth_loop / 5,172,090 / 61%

hover a frame for details / click to zoom

the pipeline

Three tools, one cost pipeline.

Each tier catches a different failure mode. Used together they close the loop: prevent at compile time, detect at test time, diagnose when a budget breaks.

01 / prevent at compile time

Cost Linter

Static analysis inside the compiler. Flags structurally expensive code (storage writes in loops, unbounded iteration) before cargo build even finishes.

open repository
02 / detect at test time

Budget Assert

Simulates your contract against the network. Measures exact cpu and io spend per invocation and fails CI the moment you cross your budget.

open repository
03 / diagnose at failure time

Cost Profiler

Traces every WASM instruction and maps it back to your Rust source. A flamegraph that names the function that ate your budget.

open repository

the workflow

How to profile a contract.

Profiling your cost doesn't require modifying your contract code. Simply build with debug symbols and trace the local WASM execution.

compile time

catch the pattern

The linter reads your code the way the compiler does, and stops expensive structures at the door.

test time

measure the bill

Budget assert executes real invocations on a simulated network and reports the exact cpu and io cost.

failure time

trace the culprit

When a budget fails, the profiler walks every instruction and tells you precisely where it went.

Frequently Asked Questions.

No. The profiler hooks directly into the local WASM execution engine. You only need to compile your binary with DWARF debug info.

You shouldn't. The required debug tables will heavily bloat your binary size, resulting in significantly higher on-chain deployment fees.

No. The profiler traces execution locally in a simulated test environment. It does not query mainnet or testnet transactions.

The profiler will still generate a valid trace. For panics, you'll see the cost leading up to the failure. For infinite loops, it gracefully halts and outputs a partial trace.

Aggressive compiler optimizations like LTO (Link-Time Optimization) and inlining can merge functions. Downstream tools may also strip debug sections, causing coarse line mappings.