Back to Common Questions

Common Questions / Troubleshooting

How do I upgrade to Substreams 0.8 (prost to buffa)?

Updated

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.

substreamssubstreams-ethereumsubstreams-solanasubstreams-database-changeProtobuf
0.8.00.12.00.16.05.0.0buffa
0.7.x0.11.x0.15.x3.x, 4.xprost
0.6.x0.10.x0.14.x2.xprost

What are the steps?

  1. In Cargo.toml, remove prost and prost-types; add buffa = "0.9.2" and buffa-types = "0.9.2"; set substreams = "0.8.0" and the matching chain crates.
  2. Delete buf.gen.yaml and src/pb.
  3. Run substreams build to regenerate bindings.
  4. Update handler code (for example is_some() becomes is_set(), and use buffa::Message; with decode_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?