[confidential-transfer] Add docs and additional comments in the proof generation logic (#638)

Author: samkim-crypto

confidential-transfer/proof-extraction/src/burn.rs

@@ -83,6 +83,7 @@ impl BurnProofContext {
             *remaining_balance_commitment,
             burn_amount_commitment_lo,
             burn_amount_commitment_hi,
+            // we don't care about the padding commitment, so ignore it
         ];
 
         // range proof context always contains 8 commitments and therefore,

confidential-transfer/proof-extraction/src/mint.rs

@@ -83,6 +83,7 @@ impl MintProofContext {
             *new_supply_commitment,
             mint_amount_commitment_lo,
             mint_amount_commitment_hi,
+            // we don't care about the padding commitment, so ignore it
         ];
 
         // range proof context always contains 8 commitments and therefore,

confidential-transfer/proof-extraction/src/transfer.rs

@@ -88,6 +88,7 @@ impl TransferProofContext {
             *new_source_commitment,
             transfer_amount_commitment_lo,
             transfer_amount_commitment_hi,
+            // we don't care about the padding commitment, so ignore it
         ];
 
         // range proof context always contains 8 commitments and therefore,

confidential-transfer/proof-generation/src/burn.rs

@@ -1,3 +1,39 @@
+//! Generates the zero-knowledge proofs required for a confidential burn.
+//!
+//! A confidential burn operation removes tokens from a user's confidential balance and decreases the
+//! token's total supply. This process requires three distinct zero-knowledge proofs to ensure the
+//! operation is valid, the user is solvent, and the token supply is updated correctly.
+//!
+//! ## Protocol Flow and Proof Components
+//!
+//! 1.  **Encrypt Burn Amount**: The burn amount is encrypted in a grouped (twisted) ElGamal
+//!     ciphertext. This single operation prepares the `burn_amount` to be simultaneously
+//!     subtracted from the user's account and recorded in the mint's `pending_burn` accumulator,
+//!     which will later be subtracted from the total supply.
+//!
+//! 2.  **Homomorphic Calculation**: The client homomorphically computes their new encrypted balance
+//!     by subtracting the source-encrypted component of the `burn_amount` from their current
+//!     `available_balance` ciphertext.
+//!
+//! 3.  **Generate Proofs**: The user generates three proofs:
+//!
+//!     -   **Batched Grouped Ciphertext Validity Proof**:
+//!         This proof certifies that the grouped ElGamal ciphertext for the `burn_amount` is well-formed
+//!         and was correctly encrypted for the source, supply, and auditor public keys.
+//!
+//!     -   **Ciphertext-Commitment Equality Proof**:
+//!         This proof provides the cryptographic link needed for the solvency check. After the user's
+//!         new balance is computed homomorphically, the prover no longer knows the associated
+//!         Pedersen opening. To perform a range proof, the prover creates a *new* Pedersen commitment
+//!         for their `remaining_balance` (for which they know the opening) and uses this proof to
+//!         certify that the ciphertext and the new commitment hide the same value.
+//!
+//!     -   **Range Proof (`BatchedRangeProofU128`)**:
+//!         This proof is the core solvency check. It certifies that the user's `remaining_balance`
+//!         is non-negative (i.e., in the range `[0, 2^64)`), which makes it cryptographically
+//!         impossible to burn more tokens than one possesses. It also proves the `burn_amount` itself
+//!         is a valid 48-bit number.
+
 #[cfg(target_arch = "wasm32")]
 use solana_zk_sdk::encryption::grouped_elgamal::GroupedElGamalCiphertext3Handles;
 use {
@@ -158,6 +194,10 @@ pub fn burn_split_proof_data(
         };
 
     // generate range proof data
+
+    // the total bit lengths for the range proof must be a power-of-2
+    // therefore, create a Pedersen commitment to 0 and use it as a dummy commitment to a 16-bit
+    // value
     let (padding_commitment, padding_opening) = Pedersen::new(0_u64);
     let range_proof_data = BatchedRangeProofU128Data::new(
         vec![

confidential-transfer/proof-generation/src/mint.rs

@@ -1,3 +1,39 @@
+//! Generates the zero-knowledge proofs required for a confidential mint.
+//!
+//! A confidential mint operation increases the total supply of a token and deposits the newly
+//! created tokens into a user's confidential account. This process requires three distinct
+//! zero-knowledge proofs:
+//!
+//! ## Protocol Flow and Proof Components
+//!
+//! 1.  **Encrypt Mint Amount**: The mint amount is encrypted in a grouped (twisted) ElGamal
+//!     ciphertext. This single cryptographic operation prepares the mint amount to be simultaneously
+//!     added to the destination account's balance and the mint's total supply. It also includes an
+//!     encryption for an optional auditor.
+//!
+//! 2.  **Homomorphic Calculation**: The client homomorphically computes the new encrypted total supply
+//!     by adding the supply-encrypted component of the mint amount to the mint's current
+//!     `confidential_supply` ciphertext.
+//!
+//! 3.  **Generate Proofs**: The user with mint authority generates three proofs:
+//!
+//!     -   **Batched Grouped Ciphertext Validity Proof**:
+//!         This proof certifies that the grouped ElGamal ciphertext for the `mint_amount` is well-formed
+//!         and was correctly encrypted for the destination, supply, and auditor public keys.
+//!
+//!     -   **Ciphertext-Commitment Equality Proof**:
+//!         This proof provides a cryptographic link that enables the total supply to be range-checked.
+//!         When the `new_supply_ciphertext` is computed homomorphically, the prover no longer knows
+//!         the associated Pedersen opening (randomness). To perform a range proof, the prover creates a
+//!         *new* Pedersen commitment for the `new_supply` value (for which they know the opening) and
+//!         uses this proof to certify that the ciphertext and the new commitment hide the same value.
+//!
+//!     -   **Range Proof (`BatchedRangeProofU128`)**:
+//!         This proof ensures supply integrity. It certifies that the `mint_amount` is a valid
+//!         48-bit number and, crucially, that the `new_supply` does not exceed the 64-bit limit.
+//!         This makes it cryptographically impossible to mint tokens in a way that would cause the
+//!         total supply to overflow.
+
 #[cfg(target_arch = "wasm32")]
 use solana_zk_sdk::encryption::grouped_elgamal::GroupedElGamalCiphertext3Handles;
 use {
@@ -152,6 +188,10 @@ pub fn mint_split_proof_data(
         };
 
     // generate range proof data
+
+    // the total bit lengths for the range proof must be a power-of-2
+    // therefore, create a Pedersen commitment to 0 and use it as a dummy commitment to a 16-bit
+    // value
     let (padding_commitment, padding_opening) = Pedersen::new(0_u64);
     let range_proof_data = BatchedRangeProofU128Data::new(
         vec![

confidential-transfer/proof-generation/src/transfer.rs

@@ -1,3 +1,44 @@
+//! Generates the zero-knowledge proofs required for a confidential transfer.
+//!
+//! A confidential transfer requires a composition of three distinct zero-knowledge proofs to ensure
+//! correctness and security. This function orchestrates their generation.
+//!
+//! ## Protocol Flow and Proof Components
+//!
+//! 1.  **Encrypt Transfer Amount**: The transfer amount is split into low (16-bit) and high (32-bit)
+//!     components. This is done to facilitate efficient decryption, which would otherwise require
+//!     solving the discrete logarithm problem over the entire 64-bit range. Each component is
+//!     encrypted as a grouped (twisted) ElGamal ciphertext with decryption handles for the source,
+//!     destination, and an optional auditor.
+//!
+//! 2.  **Generate Proofs**: The sender then generates the following proofs in a specific logical order:
+//!
+//!     -   **Ciphertext Validity Proof (`BatchedGroupedCiphertext3HandlesValidityProofData`)**:
+//!         This proof certifies that the grouped ElGamal ciphertexts for the transfer amount are
+//!         well-formed (i.e., they are valid encryptions of the low and high bit components under
+//!         the source, destination, and auditor keys).
+//!
+//!     -   **Range Proof (`BatchedRangeProofU128Data`)**:
+//!         This proof ensures solvency and prevents the creation of tokens. It certifies that:
+//!         1.  The sender's remaining balance is a non-negative 64-bit integer. This is ensures
+//!             that `current_balance >= transfer_amount`.
+//!         2.  The low and high components of the transfer amount are valid 16-bit and 32-bit
+//!             integers, respectively.
+//!
+//!         A range proof can only be generated from a Pedersen commitment for which the prover
+//!         knows the opening. However, a sender does not necessarily know the Pedersen opening
+//!         for the ciphertext associated with the sender's remaining balance ciphertext. This
+//!         this necessitates the ciphertext-commitment equality proof below.
+//!
+//!     -   **Ciphertext-Commitment Equality Proof (`CiphertextCommitmentEqualityProofData`)**:
+//!         We require that the sender create a *new* Pedersen commitment to their known plaintext
+//!         remaining balance. This equality proof then certifies that the homomorphically computed
+//!         `new_balance_ciphertext` and the new Pedersen commitment encrypt/commit to the exact same
+//!         value.
+//!
+//! These three proofs, when verified together, allow the on-chain program to securely process the
+//! confidential transfer.
+
 #[cfg(target_arch = "wasm32")]
 use solana_zk_sdk::encryption::grouped_elgamal::GroupedElGamalCiphertext3Handles;
 use {
@@ -163,6 +204,10 @@ pub fn transfer_split_proof_data(
         };
 
     // generate range proof data
+
+    // the total bit lengths for the range proof must be a power-of-2
+    // therefore, create a Pedersen commitment to 0 and use it as a dummy commitment to a 16-bit
+    // value
     let (padding_commitment, padding_opening) = Pedersen::new(0_u64);
     let range_proof_data = BatchedRangeProofU128Data::new(
         vec![

confidential-transfer/proof-generation/src/transfer_with_fee.rs

@@ -1,3 +1,51 @@
+//! Generates the zero-knowledge proofs required for a confidential transfer with a fee.
+//!
+//! A confidential transfer with a fee is more complex than a simple transfer. It requires five
+//! distinct zero-knowledge proofs to ensure the validity of the transfer, the solvency of the
+//! sender, and the correctness of the fee amount according to the on-chain mint configuration.
+//!
+//! ## Protocol Flow and Proof Components
+//!
+//! 1.  **Fee Calculation**: The client first calculates the required fee based on the transfer
+//!     amount and the on-chain fee parameters (rate and maximum cap).
+//!
+//! 2.  **Encrypt Amounts**: The gross transfer amount and the fee amount are each split into low
+//!     and high bit components. These components are then encrypted into separate grouped (twisted)
+//!     ElGamal ciphertexts with the appropriate decryption handles for the involved parties (source,
+//!     destination, auditor, and withdraw authority).
+//!
+//! 3.  **Generate Proofs**: The sender generates five proofs that work in concert:
+//!
+//!     -   **Transfer Amount Ciphertext Validity Proof
+//!         (`BatchedGroupedCiphertext3HandlesValidityProofData`)**: Certifies that the grouped
+//!         ElGamal ciphertext for the gross transfer amount is well-formed.
+//!
+//!     -   **Fee Ciphertext Validity Proof
+//!         (`BatchedGroupedCiphertext2HandlesValidityProofData`)**: Certifies that the grouped
+//!         ElGamal ciphertext for the transfer fee is well-formed.
+//!
+//!     -   **Fee Calculation Proof (`PercentageWithCapProofData`)**:
+//!         It's a "one-of-two" proof that certifies **either**:
+//!           1. The `fee_amount` is exactly equal to the on-chain `maximum_fee`.
+//!           2. The `fee_amount` was correctly calculated as a percentage of the
+//!              `transfer_amount`, according to the on-chain `fee_rate_basis_points`.
+//!
+//!         **Note**: The proof certifies that the transfer fee is a valid percentage of the
+//!         transfer amount or that the fee is exactly the maximum fee. While the sender is
+//!         expected to choose the lower of these two options, the proof does not enforce this
+//!         choice.
+//!
+//!     -   **Range Proof (`BatchedRangeProofU256Data`)**:
+//!         This expanded range proof ensures the solvency of the entire transaction by certifying
+//!         that all critical monetary values are non-negative. This includes the sender's remaining
+//!         balance, the gross transfer amount, the fee amount, and the net transfer amount that the
+//!         destination receives.
+//!
+//!     -   **Ciphertext-Commitment Equality Proof (`CiphertextCommitmentEqualityProofData`)**:
+//!         Identical in purpose to the simple transfer, this proof links the sender's remaining
+//!         balance (as a homomorphically computed ElGamal ciphertext) to a new Pedersen commitment.
+//!         This commitment is then used in the Range Proof to prove the sender's solvency.
+
 #[cfg(not(target_arch = "wasm32"))]
 use solana_zk_sdk::encryption::grouped_elgamal::GroupedElGamal;
 #[cfg(target_arch = "wasm32")]
@@ -40,11 +88,6 @@ const NET_TRANSFER_AMOUNT_BIT_LENGTH: usize = 64;
 
 /// The proof data required for a confidential transfer instruction when the
 /// mint is extended for fees
-///
-/// NOTE: The proofs certify that the transfer fee is a valid percentage of the
-/// transfer amount, as determined by the fee basis points, or that the fee is
-/// exactly the maximum fee. While the sender is expected to choose the lower of
-/// these two options, the proof does not enforce this choice.
 pub struct TransferWithFeeProofData {
     pub equality_proof_data: CiphertextCommitmentEqualityProofData,
     pub transfer_amount_ciphertext_validity_proof_data_with_ciphertext:
@@ -193,12 +236,16 @@ pub fn transfer_with_fee_split_proof_data(
     // calculate fee
     let transfer_fee_basis_points = fee_rate_basis_points;
     let transfer_fee_maximum_fee = maximum_fee;
-    let (raw_fee_amount, delta_fee) = calculate_fee(transfer_amount, transfer_fee_basis_points)
+    let (raw_fee_amount, raw_delta_fee) = calculate_fee(transfer_amount, transfer_fee_basis_points)
         .ok_or(TokenProofGenerationError::FeeCalculation)?;
 
     // if raw fee is greater than the maximum fee, then use the maximum fee for the
-    // fee amount
-    let fee_amount = std::cmp::min(transfer_fee_maximum_fee, raw_fee_amount);
+    // fee amount and set the claimed delta fee to be 0 for simplicity
+    let (fee_amount, claimed_delta_fee) = if transfer_fee_maximum_fee < raw_fee_amount {
+        (transfer_fee_maximum_fee, 0)
+    } else {
+        (raw_fee_amount, raw_delta_fee)
+    };
     let net_transfer_amount = transfer_amount
         .checked_sub(fee_amount)
         .ok_or(TokenProofGenerationError::FeeCalculation)?;
@@ -249,7 +296,7 @@ pub fn transfer_with_fee_split_proof_data(
     let net_transfer_amount_opening = &combined_transfer_amount_opening - &combined_fee_opening;
 
     // compute claimed and real delta commitment
-    let (claimed_commitment, claimed_opening) = Pedersen::new(delta_fee);
+    let (claimed_commitment, claimed_opening) = Pedersen::new(claimed_delta_fee);
     let (delta_commitment, delta_opening) = compute_delta_commitment_and_opening(
         (
             &combined_transfer_amount_commitment,
@@ -266,7 +313,7 @@ pub fn transfer_with_fee_split_proof_data(
         fee_amount,
         &delta_commitment,
         &delta_opening,
-        delta_fee,
+        claimed_delta_fee,
         &claimed_commitment,
         &claimed_opening,
         transfer_fee_maximum_fee,
@@ -327,7 +374,7 @@ pub fn transfer_with_fee_split_proof_data(
 
     // generate range proof data
     let delta_fee_complement = MAX_FEE_BASIS_POINTS_SUB_ONE
-        .checked_sub(delta_fee)
+        .checked_sub(claimed_delta_fee)
         .ok_or(TokenProofGenerationError::FeeCalculation)?;
 
     let max_fee_basis_points_sub_one_commitment =
@@ -353,7 +400,7 @@ pub fn transfer_with_fee_split_proof_data(
             new_decrypted_available_balance,
             transfer_amount_lo,
             transfer_amount_hi,
-            delta_fee,
+            claimed_delta_fee,
             delta_fee_complement,
             fee_amount_lo,
             fee_amount_hi,

confidential-transfer/proof-generation/src/withdraw.rs

@@ -1,3 +1,37 @@
+//! Generates the zero-knowledge proofs required for a confidential withdraw.
+//!
+//! A confidential withdraw operation converts a user's encrypted, confidential token balance back into a
+//! standard, publicly-visible SPL token balance. To ensure this operation is valid and that a user
+//! cannot create tokens out of thin air, it requires two distinct zero-knowledge proofs.
+//!
+//! ## Protocol Flow and Proof Components
+//!
+//! 1.  **Calculate Remaining Balance**: The client first calculates the remaining confidential balance
+//!     by subtracting the desired `withdraw_amount` from their current known balance.
+//!
+//! 2.  **Homomorphic Calculation**: The client homomorphically computes the new encrypted balance
+//!     ciphertext. This is done by taking the current `available_balance` ciphertext and subtracting
+//!     a newly-encoded ciphertext of the `withdraw_amount`.
+//!
+//! 3.  **Generate Proofs**: The user generates two proofs to certify the validity of the operation:
+//!
+//!     -   **Ciphertext-Commitment Equality Proof (`CiphertextCommitmentEqualityProofData`)**:
+//!         This proof provides a cryptographic link that enables the solvency check. When the
+//!         `remaining_balance_ciphertext` is computed homomorphically, the prover may not know the
+//!         corresponding Pedersen opening (randomness) for the resulting ciphertext. Performing a
+//!         range proof requires knowledge of this opening.
+//!
+//!         To solve this, the prover creates a *new* Pedersen commitment for the remaining balance,
+//!         for which it knows the opening. The equality proof then certifies that the
+//!         homomorphically-derived ciphertext and this new commitment hide the exact same numerical
+//!         value. This allows the range proof to be performed on the new commitment.
+//!
+//!     -   **Range Proof (`BatchedRangeProofU64Data`)**:
+//!         This proof certifies the user's **solvency**. By proving that the value inside the
+//!         Pedersen commitment for the *remaining balance* is non-negative (i.e., it is in the range
+//!         `[0, 2^64)`), it implicitly proves that the user's original balance was greater than or
+//!         equal to the `withdraw_amount`.
+
 use {
     crate::errors::TokenProofGenerationError,
     solana_zk_sdk::{

scripts/solana.dic

@@ -61,3 +61,5 @@ Pedersen
 aes
 plaintext
 pausable
+homomorphic
+homomorphically