The Direct client
The Direct client is built on Bare, a lightweight JavaScript runtime, which is bundled with the client code into a standalone executable. Signed releases establish the executable's authenticity; reproducible builds allow it to be compared with the published source.
For help running the client and using its interface, see Hosting a local gateway.
A shared core
Consumers and providers run the same executable. Its shared core provides identity, signing, and connection management for every service on both sides of the exchange. Service implementations use these capabilities through internal interfaces, so they can exchange work without each handling keys and connection setup themselves.
A persistent identity
Each running instance of the Direct client needs to remain recognizable when it restarts or its network address changes. Its identity comes from a random secret seed generated by the client. At startup, the core derives a cryptographic key pair from that seed, so reusing the seed preserves the instance's identity.
The public key is how other peers identify the instance. The private key stays with the core and lets it prove that identity. Knowing the public key lets another peer verify that proof, but does not let it impersonate the instance.
For a provider, this also links its advertised offerings to its client instance. The core signs the offerings with the private key. A consumer checks those signatures with the provider's public key, then uses that same public key to authenticate the provider when connecting. It can therefore check that the offering and the connection belong to the same identity, even if the provider's address has changed. Provider verification checks how well the provider delivers the advertised work.
Managing provider connections
The core manages provider connections through the Holepunch stack. Services share its pool of open connections, so work for different services offered by the same provider can use the same connection. Completing one request leaves it available for further work.
As provider selection changes, the core updates the pool. Service implementations use the connected providers without handling connection setup and reuse themselves. The connections chapter explains how multiple exchanges share a connection.
What services add
A service implementation handles a particular kind of work on both sides of the connection. It accepts requests from the consumer's application, passes them to the provider's service infrastructure, and returns the results. The core supplies the peer connection that carries the exchange between the two machines.
Announcing provider capabilities
The service implementation defines which capabilities a provider can offer over the network and how to describe them in an announcement. It passes the announcement to the core, which signs it and sends it to Direct-operated peers for inclusion in the provider directory.
On the consumer side, the core retrieves directory entries and verifies the provider signatures. The service implementation decodes the announcements and identifies providers with the capabilities needed for a request.
For blockchain RPC, capabilities can include historical queries and support for particular EIPs. The service implementation defines how providers advertise these capabilities and how their support can be checked.
The consumer's implementation determines what each request needs, using explicit requirements or service-specific heuristics, and selects only compatible providers. A query at an old block needs historical data; a request that identifies a block by hash may require EIP-1898.
Handling requests and responses
A service implementation connects the application's local API to the provider's backend. On the consumer side, it reads an incoming local API request and encodes it for transmission through the core. On the provider side, it decodes that request and passes the work to the configured service infrastructure.
Responses follow the reverse path. The provider's implementation encodes the returned data or error, and the consumer's implementation turns it into the response expected by the application. Responses can arrive all at once or progressively as a stream over the same connection. The service defines how both ends represent requests, results, and errors; the core carries those messages between them.
For example, for AI this means passing the requested model, prompt, and generation parameters to a model server. As the server generates output, the implementation sends it back progressively, allowing the application to receive a streamed response.
Measuring usage
Each service implementation defines how usage is counted and applies the provider's advertised prices to calculate the charge. These measurements supply the amounts used by the payment flow.
For example, blockchain RPC counts billable requests, while AI measures token usage. The unit and counting rules belong to the service; the payment protocol then handles authorization and settlement.
Local protections
With the Direct client running locally on both sides, service implementations can add protections at either end of the exchange. They can protect data before it leaves the consumer's machine and check results before returning them to the application.
For instance, a service can detect a failed request and retry it with another compatible provider when the work can safely be repeated. It can also examine a response before passing it back to the application. A blockchain RPC implementation, for example, can verify available cryptographic proofs or compare responses from several providers and require quorum on the result.
An AI implementation can also protect prompts while they are being processed. The consumer's local client verifies the provider's trusted execution environment (TEE) and its encryption key, then encrypts the prompt with that key. That way, only the local instance and the TEE running the model can read the prompt; neither the provider's host operator nor Direct can access it in plain text.
Each service implementation can add its own set of local protections suited to the work it performs. The blockchain RPC guide describes the protections available for blockchain requests.