@secondlayer/sdk 9.0.1 → 10.0.0

package/dist/index.d.ts

@@ -16,7 +16,30 @@ interface SecondLayerOptions {
 	dumpsBaseUrl?: string;
 	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
 	origin?: "cli" | "mcp" | "session";
+	/** Check the ed25519 signature on every Streams read. Omit for lenient
+	*  (verify when signed, pass through unsigned self-host responses), `true`
+	*  or `{ publicKey }` for strict, `false` for off. Reaches `sl.streams`. */
+	verify?: boolean | {
+		publicKey: string;
+	};
+	/** Check the dumps manifest signature before trusting any file hash
+	*  (default on). Reaches `sl.streams.dumps`. */
+	verifyDumpsManifest?: boolean;
+	/** How long one request may take, headers and body, before it fails with a
+	*  retryable `ApiError` (default 30 000 ms). A hung socket then trips the
+	*  retry policy instead of stalling a walk or consume loop forever. `0`
+	*  disables the timeout. */
+	requestTimeoutMs?: number;
 }
+/** Default per-request budget. Long enough for a 1000-row filtered page on a
+*  cold cache, short enough that a half-open connection surfaces as a retry. */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+/** Per-call options every `request*` method accepts. */
+type RequestOptions = {
+	/** Cancels the in-flight request (and its body read). The rejection is the
+	*  signal's reason, an `AbortError` by default, never an `ApiError`. */
+	signal?: AbortSignal;
+};
 /** Product default: the local one-box API. Override with `baseUrl` or `SL_API_URL`. */
 declare const LOCAL_API_URL = "http://127.0.0.1:3800";
 declare function resolveBaseUrl(explicit?: string): string;
@@ -50,14 +73,24 @@ declare abstract class BaseClient {
 	protected apiKey?: string;
 	protected origin: "cli" | "mcp" | "session";
 	protected fetchImpl: FetchLike;
+	protected requestTimeoutMs: number;
 	constructor(options?: Partial<SecondLayerOptions>);
 	static authHeaders(apiKey?: string): Record<string, string>;
-	protected request<T>(method: string, path: string, body?: unknown): Promise<T>;
+	protected request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
 	/** Like `request`, but maps a 404 to `null` instead of throwing — the one
 	*  place that owns the "absent resource" rule for `get*` accessors. */
-	protected requestOrNull<T>(method: string, path: string, body?: unknown): Promise<T | null>;
-	protected requestText(method: string, path: string, body?: unknown): Promise<string>;
-	private fetchResponse;
+	protected requestOrNull<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T | null>;
+	protected requestText(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<string>;
+	/** Run one request under the caller's signal plus the per-request timeout.
+	*  One combined signal covers the fetch and the body read, so a socket that
+	*  stalls mid-body times out the same way one that never answers does. A
+	*  timeout rejects with a retryable `ApiError`; a caller abort rejects with
+	*  the signal's reason so loops can tell "stop" from "try again". */
+	private withRequestBudget;
+	/** Issue the HTTP request and map non-2xx statuses onto the error family.
+	*  `signal` is the combined caller-plus-timeout signal from `request*`;
+	*  subclasses that stream a body call this directly and read it themselves. */
+	protected fetchResponse(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<Response>;
 }
 interface SubgraphSource {
 	name: string;
@@ -120,8 +153,10 @@ declare class Subgraphs extends BaseClient {
 	markdown(name: string, options?: SubgraphSpecOptions): Promise<string>;
 	/**
 	* 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.
+	* 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(name: string): Promise<{
@@ -129,6 +164,8 @@ declare class Subgraphs extends BaseClient {
 		operationId?: string;
 		status?: string;
 	}>;
+	/** Process one block range. 409 `OPERATION_IN_PROGRESS` while another
+	*  reindex or backfill runs on this subgraph. */
 	backfill(name: string, options: {
 		fromBlock: number;
 		toBlock: number;
@@ -158,6 +195,9 @@ declare class Subgraphs extends BaseClient {
 	/** Status of a single operation (poll the `operationId` returned by
 	*  reindex/backfill/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>;
 	getSource(name: string): Promise<SubgraphSource>;
 	/**
@@ -188,6 +228,13 @@ declare class Subgraphs extends BaseClient {
 		name: string;
 		schema: Record<string, unknown>;
 	}>(def: T): InferSubgraphClient<T>;
+	/**
+	* `columns` is the table's declared column set from `defineSubgraph()`.
+	* Filters and orderBy always accept the canonical system names
+	* `_id` / `_blockHeight` / `_txId` / `_createdAt`; the unprefixed
+	* shorthands (`id`, `blockHeight`, ...) mean the system column only when
+	* the table declares no column of that name.
+	*/
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
@@ -438,8 +485,11 @@ interface ConsumerSink<Tx = unknown> {
 	* same `rewindCursor` (the lowest fork point) but its own
 	* `forkPointHeight` — scope the undo by `forkPointHeight` only (contract
 	* invariant #11), and expect re-application after a crash (#10).
+	*
+	* `rewindCursor` is `null` only for a fork at genesis: clear the
+	* checkpoint so the next run starts from the first event.
 	*/
-	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+	rollback(forkPointHeight: number, rewindCursor: string | null): Promise<void>;
 }
 /** The transaction type a sink hands to `onBatch` (`ctx.tx`). */
 type SinkTx<S> = S extends ConsumerSink<infer Tx> ? Tx : never;
@@ -590,11 +640,41 @@ type StreamsEventsSubscribeParams = {
 	filters?: StreamsFilterMap;
 	/** Abort to unsubscribe (the returned function does the same). */
 	signal?: AbortSignal;
-	/** Called for each pushed event, in order. */
+	/**
+	* Called for each pushed event, in order. The resume cursor advances only
+	* after this resolves, so a handler that throws sees the same event again
+	* on reconnect (at-least-once). Key durable writes by `cursor`.
+	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
-	/** Called on a connection error; the subscription auto-reconnects from the
-	*  last delivered cursor unless the signal has aborted. */
+	/**
+	* Called on every failure. Transport errors (dropped socket, 5xx, 429, a
+	* stale connection, a throwing handler) reconnect from the last handled
+	* cursor with exponential backoff. Errors that a retry cannot fix (401,
+	* 4xx, a bad signature) end the subscription and reject its `done`.
+	*/
 	onError?: (err: unknown) => void;
+	/**
+	* First reconnect pause in ms (default 1000). Doubles per consecutive
+	* failure up to 30 s with jitter, resets once a frame arrives, and never
+	* undercuts a `Retry-After`.
+	*/
+	reconnectDelayMs?: number;
+	/**
+	* Reconnect when no frame (pings included) arrives for this long (default
+	* 60000, three server heartbeats). Catches a half-open socket that never
+	* errors; set it above your instance's heartbeat interval.
+	*/
+	staleAfterMs?: number;
+};
+/**
+* Handle for a live subscription: call it to unsubscribe. `done` resolves
+* after unsubscribe (or the signal aborting) and rejects with the error that
+* ended the loop when a retry could not fix it, so a worker can `await`
+* it instead of polling for silence.
+*/
+type StreamsSubscription = {
+	(): void;
+	done: Promise<void>;
 };
 /**
 * The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
@@ -659,8 +739,11 @@ type StreamsBatchContext = ConsumerBatchContext;
 * The checkpoint for a reorg rollback. Persist `cursor` (the rewind position)
 * inside the same transaction as your rollback so the two commit atomically.
 */
+/** `cursor` is the rewind position the loop resumes from after `onReorg`:
+*  the foot of the fork point, or `null` for a fork at genesis. Persist it
+*  in the same transaction as the rollback. */
 type StreamsReorgContext = {
-	cursor: string;
+	cursor: string | null;
 };
 type StreamsEventsConsumeParams<
 	TTx = never,
@@ -728,12 +811,23 @@ type StreamsEventsConsumeParams<
 	onBatch?: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>;
 	/**
 	* Roll your projection back to `reorg.fork_point_height`, persisting
-	* `ctx.cursor` in the same transaction. Called once per *new* reorg
-	* (deduped in-memory, fork-ascending) before the SDK rewinds and re-reads the
-	* now-canonical events. Omit it to ignore reorgs (events stay canonical, but
-	* stale rows from an orphaned fork are left in place).
+	* `ctx.cursor` in the same transaction. Called once per *new* reorg at or
+	* below the checkpoint (deduped in-memory, fork-ascending) before the SDK
+	* rewinds and re-reads the now-canonical events. A reorg whose fork sits
+	* above the checkpoint is not a rollback (nothing past it was written) and
+	* is skipped. Omit it to ignore reorgs (events stay canonical, but stale
+	* rows from an orphaned fork are left in place).
+	*
+	* With `onReorg` or a `sink` attached, every empty page also polls
+	* `reorgs.list` (one extra request per idle poll) so a fork that lands
+	* while the consumer idles at the tip is rolled back too.
 	*/
 	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void;
+	/** Deepest rewind one reorg may make below the checkpoint before the loop
+	*  refuses with `ValidationError`. Default 1000 blocks. The fork point is
+	*  server supplied and drives a delete on every declared table, so raise
+	*  this only for a source you trust. */
+	maxRollbackDepth?: number;
 	/** Page-fetch retries after the first failure (429/5xx/network only —
 	*  4xx and handler throws always propagate). Default 3; `0` disables. */
 	retryCount?: number;
@@ -796,8 +890,16 @@ type StreamsEventsReplayParams = {
 	* Called once per finalized dump file, in block order, before live tailing.
 	* Process the parquet with your own tooling (e.g. DuckDB) — the SDK does not
 	* decode parquet. Use `client.dumps.download(file)` to fetch + verify bytes.
+	*
+	* Delivery is file-granular and at-least-once: a file whose range straddles
+	* `from` is handed over whole. `ctx.from` is that cursor (`null` from
+	* genesis); skip rows at or below it, or key rows by `cursor` so a re-run
+	* is an idempotent no-op. Files ending at or below `from` are not handed
+	* over at all.
 	*/
-	onDumpFile: (file: StreamsDumpFile) => Promise<void> | void;
+	onDumpFile: (file: StreamsDumpFile, ctx: {
+		from: string | null;
+	}) => Promise<void> | void;
 	/** Called per live page after the dump phase, like `consume`. */
 	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined;
 	/**
@@ -933,9 +1035,11 @@ type StreamsClient = {
 		* 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.
+		* 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()`.
 		*/
-		subscribe(params: StreamsEventsSubscribeParams): () => void;
+		subscribe(params: StreamsEventsSubscribeParams): StreamsSubscription;
 	};
 	blocks: {
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
@@ -1022,9 +1126,18 @@ type IndexConsumeOptions<
 	*  `consumerHealth().record`. */
 	onProgress?: (ctx: ConsumerBatchContext) => void;
 	onBatch: (items: TItem[], envelope: TEnvelope, ctx: ConsumerBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>;
+	/** Called once per new reorg at or below the checkpoint, before the loop
+	*  rewinds to `ctx.cursor` (`null` = pre-genesis) and re-reads. A reorg
+	*  whose fork sits ABOVE the checkpoint is not a rollback: nothing past
+	*  it was written, so it is noted and the page is read as normal. */
 	onReorg?: (reorg: IndexReorg, ctx: {
-		cursor: string;
+		cursor: string | null;
 	}) => Promise<void> | void;
+	/** Deepest rewind one reorg may make below the checkpoint before the loop
+	*  refuses with `ValidationError`. Default 1000 blocks. The fork point is
+	*  server supplied and drives a delete on every declared table, so raise
+	*  this only for a source you trust. */
+	maxRollbackDepth?: number;
 	sleep?: Sleep;
 	emptyBackoffMs?: number;
 	maxPages?: number;
@@ -1143,10 +1256,24 @@ type FtTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & {
+/** Largest page any Index list route serves. The server clamps `limit` above
+*  this without saying so, so `walk` refuses a bigger `batchSize` up front
+*  rather than paging in silently smaller steps. */
+declare const INDEX_MAX_PAGE_SIZE = 1e3;
+/** Options every `walk*` feed shares on top of its list filters. Page fetches
+*  retry with the same `retryCount`/`retryDelay`/`onError` vocabulary as
+*  `consume()`; the tradeoff is that a walk can pause for the retry delays
+*  instead of failing fast on the first 429. */
+type WalkOptions = PageRetryOptions & {
+	/** Rows per page request. Default 200, max `INDEX_MAX_PAGE_SIZE` (1000). */
 	batchSize?: number;
+	/** Stops the walk. The iterator always rejects with the signal's reason (an
+	*  `AbortError` by default), whether the abort lands during a page request
+	*  (which is cancelled) or between yields, so a caller can tell a finished
+	*  walk from a stopped one. */
 	signal?: AbortSignal;
 };
+type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & WalkOptions;
 type NftTransfer = {
 	cursor: string;
 	block_height: number;
@@ -1184,10 +1311,7 @@ type NftTransfersListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & WalkOptions;
 type IndexEventBase = {
 	cursor: string;
 	block_height: number;
@@ -1342,10 +1466,7 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	*/
 	fields?: readonly (keyof IndexEventOf<T> & string)[];
 };
-type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & WalkOptions;
 type EventsConsumeParams<
 	T extends IndexEventType = IndexEventType,
 	TTx = never
@@ -1385,10 +1506,7 @@ type ContractCallsListParams = {
 	*  Mutually exclusive with contractId. */
 	trait?: string;
 };
-type ContractCallsWalkParams = Omit<ContractCallsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+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
 *  for chain linkage, burn anchor for Bitcoin confirmations. Use `blocks` for
@@ -1413,10 +1531,7 @@ type CanonicalListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type CanonicalWalkParams = Omit<CanonicalListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type CanonicalWalkParams = Omit<CanonicalListParams, "limit"> & WalkOptions;
 /** A block resource. Metadata is intentionally thin — only chain-linkage and
 *  burn-anchor fields are persisted (no miner / tx_count / signer). */
 type IndexBlock = {
@@ -1445,10 +1560,7 @@ type BlocksListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type BlocksWalkParams = Omit<BlocksListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type BlocksWalkParams = Omit<BlocksListParams, "limit"> & WalkOptions;
 type IndexPostCondition = {
 	type: "stx";
 	principal: string;
@@ -1554,10 +1666,7 @@ type TransactionsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type TransactionsWalkParams = Omit<TransactionsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type TransactionsWalkParams = Omit<TransactionsListParams, "limit"> & WalkOptions;
 /** A decoded PoX-4 stacking action (one per stacking contract call). */
 type IndexStackingAction = {
 	cursor: string;
@@ -1601,10 +1710,7 @@ type StackingListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type StackingWalkParams = Omit<StackingListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+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
 *  a sequence cursor instead of a block position. */
@@ -1660,10 +1766,7 @@ type MempoolListParams = {
 	/** Filter to pending calls to a single function (composes with `contractId`). */
 	functionName?: string;
 };
-type MempoolWalkParams = Omit<MempoolListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+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
@@ -1855,10 +1958,7 @@ 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>;
-type SbtcDepositsWalkParams = Omit<SbtcDepositsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+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. */
@@ -1883,10 +1983,7 @@ type SbtcWithdrawalsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type SbtcWithdrawalsWalkParams = Omit<SbtcWithdrawalsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type SbtcWithdrawalsWalkParams = Omit<SbtcWithdrawalsListParams, "limit"> & WalkOptions;
 type SbtcEventsListParams = {
 	cursor?: string | null;
 	fromCursor?: string | null;
@@ -1899,10 +1996,7 @@ type SbtcEventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type SbtcEventsWalkParams = Omit<SbtcEventsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+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>;
 /** `index.sbtc` — the decoded sBTC peg surface (deposits, withdrawals, raw
@@ -1993,10 +2087,7 @@ type PoxCyclesListParams = {
 	cursor?: number | null;
 	limit?: number;
 };
-type PoxCyclesWalkParams = Omit<PoxCyclesListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type PoxCyclesWalkParams = Omit<PoxCyclesListParams, "limit"> & WalkOptions;
 /** `index.pox` — PoX reward-cycle aggregates. */
 interface PoxResource {
 	cycles: {
@@ -2071,10 +2162,7 @@ type Pox5EventsListParams = {
 	fromHeight?: number;
 	toHeight?: number;
 };
-type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & {
-	batchSize?: number;
-	signal?: AbortSignal;
-};
+type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & WalkOptions;
 /** `index.pox5` — decoded PoX-5 print events, the staking primitive from the
 *  epoch 4.0 hard fork onward (PoX-4's `index.stacking` stream ends there). */
 interface Pox5Resource {
@@ -2279,9 +2367,13 @@ declare class Index extends BaseClient {
 	private listNftTransfers;
 	/** Shared keyset-pagination loop for every `walk*` feed: seed the cursor from
 	*  `cursor`/`fromCursor` (and `fromHeight` 0 on the first page), then page until
-	*  the cursor stops advancing or a short page signals the tail. `list` merges the
-	*  resource's filter params; `itemsOf` selects the envelope's item array. PoX
-	*  cycles use a numeric cursor and are walked separately. */
+	*  the server stops advancing the cursor (`next_cursor` null or unchanged). A
+	*  short page is not a tail signal: the server clamps oversized limits without
+	*  saying so, so trusting page length truncated backfills. The cost is one
+	*  extra empty fetch at the end of feeds that never return a null cursor.
+	*  `list` merges the resource's filter params; `itemsOf` selects the envelope's
+	*  item array. Each page fetch retries under `fetchPageWithRetry`; the cursor
+	*  is a string keyset for every feed except PoX cycles, which use a number. */
 	private keysetWalk;
 	private walkFtTransfers;
 	private walkNftTransfers;
@@ -2370,23 +2462,48 @@ interface ActiveSubgraphOperation {
 	status: SubgraphOperationStatus["status"];
 	progress: number | null;
 }
+/** Why one snapshot field could not be read. Serialized from the SDK error
+*  family so a snapshot stays plain data. */
+interface ContextFieldError {
+	message: string;
+	/** Stable code from the API envelope (`UNAUTHORIZED`, `INDEX_NOT_READY`)
+	*  or the SDK (`REQUEST_TIMEOUT`); absent for a bare transport failure. */
+	code?: string;
+	/** HTTP status; `0` when the API could not be reached. */
+	status?: number;
+	/** Whether the same read can succeed on a retry (429, 5xx, network). */
+	retryable: boolean;
+}
+/** One snapshot field: the value, or `null` plus the error that produced it.
+*  `value: null` with no `error` means the read succeeded and found nothing. */
+interface ContextField<T> {
+	value: T | null;
+	error?: ContextFieldError;
+}
 /**
-* A point-in-time orientation snapshot for an agent: who you are, the live tips,
-* and what you own. Each field is `null` when it couldn't be read (e.g. no key,
-* or a free-tier key for a Build+ surface) so the snapshot never throws.
+* 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.
 */
 interface ContextSnapshot {
-	account: ContextAccount | null;
-	streamsTip: StreamsTip | null;
-	indexTip: IndexTip | null;
-	subgraphs: SubgraphSummary2[] | null;
-	subscriptions: {
+	/** Token identity from `/api/accounts/me`. A self-hosted instance has no
+	*  account system: the read 404s and the field carries that error. */
+	account: ContextField<ContextAccount>;
+	streamsTip: ContextField<StreamsTip>;
+	indexTip: ContextField<IndexTip>;
+	subgraphs: ContextField<SubgraphSummary2[]>;
+	subscriptions: ContextField<{
 		count: number;
 		byStatus: Record<string, number>;
-	} | null;
+	}>;
 	/** In-flight reindex operations (bounded to subgraphs reporting `reindexing`). */
-	activeOperations: ActiveSubgraphOperation[] | null;
+	activeOperations: ContextField<ActiveSubgraphOperation[]>;
 }
+/** Fold one read into a {@link ContextField}: the value, or `null` with the
+*  failure described. Exported for callers that assemble their own snapshot
+*  from extra reads and want the same shape. */
+declare function contextField<T>(read: Promise<T>): Promise<ContextField<T>>;
 declare class SecondLayer extends BaseClient {
 	readonly streams: StreamsClient;
 	readonly index: Index;
@@ -2395,14 +2512,8 @@ declare class SecondLayer extends BaseClient {
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
-	* Assemble a {@link ContextSnapshot} — the same orientation an MCP agent reads
-	* from `secondlayer://context`, but available to any SDK/CLI consumer. Reads
-	* run concurrently and degrade to `null` per field on failure.
-	*/
-	/**
 	* Up to 10 public reads in one round trip (`POST /v1/batch`). Each item
-	* keeps its own auth/quota/x402 semantics; forwarded credentials (API key,
-	* PAYMENT-BALANCE/SESSION) apply to every item.
+	* is authorized on its own; the client's bearer token applies to every item.
 	*/
 	batch(requests: Array<{
 		path: string;
@@ -2414,6 +2525,12 @@ declare class SecondLayer extends BaseClient {
 			body: unknown;
 		}>;
 	}>;
+	/**
+	* 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.
+	*/
 	context(): Promise<ContextSnapshot>;
 }
 /**
@@ -2437,6 +2554,8 @@ declare function getSubgraph<T extends {
 type CreateStreamsClientOptions = {
 	apiKey?: string;
 	baseUrl?: string;
+	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
+	origin?: "cli" | "mcp" | "session";
 	fetchImpl?: FetchLike2;
 	/**
 	* Public base URL for bulk parquet dumps (the R2/CDN bucket root). Required
@@ -2564,37 +2683,32 @@ declare class ApiError extends SecondLayerError {
 	body?: unknown;
 	constructor(status: number, message: string, body?: unknown, code?: string, options?: SecondLayerErrorOptions);
 }
-/** Thrown on a 401 — by both the platform clients and Streams. */
+/** Thrown on a 401 by both the instance clients and Streams. Carries the
+*  server's `{error, code}` envelope when it sent one, so a revoked token reads
+*  differently from a missing one. */
 declare class AuthError extends ApiError {
 	readonly status: 401;
-	constructor(message?: string);
+	constructor(message?: string, body?: unknown, code?: string);
 }
-/** Thrown on a 429 — by both the platform clients and Streams. `retryable`,
+/** Thrown on a 429 by both the instance clients and Streams. `retryable`,
 *  with `retryAfterSeconds` parsed from the `Retry-After` header when sent. */
 declare class RateLimitError extends ApiError {
 	/** Raw `Retry-After` header value (seconds or HTTP-date). */
 	readonly retryAfter?: string | undefined;
 	readonly status: 429;
-	constructor(message?: string, retryAfter?: string | undefined);
+	constructor(message?: string, retryAfter?: string | undefined, body?: unknown, code?: string);
 }
-/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried. */
+/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried.
+*  `code` is the server's machine-readable code when the envelope carried one. */
 declare class ValidationError extends ApiError {
-	constructor(message: string, status: number, body?: unknown);
+	constructor(message: string, status: number, body?: unknown, code?: string);
 }
 /** Parse a `Retry-After` header: delta-seconds or an HTTP-date. */
 declare function parseRetryAfter(value?: string | null): number | undefined;
-/**
-* Thrown on optimistic-concurrency conflict when a deploy supplies an
-* `expectedVersion` that no longer matches the server's stored version.
-*/
-declare class VersionConflictError extends ApiError {
-	currentVersion: string;
-	expectedVersion: string;
-	constructor(currentVersion: string, expectedVersion: string, message?: string);
-}
-/** Thrown on a 5xx from the Streams API. `retryable`. */
+/** Thrown on a 5xx from the Streams API, and on a failed signing-key fetch.
+*  `retryable`: the page retry policy tries again. */
 declare class StreamsServerError extends ApiError {
-	constructor(message: string, status: number, body?: unknown);
+	constructor(message: string, status: number, body?: unknown, code?: string);
 }
 /** Thrown when response signature verification is enabled and fails. */
 declare class StreamsSignatureError extends SecondLayerError {
@@ -2606,7 +2720,9 @@ import { DecodedEventColumns, DecodedEventRow, DecodedFtBurn, DecodedFtBurnPaylo
 * Helpers for Streams cursors. A cursor is the opaque `<block>:<index>` string
 * that marks a position in the event stream; treat the format as an
 * implementation detail and go through these helpers instead of string-building
-* it at call sites.
+* it at call sites. Encode/decode and the rewind sentinel come from the
+* canonical codec in `@secondlayer/shared` so the SDK cannot accept a spelling
+* the server would 400, or rewind to a different foot than Index/Streams.
 */
 declare const Cursor: {
 	/**
@@ -2618,14 +2734,19 @@ declare const Cursor: {
 	* is `height`: the new canonical block at `height` carries a fresh first
 	* event at `(height, 0)` that the consumer MUST re-read.
 	*
-	* Encoded as `${height-1}:${SENTINEL}` rather than the seemingly-natural
+	* Encoded as `blockEndCursor(height - 1)` rather than the seemingly-natural
 	* `${height}:0` — that earlier form was an off-by-one: being exclusive, it
 	* skipped `(height, 0)`, silently dropping the fork block's first row on
 	* every reorg. The sentinel is int4 max (the `event_index`/`tx_index` column
 	* type), larger than any real index, so nothing at `height - 1` survives the
 	* keyset and the next returned row is exactly `(height, 0)`.
+	*
+	* `atHeight(0)` is `null`: the pre-genesis position both consume loops
+	* accept as "read everything from the first event". There is no string
+	* cursor below `0:0`, and `0:0` itself is exclusive, so returning it here
+	* skipped the genesis event.
 	*/
-	atHeight(height: number): string;
+	atHeight(height: number): string | null;
 	/** Parse a `<block>:<index>` cursor. Throws `ValidationError` if malformed. */
 	parse(cursor: string): {
 		blockHeight: number;
@@ -2832,4 +2953,4 @@ declare function verifySecondlayerSignature(rawBody: string, headers: WebhookHea
 declare function decodeChainWebhook(rawBody: string): ChainWebhookDelivery;
 import { RewardSet as RewardSet2 } from "@secondlayer/shared/node/consensus";
 import { decodeClarityValue, toJsonSafe } from "@secondlayer/shared/streams-rows";
-export { verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, resolveBaseUrl, resolveApiKey, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, decode, createStreamsClient, consumerHealth, consumeIndexFeed, WithSinkTx, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SinkTx, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, LOCAL_API_URL, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEventFields, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, IndexAlwaysFields, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload2 as FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextAccount, ConsumerSink, ConsumerHealth, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CREDENTIAL_ENV_VARS, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiError, ActiveSubgraphOperation };
+export { verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, resolveBaseUrl, resolveApiKey, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, decode, createStreamsClient, contextField, consumerHealth, consumeIndexFeed, WithSinkTx, WebhookHeaderInput, WalkOptions, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsSubscription, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SinkTx, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, RequestOptions, ReplayResult2 as ReplayResult, RateLimitError, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, LOCAL_API_URL, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEventFields, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, IndexAlwaysFields, Index, INDEX_MAX_PAGE_SIZE, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload2 as FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, DeliveryRow2 as DeliveryRow, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, DeadRow2 as DeadRow, DEFAULT_REQUEST_TIMEOUT_MS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextFieldError, ContextField, ContextAccount, ConsumerSink, ConsumerHealth, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, CREDENTIAL_ENV_VARS, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiError, ActiveSubgraphOperation };