Updated contract docs for synchronize pull request bugfix/liquidity-deposit-and-borrow-unit-inconsistency

Author: duelinggalois

docs/developer-guide/contracts/AmmalgamPair.sol/contract.AmmalgamPair.md

@@ -1,22 +1,22 @@
 # SaturationAndGeometricTWAPState
-[Git Source](https://github.com/Ammalgam-Protocol/core-v1/blob/82dff11576b9df76b675736dba889653cf737de9/contracts/SaturationAndGeometricTWAPState.sol)
+[Git Source](https://github.com/Ammalgam-Protocol/core-v1/blob/50c2020998f5d2b0b343c9061ad14779312d3011/contracts/SaturationAndGeometricTWAPState.sol)
 
 **Inherits:**
-[ISaturationAndGeometricTWAPState](/docs/developer-guide/contracts/interfaces/ISaturationAndGeometricTWAPState.sol/interface.ISaturationAndGeometricTWAPState.md), Ownable
+Initializable, [ISaturationAndGeometricTWAPState](/docs/developer-guide/contracts/interfaces/ISaturationAndGeometricTWAPState.sol/interface.ISaturationAndGeometricTWAPState.md), OwnableUpgradeable
 
 
 ## State Variables
 ### midTermIntervalConfig
 
 ```solidity
-uint24 public immutable midTermIntervalConfig;
+uint24 public midTermIntervalConfig;
 ```
 
 
 ### longTermIntervalConfig
 
 ```solidity
-uint24 public immutable longTermIntervalConfig;
+uint24 public longTermIntervalConfig;
 ```
 
 
@@ -41,6 +41,13 @@ mapping(address => mapping(address => uint256)) maxNewPositionSaturationInMAG2;
 ```
 
 
+### lastUsedActiveLiquidityInLAssets
+
+```solidity
+mapping(address => mapping(address => uint256)) lastUsedActiveLiquidityInLAssets;
+```
+
+
 ### isPairInitialized
 
 ```solidity
@@ -53,7 +60,14 @@ mapping(address => bool) internal isPairInitialized;
 
 
 ```solidity
-constructor(uint24 _midTermIntervalConfig, uint24 _longTermIntervalConfig) Ownable(msg.sender);
+constructor();
+```
+
+### initialize
+
+
+```solidity
+function initialize(uint24 _midTermIntervalConfig, uint24 _longTermIntervalConfig, address _owner) public initializer;
 ```
 
 ### isInitialized
@@ -78,9 +92,7 @@ initializes the sat and TWAP struct
 
 
 ```solidity
-function init(
-    int16 firstTick
-) external;
+function init(uint256 reserveXAssets, uint256 reserveYAssets) external;
 ```
 
 ### setNewPositionSaturation
@@ -90,28 +102,18 @@ function init(
 function setNewPositionSaturation(address pair, uint256 maxDesiredSaturationMag2) external;
 ```
 
-### getNewPositionSaturation
-
-
-```solidity
-function getNewPositionSaturation(
-    address pair,
-    address account
-) internal view returns (uint256 maxDesiredSaturationInMAG2);
-```
-
 ### getTree
 
 
 ```solidity
 function getTree(address pairAddress, bool netDebtX) private view returns (Saturation.Tree storage);
 ```
 
-### getLeafDetails
+### getTreeLeafDetails
 
 
 ```solidity
-function getLeafDetails(
+function getTreeLeafDetails(
     address pairAddress,
     bool netDebtX,
     uint256 leafIndex
@@ -121,17 +123,12 @@ function getLeafDetails(
     returns (
         Saturation.SaturationPair memory saturation,
         uint256 currentPenaltyInBorrowLSharesPerSatInQ72,
+        uint128 totalSatInLAssets,
+        uint16 highestSetLeaf,
         uint16[] memory tranches
     );
 ```
 
-### getTreeDetails
-
-
-```solidity
-function getTreeDetails(address pairAddress, bool netDebtX) external view returns (uint16, uint128);
-```
-
 ### getTrancheDetails
 
 
@@ -156,28 +153,62 @@ function getAccount(
 
 ### update
 
-update the borrow position of an account and potentially check (and revert) if the resulting sat is too high
+update the borrow position of an account and potentially check (and revert) if the
+resulting sat is too high
 
 *run accruePenalties before running this function*
 
 
 ```solidity
-function update(Validation.InputParams memory inputParams, address account) external virtual;
+function update(
+    Validation.InputParams memory inputParams,
+    address account,
+    bool skipMinOrMaxTickCheck
+) public virtual isInitialized;
 ```
 **Parameters**
 
 |Name|Type|Description|
 |----|----|-----------|
 |`inputParams`|`Validation.InputParams`| contains the position and pair params, like account borrows/deposits, current price and active liquidity|
 |`account`|`address`| for which is position is being updated|
+|`skipMinOrMaxTickCheck`|`bool`||
+
+
+### scaleDesiredSaturation
 
+Scales the desired saturation threshold based on changes in Active Liquidity Assets (ALA).
 
-### _update
+*When liquidity is burned from the pool, ALA decreases. Without scaling, this would cause
+existing positions to appear more saturated (since saturation = borrows / ALA), potentially
+triggering unwarranted liquidation premiums. This function scales the desired saturation
+proportionally to ALA changes to maintain the position's relative health.
+The scaling formula: scaled = lastUsedALA * desiredSat / currentALA*
 
 
 ```solidity
-function _update(Validation.InputParams memory inputParams, address account) internal isInitialized;
+function scaleDesiredSaturation(
+    address pair,
+    address account,
+    uint256 currentALA,
+    bool capAtPenaltyStart
+) internal view returns (uint256 desiredSaturationInMAG2);
 ```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`pair`|`address`|The address of the pair contract.|
+|`account`|`address`|The account whose saturation threshold is being scaled.|
+|`currentALA`|`uint256`|The current active liquidity assets in the pool.|
+|`capAtPenaltyStart`|`bool`|If `true`, caps the scaled value at START_SATURATION_PENALTY_RATIO_IN_MAG2. Used in _update() to prevent excessive. Set to `false` in calcSatChangeRatioBips() for accurate premium calculations.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`desiredSaturationInMAG2`|`uint256`|The scaled desired saturation threshold.|
+
 
 ### accruePenalties
 
@@ -218,7 +249,7 @@ function calcSatChangeRatioBips(
     uint256 liqSqrtPriceInYInQ72,
     address pairAddress,
     address account
-) external view virtual isInitialized returns (uint256 ratioNetXBips, uint256 ratioNetYBips);
+) external view virtual isInitialized returns (uint256 ratioBips);
 ```
 **Parameters**
 
@@ -234,8 +265,7 @@ function calcSatChangeRatioBips(
 
 |Name|Type|Description|
 |----|----|-----------|
-|`ratioNetXBips`|`uint256`|The ratio representing the change in netX saturation for account.|
-|`ratioNetYBips`|`uint256`|The ratio representing the change in netY saturation for account.|
+|`ratioBips`|`uint256`|The ratio representing the change saturation for account.|
 
 
 ### getObservations
@@ -278,7 +308,7 @@ provided block timestamp is less than or equal to the last recorded timestamp.*
 
 
 ```solidity
-function recordObservation(int16 newTick, uint32 timeElapsed) external isInitialized returns (bool);
+function recordObservation(int16 newTick, uint32 timeElapsed) public virtual isInitialized returns (bool);
 ```
 **Parameters**
 
@@ -305,7 +335,8 @@ long-term tick, mid-term tick, and current tick.*
 ```solidity
 function getTickRange(
     address pair,
-    int16 currentTick,
+    uint256 reserveXAssets,
+    uint256 reserveYAssets,
     bool includeLongTermTick
 ) external view virtual returns (int16, int16);
 ```
@@ -314,7 +345,8 @@ function getTickRange(
 |Name|Type|Description|
 |----|----|-----------|
 |`pair`|`address`|The address of the pair for which the tick range is being calculated.|
-|`currentTick`|`int16`|The current (most recent) tick based on the current reserves.|
+|`reserveXAssets`|`uint256`|The current pair reserves of asset X.|
+|`reserveYAssets`|`uint256`|The current pair reserves of asset Y.|
 |`includeLongTermTick`|`bool`|Boolean value indicating whether to include the long-term tick in the range.|
 
 **Returns**
@@ -325,17 +357,6 @@ function getTickRange(
 |`<none>`|`int16`|maxTick The maximum tick value among the three observed ticks.|
 
 
-### _getTickRange
-
-
-```solidity
-function _getTickRange(
-    address pair,
-    int16 currentTick,
-    bool includeLongTermTick
-) internal view returns (int16, int16);
-```
-
 ### getLendingStateTickAndCheckpoint
 
 Gets the tick value representing the TWAP since the last
@@ -390,30 +411,6 @@ function getObservedMidTermTick(
 |`<none>`|`int16`|midTermTick The mid-term tick value.|
 
 
-### boundTick
-
-*The function ensures that `newTick` stays within the bounds
-determined by `lastTick` and a dynamically calculated factor.*
-
-
-```solidity
-function boundTick(
-    int16 newTick
-) external view returns (int16);
-```
-**Parameters**
-
-|Name|Type|Description|
-|----|----|-----------|
-|`newTick`|`int16`|The proposed new tick value to be adjusted within valid bounds.|
-
-**Returns**
-
-|Name|Type|Description|
-|----|----|-----------|
-|`<none>`|`int16`|The adjusted tick value constrained within the allowable range.|
-
-
 ### getLendingStateTick
 
 Gets the tick value representing the TWAP since the last lending update.
@@ -442,15 +439,3 @@ function getLendingStateTick(
 |`maxSatInWads`|`uint256`|The maximum saturation in WADs.|
 
 
-### liquidationCheckHardPremiums
-
-
-```solidity
-function liquidationCheckHardPremiums(
-    Validation.InputParams memory inputParams,
-    address borrower,
-    Liquidation.HardLiquidationParams memory hardLiquidationParams,
-    uint256 actualRepaidLiquidityAssets
-) external view returns (bool badDebt);
-```
-