Class directory and coverage

Starkscan's class routes combine a complete indexed origin catalog with bounded usage observations. They are not interchangeable.

Choose the directory sort by question

GET /v1/{chain}/classes supports:

Page with the returned opaque nextCursor; cursors are sort-specific. A declaration-only class can legitimately have zero/null observed usage fields.

Instance counts are not a chain-wide census

GET /v1/{chain}/class/{class_hash} returns instanceCoverage beside every count. Read it before interpreting instanceCount, accountInstanceCount, contractInstanceCount, or unknownInstanceCount.

• coverageStatus: partial with reasonCode: indexed_observation_window means the projection has bounded observations between observedFromBlock and observedThroughBlock.
• isLowerBound: true means numeric counts can be used only as lower bounds inside that observation contract.
• isExhaustive is always false; the route never claims a global class-instance census.
• classificationCoverage: known_for_observed_instances applies only to materialized observed rows, not every on-chain instance.
• coverageStatus: unavailable means no trustworthy usage watermark exists. The bounds are null and isLowerBound is false.

An unknownInstanceCount is an honest classification result, not evidence that the class label is wrong. A reviewed classLabel describes a class family; it does not force every observed address into account or contract classification.

Origins, labels, and source verification

Class origin evidence can come from indexed finalized/head DECLARE or legacy DEPLOY transactions. It establishes the indexed class origin, not source-code verification. classLabel is a reviewed family label; use the separate verification fields/routes when exact source verification matters.

The request path reads materialized facts and does not call RPC or aggregate raw history to fill gaps. Preserve nullable fields and coverage reason codes rather than substituting current class state or zero.

TypeScript SDK

const page = await explorer.getClasses('SN_MAIN', undefined, 50, 'instances_desc');
const firstClass = page.items[0];
if (!firstClass) {
  throw new Error('no observed classes are currently published');
}

const detail = await explorer.getClass('SN_MAIN', firstClass.classHash);

if (!detail.instanceCoverage.isExhaustive) {
  console.log('observed lower bound', detail.instanceCount);
}

Use the API reference for exact cursor and response schemas and API discovery for the caller-specific operation and rate-limit contract.