From 4329375f7fea3216bb45b008522a161137244101 Mon Sep 17 00:00:00 2001 From: Igor Kuzmenko Date: Tue, 15 Aug 2017 22:22:30 +0200 Subject: [PATCH] Cleans up simple _devdocs Markdown files --- _devdocs/examples/intro.md | 3 - _devdocs/examples/p2p_networking.md | 20 --- _devdocs/examples/payment_processing.md | 39 ------ _devdocs/examples/testing.md | 26 ---- _devdocs/examples/transactions.md | 56 --------- _devdocs/guides/block_chain.md | 38 ------ _devdocs/guides/contracts.md | 27 ---- _devdocs/guides/intro.md | 3 - _devdocs/guides/mining.md | 34 ----- _devdocs/guides/operating_modes.md | 34 ----- _devdocs/guides/p2p_network.md | 67 ---------- _devdocs/guides/payment_processing.md | 77 ------------ _devdocs/guides/transactions.md | 87 ------------- _devdocs/guides/wallets.md | 109 ---------------- _devdocs/references/block_chain.md | 27 ---- _devdocs/references/intro.md | 8 -- _devdocs/references/p2p_networking.md | 157 ------------------------ _devdocs/references/transactions.md | 40 ------ _devdocs/references/wallets.md | 8 -- 19 files changed, 860 deletions(-) diff --git a/_devdocs/examples/intro.md b/_devdocs/examples/intro.md index 0cf30acb67..d2ecafcaae 100644 --- a/_devdocs/examples/intro.md +++ b/_devdocs/examples/intro.md @@ -4,8 +4,6 @@ http://opensource.org/licenses/MIT. {% endcomment %} {% assign filename="_includes/devdoc/example_intro.md" %} -{% 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 @@ -66,4 +64,3 @@ 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/_devdocs/examples/p2p_networking.md b/_devdocs/examples/p2p_networking.md index f2acede973..176dabaf55 100644 --- a/_devdocs/examples/p2p_networking.md +++ b/_devdocs/examples/p2p_networking.md @@ -5,12 +5,8 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/example_p2p_networking.md" %} ## P2P Network -{% include helpers/subhead-links.md %} ### Creating A Bloom Filter -{% include helpers/subhead-links.md %} - -{% autocrossref %} In this section, we'll use variable names that correspond to the field names in the [`filterload` message documentation][filterload message]. @@ -160,12 +156,7 @@ b50f ....... Filter: 1010 1101 1111 0000 00 ......... nFlags: BLOOM_UPDATE_NONE {% endhighlight %} -{% endautocrossref %} - ### Evaluating A Bloom Filter -{% include helpers/subhead-links.md %} - -{% autocrossref %} Using a bloom filter to find matching data is nearly identical to constructing a bloom filter---except that at each step we check to see @@ -235,12 +226,7 @@ match failure: MATCH FAILURE: Index 0x6 not set in 1010110111110000 {% endhighlight %} -{% endautocrossref %} - ### Retrieving A MerkleBlock -{% include helpers/subhead-links.md %} - -{% autocrossref %} For the `merkleblock` message documentation on the reference page, an actual merkle block was retrieved from the network and manually @@ -351,12 +337,7 @@ python get-merkle.py | nc localhost 8333 | hd Part of the response is shown in the section below. -{% endautocrossref %} - ### Parsing A MerkleBlock -{% include helpers/subhead-links.md %} - -{% autocrossref %} In the section above, we retrieved a merkle block from the network; now we will parse it. Most of the block header has been omitted. For @@ -453,4 +434,3 @@ The final steps would be to ensure the computed computed merkle root is identical to the merkle root in the header and check the other steps of the parsing checklist in the `merkleblock` message section. -{% endautocrossref %} diff --git a/_devdocs/examples/payment_processing.md b/_devdocs/examples/payment_processing.md index 45b7f1a759..8918d8f6df 100644 --- a/_devdocs/examples/payment_processing.md +++ b/_devdocs/examples/payment_processing.md @@ -5,18 +5,12 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/example_payment_processing.md" %} ## Payment Processing -{% include helpers/subhead-links.md %} ### Payment Protocol -{% include helpers/subhead-links.md %} - -{% autocrossref %} To request payment using the payment protocol, you use an extended (but backwards-compatible) `bitcoin:` URI. For example: -{% endautocrossref %} - ~~~ bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\ ?amount=0.10\ @@ -25,8 +19,6 @@ 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` @@ -36,12 +28,7 @@ served with the [MIME][] type `application/bitcoin-paymentrequest`. **Resource:** Gavin Andresen's [Payment Request Generator][] generates custom example URIs and payment requests for use with testnet. -{% endautocrossref %} - #### PaymentRequest & PaymentDetails -{% include helpers/subhead-links.md %} - -{% autocrossref %} The [PaymentRequest][]{:#term-paymentrequest}{:.term} is created with data structures built using Google's Protocol Buffers. BIP70 describes these data @@ -63,12 +50,7 @@ protocol buffer compilers are available for a variety of programming languages. You will also need a copy of the PaymentRequest [Protocol Buffer description][core paymentrequest.proto] from the Bitcoin Core source code. -{% endautocrossref %} - ##### Initialization Code -{% include helpers/subhead-links.md %} - -{% autocrossref %} With the Python code generated by `protoc`, we can start our simple CGI program. @@ -95,12 +77,7 @@ The startup code above is quite simple, requiring nothing but the epoch functions from the OpenSSL library, and the data structures and functions created by `protoc`. -{% endautocrossref %} - ##### Configuration Code -{% include helpers/subhead-links.md %} - -{% autocrossref %} Next, we'll set configuration settings which will typically only change when the receiver wants to do something differently. The code pushes a @@ -246,12 +223,7 @@ The private SSL key will not be transmitted with your request. We're only loading it into memory here so we can use it to sign the request later. -{% endautocrossref %} - ##### Code Variables -{% include helpers/subhead-links.md %} - -{% autocrossref %} Now let's look at the variables your CGI program will likely set for each payment. @@ -350,12 +322,7 @@ given over to storing the certificate chain. As will be described in a later subsection, the `memo` field can be used by the spender after payment as part of a cryptographically-proven receipt. -{% endautocrossref %} - ##### Derivable Data -{% include helpers/subhead-links.md %} - -{% autocrossref %} Next, let's look at some information your CGI program can automatically derive. @@ -437,12 +404,7 @@ signing the completed and serialized PaymentRequest. We'll use the private key we stored in memory in the configuration section and the same hashing formula we specified in `pki_type` (sha256 in this case) -{% endautocrossref %} - ##### Output Code -{% include helpers/subhead-links.md %} - -{% autocrossref %} Now that we have PaymentRequest all filled out, we can serialize it and send it along with the HTTP headers, as shown in the code below. @@ -470,4 +432,3 @@ created by the program above appears in the GUI from Bitcoin Core 0.9. ![Bitcoin Core Showing Validated Payment Request](/img/dev/en-btcc-payment-request.png) -{% endautocrossref %} diff --git a/_devdocs/examples/testing.md b/_devdocs/examples/testing.md index 9f52a8aa92..0cd58cf99f 100644 --- a/_devdocs/examples/testing.md +++ b/_devdocs/examples/testing.md @@ -5,19 +5,11 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/example_testing.md" %} ## Testing Applications -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin Core provides testing tools designed to let developers test their applications with reduced risks and limitations. -{% endautocrossref %} - ### Testnet -{% include helpers/subhead-links.md %} - -{% autocrossref %} When run with no arguments, all Bitcoin Core programs default to Bitcoin's main network ([mainnet][/en/glossary/mainnet]{:#term-mainnet}{:.term}). However, for development, @@ -32,12 +24,7 @@ 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 -{% include helpers/subhead-links.md %} - -{% autocrossref %} For situations where interaction with random peers and blocks is unnecessary or @@ -50,19 +37,13 @@ Many developers consider regtest mode the preferred way to develop new applications. The following example will let you create a regtest environment after you first [configure bitcoind][bitcoind initial setup]. -{% endautocrossref %} - {% highlight bash %} > bitcoind -regtest -daemon Bitcoin server starting {% endhighlight %} -{% autocrossref %} - Start `bitcoind` in regtest mode to create a private block chain. -{% endautocrossref %} - ~~~ ## Bitcoin Core 0.10.1 and earlier bitcoin-cli -regtest setgenerate true 101 @@ -71,8 +52,6 @@ bitcoin-cli -regtest setgenerate true 101 bitcoin-cli -regtest generate 101 ~~~ -{% autocrossref %} - Generate 101 blocks using a special RPC which is only available in regtest mode. This takes less than a second on a generic PC. Because this is a new block chain using Bitcoin's default @@ -82,15 +61,11 @@ 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`. @@ -102,4 +77,3 @@ start a new regtest. (See the [Developer Examples Introduction][devexamples] for configuration directory locations on various operating systems. Always back up mainnet wallets before performing dangerous operations such as deleting.) -{% endautocrossref %} diff --git a/_devdocs/examples/transactions.md b/_devdocs/examples/transactions.md index d01c9fea63..ee320c8b2a 100644 --- a/_devdocs/examples/transactions.md +++ b/_devdocs/examples/transactions.md @@ -5,12 +5,8 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/example_transactions.md" %} ## Transactions -{% include helpers/subhead-links.md %} ### Transaction Tutorial -{% include helpers/subhead-links.md %} - -{% autocrossref %} Creating transactions is something most Bitcoin applications do. This section describes how to use Bitcoin Core's RPC interface to @@ -25,17 +21,7 @@ In order to use this tutorial, you will need to setup [Bitcoin Core][core execut and create a regression test mode environment with 50 BTC in your test wallet. -{% endautocrossref %} - - - - - - #### Simple Spending -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin Core provides several RPCs which handle all the details of spending, including creating change outputs and paying appropriate fees. @@ -127,17 +113,7 @@ list of UTXOs. Create a new block to confirm the transaction above (takes less than a second) and clear the shell variable. -{% endautocrossref %} - - - - - - #### Simple Raw Transaction -{% include helpers/subhead-links.md %} - -{% autocrossref %} The raw transaction RPCs allow users to create custom transactions and delay broadcasting those transactions. However, mistakes made in raw @@ -252,7 +228,6 @@ would be a whopping 40 bitcoins. See the Complex Raw Transaction subsection below for how to create a transaction with multiple outputs so you can send the change back to yourself. -
{% highlight bash %} > bitcoin-cli -regtest decoderawtransaction $RAW_TX @@ -353,16 +328,7 @@ connected to other peers because we started in regtest mode. Generate a block to confirm the transaction and clear our shell variables. -{% endautocrossref %} - - - - - #### Complex Raw Transaction -{% include helpers/subhead-links.md %} - -{% autocrossref %} In this example, we'll create a transaction with two inputs and two outputs. We'll sign each of the inputs separately, as might happen if @@ -511,7 +477,6 @@ e8677d2cc74df51f738285013c260000000000ffffffff02f028d6dc01000000\ Create the raw transaction using `createrawtransaction` much the same as before, except now we have two inputs and two outputs. -
{% highlight bash %} > bitcoin-cli -regtest signrawtransaction $RAW_TX '[]' ''' @@ -607,16 +572,7 @@ not going to send this transaction to the connected node with Signing subsection below how to spend a transaction which is not yet in the block chain or memory pool. -{% endautocrossref %} - - - - - #### Offline Signing -{% include helpers/subhead-links.md %} - -{% autocrossref %} We will now spend the transaction created in the Complex Raw Transaction subsection above without sending it to the local node first. This is the @@ -745,7 +701,6 @@ variable. {% endhighlight %}
- Decode the signed raw transaction so we can get its txid. Also, choose a specific one of its UTXOs to spend and save that UTXO's output index number (vout) and hex pubkey script (scriptPubKey) into shell variables. @@ -906,17 +861,7 @@ are part of the local node's memory pool. Remove old shell variables. -{% endautocrossref %} - - - - - - #### P2SH Multisig -{% include helpers/subhead-links.md %} - -{% autocrossref %} In this subsection, we will create a P2SH multisig address, spend satoshis to it, and then spend those satoshis from it to another @@ -1276,4 +1221,3 @@ complete. We send the transaction spending the P2SH multisig output to the local node, which accepts it. -{% endautocrossref %} diff --git a/_devdocs/guides/block_chain.md b/_devdocs/guides/block_chain.md index 946592f543..b8967ef610 100644 --- a/_devdocs/guides/block_chain.md +++ b/_devdocs/guides/block_chain.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_block_chain.md" %} ## Block Chain -{% include helpers/subhead-links.md %} - -{% autocrossref %} The block chain provides Bitcoin's public ledger, an ordered and timestamped record of transactions. This system is used to protect against double spending @@ -21,12 +18,7 @@ nodes follow to maintain consensus are called [consensus rules][/en/glossary/consensus-rules]{:#term-consensus-rules}{:.term}. This section describes many of the consensus rules used by Bitcoin Core. -{% endautocrossref %} - ### Block Chain Overview -{% include helpers/subhead-links.md %} - -{% autocrossref %} ![Block Chain Overview](/img/dev/en-blockchain-overview.svg) @@ -76,12 +68,7 @@ For example, in the illustration above, each transaction spends 10,000 satoshis fewer than it receives from its combined inputs, effectively paying a 10,000 satoshi transaction fee. -{% endautocrossref %} - ### Proof Of Work -{% include helpers/subhead-links.md %} - -{% autocrossref %} The block chain is collaboratively maintained by anonymous peers on the network, so Bitcoin requires that each block prove a significant amount of work was invested in @@ -151,12 +138,7 @@ a block does not slow down hashing with extra I/O, and adding additional transaction data only requires the recalculation of the ancestor hashes in the merkle tree. -{% endautocrossref %} - ### Block Height And Forking -{% include helpers/subhead-links.md %} - -{% autocrossref %} Any Bitcoin miner who successfully hashes a block header to a value below the target threshold can add the entire block to the block chain @@ -196,12 +178,7 @@ Since multiple blocks can have the same height during a block chain fork, block height should not be used as a globally unique identifier. Instead, blocks are usually referenced by the hash of their header (often with the byte order reversed, and in hexadecimal). -{% endautocrossref %} - ### Transaction Data -{% include helpers/subhead-links.md %} - -{% autocrossref %} Every block must include one or more transactions. The first one of these transactions must be a coinbase transaction, also called a generation transaction, which should collect and @@ -232,8 +209,6 @@ process repeats until only one hash remains, the merkle root. For example, if transactions were merely joined (not hashed), a five-transaction merkle tree would look like the following text diagram: -{% endautocrossref %} - ~~~ ABCDEEEE .......Merkle root / \ @@ -244,8 +219,6 @@ five-transaction merkle tree would look like the following text diagram: A B C D E .........Transactions ~~~ -{% autocrossref %} - As discussed in the Simplified Payment Verification (SPV) subsection, the merkle tree allows clients to verify for themselves that a transaction was included in a block by obtaining the @@ -266,12 +239,7 @@ Note: If identical txids are found within the same block, there is a possibility Since it is impractical to have separate transactions with identical txids, this does not impose a burden on honest software, but must be checked if the invalid status of a block is to be cached; otherwise, a valid block with the duplicates eliminated could have the same merkle root and block hash, but be rejected by the cached invalid outcome, resulting in security bugs such as CVE-2012-2459. -{% endautocrossref %} - ### Consensus Rule Changes -{% include helpers/subhead-links.md %} - -{% autocrossref %} To maintain consensus, all full nodes validate blocks using the same consensus rules. However, sometimes the consensus rules are changed to @@ -341,12 +309,7 @@ downgrade was removed. A document from Gavin Andresen outlines [how future rule changes may be implemented](https://gist.github.com/gavinandresen/2355445). -{% endautocrossref %} - #### Detecting Forks -{% include helpers/subhead-links.md %} - -{% autocrossref %} Non-upgraded nodes may use and distribute incorrect information during both types of forks, creating several situations which could lead to @@ -387,4 +350,3 @@ SPV clients should also monitor for block and transaction version number increases to ensure they process received transactions and create new transactions using the current consensus rules. -{% endautocrossref %} diff --git a/_devdocs/guides/contracts.md b/_devdocs/guides/contracts.md index 07486f0952..cb71aefe68 100644 --- a/_devdocs/guides/contracts.md +++ b/_devdocs/guides/contracts.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_contracts.md" %} ## Contracts -{% include helpers/subhead-links.md %} - -{% autocrossref %} Contracts are transactions which use the decentralized Bitcoin system to enforce financial @@ -24,12 +21,7 @@ Besides the contract types described below, many other contract types have been proposed. Several of them are collected on the [Contracts page](https://en.bitcoin.it/wiki/Contracts) of the Bitcoin Wiki. -{% endautocrossref %} - ### Escrow And Arbitration -{% include helpers/subhead-links.md %} - -{% autocrossref %} Charlie-the-customer wants to buy a product from Bob-the-businessman, but neither of them trusts the other person, so they use a contract to @@ -52,14 +44,10 @@ To create a multiple-signature ([multisig][/en/glossary/multisig]{:#term-multisi output, they each give the others a public key. Then Bob creates the following [P2SH multisig][/en/glossary/p2sh-multisig]{:#term-p2sh-multisig}{:.term} redeem script: -{% endautocrossref %} - ~~~ OP_2 [A's pubkey] [B's pubkey] [C's pubkey] OP_3 OP_CHECKMULTISIG ~~~ -{% autocrossref %} - (Opcodes to push the public keys onto the stack are not shown.) `OP_2` and `OP_3` push the actual numbers 2 and 3 onto the @@ -92,14 +80,10 @@ that Bob created. She gives a copy of the incomplete transaction to both Bob and Charlie. Either one of them can complete it by adding his signature to create the following signature script: -{% endautocrossref %} - ~~~ OP_0 [A's signature] [B's or C's signature] [serialized redeem script] ~~~ -{% autocrossref %} - (Opcodes to push the signatures and redeem script onto the stack are not shown. `OP_0` is a workaround for an off-by-one error in the original implementation which must be preserved for compatibility. Note that @@ -125,12 +109,7 @@ need to worry about their arbitrator stealing their money. **Resource:** [BitRated](https://www.bitrated.com/) provides a multisig arbitration service interface using HTML/JavaScript on a GNU AGPL-licensed website. -{% endautocrossref %} - ### Micropayment Channel -{% include helpers/subhead-links.md %} - -{% autocrossref %} @@ -203,12 +182,7 @@ implementation, and [a tutorial][bitcoinj micropayment tutorial] all under an Apache license. -{% endautocrossref %} - ### CoinJoin -{% include helpers/subhead-links.md %} - -{% autocrossref %} Alice is concerned about her privacy. She knows every transaction gets added to the public block chain, so when Bob and Charlie pay her, they @@ -286,4 +260,3 @@ saving each one of them a tiny amount of satoshis. CoinJoin is [CoinMux](http://coinmux.com/), available under the Apache license. -{% endautocrossref %} diff --git a/_devdocs/guides/intro.md b/_devdocs/guides/intro.md index cd99ac8daf..a02e73ebdb 100644 --- a/_devdocs/guides/intro.md +++ b/_devdocs/guides/intro.md @@ -3,8 +3,6 @@ This file is licensed under the MIT License (MIT) available on http://opensource.org/licenses/MIT. {% endcomment %} -{% autocrossref %} - The Developer Guide aims to provide the information you need to understand Bitcoin and start building Bitcoin-based applications, but it is [not a specification][]. To make the best use of @@ -23,4 +21,3 @@ 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/_devdocs/guides/mining.md b/_devdocs/guides/mining.md index d4237ba462..d57daa9560 100644 --- a/_devdocs/guides/mining.md +++ b/_devdocs/guides/mining.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_mining.md" %} ## Mining -{% include helpers/subhead-links.md %} - -{% autocrossref %} Mining adds new blocks to the block chain, making transaction history hard to modify. Mining today takes on two forms: @@ -23,12 +20,7 @@ hard to modify. Mining today takes on two forms: they each contributed, allowing the miner to receive small payments with a lower variance (shorter time between payments). -{% endautocrossref %} - ### Solo Mining -{% include helpers/subhead-links.md %} - -{% autocrossref %} As illustrated below, solo miners typically use `bitcoind` to get new transactions from the network. Their mining software periodically polls @@ -55,12 +47,7 @@ the mining software. The mining software combines the header with the block and sends the completed block to `bitcoind` to be broadcast to the network for addition to the block chain. -{% endautocrossref %} - ### Pool Mining -{% include helpers/subhead-links.md %} - -{% autocrossref %} Pool miners follow a similar workflow, illustrated below, which allows mining pool operators to pay miners based on their share of the work @@ -98,12 +85,7 @@ average to create a successful block, so the mining pool can pay 1/100th of its payout for each share received. Different mining pools use different reward distribution systems based on this basic share system. -{% endautocrossref %} - ### Block Prototypes -{% include helpers/subhead-links.md %} - -{% autocrossref %} In both solo and pool mining, the mining software needs to get the information necessary to construct block headers. This subsection @@ -111,12 +93,7 @@ describes, in a linear way, how that information is transmitted and used. However, in actual implementations, parallel threads and queuing are used to keep ASIC hashers working at maximum capacity, -{% endautocrossref %} - #### getwork RPC -{% include helpers/subhead-links.md %} - -{% autocrossref %} The simplest and earliest method was the now-deprecated Bitcoin Core `getwork` RPC, which constructs a header for the miner directly. Since a @@ -125,12 +102,7 @@ many modern miners need to make dozens or hundreds of `getwork` requests a second. Solo miners may still use `getwork` on v0.9.5 or below, but most pools today discourage or disallow its use. -{% endautocrossref %} - #### getblocktemplate RPC -{% include helpers/subhead-links.md %} - -{% autocrossref %} An improved method is the Bitcoin Core `getblocktemplate` RPC. This provides the mining software with much more information: @@ -163,12 +135,7 @@ mining pool to push a new `getblocktemplate` to the miner as soon as any miner on the peer-to-peer network publishes a new block or the pool wants to send more transactions to the mining software. -{% endautocrossref %} - #### Stratum -{% include helpers/subhead-links.md %} - -{% autocrossref %} A widely used alternative to `getblocktemplate` is the [Stratum mining protocol][]. Stratum focuses on giving miners the minimal information they @@ -212,4 +179,3 @@ peer-to-peer network. pools. The [libblkmaker][] C library and [python-blkmaker][] library, both MIT licensed, can interpret GetBlockTemplate for your programs. -{% endautocrossref %} diff --git a/_devdocs/guides/operating_modes.md b/_devdocs/guides/operating_modes.md index 5c4e5f0720..3858c3b607 100644 --- a/_devdocs/guides/operating_modes.md +++ b/_devdocs/guides/operating_modes.md @@ -5,18 +5,10 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_operating_modes.md" %} ## Operating Modes -{% include helpers/subhead-links.md %} - -{% autocrossref %} Currently there are two primary methods of validating the block chain as a client: Full nodes and SPV clients. Other methods, such as server-trusting methods, are not discussed as they are not recommended. -{% endautocrossref %} - ### Full Node -{% include helpers/subhead-links.md %} - -{% autocrossref %} The first and most secure model is the one followed by Bitcoin Core, also known as a “thick” or “full chain” client. This security model assures the validity of the block chain by downloading and validating blocks from the genesis block all the way to the most recently discovered block. This is known as using the *height* of a particular block to verify the client’s view of the network. @@ -24,12 +16,7 @@ For a client to be fooled, an adversary would need to give a complete alternativ ![Block Height Compared To Block Depth](/img/dev/en-block-height-vs-depth.svg) -{% endautocrossref %} - ### Simplified Payment Verification (SPV) -{% include helpers/subhead-links.md %} - -{% autocrossref %} An alternative approach detailed in the [original Bitcoin paper][bitcoinpdf] is a client that only downloads the headers of blocks during the initial syncing process and then requests transactions from full nodes as needed. This scales linearly with the height of the block chain at only 80 bytes per block header, or up to 4.2MB per year, regardless of total block size. @@ -37,12 +24,7 @@ As described in the white paper, the merkle root in the block header along with The block's depth in the block chain corresponds to the cumulative difficulty that has been performed to build on top of that particular block. The SPV client knows the merkle root and associated transaction information, and requests the respective merkle branch from a full node. Once the merkle branch has been retrieved, proving the existence of the transaction in the block, the SPV client can then look to block *depth* as a proxy for transaction validity and security. The cost of an attack on a user by a malicious node who inserts an invalid transaction grows with the cumulative difficulty built on top of that block, since the malicious node alone will be mining this forged chain. -{% endautocrossref %} - #### Potential SPV Weaknesses -{% include helpers/subhead-links.md %} - -{% autocrossref %} If implemented naively, an SPV client has a few important weaknesses. @@ -52,12 +34,7 @@ Second, the SPV client only requests transactions from full nodes corresponding To mitigate the latter issue, Bloom filters have been implemented as a method of obfuscation and compression of block data requests. -{% endautocrossref %} - #### Bloom Filters -{% include helpers/subhead-links.md %} - -{% autocrossref %} A Bloom filter is a space-efficient probabilistic data structure that is used to test membership of an element. The data structure achieves great data compression at the expense of a prescribed false positive rate. @@ -71,12 +48,7 @@ Querying of the Bloom filter is done by using the same hash functions as before. Removal of elements can only be done by scrapping the bloom filter and re-creating it from scratch. -{% endautocrossref %} - #### Application Of Bloom Filters -{% include helpers/subhead-links.md %} - -{% autocrossref %} Rather than viewing the false positive rates as a liability, it is used to create a tunable parameter that represents the desired privacy level and bandwidth trade-off. A SPV client creates their Bloom filter and sends it to a full node using the message `filterload`, which sets the filter for which transactions are desired. The command `filteradd` allows addition of desired data to the filter without needing to send a totally new Bloom filter, and `filterclear` allows the connection to revert to standard block discovery mechanisms. If the filter has been loaded, then full nodes will send a modified form of blocks, called a merkle block. The merkle block is simply the block header with the merkle branch associated with the set Bloom filter. @@ -89,12 +61,7 @@ If a user is more privacy-conscious, he can set the Bloom filter to include more Bloom filters were standardized for use via [BIP37](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki). Review the BIP for implementation details. -{% endautocrossref %} - ### Future Proposals -{% include helpers/subhead-links.md %} - -{% autocrossref %} There are future proposals such as Unspent Transaction Output (UTXO) commitments in the block chain to find a more satisfactory middle-ground for clients between needing a complete copy of the block chain, or trusting that a majority of your connected peers are not lying. UTXO commitments would enable a very secure client using a finite amount of storage using a data structure that is authenticated in the block chain. These type of proposals are, however, in very early stages, and will require soft forks in the network. @@ -102,4 +69,3 @@ Until these types of operating modes are implemented, modes should be chosen bas **Resources:** [Original Thread on UTXO Commitments](https://bitcointalk.org/index.php?topic=88208.0), [Authenticated Prefix Trees BIP Proposal](https://github.com/maaku/bips/blob/master/drafts/auth-trie.mediawiki) -{% endautocrossref %} diff --git a/_devdocs/guides/p2p_network.md b/_devdocs/guides/p2p_network.md index 45f78bb924..1fc9cd2196 100644 --- a/_devdocs/guides/p2p_network.md +++ b/_devdocs/guides/p2p_network.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_p2p_network.md" %} ## P2P Network -{% include helpers/subhead-links.md %} - -{% autocrossref %} The Bitcoin network protocol allows full nodes (peers) to collaboratively maintain a @@ -31,12 +28,7 @@ default behavior is described. Also, for privacy, actual IP addresses in the example output below have been replaced with [RFC5737][] reserved IP addresses. -{% endautocrossref %} - ### Peer Discovery -{% include helpers/subhead-links.md %} - -{% autocrossref %} When started for the first time, programs don't know the IP addresses of any active full nodes. In order to discover some IP @@ -124,12 +116,7 @@ seeds used by Bitcoin Core and BitcoinJ. The Bitcoin Core [DNS Seed Policy][]. The hardcoded list of IP addresses used by Bitcoin Core and BitcoinJ is generated using the [makeseeds script][]. -{% endautocrossref %} - ### Connecting To Peers -{% include helpers/subhead-links.md %} - -{% autocrossref %} Connecting to a peer is done by sending a `version` message, which contains your version number, block, and current time to the remote @@ -141,12 +128,7 @@ Once connected, the client can send to the remote node `getaddr` and `addr` mess In order to maintain a connection with a peer, nodes by default will send a message to peers before 30 minutes of inactivity. If 90 minutes pass without a message being received by a peer, the client will assume that connection has closed. -{% endautocrossref %} - ### Initial Block Download -{% include helpers/subhead-links.md %} - -{% autocrossref %} Before a full node can validate unconfirmed transactions and recently-mined blocks, it must download and validate all blocks from @@ -166,12 +148,7 @@ Bitcoin Core 0.10.0 will also perform IBD if its local best block chain is more than 144 blocks lower than its local best header chain (that is, the local block chain is more than about 24 hours in the past). -{% endautocrossref %} - #### Blocks-First -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin Core (up until version [0.9.3][bitcoin core 0.9.3]) uses a simple initial block download (IBD) method we'll call *blocks-first*. @@ -261,13 +238,8 @@ node is synced to the tip of the block chain. At that point, the node will accept blocks sent through the regular block broadcasting described in a later subsection. -{% endautocrossref %} - ##### Blocks-First Advantages & Disadvantages {:.no_toc} -{% include helpers/subhead-links.md %} - -{% autocrossref %} The primary advantage of blocks-first IBD is its simplicity. The primary disadvantage is that the IBD node relies on a single sync node for all @@ -311,12 +283,7 @@ to the reference page for that message. | **From→To** | IBD→Sync | Sync→IBD | IBD→Sync | Sync→IBD | **Payload** | One or more header hashes | Up to 500 block inventories (unique identifiers) | One or more block inventories | One serialized block -{% endautocrossref %} - #### Headers-First -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin Core 0.10.0 uses an initial block download (IBD) method called *headers-first*. The goal is to download the headers for the best [header @@ -417,12 +384,7 @@ to the reference page for that message. | **From→To** | IBD→Sync | Sync→IBD | IBD→*Many* | *Many*→IBD | **Payload** | One or more header hashes | Up to 2,000 block headers | One or more block inventories derived from header hashes | One serialized block -{% endautocrossref %} - ### Block Broadcasting -{% include helpers/subhead-links.md %} - -{% autocrossref %} When a miner discovers a new block, it broadcasts the new block to its peers using one of the following methods: @@ -477,12 +439,7 @@ block retrieval method.) | **From→To** | Relay→BF/HF | Relay→SPV | Relay→SPV | | **Payload** | The new block in [serialized format][section serialized blocks] | The new block filtered into a merkle block | Serialized transactions from the new block that match the bloom filter | -{% endautocrossref %} - #### Orphan Blocks -{% include helpers/subhead-links.md %} - -{% autocrossref %} Blocks-first nodes may download orphan blocks---blocks whose previous block header hash field refers to a block header this node @@ -516,21 +473,11 @@ message is an orphan block, a headers-first node will discard it immediately. However, orphan discarding does mean that headers-first nodes will ignore orphan blocks sent by miners in an unsolicited block push. -{% endautocrossref %} - ### Transaction Broadcasting -{% include helpers/subhead-links.md %} - -{% autocrossref %} In order to send a transaction to a peer, an `inv` message is sent. If a `getdata` response message is received, the transaction is sent using `tx`. The peer receiving this transaction also forwards the transaction in the same manner, given that it is a valid transaction. -{% endautocrossref %} - #### Memory Pool -{% include helpers/subhead-links.md %} - -{% autocrossref %} Full peers may keep track of unconfirmed transactions which are eligible to be included in the next block. This is essential for miners who will @@ -563,27 +510,13 @@ hasn't yet been included in a block and that it only spends UTXOs, so they can't know which transactions are eligible to be included in the next block. -{% endautocrossref %} - - - - ### Misbehaving Nodes -{% include helpers/subhead-links.md %} - -{% autocrossref %} Take note that for both types of broadcasting, mechanisms are in place to punish misbehaving peers who take up bandwidth and computing resources by sending false information. If a peer gets a banscore above the `-banscore=` threshold, he will be banned for the number of seconds defined by `-bantime=`, which is 86,400 by default (24 hours). -{% endautocrossref %} - ### Alerts -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Removed in Bitcoin Core 0.13.0* Earlier versions of Bitcoin Core allowed developers and trusted community members to issue [Bitcoin alerts](https://bitcoin.org/en/alerts) to notify users of critical network-wide issues. This messaging system [was retired](https://bitcoin.org/en/alert/2016-11-01-alert-retirement) in Bitcoin Core v0.13.0; however, internal alerts, partition detection warnings and the `-alertnotify` option features remain. -{% endautocrossref %} diff --git a/_devdocs/guides/payment_processing.md b/_devdocs/guides/payment_processing.md index 10ec3ca2db..b40dc6b3ac 100644 --- a/_devdocs/guides/payment_processing.md +++ b/_devdocs/guides/payment_processing.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_payment_processing.md" %} ## Payment Processing -{% include helpers/subhead-links.md %} - -{% autocrossref %} Payment processing encompasses the steps spenders and receivers perform to make and accept payments in exchange for products or services. The @@ -27,12 +24,7 @@ occasional or optional steps. It is worth mentioning that each of these steps can be outsourced by using third party APIs and services. -{% endautocrossref %} - ### Pricing Orders -{% include helpers/subhead-links.md %} - -{% autocrossref %} Because of exchange rate variability between satoshis and national currencies ([fiat][]{:#term-fiat}{:.term}), many Bitcoin orders are priced in fiat but paid @@ -76,12 +68,7 @@ to request an additional payment or to issue a refund. Longer expiration periods increase the chance that the exchange rate will fluctuate a significant amount before payment is received. -{% endautocrossref %} - ### Requesting Payments -{% include helpers/subhead-links.md %} - -{% autocrossref %} Before requesting payment, your application must create a Bitcoin address, or acquire an address from another program such as @@ -128,12 +115,7 @@ and payment requests should be sent over HTTPS or other secure methods to prevent man-in-the-middle attacks from replacing your Bitcoin address with the attacker's address. -{% endautocrossref %} - #### Plain Text -{% include helpers/subhead-links.md %} - -{% autocrossref %} To specify an amount directly for copying and pasting, you must provide the address, the amount, and the denomination. An expiration time for @@ -141,16 +123,12 @@ the offer may also be specified. For example: (Note: all examples in this section use testnet addresses.) -{% endautocrossref %} - ~~~ Pay: mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN Amount: 100 BTC You must pay by: 2014-04-01 at 23:00 UTC ~~~ -{% autocrossref %} - Indicating the denomination is critical. As of this writing, popular Bitcoin wallet software defaults to denominating amounts in either bitcoins (BTC) , millibitcoins (mBTC) or microbitcoins (uBTC, "bits"). Choosing between each unit is widely supported, @@ -165,26 +143,17 @@ some or all of the following options: | 0.000001 | microbitcoin (uBTC, "bits") | | 0.00000001 | satoshi | -{% endautocrossref %} - #### bitcoin: URI -{% include helpers/subhead-links.md %} - -{% autocrossref %} The [`bitcoin:` URI][bitcoin URI]{:#term-bitcoin-uri}{:.term} scheme defined in BIP21 eliminates denomination confusion and saves the spender from copying and pasting two separate values. It also lets the payment request provide some additional information to the spender. An example: -{% endautocrossref %} - ~~~ bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=100 ~~~ -{% autocrossref %} - Only the address is required, and if it is the only thing specified, wallets will pre-fill a payment request with it and let the spender enter an amount. The amount specified is always in @@ -218,12 +187,7 @@ Programs accepting URIs in any form must ask the user for permission before paying unless the user has explicitly disabled prompting (as might be the case for micropayments). -{% endautocrossref %} - #### QR Codes -{% include helpers/subhead-links.md %} - -{% autocrossref %} QR codes are a popular way to exchange `bitcoin:` URIs in person, in images, or in videos. Most mobile Bitcoin wallet apps, and some desktop @@ -246,12 +210,7 @@ Low-level damage correction works well when space is limited, and quartile-level damage correction helps ensure fast scanning when displayed on high-resolution screens. -{% endautocrossref %} - #### Payment Protocol -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin Core 0.9 supports the new [payment protocol][/en/glossary/payment-protocol]{:#term-payment-protocol}{:.term}. The payment protocol adds many important features to payment requests: @@ -409,12 +368,7 @@ If a refund needs to be issued, Bob's server can safely pay the refund-to pubkey script provided by Charlie. See the Refunds section below for more details. -{% endautocrossref %} - ### Verifying Payment -{% include helpers/subhead-links.md %} - -{% autocrossref %} As explained in the [Transactions][] and [Block Chain][section block chain] sections, broadcasting a transaction to the network doesn't ensure that the receiver gets @@ -504,12 +458,7 @@ savvy merchants manually flag them as high risk. Your program can provide a safe mode which stops automatic payment acceptance on a global or per-customer basis. -{% endautocrossref %} - ### Issuing Refunds -{% include helpers/subhead-links.md %} - -{% autocrossref %} Occasionally receivers using your applications will need to issue refunds. The obvious way to do that, which is very unsafe, is simply @@ -548,12 +497,7 @@ original payment was made. This allows you to ensure the user still has access to the key or keys for the `refund_to` address. -{% endautocrossref %} - ### Disbursing Income (Limiting Forex Risk) -{% include helpers/subhead-links.md %} - -{% autocrossref %} Many receivers worry that their satoshis will be less valuable in the future than they are now, called foreign exchange (forex) risk. To limit @@ -577,12 +521,7 @@ which can lead to different results. first, which can help ensure that the receiver's payments always confirm, although this has utility only in a few edge cases. -{% endautocrossref %} - #### Merge Avoidance -{% include helpers/subhead-links.md %} - -{% autocrossref %} When a receiver receives satoshis in an output, the spender can track (in a crude way) how the receiver spends those satoshis. But the spender @@ -612,12 +551,7 @@ to the payment protocol which will allow payers to avoid merging by intelligently distributing their payments among multiple outputs provided by the receiver. -{% endautocrossref %} - #### Last In, First Out (LIFO) -{% include helpers/subhead-links.md %} - -{% autocrossref %} Outputs can be spent as soon as they're received---even before they're confirmed. Since recent outputs are at the greatest risk of being @@ -650,12 +584,7 @@ reputation might be at stake, such as when paying employees. In these cases, it's better to wait for transactions to be fully verified (see the [Verification subsection][] above) before using them to make payments. -{% endautocrossref %} - #### First In, First Out (FIFO) -{% include helpers/subhead-links.md %} - -{% autocrossref %} The oldest outputs are the most reliable, as the longer it's been since they were received, the more blocks would need to be modified to double @@ -690,12 +619,7 @@ a receiver who holds each payment for six confirmations, and then spends 100% of verified payments to vendors and a savings account on a bi-hourly schedule. -{% endautocrossref %} - ### Rebilling Recurring Payments -{% include helpers/subhead-links.md %} - -{% autocrossref %} Automated recurring payments are not possible with decentralized Bitcoin wallets. Even if a wallet supported automatically sending non-reversible @@ -720,4 +644,3 @@ regular basis and authorize payment---but it should be easier and more secure for the spender than clicking an emailed invoice, increasing the chance receivers get paid on time. -{% endautocrossref %} diff --git a/_devdocs/guides/transactions.md b/_devdocs/guides/transactions.md index 0ef742f02f..fb73f26441 100644 --- a/_devdocs/guides/transactions.md +++ b/_devdocs/guides/transactions.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_transactions.md" %} ## Transactions -{% include helpers/subhead-links.md %} - -{% autocrossref %} -{% endautocrossref %} - ### Locktime And Sequence Number -{% include helpers/subhead-links.md %} - -{% autocrossref %} One thing all signature hash types sign is the transaction's [locktime][/en/glossary/locktime]{:#term-locktime}{:.term}. (Called nLockTime in the Bitcoin Core source code.) @@ -638,12 +567,7 @@ enable locktime. can be added to any block whose block time is greater than the locktime. -{% endautocrossref %} - ### Transaction Fees And Change -{% include helpers/subhead-links.md %} - -{% autocrossref %} Transactions pay fees based on the total byte size of the signed transaction. Fees per byte are calculated based on current demand for space in mined blocks with fees rising as demand increases. The transaction fee is given to the Bitcoin miner, as explained in the [block chain section][section block chain], and so it is @@ -672,12 +596,7 @@ or P2SH script hash as was used in the UTXO, but for the reasons described in the [next subsection](#avoiding-key-reuse), it is highly recommended that change outputs be sent to a new P2PKH or P2SH address. -{% endautocrossref %} - ### Avoiding Key Reuse -{% include helpers/subhead-links.md %} - -{% autocrossref %} In a transaction, the spender and receiver each reveal to each other all public keys or addresses used in the transaction. This allows either @@ -726,12 +645,7 @@ users from reusing addresses. If your application needs to provide a fixed URI to which payments should be sent, please see the [`bitcoin:` URI section][bitcoin URI subsection] below. -{% endautocrossref %} - ### Transaction Malleability -{% include helpers/subhead-links.md %} - -{% autocrossref %} None of Bitcoin's signature hash types protect the signature script, leaving the door open for a limited denial of service attack called [transaction @@ -781,4 +695,3 @@ in a way that invalidates the lost transaction. One method which will always work is to ensure the reissued payment spends all of the same outputs that the lost transaction used as inputs. -{% endautocrossref %} diff --git a/_devdocs/guides/wallets.md b/_devdocs/guides/wallets.md index f599495467..23f5d015c7 100644 --- a/_devdocs/guides/wallets.md +++ b/_devdocs/guides/wallets.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/guide_wallets.md" %} ## Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} A Bitcoin wallet can refer to either a wallet program or a wallet file. Wallet programs create public keys to receive satoshis and use the @@ -19,12 +16,7 @@ Wallet programs and wallet files are addressed below in separate subsections, and this document attempts to always make it clear whether we're talking about wallet programs or wallet files. -{% endautocrossref %} - ### Wallet Programs -{% include helpers/subhead-links.md %} - -{% autocrossref %} Permitting receiving and spending of satoshis is the only essential feature of wallet software---but a particular wallet program doesn't @@ -47,12 +39,7 @@ cases, P2PKH or P2SH hashes will be distributed instead of public keys, with the actual public keys only being distributed when the outputs they control are spent. -{% endautocrossref %} - #### Full-Service Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} The simplest wallet is a program which performs all three functions: it generates private keys, derives the corresponding public keys, helps @@ -80,13 +67,7 @@ This protects the private keys when they aren't being used, but it cannot protect against an attack designed to capture the encryption key or to read the decrypted keys from memory. -{% endautocrossref %} - - #### Signing-Only Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} To increase security, private keys can be generated and stored by a separate wallet program operating in a more secure environment. These @@ -120,12 +101,7 @@ peer-to-peer network. The following subsections describe the two most common variants of signing-only wallets: offline wallets and hardware wallets. -{% endautocrossref %} - ##### Offline Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} Several full-service wallets programs will also operate as two separate wallets: one program instance acting as a signing-only wallet (often called an @@ -172,14 +148,7 @@ The offline device must be booted up whenever funds are to be spent, and the user must physically copy data from the online device to the offline device and back. -{% endautocrossref %} - - - ##### Hardware Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} Hardware wallets are devices dedicated to running a signing-only wallet. Their dedication lets them eliminate many of the vulnerabilities @@ -218,15 +187,7 @@ writing, very few popular wallet programs support hardware wallets---although almost all popular wallet programs have announced their intention to support at least one model of hardware wallet. -{% endautocrossref %} - - - - #### Distributing-Only Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} Wallet programs which run in difficult-to-secure environments, such as webservers, can be designed to distribute public keys (including P2PKH @@ -253,36 +214,19 @@ database is used anyway to associate each incoming payment with a separate public key for payment tracking. See the [Payment Processing][devguide payment processing] section for details. -{% endautocrossref %} - - - ### Wallet Files -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin wallets at their core are a collection of private keys. These collections are stored digitally in a file, or can even be physically stored on pieces of paper. -{% endautocrossref %} - #### Private Key Formats -{% include helpers/subhead-links.md %} - -{% autocrossref %} Private keys are what are used to unlock satoshis from a particular address. In Bitcoin, a private key in standard format is simply a 256-bit number, between the values: 0x01 and 0xFFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFE BAAE DCE6 AF48 A03B BFD2 5E8C D036 4140, representing nearly the entire range of 2256-1 values. The range is governed by the secp256k1 ECDSA encryption standard used by Bitcoin. -{% endautocrossref %} - ##### Wallet Import Format (WIF) -{% include helpers/subhead-links.md %} - -{% autocrossref %} In order to make copying of private keys less prone to error, [Wallet Import Format][/en/glossary/wallet-import-format]{:#term-wallet-import-format}{:.term} may be utilized. WIF uses base58Check encoding on an private key, greatly decreasing the chance of copying error, much like standard Bitcoin addresses. @@ -306,12 +250,7 @@ In order to make copying of private keys less prone to error, [Wallet Import For The process is easily reversible, using the Base58 decoding function, and removing the padding. -{% endautocrossref %} - ##### Mini Private Key Format -{% include helpers/subhead-links.md %} - -{% autocrossref %} Mini private key format is a method for encoding a private key in under 30 characters, enabling keys to be embedded in a small physical space, such as physical bitcoin tokens, and more damage-resistant QR codes. @@ -328,15 +267,7 @@ Many implementations disallow the character '1' in the mini private key due to i **Resource:** A common tool to create and redeem these keys is the [Casascius Bitcoin Address Utility][casascius address utility]. -{% endautocrossref %} - - - - #### Public Key Formats -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin ECDSA public keys represent a point on a particular Elliptic Curve (EC) defined in secp256k1. In their traditional uncompressed form, @@ -389,19 +320,13 @@ help programs identify how keys should be used: the midpoint of the curve. These prefix bytes are all used in official secp256k1 documentation. -{% endautocrossref %} - - #### Hierarchical Deterministic Key Creation -{% include helpers/subhead-links.md %} -{% autocrossref %} - The hierarchical deterministic key creation and transfer protocol ([HD protocol][/en/glossary/hd-protocol]{:#term-hd-protocol}{:.term}) greatly simplifies wallet backups, eliminates the need for repeated communication between multiple @@ -417,12 +342,8 @@ function, [`point()`][point function]{:#term-point-function}{:.term}, which takes a large integer (the private key) and turns it into a graph point (the public key): -{% endautocrossref %} - point(private_key) == public_key -{% autocrossref %} - Because of the way `point()` works, it's possible to create a [child public key][/en/glossary/child-key]{:#term-child-public-key}{:.term} by combining an existing [(parent) public key][/en/glossary/parent-key]{:#term-parent-public-key}{:.term} with another public key created from any @@ -431,12 +352,8 @@ would be created by the `point()` function if you added the *i* value to the original (parent) private key and then found the remainder of that sum divided by a global constant used by all Bitcoin software (*p*): -{% endautocrossref %} - point( (parent_private_key + i) % p ) == parent_public_key + point(i) -{% autocrossref %} - This means that two or more independent programs which agree on a sequence of integers can create a series of unique [child key][/en/glossary/child-key]{:#term-child-key}{:.term} pairs from a single [parent key][/en/glossary/parent-key]{:#term-parent-key}{:.term} pair without any further communication. @@ -449,12 +366,8 @@ Child public keys can also create their own child public keys (grandchild public keys) by repeating the child key derivation operations: -{% endautocrossref %} - point( (child_private_key + i) % p ) == child_public_key + point(i) -{% autocrossref %} - Whether creating child public keys or further-descended public keys, a predictable sequence of integer values would be no better than using a single public key for all transactions, as anyone who knew one child @@ -497,14 +410,10 @@ lefthand side of the hash output are used as the integer value to be combined with either the parent private key or parent public key to, respectively, create either a child private key or child public key: -{% endautocrossref %} - child_private_key == (parent_private_key + lefthand_hash_output) % G child_public_key == point( (parent_private_key + lefthand_hash_output) % G ) child_public_key == point(child_private_key) == parent_public_key + point(lefthand_hash_output) -{% autocrossref %} - Specifying different index numbers will create different unlinkable child keys from the same parent keys. Repeating the procedure for the child keys using the child chain code will create unlinkable grandchild keys. @@ -541,12 +450,7 @@ key. The master extended keys are functionally equivalent to other extended keys; it is only their location at the top of the hierarchy which makes them special. -{% endautocrossref %} - ##### Hardened Keys -{% include helpers/subhead-links.md %} - -{% autocrossref %} Hardened extended keys fix a potential problem with normal extended keys. If an attacker gets a normal parent @@ -631,12 +535,7 @@ public keys and extended private keys. For details, please see the [wallet section in the developer reference][devref wallets] or BIP32 for the full HD protocol specification. -{% endautocrossref %} - ##### Storing Root Seeds -{% include helpers/subhead-links.md %} - -{% autocrossref %} Root seeds in the HD protocol are 128, 256, or 512 bits of random data which must be backed up precisely. To make it more convenient to use @@ -665,14 +564,7 @@ duress. For implementation details, please see BIP39. -{% endautocrossref %} - - - #### Loose-Key Wallets -{% include helpers/subhead-links.md %} - -{% autocrossref %} Loose-Key wallets, also called "Just a Bunch Of Keys (JBOK)", are a deprecated form of wallet that originated from the Bitcoin Core client wallet. The Bitcoin Core client wallet would create 100 private key/public key pairs automatically via a Pseudo-Random-Number Generator (PRNG) for later use. @@ -685,4 +577,3 @@ This created considerable difficulty in backing up one’s keys, con This wallet type is being actively phased out and discouraged from being used due to the backup hassle. -{% endautocrossref %} diff --git a/_devdocs/references/block_chain.md b/_devdocs/references/block_chain.md index 2db7583db4..c698a5c506 100644 --- a/_devdocs/references/block_chain.md +++ b/_devdocs/references/block_chain.md @@ -5,14 +5,10 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/ref_block_chain.md" %} ## Block Chain -{% include helpers/subhead-links.md %} The following subsections briefly document core block details. ### Block Headers -{% include helpers/subhead-links.md %} - -{% autocrossref %} Block headers are serialized in the 80-byte format described below and then hashed as part of Bitcoin's proof-of-work algorithm, making the @@ -45,12 +41,7 @@ b6ff0b1b1680a2862a30ca44d346d9e8 fe9f0864 ........................... Nonce {% endhighlight %} -{% endautocrossref %} - #### Block Versions -{% include helpers/subhead-links.md %} - -{% autocrossref %} * **Version 1** was introduced in the genesis block (January 2009). @@ -88,12 +79,7 @@ function. Draft BIP9 describes the version bits design as of this writing, although it is still being actively edited and may substantially change while in the draft state. -{% endautocrossref %} - #### Merkle Trees -{% include helpers/subhead-links.md %} - -{% autocrossref %} The merkle root is constructed using all the TXIDs of transactions in this block, but first the TXIDs are placed in order as required by the @@ -138,12 +124,7 @@ TXIDs and intermediate hashes are always in internal byte order when they're concatenated, and the resulting merkle root is also in internal byte order when it's placed in the block header. -{% endautocrossref %} - #### Target nBits -{% include helpers/subhead-links.md %} - -{% autocrossref %} The target threshold is a 256-bit unsigned integer which a header hash must be equal to or below in order for that header to be a valid part of @@ -200,13 +181,7 @@ a different difficulty 1 value---0x207fffff, the highest possible value below uint32_max which can be encoded; this allows near-instant building of blocks in regtest mode. -{% endautocrossref %} - - ### Serialized Blocks -{% include helpers/subhead-links.md %} - -{% autocrossref %} Under current consensus rules, a block is not valid unless its serialized size is less than or equal to 1 MB. All fields described @@ -232,5 +207,3 @@ reward][/en/glossary/block-reward]{:#term-block-reward}{:.term}. A coinbase tran invalid if it tries to spend more value than is available from the block reward. -{% endautocrossref %} - diff --git a/_devdocs/references/intro.md b/_devdocs/references/intro.md index 16b80ad365..6ebf42dc90 100644 --- a/_devdocs/references/intro.md +++ b/_devdocs/references/intro.md @@ -4,8 +4,6 @@ http://opensource.org/licenses/MIT. {% endcomment %} {% assign filename="_includes/devdoc/ref_intro.md" %} -{% autocrossref %} - The Developer Reference aims to provide technical details and API information to help you start building Bitcoin-based applications, but it is [not a specification][]. To make the best use of @@ -24,13 +22,8 @@ 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 %} - #### Not A Specification {:.no_toc} -{% include helpers/subhead-links.md %} - -{% autocrossref %} The Bitcoin.org Developer Documentation describes how Bitcoin works to help educate new Bitcoin developers, but it is not a specification---and @@ -65,4 +58,3 @@ allow you to report an issue or to edit the documentation on GitHub. Please use those links if you find any errors or important missing information. -{% endautocrossref %} diff --git a/_devdocs/references/p2p_networking.md b/_devdocs/references/p2p_networking.md index ce973d198f..2fd9755d17 100644 --- a/_devdocs/references/p2p_networking.md +++ b/_devdocs/references/p2p_networking.md @@ -5,9 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/ref_p2p_networking.md" %} ## P2P Network -{% include helpers/subhead-links.md %} - -{% autocrossref %} This section describes the Bitcoin P2P network protocol (but it is [not a specification][]). It does not describe the discontinued direct [IP-to-IP @@ -20,12 +17,7 @@ All peer-to-peer communication occurs entirely over TCP. **Note:** unless their description says otherwise, all multi-byte integers mentioned in this section are transmitted in little-endian order. -{% endautocrossref %} - ### Constants And Defaults -{% include helpers/subhead-links.md %} - -{% autocrossref %} The following constants and defaults are taken from Bitcoin Core's [chainparams.cpp][core chainparams.cpp] source code file. @@ -51,12 +43,7 @@ Bitcoin Core's [chainparams.cpp][core chainparams.cpp] also includes other constants useful to programs, such as the hash of the genesis blocks for the different networks. -{% endautocrossref %} - ### Protocol Versions -{% include helpers/subhead-links.md %} - -{% autocrossref %} The table below lists some notable versions of the P2P network protocol, with the most recent versions listed first. (If you know of a protocol @@ -83,12 +70,7 @@ As of Bitcoin Core 0.14.2, the most recent protocol version is 70015. | 209 | Bitcoin Core 0.2.9
(May 2010) | • Added checksum field to message headers. | 106 | Bitcoin Core 0.1.6
(Oct 2009) | • Added receive IP address fields to `version` message. -{% endautocrossref %} - ### Message Headers -{% include helpers/subhead-links.md %} - -{% autocrossref %} All messages in the network protocol use the same container format, which provides a required multi-field message header and an optional payload. @@ -111,12 +93,7 @@ f9beb4d9 ................... Start string: Mainnet 5df6e0e2 ................... Checksum: SHA256(SHA256()) {% endhighlight %} -{% endautocrossref %} - ### Data Messages -{% include helpers/subhead-links.md %} - -{% autocrossref %} The following network messages all request or provide data related to transactions and blocks. @@ -145,12 +122,7 @@ Type identifier zero and type identifiers greater than three are reserved for future implementations. Bitcoin Core ignores all inventories with one of these unknown types. -{% endautocrossref %} - #### Block -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `block` message transmits a single serialized block in the format described in the [serialized blocks section][section serialized blocks]. @@ -168,12 +140,7 @@ different reasons: send the block from multiple nodes, possibly sending the same block to some peers more than once. -{% endautocrossref %} - #### GetBlocks -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `getblocks` message requests an `inv` message that provides block header hashes starting from a particular point in the block chain. It @@ -220,12 +187,7 @@ d39f608a7775b537729884d4e6633bb2 00000000000000000000000000000000 ... Stop hash {% endhighlight %} -{% endautocrossref %} - #### GetData -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `getdata` message requests one or more data objects from another node. The objects are requested by an inventory, which the requesting @@ -244,12 +206,7 @@ previously advertised it had that data by sending an `inv` message. The format and maximum size limitations of the `getdata` message are identical to the `inv` message; only the message header differs. -{% endautocrossref %} - #### GetHeaders -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 31800.* @@ -263,12 +220,7 @@ with one minor difference: the `inv` reply to the `getblocks` message will include no more than 500 block header hashes; the `headers` reply to the `getheaders` message will include as many as 2,000 block headers. -{% endautocrossref %} - #### Headers -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 31800.* @@ -299,12 +251,7 @@ fe9f0864 ........................... Nonce 00 ................................. Transaction count (0x00) {% endhighlight %} -{% endautocrossref %} - #### Inv -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `inv` message (inventory message) transmits one or more inventories of objects known to the transmitting peer. It can be sent unsolicited to @@ -335,12 +282,7 @@ de55ffd709ac1f5dc509a0925d0b1fc4 a055aaf1d872e94ae85e9817b2c68dc7 ... Hash (TXID) {% endhighlight %} -{% endautocrossref %} - #### MemPool -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 60002.* @@ -384,12 +326,7 @@ be complete: There is no payload in a `mempool` message. See the [message header section][section message header] for an example of a message without a payload. -{% endautocrossref %} - #### MerkleBlock -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70001 as described by BIP37.* @@ -453,7 +390,6 @@ a `tx` message. ##### Parsing A MerkleBlock Message {:.no_toc} -{% include helpers/subhead-links.md %} As seen in the annotated hexdump above, the `merkleblock` message provides three special data types: a transaction count, a list of @@ -526,7 +462,6 @@ example]. ##### Creating A MerkleBlock Message {:.no_toc} -{% include helpers/subhead-links.md %} It's easier to understand how to create a `merkleblock` message after you understand how to parse an already-created message, so we recommend @@ -570,12 +505,7 @@ instructions in the table above, processing is complete. Pad your flag list to a byte boundary and construct the `merkleblock` message using the template near the beginning of this subsection. -{% endautocrossref %} - #### NotFound -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70001.* @@ -589,12 +519,7 @@ send those blocks.) The format and maximum size limitations of the `notfound` message are identical to the `inv` message; only the message header differs. -{% endautocrossref %} - #### Tx -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `tx` message transmits a single transaction in the raw transaction format. It can be sent in a variety of situations; @@ -615,16 +540,7 @@ format. It can be sent in a variety of situations; For an example hexdump of the raw transaction format, see the [raw transaction section][raw transaction format]. -{% endautocrossref %} - - - - - ### Control Messages -{% include helpers/subhead-links.md %} - -{% autocrossref %} The following network messages all help control the connection between two peers or allow them to advise each other about the rest of the @@ -638,12 +554,7 @@ information. In addition, this section does not yet cover P2P protocol operation over the [Tor network][tor]; if you would like to contribute information about Tor, please [open an issue][docs issue]. -{% endautocrossref %} - #### Addr -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `addr` (IP address) message relays connection information for peers on the network. Each peer which wants to accept incoming @@ -684,27 +595,14 @@ d91f4854 ........................... Epoch time: 1414012889 [...] .............................. (999 more addresses omitted) {% endhighlight %} -{% endautocrossref %} - - - - #### Alert -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 311.* *Removed in protocol version 70013 and released in Bitcoin Core 0.13.0* The legacy p2p network alert messaging system has been retired; however, internal alerts, partition detection warnings and the `-alertnotify` option features remain. See [Alert System Retirement](https://bitcoin.org/en/alert/2016-11-01-alert-retirement) for details. -{% endautocrossref %} - #### FeeFilter -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70013 as described by BIP133.* @@ -743,17 +641,11 @@ inv messages generated from a mempool message are subject to a fee filter if it The annotated hexdump below shows a `feefilter` message. (The message header has been omitted.) -{% endautocrossref %} - {% highlight text %} 7cbd000000000000 ... satoshis per kilobyte: 48,508 {% endhighlight %} - #### FilterAdd -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70001 as described by BIP37.* @@ -788,12 +680,7 @@ fdacf9b3eb077412e7a968d2e4f11b9a 9dee312d666187ed77ee7d26af16cb0b ... Element (A TXID) {% endhighlight %} -{% endautocrossref %} - #### FilterClear -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70001 as described by BIP37.* @@ -809,13 +696,7 @@ a `filterload` message before a `filterclear` message. There is no payload in a `filterclear` message. See the [message header section][section message header] for an example of a message without a payload. -{% endautocrossref %} - - #### FilterLoad -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70001 as described by BIP37.* @@ -1048,12 +929,7 @@ make the filter useless. For this reason, clients using automatic filter updates need to monitor the actual false positive rate and send a new filter when the rate gets too high. -{% endautocrossref %} - #### GetAddr -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `getaddr` message requests an `addr` message from the receiving node, preferably one with lots of IP addresses of other receiving nodes. @@ -1064,13 +940,7 @@ messages to arrive over time. There is no payload in a `getaddr` message. See the [message header section][section message header] for an example of a message without a payload. -{% endautocrossref %} - - #### Ping -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `ping` message helps confirm that the receiving peer is still connected. If a TCP/IP error is encountered when sending the `ping` @@ -1093,12 +963,7 @@ header has been omitted.) 0094102111e2af4d ... Nonce {% endhighlight %} -{% endautocrossref %} - #### Pong -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 60001 as described by BIP31.* @@ -1113,12 +978,7 @@ the same nonce received in the `ping` message it is replying to. The format of the `pong` message is identical to the `ping` message; only the message header differs. -{% endautocrossref %} - #### Reject -{% include helpers/subhead-links.md %} - -{% autocrossref %} *Added in protocol version 70002 as described by BIP61.* @@ -1169,12 +1029,7 @@ header has been omitted.) 947baf86a31017939575fb2354222821 ... TXID {% endhighlight %} -{% endautocrossref %} - #### SendHeaders -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `sendheaders` message tells the receiving peer to send new block announcements using a `headers` message rather than an `inv` message. @@ -1182,12 +1037,7 @@ announcements using a `headers` message rather than an `inv` message. There is no payload in a `sendheaders` message. See the [message header section][section message header] for an example of a message without a payload. -{% endautocrossref %} - #### VerAck -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `verack` message acknowledges a previously-received `version` message, informing the connecting node that it can begin to send @@ -1195,13 +1045,7 @@ other messages. The `verack` message has no payload; for an example of a message with no payload, see the [message headers section][section message header]. -{% endautocrossref %} - - #### Version -{% include helpers/subhead-links.md %} - -{% autocrossref %} The `version` message provides information about the transmitting node to the receiving node at the beginning of a connection. Until both peers @@ -1262,4 +1106,3 @@ cf050500 ........................... Start height: 329167 01 ................................. Relay flag: true {% endhighlight %} -{% endautocrossref %} diff --git a/_devdocs/references/transactions.md b/_devdocs/references/transactions.md index 6c4d27a2db..2cb1c17278 100644 --- a/_devdocs/references/transactions.md +++ b/_devdocs/references/transactions.md @@ -5,14 +5,10 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/ref_transactions.md" %} ## Transactions -{% include helpers/subhead-links.md %} The following subsections briefly document core transaction details. #### OpCodes -{% include helpers/subhead-links.md %} - -{% autocrossref %} The opcodes used in the pubkey scripts of standard transactions are: @@ -124,12 +120,7 @@ Failure, aborted: two signature matches required but none found so far, and there's only one pubkey remaining {% endhighlight %} -{% endautocrossref %} - #### Address Conversion -{% include helpers/subhead-links.md %} - -{% autocrossref %} The hashes used in P2PKH and P2SH outputs are commonly encoded as Bitcoin addresses. This is the procedure to encode those hashes and decode the @@ -194,12 +185,7 @@ To convert addresses back into hashes, reverse the base58 encoding, extract the checksum, repeat the steps to create the checksum and compare it against the extracted checksum, and then remove the version byte. -{% endautocrossref %} - #### Raw Transaction Format -{% include helpers/subhead-links.md %} - -{% autocrossref %} Bitcoin transactions are broadcast between peers in a serialized byte format, called [raw format][/en/glossary/serialized-transaction]{:#term-raw-format}{:.term}. @@ -231,13 +217,8 @@ txOut structures may recur within a transaction. CompactSize unsigned integers are a form of variable-length integers; they are described in the [CompactSize section][section CompactSize unsigned integer]. -{% endautocrossref %} - ##### TxIn: A Transaction Input (Non-Coinbase) {#txin} {:.no_toc} -{% include helpers/subhead-links.md %} - -{% autocrossref %} Each non-coinbase input spends an outpoint from a previous transaction. (Coinbase inputs are described separately after the example section below.) @@ -249,13 +230,8 @@ Each non-coinbase input spends an outpoint from a previous transaction. | *Varies* | signature script | char[] | A script-language script which satisfies the conditions placed in the outpoint's pubkey script. Should only contain data pushes; see the [signature script modification warning][]. | 4 | sequence | uint32_t | Sequence number. Default for Bitcoin Core and almost all other programs is 0xffffffff. -{% endautocrossref %} - ##### Outpoint: The Specific Part Of A Specific Output {#outpoint} {:.no_toc} -{% include helpers/subhead-links.md %} - -{% autocrossref %} Because a single transaction can include multiple outputs, the outpoint structure includes both a TXID and an output index number to refer to @@ -266,13 +242,8 @@ specific output. | 32 | hash | char[32] | The TXID of the transaction holding the output to spend. The TXID is a hash provided here in internal byte order. | 4 | index | uint32_t | The output index number of the specific output to spend from the transaction. The first output is 0x00000000. -{% endautocrossref %} - ##### TxOut: A Transaction Output {#txout} {:.no_toc} -{% include helpers/subhead-links.md %} - -{% autocrossref %} Each output spends a certain number of satoshis, placing them under control of anyone who can satisfy the provided pubkey script. @@ -324,13 +295,8 @@ to a new pay-to-pubkey-hash (P2PKH) output. 00000000 ................................... locktime: 0 (a block height) {% endhighlight %} -{% endautocrossref %} - ##### Coinbase Input: The Input Of The First Transaction In A Block {#coinbase} {:.no_toc} -{% include helpers/subhead-links.md %} - -{% autocrossref %} The first transaction in a block, called the coinbase transaction, must have exactly one input, called a coinbase. The coinbase input currently @@ -382,12 +348,7 @@ An itemized coinbase transaction: | 00000000 ............................ Locktime {% endhighlight %} -{% endautocrossref %} - ### CompactSize Unsigned Integers -{% include helpers/subhead-links.md %} - -{% autocrossref %} The raw transaction format and several peer-to-peer network messages use a type of variable-length integer to indicate the number of bytes in a @@ -415,4 +376,3 @@ the numbers look like regular unsigned integers in little-endian order. For example, the number 515 is encoded as 0xfd0302. -{% endautocrossref %} diff --git a/_devdocs/references/wallets.md b/_devdocs/references/wallets.md index d7a0ef5804..1c54dbb24e 100644 --- a/_devdocs/references/wallets.md +++ b/_devdocs/references/wallets.md @@ -5,7 +5,6 @@ http://opensource.org/licenses/MIT. {% assign filename="_includes/devdoc/ref_wallets.md" %} ## Wallets -{% include helpers/subhead-links.md %} ### Deterministic Wallet Formats @@ -13,23 +12,16 @@ http://opensource.org/licenses/MIT. #### Type 1: Single Chain Wallets -{% autocrossref %} - Type 1 deterministic wallets are the simpler of the two, which can create a single series of keys from a single seed. A primary weakness is that if the seed is leaked, all funds are compromised, and wallet sharing is extremely limited. -{% endautocrossref %} - #### Type 2: Hierarchical Deterministic (HD) Wallets -{% autocrossref %} - ![Overview Of Hierarchical Deterministic Key Derivation](/img/dev/en-hd-overview.svg) For an overview of HD wallets, please see the [developer guide section][devguide wallets]. For details, please see BIP32. -{% endautocrossref %}