@otskit/client 0.1.0

package/dist/index.js

@@ -0,0 +1,965 @@
+// src/types.ts
+var DEFAULT_CALENDARS = [
+  "https://alice.btc.calendar.opentimestamps.org",
+  "https://bob.btc.calendar.opentimestamps.org",
+  "https://finney.calendar.eternitywall.com",
+  "https://btc.calendar.catallaxy.com"
+];
+var DEFAULT_RESILIENCE = {
+  totalTimeoutMs: 3e4,
+  connectTimeoutMs: 5e3,
+  retries: {
+    enabled: true,
+    maxAttempts: 3,
+    backoff: {
+      strategy: "exponential",
+      initialDelayMs: 200,
+      maxDelayMs: 5e3,
+      jitter: "full"
+    }
+  },
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 5,
+    recoveryTimeoutMs: 15e3,
+    halfOpenMaxAttempts: 1
+  }
+};
+
+// src/errors.ts
+var OpenTimestampsClientError = class extends Error {
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = this.constructor.name;
+    this.cause = options?.cause;
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+};
+var ValidationError = class extends OpenTimestampsClientError {
+};
+var StampError = class extends OpenTimestampsClientError {
+  successfulSubmissions;
+  failedSubmissions;
+  constructor(message, successful, failed, options) {
+    super(message, options);
+    this.successfulSubmissions = successful;
+    this.failedSubmissions = failed;
+  }
+};
+var UpgradeError = class extends OpenTimestampsClientError {
+};
+var NetworkError = class extends OpenTimestampsClientError {
+  /** HTTP status code, cuando el fallo viene de una respuesta HTTP. */
+  status;
+  constructor(message, options) {
+    super(message, options);
+    this.status = options?.status;
+  }
+};
+var CircuitBreakerError = class extends NetworkError {
+  constructor(calendar) {
+    super(`Circuit breaker open for calendar: ${calendar}`);
+  }
+};
+var CommitmentNotFoundError = class extends NetworkError {
+};
+var CalendarResponseTooLargeError = class extends NetworkError {
+};
+var EsploraResponseError = class extends NetworkError {
+};
+
+// src/network/circuit-breaker.ts
+var CircuitState = /* @__PURE__ */ ((CircuitState2) => {
+  CircuitState2["CLOSED"] = "CLOSED";
+  CircuitState2["OPEN"] = "OPEN";
+  CircuitState2["HALF_OPEN"] = "HALF_OPEN";
+  return CircuitState2;
+})(CircuitState || {});
+var CircuitBreaker = class {
+  constructor(options, logger) {
+    this.options = options;
+    this.logger = logger;
+  }
+  options;
+  logger;
+  circuits = /* @__PURE__ */ new Map();
+  /**
+   * Execute a request through the circuit breaker
+   */
+  async execute(key, fn) {
+    if (!this.options.enabled) {
+      return fn();
+    }
+    const circuit = this.getOrCreateCircuit(key);
+    if (circuit.state === "OPEN" /* OPEN */) {
+      const shouldAttemptRecovery = this.shouldAttemptRecovery(circuit);
+      if (shouldAttemptRecovery) {
+        this.logger?.info(`Circuit breaker for ${key} entering HALF_OPEN state`);
+        circuit.state = "HALF_OPEN" /* HALF_OPEN */;
+        circuit.stats.halfOpenAttempts = 0;
+      } else {
+        throw new CircuitBreakerError(key);
+      }
+    }
+    if (circuit.state === "HALF_OPEN" /* HALF_OPEN */) {
+      const maxAttempts = this.options.halfOpenMaxAttempts || 1;
+      if (circuit.stats.halfOpenAttempts >= maxAttempts) {
+        this.logger?.warn(`Circuit breaker for ${key} reopening after failed HALF_OPEN attempts`);
+        circuit.state = "OPEN" /* OPEN */;
+        circuit.stats.lastFailureTime = Date.now();
+        throw new CircuitBreakerError(key);
+      }
+      circuit.stats.halfOpenAttempts++;
+    }
+    try {
+      const result = await fn();
+      this.onSuccess(key, circuit);
+      return result;
+    } catch (error) {
+      this.onFailure(key, circuit);
+      throw error;
+    }
+  }
+  getOrCreateCircuit(key) {
+    let circuit = this.circuits.get(key);
+    if (!circuit) {
+      circuit = {
+        state: "CLOSED" /* CLOSED */,
+        stats: {
+          consecutiveFailures: 0,
+          halfOpenAttempts: 0
+        }
+      };
+      this.circuits.set(key, circuit);
+    }
+    return circuit;
+  }
+  shouldAttemptRecovery(circuit) {
+    if (!circuit.stats.lastFailureTime) return false;
+    const elapsed = Date.now() - circuit.stats.lastFailureTime;
+    return elapsed >= this.options.recoveryTimeoutMs;
+  }
+  onSuccess(key, circuit) {
+    if (circuit.state === "HALF_OPEN" /* HALF_OPEN */) {
+      this.logger?.info(`Circuit breaker for ${key} closing after successful HALF_OPEN attempt`);
+      circuit.state = "CLOSED" /* CLOSED */;
+    }
+    circuit.stats.consecutiveFailures = 0;
+    circuit.stats.halfOpenAttempts = 0;
+  }
+  onFailure(key, circuit) {
+    circuit.stats.consecutiveFailures++;
+    circuit.stats.lastFailureTime = Date.now();
+    if (circuit.state === "HALF_OPEN" /* HALF_OPEN */) {
+      this.logger?.warn(`Circuit breaker for ${key} reopening after failed HALF_OPEN attempt`);
+      circuit.state = "OPEN" /* OPEN */;
+      return;
+    }
+    if (circuit.stats.consecutiveFailures >= this.options.failureThreshold) {
+      this.logger?.warn(
+        `Circuit breaker for ${key} opening after ${circuit.stats.consecutiveFailures} consecutive failures`
+      );
+      circuit.state = "OPEN" /* OPEN */;
+    }
+  }
+  /** Get current state for debugging/monitoring */
+  getState(key) {
+    return this.circuits.get(key)?.state;
+  }
+  /** Reset a specific circuit */
+  reset(key) {
+    this.circuits.delete(key);
+  }
+  /** Reset all circuits */
+  resetAll() {
+    this.circuits.clear();
+  }
+};
+
+// src/network/retry.ts
+function calculateDelay(attempt, options) {
+  const { strategy, initialDelayMs, maxDelayMs, jitter } = options.backoff;
+  let delay;
+  switch (strategy) {
+    case "exponential":
+      delay = initialDelayMs * Math.pow(2, attempt - 1);
+      break;
+    case "linear":
+      delay = initialDelayMs * attempt;
+      break;
+    case "constant":
+      delay = initialDelayMs;
+      break;
+  }
+  if (maxDelayMs && delay > maxDelayMs) {
+    delay = maxDelayMs;
+  }
+  switch (jitter) {
+    case "full":
+      delay = Math.random() * delay;
+      break;
+    case "equal":
+      delay = delay / 2 + Math.random() * (delay / 2);
+      break;
+    case "none":
+    default:
+      break;
+  }
+  return Math.floor(delay);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Aborted"));
+      return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      reject(new Error("Aborted"));
+    });
+  });
+}
+async function withRetry(fn, options, logger, signal) {
+  if (!options.enabled) {
+    return fn();
+  }
+  let lastError;
+  for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
+    try {
+      logger?.debug(`Attempt ${attempt}/${options.maxAttempts}`);
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (signal?.aborted) {
+        throw lastError;
+      }
+      if (error.retryable === false) {
+        logger?.debug("Error is not retryable (4xx client error), failing immediately");
+        throw lastError;
+      }
+      if (attempt === options.maxAttempts) {
+        logger?.warn(`All ${options.maxAttempts} attempts failed`);
+        throw lastError;
+      }
+      const delay = calculateDelay(attempt, options);
+      logger?.debug(`Retry attempt ${attempt} failed, waiting ${delay}ms before next attempt`);
+      try {
+        await sleep(delay, signal);
+      } catch {
+        throw lastError;
+      }
+    }
+  }
+  throw lastError || new Error("Retry failed");
+}
+
+// src/adapters/fetch-adapter.ts
+async function executeRequest(request) {
+  try {
+    const response = await globalThis.fetch(request.url, {
+      method: request.method,
+      headers: {
+        "Content-Type": "application/octet-stream",
+        ...request.headers
+      },
+      body: request.body,
+      signal: request.signal
+    });
+    const arrayBuffer = await response.arrayBuffer();
+    const data = new Uint8Array(arrayBuffer);
+    return {
+      ok: response.ok,
+      status: response.status,
+      statusText: response.statusText,
+      data
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        throw new NetworkError("Request aborted", { cause: error });
+      }
+      if (error.message.includes("timeout")) {
+        throw new NetworkError("Request timeout", { cause: error });
+      }
+      throw new NetworkError(`Network request failed: ${error.message}`, { cause: error });
+    }
+    throw new NetworkError("Unknown network error");
+  }
+}
+function createTimeoutController(timeoutMs, parentSignal) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort(new Error("Timeout"));
+  }, timeoutMs);
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      clearTimeout(timeout);
+      controller.abort(parentSignal.reason);
+    } else {
+      parentSignal.addEventListener("abort", () => {
+        clearTimeout(timeout);
+        controller.abort(parentSignal.reason);
+      });
+    }
+  }
+  controller.signal.addEventListener("abort", () => {
+    clearTimeout(timeout);
+  });
+  return controller;
+}
+
+// src/network/resilience.ts
+var ResilientNetworkLayer = class {
+  constructor(options, logger) {
+    this.options = options;
+    this.logger = logger;
+    this.circuitBreaker = new CircuitBreaker(options.circuitBreaker, logger);
+  }
+  options;
+  logger;
+  circuitBreaker;
+  /**
+   * Execute a request with full resilience pipeline
+   */
+  async request(calendarUrl, request, parentSignal) {
+    const startTime = Date.now();
+    const totalController = createTimeoutController(
+      this.options.totalTimeoutMs,
+      parentSignal
+    );
+    try {
+      return await this.circuitBreaker.execute(calendarUrl, async () => {
+        return await withRetry(
+          async () => {
+            const attemptController = createTimeoutController(
+              this.options.connectTimeoutMs,
+              totalController.signal
+            );
+            try {
+              const response = await executeRequest({
+                ...request,
+                signal: attemptController.signal
+              });
+              const elapsed = Date.now() - startTime;
+              this.logger?.debug(`Request to ${calendarUrl} succeeded in ${elapsed}ms`);
+              if (!response.ok) {
+                if (response.status >= 400 && response.status < 500) {
+                  const error = new NetworkError(
+                    `HTTP ${response.status}: ${response.statusText}`,
+                    { status: response.status }
+                  );
+                  error.retryable = false;
+                  throw error;
+                }
+                throw new NetworkError(
+                  `HTTP ${response.status}: ${response.statusText}`,
+                  { status: response.status }
+                );
+              }
+              return response;
+            } finally {
+              attemptController.signal.removeEventListener("abort", () => {
+              });
+            }
+          },
+          this.options.retries,
+          this.logger,
+          totalController.signal
+        );
+      });
+    } catch (error) {
+      const elapsed = Date.now() - startTime;
+      this.logger?.error(`Request to ${calendarUrl} failed after ${elapsed}ms`, error);
+      throw error;
+    } finally {
+      totalController.signal.removeEventListener("abort", () => {
+      });
+    }
+  }
+  /** Get circuit breaker state for a calendar */
+  getCircuitState(calendarUrl) {
+    return this.circuitBreaker.getState(calendarUrl);
+  }
+  /** Reset circuit breaker for a calendar */
+  resetCircuit(calendarUrl) {
+    this.circuitBreaker.reset(calendarUrl);
+  }
+  /** Reset all circuit breakers */
+  resetAllCircuits() {
+    this.circuitBreaker.resetAll();
+  }
+};
+
+// src/core/orchestration.ts
+import {
+  DetachedTimestampFile,
+  OpSHA256,
+  OpAppend,
+  makeMerkleTree
+} from "@otskit/core";
+
+// src/network/calendar.ts
+import { Timestamp, StreamDeserializationContext, bytesToHex } from "@otskit/core";
+var MAX_CALENDAR_RESPONSE_SIZE = 1e4;
+function assertCommitment(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError("commitment must be a Uint8Array");
+  }
+  if (bytes.length === 0 || bytes.length > 64) {
+    throw new RangeError(`commitment length ${bytes.length} is out of range (1..64)`);
+  }
+}
+var OTS_HEADERS = {
+  Accept: "application/vnd.opentimestamps.v1",
+  "Content-Type": "application/x-www-form-urlencoded"
+};
+function joinUrl(base, path) {
+  return base.replace(/\/+$/, "") + path;
+}
+var CalendarClient = class {
+  constructor(url, networkLayer, logger) {
+    this.url = url;
+    this.networkLayer = networkLayer;
+    this.logger = logger;
+  }
+  url;
+  networkLayer;
+  logger;
+  /** Envía un digest al calendario y devuelve el Timestamp que lo commit-ea. */
+  async submit(digest, signal) {
+    assertCommitment(digest);
+    this.logger?.debug(`Submitting digest to ${this.url}/digest`);
+    const response = await this.networkLayer.request(
+      this.url,
+      { url: joinUrl(this.url, "/digest"), method: "POST", headers: OTS_HEADERS, body: digest },
+      signal
+    );
+    return this.#parseTimestamp(response.data, digest);
+  }
+  /** Pregunta al calendario si tiene un Timestamp más completo para `commitment` (upgrade). */
+  async getTimestamp(commitment, signal) {
+    assertCommitment(commitment);
+    const path = `/timestamp/${bytesToHex(commitment)}`;
+    this.logger?.debug(`Querying ${this.url}${path}`);
+    let response;
+    try {
+      response = await this.networkLayer.request(
+        this.url,
+        { url: joinUrl(this.url, path), method: "GET", headers: OTS_HEADERS },
+        signal
+      );
+    } catch (err) {
+      if (err instanceof NetworkError && err.status === 404) {
+        throw new CommitmentNotFoundError(`calendar ${this.url} has no timestamp for the commitment yet`, {
+          cause: err
+        });
+      }
+      throw err;
+    }
+    return this.#parseTimestamp(response.data, commitment);
+  }
+  /** Deserializa la respuesta del calendario como un Timestamp commit-eado a `commitment`. */
+  #parseTimestamp(data, commitment) {
+    if (data.length > MAX_CALENDAR_RESPONSE_SIZE) {
+      throw new CalendarResponseTooLargeError(
+        `calendar response of ${data.length} bytes exceeds limit ${MAX_CALENDAR_RESPONSE_SIZE}`
+      );
+    }
+    const ctx = new StreamDeserializationContext(data);
+    const timestamp = Timestamp.deserialize(ctx, commitment);
+    ctx.assertEof();
+    return timestamp;
+  }
+};
+function wildcardToRegExp(pattern) {
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, "[^/]*");
+  return new RegExp(`^${escaped}$`, "i");
+}
+var UrlWhitelist = class {
+  #patterns = /* @__PURE__ */ new Set();
+  constructor(urls) {
+    if (urls) {
+      for (const u of urls) this.add(u);
+    }
+  }
+  /** Añade un patrón; si no trae esquema, se añaden las variantes http y https. */
+  add(url) {
+    if (typeof url !== "string") {
+      throw new TypeError("UrlWhitelist: URL must be a string");
+    }
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      this.#patterns.add(url);
+    } else {
+      this.#patterns.add("http://" + url);
+      this.#patterns.add("https://" + url);
+    }
+  }
+  /** Verdadero si `url` casa con algún patrón de la whitelist. */
+  contains(url) {
+    for (const pattern of this.#patterns) {
+      if (wildcardToRegExp(pattern).test(url)) return true;
+    }
+    return false;
+  }
+  toString() {
+    return `UrlWhitelist([${[...this.#patterns].join(", ")}])`;
+  }
+};
+var DEFAULT_CALENDAR_WHITELIST = new UrlWhitelist([
+  "https://*.calendar.opentimestamps.org",
+  // Peter Todd
+  "https://*.calendar.eternitywall.com",
+  // Eternity Wall
+  "https://*.calendar.catallaxy.com"
+  // Catallaxy
+]);
+var DEFAULT_AGGREGATORS = [
+  "https://a.pool.opentimestamps.org",
+  "https://b.pool.opentimestamps.org",
+  "https://a.pool.eternitywall.com",
+  "https://ots.btc.catallaxy.com"
+];
+
+// src/network/esplora.ts
+import { verifyAgainstBlockheader, VerificationError } from "@otskit/core";
+var PUBLIC_ESPLORA_URL = "https://blockstream.info/api";
+var MAX_ESPLORA_RESPONSE_SIZE = 1e5;
+var HEX64_RE = /^[0-9a-f]{64}$/i;
+var EsploraClient = class {
+  #url;
+  #networkLayer;
+  #logger;
+  constructor(networkLayer, options = {}) {
+    const raw = options.url ?? PUBLIC_ESPLORA_URL;
+    let parsed;
+    try {
+      parsed = new URL(raw);
+    } catch {
+      throw new ValidationError(`invalid Esplora URL: ${raw}`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      throw new ValidationError(`Esplora URL must use http(s): ${raw}`);
+    }
+    this.#networkLayer = networkLayer;
+    this.#url = raw.replace(/\/+$/, "");
+    this.#logger = options.logger;
+  }
+  /** Devuelve el hash (hex 64, minúsculas) del bloque a la altura dada. */
+  async blockHash(height, signal) {
+    if (!Number.isSafeInteger(height) || height < 0) {
+      throw new ValidationError(`block height must be a non-negative safe integer; got ${height}`);
+    }
+    this.#logger?.debug(`Esplora block-height ${height}`);
+    const response = await this.#networkLayer.request(
+      this.#url,
+      { url: `${this.#url}/block-height/${height}`, method: "GET", headers: { Accept: "text/plain" } },
+      signal
+    );
+    const text = this.#decode(response.data).trim();
+    if (!HEX64_RE.test(text)) {
+      throw new EsploraResponseError(`esplora returned an invalid block hash for height ${height}`);
+    }
+    return text.toLowerCase();
+  }
+  /** Devuelve la cabecera del bloque (merkleroot + time) dado su hash. */
+  async block(hash, signal) {
+    if (typeof hash !== "string" || !HEX64_RE.test(hash)) {
+      throw new ValidationError("block hash must be a 64-char hex string");
+    }
+    this.#logger?.debug(`Esplora block ${hash}`);
+    const response = await this.#networkLayer.request(
+      this.#url,
+      { url: `${this.#url}/block/${hash}`, method: "GET", headers: { Accept: "application/json" } },
+      signal
+    );
+    const text = this.#decode(response.data);
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch (err) {
+      throw new EsploraResponseError("esplora returned a non-JSON block response", {
+        /* v8 ignore next */
+        cause: err instanceof Error ? err : void 0
+      });
+    }
+    if (typeof body !== "object" || body === null) {
+      throw new EsploraResponseError("esplora block response is not an object");
+    }
+    const { merkle_root: merkleroot, timestamp: time } = body;
+    if (typeof merkleroot !== "string" || !HEX64_RE.test(merkleroot)) {
+      throw new EsploraResponseError("esplora block merkle_root is not a 64-char hex string");
+    }
+    if (typeof time !== "number" || !Number.isInteger(time) || time <= 0) {
+      throw new EsploraResponseError("esplora block timestamp is not a positive integer");
+    }
+    return { merkleroot, time };
+  }
+  /** Decodifica el cuerpo a texto aplicando el límite de tamaño (fail-closed). */
+  #decode(data) {
+    if (data.length > MAX_ESPLORA_RESPONSE_SIZE) {
+      throw new EsploraResponseError(
+        `esplora response of ${data.length} bytes exceeds limit ${MAX_ESPLORA_RESPONSE_SIZE}`
+      );
+    }
+    return new TextDecoder("utf-8", { fatal: false }).decode(data);
+  }
+};
+async function verifyTimestampAttestation(digest, attestation, explorer, signal) {
+  if (attestation.kind !== "bitcoin" && attestation.kind !== "litecoin") {
+    throw new VerificationError(`cannot verify a '${attestation.kind}' attestation against the chain`);
+  }
+  const hash = await explorer.blockHash(attestation.height, signal);
+  const header = await explorer.block(hash, signal);
+  return verifyAgainstBlockheader(digest, header);
+}
+
+// src/core/orchestration.ts
+function validateHash(hash) {
+  if (typeof hash === "string") {
+    const hex = hash.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+      throw new ValidationError("Hash must be a 64-character hex string (SHA-256)");
+    }
+    return Uint8Array.from(Buffer.from(hex, "hex"));
+  }
+  if (hash.length !== 32) {
+    throw new ValidationError("Hash must be exactly 32 bytes (SHA-256)");
+  }
+  return Uint8Array.from(hash);
+}
+function secureNonce(n) {
+  const bytes = new Uint8Array(n);
+  if (!globalThis.crypto?.getRandomValues) {
+    throw new Error("secure RNG unavailable: globalThis.crypto.getRandomValues is required");
+  }
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}
+var bytesEq = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
+function assertHttpUrl(url, label) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new ValidationError(`${label} is not a valid URL: ${url}`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new ValidationError(`${label} must use http(s): ${url}`);
+  }
+}
+async function orchestrateStamp(hash, calendars, networkLayer, logger, signal, minimumSuccessfulSubmissions = 2) {
+  if (calendars.length === 0) {
+    throw new ValidationError("at least one calendar is required to stamp");
+  }
+  if (!Number.isInteger(minimumSuccessfulSubmissions) || minimumSuccessfulSubmissions < 1) {
+    throw new ValidationError("minimumSuccessfulSubmissions must be an integer >= 1");
+  }
+  if (minimumSuccessfulSubmissions > calendars.length) {
+    throw new ValidationError(
+      `minimumSuccessfulSubmissions (${minimumSuccessfulSubmissions}) cannot exceed the number of calendars (${calendars.length})`
+    );
+  }
+  for (const url of calendars) assertHttpUrl(url, "calendar");
+  const digest = validateHash(hash);
+  logger?.info(`Starting stamp for ${Buffer.from(digest).toString("hex")}`);
+  const detached = DetachedTimestampFile.fromHash(new OpSHA256(), digest);
+  const nonceAppended = detached.timestamp.add(new OpAppend(secureNonce(16)));
+  const merkleRoot = nonceAppended.add(new OpSHA256());
+  const merkleTip = makeMerkleTree([merkleRoot]);
+  const results = await Promise.allSettled(
+    calendars.map((url) => new CalendarClient(url, networkLayer, logger).submit(merkleTip.getDigest(), signal))
+  );
+  const successful = [];
+  const failed = [];
+  results.forEach((r, i) => {
+    const calendar = calendars[i];
+    if (r.status === "fulfilled") {
+      merkleTip.merge(r.value);
+      successful.push({ calendar });
+      logger?.info(`Submitted to ${calendar}`);
+    } else {
+      const error = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
+      failed.push({ calendar, error });
+      logger?.warn(`Failed to submit to ${calendar}: ${error.message}`);
+    }
+  });
+  if (successful.length < minimumSuccessfulSubmissions) {
+    throw new StampError(
+      `Insufficient successful submissions (${successful.length}/${minimumSuccessfulSubmissions} required)`,
+      successful,
+      failed
+    );
+  }
+  return Buffer.from(detached.serializeToBytes());
+}
+async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, logger, signal) {
+  let detached;
+  try {
+    detached = DetachedTimestampFile.deserialize(new Uint8Array(incompleteProof));
+  } catch (error) {
+    throw new ValidationError("Invalid .ots proof format", {
+      /* v8 ignore next */
+      cause: error instanceof Error ? error : void 0
+    });
+  }
+  if (detached.timestamp.isTimestampComplete()) {
+    logger?.info("Proof already complete; nothing to upgrade");
+    return Buffer.from(incompleteProof);
+  }
+  const before = detached.serializeToBytes();
+  for (const subStamp of detached.timestamp.directlyVerified()) {
+    if (subStamp.isTimestampComplete()) continue;
+    for (const att of subStamp.attestations) {
+      if (att.kind !== "pending") continue;
+      if (!DEFAULT_CALENDAR_WHITELIST.contains(att.uri)) {
+        logger?.warn(`Ignoring attestation from non-whitelisted calendar ${att.uri}`);
+        continue;
+      }
+      try {
+        const upgraded = await new CalendarClient(att.uri, networkLayer, logger).getTimestamp(
+          subStamp.getDigest(),
+          signal
+        );
+        subStamp.merge(upgraded);
+      } catch (err) {
+        if (err instanceof CommitmentNotFoundError) {
+          logger?.debug(`Calendar ${att.uri} has not confirmed yet`);
+          continue;
+        }
+        logger?.warn(`Failed to query ${att.uri}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+  const after = detached.serializeToBytes();
+  if (bytesEq(before, after)) {
+    throw new UpgradeError("No calendar has confirmed the timestamp yet (Bitcoin not yet mined)");
+  }
+  return Buffer.from(after);
+}
+async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal) {
+  let detached;
+  try {
+    detached = DetachedTimestampFile.deserialize(new Uint8Array(proof));
+  } catch {
+    return { valid: false, error: "Invalid .ots proof format" };
+  }
+  if (originalDataHash !== void 0) {
+    let expected;
+    try {
+      expected = validateHash(originalDataHash);
+    } catch (err) {
+      return { valid: false, error: err instanceof Error ? err.message : "Invalid hash format" };
+    }
+    if (!bytesEq(expected, detached.fileDigest())) {
+      return { valid: false, error: "File hash does not match proof" };
+    }
+  }
+  const bitcoinAtts = detached.timestamp.allAttestations().filter(({ attestation }) => attestation.kind === "bitcoin");
+  if (bitcoinAtts.length === 0) {
+    const hasLitecoin = detached.timestamp.allAttestations().some(({ attestation }) => attestation.kind === "litecoin");
+    if (hasLitecoin) {
+      return { valid: false, error: "Litecoin verification is not supported by this client" };
+    }
+    return { valid: false, error: "No Bitcoin attestation found (timestamp not yet confirmed)" };
+  }
+  const explorer = new EsploraClient(networkLayer);
+  let lastError = "";
+  for (const { msg, attestation } of bitcoinAtts) {
+    if (attestation.kind !== "bitcoin") continue;
+    try {
+      const time = await verifyTimestampAttestation(Uint8Array.from(msg).reverse(), attestation, explorer, signal);
+      logger?.info(`Verified against Bitcoin block ${attestation.height}`);
+      return { valid: true, blockHeight: attestation.height, timestamp: time };
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+      logger?.warn(`Bitcoin attestation at height ${attestation.height} failed: ${lastError}`);
+    }
+  }
+  return { valid: false, error: `Could not verify against the Bitcoin blockchain: ${lastError}` };
+}
+
+// src/client.ts
+var OpenTimestampsClient = class {
+  calendars;
+  networkLayer;
+  logger;
+  globalSignal;
+  minimumSuccessfulSubmissions;
+  /**
+   * Create a new OpenTimestamps client
+   * 
+   * @param options Client configuration options
+   */
+  constructor(options = {}) {
+    if (!options.calendars || options.calendars.length === 0) {
+      this.calendars = DEFAULT_CALENDARS;
+      this.logger?.info("No calendars provided, using defaults");
+    } else {
+      this.calendars = options.calendars;
+    }
+    this.minimumSuccessfulSubmissions = options.minimumSuccessfulSubmissions ?? 2;
+    const resilienceConfig = {
+      ...DEFAULT_RESILIENCE,
+      ...options.resilience,
+      retries: {
+        ...DEFAULT_RESILIENCE.retries,
+        ...options.resilience?.retries,
+        backoff: {
+          ...DEFAULT_RESILIENCE.retries.backoff,
+          ...options.resilience?.retries?.backoff
+        }
+      },
+      circuitBreaker: {
+        ...DEFAULT_RESILIENCE.circuitBreaker,
+        ...options.resilience?.circuitBreaker
+      }
+    };
+    this.logger = options.logger;
+    this.globalSignal = options.signal;
+    this.networkLayer = options.networkLayer ?? new ResilientNetworkLayer(resilienceConfig, this.logger);
+    this.logger?.info(`OpenTimestamps client initialized with ${this.calendars.length} calendars`);
+  }
+  /**
+   * Create a timestamp by submitting a hash to calendar servers
+   * 
+   * @param hash SHA-256 hash of the data to timestamp (as Buffer or hex string)
+   * @param options Operation-specific options
+   * @returns Initial .ots proof with pending attestations
+   * 
+   * @throws {ValidationError} If the hash is invalid
+   * @throws {StampError} If submission fails to all calendars
+   * @throws {NetworkError} If network errors occur
+   * 
+   * @example
+   * ```typescript
+   * const hash = crypto.createHash('sha256').update('my data').digest()
+   * const otsProof = await client.stamp(hash)
+   * // Save otsProof to database as Buffer
+   * ```
+   */
+  async stamp(hash, options) {
+    const signal = options?.signal || this.globalSignal;
+    return orchestrateStamp(
+      hash,
+      this.calendars,
+      this.networkLayer,
+      this.logger,
+      signal,
+      this.minimumSuccessfulSubmissions
+    );
+  }
+  /**
+   * Upgrade an incomplete timestamp proof by querying calendars for Bitcoin confirmation
+   * 
+   * @param incompleteProof The initial .ots proof returned by stamp()
+   * @param options Operation-specific options
+   * @returns Upgraded .ots proof with Bitcoin attestation (if available)
+   * 
+   * @throws {ValidationError} If the proof format is invalid
+   * @throws {UpgradeError} If no calendar has confirmed the timestamp yet
+   * @throws {NetworkError} If network errors occur
+   * 
+   * @example
+   * ```typescript
+   * // Proof already has pending attestations from stamp()
+   * const upgradedProof = await client.upgrade(incompleteProof)
+   * 
+   * // If upgrade throws UpgradeError, Bitcoin hasn't confirmed yet
+   * // Retry later (typically 10-60 minutes after stamp)
+   * ```
+   */
+  async upgrade(incompleteProof, options) {
+    const signal = options?.signal || this.globalSignal;
+    return orchestrateUpgrade(
+      incompleteProof,
+      this.calendars,
+      this.networkLayer,
+      this.logger,
+      signal
+    );
+  }
+  /**
+   * Verify a complete timestamp proof against the Bitcoin blockchain
+   * 
+   * @param proof The complete .ots proof with Bitcoin attestation
+   * @param originalDataHash Optional: the original data hash to verify against
+   * @returns Verification result with block details
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.verify(completeProof, originalHash)
+   * 
+   * if (result.valid) {
+   *   console.log(`Timestamp confirmed in Bitcoin block ${result.blockHeight}`)
+   *   console.log(`Block timestamp: ${new Date(result.timestamp! * 1000)}`)
+   * } else {
+   *   console.error(`Verification failed: ${result.error}`)
+   * }
+   * ```
+   */
+  async verify(proof, originalDataHash) {
+    return orchestrateVerify(proof, this.networkLayer, originalDataHash, this.logger, this.globalSignal);
+  }
+  /**
+   * Get the current state of the circuit breaker for a calendar
+   * Useful for monitoring and debugging
+   * 
+   * @param calendarUrl The calendar URL to check
+   * @returns Circuit state: 'CLOSED', 'OPEN', or 'HALF_OPEN' (undefined if not yet initialized)
+   */
+  getCircuitState(calendarUrl) {
+    return this.networkLayer.getCircuitState(calendarUrl);
+  }
+  /**
+   * Reset the circuit breaker for a specific calendar
+   * Use this to manually recover a calendar that has been marked as failing
+   * 
+   * @param calendarUrl The calendar URL to reset
+   */
+  resetCircuit(calendarUrl) {
+    this.logger?.info(`Manually resetting circuit breaker for ${calendarUrl}`);
+    this.networkLayer.resetCircuit(calendarUrl);
+  }
+  /**
+   * Reset all circuit breakers
+   * Use this to clear all failure states
+   */
+  resetAllCircuits() {
+    this.logger?.info("Manually resetting all circuit breakers");
+    this.networkLayer.resetAllCircuits();
+  }
+};
+
+// src/index.ts
+import { DetachedTimestampFile as DetachedTimestampFile2, Timestamp as Timestamp2 } from "@otskit/core";
+import { verifyAgainstBlockheader as verifyAgainstBlockheader2 } from "@otskit/core";
+export {
+  CalendarClient,
+  CalendarResponseTooLargeError,
+  CircuitBreakerError,
+  CircuitState,
+  CommitmentNotFoundError,
+  DEFAULT_AGGREGATORS,
+  DEFAULT_CALENDARS,
+  DEFAULT_CALENDAR_WHITELIST,
+  DEFAULT_RESILIENCE,
+  DetachedTimestampFile2 as DetachedTimestampFile,
+  EsploraClient,
+  EsploraResponseError,
+  MAX_CALENDAR_RESPONSE_SIZE,
+  MAX_ESPLORA_RESPONSE_SIZE,
+  NetworkError,
+  OpenTimestampsClient,
+  OpenTimestampsClientError,
+  PUBLIC_ESPLORA_URL,
+  ResilientNetworkLayer,
+  StampError,
+  Timestamp2 as Timestamp,
+  UpgradeError,
+  UrlWhitelist,
+  ValidationError,
+  verifyAgainstBlockheader2 as verifyAgainstBlockheader,
+  verifyTimestampAttestation
+};