@secondlayer/sdk 15.0.1 → 15.0.3

package/dist/index.d.ts

@@ -17,6 +17,7 @@ type InstanceClient = {
 	*/
 	diagnose(): Promise<InstanceDiagnosis>;
 };
+/** What to verify against, and the optional block range. */
 type ArchiveVerifyInput = {
 	against: string;
 	target?: string;
@@ -26,6 +27,7 @@ type ArchiveVerifyInput = {
 	publicKeyPem?: string;
 };
 type ArchiveVerifyRangeStatus = "match" | "digest-mismatch" | "count-mismatch" | "missing";
+/** Whether the archive is clean, diverged, or unanchored, by range. */
 type ArchiveVerifyResult = {
 	status: "clean" | "diverged" | "unanchored";
 	target: string;
@@ -50,8 +52,11 @@ type ArchiveVerifyResult = {
 };
 import { RangeDigest } from "@secondlayer/shared/archive/range-digest";
 import { ArchiveStatus } from "@secondlayer/shared/archive/status";
+/** The three archive datasets: blocks, transactions, and events. */
 type ArchiveDataset = "blocks" | "transactions" | "events";
+/** Whether an archive purchase is a bootstrap or a repair. */
 type ArchiveFlow = "bootstrap" | "repair";
+/** One archive file: dataset, block range, path, rows, bytes. */
 type ArchivePartition = {
 	dataset: string;
 	from_block: number;
@@ -74,6 +79,7 @@ type ArchiveManifest = {
 	key_id?: string;
 	[key: string]: unknown;
 };
+/** A loaded archive manifest with its origin and signature check. */
 type LoadedArchive = {
 	manifest: ArchiveManifest;
 	origin: string;
@@ -84,6 +90,7 @@ type LoadedArchive = {
 		reason?: string;
 	};
 };
+/** The price of an archive request, after any free allowance. */
 type ArchiveQuote = {
 	partitions: number;
 	bundles: number;
@@ -100,11 +107,13 @@ type ArchiveFetchItem = {
 	expiresAt: string;
 	chargedUsdMicros: number;
 };
+/** Download links for archive partitions and what they cost. */
 type ArchiveFetchResult = {
 	urls: ArchiveFetchItem[];
 	chargedTotalUsdMicros: number;
 	balanceAfterUsdMicros: number;
 };
+/** Your archive credit balance and its refill settings. */
 type ArchiveCreditsBalance = {
 	creditsUsdMicros: string;
 	refill: {
@@ -113,6 +122,7 @@ type ArchiveCreditsBalance = {
 		lastAt: string | null;
 	};
 };
+/** Options for loading an archive manifest. */
 type ArchiveLoadOptions = {
 	insecure?: boolean;
 };
@@ -345,6 +355,7 @@ declare abstract class BaseClient {
 */
 /** Whether a trait match must be declared in source, inferred from ABI, or either. */
 type ContractConformance = "declared" | "inferred" | "any";
+/** Trait, conformance, and paging for listing contracts. */
 interface ContractsListParams {
 	/** Required. Trait identifier to match (e.g. "sip-010", or a fully-qualified trait). */
 	trait: string;
@@ -357,6 +368,7 @@ interface ContractsListParams {
 	/** Opaque cursor from a prior response's `next_cursor`. */
 	cursor?: string;
 }
+/** A deployed contract with its traits, standards, and ABI status. */
 interface ContractSummary {
 	contract_id: string;
 	deployer: string;
@@ -367,6 +379,7 @@ interface ContractSummary {
 	/** Present only when `include: "abi"` was requested. */
 	abi?: unknown;
 }
+/** One page of contracts and the cursor for the next page. */
 interface ContractsEnvelope {
 	contracts: ContractSummary[];
 	next_cursor: string | null;
@@ -600,6 +613,7 @@ type WithSinkTx<TTx> = [TTx] extends [never] ? unknown : {
 import { VmEventType } from "@secondlayer/shared";
 import { RuneEventType, RuneStreamsEvent, StreamsEvent, StreamsEventType, StreamsWireEvent, VmStreamsEvent } from "@secondlayer/shared/streams-rows";
 import { StreamsWireEvent as StreamsWireEvent2, RuneEtchEntry, RuneEventPayload, StreamsEventPayload } from "@secondlayer/shared/streams-rows";
+/** The chain tip: latest block, Bitcoin anchor, and finality boundary. */
 type StreamsTip = {
 	block_height: number;
 	block_hash: string;
@@ -619,15 +633,19 @@ type StreamsTip = {
 	/** Oldest seekable cursor (`<oldest_seekable_height>:0`); `null` = unlimited. */
 	oldest_cursor?: string | null;
 };
-/** `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" })`. */
+/**
+* The Bitcoin tip, without burn-chain or retention fields.
+*
+* Bitcoin has no burn chain of its own, and Runes reads have no retention
+* ladder. Returned by `tip({ chain: "bitcoin" })`.
+*/
 type StreamsBitcoinTip = {
 	block_height: number;
 	block_hash: string;
 	finalized_height: number;
 	lag_seconds: number;
 };
+/** A canonical Stacks block with its Bitcoin anchor. */
 type StreamsCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -635,7 +653,7 @@ type StreamsCanonicalBlock = {
 	burn_block_hash: string | null;
 	is_canonical: true;
 };
-/** `chain=bitcoin` canonical block — no burn-chain fields. */
+/** A Bitcoin canonical block, without burn-chain fields. */
 type StreamsBitcoinCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -656,6 +674,7 @@ type StreamsReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** One page of events with the next cursor, tip, and reorgs. */
 type StreamsEventsEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
@@ -665,24 +684,30 @@ type StreamsEventsEnvelope<
 	tip: TTip;
 	reorgs: StreamsReorg[];
 };
+/** One page of events with the tip and reorgs, no cursor. */
 type StreamsEventsListEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
 > = Omit<StreamsEventsEnvelope<TEvent, TTip>, "next_cursor">;
-/** The StreamsEvent union narrowed to a `types` selection — what a
-*  const-generic `types: ["ft_transfer"]` buys at the type level. */
+/**
+* The event union narrowed to a `types` selection.
+*
+* A const-generic `types: ["ft_transfer"]` narrows the event type.
+*/
 type StreamsEventOfTypes<T extends readonly StreamsEventType[]> = Extract<StreamsEvent, {
 	event_type: T[number];
 }>;
+/** A starting point and limit for listing reorgs. */
 type StreamsReorgsListParams = {
 	since: string;
 	limit?: number;
 };
+/** A list of reorgs and the cursor to resume from. */
 type StreamsReorgsListEnvelope = {
 	reorgs: StreamsReorg[];
 	next_since: string | null;
 };
-/** A filter that matches a single value or any value in a list. */
+/** A single value or a list of values to match. */
 type StreamsFilterValue = string | readonly string[];
 /**
 * One labelled filter group. Fields inside a group AND together; groups in a
@@ -712,6 +737,7 @@ type StreamsEventForFilter<
 }> : Extract<StreamsEvent, {
 	event_type: T;
 }> : D extends true ? IndexEvent : StreamsEvent;
+/** Cursor, height range, and limit shared by every list call. */
 type StreamsEventsListParamsCommon = {
 	cursor?: string | null;
 	fromHeight?: number;
@@ -739,12 +765,13 @@ type StreamsEventsStacksListParams = StreamsEventsListParamsCommon & {
 	filters?: StreamsFilterMap;
 };
 /**
-* `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`/
-* `assetIdentifier`/`filters`/`clock` don't exist on this branch — they're
-* Stacks-only (the server 400s on them too).
+* List options for Runes events, with their own cursor space.
+*
+* `types` is restricted to `RuneEventType` at the type level, so e.g. `{ chain:
+* "bitcoin", types: ["ft_transfer"] }` is a compile error rather than a silent
+* 400 at request time. `contractId`, `sender`, `recipient`, `assetIdentifier`,
+* `filters`, and `clock` don't exist on this branch; they're Stacks-only (the
+* server 400s on them too).
 */
 type StreamsEventsBitcoinListParams = StreamsEventsListParamsCommon & {
 	chain: "bitcoin";
@@ -755,7 +782,9 @@ type StreamsEventsBitcoinListParams = StreamsEventsListParamsCommon & {
 	/** A mainnet address. */
 	address?: string;
 };
+/** Chain, cursor, height range, and filters for listing Streams events. */
 type StreamsEventsListParams = StreamsEventsStacksListParams | StreamsEventsBitcoinListParams;
+/** Cursor, batching, and stop options shared by every event stream. */
 type StreamsEventsStreamCommon = {
 	fromCursor?: string | null;
 	batchSize?: number;
@@ -764,8 +793,12 @@ type StreamsEventsStreamCommon = {
 	maxEmptyPolls?: number;
 	signal?: AbortSignal;
 };
-/** `chain: "stacks"` (default, omit `chain` entirely) — matches
-*  {@link StreamsEventsStacksListParams}. */
+/**
+* Stream options for Stacks events, the default chain.
+*
+* `chain: "stacks"` is the default, so omit `chain` entirely. Matches
+* `StreamsEventsStacksListParams`.
+*/
 type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	chain?: "stacks";
 	types?: readonly StreamsEventType[];
@@ -777,11 +810,14 @@ type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
 	filters?: StreamsFilterMap;
 };
-/** `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
-*  on this branch — they're Stacks-only. */
+/**
+* Stream options for Runes events, tailed like the Stacks default.
+*
+* `types` is restricted to `RuneEventType` at the type level, matching
+* `StreamsEventsBitcoinListParams`. `contractId`, `sender`, `recipient`,
+* `assetIdentifier`, and `filters` don't exist on this branch; they're
+* Stacks-only.
+*/
 type StreamsEventsStreamBitcoinParams = StreamsEventsStreamCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -835,9 +871,12 @@ type StreamsEventsSubscribeStacksParams = StreamsEventsSubscribeCommon & {
 	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
 };
-/** `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. */
+/**
+* Options for pushing Runes events live, on their own cursor space.
+*
+* `contractId`, `sender`, `recipient`, `assetIdentifier`, and `filters` don't
+* exist on this branch; they're Stacks-only.
+*/
 type StreamsEventsSubscribeBitcoinParams = StreamsEventsSubscribeCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -928,6 +967,7 @@ type StreamsBatchContext = ConsumerBatchContext;
 type StreamsReorgContext = {
 	cursor: string | null;
 };
+/** Options for consuming Streams events: cursor, batching, filters, handler. */
 type StreamsEventsConsumeParams<
 	TTx = never,
 	D extends boolean = false,
@@ -1045,13 +1085,14 @@ type StreamsEventsConsumeParams<
 	wake?: () => Promise<void>;
 };
 /**
-* `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
-* equivalent yet), so `onBatch` is the only way in and is required. Reorg
-* rewind still works the same way (bitcoin reorgs carry the same
-* `fork_point_height` + `new_canonical_tip` shape as Stacks ones).
+* Options for the checkpointed sweep over Runes events.
+*
+* A separate, simpler type from `StreamsEventsConsumeParams` rather than a
+* widened union member: `filters`, `on`, and `decoded` are Stacks-only concepts
+* (labelled OR-groups and Index-shaped projection have no Runes equivalent
+* yet), so `onBatch` is the only way in and is required. Reorg rewind still
+* works the same way (bitcoin reorgs carry the same `fork_point_height` and
+* `new_canonical_tip` shape as Stacks ones).
 */
 type StreamsEventsConsumeBitcoinParams<TTx = never> = {
 	chain: "bitcoin";
@@ -1084,9 +1125,10 @@ type StreamsEventsConsumeBitcoinParams<TTx = never> = {
 	wake?: () => Promise<void>;
 };
 /**
-* One yielded page from {@link StreamsClient.consume} — the
-* `GET /v1/streams/events` envelope verbatim, with `next_cursor` renamed to
-* `cursor` (the checkpoint to persist and resume from).
+* One page yielded by `consume`, with `cursor` to persist and resume.
+*
+* It is the `GET /v1/streams/events` envelope verbatim, with `next_cursor`
+* renamed to `cursor`.
 */
 type StreamsBatch<
 	TEvent = StreamsEvent,
@@ -1100,6 +1142,7 @@ type StreamsBatch<
 	/** Chain reorgs reported alongside this page; empty when none. */
 	reorgs: StreamsReorg[];
 };
+/** Cursor, batch size, and polling options shared by every consume loop. */
 type StreamsConsumeCommon = {
 	/** Resume strictly after this cursor; omit to start from the oldest seekable page. */
 	cursor?: string | null;
@@ -1123,9 +1166,12 @@ type StreamsConsumeStacksParams = StreamsConsumeCommon & {
 	*  event echoes the labels it matched. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` — Runes batches, own cursor space.
-*  `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters` don't exist
-*  on this branch — they're Stacks-only. */
+/**
+* Consume options for Runes batches, with their own cursor space.
+*
+* `contractId`, `sender`, `recipient`, `assetIdentifier`, and `filters` don't
+* exist on this branch; they're Stacks-only.
+*/
 type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -1136,11 +1182,13 @@ type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
 	address?: string;
 };
 type StreamsConsumeParams = StreamsConsumeStacksParams | StreamsConsumeBitcoinParams;
+/** Where a consume loop stopped: cursor, pages read, empty polls. */
 type StreamsEventsConsumeResult = {
 	cursor: string | null;
 	pages: number;
 	emptyPolls: number;
 };
+/** Options for replaying history from dump files, then tailing live. */
 type StreamsEventsReplayParams = {
 	/** Start point: `"genesis"` (default) or a `<block>:<index>` cursor. */
 	from?: "genesis" | string;
@@ -1196,6 +1244,7 @@ type StreamsDumpFile = {
 	schema_version: number;
 	created_at: string;
 };
+/** The index of finalized Parquet dump files for one dataset. */
 type StreamsDumpsManifest = {
 	dataset: string;
 	network: string;
@@ -1569,6 +1618,7 @@ type IndexReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** A decoded fungible-token transfer: sender, recipient, asset, amount. */
 type FtTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1583,6 +1633,7 @@ type FtTransfer = {
 	recipient: string;
 	amount: string;
 };
+/** One page of fungible-token transfers, with the cursor, tip, and reorgs. */
 type FtTransfersEnvelope<TRow = FtTransfer> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -1594,6 +1645,7 @@ type FtTransfersEnvelope<TRow = FtTransfer> = {
 type FtTransferAlwaysFields = "cursor" | "block_height" | "event_type";
 /** An ft-transfer row narrowed to the requested columns plus the always-present ones. */
 type FtTransferFields<F extends keyof FtTransfer & string> = Pick<FtTransfer, (F | FtTransferAlwaysFields) & keyof FtTransfer>;
+/** Column selection, paging, and filters for listing token transfers. */
 type FtTransfersListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -1629,7 +1681,9 @@ type WalkOptions = PageRetryOptions & {
 	*  walk from a stopped one. */
 	signal?: AbortSignal;
 };
+/** `FtTransfersListParams` without `limit`, plus walk options. */
 type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & WalkOptions;
+/** A decoded non-fungible-token transfer: sender, recipient, asset, value. */
 type NftTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1644,6 +1698,7 @@ type NftTransfer = {
 	recipient: string;
 	value: string;
 };
+/** One page of non-fungible-token transfers, with the cursor, tip, and reorgs. */
 type NftTransfersEnvelope<TRow = NftTransfer> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -1654,6 +1709,7 @@ type NftTransfersEnvelope<TRow = NftTransfer> = {
 type NftTransferAlwaysFields = "cursor" | "block_height" | "event_type";
 /** An nft-transfer row narrowed to the requested columns plus the always-present ones. */
 type NftTransferFields<F extends keyof NftTransfer & string> = Pick<NftTransfer, (F | NftTransferAlwaysFields) & keyof NftTransfer>;
+/** Column selection, paging, and filters for listing NFT transfers. */
 type NftTransfersListParams = {
 	/** Columns to return (see {@link FtTransfersListParams.fields}). */
 	fields?: readonly (keyof NftTransfer & string)[];
@@ -1667,6 +1723,7 @@ type NftTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `NftTransfersListParams` without `limit`, plus walk options. */
 type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & WalkOptions;
 type IndexEventBase = {
 	cursor: string;
@@ -1687,6 +1744,7 @@ type IndexEventBase = {
 	tx_contract_id?: string | null;
 	tx_function_name?: string | null;
 };
+/** A fungible-token transfer event. */
 type IndexFtTransfer = IndexEventBase & {
 	event_type: "ft_transfer";
 	asset_identifier: string;
@@ -1694,6 +1752,7 @@ type IndexFtTransfer = IndexEventBase & {
 	recipient: string;
 	amount: string;
 };
+/** A non-fungible-token transfer event. */
 type IndexNftTransfer = IndexEventBase & {
 	event_type: "nft_transfer";
 	asset_identifier: string;
@@ -1701,6 +1760,7 @@ type IndexNftTransfer = IndexEventBase & {
 	recipient: string;
 	value: string;
 };
+/** An STX transfer event. */
 type IndexStxTransfer = IndexEventBase & {
 	event_type: "stx_transfer";
 	sender: string;
@@ -1708,16 +1768,19 @@ type IndexStxTransfer = IndexEventBase & {
 	amount: string;
 	memo: string | null;
 };
+/** An STX mint event. */
 type IndexStxMint = IndexEventBase & {
 	event_type: "stx_mint";
 	recipient: string;
 	amount: string;
 };
+/** An STX burn event. */
 type IndexStxBurn = IndexEventBase & {
 	event_type: "stx_burn";
 	sender: string;
 	amount: string;
 };
+/** An STX lock event with its unlock height. */
 type IndexStxLock = IndexEventBase & {
 	event_type: "stx_lock";
 	sender: string;
@@ -1726,30 +1789,35 @@ type IndexStxLock = IndexEventBase & {
 		unlock_height: string | null;
 	};
 };
+/** A fungible-token mint event. */
 type IndexFtMint = IndexEventBase & {
 	event_type: "ft_mint";
 	asset_identifier: string;
 	recipient: string;
 	amount: string;
 };
+/** A fungible-token burn event. */
 type IndexFtBurn = IndexEventBase & {
 	event_type: "ft_burn";
 	asset_identifier: string;
 	sender: string;
 	amount: string;
 };
+/** A non-fungible-token mint event. */
 type IndexNftMint = IndexEventBase & {
 	event_type: "nft_mint";
 	asset_identifier: string;
 	recipient: string;
 	value: string;
 };
+/** A non-fungible-token burn event. */
 type IndexNftBurn = IndexEventBase & {
 	event_type: "nft_burn";
 	asset_identifier: string;
 	sender: string;
 	value: string;
 };
+/** A contract `print` event with its topic and value. */
 type IndexPrint = IndexEventBase & {
 	event_type: "print";
 	payload: {
@@ -1758,6 +1826,7 @@ type IndexPrint = IndexEventBase & {
 		raw_value: string | null;
 	};
 };
+/** A contract call made from inside another contract call. */
 type IndexNestedContractCall = IndexEventBase & {
 	event_type: "nested_contract_call";
 	sender: string | null;
@@ -1766,23 +1835,27 @@ type IndexNestedContractCall = IndexEventBase & {
 	function_args: unknown;
 	raw_result: string | null;
 };
+/** A contract data variable write. */
 type IndexVarSet = IndexEventBase & {
 	event_type: "var_set";
 	var_name: string;
 	raw_value: string;
 };
+/** A contract map entry overwrite. */
 type IndexMapSet = IndexEventBase & {
 	event_type: "map_set";
 	map: string;
 	raw_key: string;
 	raw_value: string;
 };
+/** A new contract map entry. */
 type IndexMapInsert = IndexEventBase & {
 	event_type: "map_insert";
 	map: string;
 	raw_key: string;
 	raw_value: string;
 };
+/** A contract map entry deletion. */
 type IndexMapDelete = IndexEventBase & {
 	event_type: "map_delete";
 	map: string;
@@ -1799,6 +1872,7 @@ type IndexEventFields<
 	T extends IndexEventType,
 	F extends keyof IndexEventOf<T> & string
 > = Pick<IndexEventOf<T>, (F | IndexAlwaysFields) & keyof IndexEventOf<T>>;
+/** One page of decoded events, with the cursor, tip, and reorgs. */
 type EventsEnvelope<
 	T extends IndexEventType = IndexEventType,
 	TRow = IndexEventOf<T>
@@ -1813,6 +1887,7 @@ type EventsEnvelope<
 type IndexEventOf<T extends IndexEventType> = Extract<IndexEvent, {
 	event_type: T;
 }>;
+/** Event type, paging, and filters for listing decoded events. */
 type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	/** Decoded types or VM types (`nested_contract_call`, `map_set`, …). */
 	eventType: T;
@@ -1857,11 +1932,13 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	*/
 	fields?: readonly (keyof IndexEventOf<T> & string)[];
 };
+/** `EventsListParams` without `limit`, plus walk options. */
 type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & WalkOptions;
 type EventsConsumeParams<
 	T extends IndexEventType = IndexEventType,
 	TTx = never
 > = Omit<EventsListParams<T>, "cursor" | "fromCursor" | "limit" | "fields"> & IndexConsumeOptions<IndexEventOf<T>, EventsEnvelope<T>, TTx>;
+/** A decoded contract call: contract, function, sender, arguments, result. */
 type IndexContractCall = {
 	cursor: string;
 	block_height: number;
@@ -1876,12 +1953,14 @@ type IndexContractCall = {
 	result: unknown;
 	result_hex: string | null;
 };
+/** One page of contract calls, with the cursor, tip, and reorgs. */
 type ContractCallsEnvelope = {
 	contract_calls: IndexContractCall[];
 	next_cursor: string | null;
 	tip: IndexTip;
 	reorgs: IndexReorg[];
 };
+/** Paging and contract filters for listing contract calls. */
 type ContractCallsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1897,6 +1976,7 @@ type ContractCallsListParams = {
 	*  Mutually exclusive with contractId. */
 	trait?: string;
 };
+/** `ContractCallsListParams` without `limit`, plus walk options. */
 type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & WalkOptions;
 type ContractCallsConsumeParams<TTx = never> = Omit<ContractCallsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexContractCall, ContractCallsEnvelope, TTx>;
 /** One canonical block in the sync map. Lean by design — block + parent hash
@@ -1910,11 +1990,13 @@ type IndexCanonicalBlock = {
 	burn_block_height: number;
 	burn_block_hash: string | null;
 };
+/** One page of canonical blocks, with the next cursor and chain tip. */
 type CanonicalEnvelope = {
 	canonical: IndexCanonicalBlock[];
 	next_cursor: string | null;
 	tip: IndexTip;
 };
+/** Paging and height filters for listing canonical blocks. */
 type CanonicalListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1922,6 +2004,7 @@ type CanonicalListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `CanonicalListParams` without `limit`, plus walk options. */
 type CanonicalWalkParams = Omit<CanonicalListParams, "limit"> & WalkOptions;
 /** One MARF write a block committed, in the node's write order. Present only
 *  from the height the instance's node subscribed to `state_writes`. */
@@ -1946,12 +2029,14 @@ type IndexStateWrite = {
 	tx_contract_id?: string | null;
 	tx_function_name?: string | null;
 };
+/** One page of contract state writes, with the cursor, tip, and reorgs. */
 type StateWritesEnvelope = {
 	state_writes: IndexStateWrite[];
 	next_cursor: string | null;
 	tip: IndexTip;
 	reorgs: IndexReorg[];
 };
+/** Paging and filters for listing contract state writes. */
 type StateWritesListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1965,6 +2050,7 @@ type StateWritesListParams = {
 	/** Join the writing transaction's `tx_*` fields onto each row. */
 	txContext?: boolean;
 };
+/** `StateWritesListParams` without `limit`, plus walk options. */
 type StateWritesWalkParams = Omit<StateWritesListParams, "limit"> & WalkOptions;
 /** A block resource. Metadata is intentionally thin — only chain-linkage and
 *  burn-anchor fields are persisted (no miner / tx_count / signer). */
@@ -1978,15 +2064,18 @@ type IndexBlock = {
 	block_time: string | null;
 	canonical: boolean;
 };
+/** One page of blocks, with the next cursor and chain tip. */
 type BlocksEnvelope = {
 	blocks: IndexBlock[];
 	next_cursor: string | null;
 	tip: IndexTip;
 };
+/** One block and the chain tip. */
 type BlockEnvelope = {
 	block: IndexBlock;
 	tip: IndexTip;
 };
+/** Paging and height filters for listing blocks. */
 type BlocksListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1994,6 +2083,7 @@ type BlocksListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `BlocksListParams` without `limit`, plus walk options. */
 type BlocksWalkParams = Omit<BlocksListParams, "limit"> & WalkOptions;
 type IndexPostCondition = {
 	type: "stx";
@@ -2070,12 +2160,14 @@ type IndexTransaction = {
 		cause: number;
 	};
 };
+/** One page of transactions, with the cursor, tip, and reorgs. */
 type TransactionsEnvelope<TRow = IndexTransaction> = {
 	transactions: TRow[];
 	next_cursor: string | null;
 	tip: IndexTip;
 	reorgs: IndexReorg[];
 };
+/** One transaction and the chain tip. */
 type TransactionEnvelope = {
 	transaction: IndexTransaction;
 	tip: IndexTip;
@@ -2084,6 +2176,7 @@ type TransactionEnvelope = {
 type TransactionAlwaysFields = "cursor" | "block_height" | "tx_id";
 /** A Transaction row narrowed to the requested columns plus the always-present ones. */
 type TransactionFields<F extends keyof IndexTransaction & string> = Pick<IndexTransaction, (F | TransactionAlwaysFields) & keyof IndexTransaction>;
+/** Column selection, paging, and filters for listing transactions. */
 type TransactionsListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -2100,6 +2193,7 @@ type TransactionsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `TransactionsListParams` without `limit`, plus walk options. */
 type TransactionsWalkParams = Omit<TransactionsListParams, "limit"> & WalkOptions;
 /** A decoded PoX-4 stacking action (one per stacking contract call). */
 type IndexStackingAction = {
@@ -2126,6 +2220,7 @@ type IndexStackingAction = {
 	signer_key: string | null;
 	result_ok: boolean;
 };
+/** One page of stacking actions, with the cursor, tip, and reorgs. */
 type StackingEnvelope = {
 	stacking: IndexStackingAction[];
 	next_cursor: string | null;
@@ -2134,6 +2229,7 @@ type StackingEnvelope = {
 	/** Present only when the PoX-4 decoder is disabled, explaining an empty feed. */
 	notes?: string;
 };
+/** Paging and filters for listing stacking actions. */
 type StackingListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2144,6 +2240,7 @@ type StackingListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `StackingListParams` without `limit`, plus walk options. */
 type StackingWalkParams = Omit<StackingListParams, "limit"> & WalkOptions;
 /** A pending (unconfirmed) transaction. Like a transaction document but
 *  pre-chain — no block_height/tx_index/result/events — with `received_at` and
@@ -2180,15 +2277,18 @@ type IndexMempoolTransaction = {
 		cause: number;
 	};
 };
+/** One page of pending transactions, with the next cursor and chain tip. */
 type MempoolEnvelope = {
 	mempool: IndexMempoolTransaction[];
 	next_cursor: string | null;
 	tip: IndexTip;
 };
+/** One pending transaction and the chain tip. */
 type MempoolTransactionEnvelope = {
 	transaction: IndexMempoolTransaction;
 	tip: IndexTip;
 };
+/** Paging and sender filters for listing pending transactions. */
 type MempoolListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2200,11 +2300,13 @@ type MempoolListParams = {
 	/** Filter to pending calls to a single function (composes with `contractId`). */
 	functionName?: string;
 };
+/** `MempoolListParams` without `limit`, plus walk options. */
 type MempoolWalkParams = Omit<MempoolListParams, "limit"> & WalkOptions;
 /**
-* Empirical per-topic print payload schema for a contract, inferred from
-* sampled on-chain events. `topics` is sorted by count desc; `sampled` is true
-* when the contract has more print events than the windows examined.
+* Per-topic print payload schema for a contract, inferred from sampled events.
+*
+* `topics` is sorted by count desc; `sampled` is true when the contract has
+* more print events than the windows examined.
 */
 type PrintSchemaResponse = {
 	contract_id: string;
@@ -2241,8 +2343,12 @@ type IndexSbtcDeposit = {
 type IndexSbtcDepositDetail = IndexSbtcDeposit & {
 	status: "COMPLETED";
 };
-/** A peg-out collapsed to one row per `request_id`, with lifecycle `status`
-*  derived from the latest accept/reject. */
+/**
+* A peg-out as one row per request, with its latest status.
+*
+* Collapsed to one row per `request_id`, with lifecycle `status` derived from
+* the latest accept/reject.
+*/
 type IndexSbtcWithdrawal = {
 	cursor: string;
 	request_id: number;
@@ -2296,8 +2402,11 @@ type IndexSbtcWithdrawalDetail = {
 	};
 	finalized: boolean;
 };
-/** A raw decoded sBTC protocol-state event — the full `sbtc_events` row, one
-*  per event across all topics. */
+/**
+* A raw decoded sBTC protocol-state event, one per event.
+*
+* It is the full `sbtc_events` row, one per event across all topics.
+*/
 type IndexSbtcEvent = {
 	cursor: string;
 	block_height: number;
@@ -2336,6 +2445,7 @@ type IndexSbtcSummary = {
 	total_locked_sats: string;
 	sbtc_supply_sats: string | null;
 };
+/** One page of sBTC deposits, with the cursor, tip, and reorgs. */
 type SbtcDepositsEnvelope<TRow = IndexSbtcDeposit> = {
 	deposits: TRow[];
 	next_cursor: string | null;
@@ -2344,10 +2454,12 @@ type SbtcDepositsEnvelope<TRow = IndexSbtcDeposit> = {
 	/** Present only when the sBTC decoder is disabled, explaining an empty feed. */
 	notes?: string;
 };
+/** One sBTC deposit and the chain tip. */
 type SbtcDepositEnvelope = {
 	deposit: IndexSbtcDepositDetail;
 	tip: IndexTip;
 };
+/** One page of sBTC withdrawals, with the cursor, tip, and reorgs. */
 type SbtcWithdrawalsEnvelope<TRow = IndexSbtcWithdrawal> = {
 	withdrawals: TRow[];
 	next_cursor: string | null;
@@ -2355,10 +2467,12 @@ type SbtcWithdrawalsEnvelope<TRow = IndexSbtcWithdrawal> = {
 	reorgs: IndexReorg[];
 	notes?: string;
 };
+/** One sBTC withdrawal and the chain tip. */
 type SbtcWithdrawalEnvelope = {
 	withdrawal: IndexSbtcWithdrawalDetail;
 	tip: IndexTip;
 };
+/** One page of sBTC events, with the cursor, tip, and reorgs. */
 type SbtcEventsEnvelope = {
 	events: IndexSbtcEvent[];
 	next_cursor: string | null;
@@ -2366,11 +2480,13 @@ type SbtcEventsEnvelope = {
 	reorgs: IndexReorg[];
 	notes?: string;
 };
+/** The sBTC totals and the chain tip. */
 type SbtcSummaryEnvelope = {
 	summary: IndexSbtcSummary;
 	tip: IndexTip;
 	notes?: string;
 };
+/** Column selection, paging, and filters for listing sBTC deposits. */
 type SbtcDepositsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2392,11 +2508,13 @@ type SbtcDepositsListParams = {
 type SbtcDepositAlwaysFields = "cursor" | "block_height";
 /** A deposit row narrowed to the requested columns plus the always-present ones. */
 type SbtcDepositFields<F extends keyof IndexSbtcDeposit & string> = Pick<IndexSbtcDeposit, (F | SbtcDepositAlwaysFields) & keyof IndexSbtcDeposit>;
+/** `SbtcDepositsListParams` without `limit`, plus walk options. */
 type SbtcDepositsWalkParams = Omit<SbtcDepositsListParams, "limit"> & WalkOptions;
 /** SbtcWithdrawal columns that survive any projection. */
 type SbtcWithdrawalAlwaysFields = "cursor" | "request_id";
 /** A SbtcWithdrawal row narrowed to the requested columns plus the always-present ones. */
 type SbtcWithdrawalFields<F extends keyof IndexSbtcWithdrawal & string> = Pick<IndexSbtcWithdrawal, (F | SbtcWithdrawalAlwaysFields) & keyof IndexSbtcWithdrawal>;
+/** Column selection, paging, and filters for listing sBTC withdrawals. */
 type SbtcWithdrawalsListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -2417,7 +2535,9 @@ type SbtcWithdrawalsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `SbtcWithdrawalsListParams` without `limit`, plus walk options. */
 type SbtcWithdrawalsWalkParams = Omit<SbtcWithdrawalsListParams, "limit"> & WalkOptions;
+/** Paging and filters for listing sBTC events. */
 type SbtcEventsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2430,6 +2550,7 @@ type SbtcEventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `SbtcEventsListParams` without `limit`, plus walk options. */
 type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & WalkOptions;
 type SbtcEventsConsumeParams<TTx = never> = Omit<SbtcEventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexSbtcEvent, SbtcEventsEnvelope, TTx>;
 type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "cursor" | "fromCursor" | "limit" | "fields"> & IndexConsumeOptions<IndexSbtcDeposit, SbtcDepositsEnvelope, TTx>;
@@ -2575,6 +2696,7 @@ type IndexPoxCycleSigner = {
 	in_set: boolean;
 	rewards_claimed: string;
 };
+/** One page of reward cycles, newest first, with the next cursor. */
 type PoxCyclesEnvelope = {
 	/** The PoX version this response reports. Currently 5. */
 	pox_version: 5;
@@ -2583,6 +2705,7 @@ type PoxCyclesEnvelope = {
 	next_cursor: number | null;
 	tip: IndexTip;
 };
+/** One reward cycle with its signers and the chain tip. */
 type PoxCycleEnvelope = {
 	pox_version: 5;
 	cycle: IndexPoxCycle & {
@@ -2590,11 +2713,13 @@ type PoxCycleEnvelope = {
 	};
 	tip: IndexTip;
 };
+/** Paging for listing reward cycles. */
 type PoxCyclesListParams = {
 	/** A `reward_cycle` to page from; the page returns cycles below it (descending). */
 	cursor?: number | null;
 	limit?: number;
 };
+/** `PoxCyclesListParams` without `limit`, plus walk options. */
 type PoxCyclesWalkParams = Omit<PoxCyclesListParams, "limit"> & WalkOptions;
 /** `index.pox` — reward cycles of the current PoX (PoX-5). */
 interface PoxResource {
@@ -2652,6 +2777,7 @@ type IndexPox5Event = {
 	/** The full decoded print tuple as JSON. */
 	data: unknown;
 };
+/** One page of PoX-5 events, with the cursor, tip, and reorgs. */
 type Pox5EventsEnvelope<TRow = IndexPox5Event> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -2664,6 +2790,7 @@ type Pox5EventsEnvelope<TRow = IndexPox5Event> = {
 type Pox5EventAlwaysFields = "cursor" | "block_height" | "topic";
 /** A Pox5Event row narrowed to the requested columns plus the always-present ones. */
 type Pox5EventFields<F extends keyof IndexPox5Event & string> = Pick<IndexPox5Event, (F | Pox5EventAlwaysFields) & keyof IndexPox5Event>;
+/** Column selection, paging, and filters for listing PoX-5 events. */
 type Pox5EventsListParams = {
 	/**
 	* Columns to return. The server projects the row, so an unrequested column
@@ -2685,6 +2812,7 @@ type Pox5EventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
+/** `Pox5EventsListParams` without `limit`, plus walk options. */
 type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & WalkOptions;
 type Pox5EventsConsumeParams<TTx = never> = Omit<Pox5EventsListParams, "cursor" | "fromCursor" | "limit"> & IndexConsumeOptions<IndexPox5Event, Pox5EventsEnvelope, TTx>;
 /** `index.pox5` — decoded PoX-5 print events, the staking primitive from the
@@ -2724,11 +2852,13 @@ interface Pox5Resource {
 /** A rune's `<block>:<tx>` id — the etch transaction's position, e.g. `840000:3`. */
 type RuneId = `${number}:${number}`;
 /**
-* A rune reference accepted by every Runes call: an id ({@link RuneId}) or a
-* name, with or without spacers, in any case — `DOG•GO•TO•THE•MOON`,
-* `dog.go.to.the.moon` and `doggotothemoon` all resolve to the same rune.
-* Typing every rune name is a no (178k runes and growing — a generated union
-* would be huge and stale on day one); `list({ search })` covers discovery.
+* A rune id or name, in any case, with or without spacers.
+*
+* `DOG•GO•TO•THE•MOON`, `dog.go.to.the.moon` and `doggotothemoon` all resolve
+* to the same rune.
+*
+* Typing every rune name is a no: 178k runes and growing, so a generated union
+* would be huge and stale on day one. `list({ search })` covers discovery.
 */
 type RuneRef = RuneId | (string & {});
 /** The Bitcoin chain tip a Runes read was served against — a separate clock
@@ -2773,8 +2903,11 @@ type IndexRuneTerms = {
 	offset_start: string | null;
 	offset_end: string | null;
 };
-/** One etched rune's full entry: identity, premine/mint/burn counters,
-*  computed supply, and mint terms. */
+/**
+* One etched rune: identity, counters, supply, and mint terms.
+*
+* Counters cover premine, mint, and burn; supply is computed.
+*/
 type IndexRuneEntry = IndexRuneRefSummary & {
 	/** Etch sequence number (u128 decimal string) — 0 is genesis. */
 	number: string;
@@ -2791,6 +2924,7 @@ type IndexRuneEntry = IndexRuneRefSummary & {
 	etched_tx_index: number;
 	terms: IndexRuneTerms | null;
 };
+/** One page of runes, with the cursor and Bitcoin tip. */
 type RunesEnvelope<TRow = IndexRuneEntry> = {
 	runes: TRow[];
 	next_cursor: string | null;
@@ -2801,6 +2935,7 @@ type RunesEnvelope<TRow = IndexRuneEntry> = {
 	/** Present only when Runes data is not configured on this instance. */
 	notes?: string;
 };
+/** Name search, sort order, and paging for listing runes. */
 type RunesListParams = {
 	/** Name prefix, spacers and case ignored (`dog` matches `DOG•GO•TO•THE•MOON`). */
 	search?: string;
@@ -2809,13 +2944,17 @@ type RunesListParams = {
 	cursor?: string | null;
 	limit?: number;
 };
+/** One rune and the Bitcoin tip. */
 type RuneEnvelope = {
 	rune: IndexRuneEntry;
 	tip: IndexBitcoinTip;
 };
 type IndexRuneEventKind = "rune_etch" | "rune_mint" | "rune_transfer" | "rune_burn";
-/** One etch/mint/transfer/burn event, with the rune's identity embedded so an
-*  activity feed never needs a second lookup to show a name. */
+/**
+* One rune etch, mint, transfer, or burn, with the rune's identity.
+*
+* The identity is embedded so an activity feed needs no second lookup to show a name.
+*/
 type IndexRuneEvent = {
 	cursor: string;
 	block_height: number;
@@ -2830,6 +2969,7 @@ type IndexRuneEvent = {
 	address: string | null;
 	rune: IndexRuneRefSummary;
 };
+/** One page of rune events, with the cursor, Bitcoin tip, and reorgs. */
 type RuneActivityEnvelope<TRow = IndexRuneEvent> = {
 	events: TRow[];
 	next_cursor: string | null;
@@ -2837,6 +2977,7 @@ type RuneActivityEnvelope<TRow = IndexRuneEvent> = {
 	reorgs: IndexBtcReorg[];
 	notes?: string;
 };
+/** Paging and height filters for listing rune events. */
 type RuneActivityListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -2848,6 +2989,7 @@ type RuneActivityListParams = {
 	kind?: readonly IndexRuneEventKind[];
 	txid?: string;
 };
+/** `RuneActivityListParams` without `limit`, plus walk options. */
 type RuneActivityWalkParams = Omit<RuneActivityListParams, "limit"> & WalkOptions;
 /** A rune's balance on one unspent output, with the rune's identity embedded. */
 type IndexRuneBalance = {
@@ -2859,6 +3001,7 @@ type IndexRuneBalance = {
 	/** u128 decimal string. Never `Number()`. */
 	amount: string;
 };
+/** One page of rune balances, with the cursor and Bitcoin tip. */
 type RuneBalancesEnvelope<TRow = IndexRuneBalance> = {
 	balances: TRow[];
 	next_cursor: string | null;
@@ -2867,8 +3010,11 @@ type RuneBalancesEnvelope<TRow = IndexRuneBalance> = {
 	reorgs: IndexBtcReorg[];
 	notes?: string;
 };
-/** Exactly one of `address`/`outpoint` is required — enforced at the type
-*  level, not just at runtime. */
+/**
+* Rune balance filters; exactly one of `address` or `outpoint`.
+*
+* Enforced at the type level, not just at runtime.
+*/
 type RuneBalancesListParams = ({
 	address: string;
 	outpoint?: never;
@@ -3032,9 +3178,12 @@ type IndexEventTypeFilters = {
 	equality_filters?: string[];
 	required_non_null?: string[];
 };
-/** The `GET /v1/index` discovery doc — live endpoint + filter vocabulary.
-*  Shape is intentionally open (the server may add fields); the agent-relevant
-*  parts are the per-type filter rules. */
+/**
+* The `GET /v1/index` discovery doc: live endpoints and filter vocabulary.
+*
+* Shape is intentionally open (the server may add fields); the agent-relevant
+* parts are the per-type filter rules.
+*/
 type IndexDiscovery = {
 	event_type_filters?: Record<string, IndexEventTypeFilters>;
 	[key: string]: unknown;
@@ -3287,6 +3436,7 @@ import { ReindexResponse, SubgraphAggregateParams, SubgraphAggregateResponse, Su
 import { DeploySubgraphRequest, DeploySubgraphResponse } from "@secondlayer/shared/schemas/subgraphs";
 import { SubgraphAgentSchema, SubgraphSpecOptions } from "@secondlayer/shared/subgraphs/spec";
 import { InferSubgraphClient } from "@secondlayer/subgraphs";
+/** A deployed subgraph's source code, handler bundle, and pin. */
 interface SubgraphSource {
 	name: string;
 	version: string;
@@ -3330,6 +3480,7 @@ interface SubgraphRowsEnvelope<T = unknown> {
 		blocks_behind: number;
 	};
 }
+/** A deployed subgraph's bundled sources, schema, and handler code. */
 interface BundleSubgraphResponse {
 	ok: true;
 	name: string;
@@ -3624,10 +3775,11 @@ interface ContextField<T> {
 	error?: ContextFieldError;
 }
 /**
-* A point-in-time orientation snapshot for an agent: the live tips and what
-* this instance holds. Every field is a {@link ContextField}, so a missing
-* value says why it is missing (API unreachable, token rejected, index still
-* catching up) instead of a bare `null`. `context()` itself never throws.
+* A point-in-time orientation snapshot: live tips and what this instance holds.
+*
+* Every field is a `ContextField`, so a missing value says why it is missing
+* (API unreachable, token rejected, index still catching up) instead of a bare
+* `null`. `context()` itself never throws.
 */
 interface ContextSnapshot {
 	/** Token identity from `/api/accounts/me`. A self-hosted instance has no