omniops/relayer

Relayer Docker镜像文档

1. 镜像概述

Relayer镜像用于部署跨链消息中继器，核心功能是将源链的跨链消息（附带 graphic 证明）可靠地提交至目标链，实现不同网络间的消息传递与验证。该镜像封装了消息监听、证明生成、交易签名及目标链提交等完整流程，简化跨链消息中继的部署与运维。

2. 核心功能与特性

2.1 核心功能

• 跨链消息转发：监听源链的跨链事件，提取消息并生成验证证明。
• 证明自动生成：集成链上验证逻辑，自动生成符合目标链验证合约要求的消息证明（如Merkle证明、零知识证明等）。
• 目标链提交：通过目标链RPC接口发送交易，将消息与证明提交至目标链验证合约。

2.2 关键特性

• 多链兼容性：支持主流***网络（如EVM链、Cosmos链等，具体取决于底层实现）。
• 高可靠性：内置消息队列与重试机制，处理网络波动或交易失败场景。
• 轻量级部署：Docker容器化设计，支持单节点或集群部署。
• 可配置性：通过环境变量灵活配置链参数、证明规则及运行时行为。

3. 使用场景与适用范围

3.1 典型使用场景

• 跨链资产转移：DeFi应用中，将用户资产跨链转移的消息中继（如从***到Polygon）。
• 跨链合约交互：多链DApp中，源链合约调用触发目标链合约执行（如跨链治理提案）。
• 跨链数据同步：预言机数据、链上状态（如NFT所有权）跨链同步至目标链。
• 跨链NFT交易：NFT跨链转移时，中继所有权变更消息与证明至目标链。

3.2 适用范围

• ***开发者：快速部署跨链消息基础设施。
• 跨链服务提供商：构建高可用的中继服务集群。
• 多链项目团队：为DApp集成跨链消息能力。

4. 使用方法与配置说明

4.1 基本使用（docker run）

通过docker run命令启动中继器，需指定源链/目标链参数、密钥及网络配置：

bash
docker run -d \
  --name relayer \
  -e SOURCE_CHAIN_RPC="https://source-chain-rpc.example.com" \
  -e DEST_CHAIN_RPC="https://dest-chain-rpc.example.com" \
  -e PRIVATE_KEY="0xYourPrivateKeyForDestChainTransaction" \
  -e PROOF_VERIFIER_CONTRACT="0xDestChainProofVerifierContractAddress" \
  -e SOURCE_CHAIN_ID=1 \
  -e DEST_CHAIN_ID=5 \
  -v ./relayer-data:/app/data \
  --network host \
  relayer:latest

4.2 Docker Compose配置示例

通过docker-compose.yml管理多环境配置（如测试/生产环境分离）：

yaml
version: "3.8"
services:
  relayer:
    image: relayer:latest
    container_name: relayer
    restart: unless-stopped
    environment:
      - SOURCE_CHAIN_RPC=https://source-chain-rpc.example.com
      - DEST_CHAIN_RPC=https://dest-chain-rpc.example.com
      - PRIVATE_KEY=${RELAYER_PRIVATE_KEY}  # 从环境变量文件加载密钥
      - PROOF_VERIFIER_CONTRACT=0xDestChainProofVerifierContractAddress
      - SOURCE_CHAIN_ID=1
      - DEST_CHAIN_ID=5
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
      - MESSAGE_QUEUE_SIZE=2000  # 消息队列缓冲区大小
      - RETRY_DELAY=10  # 失败重试延迟（秒）
    volumes:
      - ./relayer-data:/app/data  # 持久化消息缓存与运行日志
    network_mode: host  # 直接使用主机网络（或配置自定义桥接网络）

4.3 环境变量详解

4.4 卷与网络配置

• 卷挂载：/app/data目录用于持久化消息缓存（未提交成功的消息）与运行日志，建议通过宿主机目录挂载（如示例中的./relayer-data:/app/data），避免容器重启后数据丢失。
• 网络配置：需确保容器可访问源链/目标链的RPC端点（可通过--network host直接使用主机网络，或配置自定义桥接网络并开放出站端口）。

5. 部署示例

5.1 单节点部署（测试环境）

适用于开发或测试场景，快速验证跨链消息流程：

bash
# 启动Relayer容器
docker run -d \
  --name relayer-test \
  -e SOURCE_CHAIN_RPC="https://goerli.infura.io/v3/your-api-key" \
  -e DEST_CHAIN_RPC="https://sepolia.infura.io/v3/your-api-key" \
  -e PRIVATE_KEY="0xTestnetPrivateKeyWithEth" \
  -e PROOF_VERIFIER_CONTRACT="0x5FbDB2315678afecb367f032d93F642f64180aa3" \
  -e SOURCE_CHAIN_ID=5 \
  -e DEST_CHAIN_ID=11155111 \
  -e LOG_LEVEL=debug \
  -v ./test-data:/app/data \
  relayer:latest

# 查看日志验证运行状态
docker logs -f relayer-test

5.2 生产环境部署（Docker Compose）

生产环境需配置高可用（如自动重启、资源限制、日志持久化），示例docker-compose.yml：

yaml
version: "3.8"
services:
  relayer:
    image: relayer:latest
    container_name: relayer-prod
    restart: always  # 容器退出时自动重启
    environment:
      - SOURCE_CHAIN_RPC=https://mainnet.infura.io/v3/your-api-key
      - DEST_CHAIN_RPC=https://polygon-mainnet.infura.io/v3/your-api-key
      - PRIVATE_KEY=${RELAYER_PROD_PRIVATE_KEY}  # 从.env文件加载密钥（避免硬编码）
      - PROOF_VERIFIER_CONTRACT=0xProdProofVerifierContractAddress
      - SOURCE_CHAIN_ID=1
      - DEST_CHAIN_ID=137
      - LOG_LEVEL=info
      - MESSAGE_QUEUE_SIZE=5000
      - GAS_LIMIT=500000
    volumes:
      - /data/relayer:/app/data  # 宿主机数据卷，持久化消息与日志
    networks:
      - relayer-network  # 自定义网络隔离
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G

networks:
  relayer-network:
    driver: bridge

6. 注意事项

• 私钥安全：PRIVATE_KEY需妥善保管，生产环境中建议通过 secrets 管理工具（如Docker Secrets、Kubernetes Secrets）注入，避免明文暴露。
• RPC可靠性：源链/目标链RPC端点建议使用高可用服务（如多节点负载均衡），避免单点故障导致消息丢失。
• Gas管理：确保私钥对应地址有足够的目标链原生代币（用于支付Gas），可配置自动Gas价格调整（如有支持）。
• 版本兼容性：不同版本Relayer可能存在配置参数变更，升级前需查阅镜像更新日志。
• 监控告警：建议对接监控工具（如Prometheus、Grafana）监控消息提交成功率、延迟等指标，及时发现异常。