@coopenomics/parser 1.0.0

package/dist/index.js

@@ -0,0 +1,1773 @@
+// src/config/index.ts
+import { readFileSync } from "fs";
+import { parse as parseYaml } from "yaml";
+
+// src/errors.ts
+var ConfigValidationError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "ConfigValidationError";
+    this.cause = cause;
+  }
+};
+var ConfigSecurityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigSecurityError";
+  }
+};
+var NotImplementedError = class extends Error {
+  constructor(method) {
+    super(`${method} is not implemented`);
+    this.name = "NotImplementedError";
+  }
+};
+var ChainIdMismatchError = class extends Error {
+  constructor(expected, actual) {
+    super(`Chain ID mismatch: expected ${expected}, got ${actual}`);
+    this.name = "ChainIdMismatchError";
+  }
+};
+var AbiNotFoundError = class extends Error {
+  constructor(contract, blockNum, abiFallback) {
+    super(`ABI for ${contract} not found at block ${blockNum}, abiFallback=${abiFallback}`);
+    this.name = "AbiNotFoundError";
+  }
+};
+
+// src/config/index.ts
+var PLAIN_SECRET_RE = /redis:\/\/[^$\s]*:[^@$\s]+@/i;
+function interpolateEnv(value) {
+  return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+    return process.env[varName] ?? `\${${varName}}`;
+  });
+}
+function interpolateDeep(obj) {
+  if (typeof obj === "string") return interpolateEnv(obj);
+  if (Array.isArray(obj)) return obj.map(interpolateDeep);
+  if (obj !== null && typeof obj === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+      result[k] = interpolateDeep(v);
+    }
+    return result;
+  }
+  return obj;
+}
+function isObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function validate(raw) {
+  const errors = [];
+  if (!isObject(raw)) {
+    errors.push("(root) must be an object");
+    throw new ConfigValidationError(`Config validation failed: ${errors.join("; ")}`);
+  }
+  if (!isObject(raw["ship"]) || typeof raw["ship"]["url"] !== "string") {
+    errors.push("ship.url is required and must be a string");
+  }
+  if (!isObject(raw["redis"]) || typeof raw["redis"]["url"] !== "string") {
+    errors.push("redis.url is required and must be a string");
+  }
+  const abiFallback = raw["abiFallback"];
+  if (abiFallback !== void 0 && abiFallback !== "rpc-current" && abiFallback !== "fail") {
+    errors.push('abiFallback must be "rpc-current" or "fail"');
+  }
+  const deserializer = raw["deserializer"];
+  if (deserializer !== void 0 && deserializer !== "wharfkit") {
+    errors.push('deserializer must be "wharfkit"');
+  }
+  if (errors.length > 0) {
+    throw new ConfigValidationError(`Config validation failed: ${errors.join("; ")}`);
+  }
+  return true;
+}
+function checkPlainSecrets(opts) {
+  if (PLAIN_SECRET_RE.test(opts.redis.url)) {
+    throw new ConfigSecurityError(
+      "Secrets must be injected via env variables, not hardcoded in config"
+    );
+  }
+}
+function parseConfig(raw) {
+  const interpolated = interpolateDeep(raw);
+  validate(interpolated);
+  const opts = interpolated;
+  checkPlainSecrets(opts);
+  return opts;
+}
+function fromConfigFile(filePath) {
+  const text = readFileSync(filePath, "utf8");
+  const raw = parseYaml(text);
+  return parseConfig(raw);
+}
+
+// src/adapters/ShipReaderAdapter.ts
+import { ShipClient } from "@coopenomics/coopos-ship-reader";
+var ShipReaderAdapter = class {
+  client;
+  /**
+   * @param opts.url — WebSocket URL SHiP-ноды, например ws://localhost:29999.
+   * @param opts.timeoutMs — таймаут WebSocket-подключения.
+   * @param opts.chainUrl — HTTP URL chain API (для getRawAbi / getChainInfo).
+   */
+  constructor(opts) {
+    const shipCfg = { url: opts.url };
+    if (opts.timeoutMs !== void 0) shipCfg.timeoutMs = opts.timeoutMs;
+    if (opts.chainUrl !== void 0) {
+      this.client = new ShipClient({ ship: shipCfg, chain: { url: opts.chainUrl } });
+    } else {
+      this.client = new ShipClient({ ship: shipCfg });
+    }
+  }
+  /**
+   * Устанавливает WebSocket-соединение и выполняет SHiP-рукопожатие.
+   * Рукопожатие возвращает chainId — hex-хэш genesis.json.
+   */
+  async connect() {
+    await this.client.connect();
+    const { chainId } = await this.client.handshake();
+    return { chainId };
+  }
+  /** Начинает асинхронный поток блоков от указанной позиции. */
+  streamBlocks(opts) {
+    return this.client.streamBlocks(opts);
+  }
+  /**
+   * ACK n блоков: сигнализирует SHiP-ноде что мы готовы принять ещё.
+   * SHiP использует оконное управление потоком: без ACK нода замолчит.
+   */
+  ack(n) {
+    this.client.ack(n);
+  }
+  /** Закрывает WebSocket. */
+  async close() {
+    this.client.close();
+  }
+  /** GET /v1/chain/get_info — возвращает head block, last irreversible и т.д. */
+  getChainInfo() {
+    return this.client.getChainInfo();
+  }
+  /** GET /v1/chain/get_raw_abi — загружает сырые байты ABI для bootstrap. */
+  getRawAbi(contract) {
+    return this.client.getRawAbi(contract);
+  }
+  /**
+   * Десериализует нативную SHiP-дельту в типизированный объект.
+   * Делегируется встроенному deserializer'у ship-reader, который
+   * содержит hardcoded-схемы нативных таблиц (permission, account, …).
+   */
+  deserializeNativeDelta(delta) {
+    return this.client.deserializer.deserializeNativeDelta(delta);
+  }
+};
+
+// src/adapters/IoRedisStore.ts
+var { default: RedisClass } = await import("ioredis");
+var PEXPIRE_LUA = `
+local current = redis.call('GET', KEYS[1])
+if current == ARGV[2] then
+  redis.call('PEXPIRE', KEYS[1], ARGV[1])
+  return 1
+end
+return 0
+`;
+var DEL_LUA = `
+local current = redis.call('GET', KEYS[1])
+if current == ARGV[1] then
+  redis.call('DEL', KEYS[1])
+  return 1
+end
+return 0
+`;
+function parseStreamEntries(raw) {
+  const messages = [];
+  for (const [msgId, rawFields] of raw) {
+    const fields = {};
+    for (let i = 0; i + 1 < rawFields.length; i += 2) {
+      fields[rawFields[i] ?? ""] = rawFields[i + 1] ?? "";
+    }
+    messages.push({ id: msgId, fields });
+  }
+  return messages;
+}
+function parseXGroupInfo(raw) {
+  let obj;
+  if (Array.isArray(raw)) {
+    obj = {};
+    for (let i = 0; i + 1 < raw.length; i += 2) {
+      obj[raw[i]] = raw[i + 1];
+    }
+  } else {
+    obj = raw;
+  }
+  return {
+    name: String(obj["name"] ?? ""),
+    pending: Number(obj["pending"] ?? 0),
+    // Поле 'last-delivered-id' в Redis (с дефисами), не 'lastDeliveredId'
+    lastDeliveredId: String(obj["last-delivered-id"] ?? "0-0"),
+    // lag появилось в Redis 7.0; null для старых версий
+    lag: obj["lag"] != null ? Number(obj["lag"]) : null,
+    consumers: Number(obj["consumers"] ?? 0)
+  };
+}
+var IoRedisStore = class {
+  /** Прямой доступ к ioredis-клиенту (для тестов и расширения). */
+  client;
+  constructor(opts) {
+    const redisOpts = {
+      lazyConnect: true,
+      // не подключаться в конструкторе — явный connect()
+      enableReadyCheck: true
+      // проверять готовность перед командами
+    };
+    if (opts.password !== void 0) redisOpts.password = opts.password;
+    if (opts.keyPrefix !== void 0) redisOpts.keyPrefix = opts.keyPrefix;
+    this.client = new RedisClass(opts.url, redisOpts);
+  }
+  /** Явное подключение — вызывается один раз при старте Parser/ParserClient. */
+  async connect() {
+    await this.client.connect();
+  }
+  /** XADD stream * field1 val1 … — возвращает присвоенный entry ID. */
+  async xadd(stream, fields) {
+    const args = [];
+    for (const [k, v] of Object.entries(fields)) args.push(k, v);
+    const id = await this.client.xadd(stream, "*", ...args);
+    return id ?? "";
+  }
+  /** XTRIM stream MINID minId — удаляет записи с ID < minId. */
+  async xtrim(stream, minId) {
+    return this.client.xtrim(stream, "MINID", minId);
+  }
+  /**
+   * XGROUP CREATE stream group startId MKSTREAM
+   * MKSTREAM: создаёт стрим если не существует.
+   * BUSYGROUP: группа уже существует — это нормально, поглощаем ошибку.
+   */
+  async xgroupCreate(stream, group, startId) {
+    try {
+      await this.client.xgroup("CREATE", stream, group, startId, "MKSTREAM");
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("BUSYGROUP")) return;
+      throw err;
+    }
+  }
+  /** XGROUP SETID stream group id — переставляет позицию group в стриме. */
+  async xgroupSetId(stream, group, id) {
+    await this.client.xgroup("SETID", stream, group, id);
+  }
+  /** XINFO GROUPS stream → список consumer groups с метриками. */
+  async xinfoGroups(stream) {
+    const raw = await this.client.xinfo("GROUPS", stream);
+    return (raw ?? []).map(parseXGroupInfo);
+  }
+  /**
+   * XREADGROUP GROUP group consumer COUNT count BLOCK blockMs STREAMS stream id
+   * id='>' — только новые сообщения.
+   * id='0' — PEL (pending): уже доставленные, но не подтверждённые (recovery).
+   */
+  async xreadGroup(stream, group, consumer, count, blockMs, id) {
+    const result = await this.client.xreadgroup(
+      "GROUP",
+      group,
+      consumer,
+      "COUNT",
+      count,
+      "BLOCK",
+      blockMs,
+      "STREAMS",
+      stream,
+      id
+    );
+    if (!result) return [];
+    const messages = [];
+    for (const [, entries] of result) {
+      messages.push(...parseStreamEntries(entries));
+    }
+    return messages;
+  }
+  /** XRANGE stream start end COUNT count. */
+  async xrange(stream, start, end, count) {
+    const raw = await this.client.xrange(stream, start, end, "COUNT", count);
+    return parseStreamEntries(raw);
+  }
+  /** XREVRANGE stream end start COUNT count. */
+  async xrevrange(stream, end, start, count) {
+    const raw = await this.client.xrevrange(stream, end, start, "COUNT", count);
+    return parseStreamEntries(raw);
+  }
+  /** XLEN stream. */
+  async xlen(stream) {
+    return this.client.xlen(stream);
+  }
+  /** XDEL stream id — удаляет запись по ID. */
+  async xdel(stream, id) {
+    return this.client.xdel(stream, id);
+  }
+  /** XACK stream group id — убирает из PEL. */
+  async xack(stream, group, id) {
+    await this.client.xack(stream, group, id);
+  }
+  /** ZADD key score member. */
+  async zadd(key, score, member) {
+    await this.client.zadd(key, score, member);
+  }
+  /**
+   * ZREVRANGEBYSCORE key max min LIMIT 0 1
+   * Возвращает максимум один элемент с score ≤ max.
+   * Используется для поиска ABI: «последняя версия не позже блока N».
+   */
+  async zrangeByscoreRev(key, max, min) {
+    return this.client.zrevrangebyscore(key, max, min, "LIMIT", 0, 1);
+  }
+  /** ZRANGEBYSCORE key min max LIMIT 0 9999999 — все элементы в диапазоне. */
+  async zrangeByScore(key, min, max) {
+    return this.client.zrangebyscore(key, min, max, "LIMIT", 0, 9999999);
+  }
+  /** ZCOUNT key min max. */
+  async zcount(key, min, max) {
+    return this.client.zcount(key, min, max);
+  }
+  /** ZREMRANGEBYSCORE key min max → число удалённых. */
+  async zremRangeByScore(key, min, max) {
+    return this.client.zremrangebyscore(key, min, max);
+  }
+  /** ZCARD key. */
+  async zcard(key) {
+    return this.client.zcard(key);
+  }
+  /** HSET key field1 val1 field2 val2 … */
+  async hset(key, fields) {
+    const args = [];
+    for (const [k, v] of Object.entries(fields)) args.push(k, v);
+    if (args.length > 0) await this.client.hset(key, ...args);
+  }
+  /** HGET key field. */
+  async hget(key, field) {
+    return this.client.hget(key, field);
+  }
+  /** HGETALL key → пустой объект если ключ не существует (ioredis возвращает null). */
+  async hgetAll(key) {
+    const result = await this.client.hgetall(key);
+    return result ?? {};
+  }
+  /** HINCRBY key field increment → новое значение счётчика. */
+  async hincrby(key, field, increment) {
+    return this.client.hincrby(key, field, increment);
+  }
+  /** HDEL key field. */
+  async hdel(key, field) {
+    await this.client.hdel(key, field);
+  }
+  /**
+   * SET key value NX PX pxMs
+   * NX: только если не существует. PX: TTL в миллисекундах.
+   * Используется для захвата distributed lock'а.
+   */
+  async setNx(key, value, pxMs) {
+    const result = await this.client.set(key, value, "NX", "PX", pxMs);
+    return result === "OK";
+  }
+  /**
+   * Выполняет PEXPIRE_LUA: продлевает TTL lock'а только если мы — владелец.
+   * Возвращает true если продление прошло успешно.
+   */
+  async pexpire(key, ms, value) {
+    const result = await this.client.eval(PEXPIRE_LUA, 1, key, String(ms), value);
+    return result === 1;
+  }
+  /**
+   * Выполняет DEL_LUA: удаляет lock только если мы — владелец.
+   * Возвращает true если удаление прошло успешно.
+   */
+  async luaDel(key, value) {
+    const result = await this.client.eval(DEL_LUA, 1, key, value);
+    return result === 1;
+  }
+  /** EXPIRE key seconds. */
+  async expire(key, seconds) {
+    await this.client.expire(key, seconds);
+  }
+  /**
+   * Полный SCAN по паттерну: итерирует cursor пока не вернётся '0'.
+   * @param count — подсказка Redis сколько ключей возвращать за итерацию.
+   * @returns Полный список ключей (может быть большим для широких паттернов).
+   */
+  async scan(pattern, count = 100) {
+    const keys = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, batch] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", count);
+      keys.push(...batch);
+      cursor = nextCursor;
+    } while (cursor !== "0");
+    return keys;
+  }
+  /** Закрывает соединение с Redis. */
+  async quit() {
+    await this.client.quit();
+  }
+};
+
+// src/workers/WorkerPool.ts
+import { fileURLToPath } from "url";
+import { join, dirname, resolve } from "path";
+import { existsSync } from "fs";
+var { default: PiscinaClass } = await import("piscina");
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+function resolveWorkerPath() {
+  const candidates = [
+    // Production: рядом с WorkerPool
+    join(__dirname, "deserialize.worker.cjs"),
+    // Source mode (tests): относительный путь к dist/
+    resolve(__dirname, "../../dist/deserialize.worker.cjs"),
+    resolve(__dirname, "../../dist/workers/deserialize.worker.cjs")
+  ];
+  for (const path of candidates) {
+    if (existsSync(path)) return path;
+  }
+  throw new Error(
+    `Could not find deserialize.worker.cjs. Tried: ${candidates.join(", ")}. Run "pnpm build" first if running from source.`
+  );
+}
+var WorkerPool = class {
+  pool;
+  /**
+   * @param maxThreads — максимум параллельных worker-потоков.
+   *   Оптимум зависит от числа CPU и IO-нагрузки. Дефолт 2 подходит
+   *   для большинства серверов; 4+ потока ускоряют плотные блоки (много actions).
+   */
+  constructor(maxThreads = 2) {
+    this.pool = new PiscinaClass({
+      filename: resolveWorkerPath(),
+      maxThreads
+    });
+  }
+  /**
+   * Запускает десериализацию в одном из свободных worker-потоков.
+   * Блокирует промис пока worker не вернёт результат.
+   */
+  run(task) {
+    return this.pool.run(task);
+  }
+  /**
+   * Доля занятых потоков от общего числа (0..1).
+   * Полезно для метрики parser_worker_pool_queue_depth.
+   */
+  get utilization() {
+    return this.pool.utilization;
+  }
+  /** Завершает все worker-потоки (вызывается при остановке парсера). */
+  destroy() {
+    return this.pool.destroy();
+  }
+};
+
+// src/core/BlockProcessor.ts
+import PQueue from "p-queue";
+import { ABI, Blob as AntelopeBlob } from "@wharfkit/antelope";
+import { isNativeTableName } from "@coopenomics/coopos-ship-reader";
+
+// src/events/eventId.ts
+function computeEventId(event) {
+  const blockIdShort = (blockId) => blockId.slice(0, 16);
+  if (event.kind === "action") {
+    return `${event.chain_id}:a:${event.block_num}:${blockIdShort(event.block_id)}:${event.global_sequence}`;
+  }
+  if (event.kind === "delta") {
+    return `${event.chain_id}:d:${event.block_num}:${blockIdShort(event.block_id)}:${event.code}:${event.scope}:${event.table}:${event.primary_key}`;
+  }
+  if (event.kind === "native-delta") {
+    return `${event.chain_id}:n:${event.block_num}:${blockIdShort(event.block_id)}:${event.table}:${event.lookup_key}`;
+  }
+  if (event.kind === "fork") {
+    return `${event.chain_id}:f:${event.forked_from_block}:${blockIdShort(event.new_head_block_id)}`;
+  }
+  const _exhaustive = event;
+  return _exhaustive;
+}
+
+// src/core/BlockProcessor.ts
+function abiToJson(bytes) {
+  try {
+    const base64 = Buffer.from(bytes).toString("base64");
+    const abi = ABI.from(AntelopeBlob.from(base64));
+    return JSON.stringify(abi.toJSON());
+  } catch {
+    return "{}";
+  }
+}
+var BlockProcessor = class {
+  /** Очередь с concurrency=1: только один блок обрабатывается одновременно. */
+  queue;
+  chainId;
+  workerPool;
+  abiBootstrapper;
+  abiStore;
+  chainClient;
+  constructor(opts) {
+    this.chainId = opts.chainId;
+    this.workerPool = opts.workerPool;
+    this.abiBootstrapper = opts.abiBootstrapper;
+    this.abiStore = opts.abiStore;
+    this.chainClient = opts.chainClient;
+    this.queue = new PQueue({ concurrency: 1 });
+  }
+  /**
+   * Ставит блок в очередь на обработку.
+   * Возвращает Promise который резолвится когда этот конкретный блок обработан.
+   * Блоки обрабатываются строго последовательно (concurrency=1).
+   */
+  process(block) {
+    return this.queue.add(() => this.processBlock(block));
+  }
+  async processBlock(block) {
+    const actionEvents = [];
+    const deltaEvents = [];
+    const nativeDeltaEvents = [];
+    const blockNum = block.thisBlock.blockNum;
+    const blockId = block.thisBlock.blockId;
+    const blockTime = block.traces[0]?.blockTime ?? (/* @__PURE__ */ new Date()).toISOString();
+    for (const trace of block.traces) {
+      const abiBytes = await this.abiBootstrapper.ensureAbi(trace.account, blockNum);
+      const abiJson = abiBytes && abiBytes.length > 0 ? abiToJson(abiBytes) : "{}";
+      let data = {};
+      if (trace.actRaw.length > 0) {
+        try {
+          data = await this.workerPool.run({
+            rawBinary: trace.actRaw,
+            abiJson,
+            contract: trace.account,
+            typeName: trace.name,
+            kind: "action"
+          });
+        } catch {
+          data = {};
+        }
+      }
+      if (trace.account === "eosio" && trace.name === "setabi") {
+        const contractName = data["account"];
+        const abiHex = data["abi"];
+        if (typeof contractName === "string" && typeof abiHex === "string" && abiHex.length > 0) {
+          await this.abiStore.storeAbi(contractName, blockNum, Buffer.from(abiHex, "hex"));
+        }
+      }
+      const partial = {
+        kind: "action",
+        chain_id: this.chainId,
+        block_num: blockNum,
+        block_time: blockTime,
+        block_id: blockId,
+        account: trace.account,
+        name: trace.name,
+        authorization: [...trace.authorization],
+        data,
+        action_ordinal: trace.actionOrdinal,
+        global_sequence: trace.globalSequence,
+        receipt: trace.receipt
+      };
+      actionEvents.push({ ...partial, event_id: computeEventId(partial) });
+    }
+    for (const delta of block.deltas) {
+      if (delta.name === "account" && delta.present && delta.rowRaw.length > 0) {
+        const eosioAbiBytes = await this.abiBootstrapper.ensureAbi("eosio", blockNum);
+        const eosioAbiJson = eosioAbiBytes && eosioAbiBytes.length > 0 ? abiToJson(eosioAbiBytes) : "{}";
+        try {
+          const accountData = await this.workerPool.run({
+            rawBinary: delta.rowRaw,
+            abiJson: eosioAbiJson,
+            contract: "eosio",
+            typeName: "account",
+            kind: "delta"
+          });
+          const accountName = accountData["name"];
+          const abiHex = accountData["abi"];
+          if (typeof accountName === "string" && typeof abiHex === "string" && abiHex.length > 0) {
+            await this.abiStore.storeAbi(accountName, blockNum, Buffer.from(abiHex, "hex"));
+          }
+        } catch {
+        }
+      }
+      if (delta.name === "contract_row") {
+        if (!delta.code || !delta.scope || !delta.table || !delta.primaryKey) continue;
+        const abiBytes = await this.abiBootstrapper.ensureAbi(delta.code, blockNum);
+        const abiJson = abiBytes && abiBytes.length > 0 ? abiToJson(abiBytes) : "{}";
+        let value = {};
+        if (delta.rowRaw.length > 0) {
+          try {
+            value = await this.workerPool.run({
+              rawBinary: delta.rowRaw,
+              abiJson,
+              contract: delta.code,
+              typeName: delta.table,
+              kind: "delta"
+            });
+          } catch {
+            value = {};
+          }
+        }
+        const partial = {
+          kind: "delta",
+          chain_id: this.chainId,
+          block_num: blockNum,
+          block_time: blockTime,
+          block_id: blockId,
+          code: delta.code,
+          scope: delta.scope,
+          table: delta.table,
+          primary_key: delta.primaryKey,
+          value,
+          present: delta.present
+        };
+        deltaEvents.push({ ...partial, event_id: computeEventId(partial) });
+        continue;
+      }
+      if (isNativeTableName(delta.name)) {
+        try {
+          const native = this.chainClient.deserializeNativeDelta(delta);
+          const partial = {
+            kind: "native-delta",
+            chain_id: this.chainId,
+            block_num: blockNum,
+            block_time: blockTime,
+            block_id: blockId,
+            table: native.table,
+            lookup_key: native.lookup_key,
+            data: native.data,
+            present: native.present
+          };
+          nativeDeltaEvents.push({ ...partial, event_id: computeEventId(partial) });
+        } catch {
+        }
+      }
+    }
+    return [...actionEvents, ...deltaEvents, ...nativeDeltaEvents];
+  }
+  /** Число заданий, ожидающих обработки (в очереди + текущее). */
+  get pendingCount() {
+    return this.queue.size + this.queue.pending;
+  }
+  /** Ждёт завершения всех задач в очереди (вызывается при graceful shutdown). */
+  onIdle() {
+    return this.queue.onIdle();
+  }
+};
+
+// src/core/XtrimSupervisor.ts
+var XtrimSupervisor = class {
+  timer = null;
+  redis;
+  stream;
+  intervalMs;
+  constructor(opts) {
+    this.redis = opts.redis;
+    this.stream = opts.stream;
+    this.intervalMs = opts.intervalMs ?? 6e4;
+  }
+  /** Запускает периодический trim. Идемпотентен — повторный вызов игнорируется. */
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.trim();
+    }, this.intervalMs);
+    this.timer.unref?.();
+  }
+  /** Останавливает trim-цикл (вызывается при graceful shutdown). */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /**
+   * Один цикл очистки:
+   * 1. Получаем список consumer groups через XINFO GROUPS.
+   * 2. Фильтруем группы у которых есть pending сообщения (pending > 0).
+   * 3. Находим минимальный lastDeliveredId среди таких групп.
+   * 4. XTRIM stream MINID minId — удаляем всё старее этого ID.
+   *
+   * Если pending-групп нет — trim не делается (всё подтверждено).
+   * Если стрим не существует или XInfo бросает — тихо игнорируем (best-effort).
+   */
+  async trim() {
+    try {
+      const groups = await this.redis.xinfoGroups(this.stream);
+      if (!groups || groups.length === 0) return;
+      const pendingGroups = groups.filter((g) => g.pending > 0);
+      if (pendingGroups.length === 0) return;
+      const minId = pendingGroups.map((g) => g.lastDeliveredId).reduce((a, b) => a < b ? a : b);
+      if (minId) await this.redis.xtrim(this.stream, minId);
+    } catch {
+    }
+  }
+};
+
+// src/core/ForkDetector.ts
+var ForkDetector = class {
+  /** -1 означает «ещё не видели ни одного блока». */
+  lastBlockNum = -1;
+  chainId;
+  constructor(chainId) {
+    this.chainId = chainId;
+  }
+  /**
+   * Проверяет, является ли входящий блок форком.
+   * Должен вызываться один раз перед обработкой каждого блока.
+   *
+   * @returns ForkEvent если обнаружен форк, null при нормальной последовательности.
+   */
+  check(blockNum, blockId) {
+    let event = null;
+    if (this.lastBlockNum >= 0 && blockNum <= this.lastBlockNum) {
+      const partial = {
+        kind: "fork",
+        chain_id: this.chainId,
+        forked_from_block: this.lastBlockNum,
+        new_head_block_id: blockId
+      };
+      event = { ...partial, event_id: computeEventId(partial) };
+    }
+    this.lastBlockNum = blockNum;
+    return event;
+  }
+  /**
+   * Сбрасывает историю (вызывается при переподключении к SHiP-ноде,
+   * чтобы не ложно детектировать форк при старте с произвольного блока).
+   */
+  reset() {
+    this.lastBlockNum = -1;
+  }
+};
+
+// src/redis/keys.ts
+var RedisKeys = {
+  /**
+   * Главный поток событий парсера (unified event stream).
+   * Тип Redis: Stream. Тримируется XtrimSupervisor'ом.
+   * Пример: ce:parser:eos-mainnet:events
+   */
+  eventsStream: (chainId) => `ce:parser:${chainId}:events`,
+  /**
+   * Dead-letter поток для конкретной подписки.
+   * Содержит сообщения, которые не смог обработать consumer после N попыток.
+   * Тип Redis: Stream.
+   * Пример: ce:parser:eos-mainnet:dead:verifier
+   */
+  deadLetterStream: (chainId, subId) => `ce:parser:${chainId}:dead:${subId}`,
+  /**
+   * Поток для задания on-demand reparse (зарезервировано для будущего).
+   * Тип Redis: Stream.
+   */
+  reparseStream: (chainId, jobId) => `ce:parser:${chainId}:reparse:${jobId}`,
+  /**
+   * История версий ABI конкретного контракта.
+   * Тип Redis: Sorted Set. Score = block_num, member = base64(rawAbiBytes).
+   * При поиске ABI для блока N используется ZREVRANGEBYSCORE … N -inf LIMIT 0 1.
+   * Пример: parser:abi:eosio.token
+   */
+  abiZset: (contract) => `parser:abi:${contract}`,
+  /**
+   * Контрольная точка синхронизации парсера (crash-recovery).
+   * Тип Redis: Hash. Поля: block_num, block_id, last_updated.
+   * При рестарте парсер читает отсюда позицию и продолжает с неё.
+   */
+  syncHash: (chainId) => `parser:sync:${chainId}`,
+  /**
+   * Реестр всех зарегистрированных подписок.
+   * Тип Redis: Hash. Ключ поля = subId, значение = JSON-метаданные подписки.
+   */
+  subsHash: () => `parser:subs`,
+  /**
+   * Счётчики ошибок per-event для конкретной подписки.
+   * Тип Redis: Hash. Ключ поля = event_id, значение = число провалов.
+   * TTL: 24 часа (обновляется при каждом новом провале).
+   * Используется FailureTracker для решения о переводе в dead-letter.
+   */
+  subFailuresHash: (subId) => `parser:sub:${subId}:failures`,
+  /**
+   * Блокировка single-active-consumer для подписки.
+   * Тип Redis: String (instanceId держателя блокировки). TTL: 10 с (автопродление).
+   * Только один экземпляр consumer-а может быть active; остальные — standby.
+   */
+  subLock: (subId) => `parser:sub:${subId}:lock`,
+  /**
+   * Метаданные задания reparse (зарезервировано для будущего).
+   * Тип Redis: Hash.
+   */
+  reparseJobHash: (jobId) => `parser:reparse:${jobId}`
+};
+
+// src/abi/AbiStore.ts
+var AbiStore = class {
+  constructor(redis) {
+    this.redis = redis;
+  }
+  redis;
+  /**
+   * Ищет версию ABI контракта, актуальную на момент blockNum.
+   * Использует ZREVRANGEBYSCORE: возвращает последнюю запись со score ≤ blockNum.
+   * @returns Байты ABI или null если история пуста для данного контракта.
+   */
+  async getAbi(contract, blockNum) {
+    const key = RedisKeys.abiZset(contract);
+    const results = await this.redis.zrangeByscoreRev(key, String(blockNum), "-inf");
+    if (results.length === 0 || !results[0]) return null;
+    return Buffer.from(results[0], "base64");
+  }
+  /**
+   * Сохраняет новую версию ABI, привязывая её к blockNum.
+   * Вызывается AbiBootstrapper при первом наблюдении контракта и
+   * BlockProcessor'ом при перехвате eosio::setabi / account-дельты.
+   */
+  async storeAbi(contract, blockNum, abiBytes) {
+    const key = RedisKeys.abiZset(contract);
+    const member = Buffer.from(abiBytes).toString("base64");
+    await this.redis.zadd(key, blockNum, member);
+  }
+};
+
+// src/abi/AbiBootstrapper.ts
+var AbiBootstrapper = class {
+  constructor(chainClient, abiStore, opts) {
+    this.chainClient = chainClient;
+    this.abiStore = abiStore;
+    this.abiFallback = opts?.abiFallback ?? "rpc-current";
+  }
+  chainClient;
+  abiStore;
+  /** Контракты, ABI которых уже гарантированно записан в Redis в этом сеансе. */
+  observedContracts = /* @__PURE__ */ new Set();
+  abiFallback;
+  /**
+   * Гарантирует наличие ABI для контракта в кэше перед декодированием события.
+   *
+   * Быстрый путь: контракт уже в observedContracts → сразу идём в Redis.
+   * Медленный путь: первая встреча → проверяем Redis → если пусто, скачиваем с RPC.
+   *
+   * @param contract — имя аккаунта-контракта (например 'eosio.token').
+   * @param blockNum — номер блока, для которого нужна ABI (для поиска версии).
+   * @returns Байты ABI или null если ABI недоступен и abiFallback='rpc-current'.
+   * @throws AbiNotFoundError если abiFallback='fail' и ABI не найден.
+   */
+  async ensureAbi(contract, blockNum) {
+    if (this.observedContracts.has(contract)) {
+      return this.abiStore.getAbi(contract, blockNum);
+    }
+    const stored = await this.abiStore.getAbi(contract, blockNum);
+    if (stored) {
+      this.observedContracts.add(contract);
+      return stored;
+    }
+    this.observedContracts.add(contract);
+    try {
+      const abiBytes = await this.chainClient.getRawAbi(contract);
+      await this.abiStore.storeAbi(contract, blockNum, abiBytes);
+      return abiBytes;
+    } catch {
+      if (this.abiFallback === "fail") {
+        throw new AbiNotFoundError(contract, blockNum, this.abiFallback);
+      }
+      return null;
+    }
+  }
+};
+
+// src/core/Parser.ts
+var Parser = class _Parser {
+  opts;
+  chainClient = null;
+  redis = null;
+  workerPool = null;
+  blockProcessor = null;
+  xtrimSupervisor = null;
+  running = false;
+  stopSignal = false;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  static fromConfigFile(filePath) {
+    return new _Parser(fromConfigFile(filePath));
+  }
+  static fromConfig(raw) {
+    return new _Parser(parseConfig(raw));
+  }
+  async start() {
+    this.stopSignal = false;
+    this.running = true;
+    if (!this.opts.noSignalHandlers) {
+      const shutdown = () => void this.stop();
+      process.once("SIGTERM", shutdown);
+      process.once("SIGINT", shutdown);
+    }
+    this.redis = new IoRedisStore(this.opts.redis);
+    await this.redis.connect();
+    await this.checkRedisPersistence();
+    this.workerPool = new WorkerPool(this.opts.workerPool?.maxThreads ?? 2);
+    const shipOpts = {
+      url: this.opts.ship.url
+    };
+    if (this.opts.ship.timeoutMs !== void 0) shipOpts.timeoutMs = this.opts.ship.timeoutMs;
+    if (this.opts.chain?.url !== void 0) shipOpts.chainUrl = this.opts.chain.url;
+    this.chainClient = new ShipReaderAdapter(shipOpts);
+    const { chainId } = await this.chainClient.connect();
+    if (this.opts.chain?.id && this.opts.chain.id !== chainId) {
+      throw new ChainIdMismatchError(this.opts.chain.id, chainId);
+    }
+    const abiFallback = this.opts.abiFallback ?? "rpc-current";
+    const abiStore = new AbiStore(this.redis);
+    const abiBootstrapper = new AbiBootstrapper(this.chainClient, abiStore, { abiFallback });
+    this.blockProcessor = new BlockProcessor({
+      chainId,
+      workerPool: this.workerPool,
+      abiBootstrapper,
+      abiStore,
+      chainClient: this.chainClient
+    });
+    const syncKey = RedisKeys.syncHash(chainId);
+    const eventsStream = RedisKeys.eventsStream(chainId);
+    const lastBlockNum = await this.redis.hget(syncKey, "block_num");
+    const lastBlockId = await this.redis.hget(syncKey, "block_id");
+    const havePositions = lastBlockNum && lastBlockId ? [{ blockNum: Number(lastBlockNum), blockId: lastBlockId }] : [];
+    const xtrimOpts = {
+      redis: this.redis,
+      stream: eventsStream
+    };
+    if (this.opts.xtrim?.intervalMs !== void 0) xtrimOpts.intervalMs = this.opts.xtrim.intervalMs;
+    this.xtrimSupervisor = new XtrimSupervisor(xtrimOpts);
+    if (this.opts.xtrim?.enabled !== false) {
+      this.xtrimSupervisor.start();
+    }
+    const streamOpts = {
+      startBlock: havePositions[0]?.blockNum ?? 0,
+      havePositions
+    };
+    const irreversibleOnly = this.opts.irreversibleOnly ?? false;
+    const forkDetector = new ForkDetector(chainId);
+    for await (const block of this.chainClient.streamBlocks(streamOpts)) {
+      if (this.stopSignal) break;
+      if (irreversibleOnly && block.thisBlock.blockNum > block.lastIrreversible.blockNum) {
+        this.chainClient.ack(1);
+        continue;
+      }
+      const forkEvent = forkDetector.check(block.thisBlock.blockNum, block.thisBlock.blockId);
+      const events = await this.blockProcessor.process(block);
+      const toPublish = forkEvent ? [forkEvent, ...events] : events;
+      for (const event of toPublish) {
+        await this.redis.xadd(eventsStream, this.eventToFields(event));
+      }
+      await this.redis.hset(syncKey, {
+        block_num: String(block.thisBlock.blockNum),
+        block_id: block.thisBlock.blockId,
+        last_updated: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      this.chainClient.ack(1);
+    }
+  }
+  eventToFields(event) {
+    return {
+      data: JSON.stringify(
+        event,
+        (_k, v) => typeof v === "bigint" ? v.toString() : v
+      )
+    };
+  }
+  async stop() {
+    this.stopSignal = true;
+    if (this.blockProcessor) {
+      await this.blockProcessor.onIdle();
+    }
+    if (this.chainClient) {
+      await this.chainClient.close();
+      this.chainClient = null;
+    }
+    if (this.workerPool) {
+      await this.workerPool.destroy();
+      this.workerPool = null;
+    }
+    if (this.xtrimSupervisor) {
+      this.xtrimSupervisor.stop();
+      this.xtrimSupervisor = null;
+    }
+    if (this.redis) {
+      await this.redis.quit();
+      this.redis = null;
+    }
+    this.running = false;
+  }
+  get isRunning() {
+    return this.running;
+  }
+  async checkRedisPersistence() {
+    const redis = this.redis;
+    try {
+      const aofResult = await redis.hget("__parser_check__", "__noop__");
+      void aofResult;
+    } catch {
+    }
+  }
+};
+
+// src/client/ParserClient.ts
+import { randomUUID } from "crypto";
+import { hostname } from "os";
+
+// src/client/SubscriptionLock.ts
+var LOCK_TTL_MS = 1e4;
+var HEARTBEAT_MS = 3e3;
+var STANDBY_POLL_MS = 500;
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+var SubscriptionLock = class {
+  redis;
+  key;
+  instanceId;
+  heartbeatMs;
+  acquireTimeoutMs;
+  heartbeatTimer = null;
+  _state = "acquiring";
+  constructor(opts) {
+    this.redis = opts.redis;
+    this.key = RedisKeys.subLock(opts.subId);
+    this.instanceId = opts.instanceId;
+    this.heartbeatMs = opts.heartbeatIntervalMs ?? HEARTBEAT_MS;
+    this.acquireTimeoutMs = opts.acquireLockTimeoutMs ?? Infinity;
+  }
+  /** Текущее состояние: acquiring → active/standby → released. */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Пробует захватить lock одним атомарным SET NX PX.
+   * @returns true если захватили (state = active), false если занят (state = standby).
+   */
+  async acquire() {
+    const acquired = await this.redis.setNx(this.key, this.instanceId, LOCK_TTL_MS);
+    if (acquired) {
+      this._state = "active";
+      this.startHeartbeat();
+    } else {
+      this._state = "standby";
+    }
+    return acquired;
+  }
+  /**
+   * Блокирует текущий процесс до тех пор пока lock не освободится и мы его захватим.
+   * Опрашивает Redis каждые STANDBY_POLL_MS мс.
+   * @throws Error если acquireLockTimeoutMs истёк.
+   */
+  async waitForPromotion() {
+    const deadline = this.acquireTimeoutMs === Infinity ? Infinity : Date.now() + this.acquireTimeoutMs;
+    while (true) {
+      if (Date.now() > deadline) {
+        throw new Error(`Lock acquire timeout after ${this.acquireTimeoutMs}ms`);
+      }
+      await sleep(STANDBY_POLL_MS);
+      const acquired = await this.redis.setNx(this.key, this.instanceId, LOCK_TTL_MS);
+      if (acquired) {
+        this._state = "active";
+        this.startHeartbeat();
+        return;
+      }
+    }
+  }
+  /** Запускает периодическое продление TTL (heartbeat). */
+  startHeartbeat() {
+    this.heartbeatTimer = setInterval(() => {
+      void this.renewHeartbeat();
+    }, this.heartbeatMs);
+    this.heartbeatTimer.unref?.();
+  }
+  /**
+   * Один шаг heartbeat: продлеваем TTL через LUA-скрипт.
+   * Если LUA вернул false — кто-то другой захватил lock (race condition после
+   * истечения нашего TTL). Переходим в standby.
+   */
+  async renewHeartbeat() {
+    const renewed = await this.redis.pexpire(this.key, LOCK_TTL_MS, this.instanceId);
+    if (!renewed && this._state === "active") {
+      this.stopHeartbeat();
+      this._state = "standby";
+    }
+  }
+  /** Останавливает heartbeat-таймер (без освобождения lock'а). */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  /**
+   * Освобождает lock: останавливает heartbeat, удаляет ключ через LUA (conditional).
+   * После вызова state = 'released'.
+   */
+  async release() {
+    this.stopHeartbeat();
+    await this.redis.luaDel(this.key, this.instanceId);
+    this._state = "released";
+  }
+};
+
+// src/client/RedisConsumer.ts
+var CONSUMER_NAME = "primary";
+var RedisConsumer = class {
+  redis;
+  stream;
+  groupName;
+  blockMs;
+  count;
+  stopped = false;
+  constructor(opts) {
+    this.redis = opts.redis;
+    this.stream = opts.stream;
+    this.groupName = opts.groupName;
+    this.blockMs = opts.blockMs ?? 2e3;
+    this.count = opts.count ?? 10;
+  }
+  /**
+   * XGROUP CREATE stream groupName startId MKSTREAM
+   * Создаёт group (или игнорирует если уже существует — BUSYGROUP).
+   * startId='$' — читать только новые; startId='0' — с самого начала.
+   */
+  async init(startId = "$") {
+    await this.redis.xgroupCreate(this.stream, this.groupName, startId);
+  }
+  /**
+   * XGROUP SETID — переставляет позицию group (для reset-subscription).
+   * Примечание: здесь используется xgroupCreate что идемпотентно;
+   * для точного SETID нужен xgroupSetId из RedisStore.
+   */
+  async setStartId(id) {
+    await this.redis.xgroupCreate(this.stream, this.groupName, id);
+  }
+  /**
+   * Читает PEL (pending entries) с id='0': сообщения, доставленные но не подтверждённые.
+   * Вызывается при старте для recovery после крэша.
+   */
+  async recoverOwnPending() {
+    return this.redis.xreadGroup(
+      this.stream,
+      this.groupName,
+      CONSUMER_NAME,
+      100,
+      0,
+      // blockMs=0: не блокировать при чтении PEL
+      "0"
+      // id='0': PEL
+    );
+  }
+  /**
+   * Асинхронный генератор сообщений.
+   *
+   * Порядок:
+   * 1. Сначала отдаём все pending (незавершённые из предыдущей сессии).
+   * 2. Затем в бесконечном цикле читаем новые (BLOCK 2000 мс).
+   *
+   * Цикл прерывается при вызове stop().
+   * Каждое сообщение нужно подтвердить через ack(msg.id).
+   */
+  async *read() {
+    const pending = await this.recoverOwnPending();
+    for (const msg of pending) {
+      yield msg;
+    }
+    while (!this.stopped) {
+      const messages = await this.redis.xreadGroup(
+        this.stream,
+        this.groupName,
+        CONSUMER_NAME,
+        this.count,
+        this.blockMs,
+        ">"
+        // id='>': только непрочитанные новые
+      );
+      for (const msg of messages) {
+        if (this.stopped) return;
+        yield msg;
+      }
+    }
+  }
+  /** XACK stream groupName id — подтверждает что сообщение обработано. */
+  async ack(id) {
+    await this.redis.xack(this.stream, this.groupName, id);
+  }
+  /** Сигнализирует генератору прекратить чтение (graceful stop). */
+  stop() {
+    this.stopped = true;
+  }
+};
+
+// src/client/FailureTracker.ts
+var FAILURE_THRESHOLD = 3;
+var FAILURE_TTL_SECONDS = 86400;
+var FailureTracker = class {
+  redis;
+  chainId;
+  constructor(redis, chainId) {
+    this.redis = redis;
+    this.chainId = chainId;
+  }
+  /**
+   * Инкрементирует счётчик ошибок для eventId и продлевает TTL хэша.
+   * @returns Новое значение счётчика (1, 2, 3, …).
+   */
+  async recordFailure(subId, eventId) {
+    const key = RedisKeys.subFailuresHash(subId);
+    const count = await this.redis.hincrby(key, eventId, 1);
+    await this.redis.expire(key, FAILURE_TTL_SECONDS);
+    return count;
+  }
+  /**
+   * Возвращает текущий счётчик ошибок для eventId.
+   * 0 если счётчик не существует (событие ещё не проваливалось).
+   */
+  async getFailureCount(subId, eventId) {
+    const key = RedisKeys.subFailuresHash(subId);
+    const val = await this.redis.hget(key, eventId);
+    return val ? parseInt(val, 10) : 0;
+  }
+  /**
+   * Проверяет достиг ли счётчик порога для dead-letter.
+   * Вызывается после recordFailure: if (shouldDeadLetter(count)) { … }
+   */
+  shouldDeadLetter(count) {
+    return count >= FAILURE_THRESHOLD;
+  }
+  /**
+   * Записывает событие в dead-letter stream с метаданными об ошибке.
+   * Dead-letter stream: ce:parser:<chainId>:dead:<subId>
+   * Поля записи: data (оригинальный payload), failureCount, lastError, subId.
+   */
+  async routeToDeadLetter(subId, eventId, payload, lastError) {
+    const stream = RedisKeys.deadLetterStream(this.chainId, subId);
+    await this.redis.xadd(stream, {
+      ...payload,
+      failureCount: String(FAILURE_THRESHOLD),
+      lastError,
+      subId
+    });
+  }
+  /**
+   * Сбрасывает счётчик ошибок для eventId после успешной обработки.
+   * Вызывается после успешного yield события в ParserClient.
+   */
+  async clearFailure(subId, eventId) {
+    await this.redis.hdel(RedisKeys.subFailuresHash(subId), eventId);
+  }
+};
+
+// src/client/filters.ts
+function matchesWildcard(value, pattern) {
+  if (pattern === void 0 || pattern === "*") return true;
+  return value === pattern;
+}
+function matchAction(event, filter) {
+  if (!matchesWildcard(event.account, filter.account)) return false;
+  if (!matchesWildcard(event.name, filter.name)) return false;
+  if (filter.data) {
+    for (const [k, v] of Object.entries(filter.data)) {
+      if (event.data[k] !== v) return false;
+    }
+  }
+  return true;
+}
+function matchDelta(event, filter) {
+  if (!matchesWildcard(event.code, filter.code)) return false;
+  if (!matchesWildcard(event.table, filter.table)) return false;
+  if (!matchesWildcard(event.scope, filter.scope)) return false;
+  return true;
+}
+function matchNativeDelta(event, filter) {
+  return matchesWildcard(event.table, filter.table);
+}
+function matchOne(event, filter) {
+  if (event.kind !== filter.kind) return false;
+  if (filter.kind === "action") return matchAction(event, filter);
+  if (filter.kind === "delta") return matchDelta(event, filter);
+  if (filter.kind === "native-delta") return matchNativeDelta(event, filter);
+  if (filter.kind === "fork") return true;
+  const _exhaustive = filter;
+  return _exhaustive;
+}
+function matchFilters(event, filters) {
+  if (!filters || filters.length === 0) return true;
+  return filters.some((f) => matchOne(event, f));
+}
+
+// src/client/ParserClient.ts
+var ParserClient = class {
+  opts;
+  redis = null;
+  lock = null;
+  consumer = null;
+  failureTracker = null;
+  /** Уникальный ID этого экземпляра — используется как значение distributed lock'а. */
+  instanceId;
+  closed = false;
+  constructor(opts) {
+    this.opts = opts;
+    this.instanceId = `${hostname()}:${process.pid}:${randomUUID()}`;
+  }
+  /**
+   * Основной AsyncGenerator: инициализирует подключение и начинает yield событий.
+   *
+   * Этапы старта:
+   *   1. Подключаемся к Redis.
+   *   2. Регистрируем подписку в HSET parser:subs.
+   *   3. Пытаемся захватить lock; если занят — ждём освобождения.
+   *   4. Определяем startId для consumer group.
+   *   5. Создаём consumer group (XGROUP CREATE).
+   *   6. Читаем события в цикле, фильтруем, yield'им.
+   *
+   * Генератор завершается при вызове close().
+   */
+  async *stream() {
+    this.redis = new IoRedisStore(this.opts.redis);
+    await this.redis.connect();
+    const subId = this.opts.subscriptionId;
+    const chainId = this.opts.chain.id;
+    const stream = RedisKeys.eventsStream(chainId);
+    const groupName = subId;
+    this.failureTracker = new FailureTracker(this.redis, chainId);
+    await this.redis.hset(RedisKeys.subsHash(), {
+      [subId]: JSON.stringify({
+        subId,
+        filters: this.opts.filters ?? [],
+        startFrom: this.opts.startFrom ?? "last_known",
+        registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    });
+    const lockOpts = {
+      redis: this.redis,
+      subId,
+      instanceId: this.instanceId
+    };
+    if (this.opts.acquireLockTimeoutMs !== void 0) {
+      lockOpts.acquireLockTimeoutMs = this.opts.acquireLockTimeoutMs;
+    }
+    this.lock = new SubscriptionLock(lockOpts);
+    if (!this.opts.noSignalHandlers) {
+      const close = () => void this.close();
+      process.once("SIGTERM", close);
+      process.once("SIGINT", close);
+    }
+    const acquired = await this.lock.acquire();
+    if (!acquired) {
+      await this.lock.waitForPromotion();
+    }
+    const startFrom = this.opts.startFrom ?? "last_known";
+    let startId;
+    if (startFrom === "last_known") {
+      startId = "$";
+    } else if (startFrom === "head-minus-1000") {
+      startId = "0";
+    } else {
+      startId = `${startFrom}-0`;
+    }
+    this.consumer = new RedisConsumer({
+      redis: this.redis,
+      stream,
+      groupName,
+      blockMs: 2e3
+    });
+    await this.consumer.init(startId);
+    for await (const msg of this.consumer.read()) {
+      if (this.closed) break;
+      const rawData = msg.fields["data"];
+      if (!rawData) {
+        await this.consumer.ack(msg.id);
+        continue;
+      }
+      let event;
+      try {
+        event = JSON.parse(rawData);
+        if (event.kind === "action" && typeof event.global_sequence === "string") {
+          event = { ...event, global_sequence: BigInt(event.global_sequence) };
+        }
+      } catch {
+        await this.consumer.ack(msg.id);
+        continue;
+      }
+      if (!matchFilters(event, this.opts.filters)) {
+        await this.consumer.ack(msg.id);
+        continue;
+      }
+      try {
+        yield event;
+        await this.consumer.ack(msg.id);
+        await this.failureTracker.clearFailure(subId, event.event_id);
+      } catch (err) {
+        const count = await this.failureTracker.recordFailure(subId, event.event_id);
+        if (this.failureTracker.shouldDeadLetter(count)) {
+          await this.failureTracker.routeToDeadLetter(
+            subId,
+            event.event_id,
+            msg.fields,
+            err instanceof Error ? err.message : String(err)
+          );
+          await this.consumer.ack(msg.id);
+          await this.failureTracker.clearFailure(subId, event.event_id);
+        }
+      }
+    }
+  }
+  /**
+   * Graceful shutdown: останавливает генератор, освобождает lock, закрывает Redis.
+   */
+  async close() {
+    this.closed = true;
+    this.consumer?.stop();
+    if (this.lock) {
+      this.lock.stopHeartbeat();
+      await this.lock.release();
+    }
+    if (this.redis) {
+      await this.redis.quit();
+      this.redis = null;
+    }
+  }
+  /** Закрывает клиент и завершает процесс (для использования в SIGINT-обработчике). */
+  closeAndExit() {
+    void (async () => {
+      await this.close();
+      process.exit(0);
+    })();
+  }
+};
+
+// src/index.ts
+import { NATIVE_TABLE_NAMES, isNativeTableName as isNativeTableName2 } from "@coopenomics/coopos-ship-reader";
+
+// src/core/ReconnectSupervisor.ts
+var DEFAULT_BACKOFF_SECONDS = [1, 2, 5, 15, 60];
+var DEFAULT_MAX_ATTEMPTS = 10;
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+var ReconnectSupervisor = class {
+  maxAttempts;
+  backoffSeconds;
+  onAttempt;
+  onGiveUp;
+  constructor(opts = {}) {
+    this.maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.backoffSeconds = opts.backoffSeconds ?? DEFAULT_BACKOFF_SECONDS;
+    this.onAttempt = opts.onAttempt ?? (() => void 0);
+    this.onGiveUp = opts.onGiveUp ?? ((n) => {
+      process.stderr.write(`ReconnectSupervisor: exhausted ${n} attempts, exiting
+`);
+      process.exit(1);
+    });
+  }
+  /**
+   * Запускает fn и повторяет при исключении с паузами.
+   *
+   * Псевдокод:
+   *   loop:
+   *     try: return await fn()
+   *     catch: attempt++
+   *       if attempt >= maxAttempts: onGiveUp(); throw
+   *       delay = backoffSeconds[min(attempt-1, len-1)] * 1000
+   *       onAttempt(attempt, delay); sleep(delay)
+   *
+   * @returns Результат первого успешного вызова fn.
+   */
+  async run(fn) {
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return await fn();
+      } catch (err) {
+        attempt++;
+        if (attempt >= this.maxAttempts) {
+          this.onGiveUp(attempt);
+          throw err;
+        }
+        const backoffIdx = Math.min(attempt - 1, this.backoffSeconds.length - 1);
+        const delayMs = (this.backoffSeconds[backoffIdx] ?? 60) * 1e3;
+        this.onAttempt(attempt, delayMs);
+        await sleep2(delayMs);
+      }
+    }
+  }
+};
+
+// src/logger.ts
+import pino from "pino";
+var REDACT_PATHS = [
+  "password",
+  "token",
+  "secret",
+  "authorization",
+  "*.password",
+  "*.token",
+  "*.secret",
+  "*.authorization",
+  "redis.password",
+  "redis.url"
+  // Redis URL может содержать пароль в строке подключения
+];
+function createLogger(opts = {}) {
+  const level = opts.level ?? (process.env["LOG_LEVEL"] ?? "info");
+  const pretty = opts.pretty ?? process.env["NODE_ENV"] === "development";
+  const base = {};
+  if (opts.chain_id) base["chain_id"] = opts.chain_id;
+  const transport = pretty ? { target: "pino-pretty", options: { colorize: true, translateTime: "SYS:standard" } } : void 0;
+  const logger = pino(
+    {
+      level,
+      redact: { paths: REDACT_PATHS, censor: "[REDACTED]" },
+      base
+    },
+    transport ? pino.transport(transport) : pino.destination(1)
+  );
+  return logger;
+}
+var rootLogger = createLogger();
+
+// src/metrics/parserMetrics.ts
+import {
+  Counter,
+  Gauge,
+  Histogram,
+  Registry
+} from "prom-client";
+function createParserMetrics(prefix = "parser") {
+  const registry = new Registry();
+  const blocksProcessedTotal = new Counter({
+    name: `${prefix}_blocks_processed_total`,
+    help: "Total number of blocks processed by the parser",
+    registers: [registry]
+  });
+  const indexingLagSeconds = new Gauge({
+    name: `${prefix}_indexing_lag_seconds`,
+    help: "Lag between head block time and current block time in seconds",
+    registers: [registry]
+  });
+  const eventsPublishedTotal = new Counter({
+    name: `${prefix}_events_published_total`,
+    help: "Total events published to Redis stream",
+    labelNames: ["kind"],
+    registers: [registry]
+  });
+  const abiCacheHitsTotal = new Counter({
+    name: `${prefix}_abi_cache_hits_total`,
+    help: "Number of ABI cache hits",
+    registers: [registry]
+  });
+  const abiCacheMissesTotal = new Counter({
+    name: `${prefix}_abi_cache_misses_total`,
+    help: "Number of ABI cache misses (fetched from chain)",
+    registers: [registry]
+  });
+  const streamLength = new Gauge({
+    name: `${prefix}_stream_length`,
+    help: "Current length of the Redis events stream",
+    registers: [registry]
+  });
+  const xtrimmedEntriesTotal = new Counter({
+    name: `${prefix}_xtrimmed_entries_total`,
+    help: "Total number of entries removed by XTRIM",
+    registers: [registry]
+  });
+  const blockProcessingDuration = new Histogram({
+    name: `${prefix}_block_processing_duration_seconds`,
+    help: "Duration of block processing in seconds",
+    buckets: [1e-3, 5e-3, 0.01, 0.05, 0.1, 0.5, 1, 5],
+    registers: [registry]
+  });
+  const workerPoolQueueDepth = new Gauge({
+    name: `${prefix}_worker_pool_queue_depth`,
+    help: "Current number of tasks queued in the Piscina worker pool",
+    registers: [registry]
+  });
+  const blockProcessingErrors = new Counter({
+    name: `${prefix}_block_processing_errors_total`,
+    help: "Total number of block processing errors",
+    registers: [registry]
+  });
+  return {
+    registry,
+    blocksProcessedTotal,
+    indexingLagSeconds,
+    eventsPublishedTotal,
+    abiCacheHitsTotal,
+    abiCacheMissesTotal,
+    streamLength,
+    xtrimmedEntriesTotal,
+    blockProcessingDuration,
+    workerPoolQueueDepth,
+    blockProcessingErrors
+  };
+}
+
+// src/metrics/clientMetrics.ts
+import {
+  Counter as Counter2,
+  Gauge as Gauge2,
+  Histogram as Histogram2,
+  Registry as Registry2
+} from "prom-client";
+function createClientMetrics(prefix = "parser_client") {
+  const registry = new Registry2();
+  const handlerErrorsTotal = new Counter2({
+    name: `${prefix}_handler_errors_total`,
+    help: "Total errors thrown by subscription event handlers",
+    labelNames: ["sub_id", "kind"],
+    registers: [registry]
+  });
+  const handlerDurationSeconds = new Histogram2({
+    name: `${prefix}_handler_duration_seconds`,
+    help: "Duration of subscription handler execution in seconds",
+    labelNames: ["sub_id", "kind"],
+    buckets: [1e-3, 5e-3, 0.01, 0.05, 0.1, 0.5, 1],
+    registers: [registry]
+  });
+  const subscriptionLockState = new Gauge2({
+    name: `${prefix}_subscription_lock_state`,
+    help: "Lock state gauge: 1=active, 0=standby/acquiring",
+    labelNames: ["sub_id", "role"],
+    registers: [registry]
+  });
+  const deadLettersTotal = new Counter2({
+    name: `${prefix}_dead_letters_total`,
+    help: "Total messages routed to dead-letter stream",
+    labelNames: ["sub_id"],
+    registers: [registry]
+  });
+  const messagesConsumedTotal = new Counter2({
+    name: `${prefix}_messages_consumed_total`,
+    help: "Total messages read from the events stream",
+    labelNames: ["sub_id"],
+    registers: [registry]
+  });
+  const messageAcknowledgedTotal = new Counter2({
+    name: `${prefix}_messages_acknowledged_total`,
+    help: "Total messages acknowledged (XACK)",
+    labelNames: ["sub_id"],
+    registers: [registry]
+  });
+  const consumerPendingMessages = new Gauge2({
+    name: `${prefix}_consumer_pending_messages`,
+    help: "Current number of pending (unacknowledged) messages for this consumer",
+    labelNames: ["sub_id"],
+    registers: [registry]
+  });
+  const filterMatchesTotal = new Counter2({
+    name: `${prefix}_filter_matches_total`,
+    help: "Total events that matched subscription filters",
+    labelNames: ["sub_id", "kind"],
+    registers: [registry]
+  });
+  return {
+    registry,
+    handlerErrorsTotal,
+    handlerDurationSeconds,
+    subscriptionLockState,
+    deadLettersTotal,
+    messagesConsumedTotal,
+    messageAcknowledgedTotal,
+    consumerPendingMessages,
+    filterMatchesTotal
+  };
+}
+
+// src/observability/HttpServer.ts
+import { createServer } from "http";
+var HttpServer = class {
+  server;
+  port;
+  lagThresholdSeconds;
+  getLag;
+  metricsRegistry;
+  constructor(opts) {
+    this.port = opts.port ?? 9090;
+    this.lagThresholdSeconds = opts.lagThresholdSeconds ?? 60;
+    this.getLag = opts.getLag;
+    this.metricsRegistry = opts.metricsRegistry;
+    this.server = createServer((req, res) => void this.handle(req, res));
+  }
+  /** Запускает HTTP-сервер, разрешает Promise после успешного bind. */
+  start() {
+    return new Promise((resolve2, reject) => {
+      this.server.listen(this.port, () => resolve2());
+      this.server.once("error", reject);
+    });
+  }
+  /**
+   * Останавливает сервер и ждёт закрытия всех соединений.
+   * Вызывается при graceful shutdown парсера.
+   */
+  stop() {
+    return new Promise((resolve2, reject) => {
+      this.server.close((err) => err ? reject(err) : resolve2());
+    });
+  }
+  /** Диспетчеризация HTTP-запросов по URL. */
+  async handle(req, res) {
+    const url = req.url ?? "/";
+    if (url === "/health" || url === "/health/") {
+      const lagSeconds = this.getLag();
+      const degraded = lagSeconds > this.lagThresholdSeconds;
+      const body = {
+        status: degraded ? "degraded" : "ok",
+        indexingLagSeconds: lagSeconds,
+        lagThresholdSeconds: this.lagThresholdSeconds
+      };
+      res.writeHead(degraded ? 503 : 200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body));
+      return;
+    }
+    if (url === "/metrics" || url === "/metrics/") {
+      try {
+        const content = await this.metricsRegistry.metrics();
+        res.writeHead(200, { "Content-Type": this.metricsRegistry.contentType });
+        res.end(content);
+      } catch (err) {
+        res.writeHead(500);
+        res.end("Internal error");
+      }
+      return;
+    }
+    res.writeHead(404);
+    res.end("Not found");
+  }
+};
+export {
+  AbiBootstrapper,
+  AbiNotFoundError,
+  AbiStore,
+  BlockProcessor,
+  CONSUMER_NAME,
+  ChainIdMismatchError,
+  ConfigSecurityError,
+  ConfigValidationError,
+  FailureTracker,
+  ForkDetector,
+  HttpServer,
+  IoRedisStore,
+  NATIVE_TABLE_NAMES,
+  NotImplementedError,
+  Parser,
+  ParserClient,
+  ReconnectSupervisor,
+  RedisConsumer,
+  RedisKeys,
+  ShipReaderAdapter,
+  SubscriptionLock,
+  WorkerPool,
+  XtrimSupervisor,
+  computeEventId,
+  createClientMetrics,
+  createLogger,
+  createParserMetrics,
+  fromConfigFile,
+  isNativeTableName2 as isNativeTableName,
+  matchFilters,
+  parseConfig,
+  rootLogger
+};
+//# sourceMappingURL=index.js.map