Read tiers

This reference lists the sources used by SDK reads, watches, and status accessors. Use it to budget startup dependencies and requests, and to decide whether a value is fresh enough for your application. Architecture explains transport ownership.

The tiers

indexerUrl is optional: a caller that only uses chain reads (smart accounts included) constructs without one, and the main-indexer methods below then throw NotConfiguredError. Configuring it does not mean that every method requests the main indexer. The chain socket opens lazily on chain I/O. Price-feed transport and failures are separate from the market store.

A result can combine tiers with different timestamps. The SDK does not generally compare indexed state with the current chain head to certify freshness. Check the method-specific inputs below before treating a derived value as current.

Return contract

• An indexer point read resolves to null when the row does not exist and throws IndexerError when the request fails.
• An indexer list read resolves to [] when there are no rows and throws IndexerError when the request fails.
• A chain read throws on failure. It never returns null in place of a failure.
• A live-store read returns empty data for a market with no active watch. getWatchStatus(pool) is "unwatched" in that state.
• A chain-seeded watch loads no fill history, so getLiveFills can be empty while the book is complete. getLiveStatus().fillsLoaded separates the two states: false means the history was never loaded, true means there are genuinely no fills in the loaded range. A failed fill read sets failure.operation to "fill-history" and does not empty the book.
• Orders a chain seed writes carry an empty createdAt and txHash: placement history is indexer-only and the seed does not invent it. userOrders sorts on createdAt, so seeded orders sort LAST behind any order carrying a real placement timestamp. A chain-seeded pool is not re-snapshotted while the watch lives, so they stay undated for the store's lifetime; read placement history from the indexer.
• The market row a chain seed writes carries only what the module answers. Indexer-only fields — question, asset, oracleQuestion, strike/mode, tradingStart, intervalSec/interval, createdAtTimestamp/createdAtBlock, createdByTx, the volume counters, and the origin attribution — are empty, null or zero and STAY that way: a seeded pool is not re-hydrated by a later watch, and the row outlives stop(), so the seeded row persists for the store's lifetime. Read the indexer directly (getBinaryMarket) when those fields are needed. strike/mode are null rather than "0"/"reference", because a strike of 0 is the protocol's sentinel for an up/down market and would mislabel a fixed-strike one.
• A chain seed never blanks a row the indexer already supplied. The row outlives stop(), so a pool watched from the indexer first and chain-seeded later keeps each indexer-only field listed above, while every field the module answers — status, backing, nonce, finalized, voided, winningOutcome, collateral, the decimals and the token ids — takes the fresher chain value.
• getLiveStatus() reports seedSource ("indexer", "chain", or null before the first watch), seedBlock, and seedTruncated. The indexer snapshot applies a PER-SCOPE order budget that is SHARED across the scope's pools, not a per-pool floor, and it drops the oldest resting orders first. A chain seed has no such cap; seedTruncated is true only when the drain reaches its own page budget.
• A live price read keeps answering with its last values after the server rejects the asset's subscription. getPriceStatus(asset) is "error" in that state, and the rejection is also emitted as a warn event on the debug channel.

Exchange API (SomniaMarkets)

A watch* call resolves with the current value on its first call and on every later call resolves when the channel's value changes.

Engine (SomniaMarketsClient)

The tables in this section are the canonical Engine inventory. Names refer to exchange.client, not similarly named Exchange methods. The inventory guard checks membership only; source and freshness claims require source review. Configuration, cleanup, escape hatches, and capability factories are outside this read inventory.

Live store

Chain

Indexer

Price-feed HTTP reads

Mixed and derived reads

| Independent RPC head, then main-indexer metadata plus processed-block time. Raw measurements, no SDK stale threshold. | getIndexerFreshness | | One independent head for response-associated reads, using the same owner. | createObservedReads | | Per-asset price watch lifecycle, without I/O. | getPriceHealth, listPriceHealth |

Watch startup and updates

Engine watches return a handle with stop(). Repeated handles for the same scope share its work. The scope normally remains for about 30 seconds after the last handle stops, so a quick remount can reuse it. After teardown, a new watch hydrates again.

Market watches hydrate a main-indexer snapshot before chain backfill and live updates. watchUser hydrates the account's indexed order/fill history. It opens no subscription of its own. Subsequent account updates come only from market scopes watched by this client; it is not an account-wide chain subscription.

Price watches hydrate metadata and recent prices from the separate price-feed HTTP service. Each asset key owns a Hasura socket for its price and tick subscriptions. A resolved watch means its snapshot landed, not that the socket has connected. Check getPriceStatus for state. Rejected subscriptions report error, while synchronous price reads retain stale values. These failures do not change market-watch status.

React hooks

useIndexerQuery runs the supplied callback on mount, owner or dependency changes, and explicit refetch. It does not poll or automatically refresh on live events. The callback determines its source and freshness. The hook passes an abort signal and fences superseded responses; cancellation reaches the request only if the callback forwards that signal to an operation that supports it.

Automatic hooks preserve background acquisition semantics: failures use the configured debug/console warning channel and do not throw during render. This includes useFundingRateSeries; its state.error still contains history query failures. Opt into useWatchMarketResult, useWatchUserResult, or useWatchPriceResult for a typed acquisition error, which a component may explicitly throw into an ErrorBoundary. Missing-provider validation still throws InvalidInputError.

Response-associated indexer observations

client.createObservedReads() observes one independent RPC head. Its read and batch methods accept the operations in ObservedReadOperation. The roster includes every ordinary main-indexer domain read, including mixed-tier derived reads. getSyncStatus, waitForIndexedBlock and getIndexerFreshness are source diagnostics, not row reads. Live-store reads, chain-only reads, write capabilities and the separate price service are excluded.

The envelope keeps the domain value in data. observation.latestProcessedBlock is the minimum metadata watermark across successful contributing responses. Missing metadata in any response leaves it null. startedAt, completedAt and responseCount describe the observation span. The metadata is selected beside the rows in the same GraphQL request, without a separate metadata request. A rejected privileged aggregate attempt does not contribute; its successful fallback does. Observed portfolio reads refresh their scope inside the logical read so a cached pool set cannot hide an older contributing response.

These are indexing watermarks. They do not claim each entity changed at that block, that the RPC itself is current, or that separate requests share an atomic historical snapshot. Keep an envelope with its value; later reads cannot update its observation. Create a new observed capability to refresh the shared head. Closing the owner cancels pending observations; a stopped capability cannot reopen transports.

fetchStatus() remains a local-only three-field chain-tail snapshot. Opt into fetchDataStatus() to read RPC and the main indexer once. Its top-level status retains chain-tail meaning; indexer contains independent measurements and prices lists precise per-asset health. API-only monitors keep using client.getSyncStatus(chainId) with no RPC dependency. client.waitForIndexedBlock(chainId, block) polls the same metadata until the indexer has processed a block, so a caller can read its own write instead of guessing a delay.

The concrete exchange.client exposes the additive SomniaMarketsClientWithObservations contract. SomniaMarketsClient includes waitForIndexedBlock, and order-list selections include userData. Custom SomniaMarketsClient implementations must provide the wait, and a serving indexer must expose Order.userData. Other ordinary reads retain their document selections and role permissions. Only observed reads select the response watermark. stopLive() invalidates observed capabilities and cancels pending indexed-block waits without aborting ordinary pending indexer reads; a later wait relinks to the replacement owner signal. Caller cancellation still reaches those reads.

Consumer example

Use the configured exchange in dreamDEX or another consumer. The downstream dreamDEX hook edit remains outside this repository.

const observed = await exchange.client.createObservedReads();
const [markets, count] = await observed.batch([
  { operation: "listMarkets", args: [{ limit: 20 }] },
  { operation: "countMarkets", args: [] },
]);
console.log(markets.data, markets.observation.latestProcessedBlock);
console.log(count.data, count.observation.independentHead.blockNumber);
const freshness = await exchange.client.getIndexerFreshness(exchange.client.config.chain.id);
console.log(freshness?.lagBlocks, freshness?.lagSeconds);

For a local end-to-end observation, start ./demo-clob.sh up, construct the exchange with the local chain and deployment configuration used by the explorer, and run this example against http://127.0.0.1:8085/v1/graphql and ws://127.0.0.1:8545. Use chain id 31337. No production configuration or transaction is required.