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.

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

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 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 Liquity Protocol 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, Bootstrapping is completed through an Initial Protocol Loan.

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

Before you start

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

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

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!

Wallets are created periodically based on governance. updateWalletParameters changes the time between wallets and walletParameters 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 Threshold Elliptic Curve Digital Signature Algorithm, requiring 51-of-100 Signers to cooperate.

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

The probability that a Staker 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 random number 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 Binomial Distribution. From wikipedia:

A Binomial distribution with parameters n and p is the discrete probability distribution of the number of successes in a sequence of n independent experiments, each asking a yes–no question, and each with its own Boolean-valued outcome: 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.

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 ~8.83% of the Stake.

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!

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

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

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

• They exist only as whitepapers.

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.

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.

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.

Fundamentals: Dive a little deeper

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

Summary

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.

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

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.

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.

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

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.

Introduction

An immediate question that comes up is providing utility for the bridged tBTC for DeFi applications. Threshold USD provides an alternative utility to tBTC by allowing to mint thUSD, which then can be used for multiple purposes in a wider ecosystem.

What is Threshold USD?

Threshold USD is a decentralized borrowing protocol that allows you to draw loans using tBTC and ETH as collateral. Loans are paid out in thUSD (a USD pegged stablecoin) and need to maintain a minimum collateral ratio of 110%.

Liquity is totally governance free and immutable; although that is a tremendous strength for a DeFi Protocol as it makes it completely censorship resistant, it also exposes the protocol to existential oracle risk and limits its ability to scale and respond to market dynamics.

With that in mind some flexibilitiy is embeded into Threshold USD. It has a few parameters that can be changed through governance:

• Collateral Type: in addition to tBTC other collateral types may be added (ETH will be an additional collateral to tBTC, as it is the most decentralized and abundant asset in Ethereum) and also removed by revoking mint and burn capabilities.

• Price Feed Contract: Oracles are critical for the health of the protocol (defining liquidations) and may need to be updated due to poor performance of existing oracles

• PCV Contract: Withdraw from BAMM to PCV, pay the debt and withdraw funds from PCV after repaying all the debt.

• BAMM Contract: Dao has veto capability for change submission to the "A" parameter and B.Protocol fees.

What’s the motivation behind Threshold USD?

Stable-value assets are an essential building block for Ethereum applications and have grown to represent tens of billions of dollars in value.

However, the vast majority of this value is in the form of fiat-collateralized stablecoins like USDT and USDC. Decentralized stablecoins like DAI and sUSD make up only a small portion of the total stablecoin supply, meaning the vast majority of stablecoins are centralized.

Threshold USD addresses this by creating a more capital efficient and user-friendly way to borrow stablecoins.

What are the key benefits of Threshold USD?

Threshold USD’s key benefits include:

• Low cost for tBTC loan (0.5% issuance fee and no interest rate at launch).

• Minimum collateral ratio of 110% — more efficient usage of deposited tBTC

• Governance Minimized— most operations are algorithmic and fully automated, and most protocol parameters are set at time of contract deployment.

  • Note: See section above for parameters that can be changed through governance

• Directly redeemable — thUSD can be redeemed at face value for the underlying collateral at any time

Can Threshold USD be upgraded or changed?

Yes. The Threshold USD token contracts mint function will be able to add additional contracts; this is how we keep the option to upgrade while leaving all the contracts immutable with the exception of the price feed contract.

How can I use Threshold USD?

You can use thUSD via a web interface (aka frontend) or directly via the smart contracts.

What are the main use cases of Threshold USD?

• Borrow thUSD against tBTC by opening a Vault and use directly in DeFi applications or exchange for other coins

• Secure Threshold USD by providing thUSD to the Stability Pool in exchange for Liquidation rewards

• Redeem 1 thUSD for 1 USD worth of tBTC when the thUSD peg falls below $1 (i.e. arbitrage the system)

What is thUSD?

thUSD is the USD-pegged stablecoin used to pay out loans on the Threshold USD protocol. At any time it can be redeemed against the underlying collateral at face value.

What do I need in order to use Threshold USD?

To become a Stability Pool depositor you need to have thUSD, which can be borrowed by opening a Vault. You can also use Curve or another (decentralized) exchange to buy the tokens on the open market.

Does Threshold USD charge any fees?

These are the fees for using Threshold USD Protocol:

• A one-time fee whenever thUSD is borrowed, as a percentage of the drawn amount (in thUSD)

• A fee when thUSD is redeemed (see Section “Redemptions and thUSD Price Stability” for details on the Redemption Mechanism)

  • For redeemers, there is a redemption fee on the amount paid to users by the system (in tBTC) when exchanging thUSD for tBTC. Note that redemption is separate from repaying your loan as a borrower, which is free of charge

• Both fees depend on the redemption volumes, i.e. they increase upon every redemption in function of the redeemed amount, and decay over time as long as no redemptions take place. The intent is to throttle large redemptions with higher fees, and to throttle borrowing directly after large redemption volumes. The fee decay over time ensures that the fee for both borrowers and redeemers will “cool down”, while redemptions volumes are low.

• The fees cannot become smaller than 0.5% (except in Recovery Mode), which protects the redemption facility from being misused by arbitrageurs front-running the price feed. The borrowing fee is capped at 5%, keeping the system (somewhat) attractive for borrowers even in phases where the monetary is contracting due to redemptions. Other than that, the two fees are identical.

• Interest rate: at launch no ongoing interest rate is charged when using ETH and tBTC as collateral, only the initial borrowing fee.

  The decision to incorporate an ongoing interest rate that will accrue on the loan amount in thUSD, which is calculated based on a predetermined interest rate and the amount of time that has elapsed, will be made by the DAO in the near future for these and any other future collaterals.

How can I earn money using Threshold USD?

There are two main ways to generate revenue using Threshold USD:

• Deposit thUSD to the Stability Pool and earn liquidation gains (in tBTC).

Other opportunities may arise in time in the DeFi Ecosystem to use thUSD and earn rewards or yield.

Can I lose my funds?

As a non-custodial system, all the tokens sent to the protocol will be held and managed algorithmically without the interference of any person or legal entity. That means your funds will only be subject to the rules set forth in the smart contract code.

You may lose all or part of your funds in a Liquidation scenario:

• You are a borrower (Vault owner) and your collateral in tBTC is liquidated. You will still keep your borrowed thUSD, but your Vault will be closed and your collateral will be used to compensate Stability Pool depositors.

  • If the liquidation happens under Normal Mode (i.e. your Vault is at 110% Collateral Ratio), all your Collateral will be used the Liquidation and fees

  • If the liquidation happens under Recovery Mode (i.e. Total Protocol Collateral Ratio is less than 150%), you may recover a part of the Collateral if your Vault is between the 110% and 150% Collateral Ratio)

In addition, the following Scenarios may happen that may lead to loss of funds:

• Bugs/Hacks: 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. This includes potential bugs/hacks on tBTC as it is the collateral for thUSD.

• Price Oracle Risk: Liquidations are triggered by the Collateral Ratio, which is a function of the Collateral Price. There is a risk of malfunction of manipulation with the Price Feed. We are minimizing the exposure to those risks, but they cannot be completely ruled out

• If the Threshold USD is not accepted and all users want to leave, the last fraction of collateral cannot be recovered as there won’t be enough thUSD available (due to Loan fees accrued). This would only affect a very minor fraction of capital

• For redemptions, in case of an acceleration of redemptions, the redemption fee increases and can lead to losses. If the Total Collateral Ratio is less than 110%, redemptions are blocked

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.

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.

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 Initial Protocol Loan 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.

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 here (https://www.liquity.org/blog/on-price-stability-of-liquity). 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.

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.

​

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

Connecting to BOB Network

1. Access Wallet Setup
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

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.

The Initial Protocol Loan (IPL) is a debt issued against the protocol itself in order to fund the stability pool. Even though it's technically debt, it does not in itself make the protocol a fractional reserve because all funds are accounted for.

How it works

thUSD is minted by the PCV and deposited into the stability pool. A freeze on withdraw is initiated until debt is fully repaid. At any time, the Threshold DAO can initiate a withdraw, which will destruct the debt and withdraw exceeds. If the PCV for some reason has less than the debt available, withdraw is denied.

Profits from usage of the protocol (loan interest, redemption fee, etc) accrues into the PCV, so in an event where there are less funds than debt the protocol first has to earn back the missing funds.

Benefits of the hybrid PCV + IPL model:

• Bootstrap stability pool for free

• No need for a Protocol token = all profits accrue directly to the PCV

• Immediate surplus on first loan drawn / liquidation

• Predictability and (once debt is repaid) high resilience against Black Swans

• No idle capital (it doesn't "really" exist)

Disadvantages

• Higher risk of under-collateralization during the initial stages

• Poor management of PCV could result in not enough funds in the stability pool

About the risk

Each liquidation that occurs will draw against the stability pool and result in ~10% profit to the stability pool. This also means that the price can drop up to 10% after a liquidation before the stability pool is at risk of losing money on the liquidation. Our integration with B.Protocol ensures that liquidated tBTC is automatically converted back to thUSD and re-deposited into the stability pool. Under normal circumstances and without other factors, it is expected that the balance of thUSD in the pool will grow over time.

But there can be Black Swan events, large drops in the price of BTC in a short period of time or liquidity issues that results in a loss, even at ~10% profit. This is a risk of the protocol becoming undercollateralized, but the same issue would apply even without debt (stability pool not being profitable). The protocol is created to be sustainable, so these types of rare events will be averaged out. In addition, all income streams from Threshold USD also ends up in the PCV which further decrease the risk of undercollaterization.

The undercollaterialization is mostly a concern during the initial bootstrapping phase. As interest accrue and repay the initial debt, the funds in the stability pool will be replaced by fully owned PVC, thus eliminating this disadvantage.

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.

Steps to Open Collateral Vaults and Mint thUSD

1. Access the thUSD App Interface:

   • Navigate to app.thresholdusd.org 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 app.thresholdusd.org to ensure it remains adequately collateralized. You can adjust collateral and debt position to adjust the collateralization ratio or repay thUSD as needed.

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.

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

The process for delegating liquid tokens 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.

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

Lifecycle of a successful proposal

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

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

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

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

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

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

Deviations in the proposal lifecycle

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

Council Multisigs

Treasury Guild Multisigs

Integrations Guild Multisigs

Marketing Guild Multisigs

One important step to get your node operating on the Threshold Network is proper application authorization as well as operator account registration. Applications need only be authorized once.

Application Authorization

To get started, visit the Threshold Dashboard and connect your wallet.

Click on "Configure Apps"

Select BOTH tBTC and Random Beacon applications and enter your desired amount of T to stake per application. Note that the minimum is 40,000T.

Operator Registration

The operator account is the Ethereum account created on your node. In order for the network to associate your T stake with your node, you must register your Operator Address.

After both applications have been authorized, click on "Start Mapping" to begin the Operator Registration process.

Enter your Operator Address in the field provided and click on "Map Address."

Once the steps above have been successfully completed, you are ready to move on to the next step in the node deployment process.

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

1. Go to https://boardroom.io/threshold.

2. Connect your wallet.

3. Click "Set Up Delegation".

4. Select your "Delegation Type" - either to yourself or a third party.

5. Enter "Delegate Address" and click on "Delegate Votes".

6. Sign the transaction.

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

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

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

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.

Download the Binary

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

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

Extract the compressed file:

Configure tBTC v2 Client

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

The following flags must be set at minimum:

To launch the client, execute the following:

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

You should see the following shortly:

Congratulations, your node is up and running.

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.

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.

Install Docker

Install or update Docker to the latest version. Visit the Official Docker website for detailed instructions. Use the command below to find your installed version if needed:

docker --version

Docker and Security Best Practices

General best practices recommend against running the tBTC v2 client as the root user as a security precaution. One security-minded approach is to Run the Docker daemon as a non-root user (Rootless mode).

Next, choose ONE of the following options: Docker Compose makes managing the container simple, but requires an additional step to ensure the container starts after a reboot. The tBTC v2 Service option configures the client to run as a service in order to ensure that the client is restarted automatically, should your machine reboot. The Docker Launch Script is faster to setup, but won't start the client if your machine reboots.

version: '3'
services:
  keep-client:
    image: keepnetwork/keep-client:latest
    container_name: keep-client
    restart: on-failure
    ports:
      - "3919:3919"
      - "9601:9601"
    volumes:
      - /home/$USER/keep/config/:/mnt/keep/config
      - /home/$USER/keep/storage/:/mnt/keep/storage
    environment:
      - KEEP_ETHEREUM_PASSWORD=<Operator Account keyfile password>
      - LOG_LEVEL=info
    logging:
      options:
        max-size: "100m"
        max-file: "3"
    command: start --ethereum.url "<Ethereum API WS URL>"  --ethereum.keyFile "/mnt/keep/config/<Operator Account keyfile name>" --storage.dir "/mnt/keep/storage" --network.announcedAddresses "/ip4/<PUBLIC_IP_OF_MACHINE>/tcp/3919"

# /etc/systemd/system/docker-compose-app.service

[Unit]
Description=Docker Compose Application Service
Requires=docker.service
After=docker.service
StartLimitIntervalSec=60

[Service]
WorkingDirectory=/home/$USER/keep/
ExecStart=/usr/local/bin/docker-compose up
ExecStop=/usr/local/bin/docker-compose down
TimeoutStartSec=0
Restart=on-failure
StartLimitBurst=3

[Install]
WantedBy=multi-user.target

cd /etc/systemd/system/
nano tbtcv2.service

[Unit]
Description=tBTC v2 client
After=network.target
Wants=network.target

[Service]
Environment="ETHEREUM_WS_URL=<Ethereum API WS URL>"
Environment="OPERATOR_KEY_FILE_NAME=<Operator Account keyfile name>"
Environment="OPERATOR_KEY_FILE_PASSWORD=<Operator Account keyfile password>"
Environment="PUBLIC_IP=/ip4/<PUBLIC_IP_OF_MACHINE>/tcp/3919"
Environment="CONFIG_DIR=/home/<user name>/keep/config"
Environment="STORAGE_DIR=/home/<user name>/keep/storage"

# These items only apply if you setup rootless-mode.
# Do not enable unless using rootless mode. Don't forget to adjust user UID.
#Environment="XDG_RUNTIME_DIR=/run/<user name>/<user UID>/"
#Environment="DOCKER_HOST=unix:///run/<user name>/<user UID>/docker.sock"

Type=simple
WorkingDirectory=/home/$USER

ExecStart=/usr/bin/docker run \
    --volume ${CONFIG_DIR}:/mnt/keep/config \
    --volume ${STORAGE_DIR}:/mnt/keep/storage \
    --env KEEP_ETHEREUM_PASSWORD=${OPERATOR_KEY_FILE_PASSWORD} \
    --env LOG_LEVEL=info \
    --log-opt max-size=100m \
    --log-opt max-file=3 \
    -p 3919:3919 \
    -p 9601:9601 \
    keepnetwork/keep-client:latest \
    start \
    --ethereum.url ${ETHEREUM_WS_URL} \
    --ethereum.keyFile /mnt/keep/config/${OPERATOR_KEY_FILE_NAME} \
    --storage.dir /mnt/keep/storage \
    --network.announcedAddresses $PUBLIC_IP

Restart=always
RestartSec=15s

[Install]
WantedBy=default.target

sudo systemctl start tbtcv2

sudo systemctl status tbtcv2

docker ps

systemctl enable tbtcv2

reboot now

nano keep.sh

# Keep tBTC v2 Client
#
# Ethereum endpoint WebSocket URL
# This can be a provider such as Infura, Alchemy, Ankr, etc or your own Geth Nodeq
# ETHEREUM_WS_URL="wss://mainnet.infura.io/ws/v3/redacted_credentials"
# note: only replace characters inside the " ". The Quotation marks must be retained
ETHEREUM_WS_URL="<Ethereum API WS URL>"

# copied to home/keep/config earlier
OPERATOR_KEY_FILE_NAME="<Operator Account keyfile name>"

# password set during Operator Account Address creation
OPERATOR_KEY_FILE_PASSWORD="<Operator Account keyfile password>"

# To configure your node with a Public IP, enter it below.
PUBLIC_IP="<PUBLIC_IP_OF_MACHINE>"
# Alternatively, you can use DNS.
# To configure DNS, modify the last line of the script
# and add your DNS in the following format:
# /dns4/bootstrap-1.test.keep.network/tcp/3919

# Setup configuration and storage directories
# THESE MUST BE PERSISTENT STORAGE
CONFIG_DIR="/home/$USER/keep/config"
STORAGE_DIR="/home/$USER/keep/storage"

docker run \
    --detach \
    --restart on-failure \
    --volume $CONFIG_DIR:/mnt/keep/config \
    --volume $STORAGE_DIR:/mnt/keep/storage \
    --env KEEP_ETHEREUM_PASSWORD=$OPERATOR_KEY_FILE_PASSWORD \
    --env LOG_LEVEL=info \
    --log-opt max-size=100m \
    --log-opt max-file=3 \
    -p 3919:3919 \
    -p 9601:9601 \
    keepnetwork/keep-client:latest \
    start \
    --ethereum.url $ETHEREUM_WS_URL \
    --ethereum.keyFile /mnt/keep/config/$OPERATOR_KEY_FILE_NAME \
    --storage.dir /mnt/keep/storage \
    --network.announcedAddresses /ip4/$PUBLIC_IP/tcp/3919

sudo chmod +x keep.sh

sudo bash keep.sh

Client Startup and Logs

Unless the --detach flag was removed from the startup script, there will be no console output. In order to check your node, retrieve the Docker logs.

First, find your Docker instance identification, it'll be a random combination of words, e.g. stinky_brownie:

sudo docker ps

Use your specific identification and substitute:

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

Scroll down about half a page, and you should see the following:

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

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.

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

Logging

Configuration options for logging

Alternatives to Dashboard

Alternative application authorization methods to using the Threshold Dashboard.

Config File

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

CLI Options

Client Info

Client information exposed by the tBTC v2 staking client.

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"

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:

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.

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

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.

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.

Checkpoints

Abstract contract to support checkpoints for Compound-like voting and delegation. This implementation supports token supply up to 2^96 - 1. This contract keeps a history (checkpoints) of each account's vote power. Vote power can be delegated either by calling the {delegate} function directly, or by providing a signature to be used with {delegateBySig}. Voting power can be publicly queried through {getVotes} and {getPastVotes}. NOTE: Extracted from OpenZeppelin ERCVotes.sol. This contract is upgrade-safe.

Checkpoint

struct Checkpoint {
  uint32 fromBlock;
  uint96 votes;
}

_delegates

mapping(address => address) _delegates

_checkpoints

mapping(address => uint128[]) _checkpoints

_totalSupplyCheckpoints

uint128[] _totalSupplyCheckpoints

DelegateChanged

event DelegateChanged(address delegator, address fromDelegate, address toDelegate)

Emitted when an account changes their delegate.

DelegateVotesChanged

event DelegateVotesChanged(address delegate, uint256 previousBalance, uint256 newBalance)

Emitted when a balance or delegate change results in changes to an account's voting power.

checkpoints

function checkpoints(address account, uint32 pos) public view virtual returns (struct Checkpoints.Checkpoint checkpoint)

numCheckpoints

function numCheckpoints(address account) public view virtual returns (uint32)

Get number of checkpoints for account.

delegates

function delegates(address account) public view virtual returns (address)

Get the address account is currently delegating to.

getVotes

function getVotes(address account) public view returns (uint96)

Gets the current votes balance for account.

Parameters

Return Values

getPastVotes

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

Determine the prior number of votes for an account as of a block number.

Block number must be a finalized block or else this function will revert to prevent misinformation.

Parameters

Return Values

getPastTotalSupply

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

Retrieve the totalSupply at the end of blockNumber. Note, this value is the sum of all balances, but it is NOT the sum of all the delegated votes!

blockNumber must have been already mined

Parameters

delegate

function delegate(address delegator, address delegatee) internal virtual

Change delegation for delegator to delegatee.

moveVotingPower

function moveVotingPower(address src, address dst, uint256 amount) internal

Moves voting power from one delegate to another

Parameters

writeCheckpoint

function writeCheckpoint(uint128[] ckpts, function (uint256,uint256) view returns (uint256) op, uint256 delta) internal returns (uint256 oldWeight, uint256 newWeight)

Writes a new checkpoint based on operating last stored value with a delta. Usually, said operation is the add or subtract functions from this contract, but more complex functions can be passed as parameters.

Parameters

lookupCheckpoint

function lookupCheckpoint(uint128[] ckpts, uint256 blockNumber) internal view returns (uint96)

Lookup a value in a list of (sorted) checkpoints.

Parameters

maxSupply

function maxSupply() internal view virtual returns (uint96)

Maximum token supply. Defaults to type(uint96).max (2^96 - 1)

encodeCheckpoint

function encodeCheckpoint(uint32 blockNumber, uint96 value) internal pure returns (uint128)

Encodes a blockNumber and value into a single uint128 checkpoint.

blockNumber is stored in the first 32 bits, while value in the remaining 96 bits.

decodeBlockNumber

function decodeBlockNumber(uint128 checkpoint) internal pure returns (uint32)

Decodes a block number from a uint128 checkpoint.

decodeValue

function decodeValue(uint128 checkpoint) internal pure returns (uint96)

Decodes a voting value from a uint128 checkpoint.

decodeCheckpoint

function decodeCheckpoint(uint128 checkpoint) internal pure returns (uint32 blockNumber, uint96 value)

Decodes a block number and voting value from a uint128 checkpoint.

add

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

subtract

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

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: Threshold Network DAO Proposal — v2

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: Minimum Stake Size of 40,000 T at Network Genesis

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: Bootstrap Threshold DAO Guilds

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

TIP-020: Interim Era Incentive Schemes: (1) One-off Migration+Stake Bonus & (2) Ongoing Stable Yield

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

TIP-026: Threshold Improvement Proposals (TIPs): Flows and Template

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

TIP-032: Council decision: Reward allocation between tBTCv2 & PRE (overall target APY = 15%)

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 Rules Subcommittee, 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: Rules for Guild Committee Elections and Management

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

TIP-034: Rules for New Proposals

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: Increase the Number of Seats on the Integrations Guild from 5 to 7

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

TIP-049: Restructure the Marketing Guild Committee

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

Additional Rules for Elections

TC-003: Council Elections Retrospective and Lessons Learned for the Third Epoch

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.

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

Recommended Machine Types

Your operating environment will ultimately dictate what machine type to go with. This is particularly relevant if you’re running a containerized solution where multiple applications are sharing VM resources. The below types are sufficient for running one instance of the tBTC v2 Node.

The preferred OS is Ubuntu.

Ethereum API

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

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.

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 ./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 be funded with sepolia ETH and maintain a positive balance at all times to ensure proper operation and availability of your tBTC v2 node.

Network Configuration

The node has to be accessible publicly to establish and maintain connections with bootstrap nodes and discovered peers.

The node exposes metrics and diagnostics services for monitoring. A network port has to be exposed publicly, so the peers can connect to your node. A Diagnostics Port has to be exposed publicly, for the rewards allocation.

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 an addresses (ip4 or dns4) under which your node is reachable for the public.

To read more about multiaddress see the libp2p docummentation.

One important step to get your node operating on the Threshold Network is proper application authorization as well as operator account registration. Applications need only be authorized once.

Application Authorization

To get started, visit the Threshold Dashboard and connect your wallet.

Click on "Configure Apps"

Select BOTH tBTC and Random Beacon applications and enter your desired amount of T to stake per application. Note that the minimum is 40,000T.

Operator Registration

The operator account is the Ethereum account created on your node. In order for the network to associate your T stake with your node, you must register your Operator Address.

After both applications have been authorized, click on "Start Mapping" to begin the Operator Registration process.

Enter your Operator Address in the field provided and click on "Map Address."

Once the steps above have been successfully completed, you are ready to move on to the next step in the node deployment process.

Create Folder Structure

The client requires two persistent directories. These directories will store configuration files and data generated and used by the client. It is highly recommended to create frequent backups of these directories. Loss of these data may be catastrophic and may lead to slashing.

Create folders for tBTC v2 client

cd /home
mkdir keep
cd keep
mkdir storage config

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

The keystore subdirectory contains sensitive key material data generated by the client. 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 Geth was installed for the root user with the command provided in the Operator Account creation step, the operator-key file should be located in the ~/operator-key directory.

cd ~/operator-key

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

ls -la
cp name_of_account_key_file /home/keep/config/name_of_account_key_file

Install Docker

Install or update Docker to the latest version. Visit the Official Docker website for detailed instructions. Use the command below to find your installed version if needed:

docker --version

Docker Launch Script

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

Create the launch script:

nano keep.sh

And paste the following:

# Keep Testnet tBTC v2 Client
#
# Ethereum endpoint WebSocket URL
# This can be a provider such as Infura, Alchemy, Ankr, etc or your own Geth Nodeq
# ETHEREUM_WS_URL="wss://sepolia.infura.io/ws/v3/redacted_credentials"
# note: only replace characters inside the " ". The Quotation marks must be retained
ETHEREUM_WS_URL="<Ethereum API WS URL>"

# copied to home/keep/config earlier
OPERATOR_KEY_FILE_NAME="<Operator Account keyfile name>"

# password set during Operator Account Address creation
OPERATOR_KEY_FILE_PASSWORD="<Operator Account keyfile password>"

# To configure your node with a Public IP, enter it below.
PUBLIC_IP="<PUBLIC_IP_OF_MACHINE>"
# Alternatively, you can use DNS.
# To configure DNS, modify the last line of the script
# and add your DNS in the following format:
# /dns4/bootstrap-1.test.keep.network/tcp/3919

# Setup configuration and storage directories
# THESE MUST BE PERSISTENT STORAGE
CONFIG_DIR="/home/keep/config"
STORAGE_DIR="/home/keep/storage"

docker run \
    --detach \
    --restart on-failure \
    --volume $CONFIG_DIR:/mnt/keep/config \
    --volume $STORAGE_DIR:/mnt/keep/storage \
    --env KEEP_ETHEREUM_PASSWORD=$OPERATOR_KEY_FILE_PASSWORD \
    --env LOG_LEVEL=info \
    --log-opt max-size=100m \
    --log-opt max-file=3 \
    -p 3919:3919 \
    -p 9601:9601 \
    us-docker.pkg.dev/keep-test-f3e0/public/keep-client \
    start \
    --testnet \
    --ethereum.url $ETHEREUM_WS_URL \
    --ethereum.keyFile /mnt/keep/config/$OPERATOR_KEY_FILE_NAME \
    --storage.dir /mnt/keep/storage \
    --network.announcedAddresses /ip4/$PUBLIC_IP/tcp/3919

Save and close the file, and make it executable:

sudo chmod +x keep.sh

To launch the tBTC v2 client, execute:

sudo bash keep.sh

Client Startup

Unless the --detach flag was removed from the startup script, there will be no console output. In order to check your node, retrieve the Docker logs.

First, find your Docker instance identification, it'll be a random combination of words, e.g. stinky_brownie:

sudo docker ps

Use your specific identification and substitute:

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

Scroll down about half a page, and you should see the following:

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

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

Congratulations, your node is up and running.

BaseTokenholderGovernor

VETO_POWER

constructor

cancel

propose

quorum

proposalThreshold

getVotes

state

supportsInterface

_execute

_cancel

_executor

proposalDeadline

_castVote

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

IStaking

The staking contract enables T owners to have their wallets offline and their stake managed by staking providers on their behalf. The staking contract does not define operator role. The operator responsible for running off-chain client software is appointed by the staking provider in the particular application utilizing the staking contract. All off-chain client software should be able to run without exposing operator's or staking provider’s private key and should not require any owner’s keys at all. The stake delegation optimizes the network throughput without compromising the security of the owners’ stake.

StakeType

stake

Creates a delegation with msg.sender owner with the given staking provider, beneficiary, and authorizer. Transfers the given amount of T to the staking contract.

The owner of the delegation needs to have the amount approved to transfer to the staking contract.

stakeKeep

Copies delegation from the legacy KEEP staking contract to T staking contract. No tokens are transferred. Caches the active stake amount from KEEP staking contract. Can be called by anyone.

The staking provider in T staking contract is the legacy KEEP staking contract operator.

stakeNu

Copies delegation from the legacy NU staking contract to T staking contract, additionally appointing staking provider, beneficiary and authorizer roles. Caches the amount staked in NU staking contract. Can be called only by the original delegation owner.

setMinimumStakeAmount

Allows the Governance to set the minimum required stake amount. This amount is required to protect against griefing the staking contract and individual applications are allowed to require higher minimum stakes if necessary.

approveApplication

Allows the Governance to approve the particular application before individual stake authorizers are able to authorize it.

increaseAuthorization

Increases the authorization of the given staking provider for the given application by the given amount. Can only be called by the authorizer for that staking provider.

Calls authorizationIncreased(address stakingProvider, uint256 amount) on the given application to notify the application about authorization change. See IApplication.

requestAuthorizationDecrease

Requests decrease of the authorization for the given staking provider on the given application by the provided amount. It may not change the authorized amount immediatelly. When it happens depends on the application. Can only be called by the given staking provider’s authorizer. Overwrites pending authorization decrease for the given staking provider and application if the application agrees for that. If the application does not agree for overwriting, the function reverts.

Calls authorizationDecreaseRequested(address stakingProvider, uint256 amount) on the given application. See IApplication.

requestAuthorizationDecrease

Requests decrease of all authorizations for the given staking provider on all applications by all authorized amount. It may not change the authorized amount immediatelly. When it happens depends on the application. Can only be called by the given staking provider’s authorizer. Overwrites pending authorization decrease for the given staking provider and application.

Calls authorizationDecreaseRequested(address stakingProvider, uint256 amount) for each authorized application. See IApplication.

approveAuthorizationDecrease

Called by the application at its discretion to approve the previously requested authorization decrease request. Can only be called by the application that was previously requested to decrease the authorization for that staking provider. Returns resulting authorized amount for the application.

forceDecreaseAuthorization

Decreases the authorization for the given stakingProvider on the given disabled application, for all authorized amount. Can be called by anyone.

pauseApplication

Pauses the given application’s eligibility to slash stakes. Besides that stakers can't change authorization to the application. Can be called only by the Panic Button of the particular application. The paused application can not slash stakes until it is approved again by the Governance using approveApplication function. Should be used only in case of an emergency.

disableApplication

Disables the given application. The disabled application can't slash stakers. Also stakers can't increase authorization to that application but can decrease without waiting by calling requestAuthorizationDecrease at any moment. Can be called only by the governance. The disabled application can't be approved again. Should be used only in case of an emergency.

setPanicButton

Sets the Panic Button role for the given application to the provided address. Can only be called by the Governance. If the Panic Button for the given application should be disabled, the role address should be set to 0x0 address.

setAuthorizationCeiling

Sets the maximum number of applications one staking provider can have authorized. Used to protect against DoSing slashing queue. Can only be called by the Governance.

topUp

Increases the amount of the stake for the given staking provider.

The sender of this transaction needs to have the amount approved to transfer to the staking contract.

topUpKeep

Propagates information about stake top-up from the legacy KEEP staking contract to T staking contract. Can be called only by the owner or the staking provider.

topUpNu

Propagates information about stake top-up from the legacy NU staking contract to T staking contract. Can be called only by the owner or the staking provider.

unstakeT

Reduces the liquid T stake amount by the provided amount and withdraws T to the owner. Reverts if there is at least one authorization higher than the sum of the legacy stake and remaining liquid T stake or if the unstake amount is higher than the liquid T stake amount. Can be called only by the delegation owner or the staking provider.

unstakeKeep

Sets the legacy KEEP staking contract active stake amount cached in T staking contract to 0. Reverts if the amount of liquid T staked in T staking contract is lower than the highest application authorization. This function allows to unstake from KEEP staking contract and still being able to operate in T network and earning rewards based on the liquid T staked. Can be called only by the delegation owner or the staking provider.

unstakeNu

Reduces cached legacy NU stake amount by the provided amount. Reverts if there is at least one authorization higher than the sum of remaining legacy NU stake and liquid T stake for that staking provider or if the untaked amount is higher than the cached legacy stake amount. If succeeded, the legacy NU stake can be partially or fully undelegated on the legacy staking contract. This function allows to unstake from NU staking contract and still being able to operate in T network and earning rewards based on the liquid T staked. Can be called only by the delegation owner or the staking provider.

unstakeAll

Sets cached legacy stake amount to 0, sets the liquid T stake amount to 0 and withdraws all liquid T from the stake to the owner. Reverts if there is at least one non-zero authorization. Can be called only by the delegation owner or the staking provider.

notifyKeepStakeDiscrepancy

Notifies about the discrepancy between legacy KEEP active stake and the amount cached in T staking contract. Slashes the staking provider in case the amount cached is higher than the actual active stake amount in KEEP staking contract. Needs to update authorizations of all affected applications and execute an involuntary allocation decrease on all affected applications. Can be called by anyone, notifier receives a reward.

notifyNuStakeDiscrepancy

Notifies about the discrepancy between legacy NU active stake and the amount cached in T staking contract. Slashes the staking provider in case the amount cached is higher than the actual active stake amount in NU staking contract. Needs to update authorizations of all affected applications and execute an involuntary allocation decrease on all affected applications. Can be called by anyone, notifier receives a reward.

setStakeDiscrepancyPenalty

Sets the penalty amount for stake discrepancy and reward multiplier for reporting it. The penalty is seized from the delegated stake, and 5% of the penalty, scaled by the multiplier, is given to the notifier. The rest of the tokens are burned. Can only be called by the Governance. See seize function.

setNotificationReward

Sets reward in T tokens for notification of misbehaviour of one staking provider. Can only be called by the governance.

pushNotificationReward

Transfer some amount of T tokens as reward for notifications of misbehaviour

withdrawNotificationReward

Withdraw some amount of T tokens from notifiers treasury. Can only be called by the governance.

slash

Adds staking providers to the slashing queue along with the amount that should be slashed from each one of them. Can only be called by application authorized for all staking providers in the array.

seize

Adds staking providers to the slashing queue along with the amount. The notifier will receive reward per each staking provider from notifiers treasury. Can only be called by application authorized for all staking providers in the array.

processSlashing

Takes the given number of queued slashing operations and processes them. Receives 5% of the slashed amount. Executes involuntaryAllocationDecrease function on each affected application.

authorizedStake

Returns the authorized stake amount of the staking provider for the application.

stakes

Returns staked amount of T, Keep and Nu for the specified staking provider.

All values are in T denomination

getStartStakingTimestamp

Returns start staking timestamp.

This value is set at most once.

stakedNu

Returns staked amount of NU for the specified staking provider.

rolesOf

Gets the stake owner, the beneficiary and the authorizer for the specified staking provider address.

Return Values

getApplicationsLength

Returns length of application array

getSlashingQueueLength

Returns length of slashing queue

getMinStaked

Returns minimum possible stake for T, KEEP or NU in T denomination.

For example, suppose the given staking provider has 10 T, 20 T worth of KEEP, and 30 T worth of NU all staked, and the maximum application authorization is 40 T, then getMinStaked for that staking provider returns:

• 0 T if KEEP stake type specified i.e. min = 40 T max - (10 T + 30 T worth of NU) = 0 T

• 10 T if NU stake type specified i.e. min = 40 T max - (10 T + 20 T worth of KEEP) = 10 T

• 0 T if T stake type specified i.e. min = 40 T max - (20 T worth of KEEP + 30 T worth of NU) < 0 T In other words, the minimum stake amount for the specified stake type is the minimum amount of stake of the given type needed to satisfy the maximum application authorization given the staked amounts of the other stake types for that staking provider.

getAvailableToAuthorize

Returns available amount to authorize for the specified application

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

IKeepTokenStaking

Interface for Keep TokenStaking contract

seize

Seize provided token amount from every member in the misbehaved operators array. The tattletale is rewarded with 5% of the total seized amount scaled by the reward adjustment parameter and the rest 95% is burned.

Parameters

getDelegationInfo

Gets stake delegation info for the given operator.

Parameters

Return Values

ownerOf

Gets the stake owner for the specified operator address.

Return Values

beneficiaryOf

Gets the beneficiary for the specified operator address.

Return Values

authorizerOf

Gets the authorizer for the specified operator address.

Return Values

eligibleStake

Gets the eligible stake balance of the specified address. An eligible stake is a stake that passed the initialization period and is not currently undelegating. Also, the operator had to approve the specified operator contract.

Operator with a minimum required amount of eligible stake can join the network and participate in new work selection.

Parameters

Return Values

INuCypherStakingEscrow

Interface for NuCypher StakingEscrow contract

slashStaker

Slash the staker's stake and reward the investigator

Parameters

requestMerge

Request merge between NuCypher staking contract and T staking contract. Returns amount of staked tokens

getAllTokens

Get all tokens belonging to the staker