Updated to v0.5.7 #1076 (commit ab9d1cb)

Author: CanonicalJP

docs/overview.md

@@ -67,8 +67,9 @@ Users interact with the Spokes, which then interact directly with the Hubs. The
 - Managing user data structures and configurations.
 - Providing emergency stop functionality to halt operations, if needed.
 - Utilizing share-based accounting internally to simplify bookkeeping and ensure assets remain within designated Hub's caps as interest accrues.
-- Having a distinct `reserveId` in each Spoke, different from the `assetId` in the Hub, to allow for Spoke-specific configurations.
-- Managing oracle interactions.
+- Maintaining a Spoke-level `reserveId` tracking to allow for Spoke-specific configurations, different from the `assetId` of the underlying asset in the Hub.
+- Managing oracle interactions. Oracle is spoke-specific and may be bound once post-deployment of the Spoke.
+- Employing transient reentrancy guards for extra protection against reentrancy attacks. Even though Hub, IR Strategy, and Price Feeds are trusted and V4 does not support ERC20s with callbacks.
 
 # Risk Premium
 
@@ -92,7 +93,7 @@ The User Risk Premium $RP_u$ represents the quality of assets used as collateral
 - Asset price ($P_i$) of asset $i$: Prices are continuously fluctuating, with some assets being less volatile than others.
 - Collateral Risk ($CR_i$) of asset $i$: Risk parameter configured and updated on a regular basis by the Governor.
 
-Ideally, the User Risk Premium would be updated continuously to reflect its dynamic nature, ensuring it is always up-to-date and aligned with the last state of the user’s position. However, this is technically infeasible because of the limitations of EVM blockchains, requiring constant updates by means of onchain transactions. Instead, the User Risk Premium is updated only when the user performs certain actions which affect collateralization. An update can also be permissionlessly triggered (updateUserRiskPremium) by a user on their own positions. Additionally, a position manager or the Governor can trigger permissioned updates in particular cases. If the user remains inactive, their User Risk Premium remains constant. Exceptionally, the Governor retains the ability to forcibly update the User Risk Premium of a given user to match the most recent risk parameters of its collateral assets, even in the absence of user interaction. This is particularly relevant in scenarios where a specific user position has accumulated additional risk between interactions.
+Ideally, the User Risk Premium would be updated continuously to reflect its dynamic nature, ensuring it is always up-to-date and aligned with the last state of the user’s position. However, this is technically infeasible because of the limitations of EVM blockchains, requiring constant updates by means of onchain transactions. Instead, the User Risk Premium is refreshed only on actions that can change the position’s effective collateralization (e.g., `borrow`, `withdraw` when withdrawing collateral, `disableUsingAsCollateral` and `liquidateUser`). Actions that only reduce risk exposure (e.g., repay and supply) do not refresh the User Risk Premium. An update can also be permissionlessly triggered (`updateUserRiskPremium`) by a user on their own position or permissionedly triggered by a position manager or the Governor (in particular cases). If the user remains inactive, their User Risk Premium remains constant. Exceptionally, the Governor retains the ability to forcibly update the User Risk Premium of a given user to match the most recent risk parameters of its collateral assets, even in the absence of user interaction. This is particularly relevant in scenarios where a specific user position has accumulated additional risk between interactions.
 
 $RP_u$ is the Risk Premium of the user $u$
 
@@ -232,25 +233,26 @@ Aave V4 introduces a redesigned liquidation mechanism that replaces the fixed cl
 
 Aave V4 exposes several configurable parameters that influence liquidation:
 
-| **Parameter**                | **Description**                                                                                                                                                                                                                                                                                                   | **Constraints**                                               |     |     |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --- | --- |
-| `TargetHealthFactor`         | A spoke‑wide value set by the Governor representing the HF to which a borrower should be restored after liquidation. Liquidators repay only enough debt to reach this HF under normal circumstances that do not result in dust collateral or debt remaining.                                                      | Must be ≥ the `HEALTH_FACTOR_LIQUIDATION_THRESHOLD` constant. |
-| `DUST_LIQUIDATION_THRESHOLD` | Hard‑coded threshold used to prevent extremely small leftover of debt and/or collateral. The maximum debt that can be liquidated is increased to ensure that debt or collateral dust less than this threshold does not remain unless the corresponding respective collateral or debt reserve is fully liquidated. | Hard‑coded constant set to 1_000 USD in base units.           |
-| `maxLiquidationBonus`        | Per reserve defined maximum liquidation bonus for a collateral, expressed in basis points (BPS). A value of 105_00 means there is 5_00 extra seized collateral over the amount of debt repaid in base currency.                                                                                                   | Must be ≥ 100_00                                              |
-| `healthFactorForMaxBonus`    | Spoke‑wide value expressed in WAD units defining the HF below which the max bonus applies. It must be less than or equal to `HEALTH_FACTOR_LIQUIDATION_THRESHOLD` to avoid division‑by‑zero.                                                                                                                      | Must be < `HEALTH_FACTOR_LIQUIDATION_THRESHOLD`.              |
-| `liquidationBonusFactor`     | Spoke‑wide percentage (expressed in BPS) specifying the fraction of the max bonus earned at the threshold `HEALTH_FACTOR_LIQUIDATION_THRESHOLD`. It defines the minimum bonus; e.g., a factor of 80_00 yields a bonus equal to 80% of the max bonus when HF equals the liquidation threshold.                     | Must be ≤ 100_00                                              |
-| `liquidatable`               | Determines if a given reserve can be seized during liquidation when used as collateral. This flag can be adjusted by priviledged roles depending on the scenario and could be used to replicate use cases such as the V3 oracle sentinel and the V3 unpause grace period.                                         | Must be `true` or `false`                                     |
+| **Parameter**                | **Description**                                                                                                                                                                                                                                                                                                                                                | **Constraints**                                               |     |     |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --- | --- |
+| `TargetHealthFactor`         | A spoke‑wide value set by the Governor representing the HF to which a borrower should be restored after liquidation. Liquidators repay only enough debt to reach this HF under normal circumstances that do not result in dust collateral or debt remaining.                                                                                                   | Must be ≥ the `HEALTH_FACTOR_LIQUIDATION_THRESHOLD` constant. |
+| `DUST_LIQUIDATION_THRESHOLD` | Hard‑coded threshold used to prevent extremely small leftover of debt and/or collateral. The maximum debt that can be liquidated is increased to ensure that debt or collateral dust less than this threshold does not remain unless the corresponding respective collateral or debt reserve is fully liquidated.                                              | Hard‑coded constant set to 1_000 USD in base units.           |
+| `maxLiquidationBonus`        | Per reserve defined maximum liquidation bonus for a collateral, expressed in basis points (BPS). A value of 105_00 means there is 5_00 extra seized collateral over the amount of debt repaid in base currency.                                                                                                                                                | Must be ≥ 100_00                                              |
+| `healthFactorForMaxBonus`    | Spoke‑wide value expressed in WAD units defining the HF below which the max bonus applies. It must be less than or equal to `HEALTH_FACTOR_LIQUIDATION_THRESHOLD` to avoid division‑by‑zero.                                                                                                                                                                   | Must be < `HEALTH_FACTOR_LIQUIDATION_THRESHOLD`.              |
+| `liquidationBonusFactor`     | Spoke‑wide percentage (expressed in BPS) specifying the fraction of the max bonus earned at the threshold `HEALTH_FACTOR_LIQUIDATION_THRESHOLD`. It defines the minimum bonus; e.g., a factor of 80_00 yields a bonus equal to 80% of the max bonus when HF equals the liquidation threshold.                                                                  | Must be ≤ 100_00                                              |
+| `liquidatable`               | Determines if a given reserve can be seized during liquidation when used as collateral. This flag can be adjusted by priviledged roles depending on the scenario and could be used to replicate use cases such as the V3 oracle sentinel and the V3 unpause grace period.                                                                                      | Must be `true` or `false`                                     |
+| `receiveSharesEnabled`       | Per-reserve flag that determines whether liquidators can receive Hub shares directly (instead of underlying assets) when liquidating positions. When enabled and the reserve is not frozen, liquidators can opt to receive shares via the `receiveShares` parameter. Shares accrue yield in the Hub, providing a more capital-efficient liquidation mechanism. | Must be `true` or `false`                                     |
 
 ## Liquidation Process in V4
 
 The following high‑level steps outline the V4 liquidation flow:
 
-1. **Check Eligibility:** When a borrower’s HF drops below the `HEALTH_FACTOR_LIQUIDATION_THRESHOLD`, anyone can trigger a liquidation; however, accounts are not allowed to liquidate their own positions. The protocol retrieves the borrower’s total debt value, current HF, and total collateral value, counting only reserves with `usingAsCollateral` enabled, CF > 0, and the reserve not paused; liquidations in which reserves are frozen are allowed.
+1. **Check Eligibility:** When a borrower’s HF drops below the `HEALTH_FACTOR_LIQUIDATION_THRESHOLD`, anyone can trigger a liquidation; however, accounts are not allowed to liquidate their own positions. The protocol retrieves the borrower’s total debt value, current HF, and total collateral value, including only reserves with `usingAsCollateral` enabled, CF > 0, and not paused. Liquidations of frozen reserves are allowed. Other paused reserves/spokes (not the target reserve being liquidated or the spoke being called by the liquidator) don't block liquidations.
 2. **Determine Debt to Repay:** Based on the Target Health Factor `TargetHealthFactor`, the protocol computes the debt that must be repaid to restore the borrower’s HF to `TargetHealthFactor`. The required repayment amount depends on the borrower’s current debt and collateral (CF, LB, HF).
 3. **Handle Dust Debt:** If the borrower’s remaining debt after a standard liquidation would be below the `DUST_LIQUIDATION_THRESHOLD`, and the liquidator intends to fully repay the debt, the protocol increases the allowable debt that can be liquidated, so that the entire debt can be covered. However, dust may still remain if the liquidator targets debt equal to the full amount of the collateral reserve $C_i$ being seized (i.e., $Δ C_i = C_i$), then a residual debt $D_{dust} > 0$ can remain when there are multiple collateral reserves ($N_{coll} > 1$). If there is a single collateral reserve ($N_{coll} = 1$), the residual, along with any other existing debt across all reserves, is recorded as a protocol deficit.
 4. **Calculate Collateral to Seize and Handle Collateral Dust**: Convert the debt to be repaid into the collateral asset’s value and apply the liquidation bonus for this specific liquidation. By this point the bonus is fixed (not variable during execution) based on the position’s HF at the start of liquidation and the reserve’s `maxLiquidationBonus`. The formula in this step just computes that liquidation bonus and the resulting collateral to transfer. If the chosen collateral is not sufficient, all of that collateral is seized and the repaid debt is recomputed. Lastly, collateral dust is accounted for.
 5. **Apply Debt Repayment & Transfer Collateral**: Reduce the borrower’s debt amount by the repaid amount. Transfer the corresponding collateral to the liquidator with the liquidation bonus applied, minus the protocol fee (as in V3). The fee portion is sent to the protocol/fee receiver via the Hub as shares, accrues yield there, and the shares are assigned directly via Hub accounting.
-6. **Emit Events and Update State:** A `LiquidationCall` event is emitted containing details of the liquidation. The borrower’s and reserve’s interest indices are updated. If the borrower still has debt outstanding and no remaining collateral, the system will record a protocol deficit.
+6. **Emit Events and Update State:** A `LiquidationCall` event is emitted containing details of the liquidation. The borrower’s and reserve’s interest indices are updated. If the borrower still has debt outstanding and no remaining collateral, the system will record a protocol deficit. Reporting deficit is allowed even when the reporting spoke is paused (as long as it’s active).
 
 ## Dust and Rounding Considerations