Read tiers

This page describes the three freshness tiers a read can come from, and which methods belong to each. A tier decides how fresh a value is, what it costs, and what it needs to work. The design reasons are in Architecture.

The tiers

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.

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)

Live store

getLiveMarkets, getLiveMarketByPool, getLiveMarketByAddress, getLiveFills, getLiveUserFills, getLiveUserOrders, getLiveFundingUpdates, getLiveBinaryOrderBook, getLiveBinaryOrderBookByMarket, getLiveSpotOrderBook, getLiveStatus, getWatchStatus, isTailing, subscribeLive.

Price feed: getLivePrice, getLivePrices, getLivePriceTicks, getLivePriceFeedInfo, getPriceStatus, subscribePrices.

Watches: watchMarket(pool), watchMarkets({ discover }), watchUser(user), watchPrice(asset), watchPrices(assets). Each returns a handle with stop(). Handles on one scope share a subscription. The scope is torn down about 30 seconds after the last handle stops.

Chain

Books and orders: getBinaryOrderBook, getSpotOrderBook, getOrderOnchain, getOwnOpenOrdersOnchain, getAllOpenOrdersOnchain.

Markets and system: getMarketOnchain, getContractMeta, getHeadBlock, getSystemInfo, getTransactionSummary, getPoolCreator, getFreePools, getOnchainResolutionPrice, getMaxVenueFeeBps, encodeBinaryVenueFeeParams.

Balances and allowances: getErc20Balance, getErc20Metadata, getErc20Allowance, getBalances, getNativeBalance, getOutcomeBalance, getVaultBalance, getOwnLockedBalance, getLockedTokenBreakdown.

Operators and builders: getOperatorPermissionsRegistry, isOperatorAuthorized, isGloballyApproved, isApprovedForPool, getMaxBuilderFeeBpsTimes1k, getBuilderApproval, getEffectiveBuilderApproval, getStopOrderSomiPayment, getPerpStopOrderSomiPayment, getPerpStopOrder, getUnclaimedPerpStopSomi, getManualVaultMode, getAutoPullRequirement, convertToQuoteAtPriceCeil.

Perps: getPerpState, getPerpPosition, getMarginAccount, getAccountHealth, getLiquidationPrice, previewPerpLiquidationPrice, getPerpLeverage, getPerpPositionAnalytics, listPerpPositionAnalytics, getMaxPerpOrderSize, previewPerpOrderMargin, previewPerpClosePnl, getPerpSideHolders, getBankruptcyPrice, getPerpSystemConfig, getInsuranceFundState, getLiquidationEngineConfig, tryGetPerpAccountEquity, getPerpCollateralBasis, listPerpPoolStatuses, listTradeablePerpPools, isPerpPoolRegistered, getPerpRiskParams, getPerpHealthSnapshot, getEffectiveImfBps, getPerpMaxLeverage, getPerpLeverageImSurcharge, tryGetPerpLeverageImSurcharge, readPerpMarketFromChain, quotePerpFundingPayer, getPerpMainFunding, getPerpLinkedWalletRegistry, getPerpWalletPullCapacity, getPerpWalletLinkage, listPerpLinkedChildren, getPerpMaxLinkedChildren.

Oracle hub: getSchedulingCost, earmarkedOf, creditOf, outstandingOf, withdrawableOf, payerCreditOf, payerOf, resolveReserve, quoteCreateMarketValue.

SomniaLend: client.lend.listReserves, client.lend.getAccount.

Indexer

Markets: listMarkets, listRegistryMarkets, countMarkets, countMarketsBounded, getMarket, getMarketByPool, listMarketsByPool, listBinaryMarkets, listLiveBinaryMarkets, listPastBinaryMarkets, getBinaryMarket, getBinaryMarketByAddress, listBinaryVenueIds, listBinaryAssets, countBinaryMarkets, countBinaryMarketsBounded, listSpotMarkets, getSpotMarket, listPerpMarkets, getPerpMarket, getMarketFees, getMarketStatusHistory.

History: getCandles, getFills, getFill, getUserFills, countUserFills, getOrderFills, getOrder, getOrders, getOpenOrders, countOrders, listSweepableOrders, getMarketActivity, getTransactionActivity, getTradeContext, getRouterActions.

Portfolios: getPortfolio, getSpotPortfolio, getPerpPortfolio, getOutcomeBalances, getSpotStopOrders, listPerpStopOrders, listPerpOrderHistory, listPerpPositions.

Resolution: getMarketResolution, getOpeningPrices, getResolutionPrices, getBookTops.

Fees and perps history: listProtocolFees, listBuilderFees, listSettlementFees, listBuilderApprovals, getVaultPayoutFallbacks, getFundingPayments, getMarginEvents, getLiquidations, listFundingRateHistory, listFundingRateCandles, listPerpFees, getOpenInterestHistory.

Control plane: listOperators, getOperator, countOperators, listVenues, getVenue, countVenues, listMarketCreators, getMarketCreator, listOracleAdapters, getOracleAdapter, listSeries, getSeries, getOracleQuestion, listOracleQuestions, getOperatorHubAccount, listOperatorHubAccounts, listOracleBinds, listOracleCallbacks, getSyncStatus, getPool, getPoolBindings.

Derived reads

quoteBinaryOrder, quoteBinaryStake, quoteBinarySell, getBinaryBookParams, getClosingPrice, getMarketStats24h, getBinaryPositionPnL, getOpenPositionsWithPnL, and getClaimable compute a result from one or more of the tiers above. Each method's API reference names its inputs.

React hooks