M README.md → README.md

@@ -3,3 +3,4 @@
 - [aes-gcm](/aes-gcm): Plonky2 circuits for AES & AES-GCM encryption system as described at
 	- AES: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf
 	- AES-GCM (Galois Counter Mode): https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
+- [feistel](/feistel): a Plonky2 library for a finite field analogue of the Feistel cipher as described [here](https://en.wikipedia.org/wiki/Feistel_cipher).

M feistel/src/circuit.rs → feistel/src/circuit.rs

@@ -12,13 +12,16 @@ };
 
 pub(crate) const D: usize = 2;
 
+/// State on which the Feistel-like cipher operates
 #[derive(Debug, Copy, Clone)]
 pub struct FeistelStateTarget<const STATE_LEN: usize>([Target; STATE_LEN]);
 
 pub trait CircuitBuilderFeistel<F: RichField + Extendable<D>, const D: usize> {
+    /// Feistel state target constructor
     fn add_feistel_state_target<const STATE_LEN: usize>(&mut self)
     -> FeistelStateTarget<STATE_LEN>;
 
+    /// Generates Feistel-like cipher as in `crate::feistel_cipher`
     fn feistel_cipher<const STATE_HALF_LEN: usize, const KEY_LEN: usize>(
         &mut self,
         state: FeistelStateTarget<{ 2 * STATE_HALF_LEN }>,
@@ -66,6 +69,7 @@ }
 }
 
 pub trait PartialWitnessFeistel {
+    /// Sets witnesses for a Feistel state target
     fn set_feistel_state_target<const STATE_SIZE: usize>(
         &mut self,
         target: &FeistelStateTarget<STATE_SIZE>,

M feistel/src/lib.rs → feistel/src/lib.rs

@@ -7,6 +7,9 @@ use std::array;
 
 use plonky2::field::types::Field;
 
+/// Feistel-type cipher for finite fields, where XORing is replaced
+/// with addition, cf. https://en.wikipedia.org/wiki/Feistel_cipher or
+/// §3.5.1 of Stinson's Crytography (3rd edition).
 pub fn feistel_cipher<const STATE_HALF_LEN: usize, const KEY_LEN: usize, F: Field>(
     state: [F; 2 * STATE_HALF_LEN],
     key_schedule: &[[F; KEY_LEN]],
@@ -37,6 +40,8 @@ )
     }
 }
 
+/// Feistel-type inverse cipher for finite fields, where XORing is
+/// replaced with subtraction.
 pub fn feistel_inv_cipher<const STATE_HALF_LEN: usize, const KEY_LEN: usize, F: Field>(
     state: [F; 2 * STATE_HALF_LEN],
     reverse_key_schedule: &[[F; KEY_LEN]],