Skip to content
EXTENDED DOCUMENTATION

Relayer

text
workers/neo-os-relayer
is the authoritative Rust async request/response bridge for the Morpheus MiniApp OS kernel.
text
workers/morpheus-relayer
is the frozen Node compatibility/parity implementation; it is not a production authority and is never the target of the canonical run commands below.

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. MiniApp OS kernel request is emitted on-chain
  2. Relayer detects the event
  3. Relayer forwards the payload to the appropriate built-in module lane
  4. Relayer calls
    text
    fulfillRequest(...)
    back on the kernel contract
  5. The kernel persists the canonical inbox item
  6. Optional external callback adapters receive the result when configured

Supported chains

  • Neo N3
  • NeoX

Both chains support request and feed delivery. Select either or both with

text
MORPHEUS_ACTIVE_CHAINS
, and choose
text
requests_only
,
text
feed_only
, or
text
combined
. Automation is not part of this authority boundary and must remain disabled.

Request routing

The relayer is still migrating from legacy

text
requestType
routing to the kernel's
text
miniapp + module + operation
model.

Today it effectively maps legacy request taxonomy onto built-in module lanes:

The relayer maps

text
requestType
plus payload shape to worker routes:

  • text
    compute
    → built-in compute module →
    text
    /compute/execute
  • text
    datafeed
    /
    text
    pricefeed
    /
    text
    feed
    → built-in shared resource module →
    text
    /oracle/feed
  • text
    vrf
    /
    text
    random
    →
    text
    /vrf/random
  • text
    privacy_oracle
    and other legacy Oracle request types → built-in fetch/query module →
    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

Long-term target:

  • requests should be interpreted as kernel requests
  • built-in modules should remain reusable across many registered miniapps
  • miniapps should not need their own generic relayer plumbing

Commands

bash
cargo test --locked --all-targets -p neo-os-relayer
npm run config:relayer:rust
npm run once:relayer
npm run start:relayer
npm run metrics:relayer

The historical Node commands carry the explicit

text
:compat
suffix, for example
text
npm run start:relayer:compat
; use them only under the documented
text
ENABLE_NODE_COMPAT
boundary.

Required env

  • text
    MORPHEUS_RUNTIME_URL
  • text
    MORPHEUS_RUNTIME_TOKEN
    or
    text
    NITRO_API_TOKEN
    /
    text
    NITRO_SHARED_SECRET
  • text
    MORPHEUS_RELAYER_ENCLAVE_FULFILL=true
    for every request lane
  • text
    MORPHEUS_NETWORK
    (
    text
    testnet
    or
    text
    mainnet
    )
  • a network-scoped Neo N3 RPC list and oracle/datafeed contract for each enabled Neo N3 lane
  • text
    MORPHEUS_RELAYER_NEOX_RPC_URL
    ,
    text
    MORPHEUS_RELAYER_NEOX_CHAIN_ID
    , and the NeoX oracle/datafeed contract for each enabled NeoX lane
  • text
    SIGNER_SERVICE_URL
    /
    text
    SIGNER_SERVICE_TOKEN
    with
    text
    SIGNER_ROLE_UPDATER_KEY_ID
    and
    text
    SIGNER_ROLE_ORACLE_VERIFIER_KEY_ID
    — the token belongs to a dedicated bearer caller;
    text
    workload-ed25519
    assertions are not yet supported by the relayer transport. All relayer Neo N3 signing goes through the custody signer service; the relayer holds no signing key material
  • text
    SIGNER_ROLE_NEOX_UPDATER_KEY_ID
    /
    text
    SIGNER_ROLE_NEOX_VERIFIER_KEY_ID
    — separate NeoX custody identities for EIP-1559 submission and semantic EIP-191 fulfillment proofs; the same key id must not be used for both

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 kernel contract so automation executions can be queued on-chain through the compatibility path
  • that automation statement describes the frozen Node compatibility path; the production Rust relayer rejects
    text
    MORPHEUS_AUTOMATION_ENABLED=true

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 the production Rust image. Its default command is deliberately

text
config:validate
, so selecting a run loop is explicit:

bash
docker build -f deploy/nitro/Dockerfile.relayer -t neo-os-relayer:local .
docker run --rm --env-file deploy/nitro/neo-os-relayer.env neo-os-relayer:local

For a loop use

text
docker-compose.rust.yml
with an immutable image. The historical
text
workers/morpheus-relayer/Dockerfile
is Node compatibility only and is not published as a production service image.

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 --now morpheus-relayer

The unit launches

text
/opt/neoos/services/bin/neo-os-relayer
, never npm. Neo N3 and NeoX request/feed delivery are production Rust lanes; automation remains disabled and is rejected during configuration validation. See
text
PRODUCTION_RUST_TOPOLOGY.md
.

Nitro Sidecar Pattern

A simple production pattern is:

  • deploy the Rust
    text
    workers/nitro-enclave-host
    EIF and its paired
    text
    workers/neo-signer
    custody boundary
  • run the
    text
    neo-os-relayer
    Rust binary as a sidecar process on a small VM or container
  • point enclave-fulfillment traffic at the authenticated vsock gateway
  • keep Neo private keys in
    text
    neo-signer
    ; the sidecar holds only its scoped workload credential and non-custody provider configuration

text
workers/nitro-worker
is a separately published compatibility/CVM runtime and parity oracle. It is not the process measured by
text
Dockerfile.enclave
and must not be described or deployed as the Rust Nitro EIF.

CURRENT DESIGNUPDATED FOR DUAL-CVM ARCHITECTURE
NeoOS Services