Skip to content

Commit

Permalink
update scanner documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@oxarbitrage
oxarbitrage committed Jul 13, 2024
1 parent 255a483 commit 1fdeb3f
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 53 deletions.
10 changes: 4 additions & 6 deletions book/src/user/shielded-scan-grpc-server.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@

### 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:
After setting up [Zebra Shielded Scanning](https://zebra.zfnd.org/user/shielded-scan.html), adyou can add a `listen-addr` argument to the scanner binary:

```toml
[shielded_scan]
listen_addr = "127.0.0.1:8231"
```

Then, run `zebrad` to start the scan gRPC server.
```bash
RUST_LOG=info zebra-scanner --sapling-keys-to-scan '{"key":"zxviews1q0duytgcqqqqpqre26wkl45gvwwwd706xw608hucmvfalr759ejwf7qshjf5r9aa7323zulvz6plhttp5mltqcgs9t039cx2d09mgq05ts63n8u35hyv6h9nc9ctqqtue2u7cer2mqegunuulq2luhq3ywjcz35yyljewa4mgkgjzyfwh6fr6jd0dzd44ghk0nxdv2hnv4j5nxfwv24rwdmgllhe0p8568sgqt9ckt02v2kxf5ahtql6s0ltjpkckw8gtymxtxuu9gcr0swvz", "birthday_height": 419200}' --zebrad-cache-dir /media/alfredo/stuff/chain/zebra --zebra-rpc-listen-addr '127.0.0.1:8232' --listen-addr '127.0.0.1:8231'
```

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

Expand Down
79 changes: 32 additions & 47 deletions book/src/user/shielded-scan.md
View file
Original file line number Diff line number Diff line change
@@ -1,90 +1,75 @@
# Zebra Shielded Scanning

This document describes Zebra's shielded scanning from users' perspective.
The `zebra-scanner` binary is a standalone application that utilizes Zebra libraries to scan for transactions associated with specific Sapling viewing keys. It stores the discovered transactions and scanning progress data in a RocksDB database.

For this application to function, it requires a `zebrad` node to be running concurrently with the scanner application.

For now, we only support Sapling, and only store transaction IDs in the scanner results database.
Ongoing development is tracked in issue [#7728](https://github.com/ZcashFoundation/zebra/issues/7728).

Ongoing development is tracked in issue [#7728](https://github.com/ZcashFoundation/zebra/issues/7728) and [#8573](https://github.com/ZcashFoundation/zebra/issues/8573).

## Important Security Warning

Zebra's shielded scanning feature has known security issues. It is for experimental use only.

Do not use regular or sensitive viewing keys with Zebra's experimental scanning
feature. Do not use this feature on a shared machine. We suggest generating new
keys for experimental use or publicly known keys.
Do not use regular or sensitive viewing keys with Zebra's experimental scanning feature. Do not use this feature on a shared machine. We suggest generating new keys for experimental use or publicly known keys.

## Build & Install

Use [Zebra 1.6.0](https://github.com/ZcashFoundation/zebra/releases/tag/v1.6.0)
or greater, or the `main` branch to get the latest features, and enable the
`shielded-scan` feature during the build. You can also use Rust's `cargo` to
install the latest release:
Use [Zebra 1.9.0](https://github.com/ZcashFoundation/zebra/releases/tag/v1.9.0) or greater, or the `main` branch to get the latest features.

You can also use Rust's `cargo` to install `zebra-scanner` from the latest release Zebra repository:

```bash
cargo install --features shielded-scan --locked --git https://github.com/ZcashFoundation/zebra zebrad
cargo install --locked --git https://github.com/ZcashFoundation/zebra zebra-scan
```

Zebra binary will be at `~/.cargo/bin/zebrad`, which should be in your `PATH`.
The scanner binary will be at `~/.cargo/bin/zebra-scanner`, which should be in your `PATH`.

## Configuration
## Arguments

Generate a configuration file with the default settings:
Retrieve the binary arguments with:

```bash
zebrad generate -o ~/.config/zebrad.toml
zebra-scanner --help
```

## Scanning the Block Chain

In the generated `zebrad.toml` file, use:

- the `[shielded_scan]` table for database settings, and
- the `[shielded_scan.sapling_keys_to_scan]` table for diversifiable full viewing keys.

Sapling diversifiable/extended full viewing keys strings start with `zxviews` as
described in
[ZIP-32](https://zips.z.cash/zip-0032#sapling-extended-full-viewing-keys).

For example, to scan the block chain with the [public ZECpages viewing
key](https://zecpages.com/boardinfo), use:
Before starting, ensure a `zebrad` node is running locally with the RPC endpoint open. Refer to the [lightwalletd zebrad setup](https://zebra.zfnd.org/user/lightwalletd.html#configure-zebra-for-lightwalletd) or [zebrad mining setup](https://zebra.zfnd.org/user/mining.html#configure-zebra-for-mining) for instructions.

```toml
[shielded_scan.sapling_keys_to_scan]
"zxviews1q0duytgcqqqqpqre26wkl45gvwwwd706xw608hucmvfalr759ejwf7qshjf5r9aa7323zulvz6plhttp5mltqcgs9t039cx2d09mgq05ts63n8u35hyv6h9nc9ctqqtue2u7cer2mqegunuulq2luhq3ywjcz35yyljewa4mgkgjzyfwh6fr6jd0dzd44ghk0nxdv2hnv4j5nxfwv24rwdmgllhe0p8568sgqt9ckt02v2kxf5ahtql6s0ltjpkckw8gtymxtxuu9gcr0swvz" = 419200
```
To initiate the scanning process, you need the following:

Where the number 419200 is the birthday of the key:
- birthday lower than the Sapling activation height defaults to Sapling activation height.
- birthday greater or equal than Sapling activation height will start scanning at provided height, improving scanner speed.
- A zebrad cache state directory. This can be obtained from the running zebrad configuration file, under the `state` section in the `cache_dir` field.
- A key to scan with, optionally including a birthday height, which specifies the starting height for the scanning process for that key.
- A zebrad RPC endpoint address. This can be found in the running zebrad configuration file, under the `rpc` section in the `listen_addr` field.

## Scanning the Block Chain

Simply run
Pass the data as arguments, for example:

```bash
zebrad
RUST_LOG=info zebra-scanner --sapling-keys-to-scan '{"key":"zxviews1q0duytgcqqqqpqre26wkl45gvwwwd706xw608hucmvfalr759ejwf7qshjf5r9aa7323zulvz6plhttp5mltqcgs9t039cx2d09mgq05ts63n8u35hyv6h9nc9ctqqtue2u7cer2mqegunuulq2luhq3ywjcz35yyljewa4mgkgjzyfwh6fr6jd0dzd44ghk0nxdv2hnv4j5nxfwv24rwdmgllhe0p8568sgqt9ckt02v2kxf5ahtql6s0ltjpkckw8gtymxtxuu9gcr0swvz", "birthday_height": 419200}' --zebrad-cache-dir /media/alfredo/stuff/chain/zebra --zebra-rpc-listen-addr '127.0.0.1:8232'
```

The scanning will start once Zebra syncs its state past the Sapling activation
height. Scanning a synced state takes between 12 and 24 hours. The scanner looks
for transactions containing Sapling notes with outputs decryptable by the
provided viewing keys.
- A birthday lower than the Sapling activation height defaults to Sapling activation height.
- A birthday greater or equal than Sapling activation height will start scanning at provided height, improving scanner speed.

The scanning process begins once Zebra syncs its state past the Sapling activation height. Scanning a synced state takes between 12 and 24 hours. The scanner searches for transactions containing Sapling notes with outputs decryptable by the provided viewing keys.

You should see log messages in the output every 10 000 blocks scanned, similar
to:
You will see log messages in the output every 10,000 blocks scanned, similar to:

```
2023-12-16T12:14:41.526740Z INFO zebra_scan::storage::db: Last scanned height for key number 0 is 435000, resuming at 435001
2023-12-16T12:14:41.526745Z INFO zebra_scan::storage::db: loaded Zebra scanner cache
...
2023-12-16T12:15:19.063796Z INFO {zebrad="39830b0" net="Main"}: zebra_scan::scan: Scanning the blockchain for key 0, started at block 435001, now at block 440000, current tip 2330550
2024-07-13T16:07:47.944309Z INFO zebra_scan::service::scan_task::scan: Scanning the blockchain for key 0, started at block 571001, now at block 580000, current tip 2556979
2024-07-13T16:08:07.811013Z INFO zebra_scan::service::scan_task::scan: Scanning the blockchain for key 0, started at block 571001, now at block 590000, current tip 2556979
...
```

The Zebra scanner will resume the task if your Zebra instance went down for any
reason. In a new start, Zebra will display:
If your Zebra instance goes down for any reason, the Zebra scanner will resume the task. Upon a new start, Zebra will display:

```
Last scanned height for key number 0 is 1798000, resuming at 1798001
2024-07-13T16:07:17.700073Z INFO zebra_scan::storage::db: Last scanned height for key number 0 is 590000, resuming at 590001
2024-07-13T16:07:17.706727Z INFO zebra_scan::service::scan_task::scan: got min scan height start_height=Height(590000)
```

## Displaying Scanning Results
Expand Down

0 comments on commit 1fdeb3f

Please sign in to comment.