@secondlayer/sdk 15.0.0 → 15.0.2

package/dist/index.d.ts

@@ -4,9 +4,20 @@ import { InstanceDiagnosis, PublicStatus } from "@secondlayer/shared/archive/ins
 /** Structural `/public/status` payload. Extra fields are ignored by diagnosis. */
 type InstanceStatus = PublicStatus;
 type InstanceClient = {
+	/**
+	* Get the instance's public status report.
+	*
+	* Reads `GET /public/status`: the overall status, chain tip, chain integrity, and the state of each service and decoder.
+	*/
 	status(): Promise<InstanceStatus>;
+	/**
+	* Turn the status report into a verdict with next steps.
+	*
+	* Resolves to a `state` (`healthy`, `empty-index`, or `degraded`), the API's own `overall` status, and a list of issues, each with the commands that resolve it. A fresh instance with no blocks indexed reads as `empty-index`, not broken.
+	*/
 	diagnose(): Promise<InstanceDiagnosis>;
 };
+/** What to verify against, and the optional block range. */
 type ArchiveVerifyInput = {
 	against: string;
 	target?: string;
@@ -16,6 +27,7 @@ type ArchiveVerifyInput = {
 	publicKeyPem?: string;
 };
 type ArchiveVerifyRangeStatus = "match" | "digest-mismatch" | "count-mismatch" | "missing";
+/** Whether the archive is clean, diverged, or unanchored, by range. */
 type ArchiveVerifyResult = {
 	status: "clean" | "diverged" | "unanchored";
 	target: string;
@@ -40,8 +52,11 @@ type ArchiveVerifyResult = {
 };
 import { RangeDigest } from "@secondlayer/shared/archive/range-digest";
 import { ArchiveStatus } from "@secondlayer/shared/archive/status";
+/** The three archive datasets: blocks, transactions, and events. */
 type ArchiveDataset = "blocks" | "transactions" | "events";
+/** Whether an archive purchase is a bootstrap or a repair. */
 type ArchiveFlow = "bootstrap" | "repair";
+/** One archive file: dataset, block range, path, rows, bytes. */
 type ArchivePartition = {
 	dataset: string;
 	from_block: number;
@@ -64,6 +79,7 @@ type ArchiveManifest = {
 	key_id?: string;
 	[key: string]: unknown;
 };
+/** A loaded archive manifest with its origin and signature check. */
 type LoadedArchive = {
 	manifest: ArchiveManifest;
 	origin: string;
@@ -74,6 +90,7 @@ type LoadedArchive = {
 		reason?: string;
 	};
 };
+/** The price of an archive request, after any free allowance. */
 type ArchiveQuote = {
 	partitions: number;
 	bundles: number;
@@ -90,11 +107,13 @@ type ArchiveFetchItem = {
 	expiresAt: string;
 	chargedUsdMicros: number;
 };
+/** Download links for archive partitions and what they cost. */
 type ArchiveFetchResult = {
 	urls: ArchiveFetchItem[];
 	chargedTotalUsdMicros: number;
 	balanceAfterUsdMicros: number;
 };
+/** Your archive credit balance and its refill settings. */
 type ArchiveCreditsBalance = {
 	creditsUsdMicros: string;
 	refill: {
@@ -103,37 +122,88 @@ type ArchiveCreditsBalance = {
 		lastAt: string | null;
 	};
 };
+/** Options for loading an archive manifest. */
 type ArchiveLoadOptions = {
 	insecure?: boolean;
 };
 type ArchiveClient = {
+	/**
+	* Load the latest signed archive manifest.
+	*
+	* Reads `<archive>/latest.json` unless `against` names another manifest URL. The manifest's ed25519 signature is checked against the archive signing key, and a missing or invalid one throws `ArchiveSignatureError`. `insecure: true` skips the check; `signature.verified` on the result says whether it held.
+	*/
 	latest(against?: string, opts?: ArchiveLoadOptions): Promise<LoadedArchive>;
+	/**
+	* Load an archive manifest from a URL.
+	*
+	* Takes http(s) URLs only; a local path throws a `ValidationError` and stays on the CLI. The signature check is the same as {@link latest}.
+	*/
 	load(against: string, opts?: ArchiveLoadOptions): Promise<LoadedArchive>;
+	/**
+	* Get the archive's current operational state.
+	*
+	* Reads the public `status.json`: `fresh`, `lagging`, `stale`, `gap`, `failed-audit`, or `source-unavailable`, plus how far the last signed publish reaches.
+	*/
 	status(): Promise<ArchiveStatus>;
+	/**
+	* List a loaded archive's partitions, optionally filtered.
+	*
+	* Runs locally on the manifest you already loaded and makes no request. Filter by `dataset` (`blocks`, `transactions`, or `events`) and a block range.
+	*/
 	partitions(ref: LoadedArchive, filter?: {
 		dataset?: ArchiveDataset;
 		fromBlock?: number;
 		toBlock?: number;
 	}): ArchivePartition[];
+	/**
+	* Price a fetch against your balance before you pay for it.
+	*
+	* Nothing is charged. `flow` is `bootstrap` or `repair`. The quote has the bundle count, the price in USD, the free repair allowance applied, your balance, and `sufficient`. Needs an account key (`sk-sl_*`), not an instance token.
+	*/
 	quote(input: {
 		paths: string[];
 		flow: ArchiveFlow;
 	}): Promise<ArchiveQuote>;
+	/**
+	* Get presigned download URLs for archive partitions.
+	*
+	* Draws credits per partition bundle; your first six repair bundles each month are free. Lists longer than 64 paths go out in batches of 64. Each URL is short-lived (`expiresAt`); pass it to {@link download}. An empty balance throws `InsufficientArchiveCreditsError` with the shortfall. Needs an account key (`sk-sl_*`).
+	*/
 	fetch(input: {
 		paths: string[];
 		flow: ArchiveFlow;
 	}): Promise<ArchiveFetchResult>;
+	/**
+	* Download a partition's bytes and verify them.
+	*
+	* The sha256 is checked against the manifest, and a mismatch throws `ArchiveSignatureError`. On the official archive host you must pass the presigned `url` from {@link fetch}, or it throws a `ValidationError`; any other host downloads straight from its archive tree.
+	*/
 	download(partition: ArchivePartition, opts?: {
 		url?: string;
 	}): Promise<Uint8Array>;
 	credits: {
+		/**
+		* Get your archive credit balance.
+		*
+		* Returns `creditsUsdMicros` (millionths of a dollar, as a string) and your auto-refill setting. Needs an account key (`sk-sl_*`).
+		*/
 		balance(): Promise<ArchiveCreditsBalance>;
+		/**
+		* Start a card checkout for a credit pack.
+		*
+		* `pack` is the dollar amount: 10, 25, 50, or 100. Resolves to the checkout `url`. Needs no account key.
+		*/
 		checkout(input: {
 			email: string;
 			pack: 10 | 25 | 50 | 100;
 		}): Promise<{
 			url: string;
 		}>;
+		/**
+		* Set or turn off automatic credit refill.
+		*
+		* Pass `belowUsd` and `packUsd` to buy a pack whenever the balance drops below the threshold, or `{ off: true }` to stop. Needs an account key (`sk-sl_*`).
+		*/
 		refill(input: {
 			belowUsd: number;
 			packUsd: 10 | 25 | 50 | 100;
@@ -147,6 +217,11 @@ type ArchiveClient = {
 };
 /** Hosted archive client plus instance `verify`. `status()` is still the public archive tree. */
 type SecondLayerArchive = ArchiveClient & {
+	/**
+	* Check your instance's data against a signed archive.
+	*
+	* Runs `POST /v1/archive/verify` on your instance: read-only, and it compares raw identity digests only (the deep semantic check is CLI-only). Resolves to `clean`, `diverged`, or `unanchored`; a failed signature is `unanchored`, never `clean`. Narrow the check with `fromBlock` and `toBlock`. Verification is free.
+	*/
 	verify(input: ArchiveVerifyInput): Promise<ArchiveVerifyResult>;
 };
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
@@ -280,6 +355,7 @@ declare abstract class BaseClient {
 */
 /** Whether a trait match must be declared in source, inferred from ABI, or either. */
 type ContractConformance = "declared" | "inferred" | "any";
+/** Trait, conformance, and paging for listing contracts. */
 interface ContractsListParams {
 	/** Required. Trait identifier to match (e.g. "sip-010", or a fully-qualified trait). */
 	trait: string;
@@ -292,6 +368,7 @@ interface ContractsListParams {
 	/** Opaque cursor from a prior response's `next_cursor`. */
 	cursor?: string;
 }
+/** A deployed contract with its traits, standards, and ABI status. */
 interface ContractSummary {
 	contract_id: string;
 	deployer: string;
@@ -302,6 +379,7 @@ interface ContractSummary {
 	/** Present only when `include: "abi"` was requested. */
 	abi?: unknown;
 }
+/** One page of contracts and the cursor for the next page. */
 interface ContractsEnvelope {
 	contracts: ContractSummary[];
 	next_cursor: string | null;
@@ -311,8 +389,10 @@ declare class Contracts extends BaseClient {
 	/** Find contracts conforming to `trait`. `trait` is required (server 400s without it). */
 	list(params: ContractsListParams): Promise<ContractsEnvelope>;
 	/**
-	* Fetch a single contract from the registry by id (the prod-safe ABI source).
-	* Pass `{ includeAbi: true }` for the full ABI blob. Resolves null on 404.
+	* Get one contract from the registry by id, or `null`.
+	*
+	* The prod-safe ABI source. Pass `{ includeAbi: true }` for the full ABI
+	* blob. Resolves to `null` on 404.
 	*/
 	get(contractId: string, opts?: {
 		includeAbi?: boolean;
@@ -533,6 +613,7 @@ type WithSinkTx<TTx> = [TTx] extends [never] ? unknown : {
 import { VmEventType } from "@secondlayer/shared";
 import { RuneEventType, RuneStreamsEvent, StreamsEvent, StreamsEventType, StreamsWireEvent, VmStreamsEvent } from "@secondlayer/shared/streams-rows";
 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;
@@ -552,15 +633,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;
@@ -568,7 +653,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;
@@ -589,6 +674,7 @@ type StreamsReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** One page of events with the next cursor, tip, and reorgs. */
 type StreamsEventsEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
@@ -598,24 +684,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
@@ -645,14 +737,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. */
@@ -672,12 +765,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";
@@ -688,7 +782,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;
@@ -697,8 +793,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[];
@@ -710,11 +810,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[];
@@ -768,9 +871,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[];
@@ -861,6 +967,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,
@@ -978,13 +1085,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";
@@ -1017,9 +1125,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,
@@ -1033,6 +1142,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;
@@ -1056,9 +1166,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[];
@@ -1069,11 +1182,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;
@@ -1129,6 +1244,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;
@@ -1160,38 +1276,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[];
@@ -1202,27 +1323,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.
+		*
+		* 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.
 		*
-		* 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.
+		* `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>;
@@ -1234,46 +1363,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.
 		*
-		* Use `stream` for live processors and watch-style apps. It tails
-		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
-		* `maxEmptyPolls` stops it.
+		* 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.
+		*
+		* 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>;
@@ -1281,10 +1430,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>;
@@ -1452,6 +1618,7 @@ type IndexReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** A decoded fungible-token transfer: sender, recipient, asset, amount. */
 type FtTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1466,6 +1633,7 @@ type FtTransfer = {
 	recipient: string;
 	amount: string;
 };
+/** One page of fungible-token transfers, with the cursor, tip, and reorgs. */
 type FtTransfersEnvelope<TRow = FtTransfer> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -1477,6 +1645,7 @@ type FtTransfersEnvelope<TRow = FtTransfer> = {
 type FtTransferAlwaysFields = "cursor" | "block_height" | "event_type";
 /** An ft-transfer row narrowed to the requested columns plus the always-present ones. */
 type FtTransferFields<F extends keyof FtTransfer & string> = Pick<FtTransfer, (F | FtTransferAlwaysFields) & keyof FtTransfer>;
+/** Column selection, paging, and filters for listing token transfers. */
 type FtTransfersListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -1512,7 +1681,9 @@ type WalkOptions = PageRetryOptions & {
 	*  walk from a stopped one. */
 	signal?: AbortSignal;
 };
+/** `FtTransfersListParams` without `limit`, plus walk options. */
 type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & WalkOptions;
+/** A decoded non-fungible-token transfer: sender, recipient, asset, value. */
 type NftTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1527,6 +1698,7 @@ type NftTransfer = {
 	recipient: string;
 	value: string;
 };
+/** One page of non-fungible-token transfers, with the cursor, tip, and reorgs. */
 type NftTransfersEnvelope<TRow = NftTransfer> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -1537,6 +1709,7 @@ type NftTransfersEnvelope<TRow = NftTransfer> = {
 type NftTransferAlwaysFields = "cursor" | "block_height" | "event_type";
 /** An nft-transfer row narrowed to the requested columns plus the always-present ones. */
 type NftTransferFields<F extends keyof NftTransfer & string> = Pick<NftTransfer, (F | NftTransferAlwaysFields) & keyof NftTransfer>;
+/** Column selection, paging, and filters for listing NFT transfers. */
 type NftTransfersListParams = {
 	/** Columns to return (see {@link FtTransfersListParams.fields}). */
 	fields?: readonly (keyof NftTransfer & string)[];
@@ -1550,6 +1723,7 @@ type NftTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `NftTransfersListParams` without `limit`, plus walk options. */
 type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & WalkOptions;
 type IndexEventBase = {
 	cursor: string;
@@ -1570,6 +1744,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;
@@ -1577,6 +1752,7 @@ type IndexFtTransfer = IndexEventBase & {
 	recipient: string;
 	amount: string;
 };
+/** A non-fungible-token transfer event. */
 type IndexNftTransfer = IndexEventBase & {
 	event_type: "nft_transfer";
 	asset_identifier: string;
@@ -1584,6 +1760,7 @@ type IndexNftTransfer = IndexEventBase & {
 	recipient: string;
 	value: string;
 };
+/** An STX transfer event. */
 type IndexStxTransfer = IndexEventBase & {
 	event_type: "stx_transfer";
 	sender: string;
@@ -1591,16 +1768,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;
@@ -1609,30 +1789,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: {
@@ -1641,6 +1826,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;
@@ -1649,23 +1835,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;
@@ -1682,6 +1872,7 @@ type IndexEventFields<
 	T extends IndexEventType,
 	F extends keyof IndexEventOf<T> & string
 > = Pick<IndexEventOf<T>, (F | IndexAlwaysFields) & keyof IndexEventOf<T>>;
+/** One page of decoded events, with the cursor, tip, and reorgs. */
 type EventsEnvelope<
 	T extends IndexEventType = IndexEventType,
 	TRow = IndexEventOf<T>
@@ -1696,6 +1887,7 @@ type EventsEnvelope<
 type IndexEventOf<T extends IndexEventType> = Extract<IndexEvent, {
 	event_type: T;
 }>;
+/** Event type, paging, and filters for listing decoded events. */
 type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	/** Decoded types or VM types (`nested_contract_call`, `map_set`, …). */
 	eventType: T;
@@ -1740,11 +1932,13 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	*/
 	fields?: readonly (keyof IndexEventOf<T> & string)[];
 };
+/** `EventsListParams` without `limit`, plus walk options. */
 type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & WalkOptions;
 type EventsConsumeParams<
 	T extends IndexEventType = IndexEventType,
 	TTx = never
 > = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit" | "fields"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>, TTx>;
+/** A decoded contract call: contract, function, sender, arguments, result. */
 type IndexContractCall = {
 	cursor: string;
 	block_height: number;
@@ -1759,12 +1953,14 @@ type IndexContractCall = {
 	result: unknown;
 	result_hex: string | null;
 };
+/** One page of contract calls, with the cursor, tip, and reorgs. */
 type ContractCallsEnvelope = {
 	contract_calls: IndexContractCall[];
 	next_cursor: string | null;
 	tip: IndexTip;
 	reorgs: IndexReorg[];
 };
+/** Paging and contract filters for listing contract calls. */
 type ContractCallsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1780,6 +1976,7 @@ type ContractCallsListParams = {
 	*  Mutually exclusive with contractId. */
 	trait?: string;
 };
+/** `ContractCallsListParams` without `limit`, plus walk options. */
 type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & WalkOptions;
 type ContractCallsConsumeParams<TTx = never> = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope, TTx>;
 /** One canonical block in the sync map. Lean by design — block + parent hash
@@ -1793,11 +1990,13 @@ type IndexCanonicalBlock = {
 	burn_block_height: number;
 	burn_block_hash: string | null;
 };
+/** One page of canonical blocks, with the next cursor and chain tip. */
 type CanonicalEnvelope = {
 	canonical: IndexCanonicalBlock[];
 	next_cursor: string | null;
 	tip: IndexTip;
 };
+/** Paging and height filters for listing canonical blocks. */
 type CanonicalListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1805,6 +2004,7 @@ type CanonicalListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `CanonicalListParams` without `limit`, plus walk options. */
 type CanonicalWalkParams = Omit<CanonicalListParams, "limit"> & WalkOptions;
 /** One MARF write a block committed, in the node's write order. Present only
 *  from the height the instance's node subscribed to `state_writes`. */
@@ -1829,12 +2029,14 @@ type IndexStateWrite = {
 	tx_contract_id?: string | null;
 	tx_function_name?: string | null;
 };
+/** One page of contract state writes, with the cursor, tip, and reorgs. */
 type StateWritesEnvelope = {
 	state_writes: IndexStateWrite[];
 	next_cursor: string | null;
 	tip: IndexTip;
 	reorgs: IndexReorg[];
 };
+/** Paging and filters for listing contract state writes. */
 type StateWritesListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1848,6 +2050,7 @@ type StateWritesListParams = {
 	/** Join the writing transaction's `tx_*` fields onto each row. */
 	txContext?: boolean;
 };
+/** `StateWritesListParams` without `limit`, plus walk options. */
 type StateWritesWalkParams = Omit<StateWritesListParams, "limit"> & WalkOptions;
 /** A block resource. Metadata is intentionally thin — only chain-linkage and
 *  burn-anchor fields are persisted (no miner / tx_count / signer). */
@@ -1861,15 +2064,18 @@ type IndexBlock = {
 	block_time: string | null;
 	canonical: boolean;
 };
+/** One page of blocks, with the next cursor and chain tip. */
 type BlocksEnvelope = {
 	blocks: IndexBlock[];
 	next_cursor: string | null;
 	tip: IndexTip;
 };
+/** One block and the chain tip. */
 type BlockEnvelope = {
 	block: IndexBlock;
 	tip: IndexTip;
 };
+/** Paging and height filters for listing blocks. */
 type BlocksListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1877,6 +2083,7 @@ type BlocksListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `BlocksListParams` without `limit`, plus walk options. */
 type BlocksWalkParams = Omit<BlocksListParams, "limit"> & WalkOptions;
 type IndexPostCondition = {
 	type: "stx";
@@ -1953,12 +2160,14 @@ type IndexTransaction = {
 		cause: number;
 	};
 };
+/** One page of transactions, with the cursor, tip, and reorgs. */
 type TransactionsEnvelope<TRow = IndexTransaction> = {
 	transactions: TRow[];
 	next_cursor: string | null;
 	tip: IndexTip;
 	reorgs: IndexReorg[];
 };
+/** One transaction and the chain tip. */
 type TransactionEnvelope = {
 	transaction: IndexTransaction;
 	tip: IndexTip;
@@ -1967,6 +2176,7 @@ type TransactionEnvelope = {
 type TransactionAlwaysFields = "cursor" | "block_height" | "tx_id";
 /** A Transaction row narrowed to the requested columns plus the always-present ones. */
 type TransactionFields<F extends keyof IndexTransaction & string> = Pick<IndexTransaction, (F | TransactionAlwaysFields) & keyof IndexTransaction>;
+/** Column selection, paging, and filters for listing transactions. */
 type TransactionsListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -1983,6 +2193,7 @@ type TransactionsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `TransactionsListParams` without `limit`, plus walk options. */
 type TransactionsWalkParams = Omit<TransactionsListParams, "limit"> & WalkOptions;
 /** A decoded PoX-4 stacking action (one per stacking contract call). */
 type IndexStackingAction = {
@@ -2009,6 +2220,7 @@ type IndexStackingAction = {
 	signer_key: string | null;
 	result_ok: boolean;
 };
+/** One page of stacking actions, with the cursor, tip, and reorgs. */
 type StackingEnvelope = {
 	stacking: IndexStackingAction[];
 	next_cursor: string | null;
@@ -2017,6 +2229,7 @@ type StackingEnvelope = {
 	/** Present only when the PoX-4 decoder is disabled, explaining an empty feed. */
 	notes?: string;
 };
+/** Paging and filters for listing stacking actions. */
 type StackingListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2027,6 +2240,7 @@ type StackingListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `StackingListParams` without `limit`, plus walk options. */
 type StackingWalkParams = Omit<StackingListParams, "limit"> & WalkOptions;
 /** A pending (unconfirmed) transaction. Like a transaction document but
 *  pre-chain — no block_height/tx_index/result/events — with `received_at` and
@@ -2063,15 +2277,18 @@ type IndexMempoolTransaction = {
 		cause: number;
 	};
 };
+/** One page of pending transactions, with the next cursor and chain tip. */
 type MempoolEnvelope = {
 	mempool: IndexMempoolTransaction[];
 	next_cursor: string | null;
 	tip: IndexTip;
 };
+/** One pending transaction and the chain tip. */
 type MempoolTransactionEnvelope = {
 	transaction: IndexMempoolTransaction;
 	tip: IndexTip;
 };
+/** Paging and sender filters for listing pending transactions. */
 type MempoolListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2083,11 +2300,13 @@ type MempoolListParams = {
 	/** Filter to pending calls to a single function (composes with `contractId`). */
 	functionName?: string;
 };
+/** `MempoolListParams` without `limit`, plus walk options. */
 type MempoolWalkParams = Omit<MempoolListParams, "limit"> & WalkOptions;
 /**
-* Empirical per-topic print payload schema for a contract, inferred from
-* sampled on-chain events. `topics` is sorted by count desc; `sampled` is true
-* when the contract has more print events than the windows examined.
+* Per-topic print payload schema for a contract, inferred from sampled events.
+*
+* `topics` is sorted by count desc; `sampled` is true when the contract has
+* more print events than the windows examined.
 */
 type PrintSchemaResponse = {
 	contract_id: string;
@@ -2124,8 +2343,12 @@ type IndexSbtcDeposit = {
 type IndexSbtcDepositDetail = IndexSbtcDeposit & {
 	status: "COMPLETED";
 };
-/** A peg-out collapsed to one row per `request_id`, with lifecycle `status`
-*  derived from the latest accept/reject. */
+/**
+* A peg-out as one row per request, with its latest status.
+*
+* Collapsed to one row per `request_id`, with lifecycle `status` derived from
+* the latest accept/reject.
+*/
 type IndexSbtcWithdrawal = {
 	cursor: string;
 	request_id: number;
@@ -2179,8 +2402,11 @@ type IndexSbtcWithdrawalDetail = {
 	};
 	finalized: boolean;
 };
-/** A raw decoded sBTC protocol-state event — the full `sbtc_events` row, one
-*  per event across all topics. */
+/**
+* A raw decoded sBTC protocol-state event, one per event.
+*
+* It is the full `sbtc_events` row, one per event across all topics.
+*/
 type IndexSbtcEvent = {
 	cursor: string;
 	block_height: number;
@@ -2219,6 +2445,7 @@ type IndexSbtcSummary = {
 	total_locked_sats: string;
 	sbtc_supply_sats: string | null;
 };
+/** One page of sBTC deposits, with the cursor, tip, and reorgs. */
 type SbtcDepositsEnvelope<TRow = IndexSbtcDeposit> = {
 	deposits: TRow[];
 	next_cursor: string | null;
@@ -2227,10 +2454,12 @@ type SbtcDepositsEnvelope<TRow = IndexSbtcDeposit> = {
 	/** Present only when the sBTC decoder is disabled, explaining an empty feed. */
 	notes?: string;
 };
+/** One sBTC deposit and the chain tip. */
 type SbtcDepositEnvelope = {
 	deposit: IndexSbtcDepositDetail;
 	tip: IndexTip;
 };
+/** One page of sBTC withdrawals, with the cursor, tip, and reorgs. */
 type SbtcWithdrawalsEnvelope<TRow = IndexSbtcWithdrawal> = {
 	withdrawals: TRow[];
 	next_cursor: string | null;
@@ -2238,10 +2467,12 @@ type SbtcWithdrawalsEnvelope<TRow = IndexSbtcWithdrawal> = {
 	reorgs: IndexReorg[];
 	notes?: string;
 };
+/** One sBTC withdrawal and the chain tip. */
 type SbtcWithdrawalEnvelope = {
 	withdrawal: IndexSbtcWithdrawalDetail;
 	tip: IndexTip;
 };
+/** One page of sBTC events, with the cursor, tip, and reorgs. */
 type SbtcEventsEnvelope = {
 	events: IndexSbtcEvent[];
 	next_cursor: string | null;
@@ -2249,11 +2480,13 @@ type SbtcEventsEnvelope = {
 	reorgs: IndexReorg[];
 	notes?: string;
 };
+/** The sBTC totals and the chain tip. */
 type SbtcSummaryEnvelope = {
 	summary: IndexSbtcSummary;
 	tip: IndexTip;
 	notes?: string;
 };
+/** Column selection, paging, and filters for listing sBTC deposits. */
 type SbtcDepositsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2275,11 +2508,13 @@ type SbtcDepositsListParams = {
 type SbtcDepositAlwaysFields = "cursor" | "block_height";
 /** A deposit row narrowed to the requested columns plus the always-present ones. */
 type SbtcDepositFields<F extends keyof IndexSbtcDeposit & string> = Pick<IndexSbtcDeposit, (F | SbtcDepositAlwaysFields) & keyof IndexSbtcDeposit>;
+/** `SbtcDepositsListParams` without `limit`, plus walk options. */
 type SbtcDepositsWalkParams = Omit<SbtcDepositsListParams, "limit"> & WalkOptions;
 /** SbtcWithdrawal columns that survive any projection. */
 type SbtcWithdrawalAlwaysFields = "cursor" | "request_id";
 /** A SbtcWithdrawal row narrowed to the requested columns plus the always-present ones. */
 type SbtcWithdrawalFields<F extends keyof IndexSbtcWithdrawal & string> = Pick<IndexSbtcWithdrawal, (F | SbtcWithdrawalAlwaysFields) & keyof IndexSbtcWithdrawal>;
+/** Column selection, paging, and filters for listing sBTC withdrawals. */
 type SbtcWithdrawalsListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -2300,7 +2535,9 @@ type SbtcWithdrawalsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `SbtcWithdrawalsListParams` without `limit`, plus walk options. */
 type SbtcWithdrawalsWalkParams = Omit<SbtcWithdrawalsListParams, "limit"> & WalkOptions;
+/** Paging and filters for listing sBTC events. */
 type SbtcEventsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2313,6 +2550,7 @@ type SbtcEventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `SbtcEventsListParams` without `limit`, plus walk options. */
 type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & WalkOptions;
 type SbtcEventsConsumeParams<TTx = never> = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope, TTx>;
 type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit" | "fields"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope, TTx>;
@@ -2320,15 +2558,27 @@ type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "curs
 *  events, scoreboard). The only productized decoded sBTC peg feed on Stacks. */
 interface SbtcResource {
 	deposits: {
-		/** Narrowing overload: `fields` shrinks the row type to exactly the
-		*  requested columns plus {@link SbtcDepositAlwaysFields}. */
+		/**
+		* Read one page of completed sBTC deposits.
+		*
+		* Filter by `sender`, `bitcoinTxid`, and a height range. `confirmed: true` keeps only deposits past the finality boundary. `fields` returns only those columns and narrows the row type; `cursor` and `block_height` always come back.
+		*/
 		list<const F extends keyof IndexSbtcDeposit & string>(params: SbtcDepositsListParams & {
 			fields: readonly F[];
 		}): Promise<SbtcDepositsEnvelope<SbtcDepositFields<F>>>;
 		list(params?: SbtcDepositsListParams): Promise<SbtcDepositsEnvelope>;
+		/**
+		* Iterate every completed sBTC deposit, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: SbtcDepositsWalkParams): AsyncIterable<IndexSbtcDeposit>;
-		/** Checkpointed sweep of completed deposits — append-only, so safe to
-		*  mirror. See {@link IndexConsumeOptions}. */
+		/**
+		* Run a checkpointed, reorg-aware indexer over completed deposits.
+		*
+		* Deposits are append-only, so they are safe to mirror. See
+		* {@link IndexConsumeOptions}.
+		*/
 		consume<TTx = never>(params: SbtcDepositsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<{
@@ -2340,21 +2590,43 @@ interface SbtcResource {
 		get(bitcoinTxid: string): Promise<SbtcDepositEnvelope | null>;
 	};
 	withdrawals: {
-		/** Narrowing overload: `fields` shrinks the row type to exactly the
-		*  requested columns plus {@link SbtcWithdrawalAlwaysFields}. */
+		/**
+		* Read one page of sBTC withdrawals, each with its current status.
+		*
+		* Filter by `status` (`REQUESTED`, `ACCEPTED`, `REJECTED`), `sender`, `requestId`, `settlementConfirmed`, and a height range. A row changes as the peg-out moves along, which is why withdrawals have no `consume`. `fields` returns only those columns and narrows the row type; `cursor` and `request_id` always come back.
+		*/
 		list<const F extends keyof IndexSbtcWithdrawal & string>(params: SbtcWithdrawalsListParams & {
 			fields: readonly F[];
 		}): Promise<SbtcWithdrawalsEnvelope<SbtcWithdrawalFields<F>>>;
 		list(params?: SbtcWithdrawalsListParams): Promise<SbtcWithdrawalsEnvelope>;
+		/**
+		* Iterate every sBTC withdrawal, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: SbtcWithdrawalsWalkParams): AsyncIterable<IndexSbtcWithdrawal>;
 		/** Fetch a withdrawal's full lifecycle by request id; 404 → null. */
 		get(requestId: number): Promise<SbtcWithdrawalEnvelope | null>;
 	};
 	events: {
+		/**
+		* Read one page of the raw sBTC peg event log.
+		*
+		* Filter by `topic`, `sender`, `requestId`, `bitcoinTxid`, and a height range. `confirmed: true` keeps only events past the finality boundary.
+		*/
 		list(params?: SbtcEventsListParams): Promise<SbtcEventsEnvelope>;
+		/**
+		* Iterate every sBTC peg event, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: SbtcEventsWalkParams): AsyncIterable<IndexSbtcEvent>;
-		/** Checkpointed sweep of the raw peg event log — append-only across all
-		*  six topics. See {@link IndexConsumeOptions}. */
+		/**
+		* Run a checkpointed, reorg-aware indexer over the raw peg event log.
+		*
+		* The log is append-only across all six topics. See
+		* {@link IndexConsumeOptions}.
+		*/
 		consume<TTx = never>(params: SbtcEventsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<{
@@ -2363,7 +2635,11 @@ interface SbtcResource {
 			emptyPolls: number;
 		}>;
 	};
-	/** The peg scoreboard — a single all-time aggregate (no pagination). */
+	/**
+	* Get the all-time sBTC peg scoreboard.
+	*
+	* A single aggregate, with no pagination.
+	*/
 	summary(): Promise<SbtcSummaryEnvelope>;
 }
 /** One pox-5 reward cycle, exact to the node. */
@@ -2420,6 +2696,7 @@ type IndexPoxCycleSigner = {
 	in_set: boolean;
 	rewards_claimed: string;
 };
+/** One page of reward cycles, newest first, with the next cursor. */
 type PoxCyclesEnvelope = {
 	/** The PoX version this response reports. Currently 5. */
 	pox_version: 5;
@@ -2428,6 +2705,7 @@ type PoxCyclesEnvelope = {
 	next_cursor: number | null;
 	tip: IndexTip;
 };
+/** One reward cycle with its signers and the chain tip. */
 type PoxCycleEnvelope = {
 	pox_version: 5;
 	cycle: IndexPoxCycle & {
@@ -2435,19 +2713,35 @@ type PoxCycleEnvelope = {
 	};
 	tip: IndexTip;
 };
+/** Paging for listing reward cycles. */
 type PoxCyclesListParams = {
 	/** A `reward_cycle` to page from; the page returns cycles below it (descending). */
 	cursor?: number | null;
 	limit?: number;
 };
+/** `PoxCyclesListParams` without `limit`, plus walk options. */
 type PoxCyclesWalkParams = Omit<PoxCyclesListParams, "limit"> & WalkOptions;
 /** `index.pox` — reward cycles of the current PoX (PoX-5). */
 interface PoxResource {
 	cycles: {
+		/**
+		* Read one page of PoX reward cycles, newest first.
+		*
+		* `cursor` is a `reward_cycle` number, and the page returns the cycles below it. `next_cursor` is the next cycle number to page from, or `null` at the end. This reports the current PoX (PoX-5); PoX-4 history is not served here, so read `stacking` for it.
+		*/
 		list(params?: PoxCyclesListParams): Promise<PoxCyclesEnvelope>;
+		/**
+		* Iterate every reward cycle, paging for you.
+		*
+		* Takes the same filters as `list` (it pages by reward cycle number). Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: PoxCyclesWalkParams): AsyncIterable<IndexPoxCycle>;
-		/** Fetch one reward cycle by number; 404 (unknown cycle, or below pox-5's
-		*  first reward cycle 141 — final PoX-4 history, not served here) → null. */
+		/**
+		* Get one reward cycle by number, or `null`.
+		*
+		* Resolves to `null` on 404: an unknown cycle, or one below pox-5's first
+		* reward cycle (141), whose PoX-4 history is final and not served here.
+		*/
 		get(rewardCycle: number): Promise<PoxCycleEnvelope | null>;
 	};
 }
@@ -2483,6 +2777,7 @@ type IndexPox5Event = {
 	/** The full decoded print tuple as JSON. */
 	data: unknown;
 };
+/** One page of PoX-5 events, with the cursor, tip, and reorgs. */
 type Pox5EventsEnvelope<TRow = IndexPox5Event> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -2495,6 +2790,7 @@ type Pox5EventsEnvelope<TRow = IndexPox5Event> = {
 type Pox5EventAlwaysFields = "cursor" | "block_height" | "topic";
 /** A Pox5Event row narrowed to the requested columns plus the always-present ones. */
 type Pox5EventFields<F extends keyof IndexPox5Event & string> = Pick<IndexPox5Event, (F | Pox5EventAlwaysFields) & keyof IndexPox5Event>;
+/** Column selection, paging, and filters for listing PoX-5 events. */
 type Pox5EventsListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -2516,21 +2812,34 @@ type Pox5EventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `Pox5EventsListParams` without `limit`, plus walk options. */
 type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & WalkOptions;
 type Pox5EventsConsumeParams<TTx = never> = Omit<Pox5EventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexPox5Event, Pox5EventsEnvelope, TTx>;
 /** `index.pox5` — decoded PoX-5 print events, the staking primitive from the
 *  epoch 4.0 hard fork onward (PoX-4's `index.stacking` stream ends there). */
 interface Pox5Resource {
 	events: {
-		/** Narrowing overload: `fields` shrinks the row type to exactly the
-		*  requested columns plus {@link Pox5EventAlwaysFields}. */
+		/**
+		* Read one page of decoded PoX-5 staking events.
+		*
+		* Filter by `topic`, `staker`, `signer`, `signerManager`, `bondIndex`, `rewardCycle`, and a height range. `confirmed: true` keeps only rows past the finality boundary. `fields` returns only those columns and narrows the row type; `cursor`, `block_height`, and `topic` always come back.
+		*/
 		list<const F extends keyof IndexPox5Event & string>(params: Pox5EventsListParams & {
 			fields: readonly F[];
 		}): Promise<Pox5EventsEnvelope<Pox5EventFields<F>>>;
 		list(params?: Pox5EventsListParams): Promise<Pox5EventsEnvelope>;
+		/**
+		* Iterate every PoX-5 event, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: Pox5EventsWalkParams): AsyncIterable<IndexPox5Event>;
-		/** Checkpointed sweep of the pox-5 print log — append-only across all
-		*  19 topics. See {@link IndexConsumeOptions}. */
+		/**
+		* Run a checkpointed, reorg-aware indexer over PoX-5 events.
+		*
+		* The pox-5 print log is append-only across all 19 topics. See
+		* {@link IndexConsumeOptions}.
+		*/
 		consume<TTx = never>(params: Pox5EventsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<{
@@ -2543,11 +2852,13 @@ interface Pox5Resource {
 /** A rune's `<block>:<tx>` id — the etch transaction's position, e.g. `840000:3`. */
 type RuneId = `${number}:${number}`;
 /**
-* A rune reference accepted by every Runes call: an id ({@link RuneId}) or a
-* name, with or without spacers, in any case — `DOG•GO•TO•THE•MOON`,
-* `dog.go.to.the.moon` and `doggotothemoon` all resolve to the same rune.
-* Typing every rune name is a no (178k runes and growing — a generated union
-* would be huge and stale on day one); `list({ search })` covers discovery.
+* A rune id or name, in any case, with or without spacers.
+*
+* `DOG•GO•TO•THE•MOON`, `dog.go.to.the.moon` and `doggotothemoon` all resolve
+* to the same rune.
+*
+* Typing every rune name is a no: 178k runes and growing, so a generated union
+* would be huge and stale on day one. `list({ search })` covers discovery.
 */
 type RuneRef = RuneId | (string & {});
 /** The Bitcoin chain tip a Runes read was served against — a separate clock
@@ -2592,8 +2903,11 @@ type IndexRuneTerms = {
 	offset_start: string | null;
 	offset_end: string | null;
 };
-/** One etched rune's full entry: identity, premine/mint/burn counters,
-*  computed supply, and mint terms. */
+/**
+* One etched rune: identity, counters, supply, and mint terms.
+*
+* Counters cover premine, mint, and burn; supply is computed.
+*/
 type IndexRuneEntry = IndexRuneRefSummary & {
 	/** Etch sequence number (u128 decimal string) — 0 is genesis. */
 	number: string;
@@ -2610,6 +2924,7 @@ type IndexRuneEntry = IndexRuneRefSummary & {
 	etched_tx_index: number;
 	terms: IndexRuneTerms | null;
 };
+/** One page of runes, with the cursor and Bitcoin tip. */
 type RunesEnvelope<TRow = IndexRuneEntry> = {
 	runes: TRow[];
 	next_cursor: string | null;
@@ -2620,6 +2935,7 @@ type RunesEnvelope<TRow = IndexRuneEntry> = {
 	/** Present only when Runes data is not configured on this instance. */
 	notes?: string;
 };
+/** Name search, sort order, and paging for listing runes. */
 type RunesListParams = {
 	/** Name prefix, spacers and case ignored (`dog` matches `DOG•GO•TO•THE•MOON`). */
 	search?: string;
@@ -2628,13 +2944,17 @@ type RunesListParams = {
 	cursor?: string | null;
 	limit?: number;
 };
+/** One rune and the Bitcoin tip. */
 type RuneEnvelope = {
 	rune: IndexRuneEntry;
 	tip: IndexBitcoinTip;
 };
 type IndexRuneEventKind = "rune_etch" | "rune_mint" | "rune_transfer" | "rune_burn";
-/** One etch/mint/transfer/burn event, with the rune's identity embedded so an
-*  activity feed never needs a second lookup to show a name. */
+/**
+* One rune etch, mint, transfer, or burn, with the rune's identity.
+*
+* The identity is embedded so an activity feed needs no second lookup to show a name.
+*/
 type IndexRuneEvent = {
 	cursor: string;
 	block_height: number;
@@ -2649,6 +2969,7 @@ type IndexRuneEvent = {
 	address: string | null;
 	rune: IndexRuneRefSummary;
 };
+/** One page of rune events, with the cursor, Bitcoin tip, and reorgs. */
 type RuneActivityEnvelope<TRow = IndexRuneEvent> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -2656,6 +2977,7 @@ type RuneActivityEnvelope<TRow = IndexRuneEvent> = {
 	reorgs: IndexBtcReorg[];
 	notes?: string;
 };
+/** Paging and height filters for listing rune events. */
 type RuneActivityListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2667,6 +2989,7 @@ type RuneActivityListParams = {
 	kind?: readonly IndexRuneEventKind[];
 	txid?: string;
 };
+/** `RuneActivityListParams` without `limit`, plus walk options. */
 type RuneActivityWalkParams = Omit<RuneActivityListParams, "limit"> & WalkOptions;
 /** A rune's balance on one unspent output, with the rune's identity embedded. */
 type IndexRuneBalance = {
@@ -2678,6 +3001,7 @@ type IndexRuneBalance = {
 	/** u128 decimal string. Never `Number()`. */
 	amount: string;
 };
+/** One page of rune balances, with the cursor and Bitcoin tip. */
 type RuneBalancesEnvelope<TRow = IndexRuneBalance> = {
 	balances: TRow[];
 	next_cursor: string | null;
@@ -2686,8 +3010,11 @@ type RuneBalancesEnvelope<TRow = IndexRuneBalance> = {
 	reorgs: IndexBtcReorg[];
 	notes?: string;
 };
-/** Exactly one of `address`/`outpoint` is required — enforced at the type
-*  level, not just at runtime. */
+/**
+* Rune balance filters; exactly one of `address` or `outpoint`.
+*
+* Enforced at the type level, not just at runtime.
+*/
 type RuneBalancesListParams = ({
 	address: string;
 	outpoint?: never;
@@ -2708,14 +3035,28 @@ interface RunesResource {
 	/** The rune catalog. `search` prefix-matches the name; `sort` is etch
 	*  order (default) or busiest-first. */
 	list(params?: RunesListParams): Promise<RunesEnvelope>;
-	/** One rune's full entry by id or name; `null` on 404 (no such rune, or
-	*  Runes isn't configured on this instance). */
+	/**
+	* Get one rune by id or name, or `null`.
+	*
+	* Resolves to `null` on 404: no such rune, or Runes isn't configured on
+	* this instance.
+	*/
 	get(rune: RuneRef): Promise<RuneEnvelope | null>;
 	/** Current per-outpoint rune balances by address or outpoint. */
 	balances(params: RuneBalancesListParams): Promise<RuneBalancesEnvelope>;
 	/** Etch/mint/transfer/burn events, cursor `<block_height>:<event_index>`. */
 	activity: {
+		/**
+		* Read one page of Rune etch, mint, transfer, and burn events.
+		*
+		* Filter by `rune` (an id or a name), `address`, `kind`, `txid`, and a height range. The cursor is `<block_height>:<event_index>`, and the envelope's tip is a Bitcoin tip. `notes` says so when Runes is not configured on the instance.
+		*/
 		list(params?: RuneActivityListParams): Promise<RuneActivityEnvelope>;
+		/**
+		* Iterate every Rune event, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: RuneActivityWalkParams): AsyncIterable<IndexRuneEvent>;
 	};
 }
@@ -2733,15 +3074,20 @@ interface FtTransfersResource {
 		fields: readonly F[];
 	}): Promise<FtTransfersEnvelope<FtTransferFields<F>>>;
 	(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
-	/** Narrowing overload: `fields` shrinks the row type to exactly the
-	*  requested columns plus {@link FtTransferAlwaysFields}. */
+	/**
+	* Read one page of fungible-token transfers, plus the cursor for the next.
+	*
+	* Filter by `contractId`, `assetIdentifier`, `sender`, `recipient`, and a height range. Filters are equality only: there is no amount filter. Pass `next_cursor` back as `cursor` to continue. `fields` returns only those columns and narrows the row type; `cursor`, `block_height`, and `event_type` always come back. `reorgs` on the envelope lists forks that overlap the page.
+	*/
 	list<const F extends keyof FtTransfer & string>(params: FtTransfersListParams & {
 		fields: readonly F[];
 	}): Promise<FtTransfersEnvelope<FtTransferFields<F>>>;
 	list(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
-	/** Narrowing overload, matching `list`: `walk` forwards `fields` to the
-	*  wire, so without this the yielded rows are stripped while the type
-	*  still promises every column. */
+	/**
+	* Iterate every fungible-token transfer, paging for you.
+	*
+	* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+	*/
 	walk<const F extends keyof FtTransfer & string>(params: FtTransfersWalkParams & {
 		fields: readonly F[];
 	}): AsyncIterable<FtTransferFields<F>>;
@@ -2755,13 +3101,20 @@ interface NftTransfersResource {
 		fields: readonly F[];
 	}): Promise<NftTransfersEnvelope<NftTransferFields<F>>>;
 	(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
-	/** Narrowing overload: `fields` shrinks the row type to exactly the
-	*  requested columns plus {@link NftTransferAlwaysFields}. */
+	/**
+	* Read one page of NFT transfers, plus the cursor for the next.
+	*
+	* Filter by `contractId`, `assetIdentifier`, `sender`, `recipient`, and a height range. Pass `next_cursor` back as `cursor` to continue. `fields` returns only those columns and narrows the row type; `cursor`, `block_height`, and `event_type` always come back.
+	*/
 	list<const F extends keyof NftTransfer & string>(params: NftTransfersListParams & {
 		fields: readonly F[];
 	}): Promise<NftTransfersEnvelope<NftTransferFields<F>>>;
 	list(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
-	/** Narrowing overload, matching `list` (see {@link FtTransfersResource}). */
+	/**
+	* Iterate every NFT transfer, paging for you.
+	*
+	* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+	*/
 	walk<const F extends keyof NftTransfer & string>(params: NftTransfersWalkParams & {
 		fields: readonly F[];
 	}): AsyncIterable<NftTransferFields<F>>;
@@ -2778,9 +3131,11 @@ interface IndexEventsResource {
 		fields: readonly F[];
 	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
-	/** Narrowing overload: `fields` shrinks the returned row type to exactly
-	*  the requested columns plus {@link IndexAlwaysFields}. `const F` means no
-	*  `as const` at the call site. */
+	/**
+	* Read one page of decoded events of one type.
+	*
+	* `eventType` is required: a decoded type (`ft_transfer`, `print`, ...) or a VM type (`nested_contract_call`, `map_set`, ...), and a literal narrows the row type. Scope with `contractId` (one id or up to 20) or `trait`, never both, plus `assetIdentifier`, `sender`, `recipient`, `functionName`, `caller`, `map`, `varName`, `txId`, and a height range. `txContext: true` joins the submitting transaction onto each event. `fields` returns only those columns and narrows the row type; it saves wire bytes but does not change what you are billed, since rows are metered, not columns.
+	*/
 	list<
 		T extends IndexEventType,
 		const F extends keyof IndexEventOf<T> & string
@@ -2788,9 +3143,11 @@ interface IndexEventsResource {
 		fields: readonly F[];
 	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	list<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
-	/** Narrowing overload, matching `list`: `walk` forwards `fields` to the
-	*  wire, so without this the yielded rows are stripped while the type
-	*  still promises every column. */
+	/**
+	* Iterate every decoded event of one type, paging for you.
+	*
+	* Takes the same filters as `list`, including `eventType`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+	*/
 	walk<
 		T extends IndexEventType,
 		const F extends keyof IndexEventOf<T> & string
@@ -2798,6 +3155,11 @@ interface IndexEventsResource {
 		fields: readonly F[];
 	}): AsyncIterable<IndexEventFields<T, F>>;
 	walk<T extends IndexEventType>(params: EventsWalkParams<T>): AsyncIterable<IndexEventOf<T>>;
+	/**
+	* Run a checkpointed, reorg-aware indexer over decoded events.
+	*
+	* Write your rows in `onBatch` and commit `ctx.cursor` in the same transaction; resume with `fromCursor`. Without `fromCursor` or `fromHeight` the API serves only its recent default window, so pass `fromHeight: 0` for a full backfill. A reorg at or below your checkpoint calls `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. `finalizedOnly` holds delivery to finalized rows, so no reorg handling is needed. `mode: "tail"` (default) keeps polling at the tip; `mode: "bounded"` returns on the first empty page. Resolves to `{ cursor, pages, emptyPolls }`.
+	*/
 	consume<
 		T extends IndexEventType,
 		TTx = never
@@ -2816,9 +3178,12 @@ type IndexEventTypeFilters = {
 	equality_filters?: string[];
 	required_non_null?: string[];
 };
-/** The `GET /v1/index` discovery doc — live endpoint + filter vocabulary.
-*  Shape is intentionally open (the server may add fields); the agent-relevant
-*  parts are the per-type filter rules. */
+/**
+* The `GET /v1/index` discovery doc: live endpoints and filter vocabulary.
+*
+* Shape is intentionally open (the server may add fields); the agent-relevant
+* parts are the per-type filter rules.
+*/
 type IndexDiscovery = {
 	event_type_filters?: Record<string, IndexEventTypeFilters>;
 	[key: string]: unknown;
@@ -2826,15 +3191,19 @@ type IndexDiscovery = {
 declare class Index extends BaseClient {
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
-	* Index discovery doc — the live vocabulary: every endpoint, each event type's
-	* columns, allowed/equality filters, and required-non-null fields. Read this to
-	* learn what's queryable (and which types accept `trait`) instead of hardcoding.
+	* Get the live vocabulary of what Index can query.
+	*
+	* The discovery doc lists every endpoint and each event type's columns,
+	* allowed and equality filters, and required-non-null fields. Read it to
+	* learn what's queryable (and which types accept `trait`) instead of
+	* hardcoding.
 	*/
 	discover(): Promise<IndexDiscovery>;
 	/**
-	* Empirical per-topic print payload schema for a contract — what topics it
-	* emits and each field's observed Clarity/TS/column types. Anonymous read;
-	* 404 → null.
+	* Get the print payload schema a contract actually emits.
+	*
+	* Lists the topics it emits and each field's observed Clarity, TS, and
+	* column types. Anonymous read; resolves to `null` on 404.
 	*/
 	printSchema(contractId: string): Promise<PrintSchemaResponse | null>;
 	/** Callable: `index.ftTransfers(params)` ≡ `index.ftTransfers.list(params)`. */
@@ -2845,8 +3214,23 @@ declare class Index extends BaseClient {
 	*  Callable: `index.events(params)` ≡ `index.events.list(params)`. */
 	readonly events: IndexEventsResource;
 	readonly contractCalls: {
+		/**
+		* Read one page of decoded contract calls.
+		*
+		* Filter by `contractId` (one id or up to 20) or `trait`, never both, plus `functionName`, `sender`, and a height range. Each row has the function name, arguments, result, and status. Pass `next_cursor` back as `cursor` to continue.
+		*/
 		list: (params?: ContractCallsListParams) => Promise<ContractCallsEnvelope>;
+		/**
+		* Iterate every decoded contract call, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: ContractCallsWalkParams) => AsyncIterable<IndexContractCall>;
+		/**
+		* Run a checkpointed, reorg-aware indexer over contract calls.
+		*
+		* Write your rows in `onBatch` and commit `ctx.cursor` in the same transaction; resume with `fromCursor`. Without `fromCursor` or `fromHeight` the API serves only its recent default window, so pass `fromHeight: 0` for a full backfill. A reorg at or below your checkpoint calls `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. `finalizedOnly` holds delivery to finalized rows, so no reorg handling is needed. `mode: "tail"` (default) keeps polling at the tip; `mode: "bounded"` returns on the first empty page. Resolves to `{ cursor, pages, emptyPolls }`. Calls already carry `sender` and `function_name`, so there is no `txContext`.
+		*/
 		consume: <TTx = never>(params: ContractCallsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}) => Promise<{
@@ -2857,49 +3241,125 @@ declare class Index extends BaseClient {
 	};
 	/** Canonical block-hash map — sync only the current canonical chain. */
 	readonly canonical: {
+		/**
+		* Read one page of the canonical block-hash map.
+		*
+		* Each row is a block's hash, its parent hash, and its burn-chain anchor. Compare it with your own tables to confirm you follow the current chain.
+		*/
 		list: (params?: CanonicalListParams) => Promise<CanonicalEnvelope>;
+		/**
+		* Iterate every canonical block hash, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: CanonicalWalkParams) => AsyncIterable<IndexCanonicalBlock>;
 	};
 	/** Exact MARF writes per canonical block (`/v1/index/state-writes`). */
 	readonly stateWrites: {
+		/**
+		* Read one page of the contract-state writes each block committed.
+		*
+		* Rows are the exact key and value writes, in the node's write order (`ordinal`), so you can see which key a transaction changed when events alone do not show it. Filter by `blockHeight` (excludes `fromHeight` and `toHeight`) or `contractId`. `txContext: true` joins the writing transaction. Rows exist only from the height your node first subscribed to state writes.
+		*/
 		list: (params?: StateWritesListParams) => Promise<StateWritesEnvelope>;
+		/**
+		* Iterate every state write, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: StateWritesWalkParams) => AsyncIterable<IndexStateWrite>;
 	};
 	/** Canonical blocks: paginated `list`/`walk`, plus `get` by height or hash
 	*  (resolves to null on 404). */
 	readonly blocks: {
+		/**
+		* Read one page of canonical blocks.
+		*
+		* Each block has its hash, parent hash, burn-chain anchor, and `block_time`. Filter by a height range.
+		*/
 		list: (params?: BlocksListParams) => Promise<BlocksEnvelope>;
+		/**
+		* Iterate every canonical block, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: BlocksWalkParams) => AsyncIterable<IndexBlock>;
+		/**
+		* Get one block by height or hash, or `null`.
+		*
+		* Resolves to `null` when no such block exists (404).
+		*/
 		get: (ref: string | number) => Promise<BlockEnvelope | null>;
 	};
 	/** Full transaction documents: paginated `list`/`walk`, plus `get` by tx_id
 	*  (resolves to null on 404). */
 	readonly transactions: {
-		/** Narrowing overload: `fields` shrinks the row type to exactly the
-		*  requested columns plus {@link TransactionAlwaysFields}. Declared as
-		*  an overloaded call signature because an arrow property cannot carry
-		*  overloads. */
+		/**
+		* Read one page of full transaction documents.
+		*
+		* Filter by `type`, `sender`, `contractId`, and a height range. Each document has the decoded post conditions and the payload for its `tx_type`; enrichment fields are null when the raw transaction cannot be decoded. `fields` returns only those columns and narrows the row type; `cursor`, `block_height`, and `tx_id` always come back.
+		*/
 		list: {
 			<const F extends keyof IndexTransaction & string>(params: TransactionsListParams & {
 				fields: readonly F[];
 			}): Promise<TransactionsEnvelope<TransactionFields<F>>>;
 			(params?: TransactionsListParams): Promise<TransactionsEnvelope>;
 		};
+		/**
+		* Iterate every transaction document, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: TransactionsWalkParams) => AsyncIterable<IndexTransaction>;
+		/**
+		* Get one transaction by id, or `null`.
+		*
+		* Resolves to `null` when the transaction is not found (404).
+		*/
 		get: (txId: string) => Promise<TransactionEnvelope | null>;
+		/**
+		* Get a transaction's inclusion proof, or `null`.
+		*
+		* The proof is the raw transaction, the Nakamoto block header, and the merkle path. Check it yourself with `verifyTransactionProof`; nothing in it needs to be trusted. Resolves to `null` on 404. A 503 (`PROOF_TX_SET_INCOMPLETE` or `PROOF_NODE_UNAVAILABLE`) throws an `ApiError`: the proof cannot be assembled on this deployment right now.
+		*/
 		getProof: (txId: string) => Promise<TransactionProof | null>;
 	};
 	/** Decoded PoX-4 stacking actions. Empty (with a `notes` hint) when the
 	*  platform's PoX-4 decoder is disabled. */
 	readonly stacking: {
+		/**
+		* Read one page of decoded PoX-4 stacking actions.
+		*
+		* One row per stacking contract call. Filter by `functionName`, `stacker`, `caller`, and a height range. The feed is empty, with a `notes` hint, when the instance's PoX-4 decoder is disabled. For the current PoX, use `pox5.events` and `pox.cycles`.
+		*/
 		list: (params?: StackingListParams) => Promise<StackingEnvelope>;
+		/**
+		* Iterate every PoX-4 stacking action, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: StackingWalkParams) => AsyncIterable<IndexStackingAction>;
 	};
 	/** Pending (unconfirmed) transactions: paginated `list`/`walk`, plus `get` by
 	*  tx_id (resolves to null when the tx has confirmed or dropped). */
 	readonly mempool: {
+		/**
+		* Read one page of pending, unconfirmed transactions.
+		*
+		* Filter by `sender`, `type`, `contractId`, and `functionName`. There is no height filter: rows carry `received_at` and a sequence cursor instead of a block position.
+		*/
 		list: (params?: MempoolListParams) => Promise<MempoolEnvelope>;
+		/**
+		* Iterate every pending transaction, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: MempoolWalkParams) => AsyncIterable<IndexMempoolTransaction>;
+		/**
+		* Get one pending transaction, or `null`.
+		*
+		* Resolves to `null` once the transaction has confirmed or dropped.
+		*/
 		get: (txId: string) => Promise<MempoolTransactionEnvelope | null>;
 	};
 	/** Decoded sBTC peg surface — the only productized decoded sBTC peg feed on
@@ -2976,6 +3436,7 @@ import { ReindexResponse, SubgraphAggregateParams, SubgraphAggregateResponse, Su
 import { DeploySubgraphRequest, DeploySubgraphResponse } from "@secondlayer/shared/schemas/subgraphs";
 import { SubgraphAgentSchema, SubgraphSpecOptions } from "@secondlayer/shared/subgraphs/spec";
 import { InferSubgraphClient } from "@secondlayer/subgraphs";
+/** A deployed subgraph's source code, handler bundle, and pin. */
 interface SubgraphSource {
 	name: string;
 	version: string;
@@ -3019,6 +3480,7 @@ interface SubgraphRowsEnvelope<T = unknown> {
 		blocks_behind: number;
 	};
 }
+/** A deployed subgraph's bundled sources, schema, and handler code. */
 interface BundleSubgraphResponse {
 	ok: true;
 	name: string;
@@ -3030,26 +3492,54 @@ interface BundleSubgraphResponse {
 	bundleSize: number;
 }
 declare class Subgraphs extends BaseClient {
+	/**
+	* List the subgraphs deployed to this instance.
+	*
+	* Each summary has the status, the last processed block against the chain tip, progress, `gapCount`, and an `integrity` flag.
+	*/
 	list(): Promise<{
 		data: SubgraphSummary[];
 	}>;
 	/**
-	* The subgraph's current state — health, sync position, tables. The verify
-	* step after a deploy, reindex, or backfill: poll it until `sync` catches
-	* the tip.
+	* Get a subgraph's health, sync position, and tables.
+	*
+	* The verify step after a deploy, reindex, or backfill: poll it until
+	* `sync` catches the tip.
 	*/
 	status(name: string): Promise<SubgraphDetail>;
+	/**
+	* Get a subgraph's OpenAPI spec.
+	*
+	* Describes the REST routes generated for each table. Pass `serverUrl` to set the server the spec advertises.
+	*/
 	openapi(name: string, options?: SubgraphSpecOptions): Promise<Record<string, unknown>>;
+	/**
+	* Get a subgraph's schema as JSON, shaped for agents.
+	*
+	* Per table: the endpoints, columns, indexes, which fields are sortable, selectable, searchable, or filterable, and a ready example query. Pass `serverUrl` to set the server the endpoints use.
+	*/
 	schema(name: string, options?: SubgraphSpecOptions): Promise<SubgraphAgentSchema>;
+	/**
+	* Get a subgraph's generated API docs as Markdown text.
+	*
+	* Pass `serverUrl` to set the server the examples use.
+	*/
 	markdown(name: string, options?: SubgraphSpecOptions): Promise<string>;
 	/**
-	* Reindex always drops and rebuilds the whole subgraph, so it takes no
+	* Rebuild a subgraph from scratch.
+	*
+	* A reindex always drops and rebuilds the whole subgraph, so it takes no
 	* block range; the API rejects one with `REINDEX_RANGE_NOT_SUPPORTED`.
 	* Use {@link backfill} to process a specific range. While a reindex or
 	* backfill is already running the API answers 409 with code
 	* `OPERATION_IN_PROGRESS`; poll {@link operations} until it finishes.
 	*/
 	reindex(name: string): Promise<ReindexResponse>;
+	/**
+	* Stop a running reindex or backfill.
+	*
+	* Requests the cancel and resolves with the `operationId` and a `cancel_requested` status. Poll {@link getOperation} until `status` is terminal. Throws a 404 with code `NO_OPERATION` when nothing is running.
+	*/
 	stop(name: string): Promise<{
 		message: string;
 		operationId?: string;
@@ -3061,19 +3551,31 @@ declare class Subgraphs extends BaseClient {
 		fromBlock: number;
 		toBlock: number;
 	}): Promise<ReindexResponse>;
+	/**
+	* List the block ranges a subgraph is missing.
+	*
+	* Each gap has its `start`, `end`, `size`, `reason`, and when it was detected and resolved. `resolved` filters to resolved or open gaps; page with `limit` and `offset`. `meta` reports the total gap count and total missing blocks.
+	*/
 	gaps(name: string, opts?: {
 		limit?: number;
 		offset?: number;
 		resolved?: boolean;
 	}): Promise<SubgraphGapsResponse>;
+	/**
+	* Delete a subgraph and its tables.
+	*
+	* Permanent. The API cancels any running reindex or backfill first, waits up to 5 seconds for it to stop, then drops the subgraph's tables and registry entry. `force: true` is sent as `?force=true`.
+	*/
 	delete(name: string, options?: {
 		force?: boolean;
 	}): Promise<{
 		message: string;
 	}>;
 	/**
-	* Open /v1 read: cursor-paginated rows. Anon works on an open instance;
-	* pass an apiKey on the client where reads are closed. `next_cursor` is set
+	* Read a table's rows, one cursor page at a time.
+	*
+	* Anon works on an open instance; pass an apiKey on the client where reads
+	* are closed. `next_cursor` is set
 	* on every page that returned rows and is `null` only on an empty page, so a
 	* poller tails with `cursor = page.next_cursor ?? cursor`. A paging loop
 	* ends on an empty page (or one shorter than `limit`).
@@ -3085,13 +3587,20 @@ declare class Subgraphs extends BaseClient {
 	operations(name: string): Promise<{
 		operations: SubgraphOperationStatus[];
 	}>;
-	/** Status of a single operation (poll the `operationId` returned by
-	*  reindex/backfill/stop until `status` is terminal). */
+	/** Get the status of one reindex, backfill, or stop operation.
+	*
+	*  Poll the `operationId` returned by `reindex`, `backfill`, or `stop`
+	*  until `status` is terminal. */
 	getOperation(name: string, operationId: string): Promise<SubgraphOperationStatus>;
 	/** Create or update a subgraph. A deploy that needs a rebuild queues one;
 	*  if a reindex or backfill is already running the API answers 409 with
 	*  code `OPERATION_IN_PROGRESS` (an `ApiError`, not a dedicated class). */
 	deploy(data: DeploySubgraphRequest): Promise<DeploySubgraphResponse>;
+	/**
+	* Get a deployed subgraph's source.
+	*
+	* Returns `sourceCode`, the bundled `handlerCode` the runtime executes, and the `pin` hash of what you deployed. `handlerCode` and `pin` are `null` for local deploys. A subgraph deployed before source was captured returns `sourceCode: null` and `readOnly: true` with a `reason`; redeploy it to capture the source.
+	*/
 	getSource(name: string): Promise<SubgraphSource>;
 	/**
 	* Bundle a TypeScript subgraph source on the server. Used by the web chat
@@ -3100,13 +3609,15 @@ declare class Subgraphs extends BaseClient {
 	bundle(data: {
 		code: string;
 	}): Promise<BundleSubgraphResponse>;
-	/** Open /v1 read: exact row count for a filtered set. Same auth posture as
-	*  {@link rows}. */
+	/** Count the rows in a table that match a filter.
+	*
+	*  The count is exact. Same auth posture as {@link rows}. */
 	count(name: string, table: string, params?: Pick<SubgraphQueryParams, "filters">): Promise<{
 		count: number;
 	}>;
-	/** Open /v1 read: scalar aggregates over a filtered set. Same auth posture
-	*  as {@link rows}. */
+	/** Compute scalar aggregates over a table's matching rows.
+	*
+	*  Same auth posture as {@link rows}. */
 	aggregate(name: string, table: string, params?: SubgraphAggregateParams): Promise<SubgraphAggregateResponse>;
 	/**
 	* Returns a typed client for a subgraph defined with `defineSubgraph()`.
@@ -3139,37 +3650,93 @@ import { CreateWebhookRequest, CreateWebhookResponse, DeadRow, DeliveryRow, Repl
 import { ChainTrigger, ChainTriggerType, CreateWebhookRequest as CreateWebhookRequest2, CreateWebhookResponse as CreateWebhookResponse2, DeadRow as DeadRow2, DeliveryRow as DeliveryRow2, ReplayResult as ReplayResult2, RotateSecretResponse as RotateSecretResponse2, WebhookActivity as WebhookActivity2, WebhookActivityHour, WebhookAuth, WebhookDeliveryDetail as WebhookDeliveryDetail2, WebhookDetail as WebhookDetail2, WebhookFormat, WebhookKind, WebhookStatus, WebhookSummary as WebhookSummary2, WebhookTestResult as WebhookTestResult2, UpdateWebhookRequest as UpdateWebhookRequest2 } from "@secondlayer/shared/schemas/webhooks";
 import { trigger } from "@secondlayer/shared/schemas/webhooks";
 declare class Webhooks extends BaseClient {
+	/**
+	* List your webhooks.
+	*
+	* Each summary has the status, format, URL, last delivery and last success, and the circuit breaker state (`circuitFailures`, `circuitOpenedAt`).
+	*/
 	list(): Promise<{
 		data: WebhookSummary[];
 	}>;
+	/**
+	* Get one webhook's full configuration.
+	*
+	* Adds the triggers, the receiver's auth (redacted to header names and whether a secret is set), the retry and timeout limits, `lastError`, and a `warning` when this instance's trigger evaluator is not running.
+	*/
 	get(id: string): Promise<WebhookDetail>;
+	/**
+	* Create a webhook that POSTs chain events to your URL.
+	*
+	* Takes a `name`, a `url`, and `triggers` built with `trigger.*`; each trigger is validated before anything is provisioned, and an invalid one is a 400. The signing secret comes back once in `signingSecret`, so store it. A webhook starts at the chain tip and never backfills: use {@link replay} for history. Hosted accounts cap `maxRetries` at 7 and `timeoutMs` at 30000.
+	*/
 	create(input: CreateWebhookRequest): Promise<CreateWebhookResponse>;
+	/**
+	* Change a webhook's name, URL, format, auth, or delivery limits.
+	*
+	* Send only the fields to change: `name`, `url`, `format`, `authConfig`, `maxRetries`, `timeoutMs`, `concurrency`. Triggers are not part of an update. Resolves to the updated webhook.
+	*/
 	update(id: string, patch: UpdateWebhookRequest): Promise<WebhookDetail>;
+	/**
+	* Stop deliveries without deleting the webhook.
+	*
+	* Resolves to the updated webhook. {@link resume} turns it back on.
+	*/
 	pause(id: string): Promise<WebhookDetail>;
+	/**
+	* Start delivering again after a pause.
+	*
+	* Also clears a circuit-breaker pause, which happens after 20 straight failed deliveries. Resolves to the updated webhook.
+	*/
 	resume(id: string): Promise<WebhookDetail>;
+	/**
+	* Delete a webhook.
+	*
+	* Resolves to `{ ok: true }`. Throws a 404 when the webhook does not exist.
+	*/
 	delete(id: string): Promise<{
 		ok: true;
 	}>;
+	/**
+	* Issue a new signing secret.
+	*
+	* The new secret comes back once in `signingSecret`. Update the receiver that calls `verifyWebhookSignature` with it: deliveries are signed with the new secret from now on.
+	*/
 	rotateSecret(id: string): Promise<RotateSecretResponse>;
-	/** Send a one-off test webhook to the webhook's URL (built for its
-	*  format, SSRF-guarded). Logged as a delivery row, visible via deliveries. */
+	/** Send a one-off test delivery to a webhook's URL.
+	*
+	*  Built for the webhook's format and SSRF-guarded. Logged as a delivery
+	*  row, visible via `deliveries`. */
 	test(id: string): Promise<WebhookTestResult>;
 	/** The last 100 delivery attempts, newest first. The server caps the window;
 	*  there is nothing to page. */
 	deliveries(id: string): Promise<{
 		data: DeliveryRow[];
 	}>;
-	/** Hourly delivered/waiting/gave-up counts for the last 7 days, plus the
-	*  current queue depth — the events chart on the detail page. */
+	/** Get a webhook's hourly delivery counts for the last 7 days.
+	*
+	*  Each hour has delivered, waiting, and gave-up counts, plus the current
+	*  queue depth. This is the events chart on the detail page. */
 	activity(id: string): Promise<WebhookActivity>;
-	/** One delivery attempt with its outbox context (payload, response
-	*  headers) — the delivery card on the detail page. */
+	/** Get one delivery attempt with its payload and response.
+	*
+	*  Includes the outbox context (payload, response headers). This is the
+	*  delivery card on the detail page. */
 	delivery(id: string, deliveryId: string): Promise<WebhookDeliveryDetail>;
+	/**
+	* Re-deliver historical events over an existing webhook.
+	*
+	* Pass `fromBlock` and `toBlock`; the range is capped at 100,000 blocks. A replay is historical only and never moves the live cursor. It is idempotent: the same range twice is a no-op, so pass any string as `force` to re-deliver it. Replays carry `is_replay` and use the standard `chain.{type}.apply` envelope. Resolves to `replayId`, `enqueuedCount`, and `scannedCount`. A second replay while one is running is a 409. `sbtc_withdrawal_swept_confirmed` is forward-only and never replayed. Hosted accounts get 5 replays an hour.
+	*/
 	replay(id: string, range: {
 		fromBlock: number;
 		toBlock: number;
 		force?: string;
 	}): Promise<ReplayResult>;
+	/**
+	* List the events a webhook gave up delivering.
+	*
+	* Returns up to 100 dead-lettered events, newest failure first. Each row's `id` is what {@link requeue} takes.
+	*/
 	dead(id: string): Promise<{
 		data: DeadRow[];
 	}>;
@@ -3208,10 +3775,11 @@ interface ContextField<T> {
 	error?: ContextFieldError;
 }
 /**
-* A point-in-time orientation snapshot for an agent: the live tips and what
-* this instance holds. Every field is a {@link ContextField}, so a missing
-* value says why it is missing (API unreachable, token rejected, index still
-* catching up) instead of a bare `null`. `context()` itself never throws.
+* A point-in-time orientation snapshot: live tips and what this instance holds.
+*
+* Every field is a `ContextField`, so a missing value says why it is missing
+* (API unreachable, token rejected, index still catching up) instead of a bare
+* `null`. `context()` itself never throws.
 */
 interface ContextSnapshot {
 	/** Token identity from `/api/accounts/me`. A self-hosted instance has no
@@ -3243,8 +3811,12 @@ declare class SecondLayer extends BaseClient {
 	readonly instance: InstanceClient;
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
-	* Up to 10 public reads in one round trip (`POST /v1/batch`). Each item
-	* is authorized on its own; the client's bearer token applies to every item.
+	* Run up to 10 public reads in one round trip (`POST /v1/batch`).
+	*
+	* Each item is authorized on its own; the client's bearer token applies to
+	* every item. Results come back in order as `{ path, status, body }`. Only
+	* paths under `/v1/index/`, `/v1/subgraphs`, `/v1/streams/`, and
+	* `/v1/contracts` are allowed; anything else is a per-item 400.
 	*/
 	batch(requests: Array<{
 		path: string;
@@ -3257,10 +3829,12 @@ declare class SecondLayer extends BaseClient {
 		}>;
 	}>;
 	/**
-	* Assemble a {@link ContextSnapshot}: the same orientation an MCP agent
-	* reads from `secondlayer://context`, available to any SDK/CLI consumer.
-	* Reads run concurrently; a failed read lands as `{ value: null, error }`
-	* on its field rather than rejecting the whole snapshot.
+	* Get a one-call snapshot of your account and instance.
+	*
+	* Returns a {@link ContextSnapshot}: the same orientation an MCP agent reads
+	* from `secondlayer://context`, available to any SDK or CLI consumer. Reads
+	* run concurrently; a failed read lands as `{ value: null, error }` on its
+	* field rather than rejecting the whole snapshot.
 	*/
 	context(): Promise<ContextSnapshot>;
 }
@@ -3291,7 +3865,7 @@ import { DeadRow as DeadRow3, DeliveryRow as DeliveryRow3, WebhookDetail as Webh
 * dashboard's webhook detail page. Moved out of the CLI (unchanged behavior)
 * so the web can build the same judgment without printing CLI-command text.
 *
-* Plan 068 adds five deterministic, numbers-only detectors on top of the
+* Five deterministic, numbers-only detectors sit on top of the
 * existing flag checks: no model, no history beyond the deliveries window
 * already fetched. Thresholds are named constants below, conservative on
 * purpose — a wrong insight costs more trust than a missed one.