Skip to content

BLOCK_STORAGE.md

Latest commit

 

History

History
189 lines (147 loc) · 4.41 KB

BLOCK_STORAGE.md

File metadata and controls

189 lines (147 loc) · 4.41 KB

区块数据存储功能（模拟全节点）

功能说明

系统支持将监听到的区块和交易数据保存到本地，并提供类似全节点的查询接口。这是一个轻量级的"模拟全节点"功能：

  • ✅ 只监听和存储：不参与共识，不验证区块，只是保存数据
  • ✅ 文件系统存储：使用 JSON 文件存储，简单可靠
  • ✅ 查询接口：提供 JSON-RPC 和 RESTful API 接口
  • ✅ 多链支持：支持所有已实现的区块链

启用方法

1. 配置启用

在 config/config.yaml 中添加存储配置：

storage:
  enabled: true              # 启用区块存储
  data_dir: "./data/blocks"  # 数据存储目录（相对路径或绝对路径）

server:
  port: 8080  # RPC 服务端口（可选，用于查询接口）

2. 数据目录结构

启用后会创建以下目录结构：

data/blocks/
├── ethereum/
│   ├── blocks/           # 区块数据
│   │   ├── 12345678.json
│   │   ├── 12345679.json
│   │   └── ...
│   ├── transactions/     # 交易数据（按区块号组织）
│   │   ├── 12345678/
│   │   │   ├── 0xabc123...json
│   │   │   └── ...
│   │   └── ...
│   └── index/            # 索引文件
│       ├── latest.json    # 最新区块索引
│       └── addresses/     # 地址索引
├── bnb/
│   └── ...
├── solana/
│   └── ...
└── ...

查询接口

JSON-RPC 2.0 接口

端点: http://localhost:8080/rpc

示例请求

# 获取最新区块
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getLatestBlock",
    "params": ["ethereum"],
    "id": 1
  }'

# 根据区块号获取区块
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getBlockByNumber",
    "params": ["ethereum", 12345678],
    "id": 2
  }'

# 根据区块哈希获取区块
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getBlockByHash",
    "params": ["ethereum", "0x1234..."],
    "id": 3
  }'

# 获取交易
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getTransaction",
    "params": ["ethereum", "0xabc123..."],
    "id": 4
  }'

# 获取区块中的所有交易
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getBlockTransactions",
    "params": ["ethereum", 12345678],
    "id": 5
  }'

RESTful API 接口

1. 获取区块

GET /api/v1/blocks/{chain}/{blockNumber}

示例：

curl http://localhost:8080/api/v1/blocks/ethereum/12345678

2. 获取交易

GET /api/v1/transactions/{chain}/{txHash}

示例：

curl http://localhost:8080/api/v1/transactions/ethereum/0xabc123...

3. 获取链信息

GET /api/v1/chains/{chain}

示例：

curl http://localhost:8080/api/v1/chains/ethereum

响应示例：

{
  "chain": "ethereum",
  "latest_block": 12345678,
  "latest_hash": "0x1234...",
  "timestamp": "2024-01-01T12:00:00Z",
  "tx_count": 150
}

支持的链

所有已实现的链都支持存储：

  • ethereum - 以太坊
  • bnb - BNB Chain
  • solana - Solana
  • sui - Sui
  • tron - Tron
  • btc - Bitcoin

工作原理

  1. 监听区块：监听器检测到新区块时，自动保存区块信息
  2. 保存交易：每笔监听到的交易都会保存到对应区块目录
  3. 定期同步：每 30 秒同步一次最新区块信息
  4. 索引维护：自动维护区块哈希索引和最新区块索引

注意事项

  1. 存储空间：区块数据会持续增长，建议定期清理旧数据或限制存储范围
  2. 性能：文件系统存储适合小规模使用，大规模建议使用数据库
  3. 数据完整性：只保存监听到的数据，不会补全历史数据
  4. 启动同步：首次启动只从当前开始保存，不会同步历史区块

数据清理

如需清理旧数据，可以直接删除 data/blocks/{chain}/blocks/ 目录下的旧区块文件。

注意：清理后索引会自动重建，但已删除的区块无法恢复（除非重新监听）。