Document the v2 coverage pool #2

mhluongo · 2021-02-16T15:08:44Z

Rewards pools
Depositing funds
Exit markets (close)
Auctions (prototype as documentation)

docs/overview.adoc

Shadowfiend

Left notesssss.

Shadowfiend · 2021-02-18T19:58:25Z

docs/overview.adoc


-## The collateral pool
+== The collateral pool

 The collateral pool is a collection of single-specific pools that share losses


Suggested change

The collateral pool is a collection of single-specific pools that share losses

The collateral pool is a collection of single-asset-specific pools that share losses

?

Is the "single-asset-specific pool" a coverage pool or the "collateral pool" is a synonym of "coverage pool"?

I think a coverage pool is a collection of single-asset-specific collateral pools... 🤔 A coverage pool is backed by multiple tokens, with a separate collateral pool for each token.

I need to include this in the overview

Coverage pool ---> Collateral pool ---> Asset B | \--> Asset A | \--> Rewards pool

Would this one below be more accurate?

Coverage pool ---> Collateral pool ---> Asset B | \--> Collateral pool ---> Asset A | \--> Rewards pool

I need a name for the collection of collateral pools in your diagram above. Either a collateral pool holds asset A, B, C, and a coverage pool has one, or a coverage pool has multiple collateral pools.

We need to be able to easily say "3% of all assets across the coverage pool were auctioned off" but refer to just collateral, and not eg the rewards pool.

"Collateral pool" containing a number of "asset pools"?

docs/overview.adoc

Shadowfiend · 2021-02-18T20:43:33Z

docs/rewards-pool.adoc

+At tick 5, if the rewards rates are changed, say to 1:1, the rewards tokens are
+realized, then the virtual minting continues at the new rate.
+
+.Virtual and real rewards


Worth clarifying that this is with a change in rate at tick 5, or include that in the table. Might also be nice to progressively disclose with a version of the first table that adds real rewards before adding the change at tick 5.

Went with an explicit reward rate in the second table

docs/rewards-pool.adoc

Shadowfiend · 2021-02-18T21:00:19Z

docs/risk-manager.adoc

+In addition to claiming coverage and opening an auction, the risk manager
+determines the parameters that govern the auction, including the velocity of the
+falling price based on market conditions, and whether to withdraw a claim and
+end an auction early.


Is this something you'd see tBTC using, or just an arbitrary feature that could be added to a generic coverage pool?

The velocity adjustment will like make it into both v1 and v2, and the early auction end is useful in v1

I could probably use some details on how these would apply to develop intuition here.

Practicing before I update the doc...

slowing the velocity of a falling price auction means you believe, for whatever reason, that you're close to the "market" price

speeding up means you think you have a way to go. If there's a mass exit attempt, maybe the auction should be sped up

I don't know if I'll be able to generally describe when exit markets can be used to speed or slow auctions in the first revision of coverage pools.

The last one (ending an auction) might happen in tBTC v1 if someone else takes a tBTC liquidation, and we no longer have reason to claim coverage.

Shadowfiend · 2021-02-18T21:09:32Z

docs/risk-manager.adoc

+   underwriters based on the relative reward rate, regardless of the asset.
+2. Deposit the funds directly in the collateral pool, requiring funds to be
+   traded to match the existing collateral distribution, or intentionally
+   distributing funds in a way that favors a particular underwritten asset.


Is there an unspoken constraint here that the collateral pool should probably only handle auctions that repay in one of the underlying assets?

Nope, though there is an assumption that governance will know that the sum of the collateral in the pool is going to be paying out in a particular asset, and choose the acceptable collateral accordingly.

Neither version of tBTC would use the single-collateral version of 2. mentioned here, but it might make sense in both v1 and v2 to auction the pool for TBTC, get ETH, then have a strategy to Uniswap that back to to original asset composition

Shadowfiend · 2021-02-18T21:11:24Z

docs/exit-markets.adoc

+Auctioning off immediate withdrawal excludes an important risk counter-signal:
+deposits.
+
+=== A physical analog


In pedant-land, I'm pretty sure even though it's strictly the same, “analogue” is the generally-used spelling in noun form 😬

I think I was going for "analogy"

No the word is the right fit, and the spelling is also right, just not the commonly-used one.

Shadowfiend · 2021-02-18T21:18:04Z

docs/exit-markets.adoc

+<pic>
+
+An underwriter withdrawing the entire pool, immediately, costs the entire
+underwriter token supply `U` — not something a rational player would do.


Because it implies a gain of 0 underlying assets and a loss of U, so a total loss, right?

Feels like it may be worth being explicit about that.

By continuity we may not be able to do this; if we want the cost of withdrawing x + y tokens at once to equal the cost of withdrawing x tokens and then y tokens later in the same block it implies that withdrawing any amount immediately must cost the entire withdrawn amount

And if we don't have continuity, it's possible to withdraw the entire pool immediately without losing the entire token supply by splitting up the withdrawal into smaller withdrawals unless we prevent immediate withdrawals altogether and bundle withdrawals together across one or more blocks

If Uniswap can do it, we can do it 😄

It's too Friday evening for me to articulate this precisely, but isn't how Uniswap does it that you have assets A and B, and the pool has T tokens issued so that A * B = T^2 * K, so if you try to get all A assets out you have to pay infinity B tokens in, but if you pay in 100% of T tokens you get 100% of both A and B out of it?

Shadowfiend · 2021-02-18T21:34:51Z

docs/exit-markets.adoc

+
+As new funds enter the pool, `y` grows by `r * P` where `r` is the portion of
+the pool the new funds represent, maintaining the constraint `k`. `y` never
+exceeds `100% * P`.


Did not have time to do any diligence on playing this out hehe.

Some examples could be helpful. 😬 For example, at first, I thought y is just a function of time ("as the time goes on y grows linearly") but it is probably* a function of time and pool's liquidity ("As new funds enter the pool, y grows by r * P").

Yeah I've struggled with this, I might need some tables.

docs/overview.adoc

nkuba · 2021-02-18T15:17:29Z

docs/rewards-pool.adoc

+collateral pool, and a WBTC collateral pool, with respective reward rates of 1
+and 2.
+
+Rewards tokens are minted constantly over time and distributed according to the


Is it a linear distribution? How will the rules for tokens releasing be defined, e.g. at each rewards tokens allocation, and be constant over a specific period? Would it be possible to top-up the rewards pool? Do we want to take an example of how TokenGeyser's rewards pools work?

So this will be different from TokenGeyser's rewards pool as the rewards pool won't distribute underlying reward tokens directly but mint tokens as a share in the whole rewards pool, right?

How will be the allocated rewards tokens unlocking? Will an unlocking period be defined on each allocation?

docs/rewards-pool.adoc

nkuba · 2021-02-18T15:49:04Z

docs/rewards-pool.adoc

+= The rewards pool
+
+A rewards pool is a contract that accepts arbitrary assets and mints a single
+reward token. Recipients of the reward token can at any time turn it in for a


Assuming a rewards pool supports multiple tokens as rewards, and we're minting one type of token as a share of the rewards pool, how will we handle a situation when any of the rewards tokens is allocated at random points in time? The rewards pool won't pay attention to when a staker joined the coverage pool (what tokens were placed in the rewards pool at that point), only stake milliseconds matter, right?

I'm working on that part now — "depositing funds". What I'd like to do is make new entrants pay for the outstanding rewards rather than track entry per depositor.

For example, if you want covWBTC, and the WBTC pool has 100 reward tokens assigned to it, you pay some of your WBTC to account for that.

That sounds like it's going to have lots of annoying hidden complexity that could end up either gameable or discouraging pool entry, with the correct balance being hard to strike. Tracking rewards[depositor][token] seems easier even if it gets slightly more expensive with a wide variety of reward tokens.

Your way breaks composability. If we do that we can't issue fungible underwriter token, or we issue them and they aren't reward yielding.

Give me a bit to write this up, I think I can convince you (and it's a generalization of exit markets)

Can we have you pay in the reward tokens instead of the asset itself, so we don't need to worry about exchange rates between asset and rewards?

Yeah that's the simpler design, but worse UX / adding a dependency. I'll try to cover both options

nkuba · 2021-02-19T08:37:26Z

docs/rewards-pool.adoc

+
+There are two bottlenecks in efficient runtime on the EVM with this structure.
+
+The first is the number of reward recipients. Each rate change and reward token


For example, a rewards pool might have two recipients — a WETH collateral pool, and a WBTC collateral pool, with respective reward rates of 1 and 2.

I was under an impression that coverage pools will be recipients of the rewards pool. Couldn't coverage pools be the recipients?

nkuba · 2021-02-19T08:55:20Z

docs/overview.adoc


-## The collateral pool
+== The collateral pool

 The collateral pool is a collection of single-specific pools that share losses


Is the "single-asset-specific pool" a coverage pool or the "collateral pool" is a synonym of "coverage pool"?

nkuba · 2021-02-19T09:19:11Z

docs/risk-manager.adoc

+entire collateral pool is on offer.
+
+For an auction to be filled, a participant pays the asking price, and in return
+receives a portion of each asset in the pool.


What do you mean by "a portion of each asset in the pool"? Does it refer to a portion of multiple types of assets across a collection of single-asset pools?

It means the portion of the pool on offer ( eg 3%) from each asset

nkuba · 2021-02-19T09:29:06Z

docs/risk-manager.adoc

+== Auctions
+
+When the risk manager claims coverage, it specifies an amount denominated in
+the asset the pool covers. An auction is opened across across all assets in the


Is this a collateral pool that determines the ratio between assets for a coverage claim?

nkuba · 2021-02-19T09:31:58Z

docs/overview.adoc

@@ -1,6 +1,6 @@
-# Components
+= Components


Having a glossary would be super helpful.

pdyraga · 2021-02-19T10:13:50Z

docs/exit-markets.adoc

+
+Exit markets smooth out coverage pool liquidity and the discontinuity of
+fixed-delay withdrawals, and expose a proxy for the short-term risk of the
+pool — the withdrawal fee curve.


I see a value for underwriters being able to exit the pool early but it is not entirely clear to me how the exit market will smooth the liquidity and why is it better for the pool compared to a fixed withdrawal period.

If all underwriters wait for P before withdrawing tokens, it is the same as waiting for a fixed withdrawal period.

If some underwriters do not wait for P, their withdrawal fees fuel up the pool, but even though the pool has shrunk - it has lower liquidity than it would have in the case of a fixed withdrawal period.

For example, let's say I deposited 100 WETH into the pool. At P/2 I decided to withdraw. I had to leave 30% of my tokens in the pool. We can say that the pool earned 30 WETH. But at the same time, for the remaining P/2 its liquidity shrunk by 70 WETH.

If some underwriters do not wait for P, their withdrawal fees fuel up the pool, but even though the pool has shrunk - it has lower liquidity than it would have in the case of a fixed withdrawal period.

The assumption is that allowing quicker withdrawals will lead to greater total liquidity over the lifetime of a pool, compared to a fixed period pool, because the structure is more friendly to underwriters who are giving up opportunity cost.

docs/exit-markets.adoc

pdyraga · 2021-02-19T10:53:00Z

docs/exit-markets.adoc

+
+As new funds enter the pool, `y` grows by `r * P` where `r` is the portion of
+the pool the new funds represent, maintaining the constraint `k`. `y` never
+exceeds `100% * P`.


Some examples could be helpful. 😬 For example, at first, I thought y is just a function of time ("as the time goes on y grows linearly") but it is probably* a function of time and pool's liquidity ("As new funds enter the pool, y grows by r * P").

pdyraga · 2021-02-19T11:07:51Z

docs/overview.adoc


-## The collateral pool
+== The collateral pool

 The collateral pool is a collection of single-specific pools that share losses


I think a coverage pool is a collection of single-asset-specific collateral pools... 🤔 A coverage pool is backed by multiple tokens, with a separate collateral pool for each token.

pdyraga · 2021-02-19T11:13:53Z

docs/overview.adoc

 Over a period of a week, if a collateral pool contains two assets — WBTC at a
-earnings rate of 2, and ETH at an earnings rate of 1 — each will be allocated
-earnings pool tokens at a rate of 2 to 1.
+rewards rate of 2, and ETH at an rewards rate of 1 — each will be allocated
+rewards pool tokens at a rate of 2 to 1.


Over a period of a week, if a **coverage** pool contains two assets — WBTC at a rewards rate of 2, and ETH at a rewards rate of 1 — each **collateral pool** will be allocated rewards pool tokens at a rate of 2 to 1.

?

A collateral pool is a single-asset pool, it accepts token and mints underwriter token, it can't have more than two assets. At least that's my understanding heh.

I'm considering changing the terminology up a bit here. Whether all of the collateral is in one pile (eg Maker's vat) or in separate contracts isn't material to the design. Will give it some thought.

The important thing to understand is that If you put in WBTC, you get covWBTC, and you aren't taking an esoteric position against other assets in the pool like you might in an automated market maker.

pdyraga · 2021-02-19T11:41:36Z

docs/rewards-pool.adoc

+|7    |7                     |5                  |11                    |9
+|8    |8                     |5                  |12                    |9
+|==========================================================================================


I am not sure I follow how virtual rewards are turned into real rewards, it would be good to mark when rewards are materialized.

My understanding is that the first realization of rewards happened after interval 1.
Then they were not getting realized until interval 5 ended.
When that happened:

There were 5 - 1 = 4 unspent WETH virtual rewards.

There were 9 - 2 = 7 unspent WBTC virtual rewards.

4 real rewards were allocated to WETH pool, making a total of real rewards 1 + 4 = 5.

7 real rewards were allocated to WBTC pool, making a total of real rewards 2 + 7 = 9.

Also, I do not understand how the amount of allocated rewards maps to realized rewards. In the table we assumed 1 virtual reward = 1 real reward but I guess it may happen when it is not 1:1.

pdyraga · 2021-02-19T11:53:16Z

docs/rewards-pool.adoc

+
+The first is the number of reward recipients. Each rate change and reward token
+burn require iterating through all recipients, computing rewards, and minting
+tokens. These costs are ultimately shouldered by reward beneficiaries, and place


Iterating through everyone is an out-of-gas DoS attack vector, there has to be a way, otherwise, I am afraid it's a non-go. I wonder if we can reuse some logic from TokenGeyser contract - the usage case seems pretty similar. I stake my tokens in a pool, based on how long I stake, I receive rewards proportionally to other stakers in the pool.

pdyraga · 2021-02-19T12:41:27Z

docs/risk-manager.adoc

+exchange rate, there is a point between `t=1` and `t=10` where it makes sense to
+buy all assets on offer.
+
+An efficient on-chain implementation can allow partial and atomic fills, opening


... and partial fill? 😆

docs/overview.adoc

@Shadowfiend

H/t @Shadowfiend Co-authored-by: Antonio Salazar Cardozo <antonio@keep.network>

mhluongo · 2021-03-20T21:46:22Z

I've tried to address the "easy" concerns here, and it's ready for another pass.

I'll take this out of draft when I've

Included the simpler fund-depositing scheme (adding reward tokens)
Given then exit market bit some more rigor / maybe added tables

mhluongo requested review from Shadowfiend, pdyraga, Battenfield, eth-r, nkuba and dougvk February 16, 2021 15:08

mhluongo added 3 commits February 17, 2021 23:13

Describe exit markets

930dfbb

Describe the rewards pool

39b6ee0

Describe the risk manager role

02ec7cb

mhluongo force-pushed the expand-docs branch from 941b56d to 02ec7cb Compare February 18, 2021 04:14

Shadowfiend reviewed Feb 18, 2021

View reviewed changes

docs/overview.adoc Outdated Show resolved Hide resolved

Shadowfiend reviewed Feb 18, 2021

View reviewed changes

nkuba reviewed Feb 19, 2021

View reviewed changes

pdyraga reviewed Feb 19, 2021

View reviewed changes

pdyraga reviewed Mar 15, 2021

View reviewed changes

docs/overview.adoc Show resolved Hide resolved

mhluongo and others added 7 commits March 20, 2021 17:13

s/across across/across

549a24d

H/t @Shadowfiend Co-authored-by: Antonio Salazar Cardozo <antonio@keep.network>

Define "AMM" and other acronyms in the docs

7e2048b

Document an example rewarding a collateral asset

47bca77

Prefer abbreviated xref links in AsciiDoc

0633df7

Link overview sections to more detailed docs

9e29b40

Add reward rate details to the reward pool docs

023afa3

Detail why one might change auction price velocity

cb364a7

mhluongo requested review from pdyraga, Shadowfiend and nkuba March 20, 2021 21:44

Clarify the collateral pool is made of asset pools

cc27130

pdyraga changed the title ~~Document the coverage pool~~ Document the v2 coverage pool May 17, 2021

pdyraga mentioned this pull request May 17, 2021

Document the v1 coverage pool #52

Merged

	The collateral pool is a collection of single-specific pools that share losses
	The collateral pool is a collection of single-asset-specific pools that share losses


		There are two bottlenecks in efficient runtime on the EVM with this structure.

		The first is the number of reward recipients. Each rate change and reward token

Document the v2 coverage pool #2

Are you sure you want to change the base?

Document the v2 coverage pool #2

Conversation

mhluongo commented Feb 16, 2021 • edited Loading

Shadowfiend left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eth-r Feb 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhluongo Mar 20, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhluongo commented Mar 20, 2021

mhluongo commented Feb 16, 2021 •

edited

Loading

eth-r Feb 19, 2021 •

edited

Loading

mhluongo Mar 20, 2021 •

edited

Loading