@secondlayer/sdk 6.0.0 → 6.2.0

package/dist/subgraphs/index.d.ts

@@ -105,6 +105,170 @@ declare class Subgraphs extends BaseClient {
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
+/**
+* Typed client for the contract-discovery API (`GET /v1/contracts`).
+*
+* "Find all contracts conforming to a trait" — backed by the contract registry:
+* `declared` traits parsed from Clarity source, `inferred` standards from static
+* ABI shape-matching. Anonymous public read. `trait` is required; the ABI blob is
+* omitted unless `include: "abi"` is passed.
+*/
+/** Whether a trait match must be declared in source, inferred from ABI, or either. */
+type ContractConformance = "declared" | "inferred" | "any";
+interface ContractsListParams {
+	/** Required. Trait identifier to match (e.g. "sip-010", or a fully-qualified trait). */
+	trait: string;
+	/** Match source. Defaults to "any" server-side. */
+	conformance?: ContractConformance;
+	/** Set to "abi" to include the full ABI blob in each row. */
+	include?: "abi";
+	/** Page size, 1–500 (default 100 server-side). */
+	limit?: number;
+	/** Opaque cursor from a prior response's `next_cursor`. */
+	cursor?: string;
+}
+interface ContractSummary {
+	contract_id: string;
+	deployer: string;
+	block_height: number;
+	declared_traits: string[] | null;
+	inferred_standards: string[] | null;
+	abi_status: string;
+	/** Present only when `include: "abi"` was requested. */
+	abi?: unknown;
+}
+interface ContractsEnvelope {
+	contracts: ContractSummary[];
+	next_cursor: string | null;
+}
+declare class Contracts extends BaseClient {
+	constructor(options?: Partial<SecondLayerOptions>);
+	/** Find contracts conforming to `trait`. `trait` is required (server 400s without it). */
+	list(params: ContractsListParams): Promise<ContractsEnvelope>;
+}
+/**
+* Typed client for the Foundation Datasets REST API (`/v1/datasets/*`).
+*
+* Most datasets are cursor-paginated event lists with a uniform `list`/`walk`
+* surface; a few (bns names/namespaces/resolve, network-health) are
+* offset/single-object/summary and get bespoke methods. Query params are typed
+* per dataset; rows are `DatasetRow` (JSON) in v1 — per-dataset row interfaces
+* are a fast-follow.
+*/
+/** A dataset row — flat JSON object. Per-dataset interfaces are a follow-up. */
+type DatasetRow = Record<string, unknown>;
+/** Filters shared by every cursor-paginated dataset. */
+interface CursorListParams {
+	cursor?: string;
+	limit?: number;
+	fromBlock?: number;
+	toBlock?: number;
+}
+interface CursorEnvelope {
+	rows: DatasetRow[];
+	next_cursor: string | null;
+	tip?: {
+		block_height: number
+	};
+}
+type RangeFilters = CursorListParams;
+type StxTransfersParams = RangeFilters & {
+	sender?: string
+	recipient?: string
+};
+type SbtcEventsParams = RangeFilters & {
+	topic?: string
+	address?: string
+};
+type SbtcTokenEventsParams = RangeFilters & {
+	eventType?: string
+	sender?: string
+	recipient?: string
+};
+type Pox4CallsParams = RangeFilters & {
+	functionName?: string
+	stacker?: string
+	delegateTo?: string
+	signerKey?: string
+	rewardCycle?: number
+	/** Any-role: matches caller OR stacker OR delegate_to. */
+	address?: string
+};
+type BurnchainRewardsParams = RangeFilters & {
+	/** Filter to one Bitcoin reward address. */
+	recipient?: string
+};
+type BurnchainRewardSlotsParams = RangeFilters & {
+	/** Filter to one reward-set Bitcoin address. */
+	holder?: string
+};
+type BnsEventsParams = RangeFilters & {
+	topic?: string
+	namespace?: string
+	name?: string
+	owner?: string
+};
+type BnsNamespaceEventsParams = RangeFilters & {
+	status?: string
+	namespace?: string
+};
+type BnsMarketplaceEventsParams = RangeFilters & {
+	action?: string
+	bnsId?: string
+};
+type CursorDataset<P> = {
+	list: (params?: P) => Promise<CursorEnvelope>
+	walk: (params?: P & {
+		batchSize?: number
+		signal?: AbortSignal
+	}) => AsyncIterable<DatasetRow>
+};
+declare class Datasets extends BaseClient {
+	constructor(options?: Partial<SecondLayerOptions>);
+	/** Dataset catalog + freshness (the discovery endpoint). */
+	listDatasets(): Promise<unknown>;
+	/**
+	* Generic cursor query by slug — used by the CLI. Params are passed through as
+	* REST query keys (snake_case), so callers can use the documented filter names
+	* directly. Throws for non-cursor (bespoke) datasets.
+	*/
+	query(slug: string, params?: Record<string, unknown>): Promise<CursorEnvelope>;
+	readonly stxTransfers: CursorDataset<StxTransfersParams>;
+	readonly sbtcEvents: CursorDataset<SbtcEventsParams>;
+	readonly sbtcTokenEvents: CursorDataset<SbtcTokenEventsParams>;
+	readonly pox4Calls: CursorDataset<Pox4CallsParams>;
+	readonly burnchainRewards: CursorDataset<BurnchainRewardsParams>;
+	readonly burnchainRewardSlots: CursorDataset<BurnchainRewardSlotsParams>;
+	readonly bnsEvents: CursorDataset<BnsEventsParams>;
+	readonly bnsNamespaceEvents: CursorDataset<BnsNamespaceEventsParams>;
+	readonly bnsMarketplaceEvents: CursorDataset<BnsMarketplaceEventsParams>;
+	/** BNS names — offset-paginated. */
+	bnsNames(params?: {
+		namespace?: string
+		owner?: string
+		limit?: number
+		offset?: number
+	}): Promise<{
+		names: DatasetRow[]
+	}>;
+	/** All BNS namespaces (no pagination). */
+	bnsNamespaces(): Promise<{
+		namespaces: DatasetRow[]
+	}>;
+	/** Resolve a fully-qualified BNS name → single record. */
+	bnsResolve(fqn: string): Promise<{
+		name: DatasetRow | null
+	}>;
+	/** Network health summary. */
+	networkHealth(): Promise<{
+		summary: DatasetRow
+	}>;
+	private get;
+	/** Map camelCase filter fields to snake_case query keys (dropping pagination
+	*  controls) and build the canonical query suffix. */
+	private paramsToQuery;
+	private cursorDataset;
+}
 type IndexTip = {
 	block_height: number
 	lag_seconds: number
@@ -414,6 +578,11 @@ type PrintPayload = {
 	raw_value?: string
 };
 type StreamsEventBase = {
+	/**
+	* Globally unique, monotonic position of this event (`<block>:<index>`). Use
+	* it as the primary key of your projection rows — replaying a batch then
+	* upserts cleanly. Don't synthesize your own id from `tx_id`/`event_index`.
+	*/
 	cursor: string
 	block_height: number
 	block_hash: string
@@ -510,9 +679,32 @@ type StreamsEventsStreamParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
+/**
+* The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
+* transaction as your projection writes, then resume from it via `fromCursor`.
+* It is the position to advance to: `next_cursor` normally, or the last
+* finalized event when `finalizedOnly` is set.
+*/
+type StreamsBatchContext = {
+	cursor: string | null
+};
+/**
+* The checkpoint for a reorg rollback. Persist `cursor` (the rewind position)
+* inside the same transaction as your rollback so the two commit atomically.
+*/
+type StreamsReorgContext = {
+	cursor: string
+};
 type StreamsEventsConsumeParams = {
 	fromCursor?: string | null
 	mode?: "tail" | "bounded"
+	/**
+	* Emit only finalized (immutable) events and never surface reorgs. The SDK
+	* checkpoints at the last finalized event and re-reads the unfinalized tail
+	* until it settles. Trades finality lag for zero reorg handling; `onReorg` is
+	* ignored.
+	*/
+	finalizedOnly?: boolean
 	types?: readonly StreamsEventType[]
 	notTypes?: readonly StreamsEventType[]
 	contractId?: StreamsFilterValue
@@ -520,7 +712,20 @@ type StreamsEventsConsumeParams = {
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
 	batchSize?: number
-	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
+	/**
+	* Apply a page of canonical events. Persist `ctx.cursor` in the same
+	* transaction as your writes. Returning a cursor overrides `ctx.cursor` as
+	* the resume point (advanced manual control); returning nothing uses it.
+	*/
+	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
+	/**
+	* Roll your projection back to `reorg.fork_point_height`, persisting
+	* `ctx.cursor` in the same transaction. Called once per *new* reorg
+	* (deduped in-memory, fork-ascending) before the SDK rewinds and re-reads the
+	* now-canonical events. Omit it to ignore reorgs (events stay canonical, but
+	* stale rows from an orphaned fork are left in place).
+	*/
+	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void
 	emptyBackoffMs?: number
 	maxPages?: number
 	maxEmptyPolls?: number
@@ -660,6 +865,8 @@ declare class Subscriptions extends BaseClient {
 declare class SecondLayer extends BaseClient {
 	readonly streams: StreamsClient;
 	readonly index: Index;
+	readonly datasets: Datasets;
+	readonly contracts: Contracts;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);