Create first draft of Chapter 15: Setting up a Bitcoin Regtest #15

bvolpato · 2017-12-12T19:58:37Z

This is a draft of Chapter 15, will be looking into improving and completing it

bvolpato · 2017-12-12T20:39:32Z

I am willing to go as far as you want on this topic. I covered the basics of Regtest startup, mining and testing the created blockchain.
I'm going to review and see if I didn't leave anything important out and improve the wording, but let me know if I'm missing any other subject that you wanted to be covered here.

bvolpato · 2017-12-12T20:44:30Z

I also suggest switching orders of 15.2 and 15.3. To test, first you'll have to mine the blocks and generate some output.
Let me know if you have a reason to keep as is.

ChristopherA · 2017-12-12T22:43:06Z

@shannona You OK with switching 15.2 and 15.3?

shannona

Overall, this looks like a great start. Thanks so much for taking this on! My main comment is that I'd like to see more results. That's been a very important part of the tutorials: (1) show the commands; (2) explain the commands; (3) shows the results; (4) explain the results. For your new chapter here, the main thing that can be added are the results: not just what the command output, but also what other things we can see now that it's output, such as transactions and blocks. With that in hand, we can deliver a very thorough explanation of how this all works.

shannona · 2017-12-13T21:47:26Z

15_1_Building_the_Regtest.md

+
+To start your Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command:
+```
+$ bitcoind -regtest -daemon


I'd like to see some comments on how this interrelates with a normal setup, which users will presumably have from other parts of the tutorial. Should they start from scratch with a newly create VM? Can they run this in parallel with their existing setups? Can they run it parallel, but not simultaneously?

shannona · 2017-12-13T21:48:16Z

15_1_Building_the_Regtest.md

+
+Regtest wallets and block chain state (chainstate) are saved in the regtest subdirectory of the Bitcoin configuration directory. 
+If you want to start a brand new Blockchain using the Regtest mode, all you have to do is delete the `regtest` folder and restart the Bitcoind.
+


Always great to show the command line examples, so here it might be nice to see what that subdirectory looks like. I think I did the same thing in the early sections.

shannona · 2017-12-13T21:48:57Z

15_2_Testing_with_Regtest.md

+After [mining blocks](15_3_Mining_with_Regtest.md) and getting the rewards, you can verify the balance on your wallet:
+```
+$ bitcoin-cli -regtest getbalance
+```


We'd like to show the results too.

shannona · 2017-12-13T21:49:38Z

15_2_Testing_with_Regtest.md

+For example, to create a transaction and include into a block:
+```
+$ bitcoin-cli -regtest sendtoaddress [address] 10.0
+```


shannona · 2017-12-13T21:50:00Z

15_2_Testing_with_Regtest.md

+```
+
+And after it, if your application requires 6 confirmations, you can mine additional 6 blocks into your Regtest chain:
+```


It'd be nice to have a little bit additional explanation on this, though that might prove unnecessary once you flip the chapters around.

shannona · 2017-12-13T21:50:35Z

15_2_Testing_with_Regtest.md

+And after it, if your application requires 6 confirmations, you can mine additional 6 blocks into your Regtest chain:
+```
+$ bitcoin-cli -regtest generate 6
+```


Results?
If that command doesn't give results, maybe show the transaction with the confirmations.

shannona · 2017-12-13T21:51:20Z

15_3_Mining_with_Regtest.md

+You can generate/mine new blocks using the RPC method `generate`. This method is only available in the Regtest mode, using the following command:
+```
+$ bitcoin-cli -regtest generate 101
+```


Results? Or otherwise show that we now have 101 blocks.

shannona · 2017-12-13T21:51:56Z

15_3_Mining_with_Regtest.md

+```
+
+This command will generate 101 blocks using a special RPC which is only available in regtest mode. This takes less than a second on a generic PC. 
+Because this is a new block chain using Bitcoin’s default rules, the first blocks pay a block reward of 50 bitcoins. 


It'd be nice to show how that reward shows up too.

shannona · 2017-12-13T21:55:02Z

@brunocvcunha, definitely feel free to flip the chapters around. My experience in writing this was that no chapter outline ever survived first contact with the writing. It's just meant to be a starting position, so expansions or contractions of topics or changing of ordering are all perfectly fine. (Looking at your sections, that's exactly what I would have done.)

bvolpato · 2017-12-13T22:07:51Z

Got it! Thanks for the detailed review.

I'll check all of your points and push the changes later today.

ChristopherA · 2017-12-13T23:29:29Z

@kallewoof had suggested that in the regtest section the testing tool https://www.npmjs.com/package/bitcointest might be useful. Thoughts?

bvolpato · 2017-12-14T03:23:09Z

I think it's an interesting topic to cover, allowing you to simulate edge cases that might happen in the real world.

Maybe show the configuration, an example, and link to their repo at https://github.com/dgarage/bitcointest?

bvolpato · 2017-12-14T03:29:58Z

@shannona I improved & reviewed the chapter considering your reviews.

Let me know if something is still off.

bvolpato · 2017-12-14T06:10:31Z

Added some details about the bitcointest: https://github.com/ChristopherA/Learning-Bitcoin-from-the-Command-Line/pull/15/files#diff-6ce8301eb7b94e92c2df2c93d324daccR81

kallewoof

Generally some technicalities, and general use of "the Regtest [Mode]" which I find unusual and recommend changing.

kallewoof · 2017-12-14T08:36:05Z

15_3_Testing_with_Regtest.md

+```
+```javascript
+const { BitcoinNet, BitcoinGraph } = require('bitcointest');
+net = new BitcoinNet('/usr/local/bin', '/tmp/bitcointest/', 22001, 22002);


Why not const net and const graph here? They don't seem to be modified and if they were, it should be let net / let graph.

kallewoof · 2017-12-14T08:37:50Z

15_1_Building_the_Regtest.md

@@ -0,0 +1,31 @@
+# 15.1: Building the Regtest


I'm not sure what this title is insinuating. You don't build regtest, and the use of the is weird.

kallewoof · 2017-12-14T08:38:09Z

15_0_Setting_Up_a_Bitcoin_Regtest.md

+
+## Table of Contents
+
+  * [Section One: Building the Regtest](15_1_Building_the_Regtest.md)


See other comment -- I think this title needs to be changed.

kallewoof · 2017-12-14T08:39:15Z

15_1_Building_the_Regtest.md

+If you want to start a brand new Blockchain using the Regtest mode, all you have to do is delete the `regtest` folder and restart the Bitcoind:
+```
+$ rm -rf regtest
+```


Typically you would just make a new datadir and use the -datadir option.
E.g.

$ mkdir d $ bitcoind -regtest -datadir=d $ alias bcli="bitcoin-cli -regtest -datadir=d" $ bcli [...]

kallewoof · 2017-12-14T08:39:58Z

15_1_Building_the_Regtest.md

+
+## What's Next?
+
+After starting your bitcoind in the Regtest mode, you can now use Regtest-specific RPC commands to [generate/mine blocks in your private chain](15_2_Mining_with_Regtest.md).


Consistent use of the Regtest [Mode] -- I suggest nixing the -- i.e. running bitcoind on regtest

kallewoof · 2017-12-14T08:40:38Z

15_2_Mining_with_Regtest.md

+> **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.
+
+This document explains how to generate (i.e. mine) blocks using a Regtest (Regression Test) blockchain.
+To generate the Genesis block and the next blocks on a new blockchain requires very minimal proof-of-work, due to the low difficulty and that it follows the Testnet rules.


The genesis block is not generated, it's hard coded into bitcoin for all networks (main, test, and regtest).

kallewoof · 2017-12-14T08:41:05Z

15_2_Mining_with_Regtest.md

+
+## Generating blocks
+
+You can generate/mine new blocks using the RPC method `generate`. This method is only available in the Regtest mode, using the following command:


generate is technically available in all modes (I would call them networks not modes, actually), but it's not very likely to yield any blocks on mainnet or testnet due to the high difficulty. (Anecdote: I tried for a couple months awhile back. Alas, my balance remained 0)

kallewoof · 2017-12-14T08:41:31Z

15_2_Mining_with_Regtest.md

+The output is the block hash of every block generated (in our example, 101 hashes).
+
+
+This command will generate 101 blocks using a special RPC which is only available in regtest mode. This takes less than a second on a generic PC.


See above comment.

kallewoof · 2017-12-14T08:42:32Z

15_2_Mining_with_Regtest.md

+
+This command will generate 101 blocks using a special RPC which is only available in regtest mode. This takes less than a second on a generic PC.
+Because this is a new block chain using Bitcoin’s default rules, the first blocks pay a block reward of 50 bitcoins.
+Unlike mainnet, in regtest mode only the first 150 blocks pay a reward of 50 bitcoins.


Should mention that the subsidy halving period for regtest is 150 blocks, so after 150 blocks you receive half of the prior amount (i.e. 25), and after another 150 (=300) you receive 12.5, and so on. It looks right now as if you stop receiving reward after 150 blocks.

kallewoof · 2017-12-14T08:42:58Z

15_2_Mining_with_Regtest.md

+
+## What's Next?
+
+After starting your bitcoind in the Regtest mode and generating the first blocks, you have balance in your address to spend and [test the Regtest blockchain](15_3_Testing_with_Regtest.md).


After starting bitcoind on regtest and[...]

bvolpato · 2017-12-14T17:14:40Z

Thanks for your input!

I think I was really overusing the word "mode", but "Regtest mode" is a common expression to describe the Bitcoin Core started with -regtest: https://bitcoin.org/en/glossary/regression-test-mode.

How does it look now?

ChristopherA

I'm going to accept this pull request as is, but we probably need to come up with some header for chapters that talks about their level of review and completeness. For instance, this version is sufficiently informative, but I think still needs to be fitted into the overall pedagogy not only of "What is regtest" but also "why regtest", "what it is regtest actually good for", and "how learning regtest help you understand X".

kallewoof

Several cases of the Regtest or the Mainnet, uppercase Blockchain, use of private instead of local, and some other issues. This PR was merged so maybe make a new PR to address this?

kallewoof · 2017-12-28T04:15:14Z

15_0_Setting_Up_a_Bitcoin_Regtest.md

@@ -0,0 +1,18 @@
+# Chapter 15: Setting Up a Bitcoin Regtest


Remove a in a Bitcoin Regtest.

kallewoof · 2017-12-28T04:15:45Z

15_0_Setting_Up_a_Bitcoin_Regtest.md

@@ -0,0 +1,18 @@
+# Chapter 15: Setting Up a Bitcoin Regtest
+
+While developing Bitcoin applications, you might want to use your applications isolated from any public Blockchain such as the Mainnet or the Testnet.


Remove the from Mainnet / Testnet and don't capitalize. (such as mainnet or testnet). This applies to the remainder of this PR (i.e. below 'the Regtest', etc).

kallewoof · 2017-12-28T04:16:46Z

15_0_Setting_Up_a_Bitcoin_Regtest.md

+# Chapter 15: Setting Up a Bitcoin Regtest
+
+While developing Bitcoin applications, you might want to use your applications isolated from any public Blockchain such as the Mainnet or the Testnet.
+You can create a Blockchain from scratch using the Regtest, with one main advantage over Testnet: you choose when to create new blocks, so you have complete control over the environment.


Decapitalize Blockchain (-> blockchain). This applies to the remainder of this PR.

kallewoof · 2017-12-28T04:19:40Z

15_0_Setting_Up_a_Bitcoin_Regtest.md

+
+## Table of Contents
+
+  * [Section One: Starting the Regtest](15_1_Starting_the_Regtest.md)


This name is confusing and misleading. I suggest Starting a Node on the Regtest Network

kallewoof · 2017-12-28T04:21:06Z

15_1_Starting_the_Regtest.md

+
+> **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.
+
+This document explains how to build a Regtest (Regression Test) by hand to be able to develop new applications without the need to interact with other peers and blocks.


how to set up a bitcoin node locally using the regtest (regression test) network in order to develop new applications[...]

kallewoof · 2017-12-28T04:26:03Z

15_2_Mining_with_Regtest.md

+
+## Generating blocks
+
+You can generate/mine new blocks using the RPC method `generate`. It only makes sense to use this method on regtest, due to the high difficulty it's very unlikely that it will yield to new blocks in the mainnet or testnet:


that it will yield any new blocks on mainnet or testnet

kallewoof · 2017-12-28T04:26:39Z

15_2_Mining_with_Regtest.md

+The output is the block hash of every block generated (in our example, 101 hashes).
+
+
+This command will generate 101 blocks using a special RPC to generate the blocks on your regtest network. Running this command only makes sense on the regtest, if you try to run on the mainnet or testnet, it is very unlikely that it will be able to yield any block. On regtest, this takes less than a second on a generic PC.


First sentence is awkward. This paragraph repeats what is written above mostly.

kallewoof · 2017-12-28T04:26:55Z

15_2_Mining_with_Regtest.md

+
+
+This command will generate 101 blocks using a special RPC to generate the blocks on your regtest network. Running this command only makes sense on the regtest, if you try to run on the mainnet or testnet, it is very unlikely that it will be able to yield any block. On regtest, this takes less than a second on a generic PC.
+Because this is a new block chain using Bitcoin’s default rules, the first blocks pay a block reward of 50 bitcoins.


blockchain (one word)

kallewoof · 2017-12-28T04:28:35Z

15_3_Testing_with_Regtest.md

+## Validating the Regtest
+Now you should be able to use this balance for any type of interaction with the private Blockchain, such as sending Bitcoin transactions according to [Chapter 4]((04_0_Sending_Bitcoin_Transactions.md)) in this guide. The only difference is that you need to use the flag `-regtest` when running the `bitcoin-cli` in order for the request to be sent to the Regtest Bitcoin daemon.
+
+It is important to note that for your transactions to complete, you will have to generate/mine new blocks so that the transactions can be included into them.


Maybe use for your transactions to confirm here -- I think the user should know what that means at this point (Chapter 15).

kallewoof · 2017-12-28T04:29:36Z

15_3_Testing_with_Regtest.md

+## Testing with Regtest
+
+When you are on regtest, you are able to simulate edge cases and attacks that might happen in the real world, such  as Double Spend.
+We are going to use the package [bitcointest by dgarage](https://github.com/dgarage/bitcointest) to simulate a transaction from one wallet to another, but you can check [their guide](https://www.npmjs.com/package/bitcointest) for more specific attack simulations, such as Double Spend.


bitcointest by Digital Garage

bvolpato force-pushed the master branch from 88e12a4 to 06e8988 Compare December 12, 2017 20:21

Create first draft of Chapter 15

23423b7

bvolpato force-pushed the master branch from 06e8988 to 23423b7 Compare December 12, 2017 20:22

bvolpato changed the title ~~Create 15.1: Building the Regtest~~ Create first draft of Chapter 15: Setting up a Bitcoin Regtest Dec 12, 2017

bvolpato added 5 commits December 12, 2017 12:25

Add Chapter 15 anchors

6f23fd6

First version of 15.3: Mining the Regtest

0c1b5a8

Update 15.1 to have anchor to other topics

0bdaeb5

small fix

dfc7c96

Improve 15.2 and anchors to the other documents

39b80e5

bvolpato added 7 commits December 12, 2017 12:48

fix word

a262cb5

Word fix

9551441

Words fix

1e195d8

Fix "What's Next?" title to conform with the repo

0c27f80

Flag -regtest is needed when using the bitcoin-cli

1ef4324

Resetting the Regtest Blockchain

643d78f

Add example of sendtoaddress + confirm the tx

262dc4b

shannona self-requested a review December 13, 2017 21:45

shannona requested changes Dec 13, 2017

View reviewed changes

bvolpato added 5 commits December 13, 2017 14:21

Chapter 15 improvements

34886ff

Chapter 15 improvements

c5cc9d7

Improve Chapter 15 - Regtest

ecc3a6e

Add chapters

10b56c7

Improvements

422484e

What's next on 15.2 Mining

37a755b

Add bitcointest

d875019

Use javascript lang on the snippet

6715a51

kallewoof reviewed Dec 14, 2017

View reviewed changes

Improvements

111be64

shannona approved these changes Dec 14, 2017

View reviewed changes

ChristopherA approved these changes Dec 14, 2017

View reviewed changes

ChristopherA merged commit 5363a6c into BlockchainCommons:master Dec 14, 2017

kallewoof reviewed Dec 28, 2017

View reviewed changes

shannona mentioned this pull request Dec 14, 2022

Uncomplicate btcblock alias and fix 301 error #593

Merged


		Regtest wallets and block chain state (chainstate) are saved in the regtest subdirectory of the Bitcoin configuration directory.
		If you want to start a brand new Blockchain using the Regtest mode, all you have to do is delete the `regtest` folder and restart the Bitcoind.


		## Table of Contents

		* [Section One: Building the Regtest](15_1_Building_the_Regtest.md)


		## What's Next?

		After starting your bitcoind in the Regtest mode, you can now use Regtest-specific RPC commands to [generate/mine blocks in your private chain](15_2_Mining_with_Regtest.md).


		## Generating blocks

		You can generate/mine new blocks using the RPC method `generate`. This method is only available in the Regtest mode, using the following command:

		The output is the block hash of every block generated (in our example, 101 hashes).


		This command will generate 101 blocks using a special RPC which is only available in regtest mode. This takes less than a second on a generic PC.

		@@ -0,0 +1,18 @@
		# Chapter 15: Setting Up a Bitcoin Regtest

		While developing Bitcoin applications, you might want to use your applications isolated from any public Blockchain such as the Mainnet or the Testnet.


		## Table of Contents

		* [Section One: Starting the Regtest](15_1_Starting_the_Regtest.md)


		> NOTE: This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.

		This document explains how to build a Regtest (Regression Test) by hand to be able to develop new applications without the need to interact with other peers and blocks.



		This command will generate 101 blocks using a special RPC to generate the blocks on your regtest network. Running this command only makes sense on the regtest, if you try to run on the mainnet or testnet, it is very unlikely that it will be able to yield any block. On regtest, this takes less than a second on a generic PC.
		Because this is a new block chain using Bitcoin’s default rules, the first blocks pay a block reward of 50 bitcoins.

Uh oh!

Create first draft of Chapter 15: Setting up a Bitcoin Regtest #15

Create first draft of Chapter 15: Setting up a Bitcoin Regtest #15

Uh oh!

Conversation

bvolpato commented Dec 12, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bvolpato commented Dec 12, 2017

Uh oh!

bvolpato commented Dec 12, 2017

Uh oh!

ChristopherA commented Dec 12, 2017

Uh oh!

shannona left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shannona commented Dec 13, 2017

Uh oh!

bvolpato commented Dec 13, 2017

Uh oh!

ChristopherA commented Dec 13, 2017

Uh oh!

bvolpato commented Dec 14, 2017

Uh oh!

bvolpato commented Dec 14, 2017

Uh oh!

bvolpato commented Dec 14, 2017

Uh oh!

kallewoof left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kallewoof Dec 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kallewoof Dec 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bvolpato commented Dec 14, 2017

Uh oh!

ChristopherA left a comment

Choose a reason for hiding this comment

Uh oh!

kallewoof left a comment

Choose a reason for hiding this comment

Uh oh!

bvolpato commented Dec 12, 2017 •

edited

Loading

kallewoof Dec 14, 2017 •

edited

Loading

kallewoof Dec 14, 2017 •

edited

Loading