149 lines
4.5 KiB
Markdown
149 lines
4.5 KiB
Markdown
# Zebra Shielded Scanning gRPC Server
|
|
|
|
## Get Started
|
|
|
|
### Setup
|
|
|
|
After setting up [Zebra Shielded Scanning](https://zebra.zfnd.org/user/shielded-scan.html), add a `listen_addr` field to the shielded-scan configuration:
|
|
|
|
```toml
|
|
[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](https://github.com/fullstorydev/grpcurl?tab=readme-ov-file#installation).
|
|
|
|
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](https://github.com/ZcashFoundation/zebra/blob/main/zebra-grpc/proto/scanner.proto) 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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
|
|
```bash
|
|
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
|
|
|
|
<!-- TODO: Add a reference to zebra-grpc method docs -->
|
|
|
|
---
|
|
#### 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.
|