diff --git a/README.md b/README.md index 1b2490164..f1f0a2199 100644 --- a/README.md +++ b/README.md @@ -141,6 +141,7 @@ You can also build Zebra with additional [Cargo features](https://doc.rust-lang. - `prometheus` for [Prometheus metrics](https://zebra.zfnd.org/user/metrics.html) - `sentry` for [Sentry monitoring](https://zebra.zfnd.org/user/tracing.html#sentry-production-monitoring) - `elasticsearch` for [experimental Elasticsearch support](https://zebra.zfnd.org/user/elasticsearch.html) +- `shielded-scan` for [experimental shielded scan support](https://zebra.zfnd.org/user/shielded-scan.html) You can combine multiple features by listing them as parameters of the `--features` flag: diff --git a/book/src/user/shielded-scan.md b/book/src/user/shielded-scan.md index df72b0aa7..02bca1e91 100644 --- a/book/src/user/shielded-scan.md +++ b/book/src/user/shielded-scan.md @@ -9,12 +9,22 @@ Ongoing development is tracked in issue [#7728](https://github.com/ZcashFoundati 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. +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. ## Build & Install -Using the `shielded-scan` feature. TODO: add examples, document the feature in zebrad/src/lib.rs. +- Clone a Zebra version greater than or equal to [1.5.0](https://github.com/ZcashFoundation/zebra/releases/tag/v1.5.0) or use the `main` branch to get the latest features. + +```bash +cargo install --features shielded-scan --locked --git https://github.com/ZcashFoundation/zebra zebrad +``` +Zebra binary will be at `~/.cargo/bin/zebrad`. + +- Generate a configuration file with the default settings: + +```bash +zebrad generate -o ~/.config/zebrad.toml +``` ## Configuration @@ -22,15 +32,63 @@ In `zebrad.toml`, use: - the `[shielded_scan]` table for database settings, and - the `[shielded_scan.sapling_keys_to_scan]` table for diversifiable full viewing keys. -TODO: add a definition for DFVK, link to its format, and add examples and links to keys and database settings. +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 for transactions with the [public ZECpages viewing key](https://zecpages.com/boardinfo) use: + +```toml +[shielded_scan.sapling_keys_to_scan] +"zxviews1q0duytgcqqqqpqre26wkl45gvwwwd706xw608hucmvfalr759ejwf7qshjf5r9aa7323zulvz6plhttp5mltqcgs9t039cx2d09mgq05ts63n8u35hyv6h9nc9ctqqtue2u7cer2mqegunuulq2luhq3ywjcz35yyljewa4mgkgjzyfwh6fr6jd0dzd44ghk0nxdv2hnv4j5nxfwv24rwdmgllhe0p8568sgqt9ckt02v2kxf5ahtql6s0ltjpkckw8gtymxtxuu9gcr0swvz" = 419200 +``` + +Where the number `1` above is the birthday of the corresponding 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. ## Running Sapling Scanning -Launch Zebra and wait for 12-24 hours. +For full scanning results. launch Zebra and wait for 12-24 hours. Zebra needs to be synced up to at least the Sapling activation height to start scanning. If you have an already synced-up chain, the scanner will start looking for transactions for the provided keys from the start. -## Expert: Querying Raw Sapling Scanning Results +```bash +zebrad +``` -TODO: Copy these instructions and examples here: -- https://github.com/ZcashFoundation/zebra/issues/8046#issuecomment-1844772654 +You should see log messages in the output every 10000 blocks scanned, similar to: -Database paths are different on Linux, macOS, and Windows. +``` +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 +... +``` + +The Zebra scanner will resume the task if your Zebra instance went down for any reason. In a new start, Zebra will display: + +``` +Last scanned height for key number 0 is 1798000, resuming at 1798001 +``` + +## Querying results with the `scanning-results-reader` utility. + +The easier way to read the results of found transactions and more is to use the utility tool named `scanning-results-reader`. Please read the [tool description](https://github.com/ZcashFoundation/zebra/tree/main/zebra-utils#scanning-results-reader) to learn how to use it. Instructions are straightforward. + +## Querying Raw Sapling Scanning Results + +A more advanced way to query results is to use `ldb` tool, requires a certain level of expertise. + +Install `ldb`: + +```bash +sudo apt install rocksdb-tools +``` + +Run `ldb` with the scanner database: + +```bash +ldb --db="$HOME/.cache/zebra/private-scan/v1/mainnet" --secondary_path= --column_family=sapling_tx_ids --hex scan +``` + +Some of the output will be markers the scanner uses to keep track of progress, however, some of them will be transactions found. + +To lean more about how to filter the database please refer to [RocksDB Administration and Data Access Tool](https://github.com/facebook/rocksdb/wiki/Administration-and-Data-Access-Tool) diff --git a/zebrad/src/lib.rs b/zebrad/src/lib.rs index 04aeb9f27..11559b947 100644 --- a/zebrad/src/lib.rs +++ b/zebrad/src/lib.rs @@ -102,6 +102,8 @@ //! //! * `elasticsearch`: save block data into elasticsearch database. Read the [elasticsearch](https://zebra.zfnd.org/user/elasticsearch.html) //! section of the book for more details. +//! * `shielded-scan`: enable experimental support for scanning shielded transactions. Read the [shielded-scan](https://zebra.zfnd.org/user/shielded-scan.html) +//! section of the book for more details. #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")]