# Developers' Guide: How Wax Lost Weight 🏋️ ![squeezing-wax-small.png](https://images.hive.blog/DQmNQBeUEFyboq1fQitJGKXimvqBusZKH3PYZzyGG56MmHt/squeezing-wax-small.png) # Developers' Guide: How Wax Lost Weight 🏋️ Hey Hive community! 👋 As promised in this [article](hive-139531/@thebeedevs/afj7u-decentralized-google-login) below is detailed info how we did it. Enjoy ! ## 🤓 For the Nerds: Technical Deep Dive We imagine you might be interested in how we achieved such a significant size improvement in a project as complex as the Wax library (which mixes core Hive C++ code with TypeScript/JavaScript interfaces). Below, we share the key steps and ideas behind this "magic" change. Our old motto is: *It's not a big deal to achieve complex goals by using lots of source code and dependencies—the real trick is simplicity and a minimal amount of code (both source and generated binary) to limit maintenance, resource consumption, and execution costs...* Since the size of the Wax NPM package was mostly dominated by the internally held WASM code, focusing on reducing this part was the obvious decision. ### Step 1: Improved emSDK Toolchain The [Emscripten](https://emscripten.org/) toolchain we use to build the C++ portion of Wax targeting WASM has been improving significantly lately. No surprise there—WASM is one of the cutting-edge technologies these days. The obvious approach was to upgrade from the 3.0 series and early 4.0 releases we used in the past, which hadn't provided any significant improvements. But... Yes—there were some changes that allowed us to go further, where previously it was very troublesome. How did we do it? Well, our infrastructure is mostly based on Docker images, which allow us to efficiently manage our development environments by combining external tool upgrades with our own changes. We updated the [common-ci-configuration](https://gitlab.syncad.com/hive/common-ci-configuration/-/commit/1fbe7147a58e5938e4dda5ba25953054b428fe62) module to use a new emsdk Docker image (version 4.0.22 series). Although it didn't immediately lead us to *low-hanging fruit* and instant benefits after the upgrade, it offered—in my humble opinion—something much more important: the ability to analyze WASM binaries using other WASM tools. We had tried a few months ago and it was impossible—the produced WASM binary was simply incompatible with WASM targets built by Rust or other tools (like WABT). --- ### Step 2: emsdk 4.0.22 with -Oz Optimized System Libraries **What changed in common-ci-configuration:** - Now all system libraries (especially Boost, OpenSSL) are compiled with the **-Oz** optimization level. Some of these libraries are built on our side to provide better compatibility with the underlying C++ code shared directly with the Hive protocol library. - This propagates size savings across ALL linked code, not just our source. The above trivial step—which, honestly, we had missed when we first discovered how much space could be saved (in the direct Wax code build) by using the `-Oz` switch instead of the default `-O3` in Release WASM builds—gave us benefits: close to hundreds of kilobytes. But the results were still disappointing. We still had a binary exceeding 5MB. 😥 --- ### Step 3: Additional wasm-opt Binaryen Passes HA ‼️ The new compiler, thanks to newer underlying Binaryen tools (responsible for binary code generation), also offered the ability to perform post-build optimizations at low risk. This is the big one! We added a custom set of Binaryen optimization passes that run after the initial WASM compilation: ```diff # ts/wasm/src/CMakeLists.txt DEFINE_WASM_TARGET_FOR( wax TARGET_ENVIRONMENT "web" LINK_LIBRARIES hive_protocol LINK_OPTIONS -sNO_DYNAMIC_EXECUTION=1 -sALLOW_MEMORY_GROWTH=1 + -sBINARYEN_EXTRA_PASSES="--all-features,-Oz,--strip-debug,--strip-dwarf,--strip-producers,--remove-unused-names,--remove-unused-module-elements,--vacuum,--duplicate-function-elimination,--merge-similar-functions" ) DEFINE_WASM_TARGET_FOR( wax TARGET_ENVIRONMENT "node" LINK_LIBRARIES hive_protocol LINK_OPTIONS -sALLOW_MEMORY_GROWTH=1 + -sBINARYEN_EXTRA_PASSES="--all-features,-Oz,--strip-debug,--strip-dwarf,--strip-producers,--remove-unused-names,--remove-unused-module-elements,--vacuum,--duplicate-function-elimination,--merge-similar-functions" ) ``` That was the first breath of fresh spring! (Even though winter was coming. 😊) 500 kB less! 🍾 **Breakdown of each pass:** | Pass | Description | | ------ | ------------ | | `--all-features` | Enable all WASM features for maximum optimization opportunities | | `-Oz` | Optimize aggressively for size | | `--strip-debug` | Remove debug information | | `--strip-dwarf` | Remove DWARF debugging data | | `--strip-producers` | Remove producer section (compiler metadata) | | `--remove-unused-names` | Strip unnecessary function/variable names | | `--remove-unused-module-elements` | Dead code elimination at module level | | `--vacuum` | Remove obviously unneeded code | | `--duplicate-function-elimination` | Merge identical functions into one | | `--merge-similar-functions` | Merge functions that differ only slightly | **Result:** ~500 kB reduction from this single change! 🎯 But what to do next? The black box. Yes, this was one of our biggest problems: how could we look inside the WASM binary package, how could we split it logically, and—**most importantly**—how could we associate it with the source code to answer the question: what led the compiler to produce so much binary code? --- ### Step 4: Black Magic: What's Under the Black Box Cover? Simple Answer: The Evil. Here we could offer some not-so-kind words about the code generated by the Emscripten compiler—it was *guilty*, producing tons of trash. Not exactly. We needed an exorcist—a.k.a. a hacker. :-) OK, let's get back down to earth: we needed tools. And we got them—thanks to the compiler upgrade mentioned above. Due to the standardized format of the produced WASM binary, analysis by third-party tools became possible. `twiggy` is our hero... It was the tool that allowed us to peer into the produced binary. And what we saw... was a big surprise. 😃 ### 🔬 How to Analyze WASM Binary Size (Developer Guide) To make things easier for everyone doing Wax development in our group, we added professional binary analysis tools to our emsdk Docker image to help with optimization efforts. #### Available Tools | Tool | Description | Best For | | ---- | ----------- | -------- | | **twiggy** | WASM-specific size profiler | Function-level analysis, dominators | | **bloaty** | Google's binary size profiler | Compile units, DWARF analysis | | **wasm-objdump** | WABT disassembler | Section breakdown, raw details | | **wasm-opt** | Binaryen optimizer | Metrics, optimization passes | #### Investigation Workflow **Step 1: Get section breakdown** ```bash wasm-objdump -h wax.common.wasm ``` **Step 2: Get overall metrics** ```bash wasm-opt --all-features --metrics wax.common.wasm ``` Example output: ``` [funcs] : 9405 [memory-data] : 1777632 # 🔴 Static data - often the biggest culprit! Try : 31448 # 🔴 Exception handling blocks Rethrow : 24515 # 🔴 Exception rethrowing ``` **Step 3: Find top size consumers** ```bash twiggy top -n 50 wax.common.wasm ``` Example output: ``` Shallow Bytes │ Shallow % │ Item ───────────────┼───────────┼────────────────────── 1114324 ┊ 24.42% ┊ data[83] # 🔴 1.1MB data segment! 185555 ┊ 4.07% ┊ data[0] 28393 ┊ 0.62% ┊ code[174] # Largest function 14475 ┊ 0.32% ┊ code[4568] ``` **Step 4: Analyze dominators (what removal would save)** ```bash twiggy dominators -n 50 wax.common.wasm ``` **Step 5: Look for common bloat patterns** ```bash # Search for exception handling, RTTI, Boost, fc library twiggy top wax.common.wasm | grep -E "(cxa_|typeinfo|boost|fc::|std::)" # Extract strings to find embedded data strings wax.common.wasm | sort | uniq -c | sort -rn | head -100 # Find type names, error messages strings wax.common.wasm | grep -E "hive::|fc::|error|exception" | head -50 ``` YEAH—we're not blind anymore! Now it was time to figure out what was contained in this huge data segment... #### Interpreting Data Segments You can see large `data[N]` segments in twiggy output (the example below dumps part of the biggest one): ```bash # Check if it's strings or binary data wasm-opt --all-features --print wax.common.wasm > wax.wat grep -A 5 "(data (;83;)" wax.wat | head -20 ``` The question was: what kind of data could be there? Potential answers: - **Readable strings** → Error messages, type names, JSON keys - **Binary data (escape sequences like `\a8\cde`)** → Crypto tables, lookup tables A quick conversation with an AI chat about potential sources of such large data segments led us to secp256k1, which has precompiled lookup tables—and fortunately, options to reduce its size: For crypto tables (like secp256k1), the build step shown below allows reducing precomputation data size by ~1 MB: ```bash # When building secp256k1 ./configure --with-ecmult-window=4 --with-ecmult-gen-precision=2 ``` We also created a small local script to improve the workflow and speed up iterations during the optimizations: #### Quick Size Check Script ```bash #!/bin/bash WASM_FILE="$1" echo "=== Section Sizes ===" wasm-objdump -h "$WASM_FILE" echo -e "\n=== Metrics ===" wasm-opt --all-features --metrics "$WASM_FILE" echo -e "\n=== Top 20 Size Consumers ===" twiggy top -n 20 "$WASM_FILE" echo -e "\n=== Potential Bloat Patterns ===" twiggy top "$WASM_FILE" | grep -E "(cxa_|typeinfo|boost|fc::|exception)" || echo "None found" ``` We gained this magical skill to look into the produced binary. But we still needed to associate the binary data with C++ source code parts and calculate/estimate their impact on WASM size. To do this, we simply re-enabled debug symbol generation in our WASM (which made it huge again, but also allowed us to find the sources matching each binary code section). Here are the results: #### Common Bloat Sources in C++ → WASM | Source | Typical Impact | How to Detect | | ------ | -------------- | ------------- | | **secp256k1 precomputation tables** | 500 kB–1.5 MB | Large `data[N]` segments with binary data | | **C++ exceptions** | 100 kB–500 kB+ | Look for `__cxa_throw`, high `Try`/`Rethrow` counts | | **RTTI (dynamic_cast)** | 50 kB–200 kB | Look for `typeinfo`, `__dynamic_cast` | | **iostream/formatting** | 200 kB–500 kB | Look for `std::ostream`, `basic_string` | | **FC library reflection** | 200 kB–1 MB | Look for `fc::` namespace, string literals | | **Template instantiations** | Varies | Repeated patterns with different types | | **Debug symbols/names** | 500 kB–2 MB | Check "name" section with `wasm-objdump -h` | The above analysis and further digging into the C++ code brought us a few other optimization ideas... ### Step 5: Centralized Exception Handling in the fc Library We already knew that enabling exception handling in Emscripten builds led to a significant binary size increase. It was easy to verify by simply removing the dedicated switches from the compiler command line. The problem was that we needed exceptions to make the code work correctly. To understand why these changes helped, some deeper knowledge is needed—specifically about the ways the compiler chooses to generate exception handler code and perform code generation for C++ templates. Using another great tool, [Clang Build Analyzer](https://github.com/aras-p/ClangBuildAnalyzer), showed us exactly how many template instantiations are performed by the compiler. This led us to `fc::raw::pack`/`fc::raw::unpack` and the reflection visitor, which had thousands of instantiations. Some of them are eliminated at the end by the linker, but a lot of binary code was still generated from them. Further quick tests (done in a trivial way by simply eliminating parts of code from such template functions) allowed us to identify the culprit. 👉 **The Problem:** The `FC_RETHROW_EXCEPTIONS` macro was being used inline in template code, specifically in `fc::raw::unpack`. Since templates are instantiated for every type, this meant: - ~3 catch handlers generated per template instantiation - Hundreds of template instantiations = thousands of duplicate exception handlers - Massive code bloat in the final binary **The Solution:** We introduced the `unpack_error_handler` class, which moves the exception handling logic from inline template code to a **single non-template function** whose code is generated only once. You can find its definition [here](https://gitlab.syncad.com/hive/fc/-/blob/main/include/fc/exception/exception.hpp?ref_type=heads#L333). Below is an illustration of the idea: how to preserve runtime behavior while eliminating binary code bloat. ```cpp // Before: Exception handling duplicated in every template instantiation, // leading to significant code bloat template void unpack(Stream& s, T& value, uint32_t, bool limit_is_disabled ) { try { // unpack logic unpack_object_visitor visitor( v, s, limit_is_disabled ); } FC_RETHROW_EXCEPTIONS(warn, "error unpacking ${type}", ("type", fc::get_typename::name())) } // After: Exception handling centralized—a single exception handler implemented // inside the `call` method wraps client code passed as a functor (lambda expression) template void unpack( Stream& s, T& v, uint32_t, bool limit_is_disabled ) { unpack_object_visitor visitor( v, s, limit_is_disabled ); unpack_error_handler error_handler( fc::get_typename::name()); error_handler.call( /// Actual code to call: real unpack body [&visitor]() { fc::reflector::visit( visitor ); }, /// Helper code to improve error messaging and provide the name of the /// field being processed when the exception was thrown [&visitor]() { return visitor.get_field_name(); } ); } ``` **Result:** Significant reduction in binary size by eliminating redundant exception handling code across all protocol type serialization. --- ### Step 6: Excluding Virtual Operations via HIVE_PROTOCOL_SKIP_VOPS The above template code generation analysis led us to another idea: cutting things down by reducing the set of blockchain operations to include only those that can be part of a transaction. Virtual operations (vops) are operations generated by the blockchain itself—they're never submitted by users. Examples include `author_reward_operation`, `curation_reward_operation`, `fill_order_operation`, etc. **The Problem:** The `hive::protocol::operation` type is an `fc::static_variant` containing ALL operation types. Each type in the variant generates: - Serialization/deserialization code - Visitor handlers - Type metadata With **43 virtual operation types** that Wax never needs to create or sign, that's a lot of dead code! **The Solution:** We added a compile definition that conditionally excludes virtual operations from the operation variant: ```cmake # ts/wasm/src/CMakeLists.txt (line 19) add_compile_definitions(HIVE_PROTOCOL_SKIP_VOPS) ``` This triggers the `#ifndef HIVE_PROTOCOL_SKIP_VOPS` guards in the protocol headers: ```cpp // core/operations_fwd.hpp // Regular operations (always included) transfer_operation, vote_operation, comment_operation, // ... 49 regular operations total #ifndef HIVE_PROTOCOL_SKIP_VOPS , /// virtual operations below this point (EXCLUDED from WASM build!) fill_convert_request_operation, author_reward_operation, curation_reward_operation, comment_reward_operation, // ... 43 virtual operations total #endif ``` **Result:** Removing 43 types from the static variant eliminates all their associated template instantiations, significantly reducing binary size. --- ### Step 7: Minimal OpenSSL Build for WASM As is typical in an optimization process, eliminating larger bottlenecks (large binary code sections in our case) uncovered other *culprits* and made it worthwhile to try optimizing them as well. OpenSSL is notoriously large, but we only need a small subset of its functionality for cryptographic operations in Wax. **Commit:** [3fc2ac36](https://gitlab.syncad.com/hive/common-ci-configuration/-/commit/3fc2ac36782f9980f1cfec5d676f7e411932221f) - *Optimize OpenSSL build for minimal WASM size* **Disabled Features:** | Category | Disabled | | -------- | -------- | | Protocols | SSL, TLS, DTLS, SSL3 | | Algorithms | DSA, DH, RC2, RC4, RC5, Blowfish | | Features | CMS, OCSP, SRP, PSK, timestamps, CT, compression | | I/O | stdio, sockets | | Debug | Error strings, auto error init, filenames | **Compiler Flags Applied:** ```bash -fvisibility=hidden # Hide internal symbols -ffunction-sections # Place each function in its own section -fdata-sections # Place each data item in its own section --gc-sections # Garbage collect unused sections at link time ``` **Result:** Dramatically smaller OpenSSL footprint—only the essential crypto primitives remain! --- ### 🔮 Future Optimization Ideas (Internal Notes) We're not done yet! Here are potential optimizations we're exploring for future releases: #### 1. Strip fc Error Messages & File References **Potential savings:** ~150 kB The `fc` library embeds error messages with `__FILE__` and `__func__` macros for debugging. Stripping these could save significant space, but we're **not ready yet**—we don't have all error hashes properly handled for production error reporting. > **Note:** Just removing `__FILE__` and `__func__` alone saves only ~1 kB—the real savings come from stripping the full error message strings. #### 2. LTO (Link-Time Optimization) **Status:** ❌ Not viable currently We tested `-flto=thin` but it actually **increased** binary size. This is counterintuitive but can happen when LTO inlines aggressively or when the optimizer makes different trade-offs. This needs more investigation. #### 3. Replace std::string with a Lightweight Alternative **Potential approach:** `std::string` → Custom class → `fc::string` The standard library string implementation carries overhead. A minimal string class tailored for our use cases could reduce both code size and memory footprint. #### 4. Replace fc::static_variant with Virtual Visitor Pattern **Proposed by:** @small.minion Instead of using `fc::static_variant` (which generates template code for every type combination), we could: - Create a standard abstract base class - Implement the classical virtual visitor pattern - Trade some runtime performance for significant code size reduction This would eliminate the template instantiation explosion that static variants cause. #### 5. Non-Template Stream Operations **Idea:** Replace `template` with `void*`-based streams Current stream operations are templated, generating separate code for each stream type. Using type-erased streams (via `void*` or abstract base) would reduce code duplication at the cost of some type safety. #### 6. Separate binary_view + fc::raw into a Dedicated WASM Module **Potential savings:** ~400 kB (estimated, may overlap with other optimizations) The binary view functionality and raw serialization could be split into a separate WASM module that's loaded on demand. This would: - Reduce initial bundle size - Allow lazy loading for features not always needed - Enable independent optimization of each module #### 7. Explicit FC_REFLECT Instantiation **Approach:** Define all reflection code in a single `.cpp` file Currently, `FC_REFLECT` macros may instantiate template code in multiple translation units. Consolidating all reflection definitions into one compilation unit could enable better dead code elimination and reduce duplicate instantiations. #### 8. Awaiting Other Compiler and WASM Improvements This is the most tedious part for us. 🤣 I'm joking, of course. 😊 But honestly, our hopes are not unfounded. The last few months brought another WASM standard: [WASM 3.0](https://webassembly.org/news/2025-09-17-wasm-3.0/). There is an important note related to exception handling, which is a crucial part of every modern language: ``` Previously, there was no efficient way to compile exception handling to Wasm ``` The introduction of new standardized WASM features gives us hope that this will be done much better. The deeper integration with the JS stack that they promise also looks great. --- This programming adventure that our task turned into finally resulted in reducing the Wax package size from 5.6 MB to 3.4 MB (uncompressed size). Happy building! 🐝 @mtyszczak from @thebeedevs