Skip to content

Updated contract docs for pull request copilot/allow-revoke-allowance-on-debt-tokens #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
duelinggalois wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Updated contract docs for pull request copilot/allow-revoke-allowance-on-debt-tokens #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 126 additions & 138 deletions docs/developer-guide/contracts/AmmalgamPair.sol/contract.AmmalgamPair.md
View file
Open in desktop

Large diffs are not rendered by default.

148 changes: 67 additions & 81 deletions ...SaturationAndGeometricTWAPState.sol/contract.SaturationAndGeometricTWAPState.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/0de309c2d649ef8a8b8cfbcf17ff86c15e09a942/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;
```


Expand All @@ -41,6 +41,13 @@ mapping(address => mapping(address => uint256)) maxNewPositionSaturationInMAG2;
```


### lastUsedActiveLiquidityInLAssets

```solidity
mapping(address => mapping(address => uint256)) lastUsedActiveLiquidityInLAssets;
```


### isPairInitialized

```solidity
Expand All @@ -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
Expand All @@ -78,9 +92,7 @@ initializes the sat and TWAP struct


```solidity
function init(
int16 firstTick
) external;
function init(uint256 reserveXAssets, uint256 reserveYAssets) external;
```

### setNewPositionSaturation
Expand All @@ -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
Expand All @@ -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


Expand All @@ -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

Expand Down Expand Up @@ -278,7 +309,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**

Expand All @@ -305,7 +336,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);
```
Expand All @@ -314,7 +346,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**
Expand All @@ -325,17 +358,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
Expand Down Expand Up @@ -390,30 +412,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.
Expand Down Expand Up @@ -442,15 +440,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);
```

Loading