syntax = "proto3";

package sf.firehose.v1;

import "google/protobuf/any.proto";

option go_package = "github.com/streamingfast/pbgo/sf/firehose/v1;pbfirehose";

service Stream {
  rpc Blocks(Request) returns (stream Response);
}

// For historical segments, forks are not passed
message Request {
  // Controls where the stream of blocks will start.
  //
  // The stream will start **inclusively** at the requested block num.
  //
  // When not provided, starts at first streamable block of the chain. Not all
  // chain starts at the same block number, so you might get an higher block than
  // requested when using default value of 0.
  //
  // Can be negative, will be resolved relative to the chain head block, assuming
  // a chain at head block #100, then using `-50` as the value will start at block
  // #50. If it resolves before first streamable block of chain, we assume start
  // of chain.
  //
  // If `start_cursor` is passed, this value is ignored and the stream instead starts
  // immediately after the Block pointed by the opaque `start_cursor` value.
  int64 start_block_num = 1;

  // Controls where the stream of blocks will start which will be immediately after
  // the Block pointed by this opaque cursor.
  //
  // Obtain this value from a previously received `Response.cursor`.
  //
  // This value takes precedence over `start_block_num`.
  string start_cursor = 13;

  // When non-zero, controls where the stream of blocks will stop.
  //
  // The stream will close **after** that block has passed so the boundary is
  // **inclusive**.
  uint64 stop_block_num = 5;

  // Filter the steps you want to see. If not specified, defaults to all steps.
  //
  // Most common steps will be [STEP_IRREVERSIBLE], or [STEP_NEW, STEP_UNDO, STEP_IRREVERSIBLE].
  repeated ForkStep fork_steps = 8;

  // feature moved to transforms
  string include_filter_expr = 10 [deprecated=true];
  string exclude_filter_expr = 11 [deprecated=true];
  reserved 15; // removed: details
  reserved 16; // removed: confirmations


  //- EOS "handoffs:3"
  //- EOS "lib"
  //- EOS "confirms:3"
  //- ETH "confirms:200"
  //- ETH "confirms:7"
  //- SOL "commmitement:finalized"
  //- SOL "confirms:200"
  string irreversibility_condition = 17;

  repeated google.protobuf.Any transforms = 18;
}

message Response {
  // Chain specific block payload, one of:
  // - sf.eosio.codec.v1.Block
  // - sf.ethereum.codec.v1.Block
  // - sf.near.codec.v1.Block
  // - sf.solana.codec.v1.Block
  google.protobuf.Any block = 1;
  ForkStep step = 6;
  string cursor = 10;
}

enum ForkStep {
  STEP_UNKNOWN = 0;
  // Block is new head block of the chain, that is linear with the previous block
  STEP_NEW = 1;
  // Block is now forked and should be undone, it's not the head block of the chain anymore
  STEP_UNDO = 2;
  // Removed, was STEP_REDO
  reserved 3;
  // Block is now irreversible and can be committed to (finality is chain specific, see chain documentation for more details)
  STEP_IRREVERSIBLE = 4;
  // Removed, was STEP_STALLED
  reserved 5 ;
}
