# stBTC

This contract implements the ERC-4626 tokenized vault standard. Bitcoin deposits are tracked with a receipt token called stBTC, commonly referred to as "shares". Users have the flexibility to redeem stBTC, enabling them to withdraw their deposited tBTC along with any accrued rewards.

*ERC-4626 is a standard to optimize and unify the technical parameters of vaults. This contract facilitates the minting and burning of shares (stBTC), which are represented as standard ERC20 tokens, providing a seamless exchange with tBTC or bitcoin tokens.*

## dispatcher

```solidity
contract IDispatcher dispatcher
```

Dispatcher contract that routes tBTC from stBTC to a given allocation contract and back.

## treasury

```solidity
address treasury
```

Address of the treasury wallet, where fees should be transferred to.

## minimumDepositAmount

```solidity
uint256 minimumDepositAmount
```

Minimum amount for a single deposit operation. The value should be set low enough so the deposits routed through Bitcoin Depositor contract won't be rejected. It means that minimumDepositAmount should be lower than tBTC protocol's depositDustThreshold reduced by all the minting fees taken before depositing in the Acre contract.

## entryFeeBasisPoints

```solidity
uint256 entryFeeBasisPoints
```

Entry fee basis points applied to entry fee calculation.

## exitFeeBasisPoints

```solidity
uint256 exitFeeBasisPoints
```

Exit fee basis points applied to exit fee calculation.

## allowedDebt

```solidity
mapping(address => uint256) allowedDebt
```

Returns the maximum amount of the underlying asset for which the shares can be minted without the coverage in deposited assets.

## currentDebt

```solidity
mapping(address => uint256) currentDebt
```

Returns the current debt of the debtor.

## totalDebt

```solidity
uint256 totalDebt
```

Total amount of debt across all debtors.

*This is the total amount of assets for which shares have been minted without the coverage in deposited assets. The value is used to adjust the total assets held by the vault.*

## TreasuryUpdated

```solidity
event TreasuryUpdated(address oldTreasury, address newTreasury)
```

Emitted when the treasury wallet address is updated.

### Parameters

| Name        | Type    | Description                         |
| ----------- | ------- | ----------------------------------- |
| oldTreasury | address | Address of the old treasury wallet. |
| newTreasury | address | Address of the new treasury wallet. |

## MinimumDepositAmountUpdated

```solidity
event MinimumDepositAmountUpdated(uint256 minimumDepositAmount)
```

Emitted when deposit parameters are updated.

### Parameters

| Name                 | Type    | Description                              |
| -------------------- | ------- | ---------------------------------------- |
| minimumDepositAmount | uint256 | New value of the minimum deposit amount. |

## DispatcherUpdated

```solidity
event DispatcherUpdated(address oldDispatcher, address newDispatcher)
```

Emitted when the dispatcher contract is updated.

### Parameters

| Name          | Type    | Description                             |
| ------------- | ------- | --------------------------------------- |
| oldDispatcher | address | Address of the old dispatcher contract. |
| newDispatcher | address | Address of the new dispatcher contract. |

## EntryFeeBasisPointsUpdated

```solidity
event EntryFeeBasisPointsUpdated(uint256 entryFeeBasisPoints)
```

Emitted when the entry fee basis points are updated.

### Parameters

| Name                | Type    | Description                        |
| ------------------- | ------- | ---------------------------------- |
| entryFeeBasisPoints | uint256 | New value of the fee basis points. |

## ExitFeeBasisPointsUpdated

```solidity
event ExitFeeBasisPointsUpdated(uint256 exitFeeBasisPoints)
```

Emitted when the exit fee basis points are updated.

### Parameters

| Name               | Type    | Description                        |
| ------------------ | ------- | ---------------------------------- |
| exitFeeBasisPoints | uint256 | New value of the fee basis points. |

## DebtAllowanceUpdated

```solidity
event DebtAllowanceUpdated(address debtor, uint256 newAllowance)
```

Emitted when the maximum debt allowance of the debtor is updated.

### Parameters

| Name         | Type    | Description                           |
| ------------ | ------- | ------------------------------------- |
| debtor       | address | Address of the debtor.                |
| newAllowance | uint256 | Maximum debt allowance of the debtor. |

## DebtMinted

```solidity
event DebtMinted(address debtor, uint256 currentDebt, uint256 assets, uint256 shares)
```

Emitted when debt is minted.

### Parameters

| Name        | Type    | Description                                    |
| ----------- | ------- | ---------------------------------------------- |
| debtor      | address | Address of the debtor.                         |
| currentDebt | uint256 | Current debt of the debtor.                    |
| assets      | uint256 | Amount of assets for which debt will be taken. |
| shares      | uint256 | Amount of shares minted.                       |

## DebtRepaid

```solidity
event DebtRepaid(address debtor, uint256 currentDebt, uint256 assets, uint256 shares)
```

Emitted when debt is repaid.

### Parameters

| Name        | Type    | Description                         |
| ----------- | ------- | ----------------------------------- |
| debtor      | address | Address of the debtor.              |
| currentDebt | uint256 | Current debt of the debtor.         |
| assets      | uint256 | Amount of assets repaying the debt. |
| shares      | uint256 | Amount of shares burned.            |

## LessThanMinDeposit

```solidity
error LessThanMinDeposit(uint256 amount, uint256 min)
```

Reverts if the amount is less than the minimum deposit amount.

### Parameters

| Name   | Type    | Description                               |
| ------ | ------- | ----------------------------------------- |
| amount | uint256 | Amount to check.                          |
| min    | uint256 | Minimum amount to check 'amount' against. |

## DisallowedAddress

```solidity
error DisallowedAddress()
```

Reverts if the address is disallowed.

## ExceedsMaxFeeBasisPoints

```solidity
error ExceedsMaxFeeBasisPoints()
```

Reverts if the fee basis points exceed the maximum value.

## SameTreasury

```solidity
error SameTreasury()
```

Reverts if the treasury address is the same.

## SameDispatcher

```solidity
error SameDispatcher()
```

Reverts if the dispatcher address is the same.

## InsufficientDebtAllowance

```solidity
error InsufficientDebtAllowance(address debtor, uint256 allowance, uint256 needed)
```

Emitted when the debt allowance of a debtor is insufficient.

*Used in the debt minting function.*

### Parameters

| Name      | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| debtor    | address | Address of the debtor.                  |
| allowance | uint256 | Maximum debt allowance of the debtor.   |
| needed    | uint256 | Requested amount of debt of the debtor. |

## ExcessiveDebtRepayment

```solidity
error ExcessiveDebtRepayment(address debtor, uint256 debt, uint256 needed)
```

Emitted when the debt of the debtor is insufficient - the debtor tries to repay more than they borrowed.

*Used in the debt repayment function.*

### Parameters

| Name   | Type    | Description                                   |
| ------ | ------- | --------------------------------------------- |
| debtor | address | Address of the debtor.                        |
| debt   | uint256 | Current debt of the debtor.                   |
| needed | uint256 | Requested amount of assets repaying the debt. |

## constructor

```solidity
constructor() public
```

## initialize

```solidity
function initialize(contract IERC20 asset, address _treasury) public
```

## updateTreasury

```solidity
function updateTreasury(address newTreasury) external
```

Updates treasury wallet address.

### Parameters

| Name        | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| newTreasury | address | New treasury wallet address. |

## updateMinimumDepositAmount

```solidity
function updateMinimumDepositAmount(uint256 newMinimumDepositAmount) external
```

Updates minimum deposit amount.

### Parameters

| Name                    | Type    | Description                                                                                       |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| newMinimumDepositAmount | uint256 | New value of the minimum deposit amount. It is the minimum amount for a single deposit operation. |

## updateDispatcher

```solidity
function updateDispatcher(contract IDispatcher newDispatcher) external
```

Updates the dispatcher contract and gives it an unlimited allowance to transfer deposited tBTC.

### Parameters

| Name          | Type                 | Description                             |
| ------------- | -------------------- | --------------------------------------- |
| newDispatcher | contract IDispatcher | Address of the new dispatcher contract. |

## updateEntryFeeBasisPoints

```solidity
function updateEntryFeeBasisPoints(uint256 newEntryFeeBasisPoints) external
```

Update the entry fee basis points.

### Parameters

| Name                   | Type    | Description                        |
| ---------------------- | ------- | ---------------------------------- |
| newEntryFeeBasisPoints | uint256 | New value of the fee basis points. |

## updateExitFeeBasisPoints

```solidity
function updateExitFeeBasisPoints(uint256 newExitFeeBasisPoints) external
```

Update the exit fee basis points.

### Parameters

| Name                  | Type    | Description                        |
| --------------------- | ------- | ---------------------------------- |
| newExitFeeBasisPoints | uint256 | New value of the fee basis points. |

## approveAndCall

```solidity
function approveAndCall(address spender, uint256 value, bytes extraData) external returns (bool)
```

Calls `receiveApproval` function on spender previously approving the spender to withdraw from the caller multiple times, up to the `value` amount. If this function is called again, it overwrites the current allowance with `value`. Reverts if the approval reverted or if `receiveApproval` call on the spender reverted.

*If the `value` is set to `type(uint256).max` then `transferFrom` and `burnFrom` will not reduce an allowance.*

### Parameters

| Name      | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| spender   | address | The address which will spend the funds. |
| value     | uint256 | The amount of tokens to be spent.       |
| extraData | bytes   | Additional data.                        |

### Return Values

| Name | Type | Description                                                  |
| ---- | ---- | ------------------------------------------------------------ |
| \[0] | bool | True if both approval and `receiveApproval` calls succeeded. |

## disableNonFungibleWithdrawals

```solidity
function disableNonFungibleWithdrawals() external
```

Disables non-fungible withdrawals.

## updateDebtAllowance

```solidity
function updateDebtAllowance(address debtor, uint256 newAllowance) external
```

Sets the maximum debt allowance of the debtor.

*The current debt value is intentionally not checked to allow the governance reduce the debt allowance in case the depositor becomes risky or malicious.*

### Parameters

| Name         | Type    | Description                           |
| ------------ | ------- | ------------------------------------- |
| debtor       | address | Address of the debtor.                |
| newAllowance | uint256 | Maximum debt allowance of the debtor. |

## mintDebt

```solidity
function mintDebt(uint256 shares, address receiver) public returns (uint256 assets)
```

Mints the requested amount of shares and registers a debt in asset corresponding to the minted amount of shares.

*The debt is calculated based on the current conversion rate from the shares to assets.*

### Parameters

| Name     | Type    | Description                   |
| -------- | ------- | ----------------------------- |
| shares   | uint256 | The amount of shares to mint. |
| receiver | address | The receiver of the shares.   |

### Return Values

| Name   | Type    | Description                                           |
| ------ | ------- | ----------------------------------------------------- |
| assets | uint256 | The debt amount in asset taken for the shares minted. |

## mintReceipt

```solidity
function mintReceipt(address to, uint256 amount) external
```

*This function proxies `mintDebt` call and provides compatibility with Mezo IReceiptToken interface.*

## repayDebt

```solidity
function repayDebt(uint256 shares) public returns (uint256 assets)
```

Repay the asset debt, fully of partially with the provided shares.

*The debt to be repaid is calculated based on the current conversion rate from the shares to assets. The debtor has to approve the transfer of the shares. To determine the asset debt that is going to be repaid, the caller can use the `previewRepayDebt` function.*

### Parameters

| Name   | Type    | Description                     |
| ------ | ------- | ------------------------------- |
| shares | uint256 | The amount of shares to return. |

### Return Values

| Name   | Type    | Description                           |
| ------ | ------- | ------------------------------------- |
| assets | uint256 | The amount of debt in asset paid off. |

## burnReceipt

```solidity
function burnReceipt(uint256 amount) external
```

This function proxies `repayDebt` call and provides compatibility with Mezo IReceiptToken interface.

## deposit

```solidity
function deposit(uint256 assets, address receiver) public returns (uint256)
```

Mints shares to receiver by depositing exactly amount of tBTC tokens.

*Takes into account a deposit parameter, minimum deposit amount, which determines the minimum amount for a single deposit operation. The amount of the assets has to be pre-approved in the tBTC contract.*

### Parameters

| Name     | Type    | Description                                                                                |
| -------- | ------- | ------------------------------------------------------------------------------------------ |
| assets   | uint256 | Approved amount of tBTC tokens to deposit. This includes treasury fees for deposited tBTC. |
| receiver | address | The address to which the shares will be minted.                                            |

### Return Values

| Name | Type    | Description                                                |
| ---- | ------- | ---------------------------------------------------------- |
| \[0] | uint256 | Minted shares adjusted for the fees taken by the treasury. |

## mint

```solidity
function mint(uint256 shares, address receiver) public returns (uint256 assets)
```

Mints shares to receiver by depositing tBTC tokens.

*Takes into account a deposit parameter, minimum deposit amount, which determines the minimum amount for a single deposit operation. The amount of the assets has to be pre-approved in the tBTC contract. The msg.sender is required to grant approval for the transfer of a certain amount of tBTC, and in addition, approval for the associated fee. Specifically, the total amount to be approved (amountToApprove) should be equal to the sum of the deposited amount and the fee. To determine the total assets amount necessary for approval corresponding to a given share amount, use the `previewMint` function.*

### Parameters

| Name     | Type    | Description                                     |
| -------- | ------- | ----------------------------------------------- |
| shares   | uint256 | Amount of shares to mint.                       |
| receiver | address | The address to which the shares will be minted. |

### Return Values

| Name   | Type    | Description                 |
| ------ | ------- | --------------------------- |
| assets | uint256 | Used assets to mint shares. |

## withdraw

```solidity
function withdraw(uint256 assets, address receiver, address owner) public returns (uint256)
```

Withdraws assets from the vault and transfers them to the receiver.

*Withdraw unallocated assets first and and if not enough, then pull the assets from the dispatcher.*

### Parameters

| Name     | Type    | Description                                          |
| -------- | ------- | ---------------------------------------------------- |
| assets   | uint256 | Amount of assets to withdraw.                        |
| receiver | address | The address to which the assets will be transferred. |
| owner    | address | The address of the owner of the shares.              |

## redeem

```solidity
function redeem(uint256 shares, address receiver, address owner) public returns (uint256)
```

Redeems shares for assets and transfers them to the receiver.

*Redeem unallocated assets first and and if not enough, then pull the assets from the dispatcher.*

### Parameters

| Name     | Type    | Description                                          |
| -------- | ------- | ---------------------------------------------------- |
| shares   | uint256 | Amount of shares to redeem.                          |
| receiver | address | The address to which the assets will be transferred. |
| owner    | address | The address of the owner of the shares.              |

## totalAssets

```solidity
function totalAssets() public view returns (uint256)
```

Returns the total amount of assets held by the vault across all allocations and this contract.

*The value contains virtual assets reflecting the debt minted by the debtors. The debt is not backed by the deposited assets, and it is used to adjust the total assets held by the vault, to allow shares and assets conversion calculations.*

## maxDeposit

```solidity
function maxDeposit(address) public view returns (uint256)
```

*Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver, through a deposit call. If the Vault is paused, returns 0.*

## maxMint

```solidity
function maxMint(address) public view returns (uint256)
```

*Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call. If the Vault is paused, returns 0.*

## maxWithdraw

```solidity
function maxWithdraw(address owner) public view returns (uint256)
```

*Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the Vault, through a withdraw call. If the Vault is paused, returns 0.*

## maxRedeem

```solidity
function maxRedeem(address owner) public view returns (uint256)
```

*Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault, through a redeem call. If the Vault is paused, returns 0.*

## assetsBalanceOf

```solidity
function assetsBalanceOf(address account) public view returns (uint256)
```

Returns the number of assets that corresponds to the amount of shares held by the specified account.

*This function is used to convert shares to assets position for the given account. It does not take fees into account.*

### Parameters

| Name    | Type    | Description              |
| ------- | ------- | ------------------------ |
| account | address | The owner of the shares. |

### Return Values

| Name | Type    | Description           |
| ---- | ------- | --------------------- |
| \[0] | uint256 | The amount of assets. |

## previewRepayDebt

```solidity
function previewRepayDebt(uint256 shares) public view returns (uint256)
```

Previews the amount of assets that will be burned for the given amount of repaid shares.

## \_entryFeeBasisPoints

```solidity
function _entryFeeBasisPoints() internal view returns (uint256)
```

### Return Values

| Name | Type    | Description                                     |
| ---- | ------- | ----------------------------------------------- |
| \[0] | uint256 | Returns entry fee basis point used in deposits. |

## \_exitFeeBasisPoints

```solidity
function _exitFeeBasisPoints() internal view returns (uint256)
```

### Return Values

| Name | Type    | Description                                       |
| ---- | ------- | ------------------------------------------------- |
| \[0] | uint256 | Returns exit fee basis point used in withdrawals. |

## \_feeRecipient

```solidity
function _feeRecipient() internal view returns (address)
```

Returns the address of the treasury wallet, where fees should be transferred to.


---

# 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.acre.fi/api/stbtc.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.