> For the complete documentation index, see [llms.txt](https://docs.robinmesh.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robinmesh.com/architecture.md). # Architecture Three independent layers make up RobinMesh. Enforcement lives in the smart contracts on Robinhood Chain, which are the final authority. Routing is handled by the orchestrator network. Users and developers touch the system through the client layer. *** ## System overview ``` +---------------------------------------------------------------+ | User / Developer | | (Chat UI / API Client / SDK) | +-----------------------------+---------------------------------+ | | 1. Submit job + lock escrow on-chain | v +---------------------------------------------------------------+ | Orchestrator Network | | (libp2p peer mesh, decentralized) | | | | Worker discovery via gossip protocol | | Job matching: model availability, stake weight, | | latency, reputation score | | Token streaming: worker -> orchestrator -> client | +-----------------------------+---------------------------------+ | | 2. Route job to best available worker | v +---------------------------------------------------------------+ | Worker Node | | Browser (WebGPU via WebLLM) or Native (robinmesh-node) | | | | Decrypt payload with ephemeral session key | | Run inference locally | | Stream tokens back through orchestrator | | Sign and submit proof of completion | +-----------------------------+---------------------------------+ | | 3. Submit proof on-chain | v +---------------------------------------------------------------+ | Robinhood Chain Smart Contracts | | | | Verify proof signature | | Release escrow: 75-85% to worker, 15-25% to treasury | | Emit indexed event for Explorer | +---------------------------------------------------------------+ ``` *** ## Layer 1: Client interfaces **Chat UI** A web chat client at `robinmesh.com/app`, built with Next.js and served from the edge. It covers wallet connection, credit top-ups, model selection, and rendering of streamed responses. **REST API** `api.robinmesh.com/v1` exposes an HTTP API compatible with the OpenAI format, authenticated with an API key as a bearer token. Credits for a request are locked in escrow before routing starts, and the response headers carry the Robinhood Chain transaction hash for that escrow lock. **TypeScript and Python SDKs** Light layers over the REST API. They contribute wallet-native authentication, helpers for streaming, React hooks, and typed accessors for on-chain job receipts. *** ## Layer 2: Orchestrator network Orchestration runs on a libp2p peer-to-peer mesh with no central server anywhere in it. Running an orchestrator node is open to anyone, and each routed job pays the node a routing fee. **Worker discovery** Every worker gossips its capabilities into the mesh: GPU model, free VRAM, which models it hosts, geographic region, stake weight, and how deep its queue currently is. From that stream, orchestrators keep a live picture of the whole network. **Job routing** An incoming job is matched to a worker on four criteria: 1. Model availability: the worker has to be hosting the model the job asks for 2. Stake weight: a larger stake means higher routing priority 3. Reputation score: kept on-chain and updated after every completed job 4. Estimated latency to the client that submitted the job **Token streaming** After a worker takes a job, generated tokens travel over WebSocket from the worker, through the orchestrator, to the client. The orchestrator passes the stream along as it arrives; it never buffers the complete output. **Fault handling** A worker that has not started streaming within the timeout (8 seconds by default, configurable) loses the job, which moves to the next available worker while the escrow stays locked. Should 120 seconds pass with no worker finishing the job, the `job_escrow` contract refunds the escrow on its own. *** ## Layer 3: Worker nodes ### Browser workers (Tier 1) A browser worker does inference through WebGPU using the WebLLM runtime, with nothing to install. Quantized GGUF models are loaded into browser memory, and jobs execute on a Web Worker thread so the page stays responsive. | Property | Value | | ---------------- | --------------------------------- | | Runtime | WebLLM + WebGPU | | Supported models | 1B to 8B quantized (GGUF) | | Minimum VRAM | 3GB GPU memory visible to browser | | Setup | Open the Earn tab in Chrome 113+ | | Payout rate | 75% of job value (unstaked) | ### Native workers (Tier 2) A native worker runs `robinmesh-node`, one Rust binary that takes care of GPU backends, model downloads, the job queue, and all on-chain interactions. | Property | Value | | ---------------- | ------------------------------------------------ | | Runtime | robinmesh-node (Rust) | | GPU backends | CUDA (NVIDIA), Metal (Apple Silicon), ROCm (AMD) | | Inference engine | llama.cpp | | Supported models | 8B to 70B+ (full precision and quantized) | | Setup | Install binary, connect wallet, stake, configure | | Payout rate | 75% unstaked, 85% with minimum stake | *** ## Layer 4: Robinhood Chain smart contracts Every contract is open-source and goes through an audit before it reaches Mainnet. | Contract | Responsibility | | ----------------- | -------------------------------------------------------------------------------------------------- | | `job_escrow` | Locks credits at job submission. Releases them on verified completion, or refunds them on timeout. | | `worker_registry` | Holds each worker's stake, registered models, and on-chain reputation. | | `settlement` | Checks the proof of completion and splits the payout between worker and treasury. | | `staking` | Runs $RMESH staking: lock periods and the tiers of the earnings multiplier. | | `governance` | On-chain votes on model curation, fee parameters, and protocol upgrades. Goes live after the beta. | ### Proof of completion When inference finishes, the worker posts a small cryptographic proof consisting of: * The SHA-256 hash of the complete output token stream * A signature over that hash from the worker's registered secp256k1 keypair The `settlement` contract confirms the signature belongs to the registered address and then releases the escrow. A client whose local hash of the received output disagrees with the submitted proof has a 60-second window to open a dispute. **During the beta:** disputes are arbitrated by the RobinMesh Safe multisig. When a dishonest proof is confirmed, 5% of the worker's staked $RMESH is slashed. **Looking further out:** ZK proof-of-inference is under active research. With it, verification becomes fully trustless and the dispute window disappears. *** ## Technology stack | Layer | Technology | Reason | | ----------------- | ----------------------- | ----------------------------------------------------------------------------------- | | Blockchain | Robinhood Chain Mainnet | \~100ms blocks, sub-cent fees, Ethereum security, native USDG | | Smart contracts | Solidity + Foundry | Mature EVM toolchain with well-established audit tooling | | Credits | USDG (ERC-20) | A Paxos-issued stablecoin native to Robinhood Chain | | Governance token | $RMESH (ERC-20) | Staking, governance, and protocol value accrual | | P2P networking | libp2p | A proven peer mesh, used here for orchestration | | Native inference | llama.cpp | CUDA, Metal, and ROCm support plus wide model format coverage | | Browser inference | WebLLM + WebGPU | Lets workers run in a browser with zero installation | | Indexing | Alchemy | The recommended RPC for Robinhood Chain, with webhooks and full transaction history | | API layer | TypeScript / Node.js | Quick to iterate on, with first-class EVM libraries (viem, ethers.js) | | Dashboard | Next.js | Server-side rendering, deployable at the edge | *** ## The settlement flow, end to end 1. The user tops up credits by sending USDG to the `job_escrow` contract, whether by wallet transfer, payment link, or on-ramp (gas sponsored via ERC-4337). The contract records the credits as an on-chain balance keyed to the user's wallet address. 2. The user submits an inference request, and the escrow contract atomically locks that job's credit cost. Job ID and locked amount hit the chain before any routing takes place. 3. Using the matching criteria described above, the orchestrator picks an available worker and routes the job there. 4. The worker decrypts the payload, runs the model, and streams tokens back to the client. 5. The worker sends a signed proof-of-completion to the `settlement` contract. 6. After verifying the signature, the settlement contract releases the funds in one atomic step: * **75%** to the worker's wallet (or **85%** when the worker holds an active stake) * The rest to the protocol treasury 7. Alchemy indexes the settlement transaction, which shows up in the RobinMesh Explorer within seconds. From the moment the escrow locks until settlement completes, every step is a Robinhood Chain transaction anyone can inspect on Blockscout. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.robinmesh.com/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.