Threshold Network 백서 전문

grade ```solidity function initiateUpgrade(address _newVault) external ``` Initiates vault upgrade process. The upgrade process needs to be finalized with a call to `finalizeUpgrade` function after the `UPGRADE_GOVERNANCE_DELAY` passes. Only the governance can initiate the upgrade. #### Parameters | Name | Type | Description | | ---------- | ------- | ---------------------- | | \_newVault | address | The new vault address. | ### finalizeUpgrade ```solidity function finalizeUpgrade() external ``` Allows the governance to finalize vault upgrade process. The upgrade process needs to be first initiated with a call to `initiateUpgrade` and the `GOVERNANCE_DELAY` needs to pass. Once the upgrade is finalized, the new vault becomes the owner of the TBTC token and receives the whole Bank balance of this vault. ### recoverERC20FromToken ```solidity function recoverERC20FromToken(contract IERC20 token, address recipient, uint256 amount) external ``` Allows the governance of the TBTCVault to recover any ERC20 token sent mistakenly to the TBTC token contract address. #### Parameters | Name | Type | Description | | --------- | --------------- | ---------------------------------------------- | | token | contract IERC20 | Address of the recovered ERC20 token contract. | | recipient | address | Address the recovered token should be sent to. | | amount | uint256 | Recovered amount. | ### recoverERC721FromToken ```solidity function recoverERC721FromToken(contract IERC721 token, address recipient, uint256 tokenId, bytes data) external ``` Allows the governance of the TBTCVault to recover any ERC721 token sent mistakenly to the TBTC token contract address. #### Parameters | Name | Type | Description | | --------- | ---------------- | ----------------------------------------------- | | token | contract IERC721 | Address of the recovered ERC721 token contract. | | recipient | address | Address the recovered token should be sent to. | | tokenId | uint256 | Identifier of the recovered token. | | data | bytes | Additional data. | ### recoverERC20 ```solidity function recoverERC20(contract IERC20 token, address recipient, uint256 amount) external ``` Allows the governance of the TBTCVault to recover any ERC20 token sent - mistakenly or not - to the vault address. This function should be used to withdraw TBTC v1 tokens transferred to TBTCVault as a result of VendingMachine > TBTCVault upgrade. #### Parameters | Name | Type | Description | | --------- | --------------- | ---------------------------------------------- | | token | contract IERC20 | Address of the recovered ERC20 token contract. | | recipient | address | Address the recovered token should be sent to. | | amount | uint256 | Recovered amount. | ### recoverERC721 ```solidity function recoverERC721(contract IERC721 token, address recipient, uint256 tokenId, bytes data) external ``` Allows the governance of the TBTCVault to recover any ERC721 token sent mistakenly to the vault address. #### Parameters | Name | Type | Description | | --------- | ---------------- | ----------------------------------------------- | | token | contract IERC721 | Address of the recovered ERC721 token contract. | | recipient | address | Address the recovered token should be sent to. | | tokenId | uint256 | Identifier of the recovered token. | | data | bytes | Additional data. | ### amountToSatoshis ```solidity function amountToSatoshis(uint256 amount) public view returns (uint256 convertibleAmount, uint256 remainder, uint256 satoshis) ``` Returns the amount of TBTC to be minted/unminted, the remainder, and the Bank balance to be transferred for the given mint/unmint. Note that if the `amount` is not divisible by SATOSHI\_MULTIPLIER, the remainder is left on the caller's account when minting or unminting. #### Return Values | Name | Type | Description | | ----------------- | ------- | --------------------------------------------------------------------------------- | | convertibleAmount | uint256 | Amount of TBTC to be minted/unminted. | | remainder | uint256 | Not convertible remainder if amount is not divisible by SATOSHI\_MULTIPLIER. | | satoshis | uint256 | Amount in satoshis - the Bank balance to be transferred for the given mint/unmint | ### \_mint ```solidity function _mint(address minter, uint256 amount) internal ``` Mints the given amount of TBTC to the given depositor's address. Implemented by TBTCVault. ### \_unmint ```solidity function _unmint(address unminter, uint256 amount) internal ``` `amount` MUST be divisible by SATOSHI\_MULTIPLIER with no change. ### \_unmintAndRedeem ```solidity function _unmintAndRedeem(address redeemer, uint256 amount, bytes redemptionData) internal ``` `amount` MUST be divisible by SATOSHI\_MULTIPLIER with no change. # VendingMachine ## VendingMachine The Vending Machine is the owner of TBTC v2 token and can mint TBTC v2 tokens in 1:1 ratio from TBTC v1 tokens with TBTC v1 deposited in the contract as collateral. TBTC v2 can be unminted back to TBTC v1 with or without a fee - fee parameter is controlled by the Governance. This implementation acts as a bridge between TBTC v1 and TBTC v2 token, allowing to mint TBTC v2 before the system is ready and fully operational without sacrificing any security guarantees and decentralization of the project. Vending Machine can be upgraded in a two-step, governance-controlled process. The new version of the Vending Machine will receive the ownership of TBTC v2 token and entire TBTC v1 balance stored as collateral. It is expected that this process will be executed before the v2 system launch. There is an optional unmint fee with a value that can be updated in a two-step, governance-controlled process. All governable parameters are controlled by two roles: update initiator and finalizer. There is a separate initiator role for unmint fee update and vending machine upgrade. The initiator proposes the change by initiating the update and the finalizer (contract owner) may approve it by finalizing the change after the governance delay passes. ### GOVERNANCE\_DELAY ```solidity uint256 GOVERNANCE_DELAY ``` The time delay that needs to pass between initializing and finalizing update of any governable parameter in this contract. ### FLOATING\_POINT\_DIVISOR ```solidity uint256 FLOATING_POINT_DIVISOR ``` Divisor for precision purposes. Used to represent fractions in parameter values. ### tbtcV1 ```solidity contract IERC20 tbtcV1 ``` ### tbtcV2 ```solidity contract TBTC tbtcV2 ``` ### unmintFee ```solidity uint256 unmintFee ``` The fee for unminting TBTC v2 back into TBTC v1 represented as 1e18 precision fraction. The fee is proportional to the amount being unminted and added on the top of the amount being unminted. To calculate the fee value, the amount being unminted needs to be multiplied by `unmintFee` and divided by 1e18. For example, `unmintFee` set to 1000000000000000 means that 0.001 of the amount being unminted needs to be paid to the `VendingMachine` as an unminting fee on the top of the amount being unminted. ### newUnmintFee ```solidity uint256 newUnmintFee ``` ### unmintFeeUpdateInitiatedTimestamp ```solidity uint256 unmintFeeUpdateInitiatedTimestamp ``` ### unmintFeeUpdateInitiator ```solidity address unmintFeeUpdateInitiator ``` ### newVendingMachine ```solidity address newVendingMachine ``` The address of a new vending machine. Set only when the upgrade process is pending. Once the upgrade gets finalized, the new vending machine will become an owner of TBTC v2 token. ### vendingMachineUpgradeInitiatedTimestamp ```solidity uint256 vendingMachineUpgradeInitiatedTimestamp ``` ### vendingMachineUpgradeInitiator ```solidity address vendingMachineUpgradeInitiator ``` ### UnmintFeeUpdateInitiated ```solidity event UnmintFeeUpdateInitiated(uint256 newUnmintFee, uint256 timestamp) ``` ### UnmintFeeUpdated ```solidity event UnmintFeeUpdated(uint256 newUnmintFee) ``` ### VendingMachineUpgradeInitiated ```solidity event VendingMachineUpgradeInitiated(address newVendingMachine, uint256 timestamp) ``` ### VendingMachineUpgraded ```solidity event VendingMachineUpgraded(address newVendingMachine) ``` ### Minted ```solidity event Minted(address recipient, uint256 amount) ``` ### Unminted ```solidity event Unminted(address recipient, uint256 amount, uint256 fee) ``` ### only ```solidity modifier only(address authorizedCaller) ``` ### onlyAfterGovernanceDelay ```solidity modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) ``` ### constructor ```solidity constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2, uint256 _unmintFee) public ``` ### mint ```solidity function mint(uint256 amount) external ``` Mints TBTC v2 to the caller from TBTC v1 with 1:1 ratio. The caller needs to have at least `amount` of TBTC v1 balance approved for transfer to the `VendingMachine` before calling this function. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------------ | | amount | uint256 | The amount of TBTC v2 to mint from TBTC v1 | ### receiveApproval ```solidity function receiveApproval(address from, uint256 amount, address token, bytes) external ``` Mints TBTC v2 to `from` address from TBTC v1 with 1:1 ratio. `from` address needs to have at least `amount` of TBTC v1 balance approved for transfer to the `VendingMachine` before calling this function. This function is a shortcut for approve + mint. Only TBTC v1 caller is allowed and only TBTC v1 is allowed as a token to transfer. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------------- | | from | address | TBTC v1 token holder minting TBTC v2 tokens | | amount | uint256 | The amount of TBTC v2 to mint from TBTC v1 | | token | address | TBTC v1 token address | | | bytes | | ### unmint ```solidity function unmint(uint256 amount) external ``` Unmints TBTC v2 from the caller into TBTC v1. Depending on `unmintFee` value, may require paying an additional unmint fee in TBTC v2 in addition to the amount being unminted. To see what is the value of the fee, please call `unmintFeeFor(amount)` function. The caller needs to have at least `amount + unmintFeeFor(amount)` of TBTC v2 balance approved for transfer to the `VendingMachine` before calling this function. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------------ | | amount | uint256 | The amount of TBTC v2 to unmint to TBTC v1 | ### withdrawFees ```solidity function withdrawFees(address recipient, uint256 amount) external ``` Allows the Governance to withdraw unmint fees accumulated by `VendingMachine`. #### Parameters | Name | Type | Description | | --------- | ------- | ----------------------------------------- | | recipient | address | The address receiving the fees | | amount | uint256 | The amount of fees in TBTC v2 to withdraw | ### initiateUnmintFeeUpdate ```solidity function initiateUnmintFeeUpdate(uint256 _newUnmintFee) external ``` Initiates unmint fee update process. The update process needs to be finalized with a call to `finalizeUnmintFeeUpdate` function after the `GOVERNANCE_DELAY` passes. Only unmint fee update initiator role can initiate the update. #### Parameters | Name | Type | Description | | -------------- | ------- | ------------------ | | \_newUnmintFee | uint256 | The new unmint fee | ### finalizeUnmintFeeUpdate ```solidity function finalizeUnmintFeeUpdate() external ``` Allows the contract owner to finalize unmint fee update process. The update process needs to be first initiated with a call to `initiateUnmintFeeUpdate` and the `GOVERNANCE_DELAY` needs to pass. ### initiateVendingMachineUpgrade ```solidity function initiateVendingMachineUpgrade(address _newVendingMachine) external ``` Initiates vending machine upgrade process. The upgrade process needs to be finalized with a call to `finalizeVendingMachineUpgrade` function after the `GOVERNANCE_DELAY` passes. Only vending machine upgrade initiator role can initiate the upgrade. #### Parameters | Name | Type | Description | | ------------------- | ------- | ------------------------------- | | \_newVendingMachine | address | The new vending machine address | ### finalizeVendingMachineUpgrade ```solidity function finalizeVendingMachineUpgrade() external ``` Allows the contract owner to finalize vending machine upgrade process. The upgrade process needs to be first initiated with a call to `initiateVendingMachineUpgrade` and the `GOVERNANCE_DELAY` needs to pass. Once the upgrade is finalized, the new vending machine will become an owner of TBTC v2 token and all TBTC v1 held by this contract will be transferred to the new vending machine. ### transferUnmintFeeUpdateInitiatorRole ```solidity function transferUnmintFeeUpdateInitiatorRole(address newInitiator) external ``` Transfers unmint fee update initiator role to another address. Can be called only by the current unmint fee update initiator. #### Parameters | Name | Type | Description | | ------------ | ------- | ----------------------------------- | | newInitiator | address | The new unmint fee update initiator | ### transferVendingMachineUpgradeInitiatorRole ```solidity function transferVendingMachineUpgradeInitiatorRole(address newInitiator) external ``` Transfers vending machine upgrade initiator role to another address. Can be called only by the current vending machine upgrade initiator. #### Parameters | Name | Type | Description | | ------------ | ------- | ----------------------------------------- | | newInitiator | address | The new vending machine upgrade initiator | ### getRemainingUnmintFeeUpdateTime ```solidity function getRemainingUnmintFeeUpdateTime() external view returns (uint256) ``` Get the remaining time that needs to pass until unmint fee update can be finalized by the Governance. If the update has not been initiated, the function reverts. ### getRemainingVendingMachineUpgradeTime ```solidity function getRemainingVendingMachineUpgradeTime() external view returns (uint256) ``` Get the remaining time that needs to pass until vending machine upgrade can be finalized by the Governance. If the upgrade has not been initiated, the function reverts. ### unmintFeeFor ```solidity function unmintFeeFor(uint256 amount) public view returns (uint256) ``` Calculates the fee that needs to be paid to the `VendingMachine` to unmint the given amount of TBTC v2 back into TBTC v1. ### \_mint ```solidity function _mint(address tokenOwner, uint256 amount) internal ``` # VendingMachineV2 ## VendingMachineV2 VendingMachineV2 is used to exchange tBTC v1 to tBTC v2 in a 1:1 ratio during the process of tBTC v1 bridge sunsetting. The redeemer selected by the DAO based on the "TIP-027b tBTC v1: The Sunsetting" proposal will deposit tBTC v2 tokens into VendingMachineV2 so that outstanding tBTC v1 token owners can upgrade to tBTC v2 tokens. The redeemer will withdraw the tBTC v1 tokens deposited into the contract to perform tBTC v1 redemptions. The redeemer may decide to withdraw their deposited tBTC v2 at any moment in time. The amount withdrawable is lower than the amount deposited in case tBTC v1 was exchanged for tBTC v2. This contract is owned by the redeemer. ### tbtcV1 ```solidity contract IERC20 tbtcV1 ``` ### tbtcV2 ```solidity contract TBTC tbtcV2 ``` ### Exchanged ```solidity event Exchanged(address to, uint256 amount) ``` ### Deposited ```solidity event Deposited(address from, uint256 amount) ``` ### Withdrawn ```solidity event Withdrawn(address token, address to, uint256 amount) ``` ### constructor ```solidity constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public ``` ### exchange ```solidity function exchange(uint256 amount) external ``` Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. The caller needs to have at least `amount` of tBTC v1 balance approved for transfer to the `VendingMachineV2` before calling this function. #### Parameters | Name | Type | Description | | ------ | ------- | ---------------------------------------------- | | amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | ### receiveApproval ```solidity function receiveApproval(address from, uint256 amount, address token, bytes) external ``` Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. The caller needs to have at least `amount` of tBTC v1 balance approved for transfer to the `VendingMachineV2` before calling this function. This function is a shortcut for `approve` + `exchange`. Only tBTC v1 token caller is allowed and only tBTC v1 is allowed as a token to transfer. #### Parameters | Name | Type | Description | | ------ | ------- | --------------------------------------------------- | | from | address | tBTC v1 token holder exchanging tBTC v1 to tBTC v2. | | amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | | token | address | tBTC v1 token address. | | | bytes | | ### depositTbtcV2 ```solidity function depositTbtcV2(uint256 amount) external ``` Allows to deposit tBTC v2 tokens to the contract. VendingMachineV2 can not mint tBTC v2 tokens so tBTC v2 needs to be deposited into the contract so that tBTC v1 to tBTC v2 exchange can happen. The caller needs to have at least `amount` of tBTC v2 balance approved for transfer to the `VendingMachineV2` before calling this function. This function is for the redeemer and tBTC v1 operators. This is NOT a function for tBTC v1 token holders. #### Parameters | Name | Type | Description | | ------ | ------- | --------------------------------------------------- | | amount | uint256 | The amount of tBTC v2 to deposit into the contract. | ### withdrawFunds ```solidity function withdrawFunds(contract IERC20 token, address recipient, uint256 amount) external ``` Allows the contract owner to withdraw tokens. This function is used in two cases: 1) when the redeemer wants to redeem tBTC v1 tokens to perform tBTC v2 redemptions; 2) when the deadline for tBTC v1 -> tBTC v2 exchange passed and the redeemer wants their tBTC v2 back. This function is for the redeemer. This is NOT a function for tBTC v1 token holders. #### Parameters | Name | Type | Description | | --------- | --------------- | -------------------------------------------------- | | token | contract IERC20 | The address of a token to withdraw. | | recipient | address | The address which should receive withdrawn tokens. | | amount | uint256 | The amount to withdraw. | ### \_exchange ```solidity function _exchange(address tokenOwner, uint256 amount) internal ``` # VendingMachineV3 ## VendingMachineV3 VendingMachineV3 is used to exchange tBTC v1 to tBTC v2 in a 1:1 ratio after the tBTC v1 bridge sunsetting is completed. Since tBTC v1 bridge is no longer working, tBTC v1 tokens can not be used to perform BTC redemptions. This contract allows tBTC v1 owners to upgrade to tBTC v2 without any deadline. This way, tBTC v1 tokens left on the market are always backed by Bitcoin. The governance will deposit tBTC v2 into the contract in the amount equal to tBTC v1 supply. The governance is allowed to withdraw tBTC v2 only if tBTC v2 left in this contract is enough to cover the upgrade of all tBTC v1 left on the market. This contract is owned by the governance. ### tbtcV1 ```solidity contract IERC20 tbtcV1 ``` ### tbtcV2 ```solidity contract TBTC tbtcV2 ``` ### Exchanged ```solidity event Exchanged(address to, uint256 amount) ``` ### Deposited ```solidity event Deposited(address from, uint256 amount) ``` ### TbtcV2Withdrawn ```solidity event TbtcV2Withdrawn(address to, uint256 amount) ``` ### FundsRecovered ```solidity event FundsRecovered(address token, address to, uint256 amount) ``` ### constructor ```solidity constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public ``` ### exchange ```solidity function exchange(uint256 amount) external ``` Exchange tBTC v1 for tBTC v2 in a