BitcoinDepositor

The contract integrates Acre depositing with tBTC minting. User who wants to deposit BTC in Acre should submit a Bitcoin transaction to the most recently created off-chain ECDSA wallets of the tBTC Bridge using pay-to-script-hash (P2SH) or pay-to-witness-script-hash (P2WSH) containing hashed information about this Depositor contract address, and deposit owner's Ethereum address. Then, the deposit owner initiates tBTC minting by revealing their Ethereum address along with their deposit blinding factor, refund public key hash and refund locktime on the tBTC Bridge through this Depositor contract. The off-chain ECDSA wallet and Optimistic Minting bots listen for these sorts of messages and when they get one, they check the Bitcoin network to make sure the deposit lines up. Majority of tBTC minting is finalized by the Optimistic Minting process, where Minter bot initializes minting process and if there is no veto from the Guardians, the process is finalized and tBTC minted to the Depositor address. If the revealed deposit is not handled by the Optimistic Minting process the off-chain ECDSA wallet may decide to pick the deposit transaction for sweeping, and when the sweep operation is confirmed on the Bitcoin network, the tBTC Bridge and tBTC vault mint the tBTC token to the Depositor address. After tBTC is minted to the Depositor, on the deposit finalization tBTC is deposited in Acre and stBTC shares are emitted to the deposit owner.

DepositState

Reflects the deposit state: - Unknown deposit has not been initialized yet. - Initialized deposit has been initialized with a call to initializeDeposit function and is known to this contract. - Finalized deposit led to tBTC ERC20 minting and was finalized with a call to finalizeDeposit function that deposited tBTC to the stBTC contract.

enum DepositState {
  Unknown,
  Initialized,
  Finalized
}

deposits

mapping(uint256 => enum BitcoinDepositor.DepositState) deposits

Holds the deposit state, keyed by the deposit key calculated for the individual deposit during the call to initializeDeposit function.

tbtcToken

contract IERC20 tbtcToken

tBTC Token contract.

stbtc

contract stBTC stbtc

stBTC contract.

minDepositAmount

uint256 minDepositAmount

Minimum amount of a single deposit (in tBTC token precision).

This parameter should be set to a value exceeding the minimum deposit amount supported by the tBTC Bridge.

depositorFeeDivisor

uint64 depositorFeeDivisor

Divisor used to compute the depositor fee taken from each deposit and transferred to the treasury upon deposit finalization.

That fee is computed as follows: depositorFee = depositedAmount / depositorFeeDivisor for example, if the depositor fee needs to be 2% of each deposit, the depositorFeeDivisor should be set to 50 because 1/50 = 0.02 = 2%.

DepositInitialized

event DepositInitialized(uint256 depositKey, address caller, address depositOwner, uint256 initialAmount)

Emitted when a deposit is initialized.

Deposit details can be fetched from {{ Bridge.DepositRevealed }} event emitted in the same transaction.

Parameters

Name	Type	Description
depositKey	uint256	Deposit key identifying the deposit.
caller	address	Address that initialized the deposit.
depositOwner	address	The address to which the stBTC shares will be minted.
initialAmount	uint256	Amount of funding transaction.

DepositFinalized

event DepositFinalized(uint256 depositKey, address caller, uint16 referral, uint256 initialAmount, uint256 bridgedAmount, uint256 depositorFee)

Emitted when a deposit is finalized.

Deposit details can be fetched from {{ ERC4626.Deposit }} event emitted in the same transaction.

Parameters

Name	Type	Description
depositKey	uint256	Deposit key identifying the deposit.
caller	address	Address that finalized the deposit.
referral	uint16	Data used for referral program.
initialAmount	uint256	Amount of funding transaction.
bridgedAmount	uint256	Amount of tBTC tokens that was bridged by the tBTC bridge.
depositorFee	uint256	Depositor fee amount.

MinDepositAmountUpdated

event MinDepositAmountUpdated(uint256 minDepositAmount)

Emitted when a minimum single deposit amount is updated.

Parameters

Name	Type	Description
minDepositAmount	uint256	New value of the minimum single deposit amount (in tBTC token precision).

DepositorFeeDivisorUpdated

event DepositorFeeDivisorUpdated(uint64 depositorFeeDivisor)

Emitted when a depositor fee divisor is updated.

Parameters

Name	Type	Description
depositorFeeDivisor	uint64	New value of the depositor fee divisor.

TbtcTokenZeroAddress

error TbtcTokenZeroAddress()

Reverts if the tBTC Token address is zero.

StbtcZeroAddress

error StbtcZeroAddress()

Reverts if the stBTC address is zero.

DepositOwnerIsZeroAddress

error DepositOwnerIsZeroAddress()

Deposit owner address is zero.

UnexpectedDepositState

error UnexpectedDepositState(enum BitcoinDepositor.DepositState actualState, enum BitcoinDepositor.DepositState expectedState)

Attempted to execute function for deposit in unexpected current state.

DepositorFeeExceedsBridgedAmount

error DepositorFeeExceedsBridgedAmount(uint256 depositorFee, uint256 bridgedAmount)

Calculated depositor fee exceeds the amount of minted tBTC tokens.

MinDepositAmountLowerThanBridgeMinDeposit

error MinDepositAmountLowerThanBridgeMinDeposit(uint256 minDepositAmount, uint256 bridgeMinDepositAmount)

Attempted to set minimum deposit amount to a value lower than the tBTC Bridge deposit dust threshold.

constructor

constructor() public

initialize

function initialize(address bridge, address tbtcVault, address _tbtcToken, address _stbtc) public

Bitcoin Depositor contract initializer.

Parameters

Name	Type	Description
bridge	address	tBTC Bridge contract instance.
tbtcVault	address	tBTC Vault contract instance.
_tbtcToken	address	tBTC token contract instance.
_stbtc	address	stBTC contract instance.

initializeDeposit

function initializeDeposit(struct IBridgeTypes.BitcoinTxInfo fundingTx, struct IBridgeTypes.DepositRevealInfo reveal, address depositOwner, uint16 referral) external

This function allows depositing process initialization for a Bitcoin deposit made by an user with a P2(W)SH transaction. It uses the supplied information to reveal a deposit to the tBTC Bridge contract.

Requirements: - The revealed vault address must match the TBTCVault address, - All requirements from {Bridge#revealDepositWithExtraData} function must be met. - depositOwner must be the deposit owner address used in the P2(W)SH BTC deposit transaction as part of the extra data. - referral must be the referral info used in the P2(W)SH BTC deposit transaction as part of the extra data. - BTC deposit for the given fundingTxHash, fundingOutputIndex can be revealed only one time.

Parameters

Name	Type	Description
fundingTx	struct IBridgeTypes.BitcoinTxInfo	Bitcoin funding transaction data, see IBridgeTypes.BitcoinTxInfo.
reveal	struct IBridgeTypes.DepositRevealInfo	Deposit reveal data, see IBridgeTypes.DepositRevealInfo.
depositOwner	address	The address to which the stBTC shares will be minted.
referral	uint16	Data used for referral program.

finalizeDeposit

function finalizeDeposit(uint256 depositKey) external

This function should be called for previously initialized deposit request, after tBTC minting process completed, meaning tBTC was minted to this contract.

_It calculates the amount to deposit based on the approximate minted tBTC amount reduced by the depositor fee. IMPORTANT NOTE: The minted tBTC amount used by this function is an approximation. See documentation of the {{AbstractTBTCDepositor#calculateTbtcAmount}} responsible for calculating this value for more details.

Parameters

Name	Type	Description
depositKey	uint256	Deposit key identifying the deposit.

updateMinDepositAmount

function updateMinDepositAmount(uint256 newMinDepositAmount) external

Updates the minimum deposit amount.

It requires that the new value is greater or equal to the tBTC Bridge deposit dust threshold, to ensure deposit will be able to be bridged.

Parameters

Name	Type	Description
newMinDepositAmount	uint256	New minimum deposit amount (in tBTC precision).

updateDepositorFeeDivisor

function updateDepositorFeeDivisor(uint64 newDepositorFeeDivisor) external

Updates the depositor fee divisor.

Parameters

Name	Type	Description
newDepositorFeeDivisor	uint64	New depositor fee divisor value.

encodeExtraData

function encodeExtraData(address depositOwner, uint16 referral) public pure returns (bytes32)

Encodes deposit owner address and referral as extra data.

Packs the data to bytes32: 20 bytes of deposit owner address and 2 bytes of referral, 10 bytes of trailing zeros.

Parameters

Name	Type	Description
depositOwner	address	The address to which the stBTC shares will be minted.
referral	uint16	Data used for referral program.

Return Values

Name	Type	Description
[0]	bytes32	Encoded extra data.

decodeExtraData

function decodeExtraData(bytes32 extraData) public pure returns (address depositOwner, uint16 referral)

Decodes deposit owner address and referral from extra data.

Unpacks the data from bytes32: 20 bytes of deposit owner address and 2 bytes of referral, 10 bytes of trailing zeros.

Parameters

Name	Type	Description
extraData	bytes32	Encoded extra data.

Return Values

Name	Type	Description
depositOwner	address	The address to which the stBTC shares will be minted.
referral	uint16	Data used for referral program.