BitcoinTx

Allows to reference Bitcoin raw transaction in Solidity.

See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format

Raw Bitcoin transaction data:

Non-coinbase transaction input (txIn):

The reference to transaction being spent (outpoint):

Transaction output (txOut):

compactSize uint format:

(*) compactSize uint is often references as VarInt)

Coinbase transaction input (txIn):

(*) Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to the stack followed by the block height as a little-endian unsigned integer. This script must be as short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total size four bytes until block 16,777,216 about 300 years from now.

Validates the SPV proof of the Bitcoin transaction. Reverts in case the validation or proof verification fail.

Evaluates the given Bitcoin proof difficulty against the actual Bitcoin chain difficulty provided by the relay oracle. Reverts in case the evaluation fails.

Extracts public key hash from the provided P2PKH or P2WPKH output. Reverts if the validation fails.

Requirements:

• The output must be of P2PKH or P2WPKH type and lock the funds on a 20-byte public key hash.

Build the P2PKH script from the given public key hash.

The P2PKH script has the following byte format: <0x1976a914> <20-byte PKH> <0x88ac>. According to https://en.bitcoin.it/wiki/Script#Opcodes this translates to:

• 0x19: Byte length of the entire script

• 0x76: OP_DUP

• 0xa9: OP_HASH160

• 0x14: Byte length of the public key hash

Build the P2WPKH script from the given public key hash.

The P2WPKH script has the following format: <0x160014> <20-byte PKH>. According to https://en.bitcoin.it/wiki/Script#Opcodes this translates to:

• 0x16: Byte length of the entire script

• 0x00: OP_0

• 0x14: Byte length of the public key hash which matches the P2WPKH structure as per: https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH

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

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 is the value accrual and governance asset for the network.

TBTC

constructor

constructor() public

IVault

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

receiveBalanceIncrease

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

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

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

Parameters

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)

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.

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

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:

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

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

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

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

In contrast, tBTC is a decentralized and trust-minimized bridge between Bitcoin and DeFi. It provides Bitcoin holders with secure, open access to the broader DeFi ecosystem, allowing you to unlock the value of your Bitcoin by borrowing and lending, minting stablecoins, providing liquidity, and more.

Instead of centralized intermediaries, tBTC uses a randomly selected group of operators running nodes on the Threshold Network to secure deposited Bitcoin through . tBTC requires a threshold majority agreement before operators can perform any action with your Bitcoin.

By rotating the selection of operators bi-weekly, tBTC protects against any individual or group of operators colluding to fraudulently seize the underlying deposits. By relying on an honest-majority assumption, we can calculate the likelihood of any wallet comprised of a quorum of dishonest operators.

tBTC fees are action-based (i.e., users incur a mint and redemption fee when using the bridge). The

Staking T tokens secures the Threshold Network and enables stakers to get fee waivers/rebates on tBTC mint and redemption fees. Stakers receive direct rebates from real protocol activity, with no inflationary emissions or token unlocks involved.

Since the beginning of 2026, T token holders have been able to when minting tBTC and redeeming BTC. With the reinstatement of minting fees, staking T has become even more valuable for reducing costs when using tBTC on the Threshold Bridge.

The in the app will continue to display rebates or fee waivers earned through staking T. Because rebates now apply to both minting and redemption fees, they will appear across both transaction types.

Staking T (Threshold Tokens) returns a share of the tBTC mint and redemption fees to stakers as rebates. The breakdown below shows exactly how much you can save at each fee tier, giving you a clear basis to evaluate whether staking T offsets the cost of your expected tBTC activity.

$T is available on most decentralized exchanges and major centralized exchanges, giving anyone a path to participate. Staking T is the operational backbone of Threshold Network: stakers provide the security that backs tBTC and earn a share of every fee the protocol generates, aligning incentives between the network and the people who secure it.

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

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:

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

Initialize the SDK

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

Request redemption

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

import { TBTC } from "@keep-network/tbtc-v2.ts"
import { BigNumber } from "ethers"

// Initialized SDK.
const sdk: TBTC

// Set the P2WPKH/P2PKH or P2WSH/P2SH Bitcoin redeemer address. This is the
// address where redeemed BTC will land.
const bitcoinRedeemerAddress: string = "..."

// Set the desired redemption amount using 1e18 precision. No need to do an 
// explicit approval on the TBTC token upfront.
const amount = BigNumber.from(5 * 1e18)

// Request redemption. This action will burn TBTC tokens and register a
// redemption request in the bridge. Returns the hash of the request redemption
// transaction and the target wallet public key that will handle the redemption.
const {
  targetChainTxHash,
  walletPublicKey
} = await sdk.redemptions.requestRedemption(bitcoinRedeemerAddress, amount)

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

Initialize the SDK

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

Initiate the deposit

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

import { TBTC } from "@keep-network/tbtc-v2.ts"

// Initialized SDK.
const sdk: TBTC

// Set the P2WPKH/P2PKH Bitcoin recovery address. It can be used to recover
// deposited BTC in case something exceptional happens.
const bitcoinRecoveryAddress: string = "..."

// Initiate the deposit.
const deposit = await sdk.deposits.initiateDeposit(bitcoinRecoveryAddress)

// Take the Bitcoin deposit address. BTC must be sent here.
const bitcoinDepositAddress = await deposit.getBitcoinAddress()

Make the Bitcoin deposit transaction

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

• Recommended: Use an external Bitcoin wallet

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

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:

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

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

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

Requirements:

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

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.

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

Allows the governance to upgrade the LightRelay

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

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

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

To create a new Ethereum account, (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.

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

You may find that some notable professional staking providers request DAO approval here.

Signer nodes form a permissioned set responsible for creating tBTC wallets that custody BTC. Running a tBTC Signer node is a significant commitment with specific requirements. This document aims to highlight such requirements, technical recommendations, and possible costs of operating a tBTC Signer node.

To stay informed about current node activities and other tBTC-related transactions, you may visit the Threshold App Explorer page.

General requirements

Running a Signer node is a long-term commitment.

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

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

Technical requirements

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

• 4 CPUs

• 4 GB of RAM

• 1 GB of persistent disk space

• 80 Mbps of network bandwidth

In addition to the above:

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

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

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

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

Key system assumptions

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

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

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

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

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

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

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

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

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

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

The above assumptions and figures should be used cautiously, as they are intended only to provide a general sense of infrastructure costs. Each prospective Signer node operator should conduct their own estimates based on their individual circumstances.

Last but not least, the presented estimate refers only to the infrastructure-related costs of operating a tBTC Signer node. This estimate DOES NOT include human operational costs. Each Signer must include this overhead when making their own estimates.

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.

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

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

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

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

The next pages cover the complete setup process for a tBTC v2 node. Two installation methods are supported, Docker and binary, each with its own configuration flow. Choose the method that aligns with your infrastructure standards, then follow the step-by-step instructions to bring your node online and connect it to the Threshold Network.

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

contract IERC20 tbtcV1

tbtcV2

contract TBTC tbtcV2

Exchanged

event Exchanged(address to, uint256 amount)

Deposited

event Deposited(address from, uint256 amount)

Withdrawn

event Withdrawn(address token, address to, uint256 amount)

constructor

constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public

exchange

function exchange(uint256 amount) external

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

Parameters

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.

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.

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.

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:

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:

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

cd /home/$USER/
mkdir keep
cd keep
mkdir storage config

The tBTC v2 client will create two subdirectories within the storage directory: keystore and work. You do not need to create these.

The keystore subdirectory contains sensitive key material data generated by the client. Losing the keystore data is a serious protocol offense and leads to slashing and potentially losing funds.

The work directory contains data generated by the client that should persist through client restarts or relocations. If the work data are lost, the client will be able to recreate them, but it is inconvenient due to the time needed for the operation to complete, and may lead to losing rewards.

Assuming for the root user with the command provided in the step, the operator-key file should be located in the /.operator-key directory.

Contained within the operator-key directory is the account key file (operator key file), its name will be similar to the following: UTC--2018-11-01T06-23-57.810787758Z--fa3da235947aab49d439f3bcb46effd1a7237e32

Copy (not move!) this account key file to the config directory created above

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:

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.

Committee Multisigs

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

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.

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

What is Sweeping?

Sweeping is an accounting optimization for tracking Bitcoin deposits in tBTC contracts. It involves periodically consolidating recent Bitcoin deposits into a single Unspent Transaction Output (UTXO) for a more optimal commitment cadence to Ethereum. This process simplifies tracking associated public keys and refund time locks while also helping prevent supply peg disruption. Typically, Sweeping runs every 8 hours, depending on the volume and size of deposits.

How it works

When a user makes a deposit, they lock the funds using our locking script. This creates an Unspent Transaction Output (UTXO).

Typically, the job of a bitcoin "wallet" (wallets don't exist in the same way they do on Ethereum) is to scan the blockchain for specific locking script patterns it thinks it can unlock (like a P2PKH script associated with your public key) and sum up the relevant funds. When you want to send someone else bitcoin, the wallet software figures out which UTXOs to unlock to send to them so that you don't have to.

If we wanted to be able to redeem bitcoin deposits, we would need to track which deposits are associated with which public keys, the same way that wallet software does; this is a headache, especially from a bitcoin mining fee perspective.

Further, our locking script includes this idea of a time-locked refund. If the funds are not touched by a certain amount of time (9 months at the time of writing; <locktime> In the script, we allow the depositor to reclaim their deposit. We do this as an effective escape hatch in case something goes wrong with the protocol or deposit.

As a result, we set the same time limit for collecting the deposit. If we don't move the funds by that time, a user could deposit 5 BTC, receive 5 TBTC, and then 9 months later reclaim their original 5 BTC without redeeming the 5 BTC. This would break the TBTC supply peg.

Sweeping aims to solve both of these problems simultaneously, as well as serves as a performance optimization. Every 8 hours, we collect all recent deposits, unlock them, and then send the funds using a standard P2PKH script back to the wallet, consolidating the UTXOs into a single UTXO.

The result is that all of the scattered deposits are "swept" into a single "pile" represented by one UTXO that we can commit to on Ethereum.

Here's a deposit for . That deposit is swept in transaction (along with many other deposits). That was one of three sweeps performed by that wallet (as of writing).

That transaction created a UTXO worth 1.51614471 BTC. The next transaction

Used the old UTXO (the first input) as well as all of the recent deposits to create a new UTXO (the output on the right) worth 15.42475511 BTC. The final transaction

Follows the same pattern. It uses the old UTXO (the first input) and the recent deposits to create a new UTXO worth 59.52818486 BTC.

Configuration options for logging

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.

See GitHub for the latest release:

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

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

Extract the compressed file:

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

The following flags must be set at a minimum:

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

To launch the client, execute the following:

If you still hold KEEP or NU, you can still convert your tokens to T. The migration began around the launch of Threshold in 2022. That original migration experience is now legacy infrastructure, and the old upgrade UI is no longer a practical way to complete the conversion.

However, the underlying smart contracts did not disappear.

The KEEP and NU Vending Machine contracts were designed to remain available indefinitely, which means there is no migration deadline for liquid KEEP or NU tokens. If you still have KEEP or NU sitting in your wallet, you can interact with those contracts directly through Etherscan.

It looks more technical than the old UI, but the process itself is relatively straightforward.

The conversion ratios were fixed when Threshold launched and are based on the respective token supplies rather than their market prices. ()

Liquid T holders can delegate their token weights to themselves or a third party for voting on governance proposals.

1. Go to .

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

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

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.

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

VendingMachine

The Vending Machine is the owner of TBTC v2 token and can mint TBTC v2 tokens in 1:1 ratio from TBTC v1 tokens with TBTC v1 deposited in the contract as collateral. TBTC v2 can be unminted back to TBTC v1 with or without a fee - fee parameter is controlled by the Governance. This implementation acts as a bridge between TBTC v1 and TBTC v2 token, allowing to mint TBTC v2 before the system is ready and fully operational without sacrificing any security guarantees and decentralization of the project. Vending Machine can be upgraded in a two-step, governance-controlled process. The new version of the Vending Machine will receive the ownership of TBTC v2 token and entire TBTC v1 balance stored as collateral. It is expected that this process will be executed before the v2 system launch. There is an optional unmint fee with a value that can be updated in a two-step, governance-controlled process. All governable parameters are controlled by two roles: update initiator and finalizer. There is a separate initiator role for unmint fee update and vending machine upgrade. The initiator proposes the change by initiating the update and the finalizer (contract owner) may approve it by finalizing the change after the governance delay passes.

GOVERNANCE_DELAY

uint256 GOVERNANCE_DELAY

The time delay that needs to pass between initializing and finalizing update of any governable parameter in this contract.

FLOATING_POINT_DIVISOR

uint256 FLOATING_POINT_DIVISOR

Divisor for precision purposes. Used to represent fractions in parameter values.

tbtcV1

contract IERC20 tbtcV1

tbtcV2

contract TBTC tbtcV2

unmintFee

uint256 unmintFee

The fee for unminting TBTC v2 back into TBTC v1 represented as 1e18 precision fraction. The fee is proportional to the amount being unminted and added on the top of the amount being unminted. To calculate the fee value, the amount being unminted needs to be multiplied by unmintFee and divided by 1e18. For example, unmintFee set to 1000000000000000 means that 0.001 of the amount being unminted needs to be paid to the VendingMachine as an unminting fee on the top of the amount being unminted.

The address of a new vending machine. Set only when the upgrade process is pending. Once the upgrade gets finalized, the new vending machine will become an owner of TBTC v2 token.

Mints TBTC v2 to the caller from TBTC v1 with 1:1 ratio. The caller needs to have at least amount of TBTC v1 balance approved for transfer to the VendingMachine before calling this function.

Mints TBTC v2 to from address from TBTC v1 with 1:1 ratio. from address needs to have at least amount of TBTC v1 balance approved for transfer to the VendingMachine before calling this function.

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

Unmints TBTC v2 from the caller into TBTC v1. Depending on unmintFee value, may require paying an additional unmint fee in TBTC v2 in addition to the amount being unminted. To see what is the value of the fee, please call unmintFeeFor(amount) function. The caller needs to have at least amount + unmintFeeFor(amount) of TBTC v2 balance approved for transfer to the VendingMachine before calling this function.

Allows the Governance to withdraw unmint fees accumulated by VendingMachine.

Initiates unmint fee update process. The update process needs to be finalized with a call to finalizeUnmintFeeUpdate function after the GOVERNANCE_DELAY passes. Only unmint fee update initiator role can initiate the update.

Allows the contract owner to finalize unmint fee update process. The update process needs to be first initiated with a call to initiateUnmintFeeUpdate and the GOVERNANCE_DELAY needs to pass.

Initiates vending machine upgrade process. The upgrade process needs to be finalized with a call to finalizeVendingMachineUpgrade function after the GOVERNANCE_DELAY passes. Only vending machine upgrade initiator role can initiate the upgrade.

Allows the contract owner to finalize vending machine upgrade process. The upgrade process needs to be first initiated with a call to initiateVendingMachineUpgrade and the GOVERNANCE_DELAY needs to pass. Once the upgrade is finalized, the new vending machine will become an owner of TBTC v2 token and all TBTC v1 held by this contract will be transferred to the new vending machine.

Transfers unmint fee update initiator role to another address. Can be called only by the current unmint fee update initiator.

Transfers vending machine upgrade initiator role to another address. Can be called only by the current vending machine upgrade initiator.

Get the remaining time that needs to pass until unmint fee update can be finalized by the Governance. If the update has not been initiated, the function reverts.

Get the remaining time that needs to pass until vending machine upgrade can be finalized by the Governance. If the upgrade has not been initiated, the function reverts.

Calculates the fee that needs to be paid to the VendingMachine to unmint the given amount of TBTC v2 back into TBTC v1.

Protocol Upgrades

Defense by Thesis - Beta Staker Allowlist & Bridge Fee Rebates

• Date: 27 November 2025

• Report: View Audit 1 PDF - View Audit 2 PDF

• Scope: Smart contracts for T staking rebates. See related proposals, TIP-067 and TIP-106

Defense by Thesis - WalletRegistry & EcdsaDkg

• Date: 5 November 2025

• Report:

• Scope: WalletRegistry and EcdsaDkg smart contracts

• Date: 31 Oct 2025

• Report:

• Scope: NativeBTCDepositor contract

• Date: 25 Sept 2025

• Report:

• Scope: Threshold CCIP Update

• Date: 08 Sept 2025

• Report:

• Scope: Cross-chain bridge transfers

• Date: 01 May 2025

• Report:

• Scope: tBTC integration with the Sui blockchain

• Date: April 2025

• Report:

• Scope: tBTC integration with the StarkNet blockchain

• Date: April 11th, 2024

• Report:

• Scope: tBTC integration with the Base blockchain

• Date: 29 August 2023

• Report: -

• Scope: Smart contracts for the tBTC Bridge on Solana

• Date: 29 September 2022

• Report: -

• Scope: Security audit of the core tBTC Bridge contracts

• Date: 19 November 2021

• Report: -

• Scope: Vending machine security audit

• Date: 09 November 2021

• Report: -

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

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.

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.

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

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

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

The library handles the logic for challenging Bridge wallets that committed fraud.

Anyone can submit a fraud challenge indicating that a UTXO being under the wallet control was unlocked by the wallet but was not used according to the protocol rules. That means the wallet signed a transaction input pointing to that UTXO and there is a unique sighash and signature pair associated with that input.

In order to defeat the challenge, the same wallet public key and signature must be provided as were used to calculate the sighash during the challenge. The wallet provides the preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim.

The fraud challenge defeat attempt will succeed if the inputs in the preimage are considered honestly spent by the wallet. Therefore the transaction spending the UTXO must be proven in the Bridge before a challenge defeat is called.

Another option is when a malicious wallet member used a signed heartbeat message periodically produced by the wallet off-chain to challenge the wallet for a fraud. Anyone from the wallet can defeat the challenge by proving the sighash and signature were produced for a heartbeat message following a strict format.

Submits a fraud challenge indicating that a UTXO being under wallet control was unlocked by the wallet but was not used according to the protocol rules. That means the wallet signed a transaction input pointing to that UTXO and there is a unique sighash and signature pair associated with that input. This function uses those parameters to create a fraud accusation that proves a given transaction input unlocking the given UTXO was actually signed by the wallet. This function cannot determine whether the transaction was actually broadcast and the input was consumed in a fraudulent way so it just opens a challenge period during which the wallet can defeat the challenge by submitting proof of a transaction that consumes the given input according to protocol rules. To prevent spurious allegations, the caller must deposit ETH that is returned back upon justified fraud challenge or confiscated otherwise.

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.

Wormhole Token Bridge interface. Contains only selected functions used by L2WormholeGateway.

Selected cross-ecosystem bridges are given the minting authority for tBTC token on L2 and sidechains. This contract gives a minting authority to the Wormhole Bridge.

The process of bridging from L1 to L2 (or sidechain) looks as follows:

1. There is a tBTC holder on L1. The holder goes to the Wormhole Portal and selects the chain they want to bridge to.

2. The holder submits one transaction to L1 locking their tBTC tokens in the bridge’s smart contract. After the transaction is mined, they wait about 15 minutes for the Ethereum block finality.

The is an ERC-20 token that powers tBTC and serves as the value accrual asset for the Threshold Network. As of late, the T token is fully diluted.

Historically, the T token was formed through the merger of two entities, NU and KEEP. Based on the final merger proposal, the conversion ratio for each token is determined by total supply rather than price. During the merger, the supply of NU is approximately 1,380,688,920, and the total supply of KEEP is approximately 940,795,010. Accordingly, the conversion factors are ~3.26 T per NU and ~4.78 T per KEEP.

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

• 4.5B T allocated to NU token holders

• 4.5B T allocated to KEEP token holders