Merge pull request #561 from keep-network/doc-drift

Doc Drift: Fix a variety of doc issues, primarily around cross-references

docs/appendix/sighash/index.adoc

@@ -1,36 +1,34 @@
 :toc: macro
 
+[[sighash]]
 = Standardized Sighash Construction
 
 ifndef::tbtc[]
 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
 signer's intent with respect to them. Specifically, BIP143 sighash commits to
 the following (not in this order):
 
 1. One or All inputs
-1. None, One, or All outputs
-1. The specific prevout this signature witnesses
-1. The pubkey script or redeem script code locking that prevout
-1. The value of the prevout this signature witnesses
-1. The sequence of the input spending that prevout
-1. The transaction version
-1. The transaction locktime
+2. none, one, or all outputs
+3. The specific prevout this signature witnesses
+4. The pubkey script or redeem script code locking that prevout
+5. The value of the prevout this signature witnesses
+6. The sequence of the input spending that prevout
+7. The transaction version
+8. The transaction locktime
 
 These are committed to via the double-sha256 of an ordered bytestring. This
 digest is signed, and can be reproduced by anyone inspecting the transaction
@@ -68,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

@@ -1,25 +1,24 @@
 :toc: macro
 
+[[spv]]
 = Simplified Payment Verification (SPV): A Primer
 
 ifndef::tbtc[]
 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
 
@@ -28,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
@@ -82,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
@@ -125,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/bonding/index.adoc

@@ -1,12 +1,13 @@
 :toc: macro
 
-[#bonding]
+[[bonding]]
 = Bonding
 
 ifndef::tbtc[]
 toc::[]
 
-:root-prefix: ../
+:relfileprefix: ../
+:root-prefix: {relfileprefix}
 include::../constants.adoc[]
 endif::tbtc[]
 
@@ -105,11 +106,11 @@ If the value of ETH crosses a security threshold, open _Deposit_ s will enter
 
 === BTC price drop relative to ETH
 
-Since <<Signer 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.
+Since <<signer-fees/index.adoc#signer-fees,signer 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 earning fees on their assets.
 
 Signers SHOULD buy TBTC from the markets in anticipation of such overly
 overcollateralized Deposits and they SHOULD use it to redeem these positions,
@@ -186,10 +187,10 @@ Forced liquidation should be rare, as rational signers will redeem deposits
 before liquidation becomes necessary. However, the possibility of extreme
 punishment via liquidation is necessary to prevent dishonest behavior from
 signers. Liquidation may occur because because signers
-<<{root-prefix}/failure/index#abort, didn't produce a valid signature in
+<<failure/index.adoc#abort, didn't produce a valid signature in
 response to 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 <<{root-prefix}/failure/index#Fraud,
+the courtesy call, or because the signers <<failure/index.adoc#fraud,
 produced a fraudulent signature>>{fraudulent-signature}.
 
 The primary goal of the liquidation process is to make the deposit owner
@@ -205,11 +206,11 @@ responsible for reporting the misbehavior (for fraud) or between the signers and
 the account that triggered liquidation (for collateralization issues).
 
 To compensate the deposit owner, the contract starts a falling-price auction
-with the seized signer bond. It offers {auction-start-percent} of the signer
-bond in exchange for the outstanding TBTC amount. The amount of bond on sale
-increases over time until someone chooses to purchase it, or the auction
-reaches 100% of the bond. The auction will remain open until a buyer is
-found.
+with the seized signer bond. It offers {liquidation-auction-start-percent} of
+the signer bond in exchange for the outstanding TBTC amount. The amount of
+bond on sale increases over time until someone chooses to purchase it, or the
+auction reaches 100% of the bond. The auction will remain open until a buyer
+is found.
 
 TBTC received during this process is sent to the deposit owner; if the owner is
 the vending machine, the vending machine MUST burn the TBTC to maintain the
@@ -228,7 +229,7 @@ design is for them to decide—it might be split up, stolen by a signing
 majority, or lost permanently.
 
 NOTE: If a Fee Rebate Token (FRT) has been given out to mint TBTC for a
-deposit that is liquidated (see <<{root-prefix}/minting/index,the Minting
+deposit that is liquidated (see <<minting/index.adoc#minting,the Minting
 section>>), the FRT owner is _not_ refunded
 during liquidation. The fees that were escrowed in exchange for the FRT are
 instead used to compensate the signers, and the FRT is no longer eligible for
@@ -245,7 +246,7 @@ the Deposit (1 BTC / 75 ETH)
 3. Liquidation is triggered and the 75 ETH is seized to buy back TBTC.
 
 4. The _Deposit_ must use the 75 ETH to purchase 1 TBTC. In an attempt to get a
-discount, it auctions {auction-start-percent} of its ETH reserves.
+discount, it auctions {liquidation-auction-start-percent} of its ETH reserves.
 
 5. An arbitrageur burns 1 TBTC at 90% of the auction and obtains 67.5 ETH. The
 liquidation of the _Deposit_ is now over.

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/economics.adoc

@@ -3,21 +3,20 @@
 = Deposit economics
 
 ifndef::tbtc[]
-toc::[]
-
-:root-prefix: ../
+:relfileprefix: ../
+:root-prefix: {relfileprefix}
 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
+fees must be <<minting/index.adoc#minting,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>>.
+<<signer-fees/index.adoc#signer-fees,their own section>>.
 
 
 [[term]]
@@ -31,11 +30,10 @@ 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>>.
+redemption by another user. The rebate mechanism is <<minting/index.adoc#minting,
+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>>.
+<<redemption/index.adoc#redemption,the section on redemption>>.

docs/deposits/index.adoc

@@ -5,7 +5,8 @@
 ifndef::tbtc[]
 toc::[]
 
-:root-prefix: ../
+:relfileprefix: ../
+:root-prefix: {relfileprefix}
 include::../constants.adoc[]
 endif::tbtc[]
 
@@ -79,7 +80,7 @@ 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>>.
+<<bonding/index#bonding,its own section>>.
 
 ==== Distributed key generation
 
@@ -104,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 \
@@ -133,7 +135,7 @@ 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>>.
+properties <<appendix/spv/index#spv,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