syntax = "proto3";
package scanner;

// Empty is for gRPCs that take no arguments, currently only GetInfo.
message Empty {}

service Scanner {
    // Get information about the scanner service.
    rpc GetInfo (Empty) returns (InfoReply);

    // Clear results for a set of keys without removing the keys from the scanner.
    // This request does not stop the scanner from scanning blocks for these keys, it
    // only clears past results.
    rpc ClearResults(ClearResultsRequest) returns (Empty);

    // Deletes a set of keys and their results from the scanner.
    // This request stop the scanner from scanning blocks for the these keys.
    rpc DeleteKeys(DeleteKeysRequest) returns (Empty);

    // Get all data we have stored for the given keys.
    rpc GetResults(GetResultsRequest) returns (GetResultsResponse);

    // Submits scanning keys to the scanner.
    rpc RegisterKeys(RegisterKeysRequest) returns (RegisterKeysResponse);

    // Register keys and listen to the results
    rpc Scan (ScanRequest) returns (stream ScanResponse);
}

// A response to a GetInfo call.
message InfoReply {
    // The minimum sapling height allowed.
    uint32 min_sapling_birthday_height = 1;
}

// A request for clearing past results from the scanner cache.
message ClearResultsRequest {
    // Keys for which to clear results.
    repeated string keys = 1;
}

// A request to delete keys, delete their results, and stop scanning for their results.
message DeleteKeysRequest {
    // Keys to delete from scanner.
    repeated string keys = 1;
}

// A request for getting results for a set of keys.
message GetResultsRequest {
    // Keys for which to get results.
    repeated string keys = 1;
}

// A request to register scanning keys
message RegisterKeysRequest {
    // Keys to register
    repeated KeyWithHeight keys = 1;
}

// A set of responses for each provided key of a GetResults call.
message GetResultsResponse {
    // Results for each key.
    map<string, Results> results = 1;
}

// A response to `RegisterKeysRequest` containing registered keys
message RegisterKeysResponse {
    // Keys that were registered
    repeated string keys = 1;
}

// A result for a single key.
message Results {
    // A height, transaction id map
    map<uint32, Transactions> by_height = 1;
}

// A vector of transaction hashes
message Transactions {
    // Transactions
    repeated Transaction transactions = 1;
}

// Transaction data
message Transaction {
    // The transaction hash/id
    string hash = 1;
}

// A scanning key with an optional birth height
message KeyWithHeight {
    // Scanning key
    string key = 1;
    // Birth height of the key
    optional uint32 height = 2;
}

// A request for registering keys and getting their transactions
message ScanRequest {
    // A set of viewing keys
    repeated KeyWithHeight keys = 2;
}

// Response to Scan calls
message ScanResponse {
    // Results for each key.
    map<string, Results> results = 1;
}