-
Notifications
You must be signed in to change notification settings - Fork 16
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document the v2 coverage pool #2
base: main
Are you sure you want to change the base?
Conversation
mhluongo
commented
Feb 16, 2021
•
edited
Loading
edited
- Rewards pools
- Depositing funds
- Exit markets (close)
- Auctions (prototype as documentation)
941b56d
to
02ec7cb
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Left notesssss.
docs/overview.adoc
Outdated
|
||
## The collateral pool | ||
== The collateral pool | ||
|
||
The collateral pool is a collection of single-specific pools that share losses |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is the "single-asset-specific pool" a coverage pool or the "collateral pool" is a synonym of "coverage pool"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I need to include this in the overview
Coverage pool ---> Collateral pool ---> Asset B
| \--> Asset A
|
\--> Rewards pool
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would this one below be more accurate?
Coverage pool ---> Collateral pool ---> Asset B
| \--> Collateral pool ---> Asset A
|
\--> Rewards pool
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Collateral pool" containing a number of "asset pools"?
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Went with an explicit reward rate in the second table
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this something you'd see tBTC using, or just an arbitrary feature that could be added to a generic coverage pool?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The velocity adjustment will like make it into both v1 and v2, and the early auction end is useful in v1
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I could probably use some details on how these would apply to develop intuition here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Got it!
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there an unspoken constraint here that the collateral pool should probably only handle auctions that repay in one of the underlying assets?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Auctioning off immediate withdrawal excludes an important risk counter-signal: | ||
deposits. | ||
|
||
=== A physical analog |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In pedant-land, I'm pretty sure even though it's strictly the same, “analogue” is the generally-used spelling in noun form 😬
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think I was going for "analogy"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No the word is the right fit, and the spelling is also right, just not the commonly-used one.
<pic> | ||
|
||
An underwriter withdrawing the entire pool, immediately, costs the entire | ||
underwriter token supply `U` — not something a rational player would do. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Because it implies a gain of 0 underlying assets and a loss of U
, so a total loss, right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Correct
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Feels like it may be worth being explicit about that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If Uniswap can do it, we can do it 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
|
||
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Did not have time to do any diligence on playing this out hehe.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
").
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah I've struggled with this, I might need some tables.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How will be the allocated rewards tokens unlocking? Will an unlocking period be defined on each allocation?
= 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah that's the simpler design, but worse UX / adding a dependency. I'll try to cover both options
|
||
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
docs/overview.adoc
Outdated
|
||
## The collateral pool | ||
== The collateral pool | ||
|
||
The collateral pool is a collection of single-specific pools that share losses |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is the "single-asset-specific pool" a coverage pool or the "collateral pool" is a synonym of "coverage pool"?
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It means the portion of the pool on offer ( eg 3%) from each asset
docs/risk-manager.adoc
Outdated
== 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this a collateral pool that determines the ratio between assets for a coverage claim?
@@ -1,6 +1,6 @@ | |||
# Components | |||
= Components |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Having a glossary would be super helpful.
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
").
docs/overview.adoc
Outdated
|
||
## The collateral pool | ||
== The collateral pool | ||
|
||
The collateral pool is a collection of single-specific pools that share losses |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
docs/overview.adoc
Outdated
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
docs/rewards-pool.adoc
Outdated
|7 |7 |5 |11 |9 | ||
|8 |8 |5 |12 |9 | ||
|========================================================================================== |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
... and partial fill? 😆
H/t @Shadowfiend Co-authored-by: Antonio Salazar Cardozo <[email protected]>
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
|