diff --git a/_autocrossref.yaml b/_autocrossref.yaml index 24f4182e..e463bedd 100644 --- a/_autocrossref.yaml +++ b/_autocrossref.yaml @@ -157,6 +157,8 @@ recurrent rebilling: redeemScript: refund: refunds: refund +regression test mode: +regtest: regression test mode root certificate: root seed: RPCs: rpc diff --git a/_includes/example_intro.md b/_includes/example_intro.md new file mode 100644 index 00000000..7a7c5fc8 --- /dev/null +++ b/_includes/example_intro.md @@ -0,0 +1,45 @@ +{% autocrossref %} + +The following guide aims to provide examples to help you start +building Bitcoin-based applications. To make the best use of this document, +you may want to install the current version of Bitcoin Core, either from +[source][core git] or from a [pre-compiled executable][core executable]. + +Once installed, you'll have access to three programs: `bitcoind`, +`bitcoin-qt`, and `bitcoin-cli`. + +* `bitcoin-qt` provides a combination full Bitcoin peer and wallet + frontend. From the Help menu, you can access a console where you can + enter the RPC commands used throughout this document. + +* `bitcoind` is more useful for programming: it provides a full peer + which you can interact with through RPCs to port 8332 (or 18332 + for testnet). + +* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the + command line. For example, `bitcoin-cli help` + +All three programs get settings from `bitcoin.conf` in the `Bitcoin` +application directory: + +* Windows: `%APPDATA%\Bitcoin\` + +* OSX: `$HOME/Library/Application Support/Bitcoin/` + +* Linux: `$HOME/.bitcoin/` + +For development, it's safer and cheaper to use Bitcoin's test network (testnet) +or regression test mode (regtest) described below. + +Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum +tech support] and [IRC channels][]. Errors or suggestions related to +documentation on Bitcoin.org can be [submitted as an issue][docs issue] +or posted to the [bitcoin-documentation mailing list][]. + +In the following documentation, some strings have been shortened or wrapped: "[...]" +indicates extra data was removed, and lines ending in a single backslash "\\" +are continued below. If you hover your mouse over a paragraph, cross-reference +links will be shown in blue. If you hover over a cross-reference link, a brief +definition of the term will be displayed in a tooltip. + +{% endautocrossref %} diff --git a/_includes/example_payment_processing.md b/_includes/example_payment_processing.md index 5272b4fe..e19df3e5 100644 --- a/_includes/example_payment_processing.md +++ b/_includes/example_payment_processing.md @@ -7,6 +7,8 @@ To request payment using the payment protocol, you use an extended (but backwards-compatible) `bitcoin:` URI. For example: +{% endautocrossref %} + ~~~ bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\ ?amount=0.10\ @@ -15,6 +17,8 @@ bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\ &r=https://example.com/pay.php/invoice%3Dda39a3ee ~~~ +{% autocrossref %} + The browser, QR code reader, or other program processing the URI opens the spender's Bitcoin wallet program on the URI. If the wallet program is aware of the payment protocol, it accesses the URL specified in the `r` diff --git a/_includes/example_testing.md b/_includes/example_testing.md new file mode 100644 index 00000000..a7c861ab --- /dev/null +++ b/_includes/example_testing.md @@ -0,0 +1,91 @@ +## Testing Applications + +{% autocrossref %} + +Bitcoin Core provides testing tools designed to let developers +test their applications with reduced risks and limitations. + +{% endautocrossref %} + +### Testnet + +{% autocrossref %} + +When run with no arguments, all Bitcoin Core programs default to Bitcoin's main +network ([mainnet][mainnet]{:#term-mainnet}{:.term}). However, for development, +it's safer and cheaper to use Bitcoin's test network (testnet) +where the satoshis spent have no real-world value. Testnet also relaxes some +restrictions (such as standard transaction checks) so you can test functions +which might currently be disabled by default on mainnet. + +To use testnet, use the argument `-testnet` with `bitcoin-cli`, `bitcoind` or `bitcoin-qt` or add +`testnet=1` to your `bitcoin.conf` file. To get +free satoshis for testing, use [Piotr Piasecki's testnet faucet][]. +Testnet is a public resource provided for free by members of the +community, so please don't abuse it. + +{% endautocrossref %} + +### Regtest Mode + +{% autocrossref %} + +For situations +where interaction with random peers and blocks is unnecessary or +unwanted, Bitcoin Core's regression test mode (regtest mode) lets you +instantly create a brand-new private block chain with the same basic +rules as testnet---but one major difference: you choose when to create +new blocks, so you have complete control over the environment. + +Many developers consider regtest mode the preferred way to develop new +applications. The following example will let you create a regtest +environment. + +{% endautocrossref %} + +{% highlight bash %} +> bitcoind -regtest -daemon +Bitcoin server starting +{% endhighlight %} + +{% autocrossref %} + +Start `bitcoind` in regtest mode to create a private block chain. + +{% endautocrossref %} + +~~~ +bitcoin-cli -regtest setgenerate true 101 +~~~ + +{% autocrossref %} + +Generate 101 blocks using a special version of the `setgenerate` RPC +which is only available in regtest mode. This takes about 30 seconds on +a generic PC. Because this is a new block chain using Bitcoin's default +rules, the first 210,000 blocks pay a block reward of 50 bitcoins. +However, a block must have 100 confirmations before that reward can be +spent, so we generate 101 blocks to get access to the coinbase +transaction from block #1. + +{% endautocrossref %} + +{% highlight bash %} +bitcoin-cli -regtest getbalance +50.00000000 +{% endhighlight %} + +{% autocrossref %} + +Verify that we now have 50 bitcoins available to spend. + +You can now use Bitcoin Core RPCs prefixed with `bitcoin-cli -regtest`. + +Regtest wallets and block chain state (chainstate) are saved in the `regtest` +subdirectory of the Bitcoin Core configuration directory. You can safely +delete the `regtest` subdirectory and restart Bitcoin Core to +start a new regtest. (See the [Developer Examples Introduction][devexamples] for default +configuration directory locations on various operating systems. Always back up +mainnet wallets before performing dangerous operations such as deleting.) + +{% endautocrossref %} diff --git a/_includes/example_transactions.md b/_includes/example_transactions.md index 55715a28..3bb2971d 100644 --- a/_includes/example_transactions.md +++ b/_includes/example_transactions.md @@ -13,67 +13,8 @@ transactions, but in any system, you will need to provide the same kinds of data to create transactions with the same attributes as those described below. -You are encouraged to try the following examples on your own using the -regtest mode described below. - -Note: as in other parts of the documentation, we wrap long strings with -"\\" and indicate omissions with "[...]". - -{% endautocrossref %} - -#### Regtest Mode - -{% autocrossref %} - -Bitcoin's testnet provides an excellent way to test Bitcoin -functionality without risking real satoshis. However, for situations -where interaction with random peers and blocks is unnecessary or -unwanted, Bitcoin Core's regression test (regtest) mode lets you -instantly create a brand-new private block chain with the same basic -rules as testnet---but one major difference: you choose when to create -new blocks, so you have complete control over the environment. - -Many developers consider regtest mode the preferred way to develop new -applications, and this tutorial will use it exclusively. - -{% highlight bash %} -> bitcoind -regtest -daemon -Bitcoin server starting -{% endhighlight %} - -Start `bitcoind` in regtest mode to create a private block chain. - -{% highlight bash %} -> bitcoin-cli -regtest getbalance -0.00000000 -{% endhighlight %} - -Check our starting balance with the `getbalance` RPC. Regtest wallets -and block chain state (chainstate) are saved in the `regtest` -subdirectory of the Bitcoin Core configuration directory. You can safely -delete the `regtest` subdirectory and restart Bitcoin Core to start a -new regtest. (See the [Guide Introduction][devguide] for default configuration -directory locations on various operating systems. Always back up mainnet -wallets before performing dangerous operations such as deleting.) - -~~~ -bitcoin-cli -regtest setgenerate true 101 -~~~ - -Generate 101 blocks using a special version of the `setgenerate` RPC -which is only available in regtest mode. This takes about 30 seconds on -a generic PC. Because this is a new block chain using Bitcoin's default -rules, the first 210,000 blocks pay a block reward of 50 bitcoins. -However, a block must have 100 confirmations before that reward can be -spent, so we generate 101 blocks to get access to the coinbase -transaction from block #1. - -{% highlight bash %} -bitcoin-cli -regtest getbalance -50.00000000 -{% endhighlight %} - -Verify that we now have 50 bitcoins available to spend. +In order to use this tutorial, you will need to setup [Bitcoin Core][core executable] +and create a [regression test mode][] environment. {% endautocrossref %} @@ -163,11 +104,11 @@ the spend to the address we provided. If we had spent those satoshis to someone else, that second transaction would not be displayed in our list of UTXOs. -~~~ +{% highlight bash %} > bitcoin-cli -regtest setgenerate true 1 > unset NEW_ADDRESS -~~~ +{% endhighlight %} Create a new block to confirm the transaction above (takes less than a second) and clear the shell variable. @@ -379,11 +320,11 @@ Send the signed transaction to the connected node using the would usually then broadcast it to other peers, but we're not currently connected to other peers because we started in regtest mode. -~~~ +{% highlight bash %} > bitcoin-cli -regtest setgenerate true 1 > unset UTXO_TXID UTXO_VOUT NEW_ADDRESS RAW_TX SIGNED_RAW_TX -~~~ +{% endhighlight %} Generate a block to confirm the transaction and clear our shell variables. diff --git a/_includes/guide_intro.md b/_includes/guide_intro.md index 51b9e8ae..9a40feee 100644 --- a/_includes/guide_intro.md +++ b/_includes/guide_intro.md @@ -1,62 +1,19 @@ {% autocrossref %} -The Developer Guide aims to provide the information you need to start -building Bitcoin-based applications. To make the best use of this guide, -you may want to install the current version of Bitcoin Core, either from -[source][core git] or from a [pre-compiled executable][core executable]. - -Once installed, you'll have access to three programs: `bitcoind`, -`bitcoin-qt`, and `bitcoin-cli`. When run with no arguments, all three -programs default to Bitcoin's main network ([mainnet][mainnet]{:#term-mainnet}{:.term}) which will require -you purchase satoshis in order to generate transactions. - -However, for development, it's safer and cheaper to use Bitcoin's test -network ([testnet][testnet]{:#term-testnet}{:.term}) where the satoshis spent have no real-world value. -Testnet also relaxes some restrictions (such as standard transaction -checks) so you can test functions which might currently be disabled by -default on mainnet. - -To use testnet, use the argument `-testnet` with each program or add -`testnet=1` to your `bitcoin.conf` file. To get -free satoshis for testing, use [Piotr Piasecki's testnet faucet][]. -Testnet is a public resource provided for free by members of the -community, so please don't abuse it. - -You can speed up development further using the [regression test mode][] -which creates a new testnet local to your computer. This regtest mode -will let you generate blocks almost instantly with a RPC command so you -can generate your own satoshis and add transactions to the block chain -immediately. - -* `bitcoin-qt` provides a combination full Bitcoin peer and wallet - frontend. From the Help menu, you can access a console where you can - enter the RPC commands used throughout this document. - -* `bitcoind` is more useful for programming: it provides a full peer - which you can interact with through RPCs to port 8332 (or 18332 - for testnet). - -* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the - command line. For example, `bitcoin-cli help` - -All three programs get settings from `bitcoin.conf` in the `Bitcoin` -application directiory: - -* Windows: `%APPDATA%\Bitcoin\` - -* OSX: `$HOME/Library/Application Support/Bitcoin/` - -* Linux: `$HOME/.bitcoin/` +The Developer Guide aims to provide the explanations you need to understand +Bitcoin and start building Bitcoin-based applications. To make the best use of +this documentation, you may want to install the current version of Bitcoin +Core, either from [source][core git] or from a [pre-compiled executable][core executable]. Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum tech support] and [IRC channels][]. Errors or suggestions related to documentation on Bitcoin.org can be [submitted as an issue][docs issue] or posted to the [bitcoin-documentation mailing list][]. -In the following guide, -some strings have been shortened or wrapped: "[...]" indicates extra data was removed, and lines ending in a single backslash "\\" are continued below. -If you hover your mouse over a paragraph, cross-reference links will be -shown in blue. If you hover over a cross-reference link, a brief +In the following documentation, some strings have been shortened or wrapped: "[...]" +indicates extra data was removed, and lines ending in a single backslash "\\" +are continued below. If you hover your mouse over a paragraph, cross-reference +links will be shown in blue. If you hover over a cross-reference link, a brief definition of the term will be displayed in a tooltip. {% endautocrossref %} diff --git a/_includes/ref_intro.md b/_includes/ref_intro.md new file mode 100644 index 00000000..f427d421 --- /dev/null +++ b/_includes/ref_intro.md @@ -0,0 +1,19 @@ +{% autocrossref %} + +The Developer Reference aims to provide specifications and APIs information +to help you start building Bitcoin-based applications. To make the best use of +this documentation, you may want to install the current version of Bitcoin +Core, either from [source][core git] or from a [pre-compiled executable][core executable]. + +Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum +tech support] and [IRC channels][]. Errors or suggestions related to +documentation on Bitcoin.org can be [submitted as an issue][docs issue] +or posted to the [bitcoin-documentation mailing list][]. + +In the following documentation, some strings have been shortened or wrapped: "[...]" +indicates extra data was removed, and lines ending in a single backslash "\\" +are continued below. If you hover your mouse over a paragraph, cross-reference +links will be shown in blue. If you hover over a cross-reference link, a brief +definition of the term will be displayed in a tooltip. + +{% endautocrossref %} diff --git a/_includes/ref_transactions.md b/_includes/ref_transactions.md index a039f2ef..2b85d31e 100644 --- a/_includes/ref_transactions.md +++ b/_includes/ref_transactions.md @@ -101,8 +101,6 @@ Nolan provided the following example encoding algorithm to the Bitcoin Wiki [Base58Check encoding](https://en.bitcoin.it/wiki/Base58Check_encoding) page: -{% endautocrossref %} - {% highlight c %} code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz" x = convert_bytes_to_big_integer(hash_result) @@ -123,8 +121,6 @@ repeat(number_of_leading_zero_bytes_in_hash) output_string.reverse(); {% endhighlight %} -{% autocrossref %} - Bitcoin's own code can be traced using the [base58 header file][core base58.h]. diff --git a/_includes/references.md b/_includes/references.md index d1a9bcef..e0c82722 100644 --- a/_includes/references.md +++ b/_includes/references.md @@ -52,7 +52,7 @@ [leaf certificate]: /en/developer-examples#term-leaf-certificate "The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis" [locktime]: /en/developer-guide#term-locktime "Part of a transaction which indicates the earliest time or earliest block when that transaction can be added to the block chain" [long-term fork]: /en/developer-guide#term-long-term-fork "When a series of blocks have corresponding block heights, indicating a possibly serious problem" -[mainnet]: /en/developer-guide#term-mainnet "The Bitcoin main network used to transfer satoshis (compare to testnet, the test network)" +[mainnet]: /en/developer-examples#term-mainnet "The Bitcoin main network used to transfer satoshis (compare to testnet, the test network)" [master chain code]: /en/developer-guide#term-master-chain-code "The chain code derived from the root seed" [master private key]: /en/developer-guide#term-master-private-key "A private key derived from the root seed" [merge]: /en/developer-guide#term-merge "Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control" @@ -116,6 +116,7 @@ [recurrent rebilling]: /en/developer-guide#rebilling-recurring-payments "Billing a spender on a regular schedule" [redeemScript]: /en/developer-guide#term-redeemscript "A script created by the recipient, hashed, and given to the spender for use in a P2SH output" [refund]: /en/developer-guide#issuing-refunds "A transaction which refunds some or all satoshis received in a previous transaction" +[regression test mode]: /en/developer-examples#regtest-mode "A local testing environment in which developers can control blocks" [root certificate]: /en/developer-examples#term-root-certificate "A certificate belonging to a certificate authority (CA)" [root seed]: /en/developer-guide#term-root-seed "A potentially-short value used as a seed to generate a master private key and master chain code for an HD wallet" [satoshi]: /en/developer-guide#term-satoshi "The smallest unit of Bitcoin value; 0.00000001 bitcoins. Also used generically for any value of bitcoins" @@ -139,7 +140,7 @@ [stack]: /en/developer-guide#term-stack "An evaluation stack used in Bitcoin's script language" [standard script]: /en/developer-guide#standard-transactions "An output script which matches the isStandard() patterns specified in Bitcoin Core---or a transaction containing only standard outputs. Only standard transactions are mined or broadcast by peers running the default Bitcoin Core software" [target]: /en/developer-guide#term-target "The threshold below which a block header hash must be in order for the block to be added to the block chain" -[testnet]: /en/developer-guide#term-testnet "A Bitcoin-like network where the satoshis have no real-world value to allow risk-free testing" +[testnet]: /en/developer-examples#testnet "A Bitcoin-like network where the satoshis have no real-world value to allow risk-free testing" [transaction fee]: /en/developer-guide#term-transaction-fee "The amount remaining when all outputs are subtracted from all inputs in a transaction; the fee is paid to the miner who includes that transaction in a block" [transaction fees]: /en/developer-guide#term-transaction-fee "The amount remaining when all outputs are subtracted from all inputs in a transaction; the fee is paid to the miner who includes that transaction in a block" [transaction malleability]: /en/developer-guide#transaction-malleability "The ability of an attacker to change the transaction identifier (txid) of unconfirmed transactions, making dependent transactions invalid" @@ -179,6 +180,7 @@ [DER]: https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One [devex complex raw transaction]: /en/developer-examples#complex-raw-transaction [devex payment protocol]: /en/developer-examples#payment-protocol +[devexamples]: /en/developer-examples [devguide]: /en/developer-guide [devguide avoiding key reuse]: /en/developer-guide#avoiding-key-reuse [devguide hardened keys]: /en/developer-guide#hardened-keys @@ -200,7 +202,6 @@ [prime symbol]: https://en.wikipedia.org/wiki/Prime_%28symbol%29 [protobuf]: https://developers.google.com/protocol-buffers/ [raw transaction format]: /en/developer-reference#raw-transaction-format -[regression test mode]: https://bitcoinj.github.io/testing [rpc addmultisigaddress]: /en/developer-reference#addmultisigaddress [rpc addnode]: /en/developer-reference#addnode [rpc backupwallet]: /en/developer-reference#backupwallet diff --git a/_plugins/autocrossref.rb b/_plugins/autocrossref.rb index 4e4a653c..85edd39c 100644 --- a/_plugins/autocrossref.rb +++ b/_plugins/autocrossref.rb @@ -63,8 +63,8 @@ require 'yaml' (?![^\[]*\]) ## No subst if key inside [brackets] (?![^\{]*\}) ## No subst if key inside {braces} (?![^\s]*) ## No subst if after key - (?![\S ]*<\/span>) ## No subst on a line with a close span. This - ## prevents matching in highlight blocks + (?!((?!
).)*(<\/pre>))  ## No subst on a line with a closing pre tag. This 
+                                        ## prevents matching in {% highlight %} code blocks.
             (?![^\(]*(\.svg|\.png))  ## No subst if key inside an image name. This 
 		     ## simple regex has the side effect that we can't
 		     ## use .svg or .png in non-image base text; if that
diff --git a/en/developer-examples.md b/en/developer-examples.md
index a3189948..ae17bd1d 100644
--- a/en/developer-examples.md
+++ b/en/developer-examples.md
@@ -22,6 +22,10 @@ title: "Developer Examples - Bitcoin"
 
 {% include fragment_reviews_needed.md %}
 
+{% include example_intro.md %}
+
+{% include example_testing.md %}
+
 {% include example_transactions.md %}
 
 {% include example_payment_processing.md %}
diff --git a/en/developer-reference.md b/en/developer-reference.md
index 43bd20a7..9ef2905e 100644
--- a/en/developer-reference.md
+++ b/en/developer-reference.md
@@ -22,6 +22,8 @@ title: "Developer Reference - Bitcoin"
 
 {% include fragment_reviews_needed.md %}
 
+{% include ref_intro.md %}
+
 {% include ref_block_chain.md %}
 
 {% include ref_transactions.md %}