# What is the Threshold Network? **Threshold Network powers tBTC, the Bitcoin standard in finance, and the most decentralized 1:1 tokenized Bitcoin.** tBTC enables Bitcoin liquidity to move seamlessly across chains without compromising settlement finality. Built on threshold cryptography and secured by a rotating network of independent node operators, it distributes control of Bitcoin so that no single entity can act alone on funds. This structure upholds Bitcoin’s core principles of being trust-minimized, permissionless, and censorship-resistant while maintaining a direct and verifiable path back to native Bitcoin. No complex staking mechanics needed. Threshold Network's [T token](/t-token) is the value accrual and governance asset for the network. {% hint style="info" %} Threshold Network has been managed by **Threshold Labs (TLabs) since February 2025,** following the approval of DAO proposals [TIP-098](https://forum.threshold.network/t/tip-098-the-future-of-threshold/1012) and [TIP-100](https://forum.threshold.network/t/tip-100-the-future-of-threshold-continued/1033). Threshold Labs, led by *MacLane Wilkison and Callan Sarre,* handles operations, development, and growth of the protocol and tBTC. {% endhint %} # T Token A comprehensive guide to understand Threshold's token: T The [T token](https://etherscan.io/address/0xCdF7028ceAB81fA0C6971208e83fa7872994beE5) is an ERC-20 token that powers tBTC and serves as the value accrual asset for the Threshold Network. As of late, the T token is fully diluted. ### T Token History and Supply Historically, the T token was formed through the merger of two entities, NU and KEEP. Based on the final merger proposal, the conversion ratio for each token is determined by total supply rather than price. During the merger, the supply of NU is approximately 1,380,688,920, and the total supply of KEEP is approximately 940,795,010. Accordingly, the conversion factors are \~3.26 T per NU and \~4.78 T per KEEP. The initial supply of T was established by the DAO at launch as 10Billion T with the following allocation during launch: * 4.5B T allocated to NU token holders * 4.5B T allocated to KEEP token holders * 1B T allocated to the Threshold DAO treasury An additional **1.155B tokens** were minted during the network's inflationary bootstraping phase as incentives for stakers and node operators, resulting in a final total supply of 11,155,000,000 T tokens. *** ### Supply Endpoints * Supply API endpoint - * Total Supply - * Circulating Supply - * Treasury Supply - *** ### Where to access T Tokens **T Token** trades across most major centralized exchanges (Coinbase, Binance, Kraken, KuCoin, Bybit) and leading decentralized exchanges (Uniswap, Curve, Balancer). This gives both institutional and retail participants direct access to the token through fiat on-ramps or self-custodied wallets. For a complete, real-time view of every venue where T is traded, including current pricing, volume, and the full list of active spot markets, refer to [CoinMarketCap's T Markets page](https://coinmarketcap.com/currencies/threshold/). *** ### Using T Tokens T tokens give holders two ways to participate in Threshold Network. 1. **The first is governance:** T holders can vote on proposals that determine how the protocol evolves, from product priorities to fee adjustments to treasury allocation. {% hint style="info" %} For a complete walkthrough of how governance works, see the [Threshold Governance Process](https://docs.threshold.network/governance/governance-process). {% endhint %} 2. **The second is staking:** by staking T, holders earn fee waivers and rebates on every tBTC mint and redemption, capturing a share of the real economic activity flowing through the network. {% hint style="info" %} For the staking mechanics and the fee savings available to stakers, see [Staking T Tokens](https://docs.threshold.network/t-token/staking-t-tokens). {% endhint %} # Staking T Tokens The Basics of Staking Threshold (T) Tokens, and its benefits. Staking T tokens secures the Threshold Network and enables stakers to get fee waivers/rebates on tBTC mint and redemption fees. Stakers receive direct rebates from real protocol activity, with no inflationary emissions or token unlocks involved. ### T Staking for tBTC Fee Rebates/ Waivers Since the beginning of 2026, T token holders have been able to [stake their T to receive fee rebates and waivers ](https://www.threshold.network/blog/tbtc-redemption-fee-waivers-for-t-stakers)when minting tBTC and redeeming BTC. With the reinstatement of minting fees, staking T has become even more valuable for reducing costs when using tBTC on the Threshold Bridge. The [Explorer page](https://app.threshold.network/explorer?tab=staking) in the app will continue to display rebates or fee waivers earned through staking T. Because rebates now apply to both minting and redemption fees, they will appear across both transaction types. {% hint style="info" %} **Staking T is optional;** it is not required when using, minting, or bridging tBTC. {% endhint %} Staking T (Threshold Tokens) returns a share of the tBTC mint and redemption fees to stakers as rebates. The breakdown below shows exactly how much you can save at each fee tier, giving you a clear basis to evaluate whether staking T offsets the cost of your expected tBTC activity.
*** $T is available on most decentralized exchanges and major centralized exchanges, giving anyone a path to participate. Staking T is the operational backbone of Threshold Network: stakers provide the security that backs tBTC and earn a share of every fee the protocol generates, aligning incentives between the network and the people who secure it. {% hint style="info" %} Start Staking T and get tBTC fee waivers via {% endhint %} # tBTC Bitcoin Bridge A Decentralized, Permissionless Bitcoin Bridge Existing solutions that bridge Bitcoin to DeFi require users to send their Bitcoin to an intermediary in exchange for an IOU token representing the original asset. This centralized model requires you to trust a third party and is susceptible to censorship, threatening the premise of Bitcoin as a sovereign, secure, permissionless digital asset. In contrast, tBTC is a decentralized and trust-minimized bridge between Bitcoin and DeFi. It provides Bitcoin holders with secure, open access to the broader DeFi ecosystem, allowing you to unlock the value of your Bitcoin by borrowing and lending, minting stablecoins, providing liquidity, and more. {% hint style="info" %} The New Unified Bitcoin Router by Threshold enables seamless tBTC minting, deminting, cross-chain bridging, and staking - all in one platform. It supports gasless minting and detects T staking rebates in real time. **Mint tBTC now at** [**https://app.threshold.network/**](https://app.threshold.network/) {% endhint %} ### Honest Majority Assumption Instead of centralized intermediaries, tBTC uses a randomly selected group of operators running nodes on the Threshold Network to secure deposited Bitcoin through [threshold cryptography](https://www.threshold.network/blog/what-is-threshold-cryptography). tBTC requires a threshold majority agreement before operators can perform any action with your Bitcoin. By rotating the selection of operators bi-weekly, tBTC protects against any individual or group of operators colluding to fraudulently seize the underlying deposits. By relying on an honest-majority assumption, we can calculate the likelihood of any wallet comprised of a quorum of dishonest operators.
### Fees tBTC fees are action-based (i.e., users incur a mint and redemption fee when using the bridge). The **mint and redemption fee is** [**0.2%**](https://etherscan.io/address/0x5e4861a80B55f035D899f66772117F00FA0E8e7B#readProxyContract#F13) **or 20 basis points**. The mint fee was initially offset to support adoption; however, following a recent governance decision, it was reinstated on April 15, 2026. You can read more about the reinstatement [here.](https://www.threshold.network/blog/tbtc-mint-fee-reinstatement) ### Fee Rebates or Fee Waivers Minting and redemption fees are set at 20 basis points to support decentralized bridge operations. However, these fees can be partially or fully offset by [staking $T](https://app.threshold.network/stake). **Staking $T is optional.** Eligible participants receive fee waivers in line with protocol parameters, and waivers are applied automatically when using the new Threshold Unified Bitcoin Router, accessible at . {% hint style="info" %} To learn more about T Token Staking and its benefits, **visit this** [**page**](/t-token) **or read the** [**release article.**](https://www.threshold.network/blog/tbtc-redemption-fee-waivers-for-t-stakers) {% endhint %} # Wallet Generation Wallets are created periodically based on governance. [`updateWalletParameters`](https://etherscan.io/address/0x5e4861a80b55f035d899f66772117f00fa0e8e7b#writeProxyContract#F32) changes the time between wallets and [`walletParameters`](https://etherscan.io/address/0x5e4861a80b55f035d899f66772117f00fa0e8e7b#readProxyContract#F18) reads it. The time between new wallets is held in `walletCreationPeriod` in number of seconds, so the current value of `1209600` represents 14 days.\ \ In order for the wallet to move funds, it produces signatures using a [Threshold Elliptic Curve Digital Signature Algorithm](https://eprint.iacr.org/2019/114.pdf), requiring 51-of-100 Signers to cooperate. The 100 signers on each wallet are chosen with our [Sortition Pool](https://github.com/keep-network/sortition-pools), and the randomness is provided by the [Random Beacon](https://github.com/keep-network/keep-core/tree/main/pkg/beacon). The probability that an operator is chosen to be a Signer is equal to their allowlist weighting. Each Signer is chosen independently. The same operator can be a signer on the same wallet multiple times. The same operator can be a Signer on multiple wallets simultaneously. ## Examples For simplicity, say there are only three Stakers: Alice, Bob, and Carol. Alice has 250M T, Bob has 400M T, and Carol has 350M T staked, so they own 25%, 40% and 35% of the stake respectively. That means, Alice has a 25% chance to be a Signer, Bob has a 40% chance, and Carol has a 35% chance. Each Signer is selected independently. The Sortition Pool is more complex (because of heavy gas optimization), but reasoning about it could look like this:\ \ For each Signer, we're going to generate a random number between 1 and 100. Alice is the Signer if the number is in \[1, 25]. Bob is the Signer if the number is in \[26, 65]. Carol is the Signer if the number is in \[66, 100]. For example, if our first [random number](https://www.random.org/) is 33, our first Signer would be Bob. We can generate 100 random numbers: `(75, 51, 13, 48, 36, 62, 46, 65, 97, 67...)`, and then use that to determine Signers: `(Carol, Bob, Alice, Bob, Bob, Bob, Bob, Bob, Carol, Carol...)`.\ \ This example illustrates a few properties mentioned earlier: * Each Signer is selected independently. Whether or not Carol is the first signer has no influence on Carol being the second Signer. * The chance that you become a particular Signer is equal to your share of the Stake. ### Statistics If Carol has a 35% chance of being a particular Signer, what are the chances that Carol has at least 51 of the 100 seats (and could control the wallet by herself)? The number of Signers that Carol controls on a wallet is modeled by the [Binomial Distribution](https://en.wikipedia.org/wiki/Binomial_distribution). From Wikipedia: > A Binomial distribution with parameters `n` and `p` is the [discrete probability distribution](https://en.wikipedia.org/wiki/Discrete_probability_distribution) of the number of successes in a sequence of `n` [independent](https://en.wikipedia.org/wiki/Statistical_independence) [experiments](https://en.wikipedia.org/wiki/Experiment_\(probability_theory\)), each asking a [yes–no question](https://en.wikipedia.org/wiki/Yes%E2%80%93no_question), and each with its own [Boolean](https://en.wikipedia.org/wiki/Boolean-valued_function)-valued [outcome](https://en.wikipedia.org/wiki/Outcome_\(probability\)): *success* (with probability `p`) or *failure* (with probability `1−p`). This is exactly our situation! From Carol's perspective, there will be `n=100` independent experiments, each asking a yes-no question (does this Signer belong to Carol), each with a 35% probability. That means we can use a [Binomial Probability Calculator](https://stattrek.com/online-calculator/binomial) to answer our question:\ \ ![](/files/fSaQT3g0efkwJWAc2Wkd) It's the last figure: "Cumulative probability: P(X>51)" that's relevant. That says there is a \~0.074% chance that Carol would have a controlling Share of any particular wallet. The next important question is "The probability that Carol controls a Wallet is low, but it only needs to happen once for things to be bad. What is the probability that she controls *any* wallet in the next 2 years?" A wallet is generated every 14 days, so over the next 2 years, the system will generate \~52 wallets. Each wallet has a `1 - 0.00074 = .99926` or 99.926% chance of *not* being controlled by Carol. That means we can exponentiate: $$ 0.99926^{52} = .9622 $$ Carol would have a \~3.8% chance of getting control of a wallet in 2 years. That's with her owning 35% of the total Stake! Alice has a *much* lower chance. She has a `0.0002131%` chance of controlling a wallet, which means that over the course of 52 wallets, she has a `0.02131%` chance of controlling *any* wallet in 2 years. As of writing, the \*largest\* Staker controls [\~8.83% of the Stake](https://dune.com/queries/2013598). ### Sybil Resistance The only thing a Staker accomplishes by splitting their Stake into multiple identities is making the system appear more diverse. For example, say that Alice split up her Stake equally into 5 accounts: Alice1, Alice2, Alice3, Alice4, and Alice5. Now, rather than Alice having a 25% chance to be a Signer, each account has a 5% chance, which collectively adds up to 25%. To use the example from earlier: Alice has 250M T, Bob has 400M T, and Carol has 350M T staked. Alice has her T split into 50M for each identity. Alice1 would own 50M/1000M = 5%.\ \ Keeping with the simplification of assigning numbers from 1 to 100 to identities, Alice1 would get \[1, 5], Alice2 gets \[6, 10], Alice3 gets \[11, 15], Alice4 gets \[16, 20], Alice5 gets \[21, 25], Bob gets \[26, 65], Carol gets \[66, 100]. If we use the same random numbers as before, `(75, 51, 13, 48, 36, 62, 46, 65, 97, 67...)`, then we make the assignments as `(Carol, Bob, Alice3, Bob, Bob, Bob, Bob, Bob, Carol, Carol...)`. Nothing has effectively changed! # Wallet Signing The primary wallet responsibility is taking care of Bitcoins deposited by tBTC users. Whenever a wallet needs to move some Bitcoins due to a protocol action (e.g. deposit sweep or redemption), it must assemble an appropriate Bitcoin transaction and sign each transaction's input using the tECDSA signing algorithm. During the tECDSA signing, randomly selected 51-of-100 wallet signers must collaborate to produce a proper signature. ## Anatomy of a signing attempt A single tECDSA signing attempt consists of several steps. Each step has a maximum duration expressed in the specific number of host chain (e.g., Ethereum) blocks: 1. Signers' readiness announcement phase, which takes **exactly** 6 blocks 2. Signature production & advertisement phase, which takes **up to** 30 blocks 3. Cooldown period that takes **exactly** 5 blocks That means a single signing attempt can take up to **41 blocks** (\~8 minutes on Ethereum, assuming a 12-second average block time). If the signature is not produced during that time, the wallet signers abandon the signing attempt and retry. ## Signing retries A wallet that is asked to sign the given message (e.g., Bitcoin transaction input) does not limit itself to a single tECDSA signing attempt. Due to the distributed nature of the signing algorithm, a single signing attempt may fail, for example, due to unexpected network problems affecting inter-signer communication. If the first signing attempt fails, another set of 51 randomly selected wallet signers retries signing during the next attempt. Subsequent signing attempts are scheduled on fixed intervals, based on the block the first attempt started at, and the known maximum duration of a single attempt (41 blocks). For example, if the first attempt started at block **B**, subsequent attempts will be scheduled as follows: * Attempt 2 -> **B + 41** * Attempt 3 -> **B + 82** * Attempt N -> **B + (N-1) \* 41** The wallet always executes **up to 5 signing attempts**. Such a count of maximum attempts is an acceptable trade-off between a reasonable signing timeout and a sufficient tolerance for misbehaving wallet signers. Executing 5 signing attempts allows 5 different 51-signer subsets to be tried. This is enough to produce a signature even for an unlikely scenario of 2 misbehaving wallet signers. In that case, 51 signers must be selected out of the honest 98 signers. That means the probability of selecting a successful subset is: ``` P = (98 choose 51) / (100 choose 51) = ~0.24 ``` which means 5 selections are required in the worst case. Combining the 5 signing attempts at maximum with up to 41 blocks per single attempt means the wallet will try to sign the given message for **5\*41 = 205 blocks** (\~40 minutes on Ethereum, assuming 12 seconds as the average block time). If the signature is not produced during that time, wallet signers ultimately give up. ## Serial signing Wallets can sign multiple messages (e.g., multiple inputs in a single Bitcoin transaction) serially, one after another. In such a case, the signing process is successful only if all messages in the batch are signed. As mentioned in the previous section, the maximum allowed time for signing a single message is 205 blocks (\~40 minutes on Ethereum). That means the maximum time to sign a batch of **N** messages is **N\*205 blocks**. During that time, the wallet cannot perform any other work, as signing is computationally heavy. This factor must be taken into account while building wallet actions that leverage signing. ## Signing as the foundation of wallet actions The tBTC protocol defines a finite set of wallet actions: * Heartbeat * Deposit sweep * Redemption * Moving funds * Moved funds sweep Each action involves wallet signing under the hood. The time necessary to complete the given action depends on how many signatures must be produced during execution. Knowing the worst-case time required to produce a single signature (205 blocks) and the number of signatures that may be required by the given action, we can set appropriate time bounds for specific actions. This information is crucial for proper wallet coordination. ### Example: Deposit sweep Let's use the *Deposit sweep* action to show how signing affects wallet actions*.* This action is initiated by a coordinator who submits a deposit sweep proposal through the `WalletCoordinator` chain contract. An expected outcome of that action is a Bitcoin transaction with multiple inputs (swept deposits) and one output, submitted to the Bitcoin chain. That means the action's execution time depends strongly on the number of deposits suggested in the given sweep proposal. The `WalletCoordinator` contract has some governable parameters that impact the *Deposit sweep* action: * `depositSweepMaxSize` That sets the maximum number of deposits within a single sweep proposal * `depositSweepProposalValidity` which determines the validity period of the proposal. This is an exclusive time the wallet has to execute the given sweep, and no other actions can be taken during this time In other words, the wallet can sweep up to `depositSweepMaxSize` deposits and has `depositSweepProposalValidity` time to do so. Signing is the most important and complex step of the *Deposit sweep* action and the reference client implementation sets the signing timeout to be `depositSweepProposalValidity - 1 hour` for all inputs of the sweep transaction. Producing a signature for a single-deposit input may take up to 205 blocks (5 attempts in total). This is \~40 minutes, assuming Ethereum's average block time of 12 seconds. Having that in mind, the aforementioned `WalletCoordinator` governable parameters must be chosen with care as they have a strong impact on signing execution: * If `depositSweepMaxSize = 5` and `depositSweepProposalValidity = 4 hours`, the wallet will try to sign 5 inputs in 3 hours, which gives \~36 minutes per input. As 5 signing attempts take \~40 minutes, this configuration will allow for 4 attempts per input * If `depositSweepMaxSize = 10` and `depositSweepProposalValidity = 4 hours`, the wallet will try to sign 10 inputs in 3 hours, which gives \~18 minutes per input. As 5 signing attempts take \~40 minutes, this configuration will allow for 2 attempts per input * If `depositSweepMaxSize = 20` and `depositSweepProposalValidity = 4 hours`, the wallet will try to sign 20 inputs in 3 hours, which gives \~9 minutes per input. As 5 signing attempts take \~40 minutes, this configuration will allow for 1 attempt per input # Sweeping An accounting optimization for tracking bitcoin deposits in tBTC contracts ### What is Sweeping? Sweeping is an accounting optimization for tracking Bitcoin deposits in tBTC contracts. It involves periodically consolidating recent Bitcoin deposits into a single Unspent Transaction Output (UTXO) for a more optimal commitment cadence to Ethereum. This process simplifies tracking associated public keys and refund time locks while also helping prevent supply peg disruption. Typically, Sweeping runs every 8 hours, depending on the volume and size of deposits. ### How it works When a user makes a deposit, they lock the funds using our [locking script](https://blog.threshold.network/tbtcv2-deposits-explained/). This creates an Unspent Transaction Output ([UTXO](https://learnmeabitcoin.com/technical/utxo)). Typically, the job of a bitcoin "wallet" (wallets don't exist in the same way they do on Ethereum) is to scan the blockchain for specific locking script patterns it thinks it can unlock (like a [P2PKH script](https://learnmeabitcoin.com/technical/p2pkh) associated with your public key) and sum up the relevant funds. When you want to send someone else bitcoin, the wallet software figures out which UTXOs to unlock to send to them so that you don't have to. If we wanted to be able to redeem bitcoin deposits, we would need to track which deposits are associated with which public keys, the same way that wallet software does; this is a headache, especially from a bitcoin mining fee perspective. Further, our [locking script](https://blog.threshold.network/tbtcv2-deposits-explained/) includes this idea of a time-locked refund. If the funds are not touched by a certain amount of time (9 months at the time of writing; `` In the script, we allow the depositor to reclaim their deposit. We do this as an effective escape hatch in case something goes wrong with the protocol or deposit. As a result, we set the same time limit for collecting the deposit. If we don't move the funds by that time, a user could deposit 5 BTC, receive 5 TBTC, and then 9 months later reclaim their original 5 BTC without redeeming the 5 BTC. This would break the TBTC supply peg. Sweeping aims to solve both of these problems simultaneously, as well as serves as a performance optimization. Every 8 hours, we collect all recent deposits, unlock them, and then send the funds using a standard P2PKH script back to the wallet, consolidating the UTXOs into a single UTXO. The result is that all of the scattered deposits are "swept" into a single "pile" represented by one UTXO that we can commit to on Ethereum. ### Example Here's a deposit for [10.3 BTC](https://mempool.space/tx/a4dc393dc48a82d1bb2d5dc30437fdb83e61565c47274dbe1c064117541ea97d). That deposit is swept in transaction [0db1929c2fa41649264b95b9162bc7a12f43cb455a91bae7177667a53290d7e8](https://mempool.space/tx/0db1929c2fa41649264b95b9162bc7a12f43cb455a91bae7177667a53290d7e8) (along with many other deposits). That was one of three sweeps performed by that wallet (as of writing). ![https://mempool.space/tx/1ddffd9e5d4c84b49c9f912bfc3b97d8f5aba0620e35ec6a50e7043c9141d373](/files/2PlpiOLWM3pOv9H3GC6c) That transaction created a UTXO worth 1.51614471 BTC. The next transaction ![https://mempool.space/tx/40240aaa602f534ae7e1654546e7ee5f49a32d6d64215d90acbb9a720f63098e](/files/Z7mFaIiuA8OliTNtXTao) Used the old UTXO (the first input) as well as all of the recent deposits to create a new UTXO (the output on the right) worth 15.42475511 BTC. The final transaction ![https://mempool.space/tx/0db1929c2fa41649264b95b9162bc7a12f43cb455a91bae7177667a53290d7e8](/files/Qs07DPxt5FBdpPV1MpcQ) Follows the same pattern. It uses the old UTXO (the first input) and the recent deposits to create a new UTXO worth 59.52818486 BTC. # Verifiable Bitcoin Accounts VBA is built based on what institutions actually need for Institutional Bitcoin deployment. Verifiable Bitcoin Accounts (VBA) are how institutions use Bitcoin without compromise, enabling deployment into onchain lending and yield markets while preserving existing custody arrangements. Built on Threshold Network's battle-tested signer infrastructure, Verifiable Bitcoin Accounts (VBA) is purpose-built for custodians, institutional allocators, asset managers, family offices, hedge funds, corporate treasury teams, and other organizations. It delivers segregated custody, verifiable UTXOs, direct access to onchain yield/ lending markets, and an optional legal framework. Every spending condition, recovery path, and migration rule is encoded in Bitcoin Script - verifiable onchain, and auditable by design. {% hint style="info" %} Visit the Threshold Network [Institutional page](https://threshold.network/institutional) for more info. {% endhint %} # Technical Diagram Verifiable Bitcoin Accounts (VBA) combine three layers: the institution's existing custody, Threshold Network's distributed signer infrastructure, and pre-approved onchain deployment venues. Bitcoin Script enforces all spending conditions at the consensus layer.
Verifiable Bitcoin Accounts (VBA) Lifecycle by Threshold Network
## Layer 1: Custody Compatibility Any key management system that can sign Bitcoin transactions and produce BIP-174 (PSBT) compatible partial signatures can participate as depositor (D), custodian (C), or signer (S). ``` +--------------------------------------------------------------------------+ | CUSTODY COMPATIBILITY | +--------------------------------------------------------------------------+ +----------------------+ +----------------------+ +----------------------+ | QUALIFIED CUSTODIAN | | THRESHOLD MPC | | SELF-CUSTODY | | (holds key C or D) | | (holds key S) | | (holds key D) | | | | | | | | - Any regulated | | - tECDSA threshold | | - HSM-based signing | | custodian that | | signing (e.g., | | - Hardware wallets | | supports PSBT | | keep-core nodes) | | - MPC wallets | | - MPC or HSM-based | | - Produces single | | | | key management | | aggregated pubkey | | | | | | for Bitcoin Script | | | +----------------------+ +----------------------+ +----------------------+ | | | +-------------------------+-------------------------+ | v +-----------------------------------------+ | PSBT SIGNING INTERFACE | | (BIP-174 Compatible) | | Each party signs independently | | and contributes partial signature | +-----------------------------------------+ | v +--------------------------------------+ | FINALIZED BITCOIN TRANSACTION | | Broadcast + SPV-proven to Ethereum | +--------------------------------------+ ``` #### Template-to-role mapping
TemplateRoles presentRequired signers per path
qc_v1D + C + SCOOPERATIVE: D+C+S; MIGRATION: S+C; EARLY_EXIT: D+C; LAST_RESORT: D
self_v1D + S (no C)COOPERATIVE: D+S; MIGRATION: S; LAST_RESORT: D
**Key principle:** No asset migration is required. The custody relationship that the institution already maintains continues to govern the asset throughout the VBA's lifecycle. *** ## Layer 2: Multi-Party Control Model ``` +---------------------------------------------------------------------------------+ | MULTI-PARTY CONTROL FLOW | +---------------------------------------------------------------------------------+ +-----------------------+ +------------------------+ +----------------------+ | INSTITUTION | | SIGNER NETWORK | | CUSTODIAN | | Signing Key D | | Signing Key S | | Signing Key C | | (depositor) | | (single aggregated key | | (qc_v1 only) | | | | may be tECDSA-managed | | | | | | off-chain) | | | +-----------------------+ +------------------------+ +----------------------+ | | | | | | +-----------------------------+-----------------------------+ | v +-------------------------------------------------------+ | PATH SELECTION | | | | COOPERATIVE: D + C + S (3-of-3 CHECKMULTISIG) | | MIGRATION: S + C (2-of-2 CHECKMULTISIG) | | EARLY_EXIT: D + C (2-of-2 CHECKMULTISIG) | | LAST_RESORT: D only (1-of-1 CHECKSIG) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | SBT CONSTRUCTION (BIP-174) | | | | Each signer adds partial sig to PSBT independently | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | PSBT FULLY SIGNED | | | | Broadcast to Bitcoin network | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | SPV PROOF SUBMITTED | | | | CovenantBitcoinTxProofVerifier | | validates proof on Ethereum | | CovenantAuthority updates reserve state | +-------------------------------------------------------+ ``` **Enforcement:** The quorum threshold is encoded in the Bitcoin Script governing the UTXO. Any transaction below the threshold is rejected by the Bitcoin network at the consensus layer. *** ## Layer 3: Bitcoin Script Enforcement Spending conditions are written directly in Bitcoin Script and validated by every Bitcoin full node. ``` +-------------------------------------------------------------------------------+ | BITCOIN SCRIPT ENFORCEMENT MODEL (qc_v1) | +-------------------------------------------------------------------------------+ VBA UTXO (P2WSH with embedded witness script) | +-> SPENDING PATH 1: COOPERATIVE -- Unanimous authorized movement | | | +-- 3-of-3 OP_CHECKMULTISIG (D + C + S all required) | +-- No locktime constraint | +-- No destination restriction in Bitcoin Script * | +-> SPENDING PATH 2: MIGRATION -- Post-maturity signer-led move | | | +-- 2-of-2 OP_CHECKMULTISIG (S + C) | +-- OP_CHECKLOCKTIMEVERIFY: locktime = maturityHeight | +-- No destination restriction in Bitcoin Script * | +-> SPENDING PATH 3: EARLY_EXIT -- Pre-maturity depositor + custodian | | | +-- 2-of-2 OP_CHECKMULTISIG (D + C) | +-- OP_CHECKLOCKTIMEVERIFY: locktime = maturityHeight - beta | +-- No destination restriction in Bitcoin Script * | +-> SPENDING PATH 4: LAST_RESORT -- Solo depositor recovery | +-- OP_CHECKSIG: single signature (D only) +-- OP_CHECKLOCKTIMEVERIFY: locktime = maturityHeight + delta2 +-- Activates if all other parties are unavailable ``` Destination address constraints are enforced by Covenant Authority on Ethereum, NOT by Bitcoin Script. Bitcoin Script only checks signatures and timelocks. *Validated by: Every Bitcoin full node (script validity only)* #### self\_v1 Template (Self-custody, no custodian) ``` +-----------------------------------------------------------------+ | BITCOIN SCRIPT ENFORCEMENT MODEL (self_v1) | +-----------------------------------------------------------------+ Keys: D = depositor, S = signer (no custodian in this template) +-> SPENDING PATH 1: COOPERATIVE | +-- 2-of-2 OP_CHECKMULTISIG (D + S) | +-- No locktime | +-> SPENDING PATH 2: MIGRATION | +-- OP_CHECKSIG: single signature (S only) | +-- OP_CHECKLOCKTIMEVERIFY: locktime = maturityHeight | +-> SPENDING PATH 3: LAST_RESORT +-- OP_CHECKSIG: single signature (D only) +-- OP_CHECKLOCKTIMEVERIFY: locktime = maturityHeight + delta2 ``` **No external dependencies:** The rules governing each VBA do not rely on application-layer software, smart contracts on other chains, or proprietary policy engines. *** ### Liquidation & Migration Path When a position is liquidated in an approved venue, Threshold signers automatically execute the predefined migration path. ``` ┌──────────────────────────────────────────────────────────┐ │ LIQUIDATION & MIGRATION FLOW │ └──────────────────────────────────────────────────────────┘ ┌──────────────────────┐ │ ONCHAIN VENUE │ Liquidation event triggered │ (Aave, Morpho, │ (e.g., LTV breach, oracle price) │ Curve, Yield Basis) │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ THRESHOLD SIGNERS │ Independent verification │ │ of onchain state │ • Direct read of │ │ contract state │ │ • No external oracle │ │ • No off-chain │ │ coordination │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ QUORUM EVALUATION │ Threshold signers reach │ │ quorum agreement │ Each signer verifies │ │ conditions are met │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ PRE-CONSTRUCTED │ Migration PSBT signed │ MIGRATION PSBT │ by quorum │ │ │ Destination: │ │ Pre-defined at │ │ account setup │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ BROADCAST TO │ │ BITCOIN NETWORK │ └──────────┬───────────┘ │ ┌────┴────────────────────────────┐ ▼ ▼ ┌──────────────────────┐ ┌───────────────────────────┐ │ THRESHOLD BRIDGE │ │ PRE-APPROVED │ │ (Default) │ │ COUNTERPARTY ADDRESS │ │ │ │ (Where venue settlement │ │ │ │ requires it) │ └──────────────────────┘ └───────────────────────────┘ ``` **Critical property:** The migration destination is whitelisted at account setup. Signers do not exercise discretion about where capital goes. They verify a predefined condition and execute a predefined action. *** ### Recovery Architecture Every VBA includes layered recovery paths that operate without requiring counterparty cooperation. ``` +-----------------------------------------------------------------------+ | RECOVERY ARCHITECTURE | +-----------------------------------------------------------------------+ FAILURE SCENARIO 1: Signer network disrupted | +-- Recovery Path A: Joint depositor + custodian recovery (EARLY_EXIT) | | | +-- Threshold signers NOT required | +-- Depositor key (D) + custodian key (C) sign | +-- 2-of-2 OP_CHECKMULTISIG on Bitcoin Script | +-- REQUIRES a timelock: locktime = maturityHeight - beta | (activates BEFORE full maturity, but still time-gated) +-- Reserve state must be in EXITING on Ethereum (CovenantAuthority) FAILURE SCENARIO 2: Both signer network AND custodian are unavailable | +-- Recovery Path B: Depositor solo recovery (LAST_RESORT) | | | +-- Only the institution's key (D) required | +-- OP_CHECKSIG (not multisig -- single signature) | +-- Enforced by OP_CHECKLOCKTIMEVERIFY | +-- Locktime = maturityHeight + delta2 | (longest timelock, set at account creation) +-- Activates automatically when the timelock expires ``` #### Enforcement Mechanism: Recovery paths encoded in Bitcoin Script (P2WSH). However, the reserve state machine lives on Ethereum: CovenantAuthority.reserveStates is the canonical record. IBitcoinRelay must be live for freshness check, Attester quorum (CovenantOracle) required for state advances, Bitcoin txs must be SPV-proven back to Ethereum *** ### Complete Lifecycle Summary A complete view of how a VBA progresses from setup through operation to potential recovery. ``` ┌────────────────────────────────────────────────────┐ │ VBA LIFECYCLE │ └────────────────────────────────────────────────────┘ PHASE 1: SETUP ┌────────────────────────────────────────────────────┐ │ • Quorum structure defined │ │ • Whitelisted venues selected │ │ • Recovery paths configured with timelocks │ │ • Bitcoin Script encoded │ │ • PSBTs pre-constructed │ │ • Optional ACA executed │ └─────────────────────┬──────────────────────────────┘ ▼ PHASE 2: FUNDING ┌────────────────────────────────────────────────────┐ │ • Institution funds VBA from existing custody │ │ • UTXO created with embedded Script conditions │ │ • Account verified and operational │ └─────────────────────┬──────────────────────────────┘ ▼ PHASE 3: DEPLOYMENT ┌────────────────────────────────────────────────────┐ │ • Capital deployed into whitelisted venues │ │ • Multi-party authorization on every movement │ │ • All transactions verifiable on Bitcoin L1 │ └─────────────────────┬──────────────────────────────┘ ▼ PHASE 4: ACTIVE OPERATION ┌────────────────────────────────────────────────────┐ │ • Threshold signers monitor venue activity │ │ • Yield accrues to the account │ │ • Standard reporting generated │ │ • Quarterly reviews with coverage team │ └─────────────────────┬──────────────────────────────┘ ▼ PHASE 5: EXIT (one of three paths) ┌────────────────────────────────────────────────────┐ │ Path A: Normal Exit │ │ Multi-party quorum unwinds positions │ │ Capital returns to the institution's custod │ │ │ │ Path B: Liquidation-Triggered Migration │ │ Pre-defined migration path executes │ │ Capital settles on the whitelisted destination │ │ │ │ Path C: Recovery (Counterparty Failure) │ │ Recovery path activates per Script conditions │ │ The institution recovers capital independently │ └────────────────────────────────────────────────────┘ ``` *** ### Trust Model Summary
ComponentTrust AssumptionEnforcement Mechanism
Spending conditionsNone requiredBitcoin Script + consensus
Quorum thresholdNone required (for Bitcoin Script rules)Bitcoin Script (OP_CHECKMULTISIG); threshold varies by path
Timelock enforcementNone requiredBitcoin Script (OP_CHECKLOCKTIMEVERIFY)
Reserve state machineIBitcoinRelay livenessCovenantAuthority contract on Ethereum (canonical state)
Attestation quorumThreshold attester honesty (threshold-bound)CovenantOracle on Ethereum; ECDSA signature quorum required
Migration executionThreshold signer honesty (threshold-bound)Bitcoin Script path + CovenantAuthority state transition
Recovery activationNone required (Bitcoin Script paths)Bitcoin consensus + OP_CHECKLOCKTIMEVERIFY
Legal enforceabilityCounterparty contractual complianceTripartite Account Control Agreement (optional)
**Net trust model:** The institution does not need to trust Threshold Network for the integrity of the rules governing its capital. It uses Threshold's signer network for operational liveness. If that liveness fails, the recovery path activates without requiring Threshold's participation. *** ### Verification Every condition governing a VBA can be verified independently: * **Spending conditions:** Inspect the Bitcoin Script attached to the UTXO using any Bitcoin full node or open-source script debugger * **Quorum requirements:** Validate the multisig structure encoded in Script * **Recovery paths:** Confirm the timelock parameters and signing requirements * **Onchain state:** Read the UTXO and transaction history directly from any Bitcoin full node * **Deployment activity:** Audit transactions on the relevant chain and reconcile against the VBA's signed PSBT history No proprietary tooling is required for any of this verification. # tBTC Minting Walkthrough Follow along with this guide and leverage your Bitcoin by minting tBTC.
## Before you start Here are some things you will need before you start the minting process:\ \ **What you need:** :white\_check\_mark: At least 0.01 Bitcoin (BTC) :white\_check\_mark: Bitcoin compatible wallet (self-custodied) :white\_check\_mark: Destination Wallet (on supported chains; see the list of supported chains [here](https://docs.threshold.network/contract-addresses/tbtc).)\ \ **Important Reminders:** * *Always download and securely store your deposit receipt.* This JSON file is required to recover your funds in the event of any technical issues during the minting process. * *Minting may take anywhere from a few minutes to several hours*, depending on the amount of BTC deposited. You can monitor the status at * *Your BTC recovery address must come from a self-custodied wallet that you control.* Do not use an address from a centralized exchange. * *Multisig wallets are supported as long as they’re on the correct network.* {% hint style="info" %} If you don't have a Bitcoin wallet, you'll need to set one up. A solid option to use is Green Wallet. You can download it here: * [Apple store download](< https://apps.apple.com/us/app/green-bitcoin-wallet/id1402243590>) * [Google store download](https://play.google.com/store/apps/details?id=com.greenaddress.greenbits_android_wallet\&gl=US\&pli=1) After you've created your wallet, select `Bitcoin` as your network.. {% endhint %} ## Start minting tBTC :tada: *You're ready to mint! Go to the tBTC app here:* [*https://app.threshold.network*](https://app.threshold.network/)*, and watch the tutorial video below:* {% embed url="" %} ### Congrats — you minted! :tada: You've successfully minted tBTC! :tada: # Governance Process Discover how you can participate in Threshold Governance Process ### Lifecycle of a successful proposal 1. **Forum discussion**: A Threshold community member posts a potential proposal on the Threshold governance forums. Community members who post the initial proposal are encouraged to get active in Meta governance discussions within the community on forums and in Discord to earn support for the proposal. There is no minimum token threshold required to create a new proposal on the forums. Community mods reserve the right to moderate spam proposals during this stage by deleting the proposal from the forums. 2. **Temperature Check:** Once a potential proposal has enough traction and discussion within the community, it can proceed for a temperature check via an off-chain [snapshot](https://snapshot.org/#/threshold.eth). If a proposal receives majority support during the temperature check, it is eligible to move onto the next step. 3. **Proposal Creation**: A community member holding enough vote weight (at least 0.25% of T total supply) submits the proposal on-chain. The proposal enters a **2-day delay period before voting** officially begins. 4. **Vote Period**: Proposal **voting remains open for 10 days**. If the proposal passes with enough quorum (at least 1.5% of T total supply), it moves onto the next step; if the proposal fails, it is canceled. Creators and supporters of the proposal may bring a modified proposal forward again but it must be sufficiently different and pass requirements outlined in previous steps. 5. **Timelock Period**: Once a proposal is approved, the Governor Bravo smart contracts include an additional **timelock delay of 2 days**. Anyone can interact with the Governor Bravo smart contracts to queue an approved proposal into the Timelock contract. 6. **Execution**: After the timelock delay, anyone can execute an approved proposal. ![The lifecycle of a successful proposal](/files/U0OP2wXTJNdp3er5X5an) ### Deviations in the proposal lifecycle * **Committee vetos:** During the on-chain phase, the Elected Committee can veto any proposal. This is intended to be an extra security mechanism in the event that a dangerous proposal passes. * **Late quorum prevention:** The 10-days voting period is automatically extended when quorum is reached late, to prevent governance attacks that try to reach quorum at the last minute; in case a proposal reaches quorum less than 2 days before the deadline, the proposal deadline is **extended for 2 more days** from the moment the quorum was reached. * **Off-chain proposals:** Some proposals do not imply any on-chain action (e.g. Council and Guild elections). In these cases, there is a Snapshot vote that takes 5 days for regular proposals and 7 days for elections, with no associated on-chain proposal. # Threshold Multisigs Compilation of current multisigs for the Threshold Committee ## Committee Multisigs | Chain | Address | Safe Link | | --------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | Ethereum | 0x9F6e831c8F8939DC0C830C6e492e7cEf4f9C2F5f | | | Eth: Foundation | 0xf642Bd6A9F76294d86E99c2071cFE2Aa3B61fBDa | | | Arbitrum | 0x9F6e831c8F8939DC0C830C6e492e7cEf4f9C2F5f | | | Optimism | 0x7fB50BBabeDEE52b8760Ba15c0c199aF33Fc2EfA | | | Polygon | 0x9F6e831c8F8939DC0C830C6e492e7cEf4f9C2F5f | | | Base | 0x518385dd31289F1000fE6382b0C65df4d1Cd3bfC | | | Solana | 814TqVmhQGKB3srSLRuMcH6m8qWFHRSbNpRxC5Xnador | | | Starknet | 0x0314A42C20b0364C6df5Af35E0914dd65F24a61F3563a8bc2A9D664938f37c4F | N/A (Argent's Multisig) | {% hint style="info" %} The Threshold Committee multisigs have a signature policy threshold set to 6 of 9. {% endhint %} # Liquid Token Delegation How to delegate liquid T tokens Liquid T holders can delegate their token weights to themselves or a third party for voting on governance proposals. {% hint style="info" %} Delegation is performed via an onchain transaction, which incurs ETH gas costs. {% endhint %} 1. Go to . 2\. Connect your wallet. 3\. Click "*Set Up Delegation".*
Set Up Delegation
4\. Select your *"Delegation Type"* - either to yourself or a third party.
Choose Delegation Type
5\. Enter *"Delegate Address"* and click on *"Delegate Votes".*
Delegate Votes
6\. Sign the transaction. # tBTC Signers A comprehensive guide for tBTC Signers Threshold Network allows authorized signers to participate in tBTC minting, redemptions, and custody. These signers ensure key operations run properly without interruptions. You may find that some notable professional staking providers request DAO approval [here](https://forum.threshold.network/t/tip-067-part-1-add-professional-node-operators-to-beta-staker-program/730/20). {% hint style="info" %} Visit the [contract page on Etherscan](https://etherscan.io/address/0xc2731fb2823af3Efc2694c9bC86F444d5c5bb4Dc#readContract#F16) to see the current number of Beta Stakers. {% endhint %} Signer nodes form a permissioned set responsible for creating tBTC wallets that custody BTC. Running a tBTC Signer node is a significant commitment with specific requirements. This document aims to highlight such requirements, technical recommendations, and possible costs of operating a tBTC Signer node. To stay informed about current node activities and other tBTC-related transactions, you may visit the [Threshold App Explorer page.](https://app.threshold.network/explorer?tab=deposits) ## General requirements Running a Signer node is a long-term commitment. Operators of Signer nodes are expected to be extremely responsive. Ideally, they should be able to upgrade their nodes within 24 hours of notification. Operators of Signer nodes must be technically capable. They are responsible for ensuring high availability (more than 96% uptime) and the node's security. ## Technical requirements A Signer node performs relatively computationally expensive operations (DKG, threshold signing, etc). To ensure a high level of service, a Signer node requires a machine with: * 4 CPUs * 4 GB of RAM * 1 GB of persistent disk space * 80 Mbps of network bandwidth * Linux OS In addition to the above: * The underlying machine’s operating system and tools must be up to date, especially regarding recent security patches. * Backups of the persistent disk must be performed on an ongoing basis. This is crucial to ensure the safety of mission-critical data (e.g., key material). Using an additional encryption layer for backups is highly recommended. * The network layer must provide a unique public IPv4 address so the node can be reached from the external network. A proper firewall configuration must be in place to ensure a safe perimeter, allowing inbound traffic on two ports (communication and diagnostics). The internet connection must be stable, and failover scenarios must be accounted for. * A Signer node requires access to an Ethereum node. It is highly recommended to set up a private Ethereum stack (e.g., Geth + Prysm) and use public providers as a failover (e.g., Alchemy, Infura, etc). Such a setup is crucial for network diversity and decentralization as it helps avoid the single-point-of-failure risk associated with public providers. Signers should use their own judgment for selecting stack components. Specific technical requirements for a private Ethereum stack depend on the software used. For example, a stack based on [Geth + Prysm requires 4 CPU / 16 GB RAM / 2 TB SSD](https://docs.prylabs.network/docs/install/install-with-script#step-1-review-prerequisites-and-best-practices). * A Signer node requires an Electrum protocol server to interact with Bitcoin. It is highly recommended to set up a private stack consisting of an Electrum server (e.g., Fulcrum, ElectrumX, Electrs, etc) paired with a Bitcoin node (e.g., Bitcoin Core) and use public servers as a failover. The reasons are exactly the same as for a private Ethereum stack. Signers should use their own judgment for selecting stack components. Specific technical requirements for a private Bitcoin stack depend on the software used. For example, a stack based on Fulcrum + Bitcoin Core requires 8 CPU / 16 GB RAM / 2 TB SSD. * It is highly recommended to set up a private monitoring stack to ensure observability and alerting. The monitoring system should supervise the node itself as well as Ethereum and Bitcoin stacks. Signer operators should use their own judgment for selecting stack components. Specific technical requirements for a monitoring stack depend on the software used. For example, a stack based on Grafana + Prometheus requires 2 CPU / 4 GB RAM / 20 GB HDD. ## Cost estimation The actual monthly costs of running a Signer node depend on the hosting model (VPS vs self-hosting) and infrastructure configuration. The following estimate provides a ballpark figure. It also assumes that all aforementioned technical requirements and recommendations are taken into account. **Key system assumptions** * Signer node requires 4 CPUs / 4 GB RAM / 1 GB HDD * Ethereum stack requires 4 CPUs / 16 GB RAM / 2 TB SSD * Bitcoin stack requires 8 CPUs / 16 GB RAM / 2 TB SSD * Monitoring stack requires 2 CPUs / 4 GB RAM / 20 GB HDD * External storage for backups (node and auxiliary stacks) is 1 TB HDD * The network layer ensures 100 Mbps of bandwidth and includes all necessary equipment (firewall, public IPs, etc.). The above assumptions can be used to divide costs into 4 categories: 1. **Computing costs:** This category includes the costs of running 18 CPUs and 40 GB of RAM. There are several possible configurations that can provide such computing capacity. Using the VPS-based model as an example, the cost of 3x 8CPU/16GB VMs on leading cloud service providers starts from \~$400/month. 2. **Storage costs:** This category includes the cost of using a 4 TB SSD and \~1 TB HDD in total. For the VPS-based model, part of this cost is often included in the cost of VMs, but some providers charge separately for storage at rates like \~$0.08/GB (e.g., Amazon EBS). In that case, it is safe to assume that storage costs start from \~$200/month. 3. **Network costs:** This category includes the cost of 100 Mbps of bandwidth and all auxiliary equipment and features, such as a firewall or public IPs. For the VPS-based model, such bandwidth is often provided out of the box with the VMs, but a firewall and public IPs may be charged separately. Moreover, some providers may apply an additional charge on egress traffic. It is safe to assume that network costs start from \~$50/month. 4. **Other costs:** This category includes all maintenance and other costs, depending on the hosting model and infrastructure configuration. For the VPS-based model, such costs can be OS licenses, automatic backup, additional management tools, and so on. For the self-hosting model, these can be costs of internet connection, power failover (e.g., UPS), auxiliary network equipment, and similar. This category of costs must be factored into the total monthly cost. ## Bottom Line In summary, the cost for running a Signer node using the VPS-based model starts at approximately $650/month. Assuming a safety margin for other costs, a rough estimate is $800/month to run a setup in accordance with the technical requirements and recommendations. Estimating the general cost for the self-hosting model is non-trivial due to the variety of possible configurations. The total monthly cost can be similar to the VPS-based model, but may also incur additional hidden costs, such as hardware maintenance ## **Disclaimer** The above assumptions and figures should be used cautiously, as they are intended only to provide a general sense of infrastructure costs. Each prospective Signer node operator should conduct their own estimates based on their individual circumstances. Last but not least, the presented estimate refers only to the infrastructure-related costs of operating a tBTC Signer node. **This estimate DOES NOT include human operational costs.** Each Signer must include this overhead when making their own estimates.
# Node Setup This document explains the basic installation and configuration for the tBTC v2 client. {% hint style="info" %} Please be aware that running a node is not an easy task and requires technical skill and commitment to maintaining node uptime and availability. {% endhint %} Please review this document in its entirety prior to beginning setup of your node to familiarize yourself with the general setup process. ### Important Considerations The Threshold Network expects certain capabilities for each node running on the network. To help attain these capabilities consider the following criteria: * It is paramount that tBTC v2 nodes remain available to the Network. We strongly encourage a stable and redundant internet connection. * Equally important is machine uptime and reliability. A VPS is strongly recommended. * A connection to a production grade self-hosted or third party Ethereum node deployment. * Persistent and redundant storage that will survive a VM or container rotation, and a disk failure. * Each node running on the network requires a unique Ethereum Operator Account. The account has to maintain a positive Ether balance at all times. * Each node running on the network requires a unique IP address or a unique application port running under the same IP. ### Recommended Machine Types {% hint style="info" %} While it is possible to run the client on a local machine, this is not recommended. {% endhint %} Your operating environment will ultimately dictate what machine type to go with. This is particularly relevant if you’re running a containerized solution where multiple applications are sharing VM resources. The below types are sufficient for running one instance of the tBTC v2 Node. The preferred OS is Ubuntu. | VPS Provider | VPS Type | | ------------ | -------------------------------------------- | | AWS | c5.large | | Azure | F2s v2 | | Google Cloud | n2-highcpu-2 | | Self-hosted | 2 vCPU / 2 GB RAM / 1 GiB Persistent Storage | ### **Ethereum API** A Keep Node requires a connection to a WebSocket Ethereum API. You should obtain a WS API URL from a service provider (e.g. [Alchemy](https://www.alchemy.com/), [Infura](https://www.infura.io/), [Ankr](https://www.ankr.com/rpc-service/)) or run your own Ethereum node (e.g. [Geth](https://geth.ethereum.org/)). ### Bitcoin API Starting from version `v2.0.0-m3` , the Keep Node interacts with the Bitcoin network through an Electrum protocol server. You can use one of the publicly available servers or run your own. The URL of the chosen server should be passed under the `bitcoin.electrum` section of the configuration. If no Electrum server is set explicitly in the `bitcoin.electrum` configuration section, the Keep Node will randomly pick one server from its embedded server list, appropriate for the Bitcoin network the Keep Node is currently running against. ### Configuration The client expects configuration options to be passed as CLI flags or specified in a [config file](/tbtc-signer-nodes/tbtc-v2-node-setup/advanced-options/config-file). If you specify an option by using a parameter on the command line, it will override the value read from the configuration file. # Operator Account Prepare your machine to install the tBTC v2 client The client requires an Ethereum Key File of an Operator Account to connect to the Ethereum chain. This account is created in a subsequent step using Geth (GoEthereum). The Ethereum Key File is expected to be encrypted with a password. The password has to be provided in a prompt after the client starts or configured as a `KEEP_ETHEREUM_PASSWORD` environment variable. The Operator Account has to maintain a positive Ether balance at all times. We strongly advise you monitor the account and top-up when its balance gets below 0.5 Ether. ### Install Geth (GoEthereum) To create a new Ethereum account, [install Geth](https://geth.ethereum.org/docs/getting-started/installing-geth) (GoEthereum) and create a new account using the command below. This account will subsequently be referred to as the Operator Account. 
geth account new --keystore /home/$USER/.operator-key
When prompted, provide a password to protect the operator key file. {% hint style="info" %} Use a password manager to generate a strong password and store it safely. It will be needed again during setup. {% endhint %} {% hint style="warning" %} Avoid passwords that contain the following characters: ', ", \`, $\ These characters may be interpreted as part of the configuration which can lead to undesirable outcomes that may be extremely time intensive to correct. {% endhint %} Once the process completes, your public key will be displayed. Take note of your Operator Account public key. {% hint style="danger" %} DO NOT LOSE THE PASSWORD TO THE OPERATOR ACCOUNT. {% endhint %} ### Funding your Operator Account Your Operator Account will need to maintain a positive ETH balance at all times to ensure proper operation and availability of your tBTC v2 node. # Network Configuration Required network configuration for the tBTC v2 client. ### Required Ports The node has to be accessible publicly to establish and maintain connections with bootstrap nodes and discovered peers. The node exposes metrics and diagnostics services for network health monitoring purposes. Update firewall rules as necessary, including application level firewalls for the following ports | Purpose | Config Property | Protocol | Default | | ------- | --------------- | -------- | ------- | | Network | network.port | TCP | 3919 | | Status | clientInfo.port | TCP | 9601 | {% hint style="warning" %} The network port must be exposed publicly for peers to connect to your node. {% endhint %} {% hint style="warning" %} The status port must be exposed publicly for rewards allocation. {% endhint %} ### **Announced Addresses** An Announced Address is a layered addressing information (`multiaddress`/`multiaddr`) announced to the Threshold Network that is used by peers to connect with your node, e.g.: `/dns4/bootstrap-0.test.keep.network/tcp/3919` or `/ip4/104.154.61.116/tcp/3919`. If the machine you’re running your node is not exposing a public IP (e.g. it is behind NAT) you should set the `network.AnnouncedAddresses` (flag: `--network.announcedAddresses`) configuration property to addresses (`ip4` or `dns4`) under which your node is reachable for the public. To read more about `multiaddress` see the [libp2p documentation](https://docs.libp2p.io/reference/glossary/#multiaddr). # Data Storage Setup persistent data directories for the client. The client requires two persistent directories. These directories will store configuration files and data generated and used by the client. It is highly recommended to create frequent backups of these directories. Loss of these data may be catastrophic and may lead to slashing. {% hint style="warning" %} It is crucial to ensure that the data directory is persisted and backed up regularly. {% endhint %} #### Create folders for tBTC v2 client ```bash cd /home/$USER/ mkdir keep cd keep mkdir storage config ``` The tBTC v2 client will create two subdirectories within the storage directory: `keystore` and `work`. You do not need to create these. The `keystore` subdirectory contains sensitive key material data generated by the client. Losing the `keystore` data is a serious protocol offense and leads to slashing and potentially losing funds. {% hint style="danger" %} It is the operator’s responsibility to ensure the keystore data is not lost under any circumstances. {% endhint %} The `work` directory contains data generated by the client that should persist through client restarts or relocations. If the `work` data are lost, the client will be able to recreate them, but it is inconvenient due to the time needed for the operation to complete, and may lead to losing rewards. ### **Copy the Operator keystore file** Assuming [Geth was installed](/tbtc-signer-nodes/tbtc-v2-node-setup/operator-account) for the root user with the command provided in the [Operator Account creation](/tbtc-signer-nodes/tbtc-v2-node-setup/operator-account) step, the operator-key file should be located in the `/.operator-key` directory. ```bash cd /home/$USER/.operator-key ``` Contained within the `operator-key` directory is the account key file (operator key file), its name will be similar to the following: \ `UTC--2018-11-01T06-23-57.810787758Z--fa3da235947aab49d439f3bcb46effd1a7237e32` **Copy (not move!)** this account key file to the `config` directory created above ```bash ls -la cp name_of_account_key_file /home/$USER/keep/config/name_of_account_key_file ``` # Installation A tBTC v2 node can be set up using either a docker or binary installation. The next pages cover the complete setup process for a tBTC v2 node. Two installation methods are supported, Docker and binary, each with its own configuration flow. Choose the method that aligns with your infrastructure standards, then follow the step-by-step instructions to bring your node online and connect it to the Threshold Network. # Docker Installation This page will guide you through Docker setup steps. ### Install Docker Install or update Docker to the latest version. Visit the [Official Docker website](https://docs.docker.com/engine/install/ubuntu/) for detailed instructions. Use the command below to find your installed version if needed: ```bash docker --version ``` ### Docker and Security Best Practices General best practices recommend against running the tBTC v2 client as the `root` user as a security precaution. One security-minded approach is to [Run the Docker daemon as a non-root user](https://docs.docker.com/engine/security/rootless/) (Rootless mode). Next, choose ONE of the following options:\ **Docker Compose** makes managing the container simple, but requires an additional step to ensure the container starts after a reboot.\ The **tBTC v2 Service** option configures the client to run as a service in order to ensure that the client is restarted automatically, should your machine reboot.\ The **Docker Launch Script** is faster to setup, but won't start the client if your machine reboots. {% tabs %} {% tab title="Docker Compose" %} Navigate to `cd /home/$USER/keep/` Create a file named `docker-compose.yaml` Copy the the template below into the file and replace the \ with respective details. ``` version: '3' services: keep-client: image: keepnetwork/keep-client:latest container_name: keep-client restart: on-failure ports: - "3919:3919" - "9601:9601" volumes: - /home/$USER/keep/config/:/mnt/keep/config - /home/$USER/keep/storage/:/mnt/keep/storage environment: - KEEP_ETHEREUM_PASSWORD= - LOG_LEVEL=info logging: options: max-size: "100m" max-file: "3" command: start --ethereum.url "" --ethereum.keyFile "/mnt/keep/config/" --storage.dir "/mnt/keep/storage" --network.announcedAddresses "/ip4//tcp/3919" ``` Save and close the file when finished. To start the tBTC client `sudo docker compose up` tBTC will start up with the console output on screen. Verify that the client is running correctly, then press `CTRL` + `c` to stop the client. Restart the client with the 'detach' flag: `sudo docker compose up -d` To stop the container at a later time, use `sudo docker compose down` #### Starting Container Automatically After Reboot To ensure the tBTC container starts after a server reboot, use the template below to create a service in `/etc/systemd/system/` called `docker-compose-app.service` ``` # /etc/systemd/system/docker-compose-app.service [Unit] Description=Docker Compose Application Service Requires=docker.service After=docker.service StartLimitIntervalSec=60 [Service] WorkingDirectory=/home/$USER/keep/ ExecStart=/usr/local/bin/docker-compose up ExecStop=/usr/local/bin/docker-compose down TimeoutStartSec=0 Restart=on-failure StartLimitBurst=3 [Install] WantedBy=multi-user.target ``` Adjust the `WorkingDirectory` to the path of your tBTC folder. Save and close the file when finished. use `sudo systemctl enable docker-compose-app` to enable the service. {% endtab %} {% tab title="Systemd Service" %} Create the tbtcv2.service file: ```bash cd /etc/systemd/system/ nano tbtcv2.service ``` Paste the following in the tbtcv2.service file: 
[Unit]
Description=tBTC v2 client
After=network.target
Wants=network.target

[Service]
Environment="ETHEREUM_WS_URL=<Ethereum API WS URL>"
Environment="OPERATOR_KEY_FILE_NAME=<Operator Account keyfile name>"
Environment="OPERATOR_KEY_FILE_PASSWORD=<Operator Account keyfile password>"
Environment="PUBLIC_IP=/ip4/<PUBLIC_IP_OF_MACHINE>/tcp/3919"
Environment="CONFIG_DIR=/home/<user name>/keep/config"
Environment="STORAGE_DIR=/home/<user name>/keep/storage"

# These items only apply if you setup rootless-mode.
# Do not enable unless using rootless mode. Don't forget to adjust user UID.
#Environment="XDG_RUNTIME_DIR=/run/<user name>/<user UID>/"
#Environment="DOCKER_HOST=unix:///run/<user name>/<user UID>/docker.sock"

Type=simple
WorkingDirectory=/home/$USER

ExecStart=/usr/bin/docker run \
    --volume ${CONFIG_DIR}:/mnt/keep/config \
    --volume ${STORAGE_DIR}:/mnt/keep/storage \
    --env KEEP_ETHEREUM_PASSWORD=${OPERATOR_KEY_FILE_PASSWORD} \
    --env LOG_LEVEL=info \
    --log-opt max-size=100m \
    --log-opt max-file=3 \
    -p 3919:3919 \
    -p 9601:9601 \
    keepnetwork/keep-client:latest \
    start \
    --ethereum.url ${ETHEREUM_WS_URL} \
    --ethereum.keyFile /mnt/keep/config/${OPERATOR_KEY_FILE_NAME} \
    --storage.dir /mnt/keep/storage \
    --network.announcedAddresses $PUBLIC_IP

Restart=always
RestartSec=15s

[Install]
WantedBy=default.target
Replace the placeholders inside the <> brackets, remove the <> brackets but be sure to not edit anything further. When done, save and close the file. Next, test to make sure your configuration works: ```bash sudo systemctl start tbtcv2 ``` There will be no console output because it will be running in the background. Use systemctl to get the status of the service: ```bash sudo systemctl status tbtcv2 ``` If the service failed, go back and double check your configuration. Another option is to see if the Docker container is running: ```bash docker ps ``` If everything is running as intended, enable the service: ```bash systemctl enable tbtcv2 ``` Now, with the service running, you should make sure that your configuration will tolerate a reboot and start up again automatically. ```bash reboot now ``` Log back in to your machine and check that the service is running. If it is, you're done. If not, go back and review your work. {% endtab %} {% tab title="Docker Container" %} ### Docker Launch Script To launch the tBTC v2 client, several configuration flags and environmental values need to be set. For simplicity, a bash script can be used rather than typing or pasting all the flags into the console. Create the launch script: ``` nano keep.sh ``` And paste the following: ```bash # Keep tBTC v2 Client # # Ethereum endpoint WebSocket URL # This can be a provider such as Infura, Alchemy, Ankr, etc or your own Geth Nodeq # ETHEREUM_WS_URL="wss://mainnet.infura.io/ws/v3/redacted_credentials" # note: only replace characters inside the " ". The Quotation marks must be retained ETHEREUM_WS_URL="" # copied to home/keep/config earlier OPERATOR_KEY_FILE_NAME="" # password set during Operator Account Address creation OPERATOR_KEY_FILE_PASSWORD="" # To configure your node with a Public IP, enter it below. PUBLIC_IP="" # Alternatively, you can use DNS. # To configure DNS, modify the last line of the script # and add your DNS in the following format: # /dns4/bootstrap-1.test.keep.network/tcp/3919 # Setup configuration and storage directories # THESE MUST BE PERSISTENT STORAGE CONFIG_DIR="/home/$USER/keep/config" STORAGE_DIR="/home/$USER/keep/storage" docker run \ --detach \ --restart on-failure \ --volume $CONFIG_DIR:/mnt/keep/config \ --volume $STORAGE_DIR:/mnt/keep/storage \ --env KEEP_ETHEREUM_PASSWORD=$OPERATOR_KEY_FILE_PASSWORD \ --env LOG_LEVEL=info \ --log-opt max-size=100m \ --log-opt max-file=3 \ -p 3919:3919 \ -p 9601:9601 \ keepnetwork/keep-client:latest \ start \ --ethereum.url $ETHEREUM_WS_URL \ --ethereum.keyFile /mnt/keep/config/$OPERATOR_KEY_FILE_NAME \ --storage.dir /mnt/keep/storage \ --network.announcedAddresses /ip4/$PUBLIC_IP/tcp/3919 ``` Save and close the file, and make it executable: ```bash sudo chmod +x keep.sh ``` To launch the tBTC v2 client, execute: 
sudo bash keep.sh
{% hint style="info" %} The `--detach` property will prevent the status messages from the client to be printed to the console. Review the Docker logs for detailed status information. {% endhint %} {% endtab %} {% endtabs %} {% hint style="danger" %} The path shown in the example configuration will differ from yours. Make sure it is configured correctly. {% endhint %} ## Client Startup and Logs Unless the `--detach` flag was removed from the startup script, there will be no console output. In order to check your node, retrieve the Docker logs. First, find your Docker instance identification, it'll be a random combination of words, e.g. `stinky_brownie`: ```bash sudo docker ps ``` Use your specific identification and substitute: ``` sudo docker logs stinky_brownie >& /path/to/output/file ``` Scroll down about half a page, and you should see the following: 

▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓    ▓▓▓▓▓▓▓▀    ▐▓▓▓▓▓▓    ▐▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀      ▐▓▓▓▓▓▓▄▄▄▄         ▓▓▓▓▓▓▄▄▄▄         ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▀        ▐▓▓▓▓▓▓▓▓▓▓         ▓▓▓▓▓▓▓▓▓▓▌        ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄       ▐▓▓▓▓▓▓▀▀▀▀         ▓▓▓▓▓▓▀▀▀▀         ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
  ▓▓▓▓▓▓   ▀▓▓▓▓▓▓▄     ▐▓▓▓▓▓▓     ▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓

Trust math, not hardware.
	
-----------------------------------------------------------------------------------
| Keep Client Node                                                                |
|                                                                                 |
| Version: Version: vX.X.X-XX (4d745f6d0)                                         |
|                                                                                 |
| Operator: 0x_your_operator_address                                              |
|                                                                                 |
| Port: 3919                                                                      |
| IPs : /ip4/111.222.333.444/tcp/3919/ipfs/redacted                               |
|                                                                                 |
| Contracts:                                                                      |
| RandomBeacon   : 0x5499f54b4A1CB4816eefCf78962040461be3D80b                     |
| WalletRegistry : 0x46d52E41C2F300BC82217Ce22b920c34995204eb                     |
| TokenStaking   : 0x01B67b1194C75264d06F808A921228a95C765dd7                     |
-----------------------------------------------------------------------------------
Congratulations, your node is up and running. # Binary Installation This page will guide you through Binary setup steps. {% hint style="warning" %} Choose either Docker installation OR Binary installation. {% endhint %} ### Download the Binary See GitHub for the latest release: Under Assets, copy the path to the compressed binary and use the command below to download the file. Make relevant adjustments to the version as necessary: {% code overflow="wrap" %} ```bash cd /home/keep wget https://github.com/threshold-network/keep-core/releases/download/XX.X.X-XX/keep-client-mainnet-XX.X.X-XX-linux-amd64.tar.gz ``` {% endcode %} After the download completes, use the command below to display the contents of the folder: ```bash ls -la ``` Extract the compressed file: ```bash tar xzvf downloaded-file-name-here.tar.gz ``` {% hint style="info" %} You can save some time and prevent misspelling a file name by typing the first few letter of the file name and pressing the Tab key. This will autocomplete the file name. Be sure to verify the file name prior to pressing the enter key. {% endhint %} ### Configure tBTC v2 Client To launch the tBTC v2 client, several configuration flags and environmental values need to be set. For simplicity, a bash script can be used rather than typing or pasting all the flags into the console. The following flags must be set at a minimum: ```bash --ethereum.url "wss://mainnet-ETH-enpoint-here" --storage.dir "/home/keep/storage" --ethereum.keyFile "/home/keep/config/UTC--Your-Operator-Key-Name" # to configure your node to use your machine's public IP --network.announcedAddresses "/ip4/your.ipv4.address.here/tcp/3919" # to configure your node to use DNS, provide your DNS in the following # format # /dns4/bootstrap-1.test.keep.network/tcp/3919 ``` For a complete list of client commands and flags, see [CLI Options](/tbtc-signer-nodes/tbtc-v2-node-setup/advanced-options/cli-options). To launch the client, execute the following: {% code overflow="wrap" %} ```bash ./keep-client start --ethereum.url "wss://mainnet-ETH-enpoint-here" --storage.dir "/home/keep/storage" --ethereum.keyFile "/home/keep/config/UTC--Your-Operator-Key-Name" --network.announcedAddresses "/ip4/your.ipv4.address.here/tcp/3919" ``` {% endcode %} If everything is configured correctly, the client will request the password for the Operator Account. Supply the password and press Enter. You should see the following shortly: ``` ▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄ ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓ ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ Trust math, not hardware. ----------------------------------------------------------------------------------- | Keep Client Node | | | | Version: Version: vX.X.X-XX (4d745f6d0) | | | | Operator: 0x_your_operator_address | | | | Port: 3919 | | IPs : /ip4/111.222.333.444/tcp/3919/ipfs/redacted | | | | Contracts: | | RandomBeacon : 0x5499f54b4A1CB4816eefCf78962040461be3D80b | | WalletRegistry : 0x46d52E41C2F300BC82217Ce22b920c34995204eb | | TokenStaking : 0x01B67b1194C75264d06F808A921228a95C765dd7 | ----------------------------------------------------------------------------------- ``` Congratulations, your node is up and running. # Updating Nodes Update procedure for the tBTC v2 client depends on installation method ## Docker Installation The following instructions assume your docker install followed [these](/tbtc-signer-nodes/tbtc-v2-node-setup/installation/docker-installation) installation instructions. {% tabs %} {% tab title="Docker Install" %} To update a tBTC node: Pull the new image ```bash docker pull keepnetwork/keep-client:latest ``` Restart the tBTC service ```bash sudo systemctl restart tbtcv2 ``` To free system resources, run ```bash sudo docker container prune ``` ```bash sudo docker image prune ``` Examine logs to ensure the node started correctly. Find Docker instance identification; it'll be a random combination of words, e.g. `stinky_brownie`: ```bash sudo docker ps ``` Use specific identification and substitute accordingly; specify a path and file name for the log file: ```bash sudo docker logs stinky_brownie >& /path/to/output/file ``` Display the log file ```bash cat /path/to/output/file ``` Look for the following and take note of the version: 

▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓    ▓▓▓▓▓▓▓▀    ▐▓▓▓▓▓▓    ▐▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀      ▐▓▓▓▓▓▓▄▄▄▄         ▓▓▓▓▓▓▄▄▄▄         ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▀        ▐▓▓▓▓▓▓▓▓▓▓         ▓▓▓▓▓▓▓▓▓▓▌        ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄       ▐▓▓▓▓▓▓▀▀▀▀         ▓▓▓▓▓▓▀▀▀▀         ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
  ▓▓▓▓▓▓   ▀▓▓▓▓▓▓▄     ▐▓▓▓▓▓▓     ▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓

Trust math, not hardware.
	
-----------------------------------------------------------------------------------
| Keep Client Node                                                                |
|                                                                                 |
| Version: vX.X.X-XX (4d745f6d0)                                         |
|                                                                                 |
| Operator: 0x_your_operator_address                                              |
|                                                                                 |
| Port: 3919                                                                      |
| IPs : /ip4/111.222.333.444/tcp/3919/ipfs/redacted                               |
|                                                                                 |
| Contracts:                                                                      |
| RandomBeacon   : 0x5499f54b4A1CB4816eefCf78962040461be3D80b                     |
| WalletRegistry : 0x46d52E41C2F300BC82217Ce22b920c34995204eb                     |
| TokenStaking   : 0x01B67b1194C75264d06F808A921228a95C765dd7                     |
-----------------------------------------------------------------------------------
Alternatively, verify your client updated by visiting your status page: ``` http://111.222.333.444:9601/metrics ``` Compare the displayed version number to the version number you are expecting, i.e.: ``` client_info{version="vX.X.X-XX"} ``` {% endtab %} {% tab title="Binary Install" %} This install method requires downloading the latest version of the binary. Follow the installation steps provided [here](/tbtc-signer-nodes/tbtc-v2-node-setup/installation/binary-installation). {% endtab %} {% endtabs %} # Advanced Options Advanced configuration options and tBTC v2 client options ### [Logging](/tbtc-signer-nodes/tbtc-v2-node-setup/advanced-options/logging) Configuration options for logging ### [Config File](/tbtc-signer-nodes/tbtc-v2-node-setup/advanced-options/config-file) Application configuration can be stored in a file and passed to the application with the `--config` flag. ### [CLI Options](/tbtc-signer-nodes/tbtc-v2-node-setup/advanced-options/cli-options) ### [Client Info](/tbtc-signer-nodes/tbtc-v2-node-setup/advanced-options/client-info) Client information exposed by the tBTC v2 client. # Logging Optional logging configuration for the tBTC v2 client. ### Configuration Logging can be configured with environment variables. Please see sample settings: ```bash LOG_LEVEL=DEBUG IPFS_LOGGING_FMT=nocolor GOLOG_FILE=/var/log/keep/keep.log GOLOG_TRACING_FILE=/var/log/keep/trace.json ``` {% hint style="success" %} LOG\_LEVEL option DEBUG will generate extensive output. Consider INFO instead. {% endhint %} {% hint style="info" %} If you want to share your LibP2P address with others you can get it from the startup log. When sharing remember to substitute the `/ipv4/` address with the public facing IP of your client if you’re running on a private machine, or replace the entire `/ipv4/` segment with a DNS entry if you’re using a hostname. {% endhint %} # Config File Use a config file to store client configuration. Application configuration can be stored in a file and passed to the application with the `--config` flag. Example: ``` ./keep-client --config /path/to/your/config.toml start ``` Configuration files in formats TOML, YAML and JSON are supported. Sample configuration file: {% code overflow="wrap" %} ```toml # This is a sample TOML configuration file for the Keep client. [ethereum] URL = "ws://127.0.0.1:8546" KeyFile = "/Users/someuser/ethereum/data/keystore/UTC--2018-03-11T01-37-33.202765887Z--AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA8AAAAAAAAA" # Uncomment to override the defaults for transaction status monitoring. # MiningCheckInterval is the interval in which transaction # mining status is checked. If the transaction is not mined within this # time, the gas price is increased and transaction is resubmitted. # # MiningCheckInterval = 60 # 60 sec (default value) # MaxGasFeeCap specifies the maximum gas fee cap the client is # willing to pay for the transaction to be mined. The offered transaction # gas cost can not be higher than the max gas fee cap value. If the maximum # allowed gas fee cap is reached, no further resubmission attempts are # performed. This property should be set only for Ethereum. In case of # legacy non-EIP-1559 transactions, this field works in the same way as # `MaxGasPrice` property. # # MaxGasFeeCap = "500 Gwei" # 500 Gwei (default value) # Uncomment to enable Ethereum node rate limiting. Both properties can be # used together or separately. # # RequestsPerSecondLimit sets the maximum average number of requests # per second which can be executed against the Ethereum node. # All types of Ethereum node requests are rate-limited, # including view function calls. # # RequestsPerSecondLimit = 150 # ConcurrencyLimit sets the maximum number of concurrent requests which # can be executed against the Ethereum node at the same time. # This limit affects all types of Ethereum node requests, # including view function calls. # # ConcurrencyLimit = 30 # BalanceAlertThreshold defines a minimum value of the operator's account # balance below which the client will start reporting errors in logs. # A value can be provided in `wei`, `Gwei` or `ether`, e.g. `7.5 ether`, # `7500000000 Gwei`. # # BalanceAlertThreshold = "0.5 ether" # 0.5 ether (default value) [bitcoin.electrum] # URL to the Electrum server in format: `scheme://hostname:port`. # Should be uncommented only when using a custom Electrum server. Otherwise, # one of the default embedded servers is selected randomly at startup. # URL = "tcp://127.0.0.1:50001" # Timeout for a single attempt of Electrum connection establishment. # ConnectTimeout = "10s" # Timeout for Electrum connection establishment retries. # ConnectRetryTimeout = "1m" # Timeout for a single attempt of Electrum protocol request. # RequestTimeout = "30s" # Timeout for Electrum protocol request retries. # RequestRetryTimeout = "2m" # Interval for connection keep alive requests. # KeepAliveInterval = "5m" [network] Bootstrap = false Peers = [ "/ip4/127.0.0.1/tcp/3919/ipfs/16Uiu2HAmFRJtCWfdXhZEZHWb4tUpH1QMMgzH1oiamCfUuK6NgqWX", ] Port = 3920 # Uncomment to override the node's default addresses announced in the network # AnnouncedAddresses = ["/dns4/example.com/tcp/3919", "/ip4/80.70.60.50/tcp/3919"] # Uncomment to enable courtesy message dissemination for topics this node is # not subscribed to. Messages will be forwarded to peers for the duration # specified as a value in seconds. # Message dissemination is disabled by default and should be enabled only # on selected bootstrap nodes. It is not a good idea to enable dissemination # on non-bootstrap node as it may clutter communication and eventually lead # to blacklisting the node. The maximum allowed value is 90 seconds. # # DisseminationTime = 90 [storage] Dir = "/my/secure/location" # ClientInfo exposes metrics and diagnostics modules. # # Metrics collects and exposes information useful for external monitoring tools usually # operating on time series data. # All values exposed by metrics module are quantifiable or countable. # # The following metrics are available: # - connected peers count # - connected bootstraps count # - eth client connectivity status # # Diagnostics module exposes the following information: # - list of connected peers along with their network id and ethereum operator address # - information about the client's network id and ethereum operator address [clientInfo] Port = 9601 # NetworkMetricsTick = 60 # EthereumMetricsTick = 600 # Uncomment to overwrite default values for TBTC config. # # [tbtc] # PreParamsPoolSize = 3000 # PreParamsGenerationTimeout = "2m" # PreParamsGenerationDelay = "10s" # PreParamsGenerationConcurrency = 1 # KeyGenConcurrency = 1 # Developer options to work with locally deployed contracts # # [developer] # TokenStakingAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" # RandomBeaconAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" # WalletRegistryAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" # BridgeAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" ``` {% endcode %} # CLI Options Review available CLI Options below. {% embed url="" %} ``` $ keep-client start --help Starts the Keep Client in the foreground Usage: keep-client start [flags] Flags: --ethereum.url string WS connection URL for Ethereum client. --ethereum.keyFile string The local filesystem path to Keep operator account keyfile. --ethereum.miningCheckInterval duration The time interval in seconds in which transaction mining status is checked. If the transaction is not mined within this time, the gas price is increased and transaction is resubmitted. (default 1m0s) --ethereum.maxGasFeeCap wei The maximum gas fee the client is willing to pay for the transaction to be mined. If reached, no resubmission attempts are performed. (default 500 gwei) --ethereum.requestPerSecondLimit int Request per second limit for all types of Ethereum client requests. (default 150) --ethereum.concurrencyLimit int The maximum number of concurrent requests which can be executed against Ethereum client. (default 30) --ethereum.balanceAlertThreshold wei The minimum balance of operator account below which client starts reporting errors in logs. (default 500000000 gwei) --bitcoin.electrum.url scheme://hostname:port URL to the Electrum server in format: scheme://hostname:port. --bitcoin.electrum.connectTimeout duration Timeout for a single attempt of Electrum connection establishment. (default 10s) --bitcoin.electrum.connectRetryTimeout duration Timeout for Electrum connection establishment retries. (default 1m0s) --bitcoin.electrum.requestTimeout duration Timeout for a single attempt of Electrum protocol request. (default 30s) --bitcoin.electrum.requestRetryTimeout duration Timeout for Electrum protocol request retries. (default 2m0s) --bitcoin.electrum.keepAliveInterval duration Interval for connection keep alive requests. (default 5m0s) --network.bootstrap Run the client in bootstrap mode. --network.peers strings Addresses of the network bootstrap nodes. -p, --network.port int Keep client listening port. (default 3919) --network.announcedAddresses strings Overwrites the default Keep client address announced in the network. Should be used for NAT or when more advanced firewall rules are applied. --network.disseminationTime int Specifies courtesy message dissemination time in seconds for topics the node is not subscribed to. Should be used only on selected bootstrap nodes. (0 = none) --storage.dir string Location to store the Keep client key shares and other sensitive data. --clientInfo.port int Client Info HTTP server listening port. (default 9601) --clientInfo.networkMetricsTick duration Client Info network metrics check tick in seconds. (default 1m0s) --clientInfo.ethereumMetricsTick duration Client info Ethereum metrics check tick in seconds. (default 10m0s) --tbtc.preParamsPoolSize int tECDSA pre-parameters pool size. (default 1000) --tbtc.preParamsGenerationTimeout duration tECDSA pre-parameters generation timeout. (default 2m0s) --tbtc.preParamsGenerationDelay duration tECDSA pre-parameters generation delay. (default 10s) --tbtc.preParamsGenerationConcurrency int tECDSA pre-parameters generation concurrency. (default 1) --tbtc.keyGenerationConcurrency int tECDSA key generation concurrency. (default number of cores) --developer.bridgeAddress string Address of the Bridge smart contract --developer.lightRelayAddress string Address of the LightRelay smart contract --developer.lightRelayMaintainerProxyAddress string Address of the LightRelayMaintainerProxy smart contract --developer.randomBeaconAddress string Address of the RandomBeacon smart contract --developer.tokenStakingAddress string Address of the TokenStaking smart contract --developer.walletRegistryAddress string Address of the WalletRegistry smart contract --developer.walletCoordinatorAddress string Address of the WalletCoordinator smart contract Global Flags: -c, --config string Path to the configuration file. Supported formats: TOML, YAML, JSON. --developer Developer network --testnet Testnet network Environment variables: KEEP_ETHEREUM_PASSWORD Password for Keep operator account keyfile decryption. LOG_LEVEL Space-delimited set of log level directives; set to "help" for help. ``` # Client Info Client information exposed by the tBTC v2 client. The client exposes metrics and diagnostics on a configurable port (default: `9601`) under `/metrics` and `/diagnostics` resources. The data can be consumed by Prometheus to monitor the state of a node. ### Metrics The client exposes the following metrics: * connected peers count, * connected bootstraps count, * Ethereum client connectivity status (if a simple read-only CALL can be executed). Metrics are enabled once the client starts. It is possible to customize the port at which metrics endpoint is exposed as well as the frequency with which the metrics are collected. Exposed metrics contain the value and timestamp at which they were collected. Example metrics endpoint call result: ``` $ curl localhost:9601/metrics # TYPE connected_peers_count gauge connected_peers_count 108 1623235129569 # TYPE connected_bootstrap_count gauge connected_bootstrap_count 10 1623235129569 # TYPE eth_connectivity gauge eth_connectivity 1 1623235129789 ``` ### Diagnostics The client exposes the following diagnostics: * list of connected peers along with their network id and Ethereum operator address, * information about the client’s network id and Ethereum operator address. Diagnostics are enabled once the client starts. It is possible to customize the port at which diagnostics endpoint is exposed. Example diagnostics endpoint call result: ``` $ curl localhost:9601/diagnostics { "client_info" { "ethereum_address":"0xDcd4199e22d09248cA2583cBDD2759b2acD22381", "network_id":"16Uiu2HAkzYFHsqbwt64ZztWWK1hyeLntRNqWMYFiZjaKu1PZgikN" }, "connected_peers": [ {"ethereum_address":"0x3712C6fED51CECA83cA953f6FF3458f2339436b4","network_id":"16Uiu2HAkyYtzNoWuF3ULaA7RMfVAxvfQQ9YRvRT3TK4tXmuZtaWi"}, {"ethereum_address":"0x4bFa10B1538E8E765E995688D8EEc39C717B6797","network_id":"16Uiu2HAm9d4MG4LNrwkFmugD2pX7frm6ZmA4vE3EFAEjk7yaoeLd"}, {"ethereum_address":"0x650A9eD18Df873cad98C88dcaC8170531cAD2399","network_id":"16Uiu2HAkvjVWogUk2gq6VTNLQdFoSHXYpobJdZyuAYeoWD66e8BD"}, ... ] } ``` # Frequently Asked Questions Find answers to some of the most commonly asked questions here. ### Errors in Logs or Console Certain errors may be reported by your node. See a sample below: {% code overflow="wrap" %} ``` 2022-10-10T18:30:42.571Z WARN keep-beacon beacon/node.go:78 selecting group not possible: [cannot select group in the sortition pool: [got error [execution reverted: Sortition pool unlocked] while resolving original error [execution reverted: Sortition pool unlocked]]] {"seed": "0x29c60250c292e108e6abf4dcc76cb161d8ae8e803c4d4419eaff6e97f514b080"} ``` {% endcode %} {% hint style="info" %} This warning is normal and may happen. It will disappear and reappear periodically. {% endhint %} When the pool is locked, new operators cannot join but sortition (selecting operators from the pool) is possible. When the pool is unlocked, new operators can join but the sortition is not possible. Once the first set of Signers is registered, the pool will get locked for some time to allow the sortition. After some time, when another set of Signers are added, the pool will be unlocked again. # Sepolia Testnet Here you'll find the [Sepolia testnet](https://dashboard.test.threshold.network/) version of the Threshold dapp.

Sepolia Testnet - Threshold Dashboard

# Testnet Node Setup This page will show you how to launch a tBTC v2 node on the testnet. {% hint style="danger" %} This is a TESTNET guide document. {% endhint %} ## Recommended Machine Types {% hint style="info" %} While it is possible to run the client on a local machine, this is not recommended. {% endhint %} Your operating environment will ultimately dictate what machine type to go with. This is particularly relevant if you’re running a containerized solution where multiple applications are sharing VM resources. The below types are sufficient for running one instance of the tBTC v2 Node. The preferred OS is Ubuntu. | VPS Provider | VPS Type | | ------------ | -------------------------------------------- | | AWS | c5.large | | Azure | F2s v2 | | Google Cloud | n2-highcpu-2 | | Self-hosted | 2 vCPU / 2 GB RAM / 1 GiB Persistent Storage | ## **Ethereum API** A Keep Node requires a connection to a WebSocket Ethereum API. You should obtain a WS API URL from a service provider (e.g., [Alchemy](https://www.alchemy.com/), [Infura](https://www.infura.io/), [Ankr](https://www.ankr.com/rpc-service/)) or run your own Ethereum node (e.g. [Geth](https://geth.ethereum.org/)). The client requires an Ethereum Key File of an Operator Account to connect to the Ethereum chain. This account is created in a subsequent step using Geth (GoEthereum). The Ethereum Key File is expected to be encrypted with a password. The password has to be provided in a prompt after the client starts or configured as a `KEEP_ETHEREUM_PASSWORD` environment variable. The Operator Account has to maintain a positive Ether balance at all times. {% hint style="warning" %} Please do NOT reuse an operator account that is being used for PRE or other applications. {% endhint %} ## Install Geth (GoEthereum) To create a new Ethereum account, [install Geth](https://geth.ethereum.org/docs/install-and-build/installing-geth#ubuntu-via-ppas) (GoEthereum) and create a new account using the command below. This account will subsequently be referred to as the Operator Account. 
geth account new --keystore ./operator-key
When prompted, provide a password to protect the operator key file. {% hint style="info" %} Use a password manager to generate a strong password and store it safely. It will be needed again during setup. {% endhint %} {% hint style="warning" %} Avoid passwords that contain the following characters: ', ", \`, $\ These characters may be interpreted as part of the configuration, which can lead to undesirable outcomes that may be extremely time-intensive to correct. {% endhint %} Once the process completes, your public key will be displayed. Take note of your Operator Account public key. {% hint style="danger" %} DO NOT LOSE THE PASSWORD TO THE OPERATOR ACCOUNT. {% endhint %} ### Funding your Operator Account Your Operator Account will need to be funded with sepolia ETH and maintain a positive balance at all times to ensure proper operation and availability of your tBTC v2 node. ## Network Configuration The node has to be accessible publicly to establish and maintain connections with bootstrap nodes and discovered peers. {% hint style="info" %} Update firewall rules as necessary, including application level firewalls. {% endhint %} The node exposes metrics and diagnostics services for monitoring. A network port has to be exposed publicly, so the peers can connect to your node. A Diagnostics Port has to be exposed publicly, for the rewards allocation. | Purpose | Config Property | Protocol | Default | | ------- | --------------- | -------- | ------- | | Network | network.port | TCP | 3919 | | Status | clientInfo.port | TCP | 9601 | {% hint style="info" %} A Diagnostics Port has to be exposed publicly for the rewards allocation. {% endhint %} ### **Announced Addresses** An Announced Address is a layered addressing information (`multiaddress`/`multiaddr`) announced to the Threshold Network that is used by peers to connect with your node, e.g.: `/dns4/bootstrap-0.test.keep.network/tcp/3919` or `/ip4/104.154.61.116/tcp/3919`. If the machine you’re running your node on is not exposing a public IP (e.g., it is behind NAT), you should set the `network.AnnouncedAddresses` (flag: `--network.announcedAddresses`) configuration property to an address (`ip4` or `dns4`) under which your node is reachable for the public. To read more about `multiaddress` see the [libp2p documentation](https://docs.libp2p.io/reference/glossary/#multiaddr). ## Create Folder Structure The client requires two persistent directories. These directories will store configuration files and data generated and used by the client. It is highly recommended to create frequent backups of these directories. Loss of these data may be catastrophic and may lead to slashing. {% hint style="warning" %} It is crucial to ensure that the data directory is persisted and backed up regularly. {% endhint %} #### Create folders for tBTC v2 client ```bash cd /home mkdir keep cd keep mkdir storage config ``` The tBTC v2 client will create two subdirectories within the storage directory: `keystore` and `work`. You do not need to create these. The `keystore` subdirectory contains sensitive key material data generated by the client. Loosing the `keystore` data is a serious protocol offense and leads to slashing and potentially losing funds. {% hint style="info" %} It is the operator’s responsibility to ensure the keystore data are not lost under any circumstances. {% endhint %} The `work` directory contains data generated by the client that should persist the client restarts or relocations. If the `work` data are lost the client will be able to recreate them, but it is inconvenient due to the time needed for the operation to complete and may lead to losing rewards. ## **Copy Operator keystore file** Assuming [Geth was installed](/tbtc-signer-nodes/tbtc-v2-node-setup/operator-account) for the root user with the command provided in the [Operator Account creation](/tbtc-signer-nodes/tbtc-v2-node-setup/operator-account) step, the operator-key file should be located in the `~/operator-key` directory. ```bash cd ~/operator-key ``` Contained within the `operator-key` directory is the account key file (operator key file), its name will be similar to the following: \ `UTC--2018-11-01T06-23-57.810787758Z--fa3da235947aab49d439f3bcb46effd1a7237e32` **Copy (not move!)** this account key file to the `config` directory created above ```bash ls -la cp name_of_account_key_file /home/keep/config/name_of_account_key_file ``` ## Install Docker Install or update Docker to the latest version. Visit the [Official Docker website](https://docs.docker.com/engine/install/ubuntu/) for detailed instructions. Use the command below to find your installed version if needed: ```bash docker --version ``` ## Docker Launch Script To launch the tBTC v2 client, several configuration flags and environmental values need to be set. For simplicity, a bash script can be used rather than typing or pasting all the flags into the console. Create the launch script: ``` nano keep.sh ``` And paste the following: ```bash # Keep Testnet tBTC v2 Client # # Ethereum endpoint WebSocket URL # This can be a provider such as Infura, Alchemy, Ankr, etc or your own Geth Nodeq # ETHEREUM_WS_URL="wss://sepolia.infura.io/ws/v3/redacted_credentials" # note: only replace characters inside the " ". The Quotation marks must be retained ETHEREUM_WS_URL="" # copied to home/keep/config earlier OPERATOR_KEY_FILE_NAME="" # password set during Operator Account Address creation OPERATOR_KEY_FILE_PASSWORD="" # To configure your node with a Public IP, enter it below. PUBLIC_IP="" # Alternatively, you can use DNS. # To configure DNS, modify the last line of the script # and add your DNS in the following format: # /dns4/bootstrap-1.test.keep.network/tcp/3919 # Setup configuration and storage directories # THESE MUST BE PERSISTENT STORAGE CONFIG_DIR="/home/keep/config" STORAGE_DIR="/home/keep/storage" docker run \ --detach \ --restart on-failure \ --volume $CONFIG_DIR:/mnt/keep/config \ --volume $STORAGE_DIR:/mnt/keep/storage \ --env KEEP_ETHEREUM_PASSWORD=$OPERATOR_KEY_FILE_PASSWORD \ --env LOG_LEVEL=info \ --log-opt max-size=100m \ --log-opt max-file=3 \ -p 3919:3919 \ -p 9601:9601 \ us-docker.pkg.dev/keep-test-f3e0/public/keep-client \ start \ --testnet \ --ethereum.url $ETHEREUM_WS_URL \ --ethereum.keyFile /mnt/keep/config/$OPERATOR_KEY_FILE_NAME \ --storage.dir /mnt/keep/storage \ --network.announcedAddresses /ip4/$PUBLIC_IP/tcp/3919 ``` Save and close the file, and make it executable: ```bash sudo chmod +x keep.sh ``` To launch the tBTC v2 client, execute: 
sudo bash keep.sh
{% hint style="info" %} The `--detach` property will prevent the status messages from the client to be printed to the console. Review the Docker logs for detailed status information. {% endhint %} {% hint style="danger" %} The path shown in the example configuration will differ from yours. Make sure it is configured correctly. {% endhint %} ## Client Startup Unless the `--detach` flag was removed from the startup script; there will be no console output. To check your node, retrieve the Docker logs. First, find your Docker instance identification; it'll be a random combination of words, e.g. `stinky_brownie`: ```bash sudo docker ps ``` Use your specific identification and substitute: ``` sudo docker logs stinky_brownie >& /path/to/output/file ``` Scroll down about half a page, and you should see the following: 

▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓    ▓▓▓▓▓▓▓▀    ▐▓▓▓▓▓▓    ▐▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀      ▐▓▓▓▓▓▓▄▄▄▄         ▓▓▓▓▓▓▄▄▄▄         ▐▓▓▓▓▓▌   ▐▓▓▓▓▓▓
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▀        ▐▓▓▓▓▓▓▓▓▓▓         ▓▓▓▓▓▓▓▓▓▓▌        ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  ▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄       ▐▓▓▓▓▓▓▀▀▀▀         ▓▓▓▓▓▓▀▀▀▀         ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
  ▓▓▓▓▓▓   ▀▓▓▓▓▓▓▄     ▐▓▓▓▓▓▓     ▓▓▓▓▓   ▓▓▓▓▓▓     ▓▓▓▓▓   ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓▓▓

Trust math, not hardware.
	
-----------------------------------------------------------------------------------
| Keep Client Node                                                                |
|                                                                                 |
| Version: Version: vX.X.XX (4d745f6d0)                                         |
|                                                                                 |
| Operator: 0x_your_operator_address                                              |
|                                                                                 |
| Port: 3919                                                                      |
| IPs : /ip4/111.222.333.444/tcp/3919/ipfs/redacted                               |
|                                                                                 |
| Contracts:                                                                      |
| RandomBeacon   : 0x2bA82903B635a96154A515488d2952E86D6adc3A                     |
| WalletRegistry : 0x2363cc10b7680000C02E4a7067A68d1788ffc86F                     |
| TokenStaking   : 0x69f962a0fbA5635e84eC94131f9072108E2E4F24                     |
-----------------------------------------------------------------------------------
Congratulations, your node is up and running. # tBTC SDK Build with Bitcoin using Threshold's tBTC SDK tBTC SDK is a TypeScript library that provides effortless access to the fundamental features of the tBTC Bitcoin bridge. The SDK allows developers to integrate tBTC into their own applications and offer the power of trustless tokenized Bitcoin to their users. The SDK documentation consists of the following parts: * [Quickstart](/app-development/tbtc-sdk/quickstart) * [Architecture](/app-development/tbtc-sdk/architecture) * [Guides](/app-development/tbtc-sdk/guides) * [API Reference](https://github.com/keep-network/tbtc-v2/tree/main/typescript/api-reference) For a high-level overview of the tBTC protocol, please see the [tBTC Bitcoin Bridge](/tbtc-v2) section. # Quickstart Here you can find instructions explaining how to use the SDK in your own project. ### Installation To install the tBTC SDK in your project, run: {% tabs %} {% tab title="yarn" %} {% code fullWidth="false" %} ```bash yarn add @keep-network/tbtc-v2.ts ``` {% endcode %} {% endtab %} {% tab title="npm" %} ```bash npm i @keep-network/tbtc-v2.ts ``` {% endtab %} {% endtabs %} Please note that you will also need to install the [ethers v5](https://docs.ethers.org/v5) library to initialize a signer or provider. To do so, invoke: {% tabs %} {% tab title="yarn" %} ```bash yarn add ethers@legacy-v5 ``` {% endtab %} {% tab title="npm" %} ```bash npm i ethers@legacy-v5 ``` {% endtab %} {% endtabs %} {% hint style="warning" %} ``` The SDK depends on ethers v5. Proper support for newer ethers versions is not guaranteed right now. ``` {% endhint %} ### Usage Here is a brief example demonstrating the use of the SDK in Ethereum: ```typescript // Import SDK entrypoint component. import { TBTC } from "@keep-network/tbtc-v2.ts" // Create an instance of ethers signer. const signer = (...) // Initialize the SDK for Ethereum only. const sdk = await TBTC.initializeMainnet(signer) // Access SDK features. sdk.deposits.(...) sdk.redemptions.(...) // Access tBTC smart contracts directly. sdk.tbtcContracts.(...) // Access Bitcoin client directly. sdk.bitcoinClient.(...) ``` #### Crosschain Here is a brief example demonstrating the use of the SDK in some L2, e.g. Arbitrum: ```typescript // Import SDK entrypoint component. import { TBTC } from "@keep-network/tbtc-v2.ts" // Create an instance of ethers provider. const ethProvider = (...) // Create an instance of ethers signer. const arbitrumSigner = (...) // Initialize the SDK for Ethereum only. const sdk = await TBTC.initializeMainnet(ethProvider, true) // Initialize it for any L2 (E.g., Arbitrum) await sdk.initializeCrossChain("Arbitrum", arbitrumSigner); // Access SDK features. sdk.deposits.(...) sdk.redemptions.(...) // Access tBTC smart contracts directly. sdk.tbtcContracts.(...) // Access Bitcoin client directly. sdk.bitcoinClient.(...) ``` # Architecture The following diagram presents the architecture of the tBTC SDK and its place in the ecosystem:
As you can see, the SDK consists of several major parts: * `TBTC` component * Feature services * Shared libraries ### `TBTC` component The `TBTC` component is the main entry point to the SDK. It provides different ways to initialize the SDK that are supposed to address the common use cases (see [Initialize SDK](/app-development/tbtc-sdk/guides/initialize-sdk) guide to learn more). Moreover, the `TBTC` component gives access to the SDK core features through feature services as well as low-level direct access to the underlying tBTC smart contracts and Bitcoin network client. ### Feature services The SDK feature services provide seamless access to the core features of the tBTC bridge. The most important features of the SDK are: * **Deposits:** deposit and mint flow for BTC depositors * **Redemptions:** unmint and redeem flow for TBTC redeemers * **Maintenance:** authorized maintenance actions for maintainers (e.g. optimistic minting guardians) ### Shared libraries Shared libraries are reusable modules that provide cross-cutting concerns leveraged by multiple feature services and the `TBTC` component. The main shared libraries of the SDK are: * **Bitcoin**: interfaces and utilities necessary to interact with the Bitcoin chain * **Contracts**: chain-agnostic interfaces allowing interaction with tBTC smart contracts * **Electrum**: Electrum-based implementation of the Bitcoin client * **Ethereum**: implementations of tBTC smart contract interfaces for the Ethereum chain * **Utils**: general utility functions # Guides # Initialize SDK Before initializing the tBTC SDK instance in your project, you need to answer the following questions: * What Bitcoin network and which tBTC contracts do you plan to interact with? * Do you want to perform just read-only actions or send transactions as well? Answering those questions will allow initializing the SDK in the right way. The SDK is prepared to handle common use cases but provides some flexibility as well. This guide explains that in detail. ## Specific guides {% hint style="info" %} These guides will show you how to initialize the SDK in mainnet, testnet, crosschain or custom mode. {% endhint %} {% content-ref url="/pages/eoNzev0ciRsjBzGE4Wh7" %} [Ethereum and Bitcoin mainnet](/app-development/tbtc-sdk/guides/initialize-sdk/ethereum-and-bitcoin-mainnet) {% endcontent-ref %} {% content-ref url="/pages/IyyThGGiDlY4l6D21QDf" %} [Ethereum and Bitcoin testnet](/app-development/tbtc-sdk/guides/initialize-sdk/ethereum-and-bitcoin-testnet) {% endcontent-ref %} {% content-ref url="/pages/vzYgTQooYel4wmCBWok2" %} [Crosschain](/app-development/tbtc-sdk/guides/initialize-sdk/crosschain) {% endcontent-ref %} {% content-ref url="/pages/qJOdHUlK5bVgW7WuzWGQ" %} [Custom mode](/app-development/tbtc-sdk/guides/initialize-sdk/custom-mode) {% endcontent-ref %} # Ethereum and Bitcoin mainnet This is the most common case when you want to use the SDK to interact with the tBTC bridge on Ethereum and Bitcoin mainnet. The SDK addresses it by exposing the `TBTC.initializeMainnet` function. That function: * Takes an Ethers signer or provider as a parameter and uses it to interact with tBTC contracts deployed on Ethereum mainnet * Automatically configures an Electrum Bitcoin client to communicate with the Bitcoin mainnet (communication is done through a set of pre-configured Electrum servers) The following code snippet presents the usage of this function: ```typescript import * as ethers from "ethers" import { TBTC } from "@keep-network/tbtc-v2.ts" // Create an Ethers provider. Pass the URL of an Ethereum mainnet node. // For example, Alchemy or Infura. const provider = new ethers.providers.JsonRpcProvider("...") // Create an Ethers signer. Pass the private key and the above provider. const signer = new ethers.Wallet("...", provider) // If you want to initialize the SDK just for read-only actions, it is // enough to pass the provider. const sdkReadonly = await TBTC.initializeMainnet(provider) // If you want to make transactions as well, you have to pass the signer. const sdk = await TBTC.initializeMainnet(signer) ``` {% hint style="info" %} The above code snippet presents just one way of creating an Ethers signer/provider. Please refer [Ethers v5 documentation](https://docs.ethers.org/v5/api) to learn more. {% endhint %} # Ethereum and Bitcoin testnet This is the case where you want to use the SDK to interact with the tBTC bridge on Ethereum and Bitcoin testnet. The SDK addresses it by exposing the `TBTC.initializeSepolia` function. That function: * Takes an Ethers signer or provider as a parameter and uses it to interact with tBTC contracts deployed on Ethereum Sepolia * Automatically configures an Electrum Bitcoin client to communicate with the Bitcoin testnet (communication is done through a set of pre-configured Electrum servers) The usage of this function is exactly the same as for the previous `TBTC.initializeMainnet` function. # Crosschain This mode of the SDK will initialize Ethereum, Bitcoin and an L2 to work with tBTC. Compatible with mainnet and testnet. {% hint style="info" %} Currently only functional with **Arbitrum**, soon more blockchains will be available. {% endhint %} ## Mainnet The SDK addresses it by exposing the `TBTC.initializeMainnet` function. That function: * Takes an Ethers signer or provider as a parameter and uses it to interact with tBTC contracts deployed on Ethereum mainnet * Needs to receive as a second parameter the value `true` to activate the crosschain mode. * Automatically configures an Electrum Bitcoin client to communicate with the Bitcoin mainnet (communication is done through a set of pre-configured Electrum servers) The following code snippet presents the usage of this function: ```typescript import * as ethers from "ethers" import { TBTC } from "@keep-network/tbtc-v2.ts" // Create an Ethers provider. Pass the URL of an Ethereum and Arbitrum mainnet node. // For example, Alchemy or Infura. const ethProvider = new ethers.providers.JsonRpcProvider("...") const arbProvider = new ethers.providers.JsonRpcProvider("...") // Create an Ethers signer. Pass the private key and the above provider. const arbSigner = new ethers.Wallet("...", provider) // If you want to initialize the SDK, it is enough to pass the provider. const sdk = await TBTC.initializeMainnet(ethProvider, true) // Initialize cross-chain functionality for TBTC on Arbitrum await sdk.initializeCrossChain("Arbitrum", arbSigner); // The SDK will be ready to launch read and write in Arbitrum. ``` {% hint style="info" %} The above code snippet presents just one way of creating an Ethers signer/provider. Please refer [Ethers v5 documentation](https://docs.ethers.org/v5/api) to learn more. {% endhint %} ## Testnet The SDK addresses it by exposing the `TBTC.initializeSepolia` function. That function: * Takes an Ethers signer or provider as a parameter and uses it to interact with tBTC contracts deployed on Ethereum Sepolia * Needs to receive as a second parameter the value `true` to activate the crosschain mode. * Automatically configures an Electrum Bitcoin client to communicate with the Bitcoin testnet (communication is done through a set of pre-configured Electrum servers) The usage of this function is exactly the same as for the previous `TBTC.initializeMainnet` function. ```typescript import * as ethers from "ethers" import { TBTC } from "@keep-network/tbtc-v2.ts" // Create an Ethers provider. Pass the URL of an Ethereum and Arbitrum testnet node. // For example, Alchemy or Infura. const ethProvider = new ethers.providers.JsonRpcProvider("...") const arbProvider = new ethers.providers.JsonRpcProvider("...") // Create an Ethers signer. Pass the private key and the above provider. const arbSigner = new ethers.Wallet("...", provider) // If you want to initialize the SDK, it is enough to pass the provider. const sdk = await TBTC.initializeSepolia(ethProvider, true) // Initialize cross-chain functionality for TBTC on Arbitrum await sdk.initializeCrossChain("Arbitrum", arbSigner); // The SDK will be ready to launch read and write in Arbitrum. ``` # Custom mode Apart from the opinionated initialization functions, the SDK provides a flexible TBTC.initializeCustom function for advanced users. This function allows setting up the SDK to work with custom tBTC smart contracts and custom Bitcoin network. For example, it can be used to address the following use cases: #### Using locally deployed tBTC contracts and local Bitcoin network This is the common case when you are setting up a development environment. Let's suppose you have deployed the tBTC contracts on your local Ethereum chain and you are using a [local Bitcoin regtest node](https://developer.bitcoin.org/examples/testing.html#regtest-mode). The following snippet demonstrates SDK initialization in that case: ```typescript import * as ethers from "ethers" import { TBTC, TBTCContracts, EthereumBridge, EthereumTBTCToken, EthereumTBTCVault, EthereumWalletRegistry, ElectrumClient, } from "@keep-network/tbtc-v2.ts" // Create an Ethers provider. Pass the URL of your local Ethereum node. const provider = new ethers.providers.JsonRpcProvider("...") // Create an Ethers signer. Pass the private key and the above provider. const signer = new ethers.Wallet("...", provider) // Create a reference to your locally deployed tBTC contracts. // ABI will be loaded from the following contract packages: // - @keep-network/tbtc-v2 // - @keep-network/ecdsa const tbtcContracts: TBTCContracts = { bridge: new EthereumBridge({address: "...", signerOrProvider: signer}), tbtcToken: new EthereumTBTCToken({address: "...", signerOrProvider: signer}), tbtcVault: new EthereumTBTCVault({address: "...", signerOrProvider: signer}), walletRegistry: new EthereumWalletRegistry({address: "...", signerOrProvider: signer}) } // Create an Electrum Bitcoin client pointing to your local regtest node. const bitcoinClient = ElectrumClient.fromUrl("...") // Initialize the SDK. const sdk = await TBTC.initializeCustom(tbtcContracts, bitcoinClient) ``` #### Using a custom Bitcoin client instead of the automatically configured one In some cases, you may want to initialize the SDK for mainnet/testnet, but point the Electrum Bitcoin client to your own server. Here is how you can do that: ```typescript import * as ethers from "ethers" import { TBTC, TBTCContracts, loadEthereumContracts, ElectrumClient } from "@keep-network/tbtc-v2.ts" // Create an Ethers provider. Pass a URL of an Ethereum mainnet node. // For example, Alchemy or Infura. const provider = new ethers.providers.JsonRpcProvider("...") // Create an Ethers signer. Pass the private key and the above provider. const signer = new ethers.Wallet("...", provider) // Load tBTC Ethereum mainnet contracts manually. const tbtcContracts: TBTCContracts = await loadEthereumContracts(signer, "mainnet") // Create an Electrum Bitcoin client pointing to your own mainnet server. const bitcoinClient = ElectrumClient.fromUrl("...") // Initialize the SDK with Electrum Bitcoin client pointing to your own server. const sdk = await TBTC.initializeCustom(tbtcContracts, bitcoinClient) ``` You can even use another (non-Electrum) Bitcoin client implementation. This is how you can achieve that: ```typescript import * as ethers from "ethers" import { TBTC, TBTCContracts, loadEthereumContracts, BitcoinClient, } from "@keep-network/tbtc-v2.ts" // Create an Ethers provider. Pass a URL of an Ethereum mainnet node. // For example, Alchemy or Infura. const provider = new ethers.providers.JsonRpcProvider("...") // Create an Ethers signer. Pass the private key and the above provider. const signer = new ethers.Wallet("...", provider) // Load tBTC Ethereum mainnet contracts manually. const tbtcContracts: TBTCContracts = await loadEthereumContracts(signer, "mainnet") // Create your own Bitcoin client implementation. class OwnBitcoinClientImpl implements BitcoinClient { // Implement all required methods } // Initialize your own Bitcoin client implementation. const bitcoinClient = new OwnBitcoinClientImpl() // Initialize the SDK with your own Bitcoin client implementation. const sdk = await TBTC.initializeCustom(tbtcContracts, bitcoinClient) ``` #### Using mock tBTC contracts and mock Bitcoin network Sometimes, you may also want to initialize the SDK with mock tBTC contracts and Bitcoin network for testing purposes. This can be done as follows: ```typescript import { TBTC, TBTCContracts, Bridge, TBTCToken, TBTCVault, WalletRegistry, BitcoinClient, } from "@keep-network/tbtc-v2.ts" // Create mock Bridge contract implementation. class MockBridge implements Bridge { // Implement all required methods } // Create mock TBTCToken contract implementation. class MockTBTCToken implements TBTCToken { // Implement all required methods } // Create mock TBTCVault contract implementation. class MockTBTCVault implements TBTCVault { // Implement all required methods } // Create mock WalletRegistry contract implementation. class MockWalletRegistry implements WalletRegistry { // Implement all required methods } // Create mock BitcoinClient contract implementation. class MockBitcoinClient implements BitcoinClient { // Implement all required methods } // Create instances of the mock contracts. const tbtcContracts: TBTCContracts = { bridge: new MockBridge(), tbtcToken: new MockTBTCToken(), tbtcVault: new MockTBTCVault(), walletRegistry: new MockWalletRegistry() } // Create an instance of the mock Bitcoin client. const bitcoinClient = new MockBitcoinClient() // Initialize the SDK. const sdk = await TBTC.initializeCustom(tbtcContracts, bitcoinClient) ``` # Deposit and mint The main feature of the tBTC bridge is depositing BTC and using it to mint the ERC-20 TBTC token. This guide explains how to perform this process using the SDK. ### Initialize the SDK First, initialize the SDK, as described in the [Initialize SDK](/app-development/tbtc-sdk/guides/initialize-sdk) guide. ### Initiate the deposit Once the SDK is initialized, you can initiate the deposit and get their Bitcoin address in the following way: ```typescript import { TBTC } from "@keep-network/tbtc-v2.ts" // Initialized SDK. const sdk: TBTC // Set the P2WPKH/P2PKH Bitcoin recovery address. It can be used to recover // deposited BTC in case something exceptional happens. const bitcoinRecoveryAddress: string = "..." // Initiate the deposit. const deposit = await sdk.deposits.initiateDeposit(bitcoinRecoveryAddress) // Take the Bitcoin deposit address. BTC must be sent here. const bitcoinDepositAddress = await deposit.getBitcoinAddress() ``` ### Make the Bitcoin deposit transaction The next step is doing the actual Bitcoin deposit transaction to the deposit address. There are two possible ways to do so: * **Recommended**: Use an external Bitcoin wallet * **Non-recommended**: Use the experimental SDK [`DepositFunding`](https://github.com/keep-network/tbtc-v2/blob/f78fe3808733a56cdd5c9e4adcaaf84921cadd3b/typescript/src/services/deposits/funding.ts#L27) component. This code is used for testing purposes and **is not safe** for production use! ### Initiate minting Once the Bitcoin deposit transaction is done, minting can be initiated. This can be done using the `initiateMinting` method exposed by the `Deposit` class. This method has two modes: * **Automatic**: Automatically detect the latest funding UTXO and use it to initiate minting. This mode is the default one that should be used when a single Bitcoin deposit transaction has been made. * **Manual**: Take a funding UTXO as a parameter and use it to initiate minting. This mode can be useful when multiple Bitcoin deposit transactions target the same deposit address. Here is an example of both: {% tabs %} {% tab title="Automatic" %} ```typescript // Initiate minting using latest funding UTXO. Returns hash of the // initiate minting transaction. Can throw an error if there are no // Bitcoin funding transactions targeting this deposit address. // In that case, consider retrying after a delay. const txHash = await deposit.initiateMinting() ``` {% endtab %} {% tab title="Manual" %} ```typescript // Detect funding UTXOs manually. There can be more than one. await fundingUTXOs = await deposit.detectFunding() // Initiate minting using one of the funding UTXOs. Returns hash of the // initiate minting transaction. const txHash = await deposit.initiateMinting(fundingUTXOs[0]) ``` {% endtab %} {% endtabs %} # Unmint and redeem Another core feature of the tBTC bridge is unminting (burning) TBTC tokens and redeeming BTC in return. This guide explains how to perform this process using the SDK. ### Initialize the SDK First, initialize the SDK, as described in the [Initialize SDK](/app-development/tbtc-sdk/guides/initialize-sdk) guide. ### Request redemption Once the SDK is initialized, you can unmint and request for redemption in the following way: ```typescript import { TBTC } from "@keep-network/tbtc-v2.ts" import { BigNumber } from "ethers" // Initialized SDK. const sdk: TBTC // Set the P2WPKH/P2PKH or P2WSH/P2SH Bitcoin redeemer address. This is the // address where redeemed BTC will land. const bitcoinRedeemerAddress: string = "..." // Set the desired redemption amount using 1e18 precision. No need to do an // explicit approval on the TBTC token upfront. const amount = BigNumber.from(5 * 1e18) // Request redemption. This action will burn TBTC tokens and register a // redemption request in the bridge. Returns the hash of the request redemption // transaction and the target wallet public key that will handle the redemption. const { targetChainTxHash, walletPublicKey } = await sdk.redemptions.requestRedemption(bitcoinRedeemerAddress, amount) ``` # tBTC Contracts API # Bridge API You can learn about APIs of contracts related to the Bridge under the following links: [Bank](/app-development/tbtc-contracts-api/tbtc-v2-api/bank) [BitcoinTx](/app-development/tbtc-contracts-api/tbtc-v2-api/bitcointx) [Bridge](/app-development/tbtc-contracts-api/tbtc-v2-api/bridge) [BridgeGovernance](/app-development/tbtc-contracts-api/tbtc-v2-api/bridgegovernance) [BridgeGovernanceParameters](/app-development/tbtc-contracts-api/tbtc-v2-api/bridgegovernanceparameters) [BridgeState](/app-development/tbtc-contracts-api/tbtc-v2-api/bridgestate) [Deposit](/app-development/tbtc-contracts-api/tbtc-v2-api/deposit) [DepositSweep](/app-development/tbtc-contracts-api/tbtc-v2-api/depositsweep) [DonationVault](/app-development/tbtc-contracts-api/tbtc-v2-api/donationvault) [EcdsaLib](/app-development/tbtc-contracts-api/tbtc-v2-api/ecdsalib) [Fraud](/app-development/tbtc-contracts-api/tbtc-v2-api/fraud) [GovernanceUtils](/app-development/tbtc-contracts-api/tbtc-v2-api/governanceutils) [Heartbeat](/app-development/tbtc-contracts-api/tbtc-v2-api/heartbeat) [IReceiveBalanceApproval](/app-development/tbtc-contracts-api/tbtc-v2-api/ireceivebalanceapproval) [IRelay](/app-development/tbtc-contracts-api/tbtc-v2-api/irelay) [IVault](/app-development/tbtc-contracts-api/tbtc-v2-api/ivault) [L2tBTC](/app-development/tbtc-contracts-api/tbtc-v2-api/l2tbtc) [L2WormholeGateway](/app-development/tbtc-contracts-api/tbtc-v2-api/l2wormholegateway) [LightRelay](/app-development/tbtc-contracts-api/tbtc-v2-api/lightrelay) [LightRelayMaintainerProxy](/app-development/tbtc-contracts-api/tbtc-v2-api/lightrelaymaintainerproxy) [MaintainerProxy](/app-development/tbtc-contracts-api/tbtc-v2-api/maintainerproxy) [MovingFunds](/app-development/tbtc-contracts-api/tbtc-v2-api/movingfunds) [Redemption](/app-development/tbtc-contracts-api/tbtc-v2-api/redemption) [tBTC](/app-development/tbtc-contracts-api/tbtc-v2-api/tbtc) [tBTCOptimisticMinting](/app-development/tbtc-contracts-api/tbtc-v2-api/tbtcoptimisticminting) [tBTCVault](/app-development/tbtc-contracts-api/tbtc-v2-api/tbtcvault) [VendingMachine](/app-development/tbtc-contracts-api/tbtc-v2-api/vendingmachine) [VendingMachineV2](/app-development/tbtc-contracts-api/tbtc-v2-api/vendingmachinev2) [VendingMachineV3](/app-development/tbtc-contracts-api/tbtc-v2-api/vendingmachinev3) [WalletCoordinator](/app-development/tbtc-contracts-api/tbtc-v2-api/walletcoordinator) [Wallets](/app-development/tbtc-contracts-api/tbtc-v2-api/wallets) # Bank ## Bank Bank is a central component tracking Bitcoin balances. Balances can be transferred between balance owners, and balance owners can approve their balances to be spent by others. Balances in the Bank are updated for depositors who deposited their Bitcoin into the Bridge and only the Bridge can increase balances. Bank is a governable contract and the Governance can upgrade the Bridge address. ### bridge ```solidity address bridge ``` ### balanceOf ```solidity mapping(address => uint256) balanceOf ``` The balance of the given account in the Bank. Zero by default. ### allowance ```solidity mapping(address => mapping(address => uint256)) allowance ``` The remaining amount of balance a spender will be allowed to transfer on behalf of an owner using `transferBalanceFrom`. Zero by default. ### nonces ```solidity mapping(address => uint256) nonces ``` Returns the current nonce for an EIP2612 permission for the provided balance owner to protect against replay attacks. Used to construct an EIP2612 signature provided to the `permit` function. ### cachedChainId ```solidity uint256 cachedChainId ``` ### cachedDomainSeparator ```solidity bytes32 cachedDomainSeparator ``` ### PERMIT\_TYPEHASH ```solidity bytes32 PERMIT_TYPEHASH ``` Returns an EIP2612 Permit message hash. Used to construct an EIP2612 signature provided to the `permit` function. ### BalanceTransferred ```solidity event BalanceTransferred(address from, address to, uint256 amount) ``` ### BalanceApproved ```solidity event BalanceApproved(address owner, address spender, uint256 amount) ``` ### BalanceIncreased ```solidity event BalanceIncreased(address owner, uint256 amount) ``` ### BalanceDecreased ```solidity event BalanceDecreased(address owner, uint256 amount) ``` ### BridgeUpdated ```solidity event BridgeUpdated(address newBridge) ``` ### onlyBridge ```solidity modifier onlyBridge() ``` ### constructor ```solidity constructor() public ``` ### updateBridge ```solidity function updateBridge(address _bridge) external ``` Allows the Governance to upgrade the Bridge address. The function does not implement any governance delay and does not check the status of the Bridge. The Governance implementation needs to ensure all requirements for the upgrade are satisfied before executing this function. Requirements: * The new Bridge address must not be zero. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------------- | | \_bridge | address | The new Bridge address. | ### transferBalance ```solidity function transferBalance(address recipient, uint256 amount) external ``` Moves the given `amount` of balance from the caller to `recipient`. Requirements: * `recipient` cannot be the zero address, * the caller must have a balance of at least `amount`. #### Parameters | Name | Type | Description | | --------- | ------- | -------------------------------------- | | recipient | address | The recipient of the balance. | | amount | uint256 | The amount of the balance transferred. | ### approveBalance ```solidity function approveBalance(address spender, uint256 amount) external ``` Sets `amount` as the allowance of `spender` over the caller's balance. Does not allow updating an existing allowance to a value that is non-zero to avoid someone using both the old and the new allowance by unfortunate transaction ordering. To update an allowance to a non-zero value please set it to zero first or use `increaseBalanceAllowance` or `decreaseBalanceAllowance` for an atomic update. If the `amount` is set to `type(uint256).max`, `transferBalanceFrom` will not reduce an allowance. #### Parameters | Name | Type | Description | | ------- | ------- | ------------------------------------------------------ | | spender | address | The address that will be allowed to spend the balance. | | amount | uint256 | The amount the spender is allowed to spend. | ### approveBalanceAndCall ```solidity function approveBalanceAndCall(address spender, uint256 amount, bytes extraData) external ``` Sets the `amount` as an allowance of a smart contract `spender` over the caller's balance and calls the `spender` via `receiveBalanceApproval`. If the `amount` is set to `type(uint256).max`, the potential `transferBalanceFrom` executed in `receiveBalanceApproval` of `spender` will not reduce an allowance. Beware that changing an allowance with this function brings the risk that `spender` may use both the old and the new allowance by unfortunate transaction ordering. Please use `increaseBalanceAllowance` and `decreaseBalanceAllowance` to eliminate the risk. #### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------------------------------------------------------ | | spender | address | The smart contract that will be allowed to spend the balance. | | amount | uint256 | The amount the spender contract is allowed to spend. | | extraData | bytes | Extra data passed to the `spender` contract via `receiveBalanceApproval` call. | ### increaseBalanceAllowance ```solidity function increaseBalanceAllowance(address spender, uint256 addedValue) external ``` Atomically increases the caller's balance allowance granted to `spender` by the given `addedValue`. #### Parameters | Name | Type | Description | | ---------- | ------- | --------------------------------------------------------- | | spender | address | The spender address for which the allowance is increased. | | addedValue | uint256 | The amount by which the allowance is increased. | ### decreaseBalanceAllowance ```solidity function decreaseBalanceAllowance(address spender, uint256 subtractedValue) external ``` Atomically decreases the caller's balance allowance granted to `spender` by the given `subtractedValue`. Requirements: * `spender` must not be the zero address, * the current allowance for `spender` must not be lower than the `subtractedValue`. #### Parameters | Name | Type | Description | | --------------- | ------- | --------------------------------------------------------- | | spender | address | The spender address for which the allowance is decreased. | | subtractedValue | uint256 | The amount by which the allowance is decreased. | ### transferBalanceFrom ```solidity function transferBalanceFrom(address spender, address recipient, uint256 amount) external ``` Moves `amount` of balance from `spender` to `recipient` using the allowance mechanism. `amount` is then deducted from the caller's allowance unless the allowance was made for `type(uint256).max`. Requirements: * `recipient` cannot be the zero address, * `spender` must have a balance of at least `amount`, * the caller must have an allowance for `spender`'s balance of at least `amount`. #### Parameters | Name | Type | Description | | --------- | ------- | -------------------------------------------------- | | spender | address | The address from which the balance is transferred. | | recipient | address | The address to which the balance is transferred. | | amount | uint256 | The amount of balance that is transferred. | ### permit ```solidity function permit(address owner, address spender, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external ``` An EIP2612 approval made with secp256k1 signature. Users can authorize a transfer of their balance with a signature conforming to the EIP712 standard, rather than an on-chain transaction from their address. Anyone can submit this signature on the user's behalf by calling the `permit` function, paying gas fees, and possibly performing other actions in the same transaction. The deadline argument can be set to `type(uint256).max to create permits that effectively never expire. If the` amount`is set to`type(uint256).max`then`transferBalanceFrom`will not reduce an allowance. Beware that changing an allowance with this function brings the risk that someone may use both the old and the new allowance by unfortunate transaction ordering. Please use`increaseBalanceAllowance`and`decreaseBalanceAllowance\` to eliminate the risk. #### Parameters | Name | Type | Description | | -------- | ------- | ------------------------------------------------------ | | owner | address | The balance owner who signed the permission. | | spender | address | The address that will be allowed to spend the balance. | | amount | uint256 | The amount the spender is allowed to spend. | | deadline | uint256 | The UNIX time until which the permit is valid. | | v | uint8 | V part of the permit signature. | | r | bytes32 | R part of the permit signature. | | s | bytes32 | S part of the permit signature. | ### increaseBalances ```solidity function increaseBalances(address[] recipients, uint256[] amounts) external ``` Increases balances of the provided `recipients` by the provided `amounts`. Can only be called by the Bridge. Requirements: * length of `recipients` and `amounts` must be the same, * none of `recipients` addresses must point to the Bank. #### Parameters | Name | Type | Description | | ---------- | ---------- | ---------------------------------------- | | recipients | address\[] | Balance increase recipients. | | amounts | uint256\[] | Amounts by which balances are increased. | ### increaseBalance ```solidity function increaseBalance(address recipient, uint256 amount) external ``` Increases balance of the provided `recipient` by the provided `amount`. Can only be called by the Bridge. Requirements: * `recipient` address must not point to the Bank. #### Parameters | Name | Type | Description | | --------- | ------- | ----------------------------------------- | | recipient | address | Balance increase recipient. | | amount | uint256 | Amount by which the balance is increased. | ### increaseBalanceAndCall ```solidity function increaseBalanceAndCall(address vault, address[] recipients, uint256[] amounts) external ``` Increases the given smart contract `vault`'s balance and notifies the `vault` contract about it. Can be called only by the Bridge. Requirements: * `vault` must implement `IVault` interface, * length of `recipients` and `amounts` must be the same. #### Parameters | Name | Type | Description | | ---------- | ---------- | ---------------------------------------- | | vault | address | Address of `IVault` recipient contract. | | recipients | address\[] | Balance increase recipients. | | amounts | uint256\[] | Amounts by which balances are increased. | ### decreaseBalance ```solidity function decreaseBalance(uint256 amount) external ``` Decreases caller's balance by the provided `amount`. There is no way to restore the balance so do not call this function unless you really know what you are doing! Requirements: * The caller must have a balance of at least `amount`. #### Parameters | Name | Type | Description | | ------ | ------- | --------------------------------------------- | | amount | uint256 | The amount by which the balance is decreased. | ### DOMAIN\_SEPARATOR ```solidity function DOMAIN_SEPARATOR() public view returns (bytes32) ``` Returns hash of EIP712 Domain struct with `TBTC Bank` as a signing domain and Bank contract as a verifying contract. Used to construct an EIP2612 signature provided to the `permit` function. ### \_increaseBalance ```solidity function _increaseBalance(address recipient, uint256 amount) internal ``` # BitcoinTx ## BitcoinTx Allows to reference Bitcoin raw transaction in Solidity. See Raw Bitcoin transaction data: | Bytes | Name | BTC type | Description | | ------ | -------------- | --------------------- | ------------------------- | | 4 | version | int32\_t (LE) | TX version number | | varies | tx\_in\_count | compactSize uint (LE) | Number of TX inputs | | varies | tx\_in | txIn\[] | TX inputs | | varies | tx\_out\_count | compactSize uint (LE) | Number of TX outputs | | varies | tx\_out | txOut\[] | TX outputs | | 4 | lock\_time | uint32\_t (LE) | Unix time or block number | Non-coinbase transaction input (txIn): | Bytes | Name | BTC type | Description | | ------ | ----------------- | --------------------- | ------------------------------------------- | | 36 | previous\_output | outpoint | The previous outpoint being spent | | varies | script\_bytes | compactSize uint (LE) | The number of bytes in the signature script | | varies | signature\_script | char\[] | The signature script, empty for P2WSH | | 4 | sequence | uint32\_t (LE) | Sequence number | The reference to transaction being spent (outpoint): | Bytes | Name | BTC type | Description | | ----- | ----- | -------------- | ---------------------------------------- | | 32 | hash | char\[32] | Hash of the transaction to spend | | 4 | index | uint32\_t (LE) | Index of the specific output from the TX | Transaction output (txOut): | Bytes | Name | BTC type | Description | | ------ | ----------------- | --------------------- | ------------------------------------ | | 8 | value | int64\_t (LE) | Number of satoshis to spend | | 1+ | pk\_script\_bytes | compactSize uint (LE) | Number of bytes in the pubkey script | | varies | pk\_script | char\[] | Pubkey script | compactSize uint format: | Value | Bytes | Format | | --------------------------------------- | ----- | --------------------------------------------- | | >= 0 && <= 252 | 1 | uint8\_t | | >= 253 && <= 0xffff | 3 | 0xfd followed by the number as uint16\_t (LE) | | >= 0x10000 && <= 0xffffffff | 5 | 0xfe followed by the number as uint32\_t (LE) | | >= 0x100000000 && <= 0xffffffffffffffff | 9 | 0xff followed by the number as uint64\_t (LE) | (\*) compactSize uint is often references as VarInt) Coinbase transaction input (txIn): | Bytes | Name | BTC type | Description | | ------ | ---------------- | --------------------- | ------------------------------------------- | | 32 | hash | char\[32] | A 32-byte 0x0 null (no previous\_outpoint) | | 4 | index | uint32\_t (LE) | 0xffffffff (no previous\_outpoint) | | varies | script\_bytes | compactSize uint (LE) | The number of bytes in the coinbase script | | varies | height | char\[] | The block height of this block (BIP34) (\*) | | varies | coinbase\_script | none | Arbitrary data, max 100 bytes | | 4 | sequence | uint32\_t (LE) | Sequence number | (\*) Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to the stack followed by the block height as a little-endian unsigned integer. This script must be as short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total size four bytes until block 16,777,216 about 300 years from now. ### Info ```solidity struct Info { bytes4 version; bytes inputVector; bytes outputVector; bytes4 locktime; } ``` ### Proof ```solidity struct Proof { bytes merkleProof; uint256 txIndexInBlock; bytes bitcoinHeaders; } ``` ### UTXO ```solidity struct UTXO { bytes32 txHash; uint32 txOutputIndex; uint64 txOutputValue; } ``` ### RSVSignature ```solidity struct RSVSignature { bytes32 r; bytes32 s; uint8 v; } ``` ### validateProof ```solidity function validateProof(struct BridgeState.Storage self, struct BitcoinTx.Info txInfo, struct BitcoinTx.Proof proof) internal view returns (bytes32 txHash) ``` Validates the SPV proof of the Bitcoin transaction. Reverts in case the validation or proof verification fail. #### Parameters | Name | Type | Description | | ------ | -------------------------- | ------------------------- | | self | struct BridgeState.Storage | | | txInfo | struct BitcoinTx.Info | Bitcoin transaction data. | | proof | struct BitcoinTx.Proof | Bitcoin proof data. | #### Return Values | Name | Type | Description | | ------ | ------- | -------------------------------- | | txHash | bytes32 | Proven 32-byte transaction hash. | ### evaluateProofDifficulty ```solidity function evaluateProofDifficulty(struct BridgeState.Storage self, bytes bitcoinHeaders) internal view ``` Evaluates the given Bitcoin proof difficulty against the actual Bitcoin chain difficulty provided by the relay oracle. Reverts in case the evaluation fails. #### Parameters | Name | Type | Description | | -------------- | -------------------------- | ------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | bitcoinHeaders | bytes | Bitcoin headers chain being part of the SPV proof. Used to extract the observed proof difficulty. | ### extractPubKeyHash ```solidity function extractPubKeyHash(struct BridgeState.Storage, bytes output) internal pure returns (bytes20 pubKeyHash) ``` Extracts public key hash from the provided P2PKH or P2WPKH output. Reverts if the validation fails. Requirements: * The output must be of P2PKH or P2WPKH type and lock the funds on a 20-byte public key hash. #### Parameters | Name | Type | Description | | ------ | -------------------------- | ----------------------- | | | struct BridgeState.Storage | | | output | bytes | The transaction output. | #### Return Values | Name | Type | Description | | ---------- | ------- | -------------------------------------------------- | | pubKeyHash | bytes20 | 20-byte public key hash the output locks funds on. | ### makeP2PKHScript ```solidity function makeP2PKHScript(bytes20 pubKeyHash) internal pure returns (bytes26) ``` Build the P2PKH script from the given public key hash. The P2PKH script has the following byte format: <0x1976a914> <20-byte PKH> <0x88ac>. According to this translates to: * 0x19: Byte length of the entire script * 0x76: OP\_DUP * 0xa9: OP\_HASH160 * 0x14: Byte length of the public key hash * 0x88: OP\_EQUALVERIFY * 0xac: OP\_CHECKSIG which matches the P2PKH structure as per: #### Parameters | Name | Type | Description | | ---------- | ------- | ---------------------------- | | pubKeyHash | bytes20 | The 20-byte public key hash. | #### Return Values | Name | Type | Description | | ---- | ------- | ----------------- | | \[0] | bytes26 | The P2PKH script. | ### makeP2WPKHScript ```solidity function makeP2WPKHScript(bytes20 pubKeyHash) internal pure returns (bytes23) ``` Build the P2WPKH script from the given public key hash. The P2WPKH script has the following format: <0x160014> <20-byte PKH>. According to this translates to: * 0x16: Byte length of the entire script * 0x00: OP\_0 * 0x14: Byte length of the public key hash which matches the P2WPKH structure as per: #### Parameters | Name | Type | Description | | ---------- | ------- | ---------------------------- | | pubKeyHash | bytes20 | The 20-byte public key hash. | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------ | | \[0] | bytes23 | The P2WPKH script. | # Bridge ## Bridge Bridge manages BTC deposit and redemption flow and is increasing and decreasing balances in the Bank as a result of BTC deposit and redemption operations performed by depositors and redeemers. Depositors send BTC funds to the most recently created off-chain ECDSA wallet of the bridge using pay-to-script-hash (P2SH) or pay-to-witness-script-hash (P2WSH) containing hashed information about the depositor’s Ethereum address. Then, the depositor reveals their Ethereum address along with their deposit blinding factor, refund public key hash and refund locktime to the Bridge on Ethereum chain. The off-chain ECDSA wallet listens for these sorts of messages and when it gets one, it checks the Bitcoin network to make sure the deposit lines up. If it does, 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 ECDSA wallet informs the Bridge about the sweep increasing appropriate balances in the Bank. Bridge is an upgradeable component of the Bank. The order of functionalities in this contract is: deposit, sweep, redemption, moving funds, wallet lifecycle, frauds, parameters. ### self ```solidity struct BridgeState.Storage self ``` ### DepositRevealed ```solidity event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault) ``` ### DepositsSwept ```solidity event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) ``` ### RedemptionRequested ```solidity event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee) ``` ### RedemptionsCompleted ```solidity event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash) ``` ### RedemptionTimedOut ```solidity event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript) ``` ### WalletMovingFunds ```solidity event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### MovingFundsCommitmentSubmitted ```solidity event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter) ``` ### MovingFundsTimeoutReset ```solidity event MovingFundsTimeoutReset(bytes20 walletPubKeyHash) ``` ### MovingFundsCompleted ```solidity event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash) ``` ### MovingFundsTimedOut ```solidity event MovingFundsTimedOut(bytes20 walletPubKeyHash) ``` ### MovingFundsBelowDustReported ```solidity event MovingFundsBelowDustReported(bytes20 walletPubKeyHash) ``` ### MovedFundsSwept ```solidity event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) ``` ### MovedFundsSweepTimedOut ```solidity event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex) ``` ### NewWalletRequested ```solidity event NewWalletRequested() ``` ### NewWalletRegistered ```solidity event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletClosing ```solidity event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletClosed ```solidity event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletTerminated ```solidity event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### FraudChallengeSubmitted ```solidity event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s) ``` ### FraudChallengeDefeated ```solidity event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash) ``` ### FraudChallengeDefeatTimedOut ```solidity event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash) ``` ### VaultStatusUpdated ```solidity event VaultStatusUpdated(address vault, bool isTrusted) ``` ### SpvMaintainerStatusUpdated ```solidity event SpvMaintainerStatusUpdated(address spvMaintainer, bool isTrusted) ``` ### DepositParametersUpdated ```solidity event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) ``` ### RedemptionParametersUpdated ```solidity event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) ``` ### MovingFundsParametersUpdated ```solidity event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) ``` ### WalletParametersUpdated ```solidity event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) ``` ### FraudParametersUpdated ```solidity event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) ``` ### TreasuryUpdated ```solidity event TreasuryUpdated(address treasury) ``` ### onlySpvMaintainer ```solidity modifier onlySpvMaintainer() ``` ### constructor ```solidity constructor() public ``` ### initialize ```solidity function initialize(address _bank, address _relay, address _treasury, address _ecdsaWalletRegistry, address payable _reimbursementPool, uint96 _txProofDifficultyFactor) external ``` Initializes upgradable contract on deployment. #### Parameters | Name | Type | Description | | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | | \_bank | address | Address of the Bank the Bridge belongs to. | | \_relay | address | Address of the Bitcoin relay providing the current Bitcoin network difficulty. | | \_treasury | address | Address where the deposit and redemption treasury fees will be sent to. | | \_ecdsaWalletRegistry | address | Address of the ECDSA Wallet Registry contract. | | \_reimbursementPool | address payable | Address of the Reimbursement Pool contract. | | \_txProofDifficultyFactor | uint96 | The number of confirmations on the Bitcoin chain required to successfully evaluate an SPV proof. | ### revealDeposit ```solidity function revealDeposit(struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external ``` Used by the depositor to reveal information about their P2(W)SH Bitcoin deposit to the Bridge on Ethereum chain. The off-chain wallet listens for revealed deposit events and may decide to include the revealed deposit in the next executed sweep. Information about the Bitcoin deposit can be revealed before or after the Bitcoin transaction with P2(W)SH deposit is mined on the Bitcoin chain. Worth noting, the gas cost of this function scales with the number of P2(W)SH transaction inputs and outputs. The deposit may be routed to one of the trusted vaults. When a deposit is routed to a vault, vault gets notified when the deposit gets swept and it may execute the appropriate action. Requirements: * This function must be called by the same Ethereum address as the one used in the P2(W)SH BTC deposit transaction as a depositor, * `reveal.walletPubKeyHash` must identify a `Live` wallet, * `reveal.vault` must be 0x0 or point to a trusted vault, * `reveal.fundingOutputIndex` must point to the actual P2(W)SH output of the BTC deposit transaction, * `reveal.blindingFactor` must be the blinding factor used in the P2(W)SH BTC deposit transaction, * `reveal.walletPubKeyHash` must be the wallet pub key hash used in the P2(W)SH BTC deposit transaction, * `reveal.refundPubKeyHash` must be the refund pub key hash used in the P2(W)SH BTC deposit transaction, * `reveal.refundLocktime` must be the refund locktime used in the P2(W)SH BTC deposit transaction, * BTC deposit for the given `fundingTxHash`, `fundingOutputIndex` can be revealed only one time. If any of these requirements is not met, the wallet *must* refuse to sweep the deposit and the depositor has to wait until the deposit script unlocks to receive their BTC back. #### Parameters | Name | Type | Description | | --------- | -------------------------------- | ------------------------------------------------------- | | fundingTx | struct BitcoinTx.Info | Bitcoin funding transaction data, see `BitcoinTx.Info`. | | reveal | struct Deposit.DepositRevealInfo | Deposit reveal data, see \`RevealInfo struct. | ### submitDepositSweepProof ```solidity function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external ``` Used by the wallet to prove the BTC deposit sweep transaction and to update Bank balances accordingly. Sweep is only accepted if it satisfies SPV proof. The function is performing Bank balance updates by first computing the Bitcoin fee for the sweep transaction. The fee is divided evenly between all swept deposits. Each depositor receives a balance in the bank equal to the amount inferred during the reveal transaction, minus their fee share. It is possible to prove the given sweep only one time. Requirements: * `sweepTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `sweepTx` should represent a Bitcoin transaction with 1..n inputs. If the wallet has no main UTXO, all n inputs should correspond to P2(W)SH revealed deposits UTXOs. If the wallet has an existing main UTXO, one of the n inputs must point to that main UTXO and remaining n-1 inputs should correspond to P2(W)SH revealed deposits UTXOs. That transaction must have only one P2(W)PKH output locking funds on the 20-byte wallet public key hash, * All revealed deposits that are swept by `sweepTx` must have their `vault` parameters set to the same address as the address passed in the `vault` function parameter, * `sweepProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If there is no main UTXO, this parameter is ignored. #### Parameters | Name | Type | Description | | ---------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sweepTx | struct BitcoinTx.Info | Bitcoin sweep transaction data. | | sweepProof | struct BitcoinTx.Proof | Bitcoin sweep proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | | vault | address | Optional address of the vault where all swept deposits should be routed to. All deposits swept as part of the transaction must have their `vault` parameters set to the same address. If this parameter is set to an address of a trusted vault, swept deposits are routed to that vault. If this parameter is set to the zero address or to an address of a non-trusted vault, swept deposits are not routed to a vault but depositors' balances are increased in the Bank individually. | ### requestRedemption ```solidity function requestRedemption(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, bytes redeemerOutputScript, uint64 amount) external ``` Requests redemption of the given amount from the specified wallet to the redeemer Bitcoin output script. Handles the simplest case in which the redeemer's balance is decreased in the Bank. Requirements: * Wallet behind `walletPubKeyHash` must be live, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain, * `redeemerOutputScript` must be a proper Bitcoin script, * `redeemerOutputScript` cannot have wallet PKH as payload, * `amount` must be above or equal the `redemptionDustThreshold`, * Given `walletPubKeyHash` and `redeemerOutputScript` pair can be used for only one pending request at the same time, * Wallet must have enough Bitcoin balance to process the request, * Redeemer must make an allowance in the Bank that the Bridge contract can spend the given `amount`. #### Parameters | Name | Type | Description | | -------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | | amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | ### receiveBalanceApproval ```solidity function receiveBalanceApproval(address balanceOwner, uint256 amount, bytes redemptionData) external ``` Requests redemption of the given amount from the specified wallet to the redeemer Bitcoin output script. Used by `Bank.approveBalanceAndCall`. Can handle more complex cases where balance owner may be someone else than the redeemer. For example, vault redeeming its balance for some depositor. Requirements: * The caller must be the Bank, * Wallet behind `walletPubKeyHash` must be live, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain, * `redeemerOutputScript` must be a proper Bitcoin script, * `redeemerOutputScript` cannot have wallet PKH as payload, * `amount` must be above or equal the `redemptionDustThreshold`, * Given `walletPubKeyHash` and `redeemerOutputScript` pair can be used for only one pending request at the same time, * Wallet must have enough Bitcoin balance to process the request. Note on upgradeability: Bridge is an upgradeable contract deployed behind a TransparentUpgradeableProxy. Accepting redemption data as bytes provides great flexibility. The Bridge is just like any other contract with a balance approved in the Bank and can be upgraded to another version without being bound to a particular interface forever. This flexibility comes with the cost - developers integrating their vaults and dApps with `Bridge` using `approveBalanceAndCall` need to pay extra attention to `redemptionData` and adjust the code in case the expected structure of `redemptionData` changes. #### Parameters | Name | Type | Description | | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | | amount | uint256 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | | redemptionData | bytes | ABI-encoded redemption data: \[ address redeemer, bytes20 walletPubKeyHash, bytes32 mainUtxoTxHash, uint32 mainUtxoTxOutputIndex, uint64 mainUtxoTxOutputValue, bytes redeemerOutputScript ] - redeemer: The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to, - walletPubKeyHash: The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key), - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as currently known on the Ethereum chain, - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output index, as currently known on Ethereum chain, - mainUtxoTxOutputValue: Data of the wallet's main UTXO output value, as currently known on Ethereum chain, - redeemerOutputScript The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | ### submitRedemptionProof ```solidity function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external ``` Used by the wallet to prove the BTC redemption transaction and to make the necessary bookkeeping. Redemption is only accepted if it satisfies SPV proof. The function is performing Bank balance updates by burning the total redeemed Bitcoin amount from Bridge balance and transferring the treasury fee sum to the treasury address. It is possible to prove the given redemption only one time. Requirements: * `redemptionTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `redemptionTx` should represent a Bitcoin transaction with exactly 1 input that refers to the wallet's main UTXO. That transaction should have 1..n outputs handling existing pending redemption requests or pointing to reported timed out requests. There can be also 1 optional output representing the change and pointing back to the 20-byte wallet public key hash. The change should be always present if the redeemed value sum is lower than the total wallet's BTC balance, * `redemptionProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. Additionally, the recent main UTXO on Ethereum must be set, * `walletPubKeyHash` must be connected with the main UTXO used as transaction single input. Other remarks: * Putting the change output as the first transaction output can save some gas because the output processing loop begins each iteration by checking whether the given output is the change thus uses some gas for making the comparison. Once the change is identified, that check is omitted in further iterations. #### Parameters | Name | Type | Description | | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | redemptionTx | struct BitcoinTx.Info | Bitcoin redemption transaction data. | | redemptionProof | struct BitcoinTx.Proof | Bitcoin redemption proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | ### notifyRedemptionTimeout ```solidity function notifyRedemptionTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) external ``` Notifies that there is a pending redemption request associated with the given wallet, that has timed out. The redemption request is identified by the key built as `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. The results of calling this function: * The pending redemptions value for the wallet will be decreased by the requested amount (minus treasury fee), * The tokens taken from the redeemer on redemption request will be returned to the redeemer, * The request will be moved from pending redemptions to timed-out redemptions, * If the state of the wallet is `Live` or `MovingFunds`, the wallet operators will be slashed and the notifier will be rewarded, * If the state of wallet is `Live`, the wallet will be closed or marked as `MovingFunds` (depending on the presence or absence of the wallet's main UTXO) and the wallet will no longer be marked as the active wallet (if it was marked as such). Requirements: * The wallet must be in the Live or MovingFunds or Terminated state, * The redemption request identified by `walletPubKeyHash` and `redeemerOutputScript` must exist, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract, * The amount of time defined by `redemptionTimeout` must have passed since the redemption was requested (the request must be timed-out). #### Parameters | Name | Type | Description | | -------------------- | --------- | ---------------------------------------------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | | redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH). | ### submitMovingFundsCommitment ```solidity function submitMovingFundsCommitment(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) external ``` Submits the moving funds target wallets commitment. Once all requirements are met, that function registers the target wallets commitment and opens the way for moving funds proof submission. The caller is reimbursed for the transaction costs. Requirements: * The source wallet must be in the MovingFunds state, * The source wallet must not have pending redemption requests, * The source wallet must not have pending moved funds sweep requests, * The source wallet must not have submitted its commitment already, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given source wallet in the ECDSA registry. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events, * The `walletMemberIndex` must be in range \[1, walletMembersIDs.length], * The caller must be the member of the source wallet signing group at the position indicated by `walletMemberIndex` parameter, * The `walletMainUtxo` components must point to the recent main UTXO of the source wallet, as currently known on the Ethereum chain, * Source wallet BTC balance must be greater than zero, * At least one Live wallet must exist in the system, * Submitted target wallets count must match the expected count `N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))` where `N > 0`, * Each target wallet must be not equal to the source wallet, * Each target wallet must follow the expected order i.e. all target wallets 20-byte public key hashes represented as numbers must form a strictly increasing sequence without duplicates, * Each target wallet must be in Live state. #### Parameters | Name | Type | Description | | ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ | | walletPubKeyHash | bytes20 | 20-byte public key hash of the source wallet. | | walletMainUtxo | struct BitcoinTx.UTXO | Data of the source wallet's main UTXO, as currently known on the Ethereum chain. | | walletMembersIDs | uint32\[] | Identifiers of the source wallet signing group members. | | walletMemberIndex | uint256 | Position of the caller in the source wallet signing group members list. | | targetWallets | bytes20\[] | List of 20-byte public key hashes of the target wallets that the source wallet commits to move the funds to. | ### resetMovingFundsTimeout ```solidity function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external ``` Resets the moving funds timeout for the given wallet if the target wallet commitment cannot be submitted due to a lack of live wallets in the system. Requirements: * The wallet must be in the MovingFunds state, * The target wallets commitment must not be already submitted for the given moving funds wallet, * Live wallets count must be zero, * The moving funds timeout reset delay must be elapsed. #### Parameters | Name | Type | Description | | ---------------- | ------- | --------------------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the moving funds wallet. | ### submitMovingFundsProof ```solidity function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external ``` Used by the wallet to prove the BTC moving funds transaction and to make the necessary state changes. Moving funds is only accepted if it satisfies SPV proof. The function validates the moving funds transaction structure by checking if it actually spends the main UTXO of the declared wallet and locks the value on the pre-committed target wallets using a reasonable transaction fee. If all preconditions are met, this functions closes the source wallet. It is possible to prove the given moving funds transaction only one time. Requirements: * `movingFundsTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `movingFundsTx` should represent a Bitcoin transaction with exactly 1 input that refers to the wallet's main UTXO. That transaction should have 1..n outputs corresponding to the pre-committed target wallets. Outputs must be ordered in the same way as their corresponding target wallets are ordered within the target wallets commitment, * `movingFundsProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. Additionally, the recent main UTXO on Ethereum must be set, * `walletPubKeyHash` must be connected with the main UTXO used as transaction single input, * The wallet that `walletPubKeyHash` points to must be in the MovingFunds state, * The target wallets commitment must be submitted by the wallet that `walletPubKeyHash` points to, * The total Bitcoin transaction fee must be lesser or equal to `movingFundsTxMaxTotalFee` governable parameter. #### Parameters | Name | Type | Description | | ---------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | movingFundsTx | struct BitcoinTx.Info | Bitcoin moving funds transaction data. | | movingFundsProof | struct BitcoinTx.Proof | Bitcoin moving funds proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the moving funds transaction. | ### notifyMovingFundsTimeout ```solidity function notifyMovingFundsTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs) external ``` Notifies about a timed out moving funds process. Terminates the wallet and slashes signing group members as a result. Requirements: * The wallet must be in the MovingFunds state, * The moving funds timeout must be actually exceeded, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract. #### Parameters | Name | Type | Description | | ---------------- | --------- | ------------------------------------------------ | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### notifyMovingFundsBelowDust ```solidity function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external ``` Notifies about a moving funds wallet whose BTC balance is below the moving funds dust threshold. Ends the moving funds process and begins wallet closing immediately. Requirements: * The wallet must be in the MovingFunds state, * The `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If the wallet has no main UTXO, this parameter can be empty as it is ignored, * The wallet BTC balance must be below the moving funds threshold. #### Parameters | Name | Type | Description | | ---------------- | --------------------- | ------------------------------------------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | ### submitMovedFundsSweepProof ```solidity function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external ``` Used by the wallet to prove the BTC moved funds sweep transaction and to make the necessary state changes. Moved funds sweep is only accepted if it satisfies SPV proof. The function validates the sweep transaction structure by checking if it actually spends the moved funds UTXO and the sweeping wallet's main UTXO (optionally), and if it locks the value on the sweeping wallet's 20-byte public key hash using a reasonable transaction fee. If all preconditions are met, this function updates the sweeping wallet main UTXO, thus their BTC balance. It is possible to prove the given sweep transaction only one time. Requirements: * `sweepTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `sweepTx` should represent a Bitcoin transaction with the first input pointing to a moved funds sweep request targeted to the wallet, and optionally, the second input pointing to the wallet's main UTXO, if the sweeping wallet has a main UTXO set. There should be only one output locking funds on the sweeping wallet 20-byte public key hash, * `sweepProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the sweeping wallet, as currently known on the Ethereum chain. If there is no main UTXO, this parameter is ignored, * The sweeping wallet must be in the Live or MovingFunds state, * The total Bitcoin transaction fee must be lesser or equal to `movedFundsSweepTxMaxTotalFee` governable parameter. #### Parameters | Name | Type | Description | | ---------- | ---------------------- | ---------------------------------------------------------------------------------- | | sweepTx | struct BitcoinTx.Info | Bitcoin sweep funds transaction data. | | sweepProof | struct BitcoinTx.Proof | Bitcoin sweep funds proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain. | ### notifyMovedFundsSweepTimeout ```solidity function notifyMovedFundsSweepTimeout(bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) external ``` Notifies about a timed out moved funds sweep process. If the wallet is not terminated yet, that function terminates the wallet and slashes signing group members as a result. Marks the given sweep request as TimedOut. Requirements: * The moved funds sweep request must be in the Pending state, * The moved funds sweep timeout must be actually exceeded, * The wallet must be either in the Live or MovingFunds or Terminated state, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract. #### Parameters | Name | Type | Description | | ------------------------ | --------- | ----------------------------------------------------------------------------------------- | | movingFundsTxHash | bytes32 | 32-byte hash of the moving funds transaction that caused the sweep request to be created. | | movingFundsTxOutputIndex | uint32 | Index of the moving funds transaction output that is subject of the sweep request. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### requestNewWallet ```solidity function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) external ``` Requests creation of a new wallet. This function just forms a request and the creation process is performed asynchronously. Once a wallet is created, the ECDSA Wallet Registry will notify this contract by calling the `__ecdsaWalletCreatedCallback` function. Requirements: * `activeWalletMainUtxo` components must point to the recent main UTXO of the given active wallet, as currently known on the Ethereum chain. If there is no active wallet at the moment, or the active wallet has no main UTXO, this parameter can be empty as it is ignored, * Wallet creation must not be in progress, * If the active wallet is set, one of the following conditions must be true: * The active wallet BTC balance is above the minimum threshold and the active wallet is old enough, i.e. the creation period was elapsed since its creation time, * The active wallet BTC balance is above the maximum threshold. #### Parameters | Name | Type | Description | | -------------------- | --------------------- | -------------------------------------------------------------------------------- | | activeWalletMainUtxo | struct BitcoinTx.UTXO | Data of the active wallet's main UTXO, as currently known on the Ethereum chain. | ### \_\_ecdsaWalletCreatedCallback ```solidity function __ecdsaWalletCreatedCallback(bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) external ``` A callback function that is called by the ECDSA Wallet Registry once a new ECDSA wallet is created. Requirements: * The only caller authorized to call this function is `registry`, * Given wallet data must not belong to an already registered wallet. #### Parameters | Name | Type | Description | | ------------- | ------- | ----------------------------------- | | ecdsaWalletID | bytes32 | Wallet's unique identifier. | | publicKeyX | bytes32 | Wallet's public key's X coordinate. | | publicKeyY | bytes32 | Wallet's public key's Y coordinate. | ### \_\_ecdsaWalletHeartbeatFailedCallback ```solidity function __ecdsaWalletHeartbeatFailedCallback(bytes32, bytes32 publicKeyX, bytes32 publicKeyY) external ``` A callback function that is called by the ECDSA Wallet Registry once a wallet heartbeat failure is detected. Requirements: * The only caller authorized to call this function is `registry`, * Wallet must be in Live state. #### Parameters | Name | Type | Description | | ---------- | ------- | ----------------------------------- | | | bytes32 | | | publicKeyX | bytes32 | Wallet's public key's X coordinate. | | publicKeyY | bytes32 | Wallet's public key's Y coordinate. | ### notifyWalletCloseable ```solidity function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external ``` Notifies that the wallet is either old enough or has too few satoshi left and qualifies to be closed. Requirements: * Wallet must not be set as the current active wallet, * Wallet must exceed the wallet maximum age OR the wallet BTC balance must be lesser than the minimum threshold. If the latter case is true, the `walletMainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If the wallet has no main UTXO, this parameter can be empty as it is ignored since the wallet balance is assumed to be zero, * Wallet must be in Live state. #### Parameters | Name | Type | Description | | ---------------- | --------------------- | ------------------------------------------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | ### notifyWalletClosingPeriodElapsed ```solidity function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) external ``` Notifies about the end of the closing period for the given wallet. Closes the wallet ultimately and notifies the ECDSA registry about this fact. Requirements: * The wallet must be in the Closing state, * The wallet closing period must have elapsed. #### Parameters | Name | Type | Description | | ---------------- | ------- | -------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### submitFraudChallenge ```solidity function submitFraudChallenge(bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external payable ``` Submits a fraud challenge indicating that a UTXO being under wallet control was unlocked by the wallet but was not used according to the protocol rules. That means the wallet signed a transaction input pointing to that UTXO and there is a unique sighash and signature pair associated with that input. This function uses those parameters to create a fraud accusation that proves a given transaction input unlocking the given UTXO was actually signed by the wallet. This function cannot determine whether the transaction was actually broadcast and the input was consumed in a fraudulent way so it just opens a challenge period during which the wallet can defeat the challenge by submitting proof of a transaction that consumes the given input according to protocol rules. To prevent spurious allegations, the caller must deposit ETH that is returned back upon justified fraud challenge or confiscated otherwise. Requirements: * Wallet behind `walletPublicKey` must be in Live or MovingFunds or Closing state, * The challenger must send appropriate amount of ETH used as fraud challenge deposit, * The signature (represented by r, s and v) must be generated by the wallet behind `walletPubKey` during signing of `sighash` which was calculated from `preimageSha256`, * Wallet can be challenged for the given signature only once. #### Parameters | Name | Type | Description | | --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | | signature | struct BitcoinTx.RSVSignature | Bitcoin signature in the R/S/V format. | ### defeatFraudChallenge ```solidity function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) external ``` Allows to defeat a pending fraud challenge against a wallet if the transaction that spends the UTXO follows the protocol rules. In order to defeat the challenge the same `walletPublicKey` and signature (represented by `r`, `s` and `v`) must be provided as were used to calculate the sighash during input signing. The fraud challenge defeat attempt will only succeed if the inputs in the preimage are considered honestly spent by the wallet. Therefore the transaction spending the UTXO must be proven in the Bridge before a challenge defeat is called. If successfully defeated, the fraud challenge is marked as resolved and the amount of ether deposited by the challenger is sent to the treasury. Requirements: * `walletPublicKey` and `sighash` calculated as `hash256(preimage)` must identify an open fraud challenge, * the preimage must be a valid preimage of a transaction generated according to the protocol rules and already proved in the Bridge, * before a defeat attempt is made the transaction that spends the given UTXO must be proven in the Bridge. #### Parameters | Name | Type | Description | | --------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | | witness | bool | Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input. | ### defeatFraudChallengeWithHeartbeat ```solidity function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) external ``` Allows to defeat a pending fraud challenge against a wallet by proving the sighash and signature were produced for an off-chain wallet heartbeat message following a strict format. In order to defeat the challenge the same `walletPublicKey` and signature (represented by `r`, `s` and `v`) must be provided as were used to calculate the sighash during heartbeat message signing. The fraud challenge defeat attempt will only succeed if the signed message follows a strict format required for heartbeat messages. If successfully defeated, the fraud challenge is marked as resolved and the amount of ether deposited by the challenger is sent to the treasury. Requirements: * `walletPublicKey` and `sighash` calculated as `hash256(heartbeatMessage)` must identify an open fraud challenge, * `heartbeatMessage` must follow a strict format of heartbeat messages. #### Parameters | Name | Type | Description | | ---------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | heartbeatMessage | bytes | Off-chain heartbeat message meeting the heartbeat message format requirements which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. | ### notifyFraudChallengeDefeatTimeout ```solidity function notifyFraudChallengeDefeatTimeout(bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) external ``` Notifies about defeat timeout for the given fraud challenge. Can be called only if there was a fraud challenge identified by the provided `walletPublicKey` and `sighash` and it was not defeated on time. The amount of time that needs to pass after a fraud challenge is reported is indicated by the `challengeDefeatTimeout`. After a successful fraud challenge defeat timeout notification the fraud challenge is marked as resolved, the stake of each operator is slashed, the ether deposited is returned to the challenger and the challenger is rewarded. Requirements: * The wallet must be in the Live or MovingFunds or Closing or Terminated state, * The `walletPublicKey` and `sighash` calculated from `preimageSha256` must identify an open fraud challenge, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract, * The amount of time indicated by `challengeDefeatTimeout` must pass after the challenge was reported. #### Parameters | Name | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | | preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | ### setVaultStatus ```solidity function setVaultStatus(address vault, bool isTrusted) external ``` Allows the Governance to mark the given vault address as trusted or no longer trusted. Vaults are not trusted by default. Trusted vault must meet the following criteria: * `IVault.receiveBalanceIncrease` must have a known, low gas cost, * `IVault.receiveBalanceIncrease` must never revert. Without restricting reveal only to trusted vaults, malicious vaults not meeting the criteria would be able to nuke sweep proof transactions executed by ECDSA wallet with deposits routed to them. Can only be called by the Governance. #### Parameters | Name | Type | Description | | --------- | ------- | ---------------------------------------------------- | | vault | address | The address of the vault. | | isTrusted | bool | flag indicating whether the vault is trusted or not. | ### setSpvMaintainerStatus ```solidity function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) external ``` Allows the Governance to mark the given address as trusted or no longer trusted SPV maintainer. Addresses are not trusted as SPV maintainers by default. The SPV proof does not check whether the transaction is a part of the Bitcoin mainnet, it only checks whether the transaction has been mined performing the required amount of work as on Bitcoin mainnet. The possibility of submitting SPV proofs is limited to trusted SPV maintainers. The system expects transaction confirmations with the required work accumulated, so trusted SPV maintainers can not prove the transaction without providing the required Bitcoin proof of work. Trusted maintainers address the issue of an economic game between tBTC and Bitcoin mainnet where large Bitcoin mining pools can decide to use their hash power to mine fake Bitcoin blocks to prove them in tBTC instead of receiving Bitcoin miner rewards. Can only be called by the Governance. #### Parameters | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------ | | spvMaintainer | address | The address of the SPV maintainer. | | isTrusted | bool | flag indicating whether the address is trusted or not. | ### updateDepositParameters ```solidity function updateDepositParameters(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) external ``` of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the depositor. Requirements: * Deposit dust threshold must be greater than zero, * Deposit dust threshold must be greater than deposit TX max fee, * Deposit transaction max fee must be greater than zero. #### Parameters | Name | Type | Description | | ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | depositDustThreshold | uint64 | | | depositTreasuryFeeDivisor | uint64 | New value of the treasury fee divisor. It is the divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | | depositTxMaxFee | uint64 | New value of the deposit tx max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | | depositRevealAheadPeriod | uint32 | New value of the deposit reveal ahead period parameter in seconds. It defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. | ### updateRedemptionParameters ```solidity function updateRedemptionParameters(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) external ``` Updates parameters of redemptions. Requirements: * Redemption dust threshold must be greater than moving funds dust threshold, * Redemption dust threshold must be greater than the redemption TX max fee, * Redemption transaction max fee must be greater than zero, * Redemption transaction max total fee must be greater than or equal to the redemption transaction per-request max fee, * Redemption timeout must be greater than zero, * Redemption timeout notifier reward multiplier must be in the range \[0, 100]. #### Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | redemptionDustThreshold | uint64 | New value of the redemption dust threshold in satoshis. It is the minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | | redemptionTreasuryFeeDivisor | uint64 | New value of the redemption treasury fee divisor. It is the divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | | redemptionTxMaxFee | uint64 | New value of the redemption transaction max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | | redemptionTxMaxTotalFee | uint64 | New value of the redemption transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a *total* max fee for the entire redemption transaction. | | redemptionTimeout | uint32 | New value of the redemption timeout in seconds. It is the time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked balance is returned to the redeemer in full amount. | | redemptionTimeoutSlashingAmount | uint96 | New value of the redemption timeout slashing amount in T, it is the amount slashed from each wallet member for redemption timeout. | | redemptionTimeoutNotifierRewardMultiplier | uint32 | New value of the redemption timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a redemption timeout receives. The value must be in the range \[0, 100]. | ### updateMovingFundsParameters ```solidity function updateMovingFundsParameters(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) external ``` Updates parameters of moving funds. Requirements: * Moving funds transaction max total fee must be greater than zero, * Moving funds dust threshold must be greater than zero and lower than the redemption dust threshold, * Moving funds timeout reset delay must be greater than zero, * Moving funds timeout must be greater than the moving funds timeout reset delay, * Moving funds timeout notifier reward multiplier must be in the range \[0, 100], * Moved funds sweep transaction max total fee must be greater than zero, * Moved funds sweep timeout must be greater than zero, * Moved funds sweep timeout notifier reward multiplier must be in the range \[0, 100]. #### Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | movingFundsTxMaxTotalFee | uint64 | New value of the moving funds transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a *total* max fee for the entire moving funds transaction. | | movingFundsDustThreshold | uint64 | New value of the moving funds dust threshold. It is the minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | | movingFundsTimeoutResetDelay | uint32 | New value of the moving funds timeout reset delay in seconds. It is the time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. | | movingFundsTimeout | uint32 | New value of the moving funds timeout in seconds. It is the time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. | | movingFundsTimeoutSlashingAmount | uint96 | New value of the moving funds timeout slashing amount in T, it is the amount slashed from each wallet member for moving funds timeout. | | movingFundsTimeoutNotifierRewardMultiplier | uint32 | New value of the moving funds timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moving funds timeout receives. The value must be in the range \[0, 100]. | | movingFundsCommitmentGasOffset | uint16 | New value of the gas offset for moving funds target wallet commitment transaction gas costs reimbursement. | | movedFundsSweepTxMaxTotalFee | uint64 | New value of the moved funds sweep transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a *total* max fee for the entire moved funds sweep transaction. | | movedFundsSweepTimeout | uint32 | New value of the moved funds sweep timeout in seconds. It is the time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. | | movedFundsSweepTimeoutSlashingAmount | uint96 | New value of the moved funds sweep timeout slashing amount in T, it is the amount slashed from each wallet member for moved funds sweep timeout. | | movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New value of the moved funds sweep timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moved funds sweep timeout receives. The value must be in the range \[0, 100]. | ### updateWalletParameters ```solidity function updateWalletParameters(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) external ``` Requirements: * Wallet maximum BTC balance must be greater than the wallet minimum BTC balance, * Wallet maximum BTC transfer must be greater than zero, * Wallet closing period must be greater than zero. ### updateFraudParameters ```solidity function updateFraudParameters(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) external ``` Updates parameters related to frauds. Requirements: * Fraud challenge defeat timeout must be greater than 0, * Fraud notifier reward multiplier must be in the range \[0, 100]. #### Parameters | Name | Type | Description | | ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fraudChallengeDepositAmount | uint96 | New value of the fraud challenge deposit amount in wei, it is the amount of ETH the party challenging the wallet for fraud needs to deposit. | | fraudChallengeDefeatTimeout | uint32 | New value of the challenge defeat timeout in seconds, it is the amount of time the wallet has to defeat a fraud challenge. The value must be greater than zero. | | fraudSlashingAmount | uint96 | New value of the fraud slashing amount in T, it is the amount slashed from each wallet member for committing a fraud. | | fraudNotifierRewardMultiplier | uint32 | New value of the fraud notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a fraud receives. The value must be in the range \[0, 100]. | ### updateTreasury ```solidity function updateTreasury(address treasury) external ``` Updates treasury address. The treasury receives the system fees. The treasury address must not be 0x0. #### Parameters | Name | Type | Description | | -------- | ------- | ---------------------------------- | | treasury | address | New value of the treasury address. | ### deposits ```solidity function deposits(uint256 depositKey) external view returns (struct Deposit.DepositRequest) ``` Collection of all revealed deposits indexed by keccak256(fundingTxHash | fundingOutputIndex). The fundingTxHash is bytes32 (ordered as in Bitcoin internally) and fundingOutputIndex an uint32. This mapping may contain valid and invalid deposits and the wallet is responsible for validating them before attempting to execute a sweep. ### pendingRedemptions ```solidity function pendingRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest) ``` Collection of all pending redemption requests indexed by redemption key built as `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. The walletPubKeyHash is the 20-byte wallet's public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) and `redeemerOutputScript` is a Bitcoin script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC as requested by the redeemer. Requests are added to this mapping by the `requestRedemption` method (duplicates not allowed) and are removed by one of the following methods: * `submitRedemptionProof` in case the request was handled successfully, * `notifyRedemptionTimeout` in case the request was reported to be timed out. ### timedOutRedemptions ```solidity function timedOutRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest) ``` Collection of all timed out redemptions requests indexed by redemption key built as `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. The walletPubKeyHash is the 20-byte wallet's public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) and `redeemerOutputScript` is the Bitcoin script (P2PKH, P2WPKH, P2SH or P2WSH) that is involved in the timed out request. Only one method can add to this mapping: * `notifyRedemptionTimeout` which puts the redemption key to this mapping based on a timed out request stored previously in `pendingRedemptions` mapping. Only one method can remove entries from this mapping: * `submitRedemptionProof` in case the timed out redemption request was a part of the proven transaction. ### spentMainUTXOs ```solidity function spentMainUTXOs(uint256 utxoKey) external view returns (bool) ``` Collection of main UTXOs that are honestly spent indexed by keccak256(fundingTxHash | fundingOutputIndex). The fundingTxHash is bytes32 (ordered as in Bitcoin internally) and fundingOutputIndex an uint32. A main UTXO is considered honestly spent if it was used as an input of a transaction that have been proven in the Bridge. ### wallets ```solidity function wallets(bytes20 walletPubKeyHash) external view returns (struct Wallets.Wallet) ``` Gets details about a registered wallet. #### Parameters | Name | Type | Description | | ---------------- | ------- | --------------------------------------------------------------------------------------------------------- | | walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | #### Return Values | Name | Type | Description | | ---- | --------------------- | --------------- | | \[0] | struct Wallets.Wallet | Wallet details. | ### activeWalletPubKeyHash ```solidity function activeWalletPubKeyHash() external view returns (bytes20) ``` Gets the public key hash of the active wallet. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \[0] | bytes20 | The 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the active wallet. Returns bytes20(0) if there is no active wallet at the moment. | ### liveWalletsCount ```solidity function liveWalletsCount() external view returns (uint32) ``` Gets the live wallets count. #### Return Values | Name | Type | Description | | ---- | ------ | ----------------------------------------------------- | | \[0] | uint32 | The current count of wallets being in the Live state. | ### fraudChallenges ```solidity function fraudChallenges(uint256 challengeKey) external view returns (struct Fraud.FraudChallenge) ``` Returns the fraud challenge identified by the given key built as keccak256(walletPublicKey|sighash). ### movedFundsSweepRequests ```solidity function movedFundsSweepRequests(uint256 requestKey) external view returns (struct MovingFunds.MovedFundsSweepRequest) ``` Collection of all moved funds sweep requests indexed by `keccak256(movingFundsTxHash | movingFundsOutputIndex)`. The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin internally) and `movingFundsOutputIndex` an `uint32`. Each entry is actually an UTXO representing the moved funds and is supposed to be swept with the current main UTXO of the recipient wallet. #### Parameters | Name | Type | Description | | ---------- | ------- | -------------------------------------------------- | | requestKey | uint256 | Request key built as \`keccak256(movingFundsTxHash | #### Return Values | Name | Type | Description | | ---- | ----------------------------------------- | ----------------------------------------- | | \[0] | struct MovingFunds.MovedFundsSweepRequest | Details of the moved funds sweep request. | ### isVaultTrusted ```solidity function isVaultTrusted(address vault) external view returns (bool) ``` Indicates if the vault with the given address is trusted or not. Depositors can route their revealed deposits only to trusted vaults and have trusted vaults notified about new deposits as soon as these deposits get swept. Vaults not trusted by the Bridge can still be used by Bank balance owners on their own responsibility - anyone can approve their Bank balance to any address. ### depositParameters ```solidity function depositParameters() external view returns (uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) ``` Returns the current values of Bridge deposit parameters. #### Return Values | Name | Type | Description | | ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | depositDustThreshold | uint64 | The minimal amount that can be requested to deposit. Value of this parameter must take into account the value of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the depositor. | | depositTreasuryFeeDivisor | uint64 | Divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | | depositTxMaxFee | uint64 | Maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | | depositRevealAheadPeriod | uint32 | Defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. For example, if the deposit become refundable on August 1st, and the ahead period is 7 days, the latest moment for deposit reveal is July 25th. Value in seconds. | ### redemptionParameters ```solidity function redemptionParameters() external view returns (uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) ``` Returns the current values of Bridge redemption parameters. #### Return Values | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | redemptionDustThreshold | uint64 | The minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | | redemptionTreasuryFeeDivisor | uint64 | Divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | | redemptionTxMaxFee | uint64 | Maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | | redemptionTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a *total* max fee for the entire redemption transaction. | | redemptionTimeout | uint32 | Time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked balance is returned to the redeemer in full amount. | | redemptionTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a redemption timeout. | | redemptionTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a redemption timeout receives. The value is in the range \[0, 100]. | ### movingFundsParameters ```solidity function movingFundsParameters() external view returns (uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) ``` Returns the current values of Bridge moving funds between wallets parameters. #### Return Values | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | movingFundsTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a *total* max fee for the entire moving funds transaction. | | movingFundsDustThreshold | uint64 | The minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | | movingFundsTimeoutResetDelay | uint32 | Time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. Value in seconds This value should be lower than the value of the `movingFundsTimeout`. | | movingFundsTimeout | uint32 | Time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. Value in seconds. | | movingFundsTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a moving funds timeout. | | movingFundsTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a moving funds timeout receives. The value is in the range \[0, 100]. | | movingFundsCommitmentGasOffset | uint16 | The gas offset used for the moving funds target wallet commitment transaction cost reimbursement. | | movedFundsSweepTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a *total* max fee for the entire moved funds sweep transaction. | | movedFundsSweepTimeout | uint32 | Time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. Value in seconds. | | movedFundsSweepTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a moved funds sweep timeout. | | movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a moved funds sweep timeout receives. The value is in the range \[0, 100]. | ### walletParameters ```solidity function walletParameters() external view returns (uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) ``` #### Return Values | Name | Type | Description | | --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletCreationPeriod | uint32 | Determines how frequently a new wallet creation can be requested. Value in seconds. | | walletCreationMinBtcBalance | uint64 | The minimum BTC threshold in satoshi that is used to decide about wallet creation. | | walletCreationMaxBtcBalance | uint64 | The maximum BTC threshold in satoshi that is used to decide about wallet creation. | | walletClosureMinBtcBalance | uint64 | The minimum BTC threshold in satoshi that is used to decide about wallet closure. | | walletMaxAge | uint32 | The maximum age of a wallet in seconds, after which the wallet moving funds process can be requested. | | walletMaxBtcTransfer | uint64 | The maximum BTC amount in satoshi than can be transferred to a single target wallet during the moving funds process. | | walletClosingPeriod | uint32 | Determines the length of the wallet closing period, i.e. the period when the wallet remains in the Closing state and can be subject of deposit fraud challenges. Value in seconds. | ### fraudParameters ```solidity function fraudParameters() external view returns (uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) ``` Returns the current values of Bridge fraud parameters. #### Return Values | Name | Type | Description | | ----------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | fraudChallengeDepositAmount | uint96 | The amount of ETH in wei the party challenging the wallet for fraud needs to deposit. | | fraudChallengeDefeatTimeout | uint32 | The amount of time the wallet has to defeat a fraud challenge. | | fraudSlashingAmount | uint96 | The amount slashed from each wallet member for committing a fraud. | | fraudNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a fraud receives. The value is in the range \[0, 100]. | ### contractReferences ```solidity function contractReferences() external view returns (contract Bank bank, contract IRelay relay, contract IWalletRegistry ecdsaWalletRegistry, contract ReimbursementPool reimbursementPool) ``` Returns the addresses of contracts Bridge is interacting with. #### Return Values | Name | Type | Description | | ------------------- | -------------------------- | ------------------------------------------------------------------------------ | | bank | contract Bank | Address of the Bank the Bridge belongs to. | | relay | contract IRelay | Address of the Bitcoin relay providing the current Bitcoin network difficulty. | | ecdsaWalletRegistry | contract IWalletRegistry | Address of the ECDSA Wallet Registry. | | reimbursementPool | contract ReimbursementPool | Address of the Reimbursement Pool. | ### treasury ```solidity function treasury() external view returns (address) ``` Address where the deposit treasury fees will be sent to. Treasury takes part in the operators rewarding process. ### txProofDifficultyFactor ```solidity function txProofDifficultyFactor() external view returns (uint256) ``` The number of confirmations on the Bitcoin chain required to successfully evaluate an SPV proof. # BridgeGovernance ## BridgeGovernance Owns the `Bridge` contract and is responsible for updating its governable parameters in respect to governance delay individual for each parameter. The other responsibility is marking a vault address as trusted or no longer trusted. ### depositData ```solidity struct BridgeGovernanceParameters.DepositData depositData ``` ### redemptionData ```solidity struct BridgeGovernanceParameters.RedemptionData redemptionData ``` ### movingFundsData ```solidity struct BridgeGovernanceParameters.MovingFundsData movingFundsData ``` ### walletData ```solidity struct BridgeGovernanceParameters.WalletData walletData ``` ### fraudData ```solidity struct BridgeGovernanceParameters.FraudData fraudData ``` ### treasuryData ```solidity struct BridgeGovernanceParameters.TreasuryData treasuryData ``` ### bridge ```solidity contract Bridge bridge ``` ### governanceDelays ```solidity uint256[3] governanceDelays ``` ### bridgeGovernanceTransferChangeInitiated ```solidity uint256 bridgeGovernanceTransferChangeInitiated ``` ### newBridgeGovernance ```solidity address newBridgeGovernance ``` ### BridgeGovernanceTransferStarted ```solidity event BridgeGovernanceTransferStarted(address newBridgeGovernance, uint256 timestamp) ``` ### DepositDustThresholdUpdateStarted ```solidity event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp) ``` ### DepositDustThresholdUpdated ```solidity event DepositDustThresholdUpdated(uint64 depositDustThreshold) ``` ### DepositTreasuryFeeDivisorUpdateStarted ```solidity event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp) ``` ### DepositTreasuryFeeDivisorUpdated ```solidity event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor) ``` ### DepositTxMaxFeeUpdateStarted ```solidity event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp) ``` ### DepositTxMaxFeeUpdated ```solidity event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee) ``` ### DepositRevealAheadPeriodUpdateStarted ```solidity event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp) ``` ### DepositRevealAheadPeriodUpdated ```solidity event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod) ``` ### RedemptionDustThresholdUpdateStarted ```solidity event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp) ``` ### RedemptionDustThresholdUpdated ```solidity event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold) ``` ### RedemptionTreasuryFeeDivisorUpdateStarted ```solidity event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp) ``` ### RedemptionTreasuryFeeDivisorUpdated ```solidity event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor) ``` ### RedemptionTxMaxFeeUpdateStarted ```solidity event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp) ``` ### RedemptionTxMaxFeeUpdated ```solidity event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee) ``` ### RedemptionTxMaxTotalFeeUpdateStarted ```solidity event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp) ``` ### RedemptionTxMaxTotalFeeUpdated ```solidity event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee) ``` ### RedemptionTimeoutUpdateStarted ```solidity event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp) ``` ### RedemptionTimeoutUpdated ```solidity event RedemptionTimeoutUpdated(uint32 redemptionTimeout) ``` ### RedemptionTimeoutSlashingAmountUpdateStarted ```solidity event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp) ``` ### RedemptionTimeoutSlashingAmountUpdated ```solidity event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount) ``` ### RedemptionTimeoutNotifierRewardMultiplierUpdateStarted ```solidity event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp) ``` ### RedemptionTimeoutNotifierRewardMultiplierUpdated ```solidity event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier) ``` ### MovingFundsTxMaxTotalFeeUpdateStarted ```solidity event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp) ``` ### MovingFundsTxMaxTotalFeeUpdated ```solidity event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee) ``` ### MovingFundsDustThresholdUpdateStarted ```solidity event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp) ``` ### MovingFundsDustThresholdUpdated ```solidity event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold) ``` ### MovingFundsTimeoutResetDelayUpdateStarted ```solidity event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp) ``` ### MovingFundsTimeoutResetDelayUpdated ```solidity event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay) ``` ### MovingFundsTimeoutUpdateStarted ```solidity event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp) ``` ### MovingFundsTimeoutUpdated ```solidity event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout) ``` ### MovingFundsTimeoutSlashingAmountUpdateStarted ```solidity event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp) ``` ### MovingFundsTimeoutSlashingAmountUpdated ```solidity event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount) ``` ### MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted ```solidity event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp) ``` ### MovingFundsTimeoutNotifierRewardMultiplierUpdated ```solidity event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier) ``` ### MovingFundsCommitmentGasOffsetUpdateStarted ```solidity event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp) ``` ### MovingFundsCommitmentGasOffsetUpdated ```solidity event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset) ``` ### MovedFundsSweepTxMaxTotalFeeUpdateStarted ```solidity event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp) ``` ### MovedFundsSweepTxMaxTotalFeeUpdated ```solidity event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee) ``` ### MovedFundsSweepTimeoutUpdateStarted ```solidity event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp) ``` ### MovedFundsSweepTimeoutUpdated ```solidity event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout) ``` ### MovedFundsSweepTimeoutSlashingAmountUpdateStarted ```solidity event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp) ``` ### MovedFundsSweepTimeoutSlashingAmountUpdated ```solidity event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount) ``` ### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted ```solidity event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp) ``` ### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated ```solidity event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) ``` ### WalletCreationPeriodUpdateStarted ```solidity event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp) ``` ### WalletCreationPeriodUpdated ```solidity event WalletCreationPeriodUpdated(uint32 walletCreationPeriod) ``` ### WalletCreationMinBtcBalanceUpdateStarted ```solidity event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp) ``` ### WalletCreationMinBtcBalanceUpdated ```solidity event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance) ``` ### WalletCreationMaxBtcBalanceUpdateStarted ```solidity event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp) ``` ### WalletCreationMaxBtcBalanceUpdated ```solidity event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance) ``` ### WalletClosureMinBtcBalanceUpdateStarted ```solidity event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp) ``` ### WalletClosureMinBtcBalanceUpdated ```solidity event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance) ``` ### WalletMaxAgeUpdateStarted ```solidity event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp) ``` ### WalletMaxAgeUpdated ```solidity event WalletMaxAgeUpdated(uint32 walletMaxAge) ``` ### WalletMaxBtcTransferUpdateStarted ```solidity event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp) ``` ### WalletMaxBtcTransferUpdated ```solidity event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer) ``` ### WalletClosingPeriodUpdateStarted ```solidity event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp) ``` ### WalletClosingPeriodUpdated ```solidity event WalletClosingPeriodUpdated(uint32 walletClosingPeriod) ``` ### FraudChallengeDepositAmountUpdateStarted ```solidity event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp) ``` ### FraudChallengeDepositAmountUpdated ```solidity event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount) ``` ### FraudChallengeDefeatTimeoutUpdateStarted ```solidity event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp) ``` ### FraudChallengeDefeatTimeoutUpdated ```solidity event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout) ``` ### FraudSlashingAmountUpdateStarted ```solidity event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp) ``` ### FraudSlashingAmountUpdated ```solidity event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount) ``` ### FraudNotifierRewardMultiplierUpdateStarted ```solidity event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp) ``` ### FraudNotifierRewardMultiplierUpdated ```solidity event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier) ``` ### TreasuryUpdateStarted ```solidity event TreasuryUpdateStarted(address newTreasury, uint256 timestamp) ``` ### TreasuryUpdated ```solidity event TreasuryUpdated(address treasury) ``` ### constructor ```solidity constructor(contract Bridge _bridge, uint256 _governanceDelay) public ``` ### setVaultStatus ```solidity function setVaultStatus(address vault, bool isTrusted) external ``` Allows the Governance to mark the given vault address as trusted or no longer trusted. Vaults are not trusted by default. Trusted vault must meet the following criteria: * `IVault.receiveBalanceIncrease` must have a known, low gas cost, * `IVault.receiveBalanceIncrease` must never revert. #### Parameters | Name | Type | Description | | --------- | ------- | ---------------------------------------------------- | | vault | address | The address of the vault. | | isTrusted | bool | flag indicating whether the vault is trusted or not. | ### setSpvMaintainerStatus ```solidity function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) external ``` Allows the Governance to mark the given address as trusted or no longer trusted SPV maintainer. Addresses are not trusted as SPV maintainers by default. #### Parameters | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------ | | spvMaintainer | address | The address of the SPV maintainer. | | isTrusted | bool | flag indicating whether the address is trusted or not. | ### beginGovernanceDelayUpdate ```solidity function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external ``` Begins the governance delay update process. Can be called only by the contract owner. The event that informs about the start of the governance delay was skipped on purpose to trim the contract size. All the params inside of the `governanceDelays` array are public and can be easily fetched. #### Parameters | Name | Type | Description | | -------------------- | ------- | -------------------- | | \_newGovernanceDelay | uint256 | New governance delay | ### finalizeGovernanceDelayUpdate ```solidity function finalizeGovernanceDelayUpdate() external ``` Finalizes the governance delay update process. Can be called only by the contract owner, after the governance delay elapses. Updated event was skipped on purpose to trim the contract size. All the params inside of the `governanceDelays` array are public and can be easily fetched. ### beginBridgeGovernanceTransfer ```solidity function beginBridgeGovernanceTransfer(address _newBridgeGovernance) external ``` Begins the Bridge governance transfer process. Can be called only by the contract owner. It is the governance responsibility to validate the correctness of the new Bridge Governance contract. The other reason for not adding this check is to go down with the contract size and leaving only the essential code. ### finalizeBridgeGovernanceTransfer ```solidity function finalizeBridgeGovernanceTransfer() external ``` Finalizes the bridge governance transfer process. Can be called only by the contract owner, after the governance delay elapses. Bridge governance transferred event can be read from the Governable bridge contract 'GovernanceTransferred(old, new)'. Event that informs about the transfer in this function is skipped on purpose to go down with the contract size. ### beginDepositDustThresholdUpdate ```solidity function beginDepositDustThresholdUpdate(uint64 _newDepositDustThreshold) external ``` Begins the deposit dust threshold amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------- | ------ | ---------------------------------- | | \_newDepositDustThreshold | uint64 | New deposit dust threshold amount. | ### finalizeDepositDustThresholdUpdate ```solidity function finalizeDepositDustThresholdUpdate() external ``` Finalizes the deposit dust threshold amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDepositTreasuryFeeDivisorUpdate ```solidity function beginDepositTreasuryFeeDivisorUpdate(uint64 _newDepositTreasuryFeeDivisor) external ``` Begins the deposit treasury fee divisor amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------ | ------ | --------------------------------- | | \_newDepositTreasuryFeeDivisor | uint64 | New deposit treasury fee divisor. | ### finalizeDepositTreasuryFeeDivisorUpdate ```solidity function finalizeDepositTreasuryFeeDivisorUpdate() external ``` Finalizes the deposit treasury fee divisor amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDepositTxMaxFeeUpdate ```solidity function beginDepositTxMaxFeeUpdate(uint64 _newDepositTxMaxFee) external ``` Begins the deposit tx max fee amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------- | ------ | ----------------------- | | \_newDepositTxMaxFee | uint64 | New deposit tx max fee. | ### finalizeDepositTxMaxFeeUpdate ```solidity function finalizeDepositTxMaxFeeUpdate() external ``` Finalizes the deposit tx max fee amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDepositRevealAheadPeriodUpdate ```solidity function beginDepositRevealAheadPeriodUpdate(uint32 _newDepositRevealAheadPeriod) external ``` Begins the deposit reveal ahead period update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------- | ------ | -------------------------------- | | \_newDepositRevealAheadPeriod | uint32 | New deposit reveal ahead period. | ### finalizeDepositRevealAheadPeriodUpdate ```solidity function finalizeDepositRevealAheadPeriodUpdate() external ``` Finalizes the deposit reveal ahead period update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionDustThresholdUpdate ```solidity function beginRedemptionDustThresholdUpdate(uint64 _newRedemptionDustThreshold) external ``` Begins the redemption dust threshold amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------------------- | ------ | ------------------------------ | | \_newRedemptionDustThreshold | uint64 | New redemption dust threshold. | ### finalizeRedemptionDustThresholdUpdate ```solidity function finalizeRedemptionDustThresholdUpdate() external ``` Finalizes the dust threshold amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionTreasuryFeeDivisorUpdate ```solidity function beginRedemptionTreasuryFeeDivisorUpdate(uint64 _newRedemptionTreasuryFeeDivisor) external ``` Begins the redemption treasury fee divisor amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------------- | ------ | ------------------------------------ | | \_newRedemptionTreasuryFeeDivisor | uint64 | New redemption treasury fee divisor. | ### finalizeRedemptionTreasuryFeeDivisorUpdate ```solidity function finalizeRedemptionTreasuryFeeDivisorUpdate() external ``` Finalizes the redemption treasury fee divisor amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionTxMaxFeeUpdate ```solidity function beginRedemptionTxMaxFeeUpdate(uint64 _newRedemptionTxMaxFee) external ``` Begins the redemption tx max fee amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------- | ------ | -------------------------- | | \_newRedemptionTxMaxFee | uint64 | New redemption tx max fee. | ### finalizeRedemptionTxMaxFeeUpdate ```solidity function finalizeRedemptionTxMaxFeeUpdate() external ``` Finalizes the redemption tx max fee amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionTxMaxTotalFeeUpdate ```solidity function beginRedemptionTxMaxTotalFeeUpdate(uint64 _newRedemptionTxMaxTotalFee) external ``` Begins the redemption tx max total fee amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------------------- | ------ | -------------------------------- | | \_newRedemptionTxMaxTotalFee | uint64 | New redemption tx max total fee. | ### finalizeRedemptionTxMaxTotalFeeUpdate ```solidity function finalizeRedemptionTxMaxTotalFeeUpdate() external ``` Finalizes the redemption tx max total fee amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionTimeoutUpdate ```solidity function beginRedemptionTimeoutUpdate(uint32 _newRedemptionTimeout) external ``` Begins the redemption timeout amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------------- | ------ | ----------------------- | | \_newRedemptionTimeout | uint32 | New redemption timeout. | ### finalizeRedemptionTimeoutUpdate ```solidity function finalizeRedemptionTimeoutUpdate() external ``` Finalizes the redemption timeout amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionTimeoutSlashingAmountUpdate ```solidity function beginRedemptionTimeoutSlashingAmountUpdate(uint96 _newRedemptionTimeoutSlashingAmount) external ``` Begins the redemption timeout slashing amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------------ | ------ | --------------------------------------- | | \_newRedemptionTimeoutSlashingAmount | uint96 | New redemption timeout slashing amount. | ### finalizeRedemptionTimeoutSlashingAmountUpdate ```solidity function finalizeRedemptionTimeoutSlashingAmountUpdate() external ``` Finalizes the redemption timeout slashing amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginRedemptionTimeoutNotifierRewardMultiplierUpdate ```solidity function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(uint32 _newRedemptionTimeoutNotifierRewardMultiplier) external ``` Begins the redemption timeout notifier reward multiplier amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | -------------------------------------------------- | | \_newRedemptionTimeoutNotifierRewardMultiplier | uint32 | New redemption timeout notifier reward multiplier. | ### finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate ```solidity function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate() external ``` Finalizes the redemption timeout notifier reward multiplier amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsTxMaxTotalFeeUpdate ```solidity function beginMovingFundsTxMaxTotalFeeUpdate(uint64 _newMovingFundsTxMaxTotalFee) external ``` Begins the moving funds tx max total fee update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------- | ------ | ---------------------------------- | | \_newMovingFundsTxMaxTotalFee | uint64 | New moving funds tx max total fee. | ### finalizeMovingFundsTxMaxTotalFeeUpdate ```solidity function finalizeMovingFundsTxMaxTotalFeeUpdate() external ``` Finalizes the moving funds tx max total fee update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsDustThresholdUpdate ```solidity function beginMovingFundsDustThresholdUpdate(uint64 _newMovingFundsDustThreshold) external ``` Begins the moving funds dust threshold update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------- | ------ | -------------------------------- | | \_newMovingFundsDustThreshold | uint64 | New moving funds dust threshold. | ### finalizeMovingFundsDustThresholdUpdate ```solidity function finalizeMovingFundsDustThresholdUpdate() external ``` Finalizes the moving funds dust threshold update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsTimeoutResetDelayUpdate ```solidity function beginMovingFundsTimeoutResetDelayUpdate(uint32 _newMovingFundsTimeoutResetDelay) external ``` Begins the moving funds timeout reset delay update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------------- | ------ | ------------------------------------- | | \_newMovingFundsTimeoutResetDelay | uint32 | New moving funds timeout reset delay. | ### finalizeMovingFundsTimeoutResetDelayUpdate ```solidity function finalizeMovingFundsTimeoutResetDelayUpdate() external ``` Finalizes the moving funds timeout reset delay update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsTimeoutUpdate ```solidity function beginMovingFundsTimeoutUpdate(uint32 _newMovingFundsTimeout) external ``` Begins the moving funds timeout update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------- | ------ | ------------------------- | | \_newMovingFundsTimeout | uint32 | New moving funds timeout. | ### finalizeMovingFundsTimeoutUpdate ```solidity function finalizeMovingFundsTimeoutUpdate() external ``` Finalizes the moving funds timeout update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsTimeoutSlashingAmountUpdate ```solidity function beginMovingFundsTimeoutSlashingAmountUpdate(uint96 _newMovingFundsTimeoutSlashingAmount) external ``` Begins the moving funds timeout slashing amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------------- | ------ | ----------------------------------------- | | \_newMovingFundsTimeoutSlashingAmount | uint96 | New moving funds timeout slashing amount. | ### finalizeMovingFundsTimeoutSlashingAmountUpdate ```solidity function finalizeMovingFundsTimeoutSlashingAmountUpdate() external ``` Finalizes the moving funds timeout slashing amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsTimeoutNotifierRewardMultiplierUpdate ```solidity function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) external ``` Begins the moving funds timeout notifier reward multiplier update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------------------------------------------- | | \_newMovingFundsTimeoutNotifierRewardMultiplier | uint32 | New moving funds timeout notifier reward multiplier. | ### finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate ```solidity function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate() external ``` Finalizes the moving funds timeout notifier reward multiplier update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovingFundsCommitmentGasOffsetUpdate ```solidity function beginMovingFundsCommitmentGasOffsetUpdate(uint16 _newMovingFundsCommitmentGasOffset) external ``` Begins the moving funds commitment gas offset update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------------- | ------ | --------------------------------------- | | \_newMovingFundsCommitmentGasOffset | uint16 | New moving funds commitment gas offset. | ### finalizeMovingFundsCommitmentGasOffsetUpdate ```solidity function finalizeMovingFundsCommitmentGasOffsetUpdate() external ``` Finalizes the moving funds commitment gas offset update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovedFundsSweepTxMaxTotalFeeUpdate ```solidity function beginMovedFundsSweepTxMaxTotalFeeUpdate(uint64 _newMovedFundsSweepTxMaxTotalFee) external ``` Begins the moved funds sweep tx max total fee update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------------- | ------ | --------------------------------------- | | \_newMovedFundsSweepTxMaxTotalFee | uint64 | New moved funds sweep tx max total fee. | ### finalizeMovedFundsSweepTxMaxTotalFeeUpdate ```solidity function finalizeMovedFundsSweepTxMaxTotalFeeUpdate() external ``` Finalizes the moved funds sweep tx max total fee update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovedFundsSweepTimeoutUpdate ```solidity function beginMovedFundsSweepTimeoutUpdate(uint32 _newMovedFundsSweepTimeout) external ``` Begins the moved funds sweep timeout update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------- | ------ | ------------------------------ | | \_newMovedFundsSweepTimeout | uint32 | New moved funds sweep timeout. | ### finalizeMovedFundsSweepTimeoutUpdate ```solidity function finalizeMovedFundsSweepTimeoutUpdate() external ``` Finalizes the moved funds sweep timeout update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovedFundsSweepTimeoutSlashingAmountUpdate ```solidity function beginMovedFundsSweepTimeoutSlashingAmountUpdate(uint96 _newMovedFundsSweepTimeoutSlashingAmount) external ``` Begins the moved funds sweep timeout slashing amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ---------------------------------------------- | | \_newMovedFundsSweepTimeoutSlashingAmount | uint96 | New moved funds sweep timeout slashing amount. | ### finalizeMovedFundsSweepTimeoutSlashingAmountUpdate ```solidity function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate() external ``` Finalizes the moved funds sweep timeout slashing amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate ```solidity function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) external ``` Begins the moved funds sweep timeout notifier reward multiplier update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------------------------------- | ------ | --------------------------------------------------------- | | \_newMovedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New moved funds sweep timeout notifier reward multiplier. | ### finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate ```solidity function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate() external ``` Finalizes the moved funds sweep timeout notifier reward multiplier update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletCreationPeriodUpdate ```solidity function beginWalletCreationPeriodUpdate(uint32 _newWalletCreationPeriod) external ``` Begins the wallet creation period update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------- | ------ | --------------------------- | | \_newWalletCreationPeriod | uint32 | New wallet creation period. | ### finalizeWalletCreationPeriodUpdate ```solidity function finalizeWalletCreationPeriodUpdate() external ``` Finalizes the wallet creation period update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletCreationMinBtcBalanceUpdate ```solidity function beginWalletCreationMinBtcBalanceUpdate(uint64 _newWalletCreationMinBtcBalance) external ``` Begins the wallet creation min btc balance update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------- | ------ | ------------------------------------ | | \_newWalletCreationMinBtcBalance | uint64 | New wallet creation min btc balance. | ### finalizeWalletCreationMinBtcBalanceUpdate ```solidity function finalizeWalletCreationMinBtcBalanceUpdate() external ``` Finalizes the wallet creation min btc balance update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletCreationMaxBtcBalanceUpdate ```solidity function beginWalletCreationMaxBtcBalanceUpdate(uint64 _newWalletCreationMaxBtcBalance) external ``` Begins the wallet creation max btc balance update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------- | ------ | ------------------------------------ | | \_newWalletCreationMaxBtcBalance | uint64 | New wallet creation max btc balance. | ### finalizeWalletCreationMaxBtcBalanceUpdate ```solidity function finalizeWalletCreationMaxBtcBalanceUpdate() external ``` Finalizes the wallet creation max btc balance update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletClosureMinBtcBalanceUpdate ```solidity function beginWalletClosureMinBtcBalanceUpdate(uint64 _newWalletClosureMinBtcBalance) external ``` Begins the wallet closure min btc balance update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------- | ------ | ----------------------------------- | | \_newWalletClosureMinBtcBalance | uint64 | New wallet closure min btc balance. | ### finalizeWalletClosureMinBtcBalanceUpdate ```solidity function finalizeWalletClosureMinBtcBalanceUpdate() external ``` Finalizes the wallet closure min btc balance update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletMaxAgeUpdate ```solidity function beginWalletMaxAgeUpdate(uint32 _newWalletMaxAge) external ``` Begins the wallet max age update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------- | ------ | ------------------- | | \_newWalletMaxAge | uint32 | New wallet max age. | ### finalizeWalletMaxAgeUpdate ```solidity function finalizeWalletMaxAgeUpdate() external ``` Finalizes the wallet max age update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletMaxBtcTransferUpdate ```solidity function beginWalletMaxBtcTransferUpdate(uint64 _newWalletMaxBtcTransfer) external ``` Begins the wallet max btc transfer amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------- | ------ | ---------------------------- | | \_newWalletMaxBtcTransfer | uint64 | New wallet max btc transfer. | ### finalizeWalletMaxBtcTransferUpdate ```solidity function finalizeWalletMaxBtcTransferUpdate() external ``` Finalizes the wallet max btc transfer amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletClosingPeriodUpdate ```solidity function beginWalletClosingPeriodUpdate(uint32 _newWalletClosingPeriod) external ``` Begins the wallet closing period update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------ | ------ | -------------------------- | | \_newWalletClosingPeriod | uint32 | New wallet closing period. | ### finalizeWalletClosingPeriodUpdate ```solidity function finalizeWalletClosingPeriodUpdate() external ``` Finalizes the wallet closing period update process. Can be called only by the contract owner, after the governance delay elapses. ### beginFraudChallengeDepositAmountUpdate ```solidity function beginFraudChallengeDepositAmountUpdate(uint96 _newFraudChallengeDepositAmount) external ``` Begins the fraud challenge deposit amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------- | ------ | ----------------------------------- | | \_newFraudChallengeDepositAmount | uint96 | New fraud challenge deposit amount. | ### finalizeFraudChallengeDepositAmountUpdate ```solidity function finalizeFraudChallengeDepositAmountUpdate() external ``` Finalizes the fraud challenge deposit amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginFraudChallengeDefeatTimeoutUpdate ```solidity function beginFraudChallengeDefeatTimeoutUpdate(uint32 _newFraudChallengeDefeatTimeout) external ``` Begins the fraud challenge defeat timeout update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------- | ------ | ----------------------------------- | | \_newFraudChallengeDefeatTimeout | uint32 | New fraud challenge defeat timeout. | ### finalizeFraudChallengeDefeatTimeoutUpdate ```solidity function finalizeFraudChallengeDefeatTimeoutUpdate() external ``` Finalizes the fraud challenge defeat timeout update process. Can be called only by the contract owner, after the governance delay elapses. ### beginFraudSlashingAmountUpdate ```solidity function beginFraudSlashingAmountUpdate(uint96 _newFraudSlashingAmount) external ``` Begins the fraud slashing amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------ | ------ | -------------------------- | | \_newFraudSlashingAmount | uint96 | New fraud slashing amount. | ### finalizeFraudSlashingAmountUpdate ```solidity function finalizeFraudSlashingAmountUpdate() external ``` Finalizes the fraud slashing amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginFraudNotifierRewardMultiplierUpdate ```solidity function beginFraudNotifierRewardMultiplierUpdate(uint32 _newFraudNotifierRewardMultiplier) external ``` Begins the fraud notifier reward multiplier update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------------------------- | ------ | ------------------------------------- | | \_newFraudNotifierRewardMultiplier | uint32 | New fraud notifier reward multiplier. | ### finalizeFraudNotifierRewardMultiplierUpdate ```solidity function finalizeFraudNotifierRewardMultiplierUpdate() external ``` Finalizes the fraud notifier reward multiplier update process. Can be called only by the contract owner, after the governance delay elapses. ### beginTreasuryUpdate ```solidity function beginTreasuryUpdate(address _newTreasury) external ``` Begins the treasury address update process. Can be called only by the contract owner. It does not perform any parameter validation. #### Parameters | Name | Type | Description | | ------------- | ------- | --------------------- | | \_newTreasury | address | New treasury address. | ### finalizeTreasuryUpdate ```solidity function finalizeTreasuryUpdate() external ``` Finalizes the treasury address update process. Can be called only by the contract owner, after the governance delay elapses. ### governanceDelay ```solidity function governanceDelay() internal view returns (uint256) ``` Gets the governance delay parameter. # BridgeGovernanceParameters ## BridgeGovernanceParameters ### TreasuryData ```solidity struct TreasuryData { address newTreasury; uint256 treasuryChangeInitiated; } ``` ### DepositData ```solidity struct DepositData { uint64 newDepositDustThreshold; uint256 depositDustThresholdChangeInitiated; uint64 newDepositTreasuryFeeDivisor; uint256 depositTreasuryFeeDivisorChangeInitiated; uint64 newDepositTxMaxFee; uint256 depositTxMaxFeeChangeInitiated; uint32 newDepositRevealAheadPeriod; uint256 depositRevealAheadPeriodChangeInitiated; } ``` ### RedemptionData ```solidity struct RedemptionData { uint64 newRedemptionDustThreshold; uint256 redemptionDustThresholdChangeInitiated; uint64 newRedemptionTreasuryFeeDivisor; uint256 redemptionTreasuryFeeDivisorChangeInitiated; uint64 newRedemptionTxMaxFee; uint256 redemptionTxMaxFeeChangeInitiated; uint64 newRedemptionTxMaxTotalFee; uint256 redemptionTxMaxTotalFeeChangeInitiated; uint32 newRedemptionTimeout; uint256 redemptionTimeoutChangeInitiated; uint96 newRedemptionTimeoutSlashingAmount; uint256 redemptionTimeoutSlashingAmountChangeInitiated; uint32 newRedemptionTimeoutNotifierRewardMultiplier; uint256 redemptionTimeoutNotifierRewardMultiplierChangeInitiated; } ``` ### MovingFundsData ```solidity struct MovingFundsData { uint64 newMovingFundsTxMaxTotalFee; uint256 movingFundsTxMaxTotalFeeChangeInitiated; uint64 newMovingFundsDustThreshold; uint256 movingFundsDustThresholdChangeInitiated; uint32 newMovingFundsTimeoutResetDelay; uint256 movingFundsTimeoutResetDelayChangeInitiated; uint32 newMovingFundsTimeout; uint256 movingFundsTimeoutChangeInitiated; uint96 newMovingFundsTimeoutSlashingAmount; uint256 movingFundsTimeoutSlashingAmountChangeInitiated; uint32 newMovingFundsTimeoutNotifierRewardMultiplier; uint256 movingFundsTimeoutNotifierRewardMultiplierChangeInitiated; uint16 newMovingFundsCommitmentGasOffset; uint256 movingFundsCommitmentGasOffsetChangeInitiated; uint64 newMovedFundsSweepTxMaxTotalFee; uint256 movedFundsSweepTxMaxTotalFeeChangeInitiated; uint32 newMovedFundsSweepTimeout; uint256 movedFundsSweepTimeoutChangeInitiated; uint96 newMovedFundsSweepTimeoutSlashingAmount; uint256 movedFundsSweepTimeoutSlashingAmountChangeInitiated; uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier; uint256 movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated; } ``` ### WalletData ```solidity struct WalletData { uint32 newWalletCreationPeriod; uint256 walletCreationPeriodChangeInitiated; uint64 newWalletCreationMinBtcBalance; uint256 walletCreationMinBtcBalanceChangeInitiated; uint64 newWalletCreationMaxBtcBalance; uint256 walletCreationMaxBtcBalanceChangeInitiated; uint64 newWalletClosureMinBtcBalance; uint256 walletClosureMinBtcBalanceChangeInitiated; uint32 newWalletMaxAge; uint256 walletMaxAgeChangeInitiated; uint64 newWalletMaxBtcTransfer; uint256 walletMaxBtcTransferChangeInitiated; uint32 newWalletClosingPeriod; uint256 walletClosingPeriodChangeInitiated; } ``` ### FraudData ```solidity struct FraudData { uint96 newFraudChallengeDepositAmount; uint256 fraudChallengeDepositAmountChangeInitiated; uint32 newFraudChallengeDefeatTimeout; uint256 fraudChallengeDefeatTimeoutChangeInitiated; uint96 newFraudSlashingAmount; uint256 fraudSlashingAmountChangeInitiated; uint32 newFraudNotifierRewardMultiplier; uint256 fraudNotifierRewardMultiplierChangeInitiated; } ``` ### DepositDustThresholdUpdateStarted ```solidity event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp) ``` ### DepositDustThresholdUpdated ```solidity event DepositDustThresholdUpdated(uint64 depositDustThreshold) ``` ### DepositTreasuryFeeDivisorUpdateStarted ```solidity event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp) ``` ### DepositTreasuryFeeDivisorUpdated ```solidity event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor) ``` ### DepositTxMaxFeeUpdateStarted ```solidity event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp) ``` ### DepositTxMaxFeeUpdated ```solidity event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee) ``` ### DepositRevealAheadPeriodUpdateStarted ```solidity event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp) ``` ### DepositRevealAheadPeriodUpdated ```solidity event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod) ``` ### RedemptionDustThresholdUpdateStarted ```solidity event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp) ``` ### RedemptionDustThresholdUpdated ```solidity event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold) ``` ### RedemptionTreasuryFeeDivisorUpdateStarted ```solidity event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp) ``` ### RedemptionTreasuryFeeDivisorUpdated ```solidity event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor) ``` ### RedemptionTxMaxFeeUpdateStarted ```solidity event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp) ``` ### RedemptionTxMaxFeeUpdated ```solidity event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee) ``` ### RedemptionTxMaxTotalFeeUpdateStarted ```solidity event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp) ``` ### RedemptionTxMaxTotalFeeUpdated ```solidity event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee) ``` ### RedemptionTimeoutUpdateStarted ```solidity event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp) ``` ### RedemptionTimeoutUpdated ```solidity event RedemptionTimeoutUpdated(uint32 redemptionTimeout) ``` ### RedemptionTimeoutSlashingAmountUpdateStarted ```solidity event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp) ``` ### RedemptionTimeoutSlashingAmountUpdated ```solidity event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount) ``` ### RedemptionTimeoutNotifierRewardMultiplierUpdateStarted ```solidity event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp) ``` ### RedemptionTimeoutNotifierRewardMultiplierUpdated ```solidity event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier) ``` ### MovingFundsTxMaxTotalFeeUpdateStarted ```solidity event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp) ``` ### MovingFundsTxMaxTotalFeeUpdated ```solidity event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee) ``` ### MovingFundsDustThresholdUpdateStarted ```solidity event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp) ``` ### MovingFundsDustThresholdUpdated ```solidity event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold) ``` ### MovingFundsTimeoutResetDelayUpdateStarted ```solidity event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp) ``` ### MovingFundsTimeoutResetDelayUpdated ```solidity event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay) ``` ### MovingFundsTimeoutUpdateStarted ```solidity event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp) ``` ### MovingFundsTimeoutUpdated ```solidity event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout) ``` ### MovingFundsTimeoutSlashingAmountUpdateStarted ```solidity event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp) ``` ### MovingFundsTimeoutSlashingAmountUpdated ```solidity event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount) ``` ### MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted ```solidity event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp) ``` ### MovingFundsTimeoutNotifierRewardMultiplierUpdated ```solidity event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier) ``` ### MovingFundsCommitmentGasOffsetUpdateStarted ```solidity event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp) ``` ### MovingFundsCommitmentGasOffsetUpdated ```solidity event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset) ``` ### MovedFundsSweepTxMaxTotalFeeUpdateStarted ```solidity event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp) ``` ### MovedFundsSweepTxMaxTotalFeeUpdated ```solidity event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee) ``` ### MovedFundsSweepTimeoutUpdateStarted ```solidity event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp) ``` ### MovedFundsSweepTimeoutUpdated ```solidity event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout) ``` ### MovedFundsSweepTimeoutSlashingAmountUpdateStarted ```solidity event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp) ``` ### MovedFundsSweepTimeoutSlashingAmountUpdated ```solidity event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount) ``` ### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted ```solidity event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp) ``` ### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated ```solidity event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) ``` ### WalletCreationPeriodUpdateStarted ```solidity event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp) ``` ### WalletCreationPeriodUpdated ```solidity event WalletCreationPeriodUpdated(uint32 walletCreationPeriod) ``` ### WalletCreationMinBtcBalanceUpdateStarted ```solidity event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp) ``` ### WalletCreationMinBtcBalanceUpdated ```solidity event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance) ``` ### WalletCreationMaxBtcBalanceUpdateStarted ```solidity event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp) ``` ### WalletCreationMaxBtcBalanceUpdated ```solidity event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance) ``` ### WalletClosureMinBtcBalanceUpdateStarted ```solidity event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp) ``` ### WalletClosureMinBtcBalanceUpdated ```solidity event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance) ``` ### WalletMaxAgeUpdateStarted ```solidity event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp) ``` ### WalletMaxAgeUpdated ```solidity event WalletMaxAgeUpdated(uint32 walletMaxAge) ``` ### WalletMaxBtcTransferUpdateStarted ```solidity event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp) ``` ### WalletMaxBtcTransferUpdated ```solidity event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer) ``` ### WalletClosingPeriodUpdateStarted ```solidity event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp) ``` ### WalletClosingPeriodUpdated ```solidity event WalletClosingPeriodUpdated(uint32 walletClosingPeriod) ``` ### FraudChallengeDepositAmountUpdateStarted ```solidity event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp) ``` ### FraudChallengeDepositAmountUpdated ```solidity event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount) ``` ### FraudChallengeDefeatTimeoutUpdateStarted ```solidity event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp) ``` ### FraudChallengeDefeatTimeoutUpdated ```solidity event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout) ``` ### FraudSlashingAmountUpdateStarted ```solidity event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp) ``` ### FraudSlashingAmountUpdated ```solidity event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount) ``` ### FraudNotifierRewardMultiplierUpdateStarted ```solidity event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp) ``` ### FraudNotifierRewardMultiplierUpdated ```solidity event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier) ``` ### TreasuryUpdateStarted ```solidity event TreasuryUpdateStarted(address newTreasury, uint256 timestamp) ``` ### TreasuryUpdated ```solidity event TreasuryUpdated(address treasury) ``` ### onlyAfterGovernanceDelay ```solidity modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 governanceDelay) ``` Reverts if called before the governance delay elapses. #### Parameters | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------- | | changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | | governanceDelay | uint256 | | ### beginDepositDustThresholdUpdate ```solidity function beginDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositDustThreshold) external ``` Begins the deposit dust threshold amount update process. #### Parameters | Name | Type | Description | | ------------------------- | --------------------------------------------- | ---------------------------------- | | self | struct BridgeGovernanceParameters.DepositData | | | \_newDepositDustThreshold | uint64 | New deposit dust threshold amount. | ### finalizeDepositDustThresholdUpdate ```solidity function finalizeDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external ``` Finalizes the deposit dust threshold amount update process. Can be called after the governance delay elapses. ### beginDepositTreasuryFeeDivisorUpdate ```solidity function beginDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTreasuryFeeDivisor) external ``` Begins the deposit treasury fee divisor amount update process. #### Parameters | Name | Type | Description | | ------------------------------ | --------------------------------------------- | ---------------------------------------- | | self | struct BridgeGovernanceParameters.DepositData | | | \_newDepositTreasuryFeeDivisor | uint64 | New deposit treasury fee divisor amount. | ### finalizeDepositTreasuryFeeDivisorUpdate ```solidity function finalizeDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external ``` Finalizes the deposit treasury fee divisor amount update process. Can be called after the governance delay elapses. ### beginDepositTxMaxFeeUpdate ```solidity function beginDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTxMaxFee) external ``` Begins the deposit tx max fee amount update process. #### Parameters | Name | Type | Description | | -------------------- | --------------------------------------------- | ------------------------------ | | self | struct BridgeGovernanceParameters.DepositData | | | \_newDepositTxMaxFee | uint64 | New deposit tx max fee amount. | ### finalizeDepositTxMaxFeeUpdate ```solidity function finalizeDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external ``` Finalizes the deposit tx max fee amount update process. Can be called after the governance delay elapses. ### beginDepositRevealAheadPeriodUpdate ```solidity function beginDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint32 _newDepositRevealAheadPeriod) external ``` Begins the deposit reveal ahead period update process. #### Parameters | Name | Type | Description | | ----------------------------- | --------------------------------------------- | -------------------------------- | | self | struct BridgeGovernanceParameters.DepositData | | | \_newDepositRevealAheadPeriod | uint32 | New deposit reveal ahead period. | ### finalizeDepositRevealAheadPeriodUpdate ```solidity function finalizeDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external ``` Finalizes the deposit reveal ahead period update process. Can be called after the governance delay elapses. ### beginRedemptionDustThresholdUpdate ```solidity function beginRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionDustThreshold) external ``` Begins the redemption dust threshold amount update process. #### Parameters | Name | Type | Description | | ---------------------------- | ------------------------------------------------ | ------------------------------------- | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionDustThreshold | uint64 | New redemption dust threshold amount. | ### finalizeRedemptionDustThresholdUpdate ```solidity function finalizeRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption dust threshold amount update process. Can be called after the governance delay elapses. ### beginRedemptionTreasuryFeeDivisorUpdate ```solidity function beginRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTreasuryFeeDivisor) external ``` Begins the redemption treasury fee divisor amount update process. #### Parameters | Name | Type | Description | | --------------------------------- | ------------------------------------------------ | ------------------------------------------- | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionTreasuryFeeDivisor | uint64 | New redemption treasury fee divisor amount. | ### finalizeRedemptionTreasuryFeeDivisorUpdate ```solidity function finalizeRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption treasury fee divisor amount update process. Can be called after the governance delay elapses. ### beginRedemptionTxMaxFeeUpdate ```solidity function beginRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxFee) external ``` Begins the redemption tx max fee amount update process. #### Parameters | Name | Type | Description | | ----------------------- | ------------------------------------------------ | --------------------------------- | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionTxMaxFee | uint64 | New redemption tx max fee amount. | ### finalizeRedemptionTxMaxFeeUpdate ```solidity function finalizeRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption tx max fee amount update process. Can be called after the governance delay elapses. ### beginRedemptionTxMaxTotalFeeUpdate ```solidity function beginRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxTotalFee) external ``` Begins the redemption tx max total fee amount update process. #### Parameters | Name | Type | Description | | ---------------------------- | ------------------------------------------------ | --------------------------------------- | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionTxMaxTotalFee | uint64 | New redemption tx max total fee amount. | ### finalizeRedemptionTxMaxTotalFeeUpdate ```solidity function finalizeRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption tx max total fee amount update process. Can be called after the governance delay elapses. ### beginRedemptionTimeoutUpdate ```solidity function beginRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeout) external ``` Begins the redemption timeout amount update process. #### Parameters | Name | Type | Description | | ---------------------- | ------------------------------------------------ | ------------------------------ | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionTimeout | uint32 | New redemption timeout amount. | ### finalizeRedemptionTimeoutUpdate ```solidity function finalizeRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption timeout amount update process. Can be called after the governance delay elapses. ### beginRedemptionTimeoutSlashingAmountUpdate ```solidity function beginRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint96 _newRedemptionTimeoutSlashingAmount) external ``` Begins the redemption timeout slashing amount update process. #### Parameters | Name | Type | Description | | ------------------------------------ | ------------------------------------------------ | --------------------------------------- | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionTimeoutSlashingAmount | uint96 | New redemption timeout slashing amount. | ### finalizeRedemptionTimeoutSlashingAmountUpdate ```solidity function finalizeRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption timeout slashing amount update process. Can be called after the governance delay elapses. ### beginRedemptionTimeoutNotifierRewardMultiplierUpdate ```solidity function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeoutNotifierRewardMultiplier) external ``` Begins the redemption timeout notifier reward multiplier amount update process. #### Parameters | Name | Type | Description | | ---------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------- | | self | struct BridgeGovernanceParameters.RedemptionData | | | \_newRedemptionTimeoutNotifierRewardMultiplier | uint32 | New redemption timeout notifier reward multiplier amount. | ### finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate ```solidity function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external ``` Finalizes the redemption timeout notifier reward multiplier amount update process. Can be called after the governance delay elapses. ### beginMovingFundsTxMaxTotalFeeUpdate ```solidity function beginMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsTxMaxTotalFee) external ``` Begins the moving funds tx max total fee amount update process. #### Parameters | Name | Type | Description | | ----------------------------- | ------------------------------------------------- | ----------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsTxMaxTotalFee | uint64 | New moving funds tx max total fee amount. | ### finalizeMovingFundsTxMaxTotalFeeUpdate ```solidity function finalizeMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds tx max total fee amount update process. Can be called after the governance delay elapses. ### beginMovingFundsDustThresholdUpdate ```solidity function beginMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsDustThreshold) external ``` Begins the moving funds dust threshold amount update process. #### Parameters | Name | Type | Description | | ----------------------------- | ------------------------------------------------- | --------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsDustThreshold | uint64 | New moving funds dust threshold amount. | ### finalizeMovingFundsDustThresholdUpdate ```solidity function finalizeMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds dust threshold amount update process. Can be called after the governance delay elapses. ### beginMovingFundsTimeoutResetDelayUpdate ```solidity function beginMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutResetDelay) external ``` Begins the moving funds timeout reset delay amount update process. #### Parameters | Name | Type | Description | | --------------------------------- | ------------------------------------------------- | -------------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsTimeoutResetDelay | uint32 | New moving funds timeout reset delay amount. | ### finalizeMovingFundsTimeoutResetDelayUpdate ```solidity function finalizeMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds timeout reset delay amount update process. Can be called after the governance delay elapses. ### beginMovingFundsTimeoutUpdate ```solidity function beginMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeout) external ``` Begins the moving funds timeout amount update process. #### Parameters | Name | Type | Description | | ----------------------- | ------------------------------------------------- | -------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsTimeout | uint32 | New moving funds timeout amount. | ### finalizeMovingFundsTimeoutUpdate ```solidity function finalizeMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds timeout amount update process. Can be called after the governance delay elapses. ### beginMovingFundsTimeoutSlashingAmountUpdate ```solidity function beginMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovingFundsTimeoutSlashingAmount) external ``` Begins the moving funds timeout slashing amount update process. #### Parameters | Name | Type | Description | | ------------------------------------- | ------------------------------------------------- | ----------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsTimeoutSlashingAmount | uint96 | New moving funds timeout slashing amount. | ### finalizeMovingFundsTimeoutSlashingAmountUpdate ```solidity function finalizeMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds timeout slashing amount update process. Can be called after the governance delay elapses. ### beginMovingFundsTimeoutNotifierRewardMultiplierUpdate ```solidity function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) external ``` Begins the moving funds timeout notifier reward multiplier amount update process. #### Parameters | Name | Type | Description | | ----------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsTimeoutNotifierRewardMultiplier | uint32 | New moving funds timeout notifier reward multiplier amount. | ### finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate ```solidity function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds timeout notifier reward multiplier amount update process. Can be called after the governance delay elapses. ### beginMovingFundsCommitmentGasOffsetUpdate ```solidity function beginMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint16 _newMovingFundsCommitmentGasOffset) external ``` Begins the moving funds commitment gas offset update process. #### Parameters | Name | Type | Description | | ----------------------------------- | ------------------------------------------------- | --------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovingFundsCommitmentGasOffset | uint16 | New moving funds commitment gas offset. | ### finalizeMovingFundsCommitmentGasOffsetUpdate ```solidity function finalizeMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moving funds commitment gas offset update process. Can be called after the governance delay elapses. ### beginMovedFundsSweepTxMaxTotalFeeUpdate ```solidity function beginMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovedFundsSweepTxMaxTotalFee) external ``` Begins the moved funds sweep tx max total fee amount update process. #### Parameters | Name | Type | Description | | --------------------------------- | ------------------------------------------------- | ---------------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovedFundsSweepTxMaxTotalFee | uint64 | New moved funds sweep tx max total fee amount. | ### finalizeMovedFundsSweepTxMaxTotalFeeUpdate ```solidity function finalizeMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moved funds sweep tx max total fee amount update process. Can be called after the governance delay elapses. ### beginMovedFundsSweepTimeoutUpdate ```solidity function beginMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeout) external ``` Begins the moved funds sweep timeout amount update process. #### Parameters | Name | Type | Description | | --------------------------- | ------------------------------------------------- | ------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovedFundsSweepTimeout | uint32 | New moved funds sweep timeout amount. | ### finalizeMovedFundsSweepTimeoutUpdate ```solidity function finalizeMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moved funds sweep timeout amount update process. Can be called after the governance delay elapses. ### beginMovedFundsSweepTimeoutSlashingAmountUpdate ```solidity function beginMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovedFundsSweepTimeoutSlashingAmount) external ``` Begins the moved funds sweep timeout slashing amount update process. #### Parameters | Name | Type | Description | | ----------------------------------------- | ------------------------------------------------- | ---------------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovedFundsSweepTimeoutSlashingAmount | uint96 | New moved funds sweep timeout slashing amount. | ### finalizeMovedFundsSweepTimeoutSlashingAmountUpdate ```solidity function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moved funds sweep timeout slashing amount update process. Can be called after the governance delay elapses. ### beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate ```solidity function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) external ``` Begins the moved funds sweep timeout notifier reward multiplier amount update process. #### Parameters | Name | Type | Description | | --------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- | | self | struct BridgeGovernanceParameters.MovingFundsData | | | \_newMovedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New moved funds sweep timeout notifier reward multiplier amount. | ### finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate ```solidity function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external ``` Finalizes the moved funds sweep timeout notifier reward multiplier amount update process. Can be called after the governance delay elapses. ### beginWalletCreationPeriodUpdate ```solidity function beginWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletCreationPeriod) external ``` Begins the wallet creation period amount update process. #### Parameters | Name | Type | Description | | ------------------------- | -------------------------------------------- | ---------------------------------- | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletCreationPeriod | uint32 | New wallet creation period amount. | ### finalizeWalletCreationPeriodUpdate ```solidity function finalizeWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet creation period amount update process. Can be called after the governance delay elapses. ### beginWalletCreationMinBtcBalanceUpdate ```solidity function beginWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMinBtcBalance) external ``` Begins the wallet creation min btc balance amount update process. #### Parameters | Name | Type | Description | | -------------------------------- | -------------------------------------------- | ------------------------------------------- | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletCreationMinBtcBalance | uint64 | New wallet creation min btc balance amount. | ### finalizeWalletCreationMinBtcBalanceUpdate ```solidity function finalizeWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet creation min btc balance amount update process. Can be called after the governance delay elapses. ### beginWalletCreationMaxBtcBalanceUpdate ```solidity function beginWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMaxBtcBalance) external ``` Begins the wallet creation max btc balance amount update process. #### Parameters | Name | Type | Description | | -------------------------------- | -------------------------------------------- | ------------------------------------------- | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletCreationMaxBtcBalance | uint64 | New wallet creation max btc balance amount. | ### finalizeWalletCreationMaxBtcBalanceUpdate ```solidity function finalizeWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet creation max btc balance amount update process. Can be called after the governance delay elapses. ### beginWalletClosureMinBtcBalanceUpdate ```solidity function beginWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletClosureMinBtcBalance) external ``` Begins the wallet closure min btc balance amount update process. #### Parameters | Name | Type | Description | | ------------------------------- | -------------------------------------------- | ------------------------------------------ | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletClosureMinBtcBalance | uint64 | New wallet closure min btc balance amount. | ### finalizeWalletClosureMinBtcBalanceUpdate ```solidity function finalizeWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet closure min btc balance amount update process. Can be called after the governance delay elapses. ### beginWalletMaxAgeUpdate ```solidity function beginWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletMaxAge) external ``` Begins the wallet max age amount update process. #### Parameters | Name | Type | Description | | ----------------- | -------------------------------------------- | -------------------------- | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletMaxAge | uint32 | New wallet max age amount. | ### finalizeWalletMaxAgeUpdate ```solidity function finalizeWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet max age amount update process. Can be called after the governance delay elapses. ### beginWalletMaxBtcTransferUpdate ```solidity function beginWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletMaxBtcTransfer) external ``` Begins the wallet max btc transfer amount update process. #### Parameters | Name | Type | Description | | ------------------------- | -------------------------------------------- | ----------------------------------- | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletMaxBtcTransfer | uint64 | New wallet max btc transfer amount. | ### finalizeWalletMaxBtcTransferUpdate ```solidity function finalizeWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet max btc transfer amount update process. Can be called after the governance delay elapses. ### beginWalletClosingPeriodUpdate ```solidity function beginWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletClosingPeriod) external ``` Begins the wallet closing period amount update process. #### Parameters | Name | Type | Description | | ------------------------ | -------------------------------------------- | --------------------------------- | | self | struct BridgeGovernanceParameters.WalletData | | | \_newWalletClosingPeriod | uint32 | New wallet closing period amount. | ### finalizeWalletClosingPeriodUpdate ```solidity function finalizeWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external ``` Finalizes the wallet closing period amount update process. Can be called after the governance delay elapses. ### beginFraudChallengeDepositAmountUpdate ```solidity function beginFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudChallengeDepositAmount) external ``` Begins the fraud challenge deposit amount update process. #### Parameters | Name | Type | Description | | -------------------------------- | ------------------------------------------- | ----------------------------------- | | self | struct BridgeGovernanceParameters.FraudData | | | \_newFraudChallengeDepositAmount | uint96 | New fraud challenge deposit amount. | ### finalizeFraudChallengeDepositAmountUpdate ```solidity function finalizeFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external ``` Finalizes the fraud challenge deposit amount update process. Can be called after the governance delay elapses. ### beginFraudChallengeDefeatTimeoutUpdate ```solidity function beginFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudChallengeDefeatTimeout) external ``` Begins the fraud challenge defeat timeout amount update process. #### Parameters | Name | Type | Description | | -------------------------------- | ------------------------------------------- | ------------------------------------------ | | self | struct BridgeGovernanceParameters.FraudData | | | \_newFraudChallengeDefeatTimeout | uint32 | New fraud challenge defeat timeout amount. | ### finalizeFraudChallengeDefeatTimeoutUpdate ```solidity function finalizeFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external ``` Finalizes the fraud challenge defeat timeout amount update process. Can be called after the governance delay elapses. ### beginFraudSlashingAmountUpdate ```solidity function beginFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudSlashingAmount) external ``` Begins the fraud slashing amount update process. #### Parameters | Name | Type | Description | | ------------------------ | ------------------------------------------- | -------------------------- | | self | struct BridgeGovernanceParameters.FraudData | | | \_newFraudSlashingAmount | uint96 | New fraud slashing amount. | ### finalizeFraudSlashingAmountUpdate ```solidity function finalizeFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external ``` Finalizes the fraud slashing amount update process. Can be called after the governance delay elapses. ### beginFraudNotifierRewardMultiplierUpdate ```solidity function beginFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudNotifierRewardMultiplier) external ``` Begins the fraud notifier reward multiplier amount update process. #### Parameters | Name | Type | Description | | ---------------------------------- | ------------------------------------------- | -------------------------------------------- | | self | struct BridgeGovernanceParameters.FraudData | | | \_newFraudNotifierRewardMultiplier | uint32 | New fraud notifier reward multiplier amount. | ### finalizeFraudNotifierRewardMultiplierUpdate ```solidity function finalizeFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external ``` Finalizes the fraud notifier reward multiplier amount update process. Can be called after the governance delay elapses. ### beginTreasuryUpdate ```solidity function beginTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, address _newTreasury) external ``` Begins the treasury address update process. It does not perform any parameter validation. #### Parameters | Name | Type | Description | | ------------- | ---------------------------------------------- | --------------------- | | self | struct BridgeGovernanceParameters.TreasuryData | | | \_newTreasury | address | New treasury address. | ### finalizeTreasuryUpdate ```solidity function finalizeTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, uint256 governanceDelay) external ``` Finalizes the treasury address update process. Can be called after the governance delay elapses. # BridgeState ## BridgeState ### Storage ```solidity struct Storage { contract Bank bank; contract IRelay relay; uint96 txProofDifficultyFactor; contract IWalletRegistry ecdsaWalletRegistry; contract ReimbursementPool reimbursementPool; address treasury; bytes32 __treasuryAlignmentGap; uint64 depositDustThreshold; uint64 depositTreasuryFeeDivisor; uint64 depositTxMaxFee; uint32 depositRevealAheadPeriod; bytes32 __depositAlignmentGap; uint64 movingFundsTxMaxTotalFee; uint64 movingFundsDustThreshold; uint32 movingFundsTimeoutResetDelay; uint32 movingFundsTimeout; uint96 movingFundsTimeoutSlashingAmount; uint32 movingFundsTimeoutNotifierRewardMultiplier; uint16 movingFundsCommitmentGasOffset; bytes32 __movingFundsAlignmentGap; uint64 movedFundsSweepTxMaxTotalFee; uint32 movedFundsSweepTimeout; uint96 movedFundsSweepTimeoutSlashingAmount; uint32 movedFundsSweepTimeoutNotifierRewardMultiplier; uint64 redemptionDustThreshold; uint64 redemptionTreasuryFeeDivisor; uint64 redemptionTxMaxFee; uint64 redemptionTxMaxTotalFee; bytes32 __redemptionAlignmentGap; uint32 redemptionTimeout; uint96 redemptionTimeoutSlashingAmount; uint32 redemptionTimeoutNotifierRewardMultiplier; uint96 fraudChallengeDepositAmount; uint32 fraudChallengeDefeatTimeout; uint96 fraudSlashingAmount; uint32 fraudNotifierRewardMultiplier; uint32 walletCreationPeriod; uint64 walletCreationMinBtcBalance; uint64 walletCreationMaxBtcBalance; uint64 walletClosureMinBtcBalance; uint32 walletMaxAge; bytes20 activeWalletPubKeyHash; uint32 liveWalletsCount; uint64 walletMaxBtcTransfer; uint32 walletClosingPeriod; mapping(uint256 => struct Deposit.DepositRequest) deposits; mapping(address => bool) isVaultTrusted; mapping(address => bool) isSpvMaintainer; mapping(uint256 => struct MovingFunds.MovedFundsSweepRequest) movedFundsSweepRequests; mapping(uint256 => struct Redemption.RedemptionRequest) pendingRedemptions; mapping(uint256 => struct Redemption.RedemptionRequest) timedOutRedemptions; mapping(uint256 => struct Fraud.FraudChallenge) fraudChallenges; mapping(uint256 => bool) spentMainUTXOs; mapping(bytes20 => struct Wallets.Wallet) registeredWallets; uint256[50] __gap; } ``` ### DepositParametersUpdated ```solidity event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) ``` ### RedemptionParametersUpdated ```solidity event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) ``` ### MovingFundsParametersUpdated ```solidity event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) ``` ### WalletParametersUpdated ```solidity event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) ``` ### FraudParametersUpdated ```solidity event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) ``` ### TreasuryUpdated ```solidity event TreasuryUpdated(address treasury) ``` ### updateDepositParameters ```solidity function updateDepositParameters(struct BridgeState.Storage self, uint64 _depositDustThreshold, uint64 _depositTreasuryFeeDivisor, uint64 _depositTxMaxFee, uint32 _depositRevealAheadPeriod) internal ``` of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the depositor. Requirements: * Deposit dust threshold must be greater than zero, * Deposit dust threshold must be greater than deposit TX max fee, * Deposit transaction max fee must be greater than zero. #### Parameters | Name | Type | Description | | --------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | self | struct BridgeState.Storage | | | \_depositDustThreshold | uint64 | | | \_depositTreasuryFeeDivisor | uint64 | New value of the treasury fee divisor. It is the divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | | \_depositTxMaxFee | uint64 | New value of the deposit tx max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | | \_depositRevealAheadPeriod | uint32 | New value of the deposit reveal ahead period parameter in seconds. It defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. | ### updateRedemptionParameters ```solidity function updateRedemptionParameters(struct BridgeState.Storage self, uint64 _redemptionDustThreshold, uint64 _redemptionTreasuryFeeDivisor, uint64 _redemptionTxMaxFee, uint64 _redemptionTxMaxTotalFee, uint32 _redemptionTimeout, uint96 _redemptionTimeoutSlashingAmount, uint32 _redemptionTimeoutNotifierRewardMultiplier) internal ``` Updates parameters of redemptions. Requirements: * Redemption dust threshold must be greater than moving funds dust threshold, * Redemption dust threshold must be greater than the redemption TX max fee, * Redemption transaction max fee must be greater than zero, * Redemption transaction max total fee must be greater than or equal to the redemption transaction per-request max fee, * Redemption timeout must be greater than zero, * Redemption timeout notifier reward multiplier must be in the range \[0, 100]. #### Parameters | Name | Type | Description | | ------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | self | struct BridgeState.Storage | | | \_redemptionDustThreshold | uint64 | New value of the redemption dust threshold in satoshis. It is the minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | | \_redemptionTreasuryFeeDivisor | uint64 | New value of the redemption treasury fee divisor. It is the divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | | \_redemptionTxMaxFee | uint64 | New value of the redemption transaction max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | | \_redemptionTxMaxTotalFee | uint64 | New value of the redemption transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a *total* max fee for the entire redemption transaction. | | \_redemptionTimeout | uint32 | New value of the redemption timeout in seconds. It is the time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked TBTC is returned to the redeemer in full amount. | | \_redemptionTimeoutSlashingAmount | uint96 | New value of the redemption timeout slashing amount in T, it is the amount slashed from each wallet member for redemption timeout. | | \_redemptionTimeoutNotifierRewardMultiplier | uint32 | New value of the redemption timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a redemption timeout receives. The value must be in the range \[0, 100]. | ### updateMovingFundsParameters ```solidity function updateMovingFundsParameters(struct BridgeState.Storage self, uint64 _movingFundsTxMaxTotalFee, uint64 _movingFundsDustThreshold, uint32 _movingFundsTimeoutResetDelay, uint32 _movingFundsTimeout, uint96 _movingFundsTimeoutSlashingAmount, uint32 _movingFundsTimeoutNotifierRewardMultiplier, uint16 _movingFundsCommitmentGasOffset, uint64 _movedFundsSweepTxMaxTotalFee, uint32 _movedFundsSweepTimeout, uint96 _movedFundsSweepTimeoutSlashingAmount, uint32 _movedFundsSweepTimeoutNotifierRewardMultiplier) internal ``` Updates parameters of moving funds. Requirements: * Moving funds transaction max total fee must be greater than zero, * Moving funds dust threshold must be greater than zero and lower than the redemption dust threshold, * Moving funds timeout reset delay must be greater than zero, * Moving funds timeout must be greater than the moving funds timeout reset delay, * Moving funds timeout notifier reward multiplier must be in the range \[0, 100], * Moved funds sweep transaction max total fee must be greater than zero, * Moved funds sweep timeout must be greater than zero, * Moved funds sweep timeout notifier reward multiplier must be in the range \[0, 100]. #### Parameters | Name | Type | Description | | ------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | self | struct BridgeState.Storage | | | \_movingFundsTxMaxTotalFee | uint64 | New value of the moving funds transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a *total* max fee for the entire moving funds transaction. | | \_movingFundsDustThreshold | uint64 | New value of the moving funds dust threshold. It is the minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | | \_movingFundsTimeoutResetDelay | uint32 | New value of the moving funds timeout reset delay in seconds. It is the time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. | | \_movingFundsTimeout | uint32 | New value of the moving funds timeout in seconds. It is the time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. | | \_movingFundsTimeoutSlashingAmount | uint96 | New value of the moving funds timeout slashing amount in T, it is the amount slashed from each wallet member for moving funds timeout. | | \_movingFundsTimeoutNotifierRewardMultiplier | uint32 | New value of the moving funds timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moving funds timeout receives. The value must be in the range \[0, 100]. | | \_movingFundsCommitmentGasOffset | uint16 | New value of the gas offset for moving funds target wallet commitment transaction gas costs reimbursement. | | \_movedFundsSweepTxMaxTotalFee | uint64 | New value of the moved funds sweep transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a *total* max fee for the entire moved funds sweep transaction. | | \_movedFundsSweepTimeout | uint32 | New value of the moved funds sweep timeout in seconds. It is the time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. | | \_movedFundsSweepTimeoutSlashingAmount | uint96 | New value of the moved funds sweep timeout slashing amount in T, it is the amount slashed from each wallet member for moved funds sweep timeout. | | \_movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New value of the moved funds sweep timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moved funds sweep timeout receives. The value must be in the range \[0, 100]. | ### updateWalletParameters ```solidity function updateWalletParameters(struct BridgeState.Storage self, uint32 _walletCreationPeriod, uint64 _walletCreationMinBtcBalance, uint64 _walletCreationMaxBtcBalance, uint64 _walletClosureMinBtcBalance, uint32 _walletMaxAge, uint64 _walletMaxBtcTransfer, uint32 _walletClosingPeriod) internal ``` Requirements: * Wallet maximum BTC balance must be greater than the wallet minimum BTC balance, * Wallet maximum BTC transfer must be greater than zero, * Wallet closing period must be greater than zero. ### updateFraudParameters ```solidity function updateFraudParameters(struct BridgeState.Storage self, uint96 _fraudChallengeDepositAmount, uint32 _fraudChallengeDefeatTimeout, uint96 _fraudSlashingAmount, uint32 _fraudNotifierRewardMultiplier) internal ``` Updates parameters related to frauds. Requirements: * Fraud challenge defeat timeout must be greater than 0, * Fraud notifier reward multiplier must be in the range \[0, 100]. #### Parameters | Name | Type | Description | | ------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | \_fraudChallengeDepositAmount | uint96 | New value of the fraud challenge deposit amount in wei, it is the amount of ETH the party challenging the wallet for fraud needs to deposit. | | \_fraudChallengeDefeatTimeout | uint32 | New value of the challenge defeat timeout in seconds, it is the amount of time the wallet has to defeat a fraud challenge. The value must be greater than zero. | | \_fraudSlashingAmount | uint96 | New value of the fraud slashing amount in T, it is the amount slashed from each wallet member for committing a fraud. | | \_fraudNotifierRewardMultiplier | uint32 | New value of the fraud notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a fraud receives. The value must be in the range \[0, 100]. | ### updateTreasury ```solidity function updateTreasury(struct BridgeState.Storage self, address _treasury) internal ``` Updates treasury address. The treasury receives the system fees. The treasury address must not be 0x0. #### Parameters | Name | Type | Description | | ---------- | -------------------------- | ---------------------------------- | | self | struct BridgeState.Storage | | | \_treasury | address | New value of the treasury address. | # Deposit ## Deposit The library handles the logic for revealing Bitcoin deposits to the Bridge. The depositor puts together a P2SH or P2WSH address to deposit the funds. This script is unique to each depositor and looks like this: ``` DROP DROP DUP HASH160 EQUAL IF CHECKSIG ELSE DUP HASH160 EQUALVERIFY CHECKLOCKTIMEVERIFY DROP CHECKSIG ENDIF ``` Since each depositor has their own Ethereum address and their own blinding factor, each depositor’s script is unique, and the hash of each depositor’s script is unique. ### DepositRevealInfo ```solidity struct DepositRevealInfo { uint32 fundingOutputIndex; bytes8 blindingFactor; bytes20 walletPubKeyHash; bytes20 refundPubKeyHash; bytes4 refundLocktime; address vault; } ``` ### DepositRequest ```solidity struct DepositRequest { address depositor; uint64 amount; uint32 revealedAt; address vault; uint64 treasuryFee; uint32 sweptAt; } ``` ### DepositRevealed ```solidity event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault) ``` ### revealDeposit ```solidity function revealDeposit(struct BridgeState.Storage self, struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external ``` Used by the depositor to reveal information about their P2(W)SH Bitcoin deposit to the Bridge on Ethereum chain. The off-chain wallet listens for revealed deposit events and may decide to include the revealed deposit in the next executed sweep. Information about the Bitcoin deposit can be revealed before or after the Bitcoin transaction with P2(W)SH deposit is mined on the Bitcoin chain. Worth noting, the gas cost of this function scales with the number of P2(W)SH transaction inputs and outputs. The deposit may be routed to one of the trusted vaults. When a deposit is routed to a vault, vault gets notified when the deposit gets swept and it may execute the appropriate action. Requirements: * This function must be called by the same Ethereum address as the one used in the P2(W)SH BTC deposit transaction as a depositor, * `reveal.walletPubKeyHash` must identify a `Live` wallet, * `reveal.vault` must be 0x0 or point to a trusted vault, * `reveal.fundingOutputIndex` must point to the actual P2(W)SH output of the BTC deposit transaction, * `reveal.blindingFactor` must be the blinding factor used in the P2(W)SH BTC deposit transaction, * `reveal.walletPubKeyHash` must be the wallet pub key hash used in the P2(W)SH BTC deposit transaction, * `reveal.refundPubKeyHash` must be the refund pub key hash used in the P2(W)SH BTC deposit transaction, * `reveal.refundLocktime` must be the refund locktime used in the P2(W)SH BTC deposit transaction, * BTC deposit for the given `fundingTxHash`, `fundingOutputIndex` can be revealed only one time. If any of these requirements is not met, the wallet *must* refuse to sweep the deposit and the depositor has to wait until the deposit script unlocks to receive their BTC back. #### Parameters | Name | Type | Description | | --------- | -------------------------------- | ------------------------------------------------------- | | self | struct BridgeState.Storage | | | fundingTx | struct BitcoinTx.Info | Bitcoin funding transaction data, see `BitcoinTx.Info`. | | reveal | struct Deposit.DepositRevealInfo | Deposit reveal data, see \`RevealInfo struct. | ### validateDepositRefundLocktime ```solidity function validateDepositRefundLocktime(struct BridgeState.Storage self, bytes4 refundLocktime) internal view ``` Validates the deposit refund locktime. The validation passes successfully only if the deposit reveal is done respectively earlier than the moment when the deposit refund locktime is reached, i.e. the deposit become refundable. Reverts otherwise. Requirements: * `refundLocktime` as integer must be >= 500M * `refundLocktime` must denote a timestamp that is at least `depositRevealAheadPeriod` seconds later than the moment of `block.timestamp` #### Parameters | Name | Type | Description | | -------------- | -------------------------- | ----------------------------------------- | | self | struct BridgeState.Storage | | | refundLocktime | bytes4 | The deposit refund locktime as 4-byte LE. | # DepositSweep ## DepositSweep The library handles the logic for sweeping transactions revealed to the Bridge Bridge active wallet periodically signs a transaction that unlocks all of the valid, revealed deposits above the dust threshold, combines them into a single UTXO with the existing main wallet UTXO, and relocks those transactions without a 30-day refund clause to the same wallet. This has two main effects: it consolidates the UTXO set and it disables the refund. Balances of depositors in the Bank are increased when the SPV sweep proof is submitted to the Bridge. ### DepositSweepTxInputsProcessingInfo ```solidity struct DepositSweepTxInputsProcessingInfo { bytes sweepTxInputVector; struct BitcoinTx.UTXO mainUtxo; address vault; } ``` ### DepositSweepTxInputsInfo ```solidity struct DepositSweepTxInputsInfo { uint256 inputsTotalValue; address[] depositors; uint256[] depositedAmounts; uint256[] treasuryFees; } ``` ### DepositsSwept ```solidity event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) ``` ### submitDepositSweepProof ```solidity function submitDepositSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external ``` Used by the wallet to prove the BTC deposit sweep transaction and to update Bank balances accordingly. Sweep is only accepted if it satisfies SPV proof. The function is performing Bank balance updates by first computing the Bitcoin fee for the sweep transaction. The fee is divided evenly between all swept deposits. Each depositor receives a balance in the bank equal to the amount inferred during the reveal transaction, minus their fee share. It is possible to prove the given sweep only one time. Requirements: * `sweepTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `sweepTx` should represent a Bitcoin transaction with 1..n inputs. If the wallet has no main UTXO, all n inputs should correspond to P2(W)SH revealed deposits UTXOs. If the wallet has an existing main UTXO, one of the n inputs must point to that main UTXO and remaining n-1 inputs should correspond to P2(W)SH revealed deposits UTXOs. That transaction must have only one P2(W)PKH output locking funds on the 20-byte wallet public key hash, * All revealed deposits that are swept by `sweepTx` must have their `vault` parameters set to the same address as the address passed in the `vault` function parameter, * `sweepProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If there is no main UTXO, this parameter is ignored. #### Parameters | Name | Type | Description | | ---------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | sweepTx | struct BitcoinTx.Info | Bitcoin sweep transaction data. | | sweepProof | struct BitcoinTx.Proof | Bitcoin sweep proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | | vault | address | Optional address of the vault where all swept deposits should be routed to. All deposits swept as part of the transaction must have their `vault` parameters set to the same address. If this parameter is set to an address of a trusted vault, swept deposits are routed to that vault. If this parameter is set to the zero address or to an address of a non-trusted vault, swept deposits are not routed to a vault but depositors' balances are increased in the Bank individually. | ### resolveDepositSweepingWallet ```solidity function resolveDepositSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo) ``` Resolves sweeping wallet based on the provided wallet public key hash. Validates the wallet state and current main UTXO, as currently known on the Ethereum chain. Requirements: * Sweeping wallet must be either in Live or MovingFunds state, * If the main UTXO of the sweeping wallet exists in the storage, the passed `mainUTXO` parameter must be equal to the stored one. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | #### Return Values | Name | Type | Description | | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | wallet | struct Wallets.Wallet | Data of the sweeping wallet. | | resolvedMainUtxo | struct BitcoinTx.UTXO | The actual main UTXO of the sweeping wallet resolved by cross-checking the `mainUtxo` parameter with the chain state. If the validation went well, this is the plain-text main UTXO corresponding to the `wallet.mainUtxoHash`. | ### processDepositSweepTxOutput ```solidity function processDepositSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value) ``` Processes the Bitcoin sweep transaction output vector by extracting the single output and using it to gain additional information required for further processing (e.g. value and wallet public key hash). #### Parameters | Name | Type | Description | | ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | sweepTxOutputVector | bytes | Bitcoin sweep transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | #### Return Values | Name | Type | Description | | ---------------- | ------- | -------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte wallet public key hash. | | value | uint64 | 8-byte sweep transaction output value. | ### processDepositSweepTxInputs ```solidity function processDepositSweepTxInputs(struct BridgeState.Storage self, struct DepositSweep.DepositSweepTxInputsProcessingInfo processInfo) internal returns (struct DepositSweep.DepositSweepTxInputsInfo resultInfo) ``` Processes the Bitcoin sweep transaction input vector. It extracts each input and tries to obtain associated deposit or main UTXO data, depending on the input type. Reverts if one of the inputs cannot be recognized as a pointer to a revealed deposit or expected main UTXO. This function also marks each processed deposit as swept. #### Return Values | Name | Type | Description | | ---------- | -------------------------------------------- | --------------------------- | | resultInfo | struct DepositSweep.DepositSweepTxInputsInfo | Outcomes of the processing. | ### parseDepositSweepTxInputAt ```solidity function parseDepositSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength) ``` Parses a Bitcoin transaction input starting at the given index. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. #### Parameters | Name | Type | Description | | ------------------ | ------- | --------------------------------- | | inputVector | bytes | Bitcoin transaction input vector. | | inputStartingIndex | uint256 | Index the given input starts at. | #### Return Values | Name | Type | Description | | -------------- | ------- | ---------------------------------------------------------------------------------------------- | | outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the given input's outpoint. | | outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the given input's outpoint. | | inputLength | uint256 | Byte length of the given input. | ### depositSweepTxFeeDistribution ```solidity function depositSweepTxFeeDistribution(uint256 sweepTxInputsTotalValue, uint256 sweepTxOutputValue, uint256 depositsCount) internal pure returns (uint256 depositTxFee, uint256 depositTxFeeRemainder) ``` Determines the distribution of the sweep transaction fee over swept deposits. It is up to the caller to decide how the remainder should be counted in. This function only computes its value. #### Parameters | Name | Type | Description | | ----------------------- | ------- | ----------------------------------------------------- | | sweepTxInputsTotalValue | uint256 | Total value of all sweep transaction inputs. | | sweepTxOutputValue | uint256 | Value of the sweep transaction output. | | depositsCount | uint256 | Count of the deposits swept by the sweep transaction. | #### Return Values | Name | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | depositTxFee | uint256 | Transaction fee per deposit determined by evenly spreading the divisible part of the sweep transaction fee over all deposits. | | depositTxFeeRemainder | uint256 | The indivisible part of the sweep transaction fee than cannot be distributed over all deposits. | # DonationVault ## DonationVault Vault that allows making BTC donations to the system. Upon deposit, this vault does not increase depositors' balances and always decreases its own balance in the same transaction. The vault also allows making donations using existing Bank balances. BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE. USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING! ### bank ```solidity contract Bank bank ``` ### DonationReceived ```solidity event DonationReceived(address donor, uint256 donatedAmount) ``` ### onlyBank ```solidity modifier onlyBank() ``` ### constructor ```solidity constructor(contract Bank _bank) public ``` ### donate ```solidity function donate(uint256 amount) external ``` Transfers the given `amount` of the Bank balance from the caller to the Donation Vault and immediately decreases the vault's balance in the Bank by the transferred `amount`. Requirements: * The caller's balance in the Bank must be greater than or equal to the `amount`, * Donation Vault must have an allowance for caller's balance in the Bank for at least `amount`. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------- | | amount | uint256 | Amount of the Bank balance to donate. | ### receiveBalanceApproval ```solidity function receiveBalanceApproval(address owner, uint256 amount, bytes) external ``` Transfers the given `amount` of the Bank balance from the `owner` to the Donation Vault and immediately decreases the vault's balance in the Bank by the transferred `amount`. Requirements: * Can only be called by the Bank via `approveBalanceAndCall`, * The `owner` balance in the Bank must be greater than or equal to the `amount`. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------------------------------------------------------- | | owner | address | Address of the Bank balance owner who approved their balance to be used by the vault. | | amount | uint256 | The amount of the Bank balance approved by the owner to be used by the vault. | | | bytes | | ### receiveBalanceIncrease ```solidity function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external ``` Ignores the deposited amounts and does not increase depositors' individual balances. The vault decreases its own tBTC balance in the Bank by the total deposited amount. Requirements: * Can only be called by the Bank after the Bridge swept deposits and Bank increased balance for the vault, * The `depositors` array must not be empty, * The `depositors` array length must be equal to the `depositedAmounts` array length. #### Parameters | Name | Type | Description | | ---------------- | ---------- | ------------------------------------------------------- | | depositors | address\[] | Addresses of depositors whose deposits have been swept. | | depositedAmounts | uint256\[] | Amounts deposited by individual depositors and swept. | # EcdsaLib ## EcdsaLib ### compressPublicKey ```solidity function compressPublicKey(bytes32 x, bytes32 y) internal pure returns (bytes) ``` Converts public key X and Y coordinates (32-byte each) to a compressed public key (33-byte). Compressed public key is X coordinate prefixed with `02` or `03` based on the Y coordinate parity. It is expected that the uncompressed public key is stripped (i.e. it is not prefixed with `04`). #### Parameters | Name | Type | Description | | ---- | ------- | ----------------------------------- | | x | bytes32 | Wallet's public key's X coordinate. | | y | bytes32 | Wallet's public key's Y coordinate. | #### Return Values | Name | Type | Description | | ---- | ----- | ------------------------------------------------------------ | | \[0] | bytes | Compressed public key (33-byte), prefixed with `02` or `03`. | # Fraud ## Fraud The library handles the logic for challenging Bridge wallets that committed fraud. Anyone can submit a fraud challenge indicating that a UTXO being under the wallet control was unlocked by the wallet but was not used according to the protocol rules. That means the wallet signed a transaction input pointing to that UTXO and there is a unique sighash and signature pair associated with that input. In order to defeat the challenge, the same wallet public key and signature must be provided as were used to calculate the sighash during the challenge. The wallet provides the preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. The fraud challenge defeat attempt will succeed if the inputs in the preimage are considered honestly spent by the wallet. Therefore the transaction spending the UTXO must be proven in the Bridge before a challenge defeat is called. Another option is when a malicious wallet member used a signed heartbeat message periodically produced by the wallet off-chain to challenge the wallet for a fraud. Anyone from the wallet can defeat the challenge by proving the sighash and signature were produced for a heartbeat message following a strict format. ### FraudChallenge ```solidity struct FraudChallenge { address challenger; uint256 depositAmount; uint32 reportedAt; bool resolved; } ``` ### FraudChallengeSubmitted ```solidity event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s) ``` ### FraudChallengeDefeated ```solidity event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash) ``` ### FraudChallengeDefeatTimedOut ```solidity event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash) ``` ### submitFraudChallenge ```solidity function submitFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external ``` Submits a fraud challenge indicating that a UTXO being under wallet control was unlocked by the wallet but was not used according to the protocol rules. That means the wallet signed a transaction input pointing to that UTXO and there is a unique sighash and signature pair associated with that input. This function uses those parameters to create a fraud accusation that proves a given transaction input unlocking the given UTXO was actually signed by the wallet. This function cannot determine whether the transaction was actually broadcast and the input was consumed in a fraudulent way so it just opens a challenge period during which the wallet can defeat the challenge by submitting proof of a transaction that consumes the given input according to protocol rules. To prevent spurious allegations, the caller must deposit ETH that is returned back upon justified fraud challenge or confiscated otherwise. Requirements: * Wallet behind `walletPublicKey` must be in Live or MovingFunds or Closing state, * The challenger must send appropriate amount of ETH used as fraud challenge deposit, * The signature (represented by r, s and v) must be generated by the wallet behind `walletPubKey` during signing of `sighash` which was calculated from `preimageSha256`, * Wallet can be challenged for the given signature only once. #### Parameters | Name | Type | Description | | --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | | signature | struct BitcoinTx.RSVSignature | Bitcoin signature in the R/S/V format | ### defeatFraudChallenge ```solidity function defeatFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimage, bool witness) external ``` Allows to defeat a pending fraud challenge against a wallet if the transaction that spends the UTXO follows the protocol rules. In order to defeat the challenge the same `walletPublicKey` and signature (represented by `r`, `s` and `v`) must be provided as were used to calculate the sighash during input signing. The fraud challenge defeat attempt will only succeed if the inputs in the preimage are considered honestly spent by the wallet. Therefore the transaction spending the UTXO must be proven in the Bridge before a challenge defeat is called. If successfully defeated, the fraud challenge is marked as resolved and the amount of ether deposited by the challenger is sent to the treasury. Requirements: * `walletPublicKey` and `sighash` calculated as `hash256(preimage)` must identify an open fraud challenge, * the preimage must be a valid preimage of a transaction generated according to the protocol rules and already proved in the Bridge, * before a defeat attempt is made the transaction that spends the given UTXO must be proven in the Bridge. #### Parameters | Name | Type | Description | | --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | | witness | bool | Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input. | ### defeatFraudChallengeWithHeartbeat ```solidity function defeatFraudChallengeWithHeartbeat(struct BridgeState.Storage self, bytes walletPublicKey, bytes heartbeatMessage) external ``` Allows to defeat a pending fraud challenge against a wallet by proving the sighash and signature were produced for an off-chain wallet heartbeat message following a strict format. In order to defeat the challenge the same `walletPublicKey` and signature (represented by `r`, `s` and `v`) must be provided as were used to calculate the sighash during heartbeat message signing. The fraud challenge defeat attempt will only succeed if the signed message follows a strict format required for heartbeat messages. If successfully defeated, the fraud challenge is marked as resolved and the amount of ether deposited by the challenger is sent to the treasury. Requirements: * `walletPublicKey` and `sighash` calculated as `hash256(heartbeatMessage)` must identify an open fraud challenge, * `heartbeatMessage` must follow a strict format of heartbeat messages. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes), | | heartbeatMessage | bytes | Off-chain heartbeat message meeting the heartbeat message format requirements which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. | ### resolveFraudChallenge ```solidity function resolveFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, struct Fraud.FraudChallenge challenge, bytes32 sighash) internal ``` Called only for successfully defeated fraud challenges. The fraud challenge is marked as resolved and the amount of ether deposited by the challenger is sent to the treasury. Requirements: * Must be called only for successfully defeated fraud challenges. ### notifyFraudChallengeDefeatTimeout ```solidity function notifyFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) external ``` Notifies about defeat timeout for the given fraud challenge. Can be called only if there was a fraud challenge identified by the provided `walletPublicKey` and `sighash` and it was not defeated on time. The amount of time that needs to pass after a fraud challenge is reported is indicated by the `challengeDefeatTimeout`. After a successful fraud challenge defeat timeout notification the fraud challenge is marked as resolved, the stake of each operator is slashed, the ether deposited is returned to the challenger and the challenger is rewarded. Requirements: * The wallet must be in the Live or MovingFunds or Closing or Terminated state, * The `walletPublicKey` and `sighash` calculated from `preimageSha256` must identify an open fraud challenge, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract, * The amount of time indicated by `challengeDefeatTimeout` must pass after the challenge was reported. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | | preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | ### extractUtxoKeyFromWitnessPreimage ```solidity function extractUtxoKeyFromWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey) ``` Extracts the UTXO keys from the given preimage used during signing of a witness input. #### Parameters | Name | Type | Description | | -------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference | #### Return Values | Name | Type | Description | | ------- | ------- | ------------------------------------- | | utxoKey | uint256 | UTXO key that identifies spent input. | ### extractUtxoKeyFromNonWitnessPreimage ```solidity function extractUtxoKeyFromNonWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey) ``` Extracts the UTXO key from the given preimage used during signing of a non-witness input. #### Parameters | Name | Type | Description | | -------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | #### Return Values | Name | Type | Description | | ------- | ------- | ------------------------------------- | | utxoKey | uint256 | UTXO key that identifies spent input. | ### extractSighashType ```solidity function extractSighashType(bytes preimage) internal pure returns (uint32 sighashType) ``` Extracts the sighash type from the given preimage. Sighash type is stored as the last 4 bytes in the preimage (little endian). #### Parameters | Name | Type | Description | | -------- | ----- | ---------------------------------------------------------------- | | preimage | bytes | Serialized subset of the transaction. See BIP-143 for reference. | #### Return Values | Name | Type | Description | | ----------- | ------ | --------------------------------- | | sighashType | uint32 | Sighash type as a 32-bit integer. | # GovernanceUtils ## GovernanceUtils ### onlyAfterGovernanceDelay ```solidity function onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view ``` Reverts if the governance delay has not passed since the change initiated time or if the change has not been initiated. #### Parameters | Name | Type | Description | | ------------------------ | ------- | ----------------------------------------------------- | | changeInitiatedTimestamp | uint256 | The timestamp at which the change has been initiated. | | delay | uint256 | Governance delay. | ### getRemainingGovernanceDelay ```solidity function getRemainingGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view returns (uint256) ``` Gets the time remaining until the governable parameter update can be committed. #### Parameters | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------- | | changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | | delay | uint256 | Governance delay. | #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | # Heartbeat ## Heartbeat The library establishes expected format for heartbeat messages signed by wallet ECDSA signing group. Heartbeat messages are constructed in such a way that they can not be used as a Bitcoin transaction preimages. The smallest Bitcoin non-coinbase transaction is a one spending an OP\_TRUE anyonecanspend output and creating 1 OP\_TRUE anyonecanspend output. Such a transaction has 61 bytes (see `BitcoinTx` documentation): 4 bytes for version 1 byte for tx\_in\_count 36 bytes for tx\_in.previous\_output 1 byte for tx\_in.script\_bytes (value: 0) 0 bytes for tx\_in.signature\_script 4 bytes for tx\_in.sequence 1 byte for tx\_out\_count 8 bytes for tx\_out.value 1 byte for tx\_out.pk\_script\_bytes 1 byte for tx\_out.pk\_script 4 bytes for lock\_time The smallest Bitcoin coinbase transaction is a one creating 1 OP\_TRUE anyonecanspend output and having an empty coinbase script. Such a transaction has 65 bytes: 4 bytes for version 1 byte for tx\_in\_count 32 bytes for tx\_in.hash (all 0x00) 4 bytes for tx\_in.index (all 0xff) 1 byte for tx\_in.script\_bytes (value: 0) 4 bytes for tx\_in.height 0 byte for tx\_in.coinbase\_script 4 bytes for tx\_in.sequence 1 byte for tx\_out\_count 8 bytes for tx\_out.value 1 byte for tx\_out.pk\_script\_bytes 1 byte for tx\_out.pk\_script 4 bytes for lock\_time A SIGHASH flag is used to indicate which part of the transaction is signed by the ECDSA signature. There are currently 3 flags: SIGHASH\_ALL, SIGHASH\_NONE, SIGHASH\_SINGLE, and different combinations of these flags. No matter the SIGHASH flag and no matter the combination, the following fields from the transaction are always included in the constructed preimage: 4 bytes for version 36 bytes for tx\_in.previous\_output (or tx\_in.hash + tx\_in.index for coinbase) 4 bytes for lock\_time Additionally, the last 4 bytes of the preimage determines the SIGHASH flag. This is enough to say there is no way the preimage could be shorter than 4 + 36 + 4 + 4 = 48 bytes. For this reason, we construct the heartbeat message, as a 16-byte message. The first 8 bytes are 0xffffffffffffffff. The last 8 bytes are for an arbitrary uint64, being a signed heartbeat nonce (for example, the last Ethereum block hash). The message being signed by the wallet when executing the heartbeat protocol should be Bitcoin's hash256 (double SHA-256) of the heartbeat message: heartbeat\_sighash = hash256(heartbeat\_message) ### isValidHeartbeatMessage ```solidity function isValidHeartbeatMessage(bytes message) internal pure returns (bool) ``` Determines if the signed byte array is a valid, non-fraudulent heartbeat message. Wallet heartbeat message must be exactly 16 bytes long with the first 8 bytes set to 0xffffffffffffffff. #### Parameters | Name | Type | Description | | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------ | | message | bytes | Message signed by the wallet. It is a potential heartbeat message, Bitcoin transaction preimage, or an arbitrary signed bytes. | #### Return Values | Name | Type | Description | | ---- | ---- | ------------------------------------------------- | | \[0] | bool | True if valid heartbeat message, false otherwise. | # IReceiveBalanceApproval ## IReceiveBalanceApproval `IReceiveBalanceApproval` is an interface for a smart contract consuming Bank balances approved to them in the same transaction by other contracts or externally owned accounts (EOA). ### receiveBalanceApproval ```solidity function receiveBalanceApproval(address owner, uint256 amount, bytes extraData) external ``` Called by the Bank in `approveBalanceAndCall` function after the balance `owner` approved `amount` of their balance in the Bank for the contract. This way, the depositor can approve balance and call the contract to use the approved balance in a single transaction. The implementation must ensure this function can only be called by the Bank. The Bank does *not* guarantee that the `amount` approved by the `owner` currently exists on their balance. That is, the `owner` could approve more balance than they currently have. This works the same as `Bank.approve` function. The contract must ensure the actual balance is checked before performing any action based on it. #### Parameters | Name | Type | Description | | --------- | ------- | ---------------------------------------------------------------------------------------- | | owner | address | Address of the Bank balance owner who approved their balance to be used by the contract. | | amount | uint256 | The amount of the Bank balance approved by the owner to be used by the contract. | | extraData | bytes | The `extraData` passed to `Bank.approveBalanceAndCall`. | # IRelay ## IRelay Contains only the methods needed by tBTC v2. The Bitcoin relay provides the difficulty of the previous and current epoch. One difficulty epoch spans 2016 blocks. ### getCurrentEpochDifficulty ```solidity function getCurrentEpochDifficulty() external view returns (uint256) ``` Returns the difficulty of the current epoch. ### getPrevEpochDifficulty ```solidity function getPrevEpochDifficulty() external view returns (uint256) ``` Returns the difficulty of the previous epoch. # IVault ## IVault `IVault` is an interface for a smart contract consuming Bank balances of other contracts or externally owned accounts (EOA). ### receiveBalanceIncrease ```solidity function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external ``` Called by the Bank in `increaseBalanceAndCall` function after increasing the balance in the Bank for the vault. It happens in the same transaction in which deposits were swept by the Bridge. This allows the depositor to route their deposit revealed to the Bridge to the particular smart contract (vault) in the same transaction in which the deposit is revealed. This way, the depositor does not have to execute additional transaction after the deposit gets swept by the Bridge to approve and transfer their balance to the vault. The implementation must ensure this function can only be called by the Bank. The Bank guarantees that the vault's balance was increased by the sum of all deposited amounts before this function is called, in the same transaction. #### Parameters | Name | Type | Description | | ---------------- | ---------- | ------------------------------------------------------- | | depositors | address\[] | Addresses of depositors whose deposits have been swept. | | depositedAmounts | uint256\[] | Amounts deposited by individual depositors and swept. | # L2TBTC ## L2TBTC Canonical L2/sidechain token implementation. tBTC token is minted on L1 and locked there to be moved to L2/sidechain. By deploying a canonical token on each L2/sidechain, we can ensure the supply of tBTC remains sacrosanct, while enabling quick, interoperable cross-chain bridges and localizing ecosystem risk. This contract is flexible enough to: * Delegate minting authority to a native bridge on the chain, if present. * Delegate minting authority to a short list of ecosystem bridges. * Have mints and burns paused by any one of n guardians, allowing avoidance of contagion in case of a chain- or bridge-specific incident. * Be governed and upgradeable. The token is burnable by the token holder and supports EIP2612 permits. Token holder can authorize a transfer of their token with a signature conforming EIP712 standard instead of an on-chain transaction from their address. Anyone can submit this signature on the user's behalf by calling the permit function, paying gas fees, and possibly performing other actions in the same transaction. The governance can recover ERC20 and ERC721 tokens sent mistakenly to L2TBTC token contract. ### isMinter ```solidity mapping(address => bool) isMinter ``` Indicates if the given address is a minter. Only minters can mint the token. ### minters ```solidity address[] minters ``` List of all minters. ### isGuardian ```solidity mapping(address => bool) isGuardian ``` Indicates if the given address is a guardian. Only guardians can pause token mints and burns. ### guardians ```solidity address[] guardians ``` List of all guardians. ### MinterAdded ```solidity event MinterAdded(address minter) ``` ### MinterRemoved ```solidity event MinterRemoved(address minter) ``` ### GuardianAdded ```solidity event GuardianAdded(address guardian) ``` ### GuardianRemoved ```solidity event GuardianRemoved(address guardian) ``` ### onlyMinter ```solidity modifier onlyMinter() ``` ### onlyGuardian ```solidity modifier onlyGuardian() ``` ### initialize ```solidity function initialize(string _name, string _symbol) external ``` Initializes the token contract. #### Parameters | Name | Type | Description | | -------- | ------ | --------------------------------------------------------------- | | \_name | string | The name of the token. | | \_symbol | string | The symbol of the token, usually a shorter version of the name. | ### addMinter ```solidity function addMinter(address minter) external ``` Adds the address to the minters list. Requirements: * The caller must be the contract owner. * `minter` must not be a minter address already. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------ | | minter | address | The address to be added as a minter. | ### removeMinter ```solidity function removeMinter(address minter) external ``` Removes the address from the minters list. Requirements: * The caller must be the contract owner. * `minter` must be a minter address. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------------------------------ | | minter | address | The address to be removed from the minters list. | ### addGuardian ```solidity function addGuardian(address guardian) external ``` Adds the address to the guardians list. Requirements: * The caller must be the contract owner. * `guardian` must not be a guardian address already. #### Parameters | Name | Type | Description | | -------- | ------- | -------------------------------------- | | guardian | address | The address to be added as a guardian. | ### removeGuardian ```solidity function removeGuardian(address guardian) external ``` Removes the address from the guardians list. Requirements: * The caller must be the contract owner. * `guardian` must be a guardian address. #### Parameters | Name | Type | Description | | -------- | ------- | -------------------------------------------------- | | guardian | address | The address to be removed from the guardians list. | ### recoverERC20 ```solidity function recoverERC20(contract IERC20Upgradeable token, address recipient, uint256 amount) external ``` Allows the governance of the token contract to recover any ERC20 sent mistakenly to the token contract address. #### Parameters | Name | Type | Description | | --------- | -------------------------- | --------------------------------------------------------------- | | token | contract IERC20Upgradeable | The address of the token to be recovered. | | recipient | address | The token recipient address that will receive recovered tokens. | | amount | uint256 | The amount to be recovered. | ### recoverERC721 ```solidity function recoverERC721(contract IERC721Upgradeable token, address recipient, uint256 tokenId, bytes data) external ``` Allows the governance of the token contract to recover any ERC721 sent mistakenly to the token contract address. #### Parameters | Name | Type | Description | | --------- | --------------------------- | ------------------------------------------------------------------ | | token | contract IERC721Upgradeable | The address of the token to be recovered. | | recipient | address | The token recipient address that will receive the recovered token. | | tokenId | uint256 | The ID of the ERC721 token to be recovered. | | data | bytes | | ### pause ```solidity function pause() external ``` Allows one of the guardians to pause mints and burns allowing avoidance of contagion in case of a chain- or bridge-specific incident. Requirements: * The caller must be a guardian. * The contract must not be already paused. ### unpause ```solidity function unpause() external ``` Allows the governance to unpause mints and burns previously paused by one of the guardians. Requirements: * The caller must be the contract owner. * The contract must be paused. ### mint ```solidity function mint(address account, uint256 amount) external ``` Allows one of the minters to mint `amount` tokens and assign them to `account`, increasing the total supply. Emits a `Transfer` event with `from` set to the zero address. Requirements: * The caller must be a minter. * `account` must not be the zero address. #### Parameters | Name | Type | Description | | ------- | ------- | --------------------------------- | | account | address | The address to receive tokens. | | amount | uint256 | The amount of token to be minted. | ### burn ```solidity function burn(uint256 amount) public ``` Destroys `amount` tokens from the caller. Emits a `Transfer` event with `to` set to the zero address. Requirements: * The caller must have at least `amount` tokens. #### Parameters | Name | Type | Description | | ------ | ------- | --------------------------------- | | amount | uint256 | The amount of token to be burned. | ### burnFrom ```solidity function burnFrom(address account, uint256 amount) public ``` Destroys `amount` tokens from `account`, deducting from the caller's allowance. Emits a `Transfer` event with `to` set to the zero address. Requirements: * The che caller must have allowance for `accounts`'s tokens of at least `amount`. * `account` must not be the zero address. * `account` must have at least `amount` tokens. #### Parameters | Name | Type | Description | | ------- | ------- | --------------------------------------- | | account | address | The address owning tokens to be burned. | | amount | uint256 | The amount of token to be burned. | ### getMinters ```solidity function getMinters() external view returns (address[]) ``` Allows to fetch a list of all minters. ### getGuardians ```solidity function getGuardians() external view returns (address[]) ``` Allows to fetch a list of all guardians. # L2WormholeGateway ## IWormholeTokenBridge Wormhole Token Bridge interface. Contains only selected functions used by L2WormholeGateway. ### completeTransferWithPayload ```solidity function completeTransferWithPayload(bytes encodedVm) external returns (bytes) ``` ### parseTransferWithPayload ```solidity function parseTransferWithPayload(bytes encoded) external pure returns (struct IWormholeTokenBridge.TransferWithPayload transfer) ``` ### transferTokens ```solidity function transferTokens(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64 sequence) ``` ### transferTokensWithPayload ```solidity function transferTokensWithPayload(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint32 nonce, bytes payload) external payable returns (uint64 sequence) ``` ### TransferWithPayload ```solidity struct TransferWithPayload { uint8 payloadID; uint256 amount; bytes32 tokenAddress; uint16 tokenChain; bytes32 to; uint16 toChain; bytes32 fromAddress; bytes payload; } ``` ## L2WormholeGateway Selected cross-ecosystem bridges are given the minting authority for tBTC token on L2 and sidechains. This contract gives a minting authority to the Wormhole Bridge. The process of bridging from L1 to L2 (or sidechain) looks as follows: 1. There is a tBTC holder on L1. The holder goes to the Wormhole Portal and selects the chain they want to bridge to. 2. The holder submits one transaction to L1 locking their tBTC tokens in the bridge’s smart contract. After the transaction is mined, they wait about 15 minutes for the Ethereum block finality. 3. The holder submits one transaction to L2 that is minting tokens. After that transaction is mined, they have their tBTC on L2. The process of bridging from L2 (or sidechain) to L1 looks as follows: 1. There is a tBTC holder on L2. That holder goes to the Wormhole Portal and selects one of the L2 chains they want to bridge from. 2. The holder submits one transaction to L2 that is burning the token. After the transaction is mined, they wait about 15 minutes for the L2 block finality. 3. The holder submits one transaction to L1 unlocking their tBTC tokens from the bridge’s smart contract. After that transaction is mined, they have their tBTC on L1. This smart contract is integrated with step 3 of L1->L2 bridging and step 1 of L2->L1 or L2->L2 bridging. When the user redeems token on L2, this contract receives the Wormhole tBTC representation and mints the canonical tBTC in an equal amount. When user sends their token from L1, this contract burns the canonical tBTC and sends Wormhole tBTC representation through the bridge in an equal amount. This contract is supposed to be deployed behind a transparent upgradeable proxy. ### bridge ```solidity contract IWormholeTokenBridge bridge ``` Reference to the Wormhole Token Bridge contract. ### bridgeToken ```solidity contract IERC20Upgradeable bridgeToken ``` Wormhole tBTC token representation. ### tbtc ```solidity contract L2TBTC tbtc ``` Canonical tBTC token. ### gateways ```solidity mapping(uint16 => bytes32) gateways ``` Maps Wormhole chain ID to the Wormhole tBTC gateway address on that chain. For example, this chain's ID should be mapped to this contract's address. If there is no Wormhole tBTC gateway address on the given chain, there is no entry in this mapping. The mapping holds addresses in a Wormhole-specific format, where Ethereum address is left-padded with zeros. ### mintingLimit ```solidity uint256 mintingLimit ``` Minting limit for this gateway. Useful for early days of testing the system. The gateway can not mint more canonical tBTC than this limit. ### mintedAmount ```solidity uint256 mintedAmount ``` The amount of tBTC minted by this contract. tBTC burned by this contract decreases this amount. ### WormholeTbtcReceived ```solidity event WormholeTbtcReceived(address receiver, uint256 amount) ``` ### WormholeTbtcSent ```solidity event WormholeTbtcSent(uint256 amount, uint16 recipientChain, bytes32 gateway, bytes32 recipient, uint256 arbiterFee, uint32 nonce) ``` ### WormholeTbtcDeposited ```solidity event WormholeTbtcDeposited(address depositor, uint256 amount) ``` ### GatewayAddressUpdated ```solidity event GatewayAddressUpdated(uint16 chainId, bytes32 gateway) ``` ### MintingLimitUpdated ```solidity event MintingLimitUpdated(uint256 mintingLimit) ``` ### initialize ```solidity function initialize(contract IWormholeTokenBridge _bridge, contract IERC20Upgradeable _bridgeToken, contract L2TBTC _tbtc) external ``` ### sendTbtc ```solidity function sendTbtc(uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64) ``` This function is called when the user sends their token from L2. The contract burns the canonical tBTC from the user and sends wormhole tBTC representation over the bridge. Keep in mind that when multiple bridges receive a minting authority on the canonical tBTC, this function may not be able to send all amounts of tBTC through the Wormhole bridge. The capability of Wormhole Bridge to send tBTC from the chain is limited to the amount of tBTC bridged through Wormhole to that chain. Requirements: * The sender must have at least `amount` of the canonical tBTC and it has to be approved for L2WormholeGateway. * The L2WormholeGateway must have at least `amount` of the wormhole tBTC. * The recipient must not be 0x0. * The amount to transfer must not be 0, * The amount to transfer must be >= 10^10 (1e18 precision). Depending if Wormhole tBTC gateway is registered on the target chain, this function uses transfer or transfer with payload over the Wormhole bridge. #### Parameters | Name | Type | Description | | -------------- | ------- | -------------------------------------------------------------------------------------- | | amount | uint256 | The amount of tBTC to be sent. | | recipientChain | uint16 | The Wormhole recipient chain ID. | | recipient | bytes32 | The address of the recipient in the Wormhole format. | | arbiterFee | uint256 | The Wormhole arbiter fee. Ignored if sending tBTC to chain with Wormhole tBTC gateway. | | nonce | uint32 | The Wormhole nonce used to batch messages together. | #### Return Values | Name | Type | Description | | ---- | ------ | ----------------------------- | | \[0] | uint64 | The Wormhole sequence number. | ### receiveTbtc ```solidity function receiveTbtc(bytes encodedVm) external ``` This function is called when the user redeems their token on L2. The contract receives Wormhole tBTC representation and mints the canonical tBTC for the user. If the tBTC minting limit has been reached by this contract, instead of minting tBTC the receiver address receives Wormhole tBTC representation. Requirements: * The receiver of Wormhole tBTC should be the L2WormholeGateway contract. * The receiver of the canonical tBTC should be abi-encoded in the payload. * The receiver of the canonical tBTC must not be the zero address. The Wormhole Token Bridge contract has protection against redeeming the same VAA again. When a Token Bridge VAA is redeemed, its message body hash is stored in a map. This map is used to check whether the hash has already been set in this map. For this reason, this function does not have to be nonReentrant. #### Parameters | Name | Type | Description | | --------- | ----- | --------------------------------------------------------------- | | encodedVm | bytes | A byte array containing a Wormhole VAA signed by the guardians. | ### depositWormholeTbtc ```solidity function depositWormholeTbtc(uint256 amount) external ``` Allows to deposit Wormhole tBTC token in exchange for canonical tBTC. Useful in a situation when user received wormhole tBTC instead of canonical tBTC. One example of such situation is when the minting limit was exceeded but the user minted anyway. Requirements: * The sender must have at least `amount` of the Wormhole tBTC and it has to be approved for L2WormholeGateway. * The minting limit must allow for minting the given amount. #### Parameters | Name | Type | Description | | ------ | ------- | --------------------------------------- | | amount | uint256 | The amount of Wormhole tBTC to deposit. | ### updateGatewayAddress ```solidity function updateGatewayAddress(uint16 chainId, bytes32 gateway) external ``` Lets the governance to update the tBTC gateway address on the chain with the given Wormhole ID. Use toWormholeAddress function to convert between Ethereum and Wormhole address formats. #### Parameters | Name | Type | Description | | ------- | ------- | ---------------------------------------------------------------- | | chainId | uint16 | Wormhole ID of the chain. | | gateway | bytes32 | Address of tBTC gateway on the given chain in a Wormhole format. | ### updateMintingLimit ```solidity function updateMintingLimit(uint256 _mintingLimit) external ``` Lets the governance to update the tBTC minting limit for this contract. #### Parameters | Name | Type | Description | | -------------- | ------- | ---------------------- | | \_mintingLimit | uint256 | The new minting limit. | ### toWormholeAddress ```solidity function toWormholeAddress(address _address) external pure returns (bytes32) ``` Converts Ethereum address into Wormhole format. #### Parameters | Name | Type | Description | | --------- | ------- | ----------------------- | | \_address | address | The address to convert. | ### fromWormholeAddress ```solidity function fromWormholeAddress(bytes32 _address) public pure returns (address) ``` Converts Wormhole address into Ethereum format. #### Parameters | Name | Type | Description | | --------- | ------- | ----------------------- | | \_address | bytes32 | The address to convert. | ### normalize ```solidity function normalize(uint256 amount) internal pure returns (uint256) ``` Eliminates the dust that cannot be bridged with Wormhole due to the decimal shift in the Wormhole Bridge contract. See # LightRelay ## Epoch ```solidity struct Epoch { uint32 timestamp; uint224 target; } ``` ## ILightRelay ### Genesis ```solidity event Genesis(uint256 blockHeight) ``` ### Retarget ```solidity event Retarget(uint256 oldDifficulty, uint256 newDifficulty) ``` ### ProofLengthChanged ```solidity event ProofLengthChanged(uint256 newLength) ``` ### AuthorizationRequirementChanged ```solidity event AuthorizationRequirementChanged(bool newStatus) ``` ### SubmitterAuthorized ```solidity event SubmitterAuthorized(address submitter) ``` ### SubmitterDeauthorized ```solidity event SubmitterDeauthorized(address submitter) ``` ### retarget ```solidity function retarget(bytes headers) external ``` ### validateChain ```solidity function validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount) ``` ### getBlockDifficulty ```solidity function getBlockDifficulty(uint256 blockNumber) external view returns (uint256) ``` ### getEpochDifficulty ```solidity function getEpochDifficulty(uint256 epochNumber) external view returns (uint256) ``` ### getRelayRange ```solidity function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd) ``` ## RelayUtils ### extractTimestampAt ```solidity function extractTimestampAt(bytes headers, uint256 at) internal pure returns (uint32) ``` Extract the timestamp of the header at the given position. Assumes that the specified position contains a valid header. Performs no validation whatsoever. #### Parameters | Name | Type | Description | | ------- | ------- | --------------------------------------------- | | headers | bytes | Byte array containing the header of interest. | | at | uint256 | The start of the header in the array. | #### Return Values | Name | Type | Description | | ---- | ------ | ---------------------------- | | \[0] | uint32 | The timestamp of the header. | ## LightRelay THE RELAY MUST NOT BE USED BEFORE GENESIS AND AT LEAST ONE RETARGET. ### ready ```solidity bool ready ``` ### authorizationRequired ```solidity bool authorizationRequired ``` ### proofLength ```solidity uint64 proofLength ``` ### genesisEpoch ```solidity uint64 genesisEpoch ``` ### currentEpoch ```solidity uint64 currentEpoch ``` ### currentEpochDifficulty ```solidity uint256 currentEpochDifficulty ``` ### prevEpochDifficulty ```solidity uint256 prevEpochDifficulty ``` ### epochs ```solidity mapping(uint256 => struct Epoch) epochs ``` ### isAuthorized ```solidity mapping(address => bool) isAuthorized ``` ### relayActive ```solidity modifier relayActive() ``` ### genesis ```solidity function genesis(bytes genesisHeader, uint256 genesisHeight, uint64 genesisProofLength) external ``` Establish a starting point for the relay by providing the target, timestamp and blockheight of the first block of the relay genesis epoch. If the relay is used by querying the current and previous epoch difficulty, at least one retarget needs to be provided after genesis; otherwise the prevEpochDifficulty will be uninitialised and zero. #### Parameters | Name | Type | Description | | ------------------ | ------- | ------------------------------------------------- | | genesisHeader | bytes | The first block header of the genesis epoch. | | genesisHeight | uint256 | The block number of the first block of the epoch. | | genesisProofLength | uint64 | The number of blocks required to accept a proof. | ### setProofLength ```solidity function setProofLength(uint64 newLength) external ``` Set the number of blocks required to accept a header chain. For production, a high number (e.g. 20-50) is recommended. Small numbers are accepted but should only be used for testing. #### Parameters | Name | Type | Description | | --------- | ------ | ------------------------------------------------------ | | newLength | uint64 | The required number of blocks. Must be less than 2016. | ### setAuthorizationStatus ```solidity function setAuthorizationStatus(bool status) external ``` Set whether the relay requires retarget submitters to be pre-authorised by governance. #### Parameters | Name | Type | Description | | ------ | ---- | ------------------------------------------------------ | | status | bool | True if authorisation is to be required, false if not. | ### authorize ```solidity function authorize(address submitter) external ``` Authorise the given address to submit retarget proofs. #### Parameters | Name | Type | Description | | --------- | ------- | ----------------------------- | | submitter | address | The address to be authorised. | ### deauthorize ```solidity function deauthorize(address submitter) external ``` Rescind the authorisation of the submitter to retarget. #### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------- | | submitter | address | The address to be deauthorised. | ### retarget ```solidity function retarget(bytes headers) external ``` Add a new epoch to the relay by providing a proof of the difficulty before and after the retarget. Checks that the first X blocks are valid in the most recent epoch, that the difficulty of the new epoch is calculated correctly according to the block timestamps, and that the next X blocks would be valid in the new epoch. We have no information of block heights, so we cannot enforce that retargets only happen every 2016 blocks; instead, we assume that this is the case if a valid proof of work is provided. It is possible to cheat the relay by providing X blocks from earlier in the most recent epoch, and then mining X new blocks after them. However, each of these malicious blocks would have to be mined to a higher difficulty than the legitimate ones. Alternatively, if the retarget has not been performed yet, one could first mine X blocks in the old difficulty with timestamps set far in the future, and then another X blocks at a greatly reduced difficulty. In either case, cheating the realy requires more work than mining X legitimate blocks. Only the most recent epoch is vulnerable to these attacks; once a retarget has been proven to the relay, the epoch is immutable even if a contradictory proof were to be presented later. #### Parameters | Name | Type | Description | | ------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | headers | bytes | A chain of headers including the last X blocks before the retarget, followed by the first X blocks after the retarget, where X equals the current proof length. | ### validateChain ```solidity function validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount) ``` Check whether a given chain of headers should be accepted as valid within the rules of the relay. If the validation fails, this function throws an exception. A chain of headers is accepted as valid if: * Its length is between 2 and 2015 headers. * Headers in the chain are sequential and refer to previous digests. * Each header is mined with the correct amount of work. * The difficulty in each header matches an epoch of the relay, as determined by the headers' timestamps. The headers must be between the genesis epoch and the latest proven epoch (inclusive). If the chain contains a retarget, it is accepted if the retarget has already been proven to the relay. If the chain contains blocks of an epoch that has not been proven to the relay (after a retarget within the header chain, or when the entire chain falls within an epoch that has not been proven yet), it will be rejected. One exception to this is when two subsequent epochs have exactly the same difficulty; headers from the latter epoch will be accepted if the previous epoch has been proven to the relay. This is because it is not possible to distinguish such headers from headers of the previous epoch. If the difficulty increases significantly between relay genesis and the present, creating fraudulent proofs for earlier epochs becomes easier. Users of the relay should check the timestamps of valid headers and only accept appropriately recent ones. #### Parameters | Name | Type | Description | | ------- | ----- | ------------------------------------- | | headers | bytes | A chain of 2 to 2015 bitcoin headers. | #### Return Values | Name | Type | Description | | ----------------------- | ------- | ---------------------------------- | | startingHeaderTimestamp | uint256 | The timestamp of the first header. | | headerCount | uint256 | The number of headers. | ### getBlockDifficulty ```solidity function getBlockDifficulty(uint256 blockNumber) external view returns (uint256) ``` Get the difficulty of the specified block. #### Parameters | Name | Type | Description | | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | blockNumber | uint256 | The number of the block. Must fall within the relay range (at or after the relay genesis, and at or before the end of the most recent epoch proven to the relay). | #### Return Values | Name | Type | Description | | ---- | ------- | ---------------------------- | | \[0] | uint256 | The difficulty of the epoch. | ### getRelayRange ```solidity function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd) ``` Get the range of blocks the relay can accept proofs for. Assumes that the genesis has been set correctly. Additionally, if the next epoch after the current one has the exact same difficulty, headers for it can be validated as well. This function should be used for informative purposes, e.g. to determine whether a retarget must be provided before submitting a header chain for validation. #### Return Values | Name | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------- | | relayGenesis | uint256 | The height of the earliest block that can be included in header chains for the relay to validate. | | currentEpochEnd | uint256 | The height of the last block that can be included in header chains for the relay to validate. | ### getCurrentEpochDifficulty ```solidity function getCurrentEpochDifficulty() external view virtual returns (uint256) ``` Returns the difficulty of the current epoch. returns 0 if the relay is not ready. #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------------------ | | \[0] | uint256 | The difficulty of the current epoch. | ### getPrevEpochDifficulty ```solidity function getPrevEpochDifficulty() external view virtual returns (uint256) ``` Returns the difficulty of the previous epoch. Returns 0 if the relay is not ready or has not had a retarget. #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------------------- | | \[0] | uint256 | The difficulty of the previous epoch. | ### getCurrentAndPrevEpochDifficulty ```solidity function getCurrentAndPrevEpochDifficulty() external view returns (uint256 current, uint256 previous) ``` ### getEpochDifficulty ```solidity function getEpochDifficulty(uint256 epochNumber) public view returns (uint256) ``` Get the difficulty of the specified epoch. #### Parameters | Name | Type | Description | | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | epochNumber | uint256 | The number of the epoch (the height of the first block of the epoch, divided by 2016). Must fall within the relay range. | #### Return Values | Name | Type | Description | | ---- | ------- | ---------------------------- | | \[0] | uint256 | The difficulty of the epoch. | ### validateHeader ```solidity function validateHeader(bytes headers, uint256 start, bytes32 prevDigest) internal view returns (bytes32 digest, uint256 target) ``` Check that the specified header forms a correct chain with the digest of the previous header (if provided), and has sufficient work. Throws an exception if the header's chain or PoW are invalid. Performs no other validation. #### Parameters | Name | Type | Description | | ---------- | ------- | --------------------------------------------------------------------------------------------- | | headers | bytes | The byte array containing the header of interest. | | start | uint256 | The start of the header in the array. | | prevDigest | bytes32 | The digest of the previous header (optional; providing zeros for the digest skips the check). | #### Return Values | Name | Type | Description | | ------ | ------- | --------------------------------- | | digest | bytes32 | The digest of the current header. | | target | uint256 | The PoW target of the header. | # LightRelayMaintainerProxy ## LightRelayMaintainerProxy The proxy contract that allows the relay maintainers to be refunded for the spent gas from the `ReimbursementPool`. When proving the next Bitcoin difficulty epoch, the maintainer calls the `LightRelayMaintainerProxy` which in turn calls the actual `LightRelay` contract. ### lightRelay ```solidity contract ILightRelay lightRelay ``` ### isAuthorized ```solidity mapping(address => bool) isAuthorized ``` Stores the addresses that can maintain the relay. Those addresses are attested by the DAO. The goal is to prevent a griefing attack by frontrunning relay maintainer which is responsible for retargetting the relay in the given round. The maintainer's transaction would revert with no gas refund. Having the ability to restrict maintainer addresses is also important in case the underlying relay contract has authorization requirements for callers. ### retargetGasOffset ```solidity uint256 retargetGasOffset ``` Gas that is meant to balance the retarget overall cost. Can be ### LightRelayUpdated ```solidity event LightRelayUpdated(address newRelay) ``` ### MaintainerAuthorized ```solidity event MaintainerAuthorized(address maintainer) ``` ### MaintainerDeauthorized ```solidity event MaintainerDeauthorized(address maintainer) ``` ### RetargetGasOffsetUpdated ```solidity event RetargetGasOffsetUpdated(uint256 retargetGasOffset) ``` ### onlyRelayMaintainer ```solidity modifier onlyRelayMaintainer() ``` ### onlyReimbursableAdmin ```solidity modifier onlyReimbursableAdmin() ``` ### constructor ```solidity constructor(contract ILightRelay _lightRelay, contract ReimbursementPool _reimbursementPool) public ``` ### updateLightRelay ```solidity function updateLightRelay(contract ILightRelay _lightRelay) external ``` Allows the governance to upgrade the `LightRelay` address. The function does not implement any governance delay and does not check the status of the `LightRelay`. The Governance implementation needs to ensure all requirements for the upgrade are satisfied before executing this function. ### authorize ```solidity function authorize(address maintainer) external ``` Authorizes the given address as a maintainer. Can only be called by the owner and the address of the maintainer must not be already authorized. The function does not implement any governance delay. #### Parameters | Name | Type | Description | | ---------- | ------- | ----------------------------------------------- | | maintainer | address | The address of the maintainer to be authorized. | ### deauthorize ```solidity function deauthorize(address maintainer) external ``` Deauthorizes the given address as a maintainer. Can only be called by the owner and the address of the maintainer must be authorized. The function does not implement any governance delay. #### Parameters | Name | Type | Description | | ---------- | ------- | ------------------------------------------------- | | maintainer | address | The address of the maintainer to be deauthorized. | ### updateRetargetGasOffset ```solidity function updateRetargetGasOffset(uint256 newRetargetGasOffset) external ``` Updates the values of retarget gas offset. Can be called only by the contract owner. The caller is responsible for validating the parameter. The function does not implement any governance delay. #### Parameters | Name | Type | Description | | -------------------- | ------- | ------------------------ | | newRetargetGasOffset | uint256 | New retarget gas offset. | ### retarget ```solidity function retarget(bytes headers) external ``` Wraps `LightRelay.retarget` call and reimburses the caller's transaction cost. Can only be called by an authorized relay maintainer. See `LightRelay.retarget` function documentation. # MaintainerProxy ## MaintainerProxy Maintainers are the willing off-chain clients approved by the governance. Maintainers proxy calls to the `Bridge` contract via 'MaintainerProxy' and are refunded for the spent gas from the `ReimbursementPool`. There are two types of maintainers: wallet maintainers and SPV maintainers. ### bridge ```solidity contract Bridge bridge ``` ### isWalletMaintainer ```solidity mapping(address => uint256) isWalletMaintainer ``` Authorized wallet maintainers that can interact with the set of functions for wallet maintainers only. Authorization can be granted and removed by the governance. 'Key' is the address of the maintainer. 'Value' represents an index+1 in the 'maintainers' array. 1 was added so the maintainer index can never be 0 which is a reserved index for a non-existent maintainer in this map. ### walletMaintainers ```solidity address[] walletMaintainers ``` This list of wallet maintainers keeps the order of which wallet maintainer should be submitting a next transaction. It does not enforce the order but only tracks who should be next in line. ### isSpvMaintainer ```solidity mapping(address => uint256) isSpvMaintainer ``` Authorized SPV maintainers that can interact with the set of functions for SPV maintainers only. Authorization can be granted and removed by the governance. 'Key' is the address of the maintainer. 'Value' represents an index+1 in the 'maintainers' array. 1 was added so the maintainer index can never be 0 which is a reserved index for a non-existent maintainer in this map. ### spvMaintainers ```solidity address[] spvMaintainers ``` This list of SPV maintainers keeps the order of which SPV maintainer should be submitting a next transaction. It does not enforce the order but only tracks who should be next in line. ### submitDepositSweepProofGasOffset ```solidity uint256 submitDepositSweepProofGasOffset ``` Gas that is meant to balance the submission of deposit sweep proof overall cost. Can be updated by the governance based on the current market conditions. ### submitRedemptionProofGasOffset ```solidity uint256 submitRedemptionProofGasOffset ``` Gas that is meant to balance the submission of redemption proof overall cost. Can be updated by the governance based on the current market conditions. ### resetMovingFundsTimeoutGasOffset ```solidity uint256 resetMovingFundsTimeoutGasOffset ``` Gas that is meant to balance the reset of moving funds timeout overall cost. Can be updated by the governance based on the current market conditions. ### submitMovingFundsProofGasOffset ```solidity uint256 submitMovingFundsProofGasOffset ``` Gas that is meant to balance the submission of moving funds proof overall cost. Can be updated by the governance based on the current market conditions. ### notifyMovingFundsBelowDustGasOffset ```solidity uint256 notifyMovingFundsBelowDustGasOffset ``` Gas that is meant to balance the notification of moving funds below dust overall cost. Can be updated by the governance based on the current market conditions. ### submitMovedFundsSweepProofGasOffset ```solidity uint256 submitMovedFundsSweepProofGasOffset ``` Gas that is meant to balance the submission of moved funds sweep proof overall cost. Can be updated by the governance based on the current market conditions. ### requestNewWalletGasOffset ```solidity uint256 requestNewWalletGasOffset ``` Gas that is meant to balance the request of a new wallet overall cost. Can be updated by the governance based on the current market conditions. ### notifyWalletCloseableGasOffset ```solidity uint256 notifyWalletCloseableGasOffset ``` Gas that is meant to balance the notification of closeable wallet overall cost. Can be updated by the governance based on the current market conditions. ### notifyWalletClosingPeriodElapsedGasOffset ```solidity uint256 notifyWalletClosingPeriodElapsedGasOffset ``` Gas that is meant to balance the notification of wallet closing period elapsed overall cost. Can be updated by the governance based on the current market conditions. ### defeatFraudChallengeGasOffset ```solidity uint256 defeatFraudChallengeGasOffset ``` Gas that is meant to balance the defeat fraud challenge overall cost. Can be updated by the governance based on the current market conditions. ### defeatFraudChallengeWithHeartbeatGasOffset ```solidity uint256 defeatFraudChallengeWithHeartbeatGasOffset ``` Gas that is meant to balance the defeat fraud challenge with heartbeat overall cost. Can be updated by the governance based on the current market conditions. ### WalletMaintainerAuthorized ```solidity event WalletMaintainerAuthorized(address maintainer) ``` ### WalletMaintainerUnauthorized ```solidity event WalletMaintainerUnauthorized(address maintainer) ``` ### SpvMaintainerAuthorized ```solidity event SpvMaintainerAuthorized(address maintainer) ``` ### SpvMaintainerUnauthorized ```solidity event SpvMaintainerUnauthorized(address maintainer) ``` ### BridgeUpdated ```solidity event BridgeUpdated(address newBridge) ``` ### GasOffsetParametersUpdated ```solidity event GasOffsetParametersUpdated(uint256 submitDepositSweepProofGasOffset, uint256 submitRedemptionProofGasOffset, uint256 resetMovingFundsTimeoutGasOffset, uint256 submitMovingFundsProofGasOffset, uint256 notifyMovingFundsBelowDustGasOffset, uint256 submitMovedFundsSweepProofGasOffset, uint256 requestNewWalletGasOffset, uint256 notifyWalletCloseableGasOffset, uint256 notifyWalletClosingPeriodElapsedGasOffset, uint256 defeatFraudChallengeGasOffset, uint256 defeatFraudChallengeWithHeartbeatGasOffset) ``` ### onlyWalletMaintainer ```solidity modifier onlyWalletMaintainer() ``` ### onlySpvMaintainer ```solidity modifier onlySpvMaintainer() ``` ### onlyReimbursableAdmin ```solidity modifier onlyReimbursableAdmin() ``` ### constructor ```solidity constructor(contract Bridge _bridge, contract ReimbursementPool _reimbursementPool) public ``` ### submitDepositSweepProof ```solidity function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external ``` Wraps `Bridge.submitDepositSweepProof` call and reimburses the caller's transaction cost. See `Bridge.submitDepositSweepProof` function documentation. ### submitRedemptionProof ```solidity function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external ``` Wraps `Bridge.submitRedemptionProof` call and reimburses the caller's transaction cost. See `Bridge.submitRedemptionProof` function documentation. ### resetMovingFundsTimeout ```solidity function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external ``` Wraps `Bridge.resetMovingFundsTimeout` call and reimburses the caller's transaction cost. See `Bridge.resetMovingFundsTimeout` function documentation. ### submitMovingFundsProof ```solidity function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external ``` Wraps `Bridge.submitMovingFundsProof` call and reimburses the caller's transaction cost. See `Bridge.submitMovingFundsProof` function documentation. ### notifyMovingFundsBelowDust ```solidity function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external ``` Wraps `Bridge.notifyMovingFundsBelowDust` call and reimburses the caller's transaction cost. See `Bridge.notifyMovingFundsBelowDust` function documentation. ### submitMovedFundsSweepProof ```solidity function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external ``` Wraps `Bridge.submitMovedFundsSweepProof` call and reimburses the caller's transaction cost. See `Bridge.submitMovedFundsSweepProof` function documentation. ### requestNewWallet ```solidity function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) external ``` Wraps `Bridge.requestNewWallet` call and reimburses the caller's transaction cost. See `Bridge.requestNewWallet` function documentation. ### notifyWalletCloseable ```solidity function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external ``` Wraps `Bridge.notifyWalletCloseable` call and reimburses the caller's transaction cost. See `Bridge.notifyWalletCloseable` function documentation. ### notifyWalletClosingPeriodElapsed ```solidity function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) external ``` Wraps `Bridge.notifyWalletClosingPeriodElapsed` call and reimburses the caller's transaction cost. See `Bridge.notifyWalletClosingPeriodElapsed` function documentation. ### defeatFraudChallenge ```solidity function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) external ``` Wraps `Bridge.defeatFraudChallenge` call and reimburses the caller's transaction cost. See `Bridge.defeatFraudChallenge` function documentation. ### defeatFraudChallengeWithHeartbeat ```solidity function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) external ``` Wraps `Bridge.defeatFraudChallengeWithHeartbeat` call and reimburses the caller's transaction cost. See `Bridge.defeatFraudChallengeWithHeartbeat` function documentation. ### authorizeWalletMaintainer ```solidity function authorizeWalletMaintainer(address maintainer) external ``` Authorize a wallet maintainer that can interact with this reimbursement pool. Can be authorized by the owner only. #### Parameters | Name | Type | Description | | ---------- | ------- | ------------------------------- | | maintainer | address | Wallet maintainer to authorize. | ### authorizeSpvMaintainer ```solidity function authorizeSpvMaintainer(address maintainer) external ``` Authorize an SPV maintainer that can interact with this reimbursement pool. Can be authorized by the owner only. #### Parameters | Name | Type | Description | | ---------- | ------- | ---------------------------- | | maintainer | address | SPV maintainer to authorize. | ### unauthorizeWalletMaintainer ```solidity function unauthorizeWalletMaintainer(address maintainerToUnauthorize) external ``` Unauthorize a wallet maintainer that was previously authorized to interact with the Maintainer Proxy contract. Can be unauthorized by the owner only. The last maintainer is swapped with the one to be unauthorized. The unauthorized maintainer is then removed from the list. An index of the last maintainer is changed with the removed maintainer. Ex. 'walletMaintainers' list: \[0x1, 0x2, 0x3, 0x4, 0x5] 'isWalletMaintainer' map: \[0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5] unauthorize: 0x3 new 'walletMaintainers' list: \[0x1, 0x2, 0x5, 0x4] new 'isWalletMaintainer' map: \[0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3] #### Parameters | Name | Type | Description | | ----------------------- | ------- | -------------------------- | | maintainerToUnauthorize | address | Maintainer to unauthorize. | ### unauthorizeSpvMaintainer ```solidity function unauthorizeSpvMaintainer(address maintainerToUnauthorize) external ``` Unauthorize an SPV maintainer that was previously authorized to interact with the Maintainer Proxy contract. Can be unauthorized by the owner only. The last maintainer is swapped with the one to be unauthorized. The unauthorized maintainer is then removed from the list. An index of the last maintainer is changed with the removed maintainer. Ex. 'spvMaintainers' list: \[0x1, 0x2, 0x3, 0x4, 0x5] 'isSpvMaintainer' map: \[0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5] unauthorize: 0x3 new 'spvMaintainers' list: \[0x1, 0x2, 0x5, 0x4] new 'isSpvMaintainer' map: \[0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3] #### Parameters | Name | Type | Description | | ----------------------- | ------- | -------------------------- | | maintainerToUnauthorize | address | Maintainer to unauthorize. | ### updateBridge ```solidity function updateBridge(contract Bridge _bridge) external ``` Allows the Governance to upgrade the Bridge address. The function does not implement any governance delay and does not check the status of the Bridge. The Governance implementation needs to ensure all requirements for the upgrade are satisfied before executing this function. ### updateGasOffsetParameters ```solidity function updateGasOffsetParameters(uint256 newSubmitDepositSweepProofGasOffset, uint256 newSubmitRedemptionProofGasOffset, uint256 newResetMovingFundsTimeoutGasOffset, uint256 newSubmitMovingFundsProofGasOffset, uint256 newNotifyMovingFundsBelowDustGasOffset, uint256 newSubmitMovedFundsSweepProofGasOffset, uint256 newRequestNewWalletGasOffset, uint256 newNotifyWalletCloseableGasOffset, uint256 newNotifyWalletClosingPeriodElapsedGasOffset, uint256 newDefeatFraudChallengeGasOffset, uint256 newDefeatFraudChallengeWithHeartbeatGasOffset) external ``` Updates the values of gas offset parameters. Can be called only by the contract owner. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | --------------------------------------------- | ------- | ----------------------------------------------------- | | newSubmitDepositSweepProofGasOffset | uint256 | New submit deposit sweep proof gas offset. | | newSubmitRedemptionProofGasOffset | uint256 | New submit redemption proof gas offset. | | newResetMovingFundsTimeoutGasOffset | uint256 | New reset moving funds timeout gas offset. | | newSubmitMovingFundsProofGasOffset | uint256 | New submit moving funds proof gas offset. | | newNotifyMovingFundsBelowDustGasOffset | uint256 | New notify moving funds below dust gas offset. | | newSubmitMovedFundsSweepProofGasOffset | uint256 | New submit moved funds sweep proof gas offset. | | newRequestNewWalletGasOffset | uint256 | New request new wallet gas offset. | | newNotifyWalletCloseableGasOffset | uint256 | New notify closeable wallet gas offset. | | newNotifyWalletClosingPeriodElapsedGasOffset | uint256 | New notify wallet closing period elapsed gas offset. | | newDefeatFraudChallengeGasOffset | uint256 | New defeat fraud challenge gas offset. | | newDefeatFraudChallengeWithHeartbeatGasOffset | uint256 | New defeat fraud challenge with heartbeat gas offset. | ### allWalletMaintainers ```solidity function allWalletMaintainers() external view returns (address[]) ``` Gets an entire array of wallet maintainer addresses. ### allSpvMaintainers ```solidity function allSpvMaintainers() external view returns (address[]) ``` Gets an entire array of SPV maintainer addresses. # MovingFunds ## MovingFunds The library handles the logic for moving Bitcoin between Bridge wallets. A wallet that failed a heartbeat, did not process requested redemption on time, or qualifies to be closed, begins the procedure of moving funds to other wallets in the Bridge. The wallet needs to commit to which other Live wallets it is moving the funds to and then, provide an SPV proof of moving funds to the previously committed wallets. Once the proof is submitted, all target wallets are supposed to sweep the received UTXOs with their own main UTXOs in order to update their BTC balances. ### MovingFundsTxOutputsProcessingInfo ```solidity struct MovingFundsTxOutputsProcessingInfo { bytes32 movingFundsTxHash; bytes movingFundsTxOutputVector; } ``` ### MovedFundsSweepRequestState ```solidity enum MovedFundsSweepRequestState { Unknown, Pending, Processed, TimedOut } ``` ### MovedFundsSweepRequest ```solidity struct MovedFundsSweepRequest { bytes20 walletPubKeyHash; uint64 value; uint32 createdAt; enum MovingFunds.MovedFundsSweepRequestState state; } ``` ### MovingFundsCommitmentSubmitted ```solidity event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter) ``` ### MovingFundsTimeoutReset ```solidity event MovingFundsTimeoutReset(bytes20 walletPubKeyHash) ``` ### MovingFundsCompleted ```solidity event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash) ``` ### MovingFundsTimedOut ```solidity event MovingFundsTimedOut(bytes20 walletPubKeyHash) ``` ### MovingFundsBelowDustReported ```solidity event MovingFundsBelowDustReported(bytes20 walletPubKeyHash) ``` ### MovedFundsSwept ```solidity event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) ``` ### MovedFundsSweepTimedOut ```solidity event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex) ``` ### submitMovingFundsCommitment ```solidity function submitMovingFundsCommitment(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) external ``` Submits the moving funds target wallets commitment. Once all requirements are met, that function registers the target wallets commitment and opens the way for moving funds proof submission. Requirements: * The source wallet must be in the MovingFunds state, * The source wallet must not have pending redemption requests, * The source wallet must not have pending moved funds sweep requests, * The source wallet must not have submitted its commitment already, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given source wallet in the ECDSA registry. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events, * The `walletMemberIndex` must be in range \[1, walletMembersIDs.length], * The caller must be the member of the source wallet signing group at the position indicated by `walletMemberIndex` parameter, * The `walletMainUtxo` components must point to the recent main UTXO of the source wallet, as currently known on the Ethereum chain, * Source wallet BTC balance must be greater than zero, * At least one Live wallet must exist in the system, * Submitted target wallets count must match the expected count `N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))` where `N > 0`, * Each target wallet must be not equal to the source wallet, * Each target wallet must follow the expected order i.e. all target wallets 20-byte public key hashes represented as numbers must form a strictly increasing sequence without duplicates, * Each target wallet must be in Live state. #### Parameters | Name | Type | Description | | ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the source wallet. | | walletMainUtxo | struct BitcoinTx.UTXO | Data of the source wallet's main UTXO, as currently known on the Ethereum chain. | | walletMembersIDs | uint32\[] | Identifiers of the source wallet signing group members. | | walletMemberIndex | uint256 | Position of the caller in the source wallet signing group members list. | | targetWallets | bytes20\[] | List of 20-byte public key hashes of the target wallets that the source wallet commits to move the funds to. | ### resetMovingFundsTimeout ```solidity function resetMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash) external ``` Resets the moving funds timeout for the given wallet if the target wallet commitment cannot be submitted due to a lack of live wallets in the system. Requirements: * The wallet must be in the MovingFunds state, * The target wallets commitment must not be already submitted for the given moving funds wallet, * Live wallets count must be zero, * The moving funds timeout reset delay must be elapsed. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the moving funds wallet | ### submitMovingFundsProof ```solidity function submitMovingFundsProof(struct BridgeState.Storage self, struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external ``` Used by the wallet to prove the BTC moving funds transaction and to make the necessary state changes. Moving funds is only accepted if it satisfies SPV proof. The function validates the moving funds transaction structure by checking if it actually spends the main UTXO of the declared wallet and locks the value on the pre-committed target wallets using a reasonable transaction fee. If all preconditions are met, this functions closes the source wallet. It is possible to prove the given moving funds transaction only one time. Requirements: * `movingFundsTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `movingFundsTx` should represent a Bitcoin transaction with exactly 1 input that refers to the wallet's main UTXO. That transaction should have 1..n outputs corresponding to the pre-committed target wallets. Outputs must be ordered in the same way as their corresponding target wallets are ordered within the target wallets commitment, * `movingFundsProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. Additionally, the recent main UTXO on Ethereum must be set, * `walletPubKeyHash` must be connected with the main UTXO used as transaction single input, * The wallet that `walletPubKeyHash` points to must be in the MovingFunds state, * The target wallets commitment must be submitted by the wallet that `walletPubKeyHash` points to, * The total Bitcoin transaction fee must be lesser or equal to `movingFundsTxMaxTotalFee` governable parameter. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | movingFundsTx | struct BitcoinTx.Info | Bitcoin moving funds transaction data. | | movingFundsProof | struct BitcoinTx.Proof | Bitcoin moving funds proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the moving funds transaction. | ### processMovingFundsTxOutputs ```solidity function processMovingFundsTxOutputs(struct BridgeState.Storage self, struct MovingFunds.MovingFundsTxOutputsProcessingInfo processInfo) internal returns (bytes32 targetWalletsHash, uint256 outputsTotalValue) ``` Processes the moving funds Bitcoin transaction output vector and extracts information required for further processing. Requirements: * The `movingFundsTxOutputVector` must be parseable, i.e. must be validated by the caller as stated in their parameter doc, * Each output must refer to a 20-byte public key hash, * The total outputs value must be evenly divided over all outputs. #### Parameters | Name | Type | Description | | ----------- | ----------------------------------------------------- | ---------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | processInfo | struct MovingFunds.MovingFundsTxOutputsProcessingInfo | Processing info containing the moving funds tx hash and output vector. | #### Return Values | Name | Type | Description | | ----------------- | ------- | ------------------------------------------------------------------------------ | | targetWalletsHash | bytes32 | keccak256 hash over the list of actual target wallets used in the transaction. | | outputsTotalValue | uint256 | Sum of all outputs values. | ### notifyMovingFundsTimeout ```solidity function notifyMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) external ``` Notifies about a timed out moving funds process. Terminates the wallet and slashes signing group members as a result. Requirements: * The wallet must be in the MovingFunds state, * The moving funds timeout must be actually exceeded, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------ | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### notifyMovingFundsBelowDust ```solidity function notifyMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external ``` Notifies about a moving funds wallet whose BTC balance is below the moving funds dust threshold. Ends the moving funds process and begins wallet closing immediately. Requirements: * The wallet must be in the MovingFunds state, * The `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If the wallet has no main UTXO, this parameter can be empty as it is ignored, * The wallet BTC balance must be below the moving funds threshold. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | ### submitMovedFundsSweepProof ```solidity function submitMovedFundsSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external ``` Used by the wallet to prove the BTC moved funds sweep transaction and to make the necessary state changes. Moved funds sweep is only accepted if it satisfies SPV proof. The function validates the sweep transaction structure by checking if it actually spends the moved funds UTXO and the sweeping wallet's main UTXO (optionally), and if it locks the value on the sweeping wallet's 20-byte public key hash using a reasonable transaction fee. If all preconditions are met, this function updates the sweeping wallet main UTXO, thus their BTC balance. It is possible to prove the given sweep transaction only one time. Requirements: * `sweepTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `sweepTx` should represent a Bitcoin transaction with the first input pointing to a wallet's sweep Pending request and, optionally, the second input pointing to the wallet's main UTXO, if the sweeping wallet has a main UTXO set. There should be only one output locking funds on the sweeping wallet 20-byte public key hash, * `sweepProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the sweeping wallet, as currently known on the Ethereum chain. If there is no main UTXO, this parameter is ignored, * The sweeping wallet must be in the Live or MovingFunds state, * The total Bitcoin transaction fee must be lesser or equal to `movedFundsSweepTxMaxTotalFee` governable parameter. #### Parameters | Name | Type | Description | | ---------- | -------------------------- | ---------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | sweepTx | struct BitcoinTx.Info | Bitcoin sweep funds transaction data. | | sweepProof | struct BitcoinTx.Proof | Bitcoin sweep funds proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain. | ### processMovedFundsSweepTxOutput ```solidity function processMovedFundsSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value) ``` Processes the Bitcoin moved funds sweep transaction output vector by extracting the single output and using it to gain additional information required for further processing (e.g. value and wallet public key hash). Requirements: * Output vector must contain only one output, * The single output must be of P2PKH or P2WPKH type and lock the funds on a 20-byte public key hash. #### Parameters | Name | Type | Description | | ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | sweepTxOutputVector | bytes | Bitcoin moved funds sweep transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | #### Return Values | Name | Type | Description | | ---------------- | ------- | -------------------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte wallet public key hash. | | value | uint64 | 8-byte moved funds sweep transaction output value. | ### resolveMovedFundsSweepingWallet ```solidity function resolveMovedFundsSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo) ``` Resolves sweeping wallet based on the provided wallet public key hash. Validates the wallet state and current main UTXO, as currently known on the Ethereum chain. Requirements: * Sweeping wallet must be either in Live or MovingFunds state, * If the main UTXO of the sweeping wallet exists in the storage, the passed `mainUTXO` parameter must be equal to the stored one. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | #### Return Values | Name | Type | Description | | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | wallet | struct Wallets.Wallet | Data of the sweeping wallet. | | resolvedMainUtxo | struct BitcoinTx.UTXO | The actual main UTXO of the sweeping wallet resolved by cross-checking the `mainUtxo` parameter with the chain state. If the validation went well, this is the plain-text main UTXO corresponding to the `wallet.mainUtxoHash`. | ### processMovedFundsSweepTxInputs ```solidity function processMovedFundsSweepTxInputs(struct BridgeState.Storage self, bytes sweepTxInputVector, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) internal returns (uint256 inputsTotalValue) ``` Processes the Bitcoin moved funds sweep transaction input vector. It extracts the first input and tries to match it with one of the moved funds sweep requests targeting the sweeping wallet. If the sweep request is an existing Pending request, this function marks it as Processed. If the sweeping wallet has a main UTXO, this function extracts the second input, makes sure it refers to the wallet main UTXO, and marks that main UTXO as correctly spent. Requirements: * The input vector must consist of one mandatory and one optional input, * The mandatory input must be the first input in the vector, * The mandatory input must point to a Pending moved funds sweep request that is targeted to the sweeping wallet, * The optional output must be the second input in the vector, * The optional input is required if the sweeping wallet has a main UTXO (i.e. the `mainUtxo` is not zeroed). In that case, that input must point the the sweeping wallet main UTXO. #### Parameters | Name | Type | Description | | ------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | sweepTxInputVector | bytes | Bitcoin moved funds sweep transaction input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | | mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO. If no main UTXO exists for the given the wallet, this parameter's fields should be zeroed to bypass the main UTXO validation. | | walletPubKeyHash | bytes20 | 20-byte public key hash of the sweeping wallet. | #### Return Values | Name | Type | Description | | ---------------- | ------- | ----------------------- | | inputsTotalValue | uint256 | Total inputs value sum. | ### parseMovedFundsSweepTxInputAt ```solidity function parseMovedFundsSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength) ``` Parses a Bitcoin transaction input starting at the given index. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. #### Parameters | Name | Type | Description | | ------------------ | ------- | --------------------------------- | | inputVector | bytes | Bitcoin transaction input vector. | | inputStartingIndex | uint256 | Index the given input starts at. | #### Return Values | Name | Type | Description | | -------------- | ------- | ---------------------------------------------------------------------------------------------- | | outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the given input's outpoint. | | outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the given input's outpoint. | | inputLength | uint256 | Byte length of the given input. | ### notifyMovedFundsSweepTimeout ```solidity function notifyMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) external ``` Notifies about a timed out moved funds sweep process. If the wallet is not terminated yet, that function terminates the wallet and slashes signing group members as a result. Marks the given sweep request as TimedOut. Requirements: * The moved funds sweep request must be in the Pending state, * The moved funds sweep timeout must be actually exceeded, * The wallet must be either in the Live or MovingFunds or Terminated state,, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract. #### Parameters | Name | Type | Description | | ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | movingFundsTxHash | bytes32 | 32-byte hash of the moving funds transaction that caused the sweep request to be created. | | movingFundsTxOutputIndex | uint32 | Index of the moving funds transaction output that is subject of the sweep request. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | # Redemption ## OutboundTx Aggregates functions common to the redemption transaction proof validation and to the moving funds transaction proof validation. ### processWalletOutboundTxInput ```solidity function processWalletOutboundTxInput(struct BridgeState.Storage self, bytes walletOutboundTxInputVector, struct BitcoinTx.UTXO mainUtxo) internal ``` Checks whether an outbound Bitcoin transaction performed from the given wallet has an input vector that contains a single input referring to the wallet's main UTXO. Marks that main UTXO as correctly spent if the validation succeeds. Reverts otherwise. There are two outbound transactions from a wallet possible: a redemption transaction or a moving funds to another wallet transaction. #### Parameters | Name | Type | Description | | --------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletOutboundTxInputVector | bytes | Bitcoin outbound transaction's input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | ### parseWalletOutboundTxInput ```solidity function parseWalletOutboundTxInput(bytes walletOutboundTxInputVector) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex) ``` Parses the input vector of an outbound Bitcoin transaction performed from the given wallet. It extracts the single input then the transaction hash and output index from its outpoint. There are two outbound transactions from a wallet possible: a redemption transaction or a moving funds to another wallet transaction. #### Parameters | Name | Type | Description | | --------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | walletOutboundTxInputVector | bytes | Bitcoin outbound transaction input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | #### Return Values | Name | Type | Description | | -------------- | ------- | ---------------------------------------------------------------------------------------- | | outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the input's outpoint. | | outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the input's outpoint. | ## Redemption The library handles the logic for redeeming Bitcoin balances from the Bridge. To initiate a redemption, a user with a Bank balance supplies a Bitcoin address. Then, the system calculates the redemption fee, and releases balance to the provided Bitcoin address. Just like in case of sweeps of revealed deposits, redemption requests are processed in batches and require SPV proof to be submitted to the Bridge. ### RedemptionRequest ```solidity struct RedemptionRequest { address redeemer; uint64 requestedAmount; uint64 treasuryFee; uint64 txMaxFee; uint32 requestedAt; } ``` ### RedemptionTxOutputsInfo ```solidity struct RedemptionTxOutputsInfo { uint256 outputsTotalValue; uint64 totalBurnableValue; uint64 totalTreasuryFee; uint32 changeIndex; uint64 changeValue; } ``` ### RedemptionTxOutputsProcessingInfo ```solidity struct RedemptionTxOutputsProcessingInfo { uint256 outputStartingIndex; uint256 outputsCount; bytes32 walletP2PKHScriptKeccak; bytes32 walletP2WPKHScriptKeccak; } ``` ### RedemptionRequested ```solidity event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee) ``` ### RedemptionsCompleted ```solidity event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash) ``` ### RedemptionTimedOut ```solidity event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript) ``` ### requestRedemption ```solidity function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, bytes redeemerOutputScript, uint64 amount) external ``` Requests redemption of the given amount from the specified wallet to the redeemer Bitcoin output script. This function handles the simplest case, where balance owner is the redeemer. Requirements: * Wallet behind `walletPubKeyHash` must be live, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain, * `redeemerOutputScript` must be a proper Bitcoin script, * `redeemerOutputScript` cannot have wallet PKH as payload, * `amount` must be above or equal the `redemptionDustThreshold`, * Given `walletPubKeyHash` and `redeemerOutputScript` pair can be used for only one pending request at the same time, * Wallet must have enough Bitcoin balance to proceed the request, * Balance owner must make an allowance in the Bank that the Bridge contract can spend the given `amount`. #### Parameters | Name | Type | Description | | -------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. Balance owner address is stored as a redeemer address who will be able co claim back the Bank balance if anything goes wrong during the redemption. | | redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | | amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | ### requestRedemption ```solidity function requestRedemption(struct BridgeState.Storage self, address balanceOwner, uint64 amount, bytes redemptionData) external ``` Requests redemption of the given amount from the specified wallet to the redeemer Bitcoin output script. Used by `Bridge.receiveBalanceApproval`. Can handle more complex cases where balance owner may be someone else than the redeemer. Requirements: * Wallet behind `walletPubKeyHash` must be live, * `mainUtxo*` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain, * `redeemerOutputScript` must be a proper Bitcoin script, * `redeemerOutputScript` cannot have wallet PKH as payload, * `amount` must be above or equal the `redemptionDustThreshold`, * Given `walletPubKeyHash` and `redeemerOutputScript` pair can be used for only one pending request at the same time, * Wallet must have enough Bitcoin balance to proceed the request, * Balance owner must make an allowance in the Bank that the Bridge contract can spend the given `amount`. #### Parameters | Name | Type | Description | | -------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | | amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | | redemptionData | bytes | ABI-encoded redemption data: \[ address redeemer, bytes20 walletPubKeyHash, bytes32 mainUtxoTxHash, uint32 mainUtxoTxOutputIndex, uint64 mainUtxoTxOutputValue, bytes redeemerOutputScript ] - redeemer: The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their Bitcoin balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to, - walletPubKeyHash: The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key), - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as currently known on the Ethereum chain, - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output index, as currently known on Ethereum chain, - mainUtxoTxOutputValue: Data of the wallet's main UTXO output value, as currently known on Ethereum chain, - redeemerOutputScript The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | ### requestRedemption ```solidity function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, address redeemer, bytes redeemerOutputScript, uint64 amount) internal ``` Requests redemption of the given amount from the specified wallet to the redeemer Bitcoin output script. Requirements: * Wallet behind `walletPubKeyHash` must be live, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain, * `redeemerOutputScript` must be a proper Bitcoin script, * `redeemerOutputScript` cannot have wallet PKH as payload, * `amount` must be above or equal the `redemptionDustThreshold`, * Given `walletPubKeyHash` and `redeemerOutputScript` pair can be used for only one pending request at the same time, * Wallet must have enough Bitcoin balance to proceed the request, * Balance owner must make an allowance in the Bank that the Bridge contract can spend the given `amount`. #### Parameters | Name | Type | Description | | -------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | | redeemer | address | The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their Bitcoin balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to. | | redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | | amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | ### submitRedemptionProof ```solidity function submitRedemptionProof(struct BridgeState.Storage self, struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external ``` Used by the wallet to prove the BTC redemption transaction and to make the necessary bookkeeping. Redemption is only accepted if it satisfies SPV proof. The function is performing Bank balance updates by burning the total redeemed Bitcoin amount from Bridge balance and transferring the treasury fee sum to the treasury address. It is possible to prove the given redemption only one time. Requirements: * `redemptionTx` components must match the expected structure. See `BitcoinTx.Info` docs for reference. Their values must exactly correspond to appropriate Bitcoin transaction fields to produce a provable transaction hash, * The `redemptionTx` should represent a Bitcoin transaction with exactly 1 input that refers to the wallet's main UTXO. That transaction should have 1..n outputs handling existing pending redemption requests or pointing to reported timed out requests. There can be also 1 optional output representing the change and pointing back to the 20-byte wallet public key hash. The change should be always present if the redeemed value sum is lower than the total wallet's BTC balance, * `redemptionProof` components must match the expected structure. See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` field must contain a valid number of block headers, not less than the `txProofDifficultyFactor` contract constant, * `mainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. Additionally, the recent main UTXO on Ethereum must be set, * `walletPubKeyHash` must be connected with the main UTXO used as transaction single input. Other remarks: * Putting the change output as the first transaction output can save some gas because the output processing loop begins each iteration by checking whether the given output is the change thus uses some gas for making the comparison. Once the change is identified, that check is omitted in further iterations. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | redemptionTx | struct BitcoinTx.Info | Bitcoin redemption transaction data. | | redemptionProof | struct BitcoinTx.Proof | Bitcoin redemption proof data. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | | walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | ### resolveRedeemingWallet ```solidity function resolveRedeemingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet) ``` Resolves redeeming wallet based on the provided wallet public key hash. Validates the wallet state and current main UTXO, as currently known on the Ethereum chain. Requirements: * Sweeping wallet must be either in Live or MovingFunds state, * Main UTXO of the redeeming wallet must exists in the storage, * The passed `mainUTXO` parameter must be equal to the stored one. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | | mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | #### Return Values | Name | Type | Description | | ------ | --------------------- | ---------------------------- | | wallet | struct Wallets.Wallet | Data of the sweeping wallet. | ### processRedemptionTxOutputs ```solidity function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash) internal returns (struct Redemption.RedemptionTxOutputsInfo info) ``` Processes the Bitcoin redemption transaction output vector. It extracts each output and tries to identify it as a pending redemption request, reported timed out request, or change. Reverts if one of the outputs cannot be recognized properly. This function also marks each request as processed by removing them from `pendingRedemptions` mapping. #### Parameters | Name | Type | Description | | ------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | redemptionTxOutputVector | bytes | Bitcoin redemption transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | | walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | #### Return Values | Name | Type | Description | | ---- | ----------------------------------------- | --------------------------- | | info | struct Redemption.RedemptionTxOutputsInfo | Outcomes of the processing. | ### processRedemptionTxOutputs ```solidity function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash, struct Redemption.RedemptionTxOutputsProcessingInfo processInfo) internal returns (struct Redemption.RedemptionTxOutputsInfo resultInfo) ``` Processes all outputs from the redemption transaction. Tries to identify output as a change output, pending redemption request or reported redemption. Reverts if one of the outputs cannot be recognized properly. Marks each request as processed by removing them from `pendingRedemptions` mapping. #### Parameters | Name | Type | Description | | ------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | redemptionTxOutputVector | bytes | Bitcoin redemption transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | | walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | | processInfo | struct Redemption.RedemptionTxOutputsProcessingInfo | RedemptionTxOutputsProcessingInfo identifying output starting index, the number of outputs and possible wallet change P2PKH and P2WPKH scripts. | ### processNonChangeRedemptionTxOutput ```solidity function processNonChangeRedemptionTxOutput(struct BridgeState.Storage self, uint256 redemptionKey, uint64 outputValue) internal returns (uint64 burnableValue, uint64 treasuryFee) ``` Processes a single redemption transaction output. Tries to identify output as a pending redemption request or reported redemption timeout. Output script passed to this function must not be the change output. Such output needs to be identified separately before calling this function. Reverts if output is neither requested pending redemption nor requested and reported timed-out redemption. This function also marks each pending request as processed by removing them from `pendingRedemptions` mapping. Requirements: * This function should be called only if the given output represents redemption. It must not be the change output. #### Parameters | Name | Type | Description | | ------------- | -------------------------- | --------------------------------------------- | | self | struct BridgeState.Storage | | | redemptionKey | uint256 | Redemption key of the output being processed. | | outputValue | uint64 | Value of the output being processed. | #### Return Values | Name | Type | Description | | ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | burnableValue | uint64 | The value burnable as a result of processing this single redemption output. This value needs to be summed up with burnable values of all other outputs to evaluate total burnable value for the entire redemption transaction. This value is 0 for a timed-out redemption request. | | treasuryFee | uint64 | The treasury fee from this single redemption output. This value needs to be summed up with treasury fees of all other outputs to evaluate the total treasury fee for the entire redemption transaction. This value is 0 for a timed-out redemption request. | ### notifyRedemptionTimeout ```solidity function notifyRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) external ``` Notifies that there is a pending redemption request associated with the given wallet, that has timed out. The redemption request is identified by the key built as `keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. The results of calling this function: * the pending redemptions value for the wallet will be decreased by the requested amount (minus treasury fee), * the tokens taken from the redeemer on redemption request will be returned to the redeemer, * the request will be moved from pending redemptions to timed-out redemptions, * if the state of the wallet is `Live` or `MovingFunds`, the wallet operators will be slashed and the notifier will be rewarded, * if the state of wallet is `Live`, the wallet will be closed or marked as `MovingFunds` (depending on the presence or absence of the wallet's main UTXO) and the wallet will no longer be marked as the active wallet (if it was marked as such). Requirements: * The wallet must be in the Live or MovingFunds or Terminated state, * The redemption request identified by `walletPubKeyHash` and `redeemerOutputScript` must exist, * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events of the `WalletRegistry` contract, * The amount of time defined by `redemptionTimeout` must have passed since the redemption was requested (the request must be timed-out). #### Parameters | Name | Type | Description | | -------------------- | -------------------------- | ---------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | | redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH). | ### getRedemptionKey ```solidity function getRedemptionKey(bytes20 walletPubKeyHash, bytes script) internal pure returns (uint256) ``` Calculate redemption key without allocations. #### Parameters | Name | Type | Description | | ---------------- | ------- | ------------------------------------ | | walletPubKeyHash | bytes20 | the pubkey hash of the wallet. | | script | bytes | the output script of the redemption. | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------------------- | | \[0] | uint256 | The key = keccak256(keccak256(script) | ### \_getRedemptionKey ```solidity function _getRedemptionKey(bytes20 walletPubKeyHash, bytes32 scriptHash) internal pure returns (uint256) ``` Finish calculating redemption key without allocations. #### Parameters | Name | Type | Description | | ---------------- | ------- | ----------------------------------------- | | walletPubKeyHash | bytes20 | the pubkey hash of the wallet. | | scriptHash | bytes32 | the output script hash of the redemption. | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------------ | | \[0] | uint256 | The key = keccak256(scriptHash | # TBTC ## TBTC ### constructor ```solidity constructor() public ``` # TBTCOptimisticMinting ## TBTCOptimisticMinting The Optimistic Minting mechanism allows to mint TBTC before `TBTCVault` receives the Bank balance. There are two permissioned sets in the system: Minters and Guardians, both set up in 1-of-n mode. Minters observe the revealed deposits and request minting TBTC. Any single Minter can perform this action. There is an `optimisticMintingDelay` between the time of the request from a Minter to the time TBTC is minted. During the time of the delay, any Guardian can cancel the minting. This functionality is a part of `TBTCVault`. It is implemented in a separate abstract contract to achieve better separation of concerns and easier-to-follow code. ### OptimisticMintingRequest ```solidity struct OptimisticMintingRequest { uint64 requestedAt; uint64 finalizedAt; } ``` ### GOVERNANCE\_DELAY ```solidity uint256 GOVERNANCE_DELAY ``` The time delay that needs to pass between initializing and finalizing the upgrade of governable parameters. ### SATOSHI\_MULTIPLIER ```solidity uint256 SATOSHI_MULTIPLIER ``` Multiplier to convert satoshi to TBTC token units. ### bridge ```solidity contract Bridge bridge ``` ### isOptimisticMintingPaused ```solidity bool isOptimisticMintingPaused ``` Indicates if the optimistic minting has been paused. Only the Governance can pause optimistic minting. Note that the pause of the optimistic minting does not stop the standard minting flow where wallets sweep deposits. ### optimisticMintingFeeDivisor ```solidity uint32 optimisticMintingFeeDivisor ``` Divisor used to compute the treasury fee taken from each optimistically minted deposit and transferred to the treasury upon finalization of the optimistic mint. This fee is computed as follows: `fee = amount / optimisticMintingFeeDivisor`. For example, if the fee needs to be 2%, the `optimisticMintingFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. The optimistic minting fee does not replace the deposit treasury fee cut by the Bridge. The optimistic fee is a percentage AFTER the treasury fee is cut: `optimisticMintingFee = (depositAmount - treasuryFee) / optimisticMintingFeeDivisor` ### optimisticMintingDelay ```solidity uint32 optimisticMintingDelay ``` The time that needs to pass between the moment the optimistic minting is requested and the moment optimistic minting is finalized with minting TBTC. ### isMinter ```solidity mapping(address => bool) isMinter ``` Indicates if the given address is a Minter. Only Minters can request optimistic minting. ### minters ```solidity address[] minters ``` List of all Minters. May be used to establish an order in which the Minters should request for an optimistic minting. ### isGuardian ```solidity mapping(address => bool) isGuardian ``` Indicates if the given address is a Guardian. Only Guardians can cancel requested optimistic minting. ### optimisticMintingRequests ```solidity mapping(uint256 => struct TBTCOptimisticMinting.OptimisticMintingRequest) optimisticMintingRequests ``` Collection of all revealed deposits for which the optimistic minting was requested. Indexed by a deposit key computed as `keccak256(fundingTxHash | fundingOutputIndex)`. ### optimisticMintingDebt ```solidity mapping(address => uint256) optimisticMintingDebt ``` Optimistic minting debt value per depositor's address. The debt represents the total value of all depositor's deposits revealed to the Bridge that has not been yet swept and led to the optimistic minting of TBTC. When `TBTCVault` sweeps a deposit, the debt is fully or partially paid off, no matter if that particular swept deposit was used for the optimistic minting or not. The values are in 1e18 Ethereum precision. ### newOptimisticMintingFeeDivisor ```solidity uint32 newOptimisticMintingFeeDivisor ``` New optimistic minting fee divisor value. Set only when the parameter update process is pending. Once the update gets ### optimisticMintingFeeUpdateInitiatedTimestamp ```solidity uint256 optimisticMintingFeeUpdateInitiatedTimestamp ``` The timestamp at which the update of the optimistic minting fee divisor started. Zero if update is not in progress. ### newOptimisticMintingDelay ```solidity uint32 newOptimisticMintingDelay ``` New optimistic minting delay value. Set only when the parameter update process is pending. Once the update gets finalized, this ### optimisticMintingDelayUpdateInitiatedTimestamp ```solidity uint256 optimisticMintingDelayUpdateInitiatedTimestamp ``` The timestamp at which the update of the optimistic minting delay started. Zero if update is not in progress. ### OptimisticMintingRequested ```solidity event OptimisticMintingRequested(address minter, uint256 depositKey, address depositor, uint256 amount, bytes32 fundingTxHash, uint32 fundingOutputIndex) ``` ### OptimisticMintingFinalized ```solidity event OptimisticMintingFinalized(address minter, uint256 depositKey, address depositor, uint256 optimisticMintingDebt) ``` ### OptimisticMintingCancelled ```solidity event OptimisticMintingCancelled(address guardian, uint256 depositKey) ``` ### OptimisticMintingDebtRepaid ```solidity event OptimisticMintingDebtRepaid(address depositor, uint256 optimisticMintingDebt) ``` ### MinterAdded ```solidity event MinterAdded(address minter) ``` ### MinterRemoved ```solidity event MinterRemoved(address minter) ``` ### GuardianAdded ```solidity event GuardianAdded(address guardian) ``` ### GuardianRemoved ```solidity event GuardianRemoved(address guardian) ``` ### OptimisticMintingPaused ```solidity event OptimisticMintingPaused() ``` ### OptimisticMintingUnpaused ```solidity event OptimisticMintingUnpaused() ``` ### OptimisticMintingFeeUpdateStarted ```solidity event OptimisticMintingFeeUpdateStarted(uint32 newOptimisticMintingFeeDivisor) ``` ### OptimisticMintingFeeUpdated ```solidity event OptimisticMintingFeeUpdated(uint32 newOptimisticMintingFeeDivisor) ``` ### OptimisticMintingDelayUpdateStarted ```solidity event OptimisticMintingDelayUpdateStarted(uint32 newOptimisticMintingDelay) ``` ### OptimisticMintingDelayUpdated ```solidity event OptimisticMintingDelayUpdated(uint32 newOptimisticMintingDelay) ``` ### onlyMinter ```solidity modifier onlyMinter() ``` ### onlyGuardian ```solidity modifier onlyGuardian() ``` ### onlyOwnerOrGuardian ```solidity modifier onlyOwnerOrGuardian() ``` ### whenOptimisticMintingNotPaused ```solidity modifier whenOptimisticMintingNotPaused() ``` ### onlyAfterGovernanceDelay ```solidity modifier onlyAfterGovernanceDelay(uint256 updateInitiatedTimestamp) ``` ### constructor ```solidity constructor(contract Bridge _bridge) internal ``` ### \_mint ```solidity function _mint(address minter, uint256 amount) internal virtual ``` Mints the given amount of TBTC to the given depositor's address. Implemented by TBTCVault. ### getMinters ```solidity function getMinters() external view returns (address[]) ``` Allows to fetch a list of all Minters. ### requestOptimisticMint ```solidity function requestOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external ``` Allows a Minter to request for an optimistic minting of TBTC. The following conditions must be met: * There is no optimistic minting request for the deposit, finalized or not. * The deposit with the given Bitcoin funding transaction hash and output index has been revealed to the Bridge. * The deposit has not been swept yet. * The deposit is targeted into the TBTCVault. * The optimistic minting is not paused. After calling this function, the Minter has to wait for `optimisticMintingDelay` before finalizing the mint with a call to finalizeOptimisticMint. The deposit done on the Bitcoin side must be revealed early enough to the Bridge on Ethereum to pass the Bridge's validation. The validation passes successfully only if the deposit reveal is done respectively earlier than the moment when the deposit refund locktime is reached, i.e. the deposit becomes refundable. It may happen that the wallet does not sweep a revealed deposit and one of the Minters requests an optimistic mint for that deposit just before the locktime is reached. Guardians must cancel optimistic minting for this deposit because the wallet will not be able to sweep it. The on-chain optimistic minting code does not perform any validation for gas efficiency: it would have to perform the same validation as `validateDepositRefundLocktime` and expect the entire `DepositRevealInfo` to be passed to assemble the expected script hash on-chain. Guardians must validate if the deposit happened on Bitcoin, that the script hash has the expected format, and that the wallet is an active one so they can also validate the time left for the refund. ### finalizeOptimisticMint ```solidity function finalizeOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external ``` Allows a Minter to finalize previously requested optimistic minting. The following conditions must be met: * The optimistic minting has been requested for the given deposit. * The deposit has not been swept yet. * At least `optimisticMintingDelay` passed since the optimistic minting was requested for the given deposit. * The optimistic minting has not been finalized earlier for the given deposit. * The optimistic minting request for the given deposit has not been canceled by a Guardian. * The optimistic minting is not paused. This function mints TBTC and increases `optimisticMintingDebt` for the given depositor. The optimistic minting request is marked as finalized. ### cancelOptimisticMint ```solidity function cancelOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external ``` Allows a Guardian to cancel optimistic minting request. The following conditions must be met: * The optimistic minting request for the given deposit exists. * The optimistic minting request for the given deposit has not been finalized yet. Optimistic minting request is removed. It is possible to request optimistic minting again for the same deposit later. Guardians must validate the following conditions for every deposit for which the optimistic minting was requested: * The deposit happened on Bitcoin side and it has enough confirmations. * The optimistic minting has been requested early enough so that the wallet has enough time to sweep the deposit. * The wallet is an active one and it does perform sweeps or it will perform sweeps once the sweeps are activated. ### addMinter ```solidity function addMinter(address minter) external ``` Adds the address to the Minter list. ### removeMinter ```solidity function removeMinter(address minter) external ``` Removes the address from the Minter list. ### addGuardian ```solidity function addGuardian(address guardian) external ``` Adds the address to the Guardian set. ### removeGuardian ```solidity function removeGuardian(address guardian) external ``` Removes the address from the Guardian set. ### pauseOptimisticMinting ```solidity function pauseOptimisticMinting() external ``` Pauses the optimistic minting. Note that the pause of the optimistic minting does not stop the standard minting flow where wallets sweep deposits. ### unpauseOptimisticMinting ```solidity function unpauseOptimisticMinting() external ``` Unpauses the optimistic minting. ### beginOptimisticMintingFeeUpdate ```solidity function beginOptimisticMintingFeeUpdate(uint32 _newOptimisticMintingFeeDivisor) external ``` Begins the process of updating optimistic minting fee. The fee is computed as follows: `fee = amount / optimisticMintingFeeDivisor`. For example, if the fee needs to be 2% of each deposit, the `optimisticMintingFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. See the documentation for optimisticMintingFeeDivisor. ### finalizeOptimisticMintingFeeUpdate ```solidity function finalizeOptimisticMintingFeeUpdate() external ``` Finalizes the update process of the optimistic minting fee. ### beginOptimisticMintingDelayUpdate ```solidity function beginOptimisticMintingDelayUpdate(uint32 _newOptimisticMintingDelay) external ``` Begins the process of updating optimistic minting delay. ### finalizeOptimisticMintingDelayUpdate ```solidity function finalizeOptimisticMintingDelayUpdate() external ``` Finalizes the update process of the optimistic minting delay. ### calculateDepositKey ```solidity function calculateDepositKey(bytes32 fundingTxHash, uint32 fundingOutputIndex) public pure returns (uint256) ``` Calculates deposit key the same way as the Bridge contract. The deposit key is computed as `keccak256(fundingTxHash | fundingOutputIndex)`. ### repayOptimisticMintingDebt ```solidity function repayOptimisticMintingDebt(address depositor, uint256 amount) internal returns (uint256) ``` Used by `TBTCVault.receiveBalanceIncrease` to repay the optimistic minting debt before TBTC is minted. When optimistic minting is finalized, debt equal to the value of the deposit being a subject of the optimistic minting is incurred. When `TBTCVault` sweeps a deposit, the debt is fully or partially paid off, no matter if that particular deposit was used for the optimistic minting or not. See `TBTCVault.receiveBalanceIncrease` #### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------------------------------- | | depositor | address | The depositor whose balance increase is received. | | amount | uint256 | The balance increase amount for the depositor received. | #### Return Values | Name | Type | Description | | ---- | ------- | ----------------------------------------------------------------------------------- | | \[0] | uint256 | The TBTC amount that should be minted after paying off the optimistic minting debt. | # TBTCVault ## TBTCVault TBTC is a fully Bitcoin-backed ERC-20 token pegged to the price of Bitcoin. It facilitates Bitcoin holders to act on the Ethereum blockchain and access the decentralized finance (DeFi) ecosystem. TBTC Vault mints and unmints TBTC based on Bitcoin balances in the Bank. TBTC Vault is the owner of TBTC token contract and is the only contract minting the token. ### bank ```solidity contract Bank bank ``` ### tbtcToken ```solidity contract TBTC tbtcToken ``` ### newVault ```solidity address newVault ``` The address of a new TBTC vault. Set only when the upgrade process is pending. Once the upgrade gets finalized, the new TBTC vault will become an owner of TBTC token. ### upgradeInitiatedTimestamp ```solidity uint256 upgradeInitiatedTimestamp ``` The timestamp at which an upgrade to a new TBTC vault was initiated. Set only when the upgrade process is pending. ### Minted ```solidity event Minted(address to, uint256 amount) ``` ### Unminted ```solidity event Unminted(address from, uint256 amount) ``` ### UpgradeInitiated ```solidity event UpgradeInitiated(address newVault, uint256 timestamp) ``` ### UpgradeFinalized ```solidity event UpgradeFinalized(address newVault) ``` ### onlyBank ```solidity modifier onlyBank() ``` ### constructor ```solidity constructor(contract Bank _bank, contract TBTC _tbtcToken, contract Bridge _bridge) public ``` ### mint ```solidity function mint(uint256 amount) external ``` Mints the given `amount` of TBTC to the caller previously transferring `amount / SATOSHI_MULTIPLIER` of the Bank balance from caller to TBTC Vault. If `amount` is not divisible by SATOSHI\_MULTIPLIER, the remainder is left on the caller's Bank balance. TBTC Vault must have an allowance for caller's balance in the Bank for at least `amount / SATOSHI_MULTIPLIER`. #### Parameters | Name | Type | Description | | ------ | ------- | ----------------------- | | amount | uint256 | Amount of TBTC to mint. | ### receiveBalanceApproval ```solidity function receiveBalanceApproval(address owner, uint256 satoshis, bytes) external ``` Transfers `satoshis` of the Bank balance from the caller to TBTC Vault and mints `satoshis * SATOSHI_MULTIPLIER` of TBTC to the caller. Can only be called by the Bank via `approveBalanceAndCall`. #### Parameters | Name | Type | Description | | -------- | ------- | ------------------------------------------ | | owner | address | The owner who approved their Bank balance. | | satoshis | uint256 | Amount of satoshis used to mint TBTC. | | | bytes | | ### receiveBalanceIncrease ```solidity function receiveBalanceIncrease(address[] depositors, uint256[] depositedSatoshiAmounts) external ``` Mints the same amount of TBTC as the deposited satoshis amount multiplied by SATOSHI\_MULTIPLIER for each depositor in the array. Can only be called by the Bank after the Bridge swept deposits and Bank increased balance for the vault. Fails if `depositors` array is empty. Expects the length of `depositors` and `depositedSatoshiAmounts` is the same. ### unmint ```solidity function unmint(uint256 amount) external ``` Burns `amount` of TBTC from the caller's balance and transfers `amount / SATOSHI_MULTIPLIER` back to the caller's balance in the Bank. If `amount` is not divisible by SATOSHI\_MULTIPLIER, the remainder is left on the caller's account. Caller must have at least `amount` of TBTC approved to TBTC Vault. #### Parameters | Name | Type | Description | | ------ | ------- | ------------------------- | | amount | uint256 | Amount of TBTC to unmint. | ### unmintAndRedeem ```solidity function unmintAndRedeem(uint256 amount, bytes redemptionData) external ``` Burns `amount` of TBTC from the caller's balance and transfers `amount / SATOSHI_MULTIPLIER` of Bank balance to the Bridge requesting redemption based on the provided `redemptionData`. If `amount` is not divisible by SATOSHI\_MULTIPLIER, the remainder is left on the caller's account. Caller must have at least `amount` of TBTC approved to TBTC Vault. #### Parameters | Name | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | amount | uint256 | Amount of TBTC to unmint and request to redeem in Bridge. | | redemptionData | bytes | Redemption data in a format expected from `redemptionData` parameter of Bridge's `receiveBalanceApproval` function. | ### receiveApproval ```solidity function receiveApproval(address from, uint256 amount, address token, bytes extraData) external ``` Burns `amount` of TBTC from the caller's balance. If `extraData` is empty, transfers `amount` back to the caller's balance in the Bank. If `extraData` is not empty, requests redemption in the Bridge using the `extraData` as a `redemptionData` parameter to Bridge's `receiveBalanceApproval` function. If `amount` is not divisible by SATOSHI\_MULTIPLIER, the remainder is left on the caller's account. Note that it may left a token approval equal to the remainder. This function is doing the same as `unmint` or `unmintAndRedeem` (depending on `extraData` parameter) but it allows to execute unminting without a separate approval transaction. The function can be called only via `approveAndCall` of TBTC token. #### Parameters | Name | Type | Description | | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | from | address | TBTC token holder executing unminting. | | amount | uint256 | Amount of TBTC to unmint. | | token | address | TBTC token address. | | extraData | bytes | Redemption data in a format expected from `redemptionData` parameter of Bridge's `receiveBalanceApproval` function. If empty, `receiveApproval` is not requesting a redemption of Bank balance but is instead performing just TBTC unminting to a Bank balance. | ### initiateUpgrade ```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 1:1 ratio. The caller needs to have at least `amount` of tBTC v1 balance approved for transfer to the `VendingMachineV3` 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 `VendingMachineV3` before calling this function. This function is a shortcut for `approve` + `exchange`. 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 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. `VendingMachineV3` 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 `VendingMachineV3` 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. | ### withdrawTbtcV2 ```solidity function withdrawTbtcV2(address recipient, uint256 amount) external ``` Allows the governance to withdraw tBTC v2 deposited into this contract. 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. #### Parameters | Name | Type | Description | | --------- | ------- | -------------------------------------------------- | | recipient | address | The address which should receive withdrawn tokens. | | amount | uint256 | The amount to withdraw. | ### recoverFunds ```solidity function recoverFunds(contract IERC20 token, address recipient, uint256 amount) external ``` Allows the governance to recover ERC20 sent to this contract by mistake or tBTC v1 locked in the contract to exchange to tBTC v2. No tBTC v2 can be withdrawn using this function. #### Parameters | Name | Type | Description | | --------- | --------------- | -------------------------------------------------- | | token | contract IERC20 | The address of a token to recover. | | recipient | address | The address which should receive recovered tokens. | | amount | uint256 | The amount to recover. | ### \_exchange ```solidity function _exchange(address tokenOwner, uint256 amount) internal ``` # WalletCoordinator ## WalletCoordinator The wallet coordinator contract aims to facilitate the coordination of the off-chain wallet members during complex multi-chain wallet operations like deposit sweeping, redemptions, or moving funds. Such processes involve various moving parts and many steps that each individual wallet member must do. Given the distributed nature of the off-chain wallet software, full off-chain implementation is challenging and prone to errors, especially byzantine faults. This contract provides a single and trusted on-chain coordination point thus taking the riskiest part out of the off-chain software. The off-chain wallet members can focus on the core tasks and do not bother about electing a trusted coordinator or aligning internal states using complex consensus algorithms. ### WalletAction ```solidity enum WalletAction { Idle, Heartbeat, DepositSweep, Redemption, MovingFunds, MovedFundsSweep } ``` ### WalletLock ```solidity struct WalletLock { uint32 expiresAt; enum WalletCoordinator.WalletAction cause; } ``` ### DepositSweepProposal ```solidity struct DepositSweepProposal { bytes20 walletPubKeyHash; struct WalletCoordinator.DepositKey[] depositsKeys; uint256 sweepTxFee; uint256[] depositsRevealBlocks; } ``` ### DepositKey ```solidity struct DepositKey { bytes32 fundingTxHash; uint32 fundingOutputIndex; } ``` ### DepositExtraInfo ```solidity struct DepositExtraInfo { struct BitcoinTx.Info fundingTx; bytes8 blindingFactor; bytes20 walletPubKeyHash; bytes20 refundPubKeyHash; bytes4 refundLocktime; } ``` ### RedemptionProposal ```solidity struct RedemptionProposal { bytes20 walletPubKeyHash; bytes[] redeemersOutputScripts; uint256 redemptionTxFee; } ``` ### isCoordinator ```solidity mapping(address => bool) isCoordinator ``` Mapping that holds addresses allowed to submit proposals and request heartbeats. ### walletLock ```solidity mapping(bytes20 => struct WalletCoordinator.WalletLock) walletLock ``` Mapping that holds wallet time locks. The key is a 20-byte wallet public key hash. ### bridge ```solidity contract Bridge bridge ``` Handle to the Bridge contract. ### heartbeatRequestValidity ```solidity uint32 heartbeatRequestValidity ``` Determines the wallet heartbeat request validity time. In other words, this is the worst-case time for a wallet heartbeat during which the wallet is busy and canot take other actions. This is also the duration of the time lock applied to the wallet once a new heartbeat request is submitted. For example, if a deposit sweep proposal was submitted at 2 pm and heartbeatRequestValidity is 1 hour, the next request or proposal (of any type) can be submitted after 3 pm. ### heartbeatRequestGasOffset ```solidity uint32 heartbeatRequestGasOffset ``` Gas that is meant to balance the heartbeat request overall cost. Can be updated by the owner based on the current conditions. ### depositSweepProposalValidity ```solidity uint32 depositSweepProposalValidity ``` Determines the deposit sweep proposal validity time. In other words, this is the worst-case time for a deposit sweep during which the wallet is busy and cannot take another actions. This is also the duration of the time lock applied to the wallet once a new deposit sweep proposal is submitted. For example, if a deposit sweep proposal was submitted at 2 pm and depositSweepProposalValidity is 4 hours, the next proposal (of any type) can be submitted after 6 pm. ### depositMinAge ```solidity uint32 depositMinAge ``` The minimum time that must elapse since the deposit reveal before a deposit becomes eligible for a deposit sweep. For example, if a deposit was revealed at 9 am and depositMinAge is 2 hours, the deposit is eligible for sweep after 11 am. Forcing deposit minimum age ensures block finality for Ethereum. In the happy path case, i.e. where the deposit is revealed immediately after being broadcast on the Bitcoin network, the minimum age check also ensures block finality for Bitcoin. ### depositRefundSafetyMargin ```solidity uint32 depositRefundSafetyMargin ``` Each deposit can be technically swept until it reaches its refund timestamp after which it can be taken back by the depositor. However, allowing the wallet to sweep deposits that are close to their refund timestamp may cause a race between the wallet and the depositor. In result, the wallet may sign an invalid sweep transaction that aims to sweep an already refunded deposit. Such tx signature may be used to create an undefeatable fraud challenge against the wallet. In order to mitigate that problem, this parameter determines a safety margin that puts the latest moment a deposit can be swept far before the point after which the deposit becomes refundable. For example, if a deposit becomes refundable after 8 pm and depositRefundSafetyMargin is 6 hours, the deposit is valid for for a sweep only before 2 pm. ### depositSweepMaxSize ```solidity uint16 depositSweepMaxSize ``` The maximum count of deposits that can be swept within a single sweep. ### depositSweepProposalSubmissionGasOffset ```solidity uint32 depositSweepProposalSubmissionGasOffset ``` Gas that is meant to balance the deposit sweep proposal submission overall cost. Can be updated by the owner based on the current conditions. ### redemptionProposalValidity ```solidity uint32 redemptionProposalValidity ``` Determines the redemption proposal validity time. In other words, this is the worst-case time for a redemption during which the wallet is busy and cannot take another actions. This is also the duration of the time lock applied to the wallet once a new redemption proposal is submitted. For example, if a redemption proposal was submitted at 2 pm and redemptionProposalValidity is 2 hours, the next proposal (of any type) can be submitted after 4 pm. ### redemptionRequestMinAge ```solidity uint32 redemptionRequestMinAge ``` The minimum time that must elapse since the redemption request creation before a request becomes eligible for a processing. For example, if a request was created at 9 am and redemptionRequestMinAge is 2 hours, the request is eligible for processing after 11 am. Forcing request minimum age ensures block finality for Ethereum. ### redemptionRequestTimeoutSafetyMargin ```solidity uint32 redemptionRequestTimeoutSafetyMargin ``` Each redemption request can be technically handled until it reaches its timeout timestamp after which it can be reported as timed out. However, allowing the wallet to handle requests that are close to their timeout timestamp may cause a race between the wallet and the redeemer. In result, the wallet may redeem the requested funds even though the redeemer already received back their tBTC (locked during redemption request) upon reporting the request timeout. In effect, the redeemer may end out with both tBTC and redeemed BTC in their hands which has a negative impact on the tBTC <-> BTC peg. In order to mitigate that problem, this parameter determines a safety margin that puts the latest moment a request can be handled far before the point after which the request can be reported as timed out. For example, if a request times out after 8 pm and redemptionRequestTimeoutSafetyMargin is 2 hours, the request is valid for processing only before 6 pm. ### redemptionMaxSize ```solidity uint16 redemptionMaxSize ``` The maximum count of redemption requests that can be processed within a single redemption. ### redemptionProposalSubmissionGasOffset ```solidity uint32 redemptionProposalSubmissionGasOffset ``` Gas that is meant to balance the redemption proposal submission overall cost. Can be updated by the owner based on the current conditions. ### CoordinatorAdded ```solidity event CoordinatorAdded(address coordinator) ``` ### CoordinatorRemoved ```solidity event CoordinatorRemoved(address coordinator) ``` ### WalletManuallyUnlocked ```solidity event WalletManuallyUnlocked(bytes20 walletPubKeyHash) ``` ### HeartbeatRequestParametersUpdated ```solidity event HeartbeatRequestParametersUpdated(uint32 heartbeatRequestValidity, uint32 heartbeatRequestGasOffset) ``` ### HeartbeatRequestSubmitted ```solidity event HeartbeatRequestSubmitted(bytes20 walletPubKeyHash, bytes message, address coordinator) ``` ### DepositSweepProposalParametersUpdated ```solidity event DepositSweepProposalParametersUpdated(uint32 depositSweepProposalValidity, uint32 depositMinAge, uint32 depositRefundSafetyMargin, uint16 depositSweepMaxSize, uint32 depositSweepProposalSubmissionGasOffset) ``` ### DepositSweepProposalSubmitted ```solidity event DepositSweepProposalSubmitted(struct WalletCoordinator.DepositSweepProposal proposal, address coordinator) ``` ### RedemptionProposalParametersUpdated ```solidity event RedemptionProposalParametersUpdated(uint32 redemptionProposalValidity, uint32 redemptionRequestMinAge, uint32 redemptionRequestTimeoutSafetyMargin, uint16 redemptionMaxSize, uint32 redemptionProposalSubmissionGasOffset) ``` ### RedemptionProposalSubmitted ```solidity event RedemptionProposalSubmitted(struct WalletCoordinator.RedemptionProposal proposal, address coordinator) ``` ### onlyCoordinator ```solidity modifier onlyCoordinator() ``` ### onlyAfterWalletLock ```solidity modifier onlyAfterWalletLock(bytes20 walletPubKeyHash) ``` ### onlyReimbursableAdmin ```solidity modifier onlyReimbursableAdmin() ``` ### initialize ```solidity function initialize(contract Bridge _bridge) external ``` ### addCoordinator ```solidity function addCoordinator(address coordinator) external ``` Adds the given address to the set of coordinator addresses. Requirements: * The caller must be the owner, * The `coordinator` must not be an existing coordinator. #### Parameters | Name | Type | Description | | ----------- | ------- | ------------------------------- | | coordinator | address | Address of the new coordinator. | ### removeCoordinator ```solidity function removeCoordinator(address coordinator) external ``` Removes the given address from the set of coordinator addresses. Requirements: * The caller must be the owner, * The `coordinator` must be an existing coordinator. #### Parameters | Name | Type | Description | | ----------- | ------- | ------------------------------------ | | coordinator | address | Address of the existing coordinator. | ### unlockWallet ```solidity function unlockWallet(bytes20 walletPubKeyHash) external ``` Allows to unlock the given wallet before their time lock expires. This function should be used in exceptional cases where something went wrong and there is a need to unlock the wallet without waiting. Requirements: * The caller must be the owner. #### Parameters | Name | Type | Description | | ---------------- | ------- | ------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet | ### updateHeartbeatRequestParameters ```solidity function updateHeartbeatRequestParameters(uint32 _heartbeatRequestValidity, uint32 _heartbeatRequestGasOffset) external ``` Updates parameters related to heartbeat request. Requirements: * The caller must be the owner. #### Parameters | Name | Type | Description | | --------------------------- | ------ | --------------------------------------------- | | \_heartbeatRequestValidity | uint32 | The new value of `heartbeatRequestValidity`. | | \_heartbeatRequestGasOffset | uint32 | The new value of `heartbeatRequestGasOffset`. | ### updateDepositSweepProposalParameters ```solidity function updateDepositSweepProposalParameters(uint32 _depositSweepProposalValidity, uint32 _depositMinAge, uint32 _depositRefundSafetyMargin, uint16 _depositSweepMaxSize, uint32 _depositSweepProposalSubmissionGasOffset) external ``` Updates parameters related to deposit sweep proposal. Requirements: * The caller must be the owner. #### Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------ | | \_depositSweepProposalValidity | uint32 | The new value of `depositSweepProposalValidity`. | | \_depositMinAge | uint32 | The new value of `depositMinAge`. | | \_depositRefundSafetyMargin | uint32 | The new value of `depositRefundSafetyMargin`. | | \_depositSweepMaxSize | uint16 | The new value of `depositSweepMaxSize`. | | \_depositSweepProposalSubmissionGasOffset | uint32 | | ### requestHeartbeat ```solidity function requestHeartbeat(bytes20 walletPubKeyHash, bytes message) public ``` Submits a heartbeat request from the wallet. Locks the wallet for a specific time, equal to the request validity period. This function validates the proposed heartbeat messge to see if it matches the heartbeat format expected by the Bridge. Requirements: * The caller is a coordinator, * The wallet is not time-locked, * The message to sign is a valid heartbeat message. #### Parameters | Name | Type | Description | | ---------------- | ------- | -------------------------------------------------------------------------------- | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet that is supposed to execute the heartbeat. | | message | bytes | The proposed heartbeat message for the wallet to sign. | ### requestHeartbeatWithReimbursement ```solidity function requestHeartbeatWithReimbursement(bytes20 walletPubKeyHash, bytes message) external ``` Wraps `requestHeartbeat` call and reimburses the caller's transaction cost. See `requestHeartbeat` function documentation. ### submitDepositSweepProposal ```solidity function submitDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal) public ``` Submits a deposit sweep proposal. Locks the target wallet for a specific time, equal to the proposal validity period. This function does not store the proposal in the state but just emits an event that serves as a guiding light for wallet off-chain members. Wallet members are supposed to validate the proposal on their own, before taking any action. Requirements: * The caller is a coordinator, * The wallet is not time-locked. #### Parameters | Name | Type | Description | | -------- | --------------------------------------------- | -------------------------- | | proposal | struct WalletCoordinator.DepositSweepProposal | The deposit sweep proposal | ### submitDepositSweepProposalWithReimbursement ```solidity function submitDepositSweepProposalWithReimbursement(struct WalletCoordinator.DepositSweepProposal proposal) external ``` Wraps `submitDepositSweepProposal` call and reimburses the caller's transaction cost. See `submitDepositSweepProposal` function documentation. ### validateDepositSweepProposal ```solidity function validateDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal, struct WalletCoordinator.DepositExtraInfo[] depositsExtraInfo) external view returns (bool) ``` View function encapsulating the main rules of a valid deposit sweep proposal. This function is meant to facilitate the off-chain validation of the incoming proposals. Thanks to it, most of the work can be done using a single readonly contract call. Worth noting, the validation done here is not exhaustive as some conditions may not be verifiable within the on-chain function or checking them may be easier on the off-chain side. For example, this function does not check the SPV proofs and confirmations of the deposit funding transactions as this would require an integration with the difficulty relay that greatly increases complexity. Instead of that, each off-chain wallet member is supposed to do that check on their own. Requirements: * The target wallet must be in the Live state, * The number of deposits included in the sweep must be in the range \[1, `depositSweepMaxSize`], * The length of `depositsExtraInfo` array must be equal to the length of `proposal.depositsKeys`, i.e. each deposit must have exactly one set of corresponding extra data, * The proposed sweep tx fee must be grater than zero, * The proposed maximum per-deposit sweep tx fee must be lesser than or equal the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`), * Each deposit must be revealed to the Bridge, * Each deposit must be old enough, i.e. at least `depositMinAge` elapsed since their reveal time, * Each deposit must not be swept yet, * Each deposit must have valid extra data (see `validateDepositExtraInfo`), * Each deposit must have the refund safety margin preserved, * Each deposit must be controlled by the same wallet, * Each deposit must target the same vault, * Each deposit must be unique. The following off-chain validation must be performed as a bare minimum: * Inputs used for the sweep transaction have enough Bitcoin confirmations, * Deposits revealed to the Bridge have enough Ethereum confirmations. #### Parameters | Name | Type | Description | | ----------------- | --------------------------------------------- | ------------------------------------------------------- | | proposal | struct WalletCoordinator.DepositSweepProposal | The sweeping proposal to validate. | | depositsExtraInfo | struct WalletCoordinator.DepositExtraInfo\[] | Deposits extra data required to perform the validation. | #### Return Values | Name | Type | Description | | ---- | ---- | ------------------------------------------------- | | \[0] | bool | True if the proposal is valid. Reverts otherwise. | ### validateSweepTxFee ```solidity function validateSweepTxFee(uint256 sweepTxFee, uint256 depositsCount) internal view ``` Validates the sweep tx fee by checking if the part of the fee incurred by each deposit does not exceed the maximum value allowed by the Bridge. This function is heavily based on `DepositSweep.depositSweepTxFeeDistribution` function. Requirements: * The sweep tx fee must be grater than zero, * The maximum per-deposit sweep tx fee must be lesser than or equal the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`). #### Parameters | Name | Type | Description | | ------------- | ------- | ----------------------------------------------------- | | sweepTxFee | uint256 | The sweep transaction fee. | | depositsCount | uint256 | Count of the deposits swept by the sweep transaction. | ### validateDepositExtraInfo ```solidity function validateDepositExtraInfo(struct WalletCoordinator.DepositKey depositKey, address depositor, struct WalletCoordinator.DepositExtraInfo depositExtraInfo) internal view ``` Validates the extra data for the given deposit. This function is heavily based on `Deposit.revealDeposit` function. Requirements: * The transaction hash computed using `depositExtraInfo.fundingTx` must match the `depositKey.fundingTxHash`. This requirement ensures the funding transaction data provided in the extra data container actually represent the funding transaction of the given deposit. * The P2(W)SH script inferred from `depositExtraInfo` is actually used to lock funds by the `depositKey.fundingOutputIndex` output of the `depositExtraInfo.fundingTx` transaction. This requirement ensures the reveal data provided in the extra data container actually matches the given deposit. #### Parameters | Name | Type | Description | | ---------------- | ----------------------------------------- | ------------------------------------------- | | depositKey | struct WalletCoordinator.DepositKey | Key of the given deposit. | | depositor | address | Depositor that revealed the deposit. | | depositExtraInfo | struct WalletCoordinator.DepositExtraInfo | Extra data being subject of the validation. | ### updateRedemptionProposalParameters ```solidity function updateRedemptionProposalParameters(uint32 _redemptionProposalValidity, uint32 _redemptionRequestMinAge, uint32 _redemptionRequestTimeoutSafetyMargin, uint16 _redemptionMaxSize, uint32 _redemptionProposalSubmissionGasOffset) external ``` Updates parameters related to redemption proposal. Requirements: * The caller must be the owner. #### Parameters | Name | Type | Description | | --------------------------------------- | ------ | --------------------------------------------------------- | | \_redemptionProposalValidity | uint32 | The new value of `redemptionProposalValidity`. | | \_redemptionRequestMinAge | uint32 | The new value of `redemptionRequestMinAge`. | | \_redemptionRequestTimeoutSafetyMargin | uint32 | The new value of `redemptionRequestTimeoutSafetyMargin`. | | \_redemptionMaxSize | uint16 | The new value of `redemptionMaxSize`. | | \_redemptionProposalSubmissionGasOffset | uint32 | The new value of `redemptionProposalSubmissionGasOffset`. | ### submitRedemptionProposal ```solidity function submitRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) public ``` Submits a redemption proposal. Locks the target wallet for a specific time, equal to the proposal validity period. This function does not store the proposal in the state but just emits an event that serves as a guiding light for wallet off-chain members. Wallet members are supposed to validate the proposal on their own, before taking any action. Requirements: * The caller is a coordinator, * The wallet is not time-locked. #### Parameters | Name | Type | Description | | -------- | ------------------------------------------- | ----------------------- | | proposal | struct WalletCoordinator.RedemptionProposal | The redemption proposal | ### submitRedemptionProposalWithReimbursement ```solidity function submitRedemptionProposalWithReimbursement(struct WalletCoordinator.RedemptionProposal proposal) external ``` Wraps `submitRedemptionProposal` call and reimburses the caller's transaction cost. See `submitRedemptionProposal` function documentation. ### validateRedemptionProposal ```solidity function validateRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) external view returns (bool) ``` View function encapsulating the main rules of a valid redemption proposal. This function is meant to facilitate the off-chain validation of the incoming proposals. Thanks to it, most of the work can be done using a single readonly contract call. Requirements: * The target wallet must be in the Live state, * The number of redemption requests included in the redemption proposal must be in the range \[1, `redemptionMaxSize`], * The proposed redemption tx fee must be grater than zero, * The proposed redemption tx fee must be lesser than or equal to the maximum total fee allowed by the Bridge (`Bridge.redemptionTxMaxTotalFee`), * The proposed maximum per-request redemption tx fee share must be lesser than or equal to the maximum fee share allowed by the given request (`RedemptionRequest.txMaxFee`), * Each request must be a pending request registered in the Bridge, * Each request must be old enough, i.e. at least `redemptionRequestMinAge` elapsed since their creation time, * Each request must have the timeout safety margin preserved, * Each request must be unique. #### Parameters | Name | Type | Description | | -------- | ------------------------------------------- | ------------------------------------ | | proposal | struct WalletCoordinator.RedemptionProposal | The redemption proposal to validate. | #### Return Values | Name | Type | Description | | ---- | ---- | ------------------------------------------------- | | \[0] | bool | True if the proposal is valid. Reverts otherwise. | # Wallets ## Wallets Library responsible for handling integration between Bridge contract and ECDSA wallets. ### WalletState ```solidity enum WalletState { Unknown, Live, MovingFunds, Closing, Closed, Terminated } ``` ### Wallet ```solidity struct Wallet { bytes32 ecdsaWalletID; bytes32 mainUtxoHash; uint64 pendingRedemptionsValue; uint32 createdAt; uint32 movingFundsRequestedAt; uint32 closingStartedAt; uint32 pendingMovedFundsSweepRequestsCount; enum Wallets.WalletState state; bytes32 movingFundsTargetWalletsCommitmentHash; } ``` ### NewWalletRequested ```solidity event NewWalletRequested() ``` ### NewWalletRegistered ```solidity event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletMovingFunds ```solidity event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletClosing ```solidity event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletClosed ```solidity event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### WalletTerminated ```solidity event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) ``` ### requestNewWallet ```solidity function requestNewWallet(struct BridgeState.Storage self, struct BitcoinTx.UTXO activeWalletMainUtxo) external ``` Requests creation of a new wallet. This function just forms a request and the creation process is performed asynchronously. Outcome of that process should be delivered using `registerNewWallet` function. Requirements: * `activeWalletMainUtxo` components must point to the recent main UTXO of the given active wallet, as currently known on the Ethereum chain. If there is no active wallet at the moment, or the active wallet has no main UTXO, this parameter can be empty as it is ignored, * Wallet creation must not be in progress, * If the active wallet is set, one of the following conditions must be true: * The active wallet BTC balance is above the minimum threshold and the active wallet is old enough, i.e. the creation period was elapsed since its creation time, * The active wallet BTC balance is above the maximum threshold. #### Parameters | Name | Type | Description | | -------------------- | -------------------------- | -------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | activeWalletMainUtxo | struct BitcoinTx.UTXO | Data of the active wallet's main UTXO, as currently known on the Ethereum chain. | ### registerNewWallet ```solidity function registerNewWallet(struct BridgeState.Storage self, bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) external ``` Registers a new wallet. This function should be called after the wallet creation process initiated using `requestNewWallet` completes and brings the outcomes. Requirements: * The only caller authorized to call this function is `registry`, * Given wallet data must not belong to an already registered wallet. #### Parameters | Name | Type | Description | | ------------- | -------------------------- | ----------------------------------- | | self | struct BridgeState.Storage | | | ecdsaWalletID | bytes32 | Wallet's unique identifier. | | publicKeyX | bytes32 | Wallet's public key's X coordinate. | | publicKeyY | bytes32 | Wallet's public key's Y coordinate. | ### notifyWalletRedemptionTimeout ```solidity function notifyWalletRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal ``` Handles a notification about a wallet redemption timeout. Triggers the wallet moving funds process only if the wallet is still in the Live state. That means multiple action timeouts can be reported for the same wallet but only the first report requests the wallet to move their funds. Executes slashing if the wallet is in Live or MovingFunds state. Allows to notify redemption timeout also for a Terminated wallet in case the redemption was requested before the wallet got terminated. Requirements: * The wallet must be in the `Live`, `MovingFunds`, or `Terminated` state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------ | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### notifyWalletHeartbeatFailed ```solidity function notifyWalletHeartbeatFailed(struct BridgeState.Storage self, bytes32 publicKeyX, bytes32 publicKeyY) external ``` Handles a notification about a wallet heartbeat failure and triggers the wallet moving funds process. Requirements: * The only caller authorized to call this function is `registry`, * Wallet must be in Live state. #### Parameters | Name | Type | Description | | ---------- | -------------------------- | ----------------------------------- | | self | struct BridgeState.Storage | | | publicKeyX | bytes32 | Wallet's public key's X coordinate. | | publicKeyY | bytes32 | Wallet's public key's Y coordinate. | ### notifyWalletCloseable ```solidity function notifyWalletCloseable(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external ``` Notifies that the wallet is either old enough or has too few satoshis left and qualifies to be closed. Requirements: * Wallet must not be set as the current active wallet, * Wallet must exceed the wallet maximum age OR the wallet BTC balance must be lesser than the minimum threshold. If the latter case is true, the `walletMainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If the wallet has no main UTXO, this parameter can be empty as it is ignored since the wallet balance is assumed to be zero, * Wallet must be in Live state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | ### notifyWalletClosingPeriodElapsed ```solidity function notifyWalletClosingPeriodElapsed(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal ``` Notifies about the end of the closing period for the given wallet. Closes the wallet ultimately and notifies the ECDSA registry about this fact. Requirements: * The wallet must be in the Closing state, * The wallet closing period must have elapsed. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### notifyWalletFundsMoved ```solidity function notifyWalletFundsMoved(struct BridgeState.Storage self, bytes20 walletPubKeyHash, bytes32 targetWalletsHash) internal ``` Notifies that the wallet completed the moving funds process successfully. Checks if the funds were moved to the expected target wallets. Closes the source wallet if everything went good and reverts otherwise. Requirements: * The caller must make sure the moving funds transaction actually happened on Bitcoin chain and fits the protocol requirements, * The source wallet must be in the MovingFunds state, * The target wallets commitment must be submitted by the source wallet, * The actual target wallets used in the moving funds transaction must be exactly the same as the target wallets commitment. #### Parameters | Name | Type | Description | | ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | targetWalletsHash | bytes32 | 32-byte keccak256 hash over the list of 20-byte public key hashes of the target wallets actually used within the moving funds transactions. | ### notifyWalletMovingFundsBelowDust ```solidity function notifyWalletMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal ``` Called when a MovingFunds wallet has a balance below the dust threshold. Begins the wallet closing. Requirements: * The wallet must be in the MovingFunds state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### notifyWalletMovingFundsTimeout ```solidity function notifyWalletMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal ``` Called when the timeout for MovingFunds for the wallet elapsed. Slashes wallet members and terminates the wallet. Requirements: * The wallet must be in the MovingFunds state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------ | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### notifyWalletMovedFundsSweepTimeout ```solidity function notifyWalletMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal ``` Called when a wallet which was asked to sweep funds moved from another wallet did not provide a sweeping proof before a timeout. Slashes and terminates the wallet who failed to provide a proof. Requirements: * The wallet must be in the `Live`, `MovingFunds`, or `Terminated` state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------ | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet which was supposed to sweep funds. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### notifyWalletFraudChallengeDefeatTimeout ```solidity function notifyWalletFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, address challenger) internal ``` Called when a wallet which was challenged for a fraud did not defeat the challenge before the timeout. Slashes and terminates the wallet who failed to defeat the challenge. If the wallet is already terminated, it does nothing. Requirements: * The wallet must be in the `Live`, `MovingFunds`, `Closing` or `Terminated` state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------ | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet which was supposed to sweep funds. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | | challenger | address | Address of the party which submitted the fraud challenge. | ### moveFunds ```solidity function moveFunds(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal ``` Requests a wallet to move their funds. If the wallet balance is zero, the wallet closing begins immediately. If the move funds request refers to the current active wallet, such a wallet is no longer considered active and the active wallet slot is unset allowing to trigger a new wallet creation immediately. Requirements: * The caller must make sure that the wallet is in the Live state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### beginWalletClosing ```solidity function beginWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal ``` Begins the closing period of the given wallet. Requirements: * The caller must make sure that the wallet is in the MovingFunds state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### finalizeWalletClosing ```solidity function finalizeWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal ``` Finalizes the closing period of the given wallet and notifies the ECDSA registry about this fact. Requirements: * The caller must make sure that the wallet is in the Closing state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### terminateWallet ```solidity function terminateWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal ``` Terminates the given wallet and notifies the ECDSA registry about this fact. If the wallet termination refers to the current active wallet, such a wallet is no longer considered active and the active wallet slot is unset allowing to trigger a new wallet creation immediately. Requirements: * The caller must make sure that the wallet is in the Live or MovingFunds or Closing state. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | -------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | ### getWalletBtcBalance ```solidity function getWalletBtcBalance(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) internal view returns (uint64 walletBtcBalance) ``` Gets BTC balance for given the wallet. Requirements: * `walletMainUtxo` components must point to the recent main UTXO of the given wallet, as currently known on the Ethereum chain. If the wallet has no main UTXO, this parameter can be empty as it is ignored. #### Parameters | Name | Type | Description | | ---------------- | -------------------------- | ------------------------------------------------------------------------- | | self | struct BridgeState.Storage | | | walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | | walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | #### Return Values | Name | Type | Description | | ---------------- | ------ | ----------------------------------------- | | walletBtcBalance | uint64 | Current BTC balance for the given wallet. | # ECDSA API You can learn about APIs of contracts related to ECDSA under the following links: [EcdsaAuthorization](/app-development/tbtc-contracts-api/ecdsa-api/ecdsaauthorization) [EcdsaDkg](/app-development/tbtc-contracts-api/ecdsa-api/ecdsadkg) [EcdsaDkgValidator](/app-development/tbtc-contracts-api/ecdsa-api/ecdsadkgvalidator) [EcdsaInactivity](/app-development/tbtc-contracts-api/ecdsa-api/ecdsainactivity) [IWalletOwner](/app-development/tbtc-contracts-api/ecdsa-api/iwalletowner) [IWalletRegistry](/app-development/tbtc-contracts-api/ecdsa-api/iwalletregistry) [WalletRegistry](/app-development/tbtc-contracts-api/ecdsa-api/walletregistry) [WalletRegistryGovernance](/app-development/tbtc-contracts-api/ecdsa-api/walletregistrygovernance) [Wallets](/app-development/tbtc-contracts-api/ecdsa-api/wallets) # EcdsaAuthorization ## EcdsaAuthorization Library managing the state of stake authorizations for ECDSA operator contract and the presence of operators in the sortition pool based on the stake authorized for them. ### Parameters ```solidity struct Parameters { uint96 minimumAuthorization; uint64 authorizationDecreaseDelay; uint64 authorizationDecreaseChangePeriod; } ``` ### AuthorizationDecrease ```solidity struct AuthorizationDecrease { uint96 decreasingBy; uint64 decreasingAt; } ``` ### Data ```solidity struct Data { struct EcdsaAuthorization.Parameters parameters; mapping(address => address) stakingProviderToOperator; mapping(address => address) operatorToStakingProvider; mapping(address => struct EcdsaAuthorization.AuthorizationDecrease) pendingDecreases; uint256[46] __gap; } ``` ### OperatorRegistered ```solidity event OperatorRegistered(address stakingProvider, address operator) ``` ### AuthorizationIncreased ```solidity event AuthorizationIncreased(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount) ``` ### AuthorizationDecreaseRequested ```solidity event AuthorizationDecreaseRequested(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount, uint64 decreasingAt) ``` ### AuthorizationDecreaseApproved ```solidity event AuthorizationDecreaseApproved(address stakingProvider) ``` ### InvoluntaryAuthorizationDecreaseFailed ```solidity event InvoluntaryAuthorizationDecreaseFailed(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount) ``` ### OperatorJoinedSortitionPool ```solidity event OperatorJoinedSortitionPool(address stakingProvider, address operator) ``` ### OperatorStatusUpdated ```solidity event OperatorStatusUpdated(address stakingProvider, address operator) ``` ### setMinimumAuthorization ```solidity function setMinimumAuthorization(struct EcdsaAuthorization.Data self, uint96 _minimumAuthorization) internal ``` Sets the minimum authorization for ECDSA application. Without at least the minimum authorization, staking provider is not eligible to join and operate in the network. ### setAuthorizationDecreaseDelay ```solidity function setAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseDelay) internal ``` Sets the authorization decrease delay. It is the time in seconds that needs to pass between the time authorization decrease is requested and the time the authorization decrease can be approved, no matter the authorization decrease amount. ### setAuthorizationDecreaseChangePeriod ```solidity function setAuthorizationDecreaseChangePeriod(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseChangePeriod) internal ``` Sets the authorization decrease change period. It is the time period before the authorization decrease delay end, during which the authorization decrease request can be overwritten. ### registerOperator ```solidity function registerOperator(struct EcdsaAuthorization.Data self, address operator) internal ``` Used by staking provider to set operator address that will operate ECDSA node. The given staking provider can set operator address only one time. The operator address can not be changed and must be unique. Reverts if the operator is already set for the staking provider or if the operator address is already in use. Reverts if there is a pending authorization decrease for the staking provider. ### authorizationIncreased ```solidity function authorizationIncreased(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal ``` Used by T staking contract to inform the application that the authorized stake amount for the given staking provider increased. Reverts if the authorization amount is below the minimum. The function is not updating the sortition pool. Sortition pool state needs to be updated by the operator with a call to `joinSortitionPool` or `updateOperatorStatus`. Should only be callable by T staking contract. ### authorizationDecreaseRequested ```solidity function authorizationDecreaseRequested(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal ``` Used by T staking contract to inform the application that the authorization decrease for the given staking provider has been requested. Reverts if the amount after deauthorization would be non-zero and lower than the minimum authorization. Reverts if another authorization decrease request is pending for the staking provider and not enough time passed since the original request (see `authorizationDecreaseChangePeriod`). If the operator is not known (`registerOperator` was not called) it lets to `approveAuthorizationDecrease` immediately. If the operator is known (`registerOperator` was called), the operator needs to update state of the sortition pool with a call to `joinSortitionPool` or `updateOperatorStatus`. After the sortition pool state is in sync, authorization decrease delay starts. After authorization decrease delay passes, authorization decrease request needs to be approved with a call to `approveAuthorizationDecrease` function. If there is a pending authorization decrease request, it is overwritten, but only if enough time passed since the original request. Otherwise, the function reverts. Should only be callable by T staking contract. ### approveAuthorizationDecrease ```solidity function approveAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal ``` Approves the previously registered authorization decrease request. Reverts if authorization decrease delay have not passed yet or if the authorization decrease was not requested for the given staking provider. ### involuntaryAuthorizationDecrease ```solidity function involuntaryAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal ``` Used by T staking contract to inform the application the authorization has been decreased for the given staking provider involuntarily, as a result of slashing. If the operator is not known (`registerOperator` was not called) the function does nothing. The operator was never in a sortition pool so there is nothing to update. If the operator is known, sortition pool is unlocked, and the operator is in the sortition pool, the sortition pool state is updated. If the sortition pool is locked, update needs to be postponed. Every other staker is incentivized to call `updateOperatorStatus` for the problematic operator to increase their own rewards in the pool. Should only be callable by T staking contract. ### joinSortitionPool ```solidity function joinSortitionPool(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool) internal ``` Lets the operator join the sortition pool. The operator address must be known - before calling this function, it has to be appointed by the staking provider by calling `registerOperator`. Also, the operator must have the minimum authorization required by ECDSA. Function reverts if there is no minimum stake authorized or if the operator is not known. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. ### updateOperatorStatus ```solidity function updateOperatorStatus(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal ``` Updates status of the operator in the sortition pool. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. Function reverts if the operator is not known. ### isOperatorUpToDate ```solidity function isOperatorUpToDate(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal view returns (bool) ``` Checks if the operator's authorized stake is in sync with operator's weight in the sortition pool. If the operator is not in the sortition pool and their authorized stake is non-zero, function returns false. ### eligibleStake ```solidity function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal view returns (uint96) ``` Returns the current value of the staking provider's eligible stake. Eligible stake is defined as the currently authorized stake minus the pending authorization decrease. Eligible stake is what is used for operator's weight in the pool. If the authorized stake minus the pending authorization decrease is below the minimum authorization, eligible stake is 0. This function can be exposed to the public in contrast to the second variant accepting `decreasingBy` as a parameter. ### eligibleStake ```solidity function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider, uint96 decreasingBy) internal view returns (uint96) ``` Returns the current value of the staking provider's eligible stake. Eligible stake is defined as the currently authorized stake minus the pending authorization decrease. Eligible stake is what is used for operator's weight in the pool. If the authorized stake minus the pending authorization decrease is below the minimum authorization, eligible stake is 0. This function is not intended to be exposes to the public. `decreasingBy` must be fetched from `pendingDecreases` mapping and it is passed as a parameter to optimize gas usage of functions that call `eligibleStake` and need to use `AuthorizationDecrease` fetched from `pendingDecreases` for some additional logic. ### pendingAuthorizationDecrease ```solidity function pendingAuthorizationDecrease(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint96) ``` Returns the amount of stake that is pending authorization decrease for the given staking provider. If no authorization decrease has been requested, returns zero. ### remainingAuthorizationDecreaseDelay ```solidity function remainingAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint64) ``` Returns the remaining time in seconds that needs to pass before the requested authorization decrease can be approved. If the sortition pool state was not updated yet by the operator after requesting the authorization decrease, returns `type(uint64).max`. # EcdsaDkg ## EcdsaDkg ### Parameters ```solidity struct Parameters { uint256 seedTimeout; uint256 resultChallengePeriodLength; uint256 resultChallengeExtraGas; uint256 resultSubmissionTimeout; uint256 submitterPrecedencePeriodLength; } ``` ### Data ```solidity struct Data { contract SortitionPool sortitionPool; contract EcdsaDkgValidator dkgValidator; struct EcdsaDkg.Parameters parameters; uint256 stateLockBlock; uint256 startBlock; uint256 seed; uint256 resultSubmissionStartBlockOffset; bytes32 submittedResultHash; uint256 submittedResultBlock; uint256[38] __gap; } ``` ### Result ```solidity struct Result { uint256 submitterMemberIndex; bytes groupPubKey; uint8[] misbehavedMembersIndices; bytes signatures; uint256[] signingMembersIndices; uint32[] members; bytes32 membersHash; } ``` ### State ```solidity enum State { IDLE, AWAITING_SEED, AWAITING_RESULT, CHALLENGE } ``` ### groupSize ```solidity uint256 groupSize ``` Size of a group in ECDSA wallet. ### DkgStarted ```solidity event DkgStarted(uint256 seed) ``` ### DkgResultSubmitted ```solidity event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct EcdsaDkg.Result result) ``` ### DkgTimedOut ```solidity event DkgTimedOut() ``` ### DkgResultApproved ```solidity event DkgResultApproved(bytes32 resultHash, address approver) ``` ### DkgResultChallenged ```solidity event DkgResultChallenged(bytes32 resultHash, address challenger, string reason) ``` ### DkgStateLocked ```solidity event DkgStateLocked() ``` ### DkgSeedTimedOut ```solidity event DkgSeedTimedOut() ``` ### init ```solidity function init(struct EcdsaDkg.Data self, contract SortitionPool _sortitionPool, contract EcdsaDkgValidator _dkgValidator) internal ``` Initializes SortitionPool and EcdsaDkgValidator addresses. Can be performed only once. #### Parameters | Name | Type | Description | | --------------- | -------------------------- | --------------------------- | | self | struct EcdsaDkg.Data | | | \_sortitionPool | contract SortitionPool | Sortition Pool reference | | \_dkgValidator | contract EcdsaDkgValidator | EcdsaDkgValidator reference | ### currentState ```solidity function currentState(struct EcdsaDkg.Data self) internal view returns (enum EcdsaDkg.State state) ``` Determines the current state of group creation. It doesn't take timeouts into consideration. The timeouts should be tracked and notified separately. ### lockState ```solidity function lockState(struct EcdsaDkg.Data self) internal ``` Locks the sortition pool and starts awaiting for the group creation seed. ### start ```solidity function start(struct EcdsaDkg.Data self, uint256 seed) internal ``` ### submitResult ```solidity function submitResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal ``` Allows to submit a DKG result. The submitted result does not go through a validation and before it gets accepted, it needs to wait through the challenge period during which everyone has a chance to challenge the result as invalid one. Submitter of the result needs to be in the sortition pool and if the result gets challenged, the submitter will get slashed. ### hasSeedTimedOut ```solidity function hasSeedTimedOut(struct EcdsaDkg.Data self) internal view returns (bool) ``` Checks if awaiting seed timed out. #### Return Values | Name | Type | Description | | ---- | ---- | ------------------------------------------------- | | \[0] | bool | True if awaiting seed timed out, false otherwise. | ### hasDkgTimedOut ```solidity function hasDkgTimedOut(struct EcdsaDkg.Data self) internal view returns (bool) ``` Checks if DKG timed out. The DKG timeout period includes time required for off-chain protocol execution and time for the result publication. After this time a result cannot be submitted and DKG can be notified about the timeout. DKG period is adjusted by result submission offset that include blocks that were mined while invalid result has been registered until it got challenged. #### Return Values | Name | Type | Description | | ---- | ---- | --------------------------------------- | | \[0] | bool | True if DKG timed out, false otherwise. | ### notifySeedTimeout ```solidity function notifySeedTimeout(struct EcdsaDkg.Data self) internal ``` Notifies about the seed was not delivered and restores the initial DKG state (IDLE). ### notifyDkgTimeout ```solidity function notifyDkgTimeout(struct EcdsaDkg.Data self) internal ``` Notifies about DKG timeout. ### approveResult ```solidity function approveResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (uint32[] misbehavedMembers) ``` Approves DKG result. Can be called when the challenge period for the submitted result is finished. Considers the submitted result as valid. For the first `submitterPrecedencePeriodLength` blocks after the end of the challenge period can be called only by the DKG result submitter. After that time, can be called by anyone. Can be called after a challenge period for the submitted result. #### Parameters | Name | Type | Description | | ------ | ---------------------- | -------------------------------------------------------------------------------- | | self | struct EcdsaDkg.Data | | | result | struct EcdsaDkg.Result | Result to approve. Must match the submitted result stored during `submitResult`. | #### Return Values | Name | Type | Description | | ----------------- | --------- | ------------------------------------------------- | | misbehavedMembers | uint32\[] | Identifiers of members who misbehaved during DKG. | ### challengeResult ```solidity function challengeResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter) ``` Challenges DKG result. If the submitted result is proved to be invalid it reverts the DKG back to the result submission phase. Can be called during a challenge period for the submitted result. #### Parameters | Name | Type | Description | | ------ | ---------------------- | ---------------------------------------------------------------------------------- | | self | struct EcdsaDkg.Data | | | result | struct EcdsaDkg.Result | Result to challenge. Must match the submitted result stored during `submitResult`. | #### Return Values | Name | Type | Description | | ------------------- | ------- | -------------------------------------- | | maliciousResultHash | bytes32 | Hash of the malicious result. | | maliciousSubmitter | uint32 | Identifier of the malicious submitter. | ### requireChallengeExtraGas ```solidity function requireChallengeExtraGas(struct EcdsaDkg.Data self) internal view ``` Due to EIP150, 1/64 of the gas is not forwarded to the call, and will be kept to execute the remaining operations in the function after the call inside the try-catch. To ensure there is no way for the caller to manipulate gas limit in such a way that the call inside try-catch fails with out-of-gas and the rest of the function is executed with the remaining 1/64 of gas, we require an extra gas amount to be left at the end of the call to the function challenging DKG result and wrapping the call to EcdsaDkgValidator and TokenStaking contracts inside a try-catch. ### isResultValid ```solidity function isResultValid(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal view returns (bool, string) ``` Checks if DKG result is valid for the current DKG. #### Parameters | Name | Type | Description | | ------ | ---------------------- | ----------- | | self | struct EcdsaDkg.Data | | | result | struct EcdsaDkg.Result | DKG result. | #### Return Values | Name | Type | Description | | ---- | ------ | -------------------------------------------------------------------------------------------- | | \[0] | bool | True if the result is valid. If the result is invalid it returns false and an error message. | | \[1] | string | | ### setSeedTimeout ```solidity function setSeedTimeout(struct EcdsaDkg.Data self, uint256 newSeedTimeout) internal ``` Set setSeedTimeout parameter. ### setResultChallengePeriodLength ```solidity function setResultChallengePeriodLength(struct EcdsaDkg.Data self, uint256 newResultChallengePeriodLength) internal ``` Set resultChallengePeriodLength parameter. ### setResultChallengeExtraGas ```solidity function setResultChallengeExtraGas(struct EcdsaDkg.Data self, uint256 newResultChallengeExtraGas) internal ``` Set resultChallengeExtraGas parameter. ### setResultSubmissionTimeout ```solidity function setResultSubmissionTimeout(struct EcdsaDkg.Data self, uint256 newResultSubmissionTimeout) internal ``` Set resultSubmissionTimeout parameter. ### setSubmitterPrecedencePeriodLength ```solidity function setSubmitterPrecedencePeriodLength(struct EcdsaDkg.Data self, uint256 newSubmitterPrecedencePeriodLength) internal ``` Set submitterPrecedencePeriodLength parameter. ### complete ```solidity function complete(struct EcdsaDkg.Data self) internal ``` Completes DKG by cleaning up state. Should be called after DKG times out or a result is approved. # EcdsaDkgValidator ## EcdsaDkgValidator EcdsaDkgValidator allows performing a full validation of DKG result, including checking the format of fields in the result, declared selected group members, and signatures of operators supporting the result. The operator submitting the result should perform the validation using a free contract call before submitting the result to ensure their result is valid and can not be challenged. All other network operators should perform validation of the submitted result using a free contract call and challenge the result if the validation fails. ### groupSize ```solidity uint256 groupSize ``` Size of a group in DKG. ### groupThreshold ```solidity uint256 groupThreshold ``` The minimum number of group members needed to interact according to the protocol to produce a signature. The adversary can not learn anything about the key as long as it does not break into groupThreshold+1 of members. ### activeThreshold ```solidity uint256 activeThreshold ``` The minimum number of active and properly behaving group members during the DKG needed to accept the result. This number is higher than `groupThreshold` to keep a safety margin for members becoming inactive after DKG so that the group can still produce signature. ### publicKeyByteSize ```solidity uint256 publicKeyByteSize ``` Size in bytes of a public key produced by group members during the the DKG. The length assumes uncompressed ECDSA public key. ### signatureByteSize ```solidity uint256 signatureByteSize ``` Size in bytes of a single signature produced by operator supporting DKG result. ### sortitionPool ```solidity contract SortitionPool sortitionPool ``` ### constructor ```solidity constructor(contract SortitionPool _sortitionPool) public ``` ### validate ```solidity function validate(struct EcdsaDkg.Result result, uint256 seed, uint256 startBlock) external view returns (bool isValid, string errorMsg) ``` Performs a full validation of DKG result, including checking the format of fields in the result, declared selected group members, and signatures of operators supporting the result. #### Parameters | Name | Type | Description | | ---------- | ---------------------- | --------------------------------------------------- | | result | struct EcdsaDkg.Result | | | seed | uint256 | seed used to start the DKG and select group members | | startBlock | uint256 | DKG start block | #### Return Values | Name | Type | Description | | -------- | ------ | -------------------------------------------------- | | isValid | bool | true if the result is valid, false otherwise | | errorMsg | string | validation error message; empty for a valid result | ### validateFields ```solidity function validateFields(struct EcdsaDkg.Result result) public pure returns (bool isValid, string errorMsg) ``` Performs a static validation of DKG result fields: lengths, ranges, and order of arrays. #### Return Values | Name | Type | Description | | -------- | ------ | -------------------------------------------------- | | isValid | bool | true if the result is valid, false otherwise | | errorMsg | string | validation error message; empty for a valid result | ### validateGroupMembers ```solidity function validateGroupMembers(struct EcdsaDkg.Result result, uint256 seed) public view returns (bool) ``` Performs validation of group members as declared in DKG result against group members selected by the sortition pool. #### Parameters | Name | Type | Description | | ------ | ---------------------- | --------------------------------------------------- | | result | struct EcdsaDkg.Result | | | seed | uint256 | seed used to start the DKG and select group members | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------- | | \[0] | bool | true if group members matches; false otherwise | ### validateSignatures ```solidity function validateSignatures(struct EcdsaDkg.Result result, uint256 startBlock) public view returns (bool) ``` Performs validation of signatures supplied in DKG result. Note that this function does not check if addresses which supplied signatures supporting the result are the ones selected to the group by sortition pool. This function should be used together with `validateGroupMembers`. #### Parameters | Name | Type | Description | | ---------- | ---------------------- | --------------- | | result | struct EcdsaDkg.Result | | | startBlock | uint256 | DKG start block | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------- | | \[0] | bool | true if group members matches; false otherwise | ### validateMembersHash ```solidity function validateMembersHash(struct EcdsaDkg.Result result) public pure returns (bool) ``` Performs validation of hashed group members that actively took part in DKG. #### Parameters | Name | Type | Description | | ------ | ---------------------- | ----------- | | result | struct EcdsaDkg.Result | DKG result | #### Return Values | Name | Type | Description | | ---- | ---- | --------------------------------------------------------------------------------------- | | \[0] | bool | true if calculated result's group members hash matches with the one that is challenged. | # EcdsaInactivity ## EcdsaInactivity ### Claim ```solidity struct Claim { bytes32 walletID; uint256[] inactiveMembersIndices; bool heartbeatFailed; bytes signatures; uint256[] signingMembersIndices; } ``` ### groupThreshold ```solidity uint256 groupThreshold ``` The minimum number of wallet signing group members needed to interact according to the protocol to produce a valid inactivity claim. ### signatureByteSize ```solidity uint256 signatureByteSize ``` Size in bytes of a single signature produced by member supporting the inactivity claim. ### verifyClaim ```solidity function verifyClaim(contract SortitionPool sortitionPool, struct EcdsaInactivity.Claim claim, bytes walletPubKey, uint256 nonce, uint32[] groupMembers) external view returns (uint32[] inactiveMembers) ``` Verifies the inactivity claim according to the rules defined in `Claim` struct documentation. Reverts if verification fails. Wallet signing group members hash is validated upstream in `WalletRegistry.notifyOperatorInactivity()` #### Parameters | Name | Type | Description | | ------------- | ---------------------------- | ----------------------------------------------------- | | sortitionPool | contract SortitionPool | Sortition pool reference | | claim | struct EcdsaInactivity.Claim | Inactivity claim | | walletPubKey | bytes | Public key of the wallet | | nonce | uint256 | Current inactivity nonce for wallet used in the claim | | groupMembers | uint32\[] | Identifiers of group members | #### Return Values | Name | Type | Description | | --------------- | --------- | --------------------------------------- | | inactiveMembers | uint32\[] | Identifiers of members who are inactive | ### validateMembersIndices ```solidity function validateMembersIndices(uint256[] indices, uint256 groupSize) internal pure ``` Validates members indices array. Array is considered valid if its size and each single index are in \[1, groupSize] range, indexes are unique, and sorted in an ascending order. Reverts if validation fails. #### Parameters | Name | Type | Description | | --------- | ---------- | ----------------------------- | | indices | uint256\[] | Array to validate. | | groupSize | uint256 | Group size used as reference. | # IWalletOwner ## IWalletOwner ### \_\_ecdsaWalletCreatedCallback ```solidity function __ecdsaWalletCreatedCallback(bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) external ``` Callback function executed once a new wallet is created. Should be callable only by the Wallet Registry. #### Parameters | Name | Type | Description | | ---------- | ------- | ----------------------------------- | | walletID | bytes32 | Wallet's unique identifier. | | publicKeyX | bytes32 | | | publicKeyY | bytes32 | Wallet's public key's X coordinate. | ### \_\_ecdsaWalletHeartbeatFailedCallback ```solidity function __ecdsaWalletHeartbeatFailedCallback(bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) external ``` Callback function executed once a wallet heartbeat failure is detected. Should be callable only by the Wallet Registry. #### Parameters | Name | Type | Description | | ---------- | ------- | ----------------------------------- | | walletID | bytes32 | Wallet's unique identifier. | | publicKeyX | bytes32 | | | publicKeyY | bytes32 | Wallet's public key's X coordinate. | # IWalletRegistry ## IWalletRegistry ### requestNewWallet ```solidity function requestNewWallet() external ``` Requests a new wallet creation. Only the Wallet Owner can call this function. ### closeWallet ```solidity function closeWallet(bytes32 walletID) external ``` Closes an existing wallet. Only the Wallet Owner can call this function. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | ### seize ```solidity function seize(uint96 amount, uint256 rewardMultiplier, address notifier, bytes32 walletID, uint32[] walletMembersIDs) external ``` Adds all signing group members of the wallet with the given ID to the slashing queue of the staking contract. The notifier will receive reward per each group member from the staking contract notifiers treasury. The reward is scaled by the `rewardMultiplier` provided as a parameter. Only the Wallet Owner can call this function. Requirements: * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events. * `rewardMultiplier` must be between \[0, 100]. * This function does revert if staking contract call reverts. The calling code needs to handle the potential revert. #### Parameters | Name | Type | Description | | ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- | | amount | uint96 | Amount of tokens to seize from each signing group member | | rewardMultiplier | uint256 | Fraction of the staking contract notifiers reward the notifier should receive; should be between \[0, 100] | | notifier | address | Address of the misbehavior notifier | | walletID | bytes32 | ID of the wallet | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members | ### getWalletPublicKey ```solidity function getWalletPublicKey(bytes32 walletID) external view returns (bytes) ``` Gets public key of a wallet with a given wallet ID. The public key is returned in an uncompressed format as a 64-byte concatenation of X and Y coordinates. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | #### Return Values | Name | Type | Description | | ---- | ----- | -------------------------------------- | | \[0] | bytes | Uncompressed public key of the wallet. | ### getWalletCreationState ```solidity function getWalletCreationState() external view returns (enum EcdsaDkg.State) ``` Check current wallet creation state. ### isWalletMember ```solidity function isWalletMember(bytes32 walletID, uint32[] walletMembersIDs, address operator, uint256 walletMemberIndex) external view returns (bool) ``` Checks whether the given operator is a member of the given wallet signing group. Requirements: * The `operator` parameter must be an actual sortition pool operator. * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events. * The `walletMemberIndex` must be in range \[1, walletMembersIDs.length] #### Parameters | Name | Type | Description | | ----------------- | --------- | ----------------------------------------------------------------- | | walletID | bytes32 | ID of the wallet | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members | | operator | address | Address of the checked operator | | walletMemberIndex | uint256 | Position of the operator in the wallet signing group members list | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------------------------------------------------- | | \[0] | bool | True - if the operator is a member of the given wallet signing group. False - otherwise. | # WalletRegistry ## WalletRegistry ### authorization ```solidity struct EcdsaAuthorization.Data authorization ``` ### dkg ```solidity struct EcdsaDkg.Data dkg ``` ### wallets ```solidity struct Wallets.Data wallets ``` ### \_maliciousDkgResultSlashingAmount ```solidity uint96 _maliciousDkgResultSlashingAmount ``` Slashing amount for submitting a malicious DKG result. Every DKG result submitted can be challenged for the time of `dkg.resultChallengePeriodLength`. If the DKG result submitted is challenged and proven to be malicious, the operator who submitted the malicious result is slashed for `_maliciousDkgResultSlashingAmount`. ### \_maliciousDkgResultNotificationRewardMultiplier ```solidity uint256 _maliciousDkgResultNotificationRewardMultiplier ``` Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about a malicious DKG result. Notifiers are rewarded from a notifiers treasury pool. For example, if notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected. ### \_sortitionPoolRewardsBanDuration ```solidity uint256 _sortitionPoolRewardsBanDuration ``` Duration of the sortition pool rewards ban imposed on operators who missed their turn for DKG result submission or who failed a heartbeat. ### \_dkgResultSubmissionGas ```solidity uint256 _dkgResultSubmissionGas ``` Calculated max gas cost for submitting a DKG result. This will be refunded as part of the DKG approval process. It is in the submitter's interest to not skip his priority turn on the approval, otherwise the refund of the DKG submission will be refunded to another group member that will call the DKG approve function. ### \_dkgResultApprovalGasOffset ```solidity uint256 _dkgResultApprovalGasOffset ``` Gas that is meant to balance the DKG result approval's overall cost. It can be updated by the governance based on the current market conditions. ### \_notifyOperatorInactivityGasOffset ```solidity uint256 _notifyOperatorInactivityGasOffset ``` Gas that is meant to balance the notification of an operator inactivity. It can be updated by the governance based on the current market conditions. ### \_notifySeedTimeoutGasOffset ```solidity uint256 _notifySeedTimeoutGasOffset ``` Gas that is meant to balance the notification of a seed for DKG delivery timeout. It can be updated by the governance based on the current market conditions. ### \_notifyDkgTimeoutNegativeGasOffset ```solidity uint256 _notifyDkgTimeoutNegativeGasOffset ``` Gas that is meant to balance the notification of a DKG protocol execution timeout. It can be updated by the governance based on the current market conditions. The value is subtracted for the refundable gas calculation, as the DKG timeout notification transaction recovers some gas when cleaning up the storage. ### inactivityClaimNonce ```solidity mapping(bytes32 => uint256) inactivityClaimNonce ``` Stores current operator inactivity claim nonce for the given wallet signing group. Each claim is made with a unique nonce which protects against claim replay. ### walletOwner ```solidity contract IWalletOwner walletOwner ``` ### sortitionPool ```solidity contract SortitionPool sortitionPool ``` ### staking ```solidity contract IStaking staking ``` ### randomBeacon ```solidity contract IRandomBeacon randomBeacon ``` ### DkgStarted ```solidity event DkgStarted(uint256 seed) ``` ### DkgResultSubmitted ```solidity event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct EcdsaDkg.Result result) ``` ### DkgTimedOut ```solidity event DkgTimedOut() ``` ### DkgResultApproved ```solidity event DkgResultApproved(bytes32 resultHash, address approver) ``` ### DkgResultChallenged ```solidity event DkgResultChallenged(bytes32 resultHash, address challenger, string reason) ``` ### DkgStateLocked ```solidity event DkgStateLocked() ``` ### DkgSeedTimedOut ```solidity event DkgSeedTimedOut() ``` ### WalletCreated ```solidity event WalletCreated(bytes32 walletID, bytes32 dkgResultHash) ``` ### WalletClosed ```solidity event WalletClosed(bytes32 walletID) ``` ### DkgMaliciousResultSlashed ```solidity event DkgMaliciousResultSlashed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) ``` ### DkgMaliciousResultSlashingFailed ```solidity event DkgMaliciousResultSlashingFailed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) ``` ### AuthorizationParametersUpdated ```solidity event AuthorizationParametersUpdated(uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) ``` ### RewardParametersUpdated ```solidity event RewardParametersUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) ``` ### SlashingParametersUpdated ```solidity event SlashingParametersUpdated(uint256 maliciousDkgResultSlashingAmount) ``` ### DkgParametersUpdated ```solidity event DkgParametersUpdated(uint256 seedTimeout, uint256 resultChallengePeriodLength, uint256 resultChallengeExtraGas, uint256 resultSubmissionTimeout, uint256 resultSubmitterPrecedencePeriodLength) ``` ### GasParametersUpdated ```solidity event GasParametersUpdated(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) ``` ### RandomBeaconUpgraded ```solidity event RandomBeaconUpgraded(address randomBeacon) ``` ### WalletOwnerUpdated ```solidity event WalletOwnerUpdated(address walletOwner) ``` ### OperatorRegistered ```solidity event OperatorRegistered(address stakingProvider, address operator) ``` ### AuthorizationIncreased ```solidity event AuthorizationIncreased(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount) ``` ### AuthorizationDecreaseRequested ```solidity event AuthorizationDecreaseRequested(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount, uint64 decreasingAt) ``` ### AuthorizationDecreaseApproved ```solidity event AuthorizationDecreaseApproved(address stakingProvider) ``` ### InvoluntaryAuthorizationDecreaseFailed ```solidity event InvoluntaryAuthorizationDecreaseFailed(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount) ``` ### OperatorJoinedSortitionPool ```solidity event OperatorJoinedSortitionPool(address stakingProvider, address operator) ``` ### OperatorStatusUpdated ```solidity event OperatorStatusUpdated(address stakingProvider, address operator) ``` ### InactivityClaimed ```solidity event InactivityClaimed(bytes32 walletID, uint256 nonce, address notifier) ``` ### onlyStakingContract ```solidity modifier onlyStakingContract() ``` ### onlyWalletOwner ```solidity modifier onlyWalletOwner() ``` Reverts if called not by the Wallet Owner. ### onlyReimbursableAdmin ```solidity modifier onlyReimbursableAdmin() ``` ### constructor ```solidity constructor(contract SortitionPool _sortitionPool, contract IStaking _staking) public ``` Used to initialize immutable variables only, use `initialize` function for upgradable contract initialization on deployment. ### initialize ```solidity function initialize(contract EcdsaDkgValidator _ecdsaDkgValidator, contract IRandomBeacon _randomBeacon, contract ReimbursementPool _reimbursementPool) external ``` Initializes upgradable contract on deployment. ### withdrawRewards ```solidity function withdrawRewards(address stakingProvider) external ``` Withdraws application rewards for the given staking provider. Rewards are withdrawn to the staking provider's beneficiary address set in the staking contract. Reverts if staking provider has not registered the operator address. Emits `RewardsWithdrawn` event. ### withdrawIneligibleRewards ```solidity function withdrawIneligibleRewards(address recipient) external ``` Withdraws rewards belonging to operators marked as ineligible for sortition pool rewards. Can be called only by the contract guvnor, which should be the wallet registry governance contract. #### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------- | | recipient | address | Recipient of withdrawn rewards. | ### registerOperator ```solidity function registerOperator(address operator) external ``` Used by staking provider to set operator address that will operate ECDSA node. The given staking provider can set operator address only one time. The operator address can not be changed and must be unique. Reverts if the operator is already set for the staking provider or if the operator address is already in use. Reverts if there is a pending authorization decrease for the staking provider. ### joinSortitionPool ```solidity function joinSortitionPool() external ``` Lets the operator join the sortition pool. The operator address must be known - before calling this function, it has to be appointed by the staking provider by calling `registerOperator`. Also, the operator must have the minimum authorization required by ECDSA. Function reverts if there is no minimum stake authorized or if the operator is not known. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. ### updateOperatorStatus ```solidity function updateOperatorStatus(address operator) external ``` Updates status of the operator in the sortition pool. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. Function reverts if the operator is not known. ### authorizationIncreased ```solidity function authorizationIncreased(address stakingProvider, uint96 fromAmount, uint96 toAmount) external ``` Used by T staking contract to inform the application that the authorized stake amount for the given staking provider increased. Reverts if the authorization amount is below the minimum. The function is not updating the sortition pool. Sortition pool state needs to be updated by the operator with a call to `joinSortitionPool` or `updateOperatorStatus`. Can only be called by T staking contract. ### authorizationDecreaseRequested ```solidity function authorizationDecreaseRequested(address stakingProvider, uint96 fromAmount, uint96 toAmount) external ``` Used by T staking contract to inform the application that the authorization decrease for the given staking provider has been requested. Reverts if the amount after deauthorization would be non-zero and lower than the minimum authorization. If the operator is not known (`registerOperator` was not called) it lets to `approveAuthorizationDecrease` immediatelly. If the operator is known (`registerOperator` was called), the operator needs to update state of the sortition pool with a call to `joinSortitionPool` or `updateOperatorStatus`. After the sortition pool state is in sync, authorization decrease delay starts. After authorization decrease delay passes, authorization decrease request needs to be approved with a call to `approveAuthorizationDecrease` function. If there is a pending authorization decrease request, it is overwritten. Can only be called by T staking contract. ### approveAuthorizationDecrease ```solidity function approveAuthorizationDecrease(address stakingProvider) external ``` Approves the previously registered authorization decrease request. Reverts if authorization decrease delay has not passed yet or if the authorization decrease was not requested for the given staking provider. ### involuntaryAuthorizationDecrease ```solidity function involuntaryAuthorizationDecrease(address stakingProvider, uint96 fromAmount, uint96 toAmount) external ``` Used by T staking contract to inform the application the authorization has been decreased for the given staking provider involuntarily, as a result of slashing. If the operator is not known (`registerOperator` was not called) the function does nothing. The operator was never in a sortition pool so there is nothing to update. If the operator is known, sortition pool is unlocked, and the operator is in the sortition pool, the sortition pool state is updated. If the sortition pool is locked, update needs to be postponed. Every other staker is incentivized to call `updateOperatorStatus` for the problematic operator to increase their own rewards in the pool. ### upgradeRandomBeacon ```solidity function upgradeRandomBeacon(contract IRandomBeacon _randomBeacon) external ``` Updates address of the Random Beacon. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | -------------- | ---------------------- | ---------------------- | | \_randomBeacon | contract IRandomBeacon | Random Beacon address. | ### updateWalletOwner ```solidity function updateWalletOwner(contract IWalletOwner _walletOwner) external ``` Updates the wallet owner. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. The wallet owner has to implement `IWalletOwner` interface. #### Parameters | Name | Type | Description | | ------------- | --------------------- | ------------------------- | | \_walletOwner | contract IWalletOwner | New wallet owner address. | ### updateAuthorizationParameters ```solidity function updateAuthorizationParameters(uint96 _minimumAuthorization, uint64 _authorizationDecreaseDelay, uint64 _authorizationDecreaseChangePeriod) external ``` Updates the values of authorization parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | ----------------------------------- | ------ | ---------------------------------------------------- | | \_minimumAuthorization | uint96 | New minimum authorization amount. | | \_authorizationDecreaseDelay | uint64 | New authorization decrease delay in seconds. | | \_authorizationDecreaseChangePeriod | uint64 | New authorization decrease change period in seconds. | ### updateDkgParameters ```solidity function updateDkgParameters(uint256 _seedTimeout, uint256 _resultChallengePeriodLength, uint256 _resultChallengeExtraGas, uint256 _resultSubmissionTimeout, uint256 _submitterPrecedencePeriodLength) external ``` Updates the values of DKG parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | --------------------------------- | ------- | ------------------------------------------------------------------------------------------- | | \_seedTimeout | uint256 | New seed timeout. | | \_resultChallengePeriodLength | uint256 | New DKG result challenge period length. | | \_resultChallengeExtraGas | uint256 | New extra gas value required to be left at the end of the DKG result challenge transaction. | | \_resultSubmissionTimeout | uint256 | New DKG result submission timeout. | | \_submitterPrecedencePeriodLength | uint256 | New submitter precedence period length. | ### updateRewardParameters ```solidity function updateRewardParameters(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) external ``` Updates the values of reward parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | ---------------------------------------------- | ------- | --------------------------------------------------------------------- | | maliciousDkgResultNotificationRewardMultiplier | uint256 | New value of the DKG malicious result notification reward multiplier. | | sortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration in seconds. | ### updateSlashingParameters ```solidity function updateSlashingParameters(uint96 maliciousDkgResultSlashingAmount) external ``` Updates the values of slashing parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | -------------------------------- | ------ | ----------------------------------------- | | maliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount. | ### updateGasParameters ```solidity function updateGasParameters(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) external ``` Updates the values of gas-related parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | --------------------------------- | ------- | ---------------------------------------------------------- | | dkgResultSubmissionGas | uint256 | New DKG result submission gas. | | dkgResultApprovalGasOffset | uint256 | New DKG result approval gas offset. | | notifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset. | | notifySeedTimeoutGasOffset | uint256 | New seed for DKG delivery timeout notification gas offset. | | notifyDkgTimeoutNegativeGasOffset | uint256 | New DKG timeout notification gas offset. | ### requestNewWallet ```solidity function requestNewWallet() external ``` Requests a new wallet creation. Can be called only by the owner of wallets. It locks the DKG and request a new relay entry. It expects that the DKG process will be started once a new relay entry gets generated. ### closeWallet ```solidity function closeWallet(bytes32 walletID) external ``` Closes an existing wallet. Reverts if wallet with the given ID does not exist or if it has already been closed. Only a Wallet Owner can call this function. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | ### \_\_beaconCallback ```solidity function __beaconCallback(uint256 relayEntry, uint256) external ``` A callback that is executed once a new relay entry gets generated. It starts the DKG process. Can be called only by the random beacon contract. #### Parameters | Name | Type | Description | | ---------- | ------- | ------------ | | relayEntry | uint256 | Relay entry. | | | uint256 | | ### submitDkgResult ```solidity function submitDkgResult(struct EcdsaDkg.Result dkgResult) external ``` Submits result of DKG protocol. The DKG result consists of result submitting member index, calculated group public key, bytes array of misbehaved members, concatenation of signatures from group members, indices of members corresponding to each signature and the list of group members. The result is registered optimistically and waits for an approval. The result can be challenged when it is believed to be incorrect. The challenge verifies the registered result i.a. it checks if members list corresponds to the expected set of members determined by the sortition pool. The message to be signed by each member is keccak256 hash of the chain ID, calculated group public key, misbehaved members indices and DKG start block. The calculated hash should be prefixed with `\x19Ethereum signed message:` before signing, so the message to sign is: `\x19Ethereum signed message:\n${keccak256(chainID,groupPubKey,misbehavedIndices,startBlock)}` #### Parameters | Name | Type | Description | | --------- | ---------------------- | ----------- | | dkgResult | struct EcdsaDkg.Result | DKG result. | ### approveDkgResult ```solidity function approveDkgResult(struct EcdsaDkg.Result dkgResult) external ``` Approves DKG result. Can be called when the challenge period for the submitted result is finished. Considers the submitted result as valid, bans misbehaved group members from the sortition pool rewards, and completes the group creation by activating the candidate group. For the first `resultSubmissionTimeout` blocks after the end of the challenge period can be called only by the DKG result submitter. After that time, can be called by anyone. A new wallet based on the DKG result details. #### Parameters | Name | Type | Description | | --------- | ---------------------- | ----------------------------------------------------------------------------------- | | dkgResult | struct EcdsaDkg.Result | Result to approve. Must match the submitted result stored during `submitDkgResult`. | ### notifySeedTimeout ```solidity function notifySeedTimeout() external ``` Notifies about seed for DKG delivery timeout. It is expected that a seed is delivered by the Random Beacon as a relay entry in a callback function. ### notifyDkgTimeout ```solidity function notifyDkgTimeout() external ``` Notifies about DKG timeout. ### challengeDkgResult ```solidity function challengeDkgResult(struct EcdsaDkg.Result dkgResult) external ``` Challenges DKG result. If the submitted result is proved to be invalid it reverts the DKG back to the result submission phase. Due to EIP-150 1/64 of the gas is not forwarded to the call, and will be kept to execute the remaining operations in the function after the call inside the try-catch. To eliminate a class of attacks related to the gas limit manipulation, this function requires an extra amount of gas to be left at the end of the execution. #### Parameters | Name | Type | Description | | --------- | ---------------------- | ------------------------------------------------------------------------------------- | | dkgResult | struct EcdsaDkg.Result | Result to challenge. Must match the submitted result stored during `submitDkgResult`. | ### notifyOperatorInactivity ```solidity function notifyOperatorInactivity(struct EcdsaInactivity.Claim claim, uint256 nonce, uint32[] groupMembers) external ``` Notifies about operators who are inactive. Using this function, a majority of the wallet signing group can decide about punishing specific group members who constantly fail doing their job. If the provided claim is proved to be valid and signed by sufficient number of group members, operators of members deemed as inactive are banned from sortition pool rewards for the duration specified by `sortitionPoolRewardsBanDuration` parameter. The function allows to signal about single operators being inactive as well as to signal wallet-wide heartbeat failures that are propagated to the wallet owner who should begin the procedure of moving responsibilities to another wallet given that the wallet who failed the heartbeat may soon be not able to function and provide new signatures. The sender of the claim must be one of the claim signers. This function can be called only for registered wallets #### Parameters | Name | Type | Description | | ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | claim | struct EcdsaInactivity.Claim | Operator inactivity claim. | | nonce | uint256 | Current inactivity claim nonce for the given wallet signing group. Must be the same as the stored one. | | groupMembers | uint32\[] | Identifiers of the wallet signing group members. | ### seize ```solidity function seize(uint96 amount, uint256 rewardMultiplier, address notifier, bytes32 walletID, uint32[] walletMembersIDs) external ``` Allows the wallet owner to add all signing group members of the wallet with the given ID to the slashing queue of the staking . contract. The notifier will receive reward per each group member from the staking contract notifiers treasury. The reward is scaled by the `rewardMultiplier` provided as a parameter. Requirements: * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events. * `rewardMultiplier` must be between \[0, 100]. * This function does revert if staking contract call reverts. The calling code needs to handle the potential revert. #### Parameters | Name | Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------- | | amount | uint96 | Amount of tokens to seize from each signing group member. | | rewardMultiplier | uint256 | Fraction of the staking contract notifiers reward the notifier should receive; should be between \[0, 100]. | | notifier | address | Address of the misbehavior notifier. | | walletID | bytes32 | ID of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | ### isDkgResultValid ```solidity function isDkgResultValid(struct EcdsaDkg.Result result) external view returns (bool, string) ``` Checks if DKG result is valid for the current DKG. #### Parameters | Name | Type | Description | | ------ | ---------------------- | ----------- | | result | struct EcdsaDkg.Result | DKG result. | #### Return Values | Name | Type | Description | | ---- | ------ | -------------------------------------------------------------------------------------------- | | \[0] | bool | True if the result is valid. If the result is invalid it returns false and an error message. | | \[1] | string | | ### getWalletCreationState ```solidity function getWalletCreationState() external view returns (enum EcdsaDkg.State) ``` Check current wallet creation state. ### isWalletMember ```solidity function isWalletMember(bytes32 walletID, uint32[] walletMembersIDs, address operator, uint256 walletMemberIndex) external view returns (bool) ``` Checks whether the given operator is a member of the given wallet signing group. Requirements: * The `operator` parameter must be an actual sortition pool operator. * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events. * The `walletMemberIndex` must be in range \[1, walletMembersIDs.length] #### Parameters | Name | Type | Description | | ----------------- | --------- | ------------------------------------------------------------------ | | walletID | bytes32 | ID of the wallet. | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members. | | operator | address | Address of the checked operator. | | walletMemberIndex | uint256 | Position of the operator in the wallet signing group members list. | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------------------------------------------------- | | \[0] | bool | True - if the operator is a member of the given wallet signing group. False - otherwise. | ### hasSeedTimedOut ```solidity function hasSeedTimedOut() external view returns (bool) ``` Checks if awaiting seed timed out. #### Return Values | Name | Type | Description | | ---- | ---- | ------------------------------------------------- | | \[0] | bool | True if awaiting seed timed out, false otherwise. | ### hasDkgTimedOut ```solidity function hasDkgTimedOut() external view returns (bool) ``` Checks if DKG timed out. The DKG timeout period includes time required for off-chain protocol execution and time for the result publication for all group members. After this time result cannot be submitted and DKG can be notified about the timeout. #### Return Values | Name | Type | Description | | ---- | ---- | --------------------------------------- | | \[0] | bool | True if DKG timed out, false otherwise. | ### getWallet ```solidity function getWallet(bytes32 walletID) external view returns (struct Wallets.Wallet) ``` ### getWalletPublicKey ```solidity function getWalletPublicKey(bytes32 walletID) external view returns (bytes) ``` Gets public key of a wallet with a given wallet ID. The public key is returned in an uncompressed format as a 64-byte concatenation of X and Y coordinates. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | #### Return Values | Name | Type | Description | | ---- | ----- | -------------------------------------- | | \[0] | bytes | Uncompressed public key of the wallet. | ### isWalletRegistered ```solidity function isWalletRegistered(bytes32 walletID) external view returns (bool) ``` Checks if a wallet with the given ID is registered. #### Parameters | Name | Type | Description | | -------- | ------- | ------------ | | walletID | bytes32 | Wallet's ID. | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------- | | \[0] | bool | True if wallet is registered, false otherwise. | ### minimumAuthorization ```solidity function minimumAuthorization() external view returns (uint96) ``` The minimum authorization amount required so that operator can participate in ECDSA Wallet operations. ### eligibleStake ```solidity function eligibleStake(address stakingProvider) external view returns (uint96) ``` Returns the current value of the staking provider's eligible stake. Eligible stake is defined as the currently authorized stake minus the pending authorization decrease. Eligible stake is what is used for operator's weight in the sortition pool. If the authorized stake minus the pending authorization decrease is below the minimum authorization, eligible stake is 0. ### availableRewards ```solidity function availableRewards(address stakingProvider) external view returns (uint96) ``` Returns the amount of rewards available for withdrawal for the given staking provider. Reverts if staking provider has not registered the operator address. ### pendingAuthorizationDecrease ```solidity function pendingAuthorizationDecrease(address stakingProvider) external view returns (uint96) ``` Returns the amount of stake that is pending authorization decrease for the given staking provider. If no authorization decrease has been requested, returns zero. ### remainingAuthorizationDecreaseDelay ```solidity function remainingAuthorizationDecreaseDelay(address stakingProvider) external view returns (uint64) ``` Returns the remaining time in seconds that needs to pass before the requested authorization decrease can be approved. If the sortition pool state was not updated yet by the operator after requesting the authorization decrease, returns `type(uint64).max`. ### stakingProviderToOperator ```solidity function stakingProviderToOperator(address stakingProvider) public view returns (address) ``` Returns operator registered for the given staking provider. ### operatorToStakingProvider ```solidity function operatorToStakingProvider(address operator) public view returns (address) ``` Returns staking provider of the given operator. ### isOperatorUpToDate ```solidity function isOperatorUpToDate(address operator) external view returns (bool) ``` Checks if the operator's authorized stake is in sync with operator's weight in the sortition pool. If the operator is not in the sortition pool and their authorized stake is non-zero, function returns false. ### isOperatorInPool ```solidity function isOperatorInPool(address operator) external view returns (bool) ``` Returns true if the given operator is in the sortition pool. Otherwise, returns false. ### selectGroup ```solidity function selectGroup() external view returns (uint32[]) ``` Selects a new group of operators. Can only be called when DKG is in progress and the pool is locked. At least one operator has to be registered in the pool, otherwise the function fails reverting the transaction. #### Return Values | Name | Type | Description | | ---- | --------- | ------------------------------ | | \[0] | uint32\[] | IDs of selected group members. | ### dkgParameters ```solidity function dkgParameters() external view returns (struct EcdsaDkg.Parameters) ``` Retrieves dkg parameters that were set in DKG library. ### authorizationParameters ```solidity function authorizationParameters() external view returns (uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) ``` Returns authorization-related parameters. The minimum authorization is also returned by `minimumAuthorization()` function, as a requirement of `IApplication` interface. #### Return Values | Name | Type | Description | | --------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimumAuthorization | uint96 | The minimum authorization amount required so that operator can participate in the random beacon. This amount is required to execute slashing for providing a malicious DKG result or when a relay entry times out. | | authorizationDecreaseDelay | uint64 | Delay in seconds that needs to pass between the time authorization decrease is requested and the time that request gets approved. Protects against free-riders earning rewards and not being active in the network. | | authorizationDecreaseChangePeriod | uint64 | Authorization decrease change period in seconds. It is the time, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | ### rewardParameters ```solidity function rewardParameters() external view returns (uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) ``` Retrieves reward-related parameters. #### Return Values | Name | Type | Description | | ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | maliciousDkgResultNotificationRewardMultiplier | uint256 | Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about a malicious DKG result. Notifiers are rewarded from a notifiers treasury pool. For example, if notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected. | | sortitionPoolRewardsBanDuration | uint256 | Duration of the sortition pool rewards ban imposed on operators who missed their turn for DKG result submission or who failed a heartbeat. | ### slashingParameters ```solidity function slashingParameters() external view returns (uint96 maliciousDkgResultSlashingAmount) ``` Retrieves slashing-related parameters. #### Return Values | Name | Type | Description | | -------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | maliciousDkgResultSlashingAmount | uint96 | Slashing amount for submitting a malicious DKG result. Every DKG result submitted can be challenged for the time of `dkg.resultChallengePeriodLength`. If the DKG result submitted is challenged and proven to be malicious, the operator who submitted the malicious result is slashed for `_maliciousDkgResultSlashingAmount`. | ### gasParameters ```solidity function gasParameters() external view returns (uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) ``` Retrieves gas-related parameters. #### Return Values | Name | Type | Description | | --------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dkgResultSubmissionGas | uint256 | Calculated max gas cost for submitting a DKG result. This will be refunded as part of the DKG approval process. It is in the submitter's interest to not skip his priority turn on the approval, otherwise the refund of the DKG submission will be refunded to another group member that will call the DKG approve function. | | dkgResultApprovalGasOffset | uint256 | Gas that is meant to balance the DKG result approval's overall cost. It can be updated by the governance based on the current market conditions. | | notifyOperatorInactivityGasOffset | uint256 | Gas that is meant to balance the notification of an operator inactivity. It can be updated by the governance based on the current market conditions. | | notifySeedTimeoutGasOffset | uint256 | Gas that is meant to balance the notification of a seed for DKG delivery timeout. It can be updated by the governance based on the current market conditions. | | notifyDkgTimeoutNegativeGasOffset | uint256 | Gas that is meant to balance the notification of a DKG protocol execution timeout. It can be updated by the governance based on the current market conditions. | # WalletRegistryGovernance ## WalletRegistryGovernance Owns the `WalletRegistry` contract and is responsible for updating its governable parameters in respect to the governance delay. ### newGovernanceDelay ```solidity uint256 newGovernanceDelay ``` ### governanceDelayChangeInitiated ```solidity uint256 governanceDelayChangeInitiated ``` ### newWalletRegistryGovernance ```solidity address newWalletRegistryGovernance ``` ### walletRegistryGovernanceTransferInitiated ```solidity uint256 walletRegistryGovernanceTransferInitiated ``` ### newWalletOwner ```solidity address newWalletOwner ``` ### walletOwnerChangeInitiated ```solidity uint256 walletOwnerChangeInitiated ``` ### newMinimumAuthorization ```solidity uint96 newMinimumAuthorization ``` ### minimumAuthorizationChangeInitiated ```solidity uint256 minimumAuthorizationChangeInitiated ``` ### newAuthorizationDecreaseDelay ```solidity uint64 newAuthorizationDecreaseDelay ``` ### authorizationDecreaseDelayChangeInitiated ```solidity uint256 authorizationDecreaseDelayChangeInitiated ``` ### newAuthorizationDecreaseChangePeriod ```solidity uint64 newAuthorizationDecreaseChangePeriod ``` ### authorizationDecreaseChangePeriodChangeInitiated ```solidity uint256 authorizationDecreaseChangePeriodChangeInitiated ``` ### newMaliciousDkgResultSlashingAmount ```solidity uint96 newMaliciousDkgResultSlashingAmount ``` ### maliciousDkgResultSlashingAmountChangeInitiated ```solidity uint256 maliciousDkgResultSlashingAmountChangeInitiated ``` ### newMaliciousDkgResultNotificationRewardMultiplier ```solidity uint256 newMaliciousDkgResultNotificationRewardMultiplier ``` ### maliciousDkgResultNotificationRewardMultiplierChangeInitiated ```solidity uint256 maliciousDkgResultNotificationRewardMultiplierChangeInitiated ``` ### newSortitionPoolRewardsBanDuration ```solidity uint256 newSortitionPoolRewardsBanDuration ``` ### sortitionPoolRewardsBanDurationChangeInitiated ```solidity uint256 sortitionPoolRewardsBanDurationChangeInitiated ``` ### newDkgSeedTimeout ```solidity uint256 newDkgSeedTimeout ``` ### dkgSeedTimeoutChangeInitiated ```solidity uint256 dkgSeedTimeoutChangeInitiated ``` ### newDkgResultChallengePeriodLength ```solidity uint256 newDkgResultChallengePeriodLength ``` ### dkgResultChallengePeriodLengthChangeInitiated ```solidity uint256 dkgResultChallengePeriodLengthChangeInitiated ``` ### newDkgResultChallengeExtraGas ```solidity uint256 newDkgResultChallengeExtraGas ``` ### dkgResultChallengeExtraGasChangeInitiated ```solidity uint256 dkgResultChallengeExtraGasChangeInitiated ``` ### newDkgResultSubmissionTimeout ```solidity uint256 newDkgResultSubmissionTimeout ``` ### dkgResultSubmissionTimeoutChangeInitiated ```solidity uint256 dkgResultSubmissionTimeoutChangeInitiated ``` ### newSubmitterPrecedencePeriodLength ```solidity uint256 newSubmitterPrecedencePeriodLength ``` ### dkgSubmitterPrecedencePeriodLengthChangeInitiated ```solidity uint256 dkgSubmitterPrecedencePeriodLengthChangeInitiated ``` ### newDkgResultSubmissionGas ```solidity uint256 newDkgResultSubmissionGas ``` ### dkgResultSubmissionGasChangeInitiated ```solidity uint256 dkgResultSubmissionGasChangeInitiated ``` ### newDkgResultApprovalGasOffset ```solidity uint256 newDkgResultApprovalGasOffset ``` ### dkgResultApprovalGasOffsetChangeInitiated ```solidity uint256 dkgResultApprovalGasOffsetChangeInitiated ``` ### newNotifyOperatorInactivityGasOffset ```solidity uint256 newNotifyOperatorInactivityGasOffset ``` ### notifyOperatorInactivityGasOffsetChangeInitiated ```solidity uint256 notifyOperatorInactivityGasOffsetChangeInitiated ``` ### newNotifySeedTimeoutGasOffset ```solidity uint256 newNotifySeedTimeoutGasOffset ``` ### notifySeedTimeoutGasOffsetChangeInitiated ```solidity uint256 notifySeedTimeoutGasOffsetChangeInitiated ``` ### newNotifyDkgTimeoutNegativeGasOffset ```solidity uint256 newNotifyDkgTimeoutNegativeGasOffset ``` ### notifyDkgTimeoutNegativeGasOffsetChangeInitiated ```solidity uint256 notifyDkgTimeoutNegativeGasOffsetChangeInitiated ``` ### newReimbursementPool ```solidity address payable newReimbursementPool ``` ### reimbursementPoolChangeInitiated ```solidity uint256 reimbursementPoolChangeInitiated ``` ### walletRegistry ```solidity contract WalletRegistry walletRegistry ``` ### governanceDelay ```solidity uint256 governanceDelay ``` ### GovernanceDelayUpdateStarted ```solidity event GovernanceDelayUpdateStarted(uint256 governanceDelay, uint256 timestamp) ``` ### GovernanceDelayUpdated ```solidity event GovernanceDelayUpdated(uint256 governanceDelay) ``` ### WalletRegistryGovernanceTransferStarted ```solidity event WalletRegistryGovernanceTransferStarted(address newWalletRegistryGovernance, uint256 timestamp) ``` ### WalletRegistryGovernanceTransferred ```solidity event WalletRegistryGovernanceTransferred(address newWalletRegistryGovernance) ``` ### WalletOwnerUpdateStarted ```solidity event WalletOwnerUpdateStarted(address walletOwner, uint256 timestamp) ``` ### WalletOwnerUpdated ```solidity event WalletOwnerUpdated(address walletOwner) ``` ### MinimumAuthorizationUpdateStarted ```solidity event MinimumAuthorizationUpdateStarted(uint96 minimumAuthorization, uint256 timestamp) ``` ### MinimumAuthorizationUpdated ```solidity event MinimumAuthorizationUpdated(uint96 minimumAuthorization) ``` ### AuthorizationDecreaseDelayUpdateStarted ```solidity event AuthorizationDecreaseDelayUpdateStarted(uint64 authorizationDecreaseDelay, uint256 timestamp) ``` ### AuthorizationDecreaseDelayUpdated ```solidity event AuthorizationDecreaseDelayUpdated(uint64 authorizationDecreaseDelay) ``` ### AuthorizationDecreaseChangePeriodUpdateStarted ```solidity event AuthorizationDecreaseChangePeriodUpdateStarted(uint64 authorizationDecreaseChangePeriod, uint256 timestamp) ``` ### AuthorizationDecreaseChangePeriodUpdated ```solidity event AuthorizationDecreaseChangePeriodUpdated(uint64 authorizationDecreaseChangePeriod) ``` ### MaliciousDkgResultSlashingAmountUpdateStarted ```solidity event MaliciousDkgResultSlashingAmountUpdateStarted(uint256 maliciousDkgResultSlashingAmount, uint256 timestamp) ``` ### MaliciousDkgResultSlashingAmountUpdated ```solidity event MaliciousDkgResultSlashingAmountUpdated(uint256 maliciousDkgResultSlashingAmount) ``` ### MaliciousDkgResultNotificationRewardMultiplierUpdateStarted ```solidity event MaliciousDkgResultNotificationRewardMultiplierUpdateStarted(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 timestamp) ``` ### MaliciousDkgResultNotificationRewardMultiplierUpdated ```solidity event MaliciousDkgResultNotificationRewardMultiplierUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier) ``` ### SortitionPoolRewardsBanDurationUpdateStarted ```solidity event SortitionPoolRewardsBanDurationUpdateStarted(uint256 sortitionPoolRewardsBanDuration, uint256 timestamp) ``` ### SortitionPoolRewardsBanDurationUpdated ```solidity event SortitionPoolRewardsBanDurationUpdated(uint256 sortitionPoolRewardsBanDuration) ``` ### DkgSeedTimeoutUpdateStarted ```solidity event DkgSeedTimeoutUpdateStarted(uint256 dkgSeedTimeout, uint256 timestamp) ``` ### DkgSeedTimeoutUpdated ```solidity event DkgSeedTimeoutUpdated(uint256 dkgSeedTimeout) ``` ### DkgResultChallengePeriodLengthUpdateStarted ```solidity event DkgResultChallengePeriodLengthUpdateStarted(uint256 dkgResultChallengePeriodLength, uint256 timestamp) ``` ### DkgResultChallengePeriodLengthUpdated ```solidity event DkgResultChallengePeriodLengthUpdated(uint256 dkgResultChallengePeriodLength) ``` ### DkgResultChallengeExtraGasUpdateStarted ```solidity event DkgResultChallengeExtraGasUpdateStarted(uint256 dkgResultChallengeExtraGas, uint256 timestamp) ``` ### DkgResultChallengeExtraGasUpdated ```solidity event DkgResultChallengeExtraGasUpdated(uint256 dkgResultChallengeExtraGas) ``` ### DkgResultSubmissionTimeoutUpdateStarted ```solidity event DkgResultSubmissionTimeoutUpdateStarted(uint256 dkgResultSubmissionTimeout, uint256 timestamp) ``` ### DkgResultSubmissionTimeoutUpdated ```solidity event DkgResultSubmissionTimeoutUpdated(uint256 dkgResultSubmissionTimeout) ``` ### DkgSubmitterPrecedencePeriodLengthUpdateStarted ```solidity event DkgSubmitterPrecedencePeriodLengthUpdateStarted(uint256 submitterPrecedencePeriodLength, uint256 timestamp) ``` ### DkgSubmitterPrecedencePeriodLengthUpdated ```solidity event DkgSubmitterPrecedencePeriodLengthUpdated(uint256 submitterPrecedencePeriodLength) ``` ### DkgResultSubmissionGasUpdateStarted ```solidity event DkgResultSubmissionGasUpdateStarted(uint256 dkgResultSubmissionGas, uint256 timestamp) ``` ### DkgResultSubmissionGasUpdated ```solidity event DkgResultSubmissionGasUpdated(uint256 dkgResultSubmissionGas) ``` ### DkgResultApprovalGasOffsetUpdateStarted ```solidity event DkgResultApprovalGasOffsetUpdateStarted(uint256 dkgResultApprovalGasOffset, uint256 timestamp) ``` ### DkgResultApprovalGasOffsetUpdated ```solidity event DkgResultApprovalGasOffsetUpdated(uint256 dkgResultApprovalGasOffset) ``` ### NotifyOperatorInactivityGasOffsetUpdateStarted ```solidity event NotifyOperatorInactivityGasOffsetUpdateStarted(uint256 notifyOperatorInactivityGasOffset, uint256 timestamp) ``` ### NotifyOperatorInactivityGasOffsetUpdated ```solidity event NotifyOperatorInactivityGasOffsetUpdated(uint256 notifyOperatorInactivityGasOffset) ``` ### NotifySeedTimeoutGasOffsetUpdateStarted ```solidity event NotifySeedTimeoutGasOffsetUpdateStarted(uint256 notifySeedTimeoutGasOffset, uint256 timestamp) ``` ### NotifySeedTimeoutGasOffsetUpdated ```solidity event NotifySeedTimeoutGasOffsetUpdated(uint256 notifySeedTimeoutGasOffset) ``` ### NotifyDkgTimeoutNegativeGasOffsetUpdateStarted ```solidity event NotifyDkgTimeoutNegativeGasOffsetUpdateStarted(uint256 notifyDkgTimeoutNegativeGasOffset, uint256 timestamp) ``` ### NotifyDkgTimeoutNegativeGasOffsetUpdated ```solidity event NotifyDkgTimeoutNegativeGasOffsetUpdated(uint256 notifyDkgTimeoutNegativeGasOffset) ``` ### ReimbursementPoolUpdateStarted ```solidity event ReimbursementPoolUpdateStarted(address reimbursementPool, uint256 timestamp) ``` ### ReimbursementPoolUpdated ```solidity event ReimbursementPoolUpdated(address reimbursementPool) ``` ### onlyAfterGovernanceDelay ```solidity modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) ``` Reverts if called before the governance delay elapses. #### Parameters | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------- | | changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | ### constructor ```solidity constructor(contract WalletRegistry _walletRegistry, uint256 _governanceDelay) public ``` ### upgradeRandomBeacon ```solidity function upgradeRandomBeacon(address _newRandomBeacon) external ``` Upgrades the random beacon. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------- | ------- | ------------------------- | | \_newRandomBeacon | address | New random beacon address | ### initializeWalletOwner ```solidity function initializeWalletOwner(address _walletOwner) external ``` Initializes the Wallet Owner's address. Can be called only by the contract owner. It can be called only if walletOwner has not been set before. It doesn't enforce a governance delay for the initial update. Any subsequent updates should be performed with beginWalletOwnerUpdate/finalizeWalletOwnerUpdate with respect of a governance delay. #### Parameters | Name | Type | Description | | ------------- | ------- | -------------------------- | | \_walletOwner | address | The Wallet Owner's address | ### beginGovernanceDelayUpdate ```solidity function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external ``` Begins the governance delay update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------- | ------- | -------------------- | | \_newGovernanceDelay | uint256 | New governance delay | ### finalizeGovernanceDelayUpdate ```solidity function finalizeGovernanceDelayUpdate() external ``` Finalizes the governance delay update process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletRegistryGovernanceTransfer ```solidity function beginWalletRegistryGovernanceTransfer(address _newWalletRegistryGovernance) external ``` Begins the wallet registry governance transfer process. Can be called only by the contract owner. ### finalizeWalletRegistryGovernanceTransfer ```solidity function finalizeWalletRegistryGovernanceTransfer() external ``` Finalizes the wallet registry governance transfer process. Can be called only by the contract owner, after the governance delay elapses. ### beginWalletOwnerUpdate ```solidity function beginWalletOwnerUpdate(address _newWalletOwner) external ``` Begins the wallet owner update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------- | ------- | ------------------------ | | \_newWalletOwner | address | New wallet owner address | ### finalizeWalletOwnerUpdate ```solidity function finalizeWalletOwnerUpdate() external ``` Finalizes the wallet owner update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMinimumAuthorizationUpdate ```solidity function beginMinimumAuthorizationUpdate(uint96 _newMinimumAuthorization) external ``` Begins the minimum authorization amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------- | ------ | --------------------------------- | | \_newMinimumAuthorization | uint96 | New minimum authorization amount. | ### finalizeMinimumAuthorizationUpdate ```solidity function finalizeMinimumAuthorizationUpdate() external ``` Finalizes the minimum authorization amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginAuthorizationDecreaseDelayUpdate ```solidity function beginAuthorizationDecreaseDelayUpdate(uint64 _newAuthorizationDecreaseDelay) external ``` Begins the authorization decrease delay update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------- | ------ | -------------------------------- | | \_newAuthorizationDecreaseDelay | uint64 | New authorization decrease delay | ### finalizeAuthorizationDecreaseDelayUpdate ```solidity function finalizeAuthorizationDecreaseDelayUpdate() external ``` Finalizes the authorization decrease delay update process. Can be called only by the contract owner, after the governance delay elapses. ### beginAuthorizationDecreaseChangePeriodUpdate ```solidity function beginAuthorizationDecreaseChangePeriodUpdate(uint64 _newAuthorizationDecreaseChangePeriod) external ``` Begins the authorization decrease change period update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------------- | ------ | ---------------------------------------- | | \_newAuthorizationDecreaseChangePeriod | uint64 | New authorization decrease change period | ### finalizeAuthorizationDecreaseChangePeriodUpdate ```solidity function finalizeAuthorizationDecreaseChangePeriodUpdate() external ``` Finalizes the authorization decrease change period update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMaliciousDkgResultSlashingAmountUpdate ```solidity function beginMaliciousDkgResultSlashingAmountUpdate(uint96 _newMaliciousDkgResultSlashingAmount) external ``` Begins the malicious DKG result slashing amount update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------------- | ------ | ---------------------------------------- | | \_newMaliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | ### finalizeMaliciousDkgResultSlashingAmountUpdate ```solidity function finalizeMaliciousDkgResultSlashingAmountUpdate() external ``` Finalizes the malicious DKG result slashing amount update process. Can be called only by the contract owner, after the governance delay elapses. ### beginMaliciousDkgResultNotificationRewardMultiplierUpdate ```solidity function beginMaliciousDkgResultNotificationRewardMultiplierUpdate(uint256 _newMaliciousDkgResultNotificationRewardMultiplier) external ``` Begins the DKG malicious result notification reward multiplier update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------------------------------- | ------- | -------------------------------------------------------- | | \_newMaliciousDkgResultNotificationRewardMultiplier | uint256 | New DKG malicious result notification reward multiplier. | ### finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate ```solidity function finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate() external ``` Finalizes the DKG malicious result notification reward multiplier update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgResultSubmissionGasUpdate ```solidity function beginDkgResultSubmissionGasUpdate(uint256 _newDkgResultSubmissionGas) external ``` Begins the dkg result submission gas update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------------------------- | ------- | ------------------------------ | | \_newDkgResultSubmissionGas | uint256 | New DKG result submission gas. | ### finalizeDkgResultSubmissionGasUpdate ```solidity function finalizeDkgResultSubmissionGasUpdate() external ``` Finalizes the dkg result submission gas update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgResultApprovalGasOffsetUpdate ```solidity function beginDkgResultApprovalGasOffsetUpdate(uint256 _newDkgResultApprovalGasOffset) external ``` Begins the dkg approval gas offset update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------- | ------- | ---------------------------- | | \_newDkgResultApprovalGasOffset | uint256 | New DKG result approval gas. | ### finalizeDkgResultApprovalGasOffsetUpdate ```solidity function finalizeDkgResultApprovalGasOffsetUpdate() external ``` Finalizes the dkg result approval gas offset update process. Can be called only by the contract owner, after the governance delay elapses. ### beginNotifyOperatorInactivityGasOffsetUpdate ```solidity function beginNotifyOperatorInactivityGasOffsetUpdate(uint256 _newNotifyOperatorInactivityGasOffset) external ``` Begins the notify operator inactivity gas offset update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------------- | ------- | ----------------------------------------------- | | \_newNotifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset | ### finalizeNotifyOperatorInactivityGasOffsetUpdate ```solidity function finalizeNotifyOperatorInactivityGasOffsetUpdate() external ``` Finalizes the notify operator inactivity gas offset update process. Can be called only by the contract owner, after the governance delay elapses. ### beginNotifySeedTimeoutGasOffsetUpdate ```solidity function beginNotifySeedTimeoutGasOffsetUpdate(uint256 _newNotifySeedTimeoutGasOffset) external ``` Begins the notify seed for DKG delivery timeout gas offset update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------- | ------- | --------------------------------------------------------- | | \_newNotifySeedTimeoutGasOffset | uint256 | New seed for DKG delivery timeout notification gas offset | ### finalizeNotifySeedTimeoutGasOffsetUpdate ```solidity function finalizeNotifySeedTimeoutGasOffsetUpdate() external ``` Finalizes the notify seed for DKG delivery timeout gas offset update process. Can be called only by the contract owner, after the governance delay elapses. ### beginNotifyDkgTimeoutNegativeGasOffsetUpdate ```solidity function beginNotifyDkgTimeoutNegativeGasOffsetUpdate(uint256 _newNotifyDkgTimeoutNegativeGasOffset) external ``` Begins the notify DKG timeout negative gas offset update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | -------------------------------------- | ------- | ---------------------------------------------------- | | \_newNotifyDkgTimeoutNegativeGasOffset | uint256 | New DKG timeout negative gas notification gas offset | ### finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate ```solidity function finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate() external ``` Finalizes the notify DKG timeout negative gas offset update process. Can be called only by the contract owner, after the governance delay elapses. ### beginReimbursementPoolUpdate ```solidity function beginReimbursementPoolUpdate(address payable _newReimbursementPool) external ``` Begins the reimbursement pool update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ---------------------- | --------------- | ----------------------- | | \_newReimbursementPool | address payable | New reimbursement pool. | ### finalizeReimbursementPoolUpdate ```solidity function finalizeReimbursementPoolUpdate() external ``` Finalizes the reimbursement pool update process. Can be called only by the contract owner, after the governance delay elapses. ### beginSortitionPoolRewardsBanDurationUpdate ```solidity function beginSortitionPoolRewardsBanDurationUpdate(uint256 _newSortitionPoolRewardsBanDuration) external ``` Begins the sortition pool rewards ban duration update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------------ | ------- | ---------------------------------------- | | \_newSortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration. | ### finalizeSortitionPoolRewardsBanDurationUpdate ```solidity function finalizeSortitionPoolRewardsBanDurationUpdate() external ``` Finalizes the sortition pool rewards ban duration update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgSeedTimeoutUpdate ```solidity function beginDkgSeedTimeoutUpdate(uint256 _newDkgSeedTimeout) external ``` Begins the DKG seed timeout update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------- | ------- | ------------------------------ | | \_newDkgSeedTimeout | uint256 | New DKG seed timeout in blocks | ### finalizeDkgSeedTimeoutUpdate ```solidity function finalizeDkgSeedTimeoutUpdate() external ``` Finalizes the DKG seed timeout update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgResultChallengePeriodLengthUpdate ```solidity function beginDkgResultChallengePeriodLengthUpdate(uint256 _newDkgResultChallengePeriodLength) external ``` Begins the DKG result challenge period length update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ----------------------------------- | ------- | ------------------------------------------------ | | \_newDkgResultChallengePeriodLength | uint256 | New DKG result challenge period length in blocks | ### finalizeDkgResultChallengePeriodLengthUpdate ```solidity function finalizeDkgResultChallengePeriodLengthUpdate() external ``` Finalizes the DKG result challenge period length update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgResultChallengeExtraGasUpdate ```solidity function beginDkgResultChallengeExtraGasUpdate(uint256 _newDkgResultChallengeExtraGas) external ``` Begins the DKG result challenge extra gas update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------- | ------- | ---------------------------------- | | \_newDkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | ### finalizeDkgResultChallengeExtraGasUpdate ```solidity function finalizeDkgResultChallengeExtraGasUpdate() external ``` Finalizes the DKG result challenge extra gas update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgResultSubmissionTimeoutUpdate ```solidity function beginDkgResultSubmissionTimeoutUpdate(uint256 _newDkgResultSubmissionTimeout) external ``` Begins the DKG result submission timeout update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------- | ------- | ------------------------------------------- | | \_newDkgResultSubmissionTimeout | uint256 | New DKG result submission timeout in blocks | ### finalizeDkgResultSubmissionTimeoutUpdate ```solidity function finalizeDkgResultSubmissionTimeoutUpdate() external ``` Finalizes the DKG result submission timeout update process. Can be called only by the contract owner, after the governance delay elapses. ### beginDkgSubmitterPrecedencePeriodLengthUpdate ```solidity function beginDkgSubmitterPrecedencePeriodLengthUpdate(uint256 _newSubmitterPrecedencePeriodLength) external ``` Begins the DKG submitter precedence period length update process. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | ------------------------------------ | ------- | ---------------------------------------------------- | | \_newSubmitterPrecedencePeriodLength | uint256 | New DKG submitter precedence period length in blocks | ### finalizeDkgSubmitterPrecedencePeriodLengthUpdate ```solidity function finalizeDkgSubmitterPrecedencePeriodLengthUpdate() external ``` Finalizes the DKG submitter precedence period length update process. Can be called only by the contract owner, after the governance delay elapses. ### withdrawIneligibleRewards ```solidity function withdrawIneligibleRewards(address recipient) external ``` Withdraws rewards belonging to operators marked as ineligible for sortition pool rewards. Can be called only by the contract owner. #### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------- | | recipient | address | Recipient of withdrawn rewards. | ### getRemainingGovernanceDelayUpdateTime ```solidity function getRemainingGovernanceDelayUpdateTime() external view returns (uint256) ``` Get the time remaining until the governance delay can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingWalletRegistryGovernanceTransferDelayTime ```solidity function getRemainingWalletRegistryGovernanceTransferDelayTime() external view returns (uint256) ``` Get the time remaining until the wallet registry governance can be transferred. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingMimimumAuthorizationUpdateTime ```solidity function getRemainingMimimumAuthorizationUpdateTime() external view returns (uint256) ``` Get the time remaining until the minimum authorization amount can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingAuthorizationDecreaseDelayUpdateTime ```solidity function getRemainingAuthorizationDecreaseDelayUpdateTime() external view returns (uint256) ``` Get the time remaining until the authorization decrease delay can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingAuthorizationDecreaseChangePeriodUpdateTime ```solidity function getRemainingAuthorizationDecreaseChangePeriodUpdateTime() external view returns (uint256) ``` Get the time remaining until the authorization decrease change period can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingMaliciousDkgResultSlashingAmountUpdateTime ```solidity function getRemainingMaliciousDkgResultSlashingAmountUpdateTime() external view returns (uint256) ``` Get the time remaining until the malicious DKG result slashing amount can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime ```solidity function getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime() external view returns (uint256) ``` Get the time remaining until the DKG malicious result notification reward multiplier duration can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingSortitionPoolRewardsBanDurationUpdateTime ```solidity function getRemainingSortitionPoolRewardsBanDurationUpdateTime() external view returns (uint256) ``` Get the time remaining until the sortition pool rewards ban duration can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingDkgSeedTimeoutUpdateTime ```solidity function getRemainingDkgSeedTimeoutUpdateTime() external view returns (uint256) ``` Get the time remaining until the DKG seed timeout can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingDkgResultChallengePeriodLengthUpdateTime ```solidity function getRemainingDkgResultChallengePeriodLengthUpdateTime() external view returns (uint256) ``` Get the time remaining until the DKG result challenge period length can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingDkgResultChallengeExtraGasUpdateTime ```solidity function getRemainingDkgResultChallengeExtraGasUpdateTime() external view returns (uint256) ``` ### getRemainingDkgResultSubmissionTimeoutUpdateTime ```solidity function getRemainingDkgResultSubmissionTimeoutUpdateTime() external view returns (uint256) ``` Get the time remaining until the DKG result submission timeout can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingWalletOwnerUpdateTime ```solidity function getRemainingWalletOwnerUpdateTime() external view returns (uint256) ``` Get the time remaining until the wallet owner can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime ```solidity function getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime() external view returns (uint256) ``` Get the time remaining until the wallet owner can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingDkgResultSubmissionGasUpdateTime ```solidity function getRemainingDkgResultSubmissionGasUpdateTime() external view returns (uint256) ``` Get the time remaining until the dkg result submission gas can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingDkgResultApprovalGasOffsetUpdateTime ```solidity function getRemainingDkgResultApprovalGasOffsetUpdateTime() external view returns (uint256) ``` Get the time remaining until the dkg result approval gas offset can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingNotifyOperatorInactivityGasOffsetUpdateTime ```solidity function getRemainingNotifyOperatorInactivityGasOffsetUpdateTime() external view returns (uint256) ``` Get the time remaining until the operator inactivity gas offset can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingNotifySeedTimeoutGasOffsetUpdateTime ```solidity function getRemainingNotifySeedTimeoutGasOffsetUpdateTime() external view returns (uint256) ``` Get the time remaining until the seed for DKG delivery timeout gas offset can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime ```solidity function getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime() external view returns (uint256) ``` Get the time remaining until the DKG timeout negative gas offset can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingReimbursementPoolUpdateTime ```solidity function getRemainingReimbursementPoolUpdateTime() external view returns (uint256) ``` Get the time remaining until reimbursement pool can be updated. #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | ### getRemainingChangeTime ```solidity function getRemainingChangeTime(uint256 changeTimestamp) internal view returns (uint256) ``` Gets the time remaining until the governable parameter update can be committed. #### Parameters | Name | Type | Description | | --------------- | ------- | ------------------------------------------------- | | changeTimestamp | uint256 | Timestamp indicating the beginning of the change. | #### Return Values | Name | Type | Description | | ---- | ------- | -------------------------- | | \[0] | uint256 | Remaining time in seconds. | # Wallets ## Wallets ### Wallet ```solidity struct Wallet { bytes32 membersIdsHash; bytes32 publicKeyX; bytes32 publicKeyY; } ``` ### Data ```solidity struct Data { mapping(bytes32 => struct Wallets.Wallet) registry; uint256[49] __gap; } ``` ### validatePublicKey ```solidity function validatePublicKey(struct Wallets.Data self, bytes publicKey) internal view ``` Performs preliminary validation of a new group public key. The group public key must be unique and have 64 bytes in length. If the validation fails, the function reverts. This function must be called first for a public key of a wallet added with `addWallet` function. #### Parameters | Name | Type | Description | | --------- | ------------------- | ---------------------------------------- | | self | struct Wallets.Data | | | publicKey | bytes | Uncompressed public key of a new wallet. | ### addWallet ```solidity function addWallet(struct Wallets.Data self, bytes32 membersIdsHash, bytes publicKey) internal returns (bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) ``` Registers a new wallet. This function does not validate parameters. The code calling this function must call `validatePublicKey` first. Uses a public key hash as a unique identifier of a wallet. #### Parameters | Name | Type | Description | | -------------- | ------------------- | ------------------------------------------------- | | self | struct Wallets.Data | | | membersIdsHash | bytes32 | Keccak256 hash of group members identifiers array | | publicKey | bytes | Uncompressed public key | #### Return Values | Name | Type | Description | | ---------- | ------- | ---------------------------------- | | walletID | bytes32 | Wallet's ID | | publicKeyX | bytes32 | Wallet's public key's X coordinate | | publicKeyY | bytes32 | Wallet's public key's Y coordinate | ### deleteWallet ```solidity function deleteWallet(struct Wallets.Data self, bytes32 walletID) internal ``` Deletes wallet with the given ID from the registry. Reverts if wallet with the given ID has not been registered or if it has already been closed. ### isWalletRegistered ```solidity function isWalletRegistered(struct Wallets.Data self, bytes32 walletID) internal view returns (bool) ``` Checks if a wallet with the given ID is registered. #### Parameters | Name | Type | Description | | -------- | ------------------- | ----------- | | self | struct Wallets.Data | | | walletID | bytes32 | Wallet's ID | #### Return Values | Name | Type | Description | | ---- | ---- | ----------------------------------------------- | | \[0] | bool | True if a wallet is registered, false otherwise | ### getWalletMembersIdsHash ```solidity function getWalletMembersIdsHash(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32) ``` Returns Keccak256 hash of the wallet signing group members identifiers array. Group members do not include operators selected by the sortition pool that misbehaved during DKG. Reverts if wallet with the given ID is not registered. #### Parameters | Name | Type | Description | | -------- | ------------------- | ---------------- | | self | struct Wallets.Data | | | walletID | bytes32 | ID of the wallet | #### Return Values | Name | Type | Description | | ---- | ------- | --------------------------------- | | \[0] | bytes32 | Wallet signing group members hash | ### getWalletPublicKeyCoordinates ```solidity function getWalletPublicKeyCoordinates(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32 x, bytes32 y) ``` Gets public key of a wallet with the given wallet ID. The public key is returned as X and Y coordinates. Reverts if wallet with the given ID is not registered. #### Parameters | Name | Type | Description | | -------- | ------------------- | ---------------- | | self | struct Wallets.Data | | | walletID | bytes32 | ID of the wallet | #### Return Values | Name | Type | Description | | ---- | ------- | ----------------------- | | x | bytes32 | Public key X coordinate | | y | bytes32 | Public key Y coordinate | ### getWalletPublicKey ```solidity function getWalletPublicKey(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes) ``` Gets public key of a wallet with the given wallet ID. The public key is returned in an uncompressed format as a 64-byte concatenation of X and Y coordinates. Reverts if wallet with the given ID is not registered. #### Parameters | Name | Type | Description | | -------- | ------------------- | ---------------- | | self | struct Wallets.Data | | | walletID | bytes32 | ID of the wallet | #### Return Values | Name | Type | Description | | ---- | ----- | ------------------------------------- | | \[0] | bytes | Uncompressed public key of the wallet | # Mainnet ## Threshold Contracts (Ethereum L1) Delivered in `@threshold-network/solidity-contracts@1.2.1` package.
ContractAddress
T Token0xCdF7028ceAB81fA0C6971208e83fa7872994beE5
Governor Bravo Timelock Controller0x87F005317692D05BAA4193AB0c961c69e175f45f
## tBTC Application Contracts (Ethereum L1) Delivered in `@keep-network/random-beacon@2.0.0`, `@keep-network/ecdsa@2.0.0` and `@keep-network/tbtc-v2@1.6.0` packages. | Contract | Address | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Bridge | [0x5e4861a80B55f035D899f66772117F00FA0E8e7B](https://etherscan.io/address/0x5e4861a80B55f035D899f66772117F00FA0E8e7B) | | RebateStaking | [0x0184739C32edc3471D3e4860c8E39a5f3Ff85A45](https://etherscan.io/address/0x0184739C32edc3471D3e4860c8E39a5f3Ff85A45) | | Timelock Controller | [0x92f2d8b72a7F6a551Be60b9aa4194248E9B4913D](https://etherscan.io/address/0x92f2d8b72a7F6a551Be60b9aa4194248E9B4913D#code) | | RandomBeacon | [0x5499f54b4A1CB4816eefCf78962040461be3D80b](https://etherscan.io/address/0x5499f54b4A1CB4816eefCf78962040461be3D80b) | | TBTC | [0x18084fbA666a33d37592fA2633fD49a74DD93a88](https://etherscan.io/address/0x18084fbA666a33d37592fA2633fD49a74DD93a88) | | TBTCVault | [0x9C070027cdC9dc8F82416B2e5314E11DFb4FE3CD](https://etherscan.io/address/0x9C070027cdC9dc8F82416B2e5314E11DFb4FE3CD) | | VendingMachineV3 | [0x7570a2350183b4BdF7CA74faD3Fc19048E6437e6](https://etherscan.io/address/0x7570a2350183b4BdF7CA74faD3Fc19048E6437e6) | | WalletRegistry | [0x46d52E41C2F300BC82217Ce22b920c34995204eb](https://etherscan.io/address/0x46d52E41C2F300BC82217Ce22b920c34995204eb) | | WalletProposalValidator | [0x30019D85a86ABD3cDA1167F4C052690c32FBDEc2](https://etherscan.io/address/0x30019D85a86ABD3cDA1167F4C052690c32FBDEc2) | | RedemptionWatchtower | [0xB8dF0A949aC45ff8f401553A1dcb742Feb38E6D3](https://etherscan.io/address/0xB8dF0A949aC45ff8f401553A1dcb742Feb38E6D3) | | CoveragePool | [0x7D7B622C07f216d99eFc3EfB9Cf71872F46D811A](https://etherscan.io/address/0x7D7B622C07f216d99eFc3EfB9Cf71872F46D811A) | | Relayer Bot | [0x45332eee9b495b1dda896fd53112eaacc10b2c19](https://etherscan.io/address/0x45332eee9b495b1dda896fd53112eaacc10b2c19) | | L1BitcoinDepositor (Arbitrum) | [0x75A6e4A7C8fAa162192FAD6C1F7A6d48992c619A](https://etherscan.io/address/0x75A6e4A7C8fAa162192FAD6C1F7A6d48992c619A) | | L1BitcoinDepositor (Base) | [0x186D048097c7406C64EfB0537886E3CaE100a1fe](https://etherscan.io/address/0x186D048097c7406C64EfB0537886E3CaE100a1fe) | | L1BTCRedeemerProxy | [0x5D4d83aaB53B7E7cA915AEB2d4d3f4e03823DbDe](https://etherscan.io/address/0x5D4d83aaB53B7E7cA915AEB2d4d3f4e03823DbDe) | | LockReleaseTokenPoolUpgradeable | [0x03E342731c08FDDc34cFb43E91cB3a7e424ee0F6](https://etherscan.io/address/0x03E342731c08FDDc34cFb43E91cB3a7e424ee0F6#readProxyContract) | | CCIP Router (BOB) | [0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D](mailto:undefined) | ## L2/Other tBTC Application Contracts ### Arbitrum One (chain ID: 42161) | Contract | Address | | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | ArbitrumTBTC | [0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40](https://arbiscan.io/address/0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40) | | ArbitrumWormholeGateway | [0x1293a54e160D1cd7075487898d65266081A15458](https://arbiscan.io/address/0x1293a54e160D1cd7075487898d65266081A15458) | | L2BitcoinDepositor | [0x1C8d7b744b474c080faADd5BF9AD965Be4258F9e](https://arbiscan.io/address/0x1C8d7b744b474c080faADd5BF9AD965Be4258F9e) | | L2BTCRedeemerProxy | [0xd7Cd996a47b3293d4FEc2dBcF49692370334d9b7](https://arbiscan.io/address/0xd7Cd996a47b3293d4FEc2dBcF49692370334d9b7) | ### Base (chain ID: 8453) | Contract | Address | | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | BaseTBTC | [0x236aa50979D5f3De3Bd1Eeb40E81137F22ab794b](https://basescan.org/token/0x236aa50979d5f3de3bd1eeb40e81137f22ab794b) | | BaseWormholeGateway | [0x09959798B95d00a3183d20FaC298E4594E599eab](https://basescan.org/address/0x09959798b95d00a3183d20fac298e4594e599eab) | | L2BitcoinDepositor | [0xa2A81d9445b4F898b028c96D164bcd6c8C8C512E](https://basescan.org/address/0xa2A81d9445b4F898b028c96D164bcd6c8C8C512E) | | L2BTCRedeemerProxy | [0xe931F1Ac6B00400E1dAD153E184afeE164d2D88B](https://basescan.org/address/0xe931F1Ac6B00400E1dAD153E184afeE164d2D88B) | ### Optimism (chain ID: 10) | Contract | Address | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | OptimismTBTC | [0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40](https://optimistic.etherscan.io/address/0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40) | | OptimismWormholeGateway | [0x1293a54e160D1cd7075487898d65266081A15458](https://optimistic.etherscan.io/address/0x1293a54e160D1cd7075487898d65266081A15458) | ### Polygon PoS (chain ID: 137)
ContractAddress
PolygonTBTC0x236aa50979D5f3De3Bd1Eeb40E81137F22ab794b
PolygonWormholeGateway0x09959798B95d00a3183d20FaC298E4594E599eab
### Solana
ContractAddress
SolanaTBTC (Token)6DNSN2BJsaPFdFFc1zP37kkeNe4Usc1Sqkzr9C9vPWcU
SolanaTBTC (Program)Gj93RRt6QB7FjmyokAD5rcMAku7pq3Fk2Aa8y6nNbwsV
SolanaWormholeGateway87MEvHZCXE3ML5rrmh5uX1FbShHmRXXS32xJDGbQ7h5t
### Starknet | Contract | Address | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | StarknetTBTC | [0x04daa17763b286d1e59b97c283c0b8c949994c361e426a28f743c67bdfe9a32f](https://voyager.online/contract/0x04daa17763b286d1e59b97c283c0b8c949994c361e426a28f743c67bdfe9a32f) | | L1 StarkGate Bridge | [0x2111A49ebb717959059693a3698872a0aE9866b9](https://etherscan.io/address/0x2111A49ebb717959059693a3698872a0aE9866b9#tokentxns) | | L2 StarkGate Bridge | [0x067eb1988556edd7543a3c9ee24cc078be35fd49f0b7f264cc0434aeb6dfb09e](https://voyager.online/contract/0x067eb1988556edd7543a3c9ee24cc078be35fd49f0b7f264cc0434aeb6dfb09e) | | StarknetBitcoinDepositor | [0xC9031f76006da0BD4bFa9E02aDf0d448dB3BC155](https://etherscan.io/address/0xC9031f76006da0BD4bFa9E02aDf0d448dB3BC155#tokentxns) | ### Sui | Contract | Address | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sui tBTC | [0x77045f1b9f811a7a8fb9ebd085b5b0c55c5cb0d1520ff55f7037f89b5da9f5f1](https://suiscan.xyz/mainnet/coin/0x77045f1b9f811a7a8fb9ebd085b5b0c55c5cb0d1520ff55f7037f89b5da9f5f1::TBTC::TBTC/txs) | | L1BitcoinDepositor | [0xb810AbD43d8FCFD812d6FEB14fefc236E92a341A](https://etherscan.io/address/0xb810AbD43d8FCFD812d6FEB14fefc236E92a341A) | | Sui Package ID | [0x77045f1b9f811a7a8fb9ebd085b5b0c55c5cb0d1520ff55f7037f89b5da9f5f1](https://suiscan.xyz/mainnet/coin/0x77045f1b9f811a7a8fb9ebd085b5b0c55c5cb0d1520ff55f7037f89b5da9f5f1::TBTC::TBTC/txs) | ### BOB
BOB tBTC0xBBa2eF945D523C4e2608C9E1214C2Cc64D4fc2e2
Standard Bridge on BOB0x4200000000000000000000000000000000000010
BurnFromMintTokenPoolUpgradeable0x36Ee23c94523A05981baaEEaea4BA97cDDe21f6a
CCIP Router0x827716e74F769AB7b6bb374A29235d9c2156932C
# Sepolia Testnet ## Threshold Contracts Delivered in `@threshold-network/solidity-contracts@1.3.0-sepolia.0` NPM package.
ContractAddress
T Token0x46abDF5aD1726ba700794539C3dB8fE591854729
## TBTC Application Contracts Delivered in `@keep-network/random-beacon@2.1.0-sepolia.1`, `@keep-network/ecdsa@2.1.0-sepolia.1` and `@keep-network/tbtc-v2@1.6.0-sepolia.6` NPM packages. | Contract | Address | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Bridge | [0x9b1a7fE5a16A15F2f9475C5B231750598b113403](https://sepolia.etherscan.io/address/0x9b1a7fE5a16A15F2f9475C5B231750598b113403#code) | | RandomBeacon | [0x02CBA6D77CF9fB019e322c55b34c9d42f2eF4D74](https://sepolia.etherscan.io/address/0x02CBA6D77CF9fB019e322c55b34c9d42f2eF4D74) | | TBTC | [0x517f2982701695D4E52f1ECFBEf3ba31Df470161](https://sepolia.etherscan.io/address/0x517f2982701695D4E52f1ECFBEf3ba31Df470161) | | TBCTVault | [0xB5679dE944A79732A75CE556191DF11F489448d5](https://sepolia.etherscan.io/address/0xB5679dE944A79732A75CE556191DF11F489448d5) | | VendingMachine | [0x0b82E51164720543dB3FB13043876F37e9a19A4A](https://sepolia.etherscan.io/address/0x0b82E51164720543dB3FB13043876F37e9a19A4A) | | WalletRegistry | [0x2DfC89675AB5Fb5Be7c2A86d373Daac3E795fc25](https://sepolia.etherscan.io/address/0x2DfC89675AB5Fb5Be7c2A86d373Daac3E795fc25) | | WalletProposalValidator | [0x4d7E5B28F018C60Ed662017b381eEd553cfa8Fbe](https://sepolia.etherscan.io/address/0x4d7E5B28F018C60Ed662017b381eEd553cfa8Fbe) | | LightRelay | [0x998D17122dA4ed98e558198665984E08D1cEAA8d](https://sepolia.etherscan.io/address/0x998D17122dA4ed98e558198665984E08D1cEAA8d) | | LightRelayMaintainerProxy | [0xA669AC294BCf04CEeB5EBC26d9E1bF4fc4574e06](https://sepolia.etherscan.io/address/0xA669AC294BCf04CEeB5EBC26d9E1bF4fc4574e06) | | RedemptionWatchtower | [0x4E6CFb556143381070b17825707b3DE7F3148FaC](https://sepolia.etherscan.io/address/0x4E6CFb556143381070b17825707b3DE7F3148FaC) | | L1BitcoinDepositor (Arbitrum) | [0xD9B523fb879C63b00ef14e48C98f4e3398d3BA2D](https://sepolia.etherscan.io/address/0xD9B523fb879C63b00ef14e48C98f4e3398d3BA2D) | | L1BitcoinDepositor (Base) | [0x59FAE614867b66421b44D1Ed3461e6B6a4B50106](https://sepolia.etherscan.io/address/0x59FAE614867b66421b44D1Ed3461e6B6a4B50106) | ## L2 tBTC Application Contracts ### Arbitrum Sepolia (chain ID: 421614) Delivered in `` @keep-network/tbtc-v2-arbitrum@1.1.1-sepolia.0` `` NPM package. | Contract | Address | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | ArbitrumTBTC | [0xb8f31A249bcb45267d06b9E51252c4793B917Cd0](https://sepolia.arbiscan.io/address/0xb8f31A249bcb45267d06b9E51252c4793B917Cd0) | | ArbitrumWormholeGateway | [0xc3D46e0266d95215589DE639cC4E93b79f88fc6C](https://sepolia.arbiscan.io/address/0xc3d46e0266d95215589de639cc4e93b79f88fc6c) | | L2BitcoinDepositor | [0xB2fEC598a9374078Bb639f3d70555fc4389b7a78](https://sepolia.arbiscan.io/address/0xB2fEC598a9374078Bb639f3d70555fc4389b7a78) | ### Optimism Sepolia (chain ID: 11155420) Delivered in `` @keep-network/tbtc-v2-optimism@1.1.0-sepolia.0` `` NPM package. | Contract | Address | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | OptimismTBTC | [0x9A82bE743f0120fA24893b1631B6b2817fD94b1D](https://sepolia-optimism.etherscan.io/address/0x9a82be743f0120fa24893b1631b6b2817fd94b1d) | | OptimismWormholeGateway | [0x5FB63D9e076a314023F2D1aB5dBFd7045C281EbA](https://sepolia-optimism.etherscan.io/address/0x5FB63D9e076a314023F2D1aB5dBFd7045C281EbA) | ### Base Sepolia (chain ID: 84532) Delivered in `` @keep-network/tbtc-v2-base@1.1.0-sepolia.0` `` NPM package. | Contract | Address | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | BaseTBTC | [0xb8f31A249bcb45267d06b9E51252c4793B917Cd0](https://sepolia.basescan.org/address/0xb8f31A249bcb45267d06b9E51252c4793B917Cd0) | | BaseWormholeGateway | [0xc3D46e0266d95215589DE639cC4E93b79f88fc6C](https://sepolia.basescan.org/address/0xc3D46e0266d95215589DE639cC4E93b79f88fc6C) | | L2BitcoinDepositor | [0xDEbD9aA9BC4845c7Cd2d9a997F82A2Daea540bD5](https://sepolia.basescan.org/address/0xDEbD9aA9BC4845c7Cd2d9a997F82A2Daea540bD5) | ### Starknet Sepolia | Contract | Address | | ------------------------ | ------------------------------------------------------------------ | | StarknetTBTC | 0x05f09ee6e942b869aa159287924156cb9bc4510a447c0cc80a898780434d5c2c | | L1 StarkGate Bridge | 0xF6217de888fD6E6b2CbFBB2370973BE4c36a152D | | L2 StarkGate Bridge | 0x01fd5ad689cec587e80a3d380b5b47ff082203e118bdd22b77256ffa379b15d9 | | StarknetBitcoinDepositor | 0x40c74a5f0b0e6CC3Ae4E8dD2Db46d372504445DA | # Security Audits This page documents the various third-party security audits conducted on Threshold Network components, including tBTC bridge, staking contracts, the vending machines, thUSD, and integrations. ## Protocol Upgrades #### Defense by Thesis - Beta Staker Allowlist & Bridge Fee Rebates * **Date:** 27 November 2025 * **Report:** [View Audit 1 PDF](https://drive.google.com/file/d/1ymBpfc9vihOVA-XccqhpeitnZS208O5u/view) - [View Audit 2 PDF](https://drive.google.com/file/d/1QK1jnaoqdtoeyqTD7xz93sSk1BwerFwe/view?usp=sharing) * **Scope:** Smart contracts for T staking rebates. See related proposals, [TIP-067](https://forum.threshold.network/t/beta-staker-expansion-tip-067-compensation-adjustment/1113) and [TIP-106](https://forum.threshold.network/t/tip-106-experimenting-with-a-tbtc-fee-rebate-for-locking-t-tokens/1146) #### **Defense by Thesis - WalletRegistry & EcdsaDkg** * **Date**: 5 November 2025 * **Report**: [View PDF](https://drive.google.com/file/d/1oQJO-fW4ZUUS_DQovOtaB9CB7U6YT0AP/view?usp=sharing) * **Scope:** WalletRegistry and EcdsaDkg smart contracts #### **Defense by Thesis - Gasless Minting Feature for the Threshold App** * **Date**: 31 Oct 2025 * **Report**: [View PDF](https://drive.google.com/file/d/1RW4Bb3Rd_HdOU8pVxLpIRXCXDYKubeIp/view?usp=sharing) * **Scope:** NativeBTCDepositor contract ## Cross-Chain Integrations #### Certora - Threshold CCIP Update * **Date:** 25 Sept 2025 * **Report:** [View PDF](https://drive.google.com/file/d/1Sxc5qx69qQtqdy7AtscoAHyGaSyqyYJM/view?usp=sharing) * **Scope:** Threshold CCIP Update #### MixBytes() - Cross-Chain Redemptions * **Date:** 08 Sept 2025 * **Report:** [View PDF](https://drive.google.com/file/d/1rbVYly_VuW6LdAwhpbgxO8DpNiBn-6Vk/view?usp=sharing) * **Scope:** Cross-chain bridge transfers #### Zellic – Sui Integration (tBTC) * **Date:** 01 May 2025 * **Report:** [View PDF](https://www.notion.so/threshold-labs/tBTC-Direct-Minting-Audit-Reports-1ec45959b48e8008ab0fe7b20a130760?source=copy_link#1f345959b48e8033a1cfffe4ab1922e1) * **Scope:** tBTC integration with the Sui blockchain #### Hashlock – Starknet Integration (tBTC) * **Date:** April 2025 * **Report:** [View PDF](https://www.notion.so/threshold-labs/tBTC-Direct-Minting-Audit-Reports-1ec45959b48e8008ab0fe7b20a130760?source=copy_link#1f345959b48e80bba0cbccff21d5bf7b) * **Scope:** tBTC integration with the StarkNet blockchain #### **Thesis Defense – Base Integration (tBTC)** * **Date:** April 11th, 2024 * **Report:** [View PDF](https://github.com/Thesis-Defense/Security-Audit-Reports/blob/main/PDFs/240411_Thesis_Defense-Threshold_tBTC_Base_Smart_Contracts_Security_Audit_Report.pdf) * **Scope:** tBTC integration with the Base blockchain ## tBTC Bridge Audits #### Least Authority – Solana Smart Contracts (tBTC) * **Date:** 29 August 2023 * **Report:** [View Audit PDF](https://leastauthority.com/blog/audits/audit-of-keep-network-solana-smart-contracts/) - [Link to Least Authority](https://leastauthority.com/blog/audits/audit-of-keep-network-solana-smart-contracts/) * **Scope:** Smart contracts for the tBTC Bridge on Solana #### Least Authority – tBTC Bridge * **Date:** 29 September 2022 * **Report:** [View Audit PDF](https://github.com/threshold-network/security-audits/blob/main/29-Sep-2022-LeastAuthority.pdf) - [Link to Least Authority](https://leastauthority.com/blog/audits/audit-of-keep-network-tbtc-bridge-v2/) * **Scope:** Security audit of the core tBTC Bridge contracts ### T Vending Machine Audits #### CertiK – Vending Machine * **Date:** 19 November 2021 * **Report:** [View Audit PDF](https://github.com/threshold-network/security-audits/blob/main/19-Nov-2021-CertiK.pdf) - [Link to CertiK](https://www.certik.com/projects/threshold-network) * **Scope:** Vending machine security audit #### ChainSecurity – Staking, T Token, and Vending Machine * **Date:** 09 November 2021 * **Report:** [View Audit PDF](https://github.com/threshold-network/security-audits/blob/main/09-Nov-2021-ChainSecurity.pdf) - [Link to ChainSecurity](https://chainsecurity.com/security-audit/threshold-network) * **Scope:** Staking contracts, T token logic, and vending machine mechanisms # Links
ResourceLink
Threshold Websitehttps://threshold.network
Apphttps://app.threshold.network
Githubhttps://github.com/threshold-network
DefiLlama (tBTC)https://defillama.com/yields?token=TBTC
Bug Bountyhttps://immunefi.com/bug-bounty/thresholdnetwork/information/
Discordhttps://discord.gg/threshold
Governance Forumhttps://forum.threshold.network
Bloghttps://threshold.network/blog
Mediumhttps://medium.com/thresholdnetwork
X (Threshold Network)https://twitter.com/thetnetwork
X (tBTC)https://twitter.com/tbtc_project
Dune Analyticshttps://dune.com/threshold_network/tbtc-performance-dashboard
CoinMarketCap (T token)https://coinmarketcap.com/currencies/threshold/
CoinMarketCap (tBTC)https://coinmarketcap.com/currencies/tbtc-token/
Youtubehttps://www.youtube.com/@Threshold.Network
Linkedinhttps://linkedin.com/company/threshold-network
Galxehttps://app.galxe.com/quest/Threshold