Bitcoin Wiki - User contributions [en]

Script

2014-02-24T10:52:25Z

Michagogo: Scripts are not numbers.

Bitcoin uses a scripting system for [[transactions]]. [[Wikipedia:FORTH|Forth]]-like, Script is simple, stack-based, and processed from left to right. It is purposefully not Turing-complete, with no loops.

A script is essentially a list of instructions recorded with each transaction that describe how the next person wanting to spend the Bitcoins being transferred can gain access to them. The script for a typical Bitcoin transfer to destination Bitcoin address D simply encumbers future spending of the bitcoins with two things: the spender must provide
# a public key that, when hashed, yields destination address D embedded in the script, and
# a signature to show evidence of the private key corresponding to the public key just provided.

Scripting provides the flexibility to change the parameters of what's needed to spend transferred Bitcoins. For example, the scripting system could be used to require two private keys, or a combination of several, or even no keys at all.

A transaction is valid if nothing in the combined script triggers failure and the top stack item is true (non-zero). The party who originally ''sent'' the Bitcoins now being spent, dictates the script operations that will occur ''last'' in order to release them for use in another transaction. The party wanting to spend them must provide the input(s) to the previously recorded script that results in those operations occurring last leaving behind true (non-zero).

The stacks hold byte vectors. Byte vectors are interpreted as little-endian variable-length integers with the most significant bit determining the sign of the integer. Thus 0x81 represents -1. 0x80 is another representation of zero (so called negative 0). Byte vectors are interpreted as Booleans where False is represented by any representation of zero, and True is represented by any representation of non-zero.

== Words ==
This is a list of all Script words (commands/functions). Some of the more complicated opcodes are disabled out of concern that the client might have a bug in their implementation; if a transaction using such an opcode were to be included in the chain any fix would risk forking the chain.

True=1 and False=0.

=== Constants ===
When talking about scripts, these value-pushing words are usually omitted.

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_0, OP_FALSE
|0
|0x00
|Nothing.
|(empty value)
|An empty array of bytes is pushed onto the stack. (This is not a no-op: an item is added to the stack.)
|-
|N/A
|1-75
|0x01-0x4b
|(special)
|data
|The next ''opcode'' bytes is data to be pushed onto the stack
|-
|OP_PUSHDATA1
|76
|0x4c
|(special)
|data
|The next byte contains the number of bytes to be pushed onto the stack.
|-
|OP_PUSHDATA2
|77
|0x4d
|(special)
|data
|The next two bytes contain the number of bytes to be pushed onto the stack.
|-
|OP_PUSHDATA4
|78
|0x4e
|(special)
|data
|The next four bytes contain the number of bytes to be pushed onto the stack.
|-
|OP_1NEGATE
|79
|0x4f
|Nothing.
| -1
|The number -1 is pushed onto the stack.
|-
|OP_1, OP_TRUE
|81
|0x51
|Nothing.
|1
|The number 1 is pushed onto the stack.
|-
|OP_2-OP_16
|82-96
|0x52-0x60
|Nothing.
|2-16
|The number in the word name (2-16) is pushed onto the stack.
|}

=== Flow control ===

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_NOP
|97
|0x61
|Nothing
|Nothing
|Does nothing.
|-
|OP_IF
|99
|0x63
| colspan="2"|<expression> if [statements] [else [statements]]* endif
|If the top stack value is not 0, the statements are executed. The top stack value is removed.
|-
|OP_NOTIF
|100
|0x64
| colspan="2"|<expression> if [statements] [else [statements]]* endif
|If the top stack value is 0, the statements are executed. The top stack value is removed.
|-
|OP_ELSE
|103
|0x67
| colspan="2"|<expression> if [statements] [else [statements]]* endif
|If the preceding OP_IF or OP_NOTIF or OP_ELSE was not executed then these statements are and if the preceding OP_IF or OP_NOTIF or OP_ELSE was executed then these statements are not.
|-
|OP_ENDIF
|104
|0x68
| colspan="2"|<expression> if [statements] [else [statements]]* endif
|Ends an if/else block.
|-
|OP_VERIFY
|105
|0x69
|True / false
|Nothing / False
|'''Marks transaction as invalid''' if top stack value is not true. True is removed, but false is not.
|-
|OP_RETURN
|106
|0x6a
|Nothing
|Nothing
|'''Marks transaction as invalid'''.
|}

=== Stack ===

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_TOALTSTACK
|107
|0x6b
|x1
|(alt)x1
|Puts the input onto the top of the alt stack. Removes it from the main stack.
|-
|OP_FROMALTSTACK
|108
|0x6c
|(alt)x1
|x1
|Puts the input onto the top of the main stack. Removes it from the alt stack.
|-
|OP_IFDUP
|115
|0x73
|x
|x / x x
|If the top stack value is not 0, duplicate it.
|-
|OP_DEPTH
|116
|0x74
|Nothing
|<Stack size>
|Puts the number of stack items onto the stack.
|-
|OP_DROP
|117
|0x75
|x
|Nothing
|Removes the top stack item.
|-
|OP_DUP
|118
|0x76
|x
|x x
|Duplicates the top stack item.
|-
|OP_NIP
|119
|0x77
|x1 x2
|x2
|Removes the second-to-top stack item.
|-
|OP_OVER
|120
|0x78
|x1 x2
|x1 x2 x1
|Copies the second-to-top stack item to the top.
|-
|OP_PICK
|121
|0x79
|xn ... x2 x1 x0 <n>
|xn ... x2 x1 x0 xn
|The item ''n'' back in the stack is copied to the top.
|-
|OP_ROLL
|122
|0x7a
|xn ... x2 x1 x0 <n>
|... x2 x1 x0 xn
|The item ''n'' back in the stack is moved to the top.
|-
|OP_ROT
|123
|0x7b
|x1 x2 x3
|x2 x3 x1
|The top three items on the stack are rotated to the left.
|-
|OP_SWAP
|124
|0x7c
|x1 x2
|x2 x1
|The top two items on the stack are swapped.
|-
|OP_TUCK
|125
|0x7d
|x1 x2
|x2 x1 x2
|The item at the top of the stack is copied and inserted before the second-to-top item.
|-
|OP_2DROP
|109
|0x6d
|x1 x2
|Nothing
|Removes the top two stack items.
|-
|OP_2DUP
|110
|0x6e
|x1 x2
|x1 x2 x1 x2
|Duplicates the top two stack items.
|-
|OP_3DUP
|111
|0x6f
|x1 x2 x3
|x1 x2 x3 x1 x2 x3
|Duplicates the top three stack items.
|-
|OP_2OVER
|112
|0x70
|x1 x2 x3 x4
|x1 x2 x3 x4 x1 x2
|Copies the pair of items two spaces back in the stack to the front.
|-
|OP_2ROT
|113
|0x71
|x1 x2 x3 x4 x5 x6
|x3 x4 x5 x6 x1 x2
|The fifth and sixth items back are moved to the top of the stack.
|-
|OP_2SWAP
|114
|0x72
|x1 x2 x3 x4
|x3 x4 x1 x2
|Swaps the top two pairs of items.
|}

=== Splice ===

If any opcode marked as disabled is present in a script, it must abort and fail.

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_CAT
|126
|0x7e
|x1 x2
|out
|style="background:#D97171;"|Concatenates two strings. ''disabled.''
|-
|OP_SUBSTR
|127
|0x7f
|in begin size
|out
|style="background:#D97171;"|Returns a section of a string. ''disabled.''
|-
|OP_LEFT
|128
|0x80
|in size
|out
|style="background:#D97171;"|Keeps only characters left of the specified point in a string. ''disabled.''
|-
|OP_RIGHT
|129
|0x81
|in size
|out
|style="background:#D97171;"|Keeps only characters right of the specified point in a string. ''disabled.''
|-
|OP_SIZE
|130
|0x82
|in
|in size
|Returns the length of the input string.
|}

=== Bitwise logic ===

If any opcode marked as disabled is present in a script, it must abort and fail.

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_INVERT
|131
|0x83
|in
|out
|style="background:#D97171;"|Flips all of the bits in the input. ''disabled.''
|-
|OP_AND
|132
|0x84
|x1 x2
|out
|style="background:#D97171;"|Boolean ''and'' between each bit in the inputs. ''disabled.''
|-
|OP_OR
|133
|0x85
|x1 x2
|out
|style="background:#D97171;"|Boolean ''or'' between each bit in the inputs. ''disabled.''
|-
|OP_XOR
|134
|0x86
|x1 x2
|out
|style="background:#D97171;"|Boolean ''exclusive or'' between each bit in the inputs. ''disabled.''
|-
|OP_EQUAL
|135
|0x87
|x1 x2
|True / false
|Returns 1 if the inputs are exactly equal, 0 otherwise.
|-
|OP_EQUALVERIFY
|136
|0x88
|x1 x2
|True / false
|Same as OP_EQUAL, but runs OP_VERIFY afterward.
|}

=== Arithmetic ===

Note: Arithmetic inputs are limited to signed 32-bit integers, but may overflow their output.

If any input value for any of these commands is longer than 4 bytes, the script must abort and fail.
If any opcode marked as ''disabled'' is present in a script - it must also abort and fail.

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_1ADD
|139
|0x8b
|in
|out
|1 is added to the input.
|-
|OP_1SUB
|140
|0x8c
|in
|out
|1 is subtracted from the input.
|-
|OP_2MUL
|141
|0x8d
|in
|out
|style="background:#D97171;"|The input is multiplied by 2. ''disabled.''
|-
|OP_2DIV
|142
|0x8e
|in
|out
|style="background:#D97171;"|The input is divided by 2. ''disabled.''
|-
|OP_NEGATE
|143
|0x8f
|in
|out
|The sign of the input is flipped.
|-
|OP_ABS
|144
|0x90
|in
|out
|The input is made positive.
|-
|OP_NOT
|145
|0x91
|in
|out
|If the input is 0 or 1, it is flipped. Otherwise the output will be 0.
|-
|OP_0NOTEQUAL
|146
|0x92
|in
|out
|Returns 0 if the input is 0. 1 otherwise.
|-
|OP_ADD
|147
|0x93
|a b
|out
|a is added to b.
|-
|OP_SUB
|148
|0x94
|a b
|out
|b is subtracted from a.
|-
|OP_MUL
|149
|0x95
|a b
|out
|style="background:#D97171;"|a is multiplied by b. ''disabled.''
|-
|OP_DIV
|150
|0x96
|a b
|out
|style="background:#D97171;"|a is divided by b. ''disabled.''
|-
|OP_MOD
|151
|0x97
|a b
|out
|style="background:#D97171;"|Returns the remainder after dividing a by b. ''disabled.''
|-
|OP_LSHIFT
|152
|0x98
|a b
|out
|style="background:#D97171;"|Shifts a left b bits, preserving sign. ''disabled.''
|-
|OP_RSHIFT
|153
|0x99
|a b
|out
|style="background:#D97171;"|Shifts a right b bits, preserving sign. ''disabled.''
|-
|OP_BOOLAND
|154
|0x9a
|a b
|out
|If both a and b are not 0, the output is 1. Otherwise 0.
|-
|OP_BOOLOR
|155
|0x9b
|a b
|out
|If a or b is not 0, the output is 1. Otherwise 0.
|-
|OP_NUMEQUAL
|156
|0x9c
|a b
|out
|Returns 1 if the numbers are equal, 0 otherwise.
|-
|OP_NUMEQUALVERIFY
|157
|0x9d
|a b
|out
|Same as OP_NUMEQUAL, but runs OP_VERIFY afterward.
|-
|OP_NUMNOTEQUAL
|158
|0x9e
|a b
|out
|Returns 1 if the numbers are not equal, 0 otherwise.
|-
|OP_LESSTHAN
|159
|0x9f
|a b
|out
|Returns 1 if a is less than b, 0 otherwise.
|-
|OP_GREATERTHAN
|160
|0xa0
|a b
|out
|Returns 1 if a is greater than b, 0 otherwise.
|-
|OP_LESSTHANOREQUAL
|161
|0xa1
|a b
|out
|Returns 1 if a is less than or equal to b, 0 otherwise.
|-
|OP_GREATERTHANOREQUAL
|162
|0xa2
|a b
|out
|Returns 1 if a is greater than or equal to b, 0 otherwise.
|-
|OP_MIN
|163
|0xa3
|a b
|out
|Returns the smaller of a and b.
|-
|OP_MAX
|164
|0xa4
|a b
|out
|Returns the larger of a and b.
|-
|OP_WITHIN
|165
|0xa5
|x min max
|out
|Returns 1 if x is within the specified range (left-inclusive), 0 otherwise.
|}

=== Crypto ===

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Input
!Output
!Description
|-
|OP_RIPEMD160
|166
|0xa6
|in
|hash
|The input is hashed using RIPEMD-160.
|-
|OP_SHA1
|167
|0xa7
|in
|hash
|The input is hashed using SHA-1.
|-
|OP_SHA256
|168
|0xa8
|in
|hash
|The input is hashed using SHA-256.
|-
|OP_HASH160
|169
|0xa9
|in
|hash
|The input is hashed twice: first with SHA-256 and then with RIPEMD-160.
|-
|OP_HASH256
|170
|0xaa
|in
|hash
|The input is hashed two times with SHA-256.
|-
|OP_CODESEPARATOR
|171
|0xab
|Nothing
|Nothing
|All of the signature checking words will only match signatures to the data after the most recently-executed OP_CODESEPARATOR.
|-
|[[OP_CHECKSIG]]
|172
|0xac
|sig pubkey
|True / false
|The entire transaction's outputs, inputs, and script (from the most recently-executed OP_CODESEPARATOR to the end) are hashed. The signature used by OP_CHECKSIG must be a valid signature for this hash and public key. If it is, 1 is returned, 0 otherwise.
|-
|OP_CHECKSIGVERIFY
|173
|0xad
|sig pubkey
|True / false
|Same as OP_CHECKSIG, but OP_VERIFY is executed afterward.
|-
|OP_CHECKMULTISIG
|174
|0xae
|x sig1 sig2 ... <number of signatures> pub1 pub2 <number of public keys>
|True / False
|For each signature and public key pair, OP_CHECKSIG is executed. If more public keys than signatures are listed, some key/sig pairs can fail. All signatures need to match a public key. If all signatures are valid, 1 is returned, 0 otherwise. Due to a bug, one extra unused value is removed from the stack.
|-
|OP_CHECKMULTISIGVERIFY
|175
|0xaf
|x sig1 sig2 ... <number of signatures> pub1 pub2 ... <number of public keys>
|True / False
|Same as OP_CHECKMULTISIG, but OP_VERIFY is executed afterward.
|}

===Pseudo-words===
These words are used internally for assisting with transaction matching. They are invalid if used in actual scripts.
{| class="wikitable"
|-
!Word
!Opcode
!Hex
!Description
|-
|OP_PUBKEYHASH
|253
|0xfd
|Represents a public key hashed with OP_HASH160.
|-
|OP_PUBKEY
|254
|0xfe
|Represents a public key compatible with OP_CHECKSIG.
|-
|OP_INVALIDOPCODE
|255
|0xff
|Matches any opcode that is not yet assigned.
|}

=== Reserved words ===
Any opcode not assigned is also reserved. Using an unassigned opcode makes the transaction invalid.

{| class="wikitable"
|-
!Word
!Opcode
!Hex
!When used...
|-
|OP_RESERVED
|80
|0x50
|Transaction is invalid unless occuring in an unexecuted OP_IF branch
|-
|OP_VER
|98
|0x62
|Transaction is invalid unless occuring in an unexecuted OP_IF branch
|-
|OP_VERIF
|101
|0x65
|Transaction is invalid even when occuring in an unexecuted OP_IF branch
|-
|OP_VERNOTIF
|102
|0x66
|Transaction is invalid even when occuring in an unexecuted OP_IF branch
|-
|OP_RESERVED1
|137
|0x89
|Transaction is invalid unless occuring in an unexecuted OP_IF branch
|-
|OP_RESERVED2
|138
|0x8a
|Transaction is invalid unless occuring in an unexecuted OP_IF branch
|-
|OP_NOP1-OP_NOP10
|176-185
|0xb0-0xb9
|The word is ignored.
|}

== Scripts ==
This is a list of interesting scripts. Keep in mind that all constants actually use the data-pushing commands above. Note that there is a small number of standard script forms that are relayed from node to node; non-standard scripts are accepted if they are in a block, but nodes will not relay them.

=== Standard Transaction to Bitcoin address (pay-to-pubkey-hash) ===

scriptPubKey: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
scriptSig: <sig> <pubKey>

To demonstrate how scripts look on the wire, here is a raw scriptPubKey:
<pre> 76 A9 14
OP_DUP OP_HASH160 Bytes to push

89 AB CD EF AB BA AB BA AB BA AB BA AB BA AB BA AB BA AB BA 88 AC
Data to push OP_EQUALVERIFY OP_CHECKSIG</pre>

Note: scriptSig is in the input of the spending transaction and scriptPubKey is in the output of the previously unspent i.e. "available" transaction.

Here is how each word is processed:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
| <sig> <pubKey> OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Constants are added to the stack.
|-
|<sig> <pubKey> <pubKey>
| OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is duplicated.
|-
|<sig> <pubKey> <pubHashA>
|<pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is hashed.
|-
|<sig> <pubKey> <pubHashA> <pubKeyHash>
|OP_EQUALVERIFY OP_CHECKSIG
| Constant added.
|-
|<sig> <pubKey>
|OP_CHECKSIG
| Equality is checked between the top two stack items.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

=== Standard Generation Transaction (pay-to-pubkey) ===

OP_CHECKSIG is used directly without first hashing the public key. By default the reference implementation uses this form for coinbase payment, and scriptPubKeys of this transaction form are recognized as payments to user. The disadvantage of this transaction form is that the whole public key needs to be known in advance, implying longer payment addresses, and that it provides less protection in the event of a break in the ECDSA signature algorithm.

scriptPubKey: <pubKey> OP_CHECKSIG
scriptSig: <sig>

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
|<sig> <pubKey> OP_CHECKSIG
|scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_CHECKSIG
|Constants are added to the stack.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

=== Provably Unspendable/Prunable Outputs ===

The standard way to mark a transaction as provably unspendable is with a scriptPubKey of the following form:

scriptPubKey: OP_RETURN {zero or more ops}

OP_RETURN immediately marks the script as invalid, guaranteeing that no scriptSig exists that could possibly spend that output. Thus the output can be immediately pruned from the UTXO set even if it has not been spent. [http://blockexplorer.com/tx/eb31ca1a4cbd97c2770983164d7560d2d03276ae1aee26f12d7c2c6424252f29 eb31ca1a4cbd97c2770983164d7560d2d03276ae1aee26f12d7c2c6424252f29] is an example: it has a single output of zero value, thus giving the full 0.125BTC fee to the miner who mined the transaction without adding an entry to the UTXO set. You can also use OP_RETURN to add data to a transaction without the data ever appearing in the UTXO set, as seen in 1a2e22a717d626fc5db363582007c46924ae6b28319f07cb1b907776bd8293fc; [[P2Pool]] does this with the share chain hash txout in the coinbase of blocks it creates.

Note that this mechanism is not yet a standard transaction type, and thus will not be relayed by nodes on mainnet.

=== Anyone-Can-Spend Outputs ===

Conversely a transaction can be made spendable by anyone at all:

scriptPubKey: (empty)
scriptSig: OP_TRUE

With some software changes such transactions can be used as a way to donate funds to miners in addition to transaction fees: any miner who mines such a transaction can also include an additional one after it sending the funds to an address they control. This mechanism may be used in the future for [[fidelity bonds]] to sacrifice funds in a provable way.

Anyone-Can-Spend outputs are currently considered non-standard, and are not relayed on the P2P network.

=== Transaction puzzle ===

Transaction a4bfa8ab6435ae5f25dae9d89e4eb67dfa94283ca751f393c1ddc5a837bbc31b is an interesting puzzle.

scriptPubKey: OP_HASH256 6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000 OP_EQUAL
scriptSig: <data>

To spend the transaction you need to come up with some data such that hashing the data twice results in the given hash.

{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
|<data> OP_HASH256 <given_hash> OP_EQUAL
|
|-
|<data>
|OP_HASH256 <given_hash> OP_EQUAL
|scriptSig added to the stack.
|-
|<data_hash>
|<given_hash> OP_EQUAL
|The data is hashed.
|-
|<data_hash> <given_hash>
|OP_EQUAL
|The given hash is pushed to the stack.
|-
|true
|Empty.
|The hashes are compared, leaving true on the stack.
|}

This transaction was successfully spent by 09f691b2263260e71f363d1db51ff3100d285956a40cc0e4f8c8c2c4a80559b1. The required data happened to be the [[Genesis block]], and the given hash was the genesis block hash. Note that while transactions like this are fun, they are not secure, because they do not contain any signatures and thus any transaction attempting to spend them can be replaced with a different transaction sending the funds somewhere else.

==See Also==

* [[Transactions]]
* [[Contracts]]

[[Category:Technical]]
[[Category:Vocabulary]]

Miner fees

2014-01-30T23:13:42Z

Michagogo: /* Relaying */

[[File:fee.png|thumb|Receiving the fees from hundreds of transactions (0.44 BTC)]]
'''Transaction fees''' may be included with any transfer of bitcoins from one address to another. At the moment, many [[transactions]] are typically processed in a way where no fee is expected at all, but for transactions which draw coins from many bitcoin addresses and therefore have a large data size, a small transaction fee is usually expected.

The transaction fee is processed by and received by the bitcoin miner. When a new bitcoin block is generated with a successful hash, the information for all of the transactions is included with the block and all transaction fees are collected by that user creating the block, who is free to assign those fees to himself.

Transaction fees are voluntary on the part of the person making the bitcoin transaction, as the person attempting to make a transaction can include any fee or none at all in the transaction. On the other hand, nobody mining new bitcoins necessarily needs to accept the transactions and include them in the new block being created. The transaction fee is therefore an incentive on the part of the bitcoin user to make sure that a particular transaction will get included into the next block which is generated.

It is envisioned that over time the cumulative effect of collecting transaction fees will allow somebody creating new blocks to "earn" more bitcoins than will be mined from new bitcoins created by the new block itself. This is also an incentive to keep trying to create new blocks even if the value of the newly created block from the mining activity is zero in the far future.

==Reference Implementation==

The following sections describe the behavior of the [[Original Bitcoin client|reference implementation]] as of version 0.8.6. Earlier versions treated fees differently, as do other popular implementations (including possible later versions).

===Sending===

A transaction may be safely sent without fees if these conditions are met:

* It is smaller than 1,000 bytes.
* All outputs are 0.01 BTC or larger.
* Its priority is large enough (see the Technical Info section below)

Otherwise, the reference implementation will round up the transaction size to the next thousand bytes and add a fee of 0.1 mBTC (0.0001 BTC) per thousand bytes<ref>[http://bitcointalk.org/index.php?topic=219504.0 Default fee dropped in v0.8.2]</ref>. As an example, a fee of 0.1 mBTC (0.0001 BTC) would be added to a 746 byte transaction, and a fee of 0.2 mBTC (0.0002 BTC) would be added to a 1001 byte transaction.
Users may increase the default 0.0001 BTC/kB fee setting, but cannot control transaction fees for each transaction. Bitcoin-Qt does prompt the user to accept the fee before the transaction is sent (they may cancel the transaction if they are not willing to pay the fee).

Note that a typical transaction is 500 bytes, so the typical transaction fee for low-priority transactions is 0.1 mBTC (0.0001 BTC), regardless of the number of bitcoins sent.

===Including in Blocks===

This section describes how the reference implementation selects which transactions to put into new blocks, with default settings. All of the settings may be changed if a miner wants to create larger or smaller blocks containing more or fewer free transactions.

30,000 bytes in the block are set aside for the highest-priority transactions, regardless of transaction fee. Transactions are added highest-priority-first to this section of the block.

Then transactions that pay a fee of at least 0.0001 BTC/kb are added to the block, highest-fee transactions first, until the block is not more than 300,000 bytes big.

The remaining transactions remain in the miner's "memory pool", and may be included in later blocks if their priority or fee is large enough.

===Relaying===

The reference implementation's rules for relaying transactions across the peer-to-peer network are very similar to the rules for sending transactions, as a value of 0.0001 BTC is used to determine whether or not a transaction is considered "Free". However, the rule that all outputs must be 0.01 BTC or larger does not apply. To prevent "penny-flooding" denial-of-service attacks on the network, the reference implementation caps the number of free transactions it will relay to other nodes to (by default) 15 thousand bytes per minute.

===Settings===

{| class="wikitable"
|-
! Setting !! Default Value (units)
|-
| paytxfee || 0.0000 (BTC)
|-
| limitfreerelay || 15 (thousand bytes per minute)
|-
| mintxfee || 0.0001 (BTC)
|-
| blockmaxsize || 300000 (bytes)
|-
| blockminsize || 0 (bytes)
|-
| blockprioritysize || 30000 (bytes)
|}

==Technical info==

Transaction priority is calculated as a value-weighted sum of input age, divided by transaction size in bytes:
priority = sum(input_value_in_base_units * input_age)/size_in_bytes
Transactions need to have a priority above 57,600,000 to avoid the enforced limit (as of client version 0.3.21). This threshold is written in the code as COIN * 144 / 250, suggesting that the threshold represents a one day old, 1 btc coin (144 is the expected number of blocks per day) and a transaction size of 250 bytes.

So, for example, a transaction that has 2 inputs, one of 5 btc with 10 confirmations, and one of 2 btc with 3 confirmations, and has a size of 500bytes, will have a priority of
(500000000 * 10 + 200000000 * 3) / 500 = 11,200,000

==See Also==

* [[Free transaction relay policy]]
* [http://blockchain.info/charts/transaction-fees Transaction fee chart]

==References==
<references />

[[Category:Technical]]
[[Category:Vocabulary]]
[[Category:Mining]]
[[de:Transaktionsgebühren]]

Miner fees

2014-01-30T23:11:15Z

Michagogo: /* Reference Implementation */

[[File:fee.png|thumb|Receiving the fees from hundreds of transactions (0.44 BTC)]]
'''Transaction fees''' may be included with any transfer of bitcoins from one address to another. At the moment, many [[transactions]] are typically processed in a way where no fee is expected at all, but for transactions which draw coins from many bitcoin addresses and therefore have a large data size, a small transaction fee is usually expected.

The transaction fee is processed by and received by the bitcoin miner. When a new bitcoin block is generated with a successful hash, the information for all of the transactions is included with the block and all transaction fees are collected by that user creating the block, who is free to assign those fees to himself.

Transaction fees are voluntary on the part of the person making the bitcoin transaction, as the person attempting to make a transaction can include any fee or none at all in the transaction. On the other hand, nobody mining new bitcoins necessarily needs to accept the transactions and include them in the new block being created. The transaction fee is therefore an incentive on the part of the bitcoin user to make sure that a particular transaction will get included into the next block which is generated.

It is envisioned that over time the cumulative effect of collecting transaction fees will allow somebody creating new blocks to "earn" more bitcoins than will be mined from new bitcoins created by the new block itself. This is also an incentive to keep trying to create new blocks even if the value of the newly created block from the mining activity is zero in the far future.

==Reference Implementation==

The following sections describe the behavior of the [[Original Bitcoin client|reference implementation]] as of version 0.8.6. Earlier versions treated fees differently, as do other popular implementations (including possible later versions).

===Sending===

A transaction may be safely sent without fees if these conditions are met:

* It is smaller than 1,000 bytes.
* All outputs are 0.01 BTC or larger.
* Its priority is large enough (see the Technical Info section below)

Otherwise, the reference implementation will round up the transaction size to the next thousand bytes and add a fee of 0.1 mBTC (0.0001 BTC) per thousand bytes<ref>[http://bitcointalk.org/index.php?topic=219504.0 Default fee dropped in v0.8.2]</ref>. As an example, a fee of 0.1 mBTC (0.0001 BTC) would be added to a 746 byte transaction, and a fee of 0.2 mBTC (0.0002 BTC) would be added to a 1001 byte transaction.
Users may increase the default 0.0001 BTC/kB fee setting, but cannot control transaction fees for each transaction. Bitcoin-Qt does prompt the user to accept the fee before the transaction is sent (they may cancel the transaction if they are not willing to pay the fee).

Note that a typical transaction is 500 bytes, so the typical transaction fee for low-priority transactions is 0.1 mBTC (0.0001 BTC), regardless of the number of bitcoins sent.

===Including in Blocks===

This section describes how the reference implementation selects which transactions to put into new blocks, with default settings. All of the settings may be changed if a miner wants to create larger or smaller blocks containing more or fewer free transactions.

30,000 bytes in the block are set aside for the highest-priority transactions, regardless of transaction fee. Transactions are added highest-priority-first to this section of the block.

Then transactions that pay a fee of at least 0.0001 BTC/kb are added to the block, highest-fee transactions first, until the block is not more than 300,000 bytes big.

The remaining transactions remain in the miner's "memory pool", and may be included in later blocks if their priority or fee is large enough.

===Relaying===

The reference implementation's rules for relaying transactions across the peer-to-peer network are very similar to the rules for sending transactions, as a value of 0.0001 BTC is used to determine whether or not a transaction is considered "Free". To prevent "penny-flooding" denial-of-service attacks on the network, the reference implementation caps the number of free transactions it will relay to other nodes to (by default) 15 thousand bytes per minute.

===Settings===

{| class="wikitable"
|-
! Setting !! Default Value (units)
|-
| paytxfee || 0.0000 (BTC)
|-
| limitfreerelay || 15 (thousand bytes per minute)
|-
| mintxfee || 0.0001 (BTC)
|-
| blockmaxsize || 300000 (bytes)
|-
| blockminsize || 0 (bytes)
|-
| blockprioritysize || 30000 (bytes)
|}

==Technical info==

Transaction priority is calculated as a value-weighted sum of input age, divided by transaction size in bytes:
priority = sum(input_value_in_base_units * input_age)/size_in_bytes
Transactions need to have a priority above 57,600,000 to avoid the enforced limit (as of client version 0.3.21). This threshold is written in the code as COIN * 144 / 250, suggesting that the threshold represents a one day old, 1 btc coin (144 is the expected number of blocks per day) and a transaction size of 250 bytes.

So, for example, a transaction that has 2 inputs, one of 5 btc with 10 confirmations, and one of 2 btc with 3 confirmations, and has a size of 500bytes, will have a priority of
(500000000 * 10 + 200000000 * 3) / 500 = 11,200,000

==See Also==

* [[Free transaction relay policy]]
* [http://blockchain.info/charts/transaction-fees Transaction fee chart]

==References==
<references />

[[Category:Technical]]
[[Category:Vocabulary]]
[[Category:Mining]]
[[de:Transaktionsgebühren]]

Miner fees

2014-01-30T23:03:02Z

Michagogo: /* Reference Implementation */

[[File:fee.png|thumb|Receiving the fees from hundreds of transactions (0.44 BTC)]]
'''Transaction fees''' may be included with any transfer of bitcoins from one address to another. At the moment, many [[transactions]] are typically processed in a way where no fee is expected at all, but for transactions which draw coins from many bitcoin addresses and therefore have a large data size, a small transaction fee is usually expected.

The transaction fee is processed by and received by the bitcoin miner. When a new bitcoin block is generated with a successful hash, the information for all of the transactions is included with the block and all transaction fees are collected by that user creating the block, who is free to assign those fees to himself.

Transaction fees are voluntary on the part of the person making the bitcoin transaction, as the person attempting to make a transaction can include any fee or none at all in the transaction. On the other hand, nobody mining new bitcoins necessarily needs to accept the transactions and include them in the new block being created. The transaction fee is therefore an incentive on the part of the bitcoin user to make sure that a particular transaction will get included into the next block which is generated.

It is envisioned that over time the cumulative effect of collecting transaction fees will allow somebody creating new blocks to "earn" more bitcoins than will be mined from new bitcoins created by the new block itself. This is also an incentive to keep trying to create new blocks even if the value of the newly created block from the mining activity is zero in the far future.

==Reference Implementation==

The following sections describe the behavior of the [[Original Bitcoin client|reference implementation]] as of version 0.8.6. Earlier versions treated fees differently, as do other popular implementations.

===Sending===

A transaction may be safely sent without fees if these conditions are met:

* It is smaller than 1,000 bytes.
* All outputs are 0.01 BTC or larger.
* Its priority is large enough (see the Technical Info section below)

Otherwise, the reference implementation will round up the transaction size to the next thousand bytes and add a fee of 0.1 mBTC (0.0001 BTC) per thousand bytes<ref>[http://bitcointalk.org/index.php?topic=219504.0 Default fee dropped in v0.8.2]</ref>. As an example, a fee of 0.1 mBTC (0.0001 BTC) would be added to a 746 byte transaction, and a fee of 0.2 mBTC (0.0002 BTC) would be added to a 1001 byte transaction.
Users may increase the default 0.0001 BTC/kB fee setting, but cannot control transaction fees for each transaction. Bitcoin-Qt does prompt the user to accept the fee before the transaction is sent (they may cancel the transaction if they are not willing to pay the fee).

Note that a typical transaction is 500 bytes, so the typical transaction fee for low-priority transactions is 0.1 mBTC (0.0001 BTC), regardless of the number of bitcoins sent.

===Including in Blocks===

This section describes how the reference implementation selects which transactions to put into new blocks, with default settings. All of the settings may be changed if a miner wants to create larger or smaller blocks containing more or fewer free transactions.

30,000 bytes in the block are set aside for the highest-priority transactions, regardless of transaction fee. Transactions are added highest-priority-first to this section of the block.

Then transactions that pay a fee of at least 0.0001 BTC/kb are added to the block, highest-fee transactions first, until the block is not more than 300,000 bytes big.

The remaining transactions remain in the miner's "memory pool", and may be included in later blocks if their priority or fee is large enough.

===Relaying===

The reference implementation's rules for relaying transactions across the peer-to-peer network are very similar to the rules for sending transactions, as a value of 0.0001 BTC is used to determine whether or not a transaction is considered "Free". To prevent "penny-flooding" denial-of-service attacks on the network, the reference implementation caps the number of free transactions it will relay to other nodes to (by default) 15 thousand bytes per minute.

===Settings===

{| class="wikitable"
|-
! Setting !! Default Value (units)
|-
| paytxfee || 0.0000 (BTC)
|-
| limitfreerelay || 15 (thousand bytes per minute)
|-
| mintxfee || 0.0001 (BTC)
|-
| blockmaxsize || 300000 (bytes)
|-
| blockminsize || 0 (bytes)
|-
| blockprioritysize || 30000 (bytes)
|}

==Technical info==

Transaction priority is calculated as a value-weighted sum of input age, divided by transaction size in bytes:
priority = sum(input_value_in_base_units * input_age)/size_in_bytes
Transactions need to have a priority above 57,600,000 to avoid the enforced limit (as of client version 0.3.21). This threshold is written in the code as COIN * 144 / 250, suggesting that the threshold represents a one day old, 1 btc coin (144 is the expected number of blocks per day) and a transaction size of 250 bytes.

So, for example, a transaction that has 2 inputs, one of 5 btc with 10 confirmations, and one of 2 btc with 3 confirmations, and has a size of 500bytes, will have a priority of
(500000000 * 10 + 200000000 * 3) / 500 = 11,200,000

==See Also==

* [[Free transaction relay policy]]
* [http://blockchain.info/charts/transaction-fees Transaction fee chart]

==References==
<references />

[[Category:Technical]]
[[Category:Vocabulary]]
[[Category:Mining]]
[[de:Transaktionsgebühren]]

P2SH

2013-10-15T22:31:40Z

Michagogo: Redirected page to BIP 0016

#REDIRECT [[BIP_0016]]

Eligius

2013-09-24T19:25:25Z

Michagogo:

'''Eligius''', also sometimes referred to as Éloi or "[[Luke Dashjr|Luke-Jr's]] pool", is a [[Pooled mining|mining pool]].
As of October 23, 2012, Eligius is maintained by [[User:Wizkid057|wizkid057]]. <ref>https://bitcointalk.org/index.php?topic=23768.msg1291494#msg1291494</ref>

To use it, a miner merely needs to be directed to mining.eligius.st on port 8337, with the username set to a valid bitcoin address (which receives the payout). '''No registration is needed.'''

Donation address: 1E1igiusfEjs1pCaGjEERExE9gYcrFwow7 / Mx5FUQn8oBCoRdyBTUFu9JW5SsdEku56PP

Basic concepts:
* Pool keeps all transaction fees to itself.
* The pool charges no fees and shares are managed under the [http://eligius.st/wiki/index.php/Capped_PPS#CPPS_with_Recent_Backpay_.28CPPSRB.29 CPPSRB] reward system at 100% value at the time of mining. <ref>http://eligius.st/wiki/index.php/Capped_PPS#CPPS_with_Recent_Backpay_.28CPPSRB.29</ref>
* When a block is found, all miners who have reached the minimum payout threshold (currently about 0.17 BTC) are paid via the Generation transaction.
* The pool almost never has miner's funds, as they are paid directly to the miners from the block reward.
* If a block is orphaned, its shares become part of the next block's reward distribution.
* No registration. Just send username with the address you want payouts to (password can be anything).

Eligius was announced on April 27, 2011<ref>[https://bitcointalk.org/index.php?topic=6648.0 Please test: New Experimental Pool]</ref>. At the time the service was operated without a name, paying out even tiny coins immediately.

==Connecting to Eligius==
* GBT
: gbt.mining.eligius.st:9337
* Stratum
: stratum+tcp://stratum.mining.eligius.st:3334
* Getwork
: getwork.mining.eligius.st:8337

==Eligius-related links==

* [http://eligius.st Main webpage]
* [http://eligius.st/~wizkid057/newstats/ Pool statistics (hashrate, found blocks, per-address balance stats)]
* [http://eligius.st/~luke-jr/raw/combined/hashrate.txt Total pool hashrate (EU + US, estimate)]
* [http://eligius.st/~luke-jr/raw/ JSON API]

==See Also==

* [[Comparison of mining pools]]
* [[Pooled mining]]

==References==
<references />

[[Category:Pool Operators]]

Mining

2013-08-18T19:48:08Z

Michagogo: /* CPU Mining */

[[File:Quick-and-dirty-4x5970-cooling.jpg|thumb|right|A quick and dirty mining rig]]
== Introduction ==
'''Mining''', or generating, is the process of adding transaction records to Bitcoin's public ledger of past transactions. This ledger of past transactions is called the [[block chain]] as it is a chain of [[block|blocks]]. The block chain serves to [[Confirmation|confirm]] transactions to the rest of the network as having taken place. Bitcoin nodes use the block chain to distinguish legitimate Bitcoin transactions from attempts to respend coins that have already been spent elsewhere.

Mining is intentionally designed to be resource-intensive and difficult so that the number of blocks found each day by miners remains steady. Individual [[blocks]] must contain a [[proof of work|proof of work]] to be considered valid. This proof of work is verified by other Bitcoin nodes each time they receive a block.

== History ==
Bitcoin's public ledger (the 'block chain') was started on January 3rd, 2009 at 18:15 UTC presumably by [[Satoshi Nakamoto]]. The first block is known as the [[genesis block]]. The first transaction recorded in the first block was a single transaction paying the reward of 50 new bitcoins to its creator.

Bitcoin mining is so called because it resembles the mining of other commodities: it requires exertion and it slowly makes new currency available at a rate that resembles the rate at which commodities like gold are mined from the ground. See [[Controlled Currency Supply]].

== Mining contracts ==
Provides mining services with performance specified by contract. An example would be where a specific level of mining capacity is rented out for a set price for a specific duration. One of the biggest mining contractors is [[Minerlease]]

== Difficulty ==
=== The Computationally-Difficult Problem ===
Mining a block is difficult because the SHA-256 hash of a block's header must be lower than or equal to the [[Target|target]] in order for the block to be accepted by the network. This problem can be simplified for explanation purposes: The hash of a block must start with a certain number of zeros. The probability of calculating a hash that starts with many zeros is very low, therefore many attempts must be made. In order to generate a new hash each round, a [[Nonce|nonce]] is incremented. See [[Proof of work]] for more information.

=== The Difficulty Metric ===
The [[Difficulty|difficulty]] is the measure of how difficult it is to find a new block compared to the easiest it can ever be. It is recalculated every 2016 blocks to a value such that the previous 2016 blocks would have been generated in exactly two weeks had everyone been mining at this difficulty. This will yield, on average, one block every ten minutes. As more miners join, the rate of block creation will go up. As the rate of block generation goes up, the difficulty rises to compensate which will push the rate of block creation back down. Any blocks released by malicious miners that do not meet the required difficulty [[Target|target]] will simply be rejected by everyone on the network and thus will be worthless.

=== Reward ===
When a block is discovered, the discoverer may award themselves a certain number of bitcoins, which is agreed-upon by everyone in the network. Currently this bounty is 25 bitcoins; this value will halve every 210,000 blocks. See [[Controlled Currency Supply]].

Additionally, the miner is awarded the fees paid by users sending transactions. The fee is an incentive for the miner to include the transaction in their block. In the future, as the number of new bitcoins miners are allowed to create in each block dwindles, the fees will make up a much more important percentage of mining income.

== Hardware ==
[[File:Usb-fpga module 1.15x-hs-800.jpg|thumb|right|FPGA Module]]
Users have used various types of hardware over time to mine blocks. Hardware specifications and performance statistics are detailed on the [[Mining Hardware Comparison]] page.
=== CPU Mining ===
Early Bitcoin client versions allowed users to use their CPUs to mine. The advent of GPU mining made CPU mining financially unwise. The option still exists in the reference Bitcoin client, but it is disabled by default.

=== GPU Mining ===
GPU Mining is drastically faster and more efficient than CPU mining. See the main article: [[Why a GPU mines faster than a CPU]]. A variety of popular [[Mining rig|mining rigs]] have been documented.
=== FPGA Mining ===
FPGA mining is a very efficient and fast way to mine, comparable to GPU mining and drastically outperforming CPU mining. FPGAs typically consume very small amounts of power with relatively high hash ratings, making them more viable and efficient than GPU mining. See [[Mining Hardware Comparison]] for FPGA hardware specifications and statistics.
=== ASIC Mining ===
An application-specific integrated circuit, or ''ASIC'', is a microchip designed and manufactured for a very specific purpose. ASICs designed for Bitcoin mining were first released in 2013 and (at the time of this writing) are in the hands of a very limited number of miners. For the amount of power they consume, they are vastly faster than all previous technologies and already has made GPU mining financially unwise in some countries and setups.

== Pools ==
As mining a block became more and more difficult, individuals found that they were working for months without finding a block and receiving ''any'' reward for their mining efforts. Thus they started organizing themselves into [[Pooled mining|pools]] so that they could share rewards more evenly. See [[Pooled mining]] and [[Comparison of mining pools]].
[[Category:Mining]][[Category:Vocabulary]]

==See Also==

* [http://codinginmysleep.com/bitcoin-mining-in-plain-english Bitcoin Mining in Plain English] by David Perry
* [[Automatically mine when computer is locked|Tutorial to automatically start mining when you lock your computer]]. (Windows 7)
* [http://www.reddit.com/r/Bitcoin/comments/18q2jx/eli5_bitcoin_mining_xpost_in_eli5/ Simplified Explanation of Bitcoin Mining] by reddit user [http://www.reddit.com/user/azotic azotic]

Satoshi Client Node Discovery

2013-07-03T21:54:29Z

Michagogo: Modernized somewhat

==Overview==

The Satoshi client discovers the IP address and port of nodes in several different ways.

# Nodes discover their own external address by various methods.
# Nodes receive the callback address of remote nodes that connect to them.
# Nodes makes DNS request to receive IP addresses.
# Nodes can use addresses hard coded into the software.
# Nodes exchange addresses with other nodes.
# Nodes store addresses in a database and read that database on startup.
# Nodes can be provided addresses as command line arguments
# Nodes read addresses from a user provided text file on startup

A timestamp is kept for each address to keep track of when the node
address was last seen. The AddressCurrentlyConnected in [https://github.com/bitcoin/bitcoin/blob/master/src/net.cpp net.cpp] handles
updating the timestamp whenever a message is received from a node.
Timestamps are only updated on an address and saved to the database
when the timestamp is over 20 minutes old.

See the Node Connectivity article for information on which type of
addresses take precedence when actually connecting to nodes.

In the first section we will cover how a node handles a request for
addresses via the "getaddr" message. By understanding the role of
timestamps, it will become more clear why timestamps are kept the way
they are for each of the different ways an address is discovered.

==Handling Message "getaddr"==

When a node receives a "getaddr" request, it first figures out how many
addresses it has that have a timestamp in the last 3 hours.
Then it sends those addresses, but if there are more than 2500 addresses
seen in the last 3 hours, it selects around 2500 out of the available
recent addresses by using random selection.

Now lets look at the ways a node finds out about node addresses.

==Discovery Methods==

===Local Client's External Address===
The client uses public web services which return the information to determine its own external, routable IP address.

The client runs a thread called ThreadGetMyExternalIP (in [https://github.com/bitcoin/bitcoin/blob/master/src/net.cpp net.cpp])
which attempts to determine the client's IP address as seen from the outside
world.

First, it attempts to connect to 91.198.22.70 port 80, which should be
the checkip.dyndns.org server. If connection fails, a DNS request is made
for checkip.dyndns.org and a connection is attempted to that address.
Next, it attempts to connect to 74.208.43.192 port 80, which should be
the www.showmyip.com server. If connection fails, a DNS request is made
for www.showmyip.com and a connection is attempted to that address.

For each address attempted above, the client attempts to connect,
send a HTTP request, read the appropriate response line, and parse the
IP address from it.
If this succeeds, the IP address is returned, it is advertised to any connected
nodes, and then the thread finishes (without proceeding to the next
address).

===Connect Callback Address===
When a node receives an initial "version" message, and that node initiated the connection, then the node advertises its address to the remote so that it can connect back to the local node if it wants to.

After sending its own address, it sends a "getaddr" request message to the remote node to learn about more addresses, if the remote node version is recent or if the local node does not yet have 1000 addresses.

===IRC Addresses===

As of version 0.6.x the Bitcoin client no longer uses IRC bootstrapping by default, and as of version 0.8.2 support for IRC bootstrapping has been removed completely. This documentation below is accurate for most prior versions.

In addition to learning and sharing its own address, the node learned about other node addresses via an IRC channel. See [https://github.com/bitcoin/bitcoin/blob/847593228de8634bf6ef5933a474c7e63be59146/src/irc.cpp irc.cpp].

After learning its own address, a node encoded its own address into a string to be used as a nickname. Then, it randomly joined an IRC channel named between #bitcoin00 and #bitcoin99. Then it issued a WHO command. The thread read the lines as they appeared in the channel and decoded the IP addresses of other nodes in the channel. It did this in a loop, forever, until the node was shutdown.

When the client discovered an address from IRC, it set the timestamp on the address to the current time, but it used a "penalty" of 51 minutes, which means it looked like it was actually seen almost an hour earlier.

===DNS Addresses===
Upon startup, if peer node discovery is needed, the client then issues DNS requests to learn about the addresses of other peer nodes. The client includes a list of host names for DNS services that are seeded. As-of May 17, 2012 the list (from chainparams.cpp<ref>[https://github.com/bitcoin/bitcoin/blob/master/src/chainparams.cpp#L139 bitcoin/src/chainparams.cpp at master]</ref>) includes:

* bitseed.xf2.org
* dnsseed.bluematt.me
* seed.bitcoin.sipa.be
* dnsseed.bitcoin.dashjr.org

A DNS reply can contain multiple IP addresses for a requested name.

Addresses discovered via DNS are initially given a zero timestamp, therefore they are not advertised in response to a "getaddr" request.

===Hard Coded "Seed" Addresses===
The client contains hard coded IP addresses that represent bitcoin nodes.

These addresses are only used as a last resort, if no other method has produced any addresses at all. When the loop in the connection handling thread ThreadOpenConnections2() sees an empty address map, it uses the "seed" IP addresses as backup.

There is code is move away from seed nodes when possible. The presumption is that this is to avoid overloading those nodes. Once the local node has enough addresses (presumably learned from the seed nodes), the connection thread will close seed node connections.

Seed Addresses are initially given a zero timestamp,
therefore they are not advertised in response to a "getaddr" request.

===Ongoing "addr" advertisements===
Nodes may receive addresses in an "addr" message after having sent a "getaddr" request, or "addr" messages may arrive unsolicited, because nodes advertise addresses gratuitously when they relay addresses (see below), when they advertise their own address periodically, and when a connection is made.

If the address is from a really old version, it is ignored; if from a not-so-old version, it is ignored if we have 1000 addresses already.

If the sender sent over 1000 addresses, they are all ignored.

Addresses received from an "addr" message have a timestamp, but the timestamp is not necessarily honored directly.

For every address in the message:
# If the timestamp is too low or too high, it is set to 5 days ago.
# We subtract 2 hours from the timestamp and add the address.

Note that when any address is added, for any reason, the code that calls AddAddress() does not check to see if it already exists. The AddAddresss() function in [https://github.com/bitcoin/bitcoin/blob/master/src/net.cpp net.cpp] will do that, and if the address already exists, further processing is done to update the address record. If the advertised services of the address have changed, that is updated and stored.

If the address has been seen in the last 24 hours and the timestamp is currently over 60 minutes old, then it is updated to 60 minutes ago.

If the address has NOT been seen in the last 24 hours, and the timestamp is currently over 24 hours old, then it is updated to 24 hours ago.

====Address Relay====

Once addresses are added from an "addr" message (see above), they then may be relayed to the other nodes. First, the following criteria must be set [9]:

#The address timestamp, after processing, is within 60 minutes of the current time
#The "addr" message contains 10 addresses or less
#And fGetAddr is not set on the node. fGetAddr starts false, is set to true when we request addresses from a node, and it is cleared when we receive less than 1000 addresses from a node.
#The address must be routable.

When they meet the above criteria, the node hashes all the eligible node IP addresses, as well as the current day in the form of an integer, and the two nodes with the lowest hash value are chosen to have the address relayed to them.

====Self broadcast====

Every 24 hours, the node advertises its own address to all connected nodes.

It also clears the list of the addresses we think the remote node has, which will trigger a refresh of sends to nodes. This code is in SendMessages() in [https://github.com/bitcoin/bitcoin/blob/master/src/main.cpp main.cpp].

====Old Address Cleanup====

In SendMessages() in [https://github.com/bitcoin/bitcoin/blob/master/src/main.cpp main.cpp], there is code to remove old addresses.

This is done every ten minutes, as long as there are 3 active connections.

The node erases messages that have not been used in 14 days as long as there are at least 1000 addresses in the map, and as long as the erasing process has not taken more than 20 seconds.

===Addresses stored in the Database===
Addresses are stored in the database when AddAddress() is called.

Addresses are read on startup when AppInit2() calls LoadAddresses(), which is located in [https://github.com/bitcoin/bitcoin/blob/master/src/db.cpp db.cpp].

Currently, it appears all addresses are stored all at once whenever any address is stored or updated<ref>[http://bitcointalk.org/index.php?topic=26436.0 Lots of disk activity on Bitcoin startup: easy fix?]</ref>. Indeed, AddAddress is seen to take over .01 seconds in various testing and is typically called tens of thousands of times in the initial 12 hours of running the client.

===Command Line Provided Addresses===

The user can specify nodes to connect to with the
-addnode <ip>
command line argument. Multiple nodes may be specified.

Addresses provided on the command line are initially given a zero timestamp, therefore they are not advertised in response to a "getaddr" request.

The user can also specify an address to connect to with the -connect <ip>
command line argument. Multiple nodes may be specified.

The -connect argument differs from -addnode in that -connect addresses are not added to the address database and when -connect is specified, only those addresses are used.

===Text File Provided Addresses===

The client will automatically read a file named "addr.txt" in the bitcoin data directory and will add any addresses it finds in there as node addresses. These nodes are given no special preference over other addresses. They are just added to the pool.

Addresses loaded from the text file are initially given a zero timestamp, therefore they are not advertised in response to a "getaddr" request.

==See Also==

* [[Network#Bootstrapping|Network - Boostrapping]]

==References==
<references />

[[Category:Developer]]
[[Category:Technical]]

Running Bitcoin

2013-07-03T21:41:08Z

Michagogo: Updated the command-line options and removed the IRC reference from the sample config file

There are two variations of the original bitcoin program available; one with a graphical user interface (usually referred to as just “Bitcoin”), and a 'headless' version (called [[bitcoind]]). They are completely compatible with each other, and take the same command-line arguments, read the same configuration file, and read and write the same data files. You can run one copy of either Bitcoin or bitcoind on your system at a time (if you accidently try to launch another, the copy will let you know that Bitcoin or bitcoind is already running and will exit).

__TOC__

==Linux Quickstart==

The simplest way to start from scratch with the command line client, automatically syncing blockchain and creating a wallet, is to just run this command (without arguments) from the directory containing your bitcoind binary:

./bitcoind

To run with the standard GUI interface:

./bitcoin-qt

==Command-line arguments==

Give Bitcoin (or bitcoind) the -? or –-help argument and it will print out a list of the most commonly used command-line arguments and then exit:

Options:
-? This help message
-conf=<file> Specify configuration file (default: bitcoin.conf)
-pid=<file> Specify pid file (default: bitcoind.pid)
-gen Generate coins (default: 0)
-datadir=<dir> Specify data directory
-dbcache=<n> Set database cache size in megabytes (default: 25)
-timeout=<n> Specify connection timeout in milliseconds (default: 5000)
-proxy=<ip:port> Connect through socks proxy
-socks=<n> Select the version of socks proxy to use (4-5, default: 5)
-tor=<ip:port> Use proxy to reach tor hidden services (default: same as -proxy)
-dns Allow DNS lookups for -addnode, -seednode and -connect
-port=<port> Listen for connections on <port> (default: 8333 or testnet: 18333)
-maxconnections=<n> Maintain at most <n> connections to peers (default: 125)
-addnode=<ip> Add a node to connect to and attempt to keep the connection open
-connect=<ip> Connect only to the specified node(s)
-seednode=<ip> Connect to a node to retrieve peer addresses, and disconnect
-externalip=<ip> Specify your own public address
-onlynet=<net> Only connect to nodes in network <net> (IPv4, IPv6 or Tor)
-discover Discover own IP address (default: 1 when listening and no -externalip)
-checkpoints Only accept block chain matching built-in checkpoints (default: 1)
-listen Accept connections from outside (default: 1 if no -proxy or -connect)
-bind=<addr> Bind to given address and always listen on it. Use [host]:port notation for IPv6
-dnsseed Find peers using DNS lookup (default: 1 unless -connect)
-banscore=<n> Threshold for disconnecting misbehaving peers (default: 100)
-bantime=<n> Number of seconds to keep misbehaving peers from reconnecting (default: 86400)
-maxreceivebuffer=<n> Maximum per-connection receive buffer, <n>*1000 bytes (default: 5000)
-maxsendbuffer=<n> Maximum per-connection send buffer, <n>*1000 bytes (default: 1000)
-upnp Use UPnP to map the listening port (default: 1 when listening)
-paytxfee=<amt> Fee per KB to add to transactions you send
-server Accept command line and JSON-RPC commands
-testnet Use the test network
-debug Output extra debugging information. Implies all other -debug* options
-debugnet Output extra network debugging information
-logtimestamps Prepend debug output with timestamp
-shrinkdebugfile Shrink debug.log file on client startup (default: 1 when no -debug)
-printtoconsole Send trace/debug info to console instead of debug.log file
-printtodebugger Send trace/debug info to debugger
-rpcuser=<user> Username for JSON-RPC connections
-rpcpassword=<pw> Password for JSON-RPC connections
-rpcport=<port> Listen for JSON-RPC connections on <port> (default: 8332 or testnet: 18332)
-rpcallowip=<ip> Allow JSON-RPC connections from specified IP address
-rpcthreads=<n> Set the number of threads to service RPC calls (default: 4)
-blocknotify=<cmd> Execute command when the best block changes (%s in cmd is replaced by block hash)
-walletnotify=<cmd> Execute command when a wallet transaction changes (%s in cmd is replaced by TxID)
-alertnotify=<cmd> Execute command when a relevant alert is received (%s in cmd is replaced by message)
-upgradewallet Upgrade wallet to latest format
-keypool=<n> Set key pool size to <n> (default: 100)
-rescan Rescan the block chain for missing wallet transactions
-salvagewallet Attempt to recover private keys from a corrupt wallet.dat
-checkblocks=<n> How many blocks to check at startup (default: 288, 0 = all)
-checklevel=<n> How thorough the block verification is (0-4, default: 3)
-txindex Maintain a full transaction index (default: 0)
-loadblock=<file> Imports blocks from external blk000??.dat file
-reindex Rebuild block chain index from current blk000??.dat files
-par=<n> Set the number of script verification threads (up to 16, 0 = auto, <0 = leave that many cores free, default: 0)

Block creation options:
-blockminsize=<n> Set minimum block size in bytes (default: 0)
-blockmaxsize=<n> Set maximum block size in bytes (default: 250000)
-blockprioritysize=<n> Set maximum size of high-priority/low-fee transactions in bytes (default: 27000)

SSL options: (see the Bitcoin Wiki for SSL setup instructions)
-rpcssl Use OpenSSL (https) for JSON-RPC connections
-rpcsslcertificatechainfile=<file.cert> Server certificate file (default: server.cert)
-rpcsslprivatekeyfile=<file.pem> Server private key (default: server.pem)
-rpcsslciphers=<ciphers> Acceptable ciphers (default: TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH)

UI options:
-lang=<lang> Set language, for example "de_DE" (default: system locale)
-min Start minimized
-splash Show splash screen on startup (default: 1)

Many of the boolean options can also be set to off by specifying them with a "no" prefix: e.g. -nodnseed.

==Bitcoin.conf Configuration File==
All command-line options (except for -datadir and -conf) may be specified in a configuration file, and all configuration file options may also be specified on the command line. Command-line options override values set in the configuration file.

The configuration file is a list of setting=value pairs, one per line, with optional comments starting with the '#' character.

The configuration file is not automatically created; you can create it using your favorite plain-text editor. By default, Bitcoin (or bitcoind) will look for a file named 'bitcoin.conf' in the bitcoin [[data directory]], but both the data directory and the configuration file path may be changed using the -datadir and -conf command-line arguments.
{|
! Operating System
! Default bitcoin datadir
! Typical path to configuration file
|-
| Windows
| %APPDATA%\Bitcoin\
| (XP) C:\Documents and Settings\username\Application Data\Bitcoin\bitcoin.conf
(Vista, 7) C:\Users\username\AppData\Roaming\Bitcoin\bitcoin.conf
|-
| Linux
| $HOME/.bitcoin/
| /home/username/.bitcoin/bitcoin.conf
|-
| Mac OSX
| $HOME/Library/Application Support/Bitcoin/
| /Users/username/Library/Application Support/Bitcoin/bitcoin.conf
|}

Note: if running Bitcoin in testnet mode, the sub-folder "testnet" will be appended to the data directory automatically.

==Sample Bitcoin.conf==
Here is a sample bitcoin.conf file.

# bitcoin.conf configuration file. Lines beginning with # are comments.

# Network-related settings:

# Run on the test network instead of the real bitcoin network.
#testnet=0

# Connect via a socks4 proxy
#proxy=127.0.0.1:9050

##############################################################
## Quick Primer on addnode vs connect ##
## Let's say for instance you use addnode=4.2.2.4 ##
## addnode will connect you to and tell you about the ##
## nodes connected to 4.2.2.4. In addition it will tell ##
## the other nodes connected to it that you exist so ##
## they can connect to you. ##
## connect will not do the above when you 'connect' to it. ##
## It will *only* connect you to 4.2.2.4 and no one else.##
## ##
## So if you're behind a firewall, or have other problems ##
## finding nodes, add some using 'addnode'. ##
## ##
## If you want to stay private, use 'connect' to only ##
## connect to "trusted" nodes. ##
## ##
## If you run multiple nodes on a LAN, there's no need for ##
## all of them to open lots of connections. Instead ##
## 'connect' them all to one node that is port forwarded ##
## and has lots of connections. ##
## Thanks goes to [Noodle] on Freenode. ##
##############################################################

# Use as many addnode= settings as you like to connect to specific peers
#addnode=69.164.218.197
#addnode=10.0.0.2:8333

# ... or use as many connect= settings as you like to connect ONLY
# to specific peers:
#connect=69.164.218.197
#connect=10.0.0.1:8333

# Maximum number of inbound+outbound connections.
#maxconnections=

# JSON-RPC options (for controlling a running Bitcoin/bitcoind process)

# server=1 tells Bitcoin-QT to accept JSON-RPC commands.
#server=0

# You must set rpcuser and rpcpassword to secure the JSON-RPC api
#rpcuser=Ulysseys
#rpcpassword=YourSuperGreatPasswordNumber_DO_NOT_USE_THIS_OR_YOU_WILL_GET_ROBBED_385593

# How many seconds bitcoin will wait for a complete RPC HTTP request.
# after the HTTP connection is established.
#rpctimeout=30

# By default, only RPC connections from localhost are allowed. Specify
# as many rpcallowip= settings as you like to allow connections from
# other hosts (and you may use * as a wildcard character):
#rpcallowip=10.1.1.34
#rpcallowip=192.168.1.*

# Listen for RPC connections on this TCP port:
#rpcport=8332

# You can use Bitcoin or bitcoind to send commands to Bitcoin/bitcoind
# running on another host using this option:
#rpcconnect=127.0.0.1

# Use Secure Sockets Layer (also known as TLS or HTTPS) to communicate
# with Bitcoin -server or bitcoind
#rpcssl=1

# OpenSSL settings used when rpcssl=1
#rpcsslciphers=TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH
#rpcsslcertificatechainfile=server.cert
#rpcsslprivatekeyfile=server.pem

# Miscellaneous options

# Set gen=1 to attempt to generate bitcoins
#gen=0

# Use SSE instructions to try to generate bitcoins faster.
#4way=1

# Pre-generate this many public/private key pairs, so wallet backups will be valid for
# both prior transactions and several dozen future transactions.
#keypool=100

# Pay an optional transaction fee every time you send bitcoins. Transactions with fees
# are more likely than free transactions to be included in generated blocks, so may
# be validated sooner.
#paytxfee=0.00

# Allow direct connections for the 'pay via IP address' feature.
#allowreceivebyip=1

# User interface options

# Start Bitcoin minimized
#min=1

# Minimize to the system tray
#minimizetotray=1

==Platforms==
===Windows===

====Start automatically====
To configure the Bitcoin client to start automatically:

You might use the configuration-file, or the GUI-Settings:

Settings -> Options

then mark the checkbox titled:
[X] Start Bitcoin on system startup

[[{{ns:file}}:Client_Settings_Options_windows.png]]

====Batch automation====
To work with batch, you have to start the daemon (bitcoind.exe). The bitcoin.exe run with option "-server" will respond with GUI-messages you are not able to process its answers.

===Mac===
[[{{ns:file}}:MacBitcoinStartOnLogin.png]]

===Linux===
[[{{ns:file}}:Client_Settings_Options.png]]

==See Also==

* [[Data directory]]

[[es:Ejecución de Bitcoin]]

[[Category:Technical]]
[[Category:Developer]]

Testnet

2013-06-28T00:53:56Z

Michagogo:

The '''testnet''' is an alternative Bitcoin [[block chain]], to be used for testing. This allows application developers or bitcoin testers to experiment, without having to use real bitcoins or worrying about breaking the main bitcoin chain.

Run bitcoin or bitcoind with the -testnet flag to use the testnet (or put testnet=1 in the bitcoin.conf file).

There have been three generations of testnet. Testnet2 was just the first testnet reset with a different genesis block, because people were starting to trade testnet coins for real money. '''Testnet3''' is the current test network. It was introduced with the 0.7 release, introduced a third genesis block, a new rule to avoid the "difficulty was too high, is now too low, and transactions take too long to verify" problem, and contains blocks with edge-case transactions designed to test implementation compatibility.

==Differences==
* Default Bitcoin network protocol listen port is 18333 (instead of 8333)
* Default RPC connection port is 18332 (instead of 8332)
* Bootstrapping IRC channel is #bitcoinTEST instead of #bitcoin (both on irc.lfnet.org). The built-in node list is disabled.
* A different value of ADDRESSVERSION field ensures no testnet BitCoin addresses will work on the production network. (0x6F rather than 0x00)
* The protocol message header bytes are 0x0B110907 (instead of 0xF9BEB4D9)
* Minimum [[difficulty]] of 1.0 on testnet is equal to difficulty of 0.5 on mainnet. This means that the mainnet-equivalent of any testnet difficulty is half the testnet difficulty. In addition, if no block has been found in 20 minutes, the difficulty automatically resets back to the minimum for a single block, after which it returns to its previous value.
* A new genesis block
* The IsStandard() check is disabled so that non-standard transactions can be experimented with.

==Genesis Block==

Testnet uses a different genesis block to the main network. You can find it at http://blockexplorer.com/testnet/b/0
The testnet was reset with a new genesis block for the 0.7 bitcoin release.

==External links==
* [https://sourceforge.net/projects/bitcoin/files/Bitcoin/testnet-in-a-box/ Testnet-In-A-Box self-contained testnet]
* [https://github.com/freewil/bitcoin-testnet-box Forked/Updated testnet-box]
* [https://bitcointalk.org/?topic=4483.0 Test Network forum topic]
* [https://freebitcoins.appspot.com/test/ Testnet Faucet]
* [http://testnet.mojocoin.com/ Another Testnet Faucet]
* [http://pool.qdoop.net:18331/chain/Testnet3 Testnet3 ABE based Block Explorer]
* [http://blockexplorer.com/testnet Testnet Block Explorer]
* [http://blockexplorer.com/testnet/q/getdifficulty Testnet current difficulty] As output by BitCoin's getDifficulty]

[[Category:Technical]]
[[Category:Developer]]