How to optimize Stylus WASM binaries
This document is currently in public preview and may change significantly as feedback is captured from readers like you. Click the Request an update button at the top of this document or join the Arbitrum Discord to share your feedback.
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
Third-party optimization tooling
Additional WASM-specific tooling exists to shrink binaries. Due to being 3rd 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.
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.