feat(ISwapExecutor): Add ISwapExecutor and docs

docs/README.md

@@ -25,3 +25,7 @@ While VM integration is certainly the quickest and probably most accessible one
 For indexing purposes, it is required that you provide a [substreams](https://substreams.streamingfast.io/) package that emits a specified set of messages. If your protocol already has a [substreams package](https://github.com/messari/substreams) for indexing implemented, you can adjust it to emit the required messages.
 
 **VM Integration** Currently the only supported integration is for EVM protocols in order to complement the Solidity protocol logic. [**Read more here.**](https://github.com/propeller-heads/propeller-venue-lib/blob/main/docs/indexing/vm-integration/README.md) **Custom Entity Integration** Coming soon, this integration will complement the upcoming native Rust protocol logic.
+
+### Execution
+
+The execution component involves the implementation of the `SwapExecutor` interface, enabling token swaps within the protocol. The `SwapExecutor` is responsible for performing swaps by interacting with the underlying liquidity pools, handling token approvals, managing input/output amounts, and ensuring gas-efficient and secure execution. Each protocol must implement its own `SwapExecutor`, tailored to its specific logic and requirements.

docs/SUMMARY.md

@@ -15,3 +15,6 @@
 - [VM Integration](indexing/vm-integration/README.md)
 - [Native Integration](indexing/native-integration.md)
 - [Reserved Attributes](indexing/reserved-attributes.md)
+
+## Execution
+- [Swap Executor](execution/swap-executor.md)

docs/execution/swap-executor.md

@@ -0,0 +1,40 @@
+# Implementing a SwapExecutor for a Protocol
+
+## Overview
+
+The `ISwapExecutor` interface is designed to perform swaps on a liquidity pool. 
+It allows for flexible interaction by accepting either the amount of the input token or the amount of the output token 
+as parameters, returning the corresponding swapped amount. 
+This interface is essential for creating a `SwapExecutor` specific to a protocol.
+
+## Key Methods
+
+- **swap(uint256 givenAmount, bytes calldata data)**
+  - **Purpose**: To perform a token swap, either specifying the input amount to get the output amount or vice versa.
+  - **Parameters**:
+    - `givenAmount`: The amount of the token (input or output) for the swap.
+    - `data`: Encoded information necessary for the swap (e.g., pool address, token addresses - depends on the protocol).
+  - **Returns**: The amount of the token swapped.
+
+## Implementation Steps
+
+1. **Define Protocol-Specific Logic**: Implement the `swap` function to interact with the protocol's liquidity pool. 
+Use the `data` parameter to encode necessary information like pool and token addresses.
+2. **Handling Input and Output**: Depending on the provided `givenAmount`, determine whether it's an input or output 
+swap. Calculate the corresponding swapped amount based on the pool's pricing logic.
+3. **Error Handling**: Use `ISwapExecutorErrors` (`InvalidParameterLength` and `UnknownPoolType`) to manage potential 
+errors, such as invalid parameter lengths or unknown pool types in the swap logic.
+4. **Token Approvals**: If the protocol requires token approvals (allowances) before swaps can occur, 
+manage these approvals within the implementation to ensure smooth execution of the swap.
+5. **Token Transfer Support**: Ensure that the implementation supports transferring received tokens to a designated 
+receiver address, either within the swap function or through an additional transfer step.
+6. **Gas Efficiency**: Ensure the implementation is gas-efficient, ideally using assembly where possible, 
+though it is not mandatory. Strive for optimal performance in the swap logic
+7. **Security Considerations**: Follow common security best practices, such as validating inputs, ensuring proper 
+access control, and safeguarding against reentrancy attacks.
+
+
+
+## Example Implementation
+
+See the example implementation of a `SwapExecutor` for Balancer here (TODO: paste link)

docs/logic/vm-integration/README.md

@@ -40,7 +40,7 @@ Following exchanges have been integrated using VM approach:
 
 ### Understanding the ISwapAdapter
 
-Read the the documentation of the [Ethereum Solidity interface](ethereum-solidity.md). It describes the functions that need to be implemented as well as the manifest file. Additionally read through the docstring of the [ISwapAdapter.sol](https://github.com/propeller-heads/propeller-venue-lib/blob/main/evm/src/interfaces/ISwapAdapter.sol) interface and the [ISwapAdapterTypes.sol](https://github.com/propeller-heads/propeller-venue-lib/blob/main/evm/src/interfaces/ISwapAdapterTypes.sol) interface which defines the data types and errors used by the adapter interface. You can also generate the documentation locally and the look at the generated documentation in the `./docs` folder:
+Read the documentation of the [Ethereum Solidity interface](ethereum-solidity.md). It describes the functions that need to be implemented as well as the manifest file. Additionally read through the docstring of the [ISwapAdapter.sol](https://github.com/propeller-heads/propeller-venue-lib/blob/main/evm/src/interfaces/ISwapAdapter.sol) interface and the [ISwapAdapterTypes.sol](https://github.com/propeller-heads/propeller-venue-lib/blob/main/evm/src/interfaces/ISwapAdapterTypes.sol) interface which defines the data types and errors used by the adapter interface. You can also generate the documentation locally and the look at the generated documentation in the `./docs` folder:
 
 ```bash
 cd ./evm/