Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 is the value accrual and governance asset for the network.
A comprehensive guide to understand Threshold's token: T
The T token 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.
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 API endpoint -
Total Supply -
Circulating Supply -
Treasury Supply -
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 .
T tokens give holders two ways to participate in Threshold Network.
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.
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.
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.
Since the beginning of 2026, T token holders have been able to stake their T to receive fee rebates and waivers 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 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.
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.
This page explains how you can swap your NU and KEEP tokens to T token.
If you still hold KEEP or NU, you can still convert your tokens to T. The migration began around the launch of Threshold in 2022. That original migration experience is now legacy infrastructure, and the old upgrade UI is no longer a practical way to complete the conversion.
However, the underlying smart contracts did not disappear.
The KEEP and NU Vending Machine contracts were designed to remain available indefinitely, which means there is no migration deadline for liquid KEEP or NU tokens. If you still have KEEP or NU sitting in your wallet, you can interact with those contracts directly through Etherscan.
It looks more technical than the old UI, but the process itself is relatively straightforward.
The conversion ratios were fixed when Threshold launched and are based on the respective token supplies rather than their market prices. ()
Before the Vending Machine can convert your KEEP/NU, you first need to give the contract permission to use the KEEP you want to upgrade. Open the KEEP/NU Token Addresses on etherscan, listed as:

KEEP : 0x85eee30c52b0b379b046fb0f85f4f3dc3009afec
NU: 0x4fe83213d56308330ec302a8bd641f1d0113a4cc
a) Then connect the wallet containing your KEEP/NU.
b) Find the function called: approve
c) For spender, enter the KEEP/NU Vending Machine address
d) For amount, enter how much KEEP/NU you want to convert. One slightly confusing part is that Etherscan expects the amount in the token’s smallest unit. KEEP/ NU has 18 decimals.
1 KEEP/NU
1000000000000000000
10 KEEP/NU
10000000000000000000
100 KEEP/NU
100000000000000000000
Once your approval has been confirmed a) Open the KEEP/ NU Vending Machines:
b) Select: Contract → Write Contract → Connect to Web3
c) Connect the same wallet and find: wrap Under amount Enter the amount of KEEP/NU you want to convert, again using 18 decimals.
For example, for 100 KEEP/NU:
100000000000000000000
There is no deadline to upgrade liquid KEEP or NU into T. The Vending Machine contracts were intentionally designed to remain available to legacy token holders indefinitely. Remember that this requires two transactions:
Approve → Wrap → Receive T
You will therefore need enough ETH to cover gas for both transactions.
Most importantly, do not simply send KEEP or NU to the Vending Machine contract address. Use the approve and wrap functions described above.
If you are upgrading a significant amount and have never interacted directly with a smart contract through Etherscan before, consider converting a small amount first. Once you have confirmed that the T arrived correctly, you can repeat the process for the remaining balance.
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.
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.
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. 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.
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% 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
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 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 .
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:
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.
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.
Returns the difficulty of the current epoch.
Returns the difficulty of the previous epoch.
For a high-level overview of the tBTC protocol, please see the tBTC Bitcoin Bridge section.

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.
function getCurrentEpochDifficulty() external view returns (uint256)function getPrevEpochDifficulty() external view returns (uint256)constructor() publicAnother 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.
First, initialize the SDK, as described in the Initialize SDK guide.
Once the SDK is initialized, you can unmint and request for redemption in the following way:
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)Here you can find instructions explaining how to use the SDK in your own project.
To install the tBTC SDK in your project, run:
yarn add @keep-network/tbtc-v2.tsnpm i @keep-network/tbtc-v2.tsPlease note that you will also need to install the ethers v5 library to initialize a signer or provider. To do so, invoke:
yarn add ethers@legacy-v5npm i ethers@legacy-v5Here is a brief example demonstrating the use of the SDK in Ethereum:
// 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.(...)Here is a brief example demonstrating the use of the SDK in some L2, e.g. Arbitrum:
// 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.(...)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
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 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.
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 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
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:
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)This mode of the SDK will initialize Ethereum, Bitcoin and an L2 to work with tBTC. Compatible with mainnet and testnet.
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:
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.
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).
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).
function receiveBalanceApproval(address owner, uint256 amount, bytes extraData) externalCalled 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.
IVault is an interface for a smart contract consuming Bank balances of other contracts or externally owned accounts (EOA).
function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) externalCalled 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.
Here you'll find the Sepolia testnet version of the Threshold dapp.
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.
First, initialize the SDK, as described in the guide.
Once the SDK is initialized, you can initiate the deposit and get their Bitcoin address in the following way:
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
Reverts if the governance delay has not passed since the change initiated time or if the change has not been initiated.
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
You can learn about APIs of contracts related to ECDSA under the following links:
Find answers to some of the most commonly asked questions here.
Certain errors may be reported by your node. See a sample below:
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.
VBA is built based on what institutions actually need for Institutional Bitcoin deployment.
Verifiable Bitcoin Accounts (VBA) are a way for institutions to use Bitcoin without compromise, enabling deployment in onchain lending and yield markets while preserving existing custody arrangements.
Built on Threshold Network's battle-tested signer infrastructure, Verifiable Bitcoin Accounts (VBA) are 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 a compliant, tax-advantaged pathway to on-chain finance.
Every spending condition is verifiable on-chain and auditable by design.
depositors
address[]
Addresses of depositors whose deposits have been swept.
depositedAmounts
uint256[]
Amounts deposited by individual depositors and swept.
x
bytes32
Wallet's public key's X coordinate.
y
bytes32
Wallet's public key's Y coordinate.
[0]
bytes
Compressed public key (33-byte), prefixed with 02 or 03.
Utils: general utility functions


The extraData passed to Bank.approveBalanceAndCall.
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
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:
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"}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.
To create a new Ethereum account, install Geth (GoEthereum) and create a new account using the command below. This account will subsequently be referred to as the Operator Account.
When prompted, provide a password to protect the operator key file.
Once the process completes, your public key will be displayed. Take note of your Operator Account public key.
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.
Governance delay.
Gets the time remaining until the governable parameter update can be committed.
changeInitiatedTimestamp
uint256
Timestamp indicating the beginning of the change.
delay
uint256
Governance delay.
[0]
uint256
Remaining time in seconds.
changeInitiatedTimestamp
uint256
The timestamp at which the change has been initiated.
delay
uint256
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)
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.
message
bytes
Message signed by the wallet. It is a potential heartbeat message, Bitcoin transaction preimage, or an arbitrary signed bytes.
[0]
bool
True if valid heartbeat message, false otherwise.
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. 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. The SDK depends on ethers v5. Proper support for newer ethers versions is
not guaranteed right now.// 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()// 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])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()geth account new --keystore /home/$USER/.operator-keyfunction onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal viewfunction getRemainingGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view returns (uint256)function isValidHeartbeatMessage(bytes message) internal pure returns (bool)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.
contract ILightRelay lightRelaymapping(address => bool) isAuthorizedStores 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.
uint256 retargetGasOffsetGas that is meant to balance the retarget overall cost. Can be
event LightRelayUpdated(address newRelay)event MaintainerAuthorized(address maintainer)event MaintainerDeauthorized(address maintainer)event RetargetGasOffsetUpdated(uint256 retargetGasOffset)modifier onlyRelayMaintainer()modifier onlyReimbursableAdmin()constructor(contract ILightRelay _lightRelay, contract ReimbursementPool _reimbursementPool) publicfunction updateLightRelay(contract ILightRelay _lightRelay) externalAllows 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.
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.
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.
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.
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.
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.
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:
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:
function __ecdsaWalletCreatedCallback(bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) externalCallback function executed once a new wallet is created.
Should be callable only by the Wallet Registry.
walletID
bytes32
Wallet's unique identifier.
Callback function executed once a wallet heartbeat failure is detected.
Should be callable only by the Wallet Registry.
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.
1. Go to https://boardroom.io/threshold.
2. Connect your wallet.
3. Click "Set Up Delegation".
4. Select your "Delegation Type" - either to yourself or a third party.
5. Enter "Delegate Address" and click on "Delegate Votes".
6. Sign the transaction.
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.
cd /home/$USER/
mkdir keep
cd keep
mkdir storage configThe 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.
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.
Assuming for the root user with the command provided in the step, the operator-key file should be located in the /.operator-key directory.
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
Discover how you can participate in Threshold Governance Process
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.
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. If a proposal receives majority support during the temperature check, it is eligible to move onto the next step.
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.
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.
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.
Execution: After the timelock delay, anyone can execute an approved proposal.
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.
Required network configuration for the tBTC v2 client.
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
Network
network.port
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 .
Follow along with this guide and leverage your Bitcoin by minting tBTC.
Here are some things you will need before you start the minting process: What you need:
✅ At least 0.01 Bitcoin (BTC)
✅ Bitcoin-compatible wallet (self-custodied)
✅ Destination Wallet (on supported chains; see the list of supported chains here.) 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.
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:
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 . The following snippet demonstrates SDK initialization in that case:
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:
You can even use another (non-Electrum) Bitcoin client implementation. This is how you can achieve that:
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:
You can learn about APIs of contracts related to the Bridge under the following links:
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!
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
This document explains the basic installation and configuration for the tBTC v2 client.
Please review this document in its entirety prior to beginning setup of your node to familiarize yourself with the general setup process.
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.
An accounting optimization for tracking bitcoin deposits in tBTC contracts
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.
When a user makes a deposit, they lock the funds using our . This creates an Unspent Transaction Output ().
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 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 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; <locktime>
TCP
3919
Status
clientInfo.port
TCP
9601
Arbitrum
0x9F6e831c8F8939DC0C830C6e492e7cEf4f9C2F5f
Optimism
0x7fB50BBabeDEE52b8760Ba15c0c199aF33Fc2EfA
Polygon
0x9F6e831c8F8939DC0C830C6e492e7cEf4f9C2F5f
Base
0x518385dd31289F1000fE6382b0C65df4d1Cd3bfC
Solana
814TqVmhQGKB3srSLRuMcH6m8qWFHRSbNpRxC5Xnador
Starknet
0x0314A42C20b0364C6df5Af35E0914dd65F24a61F3563a8bc2A9D664938f37c4F
N/A (Argent's Multisig)





maintainer
address
The address of the maintainer to be authorized.
maintainer
address
The address of the maintainer to be deauthorized.
newRetargetGasOffset
uint256
New retarget gas offset.
$ 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 1623235129789Wallet's public key's X coordinate.
publicKeyX
bytes32
publicKeyY
bytes32
Wallet's public key's X coordinate.
walletID
bytes32
Wallet's unique identifier.
publicKeyX
bytes32
publicKeyY
bytes32
function authorize(address maintainer) externalfunction deauthorize(address maintainer) externalfunction updateRetargetGasOffset(uint256 newRetargetGasOffset) externalfunction retarget(bytes headers) external$ 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"},
...
]
}function __ecdsaWalletHeartbeatFailedCallback(bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) externalcd /home/$USER/.operator-keyls -la
cp name_of_account_key_file /home/$USER/keep/config/name_of_account_key_fileimport * 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)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)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)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)Donation Vault must have an allowance for caller's balance in the Bank for at least amount.
amount
uint256
Amount of the Bank balance to donate.
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.
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.
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.
depositors
address[]
Addresses of depositors whose deposits have been swept.
depositedAmounts
uint256[]
Amounts deposited by individual depositors and swept.
contract Bank bankevent DonationReceived(address donor, uint256 donatedAmount)modifier onlyBank()constructor(contract Bank _bank) publicfunction donate(uint256 amount) externalfunction receiveBalanceApproval(address owner, uint256 amount, bytes) externalfunction receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) externalPersistent 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.
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.
AWS
c5.large
Azure
F2s v2
Google Cloud
n2-highcpu-2
Self-hosted
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, Infura, Ankr) or run your own Ethereum node (e.g. Geth).
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.
The client expects configuration options to be passed as CLI flags or specified in a 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.
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.
Here's a deposit for 10.3 BTC. That deposit is swept in transaction 0db1929c2fa41649264b95b9162bc7a12f43cb455a91bae7177667a53290d7e8 (along with many other deposits). That was one of three sweeps performed by that wallet (as of writing).
That transaction created a UTXO worth 1.51614471 BTC. The next transaction
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
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.
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:
<depositorAddress> DROP
<blindingFactor> DROP
DUP HASH160 <walletPubKeyHash> EQUAL
IF
CHECKSIG
ELSE
DUP HASH160 <refundPubkeyHash> EQUALVERIFY
<refundLocktime> CHECKLOCKTIMEVERIFY DROP
CHECKSIG
ENDIFSince 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.
struct DepositRevealInfo {
uint32 fundingOutputIndex;
bytes8 blindingFactor;
bytes20 walletPubKeyHash;
bytes20 refundPubKeyHash;
bytes4 refundLocktime;
address vault;
}struct DepositRequest {
address depositor;
uint64 amount;
uint32 revealedAt;
address vault;
uint64 treasuryFee;
uint32 sweptAt;
}event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault)function revealDeposit(struct BridgeState.Storage self, struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) externalUsed 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.
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
Review available CLI Options below.
$ 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.
Update procedure for the tBTC v2 client depends on installation method
The following instructions assume your docker install followed these installation instructions.
To update a tBTC node:
Pull the new image
docker pull keepnetwork/keep-client:latestRestart the tBTC service
sudo systemctl restart tbtcv2To free system resources, run
sudo docker container prunesudo docker image pruneExamine logs to ensure the node started correctly. Find Docker instance identification; it'll be a random combination of words, e.g. stinky_brownie:
sudo docker psUse specific identification and substitute accordingly; specify a path and file name for the log file:
sudo docker logs stinky_brownie >& /path/to/output/fileDisplay the log file
cat /path/to/output/fileLook for the following and take note of the version:
Alternatively, verify your client updated by visiting your status page:
Compare the displayed version number to the version number you are expecting, i.e.:
This install method requires downloading the latest version of the binary. Follow the installation steps provided .
This page will guide you through Binary setup steps.
See GitHub for the latest release: https://github.com/threshold-network/keep-core/releases
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:
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.gzAfter the download completes, use the command below to display the contents of the folder:
ls -laExtract the compressed file:
tar xzvf downloaded-file-name-here.tar.gzTo 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:
--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.
To launch the client, execute the following:
./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"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:
Congratulations, your node is up and running.
struct Claim {
bytes32 walletID;
uint256[] inactiveMembersIndices;
bool heartbeatFailed;
bytes signatures;
uint256[] signingMembersIndices;
}uint256 groupThresholdThe minimum number of wallet signing group members needed to interact according to the protocol to produce a valid inactivity claim.
uint256 signatureByteSizeSize in bytes of a single signature produced by member supporting the inactivity claim.
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()
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.
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.
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.
Wallets are created periodically based on governance. changes the time between wallets and 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 , requiring 51-of-100 Signers to cooperate.
The 100 signers on each wallet are chosen with our , and the randomness is provided by the .
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.
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
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.
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:
Signers' readiness announcement phase, which takes exactly 6 blocks
Signature production & advertisement phase, which takes up to 30 blocks
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.
Date: 27 November 2025
Report: -
Scope: Smart contracts for T staking rebates. See related proposals, and
bytes
2 vCPU / 2 GB RAM / 1 GiB Persistent Storage



Date: 5 November 2025
Report: View PDF
Scope: WalletRegistry and EcdsaDkg smart contracts
Date: 31 Oct 2025
Report: View PDF
Scope: NativeBTCDepositor contract
Date: 25 Sept 2025
Report: View PDF
Scope: Threshold CCIP Update
Date: 08 Sept 2025
Report: View PDF
Scope: Cross-chain bridge transfers
Date: 01 May 2025
Report: View PDF
Scope: tBTC integration with the Sui blockchain
Date: April 2025
Report: View PDF
Scope: tBTC integration with the StarkNet blockchain
Date: April 11th, 2024
Report: View PDF
Scope: tBTC integration with the Base blockchain
Date: 29 August 2023
Report: View Audit PDF - Link to Least Authority
Scope: Smart contracts for the tBTC Bridge on Solana
Date: 29 September 2022
Report: View Audit PDF - Link to Least Authority
Scope: Security audit of the core tBTC Bridge contracts
Date: 19 November 2021
Report: View Audit PDF - Link to CertiK
Scope: Vending machine security audit
Date: 09 November 2021
Report: View Audit PDF - Link to ChainSecurity
Scope: Staking contracts, T token logic, and vending machine mechanisms
Deposit reveal data, see `RevealInfo struct.
self
struct BridgeState.Storage
fundingTx
struct BitcoinTx.Info
Bitcoin funding transaction data, see BitcoinTx.Info.
reveal
self
struct BridgeState.Storage
refundLocktime
bytes4
The deposit refund locktime as 4-byte LE.
struct Deposit.DepositRevealInfo
▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
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 |
-----------------------------------------------------------------------------------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[]
inactiveMembers
uint32[]
Identifiers of members who are inactive
indices
uint256[]
Array to validate.
groupSize
uint256
Group size used as reference.
Identifiers of group members
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.
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:
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.
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.
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.
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
function validateDepositRefundLocktime(struct BridgeState.Storage self, bytes4 refundLocktime) internal viewhttp://111.222.333.444:9601/metricsclient_info{version="vX.X.X-XX"}
▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
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 |
-----------------------------------------------------------------------------------function validateMembersIndices(uint256[] indices, uint256 groupSize) internal pureP = (98 choose 51) / (100 choose 51) = ~0.24amount
uint256
The amount of tBTC v1 to exchange for tBTC v2.
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.
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
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.
amount
uint256
The amount of tBTC v2 to deposit into the contract.
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.
token
contract IERC20
The address of a token to withdraw.
recipient
address
The address which should receive withdrawn tokens.
amount
contract IERC20 tbtcV1contract TBTC tbtcV2event Exchanged(address to, uint256 amount)event Deposited(address from, uint256 amount)event Withdrawn(address token, address to, uint256 amount)constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) publicfunction exchange(uint256 amount) externalfunction receiveApproval(address from, uint256 amount, address token, bytes) externalfunction depositTbtcV2(uint256 amount) externalfunction withdrawFunds(contract IERC20 token, address recipient, uint256 amount) externalfunction _exchange(address tokenOwner, uint256 amount) internal(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.
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. From Wikipedia:
A Binomial distribution with parameters
nandpis the discrete probability distribution of the number of successes in a sequence ofnindependent experiments, each asking a yes–no question, and each with its own Boolean-valued outcome: success (with probabilityp) or failure (with probability1−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 to answer our question:
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:
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.
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!
tBTC landing page
Github
DefiLlama (tBTC)
Bug Bounty
Discord
Governance Forum
Blog
X (Threshold Network)
X (tBTC)
Dune Analytics
CoinMarketCap (T token)
CoinMarketCap (tBTC)
Youtube
Galxe
Threshold Website
Official App
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.
struct Parameters {
uint96 minimumAuthorization;
uint64 authorizationDecreaseDelay;
uint64 authorizationDecreaseChangePeriod;
}struct AuthorizationDecrease {
uint96 decreasingBy;
uint64 decreasingAt;
}struct Data {
struct EcdsaAuthorization.Parameters parameters;
mapping(address => address) stakingProviderToOperator;
mapping(address => address) operatorToStakingProvider;
mapping(address => struct EcdsaAuthorization.AuthorizationDecrease) pendingDecreases;
uint256[46] __gap;
}event OperatorRegistered(address stakingProvider, address operator)event AuthorizationIncreased(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount)event AuthorizationDecreaseRequested(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount, uint64 decreasingAt)event AuthorizationDecreaseApproved(address stakingProvider)event InvoluntaryAuthorizationDecreaseFailed(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount)event OperatorJoinedSortitionPool(address stakingProvider, address operator)event OperatorStatusUpdated(address stakingProvider, address operator)function setMinimumAuthorization(struct EcdsaAuthorization.Data self, uint96 _minimumAuthorization) internalSets the minimum authorization for ECDSA application. Without at least the minimum authorization, staking provider is not eligible to join and operate in the network.
function setAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseDelay) internalSets 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.
function setAuthorizationDecreaseChangePeriod(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseChangePeriod) internalSets 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.
function registerOperator(struct EcdsaAuthorization.Data self, address operator) internalUsed 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.
function authorizationIncreased(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internalUsed 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.
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.
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.
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.
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.
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.
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.
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.
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.
Returns the amount of stake that is pending authorization decrease for the given staking provider. If no authorization decrease has been requested, returns zero.
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.
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.
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.
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.
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
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.
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
The above assumptions can be used to divide costs into 4 categories:
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.
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.
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.
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
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.
This page describes the lifecycle and process of using Verifiable Bitcoin Accounts (VBA) M1 from product activation to concluding the position.
+---------------+
| Activation | governance switches M1 on: vault trusted, caps set
+-------+-------+
|
v
+----------------+
| Deposit and | bitcoin sent to the tBTC wallet, revealed
| Reveal | to the reservation vault
+-------+--------+
|
v
+----------------+
| Acceptance | depositor requests on Ethereum; Bridge
| Request | validates and reserves capacity
+-------+--------+
|
v
+----------------+
| Anchoring on | one Bitcoin transaction moves the deposit
| Bitcoin | into its own anchor UTXO
+-------+--------+
|
v
+----------------+
| Proof and | Bridge writes the position and credits the
| Minting | vault; the vault mints tBTC, pays the owner
+-------+--------+
|
v
+----------------+ +------------------+
| Custody | ---> | re-anchor |
| (position open)| <--- | (repeatable) |
| Active | +------------------+
+-------+--------+ when a wallet retires,
| the anchor moves to a
| different Live wallet
v
M1 end state: a position ends only if its custodying wallet dies
(Stranded). Exits such as in-kind redemption, renewal and
dissolution arrive in v2.M1 is switched on by governance. The reservation machinery ships inert: the router is registered with the Bridge, the vault is deployed but untrusted, and deposits cannot be revealed to it. Governance sets the parameters and caps through the delayed governance process, then marks the vault as trusted. That final switch is when reservations become possible. Signer software enables reservation duties only on networks where M1 is activated.
Send bitcoin to a tBTC threshold wallet deposit script then reveal the deposit on Ethereum. A deposit becomes reserved by naming the reservation at reveal time; the wallet named and committed to in the deposit script is the designated wallet, and only it can accept the deposit. Reserved deposits must use a refund locktime no later than the reveal time plus the term plus 24 hours, so an unaccepted deposit always becomes refundable on Bitcoin. No reservation minimum or cap is checked at reveal: only the ordinary dust threshold.
Reserved deposits are not charged the Bridge's normal deposit treasury fee; the vault's initiation fee applies instead
Only the depositor may request acceptance. The signing window is bounded: the deposit must be at least 2 hours old, signers must wait for 6 Bitcoin confirmations before proposing, and the window must fit within the refund deadline minus a 24-hour safety margin. Parameters that matter for proof and settlement are snapshotted at the time of the request; subsequent governance changes do not affect the in-flight action or the dates already recorded.
The position is Active. The owner holds ordinary tBTC, which is the anchor amount minus the initiation fee. The anchor sits under the custodying wallet; the wallet's honest majority protects it, fraud challenges police it, and the Bridge keeps the tracked claim equal to the anchor at all times. Re-anchoring is available at any position age. The recorded term dates exist so v2 can honor the term; in M1, nothing expires, renews, or closes on them, except that a position still sitting on a Closing wallet can be stranded once its dissolution date has passed.
Once a retiring wallet holds no reservations and its remaining balance is below the dust threshold, signer software reports that, so the wallet can begin closing.
Stranding is M1's only terminal state. Anyone may file it when the position is Active , and the custodying wallet is Terminated, Closed, or Closing with its dissolution date passed. The Bridge releases the capacity, drops the anchor from tracking, and records the position as Stranded. The owner's tBTC balance does not change; what is lost is the in-kind option of getting that specific bitcoin back, which v2 can honor. There is no compensation mechanism: if the bitcoin is really gone, the shortfall affects tBTC backing as a whole, exactly as with any terminated tBTC wallet today.
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.
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.
Requests a new wallet creation.
Only the Wallet Owner can call this function.
Closes an existing wallet.
Only the Wallet Owner can call this function.
address
tBTC v1 token address.
bytes
uint256
The amount to withdraw.
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.
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.).
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.

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 startConfiguration files in formats TOML, YAML and JSON are supported.
Sample configuration file:
function authorizationDecreaseRequested(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internalfunction approveAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internalfunction involuntaryAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address stakingProvider, uint96 fromAmount, uint96 toAmount) internalfunction joinSortitionPool(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool) internalfunction updateOperatorStatus(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internalfunction isOperatorUpToDate(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal view returns (bool)function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal view returns (uint96)function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider, uint96 decreasingBy) internal view returns (uint96)function pendingAuthorizationDecrease(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint96)function remainingAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint64) 1. DEPOSITOR, on Ethereum: requests acceptance for the deposit.
The Bridge checks the deposit (revealed, reserved, routed to the
vault, not swept, no duplicate position or pending action), checks
that the named wallet is the designated wallet and is Live, checks
the amount against the minimum and the caps, and records a pending
authorization: a deadline, snapshots of the max fee, the minimum
amount, the term and the dissolution delay. Capacity is reserved.
2. DESIGNATED WALLET, on Bitcoin: the wallet's signers check the
authorization on-chain, wait for the deposit to be confirmed, and
sign a one-input/one-output anchor transaction that pays the
wallet's key.
3. SPV MAINTAINER, on Ethereum: proves the confirmed anchor transaction
to the Bridge (Merkle inclusion, coinbase proof, proof-of-work).
4. BRIDGE, on Ethereum: settles the action - writes the position (owner,
custodying wallet, anchor outpoint, claim equal to anchor amount,
state Active, expiry and dissolution dates recorded) and credits
the vault. The vault mints tBTC against the anchor and transfers it
to the owner, minus the initiation fee. 1. REQUEST, on Ethereum: the position must be Active. If the source wallet
is Live, only governance may request (deliberate rotation off a healthy
wallet). If the source is retiring (MovingFunds or Closing), anyone may
request. The target must be a different wallet in the Live state, with a
free slot under its caps. Amount floor: the anchor must be greater than
the minimum plus one max fee.
2. SIGN, on Bitcoin: the source wallet's signers check the authorization
and sign a one-input/one-output re-anchor transaction paying the
target wallet. When a wallet is moving its funds, signer software
requests and signs these re-anchors automatically.
3. PROVE, on Ethereum: an SPV maintainer proves the transaction. The Bridge
moves custody to the target, shrinks the claim by the fee, releases the
source wallet's slot, and asks the vault to finance the fee: the vault
burns tBTC from its reserve, and any shortfall becomes public,
repayable fee debt.
4. LATE PROOF: a signed, confirmed re-anchor can be proven with no time
limit; a late proof can even restore a position that was stranded in
the meantime onto the new wallet.
IF THE REQUEST TIMES OUT: anyone can file the timeout. The target slot is
released, the position returns to Active on the same source wallet, and a
cooldown applies to the next non-governance request. No one is slashed.# 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"amount
uint256
The amount of tBTC v1 to exchange for tBTC v2.
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.
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
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.
amount
uint256
The amount of tBTC v2 to deposit into the contract.
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.
recipient
address
The address which should receive withdrawn tokens.
amount
uint256
The amount to withdraw.
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.
token
contract IERC20
The address of a token to recover.
recipient
address
The address which should receive recovered tokens.
amount
contract IERC20 tbtcV1contract TBTC tbtcV2event Exchanged(address to, uint256 amount)event Deposited(address from, uint256 amount)event TbtcV2Withdrawn(address to, uint256 amount)event FundsRecovered(address token, address to, uint256 amount)constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) publicfunction exchange(uint256 amount) externalfunction receiveApproval(address from, uint256 amount, address token, bytes) externalfunction depositTbtcV2(uint256 amount) externalfunction withdrawTbtcV2(address recipient, uint256 amount) externalfunction recoverFunds(contract IERC20 token, address recipient, uint256 amount) externalfunction _exchange(address tokenOwner, uint256 amount) internalID of the wallet.
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.
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
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.
walletID
bytes32
ID of the wallet.
[0]
bytes
Uncompressed public key of the wallet.
Check current wallet creation state.
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]
walletID
bytes32
ID of the wallet
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members
operator
[0]
bool
True - if the operator is a member of the given wallet signing group. False - otherwise.
function requestNewWallet() externalfunction closeWallet(bytes32 walletID) externalwalletID
bytes32
function seize(uint96 amount, uint256 rewardMultiplier, address notifier, bytes32 walletID, uint32[] walletMembersIDs) externalfunction getWalletPublicKey(bytes32 walletID) external view returns (bytes)function getWalletCreationState() external view returns (enum EcdsaDkg.State)function isWalletMember(bytes32 walletID, uint32[] walletMembersIDs, address operator, uint256 walletMemberIndex) external view returns (bool)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.
uint256 groupSizeSize of a group in DKG.
uint256 groupThresholdThe 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.
uint256 activeThresholdThe 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.
uint256 publicKeyByteSizeSize in bytes of a public key produced by group members during the the DKG. The length assumes uncompressed ECDSA public key.
uint256 signatureByteSizeSize in bytes of a single signature produced by operator supporting DKG result.
contract SortitionPool sortitionPoolconstructor(contract SortitionPool _sortitionPool) publicfunction 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.
Performs a static validation of DKG result fields: lengths, ranges, and order of arrays.
Performs validation of group members as declared in DKG result against group members selected by the sortition pool.
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.
Performs validation of hashed group members that actively took part in DKG.
Delivered in @threshold-network/[email protected] NPM package.
T Token
Delivered in @keep-network/[email protected], @keep-network/[email protected] and @keep-network/[email protected] NPM packages.
Delivered in @keep-network/[email protected]` NPM package.
Delivered in @keep-network/[email protected]` NPM package.
Delivered in @keep-network/[email protected]` NPM package.
address
tBTC v1 token address.
bytes
uint256
The amount to recover.
address
Address of the misbehavior notifier
walletID
bytes32
ID of the wallet
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members
address
Address of the checked operator
walletMemberIndex
uint256
Position of the operator in the wallet signing group members list
DKG start block
result
struct EcdsaDkg.Result
seed
uint256
seed used to start the DKG and select group members
startBlock
isValid
bool
true if the result is valid, false otherwise
errorMsg
string
validation error message; empty for a valid result
isValid
bool
true if the result is valid, false otherwise
errorMsg
string
validation error message; empty for a valid result
result
struct EcdsaDkg.Result
seed
uint256
seed used to start the DKG and select group members
[0]
bool
true if group members matches; false otherwise
result
struct EcdsaDkg.Result
startBlock
uint256
DKG start block
[0]
bool
true if group members matches; false otherwise
result
struct EcdsaDkg.Result
DKG result
[0]
bool
true if calculated result's group members hash matches with the one that is challenged.
uint256
function validateFields(struct EcdsaDkg.Result result) public pure returns (bool isValid, string errorMsg)function validateGroupMembers(struct EcdsaDkg.Result result, uint256 seed) public view returns (bool)function validateSignatures(struct EcdsaDkg.Result result, uint256 startBlock) public view returns (bool)function validateMembersHash(struct EcdsaDkg.Result result) public pure returns (bool)VendingMachine
WalletRegistry
WalletProposalValidator
LightRelay
LightRelayMaintainerProxy
RedemptionWatchtower
L1BitcoinDepositor (Arbitrum)
L1BitcoinDepositor (Base)
Bridge
RandomBeacon
TBTC
ArbitrumTBTC
ArbitrumWormholeGateway
L2BitcoinDepositor
OptimismTBTC
OptimismWormholeGateway
BaseTBTC
BaseWormholeGateway
L2BitcoinDepositor
StarknetTBTC
0x05f09ee6e942b869aa159287924156cb9bc4510a447c0cc80a898780434d5c2c
L1 StarkGate Bridge
0xF6217de888fD6E6b2CbFBB2370973BE4c36a152D
L2 StarkGate Bridge
0x01fd5ad689cec587e80a3d380b5b47ff082203e118bdd22b77256ffa379b15d9
StarknetBitcoinDepositor
0x40c74a5f0b0e6CC3Ae4E8dD2Db46d372504445DA
TBCTVault
Wormhole Token Bridge interface. Contains only selected functions used by L2WormholeGateway.
function completeTransferWithPayload(bytes encodedVm) external returns (bytes)function parseTransferWithPayload(bytes encoded) external pure returns (struct IWormholeTokenBridge.TransferWithPayload transfer)function transferTokens(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64 sequence)function transferTokensWithPayload(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint32 nonce, bytes payload) external payable returns (uint64 sequence)struct TransferWithPayload {
uint8 payloadID;
uint256 amount;
bytes32 tokenAddress;
uint16 tokenChain;
bytes32 to;
uint16 toChain;
bytes32 fromAddress;
bytes payload;
}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:
There is a tBTC holder on L1. The holder goes to the Wormhole Portal and selects the chain they want to bridge to.
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.
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:
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.
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.
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.
Reference to the Wormhole Token Bridge contract.
Wormhole tBTC token representation.
Canonical tBTC token.
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.
Minting limit for this gateway. Useful for early days of testing the system. The gateway can not mint more canonical tBTC than this limit.
The amount of tBTC minted by this contract. tBTC burned by this contract decreases this amount.
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.
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.
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.
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.
Lets the governance to update the tBTC minting limit for this contract.
Converts Ethereum address into Wormhole format.
Converts Wormhole address into Ethereum format.
Eliminates the dust that cannot be bridged with Wormhole due to the decimal shift in the Wormhole Bridge contract. See https://github.com/wormhole-foundation/wormhole/blob/96682bdbeb7c87bfa110eade0554b3d8cbf788d2/ethereum/contracts/bridge/Bridge.sol#L276-L288
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.
The time delay that needs to pass between initializing and finalizing update of any governable parameter in this contract.
Divisor for precision purposes. Used to represent fractions in parameter values.
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
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.
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.
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.
amount
uint256
The amount of tBTC to be sent.
recipientChain
uint16
The Wormhole recipient chain ID.
recipient
[0]
uint64
The Wormhole sequence number.
encodedVm
bytes
A byte array containing a Wormhole VAA signed by the guardians.
amount
uint256
The amount of Wormhole tBTC to deposit.
chainId
uint16
Wormhole ID of the chain.
gateway
bytes32
Address of tBTC gateway on the given chain in a Wormhole format.
_mintingLimit
uint256
The new minting limit.
_address
address
The address to convert.
_address
bytes32
The address to convert.
bytes32
contract IWormholeTokenBridge bridgecontract IERC20Upgradeable bridgeTokencontract L2TBTC tbtcmapping(uint16 => bytes32) gatewaysuint256 mintingLimituint256 mintedAmountevent WormholeTbtcReceived(address receiver, uint256 amount)event WormholeTbtcSent(uint256 amount, uint16 recipientChain, bytes32 gateway, bytes32 recipient, uint256 arbiterFee, uint32 nonce)event WormholeTbtcDeposited(address depositor, uint256 amount)event GatewayAddressUpdated(uint16 chainId, bytes32 gateway)event MintingLimitUpdated(uint256 mintingLimit)function initialize(contract IWormholeTokenBridge _bridge, contract IERC20Upgradeable _bridgeToken, contract L2TBTC _tbtc) externalfunction sendTbtc(uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64)function receiveTbtc(bytes encodedVm) externalfunction depositWormholeTbtc(uint256 amount) externalfunction updateGatewayAddress(uint16 chainId, bytes32 gateway) externalfunction updateMintingLimit(uint256 _mintingLimit) externalfunction toWormholeAddress(address _address) external pure returns (bytes32)function fromWormholeAddress(bytes32 _address) public pure returns (address)function normalize(uint256 amount) internal pure returns (uint256)VendingMachineThe 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.
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.
amount
uint256
The amount of TBTC v2 to mint from TBTC v1
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.
from
address
TBTC v1 token holder minting TBTC v2 tokens
amount
uint256
The amount of TBTC v2 to mint from TBTC v1
token
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.
amount
uint256
The amount of TBTC v2 to unmint to TBTC v1
Allows the Governance to withdraw unmint fees accumulated by VendingMachine.
recipient
address
The address receiving the fees
amount
uint256
The amount of fees in TBTC v2 to withdraw
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.
_newUnmintFee
uint256
The new unmint fee
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.
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.
_newVendingMachine
address
The new vending machine address
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.
Transfers unmint fee update initiator role to another address. Can be called only by the current unmint fee update initiator.
newInitiator
address
The new unmint fee update initiator
Transfers vending machine upgrade initiator role to another address. Can be called only by the current vending machine upgrade initiator.
newInitiator
address
The new vending machine upgrade initiator
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.
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.
Calculates the fee that needs to be paid to the VendingMachine to unmint the given amount of TBTC v2 back into TBTC v1.
uint256 GOVERNANCE_DELAYuint256 FLOATING_POINT_DIVISORcontract IERC20 tbtcV1contract TBTC tbtcV2uint256 unmintFeeuint256 newUnmintFeeuint256 unmintFeeUpdateInitiatedTimestampaddress unmintFeeUpdateInitiatoraddress newVendingMachineuint256 vendingMachineUpgradeInitiatedTimestampaddress vendingMachineUpgradeInitiatorevent UnmintFeeUpdateInitiated(uint256 newUnmintFee, uint256 timestamp)event UnmintFeeUpdated(uint256 newUnmintFee)event VendingMachineUpgradeInitiated(address newVendingMachine, uint256 timestamp)event VendingMachineUpgraded(address newVendingMachine)event Minted(address recipient, uint256 amount)event Unminted(address recipient, uint256 amount, uint256 fee)modifier only(address authorizedCaller)modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp)constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2, uint256 _unmintFee) publicfunction mint(uint256 amount) externalfunction receiveApproval(address from, uint256 amount, address token, bytes) externalfunction unmint(uint256 amount) externalfunction withdrawFees(address recipient, uint256 amount) externalfunction initiateUnmintFeeUpdate(uint256 _newUnmintFee) externalfunction finalizeUnmintFeeUpdate() externalfunction initiateVendingMachineUpgrade(address _newVendingMachine) externalfunction finalizeVendingMachineUpgrade() externalfunction transferUnmintFeeUpdateInitiatorRole(address newInitiator) externalfunction transferVendingMachineUpgradeInitiatorRole(address newInitiator) externalfunction getRemainingUnmintFeeUpdateTime() external view returns (uint256)function getRemainingVendingMachineUpgradeTime() external view returns (uint256)function unmintFeeFor(uint256 amount) public view returns (uint256)function _mint(address tokenOwner, uint256 amount) internalpublicKey
bytes
Uncompressed public key of a new wallet.
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.
self
struct Wallets.Data
membersIdsHash
bytes32
Keccak256 hash of group members identifiers array
publicKey
walletID
bytes32
Wallet's ID
publicKeyX
bytes32
Wallet's public key's X coordinate
publicKeyY
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.
Checks if a wallet with the given ID is registered.
self
struct Wallets.Data
walletID
bytes32
Wallet's ID
[0]
bool
True if a wallet is registered, false otherwise
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.
self
struct Wallets.Data
walletID
bytes32
ID of the wallet
[0]
bytes32
Wallet signing group members hash
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.
self
struct Wallets.Data
walletID
bytes32
ID of the wallet
x
bytes32
Public key X coordinate
y
bytes32
Public key Y coordinate
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.
self
struct Wallets.Data
walletID
bytes32
ID of the wallet
[0]
bytes
Uncompressed public key of the wallet
struct Wallet {
bytes32 membersIdsHash;
bytes32 publicKeyX;
bytes32 publicKeyY;
}struct Data {
mapping(bytes32 => struct Wallets.Wallet) registry;
uint256[49] __gap;
}function validatePublicKey(struct Wallets.Data self, bytes publicKey) internal viewself
struct Wallets.Data
function addWallet(struct Wallets.Data self, bytes32 membersIdsHash, bytes publicKey) internal returns (bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY)function deleteWallet(struct Wallets.Data self, bytes32 walletID) internalfunction isWalletRegistered(struct Wallets.Data self, bytes32 walletID) internal view returns (bool)function getWalletMembersIdsHash(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32)function getWalletPublicKeyCoordinates(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32 x, bytes32 y)function getWalletPublicKey(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes)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.
struct FraudChallenge {
address challenger;
uint256 depositAmount;
uint32 reportedAt;
bool resolved;
}event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s)event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash)event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash)function submitFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) externalSubmits 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
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.
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.
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.
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))
Extracts the UTXO keys from the given preimage used during signing of a witness input.
Extracts the UTXO key from the given preimage used during signing of a non-witness input.
Extracts the sighash type from the given preimage.
Sighash type is stored as the last 4 bytes in the preimage (little endian).
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.
contract Bridge bridgemapping(address => uint256) isWalletMaintainerAuthorized 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.
address[] walletMaintainersThis 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.
mapping(address => uint256) isSpvMaintainerAuthorized 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.
address[] spvMaintainersThis 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Gas that is meant to balance the defeat fraud challenge overall cost. Can be updated by the governance based on the current market conditions.
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.
Wraps Bridge.submitDepositSweepProof call and reimburses the caller's transaction cost.
See Bridge.submitDepositSweepProof function documentation.
Wraps Bridge.submitRedemptionProof call and reimburses the caller's transaction cost.
See Bridge.submitRedemptionProof function documentation.
Wraps Bridge.resetMovingFundsTimeout call and reimburses the caller's transaction cost.
See Bridge.resetMovingFundsTimeout function documentation.
Wraps Bridge.submitMovingFundsProof call and reimburses the caller's transaction cost.
See Bridge.submitMovingFundsProof function documentation.
Wraps Bridge.notifyMovingFundsBelowDust call and reimburses the caller's transaction cost.
See Bridge.notifyMovingFundsBelowDust function documentation.
Wraps Bridge.submitMovedFundsSweepProof call and reimburses the caller's transaction cost.
See Bridge.submitMovedFundsSweepProof function documentation.
Wraps Bridge.requestNewWallet call and reimburses the caller's transaction cost.
See Bridge.requestNewWallet function documentation.
Wraps Bridge.notifyWalletCloseable call and reimburses the caller's transaction cost.
See Bridge.notifyWalletCloseable function documentation.
Wraps Bridge.notifyWalletClosingPeriodElapsed call and reimburses the caller's transaction cost.
See Bridge.notifyWalletClosingPeriodElapsed function documentation.
Wraps Bridge.defeatFraudChallenge call and reimburses the caller's transaction cost.
See Bridge.defeatFraudChallenge function documentation.
Wraps Bridge.defeatFraudChallengeWithHeartbeat call and reimburses the caller's transaction cost.
See Bridge.defeatFraudChallengeWithHeartbeat function documentation.
Authorize a wallet maintainer that can interact with this reimbursement pool. Can be authorized by the owner only.
Authorize an SPV maintainer that can interact with this reimbursement pool. Can be authorized by the owner only.
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]
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]
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.
Updates the values of gas offset parameters.
Can be called only by the contract owner. The caller is responsible for validating parameters.
Gets an entire array of wallet maintainer addresses.
Gets an entire array of SPV maintainer addresses.
Delivered in @threshold-network/[email protected] package.
T Token
Governor Bravo Timelock Controller
Delivered in @keep-network/[email protected], @keep-network/[email protected] and @keep-network/[email protected] packages.
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.
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:
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.
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.
The time delay that needs to pass between initializing and finalizing the upgrade of governable parameters.
Multiplier to convert satoshi to TBTC token units.
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.
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:
This page will guide you through Docker setup steps.
Install or update Docker to the latest version. Visit the for detailed instructions. Use the command below to find your installed version if needed:
General best practices recommend against running the tBTC v2 client as the root user as a security precaution. One security-minded approach is to (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.
Navigate to cd /home/$USER/keep/
address
TBTC v1 token address
bytes
bytes
Uncompressed public key
bytes32
Wallet's public key's Y coordinate
Wallet can be challenged for the given signature only once.
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
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.
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.
membersIdsHashwalletIDDkgResultSubmittedDkgResultApprovedWalletRegistryThe amount of time indicated by challengeDefeatTimeout must pass after the challenge was reported.
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.
self
struct BridgeState.Storage
walletPublicKey
bytes
The public key of the wallet in the uncompressed and unprefixed format (64 bytes).
preimageSha256
self
struct BridgeState.Storage
walletPublicKey
bytes
The public key of the wallet in the uncompressed and unprefixed format (64 bytes).
preimage
self
struct BridgeState.Storage
walletPublicKey
bytes
The public key of the wallet in the uncompressed and unprefixed format (64 bytes),
heartbeatMessage
self
struct BridgeState.Storage
walletPublicKey
bytes
The public key of the wallet in the uncompressed and unprefixed format (64 bytes).
walletMembersIDs
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
utxoKey
uint256
UTXO key that identifies spent input.
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.
utxoKey
uint256
UTXO key that identifies spent input.
preimage
bytes
Serialized subset of the transaction. See BIP-143 for reference.
sighashType
uint32
Sighash type as a 32-bit integer.
bytes
bytes
bytes
uint32[]
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.
maintainer
address
Wallet maintainer to authorize.
maintainer
address
SPV maintainer to authorize.
maintainerToUnauthorize
address
Maintainer to unauthorize.
maintainerToUnauthorize
address
Maintainer to unauthorize.
newSubmitDepositSweepProofGasOffset
uint256
New submit deposit sweep proof gas offset.
newSubmitRedemptionProofGasOffset
uint256
New submit redemption proof gas offset.
fee = amount / optimisticMintingFeeDivisoroptimisticMintingFeeDivisor501/50 = 0.02 = 2%optimisticMintingFee = (depositAmount - treasuryFee) / optimisticMintingFeeDivisorThe time that needs to pass between the moment the optimistic minting is requested and the moment optimistic minting is finalized with minting TBTC.
Indicates if the given address is a Minter. Only Minters can request optimistic minting.
List of all Minters.
May be used to establish an order in which the Minters should request for an optimistic minting.
Indicates if the given address is a Guardian. Only Guardians can cancel requested optimistic minting.
Collection of all revealed deposits for which the optimistic minting was requested. Indexed by a deposit key computed as keccak256(fundingTxHash | fundingOutputIndex).
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.
New optimistic minting fee divisor value. Set only when the parameter update process is pending. Once the update gets
The timestamp at which the update of the optimistic minting fee divisor started. Zero if update is not in progress.
New optimistic minting delay value. Set only when the parameter update process is pending. Once the update gets finalized, this
The timestamp at which the update of the optimistic minting delay started. Zero if update is not in progress.
Mints the given amount of TBTC to the given depositor's address. Implemented by TBTCVault.
Allows to fetch a list of all Minters.
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.
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.
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.
Adds the address to the Minter list.
Removes the address from the Minter list.
Adds the address to the Guardian set.
Removes the address from the Guardian set.
Pauses the optimistic minting. Note that the pause of the optimistic minting does not stop the standard minting flow where wallets sweep deposits.
Unpauses the optimistic minting.
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.
Finalizes the update process of the optimistic minting fee.
Begins the process of updating optimistic minting delay.
Finalizes the update process of the optimistic minting delay.
Calculates deposit key the same way as the Bridge contract. The deposit key is computed as keccak256(fundingTxHash | fundingOutputIndex).
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
depositor
address
The depositor whose balance increase is received.
amount
uint256
The balance increase amount for the depositor received.
[0]
uint256
The TBTC amount that should be minted after paying off the optimistic minting debt.
function defeatFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimage, bool witness) externalfunction defeatFraudChallengeWithHeartbeat(struct BridgeState.Storage self, bytes walletPublicKey, bytes heartbeatMessage) externalfunction resolveFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, struct Fraud.FraudChallenge challenge, bytes32 sighash) internalfunction notifyFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) externalfunction extractUtxoKeyFromWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey)function extractUtxoKeyFromNonWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey)function extractSighashType(bytes preimage) internal pure returns (uint32 sighashType)uint256 submitDepositSweepProofGasOffsetuint256 submitRedemptionProofGasOffsetuint256 resetMovingFundsTimeoutGasOffsetuint256 submitMovingFundsProofGasOffsetuint256 notifyMovingFundsBelowDustGasOffsetuint256 submitMovedFundsSweepProofGasOffsetuint256 requestNewWalletGasOffsetuint256 notifyWalletCloseableGasOffsetuint256 notifyWalletClosingPeriodElapsedGasOffsetuint256 defeatFraudChallengeGasOffsetuint256 defeatFraudChallengeWithHeartbeatGasOffsetevent WalletMaintainerAuthorized(address maintainer)event WalletMaintainerUnauthorized(address maintainer)event SpvMaintainerAuthorized(address maintainer)event SpvMaintainerUnauthorized(address maintainer)event BridgeUpdated(address newBridge)event GasOffsetParametersUpdated(uint256 submitDepositSweepProofGasOffset, uint256 submitRedemptionProofGasOffset, uint256 resetMovingFundsTimeoutGasOffset, uint256 submitMovingFundsProofGasOffset, uint256 notifyMovingFundsBelowDustGasOffset, uint256 submitMovedFundsSweepProofGasOffset, uint256 requestNewWalletGasOffset, uint256 notifyWalletCloseableGasOffset, uint256 notifyWalletClosingPeriodElapsedGasOffset, uint256 defeatFraudChallengeGasOffset, uint256 defeatFraudChallengeWithHeartbeatGasOffset)modifier onlyWalletMaintainer()modifier onlySpvMaintainer()modifier onlyReimbursableAdmin()constructor(contract Bridge _bridge, contract ReimbursementPool _reimbursementPool) publicfunction submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) externalfunction submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) externalfunction resetMovingFundsTimeout(bytes20 walletPubKeyHash) externalfunction submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) externalfunction notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) externalfunction submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) externalfunction requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) externalfunction notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) externalfunction notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) externalfunction defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) externalfunction defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) externalfunction authorizeWalletMaintainer(address maintainer) externalfunction authorizeSpvMaintainer(address maintainer) externalfunction unauthorizeWalletMaintainer(address maintainerToUnauthorize) externalfunction unauthorizeSpvMaintainer(address maintainerToUnauthorize) externalfunction updateBridge(contract Bridge _bridge) externalfunction updateGasOffsetParameters(uint256 newSubmitDepositSweepProofGasOffset, uint256 newSubmitRedemptionProofGasOffset, uint256 newResetMovingFundsTimeoutGasOffset, uint256 newSubmitMovingFundsProofGasOffset, uint256 newNotifyMovingFundsBelowDustGasOffset, uint256 newSubmitMovedFundsSweepProofGasOffset, uint256 newRequestNewWalletGasOffset, uint256 newNotifyWalletCloseableGasOffset, uint256 newNotifyWalletClosingPeriodElapsedGasOffset, uint256 newDefeatFraudChallengeGasOffset, uint256 newDefeatFraudChallengeWithHeartbeatGasOffset) externalfunction allWalletMaintainers() external view returns (address[])function allSpvMaintainers() external view returns (address[])struct OptimisticMintingRequest {
uint64 requestedAt;
uint64 finalizedAt;
}uint256 GOVERNANCE_DELAYuint256 SATOSHI_MULTIPLIERcontract Bridge bridgebool isOptimisticMintingPauseduint32 optimisticMintingFeeDivisoruint32 optimisticMintingDelaymapping(address => bool) isMinteraddress[] mintersmapping(address => bool) isGuardianmapping(uint256 => struct TBTCOptimisticMinting.OptimisticMintingRequest) optimisticMintingRequestsmapping(address => uint256) optimisticMintingDebtuint32 newOptimisticMintingFeeDivisoruint256 optimisticMintingFeeUpdateInitiatedTimestampuint32 newOptimisticMintingDelayuint256 optimisticMintingDelayUpdateInitiatedTimestampevent OptimisticMintingRequested(address minter, uint256 depositKey, address depositor, uint256 amount, bytes32 fundingTxHash, uint32 fundingOutputIndex)event OptimisticMintingFinalized(address minter, uint256 depositKey, address depositor, uint256 optimisticMintingDebt)event OptimisticMintingCancelled(address guardian, uint256 depositKey)event OptimisticMintingDebtRepaid(address depositor, uint256 optimisticMintingDebt)event MinterAdded(address minter)event MinterRemoved(address minter)event GuardianAdded(address guardian)event GuardianRemoved(address guardian)event OptimisticMintingPaused()event OptimisticMintingUnpaused()event OptimisticMintingFeeUpdateStarted(uint32 newOptimisticMintingFeeDivisor)event OptimisticMintingFeeUpdated(uint32 newOptimisticMintingFeeDivisor)event OptimisticMintingDelayUpdateStarted(uint32 newOptimisticMintingDelay)event OptimisticMintingDelayUpdated(uint32 newOptimisticMintingDelay)modifier onlyMinter()modifier onlyGuardian()modifier onlyOwnerOrGuardian()modifier whenOptimisticMintingNotPaused()modifier onlyAfterGovernanceDelay(uint256 updateInitiatedTimestamp)constructor(contract Bridge _bridge) internalfunction _mint(address minter, uint256 amount) internal virtualfunction getMinters() external view returns (address[])function requestOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) externalfunction finalizeOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) externalfunction cancelOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) externalfunction addMinter(address minter) externalfunction removeMinter(address minter) externalfunction addGuardian(address guardian) externalfunction removeGuardian(address guardian) externalfunction pauseOptimisticMinting() externalfunction unpauseOptimisticMinting() externalfunction beginOptimisticMintingFeeUpdate(uint32 _newOptimisticMintingFeeDivisor) externalfunction finalizeOptimisticMintingFeeUpdate() externalfunction beginOptimisticMintingDelayUpdate(uint32 _newOptimisticMintingDelay) externalfunction finalizeOptimisticMintingDelayUpdate() externalfunction calculateDepositKey(bytes32 fundingTxHash, uint32 fundingOutputIndex) public pure returns (uint256)function repayOptimisticMintingDebt(address depositor, uint256 amount) internal returns (uint256)TBTC
TBTCVault
VendingMachineV3
WalletRegistry
WalletProposalValidator
RedemptionWatchtower
CoveragePool
Relayer Bot
L1BitcoinDepositor (Arbitrum)
L1BitcoinDepositor (Base)
L1BTCRedeemerProxy
LockReleaseTokenPoolUpgradeable
CCIP Router (BOB)
Bridge
RebateStaking
Timelock Controller
ArbitrumTBTC
ArbitrumWormholeGateway
L2BitcoinDepositor
L2BTCRedeemerProxy
BaseTBTC
BaseWormholeGateway
L2BitcoinDepositor
L2BTCRedeemerProxy
OptimismTBTC
OptimismWormholeGateway
PolygonTBTC
PolygonWormholeGateway
SolanaTBTC (Token)
SolanaTBTC (Program)
SolanaWormholeGateway
StarknetTBTC
L1 StarkGate Bridge
L2 StarkGate Bridge
StarknetBitcoinDepositor
Sui tBTC
L1BitcoinDepositor
Sui Package ID
BOB tBTC
Standard Bridge on BOB
BurnFromMintTokenPoolUpgradeable
CCIP Router
RandomBeacon
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.
self
struct BridgeState.Storage
sweepTx
struct BitcoinTx.Info
Bitcoin sweep transaction data.
sweepProof
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
public key hash of the wallet proving the sweep Bitcoin transaction.
mainUtxo
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.
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).
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.
walletPubKeyHash
bytes20
20-byte wallet public key hash.
value
uint64
8-byte sweep transaction output value.
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.
resultInfo
struct DepositSweep.DepositSweepTxInputsInfo
Outcomes of the processing.
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.
inputVector
bytes
Bitcoin transaction input vector.
inputStartingIndex
uint256
Index the given input starts at.
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
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.
sweepTxInputsTotalValue
uint256
Total value of all sweep transaction inputs.
sweepTxOutputValue
uint256
Value of the sweep transaction output.
depositsCount
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.
struct DepositSweepTxInputsProcessingInfo {
bytes sweepTxInputVector;
struct BitcoinTx.UTXO mainUtxo;
address vault;
}struct DepositSweepTxInputsInfo {
uint256 inputsTotalValue;
address[] depositors;
uint256[] depositedAmounts;
uint256[] treasuryFees;
}event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash)function submitDepositSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) externalfunction resolveDepositSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo)function processDepositSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value)function processDepositSweepTxInputs(struct BridgeState.Storage self, struct DepositSweep.DepositSweepTxInputsProcessingInfo processInfo) internal returns (struct DepositSweep.DepositSweepTxInputsInfo resultInfo)function parseDepositSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength)function depositSweepTxFeeDistribution(uint256 sweepTxInputsTotalValue, uint256 sweepTxOutputValue, uint256 depositsCount) internal pure returns (uint256 depositTxFee, uint256 depositTxFeeRemainder)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.
Indicates if the given address is a minter. Only minters can mint the token.
List of all minters.
Indicates if the given address is a guardian. Only guardians can pause token mints and burns.
List of all guardians.
Initializes the token contract.
_name
string
The name of the token.
_symbol
string
The symbol of the token, usually a shorter version of the name.
Adds the address to the minters list.
Requirements:
The caller must be the contract owner.
minter must not be a minter address already.
minter
address
The address to be added as a minter.
Removes the address from the minters list.
Requirements:
The caller must be the contract owner.
minter must be a minter address.
minter
address
The address to be removed from the minters list.
Adds the address to the guardians list.
Requirements:
The caller must be the contract owner.
guardian must not be a guardian address already.
guardian
address
The address to be added as a guardian.
Removes the address from the guardians list.
Requirements:
The caller must be the contract owner.
guardian must be a guardian address.
guardian
address
The address to be removed from the guardians list.
Allows the governance of the token contract to recover any ERC20 sent mistakenly to the token contract address.
token
contract IERC20Upgradeable
The address of the token to be recovered.
recipient
address
The token recipient address that will receive recovered tokens.
amount
Allows the governance of the token contract to recover any ERC721 sent mistakenly to the token contract address.
token
contract IERC721Upgradeable
The address of the token to be recovered.
recipient
address
The token recipient address that will receive the recovered token.
tokenId
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.
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.
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.
account
address
The address to receive tokens.
amount
uint256
The amount of token to be minted.
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.
amount
uint256
The amount of token to be burned.
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.
account
address
The address owning tokens to be burned.
amount
uint256
The amount of token to be burned.
Allows to fetch a list of all minters.
Allows to fetch a list of all guardians.
mapping(address => bool) isMinteraddress[] mintersmapping(address => bool) isGuardianaddress[] guardiansevent MinterAdded(address minter)event MinterRemoved(address minter)event GuardianAdded(address guardian)event GuardianRemoved(address guardian)modifier onlyMinter()modifier onlyGuardian()function initialize(string _name, string _symbol) externalfunction addMinter(address minter) externalfunction removeMinter(address minter) externalfunction addGuardian(address guardian) externalfunction removeGuardian(address guardian) externalfunction recoverERC20(contract IERC20Upgradeable token, address recipient, uint256 amount) externalfunction recoverERC721(contract IERC721Upgradeable token, address recipient, uint256 tokenId, bytes data) externalfunction pause() externalfunction unpause() externalfunction mint(address account, uint256 amount) externalfunction burn(uint256 amount) publicfunction burnFrom(address account, uint256 amount) publicfunction getMinters() external view returns (address[])function getGuardians() external view returns (address[])docker-compose.yamlCopy the the template below into the file and replace the <Placeholders> with respective details.
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
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
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.
Create the tbtcv2.service file:
cd /etc/systemd/system/
nano tbtcv2.servicePaste 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:
sudo systemctl start tbtcv2There will be no console output because it will be running in the background. Use systemctl to get the status of the service:
sudo systemctl status tbtcv2If the service failed, go back and double check your configuration.
Another option is to see if the Docker container is running:
docker psIf everything is running as intended, enable the service:
systemctl enable tbtcv2Now, with the service running, you should make sure that your configuration will tolerate a reboot and start up again automatically.
reboot nowLog 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.
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.shAnd paste the following:
# 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="<Ethereum API WS URL>"
# copied to home/keep/config earlier
OPERATOR_KEY_FILE_NAME="<Operator Account keyfile name>"
# password set during Operator Account Address creation
OPERATOR_KEY_FILE_PASSWORD="<Operator Account keyfile password>"
# To configure your node with a Public IP, enter it below.
PUBLIC_IP="<PUBLIC_IP_OF_MACHINE>"
# 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:
sudo chmod +x keep.shTo launch the tBTC v2 client, execute:
sudo bash keep.shUnless 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:
Use your specific identification and substitute:
Scroll down about half a page, and you should see the following:
Congratulations, your node is up and running.
docker --version# /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.targetsudo docker pssudo docker logs stinky_brownie >& /path/to/output/file
▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
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 |
-----------------------------------------------------------------------------------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
struct Parameters {
uint256 seedTimeout;
uint256 resultChallengePeriodLength;
uint256 resultChallengeExtraGas;
uint256 resultSubmissionTimeout;
uint256 submitterPrecedencePeriodLength;
}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;
}struct Result {
uint256 submitterMemberIndex;
bytes groupPubKey;
uint8[] misbehavedMembersIndices;
bytes signatures;
uint256[] signingMembersIndices;
uint32[] members;
bytes32 membersHash;
}enum State {
IDLE,
AWAITING_SEED,
AWAITING_RESULT,
CHALLENGE
}uint256 groupSizeSize of a group in ECDSA wallet.
event DkgStarted(uint256 seed)event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct EcdsaDkg.Result result)event DkgTimedOut()event DkgResultApproved(bytes32 resultHash, address approver)event DkgResultChallenged(bytes32 resultHash, address challenger, string reason)event DkgStateLocked()event DkgSeedTimedOut()function init(struct EcdsaDkg.Data self, contract SortitionPool _sortitionPool, contract EcdsaDkgValidator _dkgValidator) internalInitializes SortitionPool and EcdsaDkgValidator addresses. Can be performed only once.
self
struct EcdsaDkg.Data
Determines the current state of group creation. It doesn't take timeouts into consideration. The timeouts should be tracked and notified separately.
Locks the sortition pool and starts awaiting for the group creation seed.
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.
Checks if awaiting seed timed out.
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.
Notifies about the seed was not delivered and restores the initial DKG state (IDLE).
Notifies about DKG timeout.
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.
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.
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.
Checks if DKG result is valid for the current DKG.
Set setSeedTimeout parameter.
Set resultChallengePeriodLength parameter.
Set resultChallengeExtraGas parameter.
Set resultSubmissionTimeout parameter.
Set submitterPrecedencePeriodLength parameter.
Completes DKG by cleaning up state.
Should be called after DKG times out or a result is approved.
This page will show you how to launch a tBTC v2 node on the testnet.
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.
AWS
c5.large
A Keep Node requires a connection to a WebSocket Ethereum API. You should obtain a WS API URL from a service provider (e.g., , , ) or run your own Ethereum node (e.g. ).
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.
To create a new Ethereum account, (GoEthereum) and create a new account using the command below. This account will subsequently be referred to as the Operator Account.
When prompted, provide a password to protect the operator key file.
Once the process completes, your public key will be displayed. Take note of your Operator Account public key.
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.
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 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.
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 .
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.
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.
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.
Assuming for the root user with the command provided in the step, the operator-key file should be located in the ~/operator-key directory.
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
Install or update Docker to the latest version. Visit the for detailed instructions. Use the command below to find your installed version if needed:
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:
And paste the following:
Save and close the file, and make it executable:
To launch the tBTC v2 client, execute:
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:
Use your specific identification and substitute:
Scroll down about half a page, and you should see the following:
Congratulations, your node is up and running.
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.
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.
The timestamp at which an upgrade to a new TBTC vault was initiated. Set only when the upgrade process is pending.
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
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.
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.
uint256
Byte length of the given input.
uint256
Count of the deposits swept by the sweep transaction.
uint256
The amount to be recovered.
uint256
The ID of the ERC721 token to be recovered.
data
bytes
_sortitionPool
contract SortitionPool
Sortition Pool reference
_dkgValidator
contract EcdsaDkgValidator
EcdsaDkgValidator reference
[0]
bool
True if awaiting seed timed out, false otherwise.
[0]
bool
True if DKG timed out, false otherwise.
self
struct EcdsaDkg.Data
result
struct EcdsaDkg.Result
Result to approve. Must match the submitted result stored during submitResult.
misbehavedMembers
uint32[]
Identifiers of members who misbehaved during DKG.
self
struct EcdsaDkg.Data
result
struct EcdsaDkg.Result
Result to challenge. Must match the submitted result stored during submitResult.
maliciousResultHash
bytes32
Hash of the malicious result.
maliciousSubmitter
uint32
Identifier of the malicious submitter.
self
struct EcdsaDkg.Data
result
struct EcdsaDkg.Result
DKG result.
[0]
bool
True if the result is valid. If the result is invalid it returns false and an error message.
[1]
string
Azure
F2s v2
Google Cloud
n2-highcpu-2
Self-hosted
2 vCPU / 2 GB RAM / 1 GiB Persistent Storage
Network
network.port
TCP
3919
Status
clientInfo.port
TCP
9601
function currentState(struct EcdsaDkg.Data self) internal view returns (enum EcdsaDkg.State state)function lockState(struct EcdsaDkg.Data self) internalfunction start(struct EcdsaDkg.Data self, uint256 seed) internalfunction submitResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internalfunction hasSeedTimedOut(struct EcdsaDkg.Data self) internal view returns (bool)function hasDkgTimedOut(struct EcdsaDkg.Data self) internal view returns (bool)function notifySeedTimeout(struct EcdsaDkg.Data self) internalfunction notifyDkgTimeout(struct EcdsaDkg.Data self) internalfunction approveResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (uint32[] misbehavedMembers)function challengeResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter)function requireChallengeExtraGas(struct EcdsaDkg.Data self) internal viewfunction isResultValid(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal view returns (bool, string)function setSeedTimeout(struct EcdsaDkg.Data self, uint256 newSeedTimeout) internalfunction setResultChallengePeriodLength(struct EcdsaDkg.Data self, uint256 newResultChallengePeriodLength) internalfunction setResultChallengeExtraGas(struct EcdsaDkg.Data self, uint256 newResultChallengeExtraGas) internalfunction setResultSubmissionTimeout(struct EcdsaDkg.Data self, uint256 newResultSubmissionTimeout) internalfunction setSubmitterPrecedencePeriodLength(struct EcdsaDkg.Data self, uint256 newSubmitterPrecedencePeriodLength) internalfunction complete(struct EcdsaDkg.Data self) internalgeth account new --keystore ./operator-keycd /home
mkdir keep
cd keep
mkdir storage configcd ~/operator-keyls -la
cp name_of_account_key_file /home/keep/config/name_of_account_key_filedocker --versionnano keep.sh# 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="<Ethereum API WS URL>"
# copied to home/keep/config earlier
OPERATOR_KEY_FILE_NAME="<Operator Account keyfile name>"
# password set during Operator Account Address creation
OPERATOR_KEY_FILE_PASSWORD="<Operator Account keyfile password>"
# To configure your node with a Public IP, enter it below.
PUBLIC_IP="<PUBLIC_IP_OF_MACHINE>"
# 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
sudo chmod +x keep.shsudo bash keep.shsudo docker pssudo docker logs stinky_brownie >& /path/to/output/file
▓▓▌ ▓▓ ▐▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓ ▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓ ▐▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▄▄▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▄▄▄▄ ▓▓▓▓▓▓▄▄▄▄ ▐▓▓▓▓▓▌ ▐▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▀ ▐▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▌ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▀▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓▀▀▀▀ ▓▓▓▓▓▓▀▀▀▀ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
▓▓▓▓▓▓ ▀▓▓▓▓▓▓▄ ▐▓▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓▓ ▓▓▓▓▓ ▐▓▓▓▓▓▌
▓▓▓▓▓▓▓▓▓▓ █▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓ ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓
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 |
-----------------------------------------------------------------------------------amount
uint256
Amount of TBTC to mint.
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.
owner
address
The owner who approved their Bank balance.
satoshis
uint256
Amount of satoshis used to mint TBTC.
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.
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.
amount
uint256
Amount of TBTC to unmint.
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.
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.
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.
from
address
TBTC token holder executing unminting.
amount
uint256
Amount of TBTC to unmint.
token
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.
_newVault
address
The new vault address.
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.
Allows the governance of the TBTCVault to recover any ERC20 token sent mistakenly to the TBTC token contract address.
token
contract IERC20
Address of the recovered ERC20 token contract.
recipient
address
Address the recovered token should be sent to.
amount
Allows the governance of the TBTCVault to recover any ERC721 token sent mistakenly to the TBTC token contract address.
token
contract IERC721
Address of the recovered ERC721 token contract.
recipient
address
Address the recovered token should be sent to.
tokenId
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.
token
contract IERC20
Address of the recovered ERC20 token contract.
recipient
address
Address the recovered token should be sent to.
amount
Allows the governance of the TBTCVault to recover any ERC721 token sent mistakenly to the vault address.
token
contract IERC721
Address of the recovered ERC721 token contract.
recipient
address
Address the recovered token should be sent to.
tokenId
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.
convertibleAmount
uint256
Amount of TBTC to be minted/unminted.
remainder
uint256
Not convertible remainder if amount is not divisible by SATOSHI_MULTIPLIER.
satoshis
Mints the given amount of TBTC to the given depositor's address. Implemented by TBTCVault.
amount MUST be divisible by SATOSHI_MULTIPLIER with no change.
amount MUST be divisible by SATOSHI_MULTIPLIER with no change.
contract Bank bankcontract TBTC tbtcTokenaddress newVaultuint256 upgradeInitiatedTimestampevent Minted(address to, uint256 amount)event Unminted(address from, uint256 amount)event UpgradeInitiated(address newVault, uint256 timestamp)event UpgradeFinalized(address newVault)modifier onlyBank()constructor(contract Bank _bank, contract TBTC _tbtcToken, contract Bridge _bridge) publicfunction mint(uint256 amount) externalfunction receiveBalanceApproval(address owner, uint256 satoshis, bytes) externalfunction receiveBalanceIncrease(address[] depositors, uint256[] depositedSatoshiAmounts) externalfunction unmint(uint256 amount) externalfunction unmintAndRedeem(uint256 amount, bytes redemptionData) externalfunction receiveApproval(address from, uint256 amount, address token, bytes extraData) externalfunction initiateUpgrade(address _newVault) externalfunction finalizeUpgrade() externalfunction recoverERC20FromToken(contract IERC20 token, address recipient, uint256 amount) externalfunction recoverERC721FromToken(contract IERC721 token, address recipient, uint256 tokenId, bytes data) externalfunction recoverERC20(contract IERC20 token, address recipient, uint256 amount) externalfunction recoverERC721(contract IERC721 token, address recipient, uint256 tokenId, bytes data) externalfunction amountToSatoshis(uint256 amount) public view returns (uint256 convertibleAmount, uint256 remainder, uint256 satoshis)function _mint(address minter, uint256 amount) internalfunction _unmint(address unminter, uint256 amount) internalfunction _unmintAndRedeem(address redeemer, uint256 amount, bytes redemptionData) internalstruct 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;
}event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod)event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier)event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier)event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod)event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier)event TreasuryUpdated(address treasury)function updateDepositParameters(struct BridgeState.Storage self, uint64 _depositDustThreshold, uint64 _depositTreasuryFeeDivisor, uint64 _depositTxMaxFee, uint32 _depositRevealAheadPeriod) internalof 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.
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,
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,
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.
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].
Updates treasury address. The treasury receives the system fees.
The treasury address must not be 0x0.
Allows to reference Bitcoin raw transaction in Solidity.
See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format
Raw Bitcoin transaction data:
Extract the timestamp of the header at the given position.
Assumes that the specified position contains a valid header. Performs no validation whatsoever.
bytes
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.
uint256
Recovered amount.
uint256
Identifier of the recovered token.
data
bytes
Additional data.
uint256
Recovered amount.
uint256
Identifier of the recovered token.
data
bytes
Additional data.
uint256
Amount in satoshis - the Bank balance to be transferred for the given mint/unmint
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.
Redemption timeout must be greater than zero,
Redemption timeout notifier reward multiplier must be in the range [0, 100].
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].
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].
_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].
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].
self
struct BridgeState.Storage
_depositDustThreshold
uint64
_depositTreasuryFeeDivisor
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.
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.
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
self
struct BridgeState.Storage
_treasury
address
New value of the treasury address.
uint64
_redemptionTreasuryFeeDivisor
uint32
function updateRedemptionParameters(struct BridgeState.Storage self, uint64 _redemptionDustThreshold, uint64 _redemptionTreasuryFeeDivisor, uint64 _redemptionTxMaxFee, uint64 _redemptionTxMaxTotalFee, uint32 _redemptionTimeout, uint96 _redemptionTimeoutSlashingAmount, uint32 _redemptionTimeoutNotifierRewardMultiplier) internalfunction 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) internalfunction updateWalletParameters(struct BridgeState.Storage self, uint32 _walletCreationPeriod, uint64 _walletCreationMinBtcBalance, uint64 _walletCreationMaxBtcBalance, uint64 _walletClosureMinBtcBalance, uint32 _walletMaxAge, uint64 _walletMaxBtcTransfer, uint32 _walletClosingPeriod) internalfunction updateFraudParameters(struct BridgeState.Storage self, uint96 _fraudChallengeDepositAmount, uint32 _fraudChallengeDefeatTimeout, uint96 _fraudSlashingAmount, uint32 _fraudNotifierRewardMultiplier) internalfunction updateTreasury(struct BridgeState.Storage self, address _treasury) internalversion
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):
36
previous_output
outpoint
The previous outpoint being spent
varies
script_bytes
The reference to transaction being spent (outpoint):
32
hash
char[32]
Hash of the transaction to spend
4
index
uint32_t (LE)
Transaction output (txOut):
8
value
int64_t (LE)
Number of satoshis to spend
1+
pk_script_bytes
compactSize uint (LE)
compactSize uint format:
>= 0 && <= 252
1
uint8_t
>= 253 && <= 0xffff
3
0xfd followed by the number as uint16_t (LE)
>= 0x10000 && <= 0xffffffff
(*) compactSize uint is often references as VarInt)
Coinbase transaction input (txIn):
32
hash
char[32]
A 32-byte 0x0 null (no previous_outpoint)
4
index
(*) 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.
Validates the SPV proof of the Bitcoin transaction. Reverts in case the validation or proof verification fail.
self
struct BridgeState.Storage
txInfo
struct BitcoinTx.Info
Bitcoin transaction data.
proof
txHash
bytes32
Proven 32-byte transaction hash.
Evaluates the given Bitcoin proof difficulty against the actual Bitcoin chain difficulty provided by the relay oracle. Reverts in case the evaluation fails.
self
struct BridgeState.Storage
bitcoinHeaders
bytes
Bitcoin headers chain being part of the SPV proof. Used to extract the observed proof difficulty.
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.
struct BridgeState.Storage
output
bytes
The transaction output.
pubKeyHash
bytes20
20-byte public key hash the output locks funds on.
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 https://en.bitcoin.it/wiki/Script#Opcodes 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: https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash
pubKeyHash
bytes20
The 20-byte public key hash.
[0]
bytes26
The P2PKH script.
Build the P2WPKH script from the given public key hash.
The P2WPKH script has the following format: <0x160014> <20-byte PKH>. According to https://en.bitcoin.it/wiki/Script#Opcodes 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: https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH
pubKeyHash
bytes20
The 20-byte public key hash.
[0]
bytes23
The P2WPKH script.
4
struct Info {
bytes4 version;
bytes inputVector;
bytes outputVector;
bytes4 locktime;
}struct Proof {
bytes merkleProof;
uint256 txIndexInBlock;
bytes bitcoinHeaders;
}struct UTXO {
bytes32 txHash;
uint32 txOutputIndex;
uint64 txOutputValue;
}struct RSVSignature {
bytes32 r;
bytes32 s;
uint8 v;
}function validateProof(struct BridgeState.Storage self, struct BitcoinTx.Info txInfo, struct BitcoinTx.Proof proof) internal view returns (bytes32 txHash)function evaluateProofDifficulty(struct BridgeState.Storage self, bytes bitcoinHeaders) internal viewfunction extractPubKeyHash(struct BridgeState.Storage, bytes output) internal pure returns (bytes20 pubKeyHash)function makeP2PKHScript(bytes20 pubKeyHash) internal pure returns (bytes26)function makeP2WPKHScript(bytes20 pubKeyHash) internal pure returns (bytes23)at
uint256
The start of the header in the array.
[0]
uint32
The timestamp of the header.
THE RELAY MUST NOT BE USED BEFORE GENESIS AND AT LEAST ONE RETARGET.
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.
genesisHeader
bytes
The first block header of the genesis epoch.
genesisHeight
uint256
The block number of the first block of the epoch.
genesisProofLength
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.
newLength
uint64
The required number of blocks. Must be less than 2016.
Set whether the relay requires retarget submitters to be pre-authorised by governance.
status
bool
True if authorisation is to be required, false if not.
Authorise the given address to submit retarget proofs.
submitter
address
The address to be authorised.
Rescind the authorisation of the submitter to retarget.
submitter
address
The address to be deauthorised.
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.
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.
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.
headers
bytes
A chain of 2 to 2015 bitcoin headers.
startingHeaderTimestamp
uint256
The timestamp of the first header.
headerCount
uint256
The number of headers.
Get the difficulty of the specified block.
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).
[0]
uint256
The difficulty of the epoch.
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.
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.
Returns the difficulty of the current epoch.
returns 0 if the relay is not ready.
[0]
uint256
The difficulty of the current epoch.
Returns the difficulty of the previous epoch.
Returns 0 if the relay is not ready or has not had a retarget.
[0]
uint256
The difficulty of the previous epoch.
Get the difficulty of the specified epoch.
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.
[0]
uint256
The difficulty of the epoch.
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.
headers
bytes
The byte array containing the header of interest.
start
uint256
The start of the header in the array.
prevDigest
digest
bytes32
The digest of the current header.
target
uint256
The PoW target of the header.
struct Epoch {
uint32 timestamp;
uint224 target;
}event Genesis(uint256 blockHeight)event Retarget(uint256 oldDifficulty, uint256 newDifficulty)event ProofLengthChanged(uint256 newLength)event AuthorizationRequirementChanged(bool newStatus)event SubmitterAuthorized(address submitter)event SubmitterDeauthorized(address submitter)function retarget(bytes headers) externalfunction validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount)function getBlockDifficulty(uint256 blockNumber) external view returns (uint256)function getEpochDifficulty(uint256 epochNumber) external view returns (uint256)function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd)function extractTimestampAt(bytes headers, uint256 at) internal pure returns (uint32)headers
bytes
Byte array containing the header of interest.
bool readybool authorizationRequireduint64 proofLengthuint64 genesisEpochuint64 currentEpochuint256 currentEpochDifficultyuint256 prevEpochDifficultymapping(uint256 => struct Epoch) epochsmapping(address => bool) isAuthorizedmodifier relayActive()function genesis(bytes genesisHeader, uint256 genesisHeight, uint64 genesisProofLength) externalfunction setProofLength(uint64 newLength) externalfunction setAuthorizationStatus(bool status) externalfunction authorize(address submitter) externalfunction deauthorize(address submitter) externalfunction retarget(bytes headers) externalfunction validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount)function getBlockDifficulty(uint256 blockNumber) external view returns (uint256)function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd)function getCurrentEpochDifficulty() external view virtual returns (uint256)function getPrevEpochDifficulty() external view virtual returns (uint256)function getCurrentAndPrevEpochDifficulty() external view returns (uint256 current, uint256 previous)function getEpochDifficulty(uint256 epochNumber) public view returns (uint256)function validateHeader(bytes headers, uint256 start, bytes32 prevDigest) internal view returns (bytes32 digest, uint256 target)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.
address bridgemapping(address => uint256) balanceOfThe balance of the given account in the Bank. Zero by default.
mapping(address => mapping(address => uint256)) allowanceThe remaining amount of balance a spender will be allowed to transfer on behalf of an owner using transferBalanceFrom. Zero by default.
mapping(address => uint256) noncesReturns 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.
uint256 cachedChainIdbytes32 cachedDomainSeparatorbytes32 PERMIT_TYPEHASHReturns an EIP2612 Permit message hash. Used to construct an EIP2612 signature provided to the permit function.
event BalanceTransferred(address from, address to, uint256 amount)event BalanceApproved(address owner, address spender, uint256 amount)event BalanceIncreased(address owner, uint256 amount)event BalanceDecreased(address owner, uint256 amount)event BridgeUpdated(address newBridge)modifier onlyBridge()constructor() publicfunction updateBridge(address _bridge) externalAllows 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.
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.
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.
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.
Atomically increases the caller's balance allowance granted to spender by the given addedValue.
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.
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
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 amountis set totype(uint256).maxthentransferBalanceFromwill 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 useincreaseBalanceAllowanceanddecreaseBalanceAllowance` to eliminate the risk.
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.
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.
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.
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.
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.
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
Index of the specific output from the TX
Number of bytes in the pubkey script
varies
pk_script
char[]
Pubkey script
5
0xfe followed by the number as uint32_t (LE)
>= 0x100000000 && <= 0xffffffffffffffff
9
0xff followed by the number as uint64_t (LE)
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
struct BitcoinTx.Proof
Bitcoin proof data.
uint64
The number of blocks required to accept a proof.
bytes32
The digest of the previous header (optional; providing zeros for the digest skips the check).
_bridge
address
The new Bridge address.
function transferBalance(address recipient, uint256 amount) externalrecipient
address
The recipient of the balance.
amount
uint256
The amount of the balance transferred.
function approveBalance(address spender, uint256 amount) externalspender
address
The address that will be allowed to spend the balance.
amount
uint256
The amount the spender is allowed to spend.
function approveBalanceAndCall(address spender, uint256 amount, bytes extraData) externalspender
address
The smart contract that will be allowed to spend the balance.
amount
uint256
The amount the spender contract is allowed to spend.
extraData
function increaseBalanceAllowance(address spender, uint256 addedValue) externalspender
address
The spender address for which the allowance is increased.
addedValue
uint256
The amount by which the allowance is increased.
function decreaseBalanceAllowance(address spender, uint256 subtractedValue) externalspender
address
The spender address for which the allowance is decreased.
subtractedValue
uint256
The amount by which the allowance is decreased.
function transferBalanceFrom(address spender, address recipient, uint256 amount) externalspender
address
The address from which the balance is transferred.
recipient
address
The address to which the balance is transferred.
amount
function permit(address owner, address spender, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) externalowner
address
The balance owner who signed the permission.
spender
address
The address that will be allowed to spend the balance.
function increaseBalances(address[] recipients, uint256[] amounts) externalrecipients
address[]
Balance increase recipients.
amounts
uint256[]
Amounts by which balances are increased.
function increaseBalance(address recipient, uint256 amount) externalrecipient
address
Balance increase recipient.
amount
uint256
Amount by which the balance is increased.
function increaseBalanceAndCall(address vault, address[] recipients, uint256[] amounts) externalvault
address
Address of IVault recipient contract.
recipients
address[]
Balance increase recipients.
amounts
function decreaseBalance(uint256 amount) externalamount
uint256
The amount by which the balance is decreased.
function DOMAIN_SEPARATOR() public view returns (bytes32)function _increaseBalance(address recipient, uint256 amount) internalbytes
Extra data passed to the spender contract via receiveBalanceApproval call.
uint256
The amount of balance that is transferred.
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.
uint256[]
Amounts by which balances are increased.
This page describes a technical diagram for v1 of the Verifiable Bitcoin Account, also called Milestone 1 ("M1"). A second version (v2) is planned to ship later.
In M1, a Verifiable Bitcoin Account (VBA) is a UTXO reservation in the tBTC v2 Bridge. When bitcoin is deposited into a tBTC threshold wallet and revealed to the Bridge, with the reservation vault named as its vault, it is never combined with other deposits: it retains its own UTXO (the "anchor"), held by the same wallet that custodies pooled tBTC. tBTC is minted against that anchor, one position at a time. The engineering name is a "reservation"; this page uses both.
Every move of an anchor is a Bitcoin transaction with exactly one input and one output, proven to Ethereum with the Bridge's standard SPV checks. Custody security is the same as tBTC's: an honest majority of the threshold signers, with fraud challenges and stake slashing. The sections below show where each rule lives, how a position moves through its lifecycle, and how to verify any of it yourself.
POOLED DEPOSIT RESERVED DEPOSIT
+----------------+ +----------------+
| deposits 1..n | | deposit |
+-------+--------+ +-------+--------+
| sweep | reveal
v v
+----------------+ +----------------+
| shared main | | reserved |
| UTXO (pooled) | | deposit |
+----------------+ +-------+--------+
| acceptance
| proves anchor
v
+----------------+
| anchor UTXO |
| (own output, |
| P2WPKH wallet)|
+----------------+
** Both sit under the same tBTC threshold wallet key
** A reserved deposit is excluded from every sweepWhat stays the same as ordinary tBTC:
The deposit and reveal flow is identical; a reserved deposit just names the reservation vault at reveal.
Custody is the same threshold wallet and signing quorum as pooled tBTC (51 of 100 seats on mainnet).
The tBTC you receive is ordinary tBTC: freely transferable.
Fraud protection is identical: proven spends are honest, others stay challengeable, and a failed challenge terminates the wallet and slashes operators.
What is different:
Bitcoin is never swept into the wallet's main UTXO; the Bridge and signers reject any sweep that includes a reserved deposit. The flag is permanent.
Your position has its own traceable lineage: deposit UTXO, then anchor, then each re-anchor, each a one-input/one-output transaction.
tBTC is minted against your anchor by the vault, which keeps an initiation fee in reserve to fund future re-anchor miner fees.
Both shapes are enforced at proof time by the Bridge: exactly one input, exactly one output, the output paying the authorized wallet's key, fee within the snapshotted maximum, and the value floor for that transaction type; the minimum-plus-max-fee floor for re-anchors is checked when the re-anchor is requested. The signer software builds P2WPKH outputs. A Bitcoin node can verify that the signature belongs to the wallet's key, but it cannot verify anything further: the one-input/one-output shape and the value rules are Ethereum checks applied to the proven transaction.
Who pays each fee: the anchoring miner fee is paid by the owner (the anchor is the deposit minus the fee, and tBTC is minted on the anchor). The initiation fee is taken from the minted amount and kept by the vault. Re-anchor miner fees are paid from the vault's fee reserve: the vault burns tBTC in step with each bitcoin fee, so the total tBTC supply falls as bitcoin is spent.
Public fee debt: if the reserve is short, the unpaid part is recorded as public debt. While the debt is non-zero, tBTC supply exceeds backing by exactly that amount. Anyone can repay it, by burning their own tBTC. The vault owner's fee sweep repays the debt first, and can only send what is above the reserve target.
No normal deposit treasury fee applies to reserved deposits.
There is no lifetime cap on re-anchor fees in M1 (one is planned for v2). Each move's fee is capped by the snapshotted maximum, and a re-anchor can only be requested while the anchor exceeds the minimum plus one max fee, so re-anchor fees can never take a position below the minimum.
The M1 reservation timeouts - acceptance and re-anchor - do not slash anyone; no stake is seized by either. Wallet-level timeouts are different and still apply: a retiring wallet that fails to move its funds in time is slashed and terminated, which is standard tBTC wallet machinery, separate from the reservation rules.
All values below are set by the Threshold Council through Bridge governance: begin, governance delay, finalize. Vault fee settings change instantly, within the contract's hard cap.
Enforced relations: max fee > 0; minimum > max fee; term 90-730 days; renewal window > 0 and < term; action timeout > 2 hours; per-wallet count > 0; total cap <= max open positions x single cap (when both set); vault address can only change when no reservation is open and no reserved deposit is pending.
Launch posture: M1 launches with a small total cap, limited to design partners, with maxReservationsPerWallet set to 1 and a planned custody term of 12 months. Quotable code defaults: initiation fee 0.40% at deploy, hard-capped at 5%; minimum deposit age 2 hours; refund safety margin 24 hours; term range 90-730 days; signers wait 6 Bitcoin confirmations before proposing. The other values above are governance-set.
Net trust model: M1 keeps tBTC v2's custody model. What it adds is segregation and a traceable, proven lineage for each deposit. There is no depositor-held key and no Bitcoin Script recovery path after acceptance.
No in-kind redemption yet. In M1, the owner holds, transfers, or uses tBTC, or redeems through standard (pooled) tBTC redemption, which pays from pooled wallet funds, not the anchor.
No owner-initiated way to close a position in M1: no redemption, renewal or dissolution. It stays open until v2 or until its wallet dies (Stranded).
The term is recorded, not enforced. Expiry and dissolution dates exist so v2 can honor the term; in M1, their only effect is the stranding gate on Closing wallets.
Stranding: if the custodying wallet is terminated, the in-kind option is lost; the tBTC balance remains unchanged; no compensation is available. If that wallet's bitcoin is really lost, the shortfall affects tBTC backing as a whole.
Everything above is public state; no special tooling is required.
Compute the reservation key: the standard tBTC deposit key - keccak256 of the funding transaction hash and output index, as the Bridge uses for every deposit.
Read the Bridge address: reservations(key) gives owner, wallet, anchor, amounts, state, and dates; reservationActions(key, nonce) for pending actions; reservationParameters() for operational parameters; reservationCaps() for the per-wallet amount, single-position, and max-open-positions caps; activeReservationsCount() for current open count; walletReservationsCount(hash)
File the permissionless housekeeping calls: action timeouts, stale deposits, stranding
Grant, block or speed anything up; all such calls are open to anyone
Threshold Council (Bridge governance and vault owner)
Sets parameters and caps with a governance delay; changes the vault's initiation fee (hard-capped at 5%) and fee reserve target instantly; requests re-anchors off healthy Live wallets
Change values in ways the Bridge rejects; move a position without a signed, proven transaction
Anyone
Repay the vault's public fee debt; request re-anchors from retiring wallets; file housekeeping notifications
Request acceptance for someone else's deposit; re-anchor a position off a Live wallet (governance only); send a position anywhere except another Live tBTC wallet
Bridge
At proof time the Bridge verifies the SPV proof and checks the Bitcoin transaction: exactly one input, exactly one output paying the wallet's key, fee within the snapshotted maximum, amount within the rules.
Claim equals anchor
Bridge
The Bridge writes the minted claim and the anchor amount together, at acceptance and at every re-anchor; the two are never changed separately.
Signers only sign authorized moves
Signer nodes (off-chain)
Every signer re-checks the on-chain authorization before signing a reservation transaction; unauthorized proposals are hard-rejected.
Unauthorized signatures are punished
Ethereum (fraud challenges)
Proven anchor and re-anchor spends are recorded as honest; any other signature over an anchor remains challengeable, and a wallet that cannot defeat a challenge is terminated and its operators' stake slashed.
Anyone files the stranding
Capacity released, position Stranded. Owner's tBTC unchanged; no compensation.
Proof arrives late or after wallet stopped
SPV maintainer submits it
Timed-out acceptance provable within deadline plus term; re-anchor provable anytime; wallet already Closing/Closed/Terminated means stranded.
The custodying wallet's signers stop responding
No one can move the anchor without them
Positions stay where they are and the owner's tBTC is unaffected. If the wallet then misses a protocol deadline (for example while moving its funds) it is slashed and terminated, and its positions can be stranded. There is no owner-held key to recover the bitcoin independently.
reservationRenewalWindowSeconds
Renewal window; a v2 feature, must still be set.
reservationMaxTotalAmount
Global cap on the satoshi locked under active reservations; 0 turns the cap off.
maxReservationsPerWallet
How many open reservations one wallet may custody; must be greater than 0 (1 at launch).
maxReservationsAmountPerWallet
Cap on the satoshi one wallet may custody across its reservations; 0 turns it off.
reservationMaxSingleAmount
Cap on a single position; 0 turns it off.
maxActiveReservations
Global cap on open positions; must be greater than 0.
Deposit before acceptance
Nothing extra
The standard tBTC deposit refund path on Bitcoin after the refund locktime
Proof delivery
Authorized SPV maintainers, and the Bridge's Bitcoin relay being kept up to date
Liveness only: maintainers cannot forge a proof
Moving positions off retiring wallets
tBTC signer software doing its duties; free slots on Live wallets
Permissionless requests, caps, timeouts
Housekeeping (timeouts, stale deposits, stranding)
Anyone
Permissionless calls, automated by signer software
Caps and parameters
The Threshold Council
Bridge governance with delay; snapshots protect in-flight actions
Vault fees
The Threshold Council as vault owner
Instant changes, contract cap of 5%
Moving positions depends on the network: re-anchor needs a free slot on another Live wallet and working signer software; off a healthy Live wallet, only governance can move a position.
Re-anchor fees shrink the anchor, not the owner's tBTC; covered by the vault's fee reserve, with shortfalls becoming public repayable debt. No lifetime fee cap in M1; positions at or below minimum plus one max fee can never be re-anchored. Size deposits well above the minimum.
Capacity is checked at acceptance request, not when bitcoin is sent. Check free slots and caps first; unaccepted deposits are refunded in Bitcoin after their locktime.
Launch is limited to design partners and small caps, with one reservation per wallet.
Fees and parameters are set by the Threshold Council. Vault changes are instant (capped at 5%); Bridge changes are subject to the governance delay and never affect in-flight actions or recorded dates.
walletReservationsAmount(hash)pendingReservedDeposits()reservedDepositWallet(key)reservationByAnchorUtxo(txHash, 0)Check the anchor output on any Bitcoin node or explorer: it must pay the custodying wallet's key at the recorded amount.
Follow the events: ReservationAcceptanceRequested, ReservationAccepted, ReservationReanchorRequested, ReservationReanchored, ReservationAcceptanceTimedOut, ReservationReanchorTimedOut, ReservationLateSettled, ReservationStranded, ReservedDepositMarkedStale.
Read the vault: initiationFeeBps, feeReserveTarget, and inKindFeeDebtSat (the outstanding public fee debt).
Term renewal: extend the custody term of a position.
Dissolution: after the term and a delay, release a position so its wallet is no longer tied to it; the owner keeps their tBTC as an ordinary claim.
A lifetime limit on how much re-anchor fees can shrink one position.
M1 positions carry over to v2 with the dates recorded at acceptance.
Owner (depositor)
Sends and reveals the deposit; requests acceptance; receives the tBTC
Move, redeem or close the position in M1; spend the anchor
tBTC threshold wallet and its signer nodes
Custodies the anchor; proposes and signs anchor and re-anchor transactions
Include a reserved deposit in any sweep; sign a transaction outside a pending Bridge authorization (a fraud challenge punishes it)
SPV maintainers
Prove confirmed anchor and re-anchor transactions to the Bridge
Forge a proof or change what a proof settles; only authorized maintainers can submit proofs
Only the wallet's key can spend an anchor
Bitcoin
The anchor is a P2WPKH (native SegWit) output of the tBTC wallet; Bitcoin checks the wallet's signature and nothing else. A reserved deposit's refund locktime also protects the pre-acceptance path: an unaccepted deposit always becomes refundable on Bitcoin.
Every move is authorized in advance
Bridge (Ethereum)
Each move starts as a pending authorization (Acceptance or Reanchor) with a deadline and snapshots of the parameters that matter. No transaction settles without its authorization.
Caps hold
Bridge
Single-reservation, per-wallet count, per-wallet amount, global count and global amount caps are all checked when an action is requested, and capacity is reserved until settlement.
Acceptance not signed in time
Anyone files the timeout; the depositor can request again
Capacity released; new request with fresh nonce while refund window open; no slashing.
Re-anchor not completed in time
Anyone files the action timeout
Target slot released; position back to Active on same source; cooldown on next non-governance request; no slashing.
Deposit never accepted
Anyone marks it stale after refund deadline; governance can force it earlier
Pending record cleared; bitcoin refunded via the deposit script refund path on Bitcoin.
reservationMinAmount
Minimum anchor size, in satoshi. A deposit must be at least this plus the max fee, and a re-anchor can only be requested while the anchor exceeds this plus the max fee.
reservationTxMaxFee
Maximum miner fee for one anchor or re-anchor transaction.
reservationTermSeconds
The custody term of a position; the contract accepts between 90 and 730 days.
reservationDissolutionDelay
Delay after the term before dissolution can happen; a v2 feature, recorded in M1; in M1 it also sets when a position left on a Closing wallet can be stranded.
reservationActionTimeout
Bitcoin custody of the anchor
An honest majority of the custodying wallet's signers (51 of 100 seats on mainnet), the same as pooled tBTC
Threshold ECDSA; fraud challenges and stake slashing
Correct reservation records and minting
Bitcoin and Ethereum consensus only
The Bridge checks the SPV proof and the exact transaction shape before any state change
Segregation from pooled funds
Nothing extra
The Bridge rejects sweeps containing reserved deposits; signers refuse them too
Watchers (signer software)
Exact transaction shape
Custodying wallet terminated
How long a requested action has before it times out.
PEOPLE
+------------------------+ +----------------------------------------------+
| Owner (depositor) | | Threshold Council |
+------------------------+ +----------------------------------------------+
| | |
| reveal deposit, | parameters, caps | fee settings
| request acceptance | (governance delay) | (instant)
v v v
ETHEREUM
+--------------------------------------+ +-----------------------------+
| tBTC v2 Bridge with reservation code | | ReservationVault mints tBTC |
| records positions, authorizes every | credit | and pays the owner, minus |
| move, checks caps and Bitcoin proofs | -----> | the initiation fee; its fee |
| keeps the claim equal to the anchor | | reserve pays re-anchor |
| | | miner fees |
+--------------------------------------+ +-----------------------------+
^ ^ ^
| check | prove | notify: timeouts,
| authorization | Bitcoin txs | stale deposits, stranding
| | |
OFF-CHAIN (signer operators)
+-------------+ +--------------+ +------------+
| tBTC signer | | SPV | | watchers |
| nodes | | maintainers | | |
+-------------+ +--------------+ +------------+
|
| sign anchor and re-anchor transactions
v
BITCOIN
deposit UTXO --> anchor UTXO --> next anchor UTXO (1 in, 1 out each) ANCHOR TRANSACTION (acceptance)
+-------------------------------------+
| input 0: the reserved deposit UTXO |
| output 0: P2WPKH, the wallet's key |
+-------------------------------------+
value rules (proof-time):
deposit - output <= max fee
output >= minimum amount
RE-ANCHOR TRANSACTION
+-------------------------------------+
| input 0: the current anchor |
| output 0: P2WPKH, the target wallet |
+-------------------------------------+
value rules (proof-time):
anchor - output <= max fee
output > max fee (dust floor)
(the request itself required: anchor > minimum + max fee)
LINEAGE:
deposit UTXO -> anchor on wallet A -> anchor on wallet B -> ...
every transaction spends exactly the output created by the previous
one, so any Bitcoin node or explorer can re-walk the whole chain
from the original deposit. ILLUSTRATIVE NUMBERS (not the deployed parameters)
deposit 10.0000000 BTC
|
| anchoring miner fee 0.0001 BTC, paid by the owner
v
anchor 9.9999000 BTC
|
| tBTC minted 1:1 against the anchor
v
tBTC minted 9.9999000 tBTC
|
| initiation fee 0.40% = 0.0399996 tBTC, kept in the vault reserve
v
owner receives 9.9599004 tBTC
later re-anchor, miner fee 0.0001 BTC:
anchor 9.9999 -> 9.9998 BTC; the vault burns 0.0001 tBTC from its
reserve; the owner's 9.9599004 tBTC is untouched. RESERVED DEPOSIT (before a position exists)
+---------+ acceptance proof settles +--------------------------+
| Pending | -------------------------> | Accepted: now a position |
+---------+ +--------------------------+
|
| refund deadline passed, no acceptance pending: anyone
| marks it stale (governance may force it earlier)
v
+---------+
| Stale | refund on Bitcoin; can never be accepted or swept
+---------+
RESERVATION POSITION
+---------+
| Unknown | no position yet; a pending acceptance
+---------+ lives only in its action record
|
| acceptance proof settles
v
+---------+ re-anchor requested +---------------+
| Active | ----------------------> | ActionPending |
| | <---------------------- | |
+---------+ re-anchor proven (now +---------------+
| on the target wallet)
| or timed out (still on
| the source wallet)
|
| custodying wallet Terminated or Closed,
| or Closing past the dissolution date
v
+----------+
| Stranded |
+----------+
A late proof of an already-signed re-anchor can restore a Stranded
position onto the new wallet. Closed is v2 only (in-kind redemption
or dissolution); it is unreachable in M1.
ACTION STATES (one per request): Pending, then Settled, or TimedOut
(a late proof can still settle it), or Superseded (an older request's
late proof used the anchor first). Vetoed is v2 only. M1 action
types: Acceptance and Reanchor.Library responsible for handling integration between Bridge contract and ECDSA wallets.
enum WalletState {
Unknown,
Live,
MovingFunds,
Closing,
Closed,
Terminated
}struct Wallet {
bytes32 ecdsaWalletID;
bytes32 mainUtxoHash;
uint64 pendingRedemptionsValue;
uint32 createdAt;
uint32 movingFundsRequestedAt;
uint32 closingStartedAt;
uint32 pendingMovedFundsSweepRequestsCount;
enum Wallets.WalletState state;
bytes32 movingFundsTargetWalletsCommitmentHash;
}event NewWalletRequested()event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)function requestNewWallet(struct BridgeState.Storage self, struct BitcoinTx.UTXO activeWalletMainUtxo) externalRequests 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Begins the closing period of the given wallet.
Requirements:
The caller must make sure that the wallet is in the MovingFunds state.
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.
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.
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.
self
struct BridgeState.Storage
activeWalletMainUtxo
struct BitcoinTx.UTXO
Data of the active wallet's main UTXO, as currently known on the Ethereum chain.
function registerNewWallet(struct BridgeState.Storage self, bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) externalself
struct BridgeState.Storage
ecdsaWalletID
bytes32
Wallet's unique identifier.
publicKeyX
function notifyWalletRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMembersIDs
function notifyWalletHeartbeatFailed(struct BridgeState.Storage self, bytes32 publicKeyX, bytes32 publicKeyY) externalself
struct BridgeState.Storage
publicKeyX
bytes32
Wallet's public key's X coordinate.
publicKeyY
function notifyWalletCloseable(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) externalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMainUtxo
function notifyWalletClosingPeriodElapsed(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function notifyWalletFundsMoved(struct BridgeState.Storage self, bytes20 walletPubKeyHash, bytes32 targetWalletsHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
targetWalletsHash
function notifyWalletMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function notifyWalletMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMembersIDs
function notifyWalletMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet which was supposed to sweep funds.
walletMembersIDs
function notifyWalletFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, address challenger) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet which was supposed to sweep funds.
walletMembersIDs
function moveFunds(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function beginWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function finalizeWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function terminateWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internalself
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function getWalletBtcBalance(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) internal view returns (uint64 walletBtcBalance)self
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMainUtxo
walletBtcBalance
uint64
Current BTC balance for the given wallet.
bytes32
Wallet's public key's X coordinate.
publicKeyY
bytes32
Wallet's public key's Y coordinate.
uint32[]
Identifiers of the wallet signing group members.
bytes32
Wallet's public key's Y coordinate.
struct BitcoinTx.UTXO
Data of the wallet's main UTXO, as currently known on the Ethereum chain.
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.
uint32[]
Identifiers of the wallet signing group members.
uint32[]
Identifiers of the wallet signing group members.
uint32[]
Identifiers of the wallet signing group members.
challenger
address
Address of the party which submitted the fraud challenge.
struct BitcoinTx.UTXO
Data of the wallet's main UTXO, as currently known on the Ethereum chain.
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.
enum WalletAction {
Idle,
Heartbeat,
DepositSweep,
Redemption,
MovingFunds,
MovedFundsSweep
}struct WalletLock {
uint32 expiresAt;
enum WalletCoordinator.WalletAction cause;
}struct DepositSweepProposal {
bytes20 walletPubKeyHash;
struct WalletCoordinator.DepositKey[] depositsKeys;
uint256 sweepTxFee;
uint256[] depositsRevealBlocks;
}struct DepositKey {
bytes32 fundingTxHash;
uint32 fundingOutputIndex;
}struct DepositExtraInfo {
struct BitcoinTx.Info fundingTx;
bytes8 blindingFactor;
bytes20 walletPubKeyHash;
bytes20 refundPubKeyHash;
bytes4 refundLocktime;
}struct RedemptionProposal {
bytes20 walletPubKeyHash;
bytes[] redeemersOutputScripts;
uint256 redemptionTxFee;
}mapping(address => bool) isCoordinatorMapping that holds addresses allowed to submit proposals and request heartbeats.
mapping(bytes20 => struct WalletCoordinator.WalletLock) walletLockMapping that holds wallet time locks. The key is a 20-byte wallet public key hash.
contract Bridge bridgeHandle to the Bridge contract.
uint32 heartbeatRequestValidityDetermines 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.
uint32 heartbeatRequestGasOffsetGas that is meant to balance the heartbeat request overall cost. Can be updated by the owner based on the current conditions.
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.
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.
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.
The maximum count of deposits that can be swept within a single sweep.
Gas that is meant to balance the deposit sweep proposal submission overall cost. Can be updated by the owner based on the current conditions.
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.
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.
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.
The maximum count of redemption requests that can be processed within a single redemption.
Gas that is meant to balance the redemption proposal submission overall cost. Can be updated by the owner based on the current conditions.
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.
Removes the given address from the set of coordinator addresses.
Requirements:
The caller must be the owner,
The coordinator must be an existing coordinator.
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.
Updates parameters related to heartbeat request.
Requirements:
The caller must be the owner.
Updates parameters related to deposit sweep proposal.
Requirements:
The caller must be the owner.
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.
Wraps requestHeartbeat call and reimburses the caller's transaction cost.
See requestHeartbeat function documentation.
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.
Wraps submitDepositSweepProposal call and reimburses the caller's transaction cost.
See submitDepositSweepProposal function documentation.
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 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.
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).
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.
Updates parameters related to redemption proposal.
Requirements:
The caller must be the owner.
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.
Wraps submitRedemptionProposal call and reimburses the caller's transaction cost.
See submitRedemptionProposal function documentation.
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 (
The new value of depositRefundSafetyMargin.
_depositSweepMaxSize
uint16
The new value of depositSweepMaxSize.
_depositSweepProposalSubmissionGasOffset
uint32
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.
Extra data being subject of the validation.
The new value of redemptionRequestTimeoutSafetyMargin.
_redemptionMaxSize
uint16
The new value of redemptionMaxSize.
_redemptionProposalSubmissionGasOffset
uint32
The new value of redemptionProposalSubmissionGasOffset.
Bridge.redemptionTxMaxTotalFeeThe 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.
coordinator
address
Address of the new coordinator.
coordinator
address
Address of the existing coordinator.
walletPubKeyHash
bytes20
20-byte public key hash of the wallet
_heartbeatRequestValidity
uint32
The new value of heartbeatRequestValidity.
_heartbeatRequestGasOffset
uint32
The new value of heartbeatRequestGasOffset.
_depositSweepProposalValidity
uint32
The new value of depositSweepProposalValidity.
_depositMinAge
uint32
The new value of depositMinAge.
_depositRefundSafetyMargin
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.
proposal
struct WalletCoordinator.DepositSweepProposal
The deposit sweep proposal
proposal
struct WalletCoordinator.DepositSweepProposal
The sweeping proposal to validate.
depositsExtraInfo
struct WalletCoordinator.DepositExtraInfo[]
Deposits extra data required to perform the validation.
[0]
bool
True if the proposal is valid. Reverts otherwise.
sweepTxFee
uint256
The sweep transaction fee.
depositsCount
uint256
Count of the deposits swept by the sweep transaction.
depositKey
struct WalletCoordinator.DepositKey
Key of the given deposit.
depositor
address
Depositor that revealed the deposit.
depositExtraInfo
_redemptionProposalValidity
uint32
The new value of redemptionProposalValidity.
_redemptionRequestMinAge
uint32
The new value of redemptionRequestMinAge.
_redemptionRequestTimeoutSafetyMargin
proposal
struct WalletCoordinator.RedemptionProposal
The redemption proposal
proposal
struct WalletCoordinator.RedemptionProposal
The redemption proposal to validate.
[0]
bool
True if the proposal is valid. Reverts otherwise.
uint32
struct WalletCoordinator.DepositExtraInfo
uint32
uint32 depositSweepProposalValidityuint32 depositMinAgeuint32 depositRefundSafetyMarginuint16 depositSweepMaxSizeuint32 depositSweepProposalSubmissionGasOffsetuint32 redemptionProposalValidityuint32 redemptionRequestMinAgeuint32 redemptionRequestTimeoutSafetyMarginuint16 redemptionMaxSizeuint32 redemptionProposalSubmissionGasOffsetevent CoordinatorAdded(address coordinator)event CoordinatorRemoved(address coordinator)event WalletManuallyUnlocked(bytes20 walletPubKeyHash)event HeartbeatRequestParametersUpdated(uint32 heartbeatRequestValidity, uint32 heartbeatRequestGasOffset)event HeartbeatRequestSubmitted(bytes20 walletPubKeyHash, bytes message, address coordinator)event DepositSweepProposalParametersUpdated(uint32 depositSweepProposalValidity, uint32 depositMinAge, uint32 depositRefundSafetyMargin, uint16 depositSweepMaxSize, uint32 depositSweepProposalSubmissionGasOffset)event DepositSweepProposalSubmitted(struct WalletCoordinator.DepositSweepProposal proposal, address coordinator)event RedemptionProposalParametersUpdated(uint32 redemptionProposalValidity, uint32 redemptionRequestMinAge, uint32 redemptionRequestTimeoutSafetyMargin, uint16 redemptionMaxSize, uint32 redemptionProposalSubmissionGasOffset)event RedemptionProposalSubmitted(struct WalletCoordinator.RedemptionProposal proposal, address coordinator)modifier onlyCoordinator()modifier onlyAfterWalletLock(bytes20 walletPubKeyHash)modifier onlyReimbursableAdmin()function initialize(contract Bridge _bridge) externalfunction addCoordinator(address coordinator) externalfunction removeCoordinator(address coordinator) externalfunction unlockWallet(bytes20 walletPubKeyHash) externalfunction updateHeartbeatRequestParameters(uint32 _heartbeatRequestValidity, uint32 _heartbeatRequestGasOffset) externalfunction updateDepositSweepProposalParameters(uint32 _depositSweepProposalValidity, uint32 _depositMinAge, uint32 _depositRefundSafetyMargin, uint16 _depositSweepMaxSize, uint32 _depositSweepProposalSubmissionGasOffset) externalfunction requestHeartbeat(bytes20 walletPubKeyHash, bytes message) publicfunction requestHeartbeatWithReimbursement(bytes20 walletPubKeyHash, bytes message) externalfunction submitDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal) publicfunction submitDepositSweepProposalWithReimbursement(struct WalletCoordinator.DepositSweepProposal proposal) externalfunction validateDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal, struct WalletCoordinator.DepositExtraInfo[] depositsExtraInfo) external view returns (bool)function validateSweepTxFee(uint256 sweepTxFee, uint256 depositsCount) internal viewfunction validateDepositExtraInfo(struct WalletCoordinator.DepositKey depositKey, address depositor, struct WalletCoordinator.DepositExtraInfo depositExtraInfo) internal viewfunction updateRedemptionProposalParameters(uint32 _redemptionProposalValidity, uint32 _redemptionRequestMinAge, uint32 _redemptionRequestTimeoutSafetyMargin, uint16 _redemptionMaxSize, uint32 _redemptionProposalSubmissionGasOffset) externalfunction submitRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) publicfunction submitRedemptionProposalWithReimbursement(struct WalletCoordinator.RedemptionProposal proposal) externalfunction validateRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) external view returns (bool)Aggregates functions common to the redemption transaction proof validation and to the moving funds transaction proof validation.
function processWalletOutboundTxInput(struct BridgeState.Storage self, bytes walletOutboundTxInputVector, struct BitcoinTx.UTXO mainUtxo) internalChecks 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.
self
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.
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.
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,
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,
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,
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,
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.
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.
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.
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.
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
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
Calculate redemption key without allocations.
Finish calculating redemption key without allocations.
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.
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,
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.
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.
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.
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.
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.
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.
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.
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.
Data of the wallet's main UTXO, as currently known on the Ethereum chain.
20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction.
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.
Value of the output being processed.
MovingFundsif 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).
walletIDDkgResultSubmittedDkgResultApprovedWalletRegistryThe amount of time defined by redemptionTimeout must have passed since the redemption was requested (the request must be timed-out).
Identifiers of the wallet signing group members.
redeemerOutputScript
bytes
The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH).
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.
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.
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key).
self
struct BridgeState.Storage
balanceOwner
address
The address of the Bank balance owner whose balance is getting redeemed.
amount
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key).
self
struct BridgeState.Storage
redemptionTx
struct BitcoinTx.Info
Bitcoin redemption transaction data.
redemptionProof
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
public key hash of the wallet proving the sweep Bitcoin transaction.
mainUtxo
wallet
struct Wallets.Wallet
Data of the sweeping wallet.
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
info
struct Redemption.RedemptionTxOutputsInfo
Outcomes of the processing.
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
self
struct BridgeState.Storage
redemptionKey
uint256
Redemption key of the output being processed.
outputValue
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMembersIDs
walletPubKeyHash
bytes20
the pubkey hash of the wallet.
script
bytes
the output script of the redemption.
[0]
uint256
The key = keccak256(keccak256(script)
walletPubKeyHash
bytes20
the pubkey hash of the wallet.
scriptHash
bytes32
the output script hash of the redemption.
[0]
uint256
The key = keccak256(scriptHash
mainUtxo
uint64
mainUtxo
struct BitcoinTx.Proof
struct BitcoinTx.UTXO
bytes20
bytes20
uint64
uint32[]
function parseWalletOutboundTxInput(bytes walletOutboundTxInputVector) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex)struct RedemptionRequest {
address redeemer;
uint64 requestedAmount;
uint64 treasuryFee;
uint64 txMaxFee;
uint32 requestedAt;
}struct RedemptionTxOutputsInfo {
uint256 outputsTotalValue;
uint64 totalBurnableValue;
uint64 totalTreasuryFee;
uint32 changeIndex;
uint64 changeValue;
}struct RedemptionTxOutputsProcessingInfo {
uint256 outputStartingIndex;
uint256 outputsCount;
bytes32 walletP2PKHScriptKeccak;
bytes32 walletP2WPKHScriptKeccak;
}event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee)event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash)event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript)function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, bytes redeemerOutputScript, uint64 amount) externalfunction requestRedemption(struct BridgeState.Storage self, address balanceOwner, uint64 amount, bytes redemptionData) externalfunction requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, address redeemer, bytes redeemerOutputScript, uint64 amount) internalfunction submitRedemptionProof(struct BridgeState.Storage self, struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) externalfunction resolveRedeemingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet)function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash) internal returns (struct Redemption.RedemptionTxOutputsInfo info)function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash, struct Redemption.RedemptionTxOutputsProcessingInfo processInfo) internal returns (struct Redemption.RedemptionTxOutputsInfo resultInfo)function processNonChangeRedemptionTxOutput(struct BridgeState.Storage self, uint256 redemptionKey, uint64 outputValue) internal returns (uint64 burnableValue, uint64 treasuryFee)function notifyRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) externalfunction getRedemptionKey(bytes20 walletPubKeyHash, bytes script) internal pure returns (uint256)function _getRedemptionKey(bytes20 walletPubKeyHash, bytes32 scriptHash) internal pure returns (uint256)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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the source wallet.
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the moving funds wallet
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.
self
struct BridgeState.Storage
movingFundsTx
struct BitcoinTx.Info
Bitcoin moving funds transaction data.
movingFundsProof
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.
self
struct BridgeState.Storage
processInfo
struct MovingFunds.MovingFundsTxOutputsProcessingInfo
Processing info containing the moving funds tx hash and output vector.
targetWalletsHash
bytes32
keccak256 hash over the list of actual target wallets used in the transaction.
outputsTotalValue
uint256
Sum of all outputs values.
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMembersIDs
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
20-byte public key hash of the wallet.
mainUtxo
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.
self
struct BridgeState.Storage
sweepTx
struct BitcoinTx.Info
Bitcoin sweep funds transaction data.
sweepProof
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.
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.
walletPubKeyHash
bytes20
20-byte wallet public key hash.
value
uint64
8-byte moved funds sweep transaction output value.
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.
self
struct BridgeState.Storage
walletPubKeyHash
bytes20
public key hash of the wallet proving the sweep Bitcoin transaction.
mainUtxo
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.
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.
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
inputsTotalValue
uint256
Total inputs value sum.
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.
inputVector
bytes
Bitcoin transaction input vector.
inputStartingIndex
uint256
Index the given input starts at.
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
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.
self
struct BridgeState.Storage
movingFundsTxHash
bytes32
32-byte hash of the moving funds transaction that caused the sweep request to be created.
movingFundsTxOutputIndex
struct MovingFundsTxOutputsProcessingInfo {
bytes32 movingFundsTxHash;
bytes movingFundsTxOutputVector;
}enum MovedFundsSweepRequestState {
Unknown,
Pending,
Processed,
TimedOut
}struct MovedFundsSweepRequest {
bytes20 walletPubKeyHash;
uint64 value;
uint32 createdAt;
enum MovingFunds.MovedFundsSweepRequestState state;
}event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter)event MovingFundsTimeoutReset(bytes20 walletPubKeyHash)event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash)event MovingFundsTimedOut(bytes20 walletPubKeyHash)event MovingFundsBelowDustReported(bytes20 walletPubKeyHash)event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash)event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex)function submitMovingFundsCommitment(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) externalfunction resetMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash) externalfunction submitMovingFundsProof(struct BridgeState.Storage self, struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) externalfunction processMovingFundsTxOutputs(struct BridgeState.Storage self, struct MovingFunds.MovingFundsTxOutputsProcessingInfo processInfo) internal returns (bytes32 targetWalletsHash, uint256 outputsTotalValue)function notifyMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) externalfunction notifyMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) externalfunction submitMovedFundsSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) externalfunction processMovedFundsSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value)function resolveMovedFundsSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo)function processMovedFundsSweepTxInputs(struct BridgeState.Storage self, bytes sweepTxInputVector, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) internal returns (uint256 inputsTotalValue)function parseMovedFundsSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength)function notifyMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) externalwalletMainUtxo
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.
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.
uint32[]
Identifiers of the wallet signing group members.
struct BitcoinTx.UTXO
Data of the wallet's main UTXO, as currently known on the Ethereum chain.
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.
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.
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.
uint256
Byte length of the given input.
uint32
Index of the moving funds transaction output that is subject of the sweep request.
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members.
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.
struct BridgeGovernanceParameters.DepositData depositDatastruct BridgeGovernanceParameters.RedemptionData redemptionDatastruct BridgeGovernanceParameters.MovingFundsData movingFundsDatastruct BridgeGovernanceParameters.WalletData walletDatastruct BridgeGovernanceParameters.FraudData fraudDatastruct BridgeGovernanceParameters.TreasuryData treasuryDatacontract Bridge bridgeuint256[3] governanceDelaysuint256 bridgeGovernanceTransferChangeInitiatedaddress newBridgeGovernanceevent BridgeGovernanceTransferStarted(address newBridgeGovernance, uint256 timestamp)event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp)event DepositDustThresholdUpdated(uint64 depositDustThreshold)event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp)event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor)event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp)event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee)event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp)event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod)event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp)event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold)event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp)event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor)event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp)event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee)event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp)event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee)event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp)event RedemptionTimeoutUpdated(uint32 redemptionTimeout)event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp)event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount)event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp)event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier)event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp)event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee)event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp)event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold)event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp)event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay)event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp)event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout)event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp)event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount)event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp)event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier)event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp)event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset)event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp)event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee)event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp)event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout)event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp)event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount)event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp)event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier)event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp)event WalletCreationPeriodUpdated(uint32 walletCreationPeriod)event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp)event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance)event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp)event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance)event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp)event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance)event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp)event WalletMaxAgeUpdated(uint32 walletMaxAge)event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp)event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer)event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp)event WalletClosingPeriodUpdated(uint32 walletClosingPeriod)event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp)event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount)event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp)event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout)event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp)event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount)event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp)event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier)event TreasuryUpdateStarted(address newTreasury, uint256 timestamp)event TreasuryUpdated(address treasury)constructor(contract Bridge _bridge, uint256 _governanceDelay) publicfunction setVaultStatus(address vault, bool isTrusted) externalAllows 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.
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.
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.
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.
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.
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.
Begins the deposit dust threshold amount update process.
Can be called only by the contract owner.
Finalizes the deposit dust threshold amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the deposit treasury fee divisor amount update process.
Can be called only by the contract owner.
Finalizes the deposit treasury fee divisor amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the deposit tx max fee amount update process.
Can be called only by the contract owner.
Finalizes the deposit tx max fee amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the deposit reveal ahead period update process.
Can be called only by the contract owner.
Finalizes the deposit reveal ahead period update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption dust threshold amount update process.
Can be called only by the contract owner.
Finalizes the dust threshold amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption treasury fee divisor amount update process.
Can be called only by the contract owner.
Finalizes the redemption treasury fee divisor amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption tx max fee amount update process.
Can be called only by the contract owner.
Finalizes the redemption tx max fee amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption tx max total fee amount update process.
Can be called only by the contract owner.
Finalizes the redemption tx max total fee amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption timeout amount update process.
Can be called only by the contract owner.
Finalizes the redemption timeout amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption timeout slashing amount update process.
Can be called only by the contract owner.
Finalizes the redemption timeout slashing amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the redemption timeout notifier reward multiplier amount update process.
Can be called only by the contract owner.
Finalizes the redemption timeout notifier reward multiplier amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds tx max total fee update process.
Can be called only by the contract owner.
Finalizes the moving funds tx max total fee update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds dust threshold update process.
Can be called only by the contract owner.
Finalizes the moving funds dust threshold update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds timeout reset delay update process.
Can be called only by the contract owner.
Finalizes the moving funds timeout reset delay update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds timeout update process.
Can be called only by the contract owner.
Finalizes the moving funds timeout update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds timeout slashing amount update process.
Can be called only by the contract owner.
Finalizes the moving funds timeout slashing amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds timeout notifier reward multiplier update process.
Can be called only by the contract owner.
Finalizes the moving funds timeout notifier reward multiplier update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moving funds commitment gas offset update process.
Can be called only by the contract owner.
Finalizes the moving funds commitment gas offset update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moved funds sweep tx max total fee update process.
Can be called only by the contract owner.
Finalizes the moved funds sweep tx max total fee update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moved funds sweep timeout update process.
Can be called only by the contract owner.
Finalizes the moved funds sweep timeout update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moved funds sweep timeout slashing amount update process.
Can be called only by the contract owner.
Finalizes the moved funds sweep timeout slashing amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the moved funds sweep timeout notifier reward multiplier update process.
Can be called only by the contract owner.
Finalizes the moved funds sweep timeout notifier reward multiplier update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet creation period update process.
Can be called only by the contract owner.
Finalizes the wallet creation period update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet creation min btc balance update process.
Can be called only by the contract owner.
Finalizes the wallet creation min btc balance update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet creation max btc balance update process.
Can be called only by the contract owner.
Finalizes the wallet creation max btc balance update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet closure min btc balance update process.
Can be called only by the contract owner.
Finalizes the wallet closure min btc balance update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet max age update process.
Can be called only by the contract owner.
Finalizes the wallet max age update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet max btc transfer amount update process.
Can be called only by the contract owner.
Finalizes the wallet max btc transfer amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet closing period update process.
Can be called only by the contract owner.
Finalizes the wallet closing period update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the fraud challenge deposit amount update process.
Can be called only by the contract owner.
Finalizes the fraud challenge deposit amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the fraud challenge defeat timeout update process.
Can be called only by the contract owner.
Finalizes the fraud challenge defeat timeout update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the fraud slashing amount update process.
Can be called only by the contract owner.
Finalizes the fraud slashing amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the fraud notifier reward multiplier update process.
Can be called only by the contract owner.
Finalizes the fraud notifier reward multiplier update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the treasury address update process.
Can be called only by the contract owner. It does not perform any parameter validation.
Finalizes the treasury address update process.
Can be called only by the contract owner, after the governance delay elapses.
Gets the governance delay parameter.
Owns the WalletRegistry contract and is responsible for updating its governable parameters in respect to the governance delay.
Reverts if called before the governance delay elapses.
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.
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.
Duration of the sortition pool rewards ban imposed on operators who missed their turn for DKG result submission or who failed a heartbeat.
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.
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.
vault
address
The address of the vault.
isTrusted
bool
flag indicating whether the vault is trusted or not.
spvMaintainer
address
The address of the SPV maintainer.
isTrusted
bool
flag indicating whether the address is trusted or not.
_newGovernanceDelay
uint256
New governance delay
_newDepositDustThreshold
uint64
New deposit dust threshold amount.
_newDepositTreasuryFeeDivisor
uint64
New deposit treasury fee divisor.
_newDepositTxMaxFee
uint64
New deposit tx max fee.
_newDepositRevealAheadPeriod
uint32
New deposit reveal ahead period.
_newRedemptionDustThreshold
uint64
New redemption dust threshold.
_newRedemptionTreasuryFeeDivisor
uint64
New redemption treasury fee divisor.
_newRedemptionTxMaxFee
uint64
New redemption tx max fee.
_newRedemptionTxMaxTotalFee
uint64
New redemption tx max total fee.
_newRedemptionTimeout
uint32
New redemption timeout.
_newRedemptionTimeoutSlashingAmount
uint96
New redemption timeout slashing amount.
_newRedemptionTimeoutNotifierRewardMultiplier
uint32
New redemption timeout notifier reward multiplier.
_newMovingFundsTxMaxTotalFee
uint64
New moving funds tx max total fee.
_newMovingFundsDustThreshold
uint64
New moving funds dust threshold.
_newMovingFundsTimeoutResetDelay
uint32
New moving funds timeout reset delay.
_newMovingFundsTimeout
uint32
New moving funds timeout.
_newMovingFundsTimeoutSlashingAmount
uint96
New moving funds timeout slashing amount.
_newMovingFundsTimeoutNotifierRewardMultiplier
uint32
New moving funds timeout notifier reward multiplier.
_newMovingFundsCommitmentGasOffset
uint16
New moving funds commitment gas offset.
_newMovedFundsSweepTxMaxTotalFee
uint64
New moved funds sweep tx max total fee.
_newMovedFundsSweepTimeout
uint32
New moved funds sweep timeout.
_newMovedFundsSweepTimeoutSlashingAmount
uint96
New moved funds sweep timeout slashing amount.
_newMovedFundsSweepTimeoutNotifierRewardMultiplier
uint32
New moved funds sweep timeout notifier reward multiplier.
_newWalletCreationPeriod
uint32
New wallet creation period.
_newWalletCreationMinBtcBalance
uint64
New wallet creation min btc balance.
_newWalletCreationMaxBtcBalance
uint64
New wallet creation max btc balance.
_newWalletClosureMinBtcBalance
uint64
New wallet closure min btc balance.
_newWalletMaxAge
uint32
New wallet max age.
_newWalletMaxBtcTransfer
uint64
New wallet max btc transfer.
_newWalletClosingPeriod
uint32
New wallet closing period.
_newFraudChallengeDepositAmount
uint96
New fraud challenge deposit amount.
_newFraudChallengeDefeatTimeout
uint32
New fraud challenge defeat timeout.
_newFraudSlashingAmount
uint96
New fraud slashing amount.
_newFraudNotifierRewardMultiplier
uint32
New fraud notifier reward multiplier.
_newTreasury
address
New treasury address.
uint256
Timestamp indicating the beginning of the change.
Upgrades the random beacon.
Can be called only by the contract owner.
_newRandomBeacon
address
New random beacon address
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.
_walletOwner
address
The Wallet Owner's address
Begins the governance delay update process.
Can be called only by the contract owner.
_newGovernanceDelay
uint256
New governance delay
Finalizes the governance delay update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet registry governance transfer process.
Can be called only by the contract owner.
Finalizes the wallet registry governance transfer process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the wallet owner update process.
Can be called only by the contract owner.
_newWalletOwner
address
New wallet owner address
Finalizes the wallet owner update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the minimum authorization amount update process.
Can be called only by the contract owner.
_newMinimumAuthorization
uint96
New minimum authorization amount.
Finalizes the minimum authorization amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the authorization decrease delay update process.
Can be called only by the contract owner.
_newAuthorizationDecreaseDelay
uint64
New authorization decrease delay
Finalizes the authorization decrease delay update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the authorization decrease change period update process.
Can be called only by the contract owner.
_newAuthorizationDecreaseChangePeriod
uint64
New authorization decrease change period
Finalizes the authorization decrease change period update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the malicious DKG result slashing amount update process.
Can be called only by the contract owner.
_newMaliciousDkgResultSlashingAmount
uint96
New malicious DKG result slashing amount
Finalizes the malicious DKG result slashing amount update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the DKG malicious result notification reward multiplier update process.
Can be called only by the contract owner.
_newMaliciousDkgResultNotificationRewardMultiplier
uint256
New DKG malicious result notification reward multiplier.
Finalizes the DKG malicious result notification reward multiplier update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the dkg result submission gas update process.
Can be called only by the contract owner.
_newDkgResultSubmissionGas
uint256
New DKG result submission gas.
Finalizes the dkg result submission gas update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the dkg approval gas offset update process.
Can be called only by the contract owner.
_newDkgResultApprovalGasOffset
uint256
New DKG result approval gas.
Finalizes the dkg result approval gas offset update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the notify operator inactivity gas offset update process.
Can be called only by the contract owner.
_newNotifyOperatorInactivityGasOffset
uint256
New operator inactivity notification gas offset
Finalizes the notify operator inactivity gas offset update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the notify seed for DKG delivery timeout gas offset update process.
Can be called only by the contract owner.
_newNotifySeedTimeoutGasOffset
uint256
New seed for DKG delivery timeout notification gas offset
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.
Begins the notify DKG timeout negative gas offset update process.
Can be called only by the contract owner.
_newNotifyDkgTimeoutNegativeGasOffset
uint256
New DKG timeout negative gas notification gas offset
Finalizes the notify DKG timeout negative gas offset update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the reimbursement pool update process.
Can be called only by the contract owner.
_newReimbursementPool
address payable
New reimbursement pool.
Finalizes the reimbursement pool update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the sortition pool rewards ban duration update process.
Can be called only by the contract owner.
_newSortitionPoolRewardsBanDuration
uint256
New sortition pool rewards ban duration.
Finalizes the sortition pool rewards ban duration update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the DKG seed timeout update process.
Can be called only by the contract owner.
_newDkgSeedTimeout
uint256
New DKG seed timeout in blocks
Finalizes the DKG seed timeout update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the DKG result challenge period length update process.
Can be called only by the contract owner.
_newDkgResultChallengePeriodLength
uint256
New DKG result challenge period length in blocks
Finalizes the DKG result challenge period length update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the DKG result challenge extra gas update process.
Can be called only by the contract owner.
_newDkgResultChallengeExtraGas
uint256
New DKG result challenge extra gas
Finalizes the DKG result challenge extra gas update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the DKG result submission timeout update process.
Can be called only by the contract owner.
_newDkgResultSubmissionTimeout
uint256
New DKG result submission timeout in blocks
Finalizes the DKG result submission timeout update process.
Can be called only by the contract owner, after the governance delay elapses.
Begins the DKG submitter precedence period length update process.
Can be called only by the contract owner.
_newSubmitterPrecedencePeriodLength
uint256
New DKG submitter precedence period length in blocks
Finalizes the DKG submitter precedence period length update process.
Can be called only by the contract owner, after the governance delay elapses.
Withdraws rewards belonging to operators marked as ineligible for sortition pool rewards.
Can be called only by the contract owner.
recipient
address
Recipient of withdrawn rewards.
Get the time remaining until the governance delay can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the wallet registry governance can be transferred.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the minimum authorization amount can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the authorization decrease delay can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the authorization decrease change period can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the malicious DKG result slashing amount can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the DKG malicious result notification reward multiplier duration can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the sortition pool rewards ban duration can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the DKG seed timeout can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the DKG result challenge period length can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the DKG result submission timeout can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the wallet owner can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the wallet owner can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the dkg result submission gas can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the dkg result approval gas offset can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the operator inactivity gas offset can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the seed for DKG delivery timeout gas offset can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until the DKG timeout negative gas offset can be updated.
[0]
uint256
Remaining time in seconds.
Get the time remaining until reimbursement pool can be updated.
[0]
uint256
Remaining time in seconds.
Gets the time remaining until the governable parameter update can be committed.
changeTimestamp
uint256
Timestamp indicating the beginning of the change.
[0]
uint256
Remaining time in seconds.
changeInitiatedTimestamp
function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) externalfunction beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) externalfunction finalizeGovernanceDelayUpdate() externalfunction beginBridgeGovernanceTransfer(address _newBridgeGovernance) externalfunction finalizeBridgeGovernanceTransfer() externalfunction beginDepositDustThresholdUpdate(uint64 _newDepositDustThreshold) externalfunction finalizeDepositDustThresholdUpdate() externalfunction beginDepositTreasuryFeeDivisorUpdate(uint64 _newDepositTreasuryFeeDivisor) externalfunction finalizeDepositTreasuryFeeDivisorUpdate() externalfunction beginDepositTxMaxFeeUpdate(uint64 _newDepositTxMaxFee) externalfunction finalizeDepositTxMaxFeeUpdate() externalfunction beginDepositRevealAheadPeriodUpdate(uint32 _newDepositRevealAheadPeriod) externalfunction finalizeDepositRevealAheadPeriodUpdate() externalfunction beginRedemptionDustThresholdUpdate(uint64 _newRedemptionDustThreshold) externalfunction finalizeRedemptionDustThresholdUpdate() externalfunction beginRedemptionTreasuryFeeDivisorUpdate(uint64 _newRedemptionTreasuryFeeDivisor) externalfunction finalizeRedemptionTreasuryFeeDivisorUpdate() externalfunction beginRedemptionTxMaxFeeUpdate(uint64 _newRedemptionTxMaxFee) externalfunction finalizeRedemptionTxMaxFeeUpdate() externalfunction beginRedemptionTxMaxTotalFeeUpdate(uint64 _newRedemptionTxMaxTotalFee) externalfunction finalizeRedemptionTxMaxTotalFeeUpdate() externalfunction beginRedemptionTimeoutUpdate(uint32 _newRedemptionTimeout) externalfunction finalizeRedemptionTimeoutUpdate() externalfunction beginRedemptionTimeoutSlashingAmountUpdate(uint96 _newRedemptionTimeoutSlashingAmount) externalfunction finalizeRedemptionTimeoutSlashingAmountUpdate() externalfunction beginRedemptionTimeoutNotifierRewardMultiplierUpdate(uint32 _newRedemptionTimeoutNotifierRewardMultiplier) externalfunction finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate() externalfunction beginMovingFundsTxMaxTotalFeeUpdate(uint64 _newMovingFundsTxMaxTotalFee) externalfunction finalizeMovingFundsTxMaxTotalFeeUpdate() externalfunction beginMovingFundsDustThresholdUpdate(uint64 _newMovingFundsDustThreshold) externalfunction finalizeMovingFundsDustThresholdUpdate() externalfunction beginMovingFundsTimeoutResetDelayUpdate(uint32 _newMovingFundsTimeoutResetDelay) externalfunction finalizeMovingFundsTimeoutResetDelayUpdate() externalfunction beginMovingFundsTimeoutUpdate(uint32 _newMovingFundsTimeout) externalfunction finalizeMovingFundsTimeoutUpdate() externalfunction beginMovingFundsTimeoutSlashingAmountUpdate(uint96 _newMovingFundsTimeoutSlashingAmount) externalfunction finalizeMovingFundsTimeoutSlashingAmountUpdate() externalfunction beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) externalfunction finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate() externalfunction beginMovingFundsCommitmentGasOffsetUpdate(uint16 _newMovingFundsCommitmentGasOffset) externalfunction finalizeMovingFundsCommitmentGasOffsetUpdate() externalfunction beginMovedFundsSweepTxMaxTotalFeeUpdate(uint64 _newMovedFundsSweepTxMaxTotalFee) externalfunction finalizeMovedFundsSweepTxMaxTotalFeeUpdate() externalfunction beginMovedFundsSweepTimeoutUpdate(uint32 _newMovedFundsSweepTimeout) externalfunction finalizeMovedFundsSweepTimeoutUpdate() externalfunction beginMovedFundsSweepTimeoutSlashingAmountUpdate(uint96 _newMovedFundsSweepTimeoutSlashingAmount) externalfunction finalizeMovedFundsSweepTimeoutSlashingAmountUpdate() externalfunction beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) externalfunction finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate() externalfunction beginWalletCreationPeriodUpdate(uint32 _newWalletCreationPeriod) externalfunction finalizeWalletCreationPeriodUpdate() externalfunction beginWalletCreationMinBtcBalanceUpdate(uint64 _newWalletCreationMinBtcBalance) externalfunction finalizeWalletCreationMinBtcBalanceUpdate() externalfunction beginWalletCreationMaxBtcBalanceUpdate(uint64 _newWalletCreationMaxBtcBalance) externalfunction finalizeWalletCreationMaxBtcBalanceUpdate() externalfunction beginWalletClosureMinBtcBalanceUpdate(uint64 _newWalletClosureMinBtcBalance) externalfunction finalizeWalletClosureMinBtcBalanceUpdate() externalfunction beginWalletMaxAgeUpdate(uint32 _newWalletMaxAge) externalfunction finalizeWalletMaxAgeUpdate() externalfunction beginWalletMaxBtcTransferUpdate(uint64 _newWalletMaxBtcTransfer) externalfunction finalizeWalletMaxBtcTransferUpdate() externalfunction beginWalletClosingPeriodUpdate(uint32 _newWalletClosingPeriod) externalfunction finalizeWalletClosingPeriodUpdate() externalfunction beginFraudChallengeDepositAmountUpdate(uint96 _newFraudChallengeDepositAmount) externalfunction finalizeFraudChallengeDepositAmountUpdate() externalfunction beginFraudChallengeDefeatTimeoutUpdate(uint32 _newFraudChallengeDefeatTimeout) externalfunction finalizeFraudChallengeDefeatTimeoutUpdate() externalfunction beginFraudSlashingAmountUpdate(uint96 _newFraudSlashingAmount) externalfunction finalizeFraudSlashingAmountUpdate() externalfunction beginFraudNotifierRewardMultiplierUpdate(uint32 _newFraudNotifierRewardMultiplier) externalfunction finalizeFraudNotifierRewardMultiplierUpdate() externalfunction beginTreasuryUpdate(address _newTreasury) externalfunction finalizeTreasuryUpdate() externalfunction governanceDelay() internal view returns (uint256)uint256 newGovernanceDelayuint256 governanceDelayChangeInitiatedaddress newWalletRegistryGovernanceuint256 walletRegistryGovernanceTransferInitiatedaddress newWalletOwneruint256 walletOwnerChangeInitiateduint96 newMinimumAuthorizationuint256 minimumAuthorizationChangeInitiateduint64 newAuthorizationDecreaseDelayuint256 authorizationDecreaseDelayChangeInitiateduint64 newAuthorizationDecreaseChangePerioduint256 authorizationDecreaseChangePeriodChangeInitiateduint96 newMaliciousDkgResultSlashingAmountuint256 maliciousDkgResultSlashingAmountChangeInitiateduint256 newMaliciousDkgResultNotificationRewardMultiplieruint256 maliciousDkgResultNotificationRewardMultiplierChangeInitiateduint256 newSortitionPoolRewardsBanDurationuint256 sortitionPoolRewardsBanDurationChangeInitiateduint256 newDkgSeedTimeoutuint256 dkgSeedTimeoutChangeInitiateduint256 newDkgResultChallengePeriodLengthuint256 dkgResultChallengePeriodLengthChangeInitiateduint256 newDkgResultChallengeExtraGasuint256 dkgResultChallengeExtraGasChangeInitiateduint256 newDkgResultSubmissionTimeoutuint256 dkgResultSubmissionTimeoutChangeInitiateduint256 newSubmitterPrecedencePeriodLengthuint256 dkgSubmitterPrecedencePeriodLengthChangeInitiateduint256 newDkgResultSubmissionGasuint256 dkgResultSubmissionGasChangeInitiateduint256 newDkgResultApprovalGasOffsetuint256 dkgResultApprovalGasOffsetChangeInitiateduint256 newNotifyOperatorInactivityGasOffsetuint256 notifyOperatorInactivityGasOffsetChangeInitiateduint256 newNotifySeedTimeoutGasOffsetuint256 notifySeedTimeoutGasOffsetChangeInitiateduint256 newNotifyDkgTimeoutNegativeGasOffsetuint256 notifyDkgTimeoutNegativeGasOffsetChangeInitiatedaddress payable newReimbursementPooluint256 reimbursementPoolChangeInitiatedcontract WalletRegistry walletRegistryuint256 governanceDelayevent GovernanceDelayUpdateStarted(uint256 governanceDelay, uint256 timestamp)event GovernanceDelayUpdated(uint256 governanceDelay)event WalletRegistryGovernanceTransferStarted(address newWalletRegistryGovernance, uint256 timestamp)event WalletRegistryGovernanceTransferred(address newWalletRegistryGovernance)event WalletOwnerUpdateStarted(address walletOwner, uint256 timestamp)event WalletOwnerUpdated(address walletOwner)event MinimumAuthorizationUpdateStarted(uint96 minimumAuthorization, uint256 timestamp)event MinimumAuthorizationUpdated(uint96 minimumAuthorization)event AuthorizationDecreaseDelayUpdateStarted(uint64 authorizationDecreaseDelay, uint256 timestamp)event AuthorizationDecreaseDelayUpdated(uint64 authorizationDecreaseDelay)event AuthorizationDecreaseChangePeriodUpdateStarted(uint64 authorizationDecreaseChangePeriod, uint256 timestamp)event AuthorizationDecreaseChangePeriodUpdated(uint64 authorizationDecreaseChangePeriod)event MaliciousDkgResultSlashingAmountUpdateStarted(uint256 maliciousDkgResultSlashingAmount, uint256 timestamp)event MaliciousDkgResultSlashingAmountUpdated(uint256 maliciousDkgResultSlashingAmount)event MaliciousDkgResultNotificationRewardMultiplierUpdateStarted(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 timestamp)event MaliciousDkgResultNotificationRewardMultiplierUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier)event SortitionPoolRewardsBanDurationUpdateStarted(uint256 sortitionPoolRewardsBanDuration, uint256 timestamp)event SortitionPoolRewardsBanDurationUpdated(uint256 sortitionPoolRewardsBanDuration)event DkgSeedTimeoutUpdateStarted(uint256 dkgSeedTimeout, uint256 timestamp)event DkgSeedTimeoutUpdated(uint256 dkgSeedTimeout)event DkgResultChallengePeriodLengthUpdateStarted(uint256 dkgResultChallengePeriodLength, uint256 timestamp)event DkgResultChallengePeriodLengthUpdated(uint256 dkgResultChallengePeriodLength)event DkgResultChallengeExtraGasUpdateStarted(uint256 dkgResultChallengeExtraGas, uint256 timestamp)event DkgResultChallengeExtraGasUpdated(uint256 dkgResultChallengeExtraGas)event DkgResultSubmissionTimeoutUpdateStarted(uint256 dkgResultSubmissionTimeout, uint256 timestamp)event DkgResultSubmissionTimeoutUpdated(uint256 dkgResultSubmissionTimeout)event DkgSubmitterPrecedencePeriodLengthUpdateStarted(uint256 submitterPrecedencePeriodLength, uint256 timestamp)event DkgSubmitterPrecedencePeriodLengthUpdated(uint256 submitterPrecedencePeriodLength)event DkgResultSubmissionGasUpdateStarted(uint256 dkgResultSubmissionGas, uint256 timestamp)event DkgResultSubmissionGasUpdated(uint256 dkgResultSubmissionGas)event DkgResultApprovalGasOffsetUpdateStarted(uint256 dkgResultApprovalGasOffset, uint256 timestamp)event DkgResultApprovalGasOffsetUpdated(uint256 dkgResultApprovalGasOffset)event NotifyOperatorInactivityGasOffsetUpdateStarted(uint256 notifyOperatorInactivityGasOffset, uint256 timestamp)event NotifyOperatorInactivityGasOffsetUpdated(uint256 notifyOperatorInactivityGasOffset)event NotifySeedTimeoutGasOffsetUpdateStarted(uint256 notifySeedTimeoutGasOffset, uint256 timestamp)event NotifySeedTimeoutGasOffsetUpdated(uint256 notifySeedTimeoutGasOffset)event NotifyDkgTimeoutNegativeGasOffsetUpdateStarted(uint256 notifyDkgTimeoutNegativeGasOffset, uint256 timestamp)event NotifyDkgTimeoutNegativeGasOffsetUpdated(uint256 notifyDkgTimeoutNegativeGasOffset)event ReimbursementPoolUpdateStarted(address reimbursementPool, uint256 timestamp)event ReimbursementPoolUpdated(address reimbursementPool)modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp)constructor(contract WalletRegistry _walletRegistry, uint256 _governanceDelay) publicfunction upgradeRandomBeacon(address _newRandomBeacon) externalfunction initializeWalletOwner(address _walletOwner) externalfunction beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) externalfunction finalizeGovernanceDelayUpdate() externalfunction beginWalletRegistryGovernanceTransfer(address _newWalletRegistryGovernance) externalfunction finalizeWalletRegistryGovernanceTransfer() externalfunction beginWalletOwnerUpdate(address _newWalletOwner) externalfunction finalizeWalletOwnerUpdate() externalfunction beginMinimumAuthorizationUpdate(uint96 _newMinimumAuthorization) externalfunction finalizeMinimumAuthorizationUpdate() externalfunction beginAuthorizationDecreaseDelayUpdate(uint64 _newAuthorizationDecreaseDelay) externalfunction finalizeAuthorizationDecreaseDelayUpdate() externalfunction beginAuthorizationDecreaseChangePeriodUpdate(uint64 _newAuthorizationDecreaseChangePeriod) externalfunction finalizeAuthorizationDecreaseChangePeriodUpdate() externalfunction beginMaliciousDkgResultSlashingAmountUpdate(uint96 _newMaliciousDkgResultSlashingAmount) externalfunction finalizeMaliciousDkgResultSlashingAmountUpdate() externalfunction beginMaliciousDkgResultNotificationRewardMultiplierUpdate(uint256 _newMaliciousDkgResultNotificationRewardMultiplier) externalfunction finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate() externalfunction beginDkgResultSubmissionGasUpdate(uint256 _newDkgResultSubmissionGas) externalfunction finalizeDkgResultSubmissionGasUpdate() externalfunction beginDkgResultApprovalGasOffsetUpdate(uint256 _newDkgResultApprovalGasOffset) externalfunction finalizeDkgResultApprovalGasOffsetUpdate() externalfunction beginNotifyOperatorInactivityGasOffsetUpdate(uint256 _newNotifyOperatorInactivityGasOffset) externalfunction finalizeNotifyOperatorInactivityGasOffsetUpdate() externalfunction beginNotifySeedTimeoutGasOffsetUpdate(uint256 _newNotifySeedTimeoutGasOffset) externalfunction finalizeNotifySeedTimeoutGasOffsetUpdate() externalfunction beginNotifyDkgTimeoutNegativeGasOffsetUpdate(uint256 _newNotifyDkgTimeoutNegativeGasOffset) externalfunction finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate() externalfunction beginReimbursementPoolUpdate(address payable _newReimbursementPool) externalfunction finalizeReimbursementPoolUpdate() externalfunction beginSortitionPoolRewardsBanDurationUpdate(uint256 _newSortitionPoolRewardsBanDuration) externalfunction finalizeSortitionPoolRewardsBanDurationUpdate() externalfunction beginDkgSeedTimeoutUpdate(uint256 _newDkgSeedTimeout) externalfunction finalizeDkgSeedTimeoutUpdate() externalfunction beginDkgResultChallengePeriodLengthUpdate(uint256 _newDkgResultChallengePeriodLength) externalfunction finalizeDkgResultChallengePeriodLengthUpdate() externalfunction beginDkgResultChallengeExtraGasUpdate(uint256 _newDkgResultChallengeExtraGas) externalfunction finalizeDkgResultChallengeExtraGasUpdate() externalfunction beginDkgResultSubmissionTimeoutUpdate(uint256 _newDkgResultSubmissionTimeout) externalfunction finalizeDkgResultSubmissionTimeoutUpdate() externalfunction beginDkgSubmitterPrecedencePeriodLengthUpdate(uint256 _newSubmitterPrecedencePeriodLength) externalfunction finalizeDkgSubmitterPrecedencePeriodLengthUpdate() externalfunction withdrawIneligibleRewards(address recipient) externalfunction getRemainingGovernanceDelayUpdateTime() external view returns (uint256)function getRemainingWalletRegistryGovernanceTransferDelayTime() external view returns (uint256)function getRemainingMimimumAuthorizationUpdateTime() external view returns (uint256)function getRemainingAuthorizationDecreaseDelayUpdateTime() external view returns (uint256)function getRemainingAuthorizationDecreaseChangePeriodUpdateTime() external view returns (uint256)function getRemainingMaliciousDkgResultSlashingAmountUpdateTime() external view returns (uint256)function getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime() external view returns (uint256)function getRemainingSortitionPoolRewardsBanDurationUpdateTime() external view returns (uint256)function getRemainingDkgSeedTimeoutUpdateTime() external view returns (uint256)function getRemainingDkgResultChallengePeriodLengthUpdateTime() external view returns (uint256)function getRemainingDkgResultChallengeExtraGasUpdateTime() external view returns (uint256)function getRemainingDkgResultSubmissionTimeoutUpdateTime() external view returns (uint256)function getRemainingWalletOwnerUpdateTime() external view returns (uint256)function getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime() external view returns (uint256)function getRemainingDkgResultSubmissionGasUpdateTime() external view returns (uint256)function getRemainingDkgResultApprovalGasOffsetUpdateTime() external view returns (uint256)function getRemainingNotifyOperatorInactivityGasOffsetUpdateTime() external view returns (uint256)function getRemainingNotifySeedTimeoutGasOffsetUpdateTime() external view returns (uint256)function getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime() external view returns (uint256)function getRemainingReimbursementPoolUpdateTime() external view returns (uint256)function getRemainingChangeTime(uint256 changeTimestamp) internal view returns (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.
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.
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.
Reverts if called not by the Wallet Owner.
Used to initialize immutable variables only, use initialize function for upgradable contract initialization on deployment.
Initializes upgradable contract on deployment.
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.
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.
recipient
address
Recipient of withdrawn rewards.
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.
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.
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.
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.
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.
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.
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.
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.
_randomBeacon
contract IRandomBeacon
Random Beacon address.
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.
_walletOwner
contract IWalletOwner
New wallet owner address.
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.
_minimumAuthorization
uint96
New minimum authorization amount.
_authorizationDecreaseDelay
uint64
New authorization decrease delay in seconds.
_authorizationDecreaseChangePeriod
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.
_seedTimeout
uint256
New seed timeout.
_resultChallengePeriodLength
uint256
New DKG result challenge period length.
_resultChallengeExtraGas
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.
maliciousDkgResultNotificationRewardMultiplier
uint256
New value of the DKG malicious result notification reward multiplier.
sortitionPoolRewardsBanDuration
uint256
New sortition pool rewards ban duration in seconds.
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.
maliciousDkgResultSlashingAmount
uint96
New malicious DKG result slashing amount.
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.
dkgResultSubmissionGas
uint256
New DKG result submission gas.
dkgResultApprovalGasOffset
uint256
New DKG result approval gas offset.
notifyOperatorInactivityGasOffset
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.
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.
walletID
bytes32
ID of the wallet.
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.
relayEntry
uint256
Relay entry.
uint256
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)}
dkgResult
struct EcdsaDkg.Result
DKG result.
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.
dkgResult
struct EcdsaDkg.Result
Result to approve. Must match the submitted result stored during submitDkgResult.
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.
Notifies about DKG timeout.
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.
dkgResult
struct EcdsaDkg.Result
Result to challenge. Must match the submitted result stored during submitDkgResult.
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
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
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.
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
Checks if DKG result is valid for the current DKG.
result
struct EcdsaDkg.Result
DKG result.
[0]
bool
True if the result is valid. If the result is invalid it returns false and an error message.
[1]
string
Check current wallet creation state.
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]
walletID
bytes32
ID of the wallet.
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members.
operator
[0]
bool
True - if the operator is a member of the given wallet signing group. False - otherwise.
Checks if awaiting seed timed out.
[0]
bool
True if awaiting seed timed out, false otherwise.
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.
[0]
bool
True if DKG timed out, false otherwise.
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.
walletID
bytes32
ID of the wallet.
[0]
bytes
Uncompressed public key of the wallet.
Checks if a wallet with the given ID is registered.
walletID
bytes32
Wallet's ID.
[0]
bool
True if wallet is registered, false otherwise.
The minimum authorization amount required so that operator can participate in ECDSA Wallet operations.
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.
Returns the amount of rewards available for withdrawal for the given staking provider. Reverts if staking provider has not registered the operator address.
Returns the amount of stake that is pending authorization decrease for the given staking provider. If no authorization decrease has been requested, returns zero.
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.
Returns operator registered for the given staking provider.
Returns staking provider of the given operator.
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.
Returns true if the given operator is in the sortition pool. Otherwise, returns false.
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.
[0]
uint32[]
IDs of selected group members.
Retrieves dkg parameters that were set in DKG library.
Returns authorization-related parameters.
The minimum authorization is also returned by minimumAuthorization() function, as a requirement of IApplication interface.
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
Retrieves reward-related parameters.
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.
Retrieves slashing-related parameters.
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.
Retrieves gas-related parameters.
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
struct EcdsaAuthorization.Data authorizationstruct EcdsaDkg.Data dkgstruct Wallets.Data walletsuint96 _maliciousDkgResultSlashingAmountuint256 _maliciousDkgResultNotificationRewardMultiplieruint256 _sortitionPoolRewardsBanDurationuint256 _dkgResultSubmissionGasuint256 _dkgResultApprovalGasOffsetuint256 _notifyOperatorInactivityGasOffsetuint256 _notifySeedTimeoutGasOffsetuint256 _notifyDkgTimeoutNegativeGasOffsetmapping(bytes32 => uint256) inactivityClaimNoncecontract IWalletOwner walletOwnercontract SortitionPool sortitionPoolcontract IStaking stakingcontract IRandomBeacon randomBeaconevent DkgStarted(uint256 seed)event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct EcdsaDkg.Result result)event DkgTimedOut()event DkgResultApproved(bytes32 resultHash, address approver)event DkgResultChallenged(bytes32 resultHash, address challenger, string reason)event DkgStateLocked()event DkgSeedTimedOut()event WalletCreated(bytes32 walletID, bytes32 dkgResultHash)event WalletClosed(bytes32 walletID)event DkgMaliciousResultSlashed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter)event DkgMaliciousResultSlashingFailed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter)event AuthorizationParametersUpdated(uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod)event RewardParametersUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration)event SlashingParametersUpdated(uint256 maliciousDkgResultSlashingAmount)event DkgParametersUpdated(uint256 seedTimeout, uint256 resultChallengePeriodLength, uint256 resultChallengeExtraGas, uint256 resultSubmissionTimeout, uint256 resultSubmitterPrecedencePeriodLength)event GasParametersUpdated(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset)event RandomBeaconUpgraded(address randomBeacon)event WalletOwnerUpdated(address walletOwner)event OperatorRegistered(address stakingProvider, address operator)event AuthorizationIncreased(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount)event AuthorizationDecreaseRequested(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount, uint64 decreasingAt)event AuthorizationDecreaseApproved(address stakingProvider)event InvoluntaryAuthorizationDecreaseFailed(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount)event OperatorJoinedSortitionPool(address stakingProvider, address operator)event OperatorStatusUpdated(address stakingProvider, address operator)event InactivityClaimed(bytes32 walletID, uint256 nonce, address notifier)modifier onlyStakingContract()modifier onlyWalletOwner()modifier onlyReimbursableAdmin()constructor(contract SortitionPool _sortitionPool, contract IStaking _staking) publicfunction initialize(contract EcdsaDkgValidator _ecdsaDkgValidator, contract IRandomBeacon _randomBeacon, contract ReimbursementPool _reimbursementPool) externalfunction withdrawRewards(address stakingProvider) externalfunction withdrawIneligibleRewards(address recipient) externalfunction registerOperator(address operator) externalfunction joinSortitionPool() externalfunction updateOperatorStatus(address operator) externalfunction authorizationIncreased(address stakingProvider, uint96 fromAmount, uint96 toAmount) externalfunction authorizationDecreaseRequested(address stakingProvider, uint96 fromAmount, uint96 toAmount) externalfunction approveAuthorizationDecrease(address stakingProvider) externalfunction involuntaryAuthorizationDecrease(address stakingProvider, uint96 fromAmount, uint96 toAmount) externalfunction upgradeRandomBeacon(contract IRandomBeacon _randomBeacon) externalfunction updateWalletOwner(contract IWalletOwner _walletOwner) externalfunction updateAuthorizationParameters(uint96 _minimumAuthorization, uint64 _authorizationDecreaseDelay, uint64 _authorizationDecreaseChangePeriod) externalfunction updateDkgParameters(uint256 _seedTimeout, uint256 _resultChallengePeriodLength, uint256 _resultChallengeExtraGas, uint256 _resultSubmissionTimeout, uint256 _submitterPrecedencePeriodLength) externalfunction updateRewardParameters(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) externalfunction updateSlashingParameters(uint96 maliciousDkgResultSlashingAmount) externalfunction updateGasParameters(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) externalfunction requestNewWallet() externalfunction closeWallet(bytes32 walletID) externalfunction __beaconCallback(uint256 relayEntry, uint256) externalfunction submitDkgResult(struct EcdsaDkg.Result dkgResult) externalfunction approveDkgResult(struct EcdsaDkg.Result dkgResult) externalfunction notifySeedTimeout() externalfunction notifyDkgTimeout() externalfunction challengeDkgResult(struct EcdsaDkg.Result dkgResult) externalfunction notifyOperatorInactivity(struct EcdsaInactivity.Claim claim, uint256 nonce, uint32[] groupMembers) externalfunction seize(uint96 amount, uint256 rewardMultiplier, address notifier, bytes32 walletID, uint32[] walletMembersIDs) externalfunction isDkgResultValid(struct EcdsaDkg.Result result) external view returns (bool, string)function getWalletCreationState() external view returns (enum EcdsaDkg.State)function isWalletMember(bytes32 walletID, uint32[] walletMembersIDs, address operator, uint256 walletMemberIndex) external view returns (bool)function hasSeedTimedOut() external view returns (bool)function hasDkgTimedOut() external view returns (bool)function getWallet(bytes32 walletID) external view returns (struct Wallets.Wallet)function getWalletPublicKey(bytes32 walletID) external view returns (bytes)function isWalletRegistered(bytes32 walletID) external view returns (bool)function minimumAuthorization() external view returns (uint96)function eligibleStake(address stakingProvider) external view returns (uint96)function availableRewards(address stakingProvider) external view returns (uint96)function pendingAuthorizationDecrease(address stakingProvider) external view returns (uint96)function remainingAuthorizationDecreaseDelay(address stakingProvider) external view returns (uint64)function stakingProviderToOperator(address stakingProvider) public view returns (address)function operatorToStakingProvider(address operator) public view returns (address)function isOperatorUpToDate(address operator) external view returns (bool)function isOperatorInPool(address operator) external view returns (bool)function selectGroup() external view returns (uint32[])function dkgParameters() external view returns (struct EcdsaDkg.Parameters)function authorizationParameters() external view returns (uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod)function rewardParameters() external view returns (uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration)function slashingParameters() external view returns (uint96 maliciousDkgResultSlashingAmount)function gasParameters() external view returns (uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset)uint64
New authorization decrease change period in seconds.
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.
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.
uint32[]
Identifiers of the wallet signing group members.
address
Address of the misbehavior notifier.
walletID
bytes32
ID of the wallet.
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members.
address
Address of the checked operator.
walletMemberIndex
uint256
Position of the operator in the wallet signing group members list.
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.
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.
struct TreasuryData {
address newTreasury;
uint256 treasuryChangeInitiated;
}struct DepositData {
uint64 newDepositDustThreshold;
uint256 depositDustThresholdChangeInitiated;
uint64 newDepositTreasuryFeeDivisor;
uint256 depositTreasuryFeeDivisorChangeInitiated;
uint64 newDepositTxMaxFee;
uint256 depositTxMaxFeeChangeInitiated;
uint32 newDepositRevealAheadPeriod;
uint256 depositRevealAheadPeriodChangeInitiated;
}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;
}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;
}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;
}struct FraudData {
uint96 newFraudChallengeDepositAmount;
uint256 fraudChallengeDepositAmountChangeInitiated;
uint32 newFraudChallengeDefeatTimeout;
uint256 fraudChallengeDefeatTimeoutChangeInitiated;
uint96 newFraudSlashingAmount;
uint256 fraudSlashingAmountChangeInitiated;
uint32 newFraudNotifierRewardMultiplier;
uint256 fraudNotifierRewardMultiplierChangeInitiated;
}event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp)event DepositDustThresholdUpdated(uint64 depositDustThreshold)event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp)event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor)event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp)event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee)event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp)event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod)event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp)event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold)event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp)event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor)event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp)event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee)event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp)event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee)event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp)event RedemptionTimeoutUpdated(uint32 redemptionTimeout)event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp)event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount)event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp)event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier)event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp)event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee)event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp)event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold)event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp)event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay)event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp)event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout)event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp)event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount)event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp)event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier)event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp)event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset)event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp)event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee)event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp)event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout)event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp)event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount)event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp)event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier)event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp)event WalletCreationPeriodUpdated(uint32 walletCreationPeriod)event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp)event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance)event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp)event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance)event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp)event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance)event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp)event WalletMaxAgeUpdated(uint32 walletMaxAge)event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp)event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer)event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp)event WalletClosingPeriodUpdated(uint32 walletClosingPeriod)event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp)event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount)event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp)event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout)event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp)event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount)event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp)event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier)event TreasuryUpdateStarted(address newTreasury, uint256 timestamp)event TreasuryUpdated(address treasury)modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 governanceDelay)Reverts if called before the governance delay elapses.
changeInitiatedTimestamp
uint256
Timestamp indicating the beginning of the change.
Begins the deposit dust threshold amount update process.
Finalizes the deposit dust threshold amount update process.
Can be called after the governance delay elapses.
Begins the deposit treasury fee divisor amount update process.
Finalizes the deposit treasury fee divisor amount update process.
Can be called after the governance delay elapses.
Begins the deposit tx max fee amount update process.
Finalizes the deposit tx max fee amount update process.
Can be called after the governance delay elapses.
Begins the deposit reveal ahead period update process.
Finalizes the deposit reveal ahead period update process.
Can be called after the governance delay elapses.
Begins the redemption dust threshold amount update process.
Finalizes the redemption dust threshold amount update process.
Can be called after the governance delay elapses.
Begins the redemption treasury fee divisor amount update process.
Finalizes the redemption treasury fee divisor amount update process.
Can be called after the governance delay elapses.
Begins the redemption tx max fee amount update process.
Finalizes the redemption tx max fee amount update process.
Can be called after the governance delay elapses.
Begins the redemption tx max total fee amount update process.
Finalizes the redemption tx max total fee amount update process.
Can be called after the governance delay elapses.
Begins the redemption timeout amount update process.
Finalizes the redemption timeout amount update process.
Can be called after the governance delay elapses.
Begins the redemption timeout slashing amount update process.
Finalizes the redemption timeout slashing amount update process.
Can be called after the governance delay elapses.
Begins the redemption timeout notifier reward multiplier amount update process.
Finalizes the redemption timeout notifier reward multiplier amount update process.
Can be called after the governance delay elapses.
Begins the moving funds tx max total fee amount update process.
Finalizes the moving funds tx max total fee amount update process.
Can be called after the governance delay elapses.
Begins the moving funds dust threshold amount update process.
Finalizes the moving funds dust threshold amount update process.
Can be called after the governance delay elapses.
Begins the moving funds timeout reset delay amount update process.
Finalizes the moving funds timeout reset delay amount update process.
Can be called after the governance delay elapses.
Begins the moving funds timeout amount update process.
Finalizes the moving funds timeout amount update process.
Can be called after the governance delay elapses.
Begins the moving funds timeout slashing amount update process.
Finalizes the moving funds timeout slashing amount update process.
Can be called after the governance delay elapses.
Begins the moving funds timeout notifier reward multiplier amount update process.
Finalizes the moving funds timeout notifier reward multiplier amount update process.
Can be called after the governance delay elapses.
Begins the moving funds commitment gas offset update process.
Finalizes the moving funds commitment gas offset update process.
Can be called after the governance delay elapses.
Begins the moved funds sweep tx max total fee amount update process.
Finalizes the moved funds sweep tx max total fee amount update process.
Can be called after the governance delay elapses.
Begins the moved funds sweep timeout amount update process.
Finalizes the moved funds sweep timeout amount update process.
Can be called after the governance delay elapses.
Begins the moved funds sweep timeout slashing amount update process.
Finalizes the moved funds sweep timeout slashing amount update process.
Can be called after the governance delay elapses.
Begins the moved funds sweep timeout notifier reward multiplier amount update process.
Finalizes the moved funds sweep timeout notifier reward multiplier amount update process.
Can be called after the governance delay elapses.
Begins the wallet creation period amount update process.
Finalizes the wallet creation period amount update process.
Can be called after the governance delay elapses.
Begins the wallet creation min btc balance amount update process.
Finalizes the wallet creation min btc balance amount update process.
Can be called after the governance delay elapses.
Begins the wallet creation max btc balance amount update process.
Finalizes the wallet creation max btc balance amount update process.
Can be called after the governance delay elapses.
Begins the wallet closure min btc balance amount update process.
Finalizes the wallet closure min btc balance amount update process.
Can be called after the governance delay elapses.
Begins the wallet max age amount update process.
Finalizes the wallet max age amount update process.
Can be called after the governance delay elapses.
Begins the wallet max btc transfer amount update process.
Finalizes the wallet max btc transfer amount update process.
Can be called after the governance delay elapses.
Begins the wallet closing period amount update process.
Finalizes the wallet closing period amount update process.
Can be called after the governance delay elapses.
Begins the fraud challenge deposit amount update process.
Finalizes the fraud challenge deposit amount update process.
Can be called after the governance delay elapses.
Begins the fraud challenge defeat timeout amount update process.
Finalizes the fraud challenge defeat timeout amount update process.
Can be called after the governance delay elapses.
Begins the fraud slashing amount update process.
Finalizes the fraud slashing amount update process.
Can be called after the governance delay elapses.
Begins the fraud notifier reward multiplier amount update process.
Finalizes the fraud notifier reward multiplier amount update process.
Can be called after the governance delay elapses.
Begins the treasury address update process.
It does not perform any parameter validation.
Finalizes the treasury address update process.
Can be called after the governance delay elapses.
governanceDelay
uint256
self
struct BridgeGovernanceParameters.DepositData
_newDepositDustThreshold
uint64
New deposit dust threshold amount.
self
struct BridgeGovernanceParameters.DepositData
_newDepositTreasuryFeeDivisor
uint64
New deposit treasury fee divisor amount.
self
struct BridgeGovernanceParameters.DepositData
_newDepositTxMaxFee
uint64
New deposit tx max fee amount.
self
struct BridgeGovernanceParameters.DepositData
_newDepositRevealAheadPeriod
uint32
New deposit reveal ahead period.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionDustThreshold
uint64
New redemption dust threshold amount.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionTreasuryFeeDivisor
uint64
New redemption treasury fee divisor amount.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionTxMaxFee
uint64
New redemption tx max fee amount.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionTxMaxTotalFee
uint64
New redemption tx max total fee amount.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionTimeout
uint32
New redemption timeout amount.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionTimeoutSlashingAmount
uint96
New redemption timeout slashing amount.
self
struct BridgeGovernanceParameters.RedemptionData
_newRedemptionTimeoutNotifierRewardMultiplier
uint32
New redemption timeout notifier reward multiplier amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsTxMaxTotalFee
uint64
New moving funds tx max total fee amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsDustThreshold
uint64
New moving funds dust threshold amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsTimeoutResetDelay
uint32
New moving funds timeout reset delay amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsTimeout
uint32
New moving funds timeout amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsTimeoutSlashingAmount
uint96
New moving funds timeout slashing amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsTimeoutNotifierRewardMultiplier
uint32
New moving funds timeout notifier reward multiplier amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovingFundsCommitmentGasOffset
uint16
New moving funds commitment gas offset.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovedFundsSweepTxMaxTotalFee
uint64
New moved funds sweep tx max total fee amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovedFundsSweepTimeout
uint32
New moved funds sweep timeout amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovedFundsSweepTimeoutSlashingAmount
uint96
New moved funds sweep timeout slashing amount.
self
struct BridgeGovernanceParameters.MovingFundsData
_newMovedFundsSweepTimeoutNotifierRewardMultiplier
uint32
New moved funds sweep timeout notifier reward multiplier amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletCreationPeriod
uint32
New wallet creation period amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletCreationMinBtcBalance
uint64
New wallet creation min btc balance amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletCreationMaxBtcBalance
uint64
New wallet creation max btc balance amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletClosureMinBtcBalance
uint64
New wallet closure min btc balance amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletMaxAge
uint32
New wallet max age amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletMaxBtcTransfer
uint64
New wallet max btc transfer amount.
self
struct BridgeGovernanceParameters.WalletData
_newWalletClosingPeriod
uint32
New wallet closing period amount.
self
struct BridgeGovernanceParameters.FraudData
_newFraudChallengeDepositAmount
uint96
New fraud challenge deposit amount.
self
struct BridgeGovernanceParameters.FraudData
_newFraudChallengeDefeatTimeout
uint32
New fraud challenge defeat timeout amount.
self
struct BridgeGovernanceParameters.FraudData
_newFraudSlashingAmount
uint96
New fraud slashing amount.
self
struct BridgeGovernanceParameters.FraudData
_newFraudNotifierRewardMultiplier
uint32
New fraud notifier reward multiplier amount.
self
struct BridgeGovernanceParameters.TreasuryData
_newTreasury
address
New treasury address.
function beginDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositDustThreshold) externalfunction finalizeDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) externalfunction beginDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTreasuryFeeDivisor) externalfunction finalizeDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) externalfunction beginDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTxMaxFee) externalfunction finalizeDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) externalfunction beginDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint32 _newDepositRevealAheadPeriod) externalfunction finalizeDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) externalfunction beginRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionDustThreshold) externalfunction finalizeRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTreasuryFeeDivisor) externalfunction finalizeRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxFee) externalfunction finalizeRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxTotalFee) externalfunction finalizeRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeout) externalfunction finalizeRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint96 _newRedemptionTimeoutSlashingAmount) externalfunction finalizeRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeoutNotifierRewardMultiplier) externalfunction finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) externalfunction beginMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsTxMaxTotalFee) externalfunction finalizeMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsDustThreshold) externalfunction finalizeMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutResetDelay) externalfunction finalizeMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeout) externalfunction finalizeMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovingFundsTimeoutSlashingAmount) externalfunction finalizeMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) externalfunction finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint16 _newMovingFundsCommitmentGasOffset) externalfunction finalizeMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovedFundsSweepTxMaxTotalFee) externalfunction finalizeMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeout) externalfunction finalizeMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovedFundsSweepTimeoutSlashingAmount) externalfunction finalizeMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) externalfunction finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) externalfunction beginWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletCreationPeriod) externalfunction finalizeWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMinBtcBalance) externalfunction finalizeWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMaxBtcBalance) externalfunction finalizeWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletClosureMinBtcBalance) externalfunction finalizeWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletMaxAge) externalfunction finalizeWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletMaxBtcTransfer) externalfunction finalizeWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletClosingPeriod) externalfunction finalizeWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) externalfunction beginFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudChallengeDepositAmount) externalfunction finalizeFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) externalfunction beginFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudChallengeDefeatTimeout) externalfunction finalizeFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) externalfunction beginFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudSlashingAmount) externalfunction finalizeFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) externalfunction beginFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudNotifierRewardMultiplier) externalfunction finalizeFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) externalfunction beginTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, address _newTreasury) externalfunction finalizeTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, uint256 governanceDelay) externalBridge 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.
struct BridgeState.Storage selfevent DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault)event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash)event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee)event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash)event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript)event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter)event MovingFundsTimeoutReset(bytes20 walletPubKeyHash)event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash)event MovingFundsTimedOut(bytes20 walletPubKeyHash)event MovingFundsBelowDustReported(bytes20 walletPubKeyHash)event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash)event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex)event NewWalletRequested()event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash)event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s)event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash)event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash)event VaultStatusUpdated(address vault, bool isTrusted)event SpvMaintainerStatusUpdated(address spvMaintainer, bool isTrusted)event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod)event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier)event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier)event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod)event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier)event TreasuryUpdated(address treasury)modifier onlySpvMaintainer()constructor() publicfunction initialize(address _bank, address _relay, address _treasury, address _ecdsaWalletRegistry, address payable _reimbursementPool, uint96 _txProofDifficultyFactor) externalInitializes upgradable contract on deployment.
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,
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.
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,
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,
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,
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.
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,
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
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
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,
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.
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,
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
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.
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,
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
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:
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.
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.
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.
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.
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
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.
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.
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))
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.
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.
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.
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,
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,
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.
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].
Updates treasury address. The treasury receives the system fees.
The treasury address must not be 0x0.
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.
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.
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.
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.
Gets details about a registered wallet.
Gets the public key hash of the active wallet.
Gets the live wallets count.
Returns the fraud challenge identified by the given key built as keccak256(walletPublicKey|sighash).
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.
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.
Returns the current values of Bridge deposit parameters.
Returns the current values of Bridge redemption parameters.
Returns the current values of Bridge moving funds between wallets parameters.
Returns the current values of Bridge fraud parameters.
Returns the addresses of contracts Bridge is interacting with.
Address where the deposit treasury fees will be sent to. Treasury takes part in the operators rewarding process.
The number of confirmations on the Bitcoin chain required to successfully evaluate an SPV proof.
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.
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.
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.
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.
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.
MovingFundsIf 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).
walletIDDkgResultSubmittedDkgResultApprovedWalletRegistryThe amount of time defined by redemptionTimeout must have passed since the redemption was requested (the request must be timed-out).
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.
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.
DkgResultApprovedWalletRegistrysweepProof 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.
membersIdsHashwalletIDDkgResultSubmittedDkgResultApprovedWalletRegistryThe active wallet BTC balance is above the maximum threshold.
Wallet can be challenged for the given signature only once.
membersIdsHashwalletIDDkgResultSubmittedDkgResultApprovedWalletRegistryThe amount of time indicated by challengeDefeatTimeout must pass after the challenge was reported.
Redemption timeout must be greater than zero,
Redemption timeout notifier reward multiplier must be in the range [0, 100].
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].
_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
function revealDeposit(struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) externalfundingTx
struct BitcoinTx.Info
Bitcoin funding transaction data, see BitcoinTx.Info.
reveal
struct Deposit.DepositRevealInfo
Deposit reveal data, see `RevealInfo struct.
function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) externalsweepTx
struct BitcoinTx.Info
Bitcoin sweep transaction data.
sweepProof
struct BitcoinTx.Proof
Bitcoin sweep proof data.
mainUtxo
function requestRedemption(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, bytes redeemerOutputScript, uint64 amount) externalwalletPubKeyHash
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
function receiveBalanceApproval(address balanceOwner, uint256 amount, bytes redemptionData) externalbalanceOwner
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
function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) externalredemptionTx
struct BitcoinTx.Info
Bitcoin redemption transaction data.
redemptionProof
struct BitcoinTx.Proof
Bitcoin redemption proof data.
mainUtxo
function notifyRedemptionTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) externalwalletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members.
redeemerOutputScript
function submitMovingFundsCommitment(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) externalwalletPubKeyHash
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
function resetMovingFundsTimeout(bytes20 walletPubKeyHash) externalwalletPubKeyHash
bytes20
20-byte public key hash of the moving funds wallet.
function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) externalmovingFundsTx
struct BitcoinTx.Info
Bitcoin moving funds transaction data.
movingFundsProof
struct BitcoinTx.Proof
Bitcoin moving funds proof data.
mainUtxo
function notifyMovingFundsTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs) externalwalletPubKeyHash
bytes20
20-byte public key hash of the wallet.
walletMembersIDs
uint32[]
Identifiers of the wallet signing group members.
function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) externalwalletPubKeyHash
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.
function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) externalsweepTx
struct BitcoinTx.Info
Bitcoin sweep funds transaction data.
sweepProof
struct BitcoinTx.Proof
Bitcoin sweep funds proof data.
mainUtxo
function notifyMovedFundsSweepTimeout(bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) externalmovingFundsTxHash
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
function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) externalactiveWalletMainUtxo
struct BitcoinTx.UTXO
Data of the active wallet's main UTXO, as currently known on the Ethereum chain.
function __ecdsaWalletCreatedCallback(bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) externalecdsaWalletID
bytes32
Wallet's unique identifier.
publicKeyX
bytes32
Wallet's public key's X coordinate.
publicKeyY
function __ecdsaWalletHeartbeatFailedCallback(bytes32, bytes32 publicKeyX, bytes32 publicKeyY) externalbytes32
publicKeyX
bytes32
Wallet's public key's X coordinate.
publicKeyY
function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) externalwalletPubKeyHash
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.
function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) externalwalletPubKeyHash
bytes20
20-byte public key hash of the wallet.
function submitFraudChallenge(bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external payablewalletPublicKey
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
function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) externalwalletPublicKey
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
function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) externalwalletPublicKey
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.
function notifyFraudChallengeDefeatTimeout(bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) externalwalletPublicKey
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
function setVaultStatus(address vault, bool isTrusted) externalvault
address
The address of the vault.
isTrusted
bool
flag indicating whether the vault is trusted or not.
function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) externalspvMaintainer
address
The address of the SPV maintainer.
isTrusted
bool
flag indicating whether the address is trusted or not.
function updateDepositParameters(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) externaldepositDustThreshold
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
function updateRedemptionParameters(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) externalredemptionDustThreshold
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%.
function updateMovingFundsParameters(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) externalmovingFundsTxMaxTotalFee
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.
function updateWalletParameters(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) externalfunction updateFraudParameters(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) externalfraudChallengeDepositAmount
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
function updateTreasury(address treasury) externaltreasury
address
New value of the treasury address.
function deposits(uint256 depositKey) external view returns (struct Deposit.DepositRequest)function pendingRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest)function timedOutRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest)function spentMainUTXOs(uint256 utxoKey) external view returns (bool)function wallets(bytes20 walletPubKeyHash) external view returns (struct Wallets.Wallet)walletPubKeyHash
bytes20
The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key).
[0]
struct Wallets.Wallet
Wallet details.
function activeWalletPubKeyHash() external view returns (bytes20)[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.
function liveWalletsCount() external view returns (uint32)[0]
uint32
The current count of wallets being in the Live state.
function fraudChallenges(uint256 challengeKey) external view returns (struct Fraud.FraudChallenge)function movedFundsSweepRequests(uint256 requestKey) external view returns (struct MovingFunds.MovedFundsSweepRequest)requestKey
uint256
Request key built as `keccak256(movingFundsTxHash
[0]
struct MovingFunds.MovedFundsSweepRequest
Details of the moved funds sweep request.
function isVaultTrusted(address vault) external view returns (bool)function depositParameters() external view returns (uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod)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
function redemptionParameters() external view returns (uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier)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%.
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)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.
function walletParameters() external view returns (uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod)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.
function fraudParameters() external view returns (uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier)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
function contractReferences() external view returns (contract Bank bank, contract IRelay relay, contract IWalletRegistry ecdsaWalletRegistry, contract ReimbursementPool reimbursementPool)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
function treasury() external view returns (address)function txProofDifficultyFactor() external view returns (uint256)Address of the Reimbursement Pool contract.
_txProofDifficultyFactor
uint96
The number of confirmations on the Bitcoin chain required to successfully evaluate an SPV proof.
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.
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.
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.
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.
bytes
The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH).
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.
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.
struct BitcoinTx.UTXO
Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain.
uint32[]
Identifiers of the wallet signing group members.
bytes32
Wallet's public key's Y coordinate.
bytes32
Wallet's public key's Y coordinate.
struct BitcoinTx.RSVSignature
Bitcoin signature in the R/S/V format.
bool
Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input.
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.
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.
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].
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].
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].
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.
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].
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].
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.
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].
contract IWalletRegistry
Address of the ECDSA Wallet Registry.
reimbursementPool
contract ReimbursementPool
Address of the Reimbursement Pool.