Bitcoin Wiki - User contributions [en]

Block

2013-01-15T18:36:53Z

Rising:

Data is permanently recorded in the Bitcoin network through files called '''blocks'''. A block is a record of some or all of the most recent Bitcoin transactions that have not yet been recorded in any prior blocks. They could be thought of like the individual pages of a city recorder's recordbook (where changes to title to real estate are recorded) or a stock transaction ledger. In all but a few exceptional cases, new blocks are added to the end of the record (known in Bitcoin as the [[block chain]]), and once written, are never changed or removed. Each block memorializes what took place immediately before it was created.
===Block structure===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Magic no
|value always 0xD9B4BEF9
|4 bytes
|-
|Blocksize
|number of bytes following up to end of block
|4 bytes
|-
|Blockheader
|[[Block hashing algorithm| consists of 6 items]]
|80 bytes
|-
|Transaction counter
| positive integer
| 1 - 9 bytes
|-
|[[transactions]]
|the (non empty) list of transactions
|<Transaction counter>-many transactions
|}
==Description==
Each block contains, among other things, in its block header a record of some or all recent [[transactions]], and a reference to the block that came immediately before it. It also contains an answer to a difficult-to-solve mathematical puzzle - the answer to which is unique to each block. New blocks can't be submitted to the network without the correct answer - the process of "[[Mining]]" is essentially the process of competing to be the next to find the answer that "solves" the current block. The mathematical problem in each block is difficult to solve, but once a valid solution is found, it is very easy for the rest of the network to confirm that the solution is correct. There are multiple valid solutions for any given block - only one of the solutions needs to be found for the block to be solved.

Because there is a reward of brand new Bitcoins for solving each block, every block also contains a record of which [[Bitcoin address]] is entitled to receive the reward. This record is known as a generation transaction, or a [[coinbase]] transaction, and is always the first transaction appearing in every block. The number of [[Bitcoins]] generated per block starts at 50 and is halved every 210,000 blocks (about four years).

Bitcoin transactions are broadcast to the [[network]] by the sender, and all peers trying to solve blocks collect the transaction records and add them to the block they're working to solve.

The difficulty of the mathematical problem is automatically adjusted by the network, such that it targets a goal of solving an average of 6 blocks per hour. Every 2016 blocks (about two weeks), all Bitcoin clients compare the actual number created with this goal and modify the target by the percentage that it varied. This increases (or decreases) the difficulty of generating blocks.

Because each block contains a reference to the prior block, the collection of all blocks in existence can be said to form a chain. However, it's possible for the chain to have temporary splits - for example, if two miners arrive at two different valid solutions for the same block at the same time, unbeknownst to one another. The peer-to-peer network is designed to resolve these splits within a short period of time, so that only one branch of the chain survives.

The client accepts the 'longest' chain of blocks as valid. The 'length' of the entire [[block chain]] refers to the chain with the most combined difficulty, not the one with the most blocks. This prevents someone from forking the chain and creating a large number of low-difficulty blocks, and having it accepted by the network as 'longest'.

== Common Questions about Blocks ==

=== How many blocks are there? ===
[http://blockexplorer.com/q/getblockcount Current block count]

=== What is the maximum number of blocks? ===
There is no maximum number, blocks just keep getting added to the end of the chain at an average rate of one every 10 minutes.

==== Even when all 21 million coins have been generated? ====
Yes. The blocks are for proving that transactions existed at a particular time. Transactions will still occur once all the coins have been generated, so blocks will still be created as long as people are trading Bitcoins.

=== How long will it take me to generate a block? ===
No-one can say exactly. There is a [[Generation Calculator|generation calculator]] that will tell you how long it '''might''' take.

=== What if I'm 1% towards calculating a block and...? ===
There's no such thing as being 1% towards solving a block. You don't make progress towards solving it. After working on it for 24 hours, your chances of solving it are equal to what your chances were at the start or at any moment. Believing otherwise is what's known as the Gambler's fallacy [http://en.wikipedia.org/wiki/Gambler's_fallacy].

It's like trying to flip 53 coins at once and have them all come up heads. Each time you try, your chances of success are the same.

=== Where can I find more technical detail? ===
There is more technical detail on the [[block hashing algorithm]] page.

==See Also==

[https://bitcointalk.org/index.php?topic=101514.0 Format of the BDB-style block files]
* [http://en.bitcoin.it/wiki/File:Total_bitcoins_over_time_graph.png Total Bitcoins Over Time]

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

[[fr:Blocs]][[pl:Bloki]][[zh-cn:Block]]
[[de:Block]]

Irreversible Transactions

2012-12-28T15:52:31Z

Rising:

Double-spending is the result of successfully spending some money more than once. Bitcoin protects against double spending by verifying each transaction added to the [[block chain]] to ensure that the inputs for the transaction had not previously already been spent.

Other electronic systems prevent double-spending by having a master authoritative source that follows business rules for authorizing each transaction. Bitcoin uses a decentralized system, where a consensus among nodes following the same protocol is substituted for a central authority.

Bitcoin has some exposure to fraudulent double-spending when a transaction is first made, with less and less risk as a transaction gains [[confirmation|confirmations]].

==Attack vectors==

===Race attack===

Traders and merchants who accept a payment immediately on seeing "0/unconfirmed" are exposed to a double-spend occurring is there was a fraudulent attempt that successfully communicated one transaction to the merchant yet communicated a different transaction that spends the same coin that was first to eventually make it into the block chain.

Merchants can take precautions (e.g., disable incoming connections, only connect to well connected nodes) to lessen the risk of a race attack but the risk cannot be eliminated. Therefore, the cost/benefit of the risk needs to be considered when accepting payment on 0/unconfirmed when there is no recourse against the attacker.

The [[research]] paper [http://eprint.iacr.org/2012/248.pdf Two Bitcoins at the Price of One] finds that the protocol allows a high degree of success by an attacker in performing race attacks. The method studied in the research paper depends on access to the merchant's Bitcoin node which is why that even prior to this paper, recommendations for merchants include disabling incoming connections and to choose specific outgoing connections<ref>[http://bitcointalk.org/index.php?topic=79090.msg881283#msg881283 BitcoinTalk Thread - Two Bitcoins at the Price of One]</ref>.

===Finney attack===

Another attack the trader or merchant is exposed to when accepting payment on 0/unconfirmed. The Finney attack is a fraudulent double-spend that requires the participation of a miner once a block has been mined<ref>[http://www.bitcointalk.org/index.php?topic=3441.msg48384#msg48384 Best practice for fast transaction acceptance - how high is the risk?]</ref>. The risk of a Finney attack cannot be eliminated regardless of the precautions taken by the merchant, but the participation of a miner is required and a specific sequence of events must occur. Thus the attack is not trivial nor inexpensive to perform and only makes sense for the attacker when the gains from the attack are significant. Just like with the race attack, a trader or merchant should consider the cost / benefit when accepting payment on just one confirmation when there is no recourse against the attacker.

===Vector76 attack===

Also referred to as a one-confirmation attack, is a combination of the race attack and the Finney attack such that a transaction that even has one confirmation can still be double-spent. The same protective action for the race attack (no incoming connections, explicit outgoing connection to a well-connected node) significantly reduces the risk of this occurring.

===Brute force attack===

This attack has a chance to work even if the merchant waits for some confirmations, but requires relatively high hashrate.

The attacker submits to the merchant/network a transaction which pays the merchant, while privately mining a blockchain fork in which a double-spending transaction is included instead. After waiting for ''n'' confirmations, the merchant sends the product. If the attacker happened to find more than ''n'' blocks at this point, he releases his fork and regains his coins; otherwise, he can try to continue extending his fork with the hope of being able to catch up with the network. If he never manages to do this, the attack fails and the payment to the merchant will go through.

The probability of success is a function of the attacker's hashrate (as a proportion of the total network hashrate) and the number of confirmations the merchant waits for. For example, if the attacker controls 10% of the network hashrate but the merchant waits for 6 confirmations, the success probability is on the order of 0.1%.

===>50% attack===

If the attacker controls more than half of the network hashrate, the previous attack has a probability of 100% to succeed. Since the attacker can generate blocks faster than the rest of the network, he can simply persevere with his private fork until it becomes longer than the branch built by the honest network, from whatever disadvantage.

No amount of confirmations can prevent this attack; however, waiting for confirmations does increase the aggregate resource cost of performing the attack, which could make it unprofitable or delay it long enough for the circumstances to change or slower-acting synchronization methods to kick in.

==Risk management==

There are third-party services to assist traders and merchants to help manage the risk or to insure against losses.

==See Also==

* [[Weaknesses]]
* [[How bitcoin works]]
* [http://codinginmysleep.com/bitcoin-attacks-in-plain-english Bitcoin Attacks in Plain English] by David Perry

[[de:Doppelausgaben]]

==References==
<references />

[[Category:Technical]]

Irreversible Transactions

2012-12-28T15:52:22Z

Rising:

Double-spending is the result of successfully spending some money more than once. Bitcoin protects against double spending by verifying each transaction added to the [[block chain]] to ensure that the inputs for the transaction had not previously already been spent.

Other electronic systems prevent double-spending by having a master authoritative source that follows business rules for authorizing each transaction. Bitcoin uses a decentralized system, where a consensus among nodes following the same protocol is substituted for a central authority.

Bitcoin has some exposure to fraudulent double-spending when a transaction is first made, with less and less risk as a transaction gains [[confirmation|confirmations]].

==Attack vectors==

===Race attack===

Traders and merchants who accept a payment immediately on seeing "0/unconfirmed" are exposed to a double-spend occurring is there was a fraudulent attempt that successfully communicated one transaction to the merchant yet communicated a different transaction that spends the same coin that was first to eventually make it into the block chain.

Merchants can take precautions (e.g., disable incoming connections, only connect to well connected nodes) to lessen the risk of a race attack but the risk cannot be eliminated. Therefore, the cost/benefit of the risk needs to be considered when accepting payment on 0/unconfirmed when there is no recourse against the attacker.

The [[research]] paper [http://eprint.iacr.org/2012/248.pdf Two Bitcoins at the Price of One] finds that the protocol allows a high degree of success by an attacker in performing race attacks. The method studied in the research paper depends on access to the merchant's Bitcoin node which is why that even prior to this paper, recommendations for merchants include disabling incoming connections and to choose specific outgoing connections<ref>[http://bitcointalk.org/index.php?topic=79090.msg881283#msg881283 BitcoinTalk Thread - Two Bitcoins at the Price of One]</ref>.

===Finney attack===

Another attack the trader or merchant is exposed to when accepting payment on 0/unconfirmed. The Finney attack is a fraudulent double-spend that requires the participation of a miner once a block has been mined<ref>[http://www.bitcointalk.org/index.php?topic=3441.msg48384#msg48384 Best practice for fast transaction acceptance - how high is the risk?]</ref>. The risk of a Finney attack cannot be eliminated regardless of the precautions taken by the merchant, but the participation of a miner is required and a specific sequence of events must occur. Thus the attack is not trivial nor inexpensive to perform and only makes sense for the attacker when the gains from the attack are significant. Just like with the race attack, a trader or merchant should consider the cost / benefit when accepting payment on just one confirmation when there is no recourse against the attacker.

===Vector76 attack===

Also referred to as a one-confirmation attack, is a combination of the race attack and the Finney attack such that a transaction that even has one confirmation can still be double-spent. The same protective action for the race attack (no incoming connections, explicit outgoing connection to a well-connected node) significantly reduces the risk of this occurring.

===Brute force attack===

This attack has a chance to work even if the merchant waits for some confirmations, but requires relatively high hashrate.

The attacker submits to the merchant/network a transaction which pays the merchant, while privately mining a blockchain fork in which a double-spending transaction is included instead. After waiting for ''n'' confirmations, the merchant sends the product. If the attacker happened to find more than ''n'' blocks at this point, he releases his fork and regains his coins; otherwise, he can try to continue extending his fork with the hope of being able to catch up with the network. If he never manages to do this, the attack fails and the payment to the merchant will go through.

The probability of success is a function of the attacker's hashrate (as a proportion of the total network hashrate) and the number of confirmations the merchant waits for. For example, if the attacker controls 10% of the network hashrate but the merchant waits for 6 confirmations, the success probability is on the order of 0.1%.

===>50% attack===

If the attacker controls more than half of the network hashrate, the previous attack has a probability of 100% to succeed. Since the attacker can generate blocks faster than the rest of the network, he can simply persevere with his private fork until it becomes longer than the branch built by the honest network, from whatever disadvantage.

No amount of confirmations can prevent this attack; however, waiting for confirmations does increase the aggregate resource cost of performing the attack, which could make it unprofitable or delay it long enough for the circumstances to change or slower-acting synchronization methods to kick in.

==Risk management==

There are third-party services to assist traders and merchants to help manage the risk or to insure against losses.

==See Also==

* [[Weaknesses]]
* [[How bitcoin works]]
* [http://codinginmysleep.com/bitcoin-attacks-in-plain-english Bitcoin Attacks in Plain English] by David Perry

[[en:Doppelausgaben]]

==References==
<references />

[[Category:Technical]]

Lazy API

2012-12-28T15:41:17Z

Rising:

For the incredibly lazy and/or incompetent web developer, present is the lazy man's bitcoin API (copied from [http://www.bitcoin.org/smf/index.php?topic=4324.msg77187#msg77187 a forum post]):

==Problem==

Lazy web designer wants to use bitcoins without dealing with installing bitcoin on a server, installing a shopping cart interface, or using ugly merchant services with callbacks.

==Solution for sending bitcoins==

Use the [https://mtgox.com/support/tradeAPI MtGox API]

==Solution for receiving bitcoins==
# Input a list of bitcoin receiving addresses to your database
# Give a bitcoin address to a potential customer
# Have the customer tell you when they have sent the coins and have at least 1 confirmation (you can choose a number higher than 1 if you are worried about double-spending)
# Check blockexplorer to see if they sent the right amount (i.e. http://blockexplorer.com/q/getreceivedbyaddress/19hMEAaRMbEhfSkeU4GT8mgSuyR4t4M6TH/1) - the /1 is the number of confirmations you require
# Give them what they paid for
# After a reasonable amount of time has passed, you can re-use the address for another customer

You could avoid having a list of addresses and reusing them by getting a new address via API call from one of the wallet services that support this feature (e.g. https://instawallet.org/static/api).

==Risks==

===External Service===

BlockExplorer is a service that is provided by a private party. There is no guarantee that the information provided by BlockExplorer matches the blockchain.

There have not been any reports that BlockExplorer has reported transaction data incorrectly.

===Double Spending===

A merchant is exposed to a [[double-spending]] attack when recognizing a payment before it has been [[confirmation|confirmed]] with a sufficient number of blocks.

For an attacker to be successful with this double spend tactic a significant effort is required and thus the risk of this attack being made against the typical retail merchant is pretty minimal. It would not be advisable for a merchant with little to no recourse against an attacker to accept payment without a sufficient number of confirmations however.

==See Also==

* [[BitAddress]] Generate address and private key pairs for an offline wallet
* [[BitcoinNotify]] Register addresses and receive email or SMS alerts when a payment to that address occurs

[[de:API_für_Faule]]

[[Category:Developer]]

Proper Money Handling (JSON-RPC)

2012-12-23T19:07:32Z

Rising:

== Overview ==
The original bitcoin client stores all bitcoin values as 64-bit integers, with 1 BTC stored as 100,000,000 (one-hundred-million of the smallest possible bitcoin unit). Values are expressed as double-precision Numbers in the JSON API, with 1 BTC expressed as 1.00000000

If you are writing software that uses the JSON-RPC interface you need to be aware of possible floating-point conversion issues. You, or the JSON library you are using, should convert amounts to either a fixed-point Decimal representation (with 8 digits after the decimal point) or ideally a 64-bit integer representation. In either case, rounding values is required.

Improper value handling can lead to embarrassing errors; for example, if you truncate instead of doing proper rounding and your software will display the value "0.1 BTC" as "0.09999999 BTC" (or, worse, "0.09 BTC").

The original bitcoin client does proper, full-precision rounding for all values passed to it via the RPC interface. So, for example, if the value 0.1 is converted to the value "0.099999999999" by your JSON-RPC library, that value will be rounded to the nearest 0.00000001 bitcoin and will be treated as exactly 0.10 BTC.

The rest of this page gives sample code for various JSON libraries and programming languages.

== BASH ==
<source lang="bash">
function JSONtoAmount() {
printf '%.8f' "$1" | tr -d '.'
}
</source>

== C/C++ ==
C/C++ JSON libraries return the JavaScript Number type as type 'double'. To convert, without loss of precision, from a double to a 64-bit integer multiply by 100,000,000 and round to the nearest integer:
int64_t JSONtoAmount(double value) {
return (int64_t)(value * 1e8 + (value < 0.0 ? -.5 : .5));
}

To convert to a JSON value divide by 100,000,000.0, and make sure your JSON implementation outputs doubles with 8 or more digits after the decimal point:
double forJSON = (double)amount / 1e8;

== ECMAScript ==

function JSONtoAmount(value) {
return Math.round(1e8 * value);
}

== Perl ==
sub JSONtoAmount {
return sprintf '%.0f', 1e8 * shift;
}

== PHP ==
function JSONtoAmount($value) {
return round($value * 1e8);
}

== Python ==
def JSONtoAmount(value):
return long(round(value * 1e8))
def AmountToJSON(amount):
return float(amount / 1e8)

== Common Lisp ==
(defun json-to-amount (n)
(coerce (round (* n 1e8)) 'integer))

'''CAUTION''': The CL-JSON library parses numbers as ''single'' precision floating-point by
default. The default parsing behavior can be overridden as follows:

(set-custom-vars :real (lambda (n)
(json::parse-number (concatenate 'string n "d0"))))
[[Category:Technical]]
[[Category:Developer]]

[[de:Korrektes_Handling_von_Geldbeträgen_(JSON-RPC)]]

PHP developer intro

2012-12-23T18:57:54Z

Rising:

'''L'''inux '''A'''pache '''M'''ySQL '''P'''HP + Bitcoin tutorial.

For this introduction we assume that you have GNU/Linux server with Apache and PHP and that you wish to interact with the Bitcoin network from a web application. We assume some knowledge of Bitcoin and experience in PHP.

While this is written for PHP, the same principles apply for other languages. See the associated [[API reference (JSON-RPC)|API reference]] pages for info on other languages.

The easiest way to get started is to run Bitcoin in daemon mode with which PHP communicates via local HTTP requests. A library called [http://jsonrpcphp.org/ JSON-RPC] is used to call the various functions of bitcoind, which will respond back with a [http://en.wikipedia.org/wiki/Json JSON object].

== Setting up Bitcoin ==

You can download the Bitcoin daemon from the [[Main_Page|homepage]] and run one of the included binaries or compile your own from the included source code. See [[Running Bitcoin]] for details on configuring bitcoind.

Before running bitcoind you will need to create a configuration file in the Bitcoin data directory (~/.bitcoin/bitcoin.conf on Linux):
<source lang="bash">
rpcuser=user
rpcpassword={you MUST pick a unique password to be secure}
</source>
If you miss this step, bitcoind will remind you.

Now run bitcoind:
<source lang="bash">
$ ./bitcoind
# wait a few seconds for it to start up
$ ./bitcoind getinfo
# various information will be shown. If you get an error, try again until you see some useful output.
$ ./bitcoind help
# get help on commands, note no dash before help
</source>

Bitcoin will begin synchronizing with the network and downloading a complete copy of the block chain. As of August 2012, more than 2gb of data must be downloaded and verified during this process. It may take two or more hours to complete. You will know when it's done when the block count reaches the [http://blockexplorer.com/q/getblockcount current count].

== Getinfo (Bitcoind's version of Hello World) ==

Assuming Bitcoin has finished the initialisation process; download the file jsonRPCClient.php from [http://jsonrpcphp.org/ JSON-RPC PHP] and place it in a web-accessible location.

Second, create a PHP file with the following and visit it with your browser to test.

<source lang="php">
require_once 'jsonRPCClient.php';

$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');

echo "<pre>\n";
print_r($bitcoin->getinfo());
echo "</pre>";
</source>

== Precision ==

Bitcoin amounts can range from 1 (0.00000001 BTC) to nearly 2,100,000,000,000,000 (21,000,000 BTC). To avoid rounding errors, you must make sure your PHP implementation supports the full range of Bitcoin values without losing precision. Most PHP implementations use IEEE 64-bit double-precision floating point numbers with 53 bits of precision, which is enough to correctly represent the full range of bitcoin values.

See [[Proper Money Handling (JSON-RPC)]] for more information.

If your PHP implementation does not support 64-bit numbers (again, this is very rare), you must use a version of bitcoind that sends values as strings (genjix maintains a fork at http://github.com/genjix/bitcoin) and use the [http://php.net/manual/en/ref.gmp.php GMP] and [http://php.net/manual/en/ref.bc.php BC Math] libraries for all calculations involving bitcoin amounts.

== Accounts ==

In Bitcoin, money is sent to addresses and many addresses can be held by one wallet. The balance shown by default in bitcoind is the sum of the bitcoins in all the addresses in the wallet.

Bitcoin goes another step. You can have [[Accounts explained|accounts]]. Each account holds multiple addresses and acts like a mini-bitcoind.

<source lang="bash">
$ ./bitcoind listaccounts
# show list of accounts and various info for each one
$ ./bitcoind getaccountaddress user889
# get an address to receive money to that is unique for the account user889
$ ./bitcoind getbalance user889
# get the sum of all the money in the addresses owned by the account user889
</source>

In your application, each user should have a unique username. You may then query bitcoind for a unique address using $bitcoin->getaccountaddress("user889"); [gets the first address for user889] or $bitcoin->getnewaddress("user889"); [creates a new address for user889].

The customer then deposits to this address.

You can check the funds for that customer by doing $bitcoin->getbalance("user889", 4);. The 4 indicates the minimum number of confirmations we will accept before assuming this payment is valid.

If you will be using accounts for multiple deposits and withdrawals long-term, you may want to consider tracking user balances in your own database. This simplifies transfers between your application's accounts and decouples your accounts from the Bitcoin wallet.

=== getnewaddress vs getaccountaddress ===

Using getnewaddress helps increase maintain anonymity of your users by making it hard for a malicious agent to track payments flowing through your application. Running getnewaddress too often, however, will cause your wallet to become filled with many empty addresses.

It is therefore recommended to in some way limit the number of unfunded addresses each user can request. Here is an example using sessions:
<source lang="php">
<?php
require_once('jsonRPCClient.php');
$bitcoin = new jsonRPCClient('http://root:root@127.0.0.1:8332/');
# now check for appropriate funds in user account
try {
$username = ...
if(isset($_SESSION['sendaddress']))
$sendaddress = $_SESSION['sendaddress'];
else {
$sendaddress = $bitcoin->getnewaddress($username);
$_SESSION['sendaddress'] = $sendaddress;
}
$balance = $bitcoin->getbalance($username);
}
catch (Exception $e) {
die("<p>Server error! Please contact the admin.</p>");
}
?>
</source>

This creates a new address at the beginning of every new session, and stores it in the session variable.

==See Also==

* [[API reference (JSON-RPC)]]
* [[Lazy_API]]
* [[Merchant Howto]]

[[es:Introducción para desarrolladores de PHP]]
[[de:Einführung_für_PHP-Entwickler]]

[[Category:Developer]]