oceanprotocol/aquarius

Aquarius

镜像概述和主要用途

Aquarius是Ocean Protocol工具集的一部分，作为链下多链元数据缓存服务，连接Elasticsearch数据库。它持续监控上的MetadataCreated和MetadataUpdated事件，处理这些事件并将元数据存储到数据库中。通过Aquarius API，用户可以便捷地访问元数据，无需自行扫描。

核心功能和特性

元数据处理方式

• 元数据可先压缩（使用lzma）和加密（强烈推荐）后上链
• 链上元数据不存储在链上存储中，而是通过MetadataCreated事件日志捕获
• 元数据的加密和解密由Provider处理，Aquarius与Provider支持UTF-8编码字符串

组件与架构

Aquarius基于Python Flask框架构建，包含以下核心组件：

Aquarius API

提供REST API接口，用于从链下数据存储中获取元数据。详细API说明可参考API.md。

EventsMonitor

持续运行以检索和索引链上元数据，将结果保存到Elasticsearch数据库。主要组成部分：

• ElasticsearchInstance：通过环境变量配置
• MetadataContract：通过METADATA_CONTRACT_ADDRESS环境变量配置
• De*r类**：通过与Provider通信处理链上数据的解压缩和解密
• ALLOWED_PUBLISHERS：限制允许发布元数据的地址列表
• Purgatory：基于ASSET_PURGATORY_URL和ACCOUNT_PURGATORY_URL环境变量，标记某些资产为"炼狱"状态（"isInPurgatory": True）
• VeAllocate：基于VEALLOCATE_URL和VEALLOCATE_UPDATE_INTERVAL环境变量，更新数据集的veAllocation
• 起始块：通过BFACTORY_BLOCK和METADATA_CONTRACT_BLOCK定义，结合Elasticsearch中存储的最后区块，避免重复索引

EventsMonitor处理流程：

1. 按BLOCKS_CHUNK_SIZE定义的区块块处理区块
2. 检索每个区块的MetadataCreated和MetadataUpdated事件
3. 通过MetadataCreatedProcessor和MetadataUpdatedProcessor类处理事件：
   • 可选：通过RBAC_SERVER_URL和ALLOWED_PUBLISHERS检查权限
   • 解压缩并可选解密资产元数据
   • 检查资产是否需要进入炼狱状态
   • 创建JSON记录并保存到Elasticsearch
   • 若MetadataUpdated事件对应的资产在Elasticsearch中不存在，则视为MetadataCreated事件处理

使用场景和适用范围

Aquarius适用于需要访问Ocean Protocol链上元数据的应用场景，如：

• 数据市场平台开发
• 元数据检索服务
• 多链元数据聚合应用
• 需要监控元数据创建和更新的服务

详细使用方法和配置说明

环境变量配置

必填环境变量

# Ethereum网络URL
# 建议：连接官方网络时，创建Infura项目ID并使用包含项目ID的Infura URL
EVENTS_RPC
  示例:
  "http://172.15.0.3:8545", "wss://rinkeby.infura.io/ws/v3/INFURA_ID"

# 在主Flask应用的线程中运行EventsMonitor
EVENTS_ALLOW
  接受值:
    "0" - 禁用
    "1" - 启用

# 在单独进程中运行EventsMonitor，覆盖`EVENTS_ALLOW`
# 仅在Docker容器中运行时使用
RUN_EVENTS_MONITOR
  接受值:
    "0" - 禁用
    "1" - 启用

# 在事件监控器中启动HTTP服务器，用于K8s存活探测
# 访问端口5001的根端点（如http://172.0.0.1:5001），事件线程正常运行时返回200 OK
EVENTS_HTTP
  接受值:
    "1" - 启用

可选环境变量

bash
# 启用Aquarius API，默认值：1，若仅使用事件监控器无需暴露API可禁用
RUN_AQUARIUS_SERVER

# 解密资产时向Provider标识Aquarius实例，Provider可能基于此地址允许或拒绝解密
PRIVATE_KEY

# 已部署合约地址的JSON文件路径（如address.json）
ADDRESS_FILE

# 从`ADDRESS_FILE`读取合约地址时使用的网络名称
# 若未设置，网络名称从当前网络ID或`EVENTS_RPC`值（拆分wss://、http://或https://部分及后缀）推导
NETWORK_NAME

# 限制元数据缓存到指定发布者列表，格式为发布者地址列表
ALLOWED_PUBLISHERS

# 元数据合约地址，用于覆盖ocean-contracts中的值
METADATA_CONTRACT_ADDRESS

# 元数据合约部署的区块号
METADATA_CONTRACT_BLOCK

# 设为1时，从第一个元数据和BFactory区块号或特定区块号读取事件（用于调试）
IGNORE_LAST_BLOCK

# 扫描事件时的区块块大小限制，Infura接受10k区块，其他通常为1000（默认值）
BLOCKS_CHUNK_SIZE

# 资产炼狱和账户炼狱URL，格式为包含地址和原因的字典列表
# 示例：https://github.com/oceanprotocol/list-purgatory/blob/main/list-accounts.json
# 重要：若运行多链Aquarius事件监控器，确保只有一个事件监控器处理炼狱
ASSET_PURGATORY_URL
ACCOUNT_PURGATORY_URL

# 炼狱更新（刷新）时间（分钟）
PURGATORY_UPDATE_INTERVAL

# 获取veAllocation列表的URL，主网使用https://df-sql.oceandao.org/nftinfo，goerli使用https://test-df-sql.oceandao.org/nftinfo
# 格式为包含chainID、nft_addr和ve_allocated的字典列表，其他网络不应设置
VEALLOCATE_URL

# veAllocate更新（刷新）时间（分钟）
VEALLOCATE_UPDATE_INTERVAL

# RBAC权限服务器URL，若设置，Aquarius将检查RBAC权限；留空则跳过检查
RBAC_SERVER_URL

# 是否在链ID上重新索引事件时 clean start
EVENTS_CLEAN_START

# 子图URL，格式为JSON字符串，映射链ID到子图URL
SUBGRAPH_URLS

# 处理失败资产的队列，重试因临时网络问题等导致的失败
PROCESS_RETRY_QUEUE

# 放弃前重试事件的最长时间，默认2周
PROCESS_RETRY_MAX_HOLD

# 事件监控器检查新事件的间隔时间（秒），默认30
EVENTS_MONITOR_SLEEP_TIME
# 事件监控器处理队列的间隔时间（秒），默认60
EVENTS_PROCESS_QUEUE_SLEEP_TIME
# 事件监控器更新ve_allocate的间隔时间（秒），默认300
EVENTS_VE_ALLOCATE_SLEEP_TIME
# 事件监控器检查NFT转移的间隔时间（秒），默认300
EVENTS_NFT_TRANSFER_SLEEP_TIME
# 事件监控器检查炼狱列表的间隔时间（秒），默认300
EVENTS_PURGATORY_SLEEP_TIME

运行多链Aquarius

使用单个Aquarius实例索引多个链的步骤：

1. 运行一个或多个pod，设置RUN_AQUARIUS_SERVER=1、RUN_EVENTS_MONITOR=0和EVENTS_ALLOW=0，仅启用API部分
2. 为每个链启动一个pod，设置：
   • RUN_EVENTS_MONITOR=1和RUN_AQUARIUS_SERVER=0（仅运行EventsMonitor）
   • 相应的EVENTS_RPC、NETWORK_NAME、BLOCKS_CHUNK_SIZE、METADATA_CONTRACT_BLOCK、METADATA_CONTRACT_ADDRESS等环境变量

部署配置和示意图可参考https://github.com/oceanprotocol/aquarius/tree/main/deployment%E3%80%82

本地运行与开发

快速启动

开发市场平台时，可使用Barge在本地运行Aquarius及其他组件，详见https://github.com/oceanprotocol/barge%E3%80%82

API文档

• 官方API文档：[***]
• 元数据结构详情：Ocean文档
• 本地运行时，Swagger API文档地址：http://localhost:5000/api/docs 或 [***]

本地运行

测试环境下，Barge已足够；若需自定义配置运行Aquarius，参考开发者文档。

开发指南

如需改进或定制Aquarius，参考开发者流程了解贡献方式。

许可证

Copyright 2022 Ocean Protocol Foundation Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

[***]

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.