From 6038195b2699fbe3485620aa8479b9628c619953 Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 09:51:39 +0200 Subject: [PATCH 1/9] Moved DESIGN.adoc to docs-v2 directory This document describes how v2 of coverage pools will work. For v1, we are going to provide another document describing the first release. --- DESIGN.adoc => docs-v2/design.adoc | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename DESIGN.adoc => docs-v2/design.adoc (100%) diff --git a/DESIGN.adoc b/docs-v2/design.adoc similarity index 100% rename from DESIGN.adoc rename to docs-v2/design.adoc From 0e5f6932c0ed70b6e22ceb79beca09d2ce4c12fa Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 09:58:56 +0200 Subject: [PATCH 2/9] Documented v1 components of coverage pools --- docs/design.adoc | 65 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/design.adoc diff --git a/docs/design.adoc b/docs/design.adoc new file mode 100644 index 00000000..545053c0 --- /dev/null +++ b/docs/design.adoc @@ -0,0 +1,65 @@ += Components + +== Asset pool + +Asset pool accepts a single ERC-20 token as collateral, and returns an +underwriter token. For example, an asset-specific pool might accept +deposits in KEEP in return for covKEEP underwriter tokens. Underwriter tokens +represent an ownership share in the underlying collateral of the asset-specific +pool, including ownership in rewards accrued by the asset pool. + +Underwriter tokens natively support meta transactions. This means owners can +authorize a transfer of their underwriter tokens with a signature rather than +an on-chain transaction from their address. The signed message conforms EIP-712 +standard, the same one used by Uniswap pool share tokens or MakerDAO DAI tokens. +Anyone can submit the signature on the owner's behalf by calling the EIP-2612 +permit function, paying gas fees and possibly performing other actions in the +same transaction. + +== Rewards pool + +Rewards pool accepts a single ERC-20 token as a reward and releases it to the +asset pool over time in one-week reward intervals. The owner of the rewards pool +is the reward manager address funding the pool with rewards. The token released +by the reward pool is the same ERC-20 token as the one accepted by the asset +pool as collateral. + +== Coverage pool + +Coverage pool is an owner of the asset pool with the right to demand coverage +from the pool. The coverage pool keeps a governable list of approved risk +managers allowed to claim the coverage. + +== Risk manager + +Risk manager is a smart contract with the exclusive right to claim coverage +from the coverage pool. + +Demanding coverage is akin to filing a claim in traditional insurance and +processing your own claim. The risk manager holds an incredibly privileged +position, because the ability to claim coverage of an arbitrarily large +position could bankrupt the coverage pool. + +Because of the nature of the role, the risk manager is a critical component of +the coverage pool. Depending on the implementation, a risk manager can determine +whether to put assets at capped or uncapped risk; how quickly auctions should +put collateral up on offer; whether to end an auction early; and whether to +remunerate existing underwriters in the case of "extra" assets on hand from an +auction. + +Coverage is always paid out in the pool's covered asset. + +== Auctions + +When the risk manager claims coverage, it specifies an amount denominated in +the asset the pool covers. An auction is opened, increasing the portion of the +pool on offer over time. Eventually, if no offer was taken, the entire coverage +pool is on offer. + +For an auction to be filled, a participant pays the asking price, and in return +receives a portion of the asset from the asset pool. An auction can be filled +partially, allowing multiple participants to take the offer. + +In addition to claiming coverage and opening an auction, the risk manager +determines the length of the auction, determining its velocity. Risk manager +might decide to end an auction early if coverage is no longer needed. \ No newline at end of file From debe85bc5af3260cf56b54d8b023a645e4599d0e Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 11:42:49 +0200 Subject: [PATCH 3/9] Added overview section to v1 cov pool documentation --- docs/design.adoc | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/design.adoc b/docs/design.adoc index 545053c0..632f4c93 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -1,6 +1,19 @@ -= Components += Coverage pool -== Asset pool +== Overview + +A coverage pool is a flexible new money lego that can be used as a back-stop or +"buyer of last resort" in on-chain financial systems. It is a governable, +fee-earning pool to cover low-likelihood on-chain events. + +This document describes v1, single-asset version of a coverage pool. + +v2 of a coverage pool includes a multi-asset coverage and rewards, and is +covered in v2 documentation. + +== Components + +=== Asset pool Asset pool accepts a single ERC-20 token as collateral, and returns an underwriter token. For example, an asset-specific pool might accept @@ -16,7 +29,7 @@ Anyone can submit the signature on the owner's behalf by calling the EIP-2612 permit function, paying gas fees and possibly performing other actions in the same transaction. -== Rewards pool +=== Rewards pool Rewards pool accepts a single ERC-20 token as a reward and releases it to the asset pool over time in one-week reward intervals. The owner of the rewards pool @@ -24,13 +37,13 @@ is the reward manager address funding the pool with rewards. The token released by the reward pool is the same ERC-20 token as the one accepted by the asset pool as collateral. -== Coverage pool +=== Coverage pool Coverage pool is an owner of the asset pool with the right to demand coverage from the pool. The coverage pool keeps a governable list of approved risk managers allowed to claim the coverage. -== Risk manager +=== Risk manager Risk manager is a smart contract with the exclusive right to claim coverage from the coverage pool. @@ -49,7 +62,7 @@ auction. Coverage is always paid out in the pool's covered asset. -== Auctions +=== Auctions When the risk manager claims coverage, it specifies an amount denominated in the asset the pool covers. An auction is opened, increasing the portion of the @@ -62,4 +75,4 @@ partially, allowing multiple participants to take the offer. In addition to claiming coverage and opening an auction, the risk manager determines the length of the auction, determining its velocity. Risk manager -might decide to end an auction early if coverage is no longer needed. \ No newline at end of file +might decide to end an auction early if coverage is no longer needed. From e25e24e1b8834444dda2cdba51bda373f44445db Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 12:18:46 +0200 Subject: [PATCH 4/9] Added section on depositing and withdrawal from the pool --- docs/design.adoc | 140 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 1 deletion(-) diff --git a/docs/design.adoc b/docs/design.adoc index 632f4c93..f7b29832 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -6,7 +6,7 @@ A coverage pool is a flexible new money lego that can be used as a back-stop or "buyer of last resort" in on-chain financial systems. It is a governable, fee-earning pool to cover low-likelihood on-chain events. -This document describes v1, single-asset version of a coverage pool. +This document describes the v1, single-asset version of a coverage pool. v2 of a coverage pool includes a multi-asset coverage and rewards, and is covered in v2 documentation. @@ -76,3 +76,141 @@ partially, allowing multiple participants to take the offer. In addition to claiming coverage and opening an auction, the risk manager determines the length of the auction, determining its velocity. Risk manager might decide to end an auction early if coverage is no longer needed. + +== Depositing and withdrawing from the pool + +Underwriters can deposit into the pool at any time and they can top up their +positions at any time with no initialization period. + +There is a fixed, non-governable, two-week withdrawal period for underwriters. +During this period, underwriters are earning rewards but their positions are +also a subject of potential claims of the risk manager. + +Before asset pool balance sheet changes during deposit, withdrawal, or claim +operations, asset pool withdraws unlocked rewards from the rewards pool. +This way, asset pool can adjust the number of underwriter (COV) tokens minted so +that new underwriters are not participating in rewards accrued by the pool +before they joined. Also, rewards unlocked by the rewards pool are +"auto-compounding" for the asset pool underwriters: + +``` +COV_toMint / COV_totalSupply = collateral_toDeposit / collateral_totalDeposited +COV_toMint = collateral_toDeposit * COV_totalSupply / collateral_totalDeposited +``` + +The three scenarios below illustrate how deposit and withdrawal works, and how +coverage claim affects the asset pool. For simplicity, a two-week withdrawal +period has been omitted. + +=== Scenario 1 + +==== Description +70k KEEP allocated as a weekly reward. + +Three underwriters depositing roughly at the same time: + +* underwriter 1 depositing 150k KEEP +* underwriter 2 depositing 50k KEEP +* underwriter 3 depositing 200k KEEP + +After four days, 40k KEEP rewards unlocked and all three underwriters are +withdrawing from the pool. + +==== Earnings +* underwriter 1: 15k KEEP +* underwriter 2: 5k KEEP +* underwriter 3: 20k KEEP + +==== Explanation +* underwriter 1 has 150/400 share of the pool (150k out of 400k COV tokens), + + they can claim 150/400 rewards unlocked: 150 / 400 * 40k = 15k +* underwriter 2 has 50/400 share of the pool. (50k out of 400k COV tokens), + + they can claim 50/400 rewards unlocked: 50 / 400 * 40k = 5k +* underwriter 3 has 200/400 share of the pool. (200k out of 400k COV tokens), + + they can claim 200/400 rewards unlocked: 200/400 * 40k = 20k + +=== Scenario 2 + +70k KEEP allocated as a weekly reward. + +Three underwriters depositing: + +* underwriter 1 depositing 150k KEEP +* underwriter 2 depositing 50k KEEP after 24 hours +* underwriter 3 depositing 200k KEEP after 24 hours + +24 hours passes, all three underwriters are withdrawing from the pool. + +==== Earnings +* underwriter 1: ~21610 KEEP +* underwriter 2: ~3627 KEEP +* underwriter 3: ~4761 KEEP + +==== Explanation +Underwriter 1 is depositing. They receive 150k COV tokens. + +For the first 24 hours, underwriter 1 is the only one in the pool. +They earn 70k / 7 = 10k KEEP. + +Underwriter 2 is depositing. There is 150k + 10k KEEP is in the pool at that +time (deposited and rewarded). The pool needs too adjust the amount of COV +tokens minted for underwriter 2 so that they do not take a share of rewards +accrued by the pool so far: COV_minted = 50k * 150k / 160k = 46.87k. + +For the next 24 hours. there are two underwriters in the pool and they earn +rewards proportionally to their share in the pool: + +* underwriter 1: 150 / 196.87 * 10k = 7619.24 KEEP +* underwriter 2: 46.87 / 196.87 * 10k = 2380.75 KEEP + +Underwriter 3 is depositing. 150k + 10k + 50k + 10k is in the pool at that time +(deposited and rewarded). The pool needs to adjust the amount of COV tokens +minted for underwriter 3 so that they do not take a share of rewards accrued by +the pool so far: COV_minted = 200k * 196.87k / 220k = 178.97k. + +For the next 24 hours, there are three underwriters in the pool and they earn +rewards proportionally to their share: + +- underwriter 1: 150 / 375.84 * 10k = 3991.06 KEEP +- underwriter 2: 46.87 / 375.84 * 10k = 1247.07 KEEP +- underwriter 3: 178.97 / 375.84 * 10k = 4761.86 KEEP + +In total, underwriters earn: + +- underwriter 1: 10k + 7619.24 + 3991.06 = 21610.3 KEEP +- underwriter 2: 2380.75 + 1247.07 = 3627.82 KEEP +- underwriter 3: 4761.86 KEEP + + +=== Scenario 3 + +This scenario is an extension of Scenario 2 with an additional claim for +50k KEEP tokens from the coverage pool at the end. + +There is 430k KEEP in the pool (deposited + rewards). + +* underwriter 1 has 150 / 375.84 = 0.399 of the pool (= (150k + 21 610) / 430k)) +* underwriter 2 has 46.87 / 375.84 = 0.124 of the pool (= (50k + 3 627) / 430k)) +* underwriter 3 has 178.97 / 375.84 = 0.476 of the pool (= (200k + 4 761) / 430k)) + +The coverage pool claims 50k KEEP and all underwriters withdraw their funds +right after. + +==== Earnings +- underwriter 1: 1655 KEEP +- underwriter 2: -2608 KEEP +- underwriter 3: -19048 KEEP + +==== Explanation + +Coverage pool loses 50k KEEP. Underwriters are expected to take a hit +proportionally to their share of the pool: + +* underwriter 1: -50k * 150 / 375.84 = -19955 KEEP +* underwriter 2: -50k * 46.87 / 375.84 = -50k * 0.124 = -6235 KEEP +* underwriter 3: -50k * 178.97 / 375.84 = -50k * 0.476 = -23809 KEEP + +In total, underwriters earn/lose: + +* underwriter 1: 21610 - 19955 = 1655 KEEP +* underwriter 2: 3627 - 6235 = -2608 KEEP +* underwriter 3: 4761 - 23809 = -19048 KEEP \ No newline at end of file From 322843e37ddd0f91c43c203ecf9996abb1e4679a Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 13:59:45 +0200 Subject: [PATCH 5/9] Explained how tBTC v1 risk manager is going to work --- docs/design.adoc | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/design.adoc b/docs/design.adoc index f7b29832..0a59e822 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -186,7 +186,7 @@ In total, underwriters earn: This scenario is an extension of Scenario 2 with an additional claim for 50k KEEP tokens from the coverage pool at the end. -There is 430k KEEP in the pool (deposited + rewards). +There is 430k KEEP in the pool (deposited + rewards): * underwriter 1 has 150 / 375.84 = 0.399 of the pool (= (150k + 21 610) / 430k)) * underwriter 2 has 46.87 / 375.84 = 0.124 of the pool (= (50k + 3 627) / 430k)) @@ -213,4 +213,29 @@ In total, underwriters earn/lose: * underwriter 1: 21610 - 19955 = 1655 KEEP * underwriter 2: 3627 - 6235 = -2608 KEEP -* underwriter 3: 4761 - 23809 = -19048 KEEP \ No newline at end of file +* underwriter 3: 4761 - 23809 = -19048 KEEP + +== tBTC v1 risk manager + +tBTC v1 risk manager will be the first implementation of a risk manager approved +by the coverage pool. The coverage pool will contribute to potentially lowering +collateral ratios and scaling tBTC’s TVL. The coverage pool serves as a buyer +of last resort. It purchases enough TBTC on auction to make the depositor whole +in the event of liquidation if the stakers' collateral is not sufficient. + +In case of liquidation of a tBTC deposit below a certain collateralization +threshold, the risk manager opens an auction to acquire TBTC to purchase signer +bonds. Collateralization threshold and auction length are governable parameters. + +ETH purchased by the risk manager from tBTC signer bonds is swapped and +transferred to the asset pool and there are two strategies for doing that: + +* ETH is automatically swapped to asset pool underlying token on Uniswap, +* ETH is deposited in the escrow contract allowing the governance to do the swap + manually and deposit the underlying token to the asset pool. + +Which strategy is used is a governable parameter. + +In case signer bonds were purchased by a third party before the auction was +fully filled, TBTC acquired by the risk manager from potential partial auction +takes will be used in the future, reducing the amount of a next auction. \ No newline at end of file From 3ba17eb3f7bcd0c6d9a6eb1889b885123f5d9227 Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 14:08:54 +0200 Subject: [PATCH 6/9] Added documentation section on upgradeability --- docs/design.adoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/design.adoc b/docs/design.adoc index 0a59e822..dce2e10e 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -238,4 +238,11 @@ Which strategy is used is a governable parameter. In case signer bonds were purchased by a third party before the auction was fully filled, TBTC acquired by the risk manager from potential partial auction -takes will be used in the future, reducing the amount of a next auction. \ No newline at end of file +takes will be used in the future, reducing the amount of a next auction. + +== Upgradeability + +All coverage pool contracts are non-upgradeable and there are few governable +parameters listed in the next section. Underwriters can migrate to a new version +of coverage pool by moving their collateral to a new asset pool approved by the +governance. \ No newline at end of file From d9c3ed2cfaf84670df3de949163dcaf58c39b902 Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Mon, 17 May 2021 14:32:28 +0200 Subject: [PATCH 7/9] Added section on v1 governance to the docs --- docs/design.adoc | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/design.adoc b/docs/design.adoc index dce2e10e..9511a8e7 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -245,4 +245,38 @@ takes will be used in the future, reducing the amount of a next auction. All coverage pool contracts are non-upgradeable and there are few governable parameters listed in the next section. Underwriters can migrate to a new version of coverage pool by moving their collateral to a new asset pool approved by the -governance. \ No newline at end of file +governance. + +== Governance + +The governance included in the system design follows two principles: + +* All governance should abide by a time delay, giving users time to respond + to changes in the system. +* The governance role should be assignable to a credibly neutral third party or + eventual decentralization, such as the community multisig. + +.Governable parameters +|=== +|Parameter |Time delay|Description + +|Approved risk managers +|30 days +|Governance can approve and unapprove a risk manager. + +|Auction length +|12 hours +|Governance can adjust auction length based on coverage pool TVL and the minimum +possible auctioned value. + +|tBTC deposit collateralization +|12 hours +|Governance can set the maximum collateralization level of tBTC deposit under +the liquidation the tBTC v1 risk manager is going to open an auction for. The +risk manager is a buyer of the last resort and should not work with tBTC +liquidating deposits still attractive for arbitraging bots. + +|The strategy for depositing purchased tBTC signer bonds +|12 hours +|Governance can chose which strategy should be used by tBTC v1 risk manager for +depositing ETH signer bonds purchased from tBTC to the asset pool. \ No newline at end of file From 2e778f6cbc55a25b484b825a3cbed90c4b6dda63 Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Wed, 19 May 2021 15:42:53 +0200 Subject: [PATCH 8/9] Changed the mechanism risk manager uses for managing auction surplus The mechanism previously proposed has two flaws. First, it is hard to implement and requires a lot of additional bookkeeping in the contract given that multiple auctions can be open at the same time and all of them can generate a surplus. Secondly, it might happen that the auction gets opened for 0.0001 TBTC because the rest was filled by the surplus. In this scenario, the auction value is much lower than the minimum tBTC lot size and the auction length set by the governance could make not sense. --- docs/design.adoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/design.adoc b/docs/design.adoc index 9511a8e7..1a68487e 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -238,7 +238,16 @@ Which strategy is used is a governable parameter. In case signer bonds were purchased by a third party before the auction was fully filled, TBTC acquired by the risk manager from potential partial auction -takes will be used in the future, reducing the amount of a next auction. +takes will be used in the future, to purchase signer bonds once the accumulated +surplus value allows for it. For example: + +* Liquidation of 1 TBTC deposit, auction opened for 1 TBTC and early closed + after being filled for 0.3 TBTC total. 0.3 TBTC goes to the risk manager. +* Liquidation of 1 TBTC deposit, auction opened for 1 TBTC and early closed + after being filled for 0.8 TBTC total. 0.8 TBTC goes to the risk manager. +* Liquidation of 1 TBTC deposit, there is 1.1 TBTC in the surplus, instead of + opening an auction, risk manager purchases signer bonds reducing the surplus + to 0.1 TBTC. == Upgradeability From fd0f88ac27910244f04fcf3b5cdad9492e21c554 Mon Sep 17 00:00:00 2001 From: Piotr Dyraga Date: Wed, 19 May 2021 16:26:42 +0200 Subject: [PATCH 9/9] Added links to v1 design docs and Discord from README --- README.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.adoc b/README.adoc index c72f730e..7edce0bd 100644 --- a/README.adoc +++ b/README.adoc @@ -58,6 +58,12 @@ the market. If you need to cover risk in a new system... maybe because you're building a synthetic asset exchange, or a lending platform — coverage pools might be for you. +== Getting started + +* Read the link:./docs/design.adoc[v1 design documentation]. +* For questions and support, join the #keep-protocol channel on +https://discord.gg/4R6RGFf[Discord]. + == Build and test Coverage pool contracts use https://hardhat.org/[*Hardhat*] development