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.

Existing solutions that bridge Bitcoin to DeFi require users to send their Bitcoin to an intermediary, in exchange for an IOU token that represents the original asset. This centralized model requires you to trust a third party and is susceptible to censorship, threatening the premise of Bitcoin as sovereign, secure, permissionless digital asset.

In contrast, tBTC is a decentralized (and scalable) bridge between Bitcoin and DeFi. It provides Bitcoin holders secure and open access to the broader DeFi ecosystem, allowing you to unlock your Bitcoin’s value to borrow and lend, mint stablecoins, provide liquidity, and much more.

Honest Majority Assumption

Instead of centralized intermediaries, tBTC uses a randomly selected group of operators running nodes on the Threshold Network to secure deposited Bitcoin through threshold cryptography. 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 any wallet comprised of a quorum of dishonest operators (for a deeper discussion of the probability calculations, see ).

Fees

tBTC fees are action-based (i.e. users incur a mint and redemption fee when using the bridge). Currently, the mint fee is and the redemption fee is . The bridge fees can be changed through governance.

The T token is an ERC-20 token that powers tBTC and serves as the value accrual asset for the Threshold Network.

Supply

The initial supply of T was established by the DAO at launch as 10B T with the following allocation:

• 4.5B T allocated to NU token holders

• 4.5B T allocated to KEEP token holders

• 1B T allocated to the Threshold DAO treasury

An additional 1.155B tokens were minted during the network's inflationary bootstraping phase as incentives for stakers and node operators, resulting in a final total supply of 11,155,000,000 T tokens.

Supply Endpoints

• Supply API endpoint - https://api.threshold.network/supply/t

• Specific Values:

  • Total Supply - https://api.threshold.network/supply/t/total

  • Circulating Supply - https://api.threshold.network/supply/t/circulating

  • Treasury Supply - https://api.threshold.network/supply/t/treasury

Here you'll find the version of the Threshold dapp.

The client requires an Ethereum Key File of an Operator Account to connect to the Ethereum chain. This account is created in a subsequent step using Geth (GoEthereum).

The Ethereum Key File is expected to be encrypted with a password. The password has to be provided in a prompt after the client starts or configured as a KEEP_ETHEREUM_PASSWORD environment variable.

The Operator Account has to maintain a positive Ether balance at all times. We strongly advise you monitor the account and top-up when its balance gets below 0.5 Ether.

Install Geth (GoEthereum)

To create a new Ethereum account, install Geth (GoEthereum) and create a new account using the command below. This account will subsequently be referred to as the Operator Account.

geth account new --keystore /home/$USER/.operator-key

When prompted, provide a password to protect the operator key file.

Once the process completes, your public key will be displayed. Take note of your Operator Account public key.

Funding your Operator Account

Your Operator Account will need to maintain a positive ETH balance at all times to ensure proper operation and availability of your tBTC v2 node.

Logging

Configuration options for logging

Config File

Application configuration can be stored in a file and passed to the application with the --config flag.

CLI Options

Client Info

Client information exposed by the tBTC v2 client.

Configuration

Logging can be configured with environment variables. Please see sample settings:

LOG_LEVEL=DEBUG
IPFS_LOGGING_FMT=nocolor
GOLOG_FILE=/var/log/keep/keep.log
GOLOG_TRACING_FILE=/var/log/keep/trace.json

Before initializing the tBTC SDK instance in your project, you need to answer the following questions:

• What Bitcoin network and which tBTC contracts do you plan to interact with?

• Do you want to perform just read-only actions or send transactions as well?

Answering those questions will allow initializing the SDK in the right way. The SDK is prepared to handle common use cases but provides some flexibility as well. This guide explains that in detail.

Specific guides

IRelay

Contains only the methods needed by tBTC v2. The Bitcoin relay provides the difficulty of the previous and current epoch. One difficulty epoch spans 2016 blocks.

getCurrentEpochDifficulty

function getCurrentEpochDifficulty() external view returns (uint256)

Returns the difficulty of the current epoch.

getPrevEpochDifficulty

function getPrevEpochDifficulty() external view returns (uint256)

Returns the difficulty of the previous epoch.

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.

TBTC

constructor

constructor() public

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.

tBTC SDK is a TypeScript library that provides effortless access to the fundamental features of the tBTC Bitcoin bridge. The SDK allows developers to integrate tBTC into their own applications and offer the power of trustless tokenized Bitcoin to their users.

The SDK documentation consists of the following parts:

• Quickstart

• Architecture

• Guides

• API Reference

For a high-level overview of the tBTC protocol, please see the tBTC Bitcoin Bridge section.

The following diagram presents the architecture of the tBTC SDK and its place in the ecosystem:

As you can see, the SDK consists of several major parts:

• TBTC component

• Feature services

• Shared libraries

TBTC component

The TBTC component is the main entry point to the SDK. It provides different ways to initialize the SDK that are supposed to address the common use cases (see Initialize SDK guide to learn more). Moreover, the TBTC component gives access to the SDK core features through feature services as well as low-level direct access to the underlying tBTC smart contracts and Bitcoin network client.

Feature services

The role of the SDK feature services is to provide seamless access to the core features of the tBTC bridge. The most important feature services of the SDK are:

• Deposits: deposit and mint flow for BTC depositors

• Redemptions: unmint and redeem flow for TBTC redeemers

• Maintenance: authorized maintenance actions for maintainers (e.g. optimistic minting guardians)

Shared libraries

Shared libraries are reusable modules that provide cross-cutting concerns leveraged by multiple feature services and the TBTC component. The main shared libraries of the SDK are:

• Bitcoin: interfaces and utilities necessary to interact with the Bitcoin chain

• Contracts: chain-agnostic interfaces allowing to interact with tBTC smart contracts

• Electrum: Electrum-based implementation of the Bitcoin client

• Ethereum: implementations of tBTC smart contract interfaces for Ethereum chain

• Utils: general utility functions

Before you start

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 .) 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.

Start minting tBTC

🎉 You're ready to mint! Go to the tBTC app here: , and watch the tutorial video below:

Congrats — you minted!

🎉 You've successfully minted tBTC! 🎉

Here you can find instructions explaining how to use the SDK in your own project.

Installation

To install the tBTC SDK in your project, run:

Please note that you will also need to install the library to initialize a signer or provider. To do so, invoke:

Usage

Here is a brief example demonstrating the use of the SDK in Ethereum:

Crosschain

Here is a brief example demonstrating the use of the SDK in some L2, e.g. Arbitrum:

Errors in Logs or Console

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.

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.

Create folders for tBTC v2 client

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.

Copy Operator keystore file

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

Another core feature of the tBTC bridge is unminting (burning) TBTC tokens and redeeming BTC in return. This guide explains how to perform this process using the SDK.

Initialize the SDK

First, initialize the SDK, as described in the guide.

Request redemption

Once the SDK is initialized, you can unmint and request for redemption in the following way:

EcdsaLib

compressPublicKey

Converts public key X and Y coordinates (32-byte each) to a compressed public key (33-byte). Compressed public key is X coordinate prefixed with 02 or 03 based on the Y coordinate parity. It is expected that the uncompressed public key is stripped (i.e. it is not prefixed with 04).

Parameters

Return Values

Required Ports

The node has to be accessible publicly to establish and maintain connections with bootstrap nodes and discovered peers. The node exposes metrics and diagnostics services for network health monitoring purposes. Update firewall rules as necessary, including application level firewalls for the following ports

Announced Addresses

An Announced Address is a layered addressing information (multiaddress/multiaddr) announced to the Threshold Network that is used by peers to connect with your node, e.g.: /dns4/bootstrap-0.test.keep.network/tcp/3919 or /ip4/104.154.61.116/tcp/3919.

If the machine you’re running your node is not exposing a public IP (e.g. it is behind NAT) you should set the network.AnnouncedAddresses (flag: --network.announcedAddresses) configuration property to addresses (ip4 or dns4) under which your node is reachable for the public.

To read more about multiaddress see the .

IVault

IVault is an interface for a smart contract consuming Bank balances of other contracts or externally owned accounts (EOA).

receiveBalanceIncrease

Called by the Bank in increaseBalanceAndCall function after increasing the balance in the Bank for the vault. It happens in the same transaction in which deposits were swept by the Bridge. This allows the depositor to route their deposit revealed to the Bridge to the particular smart contract (vault) in the same transaction in which the deposit is revealed. This way, the depositor does not have to execute additional transaction after the deposit gets swept by the Bridge to approve and transfer their balance to the vault.

The implementation must ensure this function can only be called by the Bank. The Bank guarantees that the vault's balance was increased by the sum of all deposited amounts before this function is called, in the same transaction.

Parameters

You can learn about APIs of contracts related to ECDSA under the following links:

Please review this document in its entirety prior to beginning setup of your node to familiarize yourself with the general setup process.

Important Considerations

The Threshold Network expects certain capabilities for each node running on the network. To help attain these capabilities consider the following criteria:

• It is paramount that tBTC v2 nodes remain available to the Network. We strongly encourage a stable and redundant internet connection.

• Equally important is machine uptime and reliability. A VPS is strongly recommended.

• A connection to a production grade self-hosted or third party Ethereum node deployment.

• Persistent and redundant storage that will survive a VM or container rotation, and a disk failure.

• Each node running on the network requires a unique Ethereum Operator Account. The account has to maintain a positive Ether balance at all times.

• Each node running on the network requires a unique IP address or a unique application port running under the same IP.

Recommended Machine Types

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.

Ethereum API

A Keep Node requires a connection to a WebSocket Ethereum API. You should obtain a WS API URL from a service provider (e.g. Alchemy, Infura, Ankr) or run your own Ethereum node (e.g. Geth).

Bitcoin API

Starting from version v2.0.0-m3 , the Keep Node interacts with the Bitcoin network through an Electrum protocol server. You can use one of the publicly available servers or run your own. The URL of the chosen server should be passed under the bitcoin.electrum section of the configuration. If no Electrum server is set explicitly in the bitcoin.electrum configuration section, the Keep Node will randomly pick one server from its embedded server list, appropriate for the Bitcoin network the Keep Node is currently running against.

Configuration

The client expects configuration options to be passed as CLI flags or specified in a config file. If you specify an option by using a parameter on the command line, it will override the value read from the configuration file.

Mainnet

The SDK addresses it by exposing the TBTC.initializeMainnet function. That function:

• Takes an Ethers signer or provider as a parameter and uses it to interact with tBTC contracts deployed on Ethereum mainnet

• Needs to receive as a second parameter the value true to activate the crosschain mode.

• Automatically configures an Electrum Bitcoin client to communicate with the Bitcoin mainnet (communication is done through a set of pre-configured Electrum servers)

The following code snippet presents the usage of this function:

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. 

Testnet

The SDK addresses it by exposing the TBTC.initializeSepolia function. That function:

• Takes an Ethers signer or provider as a parameter and uses it to interact with tBTC contracts deployed on Ethereum Sepolia

• Needs to receive as a second parameter the value true to activate the crosschain mode.

• Automatically configures an Electrum Bitcoin client to communicate with the Bitcoin testnet (communication is done through a set of pre-configured Electrum servers)

The usage of this function is exactly the same as for the previous TBTC.initializeMainnet function.

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. 

IReceiveBalanceApproval

IReceiveBalanceApproval is an interface for a smart contract consuming Bank balances approved to them in the same transaction by other contracts or externally owned accounts (EOA).

receiveBalanceApproval

function receiveBalanceApproval(address owner, uint256 amount, bytes extraData) external

Called by the Bank in approveBalanceAndCall function after the balance owner approved amount of their balance in the Bank for the contract. This way, the depositor can approve balance and call the contract to use the approved balance in a single transaction.

The implementation must ensure this function can only be called by the Bank. The Bank does not guarantee that the amount approved by the owner currently exists on their balance. That is, the owner could approve more balance than they currently have. This works the same as Bank.approve function. The contract must ensure the actual balance is checked before performing any action based on it.

Parameters

GovernanceUtils

onlyAfterGovernanceDelay

function onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view

Reverts if the governance delay has not passed since the change initiated time or if the change has not been initiated.

Parameters

getRemainingGovernanceDelay

function getRemainingGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view returns (uint256)

Gets the time remaining until the governable parameter update can be committed.

Parameters

Return Values

Heartbeat

The library establishes expected format for heartbeat messages signed by wallet ECDSA signing group. Heartbeat messages are constructed in such a way that they can not be used as a Bitcoin transaction preimages.

The smallest Bitcoin non-coinbase transaction is a one spending an OP_TRUE anyonecanspend output and creating 1 OP_TRUE anyonecanspend output. Such a transaction has 61 bytes (see BitcoinTx documentation): 4 bytes for version 1 byte for tx_in_count 36 bytes for tx_in.previous_output 1 byte for tx_in.script_bytes (value: 0) 0 bytes for tx_in.signature_script 4 bytes for tx_in.sequence 1 byte for tx_out_count 8 bytes for tx_out.value 1 byte for tx_out.pk_script_bytes 1 byte for tx_out.pk_script 4 bytes for lock_time

The smallest Bitcoin coinbase transaction is a one creating 1 OP_TRUE anyonecanspend output and having an empty coinbase script. Such a transaction has 65 bytes: 4 bytes for version 1 byte for tx_in_count 32 bytes for tx_in.hash (all 0x00) 4 bytes for tx_in.index (all 0xff) 1 byte for tx_in.script_bytes (value: 0) 4 bytes for tx_in.height 0 byte for tx_in.coinbase_script 4 bytes for tx_in.sequence 1 byte for tx_out_count 8 bytes for tx_out.value 1 byte for tx_out.pk_script_bytes 1 byte for tx_out.pk_script 4 bytes for lock_time

A SIGHASH flag is used to indicate which part of the transaction is signed by the ECDSA signature. There are currently 3 flags: SIGHASH_ALL, SIGHASH_NONE, SIGHASH_SINGLE, and different combinations of these flags.

No matter the SIGHASH flag and no matter the combination, the following fields from the transaction are always included in the constructed preimage: 4 bytes for version 36 bytes for tx_in.previous_output (or tx_in.hash + tx_in.index for coinbase) 4 bytes for lock_time

Additionally, the last 4 bytes of the preimage determines the SIGHASH flag.

This is enough to say there is no way the preimage could be shorter than 4 + 36 + 4 + 4 = 48 bytes.

For this reason, we construct the heartbeat message, as a 16-byte message. The first 8 bytes are 0xffffffffffffffff. The last 8 bytes are for an arbitrary uint64, being a signed heartbeat nonce (for example, the last Ethereum block hash).

The message being signed by the wallet when executing the heartbeat protocol should be Bitcoin's hash256 (double SHA-256) of the heartbeat message: heartbeat_sighash = hash256(heartbeat_message)

isValidHeartbeatMessage

function isValidHeartbeatMessage(bytes message) internal pure returns (bool)

Determines if the signed byte array is a valid, non-fraudulent heartbeat message.

Wallet heartbeat message must be exactly 16 bytes long with the first 8 bytes set to 0xffffffffffffffff.

Parameters

Return Values

The client exposes metrics and diagnostics on a configurable port (default: 9601) under /metrics and /diagnostics resources.

The data can be consumed by Prometheus to monitor the state of a node.

Metrics

The client exposes the following metrics:

• connected peers count,

• connected bootstraps count,

• Ethereum client connectivity status (if a simple read-only CALL can be executed).

Metrics are enabled once the client starts. It is possible to customize the port at which metrics endpoint is exposed as well as the frequency with which the metrics are collected.

Exposed metrics contain the value and timestamp at which they were collected.

Example metrics endpoint call result:

$ curl localhost:9601/metrics
# TYPE connected_peers_count gauge
connected_peers_count 108 1623235129569

# TYPE connected_bootstrap_count gauge
connected_bootstrap_count 10 1623235129569

# TYPE eth_connectivity gauge
eth_connectivity 1 1623235129789

Diagnostics

The client exposes the following diagnostics:

• list of connected peers along with their network id and Ethereum operator address,

• information about the client’s network id and Ethereum operator address.

Diagnostics are enabled once the client starts. It is possible to customize the port at which diagnostics endpoint is exposed.

Example diagnostics endpoint call result:

$ curl localhost:9601/diagnostics
{
  "client_info" {
   "ethereum_address":"0xDcd4199e22d09248cA2583cBDD2759b2acD22381",
   "network_id":"16Uiu2HAkzYFHsqbwt64ZztWWK1hyeLntRNqWMYFiZjaKu1PZgikN"
  },
  "connected_peers": [
    {"ethereum_address":"0x3712C6fED51CECA83cA953f6FF3458f2339436b4","network_id":"16Uiu2HAkyYtzNoWuF3ULaA7RMfVAxvfQQ9YRvRT3TK4tXmuZtaWi"},
    {"ethereum_address":"0x4bFa10B1538E8E765E995688D8EEc39C717B6797","network_id":"16Uiu2HAm9d4MG4LNrwkFmugD2pX7frm6ZmA4vE3EFAEjk7yaoeLd"},
    {"ethereum_address":"0x650A9eD18Df873cad98C88dcaC8170531cAD2399","network_id":"16Uiu2HAkvjVWogUk2gq6VTNLQdFoSHXYpobJdZyuAYeoWD66e8BD"},
    ...
  ]
}

Committee Multisigs

Lifecycle of a successful proposal

1. Forum discussion: A Threshold community member posts a potential proposal on the Threshold governance forums. Community members who post the initial proposal are encouraged to get active in Meta governance discussions within the community on forums and in Discord to earn support for the proposal. There is no minimum token threshold required to create a new proposal on the forums. Community mods reserve the right to moderate spam proposals during this stage by deleting the proposal from the forums.

2. Temperature Check: Once a potential proposal has enough traction and discussion within the community, it can proceed for a temperature check via an off-chain snapshot. If a proposal receives majority support during the temperature check, it is eligible to move onto the next step.

3. Proposal Creation: A community member holding enough vote weight (at least 0.25% of T total supply) submits the proposal on-chain. The proposal enters a 2-day delay period before voting officially begins.

4. Vote Period: Proposal voting remains open for 10 days. If the proposal passes with enough quorum (at least 1.5% of T total supply), it moves onto the next step; if the proposal fails, it is canceled. Creators and supporters of the proposal may bring a modified proposal forward again but it must be sufficiently different and pass requirements outlined in previous steps.

5. Timelock Period: Once a proposal is approved, the Governor Bravo smart contracts include an additional timelock delay of 2 days. Anyone can interact with the Governor Bravo smart contracts to queue an approved proposal into the Timelock contract.

6. Execution: After the timelock delay, anyone can execute an approved proposal.

Deviations in the proposal lifecycle

• Committee vetos: During the on-chain phase, the Elected Committee can veto any proposal. This is intended to be an extra security mechanism in the event that a dangerous proposal passes.

• Late quorum prevention: The 10-days voting period is automatically extended when quorum is reached late, to prevent governance attacks that try to reach quorum at the last minute; in case a proposal reaches quorum less than 2 days before the deadline, the proposal deadline is extended for 2 more days from the moment the quorum was reached.

• Off-chain proposals: Some proposals do not imply any on-chain action (e.g. Council and Guild elections). In these cases, there is a Snapshot vote that takes 5 days for regular proposals and 7 days for elections, with no associated on-chain proposal.

The main feature of the tBTC bridge is depositing BTC and using it to mint the ERC-20 TBTC token. This guide explains how to perform this process using the SDK.

Initialize the SDK

First, initialize the SDK, as described in the guide.

Initiate the deposit

Once the SDK is initialized, you can initiate the deposit and get their Bitcoin address in the following way:

Make the Bitcoin deposit transaction

The next step is doing the actual Bitcoin deposit transaction to the deposit address. There are two possible ways to do so:

• Recommended: Use an external Bitcoin wallet

• Non-recommended: Use the experimental SDK component. This code is used for testing purposes and is not safe for production use!

Initiate minting

Once the Bitcoin deposit transaction is done, minting can be initiated. This can be done using the initiateMinting method exposed by the Deposit class. This method has two modes:

• Automatic: Automatically detect the latest funding UTXO and use it to initiate minting. This mode is the default one that should be used when a single Bitcoin deposit transaction has been made.

• Manual: Take a funding UTXO as a parameter and use it to initiate minting. This mode can be useful when multiple Bitcoin deposit transactions target the same deposit address.

Here is an example of both:

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:

IWalletOwner

__ecdsaWalletCreatedCallback

Callback function executed once a new wallet is created.

Should be callable only by the Wallet Registry.

Parameters

__ecdsaWalletHeartbeatFailedCallback

Callback function executed once a wallet heartbeat failure is detected.

Should be callable only by the Wallet Registry.

Parameters

DonationVault

Vault that allows making BTC donations to the system. Upon deposit, this vault does not increase depositors' balances and always decreases its own balance in the same transaction. The vault also allows making donations using existing Bank balances.

BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE. USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING!

bank

contract Bank bank

DonationReceived

event DonationReceived(address donor, uint256 donatedAmount)

onlyBank

modifier onlyBank()

constructor

constructor(contract Bank _bank) public

donate

function donate(uint256 amount) external

Transfers the given amount of the Bank balance from the caller to the Donation Vault and immediately decreases the vault's balance in the Bank by the transferred amount.

Requirements:

• The caller's balance in the Bank must be greater than or equal to the amount,

• Donation Vault must have an allowance for caller's balance in the Bank for at least amount.

Parameters

receiveBalanceApproval

function receiveBalanceApproval(address owner, uint256 amount, bytes) external

Transfers the given amount of the Bank balance from the owner to the Donation Vault and immediately decreases the vault's balance in the Bank by the transferred amount.

Requirements:

• Can only be called by the Bank via approveBalanceAndCall,

• The owner balance in the Bank must be greater than or equal to the amount.

Parameters

receiveBalanceIncrease

function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external

Ignores the deposited amounts and does not increase depositors' individual balances. The vault decreases its own tBTC balance in the Bank by the total deposited amount.

Requirements:

• Can only be called by the Bank after the Bridge swept deposits and Bank increased balance for the vault,

• The depositors array must not be empty,

• The depositors array length must be equal to the depositedAmounts array length.

Parameters

Docker Installation

The following instructions assume your docker install followed these installation instructions.

docker pull keepnetwork/keep-client:latest

sudo systemctl restart tbtcv2

sudo docker container prune

sudo docker image prune

sudo docker ps

sudo docker logs stinky_brownie >& /path/to/output/file

cat /path/to/output/file

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

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                     |
-----------------------------------------------------------------------------------

http://111.222.333.444:9601/metrics

client_info{version="vX.X.X-XX"}

You can learn about APIs of contracts related to the Bridge under the following links:

Bank

BitcoinTx

Bridge

BridgeGovernance

BridgeGovernanceParameters

BridgeState

Deposit

DepositSweep

DonationVault

EcdsaLib

Fraud

GovernanceUtils

Heartbeat

IReceiveBalanceApproval

IRelay

IVault

L2TBTC

L2WormholeGateway

LightRelay

LightRelayMaintainerProxy

MaintainerProxy

MovingFunds

Redemption

TBTC

TBTCOptimisticMinting

TBTCVault

VendingMachine

VendingMachineV2

VendingMachineV3

WalletCoordinator

Wallets

Protocol Upgrades

Defense by Thesis - Gasless Minting Feature for the Threshold App

Date: 31 Oct 2025

Report: View PDF

Scope: NativeBTCDepositor contract

Defense by Thesis - Beta Staker Allowlist & Bridge Fee Rebates

• Date: 16 Sept 2025

• Report: View PDF

• Scope: See related proposals, TIP-067 and TIP-106

Cross-Chain Integrations

Certora - Threshold CCIP Update

• Date: 25 Sept 2025

• Report: View PDF

• Scope: Threshold CCIP Update

MixBytes() - Cross-Chain Redemptions

• Date: 08 Sept 2025

• Report: View PDF

• Scope: Cross-chain bridge transfers

Zellic – Sui Integration (tBTC)

• Date: 01 May 2025

• Report: View PDF

• Scope: tBTC integration with the Sui blockchain

Hashlock – Starknet Integration (tBTC)

• Date: April 2025

• Report: View PDF

• Scope: tBTC integration with the StarkNet blockchain

Thesis Defense – Base Integration (tBTC)

• Date: April 11th, 2024

• Report: View PDF

• Scope: tBTC integration with the Base blockchain

tBTC Bridge Audits

Least Authority – Solana Smart Contracts (tBTC)

• Date: 29 August 2023

• Report: View Audit PDF - Link to Least Authority

• Scope: Smart contracts for the tBTC Bridge on Solana

Least Authority – tBTC Bridge

• Date: 29 September 2022

• Report: View Audit PDF - Link to Least Authority

• Scope: Security audit of the core tBTC Bridge contracts

T Vending Machine Audits

CertiK – Vending Machine

• Date: 19 November 2021

• Report: View Audit PDF - Link to CertiK

• Scope: Vending machine security audit

ChainSecurity – Staking, T Token, and Vending Machine

• Date: 09 November 2021

• Report: View Audit PDF - Link to ChainSecurity

• Scope: Staking contracts, T token logic, and vending machine mechanisms

Download the Binary

See GitHub for the latest release:

Under Assets, copy the path to the compressed binary and use the command below to download the file. Make relevant adjustments to version as necessary:

After the download completes, use the command below to display the contents of the folder:

Extract the compressed file:

Configure tBTC v2 Client

To launch the tBTC v2 client, several configuration flags and environmental values need to be set. For simplicity, a bash script can be used rather than typing or pasting all the flags into the console.

The following flags must be set at minimum:

For a complete list of client commands and flags, see .

To launch the client, execute the following:

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.

This function allows setting up the SDK to work with custom tBTC smart contracts and custom Bitcoin network. For example, it can be used to address the following use cases:

Using locally deployed tBTC contracts and local Bitcoin network

This is the common case when you are setting up a development environment. Let's suppose you have deployed the tBTC contracts on your local Ethereum chain and you are using a . The following snippet demonstrates SDK initialization in that case:

Using a custom Bitcoin client instead of the automatically configured one

In some cases, you may want to initialize the SDK for mainnet/testnet, but point the Electrum Bitcoin client to your own server. Here is how you can do that:

You can even use another (non-Electrum) Bitcoin client implementation. This is how you can achieve that:

Using mock tBTC contracts and mock Bitcoin network

Sometimes, you may also want to initialize the SDK with mock tBTC contracts and Bitcoin network for testing purposes. This can be done as follows:

VendingMachineV2

VendingMachineV2 is used to exchange tBTC v1 to tBTC v2 in a 1:1 ratio during the process of tBTC v1 bridge sunsetting. The redeemer selected by the DAO based on the "TIP-027b tBTC v1: The Sunsetting" proposal will deposit tBTC v2 tokens into VendingMachineV2 so that outstanding tBTC v1 token owners can upgrade to tBTC v2 tokens. The redeemer will withdraw the tBTC v1 tokens deposited into the contract to perform tBTC v1 redemptions. The redeemer may decide to withdraw their deposited tBTC v2 at any moment in time. The amount withdrawable is lower than the amount deposited in case tBTC v1 was exchanged for tBTC v2. This contract is owned by the redeemer.

tbtcV1

tbtcV2

Exchanged

Deposited

Withdrawn

constructor

exchange

Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. The caller needs to have at least amount of tBTC v1 balance approved for transfer to the VendingMachineV2 before calling this function.

Parameters

receiveApproval

Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. The caller needs to have at least amount of tBTC v1 balance approved for transfer to the VendingMachineV2 before calling this function.

This function is a shortcut for approve + exchange. Only tBTC v1 token caller is allowed and only tBTC v1 is allowed as a token to transfer.

Parameters

depositTbtcV2

Allows to deposit tBTC v2 tokens to the contract. VendingMachineV2 can not mint tBTC v2 tokens so tBTC v2 needs to be deposited into the contract so that tBTC v1 to tBTC v2 exchange can happen. The caller needs to have at least amount of tBTC v2 balance approved for transfer to the VendingMachineV2 before calling this function.

This function is for the redeemer and tBTC v1 operators. This is NOT a function for tBTC v1 token holders.

Parameters

withdrawFunds

Allows the contract owner to withdraw tokens. This function is used in two cases: 1) when the redeemer wants to redeem tBTC v1 tokens to perform tBTC v2 redemptions; 2) when the deadline for tBTC v1 -> tBTC v2 exchange passed and the redeemer wants their tBTC v2 back.

This function is for the redeemer. This is NOT a function for tBTC v1 token holders.

Parameters

_exchange

EcdsaInactivity

Claim

groupThreshold

The minimum number of wallet signing group members needed to interact according to the protocol to produce a valid inactivity claim.

signatureByteSize

Size in bytes of a single signature produced by member supporting the inactivity claim.

verifyClaim

Verifies the inactivity claim according to the rules defined in Claim struct documentation. Reverts if verification fails.

Wallet signing group members hash is validated upstream in WalletRegistry.notifyOperatorInactivity()

Parameters

Return Values

validateMembersIndices

Validates members indices array. Array is considered valid if its size and each single index are in [1, groupSize] range, indexes are unique, and sorted in an ascending order. Reverts if validation fails.

Parameters

LightRelayMaintainerProxy

The proxy contract that allows the relay maintainers to be refunded for the spent gas from the ReimbursementPool. When proving the next Bitcoin difficulty epoch, the maintainer calls the LightRelayMaintainerProxy which in turn calls the actual LightRelay contract.

lightRelay

isAuthorized

Stores the addresses that can maintain the relay. Those addresses are attested by the DAO.

The goal is to prevent a griefing attack by frontrunning relay maintainer which is responsible for retargetting the relay in the given round. The maintainer's transaction would revert with no gas refund. Having the ability to restrict maintainer addresses is also important in case the underlying relay contract has authorization requirements for callers.

retargetGasOffset

Gas that is meant to balance the retarget overall cost. Can be

LightRelayUpdated

MaintainerAuthorized

MaintainerDeauthorized

RetargetGasOffsetUpdated

onlyRelayMaintainer

onlyReimbursableAdmin

constructor

updateLightRelay

Allows the governance to upgrade the LightRelay address.

The function does not implement any governance delay and does not check the status of the LightRelay. The Governance implementation needs to ensure all requirements for the upgrade are satisfied before executing this function.

authorize

Authorizes the given address as a maintainer. Can only be called by the owner and the address of the maintainer must not be already authorized.

The function does not implement any governance delay.

Parameters

deauthorize

Deauthorizes the given address as a maintainer. Can only be called by the owner and the address of the maintainer must be authorized.

The function does not implement any governance delay.

Parameters

updateRetargetGasOffset

Updates the values of retarget gas offset.

Can be called only by the contract owner. The caller is responsible for validating the parameter. The function does not implement any governance delay.

Parameters

retarget

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.

Threshold Network allow-lists authorized signers to participate in tBTC minting, redemptions, and custody. These signers ensure key operations run properly without interruptions.

A few notable professional staking providers can be found requesting DAO approval here.

Signers nodes form a permissioned set that is 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 activity and overall network health please visit tbtcscan.com/operators or check status.threshold.network. These resources provide up-to-date statistics on node counts and operational metrics.

General requirements

Running a Signer node is a long-term commitment.

Operators of Signer nodes are expected to be extremely responsive. Ideally, they should be able to upgrade their nodes within 24 hours of notification.

Operators of Signer nodes must be technically capable. They are responsible for ensuring high availability (more than 96% uptime) and security of the node.

Technical requirements

A Signer node performs relatively computationally expensive operations (DKG, threshold signing, etc). To ensure a high level of service, a Signer node requires a machine with:

• 4 CPUs

• 4 GB of RAM

• 1 GB of persistent disk space

• 80 Mbps of network bandwidth

• Linux OS

In addition to the above:

• The underlying machine’s operating system and tools must be up to date, especially regarding recent security patches.

• Backups of the persistent disk must be performed on an ongoing basis. This is crucial to ensure the safety of mission-critical data (e.g. key material). The usage of an additional encryption layer for backups is highly recommended.

• The network layer must provide a unique public IPv4 address allowing the node to be reached from the external network. A proper firewall configuration must be in place and ensure a safe perimeter allowing inbound traffic on two ports (communication and diagnostics). The internet connection must be stable and failover scenarios must be taken into account.

• A Signer node requires access to an Ethereum node. It is highly recommended to set up a private Ethereum stack (e.g. Geth + Prysm) and use public providers as failover (e.g. Alchemy, Infura, etc). Such a setup is crucial for network diversity and decentralization as it helps avoid the single-point-of-failure risk associated with public providers. Signers should use their own judgement for selecting stack components. Specific technical requirements for a private Ethereum stack depend on the software used. For example, a stack based on Geth + Prysm requires 4 CPU / 16 GB RAM / 2 TB SSD.

• 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 failover. The reasons are exactly the same as for a private Ethereum stack. Signers should use their own judgement 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 judgement for selecting stack components. Specific technical requirements for a monitoring stack depend on the software used. For example, a stack based on Grafana + Prometheus requires 2 CPU / 4 GB RAM / 20 GB HDD.

Cost estimation

The actual monthly costs of running a Signer node depends on the hosting model (VPS vs self-hosting) and infrastructure configuration. The following estimation aims to provide a ballpark figure. It also assumes that all aforementioned technical requirements and recommendations are taken into account.

Key system assumptions

• Signer node requires 4 CPUs / 4 GB RAM / 1 GB HDD

• Ethereum stack requires 4 CPUs / 16 GB RAM / 2 TB SSD

• Bitcoin stack requires 8 CPUs / 16 GB RAM / 2 TB SSD

• Monitoring stack requires 2 CPUs / 4 GB RAM / 20 GB HDD

• External storage for backups (node and auxiliary stacks) is 1 TB HDD

• Network layer ensures 100 Mbps of bandwidth and includes all necessary equipment (firewall, public IPs, etc)

The above assumptions can be used to divide costs into 4 categories:

1. Computing costs: This category includes the costs of running 18 CPUs and 40 GB RAM in total. There are a number of possible configurations to provide such computing capacity. Using the VPS-based model as an example, the cost of 3x 8CPU/16GB VMs on leading cloud service providers starts from ~$400/month.

2. Storage costs: This category includes the costs of using 4 TB SSD and ~1 TB HDD of storage in total. For the VPS-based model, part of this cost is often included in the cost of VMs, but some providers charge for the storage separately with rates like ~$0.08/GB (e.g., Amazon EBS). In that case, it is safe to assume that storage costs start from ~$200/month.

3. Network costs: This category includes the cost of 100 Mbps of bandwidth and all auxiliary equipment and features like a firewall or public IPs. For the VPS-based model, such bandwidth is often provided out of the box with the VMs, but a firewall and public IPs may be charged separately. Moreover, some providers may apply an additional charge on egress traffic. It is safe to assume that network costs start from ~$50/month.

4. Other costs: This category includes all maintenance and other costs depending on the hosting model and infrastructure configuration. For the VPS-based model, such costs can be OS licenses, automatic backup, additional management tools, and so on. For the self-hosting model, these can be costs of internet connection, power failover (e.g., UPS), auxiliary network equipment, and similar. This category of costs must be factored into the total monthly cost.

Bottom Line

In summary, the cost for running a Signer node using the VPS-based model starts at approximately $650/month. Assuming a safety margin for other costs, a rough cost estimate is $800/month for running a setup in accordance with the technical requirements and recommendations.

Estimating the general cost for the self-hosting model is non-trivial due to the variety of possible configurations. The total monthly cost can be similar to the VPS-based model but may also incur additional hidden costs such as hardware maintenance

Disclaimer

Above assumptions and figures should be used cautiously as it is only intended to provide a general sense of the 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.

Deposit

The library handles the logic for revealing Bitcoin deposits to the Bridge.

The depositor puts together a P2SH or P2WSH address to deposit the funds. This script is unique to each depositor and looks like this:

<depositorAddress> DROP
<blindingFactor> DROP
DUP HASH160 <walletPubKeyHash> EQUAL
IF
CHECKSIG
ELSE
DUP HASH160 <refundPubkeyHash> EQUALVERIFY
<refundLocktime> CHECKLOCKTIMEVERIFY DROP
CHECKSIG
ENDIF

Since each depositor has their own Ethereum address and their own blinding factor, each depositor’s script is unique, and the hash of each depositor’s script is unique.

DepositRevealInfo

struct DepositRevealInfo {
  uint32 fundingOutputIndex;
  bytes8 blindingFactor;
  bytes20 walletPubKeyHash;
  bytes20 refundPubKeyHash;
  bytes4 refundLocktime;
  address vault;
}

DepositRequest

struct DepositRequest {
  address depositor;
  uint64 amount;
  uint32 revealedAt;
  address vault;
  uint64 treasuryFee;
  uint32 sweptAt;
}

DepositRevealed

event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault)

revealDeposit

function revealDeposit(struct BridgeState.Storage self, struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external

Used by the depositor to reveal information about their P2(W)SH Bitcoin deposit to the Bridge on Ethereum chain. The off-chain wallet listens for revealed deposit events and may decide to include the revealed deposit in the next executed sweep. Information about the Bitcoin deposit can be revealed before or after the Bitcoin transaction with P2(W)SH deposit is mined on the Bitcoin chain. Worth noting, the gas cost of this function scales with the number of P2(W)SH transaction inputs and outputs. The deposit may be routed to one of the trusted vaults. When a deposit is routed to a vault, vault gets notified when the deposit gets swept and it may execute the appropriate action.

Requirements:

• This function must be called by the same Ethereum address as the one used in the P2(W)SH BTC deposit transaction as a depositor,

• reveal.walletPubKeyHash must identify a Live wallet,

• reveal.vault must be 0x0 or point to a trusted vault,

• reveal.fundingOutputIndex must point to the actual P2(W)SH output of the BTC deposit transaction,

• reveal.blindingFactor must be the blinding factor used in the P2(W)SH BTC deposit transaction,

• reveal.walletPubKeyHash must be the wallet pub key hash used in the P2(W)SH BTC deposit transaction,

• reveal.refundPubKeyHash must be the refund pub key hash used in the P2(W)SH BTC deposit transaction,

• reveal.refundLocktime must be the refund locktime used in the P2(W)SH BTC deposit transaction,

• BTC deposit for the given fundingTxHash, fundingOutputIndex can be revealed only one time.

If any of these requirements is not met, the wallet must refuse to sweep the deposit and the depositor has to wait until the deposit script unlocks to receive their BTC back.

Parameters

validateDepositRefundLocktime

function validateDepositRefundLocktime(struct BridgeState.Storage self, bytes4 refundLocktime) internal view

Validates the deposit refund locktime. The validation passes successfully only if the deposit reveal is done respectively earlier than the moment when the deposit refund locktime is reached, i.e. the deposit become refundable. Reverts otherwise.

Requirements:

• refundLocktime as integer must be >= 500M

• refundLocktime must denote a timestamp that is at least depositRevealAheadPeriod seconds later than the moment of block.timestamp

Parameters

IWalletRegistry

requestNewWallet

Requests a new wallet creation.

Only the Wallet Owner can call this function.

closeWallet

Closes an existing wallet.

Only the Wallet Owner can call this function.

Parameters

seize

Adds all signing group members of the wallet with the given ID to the slashing queue of the staking contract. The notifier will receive reward per each group member from the staking contract notifiers treasury. The reward is scaled by the rewardMultiplier provided as a parameter.

Only the Wallet Owner can call this function. Requirements:

• The expression keccak256(abi.encode(walletMembersIDs)) must be exactly the same as the hash stored under membersIdsHash for the given walletID. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate DkgResultSubmitted and DkgResultApproved events.

• rewardMultiplier must be between [0, 100].

• This function does revert if staking contract call reverts. The calling code needs to handle the potential revert.

Parameters

getWalletPublicKey

Gets public key of a wallet with a given wallet ID. The public key is returned in an uncompressed format as a 64-byte concatenation of X and Y coordinates.

Parameters

Return Values

getWalletCreationState

Check current wallet creation state.

isWalletMember

Checks whether the given operator is a member of the given wallet signing group.

Requirements:

• The operator parameter must be an actual sortition pool operator.

• The expression keccak256(abi.encode(walletMembersIDs)) must be exactly the same as the hash stored under membersIdsHash for the given walletID. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate DkgResultSubmitted and DkgResultApproved events.

• The walletMemberIndex must be in range [1, walletMembersIDs.length]

Parameters

Return Values

VendingMachineV3

VendingMachineV3 is used to exchange tBTC v1 to tBTC v2 in a 1:1 ratio after the tBTC v1 bridge sunsetting is completed. Since tBTC v1 bridge is no longer working, tBTC v1 tokens can not be used to perform BTC redemptions. This contract allows tBTC v1 owners to upgrade to tBTC v2 without any deadline. This way, tBTC v1 tokens left on the market are always backed by Bitcoin. The governance will deposit tBTC v2 into the contract in the amount equal to tBTC v1 supply. The governance is allowed to withdraw tBTC v2 only if tBTC v2 left in this contract is enough to cover the upgrade of all tBTC v1 left on the market. This contract is owned by the governance.

tbtcV1

tbtcV2

Exchanged

Deposited

TbtcV2Withdrawn

FundsRecovered

constructor

exchange

Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. The caller needs to have at least amount of tBTC v1 balance approved for transfer to the VendingMachineV3 before calling this function.

Parameters

receiveApproval

Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. The caller needs to have at least amount of tBTC v1 balance approved for transfer to the VendingMachineV3 before calling this function.

This function is a shortcut for approve + exchange. Only tBTC v1 caller is allowed and only tBTC v1 is allowed as a token to transfer.

Parameters

depositTbtcV2

Allows to deposit tBTC v2 tokens to the contract. VendingMachineV3 can not mint tBTC v2 tokens so tBTC v2 needs to be deposited into the contract so that tBTC v1 to tBTC v2 exchange can happen. The caller needs to have at least amount of tBTC v2 balance approved for transfer to the VendingMachineV3 before calling this function.

This function is for the redeemer and tBTC v1 operators. This is NOT a function for tBTC v1 token holders.

Parameters

withdrawTbtcV2

Allows the governance to withdraw tBTC v2 deposited into this contract. The governance is allowed to withdraw tBTC v2 only if tBTC v2 left in this contract is enough to cover the upgrade of all tBTC v1 left on the market.

Parameters

recoverFunds

Allows the governance to recover ERC20 sent to this contract by mistake or tBTC v1 locked in the contract to exchange to tBTC v2. No tBTC v2 can be withdrawn using this function.

Parameters

_exchange

Threshold Contracts

Delivered in @threshold-network/[email protected] NPM package.

TBTC Application Contracts

Delivered in @keep-network/[email protected], @keep-network/[email protected] and @keep-network/[email protected] NPM packages.

L2 tBTC Application Contracts

Arbitrum Sepolia (chain ID: 421614)

Delivered in @keep-network/[email protected]` NPM package.

Optimism Sepolia (chain ID: 11155420)

Delivered in @keep-network/[email protected]` NPM package.

Base Sepolia (chain ID: 84532)

Delivered in @keep-network/[email protected]` NPM package.

Starknet Sepolia

EcdsaAuthorization

Library managing the state of stake authorizations for ECDSA operator contract and the presence of operators in the sortition pool based on the stake authorized for them.

Parameters

AuthorizationDecrease

Data

OperatorRegistered

AuthorizationIncreased

AuthorizationDecreaseRequested

AuthorizationDecreaseApproved

InvoluntaryAuthorizationDecreaseFailed

OperatorJoinedSortitionPool

OperatorStatusUpdated

setMinimumAuthorization

Sets the minimum authorization for ECDSA application. Without at least the minimum authorization, staking provider is not eligible to join and operate in the network.

setAuthorizationDecreaseDelay

Sets the authorization decrease delay. It is the time in seconds that needs to pass between the time authorization decrease is requested and the time the authorization decrease can be approved, no matter the authorization decrease amount.

setAuthorizationDecreaseChangePeriod

Sets the authorization decrease change period. It is the time period before the authorization decrease delay end, during which the authorization decrease request can be overwritten.

registerOperator

Used by staking provider to set operator address that will operate ECDSA node. The given staking provider can set operator address only one time. The operator address can not be changed and must be unique. Reverts if the operator is already set for the staking provider or if the operator address is already in use. Reverts if there is a pending authorization decrease for the staking provider.

authorizationIncreased

Used by T staking contract to inform the application that the authorized stake amount for the given staking provider increased.

Reverts if the authorization amount is below the minimum.

The function is not updating the sortition pool. Sortition pool state needs to be updated by the operator with a call to joinSortitionPool or updateOperatorStatus.

Should only be callable by T staking contract.

authorizationDecreaseRequested

Used by T staking contract to inform the application that the authorization decrease for the given staking provider has been requested.

Reverts if the amount after deauthorization would be non-zero and lower than the minimum authorization.

Reverts if another authorization decrease request is pending for the staking provider and not enough time passed since the original request (see authorizationDecreaseChangePeriod).

If the operator is not known (registerOperator was not called) it lets to approveAuthorizationDecrease immediately. If the operator is known (registerOperator was called), the operator needs to update state of the sortition pool with a call to joinSortitionPool or updateOperatorStatus. After the sortition pool state is in sync, authorization decrease delay starts.

After authorization decrease delay passes, authorization decrease request needs to be approved with a call to approveAuthorizationDecrease function.

If there is a pending authorization decrease request, it is overwritten, but only if enough time passed since the original request. Otherwise, the function reverts.

Should only be callable by T staking contract.

approveAuthorizationDecrease

Approves the previously registered authorization decrease request. Reverts if authorization decrease delay have not passed yet or if the authorization decrease was not requested for the given staking provider.

involuntaryAuthorizationDecrease

Used by T staking contract to inform the application the authorization has been decreased for the given staking provider involuntarily, as a result of slashing.

If the operator is not known (registerOperator was not called) the function does nothing. The operator was never in a sortition pool so there is nothing to update.

If the operator is known, sortition pool is unlocked, and the operator is in the sortition pool, the sortition pool state is updated. If the sortition pool is locked, update needs to be postponed. Every other staker is incentivized to call updateOperatorStatus for the problematic operator to increase their own rewards in the pool.

Should only be callable by T staking contract.

joinSortitionPool

Lets the operator join the sortition pool. The operator address must be known - before calling this function, it has to be appointed by the staking provider by calling registerOperator. Also, the operator must have the minimum authorization required by ECDSA. Function reverts if there is no minimum stake authorized or if the operator is not known. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay.

updateOperatorStatus

Updates status of the operator in the sortition pool. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. Function reverts if the operator is not known.

isOperatorUpToDate

Checks if the operator's authorized stake is in sync with operator's weight in the sortition pool. If the operator is not in the sortition pool and their authorized stake is non-zero, function returns false.

eligibleStake

Returns the current value of the staking provider's eligible stake. Eligible stake is defined as the currently authorized stake minus the pending authorization decrease. Eligible stake is what is used for operator's weight in the pool. If the authorized stake minus the pending authorization decrease is below the minimum authorization, eligible stake is 0.

This function can be exposed to the public in contrast to the second variant accepting decreasingBy as a parameter.

eligibleStake

Returns the current value of the staking provider's eligible stake. Eligible stake is defined as the currently authorized stake minus the pending authorization decrease. Eligible stake is what is used for operator's weight in the pool. If the authorized stake minus the pending authorization decrease is below the minimum authorization, eligible stake is 0.

This function is not intended to be exposes to the public. decreasingBy must be fetched from pendingDecreases mapping and it is passed as a parameter to optimize gas usage of functions that call eligibleStake and need to use AuthorizationDecrease fetched from pendingDecreases for some additional logic.

pendingAuthorizationDecrease

Returns the amount of stake that is pending authorization decrease for the given staking provider. If no authorization decrease has been requested, returns zero.

remainingAuthorizationDecreaseDelay

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.

EcdsaDkgValidator

EcdsaDkgValidator allows performing a full validation of DKG result, including checking the format of fields in the result, declared selected group members, and signatures of operators supporting the result. The operator submitting the result should perform the validation using a free contract call before submitting the result to ensure their result is valid and can not be challenged. All other network operators should perform validation of the submitted result using a free contract call and challenge the result if the validation fails.

groupSize

uint256 groupSize

Size of a group in DKG.

groupThreshold

uint256 groupThreshold

The minimum number of group members needed to interact according to the protocol to produce a signature. The adversary can not learn anything about the key as long as it does not break into groupThreshold+1 of members.

activeThreshold

uint256 activeThreshold

The minimum number of active and properly behaving group members during the DKG needed to accept the result. This number is higher than groupThreshold to keep a safety margin for members becoming inactive after DKG so that the group can still produce signature.

publicKeyByteSize

uint256 publicKeyByteSize

Size in bytes of a public key produced by group members during the the DKG. The length assumes uncompressed ECDSA public key.

signatureByteSize

uint256 signatureByteSize

Size in bytes of a single signature produced by operator supporting DKG result.

sortitionPool

contract SortitionPool sortitionPool

constructor

constructor(contract SortitionPool _sortitionPool) public

validate

function validate(struct EcdsaDkg.Result result, uint256 seed, uint256 startBlock) external view returns (bool isValid, string errorMsg)

Performs a full validation of DKG result, including checking the format of fields in the result, declared selected group members, and signatures of operators supporting the result.

Parameters

Return Values

validateFields

function validateFields(struct EcdsaDkg.Result result) public pure returns (bool isValid, string errorMsg)

Performs a static validation of DKG result fields: lengths, ranges, and order of arrays.

Return Values

validateGroupMembers

function validateGroupMembers(struct EcdsaDkg.Result result, uint256 seed) public view returns (bool)

Performs validation of group members as declared in DKG result against group members selected by the sortition pool.

Parameters

Return Values

validateSignatures

function validateSignatures(struct EcdsaDkg.Result result, uint256 startBlock) public view returns (bool)

Performs validation of signatures supplied in DKG result. Note that this function does not check if addresses which supplied signatures supporting the result are the ones selected to the group by sortition pool. This function should be used together with validateGroupMembers.

Parameters

Return Values

validateMembersHash

function validateMembersHash(struct EcdsaDkg.Result result) public pure returns (bool)

Performs validation of hashed group members that actively took part in DKG.

Parameters

Return Values

Application configuration can be stored in a file and passed to the application with the --config flag.

Example:

Configuration files in formats TOML, YAML and JSON are supported.

Sample configuration file: