Matrix Protocol

Transport

libp2p, with gossipsub topics. There is no broker and no registry server: a node discovers peers and subscribes. Messages are JSON on the wire and every one that can move value carries an ed25519 signature over a canonical, length-prefixed encoding, so no two distinct field combinations can produce the same signed bytes.

Topics

matrix.consensus.v2/proposal        a leader putting a block to the vote
matrix.consensus.v2/vote            a validator's prevote or precommit
matrix.consensus.v2/sync-request    "I am at height H, send me what I missed"
matrix.consensus.v2/sync-response   committed blocks plus the quorum that committed them
matrix.consensus.v2/head            a validator's committed height, once a second

The version in the topic name is load-bearing. v2 introduced two voting phases and the proposal envelope, and a v1 node cannot act on a v2 message: sharing a topic across that boundary would look like a network fault rather than a version boundary, so the versions simply do not meet.

matrix/market/announce/v1   provider capacity and price
matrix/market/jobs/v1      job records
matrix/market/settle/v1    settlement

Messages

Block

Immutable once built, and that matters: round, proposer and signature are all part of its hash, so a validator that re-proposes a block at a later round has to forward these exact bytes. Re-signing would change the hash, which would make it a different block, which every validator locked on the original would correctly refuse.

Block {
  height          uint64   // position in the committed chain
  round           uint64   // the round this value first appeared at
  prev_block_hash bytes    // links to the committed head
  txs             []Transaction
  proposer_id     string   // the validator that created it
  signature       bytes    // by that validator, over the canonical bytes
}

Proposal

The envelope around a block. It exists so the same value can be proposed more than once: the round being proposed for and the leader proposing it live here, not in the block.

Proposal {
  block        Block
  round        uint64            // the round being proposed FOR, >= block.round
  proposer_id  string            // the leader of that round
  signature    bytes
  justify      PolkaCertificate  // present when locked validators must switch
}

Vote

Two phases. A prevote says what a validator sees this round; a quorum of prevotes for one block is a polka. On seeing a polka a validator precommits that block, and the precommit is what locks it. A quorum of precommits commits. A vote for 32 zero bytes is a nil vote - "I support no block this round" - which is how a round concludes on evidence instead of on a timeout.

Vote {
  type        PREVOTE | PRECOMMIT
  height      uint64
  round       uint64
  block_hash  bytes   // 32 zero bytes means "no block this round"
  voter_id    string
  public_key  bytes
  signature   bytes
}

PolkaCertificate

The evidence a leader shows to unlock the others. A validator locked on one block will prevote a different one only when shown a quorum of prevotes for it at a round at least as high as its lock. A precommit quorum is deliberately not accepted here: that is a commit certificate, and a node holding one commits the block rather than voting on it.

PolkaCertificate {
  height      uint64
  round       uint64
  block_hash  bytes
  votes       []Vote   // a quorum of PREVOTES, each verified independently
}

Catching up

Gossip is best effort, so a node can miss the one proposal its height committed on. The votes keep arriving and can even reach a quorum, but a quorum without the body cannot commit, and no leader re-proposes a committed block. That is why sync-request and sync-response exist: a peer serves the committed block together with the precommit quorum that committed it, and the receiver verifies those votes itself. A served block commits under exactly the same rule as a proposed one, so the sync path adds no new trust.

head announcements exist for the quiet case: a node that was down while blocks committed, coming back to a network with no traffic, would otherwise never learn it was behind. Only validators announce, so the cost tracks the validator set rather than the size of the network.