From ffde087f02c77ddaba5e3ec7ae047807156c6209 Mon Sep 17 00:00:00 2001 From: David Harding Date: Fri, 9 May 2014 22:13:59 -0400 Subject: [PATCH] Contributions by @harding to devel docs Thanks also (in alphabetical order) to @cbeams, @mikehearn, and @tgeller, among others. The last pre-squash commit was: c2b8d562aa107c7b68c60946cea14cdccc5159ad --- _autocrossref.yaml | 296 ++ _includes/guide_block_chain.md | 242 ++ _includes/guide_contracts.md | 288 ++ _includes/guide_intro.md | 62 + _includes/guide_mining.md | 202 ++ _includes/guide_payment_processing.md | 1291 +++++++ _includes/guide_transactions.md | 664 ++++ _includes/ref_core_rpcs-abcdefg.md | 3133 +++++++++++++++++ _includes/ref_core_rpcs-hijklmn.md | 1090 ++++++ _includes/ref_core_rpcs-opqrst.md | 872 +++++ _includes/ref_core_rpcs-uvwxyz.md | 299 ++ _plugins/autocrossref.rb | 81 + img/dev/en-block-height-vs-depth.dot | 39 + img/dev/en-block-height-vs-depth.png | Bin 0 -> 4695 bytes img/dev/en-block-height-vs-depth.svg | 113 + img/dev/en-blockchain-fork.dot | 55 + img/dev/en-blockchain-fork.png | Bin 0 -> 12080 bytes img/dev/en-blockchain-fork.svg | 213 ++ img/dev/en-blockchain-overview.dot | 60 + img/dev/en-blockchain-overview.png | Bin 0 -> 7295 bytes img/dev/en-blockchain-overview.svg | 121 + img/dev/en-btcc-payment-request.png | Bin 0 -> 29521 bytes img/dev/en-cert-order.dot | 29 + img/dev/en-cert-order.png | Bin 0 -> 9204 bytes img/dev/en-cert-order.svg | 66 + img/dev/en-coinjoin.dot | 99 + img/dev/en-coinjoin.png | Bin 0 -> 12451 bytes img/dev/en-coinjoin.svg | 206 ++ img/dev/en-creating-p2ph-output.dot | 41 + img/dev/en-creating-p2ph-output.png | Bin 0 -> 4126 bytes img/dev/en-creating-p2ph-output.svg | 78 + img/dev/en-creating-p2sh-output.dot | 42 + img/dev/en-creating-p2sh-output.png | Bin 0 -> 4490 bytes img/dev/en-creating-p2sh-output.svg | 88 + ...n-hd-cross-generational-key-compromise.dot | 49 + ...n-hd-cross-generational-key-compromise.png | Bin 0 -> 5685 bytes ...n-hd-cross-generational-key-compromise.svg | 96 + img/dev/en-hd-overview.dot | 51 + img/dev/en-hd-overview.png | Bin 0 -> 6417 bytes img/dev/en-hd-overview.svg | 129 + .../en-hd-private-parent-to-private-child.dot | 67 + .../en-hd-private-parent-to-private-child.png | Bin 0 -> 10602 bytes .../en-hd-private-parent-to-private-child.svg | 159 + ...ic-child-from-public-or-private-parent.dot | 78 + ...ic-child-from-public-or-private-parent.png | Bin 0 -> 11067 bytes ...ic-child-from-public-or-private-parent.svg | 196 ++ .../en-hd-public-child-from-public-parent.dot | 39 + .../en-hd-public-child-from-public-parent.png | Bin 0 -> 7184 bytes .../en-hd-public-child-from-public-parent.svg | 85 + img/dev/en-hd-root-keys.dot | 42 + img/dev/en-hd-root-keys.png | Bin 0 -> 6874 bytes img/dev/en-hd-root-keys.svg | 111 + img/dev/en-hd-tree.dot | 66 + img/dev/en-hd-tree.png | Bin 0 -> 11029 bytes img/dev/en-hd-tree.svg | 142 + img/dev/en-micropayment-channel.dot | 54 + img/dev/en-micropayment-channel.png | Bin 0 -> 20623 bytes img/dev/en-micropayment-channel.svg | 128 + img/dev/en-p2ph-stack.dot | 145 + img/dev/en-p2ph-stack.png | Bin 0 -> 20119 bytes img/dev/en-p2ph-stack.svg | 306 ++ img/dev/en-payment-processing.dot | 29 + img/dev/en-payment-processing.png | Bin 0 -> 6129 bytes img/dev/en-payment-processing.svg | 96 + img/dev/en-payment-protocol.dot | 56 + img/dev/en-payment-protocol.png | Bin 0 -> 17220 bytes img/dev/en-payment-protocol.svg | 164 + img/dev/en-pooled-mining-overview.dot | 25 + img/dev/en-pooled-mining-overview.png | Bin 0 -> 5512 bytes img/dev/en-pooled-mining-overview.svg | 78 + img/dev/en-qr-code.png | Bin 0 -> 6583 bytes img/dev/en-qr-code.svg | 225 ++ img/dev/en-signing-output-to-spend.dot | 87 + img/dev/en-signing-output-to-spend.png | Bin 0 -> 8976 bytes img/dev/en-signing-output-to-spend.svg | 155 + img/dev/en-solo-mining-overview.dot | 25 + img/dev/en-solo-mining-overview.png | Bin 0 -> 5231 bytes img/dev/en-solo-mining-overview.svg | 77 + img/dev/en-transaction-propagation.dot | 86 + img/dev/en-transaction-propagation.png | Bin 0 -> 10622 bytes img/dev/en-transaction-propagation.svg | 195 + img/dev/en-tx-overview.dot | 84 + img/dev/en-tx-overview.png | Bin 0 -> 16665 bytes img/dev/en-tx-overview.svg | 175 + img/dev/en-unlocking-p2ph-output.dot | 47 + img/dev/en-unlocking-p2ph-output.png | Bin 0 -> 5531 bytes img/dev/en-unlocking-p2ph-output.svg | 80 + img/dev/en-unlocking-p2sh-output.dot | 47 + img/dev/en-unlocking-p2sh-output.png | Bin 0 -> 5012 bytes img/dev/en-unlocking-p2sh-output.svg | 80 + 90 files changed, 13524 insertions(+) create mode 100644 _autocrossref.yaml create mode 100644 _includes/guide_block_chain.md create mode 100644 _includes/guide_contracts.md create mode 100644 _includes/guide_intro.md create mode 100644 _includes/guide_mining.md create mode 100644 _includes/guide_payment_processing.md create mode 100644 _includes/guide_transactions.md create mode 100644 _includes/ref_core_rpcs-abcdefg.md create mode 100644 _includes/ref_core_rpcs-hijklmn.md create mode 100644 _includes/ref_core_rpcs-opqrst.md create mode 100644 _includes/ref_core_rpcs-uvwxyz.md create mode 100644 _plugins/autocrossref.rb create mode 100644 img/dev/en-block-height-vs-depth.dot create mode 100644 img/dev/en-block-height-vs-depth.png create mode 100644 img/dev/en-block-height-vs-depth.svg create mode 100644 img/dev/en-blockchain-fork.dot create mode 100644 img/dev/en-blockchain-fork.png create mode 100644 img/dev/en-blockchain-fork.svg create mode 100644 img/dev/en-blockchain-overview.dot create mode 100644 img/dev/en-blockchain-overview.png create mode 100644 img/dev/en-blockchain-overview.svg create mode 100644 img/dev/en-btcc-payment-request.png create mode 100644 img/dev/en-cert-order.dot create mode 100644 img/dev/en-cert-order.png create mode 100644 img/dev/en-cert-order.svg create mode 100644 img/dev/en-coinjoin.dot create mode 100644 img/dev/en-coinjoin.png create mode 100644 img/dev/en-coinjoin.svg create mode 100644 img/dev/en-creating-p2ph-output.dot create mode 100644 img/dev/en-creating-p2ph-output.png create mode 100644 img/dev/en-creating-p2ph-output.svg create mode 100644 img/dev/en-creating-p2sh-output.dot create mode 100644 img/dev/en-creating-p2sh-output.png create mode 100644 img/dev/en-creating-p2sh-output.svg create mode 100644 img/dev/en-hd-cross-generational-key-compromise.dot create mode 100644 img/dev/en-hd-cross-generational-key-compromise.png create mode 100644 img/dev/en-hd-cross-generational-key-compromise.svg create mode 100644 img/dev/en-hd-overview.dot create mode 100644 img/dev/en-hd-overview.png create mode 100644 img/dev/en-hd-overview.svg create mode 100644 img/dev/en-hd-private-parent-to-private-child.dot create mode 100644 img/dev/en-hd-private-parent-to-private-child.png create mode 100644 img/dev/en-hd-private-parent-to-private-child.svg create mode 100644 img/dev/en-hd-public-child-from-public-or-private-parent.dot create mode 100644 img/dev/en-hd-public-child-from-public-or-private-parent.png create mode 100644 img/dev/en-hd-public-child-from-public-or-private-parent.svg create mode 100644 img/dev/en-hd-public-child-from-public-parent.dot create mode 100644 img/dev/en-hd-public-child-from-public-parent.png create mode 100644 img/dev/en-hd-public-child-from-public-parent.svg create mode 100644 img/dev/en-hd-root-keys.dot create mode 100644 img/dev/en-hd-root-keys.png create mode 100644 img/dev/en-hd-root-keys.svg create mode 100644 img/dev/en-hd-tree.dot create mode 100644 img/dev/en-hd-tree.png create mode 100644 img/dev/en-hd-tree.svg create mode 100644 img/dev/en-micropayment-channel.dot create mode 100644 img/dev/en-micropayment-channel.png create mode 100644 img/dev/en-micropayment-channel.svg create mode 100644 img/dev/en-p2ph-stack.dot create mode 100644 img/dev/en-p2ph-stack.png create mode 100644 img/dev/en-p2ph-stack.svg create mode 100644 img/dev/en-payment-processing.dot create mode 100644 img/dev/en-payment-processing.png create mode 100644 img/dev/en-payment-processing.svg create mode 100644 img/dev/en-payment-protocol.dot create mode 100644 img/dev/en-payment-protocol.png create mode 100644 img/dev/en-payment-protocol.svg create mode 100644 img/dev/en-pooled-mining-overview.dot create mode 100644 img/dev/en-pooled-mining-overview.png create mode 100644 img/dev/en-pooled-mining-overview.svg create mode 100644 img/dev/en-qr-code.png create mode 100644 img/dev/en-qr-code.svg create mode 100644 img/dev/en-signing-output-to-spend.dot create mode 100644 img/dev/en-signing-output-to-spend.png create mode 100644 img/dev/en-signing-output-to-spend.svg create mode 100644 img/dev/en-solo-mining-overview.dot create mode 100644 img/dev/en-solo-mining-overview.png create mode 100644 img/dev/en-solo-mining-overview.svg create mode 100644 img/dev/en-transaction-propagation.dot create mode 100644 img/dev/en-transaction-propagation.png create mode 100644 img/dev/en-transaction-propagation.svg create mode 100644 img/dev/en-tx-overview.dot create mode 100644 img/dev/en-tx-overview.png create mode 100644 img/dev/en-tx-overview.svg create mode 100644 img/dev/en-unlocking-p2ph-output.dot create mode 100644 img/dev/en-unlocking-p2ph-output.png create mode 100644 img/dev/en-unlocking-p2ph-output.svg create mode 100644 img/dev/en-unlocking-p2sh-output.dot create mode 100644 img/dev/en-unlocking-p2sh-output.png create mode 100644 img/dev/en-unlocking-p2sh-output.svg diff --git a/_autocrossref.yaml b/_autocrossref.yaml new file mode 100644 index 00000000..893d10e1 --- /dev/null +++ b/_autocrossref.yaml @@ -0,0 +1,296 @@ +--- +## List of words to match with references in _includes/references.md +## in developer documentation, used by autocrossref.rb plugin. +## "pattern to match in file" => "reference to give it" + +51 percent attack: +address: +addresses: address +'`amount`': pp amount +base-58: base58check +base58: base58check +base58check: +## bitcoin -- Recommend against bitcoin (singular) because of confusion between protocol, software, denomination +bitcoins: +bitcoin QR code: URI QR code +bitcoin QR codes: URI QR code +'`bitcoin:` URI': bitcoin uri +'`bitcoin:` URIs': bitcoin uri +block: +block chain: +block-chain: block chain +block header: +block height: +block reward: +block time: +block version: +blocks: block +broadcast: +broadcasts: broadcast +broadcasting: +certificate chain: +chain code: +change address: +change addresses: change address +change output: +change outputs: change output +child extended key: +child extended keys: child extended key +child key: +child keys: child key +child public key: +child public keys: child public key +coinbase: coinbase transaction +coinbase transaction: +coinbase transactions: coinbase transaction +coinbase field: +confirm: +confirmed: +confirmation: +confirmations: +confirmed transactions: +denomination: +denominations: denomination +DER format: der +DER-formatted: der +difficulty: +double spend: +double-spend: double spend +double spending: double spend +double-spent: double spend +ECDSA: +escrow contract: +'`expires`': pp expires +extended key: +extended keys: extended key +extended private key: +extended public key: +fiat: +fork: accidental fork +genesis block: +hardened extended private key: +HD protocol: +header nonce: +high-priority transaction: high-priority transactions +high-priority transactions: +inputs: input +input: +intermediate certificate: +intermediate certificates: intermediate certificate +key index: +key pair: +'`label`': label +leaf certificate: +locktime: +long-term fork: +mainnet: +master chain code: +master private key: +'`memo`': pp memo +'`message`': message +'`merchant_data`': pp merchant data +merkle root: +merkle tree: +merge: +Merge avoidance: +micropayment channel: +micropayment channels: micropayment channel +mine: +miner: +miners: miner +minimum fee: +mining: mine +millibit: millibits +millibits: +multisig: +network: +null data: +'`op_checkmultisig`': op_checkmultisig +'`op_checksig`': op_checksig +op code: +op codes: op code +'`op_dup`': op_dup +'`op_equal`': op_equal +'`op_equalverify`': op_equalverify +'`op_hash160`': op_hash160 +'`op_return`': op_return +'`op_verify`': op_verify +orphan: +orphan: orphaned +outputs: output +output: +output index: +p2ph: +p2sh: +p2sh multisig: +parent chain code: +parent private key: +parent public key: +Payment message: pp payment +payment protocol: +"payment protocol's": payment protocol +PaymentACK: +PaymentDetails: +PaymentRequest: +PaymentRequests: paymentrequest +'`payment_url`': pp payment url +peer: +peers: peer +peer-to-peer network: network +pki: +'`pki_type`': pp pki type +'`point()`': point function +private key: +private keys: private key +proof of work: +proof-of-work: proof of work +protocol buffer: protobuf +protocol buffers: protobuf +pubkey hash: +pubkey hashes: pubkey hash +public key: +public keys: public key +public key infrastructure: pki +'`r`': r +raw format: +rawtransaction format: raw format +receipt: +recurrent rebilling: +redeemScript: +refund: +refunds: refund +'`refund_to`': pp refund to +root certificate: +root seed: +RPCs: rpc +RPC: +satoshi: +satoshis: satoshi +script: +'`script`': pp script +script hash: +scripts: script +scriptSig: +scriptSigs: scriptSig +secp256k1: +sequence number: +sequence numbers: sequence number +SIGHASH: signature hash +'`SIGHASH_ANYONECANPAY`': shacp +'`SIGHASH_ALL`': sighash_all +'`SIGHASH_ALL|SIGHASH_ANYONECANPAY`': sha_shacp +'`SIGHASH_NONE`': sighash_none +'`SIGHASH_NONE|SIGHASH_ANYONECANPAY`': shn_shacp +'`SIGHASH_SINGLE|SIGHASH_ANYONECANPAY`': shs_shacp +signature: +signature hash: +signatures: signature +SPV: +stack: +standard script: +standard scripts: standard script +standard transaction: standard script +standard transactions: standard script +target: +testnet: +#transaction -- Recommend we don't autocrossref this; it occurs too often +transaction fee: +transaction fees: transaction fee +transaction malleability: +transaction object format: +transaction version number: +'`transactions`': pp transactions +txid: +txids: txid +unconfirmed: +unconfirmed transactions: +unique address: unique addresses +unique addresses: +utxo: +utxos: utxo +verified payments: +version 2 blocks: v2 block +wallet: +wallets: wallet +wallet import format: +x.509: x509 +X509Certificates: + +## BIPS in numerical order; don't use padding zeros (e.g. BIP70 not BIP0070) +BIP21: +BIP32: +BIP39: +BIP70: + +## RPCs +'`addmultisigaddress`': rpc addmultisigaddress +'`addnode`': rpc addnode +'`backupwallet`': rpc backupwallet +'`createmultisig`': rpc createmultisig +'`createrawtransaction`': rpc createrawtransaction +'`decoderawtransaction`': rpc decoderawtransaction +'`decodescript`': rpc decodescript +'`dumpprivkey`': rpc dumpprivkey +'`dumpwallet`': rpc dumpwallet +'`getaccount`': rpc getaccount +'`getaccountaddress`': rpc getaccountaddress +'`getaddednodeinfo`': rpc getaddednodeinfo +'`getaddressesbyaccount`': rpc getaddressesbyaccount +'`getbalance`': rpc getbalance +'`getbestblockhash`': rpc getbestblockhash +'`getblock`': rpc getblock +'`getblockcount`': rpc getblockcount +'`getblockhash`': rpc getblockhash +'`getblocktemplate`': rpc getblocktemplate +'`getconnectioncount`': rpc getconnectioncount +'`getdifficulty`': rpc getdifficulty +'`getgenerate`': rpc getgenerate +'`gethashespersec`': rpc gethashespersec +'`getinfo`': rpc getinfo +'`getmininginfo`': rpc getmininginfo +'`getnettotals`': rpc getnettotals +'`getnetworkhashps`': rpc getnetworkhashps +'`getnewaddress`': rpc getnewaddress +'`getpeerinfo`': rpc getpeerinfo +'`getrawchangeaddress`': rpc getrawchangeaddress +'`getrawmempool`': rpc getrawmempool +'`getrawtransaction`': rpc getrawtransaction +'`getreceivedbyaccount`': rpc getreceivedbyaccount +'`getreceivedbyaddress`': rpc getreceivedbyaddress +'`gettransaction`': rpc gettransaction +'`gettxout`': rpc gettxout +'`gettxoutsetinfo`': rpc gettxoutsetinfo +'`getunconfirmedbalance`': rpc getunconfirmedbalance +'`getwork`': rpc getwork +'`help`': rpc help +'`importprivkey`': rpc importprivkey +'`importwallet`': rpc importwallet +'`keypoolrefill`': rpc keypoolrefill +'`listaccounts`': rpc listaccounts +'`listaddressgroupings`': rpc listaddressgroupings +'`listlockunspent`': rpc listlockunspent +'`listreceivedbyaccount`': rpc listreceivedbyaccount +'`listreceivedbyaddress`': rpc listreceivedbyaddress +'`listsinceblock`': rpc listsinceblock +'`listtransactions`': rpc listtransactions +'`listunspent`': rpc listunspent +'`lockunspent`': rpc lockunspent +'`move`': rpc move +'`ping`': rpc ping +'`sendfrom`': rpc sendfrom +'`sendmany`': rpc sendmany +'`sendrawtransaction`': rpc sendrawtransaction +'`sendtoaddress`': rpc sendtoaddress +'`setaccount`': rpc setaccount +'`setgenerate`': rpc setgenerate +'`settxfee`': rpc settxfee +'`signmessage`': rpc signmessage +'`signrawtransaction`': rpc signrawtransaction +'`stop`': rpc stop +'`submitblock`': rpc submitblock +'`validateaddress`': rpc validateaddress +'`verifychain`': rpc verifychain +'`verifymessage`': rpc verifymessage +'`walletlock`': rpc walletlock +'`walletpassphrase`': rpc walletpassphrase +'`walletpassphrasechange`': rpc walletpassphrasechange diff --git a/_includes/guide_block_chain.md b/_includes/guide_block_chain.md new file mode 100644 index 00000000..aa0bab28 --- /dev/null +++ b/_includes/guide_block_chain.md @@ -0,0 +1,242 @@ +## Block Chain + +{% autocrossref %} + +The block chain provides Bitcoin's public ledger, a timestamped record +of all confirmed transactions. This system is used to protect against double spending +and modification of previous transaction records, using proof of +work verified by the peer-to-peer network to maintain a global consensus. + +{% endautocrossref %} + +### Block Chain Overview + +{% autocrossref %} + +![Block Chain Overview](/img/dev/en-blockchain-overview.svg) + +The illustration above shows a simplified version of a block chain. +A [block][]{:#term-block}{:.term} of one or more new transactions +is collected into the transaction data part of a block. +Copies of each transaction are hashed, and the hashes are then paired, +hashed, paired again, and hashed again until a single hash remains, the +[Merkle root][]{:#term-merkle-root}{:.term} of a Merkle tree. + +The Merkle root is stored in the block header. Each block also +stores the hash of the previous block's header, chaining the blocks +together. This ensures a transaction cannot be modified without +modifying the block that records it and all following blocks. + +Transactions are also chained together. Bitcoin wallet software gives +the impression that satoshis are sent from and to addresses, but +bitcoins really move from transaction to transaction. Each standard +transaction spends the satoshis previously spent in one or more earlier +transactions, so the input of one transaction is the output of a +previous transaction. + +![Transaction Propagation](/img/dev/en-transaction-propagation.svg) + +A single transaction can spend bitcoins to multiple outputs, as would be +the case when sending satoshis to multiple addresses, but each output of +a particular transaction can only be used as an input once in the +block chain. Any subsequent reference is a forbidden double +spend---an attempt to spend the same satoshis twice. + +Outputs are not the same as Bitcoin addresses. You can use the same +address in multiple transactions, but you can only use each output once. +Outputs are tied to [transaction identifiers (TXIDs)][txid]{:#term-txid}{:.term}, which are the hashes +of signed transactions. + +Because each output of a particular transaction can only be spent once, +all transactions included in the block chain can be categorized as either +[Unspent Transaction Outputs (UTXOs)][utxo]{:#term-utxo}{:.term} or spent transaction outputs. For a +payment to be valid, it must only use UTXOs as inputs. + +Satoshis cannot be left in a UTXO after a transaction or they will be +irretrievably lost, so any difference between the number of satoshis in a +transaction's inputs and outputs is given as a [transaction fee][]{:#term-transaction-fee}{:.term} to +the Bitcoin [miner][]{:#term-miner}{:.term} who creates the block containing that transaction. +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 + +{% autocrossref %} + +The block chain is collaboratively maintained on a peer-to-peer network, so +Bitcoin requires each block prove a significant amount of work was invested in +its creation to ensure that untrustworthy peers who want to modify past blocks have +to work harder than trustworthy peers who only want to add new blocks to the +block chain. + +Chaining blocks together makes it impossible to modify transactions included +in any block without modifying all following blocks. As a +result, the cost to modify a particular block increases with every new block +added to the block chain, magnifying the effect of the proof of work. + +The [proof of work][]{:#term-proof-of-work}{:.term} used in Bitcoin +takes advantage of the apparently random nature of cryptographic hashes. +A good cryptographic hash algorithm converts arbitrary data into a +seemingly-random number. If the data is modified in any way and +the hash re-run, a new seemingly-random number is produced, so there is +no way to modify the data to make the hash number predictable. + +To prove you did some extra work to create a block, you must create a +hash of the block header which does not exceed a certain value. For +example, if the maximum possible hash value is 2256 − 1, you can prove that you +tried up to two combinations by producing a hash value less than 2256 − 1. + +In the example given above, you will almost certainly produce a +successful hash on your first try. You can even estimate the probability +that a given hash attempt will generate a number below the [target][]{:#term-target}{:.term} +threshold. Bitcoin itself does not track probabilities but instead +simply assumes that the lower it makes the target threshold, the more +hash attempts, on average, will need to be tried. + +New blocks will only be added to the block chain if their hash is at +least as challenging as a [difficulty][]{:#term-difficulty}{:.term} value expected by the peer-to-peer +network. Every 2,016 blocks, the network uses timestamps stored in each +block header to calculate the number of seconds elapsed between generation +of the first and last of those last 2,016 blocks. The ideal value is +1,209,600 seconds (two weeks). + +* If it took fewer than two weeks to generate the 2,016 blocks, + the expected difficulty value is increased proportionally (by as much + as 300%) so that the next 2,016 blocks should take exactly two weeks + to generate if hashes are checked at the same rate. + +* If it took more than two weeks to generate the blocks, the expected + difficulty value is decreased proportionally (by as much as 75%) for + the same reason. + +(Note: an off-by-one error in the Bitcoin Core implementation causes the +difficulty to be updated every 2,01*6* blocks using timestamps from only +2,01*5* blocks, creating a slight skew.) + +Because each block header must hash to a value below the target +threshold, and because each block is linked to the block that +preceded it, it requires (on average) as much hashing power to +propagate a modified block as the entire Bitcoin network expended +between the time the original block was created and the present time. +Only if you acquired a majority of the network's hashing power +could you reliably execute such a [51 percent attack][]{:#term-51-attack}{:.term} against +transaction history. + +The block header provides several easy-to-modify fields, such as a +dedicated nonce field, so obtaining new hashes doesn't require waiting +for new transactions. Also, only the 80-byte block header is hashed for +proof-of-work, so adding more bytes of transaction data to +a block does not slow down hashing with extra I/O. + +{% endautocrossref %} + +### Block Height And Forking + +{% 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. +(Assuming the block is otherwise valid.) These blocks are commonly addressed +by their [block height][]{:#term-block-height}{:.term}---the number of blocks between them and the first Bitcoin +block (block 0, most commonly known as the [genesis block]{:#term-genesis-block}{:.term}). For example, +block 2016 is where difficulty could have been first adjusted. + +![Common And Uncommon Block Chain Forks](/img/dev/en-blockchain-fork.svg) + +Multiple blocks can all have the same block height, as is common when +two or more miners each produce a block at roughly the same time. This +creates an apparent [fork][accidental fork]{:#term-accidental-fork}{:.term} in the block chain, as shown in the +illustration above. + +When miners produce simultaneous blocks at the end of the block chain, each +peer individually chooses which block to trust. (In the absence of +other considerations, discussed below, peers usually trust the first +block they see.) + +Eventually a miner produces another block which attaches to only one of +the competing simultaneously-mined blocks. This makes that side of +the fork longer than the other side. Assuming a fork only contains valid +blocks, normal peers always follow the longest fork (the most difficult chain +to recreate) and throw away ([orphan][]{:#term-orphan}{:.term}) blocks belonging to shorter forks. + +[Long-term forks][long-term fork]{:#term-long-term-fork}{:.term} are possible if different miners work at cross-purposes, +such as some miners diligently working to extend the block chain at the +same time other miners are attempting a 51 percent attack to revise +transaction history. + +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 SHA256(SHA256()) hash of their header. + +{% endautocrossref %} + +### Transaction Data + +{% autocrossref %} + +Every block must include one or more transactions. Exactly one of these +transactions must be a coinbase transaction which should collect and +spend the block reward and any transaction fees paid by transactions included in this block. + +The UTXO of a coinbase transaction has the special condition that +it cannot be spent (used as an input) for at least 100 blocks. This temporarily +prevents a miner from spending the transaction fees and block reward from a +block that may later be orphaned (destroyed) after a block chain fork. + +Blocks are not required to include any non-coinbase transactions, but +miners almost always do include additional transactions in order to +collect their transaction fees. + +All transactions, including the coinbase transaction, are encoded into +blocks in binary rawtransaction format prefixed by a block transaction +sequence number. + +The rawtransaction format is hashed to create the transaction +identifier (txid). From these txids, the [Merkle tree][]{:#term-merkle-tree}{:.term} is constructed by pairing each +txid with one other txid and then hashing them together. If there are +an odd number of txids, the txid without a partner is hashed with a +copy of itself. + +The resulting hashes themselves are each paired with one other hash and +hashed together. Any hash without a partner is hashed with itself. The +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 + / \ + ABCD EEEE + / \ / + AB CD EE .......E is paired with itself +/ \ / \ / +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 +Merkle root from a block header and a list of the intermediate hashes +from a full peer. The full peer does not need to be trusted: it is +expensive to fake block headers and the intermediate hashes cannot be faked or +the verification will fail. + +For example, to verify transaction D was added to the +block, an SPV client only needs a copy of the C, AB, and EEEE hashes in addition to the +Merkle root; the client doesn't need to know anything about any of the +other transactions. If the five transactions in this block were all at +the maximum size, downloading the entire block would require over +500,000 bytes---but downloading three hashes plus the block header +requires only 140 bytes. + +{% endautocrossref %} diff --git a/_includes/guide_contracts.md b/_includes/guide_contracts.md new file mode 100644 index 00000000..7c72d9e0 --- /dev/null +++ b/_includes/guide_contracts.md @@ -0,0 +1,288 @@ +## Contracts + +{% autocrossref %} + +By making the system hard to understand, the complexity of transactions +has so far worked against you. That changes with contracts. Contracts are +transactions which use the decentralized Bitcoin system to enforce financial +agreements. + +Bitcoin contracts can often be crafted to minimize dependency on outside +agents, such as the court system, which significantly decreases the risk +of dealing with unknown entities in financial transactions. For example, +Alice and Bob might only know each other casually over the Internet; +they would never open a checking account together---one of them could +pass bad checks, leaving the other on the hook. But with Bitcoin +contracts, they can nearly eliminate the risk from their relationship +and start a business even though they hardly know each other. + +The following subsections will describe a variety of Bitcoin contracts +already in use. Because contracts deal with real people, not just +transactions, they are framed below in story format. + +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 + +{% 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 +help ensure Charlie gets his merchandise and Bob gets his payment. + +A simple contract could say that Charlie will spend satoshis to an +output which can only be spent if Charlie and Bob both sign the input +spending it. That means Bob won't get paid unless Charlie gets his +merchandise, but Charlie can't get the merchandise and keep his payment. + +This simple contract isn't much help if there's a dispute, so Bob and +Charlie enlist the help of Alice-the-arbitrator to create an [escrow +contract][]{:#term-escrow-contract}{:.term}. Charlie spends his satoshis +to an output which can only be spent if two of the three people sign the +input. Now Charlie can pay Bob if everything is ok, Bob can refund +Charlie's money if there's a problem, or Alice can arbitrate and decide +who should get the satoshis if there's a dispute. + +To create a multiple-signature ([multisig][]{:#term-multisig}{:.term}) +output, they each give the others a public key. Then Bob creates the +following [P2SH multisig][]{:#term-p2sh-multisig}{:.term} redeemScript: + +{% endautocrossref %} + +~~~ +OP_2 [A's pubkey] [B's pubkey] [C's pubkey] OP_3 OP_CHECKMULTISIG +~~~ + +{% autocrossref %} + +(Op codes 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 +stack. `OP_2` +specifies that 2 signatures are required to sign; `OP_3` specifies that +3 public keys (unhashed) are being provided. This is a 2-of-3 multisig +script, more generically called a m-of-n script (where *m* is the +*minimum* matching signatures required and *n* in the *number* of public +keys provided). + +Bob gives the redeemScript to Charlie, who checks to make sure his +public key and Alice's public key are included. Then he hashes the +redeemScript, puts it in a P2SH output, and pays the satoshis to it. Bob +sees the payment get added to the block chain and ships the merchandise. + +Unfortunately, the merchandise gets slightly damaged in transit. Charlie +wants a full refund, but Bob thinks a 10% refund is sufficient. They +turn to Alice to resolve the issue. Alice asks for photo evidence from +Charlie along with a copy of the unhashed redeemScript Bob created and +Charlie checked. + +After looking at the evidence, Alice thinks a 40% refund is sufficient, +so she creates and signs a transaction with two outputs, one that spends 60% +of the satoshis to Bob's public key and one that spends the remaining +40% to Charlie's public key. + +In the input section of the script, Alice puts her signature, a 0x00 +placeholder byte, and a copy of the unhashed serialized redeemScript +that Bob created. She gives a copy of the incomplete transaction to +both Bob and Charlie. Either one of them can complete it by replacing +the placeholder byte with his signature, creating the following input +script: + +{% endautocrossref %} + +~~~ +OP_0 [A's signature] [B's or C's signature] [serialized redeemScript] +~~~ + +{% autocrossref %} + +(Op codes to push the signatures and redeemScript 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.) + +When the transaction is broadcast to the network, each peer checks the +input script against the P2SH output Charlie previously paid, +ensuring that the redeemScript matches the redeemScript hash previously +provided. Then the redeemScript is evaluated, with the two signatures +being used as input data. Assuming the redeemScript +validates, the two transaction outputs show up in Bob's and Charlie's +wallets as spendable balances. + +However, if Alice created and signed a transaction neither of them would +agree to, such as spending all the satoshis to herself, Bob and Charlie +can find a new arbitrator and sign a transaction spending the satoshis +to another 2-of-3 multisig redeemScript hash, this one including a public +key from that second arbitrator. This means that Bob and Charlie never +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 + +{% autocrossref %} + + + +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][]{:#term-micropayment-channel}{:.term}. + +Bob asks Alice for her public key and then creates two transactions. +The first transaction pays 100 millibits to a P2SH output whose +2-of-2 multisig redeemScript requires signatures from both Alice and Bob. +This is the bond transaction. +Broadcasting this transaction would let Alice hold the millibits +hostage, so Bob keeps this transaction private for now and creates a +second transaction. + +The second transaction spends all of the first transaction's millibits +(minus a transaction fee) back to Bob after a 24 hour delay enforced +by locktime. This is the refund transaction. Bob can't sign the refund transaction by himself, so he gives +it to Alice to sign, as shown in the +illustration below. + +![Micropayment Channel Example](/img/dev/en-micropayment-channel.svg) + +Alice checks that the refund transaction's locktime is 24 hours in the +future, signs it, and gives a copy of it back to Bob. She then asks Bob +for the bond transaction and checks that the refund transaction spends +the output of the bond transaction. She can now broadcast the bond +transaction to the network to ensure Bob has to wait for the time lock +to expire before further spending his millibits. Bob hasn't actually +spent anything so far, except possibly a small transaction fee, and +he'll be able to broadcast the refund transaction in 24 hours for a +full refund. + +Now, when Alice does some work worth 1 millibit, she asks Bob to create +and sign a new version of the refund transaction. Version two of the +transaction spends 1 millibit 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 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 transaction before +its time lock expires, Bob can broadcast the first version and receive a +full refund. 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 micropayment channels. +If someone uses transaction malleability to break the link between the +two transactions, Alice could hold Bob's 100 millibits 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. + +**Resource:** The [bitcoinj](http://bitcoinj.org) Java library +provides a complete set of micropayment functions, an example +implementation, and [a +tutorial](https://bitcoinj.github.io/working-with-micropayments) +all under an Apache license. + +{% endautocrossref %} + +### CoinJoin + +{% 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 +can each easily track those satoshis to learn what Bitcoin +addresses she pays, how much she pays them, and possibly how many +satoshis she has left. + +Because Alice isn't a criminal, she doesn't want to use some shady +Bitcoin laundering service; she just wants plausible deniability about +where she has spent her satoshis and how many she has left, so she +starts up the Tor anonymity service on her computer and logs into an +IRC chatroom as "AnonGirl." + +Also in the chatroom are "Nemo" and "Neminem." They collectively +agree to transfer satoshis between each other so no one besides them +can reliably determine who controls which satoshis. But they're faced +with a dilemma: who transfers their satoshis to one of the other two +pseudonymous persons first? The CoinJoin-style contract, shown in the +illustration below, makes this decision easy: they create a single +transaction which does all of the spending simultaneously, ensuring none +of them can steal the others' satoshis. + +![Example CoinJoin Transaction](/img/dev/en-coinjoin.svg) + +Each contributor looks through their collection of Unspent Transaction +Outputs (UTXOs) for 100 millibits they can spend. They then each generate +a brand new public key and give UTXO details and pubkey hashes to the +facilitator. In this case, the facilitator is AnonGirl; she creates +a transaction spending each of the UTXOs to three equally-sized outputs. +One output goes to each of the contributors' pubkey hashes. + +AnonGirl then signs her inputs using `SIGHASH_ALL` to ensure nobody can +change the input or output details. She gives the partially-signed +transaction to Nemo who signs his inputs the same way and passes it +to Neminem, who also signs it the same way. Neminem then broadcasts +the transaction to the peer-to-peer network, mixing all of the millibits in +a single transaction. + +As you can see in the illustration, there's no way for anyone besides +AnonGirl, Nemo, and Neminem to confidently determine who received +which output, so they can each spend their output with plausible +deniability. + +Now when Bob or Charlie try to track Alice's transactions through the +block chain, they'll also see transactions made by Nemo and +Neminem. If Alice does a few more CoinJoins, Bob and Charlie might +have to guess which transactions made by dozens or hundreds of people +were actually made by Alice. + +The complete history of Alice's satoshis is still in the block chain, +so a determined investigator could talk to the people AnonGirl +CoinJoined with to find out the ultimate origin of her satoshis and +possibly reveal AnonGirl as Alice. But against anyone casually browsing +block chain history, Alice gains plausible deniability. + +The CoinJoin technique described above costs the participants a small +amount of satoshis to pay the transaction fee. An alternative +technique, purchaser CoinJoin, can actually save them satoshis and +improve their privacy at the same time. + +AnonGirl waits in the IRC chatroom until she wants to make a purchase. +She announces her intention to spend satoshis and waits until someone +else wants to make a purchase, likely from a different merchant. Then +they combine their inputs the same way as before but set the outputs +to the separate merchant addresses so nobody will be able to figure +out solely from block chain history which one of them bought what from +the merchants. + +Since they would've had to pay a transaction fee to make their purchases +anyway, AnonGirl and her co-spenders don't pay anything extra---but +because they reduced overhead by combining multiple transactions, saving +bytes, they may be able to pay a smaller aggregate transaction fee, +saving each one of them a tiny amount of satoshis. + +**Resource:** An alpha-quality (as of this writing) implementation of decentralized +CoinJoin is [CoinMux](http://coinmux.com/), available under the Apache +license. A centralized version of purchaser CoinJoin is available at the +[SharedCoin](https://sharedcoin.com/) website (part of Blockchain.info), +whose [implementation](https://github.com/blockchain/Sharedcoin) is +available under the 4-clause BSD license. + +{% endautocrossref %} diff --git a/_includes/guide_intro.md b/_includes/guide_intro.md new file mode 100644 index 00000000..51b9e8ae --- /dev/null +++ b/_includes/guide_intro.md @@ -0,0 +1,62 @@ +{% autocrossref %} + +The Developer Guide aims to provide the information you need to start +building Bitcoin-based applications. To make the best use of this guide, +you may want to install the current version of Bitcoin Core, either from +[source][core git] or from a [pre-compiled executable][core executable]. + +Once installed, you'll have access to three programs: `bitcoind`, +`bitcoin-qt`, and `bitcoin-cli`. When run with no arguments, all three +programs default to Bitcoin's main network ([mainnet][mainnet]{:#term-mainnet}{:.term}) which will require +you purchase satoshis in order to generate transactions. + +However, for development, it's safer and cheaper to use Bitcoin's test +network ([testnet][testnet]{:#term-testnet}{:.term}) where the satoshis spent have no real-world value. +Testnet also relaxes some restrictions (such as standard transaction +checks) so you can test functions which might currently be disabled by +default on mainnet. + +To use testnet, use the argument `-testnet` with each program or add +`testnet=1` to your `bitcoin.conf` file. To get +free satoshis for testing, use [Piotr Piasecki's testnet faucet][]. +Testnet is a public resource provided for free by members of the +community, so please don't abuse it. + +You can speed up development further using the [regression test mode][] +which creates a new testnet local to your computer. This regtest mode +will let you generate blocks almost instantly with a RPC command so you +can generate your own satoshis and add transactions to the block chain +immediately. + +* `bitcoin-qt` provides a combination full Bitcoin peer and wallet + frontend. From the Help menu, you can access a console where you can + enter the RPC commands used throughout this document. + +* `bitcoind` is more useful for programming: it provides a full peer + which you can interact with through RPCs to port 8332 (or 18332 + for testnet). + +* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the + command line. For example, `bitcoin-cli help` + +All three programs get settings from `bitcoin.conf` in the `Bitcoin` +application directiory: + +* Windows: `%APPDATA%\Bitcoin\` + +* OSX: `$HOME/Library/Application Support/Bitcoin/` + +* Linux: `$HOME/.bitcoin/` + +Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum +tech support] and [IRC channels][]. Errors or suggestions related to +documentation on Bitcoin.org can be [submitted as an issue][docs issue] +or posted to the [bitcoin-documentation mailing list][]. + +In the following guide, +some strings have been shortened or wrapped: "[...]" indicates extra data was removed, and lines ending in a single backslash "\\" are continued below. +If you hover your mouse over a paragraph, cross-reference links will be +shown in blue. If you hover over a cross-reference link, a brief +definition of the term will be displayed in a tooltip. + +{% endautocrossref %} diff --git a/_includes/guide_mining.md b/_includes/guide_mining.md new file mode 100644 index 00000000..bea9b4bc --- /dev/null +++ b/_includes/guide_mining.md @@ -0,0 +1,202 @@ +## Mining + +{% autocrossref %} + +Mining adds new blocks to the block chain, making transaction history +hard to modify. Mining today takes on two forms: + +* Solo mining, where the miner attempts to generate new blocks on his + own, with the proceeds from the block reward and transaction fees + going entirely to himself, allowing him to receive large payments with + a higher variance (longer time between payments) + +* Pooled mining, where the miner pools resources with other miners to + find blocks more often, with the proceeds being shared among the pool + miners in rough correlation to the amount of hashing power + they each contributed, allowing the miner to receive small + payments with a lower variance (shorter time between payments). + +{% endautocrossref %} + +### Solo Mining + +{% autocrossref %} + +As illustrated below, solo miners typically use `bitcoind` to get new +transactions from the network. Their mining software periodically polls +`bitcoind` for new transactions using the `getblocktemplate` RPC, which +provides the list of new transactions plus the public key to which the +coinbase transaction should be sent. + +![Solo Bitcoin Mining](/img/dev/en-solo-mining-overview.svg) + +The mining software constructs a block using the template (described below) and creates a +block header. It then sends the 80-byte block header to its mining +hardware (an ASIC) along with a target threshold (difficulty setting). +The mining hardware iterates through every possible value for the block +header nonce and generates the corresponding hash. + +If none of the hashes are below the threshold, the mining hardware gets +an updated block header with a new Merkle root from the mining software; +this new block header is created by adding extra nonce data to the +coinbase field of the coinbase transaction. + +On the other hand, if a hash is found below the target threshold, the +mining hardware returns the block header with the successful nonce to +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 + +{% autocrossref %} + +Pool miners follow a similar workflow, illustrated below, which allows +mining pool operators to pay miners based on their share of the work +done. The mining pool gets new transactions from the network using +`bitcoind`. Using one of the methods discussed later, each miner's mining +software connects to the pool and requests the information it needs to +construct block headers. + +![Pooled Bitcoin Mining](/img/dev/en-pooled-mining-overview.svg) + +In pooled mining, the mining pool sets the target threshold a few orders +of magnitude higher (less difficult) than the network +difficulty. This causes the mining hardware to return many block headers +which don't hash to a value eligible for inclusion on the block chain +but which do hash below the pool's target, proving (on average) that the +miner checked a percentage of the possible hash values. + +The miner then sends to the pool a copy of the information the pool +needs to validate that the header will hash below the target and that +the the block of transactions referred to by the header Merkle root field +is valid for the pool's purposes. (This usually means that the coinbase +transaction must pay the pool.) + +The information the miner sends to the pool is called a share because it +proves the miner did a share of the work. By chance, some shares the +pool receives will also be below the network target---the mining pool +sends these to the network to be added to the block chain. + +The block reward and transaction fees that come from mining that block +are paid to the mining pool. The mining pool pays out a portion of +these proceeds to individual miners based on how many shares they generated. For +example, if the mining pool's target threshold is 100 times lower than +the network target threshold, 100 shares will need to be generated on +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 + +{% autocrossref %} + +In both solo and pool mining, the mining software needs to get the +information necessary to construct block headers. This subsection +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 + +{% autocrossref %} + +The simplest and earliest method was the now-deprecated Bitcoin Core +`getwork` RPC, which constructs a header for the miner directly. Since a +header only contains a single 4-byte nonce good for about 4 gigahashes, +many modern miners need to make dozens or hundreds of `getwork` requests +a second. Solo miners may still use `getwork`, but most pools today +discourage or disallow its use. + +{% endautocrossref %} + +#### getblocktemplate RPC + +{% autocrossref %} + +An improved method is the Bitcoin Core `getblocktemplate` RPC. This +provides the mining software with much more information: + +1. The information necessary to construct a coinbase transaction + paying the pool or the solo miner's `bitcoind` wallet. + +2. A complete dump of the transactions `bitcoind` or the mining pool + suggests including in the block, allowing the mining software to + inspect the transactions, optionally add additional transactions, and + optionally remove non-required transactions. + +3. Other information necessary to construct a block header for the next + block: the block version, previous block hash, and bits (target). + +4. The mining pool's current target threshold for accepting shares. (For + solo miners, this is the network target.) + +Using the transactions received, the mining software adds a nonce to the +coinbase extra nonce field and then converts all the transactions into a +Merkle tree to derive a Merkle root it can use in a block header. +Whenever the extra nonce field needs to be changed, the mining software +rebuilds the necessary parts of the Merkle tree and updates the time and +Merkle root fields in the block header. + +Like all `bitcoind` RPCs, `getblocktemplate` is sent over HTTP. To +ensure they get the most recent work, most miners use [HTTP longpoll][] to +leave a `getblocktemplate` request open at all times. This allows the +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 + +{% autocrossref %} + +A widely used alternative to `getblocktemplate` is the [Stratum mining +protocol][]. Stratum focuses on giving miners the minimal information they +need to construct block headers on their own: + +1. The information necessary to construct a coinbase transaction + paying the pool. + +2. The parts of the Merkle tree which need to be re-hashed to + create a new Merkle root when the coinbase transaction is + updated with a new extra nonce. The other parts of the Merkle + tree, if any, are not sent, effectively limiting the amount of data which needs + to be sent to (at most) about a kilobyte at current transaction + volume. + +3. All of the other non-Merkle root information necessary to construct a + block header for the next block. + +4. The mining pool's current target threshold for accepting shares. + +Using the coinbase transaction received, the mining software adds a +nonce to the coinbase extra nonce field, hashes the coinbase +transaction, and adds the hash to the received parts of the Merkle tree. +The tree is hashed as necessary to create a Merkle root, which is added +to the block header information received. Whenever the extra nonce field +needs to be changed, the mining software updates and re-hashes the +coinbase transaction, rebuilds the Merkle root, and updates the header +Merkle root field. + +Unlike `getblocktemplate`, miners using Stratum cannot inspect or add +transactions to the block they're currently mining. Also unlike +`getblocktemplate`, the Stratum protocol uses a two-way TCP socket which +stays open, so miners don't need to use longpoll to ensure they receive +immediate updates from mining pools when a new block is broadcast to the +peer-to-peer network. + + + +**Resources:** For more information, please see the [BFGMiner][] mining +software licensed under GPLv3 or the [Eloipool][] mining pool software +licensed under AGPLv3. A number of other mining and pool programs +exist, although many are forks of BFGMiner or Eloipool. + +{% endautocrossref %} diff --git a/_includes/guide_payment_processing.md b/_includes/guide_payment_processing.md new file mode 100644 index 00000000..9296b91e --- /dev/null +++ b/_includes/guide_payment_processing.md @@ -0,0 +1,1291 @@ +## Payment Processing + +{% autocrossref %} + +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. This section will explain how how receivers and spenders +can, respectively, request and make payments using Bitcoin---and how +they can deal with complications such as refunds and recurrent +rebilling. + +Bitcoin payment processing is being actively developed at the moment, so +each subsection below attempts to describe what's widely deployed now, +what's new, and what might be coming before the end of 2014. + +![Bitcoin Payment Processing](/img/dev/en-payment-processing.svg) + +The figure above illustrates payment processing using Bitcoin from a +receiver's perspective, starting with a new order. The following +subsections will each address the three common steps and the three +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 + +{% autocrossref %} + +Because of exchange rate variability between satoshis and national +currencies ([fiat][]{:#term-fiat}{:.term}), many Bitcoin orders are priced in 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. + +Any applications which automatically calculate order totals using exchange +rate data must take steps to ensure the price quoted reflects the +current general market value of satoshis, or the applications could +accept too few satoshis for the product or service being sold. +Alternatively, they could ask for too many satoshis, driving away potential +spenders. + +To minimize problems, your applications may want to collect data from at +least two separate sources and compare them to see how much they differ. +If the difference is substantial, your applications can enter a safe mode +until a human is able to evaluate the situation. + +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 fiat into satoshis. + +Because the exchange rate fluctuates over time, order totals pegged to +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. Longer +expiration periods increase the chance that the exchange rate will +fluctuate a significant amount before payment is received. + +{% endautocrossref %} + +### Requesting Payments + +{% autocrossref %} + +Before requesting payment, your application must create a Bitcoin +address, or acquire an address from another program such as +Bitcoin Core. Bitcoin addresses are described in detail in the +[Transactions](#transactions) section. Also described in that section +are two important reasons to [avoid using an address more than +once](#avoiding-key-reuse)---but a third reason applies especially to +payment requests: + +Using a separate address for each incoming payment makes it trivial to +determine which customers have paid their payment requests. Your +applications need only track the association between a particular payment +request and the address used in it, and then scan the block chain for +transactions matching that address. + +The next subsections will describe in detail the following four +compatible ways to give the spender the address and amount to be paid. +For increased convenience and compatibility, providing all of these options in your +payment requests is recommended. + +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 `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 `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. + +**Warning:** special care must be taken to avoid the theft of incoming +payments. In particular, private keys should not be stored on web servers, +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 + +{% autocrossref %} + +To specify an amount directly for copying and pasting, you must provide +the address, the amount, and the denomination. An expiration time for +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][]{:#term-denomination}{:.term} is critical. As of this writing, all popular +Bitcoin wallet software defaults to denominating amounts in either [bitcoins][]{:#term-bitcoins}{:.term} (BTC) +or [millibits][]{:#term-millibits}{:.term} (mBTC). Choosing between BTC and mBTC is widely supported, +but other software also lets its users select denomination amounts from +some or all of the following options: + +{% endautocrossref %} + +| Bitcoins | Unit (Abbreviation) | +|-------------|---------------------| +| 1.0 | bitcoin (BTC) | +| 0.01 | bitcent (cBTC) | +| 0.001 | millibit (mBTC) | +| 0.000001 | microbit (uBTC) | +| 0.00000001 | [satoshi][]{:#term-satoshi}{:.term} | + +{% autocrossref %} + +Because of the widespread popularity of BTC and mBTC, it may be more +useful to specify the amount in both denominations when the text is +meant to be copied and pasted. For example: + +{% endautocrossref %} + +~~~ +Pay: mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN +Amount: 100 BTC (100000 mBTC) +You must pay by: 2014-04-01 at 23:00 UTC +~~~ + +#### bitcoin: URI + +{% 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 decimal bitcoins (BTC), although requests +only for whole bitcoins (as in the example above), may omit the decimal +point. The amount field must not contain any commas. Fractional bitcoins +may be specified with or without a leading zero; for example, either of +the URIs below requesting one millibit are valid: + +{% endautocrossref %} + +~~~ +bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=.001 +bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=0.001 +~~~ + +{% autocrossref %} + +Two other parameters are widely supported. The [`label`][label]{:#term-label}{:.term} parameter is +generally used to provide wallet software with the recipient's name. The +[`message`][message]{:#term-message}{:.term} 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][]. + +All four parameters used together, with appropriate URI encoding, can be +seen in the line-wrapped example below. + +{% endautocrossref %} + +~~~ +bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\ +?amount=0.10\ +&label=Example+Merchant\ +&message=Order+of+flowers+%26+chocolates +~~~ + +{% autocrossref %} + +The URI above could be encoded in HTML as follows, providing compatibility +with wallet software which can't accept URI links and allowing you to +specify an expiration date to the spender. + +{% endautocrossref %} + +~~~ +Order flowers & chocolate using Bitcoin +(Pay 0.10 BTC [100 mBTC] to mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN by 2014-04-01 at 23:00 UTC) +~~~ + +Which produces: + +> Order flowers & chocolates using Bitcoin (Pay 0.10 BTC [100 mBTC] to mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN by 2014-04-01 at 23:00 UTC) + +{% autocrossref %} + +Some payment processors use Javascript to display countdown timers +indicating the number of minutes and seconds until the offer expires. + +The URI scheme can be extended, as will be seen in the payment protocol +section below, with both new optional and required parameters. As of this +writing, the only widely-used parameter besides the four described above +is the payment protocol's `r` parameter. + +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 + +{% 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 +wallets, support scanning QR codes to pre-fill their payment screens. + +The figure below shows the same `bitcoin:` URI code encoded as four +different [Bitcoin QR codes][URI QR code]{:#term-uri-qr-code}{:.term} at different error correction levels (described +below the image). The QR code can include the `label` and `message` +parameters---and any other optional parameters---but they were +omitted here to keep the QR code small and easy to scan with unsteady +or low-resolution mobile cameras. + +![Bitcoin QR Codes](/img/dev/en-qr-code.svg) + +QR encoders offer four possible levels of error correction: + +1. Low: corrects up to 7% damage + +2. Medium: corrects up to 15% damage but results in approximately 8% + larger images over low-level damage correction. + +3. Quartile: corrects corrects up to 25% damage but results in + approximately 20% larger images over low-level damage correction. + +4. High: corrects up to 30% damage but results in approximately 26% + larger images over low-level damage correction. + +The error correction is combined with a checksum to ensure the Bitcoin QR code +cannot be successfully decoded with data missing or accidentally altered, +so your applications should choose the appropriate level of error +correction based on the space you have available to display the code. +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 + +{% autocrossref %} + +Bitcoin Core 0.9 supports the new [payment protocol][]{:#term-payment-protocol}{:.term}. The payment protocol +adds many important features to payment requests: + +- Supports X.509 certificates and SSL encryption to verify receivers' identity + and help prevent man-in-the-middle attacks. + +- Provides more detail about the requested payment to spenders. + +- Allows spenders to submit transactions directly to receivers without going + through the peer-to-peer network. This can speed up payment processing and + work with planned features such as child-pays-for-parent transaction fees + and offline NFC or Bluetooth-based payments. + +Instead of being asked to pay a meaningless address, such as +"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN", spenders are asked to pay the +Common Name (CN) description from the receiver's X.509 certificate, such +as "www.bitcoin.org". + +To request payment using the payment protocol, you use an extended (but +backwards-compatible) `bitcoin:` URI. For example: + +{% endautocrossref %} + +~~~ +bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\ +?amount=0.10\ +&label=Example+Merchant\ +&message=Order+of+flowers+%26+chocolates\ +&r=http://example.com/pay.php/invoice%3Dda39a3ee +~~~ + +{% autocrossref %} + +None of the parameters provided above, except `r`, are required for the +payment protocol---but your applications may include them for backwards +compatibility with wallet programs which don't yet handle the payment +protocol. + +The [`r`][r]{:#term-r-parameter}{:.term} parameter tells payment-protocol-aware wallet programs to ignore +the other parameters and fetch a PaymentRequest from the URL provided. If the +request will be signed, which is recommended but not required, it can be +fetched from an HTTP server---although fetching it from an HTTPS server +would still be preferable. + +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` +parameter, which should provide it with a serialized PaymentRequest +served with the [MIME][] type `application/bitcoin-paymentrequest`. + +{% endautocrossref %} + +##### PaymentRequest & PaymentDetails + +{% autocrossref %} + +The [PaymentRequest][]{:#term-paymentrequest}{:.term} is created with data structures built using +Google's Protocol Buffers. BIP70 describes these data +structures in the non-sequential way they're defined in the payment +request protocol buffer code, but the text below will describe them in +a more linear order using a simple (but functional) Python CGI +program. (For brevity and clarity, many normal CGI best practices are +not used in this program.) + +The full sequence of events is illustrated below, starting with the +spender clicking a `bitcoin:` URI or scanning a `bitcoin:` QR code. + +![BIP70 Payment Protocol](/img/dev/en-payment-protocol.svg) + +For the script to use the protocol buffer, you will need a copy of +Google's Protocol Buffer compiler (`protoc`), which is available in most +modern Linux package managers and [directly from Google.][protobuf] Non-Google +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. + +###### Initialization Code + +With the Python code generated by `protoc`, we can start our simple +CGI program. + +{% endautocrossref %} + +{% highlight python %} +#!/usr/bin/env python + +## This is the code generated by protoc --python_out=./ paymentrequest.proto +from paymentrequest_pb2 import * + +## Load some functions +from time import time +from sys import stdout +from OpenSSL.crypto import FILETYPE_PEM, load_privatekey, sign + +## Copy three of the classes created by protoc into objects we can use +details = PaymentDetails() +request = PaymentRequest() +x509 = X509Certificates() +{% endhighlight %} + +{% autocrossref %} + +The startup code above is quite simple, requiring nothing but the epoch +(Unix date) time function, the standard out file descriptor, a few +functions from the OpenSSL library, and the data structures and +functions created by `protoc`. + +{% endautocrossref %} + +###### Configuration Code + +{% autocrossref %} + +Next, we'll set configuration settings which will typically only change +when the receiver wants to do something differently. The code pushes a +few settings into the `request` (PaymentRequest) and `details` +(PaymentDetails) objects. When we serialize them, +[PaymentDetails][]{:#term-paymentdetails}{:.term} will be contained +within the PaymentRequest. + +{% endautocrossref %} + +{% highlight python %} +## SSL Signature method +request.pki_type = "x509+sha256" ## Default: none + +## Mainnet or Testnet? +details.network = "test" ## Default: main + +## Postback URL +details.payment_url = "https://example.com/pay.py" + +## PaymentDetails version number +request.payment_details_version = 1 ## Default: 1 + +## Certificate chain +x509.certificate.append(file("/etc/apache2/example.com-cert.der", "r").read()) +#x509.certificate.append(file("/some/intermediate/cert.der", "r").read()) + +## Load private SSL key into memory for signing later +priv_key = "/etc/apache2/example.com-key.pem" +pw = "test" ## Key password +private_key = load_privatekey(FILETYPE_PEM, file(priv_key, "r").read(), pw) +{% endhighlight %} + +Each line is described below. + +{% highlight python %} +request.pki_type = "x509+sha256" ## Default: none +{% endhighlight %} + +{% autocrossref %} + +`pki_type`: (optional) tell the receiving wallet program what [Public-Key +Infrastructure][PKI]{:#term-pki}{:.term} (PKI) type you're using to +cryptographically sign your PaymentRequest so that it can't be modified +by a man-in-the-middle attack. + +If you don't want to sign the PaymentRequest, you can choose a +[`pki_type`][pp pki type]{:#term-pp-pki-type}{:.term} of `none` +(the default). + +If you do choose the sign the PaymentRequest, you currently have two +options defined by BIP70: `x509+sha1` and `x509+sha256`. Both options +use the X.509 certificate system, the same system used for HTTP Secure +(HTTPS). To use either option, you will need a certificate signed by a +certificate authority or one of their intermediaries. (A self-signed +certificate will not work.) + +Each wallet program may choose which certificate authorities to trust, +but it's likely that they'll trust whatever certificate authorities their +operating system trusts. If the wallet program doesn't have a full +operating system, as might be the case for small hardware wallets, BIP70 +suggests they use the [Mozilla Root Certificate Store][mozrootstore]. In +general, if a certificate works in your web browser when you connect to +your webserver, it will work for your PaymentRequests. + +{% endautocrossref %} + +{% highlight python %} +details.network = "test" ## Default: main +{% endhighlight %} + +{% autocrossref %} + +`network`: (optional) tell the spender's wallet program what Bitcoin network you're +using; BIP70 defines "main" for mainnet (actual payments) and "test" for +testnet (like mainnet, but fake satoshis are used). If the wallet +program doesn't run on the network you indicate, it will reject the +PaymentRequest. + +{% endautocrossref %} + +{% highlight python %} +details.payment_url = "https://example.com/pay.py" +{% endhighlight %} + +{% autocrossref %} + +`payment_url`: (required) tell the spender's wallet program where to send the Payment +message (described later). This can be a static URL, as in this example, +or a variable URL such as `https://example.com/pay.py?invoice=123.` +It should usually be an HTTPS address to prevent man-in-the-middle +attacks from modifying the message. + +{% endautocrossref %} + +{% highlight python %} +request.payment_details_version = 1 ## Default: 1 +{% endhighlight %} + +{% autocrossref %} + +`payment_details_version`: (optional) tell the spender's wallet program what version of the +PaymentDetails you're using. As of this writing, the only version is +version 1. + +{% endautocrossref %} + +{% highlight python %} +## This is the pubkey/certificate corresponding to the private SSL key +## that we'll use to sign: +x509.certificate.append(file("/etc/apache2/example.com-cert.der", "r").read()) +{% endhighlight %} + +{% autocrossref %} + +`x509certificates`: (required for signed PaymentRequests) you must +provide the public SSL key/certificate corresponding to the private SSL +key you'll use to sign the PaymentRequest. The certificate must be in +ASN.1/DER format. + +{% endautocrossref %} + +{% highlight python %} +## If the pubkey/cert above didn't have the signature of a root +## certificate authority, we'd then append the intermediate certificate +## which signed it: +#x509.certificate.append(file("/some/intermediate/cert.der", "r").read()) +{% endhighlight %} + +{% autocrossref %} + +You must also provide any intermediate certificates necessary to link +your certificate to the root certificate of a certificate authority +trusted by the spender's software, such as a certificate from the +Mozilla root store. + +The certificates must be provided in a specific order---the same order +used by Apache's `SSLCertificateFile` directive and other server +software. The figure below shows the [certificate chain][]{:#term-certificate-chain}{:.term} of the +www.bitcoin.org X.509 certificate and how each certificate (except the +root certificate) would be loaded into the [X509Certificates][]{:#term-x509certificates}{:.term} protocol +buffer message. + +![X509Certificates Loading Order](/img/dev/en-cert-order.svg) + +To be specific, the first certificate provided must be the +X.509 certificate corresponding to the private SSL key which will make the +signature, called the [leaf certificate][]{:#term-leaf-certificate}{:.term}. Any [intermediate +certificates][intermediate certificate]{:#term-intermediate-certificate}{:.term} necessary to link that signed public SSL +key to the [root +certificate][]{:#term-root-certificate}{:.term} (the certificate authority) are attached separately, with each +certificate in DER format bearing the signature of the certificate that +follows it all the way to (but not including) the root certificate. + +{% endautocrossref %} + +{% highlight python %} +priv_key = "/etc/apache2/example.com-key.pem" +pw = "test" ## Key password +private_key = load_privatekey(FILETYPE_PEM, file(priv_key, "r").read(), pw) +{% endhighlight %} + +{% autocrossref %} + +(Required for signed PaymentRequests) you will need a private SSL key in +a format your SSL library supports (DER format is not required). In this +program, we'll load it from a PEM file. (Embedding your passphrase in +your CGI code, as done here, is obviously a bad idea in real life.) + +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 + +{% autocrossref %} + +Now let's look at the variables your CGI program will likely set for +each payment. + +{% endautocrossref %} + +{% highlight python %} +## Amount of the request +amount = 10000000 ## In satoshis + +## P2PH pubkey hash +pubkey_hash = "2b14950b8d31620c6cc923c5408a701b1ec0a020" +## P2PH output script entered as hex and converted to binary +# OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG +# 76 a9 14 88 ac +hex_script = "76" + "a9" + "14" + pubkey_hash + "88" + "ac" +serialized_script = hex_script.decode("hex") + +## Load amount and script into PaymentDetails +details.outputs.add(amount = amount, script = serialized_script) + +## Memo to display to the spender +details.memo = "Flowers & chocolates" + +## Data which should be returned to you with the payment +details.merchant_data = "Invoice #123" +{% endhighlight python %} + +Each line is described below. + +{% highlight python %} +amount = 10000000 ## In satoshis (=100 mBTC) +{% endhighlight %} + +{% autocrossref %} + +`amount`: (optional) the [amount][pp amount]{:#term-pp-amount}{:.term} you want the spender to pay. You'll probably get + this value from your shopping cart application or fiat-to-BTC exchange + rate conversion tool. If you leave the amount blank, the wallet + program will prompt the spender how much to pay (which can be useful + for donations). + +{% endautocrossref %} + +{% highlight python %} +pubkey_hash = "2b14950b8d31620c6cc923c5408a701b1ec0a020" +# OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG +# 76 a9 14 88 ac +hex_script = "76" + "a9" + "14" + pubkey_hash + "88" + "ac" +serialized_script = hex_script.decode("hex") +{% endhighlight %} + +{% autocrossref %} + +`script`: (required) You must specify the output script you want the spender to +pay---any valid script is acceptable. In this example, we'll request +payment to a P2PH output script. + +First we get a pubkey hash. The hash above is the hash form of the +address used in the URI examples throughout this section, +mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN. + +Next, we plug that hash into the standard P2PH output script using hex, +as illustrated by the code comments. + +Finally, we convert the output script from hex into its serialized form. + +{% endautocrossref %} + +{% highlight python %} +details.outputs.add(amount = amount, script = serialized_script) +{% endhighlight %} + +{% autocrossref %} + +`outputs`: (required) add the output script and (optional) amount to the +PaymentDetails outputs array. + +It's possible to specify multiple [`scripts`][pp +script]{:#term-pp-script}{:.term} and `amounts` as part of a merge +avoidance strategy, described later in the [Merge Avoidance +subsection][]. However, effective merge avoidance is not possible under +the base BIP70 rules in which the spender pays each `script` the exact +amount specified by its paired `amount`. If the amounts are omitted from +all `amount`/`script` pairs, the spender will be prompted to choose an +amount to pay. + +{% endautocrossref %} + +{% highlight python %} +details.memo = "Flowers & chocolates" +{% endhighlight %} + +{% autocrossref %} + +`memo`: (optional) add a memo which will be displayed to the spender as +plain UTF-8 text. Embedded HTML or other markup will not be processed. + +{% endautocrossref %} + +{% highlight python %} +details.merchant_data = "Invoice #123" +{% endhighlight %} + +{% autocrossref %} + +`merchant_data`: (optional) add arbitrary data which should be sent back to the +receiver when the invoice is paid. You can use this to track your +invoices, although you can more reliably track payments by generating a +unique address for each payment and then tracking when it gets paid. + +The [`memo`][pp memo]{:#term-pp-memo}{:.term} field and the [`merchant_data`][pp merchant data]{:#term-pp-merchant-data}{:.term} field can be arbitrarily long, +but if you make them too long, you'll run into the 50,000 byte limit on +the entire PaymentRequest, which includes the often several kilobytes +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 + +{% autocrossref %} + +Next, let's look at some information your CGI program can +automatically derive. + +{% endautocrossref %} + +{% highlight python %} +## Request creation time +details.time = int(time()) ## Current epoch (Unix) time + +## Request expiration time +details.expires = int(time()) + 60 * 10 ## 10 minutes from now + +## PaymentDetails is complete; serialize it and store it in PaymentRequest +request.serialized_payment_details = details.SerializeToString() + +## Serialized certificate chain +request.pki_data = x509.SerializeToString() + +## Initialize signature field so we can sign the full PaymentRequest +request.signature = "" + +## Sign PaymentRequest +request.signature = sign(private_key, request.SerializeToString(), "sha256") +{% endhighlight %} + +Each line is described below. + +{% highlight python %} +details.time = int(time()) ## Current epoch (Unix) time +{% endhighlight %} + +{% autocrossref %} + +`time`: (required) PaymentRequests must indicate when they were created +in number of seconds elapsed since 1970-01-01T00:00 UTC (Unix +epoch time format). + +{% endautocrossref %} + +{% highlight python %} +details.expires = int(time()) + 60 * 10 ## 10 minutes from now +{% endhighlight %} + +{% autocrossref %} + +`expires`: (optional) the PaymentRequest may also set an [`expires`][pp +expires]{:#term-pp-expires}{:.term} time after +which they're no longer valid. You probably want to give receivers +the ability to configure the expiration time delta; here we used the +reasonable choice of 10 minutes. If this request is tied to an order +total based on a fiat-to-satoshis exchange rate, you probably want to +base this on a delta from the time you got the exchange rate. + +{% endautocrossref %} + +{% highlight python %} +request.serialized_payment_details = details.SerializeToString() +{% endhighlight %} + +{% autocrossref %} + +`serialized_payment_details`: (required) we've now set everything we need to create the +PaymentDetails, so we'll use the SerializeToString function from the +protocol buffer code to store the PaymentDetails in the appropriate +field of the PaymentRequest. + +{% endautocrossref %} + +{% highlight python %} +request.pki_data = x509.SerializeToString() +{% endhighlight %} + +{% autocrossref %} + +`pki_data`: (required for signed PaymentRequests) serialize the certificate chain +[PKI data][pp PKI data]{:#term-pp-pki-data}{:.term} and store it in the +PaymentRequest + +{% endautocrossref %} + +{% highlight python %} +request.signature = "" +{% endhighlight %} + +{% autocrossref %} + +We've filled out everything in the PaymentRequest except the signature, +but before we sign it, we have to initialize the signature field by +setting it to a zero-byte placeholder. + +{% endautocrossref %} + +{% highlight python %} +request.signature = sign(private_key, request.SerializeToString(), "sha256") +{% endhighlight %} + +{% autocrossref %} + +`signature`: (required for signed PaymentRequests) now we +make the [signature][ssl signature]{:#term-ssl-signature}{:.term} by +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 + +{% 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. + +{% endautocrossref %} + +{% highlight python %} +print "Content-Type: application/bitcoin-paymentrequest" +print "Content-Transfer-Encoding: binary" +print "" +{% endhighlight %} + +{% autocrossref %} + +(Required) BIP71 defines the content types for PaymentRequests, +Payments, and PaymentACKs. + +{% endautocrossref %} + +{% highlight python %} +file.write(stdout, request.SerializeToString()) +{% endhighlight %} + +{% autocrossref %} + +`request`: (required) now, to finish, we just dump out the serialized +PaymentRequest (which contains the serialized PaymentDetails). The +serialized data is in binary, so we can't use Python's print() +because it would add an extraneous newline. + +The following screenshot shows how the authenticated PaymentDetails +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 %} + +##### Payment + +{% autocrossref %} + +If the spender declines to pay, the wallet program will not send any +further messages to the receiver's server unless the spender clicks +another URI pointing to that server. If the spender does decide to pay, +the wallet program will create at least one transaction paying each of +the outputs in the PaymentDetails section. The wallet may broadcast +the transaction or transactions, as Bitcoin Core 0.9 does, but it +doesn't need to. + +Whether or not it broadcasts the transaction or transactions, the wallet +program composes a reply to the PaymentRequest; the reply is called the +Payment. [Payment][pp payment]{:#term-pp-payment}{:.term} contains four fields: + +* `merchant_data`: (optional) an exact copy of the + `merchant_data` from the PaymentDetails. This is + optional in the case that the PaymentDetails doesn't provide + `merchant_data`. Receivers should be aware that malicious spenders can + modify the merchant data before sending it back, so receivers may wish to + cryptographically sign it before giving it to the spender and then + validate it before relying on it. + +* [`transactions`][pp transactions]{:#term-pp-transactions}{:.term}: (required) one or more signed transactions which pay the outputs + specified in the PaymentDetails. + + + +* [`refund_to`][pp refund to]{:#term-pp-refund-to}{:.term}: (required) one or more output scripts to which the + receiver can send a partial or complete refund. As of this writing, a + proposal is gaining traction to expire refund output scripts after a + certain amount of time (not defined yet) so spenders don't need to + worry about receiving refunds to addresses they no longer monitor. + +* `memo`: (optional) a plain UTF-8 text memo sent to the receiver. It + should not contain HTML or any other markup. Spenders should not depend + on receivers reading their memos. + +The Payment is sent to the [`payment_url`][pp payment +url]{:#term-pp-payment-url}{:.term} provided in the PaymentDetails. +The URL should be a HTTPS address to prevent a man-in-the-middle attack +from modifying the spender's `refund_to` output scripts. When sending the +Payment, the wallet program must set the following HTTP client headers: + +{% endautocrossref %} + +~~~ +Content-Type: application/bitcoin-payment +Accept: application/bitcoin-paymentack +~~~ + +##### PaymentACK +{% autocrossref %} + +The receiver's CGI program at the `payment_url` receives the Payment message and +decodes it using its Protocol Buffers code. The `transactions` are +checked to see if they pay the output scripts the receiver requested in +PaymentDetails and are then broadcast to the network (unless the network +already has them). + +The CGI program checks the `merchant_data` parameter if necessary and issues +a [PaymentACK][]{:#term-paymentack}{:.term} (acknowledgment) with the following HTTP headers: + +{% endautocrossref %} + +~~~ +Content-Type: application/bitcoin-paymentack +Content-Transfer-Encoding: binary +~~~ + +{% autocrossref %} + +Then it sends another Protocol-Buffers-encoded message with one or two +fields: + +* `payment`: (required) A copy of the the entire Payment message (in + serialized form) which is being acknowledged. + +* `memo`: (optional) A plain UTF-8 text memo displayed to the spender + informing them about the status of their payment. It should not + contain HTML or any other markup. Receivers should not depend on + spenders reading their memos. + +The PaymentACK does not mean that the payment is final; it just means +that everything seems to be correct. The payment is final once the +payment transactions are block-chain confirmed to the receiver's +satisfaction. + +However, the spender's wallet program should indicate to the spender that +the payment was accepted for processing so the spender can direct his or +her attention elsewhere. + +{% endautocrossref %} + +##### Receipts + +{% autocrossref %} + +Unlike PaymentRequest, PaymentDetails, [Payment][pp payment]{:.auto-link}, and PaymentACK, there is +no specific [receipt][]{:#term-receipt}{:.term} object. However, a cryptographically-verifiable +receipt can be derived from a signed PaymentDetails and one or more confirmed +transactions. + +A signed PaymentDetails indicates what output scripts should be paid +(`script`), how much they should be paid (`amount`), and by when +(`expires`). The Bitcoin block chain indicates whether those outputs +were paid the requested amount and can provide a rough idea of when the +transactions were generated. Together, this information provides +verifiable proof that the spender paid somebody with the +receiver's private SSL key. + +{% endautocrossref %} + +### Verifying Payment + +{% autocrossref %} + +As explained in the [Transactions][] and [Block Chain][] sections, broadcasting +a transaction to the network doesn't ensure that the receiver gets +paid. A malicious spender can create one transaction that pays the +receiver and a second one that pays the same input back to himself. Only +one of these transactions will be added to the block chain, and nobody +can say for sure which one it will be. + +Two or more transactions spending the same input are commonly referred +to as a [double spend][]{:#term-double-spend}{:.term}. + +Once the transaction is included in a block, double spends are +impossible without modifying block chain history to replace the +transaction, which is quite difficult. Using this system, +the Bitcoin protocol can give each of your transactions an updating confidence +score based on the number of blocks which would need to be modified to replace +a transaction. For each block, the transaction gains one [confirmation][]{:#term-confirmation}{:.term}. Since +modifying blocks is quite difficult, higher confirmation scores indicate +greater protection. + +**0 confirmations**: The transaction has been broadcast but is still not +included in any block. Zero confirmation transactions ([unconfirmed +transactions][]{:#term-unconfirmed-transactions}{:.term}) should generally not be +trusted without risk analysis. Although miners usually confirm the first +transaction they receive, fraudsters may be able to manipulate the +network into including their version of a transaction. + +**1 confirmation**: The transaction is included in the latest block and +double-spend risk decreases dramatically. Transactions which pay +sufficient transaction fees need 10 minutes on average to receive one +confirmation. However, the most recent block gets replaced fairly often by +accident, so a double spend is still a real possibility. + +**2 confirmations**: The most recent block was chained to the block which +includes the transaction. As of March 2014, two block replacements were +exceedingly rare, and a two block replacement attack was impractical without +expensive mining equipment. + +**6 confirmations**: The network has spent about an hour working to protect +the transaction against double spends and the transaction is buried under six +blocks. Even a reasonably lucky attacker would require a large percentage of +the total network hashing power to replace six blocks. Although this number is +somewhat arbitrary, software handling high-value transactions, or otherwise at +risk for fraud, should wait for at least six confirmations before treating a +payment as accepted. + +Bitcoin Core provides several RPCs which can provide your program with the +confirmation score for transactions in your wallet or arbitrary transactions. +For example, the `listunspent` RPC provides an array of every satoshi you can +spend along with its confirmation score. + +Although confirmations provide excellent double-spend protection most of the +time, there are at least three cases where double-spend risk analysis can be +required: + +1. In the case when the program or its user cannot wait for a confirmation and +wants to accept unconfirmed payments. + +2. In the case when the program or its user is accepting high value +transactions and cannot wait for at least six confirmations or more. + +3. In the case of an implementation bug or prolonged attack against Bitcoin +which makes the system less reliable than expected. + +An interesting source of double-spend risk analysis can be acquired by +connecting to large numbers of Bitcoin peers to track how transactions and +blocks differ from each other. Some third-party APIs can provide you with this +type of service. + + + +For example, unconfirmed transactions can be compared among all connected peers +to see if any UTXO is used in multiple unconfirmed transactions, indicating a +double-spend attempt, in which case the payment can be refused until it is +confirmed. Transactions can also be ranked by their transaction fee to +estimate the amount of time until they're added to a block. + +Another example could be to detect a fork when multiple peers report differing +block header hashes at the same block height. Your program can go into a safe mode if the +fork extends for more than two blocks, indicating a possible problem with the +block chain. + +Another good source of double-spend protection can be human intelligence. For +example, fraudsters may act differently from legitimate customers, letting +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 + +{% autocrossref %} + +Occasionally receivers using your applications will need to issue +refunds. The obvious way to do that, which is very unsafe, is simply +to return the satoshis to the output script from which they came. +For example: + +* Alice wants to buy a widget from Bob, so Bob gives Alice a price and + Bitcoin address. + +* Alice opens her wallet program and sends some satoshis to that + address. Her wallet program automatically chooses to spend those + satoshis from one of its unspent outputs, an output corresponding to + the Bitcoin address mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN. + +* Bob discovers Alice paid too many satoshis. Being an honest fellow, + Bob refunds the extra satoshis to the mjSk... address. + +This seems like it should work, but Alice is using a centralized +multi-user web wallet which doesn't give unique addresses to each user, +so it has no way to know that Bob's refund is meant for Alice. Now the +refund is a unintentional donation to the company behind the centralized +wallet, unless Alice opens a support ticket and proves those satoshis +were meant for her. + +This leaves receivers only two correct ways to issue refunds: + +* If an address was copy-and-pasted or a basic `bitcoin:` URI was used, + contact the spender directly and ask them to provide a refund address. + +* If the payment protocol was used, send the refund to the output + listed in the `refund_to` field of the Payment message. + +As discussed in the Payment section, `refund_to` addresses may come with +implicit expiration dates, so you may need to revert to contacting the +spender directly if the refund is being issued a long time after the +original payment was made. + +{% endautocrossref %} + +### Disbursing Income (Limiting Forex Risk) + +{% 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 +forex risk, many receivers choose to disburse newly-acquired payments +soon after they're received. + +If your application provides this business logic, it will need to choose +which outputs to spend first. There are a few different algorithms +which can lead to different results. + +* A merge avoidance algorithm makes it harder for outsiders looking + at block chain data to figure out how many satoshis the receiver has + earned, spent, and saved. + +* A last-in-first-out (LIFO) algorithm spends newly acquired satoshis + while there's still double spend risk, possibly pushing that risk on + to others. This can be good for the receiver's balance sheet but + possibly bad for their reputation. + +* A first-in-first-out (FIFO) algorithm spends the oldest satoshis + 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 + +{% 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 +can't automatically see other satoshis paid to the receiver by other +spenders as long as the receiver uses unique addresses for each +transaction. + +However, if the receiver spends satoshis from two different spenders in +the same transaction, each of those spenders can see the other spender's +payment. This is called a [merge][]{:#term-merge}{:.term}, and the more a receiver merges +outputs, the easier it is for an outsider to track how many satoshis the +receiver has earned, spent, and saved. + +[Merge avoidance][]{:#term-merge-avoidance}{:.term} means trying to avoid spending unrelated outputs in the +same transaction. For persons and businesses which want to keep their +transaction data secret from other people, it can be an important strategy. + +A crude merge avoidance strategy is to try to always pay with the +smallest output you have which is larger than the amount being +requested. For example, if you have four outputs holding, respectively, +100, 200, 500, and 900 satoshis, you would pay a bill for 300 satoshis +with the 500-satoshi output. This way, as long as you have outputs +larger than your bills, you avoid merging. + +More advanced merge avoidance strategies largely depend on enhancements +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) + +{% 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 +double-spent, spending them before older outputs allows the spender to +hold on to older confirmed outputs which are much less likely to be +double-spent. + +There are two closely-related downsides to LIFO: + +* If you spend an output from one unconfirmed transaction in a second + transaction, the second transaction becomes invalid if transaction + malleability changes the first transaction. + +* If you spend an output from one unconfirmed transaction in a second + transaction and the first transaction's output is successfully double + spent to another output, the second transaction becomes invalid. + +In either of the above cases, the receiver of the second transaction +will see the incoming transaction notification disappear or turn into an +error message. + +Because LIFO puts the recipient of secondary transactions in as much +double-spend risk as the recipient of the primary transaction, they're +best used when the secondary recipient doesn't care about the +risk---such as an exchange or other service which is going to wait for +six confirmations whether you spend old outputs or new outputs. + +LIFO should not be used when the primary transaction recipient's +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) + +{% 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 +spend them. However, after just a few blocks, a point of rapidly +diminishing returns is reached. The [original Bitcoin paper][bitcoinpdf] +predicts the chance of an attacker being able to modify old blocks, +assuming the attacker has 30% of the total network hashing power: + +| Blocks | Chance of successful modification | +|--------|----------------------------------| +| 5 | 17.73523% | +| 10 | 4.16605% | +| 15 | 1.01008% | +| 20 | 0.24804% | +| 25 | 0.06132% | +| 30 | 0.01522% | +| 35 | 0.00379% | +| 40 | 0.00095% | +| 45 | 0.00024% | +| 50 | 0.00006% | + +FIFO does have a small advantage when it comes to transaction fees, as +older outputs may be eligible for inclusion in the 50,000 bytes set +aside for no-fee-required high-priority transactions by miners running the default Bitcoin Core +codebase. However, with transaction fees being so low, this is not a +significant advantage. + +The only practical use of FIFO is by receivers who spend all or most +of their income within a few blocks, and who want to reduce the +chance of their payments becoming accidentally invalid. For example, +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 + +{% autocrossref %} + +Automated recurring payments are not possible with decentralized Bitcoin +wallets. Even if a wallet supported automatically sending non-reversible +payments on a regular schedule, the user would still need to start the +program at the appointed time, or leave it running all the time +unprotected by encryption. + +This means automated recurring Bitcoin payments can only be made from a +centralized server which handles satoshis on behalf of its spenders. In +practice, receivers who want to set prices in fiat terms must also let +the same centralized server choose the appropriate exchange rate. + +Non-automated rebilling can be managed by the same mechanism used before +credit-card recurring payments became common: contact the spender and +ask them to pay again---for example, by sending them a PaymentRequest +`bitcoin:` URI in an HTML email. + +In the future, extensions to the payment protocol and new wallet +features may allow some wallet programs to manage a list of recurring +transactions. The spender will still need to start the program on a +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/_includes/guide_transactions.md b/_includes/guide_transactions.md new file mode 100644 index 00000000..9f4e4041 --- /dev/null +++ b/_includes/guide_transactions.md @@ -0,0 +1,664 @@ +## Transactions + +{% autocrossref %} + + + + + +Transactions let users spend satoshis. Each transaction is constructed +out of several parts which enable both simple direct payments and complex +transactions. This section will describe each part and +demonstrate how to use them together to build complete transactions. + +To keep things simple, this section pretends coinbase transactions do +not exist. Coinbase transactions can only be created by Bitcoin miners +and they're an exception to many of the rules listed below. Instead of +pointing out the coinbase exception to each rule, we invite you to read +about coinbase transactions in the block chain section of this guide. + +![The Parts Of A Transaction](/img/dev/en-tx-overview.svg) + +The figure above shows the core parts of a Bitcoin transaction. Each +transaction has at least one input and one output. Each [input][]{:#term-input}{:.term} spends the +satoshis paid to a previous output. Each [output][]{:#term-output}{:.term} then waits as an Unspent +Transaction Output (UTXO) until a later input spends it. When your +Bitcoin wallet tells you that you have a 10,000 satoshi balance, it really +means that you have 10,000 satoshis waiting in one or more UTXOs. + +Each transaction is prefixed by a four-byte [transaction version number][]{:#term-transaction-version-number}{:.term} which tells +Bitcoin peers and miners which set of rules to use to validate it. This +lets developers create new rules for future transactions without +invalidating previous transactions. + +The figures below help illustrate the other transaction features by +showing the workflow Alice uses to send Bob a transaction and which Bob +later uses to spend that transaction. Both Alice and Bob will use the +most common form of the standard Pay-To-Pubkey-Hash (P2PH) transaction +type. [P2PH][]{:#term-p2ph}{:.term} lets Alice spend satoshis to a typical Bitcoin address, +and then lets Bob further spend those satoshis using a simple +cryptographic key pair. + +![Creating A P2PH Public Key Hash To Receive Payment](/img/dev/en-creating-p2ph-output.svg) + +Bob must first generate a private/public [key pair][]{:#term-key-pair}{:.term} before Alice can create the +first transaction. Standard Bitcoin [private keys][private +key]{:#term-private-key}{:.term} are 256 bits of random +data. A copy of that data is deterministically transformed into a [public +key][]{:#term-public-key}{:.term}. Because the transformation can be reliably repeated later, the +public key does not need to be stored. + +The public key is then cryptographically hashed. This pubkey hash can +also be reliably repeated later, so it also does not need to be stored. +The hash shortens and obfuscates the public key, making manual +transcription easier and providing security against +unanticipated problems which might allow reconstruction of private keys +from public key data at some later point. + + + +Bob provides the [pubkey hash][]{:#term-pubkey-hash}{:.term} to Alice. Pubkey hashes are almost always +sent encoded as Bitcoin [addresses][]{:#term-address}{:.term}, which are base58-encoded strings +containing an address version number, the hash, and an error-detection +checksum to catch typos. The address can be transmitted +through any medium, including one-way mediums which prevent the spender +from communicating with the receiver, and it can be further encoded +into another format, such as a QR code containing a `bitcoin:` +URI. + +Once Alice has the address and decodes it back into a standard hash, she +can create the first transaction. She creates a standard P2PH +transaction output containing instructions which allow anyone to spend that +output if they can prove they control the private key corresponding to +Bob's hashed public key. These instructions are called the output [script][]{:#term-script}{:.term}. + +Alice broadcasts the transaction and it is added to the block chain. +The network categorizes it as an Unspent Transaction Output (UTXO), and Bob's +wallet software displays it as a spendable balance. + +When, some time later, Bob decides to spend the UTXO, he must create an +input which references the transaction Alice created by its hash, called +a Transaction Identifier (txid), and the specific output she used by its +index number ([output index][]{:#term-output-index}{:.term}). He must then create a [scriptSig][]{:#term-scriptsig}{:.term}---a +collection of data parameters which satisfy the conditions Alice placed +in the previous output's script. + +![Unlocking A P2PH Output For Spending](/img/dev/en-unlocking-p2ph-output.svg) + +Bob does not need to communicate with Alice to do this; he must simply +prove to the Bitcoin peer-to-peer network that he can satisfy the +script's conditions. For a P2PH-style output, Bob's scriptSig will +contain the following two pieces of data: + +1. His full (unhashed) public key, so the script can check that it + hashes to the same value as the pubkey hash provided by Alice. + +2. A [signature][]{:#term-signature}{:.term} made by using the ECDSA cryptographic formula to combine + certain transaction data (described below) with Bob's private key. + This lets the script verify that Bob owns the private key which + created the public key. + +Bob's signature doesn't just prove Bob controls his private key; it also +makes the rest of his transaction tamper-proof so Bob can safely +broadcast it over the peer-to-peer network. + +![Some Things Signed When Spending An Output](/img/dev/en-signing-output-to-spend.svg) + +As illustrated in the figure above, the data Bob signs includes the +txid and output index of the previous transaction, the previous +output's script, the script Bob creates which will let the next +recipient spend this transaction's output, and the amount of satoshis to +spend to the next recipient. In essence, the entire transaction is +signed except for any scriptSigs, which hold the full public keys and +signatures. + +After putting his signature and public key in the scriptSig, Bob +broadcasts the transaction to Bitcoin miners through the peer-to-peer +network. Each peer and miner independently validates the transaction +before broadcasting it further or attempting to include it in a new block of +transactions. + +{% endautocrossref %} + +### P2PH Script Validation + +{% autocrossref %} + +The validation procedure requires evaluation of the script. In a P2PH +output, the script is: + +{% endautocrossref %} + +~~~ +OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG +~~~ + +{% autocrossref %} + +The spender's scriptSig is evaluated and prefixed to the beginning of the +script. In a P2PH transaction, the scriptSig contains a signature (sig) +and full public key (pubkey), creating the following concatenation: + +{% endautocrossref %} + +~~~ + OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG +~~~ + +{% autocrossref %} + +The script language is a +[Forth-like](https://en.wikipedia.org/wiki/Forth_%28programming_language%29) +[stack][]{:#term-stack}{:.term}-based language deliberately designed to be stateless and not +Turing complete. Statelessness ensures that once a transaction is added +to the block chain, there is no condition which renders it permanently +unspendable. Turing-incompleteness (specifically, a lack of loops or +gotos) makes the script language less flexible and more predictable, +greatly simplifying the security model. + + + +To test whether the transaction is valid, scriptSig and script arguments +are pushed to the stack one item at a time, starting with Bob's scriptSig +and continuing to the end of Alice's script. The figure below shows the +evaluation of a standard P2PH script; below the figure is a description +of the process. + +![P2PH Stack Evaluation](/img/dev/en-p2ph-stack.svg) + +* The signature (from Bob's scriptSig) is added (pushed) to an empty stack. + Because it's just data, nothing is done except adding it to the stack. + The public key (also from the scriptSig) is pushed on top of the signature. + +* From Alice's script, the `OP_DUP` operation is pushed. `OP_DUP` replaces + itself with a copy of the data from one level below it---in this + case creating a copy of the public key Bob provided. + +* The operation pushed next, `OP_HASH160`, replaces itself with a hash + of the data from one level below it---in this case, Bob's public key. + This creates a hash of Bob's public key. + +* Alice's script then pushes the pubkey hash that Bob gave her for the + first transaction. At this point, there should be two copies of Bob's + pubkey hash at the top of the stack. + +* Now it gets interesting: Alice's script adds `OP_EQUALVERIFY` to the + stack. `OP_EQUALVERIFY` expands to `OP_EQUAL` and `OP_VERIFY` (not shown). + + `OP_EQUAL` (not shown) checks the two values below it; in this + case, it checks whether the pubkey hash generated from the full + public key Bob provided equals the pubkey hash Alice provided when + she created transaction #1. `OP_EQUAL` then replaces itself and + the two values it compared with the result of that comparison: + zero (*false*) or one (*true*). + + `OP_VERIFY` (not shown) checks the value immediately below it. If + the value is *false* it immediately terminates stack evaluation and + the transaction validation fails. Otherwise it pops both itself and + the *true* value off the stack. + +* Finally, Alice's script pushes `OP_CHECKSIG`, which checks the + signature Bob provided against the now-authenticated public key he + also provided. If the signature matches the public key and was + generated using all of the data required to be signed, `OP_CHECKSIG` + replaces itself with *true.* + +If *true* is at the top of the stack after the script has been +evaluated, the transaction is valid (provided there are no other +problems with it). + +{% endautocrossref %} + +### P2SH Scripts + +{% autocrossref %} + +Output scripts are created by spenders who have little interest in the +long-term security or usefulness of the particular satoshis they're +currently spending. Receivers do care about the conditions imposed on +the satoshis by the output script and, if they want, they can ask +spenders to use a particular script. Unfortunately, custom scripts are +less convenient than short Bitcoin addresses and more difficult to +secure than P2PH pubkey hashes. + +To solve these problems, pay-to-script-hash +([P2SH][]{:#term-p2sh}{:.term}) transactions were created in 2012 to let +a spender create an output script containing a [hash of a second +script][script hash]{:#term-script-hash}{:.term}, the +[redeemScript][]{:#term-redeemscript}{:.term}. + +The basic P2SH workflow, illustrated below, looks almost identical to +the P2PH workflow. Bob creates a redeemScript with whatever script he +wants, hashes the redeemScript, and provides the redeemScript +hash to Alice. Alice creates a P2SH-style output containing +Bob's redeemScript hash. + +![Creating A P2SH RedeemScript And Hash](/img/dev/en-creating-p2sh-output.svg) + +When Bob wants to spend the output, he provides his signature along with +the full (serialized) redeemScript in the input scriptSig. The +peer-to-peer network ensures the full redeemScript hashes to the same +value as the script hash Alice put in her output; it then processes the +redeemScript exactly as it would if it were the primary script, letting +Bob spend the output if the redeemScript returns true. + +![Unlocking A P2SH Output For Spending](/img/dev/en-unlocking-p2sh-output.svg) + +The hash of the redeemScript has the same properties as a pubkey +hash---so it can be transformed into the standard Bitcoin address format +with only one small change to differentiate it from a standard address. +This makes collecting a P2SH-style address as simple as collecting a +P2PH-style address. The hash also obfuscates any public keys in the +redeemScript, so P2SH scripts are as secure as P2PH pubkey hashes. + +{% endautocrossref %} + +### Standard Transactions + +{% autocrossref %} + +Care must be taken to avoid non-standard output scripts. As of Bitcoin Core +0.9, the standard script types are: + +**Pubkey Hash (P2PH)** + +P2PH is the most common form of script used to send a transaction to one +or multiple Bitcoin addresses. + +{% endautocrossref %} + +~~~ +script: OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG +scriptSig: +~~~ + +{% autocrossref %} + +**Script Hash (P2SH)** + +P2SH is used to send a transaction to a script hash. Each of the standard +scripts can be used inside a P2SH redeemScript, but in practice only the +multisig script makes sense until more transaction types are made standard. + +{% endautocrossref %} + +~~~ +script: OP_HASH160 OP_EQUAL +scriptSig: [sig] [sig...] +~~~ + +{% autocrossref %} + +**Multisig** + +Although P2SH multisig is now generally used for multisig transactions, this base script +can be used to require multiple signatures before a UTXO can be spent. + +In multisig scripts, called m-of-n, *m* is the *minimum* number of signatures +which must match a public key; *n* is the *number* of public keys being +provided. Both *m* and *n* should be op codes `OP_1` through `OP_16`, +corresponding to the number desired. + +Because of an off-by-one error in the original Bitcoin implementation +which must be preserved for compatibility, `OP_CHECKMULTISIG` +consumes one more value from the stack than indicated by *m*, so the +list of signatures in the scriptSig must be prefaced with an extra value +(`OP_0`) which will be consumed but not used. + +{% endautocrossref %} + +~~~ +script: [pubkey] [pubkey...] OP_CHECKMULTISIG +scriptSig: OP_0 [sig] [sig...] +~~~ + +{% autocrossref %} + +Although it’s not a separate transaction type, this is a P2SH multisig with 2-of-3: + +{% endautocrossref %} + +~~~ +script: OP_HASH160 OP_EQUAL +redeemScript: OP_CHECKMULTISIG +scriptSig: OP_0 +~~~ + +{% autocrossref %} + +**Pubkey** + +[Pubkey][]{:#term-pubkey}{:.term} scripts are a simplified form of the P2PH script; they’re used in all +coinbase transactions, but they aren’t as convenient +or secure as P2PH, so they generally +aren’t used elsewhere. + +{% endautocrossref %} + +~~~ +script: OP_CHECKSIG +scriptSig: +~~~ + +{% autocrossref %} + +**Null Data** + +[Null data][]{:#term-null-data}{:.term} scripts let you add a small amount of arbitrary data to the block +chain in exchange for paying a transaction fee, but doing so is discouraged. +(Null data is a standard script type only because some people were adding data +to the block chain in more harmful ways.) + +{% endautocrossref %} + +~~~ +script: OP_RETURN +(Null data scripts cannot be spent, so there's no scriptSig) +~~~ + +#### Non-Standard Transactions + +{% autocrossref %} + +If you use anything besides a standard script in an output, peers +and miners using the default Bitcoin Core settings will neither +accept, broadcast, nor mine your transaction. When you try to broadcast +your transaction to a peer running the default settings, you will +receive an error. + +Unfortunately, if you create a non-standard redeemScript, hash it, and use the hash +in a P2SH output, the network sees only the hash, so it will accept the +output as valid no matter what the redeemScript says. When you go to +spend that output, however, peers and miners using the default settings +will see the non-standard redeemScript and reject it. It will be +impossible to spend that output until you find a miner who disables the +default settings. + +As of Bitcoin Core 0.9, standard transactions must also meet the following +conditions: + +* The transaction must be finalized: either its locktime must be in the + past (or less than or equal to the current block height), or all of its sequence + numbers must be 0xffffffff. + +* The transaction must be smaller than 100,000 bytes. That's around 200 + times larger than a typical single-input, single-output P2PH + transaction. + +* Each of the transaction's inputs must be smaller than 500 bytes. + That's large enough to allow 3-of-3 multisig transactions in P2SH. + Multisig transactions which require more than 3 public keys are + currently non-standard. + +* The transaction's scriptSig must only push data to the script + evaluation stack. It cannot push new OP codes, with the exception of + OP codes which solely push data to the stack. + +* If any of the transaction's outputs spend less than a minimal value + (currently 546 satoshis), the transaction must pay + a minimum transaction fee (currently 10,000 satoshis). + +{% endautocrossref %} + +### Signature Hash Types + +{% autocrossref %} + +`OP_CHECKSIG` extracts a non-stack argument from each signature it +evaluates, allowing the signer to decide which parts of the transaction +to sign. Since the signature protects those parts of the transaction +from modification, this lets signers selectively choose to let other +people modify their transactions. + +The various options for what to sign are +called [signature hash][]{:#term-signature-hash}{:.term} types. There are three base SIGHASH types +currently available: + +* [`SIGHASH_ALL`][sighash_all]{:#term-sighash-all}{:.term}, the default, signs all the inputs and outputs, + protecting everything except the scriptSigs against modification. + +* [`SIGHASH_NONE`][sighash_none]{:#term-sighash-none}{:.term} signs all of the inputs but none of the outputs, + allowing anyone to change where the satoshis are going unless other + signatures using other signature hash flags protect the outputs. + +* [`SIGHASH_SINGLE`][sighash_single]{:#term-sighash-single}{:.term} signs only this input and only one corresponding + output (the output with the same output index number as the input), ensuring + nobody can change your part of the transaction but allowing other + signers to change their part of the transaction. The corresponding + output must exist or the value "1" will be signed, breaking the security + scheme. + +The base types can be modified with the [`SIGHASH_ANYONECANPAY`][shacp]{:#term-sighash-anyonecanpay}{:.term} (anyone can +pay) flag, creating three new combined types: + +* [`SIGHASH_ALL|SIGHASH_ANYONECANPAY`][sha_shacp]{:#term-sighash-all-sighash-anyonecanpay}{:.term} signs all of the outputs but only + this one input, and it also allows anyone to add or remove other + inputs, so anyone can contribute additional satoshis but they cannot + change how many satoshis are sent nor where they go. + +* [`SIGHASH_NONE|SIGHASH_ANYONECANPAY`][shn_shacp]{:#term-sighash-none-sighash-anyonecanpay}{:.term} signs only this one input and + allows anyone to add or remove other inputs or outputs, so anyone who + gets a copy of this input can spend it however they'd like. + +* [`SIGHASH_SINGLE|SIGHASH_ANYONECANPAY`][shs_shacp]{:#term-sighash-single-sighash-anyonecanpay}{:.term} signs only this input and only + one corresponding output, but it also allows anyone to add or remove + other inputs. + +Because each input is signed, a transaction with multiple inputs can +have multiple signature hash types signing different parts of the transaction. For +example, a single-input transaction signed with `NONE` could have its +output changed by the miner who adds it to the block chain. On the other +hand, if a two-input transaction has one input signed with `NONE` and +one input signed with `ALL`, the `ALL` signer can choose where to spend +the satoshis without consulting the `NONE` signer---but nobody else can +modify the transaction. + + + + + +{% endautocrossref %} + +### Locktime And Sequence Number + +{% autocrossref %} + +One thing all signature hash types sign is the transaction's [locktime][]{:#term-locktime}{:.term}. +The locktime indicates the earliest time a transaction can be added to +the block chain. + +Locktime allows signers to create time-locked transactions which will +only become valid in the future, giving the signers a chance to change +their minds. + +If any of the signers change their mind, they can create a new +non-locktime transaction. The new transaction will use, as one of +its inputs, one of the same outputs which was used as an input to +the locktime transaction. This makes the locktime transaction +invalid if the new transaction is added to the block chain before +the time lock expires. + +Care must be taken near the expiry time of a time lock. The peer-to-peer +network allows block time to be up to two hours ahead of +real time, so a locktime transaction can be added to the block chain up +to two hours before its time lock officially expires. Also, blocks are +not created at guaranteed intervals, so any attempt to cancel a valuable +transaction should be made a few hours before the time lock expires. + +Previous versions of Bitcoin Core provided a feature which prevented +transaction signers from using the method described above to cancel a +time-locked transaction, but a necessary part of this feature was +disabled to prevent DOS attacks. A legacy of this system are four-byte +[sequence numbers][sequence number]{:#term-sequence-number}{:.term} in every input. Sequence numbers were meant to allow +multiple signers to agree to update a transaction; when they finished +updating the transaction, they could agree to set every input's +sequence number to the four-byte unsigned maximum (0xffffffff), +allowing the transaction to be added to a block even if its time lock +had not expired. + +Even today, setting all sequence numbers to 0xffffffff (the default in +Bitcoin Core) can still disable the time lock, so if you want to use +locktime, at least one input must have a sequence number below the +maximum. Since sequence numbers are not used by the network for any +other purpose, setting any sequence number to zero is sufficient to +enable locktime. + +Locktime itself is an unsigned 4-byte number which can be parsed two ways: + +* If less than 500 million, locktime is parsed as a block height. The + transaction can be added to any block which has this height or higher. + +* If greater than or equal to 500 million, locktime is parsed using the + Unix epoch time format (the number of seconds elapsed since + 1970-01-01T00:00 UTC---currently over 1.395 billion). The transaction + can be added to any block whose block time is greater + than the locktime. + +{% endautocrossref %} + +### Transaction Fees And Change + +{% autocrossref %} + +Transactions typically pay transaction fees based on the total byte size +of the signed transaction. The transaction fee is given to the +Bitcoin miner, as explained in the [block chain section][block chain], and so it is +ultimately up to each miner to choose the minimum transaction fee they +will accept. + + + +By default, miners reserve 50 KB of each block for [high-priority +transactions][]{:#term-high-priority-transactions}{:.term} which spend satoshis that haven't been spent for a long +time. The remaining space in each block is typically allocated to transactions +based on their fee per byte, with higher-paying transactions being added +in sequence until all of the available space is filled. + +As of Bitcoin Core 0.9, transactions which do not count as high-priority transactions +need to pay a [minimum fee][]{:#term-minimum-fee}{:.term} of 10,000 satoshis to be +broadcast across the network. Any transaction paying the minimum fee +should be prepared to wait a long time before there's enough spare space +in a block to include it. Please see the [verifying payment section][section verifying payment] +for why this could be important. + +Since each transaction spends Unspent Transaction Outputs (UTXOs) and +because a UTXO can only be spent once, the full value of the included +UTXOs must be spent or given to a miner as a transaction fee. Few +people will have UTXOs that exactly match the amount they want to pay, +so most transactions include a change output. + +[Change outputs][change output]{:#term-change-output}{:.term} are regular outputs which spend the surplus satoshis +from the UTXOs back to the spender. They can reuse the same P2PH pubkey hash +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 P2PH or P2SH address. + +{% endautocrossref %} + +### Avoiding Key Reuse + +{% 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 +person to use the public block chain to track past and future +transactions involving the other person's same public keys or addresses. + +If the same public key is reused often, as happens when people use +Bitcoin addresses (hashed public keys) as static payment addresses, +other people can easily track the receiving and spending habits of that +person, including how many satoshis they control in known addresses. + +It doesn't have to be that way. If each public key is used exactly +twice---once to receive a payment and once to spend that payment---the +user can gain a significant amount of financial privacy. + +Even better, using new public keys or [unique +addresses][]{:#term-unique-address}{:.term} when accepting payments or creating +change outputs can be combined with other techniques discussed later, +such as CoinJoin or merge avoidance, to make it extremely difficult to +use the block chain by itself to reliably track how users receive and +spend their satoshis. + +Avoiding key reuse in combination with P2PH or P2SH addresses also +prevents anyone from seeing the user's ECDSA public key until he spends +the satoshis sent to those addresses. This, combined with the block +chain, provides security against hypothetical future attacks which may +allow reconstruction of private keys from public keys in a matter of +hours, days, months, or years (but not any faster). + +So, for both privacy and security, we encourage you to build your +applications to avoid public key reuse and, when possible, to discourage +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 + +{% autocrossref %} + +None of Bitcoin's signature hash types protect the scriptSig, leaving +the door open for a limited DOS attack called [transaction +malleability][]{:.term}{:#term-transaction-malleability}. The scriptSig +contains the signature, which can't sign itself, allowing attackers to +make non-functional modifications to a transaction without rendering it +invalid. For example, an attacker can add some data to the scriptSig +which will be dropped before the previous output script is processed. + +Although the modifications are non-functional---so they do not change +what inputs the transaction uses nor what outputs it pays---they do +change the computed hash of the transaction. Since each transaction +links to previous transactions using hashes as a transaction +identifier (txid), a modified transaction will not have the txid its +creator expected. + +This isn't a problem for most Bitcoin transactions which are designed to +be added to the block chain immediately. But it does become a problem +when the output from a transaction is spent before that transaction is +added to the block chain. + +Bitcoin developers have been working to reduce transaction malleability +among standard transaction types, but a complete fix is still only in +the planning stages. At present, new transactions should not depend on +previous transactions which have not been added to the block chain yet, +especially if large amounts of satoshis are at stake. + +Transaction malleability also affects payment tracking. Bitcoin Core's +RPC interface lets you track transactions by their txid---but if that +txid changes because the transaction was modified, it may appear that +the transaction has disappeared from the network. + +Current best practices for transaction tracking dictate that a +transaction should be tracked by the transaction outputs (UTXOs) it +spends as inputs, as they cannot be changed without invalidating the +transaction. + + + +Best practices further dictate that if a transaction does seem to +disappear from the network and needs to be reissued, that it be reissued +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/_includes/ref_core_rpcs-abcdefg.md b/_includes/ref_core_rpcs-abcdefg.md new file mode 100644 index 00000000..c339fc32 --- /dev/null +++ b/_includes/ref_core_rpcs-abcdefg.md @@ -0,0 +1,3133 @@ +#### addmultisigaddress + +~~~ +addmultisigaddress [account] +~~~ + +{% autocrossref %} + +Add a P2SH multisig address to the wallet. + +Related RPCs: `createmultisig` + +{% endautocrossref %} + +**Argument #1: Number Of Signatures Required** + +{% autocrossref %} + +*Number; required:* the *minimum* (*m*) number of signatures required to +spend satoshis sent to this m-of-n P2SH multisig script. + +{% endautocrossref %} + +~~~ + +~~~ + +**Argument #2: Full Public Keys, Or Addresses For Known Public Keys** + +{% autocrossref %} + +*String; required:* A JSON array of hex-encoded public *keys* or *addresses* +for public keys known to this Bitcoin Core instance. The multisig +script can only use full (unhashed) public keys, so you generally must +provide public keys for any address not known to this wallet. + +{% endautocrossref %} + +~~~ +[ + "" + ,[...] +] +~~~ + +**Argument #3: Account Name** + + +{% autocrossref %} +*String; optional:* The name of an *account* in the wallet which will +store the address. + +{% endautocrossref %} + +~~~ +"" +~~~ + + +**Result: A P2SH Address Printed And Stored In The Wallet** + +{% autocrossref %} + +*String:* a hash of the P2SH multisig redeemScript, which is also stored +in the wallet so Bitcoin Core can monitor the network and block chain +for transactions sent to that address (which will be displayed in the +wallet as spendable balances). + +{% endautocrossref %} + + +**Example** + +{% autocrossref %} + +Adding a 2-of-3 P2SH multisig address to the "test account" by mixing +two P2PH addresses and one full public key: + +{% endautocrossref %} + +~~~ +> bitcoin-cli -testnet addmultisigaddress \ + 2 \ + ''' + [ + "mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ", + "02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f", + "mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG" + ] + ''' \ + 'test account' +~~~ + +Result: + +~~~ +2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq +~~~ + +{% autocrossref %} + +(New P2SH multisig address also stored in wallet.) + +{% endautocrossref %} + + + + + +#### addnode + +~~~ +addnode : +~~~ + +{% autocrossref %} + +Attempts add or remove a node from the addnode list, +or try a connection to a node once. + +{% endautocrossref %} + +**Argument #1: IP Address And Port Of Node** + +{% autocrossref %} + +*String, required:* the colon-delimited IP address and port of the node to add, remove, or +connect to. + +{% endautocrossref %} + +**Argument #2: Add Or Remove The Node, Or Try Once To Connect** + +{% autocrossref %} + +*String, required:* whether to *add* or *remove* the node to the list of +known nodes. This does not necessarily mean that a connection to the +node will be established. To attempt to establish a connection +immediately, use *onetry*. + +{% endautocrossref %} + +**Return: Empty Or Error** + +{% autocrossref %} + +Will not return any data if the node is added or if *onetry* is used +(even if the connection attempt fails). Will return an error if you try +removing an unknown node. + +{% endautocrossref %} + +**Example** + +{% autocrossref %} + +Try connecting to the following node. + +{% endautocrossref %} + +~~~ +> bitcoin-cli -testnet addnode 68.39.150.9:18333 onetry +~~~ + + +#### backupwallet + +~~~ +backupwallet +~~~ + +{% autocrossref %} + +Safely copies `wallet.dat` to destination, which can be a directory or a +path with filename. + +{% endautocrossref %} + +**Argument #1: Destination Directory Or Filename** + +{% autocrossref %} + +*String, required:* a directory or filename. If a directory, a file +named `wallet.dat` will be created or overwritten. If a filename, a file +of that name will be created or overwritten. + +{% endautocrossref %} + +**Return: Empty Or Error** + +{% autocrossref %} + +Nothing will be returned on success. If the file couldn't be created or +written, an error will be returned. + +{% endautocrossref %} + +**Example** + +~~~ +> bitcoin-cli -testnet backupwallet /tmp/backup.dat +~~~ + + +#### createmultisig + +~~~ +createmultisig +~~~ + +{% autocrossref %} + +Creates a multi-signature address. + +Related RPCs: `addmultisigaddress` + +{% endautocrossref %} + +**Argument #1: Number Of Signatures Required** + +{% autocrossref %} + +*Number; required:* the *minimum* (*m*) number of signatures required to +spend satoshis sent to this m-of-n multisig script. + +{% endautocrossref %} + +~~~ + +~~~ + +**Argument #2: Full Public Keys, Or Addresses For Known Public Keys** + +{% autocrossref %} + +*String; required:* A JSON array of hex-encoded public *keys* or *addresses* +for public keys known to this Bitcoin Core instance. The multisig +script can only use full (unhashed) public keys, so you generally must +provide public keys for any address not known to this wallet. + +{% endautocrossref %} + +~~~ +[ + "" + ,[...] +] +~~~ + +**Result: Address And Hex-Encoded RedeemScript** + +{% autocrossref %} + +*String:* JSON object with the P2SH *address* and hex-encoded *redeemScript*. + +{% endautocrossref %} + +~~~ +{ + "address":"", + "redeemScript":"" +} +~~~ + +**Example** + +{% autocrossref %} + +Creating a 2-of-3 P2SH multisig address by mixing two P2PH addresses and +one full public key: + +{% endautocrossref %} + +~~~ +> bitcoin-cli -testnet createmultisig 2 ''' + [ + "mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ", + "02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f", + "mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG" + ] + ''' +~~~ + +{% autocrossref %} + +Result (redeemScript wrapped): + +{% endautocrossref %} + +~~~ +{ + "address" : "2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq", + "redeemScript" : "522103ede722780d27b05f0b1169efc90fa15a601a32\ + fc6c3295114500c586831b6aaf2102ecd2d250a76d20\ + 4011de6bc365a56033b9b3a149f679bc17205555d3c2\ + b2854f21022d609d2f0d359e5bc0e5d0ea20ff9f5d33\ + 96cb5b1906aa9c56a0e7b5edc0c5d553ae" +} +~~~ + + + + +#### createrawtransaction + +~~~ +createrawtransaction +~~~ + +{% autocrossref %} + +Create an unsigned transaction in hex rawtransaction format that spends a +previous output to an new output with a P2PH or P2SH address. The +transaction is not stored in the wallet or transmitted to the network. + + +**Argument #1: References To Previous Outputs** + +*String; required:* A JSON array of JSON objects. Each object in the +array references a previous output by its *txid* (string; required) and +output index number, called *vout* (number; required). + +{% endautocrossref %} + +~~~ +[ + { + "txid":"", + "vout": + } + ,[...] +] +~~~ + +**Argument #2: P2PH Or P2SH Addresses For New Outputs** + +{% autocrossref %} + +*String; required:* A JSON object with P2PH or P2SH addresses to pay as +keys and the amount to pay each address as its value (number; required) +in decimal bitcoins. + +{% endautocrossref %} + +~~~ +{ + "
": . + ,[...] +} +~~~ + +**Result: Unsigned Raw Transaction (In Hex)** + +{% autocrossref %} + +*String:* The resulting unsigned transaction in hex-encoded +rawtransaction format, or a JSON error if any value provided was invalid. + +{% endautocrossref %} + +**Example** + +~~~ +> bitcoin-cli -testnet createrawtransaction ''' + [ + { + "txid":"5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589", + "vout":0 + } + ] + ''' ''' + { + "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.1 + } +'''' +~~~ + +Result: + +~~~ +010000000189957b01aed596d3b361b576234eaeed3249246f14562d6bc60851\ +66cd247d5a0000000000ffffffff0180969800000000001976a9140dfc8bafc8\ +419853b34d5e072ad37d1a5159f58488ac00000000 +~~~ + + + +#### decoderawtransaction + +~~~ +decoderawtransaction +~~~ + +{% autocrossref %} + +Decode a rawtransaction format hex string into a JSON object +representing the transaction. + +{% endautocrossref %} + +**Argument: RawTransaction Hex** + +{% autocrossref %} + +*String; required:* a complete transaction in rawtransaction format hex. + +{% endautocrossref %} + +**Result: JSON Object** + +{% autocrossref %} + +A JSON object describing the the transaction is returned. The object is +described in parts below. + +{% endautocrossref %} + +~~~ +{ + "txid" : "", + "version" : , + "locktime" : , +~~~ + +{% autocrossref %} + +The transaction identifier (*txid*), the transaction *version* number, +and the *locktime*. + +{% endautocrossref %} + +~~~ + "vin" : [ + { + "txid": "", + "vout": , + "scriptSig": { + "asm": "