Zebra Shielded Scanning gRPC Server

Get Started

Setup

After setting up Zebra Shielded Scanning, add a listen_addr field to the shielded-scan configuration:

[shielded_scan]
listen_addr = "127.0.0.1:8231"

Then, run zebrad to start the scan gRPC server.

Making requests to the server will also require a gRPC client, the examples here use grpcurl, though any gRPC client should work.

See installation instructions for grpcurl here.

The types can be accessed through the zebra-grpc crate's root scanner module for clients in a Rust environment, and the scanner.proto file here can be used to build types in other environments.

Usage

To check that the gRPC server is running, try calling scanner.Scanner/GetInfo, for example with grpcurl:

grpcurl -plaintext '127.0.0.1:8231' scanner.Scanner/GetInfo

The response should look like:

{
  "minSaplingBirthdayHeight": 419200
}

An example request to the Scan method with grpcurl would look like:

grpcurl -plaintext -d '{ "keys": { "key": ["sapling_extended_full_viewing_key"] } }' '127.0.0.1:8231' scanner.Scanner/Scan

This will start scanning for transactions in Zebra's state and in new blocks as they're validated.

Or, to use the scanner gRPC server without streaming, try calling RegisterKeys with your Sapling extended full viewing key, waiting for the scanner to cache some results, then calling GetResults:

grpcurl -plaintext -d '{ "keys": { "key": ["sapling_extended_full_viewing_key"] } }' '127.0.0.1:8231' scanner.Scanner/RegisterKeys
grpcurl -plaintext -d '{ "keys": ["sapling_extended_full_viewing_key"] }' '127.0.0.1:8231' scanner.Scanner/GetResults

gRPC Reflection

To see all of the provided methods with grpcurl, try:

grpcurl -plaintext '127.0.0.1:8231' list scanner.Scanner

This will list the paths to each method in the Scanner service:

scanner.Scanner.ClearResults
scanner.Scanner.DeleteKeys
scanner.Scanner.GetInfo
scanner.Scanner.GetResults
scanner.Scanner.RegisterKeys

To see the the request and response types for a method, for example the GetResults method, try:

grpcurl -plaintext '127.0.0.1:8231' describe scanner.Scanner.GetResults \
&& grpcurl -plaintext '127.0.0.1:8231' describe scanner.GetResultsRequest \
&& grpcurl -plaintext '127.0.0.1:8231' describe scanner.GetResultsResponse \
&& grpcurl -plaintext '127.0.0.1:8231' describe scanner.Results \
&& grpcurl -plaintext '127.0.0.1:8231' describe scanner.Transactions \
&& grpcurl -plaintext '127.0.0.1:8231' describe scanner.Transaction

The response should be the request and response types for the GetResults method:

scanner.Scanner.GetResults is a method:
// Get all data we have stored for the given keys.
rpc GetResults ( .scanner.GetResultsRequest ) returns ( .scanner.GetResultsResponse );
scanner.GetResultsRequest is a message:
// A request for getting results for a set of keys.
message GetResultsRequest {
  // Keys for which to get results.
  repeated string keys = 1;
}
scanner.GetResultsResponse is a message:
// A set of responses for each provided key of a GetResults call.
message GetResultsResponse {
  // Results for each key.
  map<string, .scanner.Results> results = 1;
}
scanner.Results is a message:
// A result for a single key.
message Results {
  // A height, transaction id map
  map<uint32, .scanner.Transactions> by_height = 1;
}
scanner.Transactions is a message:
// A vector of transaction hashes
message Transactions {
  // Transactions
  repeated Transaction transactions = 1;
}
scanner.Transaction is a message:
// Transaction data
message Transaction {
  // The transaction hash/id
  string hash = 1;
}

Methods

GetInfo

Returns basic information about the zebra-scan instance.

RegisterKeys

Starts scanning for a set of keys, with optional start heights, and caching the results. Cached results can later be retrieved by calling the GetResults or Scan methods.

DeleteKeys

Stops scanning transactions for a set of keys. Deletes the keys and their cached results for the keys from zebra-scan.

GetResults

Returns cached results for a set of keys.

ClearResults

Deletes any cached results for a set of keys.

Scan

Starts scanning for a set of keys and returns a stream of results.