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,27 +1,26 @@
-# Components
+= Components
 
-## The collateral pool
+== The collateral pool
 
-The collateral pool is a collection of single-specific pools that share losses
+The collateral pool is a collection of single asset pools that share losses
 if coverage is required.
 
-Each asset-specific pool accepts a single ERC-20 token as collateral, and
-returns an underwriter token. For example, an asset-specific pool might accept
-deposits in WETH in return for covETH underwriter tokens. Underwriter tokens
-represent an ownership share in the underlying collateral of the asset-specific
-pool.
+Each asset pool accepts a single ERC-20 token as collateral, and returns an
+underwriter token. For example, an asset pool might accept deposits in WETH in
+return for covETH underwriter tokens. Underwriter tokens represent an ownership
+share in the underlying collateral of the asset pool.
 
 Entering the collateral pool exposes an underwriter to the shared risk of
-liquidation across all asset-specific pools, but it *doesn't* require the
-underwriter to enter into any positions relative to other assets in the pool.
-If an underwriter deposits ETH into a collateral pool that accepts ETH and
-WBTC, the underwriter isn't entering into a position relative to WBTC, or
-suffering any sort of impermanent loss, as they would in an AMM.
+liquidation across all asset pools, but it *doesn't* require the underwriter to
+enter into any positions relative to other assets in the pool. If an underwriter
+deposits ETH into a collateral pool that with ETH adn WBTC asset pools, the
+underwriter isn't entering into a position relative to WBTC, or suffering any
+sort of impermanent loss, as they would in an automated market maker.
 
 Underwriters are still, however, entering into positions relative to the asset
 the coverage pool is backing.
 
-## The risk manager
+== <<risk-manager.adoc,The risk manager>>
 
 The risk manager is a person or smart contract with the exclusive right to
 demand coverage from the pool.
@@ -33,23 +32,23 @@ position could bankrupt the collateral pool.
 
 Coverage is always paid out in the pool's covered asset.
 
-## The earnings pool
+== <<rewards-pool.adoc,The rewards pool>>
 
-The earnings pool is a collection of different assets that grows as underwriters
-earn fees and refunds.
+The 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
-distributed to the collateral pool. Each asset in the collateral pool earns
-based on its earnings rate.
+The rewards pool mints a single rewards token, which is periodically
+distributed across the collateral pool. Each asset pool in the collateral pool
+earns 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.
+Over a period of a week, if a collateral pool contains two asset pools — WBTC at
+a 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.
@@ -58,21 +57,21 @@ Liquidating the coverage pool fairly means selling a basket of assets, in a
 fixed ratio, with good price discovery. For this reason, collateral is
 liquidated using a Dutch auction.
 
-The portion of each single-asset pool on offer will increase over time, slowing
-until the entirety of the pool is on offer.
+The portion of each asset pool on offer will increase over time, slowing until
+the entirety of the pool is on offer.
 
 The auction is meant to be flash-loan friendly, allowing easy integration with
-AMMs and other liquidity sources.
+AMMs (automated market makers) and other on-chain liquidity sources.
 
 Once the entirety of the pool is on offer, the auction will remain open until a
 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 +89,7 @@ as increased risk of merchanism failure at transitions.
 
 Instead of a fixed delay, we introduce exit markets.
 
-## Exit markets
+== <<exit-markets.adoc,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,86 @@
+= 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
+asset pool, and a WBTC asset 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 asset pool, and 2 for the WBTC asset 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 | Reward rate
+|1    |1                     |1                  |2                     |2                  | 2 : 1
+|2    |2                     |1                  |4                     |2                  | 2 : 1
+|3    |3                     |1                  |6                     |2                  | 2 : 1
+|4    |4                     |1                  |8                     |2                  | 2 : 1
+|5    |5                     |5                  |9                     |9                  | 1 : 1
+|6    |6                     |5                  |10                    |9                  | 1 : 1
+|7    |7                     |5                  |11                    |9                  | 1 : 1
+|8    |8                     |5                  |12                    |9                  | 1 : 1
+|========================================================================================================
+
+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 asset pool in the collateral pool is assigned a
+relative rate in the rewards pool, establishing a way for governance to
+incentivize different assets to target a particular collateral 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 its asset 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.
+
+For example, in a coverage pool meant to back claims denominated in `TBTC`, with
+a collateral pool containing `WETH` and `WBTC`, any `ETH` earned by the
+underwriters should be deposited into the reward pool as `covETH` rather than
+`WETH`.
+
+== 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 different assets being distributed as reward. 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,84 @@
+= 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 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.
+
+=== Auction velocity
+
+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.
+
+A risk manager might slow the velocity of a falling price auction because it
+believes that the auction is close to "market" price. Alternatively, a manager
+might speed up an auction because it believes the auction is far from "market".
+
+Finally, a risk manager might decide to end an auction early if coverage is no
+longer needed.
+
+== 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.