Zebra 工具库

用于维护和测试 Zebra 的工具

• zebra-checkpoints
• zebrad-hash-lookup
• zebrad-log-filter
• zcash-rpc-diff
• scanning-results-reader
• openapi-generator

如果可执行文件位于您的系统执行路径中，则更容易使用。

zebra-checkpoints

此命令生成 zebra 检查点的列表，并将它们写入标准输出。每个检查点由区块高度和哈希组成。

CI 中自动生成检查点

Zebra 的 GitHub 工作流程会在每次 main 分支更新后自动生成检查点。这些检查点可以复制到 main-checkpoints.txt 和 test-checkpoints.txt 文件中。

查找 main 分支上的最新检查点

1. 找到 在 main 上完成的最新 CI Docker 工作流程运行。由于 GitHub UI 问题，一些运行将显示为等待、已取消或失败，但检查点已生成。
2. 转到 Generate checkpoints mainnet 作业中的 Result of checkpoints-mainnet 步骤，在 Generate checkpoints mainnet 作业中
3. 向下滚动，直到您看到检查点列表，它应该在大约第 200 行开始
4. 将这些检查点添加到zebra-consensus/src/checkpoint/main-checkpoints.txt的末尾
5. 为Generate checkpoints testnet重复步骤 2 到 4
6. 在https://github.com/ZcashFoundation/zebra/pulls打开一个pull请求

手动检查点生成

要创建检查点，您需要一个与网络顶端同步的zebrad或zcashd实例。可以直接查询zebrad或通过已安装的zcash-cli RPC客户端进行查询。zcashd必须通过zcash-cli进行查询，它执行正确的RPC身份验证。

检查点生成设置

确保您的zebrad或zcashd正在监听RPC请求，并且已同步到网络顶端。

如果您使用的是Debian系统，zcash-cli可以作为软件包安装。

zebra-checkpoints是一个独立的Rust二进制文件，您可以使用以下命令进行编译：

cargo install --locked --features zebra-checkpoints --git https://github.com/ZcashFoundation/zebra zebra-utils

检查点生成命令

您可以使用以下命令更新检查点

zebra-checkpoints --last-checkpoint $(tail -1 zebra-consensus/src/checkpoint/main-checkpoints.txt | cut -d" " -f1) | tee --append zebra-consensus/src/checkpoint/main-checkpoints.txt &
zebra-checkpoints --last-checkpoint $(tail -1 zebra-consensus/src/checkpoint/test-checkpoints.txt | cut -d" " -f1) -- -testnet | tee --append zebra-consensus/src/checkpoint/test-checkpoints.txt &
wait

在更新列表时，无需从创世块开始。程序选项--last-checkpoint将允许您指定要开始的块高。通常，维护人员会复制每个列表的最后一个高度，并从这里开始。

其他有用的选项包括

• --transport direct：直接连接到zebrad实例
• --addr：为节点提供自定义RPC地址和端口
• -- -testnet：将zcash-cli二进制文件连接到测试网节点实例

您可以使用以下命令查看所有zebra-checkpoints选项：

target/release/zebra-checkpoints --help

有关检查点列表的更多详细信息，请参阅zebra-checkpoints README。

测试网检查点生成

要更新测试网检查点，zebra-checkpoints需要连接到测试网节点。

要启动测试网节点，您可以选择

• 使用带有zebrad.toml的zebrad启动，其中network.network设置为Testnet，或
• 运行zcashd -testnet。

然后使用上述命令重新生成检查点。

提交新的检查点作为pull请求

• 如果您从当前列表的最后一个检查点开始，请将检查点列表添加到现有的检查点文件末尾。如果您从创世块开始，则替换整个文件。
• 在https://github.com/ZcashFoundation/zebra/pulls打开包含更新的主网和测试网列表的pull请求

zebrad-hash-lookup

给定一个块哈希，脚本将使用zcash-cli获取更多信息。

$ echo "00000001f53a5e284393dfecf2a2405f62c07e2503047a28e2d1b6e76b25f863" | zebrad-hash-lookup
high: 3299
time: 2016-11-02T13:24:26Z
hash: 00000001f53a5e284393dfecf2a2405f62c07e2503047a28e2d1b6e76b25f863
prev: 00000001dbbb8b26eb92003086c5bd854e16d9f16e2e5b4fcc007b6b0ae57be3
next: 00000001ff3ac2b4ccb57d9fd2d1187475156489ae22337ca866bbafe62991a2
$

该程序通常作为zebrad-log-filter的一部分使用，其中哈希将从zebrad输出中捕获。

zebrad-log-filter

该程序设计用于过滤zebra终端或日志文件的输出。每次看到哈希时，脚本都会捕获它并使用zebrad-hash-lookup获取更多信息。

假设zebrad、zclash-cli、zebrad-hash-lookup和zebrad-log-filter已添加到您的路径，则程序可以按以下方式使用：

$ zebrad -v start | zebrad-log-filter
...
block::Hash("
high: 2800
time: 2016-11-01T16:17:16Z
hash: 00000001ecd754790237618cb79c4cd302e52571ecda7a80e6113c5e423c0e55
prev: 00000003ed8623d9499f4bf80f8bc410066194bf6813762b31560f9319205bf8
next: 00000001436277884eef900772f0fcec9566becccebaab4713fd665b60fab309
"))) max_checkpoint_height=Height(419581)
...

zcash-rpc-diff

本程序比较 zebrad 和 zcashd RPC 响应。

请确保您已安装并同步了 zcashd 和 zebrad。

脚本

1. 获取 zebrad 和 zcashd 的提示高度和网络
2. 使用 zcash-cli 向它们发送 RPC 请求
3. 使用 diff 比较响应
4. 将完整的响应保存在临时目录中的文件中，以便您可以详细检查
5. 如果可能，比较不同的 RPC 方法以保持一致性

假设 zebrad 的 RPC 端口为 28232，您应该能够运行

$ zebra-utils/zcash-rpc-diff 28232 getinfo
Checking zebrad network and tip height...
Checking zcashd network and tip height...

Request:
getinfo

Querying zebrad main chain at height 1649797...
Querying zcashd main chain at height 1649797...

Response diff (between zcashd port and port 28232):
--- /run/user/1000/tmp.g9CJecu2Wo/zebrad-main-1649797-getinfo.json      2022-04-29 14:08:46.766240355 +1000
+++ /run/user/1000/tmp.g9CJecu2Wo/zcashd-main-1649797-getinfo.json      2022-04-29 14:08:46.769240315 +1000
@@ -1,4 +1,16 @@
 {
-  "build": "1.0.0-beta.8+54.ge83e93a",
-  "subversion": "/Zebra:1.0.0-beta.8/"
+  "version": 4070050,
+  "build": "v4.7.0-gitian",
+  "subversion": "/MagicBean:4.7.0/",
... more extra zcashd fields ...
 }

有时 zcashd 将有额外的字段 (+) 或不同的数据 (- 和 +)。有时它会有相同的数据，但顺序不同。

如果高度或网络不同，脚本将警告您，然后显示查询不匹配节点状态的结果。

脚本接受任何数量的任何 RPC。如果节点没有实现 RPC，脚本将带错误退出。

配置

脚本使用配置的 zcash-cli RPC 端口，以及命令行中提供的 zebrad 端口。

它实际上不会检查它正在与哪种节点通信，因此如果您想比较两个 zcashd 或 zebrad 节点，可以这样做。（只需编辑 zcash.conf 文件，该文件由 zcash-cli 使用，或者编辑脚本。）

您可以使用这些环境变量覆盖脚本调用的二进制文件

• $ZCASH_CLI
• $DIFF
• $JQ

扫描结果阅读器

一个用于显示 Zebra 扫描结果的实用程序。

工作原理

1. 打开 Zebra 的扫描存储并读取包含扫描密钥和 TXID 的结果。
2. 使用 getrawtransaction RPC 从 Zebra 获取交易。
3. 使用相应的扫描密钥解密交易输出。
4. 打印输出中的备忘录。

如何尝试

使用 Zebra 扫描区块链

1. 请按照 Zebra 书籍中的 构建和安装 以及 配置 指令操作。

2. 请确保 Zebra 在主网上运行并监听默认的 RPC 端口。配置文件中应包含以下内容

   [network]
   network = 'Mainnet'
   
   [rpc]
   listen_addr = "127.0.0.1:8232"
   

3. 使用您的配置文件运行 Zebra。您可以参考书籍中的 扫描区块链 部分，以获取更多详细信息。

运行阅读器

4. 要打印出可由提供的扫描密钥解密的输出中的备忘录，请同时运行 Zebra 和阅读器。例如

   cargo run --release --features shielded-scan --bin scanning-results-reader
   

OpenAPI 生成器

此实用程序通过从 zebra-rpc 集装箱代码中的 RPC 方法文档中提取信息来生成 openapi.yaml 规范。

用法

要使用生成器工具，请使用以下命令构建和运行它

cargo run --bin openapi-generator --features="openapi-generator"

此命令将在 Zebra 项目的存储库根目录中创建或更新一个 openapi.yaml 文件。

使用此实用程序生成的最新规范可以在 此处 找到。

文档标准

为了使脚本正常工作，每个 RPC 方法文档都需要遵循一个特定的、良好定义的格式。例如，以下是对 getblock 方法的代码注释，该方法接受参数

/// Returns the requested block by hash or height, as a [`GetBlock`] JSON string.
/// If the block is not in Zebra's state, returns
/// [error code `-8`.](https://github.com/zcash/zcash/issues/5758)
///
/// zcashd reference: [`getblock`](https://zcash.github.io/rpc/getblock.html)
/// method: post
/// tags: blockchain
///
/// # Parameters
///
/// - `hash_or_height`: (string, required, example="1") The hash or height for the block to be returned.
/// - `verbosity`: (number, optional, default=1, example=1) 0 for hex encoded data, 1 for a json object, and 2 for json object with transaction data.
///
/// # Notes
///
/// With verbosity=1, [`lightwalletd` only reads the `tx` field of the
/// result](https://github.com/zcash/lightwalletd/blob/dfac02093d85fb31fb9a8475b884dd6abca966c7/common/common.go#L152),
/// and other clients only read the `hash` and `confirmations` fields,
/// so we only return a few fields for now.
///
/// `lightwalletd` and mining clients also do not use verbosity=2, so we don't support it.
#[rpc(name = "getblock")]
fn get_block(
   &self,
   hash_or_height: String,
   verbosity: Option<u8>,
) -> BoxFuture<Result<GetBlock>>;

没有参数的方法示例可以是 getinfo 调用

#[rpc(name = "getinfo")]
/// Returns software information from the RPC server, as a [`GetInfo`] JSON struct.
///
/// zcashd reference: [`getinfo`](https://zcash.github.io/rpc/getinfo.html)
/// method: post
/// tags: control
///
/// # Notes
///
/// [The zcashd reference](https://zcash.github.io/rpc/getinfo.html) might not show some fields
/// in Zebra's [`GetInfo`]. Zebra uses the field names and formats from the
/// [zcashd code](https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87).
///
/// Some fields from the zcashd reference are missing from Zebra's [`GetInfo`]. It only contains the fields
/// [required for lightwalletd support.](https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95)
fn get_info(&self) -> Result<GetInfo>;

在 zebra-rpc/src/methods.rs 和 zebra-rpc/src/methods/get_block_template_rpcs.rs 文件中找到更多示例。

生成器将检测新方法，如果它们是 Rpc 特性的成员，该特性位于 zebra-rpc/src/methods.rs 文件中，并且在 GetBlockTemplateRpc 中，该特性位于 zebra-rpc/src/methods/get_block_template_rpcs.rs 文件内。