# KEEP network (Random beacon/ECDSA groups) risk - liquidation and slashing details

This document is based on the smart contracts for the following git snapshots:

[tbtc@v1.1.0](https://github.com/keep-network/tbtc/tree/v1.1.0)
[keep-ecdsa@v1.2.0](https://github.com/keep-network/keep-ecdsa/tree/v1.2.0)
[keep-core@v1.3.0](https://github.com/keep-network/keep-core/tree/v1.3.0)

See [TBTC tl;dr](#TBTC-tldr) and [Beacon tl;dr](#Beacon-tldr) if you do not care about the details.

## TBTC / ECDSA signing groups

### Abstract

The two services offered by operators are depositing and redemption of BTC. Depositing BTC into custody produces a DepositToken (`TDT`), which can be exchanged for `TBTC`. Redemption then requires a `TDT` and burning of `TBTC`.
In both cases operators can misbehave or fail and thus violating protocol needs to be discouraged. Here we try to outline these mechanisms for node operators, in order for them to better assess the risks of providing these services.

### TBTC tl;dr

The risks of running a tBTC/ECDSA signer node are:

| Event | Slashing (KEEP) | Lose collateral (ETH) |
| -------- | -------- | -------- |
| failing to create signing groups ([3 hours grace period](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/system/TBTCConstants.sol#L21)) | ❌ | ✅ (only [setup fee](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L95) paid by user) | ❌ |
| collateral price peg breaking | ❌ | ✅ (goes to [auction winner](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L162) and [left-over split between group and reporter](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L183)) |
| [group producing fraudulent signatures during funding](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L180) | ✅ ([all stake](https://github.com/keep-network/keep-ecdsa/blob/fb48534c25f93c41c14f9c5602390dd066705393/solidity/contracts/AbstractBondedECDSAKeep.sol#L377)) | ✅ ([goes to deposit owner](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L198)) |
| [group producing fraudulent signatures](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L108) | ✅ ([all stake](https://github.com/keep-network/keep-ecdsa/blob/fb48534c25f93c41c14f9c5602390dd066705393/solidity/contracts/AbstractBondedECDSAKeep.sol#L377)) | ✅ (split between [submitter](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L180) and [auction winner](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L162)) |
| failing to honor a redemption request (signature, [2 hour grace period](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/system/TBTCConstants.sol#L14); spv proof, [6 hour grace period](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/system/TBTCConstants.sol#L16)) | ❌ | ✅ ([redeemer gets tBTC](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L157) and bond is auctioned off, auction remains are [split between fraud reporter and signer group](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L181)) |
| [group producing fraudulent signature during redemption](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L108) | ✅ ([all stake](https://github.com/keep-network/keep-ecdsa/blob/fb48534c25f93c41c14f9c5602390dd066705393/solidity/contracts/AbstractBondedECDSAKeep.sol#L377)) | ✅ (redeemer gets [full bond](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L84)) |

This means that if you are part of an active signing group, your node should never be down for more than two hours, since your group could be requested to redeem a deposit at any point.

If you are currently not part of a signing group, your node should never be down for more than three hours, since you could be elected to be part of a group at any point.

### Background

The job of a node operator/staker is to hold BTC in custody. Custody is always shared between three operators for v1 of the TBTC system and these. BTC being held in custody here means that the custody group produces a joint secret key and a user wanting to put BTC into their custody would then send those to the address associated with this joint secret.
This then implies that these deposited BTC can only be moved if all three operators cooperate and produce a signature.

In v1 of TBTC both intentional and acciddental faults always affect all members of the signing group. This is because faults are not attributable.

The [`Deposit`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/Deposit.sol#L21) is the most important logical unit for operators, since rewards and punishments stem from its state.

An overview over the lifecycle of a `Deposit` can be found in the [TBTC docs](https://docs.keep.network/tbtc/#minting).

### Constants

The different constants associated with the processes outlined can be found in the `TBTCConstants.sol` [here](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/system/TBTCConstants.sol#L3).

The following

uint256 public constant REDEMPTION_SIGNATURE_TIMEOUT = 2 * 60 * 60;  // seconds

would then mean that a group of signers has two hours, starting from the moment a redemption request is created, to produce a signature.

### Collateral Peg

This section concerns the price peg of ETH collateral that TBTC signers have to bond to participate in the network and facilitate the minting of TBTC.

Collateralization is always dependent on the exchange ratio of BTC and ETH. If 1 BTC can be exchanged for 50 ETH, 150% collateralization means that for a deposit of `1 BTC` the signers need to put up `75 ETH` collateral.

This implies that relative price movements of either asset can risk the collateralization ratio to drop below safe margins. For example if BTC value were to double, then `1 BTC` would exchange for `100 ETH` and require `150 ETH` as collateral for an deposit. An old deposit with `75 ETH` as collateral would thus no longer meet the collateralization requirements.

The initial values for collateralization can be found in [`TBTCSystem.sol`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/system/TBTCSystem.sol#L78)

initialCollateralizedPercent = 150
undercollateralizedThresholdPercent = 125
severelyUndercollateralizedThresholdPercent = 110

The thresholds can be adjusted via [`beginCollateralizationThresholdsUpdate`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/system/TBTCSystem.sol#L262).

So based on these numbers, a bond is safe as long as the collateral threshold is `>= 125%` (See [notifyCourtesyCall](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L193)).

If `110% < collateral_ratio < 125%` anybody can notify the contract that a deposit is in danger via [notifyCourtesyCall](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L193). The deposit then enters the "courtesy call" state, during which the deposit can be [redeemed by anyone](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositUtils.sol#L481). That means, that `TBTC` can be directly exchanged for `BTC` without being the owner of the `TDT`.
The deposit stays in this state for 6 hours (see [constants](#Constants)) or until `collateral_ratio >= 125%` and [`exitCourtesyCall`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L204) is called.

If a given deposit has `collateral_ratio < 110%` (via [`notifyUndercollateralizedLiquidation`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L214)) or entered courtesy call more than 6 hours ago (via [`notifyCourtesyCallExpired`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L223)), it will start an [liquidation auction](#Liquidation-Auction).

### Deposit and Redemption

During deposit and redemption a user interacts with a signing group. For any deposit, a signing group gets formed, which will take custody of the BTC being deposited. Each of these deposits is backed by a deposit token (`TDT`), which can later be redeemed for BTC again.

[Deposits flow](https://docs.keep.network/tbtc/#minting)

### Slashing

Slashing is the removal of bonds/collateral and stake without an auction.

#### Stake

Slashing of staked tokens only happens if signers produce a fraudulent signature, which was not requested by the system, i.e. the [`slash`](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/TokenStaking.sol#L482) function is only called via the [`slashForSignatureFraud`](https://github.com/keep-network/keep-ecdsa/blob/fb48534c25f93c41c14f9c5602390dd066705393/solidity/contracts/BondedECDSAKeep.sol#L90) function.

There are two occassions for this:

1. [during funding](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L180)
2. [otherwise](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/Deposit.sol#L410)

In both cases [100% of the stake for a given Keep are slashed](https://github.com/keep-network/keep-ecdsa/blob/fb48534c25f93c41c14f9c5602390dd066705393/solidity/contracts/BondedECDSAKeep.sol#L95).

#### Deposit Collateral

Deposit collateral gets slashed without an [auction](#Liquidation-Auction) in three cases:

1. failure to create a signing group:
- only [setup fee](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L97) is forfeit and the group remembers should get back `deposit - setup_fee`
2. group produces fraudulent signatures during deposit funding
- the owner the deposit gets the [full bond](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L198)
3. producing fraudulent signature during redemption request
- redeemer gets [full bond](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L84)

### Liquidation Auction

The auction always starts by seizing all deposit collateral (see [`startLiquidation`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L71)).

Its execution then proceeds based on whether it was initiated by a fraudulent action, e.g. creating a signature that was not requested by the system (see [`provideFundingECDSAFraudProof`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L180)), a protocol timeout (e.g. [`notifySignerSetupFailed`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositFunding.sol#L85)) or undercollateralization (e.g. [`notifyUndercollateralizedLiquidation`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L214))

The bond is seized by the system and used to purchase TBTC to compensate the BTC deposit owner. 66.6667% (`10000 / initialCollateralizedPercent`) of the bond is offered in exchange for the outstanding BTC amount and is auctioned until 100% of the bond is offered.
For example, if a deposit has a bond of `150 ETH` representing 150% of the BTC value, then the auction would start by offering to buy TBTC for `100 ETH` and increase the offer to the full `150 ETH` at the end of the auction, making the offer more profitable as time passes.

The auction is open until a buyer is found.
The amount available for auctioning is scaled linearly over the course of 24 hours (see [`auctionValue`](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositUtils.sol#L239))

If a portion of the bond remains after the auction, what happens to it depends on the cause of liquidation.

**Under-collateralization or abort/timeouts:** "In case of liquidation due to undercollateralization or abort, the remaining bond value is split 50-50 between the account which triggered the liquidation and the signers." (See [here](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L1836))

**Fraud:** Any left-overs of the collateral after the auction is over, will be for the reporter of the fraud to take. (See [here](https://github.com/keep-network/tbtc/blob/f94110d676d939139572ef06e7eca300ce8f435f/solidity/contracts/deposit/DepositLiquidation.sol#L180))

The signers have control of the BTC wallet at the end of the liquidation process. Since signing a transaction with the private key requires 3-of-3 signatures, the signers have to coordinate to decide what they do with the funds (split equally, send funds to another address for some reason, etc).

## Random beacon

The random beacon is a service to generate strong randomness in a distributed setting via a distributed signature generation.
Nodes are put into signing groups of 64 members, which then jointly generate a signing key used whenever a new `entry` (name used for the randomness in the contracts) is requested.

At the moment, this randomness is mostly used to randomly select operators for keeps.

### Beacon tl;dr

The risks of running beacon node are:

| Event | Seizing (KEEP) |
| -------- | -------- |
| more than 50% of beacon group members are offline for [6 * 64 blocks, ~90 minutes with 14s block time](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/KeepRandomBeaconOperator.sol#L107) | ✅ (see tables below for numbers) |
| [fraudulent signature is generated](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/libraries/operator/Groups.sol#L377) | ✅ ([100% of min stake](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/libraries/operator/Groups.sol#L396)) |

Minimum stake started at `100,000 KEEP` (at [`2020-04-28 02:52:46 UTC`](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/TokenStaking.sol#L85)) and decreases in `10,000 KEEP` steps down to `10,000 KEEP` over the course of two years.

| Date | min stake |
| ---- | ---- |
| 2020-04-28 02:52:46 UTC | 100,000
| 2020-07-09 02:52:46 UTC | 90,000
| 2020-09-19 02:52:46 UTC | 80,000
| 2020-11-30 02:52:46 UTC | 70,000
| 2021-02-10 02:52:46 UTC | 60,000
| 2021-04-23 02:52:46 UTC | 50,000
| 2021-07-04 02:52:46 UTC | 40,000
| 2021-09-14 02:52:46 UTC | 30,000
| 2021-11-25 02:52:46 UTC | 20,000
| 2022-02-05 02:52:46 UTC | 10,000

For timeouts, i.e. whenever the majority of a group is offline for more than the [6 * 64 blocks](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/KeepRandomBeaconOperator.sol#L107), the below table can be used to find the applied punishment. [Punishment starts at just 1% of the min stake and goes up to 100% of the min stake after 6 months](https://github.com/keep-network/keep-core/blob/b2eb62592058518bcd15a3e3510487a5118c5a61/solidity/contracts/libraries/operator/Groups.sol#L414). Starting point here is the deployment of the `TokenStaking` contract, which was at at `2020-09-10 12:43:40 UTC`.

| Start | End | Stake seized |
| ---- | ---- | ---- |
| `2020-09-10 12:43:40 UTC` | `2020-09-19 02:52:46 UTC` | 1% of 90,000 (= 900) |
| `2020-09-19 02:52:47 UTC` | `2020-11-30 02:52:46 UTC` | 1% of 80,000 (= 800) |
| `2020-11-30 02:52:47 UTC` | `2020-12-10 12:43:40 UTC` | 1% of 70,000 (= 700) |
| `2020-12-10 12:43:40 UTC` | `2021-02-10 02:52:46 UTC` | 50% of 60,000 (= 30,000) |
| `2021-02-10 02:52:47 UTC` | `2021-03-10 12:43:40 UTC` | 50% of 50,000 (= 25,000) |
| `2021-03-10 12:43:41 UTC` | `2021-04-23 02:52:46 UTC` | 100% of 50,000 |
| `2021-07-04 02:52:47 UTC` | `2021-09-14 02:52:46 UTC` | 100% of 40,000 |
| `2021-09-14 02:52:47 UTC` | `2021-11-25 02:52:46 UTC` | 100% of 30,000 |
| `2021-11-25 02:52:47 UTC` | `2022-02-05 02:52:46 UTC` | 100% of 20,000 |
| `2022-02-05 02:52:46 UTC` | - | 100% of 10,000 |

### Seizing

While for the ECDSA/TBTC system stake is fully burned, for the beacon there is a split of 95% of the seized KEEP being burned and the other 5% being rewarded to the reporter of the fault. For example, if someone where to report a timeout on 2020-10-01, members of the beacon group would lose `64 * (80000 * 0.001) = 5120 KEEP`, of which `5120 * 0.95 = 4864` would be burned and `5120 * 0.05 = 256` would be sent to the reporter of the timeout.