docs: E2E test plan for BN Verification plugin

docs/test-plan/verification-tp.md

@@ -0,0 +1,31 @@
+# Verification Test Plan
+
+## Overview
+
+Verification is one of the most important functions of a BlockNode, as it is responsible for ensuring the integrity of the blockstream and that the data is correct—as reached by consensus across the network. This document outlines the test plan for the verification module, detailing both positive and negative test cases for the available implementations.
+
+## Key Considerations
+
+- **Implementation Variants:** Two implementations exist, SYNC for testing and ASYNC for production.
+
+- **ASYNC vs. SYNC:** The ASYNC implementation uses a thread pool with a `concurrent` TreeHasher for calculating the block root hash and is approximately 50% faster than the SYNC version, which uses a `naive` TreeHash.
+
+- **Naive Tree Hasher:** calculates the root hash of the merkle trees in a synchronous manner and using a simple recursive algorithm.
+
+- **Concurrent Tree Hasher:** calculates the root hash of the merkle trees in an asynchronous manner using a thread pool to parallelize the calculation as the blocks items are received and leafs are appended to the "merkle tree".
+
+- **Verification Criteria:** A block is verified if the calculated block root hash matches the signature provided in the block_proof.
+
+- **Acknowledgement Conditions:** The BlockNode sends a BlockAcknowledgement only if the block has been both verified and persisted successfully.
+
+- **Test Coverage:** End-to-end test scenarios should include both positive and negative cases for both the ASYNC and SYNC implementations.
+
+## Test Scenarios
+
+| Test Case ID |                         Test Name                          |                                                      Scenario Description                                                       |                                                                                                                                                               Expected Behaviour                                                                                                                                                               |                   Input                   |                                              Output                                               | Implemented (Y/N) |
+|--------------|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|---------------------------------------------------------------------------------------------------|-------------------|
+| 1            | Positive SYNC Verified                                     | The BlockStream Simulator streams a series of blocks with a valid BlockRootHash and signature.                                  | The BN should return a `PublishStreamResponse` with a `status` of type `EndOfStream` and a `PublishStreamResponseCode` = `STREAM_ITEMS_SUCCESS`. For each block, a corresponding singular `BlockAcknowledgement` field must be provided, containing the expected `block_number`, `block_root_hash`, and `block_already_exists` set to `false`. | A valid blockstream of multiple blocks    | Each block has its corresponding BlockAcknowledgement with `block_already_exists`=`false`         | Y                 |
+| 2            | Positive ASYNC Verified                                    | The BlockStream Simulator streams a series of blocks using the `ASYNC` implementation with a valid BlockRootHash and signature. | The BN should return a `PublishStreamResponse` with a successful `status` and, for each block, a corresponding singular `BlockAcknowledgement` field matching the block’s details. The responses should indicate successful persistence and verification for streamed all blocks.                                                              | A valid blockstream of multiple blocks    | Each block has its corresponding BlockAcknowledgement matching the respective block details       | Y                 |
+| 3            | Negative SYNC Verification Failure – Invalid BlockRootHash | The simulator streams blocks with an incorrect BlockRootHash that does not match the signed `block_proof`.                      | The BN should return a `PublishStreamResponse` with `PublishStreamResponseCode=STREAM_ITEMS_BAD_STATE_PROOF` and **no BlockAcknowledgement field** for blocks that fail verification. The error log should capture the mismatch between the calculated block root hash and the provided signature.                                             | Blocks with tampered block root hash      | No BlockAcknowledgement field; PublishStreamResponseCode=STREAM_ITEMS_BAD_STATE_PROOF             | Y                 |
+| 4            | Negative ASYNC Verification Failure – Tampered Signature   | Blocks are streamed with a valid BlockRootHash but with a modified/tampered signature in the `block_proof`.                     | The BN should return a `PublishStreamResponse` with `PublishStreamResponseCode=STREAM_ITEMS_BAD_STATE_PROOF` and **no BlockAcknowledgement field** for blocks that fail verification. The error log should clearly indicate failure due to signature mismatch, ensuring that tampered blocks are not verified or persisted.                    | Blocks with altered signatures            | No BlockAcknowledgement field; PublishStreamResponseCode=STREAM_ITEMS_BAD_STATE_PROOF             | Y                 |
+| 5            | Duplicate Block Handling                                   | The simulator sends a block that has already been verified and persisted, simulating a duplicate entry scenario.                | The BN should return a singular `BlockAcknowledgement` field for the duplicate block that includes the expected `block_root_hash` and a flag `block_already_exists` set to `true`, ensuring that duplicate blocks are not re-verified or persisted again.                                                                                      | A blockstream containing duplicate blocks | The duplicate block has its corresponding BlockAcknowledgement with `block_already_exists`=`true` | Y                 |