From 1fdeb3fa4cabf2fbb608a4a44c7eaae6e1ba1337 Mon Sep 17 00:00:00 2001 From: Alfredo Garcia Date: Sat, 13 Jul 2024 14:06:10 -0300 Subject: [PATCH] update scanner documentation --- book/src/user/shielded-scan-grpc-server.md | 10 ++- book/src/user/shielded-scan.md | 79 +++++++++------------- 2 files changed, 36 insertions(+), 53 deletions(-) diff --git a/book/src/user/shielded-scan-grpc-server.md b/book/src/user/shielded-scan-grpc-server.md index 2b3fca56b3f..4614ee01a5b 100644 --- a/book/src/user/shielded-scan-grpc-server.md +++ b/book/src/user/shielded-scan-grpc-server.md @@ -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. diff --git a/book/src/user/shielded-scan.md b/book/src/user/shielded-scan.md index 5d926be1e75..e388db99d32 100644 --- a/book/src/user/shielded-scan.md +++ b/book/src/user/shielded-scan.md @@ -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