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

contract IDispatcher dispatcher

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

treasury

address treasury

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

minimumDepositAmount

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

uint256 entryFeeBasisPoints

Entry fee basis points applied to entry fee calculation.

exitFeeBasisPoints

uint256 exitFeeBasisPoints

Exit fee basis points applied to exit fee calculation.

allowedDebt

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

mapping(address => uint256) currentDebt

Returns the current debt of the debtor.

totalDebt

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

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

event MinimumDepositAmountUpdated(uint256 minimumDepositAmount)

Emitted when deposit parameters are updated.

Parameters

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

DispatcherUpdated

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

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

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

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

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

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

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

error DisallowedAddress()

Reverts if the address is disallowed.

ExceedsMaxFeeBasisPoints

error ExceedsMaxFeeBasisPoints()

Reverts if the fee basis points exceed the maximum value.

SameTreasury

error SameTreasury()

Reverts if the treasury address is the same.

SameDispatcher

error SameDispatcher()

Reverts if the dispatcher address is the same.

InsufficientDebtAllowance

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

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

constructor() public

initialize

function initialize(contract IERC20 asset, address _treasury) public

updateTreasury

function updateTreasury(address newTreasury) external

Updates treasury wallet address.

Parameters

Name	Type	Description
newTreasury	address	New treasury wallet address.

updateMinimumDepositAmount

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

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

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

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

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

function disableNonFungibleWithdrawals() external

Disables non-fungible withdrawals.

updateDebtAllowance

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

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

function mintReceipt(address to, uint256 amount) external

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

repayDebt

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

function burnReceipt(uint256 amount) external

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

deposit

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

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

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

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

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

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

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

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

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

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

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

function _entryFeeBasisPoints() internal view returns (uint256)

Return Values

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

_exitFeeBasisPoints

function _exitFeeBasisPoints() internal view returns (uint256)

Return Values

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

_feeRecipient

function _feeRecipient() internal view returns (address)

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