Grokking Bitcoin

Because the communication with bitcoind happens through HTTP, any program that can send HTTP POST requests, such as the command-line tool curl, can be used to communicate with bitcoind. But to use tools other than bitcoin-cli, you need to set up a username and password to use as authentication to the web server.

Stop the node with ./bitcoin-cli stop. Open—or create, if it doesn’t exist—Bitcoin Core’s configuration file ~/.bitcoin/bitcoin.conf, and add these lines:

After you’ve modified and saved the ~/.bitcoin/bitcoin.conf file, start your node using ./bitcoind -daemon, to make the changes effective.

Here’s how I called getblockhash using curl (the backslash \ character means the command continues on the next line):

Remember to change the username from kalle to the username you configured in bitcoin.conf.

This command will prompt you for the password. Enter the password, and press Enter. The reply from the web server will be the same as when you used bitcoin-cli, but you’ll need to scan through the response body to spot the result, which is the hash of block 0.

When bitcoind (or bitcoin-qt) starts, it will automatically create a wallet for you and store it in the file ~/.bitcoin/wallet.dat. But this wallet isn’t encrypted, which means its private keys and its seed, used to derive key pairs as discussed in [ch04], are stored in the clear on your hard drive. Let’s look at some data for such a wallet:

The output from the getwalletinfo command shows various information about the wallet currently being used. This automatically created wallet is unnamed, which is why walletname is empty.

balance is how many confirmed bitcoins you have (including unconfirmed outgoing transactions), and unconfirmed_balance is the sum of incoming unconfirmed payments. immature_balance is relevant only for miners and denotes the number of newly created bitcoins, which can’t be spent until after 100 blocks passed. Refer to the help section on getwalletinfo for more details about the output.

To create an encrypted wallet, you need to create a new wallet using the command encryptwallet:

This command creates a new encrypted wallet. The -stdin option is used to read the password argument from standard input, which in this case means you type the password in your terminal window after starting the command. End your input by pressing Enter and Ctrl-D. The reason for using -stdin is that you don’t want the password to be written in the command itself, because most shell interpreters, such as bash, keep a history of commands in a file. The -stdin option ensures that the password doesn’t end up in any such history files.

It’s important to create a new encrypted wallet instead of just encrypting the existing wallet, because the old wallet might already have been compromised on your hard drive. As noted by the output, bitcoind has stopped. Bitcoin Core can’t currently switch to a new wallet file while running.

Let’s start bitcoind again and look at the wallet. You’ll see something similar to this:

Your old, unencrypted wallet.dat has been overwritten by the new, encrypted wallet.dat. For safety, however, your old seed is kept in the new encrypted wallet, in case you had actual funds in the old wallet or accidentally receive funds to that old wallet in the future. The unlocked_until value of 0 means your private keys are encrypted with the password you entered when you encrypted your wallet. From now on, you need to decrypt your private keys to access them. You’ll do that when you send bitcoin later.

You’ve created an encrypted wallet, and before you start using it, you need to back it up. In [ch04], we talked about mnemonic sentences, as defined in BIP39, which made backing up hierarchical deterministic (HD) wallet seeds simple. But this feature is not implemented in Bitcoin Core, for a few reasons—mainly, that the mnemonic sentence lacks information about the following:

To back up your Bitcoin Core wallet, you need to make a copy of the wallet.dat file. Be careful not to copy the file using your operating system’s copy facilities while bitcoind or bitcoin-qt is running. If you do this, your backup might be in an inconsistent state because bitcoind might be writing data to it while you copy. To make sure you get a consistent copy of the file while Bitcoin Core is running, run the following command:

This will instruct bitcoind to save a copy of the wallet file to walletbackup.dat in your home directory (you can change the name and path of the file to anything you like). The backup file will be an exact copy of the original wallet.dat file. Move the walletbackup.dat file to a safe place—for example, a USB memory stick in a bank safe-deposit box or on a computer at your brother’s apartment.

You’ve created an encrypted, backed-up wallet. Great! Let’s put some bitcoins into it. To do this, you need a Bitcoin address to receive the bitcoins to, so let’s get one:

This command creates a bech32 p2wpkh address for you. If you prefer another type of address, you can change bech32 to legacy to get a p2pkh address or to p2sh-segwit to get a p2wpkh nested in p2sh address. Head back to the [recap-of-payment-types] to refresh your memory on the different payment and address types.

Now, let’s send bitcoin to that address. Be careful not to send money to the address printed in this book (although I’ll happily accept it), but rather to an address you generate yourself with your own full node wallet.

This raises the question of how to get bitcoins to send to your wallet. You can get bitcoins in several ways:

I’ll leave it up to you how you obtain bitcoins and assume that you somehow will get bitcoins into the address you created previously.

I made a payment to my new address and then checked my wallet:

This shows a pending incoming payment of 5 mBTC (0.005 BTC). I now have to wait until it’s confirmed in the blockchain. Meanwhile, you can dig into the transaction by running the listtransactions command. Here are my results:

This transaction has 0 confirmations and pays 0.005 BTC. You can also see that this transaction’s txid is ebfd0d14…ba45c195.

Let’s take a closer look at the transaction using the command getrawtransaction:

This command prints the entire transaction in a human-readable (well, at least developer-readable) form. Let’s start from the top and go through the most relevant parts of this transaction. The txid is the transaction id. The hash is the double SHA256 hash of the whole transaction, including the witness. For non-segwit transactions, hash is equal to txid.

The size of the transaction is 223 bytes, and vsize (the virtual size) is also 223 vbytes; vsize is the transaction’s number of weight units (892) divided by 4, so the virtual size of a non-segwit transaction (which this is, because it only spends non-segwit outputs) is equal to its actual size.

The locktime of this transaction is set to 549655, which was the height of the strongest chain at the time of the transaction’s creation. Thus the transaction can’t be mined until block height 549656. This reduces the attractiveness of an attack in which a miner deliberately tries to reorg the blockchain and include the transaction into a block height that’s already been mined.

Next comes the list of inputs. This transaction has a single input that spends output at index 0 (vout) of the transaction with txid 8a4023db…909ab22f. The input spends a p2pkh output.

The input’s sequence number is 4294967293, which is fffffffd in hex code. This means the lock time is enabled (≤fffffffe) and the transaction is replaceable (≤fffffffd) according to BIP125. The meaning of the sequence number was summarized in [tab0901].

After the list of inputs comes the list of transaction outputs. This transaction has a list of two outputs. The first pays 0.00313955 BTC to a p2pkh address you haven’t seen before. This is probably a change output. The second output sends 0.005 BTC to the p2wpkh address created earlier.

Let’s see if the transaction is confirmed yet. You can check, for example, with getbalance. In my case, if it shows 0.00500000, then the transaction has confirmed:

Cool, the money is confirmed! Let’s move on.

You’ve received some bitcoins. Now, you want to send bitcoins to someone else. To send bitcoins, you can use the sendtoaddress command. You need to make a few decisions first:

I’ll send the bitcoins to address bc1qu456…5t7uulqm, but you should get another address to send to. If you have no other wallet, you can create a new address in Bitcoin Core to send to just for experimental purposes. I’ve obfuscated my address below so that you don’t send to my address by mistake.

Oh, dear! An error. As indicated by the error message, the private keys are encrypted in the wallet.dat file. Bitcoin Core needs the private keys to sign the transaction. To make the private keys accessible, you need to decrypt them. You do this using the walletpassphrase command with the -stdin option to prevent the passphrase from being stored by your command-line interpreter, such as bash:

The last argument, 300, is the number of seconds you should keep the wallet unlocked. After 300 seconds, the wallet will be automatically locked again in case you forget to lock it manually. Let’s retry the sendtoaddress command:

The command output a txid for the newly created transaction. This means it went well. You can relock the wallet using the walletlock command:

The wallet is now locked. I’ll list my transactions again:

The new transaction is the last one of the two. It isn’t yet confirmed, as indicated by "confirmations": 0. The fee paid was 141 satoshis. Let’s look into this transaction in detail:

The first thing to note is that txid and hash differ. That’s because this is a segwit transaction. As you may recall from [ch10], the witness isn’t included in the txid—that’s how you avoid transaction malleability—but the hash in the output includes it. Note that size and vsize differ, too, which is expected from a segwit transaction. The fee was 141 satoshis, as shown by the listtransactions command, and the vsize was 141 vbytes. The fee rate was thus selected by Bitcoin Core to be 1 sat/vbyte.

The transaction has a single input that spends output 1 of transaction ebfd0d14…ba45c195. You should recognize this output from the section where I paid 0.005 BTC to my Bitcoin Core wallet. Because that output was a p2wpkh output, the signature script (scriptSig) is empty, and the txinwitness contains the signature and pubkey.

The sequence number of the input is 4294967294, which equals fffffffe. This means the transaction has lock time enabled but isn’t replaceable using BIP125 (opt-in replace-by-fee).

I have two outputs. The first is the change of 0.00399859 BTC back to an address I own. The other is the actual payment of 0.001 BTC. Let’s check the balance again:

Yep, there it is. I didn’t have to wait for confirmation to see the new balance, because getbalance always includes my own outgoing unconfirmed transactions. I’ve spent my only UTXO (of 0.005 BTC) and created a new UTXO of 0.00399859 to myself:

It sums up perfectly.

I’ve shown a few commands you can use to wing your Bitcoin Core node, but there’s a lot more to it. Explore ./bitcoin-cli help to find out more.