Matrix OS is a peer-to-peer network for decentralized LLM compute. People leave their idle computers running to join the network like a blockchain node and contribute LLM compute to the network. Anyone can buy LLM compute and API responses with cryptocurrency, and the people who provide compute get paid by the network.
This repository is a polyglot monorepo that consolidates the Matrix OS projects into a single tree. Each subproject keeps its own toolchain and its own README; this root document describes the layout and how to build and test each piece.
services/core- Matrix Core, the Go P2P daemon that turns any machine into a Matrix node.proto- Matrix Proto, the buf-managed Protocol Buffers definitions shared across the network.apps/web- the Next.js marketing website (ecirlabs-web).apps/console- Matrix Console, a Tauri + React + TypeScript + Vite desktop app that connects to a localmatrixdnode to observe and control the marketplace (providers, jobs, wallet/token, consensus, and LLM inference).contracts- the Base-primary Hardhat project for wMATRIX, the 1:1 escrow-backed EVM mirror of native MATRIX. Base Sepolia (84532) is rehearsed before Base production (8453); the native Go L1 remains the source of truth.packages/protocol- the one TypeScript implementation of the wire byte layouts a client signs over (payment digests, run authorizations, message digests). It exists because those layouts were copied into three places and a drift between any copy and the Go verifier is a signature the node rejects for no visible reason.packages/sdk- the TypeScript client SDK. Its layout-parity test signs randomized inputs through both this package and the Go encoder and fails on a single differing byte.
Five screenshots, one per distinct claim: what the network is, the two sides of its market,
what makes balances agreed rather than local, and the desktop app actually running. Native
MATRIX is the coin of the Go consensus L1 and the single source of truth for balances,
capped at 1,000,000,000 whole MATRIX at 9 decimals; wMATRIX is the bridged ERC-20 mirror
that lets the asset list on exchanges, and is not the settlement token. Images live in
docs/screenshots.
The home page: the peer-to-peer market for compute and inference, routing out to the
product pages.
Compute Marketplace: peer-to-peer capacity announce and discovery over libp2p, with signed
jobs that settle in native MATRIX.
LLM Inference: the other half of the market, fulfilled by a local runner or a provider-API
proxy and settled through the same consensus path as compute.
Consensus: fast leader-based BFT, so a balance is one globally agreed fact rather than a
private per-node number.
Matrix Console: providers, jobs, native MATRIX wallet, consensus and inference tabs in one
window, here on the Providers tab showing local and remote capacity with the peer ids they
were discovered from - the whole thing running.
A root go.work ties the Go modules (services/core and proto) together so
they resolve consistently in workspace mode. A single merged .gitignore
covers the build artifacts of every subtree.
Each toolchain is invoked from its own subdirectory.
cd services/core
go build ./...
go test ./...cd proto
buf lint
buf generatecd apps/web
corepack yarn install --frozen-lockfile
corepack yarn lint
corepack yarn buildcd apps/console
corepack yarn install
corepack yarn build # tsc --noEmit && vite build -> dist/
corepack yarn dev # Vite dev server on http://localhost:5173The console is a Tauri + React + Vite desktop app. The web frontend builds and
runs everywhere; the native desktop bundle (corepack yarn tauri build)
additionally needs the WebKitGTK/libsoup system libraries. See the
console README for the connection configuration and
the documented native-build limitation.
cd contracts
npm install
npx hardhat compile
npx hardhat testcd packages/sdk
corepack yarn install --frozen-lockfile
corepack yarn typecheck
corepack yarn test # includes the layout-parity differential test
corepack yarn buildpackages/protocol has no build of its own: it is consumed as TypeScript source
by the web app and mirrored by the SDK, and the parity test above is what keeps
the mirror honest.
Base is the primary EVM launch target. The authoritative procedure is the
Base launch runbook: first rehearse on Base
Sepolia (84532), then perform the reviewed Base production (8453) ceremony.
It covers the immutable 6% wMATRIX cap, exact-backed 5% founder vault, dynamic
native validators versus immutable EVM attestors, bonded-open stake, zero
emission, fee/maintainer policy, user-paid Base gas, and reconciliation evidence.
Start every node from matrixd -init and merge—do not run standalone—the
Base launch overlay example.
The example intentionally contains unresolved deployment inputs and no real
accounts, addresses, origins, RPC credentials, or secrets.
An Ethereum wallet is a first-class client. An account can be controlled by a
secp256k1 key, a transaction can be an ordinary EIP-155 or EIP-1559 envelope
bound to consensus.chain_id, addresses carry an EIP-55 checksum, and
eth_rpc.addr serves the JSON-RPC a wallet needs to add the network. The chain
still runs no EVM: contract creation and calldata are refused rather than
ignored, and eth_call says so instead of returning an empty result.
A block commits to the ledger it was built on - a Merkle root over every balance -
so a node whose apply logic differs refuses to vote and says which two roots
differ, instead of quietly reaching different numbers from the same blocks. The
same root makes one balance provable to someone holding nothing else, which is
what lets anyone check that the bridge escrow actually backs the wrapped supply
(matrix_getAccountProof). It also
carries a protocol version, so the next rule change is an activation height and a
rolling upgrade rather than a coordinated restart. Moving an existing network
onto these formats is the relaunch runbook; the
wrapped token, its pools and its holders are not touched by it.
To contribute GPU capacity to a network that is already running, the
GPU provider runbook and its
overlay example cover
the whole path: sizing a model to one card, running the model server on loopback,
declaring it under inference.backends, pricing tokens against an observed cost
basis, and which single port a buyer is actually meant to reach. A provider is
not a validator and needs no stake, no attestor keystore, and no genesis.
Joining the validator set instead is
the validator-join runbook. Membership is
bought with a bond rather than granted, so the whole procedure is: lower the
admission floor if it is out of reach, fund the candidate's own consensus
account, and let the node bond and ask for itself. It is written around the
parts that are not obvious - that the protocol fee comes out of the amount sent
rather than on top of it, so funding exactly the floor lands under it; that
min_bond decides block validity and so cannot differ across nodes while an
admission is in flight; that a candidate with no bridge configured tallies
attestations and releases nothing, and diverges the first time a burn reaches
quorum; and that an idle chain produces no blocks, so a height that does not move
proves nothing and the acceptance test is stopping a node, not reading a config.
Holding your own key used to cost a wallet prompt per message, twice. A spend budget removes that without anyone taking custody: the owner signs one transfer into an account whose NAME carries the terms - which key may draw, the most one job may cost, the price ceiling, when it dies - and a delegate spends it until it runs out or expires. In a browser the delegate is the non-extractable key the page already generates, so it stops being a second account that needs its own funding. Turning it on is a rule change over money and activates at an agreed height: the budget activation runbook, and the design, the prior art and what it deliberately does not bound are in the proposal.
The buying side is the consumer runbook: getting
MATRIX into an account, and the two doors a buyer can come through. The
OpenAI-compatible /v1/chat/completions is a drop-in for any OpenAI SDK and is
custodial - that protocol carries no buyer field, so the API key is what names
the account to charge and the node must hold its key. A buyer who is not the node
operator wants the other door instead, where a signed RunAuthorization asks for
the work and a signed transfer accepts the bill, and nobody but the buyer ever
holds the key. Both are served on connect.addr.
Matrix OS is MIT licensed.