@secondlayer/sdk 10.1.1 → 10.2.0

package/README.md

@@ -234,6 +234,36 @@ await streams.events.replay({
 });
 ```
 
+Archive.
+
+Signed canonical partitions (`blocks` / `transactions` / `events`), distinct
+from Streams dumps. `latest` follows `latest.json` and verifies the ed25519
+manifest (default on). `quote` and `fetch` need an account key (`sk-sl_*`)
+against `api.secondlayer.tools`, not the instance `baseUrl`. `download`
+returns sha256-verified bytes; it does not decode parquet. Verify, repair,
+and bootstrap remain CLI.
+
+```typescript
+const sl = new SecondLayer({
+  apiKey: process.env.SL_API_KEY, // account key sk-sl_* for quote/fetch/credits
+});
+
+const ref = await sl.archive.latest();
+const partitions = sl.archive.partitions(ref, { dataset: "blocks" });
+const quote = await sl.archive.quote({
+  paths: partitions.map((p) => p.path),
+  flow: "bootstrap",
+});
+const fetched = await sl.archive.fetch({
+  paths: partitions.map((p) => p.path),
+  flow: "bootstrap",
+});
+for (const item of fetched.urls) {
+  const partition = partitions.find((p) => p.path === item.path)!;
+  const bytes = await sl.archive.download(partition, { url: item.url });
+}
+```
+
 Decoder helper.
 
 ```typescript

package/dist/index.d.ts

@@ -14,6 +14,12 @@ interface SecondLayerOptions {
 	*  Required for `streams.dumps.*`; without it the dumps client falls back to
 	*  its built-in default. */
 	dumpsBaseUrl?: string;
+	/** Public base URL for the signed canonical archive tree. Defaults to
+	*  `https://archive.secondlayer.tools`. Reaches `sl.archive`. */
+	archiveBaseUrl?: string;
+	/** Credits and fetch-gate API. Defaults to `https://api.secondlayer.tools`,
+	*  not `baseUrl`. Reaches `sl.archive` quote/fetch/credits. */
+	archiveOpsUrl?: 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
@@ -238,7 +244,156 @@ declare class Subgraphs extends BaseClient {
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
+import { InstanceDiagnosis as InstanceDiagnosis2 } from "@secondlayer/shared/archive/instance-diagnosis";
 import { SubgraphSummary as SubgraphSummary2 } from "@secondlayer/shared/schemas";
+import { InstanceDiagnosis, PublicStatus } from "@secondlayer/shared/archive/instance-diagnosis";
+/** Structural `/public/status` payload. Extra fields are ignored by diagnosis. */
+type InstanceStatus = PublicStatus;
+type InstanceClient = {
+	status(): Promise<InstanceStatus>;
+	diagnose(): Promise<InstanceDiagnosis>;
+};
+type ArchiveVerifyInput = {
+	against: string;
+	target?: string;
+	fromBlock?: number;
+	toBlock?: number;
+	insecure?: boolean;
+	publicKeyPem?: string;
+};
+type ArchiveVerifyRangeStatus = "match" | "digest-mismatch" | "count-mismatch" | "missing";
+type ArchiveVerifyResult = {
+	status: "clean" | "diverged" | "unanchored";
+	target: string;
+	against: string;
+	signature: {
+		verified: boolean;
+		reason?: string;
+	};
+	coverage?: {
+		from_block: number;
+		to_block: number;
+	};
+	ranges: Array<{
+		dataset: string;
+		from_block: number;
+		to_block: number;
+		status: ArchiveVerifyRangeStatus;
+		expected_digest: string | null;
+		actual_digest: string | null;
+	}>;
+	reason?: string;
+};
+import { RangeDigest } from "@secondlayer/shared/archive/range-digest";
+type ArchiveDataset = "blocks" | "transactions" | "events";
+type ArchiveFlow = "bootstrap" | "repair";
+type ArchivePartition = {
+	dataset: string;
+	from_block: number;
+	to_block: number;
+	path: string;
+	row_count: number;
+	byte_size: number;
+	sha256: string;
+};
+type ArchiveManifest = {
+	network?: string;
+	coverage?: {
+		from_block: number;
+		to_block: number;
+	};
+	partition_size_blocks?: number;
+	range_digests?: RangeDigest[];
+	partitions?: ArchivePartition[];
+	signature?: string;
+	key_id?: string;
+	[key: string]: unknown;
+};
+type LoadedArchive = {
+	manifest: ArchiveManifest;
+	origin: string;
+	root: string;
+	isRemote: boolean;
+	signature: {
+		verified: boolean;
+		reason?: string;
+	};
+};
+type ArchiveQuote = {
+	partitions: number;
+	bundles: number;
+	usdMicros: number;
+	usd: string;
+	freeAllowanceAppliedMicros: number;
+	allowanceRemainingBundles: number;
+	balanceUsdMicros: number;
+	sufficient: boolean;
+};
+type ArchiveFetchItem = {
+	path: string;
+	url: string;
+	expiresAt: string;
+	chargedUsdMicros: number;
+};
+type ArchiveFetchResult = {
+	urls: ArchiveFetchItem[];
+	chargedTotalUsdMicros: number;
+	balanceAfterUsdMicros: number;
+};
+type ArchiveCreditsBalance = {
+	creditsUsdMicros: string;
+	refill: {
+		belowUsd: number | null;
+		packUsd: number | null;
+		lastAt: string | null;
+	};
+};
+type ArchiveLoadOptions = {
+	insecure?: boolean;
+};
+type ArchiveClient = {
+	latest(against?: string, opts?: ArchiveLoadOptions): Promise<LoadedArchive>;
+	load(against: string, opts?: ArchiveLoadOptions): Promise<LoadedArchive>;
+	status(): Promise<unknown>;
+	partitions(ref: LoadedArchive, filter?: {
+		dataset?: ArchiveDataset;
+		fromBlock?: number;
+		toBlock?: number;
+	}): ArchivePartition[];
+	quote(input: {
+		paths: string[];
+		flow: ArchiveFlow;
+	}): Promise<ArchiveQuote>;
+	fetch(input: {
+		paths: string[];
+		flow: ArchiveFlow;
+	}): Promise<ArchiveFetchResult>;
+	download(partition: ArchivePartition, opts?: {
+		url?: string;
+	}): Promise<Uint8Array>;
+	credits: {
+		balance(): Promise<ArchiveCreditsBalance>;
+		checkout(input: {
+			email: string;
+			pack: 10 | 25 | 50 | 100;
+		}): Promise<{
+			url: string;
+		}>;
+		refill(input: {
+			belowUsd: number;
+			packUsd: 10 | 25 | 50 | 100;
+		} | {
+			off: true;
+		}): Promise<{
+			belowUsd: number | null;
+			packUsd: number | null;
+		}>;
+	};
+};
+/** Hosted archive client plus instance `verify`. `status()` is still the public archive tree. */
+type SecondLayerArchive = ArchiveClient & {
+	verify(input: ArchiveVerifyInput): Promise<ArchiveVerifyResult>;
+};
 /**
 * Typed client for the contract-discovery API (`GET /v1/contracts`).
 *
@@ -2501,6 +2656,8 @@ interface ContextSnapshot {
 	}>;
 	/** In-flight reindex operations (bounded to subgraphs reporting `reindexing`). */
 	activeOperations: ContextField<ActiveSubgraphOperation[]>;
+	/** Decoder lag / empty-index from `GET /public/status`. */
+	instance: ContextField<InstanceDiagnosis2>;
 }
 /** Fold one read into a {@link ContextField}: the value, or `null` with the
 *  failure described. Exported for callers that assemble their own snapshot
@@ -2512,6 +2669,8 @@ declare class SecondLayer extends BaseClient {
 	readonly contracts: Contracts;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
+	readonly archive: SecondLayerArchive;
+	readonly instance: InstanceClient;
 	constructor(options?: Partial<SecondLayerOptions>);
 	/**
 	* Up to 10 public reads in one round trip (`POST /v1/batch`). Each item
@@ -2705,6 +2864,23 @@ declare class RateLimitError extends ApiError {
 declare class ValidationError extends ApiError {
 	constructor(message: string, status: number, body?: unknown, code?: string);
 }
+/** Thrown when an archive manifest signature is missing or does not verify. */
+declare class ArchiveSignatureError extends SecondLayerError {
+	constructor(message?: string);
+}
+/** Thrown on a 401 from the archive ops host (quote/fetch/credits). */
+declare class ArchiveAuthError extends SecondLayerError {
+	constructor(message?: string);
+}
+/** Thrown on a 402 from archive fetch — prepaid credits do not cover the quote. */
+declare class InsufficientArchiveCreditsError extends SecondLayerError {
+	shortfallUsdMicros?: number;
+	constructor(message?: string, shortfallUsdMicros?: number);
+}
+/** Thrown on a 503 when the archive fetch gate is unconfigured. */
+declare class ArchiveGateNotConfiguredError extends SecondLayerError {
+	constructor(message?: string);
+}
 /** Parse a `Retry-After` header: delta-seconds or an HTTP-date. */
 declare function parseRetryAfter(value?: string | null): number | undefined;
 /** Thrown on a 5xx from the Streams API, and on a failed signing-key fetch.
@@ -2755,6 +2931,7 @@ declare const Cursor: {
 		eventIndex: number;
 	};
 };
+import { InstanceDiagnosis as InstanceDiagnosis3, InstanceIssue, InstanceState, PublicStatus as PublicStatus2 } from "@secondlayer/shared/archive/instance-diagnosis";
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
 /**
 * The two pieces every "deploy a consumer" guide leaves out, packaged:
@@ -2797,6 +2974,15 @@ declare function consumerHealth(options?: {
 declare function shutdownSignal(options?: {
 	signals?: readonly ("SIGTERM" | "SIGINT")[];
 }): AbortSignal;
+type CreateArchiveClientOptions = {
+	apiKey?: string;
+	fetchImpl?: FetchLike;
+	archiveBaseUrl?: string;
+	archiveOpsUrl?: string;
+	verifyManifest?: boolean;
+	publicKeyPem?: string;
+};
+declare function createArchiveClient(options?: CreateArchiveClientOptions): ArchiveClient;
 import { ChainWebhookDelivery } from "@secondlayer/shared";
 import { StandardWebhooksHeaders } from "@secondlayer/shared/crypto/standard-webhooks";
 import { StandardWebhooksHeaders as StandardWebhooksHeaders2, verify } from "@secondlayer/shared/crypto/standard-webhooks";
@@ -2955,4 +3141,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, 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 };
+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, createArchiveClient, 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, SecondLayerArchive, 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, PublicStatus2 as PublicStatus, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, LoadedArchive, LOCAL_API_URL, InsufficientArchiveCreditsError, InstanceStatus, InstanceState, InstanceIssue, InstanceDiagnosis3 as InstanceDiagnosis, InstanceClient, 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, CreateArchiveClientOptions, 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, ArchiveVerifyResult, ArchiveVerifyRangeStatus, ArchiveVerifyInput, ArchiveSignatureError, ArchiveQuote, ArchivePartition, ArchiveManifest, ArchiveLoadOptions, ArchiveGateNotConfiguredError, ArchiveFlow, ArchiveFetchResult, ArchiveFetchItem, ArchiveDataset, ArchiveCreditsBalance, ArchiveClient, ArchiveAuthError, ApiError, ActiveSubgraphOperation };

package/dist/index.js

@@ -110,6 +110,39 @@ class ValidationError extends ApiError {
     this.name = "ValidationError";
   }
 }
+
+class ArchiveSignatureError extends SecondLayerError {
+  constructor(message = "Archive manifest signature is missing or invalid.") {
+    super(message, { code: "ARCHIVE_SIGNATURE", retryable: false });
+    this.name = "ArchiveSignatureError";
+  }
+}
+
+class ArchiveAuthError extends SecondLayerError {
+  constructor(message = "Archive ops request was not authenticated.") {
+    super(message, { code: "ARCHIVE_AUTH", retryable: false });
+    this.name = "ArchiveAuthError";
+  }
+}
+
+class InsufficientArchiveCreditsError extends SecondLayerError {
+  shortfallUsdMicros;
+  constructor(message = "Insufficient archive credits.", shortfallUsdMicros) {
+    super(message, {
+      code: "INSUFFICIENT_ARCHIVE_CREDITS",
+      retryable: false
+    });
+    this.name = "InsufficientArchiveCreditsError";
+    this.shortfallUsdMicros = shortfallUsdMicros;
+  }
+}
+
+class ArchiveGateNotConfiguredError extends SecondLayerError {
+  constructor(message = "The archive gate is not configured on the server.") {
+    super(message, { code: "ARCHIVE_GATE_NOT_CONFIGURED", retryable: false });
+    this.name = "ArchiveGateNotConfiguredError";
+  }
+}
 function parseRetryAfter(value) {
   if (!value)
     return;
@@ -814,6 +847,239 @@ class Subgraphs extends BaseClient {
     };
   }
 }
+// src/archive/client.ts
+import { createHash } from "node:crypto";
+import {
+  checkSignature,
+  loadReference
+} from "@secondlayer/shared/archive/reference";
+var OFFICIAL_ARCHIVE_HOST = "archive.secondlayer.tools";
+var DEFAULT_ARCHIVE_BASE_URL = "https://archive.secondlayer.tools";
+var DEFAULT_ARCHIVE_OPS_URL = "https://api.secondlayer.tools";
+var MAX_FETCH_BATCH = 64;
+function quoteFromBody(body) {
+  return {
+    partitions: body.partitions,
+    bundles: body.bundles,
+    usdMicros: body.usd_micros,
+    usd: body.usd,
+    freeAllowanceAppliedMicros: body.free_allowance_applied_micros,
+    allowanceRemainingBundles: body.allowance_remaining_bundles,
+    balanceUsdMicros: body.balance_usd_micros,
+    sufficient: body.sufficient
+  };
+}
+function stripSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function createArchiveClient(options = {}) {
+  const apiKey = resolveApiKey(options.apiKey);
+  const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+  const archiveBaseUrl = stripSlash(options.archiveBaseUrl ?? DEFAULT_ARCHIVE_BASE_URL);
+  const archiveOpsUrl = stripSlash(options.archiveOpsUrl ?? DEFAULT_ARCHIVE_OPS_URL);
+  const verifyManifest = options.verifyManifest ?? true;
+  const pinnedPem = options.publicKeyPem;
+  let keyPromise = null;
+  async function fetchSigningKey() {
+    if (pinnedPem)
+      return pinnedPem;
+    if (keyPromise)
+      return keyPromise;
+    const pending = (async () => {
+      const res = await fetchImpl(`${archiveOpsUrl}/public/streams/signing-key`);
+      if (!res.ok) {
+        throw new ArchiveSignatureError(`Could not fetch archive signing key (${res.status}).`);
+      }
+      const body = await res.json();
+      if (typeof body.public_key_pem !== "string") {
+        throw new ArchiveSignatureError("Signing key response missing key.");
+      }
+      return body.public_key_pem;
+    })();
+    keyPromise = pending;
+    pending.catch(() => {
+      if (keyPromise === pending)
+        keyPromise = null;
+    });
+    return pending;
+  }
+  async function throwOpsError(response) {
+    const envelope = parseErrorEnvelope(await response.text());
+    if (response.status === 401) {
+      throw new ArchiveAuthError(envelope.message ?? "Archive ops request was not authenticated.");
+    }
+    if (response.status === 402) {
+      const raw = envelope.body && typeof envelope.body === "object" && "shortfall_usd_micros" in envelope.body ? Number(envelope.body.shortfall_usd_micros) : undefined;
+      throw new InsufficientArchiveCreditsError(envelope.message ?? "Insufficient archive credits.", Number.isFinite(raw) ? raw : undefined);
+    }
+    if (response.status === 503) {
+      throw new ArchiveGateNotConfiguredError(envelope.message ?? "The archive gate is not configured on the server.");
+    }
+    throw new ApiError(response.status, envelope.message ?? `Archive ops returned ${response.status}.`, envelope.body, envelope.code);
+  }
+  async function opsRequest(method, path, body, authed = true) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (authed && apiKey)
+      headers.Authorization = `Bearer ${apiKey}`;
+    const response = await fetchImpl(`${archiveOpsUrl}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined
+    });
+    if (!response.ok)
+      await throwOpsError(response);
+    return await response.json();
+  }
+  async function load(against, opts = {}) {
+    if (!/^https?:\/\//i.test(against)) {
+      throw new ValidationError("archive.load() accepts only http(s) URLs; local paths stay on the CLI.", 400);
+    }
+    const insecure = opts.insecure === true;
+    const publicKeyPem = pinnedPem ?? (verifyManifest && !insecure ? await fetchSigningKey() : undefined);
+    const ref = await loadReference(against, {
+      publicKeyPem,
+      fetchImpl
+    });
+    const signature = checkSignature(ref.manifest, publicKeyPem, insecure);
+    if (verifyManifest && !insecure && !signature.verified) {
+      throw new ArchiveSignatureError(signature.reason ?? "Archive manifest signature is missing or invalid.");
+    }
+    return { ...ref, signature };
+  }
+  async function latest(against, opts = {}) {
+    return load(against ?? `${archiveBaseUrl}/latest.json`, opts);
+  }
+  async function status() {
+    const response = await fetchImpl(`${archiveBaseUrl}/status.json`);
+    if (!response.ok) {
+      throw new ApiError(response.status, `Could not fetch archive status (${response.status}).`);
+    }
+    return response.json();
+  }
+  function partitions(ref, filter) {
+    let list = ref.manifest.partitions ?? [];
+    if (!filter)
+      return list;
+    if (filter.dataset) {
+      list = list.filter((p) => p.dataset === filter.dataset);
+    }
+    const fromBlock = filter.fromBlock;
+    if (fromBlock !== undefined) {
+      list = list.filter((p) => p.to_block >= fromBlock);
+    }
+    const toBlock = filter.toBlock;
+    if (toBlock !== undefined) {
+      list = list.filter((p) => p.from_block <= toBlock);
+    }
+    return list;
+  }
+  async function quote(input) {
+    const body = await opsRequest("POST", "/api/archive/quote", { paths: input.paths, flow: input.flow });
+    return quoteFromBody(body);
+  }
+  async function fetchPartitions(input) {
+    const urls = [];
+    let chargedTotalUsdMicros = 0;
+    let balanceAfterUsdMicros = 0;
+    for (let i = 0;i < input.paths.length; i += MAX_FETCH_BATCH) {
+      const chunk = input.paths.slice(i, i + MAX_FETCH_BATCH);
+      const body = await opsRequest("POST", "/api/archive/fetch", { paths: chunk, flow: input.flow });
+      for (const item of body.urls) {
+        urls.push({
+          path: item.path,
+          url: item.url,
+          expiresAt: item.expires_at,
+          chargedUsdMicros: item.charged_usd_micros
+        });
+      }
+      chargedTotalUsdMicros += body.charged_total_usd_micros;
+      balanceAfterUsdMicros = body.balance_after_usd_micros;
+    }
+    return { urls, chargedTotalUsdMicros, balanceAfterUsdMicros };
+  }
+  async function download(partition, opts) {
+    let url = opts?.url;
+    if (!url) {
+      let official = false;
+      try {
+        official = new URL(archiveBaseUrl).hostname === OFFICIAL_ARCHIVE_HOST;
+      } catch {
+        official = false;
+      }
+      if (official) {
+        throw new ValidationError("Official archive host requires a presigned URL from archive.fetch() before download.", 400);
+      }
+      url = `${archiveBaseUrl}/${partition.path.replace(/^\/+/, "")}`;
+    }
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+      throw new ApiError(response.status, `Could not download ${partition.path} (${response.status}).`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== partition.sha256) {
+      throw new ArchiveSignatureError(`${partition.path} sha256 mismatch (expected ${partition.sha256}, got ${digest}).`);
+    }
+    return bytes;
+  }
+  return {
+    latest,
+    load,
+    status,
+    partitions,
+    quote,
+    fetch: fetchPartitions,
+    download,
+    credits: {
+      async balance() {
+        const body = await opsRequest("GET", "/api/billing/status");
+        return {
+          creditsUsdMicros: body.creditsUsdMicros,
+          refill: body.refill
+        };
+      },
+      async checkout(input) {
+        const body = await opsRequest("POST", "/api/public/credits/checkout", { email: input.email, amount: input.pack }, false);
+        return { url: body.url };
+      },
+      async refill(input) {
+        const payload = "off" in input && input.off ? { belowUsd: null } : {
+          belowUsd: input.belowUsd,
+          packUsd: input.packUsd
+        };
+        const body = await opsRequest("POST", "/api/billing/refill", payload);
+        return { belowUsd: body.belowUsd, packUsd: body.packUsd };
+      }
+    }
+  };
+}
+
+// src/archive/instance.ts
+import {
+  diagnoseInstanceStatus
+} from "@secondlayer/shared/archive/instance-diagnosis";
+function createArchiveVerify(request) {
+  return (input) => request("POST", "/v1/archive/verify", {
+    against: input.against,
+    target: input.target ?? "raw",
+    from_block: input.fromBlock,
+    to_block: input.toBlock,
+    insecure: input.insecure,
+    public_key_pem: input.publicKeyPem
+  });
+}
+function createInstanceClient(request) {
+  async function status() {
+    return request("GET", "/public/status");
+  }
+  async function diagnose() {
+    return diagnoseInstanceStatus(await status());
+  }
+  return { status, diagnose };
+}
+
 // src/contracts/client.ts
 class Contracts extends BaseClient {
   constructor(options = {}) {
@@ -1786,7 +2052,7 @@ function decode(event) {
 }
 
 // src/streams/dumps.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { verifyStreamsBulkManifestSignature } from "@secondlayer/shared/streams-bulk-manifest";
 function createStreamsDumps(opts) {
   const baseUrl = opts.baseUrl?.replace(/\/+$/, "");
@@ -1838,7 +2104,7 @@ function createStreamsDumps(opts) {
     if (!res.body) {
       throw new StreamsServerError(`Dump ${file.path} response has no body.`, 0);
     }
-    const hash = createHash("sha256");
+    const hash = createHash2("sha256");
     const chunks = [];
     let total = 0;
     const reader = res.body.getReader();
@@ -2232,6 +2498,8 @@ class SecondLayer extends BaseClient {
   contracts;
   subgraphs;
   subscriptions;
+  archive;
+  instance;
   constructor(options = {}) {
     super(options);
     this.streams = createStreamsClient({
@@ -2247,17 +2515,36 @@ class SecondLayer extends BaseClient {
     this.contracts = new Contracts(options);
     this.subgraphs = new Subgraphs(options);
     this.subscriptions = new Subscriptions(options);
+    const request = (method, path, body) => this.request(method, path, body);
+    this.archive = {
+      ...createArchiveClient({
+        apiKey: this.apiKey,
+        fetchImpl: options.fetchImpl,
+        archiveBaseUrl: options.archiveBaseUrl,
+        archiveOpsUrl: options.archiveOpsUrl
+      }),
+      verify: createArchiveVerify(request)
+    };
+    this.instance = createInstanceClient(request);
   }
   async batch(requests) {
     return this.request("POST", "/v1/batch", { requests });
   }
   async context() {
-    const [account, streamsTip, indexEnv, subgraphsRes, subscriptionsRes] = await Promise.all([
+    const [
+      account,
+      streamsTip,
+      indexEnv,
+      subgraphsRes,
+      subscriptionsRes,
+      instance
+    ] = await Promise.all([
       contextField(this.request("GET", "/api/accounts/me")),
       contextField(this.streams.tip()),
       contextField(this.index.canonical.list({ limit: 1 })),
       contextField(this.subgraphs.list()),
-      contextField(this.subscriptions.list())
+      contextField(this.subscriptions.list()),
+      contextField(this.instance.diagnose())
     ]);
     const subgraphs = {
       value: subgraphsRes.value?.data ?? null,
@@ -2309,7 +2596,8 @@ class SecondLayer extends BaseClient {
       },
       subgraphs,
       subscriptions,
-      activeOperations
+      activeOperations,
+      instance
     };
   }
 }
@@ -2591,6 +2879,7 @@ export {
   decodeChainWebhook,
   decode,
   createStreamsClient,
+  createArchiveClient,
   contextField,
   consumerHealth,
   consumeIndexFeed,
@@ -2603,6 +2892,7 @@ export {
   SecondLayer,
   RateLimitError,
   LOCAL_API_URL,
+  InsufficientArchiveCreditsError,
   Index,
   INDEX_MAX_PAGE_SIZE,
   DEFAULT_REQUEST_TIMEOUT_MS,
@@ -2610,8 +2900,11 @@ export {
   Contracts,
   CREDENTIAL_ENV_VARS,
   AuthError,
+  ArchiveSignatureError,
+  ArchiveGateNotConfiguredError,
+  ArchiveAuthError,
   ApiError
 };
 
-//# debugId=CDF488058C75012864756E2164756E21
+//# debugId=ACBBAC86B270FAEA64756E2164756E21
 //# sourceMappingURL=index.js.map