Skip to main content

How to optimize Stylus WASM binaries

To be deployed onchain, the size of your uncompressed WebAssembly (WASM) file must not exceed 128Kb, while the compressed binary must not exceed 24KB. Stylus conforms with the same contract size limit as the EVM to remain fully interoperable with all smart contracts on Arbitrum chains.

cargo-stylus, the Stylus CLI tool, automatically compresses your WASM programs, but there are additional steps that you can take to further reduce the size of your binaries.

Your options fall into two categories: Rust compiler flags, and third-party optimization tools.

Rust compiler flags​

The Rust compiler supports various config options for shrinking binary sizes.

Cargo.toml​

[profile.release]
codegen-units = 1        # prefer efficiency to compile time
panic = "abort"          # use simple panics
opt-level = "z"          # optimize for size ("s" may also work)
strip = true             # remove debug info
lto = true               # link time optimization
debug = false            # no debug data
rpath = false            # no run-time search path
debug-assertions = false # prune debug assertions
incremental = false      # no incremental builds

Nightly Rust flags (advanced)​

If standard release flags still leave you over budget, nightly Rust offers a flag that strips the panic-formatting infrastructure entirely:

cargo +nightly -Z build-std=std,panic_abort -Zbuild-std-features=panic_immediate_abort

Combined with disabling storage caching, this can shave roughly 20% off binary size on small contracts.

Use nightly flags at your own risk

Nightly compiler flags are unstable and may change between toolchain releases. Always re-run cargo stylus check after enabling them to confirm the resulting binary is still valid.

If your contract still exceeds the size limit after these optimizations, consider splitting functionality across multiple Stylus contracts and composing them via inter-contract calls.

Third-party optimization tooling​

Additional WASM-specific tooling exists to shrink binaries. Due to being third party, users should use these at their own risk.

wasm-opt​

wasm-opt applies techniques to further reduce binary size, usually netting around 10%.

twiggy​

twiggy is a code size profiler for WASM, it can help you estimate the impact of each added component on your binaries' size.

Inspecting WASM opcodes​

To examine the WebAssembly instructions in your compiled contract, convert the binary to WebAssembly Text format using the WABT toolkit:

wasm2wat contract.wasm -o contract.wat

For one-off inspection without installing tools, use the online wasm2wat demo.

Our team has also curated a list of recommended libraries that are helpful to Stylus development and optimally sized.

Frequently asked questions​

Will future releases of Stylus introduce additional optimizations?​

Yes! We're actively working on improving WASM sizes generated by Rust code with the Stylus SDK.

Why don't I have to worry about this type of optimization when I use cargo without using Stylus?​

On modern platforms, tools like cargo don’t have to worry about the size of the binaries they produce. This is because there’s many orders of magnitude more storage available than even the largest of binaries, and for most applications it’s media like images and videos that constitutes the majority of the footprint.

Resource constraints when building on blockchains are extremely strict. Hence, while not the default option, tooling often provides mechanisms for reducing binary bloat, such as the options outlined in this document.