Search…
⌃K

Protobuf Schemas

StreamingFast Substreams protobuf schemas

Protobuf Overview

Substreams uses Protocol Buffers (protobufs) as the API for data models specific to each blockchain. Each manifest defines references to the protobufs for the Substreams implementation.
Tip: Protobufs define the input and output for modules.

Protobuf Basics

Protobufs are Google's language-neutral extensible mechanism for serializing structured data. Protobufs are similar to XML but smaller, faster, and simpler.
Additional information can be found for Protocol Buffers by visiting the links provided below.
Google Protocol Buffer Documentation
Google Protocol Buffer Tutorial

Protobuf Definition

Define a protobuf model as proto:eth.erc721.v1.Transfers representing a list of ERC721 transfers.
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
}
View this file in the repo by visiting the following link.

Identifying Data types

The ERC721 smart contract associated with the Substreams Template example contains a Transfer event. The event is targeted by creating an associated protobuf.
The protobuf file serves as the interface between the module handlers and the data being provided by Substreams.
Tip: Protobufs are chain agnostic and can be 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 implementation will dictate the number of and complexity of protobufs.
Note: The Substreams Template example targets Transfer events associated with the Bored Ape Yacht Club smart contract, located on the Ethereum blockchain.
Multitudes of more specific data types exist in the Ethereum smart contract ecosystem, some extending the ERC20 and ERC721 base implementations. Developers can create more refined and complex protobufs based on the many custom data types that exist in the blockchain they are targeting.
Tip: Using fully qualified paths for protobuf files reduces the risk of naming conflicts when other community members build their Substreams packages.

Generating Protobufs

The Substreams CLI is used to generate the associated Rust code for the protobuf.
Tip: Notice the protogen command and Substreams manifest passed into the CLI.
substreams protogen ./substreams.yaml --exclude-paths="sf/ethereum,sf/substreams,google"
The Rust code is generated and saved into src/pb/eth.erc721.v1.rs
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
#[path = "eth.erc721.v1.rs"]
#[allow(dead_code)]
pub mod erc721;
View this file in the repo by visiting the following link.