Add doxygen comments for new transactions and helper functions (#6332)

src/libxrpl/protocol/ConfidentialTransfer.cpp

@@ -117,12 +117,8 @@ serializeEcPair(secp256k1_pubkey const& in1, secp256k1_pubkey const& in2, Buffer
 bool
 isValidCiphertext(Slice const& buffer)
 {
-    // Local/temporary variables to pass to makeEcPair.
-    // Their contents will be discarded when the function returns.
     secp256k1_pubkey key1;
     secp256k1_pubkey key2;
-
-    // Call makeEcPair and return its result.
     return makeEcPair(buffer, key1, key2);
 }
 
@@ -193,22 +189,16 @@ generateBlindingFactor()
 std::optional<Buffer>
 encryptAmount(uint64_t const amt, Slice const& pubKeySlice, Slice const& blindingFactor)
 {
-    Buffer buf(ecGamalEncryptedTotalLength);
-
-    // Allocate ciphertext placeholders
-    secp256k1_pubkey c1, c2;
-    secp256k1_pubkey pubKey;
-
     if (blindingFactor.size() != ecBlindingFactorLength)
         return std::nullopt;
 
+    secp256k1_pubkey c1, c2, pubKey;
     std::memcpy(pubKey.data, pubKeySlice.data(), ecPubKeyLength);
 
-    // Encrypt the amount
     if (!secp256k1_elgamal_encrypt(secp256k1Context(), &c1, &c2, &pubKey, amt, blindingFactor.data()))
         return std::nullopt;
 
-    // Serialize the ciphertext pair into the buffer
+    Buffer buf(ecGamalEncryptedTotalLength);
     if (!serializeEcPair(c1, c2, buf))
         return std::nullopt;
 
@@ -221,18 +211,13 @@ encryptCanonicalZeroAmount(Slice const& pubKeySlice, AccountID const& account, M
     if (pubKeySlice.size() != ecPubKeyLength)
         return std::nullopt;  // LCOV_EXCL_LINE
 
-    secp256k1_pubkey c1, c2;
-    secp256k1_pubkey pubKey;
-
+    secp256k1_pubkey c1, c2, pubKey;
     std::memcpy(pubKey.data, pubKeySlice.data(), ecPubKeyLength);
 
-    // Encrypt the amount
     if (!generate_canonical_encrypted_zero(secp256k1Context(), &c1, &c2, &pubKey, account.data(), mptId.data()))
         return std::nullopt;
 
     Buffer buf(ecGamalEncryptedTotalLength);
-
-    // Serialize the ciphertext pair into the buffer
     if (!serializeEcPair(c1, c2, buf))
         return std::nullopt;
 
@@ -242,20 +227,16 @@ encryptCanonicalZeroAmount(Slice const& pubKeySlice, AccountID const& account, M
 TER
 verifySchnorrProof(Slice const& pubKeySlice, Slice const& proofSlice, uint256 const& contextHash)
 {
-    // sanity check proof length
     if (proofSlice.size() != ecSchnorrProofLength)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    // sanity check public key length
     if (pubKeySlice.size() != ecPubKeyLength)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
     secp256k1_pubkey pubKey;
     std::memcpy(pubKey.data, pubKeySlice.data(), ecPubKeyLength);
 
-    int result = secp256k1_mpt_pok_sk_verify(secp256k1Context(), proofSlice.data(), &pubKey, contextHash.data());
-
-    if (result != 1)
+    if (secp256k1_mpt_pok_sk_verify(secp256k1Context(), proofSlice.data(), &pubKey, contextHash.data()) != 1)
         return tecBAD_PROOF;
 
     return tesSUCCESS;
@@ -268,11 +249,9 @@ verifyElGamalEncryption(
     Slice const& pubKeySlice,
     Slice const& ciphertext)
 {
-    // sanity check blinding factor length
     if (blindingFactor.size() != ecBlindingFactorLength)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    // sanity check public key length
     if (pubKeySlice.size() != ecPubKeyLength)
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
@@ -283,13 +262,8 @@ verifyElGamalEncryption(
     if (!makeEcPair(ciphertext, c1, c2))
         return tecINTERNAL;  // LCOV_EXCL_LINE
 
-    int result =
-        secp256k1_elgamal_verify_encryption(secp256k1Context(), &c1, &c2, &pubKey, amount, blindingFactor.data());
-
-    if (result != 1)
-    {
+    if (secp256k1_elgamal_verify_encryption(secp256k1Context(), &c1, &c2, &pubKey, amount, blindingFactor.data()) != 1)
         return tecBAD_PROOF;
-    }
 
     return tesSUCCESS;
 }
@@ -392,6 +366,9 @@ verifyClawbackEqualityProof(
     secp256k1_pubkey pubKey;
     std::memcpy(pubKey.data, pubKeySlice.data(), ecPubKeyLength);
 
+    // Note: c2, c1 order - the proof is generated with c2 first (the encrypted
+    // message component) because the equality proof structure expects the
+    // message-containing term before the blinding term.
     if (secp256k1_equality_plaintext_verify(
             secp256k1Context(), proof.data(), &pubKey, &c2, &c1, amount, contextHash.data()) != 1)
     {
@@ -484,6 +461,8 @@ verifyBalancePcmLinkage(
     std::memcpy(pubKey.data, pubKeySlice.data(), ecPubKeyLength);
     std::memcpy(pcm.data, pcmSlice.data(), ecPubKeyLength);
 
+    // Note: c2, c1 order - the linkage proof expects the message-containing
+    // component (c2 = m*G + r*Pk) before the blinding component (c1 = r*G).
     if (secp256k1_elgamal_pedersen_link_verify(
             secp256k1Context(), proof.data(), &pubKey, &c2, &c1, &pcm, contextHash.data()) != 1)
     {
@@ -517,7 +496,6 @@ secp256k1_elgamal_generate_keypair(secp256k1_context const* ctx, unsigned char*
     return 1;  // Success
 }
 
-// ... implementation of secp256k1_elgamal_encrypt ...
 int
 secp256k1_elgamal_encrypt(
     secp256k1_context const* ctx,
@@ -579,7 +557,6 @@ secp256k1_elgamal_encrypt(
     return 1;  // Success
 }
 
-// ... implementation of secp256k1_elgamal_decrypt ...
 int
 secp256k1_elgamal_decrypt(
     secp256k1_context const* ctx,

src/xrpld/app/tx/detail/ConfidentialMPTClawback.h

@@ -5,6 +5,22 @@
 
 namespace xrpl {
 
+/**
+ * @brief Allows an MPT issuer to clawback confidential balances from a holder.
+ *
+ * This transaction enables the issuer of an MPToken Issuance (with clawback
+ * enabled) to reclaim confidential tokens from a holder's account. Unlike
+ * regular clawback, the issuer cannot see the holder's balance directly.
+ * Instead, the issuer must provide a zero-knowledge proof that demonstrates
+ * they know the exact encrypted balance amount.
+ *
+ * @par Cryptographic Operations:
+ * - **Equality Proof Verification**: Verifies that the issuer's revealed
+ *   amount matches the holder's encrypted balance using the issuer's
+ *   ElGamal private key.
+ *
+ * @see ConfidentialMPTSend, ConfidentialMPTConvert
+ */
 class ConfidentialMPTClawback : public Transactor
 {
 public:

src/xrpld/app/tx/detail/ConfidentialMPTConvert.h

@@ -5,6 +5,24 @@
 
 namespace xrpl {
 
+/**
+ * @brief Converts public (plaintext) MPT balance to confidential (encrypted)
+ * balance.
+ *
+ * This transaction allows a token holder to convert their publicly visible
+ * MPToken balance into an encrypted confidential balance. Once converted,
+ * the balance can only be spent using ConfidentialMPTSend transactions and
+ * remains hidden from public view on the ledger.
+ *
+ * @par Cryptographic Operations:
+ * - **Schnorr Proof Verification**: When registering a new ElGamal public key,
+ *   verifies proof of knowledge of the corresponding private key.
+ * - **Revealed Amount Verification**: Verifies that the provided encrypted
+ *   amounts (for holder, issuer, and optionally auditor) all encrypt the
+ *   same plaintext amount using the provided blinding factor.
+ *
+ * @see ConfidentialMPTConvertBack, ConfidentialMPTSend
+ */
 class ConfidentialMPTConvert : public Transactor
 {
 public:

src/xrpld/app/tx/detail/ConfidentialMPTConvertBack.h

@@ -5,6 +5,25 @@
 
 namespace xrpl {
 
+/**
+ * @brief Converts confidential (encrypted) MPT balance back to public
+ * (plaintext) balance.
+ *
+ * This transaction allows a token holder to convert their encrypted
+ * confidential balance back into a publicly visible MPToken balance. The
+ * holder must prove they have sufficient confidential balance without
+ * revealing the actual balance amount.
+ *
+ * @par Cryptographic Operations:
+ * - **Revealed Amount Verification**: Verifies that the provided encrypted
+ *   amounts correctly encrypt the conversion amount.
+ * - **Pedersen Linkage Proof**: Verifies that the provided balance commitment
+ *   correctly links to the holder's encrypted spending balance.
+ * - **Bulletproof Range Proof**: Verifies that the remaining balance (after
+ *   conversion) is non-negative, ensuring the holder has sufficient funds.
+ *
+ * @see ConfidentialMPTConvert, ConfidentialMPTSend
+ */
 class ConfidentialMPTConvertBack : public Transactor
 {
 public:

src/xrpld/app/tx/detail/ConfidentialMPTMergeInbox.h

@@ -5,6 +5,26 @@
 
 namespace xrpl {
 
+/**
+ * @brief Merges the confidential inbox balance into the spending balance.
+ *
+ * In the confidential transfer system, incoming funds are deposited into an
+ * "inbox" balance that the recipient cannot immediately spend. This prevents
+ * front-running attacks where an attacker could invalidate a pending
+ * transaction by sending funds to the sender. This transaction merges the
+ * inbox into the spending balance, making those funds available for spending.
+ *
+ * @par Cryptographic Operations:
+ * - **Homomorphic Addition**: Adds the encrypted inbox balance to the
+ *   encrypted spending balance using ElGamal homomorphic properties.
+ * - **Zero Encryption**: Resets the inbox to an encryption of zero.
+ *
+ * @note This transaction requires no zero-knowledge proofs because it only
+ *       combines encrypted values that the holder already owns. The
+ *       homomorphic properties of ElGamal encryption ensure correctness.
+ *
+ * @see ConfidentialMPTSend, ConfidentialMPTConvert
+ */
 class ConfidentialMPTMergeInbox : public Transactor
 {
 public:

src/xrpld/app/tx/detail/ConfidentialMPTSend.h

@@ -5,6 +5,32 @@
 
 namespace xrpl {
 
+/**
+ * @brief Transfers confidential MPT tokens between holders privately.
+ *
+ * This transaction enables private token transfers where the transfer amount
+ * is hidden from public view. Both sender and recipient must have initialized
+ * confidential balances. The transaction provides encrypted amounts for all
+ * parties (sender, destination, issuer, and optionally auditor) along with
+ * zero-knowledge proofs that verify correctness without revealing the amount.
+ *
+ * @par Cryptographic Operations:
+ * - **Multi-Ciphertext Equality Proof**: Verifies that all encrypted amounts
+ *   (sender, destination, issuer, auditor) encrypt the same plaintext value.
+ * - **Amount Pedersen Linkage Proof**: Verifies that the amount commitment
+ *   correctly links to the sender's encrypted amount.
+ * - **Balance Pedersen Linkage Proof**: Verifies that the balance commitment
+ *   correctly links to the sender's encrypted spending balance.
+ * - **Bulletproof Range Proof**: Verifies remaining balance and
+ *   transfer amount are non-negative.
+ *
+ * @note Funds are deposited into the destination's inbox, not spending
+ *       balance. The recipient must call ConfidentialMPTMergeInbox to make
+ *       received funds spendable.
+ *
+ * @see ConfidentialMPTMergeInbox, ConfidentialMPTConvert,
+ * ConfidentialMPTConvertBack
+ */
 class ConfidentialMPTSend : public Transactor
 {
 public: