From fb93a35153340c22535536d98deaccf7e9158082 Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sat, 4 Apr 2020 19:42:01 -0400 Subject: [PATCH 01/13] Fix some incorrect constant references in docs --- docs/bonding/index.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/bonding/index.adoc b/docs/bonding/index.adoc index 6bbedb2a1..ff7bb1a88 100644 --- a/docs/bonding/index.adoc +++ b/docs/bonding/index.adoc @@ -205,11 +205,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 @@ -245,7 +245,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. From 5d8113c039bddd8234782170424dc6ee782e06a6 Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sat, 4 Apr 2020 19:55:20 -0400 Subject: [PATCH 02/13] Update price feed info to reflect direct BTCETH feed --- docs/price-feed/index.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/price-feed/index.adoc b/docs/price-feed/index.adoc index 9e05b3029..d7139c2dd 100644 --- a/docs/price-feed/index.adoc +++ b/docs/price-feed/index.adoc @@ -7,10 +7,10 @@ ifndef::tbtc[toc::[]] The price feed is an integral part of the system, ensuring sufficient -collateral backs all tBTC signers. For tBTC v1, the feed will be built on the -https://developer.makerdao.com/feeds/[USD price feeds from MakerDAO], currently -operated by MakerDAO. MakerDAO has both ETHUSD and BTCUSD feeds; these are -combined to make a single ETHBTC price. +collateral backs all tBTC signers. For tBTC v1, the feed will be built on a +BTCETH +https://developer.makerdao.com/feeds/[https://docs.makerdao.com/smart-contract-modules/oracle-module/oracle-security-module-osm-detailed-documentation] +from MakerDAO, currently operated by MakerDAO. The minimal price feed design is specified completely by the interface below: From 7809b83edb088d3c325d640615c5e6656aa7347b Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sat, 4 Apr 2020 20:04:27 -0400 Subject: [PATCH 03/13] Fix a few asciidoctor numbering warnings --- docs/appendix/sighash/index.adoc | 14 +++++++------- docs/signing/index.adoc | 10 +++++----- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/appendix/sighash/index.adoc b/docs/appendix/sighash/index.adoc index bb716e3c5..e5e36851c 100644 --- a/docs/appendix/sighash/index.adoc +++ b/docs/appendix/sighash/index.adoc @@ -24,13 +24,13 @@ 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 diff --git a/docs/signing/index.adoc b/docs/signing/index.adoc index 7ddb442a0..44fb41c50 100644 --- a/docs/signing/index.adoc +++ b/docs/signing/index.adoc @@ -53,10 +53,10 @@ Informally, the participants perform the following actions to sign a message: 1. Produce an additive share of `k * x`, where each participant `i` holds `k_i` and `x_i`. -1. Efficiently calculate `R = g^(1/k)` using Bar-Ilan and Beaver's inversion +2. Efficiently calculate `R = g^(1/k)` using Bar-Ilan and Beaver's inversion trick, without any participant `i` revealing `k_i`, and set `r = R_x`. -1. Each participant calculates their share of the signature: `s_i = m * k_i + r * k_i * x_i`. -1. The threshold signature is the sum of all signatures `s_i`. +3. Each participant calculates their share of the signature: `s_i = m * k_i + r * k_i * x_i`. +4. The threshold signature is the sum of all signatures `s_i`. A more in-depth description of the protocol can be found in Section 4.1 and 4.2 of the paper. @@ -128,10 +128,10 @@ o compute, `g_0` and `g_1` generators of `G_0` and `G_1` respectively. . A signature on `m` is `s_i ＝ Η_0(m)^sk_i` . To aggregate N signatures for the same message from public keys `(pk_1, ..., pk_n)`: 1. Compute: `(t_1, ..., t_n) = H_1(pk_1, ..., pk_n)` - 1. Aggregated signature: `s = s_1^t_1 * ... * s_n^t_n` + 2. Aggregated signature: `s = s_1^t_1 * ... * s_n^t_n` . To verify the aggregated signature against the same public keys: 1. Compute: `(t_1, ..., t_n) = H_1(pk_1, ..., pk_n)` 2. Compute the aggregate public key: `pk = pk_1 ^ t_1 * ... * pk_n ^ t_n` (independent of the message being signed)) - 2. Verify the signature: `e(g_1, s) = e(pk, H_0(m))` (requires 2 pairings + 3. Verify the signature: `e(g_1, s) = e(pk, H_0(m))` (requires 2 pairings since the same message is being signed): From b6ce5f37fed38f153602d854cf858003484e9b9b Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sat, 4 Apr 2020 20:06:09 -0400 Subject: [PATCH 04/13] Stabilize cross-references with relfileprefix Asciidoctor allows relfileprefix to be combined with cross-references that end in .adoc and a proper anchor to correctly resolve both in a same-file and in separate-file compilation passes. Leverage this across the document includes. --- docs/appendix/sighash/index.adoc | 1 + docs/appendix/spv/index.adoc | 1 + docs/bonding/index.adoc | 21 ++++++------ docs/deposits/economics.adoc | 16 ++++----- docs/deposits/index.adoc | 7 ++-- docs/failure/index.adoc | 8 +++-- docs/minting/index.adoc | 18 +++++----- docs/redemption/index.adoc | 59 +++++++++++++++++--------------- docs/signer-fees/index.adoc | 4 +-- 9 files changed, 72 insertions(+), 63 deletions(-) diff --git a/docs/appendix/sighash/index.adoc b/docs/appendix/sighash/index.adoc index e5e36851c..4312a160a 100644 --- a/docs/appendix/sighash/index.adoc +++ b/docs/appendix/sighash/index.adoc @@ -1,5 +1,6 @@ :toc: macro +[[sighash]] = Standardized Sighash Construction ifndef::tbtc[] diff --git a/docs/appendix/spv/index.adoc b/docs/appendix/spv/index.adoc index ec6037823..dfee29b41 100644 --- a/docs/appendix/spv/index.adoc +++ b/docs/appendix/spv/index.adoc @@ -1,5 +1,6 @@ :toc: macro +[[spv]] = Simplified Payment Verification (SPV): A Primer ifndef::tbtc[] diff --git a/docs/bonding/index.adoc b/docs/bonding/index.adoc index ff7bb1a88..508b50206 100644 --- a/docs/bonding/index.adoc +++ b/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 <> 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 <> 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 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 +<>, 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 <>{fraudulent-signature}. The primary goal of the liquidation process is to make the deposit owner @@ -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 <>), 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 diff --git a/docs/deposits/economics.adoc b/docs/deposits/economics.adoc index 0e8f9935b..92cfe2d5c 100644 --- a/docs/deposits/economics.adoc +++ b/docs/deposits/economics.adoc @@ -3,9 +3,8 @@ = Deposit economics ifndef::tbtc[] -toc::[] - -:root-prefix: ../ +:relfileprefix: ../ +:root-prefix: {relfileprefix} include::../constants.adoc[] endif::tbtc[] @@ -13,11 +12,11 @@ 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 <>, and deposits must have predictable lifetimes. A detailed treatment of signer fees can be found in -<<{root-prefix}/signer-fees/index#,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 <>. 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>>. +<>. diff --git a/docs/deposits/index.adoc b/docs/deposits/index.adoc index b59a9e369..2ac067b08 100644 --- a/docs/deposits/index.adoc +++ b/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>>. +<>. ==== Distributed key generation @@ -133,7 +134,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 <>. 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 diff --git a/docs/failure/index.adoc b/docs/failure/index.adoc index a1e4ac1d2..ea35a31e6 100644 --- a/docs/failure/index.adoc +++ b/docs/failure/index.adoc @@ -5,7 +5,8 @@ ifndef::tbtc[] toc::[] -:root-prefix: ../ +:relfileprefix: ../ +:root-prefix: {relfileprefix} endif::tbtc[] [[abort]] @@ -13,13 +14,14 @@ endif::tbtc[] The system requires that critical actions like funding and redemption occur within a fixed time after request. Failure to do so is treated as an "abort." -Where <> indicates proof positive of forbidden behavior, an +Where <> indicates proof positive of forbidden behavior, an abort typically represents a liveness failure from some participant. As such, while aborts are still punished, and may still result in liquidation, they are not punished as severely as fraud. For example, should the signers fail to produce a redemption signature in a timely manner, their bonds are liquidated 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 @@ -29,7 +31,7 @@ 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 <> process. +starting the <> process. ==== ECDSA Fraud Proofs diff --git a/docs/minting/index.adoc b/docs/minting/index.adoc index 9fdcc77e9..75fda32b3 100644 --- a/docs/minting/index.adoc +++ b/docs/minting/index.adoc @@ -1,9 +1,11 @@ +[#minting] = Minting ifndef::tbtc[] toc::[] -:root-prefix: ../ +:relfileprefix: ../ +:root-prefix: {relfileprefix} include::../constants.adoc[] endif::tbtc[] @@ -29,12 +31,12 @@ funded until the deposit term is reached. Once the deposit is fully _qualified_ by submitting sufficient proof of the funding Bitcoin transaction, the holder of the TDT can request redemption, and, after paying any outstanding signing fees, be guaranteed the same UTXO -backing the deposit. The holder of the TDT is also guaranteed compensation -in TBTC via the signing group's bonded collateral in case of fraud or -collateralization issues (see <<{root-prefix}/bonding/index#Liquidation>>), +backing the deposit. The holder of the TDT is also guaranteed compensation in +TBTC via the signing group's bonded collateral in case of fraud or +collateralization issues (see <>), and compensation in TBTC (minus signer fees) if the deposit is redeemed by another account after it reaches term (see the section on -<<{root-prefix}/redemption/index#at-term, at-term redemption>>). +<>). === Implications @@ -125,6 +127,6 @@ provides a straightforward way to transfer it to another account for the cost of Burning all received TBTC allows for maintaining the supply peg not only when deposit ownership is transferred away from the vending machine, but also when the deposits that are still owned by the vending machine are liquidated or -<<{root-prefix}/redemption/index#at-term, redeemed at term>>, since in these -cases deposit owner compensation goes to the vending machine, which burns -that compensation immediately. +<>, since in these cases +deposit owner compensation goes to the vending machine, which burns that +compensation immediately. diff --git a/docs/redemption/index.adoc b/docs/redemption/index.adoc index addf876e9..f7c274baa 100644 --- a/docs/redemption/index.adoc +++ b/docs/redemption/index.adoc @@ -1,11 +1,13 @@ :toc: macro +[[redemption]] = Redemption ifndef::tbtc[] toc::[] -:root-prefix: ../ +:relfileprefix: ../ +:root-prefix: {relfileprefix} include::../constants.adoc[] endif::tbtc[] @@ -18,7 +20,7 @@ redeemable for the BTC held there. The tBTC redemption system aims to provide access to those BTC via a publicly verifiable process. So long as a deposit is maintained in good standing, the holder of the -<<{root-prefix}/minting/index#,non-fungible tBTC Deposit Token>> may +<> may <>, relinquishing their NFT and paying any outstanding signer fees associated with the deposit. @@ -34,20 +36,20 @@ _redemption transaction_ to the Bitcoin blockchain using that signature. [[at-term]] === Deposit Terms and Redemption -As noted in the section on -<<{root-prefix}/deposits/economics/index#term,deposit terms>>, a deposit has -a fixed term. After that term expires, the deposit becomes unlocked from the -deposit owner, so that it can be redeemed by any account (including, notably, -the deposit owner account). At this point, redemption costs exactly 1 TBTC, -with no signer fee due. If the deposit has had the signer fee -<<{root-prefix}/minting/index#vending-machine,escrowed during TBTC minting>>, -the signer fee is paid from escrow and the deposit owner is sent the full 1 -TBTC. If the deposit has no escrowed fee, the owner is sent the 1 TBTC used -to redeem, less the signer fee, which is distributed to the signers. +As noted in the section on <>, a +deposit has a fixed term. After that term expires, the deposit becomes +unlocked from the deposit owner, so that it can be redeemed by any account +(including, notably, the deposit owner account). At this point, redemption +costs exactly 1 TBTC, with no signer fee due. If the deposit has had the +signer fee <>, the signer fee is paid from escrow and the deposit owner is sent +the full 1 TBTC. If the deposit has no escrowed fee, the owner is sent the 1 +TBTC used to redeem, less the signer fee, which is distributed to the +signers. NOTE: For the deposit owner, at term, redemption is free if there are escrowed fees, or costs the signer fee if there are not. This is subtly different from -pre-term redemption, where the deposit owner must pay the signer fee _even if +pre-term redemption, where the deposit owner must pay the signer fee _even if there are escrowed fees_. The additional difference is to the Fee Rebate Token holder, who is rebated the signer fee during pre-term redemptions, but not during at-term redemptions. @@ -66,7 +68,7 @@ includes the following: 2. A public key hash (PKH) for BTC delivery - the 20-byte hash160 of a public key belonging to the requester - for security and privacy, this SHOULD be a new keypair -3. The deposit's <> in TBTC +3. The deposit's <> in TBTC Upon receipt of the _redemption request_, the smart contract escrows the repayment amount, which includes the signer fee, records the receipt of the @@ -79,7 +81,7 @@ produced could be used to both redeem the BTC and submit a signer fraud proof. A fraud proof created this way would appear valid to the host chain smart contract because it no longer has a record of the redemption request. - +[[repayment-amount]] == Repayment Amount :pre-term-redemption-footnote: footnote:pre-term-redemption[Pre-term deposits \ @@ -94,10 +96,11 @@ rebate (in pre-term redemptions). After all the math shakes out, the repayment amount can vary depending on the redeeming party, the TDT holder, the FRT holder, and the deposit's term -state. <<{root-prefix}appendix/disbursal/index#deposit-payment-flow>> lists -the various combinations that are possible, and the corresponding repayment -amounts owed by the redeemer, assuming three possible parties, A, B, and C. -It also lists out the relevant disbursal upon redemption proof. +state. The <> table lists the various combinations that are possible, and +the corresponding repayment amounts owed by the redeemer, assuming three +possible parties, A, B, and C. It also lists out the relevant disbursal upon +redemption proof. == Redemption Transaction Format @@ -115,7 +118,7 @@ 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 the requester. Its timelock and sequence numbers are set to 0 and its version is set to 1. Full documentation of the format and the construction of its -sighash can be found in the <<{root-prefix}appendix/sighash,appendix>>. +sighash can be found in the <>. Because the format is simple and canonical, any observer may use publicly available information to build it. Once a signature has been published, it is @@ -134,25 +137,26 @@ 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 <> for more details). +greater than or equal `UTXO Size - highest allowed fee` (see +<> 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 TDT holder receives the remainder of the repayment amount. As with the repayment amount, the amount each of the parties receives in case of a successful redemption varies depending on the TDT holder, FRT holder, -redeemer, and deposit state. -<<{root-prefix}appendix/disbursal/index#deposit-payment-flow>> lists the -various combinations that are possible, and the corresponding repayment -amounts owed by the redeemer, assuming three possible parties, A, B, and C: +redeemer, and deposit state. The +<> +table lists the various combinations that are possible, and the corresponding +repayment amounts owed by the redeemer, assuming three possible parties, A, +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 <> before being subject +signature, or a <> 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. @@ -165,7 +169,6 @@ request the smart contract can know both the cryptographic validity of the signature and that a signature on that digest was requested as part of a redemption process. - == Allowing for Bitcoin fee adjustment // TODO: link ECDSA fraud proofs diff --git a/docs/signer-fees/index.adoc b/docs/signer-fees/index.adoc index f66513445..5523c74d3 100644 --- a/docs/signer-fees/index.adoc +++ b/docs/signer-fees/index.adoc @@ -1,7 +1,7 @@ -[#signer-fees] +[[signer-fees]] = Signer Fees -Signers put their own <> to assure depositors there will +Signers put their own <> to assure depositors there will be no foul play. The bonds they put down are capital that could otherwise be productive, and need to earn a return relative to the risk to remain competitive with other opportunities. From d97a9fff471b06223277ae625cd2df55291b9461 Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sat, 4 Apr 2020 23:17:36 -0400 Subject: [PATCH 05/13] Tweak spec reasoning around collateral rebalancing --- docs/bonding/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bonding/index.adoc b/docs/bonding/index.adoc index 508b50206..04e7d3a33 100644 --- a/docs/bonding/index.adoc +++ b/docs/bonding/index.adoc @@ -110,7 +110,7 @@ Since <> 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. +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, From d159a45727ce229f9b9af9c39d6942cd0a968b96 Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:49:18 -0400 Subject: [PATCH 06/13] Add a few missing external references to spec --- docs/appendix/sighash/index.adoc | 14 ++++++-------- docs/appendix/spv/index.adoc | 25 +++++++++++++------------ 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/appendix/sighash/index.adoc b/docs/appendix/sighash/index.adoc index 4312a160a..dd8bca768 100644 --- a/docs/appendix/sighash/index.adoc +++ b/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 diff --git a/docs/appendix/spv/index.adoc b/docs/appendix/spv/index.adoc index dfee29b41..222da99b5 100644 --- a/docs/appendix/spv/index.adoc +++ b/docs/appendix/spv/index.adoc @@ -126,18 +126,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 From fdd3dc7afaad5d47afa947c7b4e3252b68920439 Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:52:15 -0400 Subject: [PATCH 07/13] Add a few more cross-references within the spec These were TODOs from some time ago that are still very much worth introducing for clarity. --- docs/appendix/spv/index.adoc | 14 ++++++-------- docs/deposits/index.adoc | 1 + docs/minting/index.adoc | 5 ++--- docs/redemption/index.adoc | 35 ++++++++++++++++------------------- docs/signing/index.adoc | 1 + 5 files changed, 26 insertions(+), 30 deletions(-) diff --git a/docs/appendix/spv/index.adoc b/docs/appendix/spv/index.adoc index 222da99b5..cbcd280db 100644 --- a/docs/appendix/spv/index.adoc +++ b/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 <>, +<>, and +<> 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 diff --git a/docs/deposits/index.adoc b/docs/deposits/index.adoc index 2ac067b08..4a9816cfe 100644 --- a/docs/deposits/index.adoc +++ b/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 \ diff --git a/docs/minting/index.adoc b/docs/minting/index.adoc index 75fda32b3..f8736f7d7 100644 --- a/docs/minting/index.adoc +++ b/docs/minting/index.adoc @@ -80,11 +80,10 @@ 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 +are determined by the accumulated work of their proofs. In tBTC v1, deposits are qualified by a fixed work +requirement proven via an <>, set at 6 blocks of accumulated work. -// TODO link to more details in the appendix? // TODO be specific with the deposit timeout A TDT representing a qualified deposit is also eligible for minting fungible diff --git a/docs/redemption/index.adoc b/docs/redemption/index.adoc index f7c274baa..60cd31cf5 100644 --- a/docs/redemption/index.adoc +++ b/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 @@ -129,16 +127,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 -<> for more details). +A _redemption proof_ is an <> 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 <> 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 +150,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 <> 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, +<> on the +_redemption transaction_ signature hash as requested. They have +{signature-timeout} in which to produce either a signature, or a <> 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 <>, the host chain smart contract managing the deposit has all information necessary to calculate the diff --git a/docs/signing/index.adoc b/docs/signing/index.adoc index 44fb41c50..f2213f2f3 100644 --- a/docs/signing/index.adoc +++ b/docs/signing/index.adoc @@ -1,5 +1,6 @@ :toc: macro +[[signing]] = Signing ifndef::tbtc[toc::[]] From a84c46a755352acea8e231d79c85c77341c5f6ba Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:53:45 -0400 Subject: [PATCH 08/13] Constant for spec's transaction proof difficulty factor These constants, which are all tracked in constants.adoc are important for cross-referencing against mainnet system constants. --- docs/constants.adoc | 3 +++ docs/minting/index.adoc | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/constants.adoc b/docs/constants.adoc index 96ad0885f..42bb0cada 100644 --- a/docs/constants.adoc +++ b/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 diff --git a/docs/minting/index.adoc b/docs/minting/index.adoc index f8736f7d7..943406bbc 100644 --- a/docs/minting/index.adoc +++ b/docs/minting/index.adoc @@ -82,7 +82,7 @@ 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 an <>, set at -6 blocks of accumulated work. +{tx-proof-difficulty-factor} of accumulated work. // TODO be specific with the deposit timeout From 3db67ab8f94ba9e430f7ef768a69f6578b9e79bd Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:54:51 -0400 Subject: [PATCH 09/13] Drop a few older spec TODOs that are no longer valid Some of these no longer make sense since the spec has been restructured, others are left as exercises for the reader. --- docs/appendix/spv/index.adoc | 2 -- docs/minting/index.adoc | 9 --------- docs/redemption/index.adoc | 4 ---- 3 files changed, 15 deletions(-) diff --git a/docs/appendix/spv/index.adoc b/docs/appendix/spv/index.adoc index cbcd280db..e130b0d05 100644 --- a/docs/appendix/spv/index.adoc +++ b/docs/appendix/spv/index.adoc @@ -81,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 diff --git a/docs/minting/index.adoc b/docs/minting/index.adoc index 943406bbc..e9453e4da 100644 --- a/docs/minting/index.adoc +++ b/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 @@ -84,17 +80,12 @@ are determined by the accumulated work of their proofs. In tBTC v1, deposits are requirement proven via an <>, set at {tx-proof-difficulty-factor} of accumulated work. -// TODO be specific with the deposit timeout - 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 diff --git a/docs/redemption/index.adoc b/docs/redemption/index.adoc index 60cd31cf5..786e63e8b 100644 --- a/docs/redemption/index.adoc +++ b/docs/redemption/index.adoc @@ -109,8 +109,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 @@ -168,8 +166,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 From a701d82955232c774d11d18ad0d71dc4d537924e Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:56:19 -0400 Subject: [PATCH 10/13] Remove SPV fraud proofs ECDSA fraud proofs are the only supported types at this point. --- docs/appendix/states/failure.adoc | 29 ---------------------------- docs/appendix/states/redemption.adoc | 10 ---------- docs/failure/index.adoc | 27 +++++--------------------- 3 files changed, 5 insertions(+), 61 deletions(-) diff --git a/docs/appendix/states/failure.adoc b/docs/appendix/states/failure.adoc index 7335e5a5d..aa71a58b4 100644 --- a/docs/appendix/states/failure.adoc +++ b/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 diff --git a/docs/appendix/states/redemption.adoc b/docs/appendix/states/redemption.adoc index 551b7f00d..84990635a 100644 --- a/docs/appendix/states/redemption.adoc +++ b/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* diff --git a/docs/failure/index.adoc b/docs/failure/index.adoc index ea35a31e6..ed07959e9 100644 --- a/docs/failure/index.adoc +++ b/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 <> 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 +<> 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. From 4360c4ff0e0caa6201ba31b2c2c6623cf1ec1e3b Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:57:30 -0400 Subject: [PATCH 11/13] Clarify spec's articulation of valid redemption requesters --- docs/redemption/index.adoc | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/redemption/index.adoc b/docs/redemption/index.adoc index 786e63e8b..d9787bd71 100644 --- a/docs/redemption/index.adoc +++ b/docs/redemption/index.adoc @@ -55,11 +55,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 <>, and has not entered + <>), pre-term, and the + requester holds the corresponding tBTC Deposit Token. +* If the deposit is in good standing and is at or past <>, + irrespective of whether the requester holds the corresponding tBTC Deopsit + Token. +* If the deposit has entered <>, 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}) From 5cc05c439b7b56035f7b2b84c79f7c5281f4fa3d Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:57:54 -0400 Subject: [PATCH 12/13] Drop a future improvement TODO that isn't going into v1 --- docs/redemption/index.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/redemption/index.adoc b/docs/redemption/index.adoc index d9787bd71..a1d4adff4 100644 --- a/docs/redemption/index.adoc +++ b/docs/redemption/index.adoc @@ -29,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 From b535f5f490d3eb81c0a623774546ed81ba4d3c0a Mon Sep 17 00:00:00 2001 From: Antonio Salazar Cardozo Date: Sun, 5 Apr 2020 19:58:10 -0400 Subject: [PATCH 13/13] Fix spec spelling typo --- docs/appendix/spv/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/appendix/spv/index.adoc b/docs/appendix/spv/index.adoc index e130b0d05..286d2f409 100644 --- a/docs/appendix/spv/index.adoc +++ b/docs/appendix/spv/index.adoc @@ -27,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