@@ -4,46 +4,39 @@ package sf.substreams.rpc.v2;
44
55import "google/protobuf/any.proto" ;
66import "substreams.proto" ;
7- import "firehose.proto" ;
87
9- service EndpointInfo {
10- rpc Info ( sf.firehose.v2.InfoRequest ) returns (sf.firehose.v2.InfoResponse );
8+ service Stream {
9+ rpc Blocks ( Request ) returns (stream Response );
1110}
1211
13- service Stream { rpc Blocks (Request ) returns (stream Response ); }
14-
1512message Request {
1613 int64 start_block_num = 1 ;
1714 string start_cursor = 2 ;
1815 uint64 stop_block_num = 3 ;
1916
2017 // With final_block_only, you only receive blocks that are irreversible:
21- // 'final_block_height' will be equal to current block and no 'undo_signal'
22- // will ever be sent
18+ // 'final_block_height' will be equal to current block and no 'undo_signal' will ever be sent
2319 bool final_blocks_only = 4 ;
2420
25- // Substreams has two mode when executing your module(s) either development
26- // mode or production mode . Development and production modes impact the
27- // execution of Substreams, important aspects of execution include:
21+ // Substreams has two mode when executing your module(s) either development mode or production
22+ // mode. Development and production modes impact the execution of Substreams, important aspects
23+ // of execution include:
2824 // * The time required to reach the first byte.
2925 // * The speed that large ranges get executed.
3026 // * The module logs and outputs sent back to the client.
3127 //
32- // By default, the engine runs in developer mode, with richer and deeper
33- // output. Differences between production and development modes include:
34- // * Forward parallel execution is enabled in production mode and disabled in
35- // development mode
36- // * The time required to reach the first byte in development mode is faster
37- // than in production mode.
28+ // By default, the engine runs in developer mode, with richer and deeper output. Differences
29+ // between production and development modes include:
30+ // * Forward parallel execution is enabled in production mode and disabled in development mode
31+ // * The time required to reach the first byte in development mode is faster than in production mode.
3832 //
3933 // Specific attributes of development mode include:
4034 // * The client will receive all of the executed module's logs.
41- // * It's possible to request specific store snapshots in the execution tree
42- // (via `debug_initial_store_snapshot_for_modules`).
35+ // * It's possible to request specific store snapshots in the execution tree (via `debug_initial_store_snapshot_for_modules`).
4336 // * Multiple module's output is possible.
4437 //
45- // With production mode`, however, you trade off functionality for high speed
46- // enabling forward parallel execution of module ahead of time.
38+ // With production mode`, however, you trade off functionality for high speed enabling forward
39+ // parallel execution of module ahead of time.
4740 bool production_mode = 5 ;
4841
4942 string output_module = 6 ;
@@ -54,24 +47,23 @@ message Request {
5447 repeated string debug_initial_store_snapshot_for_modules = 10 ;
5548}
5649
50+
5751message Response {
5852 oneof message {
59- SessionInit session = 1 ; // Always sent first
60- ModulesProgress progress = 2 ; // Progress of data preparation, before
61- // sending in the stream of `data` events.
53+ SessionInit session = 1 ; // Always sent first
54+ ModulesProgress progress = 2 ; // Progress of data preparation, before sending in the stream of `data` events.
6255 BlockScopedData block_scoped_data = 3 ;
6356 BlockUndoSignal block_undo_signal = 4 ;
6457 Error fatal_error = 5 ;
6558
66- // Available only in developer mode, and only if
67- // `debug_initial_store_snapshot_for_modules` is set.
59+ // Available only in developer mode, and only if `debug_initial_store_snapshot_for_modules` is set.
6860 InitialSnapshotData debug_snapshot_data = 10 ;
69- // Available only in developer mode, and only if
70- // `debug_initial_store_snapshot_for_modules` is set.
61+ // Available only in developer mode, and only if `debug_initial_store_snapshot_for_modules` is set.
7162 InitialSnapshotComplete debug_snapshot_complete = 11 ;
7263 }
7364}
7465
66+
7567// BlockUndoSignal informs you that every bit of data
7668// with a block number above 'last_valid_block' has been reverted
7769// on-chain. Delete that data and restart from 'last_valid_cursor'
@@ -92,14 +84,16 @@ message BlockScopedData {
9284 repeated StoreModuleOutput debug_store_outputs = 11 ;
9385}
9486
95- message SessionInit {
87+ message SessionInit {
9688 string trace_id = 1 ;
9789 uint64 resolved_start_block = 2 ;
9890 uint64 linear_handoff_block = 3 ;
9991 uint64 max_parallel_workers = 4 ;
10092}
10193
102- message InitialSnapshotComplete { string cursor = 1 ; }
94+ message InitialSnapshotComplete {
95+ string cursor = 1 ;
96+ }
10397
10498message InitialSnapshotData {
10599 string module_name = 1 ;
@@ -116,9 +110,9 @@ message MapModuleOutput {
116110}
117111
118112// StoreModuleOutput are produced for store modules in development mode.
119- // It is not possible to retrieve store models in production, with
120- // parallelization enabled. If you need the deltas directly, write a pass
121- // through mapper module that will get them down to you.
113+ // It is not possible to retrieve store models in production, with parallelization
114+ // enabled. If you need the deltas directly, write a pass through mapper module
115+ // that will get them down to you.
122116message StoreModuleOutput {
123117 string name = 1 ;
124118 repeated StoreDelta debug_store_deltas = 2 ;
@@ -127,18 +121,16 @@ message StoreModuleOutput {
127121
128122message OutputDebugInfo {
129123 repeated string logs = 1 ;
130- // LogsTruncated is a flag that tells you if you received all the logs or if
131- // they were truncated because you logged too much (fixed limit currently is
132- // set to 128 KiB).
124+ // LogsTruncated is a flag that tells you if you received all the logs or if they
125+ // were truncated because you logged too much (fixed limit currently is set to 128 KiB).
133126 bool logs_truncated = 2 ;
134127 bool cached = 3 ;
135128}
136129
137130// ModulesProgress is a message that is sent every 500ms
138131message ModulesProgress {
139132 // previously: repeated ModuleProgress modules = 1;
140- // these previous `modules` messages were sent in bursts and are not sent
141- // anymore.
133+ // these previous `modules` messages were sent in bursts and are not sent anymore.
142134 reserved 1 ;
143135 // List of jobs running on tier2 servers
144136 repeated Job running_jobs = 2 ;
@@ -155,82 +147,73 @@ message ProcessedBytes {
155147 uint64 total_bytes_written = 2 ;
156148}
157149
150+
158151message Error {
159152 string module = 1 ;
160153 string reason = 2 ;
161154 repeated string logs = 3 ;
162- // FailureLogsTruncated is a flag that tells you if you received all the logs
163- // or if they were truncated because you logged too much (fixed limit
164- // currently is set to 128 KiB).
155+ // FailureLogsTruncated is a flag that tells you if you received all the logs or if they
156+ // were truncated because you logged too much (fixed limit currently is set to 128 KiB).
165157 bool logs_truncated = 4 ;
166158}
167159
160+
168161message Job {
169- uint32 stage = 1 ;
170- uint64 start_block = 2 ;
171- uint64 stop_block = 3 ;
172- uint64 processed_blocks = 4 ;
173- uint64 duration_ms = 5 ;
162+ uint32 stage = 1 ;
163+ uint64 start_block = 2 ;
164+ uint64 stop_block = 3 ;
165+ uint64 processed_blocks = 4 ;
166+ uint64 duration_ms = 5 ;
174167}
175168
176169message Stage {
177- repeated string modules = 1 ;
178- repeated BlockRange completed_ranges = 2 ;
170+ repeated string modules = 1 ;
171+ repeated BlockRange completed_ranges = 2 ;
179172}
180173
181- // ModuleStats gathers metrics and statistics from each module, running on tier1
182- // or tier2 All the 'count' and 'time_ms' values may include duplicate for each
183- // stage going over that module
174+ // ModuleStats gathers metrics and statistics from each module, running on tier1 or tier2
175+ // All the 'count' and 'time_ms' values may include duplicate for each stage going over that module
184176message ModuleStats {
185- // name of the module
186- string name = 1 ;
177+ // name of the module
178+ string name = 1 ;
187179
188- // total_processed_blocks is the sum of blocks sent to that module code
189- uint64 total_processed_block_count = 2 ;
190- // total_processing_time_ms is the sum of all time spent running that module
191- // code
192- uint64 total_processing_time_ms = 3 ;
180+ // total_processed_blocks is the sum of blocks sent to that module code
181+ uint64 total_processed_block_count = 2 ;
182+ // total_processing_time_ms is the sum of all time spent running that module code
183+ uint64 total_processing_time_ms = 3 ;
193184
194- //// external_calls are chain-specific intrinsics, like "Ethereum RPC calls".
195- repeated ExternalCallMetric external_call_metrics = 4 ;
185+ //// external_calls are chain-specific intrinsics, like "Ethereum RPC calls".
186+ repeated ExternalCallMetric external_call_metrics = 4 ;
196187
197- // total_store_operation_time_ms is the sum of all time spent running that
198- // module code waiting for a store operation (ex: read, write, delete...)
199- uint64 total_store_operation_time_ms = 5 ;
200- // total_store_read_count is the sum of all the store Read operations called
201- // from that module code
202- uint64 total_store_read_count = 6 ;
188+ // total_store_operation_time_ms is the sum of all time spent running that module code waiting for a store operation (ex: read, write, delete...)
189+ uint64 total_store_operation_time_ms = 5 ;
190+ // total_store_read_count is the sum of all the store Read operations called from that module code
191+ uint64 total_store_read_count = 6 ;
203192
204- // total_store_write_count is the sum of all store Write operations called
205- // from that module code (store-only)
206- uint64 total_store_write_count = 10 ;
193+ // total_store_write_count is the sum of all store Write operations called from that module code (store-only)
194+ uint64 total_store_write_count = 10 ;
207195
208- // total_store_deleteprefix_count is the sum of all store DeletePrefix
209- // operations called from that module code (store-only) note that DeletePrefix
210- // can be a costly operation on large stores
211- uint64 total_store_deleteprefix_count = 11 ;
196+ // total_store_deleteprefix_count is the sum of all store DeletePrefix operations called from that module code (store-only)
197+ // note that DeletePrefix can be a costly operation on large stores
198+ uint64 total_store_deleteprefix_count = 11 ;
212199
213- // store_size_bytes is the uncompressed size of the full KV store for that
214- // module, from the last 'merge' operation (store-only)
215- uint64 store_size_bytes = 12 ;
200+ // store_size_bytes is the uncompressed size of the full KV store for that module, from the last 'merge' operation (store-only)
201+ uint64 store_size_bytes = 12 ;
216202
217- // total_store_merging_time_ms is the time spent merging partial stores into a
218- // full KV store for that module (store-only)
219- uint64 total_store_merging_time_ms = 13 ;
203+ // total_store_merging_time_ms is the time spent merging partial stores into a full KV store for that module (store-only)
204+ uint64 total_store_merging_time_ms = 13 ;
220205
221- // store_currently_merging is true if there is a merging operation (partial
222- // store to full KV store) on the way.
223- bool store_currently_merging = 14 ;
206+ // store_currently_merging is true if there is a merging operation (partial store to full KV store) on the way.
207+ bool store_currently_merging = 14 ;
224208
225- // highest_contiguous_block is the highest block in the highest merged full KV
226- // store of that module (store-only)
227- uint64 highest_contiguous_block = 15 ;
209+ // highest_contiguous_block is the highest block in the highest merged full KV store of that module (store-only)
210+ uint64 highest_contiguous_block = 15 ;
228211}
229212
230213message ExternalCallMetric {
231- string name = 1 ;
232- uint64 count = 2 ;
233- uint64 time_ms = 3 ;
214+ string name = 1 ;
215+ uint64 count = 2 ;
216+ uint64 time_ms = 3 ;
234217}
235218
236219message StoreDelta {
0 commit comments