mirror of
https://github.com/seigler/dash-docs
synced 2025-07-28 10:16:15 +00:00
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
This commit is contained in:
David Harding
parent
82378ddcb4
commit
ffde087f02
90 changed files with 13524 additions and 0 deletions
242
_includes/guide_block_chain.md
Normal file
242
_includes/guide_block_chain.md
Normal file
|
|
@ -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 %}
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 <span
|
||||
class="math">2<sup>256</sup> − 1</span>, you can prove that you
|
||||
tried up to two combinations by producing a hash value less than <span
|
||||
class="math">2<sup>256</sup> − 1</span>.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 %}
|
||||
288
_includes/guide_contracts.md
Normal file
288
_includes/guide_contracts.md
Normal file
|
|
@ -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<!--noref--> 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 %}
|
||||
|
||||
<!-- SOMEDAY: try to rewrite using a more likely real-world example without
|
||||
making the text or illustration more complicated -->
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 %}
|
||||
62
_includes/guide_intro.md
Normal file
62
_includes/guide_intro.md
Normal file
|
|
@ -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`<!--noref--> with each program or add
|
||||
`testnet=1`<!--noref--> to your `bitcoin.conf` file. To get
|
||||
free satoshis for testing, use [Piotr Piasecki's testnet faucet][].
|
||||
Testnet is a public resource provided for free by members of the
|
||||
community, so please don't abuse it.
|
||||
|
||||
You can speed up development further using the [regression test mode][]
|
||||
which creates a new testnet local to your computer. This regtest mode
|
||||
will let you generate blocks almost instantly with a RPC command so you
|
||||
can generate your own satoshis and add transactions to the block chain
|
||||
immediately.
|
||||
|
||||
* `bitcoin-qt` provides a combination full Bitcoin peer and wallet
|
||||
frontend. From the Help menu, you can access a console where you can
|
||||
enter the RPC commands used throughout this document.
|
||||
|
||||
* `bitcoind` is more useful for programming: it provides a full peer
|
||||
which you can interact with through RPCs to port 8332 (or 18332
|
||||
for testnet).
|
||||
|
||||
* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the
|
||||
command line. For example, `bitcoin-cli help`
|
||||
|
||||
All three programs get settings from `bitcoin.conf` in the `Bitcoin`
|
||||
application directiory:
|
||||
|
||||
* Windows: `%APPDATA%\Bitcoin\`
|
||||
|
||||
* OSX: `$HOME/Library/Application Support/Bitcoin/`
|
||||
|
||||
* Linux: `$HOME/.bitcoin/`
|
||||
|
||||
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 %}
|
||||
202
_includes/guide_mining.md
Normal file
202
_includes/guide_mining.md
Normal file
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
<!-- SOMEDAY: describe p2pool -->
|
||||
|
||||
**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 %}
|
||||
1291
_includes/guide_payment_processing.md
Normal file
1291
_includes/guide_payment_processing.md
Normal file
File diff suppressed because it is too large
Load diff
664
_includes/guide_transactions.md
Normal file
664
_includes/guide_transactions.md
Normal file
|
|
@ -0,0 +1,664 @@
|
|||
## Transactions
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
<!-- reference tx (made by Satoshi in block 170):
|
||||
bitcoind decoderawtransaction $( bitcoind getrawtransaction f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16 )
|
||||
-->
|
||||
|
||||
<!-- SOMEDAY: we need more terms than just output/input to denote the
|
||||
various ways the outputs/inputs are used, such as "prevout", "nextout",
|
||||
"curout", "curin", "nextin". (Is there any use for "previn"?) Someday,
|
||||
when I'm terribly bored, I should rewrite this whole transaction section
|
||||
to use those terms and then get feedback to see if it actually helps. -harding -->
|
||||
|
||||
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 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
<!-- Editors: from here on I will typically use the terms "pubkey hash"
|
||||
and "full public key" to provide quick differentiation between the
|
||||
different states of a public key and to help the text better match the
|
||||
space-constrained diagrams where "public-key hash" wouldn't fit. -harding -->
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 <PubkeyHash> 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 %}
|
||||
|
||||
~~~
|
||||
<Sig> <PubKey> OP_DUP OP_HASH160 <PubkeyHash> 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.
|
||||
|
||||
<!-- Editors: please do not substitute for the words push or pop in
|
||||
sections about stacks. These are programming terms. Also "above",
|
||||
"below", "top", and "bottom" are commonly used relative directions or
|
||||
locations in stack descriptions. -harding -->
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
* 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 <PubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
|
||||
scriptSig: <sig> <pubkey>
|
||||
~~~
|
||||
|
||||
{% 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 <redeemscripthash> OP_EQUAL
|
||||
scriptSig: <sig> [sig] [sig...] <redeemscript>
|
||||
~~~
|
||||
|
||||
{% 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: <m> <pubkey> [pubkey] [pubkey...] <n> OP_CHECKMULTISIG
|
||||
scriptSig: OP_0 <sig> [sig] [sig...]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Although it’s not a separate transaction type, this is a P2SH multisig with 2-of-3:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
script: OP_HASH160 <redeemscripthash> OP_EQUAL
|
||||
redeemScript: <OP_2> <pubkey> <pubkey> <pubkey> <OP_3> OP_CHECKMULTISIG
|
||||
scriptSig: OP_0 <sig> <sig> <redeemscript>
|
||||
~~~
|
||||
|
||||
{% 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: <pubkey> OP_CHECKSIG
|
||||
scriptSig: <sig>
|
||||
~~~
|
||||
|
||||
{% 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 <data>
|
||||
(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.
|
||||
|
||||
<!-- TODO: describe useful combinations maybe using a 3x3 grid;
|
||||
do something similar for the multisig section with different hashtypes
|
||||
between different sigs -->
|
||||
|
||||
<!-- TODO: add to the technical section details about what the different
|
||||
hash types sign, including the procedure for inserting the subscript -->
|
||||
|
||||
{% 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.
|
||||
|
||||
<!-- TODO: check: 50 KB or 50 KiB? Not that transactors care... -->
|
||||
|
||||
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.
|
||||
|
||||
<!-- TODO/harding: The paragraph above needs practical advice about how
|
||||
to do that. I'll need to find some time to look at somebody's wallet
|
||||
code. -harding -->
|
||||
|
||||
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 %}
|
||||
|
||||
3133
_includes/ref_core_rpcs-abcdefg.md
Normal file
3133
_includes/ref_core_rpcs-abcdefg.md
Normal file
File diff suppressed because it is too large
Load diff
1090
_includes/ref_core_rpcs-hijklmn.md
Normal file
1090
_includes/ref_core_rpcs-hijklmn.md
Normal file
File diff suppressed because it is too large
Load diff
872
_includes/ref_core_rpcs-opqrst.md
Normal file
872
_includes/ref_core_rpcs-opqrst.md
Normal file
|
|
@ -0,0 +1,872 @@
|
|||
#### ping
|
||||
|
||||
~~~
|
||||
ping
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Requests that a ping be sent to all other nodes, to measure ping time.
|
||||
Results provided in `getpeerinfo` pingtime and pingwait fields as
|
||||
decimal seconds. Ping command is handled in queue with all other
|
||||
commands, so it measures processing backlog, not just network ping.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
~~~
|
||||
bitcoin-cli -testnet ping
|
||||
~~~
|
||||
|
||||
(Success: no result printed.)
|
||||
|
||||
|
||||
#### sendfrom
|
||||
|
||||
~~~
|
||||
sendfrom <account> <address> <amount> [confirmations] [comment] [label]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Spend an amount from an account to a bitcoin address.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: From Account**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String, required:* the name of the account from which to spend the
|
||||
funds. Use "" for the default account.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: To Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String, required:* the address to which the funds should be
|
||||
spent. Use "" for the default account.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #3: Amount To Spend**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; required:* the amount to spend in decimal bitcoins.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #4: Minimum Confirmations**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; optional:* the minimum number of confirmations an incoming
|
||||
transaction must have before it will be spent. Previously spent UTXOs
|
||||
are not included regardless of the number of confirmations. Default is
|
||||
1; use 0 to spend unconfirmed transactions.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #5: A Comment**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* a comment to associate with this transaction.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #6: A Label**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* the label (name) to give the recipient.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: TXID**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
A txid for the transaction created.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Spend 0.1 bitcoins from the account "doc test" to the address indicated below
|
||||
using only UTXOs with at least six confirmations, giving the
|
||||
transaction the comment "Example spend" and labeling the spender
|
||||
"Example.com":
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
bitcoin-cli -testnet sendfrom "doc test" \
|
||||
mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \
|
||||
0.1 \
|
||||
6 \
|
||||
"Example spend" \
|
||||
"Example.com"
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
ca7cb6a5ffcc2f21036879493db4530c0ce9b5bff9648f9a3be46e2dfc8e0166
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### sendmany
|
||||
|
||||
~~~
|
||||
sendmany <account> <addresses & amounts> [confirmations] [memo]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Create and broadcast a transaction which spends outputs to multiple addresses.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: Account From Which The Satoshis Should Be Sent**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the wallet account from which the funds should be
|
||||
withdrawn. Can be "" for the default account.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: The Output Address/Amount Pairs**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* a JSON object with addresses as keys and amounts as values.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
{
|
||||
"<address>":<amount in decimal bitcoins>
|
||||
,[...]
|
||||
}
|
||||
~~~
|
||||
|
||||
**Argument #3: The Minimum Number Of Confirmations For Inputs**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; optional:* the minimum number of confirmations an previously-received
|
||||
output must have before it will be spent. The default is 1
|
||||
confirmation.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #4: A Memo**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String, optional:* a memo to be recorded with this transaction for
|
||||
record-keeping purposes. The memo is not included in the transaction.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: A Transaction Identifier**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String:* a transaction identifier (txid) for the transaction created
|
||||
and broadcast to the peer-to-peer network.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
From the account *test1*, send 0.1 bitcoins to the first address and 0.2
|
||||
bitcoins to the second address, with a memo of "Example Transaction".
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet sendmany \
|
||||
"test1" \
|
||||
'''
|
||||
{
|
||||
"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN": 0.1,
|
||||
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.2
|
||||
} ''' \
|
||||
6 \
|
||||
"Example Transaction"
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e
|
||||
~~~
|
||||
|
||||
|
||||
#### sendrawtransaction
|
||||
|
||||
~~~
|
||||
sendrawtransaction <hex> [true|false]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Broadcasts transaction in rawtransaction format to the peer-to-peer network.
|
||||
|
||||
See also: `createrawtransaction` and `signrawtransaction`
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: Raw Transaction**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* a fully-signed transaction in rawtransaction format
|
||||
(hex).
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: Whether To Allow High Fees**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Boolean; optional:* whether or not to allow the transaction to have a
|
||||
high transaction fee. Transaction fees are the difference between the
|
||||
sum of the inputs and the sum of the outputs, so a raw transaction which
|
||||
accidentally leaves off a change output, for example, can have a
|
||||
transaction fee dozens or hundreds of times larger than the network
|
||||
norm. If *true* is specified, that will be allowed. If *false* (the
|
||||
default), the transaction will be rejected with an informative error
|
||||
message.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: A TXID Or Error Message**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
If successful, the transaction's txid (hash) will be returned. If
|
||||
unsuccessful, an error message will be returned.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Examples**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Create and sign a transaction spending over 0.2 bitcoins as fees:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet signrawtransaction $(
|
||||
bitcoin-cli -testnet createrawtransaction '''
|
||||
[
|
||||
{
|
||||
"txid": "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",
|
||||
"vout": 0
|
||||
}
|
||||
]''' '''
|
||||
{
|
||||
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.1
|
||||
}'''
|
||||
)
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
{
|
||||
"hex" : "01000000011e48dee8b82c1cb03ba63998660b7bff269b70ba9\
|
||||
b23ead268afa56bbf0c7cef000000006b4830450221009c711c\
|
||||
e4df4cd8e22a10016ff6098e799f081e3a1706a9c0df14eeeb8\
|
||||
6c31bb302206323d29ab4f3138371df7b7bb794bb7c6a5e7e40\
|
||||
161e98b5c873f892d319d5230121027ce4f9db9f237fc75e420\
|
||||
742320c7df3b4ca95c44b6bc715400930f24870b2b1ffffffff\
|
||||
0180969800000000001976a9140dfc8bafc8419853b34d5e072\
|
||||
ad37d1a5159f58488ac00000000",
|
||||
"complete" : true
|
||||
}
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Now attempt to broadcast it:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet sendrawtransaction 01000000011e48dee8b82c\
|
||||
1cb03ba63998660b7bff269b70ba9b23ead268afa56bbf0c7cef00000000\
|
||||
6b4830450221009c711ce4df4cd8e22a10016ff6098e799f081e3a1706a9\
|
||||
c0df14eeeb86c31bb302206323d29ab4f3138371df7b7bb794bb7c6a5e7e\
|
||||
40161e98b5c873f892d319d5230121027ce4f9db9f237fc75e420742320c\
|
||||
7df3b4ca95c44b6bc715400930f24870b2b1ffffffff0180969800000000\
|
||||
001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac00000000
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
error: {"code":-22,"message":"TX rejected"}
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Allow high fees to force it to spend:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet sendrawtransaction 01000000[...]00000000 true
|
||||
~~~
|
||||
|
||||
Result (success):
|
||||
|
||||
~~~
|
||||
6d62d3f74be5ca614e32a2fb662deabe87ff95c7d90228cd8615da39cc824e34
|
||||
~~~
|
||||
|
||||
|
||||
#### sendtoaddress
|
||||
|
||||
~~~
|
||||
sendtoaddress <address> <amount> <memo> <label>
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Spend an amount to a given address. Encrypted wallets must be unlocked first.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* A bitcoin address which will received payment.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: Amount**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; required:* the amount in decimal bitcoins.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #3: Memo**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* the memo to give the transaction. This is not
|
||||
broadcast to the peer-to-peer network; it is stored in your wallet only.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #4: Label**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* the label to give the transaction. This is not
|
||||
broadcast to the peer-to-peer network; it is stored in your wallet only.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: TXID**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
If the spend is successful, the txid is returned.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Spend 0.1 bitcoins to the address below with the memo "sendtoadress
|
||||
example" and the label "Nemo From Example.com":
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet sendtoaddress mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6 \
|
||||
0.1 "sendtoaddress example" "Nemo From Example.com"
|
||||
~~~
|
||||
|
||||
~~~
|
||||
85a98fdf1529f7d5156483ad020a51b7f3340e47448cf932f470b72ff01a6821
|
||||
~~~
|
||||
|
||||
|
||||
#### setaccount
|
||||
|
||||
~~~
|
||||
setaccount <address> <account>
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Puts the given address in the given account.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: A Bitcoin Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the address to put in the account.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: An Account**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the account in which to put the address.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: None On Success**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
No result generated on success.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Put the address indicated below in the "doc test" account.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet setaccount \
|
||||
mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6 "doc test"
|
||||
~~~
|
||||
|
||||
(Success: no result displayed.)
|
||||
|
||||
|
||||
|
||||
|
||||
#### setgenerate
|
||||
|
||||
~~~
|
||||
setgenerate <true|false> [processors]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Enable or disable hashing to attempt to find the next block.
|
||||
|
||||
See also: `getgenerate`
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: Whether To Enable Or Disable Generation**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Boolean; required:* to enable generation, *true*; to disable, *false*.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: The Number Of Processors To Use**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; optional:* the number of logical processors to use. Defaults
|
||||
to 1; use -1 to use all available processors.
|
||||
|
||||
*Note:* in regtest mode, this argument will automatically create that
|
||||
number of blocks. See example below.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: None On Success**
|
||||
|
||||
No result on success.
|
||||
|
||||
**Examples**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Enable generation using two logical processors (on this machine, two
|
||||
cores of one physical processor):
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet setgenerate true 2
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
(Success: no result displayed. Process manager shows 200% CPU usage.)
|
||||
|
||||
Using regtest mode, generate 101 blocks (enough to be able to spend the
|
||||
coinbase transaction of the first block generated):
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -regtest setgenerate true 101
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
(Success: no result displayed. Wallet balance shows 50 bitcoins available.)
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
|
||||
|
||||
|
||||
#### settxfee
|
||||
|
||||
~~~
|
||||
settxfee amount
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Set the transaction fee per kilobyte.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument: Amount**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; required:* the transaction fee in decimal bitcoins per kilobyte.
|
||||
Will be rounded up to the nearest satoshi (0.00000001).
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: True Or False**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*True* if successful.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Set the transaction fee per kilobyte to 100,000 satoshis (1 millibit).
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet settxfee 0.00100000
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
true
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
#### signmessage
|
||||
|
||||
~~~
|
||||
signmessage <address> <message>
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Sign a message with the private key of an address. Encrypted wallets
|
||||
must be unlocked first.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the Bitcoin address corresponding to the private key
|
||||
which should be used to sign the message.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: Message**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* The message to sign.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: Message Signature**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
The signature of the message encoded in base64.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Sign a the message "Hello, World!" using the following address:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet signmessage mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \
|
||||
'Hello, World!'
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
IOGreqb/7UgD1ifcojESd32ZJgH5RGzUXitmbl6ZbdenSmitipWoLSi73TskmLY7zhcD662bTw3RHoYQl/dOAhE=
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
#### signrawtransaction
|
||||
|
||||
~~~
|
||||
signrawtransaction <raw transaction hex> [previous transactions] [private keys] [sighashtype]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Sign inputs of a transaction in rawtransaction format using private keys
|
||||
stored in the wallet or provided in the call.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: The Transaction To Sign**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the transaction to sign in rawtransaction format
|
||||
(hex).
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: P2SH Transaction Dependencies**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* A JSON array of JSON objects. Each object contains
|
||||
details about an unknown-to-this-node P2SH transaction that this transaction
|
||||
depends upon.
|
||||
|
||||
Each previous P2SH transaction must include its *txid* in hex, output
|
||||
index number (*vout*), public key (*scriptPubKey*) in hex, and
|
||||
*redeemScript* in hex.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
|
||||
~~~
|
||||
[
|
||||
{
|
||||
"txid":"<txid>",
|
||||
"vout":<output index number>,
|
||||
"scriptPubKey": "<scriptPubKey in hex>",
|
||||
"redeemScript": "<redeemScript in hex>"
|
||||
}
|
||||
,[...]
|
||||
]
|
||||
~~~
|
||||
|
||||
**Argument #3: Private Keys For Signing**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* A JSON array of base58check-encoded private keys to use
|
||||
for signing. If this argument is used, only the keys provided will be
|
||||
used to sign even if the wallet has other matching keys. If this
|
||||
argument is omitted, keys from the wallet will be used.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
[
|
||||
"<private key in base58check hex>"
|
||||
,[...]
|
||||
]
|
||||
~~~
|
||||
|
||||
**Argument #4: Sighash Type**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String, optional:* The type of signature hash to use for all of the
|
||||
signatures performed. (You must use separate calls to
|
||||
`signrawtransaction` if you want to use different sighash types for
|
||||
different signatures.)
|
||||
|
||||
The allowed values are *ALL*, *NONE*,
|
||||
*SINGLE*, *ALL|ANYONECANPAY*, *NONE|ANYONECANPAY*,
|
||||
and *SINGLE|ANYONECANPAY*.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
|
||||
**Result: Signed Transaction**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String:* a JSON object containing the transaction in *hex* with as many
|
||||
signatures as could be applied and a *complete* key indicating whether
|
||||
or not the the transaction is fully signed (0 indicates it is not
|
||||
complete).
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
{
|
||||
"hex": "<signed raw transaction hex>",
|
||||
"complete": <0|1>
|
||||
}
|
||||
~~~
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Sign the hex generated in the example section for the `rawtransaction`
|
||||
RPC:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet signrawtransaction 010000000189957b01aed5\
|
||||
96d3b361b576234eaeed3249246f14562d6bc6085166cd247d\
|
||||
5a0000000000ffffffff0180969800000000001976a9140dfc\
|
||||
8bafc8419853b34d5e072ad37d1a5159f58488ac00000000
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
{
|
||||
"hex" : "010000000189957b01aed596d3b361b576234eaeed3249246f145\
|
||||
62d6bc6085166cd247d5a000000006b483045022100c7a034fd7d\
|
||||
990b8a2bfba45fde44cae40b5ffbe42c5cf7d8143bfe317bdef3f\
|
||||
10220584e52f59b6a46d688322d65178efe83972a8517c9479630\
|
||||
6d40083af5b807c901210321eeeb46fd878ce8e62d5e0f408a0ea\
|
||||
b41d7c3a7872dc836ce360439536e423dffffffff018096980000\
|
||||
0000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58\
|
||||
488ac00000000",
|
||||
"complete" : true
|
||||
}
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### stop
|
||||
|
||||
~~~
|
||||
stop
|
||||
~~~
|
||||
|
||||
Stop the Bitcoin Core server.
|
||||
|
||||
**Example**
|
||||
|
||||
~~~
|
||||
bitcoin-cli -testnet stop
|
||||
~~~
|
||||
|
||||
(Success: no result printed but `bitcoind` shutdown.)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### submitblock
|
||||
|
||||
~~~
|
||||
submitblock <new block> [extra parameters]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Attempts to broadcast a new block to network. Extra parameters are ignored
|
||||
by Bitcoin Core but may be used by mining pools or other programs.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: The New Block In Hex**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the hex-encoded block data to broadcast to the
|
||||
peer-to-peer network.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: Extra Parameters**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; optional:* A JSON object containing extra parameters for
|
||||
mining pools and other software, such as a work identifier (workid).
|
||||
The extra parameters will not be broadcast to the network.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
{
|
||||
"<key>" : "<value>"
|
||||
}
|
||||
~~~
|
||||
|
||||
**Result: None**
|
||||
|
||||
No result printed if successful. An error message if failed.
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Submit the following block with the workid, "test".
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet submitblock 02000000df11c014a8d798395b505\
|
||||
9c722ebdf3171a4217ead71bf6e0e99f4c7000000004a6f6a2\
|
||||
db225c81e77773f6f0457bcb05865a94900ed11356d0b75228\
|
||||
efb38c7785d6053ffff001d005d43700101000000010000000\
|
||||
00000000000000000000000000000000000000000000000000\
|
||||
0000000ffffffff0d03b477030164062f503253482ffffffff\
|
||||
f0100f9029500000000232103adb7d8ef6b63de74313e0cd4e\
|
||||
07670d09a169b13e4eda2d650f529332c47646dac00000000\
|
||||
'{ "workid": "test" }'
|
||||
~~~
|
||||
|
||||
299
_includes/ref_core_rpcs-uvwxyz.md
Normal file
299
_includes/ref_core_rpcs-uvwxyz.md
Normal file
|
|
@ -0,0 +1,299 @@
|
|||
#### validateaddress
|
||||
|
||||
~~~
|
||||
validateaddress <address>
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Return information about the given Bitcoin address.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument: An Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* A Bitcoin address.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: Information About The Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
A JSON object containing one or more values (the exact number depending
|
||||
on the information). The result of *isvalid* is always returned to
|
||||
indicated whether or not the address is valid. If it is valid, the
|
||||
validated *address* is returned plus *ismine* to indicate whether or not
|
||||
it belongs to this wallet and *account* to indicate which account it
|
||||
belongs to. If it's a P2SH address, *isscript* will be true. If it's a
|
||||
P2PH address, *pubkey* will contain the public key and *compressed* will
|
||||
indicate whether or not the pubkey/address is compressed.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
{
|
||||
"isvalid" : <true|false>,
|
||||
"address" : "<address>",
|
||||
"ismine" : <true|false>,
|
||||
"isscript" : <true|false>,
|
||||
"pubkey" : "<public key hex>",
|
||||
"iscompressed" : <true|false>,
|
||||
"account" : "<account>"
|
||||
}
|
||||
~~~
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Validate the following address from the wallet:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet validateaddress mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
{
|
||||
"isvalid" : true,
|
||||
"address" : "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe",
|
||||
"ismine" : true,
|
||||
"isscript" : false,
|
||||
"pubkey" : "03bacb84c6464a58b3e0a53cc0ba4cb3b82848cd7bed25a7724b3cc75d76c9c1ba",
|
||||
"iscompressed" : true,
|
||||
"account" : "test label"
|
||||
}
|
||||
~~~
|
||||
|
||||
|
||||
#### verifychain
|
||||
|
||||
~~~
|
||||
verifychain [throughness] [blocks]
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Verify the local blockchain database.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: Throughness**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; optional:* how thoroughly to check the database, from 0 to 4
|
||||
with 4 being the most through. Defaults to 3. <!-- TODO: what does each
|
||||
level do? -->
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: Number Of Blocks To Check**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*Number; optional:* check this number of the most recent blocks.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: Verified Or Not**
|
||||
|
||||
*True* if verified.
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Verify the most recent 10,000 blocks in the most through way:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet verifychain 4 10000
|
||||
~~~
|
||||
|
||||
Result (took 25 seconds on a generic PC laptop):
|
||||
|
||||
~~~
|
||||
true
|
||||
~~~
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### verifymessage
|
||||
|
||||
~~~
|
||||
verifymessage <address> <signature> <message>
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Verify a signed message.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: The Address**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the address corresponding to the private key used to
|
||||
create the signature.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: The Signature**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the signature provided in the same base64 format
|
||||
generated by `signmessage`.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #3: The Message**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*String; required:* the exact message which was signed.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result: True Or False**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
*True* if the message provided was signed by the private key corresponding to the
|
||||
address provided.
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Check the signature on the message created in the example for
|
||||
`signmessage`:
|
||||
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet verifymessage \
|
||||
mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \
|
||||
IOGreqb/7UgD1ifcojESd32ZJgH5RGzUXitmbl6ZbdenSmitipWoLSi73TskmLY7zhcD662bTw3RHoYQl/dOAhE= \
|
||||
'Hello, World!'
|
||||
~~~
|
||||
|
||||
Result:
|
||||
|
||||
~~~
|
||||
true
|
||||
~~~
|
||||
|
||||
|
||||
#### walletlock
|
||||
|
||||
~~~
|
||||
walletlock
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
Removes the wallet encryption key from memory, locking the wallet. After
|
||||
calling this method, you will need to call `walletpassphrase` again before
|
||||
being able to call any methods which require the wallet to be unlocked.
|
||||
{% endautocrossref %}
|
||||
|
||||
|
||||
**Return**
|
||||
|
||||
No return printed on success.
|
||||
|
||||
**Example**
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet walletlock
|
||||
~~~
|
||||
|
||||
(Success: nothing printed.)
|
||||
|
||||
|
||||
#### walletpassphrase
|
||||
|
||||
walletpassphrase <passphrase> <seconds>
|
||||
|
||||
{% autocrossref %}
|
||||
Stores the wallet decryption key in memory for the indicated number of
|
||||
seconds. Issuing the `walletpassphrase` command while the wallet is
|
||||
already unlocked will set a new unlock time that overrides the old one.
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: The Passphrase**
|
||||
|
||||
{% autocrossref %}
|
||||
*String; required:* the passphrase to unlock the encrypted wallet.
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #2: The Number Of Seconds To Leave The Wallet Unlocked**
|
||||
|
||||
{% autocrossref %}
|
||||
*Number; required:* The number of seconds after which the decryption key
|
||||
will be automatically deleted from memory.
|
||||
{% endautocrossref %}
|
||||
|
||||
**Result**
|
||||
|
||||
No result printed on success.
|
||||
|
||||
**Example**
|
||||
|
||||
{% autocrossref %}
|
||||
Unlock the wallet for 10 minutes (the passphrase is "test"):
|
||||
{% endautocrossref %}
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet walletpassphrase test 600
|
||||
~~~
|
||||
|
||||
(Success: no result printed.)
|
||||
|
||||
|
||||
|
||||
#### walletpassphrasechange
|
||||
|
||||
~~~
|
||||
walletpassphrasechange <old passphrase> <new passphrase>
|
||||
~~~
|
||||
|
||||
{% autocrossref %}
|
||||
Changes the wallet passphrase from 'old passphrase' to 'new passphrase'.
|
||||
{% endautocrossref %}
|
||||
|
||||
**Argument #1: The Old Passphrase**
|
||||
|
||||
*String; required:* the current passphrase.
|
||||
|
||||
**Argument #2: The New Passphrase**
|
||||
|
||||
*String; required:* the new passphrase.
|
||||
|
||||
**Result**
|
||||
|
||||
No result printed on success.
|
||||
|
||||
**Example**
|
||||
|
||||
Change the wallet passphrase from "test" to "example":
|
||||
|
||||
~~~
|
||||
> bitcoin-cli -testnet walletpassphrasechange test example
|
||||
~~~
|
||||
|
||||
(Success: no result printed.)
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue