Create a "Testing Applications" subsection in devel-examples

Move existing "regtest / testnet" texts to the new subsection and link to it
Move Bitcoin Core setup instructions in devel-examples
Add a consistent introduction for devel-(guide/ref/examples)
Fix autocrossref.rb to not add links inside {% highlight %} code blocks
This commit is contained in:
Saivann 2014-06-12 18:38:09 -04:00
parent 8a5db84a80
commit ffed3c2529
12 changed files with 187 additions and 125 deletions

View file

@ -157,6 +157,8 @@ recurrent rebilling:
redeemScript:
refund:
refunds: refund
regression test mode:
regtest: regression test mode
root certificate:
root seed:
RPCs: rpc

View file

@ -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 %}

View file

@ -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`

View file

@ -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 %}

View file

@ -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.

View file

@ -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`<!--noref--> with each program or add
`testnet=1`<!--noref--> 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 %}

19
_includes/ref_intro.md Normal file
View file

@ -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 %}

View file

@ -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].

View file

@ -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

View file

@ -63,8 +63,8 @@ require 'yaml'
(?![^\[]*\]) ## No subst if key inside [brackets]
(?![^\{]*\}) ## No subst if key inside {braces}
(?![^\s]*<!--noref-->) ## No subst if <!--noref--> after key
(?![\S ]*<\/span>) ## No subst on a line with a close span. This
## prevents matching in highlight blocks
(?!((?!<pre>).)*(<\/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

View file

@ -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 %}

View file

@ -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 %}