rpcevents.proto

syntax = 'proto3';

option go_package = "github.com/hyperledger/burrow/rpc/rpcevents";

import "gogoproto/gogo.proto";
import "exec.proto";

package rpcevents;

option (gogoproto.marshaler_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (gogoproto.stable_marshaler_all) = true;
option (gogoproto.sizer_all) = true;
// Enable registration with golang/protobuf for the grpc-gateway.
option (gogoproto.goproto_registration) = true;
// Enable generation of XXX_MessageName methods for grpc-go/status.
option (gogoproto.messagename_all) = true;

//--------------------------------------------------
// Execution events
service ExecutionEvents {
    // Get StreamEvents (including transactions) for a range of block heights
    rpc Stream (BlocksRequest) returns (stream exec.StreamEvent);
    // Get a particular TxExecution by hash
    rpc Tx (TxRequest) returns (exec.TxExecution);
    // GetEvents provides events streaming one block at a time - that is all events emitted in a particular block
    // are guaranteed to be delivered in each GetEventsResponse
    rpc Events (BlocksRequest) returns (stream EventsResponse);
}

message GetBlockRequest {
    // Height of block required
    uint64 Height = 1;
    // Whether to wait for the block to become available
    bool Wait = 2;
}

message TxRequest {
    // Height of block required
    bytes TxHash = 1 [(gogoproto.customtype) = "github.com/hyperledger/burrow/binary.HexBytes", (gogoproto.nullable) = false];
    // Whether to wait for the block to become available
    bool Wait = 2;
}

message BlocksRequest {
    BlockRange BlockRange = 1;
    // Specify a query on which to match the tags of events.
    // Tag        | Match type | Values
    // -----------------------------------------
    //   All events
    // -----------------------------------------
    // TxType       | String     | "UnknownTx", "SendTx", "CallTx", "NameTx", "BondTx", "UnbondTx", "PermissionsTx", "GovernanceTx"
    // TxHash       | String     | bytes
    // EventType    | String     | "CallEvent", "LogEvent", "AccountInputEvent", "AccountOutputEvent"
    // EventID      | String     | string
    // Height       | Integer    | uint64
    // Index        | Integer    | uint64
    // MessageType  | String     | Go type name
    // -----------------------------------------
    //   Log event
    // -----------------------------------------
    // Address      | String     | Address (hex)
    // Log<0-4>     | String     | Word256 (hex)
    // Log<0-4>Text | String     | string (trimmed)
    // -----------------------------------------
    //   Call event
    // -----------------------------------------
    // Origin       | String     | Address (hex)
    // Callee       | String     | Address (hex)
    // Caller       | String     | Address (hex)
    // Value        | Integer    | uint64
    // Gas          | Integer    | uint64
    // StackDepth   | Integer    | uint64
    // Exception    | String     | string
    // -----------------------------------------
    //   Tx event (input/output)
    // -----------------------------------------
    // Exception  | String     | string
    //
    // For example:
    // EventType = 'LogEvent' AND EventID CONTAINS 'bar' AND TxHash = '020304' AND Height >= 34 AND Index < 3 AND Address = 'DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF'
    string Query = 2;
}

message EventsResponse {
    uint64 Height = 1;
    repeated exec.Event Events = 2;
}

message GetTxsRequest {
    uint64 StartHeight = 1;
    uint64 EndHeight = 2;
    string Query = 3;
}

message GetTxsResponse {
    uint64 Height = 1;
    repeated exec.TxExecution TxExecutions = 2;
}

message Bound {
    BoundType Type = 1;
    uint64 Index = 2;
    enum BoundType {
        // Index is absolute index of an item
        ABSOLUTE = 0;
        // Index is an offset relative to last item
        RELATIVE = 1;
        // The first block
        FIRST = 2;
        // Ignore provided index and evaluate to latest index
        LATEST = 3;
        // Ignore provided index and stream new objects as they are generated
        STREAM = 4;
    }
}

// An inclusive range of blocks to include in output
message BlockRange {
    // Bounds can be set to:
    // absolute: block height
    // relative: block height counting back from latest
    // latest: latest block when call is processed
    // stream: for End keep sending new blocks, for start same as latest
    Bound Start = 1;
    Bound End = 2;
}