Add comments

rosetta-cli-conf/testnet/bitcoin.ros

@@ -53,7 +53,8 @@ transfer(10){
     max_fee_amount = "1200";
     send_buffer = {{dust_amount}} + {{max_fee_amount}};
 
-    // reserved_amount is max_fee_amount + min_utxo size x 2
+    // We look for a coin of value >= the reserved_amount to create
+    // a transfer with change (reserved_amount is max_fee_amount + dust_amount x 2).
     reserved_amount = "2400";
     sender = find_balance({
       "minimum_balance":{
@@ -63,22 +64,32 @@ transfer(10){
       "require_coin": true
     });
 
-    available_amount = {{sender.balance.value}} - {{send_buffer}};
+    // The amount we send to the recipient is a random value
+    // between the dust_amount and the value of the entire coin (minus
+    // the amount reserved for fee payment and covering the dust minimum
+    // of the change UTXO).
+    receivable_amount = {{sender.balance.value}} - {{send_buffer}};
     recipient_amount = random_number({
       "minimum": {{dust_amount}},
-      "maximum": {{available_amount}}
+      "maximum": {{receivable_amount}}
     });
     print_message({
       "recipient_amount":{{recipient_amount}}
     });
 
-    total_change_amount = {{sender.balance.value}} - {{recipient_amount}};
-    change_amount = {{total_change_amount}} - {{max_fee_amount}};
+    // The change amount is what we aren't sending to the recipient
+    // minus the maximum fee. Don't worry, we will adjust this
+    // amount to avoid overpaying the fee after the dry run
+    // completes.
+    raw_change_amount = {{sender.balance.value}} - {{recipient_amount}};
+    change_amount = {{raw_change_amount}} - {{max_fee_amount}};
     print_message({
       "change_amount":{{change_amount}}
     });
 
-    sender_amount = 0 - {{sender.balance.value}};
+    // The last thing we need to do before creating the transaction
+    // is to find a recipient with a *types.AccountIdentifier that
+    // is not equal to the sender.
     recipient = find_balance({
       "not_account_identifier":[{{sender.account_identifier}}],
       "not_coins":[{{sender.coin}}],
@@ -89,6 +100,8 @@ transfer(10){
       "create_limit": 100,
       "create_probability": 50
     });
+
+    sender_amount = 0 - {{sender.balance.value}};
     transfer_dry_run.confirmation_depth = "1";
     transfer_dry_run.dry_run = true;
     transfer_dry_run.operations = [
@@ -114,12 +127,16 @@ transfer(10){
     ];
   },
   transfer{
+    // The suggested_fee is returned in the /construction/metadata
+    // response and saved to transfer_dry_run.suggested_fee.
     suggested_fee = find_currency_amount({
       "currency":{{currency}},
       "amounts":{{transfer_dry_run.suggested_fee}}
     });
-    change_amount = {{total_change_amount}} - {{suggested_fee.value}};
-    change_minus_dust = {{change_amount}} - {{dust_amount}};
+
+    // We can access the variables of other scenarios, so we don't
+    // need to recalculate raw_change_amount.
+    change_amount = {{raw_change_amount}} - {{suggested_fee.value}};
     transfer.network = {{transfer_dry_run.network}};
     transfer.confirmation_depth = {{transfer_dry_run.confirmation_depth}};
     transfer.operations = [
@@ -151,9 +168,9 @@ return_funds(10){
     transfer_dry_run.network = {"network":"Testnet3", "blockchain":"Bitcoin"};
     currency = {"symbol":"tBTC", "decimals":8};
 
+    // We look for a sender that is able to pay the 
+    // max_fee_amount + min_utxo size (reserved_amount is max_fee_amount + min_utxo size).
     max_fee_amount = "1200";
-
-    // reserved_amount is max_fee_amount + min_utxo size
     reserved_amount = "1800";
     sender = find_balance({
       "minimum_balance":{
@@ -163,13 +180,18 @@ return_funds(10){
       "require_coin": true
     });
 
+    // We send the maximum amount available to the recipient. Don't worry
+    // we will modify this after the dry run to make sure we don't overpay.
     recipient_amount = {{sender.balance.value}} - {{max_fee_amount}};
     print_message({
       "recipient_amount":{{recipient_amount}}
     });
 
+    // We load the recipient address from an ENV.
+    recipient_address = load_env("RECIPIENT");
+    recipient = {"address": {{recipient_address}}};
+
     sender_amount = 0 - {{sender.balance.value}};
-    recipient = {"address": "mkHS9ne12qx9pS9VojpwU5xtRd4T7X7ZUt"};
     transfer_dry_run.confirmation_depth = "1";
     transfer_dry_run.dry_run = true;
     transfer_dry_run.operations = [
@@ -189,14 +211,20 @@ return_funds(10){
     ];
   },
   transfer{
+    // The suggested_fee is returned in the /construction/metadata
+    // response and saved to transfer_dry_run.suggested_fee.
     suggested_fee = find_currency_amount({
       "currency":{{currency}},
       "amounts":{{transfer_dry_run.suggested_fee}}
     });
+
+    // We calculate the recipient_amount using the new suggested_fee
+    // and assert that it is above the minimum UTXO size.
     recipient_amount = {{sender.balance.value}} - {{suggested_fee.value}};
     dust_amount = "600";
     recipient_minus_dust = {{recipient_amount}} - {{dust_amount}};
     assert({{recipient_minus_dust}});
+
     transfer.network = {{transfer_dry_run.network}};
     transfer.confirmation_depth = {{transfer_dry_run.confirmation_depth}};
     transfer.operations = [