Reference · @novakoracle/sdk

The TypeScript SDK

A typed client over the Novak contracts, built on viem. Reads of event state go through the Event Bus only, exactly like an on-chain consumer; ABIs and addresses are generated from the contracts and the deployment, never written by hand.

Method groups

42 rows below

Feeds bundled

Chainlink Robinhood mainnet

Networks

46630 testnet · 31337 anvil

Tests

vitest: ABIs, codec, source specs, ladders

Install

The SDK is a pnpm workspace package in this repo (not on npm yet). Inside the monorepo it is linked automatically; build it before anything that imports it:

terminal

pnpm install
pnpm --filter @novakoracle/sdk build      # → sdk/dist
# after any contract change:
forge build && pnpm --filter @novakoracle/sdk gen && pnpm --filter @novakoracle/sdk build

Quickstart

import { createPublicClient, http } from "viem";
import { NovakClient, getDeployment, robinhoodTestnet } from "@novakoracle/sdk";

const publicClient = createPublicClient({ chain: robinhoodTestnet, transport: http() });
const client = new NovakClient(publicClient, undefined, getDeployment(robinhoodTestnet.id));

// Pending | Available | Voided — "not yet" vs "never"
const availability = await client.getAvailability(eventId);
const { available, outcome } = await client.resolveOutcome(eventId);

Method reference

Events (EventRegistry)

Method

createEvent(spec, account)

Kind

write

Returns

tx hash

Method

createEvents(specs[], account)

Kind

write

Returns

tx hash — up to 16 in one transaction

Method

getCreatedEventId(txHash) · getCreatedEventIds(txHash)

Kind

read

Returns

Hex · Hex[] (waits for the receipt)

Method

getEventStatus(eventId)

Kind

read

Returns

EventStatus number

Method

getEventSpec(eventId)

Kind

read

Returns

EventSpecInput

Method

isFinalized(eventId)

Kind

read

Returns

boolean

Method

finalize(eventId, account)

Kind

write

Returns

tx hash (after the dispute window)

Method

listEvents(fromBlock)

Kind

read

Returns

{ eventId, sourceId, specVersion, blockNumber }[]

Method	Kind	Returns
createEvent(spec, account)	write	tx hash
createEvents(specs[], account)	write	tx hash — up to 16 in one transaction
getCreatedEventId(txHash) · getCreatedEventIds(txHash)	read	Hex · Hex[] (waits for the receipt)
getEventStatus(eventId)	read	EventStatus number
getEventSpec(eventId)	read	EventSpecInput
isFinalized(eventId)	read	boolean
finalize(eventId, account)	write	tx hash (after the dispute window)
listEvents(fromBlock)	read	{ eventId, sourceId, specVersion, blockNumber }[]

Reading outcomes (EventBus / Settlement)

The consumer path — use these to settle anything.

Method

getAvailability(eventId)

Kind

read

Returns

Availability: 0 Pending · 1 Available · 2 Voided

Method

isAvailable(eventId)

Kind

read

Returns

boolean

Method

readOutcome(eventId)

Kind

read

Returns

Outcome { outcomeData, finalizedAt, … }

Method

resolveOutcome(eventId)

Kind

read

Returns

{ available, outcome } via Settlement

Method

waitForOutcome(eventId, { intervalMs, timeoutMs })

Kind

read

Returns

{ voided: false, outcome, outcomeData } | { voided: true }

Method	Kind	Returns
getAvailability(eventId)	read	Availability: 0 Pending · 1 Available · 2 Voided
isAvailable(eventId)	read	boolean
readOutcome(eventId)	read	Outcome { outcomeData, finalizedAt, … }
resolveOutcome(eventId)	read	{ available, outcome } via Settlement
waitForOutcome(eventId, { intervalMs, timeoutMs })	read	{ voided: false, outcome, outcomeData } \| { voided: true }

Composites (EventComposer)

Method

createComposite(spec, account)

Kind

write

Returns

tx hash

Method

tryResolveComposite(compositeId, account)

Kind

write

Returns

tx hash

Method

getResolvedComposite(compositeId)

Kind

read

Returns

{ resolved, outcome }

Method	Kind	Returns
createComposite(spec, account)	write	tx hash
tryResolveComposite(compositeId, account)	write	tx hash
getResolvedComposite(compositeId)	read	{ resolved, outcome }

Range markets (DistributionMarket)

Method

createDistributionMarket(question, boundaryIds, tradingClosesAt, b, account)

Kind

write

Returns

tx hash

Method

getCreatedDistributionMarketId(txHash)

Kind

read

Returns

Hex

Method

distributionSubsidy(b, nBuckets)

Kind

helper

Returns

bigint — approve this much first

Method

distributionBuy(id, bucket, usdgIn, minShares, account)

Kind

write

Returns

tx hash

Method

distributionSell(id, bucket, shares, minUsdgOut, account)

Kind

write

Returns

tx hash

Method

distributionQuoteBuy(id, bucket, usdgIn)

Kind

read

Returns

{ shares, fee }

Method

distributionQuoteSell(id, bucket, shares)

Kind

read

Returns

{ collateralOut, fee }

Method

distributionPrices(id)

Kind

read

Returns

number[] (sum to 1)

Method

getDistributionMarket(id) · listDistributionMarkets()

Kind

read

Returns

market info (+ boundaries, prices)

Method

distributionSharesOf(id, trader) · distributionPayoutOf(id, trader)

Kind

read

Returns

bigint[] · bigint

Method

distributionSettle(id, account) · distributionRedeem(id, account)

Kind

write

Returns

tx hash

Method	Kind	Returns
createDistributionMarket(question, boundaryIds, tradingClosesAt, b, account)	write	tx hash
getCreatedDistributionMarketId(txHash)	read	Hex
distributionSubsidy(b, nBuckets)	helper	bigint — approve this much first
distributionBuy(id, bucket, usdgIn, minShares, account)	write	tx hash
distributionSell(id, bucket, shares, minUsdgOut, account)	write	tx hash
distributionQuoteBuy(id, bucket, usdgIn)	read	{ shares, fee }
distributionQuoteSell(id, bucket, shares)	read	{ collateralOut, fee }
distributionPrices(id)	read	number[] (sum to 1)
getDistributionMarket(id) · listDistributionMarkets()	read	market info (+ boundaries, prices)
distributionSharesOf(id, trader) · distributionPayoutOf(id, trader)	read	bigint[] · bigint
distributionSettle(id, account) · distributionRedeem(id, account)	write	tx hash

Yes/no markets (Market)

Method

createMarket(eventId, tradingClosesAt, question, account)

Kind

write

Returns

tx hash

Method

getCreatedMarketId(txHash)

Kind

read

Returns

Hex

Method

depositCollateral(marketId, backingYes, amount, account)

Kind

write

Returns

tx hash — approve first

Method

closePosition(marketId, backingYes, amount, account)

Kind

write

Returns

tx hash — before tradingClosesAt only

Method

settleMarket(marketId, account) · claim(marketId, account)

Kind

write

Returns

tx hash

Method

getMarket(marketId) · listMarkets() · listMarketIds()

Kind

read

Returns

MarketDef(s) — on-chain enumeration

Method

payoutOf(marketId, trader)

Kind

read

Returns

bigint

Method	Kind	Returns
createMarket(eventId, tradingClosesAt, question, account)	write	tx hash
getCreatedMarketId(txHash)	read	Hex
depositCollateral(marketId, backingYes, amount, account)	write	tx hash — approve first
closePosition(marketId, backingYes, amount, account)	write	tx hash — before tradingClosesAt only
settleMarket(marketId, account) · claim(marketId, account)	write	tx hash
getMarket(marketId) · listMarkets() · listMarketIds()	read	MarketDef(s) — on-chain enumeration
payoutOf(marketId, trader)	read	bigint

TreasuryVault

Method

vaultClaimable(eventId, who)

Kind

read

Returns

{ resolver, committee }

Method

vaultBalances()

Kind

read

Returns

{ treasury, insurance }

Method

vaultPendingFees(eventId)

Kind

read

Returns

bigint (not yet allocated)

Method	Kind	Returns
vaultClaimable(eventId, who)	read	{ resolver, committee }
vaultBalances()	read	{ treasury, insurance }
vaultPendingFees(eventId)	read	bigint (not yet allocated)

Collateral (USDG / MockUSDG) & lending guard

Method

collateralBalance(owner) · collateralAllowance(owner) · collateralAllowanceFor(owner, spender)

Kind

read

Returns

bigint (6 decimals)

Method

approveCollateral(amount, account) · approveCollateralFor(spender, amount, account)

Kind

write

Returns

tx hash

Method

mintTestCollateral(to, amount, account)

Kind

write

Returns

tx hash — testnet MockUSDG only

Method

canLiquidate(stockToken)

Kind

read

Returns

{ allowed, blockingEventId } — StockLendingGuard

Method	Kind	Returns
collateralBalance(owner) · collateralAllowance(owner) · collateralAllowanceFor(owner, spender)	read	bigint (6 decimals)
approveCollateral(amount, account) · approveCollateralFor(spender, amount, account)	write	tx hash
mintTestCollateral(to, amount, account)	write	tx hash — testnet MockUSDG only
canLiquidate(stockToken)	read	{ allowed, blockingEventId } — StockLendingGuard

Subscriptions (stub)

Push delivery is deliberately deferred — consumers pull.

Method

subscribe · unsubscribe · isSubscribed

Kind

write

Returns

SubscriptionManager stub

Method	Kind	Returns
subscribe · unsubscribe · isSubscribed	write	SubscriptionManager stub

Other exports

Export

SOURCES · sourceId(name) · sourceName(id)

What it is

The 4 source names and their keccak256 IDs

Export

encodePriceAtSpec · decodePriceAtSpec · Comparator

What it is

chainlink.price-at.v1 specs (feed, threshold, ≥/≤, at, maxStaleness)

Export

buildPriceLadderSpecs · ladderBucketLabels

What it is

N−1 boundary specs for a range market, and their labels

Export

encodeCorporateActionSpec · encodeTradingStatusSpec · encodeFedRateSpec (+ decoders)

What it is

The other three sources

Export

CHAINLINK_FEED_CATALOG · feedBySymbol · feedByAddress

What it is

All 53 Chainlink Robinhood feeds (symbol, name, class, address, decimals)

Export

encodeBoolOutcome · encodeOutcomeV2 · decodeOutcome · encodeOutcomeForVersion

What it is

Outcome payload codec (v1 bool, v2 bool + occurredAt)

Export

deployments · getDeployment(chainId) · explorerUrl(chainId)

What it is

Generated addresses (46630, 31337) and Blockscout URLs

Export

robinhoodTestnet · robinhood · ROBINHOOD_TESTNET_ID · TESTNET_FAUCET_URL

What it is

Chain definitions

Export

eventBusAbi · eventRegistryAbi · disputeManagerAbi · distributionMarketAbi · treasuryVaultAbi · …

What it is

Generated ABIs for every contract (never hand-edited)

Export	What it is
SOURCES · sourceId(name) · sourceName(id)	The 4 source names and their keccak256 IDs
encodePriceAtSpec · decodePriceAtSpec · Comparator	chainlink.price-at.v1 specs (feed, threshold, ≥/≤, at, maxStaleness)
buildPriceLadderSpecs · ladderBucketLabels	N−1 boundary specs for a range market, and their labels
encodeCorporateActionSpec · encodeTradingStatusSpec · encodeFedRateSpec (+ decoders)	The other three sources
CHAINLINK_FEED_CATALOG · feedBySymbol · feedByAddress	All 53 Chainlink Robinhood feeds (symbol, name, class, address, decimals)
encodeBoolOutcome · encodeOutcomeV2 · decodeOutcome · encodeOutcomeForVersion	Outcome payload codec (v1 bool, v2 bool + occurredAt)
deployments · getDeployment(chainId) · explorerUrl(chainId)	Generated addresses (46630, 31337) and Blockscout URLs
robinhoodTestnet · robinhood · ROBINHOOD_TESTNET_ID · TESTNET_FAUCET_URL	Chain definitions
eventBusAbi · eventRegistryAbi · disputeManagerAbi · distributionMarketAbi · treasuryVaultAbi · …	Generated ABIs for every contract (never hand-edited)

Not wrapped on purpose

Resolver and committee calls — submitObservation, dispute, submitTier1Vote / submitTier2Vote, escalateTier2, voidAfterTier2Timeout — aren't part of the consumer client. The resolver node calls them directly with the generated eventRegistryAbi / disputeManagerAbi. Anyone can call them from a wallet or script the same way.