Documentation Updates (#1105)

* Add comments

* Add comments and fix SCW verifier

* Update README

* Fix errors and warnings

* Regularly rotate leaf node encryption keys (#1108)

This PR achieves two things:
1. Before sending an application message on a new group, clients will always rotate their encryption keys first. The reason for this is that the first encryption key used on a group is derived from the client's key package - so if the key package is not rotated frequently enough, this safeguard prevents issues related to re-use across multiple groups.
2. All clients will also rotate their encryption keys on a 30 day interval, assuming they are active on a given group. This helps with post-compromise security.

Other notes:

1. I've consolidated all intent creation into a `queue_intent()` method. This makes it easier to add pre-intent and post-intent actions in the future, for example if we want to check for missing installations before publishing *any* intent.
2. With OpenMLS's default configuration, *any* commit will rotate the encryption key. I've used a post-intent action to mark the encryption key as rotated in this scenario, so we don't perform any additional unnecessary rotations.

* Fix conflicts

* Remove unused import

---------

Co-authored-by: Richard Hua <[email protected]>
Co-authored-by: Richard Hua <[email protected]>

bindings_ffi/src/mls.rs

@@ -2552,6 +2552,9 @@ mod tests {
         let bo_group = bo.group(alix_group.id()).unwrap();
 
         bo_group.send("bo1".as_bytes().to_vec()).await.unwrap();
+        // Temporary workaround for OpenMLS issue - make sure Alix's epoch is up-to-date
+        // https://github.com/xmtp/libxmtp/issues/1116
+        alix_group.sync().await.unwrap();
         alix_group.send("alix1".as_bytes().to_vec()).await.unwrap();
 
         // Move the group forward by 3 epochs (as Alix's max_past_epochs is
@@ -2755,6 +2758,9 @@ mod tests {
         log::info!("Caro sending fifth message");
         // Caro sends a message in the group
         caro_group.update_installations().await.unwrap();
+        // Temporary workaround for OpenMLS issue - make sure Caro's epoch is up-to-date
+        // https://github.com/xmtp/libxmtp/issues/1116
+        caro_group.sync().await.unwrap();
         caro_group
             .send("Fifth message".as_bytes().to_vec())
             .await

xmtp_id/src/associations/mod.rs

@@ -18,15 +18,15 @@ pub use self::serialization::{map_vec, try_map_vec, DeserializationError};
 pub use self::signature::*;
 pub use self::state::{AssociationState, AssociationStateDiff};
 
-// Apply a single IdentityUpdate to an existing AssociationState
+/// Apply a single [`IdentityUpdate`] to an existing [`AssociationState`] and return a new [`AssociationState`]
 pub fn apply_update(
     initial_state: AssociationState,
     update: IdentityUpdate,
 ) -> Result<AssociationState, AssociationError> {
     update.update_state(Some(initial_state), update.client_timestamp_ns)
 }
 
-// Get the current state from an array of `IdentityUpdate`s. Entire operation fails if any operation fails
+/// Get the current state from an array of `IdentityUpdate`s. Entire operation fails if any operation fails
 pub fn get_state<Updates: AsRef<[IdentityUpdate]>>(
     updates: Updates,
 ) -> Result<AssociationState, AssociationError> {

xmtp_id/src/associations/verified_signature.rs

@@ -49,6 +49,10 @@ impl VerifiedSignature {
         ))
     }
 
+    /**
+     * Verifies an ECDSA signature against the provided signature text and ensures that the recovered
+     * address matches the expected address.
+     */
     pub fn from_recoverable_ecdsa_with_expected_address<Text: AsRef<str>>(
         signature_text: Text,
         signature_bytes: &[u8],
@@ -95,6 +99,8 @@ impl VerifiedSignature {
         ))
     }
 
+    /// Verifies a legacy delegated signature and recovers the wallet address responsible
+    /// associated with the signer.
     pub fn from_legacy_delegated<Text: AsRef<str>>(
         signature_text: Text,
         signature_bytes: &[u8],
@@ -120,6 +126,7 @@ impl VerifiedSignature {
         ))
     }
 
+    /// Verifies a smart contract wallet signature using the provided signature verifier.
     pub async fn from_smart_contract_wallet<Text: AsRef<str>>(
         signature_text: Text,
         signature_verifier: &dyn SmartContractSignatureVerifier,