Merge pull request #564 from keep-network/spec-ial-todos

Spec-ial Todos: Clean up most remaining spec TODOs

docs/appendix/sighash/index.adoc

@@ -8,16 +8,13 @@ toc::[]
 
 endif::tbtc[]
 
-// TODO: many refs
-
 == Overview
 
-// TODO: ref bip143
-
 For signing, Bitcoin transforms transactions using a process known as the
 SignatureHash (sighash) algorithm. The original sighash algorithm had many
 drawbacks and sharp edges. In SegWit scripts, the algorithm was changed to
-follow BIP143 (legacy addresses still use the original algorithm).
+follow https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki[BIP143]
+(legacy addresses still use the original algorithm).
 
 The goal of the sighash algorithm is to commit to selected aspects of the
 transaction in the signed digest. This prevents malleation, and indicates the
@@ -69,10 +66,11 @@ Double SHA256 of the serialization of:
    7. nSequence of the input (4-byte little endian)
    8. hashOutputs (32-byte hash)
    9. nLocktime of the transaction (4-byte little endian)
-  10. sighash type of the signature (4-byte little endian)
+  10. sighash type of the signature (4-byte little endian) <1>
 ```
-
-// TODO: ref my blogpost on sighash types
+<1> See the Summa description of
+    https://medium.com/summa-technology/summa-auction-bitcoin-technical-7344096498f2#2070[different
+    sighash types] for more details on this field.
 
 Because we don't need to use timelocks in our redemption transaction, we forbid
 their usage, allowing us to immediately standardize many elements. We also

docs/appendix/spv/index.adoc

@@ -8,19 +8,17 @@ toc::[]
 
 endif::tbtc[]
 
-// TODO: many refs
-
 == Overview
 
-// TODO: link funding, redemption, and fraud
-
 While a full discussion of SPV proofs is outside the scope of this document, it
 is important to develop a working understanding of their properties, as many
 system-critical processes rely on the SPV security assumptions. SPV proofs are
-used during the funding, redemption, and fraud processes to provide the host
-chain with information about the state of the remote chain. Practically
-speaking, there is no other way that the host chain can learn about the state
-or history of the remote chain.
+used during the <<docs/deposit.adoc#funding,funding>>,
+<<docs/redemption.adoc#redemption,redemption>>, and
+<<docs/failure.adoc#fraud,fraud>> processes to provide the host chain with
+information about the state of the remote chain. Practically speaking, there
+is no other way that the host chain can learn about the state or history of
+the remote chain.
 
 === Objectivity in Proof of Work
 
@@ -29,7 +27,7 @@ called "objectivity." Simply put, proof of work cannot be forged and no outside
 information is needed to check its validity. Without knowing the history of the
 chain, we can examine a Bitcoin block header and determine (probabilistically)
 how many hashes were performed to generate it. The number of hashes used to
-generate a header represents an unforgable cost inherent to that header,
+generate a header represents an unforgeable cost inherent to that header,
 independent of its context or history.
 
 Contrast this with Proof of Stake, in which the cost of generating a header is
@@ -83,8 +81,6 @@ large inherent cost. We argue that the system is economically secure so long as
 the cost of producing a fake proof is high and the value that can be gained by
 producing a fake proof is orders of magnitude less than that cost.
 
-// TODO: does the n add anything? can someone else improve it?
-
 The security of SPV systems also benefits from a built-in assumption of the
 Nakamoto Consensus model: that no attacker has greater than 50% of the
 hashrate. Assuming that is true, no attacker can generate Bitcoin proofs of
@@ -126,18 +122,19 @@ Anyone interested in using the state and history information in the stateless
 SPV proof's information can determine whether to accept or reject it based on
 the proof's quality.
 
-// TODO: cite Summa so much kthx
-// TODO: cite a good source on BTCRelay
-
-Stateless SPVs are relatively recent work. Their compelling advantage is
-size and cost-efficieny. A stateless SPV proof is less than 1KB, all of which
-can be discarded after validation. A relay, on the other hand, stores each
-header on-chain. This means a relay will consume linearly increasing state
-space over time. Maintenance costs are already unsustainably high, as evidenced
-by the failure of BTCRelay in December 2017. Given the already high cost of
-on-chain storage and the likely introduction of state rent in major host chain
-candidates, relying on a stateful relay seems short-sighted. A high-state
-system that is viable today may not be viable in the future.
+Stateless SPVs are relatively recent work, spearheaded by Summa and
+originally described in
+https://medium.com/summa-technology/cross-chain-auction-technical-f16710bfe69f[a
+technical post on the Summa cross-chain auction system]. Their compelling
+advantage is size and cost-efficiency. A stateless SPV proof is less than 1KB,
+all of which can be discarded after validation. A relay, on the other hand,
+stores each header on-chain. This means a relay will consume linearly
+increasing state space over time. Maintenance costs are already unsustainably
+n high, as evidenced by the failure of BTCRelay in December 2017. Given the
+already high cost of on-chain storage and the likely introduction of state
+rent in major host chain candidates, relying on a stateful relay seems
+short-sighted. A high-state system that is viable today may not be viable in
+the future.
 
 We argue that for recent transactions stateless SPV's security is equivalent
 to a relay's. An attacker would have to spend the same number of hashes to

docs/appendix/states/failure.adoc

@@ -129,35 +129,6 @@ fraud-related state transitions in a single document.
 * *to*
 ** `FRAUD_LIQUIDATION_IN_PROGRESS`
 
-=== `provideSPVFraudProof`
-* Anyone provides a SPV proof that the Deposit UTXO has been consumed.
-  If the proof is valid at recent difficulty, it is proof of signer fraud.
-* *access control*
-** anyone
-* *args*
-** `bytes _tx`
-*** the bitcoin tx
-** `bytes _proof`
-*** the bitcoin merkle inclusion proof
-** `uint _index`
-*** the index of the leaf in the merkle tree (1-indexed, sorry)
-** `bytes _headers`
-*** the header chain, earliest first, no padding
-* *reads*
-** `bytes utxoOutpoint`
-*** check if the tx spends the deposit outpoint
-** `uint256 currentDifficulty` -- from light relay
-*** check if the proof difficulty matches bitcoin main chain
-* *from*
-** `AWAITING_SIGNER_SETUP`
-** `AWAITING_BTC_FUNDING_PROOF`
-** `ACTIVE`
-** `AWAITING_WITHDRAWAL_SIGNATURE`
-** `AWAITING_WITHDRAWAL_PROOF`
-** `SIGNER_MARGIN_CALLED`
-* *to*
-** `FRAUD_LIQUIDATION_IN_PROGRESS`
-
 === `notifyRedemptionProofTimeout`
 * Anyone may poke the contract to show that a redemption proof was not
   provided within the permissible time frame. Treated as Abort

docs/appendix/states/redemption.adoc

@@ -178,16 +178,6 @@ funder bond payment.
 * *to*
 ** `LIQUIDATION_IN_PROGRESS`
 
-=== `provideSPVFraudProof` (outbound)
-// TODO: link this elsewhere
-* *access control*
-** anyone
-* *from*
-** `AWAITING_WITHDRAWAL_PROOF`
-** `AWAITING_WITHDRAWAL_SIGNATURE`
-* *to*
-** `LIQUIDATION_IN_PROGRESS`
-
 === `notifyRedemptionProofTimeout` (outbound)
 // TODO: link this elsewhere
 * *access control*

docs/constants.adoc

@@ -14,6 +14,9 @@
 // Deposit terms.
 :term-length: 6 months
 
+// Transaction proof requirements.
+:tx-proof-difficulty-factor: 6 blocks
+
 // Lots and signer fees.
 :tbtc-lot-size: 1 TBTC
 :btc-lot-size: 1 BTC

docs/deposits/index.adoc

@@ -105,6 +105,7 @@ 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.
 
+[[funding]]
 == Making a deposit
 
 :sufficient-confirmations: footnote:[For tBTC v1, sufficient confirmations means 6 confirmations. Confirmation numbers \

docs/failure/index.adoc

@@ -24,14 +24,11 @@ to protect the supply peg, but any remainder is returned to them.
 [[fraud]]
 === Fraud
 
-The system recognizes two redundant fraud proofs: ECDSA, in which the signing
-group produces a signature on a message which was not explicitly requested,
-and SPV, in which the UTXO custodied by the signing group moves for an unknown
-reason. Intuitively, the UTXO should not be able to move without ECDSA fraud,
-however, the system accepts either proof (and may require both proofs in
-certain cases). Each proof its own limitations and security parameters. When
-fraud is detected, the system penalizes the signers by seizing their bonds and
-starting the <<bonding/index.adoc#liquidation,liquidation>> process.
+The system recognizes one type of fraud proof, ECDSA fraud proofs, in which
+the signing group produces a signature on a message which was not explicitly
+requested. When fraud is detected, the system penalizes the signers by
+seizing their bonds and starting the
+<<bonding/index.adoc#liquidation,liquidation>> process.
 
 ==== ECDSA Fraud Proofs
 
@@ -70,17 +67,3 @@ gas limit). Fortunately, Bitcoin's signature hash algorithm uses double-sha256.
 This means that the preimage to the signed digest is always 32 bytes. As such,
 verification costs never scale with transaction size, and even very large
 transactions do not evade ECDSA fraud verification.
-
-==== SPV Fraud Proofs
-
-// TODO: link SPV description
-
-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 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
-proofs.

docs/minting/index.adoc

@@ -59,10 +59,6 @@ There are a few non-obvious implications to a UTXO-specific non-fungible token.
    parties. With this functionality, depositors wouldn't necessarily need to
    monitor the Bitcoin blockchain.
 
-// TODO incentivize this - we want maintainers to be submitting proofs when
-// depositors walk away
-// TODO third-party proof flow in the appendix
-// TODO link to the redemption process
 // TODO can a deposit be challenged if its proof is re-orged? it appears there's
 // no need, but the fungible TBTC vending machine will need to be smart with
 // deposits
@@ -80,22 +76,16 @@ The TBTC vending machine is a contract on the host chain that is responsible
 for minting TBTC.
 
 Any TDT representing a qualified deposit can be exchanged. Qualified deposits
-are determined by the accumulated work of their proofs. In tBTC v1, deposits are
-qualified by a fixed work requirement proven via a stateless SPV proof, set at
-6 blocks of accumulated work.
-
-// TODO link to more details in the appendix?
-// TODO be specific with the deposit timeout
+are determined by the accumulated work of their proofs. In tBTC v1, deposits are qualified by a fixed work
+requirement proven via an <<appendix/spv/index.adoc#spv,SPV proof>>, set at
+{tx-proof-difficulty-factor} of accumulated work.
 
 A TDT representing a qualified deposit is also eligible for minting fungible
 TBTC. Minting TBTC is optional; depositors can stick with their TDTs, which
 will be valid for the lifetime of a maintained deposit. Note that if a holder
 of the TDT wants to make a transaction with a different value than the lot
 size, they must mint TBTC, since the tBTC Deposit Token itself is non fungible.
 
-// TODO NB if a deposit is liquidated, the NFT can stick around and be backed by
-// the liquid token
-
 The holder of a qualified TDT may exchange that TDT for a newly minted
 {tbtc-lot-size}, less the requisite {signer-fee} signing fee. To reflect the
 reduced guarantee of the TDT holder's interest in redeeming the specific

docs/redemption/index.adoc

@@ -11,8 +11,6 @@ toc::[]
 include::../constants.adoc[]
 endif::tbtc[]
 
-// TODO backrefs to signing
-
 == Overview
 
 Deposits represent real Bitcoin unspent transaction outputs ("UTXOs") and are
@@ -31,8 +29,6 @@ signature sending the underlying BTC to the requested address. After a
 signature has been published, any actor may build and submit a
 _redemption transaction_ to the Bitcoin blockchain using that signature.
 
-// TODO: document future upgrade where signers sign singleACP?
-
 [[at-term]]
 === Deposit Terms and Redemption
 
@@ -57,11 +53,23 @@ not during at-term redemptions.
 [[requests]]
 == Redemption Requests
 
-If the deposit is in good standing (has not been accused of fraud, or entered
-signer liquidation), only the holder of the corresponding tBTC Deposit Token
-may request redemption. To do so that person makes a _redemption request_
-transaction to the smart contract on the host chain. The _redemption request_
-includes the following:
+A redemption request can be submitted in a few cases:
+
+* If the deposit is in good standing (has not already been redeemed, has
+  not been accused of <<failure/index.adoc#fraud,fraud>>, and has not entered
+  <<bonding/index.adoc#liquidation,signer liquidation>>), pre-term, and the
+  requester holds the corresponding tBTC Deposit Token.
+* If the deposit is in good standing and is at or past <<at-term,term>>,
+  irrespective of whether the requester holds the corresponding tBTC Deopsit
+  Token.
+* If the deposit has entered <<bonding/index.adoc#pre-liquidation,courtesy
+  call>>, an undercollateralization state designed to allow closing deposits
+  before they become dangerously undercollateralized, irrespective of whether
+  the requester holds the corresponding tBTC Deposit Token.
+
+To request redemption, a requester makes a _redemption request_ transaction
+to the smart contract on the host chain. The _redemption request_ includes
+the following:
 
 1. A Bitcoin transaction fee amount
   - must be >={min-redemption-btc-fee} ({min-redemption-btc-feerate})
@@ -111,8 +119,6 @@ The requester may specify only 2 aspects of the transaction: its fee and its
 destination. All other deposit-specific information (e.g. the outpoint and
 the UTXO size) is known to the deposit contract in advance.
 
-// TODO: Link
-
 The _redemption transaction_ has 1 input (the deposit UTXO) and 1 output (the
 redemption output). It does not have change outputs, or additional inputs, as
 none are needed. It simply transfers the underlying BTC to the sole custody of
@@ -129,16 +135,15 @@ anyone may do so if the signers do not.
 
 == Redemption proof
 
-// TODO: Link SPV proof breakdown
-
-A _redemption proof_ is an SPV proof that a _redemption transaction_ was
-confirmed by the Bitcoin blockchain. Once a request to redeem is confirmed,
-the deposit smart contract expects a _redemption proof_ within
-{redemption-proof-timeout}. To validate a _redemption proof_, the smart
-contract performs normal SPV proof verification, and additionally verifies
-that the recipient matches the requester's public key hash, and the value is
-greater than or equal `UTXO Size - highest allowed fee` (see
-<<Allowing for Bitcoin fee adjustment>> for more details).
+A _redemption proof_ is an <<appendix/spv/index.adoc#spv,SPV proof>> that a
+_redemption transaction_ was confirmed by the Bitcoin blockchain. Once a
+request to redeem is confirmed, the deposit smart contract expects a
+_redemption proof_ within {redemption-proof-timeout}. To validate a
+_redemption proof_, the smart contract performs normal SPV proof
+verification, and additionally verifies that the recipient matches the
+requester's public key hash, and the value is greater than or equal `UTXO
+Size - highest allowed fee` (see <<Allowing for Bitcoin fee adjustment>> for
+more details).
 
 Once redemption proof is confirmed, the signing fee is paid, the FRT holder
 receives their escrowed funds (if the deposit was redeemed pre-term), and the
@@ -153,13 +158,13 @@ B, and C.
 
 == Validating a signature
 
-After the redemption request is sufficiently confirmed, the signers MUST
-produce a signature on the _redemption transaction_ signature hash as
-requested. They have {signature-timeout} in which to produce either a
-signature, or a <<Redemption proof, _redemption proof_>> before being subject
-to penalties. Upon submission of a valid signature a _redemption proof_ is
-still required, but the deadline is extended to {redemption-proof-timeout} in
-total.
+After the redemption request is sufficiently confirmed,
+<<signing/index.adoc#signing,the signers MUST produce a signature>> on the
+_redemption transaction_ signature hash as requested. They have
+{signature-timeout} in which to produce either a signature, or a <<Redemption
+proof, _redemption proof_>> before being subject to penalties. Upon
+submission of a valid signature a _redemption proof_ is still required, but
+the deadline is extended to {redemption-proof-timeout} in total.
 
 As discussed <<Redemption Transaction Format, earlier>>, the host chain smart
 contract managing the deposit has all information necessary to calculate the
@@ -171,8 +176,6 @@ redemption process.
 
 == Allowing for Bitcoin fee adjustment
 
-// TODO: link ECDSA fraud proofs
-
 Because Bitcoin fees are determined by network congestion and other highly
 unpredictable factors, the requester may not select an appropriate fee. Signers
 are punished if no redemption proof is submitted *or* if they sign

docs/signing/index.adoc

@@ -1,5 +1,6 @@
 :toc: macro
 
+[[signing]]
 = Signing
 
 ifndef::tbtc[toc::[]]