Merge pull request #191 from chigozirim007/feature/frontloaded-vesting-curves

Add front-loaded exponential decay vesting curve

Author: JerryIdoko

contracts/vesting_curves/README.md

@@ -1,16 +1,18 @@
 ---
 
 ### Summary  
-Introduces the `VestingCurve` enum to support both **Linear** and **Exponential** vesting schedules in the Vesting Vault contract. This enhancement allows flexible release patterns, enabling either steady vesting or a slow-start/accelerated curve, while ensuring correctness through unit and integration tests.  
+Introduces the `VestingCurve` enum to support **Linear**, **Exponential**, and **ExponentialDecay** vesting schedules in the Vesting Vault contract. This enhancement allows flexible release patterns, enabling steady vesting, a slow-start/accelerated curve, or a front-loaded decay curve while ensuring correctness through unit and integration tests.  
 
 ### Key Features  
 * **VestingCurve Enum**:  
   - `Linear`: vested = total × elapsed ÷ duration  
   - `Exponential`: vested = total × elapsed² ÷ duration²  
+  - `ExponentialDecay`: vested = total - (total × remaining² ÷ duration²)  
 * **Function Dispatch**: `vested_amount`, `claim`, and `status` now branch on curve type.  
 * **Mathematical Behavior**:  
   - Linear: proportional vesting (50% time → 50% tokens).  
   - Exponential: slower start, faster finish (50% time → 25% tokens).  
+  - ExponentialDecay: faster start, slower finish (50% time → 75% tokens).  
 * **Immutable Curve**: Curve set at `initialize()` and cannot be changed mid-schedule.  
 * **Incremental Claim Guard**: Ensures multiple claims sum correctly regardless of curve.  
 * **Testing**: 11 unit + integration tests validating math, claims, and curve behavior.  
@@ -20,18 +22,18 @@ Introduces the `VestingCurve` enum to support both **Linear** and **Exponential*
    - ✅ All 11 tests should pass, covering both Linear and Exponential curves.  
 2. Build the WASM binary: `stellar contract build`.  
 3. Deploy to Stellar Testnet with `stellar contract deploy`.  
-4. Initialize vaults with `--curve '{"Linear": {}}'` and `--curve '{"Exponential": {}}'`.  
+4. Initialize vaults with `--curve '{"Linear": {}}'`, `--curve '{"Exponential": {}}'`, or `--curve '{"ExponentialDecay": {}}'`.  
 5. Invoke `get_curve` to confirm correct variant.  
-6. Check `vested_amount` at 50% elapsed: Linear → 50%, Exponential → 25%.  
+6. Check `vested_amount` at 50% elapsed: Linear → 50%, Exponential → 25%, ExponentialDecay → 75%.  
 7. Use `claim` to verify incremental transfers.  
 
 ### Checklist  
-- [x] Add `VestingCurve` enum with Linear & Exponential variants  
+- [x] Add `VestingCurve` enum with Linear, Exponential, & ExponentialDecay variants  
 - [x] Update `vested_amount`, `claim`, and `status` to dispatch on curve  
 - [x] Ensure integer-only math with `u128` intermediates  
 - [x] Enforce immutable curve at initialization  
 - [x] Implement incremental claim logic  
-- [x] Write 11 unit/integration tests for both curves  
+- [x] Write unit/integration tests for all curve variants  
 - [x] Build & deploy WASM contract to Stellar Testnet
 
 ---

contracts/vesting_curves/contracts/vesting-vault/src/lib.rs

@@ -24,6 +24,7 @@ const MAX_DURATION: u64 = 315_360_000;
 pub enum VestingCurve {
     Linear,
     Exponential,
+    ExponentialDecay,
 }
 
 // ---------------------------------------------------------------------------
@@ -100,21 +101,46 @@ impl VestingVault {
             return total; // fully vested
         }
 
+        let elapsed_u128 = elapsed as u128;
+        let duration_u128 = duration as u128;
+        let duration_sq = duration_u128 * duration_u128;
+
         match curve {
             VestingCurve::Linear => (total * elapsed as i128) / duration as i128,
             VestingCurve::Exponential => {
-                let elapsed_u128  = elapsed as u128;
-                let duration_u128 = duration as u128;
-                let total_u128    = total as u128;
-
-                let numerator   = total_u128 * elapsed_u128 * elapsed_u128;
-                let denominator = duration_u128 * duration_u128;
-
-                (numerator / denominator) as i128
+                let elapsed_sq = elapsed_u128 * elapsed_u128;
+                Self::mul_fraction(total, elapsed_sq, duration_sq)
+            }
+            VestingCurve::ExponentialDecay => {
+                let remaining = duration - elapsed;
+                let remaining_u128 = remaining as u128;
+                let remaining_sq = remaining_u128 * remaining_u128;
+
+                // Front-loaded vesting: the locked portion decays quadratically,
+                // so the initial release rate is high and slows over time.
+                total - Self::mul_fraction(total, remaining_sq, duration_sq)
             }
         }
     }
 
+    fn mul_fraction(total: i128, numerator: u128, denominator: u128) -> i128 {
+        assert!(denominator > 0, "denominator must be positive");
+        assert!(numerator <= denominator, "fraction must be <= 1");
+
+        let total_u128 = total as u128;
+
+        // For the vesting curves here numerator <= denominator, which lets us
+        // decompose the multiplication without overflowing u128 while still
+        // preserving floor(total * numerator / denominator) exactly.
+        let quotient = total_u128 / denominator;
+        let remainder = total_u128 % denominator;
+
+        let whole = quotient * numerator;
+        let fractional = (remainder * numerator) / denominator;
+
+        (whole + fractional) as i128
+    }
+
     // -----------------------------------------------------------------------
     // Claim
     // -----------------------------------------------------------------------

contracts/vesting_curves/contracts/vesting-vault/src/test.rs

@@ -148,6 +148,52 @@ fn e6_expo_after_end_capped_at_full() {
     assert_eq!(vested_at(&s.env, &s.vault, START + DURATION + 5000), TOTAL);
 }
 
+// ── Exponential Decay ───────────────────────────────────────────────────────
+
+#[test]
+fn d1_decay_at_start_is_zero() {
+    let s = create_setup(VestingCurve::ExponentialDecay);
+    assert_eq!(vested_at(&s.env, &s.vault, START), 0);
+}
+
+#[test]
+fn d2_decay_at_quarter_is_43_75_percent() {
+    let s = create_setup(VestingCurve::ExponentialDecay);
+    let elapsed = DURATION / 4;
+    let remaining = DURATION - elapsed;
+    let expected = TOTAL
+        - TOTAL * (remaining as i128 * remaining as i128)
+            / (DURATION as i128 * DURATION as i128);
+    let actual = vested_at(&s.env, &s.vault, START + elapsed);
+    assert_eq!(actual, expected, "decay 25% elapsed failed: got {actual}");
+}
+
+#[test]
+fn d3_decay_at_half_is_seventy_five_percent() {
+    let s = create_setup(VestingCurve::ExponentialDecay);
+    let expected = (TOTAL * 3) / 4; // 1 - 0.5^2 = 0.75
+    let actual = vested_at(&s.env, &s.vault, START + DURATION / 2);
+    assert_eq!(actual, expected, "decay 50% elapsed failed: got {actual}");
+}
+
+#[test]
+fn d4_decay_at_three_quarters_is_93_75_percent() {
+    let s = create_setup(VestingCurve::ExponentialDecay);
+    let elapsed = (DURATION * 3) / 4;
+    let remaining = DURATION - elapsed;
+    let expected = TOTAL
+        - TOTAL * (remaining as i128 * remaining as i128)
+            / (DURATION as i128 * DURATION as i128);
+    let actual = vested_at(&s.env, &s.vault, START + elapsed);
+    assert_eq!(actual, expected, "decay 75% elapsed failed: got {actual}");
+}
+
+#[test]
+fn d5_decay_at_end_is_full() {
+    let s = create_setup(VestingCurve::ExponentialDecay);
+    assert_eq!(vested_at(&s.env, &s.vault, START + DURATION), TOTAL);
+}
+
 // ── Comparison ──────────────────────────────────────────────────────────────
 
 #[test]
@@ -165,6 +211,21 @@ fn c1_at_midpoint_exponential_less_than_linear() {
     );
 }
 
+#[test]
+fn c2_at_midpoint_decay_greater_than_linear() {
+    let sl = create_setup(VestingCurve::Linear);
+    let sd = create_setup(VestingCurve::ExponentialDecay);
+    let mid = START + DURATION / 2;
+
+    let linear_mid = vested_at(&sl.env, &sl.vault, mid);
+    let decay_mid = vested_at(&sd.env, &sd.vault, mid);
+
+    assert!(
+        decay_mid > linear_mid,
+        "Expected decay ({decay_mid}) > linear ({linear_mid}) at midpoint"
+    );
+}
+
 // ── Integration tests ────────────────────────────────────────────────────────
 
 #[test]
@@ -203,9 +264,11 @@ fn i2_exponential_claim_at_three_quarters() {
 fn i3_get_curve_returns_correct_variant() {
     let sl = create_setup(VestingCurve::Linear);
     let se = create_setup(VestingCurve::Exponential);
+    let sd = create_setup(VestingCurve::ExponentialDecay);
 
     assert_eq!(sl.vault.get_curve(), VestingCurve::Linear);
     assert_eq!(se.vault.get_curve(), VestingCurve::Exponential);
+    assert_eq!(sd.vault.get_curve(), VestingCurve::ExponentialDecay);
 }
 
 #[test]
@@ -255,6 +318,30 @@ fn i6_double_claim_only_yields_incremental_amount() {
     assert_eq!(bal, TOTAL);
 }
 
+#[test]
+fn i7_decay_double_claim_only_yields_incremental_amount() {
+    let s = create_setup(VestingCurve::ExponentialDecay);
+
+    // First claim at 25 %
+    let elapsed = DURATION / 4;
+    s.env.ledger().with_mut(|l| l.timestamp = START + elapsed);
+    let first_claim = s.vault.claim();
+    assert_eq!(first_claim, 437_500_000);
+
+    // Advance to 50 %
+    s.env.ledger().with_mut(|l| l.timestamp = START + DURATION / 2);
+    let second_claim = s.vault.claim();
+    assert_eq!(second_claim, 312_500_000);
+
+    // Advance to 100 %
+    s.env.ledger().with_mut(|l| l.timestamp = START + DURATION);
+    let third_claim = s.vault.claim();
+    assert_eq!(third_claim, 250_000_000);
+
+    let bal = TokenClient::new(&s.env, &s.token).balance(&s.beneficiary);
+    assert_eq!(bal, TOTAL);
+}
+
 // ── Zero-duration / zero-amount edge cases (Issue #41) ──────────────────────
 
 #[test]
@@ -349,7 +436,7 @@ fn z3_zero_duration_exponential_panics() {
 // ── Duration cap (Issue #44) ────────────────────────────────────────────────
 
 #[test]
-fn i7_initialize_allows_max_duration() {
+fn i8_initialize_allows_max_duration() {
     let env = Env::default();
     env.mock_all_auths();
 
@@ -382,7 +469,7 @@ fn i7_initialize_allows_max_duration() {
 
 #[test]
 #[should_panic(expected = "duration exceeds MAX_DURATION")]
-fn i8_initialize_rejects_duration_over_max() {
+fn i9_initialize_rejects_duration_over_max() {
     let env = Env::default();
     env.mock_all_auths();