Before you start

Here are some things you will need before you start the minting process:

✅ Bitcoin (BTC)

✅ Ethereum (ETH) for Ethereum transaction gas costs

✅ Bitcoin compatible wallet

✅ Ethereum compatible wallet

If you don't already have one, you'll need to set up a Bitcoin wallet. A solid option to use is Green Wallet. You can download it here:

• Apple store download

• Google store download

After you've created your wallet, select Bitcoin as your network.

Start minting tBTC

🎉 You're ready to mint! Go to the tBTC dapp here: https://dashboard.threshold.network/tBTC/mint

STEP 1: Generate a deposit address

1. Connect your preferred Ethereum wallet to the tBTC dapp by selecting Connect Wallet.

1. Navigate to the tBTC Bridge page. This is represented in the lefthand navigation by the tBTC icon.

1. Enter a Bitcoin wallet address as the BTC Recovery Address. Click Generate Deposit Address to create your unique deposit address.

1. Make sure to download the JSON file by clicking Download. The JSON file contains a wallet public key, a refund public key, and a refund lock time. You need to keep this JSON file until you receive your tBTC tokens.

STEP 2: Make BTC Deposit

1. In your Bitcoin wallet, take a picture of the QR code of the generated Deposit Address in the tBTC dapp. It will look something like this:
2. Send your BTC deposit to this Deposit Address from your Bitcoin wallet. The minimum deposit is 0.01 BTC.

3. Return to the tBTC dapp. After your funds are sent, the screen will automatically advance to Step 3.

STEP 3: Initiate Minting

1. To initiate minting, click on Confirm deposit & mint.

1. Sign the transaction in your Ethereum wallet.

STEP 4: tBTC Minting

1. Your mint is now in progress! You don't need to remain in the dapp to wait for your tBTC tokens to mint. You can see the status of your mint in the dapp. The first stage requires 1 confirmation on the Bitcoin Network before advancing to the next step.

1. Now you will see the following while waiting for a Minter to assess the minting initialization:

1. Next, you will see the following while waiting for a Guardian to examine the minting request:

1. Success! You can see all transaction links on this screen.

1. Make sure to add the tBTC token address to your Ethereum wallet by clicking token address.

Congrats — you minted!

🎉 You've successfully minted tBTC! 🎉

Threshold Network powers tBTC, the Bitcoin standard for DeFi—a trust-minimized way to bring BTC liquidity into the crypto ecosystem while always maintaining a direct settlement path back to native Bitcoin.

Unlike other BTC derivatives or wrapped tokens, tBTC is designed to be as close to Bitcoin as possible while enabling seamless participation in DeFi. No complex staking mechanics, no dependency on a single entity—just pure BTC liquidity that always settles back to Bitcoin.

Threshold Network's powers tBTC and is the value accrual asset used to distribute profits from bridge fee via token buybacks.

Fundamentals: Dive a little deeper

Learn the fundamentals of the Threshold Network to get a deeper understanding of our main features:

Configuration options for logging

Alternative application authorization methods to using the Threshold Dashboard.

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

Client information exposed by the tBTC v2 staking client.

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

To get familiarized with API of contracts related to the DAO, go .

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

Threshold USD (thUSD) is a stablecoin soft-pegged against USD, backed by ETH and tBTC as collateral. For more details, refer to the THUSD overview.

With thUSD, you can now:

• Open collateral vaults seamlessly on BOB Network using bridged tBTC or ETH

• Mint thUSD and utilize it across the BOB Network ecosystem

Start by connecting your preferred wallet (e.g., MetaMask) at app.gobob.xyz/wallet and bridging your tBTC at app.gobob.xyz/bridge.

Connecting to BOB Network

1. Access Wallet Setup

   • Navigate to app.gobob.xyz/wallet.

2. Connect Your Wallet

   • Choose your preferred wallet (e.g., MetaMask) and follow the prompts to connect it to the BOB Network.

3. Switch to BOB Network

   • Click on the option "Switch to BOB." This will automatically add the BOB Network to your wallet and connect your wallet to the BOB Network.

4. Manual Setup

   • Alternatively, you can manually set up your wallet with the following settings:

     Chain ID: 60808

     Gas Token: ETH

     RPC URL: https://rpc.gobob.xyz/

     WS URL: wss://rpc.gobob.xyz

     Explorer: https://explorer.gobob.xyz/

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.

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

BaseTokenholderGovernor

VETO_POWER

bytes32 VETO_POWER

constructor

constructor(contract T _token, contract IVotesHistory _staking, contract TimelockController _timelock, address _vetoer, uint256 _quorumNumerator, uint256 _proposalThresholdNumerator, uint256 votingDelay, uint256 votingPeriod, uint64 votingExtension) public

cancel

function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256)

propose

function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) public returns (uint256)

quorum

function quorum(uint256 blockNumber) public view returns (uint256)

proposalThreshold

function proposalThreshold() public view returns (uint256)

getVotes

function getVotes(address account, uint256 blockNumber) public view returns (uint256)

state

function state(uint256 proposalId) public view returns (enum IGovernor.ProposalState)

supportsInterface

function supportsInterface(bytes4 interfaceId) public view returns (bool)

_execute

function _execute(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal

_cancel

function _cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal returns (uint256)

_executor

function _executor() internal view returns (address)

proposalDeadline

function proposalDeadline(uint256 proposalId) public view virtual returns (uint256)

_castVote

function _castVote(uint256 proposalId, address account, uint8 support, string reason) internal virtual returns (uint256)

IVotesHistory

getPastVotes

function getPastVotes(address account, uint256 blockNumber) external view returns (uint96)

getPastTotalSupply

function getPastTotalSupply(uint256 blockNumber) external view returns (uint96)

PercentUtils

percent

function percent(uint256 a, uint256 b) internal pure returns (uint256)

asPercentOf

function asPercentOf(uint256 a, uint256 b) internal pure returns (uint256)

SafeTUpgradeable

A wrapper around OpenZeppelin's SafeERC20Upgradeable but specific to the T token. Use this library in upgradeable contracts. If your contract is non-upgradeable, then the traditional SafeERC20 works. The motivation is to prevent upgradeable contracts that use T from depending on the Address library, which can be problematic since it uses delegatecall, which is discouraged by OpenZeppelin for use in upgradeable contracts.

This implementation force-casts T to IERC20Upgradeable to make it work with SafeERC20Upgradeable.

safeTransfer

function safeTransfer(contract T token, address to, uint256 value) internal

safeTransferFrom

function safeTransferFrom(contract T token, address from, address to, uint256 value) internal

StakerGovernor

VETO_POWER

bytes32 VETO_POWER

manager

address manager

constructor

constructor(contract IVotesHistory _staking, contract TimelockController _timelock, contract TokenholderGovernor tokenholderGovernor, address vetoer) public

cancel

function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256)

propose

function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) public returns (uint256)

quorum

function quorum(uint256 blockNumber) public view returns (uint256)

proposalThreshold

function proposalThreshold() public view returns (uint256)

getVotes

function getVotes(address account, uint256 blockNumber) public view returns (uint256)

state

function state(uint256 proposalId) public view returns (enum IGovernor.ProposalState)

supportsInterface

function supportsInterface(bytes4 interfaceId) public view returns (bool)

_execute

function _execute(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal

_cancel

function _cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal returns (uint256)

_executor

function _executor() internal view returns (address)

Returns the address of the entity that acts as governance for this contract.

By default, Governor assumes this is either the Governor contract itself, or a timelock if there's one configured. We override this here for the StakerGovernor contract so it's the Tokenholder DAO's Timelock, which we obtain at constructor time.

TokenholderGovernor

constructor

constructor(contract T _token, contract IVotesHistory _staking, contract TimelockController _timelock, address vetoer) public

To get familiarized with Random Bitcoin contracts API, go here.

Governable

Governable contract.

A constructor is not defined, which makes the contract compatible with upgradable proxies. This requires calling explicitly _transferGovernance function in a child contract.

governance

address governance

GovernanceTransferred

event GovernanceTransferred(address oldGovernance, address newGovernance)

onlyGovernance

modifier onlyGovernance()

transferGovernance

function transferGovernance(address newGovernance) external virtual

Transfers governance of the contract to newGovernance.

_transferGovernance

function _transferGovernance(address newGovernance) internal virtual

Existing solutions that bridge Bitcoin to Ethereum require users to send their Bitcoin to an intermediary, in exchange for an ERC-20 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.

The second generation of tBTC is a truly decentralized (and scalable) bridge between Bitcoin and Ethereum. It provides Bitcoin holders secure and open access to the broader DeFi ecosystem. tBTC v2 allows 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. That means tBTC requires a threshold majority agreement before operators perform any action with your Bitcoin. By rotating the selection of operators 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 here).

Unlike other solutions on the market, users of tBTC trust math, not hardware or people.

Threshold is community-driven and governed by an eponymous DAO that includes the constituencies of both the NuCypher and Keep networks. The Threshold DAO has two primary bodies: the Tokenholder DAO and the Elected Council. The goal of this two-pronged structure is to enhance representation while ensuring accountability. Each of these governance bodies holds the other accountable, similar to the system of checks and balances found in most constitutional governments. They also hold separate responsibilities that are embedded in the governance structure.

From an implementation perspective, the Tokenholder DAO is based on the Governor Bravo governance model (in particular, using OpenZeppelin Governance). The Tokenholder DAO is on Ethereum Mainnet at 0xd101f2B25bCBF992BdF55dB67c104FE7646F5447. The Elected Council is implemented as a Gnosis Safe contract, with a 6-of-9 configuration, also deployed on Ethereum Mainnet, at 0x9F6e831c8F8939DC0C830C6e492e7cEf4f9C2F5f.

A technical architecture diagram is show below.

Summary

Threshold Coverage Pool has been sunset via the DAO ratified proposal.

The Threshold Coverage Pool served as a backstop for assets secured by the tBTC protocol. In the event that secured Bitcoin were lost from the protocol, assets from the coverage pool were to be withdrawn by the risk manager, converted to BTC, and put back into the protocol to achieve the supply peg as closely as possible. The risk manager for the coverage pool was the multisig.

Over time, it became clear that this backstop model was sub-optimal given the relationship between tBTC and T - in the case of a BTC collateral loss event, T's value would also decline, greatly reducing its effectiveness as an insurance backstop. Consequently, the explicit Threshold Coverage Pool has been sunset with the approval of TIP-064.

Under the newly implemented "implicit coverage pool" model, tBTC is backed by the full faith and credit of Threshold DAO - by its treasury assets, which currently include T, ETH, wBTC, tBTC, stablecoins, CVX, veCRV, and associated LP tokens, etc.

Threshold USD (thUSD) is a stablecoin soft-pegged against USD and backed by ETH and tBTC as collateral, with a minimum collateral ratio of 110%.

With either BTC or ETH as your collateral, you'll be able to borrow thUSD at very low cost.

Threshold USD is a modified fork of built to be self-sustained through a PCV ("Protocol Controlled Value"). There is no equivalent of LQTY token in Threshold USD. Instead all profits accrue into the PCV. Since there is no token, is completed through an .

The result of protocol owning its own liquidity ("PCV") is a more predictable trajectory and sustainability long-term. The stability pool is funded by the PCV instead of user deposits. Thanks to this, no funds are wasted on rewards to passive LQTY stakers (rented liquidity) and those funds can instead by re-injected into the stability pool. As the protocol grows and accrue fees, the stability pool will be consistently topped up.

Multi-collateral

Liquity is limited to ETH as the only type of collateral. Threshold USD expand to support BTC as collateral for loans through the decentralized BTC wrapper tBTC. In the future other types of collateral may be considered for on-boarding if they are sufficiently decentralized.

Each collateral will be deployed with its own contracts and each new collateral will require a DAO vote with a lengthy time delay before deployment. By having each collateral be its own contract any collateral can easily be deprecated by disallowing minting on that specific contract.

All contracts related to thUSD can be found .

How does thUSD closely follow the price of USD?

The ability to redeem thUSD for tBTC at face value (i.e. 1 thUSD for $1 of tBTC) and the minimum collateral ratio of 110% create a price floor and price ceiling (respectively) through arbitrage opportunities. We call these "hard peg mechanisms" since they are based on direct processes.

thUSD also benefits from less direct mechanisms for USD parity — called "soft peg mechanisms". One of these mechanisms is parity as a Schelling point. Since Threshold USD treats thUSD as being equal to USD, parity between the two is an implied equilibrium state of the protocol. Another of these mechanisms is the borrowing fee on new debts. As redemptions increase (implying thUSD is below $1), so too does the baseRate — making borrowing less attractive which keeps new thUSD from hitting the market and driving the price below $1.

Liquity (on which thUSD Protocol is based on) did a thorough analysis on the price stability of LUSD (). This analysis is equally relevant for thUSD.

What are redemptions?

A redemption is the process of exchanging thUSD for tBTC at face value, as if 1 thUSD is exactly worth $1. That is, for x thUSD you get x Dollars worth of tBTC in return.

Users can redeem their thUSD for tBTC at any time without limitations. However, a redemption fee might be charged on the redeemed amount.

For example, if the current redemption fee is 1%, the price of tBTC is $50,000 and you redeem 10,000 thUSD, you would get 0.198 tBTC (0.2 tBTC minus a redemption fee of 0.002 tBTC).

Note that the redeemed amount is taken into account for calculating the base rate and might have an impact on the redemption fee, especially if the amount is large.

To illustrate how Redemptions work, below you can see the mechanism in action for LUSD, when its value went below 1 USD. The Borrowing rate (red line) immediately spiked from 0.5% up to around 1.8% and redemptions (blue bars) started to happen, i.e. users would buy LUSD at less than 1 USD and redeem for ETH in Vaults as if it was valued at 1 USD, arbitraging the difference, reducing the supply of LUSD and increasing its price.

Is a redemption the same as paying back my debt?

No, redemptions are a completely separate mechanism. All one has to do to pay back their debt is adjust their Vault's debt and collateral.

How is the redemption fee calculated?

Under normal operation, the redemption fee is given by the formula (baseRate + 0.5%) * tBTCdrawn

How is the baseRate calculated?

Redemption fees are based on the baseRate state variable in Threshold USD, which is dynamically updated. The baseRate increases with each redemption, and decays according to time passed since the last fee event - i.e. the last redemption or issuance of thUSD.

Upon each redemption:

• baseRate is decayed based on time passed since the last fee event

• baseRate is incremented by an amount proportional to the fraction of the total thUSD supply that was redeemed

• The redemption fee is given by (baseRate + 0.5%) * tBTCdrawn

As a borrower, do I lose money if I'm redeemed against?

If your Vault is redeemed against, you do not incur a net loss. However, you will lose some of your tBTC exposure. Your Vault's collateral ratio will also improve after a redemption.

How can I avoid being redeemed against?

The best way to avoid being redeemed against is by maintaining a high collateral ratio relative to the rest of the Vault's in the system. Remember: The riskiest Vault (i.e. lowest collateralized Vaults) are first in line when a redemption takes place.

A certain network effect is required for a stablecoin to function well. Bootstrapping is the process of ensuring the protocol has gained enough traction to become self-sufficient.

In the past this was usually accomplished by being an early adopter of coins, such as buying Bitcoin early and benefiting from the lower price. DeFi revolutionized the bootstrapping concept by enabling the bootstrapping of capital through yield-farming (aka rented liquidity).

Liquity Protocol (creators of the LUSD stablecoin) bootstrapped by issuing LQTY tokens to depositors in the stability pool. This incentivized people to take out loans and deposit to the stability pool.

For normal, healthy operations of the protocol, it's vital that there is sufficient funds in the stability pool to cover all liquidations. However the LQTY incentive resulted in far more deposits than required, essentially creating wasted capital. Furthermore there are concerns on how sustainable Liquity will be after the initial 100 million LQTY has been issued and the pool is only sustained through liquidations rewards.

How does Threshold USD approach this?

In Threshold USD we take a different approach. A newer concept in DeFi known as Protocol Controlled Value (PCV) is the idea that the protocol itself can own liquidity and use that to improve the protocol. This is a new alternative to renting it elsewhere (aka yield-farming) and has the benefit of long-term sustainability.

But the PCV has to come from somewhere. In thUSD we resolve this by issuing an to the PCV which then deposit these funds directly to the stability pool. Read more about this here:

That lets us bootstrap the stability pool at zero cost to the protocol.

But not only that, by eliminating the LQTY token, all profits (from interest, redemption fee, etc) will go directly into the PCV. Compared to Liquity, where profits are distributed among LQTY holders, we have eliminated a massive drain on the system, at no cost.

Having the stability pool funded on its own is enough for the protocol to function, and we can expect some users that want to borrow against their tBTC to take part, but it's not going to create major adoption, and for thUSD to function well it needs to be stable at ~$1, that requires people to put up liquidity at decentralized exchanges.

In order to draw in more users and create liquidity for thUSD, we will issue rewards to pools on other platforms (such as a thUSD stablecoin pool on Curve). This will incentivize users to take debt and deposit into Curve, with the added benefit of improved liquidity and resiliency.

How fast we want to grow can be almost entirely adjusted by how much reward is sent to the pool.

This part is indeed rented liquidity with all its drawbacks, but remember that Threshold USD profits are sent to the PCV instead of LQTY holders: as the protocol grows in popularity, profits from the protocol itself can be used to fund these rewards, thus creating a self-sustaining feedback loop.

On top of that, Threshold DAO will store some of its reserves in stablecoins, so the Threshold DAO can initiate a PCV with deposits on Curve. That will result in more stability for thUSD which is important for adoption.

Steps to Open Collateral Vaults and Mint thUSD

1. Access the thUSD App Interface:

   • Navigate to and connect your preferred wallet on BOB Network.

2. Open a New Vault:

   • Go to the “Borrow” menu, choose tBTC or ETH as your collateral, and select "Open a Vault".

3. Deposit tBTC or ETH:

   • Specify the amount of tBTC or ETH you wish to deposit as collateral. Ensure the deposited amount meets the minimum collateral requirement of $2,000 ($1,800 minimum debt + $200 liquidation reserve) + transaction fees.

4. Set the collateral amount:

   • Set your desired collateral amount. Ensure it meets the minimum required ratio of 110% of your debt.

5. Mint thUSD:

   • Enter the amount of thUSD you wish to mint based on your collateral and collateralization ratio.

   • Review the details of your vault, including the collateral amount, collateralization ratio, and minted thUSD.

   • In case of tBTC as collateral, approve tBTC expenditure.

   • Confirm, and authorize the transaction to mint thUSD.

6. Manage Your Vault:

   • Monitor your vault on to ensure it remains adequately collateralized. You can adjust collateral and debt position to adjust the collateralization ratio or repay thUSD as needed.

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

• Council vetos: During the on-chain phase, the Elected Council 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.

To participate in DAO governance, token holders must set a governance delegate address. Vote delegation is the process of granting a delegate the power to vote on your behalf, using your voting weight, on DAO governance issues. The delegate can be yourself (self-delegation) or a third party. A configured delegate can be changed or revoked at any time.

Third-Party Delegation

Third-party delegates are volunteers who actively participate in Threshold governance and wish to grow their influence over critical DAO decisions. Delegates provide ETH addresses to which other Threshold token holders and Threshold stakers can delegate their vote weight. Third-party delegates are subsequently responsible for voting on Threshold governance proposals with this vote weight that others have assigned to them.

Community members who are unsure or uninterested in governance and do not want to actively participate in proposals, discussions, and voting, can instead delegate to active DAO members who have demonstrated a commitment to Threshold. Delegating their vote allows token holders and stakers to have an indirect say in the DAO without being involved in day-to-day governance activities.

Community members interested in serving as delegates can self-nominate .

The process for delegating is explained in the following subsection. It's not currently possible to delegate tokens deposited as LP in AMM pools (e.g. Curve), although this is an area for future improvement.

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

6. Sign the transaction.

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 .

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

Errors in Logs or Console

Certain errors may be reported by your node during the early stages of Chaosnet and the tBTC 2 launch. See a sample below:

This is expected during this stage of the chaosnet. 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 beta operators is registered, the pool will get locked for some time to allow the sortition. After some time, when another set of beta operators are added, the pool will be unlocked again.

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

IManagedGrant

grantee

KeepStake

T network staking contract supports existing KEEP stakes by allowing KEEP stakers to use their stakes in T network and weights them based on KEEP<>T token ratio. KEEP stake owner is cached in T staking contract and used to restrict access to all functions only owner or operator should call. To cache KEEP stake owner in T staking contract, T staking contract first needs to resolve the owner.

Resolving liquid KEEP stake owner is easy. Resolving token grant stake owner is complicated and not possible to do on-chain from a contract external to KEEP TokenStaking contract. Keep TokenStaking knows the grant ID but does not expose it externally.

KeepStake contract addresses this problem by exposing operator-owner mappings snapshotted off-chain based on events and information publicly available from KEEP TokenStaking contract and KEEP TokenGrant contract. Additionally, it gives the Governance ability to add new mappings in case they are ever needed; in practice, this will be needed only if someone decides to stake their KEEP token grant in KEEP network after 2021-11-11 when the snapshot was taken.

Operator-owner pairs were snapshotted 2021-11-11 in the following way:

1. Fetch all TokenStaking events from KEEP staking contract.

2. Filter out undelegated operators.

3. Filter out canceled delegations.

4. Fetch grant stake information from KEEP TokenGrant for that operator to determine if we are dealing with grant delegation.

5. Fetch grantee address from KEEP TokenGrant contract.

6. Check if we are dealing with ManagedGrant by looking for all created ManagedGrants and comparing their address against grantee address fetched from TokenGrant contract.

keepTokenStaking

operatorToManagedGrant

operatorToGrantee

constructor

setManagedGrant

Allows the Governance to set new operator-managed grant pair. This function should only be called for managed grants if the snapshot does include this pair.

setGrantee

Allows the Governance to set new operator-grantee pair. This function should only be called for non-managed grants if the snapshot does include this pair.

resolveOwner

Resolves KEEP stake owner for the provided operator address. Reverts if could not resolve the owner.

resolveSnapshottedManagedGrantees

resolveSnapshottedGrantees

StakerGovernorVotes

Staker DAO voting power extraction from staked T positions,

staking

constructor

getVotes

Read the voting weight from the snapshot mechanism in the T staking contracts. Note that this also tracks legacy stakes (NU/KEEP).

See {IGovernor-getVotes}

Parameters

_getPastTotalSupply

Compute the total voting power for the Staker DAO.

Parameters

Callback

Library for handling calls to random beacon consumer.

Data

CallbackFailed

setCallbackContract

Sets callback contract.

Parameters

executeCallback

Executes consumer specified callback for the relay entry request.

Parameters

IRandomBeacon

requestRelayEntry

Creates a request to generate a new relay entry. Requires a request fee denominated in T token.

Parameters

ModUtils

modExp

Wraps the modular exponent pre-compile introduced in Byzantium. Returns base^exponent mod p.

modSqrt

Calculates and returns the square root of a mod p if such a square root exists. The modulus p must be an odd prime. If a square root does not exist, function returns 0.

legendre

Calculates the Legendre symbol of the given a mod p.

Return Values

IRandomBeaconConsumer

__beaconCallback

Receives relay entry produced by Keep Random Beacon. This function should be called only by Keep Random Beacon.

Parameters

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

is a decentralized, permissionless Bitcoin bridge developed by the Threshold Network designed to bring Bitcoin (BTC) liquidity to Ethereum and other EVM-compatible networks. It allows Bitcoin holders to mint tBTC, an ERC-20 token fully backed 1:1 by BTC, enabling seamless participation in Ethereum's DeFi ecosystem without relying on centralized intermediaries.

By integrating tBTC, developers can bridge the gap between Bitcoin's liquidity and Ethereum's smart contract capabilities. tBTC provides a decentralized, secure and permissionless way to bring BTC into the Ethereum ecosystem enabling innovative DeFi applications and expanding possibilities for cross-chain interactions.

Utilizing the provided SDKs and developer resources you can seamlessly integrate tBTC into your projects and contribute to the growth of decentralized finance.

What is Recovery Mode?

Recovery Mode kicks in when the Total Collateral Ratio (TCR) of the system falls below 150%.

During Recovery Mode, Vaults with a collateral ratio below 150% can be liquidated.

Moreover, the system blocks borrower transactions that would further decrease the TCR. New thUSD may only be issued by adjusting existing Vaults in a way that improves their collateral ratio, or by opening a new Vault with a collateral ratio>=150%. In general, if an existing Vault's adjustment reduces its collateral ratio, the transaction is only executed if the resulting TCR is above 150%.

What is the Total Collateral Ratio?

The Total Collateral Ratio or TCR is the ratio of the Dollar value of the entire system collateral at the current ETH:USD price, to the entire system debt. In other words, it's the sum of the collateral of all Vaults expressed in USD, divided by the debt of all Vaults expressed in thUSD.

What is the purpose of Recovery Mode?

The goal of Recovery Mode is to incentivize borrowers to behave in ways that promptly raise the TCR back above 150%, and to incentivize thUSD holders to replenish the Stability Pool.

Economically, Recovery Mode is designed to encourage collateral top-ups and debt repayments, and also itself acts as a self-negating deterrent: the possibility of it occurring actually guides the system away from ever reaching it. Recovery Mode is not a desirable state for the system.

What are the fees during Recovery Mode

While Recovery Mode has no impact on the redemption fee, the borrowing fee is set to 0% to maximally encourage borrowing (within the limits described above).

How can I make my Vault safe in Recovery Mode?

By increasing your collateral ratio to 150% or greater, your Vault will be protected from liquidation. This can be done by adding collateral, repaying debt, or both.

Can I be liquidated if my collateral ratio is below 150% in Recovery Mode?

Yes, you can be liquidated below 150% if your Vault's collateral ratio is smaller than 150%. In order to avoid liquidation in Normal Mode and Recovery Mode, a user should keep their collateral ratio above 150%.

How much of a Vault’s collateral can be liquidated in Recovery Mode?

In Recovery Mode, liquidation loss is capped at 110% of a Vault's collateral. Any remainder, i.e. the collateral above 110% (and below the TCR), can be reclaimed by the liquidated borrower using the standard web interface.

This means that a borrower will face the same liquidation “penalty” (10%) in Recovery Mode as in Normal Mode if their Vault gets liquidated.

Ensure your wallet has sufficient ETH for transaction fees. You can fund your wallet on BOB by transferring tBTC or ETH from the Ethereum Mainnet.

Note: The minimum amount to mint thUSD on BOB is $2,000 ($1,800 minimum debt + $200 liquidation reserve) worth of tBTC or ETH + transaction fees.

Preparation

1. Set up Wallet:

   • Ensure you have a wallet connected to the Ethereum Mainnet with sufficient tBTC or ETH for bridging.

Bridging Process

1. Access Bridge Interface:

   • Navigate to the BOB bridge interface at app.gobob.xyz/bridge.

2. Connect Wallet:

   • Connect your wallet on the Ethereum Mainnet network to the bridge interface.

3. Select tBTC or ETH:

   • Choose tBTC or ETH as the asset you want to bridge.

4. Enter Amount:

   • Specify the amount of tBTC or ETH you want to bridge.

5. Confirm Transaction:

   • Review the transaction details, including fees, and confirm the transaction.

6. Authorize Transaction:

   • Approve the transaction in your wallet.

7. Wait for Confirmation:

   • Wait for the transaction to be confirmed on the Ethereum blockchain.

8. Verify Receipt:

   • Once confirmed, check your wallet on the BOB Network to verify the receipt of the bridged tBTC or ETH.

Note: When bridging assets back from the BOB Network, please know that the process can take up to 7 days.

Additionally to the DAO governance bodies, there are three community-led guilds with different focus areas: the Marketing Guild, the Integrations Guild, and the Treasury Guild. Each guild is managed by an elected committee and holds regular, rotating elections.

Join a guild (via Discord's #dao-contribute channel) and work together with other Threshold DAO members based on your interests and expertise!

Treasury Guild

The Threshold Treasury Guild is responsible for effectively managing the Threshold DAO treasury. This includes growing Protocol Owned Liquidity (POL), researching / implementing best practice treasury management strategies, executing ecosystem liquidity incentives, diversifying the treasury, etc.

Integrations Guild

The core mission of the Threshold Integrations Guild is to build successful, synergistic and long-lasting relationships with other protocols, DAOs and external organizations.

Marketing Guild

The Threshold Marketing Guild is responsible for general Threshold marketing, growing our network of contributors, onboarding new members to the Threshold DAO, educating people about the Threshold’s value, services and use cases, and more.

An operator-registering transaction can be submitted with the Keep Client if the staking provider address key file is available.

Authorizing Random Beacon via the Client (Docker)

export KEEP_CLIENT_CONFIG_DIR=$(pwd)/config

export KEEP_CLIENT_ETHEREUM_WS_URL="<Ethereum API WS URL>"

export STAKING_PROVIDER_KEY_FILE_PASSWORD="<Staking Provider Account Key File Password>"
export STAKING_PROVIDER_KEY_FILE_NAME="<Staking Provider Account Key File Name>"
export OPERATOR_ADDRESS="<Operator Account Address>"

docker run \
    --volume $KEEP_CLIENT_CONFIG_DIR:/mnt/keep-client/config \
    --env KEEP_CLIENT_ETHEREUM_PASSWORD=$STAKING_PROVIDER_KEY_FILE_PASSWORD
    us-docker.pkg.dev/keep-test-f3e0/public/keep-client:latest \
    ethereum \
    --ethereum.url $KEEP_CLIENT_ETHEREUM_WS_URL \
    --ethereum.keyFile /mnt/keep-client/config/$STAKING_PROVIDER_KEY_FILE_NAME \
    beacon random-beacon register-operator --submit \
    $OPERATOR_ADDRESS

Authorizing TBTC application via the Client (Docker)

export KEEP_CLIENT_CONFIG_DIR=$(pwd)/config

export KEEP_CLIENT_ETHEREUM_WS_URL="<Ethereum API WS URL>"

export STAKING_PROVIDER_KEY_FILE_PASSWORD="<Staking Provider Account Key File Password>"
export STAKING_PROVIDER_KEY_FILE_NAME="<Staking Provider Account Key File Name>"
export OPERATOR_ADDRESS="<Operator Account Address>"

docker run \
    --volume $KEEP_CLIENT_CONFIG_DIR:/mnt/keep-client/config \
    --env KEEP_CLIENT_ETHEREUM_PASSWORD=$STAKING_PROVIDER_KEY_FILE_PASSWORD
    us-docker.pkg.dev/keep-test-f3e0/public/keep-client:latest \
    ethereum \
    --ethereum.url $KEEP_CLIENT_ETHEREUM_WS_URL \
    --ethereum.keyFile /mnt/keep-client/config/$STAKING_PROVIDER_KEY_FILE_NAME \
    ecdsa wallet-registry register-operator --submit
    $OPERATOR_ADDRESS

Via Web Browser

An operator-registering transactions can be submitted with Etherscan.

For each of the RandomBeacon and WalletRegistry contracts perform the following steps:

1. Find the address of the contract and open it on Etherscan (see below).

2. Go to Contract → Write Contract tab.

3. Connect your wallet with Connect to Web3 button.

4. Submit the registerOperator function with your Operator address as an argument.

IApplication

Generic interface for an application. Application is an external smart contract or a set of smart contracts utilizing functionalities offered by Threshold Network. Applications authorized for the given staking provider are eligible to slash the stake delegated to that staking provider.

RewardsWithdrawn

event RewardsWithdrawn(address stakingProvider, uint96 amount)

Event emitted by withdrawRewards function.

withdrawRewards

function withdrawRewards(address stakingProvider) external

Withdraws application rewards for the given staking provider. Rewards are withdrawn to the staking provider's beneficiary address set in the staking contract.

Emits RewardsWithdrawn event.

authorizationIncreased

function authorizationIncreased(address stakingProvider, uint96 fromAmount, uint96 toAmount) external

Used by T staking contract to inform the application that the authorized amount for the given staking provider increased. The application may do any necessary housekeeping. The application must revert the transaction in case the authorization is below the minimum required.

authorizationDecreaseRequested

function authorizationDecreaseRequested(address stakingProvider, uint96 fromAmount, uint96 toAmount) external

Used by T staking contract to inform the application that the authorization decrease for the given staking provider has been requested. The application should mark the authorization as pending decrease and respond to the staking contract with approveAuthorizationDecrease at its discretion. It may happen right away but it also may happen several months later. If there is already a pending authorization decrease request for the application, and the application does not agree for overwriting it, the function should revert.

involuntaryAuthorizationDecrease

function involuntaryAuthorizationDecrease(address stakingProvider, uint96 fromAmount, uint96 toAmount) external

Used by T staking contract to inform the application the authorization has been decreased for the given staking provider involuntarily, as a result of slashing. Lets the application to do any housekeeping neccessary. Called with 250k gas limit and does not revert the transaction if involuntaryAuthorizationDecrease call failed.

availableRewards

function availableRewards(address stakingProvider) external view returns (uint96)

Returns the amount of application rewards available for withdrawal for the given staking provider.

minimumAuthorization

function minimumAuthorization() external view returns (uint96)

The minimum authorization amount required for the staking provider so that they can participate in the application.

TokenholderGovernorVotes

Tokenholder DAO voting power extraction from both liquid and staked T token positions, including legacy stakes (NU/KEEP).

token

contract IVotesHistory token

staking

contract IVotesHistory staking

constructor

constructor(contract IVotesHistory tokenAddress, contract IVotesHistory tStakingAddress) internal

getVotes

function getVotes(address account, uint256 blockNumber) public view virtual returns (uint256)

Read the voting weight from the snapshot mechanism in the token and staking contracts. For Tokenholder DAO, there are currently two voting power sources:

• Liquid T, tracked by the T token contract

• Stakes in the T network, tracked by the T staking contract. Note that this also tracks legacy stakes (NU/KEEP); legacy stakes count for tokenholders' voting power, but not for the total voting power of the Tokenholder DAO (see {_getPastTotalSupply}).

See {IGovernor-getVotes}

Parameters

_getPastTotalSupply

function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256)

Compute the total voting power for Tokenholder DAO. Note how it only uses the token total supply as source, as native T tokens that are staked continue existing, but as deposits in the staking contract. However, legacy stakes can't contribute to the total voting power as they're already implicitly counted as part of Vending Machines' liquid balance; hence, we only need to read total voting power from the token.

Parameters

BytesLib

concatStorage

function concatStorage(bytes _preBytes, bytes _postBytes) internal

equalStorage

function equalStorage(bytes _preBytes, bytes _postBytes) internal view returns (bool)

concat

function concat(bytes _preBytes, bytes _postBytes) internal pure returns (bytes)

slice

function slice(bytes _bytes, uint256 _start, uint256 _length) internal pure returns (bytes res)

toAddress

function toAddress(bytes _bytes, uint256 _start) internal pure returns (address)

toUint8

function toUint8(bytes _bytes, uint256 _start) internal pure returns (uint8)

toUint

function toUint(bytes _bytes, uint256 _start) internal pure returns (uint256)

equal

function equal(bytes _preBytes, bytes _postBytes) internal pure returns (bool)

toBytes32

function toBytes32(bytes _source) internal pure returns (bytes32 result)

keccak256Slice

function keccak256Slice(bytes _bytes, uint256 _start, uint256 _length) internal pure returns (bytes32 result)

ProxyAdminWithDeputy

Based on ProxyAdmin, an auxiliary contract in OpenZeppelin's upgradeability approach meant to act as the admin of a TransparentUpgradeableProxy. This variant allows an additional actor, the "deputy", to perform upgrades, which originally can only be performed by the ProxyAdmin's owner. See OpenZeppelin's documentation for TransparentUpgradeableProxy for more details on why a ProxyAdmin is recommended.

deputy

address deputy

DeputyUpdated

event DeputyUpdated(address previousDeputy, address newDeputy)

onlyOwnerOrDeputy

modifier onlyOwnerOrDeputy()

constructor

constructor(contract StakerGovernor dao, address _deputy) public

setDeputy

function setDeputy(address newDeputy) external

upgrade

function upgrade(contract TransparentUpgradeableProxy proxy, address implementation) public virtual

Upgrades proxy to implementation. This contract must be the admin of proxy, and the caller must be this contract's owner or the deputy.

upgradeAndCall

function upgradeAndCall(contract TransparentUpgradeableProxy proxy, address implementation, bytes data) public payable virtual

Upgrades proxy to implementation and calls a function on the new implementation. This contract must be the admin of proxy, and the caller must be this contract's owner or the deputy.

_setDeputy

function _setDeputy(address newDeputy) internal

_checkCallerIsOwnerOrDeputy

function _checkCallerIsOwnerOrDeputy() internal view

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're locking up the funds using our specific locking script. This creates an Unspent Transaction Output (UTXO).

Typically, the job of a bitcoin "wallet" (wallets don't exist in the same way that they do on ethereum) is to scan the blockchain for particular locking script patterns that it thinks it can unlock (like a P2PKH script associated to 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 to 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 for if something goes wrong with the protocol or deposit.

As a result of this, we give ourselves 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 take all of the recent deposits, unlock them, and then send the funds using a normal P2PKH script back to the wallet itself, consolidating the UTXOs into a single UTXO.

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

Example

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

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

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

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

B. Protocol is a third-party decentralized backstop liquidity protocol aiming to make lending platforms more stable.

The problem

In Liquity Protocol there's a concept called "Stability Pool". The purpose of the stability pool is to purchase liquidated collateral (tBTC) at a discount by using Threshold USD (thUSD) as payment.

Users deposits thUSD into the stability pool and their funds are pooled with other depositors. If a pool consist of 900,000 thUSD and a user deposits 100,000 thUSD, that user is entitled to 10% of the collateral seized.

The issue with stability pool is that as liquidations occurs, thUSD is traded to tBTC, but never back to thUSD. If left untouched, the pool will eventually only consist of tBTC and no further liquidations can take place against the pool. Furthermore, by acquiring tBTC collateral, the value for depositors in the pool becomes subject to the price of BTC.

Users are therefore incentivized to quickly sell of the tBTC for thUSD to avoid taking on price risk, but in Liquity, this process is manual. Users have to manually open the UI and withdraw tBTC, sell it for thUSD and then re-deposit the thUSD. This is both a time consuming and gas costly operation, best suited for whales and users with their own bots.

Even worse, a DAO cannot realistically operate in the current stability pool model because voting to move and sell funds becomes impractical, costly and slow.

In order to establish a non-human, algorithmic, fully automated solution to compound profits we look to B.Protocol.

B.Protocol to the rescue

Instead of depositing directly into the stability pool, we can use B.Protocol's wrapping smart contract interface, which deposits the thUSD to the stability pool on behalf of all users (and the PCV).

Once liquidation happens, the discounted tBTC is automatically offered for sale by B.Protocol’s Backstop AMM (B.AMM). This is done according to a deterministic formula, which takes into account the current tBTC and thUSD inventory, and the current BTC-USD market price (which is taken from Chainlink). Whenever the sale occurs, the smart contract deposits the returned thUSD back to the stability pool.

If there are no takers for the offer on the B.AMM, Gelato Keepers will arbitrage through popular DEX pairs to fulfill the order.

This way the PCV becomes self-sufficient and able to operate indefinitely without outside interference.

Integration details

B.Protocol Team will deploy a non-upgradeable pool that is Threshold USD compatible.

The pool will be using Chainlink BTC/USD oracle (same as Threshold USD).

The pool will not deploy idle funds in any yield farming applications.

Threshold USD PCV will whitelist the smart contract for the B.Protocol pool and the Threshold Network DAO (T DAO) will vote to initiate a deposit of thUSD to the B.Protocol pool. The deposit is moved from the PCV smart contract to B.Protocol and can be moved back to the PCV at any time, without limitation, as long as the T DAO votes to do so. If there is tBTC in the pool at the time of withdraw, the tBTC may also be transferred back to the PCV.

The B.AMM contract's "A" parameter ("A" is amplification factor​​​, higher value means less slippage) is operated through a co-ownership between T DAO and B.Protocol, where B.Protocol propose "A" value and T DAO can approve or reject.

The discount rate is set to 4% on deployment, but the max rate should be configurable up to 10% in a joint governance mechanism between T DAO & B.Protocol.

All profits from liquidations will auto-compound within the B. Protocol pool.

Keeper

As a backup mechanism, B. Protocol will deploy Gelato keepers that can route.

Example:​

tBTC -> WBTC -> USDC -> thUSD

In this example funds could be routed through Curve Finance pools (both stablecoin and wrapped bitcoin pools).

In addition, funds could be routed through uniswap (v2 or v3) WBTC or USDC paired pools.

Other routes could be:

tBTC -> WBTC -> DAI -> thUSD tBTC -> WBTC -> USDT -> thUSD

The keeper is funded by the DAO and any profit it makes is distributed back to the PCV.

​

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

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 system was designed from the outset to be fully permissionless - anyone with the minimum amount of T stake, could run a node and have a of being a custodian.

In order to effectively ship the product, we launched with a permissioned set of Signers, as well as permissioned sets of Guardians and Minters. This document will explain the ideas behind those changes and what we're doing about it going forward.

TL;DR

• tBTC currently uses a permissioned set of signers (aka ) operating under an honest-majority assumption.

• The permissioned honest-majority signer set will remain in place until custody is upgraded to a 1-of-N trust assumption using BitVM2 (or an equivalent design).

Permissionless Custodianship

To select the 100 signers for a wallet, tBTC selects from the permissioned list of Beta Stakers. This decision was made for several reasons:

1. During the early days of the system; the testnet and phases, it is important to ensure that signers are available to help test changes and quickly respond to critical bugs. Having direct access to individuals known to the development team is critical in this context.

2. The underlying signature algorithm, , cannot identify misbehaving signers.

The point about GG18 is crucial. Without being able to identify misbehaving signers, a small, sophisticated, malicious minority can make it difficult to sign Bitcoin transactions in a timely manner. If we were able to identify the misbehaving signers, we could exclude them directly from the signing process.

Although alternative algorithms exist for identifying misbehaving signers, they are not yet viable for production use for one or more of the following reasons:

• They are not yet codebases.

• They are not open source.

• They exist only as whitepapers.

To address this issue, we have been developing a proof-of-concept for and exploring .

Recent advances in Bitcoin bridge design, specifically BitVM2, suggest the possibility of improving custody from an honest-majority assumption to a 1-of-N trust assumption. Threshold Network is closely monitoring the development of this design and various implementations, with the medium-term intent of upgrading tBTC's underlying custody mechanics once the technology is sufficiently mature.

Guardians and Minters

Guardians and Minters are a permissioned set of high-trust public operators with their reputations on the line.

Guardians are responsible for validating mint and redemption requests, and have the ability to veto malicious or fraudulent requests. If we were to make these lists permissionless, a malicious Minter could flood the system with fake minting requests for the Guardians to deal with, or a malicious Guardian could veto every proposed mint to halt growth.

If a Guardian or Minter misbehaves, the can vote to remove them.

Minters serve a convenience function by enabling "fast minting." Importantly, they do not have the ability to gatekeep mint requests; any deposit that all Minters refuse to approve or that a Guardian refuses to accept can still be minted every eight hours by the signers. This ensures that the system remains resilient and able to handle situations in which a malicious actor attempts to disrupt the minting process.

What is the Stability Pool?

The Stability Pool is the first line of defense in maintaining system solvency. It achieves that by acting as the source of liquidity to repay debt from liquidated Vaults—ensuring that the total thUSD supply always remains backed.

When any Vault is liquidated, an amount of thUSD corresponding to the remaining debt of the Vault is burned from the Stability Pool’s balance to repay its debt. In exchange, the entire collateral from the Vault is transferred to the Stability Pool.

The Stability Pool is funded by users transferring thUSD into it (called Stability Providers). Over time Stability Providers lose a pro-rata share of their thUSD deposits, while gaining a pro-rata share of the liquidated collateral. However, because Vaults are likely to be liquidated at just below 110% collateral ratios, it is expected that Stability Providers will receive a greater dollar-value of collateral relative to the debt they pay off.

Why should I deposit thUSD to the Stability Pool?

Stability Pool Providers will make liquidation gains.

What are liquidations?

To ensure that the entire Stablecoin supply remains fully backed by collateral, Vaults that fall under the minimum collateral ratio of 110% will be closed (liquidated).

The debt of the Vault is canceled and absorbed by the Stability Pool and its collateral distributed among Stability Providers.

The owner of the Vault still keeps the full amount of thUSD borrowed but loses ~10% value overall hence it is critical to always keep the ratio above 110%, ideally above 150%.

Who can liquidate Vaults?

Anybody can liquidate a Vault as soon as it drops below the Minimum Collateral Ratio of 110%. The initiator receives a gas compensation (200 thUSD + 0.5% of the Vaults collateral) as reward for this service.

How am I compensated for liquidating a Vault?

The liquidation of Vaults is connected with certain gas costs which the initiator has to cover. The cost per Vault was reduced by implementing batch liquidations of up to 160 - 185 Vaults but with the aim of ensuring that liquidations remain profitable even in times of soaring gas prices the protocol offers a gas compensation given by the following formula:

gas compensation = 200 thUSD + 0.5% of Vault's collateral (ETH)

The 200 thUSD is funded by a Liquidation Reserve while the variable 0.5% part (in tBTC) comes from the liquidated collateral, slightly reducing the liquidation gain for Stability Providers.

How do I benefit as a Stability Provider from liquidations?

As liquidations happen just below a collateral ratio of 110%, you will most likely experience a net gain whenever a Vault is liquidated.

Let’s say there is a total of 1,000,000 thUSD in the Stability Pool and your deposit is 100,000 thUSD.

Now, a Vault with debt of 200,000 thUSD and collateral of 10.9 tBTCis liquidated at a tBTC price of $20,000, and thus at a collateral ratio of 109% (= 100% * (10.9 * 20,000) / 200,000). Given that your pool share is 10%, your deposit will go down by 10% of the liquidated debt (20,000 thUSD), i.e. from 100,000 to 80,000 thUSD. In return, you will gain 10% of the liquidated collateral, i.e. 1.09 tBTC, which is currently worth $21,800. Your net gain from the liquidation is $1,800.

Note that depositors can immediately withdraw the collateral received from liquidations and sell it to reduce their exposure to tBTC, if the USD value of tBTC is expected to decrease (for an exception see the next section).

Can I withdraw my deposit whenever I want?

As a general rule, you can withdraw the deposit made to the Stability Pool at any time. There is no minimum lockup duration. However, withdrawals are temporarily suspended whenever there are liquidatable Vault with a collateral ratio below 110% that have not been liquidated yet.

What Oracle are you using to determine the price of tBTC?

The protocol uses price feed, falling back to the tBTC:USD oracle under the following (extreme) conditions:

• Chainlink price has not been updated for more than 4 hours

• Chainlink response call reverts, returns an invalid price or an invalid timestamp

• The price change between two consecutive Chainlink price updates is >50%.

Can I lose money by depositing funds to the Stability Pool?

While liquidations will occur at a collateral ratio well above 100% most of the time, it is theoretically possible that a Vault gets liquidated below 100% in a flash crash or due to an oracle failure. In such a case, you may experience a loss since the collateral gain will be smaller than the reduction of your deposit.

If thUSD is trading above $1, liquidations may become unprofitable for Stability Providers even at collateral ratios higher than 100%. However, this loss is hypothetical since thUSD is expected to return to the peg, so the “loss” only materializes if you had withdrawn your deposit and sold the thUSD at a price above $1.

Please note that although the system is diligently audited, a hack or a bug that results in losses for the users can never be fully excluded.

What happens if the Stability Pool is empty when liquidations occur?

If the Stability Pool is empty, the system uses a secondary liquidation mechanism called redistribution. In such a case, the system redistributes the debt and collateral from liquidated Vaults to all other existing Vaults. The redistribution of debt and collateral is done in proportion to the recipient Vault's collateral amount.

This document is intended for members of the community who would like to run their own tBTC v2 node.

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

T

Threshold Network T token

By default, token balance does not account for voting power. This makes transfers cheaper. The downside is that it requires users to delegate to themselves to activate checkpoints and have their voting power tracked.

DELEGATION_TYPEHASH

The EIP-712 typehash for the delegation struct used by delegateBySig.

constructor

delegateBySig

Delegates votes from signatory to delegatee

Parameters

delegate

Delegate votes from msg.sender to delegatee.

Parameters

beforeTokenTransfer

Hook that is called before any transfer of tokens. This includes minting and burning.

Calling conditions:

• when from and to are both non-zero, amount of from's tokens will be to transferred to to.

• when from is zero, amount tokens will be minted for to.

• when to is zero, amount of from's tokens will be burned.

• from and to are never both zero.

delegate

Change delegation for delegator to delegatee.

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

RandomBeaconChaosnet

A stub contract that will be used temporarily until the real-world random beacon client implementation is ready.

authorizedRequesters

Authorized addresses that can request a relay entry.

entry

Arbitrary relay entry. Initially set to the Euler's number. It's updated after each relay entry request.

RequesterAuthorizationUpdated

requestRelayEntry

Executes the callback with an arbitrary relay entry number.

The caller must be an authorized requester.

Parameters

setRequesterAuthorization

Authorizes a requester of the relay entry.

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:

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:

Reimbursable

reimbursementPool

ReimbursementPoolUpdated

refundable

onlyReimbursableAdmin

updateReimbursementPool

The primary wallet responsibility is taking care of Bitcoins deposited by tBTC users. Whenever a wallet needs to move some Bitcoins due to a protocol action (e.g. deposit sweep or redemption), it must assemble an appropriate Bitcoin transaction and sign each transaction's input using the tECDSA signing algorithm. During the tECDSA signing, randomly selected 51-of-100 wallet signers must collaborate to produce a proper signature.

Anatomy of a signing attempt

A single tECDSA signing attempt consists of several steps. Each step has a maximum duration expressed in the specific number of host chain (e.g. Ethereum) blocks:

1. Signers readiness announcement phase which takes exactly 6 blocks

2. Signature production & advertisement phase which takes up to 30 blocks

3. Cooldown period that takes exactly 5 blocks

That means a single signing attempt can take up to 41 blocks (~8 minutes on Ethereum, assuming 12 seconds as the average block time). If the signature is not produced during that time, wallet signers give up the signing attempt and retry.

Signing retries

A wallet that is asked to sign the given message (e.g. Bitcoin transaction input) does not limit itself to a single tECDSA signing attempt. Due to the distributed nature of the signing algorithm, a single signing attempt may fail due to, for example, some unexpected network problems affecting inter-signer communication. If the first signing attempt fails, another set of randomly selected 51 wallet signers retry signing during the next attempt. Subsequent signing attempts are scheduled on fixed intervals, based on the block the first attempt started at, and the known maximum duration of a single attempt (41 blocks). For example, if the first attempt started at the block B, subsequent attempts will be scheduled as follows:

• Attempt 2 -> B + 41

• Attempt 3 -> B + 82

• Attempt N -> B + (N-1) * 41

The wallet always executes 5 signing attempts at maximum. Such a count of maximum attempts is an acceptable trade-off between a reasonable signing timeout and a sufficient tolerance for misbehaving wallet signers. Executing 5 signing attempts allows trying 5 different 51-signer subsets. This is enough to produce a signature even for an unlikely scenario of 2 misbehaving wallet signers. In that case, 51 signers must be selected out of the honest 98 signers. That means the probability of selecting a successful subset is:

P = (98 choose 51) / (100 choose 51) = ~0.24

which means 5 selections are required in the worst case.

Combining the 5 signing attempts at maximum with up to 41 blocks per single attempt means the wallet will try to sign the given message for 5*41 = 205 blocks (~40 minutes on Ethereum, assuming 12 seconds as the average block time). If the signature is not produced during that time, wallet signers give up ultimately.

Serial signing

Wallets have the ability to sign multiple messages (e.g. multiple inputs of a single Bitcoin transaction) in a serial manner, one message after another. In such a case, the whole signing process is successful only if all messages in the batch obtained their signatures.

As mentioned in the previous section, the maximum allowed time for signing a single message is 205 blocks (~40 minutes on Ethereum). That means the maximum time to sign a batch of N messages is N*205 blocks. During that time, the wallet cannot perform any other work as signing is computationally heavy. This factor must be taken into account while building wallet actions that leverage signing.

Signing as the foundation of wallet actions

The tBTC protocol defines a finite set of wallet actions:

• Heartbeat

• Deposit sweep

• Redemption

• Moving funds

• Moved funds sweep

Each action involves wallet signing under the hood. The time necessary to complete the given action depends on how many signatures must be produced during execution. Knowing the worst-case time necessary to produce a single signature (205 blocks) and the number of signatures that may be required by the given action, we can set the right time boundaries for specific actions. This information is crucial for proper wallet coordination.

Example: Deposit sweep

Let's use the Deposit sweep action to show how signing affects wallet actions. This action is initiated by a coordinator that submits a deposit sweep proposal through the WalletCoordinator chain contract. An expected outcome of that action is a Bitcoin transaction with multiple inputs (swept deposits) and one output, submitted to the Bitcoin chain. That means the action's execution time strongly depends on the number of deposits suggested as part of the given sweep proposal. The WalletCoordinator contract has some governable parameters that impact the Deposit sweep action:

• depositSweepMaxSize that sets the maximum number of deposits within a single sweep proposal

• depositSweepProposalValidity which determines the proposal's validity time. This is an exclusive time the wallet obtains to execute the given sweep and no other actions can be taken meanwhile

In other words, the wallet can sweep up to depositSweepMaxSize deposits and has depositSweepProposalValidity time to do so.

Signing is the most important and complex step of the Deposit sweep action and the reference client implementation sets the signing timeout to be depositSweepProposalValidity - 1 hour for all inputs of the sweep transaction. Producing a signature for a single deposit input may take up to 205 blocks (5 attempts underneath). This is ~40 minutes assuming Ethereum's average block time of 12 seconds. Having that in mind, the aforementioned WalletCoordinator governable parameters must be chosen with care as they have a strong impact on signing execution:

• If depositSweepMaxSize = 5 and depositSweepProposalValidity = 4 hours, the wallet will try to sign 5 inputs in 3 hours which gives ~36 minutes per input. As 5 signing attempts take ~40 minutes, this configuration will allow for 4 attempts per input

• If depositSweepMaxSize = 10 and depositSweepProposalValidity = 4 hours, the wallet will try to sign 10 inputs in 3 hours which gives ~18 minutes per input. As 5 signing attempts take ~40 minutes, this configuration will allow for 2 attempts per input

• If depositSweepMaxSize = 20 and depositSweepProposalValidity = 4 hours, the wallet will try to sign 20 inputs in 3 hours which gives ~9 minutes per input. As 5 signing attempts take ~40 minutes, this configuration will allow for 1 attempt per input

Download the Binary

See GitHub for the latest release: https://github.com/keep-network/keep-core/releases

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

cd /home/keep
wget https://github.com/keep-network/keep-core/releases/download/XX.X.X-XX/keep-client-mainnet-XX.X.X-XX-linux-amd64.tar.gz

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

ls -la

Extract the compressed file:

tar xzvf downloaded-file-name-here.tar.gz

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:

--ethereum.url "wss://mainnet-ETH-enpoint-here"
--storage.dir "/home/keep/storage"
--ethereum.keyFile "/home/keep/config/UTC--Your-Operator-Key-Name"
# to configure your node to use your machine's public IP
--network.announcedAddresses "/ip4/your.ipv4.address.here/tcp/3919"
# to configure your node to use DNS, provide your DNS in the following
# format
# /dns4/bootstrap-1.test.keep.network/tcp/3919

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

To launch the client, execute the following:

./keep-client start --ethereum.url "wss://mainnet-ETH-enpoint-here" --storage.dir "/home/keep/storage" --ethereum.keyFile "/home/keep/config/UTC--Your-Operator-Key-Name" --network.announcedAddresses "/ip4/your.ipv4.address.here/tcp/3919"

If everything is configured correctly, the client will request the password for the Operator Account. Supply the password and press Enter.

You should see the following shortly:

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

Trust math, not hardware.
	
-----------------------------------------------------------------------------------
| Keep Client Node                                                                |
|                                                                                 |
| Version: Version: vX.X.X-XX (4d745f6d0)                                         |
|                                                                                 |
| Operator: 0x_your_operator_address                                              |
|                                                                                 |
| Port: 3919                                                                      |
| IPs : /ip4/111.222.333.444/tcp/3919/ipfs/redacted                               |
|                                                                                 |
| Contracts:                                                                      |
| RandomBeacon   : 0x5499f54b4A1CB4816eefCf78962040461be3D80b                     |
| WalletRegistry : 0x46d52E41C2F300BC82217Ce22b920c34995204eb                     |
| TokenStaking   : 0x01B67b1194C75264d06F808A921228a95C765dd7                     |
-----------------------------------------------------------------------------------

Congratulations, your node is up and running.

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

BeaconInactivity

Claim

struct Claim {
  uint64 groupId;
  uint256[] inactiveMembersIndices;
  bytes signatures;
  uint256[] signingMembersIndices;
}

groupThreshold

uint256 groupThreshold

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

signatureByteSize

uint256 signatureByteSize

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

verifyClaim

function verifyClaim(contract SortitionPool sortitionPool, struct BeaconInactivity.Claim claim, bytes groupPubKey, uint256 nonce, uint32[] groupMembers) external view returns (uint32[] inactiveMembers)

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

Group members hash is validated upstream in RandomBeacon.notifyOperatorInactivity()

Parameters

Return Values

validateMembersIndices

function validateMembersIndices(uint256[] indices, uint256 groupSize) internal pure

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

Parameters

Wallets are created periodically based on governance. changes the time between wallets and reads it. The time between new wallets is held in walletCreationPeriod in number of seconds, so the current value of 1209600 represents 14 days. In order for the wallet to move funds, it produces signatures using a , requiring 51-of-100 Signers to cooperate.

The 100 signers on each wallet are chosen with our , and the randomness is provided by the .

The probability that a is chosen to be a Signer is equal to their percentage of the total TBTC Stake. Each Signer is chosen independently. The same Staker can be a signer on the same wallet multiple times. The same Staker can be a Signer on multiple wallets simultaneously.

Examples

For simplicity, say there are only three Stakers: Alice, Bob, and Carol. Alice has 250M T, Bob has 400M T, and Carol has 350M T staked, so they own 25%, 40% and 35% of the stake respectively. That means, Alice has a 25% chance to be a Signer, Bob has a 40% chance, and Carol has a 35% chance. Each Signer is selected independently.

The Sortition Pool is more complex (because of heavy gas optimization), but reasoning about it could look like this: For each Signer, we're going to generate a random number between 1 and 100. Alice is the Signer if the number is in [1, 25]. Bob is the Signer if the number is in [26, 65]. Carol is the Signer if the number is in [66, 100]. For example, if our first is 33, our first Signer would be Bob. We can generate 100 random numbers: (75, 51, 13, 48, 36, 62, 46, 65, 97, 67...), and then use that to determine Signers: (Carol, Bob, Alice, Bob, Bob, Bob, Bob, Bob, Carol, Carol...). This example illustrates a few properties mentioned earlier:

• Each Signer is selected independently. Whether or not Carol is the first signer has no influence on Carol being the second Signer.

• The chance that you become a particular Signer is equal to your share of the Stake.

Statistics

If Carol has a 35% chance of being a particular Signer, what are chances that Carol has at least 51 of the 100 seats (and could control the wallet by herself)?

The number of Signers that Carol controls on a wallet is modeled by the . From wikipedia:

A Binomial distribution with parameters n and p is the of the number of successes in a sequence of n , each asking a , and each with its own -valued : success (with probability p) or failure (with probability 1−p).

This is exactly our situation! From Carol's perspective, there will be n=100 independent experiments, each asking a yes-no question (does this Signer belong to Carol), each with a 35% probability.

That means we can use a to answer our question:

It's the last figure: "Cumulative probability: P(X>51)" that's relevant. That says there is a ~0.074% chance that Carol would have a controlling Share of any particular wallet.

The next important question is "The probability that Carol controls a Wallet is low, but it only needs to happen once for things to be bad. What is the probability that she controls any wallet in the next 2 years?"

A wallet is generated every 14 days, so over the next 2 years, the system would generate ~52 wallets. Each wallet has a 1 - 0.00074 = .99926 or 99.926% chance of not being controlled by Carol. That means we can exponentiate:

Carol would have a ~3.8% chance of getting control of a wallet in 2 years. That's with her owning 35% of the total Stake! Alice has a much lower chance. She has a 0.0002131% chance of controlling a wallet, which means that over the course of 52 wallets, she has a 0.02131% chance of controlling any wallet in 2 years.

As of writing, the *largest* Staker controls .

Sybil Resistance

The only thing that a Staker accomplishes by splitting up their Stake into multiple identities is making the system appear to be more diverse.

For example, say that Alice split up her Stake equally into 5 accounts: Alice1, Alice2, Alice3, Alice4, and Alice5. Now, rather than Alice having a 25% chance to be a Signer, each account has a 5% chance which collectively add up to 25%.

To use the example from earlier: Alice has 250M T, Bob has 400M T, and Carol has 350M T staked. Alice has her T split into 50M for each identity. Alice1 would own 50M/1000M = 5%. Keeping with the simplification of assigning numbers from 1 to 100 to identities, Alice1 would get [1, 5], Alice2 gets [6, 10], Alice3 gets [11, 15], Alice4 gets [16, 20], Alice5 gets [21, 25], Bob gets [26, 65], Carol gets [66, 100]. If we use the same random numbers as before, (75, 51, 13, 48, 36, 62, 46, 65, 97, 67...), then we make the assignments as (Carol, Bob, Alice3, Bob, Bob, Bob, Bob, Bob, Carol, Carol...). Nothing has effectively changed!

DAO Rules

Inaugural Rules for the DAO

DAO rules were created with the inception of the DAO, and are mostly reflected in our forum, we refer as early rules to TIP-002, TIP-007, TIP-013, TIP-020, TIP-026 and TIP-032.

TIP-002:

TIP-002, outlined by Matt Luongo, describes the creation of the DAO, the different bodies and the general ways we interact with each other.

TIP-007:

TIP-007, outlined by Arj, describes the requirement of a minimum stake size for the Threshold Network stakers, at the moment of the network genesis.

TIP-013:

TIP-013, outlined by Will, describes the creation of the DAO Guilds, and its inner workings.

TIP-020:

TIP-020, outlined by Arj, describes the incentives for Threshold Network stakers at the interim era.

TIP-026:

TIP-026, outlined by Will, outlines our governance processes, and creates a template to be followed when creating TIPs.

TIP-032:

TIP-032, outlined by Arj, supersedes TIP-020 and establishes the reward allocation for stakers between the DAO products.

Rules for Guilds and Proposals Management

In 2022, the DAO lead an effort to improve our governance processes, leading to the creation and vote of several DAO rules. This endeavour was lead by the , a group of 3 people volunteered from each of the guilds + the DAO PM. The outcome of this workgroup was the creation of TIP-031 and TIP-034.

TIP-031:

TIP-031, outlined by the rules committee, establishes the rules for the DAO Guilds elections and management.

TIP-034:

TIP-034, outlined by the rules committee, extends TIP-026 by providing a more defined view to the way proposals are created for the DAO, outlining best practices and guidelines.

GP-021:

GP-021, outlined by ZeroInFo, details the expansion of the Integrations Guild Committee, increasing 2 seats.

TIP-049:

TIP-049, outlined by John Packel, describes the restructuring of the Marketing Guild Committee.

Additional Rules for Elections

TC-003:

TC-003, outlined by Luna5, outlines the alignment of the Council elections with the Guilds on the month of March, and removes the staggered elections for the Council.

GovernorParameters

Abstract contract to handle governance parameters

Based on GovernorVotesQuorumFraction, but without being opinionated on what's the source of voting power, and extended to handle proposal thresholds too. See OpenZeppelin's GovernorVotesQuorumFraction, GovernorVotes and GovernorSettings for reference.

FRACTION_DENOMINATOR

AVERAGE_BLOCK_TIME_IN_SECONDS

quorumNumerator

proposalThresholdNumerator

QuorumNumeratorUpdated

ProposalThresholdNumeratorUpdated

VotingDelaySet

VotingPeriodSet

constructor

updateQuorumNumerator

updateProposalThresholdNumerator

setVotingDelay

Update the voting delay. This operation can only be performed through a governance proposal. Emits a VotingDelaySet event.

setVotingPeriod

Update the voting period. This operation can only be performed through a governance proposal. Emits a VotingPeriodSet event.

quorum

Compute the required amount of voting power to reach quorum

Parameters

proposalThreshold

Compute the required amount of voting power to create a proposal at the last block height

This function is implemented to comply with Governor API but we we will actually use proposalThreshold(uint256 blockNumber), as in our DAOs the threshold amount changes according to supply.

proposalThreshold

Compute the required amount of voting power to create a proposal

Parameters

votingDelay

module:user-config

Delay, in number of block, between the proposal is created and the vote starts. This can be increassed to leave time for users to buy voting power, of delegate it, before the voting of a proposal starts.

votingPeriod

module:user-config

Delay, in number of blocks, between the vote start and vote ends.

NOTE: The {votingDelay} can delay the start of the vote. This must be considered when setting the voting duration compared to the voting delay.

_updateQuorumNumerator

_updateProposalThresholdNumerator

_setVotingDelay

_setVotingPeriod

_getPastTotalSupply

Compute the past total voting power at a particular block

Parameters

Why would I use Threshold USD for borrowing?

Threshold USD protocol offers low interest loans and is more capital efficient than other borrowing systems (i.e. less collateral is needed for the same loan). Instead of selling tBTC to have liquid funds, you can use the protocol to lock up your tBTC, borrow against the collateral to withdraw thUSD, and then repay your loan at a future date.

For example: Borrowers speculating on future tBTC price increases can use the protocol to leverage their tBTC positions up to 11 times, increasing their exposure to price changes. This is possible because thUSD can be borrowed against tBTC, sold on the open market to purchase more tBTC — rinse and repeat.*

*Note: This is NOT a recommendation for how to use Threshold USD. Leverage can be very risky as you can lose all your funds and should be used only by those with experience and for speculative amounts.

What do you mean by collateral?

Collateral is any asset which a borrower must provide to take out a loan, acting as a security for the debt.

Is tBTC the only collateral accepted by Threshold USD?

Currently, Threshold USD supports tBTC and ETH as collateral but additional collaterals could be added as voted by governance, as the code allows for it. The reasoning behind having these two collaterals is that they represent the two most decentralized assets in the Ethereum Ecosystem.

How can I borrow with Threshold USD?

To borrow you must open a Vault and deposit a certain amount of collateral (tBTC) to it. Then you can draw thUSD up to a collateral ratio of 110%. A minimum debt of 2,000 thUSD is required. This minimum debt threshold prevents an attacker from creating a large number of Vaults that are then unprofitable to liquidate.

What is a Vaults?

A Vault is where you take out and maintain your loan. Each Vault is linked to an Ethereum address and each address can have just one Vault. If you are familiar with Troves or CDPs from other platforms, Vault are similar in concept.

Vaults maintain two balances: one is an asset (tBTC) acting as collateral and the other is a debt denominated in thUSD. You can change the amount of each by adding collateral or repaying debt. As you make these balance changes, your Vault’s collateral ratio changes accordingly.

You can close your Vault at any time by fully paying off your debt.

Do I have to pay fees as a borrower?

For the base situation, see the section “Does Threshold USD charge any fees?”

Every time you draw thUSD from your Vault, a one-off borrowing fee is charged on the drawn amount and added to your debt. Please note that the borrowing fee is variable (and determined algorithmically) and has a minimum value of 0.5% under normal operation. The fee is 0% during Recovery Mode.

A 200 thUSD Liquidation Reserve charge will be applied as well, but returned to you upon repayment of debt.

How is the borrowing fee calculated?

When a Loan is opened, the borrowing fee is added to the debt of the Vault and is given by a baseRate . The fee rate is confined to a range between 0.5% and 5% and is multiplied by the amount of liquidity drawn by the borrower.

For example: The borrowing fee stands at 0.5% and the borrower wants to receive 4,000 thUSD to their wallet. Being charged a borrowing fee of 20.00 thUSD, the borrower will incur a debt of 4,220 thUSD after the Liquidation Reserve and issuance fee are added.

When do I need to pay my loan back?

Loans issued by the protocol do not have a repayment schedule. You can leave your Vault open and repay your debt any time, as long as you maintain a collateral ratio of at least 110%.

What is the collateral ratio?

This is the ratio between the Dollar value of the collateral in your Vault and its debt in thUSD. The collateral ratio of your Vault will fluctuate over time as the price of tBTC changes. You can influence the ratio by adjusting your Vault’s collateral and/or debt — i.e. adding more tBTC collateral or paying off some of your debt.

For example: Let’s say the current price of tBTC is $30,000 and you decide to deposit 1 tBTC. If you borrow 10,000 thUSD, then the collateral ratio for your Vault would be 200%.

(1tBTC * $30,000/​10,000 thUSD)*100 = 300%

​If you instead took out 15,000 thUSD that would put your ratio at 200%.

What is the minimum collateral ratio (MCR) and the "recommended" collateral ratio?

The minimum collateral ratio (or MCR for short) is the lowest ratio of debt to collateral that will not trigger a liquidation under normal operations (aka Normal Mode). This is a protocol parameter that is set to 110%. So if your Vault has a debt of 10,000 thUSD, you would need at least $11,000 worth of tBTC posted as collateral to avoid being liquidated.

To avoid liquidation during Recovery Mode, it is recommended to keep the ratio comfortably above 150% (e.g. 200% or better 250%).

What happens if my Vault is liquidated?

You lose your collateral as your debt is paid off through liquidation, i.e. you will no longer be able to retrieve your collateral by repaying your debt. A liquidation thus results in a net loss of 9.09% (= 100% * 10 / 110) of your collateral’s Dollar value.

What is the Liquidation Reserve?

When you open a Vault and draw a loan, 200 thUSD is set aside as a way to compensate gas costs for the transaction sender in the event your Vault gets liquidated. The Liquidation Reserve is fully refundable if your Vault is not liquidated, and is given back to you when you close your Vault by repaying your debt. The Liquidation Reserve counts as debt and is taken into account for the calculation of a Vault's collateral ratio, slightly increasing the actual collateral requirements.

What happens if my Vault is redeemed against?

When thUSD is redeemed, the tBTC provided to the redeemer is allocated from the Vault(s) with the lowest collateral ratio (even if it is above 110%). If at the time of redemption you have the Vault with the lowest ratio, you will give up some of your collateral, but your debt will be reduced accordingly.

The USD value by which your tBTC collateral is reduced corresponds to the nominal thUSD amount by which your Vault’s debt is decreased. You can think of redemptions as if somebody else is repaying your debt and retrieving an equivalent amount of your collateral. As a positive side effect, redemptions improve the collateral ratio of the affected Vaults, making them less risky.

Redemptions that do not reduce your debt to 0 are called partial redemptions, while redemptions that fully pay off a Vault’s debt are called full redemptions. In such a case, your Vault is closed, and you can claim your collateral surplus and the Liquidation Reserve at any time.

Let’s say you own a Vault with 2 tBTC collateralized and a debt of 32,000 thUSD. The current price of tBTC is $20,000. This puts your collateral ratio (CR) at 125% (= 100% * (2 * 20,000) / 32,000). Let’s imagine this is the lowest CR in the Threshold USD system and look at two examples of a partial redemption and a full redemption:

Example of a partial redemption

Somebody redeems 12,000 thUSD for 0.6 tBTC and thus repays 12,000 thUSD of your debt, reducing it from 32,000 thUSD to 20,000 thUSD. In return, 0.6 tBTC, worth $12,000, is transferred from your Vault to the redeemer. Your collateral goes down from 2 to 1.4 tBTC, while your collateral ratio goes up from 125% to 140% (= 100% * (1.4 * 20,000) / 20,000).

Example of a full redemption

Somebody redeems 60,000 thUSD for 3 tBTC. Given that the redeemed amount is larger than your debt minus 200 thUSD (set aside as a Liquidation Reserve), your debt of 32,000 thUSD is entirely cleared and your collateral gets reduced by $30,000 of tBTC, leaving you with a collateral of 0.5 tBTC (= 2 - 30,000 / 20,000).

How can you offer a collateral ratio as low as 110%?

By making liquidation instantaneous and more efficient, Threshold USD needs less collateral to provide the same security level as similar protocols that rely on lengthy auction mechanisms to sell off collateral in liquidations.

How can I take advantage of leverage?

You can sell the borrowed thUSD on the market for tBTC and use the latter to top up the collateral of your Vault. That allows you to draw and sell more thUSD, and by repeating the process you can reach the desired leverage ratio.

Note: This is NOT a recommendation for how to use Threshold USD. Leverage can be very risky and should be used only by those with experience and still will most probably end up with a Liquidation, so this should be avoided.

Why did the collateral and debt of my Vault increase without my intervention?

If Vaults are liquidated and the Stability Pool is empty (or gets emptied due to the liquidation), every borrower will receive a portion of the liquidated collateral and debt as part of a redistribution process.

About tBTC Beta Stakers Program

As part of bootstrapping tBTC utility, Threshold Network allow-lists authorized stakers to participate in tBTC minting and redemptions to ensure system continuity during progressive decentralization. These allow-listed stakers are called Beta Stakers. The goal with the Beta Staker program is to ensure key operations run properly without interruptions during early growth.

Note that this is a form of 'progressive decentralization', but with a clear, simple and already deployed pathway for the decentralization depth to increase – i.e. by adding more independent stakers to the allow list.

As of the latest contract query, there are now 35 Beta Stakers, an increase from 20 as previously reported in November 2023. A few notable professional staking providers can be found requesting DAO approval here.

Beta Staker nodes form a permissioned set that is responsible for creating tBTC wallets that custody BTC. Running a tBTC Beta Staker node is a significant commitment with specific requirements. This document aims to highlight such requirements, technical recommendations, and possible costs of operating a Beta Staker tBTC 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, stake distribution and operational metrics.

General requirements

Running a Beta Staker node is a long-term commitment. Once the given node is added to the Beta Stakers set, it must remain operational until the end of the Beta Staker Program (~12 months).

Operators of Beta Staker nodes are expected to be extremely responsive, especially regarding upgrades requested by software contributors. Ideally, they should be able to upgrade their nodes within 24 hours of notification.

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

Technical requirements

A Beta Staker node performs more computationally expensive operations (DKG, threshold signing, etc) compared to a standard node. To ensure a high level of service, a Beta Staker 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 Beta Staker 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. Beta Staker operators 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 Beta Staker 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. Beta Staker operators 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. Beta Staker 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 Beta Staker 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

• Beta Staker 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 Beta Staker 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 Beta Staker 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 node. This estimate DOES NOT include human operational costs. Each Beta Staker operator must include this overhead when making their own estimates.

Council Multisigs

Treasury Guild Multisigs

Integrations Guild Multisigs

Marketing Guild Multisigs

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:

# This is a sample TOML configuration file for the Keep client.

[ethereum]
URL = "ws://127.0.0.1:8546"
KeyFile = "/Users/someuser/ethereum/data/keystore/UTC--2018-03-11T01-37-33.202765887Z--AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA8AAAAAAAAA"

# Uncomment to override the defaults for transaction status monitoring.

# MiningCheckInterval is the interval in which transaction
# mining status is checked. If the transaction is not mined within this
# time, the gas price is increased and transaction is resubmitted.
#
# MiningCheckInterval = 60  # 60 sec (default value)

# MaxGasFeeCap specifies the maximum gas fee cap the client is
# willing to pay for the transaction to be mined. The offered transaction
# gas cost can not be higher than the max gas fee cap value. If the maximum
# allowed gas fee cap is reached, no further resubmission attempts are
# performed. This property should be set only for Ethereum. In case of
# legacy non-EIP-1559 transactions, this field works in the same way as
# `MaxGasPrice` property.
#
# MaxGasFeeCap = "500 Gwei" # 500 Gwei (default value)

# Uncomment to enable Ethereum node rate limiting. Both properties can be
# used together or separately.
#
# RequestsPerSecondLimit sets the maximum average number of requests
# per second which can be executed against the Ethereum node.
# All types of Ethereum node requests are rate-limited,
# including view function calls.
#
# RequestsPerSecondLimit = 150

# ConcurrencyLimit sets the maximum number of concurrent requests which
# can be executed against the Ethereum node at the same time.
# This limit affects all types of Ethereum node requests,
# including view function calls.
#
# ConcurrencyLimit = 30

# BalanceAlertThreshold defines a minimum value of the operator's account
# balance below which the client will start reporting errors in logs.
# A value can be provided in `wei`, `Gwei` or `ether`, e.g. `7.5 ether`,
# `7500000000 Gwei`.
#
# BalanceAlertThreshold = "0.5 ether" # 0.5 ether (default value)

[bitcoin.electrum]
# URL to the Electrum server in format: `scheme://hostname:port`.
# Should be uncommented only when using a custom Electrum server. Otherwise,
# one of the default embedded servers is selected randomly at startup.
# URL = "tcp://127.0.0.1:50001"

# Timeout for a single attempt of Electrum connection establishment.
# ConnectTimeout = "10s"

# Timeout for Electrum connection establishment retries.
# ConnectRetryTimeout = "1m"

# Timeout for a single attempt of Electrum protocol request.
# RequestTimeout = "30s"

# Timeout for Electrum protocol request retries.
# RequestRetryTimeout = "2m"

# Interval for connection keep alive requests.
# KeepAliveInterval = "5m"

[network]
Bootstrap = false
Peers = [
	"/ip4/127.0.0.1/tcp/3919/ipfs/16Uiu2HAmFRJtCWfdXhZEZHWb4tUpH1QMMgzH1oiamCfUuK6NgqWX",
]
Port = 3920

# Uncomment to override the node's default addresses announced in the network
# AnnouncedAddresses = ["/dns4/example.com/tcp/3919", "/ip4/80.70.60.50/tcp/3919"]

# Uncomment to enable courtesy message dissemination for topics this node is
# not subscribed to. Messages will be forwarded to peers for the duration
# specified as a value in seconds.
# Message dissemination is disabled by default and should be enabled only
# on selected bootstrap nodes. It is not a good idea to enable dissemination
# on non-bootstrap node as it may clutter communication and eventually lead
# to blacklisting the node. The maximum allowed value is 90 seconds.
#
# DisseminationTime = 90

[storage]
Dir = "/my/secure/location"

# ClientInfo exposes metrics and diagnostics modules.
# 
# Metrics collects and exposes information useful for external monitoring tools usually
# operating on time series data.
# All values exposed by metrics module are quantifiable or countable.
#
# The following metrics are available:
# - connected peers count
# - connected bootstraps count
# - eth client connectivity status
# 
# Diagnostics module exposes the following information:
# - list of connected peers along with their network id and ethereum operator address
# - information about the client's network id and ethereum operator address
[clientInfo]
Port = 9601
# NetworkMetricsTick = 60
# EthereumMetricsTick = 600

# Uncomment to overwrite default values for TBTC config.
#
# [tbtc]
# PreParamsPoolSize = 3000
# PreParamsGenerationTimeout = "2m"
# PreParamsGenerationDelay = "10s"
# PreParamsGenerationConcurrency = 1
# KeyGenConcurrency = 1

# Developer options to work with locally deployed contracts
#
# [developer]
# TokenStakingAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
# RandomBeaconAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
# WalletRegistryAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
# BridgeAddress = "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"

BeaconAuthorization

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

Parameters

struct Parameters {
  uint96 minimumAuthorization;
  uint64 authorizationDecreaseDelay;
  uint64 authorizationDecreaseChangePeriod;
}

AuthorizationDecrease

struct AuthorizationDecrease {
  uint96 decreasingBy;
  uint64 decreasingAt;
}

Data

struct Data {
  struct BeaconAuthorization.Parameters parameters;
  mapping(address => address) stakingProviderToOperator;
  mapping(address => address) operatorToStakingProvider;
  mapping(address => struct BeaconAuthorization.AuthorizationDecrease) pendingDecreases;
}

OperatorRegistered

event OperatorRegistered(address stakingProvider, address operator)

AuthorizationIncreased

event AuthorizationIncreased(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount)

AuthorizationDecreaseRequested

event AuthorizationDecreaseRequested(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount, uint64 decreasingAt)

AuthorizationDecreaseApproved

event AuthorizationDecreaseApproved(address stakingProvider)

InvoluntaryAuthorizationDecreaseFailed

event InvoluntaryAuthorizationDecreaseFailed(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount)

OperatorJoinedSortitionPool

event OperatorJoinedSortitionPool(address stakingProvider, address operator)

OperatorStatusUpdated

event OperatorStatusUpdated(address stakingProvider, address operator)

setParameters

function setParameters(struct BeaconAuthorization.Data self, uint96 _minimumAuthorization, uint64 _authorizationDecreaseDelay, uint64 _authorizationDecreaseChangePeriod) external

Updates authorization-related parameters.

Parameters

registerOperator

function registerOperator(struct BeaconAuthorization.Data self, address operator) public

Used by staking provider to set operator address that will operate a 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

function authorizationIncreased(struct BeaconAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) external

Used by T staking contract to inform the beacon 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

function authorizationDecreaseRequested(struct BeaconAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) public