79 lines
3.6 KiB
Rust
79 lines
3.6 KiB
Rust
use crate::encoding::{
|
||
errors::EncodingError,
|
||
models::{EncodedSolution, Solution, Transaction},
|
||
};
|
||
|
||
/// A high-level interface for encoding solutions into Tycho-compatible transactions or raw call
|
||
/// data.
|
||
///
|
||
/// This trait is designed to abstract the encoding logic required to prepare swap transactions for
|
||
/// the Tycho Router. It enables modular and customizable construction of transactions, allowing
|
||
/// integrators to maintain full control over the execution constraints.
|
||
///
|
||
/// # User Responsibility
|
||
///
|
||
/// While this trait provides convenience methods, it is **strongly recommended** that users favor
|
||
/// [`encode_solutions`] over [`encode_calldata`]. This is because:
|
||
///
|
||
/// - `encode_solutions` returns raw [`EncodedSolution`] objects, which include Tycho’s swap path
|
||
/// encoding, but leave **function argument encoding entirely in the user’s hands**.
|
||
/// - The function arguments to the router (e.g., `minAmountOut`, `receiver`, `unwrap`, `permit2`,
|
||
/// etc.) are used as **guardrails** to ensure safe on-chain execution.
|
||
/// - Automatically constructing full transactions via [`encode_calldata`] can obscure these
|
||
/// important safeguards and may result in unexpected behavior or vulnerability to MEV.
|
||
///
|
||
/// Tycho is only responsible for generating the internal swap plan. **The user must encode the
|
||
/// outer function call arguments themselves** and verify that they enforce correct and secure
|
||
/// behavior.
|
||
pub trait TychoEncoder {
|
||
/// Encodes a list of [`Solution`]s into [`EncodedSolution`]s, which include the selector and
|
||
/// internal swap call data.
|
||
///
|
||
/// This method gives users maximum flexibility and control. It **does not** produce full
|
||
/// transaction objects. Users are responsible for:
|
||
/// - Constructing the full calldata using their own encoding logic.
|
||
/// - Managing execution-critical parameters like `minAmountOut`.
|
||
///
|
||
/// # Returns
|
||
/// A vector of encoded solutions, each containing:
|
||
/// - The Tycho method selector
|
||
/// - The encoded swap path
|
||
/// - Additional metadata (e.g., permit2 information)
|
||
///
|
||
/// # Recommendation
|
||
/// Use this method if you care about execution safety and want to avoid surprises.
|
||
fn encode_solutions(
|
||
&self,
|
||
solutions: Vec<Solution>,
|
||
) -> Result<Vec<EncodedSolution>, EncodingError>;
|
||
|
||
/// Encodes a list of [`Solution`]s directly into executable transactions for the Tycho router.
|
||
///
|
||
/// This method wraps around Tycho’s example encoding logic (see [`encode_tycho_router_call`])
|
||
/// and should only be used for **prototyping or development**.
|
||
///
|
||
/// # Warning
|
||
/// This implementation uses default logic to construct the outer calldata (e.g., for setting
|
||
/// `minAmountOut`). This might not be optimal or safe for production use.
|
||
///
|
||
/// To ensure correctness, **users should implement their own encoding pipeline** using
|
||
/// [`encode_solutions`].
|
||
///
|
||
/// # Returns
|
||
/// A vector of fully constructed [`Transaction`]s that can be submitted to a node or bundler.
|
||
fn encode_full_calldata(
|
||
&self,
|
||
solutions: Vec<Solution>,
|
||
) -> Result<Vec<Transaction>, EncodingError>;
|
||
|
||
/// Performs solution-level validation and sanity checks.
|
||
///
|
||
/// This function can be used to verify whether a proposed solution is structurally sound and
|
||
/// ready for encoding.
|
||
///
|
||
/// # Returns
|
||
/// - `Ok(())` if the solution is valid.
|
||
/// - `Err(EncodingError)` if the solution is malformed or unsupported.
|
||
fn validate_solution(&self, solution: &Solution) -> Result<(), EncodingError>;
|
||
}
|