EXTENDED DOCUMENTATION

Relayer

text
workers/morpheus-relayer
is the async request/response bridge for Morpheus Oracle.

In the current production architecture, the relayer sits between the on-chain request surface and the confidential execution plane. It persists chain-originated work before checkpoint advancement and routes execution to the correct runtime lane.

It closes the loop:

  1. Oracle request is emitted on-chain
  2. Relayer detects the event
  3. Relayer forwards the payload to the Oracle or DataFeed runtime
  4. Relayer calls
    text
    fulfillRequest(...)
    back on the Oracle contract
  5. Callback consumer receives the result

Supported chains

  • Neo N3
  • Neo X code still exists in-repo as archived reference, but the active supported relayer path is Neo N3 only

Request routing

The relayer maps

text
requestType
plus payload shape to worker routes:

  • text
    compute
    →
    text
    /compute/execute
  • text
    datafeed
    /
    text
    pricefeed
    /
    text
    feed
    →
    text
    /oracle/feed
  • text
    vrf
    /
    text
    random
    →
    text
    /vrf/random
  • text
    privacy_oracle
    and other Oracle requests →
    text
    /oracle/smart-fetch
  • text
    datafeed
    /
    text
    pricefeed
    /
    text
    feed
    →
    text
    /oracle/feed
    internally for operator sync only
  • The relayer prefers the compact smart-fetch response over raw query output

Commands

bash
npm --prefix workers/morpheus-relayer test
npm --prefix workers/morpheus-relayer run once
npm --prefix workers/morpheus-relayer run start
npm --prefix workers/morpheus-relayer run metrics

Required env

  • text
    MORPHEUS_RUNTIME_URL
  • text
    MORPHEUS_RUNTIME_TOKEN
    or
    text
    PHALA_API_TOKEN
    /
    text
    PHALA_SHARED_SECRET
  • text
    MORPHEUS_NETWORK
    (
    text
    testnet
    or
    text
    mainnet
    )
  • text
    NEO_RPC_URL
  • text
    CONTRACT_MORPHEUS_ORACLE_HASH
  • text
    MORPHEUS_RELAYER_NEO_N3_WIF
    or
    text
    MORPHEUS_RELAYER_NEO_N3_PRIVATE_KEY

Archived Neo X variables are intentionally omitted here because they are not part of the current supported operations path.

If direct worker-side provider default resolution is needed during relayer processing, also set:

  • text
    SUPABASE_URL
    or
    text
    NEXT_PUBLIC_SUPABASE_URL
  • text
    SUPABASE_SECRET_KEY

Reliability Model

The relayer persists:

  • per-chain last scanned block checkpoints
  • processed-event records for dedupe
  • retry queue entries with exponential backoff
  • dead-letter history for exhausted requests
  • aggregate metrics for the latest runs

Config knobs:

  • text
    MORPHEUS_RELAYER_CONCURRENCY
  • text
    MORPHEUS_RELAYER_MAX_BLOCKS_PER_TICK
  • text
    MORPHEUS_RELAYER_MAX_RETRIES
  • text
    MORPHEUS_RELAYER_RETRY_BASE_DELAY_MS
  • text
    MORPHEUS_RELAYER_RETRY_MAX_DELAY_MS
  • text
    MORPHEUS_RELAYER_PROCESSED_CACHE_SIZE
  • text
    MORPHEUS_RELAYER_DEAD_LETTER_LIMIT
  • text
    MORPHEUS_RELAYER_LOG_FORMAT
  • text
    MORPHEUS_RELAYER_LOG_LEVEL
  • text
    MORPHEUS_RELAYER_NEO_N3_START_BLOCK

Checkpoint note:

  • if a saved checkpoint is ahead of the current confirmed chain tip, the relayer now resets that chain checkpoint to the configured start block instead of stalling forever

检查点说明：

  • 如果已保存的 checkpoint 高于当前已确认链高度，relayer 现在会自动回退到配置的起始区块，而不是永久卡住

Neo N3 txproxy note:

  • the Neo N3 txproxy allowlist now permits both
    text
    fulfillRequest
    and
    text
    queueAutomationRequest
    on the Morpheus Oracle contract so automation executions can be queued on-chain

Supabase Persistence

If

text
SUPABASE_URL
plus a service key are configured, the relayer also persists:

  • run snapshots to
    text
    morpheus_relayer_runs
  • job lifecycle records to
    text
    morpheus_relayer_jobs

The dashboard can read these through:

  • text
    /api/relayer/metrics
  • text
    /api/relayer/jobs
  • text
    /api/relayer/dead-letters

Manual operator actions:

  • text
    POST /api/relayer/jobs/retry
  • text
    POST /api/relayer/jobs/replay

These enqueue the stored event back into the relayer for manual retry / dead-letter replay.

State file

The relayer stores its durable runtime state in:

  • text
    .morpheus-relayer-state.json

Override with:

  • text
    MORPHEUS_RELAYER_STATE_FILE

Docker

Build and run:

bash
docker build -f workers/morpheus-relayer/Dockerfile -t morpheus-relayer .
docker run --env-file .env morpheus-relayer

systemd

Example unit file:

  • text
    deploy/systemd/morpheus-relayer.service

Typical install:

bash
sudo cp deploy/systemd/morpheus-relayer.service /etc/systemd/system/morpheus-relayer.service
sudo systemctl daemon-reload
sudo systemctl enable morpheus-relayer
sudo systemctl start morpheus-relayer

Phala Sidecar Pattern

A simple production pattern is:

  • deploy
    text
    workers/phala-worker
    to Phala
  • run
    text
    workers/morpheus-relayer
    as a sidecar process on a small VM or container
  • point
    text
    MORPHEUS_RUNTIME_URL
    at the public Morpheus runtime endpoint
  • keep chain updater keys and Supabase service credentials only in the sidecar env
CURRENT DESIGNUPDATED FOR DUAL-CVM ARCHITECTURE
Morpheus Oracle