feat(integration): wrappers, adapters, bench, tests, docs

.github/workflows/ci.yml

@@ -50,7 +50,7 @@ jobs:
         run: |
           ctest --test-dir build-${{ matrix.name }} \
             --output-on-failure \
-            -R 'kryzhovnik|adapters_smoke|merkletree_test'
+            -R 'test_kryzhovnik|test_kryzhovnik_wrapper|test_kryzhovnik_api|test_merkletree|test_adapters_smoke|test_adapters_batch'
 
       - name: Benchmark smoke (${{ matrix.name }})
         run: |
@@ -59,6 +59,7 @@ jobs:
             --params ${{ matrix.hypericum_paramset }} \
             --batch-size 1 \
             --iters 1 \
+            --warmup 1 \
             --verify 1 \
             --out-csv /tmp/h_${{ matrix.name }}.csv \
             --out-json /tmp/h_${{ matrix.name }}.json
@@ -68,6 +69,7 @@ jobs:
             --params default \
             --batch-size 1 \
             --iters 1 \
+            --warmup 1 \
             --verify 1 \
             --out-csv /tmp/s_${{ matrix.name }}.csv \
             --out-json /tmp/s_${{ matrix.name }}.json
@@ -77,6 +79,7 @@ jobs:
             --params ${{ matrix.kryzhovnik_paramset }} \
             --batch-size 1 \
             --iters 1 \
+            --warmup 1 \
             --verify 1 \
             --out-csv /tmp/k_${{ matrix.name }}.csv \
             --out-json /tmp/k_${{ matrix.name }}.json

.gitmodules

@@ -1,12 +1,17 @@
-[submodule "third_party/shipovnik"]
-	path = third_party/shipovnik
-	url = https://github.com/QAPP-tech/shipovnik_tc26.git
 [submodule "third_party/hypericum"]
 	path = third_party/hypericum
-	url = https://github.com/QAPP-tech/hypericum_tc26.git
+	url = https://github.com/cherninkiy/hypericum-wrapper-tc26
+	branch = main
+
+[submodule "third_party/shipovnik"]
+	path = third_party/shipovnik
+	url = https://github.com/cherninkiy/shipovnik-wrapper-tc26
+	branch = main
+
 [submodule "third_party/kryzhovnik"]
 	path = third_party/kryzhovnik
-	url = https://github.com/cherninkiy/kryzhovnik-wrapper-tc26.git
+	url = https://github.com/cherninkiy/kryzhovnik-wrapper-tc26
+	branch = main
 [submodule "third_party/iaik_merkle_tree"]
 	path = third_party/iaik_merkle_tree
 	url = https://github.com/IAIK/merkle-tree.git

README.md

@@ -12,41 +12,56 @@
 
 This project demonstrates **batch signing** (Merkle tree based) for three Russian post-quantum signature schemes:
 
-- **Shipovnik** (based on Stern protocol)
-- **Hypericum** (stateless, based on SPHINCS+, uses **Streebog** hash function from its own implementation)
-- **Kryzhovnik** (lattice-based, similar to Dilithium)
+- [Shipovnik](https://github.com/QAPP-tech/shipovnik_tc26) (based on Stern protocol)
+- [Hypericum](https://github.com/QAPP-tech/hypericum_tc26) (stateless, based on SPHINCS+, uses **Streebog** hash function from its own implementation)
+- [Kryzhovnik](https://github.com/ElenaKirshanova/pqc_LWR_signature) (lattice-based, similar to Dilithium)
 
 The goal is to measure the speedup of signing a batch of messages with a single root signature + proofs, compared to sequential signing. The results will help to assess the feasibility of batch signing in high-load PKI systems.
 
 **This is an open-source PoC for portfolio and partnership purposes. The code is released under MIT license.**
 
 ## Features
 
-- Generic Merkle tree implementation (wrapper around [IAIK/merkle-tree](https://github.com/IAIK/merkle-tree))
-- Hash abstraction layer (supports **Streebog** via Hypericum implementation, SHA-256 for fallback/testing)
-- Signature abstraction layer for:
-  - Russian PQC: [Shipovnik](https://github.com/QAPP-tech/shipovnik_tc26), [Hypericum](https://github.com/QAPP-tech/hypericum_tc26), [Kryzhovnik](https://github.com/ElenaKirshanova/pqc_LWR_signature)
-  - (planned) ML-DSA (FIPS 204) via liboqs
-- Batch signing and verification API
-- Microbenchmarks: sequential vs batch signing, verification overhead
-- Results exported as CSV + plots
+- (planned) Generic Merkle tree implementation (wrapper around [IAIK/merkle-tree](https://github.com/IAIK/merkle-tree))
+- (planned) Hash abstraction layer (supports **Streebog** via Hypericum implementation, SHA-256 for fallback/testing)
+- Signature abstraction layer for Russian PQC:
+  - [Shipovnik](https://github.com/QAPP-tech/shipovnik_tc26)
+  - [Hypericum](https://github.com/QAPP-tech/hypericum_tc26)
+  - [Kryzhovnik](https://github.com/ElenaKirshanova/pqc_LWR_signature)
+- Sequential benchmark (`bench_seq`) with configurable paramsets, verification pass, and warmup iterations
+- Test suite with unified `test_*` naming in CTest
 
-The original Kryzhovnik implementation is documented above. In this repository, the `third_party/kryzhovnik` submodule is pinned to a compatibility fork used for integration with Hypericum and Shipovnik.
+## Original Repos and Forks
+
+Algorithm links in this README always point to original repositories:
+
+- Shipovnik (original): https://github.com/QAPP-tech/shipovnik_tc26
+- Hypericum (original): https://github.com/QAPP-tech/hypericum_tc26
+- Kryzhovnik (original): https://github.com/ElenaKirshanova/pqc_LWR_signature
+
+This project currently integrates wrapper/compatibility forks as submodules:
+
+- https://github.com/cherninkiy/shipovnik-wrapper-tc26
+- https://github.com/cherninkiy/hypericum-wrapper-tc26
+- https://github.com/cherninkiy/kryzhovnik-wrapper-tc26
+
+Why forks are used:
+
+- To add integration-oriented APIs required by this project (detached and status-return wrappers)
+- To keep adapter contracts consistent across all three algorithms
+- To preserve reproducible pinned revisions for CI and local builds
 
 ## Repository Structure
 
 ```
 batch-pqc/
 ├── third_party/            # git submodules
-│   ├── shipovnik/          → https://github.com/QAPP-tech/shipovnik_tc26
-│   ├── hypericum/          → https://github.com/QAPP-tech/hypericum_tc26
+│   ├── shipovnik/          → https://github.com/cherninkiy/shipovnik-wrapper-tc26
+│   ├── hypericum/          → https://github.com/cherninkiy/hypericum-wrapper-tc26
 │   ├── kryzhovnik/         → https://github.com/cherninkiy/kryzhovnik-wrapper-tc26
 │   └── iaik_merkle_tree/   → https://github.com/IAIK/merkle-tree
 ├── src/
-│   ├── hash/               # hash provider (uses Streebog from hypericum, SHA-256 fallback)
 │   ├── signature/          # signature provider adapters
-│   ├── merkle/             # Merkle wrapper over IAIK
-│   ├── batch/              # batch signing logic
 │   └── utils/              # timers, message generators
 ├── bench/                  # benchmarking executables
 ├── tests/                  # unit tests (CTest)
@@ -80,8 +95,8 @@ git submodule update --init --recursive
 # Run tests
 ./scripts/third_party.sh tests
 
-# Run benchmarks (sequential vs batch)
-./build/bench/bench_batch --algo hypericum --batch-size 16 --iterations 100
+# Run benchmark (sequential signing)
+./build/bench/bench_seq --algo hypericum --batch-size 16 --iters 100 --verify 1
 ```
 
 ### Paramset Selection
@@ -123,12 +138,13 @@ After running benchmarks, the `results/` directory will contain:
 
 ## Current Status (MVP)
 
-- [ ] Repository structure with submodules
-- [ ] Hash abstraction + Streebog integration (from hypericum)
-- [ ] Merkle tree wrapper (uses IAIK tree)
-- [ ] Batch signer/verifier with null signature (test mode)
-- [ ] Adapters for real PQC algorithms (in progress: Hypericum first)
-- [ ] Full benchmark suite with results
+- [x] Repository structure with submodules
+- [x] Adapters for Shipovnik / Hypericum / Kryzhovnik with unified `bb_status`
+- [x] Detached/status-return integration APIs wired through wrapper submodules
+- [x] Sequential benchmark `bench_seq` with warmup and corrected signature-size metric
+- [x] Test coverage: `test_adapters_smoke`, `test_adapters_batch`, `test_kryzhovnik*`, `test_merkletree`
+- [ ] Merkle-based batch signer/verifier implementation
+- [ ] Sequential vs real batch signing benchmark comparison
 - [ ] Final report (PDF)
 
 **MVP is being developed in `dev` branch. After completion, a Pull Request to `main` will be opened for review.**

README_ru.md

@@ -14,9 +14,9 @@
 
 Этот проект демонстрирует **пакетную подпись** (на основе дерева Меркла) для трёх российских пост-квантовых схем подписи:
 
-- **Шиповник** (на основе протокола Штерна)
-- **Гиперикум** (stateless, на основе SPHINCS+, использует хеш-функцию **Стрибог** из своей реализации)
-- **Крыжовник** (на основе решёток, аналог Dilithium)
+- [Шиповник](https://github.com/QAPP-tech/shipovnik_tc26) (на основе протокола Штерна)
+- [Гиперикум](https://github.com/QAPP-tech/hypericum_tc26) (stateless, на основе SPHINCS+, использует хеш-функцию **Стрибог** из своей реализации)
+- [Крыжовник](https://github.com/ElenaKirshanova/pqc_LWR_signature) (на основе решёток, аналог Dilithium)
 
 Цель — измерить ускорение при подписи пакета сообщений с помощью одной подписи корня дерева + доказательств по сравнению с последовательной подписью. Результаты помогут оценить применимость пакетной подписи в высоконагруженных PKI-системах.
 
@@ -25,32 +25,47 @@
 ## Возможности
 
 
-- Реализация дерева Меркла (обёртка над [IAIK/merkle-tree](https://github.com/IAIK/merkle-tree))
-- Слой абстракции хеш-функций (поддерживает **Стрибог** через реализацию Hypericum, SHA-256 для тестов)
-- Слой абстракции подписей:
-  - Российские PQC: [Шиповник](https://github.com/QAPP-tech/shipovnik_tc26), [Гиперикум](https://github.com/QAPP-tech/hypericum_tc26), [Крыжовник](https://github.com/ElenaKirshanova/pqc_LWR_signature)
-  - (планируется) ML-DSA (FIPS 204) через liboqs
-- API для пакетной подписи и верификации
-- Микробенчмарки: последовательная vs пакетная подпись, накладные расходы на верификацию
-- Экспорт результатов в CSV и графики
+- (планируется) Реализация дерева Меркла (обёртка над [IAIK/merkle-tree](https://github.com/IAIK/merkle-tree))
+- (планируется) Слой абстракции хеш-функций (поддерживает **Стрибог** через реализацию Hypericum, SHA-256 для тестов)
+- Слой абстракции подписей для российских PQC:
+  - [Шиповник](https://github.com/QAPP-tech/shipovnik_tc26)
+  - [Гиперикум](https://github.com/QAPP-tech/hypericum_tc26)
+  - [Крыжовник](https://github.com/ElenaKirshanova/pqc_LWR_signature)
+- Последовательный бенчмарк (`bench_seq`) с параметрами paramset, verify-проходом и прогревочными итерациями
+- Набор тестов с унифицированными именами `test_*` в CTest
 
-Выше указана ссылка на оригинальную реализацию Крыжовника. В этом репозитории сабмодуль `third_party/kryzhovnik` зафиксирован на форке совместимости, который используется для интеграции с Hypericum и Shipovnik.
+## Оригинальные репозитории и форки
+
+Ссылки на алгоритмы в этом README всегда ведут на оригинальные репозитории:
+
+- Шиповник (оригинал): https://github.com/QAPP-tech/shipovnik_tc26
+- Гиперикум (оригинал): https://github.com/QAPP-tech/hypericum_tc26
+- Крыжовник (оригинал): https://github.com/ElenaKirshanova/pqc_LWR_signature
+
+В проекте как сабмодули используются интеграционные/совместимые форки:
+
+- https://github.com/cherninkiy/shipovnik-wrapper-tc26
+- https://github.com/cherninkiy/hypericum-wrapper-tc26
+- https://github.com/cherninkiy/kryzhovnik-wrapper-tc26
+
+Зачем используются форки:
+
+- Для добавления интеграционных API, необходимых проекту (detached и status-return обёртки)
+- Для унификации контрактов адаптеров между тремя алгоритмами
+- Для воспроизводимых зафиксированных ревизий в CI и локальной сборке
 
 ## Структура репозитория
 
 ```
 batch-pqc/
 
 ├── third_party/            # git submodules
-│   ├── shipovnik/          → https://github.com/QAPP-tech/shipovnik_tc26
-│   ├── hypericum/          → https://github.com/QAPP-tech/hypericum_tc26
+│   ├── shipovnik/          → https://github.com/cherninkiy/shipovnik-wrapper-tc26
+│   ├── hypericum/          → https://github.com/cherninkiy/hypericum-wrapper-tc26
 │   ├── kryzhovnik/         → https://github.com/cherninkiy/kryzhovnik-wrapper-tc26
 │   └── iaik_merkle_tree/   → https://github.com/IAIK/merkle-tree
 ├── src/
-│   ├── hash/               # провайдер хешей (Стрибог из hypericum, SHA-256 как запасной)
 │   ├── signature/          # адаптеры для алгоритмов подписи
-│   ├── merkle/             # обёртка Merkle над IAIK
-│   ├── batch/              # логика пакетной подписи
 │   └── utils/              # таймеры, генераторы сообщений
 ├── bench/                  # исполняемые файлы бенчмарков
 ├── tests/                  # модульные тесты (CTest)
@@ -85,8 +100,8 @@ git submodule update --init --recursive
 # Запуск тестов
 ./scripts/third_party.sh tests
 
-# Запуск бенчмарков (последовательная vs пакетная)
-./build/bench/bench_batch --algo hypericum --batch-size 16 --iterations 100
+# Запуск бенчмарка (последовательная подпись)
+./build/bench/bench_seq --algo hypericum --batch-size 16 --iters 100 --verify 1
 ```
 
 ### Выбор paramset
@@ -128,12 +143,13 @@ cmake --build build --parallel
 
 ## Текущий статус (MVP)
 
-- [ ] Структура репозитория с субмодулями
-- [ ] Абстракция хешей + интеграция Стрибога (из hypericum)
-- [ ] Обёртка Merkle дерева (использует IAIK)
-- [ ] Пакетная подпись/верификация с нулевой подписью (тестовый режим)
-- [ ] Адаптеры для реальных PQC-алгоритмов (в процессе: сначала Гиперикум)
-- [ ] Полный набор бенчмарков с результатами
+- [x] Структура репозитория с субмодулями
+- [x] Адаптеры для Шиповника / Гиперикума / Крыжовника с единым `bb_status`
+- [x] Подключены detached/status-return API через wrapper-сабмодули
+- [x] Последовательный бенчмарк `bench_seq` с warmup и исправленной метрикой размера подписей
+- [x] Покрытие тестами: `test_adapters_smoke`, `test_adapters_batch`, `test_kryzhovnik*`, `test_merkletree`
+- [ ] Реализация пакетной подписи/верификации на основе дерева Меркла
+- [ ] Сравнение бенчмарков: последовательная vs реальная пакетная подпись
 - [ ] Финальный отчёт (PDF)
 
 **MVP разрабатывается в ветке `dev`. После завершения будет открыт Pull Request в `main` для ревью.**