Spec Updates (all in one)

docs/appendix/disbursal/index.adoc

@@ -0,0 +1,72 @@
+ifndef::tbtc[]
+:root-prefix: ../../
+include::../../constants.adoc[]
+endif::tbtc[]
+
+= Redemption Payment and Disbursal Scenarios
+
+:pre-term-redemption-footnote: footnote:pre-term-redemption[Pre-term deposits \
+can only be redeemed by the TDT owner.]
+
+For a BTC lot size of {btc-lot-size} corresponding to {tbtc-lot-size} and signer
+fee of {signer-fee} ({signer-fee-basis-points} basis points), the following
+table describes the amounts disbursed to each party at redemption time for
+pre- and at-term deposits, depending on who holds the TDT and FRT, and who
+initiates redemption. Three possible parties exist in the table—A, B, and
+C—and the listed scenarios cover situations where the same party holds the
+two tokens and initiates redemption, different parties have each role, and
+possibilities in between.
+
+[#deposit-payment-flow,%header,cols="1,1,1,1,1,1a"]
+.Deposit payment flow
+|===
+| Deposit state | TDT holder | FRT holder | Redeemer | Repayment Amount | Disbursal Amounts
+
+| Pre-term      | A          | -          | A        | {signer-fee}
+  | A:: {btc-lot-size}
+    signers:: {signer-fee}
+| Pre-term      | A          | -          | B        | _N/A_{pre-term-redemption-footnote} | _N/A_
+| Pre-term      | A          | A          | A        | 0
+  | A:: {btc-lot-size}
+    signers:: {signer-fee}
+| Pre-term      | A          | B          | A        | {signer-fee}
+  | A:: {btc-lot-size}
+    signers:: {signer-fee}
+    B:: {signer-fee} (escrowed)
+| Pre-term      | A          | B          | C        | _N/A_ | _N/A_
+
+| At-term       | A          | -          | A        | {signer-fee}
+  | A:: {btc-lot-size}
+    signers:: {signer-fee}
+| At-term       | A          | -          | B        | {tbtc-lot-size}
+  | B:: {btc-lot-size}
+    signers:: {signer-fee}
+    A:: {tbtc-lot-size-less-signer-fee}
+| At-term       | A          | A          | A        | 0
+  | A:: {btc-lot-size}
+    signers:: {signer-fee} (escrowed)
+| At-term       | A          | B          | A        | 0
+  | A:: {btc-lot-size}
+    signers:: {signer-fee} (escrowed)
+    B:: 0
+| At-term       | A          | B          | B        | {tbtc-lot-size}
+  | B:: {btc-lot-size}
+    signers:: {signer-fee} (escrowed)
+    A:: {tbtc-lot-size}
+| At-term       | A          | A          | B        | {tbtc-lot-size}
+  | B:: {btc-lot-size}
+    signers:: {signer-fee} (escrowed)
+    A:: {tbtc-lot-size-less-signer-fee}
+| At-term       | A          | B          | C        | {tbtc-lot-size}
+  | C:: {btc-lot-size}
+    signers:: {signer-fee} (escrowed)
+    B:: 0
+    A:: {tbtc-lot-size}
+|===
+
+Note that all of these scenarios can be conceptualized as the TDT holder
+always receiving the 1 TBTC used to redeem the deposit; when the TDT holder
+redeems their own deposit, the TBTC they receive would be from themselves, so
+they simply owe less. Similarly, the FRT holder always receives escrow back
+when redeeming pre-term, so in cases where the redeemer holds the FRT, the
+redeemer simply does not owe the signer fee at redemption time.

docs/appendix/glossary/tbtc.adoc

@@ -20,5 +20,5 @@ Signing bond:: The bond signers put up before a deposit is funded. This bond
 ensures signers will be punished for fraud or poor uptime.
 
 Reserved TBTC:: The amount of TBTC that can't be drawn from a new deposit.
-Reserving TBTC on deposit funding sets aside funds to pay signers' custodial
-fees through the deposit term.
+Reserving TBTC on deposit funding sets aside funds to pay signing fee through
+the deposit term.

docs/appendix/index.adoc

@@ -6,6 +6,8 @@ ifndef::tbtc[]
 toc::[]
 endif::tbtc[]
 
+include::./disbursal/index.adoc[leveloffset=+1]
+
 include::./states/index.adoc[leveloffset=+1]
 
 include::./spv/index.adoc[leveloffset=+2]

docs/appendix/states/failure.adoc

@@ -7,7 +7,7 @@ ifndef::tbtc[toc::[]]
 
 == Overview
 
-Fraud and abort  processes handle custody failures. This includes punishing
+Fraud and abort  processes handle signer failures. This includes punishing
 signers and starting the bond liquidation process. These transitions can be
 invoked from almost any _Deposit_ state, as faults may occur during any other
 flow. Once fault has been proven, the bonds are put up for auction to the

docs/constants.adoc

@@ -0,0 +1,32 @@
+// Constants used throughout the spec. Generally (though not always) correspond
+// to tBTC system constants.
+
+// Overcollateralization constants.
+:extra-collateral: 50%
+:total-collateral: 150%
+
+// Liquidation constants.
+:pre-liquidation-period: 6 hours
+:pre-liquidation-threshold: 125%
+:liquidation-threshold: 110%
+:liquidation-auction-start-percent: 80%
+
+// Deposit terms.
+:term-length: 6 months
+
+// Lots and signer fees.
+:tbtc-lot-size: 1 TBTC
+:btc-lot-size: 1 BTC
+:signer-fee: 0.005 TBTC
+:signer-fee-basis-points: 50
+:tbtc-lot-size-less-signer-fee: 0.995 TBTC
+:beneficiary-bond-payment: 0.0005 TBTC
+
+// Redemption and BTC fees and fee increases.
+:redemption-proof-timeout: 12 hours
+:signature-timeout: 3 hours
+// TODO: fill in real numbers for these two
+:min-redemption-btc-fee: 2345 satoshi
+:min-redemption-btc-feerate: ~20 satoshi/vbyte
+:fee-increase-timer: 4 hours
+:fee-increase-timer-times-two: 8 hours

docs/deposits/economics.adoc

@@ -1,6 +1,16 @@
+:toc: macro
+
 = Deposit economics
 
-Signers aren't altruists -- they're paid for the service they provide.
+ifndef::tbtc[]
+toc::[]
+
+:root-prefix: ../
+include::../constants.adoc[]
+endif::tbtc[]
+
+
+Signers aren't altruists—they are 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
@@ -10,16 +20,22 @@ A detailed treatment of signer fees can be found in
 <<{root-prefix}/signer-fees/index#,their own section>>.
 
 
+[[term]]
 == 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>>.
+Depositors that don't need future access to their deposit might prefer to
+pass the costs of the system to eventual redeemers and/or want denomination
+beyond the BTC lot size or fungibility. These depositors can opt to receive a
+non-fungible Fee Rebate Token which pays a fee rebate at the deposit's
+redemption by another user. The rebate mechanism is
+<<{root-prefix}/minting/index#, explained further in the discussion around
+minting>>.
+
+At the end of the deposit term, the deposit can be redeemed by anyone including
+the signers themselves, with signer fees owed by the deposit owner. This
+mechanism is discussed in more detail in
+<<{root-prefix}/redemption/index#at-term,the section on redemption>>.

docs/deposits/index.adoc

@@ -6,26 +6,31 @@ ifndef::tbtc[]
 toc::[]
 
 :root-prefix: ../
+include::../constants.adoc[]
 endif::tbtc[]
 
 == Overview
 
 tBTC provides a mechanism for creating a token, TBTC, on a non-Bitcoin _host
-chain_, that is 1-to-1 backed by bitcoin. Parties interested in minting TBTC
-<<Deposit Request,request>> that the tBTC system provide them with a Bitcoin
-wallet address. The system selects a set of _signers_, which are tasked with
+chain_ (in tBTC v1, this host chain is Ethereum), that is 1-to-1 backed by
+bitcoin. Parties interested in minting TBTC <<request,request>> that
+the tBTC system provide them with a Bitcoin wallet address. The system
+<<signer-selection,selects a set of _signers_>>, which are tasked with
 generating a private/public keypair and furnishing it to the system. The
 interested party then becomes a _depositor_ by sending bitcoin to the wallet
 (the amount of required bitcoin is discussed separately in the section on
-<<Lots,lots>>). The bitcoin that is sent to the wallet is in two parts: one is
-eligible for 1-to-1 minting into TBTC, while the other is reserved as incentive
-and collateral for the wallet signers.
+<<Lots,lots>>). The deposit cannot be maintained for free, as deposits require
+signers to put up an ETH bond to guarantee good behavior (see the section on
+<<Deposit economics>>). To cover these costs, the deposit is paid for by
+signing fees that cover a set _term_ of deposit redemption exclusivity for
+the deposit owner, discussed separately in the section on <<term,terms>>.
 
 Each of these steps is shown in the diagram below and discussed in subsequent
 sections.
 
 image::{root-prefix}img/generated/initiate-deposit.png[]
 
+[[request]]
 == Deposit request
 
 The starting point for acquiring TBTC is generating a _deposit request_. This
@@ -35,6 +40,7 @@ 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]]
 === Signer selection
 
 Once the deposit request is received, the signing group is created by randomly
@@ -64,51 +70,63 @@ This completes the signer selection phase.
 
 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
-a bond in the native token of the host chain. This bond is used to penalize the
-members of the signing group if an unauthorized piece of data is signed by the
-signing group once distributed key generation is complete; it is also used to
-penalize a given member if the distributed key generation fails due to an
-attributed misbehavior of that member.
+a bond (the _signer bond_) in the native token of the host chain. This bond
+is used to penalize the members of the signing group if an unauthorized piece
+of data is signed by the signing group once distributed key generation is
+complete; it is also used to penalize a given member if the distributed key
+generation fails due to an attributed misbehavior of that member, if the signing
+group fails to produce a signature for the system when requested, and to
+bring the system into balance in cases of undercollateralization.
 
 Bonding is described in more detail in
 <<{root-prefix}bonding/index#bonding,its own section>>.
 
 ==== Distributed key generation
 
+:threshold-signature: footnote:[Threshold signatures allow a group of N \
+signers to generate a public key and a set of private key shares, with which \
+a subset M of the signers can create signatures on behalf of the group. For \
+tBTC v1, signing groups are 3-of-3, meaning they are groups of 3 signers that \
+require all 3 signers to collaborate to create signatures on behalf of the \
+group.]
 Some small notes about the distributed key generation a signing group undergoes.
 The distributed key generation protocol should result in three properties:
 
 1. The signing group as a whole should have an _ECDSA public key_, which will be
    shared on the host chain and will correspond to the Bitcoin wallet
    owned by that signing group.
 2. Each member of the signing group should have a _threshold ECDSA secret key
-   share_, which can be used to create a _threshold ECDSA signature share_ for
-   any transactions involving the signing group's wallet.
+   share_{threshold-signature}, which can be used to create a
+   _threshold ECDSA signature share_ for any transactions involving the
+   signing group's wallet.
 3. Each member of the signing group should be able to combine a threshold number
    of signature shares from itself and other members of the group to produce a
    signed version of a given transaction to be performed on behalf of the
    signing group.
 
 == Making a deposit
 
+:sufficient-confirmations: footnote:[For tBTC v1, sufficient confirmations means 6 confirmations. Confirmation numbers \
+that are variable, particularly in response to volume of deposits that are \
+opened, are part of the discussion for tBTC v2.]
+
 Once the tBTC system has a wallet address available for a given deposit request,
 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.
+has been sufficiently confirmed{sufficient-confirmations} 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
 transaction issued by the depositor has to be proven to the tBTC system before
 the tBTC system allows the depositor to behave as if they have successfully
-deposited their BTC into the custodial wallet. When a deposit proof is accepted
+deposited their BTC into the signer wallet. When a deposit proof is accepted
 by the system, the deposit bond is refunded to the depositor. If a deposit
 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.
 
-// TODO What is "sufficient"? Defined as a system property? Dynamic?
-
 === Light Relays
 
 To prove a deposit, the depositor submits proof the transaction has been
@@ -123,7 +141,7 @@ enough information to provide each stateless proof with some recency guarantee.
 We achieve this by taking advantage of the difficulty adjustment feature of
 Bitcoin's protocol. Bitcoin adjusts difficulty every 2016 blocks, based on
 timestamps of the first and last block in that period (due to an off-by-one
-error in the Satoshi client, one interblock period is exlcuded from the
+error in the Satoshi client, one interblock period is excluded from the
 difficulty calculation). The change is deterministic and within some tolerance
 may be set by the miner of the last block.
 
@@ -152,16 +170,14 @@ proofs.
 
 == Lots
 
-:lot-size: 1.0
-
 Deposits will be managed in fixed-size _lots_. Each deposit therefore will
-have to be of the same amount: {lot-size} BTC. Thus, a depositor submitting
+have to be of the same amount: {btc-lot-size}. Thus, a depositor submitting
 their <<Proof of deposit,proof of deposit>> must prove that they deposited
-{lot-size} into the deposit's signing group wallet. If a depositor wants to
+{btc-lot-size} into the deposit's signing group wallet. If a depositor wants to
 deposit more than the lot size, they will need to create multiple deposit
 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.
+improving the resilience of the system to signing group failure, malicious or not.
 
 include::./mistakes.adoc[leveloffset=+1]
 

docs/deposits/mistakes.adoc

@@ -4,10 +4,11 @@ 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.
+amount, ideally the the system would 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
 

docs/failure/index.adoc

@@ -2,8 +2,13 @@
 
 = Handling Failure
 
-ifndef::tbtc[toc::[]]
+ifndef::tbtc[]
+toc::[]
 
+:root-prefix: ../
+endif::tbtc[]
+
+[[abort]]
 == Aborts / Liveness
 
 The system requires that critical actions like funding and redemption occur
@@ -72,7 +77,7 @@ The signers custody a single Bitcoin UTXO. If that UTXO moves, except at the
 direction of the system then the signers have failed to perform their duties.
 SPV Proofs of Bitcoin inclusion (as documented here) suffice to prove signer
 fault. If the coins move, and its movement was not specifically requested by
-the system, then the signers have failed in their custodial duties. Compared to
+the system, then the signers have failed in their signing duties. Compared to
 ECDSA Fraud proofs, SPV Fraud Proofs are more expensive to verify and have a
 weaker security model. The system expects SPV Fraud Proofs only rarely, and
 subjects them to much higher work requirements than SPV funding and redemption