mirror of
https://github.com/ChristopherA/Learning-Bitcoin-from-the-Command-Line.git
synced 2026-04-12 16:12:55 +00:00
Compare commits
46 Commits
ca6b408c59
...
c02a2cbbec
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c02a2cbbec | ||
|
|
ba558162d2 | ||
|
|
569554580d | ||
|
|
10e837a254 | ||
|
|
3327552250 | ||
|
|
d31cc600ab | ||
|
|
2b82d54cb5 | ||
|
|
f277a9a2df | ||
|
|
9cdf11ecc2 | ||
|
|
c9c2c76f45 | ||
|
|
ad24d98468 | ||
|
|
69ab579acc | ||
|
|
6c1eb3ddac | ||
|
|
c821d7f315 | ||
|
|
466794f2bf | ||
|
|
47f0e71f67 | ||
|
|
ef2da3c025 | ||
|
|
1314235bdb | ||
|
|
058284ed75 | ||
|
|
6683069377 | ||
|
|
a0ba2a8221 | ||
|
|
698e66e5c7 | ||
|
|
1449427cf0 | ||
|
|
374d3b5414 | ||
|
|
f5b09062a8 | ||
|
|
0b6e72058f | ||
|
|
6893a3132c | ||
|
|
9423d4db07 | ||
|
|
8e76dd5aa2 | ||
|
|
32338740b2 | ||
|
|
8dea915dc5 | ||
|
|
7ec069c5d8 | ||
|
|
892918aad6 | ||
|
|
d35a85298d | ||
|
|
e06dd12c82 | ||
|
|
19eb2254e7 | ||
|
|
6fb82be1da | ||
|
|
fd3fc049ba | ||
|
|
138265d851 | ||
|
|
a5c99ea924 | ||
|
|
a333af6732 | ||
|
|
9b907565b2 | ||
|
|
493f5d85e3 | ||
|
|
564e15b02f | ||
|
|
adb8f99b22 | ||
|
|
84f66056c7 |
@ -4,20 +4,18 @@
|
||||
|
||||
The ways that we make payments for goods and services has been changing dramatically over the last several decades. Where once all transactions were conducted through cash or checks, now various electronic payment methods are the norm. However, most of these electronic payments still occur through centralized systems, where credit card companies, banks, or even internet-based financial institutions like Paypal keep long, individually correlated lists of transactions and have the power to censor transactions that they don't like.
|
||||
|
||||
These centralization risks were some of the prime catalysts behind the creation of cryptocurrencies, the first and most successful of which is Bitcoin. Bitcoin offers pseudonymity; it makes it difficult to correlate transactions; and it makes censorship by individual entities all but impossible. These advantages have made it one of the quickest growing currencies in the world. That growth in turn has made Bitcoin into a going concern among entrepreneurs and developers, eager to create new services for the Bitcoin community.
|
||||
These centralization risks were some of the prime catalysts behind the creation of cryptocurrencies, the first and most successful of which is Bitcoin. Bitcoin offers pseudonymity; it makes it more difficult to correlate transactions; and it makes censorship by individual entities all but impossible. These advantages have made it one of the quickest growing currencies in the world. That growth in turn has made Bitcoin into a going concern among entrepreneurs and developers, eager to create new services for the Bitcoin community.
|
||||
|
||||
If you're one of those entrepreneurs or developers, then this course is for you, because it's all about learning to program Bitcoin. It's an introductory course that explains all the nuances and features of Bitcoin as it goes. It also takes a very specific tack, by offering lessons in how to work _directly_ with Bitcoin Core and with the core lightning server using their RPC interfaces.
|
||||
If you're one of those entrepreneurs or developers, then this course is for you, because it's all about learning to program Bitcoin. It's an introductory course that explains all the nuances and features of Bitcoin as it goes. It also takes a very specific tack, by offering lessons in how to work _directly_ with Bitcoin Core using its RPC interfaces.
|
||||
|
||||
Why not use some of the more fully featured libraries found in various programming languages? Why not create your own from scratch? It's because working with cryptocurrency is dangerous. There are no safety nets. If you accidentally overpay your fees or lose a signing key or create an invalid transaction or make any number of potential mistakes, then your cryptocurrency will be gone forever. Much of that responsibility will, of course, lie with you as a cryptocurrency programmer, but it can be minimized by working with the most robust, secure, and safe cryptocurrency interfaces around, the ones created by the cryptocurrency programming teams themselves: ``bitcoind`` and ``lightningd``.
|
||||
Why not use some of the more fully featured libraries found in various programming languages? That's because the goal here is to create a visceral, hands-on experience that makes it easy to begin directly working with `bitcoind`. By typing in the commands, seeing the results yourself, and perhaps even exploring them beyond the specific walls of this course, you should gain a deep and intuitive understanding of how Bitcoin works, and you should be able to do so without the rigamarole of having to program, compile, and run code. You probably won't be using the command line long-term, but we think it's perfect as a learning tool, which is why we've create a whole sequence of digital-asset and digital-identity courses around that precept.
|
||||
|
||||
Much of this book thus discusses how to script Bitcoin (and Lightning) directly from the command line. Some later chapters deal with more sophisticated programming languages, but again they continue to interact directly with the ``bitcoind`` and ``lightningd`` daemons by using RPC or by interacting with the files they create. This allows you to stand on the shoulders of giants and use their trusted technology to learn how to create your own trusted systems.
|
||||
Even if you later move beyond `bitcoin-cli`, we suggest you cleave to other well-tested programming libraries rather than rolling one from scratch. Sticking with `bitcoind` and its RPC interface offers a particularly stable (yet up to date) methodology for working with Bitcoin. That's important because working with cryptocurrency is dangerous. There are no safety nets. If you accidentally overpay your fees or lose a signing key or create an invalid transaction or make any number of potential mistakes, then your cryptocurrency will be gone forever. Much of that responsibility will, of course, lie with you as a cryptocurrency programmer, but it can be minimized by working with the most robust, secure, and safe cryptocurrency interfaces around.
|
||||
|
||||
## Required Skill Level
|
||||
|
||||
You do not need to be particularly technical for the majority of this course. All you need is the confidence to run basic commands on the UNIX command line. If you're familiar with things like `ssh`, `cd`, and `ls`, the course will supply you with the rest.
|
||||
|
||||
A minority of this course requires programming knowledge, and you should skip over those sections if needed, as discussed in the next section.
|
||||
|
||||
## Overview of Topics
|
||||
|
||||
This book is broadly divided into the following sections:
|
||||
@ -27,10 +25,13 @@ This book is broadly divided into the following sections:
|
||||
| **Part One: Preparing for Bitcoin** | Understanding the basics of Bitcoin and setting up a server for use. | Command Line |
|
||||
| **Part Two: Using Bitcoin-CLI** | Using the Bitcoin-CLI for creating transactions. | Command Line |
|
||||
| **Part Three: Bitcoin Scripting** | Expanding your Bitcoin work with scripts. | Programming Concepts |
|
||||
| **Part Four: Using Tor** | Improving your node security with Tor | Command Line |
|
||||
| **Part Four: Maintaing Privacy** | Improving privacy (and why it's important) | Command Line |
|
||||
| **Appendices** | Utilizing less common Bitcoin setups. | Command Line |
|
||||
|
||||
Other topics are currently included in the course but may be moved to parallel courses as time allows:
|
||||
|
||||
| **Part Five: Programming with RPC** | Accessing RPC from C and other languages. | Programming in C |
|
||||
| **Part Six: Using Lightning-CLI** | Using the Lightning-CLI for creating transactions. | Command Line |
|
||||
| **Appendices** | Utilizing less common Bitcoin setups. | Command Line |
|
||||
|
||||
## How To Use This Course
|
||||
|
||||
@ -39,11 +40,11 @@ So where do you start? This book is primarily intended to be read sequentially.
|
||||
If you have different levels of skill or want to learn different things, you might skip to different parts of the book:
|
||||
|
||||
* If you've already got a Bitcoin environment ready to be used, jump to [Chapter Three: Understanding Your Bitcoin Setup](03_0_Understanding_Your_Bitcoin_Setup.md).
|
||||
* If you only care about Bitcoin scripting, jump to [Chapter Nine: Introducing Bitcoin Scripts](09_0_Introducing_Bitcoin_Scripts.md).
|
||||
* If you just want to read about using programming languages, jump to [Chapter Sixteen: Talking to Bitcoin](16_0_Talking_to_Bitcoind.md).
|
||||
* If you conversely don't want to do any programming, definitely skip chapters 15-17 while you're reading, and perhaps skip chapters 9-13. The rest of the course should still make sense without them.
|
||||
* If you are only interested in Lightning, zap over to [Chapter Nineteen: Understanding Your Lightning Setup](19_0_Understanding_Your_Lightning_Setup.md).
|
||||
* If you want to read the major new content added for v2 of the course (2020), following on v1 (2017), read [§3.5: Understanding the Descriptor](03_5_Understanding_the_Descriptor.md), [§4.6: Creating a SegWit Transaction](04_6_Creating_a_Segwit_Transaction.md), [Chapter 7: Expanding Bitcoin with PSBTs](07_0_Expanding_Bitcoin_Transactions_PSBTs.md), [§9.5: Scripting a P2WPKH](09_5_Scripting_a_P2WPKH.md), [§10.5: Scripting a SegWit Script](10_5_Scripting_a_Segwit_Script.md), [Chapter 14: Using Tor](14_0_Using_Tor.md), [Chapter 15: Using i2p](15_0_Using_i2p.md), [Chapter 16: Talking to Bitcoind with C](16_0_Talking_to_Bitcoind.md), [Chapter 17: Programming with Libwally](17_0_Programming_with_Libwally.md), [Chapter 18: Talking to Bitcoind with Other Languages](18_0_Talking_to_Bitcoind_Other.md), [Chapter 19: Understanding Your Lighting Setup](19_0_Understanding_Your_Lightning_Setup.md), and [Chapter 20: Using Lightning](20_0_Using_Lightning.md).
|
||||
* If you only care about Bitcoin scripting, jump to [Chapter Eleven: Introducing Bitcoin Scripts](11_0_Introducing_Bitcoin_Scripts.md).
|
||||
* If you just want to read about using programming languages, jump to [Programming: Talking to Bitcoin](P1_0_Talking_to_Bitcoind.md).
|
||||
* If you conversely don't want to do any programming, definitely skip the programming section while you're reading, and perhaps skip chapters 11-15 on Bitcoin Script. The rest of the course should still make sense without them.
|
||||
* If you are only interested in Lightning, zap over to [Lightning: Understanding Your Lightning Setup](L1_0_Understanding_Your_Lightning_Setup.md).
|
||||
* If you want to read the major new content added for v3 of the course (2026), read [§3.4: Understanding the Descriptor](03_4_Understanding_the_Descriptor.md), [§3.5: Understanding the Address](03_5_Understanding_the_Address.md), [§3.6: Creating QR Codes for Addresses](03_6_Creating_QR_Codes_for_Addresses.md), [§4.6: Sending Coins to Other Addresses](04_6_Sending_Coins_to_Other_Addresses.md) ... [TBD]
|
||||
|
||||
## Why to Use this Course
|
||||
|
||||
@ -60,4 +61,4 @@ Obviously, you're working through this course because you're interested in Bitco
|
||||
|
||||
If you'd like a basic introduction to Bitcoin, public-key cryptography, ECC, blockchains, and Lightning, read the [Introducing Bitcoin](01_1_Introducing_Bitcoin.md) interlude.
|
||||
|
||||
Otherwise, if you're ready to dive into the course, go to [Setting Up a Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md).
|
||||
Otherwise, if you're ready to dive into the course, go to [Chapter Two: Setting Up a Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md).
|
||||
|
||||
@ -4,88 +4,86 @@ Before you can get started programming Bitcoin (and Lightning), you should have
|
||||
|
||||
## About Bitcoin
|
||||
|
||||
Bitcoin is a programmatic system that allows for the transfer of the bitcoin currency. It is enabled by a decentralized, peer-to-peer system of nodes, which include full nodes, wallets, and miners. Working together, they ensure that bitcoin transactions are fast and non-repudiable. Thanks to the decentralized nature of the system, these transactions are also censor-resistant and can provide other advantages such as pseudonymity and non-correlation if used well.
|
||||
Bitcoin is a programmatic system that allows for the transfer of the bitcoin currency. It is enabled by a decentralized, peer-to-peer system of nodes, which include full nodes, wallets, and miners. Working together, they ensure that bitcoin transactions are fast and non-repudiable. Thanks to the decentralized nature of the system, these transactions are also censorship-resistant and can provide other advantages such as pseudonymity and non-correlation if used well.
|
||||
|
||||
Obviously, Bitcoin is the heart of this book, but it's also the originator of many other systems, including blockchains and Lightning, which are both detailed in this tutorial, and many other cryptocurrencies such as Ethereum and Litecoin, which are not.
|
||||
|
||||
**_How Are Coins Transferred?_** Bitcoin currency isn't physical coins. Instead it's an endless series of ownership reassignments. When one person sends coins to another, that transfer is stored as a transaction. It's the transaction that actually records the ownership of the money, not any token local to the owner's wallet or their machine.
|
||||
> 📖 **_How are coins transferred?_** Bitcoin currency isn't physical coins. Instead it's an endless series of ownership reassignments. When one person sends coins to another, that transfer is stored as a transaction. It's the transaction that actually records the ownership of the money, not any token local to the owner's wallet or their machine.
|
||||
|
||||
**_Who Can You Send Coins To?_** The vast majority of bitcoin transactions involve coins being sent to individual people (or at least to individual Bitcoin addresses). However, more complex methodologies can be used to send bitcoins to groups of people or to scripts. These various methodologies have names like P2PKH, multisig, and P2SH.
|
||||
> 📖 **_Who can you send coins to?_** The vast majority of bitcoin transactions involve coins being sent to individual people (or at least to individual Bitcoin addresses). However, more complex methodologies can be used to send bitcoins to groups of people or to scripts. These various methodologies have names like P2WPKH, multisig, and P2SH. [§3.5](03_5_Understanding_the_Address.md) will cover many of the methodologies.
|
||||
|
||||
**_How Are Transactions Stored?_** Transactions are combined into larger blocks of data, which are then written to the blockchain ledger. A block is built in such a way that it cannot be replaced or rewritten once several blocks have been built atop (following) it. This is what makes bitcoins non-repudiable: the decentralized global ledger where everything is recorded is effectively a permanent and unchangeable database.
|
||||
> 📖 **_How are transactions stored?_** Transactions are combined into larger blocks of data, which are then written to the blockchain ledger. A block is built in such a way that it cannot be replaced or rewritten once several blocks have been built atop (following) it. This is what makes bitcoins non-repudiable: the decentralized global ledger where everything is recorded is effectively a permanent and unchangeable database. However, the process of building these blocks is stochastic: it's somewhat random, so you can never be assured that a transaction will be placed in a specific block. There can also be changes in blocks if they're very recent, but only if they're _very_ recent. That means that things only become non-repudiable (and permanent and unchangeable) after a little bit of time.
|
||||
|
||||
However, the process of building these blocks is stochastic: it's somewhat random, so you can never be assured that a transaction will be placed in a specific block. There can also be changes in blocks if they're very recent, but only if they're _very_ recent. So, things become non-repudiable (and permanent and unchangeable) after a little bit of time.
|
||||
> 📖 **_How are transactions protected?_** The funds contained in a Bitcoin transaction are locked with a cryptographic puzzle. These puzzles are designed so that they can be easily solved by the person who the funds were sent to. This is done using the power of public-key cryptography. Technically, a transaction is protected by a signature that proves you're the owner of the public key that a transaction was sent to: this proof of ownership is the puzzle that's being solved. Funds are further protected by the use of hashes. Public keys aren't actually stored in the blockchain until the funds are spent: only public-key hashes are. This means that even if quantum computer were to come along, Bitcoin transactions would remain protected by this second level of cryptography.
|
||||
|
||||
**_How Are Transactions Protected?_** The funds contained in a Bitcoin transaction are locked with a cryptographic puzzle. These puzzles are designed so that they can be easily solved by the person who the funds were sent to. This is done using the power of public-key cryptography. Technically, a transaction is protected by a signature that proves you're the owner of the public key that a transaction was sent to: this proof of ownership is the puzzle that's being solved.
|
||||
|
||||
Funds are further protected by the use of hashes. Public keys aren't actually stored in the blockchain until the funds are spent: only public-key hashes are. This means that even if quantum computer were to come along, Bitcoin transactions would remain protected by this second level of cryptography.
|
||||
|
||||
**_How Are Transactions Created?_** The heart of each Bitcoin transaction is a FORTH-like scripting language that is used to lock the transaction. To respend the money, the recipient provides specific information to the script that proves he's the intended recipient.
|
||||
|
||||
However, these Bitcoin scripts are the lowest level of Bitcoin functionality. Much Bitcoin work is done through the `bitcoind` Bitcoin daemon, which is controlled through RPC commands. Many people send those RPC commands through the `bitcoin-cli` program, which provides an even simpler interface. Non-programmers don't even worry about these minutia, but instead use programmed wallets with simpler interfaces.
|
||||
> 📖 **_How are transactions created?_** The heart of each Bitcoin transaction is a FORTH-like scripting language that is used to lock the transaction. To respend the money, the recipient provides specific information to the script that proves he's the intended recipient. However, these Bitcoin scripts are the lowest level of Bitcoin functionality. Much Bitcoin work is done through the `bitcoind` Bitcoin daemon, which is controlled through RPC commands. Many people send those RPC commands through the `bitcoin-cli` program, which provides an even simpler interface. Non-programmers don't even worry about these minutia, but instead use programmed wallets with simpler interfaces.
|
||||
|
||||
### Bitcoin — In Short
|
||||
|
||||
One way to think of Bitcoin is as _a sequence of atomic transactions_. Each transaction is authenticated by a sender with the solution to a previous cryptographic puzzle that was stored as a script. The new transaction is locked for the recipient with a new cryptographic puzzle that is also stored as a script. Every transaction is recorded in an immutable global ledger.
|
||||
|
||||
> 🔥 ***What is the power of Bitcoin?*** Bitcoin allows for the creation of pseudonymous identifiers (addresses based on the hashes of public keys) that can be used to transfer digital currency. It supports the right to transact through a reduction in potential censorship and coercion. That makes it particularly important in places where centralized authorities are not trusted to take on these responsibilities, whether that's due to a corrupt government or the censorship of a traditional payment processor.
|
||||
|
||||
## About Public-Key Cryptography
|
||||
|
||||
Public-key cryptography is a mathematical system for protecting data and proving ownership through an asymmetric pair of linked keys: the public key and the private key.
|
||||
Public-key cryptography is a mathematical system for protecting data and proving ownership through an asymmetric pair of linked keys: the public key and the private key. It's important to Bitcoin (and to most blockchain systems) because it's the basis of a lot of the cryptography that protects the cryptocurrency funds. A Bitcoin transaction is typically sent to an address that is a hashed public key. The recipient is then able to retrieve the money by revealing both the public key and the private key.
|
||||
|
||||
It's important to Bitcoin (and to most blockchain systems) because it's the basis of a lot of the cryptography that protects the cryptocurrency funds. A Bitcoin transaction is typically sent to an address that is a hashed public key. The recipient is then able to retrieve the money by revealing both the public key and the private key.
|
||||
> 📖 **_What is a public key?_** A public key is the key given out to other people. In a typical public-key system, a user generates a public key and a private key, then he gives the public key to all and sundry.
|
||||
|
||||
**_What Is a Public Key?_** A public key is the key given out to other people. In a typical public-key system, a user generates a public key and a private key, then he gives the public key to all and sundry. Those recipients can encrypt information with the public key, but it can't be decrypted with the same public key because of the asymmetry of the key pair.
|
||||
> 📖 **_What is a private key?_** A private key is linked to a public key in a key pair. In a typical public-key system, a user keeps his private key secure and uses it to engage in asymmetric signing and encryption activities.
|
||||
|
||||
**_What Is a Private Key?_** A private key is linked to a public key in a key pair. In a typical public-key system, a user keeps his private key secure and uses it to decrypt messages that were encrypted with his public key before being sent to him.
|
||||
> 📖 **_What is encryption?_** Encryption is a methodology for making data unreadable. In symmetric encryption, the encoding is done with a singular "symmetric" key that allows either encryption or decryption. In asymmetric encryption, the encryption is typically done with a public key, which then requires the private key for decryption.
|
||||
|
||||
**_What Is a Signature?_** A message (or more commonly, a hash of a message) can be signed with a private key, creating a signature. Anyone with the corresponding public key can then validate the signature, which verifies that the signer owns the private key associated with the public key in question. _SegWit_ is a specific format for storing a signature on the Bitcoin network that we'll meet down the line.
|
||||
> 📖 **_What is a signature?_** A message (or more commonly, a hash of a message) can be signed with a private key, creating a signature. Anyone with the corresponding public key can then validate the signature, which verifies that the signer owns the private key associated with the public key in question. _SegWit_ is a specific format for storing a signature on the Bitcoin network that we'll meet down the line.
|
||||
|
||||
**_What Is a Hash Function?_** 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 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.
|
||||
|
||||
Bitcoin takes advantage of a hash's ability to disguise the original data, which allows concealment of a user's actual public key, making transactions resistant to quantum computing.
|
||||
> 📖 **_What is a hash function?_** 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 reliably be linked to the original data, but the original data can not be regenerated from the hash. Hashes therefore allow the transmission of small amounts of data to represent large amounts of data, which can be important for efficiency and storage requirements. Bitcoin uses hashing to disguise the original data, which allows concealment of a user's actual public key, making transactions resistant to quantum computing.
|
||||
|
||||
### Public-Key Cryptography — In Short
|
||||
|
||||
One way to think of public-key cryptography is: _a way for anyone to protect data such that only an authorized person can access it, and such that the authorized person can prove that he will have that access._
|
||||
|
||||
> 🔥 ***What is the power of public-key cryptography?*** Public-key cryptography allows asymmetric (trap door) activities: one user can encrypt data that can only be decrypted by another; or one person can create signatures that can be verified (but not duplicated) by others. Asymmetric signatures are what make Bitcoin go round.
|
||||
|
||||
## About ECC
|
||||
|
||||
ECC stands for elliptic-curve cryptography. It's a specific branch of public-key cryptography that depends on mathematical calculations conducted using elliptic curves defined over finite fields. It's more complex and harder to explain than classic public-key cryptography (which used prime numbers), but it has some nice advantages.
|
||||
|
||||
ECC does not receive much attention in this tutorial. That's because this tutorial is all about integrating with Bitcoin Core and Lightning servers, which have already taken care of the cryptography for you. In fact, this tutorial's intention is that you don't have to worry about cryptography at all, because that's something that you _really_ want experts to deal with.
|
||||
ECC does not receive much attention in this tutorial. That's because this tutorial is all about integrating with Bitcoin Core servers that have already taken care of the cryptography for you. In fact, this tutorial's intention is that you don't have to worry about cryptography at all, because that's something that you _really_ want experts to deal with.
|
||||
|
||||
**_What is an Elliptic Curve?_** An elliptic curve is a geometric curve that takes the form `y`<sup>`2`</sup> = `x`<sup>`3`</sup>` + ax + b`. A specific elliptic curve is chosen by selecting specific values of `a` and `b`. The curve must then be carefully examined to determine if it works well for cryptography. For example, the secp256k1 curve used by Bitcoin is defined as `a=0` and `b=7`.
|
||||
> 📖 **_What is an elliptic curve?_** An elliptic curve is a geometric curve that takes the form `y`<sup>`2`</sup> = `x`<sup>`3`</sup>` + ax + b`. A specific elliptic curve is chosen by selecting specific values of `a` and `b`. The curve must then be carefully examined to determine if it works well for cryptography. For example, the secp256k1 curve used by Bitcoin is defined as `a=0` and `b=7`. Any line that intersects an elliptic curve will typically do so at 3 points (absent a few cases for infinity and intersections) ... and that's the basis of elliptic-curve cryptography.
|
||||
|
||||
Any line that intersects an elliptic curve will typically so at 3 points (absent a few cases for infinity and intersections) ... and that's the basis of elliptic-curve cryptography.
|
||||
> 📖 **_What are finite fields?_** A finite field is a finite set of numbers, where all addition, subtraction, multiplication, and division is defined so that it results in other numbers also in the same finite field. One simple way to create a finite field is through the use of a modulo function.
|
||||
|
||||
**_What are Finite Fields?_** A finite field is a finite set of numbers, where all addition, subtraction, multiplication, and division is defined so that it results in other numbers also in the same finite field. One simple way to create a finite field is through the use of a modulo function.
|
||||
> 📖 **_How is an elliptic curve defined over a finite field?_** An elliptic curve defined over a finite field has all of the points on its curve drawn from a specific finite field. This takes the form: `y`<sup>`2`</sup> `% field-size = (x`<sup>`3`</sup>` + ax + b) % field-size` The finite field used for secp256k1 is `2`<sup>`256`</sup>` - 2`<sup>`32`</sup>` - 2`<sup>`9`</sup>` - 2`<sup>`8`</sup>` - 2`<sup>`7`</sup>` - 2`<sup>`6`</sup>` - 2`<sup>`4`</sup>` - 1`.
|
||||
|
||||
**_How is an Elliptic Curve Defined Over a Finite Field?_** An elliptic curve defined over a finite field has all of the points on its curve drawn from a specific finite field. This takes the form: `y`<sup>`2`</sup> `% field-size = (x`<sup>`3`</sup>` + ax + b) % field-size` The finite field used for secp256k1 is `2`<sup>`256`</sup>` - 2`<sup>`32`</sup>` - 2`<sup>`9`</sup>` - 2`<sup>`8`</sup>` - 2`<sup>`7`</sup>` - 2`<sup>`6`</sup>` - 2`<sup>`4`</sup>` - 1`.
|
||||
> 📖 **_How are elliptic curves used in cryptography?_** In elliptic-curve cryptography, a user selects a very large (256-bit) number as their private key. They then add a set base point on the curve to itself that many times. (In secp256k1, the base point is `G = 04 79BE667E F9DCBBAC 55A06295 CE870B07 029BFCDB 2DCE28D9 59F2815B 16F81798 483ADA77 26A3C465 5DA4FBFC 0E1108A8 FD17B448 A6855419 9C47D08F FB10D4B8`, which prefixes the two parts of the tuple with an `04` to say that the data point is in uncompressed form. If you prefer a straight geometric definition, it's the point "0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798,0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8") The resultant number is the public key. Various mathematical formula can then be used to prove ownership of the public key, given the private key. As with any cryptographic function, this one is a trap door: it's easy to go from private key to public key and largely impossible to go from public key to private key. This particular methodology also explains why finite fields are used in elliptic curves: it ensures that the private key will not grow too large. (Note that the finite field for secp256k1 is slightly smaller than 256 bits, which means that all public keys will be 256 bits long, just like the private keys are.)
|
||||
|
||||
**_How Are Elliptic Curves Used in Cryptography?_** In elliptic-curve cryptography, a user selects a very large (256-bit) number as his private key. He then adds a set base point on the curve to itself that many times. (In secp256k1, the base point is `G = 04 79BE667E F9DCBBAC 55A06295 CE870B07 029BFCDB 2DCE28D9 59F2815B 16F81798 483ADA77 26A3C465 5DA4FBFC 0E1108A8 FD17B448 A6855419 9C47D08F FB10D4B8`, which prefixes the two parts of the tuple with an `04` to say that the data point is in uncompressed form. If you prefer a straight geometric definition, it's the point "0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798,0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8") The resultant number is the public key. Various mathematical formula can then be used to prove ownership of the public key, given the private key. As with any cryptographic function, this one is a trap door: it's easy to go from private key to public key and largely impossible to go from public key to private key.
|
||||
|
||||
This particular methodology also explains why finite fields are used in elliptic curves: it ensures that the private key will not grow too large. Note that the finite field for secp256k1 is slightly smaller than 256 bits, which means that all public keys will be 256 bits long, just like the private keys are.
|
||||
|
||||
**_What Are the Advantages of ECC?_** The main advantage of ECC is that it allows the same security as classic public-key cryptography with a much smaller key. A 256-bit elliptic-curve public key corresponds to a 3072-bit traditional (RSA) public key.
|
||||
**_What are the advantages of ECC?_** The main advantage of ECC is that it allows the same security as classic public-key cryptography with a much smaller key. A 256-bit elliptic-curve public key corresponds to a 3072-bit traditional (RSA) public key.
|
||||
|
||||
### ECC - In Short
|
||||
|
||||
One way to think of ECC is: _a way to enable public-key cryptography that uses very small keys and very obscure math._
|
||||
|
||||
> 🔥 ***What is the power of ECC?*** The power of ECC is in its small keys. This is important for blockchains because every signature with every private key is recorded on the blockchain forever. Before the block size wars of the '10s, blocks were getting too crowded, making it harder (and more expensive) to create successful Bitcoin transactions. That would be even worse without the power of ECC.
|
||||
|
||||
## About Blockchains
|
||||
|
||||
Blockchain is the generalization of the methodology used by Bitcoin to create a distributed global ledger. Bitcoin is a blockchain as are any number of alt-coins, each of which lives on its own network and writes to its own chain. Sidechains like Liquid are blockchains too. Blockchains don't even need to have anything to do with finances. For example, there have been many discussions of using blockchains to protect self-sovereign identities.
|
||||
Blockchain is the generalization of the methodology used by Bitcoin to create a distributed global ledger. The more general methodology can be used for many purposes: there are lots of other cryptocurrencies that each have their own blockchain, and blockchains have also been used for other purposes, such as recording the provenance of digital assets. Because blockchains have become a wide category of technology, the basic concepts discussed in this course are likely to be applicable to many other projects in this growing technology sector. The specific programming commands learned in this book will not be, however, as they're fairly specific to Bitcoin.
|
||||
|
||||
Though you need to understand the basics of how a blockchain works to understand how transactions work in Bitcoin, you won't need to go any further than that. Because blockchains have become a wide category of technology, those basic concepts are likely to be applicable to many other projects in this growing technology sector. The specific programming commands learned in this book will not be, however, as they're fairly specific to Bitcoin (and Lightning).
|
||||
Though you need to understand the basics of how a blockchain works in order to understand how transactions work in Bitcoin, you won't need to go any further than that. B
|
||||
|
||||
**_Why Is It Called a Chain?_** Each block in the blockchain stores a hash of the block before it. This links the current block all the way back to the original "genesis block" through an unbroken chain. It's a way to create absolute order among possibly conflicting data. This also provides the security of blockchain, because each block is stacked atop an old one makes it harder to recreate the old block due to the proof-of-work algorithms used in block creation. Once several blocks have been built atop a block in the chain, it's essentially irreversible.
|
||||
> 📖 **_Why is it called a chain?_** Each block in the blockchain stores a hash of the block before it. This links the current block to the previous block and goes all the way back to the original "genesis block" through an unbroken chain. It's a way to create absolute order among possibly conflicting data. This also provides the security of blockchain, because each block that is stacked atop an old one makes it harder to recreate the old block due to the proof-of-work algorithms used in block creation. Once several blocks have been built atop a block in the chain, it's essentially irreversible.
|
||||
|
||||
**_What is a Fork?_** Occasionally two blocks are created around the same time. This temporarily creates a one-block fork, where either of the current blocks could be the "real" one. Every once in a while, a fork might expand to become two blocks, three blocks, or even four blocks long, but pretty quickly one side of the fork is determined to be the real one, and the other is "orphaned". This is part of the stochastic process of block creation, and demonstrates why several blocks must be built atop a block before it can be considered truly trustworthy and non-repudiable.
|
||||
> 📖 **_What is proof of work_** Blockchains are a "trustless" technology, which means that no one has to actually trust anyone else involved in transactions. Instead, trust is created by the technology itself. For Bitcoin, that means that when a transaction happens, you know the funds have been transferred, and there's no way to reverse it (once a few blocks are built on top of the block with your transaction). You know this because of "proof of work". That means that it takes an intense amount of computation to create a block. When you multiply that by a few blocks stacked atop each other, the proof of work has become so high that it will never be reversed. Other blockchains create their implicit trust in other ways. For example, Ethereum has been using "proof of stake" since 2022, which means that the permanence of blocks is assured by people putting their own currency behind a block, "staking" it.
|
||||
|
||||
**_What is a fork?_** Occasionally two blocks are created around the same time. This temporarily creates a one-block fork, where either of the current blocks could be the "real" one. Every once in a while, a fork might expand to become two blocks, three blocks, or even four blocks long, but pretty quickly one side of the fork is determined to be the real one, and the other is "orphaned". This is part of the stochastic process of block creation, and demonstrates why several blocks must be built atop a block before it can be considered truly trustworthy and non-repudiable.
|
||||
|
||||
### Blockchain — In Short
|
||||
|
||||
One way to think of blockchain is: _a linked series of blocks of unchangeable data, going back in time_. Another way is: _a linked series of blocks to absolutely order data that could be conflicting_.
|
||||
|
||||
> 🔥 ***What is the power of blockchain?*** Blockchains have a number of advantages that offset potential costs (as discussed below). The biggest include their permanent and immutable ledgers and the ability to transact in an environment where the counterparties don't trust each other.
|
||||
|
||||
## Is Blockchain Right for Me?
|
||||
|
||||
If you want to transact bitcoins, then obviously Bitcoin is right for you. However, more widely, blockchain has become a popular buzz-word even though it's not a magic bullet for all technical problems. With that said, there are many specific situations where blockchain is a superior technology.
|
||||
@ -110,35 +108,37 @@ Blockchains probably _will not_ be helpful if:
|
||||
* Secrecy is required:
|
||||
* e.g.: Information should be secret.
|
||||
* e.g.: Transactions should be secret.
|
||||
* e.g.: Transactors should be secret.
|
||||
* e.g.: Counterparties should be secret.
|
||||
* Unless: A methodology for cryptographic secrecy is carefully considered, analyzed, and tested.
|
||||
* Users need instant transaction finality.
|
||||
* e.g.: in less than 10 minutes on a Bitcoin-like network, in less than 2.5 minutes on a Litecoin-like network, in less than 15 seconds on an Ethereum-like network
|
||||
|
||||
Do note that there may still be solutions for some of these situations within the Bitcoin ecosystem. For example, payment channels are rapidly addressing questions of liquidity and payment finality.
|
||||
Do note that there may still be solutions for some of these situations within the Bitcoin ecosystem. For example, payment channels are rapidly addressing questions of liquidity and payment finality, while related cryptocurrencies such as Zcash allow for secrecy using "shielded" transactions.
|
||||
|
||||
## About Lightning
|
||||
|
||||
Lightning is a layer-2 protocol that interacts with Bitcoin to allow users to exchange their bitcoins "off-chain". It has both advantages and disadvantages over using Bitcoin on its own.
|
||||
|
||||
Lightning is also the secondary focus of this tutorial. Though it's mostly about interacting directly with Bitcoin (and the `bitcoind`), it pays some attention to Lightning because it's an upcoming technology that is likely to become a popular alternative to Bitcoin in the near future. This book takes the same approach to Lightning as to Bitcoin: it teaches how to interact directly with a trusted Lightning daemon from the command line.
|
||||
Lightning is also the secondary focus of this tutorial. Though the course is mostly about interacting directly with Bitcoin (and the `bitcoind`), it pays some attention to Lightning because it's an upcoming technology that at times has offered advantages over Bitcoin (particularly when fees cranked up during the block size wars). This book takes the same approach to Lightning as to Bitcoin: it teaches how to interact directly with a trusted Lightning daemon from the command line.
|
||||
|
||||
Unlike with Bitcoin, there are actually several variants of Lightning. This tutorial uses the standard-compliant [core lightning](https://github.com/ElementsProject/lightning) implementation as its trusted Lightning server.
|
||||
|
||||
**_What is a Layer-2 Protocol?_** A layer-2 Bitcoin protocol works on top of Bitcoin. In this case, Lightning works atop Bitcoin, interacting with it through smart contracts.
|
||||
> 📖 **_What is a layer-2 protocol?_** A layer-2 Bitcoin protocol works on top of Bitcoin. In this case, Lightning works atop Bitcoin, interacting with it through smart contracts.
|
||||
|
||||
**_What is a Lightning Channel?_** A Lightning Channel is a connection between two Lightning users. Each of the users locks up some number of bitcoins on the Bitcoin blockchain using a multi-sig signed by both of them. The two users can then exchange bitcoins through their Lightning channel without ever writing to the Bitcoin blockchain. Only when they want to close out their channel do they settle their bitcoins, based on the final division of coins.
|
||||
> 📖 **_What is a Lightning Channel?_** A Lightning Channel is a connection between two Lightning users. Each of the users locks up some number of bitcoins on the Bitcoin blockchain using a multi-sig signed by both of them. The two users can then exchange bitcoins through their Lightning channel without ever writing to the Bitcoin blockchain. Only when they want to close out their channel do they settle their bitcoins, based on the final division of coins.
|
||||
|
||||
**_What is a Lightning Network?_** Putting together a number of Lightning Channels creates the Lightning Network. This allows two users who have not created a channel between themselves to exchange bitcoins using Lightning: the protocol forms a chain of Channels between the two users, then exchanges the coins through the chain using time-locked transactions.
|
||||
> 📖 **_What is a Lightning Network?_** Putting together a number of Lightning Channels creates the Lightning Network. This allows two users who have not created a channel between themselves to exchange bitcoins using Lightning: the protocol forms a chain of Channels between the two users, then exchanges the coins through the chain using time-locked transactions.
|
||||
|
||||
**_What are the Advantages of Lightning?_** Lightning allows for faster transactions with lower fees. This creates the real possibility of bitcoin-funded micropayments. It also offers better privacy, since it's off-chain with only the first and last states of the transaction being written to the immutable Bitcoin ledger.
|
||||
> 📖 **_What are the advantages of Lightning?_** Lightning allows for faster transactions with lower fees. This creates the real possibility of bitcoin-funded micropayments. It also offers better privacy, since it's off-chain with only the first and last states of the transaction being written to the immutable Bitcoin ledger.
|
||||
|
||||
**_What are the Disadvantages of Lightning?_** Lightning is still a very new technology and hasn't been tested as thoroughly as Bitcoin. That's not just a question of the technological implementation, but also whether the design itself can be gamed in any unexpected ways.
|
||||
> 📖 **_What are the disadvantages of Lightning?_** Lightning is still a very new technology and hasn't been tested as thoroughly as Bitcoin. That's not just a question of the technological implementation, but also whether the design itself can be gamed in any unexpected ways.
|
||||
|
||||
### Lightning - In Short
|
||||
|
||||
One way to think of Lightning is: _a way to transact bitcoins using off-chain channels between pairs of people, so that only a first and final state have to be written to the blockchain_.
|
||||
|
||||
> 🔥 ***What is the power of Lightning?*** Lightning has a pair of major advantages: it's private and cheap. The privacy comes from the fact that much of it is conducted off-chain, meaning that many of your transactions aren't written to the permanent ledger of Bitcoin. The cheapness just means that fees are lower. At various times, the cost to send Bitcoin transactions has varied from a few cents to ten or twenty dollars. Whenever those fees come up from the lowest levels, they defeat the ability to send microtransactions. Lightning maintains that ability.
|
||||
|
||||
## Summary: Introducing Bitcoin
|
||||
|
||||
Bitcoin is a peer-to-peer system that allows for the transfer of funds through transactions that are locked with puzzles. These puzzles are dependent upon public-key elliptic-curve cryptography. When you generalize the ideas behind Bitcoin, you get blockchains, a technology that's currently growing and innovating. When you expand the ideas behind Bitcoin, you get layer-2 protocols such as Lightning, which expand the currency's potential.
|
||||
|
||||
@ -23,7 +23,7 @@ Supporting objectives include the ability to:
|
||||
|
||||
## Table of Contents
|
||||
|
||||
You don't actually need to read this entire chapter. Decide if you want to run a StackScript to set a node up on a Linode VPS (§2.2); or you want to set up on a different environment, such as on an AWS machine or a Mac (§2.3). Then, jump to the appropriate section. Additional information on our suggested setups may also be found in [Appendix I](A1_0_Understanding_Bitcoin_Standup.md).
|
||||
You don't actually need to read this entire chapter. Decide if you want to run a StackScript to set a node up on a Linode VPS (§2.1); or you want to set up on a different environment, such as on an AWS machine or a Mac (§2.2). Then, jump to the appropriate section. Additional information on our suggested setups may also be found in [Appendix I](A1_0_Understanding_Bitcoin_Standup.md).
|
||||
|
||||
* [Section One: Setting Up a Bitcoin Core VPS with Bitcoin Standup](02_1_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md)
|
||||
* [Section Two: Setting Up a Bitcoin Core Machine via Other Means](02_2_Setting_Up_Bitcoin_Core_Other.md)
|
||||
|
||||
@ -56,7 +56,7 @@ You're now ready to create a node based on the Stackscript.
|
||||
* **Cypherpunkpay.** These are options to install Cypherpunkpay on your server. They're primarily intended for other users of the Standup software and aren't used in this course, so you can just leave them be.
|
||||
4. Choose a region for where the Linode will be located.
|
||||
5. Select an Image
|
||||
* **Target Image.** If you followed the instructions, this will only allow you to select "Debian 13" (though previous versions of this Stackscript worked with Debian 9 through 12, and might still.)
|
||||
* **Target Image.** If you followed the instructions, this will only allow you to select "Debian 13" (though previous versions of this Stackscript worked with Debian 9 through 12 and might still.)
|
||||
|
||||
### Choose a Linode Plan
|
||||
|
||||
@ -81,7 +81,7 @@ The following chart shows minimum requirements
|
||||
Note, there may be ways to reduce both costs.
|
||||
|
||||
* For the setups we suggest as **Linode 4GB**, you may be able to reduce that to a Linode 2GB. Some versions of Bitcoin Core have worked well at that size, some have occasionally run out of memory and then recovered, and some have continuously run out of memory. Remember to up that swap space to maximize the odds of this working. Use at your own risk.
|
||||
* For the Unpruned Mainnet, which we suggest as a **Linode 64GB**, you can probably get by with a Linode 4GB, but add [Block Storage](https://cloud.linode.com/volumes/create) sufficient to store the blockchain. This is certainly a better long-term solution since the Bitcoin blockchain's storage requirements continuously increase if you don't prune, while the CPU requirements don't (or don't to the same degree). A 750 GibiByte storage would be $75 a month, which combined with a Linode 4GB is $95 a month, instead of $384, and more importantly you can keep growing it. We don't fully document this setup for two reasons (1) we don't suggest the unpruned mainnet setup, and so we suspect it's a much less common setup; and (2) we haven't tested how Linodes volumes compare to their intrinic SSDs for performance and usage. But there's full documentation on the Block Storage page. You'd need to set up the Linode, run its stackscript, but then interrupt it to move the blockchain storage over to a newly commissioned volume before continuing.
|
||||
* For the Unpruned Mainnet, which we suggest as a **Linode 64GB**, you can probably get by with a Linode 4GB, but add [Block Storage](https://cloud.linode.com/volumes/create) sufficient to store the blockchain. This is certainly a better long-term solution since the Bitcoin blockchain's storage requirements continuously increase if you don't prune, while the CPU requirements don't (or don't to the same degree). A 750 GibiByte storage would be $75 a month, which combined with a Linode 4GB is $95 a month, instead of $384, and more importantly you can keep growing it. We don't fully document this setup for two reasons (1) we don't suggest the unpruned mainnet setup, and so we suspect it's a much less common setup, particularly for this course; and (2) we haven't tested how Linodes volumes compare to their intrinic SSDs for performance and usage. But there's full documentation on the [Block Storage page](https://cloud.linode.com/volumes). You'd need to set up the Linode, run its stackscript, but then interrupt it to move the blockchain storage over to a newly commissioned volume before continuing.
|
||||
|
||||
If you are running a deployment that will be transacting real Bitcoins, you may want to alternatively consider a Dedicated-CPU Linode, which tends to run 50% more expensive than the Shared-CPU Linode. We've generally found the Shared CPUs to be entirely sufficient, but for a wide deployment, you may wish to consider higher levels of reliability.
|
||||
|
||||
@ -117,7 +117,7 @@ If you configured your VPS to use an SSH key, the login should be automatic (pos
|
||||
|
||||
### Wait a Few Minutes
|
||||
|
||||
Here's a little catch: _your StackScript is running right now_. The BASH script gets executed the first time the VPS is booted. That means your VPS isn't ready yet.
|
||||
Here's a little catch: _your StackScript is running right now_. The Bash script gets executed the first time the VPS is booted. That means your VPS isn't ready yet.
|
||||
|
||||
The total run time is about 10 minutes. So, go take a break, get an espresso, or otherwise relax for a few minutes. There are two parts of the script that take a while: the updating of all the Debian packages; and the downloading of the Bitcoin code. They shouldn't take more than 5 minutes each, which means if you come back in 10 minutes, you'll probably be ready to go.
|
||||
|
||||
@ -135,9 +135,8 @@ At that point, your home directory should look like this:
|
||||
|
||||
```
|
||||
$ ls
|
||||
bitcoin-30.2-x86_64-linux-gnu.tar.gz wget-btc-output.txt
|
||||
SHA256SUMS wget-btc-sha-asc-output.txt
|
||||
SHA256SUMS.asc wget-btc-sha-output.txt
|
||||
bitcoin-30.2-x86_64-linux-gnu.tar.gz SHA256SUMS.asc wget-btc-sha-asc-output.txt
|
||||
SHA256SUMS wget-btc-output.txt wget-btc-sha-output.txt
|
||||
```
|
||||
|
||||
These are the various files that were used to install Bitcoin on your VPS. _None_ of them are necessary. We've just left them in case you want to do any additional verification. Otherwise, you can delete them:
|
||||
@ -201,7 +200,18 @@ Although the default Debian 13 image that we are using for your VPS has been mod
|
||||
|
||||
### Protected Services
|
||||
|
||||
Your Bitcoin VPS installation is minimal and allows almost no communication. This is done through the uncomplicated firewall (`ufw`), which blocks everything except SSH connections. There's also some additional security possible for your RFC ports, thanks to the hidden services installed by Tor.
|
||||
Your Bitcoin VPS installation is minimal and allows almost no communication. This is done through the uncomplicated firewall (`ufw`), which blocks everything except SSH connections. You can verify that it's running as follows:
|
||||
```
|
||||
$ sudo ufw status
|
||||
Status: active
|
||||
|
||||
To Action From
|
||||
-- ------ ----
|
||||
22/tcp ALLOW Anywhere
|
||||
22/tcp (v6) ALLOW Anywhere (v6)
|
||||
```
|
||||
|
||||
There's also some additional security possible for your RFC ports, thanks to the hidden services installed by Tor.
|
||||
|
||||
**Adjusting UFW.** You should probably leave UFW in its super-protected stage! You don't want to use a Bitcoin machine for other services, because everyone increases your vulnerability! If you decide otherwise, there are several [guides to UFW](https://www.digitalocean.com/community/tutorials/ufw-essentials-common-firewall-rules-and-commands) that will allow you to add services. As advertised, it's uncomplicated. For example adding mail services would just require opening the mail port: `sudo ufw allow 25`. But don't do that.
|
||||
|
||||
@ -224,7 +234,7 @@ Debian is also set up to automatically upgrade itself, to ensure that it remains
|
||||
If for some reason you wanted to change this (_we don't suggest it_), you can do this:
|
||||
|
||||
```
|
||||
echo "unattended-upgrades unattended-upgrades/enable_auto_updates boolean false" | debconf-set-selections
|
||||
$ echo "unattended-upgrades unattended-upgrades/enable_auto_updates boolean false" | sudo debconf-set-selections
|
||||
```
|
||||
|
||||
_If you'd like to know more about what the Bitcoin Standup stackscript does, please see [Appendix I: Understanding Bitcoin Standup](A1_0_Understanding_Bitcoin_Standup.md)._
|
||||
@ -240,7 +250,7 @@ $ bitcoin-cli getblockcount
|
||||
```
|
||||
If it's different every time you type the command, you need to wait before working with Bitcoin. This can take hours for a mainnet setup, but if you're using our suggested setup of pruned signet, it should be done in 15 minutes or so.
|
||||
|
||||
But, once it settles at a number, you're ready to continue!
|
||||
Once it settles at a number, you're ready to continue!
|
||||
|
||||
Still, it might be time for a few more espressos. But soon enough, your system will be ready to go, and you'll be read to start experimenting.
|
||||
|
||||
@ -254,16 +264,16 @@ You have a few options for what's next:
|
||||
|
||||
* Read the [StackScript](https://github.com/BlockchainCommons/Bitcoin-Standup-Scripts/blob/master/Scripts/LinodeStandUp.sh) to understand your setup.
|
||||
* Read what the StackScript does in [Appendix I](A1_0_Understanding_Bitcoin_Standup.md).
|
||||
* Choose an entirely alternate methodology in [§2.2: Setting Up a Bitcoin-Core Machine via Other Means](02_2_Setting_Up_Bitcoin_Core_Other.md).
|
||||
* Choose an entirely alternate methodology for creating your VPS in [§2.2: Setting Up a Bitcoin-Core Machine via Other Means](02_2_Setting_Up_Bitcoin_Core_Other.md).
|
||||
* Move on to "bitcoin-cli" with [Chapter Three: Understanding Your Bitcoin Setup](03_0_Understanding_Your_Bitcoin_Setup.md).
|
||||
|
||||
## Synopsis: Bitcoin Installation Types
|
||||
|
||||
**Mainnet.** This will download the entirety of the Bitcoin blockchain. That's 280G of data (and getting more every day).
|
||||
**Mainnet.** This will download the entirety of the Bitcoin blockchain. That's 725G of data (and getting more every day).
|
||||
|
||||
**Pruned Mainnet.** This will cut the blockchain you're storing down to just the last 550 blocks. If you're not mining or running some other Bitcoin service, this should be plenty for validation.
|
||||
|
||||
**Signet.** This is the newest iteration of a testing network, where Bitcoins don't actually have value, and has largely surpassed Testnet. It's intended for experimentation and testing. Its big advantage is that its block production is more reliable that Testnet, where Testnet could stall out for a while, then produce a bunch of blocks together.
|
||||
**Signet.** This is the newest iteration of a testing network, where Bitcoins don't actually have value and has largely surpassed Testnet. It's intended for experimentation and testing. Its big advantage is that its block production is more reliable that Testnet, where Testnet could stall out for a while, then produce a bunch of blocks together.
|
||||
|
||||
**Pruned Signet.** The last 550 blocks of Signet.
|
||||
|
||||
|
||||
@ -5,12 +5,12 @@ The previous section, [§2.1: Setting Up a Bitcoin-Core VPS with Bitcoin Standup
|
||||
Following are other setup methodologies that we are aware of:
|
||||
|
||||
* *[Compiling from Source](A2_0_Compiling_Bitcoin_from_Source.md).* If you prefer to compile Bitcoin Core by hand, that's covered in Appendix 2.
|
||||
* *[Using GordianServer-macOS](https://github.com/BlockchainCommons/GordianServer-macOS).* If you have a modern Mac, you can use Blockchain Commons' *GordianNode* app, powered by *BitcoinStandup*, to install a full node on your Mac.
|
||||
* *[Using Fully Noded Server](https://github.com/Fonta1n3/FullyNoded-Server).* If you have a **Mac**, you can install Bitcoin using Fontaine's Fully Noded Server. The main gotcha is that it hides the `bitcoin-cli` binary, but you can create an alias for it using something like `alias bitcoin-cli="~/.fullynoded/BitcoinCore/bitcoin-30.2/bin/bitcoin-cli -signet"` and see [§3.1](03_1_Verifying_Your_Bitcoin_Setup.md) for more on creating aliases. Do note that Mac's zsh and our default bash shells work slightly differently so the syntax of piping, shell variables, and other similar functions might be different.
|
||||
* *[Using Other Bitcoin Standup Scripts](https://github.com/BlockchainCommons/Bitcoin-Standup-Scripts).* Blockchain Commons also offers a version of the Linode script that you used that can be run from the command line on any Debian or Ubuntu machine. This tends to be the leading-edge script, which means that it's more likely to feature new functions, like Lightning installation.
|
||||
* *[Setting Up a Bitcoin Node on AWS](https://wolfmcnally.com/115/developer-notes-setting-up-a-bitcoin-node-on-aws/).* @wolfmcnally has written a step-by-step tutorial for setting up Bitcoin-Core with Amazon Web Services (AWS).
|
||||
* *[Setting Up a Bitcoin Node on a Raspberry Pi 3](https://medium.com/@meeDamian/bitcoin-full-node-on-rbp3-revised-88bb7c8ef1d1).* Damian Mee explains how to set up a headless full node on a Raspberry Pi 3.
|
||||
* *[Setting Up a Bitcoin Node on a Raspberry Pi 3 (Revised)](https://medium.com/@meeDamian/bitcoin-full-node-on-rbp3-revised-88bb7c8ef1d1).* Damian Mee explains how to set up a headless full node on a Raspberry Pi 3.
|
||||
|
||||
Be sure that you are installing on a current version of your OS, to avoid problems down the line. As of this writing, this course is tested on Debian 11.
|
||||
Be sure that you are installing on a current version of your OS, to avoid problems down the line. As of this writing, this course is tested on Debian 13.
|
||||
|
||||
## What's Next?
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
You're now ready to begin working with the `bitcoin-cli` command-line interface. But that first requires that you understand your Bitcoin setup and its wallet features, which is what will be explained in this chapter.
|
||||
|
||||
For this and future chapters, we presume that you have a VPS with Bitcoin installed, running `bitcoind`. We also presume that you are connected to testnet, allowing for access to bitcoins without using real funds. You can either do this with Bitcoin Standup at Linode.com, per [§2.1: Setting up a Bitcoin-Core VPS with Bitcoin Standup](02_1_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md), or via other means, per [§2.2: Setting up a Bitcoin-Core Machine via Other Means](02_2_Setting_Up_Bitcoin_Core_Other.md).
|
||||
For this and future chapters, we presume that you have a VPS with Bitcoin installed, running `bitcoind`. We also presume that you are connected to signet (or testnet), allowing for access to bitcoins without using real funds. You can either do this with Bitcoin Standup at Linode.com, per [§2.1: Setting up a Bitcoin-Core VPS with Bitcoin Standup](02_1_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md), or via other means, per [§2.2: Setting up a Bitcoin-Core Machine via Other Means](02_2_Setting_Up_Bitcoin_Core_Other.md).
|
||||
|
||||
## Objectives for This Chapter
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ With that said, use of these aliases in _this_ document might accidentally obscu
|
||||
You'll begin your exploration of the Bitcoin network with the `bitcoin-cli` command. However, bitcoind _must_ be running to use bitcoin-cli, as bitcoin-cli sends JSON-RPC commands to the bitcoind. If you used our standard setup, bitcoind should already be up and running. You can double check by looking at the process table.
|
||||
```
|
||||
$ ps auxww | grep bitcoind
|
||||
standup 455 1.3 34.4 3387536 1392904 ? SLsl Jun16 59:30 /usr/local/bin/bitcoind -conf=/home/standup/.bitcoin/bitcoin.conf
|
||||
standup 9963 24.0 51.0 6602300 2048564 ? SLsl 10:37 40:08 /usr/local/bin/bitcoind -conf=/home/standup/.bitcoin/bitcoin.conf
|
||||
```
|
||||
If it's not running, you'll want to run `/usr/local/bin/bitcoind -daemon` by hand and also place it in your crontab.
|
||||
|
||||
@ -35,26 +35,26 @@ If it's not running, you'll want to run `/usr/local/bin/bitcoind -daemon` by han
|
||||
You should have the whole blockchain downloaded before you start playing. Just run the `bitcoin-cli getblockcount` alias to see if it's all loaded.
|
||||
```
|
||||
$ bitcoin-cli getblockcount
|
||||
1772384
|
||||
295304
|
||||
```
|
||||
That tells you what's loaded; you'll then need to check that against an online service that tells you the current block height.
|
||||
|
||||
> :book: ***What is Block Height?*** Block height is the the distance that a particular block is removed from the genesis block. The current block height is the block height of the newest block added to a blockchain.
|
||||
> 📖 ***What is Block Height?*** Block height is the the distance that a particular block is removed from the genesis block. The current block height is the block height of the newest block added to a blockchain.
|
||||
|
||||
You can do this by looking at a blocknet explorer, such as [the Mempool Signet explorer](https://mempool.space/signet). Does its most recent number match your `getblockcount`? If so, you're up to date.
|
||||
|
||||
If you'd like an alias to look at everything at once, the following currently works for Signet, but may disappear at some time in the future:
|
||||
If you'd like an alias to look at everything at once, the following currently works for Signet, but may disappear at some time in the future since it depends on a third-party remote API:
|
||||
```
|
||||
$ echo "alias btcblock='echo \$(bitcoin-cli -signet getblockcount)/\$(curl -s https://blockstream.info/signet/api/blocks/tip/height)'" >> .bash_profile
|
||||
$ source .bash_profile
|
||||
$ btcblock
|
||||
|
||||
288200/288200
|
||||
295304/295304
|
||||
```
|
||||
|
||||
> :link: **SIGNET vs MAINNET:** Remember that this tutorial generally assumes that you are using signet. If you're using the mainnet instead, you can retrieve the current block height with: `curl -s https://blockchain.info/q/getblockcount`. You can replace the latter half of the `btcblock` alias (between `/\$(` and `)'"`) with that.
|
||||
|
||||
If you're not up-to-date, but your `getblockcount` is increasing, no problem. Total download time can take from an hour to several hours, depending on your setup.
|
||||
If you're not up-to-date, but your `getblockcount` is increasing, no problem. Total download time can take from 15 minutes to several hours, depending on your setup.
|
||||
|
||||
## Optional: Know Your Server Types
|
||||
|
||||
@ -73,7 +73,8 @@ If you're running regtest, it probably contains this line:
|
||||
```
|
||||
regtest=1
|
||||
```
|
||||
However, if you want to run several different sorts of nodes simultaneously, you should leave the signet (or testnet or regtest) flag out of your configuration file. You can then choose whether you're using the mainnet, the signet, the testnet, or your regtest every time you run bitcoind or bitcoin-cli.
|
||||
|
||||
If you want to run several different sorts of nodes simultaneously, you should instead leave the signet (or testnet or regtest) flag out of your configuration file. You can then choose whether you're using the mainnet, the signet, the testnet, or your regtest every time you run bitcoind or bitcoin-cli.
|
||||
|
||||
Here's a set of aliases that would make that easier by creating a specific alias for starting and stopping the bitcoind, for going to the bitcoin directory, and for running bitcoin-cli, for each of the mainnet (which has no extra flags), the signet (which is -signet), the testnet (which is -testnet), or your regtest (which is -regtest).
|
||||
```
|
||||
@ -103,7 +104,7 @@ For even more complexity, you could have each of your 'start' aliases use the -c
|
||||
|
||||
## Summary: Verifying Your Bitcoin Setup
|
||||
|
||||
Before you start playing with bitcoin, you should make sure that your aliases are set up, your bitcoind is running, and your blocks are downloaded. You may also want to set up some access to alternative Bitcoin setups, if you're an advanced user.
|
||||
Before you start playing with bitcoin, you should make sure that your aliases are set up, your `bitcoind` is running, and your blocks are downloaded. You may also want to set up some access to alternative Bitcoin setups, if you're an advanced user.
|
||||
|
||||
## What's Next?
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ Before you start playing with Bitcoin, you may always want to come to a better u
|
||||
|
||||
To start with, you should understand where everything is kept: the `~/.bitcoin` directory.
|
||||
|
||||
The main directory just contains your config file and the testnet directory:
|
||||
The main directory just contains your config file and the signet directory:
|
||||
```
|
||||
$ ls ~/.bitcoin
|
||||
bitcoin.conf signet
|
||||
@ -19,13 +19,13 @@ $ ls ~/.bitcoin/signet
|
||||
banlist.json blocks debug.log peers.dat wallets
|
||||
bitcoind.pid chainstate onion_v3_private_key settings.json
|
||||
```
|
||||
You shouldn't mess with most of these files and directories — particularly not the `blocks` and `chainstate` directories, which contain all of the blockchain data, and the information in your `wallets` directory, which will contain your personal wallet (when we set it up). However, do take careful note of the `debug.log` file, which you should refer to if you ever have problems with your setup.
|
||||
You shouldn't mess with most of these files and directories — particularly not the `blocks` and `chainstate` directories, which contain all of the blockchain data, and the information in your `wallets` directory, which will contain your personal wallet(s) when they're set up. However, do take careful note of the `debug.log` file, which you should refer to if you ever have problems with your setup.
|
||||
|
||||
> :link: **SIGNET vs MAINNET:** If you're using mainnet, then _everything_ will instead be placed in the main `~/.bitcoin` directory. These various setups _do_ elegantly stack, so if you are using mainnet, signet, testnet, and regtest, you'll find that `~/.bitcoin` contains your config file and your mainnet data, the `~/.bitcoin/signet` directory contains your signet data, the `~/.bitcoin/testnet3` or `~/.bitcoin/testnet4` directory contains your testnet data, and the `~/.bitcoin/regtest` directory contains your regtest data.
|
||||
> 🔗 **SIGNET vs MAINNET:** If you're using mainnet, then _everything_ will instead be placed in the main `~/.bitcoin` directory. These various setups _do_ elegantly stack, so if you are using mainnet, signet, testnet, and regtest, you'll find that `~/.bitcoin` contains your config file and your mainnet data, the `~/.bitcoin/signet` directory contains your signet data, the `~/.bitcoin/testnet3` or `~/.bitcoin/testnet4` directory contains your testnet data, and the `~/.bitcoin/regtest` directory contains your regtest data.
|
||||
|
||||
## Know Your Bitcoin-cli Commands
|
||||
|
||||
Most of your early work will be done with the `bitcoin-cli` command, which offers an easy interface to `bitcoind`. If you ever want more information on its usage, just run it with the `help` argument. Without any other arguments, it shows you every possible command:
|
||||
Most of your work in this course will be done with the `bitcoin-cli` command, which offers an easy interface to `bitcoind`. If you ever want more information on its usage, just run it with the `help` argument. Without any other arguments, it shows you every possible command:
|
||||
```
|
||||
$ bitcoin-cli help
|
||||
== Blockchain ==
|
||||
@ -227,39 +227,35 @@ Examples:
|
||||
> curl --user myusername --data-binary '{"jsonrpc": "2.0", "id": "curltest", "method": "createwallet", "params": ["testwallet"]}' -H 'content-type: application/json' http://127.0.0.1:8332/
|
||||
> bitcoin-cli -named createwallet wallet_name=descriptors avoid_reuse=true load_on_startup=true
|
||||
> curl --user myusername --data-binary '{"jsonrpc": "2.0", "id": "curltest", "method": "createwallet", "params": {"wallet_name":"descriptors","avoid_reuse":true,"load_on_startup":true}}' -H 'content-type: application/json' http://127.0.0.1:8332/
|
||||
|
||||
```
|
||||
> :book: ***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.
|
||||
> 📖 ***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.
|
||||
|
||||
## Optional: Know Your Bitcoin Info
|
||||
|
||||
A variety of bitcoin-cli commands can give you additional information on your bitcoin data. The most general ones are:
|
||||
A variety of bitcoin-cli commands can give you additional information on your bitcoin data. The most general ones is `bitcoin-cli -getinfo`, which returns information from different RPCs.
|
||||
|
||||
`bitcoin-cli -getinfo` returns information from different RPCs (user-friendly)
|
||||
|
||||
```diff
|
||||
```
|
||||
$ bitcoin-cli -getinfo
|
||||
|
||||
! Chain: test
|
||||
Blocks: 1977694
|
||||
Headers: 1977694
|
||||
Verification progress: 0.9999993275374796
|
||||
Difficulty: 1
|
||||
Chain: signet
|
||||
Blocks: 295306
|
||||
Headers: 295306
|
||||
Verification progress: 100.0000%
|
||||
Difficulty: 0.04790444111119883
|
||||
|
||||
+ Network: in 0, out 8, total 8
|
||||
Version: 219900
|
||||
Network: in 0, out 10, total 10
|
||||
Version: 300200
|
||||
Time offset (s): 0
|
||||
Proxy: N/A
|
||||
Min tx relay fee rate (BTC/kvB): 0.00001000
|
||||
Proxies: 127.0.0.1:9050 (onion)
|
||||
Min tx relay fee rate (BTC/kvB): 0.00000100
|
||||
|
||||
@@ Wallet: ""@@
|
||||
Keypool size: 1000
|
||||
Unlocked until: 0
|
||||
Wallet: ""
|
||||
Keypool size: 4000
|
||||
Transaction fee rate (-paytxfee) (BTC/kvB): 0.00000000
|
||||
|
||||
# Balance: 0.02853102
|
||||
Balance: 0.00500385
|
||||
|
||||
- Warnings: unknown new rules activated (versionbit 28)
|
||||
Warnings: (none)
|
||||
|
||||
```
|
||||
|
||||
@ -288,9 +284,9 @@ $ bitcoin-cli getnetworkinfo
|
||||
"localrelay": true,
|
||||
"timeoffset": 0,
|
||||
"networkactive": true,
|
||||
"connections": 11,
|
||||
"connections": 10,
|
||||
"connections_in": 0,
|
||||
"connections_out": 11,
|
||||
"connections_out": 10,
|
||||
"networks": [
|
||||
{
|
||||
"name": "ipv4",
|
||||
@ -332,17 +328,17 @@ $ bitcoin-cli getnetworkinfo
|
||||
"incrementalfee": 0.00000100,
|
||||
"localaddresses": [
|
||||
{
|
||||
"address": "172.239.66.235",
|
||||
"address": "74.207.243.158",
|
||||
"port": 38333,
|
||||
"score": 1
|
||||
},
|
||||
{
|
||||
"address": "2a01:7e03::2000:92ff:fe75:3ec",
|
||||
"address": "2600:3c01::2000:61ff:fe35:66b1",
|
||||
"port": 38333,
|
||||
"score": 1
|
||||
},
|
||||
{
|
||||
"address": "km4bnrbemttglfbkafav2nf5mcy4x3l5jmi24fwtjjm3uba2ygycutyd.onion",
|
||||
"address": "djna7ztirmrxzbdndkya4cf3s7ywin3qnttcauswuh633qyghexg4lid.onion",
|
||||
"port": 38333,
|
||||
"score": 4
|
||||
}
|
||||
|
||||
@ -83,7 +83,7 @@ $ bitcoin-cli getwalletinfo
|
||||
}
|
||||
}
|
||||
```
|
||||
> :book: ***What is a Bitcoin wallet?*** A Bitcoin wallet is the digital equivalent of a physical wallet. It stores information on the amount of bitcoins you have and where it's located (addresses), as well as the ways you can use to spend it. Spending physical money is intuitive, but to spend Bitcoin, users need to provide the correct _private key_. We will explain this in more detail throughout the course, but what you should know for now is that this public-private key dynamic is part of what makes Bitcoin secure and trustless. Your key pair information is saved in the `wallet.dat` file, in addition to data about preferences and transactions. For the most part, you won't have to worry about that private key: `bitcoind` will use it when it's needed. However, this makes the `wallet.dat` file extremely important: if you lose it, you lose your private keys, and if you lose your private keys, you lose your funds!
|
||||
> 📖 ***What is a Bitcoin wallet?*** A Bitcoin wallet is the digital equivalent of a physical wallet. It stores information on the amount of bitcoins you have and where it's located (addresses), as well as the ways you can use to spend it. Spending physical money is intuitive, but to spend Bitcoin, users need to provide the correct _private key_. We will explain this in more detail throughout the course, but what you should know for now is that this public-private key dynamic is part of what makes Bitcoin secure and trustless. Your key pair information is saved in the `wallet.dat` file, in addition to data about preferences and transactions. For the most part, you won't have to worry about that private key: `bitcoind` will use it when it's needed. However, this makes the `wallet.dat` file extremely important: if you lose it, you lose your private keys, and if you lose your private keys, you lose your funds!
|
||||
|
||||
You now have a Bitcoin wallet. But you can't receive funds with a wallet. For that you need an address, which is a specific repository for funds, derived from the private key information in your wallet: its one private key can generate many addresses.
|
||||
|
||||
@ -123,7 +123,7 @@ Note that this address begins with an "tb1", which [means](https://en.bitcoin.it
|
||||
|
||||
Take careful note of the address. You'll need to give it to whomever will be sending you funds.
|
||||
|
||||
> :book: ***What is a Bitcoin address?*** A Bitcoin address is literally where you receive money. It's like an email address, but for funds. It's based on a public key, though different address schemes adjust that in different ways. Unlike an email address, a Bitcoin address should be considered single use: use it to receive funds just _once_. When you want to receive funds from someone else or at some other time, generate a new address. This is suggested in large part to improve your privacy. The whole blockchain is immutable, which means that explorers can look at long chains of transactions over time, making it possible to statistically determine who you and your contacts are, no matter how careful you are. If you keep reusing the same address, then this becomes even easier.
|
||||
> 📖 ***What is a Bitcoin address?*** A Bitcoin address is literally where you receive money. It's like an email address, but for funds. It's based on a public key, though different address schemes adjust that in different ways. Unlike an email address, a Bitcoin address should be considered single use: use it to receive funds just _once_. When you want to receive funds from someone else or at some other time, generate a new address. This is suggested in large part to improve your privacy. The whole blockchain is immutable, which means that explorers can look at long chains of transactions over time, making it possible to statistically determine who you and your contacts are, no matter how careful you are. If you keep reusing the same address, then this becomes even easier.
|
||||
|
||||
By creating your first Bitcoin address, you've also begun to fill in your Bitcoin wallet. More precisely, you've begun to fill the `wallet.dat` file in the appropriate `~/.bitcoin/signet /wallets/` directory. With a single address in hand, you could jump straight [§3.6: Receiving a Transaction](03_6_Receiving_a_Transaction.md) and begin receiving funds. However, before we get there, we're going to briefly discuss backing up your wallet and a few optional wallet commands that you might want to use in the future.
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ Private keys are what make the Bitcoin world go round. They're used to generate
|
||||
|
||||
The HD wallet, which is short for the Hierarchical Deterministic Wallet, was defined in [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki). It's a hierarchical design where a single "seed" generates an extended private key, which includes not just the private key but also a "chain code" that can be used to create descendents of that key. The key and chain code can be used to deterministically generate chains of keys (and therefore addresses) for a variety of purposes. A Bitcoin HD wallet will typically have individual chains of keys (and addresses) for a variety of different address types. But, they can all be restored from that seed (or from that master extended private key) because of their determinism: the addresses are always created in the same way provided that you have the same starting points (your master extended private key and a specific index [0,1,...,n] for a specific type of address).
|
||||
|
||||
> :book: ***What is a BIP?*** A BIP is a Bitcoin Improvement Proposal. It's an in-depth suggestion for a change to the Bitcoin Core code. Often, when a BIP has been sufficiently discussed and updated, it will become an actual part of the Bitcoin Core code. BIP-32 is one of many examples.
|
||||
> 📖 ***What is a BIP?*** A BIP is a Bitcoin Improvement Proposal. It's an in-depth suggestion for a change to the Bitcoin Core code. Often, when a BIP has been sufficiently discussed and updated, it will become an actual part of the Bitcoin Core code. BIP-32 is one of many examples.
|
||||
|
||||
## Understand Descriptor Wallets
|
||||
|
||||
@ -16,15 +16,15 @@ Most of this course presumes that you're working entirely from a single node whe
|
||||
|
||||
HD wallets offered a big step forward for managing this sort of interoperability, because they allowed you to load a single seed (or master extended private key) into a new wallet rather than having to move over a whole bag of keys. A few formats have been introduced to make it easy to move HD wallets, starting with seed phrases and the `xpub` and `xprv` formats. But they quickly proved inadequate. Seed phrases only defined the seed, not what it was used for. The `xprv` (and `xpub`) improved on that by defining the root of an HD tree, but they were very specific to a certain type of address. When a new address type was created, a new format was needed, resulting in the `yprv` and `ypub` formats. Then a third address type resulted in the creation of `zprv` and `zpub`. The system was quickly growing unmanageable. A new format was needed that described not just the extended keys, but also which address types they would be used to create. Because if you didn't have that, a new wallet would have to test a master extended public key against _every possible type of address_ and that was going to be very inefficient and time-consuming and still introduced the likelihood of losing funds.
|
||||
|
||||
> :book: **What is a seed phase?** A collection of mnemonic words can define a seed. That seed is then used to generate an extended private key. Seed phrases are not currently used by Bitcoin Core, but they are in wide use in the larger Bitcoin ecosystem.
|
||||
> 📖 **What is a seed phase?** A collection of mnemonic words can define a seed. That seed is then used to generate an extended private key. Seed phrases are not currently used by Bitcoin Core, but they are in wide use in the larger Bitcoin ecosystem. Future chapters will talk about how to use third-party tools to transform seed phrases into keys that can be imported into `bitcoin-cli`.
|
||||
|
||||
> :book: ***What is xprv?*** Xprv stands for extended private key. This is the combination of a private key and a chain code. It's a private key that a whole sequence of children private keys can be derived from.
|
||||
> 📖 ***What is xprv?*** Xprv stands for extended private key. This is the combination of a private key and a chain code. It's a private key that a whole sequence of children private keys can be derived from.
|
||||
|
||||
> :book: ***What is xpub?*** Xpub stands for extended public key. This is the combination of a public key and a chain code. It's a public key that a whole sequence of children public keys can be derived from.
|
||||
> 📖 ***What is xpub?*** Xpub stands for extended public key. This is the combination of a public key and a chain code. It's a public key that a whole sequence of children public keys can be derived from.
|
||||
|
||||
Enter, at last, the descriptor wallet. A descriptor wallet collects together "output descriptors" (sometimes called "wallet descriptors") which each either define one address or for a special "ranged descriptor" a whole array of addresses, each at a separate index. They do so through the specification of a format that includes: a function (which defines how to unlock the Bitcoin at the address), a derivation path (which defines the purpose of an address, which mostly links it to a specific standard), either the master extended public key or the master extended private key, and a checksum to make sure that nothing has been corrupted.
|
||||
|
||||
> :book: ***What is a Derivation Path?*** When you have hierarchical keys, you need to be able to define individual keys as descendents of the master key. For example `[0]` is the 0th key of the master key, `[0/1]` is the first son of the 0th key, `[0/1/1]` is the first grandson of the first son of the 0th key. Some keys also contain a `'` or `h` after the number, to show they're hardened, which protects them from a specific attack that could otherwise be used to derive a private key from a public key. You don't need to worry about the specifics, other than the fact that a derivation path like `[0/1/1/0/0]` describes a path down through a hierarchical tree and that descriptor wallets run specific calculations to deterministically determine the right address for a specific position in a tree. A derivation path defines a key, which means that a key represents a derivation path. They're equivalent.
|
||||
> 📖 ***What is a Derivation Path?*** When you have hierarchical keys, you need to be able to define individual keys as descendents of the master key. For example `[0]` is the 0th key of the master key, `[0/1]` is the first son of the 0th key, `[0/1/1]` is the first grandson of the first son of the 0th key. Some keys also contain a `'` or `h` after the number, to show they're hardened, which protects them from a specific attack that could otherwise be used to derive a private key from a public key. You don't need to worry about the specifics, other than the fact that a derivation path like `[0/1/1/0/0]` describes a path down through a hierarchical tree and that descriptor wallets run specific calculations to deterministically determine the right address for a specific position in a tree. A derivation path defines a key, which means that a key represents a derivation path. They're equivalent.
|
||||
|
||||
The derivation path allows you to calculate the right key from the master extended key, but it's the introduction of functions into descriptors that makes them particularly powerful, because they allows descriptors to serve a number of different types of past, present, and future addresses (which we'll meet in [§3.5](03_5_Understanding_the_Address.md)).
|
||||
|
||||
@ -266,7 +266,7 @@ $ bitcoin-cli deriveaddresses "wpkh([e18dae20/84h/1h/0h]tpubDC4ujMbsd9REzpGk3gnT
|
||||
```
|
||||
This example shows the derivation of addresses from the BIP-84 ranged descriptor up through index "2". If you check this against the addresses created in [§3.3](03_3_Setting_Up_Your_Wallet.md), you'll see they're just the same. Which is of course the whole point of descriptors! They are deterministically derived in the same way every time. The main purpose of this function would be to export addresses to other services (for example, if you wanted to export watch-only addresses to another wallet-app).
|
||||
|
||||
> :book: ***What is a watch-only address?*** A watch-only address allows you to watch for transactions related to an address (or to a whole family of addresses if you used a ranged descriptor), but not to spend funds on those addresses.
|
||||
> 📖 ***What is a watch-only address?*** A watch-only address allows you to watch for transactions related to an address (or to a whole family of addresses if you used a ranged descriptor), but not to spend funds on those addresses.
|
||||
|
||||
## Import a Descriptor
|
||||
|
||||
@ -294,7 +294,7 @@ We've now unlocked the full power of descriptors by both importing and exporting
|
||||
|
||||
Descriptors let you pass public keys and private keys among wallets, but more than that, they allow you to precisely and correctly define addresses and derive addresses of a lot of different sorts from a standardized description format. They're the heart of Bitcoin Core's descriptor wallets.
|
||||
|
||||
> :fire: ***What is the power of descriptors?*** Descriptors allow you to import and export keys and addresses. That's great if you want to move between different wallets. As a developer, they also allow you to build up the precise sort of addresses that you're interested in creating.
|
||||
> 🔥 ***What is the power of descriptors?*** Descriptors allow you to import and export keys and addresses. That's great if you want to move between different wallets. As a developer, they also allow you to build up the precise sort of addresses that you're interested in creating.
|
||||
|
||||
## What's Next?
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ SegWit came out of the Blocksize War of the '10s, where Bitcoin developers and u
|
||||
|
||||
The specifics aren't that important. What is important is that P2WPKH, and a few other SegWit addresses that we'll meet shortly, are the default type of address; when you created an address in [§3.3](03_3_Setting_Up_Your_Wallet.md), you created a P2WPKH.
|
||||
|
||||
> :book: **What is a fork?** A fork is a change to the Bitcoin protocol. This isn't a change to how one application (like Bitcoin Core) works, it's a change to how all of the members of the Bitcoin network agree to interact with each other. A hard fork makes new transactions incompatible with old transactions. It essentially creates two versions of Bitcoin (and most often has been used to actually create a new cryptocurrency). A soft fork ensures that old transactions remain compatible.
|
||||
> 📖 **What is a fork?** A fork is a change to the Bitcoin protocol. This isn't a change to how one application (like Bitcoin Core) works, it's a change to how all of the members of the Bitcoin network agree to interact with each other. A hard fork makes new transactions incompatible with old transactions. It essentially creates two versions of Bitcoin (and most often has been used to actually create a new cryptocurrency). A soft fork ensures that old transactions remain compatible.
|
||||
|
||||
### The Rest of the Addresses
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ To do anything more, you need to get some money. On signet this is done through
|
||||
|
||||
To use a faucet, you'll usually need to go to a URL and copy and paste in your address. Afterward, a transaction will be created that sends money from the faucet to you.
|
||||
|
||||
> :book: ***What is a transaction?*** A transaction is a bitcoin exchange. The owner of some bitcoins uses his private key to access those coins, then locks the transaction using the recipient's public key, at least for a P2WPKH transaction.
|
||||
> 📖 ***What is a transaction?*** A transaction is a bitcoin exchange. The owner of some bitcoins uses his private key to access those coins, then locks the transaction using the recipient's public key, at least for a P2WPKH transaction.
|
||||
|
||||
> :link: **SIGNET vs MAINNET:** Sadly, there are no faucets in real life. If you were playing on the mainnet, you'd need to go and actually buy bitcoins at a bitcoin exchange or ATM, or you'd need to get someone to send them to you. Signet life is much easier.
|
||||
|
||||
@ -23,9 +23,9 @@ But wait, there's no balance yet!?
|
||||
|
||||
Welcome to the world of Bitcoin latency. The problem is that your transaction hasn't yet been recorded in a block!
|
||||
|
||||
> :book: ***What is a block?*** Transactions are transmitted across the network and gathered into blocks by miners. These blocks are secured with a mathematical proof-of-work, which proves that computing power has been expended as part of the block creation. It's that proof-of-work (multiplied over many blocks, each built atop the last) that ultimately keeps Bitcoin secure.
|
||||
> 📖 ***What is a block?*** Transactions are transmitted across the network and gathered into blocks by miners. These blocks are secured with a mathematical proof-of-work, which proves that computing power has been expended as part of the block creation. It's that proof-of-work (multiplied over many blocks, each built atop the last) that ultimately keeps Bitcoin secure.
|
||||
|
||||
> :book: ***What is a miner?*** A miner is a participant of the Bitcoin network who works to create blocks. It's a paying job: when a miner successfully creates a block, they are paid a one-time reward plus the fees for the transactions in his block. Mining is big business. Miners tend to run on special hardware, accelerated in ways that make it more likely that they'll be able to create blocks. They also tend to be part of mining pools, where the miners all agree to share out the rewards when one of them successfully creates a block.
|
||||
> 📖 ***What is a miner?*** A miner is a participant of the Bitcoin network who works to create blocks. It's a paying job: when a miner successfully creates a block, they are paid a one-time reward plus the fees for the transactions in his block. Mining is big business. Miners tend to run on special hardware, accelerated in ways that make it more likely that they'll be able to create blocks. They also tend to be part of mining pools, where the miners all agree to share out the rewards when one of them successfully creates a block.
|
||||
|
||||
You might have to wait patiently for those funds. Some faucets have a waiting queue before they'll distribute funds, and in any case it takes 10 minutes to make every block, even if a faucet sent a transaction immediately, it might take 10 minutes to arrive. Eventually, however, you should see funds:
|
||||
```
|
||||
@ -33,13 +33,13 @@ $ bitcoin-cli getbalance
|
||||
0.00500090
|
||||
```
|
||||
|
||||
> :book: **Is Ten Minutes the Rule?** Ten minutes is the average amount of time it should take to generate a Bitcoin block. On Signet, it's pretty close to the rule, because the whole point of Signet is to have a regular, reliable testing environment. On Mainnet, the block time depends on when someone can randomly solve the tough proof-of-work problem that allows them to create a block. Sometimes it might take 30 minutes to generate a block, and then suddenly two more arrive a few minutes later each. Over time, the difficulty of the proof-of-work problem is moved up or down to bring the average back to 10 minutes per block.
|
||||
> 📖 **Is Ten Minutes the Rule?** Ten minutes is the average amount of time it should take to generate a Bitcoin block. On Signet, it's pretty close to the rule, because the whole point of Signet is to have a regular, reliable testing environment. On Mainnet, the block time depends on when someone can randomly solve the tough proof-of-work problem that allows them to create a block. Sometimes it might take 30 minutes to generate a block, and then suddenly two more arrive a few minutes later each. Over time, the difficulty of the proof-of-work problem is moved up or down to bring the average back to 10 minutes per block.
|
||||
|
||||
### Gain Confidence in Your Money
|
||||
|
||||
You can use `bitcoin-cli getbalance "*" [n]`, where you replace `[n]` with an integer, to see if a confirmed balance is 'n' blocks deep.
|
||||
|
||||
> :book: ***What is block depth?*** After a block is built and confirmed, another block is built on top of it, and another ... Because this is a stochastic process, there's some chance for reversal when a block is still new. Therefore, a block has to be buried several blocks deep in a chain before you can feel totally confident in your funds. Since each of those blocks tends to be built in an average of 10 minutes, it usually takes about an hour for a confirmed transaction to receive six blocks deep, which is the measure for full confidence in Bitcoin.
|
||||
> 📖 ***What is block depth?*** After a block is built and confirmed, another block is built on top of it, and another ... Because this is a stochastic process, there's some chance for reversal when a block is still new. Therefore, a block has to be buried several blocks deep in a chain before you can feel totally confident in your funds. Since each of those blocks tends to be built in an average of 10 minutes, it usually takes about an hour for a confirmed transaction to receive six blocks deep, which is the measure for full confidence in Bitcoin.
|
||||
|
||||
The following shows that our transactions have been confirmed one time, but not twice:
|
||||
```
|
||||
@ -145,7 +145,7 @@ $ bitcoin-cli listunspent
|
||||
```
|
||||
Note that bitcoins are not just a homogeneous mess of cash jammed into your pocket. Each individual transaction that you receive or that you send is placed into the immutable blockchain ledger, in a block. You can see these individual transactions when you look at your unspent money. This means that bitcoin spending isn't quite as anonymous as you'd think. Though the addresses are fairly private, transactions can be examined as they go in and out of addresses. This makes privacy vulnerable to statistical analysis. It also introduces some potential non-fungibility to bitcoins, as you can track back through series of transactions, even if you can't track a specific "bitcoin".
|
||||
|
||||
> :book: ***Why are all of these bitcoin amounts in decimals?*** Bitcoins are produced slowly, and so there are relatively few in circulation. As a result, each bitcoin over on the mainnet is worth quite a bit (~ $67,000 at the time of this writing). This means that people usually work in fractional amounts. In fact, the .005 in Signet coins would be worth about $300 if they were on the mainnet. For this reason, names have appeared for smaller amounts of bitcoins, including millibitcoins or mBTCs (one-thousandth of a bitcoin), microbitcoins or bits or μBTCs (one-millionth of a bitcoin), and satoshis (one hundred millionth of a bitcoin).
|
||||
> 📖 ***Why are all of these bitcoin amounts in decimals?*** Bitcoins are produced slowly, and so there are relatively few in circulation. As a result, each bitcoin over on the mainnet is worth quite a bit (~ $67,000 at the time of this writing). This means that people usually work in fractional amounts. In fact, the .005 in Signet coins would be worth about $300 if they were on the mainnet. For this reason, names have appeared for smaller amounts of bitcoins, including millibitcoins or mBTCs (one-thousandth of a bitcoin), microbitcoins or bits or μBTCs (one-millionth of a bitcoin), and satoshis (one hundred millionth of a bitcoin).
|
||||
|
||||
## Examine Your Transaction
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ tb1qhed3ausdjr6crntypcqjv6l2n2vtv2qv7dednu
|
||||
```
|
||||
You can then use this variable in other commands which require the address (or do similar for any other complex output). The rest of this tutorial will use this style of saving information to variables when it's practical.
|
||||
|
||||
> :book: ***When is it not practical to use command-line variables?*** Command-line variables aren't practical if you need to use the information somewhere other than on the command line. For example, saving an address may not actually be useful if you're just going to have to send it to someone else in an email. In addition, some future commands will output JSON objects instead of simple information, and variables can't be used to capture that information ... at least not without a _little_ more work.
|
||||
> 📖 ***When is it not practical to use command-line variables?*** Command-line variables aren't practical if you need to use the information somewhere other than on the command line. For example, saving an address may not actually be useful if you're just going to have to send it to someone else in an email. In addition, some future commands will output JSON objects instead of simple information, and variables can't be used to capture that information ... at least not without a _little_ more work.
|
||||
|
||||
## Summary: Using Command-Line Variables
|
||||
|
||||
|
||||
@ -235,7 +235,7 @@ Why would you do this? Mainly to sweep a wallet.
|
||||
|
||||
To send coins the easy way, make sure your transaction defaults are rationale, get an address, and send coins there. That's why they call it easy! Besides using `sendtoaddress`, you can also use `sendall`, but only if you want to empty a wallet!
|
||||
|
||||
> :fire: ***What is the power of sending coins the easy way?***
|
||||
> 🔥 ***What is the power of sending coins the easy way?***
|
||||
|
||||
> _The advantages._ It's easy. You don't have to worry about arcane things like UTXOs. You don't have to calculate transaction fees by hand, so you're not likely to make mistakes that cost you large amount`s of money. If your sole goal is to sit down at your computer and send some money, this is the way to go.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ You're now ready to create Bitcoin raw transactions. This allows you to send mon
|
||||
|
||||
Before you dive into actually creating raw transactions, you should make sure you understand how a Bitcoin transaction works. It's all about the UTXOs.
|
||||
|
||||
> :book: ***What is a UTXO?*** When you receive cash in your Bitcoin wallet, it appears as an individual transaction: a singular blob. Each of these transactions is called a Unspent Transaction Output (UTXO). It doesn't matter if various payments were made to the same address or to multiple addresses: each incoming transaction remains distinct in your wallet as a UTXO.
|
||||
> 📖 ***What is a UTXO?*** When you receive cash in your Bitcoin wallet, it appears as an individual transaction: a singular blob. Each of these transactions is called a Unspent Transaction Output (UTXO). It doesn't matter if various payments were made to the same address or to multiple addresses: each incoming transaction remains distinct in your wallet as a UTXO.
|
||||
|
||||
When you create a new outgoing transaction, you gather together one or more UTXOs, each of which represents a blob of money that you received. You use these as inputs for a new transaction. Together their amount must equal what you want to spend _or more_. Then, you generate one or more outputs, which give the money represented by the inputs to one or more people. This creates new UTXOs for the recipients, which may then use _those_ to fund future transactions.
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ $ sudo apt-get install jq
|
||||
|
||||
If that works, you're done!
|
||||
|
||||
> :book: ***What is JQ?*** The repository explains it best, saying "jq is like sed for JSON data - you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text."
|
||||
> 📖 ***What is JQ?*** The repository explains it best, saying "jq is like sed for JSON data - you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text."
|
||||
|
||||
Otherwise, you can download JQ from a [Github repository](https://stedolan.github.io/jq/). Just download a binary for Linux, OS X, or Windows, as appropriate.
|
||||
|
||||
|
||||
@ -207,7 +207,7 @@ This also might be a good time to revisit a blockchain explorer, so that you can
|
||||
|
||||
To send coins with raw transactions, you need to create a raw transaction with one or more inputs (to have sufficient funds) and one or more outputs (to retrieve change). Then, you can follow your normal procedure of using `createrawtransaction` with named arguments and JQ, as laid out in previous sections.
|
||||
|
||||
> :fire: ***What is the power of sending coins with raw transactions?***
|
||||
> 🔥 ***What is the power of sending coins with raw transactions?***
|
||||
|
||||
> _The advantages._ It gives you the best control. If your goal is to write a more intricate Bitcoin script or program, you'll probably use raw transactions so that you know exactly what's going on. That is also the _safest_ situation in which to use raw transactions, because you can programmatically ensure that you don't make mistakes.
|
||||
|
||||
|
||||
@ -244,7 +244,7 @@ $ bitcoin-cli -named fundrawtransaction hexstring=$nolock
|
||||
|
||||
If you must send funds with raw transactions then `fundrawtransaction` gives you a nice alternative where fees, inputs, and outputs are calculated for you, so you don't accidentally lose a bunch of money.
|
||||
|
||||
> :fire: ***What is the power of sending coins with automated raw transactions?***
|
||||
> 🔥 ***What is the power of sending coins with automated raw transactions?***
|
||||
|
||||
> _The advantages._ It provides a nice balance. If you're sending funds by hand and `sendtoaddress` doesn't offer enough control for whatever reason, you can get some of the advantages of raw transactions without the dangers. This methodology should be used whenever possible if you're sending raw transactions by hand.
|
||||
|
||||
|
||||
@ -8,35 +8,43 @@ You should _always_ watch to ensure that your transactions go out. `bitcoin-cli
|
||||
|
||||
The following shows a transaction that has not been put into a block. You can tell this because it has no confirmations.
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=fa2ddf84a4a632586d435e10880a2921db6310dfbd6f0f8f583aa0feacb74c8e
|
||||
$ bitcoin-cli -named gettransaction txid=1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654
|
||||
{
|
||||
"amount": -0.00020000,
|
||||
"fee": -0.00001000,
|
||||
"amount": -0.00100000,
|
||||
"fee": -0.00000141,
|
||||
"confirmations": 0,
|
||||
"trusted": true,
|
||||
"txid": "fa2ddf84a4a632586d435e10880a2921db6310dfbd6f0f8f583aa0feacb74c8e",
|
||||
"txid": "1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654",
|
||||
"wtxid": "d98414f5627f10337c9c2f4ff096a4ec5d15b91898ebf3fac3fa21b9ad299740",
|
||||
"walletconflicts": [
|
||||
],
|
||||
"time": 1592953220,
|
||||
"timereceived": 1592953220,
|
||||
"bip125-replaceable": "no",
|
||||
"mempoolconflicts": [
|
||||
],
|
||||
"time": 1773350380,
|
||||
"timereceived": 1773350380,
|
||||
"bip125-replaceable": "yes",
|
||||
"details": [
|
||||
{
|
||||
"address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx",
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.00020000,
|
||||
"vout": 0,
|
||||
"fee": -0.00001000,
|
||||
"amount": -0.00100000,
|
||||
"vout": 1,
|
||||
"fee": -0.00000141,
|
||||
"abandoned": false
|
||||
}
|
||||
],
|
||||
"hex": "02000000014cda1f42a1bd39d8d0ff5958a804bc2bc548b71d7ceadbde53ea15aeaf1e2691000000006a473044022016a7a9f045a0f6a52129f48adb7da35c2f54a0741d6614e9d55b8a3bc3e1490a0220391e9085a3697bc790e94bb924d5310e16f23489d9c600864a32674e871f523c01210278608b54b8fb0d8379d3823d31f03a7c6ab0adffb07dd3811819fdfc34f8c132ffffffff02204e000000000000160014751e76e8199196d454941c45d1b3a323f1433bd6e8030000000000001600146c45d3afa8762086c4bd76d8a71ac7c976e1919600000000"
|
||||
"hex": "02000000000101b345bc2c6d1410c949c25edbdd96eecea02a0675f2c561d473b8a58b8e88a8735d01000000fdffffff02741b06000000000016001499981dc044f0b3f893d27cb4b246dd65ffd8bde7a086010000000000160014447fde1e37d97255b5821d2dee816e8f18f6bac90247304402200391dde68ab21714f3ff352a4ef0c38b038d5bf6695787ad2c0583dc5b80b7110220581985bb88df2b452e188a60a558b2b26d47d1e0adc9c60d7d7eb569419e9d920121021b78fa3ed908a1ed1c2623a2311015b347de707d507d147dc0e83d84ec06255200000000",
|
||||
"lastprocessedblock": {
|
||||
"hash": "0000000d73256bcfb06de6e894d8f9e481af1143ac60a072cbeb1878ef7cacf7",
|
||||
"height": 295310
|
||||
}
|
||||
}
|
||||
```
|
||||
A transaction can be considered stuck if it stays in this state for an extended amount of time. Not too many years ago, you could be sure that every transaction would go out _eventually_. But, that's no longer the case due to the increased usage of Bitcoin. Now, if a transaction is stuck too long, it will drop out of the mempool and then be lost from the Bitcoin network.
|
||||
A transaction can be considered stuck if it stays in this state for an extended amount of time. Early on, you could be sure that every transaction would go out _eventually_. But, that's no longer the case due to the increased usage of Bitcoin. Now, if a transaction is stuck too long, it will drop out of the mempool and then be lost from the Bitcoin network.
|
||||
|
||||
> :book: ***What is mempool?*** Mempool (or Memory Pool) is a pool of all unconfirmed transactions at a bitcoin node. These are the transactions that a node has received from the p2p network which are not yet included in a block. Each bitcoin node can have a slightly different set of transactions in its mempool: different transactions might have propogated to a specific node. This depends on when the node was last started and also its limits on how much it's willing to store. When a miner makes a block, he uses transactions from his mempool. Then, when a block is verified, all the miners remove the transactions it contains from their pools. As of Bitcoin 0.12, unconfirmed transactions can also expire from mempools if they're old enough, typically, 72 hours, and as of version 0.14.0 eviction time was increased to 2 weeks. Mining pools might have their own mempool-management mechanisms.
|
||||
> 📖 ***What is mempool?*** Mempool (or Memory Pool) is a pool of all unconfirmed transactions at a bitcoin node. These are the transactions that a node has received from the peer-to-peer network which are not yet included in a block. Each bitcoin node can have a slightly different set of transactions in its mempool: different transactions might have propogated to a specific node. This depends on when the node was last started and also its limits on how much it's willing to store. When a miner makes a block, they use transactions from their own mempool. Then, when a block is verified, all the miners remove the transactions that block contains from their individual pools. Most mempools will not keep unconfirmed transactions for longer than two weeks, and that number could drop dramatically (to as low as a few days) in times of congestion.
|
||||
|
||||
This list of all [unconfirmed transactions](https://blockchain.info/unconfirmed-transactions) might not match any individual machine's mempool, but it should (mostly) be a superset of them.
|
||||
This list of all [unconfirmed transactions on the mainnet](https://blockchain.info/unconfirmed-transactions) might not match any individual machine's mempool, but it should (mostly) be a superset of them.
|
||||
|
||||
## Decide What to Do
|
||||
|
||||
@ -44,16 +52,21 @@ If your transaction is stuck longer than you want, you can typically do one of f
|
||||
|
||||
**1. Wait Until it Clears.** If you sent your transaction with a low or medium fee, it should eventually go through. As shown at [Mempool Space](https://mempool.space), those with lower fees _will_ get delayed. (Take a look at the leftmost transaction, and see how long it's been waiting and how much it paid for its fee.)
|
||||
|
||||
**2. Wait Until it Expires.** If you accidentally sent with no transaction fee, or if any number or other conditions are met, then your transaction might never go through. However, your coins aren't lost. As long as you don't have a wallet that purposefully resends unconfirmed transactions, it should clear from the mempool in three days or so, and then you can try again.
|
||||
**2. Wait Until it Expires.** If you accidentally sent with no transaction fee, or if any number or other conditions are met, then your transaction might never go through. However, your coins aren't lost. As long as you don't have a wallet that purposefully resends unconfirmed transactions, it should eventually clear from the mempool, and then you can try again.
|
||||
|
||||
**3. Use RBF as the Sender.** If you are the sender of the transaction, and you opted-in to RBF (Replace-By-Fee), then you can try again with a higher fee. See [§5.2: Resending a Transaction with RBF](05_2_Resending_a_Transaction_with_RBF.md).
|
||||
|
||||
**4. Use CPFP as the Receiver.** Alternatively, if you are the receiver of the transaction, you can use CPFP (Child-pays-for-parent) to use the unconfirmed transaction as an input to a new transaction. See [§5.3: Funding a Transaction with CPFP](05_3_Funding_a_Transaction_with_CPFP.md).
|
||||
**4. Use CPFP as the Receiver.** Alternatively, if you are the receiver of the transaction, you can use CPFP (Child-pays-for-parent) to use the unconfirmed transaction as an input to a new transaction. See [§5.3: Funding a Transaction with CPFP](05_3_Funding_a_Transaction_with_CPFP.md)
|
||||
|
||||
## Summary: Watching for Stuck Transactions
|
||||
|
||||
This is an introduction to the power of Bitcoin transactions. If you know that a transaction is stuck, then you can decide to free it up with features like RBF or CPFP.
|
||||
|
||||
| Role | Feature | Section |
|
||||
|-------|----------|-----|
|
||||
| Sender | RBF | §5.2 |
|
||||
| Recipient | CPFP | §5.3 |
|
||||
|
||||
## What's Next?
|
||||
|
||||
Continue "Controlling Bitcoin Transactions" with [§5.2: Resending a Transaction with RBF](05_2_Resending_a_Transaction_with_RBF.md).
|
||||
|
||||
@ -1,151 +1,340 @@
|
||||
TODO: This is now a default per updates in 24, 29. You don't need to verify any more. (Check that works, and redocument)
|
||||
|
||||
# 5.2: Resending a Transaction with RBF
|
||||
|
||||
If your Bitcoin transaction is stuck, and you're the sender, you can resend it using RBF (replace-by-fee). However, that's not all that RBF can do: it's generally a powerful and multipurpose feature that allows Bitcoin senders to recreate transactions for a variety of reasons.
|
||||
If your Bitcoin transaction is stuck, and you're the sender, you can _replace_ (resend) it using RBF (replace-by-fee). However, that's not all that RBF can do: it's generally a powerful and multipurpose feature that allows Bitcoin senders to recreate transactions for a variety of reasons.
|
||||
|
||||
## Opt-In for RBF
|
||||
## Understand Opt-In RBF vs Full RBF
|
||||
|
||||
RBF is an opt-in Bitcoin feature. Transactions are only eligible for using RBF if they've been created with a special RBF flag. This is done by setting any of the transaction's UTXO sequence numbers (which are typically set automatically), so that it's more than 0 and less than 0xffffffff-1 (4294967294).
|
||||
There are currently two versions of RBF that are present on the Bitcoin network: opt-in RBF and full RBF. Both do the same thing: they allow you to replace an existing unconfirmed transaction with a newer transaction that has a higher fee (and so is more likely to be confirmed).
|
||||
|
||||
This is accomplished simply by adding a `sequence` variable to your UTXO inputs:
|
||||
```
|
||||
$ rawtxhex=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout', "sequence": 1 } ]''' outputs='''{ "'$recipient'": 0.00007658, "'$changeaddress'": 0.00000001 }''')
|
||||
```
|
||||
You should of course sign and send your transaction as usual:
|
||||
```
|
||||
$ signedtx=$(bitcoin-cli -named signrawtransactionwithwallet hexstring=$rawtxhex | jq -r '.hex')
|
||||
$ bitcoin-cli -named sendrawtransaction hexstring=$signedtx
|
||||
5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375
|
||||
```
|
||||
Now, when you look at your transaction, you should see something new: the `bip125-replaceable` line, which has always been marked `no` before, is now marked `yes`:
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375
|
||||
|
||||
{
|
||||
"amount": 0.00000000,
|
||||
"fee": -0.00000141,
|
||||
"confirmations": 0,
|
||||
"trusted": true,
|
||||
"txid": "5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375",
|
||||
"walletconflicts": [
|
||||
],
|
||||
"time": 1592954399,
|
||||
"timereceived": 1592954399,
|
||||
"bip125-replaceable": "yes",
|
||||
"details": [
|
||||
],
|
||||
"hex": "02000000000101fa364ad3cbdb08dd0b83aac009a42a9ed00594acd6883d2a466699996cd69d8b01000000000100000002ea1d000000000000160014d591091b8074a2375ed9985a9c4b18efecfd416501000000000000001600146c45d3afa8762086c4bd76d8a71ac7c976e1919602473044022077007dff4df9ce75430e3065c82321dca9f6bdcfd5812f8dc0daeb957d3dfd1602203a624d4e9720a06def613eeea67fbf13ce1fb6188d3b7e780ce6e40e859f275d0121038a2702938e548eaec28feb92c7e4722042cfd1ea16bec9fc274640dc5be05ec500000000"
|
||||
}
|
||||
```
|
||||
The `bip125-replaceable` flag will stay `yes` until the transaction receives confirmations. At that point, it is no longer replaceable.
|
||||
* **Opt-In RBF** is the older version of RBF, originally defined by [BIP-125](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki). It required you to signal in a transaction that the transaction could later be replaced if needed. Without the signal in the original transaction, RBF was not allowed.
|
||||
* **Full RBF** was introduced by Bitcoin Core as an option in 2022 and became the default in additional updates from 2024-2025. It allows any unconfirmed transaction to be updated with RBF, even without the opt-in signal.
|
||||
|
||||
> :book: ***Should I trust transactions with no confirmations?*** No, never. This was true before RBF and it was true after RBF. Transactions must receive confirmations before they are trustworthy. This is especially true if a transaction is marked as `bip125-replaceable`, because then it can be ... replaced.
|
||||
Both versions of RBF still exist on the network and as of this writing [opt-in RBF transactions tend to outnumber full RBF transactions](https://mempool.space/rbf). This may just be because many wallets got into the habit of opting in to RBF for all transactions, because you never knew when you'd have to replace one, but it also may be because RBF is ultimately a node policy: each node (each miner, each bitcoind, etc) gets to decide whether they will accept a replaced RBF transaction or not: if enough nodes reject an RBF transaction because it doesn't have an opt-in, it fails.
|
||||
|
||||
> :information_source: **NOTE — SEQUENCE:** This is the first use of the `nSequence` value in Bitcoin. You can set it between 1 and 0xffffffff-2 (4294967293) and enable RBF, but if you're not careful you can run up against the parallel use of `nSequence` for relative timelocks. We suggest always setting it to "1", which is what Bitcoin Core does, but the other option is to set it to a value between 0xf0000000 (4026531840) and 0xffffffff-2 (4294967293). Setting it to "1" effectively makes relative timelocks irrelevent and setting it to 0xf0000000 or higher deactivates them. This is all explained further in [§11.3: Using CSV in Scripts](11_3_Using_CSV_in_Scripts.md). For now, just choose one of the non-conflicting values for `nSequence`.
|
||||
There is almost certainly enough acceptance of Full RBF today for transactions to be replaceable even without the RBF flag, and it's almost certainly safer to include the RBF flag anyway, because it's simple to do as a default. As a result, this section will talk about how the RBF opt-in flag is set on Bitcoin transactions and then how to replace transactions with RBF (whether the flag was set on the original transaction or not).
|
||||
|
||||
### Optional: Always Opt-In for RBF
|
||||
## Understand the Sequence Variable
|
||||
|
||||
If you prefer, you can _always_ opt in for RBF. Do so by running your `bitcoind` with the `-walletrbf` command. Once you've done this (and restarted your `bitcoind`), then all UTXOs should have a lower sequence number and the transaction should be marked as `bip125-replaceable`.
|
||||
Satoshi Nakamoto originally allowed for replacement of Bitcoin transactions using the `sequence` variable (usually called `nSequence`), which is set on the inputs to a transactions. The idea was that a larger sequence should be used as a replacement if a previous sequence had not been confirmed. If was simple and it was quickly tossed out for a variety of reasons.
|
||||
|
||||
When RBF came around as a new version of transaction replacement, it went back to the existing `sequence` variable, but with some new mechanics:
|
||||
|
||||
* A `sequence` that was larger than 0 and less than than 0xffffffff-1 (4294967294) opted in to RBF.
|
||||
* The opt-in only required one input to have its `sequence`. If most of a transaction's inputs were set to disallow RBF, but a single input enabled RBF, then RBF was allowed.
|
||||
* If RBF was allowed on a transaction, it could then later be replaced.
|
||||
|
||||
That was it! With RBF enabled, transactions could be replaced; with RBF disabled, transactions could not. (Except today, all transactios can be replaced, _in theory_.)
|
||||
|
||||
> ℹ️ **Sequence Usage (v1).** This is the first use of the `sequence` value in Bitcoin. You can set it between 1 and 0xffffffff-2 (4294967293) and enable RBF, but if you're not careful you can run up against the parallel use of `sequence` for relative timelocks. We suggest always setting it to "0xffffffff-2", which is what Bitcoin Core does, but the other option is to set it to to "1" or to a value between 0xf0000000 (4026531840) and 0xffffffff-2 (4294967293). Setting `sequence` to "1" effectively makes relative timelocks irrelevent and setting it to 0xf0000000 or higher deactivates them. This is all explained in later sections. For now, just choose one of the non-conflicting values for `sequence`.
|
||||
|
||||
## Understand How RBF Works
|
||||
|
||||
The RBF functionality is based on [BIP 125](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki), which lists the following rules for using RBF:
|
||||
Here's the complete sequence of how RBF works, summarised from BIP-125. It's probably more than you need to know:
|
||||
|
||||
> 1. The original transactions signal replaceability explicitly or through inheritance as described in the above Summary section.
|
||||
1. The original transaction must signal replaceability (or more recently is always allowed).
|
||||
2. The new transaction fee must be higher than the original.
|
||||
3. The new transaction must not have any new unconfirmed inputs (and it must share at least one input with the original).
|
||||
4. The new transaction must pay double the relay fees (which are a minor fee related to the cost of transmitting transactions, and are usually ignored here because of their small size).
|
||||
5. No more than 100 transactions and descendents can be replaced at one time.
|
||||
|
||||
This means that the sequence number must be set to less than 0xffffffff-1. (4294967294), or the same is true of unconfirmed parent transactions.
|
||||
The core thing to understand about RBF is that in order to use it, you must double-spend. As noted, you're reusing one or more of the UTXOs that were in your original transaction. Just sending another transaction with a different UTXO to the same recipient won't do the trick (and will likely result in your losing money). Instead, you must purposefully create a conflict, where the same UTXO is used in two different transactions. Faced with this conflict, the miners will know to use the conflicted transaction with the higher fee, and they'll be incentivized to do so by that higher fee.
|
||||
|
||||
> 2. The replacement transaction pays an absolute higher fee than the sum paid by the original transactions.
|
||||
> 3. The replacement transaction does not contain any new unconfirmed inputs that did not previously appear in the mempool. (Unconfirmed inputs are inputs spending outputs from currently unconfirmed transactions.)
|
||||
> 4. The replacement transaction must pay for its own bandwidth in addition to the amount paid by the original transactions at or above the rate set by the node's minimum relay fee setting. For example, if the minimum relay fee is 1 satoshi/byte and the replacement transaction is 500 bytes total, then the replacement must pay a fee at least 500 satoshis higher than the sum of the originals.
|
||||
> 5. The number of original transactions to be replaced and their descendant transactions which will be evicted from the mempool must not exceed a total of 100 transactions.
|
||||
> 📖 ***What is a double-spend?*** A double-spend occurs when someone sends the same electronic funds to two different people (or, to the same person twice, in two different transactions). This is a central problem for any e-cash system. It's solved in Bitcoin by the immutable ledger: once a transaction is sufficiently confirmed, no miners will verify transactions that reuse the same UTXO. However, it's possible to double-spend _before_ a transaction has been confirmed — which is why you always want one or more confirmations before you finalize a transaction. In the case of RBF, you purposefully double-spend because an initial transaction has stalled, and the miners accept your double-spend if you meet the specific criteria laid out by BIP 125.
|
||||
|
||||
The other thing to understand about RBF is that in order to use it, you must double-spend, reusing one or more the same UTXOs. Just sending another transaction with a different UTXO to the same recipient won't do the trick (and will likely result in your losing money). Instead, you must purposefully create a conflict, where the same UTXO is used in two different transactions.
|
||||
## Check the Sequence Variable
|
||||
|
||||
Faced with this conflict, the miners will know to use the one with the higher fee, and they'll be incentivized to do so by that higher fee.
|
||||
You can check the `sequence` variable of a transaction by looking at the `verbose` format of `gettransaction`.
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654 verbose=true
|
||||
{
|
||||
"amount": -0.00100000,
|
||||
"fee": -0.00000141,
|
||||
"confirmations": 1,
|
||||
"blockhash": "0000000c1dc879a623845990aae757f8e38c83474c4a0e1de9cb988cef69f15f",
|
||||
"blockheight": 295311,
|
||||
"blockindex": 50,
|
||||
"blocktime": 1773350929,
|
||||
"txid": "1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654",
|
||||
"wtxid": "d98414f5627f10337c9c2f4ff096a4ec5d15b91898ebf3fac3fa21b9ad299740",
|
||||
"walletconflicts": [
|
||||
],
|
||||
"mempoolconflicts": [
|
||||
],
|
||||
"time": 1773350380,
|
||||
"timereceived": 1773350380,
|
||||
"bip125-replaceable": "no",
|
||||
"details": [
|
||||
{
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.00100000,
|
||||
"vout": 1,
|
||||
"fee": -0.00000141,
|
||||
"abandoned": false
|
||||
}
|
||||
],
|
||||
"hex": "02000000000101b345bc2c6d1410c949c25edbdd96eecea02a0675f2c561d473b8a58b8e88a8735d01000000fdffffff02741b06000000000016001499981dc044f0b3f893d27cb4b246dd65ffd8bde7a086010000000000160014447fde1e37d97255b5821d2dee816e8f18f6bac90247304402200391dde68ab21714f3ff352a4ef0c38b038d5bf6695787ad2c0583dc5b80b7110220581985bb88df2b452e188a60a558b2b26d47d1e0adc9c60d7d7eb569419e9d920121021b78fa3ed908a1ed1c2623a2311015b347de707d507d147dc0e83d84ec06255200000000",
|
||||
"decoded": {
|
||||
"txid": "1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654",
|
||||
"hash": "d98414f5627f10337c9c2f4ff096a4ec5d15b91898ebf3fac3fa21b9ad299740",
|
||||
"version": 2,
|
||||
"size": 222,
|
||||
"vsize": 141,
|
||||
"weight": 561,
|
||||
"locktime": 0,
|
||||
"vin": [
|
||||
{
|
||||
"txid": "73a8888e8ba5b873d461c5f275062aa0ceee96dddb5ec249c910146d2cbc45b3",
|
||||
"vout": 349,
|
||||
"scriptSig": {
|
||||
"asm": "",
|
||||
"hex": ""
|
||||
},
|
||||
"txinwitness": [
|
||||
"304402200391dde68ab21714f3ff352a4ef0c38b038d5bf6695787ad2c0583dc5b80b7110220581985bb88df2b452e188a60a558b2b26d47d1e0adc9c60d7d7eb569419e9d9201",
|
||||
"021b78fa3ed908a1ed1c2623a2311015b347de707d507d147dc0e83d84ec062552"
|
||||
],
|
||||
"sequence": 4294967293
|
||||
}
|
||||
],
|
||||
"vout": [
|
||||
{
|
||||
"value": 0.00400244,
|
||||
"n": 0,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 99981dc044f0b3f893d27cb4b246dd65ffd8bde7",
|
||||
"desc": "addr(tb1qnxvpmszy7zel3y7j0j6ty3kavhla30088mrk3d)#e4e0tqst",
|
||||
"hex": "001499981dc044f0b3f893d27cb4b246dd65ffd8bde7",
|
||||
"address": "tb1qnxvpmszy7zel3y7j0j6ty3kavhla30088mrk3d",
|
||||
"type": "witness_v0_keyhash"
|
||||
}
|
||||
},
|
||||
{
|
||||
"value": 0.00100000,
|
||||
"n": 1,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 447fde1e37d97255b5821d2dee816e8f18f6bac9",
|
||||
"desc": "addr(tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn)#zau8pzqg",
|
||||
"hex": "0014447fde1e37d97255b5821d2dee816e8f18f6bac9",
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"type": "witness_v0_keyhash"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"lastprocessedblock": {
|
||||
"hash": "0000000c1dc879a623845990aae757f8e38c83474c4a0e1de9cb988cef69f15f",
|
||||
"height": 295311
|
||||
}
|
||||
}
|
||||
```
|
||||
As you can see, the single input for the transaction has an `sequence` value of `4294967293`. RBF is allowed (and relative timelocks are not).
|
||||
|
||||
> :book: ***What is a double-spend?*** A double-spend occurs when someone sends the same electronic funds to two different people (or, to the same person twice, in two different transactions). This is a central problem for any e-cash system. It's solved in Bitcoin by the immutable ledger: once a transaction is sufficiently confirmed, no miners will verify transactions that reuse the same UTXO. However, it's possible to double-spend _before_ a transaction has been confirmed — which is why you always want one or more confirmations before you finalize a transaction. In the case of RBF, you purposefully double-spend because an initial transaction has stalled, and the miners accept your double-spend if you meet the specific criteria laid out by BIP 125.
|
||||
You might also notice a related value, `bip125-replaceable`, which is a `bitcoin-cli` shorthand that tells you whether a transaction can be replaced by RBF. To be eligible, the transaction must have a `sequence` variable in the appropriate range, and it must not be confirmed. (This `bip125-replaceable` is set to `no` because the transaction has a confirmation. No more replacement at that point!)
|
||||
|
||||
> :warning: **WARNING:** Some early discussions of this policy suggested that the `nSequence` number also be increased. This in fact was the intended use of `nSequence` in its original form. This is _not_ a part of the published policy in BIP 125. In fact, increasing your sequence number can accidentally lock your transaction with a relative timelock, unless you use sequence numbers in the range of 0xf0000000 (4026531840) to 0xffffffff-2 (4294967293).
|
||||
You can also use `decoderawtransaction` to view the `sequence` variable in slightly terser form:
|
||||
```
|
||||
$ bitcoin-cli decoderawtransaction $rawtxhex3
|
||||
{
|
||||
"txid": "1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654",
|
||||
"hash": "1050f6e2d68e7e4555bd682f24157f9bb19f666cf2ba1d1b3ff959ff4f893654",
|
||||
"version": 2,
|
||||
"size": 113,
|
||||
"vsize": 113,
|
||||
"weight": 452,
|
||||
"locktime": 0,
|
||||
"vin": [
|
||||
{
|
||||
"txid": "73a8888e8ba5b873d461c5f275062aa0ceee96dddb5ec249c910146d2cbc45b3",
|
||||
"vout": 349,
|
||||
"scriptSig": {
|
||||
"asm": "",
|
||||
"hex": ""
|
||||
},
|
||||
"sequence": 4294967293
|
||||
}
|
||||
],
|
||||
"vout": [
|
||||
{
|
||||
"value": 0.00400244,
|
||||
"n": 0,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 99981dc044f0b3f893d27cb4b246dd65ffd8bde7",
|
||||
"desc": "addr(tb1qnxvpmszy7zel3y7j0j6ty3kavhla30088mrk3d)#e4e0tqst",
|
||||
"hex": "001499981dc044f0b3f893d27cb4b246dd65ffd8bde7",
|
||||
"address": "tb1qnxvpmszy7zel3y7j0j6ty3kavhla30088mrk3d",
|
||||
"type": "witness_v0_keyhash"
|
||||
}
|
||||
},
|
||||
{
|
||||
"value": 0.00100000,
|
||||
"n": 1,
|
||||
"scriptPubKey": {
|
||||
"asm": "0 447fde1e37d97255b5821d2dee816e8f18f6bac9",
|
||||
"desc": "addr(tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn)#zau8pzqg",
|
||||
"hex": "0014447fde1e37d97255b5821d2dee816e8f18f6bac9",
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"type": "witness_v0_keyhash"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Reset the Sequence Variable
|
||||
|
||||
The above examples drew from a default transaction created by `bitcoin-cli` . The sequence was already (by default!) set to "4294967293". By default, Bitcoin Core now flags all transactions with the RBF opt-in flag, so RBF is always allowed; whether other nodes use Full RBF or not, you'll be able to replace your transactions originally generated with `bitcoin-cli`.
|
||||
|
||||
However, you can chose to change this behavior. To do so, you create a raw transaction as described in [§4.2](04_2_Creating_a_Raw_Transaction.md), but you add a `sequence` variable to the `txid` and `vout` that you already have for one of the inputs. Since RBF is now on by default, you'd either be setting this to `0` to turn it off (though there's little purpose when Full RBF is widely accepted on the 'net), or to some other value to allow timelocks (more on that in chapter 8).
|
||||
```
|
||||
$ seqtx=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout', "sequence": 0 } ]''' outputs='''{ "'$recipient'": 0.001, "'$changeaddress'": 0.003 }''')
|
||||
```
|
||||
If you're just dealing with RBF, there's no point in doing this, but you'll need to in the future for other purposes.
|
||||
|
||||
## Replace a Transaction the Hard Way: By Hand
|
||||
|
||||
In order to create an RBF transaction by hand, all you have to do is create a raw transaction that: (1) replaces a previous raw transaction that opted-in to RBF and that is not confirmed; (2) reuses one or more of the same UTXOs; (3) increases fees; and (4) pays the minimum bandwidth of both transactions [which already may be taken care of by (3)].
|
||||
You now know how to enable RBF: it's probably allowed by Full RBF and it's probably allowed because your `sequence` variable is set to a value between 1 and 4294967293, but if it weren't, you could set the `sequence` by hand when you created a transaction. But how do you actually use RBF to replace an existing transaction?
|
||||
|
||||
The following example just reuses our existing variables, but decreases the amount sent to the change address, to increase the fee from the accidental 0 BTC of the original transaction to an overly generous 0.01 BTC in the new transaction:
|
||||
In order to create replacement RBF transaction by hand, all you have to do is create a raw transaction that: (1) replaces a previous raw transaction that is not confirmed; (2) reuses one or more of the same UTXOs; (3) increases fees; and (4) pays the minimum bandwidth of both transactions [which is probably already taken care of by (3)].
|
||||
|
||||
Here's an example of sending a transaction with a very low fee:
|
||||
```
|
||||
$ rawtxhex=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout', "sequence": 1 } ]''' outputs='''{ "'$recipient'": 0.000075, "'$changeaddress'": 0.00000001 }''')
|
||||
```
|
||||
We of course must re-sign it and resend it:
|
||||
```
|
||||
$ signedtx=$(bitcoin-cli -named signrawtransactionwithwallet hexstring=$rawtxhex | jq -r '.hex')
|
||||
$ seqtx=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout' } ]''' outputs='''{ "'$recipient'": 0.001, "'$changeaddress'": 0.003002 }''')
|
||||
$ signedtx=$(bitcoin-cli -named signrawtransactionwithwallet hexstring=$seqtx | jq -r '.hex')
|
||||
$ bitcoin-cli -named sendrawtransaction hexstring=$signedtx
|
||||
c6de60427b28d8ec8102e49771e5d0348fc3ef6a5bf02eb864ec745105a6951b
|
||||
cffcebcb841e4177a682527c8a10a7f7b1889d827b095c55f946d68ab8195508
|
||||
```
|
||||
You can now look at your original transaction and see that it has `walletconflicts`:
|
||||
Realizing the problem, we then resend it with a better fee using at least one of the same UTXOs. We do that by decreasing the change amount; as we saw previously, any remaining funds always pay the transaction fee.
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375
|
||||
{
|
||||
"amount": 0.00000000,
|
||||
"fee": -0.00000141,
|
||||
"confirmations": 0,
|
||||
"trusted": false,
|
||||
"txid": "5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375",
|
||||
"walletconflicts": [
|
||||
"c6de60427b28d8ec8102e49771e5d0348fc3ef6a5bf02eb864ec745105a6951b"
|
||||
],
|
||||
"time": 1592954399,
|
||||
"timereceived": 1592954399,
|
||||
"bip125-replaceable": "yes",
|
||||
"details": [
|
||||
],
|
||||
"hex": "02000000000101fa364ad3cbdb08dd0b83aac009a42a9ed00594acd6883d2a466699996cd69d8b01000000000100000002ea1d000000000000160014d591091b8074a2375ed9985a9c4b18efecfd416501000000000000001600146c45d3afa8762086c4bd76d8a71ac7c976e1919602473044022077007dff4df9ce75430e3065c82321dca9f6bdcfd5812f8dc0daeb957d3dfd1602203a624d4e9720a06def613eeea67fbf13ce1fb6188d3b7e780ce6e40e859f275d0121038a2702938e548eaec28feb92c7e4722042cfd1ea16bec9fc274640dc5be05ec500000000"
|
||||
}
|
||||
$ seqtx=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout' } ]''' outputs='''{ "'$recipient'": 0.001, "'$changeaddress'": 0.0029 }''')
|
||||
$ signedtx=$(bitcoin-cli -named signrawtransactionwithwallet hexstring=$seqtx | jq -r '.hex')
|
||||
$ bitcoin-cli -named sendrawtransaction hexstring=$signedtx
|
||||
eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149
|
||||
```
|
||||
This represents the fact that two different transactions are both trying to use the same UTXO.
|
||||
That's all that's required to use RBF in the modern day where RBF is turned on by default by most wallets, and where Full RBF would be available it it weren't!
|
||||
|
||||
Initially `listtransactions` demonstrates both transactions:
|
||||
```
|
||||
$ bitcoin-cli listtransactions
|
||||
[
|
||||
{
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.00100000,
|
||||
"vout": 0,
|
||||
"fee": -0.00000044,
|
||||
"confirmations": 0,
|
||||
"trusted": false,
|
||||
"txid": "cffcebcb841e4177a682527c8a10a7f7b1889d827b095c55f946d68ab8195508",
|
||||
"wtxid": "ded34ab60bdc9cd298348c91929bcee3f0458ccd5cef3f51cc95b5fa80318fe4",
|
||||
"walletconflicts": [
|
||||
"eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149"
|
||||
],
|
||||
"mempoolconflicts": [
|
||||
"eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149"
|
||||
],
|
||||
"time": 1773354920,
|
||||
"timereceived": 1773354920,
|
||||
"bip125-replaceable": "yes",
|
||||
"abandoned": false
|
||||
},
|
||||
{
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.00100000,
|
||||
"vout": 0,
|
||||
"fee": -0.00010244,
|
||||
"confirmations": 0,
|
||||
"trusted": true,
|
||||
"txid": "eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149",
|
||||
"wtxid": "4715973d9aed02a3f26c42eb81f1077f464421ea50505152782f792f855d8756",
|
||||
"walletconflicts": [
|
||||
"cffcebcb841e4177a682527c8a10a7f7b1889d827b095c55f946d68ab8195508"
|
||||
],
|
||||
"mempoolconflicts": [
|
||||
],
|
||||
"time": 1773354943,
|
||||
"timereceived": 1773354943,
|
||||
"bip125-replaceable": "yes",
|
||||
"abandoned": false
|
||||
}
|
||||
]
|
||||
```
|
||||
As shown, they're listed as `bip125-replaceable` (which means that the RBF opt-in flag is set, so we don't even have to fall back on Full RBF) and that they have `conflicts`, both in the `wallet` and the `mempool` (because they use the same UTXO!)
|
||||
|
||||
Eventually, the transaction with the larger fee should be accepted:
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=c6de60427b28d8ec8102e49771e5d0348fc3ef6a5bf02eb864ec745105a6951b
|
||||
$ bitcoin-cli -named gettransaction txid=eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149
|
||||
{
|
||||
"amount": 0.00000000,
|
||||
"fee": -0.00000299,
|
||||
"amount": -0.00100000,
|
||||
"fee": -0.00010244,
|
||||
"confirmations": 2,
|
||||
"blockhash": "0000000000000055ac4b6578d7ffb83b0eccef383ca74500b00f59ddfaa1acab",
|
||||
"blockheight": 1773266,
|
||||
"blockindex": 9,
|
||||
"blocktime": 1592955002,
|
||||
"txid": "c6de60427b28d8ec8102e49771e5d0348fc3ef6a5bf02eb864ec745105a6951b",
|
||||
"blockhash": "00000003be7eb7f4eb252441a0eda9cc55ef7ae8342995d8151eea3409885c24",
|
||||
"blockheight": 295314,
|
||||
"blockindex": 2,
|
||||
"blocktime": 1773355616,
|
||||
"txid": "eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149",
|
||||
"wtxid": "4715973d9aed02a3f26c42eb81f1077f464421ea50505152782f792f855d8756",
|
||||
"walletconflicts": [
|
||||
"5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375"
|
||||
"cffcebcb841e4177a682527c8a10a7f7b1889d827b095c55f946d68ab8195508"
|
||||
],
|
||||
"time": 1592954467,
|
||||
"timereceived": 1592954467,
|
||||
"mempoolconflicts": [
|
||||
],
|
||||
"time": 1773354943,
|
||||
"timereceived": 1773354943,
|
||||
"bip125-replaceable": "no",
|
||||
"details": [
|
||||
{
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.00100000,
|
||||
"vout": 0,
|
||||
"fee": -0.00010244,
|
||||
"abandoned": false
|
||||
}
|
||||
],
|
||||
"hex": "02000000000101fa364ad3cbdb08dd0b83aac009a42a9ed00594acd6883d2a466699996cd69d8b010000000001000000024c1d000000000000160014d591091b8074a2375ed9985a9c4b18efecfd416501000000000000001600146c45d3afa8762086c4bd76d8a71ac7c976e1919602473044022077dcdd98d85f6247450185c2b918a0f434d9b2e647330d741944ecae60d6ff790220424f85628cebe0ffe9fa11029b8240d08bdbfcc0c11f799483e63b437841b1cd0121038a2702938e548eaec28feb92c7e4722042cfd1ea16bec9fc274640dc5be05ec500000000"
|
||||
"hex": "020000000001015436894fff59f93f1b1dbaf26c669fb19b7f15242f68bd55457e8ed6e2f650100000000000fdffffff02a086010000000000160014447fde1e37d97255b5821d2dee816e8f18f6bac9d06c0400000000001600147b1212b39c2796ae73b726e192aa207c334ce52f02473044022016edca707550fddb4457778865cad3a18bc50025e34c59858bce01f18649788102202f0075018f6a4db8b713b939d56a452c56645d5b51b6a93242c3532fd432709e0121036d3ef06bbf57ab531fcc457b79176bea87e322db5e7d254d8702c6e59c5d3b9c00000000",
|
||||
"lastprocessedblock": {
|
||||
"hash": "000000145528df59836e3e85e619b399f4b95352cb39d4c3db706d5dbab0ae44",
|
||||
"height": 295315
|
||||
}
|
||||
}
|
||||
```
|
||||
Now the `mempoolconflicts` are gone and that `bip125-replaceable` is set to `no` because of the confirmation.
|
||||
|
||||
Meanwhile, the original transaction with the lower fee starts picking up negative confirmations, to show its divergence from the blockchain:
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375
|
||||
$ bitcoin-cli -named gettransaction txid=cffcebcb841e4177a682527c8a10a7f7b1889d827b095c55f946d68ab8195508
|
||||
{
|
||||
"amount": 0.00000000,
|
||||
"fee": -0.00000141,
|
||||
"amount": -0.00100000,
|
||||
"fee": -0.00000044,
|
||||
"confirmations": -2,
|
||||
"trusted": false,
|
||||
"txid": "5b953a0bdfae0d11d20d195ea43ab7c31a5471d2385c258394f3bb9bb3089375",
|
||||
"txid": "cffcebcb841e4177a682527c8a10a7f7b1889d827b095c55f946d68ab8195508",
|
||||
"wtxid": "ded34ab60bdc9cd298348c91929bcee3f0458ccd5cef3f51cc95b5fa80318fe4",
|
||||
"walletconflicts": [
|
||||
"c6de60427b28d8ec8102e49771e5d0348fc3ef6a5bf02eb864ec745105a6951b"
|
||||
"eb9980a5a6dc5b7859bb5b455e6dea8a71c1906a390edcd2a5acc6051c4a8149"
|
||||
],
|
||||
"time": 1592954399,
|
||||
"timereceived": 1592954399,
|
||||
"mempoolconflicts": [
|
||||
],
|
||||
"time": 1773354920,
|
||||
"timereceived": 1773354920,
|
||||
"bip125-replaceable": "yes",
|
||||
"details": [
|
||||
{
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.00100000,
|
||||
"vout": 0,
|
||||
"fee": -0.00000044,
|
||||
"abandoned": false
|
||||
}
|
||||
],
|
||||
"hex": "02000000000101fa364ad3cbdb08dd0b83aac009a42a9ed00594acd6883d2a466699996cd69d8b01000000000100000002ea1d000000000000160014d591091b8074a2375ed9985a9c4b18efecfd416501000000000000001600146c45d3afa8762086c4bd76d8a71ac7c976e1919602473044022077007dff4df9ce75430e3065c82321dca9f6bdcfd5812f8dc0daeb957d3dfd1602203a624d4e9720a06def613eeea67fbf13ce1fb6188d3b7e780ce6e40e859f275d0121038a2702938e548eaec28feb92c7e4722042cfd1ea16bec9fc274640dc5be05ec500000000"
|
||||
"hex": "020000000001015436894fff59f93f1b1dbaf26c669fb19b7f15242f68bd55457e8ed6e2f650100000000000fdffffff02a086010000000000160014447fde1e37d97255b5821d2dee816e8f18f6bac9a8940400000000001600147b1212b39c2796ae73b726e192aa207c334ce52f0247304402206d52697eab994b764ffae5220d06c4e867a9ceff609c79a3338de78e0ca427e802202d42489c026e2c28ac4b3c3fb7262fadabe944485994b696c07fe88a922e765f0121036d3ef06bbf57ab531fcc457b79176bea87e322db5e7d254d8702c6e59c5d3b9c00000000",
|
||||
"lastprocessedblock": {
|
||||
"hash": "000000145528df59836e3e85e619b399f4b95352cb39d4c3db706d5dbab0ae44",
|
||||
"height": 295315
|
||||
}
|
||||
}
|
||||
```
|
||||
Our recipients have their money, and the original, failed transaction will eventually fall out of the mempool.
|
||||
@ -154,55 +343,59 @@ Our recipients have their money, and the original, failed transaction will event
|
||||
|
||||
Raw transactions are very powerful, and you can do a lot of interesting things by combining them with RBF. However, sometimes _all_ you want to do is free up a transaction that's been hanging. You can now do that with a simple command, `bumpfee`.
|
||||
|
||||
For example, to increase the fee of transaction `4460175e8276d5a1935f6136e36868a0a3561532d44ddffb09b7cb878f76f927` you would run:
|
||||
For example, to increase the fee of transaction `1c12afac570292e99b4aed34c0452513b4ab8b7397e6a803e98a53b606e31c11` you would run:
|
||||
```
|
||||
$ bitcoin-cli -named bumpfee txid=4460175e8276d5a1935f6136e36868a0a3561532d44ddffb09b7cb878f76f927
|
||||
$ bitcoin-cli -named bumpfee 1c12afac570292e99b4aed34c0452513b4ab8b7397e6a803e98a53b606e31c11
|
||||
{
|
||||
"txid": "75208c5c8cbd83081a0085cd050fc7a4064d87c7d73176ad9a7e3aee5e70095f",
|
||||
"origfee": 0.00000000,
|
||||
"fee": 0.00022600,
|
||||
"txid": "938d3755a91efbeead1dda30c0b808986410db1078f02500fc512a0ff6704872",
|
||||
"origfee": 0.00000100,
|
||||
"fee": 0.00000806,
|
||||
"errors": [
|
||||
]
|
||||
}
|
||||
```
|
||||
The result is the automatic generation of a new transaction that has a fee determined by your bitcoin.conf file:
|
||||
The result is the automatic generation of a new transaction that has a fee determined by your bitcoin.conf file. The new transaction can be discovered by looking at `listtransactions` and then examined with `gettransaction`
|
||||
```
|
||||
$ bitcoin-cli -named gettransaction txid=75208c5c8cbd83081a0085cd050fc7a4064d87c7d73176ad9a7e3aee5e70095f
|
||||
$ bitcoin-cli gettransaction 938d3755a91efbeead1dda30c0b808986410db1078f02500fc512a0ff6704872
|
||||
{
|
||||
"amount": -0.10000000,
|
||||
"fee": -0.00022600,
|
||||
"amount": -0.00010000,
|
||||
"fee": -0.00000806,
|
||||
"confirmations": 0,
|
||||
"trusted": false,
|
||||
"txid": "75208c5c8cbd83081a0085cd050fc7a4064d87c7d73176ad9a7e3aee5e70095f",
|
||||
"trusted": true,
|
||||
"txid": "938d3755a91efbeead1dda30c0b808986410db1078f02500fc512a0ff6704872",
|
||||
"wtxid": "73afdafc1c8f77d51597beafba472e5241e9266e4a93dfbaf00bc8f5807384a5",
|
||||
"walletconflicts": [
|
||||
"4460175e8276d5a1935f6136e36868a0a3561532d44ddffb09b7cb878f76f927"
|
||||
"1c12afac570292e99b4aed34c0452513b4ab8b7397e6a803e98a53b606e31c11"
|
||||
],
|
||||
"time": 1491605676,
|
||||
"timereceived": 1491605676,
|
||||
"mempoolconflicts": [
|
||||
],
|
||||
"time": 1773356653,
|
||||
"timereceived": 1773356653,
|
||||
"bip125-replaceable": "yes",
|
||||
"replaces_txid": "4460175e8276d5a1935f6136e36868a0a3561532d44ddffb09b7cb878f76f927",
|
||||
"replaces_txid": "1c12afac570292e99b4aed34c0452513b4ab8b7397e6a803e98a53b606e31c11",
|
||||
"details": [
|
||||
{
|
||||
"account": "",
|
||||
"address": "n2eMqTT929pb1RDNuqEnxdaLau1rxy3efi",
|
||||
"address": "tb1qg3lau83hm9e9tdvzr5k7aqtw3uv0dwkfct4xdn",
|
||||
"category": "send",
|
||||
"amount": -0.10000000,
|
||||
"vout": 0,
|
||||
"fee": -0.00022600,
|
||||
"amount": -0.00010000,
|
||||
"vout": 1,
|
||||
"fee": -0.00000806,
|
||||
"abandoned": false
|
||||
}
|
||||
],
|
||||
"hex": "02000000014e843e22cb8ee522fbf4d8a0967a733685d2ad92697e63f52ce41bec8f7c8ac0020000006b48304502210094e54afafce093008172768d205d99ee2e9681b498326c077f0b6a845d9bbef702206d90256d5a2edee3cab1017b9b1c30b302530b0dd568e4af6f2d35380bbfaa280121029f39b2a19943fadbceb6697dbc859d4a53fcd3f9a8d2c8d523df2037e7c32a71010000000280969800000000001976a914e7c1345fc8f87c68170b3aa798a956c2fe6a9eff88ac38f25c05000000001976a914c101d8c34de7b8d83b3f8d75416ffaea871d664988ac00000000"
|
||||
"hex": "0200000000010149814a1c05c6aca5d2dc0e396a90c1718aea6d5e455bbb59785bdca6a58099eb0100000000fdffffff029a420400000000001600147b1212b39c2796ae73b726e192aa207c334ce52f1027000000000000160014447fde1e37d97255b5821d2dee816e8f18f6bac90247304402204c080988284fcc0f4b825c97a046df7f6ddbe5276cd76059ece272d18a3a8ab6022009cbb87b2707b899356958b4fc0d61319b61659cda8847ba184bd678c3f2535201210302b2db8ca5241f14879051ee01413643da8d798cb348ace49ea7d71d3e135bb794810400",
|
||||
"lastprocessedblock": {
|
||||
"hash": "0000000c96de4354c533b4459f2b86581871825ce25f8797bb04425e68d49fdc",
|
||||
"height": 295316
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Summary: Resending a Transaction with RBF
|
||||
|
||||
If a transaction is stuck, and you don't want to wait for it to expire entirely, if you opted-in to RBF, then you can double-spend using RBF to create a replacement transaction (or just use `bumpfee`).
|
||||
If a transaction is stuck, and you don't want to wait for it to expire entirely, then you can double-spend using RBF to create a replacement transaction (or just use `bumpfee`). You used to have to opt in, but now most wallets opt-in by default, and even if they didn't Full RBF should be available.
|
||||
|
||||
> :fire: ***What is the power of RBF?*** Obviously, RBF is very helpful if you created a transaction with too low of a fee and you need to get those funds through. However, the ability to generally replace unconfirmed transactions with updated ones has more power than just that (and is why you might want to continue using RBF with raw transactions, even following the advent of `bumpfee`).
|
||||
|
||||
> For example, you might send a transaction, and then before it's confirmed, combine it with a second transaction. This allows you to compress multiple transactions down into a single one, decreasing overall fees. It might also offer benefits to privacy. There are other reasons to use RBF too, for smart contracts or transaction cut-throughs, as described in the [Opt-in RBF FAQ](https://bitcoincore.org/en/faq/optin_rbf/).
|
||||
> 🔥 ***What is the power of RBF?*** Obviously, RBF is very helpful if you created a transaction with too low of a fee and you need to get those funds through. However, the ability to generally replace unconfirmed transactions with updated ones has more power than just that (and is why you might want to continue using RBF with raw transactions, even following the advent of `bumpfee`). For example, you might send a transaction, and then before it's confirmed, combine it with a second transaction. This allows you to compress multiple transactions down into a single one, decreasing overall fees. It might also offer benefits to privacy. There are other reasons to use RBF too, for smart contracts or transaction cut-throughs, as described in the [Opt-in RBF FAQ](https://bitcoincore.org/en/faq/optin_rbf/).
|
||||
|
||||
## What's Next?
|
||||
|
||||
|
||||
@ -4,11 +4,11 @@ If your Bitcoin transaction is stuck, and you're the _recipient_, you can clear
|
||||
|
||||
## Understand How CPFP Works
|
||||
|
||||
RBF was all about the sender. He messed up and needed to increase the fee, or he wanted to be smart and combine transactions for a variety of reasons. It was a powerful sender-oriented feature. In some ways, CPFP is RBF's opposite, because it empowers the recipient who knows that his money hasn't arrived yet and wants to speed it up. However, it's also a much simpler feature, with less wide applicability.
|
||||
RBF was all about the sender. He messed up and needed to increase the fee, or he wanted to be smart and combine transactions for a variety of reasons. It was a powerful sender-oriented feature. In some ways, CPFP is RBF's opposite, because it empowers the recipient who knows that their money hasn't arrived yet and wants to speed it up. However, it's also a much simpler feature, with less wide applicability.
|
||||
|
||||
Basically, the idea of CPFP is that a recipient has a transaction that hasn't been confirmed in a block that he wants to spend. So, he includes that unconfirmed transaction in a new transaction and pays a high-enough fee to encourage a miner to include both the original (parent) transaction and the new (child) transaction in a block. As a result, the parent and child transactions clear simultaneously.
|
||||
Basically, the idea of CPFP is that a recipient has a transaction that hasn't been confirmed in a block and they want to spend that UTXO. So, they include that unconfirmed transaction in a new transaction and pay a high-enough fee to encourage a miner to include both the original (parent) transaction and the new (child) transaction in a block. As a result, the parent and child transactions clear simultaneously.
|
||||
|
||||
It should be noted that CPFP is not a new protocol feature, like RBF. It's just a new incentivization scheme that can be used for transaction selection by miners. This also means that it's not as reliable as a protocol change like RBF: there might be reasons that the child is not selected to be put into a block, and that will prevent the parent from ever being put into a block.
|
||||
It should be noted that CPFP is not a new protocol feature, like RBF. It's just an incentivization scheme that can be used for transaction selection by miners. This also means that it's not as reliable as a protocol change like RBF: there might be reasons that the child is not selected to be put into a block, and that will prevent the parent from ever being put into a block.
|
||||
|
||||
## Spend Unconfirmed UTXOs
|
||||
|
||||
@ -17,92 +17,88 @@ Funding a transaction with CPFP is a very simple process using the methods you'r
|
||||
1. Find the `txid` and `vout` of the unconfirmed transaction. This may be the trickiest part, as `bitcoin-cli` generally tries to protect you from unconfirmed transactions. The sender might be able to send you this info; even with just the `txid`, you should be able to figure out the `vout` in a blockchain explorer.
|
||||
|
||||
You do have one other option: use `bitcoin-cli getrawmempool`, which can be used to list the contents of your entire mempool, where the unconfirmed transactions will be. You may have to dig through several if the mempool is particularly busy. You can then get more information on a specific transaction with `bitcoin-cli getrawtransaction` with the verbose flag set to `true`:
|
||||
```
|
||||
|
||||
```
|
||||
$ bitcoin-cli getrawmempool
|
||||
[
|
||||
"95d51e813daeb9a861b2dcdddf1da8c198d06452bbbecfd827447881ff79e061"
|
||||
"72ab93c9e66f3cad39620f4689748704012b9f28acf896b348208e0fc0bafa73",
|
||||
"115ff6412b832f7292d2117708ef88eb61be6a24bd8f0360e7dd73c02cafa36c",
|
||||
"074a5055b8d3ae1282b913cd6c063911b2bc8f414eed4f44efc6a0459364dc80",
|
||||
"e5f2e728aad9aafa1eab72c3654068c50cbbd5605f850f2b8a88375e580077e0"
|
||||
]
|
||||
|
||||
$ bitcoin-cli getrawtransaction 95d51e813daeb9a861b2dcdddf1da8c198d06452bbbecfd827447881ff79e061 true
|
||||
$ bitcoin-cli getrawtransaction 115ff6412b832f7292d2117708ef88eb61be6a24bd8f0360e7dd73c02cafa36c true
|
||||
{
|
||||
"txid": "95d51e813daeb9a861b2dcdddf1da8c198d06452bbbecfd827447881ff79e061",
|
||||
"hash": "9729e47b8aee776112a82cec46df7638d112ca51856c53e238a9b1f7af3be4ce",
|
||||
"txid": "115ff6412b832f7292d2117708ef88eb61be6a24bd8f0360e7dd73c02cafa36c",
|
||||
"hash": "cbebd8db046db6a265ce1e8c5ccf2127bbdb5f13d89bca9de0f46c25d33383ed",
|
||||
"version": 2,
|
||||
"size": 247,
|
||||
"vsize": 166,
|
||||
"weight": 661,
|
||||
"locktime": 1773277,
|
||||
"size": 223,
|
||||
"vsize": 142,
|
||||
"weight": 565,
|
||||
"locktime": 295321,
|
||||
"vin": [
|
||||
{
|
||||
"txid": "7a0178472300247d423ac4a04ff9165fa5b944104f6d6f9ebc557c6d207e7524",
|
||||
"txid": "a2de81cb60a445e4766c45d168f51d4caa57990859126d2553dba84b5f6ee4ea",
|
||||
"vout": 0,
|
||||
"scriptSig": {
|
||||
"asm": "0014334f3a112df0f22e743ad97eec8195a00faa59a0",
|
||||
"hex": "160014334f3a112df0f22e743ad97eec8195a00faa59a0"
|
||||
"asm": "",
|
||||
"hex": ""
|
||||
},
|
||||
"txinwitness": [
|
||||
"304402207966aa87db340841d76d3c3596d8b4858e02aed1c02d87098dcedbc60721d8940220218aac9d728c9a485820b074804a8c5936fa3145ce68e24dcf477024b19e88ae01",
|
||||
"03574b1328a5dc2d648498fc12523cdf708efd091c28722a422d122f8a0db8daa9"
|
||||
"3044022022cd7118792474d35a4ef6b4b3189d9fa88e2c6e8e2cc953598a0b9f2004bf8702207b1e72005eec6994dc4ad9099dbb640766ae50c10ecc13729fc107fd2d7cdacf01",
|
||||
"021ab1d59b685df8373c8b5ba2fc2f1c5695a91f435df3bfbe73d7fd6797dab98a"
|
||||
],
|
||||
"sequence": 4294967294
|
||||
"sequence": 4294967293
|
||||
}
|
||||
],
|
||||
"vout": [
|
||||
{
|
||||
"value": 0.01000000,
|
||||
"value": 0.00001000,
|
||||
"n": 0,
|
||||
"scriptPubKey": {
|
||||
"asm": "OP_HASH160 f079f77f2ef0ef1187093379d128ec28d0b4bf76 OP_EQUAL",
|
||||
"hex": "a914f079f77f2ef0ef1187093379d128ec28d0b4bf7687",
|
||||
"reqSigs": 1,
|
||||
"type": "scripthash",
|
||||
"addresses": [
|
||||
"2NFAkGiwnp8wvCodRBx3smJwxncuG3hndn5"
|
||||
]
|
||||
"asm": "OP_HASH160 c524be5df153dd875bd4dc92c4b8593403c1defd OP_EQUAL",
|
||||
"desc": "addr(2NBDd84nZm882RwvKHifVMyHVzVsMDMStJr)#6c3e9nhz",
|
||||
"hex": "a914c524be5df153dd875bd4dc92c4b8593403c1defd87",
|
||||
"address": "2NBDd84nZm882RwvKHifVMyHVzVsMDMStJr",
|
||||
"type": "scripthash"
|
||||
}
|
||||
},
|
||||
{
|
||||
"value": 0.02598722,
|
||||
"value": 1.28985887,
|
||||
"n": 1,
|
||||
"scriptPubKey": {
|
||||
"asm": "OP_HASH160 8799be12fb9eae6644659d95b9602ddfbb4b2aff OP_EQUAL",
|
||||
"hex": "a9148799be12fb9eae6644659d95b9602ddfbb4b2aff87",
|
||||
"reqSigs": 1,
|
||||
"type": "scripthash",
|
||||
"addresses": [
|
||||
"2N5cDPPuCTtYq13oXw8RfpY9dHJW8sL64U2"
|
||||
]
|
||||
"asm": "0 df9bb477b0c1e15c123343ddb6001de7f3f08e4f",
|
||||
"desc": "addr(tb1qm7dmgaasc8s4cy3ng0wmvqqaulelprj0vgvyys)#qs0dv45g",
|
||||
"hex": "0014df9bb477b0c1e15c123343ddb6001de7f3f08e4f",
|
||||
"address": "tb1qm7dmgaasc8s4cy3ng0wmvqqaulelprj0vgvyys",
|
||||
"type": "witness_v0_keyhash"
|
||||
}
|
||||
}
|
||||
],
|
||||
"hex": "0200000000010124757e206d7c55bc9e6f6d4f1044b9a55f16f94fa0c43a427d2400234778017a0000000017160014334f3a112df0f22e743ad97eec8195a00faa59a0feffffff0240420f000000000017a914f079f77f2ef0ef1187093379d128ec28d0b4bf768742a727000000000017a9148799be12fb9eae6644659d95b9602ddfbb4b2aff870247304402207966aa87db340841d76d3c3596d8b4858e02aed1c02d87098dcedbc60721d8940220218aac9d728c9a485820b074804a8c5936fa3145ce68e24dcf477024b19e88ae012103574b1328a5dc2d648498fc12523cdf708efd091c28722a422d122f8a0db8daa9dd0e1b00"
|
||||
"hex": "02000000000101eae46e5f4ba8db53256d1259089957aa4c1df568d1456c76e445a460cb81dea20000000000fdffffff02e80300000000000017a914c524be5df153dd875bd4dc92c4b8593403c1defd871f2bb00700000000160014df9bb477b0c1e15c123343ddb6001de7f3f08e4f02473044022022cd7118792474d35a4ef6b4b3189d9fa88e2c6e8e2cc953598a0b9f2004bf8702207b1e72005eec6994dc4ad9099dbb640766ae50c10ecc13729fc107fd2d7cdacf0121021ab1d59b685df8373c8b5ba2fc2f1c5695a91f435df3bfbe73d7fd6797dab98a99810400"
|
||||
}
|
||||
```
|
||||
Look through the `vout` array. Find the object that matches your address. (Here, it's the only one.) The `n` value is your `vout`. You now have everything you need to create a new CPFP transaction.
|
||||
Look through the `vout` array. Find the object that matches your address. The `n` value is your `vout`. You now have everything you need to create a new CPFP transaction.
|
||||
```
|
||||
$ utxo_txid=95d51e813daeb9a861b2dcdddf1da8c198d06452bbbecfd827447881ff79e061
|
||||
$ utxo_vout=0
|
||||
$ utxo_txid=115ff6412b832f7292d2117708ef88eb61be6a24bd8f0360e7dd73c02cafa36c
|
||||
$ utxo_vout=1
|
||||
$ recipient2=$(bitcoin-cli getrawchangeaddress)
|
||||
```
|
||||
|
||||
2. Create a raw transaction using your unconfirmed transaction as an input.
|
||||
3. Double the transaction fees (or more).
|
||||
3. Double your expected transaction fees (or more). (This transaction uses a fee of about $1.41, which is ridiculous based on current fees, but definitely should be enough to free up the transaction.)
|
||||
|
||||
When you take these steps, everything should look totally normal, despite the fact that you're working with an unconfirmed transaction. To verify that all was well, we even looked at the results of our signature before we saved off the information to a variable:
|
||||
```
|
||||
$ rawtxhex=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout' } ]''' outputs='''{ "'$recipient2'": 0.03597 }''')
|
||||
|
||||
$ bitcoin-cli -named signrawtransaction hexstring=$rawtxhex | jq -r '.hex'
|
||||
02000000012b137ef780666ba214842ff6ea2c3a0b36711bcaba839c3710f763e3d9687fed000000006a473044022003ca1f6797d781ef121ba7c2d1d41d763a815e9dad52aa8bc5ea61e4d521f68e022036b992e8e6bf2c44748219ca6e0056a88e8250f6fd0794dc69f79a2e8993671601210317b163ab8c8862e09c71767112b828abd3852e315441893fa0f535de4fa39b8dffffffff01905abd07000000001976a91450b1d90a130c4f3f1e5fbfa7320fd36b7265db0488ac00000000
|
||||
$ rawtxhex=$(bitcoin-cli -named createrawtransaction inputs='''[ { "txid": "'$utxo_txid'", "vout": '$utxo_vout' } ]''' outputs='''{ "'$recipient2'": 1.28983887 }''')
|
||||
|
||||
$ signedtx=$(bitcoin-cli -named signrawtransaction hexstring=$rawtxhex | jq -r '.hex')
|
||||
$ bitcoin-cli -named sendrawtransaction hexstring=$signedtx
|
||||
6a184a2f07fa30189f4831d6f041d52653a103b3883d2bec2f79187331fd7f0e
|
||||
$ txid=$(bitcoin-cli -named sendrawtransaction hexstring=$signedtx)
|
||||
```
|
||||
|
||||
4. Crossing your fingers is not needed. You have verified your data is correct. From this point on, things are out of your hands.
|
||||
|
||||
Your transactions may go through quickly. They may not. It all depends on whether the miners who are randomly generating the current blocks have the CPFP patch or not. But you've given your transactions the best chance.
|
||||
Your transactions may go through quickly. They may not. It all depends on whether the miners who are randomly generating the current blocks support CPFP or not. But you've given your transactions the best chance.
|
||||
|
||||
That's really all there is to it.
|
||||
|
||||
@ -116,9 +112,9 @@ A _recipient_ could use CPFP even if he wasn't planning on immediately spending
|
||||
|
||||
## Summary: Funding a Transaction with CPFP
|
||||
|
||||
You can take advantage of the CPFP incentives to free up funds that have been sent to you but have not been confirmed. Just use the unconfirmed transaction as UTXO and pay a higher-than-average transaction fee.
|
||||
You can take advantage of the CPFP incentives to free up funds that have been sent to you but have not been confirmed. Just use the unconfirmed transaction as the UTXO and pay a higher-than-average transaction fee.
|
||||
|
||||
> :fire: ***What is the power of CPFP?*** Mostly, CPFP is just useful to get funds unstuck when you're the recipient and the sender isn't being helpful for whatever reason. It doesn't have the more powerful possibilities of RBF, but is an alternatve way to exert control over a transaction after it's been placed in the mempool, but before it's confirmed in a block.
|
||||
> 🔥 ***What is the power of CPFP?*** Mostly, CPFP is just useful to get funds unstuck when you're the recipient and the sender isn't being helpful for whatever reason. It doesn't have the more powerful possibilities of RBF, but is an alternatve way to exert control over a transaction after it's been placed in the mempool, but before it's confirmed in a block.
|
||||
|
||||
## What's Next?
|
||||
|
||||
|
||||
@ -0,0 +1,65 @@
|
||||
-----BEGIN PGP SIGNED MESSAGE-----
|
||||
Hash: SHA512
|
||||
|
||||
# Contributor License Agreement
|
||||
|
||||
Version 1.0
|
||||
|
||||
Name: Andrea Delle Chiaie
|
||||
|
||||
E-Mail: andrea@dellechiaie.it
|
||||
|
||||
Legal Jurisdiction: Wyoming, United States of America
|
||||
|
||||
Project: https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line
|
||||
|
||||
Date: `01/24/2026`
|
||||
|
||||
## Purpose
|
||||
|
||||
This agreement gives Blockchain Commons, LLC the permission it needs in order to accept my contributions into its open software project and to manage the intellectual property in that project over time.
|
||||
|
||||
## License
|
||||
|
||||
I hereby license Blockchain Commons, LLC to:
|
||||
|
||||
1. do anything with my contributions that would otherwise infringe my copyright in them
|
||||
|
||||
2. do anything with my contributions that would otherwise infringe patents that I can or become able to license
|
||||
|
||||
3. sublicense these rights to others on any terms they like
|
||||
|
||||
## Reliability
|
||||
|
||||
I understand that Blockchain Commons will rely on this license. I may not revoke this license.
|
||||
|
||||
## Awareness
|
||||
|
||||
I promise that I am familiar with legal rules, like ["work made for hire" rules](http://worksmadeforhire.com), that can give employers and clients ownership of intellectual property in work that I do. I am also aware that legal agreements I might sign, like confidential information and invention assignment agreements, will usually give ownership of intellectual property in my work to employers, clients, and companies that I found. If someone else owns intellectual property in my work, I need their permission to license it.
|
||||
|
||||
## Copyright Guarantee
|
||||
|
||||
I promise not to offer contributions to the project that contain copyrighted work that I do not have legally binding permission to contribute under these terms. When I offer a contribution with permission, I promise to document in the contribution who owns copyright in what work, and how they gave permission to contribute it. If I later become aware that one of my contributions may have copyrighted work of others that I did not have permission to contribute, I will notify Blockchain Commons, in confidence, immediately.
|
||||
|
||||
## Patent Guarantee
|
||||
|
||||
I promise not to offer contributions to the project that I know infringe patents of others that I do not have permission to contribute under these terms.
|
||||
|
||||
## Open Source Guarantee
|
||||
|
||||
I promise not to offer contributions that contain or depend on the work of others, unless that work is available under a license that [Blue Oak Council rates bronze or better](https://blueoakconcil.org/list), such as the MIT License, two- or three-clause BSD License, the Apache License Version 2.0, or the Blue Oak Model License 1.0.0. When I offer a contribution containing or depending on others' work, I promise to document in the contribution who licenses that work, along with copies of their license terms.
|
||||
|
||||
## Disclaimers
|
||||
|
||||
***As far as the law allows, my contributions come as is, without any warranty or condition. Other than under [Copyright Guarantee](#copyright-guarantee), [Patent Guarantee](#patent-guarantee), or [Open Source Guarantee](#open-source-guarantee), I will not be liable to anyone for any damages related to my contributions or this contributor license agreement, under any kind of legal claim.***
|
||||
|
||||
- ---
|
||||
|
||||
To sign this Contributor License Agreement, fill in `$name`, `$email`, and `$date` above. Then sign using GPG using the following command `gpg --armor --clearsign --output ./CLA-signed/CLA.YOURGITHUBNAME.YOURGPGFINGERPRINT.asc CLA.md`, then either submit your signed Contributor License Agreement to this repo as a GPG signed Pull Request or email it to [ChristopherA@BlockchainCommons.com](mailto:ChristopherA@BlockchainCommons.com).
|
||||
-----BEGIN PGP SIGNATURE-----
|
||||
|
||||
iHUEARYKAB0WIQSVRx/6DDZLsTYY/pVhl+R7J+mJCQUCaXTzFwAKCRBhl+R7J+mJ
|
||||
CT+8AQCbdoyHki5m1WBwnbKzdhl1eBoKvoNuHD+Z7O4n/4NVewEAkumn2wsfXHSP
|
||||
rtK7r/72KXxVag7G3k0rWVFhORH8Fgw=
|
||||
=tBny
|
||||
-----END PGP SIGNATURE-----
|
||||
35
README.md
35
README.md
@ -3,9 +3,13 @@
|
||||
|
||||

|
||||
|
||||
Learning Bitcoin from the Command Line is a tutorial for working with Bitcoin (and Lightning) that teaches direct interaction with the servers themselves, as the most robust and secure way to begin cryptocurrency work.
|
||||
---
|
||||
|
||||
> NOTE: This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for use.
|
||||
***In 2026, Learning Bitcoin from the Command Line is being brought up to date with a new 3.0 edition. If you want to see the work in progress, visit our [`lbtcftcl-v3.0` branch](https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line/tree/lbtcftcl-v3.0), which is already much more up-to-date than v2.2.2. But be aware it is being worked on through the end of the year, and so will not be complete or entirely coherent before then.***
|
||||
|
||||
---
|
||||
|
||||
Learning Bitcoin from the Command Line is a tutorial for working with Bitcoin (and Lightning) that teaches direct interaction with the servers themselves, as the most robust and secure way to begin cryptocurrency work.
|
||||
|
||||
_This tutorial assumes that you have some minimal background of how to use the command line interface. If not, there are many tutorials available, and I have one for Mac users at https://github.com/ChristopherA/intro-mac-command-line._
|
||||
|
||||
@ -50,7 +54,7 @@ If you'd like to make your own translation, please see [Contributing](https://gi
|
||||
* [4.6: Sending Other Types of Transactions](04_6_Sending_Coins_to_Other_Addresses.md)
|
||||
* [5.0: Controlling Bitcoin Transactions](05_0_Controlling_Bitcoin_Transactions.md)
|
||||
* [5.1 Watching for Stuck Transactions](05_1_Watching_for_Stuck_Transactions.md)
|
||||
* [5.2: Resending a Transaction with RBF](05_2_Resending_a_Transaction_with_RBF.md) [**TO UPDATE**]
|
||||
* [5.2: Resending a Transaction with RBF](05_2_Resending_a_Transaction_with_RBF.md)
|
||||
* [5.3: Funding a Transaction with CPFP](05_3_Funding_a_Transaction_with_CPFP.md)
|
||||
* [6.0: Expanding Bitcoin Transactions with Multisigs](06_0_Expanding_Bitcoin_Transactions_Multisigs.md)
|
||||
* [6.1: Sending a Transaction with a Multisig](06_1_Sending_a_Transaction_to_a_Multisig.md)
|
||||
@ -64,16 +68,10 @@ If you'd like to make your own translation, please see [Contributing](https://gi
|
||||
* [8.0: Expanding Bitcoin Transactions in Other Ways](08_0_Expanding_Bitcoin_Transactions_Other.md)
|
||||
* [8.1: Sending a Transaction with a Locktime](08_1_Sending_a_Transaction_with_a_Locktime.md)
|
||||
* [8.2: Sending a Transaction with Data](08_2_Sending_a_Transaction_with_Data.md) [**TO UPDATE**]
|
||||
* [9.0: Expanding Bitcoin Transactions with Schnorr](09_0_Expanding_Bitcoin_Transactions_with_Schnorr.md) [**TO WRITE**]
|
||||
* [9.1: Understanding Schnorr & Taproot](09_1_Understanding_Schnorr_Taproot.md) [**TO WRITE**]
|
||||
* [9.2: Sending Schnorr Signed Transactions](09_2_Sending_Schnorr_Signed_Transactions.md) [**TO WRITE**]
|
||||
* [9.3: Sending a Schnorr Multisig](09_3_Sending_a_Schnorr_Multisig.md) [**TO WRITE**]
|
||||
* [9.4: Sending FROST Signed Transactions](09_4_Sending_FROST_Signed_Transactions.md) [**TO WRITE**]
|
||||
* [10.0: Expanding Bitcoin Transactions with Taproot](10_0_Expanding_Bitcoin_Transactions_with_Taproot.md) [**TO WRITE**]
|
||||
* [10.1: Sending Basic Taproot Transactions](10_1_Sending_Basic_Taproot_Transactions.md) [**TO WRITE**]
|
||||
* [10.2: Sending Advanced Taproot Transactions](10_2_Sending_Advanced_Taproot_Transactions.md) [**TO WRITE**]
|
||||
|
||||
### PART THREE: SCRIPTING WITH BITCOIN
|
||||
### PART THREE: IMPORTING & EXPORTING YOUR SECRETS
|
||||
|
||||
### PART FOUR: SCRIPTING WITH BITCOIN
|
||||
|
||||
* [11.0: Introducing Bitcoin Scripts](11_0_Introducing_Bitcoin_Scripts.md)
|
||||
* [11.1: Understanding the Foundation of Transactions](11_1_Understanding_the_Foundation_of_Transactions.md)
|
||||
@ -102,7 +100,18 @@ If you'd like to make your own translation, please see [Contributing](https://gi
|
||||
* [16.2: Writing Complex Multisig Scripts](16_2_Writing_Complex_Multisig_Scripts.md)
|
||||
* [16.3: Empowering Bitcoin with Scripts](16_3_Empowering_Bitcoin_with_Scripts.md)
|
||||
|
||||
### PART FOUR: MAINTAINING PRIVACY
|
||||
### PART FIVE: UPGRADING TO TAPROOT
|
||||
|
||||
* [9.0: Expanding Bitcoin Transactions with Schnorr](09_0_Expanding_Bitcoin_Transactions_with_Schnorr.md) [**TO WRITE**]
|
||||
* [9.1: Understanding Schnorr & Taproot](09_1_Understanding_Schnorr_Taproot.md) [**TO WRITE**]
|
||||
* [9.2: Sending Schnorr Signed Transactions](09_2_Sending_Schnorr_Signed_Transactions.md) [**TO WRITE**]
|
||||
* [9.3: Sending a Schnorr Multisig](09_3_Sending_a_Schnorr_Multisig.md) [**TO WRITE**]
|
||||
* [9.4: Sending FROST Signed Transactions](09_4_Sending_FROST_Signed_Transactions.md) [**TO WRITE**]
|
||||
* [10.0: Expanding Bitcoin Transactions with Taproot](10_0_Expanding_Bitcoin_Transactions_with_Taproot.md) [**TO WRITE**]
|
||||
* [10.1: Sending Basic Taproot Transactions](10_1_Sending_Basic_Taproot_Transactions.md) [**TO WRITE**]
|
||||
* [10.2: Sending Advanced Taproot Transactions](10_2_Sending_Advanced_Taproot_Transactions.md) [**TO WRITE**]
|
||||
|
||||
### PART SIX: MAINTAINING PRIVACY
|
||||
|
||||
* [17.0: Using Tor](16_0_Using_Tor.md)
|
||||
* [17.1: Verifying Your Tor Setup](17_1_Verifying_Your_Tor_Setup.md)
|
||||
|
||||
70
TODO.md
70
TODO.md
@ -2,14 +2,16 @@
|
||||
|
||||
The following TODO items are intended for a 3.0 version of Learning Bitcoin from the Command Line
|
||||
|
||||
## Immediate TODO (for 3/12): Cleanup
|
||||
## Immediate TODO (for 3/26): Multisigs & Descriptors
|
||||
|
||||
1. Bring chapter 1 up to date
|
||||
2. Bring chapter 2 up to date
|
||||
3. Double check §3.1 + 3.2
|
||||
4. Put in some discussions about how we'll later import seed words, etc. into whatever chapter that is.
|
||||
5. Edit/Update Chapter 5
|
||||
6. Update RBF Discussions in §5.2 for it now being default
|
||||
1. Research new Multisig functions: enumeratesigners and displayaddress.
|
||||
2. Talk about creating different sorts of multisig addresses in §6.1
|
||||
3. New §6.2: creating descriptor multisig wallets?
|
||||
4. Consider whether to expand descriptor discussion in an earlier section for how to manipulate them
|
||||
* Might need to break chapter 3 in two and make a new section on "Creating Descriptor Addresses" or something
|
||||
5. Move §6.2 on spending to §6.3 and bring it up to date.
|
||||
6. Consider current §6.3 given most functions have been removed. Anything to save? Anything with new functions? If so, §6.4
|
||||
* See: https://github.com/bitcoin/bitcoin/issues/30175
|
||||
|
||||
## Longer-Term TODO (Small Tasks)
|
||||
|
||||
@ -19,14 +21,25 @@ The following updates involve updates or the creation of new chapters, but their
|
||||
* New Subsection: Understanding Uniform Resources
|
||||
* New Subsection: Creating an Animated QR
|
||||
* New Subsection: Creating an Animated QR of a PSBT
|
||||
1. New Chapter: Using Other Command-Line Tools [this and next before scripts?]
|
||||
* 9.1: Using seedtool
|
||||
* 9.2: Using keytool
|
||||
* 9.3: Using bytewords-cli
|
||||
* 9.4: Using envelope
|
||||
* GOALS INCLUDE: importing/transforming seed phrases; exporting/storing/SSKRing
|
||||
* Might need also chapters on what the goals are
|
||||
1. New Chapter: Using Miniscript Command-Line Tools [this and next before scripts?]
|
||||
* 15.1: Using miniscript
|
||||
* 15.2: Using Bitcoin Dev Kit (BDK)
|
||||
* 15.3: Planning for the Future
|
||||
1. Revise Section: Understanding Timelock Options (11.1)
|
||||
* Explanation: Better distinguish differences
|
||||
* Reference: consider chart at in https://prestwi.ch/bitcoin-time-locks/
|
||||
|
||||
The next step in revisions is:
|
||||
|
||||
1. Run through entire course & make sure all commands & responses are still accurate (likely redoing them all).
|
||||
|
||||
1. Chapter 17+18
|
||||
* Talk about anti-correlation, anti-censorship, and anti-coercion as the three "c"s ("ac"s of privacy)
|
||||
1. Close out with return to chapter 1.0 to update (a) new-for-3.0 links; and (b) what the major parts are [and what's happened to Lightning/coding]
|
||||
1. If lightning is pulled to a parallel course (probably), also move lightning definitions in 1.1
|
||||
|
||||
## Longer-Longer-Term TODO (Big Tasks)
|
||||
|
||||
The following updates involve the large-scale work done on Schnorr and Taproot in Bitcoin Core 0.21 and 22. This represents a first cut at how to layout the work, but revision and expansion will likely be needed as everyone's understanding of these new technologies matures.
|
||||
@ -92,15 +105,6 @@ The following updates could be part of v3.0 or could be further future, dependin
|
||||
* For example in §3.4 could diagram HD keys, derivation of seed phrase to seed to key, etc
|
||||
1. New Graphics: Animated GIFs for key demos.
|
||||
* Reference: https://github.com/faressoft/terminalizer
|
||||
1. New Chapter: Using Other Command-Line Tools (between 8+9)
|
||||
* 9.1: Using seedtool
|
||||
* 9.2: Using keytool
|
||||
* 9.3: Using bytewords-cli
|
||||
* 9.4: Using envelope
|
||||
1. New Chapter: Using Miniscript Command-Line Tools (between 13+14)
|
||||
* 15.1: Using miniscript
|
||||
* 15.2: Using Bitcoin Dev Kit (BDK)
|
||||
* 15.3: Planning for the Future
|
||||
|
||||
As part of this, a new chapter
|
||||
* Put seed words into keytool to create xprv for Bitcoin Core
|
||||
@ -135,18 +139,7 @@ The software work _may_ be deprecated or moved to a separate docment. That decis
|
||||
|
||||
--
|
||||
|
||||
## Listing of Updates
|
||||
|
||||
## Legacy Updates
|
||||
|
||||
* [ ] **Segwit**
|
||||
* Segwit is now old enough that we should teach it as the default. That means that sections 3.1-4.5 should be rewritten to use Segwit as the default and 4.6 should be removed (with perhaps a bit of the information about the different types of addresses being preserved).
|
||||
* It's _possible_ that the same should occur with 10.5, but it should first be reviewed to see if it's a meaningful building block in the scripting process (or not).
|
||||
* [ ] **Signet**
|
||||
* [ ] **Descriptor Wallets**
|
||||
* [ ] **Fees**
|
||||
* There was some question of if `mintxfee` is still current, or if `paytxfee` should be used. I haven't seen any evidence of obsolence, but it'd be good to check this and make sure we're still on the best practices.
|
||||
* This is discussed in [4.1](https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line/blob/master/04_1_Sending_Coins_The_Easy_Way.md)
|
||||
# Listing of Bitcoin Updates
|
||||
|
||||
## 30.0 Updates
|
||||
|
||||
@ -234,6 +227,17 @@ See [release notes](https://bitcoincore.org/en/releases/0.21.0/).
|
||||
|
||||
# Progress Log
|
||||
|
||||
## Immediate TODO (for 3/12): Cleanup
|
||||
|
||||
1. <strike>Bring chapter 1 up to date</strike>
|
||||
2. <strike>Clear Recent PRs</strike>
|
||||
3. <strike>Bring chapter 2 up to date</strike>
|
||||
4. <strike>Replace Gordian Server in §2.2 with Fully Noded Server</strike>
|
||||
5. <strike>Double check §3.1 + 3.2</strike>
|
||||
6. <strike>Put in some discussions about how we'll later import seed words in §3.4</strike>
|
||||
7. <strike>Lightly edit §5.0, §5.1, §5.3 for updates.</strike>
|
||||
8. <strike>Updated §5.2 for changes to RBF in recent years.</strike>
|
||||
|
||||
## Immediate TODO (for 2/26): Sending Transactions
|
||||
|
||||
1. <strike>Rewrite transaction fees in §4.1 to talk about vB, et al</strike>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user