TypeScript SDK

The public ruff-hub package, version 0.2.0, provides ABIs, typed reads, result computation, and verification. It supports Node 22 or later, ESM, TypeScript types, and browser bundlers. viem 2 is a peer dependency.

Install

npm install ruff-hub viem

Pin the package version in the application’s lockfile. The examples below use the public package exports.

Read a request and quote

import type { Address, PublicClient } from 'viem';
import {
  quoteFee,
  readRequest,
  RequestStatus,
  statusName,
} from 'ruff-hub';

export async function inspectRequest(
  client: PublicClient,
  hub: Address,
  consumer: Address,
  sequence: bigint,
) {
  const quote = await quoteFee(client, hub, consumer, 100_000);
  const request = await readRequest(client, hub, sequence);

  return {
    fee: quote.fee,
    callbackGas: quote.callbackGas,
    status: statusName(request.status),
    fulfilled: request.status === RequestStatus.Fulfilled,
    callbackFailed: request.callbackFailed,
  };
}

Configure the PublicClient for your intended chain and verify its chain ID against the deployment record. Use the hub proxy and actual consumer address.

Read helpers

Export	Arguments after client, hub	Result
readRequest	sequence: bigint	HubRequest
readLane	laneId: number	HubLane
quoteFee	consumer: Address, gasLimit = 0	{ fee: bigint, callbackGas: number }
readHubConfig	None	Version, ownership, pause state, lanes, next sequence, tariff, limits, and pending count.

HubRequest and HubLane follow the contract structs. statusName(number) returns None, Pending, Fulfilled, or Expired; an unknown numeric value throws.

Verification helpers

Export	Purpose
verifyHistory(client, hub, sequence, options)	Strict event-history reconstruction with a separate comparison to current state.
verifyFulfillment(client, hub, sequence, options?)	Verification based on the current getters and reveal event.
computeRandom(inputs)	Recompute the result formula; does not by itself verify the seed commitment.

HistoryOptions requires fromBlock: bigint. Optional fields are toBlock, chunk, and maxHeadSteps, also BigInt. Defaults are latest block, 10,000-block chunks, and 2,000,000 head-verification steps.

VerifyOptions accepts maxHeadSteps. Current-state mode can use a current on-chain checkpoint above that threshold. Strict history instead reports an incomplete commitment check.

A full historical proof requires both historical.ok and historical.complete. The separate currentState.status is:

Status	matches	Meaning
match	true	All current-state comparisons succeeded.
mismatch	false	Getters contradict the reconstructed history.
not-checked	null	The current-state comparison did not run.
unavailable	null	At least one required getter could not be read.

Inspect differences as well: an unavailable getter does not erase differences found by other reads. historyExitCode(result) maps the report to CLI exit codes. The verification guide covers complete and partial results.

Formula inputs

import type { Address, Hex } from 'viem';

interface RandomInputs {
  seed: Hex;
  requestBlockHash: Hex;
  userContribution: Hex;
  sequence: bigint;
  consumer: Address;
  chainId: bigint | number;
  hub: Address;
}

computeRandom uses the exact ABI types and field order of the hub. Read the effective seed from the reveal evidence, not an unverified API response.

Event decoding and ABIs

randomnessHubAbi and exampleConsumerAbi are typed ABI exports. The corresponding JSON downloads are hub ABI and consumer ABI.

• decodeRequestedExtra(extraArgs) returns { laneId, index }.
• decodeRevealedExtra(extraArgs) returns { laneId, index, blockHash }.

The package also exports hash-chain helpers and the constants HISTORY_WINDOW = 8191n, MAX_VERIFY_STEPS = 4096n, and ONCHAIN_CHECKPOINT_INTERVAL = 256n.

Integer handling

Keep sequences, block numbers, lane indices, fees, and monetary arithmetic as BigInt. JSON does not encode BigInt directly; convert those values to decimal strings at the serialization boundary. Do not convert fee amounts to JavaScript floating-point numbers for transaction construction.