Merge pull request #294 from keep-network/document-optionally-locked-…

…deposits

Document optionally locked deposits

Begin documenting a two-phase minting process allowing all deposits
to be optionally "locked" to the depositor, or redeemable by anyone (as
in the current system).

This work will have a significant impact on deposit UX, allowing dApps to
let a depositor to more easily walk away while work accumulates on their
Bitcoin transaction.

docs/bonding/index.adoc

@@ -28,7 +28,7 @@ Since signer bonds need to be denominated in a widely traded asset to avoid
 market manipulation, the next most obvious pick for bonding is the host chain's
 native token. For the initial release of tBTC, that means ETH. As the ecosystem
 matures, other bond collateral options might become feasible at the expense of a
-more complex price feed implementation.
+more complex implementation.
 
 == Measuring security
 
@@ -61,7 +61,7 @@ the two currencies fluctuate relative to each other, sometimes wildly.
 If the value of ETH drops precipitously relative to BTC, then the dollar value
 of the ETH bonded by the signers can be less than the dollar value of the BTC
 Deposit they have backed, meaning they have positive expected value if they try
-to steal the BTC. 
+to steal the BTC.
 
 In order to avoid that, we require that the bonds are overcollateralized. For
 each ETH they collateralize, they must put up an additional {extracollateral}, for a total of
@@ -88,25 +88,25 @@ the expense of opportunity cost to the Signers which should be compensated via f
 If the value of ETH crosses a security threshold, open _Deposit_ s will enter
 <<preliq, pre-liquidation>>, followed by <<liq, liquidation>> if they do not top
 up their collateral.
- 
+
 // TODO insert a little historical analysis for a decent starting number
- 
-=== BTC Price Drop relative to ETH
- 
+
+=== BTC price drop relative to ETH
+
 Since <<Custodial Fees>> are denominated per BTC in custody (with
 overcollateralization factored in), a BTC value drop against the
 bonded asset translates in lower fees for Signers. Note that this does not
 create any issue for tBTC reserves, but it makes the system less attractive to
 signers looking to earn interest via fees on their assets.
 
-Signers SHOULD buy TBTC from the markets in anticipation of such overly 
+Signers SHOULD buy TBTC from the markets in anticipation of such overly
 overcollateralized Deposits and they SHOULD use it to redeem these positions,
 thus reclaiming their ETH liquidity which can be used to back other Deposits. An
 alternative would be to provide Signers with the ability to safely rebalance their
 bonds back to {totalcollateral}, however that introduces implementation
 complexities and as a result is not the preferred solution for the initial
 deployment of the mechanism.
- 
+
 Example:
 Let 1 BTC be worth $10,000, and 1 ETH be worth $200. Signers have to put up 75
 ETH to back a deposit. Signers are expected to make a custodial fee of 5 basis
@@ -126,10 +126,10 @@ the market. Instead, the goal is to ensure that the TBTC supply is strictly
 less than its backing BTC reserves.
 
 For this reason, the only price relationship the system needs to understand is
-between the signing bond collateral and BTC. 
+between the signing bond collateral and BTC.
 
 In concrete terms, that means the price of ETH to BTC. Due to only needing
-prices for a single pair of assets, tBTC will initially use a simple 
+prices for a single pair of assets, tBTC will initially use a simple
 <<price-oracle/index.adoc#price-oracle,price oracle>>.
 
 == Undercollateralization
@@ -151,7 +151,7 @@ liquidation will follow. This gives each signer an incentive to close the
 position before it becomes severely undercollateralized. Alternatively, if the
 ETHBTC ratio recovers such that the deposit becomes at least {first-threshold}
 collateralized during the {preliquidation-period} the Deposit is safe and is
-moved away from the pre-liquidation state. 
+moved away from the pre-liquidation state.
 
 In future versions of the system, more complex pre-liquidation mechanisms could
 be introduced. For the initial version it seems prudent to choose a simple
@@ -170,7 +170,7 @@ punishment via liquidation is necessary to prevent dishonest behavior from
 signers. Liquidation may occur because because signers didn't produce a valid
 signature  in response a redemption request, because the value of the signing
 bond dropped below the liquidation threshold, because they did not respond to the
-courtesy call, or because the signers produced a fraudulent signature. 
+courtesy call, or because the signers produced a fraudulent signature.
 // comment(Georgios): What does unauthorized signature mean here?
 
 The primary goal of the liquidation process is to bring the TBTC supply in line
@@ -179,7 +179,7 @@ system is the signers' bonds. Therefore, the liquidation process seizes the
 signers bonds and attempts to use the bonded value to purchase and burn TBTC.
 
 First, the contract attempts to use on-chain liquidity sources, such as
-https://hackmd.io/@477aQ9OrQTCbVR3fq1Qzxg/HJ9jLsfTz[Uniswap]. 
+https://uniswap.io[Uniswap].
 
 If the bond is sufficient to cover the outstanding TBTC value on these
 markets, it is immediately exchanged for TBTC.
@@ -200,7 +200,7 @@ What the unresponsive signers do with the BTC outside the tBTC system design is
 for them to decide-- it might be split up, stolen by a signing majority, or
 lost permanently.
 
-Example: 
+Example:
 1. Signers guard a deposit of 1 BTC, backed by 75 ETH at 0.02 BTC/ETH (1.5 BTC
 in ETH, 150% collateralization ratio).
 
@@ -225,4 +225,4 @@ liquidation of the Deposit is now over.
 fraud it'd be burned), and 0.1 ETH is given to the account which called the
 liquidation function on the Ethereum smart contract.
 
-1. The N signers coordinate and agree on how they will distribute the 1 BTC deposit.
+1. The N signers coordinate and agree on how they will distribute the 1 BTC deposit.

docs/deposits/economics.adoc

@@ -0,0 +1,25 @@
+= Deposit economics
+
+Signers aren't altruists -- they're paid for the service they provide.
+
+Signer fees should always be paid or escrowed up front. To achieve this, signer
+fees must be <<{root-prefix}/minting/index#,guaranteed by minting>>, and
+deposits must have predictable lifetimes.
+
+A detailed treatment of signer fees can be found in
+<<{root-prefix}/signer-fees/index#,their own section>>.
+
+
+== Terms
+
+:term-length: 6 months
+
+Fixed-term deposits mean signer fees can easily be calculated per deposit. A
+standard term of {term-length} means depositors can budget for fees, and
+signers will know how long their bonds will be inaccessible.
+
+Depositors that don't need future access to their deposit might prefer to pass
+the costs of the system to eventual redeemers. These depositors can opt to
+receive a non-fungible deposit beneficiary token which pays a fee rebate at the
+deposit's redemption. The rebate mechanism is <<{root-prefix}/minting/index#,
+explained further in the discussion around minting>>.

docs/deposits/index.adoc

@@ -28,15 +28,12 @@ image::{root-prefix}img/generated/initiate-deposit.png[]
 
 == Deposit request
 
-The starting point for acquiring TBTC is generating a _deposit request_. This is
-a transaction to a smart contract on tBTC's host chain that informs the tBTC
-system that the sender account is interested in creating a TBTC deposit. The
-transaction is a signal that the sender is interested in a signing group to back
-a wallet that will receive bitcoin from a wallet the sender controls, in order
-to produce TBTC. Because signing groups are not free to create, deposit requests
-include a small bond in the host chain's native token to cover the creation of
-the signing group. The bond is refunded when a successful deposit is made to the
-generated wallet.
+The starting point for acquiring TBTC is generating a _deposit request_. This
+request is a transaction to a smart contract on tBTC's host chain.
+signals that the sender requires a signing group backed wallet Because signing
+groups are not free to create, deposit requests include a small bond in the host
+chain's native token to cover the creation of the signing group. The bond is
+refunded when a successful deposit is made to the generated wallet.
 
 === Signer selection
 
@@ -63,7 +60,7 @@ key generation protocol that results in a public ECDSA key for the group, which
 is used to produce a wallet address that is then published to the host chain.
 This completes the signer selection phase.
 
-==== Bonding
+==== Signer bonding
 
 Before the selected members of a signing group can perform distributed key
 generation, they must agree to become members of the signing group by putting up
@@ -92,13 +89,13 @@ The distributed key generation protocol should result in three properties:
    signed version of a given transaction to be performed on behalf of the
    signing group.
 
-=== Proof of deposit
+== Making a deposit
 
 Once the tBTC system has a wallet address available for a given deposit request,
-the _depositor_ can issue a Bitcoin transaction sending BTC from a wallet they
-control to the wallet address for the signing group. Once the transaction has
-been sufficiently confirmed by the Bitcoin chain, the depositor has to issue a
-transaction to the host chain proving that the _Deposit_ has been funded.
+the _depositor_ can broadcast a Bitcoin transaction sending BTC from a wallet
+they control to the wallet address for the signing group. Once the transaction
+has been sufficiently confirmed by the Bitcoin chain, the depositor has to issue
+a transaction to the host chain proving that the _Deposit_ has been funded.
 
 The only link between the Bitcoin chain and the host chain is the tBTC system,
 which runs as a set of smart contracts on the host chain. As such, the Bitcoin
@@ -110,83 +107,15 @@ proof is not received within a given timeout window, the signing group will
 disband and the system will seize the bond's value, making it available to the
 signing group members to reclaim.
 
-To prove deposit, the depositor constructs a transaction for the host chain
-that provides proof that the transaction was accepted on the Bitcoin chain
-and has had sufficient work built on top of the block that included the deposit
-transaction. These proofs are verified by an on-chain simple payment
-verification (SPV) system. A more complete discussion of cross-chain SPV
-systems and their security properties is included in the appendix.
-
 // TODO What is "sufficient"? Defined as a system property? Dynamic?
 
-==== Overpayment & Underpayment
-
-The system is designed to function with a predefined lot size for all _Deposits_
-which is given as a system parameter. **Depositors should send the exact lot
-amount of BTC in the funding transaction, or expect loss of funds.**
-Since it is not possible for the system to force users into sending any specific
-amount, the system must gracefully handle overpayment and underpayment. The
-primary  impact of overpayment and underpayment is on the `Deposit`'s collateralization
-ratio. We treat overpayment and underpayment as faulty depositor behavior, 
-and pass on the associated costs to the depositor.
-
-### Underpayment
-
-Allowing underpayment on `Deposit` would result in over-bonded signers. To
-prevent this, the system will not accept funding proofs of less than the lot
-size (`1.0 BTC` initially). This implies that the a user that sends less than `1.0
-BTC` in the funding transaction does not receive any TBTC, and forfeits the BTC 
-locked in the funding transactions to the Signers. The Signers can unlock and
-evenly split the funds in the transaction after the _Deposit_ is resolved on-chain (see
-<<Multiple UTXOs>> for a full discussion).
-
-### Overpayment
-
-Overpayment, in contrast, would result in under-bonded signers. When overfunding
-occurs, the system accepts the funding proof, but mints TBTC according to the 
-regular lot size. 
-
-In an efficient market, this _Deposit_ will be immediately redeemed,
-as the redeemer expects to take the overfunded amount as arbitrage. 
-
-Example: A user providing a funding proof for `1.6 BTC` in a system
-with lot size of `1 BTC` mints only `1.0 TBTC`. Any user that burns `1.0 TBTC`
-is able to claim the `1.6 TBTC` _Deposit_.
-
-A depositor should notice this and immediately try to burn their TBTC to reclaim
-the amount. If not, the depositor effectively forfeits the overfunded value to
-other participants.
-
-==== Multiple UTXOs
-
-A faulty depositor may send multiple UTXOs to the signer group address. This
-may be the result of human or software error. Unfortunately, returning the
-funds to the depositor would impose require significant on-chain complexity and
-gas fees, as each UTXO would need to be proven via SPV, and a signature on it
-explicitly authorized. In addition, we would have to develop mechanisms to
-economically compel signers to sign each transaction despite the fact that the
-total value of the UTXOs is not known. As such, the system accepts only the
-first UTXO greater than the deposit lot size. All other BTC sent to the signing
-group is forfeit. Therefore it is imperative that depositors send only a single
-UTXO of an appropriate size.
-
-As a particularly damaging example, consider a naive human depositor. If she
-mistakenly sends half the lot size in one transaction and half in another, both
-UTXOs would be forfeit. **This represents a serious pitfall for depositors that
-must be carefully addressed by the user interface since significant loss of
-funds can occur.**
-
-The signers, while they may collude to move the BTC to other UTXOs, may not do
-so during the life of the _Deposit_ contract as the production of the required
-signature would constitute ECDSA fraud. As such, the most likely outcome is
-that the signers collectively wait to take personal possession of that BTC
-until the _Deposit_ concludes naturally. This allows the signers to make
-regular signing fees and keep the additional UTXOs without penalty.
-
-
 === Light Relays
 
-// TODO: crosslink to appendix SPV section
+To prove a deposit, the depositor submits proof the transaction has been
+confirmed and accumulated work on the Bitcoin chain. The proof is
+verified by an on-chain simple payment verification (SPV) contract on the host
+chain. A more complete overview of cross-chain SPV systems and their security
+properties <<{root-prefix}/appendix/spv/index#,is included in the appendix>>.
 
 Light relays are a new variant of on-chain SPV developed for tBTC. They seek to
 take advantage of the compact and efficient stateless SPV proofs while relaying
@@ -234,29 +163,6 @@ requests and fund multiple deposits. This allows each deposit to be backed by
 a different signing group, both simplifying the bonding of signing groups and
 improving the resilience of the system to signing group failure.
 
-== Deposit Economics
-
-:signer-fee-withheld: 0.005 TBTC
-
-Once a deposit has been made and funded, the corresponding TBTC is minted.
-Minted TBTC is immediately issued to the funder, who is now the beneficiary of
-a funded _Deposit_. To prevent denial of service attacks {signer-fee-withheld}
-is withheld on minting. This will be returned to the beneficiary when the
-_Deposit_ is closed. This ensures that DoS attacks based on repeatedly creating
-signing groups (e.g. Attacker creates signing group, locks 1 BTC, creates 1
-TBTC via a Deposit, trades for 1 BTC in an exchange and repeats the Deposit
-process multiple times) have high economic cost.
-
-Beneficary status is transferable (in Ethereum this is implemented as an
-ERC721-compatible non-fungible token). When the _Deposit_ resolves, the
-withheld TBTC (or equivalent value) will be returned to the current beneficiary
-along with a small additional payment. In this way the beneficiary NFT
-functions as a zero-coupon bond issued by the signing group upon funding. If
-the signing group performs its obligations, the beneficiary will eventually
-receive the bond payout. It can be expected that there will be service providers
-willing to trade {signer-fee-witheld} TBTC for 1 TBTC-coupon-bond along with
-some fee, for providing liquidity to holders of the otherwise illiquid for the
-duration of a Deposit coupon.
-
-Signer fees are described in more detail in
-<<../custodial-fees/index#,their own section>>.
+include::./mistakes.adoc[leveloffset=+1]
+
+include::./economics.adoc[leveloffset=+1]

docs/deposits/mistakes.adoc

@@ -0,0 +1,56 @@
+= Mistakes making a deposit
+
+The system is designed to function with a predefined lot size for all _Deposits_
+which is given as a system parameter. **Depositors should send the exact lot
+amount of BTC in the funding transaction, or expect loss of funds.**
+Since it is not possible for the system to force users into sending any specific
+amount, the system must gracefully handle overpayment and underpayment. The
+primary  impact of overpayment and underpayment is on the ``Deposit``'s collateralization
+ratio. We treat overpayment and underpayment as faulty depositor behavior,
+and pass on the associated costs to the depositor.
+
+== Underpayment
+
+Allowing underpayment on `Deposit` would result in over-bonded signers. To
+prevent this, the system will not accept funding proofs of less than the lot
+size (`1.0 BTC` initially). This implies that the a user that sends less than `1.0
+BTC` in the funding transaction does not receive any TBTC, and forfeits the BTC
+locked in the funding transactions to the Signers. The Signers can unlock and
+evenly split the funds in the transaction after the _Deposit_ is resolved on-chain (see
+<<Multiple UTXOs>> for a full discussion).
+
+== Overpayment
+
+Overpayment, in contrast, would result in under-bonded signers. When overfunding
+occurs, the system accepts the funding proof, but mints TBTC according to the
+regular lot size.
+
+In an efficient market, this _Deposit_ will be immediately redeemed,
+as the redeemer expects to take the overfunded amount as arbitrage.
+
+Example: A user providing a funding proof for `1.6 BTC` in a system
+with lot size of `1 BTC` mints only `1.0 TBTC`. Any user that burns `1.0 TBTC`
+is able to claim the `1.6 BTC` _Deposit_.
+
+A depositor should notice this and immediately try to burn their TBTC to reclaim
+the amount. If not, the depositor effectively forfeits the overfunded value to
+other participants.
+
+== Multiple UTXOs
+
+A faulty depositor may send multiple UTXOs to the signer group address. This
+may be the result of human or software error. Unfortunately, returning the
+funds to the depositor would impose significant on-chain complexity and gas
+fees, as each UTXO would need to be proven via SPV, and a signature on it
+explicitly authorized. In addition, we would have to develop mechanisms to
+economically compel signers to sign each transaction despite the fact that the
+total value of the UTXOs is not known. As such, the system accepts only the
+first UTXO greater than the deposit lot size. All other BTC sent to the signing
+group is forfeit. Therefore it is imperative that depositors send only a single
+UTXO of an appropriate size.
+
+As a particularly damaging example, consider a naive human depositor. If she
+mistakenly sends half the lot size in one transaction and half in another, both
+UTXOs would be forfeit. **This represents a serious pitfall for depositors that
+must be carefully addressed by the user interface since significant loss of
+funds can occur.**