From a2368114104d52c39d68fa3e7eec3f233614052c Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 22:49:02 -0800 Subject: [PATCH 01/38] Create 12.7 Accessing Bitcoind with Java --- 12_7_Accessing_Bitcoind_with_Java.md | 131 +++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 133 insertions(+) create mode 100644 12_7_Accessing_Bitcoind_with_Java.md diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md new file mode 100644 index 0000000..b534557 --- /dev/null +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -0,0 +1,131 @@ +# 12.7: Accessing Bitcoind with Java + +> **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning. + +Interacting with the `bitcoind` directly and using command-line `curl` can get simple if you understand how it works, but there's a project [JavaBitcoindRpcClient](https://github.com/Polve/JavaBitcoindRpcClient) that provides the functionality in a Java-API level, making it even easier to interact with your Bitcoin Server. + +## Setup Dependency + +If you use Maven in your Java project, you can include the dependency: +```xml + + wf.bitcoin + JavaBitcoindRpcClient + 0.9.13 + +``` + +Or if you use Gradle: +```groovy +compile 'wf.bitcoin:JavaBitcoindRpcClient:0.9.13' +``` + +### Build Your Connection + +To use `JavaBitcoindRpcClient`, you need to create a `BitcoindRpcClient` instance. The arguments in the URL are username, password, IP address and port. You should know this information from your work with `curl` . As you'll recall, the IP address 127.0.0.1 and port 18332 should be correct for the standard testnet setup described in this documents, while you can extract the user and password from `~/.bitcoin/bitcoin.conf`. + +```java + BitcoindRpcClient rpcClient = new BitcoinJSONRPCClient("http://bitcoinrpc:d8340efbcd34e312044c8431c59c792c@127.0.0.1:18332"); +``` + +> **MAINNET VS TESTNET:** The port would be 8332 for a mainnet setup. + +If `rpcClient` is successfully initialized, you'll be able to send off RPC commands. + +Later, when you're all done with your `bitcoind` connection, you should close it: +``` +rpcClient.stop(); +``` + +### Making your first RPC Call + +In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcloin-cli` or `curl`. + +For example, to execute the `getmininginfo`, you should use the `getMiningInfo()` method: +```java +MiningInfo info = rpcClient.getMiningInfo(); +System.out.println("Mining Information"); +System.out.println("------------------"); +System.out.println("Chain......: " + info.chain()); +System.out.println("Blocks.....: " + info.blocks()); +System.out.println("Difficulty.: " + info.difficulty()); +System.out.println("Hash Power.: " + new BigDecimal(info.networkHashps()).toPlainString()); +``` +The output for this line should be similar to this: +``` +Mining Information +------------------ +Chain......: test +Blocks.....: 1254920 +Difficulty.: 1.0 +Hash Power.: 6585163152453.466796875 +``` + +### Creating an Address + +You can create a new address attaching a specific label to it, as well as dump the private key for a specific address: +```java + String address = rpcClient.getNewAddress("Learning-Bitcoin-from-the-Command-Line"); + System.out.println("New Address: " + address); + + String privKey = rpcClient.dumpPrivKey(address); + System.out.println("Priv Key: " + privKey); +``` +Output: +``` +New Address: mpsFtZ8qTJPRGZy1gaaUw37fHeUSPLkzzs +Priv Key: cTy2AnmAALsHokYzJzTdsUBSqBtypmWfmSNYgG6qQH43euUZgqic +``` + + + +### Sending Transactions + +You can easily send a transaction using the method `sendToAddress()`. + +```java +String sendToAddress = rpcClient.sendToAddress("mgnNsZj6tPzpd7JwTTidUKnGoDTkcucLT5", 1); +System.out.println("Send: " + sendToAddress); +``` +This program will output a transaction id, for example: +``` +a2d2f629d6666ca6e440169a322850cd9d133f637f7a02a02a0a7477bc5687d4 +``` + +In case you want to adjust the transaction fee, you can use the `setTxFee` method before sending the output: + +```java +rpcClient.setTxFee(new BigDecimal(0.001).setScale(3, BigDecimal.ROUND_DOWN)); +``` + + +### Listening to Transactions or Blocks + +You may want to write applications that keep listening the Blockchain, and execute a specific code when something happens, such as a transaction that involves an address in your wallet, or even the generation of a new block in the network. +To do that, `JavaBitcoindRpcClient` provides support to `BitcoinAcceptor`, where you can attach listeners in the network. + +Example: +```java + BitcoinAcceptor acceptor = new BitcoinAcceptor(rpcClient, blockHash, 6, new BitcoinPaymentListener() { + + @Override + public void transaction(Transaction tx) { + System.out.println("Transaction: " + tx); + + } + + @Override + public void block(String block) { + System.out.println("Block: " + block); + + } + }); + acceptor.run(); +``` + +Every time some transaction is sent, or a new block is generated, you should see a similar output in your console: +``` +Transaction: {account=Tests, address=mhopuJzgmTwhGfpNLCJ9CRknugY691oXp1, category=receive, amount=5.0E-4, label=Tests, vout=1, confirmations=0, trusted=false, txid=361e8fcff243b74ebf396e595a007636654f67c3c7b55fd2860a3d37772155eb, walletconflicts=[], time=1513132887, timereceived=1513132887, bip125-replaceable=unknown} + +Block: 000000004564adfee3738314549f7ca35d96c4da0afc6b232183917086b6d971 +``` diff --git a/README.md b/README.md index 503dc5a..2d24eeb 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,8 @@ This tutorial assumes that you have some minimal background of how to use the co * [12.3: Programming Bitcoind with C](12_3_Programming_Bitcoind_with_C.md) — Needs Editing * [12.4: Receiving Bitcoind Notifications with C](12_4_Receiving_Bitcoind_Notifications_with_C.md) — Pending * [12.5: Accessing Bitcoind with Other Languages](12_5_Accessing_Bitcoind_with_Other_Languages.md) — Writing + * [12.6: Accessing Bitcoind with Python](12_6_Accessing_Bitcoind_with_Python.md) — Writing + * [12.7: Accessing Bitcoind with Java](12_7_Accessing_Bitcoind_with_Java.md) * 13.0: Programming with LibWally * 13.1: Programming Transactions * 13.2: Programming Scripts From 87cbce4e4ea02e2cae4f0abd758d16ba0fbe3012 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Fri, 15 Dec 2017 07:28:06 -0800 Subject: [PATCH 02/38] typo --- 12_7_Accessing_Bitcoind_with_Java.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md index b534557..037118b 100644 --- a/12_7_Accessing_Bitcoind_with_Java.md +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -39,7 +39,7 @@ rpcClient.stop(); ### Making your first RPC Call -In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcloin-cli` or `curl`. +In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcoin-cli` or `curl`. For example, to execute the `getmininginfo`, you should use the `getMiningInfo()` method: ```java From 081bc6893a45db031d7ce2bd1a8dc9bf73c341a3 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 27 Dec 2017 10:30:25 -0800 Subject: [PATCH 03/38] add Java installation details and reference to sample project --- 12_7_Accessing_Bitcoind_with_Java.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md index 037118b..8547e20 100644 --- a/12_7_Accessing_Bitcoind_with_Java.md +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -4,6 +4,23 @@ Interacting with the `bitcoind` directly and using command-line `curl` can get simple if you understand how it works, but there's a project [JavaBitcoindRpcClient](https://github.com/Polve/JavaBitcoindRpcClient) that provides the functionality in a Java-API level, making it even easier to interact with your Bitcoin Server. + +## Setup Java + +To install Java on the VPS Server, you are able to use the `apt-get` command. We will also use [Apache Maven](http://maven.apache.org/) to manage the dependencies, so we will install it together. + +``` +$ apt-get install openjdk-9-jre-headless maven +``` + +You can verify your Java installation: +``` +$ java -version +openjdk version "9-internal" +OpenJDK Runtime Environment (build 9-internal+0-2016-04-14-195246.buildd.src) +OpenJDK 64-Bit Server VM (build 9-internal+0-2016-04-14-195246.buildd.src, mixed mode) +``` + ## Setup Dependency If you use Maven in your Java project, you can include the dependency: @@ -20,6 +37,8 @@ Or if you use Gradle: compile 'wf.bitcoin:JavaBitcoindRpcClient:0.9.13' ``` +If you want a sample project and some instructions on how to run it on the server that we just created, you can refer to the [Bitcoind Java Sample Project](https://github.com/brunocvcunha/bitcoind-java-client-sample/). + ### Build Your Connection To use `JavaBitcoindRpcClient`, you need to create a `BitcoindRpcClient` instance. The arguments in the URL are username, password, IP address and port. You should know this information from your work with `curl` . As you'll recall, the IP address 127.0.0.1 and port 18332 should be correct for the standard testnet setup described in this documents, while you can extract the user and password from `~/.bitcoin/bitcoin.conf`. From 5ad174cedb55320424a2c68fbc70ba143e56a2d2 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 27 Dec 2017 10:35:49 -0800 Subject: [PATCH 04/38] adding more details to the commands --- 12_7_Accessing_Bitcoind_with_Java.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md index 8547e20..7d41b04 100644 --- a/12_7_Accessing_Bitcoind_with_Java.md +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -58,9 +58,9 @@ rpcClient.stop(); ### Making your first RPC Call -In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcoin-cli` or `curl`. +In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcoin-cli` or `curl`, using the same method names. For more details about the commands that you are able to execute and what to expect back, you should refer to [3.2: Knowing Your Bitcoin Setup](03_2_Knowing_Your_Bitcoin_Setup.md). -For example, to execute the `getmininginfo`, you should use the `getMiningInfo()` method: +For example, to execute the `getmininginfo` command to get the block information and the difficulty on the network, you should use the `getMiningInfo()` method: ```java MiningInfo info = rpcClient.getMiningInfo(); System.out.println("Mining Information"); @@ -82,7 +82,9 @@ Hash Power.: 6585163152453.466796875 ### Creating an Address -You can create a new address attaching a specific label to it, as well as dump the private key for a specific address: +You can create a new address on your wallet attaching a specific label to it, as well as dump the private key for a specific address. +For more information about the wallet setup, you can check [3.3: Setting Up Your Wallet](03_3_Setting_Up_Your_Wallet.md). + ```java String address = rpcClient.getNewAddress("Learning-Bitcoin-from-the-Command-Line"); System.out.println("New Address: " + address); @@ -101,6 +103,8 @@ Priv Key: cTy2AnmAALsHokYzJzTdsUBSqBtypmWfmSNYgG6qQH43euUZgqic ### Sending Transactions You can easily send a transaction using the method `sendToAddress()`. +For more information about sending transactions, you can check [4: Sending Bitcoin Transactions](04_0_Sending_Bitcoin_Transactions.md). + ```java String sendToAddress = rpcClient.sendToAddress("mgnNsZj6tPzpd7JwTTidUKnGoDTkcucLT5", 1); From 816fb4d6b928f3541c05b8a7700c5de0812588f0 Mon Sep 17 00:00:00 2001 From: Max Giraldo Date: Tue, 17 Oct 2017 17:01:52 -0500 Subject: [PATCH 05/38] Fix typo in 01_0_Introducing_Bitcoin.md --- 01_0_Introducing_Bitcoin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/01_0_Introducing_Bitcoin.md b/01_0_Introducing_Bitcoin.md index 6b8fe67..bda330c 100644 --- a/01_0_Introducing_Bitcoin.md +++ b/01_0_Introducing_Bitcoin.md @@ -65,7 +65,7 @@ A message (or more commonly, a hash of a message) can be signed with a private k ### What Is a Hash Function? -A hash function is an algorithm frequently used with cryptograpy. It's a way to map a large, arbitrary amount of data to a small, fixed amount of data. Hash functions used in cryptography are one-way and collision-resistant, meaning that a hash can very reliably be linked to the original data, but the original data can not be regenerated from the hash. Hashes thus allow the transmission of small amounts of data to represent large amounts of data, which can be important for efficiency and storage requirements. +A hash function is an algorithm frequently used with cryptography. It's a way to map a large, arbitrary amount of data to a small, fixed amount of data. Hash functions used in cryptography are one-way and collision-resistant, meaning that a hash can very reliably be linked to the original data, but the original data can not be regenerated from the hash. Hashes thus allow the transmission of small amounts of data to represent large amounts of data, which can be important for efficiency and storage requirements. ### Public-Key Cryptography — In Short From 6e9a94255457e8302864532adc73b2f019fbc54e Mon Sep 17 00:00:00 2001 From: Derek Mahar Date: Wed, 4 Oct 2017 10:20:53 -0400 Subject: [PATCH 06/38] Removed duplicate words. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de0ab6c..503dc5a 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Unless otherwise noted, the contents of this repository are Copyright ©2017 by ## Introduction -The best way to learn to learn deeply about bitcoin is to avoid GUIs (even bitcoin-qt), and instead learn it from the command line. +The best way to learn deeply about bitcoin is to avoid GUIs (even bitcoin-qt), and instead learn it from the command line. ## Requirements From 61f36dacac487441444c096924d060b1dc1bb1d9 Mon Sep 17 00:00:00 2001 From: Joe Andrieu Date: Sun, 6 Aug 2017 01:52:22 -0700 Subject: [PATCH 07/38] Removed extra "s" in Summary: Receiving a Transactions --- 03_4_Receiving_a_Transaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03_4_Receiving_a_Transaction.md b/03_4_Receiving_a_Transaction.md index aa306b3..8dc409f 100644 --- a/03_4_Receiving_a_Transaction.md +++ b/03_4_Receiving_a_Transaction.md @@ -203,7 +203,7 @@ You can also use it to look at individual transactions: A block explorer doesn't generally provide any more information than a command line look at a raw transaction; it just does a good job of highlighting the important information and putting together the puzzle pieces, including the transaction fees behind a transaction — another concept that we'll be covering in future sections. -## Summary: Receiving a Transactions +## Summary: Receiving a Transaction Faucets will give you money on the testnet. They come in as raw transactions, which can be examined with `getrawtransaction` or a block explorer. Once you've receive a transaction, you can see it in your balance and your wallet. From 461e1b5e75a356a1626f838dfd29347ed9acf225 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 14:08:12 -0800 Subject: [PATCH 08/38] updating version to 0.15.1 --- 02_2__Script_Linode_Setup.stackscript | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02_2__Script_Linode_Setup.stackscript b/02_2__Script_Linode_Setup.stackscript index 988fbea..48aa81b 100644 --- a/02_2__Script_Linode_Setup.stackscript +++ b/02_2__Script_Linode_Setup.stackscript @@ -23,7 +23,7 @@ # CURRENT BITCOIN RELEASE: # Change as necessary -export BITCOIN=bitcoin-core-0.14.2 +export BITCOIN=bitcoin-core-0.15.1 # Set the variable $IPADDR to the IP address the new Linode receives. IPADDR=$(/sbin/ifconfig eth0 | awk '/inet / { print $2 }' | sed 's/addr://') From ae96d099c1e1d200c3ee12b4139cef3bb8cce753 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 14:09:16 -0800 Subject: [PATCH 09/38] Update storage requirements --- 02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md b/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md index 815c00c..5ff6942 100644 --- a/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md +++ b/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md @@ -41,13 +41,13 @@ We also suggest that you choose a Debian 8 image when you're creating your machi Afterward, boot your VPS. -> **TESTNET vs MAINNET:** The various possible setups require 5-15G of storage and 2-3G of memory. The non-Pruned Mainnet is the only setup that requires considerably more: about 120G of storage to hold the current blockchain. +> **TESTNET vs MAINNET:** The various possible setups require 5-15G of storage and 2-3G of memory. The non-Pruned Mainnet is the only setup that requires considerably more: about 170G of storage to hold the current blockchain. > > Following are suggestions for machine requirements: > > | Setup | Memory | Storage | > |-------|--------|---------| -> | Mainnet | 2-3G | 120G | +> | Mainnet | 2-3G | 170G | > | Pruned Mainnet | 2-3G | ~5G | > | Testnet | 2-3G | ~15G | > | Pruned Testnet | 2-3G | ~5G | From 1a6cf909ec5d884d3a27989fcc27f47f50a90095 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 14:33:16 -0800 Subject: [PATCH 10/38] Update version to 0.15.1 --- 02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md | 16 ++++++++-------- ...ing_Up_a_Bitcoin-Core_VPS_with_StackScript.md | 6 +++--- 03_2_Knowing_Your_Bitcoin_Setup.md | 11 +++++------ 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md b/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md index 5ff6942..94ae50b 100644 --- a/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md +++ b/02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md @@ -33,7 +33,7 @@ If your cloud provider offers two-factor authentication for their web tools, we ### Create a Machine -You should now create your Bitcoin VPS. For an Unpruned Testnet setup, you should have at least 2-3G of memory and at least 15G of storage. +You should now create your Bitcoin VPS. For an Unpruned Testnet setup, you should have at least 2-3G of memory and at least 15G of storage. > **WARNING:** We've occasionally had machines run out of memory after running `bitcoind` for a few days when they only had 2G. Coming back, we find that `bitcoind` has stopped, leaving the message "Error: Out of memory. Terminating." in the `debug.log` file. This simply requires a restart of `bitcoind` and ten or fifteen minutes to get the blockchain resynced. Be generous with your memory if you want to avoid this annoyance, but don't worry too much if you hit it. @@ -61,7 +61,7 @@ You'll need to look up the IP address of your new machine, and then you should b $ ssh root@192.168.1.52 ``` -Now, you'll need to do some bog-standard configuration, then some work to improve the security of your machine. +Now, you'll need to do some bog-standard configuration, then some work to improve the security of your machine. _If you already have your own techniques for setting up a machine, go ahead and follow them, then jump ahead to "Setting Up a User", then "Installing Bitcoin". Otherwise,continue on!_ @@ -99,7 +99,7 @@ Though you're not putting much real value on this server, you should still make ### Create Firewall Rules -To start with, create a firewall rules file. +To start with, create a firewall rules file. _For all instructions that look like this, you should just be able to cut from the "cat" all the way down to the EOF, and everything will be placed into the appropriate file._ ``` @@ -245,7 +245,7 @@ Afterward give user1 access to the directory: $ chown -R user1 ~user1/.ssh ``` If you haven't set up an SSH key on your local computer yet, there are good instructions for it on [Github](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). - + ## Installing Bitcoin You're now ready to get to the bitcoin-specific part of this tutorial! @@ -283,7 +283,7 @@ $ /bin/chown user1 ~user1/.bash_profile ### Login as Your Unprivileged User -You now want to switch over to the user1 account for the actual install: +You now want to switch over to the user1 account for the actual install: ``` $ su user1 $ cd @@ -294,9 +294,9 @@ $ source ~/.bash_profile We suggest setting up two variables to make this installation more automatic. -The first variable, $BITCOIN, should be set to the current version of Bitcoin. It was 0.14.1 when we wrote this. The second will then automatically generate a truncated form used by some of the files. +The first variable, $BITCOIN, should be set to the current version of Bitcoin. It was 0.15.1 when we wrote this. The second will then automatically generate a truncated form used by some of the files. ``` -$ export BITCOIN=bitcoin-core-0.14.1 +$ export BITCOIN=bitcoin-core-0.15.1 $ export BITCOINPLAIN=`echo $BITCOIN | sed 's/bitcoin-core/bitcoin/'` ``` @@ -390,7 +390,7 @@ But wait, your Bitcoin daemon is probably still downloading blocks. This alias, ``` $ btcblock ``` -0.14.1 is quite fast to download blocks, but it might still take an hour to download the unpruned testnet. It might be time for a few more espressos. +0.15.1 is quite fast to download blocks, but it might still take an hour to download the unpruned testnet. It might be time for a few more espressos. > **TESTNET vs MAINNET:** An unpruned mainnet will take hours longer. diff --git a/02_2_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md b/02_2_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md index 8c41eb4..b21314b 100644 --- a/02_2_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md +++ b/02_2_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md @@ -102,7 +102,7 @@ _You can freely choose to enter this optional information or skip it:_ **SSH Key.** Copy your local computer's SSH key here; this allows you be able to automatically login in via SSH to your user1 account. If you haven't setup an SSH key on your local computer yet, there are good instructions for it on [Github](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/). You may also want to add your SSH key into your Linode LISH (Linode Interactive Shell) by going to your "Linode Home Page / My Preferences / LISH Settings / LISH Keys". Using an SSH key will give you a simpler and safer way to log in to your server. -**SSH-Allowed IPs.** This is a comma-separated list of IPs that will be allowed to SSH into the VPS. For example "192.168.1.15,192.168.1.16". If you do not enter any IPs, _your VPS will not be very secure_. It will constantly be bombarded by attackers trying to find their way in, and they may very well succeed. +**SSH-Allowed IPs.** This is a comma-separated list of IPs that will be allowed to SSH into the VPS. For example "192.168.1.15,192.168.1.16". If you do not enter any IPs, _your VPS will not be very secure_. It will constantly be bombarded by attackers trying to find their way in, and they may very well succeed. *The remaining questions all have to do with the mechanics of the VPS deployment and should be left as they are with one exception: bump the Swap Disk from 256MB to 512MB, to ensure that you have enough memory to download the blockchain._ @@ -148,7 +148,7 @@ You will know the StackScripts are done when a BITCOIN-IS-READY file appears in ``` $ ls -bitcoin-0.14.1-x86_64-linux-gnu.tar.gz laanwj-releases.asc +bitcoin-0.15.1-x86_64-linux-gnu.tar.gz laanwj-releases.asc BITCOIN-IS-READY SHA256SUMS.asc ``` @@ -266,7 +266,7 @@ Creating a Bitcoin-Core VPS with a StackScript made the whole process quick, sim You have a few options for what's next: * Read the [StackScript](02_2__Script_Linode_Setup.stackscript) to understand your setup. - * See the other method for setting up a VPS in [§2.1: Setting up a Bitcoin-Core VPS by Hand](02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md). + * See the other method for setting up a VPS in [§2.1: Setting up a Bitcoin-Core VPS by Hand](02_1_Setting_Up_a_Bitcoin-Core_VPS_by_Hand.md). * Move on to "bitcoin-cli" with [Chapter Three: Understanding Your Bitcoin Setup](03_0_Understanding_Your_Bitcoin_Setup.md). ## Appendix: Bitcoin Installation Types diff --git a/03_2_Knowing_Your_Bitcoin_Setup.md b/03_2_Knowing_Your_Bitcoin_Setup.md index 855f317..6e1b90a 100644 --- a/03_2_Knowing_Your_Bitcoin_Setup.md +++ b/03_2_Knowing_Your_Bitcoin_Setup.md @@ -69,7 +69,7 @@ submitblock "hexdata" ( "jsonparametersobject" ) == Network == addnode "node" "add|remove|onetry" clearbanned -disconnectnode "node" +disconnectnode "node" getaddednodeinfo dummy ( "node" ) getconnectioncount getnettotals @@ -162,7 +162,7 @@ Result: } Examples: -> bitcoin-cli getmininginfo +> bitcoin-cli getmininginfo > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getmininginfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ ``` _What is RPC?_ `bitcoin-cli` is just a handy interface that lets you send commands to the `bitcoind`. More specifically, it's an interface that lets you send RPC (or Remote Procedure Protocol) commands to the `bitcoind`. Often, the `bitcoin-cli` command and the RPC command have identical names and interfaces, but some `bitcoin-cli` commands instead provide shortcuts for more complex RPC requests. Generally, the `bitcoin-cli` interface is much cleaner and simpler than trying to send RPC commands by hand, using `curl` or some other method. However, it also has limitations as to what you can ultimately do. @@ -182,7 +182,7 @@ For example `bitcoin-cli getnetworkinfo` gives you a variety of information on y $ bitcoin-cli getnetworkinfo { "version": 140000, - "subversion": "/Satoshi:0.14.0/", + "subversion": "/Satoshi:0.15.1/", "protocolversion": 70015, "localservices": "000000000000000d", "localrelay": false, @@ -196,14 +196,14 @@ $ bitcoin-cli getnetworkinfo "reachable": true, "proxy": "", "proxy_randomize_credentials": false - }, + }, { "name": "ipv6", "limited": false, "reachable": true, "proxy": "", "proxy_randomize_credentials": false - }, + }, { "name": "onion", "limited": true, @@ -232,4 +232,3 @@ The ~/.bitcoin directory contains all of your files, while `bitcoin-cli help` an ## What's Next? Continue "Understanding Your Bitcoin Setup" with [§3.3: Setting Up Your Wallet](03_3_Setting_Up_Your_Wallet.md). - From 684bb1c4d321ff619b6b6a736dcf9838a3322b7c Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 15:51:21 -0800 Subject: [PATCH 11/38] Update outputs from bitcoin-cli on 0.15.1 --- 03_2_Knowing_Your_Bitcoin_Setup.md | 83 +++++++++++++++++------------- 1 file changed, 46 insertions(+), 37 deletions(-) diff --git a/03_2_Knowing_Your_Bitcoin_Setup.md b/03_2_Knowing_Your_Bitcoin_Setup.md index 6e1b90a..089c310 100644 --- a/03_2_Knowing_Your_Bitcoin_Setup.md +++ b/03_2_Knowing_Your_Bitcoin_Setup.md @@ -32,57 +32,64 @@ Most of your early work will be done with the `bitcoin-cli` command, which offer $ bitcoin-cli help == Blockchain == getbestblockhash -getblock "hash" ( verbose ) +getblock "blockhash" ( verbosity ) getblockchaininfo getblockcount -getblockhash index +getblockhash height getblockheader "hash" ( verbose ) getchaintips +getchaintxstats ( nblocks blockhash ) getdifficulty getmempoolancestors txid (verbose) getmempooldescendants txid (verbose) getmempoolentry txid getmempoolinfo getrawmempool ( verbose ) -gettxout "txid" n ( includemempool ) +gettxout "txid" n ( include_mempool ) gettxoutproof ["txid",...] ( blockhash ) gettxoutsetinfo -verifychain ( checklevel numblocks ) +preciousblock "blockhash" +pruneblockchain +verifychain ( checklevel nblocks ) verifytxoutproof "proof" == Control == getinfo +getmemoryinfo ("mode") help ( "command" ) stop +uptime == Generating == -generate numblocks ( maxtries ) -generatetoaddress numblocks address (maxtries) +generate nblocks ( maxtries ) +generatetoaddress nblocks address (maxtries) == Mining == getblocktemplate ( TemplateRequest ) getmininginfo -getnetworkhashps ( blocks height ) -prioritisetransaction -submitblock "hexdata" ( "jsonparametersobject" ) +getnetworkhashps ( nblocks height ) +prioritisetransaction +submitblock "hexdata" ( "dummy" ) == Network == addnode "node" "add|remove|onetry" clearbanned -disconnectnode "node" -getaddednodeinfo dummy ( "node" ) +disconnectnode "[address]" [nodeid] +getaddednodeinfo ( "node" ) getconnectioncount getnettotals getnetworkinfo getpeerinfo listbanned ping -setban "ip(/netmask)" "add|remove" (bantime) (absolute) +setban "subnet" "add|remove" (bantime) (absolute) +setnetworkactive true|false == Rawtransactions == -createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,"data":"hex",...} ( locktime ) +combinerawtransaction ["hexstring",...] +createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,"data":"hex",...} ( locktime ) ( replaceable ) decoderawtransaction "hexstring" -decodescript "hex" +decodescript "hexstring" fundrawtransaction "hexstring" ( options ) getrawtransaction "txid" ( verbose ) sendrawtransaction "hexstring" ( allowhighfees ) @@ -91,55 +98,57 @@ signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","re == Util == createmultisig nrequired ["key",...] estimatefee nblocks -estimatepriority nblocks -estimatesmartfee nblocks -estimatesmartpriority nblocks +estimatesmartfee conf_target ("estimate_mode") signmessagewithprivkey "privkey" "message" -validateaddress "bitcoinaddress" -verifymessage "bitcoinaddress" "signature" "message" +validateaddress "address" +verifymessage "address" "signature" "message" == Wallet == abandontransaction "txid" +abortrescan addmultisigaddress nrequired ["key",...] ( "account" ) addwitnessaddress "address" backupwallet "destination" -dumpprivkey "bitcoinaddress" +bumpfee "txid" ( options ) +dumpprivkey "address" dumpwallet "filename" encryptwallet "passphrase" -getaccount "bitcoinaddress" +getaccount "address" getaccountaddress "account" getaddressesbyaccount "account" -getbalance ( "account" minconf includeWatchonly ) +getbalance ( "account" minconf include_watchonly ) getnewaddress ( "account" ) getrawchangeaddress getreceivedbyaccount "account" ( minconf ) -getreceivedbyaddress "bitcoinaddress" ( minconf ) -gettransaction "txid" ( includeWatchonly ) +getreceivedbyaddress "address" ( minconf ) +gettransaction "txid" ( include_watchonly ) getunconfirmedbalance getwalletinfo importaddress "address" ( "label" rescan p2sh ) -importprivkey "bitcoinprivkey" ( "label" rescan ) +importmulti "requests" ( "options" ) +importprivkey "privkey" ( "label" ) ( rescan ) importprunedfunds importpubkey "pubkey" ( "label" rescan ) importwallet "filename" keypoolrefill ( newsize ) -listaccounts ( minconf includeWatchonly) +listaccounts ( minconf include_watchonly) listaddressgroupings listlockunspent -listreceivedbyaccount ( minconf includeempty includeWatchonly) -listreceivedbyaddress ( minconf includeempty includeWatchonly) -listsinceblock ( "blockhash" target-confirmations includeWatchonly) -listtransactions ( "account" count from includeWatchonly) -listunspent ( minconf maxconf ["address",...] ) +listreceivedbyaccount ( minconf include_empty include_watchonly) +listreceivedbyaddress ( minconf include_empty include_watchonly) +listsinceblock ( "blockhash" target_confirmations include_watchonly include_removed ) +listtransactions ( "account" count skip include_watchonly) +listunspent ( minconf maxconf ["addresses",...] [include_unsafe] [query_options]) +listwallets lockunspent unlock ([{"txid":"txid","vout":n},...]) move "fromaccount" "toaccount" amount ( minconf "comment" ) removeprunedfunds "txid" -sendfrom "fromaccount" "tobitcoinaddress" amount ( minconf "comment" "comment-to" ) -sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] ) -sendtoaddress "bitcoinaddress" amount ( "comment" "comment-to" subtractfeefromamount ) -setaccount "bitcoinaddress" "account" +sendfrom "fromaccount" "toaddress" amount ( minconf "comment" "comment_to" ) +sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] replaceable conf_target "estimate_mode") +sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount replaceable conf_target "estimate_mode") +setaccount "address" "account" settxfee amount -signmessage "bitcoinaddress" "message" +signmessage "address" "message" ``` You can also type `bitcoin help [command]` to get even more extensive info on that command. For example: ``` @@ -181,7 +190,7 @@ For example `bitcoin-cli getnetworkinfo` gives you a variety of information on y ``` $ bitcoin-cli getnetworkinfo { - "version": 140000, + "version": 150100, "subversion": "/Satoshi:0.15.1/", "protocolversion": 70015, "localservices": "000000000000000d", From dd316ac68b5ad67e8360d573bd02a58932198570 Mon Sep 17 00:00:00 2001 From: kallewoof Date: Wed, 13 Dec 2017 15:25:25 +0900 Subject: [PATCH 12/38] Update 12_5_Accessing_Bitcoind_with_Other_Languages.md --- 12_5_Accessing_Bitcoind_with_Other_Languages.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/12_5_Accessing_Bitcoind_with_Other_Languages.md b/12_5_Accessing_Bitcoind_with_Other_Languages.md index 6436a99..e201f51 100644 --- a/12_5_Accessing_Bitcoind_with_Other_Languages.md +++ b/12_5_Accessing_Bitcoind_with_Other_Languages.md @@ -21,15 +21,14 @@ sudo apt-get install mocha -g ``` ### Set Up BCRPC -You should next download BCRPC from the [BCRPC Repository](https://github.com/dgarage/bcrpc). Clone it or download it, as you prefer. - -Once you've done that, you can finish setting it up: +Create a new node.js project and install BCRPC via NPM. ``` -$ unzip bcrpc-master.zip -$ cd bcrpc-master -$ npm install +$ mkdir myproject +$ cd myproject +$ npm init +[...] +$ npm install --save bcrpc ``` - ### Test BCRPC To test the BCRPC package, you must first set environmental variables for your rpcuser and rpcpassword. As noted in [§12.1: Accessing Bitcoind with Curl](12_1_Accessing_Bitcoind_with_Curl.md), these come from `~/.bitcoin/bitcoin.conf`. From 3adfa8473d46c4b8c869c927e47e7b8774495be8 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 22:49:02 -0800 Subject: [PATCH 13/38] Create 12.7 Accessing Bitcoind with Java --- 12_7_Accessing_Bitcoind_with_Java.md | 131 +++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 133 insertions(+) create mode 100644 12_7_Accessing_Bitcoind_with_Java.md diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md new file mode 100644 index 0000000..b534557 --- /dev/null +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -0,0 +1,131 @@ +# 12.7: Accessing Bitcoind with Java + +> **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning. + +Interacting with the `bitcoind` directly and using command-line `curl` can get simple if you understand how it works, but there's a project [JavaBitcoindRpcClient](https://github.com/Polve/JavaBitcoindRpcClient) that provides the functionality in a Java-API level, making it even easier to interact with your Bitcoin Server. + +## Setup Dependency + +If you use Maven in your Java project, you can include the dependency: +```xml + + wf.bitcoin + JavaBitcoindRpcClient + 0.9.13 + +``` + +Or if you use Gradle: +```groovy +compile 'wf.bitcoin:JavaBitcoindRpcClient:0.9.13' +``` + +### Build Your Connection + +To use `JavaBitcoindRpcClient`, you need to create a `BitcoindRpcClient` instance. The arguments in the URL are username, password, IP address and port. You should know this information from your work with `curl` . As you'll recall, the IP address 127.0.0.1 and port 18332 should be correct for the standard testnet setup described in this documents, while you can extract the user and password from `~/.bitcoin/bitcoin.conf`. + +```java + BitcoindRpcClient rpcClient = new BitcoinJSONRPCClient("http://bitcoinrpc:d8340efbcd34e312044c8431c59c792c@127.0.0.1:18332"); +``` + +> **MAINNET VS TESTNET:** The port would be 8332 for a mainnet setup. + +If `rpcClient` is successfully initialized, you'll be able to send off RPC commands. + +Later, when you're all done with your `bitcoind` connection, you should close it: +``` +rpcClient.stop(); +``` + +### Making your first RPC Call + +In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcloin-cli` or `curl`. + +For example, to execute the `getmininginfo`, you should use the `getMiningInfo()` method: +```java +MiningInfo info = rpcClient.getMiningInfo(); +System.out.println("Mining Information"); +System.out.println("------------------"); +System.out.println("Chain......: " + info.chain()); +System.out.println("Blocks.....: " + info.blocks()); +System.out.println("Difficulty.: " + info.difficulty()); +System.out.println("Hash Power.: " + new BigDecimal(info.networkHashps()).toPlainString()); +``` +The output for this line should be similar to this: +``` +Mining Information +------------------ +Chain......: test +Blocks.....: 1254920 +Difficulty.: 1.0 +Hash Power.: 6585163152453.466796875 +``` + +### Creating an Address + +You can create a new address attaching a specific label to it, as well as dump the private key for a specific address: +```java + String address = rpcClient.getNewAddress("Learning-Bitcoin-from-the-Command-Line"); + System.out.println("New Address: " + address); + + String privKey = rpcClient.dumpPrivKey(address); + System.out.println("Priv Key: " + privKey); +``` +Output: +``` +New Address: mpsFtZ8qTJPRGZy1gaaUw37fHeUSPLkzzs +Priv Key: cTy2AnmAALsHokYzJzTdsUBSqBtypmWfmSNYgG6qQH43euUZgqic +``` + + + +### Sending Transactions + +You can easily send a transaction using the method `sendToAddress()`. + +```java +String sendToAddress = rpcClient.sendToAddress("mgnNsZj6tPzpd7JwTTidUKnGoDTkcucLT5", 1); +System.out.println("Send: " + sendToAddress); +``` +This program will output a transaction id, for example: +``` +a2d2f629d6666ca6e440169a322850cd9d133f637f7a02a02a0a7477bc5687d4 +``` + +In case you want to adjust the transaction fee, you can use the `setTxFee` method before sending the output: + +```java +rpcClient.setTxFee(new BigDecimal(0.001).setScale(3, BigDecimal.ROUND_DOWN)); +``` + + +### Listening to Transactions or Blocks + +You may want to write applications that keep listening the Blockchain, and execute a specific code when something happens, such as a transaction that involves an address in your wallet, or even the generation of a new block in the network. +To do that, `JavaBitcoindRpcClient` provides support to `BitcoinAcceptor`, where you can attach listeners in the network. + +Example: +```java + BitcoinAcceptor acceptor = new BitcoinAcceptor(rpcClient, blockHash, 6, new BitcoinPaymentListener() { + + @Override + public void transaction(Transaction tx) { + System.out.println("Transaction: " + tx); + + } + + @Override + public void block(String block) { + System.out.println("Block: " + block); + + } + }); + acceptor.run(); +``` + +Every time some transaction is sent, or a new block is generated, you should see a similar output in your console: +``` +Transaction: {account=Tests, address=mhopuJzgmTwhGfpNLCJ9CRknugY691oXp1, category=receive, amount=5.0E-4, label=Tests, vout=1, confirmations=0, trusted=false, txid=361e8fcff243b74ebf396e595a007636654f67c3c7b55fd2860a3d37772155eb, walletconflicts=[], time=1513132887, timereceived=1513132887, bip125-replaceable=unknown} + +Block: 000000004564adfee3738314549f7ca35d96c4da0afc6b232183917086b6d971 +``` diff --git a/README.md b/README.md index 503dc5a..2d24eeb 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,8 @@ This tutorial assumes that you have some minimal background of how to use the co * [12.3: Programming Bitcoind with C](12_3_Programming_Bitcoind_with_C.md) — Needs Editing * [12.4: Receiving Bitcoind Notifications with C](12_4_Receiving_Bitcoind_Notifications_with_C.md) — Pending * [12.5: Accessing Bitcoind with Other Languages](12_5_Accessing_Bitcoind_with_Other_Languages.md) — Writing + * [12.6: Accessing Bitcoind with Python](12_6_Accessing_Bitcoind_with_Python.md) — Writing + * [12.7: Accessing Bitcoind with Java](12_7_Accessing_Bitcoind_with_Java.md) * 13.0: Programming with LibWally * 13.1: Programming Transactions * 13.2: Programming Scripts From 723f929f0cc23c3ba35191dd0519dc0b4dda086b Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Fri, 15 Dec 2017 07:28:06 -0800 Subject: [PATCH 14/38] typo --- 12_7_Accessing_Bitcoind_with_Java.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md index b534557..037118b 100644 --- a/12_7_Accessing_Bitcoind_with_Java.md +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -39,7 +39,7 @@ rpcClient.stop(); ### Making your first RPC Call -In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcloin-cli` or `curl`. +In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcoin-cli` or `curl`. For example, to execute the `getmininginfo`, you should use the `getMiningInfo()` method: ```java From 9d7f073a1ebdc172a1910f02ffd34ff680524dd2 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 11:57:37 -0800 Subject: [PATCH 15/38] Create first draft of Chapter 15 --- 15_0_Setting_Up_a_Bitcoin_Regtest.md | 18 +++++++++++++++ 15_1_Building_the_Regtest.md | 34 ++++++++++++++++++++++++++++ 15_2_Testing_with_Regtest.md | 11 +++++++++ 3 files changed, 63 insertions(+) create mode 100644 15_0_Setting_Up_a_Bitcoin_Regtest.md create mode 100644 15_1_Building_the_Regtest.md create mode 100644 15_2_Testing_with_Regtest.md diff --git a/15_0_Setting_Up_a_Bitcoin_Regtest.md b/15_0_Setting_Up_a_Bitcoin_Regtest.md new file mode 100644 index 0000000..c5602e8 --- /dev/null +++ b/15_0_Setting_Up_a_Bitcoin_Regtest.md @@ -0,0 +1,18 @@ +# Chapter 15: Setting Up a Bitcoin Regtest + +While developing Bitcoin applications, it might happen that you 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. + +## Objectives for This Chapter + +After working through this chapter, a developer will be able to: + + * Create your own Blockchain from scratch + * Create the Genesis block and more blocks on top of it + * Get balance and interact with Bitcoind in a private way + +## Table of Contents + + * [Section One: Building the Regtest](15_1_Building_the_Regtest.md) + * [Section Two: Testing with Regtest](15_2_Testing_with_Regtest.md) + * [Section Three: Mining with Regtest](15_3_Mining_with_Regtest.md) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md new file mode 100644 index 0000000..219047f --- /dev/null +++ b/15_1_Building_the_Regtest.md @@ -0,0 +1,34 @@ +# 15.1: Building the Regtest + +> **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. +Bitcoin Core’s regression test mode (regtest mode) lets you instantly create a brand-new private block chain with the same basic rules as testnet—but one major difference: you choose when to create new blocks, so you have complete control over the environment. + +## Starting Bitcoind in Regtest Mode + +To start your bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command: +``` +$ bitcoind -regtest -daemon +``` + +## 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: +``` +$ bitcoin-cli -regtest generate 101 +``` + +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. +However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. + +## Verifying balance + +After mining blocks and getting the reward for the first one, you can verify the balance on your wallet: +``` +$ bitcoin-cli -regtest getbalance +``` + +Now you can use this balance for any kind of interaction with the private Blockchain, such as sending Bitcoin transactions according to [Chapter 4]((04_0_Sending_Bitcoin_Transactions.md)) in this guide. diff --git a/15_2_Testing_with_Regtest.md b/15_2_Testing_with_Regtest.md new file mode 100644 index 0000000..6167277 --- /dev/null +++ b/15_2_Testing_with_Regtest.md @@ -0,0 +1,11 @@ +# 15.2: Testing with Regtest + +> **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 test a Regtest (Regression Test). + +## Testing with Regtest + +After [starting Bitcoind using Regtest mode](15_1_Building_the_Regtest.md) you can use any `bitcoin-cli` command or interact with the blockchain using the RPC (Remote Procedure Call) service. + +You can try to create transactions referring to [Chapter 4 - Sending Bitcoin Transactions](04_0_Sending_Bitcoin_Transactions.md) in this guide. In order to get balance in your Regtest Wallet, you are able to [mine blocks with minimal proof-of-work and get the rewards](15_3_Mining_with_Regtest.md). From 6489be79cf32b78703c7f6e40b12a266727b43bf Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:25:16 -0800 Subject: [PATCH 16/38] Add Chapter 15 anchors --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2d24eeb..8ed6091 100644 --- a/README.md +++ b/README.md @@ -106,10 +106,10 @@ Add: HOW TO DO A REFUND (short answer: ask!) ** PART FIVE: BITCOIN FUTURES ** -* 15.0: Setting Up a Bitcoin Regtest - * 15.1: Building the Regtest - * 15.2: Testing with Regtest - * 15.3: Mining with Regtest +* [15.0: Setting Up a Bitcoin Regtest](15_0_Setting_Up_a_Bitcoin_Regtest.md) + * [15.1: Building the Regtest](15_1_Building_the_Regtest.md) + * [15.2: Testing with Regtest](15_2_Testing_with_Regtest.md) + * [15.3: Mining with Regtest](15_3_Mining_with_Regtest.md) ** APPENDICES ** From 58a53cad64219958bdd200aa0e5232894a0e914b Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:28:49 -0800 Subject: [PATCH 17/38] First version of 15.3: Mining the Regtest --- 15_3_Mining_with_Regtest.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 15_3_Mining_with_Regtest.md diff --git a/15_3_Mining_with_Regtest.md b/15_3_Mining_with_Regtest.md new file mode 100644 index 0000000..8522fb4 --- /dev/null +++ b/15_3_Mining_with_Regtest.md @@ -0,0 +1,20 @@ +# 15.3: Mining the Regtest + +> **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. + + +## 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: +``` +$ bitcoin-cli -regtest generate 101 +``` + +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. +However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. + From b30599afc93482d6db9abcc5f216071dcba78daf Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:33:17 -0800 Subject: [PATCH 18/38] Update 15.1 to have anchor to other topics --- 15_1_Building_the_Regtest.md | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index 219047f..a3c132b 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -7,28 +7,13 @@ Bitcoin Core’s regression test mode (regtest mode) lets you instantly create a ## Starting Bitcoind in Regtest Mode -To start your bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command: +To start your Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command: ``` $ bitcoind -regtest -daemon ``` -## Generating blocks +## What's next -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 -``` +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_3_Mining_with_Regtest.md). +This will allow you to get balance into your wallet and [test the Regtest blockchain](15_2_Testing_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. -However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. - -## Verifying balance - -After mining blocks and getting the reward for the first one, you can verify the balance on your wallet: -``` -$ bitcoin-cli -regtest getbalance -``` - -Now you can use this balance for any kind of interaction with the private Blockchain, such as sending Bitcoin transactions according to [Chapter 4]((04_0_Sending_Bitcoin_Transactions.md)) in this guide. From 98cfb49aeebec5071d41a636bed02af6c29ee3ed Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:33:50 -0800 Subject: [PATCH 19/38] small fix --- 15_1_Building_the_Regtest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index a3c132b..d59ce6e 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -15,5 +15,5 @@ $ bitcoind -regtest -daemon ## 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_3_Mining_with_Regtest.md). -This will allow you to get balance into your wallet and [test the Regtest blockchain](15_2_Testing_with_Regtest.md) +This will allow you to get balance into your wallet and [test the Regtest blockchain](15_2_Testing_with_Regtest.md). From abb0cc14eb385e93868a3bb617d7a3d11bf1a7eb Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:36:41 -0800 Subject: [PATCH 20/38] Improve 15.2 and anchors to the other documents --- 15_2_Testing_with_Regtest.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/15_2_Testing_with_Regtest.md b/15_2_Testing_with_Regtest.md index 6167277..808dfe3 100644 --- a/15_2_Testing_with_Regtest.md +++ b/15_2_Testing_with_Regtest.md @@ -4,8 +4,15 @@ This document explains how to test a Regtest (Regression Test). -## Testing with Regtest -After [starting Bitcoind using Regtest mode](15_1_Building_the_Regtest.md) you can use any `bitcoin-cli` command or interact with the blockchain using the RPC (Remote Procedure Call) service. +## Verifying balance -You can try to create transactions referring to [Chapter 4 - Sending Bitcoin Transactions](04_0_Sending_Bitcoin_Transactions.md) in this guide. In order to get balance in your Regtest Wallet, you are able to [mine blocks with minimal proof-of-work and get the rewards](15_3_Mining_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 +``` + +## Testing the Regtest +Now you should be able to use this balance for any kind of interaction with the private Blockchain, such as sending Bitcoin transactions according to [Chapter 4]((04_0_Sending_Bitcoin_Transactions.md)) in this guide. + +It is important to note that in order for your transactions to complete, you will have to generate/mine new blocks, so the transactions can be included into them. From a4e2bfbecc5f0d991209a8c51fe102e3487f66fd Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:48:26 -0800 Subject: [PATCH 21/38] fix word --- 15_0_Setting_Up_a_Bitcoin_Regtest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15_0_Setting_Up_a_Bitcoin_Regtest.md b/15_0_Setting_Up_a_Bitcoin_Regtest.md index c5602e8..f7c319f 100644 --- a/15_0_Setting_Up_a_Bitcoin_Regtest.md +++ b/15_0_Setting_Up_a_Bitcoin_Regtest.md @@ -1,6 +1,6 @@ # Chapter 15: Setting Up a Bitcoin Regtest -While developing Bitcoin applications, it might happen that you want to use your applications isolated from any public Blockchain such as the Mainnet or the Testnet. +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. ## Objectives for This Chapter From 7258955d2130ebba423e991946222a3a812d70bf Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:49:08 -0800 Subject: [PATCH 22/38] Word fix --- 15_1_Building_the_Regtest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index d59ce6e..b882c62 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -15,5 +15,5 @@ $ bitcoind -regtest -daemon ## 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_3_Mining_with_Regtest.md). -This will allow you to get balance into your wallet and [test the Regtest blockchain](15_2_Testing_with_Regtest.md). +This will allow you to get balance in your wallet and [test the Regtest blockchain](15_2_Testing_with_Regtest.md). From 15c8a0f734fbae9d75f5f7b9b1ce120cee1fe3a5 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 12:49:58 -0800 Subject: [PATCH 23/38] Words fix --- 15_2_Testing_with_Regtest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/15_2_Testing_with_Regtest.md b/15_2_Testing_with_Regtest.md index 808dfe3..abc7ad1 100644 --- a/15_2_Testing_with_Regtest.md +++ b/15_2_Testing_with_Regtest.md @@ -13,6 +13,6 @@ $ bitcoin-cli -regtest getbalance ``` ## Testing the Regtest -Now you should be able to use this balance for any kind of interaction with the private Blockchain, such as sending Bitcoin transactions according to [Chapter 4]((04_0_Sending_Bitcoin_Transactions.md)) in this guide. +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. -It is important to note that in order for your transactions to complete, you will have to generate/mine new blocks, so the transactions can be included into them. +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. From 9d19768ecf159c6f5a534f1312e93d0f0aae7b8d Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 13:34:18 -0800 Subject: [PATCH 24/38] Fix "What's Next?" title to conform with the repo --- 15_1_Building_the_Regtest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index b882c62..e82305a 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -12,7 +12,7 @@ To start your Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blo $ bitcoind -regtest -daemon ``` -## What's next +## 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_3_Mining_with_Regtest.md). This will allow you to get balance in your wallet and [test the Regtest blockchain](15_2_Testing_with_Regtest.md). From 16761c7be7b1324aceb47601cd512e4a1df416c5 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 13:46:18 -0800 Subject: [PATCH 25/38] Flag -regtest is needed when using the bitcoin-cli --- 15_2_Testing_with_Regtest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15_2_Testing_with_Regtest.md b/15_2_Testing_with_Regtest.md index abc7ad1..42bc637 100644 --- a/15_2_Testing_with_Regtest.md +++ b/15_2_Testing_with_Regtest.md @@ -13,6 +13,6 @@ $ bitcoin-cli -regtest getbalance ``` ## Testing 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. +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. From e10c8cabd5b4e4fdadef435529b4356103382f93 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 13:50:02 -0800 Subject: [PATCH 26/38] Resetting the Regtest Blockchain --- 15_1_Building_the_Regtest.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index e82305a..f217a5c 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -12,6 +12,11 @@ To start your Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blo $ bitcoind -regtest -daemon ``` +## Resetting the Regtest Blockchain + +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. + ## 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_3_Mining_with_Regtest.md). From 4f1cb3ed524b2f48c1a169ceb37b5eba002452c9 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Tue, 12 Dec 2017 13:54:29 -0800 Subject: [PATCH 27/38] Add example of sendtoaddress + confirm the tx --- 15_2_Testing_with_Regtest.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/15_2_Testing_with_Regtest.md b/15_2_Testing_with_Regtest.md index 42bc637..9050efb 100644 --- a/15_2_Testing_with_Regtest.md +++ b/15_2_Testing_with_Regtest.md @@ -16,3 +16,13 @@ $ bitcoin-cli -regtest getbalance 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. + +For example, to create a transaction and include into a block: +``` +$ bitcoin-cli -regtest sendtoaddress [address] 10.0 +``` + +And after it, if your application requires 6 confirmations, you can mine additional 6 blocks into your Regtest chain: +``` +$ bitcoin-cli -regtest generate 6 +``` From ae7f716a0ad8fe95d1e295f2c2209d3bf79c3d0c Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 14:21:44 -0800 Subject: [PATCH 28/38] Chapter 15 improvements --- 15_1_Building_the_Regtest.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index f217a5c..648cf7b 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -7,15 +7,23 @@ Bitcoin Core’s regression test mode (regtest mode) lets you instantly create a ## Starting Bitcoind in Regtest Mode -To start your Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command: +After [setting up your Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md), you are now able to use the Regtest mode. To start Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command: ``` $ bitcoind -regtest -daemon ``` ## Resetting the Regtest Blockchain -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. +Regtest wallets and block chain state (chainstate) are saved in the regtest subdirectory of the Bitcoin configuration directory: +``` +user@mybtc:~/.bitcoin# ls +bitcoin.conf regtest testnet3 +``` + +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 +``` ## What's Next? From 95808ceb7563b880bb6e4d9588ea64bcbf230faa Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 14:25:31 -0800 Subject: [PATCH 29/38] Chapter 15 improvements --- 15_3_Mining_with_Regtest.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/15_3_Mining_with_Regtest.md b/15_3_Mining_with_Regtest.md index 8522fb4..319a25c 100644 --- a/15_3_Mining_with_Regtest.md +++ b/15_3_Mining_with_Regtest.md @@ -11,7 +11,16 @@ To generate the Genesis block and the next blocks on a new blockchain requires v 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 +[ + "57f17afccf28b9296048b6370312678b6d8e48dc3a7b4ef7681d18ed3d91c122", + "631ff7b8135ce633c774828be3b8505726459eb65c339aab981b10363befe5a7", + ... + "1162dbfe025c7da94ee1128dc26d518a94508f532c19edc0de6bc673a909d02c", + "20cb2e815c3d42d6a117a204a0b5e726ab641c826e441b5b3417aca33f2aba48" +] ``` +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. Because this is a new block chain using Bitcoin’s default rules, the first blocks pay a block reward of 50 bitcoins. From f31266f11b2f769a8ff0a913b948f5c26a77c865 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 14:44:05 -0800 Subject: [PATCH 30/38] Improve Chapter 15 - Regtest --- 15_0_Setting_Up_a_Bitcoin_Regtest.md | 6 +++--- 15_1_Building_the_Regtest.md | 5 ++--- 15_2_Testing_with_Regtest.md | 28 --------------------------- 15_3_Mining_with_Regtest.md | 29 ---------------------------- README.md | 4 ++-- 5 files changed, 7 insertions(+), 65 deletions(-) delete mode 100644 15_2_Testing_with_Regtest.md delete mode 100644 15_3_Mining_with_Regtest.md diff --git a/15_0_Setting_Up_a_Bitcoin_Regtest.md b/15_0_Setting_Up_a_Bitcoin_Regtest.md index f7c319f..aa2590b 100644 --- a/15_0_Setting_Up_a_Bitcoin_Regtest.md +++ b/15_0_Setting_Up_a_Bitcoin_Regtest.md @@ -10,9 +10,9 @@ After working through this chapter, a developer will be able to: * Create your own Blockchain from scratch * Create the Genesis block and more blocks on top of it * Get balance and interact with Bitcoind in a private way - + ## Table of Contents * [Section One: Building the Regtest](15_1_Building_the_Regtest.md) - * [Section Two: Testing with Regtest](15_2_Testing_with_Regtest.md) - * [Section Three: Mining with Regtest](15_3_Mining_with_Regtest.md) + * [Section Two: Mining with Regtest](15_2_Mining_with_Regtest.md) + * [Section Three: Testing with Regtest](15_3_Testing_with_Regtest.md) diff --git a/15_1_Building_the_Regtest.md b/15_1_Building_the_Regtest.md index 648cf7b..ee57f5f 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Building_the_Regtest.md @@ -27,6 +27,5 @@ $ rm -rf regtest ## 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_3_Mining_with_Regtest.md). -This will allow you to get balance in your wallet and [test the Regtest blockchain](15_2_Testing_with_Regtest.md). - +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). +This will allow you to get balance in your wallet and [test the Regtest blockchain](15_3_Testing_with_Regtest.md). diff --git a/15_2_Testing_with_Regtest.md b/15_2_Testing_with_Regtest.md deleted file mode 100644 index 9050efb..0000000 --- a/15_2_Testing_with_Regtest.md +++ /dev/null @@ -1,28 +0,0 @@ -# 15.2: Testing with Regtest - -> **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 test a Regtest (Regression Test). - - -## Verifying balance - -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 -``` - -## Testing 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. - -For example, to create a transaction and include into a block: -``` -$ bitcoin-cli -regtest sendtoaddress [address] 10.0 -``` - -And after it, if your application requires 6 confirmations, you can mine additional 6 blocks into your Regtest chain: -``` -$ bitcoin-cli -regtest generate 6 -``` diff --git a/15_3_Mining_with_Regtest.md b/15_3_Mining_with_Regtest.md deleted file mode 100644 index 319a25c..0000000 --- a/15_3_Mining_with_Regtest.md +++ /dev/null @@ -1,29 +0,0 @@ -# 15.3: Mining the Regtest - -> **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. - - -## 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: -``` -$ bitcoin-cli -regtest generate 101 -[ - "57f17afccf28b9296048b6370312678b6d8e48dc3a7b4ef7681d18ed3d91c122", - "631ff7b8135ce633c774828be3b8505726459eb65c339aab981b10363befe5a7", - ... - "1162dbfe025c7da94ee1128dc26d518a94508f532c19edc0de6bc673a909d02c", - "20cb2e815c3d42d6a117a204a0b5e726ab641c826e441b5b3417aca33f2aba48" -] -``` -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. -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. -However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. - diff --git a/README.md b/README.md index 8ed6091..675e2de 100644 --- a/README.md +++ b/README.md @@ -108,8 +108,8 @@ Add: HOW TO DO A REFUND (short answer: ask!) * [15.0: Setting Up a Bitcoin Regtest](15_0_Setting_Up_a_Bitcoin_Regtest.md) * [15.1: Building the Regtest](15_1_Building_the_Regtest.md) - * [15.2: Testing with Regtest](15_2_Testing_with_Regtest.md) - * [15.3: Mining with Regtest](15_3_Mining_with_Regtest.md) + * [15.2: Mining with Regtest](15_2_Mining_with_Regtest.md) + * [15.3: Testing with Regtest](15_3_Testing_with_Regtest.md) ** APPENDICES ** From 0ae6b5ef92b85e3f5ab658c1f6d61e5793b41a67 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 14:47:54 -0800 Subject: [PATCH 31/38] Add chapters --- 15_2_Mining_with_Regtest.md | 28 +++++++++++++ 15_3_Testing_with_Regtest.md | 77 ++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 15_2_Mining_with_Regtest.md create mode 100644 15_3_Testing_with_Regtest.md diff --git a/15_2_Mining_with_Regtest.md b/15_2_Mining_with_Regtest.md new file mode 100644 index 0000000..885e4e0 --- /dev/null +++ b/15_2_Mining_with_Regtest.md @@ -0,0 +1,28 @@ +# 15.2: Mining the Regtest + +> **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. + + +## 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: +``` +$ bitcoin-cli -regtest generate 101 +[ + "57f17afccf28b9296048b6370312678b6d8e48dc3a7b4ef7681d18ed3d91c122", + "631ff7b8135ce633c774828be3b8505726459eb65c339aab981b10363befe5a7", + ... + "1162dbfe025c7da94ee1128dc26d518a94508f532c19edc0de6bc673a909d02c", + "20cb2e815c3d42d6a117a204a0b5e726ab641c826e441b5b3417aca33f2aba48" +] +``` +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. +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. +However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. diff --git a/15_3_Testing_with_Regtest.md b/15_3_Testing_with_Regtest.md new file mode 100644 index 0000000..1b9b750 --- /dev/null +++ b/15_3_Testing_with_Regtest.md @@ -0,0 +1,77 @@ +# 15.3: Testing with Regtest + +> **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 test a Regtest (Regression Test). + + +## Verifying balance + +After [mining blocks](15_2_Mining_with_Regtest.md) and getting the rewards, you can verify the balance on your wallet: +``` +$ bitcoin-cli -regtest getbalance + +``` + +## Testing 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. + +For example, to create a transaction and include into a block, you should use the `sendtoaddress` command: +``` +$ bitcoin-cli -regtest sendtoaddress [address] 15.1 +e834a4ac6ef754164c8e3f0be4f34531b74b768199ffb244ab9f6cb1bbc7465a +``` + +The output is the transaction hash included in the blockchain. You can verify the details using the `gettransaction`: +``` +$ bitcoin-cli -regtest gettransaction e834a4ac6ef754164c8e3f0be4f34531b74b768199ffb244ab9f6cb1bbc7465a +{ + "amount": 0.00000000, + "fee": -0.00178800, + "confirmations": 0, + "trusted": false, + "txid": "e834a4ac6ef754164c8e3f0be4f34531b74b768199ffb244ab9f6cb1bbc7465a", + "walletconflicts": [ + ], + "time": 1513204730, + "timereceived": 1513204730, + "bip125-replaceable": "unknown", + "details": [ + { + "account": "", + "address": "mjtN3C97kuWMgeBbxdB7hG1bjz24Grx2vA", + "category": "send", + "amount": -15.10000000, + "label": "", + "vout": 1, + "fee": -0.00178800, + "abandoned": false + }, + { + "account": "", + "address": "mjtN3C97kuWMgeBbxdB7hG1bjz24Grx2vA", + "category": "receive", + "amount": 15.10000000, + "label": "", + "vout": 1 + } + ], + "hex": "020000000f00fe2c7b70b925d0d40011ce96f8991fee5aba9537bd1b6913b37c37b041a57c00000000494830450221009ad02bfeee2a49196a99811ace20e2e7fefd16d33d525884edbc64bf6e2b1db502200b94f4000556391b0998932edde3033ba2517733c7ddffb87d91f6b756629fe201feffffff06a9301a2b39875b68f8058b8e2ad0b658f505e44a67e1e1d039140ae186ed1f0000000049483045022100c65cd13a85af6fcfba74d2852276a37076c89a7642429aa111b7986eea7fd6c7022012bbcb633d392ed469d5befda8df0a6b96e1acfa342f559877edebc2af7cb93401feffffff434b6f67e5e068401553e89f739a3edc667504597f29feb8edafc2b081cc32d90000000049483045022100b86ecc43e602180c787c36465da7fc8d1e8bfba23d6f49c37190c20889f2dfa0022032c3aec3ceefbb7a33c040ef19090cacbfd6bc9c5cd8e94252eb864891c6f34501feffffff4c65b43f8568ce58fc4c55d24ba0742e9878a031fdfae0fadac7247f42cc1f8e0000000049483045022100d055acfce852259dde051dc61792f94277d094c5da96752f925582b8e739868f02205e69add76e6b001073ad6b7df5f32a681fc8513ee0f6e126ee1c2d45149bd91d01feffffff5a72d60b58300974c5d4731e29b437ea61b87b6733bb3ca6ce5548ef8887d05b0000000049483045022100a7f5b2ee656a5a904fb27f982210de6858dfb165777ec969a77ea1c2c82975a4022001a1a563dbc3714047ec855f7aee901e756b851e255f35435e85c2ba7b0abd8401feffffff60d68e9d5650d55bc9e0b2a65ed27a3b9bceac4955760aa1560408854c3b148d000000004948304502210081a6f0c8232c52f3eaca825965077e88b816e503834989be4afb3f44f87eb98202207ae8becb99efe379fb269f477e7bb70d117dcb83e106c53b7addaa9715029da101feffffff63e2239425aad544f6e1157d5ee245d2500d4e9e9daf8049e0a38add6246da890000000049483045022100e0ab1752e8fbb244b63f7dd5649f2222e0dc42fae293b758e0c28082f77560b60220013f72fbe50acf4af197890b4d18fa89094055ed66f9226a6b461cc4ff560f8e01feffffff6aad4151087f4209ace714193dd64f770305dfb89470b79cca538b88253fbbef0000000049483045022100fee4a5f7ec6e8b55bd6aa0e93b5399af724039171d998b926e8095b70953d5f202203db0d4ef9d1bd57aeff0fe3d47d4358ec0559135dac8107507741eef0638279201feffffff7ddbca5854e25e6a2dfeacfe5828267cd1ef5d86e1da573fe2c2b21b45ecd6ce0000000049483045022100bf45241525592df4625642972dbc940ef74771139dd844bc6a9517197d01488c02203c99ca98892cc2693e8fbb9a600962eec84494fb8596acf0d670822624e497c901feffffff8672949de559e76601684c4ac3731599fd965d0c412e7df9f8ec16038d4420a60000000049483045022100b5a9bd3c6718c6bd2a8300bbd1d9de0ff1c5d02aeb6a659c52bb88958e7e3b0302207f710db1ef975c22edf54e063169aae31bbe470166cc0e5c34fd27b730b8e7d001feffffff8e006b0bb8cef2c5c2a11c8c2aa7d3ba01cb4386c7f780c45bc1014142b425f00000000048473044022046dc9db8daeb09b7c0b9f48013c8af2d0a71f688adaa8d91b40891768c852d4a02204fa15da6d58851191344a56c63bf51a540ec03f73117a3446230bb58a8a4bcce01feffffffbad05b8f86182b9b7c9c5aaa9ce3dc8d08a76848e49a2d9b8dcfb0f764bb26ca000000004847304402200682379dc36cb486309eac4913f41ac19638525677edad45ca8d9a2b0728b12f02203fb44f8a46cbc4c02f5699d7d4d9cd810bdf7e7c981b421218ccbcb7b73845f501feffffffd35228fe9ef0a742eacffc4a13f15ed7ba23854e6cb49d5010810ac11b5bdf690000000048473044022030045b882500808bd707f4654becc63de070818c82716310d39576decdd724e3022034d3b41cb5e939f0011bb5251be7941b6077fde5f4eff59afd8e49a2844288f701fefffffff5ae4cbd4ae8d68b5a34be3231cdc88b660447175f39cf7a86397f37641d4aa70000000049483045022100afe16f0de96a8629d6148f93520d690f30126c37e7f7f05300745a1273d7eb7202200933f6b371c4ea522570f3ec2aee9be2b59730b634e828f543bcdb019cf4749901fefffffff633f61ac61683221cc3d2665cf4bcf193af1c8ffe9d3d756ba83cc5eb7643250000000049483045022100ef0b8853c94d60634eff2fc1d4d75872aacb0a2d3242308b7ee256b24739c614022069fe9be8288bdd635871c263c46be710c001729d43f6fbc1350ed1a693c4646301feffffff0250780000000000001976a91464ed7fb2fe0b06f4cad0d731b122222e3e91088a88ac80c5005a000000001976a9142fed0f02d008f89f6a874168e506e2d4f9bcbfb888acd32b0000" +} +``` + +After creating a transaction, it has to be confirmed and recorded in the Blockchain, the transaction has to be included in a block. +Most of the applications require 6 block confirmations to consider the transaction as irreversible. If that is your case, you can mine additional 6 blocks into your Regtest chain: +``` +$ bitcoin-cli -regtest generate 6 +[ + "33549b2aa249f0a814db4a2ba102194881c14a2ac041c23dcc463b9e4e128e9f", + "2cc5c2012e2cacf118f9db4cdd79582735257f0ec564418867d6821edb55715e", + "128aaa99e7149a520080d90fa989c62caeda11b7d06ed1965e3fa7c76fa1d407", + "6037cc562d97eb3984cca50d8c37c7c19bae8d79b8232b92bec6dcc9708104d3", + "2cb276f5ed251bf629dd52fd108163703473f57c24eac94e169514ce04899581", + "57193ba8fd2761abf4a5ebcb4ed1a9ec2e873d67485a7cb41e75e13c65928bf3" +] +``` From 9a2017e03157d6ed0227f7ca065a25881117a3c8 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 15:02:36 -0800 Subject: [PATCH 32/38] Improvements --- 15_3_Testing_with_Regtest.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/15_3_Testing_with_Regtest.md b/15_3_Testing_with_Regtest.md index 1b9b750..5ee14d9 100644 --- a/15_3_Testing_with_Regtest.md +++ b/15_3_Testing_with_Regtest.md @@ -10,8 +10,9 @@ This document explains how to test a Regtest (Regression Test). After [mining blocks](15_2_Mining_with_Regtest.md) and getting the rewards, you can verify the balance on your wallet: ``` $ bitcoin-cli -regtest getbalance - +50.00000000 ``` +This will print the balance in your wallet. ## Testing 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. From 387cf88f17f2788fcec5acb133cdc3f7edf2d752 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 19:25:59 -0800 Subject: [PATCH 33/38] What's next on 15.2 Mining --- 15_2_Mining_with_Regtest.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/15_2_Mining_with_Regtest.md b/15_2_Mining_with_Regtest.md index 885e4e0..c8aea1d 100644 --- a/15_2_Mining_with_Regtest.md +++ b/15_2_Mining_with_Regtest.md @@ -26,3 +26,8 @@ This command will generate 101 blocks using a special RPC which is only availabl 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. However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. + + +## 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). From 3fc81a9d57e17c634cbaadf879d5ce9341deacfa Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 22:07:06 -0800 Subject: [PATCH 34/38] Add bitcointest --- 15_3_Testing_with_Regtest.md | 64 +++++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/15_3_Testing_with_Regtest.md b/15_3_Testing_with_Regtest.md index 5ee14d9..83d1fb2 100644 --- a/15_3_Testing_with_Regtest.md +++ b/15_3_Testing_with_Regtest.md @@ -14,7 +14,7 @@ $ bitcoin-cli -regtest getbalance ``` This will print the balance in your wallet. -## Testing the Regtest +## 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. @@ -76,3 +76,65 @@ $ bitcoin-cli -regtest generate 6 "57193ba8fd2761abf4a5ebcb4ed1a9ec2e873d67485a7cb41e75e13c65928bf3" ] ``` + + +## Testing with Regtest + +When you are in the Regtest mode, 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. + +First of all, you need to install Node.js, and use the NPM (Node Package Manager) to install `bitcointest`: +``` +$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - +$ sudo apt-get install -y nodejs +$ npm install -g bitcointest +``` + +After installing `bitcointest`, you can create the `test.js` file with the following content: +``` +$ nano test.js +const { BitcoinNet, BitcoinGraph } = require('bitcointest'); +net = new BitcoinNet('/usr/local/bin', '/tmp/bitcointest/', 22001, 22002); +graph = new BitcoinGraph(net); + +try { + + console.log('Launching nodes...'); + + const nodes = net.launchBatchS(4); + const [ n1, n2 ] = nodes; + net.waitForNodesS(nodes, 20000); + + console.log('Connected!'); + const blocks = n1.generateBlocksS(110); + console.info('Generated 110 blocks'); + + console.log(`n2.balance (before) = ${n2.getBalanceS()}`); + + const sometxid = n1.sendToNodeS(n2, 100); + console.log(`Generated transaction = ${sometxid}`); + n1.generateBlocksS(110); + n2.waitForBalanceChangeS(0); + + const sometx = n2.getTransactionS(sometxid); + console.log(`n2.balance (after) = ${n2.getBalanceS()}`); + + +} catch (e) { + console.error(e); + net.shutdownS(); + throw e; +} +``` + +When running `node test.js`, the command outputs: +``` +$ node test.js +Launching nodes... +Connected! +Generated 110 blocks +n2.balance (before) = 0 +Generated transaction = 91e0040c26fc18312efb80bad6ec3b00202a83465872ecf495c392a0b6afce35 +n2.after (before) = 100 + +``` From f5bc93b8668bd9806ca3e22e62008c02c8546ae4 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 13 Dec 2017 22:23:55 -0800 Subject: [PATCH 35/38] Use javascript lang on the snippet --- 15_3_Testing_with_Regtest.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/15_3_Testing_with_Regtest.md b/15_3_Testing_with_Regtest.md index 83d1fb2..669a14d 100644 --- a/15_3_Testing_with_Regtest.md +++ b/15_3_Testing_with_Regtest.md @@ -93,6 +93,8 @@ $ npm install -g bitcointest After installing `bitcointest`, you can create the `test.js` file with the following content: ``` $ nano test.js +``` +```javascript const { BitcoinNet, BitcoinGraph } = require('bitcointest'); net = new BitcoinNet('/usr/local/bin', '/tmp/bitcointest/', 22001, 22002); graph = new BitcoinGraph(net); From 15bfb254d9a3eac6128ebe593dd4b5f13c1b386d Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Thu, 14 Dec 2017 09:14:26 -0800 Subject: [PATCH 36/38] Improvements --- 15_0_Setting_Up_a_Bitcoin_Regtest.md | 4 ++-- ..._the_Regtest.md => 15_1_Starting_the_Regtest.md | 10 +++++----- 15_2_Mining_with_Regtest.md | 11 ++++++----- 15_3_Testing_with_Regtest.md | 14 +++++++------- README.md | 2 +- 5 files changed, 21 insertions(+), 20 deletions(-) rename 15_1_Building_the_Regtest.md => 15_1_Starting_the_Regtest.md (65%) diff --git a/15_0_Setting_Up_a_Bitcoin_Regtest.md b/15_0_Setting_Up_a_Bitcoin_Regtest.md index aa2590b..ad47a12 100644 --- a/15_0_Setting_Up_a_Bitcoin_Regtest.md +++ b/15_0_Setting_Up_a_Bitcoin_Regtest.md @@ -8,11 +8,11 @@ You can create a Blockchain from scratch using the Regtest, with one main advant After working through this chapter, a developer will be able to: * Create your own Blockchain from scratch - * Create the Genesis block and more blocks on top of it + * Generate/mine blocks and get the rewards * Get balance and interact with Bitcoind in a private way ## Table of Contents - * [Section One: Building the Regtest](15_1_Building_the_Regtest.md) + * [Section One: Starting the Regtest](15_1_Starting_the_Regtest.md) * [Section Two: Mining with Regtest](15_2_Mining_with_Regtest.md) * [Section Three: Testing with Regtest](15_3_Testing_with_Regtest.md) diff --git a/15_1_Building_the_Regtest.md b/15_1_Starting_the_Regtest.md similarity index 65% rename from 15_1_Building_the_Regtest.md rename to 15_1_Starting_the_Regtest.md index ee57f5f..28f7c8c 100644 --- a/15_1_Building_the_Regtest.md +++ b/15_1_Starting_the_Regtest.md @@ -1,13 +1,13 @@ -# 15.1: Building the Regtest +# 15.1: Starting the Regtest > **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. Bitcoin Core’s regression test mode (regtest mode) lets you instantly create a brand-new private block chain with the same basic rules as testnet—but one major difference: you choose when to create new blocks, so you have complete control over the environment. -## Starting Bitcoind in Regtest Mode +## Starting Bitcoind on Regtest -After [setting up your Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md), you are now able to use the Regtest mode. To start Bitcoind (Bitcoin Daemon) in Regtest mode and create a private Blockchain, you have to use the following command: +After [setting up your Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md), you are now able to use Regtest. To start Bitcoind (Bitcoin Daemon) on Regtest and create a private Blockchain, you have to use the following command: ``` $ bitcoind -regtest -daemon ``` @@ -20,12 +20,12 @@ user@mybtc:~/.bitcoin# ls bitcoin.conf regtest testnet3 ``` -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: +If you want to start a brand new Blockchain using regtest, all you have to do is delete the `regtest` folder and restart the Bitcoind: ``` $ rm -rf regtest ``` ## 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). +After starting your bitcoind on regtest, you can now use RPC commands to [generate/mine blocks in your private chain](15_2_Mining_with_Regtest.md). This will allow you to get balance in your wallet and [test the Regtest blockchain](15_3_Testing_with_Regtest.md). diff --git a/15_2_Mining_with_Regtest.md b/15_2_Mining_with_Regtest.md index c8aea1d..b07814f 100644 --- a/15_2_Mining_with_Regtest.md +++ b/15_2_Mining_with_Regtest.md @@ -3,12 +3,12 @@ > **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. +To generate blocks on a new blockchain requires very minimal proof-of-work and it will take less than a second, due to the low difficulty and that it follows the Testnet rules. ## 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: +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: ``` $ bitcoin-cli -regtest generate 101 [ @@ -22,12 +22,13 @@ $ bitcoin-cli -regtest generate 101 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. +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. -Unlike mainnet, in regtest mode only the first 150 blocks pay a reward of 50 bitcoins. +Unlike mainnet, in regtest mode only the first 150 blocks pay a reward of 50 bitcoins. After that, the reward halves after 150 blocks, so it pays 25, 12.5, and so on... + However, a block must have 100 confirmations before that reward can be spent, so we generate 101 blocks to get access to the coinbase transaction from block #1. ## 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 your bitcoind on regtest and generating the first blocks, you have balance in your address to spend and [test using Regtest blockchain](15_3_Testing_with_Regtest.md). diff --git a/15_3_Testing_with_Regtest.md b/15_3_Testing_with_Regtest.md index 669a14d..954771a 100644 --- a/15_3_Testing_with_Regtest.md +++ b/15_3_Testing_with_Regtest.md @@ -2,7 +2,7 @@ > **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 test a Regtest (Regression Test). +This document explains how to test transactions and situations using regtest (regression test). ## Verifying balance @@ -80,7 +80,7 @@ $ bitcoin-cli -regtest generate 6 ## Testing with Regtest -When you are in the Regtest mode, you are able to simulate edge cases and attacks that might happen in the real world, such as Double Spend. +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. First of all, you need to install Node.js, and use the NPM (Node Package Manager) to install `bitcointest`: @@ -96,8 +96,8 @@ $ nano test.js ``` ```javascript const { BitcoinNet, BitcoinGraph } = require('bitcointest'); -net = new BitcoinNet('/usr/local/bin', '/tmp/bitcointest/', 22001, 22002); -graph = new BitcoinGraph(net); +const net = new BitcoinNet('/usr/local/bin', '/tmp/bitcointest/', 22001, 22002); +const graph = new BitcoinGraph(net); try { @@ -123,9 +123,9 @@ try { } catch (e) { - console.error(e); - net.shutdownS(); - throw e; + console.error(e); + net.shutdownS(); + throw e; } ``` diff --git a/README.md b/README.md index 675e2de..3acf7b7 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ Add: HOW TO DO A REFUND (short answer: ask!) ** PART FIVE: BITCOIN FUTURES ** * [15.0: Setting Up a Bitcoin Regtest](15_0_Setting_Up_a_Bitcoin_Regtest.md) - * [15.1: Building the Regtest](15_1_Building_the_Regtest.md) + * [15.1: Starting the Regtest](15_1_Starting_the_Regtest.md) * [15.2: Mining with Regtest](15_2_Mining_with_Regtest.md) * [15.3: Testing with Regtest](15_3_Testing_with_Regtest.md) From ed9364cfd2a01387c338ee86b6a5a0b8ebeac446 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 27 Dec 2017 10:30:25 -0800 Subject: [PATCH 37/38] add Java installation details and reference to sample project --- 12_7_Accessing_Bitcoind_with_Java.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md index 037118b..8547e20 100644 --- a/12_7_Accessing_Bitcoind_with_Java.md +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -4,6 +4,23 @@ Interacting with the `bitcoind` directly and using command-line `curl` can get simple if you understand how it works, but there's a project [JavaBitcoindRpcClient](https://github.com/Polve/JavaBitcoindRpcClient) that provides the functionality in a Java-API level, making it even easier to interact with your Bitcoin Server. + +## Setup Java + +To install Java on the VPS Server, you are able to use the `apt-get` command. We will also use [Apache Maven](http://maven.apache.org/) to manage the dependencies, so we will install it together. + +``` +$ apt-get install openjdk-9-jre-headless maven +``` + +You can verify your Java installation: +``` +$ java -version +openjdk version "9-internal" +OpenJDK Runtime Environment (build 9-internal+0-2016-04-14-195246.buildd.src) +OpenJDK 64-Bit Server VM (build 9-internal+0-2016-04-14-195246.buildd.src, mixed mode) +``` + ## Setup Dependency If you use Maven in your Java project, you can include the dependency: @@ -20,6 +37,8 @@ Or if you use Gradle: compile 'wf.bitcoin:JavaBitcoindRpcClient:0.9.13' ``` +If you want a sample project and some instructions on how to run it on the server that we just created, you can refer to the [Bitcoind Java Sample Project](https://github.com/brunocvcunha/bitcoind-java-client-sample/). + ### Build Your Connection To use `JavaBitcoindRpcClient`, you need to create a `BitcoindRpcClient` instance. The arguments in the URL are username, password, IP address and port. You should know this information from your work with `curl` . As you'll recall, the IP address 127.0.0.1 and port 18332 should be correct for the standard testnet setup described in this documents, while you can extract the user and password from `~/.bitcoin/bitcoin.conf`. From 6769d441660a5cc251da892a3f37587f335c3c72 Mon Sep 17 00:00:00 2001 From: Bruno Volpato Date: Wed, 27 Dec 2017 10:35:49 -0800 Subject: [PATCH 38/38] adding more details to the commands --- 12_7_Accessing_Bitcoind_with_Java.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/12_7_Accessing_Bitcoind_with_Java.md b/12_7_Accessing_Bitcoind_with_Java.md index 8547e20..7d41b04 100644 --- a/12_7_Accessing_Bitcoind_with_Java.md +++ b/12_7_Accessing_Bitcoind_with_Java.md @@ -58,9 +58,9 @@ rpcClient.stop(); ### Making your first RPC Call -In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcoin-cli` or `curl`. +In order to use an RPC method using `JavaBitcoindRpcClient`, you'll find that the `BitcoindRpcClient` provides most of the functionality that can be accessed through `bitcoin-cli` or `curl`, using the same method names. For more details about the commands that you are able to execute and what to expect back, you should refer to [3.2: Knowing Your Bitcoin Setup](03_2_Knowing_Your_Bitcoin_Setup.md). -For example, to execute the `getmininginfo`, you should use the `getMiningInfo()` method: +For example, to execute the `getmininginfo` command to get the block information and the difficulty on the network, you should use the `getMiningInfo()` method: ```java MiningInfo info = rpcClient.getMiningInfo(); System.out.println("Mining Information"); @@ -82,7 +82,9 @@ Hash Power.: 6585163152453.466796875 ### Creating an Address -You can create a new address attaching a specific label to it, as well as dump the private key for a specific address: +You can create a new address on your wallet attaching a specific label to it, as well as dump the private key for a specific address. +For more information about the wallet setup, you can check [3.3: Setting Up Your Wallet](03_3_Setting_Up_Your_Wallet.md). + ```java String address = rpcClient.getNewAddress("Learning-Bitcoin-from-the-Command-Line"); System.out.println("New Address: " + address); @@ -101,6 +103,8 @@ Priv Key: cTy2AnmAALsHokYzJzTdsUBSqBtypmWfmSNYgG6qQH43euUZgqic ### Sending Transactions You can easily send a transaction using the method `sendToAddress()`. +For more information about sending transactions, you can check [4: Sending Bitcoin Transactions](04_0_Sending_Bitcoin_Transactions.md). + ```java String sendToAddress = rpcClient.sendToAddress("mgnNsZj6tPzpd7JwTTidUKnGoDTkcucLT5", 1);