From 90608482b5335dca74b8a205fcd8217bafd4527b Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Fri, 14 May 2021 19:57:18 +0530 Subject: [PATCH] Corrected links for few Glossary terms that were before pointing to terms.rst. Closes #79. In the previous commints all the keywords from terms.rst hve been moved to glossary.rst but their reference links in various pages have not updated. This commit updates all those links so that, now all those keywords point their definition in glossary.rst Final commit in order to fix #79. --- devguide/block_chain.rst | 2 +- devguide/contracts.rst | 10 ++--- devguide/p2p_network.rst | 20 +++++----- devguide/payment_processing.rst | 70 ++++++++++++++++----------------- devguide/transactions.rst | 36 ++++++++--------- devguide/wallets.rst | 12 +++--- examples/payment_processing.rst | 68 ++++++++++++++++---------------- examples/transactions.rst | 10 ++--- glossary.rst | 43 ++++++++++---------- reference/block_chain.rst | 4 +- reference/p2p_networking.rst | 42 ++++++++++---------- reference/transactions.rst | 32 +++++++-------- 12 files changed, 173 insertions(+), 176 deletions(-) diff --git a/devguide/block_chain.rst b/devguide/block_chain.rst index 4bbfbb3..8f3f333 100644 --- a/devguide/block_chain.rst +++ b/devguide/block_chain.rst @@ -154,4 +154,4 @@ In either case, block and transaction data should not be relied upon if it comes SPV clients which connect to full nodes can detect a likely hard fork by connecting to several full nodes and ensuring that they’re all on the same chain with the same block height, plus or minus several blocks to account for transmission delays and stale blocks. If there’s a divergence, the client can disconnect from nodes with weaker chains. -SPV clients should also monitor for block and :ref:`transaction version number ` increases to ensure they process received transactions and create new transactions using the current consensus rules. +SPV clients should also monitor for block and :term:`transaction version number ` increases to ensure they process received transactions and create new transactions using the current consensus rules. diff --git a/devguide/contracts.rst b/devguide/contracts.rst index 77832b4..61da0f5 100644 --- a/devguide/contracts.rst +++ b/devguide/contracts.rst @@ -41,7 +41,7 @@ In the signature script Alice puts her signature and a copy of the unhashed seri OP_0 [A's signature] [B's or C's signature] [serialized redeem script] -(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 the signature script must provide signatures in the same order as the corresponding public keys appear in the redeem script. See the description in :ref:`“OP_CHECKMULTISIG” ` for details.) +(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 the signature script must provide signatures in the same order as the corresponding public keys appear in the redeem script. See the description in :term:`“OP_CHECKMULTISIG” ` for details.) When the transaction is broadcast to the `network <../devguide/p2p_network.html>`__, each peer checks the signature script against the P2SH output Charlie previously paid, ensuring that the redeem script matches the redeem script hash previously provided. Then the redeem script is evaluated, with the two signatures being used as input data. Assuming the redeem script validates, the two transaction outputs show up in Bob’s and Charlie’s wallets as spendable balances. @@ -52,7 +52,7 @@ However, if Alice created and signed a transaction neither of them would agree t Micropayment Channel -------------------- -Alice also works part time moderating forum posts for Bob. Every time someone posts to Bob’s busy forum, Alice skims the post to make sure it isn’t offensive or spam. Alas, Bob often forgets to pay her, so Alice demands to be paid immediately after each post she approves or rejects. Bob says he can’t do that because hundreds of small payments will cost him thousands of satoshis in transaction fees, so Alice suggests they use a :ref:`micropayment channel `. +Alice also works part time moderating forum posts for Bob. Every time someone posts to Bob’s busy forum, Alice skims the post to make sure it isn’t offensive or spam. Alas, Bob often forgets to pay her, so Alice demands to be paid immediately after each post she approves or rejects. Bob says he can’t do that because hundreds of small payments will cost him thousands of satoshis in transaction fees, so Alice suggests they use a micropayment channel. Bob asks Alice for her public key and then creates two transactions. The first transaction pays 100 millibitcoins to a P2SH output whose 2-of-2 multisig redeem script requires signatures from both Alice and Bob. This is the bond transaction. Broadcasting this transaction would let Alice hold the millibitcoins hostage, so Bob keeps this transaction private for now and creates a second transaction. @@ -67,11 +67,11 @@ Alice checks that the `refund <../devguide/payment_processing.html#issuing-refun Now, when Alice does some work worth 1 millibitcoin, she asks Bob to create and sign a new version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction. Version two of the transaction spends 1 millibitcoin to Alice and the other 99 back to Bob; it does not have a locktime, so Alice can sign it and spend it whenever she wants. (But she doesn’t do that immediately.) -Alice and Bob repeat these work-and-pay steps until Alice finishes for the day, or until the time lock is about to expire. Alice signs the final version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction and broadcasts it, paying herself and refunding any remaining balance to Bob. The next day, when Alice starts work, they create a new :ref:`micropayment channel `. +Alice and Bob repeat these work-and-pay steps until Alice finishes for the day, or until the time lock is about to expire. Alice signs the final version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction and broadcasts it, paying herself and refunding any remaining balance to Bob. The next day, when Alice starts work, they create a new micropayment channel. -If Alice fails to broadcast a version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction before its time lock expires, Bob can broadcast the first version and receive a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. This is one reason :ref:`micropayment channels ` are best suited to small payments—if Alice’s Internet service goes out for a few hours near the time lock expiry, she could be cheated out of her payment. +If Alice fails to broadcast a version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction before its time lock expires, Bob can broadcast the first version and receive a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. This is one reason micropayment channels are best suited to small payments—if Alice’s Internet service goes out for a few hours near the time lock expiry, she could be cheated out of her payment. -Transaction malleability, discussed above in the Transactions section, is another reason to limit the value of :ref:`micropayment channels `. If someone uses transaction malleability to break the link between the two transactions, Alice could hold Bob’s 100 millibitcoins hostage even if she hadn’t done any work. +Transaction malleability, discussed above in the Transactions section, is another reason to limit the value of micropayment channels. If someone uses transaction malleability to break the link between the two transactions, Alice could hold Bob’s 100 millibitcoins hostage even if she hadn’t done any work. For larger payments, Bitcoin transaction fees are very low as a percentage of the total transaction value, so it makes more sense to protect payments with immediately-broadcast separate transactions. diff --git a/devguide/p2p_network.rst b/devguide/p2p_network.rst index 66896cd..55c6094 100644 --- a/devguide/p2p_network.rst +++ b/devguide/p2p_network.rst @@ -81,7 +81,7 @@ The first time a node is started, it only has a single block in its local best b In the header hashes field of the `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, this new node sends the header hash of the only block it has, the genesis block (6fe2…0000 in internal byte order). It also sets the stop hash field to all zeroes to request a maximum-size response. -Upon :ref:`receipt ` of the `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 500 block inventories (the maximum response to a `“getblocks” message <../reference/p2p_networking.html#getblocks>`__) starting from block 1. It sends these inventories in the `“inv” message <../reference/p2p_networking.html#inv>`__ illustrated below. +Upon :term:`receipt ` of the `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 500 block inventories (the maximum response to a `“getblocks” message <../reference/p2p_networking.html#getblocks>`__) starting from block 1. It sends these inventories in the `“inv” message <../reference/p2p_networking.html#inv>`__ illustrated below. .. figure:: /img/dev/en-ibd-inv.svg :alt: First Inv Message Sent During IBD @@ -101,7 +101,7 @@ The IBD node uses the received inventories to request 128 blocks from the sync n It’s important to blocks-first nodes that the blocks be requested and sent in order because each block header references the header hash of the preceding block. That means the IBD node can’t fully validate a block until its parent block has been received. Blocks that can’t be validated because their parents haven’t been received are called orphan blocks; a subsection below describes them in more detail. -Upon :ref:`receipt ` of the `“getdata” message <../reference/p2p_networking.html#getdata>`__, the sync node replies with each of the blocks requested. Each block is put into serialized block format and sent in a separate `“block” message <../reference/p2p_networking.html#block>`__. The first `“block” message <../reference/p2p_networking.html#block>`__ sent (for block 1) is illustrated below. +Upon :term:`receipt ` of the `“getdata” message <../reference/p2p_networking.html#getdata>`__, the sync node replies with each of the blocks requested. Each block is put into serialized block format and sent in a separate `“block” message <../reference/p2p_networking.html#block>`__. The first `“block” message <../reference/p2p_networking.html#block>`__ sent (for block 1) is illustrated below. .. figure:: /img/dev/en-ibd-block.svg :alt: First Block Message Sent During IBD @@ -115,7 +115,7 @@ The IBD node downloads each block, validates it, and then requests the next bloc Second GetBlocks Message Sent During IBD -Upon :ref:`receipt ` of the second `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node searches its local best block chain for a block that matches one of the header hashes in the message, trying each hash in the order they were received. If it finds a matching hash, it replies with 500 block inventories starting with the next block from that point. But if there is no matching hash (besides the stopping hash), it assumes the only block the two nodes have in common is block 0 and so it sends an ``inv`` starting with block 1 (the same `“inv” message <../reference/p2p_networking.html#inv>`__ seen several illustrations above). +Upon :term:`receipt ` of the second `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node searches its local best block chain for a block that matches one of the header hashes in the message, trying each hash in the order they were received. If it finds a matching hash, it replies with 500 block inventories starting with the next block from that point. But if there is no matching hash (besides the stopping hash), it assumes the only block the two nodes have in common is block 0 and so it sends an ``inv`` starting with block 1 (the same `“inv” message <../reference/p2p_networking.html#inv>`__ seen several illustrations above). This repeated search allows the sync node to send useful inventories even if the IBD node’s local block chain forked from the sync node’s local block chain. This fork detection becomes increasingly useful the closer the IBD node gets to the tip of the block chain. @@ -171,7 +171,7 @@ The first time a node is started, it only has a single block in its local best b In the header hashes field of the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__, the new node sends the header hash of the only block it has, the genesis block (6fe2…0000 in internal byte order). It also sets the stop hash field to all zeroes to request a maximum-size response. -Upon :ref:`receipt ` of the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 2,000 header (the maximum response) starting from block 1. It sends these header hashes in the `“headers” message <../reference/p2p_networking.html#headers>`__ illustrated below. +Upon :term:`receipt ` of the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 2,000 header (the maximum response) starting from block 1. It sends these header hashes in the `“headers” message <../reference/p2p_networking.html#headers>`__ illustrated below. .. figure:: /img/dev/en-ibd-headers.svg :alt: First headers message @@ -218,9 +218,9 @@ Block Broadcasting When a miner discovers a new block, it broadcasts the new block to its peers using one of the following methods: -- :ref:`Unsolicited Block Push `\ **:** the miner sends a `“block” message <../reference/p2p_networking.html#block>`__ to each of its full node peers with the new block. The miner can reasonably bypass the standard relay method in this way because it knows none of its peers already have the just-discovered block. +- :term:`Unsolicited Block Push `\ **:** the miner sends a `“block” message <../reference/p2p_networking.html#block>`__ to each of its full node peers with the new block. The miner can reasonably bypass the standard relay method in this way because it knows none of its peers already have the just-discovered block. -- :ref:`Standard Block Relay `\ **:** the miner, acting as a standard relay node, sends an `“inv” message <../reference/p2p_networking.html#inv>`__ to each of its peers (both full node and SPV) with an inventory referring to the new block. The most common responses are: +- :term:`Standard Block Relay `\ **:** the miner, acting as a standard relay node, sends an `“inv” message <../reference/p2p_networking.html#inv>`__ to each of its peers (both full node and SPV) with an inventory referring to the new block. The most common responses are: - Each blocks-first (BF) peer that wants the block replies with a `“getdata” message <../reference/p2p_networking.html#getdata>`__ requesting the full block. @@ -234,9 +234,9 @@ When a miner discovers a new block, it broadcasts the new block to its peers usi This protocol for block broadcasting was proposed in BIP 130 and has been implemented in Bitcoin Core since version 0.12. -By default, Bitcoin Core broadcasts blocks using direct headers announcement to any peers that have signalled with `“sendheaders” <../reference/p2p_networking.html#sendheaders>`__ and uses :ref:`standard block relay ` for all peers that have not. Bitcoin Core will accept blocks sent using any of the methods described above. +By default, Bitcoin Core broadcasts blocks using direct headers announcement to any peers that have signalled with `“sendheaders” <../reference/p2p_networking.html#sendheaders>`__ and uses :term:`standard block relay ` for all peers that have not. Bitcoin Core will accept blocks sent using any of the methods described above. -Full nodes validate the received block and then advertise it to their peers using the :ref:`standard block relay ` method described above. The condensed table below highlights the operation of the messages described above (Relay, BF, HF, and SPV refer to the relay node, a blocks-first node, a headers-first node, and an SPV client; *any* refers to a node using any block retrieval method.) +Full nodes validate the received block and then advertise it to their peers using the :term:`standard block relay ` method described above. The condensed table below highlights the operation of the messages described above (Relay, BF, HF, and SPV refer to the relay node, a blocks-first node, a headers-first node, and an SPV client; *any* refers to a node using any block retrieval method.) +------------------------------------------------------------------+---------------+------------------------------------------------------------------------------------------+ | Message | From→To | Payload | @@ -259,7 +259,7 @@ Full nodes validate the received block and then advertise it to their peers usin Orphan Blocks ~~~~~~~~~~~~~ -Blocks-first nodes may download orphan blocks—blocks whose :ref:`previous block header hash ` field refers to a block header this node hasn’t seen yet. In other words, orphan blocks have no known parent (unlike stale blocks, which have known parents but which aren’t part of the best block chain). +Blocks-first nodes may download orphan blocks—blocks whose :term:`previous block header hash ` field refers to a block header this node hasn’t seen yet. In other words, orphan blocks have no known parent (unlike stale blocks, which have known parents but which aren’t part of the best block chain). .. figure:: /img/dev/en-orphan-stale-definition.svg :alt: Difference Between Orphan And Stale Blocks @@ -270,7 +270,7 @@ When a blocks-first node downloads an orphan block, it will not validate it. Ins Headers-first nodes avoid some of this complexity by always requesting block headers with the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__ before requesting a block with the `“getdata” message <../reference/p2p_networking.html#getdata>`__. The broadcasting node will send a `“headers” message <../reference/p2p_networking.html#headers>`__ containing all the block headers (up to 2,000) it thinks the downloading node needs to reach the tip of the best header chain; each of those headers will point to its parent, so when the downloading node receives the `“block” message <../reference/p2p_networking.html#block>`__, the block shouldn’t be an orphan block—all of its parents should be known (even if they haven’t been validated yet). If, despite this, the block received in the `“block” message <../reference/p2p_networking.html#block>`__ 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 :ref:`unsolicited block push `. +However, orphan discarding does mean that headers-first nodes will ignore orphan blocks sent by miners in an :term:`unsolicited block push `. Transaction Broadcasting ------------------------ diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 8b75923..b5128ad 100644 --- a/devguide/payment_processing.rst +++ b/devguide/payment_processing.rst @@ -1,7 +1,7 @@ Payment Processing ================== -Payment processing encompasses the steps spenders and receivers perform to make and accept payments in exchange for products or services. The basic steps have not changed since the dawn of commerce, but the technology has. +Payment processing encompasses the steps spenders and receivers perform to make and accept payments in exchange for products or services. The basic steps have not changed since the dawn of commerce, but the technology has. Introduction ------------ @@ -20,7 +20,7 @@ It is worth mentioning that each of these steps can be outsourced by using third Pricing Orders -------------- -Because of exchange rate variability between satoshis and national currencies (:ref:`fiat `), many Bitcoin orders are priced in :ref:`fiat ` but paid in satoshis, necessitating a price conversion. +Because of exchange rate variability between satoshis and national currencies (:term:`fiat `), many Bitcoin orders are priced in :term:`fiat ` but paid in satoshis, necessitating a price conversion. Exchange rate data is widely available through HTTP-based APIs provided by currency exchanges. Several organizations also aggregate data from multiple exchanges to create index prices, which are also available using HTTP-based APIs. @@ -30,9 +30,9 @@ To minimize problems, your applications may want to collect data from at least t You may also want to program your applications to enter a safe mode if exchange rates are rapidly increasing or decreasing, indicating a possible problem in the Bitcoin market which could make it difficult to spend any satoshis received today. -Exchange rates lie outside the control of Bitcoin and related technologies, so there are no new or planned technologies which will make it significantly easier for your program to correctly convert order totals from :ref:`fiat ` into satoshis. +Exchange rates lie outside the control of Bitcoin and related technologies, so there are no new or planned technologies which will make it significantly easier for your program to correctly convert order totals from :term:`fiat ` into satoshis. -Because the exchange rate fluctuates over time, order totals pegged to :ref:`fiat ` must expire to prevent spenders from delaying payment in the hope that satoshis will drop in price. Most widely-used payment processing systems currently expire their invoices after 10 to 20 minutes. +Because the exchange rate fluctuates over time, order totals pegged to :term:`fiat ` must expire to prevent spenders from delaying payment in the hope that satoshis will drop in price. Most widely-used payment processing systems currently expire their invoices after 10 to 20 minutes. Shorter expiration periods increase the chance the invoice will expire before payment is received, possibly necessitating manual intervention to request an additional payment or to issue a `refund <../devguide/payment_processing.html#issuing-refunds>`__. Longer expiration periods increase the chance that the exchange rate will fluctuate a significant amount before payment is received. @@ -47,9 +47,9 @@ The next subsections will describe in detail the following four compatible ways 1. All wallet software lets its users paste in or manually enter an address and amount into a payment screen. This is, of course, inconvenient—but it makes an effective fallback option. -2. Almost all desktop wallets can associate with :ref:`“bitcoin:” URIs `, so spenders can click a link to pre-fill the payment screen. This also works with many mobile wallets, but it generally does not work with web-based wallets unless the spender installs a browser extension or manually configures a URI handler. +2. Almost all desktop wallets can associate with :term:`“bitcoin:” URIs `, so spenders can click a link to pre-fill the payment screen. This also works with many mobile wallets, but it generally does not work with web-based wallets unless the spender installs a browser extension or manually configures a URI handler. -3. Most mobile wallets support scanning :ref:`“bitcoin:” URIs ` encoded in a QR code, and almost all wallets can display them for accepting payment. While also handy for online orders, QR Codes are especially useful for in-person purchases. +3. Most mobile wallets support scanning :term:`“bitcoin:” URIs ` encoded in a QR code, and almost all wallets can display them for accepting payment. While also handy for online orders, QR Codes are especially useful for in-person purchases. 4. Recent wallet updates add support for the new payment protocol providing increased security, authentication of a receiver’s identity using `X.509 `__ certificates, and other important features such as `refunds <../devguide/payment_processing.html#issuing-refunds>`__. @@ -84,7 +84,7 @@ Bitcoins Unit (Abbreviation) bitcoin: URI ~~~~~~~~~~~~ -The :ref:`“bitcoin:” URI ` 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: +The :term:`“bitcoin:” URIs ` 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: :: @@ -92,7 +92,7 @@ The :ref:`“bitcoin:” URI ` scheme defined in `BIP21 ` parameter is generally used to provide wallet software with the recipient’s name. The :ref:`“message” ` parameter is generally used to describe the payment request to the spender. Both the label and the message are commonly stored by the spender’s wallet software—but they are never added to the actual transaction, so other Bitcoin users cannot see them. Both the label and the message must be `URI encoded `__. +Two other parameters are widely supported. The :term:`“label”