pairing.rs documentation

tests/pairing.rs

@@ -23,6 +23,66 @@ use utils::*;
 
 wasm_bindgen_test_configure!(run_in_browser);
 
+/// # Pairing Process Documentation between Alice and Bob
+///
+/// This test describes the secure pairing process between two devices, Alice and Bob,
+/// across several steps, utilizing `process_cache` to store and exchange the process state
+/// while mutually validating their commitments. Each stage is designed to establish a strong
+/// validation between the two devices via secure exchanges of `prd` messages (updates and confirmations).
+///
+/// ## Step 1 - Pairing Preparation by Alice
+/// 1. **Establishing a Shared Secret**: A shared secret is established via `connect.rs` to secure
+///    communication between Alice and Bob.
+/// 2. **Pairing Status Check**: Alice verifies that the pairing is not already active.
+/// 3. **Adding Bob's Address**: Alice adds Bob’s address to her own, setting the base for creating
+///    a new `Member` object.
+/// 4. **Initiating Pairing**: Alice initializes pairing using the transaction’s `commitment` and
+///    the created member, which contains the list of devices.
+/// 5. **Updating `prd`**: Alice creates an update `prd`, stores this new state in
+///    `alice_process_cache`, and sends the `prd` to Bob.
+///
+/// ## Step 2 - Receiving and Confirming the `prd` by Bob
+/// 1. **Receiving and Verifying**: Bob receives and decrypts the update `prd` message sent by Alice.
+/// 2. **Updating Process State**: Bob updates his process state using the `prd` data and stores
+///    this new state in `bob_process_cache`.
+/// 3. **Creating and Sending `Prd Confirm`**: Bob creates a confirmation `prd`, which he then
+///    sends to Alice to proceed with the pairing.
+///
+/// ## Step 3 - Confirmation of `Prd Confirm` by Alice
+/// 1. **Receiving and Verifying**: Alice receives the `Prd Confirm` sent by Bob.
+/// 2. **Creating Commitment**: Alice uses the received `prd` to generate a commitment based on the
+///    recorded process state.
+/// 3. **Proof Generation**: Alice creates a proof using her private spend key and response to the
+///    commitment, which is then added to the `prd`.
+/// 4. **Updating `process_cache`**: Alice stores the new state in `alice_process_cache`.
+/// 5. **Sending `Prd Response`**: Alice creates and sends a `Prd Response` to Bob, including
+///    the commitment of the `pcd` which will validate the pairing.
+///
+/// ## Step 4 - Finalizing Pairing by Bob
+/// 1. **Receiving and Verifying `Prd Response` and `pcd`**: Bob receives Alice’s `Prd Response`
+///    and updates `bob_process_cache` with the new state.
+/// 2. **Validating Pairing State**: Bob retrieves the latest process state and the state change
+///    request, in this case, the pairing.
+///     - He validates the current process state.
+///     - He decrypts the `pcd` to retrieve the request.
+/// 3. **Verifying Roles and Addresses**: Bob extracts the roles associated with the state change,
+///    retrieves the addresses of involved members, and displays them to the user to confirm pairing.
+/// 4. **Adding Final Proof**: Upon user confirmation, Bob generates and adds his proof to the `prd`,
+///    then records the final state in `bob_process_cache`.
+///
+/// ## Creation of Pairing Transaction
+/// 1. **Creating the `commit_msg`**: A validation message (`commit_msg`) containing proofs from
+///    both Alice and Bob is generated.
+/// 2. **Creating the Transaction**: A transaction containing the final commitment is created and
+///    shared between Alice and Bob.
+/// 3. **Device Pairing**: Using the transaction `txid` and the list of member addresses, the
+///    pairing is officially initiated, validated by a new `Member` object grouping Alice and Bob’s
+///    addresses along with the transaction.
+///
+/// ## Final Outcome
+/// The pairing is now active between Alice and Bob, ensuring the mutual validation of their
+/// respective identities and shared commitment to the validated `prd`.
+
 #[wasm_bindgen_test]
 fn test_pairing() {
     setup();