Add Rationale section

bip-0197.mediawiki

@@ -6,7 +6,7 @@
           Tony Cai <[email protected]>
           Atomic Loans team <[email protected]>
   Comments-Summary: No comments yet.
-  Comments-URI: TBD
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0197
   Status: Draft
   Type: Standards Track
   Created: 2019-03-19
@@ -20,7 +20,7 @@ This BIP describes a script for generalized debt agreement contract based on Has
 
 ==Summary==
 
-A Hashed Time-Locked Collateral Contract (HTLCC) consists of two scripts that permit a designated party (the "borrower") to lock funds on the Bitcoin chain for a specified amount of time as collateral in a debt agreement where the loan principal is denominated in a currency on another blockchain (eg. Ethereum). We denote the blockchain on which the loan principal is issued the principal blockchain.
+A Hashed Time-Locked Collateral Contract (HTLCC) consists of two scripts that permit a designated party (the "borrower") to lock funds on the Bitcoin chain for a specified amount of time as collateral in a debt agreement where the loan principal is denominated in a currency on another blockchain. We denote the blockchain on which the loan principal is issued the principal blockchain.
 
 The purpose of each script is to enable the creation of a debt agreement between two parties (the "borrower" and the "lender"), where the collateral is locked in a P2SH, and can only be spent once the borrower repays the principal and interest in the debt agreement on the principal blockchain. In the case that the borrower does not repay, the borrower or lender can opt for liquidation of the collateral, which will involve the atomic swapping of collateral for the loan currency. In the case that at least one of the two parties don't opt for liquidation, then each party will be entitled to a percentage of the collateral, decided when the funds are initially locked in the P2SH.
 
@@ -60,7 +60,7 @@ The Seizable Collateral script takes the following form:
 
 ===Interaction===
 
-* Alice (the "borrower") and Bob (the "lender") exchange public keys as well as two secret hashes A1, A2 created by Alice and three hashes B1, B2, B3 created by Bob. They then mutually agree upon a timeout threshold for the Loan Period, Liquidation Period, and Seizure Period. Alice constructs the script and P2SH address for the Refundable Collateral Contract and Seizable Collateral Contract. Bob constructs the script for the blockchain on which the loan principal will be issued - the principal blockchain (eg. in the event the loan agreement involves collateralizing Bitcoin for Dai, this would be the Ethereum blockchain).
+* Alice (the "borrower") and Bob (the "lender") exchange public keys as well as two secret hashes A1, A2 created by Alice and three hashes B1, B2, B3 created by Bob. They then mutually agree upon a timeout threshold for the Loan Period, Liquidation Period, and Seizure Period. Alice constructs the script and P2SH address for the Refundable Collateral Contract and Seizable Collateral Contract. Bob constructs the script for the blockchain on which the loan principal will be issued - the principal blockchain.
 
 * Bob sends loan principal funds to the loan script on the principal blockchain
 
@@ -119,7 +119,7 @@ bidding expiration num: timestamp that determines the amount of time allocated t
 seizure expiration num: timestamp that determines the amount of time during which the lender can seize funds within the Seizable Collateral P2SH, after which the borrower can refund their corresponding amount of the collateral they are entitled to (ie. either just the funds within the Refundable Collateral P2SH, or both the Refundable Collateral and Seizable Collateral in the event where the lender failed to seize).
 
 ===Approve Period===
-During this time, the lender deploys the HTLPC on the principal blockchain (Ethereum version specified here: https://github.com/ethereum/EIPs/pull/1850). Following this, the borrower locks their collateral on the Bitcoin blockchain in a HTLCC. The lender then either reveals secretB1 to signify that they are satisfied with the collateral, and the borrower can withdraw the loan by revealing secretA1. If the lender is not satisfied with the collateral locked by the borrower, the lender can refunds their loan amount by revealing secretB2, which will subsequently allow the borrower to refund the collateral amount they deposited.
+During this time, the lender deploys the HTLPC on the principal blockchain. Following this, the borrower locks their collateral on the Bitcoin blockchain in a HTLCC. The lender then either reveals secretB1 to signify that they are satisfied with the collateral, and the borrower can withdraw the loan by revealing secretA1. If the lender is not satisfied with the collateral locked by the borrower, the lender can refunds their loan amount by revealing secretB2, which will subsequently allow the borrower to refund the collateral amount they deposited.
 
 ===Loan Period===
 Once the borrower has withdrawn the loan amount, the Loan Period begins. Once the Loan Period is finished, the borrower is expected to repay the loan. If they do, the lender can then accept the repayment by revealing secretB2, enabling the borrower to refund their collateral amount. In the case that the borrower defaults or does not repay the full principal plus interest amount, the lender can choose to not accept the loan repayment, and the parties can opt for liquidation of the collateral in the Bidding Period.
@@ -133,6 +133,16 @@ In the case that either the lender or borrower don’t accept the bid, the lende
 ===Refund Period===
 In the case that the lender does not seize the collateral locked in the Seizable Collateral script, then the borrower can refund the funds locked in the Refundable Collateral script.
 
+==Rationale==
+
+The rational for the following script checking the length of secrets pushed to the stack that are used with OP_SHA256 in the following script
+
+  OP_SIZE <secret b2 length> OP_EQUALVERIFY
+
+is to ensure that the secret size is exactly a certain number of bytes long.
+
+This is especially important when this script is used alongside the HTLPC on other chains like Ethereum where the sha256 opcode only takes up 32 bytes and disregards the rest, there is a need to ensure that the length on the Bitcoin side is 32 bytes.
+
 ==Backwards Compatibility==
 
 As this is a new standard for collateralized debt, there is no need for backward compatibility. Once this is accepted as a standard there are certain aspects of the contract that can be modified while still retaining backwards compatibility, such as removing the need to verify the size of the hash if being used with two blockchains with the same maximum block size, which would be backward compatible with the current script.