From 2b43ecdf29e5034c99cf74df1d0172f6ba42e9eb Mon Sep 17 00:00:00 2001
From: TAMARA LIPOWSKI <data.lipowski@extaccount.com>
Date: Wed, 5 Feb 2025 16:44:28 -0500
Subject: [PATCH] docs: Document validation functions

---
 .../evm/strategy_encoder/strategy_encoders.rs      | 14 ++++++++++++++
 src/encoding/evm/tycho_encoder.rs                  |  9 +++++++++
 2 files changed, 23 insertions(+)

diff --git a/src/encoding/evm/strategy_encoder/strategy_encoders.rs b/src/encoding/evm/strategy_encoder/strategy_encoders.rs
index 4e5a8dd..9016da5 100644
--- a/src/encoding/evm/strategy_encoder/strategy_encoders.rs
+++ b/src/encoding/evm/strategy_encoder/strategy_encoders.rs
@@ -90,6 +90,14 @@ impl SplitSwapStrategyEncoder {
         Ok(Self { permit2: Permit2::new(signer_pk, chain)?, selector, swap_encoder_registry })
     }
 
+    /// Raises an error if the split percentages are invalid.
+    ///
+    /// Split percentages are considered valid of all the following conditions are met:
+    /// * Each split amount is < 1 (100%)
+    /// * There is exactly one 0% split for each token, and it's the last swap specified, signifying
+    ///   to the router to send the remainder of the token to the designated protocol
+    /// * The sum of all non-remainder splits for each token is < 1 (100%)
+    /// * There are no negative split amounts
     fn validate_split_percentages(&self, swaps: &[Swap]) -> Result<(), EncodingError> {
         let mut swaps_by_token: HashMap<Bytes, Vec<&Swap>> = HashMap::new();
         for swap in swaps {
@@ -160,6 +168,12 @@ impl SplitSwapStrategyEncoder {
         Ok(())
     }
 
+    /// Raises an error if swaps do not represent a valid path from the given token to the checked
+    /// token.
+    ///
+    /// A path is considered valid of all the following conditions are met:
+    /// * The checked token is reachable from the given token through the swap path
+    /// * There are tokens which are unconnected from the main path
     fn validate_swap_path(
         &self,
         swaps: &[Swap],
diff --git a/src/encoding/evm/tycho_encoder.rs b/src/encoding/evm/tycho_encoder.rs
index b350956..5cd5d5e 100644
--- a/src/encoding/evm/tycho_encoder.rs
+++ b/src/encoding/evm/tycho_encoder.rs
@@ -32,6 +32,15 @@ impl<S: StrategyEncoderRegistry> EVMTychoEncoder<S> {
 }
 
 impl<S: StrategyEncoderRegistry> EVMTychoEncoder<S> {
+    /// Raises an `EncodingError` if the solution is not considered valid.
+    ///
+    /// A solution is considered valid if all the following conditions are met:
+    /// * The solution is not exact out.
+    /// * The solution has at least one swap.
+    /// * If the solution is wrapping, the given token is the chain's native token and the first
+    ///   swap's input is the chain's wrapped token.
+    /// * If the solution is unwrapping, the checked token is the chain's native token and the last
+    ///   swap's output is the chain's wrapped token.
     fn validate_solution(&self, solution: &Solution) -> Result<(), EncodingError> {
         if solution.exact_out {
             return Err(EncodingError::FatalError(