# Absorber Module
The Absorber is Opus' implementation of a stability pool that allows yin holders to provide their yin and participate in liquidations (i.e. absorptions) as a consolidated pool.
By providing their `yin` to the Absorber, users will be able to:
1. share in the absorption rewards (also referred to as "absorbed assets");
2. receive yield in the form of a portion of the `yin` minted from debt surpluses (e.g. interest from troves and forge fees);
3. share in any additional reward tokens that may be distributed by the protocol or other parties.
Note that there are preconditions to subsequently removing `yin` that was provided earlier.
To prevent confusion with "deposit" and "withdrawal" of `yang` for trove users, we use "provide" and "remove" to refer to users who deposit and withdraw `yin` from the Absorber.
## Description of key functions
1. `provide`: users may provide `yin` and receive internal shares
2. `remove`: users who have provided `yin` previously may remove their remaining entitlement provided they have submitted a request (see below) and the conditions for the request have been fulfilled
3. `request`: users may request to `remove` their earlier provided `yin`
4. `reap`: withdraw a provider's entitlement to absorbed assets and rewards
5. `update`: inform the Absorber that an absorption has occured so that the Absorber can account for the absorbed assets. This is intended for the Purger.
## Providing liquidity
When a user provides `yin` to the Absorber, the user is issued a number of shares in an epoch for internal accounting purposes. The epoch starts from index 1, and is incremented when either (1) the Absorber's `yin` balance falls below the minimum amount; or (2) the amount of `yin` per share falls below a certain threshold.
The internal shares are used to account for the following:
1. the remaining amount of `yin` that a provider is entitled to withdraw;
2. the amount of absorbed assets the provider is entitled to based on the absorptions that have occurred while the provider has some entitlement of `yin` in the Absorber; and
3. the amount of rewards, if any, that a provider is entitled to withdraw.
On rare occasions, it is possible for a provider's shares to be carried over to the next epoch if the Absorber still has `yin`. This may happen if the trigger for the new epoch is the amount of yin represented per share falling below a certain threshold. In these cases, we keep track of a conversion rate of an epoch's share to the next epoch's share, and calculate the provider's entitlement in the new epoch. There may be some precision loss from this share conversion across epochs that will favour the protocol.
If the provider would receive zero shares for the amount provided e.g. due to loss of precision, the transaction would revert.
### Initial shares
Similar to the Gate, the Absorber is also susceptible to the first depositor front-running issue. To mitigate against this by increasing the cost of such an attack, a minimum amount of shares (`10 ** 9`) is minted into oblivion at the start of each epoch. This is either deducted from the `yin` provided by the first provider of the epoch or from the leftover `yin` of the previous epoch.
### Absorbed assets
Similar to redistributions in Shrine, absorptions are tracked with an absorption ID using a computation-heavy approach:
* Absorption ID starts from 1. 0 is used as the terminating condition.
* Each absorption is tied to an epoch.
* When `absorb` is called, we derive the amount of absorbed assets that each unit of internal share is entitled to. Any remainder amounts arising from the loss of precision will be transferred back to the Gate.
To calculate a provider's entitlement to absorbed assets, we iterate over the absorption IDs that have occurred since the provider's last absorption ID, and for each absorption ID, we multiply the provider's shares with the corresponding amount of each absorbed asset.
Note that the amount of shares that is minted into oblivion at the start of each epoch is excluded when calculating each share's entitlement to absorbed assets.
### Rewards
The Absorber supports distribution of whitelisted rewards. The only requirement is that the vesting contracts adhere to the `Blesser` interface. Caution should be exercised (e.g. checking for non-standard behaviour like blacklists) when whitelisting a reward token to ensure that a failure to vest reward tokens does not cause an absorption to revert.
The accounting and distribution of rewards is functionally similar to that of absorbed assets. The only difference is that rewards are vested whenever a user action is taken (i.e. `provide`, `remove`, `reap`, `update`), in addition to when an absorption occurs (`update`).
Note that the amount of shares that is minted into oblivion at the start of each epoch is excluded when calculating each share's entitlement to rewards.
### Minimum shares for Absorber to operate
As the initial amount of shares minted into oblivion are excluded from receiving absorbed assets and rewards, there is a potential overflow issue when attempting to distribute absorbed assets and rewards if the remaining shares is a very small number.
To mitigate against potential overflows, the Absorber is available for absorptions only if there is a minimum number of shares (currently set at `10 ** 6`) excluding the initial shares, even if there is some `yin` in the Absorber.
Note that this requirement is distinct from, and in addition to, the initial shares that is minted to oblivion at the start of each epoch to address the first depositor front-running issue. In other words, the Absorber is operational only if there is at least `10 ** 9 + 10 ** 6` shares.
## Removing liquidity
A provider who has provided `yin` can subsequently elect to remove such remaining amount. If the Absorber's `yin` has been fully used for a provider's epoch, then the provider may not have any remaining `yin` entitlement to be withdrawn.
There are two preconditions for removal:
1. if the Shrine is live, the Shrine must not be in recovery mode; and
2. the provider must have submitted a `request` and the removal must be made within the validity period.
Once a provider has submitted a `request`, the timelock (initial value of 1 minute) will start counting down. Once the timelock has elapsed, the provider has 1 hour to call `remove` before the `request` expires. In addition, if a subsequent `request` is made within the cooldown period (currently set at 7 days) of the earlier `request`, then the timelock will increase by a factor of 5, capped at a maximum of 7 days.
The purpose of imposing these restrictions are to:
1. ensure there is sufficient liquidity to absorb any prospective liquidations when there is a high risk of liquidations across the protocol;
2. prevent risk-free yield-farming tactics where a provider earns yield in the form of interest and reward tokens, if any, but frontruns liquidations by removing liquidity just before the liquidation happens.
Consequently, if a provider provides liquidity after submitting a request, the request would be invalidated by the provision, and the provider will need to submit a new request.
Regardless of whether the provider has any remaining `yin` entitlement to be withdrawn, any absorbed assets and rewards that the provider is entitled to will also be withdrawn.
## Withdrawing absorbed assets and rewards
A provider may also opt to withdraw absorbed assets and rewards only by calling `reap`. This action is not subject to any preconditions.
## Emergency Mechanism
The Absorber has a `kill` function that:
1. irreversibly pauses `provide`, preventing users from providing further liquidity; and
2. irreversibly pauses the distribution of all rewards, if any.
Users will still be able to `remove` their liquidity after the Absorber is killed.
Note that the Caretaker does not automatically kill the Absorber during global shutdown because the Absorber may be a recipient of any final debt surplus that is minted before final settlement in the Shrine.
In addition, `yin` that has been provided to the Absorber may still be used for absorptions after the Absorber is killed.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.opus.money/current/technical-documentation/smart-contracts/absorber-module.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.