Upgrading is optional. A module pinned to substreams 0.7 keeps building and streaming. If you want the speed-up, use one consistent set of crate versions, swap prost for buffa, delete the generated bindings, and rebuild with Substreams CLI v1.25.0 or later.
Why upgrade?
Substreams 0.8.0 generates Rust bindings with buffa instead of prost. Modules decode blocks 2.9x to 4.9x faster depending on the chain, and the real backfills measured finished up to 2.9x faster end to end. buffa uses lazy views that borrow from the input buffer, so a handler pays only for the fields it reads. The protobuf wire format is identical, so cached outputs, existing packages, sinks and Go or JavaScript consumers are unaffected. A new project from substreams init already uses buffa.
Which versions go together?
Every crate must come from the same row, or two incompatible copies of substreams end up in the dependency tree.
substreams | substreams-ethereum | substreams-solana | substreams-database-change | Protobuf |
|---|---|---|---|---|
| 0.8.0 | 0.12.0 | 0.16.0 | 5.0.0 | buffa |
| 0.7.x | 0.11.x | 0.15.x | 3.x, 4.x | prost |
| 0.6.x | 0.10.x | 0.14.x | 2.x | prost |
What are the steps?
- In
Cargo.toml, removeprostandprost-types; addbuffa = "0.9.2"andbuffa-types = "0.9.2"; setsubstreams = "0.8.0"and the matching chain crates. - Delete
buf.gen.yamlandsrc/pb. - Run
substreams buildto regenerate bindings. - Update handler code (for example
is_some()becomesis_set(), anduse buffa::Message;withdecode_from_slice).
The CLI reads Cargo.toml to pick the protobuf plugin, so add buffa before building or you will get prost bindings that do not compile against 0.8.0. The full steps are in Migrating from prost to buffa.
What errors might I hit?
the trait bound 'MyMessage: Message' is not satisfied. The type came from prost codegen. Confirm Cargo.toml names buffa, delete buf.gen.yaml and src/pb, and rebuild.
rust-lld: error: duplicate symbol: alloc. Two versions of substreams are linked. Run cargo tree -i substreams to find the crate pinning a pre-0.8 version; substreams-entity-change 2.0.0 is the usual cause.
Frequently asked questions
Do I need to upgrade my AI coding skills? Yes, update the Substreams agent skills along with your crates so the assistant generates buffa APIs, not prost ones.
Will it change my output? No, the wire format is unchanged.
Get an API key at thegraph.market.
Related: How do I speed up a Substreams backfill? · What is Substreams? · How do I test a Substreams package?