@secondlayer/sdk 15.0.0 → 15.0.2

package/dist/streams/index.d.ts

@@ -147,6 +147,7 @@ type IndexEventBase = {
 	tx_contract_id?: string | null;
 	tx_function_name?: string | null;
 };
+/** A fungible-token transfer event. */
 type IndexFtTransfer = IndexEventBase & {
 	event_type: "ft_transfer";
 	asset_identifier: string;
@@ -154,6 +155,7 @@ type IndexFtTransfer = IndexEventBase & {
 	recipient: string;
 	amount: string;
 };
+/** A non-fungible-token transfer event. */
 type IndexNftTransfer = IndexEventBase & {
 	event_type: "nft_transfer";
 	asset_identifier: string;
@@ -161,6 +163,7 @@ type IndexNftTransfer = IndexEventBase & {
 	recipient: string;
 	value: string;
 };
+/** An STX transfer event. */
 type IndexStxTransfer = IndexEventBase & {
 	event_type: "stx_transfer";
 	sender: string;
@@ -168,16 +171,19 @@ type IndexStxTransfer = IndexEventBase & {
 	amount: string;
 	memo: string | null;
 };
+/** An STX mint event. */
 type IndexStxMint = IndexEventBase & {
 	event_type: "stx_mint";
 	recipient: string;
 	amount: string;
 };
+/** An STX burn event. */
 type IndexStxBurn = IndexEventBase & {
 	event_type: "stx_burn";
 	sender: string;
 	amount: string;
 };
+/** An STX lock event with its unlock height. */
 type IndexStxLock = IndexEventBase & {
 	event_type: "stx_lock";
 	sender: string;
@@ -186,30 +192,35 @@ type IndexStxLock = IndexEventBase & {
 		unlock_height: string | null;
 	};
 };
+/** A fungible-token mint event. */
 type IndexFtMint = IndexEventBase & {
 	event_type: "ft_mint";
 	asset_identifier: string;
 	recipient: string;
 	amount: string;
 };
+/** A fungible-token burn event. */
 type IndexFtBurn = IndexEventBase & {
 	event_type: "ft_burn";
 	asset_identifier: string;
 	sender: string;
 	amount: string;
 };
+/** A non-fungible-token mint event. */
 type IndexNftMint = IndexEventBase & {
 	event_type: "nft_mint";
 	asset_identifier: string;
 	recipient: string;
 	value: string;
 };
+/** A non-fungible-token burn event. */
 type IndexNftBurn = IndexEventBase & {
 	event_type: "nft_burn";
 	asset_identifier: string;
 	sender: string;
 	value: string;
 };
+/** A contract `print` event with its topic and value. */
 type IndexPrint = IndexEventBase & {
 	event_type: "print";
 	payload: {
@@ -218,6 +229,7 @@ type IndexPrint = IndexEventBase & {
 		raw_value: string | null;
 	};
 };
+/** A contract call made from inside another contract call. */
 type IndexNestedContractCall = IndexEventBase & {
 	event_type: "nested_contract_call";
 	sender: string | null;
@@ -226,23 +238,27 @@ type IndexNestedContractCall = IndexEventBase & {
 	function_args: unknown;
 	raw_result: string | null;
 };
+/** A contract data variable write. */
 type IndexVarSet = IndexEventBase & {
 	event_type: "var_set";
 	var_name: string;
 	raw_value: string;
 };
+/** A contract map entry overwrite. */
 type IndexMapSet = IndexEventBase & {
 	event_type: "map_set";
 	map: string;
 	raw_key: string;
 	raw_value: string;
 };
+/** A new contract map entry. */
 type IndexMapInsert = IndexEventBase & {
 	event_type: "map_insert";
 	map: string;
 	raw_key: string;
 	raw_value: string;
 };
+/** A contract map entry deletion. */
 type IndexMapDelete = IndexEventBase & {
 	event_type: "map_delete";
 	map: string;
@@ -251,6 +267,7 @@ type IndexMapDelete = IndexEventBase & {
 /** Decoded chain event, discriminated by `event_type`. */
 type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint | IndexNestedContractCall | IndexVarSet | IndexMapSet | IndexMapInsert | IndexMapDelete;
 import { StreamsWireEvent as StreamsWireEvent2, RuneEtchEntry, RuneEventPayload, StreamsEventPayload } from "@secondlayer/shared/streams-rows";
+/** The chain tip: latest block, Bitcoin anchor, and finality boundary. */
 type StreamsTip = {
 	block_height: number;
 	block_hash: string;
@@ -270,15 +287,19 @@ type StreamsTip = {
 	/** Oldest seekable cursor (`<oldest_seekable_height>:0`); `null` = unlimited. */
 	oldest_cursor?: string | null;
 };
-/** `chain=bitcoin` tip (plan 059) — no `burn_block_height`/retention fields,
-*  since Bitcoin has no burn chain of its own and Runes reads have no
-*  retention ladder. Returned by `tip({ chain: "bitcoin" })`. */
+/**
+* The Bitcoin tip, without burn-chain or retention fields.
+*
+* Bitcoin has no burn chain of its own, and Runes reads have no retention
+* ladder. Returned by `tip({ chain: "bitcoin" })`.
+*/
 type StreamsBitcoinTip = {
 	block_height: number;
 	block_hash: string;
 	finalized_height: number;
 	lag_seconds: number;
 };
+/** A canonical Stacks block with its Bitcoin anchor. */
 type StreamsCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -286,7 +307,7 @@ type StreamsCanonicalBlock = {
 	burn_block_hash: string | null;
 	is_canonical: true;
 };
-/** `chain=bitcoin` canonical block (plan 059) — no burn-chain fields. */
+/** A Bitcoin canonical block, without burn-chain fields. */
 type StreamsBitcoinCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -307,6 +328,7 @@ type StreamsReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** One page of events with the next cursor, tip, and reorgs. */
 type StreamsEventsEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
@@ -316,24 +338,30 @@ type StreamsEventsEnvelope<
 	tip: TTip;
 	reorgs: StreamsReorg[];
 };
+/** One page of events with the tip and reorgs, no cursor. */
 type StreamsEventsListEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
 > = Omit<StreamsEventsEnvelope<TEvent, TTip>, "next_cursor">;
-/** The StreamsEvent union narrowed to a `types` selection — what a
-*  const-generic `types: ["ft_transfer"]` buys at the type level. */
+/**
+* The event union narrowed to a `types` selection.
+*
+* A const-generic `types: ["ft_transfer"]` narrows the event type.
+*/
 type StreamsEventOfTypes<T extends readonly StreamsEventType[]> = Extract<StreamsEvent, {
 	event_type: T[number];
 }>;
+/** A starting point and limit for listing reorgs. */
 type StreamsReorgsListParams = {
 	since: string;
 	limit?: number;
 };
+/** A list of reorgs and the cursor to resume from. */
 type StreamsReorgsListEnvelope = {
 	reorgs: StreamsReorg[];
 	next_since: string | null;
 };
-/** A filter that matches a single value or any value in a list. */
+/** A single value or a list of values to match. */
 type StreamsFilterValue = string | readonly string[];
 /**
 * One labelled filter group. Fields inside a group AND together; groups in a
@@ -363,14 +391,15 @@ type StreamsEventForFilter<
 }> : Extract<StreamsEvent, {
 	event_type: T;
 }> : D extends true ? IndexEvent : StreamsEvent;
+/** Cursor, height range, and limit shared by every list call. */
 type StreamsEventsListParamsCommon = {
 	cursor?: string | null;
 	fromHeight?: number;
 	toHeight?: number;
 	limit?: number;
 };
-/** `chain: "stacks"` (default, omit `chain` entirely) — unchanged since
-*  before plan 059. */
+/** `chain: "stacks"` (default, omit `chain` entirely) — unchanged since before Runes events
+*  were added. */
 type StreamsEventsStacksListParams = StreamsEventsListParamsCommon & {
 	chain?: "stacks";
 	/** `vm` reads ordinal. Omit for Streams 1.0. */
@@ -390,12 +419,13 @@ type StreamsEventsStacksListParams = StreamsEventsListParamsCommon & {
 	filters?: StreamsFilterMap;
 };
 /**
-* `chain: "bitcoin"` (plan 059) — Runes events, own cursor space. `types` is
-* restricted to {@link RuneEventType} at the type level, so e.g.
-* `{ chain: "bitcoin", types: ["ft_transfer"] }` is a compile error rather
-* than a silent 400 at request time. `contractId`/`sender`/`recipient`/
-* `assetIdentifier`/`filters`/`clock` don't exist on this branch — they're
-* Stacks-only (the server 400s on them too).
+* List options for Runes events, with their own cursor space.
+*
+* `types` is restricted to `RuneEventType` at the type level, so e.g. `{ chain:
+* "bitcoin", types: ["ft_transfer"] }` is a compile error rather than a silent
+* 400 at request time. `contractId`, `sender`, `recipient`, `assetIdentifier`,
+* `filters`, and `clock` don't exist on this branch; they're Stacks-only (the
+* server 400s on them too).
 */
 type StreamsEventsBitcoinListParams = StreamsEventsListParamsCommon & {
 	chain: "bitcoin";
@@ -406,7 +436,9 @@ type StreamsEventsBitcoinListParams = StreamsEventsListParamsCommon & {
 	/** A mainnet address. */
 	address?: string;
 };
+/** Chain, cursor, height range, and filters for listing Streams events. */
 type StreamsEventsListParams = StreamsEventsStacksListParams | StreamsEventsBitcoinListParams;
+/** Cursor, batching, and stop options shared by every event stream. */
 type StreamsEventsStreamCommon = {
 	fromCursor?: string | null;
 	batchSize?: number;
@@ -415,8 +447,12 @@ type StreamsEventsStreamCommon = {
 	maxEmptyPolls?: number;
 	signal?: AbortSignal;
 };
-/** `chain: "stacks"` (default, omit `chain` entirely) — matches
-*  {@link StreamsEventsStacksListParams}. */
+/**
+* Stream options for Stacks events, the default chain.
+*
+* `chain: "stacks"` is the default, so omit `chain` entirely. Matches
+* `StreamsEventsStacksListParams`.
+*/
 type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	chain?: "stacks";
 	types?: readonly StreamsEventType[];
@@ -428,11 +464,14 @@ type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` (plan 059/061) — Runes events, tailed the same way as
-*  the Stacks default. `types` is restricted to {@link RuneEventType} at the
-*  type level, matching {@link StreamsEventsBitcoinListParams}.
-*  `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters` don't exist
-*  on this branch — they're Stacks-only. */
+/**
+* Stream options for Runes events, tailed like the Stacks default.
+*
+* `types` is restricted to `RuneEventType` at the type level, matching
+* `StreamsEventsBitcoinListParams`. `contractId`, `sender`, `recipient`,
+* `assetIdentifier`, and `filters` don't exist on this branch; they're
+* Stacks-only.
+*/
 type StreamsEventsStreamBitcoinParams = StreamsEventsStreamCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -486,9 +525,12 @@ type StreamsEventsSubscribeStacksParams = StreamsEventsSubscribeCommon & {
 	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
 };
-/** `chain: "bitcoin"` (plan 059/061) — Runes events pushed live, on their own
-*  cursor space. `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters`
-*  don't exist on this branch — they're Stacks-only. */
+/**
+* Options for pushing Runes events live, on their own cursor space.
+*
+* `contractId`, `sender`, `recipient`, `assetIdentifier`, and `filters` don't
+* exist on this branch; they're Stacks-only.
+*/
 type StreamsEventsSubscribeBitcoinParams = StreamsEventsSubscribeCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -579,6 +621,7 @@ type StreamsBatchContext = ConsumerBatchContext;
 type StreamsReorgContext = {
 	cursor: string | null;
 };
+/** Options for consuming Streams events: cursor, batching, filters, handler. */
 type StreamsEventsConsumeParams<
 	TTx = never,
 	D extends boolean = false,
@@ -696,13 +739,14 @@ type StreamsEventsConsumeParams<
 	wake?: () => Promise<void>;
 };
 /**
-* `chain: "bitcoin"` (plan 059/061) — the checkpointed sweep over Runes
-* events. A separate, simpler type from {@link StreamsEventsConsumeParams}
-* rather than a widened union member: `filters`/`on`/`decoded` are Stacks-only
-* concepts (labelled OR-groups and Index-shaped projection have no Runes
-* equivalent yet), so `onBatch` is the only way in and is required. Reorg
-* rewind still works the same way (bitcoin reorgs carry the same
-* `fork_point_height` + `new_canonical_tip` shape as Stacks ones).
+* Options for the checkpointed sweep over Runes events.
+*
+* A separate, simpler type from `StreamsEventsConsumeParams` rather than a
+* widened union member: `filters`, `on`, and `decoded` are Stacks-only concepts
+* (labelled OR-groups and Index-shaped projection have no Runes equivalent
+* yet), so `onBatch` is the only way in and is required. Reorg rewind still
+* works the same way (bitcoin reorgs carry the same `fork_point_height` and
+* `new_canonical_tip` shape as Stacks ones).
 */
 type StreamsEventsConsumeBitcoinParams<TTx = never> = {
 	chain: "bitcoin";
@@ -735,9 +779,10 @@ type StreamsEventsConsumeBitcoinParams<TTx = never> = {
 	wake?: () => Promise<void>;
 };
 /**
-* One yielded page from {@link StreamsClient.consume} — the
-* `GET /v1/streams/events` envelope verbatim, with `next_cursor` renamed to
-* `cursor` (the checkpoint to persist and resume from).
+* One page yielded by `consume`, with `cursor` to persist and resume.
+*
+* It is the `GET /v1/streams/events` envelope verbatim, with `next_cursor`
+* renamed to `cursor`.
 */
 type StreamsBatch<
 	TEvent = StreamsEvent,
@@ -751,6 +796,7 @@ type StreamsBatch<
 	/** Chain reorgs reported alongside this page; empty when none. */
 	reorgs: StreamsReorg[];
 };
+/** Cursor, batch size, and polling options shared by every consume loop. */
 type StreamsConsumeCommon = {
 	/** Resume strictly after this cursor; omit to start from the oldest seekable page. */
 	cursor?: string | null;
@@ -774,9 +820,12 @@ type StreamsConsumeStacksParams = StreamsConsumeCommon & {
 	*  event echoes the labels it matched. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` (plan 059/061) — Runes batches, own cursor space.
-*  `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters` don't exist
-*  on this branch — they're Stacks-only. */
+/**
+* Consume options for Runes batches, with their own cursor space.
+*
+* `contractId`, `sender`, `recipient`, `assetIdentifier`, and `filters` don't
+* exist on this branch; they're Stacks-only.
+*/
 type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -787,11 +836,13 @@ type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
 	address?: string;
 };
 type StreamsConsumeParams = StreamsConsumeStacksParams | StreamsConsumeBitcoinParams;
+/** Where a consume loop stopped: cursor, pages read, empty polls. */
 type StreamsEventsConsumeResult = {
 	cursor: string | null;
 	pages: number;
 	emptyPolls: number;
 };
+/** Options for replaying history from dump files, then tailing live. */
 type StreamsEventsReplayParams = {
 	/** Start point: `"genesis"` (default) or a `<block>:<index>` cursor. */
 	from?: "genesis" | string;
@@ -847,6 +898,7 @@ type StreamsDumpFile = {
 	schema_version: number;
 	created_at: string;
 };
+/** The index of finalized Parquet dump files for one dataset. */
 type StreamsDumpsManifest = {
 	dataset: string;
 	network: string;
@@ -878,38 +930,43 @@ type StreamsDumps = {
 };
 type StreamsClient = {
 	/**
-	* Follow Streams as an async iterator of page batches.
+	* Read Streams page by page as an async iterator.
+	*
+	* Yields one {@link StreamsBatch} per events page, so each yield is exactly
+	* one API call. Empty pages are skipped; at the tip the iterator polls again
+	* every `intervalMs` (default 2000) until `signal` aborts.
 	*
-	* Yields one {@link StreamsBatch} per `GET /v1/streams/events` page — the
-	* existing envelope (`events`, `next_cursor` → `cursor`, `tip`, `reorgs`)
-	* with zero extra API calls. Batches are chosen over per-block groupings
-	* because the envelope is page-keyed, so every yield is exactly one fetch.
-	* Empty pages are skipped; at the tip the iterator re-polls every
-	* `intervalMs` (default 2000) until aborted via `signal`.
+	* Reorgs appear on `batch.reorgs`, but the cursor is not rewound for you.
+	* Use `events.consume` with `onReorg` when you need rollback.
 	*
-	* Reorgs are surfaced on the batch (`batch.reorgs`) but the cursor is not
-	* rewound automatically — use `events.consume` with `onReorg` for managed
-	* rollback semantics.
+	* A literal `types` array narrows every batch's event union to those types.
+	* `chain: "bitcoin"` batches carry Runes rows only, on the bitcoin tip shape.
 	*/
-	/** `chain: "bitcoin"` — batches carry Runes rows only, on the bitcoin tip
-	*  shape (plan 059/061). */
 	consume(params: StreamsConsumeBitcoinParams): AsyncIterableIterator<StreamsBatch<RuneStreamsEvent, StreamsBitcoinTip>>;
-	/** Narrowing overload: a literal `types` array narrows every batch's
-	*  event union to exactly those members. */
 	consume<const T extends readonly StreamsEventType[]>(params: StreamsConsumeStacksParams & {
 		types: T;
 	}): AsyncIterableIterator<StreamsBatch<StreamsEventOfTypes<T>>>;
 	consume(params?: StreamsConsumeParams): AsyncIterableIterator<StreamsBatch>;
 	events: {
-		/** `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
-		*  `event_index` = `ordinal`). Never `StreamsEvent`. Stacks-only —
-		*  `chain: "bitcoin"` has no `clock`. */
+		/**
+		* Read one page of chain events and the next cursor.
+		*
+		* Narrow with `types`, `notTypes`, `contractId`, `sender`, `recipient`,
+		* `assetIdentifier`, `fromHeight`/`toHeight`, or labelled `filters`.
+		* Filters match exactly, and an event type without a given field never
+		* matches it. Pass `next_cursor` back as `cursor` to continue. The
+		* envelope also carries the `tip` and any `reorgs`. To write the events
+		* somewhere with a checkpoint, use `events.consume` instead.
+		*
+		* A literal `types` array narrows every row to those event types.
+		* `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
+		* `event_index` = `ordinal`), never `StreamsEvent`; it is Stacks only.
+		* `chain: "bitcoin"` pages carry Runes rows only, on the bitcoin tip shape,
+		* and filter by `rune` or `address`.
+		*/
 		list(params: StreamsEventsStacksListParams & {
 			clock: "vm";
 		}): Promise<StreamsEventsEnvelope<VmStreamsEvent>>;
-		/** Narrowing overload, matching `consume`. Classic clock only —
-		*  `clock: "vm"` is overload 1, and a general `StreamsEventsListParams`
-		*  variable (clock unresolved) is the wire-union fallback. */
 		list<const T extends readonly StreamsEventType[]>(params: Omit<StreamsEventsStacksListParams, "clock" | "types" | "notTypes"> & {
 			types: T;
 			notTypes?: readonly StreamsEventType[];
@@ -920,27 +977,35 @@ type StreamsClient = {
 			notTypes?: readonly StreamsEventType[];
 			clock?: "classic";
 		}): Promise<StreamsEventsEnvelope>;
-		/** `chain: "bitcoin"` pages carry Runes rows only, on the bitcoin tip
-		*  shape (plan 059). */
 		list(params: StreamsEventsBitcoinListParams): Promise<StreamsEventsEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
-		/** Unresolved `chain`/`clock` on a general params variable: the wire union. */
 		list(params: StreamsEventsListParams): Promise<StreamsEventsEnvelope<StreamsWireEvent>>;
-		/** `chain: "bitcoin"` — Runes events for one transaction. */
+		/**
+		* Read every event a transaction emitted.
+		*
+		* Returns the events and the `tip`, with no `next_cursor`: one transaction
+		* is one response.
+		*
+		* `chain: "bitcoin"` returns the Runes events for one Bitcoin transaction.
+		*/
 		byTxId(txId: string, opts: {
 			chain: "bitcoin";
 		}): Promise<StreamsEventsListEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
 		byTxId(txId: string): Promise<StreamsEventsListEnvelope>;
 		/**
-		* Pull pages from Streams and call `onBatch` after each page.
+		* Run a checkpointed indexer that rewinds on reorgs.
 		*
-		* Use `consume` for indexers and ETL jobs that own checkpointing. Return
-		* the checkpoint cursor from `onBatch`. Default `mode: "tail"` keeps
-		* polling when caught up; `mode: "bounded"` exits on the first empty page.
-		* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
-		* stops it.
+		* Write your rows in `onBatch` and commit `ctx.cursor` in the same
+		* transaction; resume with `fromCursor`. Reorgs at or below your checkpoint
+		* call `onReorg`, then the loop re-reads from the fork point. Delivery is
+		* at-least-once, so keep writes idempotent. With a `sink`, the checkpoint
+		* and rollback are handled for you. `mode: "tail"` (default) keeps polling
+		* at the tip; `mode: "bounded"` returns on the first empty page. It also
+		* stops on `maxPages`, `maxEmptyPolls`, or `signal`. Pass `finalizedOnly`
+		* to skip reorg handling entirely.
+		*
+		* `chain: "bitcoin"` sweeps Runes events; see
+		* {@link StreamsEventsConsumeBitcoinParams}.
 		*/
-		/** `chain: "bitcoin"` — the checkpointed sweep over Runes events; see
-		*  {@link StreamsEventsConsumeBitcoinParams}. */
 		consume<TTx = never>(params: StreamsEventsConsumeBitcoinParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<StreamsEventsConsumeResult>;
@@ -952,46 +1017,66 @@ type StreamsClient = {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Backfill from bulk dumps, then continue live from the dump→live seam in
-		* one call. Iterates finalized dump files (via `onDumpFile`) in block
-		* order, then tails live from the manifest's `latest_finalized_cursor`
-		* (exclusive input → no gap or duplicate at the seam). Requires
-		* `dumpsBaseUrl`.
+		* Backfill from bulk dumps, then continue live in one call.
+		*
+		* Hands each finalized dump file to `onDumpFile` in block order, then tails
+		* live from the manifest's `latest_finalized_cursor`, with no gap or
+		* duplicate at the seam. A file that straddles `from` is delivered whole,
+		* so skip the rows at or below it. Requires `dumpsBaseUrl`.
 		*/
 		replay(params: StreamsEventsReplayParams): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Follow Streams as an async iterator.
+		* Read events one at a time as an async iterator.
+		*
+		* For live processors and watch-style apps that keep their own state. It
+		* tails indefinitely and stops when `signal`, `maxPages`, or
+		* `maxEmptyPolls` ends it. There is no checkpoint or reorg handling; use
+		* `events.consume` for that.
 		*
-		* Use `stream` for live processors and watch-style apps. It tails
-		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
-		* `maxEmptyPolls` stops it.
+		* A literal `types` array narrows every event to those types.
+		* `chain: "bitcoin"` yields Runes events only.
 		*/
-		/** `chain: "bitcoin"` — Runes events only (plan 059/061). */
 		stream(params: StreamsEventsStreamBitcoinParams): AsyncIterable<RuneStreamsEvent>;
-		/** Narrowing overload, matching `consume`. */
 		stream<const T extends readonly StreamsEventType[]>(params: StreamsEventsStreamStacksParams & {
 			types: T;
 		}): AsyncIterable<StreamsEventOfTypes<T>>;
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>;
 		/**
-		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
-		* canonical event as the server pushes it (chain cadence, not poll-bounded),
-		* and verifies each frame's inline ed25519 signature when the client was
-		* created with `verify`. Returns an unsubscribe function whose `done`
-		* settles when the loop ends. Not reorg-aware: an event delivered then
-		* orphaned is never retracted. Durable writers use `consume()`.
+		* Get each new event pushed to `onEvent` as it lands.
+		*
+		* Reconnects from the last handled cursor after a transport error, and
+		* verifies each frame's ed25519 signature when the client has `verify` on.
+		* Returns an unsubscribe function whose `done` promise settles when the
+		* loop ends. Not reorg-aware: an event delivered and then orphaned is never
+		* retracted. Durable writers use `events.consume`.
+		*
+		* `chain: "bitcoin"` delivers Runes rows to `onEvent`.
 		*/
-		/** `chain: "bitcoin"` — `onEvent` receives Runes rows (plan 059/061). */
 		subscribe(params: StreamsEventsSubscribeBitcoinParams): StreamsSubscription;
 		subscribe(params: StreamsEventsSubscribeStacksParams): StreamsSubscription;
 	};
 	blocks: {
+		/**
+		* Read every event in one block, by height or hash.
+		*
+		* Returns the events and the `tip`, with no `next_cursor`.
+		*
+		* `chain: "bitcoin"` returns the Runes events in one Bitcoin block.
+		*/
 		events(heightOrHash: number | string, opts: {
 			chain: "bitcoin";
 		}): Promise<StreamsEventsListEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
 	};
 	reorgs: {
+		/**
+		* List chain reorgs since a cursor.
+		*
+		* `since` is required. Each reorg gives its `fork_point_height` and the
+		* orphaned range. Page with `next_since`.
+		*
+		* `chain: "bitcoin"` lists Bitcoin reorgs, on their own cursor space.
+		*/
 		list(params: StreamsReorgsListParams & {
 			chain: "bitcoin";
 		}): Promise<StreamsReorgsListEnvelope>;
@@ -999,10 +1084,27 @@ type StreamsClient = {
 	};
 	/** Bulk parquet dumps. Requires `dumpsBaseUrl` on the client. */
 	dumps: StreamsDumps;
+	/**
+	* Get the canonical block at a height.
+	*
+	* Returns the block hash and, on Stacks, the burn block it anchors to.
+	*
+	* `chain: "bitcoin"` returns the Bitcoin block, without burn-chain fields.
+	*/
 	canonical(height: number, opts: {
 		chain: "bitcoin";
 	}): Promise<StreamsBitcoinCanonicalBlock>;
 	canonical(height: number): Promise<StreamsCanonicalBlock>;
+	/**
+	* Get the current chain tip.
+	*
+	* Returns the tip height and hash, `finalized_height`, and `lag_seconds`. On
+	* Stacks it also reports the oldest height your tier can seek; older reads
+	* come from the bulk dumps.
+	*
+	* `chain: "bitcoin"` returns the Bitcoin tip, without burn-chain or retention
+	* fields.
+	*/
 	tip(opts: {
 		chain: "bitcoin";
 	}): Promise<StreamsBitcoinTip>;