@secondlayer/sdk 10.1.1 → 10.3.0

package/dist/subgraphs/index.d.ts

@@ -6,14 +6,23 @@ type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<
 interface SecondLayerOptions {
 	/** Base URL of the instance API (trailing slashes are stripped). */
 	baseUrl: string;
-	/** Bearer token for authenticated requests. */
+	/** Bearer token for authenticated instance requests (`INSTANCE_TOKEN`). */
 	apiKey?: string;
+	/** Hosted account key (`sk-sl_*`). Env `SECONDLAYER_API_KEY`. Used by
+	*  `sl.archive` quote/fetch/credits, never by instance `/v1` or `/api`. */
+	accountKey?: string;
 	/** Fetch implementation. Tests and edge runtimes can provide their own. */
 	fetchImpl?: FetchLike;
 	/** Public base URL for Streams bulk parquet dumps (the cold backfill plane).
 	*  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
@@ -207,7 +216,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`).
 *
@@ -2386,6 +2544,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>;
 }
 declare class SecondLayer extends BaseClient {
 	readonly streams: StreamsClient;
@@ -2393,6 +2553,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

package/dist/subgraphs/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;
@@ -139,33 +172,55 @@ function raceAbort(promise, signal) {
   });
 }
 var LOCAL_API_URL = "http://127.0.0.1:3800";
+var INSTANCE_TOKEN_ENV = "INSTANCE_TOKEN";
+var ACCOUNT_KEY_ENV = "SECONDLAYER_API_KEY";
+var warnedUrlAlias = false;
 function resolveBaseUrl(explicit) {
   if (explicit && explicit.length > 0)
     return explicit.replace(/\/+$/, "");
   if (typeof process !== "undefined") {
-    const fromEnv = process.env?.SL_API_URL || process.env?.SECONDLAYER_API_URL;
-    if (fromEnv)
-      return fromEnv.replace(/\/+$/, "");
+    const primary = process.env?.SECONDLAYER_API_URL || undefined;
+    if (primary)
+      return primary.replace(/\/+$/, "");
+    const legacy = process.env?.SL_API_URL || undefined;
+    if (legacy) {
+      if (!warnedUrlAlias) {
+        warnedUrlAlias = true;
+        console.warn("[secondlayer] SL_API_URL is a legacy alias of SECONDLAYER_API_URL; using the alias this once.");
+      }
+      return legacy.replace(/\/+$/, "");
+    }
   }
   return LOCAL_API_URL;
 }
-var CREDENTIAL_ENV_VARS = ["INSTANCE_TOKEN", "SL_API_KEY"];
-var warnedConflicts = new Set;
 function resolveApiKey(apiKey) {
   if (apiKey !== undefined)
     return apiKey;
   if (typeof process === "undefined")
     return;
-  const instanceToken = process.env?.INSTANCE_TOKEN || undefined;
-  const legacyKey = process.env?.SL_API_KEY || undefined;
-  if (instanceToken && legacyKey && instanceToken !== legacyKey) {
-    const pair = `${instanceToken}\x00${legacyKey}`;
-    if (!warnedConflicts.has(pair)) {
-      warnedConflicts.add(pair);
-      console.warn("[secondlayer] INSTANCE_TOKEN and SL_API_KEY are set to different values — using INSTANCE_TOKEN (SL_API_KEY is a legacy alias for it).");
+  const token = process.env?.INSTANCE_TOKEN || undefined;
+  return token;
+}
+var warnedArchiveAlias = false;
+function resolveAccountKey(accountKey) {
+  if (accountKey !== undefined)
+    return accountKey;
+  if (typeof process === "undefined")
+    return;
+  const primary = process.env?.SECONDLAYER_API_KEY || undefined;
+  const slAlias = process.env?.SL_API_KEY || undefined;
+  const archiveAlias = process.env?.SL_ARCHIVE_API_KEY || undefined;
+  if (primary)
+    return primary;
+  const legacy = slAlias ?? archiveAlias;
+  if (legacy) {
+    if (!warnedArchiveAlias) {
+      warnedArchiveAlias = true;
+      console.warn("[secondlayer] SL_API_KEY / SL_ARCHIVE_API_KEY are legacy aliases of SECONDLAYER_API_KEY; using the alias this once.");
     }
+    return legacy;
   }
-  return instanceToken ?? legacyKey;
+  return;
 }
 function seg(value) {
   return encodeURIComponent(String(value));
@@ -814,6 +869,244 @@ 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;
+var ARCHIVE_CREDENTIAL_RE = /^s[ks]-sl_/;
+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 accountKey = resolveAccountKey(options.accountKey ?? 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 && accountKey) {
+      if (!ARCHIVE_CREDENTIAL_RE.test(accountKey)) {
+        throw new ArchiveAuthError("archive ops need SECONDLAYER_API_KEY (sk-sl_*), not INSTANCE_TOKEN");
+      }
+      headers.Authorization = `Bearer ${accountKey}`;
+    }
+    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 +2079,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 +2131,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 +2525,8 @@ class SecondLayer extends BaseClient {
   contracts;
   subgraphs;
   subscriptions;
+  archive;
+  instance;
   constructor(options = {}) {
     super(options);
     this.streams = createStreamsClient({
@@ -2247,17 +2542,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({
+        accountKey: options.accountKey,
+        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 +2623,8 @@ class SecondLayer extends BaseClient {
       },
       subgraphs,
       subscriptions,
-      activeOperations
+      activeOperations,
+      instance
     };
   }
 }
@@ -2329,5 +2644,5 @@ export {
   Subgraphs
 };
 
-//# debugId=10070F0E5755447564756E2164756E21
+//# debugId=B1E5E37D297ADB5664756E2164756E21
 //# sourceMappingURL=index.js.map