@secondlayer/sdk 15.0.0 → 15.0.1

package/dist/index.d.ts

@@ -4,7 +4,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 = {
@@ -107,33 +117,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;
@@ -147,6 +207,11 @@ type ArchiveClient = {
 };
 /** Hosted archive client plus instance `verify`. `status()` is still the public archive tree. */
 type SecondLayerArchive = ArchiveClient & {
+	/**
+	* Check your instance's data against a signed archive.
+	*
+	* Runs `POST /v1/archive/verify` on your instance: read-only, and it compares raw identity digests only (the deep semantic check is CLI-only). Resolves to `clean`, `diverged`, or `unanchored`; a failed signature is `unanchored`, never `clean`. Narrow the check with `fromBlock` and `toBlock`. Verification is free.
+	*/
 	verify(input: ArchiveVerifyInput): Promise<ArchiveVerifyResult>;
 };
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
@@ -311,8 +376,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;
@@ -552,7 +619,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 = {
@@ -568,7 +635,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;
@@ -651,8 +718,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. */
@@ -672,7 +739,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`/
@@ -710,7 +777,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
@@ -768,7 +835,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 & {
@@ -978,7 +1045,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
@@ -1056,7 +1123,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 & {
@@ -1160,38 +1227,43 @@ type StreamsDumps = {
 };
 type StreamsClient = {
 	/**
-	* Follow Streams as an async iterator of page batches.
+	* Read Streams page by page as an async iterator.
+	*
+	* Yields one {@link StreamsBatch} per events page, so each yield is exactly
+	* one API call. Empty pages are skipped; at the tip the iterator polls again
+	* every `intervalMs` (default 2000) until `signal` aborts.
 	*
-	* Yields one {@link StreamsBatch} per `GET /v1/streams/events` page — the
-	* existing envelope (`events`, `next_cursor` → `cursor`, `tip`, `reorgs`)
-	* with zero extra API calls. Batches are chosen over per-block groupings
-	* because the envelope is page-keyed, so every yield is exactly one fetch.
-	* Empty pages are skipped; at the tip the iterator re-polls every
-	* `intervalMs` (default 2000) until aborted via `signal`.
+	* Reorgs appear on `batch.reorgs`, but the cursor is not rewound for you.
+	* Use `events.consume` with `onReorg` when you need rollback.
 	*
-	* Reorgs are surfaced on the batch (`batch.reorgs`) but the cursor is not
-	* rewound automatically — use `events.consume` with `onReorg` for managed
-	* rollback semantics.
+	* A literal `types` array narrows every batch's event union to those types.
+	* `chain: "bitcoin"` batches carry Runes rows only, on the bitcoin tip shape.
 	*/
-	/** `chain: "bitcoin"` — batches carry Runes rows only, on the bitcoin tip
-	*  shape (plan 059/061). */
 	consume(params: StreamsConsumeBitcoinParams): AsyncIterableIterator<StreamsBatch<RuneStreamsEvent, StreamsBitcoinTip>>;
-	/** Narrowing overload: a literal `types` array narrows every batch's
-	*  event union to exactly those members. */
 	consume<const T extends readonly StreamsEventType[]>(params: StreamsConsumeStacksParams & {
 		types: T;
 	}): AsyncIterableIterator<StreamsBatch<StreamsEventOfTypes<T>>>;
 	consume(params?: StreamsConsumeParams): AsyncIterableIterator<StreamsBatch>;
 	events: {
-		/** `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
-		*  `event_index` = `ordinal`). Never `StreamsEvent`. Stacks-only —
-		*  `chain: "bitcoin"` has no `clock`. */
+		/**
+		* Read one page of chain events and the next cursor.
+		*
+		* Narrow with `types`, `notTypes`, `contractId`, `sender`, `recipient`,
+		* `assetIdentifier`, `fromHeight`/`toHeight`, or labelled `filters`.
+		* Filters match exactly, and an event type without a given field never
+		* matches it. Pass `next_cursor` back as `cursor` to continue. The
+		* envelope also carries the `tip` and any `reorgs`. To write the events
+		* somewhere with a checkpoint, use `events.consume` instead.
+		*
+		* A literal `types` array narrows every row to those event types.
+		* `clock: "vm"` pages carry vm rows only (a parallel vocabulary,
+		* `event_index` = `ordinal`), never `StreamsEvent`; it is Stacks only.
+		* `chain: "bitcoin"` pages carry Runes rows only, on the bitcoin tip shape,
+		* and filter by `rune` or `address`.
+		*/
 		list(params: StreamsEventsStacksListParams & {
 			clock: "vm";
 		}): Promise<StreamsEventsEnvelope<VmStreamsEvent>>;
-		/** Narrowing overload, matching `consume`. Classic clock only —
-		*  `clock: "vm"` is overload 1, and a general `StreamsEventsListParams`
-		*  variable (clock unresolved) is the wire-union fallback. */
 		list<const T extends readonly StreamsEventType[]>(params: Omit<StreamsEventsStacksListParams, "clock" | "types" | "notTypes"> & {
 			types: T;
 			notTypes?: readonly StreamsEventType[];
@@ -1202,27 +1274,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>;
@@ -1234,46 +1314,66 @@ type StreamsClient = {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Backfill from bulk dumps, then continue live from the dump→live seam in
-		* one call. Iterates finalized dump files (via `onDumpFile`) in block
-		* order, then tails live from the manifest's `latest_finalized_cursor`
-		* (exclusive input → no gap or duplicate at the seam). Requires
-		* `dumpsBaseUrl`.
+		* Backfill from bulk dumps, then continue live in one call.
+		*
+		* Hands each finalized dump file to `onDumpFile` in block order, then tails
+		* live from the manifest's `latest_finalized_cursor`, with no gap or
+		* duplicate at the seam. A file that straddles `from` is delivered whole,
+		* so skip the rows at or below it. Requires `dumpsBaseUrl`.
 		*/
 		replay(params: StreamsEventsReplayParams): Promise<StreamsEventsConsumeResult>;
 		/**
-		* Follow Streams as an async iterator.
+		* Read events one at a time as an async iterator.
 		*
-		* Use `stream` for live processors and watch-style apps. It tails
-		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
-		* `maxEmptyPolls` stops it.
+		* For live processors and watch-style apps that keep their own state. It
+		* tails indefinitely and stops when `signal`, `maxPages`, or
+		* `maxEmptyPolls` ends it. There is no checkpoint or reorg handling; use
+		* `events.consume` for that.
+		*
+		* A literal `types` array narrows every event to those types.
+		* `chain: "bitcoin"` yields Runes events only.
 		*/
-		/** `chain: "bitcoin"` — Runes events only (plan 059/061). */
 		stream(params: StreamsEventsStreamBitcoinParams): AsyncIterable<RuneStreamsEvent>;
-		/** Narrowing overload, matching `consume`. */
 		stream<const T extends readonly StreamsEventType[]>(params: StreamsEventsStreamStacksParams & {
 			types: T;
 		}): AsyncIterable<StreamsEventOfTypes<T>>;
 		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>;
 		/**
-		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
-		* canonical event as the server pushes it (chain cadence, not poll-bounded),
-		* and verifies each frame's inline ed25519 signature when the client was
-		* created with `verify`. Returns an unsubscribe function whose `done`
-		* settles when the loop ends. Not reorg-aware: an event delivered then
-		* orphaned is never retracted. Durable writers use `consume()`.
+		* Get each new event pushed to `onEvent` as it lands.
+		*
+		* Reconnects from the last handled cursor after a transport error, and
+		* verifies each frame's ed25519 signature when the client has `verify` on.
+		* Returns an unsubscribe function whose `done` promise settles when the
+		* loop ends. Not reorg-aware: an event delivered and then orphaned is never
+		* retracted. Durable writers use `events.consume`.
+		*
+		* `chain: "bitcoin"` delivers Runes rows to `onEvent`.
 		*/
-		/** `chain: "bitcoin"` — `onEvent` receives Runes rows (plan 059/061). */
 		subscribe(params: StreamsEventsSubscribeBitcoinParams): StreamsSubscription;
 		subscribe(params: StreamsEventsSubscribeStacksParams): StreamsSubscription;
 	};
 	blocks: {
+		/**
+		* Read every event in one block, by height or hash.
+		*
+		* Returns the events and the `tip`, with no `next_cursor`.
+		*
+		* `chain: "bitcoin"` returns the Runes events in one Bitcoin block.
+		*/
 		events(heightOrHash: number | string, opts: {
 			chain: "bitcoin";
 		}): Promise<StreamsEventsListEnvelope<RuneStreamsEvent, StreamsBitcoinTip>>;
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
 	};
 	reorgs: {
+		/**
+		* List chain reorgs since a cursor.
+		*
+		* `since` is required. Each reorg gives its `fork_point_height` and the
+		* orphaned range. Page with `next_since`.
+		*
+		* `chain: "bitcoin"` lists Bitcoin reorgs, on their own cursor space.
+		*/
 		list(params: StreamsReorgsListParams & {
 			chain: "bitcoin";
 		}): Promise<StreamsReorgsListEnvelope>;
@@ -1281,10 +1381,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>;
@@ -2320,15 +2437,27 @@ type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "curs
 *  events, scoreboard). The only productized decoded sBTC peg feed on Stacks. */
 interface SbtcResource {
 	deposits: {
-		/** Narrowing overload: `fields` shrinks the row type to exactly the
-		*  requested columns plus {@link SbtcDepositAlwaysFields}. */
+		/**
+		* Read one page of completed sBTC deposits.
+		*
+		* Filter by `sender`, `bitcoinTxid`, and a height range. `confirmed: true` keeps only deposits past the finality boundary. `fields` returns only those columns and narrows the row type; `cursor` and `block_height` always come back.
+		*/
 		list<const F extends keyof IndexSbtcDeposit & string>(params: SbtcDepositsListParams & {
 			fields: readonly F[];
 		}): Promise<SbtcDepositsEnvelope<SbtcDepositFields<F>>>;
 		list(params?: SbtcDepositsListParams): Promise<SbtcDepositsEnvelope>;
+		/**
+		* Iterate every completed sBTC deposit, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: SbtcDepositsWalkParams): AsyncIterable<IndexSbtcDeposit>;
-		/** Checkpointed sweep of completed deposits — append-only, so safe to
-		*  mirror. See {@link IndexConsumeOptions}. */
+		/**
+		* Run a checkpointed, reorg-aware indexer over completed deposits.
+		*
+		* Deposits are append-only, so they are safe to mirror. See
+		* {@link IndexConsumeOptions}.
+		*/
 		consume<TTx = never>(params: SbtcDepositsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<{
@@ -2340,21 +2469,43 @@ interface SbtcResource {
 		get(bitcoinTxid: string): Promise<SbtcDepositEnvelope | null>;
 	};
 	withdrawals: {
-		/** Narrowing overload: `fields` shrinks the row type to exactly the
-		*  requested columns plus {@link SbtcWithdrawalAlwaysFields}. */
+		/**
+		* Read one page of sBTC withdrawals, each with its current status.
+		*
+		* Filter by `status` (`REQUESTED`, `ACCEPTED`, `REJECTED`), `sender`, `requestId`, `settlementConfirmed`, and a height range. A row changes as the peg-out moves along, which is why withdrawals have no `consume`. `fields` returns only those columns and narrows the row type; `cursor` and `request_id` always come back.
+		*/
 		list<const F extends keyof IndexSbtcWithdrawal & string>(params: SbtcWithdrawalsListParams & {
 			fields: readonly F[];
 		}): Promise<SbtcWithdrawalsEnvelope<SbtcWithdrawalFields<F>>>;
 		list(params?: SbtcWithdrawalsListParams): Promise<SbtcWithdrawalsEnvelope>;
+		/**
+		* Iterate every sBTC withdrawal, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: SbtcWithdrawalsWalkParams): AsyncIterable<IndexSbtcWithdrawal>;
 		/** Fetch a withdrawal's full lifecycle by request id; 404 → null. */
 		get(requestId: number): Promise<SbtcWithdrawalEnvelope | null>;
 	};
 	events: {
+		/**
+		* Read one page of the raw sBTC peg event log.
+		*
+		* Filter by `topic`, `sender`, `requestId`, `bitcoinTxid`, and a height range. `confirmed: true` keeps only events past the finality boundary.
+		*/
 		list(params?: SbtcEventsListParams): Promise<SbtcEventsEnvelope>;
+		/**
+		* Iterate every sBTC peg event, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: SbtcEventsWalkParams): AsyncIterable<IndexSbtcEvent>;
-		/** Checkpointed sweep of the raw peg event log — append-only across all
-		*  six topics. See {@link IndexConsumeOptions}. */
+		/**
+		* Run a checkpointed, reorg-aware indexer over the raw peg event log.
+		*
+		* The log is append-only across all six topics. See
+		* {@link IndexConsumeOptions}.
+		*/
 		consume<TTx = never>(params: SbtcEventsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}): Promise<{
@@ -2363,7 +2514,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. */
@@ -2444,10 +2599,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>;
 	};
 }
@@ -2522,15 +2691,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<{
@@ -2708,14 +2889,28 @@ interface RunesResource {
 	/** The rune catalog. `search` prefix-matches the name; `sort` is etch
 	*  order (default) or busiest-first. */
 	list(params?: RunesListParams): Promise<RunesEnvelope>;
-	/** One rune's full entry by id or name; `null` on 404 (no such rune, or
-	*  Runes isn't configured on this instance). */
+	/**
+	* Get one rune by id or name, or `null`.
+	*
+	* Resolves to `null` on 404: no such rune, or Runes isn't configured on
+	* this instance.
+	*/
 	get(rune: RuneRef): Promise<RuneEnvelope | null>;
 	/** Current per-outpoint rune balances by address or outpoint. */
 	balances(params: RuneBalancesListParams): Promise<RuneBalancesEnvelope>;
 	/** Etch/mint/transfer/burn events, cursor `<block_height>:<event_index>`. */
 	activity: {
+		/**
+		* Read one page of Rune etch, mint, transfer, and burn events.
+		*
+		* Filter by `rune` (an id or a name), `address`, `kind`, `txid`, and a height range. The cursor is `<block_height>:<event_index>`, and the envelope's tip is a Bitcoin tip. `notes` says so when Runes is not configured on the instance.
+		*/
 		list(params?: RuneActivityListParams): Promise<RuneActivityEnvelope>;
+		/**
+		* Iterate every Rune event, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk(params?: RuneActivityWalkParams): AsyncIterable<IndexRuneEvent>;
 	};
 }
@@ -2733,15 +2928,20 @@ interface FtTransfersResource {
 		fields: readonly F[];
 	}): Promise<FtTransfersEnvelope<FtTransferFields<F>>>;
 	(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
-	/** Narrowing overload: `fields` shrinks the row type to exactly the
-	*  requested columns plus {@link FtTransferAlwaysFields}. */
+	/**
+	* Read one page of fungible-token transfers, plus the cursor for the next.
+	*
+	* Filter by `contractId`, `assetIdentifier`, `sender`, `recipient`, and a height range. Filters are equality only: there is no amount filter. Pass `next_cursor` back as `cursor` to continue. `fields` returns only those columns and narrows the row type; `cursor`, `block_height`, and `event_type` always come back. `reorgs` on the envelope lists forks that overlap the page.
+	*/
 	list<const F extends keyof FtTransfer & string>(params: FtTransfersListParams & {
 		fields: readonly F[];
 	}): Promise<FtTransfersEnvelope<FtTransferFields<F>>>;
 	list(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
-	/** Narrowing overload, matching `list`: `walk` forwards `fields` to the
-	*  wire, so without this the yielded rows are stripped while the type
-	*  still promises every column. */
+	/**
+	* Iterate every fungible-token transfer, paging for you.
+	*
+	* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+	*/
 	walk<const F extends keyof FtTransfer & string>(params: FtTransfersWalkParams & {
 		fields: readonly F[];
 	}): AsyncIterable<FtTransferFields<F>>;
@@ -2755,13 +2955,20 @@ interface NftTransfersResource {
 		fields: readonly F[];
 	}): Promise<NftTransfersEnvelope<NftTransferFields<F>>>;
 	(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
-	/** Narrowing overload: `fields` shrinks the row type to exactly the
-	*  requested columns plus {@link NftTransferAlwaysFields}. */
+	/**
+	* Read one page of NFT transfers, plus the cursor for the next.
+	*
+	* Filter by `contractId`, `assetIdentifier`, `sender`, `recipient`, and a height range. Pass `next_cursor` back as `cursor` to continue. `fields` returns only those columns and narrows the row type; `cursor`, `block_height`, and `event_type` always come back.
+	*/
 	list<const F extends keyof NftTransfer & string>(params: NftTransfersListParams & {
 		fields: readonly F[];
 	}): Promise<NftTransfersEnvelope<NftTransferFields<F>>>;
 	list(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
-	/** Narrowing overload, matching `list` (see {@link FtTransfersResource}). */
+	/**
+	* Iterate every NFT transfer, paging for you.
+	*
+	* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+	*/
 	walk<const F extends keyof NftTransfer & string>(params: NftTransfersWalkParams & {
 		fields: readonly F[];
 	}): AsyncIterable<NftTransferFields<F>>;
@@ -2778,9 +2985,11 @@ interface IndexEventsResource {
 		fields: readonly F[];
 	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
-	/** Narrowing overload: `fields` shrinks the returned row type to exactly
-	*  the requested columns plus {@link IndexAlwaysFields}. `const F` means no
-	*  `as const` at the call site. */
+	/**
+	* Read one page of decoded events of one type.
+	*
+	* `eventType` is required: a decoded type (`ft_transfer`, `print`, ...) or a VM type (`nested_contract_call`, `map_set`, ...), and a literal narrows the row type. Scope with `contractId` (one id or up to 20) or `trait`, never both, plus `assetIdentifier`, `sender`, `recipient`, `functionName`, `caller`, `map`, `varName`, `txId`, and a height range. `txContext: true` joins the submitting transaction onto each event. `fields` returns only those columns and narrows the row type; it saves wire bytes but does not change what you are billed, since rows are metered, not columns.
+	*/
 	list<
 		T extends IndexEventType,
 		const F extends keyof IndexEventOf<T> & string
@@ -2788,9 +2997,11 @@ interface IndexEventsResource {
 		fields: readonly F[];
 	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	list<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
-	/** Narrowing overload, matching `list`: `walk` forwards `fields` to the
-	*  wire, so without this the yielded rows are stripped while the type
-	*  still promises every column. */
+	/**
+	* Iterate every decoded event of one type, paging for you.
+	*
+	* Takes the same filters as `list`, including `eventType`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+	*/
 	walk<
 		T extends IndexEventType,
 		const F extends keyof IndexEventOf<T> & string
@@ -2798,6 +3009,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
@@ -2826,15 +3042,19 @@ type IndexDiscovery = {
 declare class Index extends BaseClient {
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
-	* Index discovery doc — the live vocabulary: every endpoint, each event type's
-	* columns, allowed/equality filters, and required-non-null fields. Read this to
-	* learn what's queryable (and which types accept `trait`) instead of hardcoding.
+	* Get the live vocabulary of what Index can query.
+	*
+	* The discovery doc lists every endpoint and each event type's columns,
+	* allowed and equality filters, and required-non-null fields. Read it to
+	* learn what's queryable (and which types accept `trait`) instead of
+	* hardcoding.
 	*/
 	discover(): Promise<IndexDiscovery>;
 	/**
-	* Empirical per-topic print payload schema for a contract — what topics it
-	* emits and each field's observed Clarity/TS/column types. Anonymous read;
-	* 404 → null.
+	* Get the print payload schema a contract actually emits.
+	*
+	* Lists the topics it emits and each field's observed Clarity, TS, and
+	* column types. Anonymous read; resolves to `null` on 404.
 	*/
 	printSchema(contractId: string): Promise<PrintSchemaResponse | null>;
 	/** Callable: `index.ftTransfers(params)` ≡ `index.ftTransfers.list(params)`. */
@@ -2845,8 +3065,23 @@ declare class Index extends BaseClient {
 	*  Callable: `index.events(params)` ≡ `index.events.list(params)`. */
 	readonly events: IndexEventsResource;
 	readonly contractCalls: {
+		/**
+		* Read one page of decoded contract calls.
+		*
+		* Filter by `contractId` (one id or up to 20) or `trait`, never both, plus `functionName`, `sender`, and a height range. Each row has the function name, arguments, result, and status. Pass `next_cursor` back as `cursor` to continue.
+		*/
 		list: (params?: ContractCallsListParams) => Promise<ContractCallsEnvelope>;
+		/**
+		* Iterate every decoded contract call, paging for you.
+		*
+		* Takes the same filters as `list`. Not a live index: it does not checkpoint, ignores reorgs, and ends when it catches the tip. `batchSize` defaults to 200 (max 1000); page fetches retry on 429 and 5xx; aborting `signal` rejects the iterator.
+		*/
 		walk: (params?: ContractCallsWalkParams) => AsyncIterable<IndexContractCall>;
+		/**
+		* Run a checkpointed, reorg-aware indexer over contract calls.
+		*
+		* Write your rows in `onBatch` and commit `ctx.cursor` in the same transaction; resume with `fromCursor`. Without `fromCursor` or `fromHeight` the API serves only its recent default window, so pass `fromHeight: 0` for a full backfill. A reorg at or below your checkpoint calls `onReorg`, then the loop re-reads from the fork point. Delivery is at-least-once, so keep writes idempotent. With a `sink`, the checkpoint and rollback are handled for you. `finalizedOnly` holds delivery to finalized rows, so no reorg handling is needed. `mode: "tail"` (default) keeps polling at the tip; `mode: "bounded"` returns on the first empty page. Resolves to `{ cursor, pages, emptyPolls }`. Calls already carry `sender` and `function_name`, so there is no `txContext`.
+		*/
 		consume: <TTx = never>(params: ContractCallsConsumeParams<TTx> & {
 			sink?: ConsumerSink<TTx>;
 		}) => Promise<{
@@ -2857,49 +3092,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
@@ -3030,26 +3341,54 @@ interface BundleSubgraphResponse {
 	bundleSize: number;
 }
 declare class Subgraphs extends BaseClient {
+	/**
+	* List the subgraphs deployed to this instance.
+	*
+	* Each summary has the status, the last processed block against the chain tip, progress, `gapCount`, and an `integrity` flag.
+	*/
 	list(): Promise<{
 		data: SubgraphSummary[];
 	}>;
 	/**
-	* The subgraph's current state — health, sync position, tables. The verify
-	* step after a deploy, reindex, or backfill: poll it until `sync` catches
-	* the tip.
+	* Get a subgraph's health, sync position, and tables.
+	*
+	* The verify step after a deploy, reindex, or backfill: poll it until
+	* `sync` catches the tip.
 	*/
 	status(name: string): Promise<SubgraphDetail>;
+	/**
+	* Get a subgraph's OpenAPI spec.
+	*
+	* Describes the REST routes generated for each table. Pass `serverUrl` to set the server the spec advertises.
+	*/
 	openapi(name: string, options?: SubgraphSpecOptions): Promise<Record<string, unknown>>;
+	/**
+	* Get a subgraph's schema as JSON, shaped for agents.
+	*
+	* Per table: the endpoints, columns, indexes, which fields are sortable, selectable, searchable, or filterable, and a ready example query. Pass `serverUrl` to set the server the endpoints use.
+	*/
 	schema(name: string, options?: SubgraphSpecOptions): Promise<SubgraphAgentSchema>;
+	/**
+	* Get a subgraph's generated API docs as Markdown text.
+	*
+	* Pass `serverUrl` to set the server the examples use.
+	*/
 	markdown(name: string, options?: SubgraphSpecOptions): Promise<string>;
 	/**
-	* Reindex always drops and rebuilds the whole subgraph, so it takes no
+	* Rebuild a subgraph from scratch.
+	*
+	* A reindex always drops and rebuilds the whole subgraph, so it takes no
 	* block range; the API rejects one with `REINDEX_RANGE_NOT_SUPPORTED`.
 	* Use {@link backfill} to process a specific range. While a reindex or
 	* backfill is already running the API answers 409 with code
 	* `OPERATION_IN_PROGRESS`; poll {@link operations} until it finishes.
 	*/
 	reindex(name: string): Promise<ReindexResponse>;
+	/**
+	* Stop a running reindex or backfill.
+	*
+	* Requests the cancel and resolves with the `operationId` and a `cancel_requested` status. Poll {@link getOperation} until `status` is terminal. Throws a 404 with code `NO_OPERATION` when nothing is running.
+	*/
 	stop(name: string): Promise<{
 		message: string;
 		operationId?: string;
@@ -3061,19 +3400,31 @@ declare class Subgraphs extends BaseClient {
 		fromBlock: number;
 		toBlock: number;
 	}): Promise<ReindexResponse>;
+	/**
+	* List the block ranges a subgraph is missing.
+	*
+	* Each gap has its `start`, `end`, `size`, `reason`, and when it was detected and resolved. `resolved` filters to resolved or open gaps; page with `limit` and `offset`. `meta` reports the total gap count and total missing blocks.
+	*/
 	gaps(name: string, opts?: {
 		limit?: number;
 		offset?: number;
 		resolved?: boolean;
 	}): Promise<SubgraphGapsResponse>;
+	/**
+	* Delete a subgraph and its tables.
+	*
+	* Permanent. The API cancels any running reindex or backfill first, waits up to 5 seconds for it to stop, then drops the subgraph's tables and registry entry. `force: true` is sent as `?force=true`.
+	*/
 	delete(name: string, options?: {
 		force?: boolean;
 	}): Promise<{
 		message: string;
 	}>;
 	/**
-	* Open /v1 read: cursor-paginated rows. Anon works on an open instance;
-	* pass an apiKey on the client where reads are closed. `next_cursor` is set
+	* Read a table's rows, one cursor page at a time.
+	*
+	* Anon works on an open instance; pass an apiKey on the client where reads
+	* are closed. `next_cursor` is set
 	* on every page that returned rows and is `null` only on an empty page, so a
 	* poller tails with `cursor = page.next_cursor ?? cursor`. A paging loop
 	* ends on an empty page (or one shorter than `limit`).
@@ -3085,13 +3436,20 @@ declare class Subgraphs extends BaseClient {
 	operations(name: string): Promise<{
 		operations: SubgraphOperationStatus[];
 	}>;
-	/** Status of a single operation (poll the `operationId` returned by
-	*  reindex/backfill/stop until `status` is terminal). */
+	/** Get the status of one reindex, backfill, or stop operation.
+	*
+	*  Poll the `operationId` returned by `reindex`, `backfill`, or `stop`
+	*  until `status` is terminal. */
 	getOperation(name: string, operationId: string): Promise<SubgraphOperationStatus>;
 	/** Create or update a subgraph. A deploy that needs a rebuild queues one;
 	*  if a reindex or backfill is already running the API answers 409 with
 	*  code `OPERATION_IN_PROGRESS` (an `ApiError`, not a dedicated class). */
 	deploy(data: DeploySubgraphRequest): Promise<DeploySubgraphResponse>;
+	/**
+	* Get a deployed subgraph's source.
+	*
+	* Returns `sourceCode`, the bundled `handlerCode` the runtime executes, and the `pin` hash of what you deployed. `handlerCode` and `pin` are `null` for local deploys. A subgraph deployed before source was captured returns `sourceCode: null` and `readOnly: true` with a `reason`; redeploy it to capture the source.
+	*/
 	getSource(name: string): Promise<SubgraphSource>;
 	/**
 	* Bundle a TypeScript subgraph source on the server. Used by the web chat
@@ -3100,13 +3458,15 @@ declare class Subgraphs extends BaseClient {
 	bundle(data: {
 		code: string;
 	}): Promise<BundleSubgraphResponse>;
-	/** Open /v1 read: exact row count for a filtered set. Same auth posture as
-	*  {@link rows}. */
+	/** Count the rows in a table that match a filter.
+	*
+	*  The count is exact. Same auth posture as {@link rows}. */
 	count(name: string, table: string, params?: Pick<SubgraphQueryParams, "filters">): Promise<{
 		count: number;
 	}>;
-	/** Open /v1 read: scalar aggregates over a filtered set. Same auth posture
-	*  as {@link rows}. */
+	/** Compute scalar aggregates over a table's matching rows.
+	*
+	*  Same auth posture as {@link rows}. */
 	aggregate(name: string, table: string, params?: SubgraphAggregateParams): Promise<SubgraphAggregateResponse>;
 	/**
 	* Returns a typed client for a subgraph defined with `defineSubgraph()`.
@@ -3139,37 +3499,93 @@ import { CreateWebhookRequest, CreateWebhookResponse, DeadRow, DeliveryRow, Repl
 import { ChainTrigger, ChainTriggerType, CreateWebhookRequest as CreateWebhookRequest2, CreateWebhookResponse as CreateWebhookResponse2, DeadRow as DeadRow2, DeliveryRow as DeliveryRow2, ReplayResult as ReplayResult2, RotateSecretResponse as RotateSecretResponse2, WebhookActivity as WebhookActivity2, WebhookActivityHour, WebhookAuth, WebhookDeliveryDetail as WebhookDeliveryDetail2, WebhookDetail as WebhookDetail2, WebhookFormat, WebhookKind, WebhookStatus, WebhookSummary as WebhookSummary2, WebhookTestResult as WebhookTestResult2, UpdateWebhookRequest as UpdateWebhookRequest2 } from "@secondlayer/shared/schemas/webhooks";
 import { trigger } from "@secondlayer/shared/schemas/webhooks";
 declare class Webhooks extends BaseClient {
+	/**
+	* List your webhooks.
+	*
+	* Each summary has the status, format, URL, last delivery and last success, and the circuit breaker state (`circuitFailures`, `circuitOpenedAt`).
+	*/
 	list(): Promise<{
 		data: WebhookSummary[];
 	}>;
+	/**
+	* Get one webhook's full configuration.
+	*
+	* Adds the triggers, the receiver's auth (redacted to header names and whether a secret is set), the retry and timeout limits, `lastError`, and a `warning` when this instance's trigger evaluator is not running.
+	*/
 	get(id: string): Promise<WebhookDetail>;
+	/**
+	* Create a webhook that POSTs chain events to your URL.
+	*
+	* Takes a `name`, a `url`, and `triggers` built with `trigger.*`; each trigger is validated before anything is provisioned, and an invalid one is a 400. The signing secret comes back once in `signingSecret`, so store it. A webhook starts at the chain tip and never backfills: use {@link replay} for history. Hosted accounts cap `maxRetries` at 7 and `timeoutMs` at 30000.
+	*/
 	create(input: CreateWebhookRequest): Promise<CreateWebhookResponse>;
+	/**
+	* Change a webhook's name, URL, format, auth, or delivery limits.
+	*
+	* Send only the fields to change: `name`, `url`, `format`, `authConfig`, `maxRetries`, `timeoutMs`, `concurrency`. Triggers are not part of an update. Resolves to the updated webhook.
+	*/
 	update(id: string, patch: UpdateWebhookRequest): Promise<WebhookDetail>;
+	/**
+	* Stop deliveries without deleting the webhook.
+	*
+	* Resolves to the updated webhook. {@link resume} turns it back on.
+	*/
 	pause(id: string): Promise<WebhookDetail>;
+	/**
+	* Start delivering again after a pause.
+	*
+	* Also clears a circuit-breaker pause, which happens after 20 straight failed deliveries. Resolves to the updated webhook.
+	*/
 	resume(id: string): Promise<WebhookDetail>;
+	/**
+	* Delete a webhook.
+	*
+	* Resolves to `{ ok: true }`. Throws a 404 when the webhook does not exist.
+	*/
 	delete(id: string): Promise<{
 		ok: true;
 	}>;
+	/**
+	* Issue a new signing secret.
+	*
+	* The new secret comes back once in `signingSecret`. Update the receiver that calls `verifyWebhookSignature` with it: deliveries are signed with the new secret from now on.
+	*/
 	rotateSecret(id: string): Promise<RotateSecretResponse>;
-	/** Send a one-off test webhook to the webhook's URL (built for its
-	*  format, SSRF-guarded). Logged as a delivery row, visible via deliveries. */
+	/** Send a one-off test delivery to a webhook's URL.
+	*
+	*  Built for the webhook's format and SSRF-guarded. Logged as a delivery
+	*  row, visible via `deliveries`. */
 	test(id: string): Promise<WebhookTestResult>;
 	/** The last 100 delivery attempts, newest first. The server caps the window;
 	*  there is nothing to page. */
 	deliveries(id: string): Promise<{
 		data: DeliveryRow[];
 	}>;
-	/** Hourly delivered/waiting/gave-up counts for the last 7 days, plus the
-	*  current queue depth — the events chart on the detail page. */
+	/** Get a webhook's hourly delivery counts for the last 7 days.
+	*
+	*  Each hour has delivered, waiting, and gave-up counts, plus the current
+	*  queue depth. This is the events chart on the detail page. */
 	activity(id: string): Promise<WebhookActivity>;
-	/** One delivery attempt with its outbox context (payload, response
-	*  headers) — the delivery card on the detail page. */
+	/** Get one delivery attempt with its payload and response.
+	*
+	*  Includes the outbox context (payload, response headers). This is the
+	*  delivery card on the detail page. */
 	delivery(id: string, deliveryId: string): Promise<WebhookDeliveryDetail>;
+	/**
+	* Re-deliver historical events over an existing webhook.
+	*
+	* Pass `fromBlock` and `toBlock`; the range is capped at 100,000 blocks. A replay is historical only and never moves the live cursor. It is idempotent: the same range twice is a no-op, so pass any string as `force` to re-deliver it. Replays carry `is_replay` and use the standard `chain.{type}.apply` envelope. Resolves to `replayId`, `enqueuedCount`, and `scannedCount`. A second replay while one is running is a 409. `sbtc_withdrawal_swept_confirmed` is forward-only and never replayed. Hosted accounts get 5 replays an hour.
+	*/
 	replay(id: string, range: {
 		fromBlock: number;
 		toBlock: number;
 		force?: string;
 	}): Promise<ReplayResult>;
+	/**
+	* List the events a webhook gave up delivering.
+	*
+	* Returns up to 100 dead-lettered events, newest failure first. Each row's `id` is what {@link requeue} takes.
+	*/
 	dead(id: string): Promise<{
 		data: DeadRow[];
 	}>;
@@ -3243,8 +3659,12 @@ declare class SecondLayer extends BaseClient {
 	readonly instance: InstanceClient;
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
-	* Up to 10 public reads in one round trip (`POST /v1/batch`). Each item
-	* is authorized on its own; the client's bearer token applies to every item.
+	* Run up to 10 public reads in one round trip (`POST /v1/batch`).
+	*
+	* Each item is authorized on its own; the client's bearer token applies to
+	* every item. Results come back in order as `{ path, status, body }`. Only
+	* paths under `/v1/index/`, `/v1/subgraphs`, `/v1/streams/`, and
+	* `/v1/contracts` are allowed; anything else is a per-item 400.
 	*/
 	batch(requests: Array<{
 		path: string;
@@ -3257,10 +3677,12 @@ declare class SecondLayer extends BaseClient {
 		}>;
 	}>;
 	/**
-	* Assemble a {@link ContextSnapshot}: the same orientation an MCP agent
-	* reads from `secondlayer://context`, available to any SDK/CLI consumer.
-	* Reads run concurrently; a failed read lands as `{ value: null, error }`
-	* on its field rather than rejecting the whole snapshot.
+	* Get a one-call snapshot of your account and instance.
+	*
+	* Returns a {@link ContextSnapshot}: the same orientation an MCP agent reads
+	* from `secondlayer://context`, available to any SDK or CLI consumer. Reads
+	* run concurrently; a failed read lands as `{ value: null, error }` on its
+	* field rather than rejecting the whole snapshot.
 	*/
 	context(): Promise<ContextSnapshot>;
 }
@@ -3291,7 +3713,7 @@ import { DeadRow as DeadRow3, DeliveryRow as DeliveryRow3, WebhookDetail as Webh
 * dashboard's webhook detail page. Moved out of the CLI (unchanged behavior)
 * so the web can build the same judgment without printing CLI-command text.
 *
-* Plan 068 adds five deterministic, numbers-only detectors on top of the
+* Five deterministic, numbers-only detectors sit on top of the
 * existing flag checks: no model, no history beyond the deliveries window
 * already fetched. Thresholds are named constants below, conservative on
 * purpose — a wrong insight costs more trust than a missed one.