feat(multi-collateral): impl apply interests

Author: MohammadNassar1

workspace/apps/perpetuals/contracts/src/core/components/positions/interface.cairo

@@ -48,7 +48,6 @@ pub trait IPositions<TContractState> {
         new_public_key: PublicKey,
         expiration: Timestamp,
     );
-
     fn enable_owner_protection(
         ref self: TContractState,
         operator_nonce: u64,

workspace/apps/perpetuals/contracts/src/core/components/positions/positions.cairo

@@ -48,7 +48,7 @@ pub mod Positions {
         IterableMapIntoIterImpl, IterableMapReadAccessImpl, IterableMapWriteAccessImpl,
     };
     use starkware_utils::storage::utils::AddToStorage;
-    use starkware_utils::time::time::{Timestamp, validate_expiration};
+    use starkware_utils::time::time::{Time, Timestamp, validate_expiration};
     use crate::core::components::snip::SNIP12MetadataImpl;
     use crate::core::errors::{
         INVALID_AMOUNT_SIGN, INVALID_BASE_CHANGE, INVALID_SAME_POSITIONS, INVALID_ZERO_AMOUNT,
@@ -185,9 +185,11 @@ pub mod Positions {
             let mut position = self.positions.entry(position_id);
             assert(position.version.read().is_zero(), POSITION_ALREADY_EXISTS);
             assert(owner_public_key.is_non_zero(), INVALID_ZERO_PUBLIC_KEY);
+            let current_time = Time::now();
             position.version.write(POSITION_VERSION);
             position.owner_public_key.write(owner_public_key);
             position.owner_protection_enabled.write(owner_protection_enabled);
+            position.last_interest_applied_time.write(current_time);
             if owner_account.is_non_zero() {
                 position.owner_account.write(Option::Some(owner_account));
             }

workspace/apps/perpetuals/contracts/src/core/core.cairo

@@ -1,7 +1,7 @@
 #[starknet::contract]
 pub mod Core {
     use core::dict::{Felt252Dict, Felt252DictTrait};
-    use core::num::traits::Zero;
+    use core::num::traits::{Pow, Zero};
     use core::panic_with_felt252;
     use openzeppelin::access::accesscontrol::AccessControlComponent;
     use openzeppelin::interfaces::erc20::IERC20DispatcherTrait;
@@ -18,8 +18,9 @@ pub mod Core {
         FEE_POSITION, InternalTrait as PositionsInternalTrait,
     };
     use perpetuals::core::errors::{
-        AMOUNT_OVERFLOW, FORCED_WAIT_REQUIRED, INVALID_ZERO_TIMEOUT, LENGTH_MISMATCH,
-        ORDER_IS_NOT_EXPIRED, TRADE_ASSET_NOT_SYNTHETIC, TRANSFER_FAILED,
+        AMOUNT_OVERFLOW, FORCED_WAIT_REQUIRED, INVALID_INTEREST_RATE, INVALID_ZERO_TIMEOUT,
+        LENGTH_MISMATCH, ORDER_IS_NOT_EXPIRED, TRADE_ASSET_NOT_SYNTHETIC, TRANSFER_FAILED,
+        ZERO_MAX_INTEREST_RATE,
     };
     use perpetuals::core::events;
     use perpetuals::core::interface::{ICore, Settlement};
@@ -45,6 +46,8 @@ pub mod Core {
     use starkware_utils::components::roles::RolesComponent::InternalTrait as RolesInternal;
     use starkware_utils::components::roles::interface::IRoles;
     use starkware_utils::hash::message_hash::OffchainMessageHash;
+    use starkware_utils::math::abs::Abs;
+    use starkware_utils::math::utils::mul_wide_and_floor_div;
     use starkware_utils::signature::stark::{PublicKey, Signature};
     use starkware_utils::storage::iterable_map::{
         IterableMapIntoIterImpl, IterableMapReadAccessImpl, IterableMapWriteAccessImpl,
@@ -161,6 +164,10 @@ pub mod Core {
         forced_action_timelock: TimeDelta,
         // Cost for executing forced actions.
         premium_cost: u64,
+        // Maximum interest rate per second (32-bit fixed-point with 32-bit fractional part).
+        // Example: max_interest_rate_per_sec = 1000000 means the rate is 1000000 / 2^32 ≈
+        // 0.000232 per second, which is approximately 7.3% per year.
+        max_interest_rate_per_sec: u32,
     }
 
     #[event]
@@ -226,6 +233,7 @@ pub mod Core {
         insurance_fund_position_owner_public_key: PublicKey,
         forced_action_timelock: u64,
         premium_cost: u64,
+        max_interest_rate_per_sec: u32,
     ) {
         self.roles.initialize(:governance_admin);
         self.replaceability.initialize(:upgrade_delay);
@@ -248,6 +256,8 @@ pub mod Core {
         assert(forced_action_timelock.is_non_zero(), INVALID_ZERO_TIMEOUT);
         self.forced_action_timelock.write(TimeDelta { seconds: forced_action_timelock });
         self.premium_cost.write(premium_cost);
+        assert(max_interest_rate_per_sec.is_non_zero(), ZERO_MAX_INTEREST_RATE);
+        self.max_interest_rate_per_sec.write(max_interest_rate_per_sec);
     }
 
     #[abi(embed_v0)]
@@ -953,6 +963,36 @@ pub mod Core {
                     },
                 );
         }
+        fn apply_interests(
+            ref self: ContractState,
+            operator_nonce: u64,
+            position_ids: Span<PositionId>,
+            interest_amounts: Span<i64>,
+        ) {
+            assert(position_ids.len() == interest_amounts.len(), LENGTH_MISMATCH);
+            self.pausable.assert_not_paused();
+            self.assets.validate_assets_integrity();
+            self.operator_nonce.use_checked_nonce(:operator_nonce);
+
+            // Read once and pass as arguments to avoid redundant storage reads
+            let current_time = Time::now();
+            let max_interest_rate_per_sec = self.max_interest_rate_per_sec.read();
+            let interest_rate_scale: u64 = 2_u64.pow(32);
+
+            let mut i: usize = 0;
+            for position_id in position_ids {
+                let interest_amount = *interest_amounts[i];
+                self
+                    ._apply_interest_to_position(
+                        position_id: *position_id,
+                        :interest_amount,
+                        :current_time,
+                        :max_interest_rate_per_sec,
+                        :interest_rate_scale,
+                    );
+                i += 1;
+            }
+        }
     }
 
     #[generate_trait]
@@ -1106,5 +1146,66 @@ pub mod Core {
         fn _is_vault(ref self: ContractState, vault_position: PositionId) -> bool {
             self.vaults.is_vault_position(vault_position)
         }
+
+        fn _apply_interest_to_position(
+            ref self: ContractState,
+            position_id: PositionId,
+            interest_amount: i64,
+            current_time: Timestamp,
+            max_interest_rate_per_sec: u32,
+            interest_rate_scale: u64,
+        ) {
+            // Check that position exists
+            let position = self.positions.get_position_mut(:position_id);
+
+            // Get old balance and last interest applied time
+            let old_balance = position.collateral_balance.read();
+            let previous_timestamp = position.last_interest_applied_time.read();
+
+            // Calculate new balance
+            let new_balance = old_balance + interest_amount.into();
+
+            // Validate interest rate
+            let old_balance_value: i64 = old_balance.into();
+            if old_balance_value.is_non_zero() && previous_timestamp.is_non_zero() {
+                // Calculate time difference
+                let time_diff: u64 = if current_time.seconds >= previous_timestamp.seconds {
+                    current_time.seconds - previous_timestamp.seconds
+                } else {
+                    // If current time is before previous time, something is wrong
+                    panic_with_felt252('INVALID_TIMESTAMP');
+                };
+
+                // Calculate maximum allowed change: |old_balance| * time_diff *
+                // max_interest_rate_per_sec / 2^32 Formula: |interest_amount| <= |old_balance| *
+                // time_diff * max_interest_rate_per_sec / 2^32
+                let old_balance_abs: u128 = old_balance_value.abs().into();
+                let max_rate: u128 = max_interest_rate_per_sec.into();
+                let time_diff_u128: u128 = time_diff.into();
+                // Calculate: (|old_balance| * time_diff * max_interest_rate_per_sec) / 2^32
+                // To preserve precision, multiply all factors first, then divide.
+                // Use mul_wide_and_floor_div to safely compute (balance * time_diff * max_rate) /
+                // scale which handles wide multiplication to avoid overflow.
+                let balance_time_product = old_balance_abs * time_diff_u128;
+                let max_allowed_change = mul_wide_and_floor_div(
+                    balance_time_product, max_rate, interest_rate_scale.into(),
+                )
+                    .expect(AMOUNT_OVERFLOW);
+
+                // Check: |interest_amount| <= max_allowed_change
+                let interest_amount_abs: u128 = interest_amount.abs().into();
+                assert(interest_amount_abs <= max_allowed_change, INVALID_INTEREST_RATE);
+
+                // Apply interest
+                position.collateral_balance.write(new_balance);
+            } else {
+                // If old balance is zero, only allow zero interest.
+                // If `prev_ts` is zero, this indicates the first interest calculation, and the
+                // interest amount is required to be zero.
+                assert(interest_amount.is_zero(), INVALID_INTEREST_RATE);
+            }
+
+            position.last_interest_applied_time.write(current_time);
+        }
     }
 }

workspace/apps/perpetuals/contracts/src/core/errors.cairo

@@ -25,6 +25,8 @@ pub const TRANSFER_FAILED: felt252 = 'TRANSFER_FAILED';
 pub const SAME_BASE_QUOTE_ASSET_IDS: felt252 = 'SAME_BASE_QUOTE_ASSET_IDS';
 pub const ORDER_IS_NOT_EXPIRED: felt252 = 'ORDER_IS_NOT_EXPIRED';
 pub const LENGTH_MISMATCH: felt252 = 'LENGTH_MISMATCH';
+pub const INVALID_INTEREST_RATE: felt252 = 'INVALID_INTEREST_RATE';
+pub const ZERO_MAX_INTEREST_RATE: felt252 = 'ZERO_MAX_INTEREST_RATE';
 
 pub fn fulfillment_exceeded_err(position_id: PositionId) -> ByteArray {
     format!("FULFILLMENT_EXCEEDED position_id: {:?}", position_id)

workspace/apps/perpetuals/contracts/src/core/interface.cairo

@@ -166,4 +166,10 @@ pub trait ICore<TContractState> {
         order_b: Order,
     );
     fn forced_trade(ref self: TContractState, order_a: Order, order_b: Order);
+    fn apply_interests(
+        ref self: TContractState,
+        operator_nonce: u64,
+        position_ids: Span<PositionId>,
+        interest_amounts: Span<i64>,
+    );
 }

workspace/apps/perpetuals/contracts/src/core/types/position.cairo

@@ -9,6 +9,7 @@ use starkware_utils::signature::stark::PublicKey;
 use starkware_utils::storage::iterable_map::{
     IterableMap, IterableMapIntoIterImpl, IterableMapReadAccessImpl, IterableMapWriteAccessImpl,
 };
+use starkware_utils::time::time::Timestamp;
 
 pub const POSITION_VERSION: u8 = 1;
 
@@ -21,6 +22,7 @@ pub struct Position {
     #[rename("synthetic_balance")]
     pub asset_balances: IterableMap<AssetId, AssetBalance>,
     pub owner_protection_enabled: bool,
+    pub last_interest_applied_time: Timestamp,
 }
 
 /// Synthetic asset in a position.

workspace/apps/perpetuals/contracts/src/tests/constants.cairo

@@ -81,6 +81,7 @@ pub const SYNTHETIC_BALANCE_AMOUNT: i64 = 20;
 pub const CONTRACT_INIT_BALANCE: u128 = 1_000_000_000;
 pub const USER_INIT_BALANCE: u128 = 10_000_000_000;
 pub const VAULT_SHARE_QUANTUM: u64 = 1_000;
+pub const MAX_INTEREST_RATE_PER_SEC: u32 = 1200; // 0.1% per hour.
 
 pub const POSITION_ID_100: PositionId = PositionId { value: 100 };
 pub const POSITION_ID_200: PositionId = PositionId { value: 200 };

workspace/apps/perpetuals/contracts/src/tests/flow_tests/perps_tests_facade.cairo

@@ -264,6 +264,7 @@ struct PerpetualsConfig {
     insurance_fund_position_owner_public_key: PublicKey,
     forced_action_timelock: u64,
     premium_cost: u64,
+    max_interest_rate_per_sec: u32,
 }
 
 #[generate_trait]
@@ -290,6 +291,7 @@ pub impl PerpetualsConfigImpl of PerpetualsConfigTrait {
             insurance_fund_position_owner_public_key: operator.key_pair.public_key,
             forced_action_timelock: FORCED_ACTION_TIMELOCK,
             premium_cost: PREMIUM_COST,
+            max_interest_rate_per_sec: MAX_INTEREST_RATE_PER_SEC,
         }
     }
 }
@@ -311,6 +313,7 @@ impl PerpetualsContractStateImpl of Deployable<PerpetualsConfig, ContractAddress
         self.insurance_fund_position_owner_public_key.serialize(ref calldata);
         self.forced_action_timelock.serialize(ref calldata);
         self.premium_cost.serialize(ref calldata);
+        self.max_interest_rate_per_sec.serialize(ref calldata);
 
         let perpetuals_contract = snforge_std::declare("Core").unwrap().contract_class();
         let (address, _) = perpetuals_contract.deploy(@calldata).unwrap();

workspace/apps/perpetuals/contracts/src/tests/test_utils.cairo

@@ -47,7 +47,7 @@ use crate::core::components::external_components::interface::{
     EXTERNAL_COMPONENT_WITHDRAWALS, IExternalComponents, IExternalComponentsDispatcher,
     IExternalComponentsDispatcherTrait,
 };
-use super::constants::{FORCED_ACTION_TIMELOCK, PREMIUM_COST};
+use super::constants::{FORCED_ACTION_TIMELOCK, MAX_INTEREST_RATE_PER_SEC, PREMIUM_COST};
 
 /// The `User` struct represents a user corresponding to a position in the state of the Core
 /// contract.
@@ -148,6 +148,7 @@ pub struct PerpetualsInitConfig {
     pub insurance_fund_position_owner_public_key: felt252,
     pub forced_action_timelock: u64,
     pub premium_cost: u64,
+    pub max_interest_rate_per_sec: u32,
     pub collateral_cfg: CollateralCfg,
     pub synthetic_cfg: SyntheticCfg,
     pub vault_share_cfg: VaultCollateralCfg,
@@ -171,6 +172,7 @@ pub impl CoreImpl of CoreTrait {
         self.insurance_fund_position_owner_public_key.serialize(ref calldata);
         self.forced_action_timelock.serialize(ref calldata);
         self.premium_cost.serialize(ref calldata);
+        self.max_interest_rate_per_sec.serialize(ref calldata);
 
         let core_contract = snforge_std::declare("Core").unwrap().contract_class();
         let (core_contract_address, _) = core_contract.deploy(@calldata).unwrap();
@@ -223,6 +225,7 @@ impl PerpetualsInitConfigDefault of Default<PerpetualsInitConfig> {
             insurance_fund_position_owner_public_key: OPERATOR_PUBLIC_KEY(),
             forced_action_timelock: FORCED_ACTION_TIMELOCK,
             premium_cost: PREMIUM_COST,
+            max_interest_rate_per_sec: MAX_INTEREST_RATE_PER_SEC,
             collateral_cfg: CollateralCfg {
                 token_cfg: TokenConfig {
                     name: COLLATERAL_NAME(),
@@ -720,6 +723,7 @@ pub fn initialized_contract_state(
         insurance_fund_position_owner_public_key: OPERATOR_PUBLIC_KEY(),
         forced_action_timelock: FORCED_ACTION_TIMELOCK,
         premium_cost: PREMIUM_COST,
+        max_interest_rate_per_sec: MAX_INTEREST_RATE_PER_SEC,
     );
     state
 }