> For the complete documentation index, see [llms.txt](https://docs.robincompute.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robincompute.org/architecture.md). # Architecture RobinCompute is three independent layers. The smart contracts on Robinhood Chain enforce the rules; they are the final authority. The orchestrator network routes jobs. 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 (robincompute-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 `robincompute.org/app`, built with Next.js and served from the edge. It handles wallet connection, credit top-ups, model selection, and rendering of streamed responses. **REST API** `api.robincompute.org/v1` exposes an HTTP API compatible with the OpenAI format, authenticated with an API key as a bearer token. Credits lock in escrow before routing starts, and the response headers carry the Robinhood Chain transaction hash for that escrow lock. That hash is your receipt. **TypeScript and Python SDKs** Thin layers over the REST API. They add wallet-native authentication, streaming helpers, React hooks, and typed accessors for on-chain job receipts. *** ## Layer 2: Orchestrator network Orchestration runs on a libp2p peer-to-peer mesh. There is no central server anywhere in it. Anyone can run an orchestrator node, and each routed job pays the node a routing fee. **Worker discovery** Each worker gossips its capabilities into the mesh: GPU model, free VRAM, hosted models, geographic region, stake weight, and current queue depth. From that stream, orchestrators hold 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 must host the model the job asks for 2. Stake weight: a larger stake means higher routing priority 3. Reputation score: stored on-chain and updated after every completed job 4. Estimated latency to the client that submitted the job **Token streaming** Once a worker takes a job, generated tokens travel over WebSocket from the worker, through the orchestrator, to the client. The orchestrator forwards the stream 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. The job moves to the next available worker while the escrow stays locked. If 120 seconds pass with no worker finishing, the `job_escrow` contract refunds the escrow on its own: no ticket, no appeal to anyone. *** ## Layer 3: Worker nodes ### Browser workers (Tier 1) A browser worker runs inference through WebGPU using the WebLLM runtime. Nothing to install. Quantized GGUF models load 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 `robincompute-node`: one Rust binary that handles GPU backends, model downloads, the job queue, and every on-chain interaction. | Property | Value | | ---------------- | ------------------------------------------------ | | Runtime | robincompute-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 audited 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` | Verifies the proof of completion and splits the payout between worker and treasury. | | `staking` | Runs $RCOMPUTE 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: * 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, then releases the escrow. If your local hash of the received output disagrees with the submitted proof, you have a 60-second window to open a dispute. **During the beta:** the RobinCompute Safe multisig arbitrates disputes. A confirmed dishonest proof costs the worker 5% of their staked $RCOMPUTE. **Looking further out:** ZK proof-of-inference is under active research. It makes verification fully trustless and removes the dispute window entirely. *** ## 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 | $RCOMPUTE (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. The orchestrator applies the matching criteria above, 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. The settlement contract verifies the signature and 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 RobinCompute Explorer within seconds. From escrow lock to final payout, every step is a Robinhood Chain transaction. Open Blockscout and watch it settle. --- # 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.robincompute.org/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.