@coopenomics/parser 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1520 @@
+import { ActionAuthorization, ActionReceipt, NativeTableName, GetBlocksOptions, ShipBlock, ChainInfo, ShipDelta, NativeDeltaEvent as NativeDeltaEvent$1 } from '@coopenomics/coopos-ship-reader';
+export { NATIVE_TABLE_NAMES, NativeAccountMetadataRow, NativeAccountRow, NativeBlockInfoRow, NativeCodeRow, NativeContractTableRow, NativeFillStatusRow, NativeGeneratedTransactionRow, NativeGlobalPropertyRow, NativeKeyValueRow, NativePermissionLinkRow, NativePermissionRow, NativeProtocolStateRow, NativeReceivedBlockRow, NativeResourceLimitsConfigRow, NativeResourceLimitsRow, NativeResourceLimitsStateRow, NativeResourceUsageRow, NativeRowTypeMap, NativeTableName, isNativeTableName } from '@coopenomics/coopos-ship-reader';
+import pino from 'pino';
+import { Registry, Counter, Gauge, Histogram } from 'prom-client';
+
+/**
+ * Загрузка и валидация конфигурации парсера.
+ *
+ * Поддерживаемые форматы: YAML файл (fromConfigFile) или уже разобранный объект (parseConfig).
+ *
+ * Конвейер обработки:
+ *   1. Чтение YAML → parseYaml → raw object.
+ *   2. interpolateDeep: рекурсивно заменяет ${VAR} → process.env[VAR].
+ *      Если переменная не задана — оставляем плейсхолдер (не ломаем конфиг, но validate упадёт
+ *      если это обязательное поле).
+ *   3. validate: проверяет обязательные поля (ship.url, redis.url) и enum-значения.
+ *   4. checkPlainSecrets: запрещает хардкодированные пароли в Redis URL.
+ *      redis://:hardcoded-pass@host → ConfigSecurityError.
+ *      redis://${REDIS_PASSWORD}@host → OK (это плейсхолдер, не секрет).
+ *
+ * Почему env-интерполяция важна: операторы хранят конфиг в git без секретов,
+ * инжектируя их через переменные среды в Kubernetes / Docker. Формат ${VAR} — стандарт.
+ */
+/**
+ * Все настройки парсера в одном объекте.
+ * Передаётся в конструктор Parser и ParserClient.
+ * Все поля кроме ship и redis — опциональны (имеют дефолты в соответствующих модулях).
+ */
+interface ParserOptions {
+    /** SHiP WebSocket соединение. timeoutMs по умолчанию 10000. */
+    ship: {
+        url: string;
+        timeoutMs?: number;
+    };
+    /** Chain API для ABI fallback (abiFallback: 'rpc-current'). Опционален. */
+    chain?: {
+        url?: string;
+        id?: string;
+    };
+    /** Redis подключение. keyPrefix добавляет namespace к ключам (полезно при shared Redis). */
+    redis: {
+        url: string;
+        password?: string;
+        keyPrefix?: string;
+    };
+    /** Piscina worker pool для десериализации. maxThreads по умолчанию = CPU count / 2. */
+    workerPool?: {
+        maxThreads?: number;
+    };
+    /** Поведение при отсутствии ABI: 'rpc-current' = попробовать Chain API, 'fail' = ошибка. */
+    abiFallback?: 'rpc-current' | 'fail';
+    /** XtrimSupervisor: интервал проверки и включение/отключение автообрезки стрима. */
+    xtrim?: {
+        intervalMs?: number;
+        enabled?: boolean;
+    };
+    /** ReconnectSupervisor: максимум попыток и backoff-таблица в секундах. */
+    reconnect?: {
+        maxAttempts?: number;
+        backoffSeconds?: number[];
+    };
+    /** Десериализатор ABI-данных. Единственный вариант — 'wharfkit'. */
+    deserializer?: 'wharfkit';
+    /** Pino logger настройки. pretty=true включает pino-pretty (для разработки). */
+    logger?: {
+        level?: string;
+        pretty?: boolean;
+    };
+    /** HTTP /health endpoint. Kubernetes liveness/readiness probe. */
+    health?: {
+        enabled?: boolean;
+        port?: number;
+        lagThresholdSeconds?: number;
+    };
+    /** HTTP /metrics endpoint для Prometheus. */
+    metrics?: {
+        enabled?: boolean;
+        port?: number;
+    };
+    /** Обрабатывать только irreversible блоки (block_num <= lastIrreversible). */
+    irreversibleOnly?: boolean;
+    /** Не устанавливать SIGTERM/SIGINT обработчики. Используется в тестах. */
+    noSignalHandlers?: boolean;
+}
+/**
+ * Парсит и валидирует конфиг из уже разобранного объекта (результат parseYaml или тест).
+ * Применяет env-интерполяцию, валидацию, проверку безопасности.
+ */
+declare function parseConfig(raw: unknown): ParserOptions;
+/**
+ * Читает YAML файл по пути и возвращает валидированные ParserOptions.
+ * Основная точка входа для CLI команд и пользовательского кода.
+ * Выбрасывает ConfigValidationError/ConfigSecurityError/Error при любых проблемах.
+ */
+declare function fromConfigFile(filePath: string): ParserOptions;
+
+declare class Parser {
+    private opts;
+    private chainClient;
+    private redis;
+    private workerPool;
+    private blockProcessor;
+    private xtrimSupervisor;
+    private running;
+    private stopSignal;
+    constructor(opts: ParserOptions);
+    static fromConfigFile(filePath: string): Parser;
+    static fromConfig(raw: unknown): Parser;
+    start(): Promise<void>;
+    private eventToFields;
+    stop(): Promise<void>;
+    get isRunning(): boolean;
+    private checkRedisPersistence;
+}
+
+/**
+ * Публичные типы событий, которые производит парсер и потребляет ParserClient.
+ *
+ * Каждое событие несёт `kind`-дискриминант для type-narrowing в switch/if,
+ * а также `event_id` — детерминированный идентификатор, вычисляемый из
+ * полей события (см. events/eventId.ts). Один и тот же event_id всегда
+ * означает одно и то же событие, что позволяет идемпотентно обрабатывать
+ * повторные доставки.
+ */
+
+/** Событие вызова смарт-контракта (inline action). */
+interface ActionEvent {
+    kind: 'action';
+    /** Уникальный детерминированный ID: chain:a:block_num:blockId[0..16]:global_sequence */
+    event_id: string;
+    chain_id: string;
+    block_num: number;
+    /** ISO-8601 время блока из трассировки транзакции. */
+    block_time: string;
+    block_id: string;
+    /** Аккаунт-владелец контракта (account). */
+    account: string;
+    /** Имя действия (action name). */
+    name: string;
+    authorization: ActionAuthorization[];
+    /** Декодированные ABI-поля действия. Пустой объект если ABI недоступен. */
+    data: Record<string, unknown>;
+    /** Порядковый номер действия внутри транзакции (1-based). */
+    action_ordinal: number;
+    /** Глобальная уникальная последовательность — монотонный счётчик действий в цепи. */
+    global_sequence: bigint;
+    /** Квитанция об исполнении; null если нет трассировки. */
+    receipt: ActionReceipt | null;
+}
+/** Изменение строки в пользовательской таблице смарт-контракта (contract_row delta). */
+interface DeltaEvent {
+    kind: 'delta';
+    /** Уникальный ID: chain:d:block_num:blockId[0..16]:code:scope:table:primary_key */
+    event_id: string;
+    chain_id: string;
+    block_num: number;
+    block_time: string;
+    block_id: string;
+    /** Аккаунт контракта-владельца таблицы. */
+    code: string;
+    /** Скоуп: обычно аккаунт, с которым связана строка. */
+    scope: string;
+    table: string;
+    /** Первичный ключ строки (строковое представление). */
+    primary_key: string;
+    /** Декодированные ABI-поля строки. */
+    value: Record<string, unknown>;
+    /** true — строка создана/обновлена; false — удалена. */
+    present: boolean;
+}
+/**
+ * Изменение нативной (системной) строки SHiP-дельты — permission, account,
+ * resource_limits и другие типы из ship-reader/native-tables.
+ *
+ * Параметр T позволяет сузить тип данных: NativeDeltaEvent<NativePermissionRow>.
+ */
+interface NativeDeltaEvent<T = Record<string, unknown>> {
+    kind: 'native-delta';
+    /** Уникальный ID: chain:n:block_num:blockId[0..16]:table:lookup_key */
+    event_id: string;
+    chain_id: string;
+    block_num: number;
+    block_time: string;
+    block_id: string;
+    /** Имя нативной таблицы, например 'permission', 'account', 'resource_limits'. */
+    table: string;
+    /** Натуральный первичный ключ строки (зависит от типа таблицы). */
+    lookup_key: string;
+    /** Десериализованные данные строки. */
+    data: T;
+    /** true — строка создана/обновлена; false — удалена. */
+    present: boolean;
+}
+/**
+ * Сигнал о микрофорке блокчейна.
+ *
+ * Публикуется первым в пакете событий того блока, где обнаружен форк.
+ * Потребитель должен откатить своё состояние для всех блоков > forked_from_block.
+ * Подробнее: docs/event-id-semantics.md.
+ */
+interface ForkEvent {
+    kind: 'fork';
+    /** Уникальный ID: chain:f:forked_from_block:newHeadBlockId[0..16] */
+    event_id: string;
+    chain_id: string;
+    /** Последний безопасный блок (до него откатываться не нужно). */
+    forked_from_block: number;
+    /** Block ID нового head — отличается от предыдущей версии того же номера. */
+    new_head_block_id: string;
+}
+/** Дискриминантное объединение всех типов событий парсера. */
+type ParserEvent = ActionEvent | DeltaEvent | NativeDeltaEvent | ForkEvent;
+
+/**
+ * Фильтры подписки — декларативный DSL для выбора нужных событий.
+ *
+ * Потребитель задаёт массив SubscriptionFilter при создании ParserClient.
+ * matchFilters(event, filters) возвращает true если событие удовлетворяет
+ * хотя бы одному фильтру (OR-семантика).
+ *
+ * Значения полей фильтра:
+ *   undefined / '*' — совпадает с любым значением (wildcard).
+ *   строка — точное совпадение.
+ *
+ * Примеры фильтров:
+ *   { kind: 'action', account: 'eosio.token', name: 'transfer' }
+ *   { kind: 'delta', code: 'eosio', table: 'global' }
+ *   { kind: 'native-delta', table: 'permission' }
+ *   { kind: 'fork' }
+ */
+
+/** Фильтр по транзакционным действиям. */
+interface ActionFilter<T extends Record<string, unknown> = Record<string, unknown>> {
+    kind: 'action';
+    /** Аккаунт контракта. undefined = любой. */
+    account?: string;
+    /** Имя действия. undefined = любое. */
+    name?: string;
+    /** Частичное совпадение по полям data. */
+    data?: Partial<T>;
+}
+/** Фильтр по изменениям строк пользовательских таблиц. */
+interface DeltaFilter {
+    kind: 'delta';
+    /** Аккаунт контракта. undefined = любой. */
+    code?: string;
+    /** Имя таблицы. undefined = любая. */
+    table?: string;
+    /** Скоуп. undefined = любой. */
+    scope?: string;
+}
+/** Фильтр по изменениям нативных системных таблиц. */
+interface NativeDeltaFilter {
+    kind: 'native-delta';
+    /** Тип нативной таблицы (permission, account, …). undefined = любая. */
+    table?: NativeTableName;
+}
+/** Фильтр по событиям форка (подписывается на все форки без уточнений). */
+interface ForkFilter {
+    kind: 'fork';
+}
+type SubscriptionFilter<T extends Record<string, unknown> = Record<string, unknown>> = ActionFilter<T> | DeltaFilter | NativeDeltaFilter | ForkFilter;
+/**
+ * Проверяет событие против набора фильтров (OR-семантика).
+ * @returns true если filters пустой/undefined (нет ограничений) или хотя бы один фильтр совпал.
+ */
+declare function matchFilters(event: ParserEvent, filters: SubscriptionFilter[] | undefined): boolean;
+
+/**
+ * Клиент-потребитель событий парсера.
+ *
+ * ParserClient — главная точка входа для прикладного кода, который хочет
+ * получать события из блокчейна без прямого доступа к Redis или SHiP.
+ *
+ * Что делает:
+ *   1. Регистрирует подписку (метаданные) в Redis Hash (parser:subs).
+ *   2. Захватывает distributed lock (single-active-consumer) через SubscriptionLock.
+ *   3. Читает события из Redis Stream через RedisConsumer (XREADGROUP).
+ *   4. Применяет фильтры (matchFilters) — пропускает нерелевантные события.
+ *   5. Доставляет событие через yield.
+ *   6. После успешной обработки: XACK + clearFailure.
+ *   7. При ошибке в обработчике: инкрементирует счётчик (FailureTracker).
+ *      При достижении порога (3 ошибки) — переводит в dead-letter stream.
+ *
+ * Использование:
+ *   const client = new ParserClient({ … })
+ *   for await (const event of client.stream()) {
+ *     await myHandler(event)
+ *   }
+ */
+
+interface ParserClientOptions {
+    /** Уникальный идентификатор подписки (имя consumer group в Redis Stream). */
+    subscriptionId: string;
+    /** Список фильтров. Пустой = все события. */
+    filters?: SubscriptionFilter[];
+    /**
+     * Стартовая позиция потребления:
+     *   'last_known' — '$' (только новые события с момента регистрации)
+     *   'head-minus-1000' — приблизительно с 1000 блоков назад
+     *   number — с указанного block_num (приблизительное преобразование в stream ID)
+     */
+    startFrom?: 'last_known' | number | 'head-minus-1000';
+    redis: {
+        url: string;
+        password?: string;
+        keyPrefix?: string;
+    };
+    chain: {
+        id: string;
+    };
+    /** Таймаут ожидания lock'а в мс (для тестов). */
+    acquireLockTimeoutMs?: number;
+    /** Отключить SIGTERM/SIGINT обработчики (для тестов и встроенного использования). */
+    noSignalHandlers?: boolean;
+}
+declare class ParserClient {
+    private opts;
+    private redis;
+    private lock;
+    private consumer;
+    private failureTracker;
+    /** Уникальный ID этого экземпляра — используется как значение distributed lock'а. */
+    private instanceId;
+    private closed;
+    constructor(opts: ParserClientOptions);
+    /**
+     * Основной AsyncGenerator: инициализирует подключение и начинает yield событий.
+     *
+     * Этапы старта:
+     *   1. Подключаемся к Redis.
+     *   2. Регистрируем подписку в HSET parser:subs.
+     *   3. Пытаемся захватить lock; если занят — ждём освобождения.
+     *   4. Определяем startId для consumer group.
+     *   5. Создаём consumer group (XGROUP CREATE).
+     *   6. Читаем события в цикле, фильтруем, yield'им.
+     *
+     * Генератор завершается при вызове close().
+     */
+    stream(): AsyncGenerator<ParserEvent>;
+    /**
+     * Graceful shutdown: останавливает генератор, освобождает lock, закрывает Redis.
+     */
+    close(): Promise<void>;
+    /** Закрывает клиент и завершает процесс (для использования в SIGINT-обработчике). */
+    closeAndExit(): void;
+}
+
+/**
+ * Порт хранилища Redis — абстракция над Redis-командами.
+ *
+ * Порт (интерфейс) изолирует бизнес-логику от конкретного Redis-клиента.
+ * Единственная реализация — IoRedisStore (adapters/IoRedisStore.ts).
+ * В тестах используются vi.fn()-моки, соответствующие этому интерфейсу.
+ *
+ * Именование методов следует camelCase-версии Redis-команд:
+ *   XADD → xadd, ZRANGEBYSCORE → zrangeByScore и т.д.
+ */
+/** Одно сообщение Redis Stream, возвращаемое XRANGE / XREADGROUP. */
+interface StreamMessage {
+    /** Redis Stream entry ID в формате <milliseconds>-<sequence>. */
+    id: string;
+    /** Пары поле→значение записи. */
+    fields: Record<string, string>;
+}
+/** Информация о consumer group из XINFO GROUPS. */
+interface XGroupInfo {
+    name: string;
+    /** Число сообщений в PEL (pending entries list) — доставлено, но не подтверждено. */
+    pending: number;
+    /** ID последнего доставленного сообщения. */
+    lastDeliveredId: string;
+    /** Отставание group от head стрима (null для Redis < 7.0). */
+    lag: number | null;
+    /** Число зарегистрированных consumers в group. */
+    consumers: number;
+}
+interface RedisStore {
+    /** XADD stream * field value … → возвращает присвоенный entry ID. */
+    xadd(stream: string, fields: Record<string, string>): Promise<string>;
+    /** XTRIM stream MINID minId — удаляет записи с ID < minId. */
+    xtrim(stream: string, minId: string): Promise<number>;
+    /**
+     * XGROUP CREATE stream group startId MKSTREAM
+     * Идемпотентен: BUSYGROUP ошибка поглощается — группа уже существует.
+     */
+    xgroupCreate(stream: string, group: string, startId: string): Promise<void>;
+    /** XGROUP SETID stream group id — перемещает позицию group. */
+    xgroupSetId(stream: string, group: string, id: string): Promise<void>;
+    /** XINFO GROUPS stream → список consumer groups с метриками. */
+    xinfoGroups(stream: string): Promise<XGroupInfo[]>;
+    /**
+     * XREADGROUP GROUP group consumer COUNT count BLOCK blockMs STREAMS stream id
+     * id='>' — читать новые; id='0' — читать PEL (pending, для recovery).
+     */
+    xreadGroup(stream: string, group: string, consumer: string, count: number, blockMs: number, id: string): Promise<StreamMessage[]>;
+    /** XRANGE stream start end COUNT count — диапазон по ID в прямом порядке. */
+    xrange(stream: string, start: string, end: string, count: number): Promise<StreamMessage[]>;
+    /** XREVRANGE stream end start COUNT count — диапазон в обратном порядке. */
+    xrevrange(stream: string, end: string, start: string, count: number): Promise<StreamMessage[]>;
+    /** XLEN stream — число записей в стриме. */
+    xlen(stream: string): Promise<number>;
+    /** XDEL stream id — удаляет запись по ID. */
+    xdel(stream: string, id: string): Promise<number>;
+    /** XACK stream group id — подтверждает обработку, убирает из PEL. */
+    xack(stream: string, group: string, id: string): Promise<void>;
+    /** ZADD key score member. */
+    zadd(key: string, score: number, member: string): Promise<void>;
+    /**
+     * ZREVRANGEBYSCORE key max min LIMIT 0 1
+     * Используется для поиска «последней версии ABI на момент блока N»:
+     * max=N, min='-inf', возвращает первый (наиболее свежий) элемент.
+     */
+    zrangeByscoreRev(key: string, max: string, min: string): Promise<string[]>;
+    /** ZRANGEBYSCORE key min max LIMIT 0 ∞. */
+    zrangeByScore(key: string, min: string, max: string): Promise<string[]>;
+    /** ZCOUNT key min max. */
+    zcount(key: string, min: string, max: string): Promise<number>;
+    /** ZREMRANGEBYSCORE key min max → число удалённых элементов. */
+    zremRangeByScore(key: string, min: string, max: string): Promise<number>;
+    /** ZCARD key — мощность множества. */
+    zcard(key: string): Promise<number>;
+    /** HSET key field1 value1 field2 value2 … */
+    hset(key: string, fields: Record<string, string>): Promise<void>;
+    /** HGET key field → null если поле или ключ не существует. */
+    hget(key: string, field: string): Promise<string | null>;
+    /** HGETALL key → пустой объект если ключ не существует. */
+    hgetAll(key: string): Promise<Record<string, string>>;
+    /** HINCRBY key field increment → новое значение. */
+    hincrby(key: string, field: string, increment: number): Promise<number>;
+    /** HDEL key field. */
+    hdel(key: string, field: string): Promise<void>;
+    /**
+     * SET key value NX PX pxMs — атомарный conditional set.
+     * Возвращает true если ключ был успешно создан (не существовал).
+     * Используется для захвата distributed lock'а.
+     */
+    setNx(key: string, value: string, pxMs: number): Promise<boolean>;
+    /**
+     * Lua-скрипт: PEXPIRE key ms IF GET(key) == value.
+     * Продлевает TTL lock'а только если мы — текущий владелец.
+     * Атомарность необходима: между GET и PEXPIRE не должно быть race condition.
+     */
+    pexpire(key: string, ms: number, value: string): Promise<boolean>;
+    /**
+     * Lua-скрипт: DEL key IF GET(key) == value.
+     * Удаляет lock только если мы — его владелец.
+     * Защищает от случайного сброса чужого lock'а (если наш TTL истёк).
+     */
+    luaDel(key: string, value: string): Promise<boolean>;
+    /** EXPIRE key seconds. */
+    expire(key: string, seconds: number): Promise<void>;
+    /**
+     * SCAN-итерация по паттерну: продолжает пока cursor != '0'.
+     * Возвращает полный список ключей, соответствующих pattern.
+     * @param count — подсказка Redis сколько ключей возвращать за итерацию (не гарантия).
+     */
+    scan(pattern: string, count?: number): Promise<string[]>;
+    /** Закрыть соединение с Redis. */
+    quit(): Promise<void>;
+}
+
+/**
+ * Distributed lock для single-active-consumer паттерна.
+ *
+ * Проблема: несколько экземпляров одного consumer-а запущены одновременно
+ * (горизонтальное масштабирование, rolling deploy). Обрабатывать события
+ * должен ровно один (active), остальные — в режиме ожидания (standby).
+ *
+ * Механизм:
+ *   - Lock реализован как Redis String с TTL 10 секунд.
+ *   - Значение = instanceId (hostname:pid:uuid) — уникально для каждого процесса.
+ *   - Active-экземпляр продлевает TTL каждые 3 секунды через heartbeat.
+ *   - Standby-экземпляры опрашивают каждые 500 мс попытку захватить lock.
+ *   - Если active-экземпляр упал — его TTL истекает за ≤10 с, standby захватывает lock.
+ *
+ * Атомарные операции:
+ *   - setNx: атомарный SET NX PX — захватывает lock.
+ *   - pexpire (LUA): продлевает TTL только если мы — владелец (не перезаписывает чужой).
+ *   - luaDel (LUA): удаляет lock только если мы — владелец.
+ */
+
+type LockState = 'acquiring' | 'active' | 'standby' | 'released';
+interface SubscriptionLockOptions {
+    redis: RedisStore;
+    /** Идентификатор подписки — определяет имя Redis-ключа. */
+    subId: string;
+    /** Уникальный ID этого экземпляра (hostname:pid:uuid). */
+    instanceId: string;
+    /** Интервал heartbeat в мс. По умолчанию 3000. */
+    heartbeatIntervalMs?: number;
+    /** Таймаут ожидания lock'а в мс. По умолчанию Infinity. */
+    acquireLockTimeoutMs?: number;
+}
+declare class SubscriptionLock {
+    private redis;
+    private key;
+    readonly instanceId: string;
+    private heartbeatMs;
+    private acquireTimeoutMs;
+    private heartbeatTimer;
+    private _state;
+    constructor(opts: SubscriptionLockOptions);
+    /** Текущее состояние: acquiring → active/standby → released. */
+    get state(): LockState;
+    /**
+     * Пробует захватить lock одним атомарным SET NX PX.
+     * @returns true если захватили (state = active), false если занят (state = standby).
+     */
+    acquire(): Promise<boolean>;
+    /**
+     * Блокирует текущий процесс до тех пор пока lock не освободится и мы его захватим.
+     * Опрашивает Redis каждые STANDBY_POLL_MS мс.
+     * @throws Error если acquireLockTimeoutMs истёк.
+     */
+    waitForPromotion(): Promise<void>;
+    /** Запускает периодическое продление TTL (heartbeat). */
+    private startHeartbeat;
+    /**
+     * Один шаг heartbeat: продлеваем TTL через LUA-скрипт.
+     * Если LUA вернул false — кто-то другой захватил lock (race condition после
+     * истечения нашего TTL). Переходим в standby.
+     */
+    private renewHeartbeat;
+    /** Останавливает heartbeat-таймер (без освобождения lock'а). */
+    stopHeartbeat(): void;
+    /**
+     * Освобождает lock: останавливает heartbeat, удаляет ключ через LUA (conditional).
+     * После вызова state = 'released'.
+     */
+    release(): Promise<void>;
+}
+
+/**
+ * Низкоуровневый Redis Stream consumer (XREADGROUP).
+ *
+ * Реализует two-phase чтение:
+ *   Фаза 1 — Recovery: при старте сначала читаем PEL (pending entries list)
+ *     с id='0'. Это сообщения, которые были доставлены в предыдущей сессии
+ *     но не подтверждены (XACK). Перечитываем их чтобы не потерять.
+ *
+ *   Фаза 2 — Normal read: читаем новые сообщения с id='>'.
+ *     BLOCK blockMs: если новых нет — ждём (не-busyloop).
+ *
+ * Все consumer'ы в одной group читают один и тот же поток, но каждое сообщение
+ * доставляется ровно одному consumer'у (группа обеспечивает fan-out).
+ *
+ * Имя consumer'а фиксировано ('primary') — мы не используем конкурентное чтение
+ * внутри одной группы (это решается через single-active-consumer lock).
+ */
+
+/** Фиксированное имя consumer'а внутри group. */
+declare const CONSUMER_NAME = "primary";
+interface RedisConsumerOptions {
+    redis: RedisStore;
+    stream: string;
+    groupName: string;
+    /** Время блокировки XREADGROUP в мс. 2000 = ждём 2 с перед следующей попыткой. */
+    blockMs?: number;
+    /** Максимум сообщений за один XREADGROUP вызов. */
+    count?: number;
+}
+declare class RedisConsumer {
+    private redis;
+    private stream;
+    private groupName;
+    private blockMs;
+    private count;
+    private stopped;
+    constructor(opts: RedisConsumerOptions);
+    /**
+     * XGROUP CREATE stream groupName startId MKSTREAM
+     * Создаёт group (или игнорирует если уже существует — BUSYGROUP).
+     * startId='$' — читать только новые; startId='0' — с самого начала.
+     */
+    init(startId?: string): Promise<void>;
+    /**
+     * XGROUP SETID — переставляет позицию group (для reset-subscription).
+     * Примечание: здесь используется xgroupCreate что идемпотентно;
+     * для точного SETID нужен xgroupSetId из RedisStore.
+     */
+    setStartId(id: string): Promise<void>;
+    /**
+     * Читает PEL (pending entries) с id='0': сообщения, доставленные но не подтверждённые.
+     * Вызывается при старте для recovery после крэша.
+     */
+    recoverOwnPending(): Promise<StreamMessage[]>;
+    /**
+     * Асинхронный генератор сообщений.
+     *
+     * Порядок:
+     * 1. Сначала отдаём все pending (незавершённые из предыдущей сессии).
+     * 2. Затем в бесконечном цикле читаем новые (BLOCK 2000 мс).
+     *
+     * Цикл прерывается при вызове stop().
+     * Каждое сообщение нужно подтвердить через ack(msg.id).
+     */
+    read(): AsyncGenerator<StreamMessage>;
+    /** XACK stream groupName id — подтверждает что сообщение обработано. */
+    ack(id: string): Promise<void>;
+    /** Сигнализирует генератору прекратить чтение (graceful stop). */
+    stop(): void;
+}
+
+/**
+ * Трекер ошибок обработки событий для конкретной подписки.
+ *
+ * Логика: consumer обрабатывает событие и иногда выбрасывает исключение.
+ * Вместо немедленного перевода в dead-letter даём несколько попыток (FAILURE_THRESHOLD = 3).
+ * После FAILURE_THRESHOLD провалов событие переводится в dead-letter stream.
+ *
+ * Счётчики хранятся в Redis Hash (parser:sub:<subId>:failures) с TTL 24 ч.
+ * TTL сбрасывается при каждом новом провале — чтобы не накапливать стали счётчики.
+ *
+ * Почему Redis, а не in-memory: при рестарте consumer'а незакрытые ошибки
+ * не теряются и события всё равно попадут в dead-letter при следующей попытке.
+ */
+
+declare class FailureTracker {
+    private redis;
+    private chainId;
+    constructor(redis: RedisStore, chainId: string);
+    /**
+     * Инкрементирует счётчик ошибок для eventId и продлевает TTL хэша.
+     * @returns Новое значение счётчика (1, 2, 3, …).
+     */
+    recordFailure(subId: string, eventId: string): Promise<number>;
+    /**
+     * Возвращает текущий счётчик ошибок для eventId.
+     * 0 если счётчик не существует (событие ещё не проваливалось).
+     */
+    getFailureCount(subId: string, eventId: string): Promise<number>;
+    /**
+     * Проверяет достиг ли счётчик порога для dead-letter.
+     * Вызывается после recordFailure: if (shouldDeadLetter(count)) { … }
+     */
+    shouldDeadLetter(count: number): boolean;
+    /**
+     * Записывает событие в dead-letter stream с метаданными об ошибке.
+     * Dead-letter stream: ce:parser:<chainId>:dead:<subId>
+     * Поля записи: data (оригинальный payload), failureCount, lastError, subId.
+     */
+    routeToDeadLetter(subId: string, eventId: string, 
+    /** Оригинальные fields из StreamMessage (включая поле 'data'). */
+    payload: Record<string, string>, lastError: string): Promise<void>;
+    /**
+     * Сбрасывает счётчик ошибок для eventId после успешной обработки.
+     * Вызывается после успешного yield события в ParserClient.
+     */
+    clearFailure(subId: string, eventId: string): Promise<void>;
+}
+
+/**
+ * Пул worker-потоков для CPU-интенсивной ABI-десериализации.
+ *
+ * Использует Piscina — высокопроизводительный worker pool для Node.js.
+ * Каждый worker держит собственный in-memory ABI-кэш, поэтому повторные
+ * задания с одним и тем же abiJson не перепарсивают его.
+ */
+interface DeserializeTask {
+    /** Сырые байты action data или table row для декодирования. */
+    rawBinary: Uint8Array;
+    /** JSON-представление ABI нужного контракта. */
+    abiJson: string;
+    contract: string;
+    /** Имя типа в ABI для декодирования. */
+    typeName: string;
+    kind: 'action' | 'delta';
+}
+declare class WorkerPool {
+    private pool;
+    /**
+     * @param maxThreads — максимум параллельных worker-потоков.
+     *   Оптимум зависит от числа CPU и IO-нагрузки. Дефолт 2 подходит
+     *   для большинства серверов; 4+ потока ускоряют плотные блоки (много actions).
+     */
+    constructor(maxThreads?: number);
+    /**
+     * Запускает десериализацию в одном из свободных worker-потоков.
+     * Блокирует промис пока worker не вернёт результат.
+     */
+    run(task: DeserializeTask): Promise<Record<string, unknown>>;
+    /**
+     * Доля занятых потоков от общего числа (0..1).
+     * Полезно для метрики parser_worker_pool_queue_depth.
+     */
+    get utilization(): number;
+    /** Завершает все worker-потоки (вызывается при остановке парсера). */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Порт блокчейн-клиента — абстракция над SHiP WebSocket-соединением.
+ *
+ * Позволяет подменять реализацию в тестах (mock) не затрагивая
+ * бизнес-логику BlockProcessor и Parser.
+ * Единственная реализация — ShipReaderAdapter (adapters/ShipReaderAdapter.ts).
+ */
+
+interface ChainClient {
+    /**
+     * Устанавливает WebSocket-соединение с SHiP-нодой и выполняет рукопожатие.
+     * @returns chainId — hex-идентификатор блокчейна из genesis.json.
+     */
+    connect(): Promise<{
+        chainId: string;
+    }>;
+    /**
+     * Возвращает AsyncIterable блоков начиная с позиции opts.startBlock.
+     * Метод блокирующий по своей природе — итерация останавливается только
+     * при закрытии соединения или брейке цикла.
+     */
+    streamBlocks(opts: GetBlocksOptions): AsyncIterable<ShipBlock>;
+    /**
+     * Отправляет ACK-подтверждение SHiP-ноде: «я обработал n блоков, присылай следующие».
+     * Без ACK нода прекратит отправку новых блоков (flow control).
+     */
+    ack(n: number): void;
+    /** Закрывает WebSocket-соединение. */
+    close(): Promise<void>;
+    /** Запрашивает chain_id и last_irreversible через chain RPC (get_info). */
+    getChainInfo(): Promise<ChainInfo>;
+    /**
+     * Загружает сырые байты ABI контракта через chain RPC (get_raw_abi).
+     * Вызывается только при первом появлении контракта (bootstrap), дальше
+     * ABI берётся из Redis-кэша (AbiStore).
+     */
+    getRawAbi(contract: string): Promise<Uint8Array>;
+    /**
+     * Десериализует нативную SHiP-дельту (permission, account и т.д.)
+     * в типизированный объект.
+     * Делегируется ship-reader'у, который знает структуру нативных таблиц.
+     */
+    deserializeNativeDelta(delta: ShipDelta): NativeDeltaEvent$1;
+}
+
+/**
+ * Хранилище версий ABI в Redis Sorted Set.
+ *
+ * Проблема: ABI контракта меняется в блоке eosio::setabi. Чтобы корректно
+ * декодировать действия и дельты исторических блоков, нужна версия ABI,
+ * актуальная именно на момент этого блока.
+ *
+ * Решение: каждая версия ABI хранится как member в ZSET с score=block_num.
+ * Для получения ABI на блок N делается ZREVRANGEBYSCORE key N -inf LIMIT 0 1 —
+ * это возвращает самую позднюю версию, появившуюся не позже блока N.
+ */
+
+declare class AbiStore {
+    private readonly redis;
+    constructor(redis: RedisStore);
+    /**
+     * Ищет версию ABI контракта, актуальную на момент blockNum.
+     * Использует ZREVRANGEBYSCORE: возвращает последнюю запись со score ≤ blockNum.
+     * @returns Байты ABI или null если история пуста для данного контракта.
+     */
+    getAbi(contract: string, blockNum: number): Promise<Uint8Array | null>;
+    /**
+     * Сохраняет новую версию ABI, привязывая её к blockNum.
+     * Вызывается AbiBootstrapper при первом наблюдении контракта и
+     * BlockProcessor'ом при перехвате eosio::setabi / account-дельты.
+     */
+    storeAbi(contract: string, blockNum: number, abiBytes: Uint8Array): Promise<void>;
+}
+
+/**
+ * Загрузчик первичного ABI для неизвестных контрактов.
+ *
+ * Жизненный цикл ABI:
+ * 1. Первая встреча с контрактом (observedContracts не содержит его):
+ *    → смотрим в AbiStore (Redis ZSET).
+ *    → если не найден — загружаем через chain RPC (getRawAbi) и сохраняем.
+ * 2. Все последующие встречи: просто читаем из AbiStore (Redis cache hit).
+ * 3. Runtime-обновления ABI (eosio::setabi или account-дельта) выполняются
+ *    непосредственно в BlockProcessor и обходят этот класс.
+ *
+ * observedContracts — in-memory Set для оптимизации: если контракт уже
+ * проходил через этот экземпляр, гарантированно был инициализирован в Redis.
+ */
+
+declare class AbiBootstrapper {
+    private readonly chainClient;
+    private readonly abiStore;
+    /** Контракты, ABI которых уже гарантированно записан в Redis в этом сеансе. */
+    private readonly observedContracts;
+    private readonly abiFallback;
+    constructor(chainClient: ChainClient, abiStore: AbiStore, opts?: {
+        abiFallback?: 'rpc-current' | 'fail';
+    });
+    /**
+     * Гарантирует наличие ABI для контракта в кэше перед декодированием события.
+     *
+     * Быстрый путь: контракт уже в observedContracts → сразу идём в Redis.
+     * Медленный путь: первая встреча → проверяем Redis → если пусто, скачиваем с RPC.
+     *
+     * @param contract — имя аккаунта-контракта (например 'eosio.token').
+     * @param blockNum — номер блока, для которого нужна ABI (для поиска версии).
+     * @returns Байты ABI или null если ABI недоступен и abiFallback='rpc-current'.
+     * @throws AbiNotFoundError если abiFallback='fail' и ABI не найден.
+     */
+    ensureAbi(contract: string, blockNum: number): Promise<Uint8Array | null>;
+}
+
+/**
+ * Обработчик одного блока SHiP → список ParserEvent.
+ *
+ * Архитектура:
+ *   BlockProcessor получает ShipBlock и возвращает массив событий в порядке:
+ *   [ActionEvents..., DeltaEvents..., NativeDeltaEvents...]
+ *
+ * Три фазы обработки:
+ *   1. Traces (транзакционные трассировки) → ActionEvent[]
+ *      - Для каждого trace: получить ABI → десериализовать action data в worker'е.
+ *      - Особый случай eosio::setabi: извлекаем новый ABI и сохраняем в AbiStore.
+ *
+ *   2. Deltas → DeltaEvent[] + NativeDeltaEvent[]
+ *      - account-дельта: содержит обновлённый ABI контракта → сохраняем в AbiStore.
+ *      - contract_row: строка пользовательской таблицы → DeltaEvent (ABI-декодирование).
+ *      - нативные таблицы (isNativeTableName): NativeDeltaEvent через chainClient.
+ *
+ * p-queue с concurrency=1 гарантирует последовательную обработку блоков:
+ * блок N+1 не начнёт обрабатываться пока не завершится блок N.
+ */
+
+interface BlockProcessorOptions {
+    /** Идентификатор цепи — проставляется в каждое событие. */
+    chainId: string;
+    /** Пул потоков для CPU-интенсивной ABI-десериализации. */
+    workerPool: WorkerPool;
+    /** Загрузчик/кэш ABI: обеспечивает ABI перед каждым декодированием. */
+    abiBootstrapper: AbiBootstrapper;
+    /** Прямой доступ к Redis-кэшу ABI для runtime-обновлений (setabi). */
+    abiStore: AbiStore;
+    /** Блокчейн-клиент для десериализации нативных дельт. */
+    chainClient: ChainClient;
+}
+declare class BlockProcessor {
+    /** Очередь с concurrency=1: только один блок обрабатывается одновременно. */
+    private queue;
+    private chainId;
+    private workerPool;
+    private abiBootstrapper;
+    private abiStore;
+    private chainClient;
+    constructor(opts: BlockProcessorOptions);
+    /**
+     * Ставит блок в очередь на обработку.
+     * Возвращает Promise который резолвится когда этот конкретный блок обработан.
+     * Блоки обрабатываются строго последовательно (concurrency=1).
+     */
+    process(block: ShipBlock): Promise<ParserEvent[]>;
+    private processBlock;
+    /** Число заданий, ожидающих обработки (в очереди + текущее). */
+    get pendingCount(): number;
+    /** Ждёт завершения всех задач в очереди (вызывается при graceful shutdown). */
+    onIdle(): Promise<void>;
+}
+
+/**
+ * Фоновый supervisor для периодической очистки основного стрима (XTRIM).
+ *
+ * Проблема: события XADD добавляются непрерывно, и без очистки стрим
+ * будет расти бесконечно, занимая память Redis.
+ *
+ * Стратегия MINID:
+ *   Вместо хранения фиксированного числа записей (MAXLEN), мы сохраняем все
+ *   записи, которые ещё не подтверждены (pending) хотя бы одной consumer group.
+ *   minId = min(lastDeliveredId всех групп с pending > 0).
+ *   XTRIM stream MINID minId удаляет всё с ID < minId.
+ *
+ * Это гарантирует, что ни один consumer не потеряет сообщения при trim:
+ * группа с отставанием «тормозит» trim, пока не догонит.
+ *
+ * Таймер unref'ится чтобы не мешать graceful shutdown Node.js процесса.
+ */
+
+interface XtrimSupervisorOpts {
+    redis: RedisStore;
+    /** Имя стрима для очистки (обычно ce:parser:<chainId>:events). */
+    stream: string;
+    /** Интервал между trim-циклами в мс. По умолчанию 60 000 (1 минута). */
+    intervalMs?: number;
+}
+declare class XtrimSupervisor {
+    private timer;
+    private readonly redis;
+    private readonly stream;
+    private readonly intervalMs;
+    constructor(opts: XtrimSupervisorOpts);
+    /** Запускает периодический trim. Идемпотентен — повторный вызов игнорируется. */
+    start(): void;
+    /** Останавливает trim-цикл (вызывается при graceful shutdown). */
+    stop(): void;
+    /**
+     * Один цикл очистки:
+     * 1. Получаем список consumer groups через XINFO GROUPS.
+     * 2. Фильтруем группы у которых есть pending сообщения (pending > 0).
+     * 3. Находим минимальный lastDeliveredId среди таких групп.
+     * 4. XTRIM stream MINID minId — удаляем всё старее этого ID.
+     *
+     * Если pending-групп нет — trim не делается (всё подтверждено).
+     * Если стрим не существует или XInfo бросает — тихо игнорируем (best-effort).
+     */
+    private trim;
+}
+
+/**
+ * Адаптер Redis — реализует интерфейс RedisStore через ioredis.
+ *
+ * Ioredis не имеет поля "exports" в package.json, поэтому для NodeNext
+ * resolution используется динамический import() с явным приведением типа.
+ *
+ * Два Lua-скрипта реализуют атомарные операции для distributed lock:
+ *
+ * PEXPIRE_LUA — условное продление TTL:
+ *   «Продли TTL ключа key на ms миллисекунд, но только если его текущее
+ *   значение равно value (т.е. мы — владельцы lock'а)».
+ *   Атомарность важна: без неё возможен race condition между GET и PEXPIRE.
+ *
+ * DEL_LUA — условное удаление:
+ *   «Удали ключ key, но только если его текущее значение равно value».
+ *   Защищает от случайного удаления lock'а другого процесса, если наш TTL истёк.
+ */
+
+/**
+ * Минимальный интерфейс ioredis-клиента с только нужными командами.
+ * Сигнатуры точно соответствуют тому что возвращает ioredis — без обёрток.
+ */
+interface IRedisClient {
+    connect(): Promise<void>;
+    xadd(stream: string, id: string, ...args: string[]): Promise<string | null>;
+    xtrim(stream: string, strategy: string, threshold: string): Promise<number>;
+    xgroup(action: string, stream: string, group: string, id: string, mkstream?: string): Promise<unknown>;
+    xinfo(subcommand: string, key: string): Promise<unknown>;
+    xreadgroup(group: string, groupName: string, consumerName: string, count: string, countVal: number, block: string, blockMs: number, streams: string, stream: string, id: string): Promise<Array<[string, Array<[string, string[]]>]> | null>;
+    xrange(key: string, start: string, end: string, count: string, countVal: number): Promise<Array<[string, string[]]>>;
+    xrevrange(key: string, end: string, start: string, count: string, countVal: number): Promise<Array<[string, string[]]>>;
+    xlen(key: string): Promise<number>;
+    xdel(key: string, ...ids: string[]): Promise<number>;
+    xack(stream: string, group: string, id: string): Promise<number>;
+    zadd(key: string, score: number, member: string): Promise<number>;
+    zrangebyscore(key: string, min: string, max: string, limit: string, offset: number, count: number): Promise<string[]>;
+    zrevrangebyscore(key: string, max: string, min: string, limit: string, offset: number, count: number): Promise<string[]>;
+    zcount(key: string, min: string, max: string): Promise<number>;
+    zremrangebyscore(key: string, min: string, max: string): Promise<number>;
+    zcard(key: string): Promise<number>;
+    hset(key: string, ...args: string[]): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hgetall(key: string): Promise<Record<string, string> | null>;
+    hincrby(key: string, field: string, increment: number): Promise<number>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    set(key: string, value: string, nx: string, px: string, ms: number): Promise<string | null>;
+    eval(script: string, numkeys: number, ...args: string[]): Promise<unknown>;
+    expire(key: string, seconds: number): Promise<number>;
+    scan(cursor: string, match: string, pattern: string, count: string, countVal: number): Promise<[string, string[]]>;
+    quit(): Promise<string>;
+}
+declare class IoRedisStore implements RedisStore {
+    /** Прямой доступ к ioredis-клиенту (для тестов и расширения). */
+    readonly client: IRedisClient;
+    constructor(opts: {
+        url: string;
+        password?: string;
+        keyPrefix?: string;
+    });
+    /** Явное подключение — вызывается один раз при старте Parser/ParserClient. */
+    connect(): Promise<void>;
+    /** XADD stream * field1 val1 … — возвращает присвоенный entry ID. */
+    xadd(stream: string, fields: Record<string, string>): Promise<string>;
+    /** XTRIM stream MINID minId — удаляет записи с ID < minId. */
+    xtrim(stream: string, minId: string): Promise<number>;
+    /**
+     * XGROUP CREATE stream group startId MKSTREAM
+     * MKSTREAM: создаёт стрим если не существует.
+     * BUSYGROUP: группа уже существует — это нормально, поглощаем ошибку.
+     */
+    xgroupCreate(stream: string, group: string, startId: string): Promise<void>;
+    /** XGROUP SETID stream group id — переставляет позицию group в стриме. */
+    xgroupSetId(stream: string, group: string, id: string): Promise<void>;
+    /** XINFO GROUPS stream → список consumer groups с метриками. */
+    xinfoGroups(stream: string): Promise<XGroupInfo[]>;
+    /**
+     * XREADGROUP GROUP group consumer COUNT count BLOCK blockMs STREAMS stream id
+     * id='>' — только новые сообщения.
+     * id='0' — PEL (pending): уже доставленные, но не подтверждённые (recovery).
+     */
+    xreadGroup(stream: string, group: string, consumer: string, count: number, blockMs: number, id: string): Promise<StreamMessage[]>;
+    /** XRANGE stream start end COUNT count. */
+    xrange(stream: string, start: string, end: string, count: number): Promise<StreamMessage[]>;
+    /** XREVRANGE stream end start COUNT count. */
+    xrevrange(stream: string, end: string, start: string, count: number): Promise<StreamMessage[]>;
+    /** XLEN stream. */
+    xlen(stream: string): Promise<number>;
+    /** XDEL stream id — удаляет запись по ID. */
+    xdel(stream: string, id: string): Promise<number>;
+    /** XACK stream group id — убирает из PEL. */
+    xack(stream: string, group: string, id: string): Promise<void>;
+    /** ZADD key score member. */
+    zadd(key: string, score: number, member: string): Promise<void>;
+    /**
+     * ZREVRANGEBYSCORE key max min LIMIT 0 1
+     * Возвращает максимум один элемент с score ≤ max.
+     * Используется для поиска ABI: «последняя версия не позже блока N».
+     */
+    zrangeByscoreRev(key: string, max: string, min: string): Promise<string[]>;
+    /** ZRANGEBYSCORE key min max LIMIT 0 9999999 — все элементы в диапазоне. */
+    zrangeByScore(key: string, min: string, max: string): Promise<string[]>;
+    /** ZCOUNT key min max. */
+    zcount(key: string, min: string, max: string): Promise<number>;
+    /** ZREMRANGEBYSCORE key min max → число удалённых. */
+    zremRangeByScore(key: string, min: string, max: string): Promise<number>;
+    /** ZCARD key. */
+    zcard(key: string): Promise<number>;
+    /** HSET key field1 val1 field2 val2 … */
+    hset(key: string, fields: Record<string, string>): Promise<void>;
+    /** HGET key field. */
+    hget(key: string, field: string): Promise<string | null>;
+    /** HGETALL key → пустой объект если ключ не существует (ioredis возвращает null). */
+    hgetAll(key: string): Promise<Record<string, string>>;
+    /** HINCRBY key field increment → новое значение счётчика. */
+    hincrby(key: string, field: string, increment: number): Promise<number>;
+    /** HDEL key field. */
+    hdel(key: string, field: string): Promise<void>;
+    /**
+     * SET key value NX PX pxMs
+     * NX: только если не существует. PX: TTL в миллисекундах.
+     * Используется для захвата distributed lock'а.
+     */
+    setNx(key: string, value: string, pxMs: number): Promise<boolean>;
+    /**
+     * Выполняет PEXPIRE_LUA: продлевает TTL lock'а только если мы — владелец.
+     * Возвращает true если продление прошло успешно.
+     */
+    pexpire(key: string, ms: number, value: string): Promise<boolean>;
+    /**
+     * Выполняет DEL_LUA: удаляет lock только если мы — владелец.
+     * Возвращает true если удаление прошло успешно.
+     */
+    luaDel(key: string, value: string): Promise<boolean>;
+    /** EXPIRE key seconds. */
+    expire(key: string, seconds: number): Promise<void>;
+    /**
+     * Полный SCAN по паттерну: итерирует cursor пока не вернётся '0'.
+     * @param count — подсказка Redis сколько ключей возвращать за итерацию.
+     * @returns Полный список ключей (может быть большим для широких паттернов).
+     */
+    scan(pattern: string, count?: number): Promise<string[]>;
+    /** Закрывает соединение с Redis. */
+    quit(): Promise<void>;
+}
+
+/**
+ * Адаптер SHiP-клиента — реализует порт ChainClient через ShipClient из ship-reader.
+ *
+ * Роль: изолирует бизнес-логику (BlockProcessor, Parser) от деталей
+ * WebSocket-протокола SHiP и специфики @coopenomics/coopos-ship-reader.
+ *
+ * Жизненный цикл:
+ *   1. new ShipReaderAdapter(opts) — конструируем клиент
+ *   2. connect() — WebSocket handshake, получаем chainId
+ *   3. streamBlocks(opts) — начинаем принимать блоки
+ *   4. ack(1) — после каждого блока подтверждаем получение
+ *   5. close() — завершаем соединение
+ */
+
+declare class ShipReaderAdapter implements ChainClient {
+    private 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: {
+        url: string;
+        timeoutMs?: number;
+        chainUrl?: string;
+    });
+    /**
+     * Устанавливает WebSocket-соединение и выполняет SHiP-рукопожатие.
+     * Рукопожатие возвращает chainId — hex-хэш genesis.json.
+     */
+    connect(): Promise<{
+        chainId: string;
+    }>;
+    /** Начинает асинхронный поток блоков от указанной позиции. */
+    streamBlocks(opts: GetBlocksOptions): AsyncIterable<ShipBlock>;
+    /**
+     * ACK n блоков: сигнализирует SHiP-ноде что мы готовы принять ещё.
+     * SHiP использует оконное управление потоком: без ACK нода замолчит.
+     */
+    ack(n: number): void;
+    /** Закрывает WebSocket. */
+    close(): Promise<void>;
+    /** GET /v1/chain/get_info — возвращает head block, last irreversible и т.д. */
+    getChainInfo(): Promise<ChainInfo>;
+    /** GET /v1/chain/get_raw_abi — загружает сырые байты ABI для bootstrap. */
+    getRawAbi(contract: string): Promise<Uint8Array>;
+    /**
+     * Десериализует нативную SHiP-дельту в типизированный объект.
+     * Делегируется встроенному deserializer'у ship-reader, который
+     * содержит hardcoded-схемы нативных таблиц (permission, account, …).
+     */
+    deserializeNativeDelta(delta: ShipDelta): NativeDeltaEvent$1;
+}
+
+/**
+ * Детерминированные идентификаторы событий.
+ *
+ * event_id — строка, однозначно идентифицирующая событие без обращения к базе данных.
+ * Свойства:
+ *   - Детерминированный: одни и те же входные данные → один и тот же ID.
+ *   - Fork-safe: события из параллельных форков одного блока отличаются
+ *     первыми 16 hex-символами block_id.
+ *   - Stateless: вычисляется в worker-потоке без каких-либо side effects.
+ *
+ * Форматы по типам (подробнее: docs/event-id-semantics.md):
+ *   action:       chain:a:block_num:blockId[0..16]:global_sequence
+ *   delta:        chain:d:block_num:blockId[0..16]:code:scope:table:primary_key
+ *   native-delta: chain:n:block_num:blockId[0..16]:table:lookup_key
+ *   fork:         chain:f:forked_from_block:newHeadId[0..16]
+ */
+
+type ActionWithoutId = Omit<ActionEvent, 'event_id'>;
+type DeltaWithoutId = Omit<DeltaEvent, 'event_id'>;
+type NativeDeltaWithoutId = Omit<NativeDeltaEvent, 'event_id'>;
+type ForkWithoutId = Omit<ForkEvent, 'event_id'>;
+/** Объединение всех типов событий до присвоения event_id. */
+type EventWithoutId = ActionWithoutId | DeltaWithoutId | NativeDeltaWithoutId | ForkWithoutId;
+/**
+ * Вычисляет event_id по полям события (без поля event_id).
+ *
+ * Принимает событие без event_id, чтобы исключить возможность рекурсии.
+ * Параметр blockId обрезается до 16 символов: это первые 8 байт, содержащих
+ * номер блока, что делает ID читаемым, но достаточным для уникальности в рамках форка.
+ */
+declare function computeEventId(event: EventWithoutId): string;
+
+/**
+ * Единый реестр Redis-ключей.
+ *
+ * Все ключи определены в одном месте, чтобы избежать опечаток и упростить
+ * поиск по кодовой базе. Полная документация формата — docs/redis-key-taxonomy.md.
+ *
+ * Префиксы:
+ *   ce:parser:<chainId>:  — Stream-ключи, относящиеся к конкретной цепи.
+ *   parser:               — Hash/ZSET/String ключи с глобальным скоупом.
+ */
+declare const RedisKeys: {
+    /**
+     * Главный поток событий парсера (unified event stream).
+     * Тип Redis: Stream. Тримируется XtrimSupervisor'ом.
+     * Пример: ce:parser:eos-mainnet:events
+     */
+    readonly eventsStream: (chainId: string) => string;
+    /**
+     * Dead-letter поток для конкретной подписки.
+     * Содержит сообщения, которые не смог обработать consumer после N попыток.
+     * Тип Redis: Stream.
+     * Пример: ce:parser:eos-mainnet:dead:verifier
+     */
+    readonly deadLetterStream: (chainId: string, subId: string) => string;
+    /**
+     * Поток для задания on-demand reparse (зарезервировано для будущего).
+     * Тип Redis: Stream.
+     */
+    readonly reparseStream: (chainId: string, jobId: string) => string;
+    /**
+     * История версий ABI конкретного контракта.
+     * Тип Redis: Sorted Set. Score = block_num, member = base64(rawAbiBytes).
+     * При поиске ABI для блока N используется ZREVRANGEBYSCORE … N -inf LIMIT 0 1.
+     * Пример: parser:abi:eosio.token
+     */
+    readonly abiZset: (contract: string) => string;
+    /**
+     * Контрольная точка синхронизации парсера (crash-recovery).
+     * Тип Redis: Hash. Поля: block_num, block_id, last_updated.
+     * При рестарте парсер читает отсюда позицию и продолжает с неё.
+     */
+    readonly syncHash: (chainId: string) => string;
+    /**
+     * Реестр всех зарегистрированных подписок.
+     * Тип Redis: Hash. Ключ поля = subId, значение = JSON-метаданные подписки.
+     */
+    readonly subsHash: () => string;
+    /**
+     * Счётчики ошибок per-event для конкретной подписки.
+     * Тип Redis: Hash. Ключ поля = event_id, значение = число провалов.
+     * TTL: 24 часа (обновляется при каждом новом провале).
+     * Используется FailureTracker для решения о переводе в dead-letter.
+     */
+    readonly subFailuresHash: (subId: string) => string;
+    /**
+     * Блокировка single-active-consumer для подписки.
+     * Тип Redis: String (instanceId держателя блокировки). TTL: 10 с (автопродление).
+     * Только один экземпляр consumer-а может быть active; остальные — standby.
+     */
+    readonly subLock: (subId: string) => string;
+    /**
+     * Метаданные задания reparse (зарезервировано для будущего).
+     * Тип Redis: Hash.
+     */
+    readonly reparseJobHash: (jobId: string) => string;
+};
+
+/**
+ * Доменные ошибки пакета.
+ *
+ * Каждый класс расширяет Error и устанавливает `name`, чтобы стек-трейсы
+ * содержали читаемое имя вместо просто "Error".
+ */
+/** Конфигурационный YAML не прошёл структурную валидацию. */
+declare class ConfigValidationError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Секреты обнаружены прямо в конфигурационном файле (например пароль Redis
+ * захардкожен в URL). Правильный способ — переменные окружения ${VAR}.
+ */
+declare class ConfigSecurityError extends Error {
+    constructor(message: string);
+}
+/** Метод интерфейса объявлен, но не реализован в данном адаптере. */
+declare class NotImplementedError extends Error {
+    constructor(method: string);
+}
+/**
+ * Chain ID в конфиге не совпал с реальным ID цепи, полученным из SHiP-рукопожатия.
+ * Защищает от случайного подключения к неверной ноде.
+ */
+declare class ChainIdMismatchError extends Error {
+    constructor(expected: string, actual: string);
+}
+/**
+ * ABI для указанного контракта не найден ни в Redis-кэше, ни по RPC,
+ * а конфигурация abiFallback='fail' запрещает продолжение без него.
+ */
+declare class AbiNotFoundError extends Error {
+    constructor(contract: string, blockNum: number, abiFallback: string);
+}
+
+/**
+ * Детектор микрофорков блокчейна.
+ *
+ * Алгоритм прост: SHiP нода отправляет блоки последовательно.
+ * При нормальной работе номер каждого следующего блока строго больше предыдущего.
+ * Если пришёл блок с номером ≤ последнему обработанному — произошёл форк.
+ *
+ * При обнаружении форка:
+ *   1. Создаём ForkEvent с forked_from_block = lastBlockNum.
+ *   2. Устанавливаем lastBlockNum = новый blockNum (форкнутая ветка теперь актуальна).
+ *   3. Возвращаем ForkEvent — он будет опубликован первым в пакете событий блока.
+ *
+ * Потребители должны откатить своё состояние для всех блоков > forked_from_block.
+ * Паттерн отката: docs/disaster-recovery.md → Scenario 4.
+ */
+
+declare class ForkDetector {
+    /** -1 означает «ещё не видели ни одного блока». */
+    private lastBlockNum;
+    private chainId;
+    constructor(chainId: string);
+    /**
+     * Проверяет, является ли входящий блок форком.
+     * Должен вызываться один раз перед обработкой каждого блока.
+     *
+     * @returns ForkEvent если обнаружен форк, null при нормальной последовательности.
+     */
+    check(blockNum: number, blockId: string): ForkEvent | null;
+    /**
+     * Сбрасывает историю (вызывается при переподключении к SHiP-ноде,
+     * чтобы не ложно детектировать форк при старте с произвольного блока).
+     */
+    reset(): void;
+}
+
+/**
+ * Supervisor для автоматического переподключения с экспоненциальным backoff.
+ *
+ * Оборачивает произвольную async-функцию (например подключение к SHiP-ноде)
+ * и повторяет её при ошибке с нарастающими паузами между попытками.
+ *
+ * Стратегия backoff: берём backoffSeconds[attempt-1], зажимая индекс
+ * по длине массива (последнее значение используется для всех поздних попыток).
+ * По умолчанию: [1, 2, 5, 15, 60] секунд.
+ *
+ * Если число попыток достигает maxAttempts — вызывается onGiveUp, который
+ * по умолчанию пишет в stderr и вызывает process.exit(1).
+ * В тестах onGiveUp можно заменить на throw чтобы не завершать процесс.
+ */
+interface ReconnectSupervisorOptions {
+    /** Максимальное число попыток до вызова onGiveUp. По умолчанию 10. */
+    maxAttempts?: number;
+    /** Паузы между попытками в секундах. Последний элемент используется для всех поздних попыток. */
+    backoffSeconds?: number[];
+    /** Вызывается перед каждым повтором с номером попытки и паузой в мс. */
+    onAttempt?: (attempt: number, delayMs: number) => void;
+    /** Вызывается при исчерпании всех попыток. По умолчанию пишет в stderr и process.exit(1). */
+    onGiveUp?: (attempts: number) => void;
+}
+declare class ReconnectSupervisor {
+    private maxAttempts;
+    private backoffSeconds;
+    private onAttempt;
+    private onGiveUp;
+    constructor(opts?: ReconnectSupervisorOptions);
+    /**
+     * Запускает 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.
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Фабрика структурированного логгера на базе Pino.
+ *
+ * Возможности:
+ *   - JSON-формат (по умолчанию) — удобен для Loki, CloudWatch, ELK.
+ *   - pino-pretty — красивый вывод при NODE_ENV=development или pretty=true.
+ *   - Redaction: поля password/token/secret/authorization заменяются '[REDACTED]'.
+ *   - Корреляционное поле chain_id: все логи одного парсера помечены chain_id.
+ *
+ * Использование:
+ *   const log = createLogger({ level: 'debug', chain_id: 'eos-mainnet' })
+ *   log.info({ block_num: 400_000_000 }, 'Block processed')
+ *
+ *   Дочерний логгер (наследует уровень и base):
+ *   const childLog = log.child({ component: 'BlockProcessor' })
+ */
+
+type Logger = pino.Logger;
+interface LoggerOptions {
+    /** Минимальный уровень: 'trace'|'debug'|'info'|'warn'|'error'|'fatal'. По умолчанию 'info'. */
+    level?: string;
+    /** Включить pino-pretty (цветной вывод). По умолчанию true при NODE_ENV=development. */
+    pretty?: boolean;
+    /** Если задан — добавляется в base поля всех сообщений. */
+    chain_id?: string;
+}
+/**
+ * Создаёт новый логгер с указанными параметрами.
+ * Уровень можно переопределить через переменную окружения LOG_LEVEL.
+ */
+declare function createLogger(opts?: LoggerOptions): Logger;
+/** Дефолтный корневой логгер без chain_id — для быстрого старта. */
+declare const rootLogger: Logger;
+
+/**
+ * Prometheus-метрики для парсера (серверная сторона: SHiP → Redis).
+ *
+ * Все метрики регистрируются в изолированном Registry — не в default глобальном.
+ * Это важно для тестов (каждый тест создаёт свой registry) и для случаев
+ * когда парсер запускается вместе с другими Prometheus-экспортёрами в процессе.
+ *
+ * Использование: createParserMetrics() → объект с counter/gauge/histogram полями.
+ * Parser главный класс передаёт их в BlockProcessor, XtrimSupervisor и HttpServer.
+ *
+ * Метрики можно наблюдать через GET /metrics (если health.enabled + metrics.enabled).
+ */
+
+/**
+ * Интерфейс парсерских метрик.
+ * Хранится как поле Parser класса и передаётся в подкомпоненты.
+ */
+interface ParserMetrics {
+    readonly registry: Registry;
+    /** Счётчик обработанных блоков. Растёт монотонно. Используется для расчёта throughput. */
+    blocksProcessedTotal: Counter;
+    /** Текущее отставание: (head_block_time - current_block_time) в секундах.
+     *  0 = в реальном времени. Большие значения → парсер не успевает. */
+    indexingLagSeconds: Gauge;
+    /** Счётчик опубликованных событий по видам (action/delta/native-delta/fork).
+     *  Позволяет видеть объём трафика каждого типа данных. */
+    eventsPublishedTotal: Counter<'kind'>;
+    /** Счётчик попаданий в кэш ABI (worker pool нашёл ABI без запроса к Redis/Chain). */
+    abiCacheHitsTotal: Counter;
+    /** Счётчик промахов кэша ABI (пришлось читать из Redis или запрашивать Chain API). */
+    abiCacheMissesTotal: Counter;
+    /** Текущая длина Redis events stream. Растущее значение → XTRIM не справляется или отключён. */
+    streamLength: Gauge;
+    /** Счётчик удалённых записей XTRIM. Помогает оценить объём хранимых данных. */
+    xtrimmedEntriesTotal: Counter;
+    /** Гистограмма времени обработки одного блока (секунды).
+     *  Buckets: 1ms–5s. Всплески → медленный ABI декодинг или Redis перегружен. */
+    blockProcessingDuration: Histogram;
+    /** Текущая глубина очереди Piscina worker pool.
+     *  Растущая очередь → worker pool не успевает за темпом блоков. */
+    workerPoolQueueDepth: Gauge;
+    /** Счётчик ошибок обработки блоков (исключения в BlockProcessor).
+     *  В норме должен быть близок к 0. */
+    blockProcessingErrors: Counter;
+}
+/**
+ * Создаёт набор парсерских метрик в изолированном Registry.
+ *
+ * @param prefix — префикс имён метрик. По умолчанию 'parser'.
+ *   Меняется в тестах и при запуске нескольких инстансов.
+ */
+declare function createParserMetrics(prefix?: string): ParserMetrics;
+
+/**
+ * Prometheus-метрики для клиентской стороны парсера (ParserClient / RedisConsumer).
+ *
+ * Клиентские метрики отражают состояние подписок, а не самого парсера.
+ * Каждая метрика имеет label sub_id — для разделения по подпискам в Grafana.
+ *
+ * Архитектурное решение: отдельный Registry от парсерских метрик позволяет:
+ *   - Запускать клиент и парсер в одном процессе без коллизий имён.
+ *   - Тестировать клиентские метрики изолированно.
+ *   - Скрейпить метрики клиента отдельным Prometheus job (если клиент — отдельный сервис).
+ *
+ * Использование: createClientMetrics() → передаётся в ParserClient конструктор.
+ */
+
+/**
+ * Интерфейс клиентских метрик.
+ * Хранится в ParserClient и передаётся в RedisConsumer и FailureTracker.
+ */
+interface ClientMetrics {
+    readonly registry: Registry;
+    /** Счётчик ошибок в пользовательском handler по (sub_id, kind).
+     *  Растущее значение → handler падает, события могут уйти в dead-letter. */
+    handlerErrorsTotal: Counter<'sub_id' | 'kind'>;
+    /** Гистограмма времени выполнения handler по (sub_id, kind).
+     *  Медленный handler блокирует потребление новых сообщений. */
+    handlerDurationSeconds: Histogram<'sub_id' | 'kind'>;
+    /** Состояние distributed lock по (sub_id, role).
+     *  1 = активный лидер, 0 = ожидание/acquiring.
+     *  Позволяет видеть в Grafana: сколько инстансов борются за лидерство. */
+    subscriptionLockState: Gauge<'sub_id' | 'role'>;
+    /** Счётчик событий, упавших в dead-letter stream по sub_id.
+     *  Ненулевое значение требует внимания оператора (replay-dead-letter). */
+    deadLettersTotal: Counter<'sub_id'>;
+    /** Счётчик прочитанных сообщений из стрима по sub_id (XREADGROUP).
+     *  Растёт при нормальной работе — отражает throughput потребления. */
+    messagesConsumedTotal: Counter<'sub_id'>;
+    /** Счётчик подтверждённых сообщений (XACK) по sub_id.
+     *  Должен быть близок к messagesConsumedTotal. Большой разрыв → PEL копится. */
+    messageAcknowledgedTotal: Counter<'sub_id'>;
+    /** Текущий размер PEL (pending entry list) по sub_id.
+     *  Растущий PEL → сообщения читаются но не подтверждаются (handler зависает или падает). */
+    consumerPendingMessages: Gauge<'sub_id'>;
+    /** Счётчик событий прошедших через фильтр подписки по (sub_id, kind).
+     *  Позволяет оценить эффективность фильтрации: отношение к messagesConsumedTotal. */
+    filterMatchesTotal: Counter<'sub_id' | 'kind'>;
+}
+/**
+ * Создаёт набор клиентских метрик в изолированном Registry.
+ *
+ * @param prefix — префикс имён метрик. По умолчанию 'parser_client'.
+ */
+declare function createClientMetrics(prefix?: string): ClientMetrics;
+
+/**
+ * Минималистичный HTTP-сервер для операционной наблюдаемости.
+ *
+ * Эндпоинты:
+ *   GET /health  → JSON { status, indexingLagSeconds, lagThresholdSeconds }
+ *                  200 OK если lag ≤ lagThresholdSeconds, 503 Service Unavailable иначе.
+ *                  Полезно для Kubernetes liveness/readiness probe.
+ *
+ *   GET /metrics → Prometheus text format (Content-Type: text/plain; version=0.0.4).
+ *                  Использует переданный metricsRegistry — обычно парсерские метрики.
+ *
+ * getLag — callback который возвращает текущее отставание в секундах.
+ * Вызывающий код (Parser) обновляет это значение после обработки каждого блока.
+ *
+ * Использование:
+ *   const server = new HttpServer({ port: 9090, getLag: () => lagGauge.value, metricsRegistry: reg })
+ *   await server.start()
+ *   // при shutdown:
+ *   await server.stop()
+ */
+
+/** Тело ответа /health. */
+interface HealthStatus {
+    status: 'ok' | 'degraded';
+    /** Текущее отставание в секундах на момент запроса. */
+    indexingLagSeconds: number;
+    /** Порог, выше которого статус становится 'degraded'. */
+    lagThresholdSeconds: number;
+}
+interface HttpServerOptions {
+    /** Порт HTTP-сервера. По умолчанию 9090. */
+    port?: number;
+    /** Порог lag в секундах для статуса degraded. По умолчанию 60. */
+    lagThresholdSeconds?: number;
+    /** Функция возвращающая актуальное значение отставания. */
+    getLag: () => number;
+    /** Реестр Prometheus-метрик для /metrics эндпоинта. */
+    metricsRegistry: Registry;
+}
+declare class HttpServer {
+    private server;
+    private port;
+    private lagThresholdSeconds;
+    private getLag;
+    private metricsRegistry;
+    constructor(opts: HttpServerOptions);
+    /** Запускает HTTP-сервер, разрешает Promise после успешного bind. */
+    start(): Promise<void>;
+    /**
+     * Останавливает сервер и ждёт закрытия всех соединений.
+     * Вызывается при graceful shutdown парсера.
+     */
+    stop(): Promise<void>;
+    /** Диспетчеризация HTTP-запросов по URL. */
+    private handle;
+}
+
+export { AbiBootstrapper, AbiNotFoundError, AbiStore, type ActionEvent, type ActionFilter, BlockProcessor, CONSUMER_NAME, type ChainClient, ChainIdMismatchError, type ClientMetrics, ConfigSecurityError, ConfigValidationError, type DeltaEvent, type DeltaFilter, FailureTracker, ForkDetector, type ForkEvent, type ForkFilter, type HealthStatus, HttpServer, type HttpServerOptions, IoRedisStore, type LockState, type Logger, type LoggerOptions, type NativeDeltaEvent, type NativeDeltaFilter, NotImplementedError, Parser, ParserClient, type ParserClientOptions, type ParserEvent, type ParserMetrics, type ParserOptions, ReconnectSupervisor, type ReconnectSupervisorOptions, RedisConsumer, RedisKeys, type RedisStore, ShipReaderAdapter, type StreamMessage, type SubscriptionFilter, SubscriptionLock, type SubscriptionLockOptions, WorkerPool, type XGroupInfo, XtrimSupervisor, computeEventId, createClientMetrics, createLogger, createParserMetrics, fromConfigFile, matchFilters, parseConfig, rootLogger };