> For the complete documentation index, see [llms.txt](https://docs.theacompute.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.theacompute.com/architecture.md). # Architecture I'm made of four independent layers. You, as a user or developer, reach me through the client layer. My orchestrator network routes the jobs. My worker nodes run them. My smart contracts on Robinhood Chain enforce the rules, and they always get the final say. *** ## The big picture ``` +---------------------------------------------------------------+ | 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 (theacompute-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: How you reach me **Chat UI** My web chat client lives at `theacompute.com/app`. I built it with Next.js and serve it from the edge. It takes care of your account (email sign-up and sign-in), topping up your units in Settings, picking a model, rendering my streamed replies, and listing your jobs with their receipts. **REST API** At `api.theacompute.com/v1` I expose an HTTP API that's compatible with the OpenAI format. You authenticate with an API key sent as a bearer token. I lock your units in escrow before I start routing (my API and contracts call them "credits"), and I put the Robinhood Chain transaction hash for that escrow lock in the response headers. Keep that hash: it's your receipt. **My SDKs for TypeScript and Python** These are thin wrappers around my REST API. On top of it they give you wallet-native auth, streaming helpers, React hooks, and typed accessors for your on-chain job receipts. *** ## Layer 2: My orchestrator network I orchestrate over a libp2p peer-to-peer mesh, and there's no central server anywhere in it. Anyone can run an orchestrator node for me, and I pay that node a routing fee for every job it routes. **How I find workers** Every worker gossips what it can do into the mesh: GPU model, free VRAM, hosted models, geographic region, stake weight, and how deep its queue is right now. My orchestrators listen to that stream and keep a live picture of my whole network. **How I route your job** When your job comes in, I match it to a worker on four things: 1. Model availability: the worker has to host the model you asked for 2. Stake weight: the bigger the stake, the higher I rank the worker for routing 3. Reputation score: I keep it on-chain and update it after every completed job 4. How much latency I expect between the worker and the client that sent the job **How I stream tokens** Once a worker takes your job, I carry the generated tokens over WebSocket from the worker, through the orchestrator, to your client. The orchestrator passes the stream along as it comes in. It never buffers the full output. **When a worker stalls** If a worker hasn't started streaming before the timeout (8 seconds by default, and you can configure it), I take the job away and hand it to the next available worker, while your escrow stays locked. If 120 seconds go by and no worker has finished, my `job_escrow` contract refunds the escrow by itself. No ticket, and no one to appeal to. *** ## Layer 3: My worker nodes ### Tier 1: workers in a browser tab A browser worker runs inference through WebGPU with the WebLLM runtime, so there's nothing to install. I load quantized GGUF models into browser memory and run jobs on a Web Worker thread, which keeps the page responsive. | Property | Value | | ---------------- | ------------------------------------------------------------------------------ | | Runtime | WebLLM + WebGPU | | Supported models | 1B to 8B quantized (GGUF) | | Minimum VRAM | 3GB GPU memory visible to browser | | Setup | Sign in, open Earn in Chrome 113+, pick Browser worker, and click "Sign me up" | | Payout rate | 75% of job value (no stake) | ### Tier 2: workers running my native node A native worker runs `theacompute-node`, a single Rust binary that handles the GPU backends, model downloads, the job queue, and all of its on-chain work with me. | Property | Value | | ---------------- | ------------------------------------------------------------------------------- | | Runtime | theacompute-node (Rust) | | GPU backends | CUDA (NVIDIA), Metal (Apple Silicon), ROCm (AMD) | | Inference engine | llama.cpp | | Supported models | Every model size (full precision and quantized) | | Setup | Install the binary, stake at least 1,000 $THEA, sign up on Earn, then configure | | Payout rate | 85% of job value (minimum 1,000 $THEA stake required) | *** ## Layer 4: My smart contracts on Robinhood Chain All of my contracts are open-source, and each one is audited before it goes to Mainnet. | Contract | What it does for me | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `job_escrow` | Locks your units when you submit a job. Releases them once completion is verified, or refunds them on timeout. | | `worker_registry` | Keeps track of every worker's stake, registered models, and on-chain reputation. | | `settlement` | Checks the proof of completion and splits the payout between the worker and the treasury. | | `staking` | Handles $THEA staking: the lock periods and the tiers of the earnings multiplier. | | `governance` | Runs on-chain votes on which models I carry, fee parameters, and protocol upgrades. It goes live after the beta. | ### How workers prove they finished When inference is done, the worker posts a small cryptographic proof: * A SHA-256 hash of the full output token stream * A signature over that hash, made with the worker's registered secp256k1 keypair My `settlement` contract checks that the signature comes from the registered address, and then releases the escrow. If the hash you compute locally over the output you received doesn't match the proof, you get a 60-second window to open a dispute. **While I'm in beta:** the TheaCompute Safe multisig rules on disputes. If a proof is confirmed dishonest, I slash 5% of that worker's staked $THEA. **Further down the road:** I'm actively researching ZK proof-of-inference. It would make verification fully trustless and do away with the dispute window completely. *** ## What I'm built with | Layer | Technology | Why I picked it | | ----------------- | ----------------------- | ----------------------------------------------------------------------------------- | | Blockchain | Robinhood Chain Mainnet | \~100ms blocks, sub-cent fees, Ethereum security, and native USDG | | Smart contracts | Solidity + Foundry | A mature EVM toolchain with solid, well-known audit tooling | | Units | USDG (ERC-20) | A stablecoin issued by Paxos that's native to Robinhood Chain | | Governance token | $THEA (ERC-20) | Covers staking, governance, and how value accrues to my protocol | | P2P networking | libp2p | A battle-tested peer mesh that I use for orchestration | | Native inference | llama.cpp | Supports CUDA, Metal, and ROCm and covers a wide range of model formats | | Browser inference | WebLLM + WebGPU | Lets my workers run inside a browser without installing anything | | Indexing | Alchemy | The RPC recommended for Robinhood Chain, with webhooks and full transaction history | | API layer | TypeScript / Node.js | Fast to iterate on, with first-class EVM libraries (viem, ethers.js) | | Dashboard | Next.js | Renders on the server and deploys at the edge | *** ## How I settle a job, start to finish 1. You top up units in Settings: tell me how much USDG to convert (1 USDG = 100 units), send exactly that amount on Robinhood Chain to the escrow address I show you, and tap "I've sent my USDG" so I can confirm the transfer on-chain. I sponsor gas via ERC-4337. My `job_escrow` contract records your units as an on-chain balance. 2. You send an inference request, and my escrow contract locks that job's cost in units atomically. The job ID and the locked amount are on-chain before I route anything. 3. My orchestrator runs the matching criteria above, chooses an available worker, and routes your job to it. 4. The worker decrypts the payload, runs the model, and streams tokens back to you. 5. The worker sends a signed proof of completion to my `settlement` contract. 6. My settlement contract checks the signature and releases the funds in a single atomic step: * **75%** to a browser worker's wallet, or **85%** to a native worker's wallet (native workers always hold a stake) * Whatever's left to the protocol treasury 7. Alchemy indexes the settlement transaction. Within seconds it shows up on my network-wide explorer at `explorer.theacompute.com`, and on your own Jobs page with its receipt and a Blockscout link. Every step, from the escrow lock to the final payout, is a Robinhood Chain transaction. Open Blockscout and watch me settle it. --- # 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.theacompute.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.