Clients, the RPC edge, and protocol integration

Choose the public CLI for wallet and shell tasks, the JavaScript SDK for application code, and direct RPC when you need an exact wire contract. The edge in front of the node handles routing, caching, and overload; it does not execute or finalize transactions.

Protocol integration designs in framework/ are a separate resource. They help structure an evaluation, but they do not add a deployed adapter or a new CLI command.

This page explains responsibility boundaries: client construction, edge transport, node execution and proposed protocol adapters. For hands-on setup, follow Configure the CLI and wallet; for a saved signature, follow Inspect a transaction.

Each client serves a different need

On 2026-09-07, the public npm versions checked were CLI 0.3.0 and SDK 0.2.0; the source manifests identify CLI 0.4.0 and SDK 0.3.0. The installed CLI 0.3.0 did not have the source CLI's raw rpc command. Treat release and source interfaces separately. See the availability reference for the dated evidence and public endpoint condition.

The SDK preserves upstream exports while adding Singularity helpers. This is useful code compatibility, not a claim that every upstream RPC method or Solana runtime behavior is supported. Wallet filesystem helpers are Node-specific; browser applications must supply a suitable signer.

Keep HTTP, WebSocket, and chain identity aligned

connect() defaults to the configured public HTTP endpoint, commitment confirmed, and HTTP 429 backoff. For the built-in endpoint it explicitly uses wss://rpc.entropytoorder.xyz/. When you override HTTP, it lets upstream derive the corresponding WebSocket address unless you explicitly provide one. This avoids quietly reading one network while subscribing to another. Connection construction.

Before a signing workflow, use the SDK's chain-identity check:

import { connect, checkCompat } from '@0xsingularity/web3.js';

const connection = connect();
await checkCompat(connection, { throwOnMismatch: true });

This compares the endpoint's genesis hash with the SDK's expected Singularity genesis hash. Without throwOnMismatch, a mismatch warns and returns ok: false; the application must inspect that result. A match establishes the reported chain identity, not health, durability, or method availability. The snippet is an integration pattern; the run separately performed read-only chain identity checks. Compatibility check.

The CLI guide owns configuration precedence and wallet handling. Keep an endpoint override explicit during diagnostics; a saved configuration or environment variable can otherwise send a command somewhere other than the default you expected.

The edge request path preserves some consistency boundaries

The active Worker implementation sends every valid HTTP JSON-RPC POST cache miss to ORIGIN_WRITE first. Ordinary and cacheable reads may retry once through ORIGIN_LB after a connection failure or selected upstream error status. Writes and sticky reads do not fail over. WebSocket upgrades pass directly to the load-balancer origin as streams. The declared ORIGIN_FALLBACK field is not the active retry target. Worker routing.

Explore request routing. A transaction acknowledgement still needs a later receipt or status check.

Sticky reads include status polling, recent blockhashes, fee estimates, simulation, and EVM call/nonce queries. Keeping them at the primary avoids immediately polling a lagging replica after submission. That routing intention does not guarantee the submitted transaction has already executed.

A JSON-RPC batch inherits the highest-risk method class. One known write makes the batch a write; one known replay-unsafe operation vetoes retry. HTTP subscription methods receive a WebSocket-directed error. The classifier treats other syntactically valid method names as ordinary reads, so maintainers must classify each newly added mutating RPC. Unknown-to-the-classifier is not evidence that a method is side-effect free. Method and batch policy.

Cache and error behavior

Only a single allowlisted immutable read is cache-eligible. The key uses hostname, method, and recursively canonicalized parameters. Batches bypass caching. getBlock requires an explicit numeric height, and an explicit commitment other than finalized prevents caching. The configured production TTL is 60 seconds; the x-eto-no-cache request header bypasses it.

A hit rewrites the JSON-RPC response ID for the current caller. A cached notification receives HTTP 204. Upstream error responses are not intended to populate the result cache. Response headers such as x-eto-cache and x-eto-origin help identify the path taken. These controls optimize access to data; they do not create a new finality rule. Cache handling, parameter policy.

The Worker forwards Authorization to origin RPC. Origin authentication remains authoritative. A JSON-RPC error may arrive with HTTP 200, including an upstream-unreachable error; clients must inspect the JSON envelope as well as transport status. Do not treat an HTTP-success response as transaction success.

The checked-in edge Terraform rate policy is 400 requests per 10 seconds per IP and Cloudflare location. The nginx direct-origin configuration has a 20-request/second bucket and a 2 MiB body cap. Actual enforcement depends on which configuration is deployed. The SDK's default 429 backoff permits five retries, starts at 250 ms, caps individual delays at 10 seconds, and uses jitter. Backoff does not make a non-idempotent operation safe to replay after an ambiguous acceptance. Edge rate rule, origin limits, SDK backoff options.

For a timeout during submission, retain the signed bytes and transaction identity, then check status before creating a replacement. The server and client receipt semantics are detailed in RPC, WebSocket, and SDK contracts.

Configuration ownership is part of deployment

Wrangler deploys the Worker script. Terraform owns production route attachment, conditional on production_flip. The production Wrangler configuration deliberately omits route declarations so a script deployment does not remove routes owned elsewhere.

This split matters during recovery: replacing a script, moving a hostname, changing load-balancer health, and changing node admission are different operations. Inspect the rendered configuration and deployment evidence for the environment rather than assuming a checked-in hostname proves its current routing. Production script configuration, route ownership.

Use the protocol framework as an evaluation guide

The framework describes eight adapter responsibilities: asset, authorization, quote, execution, liquidity, fee, oracle, and observability. Its common-invariant material asks how a protocol preserves conservation, authorization, replay boundaries, and atomic local settlement across environments.

Those are useful questions when evaluating a new integration. For example, importing an AMM requires more than copying its quote formula: identify the custody account, liquidity ownership, fee units, oracle assumptions, and the exact failure boundary of each composed call. The native product chapter documents implemented local mechanisms; cross-VM composition explains their execution boundary.

The present framework is a v0.1 research specification. Its README describes a broader file layout and proposed singularity protocol analyze|plan|scaffold|validate|partner-package workflow, but the inspected directory contains specification READMEs rather than that implementation. The maintained CLI does not expose those commands. Sushi is proposed adapter material; the Curve and dYdX references are bounded design exercises, not deployed integrations or measured partner outcomes. Framework status, adapter design, actual CLI commands.

The useful output of an evaluation is a concrete gap list: existing callable primitive, required adapter work, trust/custody assumptions, executable acceptance tests, and a named deployment route. HILSA and Bombil should appear where their actual interfaces support that design, without treating an architectural fit as completed integration.

Validation scope

The Worker tests exercise classification, cache eligibility, parameter canonicalization, and retry policy. Client tests exercise endpoint selection, wallet handling, and RPC envelopes. They do not establish live origin failover or a healthy public chain.

This run executed published CLI help/error/wallet checks and an offline SDK signed-transaction round trip, and queried public RPC read-only. It did not deploy an edge, run funded transactions, or exercise a live failover. Those exact results belong to the CLI guide, quickstart, and availability reference.