Protobuf schemas
StreamingFast Substreams protobuf schemas
Substreams uses Google Protocol Buffers extensively. Protocol Buffers, also referred to as protobufs, are used as the API for data models specific to the different blockchains. Manifests contain references to the protobufs for your Substreams module.
Tip: Protobufs define the input and output for modules.
Learn more about the details of Google Protocol Buffers in the official documentation provided by Google.
Google Protocol Buffer Documentation
Google Protocol Buffer Tutorial
Note: The
Transfers
protobuf in the Substreams Template example is located in the proto directory.eth/erc721/v1/erc721.proto
1
syntax = "proto3";
2
3
package eth.erc721.v1;
4
5
message Transfers {
6
repeated Transfer transfers = 1;
7
}
8
9
message Transfer {
10
bytes from = 1;
11
bytes to = 2;
12
uint64 token_id = 3;
13
bytes trx_hash = 4;
14
uint64 ordinal = 5;
15
}
The ERC721 smart contract used in the Substreams Template example contains a
Transfer
event. You can use the event data through a custom protobuf.The protobuf file serves as the interface between the module handlers and the data being provided by Substreams.
Tip: Protobufs are platform-independent and are defined and used for various blockchains.
- The ERC721 smart contracts used in the Substreams Template example are generic contracts used across many different Ethereum applications.
- The size and scope of the Substreams module dictates the number of and complexity of protobufs.
The Substreams Template example extracts
Transfer
events from the Bored Ape Yacht Club smart contract which is located on the Ethereum blockchain.Several specific data types exist in the Ethereum smart contract ecosystem, some extending the ERC20 and ERC721 base modules. Complex protobufs are created and refined based on the various data types used across the different blockchains.
Tip: The use of fully qualified protobuf file paths reduces the risk of naming conflicts when other community members build their Substreams packages.
substreams protogen ./substreams.yaml --exclude-paths="sf/ethereum,sf/substreams,google"
The
mod.rs
file located in the src/pb
directory of the Substreams Template example is responsible for exporting the freshly generated Rust code.src/pb/mod.rs
1
#[path = "eth.erc721.v1.rs"]
2
#[allow(dead_code)]
3
pub mod erc721;
Protocol buffers define fields' type by using standard primitive data types, such as integers, booleans, and floats or a complex data type such as
message
, enum
, oneof
or map
. View the full list of types in the Google Protocol Buffers documentation.Note: The standard approach to represent nullable data in Rust is to wrap optional values in
Option<T>
.match person.Location {
Some(location) => { /* Value is present, do something */ }
None => { /* Value is absent, do something */ }
}
if let Some(location) = person.location {
// Value is present, do something
}
Note: You need to be absolutely sure the field is always defined, otherwise Substreams panics and never completes, getting stuck on a block indefinitely.
PROST! is a tool for generating Rust code from protobuf definitions. Learn more about
prost
in the project's official GitHub repository.Last modified 3d ago