Document the v2 coverage pool

docs/exit-markets.adoc

@@ -0,0 +1,102 @@
+= Exit markets
+
+To understand the implied risk of a coverage pool, and to dampen the deleterious
+effects of short-term underwriter behavior, we introduce exit markets.
+
+Exit markets allow underwriters to express their time preference when
+withdrawing. Rather than require all withdrawals to suffer a fixed delay,
+underwriters can withdraw more quickly for a price, in competition with each
+other.
+
+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.
+
+== Mechanism
+
+Instead of a fixed withdrawal delay, collateral pools are paramaterized with a
+cost-free withdrawal period, `P`. This period is how long it takes for a
+withdrawal to clear, when funds are no longer at risk and can be freely removed
+from the collateral pool.
+
+One way to turn this into a market is for the pool to continually "auction off"
+immediate withdrawals. The pool shouldn't auction off more immediate withdrawals
+than some pool-specific risk parameter; it can auction off more at some time
+between now and `P`, but it's unclear how much more.
+
+Auctioning off immediate withdrawal excludes an important risk counter-signal:
+deposits.
+
+=== A physical analog
+
+To develop intuition, consider a fixed arm on a hinge.
+
+<pic>
+
+Forces up and down along the arm counteract each other based on their position
+along the arm and their magnitude perpendicular to the arm. Multiplied together,
+the position and magnitude yield the moment of force, or torque.
+
+<pic>
+
+If we assign the arm the length of the cost-free withdrawal period, `P`, and
+place the origin at the hinge, each force perpendicular to the arm can represent
+a withdrawal or a deposit; the moment arm for each represents the immediacy of a
+withdrawal, and the magnitude of the force represents the amount to be deposited
+or withdrawn, relative to the outstanding underwriter tokens in the pool, `U`.
+
+All perpendicular forces along the fixed arm can be aggregated into one value,
+the torque. "Maximum" torque on the arm would be all the tokens `U` multiplied
+by the cost-free period `P`. Maximum torque means the pool is drained of all
+collateral immediately.
+
+<pic with rubber band>
+
+A feedback mechanism to limit maximum torque works like a rubber band on the
+arm.
+
+This analog makes a few things clear.
+
+There's an obvious aggregate of deposits and withdrawals in the analog in
+torque, or *withdrawal immediacy*. Withdrawal immediacy can be measured in
+percent-pool-days.
+
+The analog as presented only holds at a snapshot in time. As time moves on, each
+force moves closer to the origin / hinge, lessening torque or withdrawal
+immediacy from the pool.
+
+Finally, the analog presents the question: what happens in the face of net
+positive deposits over a period? Is there a fixed platform above the arm,
+preventing periods of net positives from counting toward withdrawal immediacy?
+Or does a similar rubber-band like feedback mechanism apply?
+
+=== Details
+
+Given a pool with total assets `A`, outstanding underwriter tokens `U`, and
+cost-free withdrawal period `P`, we can draw a curve between withdrawal
+immediacy (percent-pool-days) and underwriter tokens.
+
+<pic>
+
+An underwriter withdrawing the entire pool, immediately, costs the entire
+underwriter token supply `U` — not something a rational player would do.
+Withdrawing the entire pool at period `P` costs nothing.
+
+A simple curve used by popular automated market makers is the constant product,
+used as a constraint on the relationship between two sides of a market.
+
+`x * y = k`
+
+In an exit market, `x` is the supply of underwriter tokens paid toward
+withdrawal fees over the sliding window `P`. `y`, on the other hand, is
+withdrawal immediacy. To withdraw 50% of a pool in `P/2`, an underwriter must
+swap underwriter tokens such that the pool constraint is maintained, "buying"
+immediacy.
+
+As time goes on, `y` grows linearly until it hits a max of `100% of the pool *
+P days`, growing the curve constraint `k`. As withdrawals mature, `x` shrinks,
+shrinking the curve constraint `k`.
+
+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`.

DESIGN.md → docs/overview.adoc

@@ -1,6 +1,6 @@
-# Components
+= Components
 
-## The collateral pool
+== The collateral pool
 
 The collateral pool is a collection of single-specific pools that share losses
 if coverage is required.
@@ -21,7 +21,7 @@ suffering any sort of impermanent loss, as they would in an AMM.
 Underwriters are still, however, entering into positions relative to the asset
 the coverage pool is backing.
 
-## The risk manager
+== The risk manager
 
 The risk manager is a person or smart contract with the exclusive right to
 demand coverage from the pool.
@@ -33,23 +33,23 @@ position could bankrupt the collateral pool.
 
 Coverage is always paid out in the pool's covered asset.
 
-## The earnings pool
+== The rewards pool
 
-The earnings pool is a collection of different assets that grows as underwriters
-earn fees and refunds.
+The xref:rewards-pool.adoc[rewards pool] is a collection of different assets
+that grows as underwriters earn fees and refunds.
 
-The earnings pool mints a single earnings token, which is periodically
+The rewards pool mints a single rewards token, which is periodically
 distributed to the collateral pool. Each asset in the collateral pool earns
-based on its earnings rate.
+based on its rewards rate.
 
 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.
 
-As earnings accrue, earnings pool tokens can be withdrawn by underwriters and
-redeemed for the underlying earnings.
+As rewards accrue, rewards pool tokens can be withdrawn by underwriters and
+redeemed for the underlying rewards.
 
-# Efficient collateral liquidation
+= Efficient collateral liquidation
 
 When coverage is demanded by the risk manager, some part of the collateral
 pool must be sold to obtain enough of the covered asset to fulfill the claim.
@@ -70,9 +70,9 @@ buyer is found.
 If the risk manager has made a fill-or-kill claim, the auction will expire and
 notify the risk manager. If not, all funds will remain locked on offer.
 
-# Governance and the market feedback loop
+= Governance and the market feedback loop
 
-# Solving early exits
+= Solving early exits
 
 Underwriters will always be able to front-run on-chain claims against the
 coverage pool.  Rational players can withdraw their liquidity and rewards
@@ -90,7 +90,7 @@ as increased risk of merchanism failure at transitions.
 
 Instead of a fixed delay, we introduce exit markets.
 
-## Exit markets
+== Exit markets
 
 At a given moment, whether or not a liquidation is ongoing, a mass exit from
 the collateral pool implies a pending spike in risk.

docs/rewards-pool.adoc

@@ -0,0 +1,82 @@
+= 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
+portion of the rewards in the pool.
+
+A rewards pool maintains a governable list of recipients and relative reward
+rates. 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.
+
+Rewards tokens are minted constantly over time and distributed according to the
+relative reward rates.
+
+== Accounting for rewards distribution
+
+Given the above scenario, at rewards pool creation. 3 rewards tokens are minted.
+1 is reserved for the WETH collateral pool, and 2 for the WBTC collateral pool.
+
+Every tick, an additional 3 rewards tokens are virtually minted.
+
+.Virtual rewards
+[frame="topbot",options="header"]
+|==============================================
+|Time | WETH virtual rewards | WBTC virtual rewards
+|1    |1                     |2
+|2    |2                     |4
+|3    |3                     |6
+|4    |4                     |8
+|==============================================
+
+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
+[frame="topbot",options="header"]
+|==========================================================================================
+|Time | WETH virtual rewards | WETH real rewards | WBTC virtual rewards | WBTC real rewards
+|1    |1                     |1                  |2                     |2
+|2    |2                     |1                  |4                     |2
+|3    |3                     |1                  |6                     |2
+|4    |4                     |1                  |8                     |2
+|5    |5                     |5                  |9                     |9
+|6    |6                     |5                  |10                    |9
+|7    |7                     |5                  |11                    |9
+|8    |8                     |5                  |12                    |9
+|==========================================================================================
+
+Similarly, any rewards tokens that are exchanged and burned for the underlying
+pool rewards realizes all reward token minting before the exchange occurs.
+
+This structure should make it clear that reward pools scale in the number of
+ongoing reward recipients — with implications for the <<on-chain-efficiency,
+number of assets>> supported as collateral in a coverage pool.
+
+== Relation to collateral pools
+
+A coverage pool has a single rewards pool that receives and manages all
+underwriter earnings. Each single-asset collateral pool is assigned a relative
+rate in the rewards pool, establishing a way for governance to incentivize
+different assets to target a particular pool composition.
+
+If an asset that's accepted as collateral by the coverage pool is intended as
+underwriter rewards, it should first be deposited in the coverage pool, and the
+underwriter token sent to the rewards pool. Following this pattern means a more
+capital-efficient coverage rewards mechanism, though it also means rewards are
+subject to exit markets.
+
+== On-chain efficiency
+
+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
+burn require iterating through all recipients, computing rewards, and minting
+tokens. These costs are ultimately shouldered by reward beneficiaries, and place
+a ceiling on the number of simultaneous reward recipients.
+
+The second is the number of assets being rewarded. Anyone can send a reward pool
+whatever tokens they'd like. Instead of using an allowlist or pushing the cost
+onto reward token holders at redemption time, a short denylist can be used to
+avoid mischief, and reward token holders can decide which tokens they'd like to
+be sent at redemption.

docs/risk-manager.adoc

@@ -0,0 +1,75 @@
+= The risk manager
+
+The risk manager holds a privileged role over the coverage pool. It maintains
+the ability to claim coverage from the pool, liquidating enough collateral from
+the pool to cover an outstanding obligation.
+
+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.
+
+== An example pool
+
+The tBTC v1 coverage pool has one purpose — to backstop the TBTC peg and
+simplify the lives of signers by guaranteeing to take any outstanding TBTC
+liquidation, trading TBTC for ETH.
+
+Because we have no guaranteed bounds on the ETHBTC price, the risk to the pool
+is technically uncapped; if the price of BTC suddenly 10x's relative to ETH, the
+pool is still on the hook for a fixed amount of BTC. On the other hand, once the
+pool takes a TBTC https://docs.keep.network/tbtc/#liquidation[liquidation
+auction], the resulting ETH proceeds should be distributed back to the pool.
+
+== 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
+pool, increasing the portion of the pool on offer over time. Eventually, the
+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.
+
+Consider a collateral pool containing 10 WBTC and 100 WETH, and claim of 1 TBTC.
+
+.A collateral pool under auction
+[frame="topbot",options="header"]
+|============================================
+|Time | Offer | WBTC on offer | WETH on offer
+|1    |1%     |0.1            |1
+|2    |2%     |0.2            |2
+|3    |3%     |0.3            |3
+|4    |4%     |0.4            |4
+|5    |5%     |0.5            |5
+|6    |6%     |0.6            |6
+|7    |7%     |0.7            |7
+|8    |8%     |0.8            |8
+|9    |8%     |0.9            |9
+|10   |10%    |1              |10
+|============================================
+
+For simplicity, assume WBTC and TBTC trade at parity. Regardless of the ETH/WBTC
+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
+up arbitrage opportunities with lower total liquidity requirements.
+
+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.
+
+== Returning funds
+
+If there are funds to return to the pool after a coverage claim, a risk manager
+implementation can do one of two things
+
+1. Deposit the funds in the rewards pool, effectively distributing them across
+   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.