@secondlayer/sdk 15.0.0 → 15.0.2

package/dist/subgraphs/index.d.ts

@@ -90,6 +90,7 @@ declare abstract class BaseClient {
 	*  subclasses that stream a body call this directly and read it themselves. */
 	protected fetchResponse(method: string, path: string, body?: unknown, signal?: AbortSignal, extraHeaders?: Record<string, string>): Promise<Response>;
 }
+/** A deployed subgraph's source code, handler bundle, and pin. */
 interface SubgraphSource {
 	name: string;
 	version: string;
@@ -133,6 +134,7 @@ interface SubgraphRowsEnvelope<T = unknown> {
 		blocks_behind: number;
 	};
 }
+/** A deployed subgraph's bundled sources, schema, and handler code. */
 interface BundleSubgraphResponse {
 	ok: true;
 	name: string;
@@ -144,26 +146,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;
@@ -175,19 +205,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`).
@@ -199,13 +241,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
@@ -214,13 +263,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()`.
@@ -256,9 +307,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;
@@ -268,6 +330,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;
@@ -292,8 +355,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;
@@ -316,6 +382,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;
@@ -326,6 +393,7 @@ type LoadedArchive = {
 		reason?: string;
 	};
 };
+/** The price of an archive request, after any free allowance. */
 type ArchiveQuote = {
 	partitions: number;
 	bundles: number;
@@ -342,11 +410,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: {
@@ -355,37 +425,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;
@@ -399,6 +520,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>;
 };
 /**
@@ -411,6 +537,7 @@ type SecondLayerArchive = ArchiveClient & {
 */
 /** 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;
@@ -423,6 +550,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;
@@ -433,6 +561,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;
@@ -442,8 +571,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;
@@ -618,6 +749,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";
+/** The chain tip: latest block, Bitcoin anchor, and finality boundary. */
 type StreamsTip = {
 	block_height: number;
 	block_hash: string;
@@ -637,15 +769,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;
@@ -653,7 +789,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;
@@ -674,6 +810,7 @@ type StreamsReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** One page of events with the next cursor, tip, and reorgs. */
 type StreamsEventsEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
@@ -683,24 +820,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
@@ -730,14 +873,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. */
@@ -757,12 +901,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";
@@ -773,7 +918,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;
@@ -782,8 +929,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[];
@@ -795,11 +946,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[];
@@ -853,9 +1007,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[];
@@ -945,6 +1102,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,
@@ -1062,13 +1220,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";
@@ -1101,9 +1260,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,
@@ -1117,6 +1277,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;
@@ -1140,9 +1301,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[];
@@ -1153,11 +1317,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;
@@ -1212,6 +1378,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;
@@ -1243,38 +1410,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 `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`.
+	* 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.
 	*
-	* Reorgs are surfaced on the batch (`batch.reorgs`) but the cursor is not
-	* rewound automatically — use `events.consume` with `onReorg` for managed
-	* rollback semantics.
+	* Reorgs appear on `batch.reorgs`, but the cursor is not rewound for you.
+	* Use `events.consume` with `onReorg` when you need rollback.
+	*
+	* 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[];
@@ -1285,27 +1457,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>;
@@ -1317,46 +1497,66 @@ type StreamsClient = {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Backfill from bulk dumps, then continue live from the dump→live seam in
-		* one call. Iterates finalized dump files (via `onDumpFile`) in block
-		* order, then tails live from the manifest's `latest_finalized_cursor`
-		* (exclusive input → no gap or duplicate at the seam). Requires
-		* `dumpsBaseUrl`.
+		* Backfill from bulk dumps, then continue live in one call.
+		*
+		* Hands each finalized dump file to `onDumpFile` in block order, then tails
+		* live from the manifest's `latest_finalized_cursor`, with no gap or
+		* duplicate at the seam. A file that straddles `from` is delivered whole,
+		* so skip the rows at or below it. Requires `dumpsBaseUrl`.
 		*/
 		replay(params: StreamsEventsReplayParams): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Follow Streams as an async iterator.
+		* Read events one at a time as an async iterator.
+		*
+		* For live processors and watch-style apps that keep their own state. It
+		* tails indefinitely and stops when `signal`, `maxPages`, or
+		* `maxEmptyPolls` ends it. There is no checkpoint or reorg handling; use
+		* `events.consume` for that.
 		*
-		* Use `stream` for live processors and watch-style apps. It tails
-		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
-		* `maxEmptyPolls` stops it.
+		* A literal `types` array narrows every event to those types.
+		* `chain: "bitcoin"` yields Runes events only.
 		*/
-		/** `chain: "bitcoin"` — Runes events only (plan 059/061). */
 		stream(params: StreamsEventsStreamBitcoinParams): AsyncIterable<RuneStreamsEvent>;
-		/** Narrowing overload, matching `consume`. */
 		stream<const T extends readonly StreamsEventType[]>(params: StreamsEventsStreamStacksParams & {
 			types: T;
 		}): AsyncIterable<StreamsEventOfTypes<T>>;
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>;
 		/**
-		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
-		* canonical event as the server pushes it (chain cadence, not poll-bounded),
-		* and verifies each frame's inline ed25519 signature when the client was
-		* created with `verify`. Returns an unsubscribe function whose `done`
-		* settles when the loop ends. Not reorg-aware: an event delivered then
-		* orphaned is never retracted. Durable writers use `consume()`.
+		* Get each new event pushed to `onEvent` as it lands.
+		*
+		* Reconnects from the last handled cursor after a transport error, and
+		* verifies each frame's ed25519 signature when the client has `verify` on.
+		* Returns an unsubscribe function whose `done` promise settles when the
+		* loop ends. Not reorg-aware: an event delivered and then orphaned is never
+		* retracted. Durable writers use `events.consume`.
+		*
+		* `chain: "bitcoin"` delivers Runes rows to `onEvent`.
 		*/
-		/** `chain: "bitcoin"` — `onEvent` receives Runes rows (plan 059/061). */
 		subscribe(params: StreamsEventsSubscribeBitcoinParams): StreamsSubscription;
 		subscribe(params: StreamsEventsSubscribeStacksParams): StreamsSubscription;
 	};
 	blocks: {
+		/**
+		* Read every event in one block, by height or hash.
+		*
+		* Returns the events and the `tip`, with no `next_cursor`.
+		*
+		* `chain: "bitcoin"` returns the Runes events in one Bitcoin block.
+		*/
 		events(heightOrHash: number | string, opts: {
 			chain: "bitcoin";
 		}): Promise<StreamsEventsListEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
 	};
 	reorgs: {
+		/**
+		* List chain reorgs since a cursor.
+		*
+		* `since` is required. Each reorg gives its `fork_point_height` and the
+		* orphaned range. Page with `next_since`.
+		*
+		* `chain: "bitcoin"` lists Bitcoin reorgs, on their own cursor space.
+		*/
 		list(params: StreamsReorgsListParams & {
 			chain: "bitcoin";
 		}): Promise<StreamsReorgsListEnvelope>;
@@ -1364,10 +1564,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>;
@@ -1504,6 +1721,7 @@ type IndexReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** A decoded fungible-token transfer: sender, recipient, asset, amount. */
 type FtTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1518,6 +1736,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;
@@ -1529,6 +1748,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
@@ -1560,7 +1780,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;
@@ -1575,6 +1797,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;
@@ -1585,6 +1808,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)[];
@@ -1598,6 +1822,7 @@ type NftTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `NftTransfersListParams` without `limit`, plus walk options. */
 type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & WalkOptions;
 type IndexEventBase = {
 	cursor: string;
@@ -1618,6 +1843,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;
@@ -1625,6 +1851,7 @@ type IndexFtTransfer = IndexEventBase & {
 	recipient: string;
 	amount: string;
 };
+/** A non-fungible-token transfer event. */
 type IndexNftTransfer = IndexEventBase & {
 	event_type: "nft_transfer";
 	asset_identifier: string;
@@ -1632,6 +1859,7 @@ type IndexNftTransfer = IndexEventBase & {
 	recipient: string;
 	value: string;
 };
+/** An STX transfer event. */
 type IndexStxTransfer = IndexEventBase & {
 	event_type: "stx_transfer";
 	sender: string;
@@ -1639,16 +1867,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;
@@ -1657,30 +1888,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: {
@@ -1689,6 +1925,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;
@@ -1697,23 +1934,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;
@@ -1730,6 +1971,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>
@@ -1744,6 +1986,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;
@@ -1788,11 +2031,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;
@@ -1807,12 +2052,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;
@@ -1828,6 +2075,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
@@ -1841,11 +2089,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;
@@ -1853,6 +2103,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`. */
@@ -1877,12 +2128,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;
@@ -1896,6 +2149,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). */
@@ -1909,15 +2163,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;
@@ -1925,6 +2182,7 @@ type BlocksListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `BlocksListParams` without `limit`, plus walk options. */
 type BlocksWalkParams = Omit<BlocksListParams, "limit"> & WalkOptions;
 type IndexPostCondition = {
 	type: "stx";
@@ -2001,12 +2259,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;
@@ -2015,6 +2275,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
@@ -2031,6 +2292,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 = {
@@ -2057,6 +2319,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;
@@ -2065,6 +2328,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;
@@ -2075,6 +2339,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
@@ -2111,15 +2376,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;
@@ -2131,11 +2399,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;
@@ -2172,8 +2442,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;
@@ -2227,8 +2501,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;
@@ -2267,6 +2544,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;
@@ -2275,10 +2553,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;
@@ -2286,10 +2566,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;
@@ -2297,11 +2579,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;
@@ -2323,11 +2607,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
@@ -2348,7 +2634,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;
@@ -2361,6 +2649,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>;
@@ -2368,15 +2657,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<{
@@ -2388,21 +2689,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<{
@@ -2411,7 +2734,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. */
@@ -2468,6 +2795,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;
@@ -2476,6 +2804,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 & {
@@ -2483,19 +2812,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>;
 	};
 }
@@ -2531,6 +2876,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;
@@ -2543,6 +2889,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
@@ -2564,21 +2911,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<{
@@ -2591,11 +2951,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
@@ -2640,8 +3002,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;
@@ -2658,6 +3023,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;
@@ -2668,6 +3034,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;
@@ -2676,13 +3043,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;
@@ -2697,6 +3068,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;
@@ -2704,6 +3076,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;
@@ -2715,6 +3088,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 = {
@@ -2726,6 +3100,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;
@@ -2734,8 +3109,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;
@@ -2756,14 +3134,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>;
 	};
 }
@@ -2781,15 +3173,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>>;
@@ -2803,13 +3200,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>>;
@@ -2826,9 +3230,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
@@ -2836,9 +3242,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
@@ -2846,6 +3254,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
@@ -2864,9 +3277,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;
@@ -2874,15 +3290,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)`. */
@@ -2893,8 +3313,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<{
@@ -2905,49 +3340,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
@@ -3022,37 +3533,93 @@ declare class Index extends BaseClient {
 }
 import { CreateWebhookRequest, CreateWebhookResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, UpdateWebhookRequest, WebhookActivity, WebhookDeliveryDetail, WebhookDetail, WebhookSummary, WebhookTestResult } 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[];
 	}>;
@@ -3091,10 +3658,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
@@ -3122,8 +3690,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;
@@ -3136,10 +3708,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>;
 }