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

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

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

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

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

Logging

Configuration options for logging

Config File

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

Client information exposed by the tBTC v2 client.

Required Ports

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

The 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 as 10B T with the following allocation:

• 4.5B T allocated to NU token holders

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.

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.

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

IVault

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

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

Errors in Logs or Console

Certain errors may be reported by your node. See a sample below:

TBTC

constructor

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

EcdsaAuthorization

EcdsaDkg

EcdsaDkgValidator

EcdsaInactivity

IWalletOwner

IWalletRegistry

WalletRegistry

WalletRegistryGovernance

Wallets

Committee Multisigs

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.

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

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

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

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

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:

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:

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:

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.

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

Returns the difficulty of the previous epoch.

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, (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.

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.

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)

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:

GovernanceUtils

onlyAfterGovernanceDelay

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

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.

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

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

Bank

BitcoinTx

Bridge

BridgeGovernance

BridgeGovernanceParameters

BridgeState

Deposit

DepositSweep

DonationVault

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

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

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.

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. , , ) or run your own Ethereum node (e.g. ).

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 . If you specify an option by using a parameter on the command line, it will override the value read from the configuration file.

Download the Binary

See GitHub for the latest release:

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 .

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 or check . These resources provide up-to-date statistics on node counts and operational metrics.

Protocol Upgrades

Defense by Thesis - Gasless Minting Feature for the Threshold App

Docker Installation

The following instructions assume your docker install followed installation instructions.

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!

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.

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

Using locally deployed tBTC contracts and local Bitcoin network

This is the common case when you are setting up a development environment. Let's suppose you have deployed the tBTC contracts on your local Ethereum chain and you are using a local Bitcoin regtest node. 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:

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

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:

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

DepositRequest

DepositRevealed

revealDeposit

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.

Parameters

validateDepositRefundLocktime

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

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.

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.

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

Example:

./keep-client --config /path/to/your/config.toml start

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

Sample configuration file: