Merge pull request #129 from Great-2025/feature/multi-fee-tier-structure

feat: Scaffold multi-fee tier structure for factory pool creation

Author: AlAfiz

README.md

@@ -8,10 +8,49 @@
 
 ## 🏗 Architecture
 
-The system consists of two decoupled smart contracts:
+The system consists of multiple smart contracts:
 
 1.  **`invoice_nft`**: A standard-compliant NFT representing a verified invoice. It holds metadata (IPFS hash, face value, currency, due date).
 2.  **`lending_pool`**: An escrow vault where liquidity providers deposit stablecoins (USDC). It accepts `invoice_nft` as collateral to automate loan origination and repayment.
+3.  **`factory`**: Factory contract for deploying liquidity pools with specific fee tiers.
+4.  **`amm_pool`**: Automated Market Maker pool contract with configurable fee tiers.
+
+## 💰 Fee Tiers
+
+The Factory contract supports creating pools with different fee tiers to optimize for various token pair characteristics:
+
+| Fee Tier | Basis Points | Percentage | Use Case |
+| :--- | :--- | :--- | :--- |
+| **Stable** | 5 | 0.05% | Stablecoin pairs (USDC/USDT, DAI/USDC) |
+| **Standard** | 30 | 0.30% | Standard token pairs (ETH/USDC, BTC/USDC) |
+| **Volatile** | 100 | 1.00% | Highly volatile exotic pairs |
+
+### Creating a Pool with Specific Fee Tier
+
+```rust
+// Create a stablecoin pool with 0.05% fee
+let pool_address = factory.create_pool(
+    token_a, 
+    token_b, 
+    5  // 5 basis points = 0.05%
+);
+
+// Create a standard pool with 0.30% fee
+let pool_address = factory.create_pool(
+    token_a, 
+    token_b, 
+    30  // 30 basis points = 0.30%
+);
+
+// Create a volatile pool with 1.00% fee
+let pool_address = factory.create_pool(
+    token_a, 
+    token_b, 
+    100  // 100 basis points = 1.00%
+);
+```
+
+**Important:** Only fee tiers of 5, 30, or 100 basis points are supported. Any other value will cause the transaction to fail.
 
 ## 💾 Storage Architecture
 

contracts/amm_pool/src/lib.rs

@@ -13,6 +13,7 @@ pub struct PoolState {
     pub token_b_decimals: u32,
     pub reserve_a: i128,
     pub reserve_b: i128,
+    pub fee_tier: u32, // Fee tier in basis points (5, 30, or 100)
     pub is_deprecated: bool,
     pub _status: u32, // 0 = unlocked, 1 = locked (reentrancy protection)
 }
@@ -28,11 +29,12 @@ pub struct AmmPool;
 
 #[contractimpl]
 impl AmmPool {
-    /// Initialize the AMM pool with two tokens and admin.
+    /// Initialize the AMM pool with two tokens, admin, and fee tier.
     /// 1. Queries the Stellar network to fetch exact decimal precision via Soroban token interface.
     /// 2. Validates that both values are positive integers <= 18.
-    /// 3. Aborts initialization if either token's decimals cannot be determined or are invalid.
-    pub fn init(env: Env, admin: Address, token_a: Address, token_b: Address) {
+    /// 3. Validates fee tier is one of the supported values (5, 30, or 100 basis points).
+    /// 4. Aborts initialization if validation fails.
+    pub fn init(env: Env, admin: Address, token_a: Address, token_b: Address, fee_tier: u32) {
         if env.storage().instance().has(&DataKey::State) {
             panic!("Already initialized");
         }
@@ -50,13 +52,19 @@ impl AmmPool {
             panic!("Invalid decimals for token_b");
         }
 
+        // Validate fee tier
+        if fee_tier != 5 && fee_tier != 30 && fee_tier != 100 {
+            panic!("Invalid fee tier. Only 5, 30, or 100 basis points are supported");
+        }
+
         let state = PoolState {
             token_a,
             token_b,
             token_a_decimals: decimals_a,
             token_b_decimals: decimals_b,
             reserve_a: 0,
             reserve_b: 0,
+            fee_tier,
             is_deprecated: false,
             _status: 0, // Start unlocked
         };

lib.rs

@@ -10,6 +10,7 @@ pub struct Pool {
     pub address: Address,
     pub token_a: Address,
     pub token_b: Address,
+    pub fee_tier: u32, // Fee tier in basis points (5, 30, or 100)
     pub paused: bool,
 }
 
@@ -64,24 +65,33 @@ impl FactoryContract {
         pools.get(sorted_tokens).map(|p| p.address)
     }
 
-    /// Deploys a new liquidity pool for the given token pair.
+    /// Deploys a new liquidity pool for the given token pair with a specific fee tier.
     ///
     /// # Arguments
     /// * `env` - The Soroban environment.
     /// * `token_a` - The first token address.
     /// * `token_b` - The second token address.
+    /// * `fee_tier` - The fee tier in basis points (5, 30, or 100).
     ///
     /// # Returns
     /// The address of the newly deployed pool.
-    pub fn create_pool(env: Env, token_a: Address, token_b: Address) -> Address {
+    ///
+    /// # Panics
+    /// If tokens are the same, pool already exists, or fee_tier is invalid.
+    pub fn create_pool(env: Env, token_a: Address, token_b: Address, fee_tier: u32) -> Address {
         if token_a == token_b {
             panic!("Tokens must be different");
         }
 
+        // Validate fee tier - only allow 5, 30, or 100 basis points
+        if fee_tier != 5 && fee_tier != 30 && fee_tier != 100 {
+            panic!("Invalid fee tier. Only 5, 30, or 100 basis points are supported");
+        }
+
         let (token_0, token_1) = Self::sort_tokens(token_a, token_b);
 
         let mut pools: Map<(Address, Address), Pool> =
-            env.storage().instance().get(&DataKey::Pools).unwrap_or(Map::new(&env));
+            env.storage().instance().get(&DataKey::Pools).unwrap_or_else(|| Map::new(&env));
 
         if pools.contains_key((token_0.clone(), token_1.clone())) {
             panic!("Pool already exists");
@@ -100,11 +110,21 @@ impl FactoryContract {
         // Deploy the new pool contract
         let pool_address = env.deployer().with_current_contract(salt).deploy(wasm_hash);
 
+        // Initialize the pool with the fee tier
+        let init_args = vec![&env, 
+            env.current_contract_address().into_val(&env), // Factory as admin
+            token_0.clone().into_val(&env), 
+            token_1.clone().into_val(&env),
+            fee_tier.into_val(&env)
+        ];
+        env.invoke_contract::<()>(&pool_address, &Symbol::new(&env, "init"), init_args);
+
         // Store the new pool
         let pool = Pool {
             address: pool_address.clone(),
             token_a: token_0.clone(),
             token_b: token_1.clone(),
+            fee_tier,
             paused: false,
         };