# Priority Pool

The `PriorityPool` allows users to queue asset tokens which are eventually deposited into a `StakingPool` when deposit room becomes available. The liquid staking tokens (LSTs) minted by the `StakingPool` are then distributed using a merkle tree.

Each user will continuously receive LSTs as more depositd are made into the `StakingPool` until they have received an amount equal to the amount of asset tokens they deposited into the `PriorityPool`. The rate at which each user receives LSTs is dependent on the user's reSDL balance in the `SDLPool`. A higher reSDL balance entitles the user to receive LSTs at a faster rate than a user with a smaller reSDL balance. Users that hold no reSDL can also deposit into the `PriorityPool` but they will receive no LSTs as long as there are users with deposits in the `PriorityPool` that also hold reSDL.

The secondary function of the `PriorityPool` is to act as a liquidity buffer for the `StakingPool` it deposits into. When a user redeems LSTs for the underlying asset token, these LSTs will be swapped with queued asset tokens from the `PriorityPool` if possible before queuing tokens in the `WithdrawalPool`. This both reduces gas costs for the user and ensures that the `StakingPool` earns the most yield possible as yield earning asset tokens remain in the pool instead of being withdrawn.

## View Functions

### token

Returns the address of the token this pool handles

```solidity
function token() external view returns (address)
```

#### Return Values

| Name  | Type    | Description      |
| ----- | ------- | ---------------- |
| token | address | address of token |

### stakingPool

Returns the address of the staking pool that this pool deposits into

```solidity
function stakingPool() external view returns (address)
```

#### Return Values

| Name        | Type    | Description             |
| ----------- | ------- | ----------------------- |
| stakingPool | address | address of staking pool |

### sdlPool

Returns the address of the SDL pool

```solidity
function sdlPool() external view returns (address)
```

#### Return Values

| Name    | Type    | Description         |
| ------- | ------- | ------------------- |
| sdlPool | address | address of SDL pool |

### distributionOracle

Returns the address of the oracle that handles distribution of liquid staking tokens

```solidity
function distributionOracle() external view returns (address)
```

#### Return Values

| Name               | Type    | Description                    |
| ------------------ | ------- | ------------------------------ |
| distributionOracle | address | address of distribution oracle |

### rebaseController

Returns the address of the rebase controller

```solidity
function rebaseController() external view returns (address)
```

#### Return Values

| Name             | Type    | Description                  |
| ---------------- | ------- | ---------------------------- |
| rebaseController | address | address of rebase controller |

### withdrawalPool

Returns the address of the withdrawal pool

```solidity
function withdrawalPool() external view returns (address)
```

#### Return Values

| Name           | Type    | Description                |
| -------------- | ------- | -------------------------- |
| withdrawalPool | address | address of withdrawal pool |

### queueDepositMin

Returns the minimum amount of tokens required to execute a deposit

```solidity
function queueDepositMin() external view returns (uint256)
```

#### Return Values

| Name       | Type    | Description           |
| ---------- | ------- | --------------------- |
| depositMin | uint256 | queue deposit minimum |

### queueDepositMax

Returns the maximum amount of tokens that can be deposited in a single deposit

```solidity
function queueDepositMax() external view returns (uint256)
```

#### Return Values

| Name       | Type    | Description           |
| ---------- | ------- | --------------------- |
| depositMax | uint256 | queue deposit maximum |

### poolStatus

Returns the current status of the pool

0 - OPEN (nothing disabled)\
1 - DRAINING (deposits disabled)\
2 - CLOSED (deposits/withdrawals disabled)

```solidity
function poolStatus() external view returns (PoolStatus)
```

#### Return Values

| Name       | Type       | Description                |
| ---------- | ---------- | -------------------------- |
| poolStatus | PoolStatus | current status of the pool |

### merkleRoot

Returns the merkle root for the latest distribution tree

```solidity
function merkleRoot() external view returns (bytes32)
```

#### Return Values

| Name       | Type    | Description         |
| ---------- | ------- | ------------------- |
| merkleRoot | bytes32 | current merkle root |

### ipfsHash

Returns the ipfs hash of the balance data for the latest distribution tree

```solidity
function ipfsHash() external view returns (bytes32)
```

#### Return Values

| Name     | Type    | Description      |
| -------- | ------- | ---------------- |
| ipfsHash | bytes32 | current ipfsHash |

### merkleTreeSize

Returns the number of unique addresses contained in the latest distribution tree

```solidity
function merkleTreeSize() external view returns (uint256)
```

#### Return Values

| Name           | Type    | Description              |
| -------------- | ------- | ------------------------ |
| merkleTreeSize | uint256 | current merkle tree size |

### totalQueued

Returns the total amount of token deposits in the pool waiting to be deposited into the staking pool

```solidity
function totalQueued() external view returns (uint256)
```

#### Return Values

| Name        | Type    | Description                |
| ----------- | ------- | -------------------------- |
| totalQueued | uint256 | total deposits in the pool |

### getAccounts

Returns a list of all accounts that have deposited into the pool in the order that they appear in the distribution tree

```solidity
function getAccounts() external view returns (address[])
```

#### Return Values

| Name     | Type       | Description      |
| -------- | ---------- | ---------------- |
| accounts | address\[] | list of accounts |

### getAccountIndex

Returns the index of an account representing it's position in the distribution tree

```solidity
function getAccountIndex(address _account) external view returns (uint256)
```

#### Parameters

| Name      | Type    | Description     |
| --------- | ------- | --------------- |
| \_account | address | account address |

#### Return Values

| Name  | Type    | Description   |
| ----- | ------- | ------------- |
| index | uint256 | account index |

### getQueuedTokens

Returns an account's current amount of deposits in the pool (`_distributionAmount` is stored on IPFS)

```solidity
function getQueuedTokens(address _account, uint256 _distributionAmount) public view returns (uint256)
```

#### Parameters

| Name                 | Type    | Description                                                     |
| -------------------- | ------- | --------------------------------------------------------------- |
| \_account            | address | account address                                                 |
| \_distributionAmount | uint256 | account's distribution amount from the latest distribution tree |

#### Return Values

| Name         | Type    | Description                         |
| ------------ | ------- | ----------------------------------- |
| queuedTokens | uint256 | amount of queued tokens for account |

### getLSDTokens

Returns an account's current amount of withdrawable liquid staking tokens (`_distributionShareAmount` is stored on IPFS)

```solidity
function getLSDTokens(address _account, uint256 _distributionShareAmount) external view returns (uint256)
```

#### Parameters

| Name                      | Type    | Description                                                            |
| ------------------------- | ------- | ---------------------------------------------------------------------- |
| \_account                 | address | account address                                                        |
| \_distributionShareAmount | uint256 | account's distribution share amounts from the latest distribution tree |

#### Return Values

| Name      | Type    | Description                         |
| --------- | ------- | ----------------------------------- |
| lsdTokens | uint256 | withdrawable LSD tokens for account |

### getLSDTokensBatch

Returns the current amount of withdrawable LSD tokens for multiple accounts.

```solidity
function getLSDTokensBatch(address[] calldata _accounts, uint256[] calldata _distributionShareAmounts) external view returns (uint256[] memory)
```

#### Parameters

| Name                       | Type       | Description                                 |
| -------------------------- | ---------- | ------------------------------------------- |
| \_accounts                 | address\[] | List of account addresses                   |
| \_distributionShareAmounts | uint256\[] | Distribution share amounts for each account |

#### Return Values

| Name      | Type       | Description                          |
| --------- | ---------- | ------------------------------------ |
| lsdTokens | uint256\[] | Withdrawable LSD tokens for accounts |

### canWithdraw

Returns the total amount of asset tokens that an account can withdraw (includes account's queued tokens and stLINK balance and takes into account both priority pool and staking pool liquidity)

```solidity
function canWithdraw(address _account, uint256 _distributionAmount) external view returns (uint256)
```

#### Parameters

| Name                 | Type    | Description                                                     |
| -------------------- | ------- | --------------------------------------------------------------- |
| \_account            | address | account address                                                 |
| \_distributionAmount | uint256 | account's distribution amount from the latest distribution tree |

#### Return Values

| Name        | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| canWithdraw | uint256 | amount of withrawable tokens |

### checkUpkeep

Returns whether a call should be made to performUpkeep to deposit queued/unused tokens\
into staking pool strategies

```solidity
function checkUpkeep(bytes) external view returns (bool, bytes)
```

#### Return Values

| Name         | Type  | Description                                    |
| ------------ | ----- | ---------------------------------------------- |
| upkeepNeeded | bool  | whether a call should be made to performUpkeep |
| upkeepNeeded | bytes | encoded amount of tokens to be deposited       |

### getDepositsSinceLastUpdate

Returns the amount of new deposits into the staking pool since the last call to updateDistribution and the amount of shares received for those deposits

```solidity
function getDepositsSinceLastUpdate() external view returns (uint256, uint256)
```

#### Return Values

| Name     | Type    | Description        |
| -------- | ------- | ------------------ |
| deposits | uint256 | amount of deposits |
| shares   | uint256 | amount of shares   |

### getAccountData

Returns account data used for calculating a new merkle tree

*A new merkle tree is calculated based on users' reSDL balance and the number of tokens they have queuedAccounts are returned in the same order as they are in the merkle tree*

```solidity
function getAccountData() external view returns (address[], uint256[], uint256[])
```

#### Return Values

| Name           | Type       | Description                                                                    |
| -------------- | ---------- | ------------------------------------------------------------------------------ |
| accounts       | address\[] | list of all accounts that have ever queued tokens                              |
| sdlBalances    | uint256\[] | list of SDL balances for each account                                          |
| queuedBalances | uint256\[] | list of queued token amounts for each account (ignores distributed LSD tokens) |

## Write Functions

### onTokenTransfer

ERC677 implementation to receive a token deposit or withdrawal

*Can receive both asset tokens (deposit) and liquid staking tokens (withdrawal)*

```solidity
function onTokenTransfer(address _sender, uint256 _value, bytes _calldata) external
```

#### Parameters

| Name       | Type    | Description                                                                               |
| ---------- | ------- | ----------------------------------------------------------------------------------------- |
| \_sender   | address | sender of the transfer                                                                    |
| \_value    | uint256 | value of the transfer                                                                     |
| \_calldata | bytes   | encoded shouldQueue (bool) and deposit data to pass to staking pool strategies (bytes\[]) |

### deposit

Deposits asset tokens into the staking pool and/or queues them

```solidity
function deposit(uint256 _amount, bool _shouldQueue, bytes _data) external
```

#### Parameters

| Name          | Type    | Description                                                            |
| ------------- | ------- | ---------------------------------------------------------------------- |
| \_amount      | uint256 | amount to deposit                                                      |
| \_shouldQueue | bool    | whether tokens should be queued if there's no room in the staking pool |
| \_data        | bytes   | deposit data passed to staking pool strategies                         |

### withdraw

Withdraws asset tokens

*Will unqueue sender's asset tokens before swapping liquid staking tokens if there is sufficient liquidity and \_shouldUnqueue is set to true*

```solidity
function withdraw(uint256 _amountToWithdraw, uint256 _amount, uint256 _sharesAmount, bytes32[] _merkleProof, bool _shouldUnqueue, bool _shouldUnqueueWithdrawal) external
```

#### Parameters

| Name                    | Type       | Description                                                                             |
| ----------------------- | ---------- | --------------------------------------------------------------------------------------- |
| \_amountToWithdraw      | uint256    | amount of tokens to withdraw                                                            |
| \_amount                | uint256    | amount as recorded in sender's merkle tree (stored on IPFS)entry                        |
| \_sharesAmount          | uint256    | shares amount as recorded in sender's merkle tree (stored on IPFS)entry                 |
| \_merkleProof           | bytes32\[] | merkle proof for sender's merkle tree entry (generated from IPFS data)                  |
| \_shouldUnqueue         | bool       | whether tokens should be unqueued before taking LSD tokens                              |
| \_shouldQueueWithdrawal | bool       | whether a withdrawal should be queued if the full withdrawal amount cannot be satisfied |

### unqueueTokens

Withdraws queued deposits from the priority pool

```solidity
function unqueueTokens(uint256 _amountToUnqueue, uint256 _amount, uint256 _sharesAmount, bytes32[] _merkleProof) external
```

#### Parameters

| Name              | Type       | Description                                                              |
| ----------------- | ---------- | ------------------------------------------------------------------------ |
| \_amountToUnqueue | uint256    | amount of tokens to unqueue                                              |
| \_amount          | uint256    | amount as recorded in sender's merkle tree entry (stored on IPFS)        |
| \_sharesAmount    | uint256    | shares amount as recorded in sender's merkle tree entry (stored on IPFS) |
| \_merkleProof     | bytes32\[] | merkle proof for sender's merkle tree entry (generated from IPFS data)   |

### claimLSDTokens

Claims withdrawable liquid staking tokens

```solidity
function claimLSDTokens(uint256 _amount, uint256 _sharesAmount, bytes32[] _merkleProof) external
```

#### Parameters

| Name           | Type       | Description                                             |
| -------------- | ---------- | ------------------------------------------------------- |
| \_amount       | uint256    | amount as recorded in sender's merkle tree entry        |
| \_sharesAmount | uint256    | shares amount as recorded in sender's merkle tree entry |
| \_merkleProof  | bytes32\[] | merkle proof for sender's merkle tree entry             |

### depositQueuedTokens

Deposits queued tokens and/or unused tokens sitting in staking pool

```solidity
function depositQueuedTokens(uint256 _queueDepositMin, uint256 _queueDepositMax, bytes[] _data) external
```

#### Parameters

| Name              | Type     | Description                                                                     |
| ----------------- | -------- | ------------------------------------------------------------------------------- |
| \_queueDepositMin | uint256  | min amount of tokens required for deposit into staking pool strategies          |
| \_queueDepositMax | uint256  | max amount of tokens that can be deposited into staking pool strategies at once |
| \_data            | bytes\[] | list of deposit data passed to staking pool strategies                          |

### performUpkeep

Deposits queued and/or unused tokens

```solidity
function performUpkeep(bytes _performData) external
```

#### Parameters

| Name          | Type     | Description                                                                     |
| ------------- | -------- | ------------------------------------------------------------------------------- |
| \_performData | bytes\[] | encoded list of deposit data to be passed to staking pool strategies (bytes\[]) |

### updateDistribution

Distributes a new batch of liquid staking tokens to users that have queued deposits

```solidity
function updateDistribution(bytes32 _merkleRoot, bytes32 _ipfsHash, uint256 _amountDistributed, uint256 _sharesAmountDistributed) external
```

#### Parameters

| Name                      | Type    | Description                                                            |
| ------------------------- | ------- | ---------------------------------------------------------------------- |
| \_merkleRoot              | bytes32 | new merkle root for the distribution tree                              |
| \_ipfsHash                | bytes32 | new ipfs hash for the distribution tree (CIDv0, no prefix - only hash) |
| \_amountDistributed       | uint256 | amount of LSD tokens distributed in this distribution                  |
| \_sharesAmountDistributed | uint256 | amount of LSD shares distributed in this distribution                  |

### executeQueuedWithdrawals

Executes a batch of withdrawals that have been queued in the withdrawal pool

*Withdraws tokens from the staking pool and sends them to the withdrawal pool*

```solidity
 function executeQueuedWithdrawals(uint256 _amount, bytes[] _data) external
```

#### Parameters

| Name     | Type    | Description                                               |
| -------- | ------- | --------------------------------------------------------- |
| \_amount | uint256 | total amount to withdraw                                  |
| \_data   | bytes   | list of withdrawal data passed to staking pool strategies |

### pauseForUpdate

Pauses queueing and unqueueing so a new merkle tree can be generated

```solidity
function pauseForUpdate() external
```

### setPoolStatus

Sets the pool's status

```solidity
function setPoolStatus(enum PriorityPool.PoolStatus _status) external
```

#### Parameters

| Name     | Type       | Description |
| -------- | ---------- | ----------- |
| \_status | PoolStatus | pool status |

### setQueueDepositParams

Sets the minimum and maximum amount that can be deposited into strategies at once

```solidity
function setQueueDepositParams(uint128 _queueDepositMin, uint128 _queueDepositMax) external
```

#### Parameters

| Name              | Type    | Description                                                                         |
| ----------------- | ------- | ----------------------------------------------------------------------------------- |
| \_queueDepositMin | uint128 | minimum amount of tokens required for deposit into staking pool strategies          |
| \_queueDepositMax | uint128 | maximum amount of tokens that can be deposited into staking pool strategies at once |

### setDistributionOracle

Sets the distribution oracle

```solidity
function setDistributionOracle(address _distributionOracle) external
```

#### Parameters

| Name                 | Type    | Description       |
| -------------------- | ------- | ----------------- |
| \_distributionOracle | address | address of oracle |

### setRebaseController

Sets the rebase controller

*This address has authorization to close the pool in case of emergency*

```solidity
function setRebaseController(address _rebaseController_) external
```

#### Parameters

| Name               | Type    | Description                  |
| ------------------ | ------- | ---------------------------- |
| \_rebaseController | address | address of rebase controller |

### setWithdrawalPool

Sets the withdrawal pool

```solidity
function setWithdrawalPool(address _withdrawalPool) external
```

#### Parameters

| Name             | Type    | Description                |
| ---------------- | ------- | -------------------------- |
| \_withdrawalPool | address | address of withdrawal pool |

### setAllowInstantWithdrawals

Sets whether instant withdrawals are enabled.

```solidity
function setAllowInstantWithdrawals(bool _allowInstantWithdrawals) external
```

#### Parameters

| Name                      | Type | Description                         |
| ------------------------- | ---- | ----------------------------------- |
| \_allowInstantWithdrawals | bool | Whether instant withdrawals enabled |

### allowInstantWithdrawals

Returns whether instant withdrawals are enabled.

```solidity
function allowInstantWithdrawals() external view returns (bool)
```

#### Return Values

| Name                    | Type | Description                         |
| ----------------------- | ---- | ----------------------------------- |
| allowInstantWithdrawals | bool | Whether instant withdrawals enabled |


---

# 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.stake.link/core-staking-contracts/prioritypool.md?ask=<question>
```

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.