@secondlayer/sdk 14.5.1 → 15.0.1

package/dist/subgraphs/index.d.ts

@@ -125,6 +125,7 @@ interface SubgraphOperationStatus {
 /** /v1 cursor envelope for subgraph table reads. */
 interface SubgraphRowsEnvelope<T = unknown> {
 	rows: T[];
+	/** Set on every page that returned rows; `null` only on an empty page. */
 	next_cursor: string | null;
 	tip: {
 		block_height: number;
@@ -143,26 +144,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;
@@ -174,20 +203,34 @@ 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. Resume with the
-	* returned `next_cursor`.
+	* 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`).
 	*/
 	rows<T = unknown>(name: string, table: string, params?: Omit<SubgraphQueryParams, "offset"> & {
 		cursor?: string;
@@ -196,13 +239,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
@@ -211,13 +261,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()`.
@@ -229,7 +281,8 @@ declare class Subgraphs extends BaseClient {
 	* const client = sl.subgraphs.typed(mySubgraph)
 	* const page = await client.transfers.findMany({ where: { sender: 'SP...' } })
 	* // page.rows: InferTableRow<typeof mySubgraph.schema.transfers>[]
-	* // page.nextCursor: string | null — pass back as `cursor` to resume
+	* // page.nextCursor: set whenever rows came back, null on an empty page.
+	* // Tail new rows: cursor = page.nextCursor ?? cursor
 	* ```
 	*/
 	typed<T extends {
@@ -252,7 +305,17 @@ 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>;
 };
 type ArchiveVerifyInput = {
@@ -355,33 +418,83 @@ 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;
@@ -395,6 +508,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>;
 };
 /**
@@ -438,8 +556,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;
@@ -633,7 +753,7 @@ 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,
+/** `chain=bitcoin` tip — 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" })`. */
 type StreamsBitcoinTip = {
@@ -649,7 +769,7 @@ type StreamsCanonicalBlock = {
 	burn_block_hash: string | null;
 	is_canonical: true;
 };
-/** `chain=bitcoin` canonical block (plan 059) — no burn-chain fields. */
+/** `chain=bitcoin` canonical block — no burn-chain fields. */
 type StreamsBitcoinCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -732,8 +852,8 @@ type StreamsEventsListParamsCommon = {
 	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. */
@@ -753,7 +873,7 @@ type StreamsEventsStacksListParams = StreamsEventsListParamsCommon & {
 	filters?: StreamsFilterMap;
 };
 /**
-* `chain: "bitcoin"` (plan 059) — Runes events, own cursor space. `types` is
+* `chain: "bitcoin"` — 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`/
@@ -791,7 +911,7 @@ type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` (plan 059/061) — Runes events, tailed the same way as
+/** `chain: "bitcoin"` — 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
@@ -849,7 +969,7 @@ type StreamsEventsSubscribeStacksParams = StreamsEventsSubscribeCommon & {
 	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
 };
-/** `chain: "bitcoin"` (plan 059/061) — Runes events pushed live, on their own
+/** `chain: "bitcoin"` — Runes events pushed live, on their own
 *  cursor space. `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters`
 *  don't exist on this branch — they're Stacks-only. */
 type StreamsEventsSubscribeBitcoinParams = StreamsEventsSubscribeCommon & {
@@ -1058,7 +1178,7 @@ type StreamsEventsConsumeParams<
 	wake?: () => Promise<void>;
 };
 /**
-* `chain: "bitcoin"` (plan 059/061) — the checkpointed sweep over Runes
+* `chain: "bitcoin"` — 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
@@ -1136,7 +1256,7 @@ type StreamsConsumeStacksParams = StreamsConsumeCommon & {
 	*  event echoes the labels it matched. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` (plan 059/061) — Runes batches, own cursor space.
+/** `chain: "bitcoin"` — Runes batches, own cursor space.
 *  `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters` don't exist
 *  on this branch — they're Stacks-only. */
 type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
@@ -1239,38 +1359,43 @@ type StreamsDumps = {
 };
 type StreamsClient = {
 	/**
-	* Follow Streams as an async iterator of page batches.
+	* Read Streams page by page as an async iterator.
+	*
+	* Yields one {@link StreamsBatch} per events page, so each yield is exactly
+	* one API call. Empty pages are skipped; at the tip the iterator polls again
+	* every `intervalMs` (default 2000) until `signal` aborts.
 	*
-	* Yields one {@link StreamsBatch} per `GET /v1/streams/events` page — the
-	* existing envelope (`events`, `next_cursor` → `cursor`, `tip`, `reorgs`)
-	* with zero extra API calls. Batches are chosen over per-block groupings
-	* because the envelope is page-keyed, so every yield is exactly one fetch.
-	* Empty pages are skipped; at the tip the iterator re-polls every
-	* `intervalMs` (default 2000) until aborted via `signal`.
+	* Reorgs appear on `batch.reorgs`, but the cursor is not rewound for you.
+	* Use `events.consume` with `onReorg` when you need rollback.
 	*
-	* Reorgs are surfaced on the batch (`batch.reorgs`) but the cursor is not
-	* rewound automatically — use `events.consume` with `onReorg` for managed
-	* rollback semantics.
+	* A literal `types` array narrows every batch's event union to those types.
+	* `chain: "bitcoin"` batches carry Runes rows only, on the bitcoin tip shape.
 	*/
-	/** `chain: "bitcoin"` — batches carry Runes rows only, on the bitcoin tip
-	*  shape (plan 059/061). */
 	consume(params: StreamsConsumeBitcoinParams): AsyncIterableIterator<StreamsBatch<RuneStreamsEvent, StreamsBitcoinTip>>;
-	/** Narrowing overload: a literal `types` array narrows every batch's
-	*  event union to exactly those members. */
 	consume<const T extends readonly StreamsEventType[]>(params: StreamsConsumeStacksParams & {
 		types: T;
 	}): AsyncIterableIterator<StreamsBatch<StreamsEventOfTypes<T>>>;
 	consume(params?: StreamsConsumeParams): AsyncIterableIterator<StreamsBatch>;
 	events: {
-		/** `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
-		*  `event_index` = `ordinal`). Never `StreamsEvent`. Stacks-only —
-		*  `chain: "bitcoin"` has no `clock`. */
+		/**
+		* Read one page of chain events and the next cursor.
+		*
+		* Narrow with `types`, `notTypes`, `contractId`, `sender`, `recipient`,
+		* `assetIdentifier`, `fromHeight`/`toHeight`, or labelled `filters`.
+		* Filters match exactly, and an event type without a given field never
+		* matches it. Pass `next_cursor` back as `cursor` to continue. The
+		* envelope also carries the `tip` and any `reorgs`. To write the events
+		* somewhere with a checkpoint, use `events.consume` instead.
+		*
+		* A literal `types` array narrows every row to those event types.
+		* `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
+		* `event_index` = `ordinal`), never `StreamsEvent`; it is Stacks only.
+		* `chain: "bitcoin"` pages carry Runes rows only, on the bitcoin tip shape,
+		* and filter by `rune` or `address`.
+		*/
 		list(params: StreamsEventsStacksListParams & {
 			clock: "vm";
 		}): Promise<StreamsEventsEnvelope<VmStreamsEvent>>;
-		/** Narrowing overload, matching `consume`. Classic clock only —
-		*  `clock: "vm"` is overload 1, and a general `StreamsEventsListParams`
-		*  variable (clock unresolved) is the wire-union fallback. */
 		list<const T extends readonly StreamsEventType[]>(params: Omit<StreamsEventsStacksListParams, "clock" | "types" | "notTypes"> & {
 			types: T;
 			notTypes?: readonly StreamsEventType[];
@@ -1281,27 +1406,35 @@ type StreamsClient = {
 			notTypes?: readonly StreamsEventType[];
 			clock?: "classic";
 		}): Promise<StreamsEventsEnvelope>;
-		/** `chain: "bitcoin"` pages carry Runes rows only, on the bitcoin tip
-		*  shape (plan 059). */
 		list(params: StreamsEventsBitcoinListParams): Promise<StreamsEventsEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
-		/** Unresolved `chain`/`clock` on a general params variable: the wire union. */
 		list(params: StreamsEventsListParams): Promise<StreamsEventsEnvelope<StreamsWireEvent>>;
-		/** `chain: "bitcoin"` — Runes events for one transaction. */
+		/**
+		* Read every event a transaction emitted.
+		*
+		* Returns the events and the `tip`, with no `next_cursor`: one transaction
+		* is one response.
+		*
+		* `chain: "bitcoin"` returns the Runes events for one Bitcoin transaction.
+		*/
 		byTxId(txId: string, opts: {
 			chain: "bitcoin";
 		}): Promise<StreamsEventsListEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
 		byTxId(txId: string): Promise<StreamsEventsListEnvelope>;
 		/**
-		* Pull pages from Streams and call `onBatch` after each page.
+		* Run a checkpointed indexer that rewinds on reorgs.
 		*
-		* Use `consume` for indexers and ETL jobs that own checkpointing. Return
-		* the checkpoint cursor from `onBatch`. Default `mode: "tail"` keeps
-		* polling when caught up; `mode: "bounded"` exits on the first empty page.
-		* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
-		* stops it.
+		* Write your rows in `onBatch` and commit `ctx.cursor` in the same
+		* transaction; resume with `fromCursor`. Reorgs at or below your checkpoint
+		* call `onReorg`, then the loop re-reads from the fork point. Delivery is
+		* at-least-once, so keep writes idempotent. With a `sink`, the checkpoint
+		* and rollback are handled for you. `mode: "tail"` (default) keeps polling
+		* at the tip; `mode: "bounded"` returns on the first empty page. It also
+		* stops on `maxPages`, `maxEmptyPolls`, or `signal`. Pass `finalizedOnly`
+		* to skip reorg handling entirely.
+		*
+		* `chain: "bitcoin"` sweeps Runes events; see
+		* {@link StreamsEventsConsumeBitcoinParams}.
 		*/
-		/** `chain: "bitcoin"` — the checkpointed sweep over Runes events; see
-		*  {@link StreamsEventsConsumeBitcoinParams}. */
 		consume<TTx = never>(params: StreamsEventsConsumeBitcoinParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<StreamsEventsConsumeResult>;
@@ -1313,46 +1446,66 @@ type StreamsClient = {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Backfill from bulk dumps, then continue live from the dump→live seam in
-		* one call. Iterates finalized dump files (via `onDumpFile`) in block
-		* order, then tails live from the manifest's `latest_finalized_cursor`
-		* (exclusive input → no gap or duplicate at the seam). Requires
-		* `dumpsBaseUrl`.
+		* Backfill from bulk dumps, then continue live in one call.
+		*
+		* Hands each finalized dump file to `onDumpFile` in block order, then tails
+		* live from the manifest's `latest_finalized_cursor`, with no gap or
+		* duplicate at the seam. A file that straddles `from` is delivered whole,
+		* so skip the rows at or below it. Requires `dumpsBaseUrl`.
 		*/
 		replay(params: StreamsEventsReplayParams): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Follow Streams as an async iterator.
+		* Read events one at a time as an async iterator.
 		*
-		* Use `stream` for live processors and watch-style apps. It tails
-		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
-		* `maxEmptyPolls` stops it.
+		* For live processors and watch-style apps that keep their own state. It
+		* tails indefinitely and stops when `signal`, `maxPages`, or
+		* `maxEmptyPolls` ends it. There is no checkpoint or reorg handling; use
+		* `events.consume` for that.
+		*
+		* A literal `types` array narrows every event to those types.
+		* `chain: "bitcoin"` yields Runes events only.
 		*/
-		/** `chain: "bitcoin"` — Runes events only (plan 059/061). */
 		stream(params: StreamsEventsStreamBitcoinParams): AsyncIterable<RuneStreamsEvent>;
-		/** Narrowing overload, matching `consume`. */
 		stream<const T extends readonly StreamsEventType[]>(params: StreamsEventsStreamStacksParams & {
 			types: T;
 		}): AsyncIterable<StreamsEventOfTypes<T>>;
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>;
 		/**
-		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
-		* canonical event as the server pushes it (chain cadence, not poll-bounded),
-		* and verifies each frame's inline ed25519 signature when the client was
-		* created with `verify`. Returns an unsubscribe function whose `done`
-		* settles when the loop ends. Not reorg-aware: an event delivered then
-		* orphaned is never retracted. Durable writers use `consume()`.
+		* Get each new event pushed to `onEvent` as it lands.
+		*
+		* Reconnects from the last handled cursor after a transport error, and
+		* verifies each frame's ed25519 signature when the client has `verify` on.
+		* Returns an unsubscribe function whose `done` promise settles when the
+		* loop ends. Not reorg-aware: an event delivered and then orphaned is never
+		* retracted. Durable writers use `events.consume`.
+		*
+		* `chain: "bitcoin"` delivers Runes rows to `onEvent`.
 		*/
-		/** `chain: "bitcoin"` — `onEvent` receives Runes rows (plan 059/061). */
 		subscribe(params: StreamsEventsSubscribeBitcoinParams): StreamsSubscription;
 		subscribe(params: StreamsEventsSubscribeStacksParams): StreamsSubscription;
 	};
 	blocks: {
+		/**
+		* Read every event in one block, by height or hash.
+		*
+		* Returns the events and the `tip`, with no `next_cursor`.
+		*
+		* `chain: "bitcoin"` returns the Runes events in one Bitcoin block.
+		*/
 		events(heightOrHash: number | string, opts: {
 			chain: "bitcoin";
 		}): Promise<StreamsEventsListEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
 	};
 	reorgs: {
+		/**
+		* List chain reorgs since a cursor.
+		*
+		* `since` is required. Each reorg gives its `fork_point_height` and the
+		* orphaned range. Page with `next_since`.
+		*
+		* `chain: "bitcoin"` lists Bitcoin reorgs, on their own cursor space.
+		*/
 		list(params: StreamsReorgsListParams & {
 			chain: "bitcoin";
 		}): Promise<StreamsReorgsListEnvelope>;
@@ -1360,10 +1513,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>;
@@ -2364,15 +2534,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<{
@@ -2384,21 +2566,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<{
@@ -2407,7 +2611,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. */
@@ -2488,10 +2696,24 @@ 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>;
 	};
 }
@@ -2566,15 +2788,27 @@ type Pox5EventsConsumeParams<TTx = never> = Omit<Pox5EventsListParams, "cursor"
 *  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<{
@@ -2752,14 +2986,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>;
 	};
 }
@@ -2777,15 +3025,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>>;
@@ -2799,13 +3052,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>>;
@@ -2822,9 +3082,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
@@ -2832,9 +3094,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
@@ -2842,6 +3106,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
@@ -2870,15 +3139,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)`. */
@@ -2889,8 +3162,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<{
@@ -2901,49 +3189,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
@@ -3018,37 +3382,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[];
 	}>;
@@ -3118,8 +3538,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;
@@ -3132,10 +3556,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>;
 }