# Core Architecture

The OpenSeed network is composed of three types of participant nodes, each with a distinct role in the ecosystem, interacting through well-defined protocols to enable decentralized AI inference transactions. Understanding the architecture begins with understanding each participant type in depth, and then understanding how they interact in the lifecycle of a real transaction.

### The Registry: The Network's Memory

The Registry is the first layer of the OpenSeed architecture and the entry point for any new participant joining the network. It is the network's shared memory — a continuously-updated, authoritative source of truth about who is on the network, what they offer, and how to reach them.

Conceptually, the Registry functions like a combination of a DNS server and a stock exchange order book. Like DNS, it translates abstract capability queries — "I need a provider serving Llama 3 70B at under $0.30 per million tokens" — into concrete network addresses that a Buyer can connect to. Like an order book, it maintains a live listing of available capacity with pricing, allowing Buyers to compare offerings and select the best match for their requirements.

The Registry's data model is built around Seller node records. Each record contains the Seller's unique node ID, their current public endpoint URL (which may be a P2P tunnel address that changes over time), the list of AI models they offer with their pricing, their current reputation score (updated from historical performance data), and a timestamp of their last heartbeat.

The heartbeat system is the mechanism that keeps the Registry's data fresh and accurate. Every active Seller node sends a heartbeat message to the Registry at regular intervals — typically every thirty to sixty seconds. The heartbeat serves two purposes. First, it is a liveness signal that tells the Registry the node is still online and available. If a node misses a configurable number of consecutive heartbeats — typically three to five — the Registry marks it as inactive and removes it from the active peer list served to Buyers. This prevents Buyers from being routed to offline nodes and experiencing connection failures.

Second, the heartbeat is an update mechanism. Each heartbeat message contains the Seller's current endpoint URL. For nodes using P2P tunneling, this URL may change every time the node restarts, as tunneling services like localtunnel and ngrok often assign new URLs on reconnection. By including the current URL in every heartbeat, the Registry always has a fresh, valid route to every node regardless of how frequently their URLs change.

The Registry itself is designed to be lightweight and non-authoritative. It does not control who can join the network, cannot reject valid Seller registrations, and does not participate in the payment flow. It is a coordination layer, not a control layer. In Phase 3, the Registry protocol will be federated — allowing multiple independent Registry operators to run interoperable instances, eliminating even the Registry as a potential single point of failure.

### Seller Nodes: The Supply Side

Seller nodes are the supply side of the OpenSeed marketplace. They are participants who offer AI inference capacity to the network in exchange for USDC payment. A Seller can be any of several types of operator, running any type of AI inference infrastructure.

The most common Seller type is a local model operator — someone running an open-weight model on their own hardware using a local inference server such as Ollama. Ollama wraps any supported open-weight model (Llama, Mistral, Qwen, Phi, Gemma, and dozens of others) with an OpenAI-compatible HTTP API, which the OpenSeed Seller SDK then wraps with x402 payment middleware. The result is a node that accepts payment authorizations before serving each inference request.

A second common Seller type is an API reseller — an operator who holds upstream API keys for commercial model providers (OpenAI, Anthropic, Google, Mistral) and re-exposes those endpoints through the OpenSeed network, typically at a markup above the upstream cost. This allows Sellers to offer access to frontier models without running the inference themselves, while earning the spread between their upstream cost and their OpenSeed price.

A third emerging Seller type is a managed inference operator — a business that runs dedicated GPU infrastructure specifically for the purpose of serving the OpenSeed network as a professional provider. These operators benefit from economies of scale that individual home-lab operators cannot achieve, but they compete on the same terms as everyone else — reputation and price — without any privileged access to routing.

What all Seller types share is the x402 payment middleware that the OpenSeed SDK provides. Regardless of what is running underneath — a local Ollama instance, an upstream API key, or a purpose-built inference cluster — the x402 middleware wraps the inference endpoint with the payment handshake logic, handles SpendingAuth validation, records validated authorizations, and provides the settlement interface. The Seller operator does not need to implement payment logic themselves — the SDK provides it as a turnkey layer.

Sellers set their own prices, denominated in USDC per million tokens, separately for input tokens and output tokens. Price setting is entirely at the Seller's discretion. The market determines whether their pricing attracts traffic — overpriced nodes receive few routing assignments, while competitively priced nodes with good reputation scores receive the most traffic. This natural market pressure toward efficient pricing does not require any centralized price regulation.

### Buyer Nodes: The Demand Side

Buyer nodes are the demand side of the OpenSeed marketplace. They are participants who consume AI inference, paying Sellers for each request they serve. A Buyer can be an individual developer testing a tool, a production AI agent executing autonomous tasks, or any application that needs programmatic access to AI inference.

The core component of a Buyer node is the Buyer proxy — a local HTTP server that sits between the Buyer's application and the OpenSeed network. The proxy presents a standard OpenAI-compatible API to the local application, handles all OpenSeed-specific logic invisibly, and returns standard OpenAI-compatible responses. The local application has no awareness that it is communicating with a decentralized network rather than a standard API endpoint.

Inside the proxy, the Peer Router is the decision-making component. When a request arrives from the local application, the Peer Router queries the Registry for current provider data, applies the composite reputation and price scoring algorithm to rank available peers, and selects the best match for this specific request. The Router maintains session-level performance data that supplements the historical Registry data — if a Seller performs poorly during the current session, the Router adjusts its routing weight accordingly without waiting for the Registry's reputation data to update.

The Internal EVM Signer is the payment component of the Buyer node. It is an Externally Owned Account (EOA) on Base Mainnet whose private key is stored locally and used exclusively for signing payment authorizations. The Signer generates SpendingAuth signatures — the off-chain payment authorizations that accompany each inference request — and manages the state of open payment channels, tracking which Sellers have active ReserveAuths and how much budget remains in each channel.

The Buyer proxy also maintains a local ledger of all payment activity — every SpendingAuth generated, every Seller paid, every token consumed and at what price. This data is available through the Dashboard and CLI for cost tracking, budget management, and usage analysis.

### The Complete Transaction Lifecycle

To make the architecture concrete and coherent, it is worth tracing the complete lifecycle of a single inference transaction from the moment a developer's tool sends a request to the moment it receives a response.

The developer has configured their AI tool to point at their local OpenSeed Buyer proxy, running on port 8377. The tool sends a standard OpenAI-compatible POST request to the /v1/chat/completions endpoint on the proxy.

The Buyer proxy receives the request. It checks its local channel state to see whether it has an active, funded payment channel with a suitable Seller. If this is the first request of the session, no channels are open yet.

The Peer Router queries the Registry for the current active peer list, filtered by the requested model and the Buyer's configured price cap. The Registry returns a list of active Seller nodes sorted by composite reputation and price score.

The Router selects the top-ranked Seller. If no ReserveAuth exists for this Seller, the Buyer initiates one — submitting a transaction to the OpenSeed smart contract on Base Mainnet that locks a specified amount of USDC for this Seller relationship. This transaction must confirm before the first request can proceed. After the initial session setup, this cost is amortized across all subsequent requests.

With the channel open, the Buyer forwards the inference request to the Seller's endpoint URL. The Seller receives the request, notes that no valid SpendingAuth is attached, and responds with HTTP 402 Payment Required. The response body contains an invoice: the channelId, the required USDC amount based on estimated token counts for this request, and a metadataHash that cryptographically ties the invoice to this specific request.

The Buyer proxy's Internal EVM Signer generates an EIP-712 SpendingAuth — an off-chain typed data signature authorizing the Seller to claim the specified amount from the Buyer's channel deposit. The Signer records this authorization in the local ledger.

The Buyer retries the request with the SpendingAuth embedded in the request headers. The Seller validates the signature — confirming it was signed by the Buyer's registered EOA address, that the channelId is valid, that the authorized amount is sufficient, and that the nonce is fresh (not previously used). Validation is instantaneous and requires no blockchain interaction.

Upon successful validation, the Seller processes the inference request through its underlying model and streams the response back to the Buyer proxy. The Seller records the validated SpendingAuth in its local accumulator.

The Buyer proxy receives the streaming response, strips any payment-related metadata, and forwards a clean standard OpenAI-compatible response back to the original application. From the application's perspective, nothing unusual has occurred — it sent a request and received a response, exactly as it would from any standard API endpoint.

This entire sequence — excluding the one-time ReserveAuth transaction that only happens at channel open — adds single-digit milliseconds of overhead to the inference request. The payment handshake is essentially invisible in the context of the typical hundreds of milliseconds that model inference itself requires.

<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.openseed.gg/core-concepts/core-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.