diff --git a/server/docs/design/block-verification.md b/server/docs/design/block-verification.md index aa2575775..44c464f9c 100644 --- a/server/docs/design/block-verification.md +++ b/server/docs/design/block-verification.md @@ -1,6 +1,7 @@ # Block Verification Design ## Table of Contents + 1. [Purpose](#purpose) 1. [Goals](#goals) 1. [Terms](#terms) @@ -12,54 +13,83 @@ 1. [Exceptions](#exceptions) ## Purpose -The purpose of the Block Verification feature is to ensure that blocks received from consensus nodes are valid and have not been tampered with. This is achieved by re-calculating the block hash and verifying it against the signature provided by the consensus node. + +The purpose of the Block Verification feature is to ensure that blocks received +from consensus nodes are valid and have not been tampered with. This is achieved +by re-calculating the block hash and verifying it against the signature provided +by the consensus node. ## Goals -1. The block-node must re-create the block hash from the block items and verify that it matches the hash implied by the signature. -1. If verification fails, the block should be considered invalid, and appropriate error-handling procedures must be triggered. + +1. The block-node must re-create the block hash from the block items and verify + that it matches the hash implied by the signature. +1. If verification fails, the block should be considered invalid, and + appropriate error-handling procedures must be triggered. ## Terms +
Consensus Node (CN)
A node that produces and provides blocks.
-
Block Items
The block data pieces (header, events, transactions, transaction result, state changes, proof) that make up a block.
+
Block Items
The block data pieces (header, events, transactions, +transaction result, state changes, proof) that make up a block.
Block Hash
A cryptographic hash representing the block’s integrity.
-
Signature
The cryptographic signature of the block hash created by Network private key (aka: LedgerId).
+
Signature
The cryptographic signature of the block hash created by +Network private key (aka: LedgerId).
Public Key
The public key of the LedgerId that signed the block.
## Entities - #### VerificationHandler - - Receives the stream of block items from the (partially) parsed and unverified block items ring buffer. - - When it detects a block_header, it creates a BlockHashingSession using the BlockHashingSessionFactory, providing it with the initial block items (and internally, the session will handle asynchronous hashing). - - Adds subsequent block items to the session, including the block_proof. - - Does not block waiting for verification; the hash computation and verification continue asynchronously. + - Receives the stream of block items from the (partially) parsed and + unverified block items ring buffer. + - When it detects a block_header, it creates a BlockHashingSession using the + BlockHashingSessionFactory, providing it with the initial block items (and + internally, the session will handle asynchronous hashing). + - Adds subsequent block items to the session, including the block_proof. + - Does not block waiting for verification; the hash computation and + verification continue asynchronously. - ### BlockHashingSessionFactory - - Creates new BlockHashingSession instances, provides them with a ExecutorService. + - Creates new BlockHashingSession instances, provides them with a + ExecutorService. - ### BlockHashingSession - - Holds all necessary block data while it is waiting to hash it. - - Accepts block items incrementally. (continues to compute them asynchronously) - - Once the block_proof is provided, finalizes the hash computation asynchronously. - - After computing the final hash, calls SignatureVerifier for verification. + - Holds all necessary block data while it is waiting to hash it. + - Accepts block items incrementally. (continues to compute them + asynchronously) + - Once the block_proof is provided, finalizes the hash computation + asynchronously. + - After computing the final hash, calls SignatureVerifier for verification. - ### SignatureVerifier - - Verifies the block signature is valid (using the ledger ID) and signed the same hash that was computed by the `BlockHashingSession`. - - Report results to BlockStatusManager. + - Verifies the block signature is valid (using the ledger ID) and signed the + same hash that was computed by the `BlockHashingSession`. + - Report results to BlockStatusManager. - ### BlockStatusManager - - Receives verification results from SignatureVerifier. - - Updates block status and triggers any necessary recovery or follow-up processes depending on the outcome. + - Receives verification results from SignatureVerifier. + - Updates block status and triggers any necessary recovery or follow-up + processes depending on the outcome. ## Design -1. The `VerificationHandler` receives the block items from the unverified ring buffer. -1. When the block_header is detected, the `VerificationHandler` creates a `BlockHashingSession` using the `BlockHashingSessionFactory`. + +1. The `VerificationHandler` receives the block items from the unverified ring + buffer. +1. When the block_header is detected, the `VerificationHandler` creates a + `BlockHashingSession` using the `BlockHashingSessionFactory`. 1. The `BlockHashingSession` accepts subsequent block items incrementally. -1. Once the block_proof is received, the `BlockHashingSession` calls `completeHashing()` to finalize the hash computation. -1. Upon completion of computing the final block hash, the `BlockHashingSession` calls the `SignatureVerifier` to verify the signature. -1. The `SignatureVerifier` compares the computed hash to the hash signed by the Block Proof signature. -1. If the verification fails, the `SignatureVerifier` calls the `BlockStatusManager` to update the block status as SIGNATURE_INVALID. -1. If the verification succeeds, the `SignatureVerifier` calls the `BlockStatusManager` to update the block status as VERIFIED. -1. The `BlockStatusManager` initiates any necessary recovery or follow-up processes depending on the verification result. +1. Once the block_proof is received, the `BlockHashingSession` calls + `completeHashing()` to finalize the hash computation. +1. Upon completion of computing the final block hash, the `BlockHashingSession` + calls the `SignatureVerifier` to verify the signature. +1. The `SignatureVerifier` compares the computed hash to the hash signed by the + Block Proof signature. +1. If the verification fails, the `SignatureVerifier` calls the + `BlockStatusManager` to update the block status as SIGNATURE_INVALID. +1. If the verification succeeds, the `SignatureVerifier` calls the + `BlockStatusManager` to update the block status as VERIFIED. +1. The `BlockStatusManager` initiates any necessary recovery or follow-up + processes depending on the verification result. Sequence Diagram: + ```mermaid sequenceDiagram participant U as UnverifiedRingBuffer @@ -111,73 +141,107 @@ sequenceDiagram ## Interfaces ### VerificationHandler + ```java public interface VerificationHandler { - void onBlockItemsReceived(List blockItems); + void onBlockItemsReceived(List blockItems); } ``` ### BlockHashingSessionFactory + ```java public interface BlockHashingSessionFactory { - BlockHashingSession createSession(List initialBlockItems, ExecutorService executorService, SignatureVerifier signatureVerifier); + BlockHashingSession createSession(List initialBlockItems, + ExecutorService executorService, + SignatureVerifier signatureVerifier); } ``` ### BlockHashingSession + ```java public interface BlockHashingSession { - void addBlockItem(BlockItem item); - CompletableFuture completeHashing(); + void addBlockItem(BlockItem item); + + CompletableFuture completeHashing(); } ``` ### SignatureVerifier + ```java public interface SignatureVerifier { - void verifySignature(byte[] signature, byte[] computedHash, long blockNumber); + void verifySignature(byte[] signature, + byte[] computedHash, + long blockNumber); } ``` ### BlockStatusManager + ```java public interface BlockStatusManager { - void updateBlockStatus(long blockNumber, BlockVerificationStatus status, VerificationError error); + void updateBlockStatus(long blockNumber, + BlockVerificationStatus status, + VerificationError error); } ``` ## Enums + ```java public enum BlockVerificationStatus { - VERIFIED, - ERROR + VERIFIED, + ERROR } public enum VerificationError { - NONE, - SIGNATURE_INVALID, - SYSTEM_ERROR + NONE, + SIGNATURE_INVALID, + SYSTEM_ERROR } ``` ## Configuration -As with other services already implemented in the Block Node system, the current Block Verification Service should be able to be configurable via a Config Object `VerificationConfig` and all the configurations needed shall be defined in there. -Specifics on the properties names and possible values will be defined at the Configuration document, but should include a way to enable/disable the module, select Hashing algorithm and the amount of concurrent workers for the `ServiceExecutor` pool. +As with other services already implemented in the Block Node system, the current +Block Verification Service should be able to be configurable via a Config Object +`VerificationConfig` and all the configurations needed shall be defined in +there. + +Specifics on the properties names and possible values will be defined at the +Configuration document, but should include a way to enable/disable the module, +select Hashing algorithm and the amount of concurrent workers for the +`ServiceExecutor` pool. ## Metrics +
-
blocks_received
Counter of the number of blocks received for verification.
+
blocks_received
Counter of the number of blocks received for +verification.
blocks_verified
Counter of the number of blocks verified.
-
blocks_unverified
Counter of the number of blocks that have not been verified, is the difference between blocks_received and blocks_verified.
-
blocks_signature_invalid
Counter of the number of blocks with invalid signatures.
-
blocks_system_error
Counter of the number of blocks with system errors.
-
block_verification_time
Histogram of the time taken to verify a block, gives the node operator an idea of the time taken to verify a block.
+
blocks_unverified
Counter of the number of blocks that have not been +verified, is the difference between blocks_received and blocks_verified.
+
blocks_signature_invalid
Counter of the number of blocks with +invalid signatures.
+
blocks_system_error
Counter of the number of blocks with system +errors.
+
block_verification_time
Histogram of the time taken to verify a +block, gives the node operator an idea of the time taken to verify a block.
## Exceptions -- **SYSTEM_ERROR:** Issues with node configuration or bugs. The node logs details, updates metrics, and might attempt recovery or halt. -- **SIGNATURE_INVALID:** If verification fails, SIGNATURE_INVALID is used. The block is marked invalid, and the BlockStatusManager triggers error-handling routines (requesting re-sends, removing corrupted data, notifying subscribers, etc.). + +- **SYSTEM_ERROR:** Issues with node configuration or bugs. The node logs + details, updates metrics, and might attempt recovery or halt. +- **SIGNATURE_INVALID:** If verification fails, SIGNATURE_INVALID is used. The + block is marked invalid, and the BlockStatusManager triggers error-handling + routines (requesting re-sends, removing corrupted data, notifying subscribers, + etc.). ### Signature invalid -If the computed hash does not match the hash signed by the network, the block is considered unverified. It is marked as such and publishers are requested to resend the block. + +If the computed hash does not match the hash signed by the network, the block is +considered unverified. It is marked as such and publishers are requested to +resend the block.