chore: add docs and unclog

.changelog/unreleased/breaking-changes/1255-enable-custom-paths-for-proof-verificaitons.md

@@ -0,0 +1,4 @@
+- [ibc-core-client] Enable `verify_(non_)membership()` methods to accept custom
+  paths as bytes by defining a new `serializer_path()` API allowing light client
+  developers to introduce the path serialization behavior of their system.
+  ([\#1255](https://github.com/cosmos/ibc-rs/issues/1255))

ibc-clients/ics07-tendermint/src/client_state/common.rs

@@ -231,7 +231,7 @@ pub fn verify_membership<H: HostFunctionsProvider>(
     path: PathBytes,
     value: Vec<u8>,
 ) -> Result<(), ClientError> {
-    let merkle_path = MerklePath::new(vec![prefix.clone().into_vec().into(), path]);
+    let merkle_path = MerklePath::new(vec![prefix.as_bytes().to_vec().into(), path]);
     let merkle_proof = MerkleProof::try_from(proof).map_err(ClientError::InvalidCommitmentProof)?;
 
     merkle_proof
@@ -251,7 +251,7 @@ pub fn verify_non_membership<H: HostFunctionsProvider>(
     root: &CommitmentRoot,
     path: PathBytes,
 ) -> Result<(), ClientError> {
-    let merkle_path = MerklePath::new(vec![prefix.clone().into_vec().into(), path]);
+    let merkle_path = MerklePath::new(vec![prefix.as_bytes().to_vec().into(), path]);
     let merkle_proof = MerkleProof::try_from(proof).map_err(ClientError::InvalidCommitmentProof)?;
 
     merkle_proof

ibc-core/ics02-client/context/src/client_state.rs

@@ -52,7 +52,13 @@ pub trait ClientStateCommon: Convertible<Any> {
         root: &CommitmentRoot,
     ) -> Result<(), ClientError>;
 
-    /// Determines how a path should be serialized into a `PathBytes` object.
+    /// Serializes a given path into a `PathBytes` object.
+    ///
+    /// This method provides essential information for IBC modules, enabling
+    /// them to understand how path serialization is performed on the
+    /// counterparty chain (where this light client represents it) before
+    /// passing the path bytes to either `verify_membership()` or
+    /// `verify_non_membership()`.
     fn serialize_path(&self, path: impl Into<Path>) -> Result<PathBytes, ClientError>;
 
     // Verify_membership is a generic proof verification method which verifies a

ibc-core/ics23-commitment/types/src/merkle.rs

@@ -16,6 +16,14 @@ use crate::commitment::CommitmentRoot;
 use crate::error::CommitmentError;
 use crate::specs::ProofSpecs;
 
+/// A wrapper type representing a Merkle path, consisting of a sequence of path
+/// bytes.
+///
+/// This struct by definition is compatible with Cosmos SDK chains, but it is
+/// also applicable to other blockchain implementations that follow similar path
+/// structures. Note that while Cosmos SDK chains and some non-Cosmos chains
+/// adhere to this definition, it may not be universally applicable to all
+/// non-Cosmos chains.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, PartialEq)]
@@ -24,6 +32,7 @@ pub struct MerklePath {
 }
 
 impl MerklePath {
+    /// Constructs a new `MerklePath` from a given `Vec<PathBytes>`.
     pub fn new(key_path: Vec<PathBytes>) -> Self {
         Self { key_path }
     }
@@ -41,6 +50,10 @@ impl From<RawMerklePath> for MerklePath {
     }
 }
 
+// The conversion from `MerklePath`` to `RawMerklePath` is not provided as we
+// cannot assume how the key paths of `Vec<PathBytes>` type should be serialized
+// to the `Vec<String>`.
+
 impl From<CommitmentRoot> for MerkleRoot {
     fn from(root: CommitmentRoot) -> Self {
         Self {