赫罗多特数据处理器 (HDP)

警告：此代码库是实验性的且未经审计。请自行承担风险。

HDP通过zkVM增强链外计算能力，以实现可验证的链上数据集成。更多信息，请访问我们的文档。

简介

数据处理器CLI是用于Cairo程序和zkVM环境开发者的一个基本工具。其主要功能是将可读请求转换为与Cairo程序兼容的格式，允许在Cairo虚拟机上执行命令并生成可执行输出。这种转换是预处理步骤中的关键步骤，为zkVM环境中的链外计算准备数据。

功能

• 开发工具：编码和解码数据湖和计算任务。
• 核心处理：从各种来源编译数据并计算聚合函数。
• 可扩展性：计划支持多个区块链集成和多种ZKVM后端。
• 易用性：提供CLI以方便与系统交互。

安装HDP

使用cargo安装

# Install with cargo
❯ cargo install --git https://github.com/HerodotusDev/hdp --tag v0.2.6 --locked --force

从源代码构建

# clone repo
❯ git clone https://github.com/HerodotusDev/hdp.git

# install hdp
❯ cargo install --path cli -f

入门指南

要启动交互式CLI

# Start the HDP
❯ hdp start
Welcome to Herodotus Data Processor interactive CLI! 🛰️

                _   _   ____    ____
                | | | | |  _ \  |  _ \
                | |_| | | | | | | |_) |
                |  _  | | |_| | |  __/
                |_| |_| |____/  |_|

? Step 1. What's your datalake type?

使用示例

首先找到类似于示例中的.env文件。

其次，运行如下命令

请注意，这将经历预处理 -> 处理步骤。

hdp run -r ${Request file path} -p ${Pre-processor output} -c ${PIE file after process} -o ${Output file after process}

有关hdp run上可用的命令的更全面指南

❯ hdp run --help
Run batch of tasks base on request json file

Usage: hdp run [OPTIONS] --request-file <REQUEST_FILE> --preprocessor-output-file <PREPROCESSOR_OUTPUT_FILE>

Options:
  -r, --request-file <REQUEST_FILE>
          Pass request as json file

      --rpc-url <RPC_URL>
          The RPC URL to fetch the data.

          Can be overwritten by `RPC_URL` environment variable.

      --dry-run-cairo-file <DRY_RUN_CAIRO_FILE>
          dry run contract bootloader program. only used for module task

  -p, --preprocessor-output-file <PREPROCESSOR_OUTPUT_FILE>
          Path to save output file after pre-processing

      --sound-run-cairo-file <SOUND_RUN_CAIRO_FILE>
          hdp cairo compiled program. main entry point

  -o, --output-file <OUTPUT_FILE>
          Path to save output file after process

          This will trigger processing(=pie generation) step

  -c, --cairo-pie-file <CAIRO_PIE_FILE>
          Path to save pie file

          This will trigger processing(=pie generation) step

  -h, --help
          Print help (see a summary with '-h')

集成测试

在HDP中，集成测试确保了诸如SUM、AVG、MIN、MAX和COUNT之类的聚合函数在区块链数据结构中的各种数值字段中正确运行。这些函数专门为数值数据类型设计，确保精确和可靠的计算。

集成测试

HDP的核心稳定性依赖于生成正确的输入文件并运行Cairo程序。为确保这一点，需要完整的集成测试流程来链接预处理器和处理器版本。对于持续集成测试，请参阅hdp-test仓库，其中包含下表中支持功能的所有用例。

支持的聚合函数

• SUM, AVG, MIN, MAX, COUNT：这些函数仅支持具有数值字段的字段。
• SLR：用Cairo 1编写的简单线性回归。输入数组应包含超过2个元素。

所需上下文操作

有关如何实现上下文敏感操作的实用示例，请参考COUNT函数的实现。此示例展示了如何传递和利用额外的上下文进行操作，这对于条件处理或复杂计算特别有用。

在SLR计算期间，我们还需要一个上下文作为计算的目标索引。由于SLR在预处理步骤中不受支持，我们只需传递包含函数上下文的编码任务，Cairo程序将根据提供的索引处理此计算。

函数支持矩阵

以下是支持矩阵，指示每个聚合函数测试哪些区块链元素。矩阵突出显示这些函数适用的字段。

注意：标记为“-”的字段不适用于指定的聚合函数，因为这些字段不包含数值数据或数据类型不适合这些计算。

其他说明

• 请确保应用这些函数的数据字段包含数值，以避免计算错误。
• 有关这些测试的执行方式或如何为测试的进一步开发做出贡献的详细信息，请参阅集成测试指南。

开发

# CI check
cargo make run-ci-flow

本地运行

要在本地稳定环境中运行HDP，您需要安装cairo-run，并在正确的路径中配置必要的工具，并定位编译后的Cairo程序。如果您觉得这些步骤很复杂，只需使用Docker镜像即可。

要在容器环境中安装，您需要在主机机的根目录下运行之前创建空的 input.json、output.json 和 cairo.pie 文件。

并在根目录找到包含预期请求格式的 requeset.json 文件。

docker-compose build

docker-compose up

如果您正在寻找已构建的Docker镜像，您可以从这里拉取。

许可证

hdp 在 GNU通用公共许可证v3.0 下授权。

Herodotus Dev Ltd - 2024