add suggestion

protocols/v2/noise-sv2/README.md

@@ -20,3 +20,12 @@ To include this crate in your project, run:
 
 ```bash
 cargo add noise_sv2
+```
+### Examples
+
+This crate provides example on establishing a secure line:
+
+1. **[Noise Handshake Example](https://github.com/stratum-mining/stratum/blob/main/protocols/v2/noise-sv2/examples/noise_handshake.rs)**:
+   Establish a secure line of communication between an Initiator and Responder via the Noise
+   protocol, allowing for the encryption and decryption of a secret message.
+

protocols/v2/noise-sv2/src/cipher_state.rs

@@ -39,14 +39,17 @@ use crate::aed_cipher::AeadCipher;
 use aes_gcm::Aes256Gcm;
 use chacha20poly1305::{aead::Buffer, ChaCha20Poly1305};
 
-// Manages the state and operations of an AEAD cipher.
-//
-// Provides methods for managing the cryptographic state of an AEAD cipher, including the
-// encryption key (`k`), nonce (`n`), and the cipher instance itself. It also provides methods for
-// encrypting and decrypting data with additional associated data (AAD) using the managed cipher.
-//
-// [`CipherState`] is typically implemented by structs that need to manage cipher state as part of
-// a the Noise protocol handshake.
+/// The `CipherState` trait manages AEAD ciphers for secure communication, handling the encryption key, nonce,
+/// and cipher instance. It supports encryption and decryption with ciphers like [`ChaCha20Poly1305`] and
+/// [`Aes256Gcm`], ensuring proper key and nonce management.
+///
+/// Key responsibilities:
+/// - **Key management**: Set and retrieve the 32-byte encryption key.
+/// - **Nonce management**: Track unique nonces for encryption operations.
+/// - **Cipher handling**: Initialize and manage AEAD ciphers for secure data encryption.
+///
+/// Used in protocols like Noise, `CipherState` ensures secure communication by managing cryptographic material
+/// during and after handshakes.
 pub trait CipherState<Cipher_: AeadCipher>
 where
     Self: Sized,
@@ -159,17 +162,15 @@ where
     }
 }
 
-// An enum representing a generic cipher state.
-//
-// [`GenericCipher`] abstracts over different AEAD cipher implementations, allowing for flexible
-// use of either [`ChaCha20Poly1305`] or [`Aes256Gcm`]. It provides methods for encryption,
-// decryption, and key erasure.
-//
-// A generic cipher that can be either [`ChaCha20Poly1305`] or [`Aes256Gcm`].
-//
-// The [`GenericCipher`] enum allows for flexibility in choosing between different AEAD ciphers.
-// It provides methods for encrypting, decrypting, and securely erasing the encryption key,
-// ensuring that sensitive cryptographic material is handled correctly.
+/// The `GenericCipher` enum abstracts the use of two AEAD ciphers: [`ChaCha20Poly1305`] and [`Aes256Gcm`].
+/// It provides a unified interface for secure encryption and decryption, allowing flexibility in choosing
+/// the cipher while ensuring consistent cryptographic operations.
+///
+/// Variants:
+/// - **ChaCha20Poly1305**: Uses the `ChaCha20Poly1305` cipher for encryption.
+/// - **Aes256Gcm**: Uses the `Aes256Gcm` cipher for encryption.
+///
+/// `GenericCipher` enables easy switching between ciphers while maintaining secure key and nonce management.
 #[allow(clippy::large_enum_variant)]
 pub enum GenericCipher {
     ChaCha20Poly1305(Cipher<ChaCha20Poly1305>),

protocols/v2/noise-sv2/src/initiator.rs

@@ -55,9 +55,11 @@ use secp256k1::{
     Keypair, PublicKey, XOnlyPublicKey,
 };
 
-/// Manages the state of the initiator during the Noise NX protocol handshake process. It holds the
-/// necessary cryptographic keys, handshake state, and intermediate values needed to perform the
-/// key exchange and establish a secure connection with the responder.
+/// Manages the initiator's role in the Noise NX handshake, handling key exchange, encryption, and
+/// handshake state. It securely generates and manages cryptographic keys, performs Diffie-Hellman
+/// exchanges, and maintains the handshake hash, chaining key, and nonce for message encryption.
+/// After the handshake, it facilitates secure communication using either [`ChaCha20Poly1305`] or
+/// `AES-GCM` ciphers. Sensitive data is securely erased when no longer needed.
 pub struct Initiator {
     // Cipher used for encrypting and decrypting messages during the handshake.
     //

protocols/v2/noise-sv2/src/responder.rs

@@ -53,11 +53,11 @@ use secp256k1::{ellswift::ElligatorSwift, Keypair, Secp256k1, SecretKey};
 
 const VERSION: u16 = 0;
 
-/// Represents the state and operations of the Noise NX protocol responder.
-///
-/// Manages the state of the responder during the Noise NX protocol handshake process. It holds the
-/// necessary cryptographic keys, handshake state, and intermediate values needed to perform the
-/// key exchange and establish a secure connection with the initiator.
+/// Represents the state and operations of the responder in the Noise NX protocol handshake.
+/// It handles cryptographic key exchanges, manages handshake state, and securely establishes
+/// a connection with the initiator. The responder manages key generation, Diffie-Hellman exchanges,
+/// message decryption, and state transitions, ensuring secure communication. Sensitive cryptographic
+/// material is securely erased when no longer needed.
 pub struct Responder {
     // Cipher used for encrypting and decrypting messages during the handshake.
     //