📢 stable-structures v0.7.0 Released — Major BTreeMap Speedups and Breaking API Changes

Developers
1

Hi everyone,

We’ve just released stable-structures v0.7.0, a major update focused on significant performance improvements.

Note: This release introduces breaking changes to the public API :warning:

:wrench: Highlights

  • Faster BTreeMap
    • Insert avoids cloning by using into_bytes (breaking API) :warning:
    • New lazy iterator improves scan performance (breaking API) :warning:
    • Batched read/write of child nodes and faster traversal logic
  • Breaking API Changes
    • Public methods now panic on unrecoverable failures instead of returning Result :warning:
  • Better Benchmarks
    • Expanded coverage: NNS, principal keys, I/O chunking
    • Benchmarks show big wins: median −5.16% :green_circle:, some scans −98% :green_circle:
  • Improved CI & Docs
    • Colored CI logs, custom branches benchmarking, and clearer docs

:bar_chart: Benchmark Summary (vs v0.6.7)

  • BTreeMap
    • 303 benchmarks: 24 regressed, 203 improved
    • Worst regression: +13.6% :red_circle:
    • Improvements: median −5.16% :green_circle:, best up to −98% :green_circle:
  • I/O Chunks & NNS
    • I/O reads and writes improved: worst -0%, median -49% :green_circle:, best up to −83% :green_circle:
    • NNS voting benchmarks improved: worst -0%, median -21% :green_circle:, best up to −52% :green_circle:
  • More data here

:world_map: Migration Guide

To upgrade to v0.7.0, fix any build errors by applying the following changes:

  • Implement into_bytes for your types to support the updated API
  • Update iteration logic: instead of (key, value) tuples, iterate over entry objects and use entry.key() and entry.value() to lazily access data
  • Remove .unwrap() where methods no longer return Result — these now panic on misuse

:folded_hands: Thanks to All Contributors

@maksymar, @ielashi — and everyone testing, benchmarking, and providing feedback!

Let us know how this version performs in your projects!

11 Likes
2

Great to hear about the performance improvements :flexed_biceps:. Is there a migration guide available for the breaking changes, or are they fundamentaly trivial?

2 Likes
3

Migration to a new API is trivial, just fix build errors:

  • remove .unwrap() for the cases that were returning Result
  • implement into_bytes for your data types
  • instead of iterating tuples (key, value) iterate over entry and access keys/values with entry.key()/entry.value()

That’s it!

Thank you for pointing this out, I updated the original post with instructions.

2 Likes
4

Nice! Thanks the additional description :+1:

1 Like
5

Hi, apart from the changes in the API, has anything changed in how the data is persisted? Can we safely upgrade our production canisters from 0.6 to 0.7?

6

Hi, there are no changes to how data is persisted in v0.7.0, so existing data layouts remain compatible.

That said, since the release includes breaking API changes, I’d recommend testing the upgrade in your staging environment first to ensure everything works smoothly with your setup.

6 Likes
7

I haven’t tested it on mainnet yet, but I upgraded the Juno codebase today and my small set of tests is passing (PR) :white_check_mark:. No issues so far, thanks again for the few notes you shared above, they were really useful!

I also had to upgrade ic-wasi-polyfill for compatibility reasons. Shoutout to @sgaflv for releasing a new version on the same day I reported the “issue” :raising_hands:

Side note: Not sure if it’s best practice at all but just in case, I added a set of helpers / utils in the PR to collect the new entry pattern into a map and vec. Sharing if useful to others.

2 Likes