# 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. ```solidity enum DepositState { Unknown, Initialized, Finalized } ``` ## deposits ```solidity 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 ```solidity contract IERC20 tbtcToken ``` tBTC Token contract. ## stbtc ```solidity contract stBTC stbtc ``` stBTC contract. ## minDepositAmount ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity error TbtcTokenZeroAddress() ``` Reverts if the tBTC Token address is zero. ## StbtcZeroAddress ```solidity error StbtcZeroAddress() ``` Reverts if the stBTC address is zero. ## DepositOwnerIsZeroAddress ```solidity error DepositOwnerIsZeroAddress() ``` *Deposit owner address is zero.* ## UnexpectedDepositState ```solidity error UnexpectedDepositState(enum BitcoinDepositor.DepositState actualState, enum BitcoinDepositor.DepositState expectedState) ``` *Attempted to execute function for deposit in unexpected current state.* ## DepositorFeeExceedsBridgedAmount ```solidity error DepositorFeeExceedsBridgedAmount(uint256 depositorFee, uint256 bridgedAmount) ``` *Calculated depositor fee exceeds the amount of minted tBTC tokens.* ## MinDepositAmountLowerThanBridgeMinDeposit ```solidity error MinDepositAmountLowerThanBridgeMinDeposit(uint256 minDepositAmount, uint256 bridgeMinDepositAmount) ``` *Attempted to set minimum deposit amount to a value lower than the tBTC Bridge deposit dust threshold.* ## constructor ```solidity constructor() public ``` ## initialize ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity function updateDepositorFeeDivisor(uint64 newDepositorFeeDivisor) external ``` Updates the depositor fee divisor. ### Parameters | Name | Type | Description | | ---------------------- | ------ | -------------------------------- | | newDepositorFeeDivisor | uint64 | New depositor fee divisor value. | ## encodeExtraData ```solidity 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 ```solidity 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. | --- # 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/bitcoindepositor.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.