# Architecture

#### Protocol Roles

OpenShard defines three distinct network roles, each implemented as a fully independent package with no hard coupling to the others.

The Buyer is the client-side gateway. It receives inference requests from downstream applications, queries the registry for available sellers, selects a peer based on availability and pricing, constructs the privacy payload, manages payment channel state on Base, and forwards the encrypted request to the chosen seller. The buyer never exposes the raw Ethereum account address (EOA) of the requesting party in inference payloads. Instead, it substitutes a cryptographic commitment as the externally shared identity anchor, so sellers learn nothing about buyer identity from the request contents alone.

The Seller is the inference service operated by a compute provider. It accepts incoming buyer requests, verifies the zero-knowledge proof artifacts attached to the payload, decrypts the encrypted query using ECDH-derived session keys, validates micropayment authorization signed against Base, and then proxies the actual inference task to a configured upstream AI provider. Each seller controls its own upstream model configuration, pricing, and capability declarations. Sellers are fully autonomous — they do not share runtime state with one another and each enforces its own verification logic independently.

The Registry is the control plane for service discovery. It maintains a liveness index of active peers, accepts heartbeat pings from sellers, prunes stale nodes when heartbeats lapse, and serves filtered and ranked peer listings to buyers making routing decisions. The registry sits entirely outside the inference data path — it is consulted before a request is dispatched, never during. This means the registry cannot observe inference content, even in a compromised state.

#### Service Discovery

Rather than hard-coding provider endpoints, OpenShard buyers query the registry dynamically at routing time. Sellers register on startup, send periodic heartbeats to maintain their liveness status, and are removed from the active index if their heartbeat window expires. Buyers query this index against the requested service ID, health signals, and pricing constraints, and receive a ranked candidate list in return.

Buyers can also honor an explicit peer-pin header included in the incoming request, which bypasses automatic selection and routes to a named seller peer ID. This is useful for debugging specific seller behavior, latency-sensitive routing where a buyer has prior knowledge of a fast peer, or operator-controlled topology where routing policy is managed externally.

#### Offerings and Pricing

Each seller advertises one or more Offerings — structured service definitions that describe what the seller provides. An Offering declares the capability type (inference, agent, or tool), the service IDs that buyers can request, per-token pricing expressed in USD-per-million units with separate rates for input tokens, output tokens, and cached tokens, and the upstream model name that the seller proxies to. Offerings are validated through a fluent builder interface and serialized as JSON for registry advertisement and peer discovery queries. Buyers use pricing data from discovered offerings to make cost-aware routing decisions before committing to a seller.

#### Package Responsibilities

The monorepo organizes protocol responsibilities across ten packages. The buyer package handles local gateway behavior including routing logic, payment retry orchestration, and privacy payload construction. The seller package handles the inference service including ZK proof verification, ECDH decryption, payment validation, metrics tracking, and upstream proxying. The registry package maintains the peer liveness directory and serves discovery queries. The shared package provides common primitives including EIP-712 payment type definitions, USDC unit conversion helpers, signature utilities, and audit logging. The credentials package implements ZK proof generation and verification. The crypto package provides AES and ECDH helper logic for encrypted request transport. The contracts package contains Solidity contracts deployed on Base for token lock mechanics and settlement. The sdk package exposes programmatic runtime APIs for Network, SellerNode, and Offering. The cli package provides an operator-facing command interface. The dashboard package contains the frontend and API layer for management tooling.

<br>


---

# Agent Instructions: 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:

```
GET https://docs.openshard.ai/getting-started/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.