Architecture

Subsystems

libp2p host and transport

Peer connections and the gossip topics the marketplace and consensus publish on. Discovery is peer-to-peer; there is no broker and no registry server. The host identity is persisted, so a node keeps its peer id across restarts and the multiaddrs other operators hold stay valid.

Gossip validation, before the relay

gossipsub forwards a message to the mesh BEFORE the application handler sees it, so every check the consensus engine makes - is the proposer a validator, does the signature verify - used to happen after the whole mesh had already spent bandwidth on an unauthenticated peer's bytes. A topic validator now runs first and bounds the STRUCTURE of a payload rather than any one field, so it covers every message type and any future one. Measured: a 1 MiB message declaring 349503 transactions decoded with no error into 204 MiB of heap; walking its tokens instead costs 1632 bytes.

Peer scoring

Rejecting a message stops that message; scoring is what stops the PEER. gossipsub tracks a score per peer and suppresses gossip, then publishing, then the peer entirely as it falls. Without it a peer sending nothing but garbage is refused a million times and stays a full mesh member. Measured on two hosts: 60 published messages reached validation 6 times before the peer was ignored. The freeloader penalty is deliberately off, because on a quiet chain it would graylist honest validators and a graylisted validator's votes stop being counted.

Compute marketplace

The provider order book and job records. Registering publishes a manually observed MATRIX-denominated quote with an expiry; submitting a job snapshots the accepted unit price and quote metadata so later refreshes cannot reprice work already reserved.

Consensus engine

An ed25519 validator set, a round-robin leader, and two voting phases per height. Bonded-open candidates self-sign admission after a positive bond; the set is chain state and changes at epoch boundaries. Burn-to-native bridge releases are always ordered here and require native voting-power consensus.

Base bridge boundary

WrappedMatrix minting is checked by the fixed secp256k1 attestor committee embedded at EVM deployment. That immutable committee is separate from the dynamic native bonded-open validator set; validator joins do not silently gain EVM mint authority.

Inference backends

An Ollama-style local runner, an OpenAI-compatible proxy whose key comes from the environment, or a deterministic echo backend that needs no GPU.

Pebble store

One embedded key-value store per node, holding the marketplace ledger, bridge accounting and committed consensus blocks under disjoint key prefixes.

gRPC services

Market, inference and admin, each on its own port, gated by the same authentication when ACLs are enabled.

HTTP endpoint

The same market and inference services over plain HTTP, as JSON, on port 9093. Raw gRPC needs HTTP/2 trailers that no browser can produce, so this is the surface a web app, a dApp front end or the Console in a WebView actually calls. Same objects, same auth.

How it is configured

One YAML file, written initially by matrixd -init and read at startup. The generated file is a secure baseline, not a production launch profile. The excerpt below shows an explicit public overlay; replace its origin and copy consensus values exactly across the network. See configuration for the rest.

network:
  listen_addr: /ip4/0.0.0.0/tcp/9000
  bootstrap_peers: []
storage:
  engine: pebble
  path: ~/.matrix/data
admin:
  addr: 0.0.0.0:9090      # gRPC: deploy, health, logs
market:
  addr: 0.0.0.0:9091      # gRPC: matrix.market.v1.MarketService
inference:
  addr: 0.0.0.0:9092      # gRPC: matrix.inference.v1.InferenceService
  echo_provider: local    # GPU-free backend, for trying the flow
connect:
  addr: 0.0.0.0:9093      # HTTP/JSON for the same services; "off" disables it
  public_reads: true       # keyless Get*/List* only
  signed_writes: true      # client-signature-authorized writes only
  rate_limit_per_minute: 600
  rate_limit_burst: 120
  allowed_origins: ["https://matrix.example.org"] # exact public origin, never "*"
consensus:
  membership_mode: bonded-open
  validators: []          # genesis ids; empty creates a solo/dev genesis set
  stake:
    enabled: true
    min_bond: 1000000000000000