Improve some docs for the public facing types (#76)

Author: madninja

src/keypair.rs

@@ -9,6 +9,10 @@ pub trait Sign {
     fn sign(&self, msg: &[u8]) -> Result<Vec<u8>>;
 }
 
+/// Represents a cryptographic keypair for any supported key type.
+///
+/// This enum acts as a type-erased wrapper for all supported keypair types (e.g., Ed25519, Secp256k1, ECC Compact, etc.),
+/// allowing generic handling of key generation, signing, and public key extraction.
 #[derive(PartialEq, Debug)]
 pub enum Keypair {
     Secp256k1(secp256k1::Keypair),
@@ -45,6 +49,17 @@ impl Sign for Keypair {
 }
 
 impl Keypair {
+    /// Generates a new keypair for the specified key type and network using the provided CSPRNG.
+    ///
+    /// # Arguments
+    /// * `key_tag` - The key tag specifying the network and key type.
+    /// * `csprng` - A cryptographically secure random number generator.
+    ///
+    /// # Returns
+    /// A new `Keypair` instance for the requested type and network.
+    ///
+    /// # Panics
+    /// Panics if the key type is not supported or if key generation fails.
     pub fn generate<R>(key_tag: KeyTag, csprng: &mut R) -> Keypair
     where
         R: rand_core::CryptoRng + rand_core::RngCore,
@@ -64,6 +79,17 @@ impl Keypair {
         }
     }
 
+    /// Generates a new keypair from the provided entropy for the specified key type and network.
+    ///
+    /// # Arguments
+    /// * `key_tag` - The key tag specifying the network and key type.
+    /// * `entropy` - A byte slice containing sufficient entropy for key generation.
+    ///
+    /// # Returns
+    /// A new `Keypair` instance if the entropy is valid for the requested type and network.
+    ///
+    /// # Errors
+    /// Returns an error if the entropy is invalid or the key type is not supported.
     pub fn generate_from_entropy(key_tag: KeyTag, entropy: &[u8]) -> Result<Keypair> {
         match key_tag.key_type {
             KeyType::EccCompact => Ok(Self::EccCompact(
@@ -87,6 +113,9 @@ impl Keypair {
         }
     }
 
+    /// Returns the key tag for this keypair, encoding the network and key type.
+    ///
+    /// The key tag is used to identify the network and cryptographic algorithm associated with this keypair.
     pub fn key_tag(&self) -> KeyTag {
         match self {
             Self::Secp256k1(keypair) => keypair.key_tag(),
@@ -103,6 +132,9 @@ impl Keypair {
         }
     }
 
+    /// Returns a reference to the public key associated with this keypair.
+    ///
+    /// The returned public key can be used for signature verification or key exchange.
     pub fn public_key(&self) -> &PublicKey {
         match self {
             Self::Secp256k1(keypair) => &keypair.public_key,
@@ -119,6 +151,16 @@ impl Keypair {
         }
     }
 
+    /// Performs an Elliptic Curve Diffie-Hellman (ECDH) key exchange with the given public key.
+    ///
+    /// # Arguments
+    /// * `public_key` - The peer's public key.
+    ///
+    /// # Returns
+    /// A shared secret if ECDH is supported for this key type.
+    ///
+    /// # Errors
+    /// Returns an error if ECDH is not supported for this key type or if the operation fails.
     pub fn ecdh(&self, public_key: &PublicKey) -> Result<SharedSecret> {
         match self {
             Self::EccCompact(keypair) => Ok(SharedSecret(keypair.ecdh(public_key)?)),
@@ -130,6 +172,10 @@ impl Keypair {
         }
     }
 
+    /// Serializes the keypair to its binary representation.
+    ///
+    /// # Returns
+    /// A vector of bytes containing the serialized keypair, including the key tag and secret key material.
     pub fn to_vec(&self) -> Vec<u8> {
         match self {
             Self::Secp256k1(keypair) => keypair.to_vec(),
@@ -146,6 +192,13 @@ impl Keypair {
         }
     }
 
+    /// Serializes the secret key material to its binary representation.
+    ///
+    /// # Returns
+    /// A vector of bytes containing the secret key material only (excluding the key tag).
+    ///
+    /// # Security
+    /// Handle this output with care, as it contains sensitive private key material.
     pub fn secret_to_vec(&self) -> Vec<u8> {
         match self {
             Self::Secp256k1(keypair) => keypair.secret_to_vec(),

src/public_key.rs

@@ -22,7 +22,9 @@ pub trait PublicKeySize {
 /// A public key representing any of the supported public key types on a given
 /// network.
 ///
-/// Public keys can convert to and from their binary and base58 representation
+/// This struct acts as a type-erased wrapper for all supported public key types (e.g., Ed25519, Secp256k1, ECC Compact, etc.),
+/// allowing generic handling of serialization, deserialization, and verification.
+/// Public keys can be converted to and from their binary and base58 representations.
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct PublicKey {
     /// The network this public key is valid for
@@ -370,12 +372,21 @@ impl PublicKey {
         }
     }
 
-    /// Construct a public key from its binary form
+    /// Constructs a public key from its binary representation.
+    ///
+    /// # Arguments
+    /// * `bytes` - A byte slice containing the binary representation of the public key.
+    ///
+    /// # Errors
+    /// Returns an error if the bytes do not represent a valid public key for the expected type.
     pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Result<Self> {
         Self::try_from(bytes.as_ref())
     }
 
-    /// Convert a public key to it's binary form.
+    /// Serializes the public key to its binary representation.
+    ///
+    /// # Returns
+    /// A vector of bytes containing the serialized public key, including the key tag and key material.
     pub fn to_vec(&self) -> Vec<u8> {
         let mut result = vec![0u8; self.public_key_size()];
         // Unwrap ok here since we've allocated enough space for the output
@@ -384,7 +395,10 @@ impl PublicKey {
         result
     }
 
-    /// Get the type for this key
+    /// Returns the type of this public key (e.g., Ed25519, Secp256k1, etc.).
+    ///
+    /// # Returns
+    /// The `KeyType` variant corresponding to the underlying public key.
     pub fn key_type(&self) -> KeyType {
         match self.inner {
             PublicKeyRepr::EccCompact(..) => KeyType::EccCompact,
@@ -397,14 +411,20 @@ impl PublicKey {
         }
     }
 
-    /// Get the tag for this key
+    /// Returns the key tag for this public key, encoding the network and key type.
+    ///
+    /// The key tag is used to identify the network and cryptographic algorithm associated with this public key.
     pub fn key_tag(&self) -> KeyTag {
         KeyTag {
             network: self.network,
             key_type: self.key_type(),
         }
     }
 
+    /// Returns the size in bytes of the public key, including any prefix bytes.
+    ///
+    /// # Returns
+    /// The length in bytes of the serialized public key for the underlying type.
     pub fn public_key_size(&self) -> usize {
         match &self.inner {
             PublicKeyRepr::EccCompact(..) => ecc_compact::PublicKey::PUBLIC_KEY_SIZE,

src/public_key_binary.rs

@@ -1,6 +1,11 @@
 use crate::{Error, KeyTag, PublicKey, Result};
 use std::{convert::TryFrom, fmt, str::FromStr};
 
+/// An intermediate binary representation of a public key.
+///
+/// `PublicKeyBinary` wraps the raw bytes of a public key, including its key tag, and provides convenient
+/// conversions to and from [`PublicKey`], byte slices, and base58-encoded strings. This is useful for
+/// serialization, deserialization, and as a database-friendly format.
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct PublicKeyBinary(Vec<u8>);
 
@@ -16,6 +21,13 @@ impl fmt::Debug for PublicKeyBinary {
 }
 
 impl From<PublicKey> for PublicKeyBinary {
+    /// Converts a [`PublicKey`] into its binary representation.
+    ///
+    /// # Arguments
+    /// * `value` - The [`PublicKey`] to convert.
+    ///
+    /// # Returns
+    /// A `PublicKeyBinary` containing the serialized bytes of the public key.
     fn from(value: PublicKey) -> Self {
         Self(value.to_vec())
     }
@@ -41,6 +53,13 @@ impl From<PublicKeyBinary> for Vec<u8> {
 
 impl TryFrom<PublicKeyBinary> for PublicKey {
     type Error = Error;
+    /// Attempts to parse a [`PublicKey`] from its binary representation.
+    ///
+    /// # Arguments
+    /// * `value` - The `PublicKeyBinary` to parse.
+    ///
+    /// # Errors
+    /// Returns an error if the bytes do not represent a valid public key.
     fn try_from(value: PublicKeyBinary) -> Result<Self> {
         Self::try_from(value.0)
     }
@@ -54,13 +73,24 @@ impl AsRef<[u8]> for PublicKeyBinary {
 
 impl std::str::FromStr for PublicKeyBinary {
     type Err = Error;
+    /// Parses a `PublicKeyBinary` from a base58-encoded string.
+    ///
+    /// # Arguments
+    /// * `s` - The base58-encoded string.
+    ///
+    /// # Errors
+    /// Returns an error if the string is not valid base58 or does not decode to a valid public key binary.
     fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
         let mut data = bs58::decode(s).with_check(Some(0)).into_vec()?;
         Ok(Self(data.split_off(1)))
     }
 }
 
 impl std::fmt::Display for PublicKeyBinary {
+    /// Formats the `PublicKeyBinary` as a base58-encoded string, suitable for display or storage.
+    ///
+    /// # Returns
+    /// A base58-encoded string representation of the public key binary.
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::result::Result<(), std::fmt::Error> {
         // allocate one extra byte for the base58 version
         let mut data = vec![0u8; self.0.len() + 1];