Bitcoin Wiki - User contributions [en]

PHP developer intro

2015-02-20T15:15:03Z

Pagent:

'''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].

It is however recommended to use one of the [[#Alternative_Libs_For_RPC|Alternative Libraries]] listed below instead, since they are more sophisticated.

== 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>

'''Note:''' The jsonRPCClient library uses fopen() and will throw an exception saying "Unable to connect" if it receives a 404 or 500 error from bitcoind. This prevents you from being able to see error messages generated by bitcoind (as they are sent with status 404 or 500). The [[#Alternative_Libs_For_RPC|Alternative Libraries]] listed below are similar in function to JSON-RPC PHP but do not have this issue.

== Precision ==

Bitcoin amounts can range from 1 Satoshi (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.

==Alternative Libs For RPC==
There are alternative PHP libraries for connecting to the bitcoind RPC which are recommended over using the plain jsonRPCClient.php class.
They do not rely on magic __call, use cURL instead of fopen and have better error handling (and can be installed using composer).

* [https://github.com/nbobtc/bitcoind-php NboBTC Bitcoind-PHP]
* [https://github.com/aceat64/EasyBitcoin-PHP EasyBitcoin-PHP]

==See Also==

* [[API reference (JSON-RPC)]]
* [[Lazy_API]]
* [https://github.com/cryptoapi/Payment-Gateway Bitcoin-PHP Payment library]
* [[Merchant Howto]]
* [[https://github.com/Bit-Wasp/bitcoin-lib-php Bitcoin-Lib-PHP - PHP Lib implementing signing of transactions, BIP32, etc]]

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

[[Category:Developer]]

Getblocktemplate

2013-03-02T13:13:24Z

Pagent:

getblocktemplate is a decentralized Bitcoin mining protocol openly developed by the Bitcoin community in 2012.
getblocktemplate supercedes the [[getwork]] mining protocol.

{{TOC limit|3}}

==Why change something that works?==

===Decentralization===
The original getwork mining protocol simply issues block headers for a miner to solve.
The miner is kept in the dark as to what is actually in this block, and has no influence over it.
In effect, the authority of the miner to decide which transactions are accepted, etc, is all transferred blindly to the pool operator.
A corrupt (or compromised) pool operator could use the combined hash power of all the miners to execute double spend attacks or other similar attacks.

getblocktemplate moves block creation to the miner, while giving pools a way to set down the rules for participation.
While pools can do just as much as they could before by expressing it in these rules, miners can not be kept in the dark and are enabled to freely choose what they participate in mining.
This improves the security of the Bitcoin network by making blocks decentralized again.

===ASICs===
The original getwork protocol only provides a single block header, which is sufficient for a total of about 4 GH of mining.
With the "rollntime" extension, this can be extended to 4 GH *per second*, but even that is far from sufficient for the next generation of mining equipment (ASICs) which are capable of 1000 GH/s on the high end.

By moving block creation to the miners, they are enabled to create as much work as they need locally, thus overcoming this limitation.

===Scalability===
Due to scalability problems, bitcoind's JSON-RPC stack has not been able to keep up with the hashrates needed for solo mining today.
Since getblocktemplate drastically reduces the load required to a single request per new block on the network, direct solo mining on bitcoind is again possible.
Poolservers likewise benefit from having to meet much lower demands of miners who can make their own blocks.

===Extensible===
The original getwork protocol was designed in a way that was very incompatible with extensions.
As a result, as new functionality was needed, extensions were "hacked in" out-of-band using HTTP headers.
getblocktemplate is designed from the start to be flexible for future extensions, and the [[BIP 0023|BIP 23]] specification already covers how the established getwork extensions can be implemented cleanly, regardless of transport protocol.

==How to use it==
===For miners===
Mining software with GBT support:
* [https://bitcointalk.org/?topic=78192.msg870395#msg870395 BFGMiner 2.8+]
* [https://bitcointalk.org/?topic=28402.msg357369#msg357369 cgminer 2.9+]
* [http://ufasoft.com/open/bitcoin/ Ufasoft Bitcoin Miner 0.39+]

The following miners have confirmed future support:
* [http://www.butterflylabs.com/drivers/ Butterfly Labs's EasyMiner]
* [https://bitcointalk.org/index.php?topic=1334.0 poclbm]

To take advantage of getblocktemplate, you also need a compatible pool:
* [https://www.bitarena.net BitArena.net]
* [https://bitminter.com BitMinter]
* [https://eclipsemc.com/ EclipseMC]
* [http://eligius.st Eligius]
* [https://pool.itzod.ru/ itzod.ru]
* [http://polmine.pl PolMine]
* [https://www.triplemining.com/ TripleMining]
* [https://www.pool.mkalinin.ru/ pool.mkalinin.ru]
* [http://mmpool.bitparking.com/pool Bitparking merged mining pool] (planned)
* [https://50btc.com/ 50BTC] (planned)
* Encourage your favourite pool(s) to support decentralized mining!

===For pool operators===
See also: [[Poolservers]]

If you are implementing your own pool server, see the [[#Poolserver software|section for poolserver development]].

===For developers===
====Mining software====
=====Using libblkmaker (C library)=====
If your miner can include C libraries, you can harness [http://gitorious.org/bitcoin/libblkmaker libblkmaker] to do all the GBT interpretation for you:
all your miner needs to do then is handle the networking (libblkmaker can prepare the JSON for you) and ask libblkmaker for data (block headers to search).
Note that libblkmaker does not provide a SHA256 implementation, and your miner needs to provide one for it to work.
libblkmaker currently only supports the Jansson JSON library, but was designed such that it can easily be ported to others;
[[User:Luke-jr|Luke Dashjr]] is willing to do this porting to other JSON libraries free of charge on request.

=====Using python-blkmaker=====
If your miner is written in Python, you can harness [http://gitorious.org/bitcoin/python-blkmaker python-blkmaker], a native Python port of libblkmaker, to do all the GBT interpretation for you:
all your miner needs to do then is handle the networking (python-blkmaker can prepare the JSON for you) and ask the blkmaker module for data (block headers to search).
A short example Python script is included that finds a prepared share using CPU mining.

=====From scratch=====
======Miner requests block template======

To start participating, the miner contacts the pool and requests an initial template:
{"id": 0, "method": "getblocktemplate", "params": [{"capabilities": ["coinbasetxn", "workid", "coinbase/append"]}]}

The server will respond with the full details needed to immediately begin mining blocks:
{
"error": null,
"result": {
"coinbasetxn": {
"data": "0100000001000000000000000000000000000000000000000000000000000000
0000000000ffffffff1302955d0f00456c6967697573005047dc66085fffffffff02fff1052a01
0000001976a9144ebeb1cd26d6227635828d60d3e0ed7d0da248fb88ac01000000000000001976
a9147c866aee1fa2f3b3d5effad576df3dbf1f07475588ac00000000"
},
"previousblockhash": "000000004d424dec1c660a68456b8271d09628a80cc62583e5904f5894a2483c",
"transactions": [],
"expires": 120,
"target": "00000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"longpollid": "some gibberish",
"height": 23957,
"version": 2,
"curtime": 1346886758,
"mutable": ["coinbase/append"],
"bits": "ffff001d"
},
"id": 0
}

======How to build coinbase transaction======
If the pool allows the "coinbase/append" mutation by including it in the "mutable" key, you can rebuild the coinbase transaction to append any data your miner wants, such as an extranonce - you can use as much space as you need so long as the coinbase data does not overflow the 100 byte hard limit.
If the server does *not* allow "coinbase/append", or you don't care to change it, you can skip this step entirely :)

The coinbase data always begins after exactly 42 bytes of the coinbase transaction.
The 42nd byte (that is, the byte immediately before the data) is the length of the data.
So when/if you want to add on to the coinbase data, simply insert it 42+DataLen bytes into the transaction, and increment the 42nd byte by the length of your inserted data.

Python example:
import binascii
coinbase = binascii.a2b_hex(template['coinbasetxn']['data'])
extradata = b'my block'
# The following can be done better in both Python 2 and Python 3, but this way works with both
origLen = ord(coinbase[41:42])
newLen = origLen + len(extradata)
coinbase = coinbase[0:41] + chr(newLen).encode('ascii') + coinbase[42:42 + origLen] + extradata + coinbase[42 + origLen:]

======How to build merkle root======
Collect your coinbase transaction (modified or not) at the front of the "transactions" list provided by the server.
Apply a double-SHA256 hash to each transaction in the list.

Now, as long as the list has more than 1 hash remaining, go through each pair and hash them together.
That is, concatenate the first two, double-SHA256 that, repeat for the next two, and so on.
If you encounter an odd pair (that is, the hash list ends with a single item and no pairing), concatenate it with itself and hash that.
Continue to do that until there is only one hash left:
that is your merkle root.

Python example:
import hashlib
def dblsha(data):
return hashlib.sha256(hashlib.sha256(data).digest()).digest()

txnlist = [coinbase] + [binascii.a2b_hex(a['data']) for a in template['transactions']]
merklehashes = [dblsha(t) for t in txnlist]
while len(merklehashes) > 1:
if len(merklehashes) % 2:
merklehashes.append(merklehashes[-1])
merklehashes = [dblsha(merklehashes[i] + merklehashes[i + 1]) for i in range(0, len(merklehashes), 2)]
merkleroot = merklehashes[0]

======How to build block header======
Assemble the block header as laid out in the Bitcoin [[block hashing algorithm]], using the data provided in the block template along with your very own merkle root.
Note that miners are expected to check the "version" number, and should not create blocks with versions they do not understand unless the server instructs them to do so with the "version/force" or "version/reduce" mutations - you don't need to support those, but if you don't support the version the server has provided, understand that the server may reject submissions if they don't meet some unknown future rules.
As of this time, the current Bitcoin block version is 2, so it is safe to build blocks with version 1 or 2.

Python example:
import struct
blkheader = struct.pack('<I', template['version']) + \
binascii.a2b_hex(template['previousblockhash']) + \
merkleroot + \
struct.pack('<I', template['curtime']) + \
binascii.a2b_hex(template['bits']) + \
b'NONC'

======While you're mining======
Since you're making all the blocks yourself, you really don't ever need to get another template... until it's invalid.
Generally, it's a good idea to refresh more often anyway to get more transactions, but it's better to let the pool decide when to do that, since it knows what's changed in the meantime already.

If your template included a "longpollid" key, you can queue a request for a new template to be executed as soon as the pool decides you should change.
This is the same as any other template request, except that you include the "longpollid" parameter that the pool provided in your request.
If there is already a new template, the pool might respond immediately, so be sure not to depend on a delay!

So to amend the template request we used initially, now we use:
{"id": 0, "method": "getblocktemplate", "params": [{
"capabilities": ["coinbasetxn", "workid", "coinbase/append"],
"longpollid": "some gibberish",
}]}

======Submitting shares======
When miner find the job which meets requested difficulty, it can submit the block to the server as a share:
{"id": 0, "method": "submitblock", "params": [
"020000003c48a294584f90e58325c60ca82896d071826b45680a661cec4d424d00000000
de6433d46c0c7f50d84a05aec77be0199176cdd47f77e344b6f50c84380fddba66dc47501d00ff
ff0000010001010000000100000000000000000000000000000000000000000000000000000000
00000000ffffffff1302955d0f00456c6967697573005047dc66085fffffffff02fff1052a0100
00001976a9144ebeb1cd26d6227635828d60d3e0ed7d0da248fb88ac01000000000000001976a9
147c866aee1fa2f3b3d5effad576df3dbf1f07475588ac00000000"
]}

To assemble the block data, simply concatenate your block header, number of transactions encoded in [[Protocol specification#Variable length integer|Bitcoin varint format]], followed by each of the transactions in your block (beginning with the coinbase).
If the server has listed "submit/coinbase" in its "mutable" key, you may opt to omit the transactions after the coinbase.

Python example:
def varintEncode(n):
if n < 0xfd:
return struct.pack('<B', n)
# NOTE: Technically, there are more encodings for numbers bigger than
# 16-bit, but transaction counts can't be that high with version 2 Bitcoin
# blocks
return b'\xfd' + struct.pack('<H', n)
blkdata = blkheader + varintEncode(len(txnlist)) + coinbase
if 'submit/coinbase' not in template.get('mutable', ()):
for txn in txnlist[1:]:
blkdata += txn

====Poolserver software====
Recommended standards to start with (in order of importance):
* [[BIP 0022|BIP 22 (non-optional sections)]]
* [[BIP 0022#Optional: Long Polling|BIP 22 Long Polling]]
* [[BIP 0023#Basic Pool Extensions|BIP 23 Basic Pool Extensions]]
* [[BIP 0023#Mutations|BIP 23 Mutation "coinbase/append"]] (required for miner extranonce rolling)
* [[BIP 0023#Submission Abbreviation|BIP 23 Submission Abbreviation "submit/coinbase"]]
* [[BIP 0023#Mutations|BIP 23 Mutation "time/increment"]] (be sure to specify "maxtime" or "maxtimeoff"!)

==Technical specifications==
* [[BIP 0022|BIP 22: getblocktemplate - Fundamentals]]
* [[BIP 0023|BIP 23: getblocktemplate - Pooled Mining]]

==History==

Getblocktemplate's origins trace back to forrestv's getmemorypool JSON-RPC method for bitcoind.
He created it so that his pool ([[P2Pool]]) could piggy-back on bitcoind so as to avoid harming the Bitcoin network (up to this point, it mined only empty blocks that never confirmed transactions).
Having been fighting with scalability problems in pushpool/bitcoind for months on his pool ([[Eligius]]), Luke-Jr set out to implement a fast pool server using getmemorypool to do its own block production (this became [[Eloipool]], this first open source makes-its-own-blocks poolserver).
Other poolservers also implemented block creation using getmemorypool over the months following.

At about the same time, interest in decentralizing pooled mining became a hot topic.
While [[BitPenny]] had initially released its own decentralized mining proxy months prior, [[P2Pool]]'s implementation became rapidly popular.
Anyone involved in Bitcoin mining protocols could see the need to move control of block creation back into the hands of the miners.
Unfortunately, both [[BitPenny]] and [[P2Pool]] had used very pool-specific proprietary protocols to implement their decentralization.
On the other hand, getmemorypool was *almost* a perfect fit for the task - it just lacked support for the now-ubiquitous pooled mining extensions that had developed around the getwork protocol over time.

In February of 2012, Luke implemented and [https://bitcointalk.org/?topic=23768.msg774497#msg774497 deployed] a first draft of getmemorypool mining support in [[Eloipool]] (and on [[Eligius]]) along with a proof-of-concept getwork proxy (now known as gmp-proxy), adding revisions as needed to function as a general-purpose decentralized mining protocol.
After he had confirmed it was working, he documented and proposed it on the [[Bitcoin development mailing list]] for review on February 28th, where discussion began on what was missing and what needed to be changed or clarified.
During the following few months, a number of others, both developers and testers, provided constructive criticism and suggestions, which were integrated into the standard.
Luke also actively encouraged participation in the development of the standard among pool operators and poolserver authors, especially as it became necessary to move forward into the ASIC "mining generation".
Eventually, it was decided it would be best to rename it to the more appropriate "getblocktemplate" name and drop backward compatibility with getmemorypool for simplicity.
The standard was split into two pieces and the technical specification can be found in [[BIP 0022|BIP 22]] and [[BIP 0023|BIP 23]].

==See also==
* [https://bitcointalk.org/?topic=108854 BitcoinTalk forum thread]
* [[BIP 0022|BIP 22: getblocktemplate - Fundamentals]] (technical)
* [[BIP 0023|BIP 23: getblocktemplate - Pooled Mining]] (technical)

Getblocktemplate

2013-03-02T13:11:46Z

Pagent: Removed speculation that getblocktemplate will supercede other getwork replacements (stratum)

getblocktemplate is a decentralized Bitcoin mining protocol openly developed by the Bitcoin community in 2012.
getblocktemplate supercedes the old getwork mining protocol.

{{TOC limit|3}}

==Why change something that works?==

===Decentralization===
The original getwork mining protocol simply issues block headers for a miner to solve.
The miner is kept in the dark as to what is actually in this block, and has no influence over it.
In effect, the authority of the miner to decide which transactions are accepted, etc, is all transferred blindly to the pool operator.
A corrupt (or compromised) pool operator could use the combined hash power of all the miners to execute double spend attacks or other similar attacks.

getblocktemplate moves block creation to the miner, while giving pools a way to set down the rules for participation.
While pools can do just as much as they could before by expressing it in these rules, miners can not be kept in the dark and are enabled to freely choose what they participate in mining.
This improves the security of the Bitcoin network by making blocks decentralized again.

===ASICs===
The original getwork protocol only provides a single block header, which is sufficient for a total of about 4 GH of mining.
With the "rollntime" extension, this can be extended to 4 GH *per second*, but even that is far from sufficient for the next generation of mining equipment (ASICs) which are capable of 1000 GH/s on the high end.

By moving block creation to the miners, they are enabled to create as much work as they need locally, thus overcoming this limitation.

===Scalability===
Due to scalability problems, bitcoind's JSON-RPC stack has not been able to keep up with the hashrates needed for solo mining today.
Since getblocktemplate drastically reduces the load required to a single request per new block on the network, direct solo mining on bitcoind is again possible.
Poolservers likewise benefit from having to meet much lower demands of miners who can make their own blocks.

===Extensible===
The original getwork protocol was designed in a way that was very incompatible with extensions.
As a result, as new functionality was needed, extensions were "hacked in" out-of-band using HTTP headers.
getblocktemplate is designed from the start to be flexible for future extensions, and the [[BIP 0023|BIP 23]] specification already covers how the established getwork extensions can be implemented cleanly, regardless of transport protocol.

==How to use it==
===For miners===
Mining software with GBT support:
* [https://bitcointalk.org/?topic=78192.msg870395#msg870395 BFGMiner 2.8+]
* [https://bitcointalk.org/?topic=28402.msg357369#msg357369 cgminer 2.9+]
* [http://ufasoft.com/open/bitcoin/ Ufasoft Bitcoin Miner 0.39+]

The following miners have confirmed future support:
* [http://www.butterflylabs.com/drivers/ Butterfly Labs's EasyMiner]
* [https://bitcointalk.org/index.php?topic=1334.0 poclbm]

To take advantage of getblocktemplate, you also need a compatible pool:
* [https://www.bitarena.net BitArena.net]
* [https://bitminter.com BitMinter]
* [https://eclipsemc.com/ EclipseMC]
* [http://eligius.st Eligius]
* [https://pool.itzod.ru/ itzod.ru]
* [http://polmine.pl PolMine]
* [https://www.triplemining.com/ TripleMining]
* [https://www.pool.mkalinin.ru/ pool.mkalinin.ru]
* [http://mmpool.bitparking.com/pool Bitparking merged mining pool] (planned)
* [https://50btc.com/ 50BTC] (planned)
* Encourage your favourite pool(s) to support decentralized mining!

===For pool operators===
See also: [[Poolservers]]

If you are implementing your own pool server, see the [[#Poolserver software|section for poolserver development]].

===For developers===
====Mining software====
=====Using libblkmaker (C library)=====
If your miner can include C libraries, you can harness [http://gitorious.org/bitcoin/libblkmaker libblkmaker] to do all the GBT interpretation for you:
all your miner needs to do then is handle the networking (libblkmaker can prepare the JSON for you) and ask libblkmaker for data (block headers to search).
Note that libblkmaker does not provide a SHA256 implementation, and your miner needs to provide one for it to work.
libblkmaker currently only supports the Jansson JSON library, but was designed such that it can easily be ported to others;
[[User:Luke-jr|Luke Dashjr]] is willing to do this porting to other JSON libraries free of charge on request.

=====Using python-blkmaker=====
If your miner is written in Python, you can harness [http://gitorious.org/bitcoin/python-blkmaker python-blkmaker], a native Python port of libblkmaker, to do all the GBT interpretation for you:
all your miner needs to do then is handle the networking (python-blkmaker can prepare the JSON for you) and ask the blkmaker module for data (block headers to search).
A short example Python script is included that finds a prepared share using CPU mining.

=====From scratch=====
======Miner requests block template======

To start participating, the miner contacts the pool and requests an initial template:
{"id": 0, "method": "getblocktemplate", "params": [{"capabilities": ["coinbasetxn", "workid", "coinbase/append"]}]}

The server will respond with the full details needed to immediately begin mining blocks:
{
"error": null,
"result": {
"coinbasetxn": {
"data": "0100000001000000000000000000000000000000000000000000000000000000
0000000000ffffffff1302955d0f00456c6967697573005047dc66085fffffffff02fff1052a01
0000001976a9144ebeb1cd26d6227635828d60d3e0ed7d0da248fb88ac01000000000000001976
a9147c866aee1fa2f3b3d5effad576df3dbf1f07475588ac00000000"
},
"previousblockhash": "000000004d424dec1c660a68456b8271d09628a80cc62583e5904f5894a2483c",
"transactions": [],
"expires": 120,
"target": "00000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"longpollid": "some gibberish",
"height": 23957,
"version": 2,
"curtime": 1346886758,
"mutable": ["coinbase/append"],
"bits": "ffff001d"
},
"id": 0
}

======How to build coinbase transaction======
If the pool allows the "coinbase/append" mutation by including it in the "mutable" key, you can rebuild the coinbase transaction to append any data your miner wants, such as an extranonce - you can use as much space as you need so long as the coinbase data does not overflow the 100 byte hard limit.
If the server does *not* allow "coinbase/append", or you don't care to change it, you can skip this step entirely :)

The coinbase data always begins after exactly 42 bytes of the coinbase transaction.
The 42nd byte (that is, the byte immediately before the data) is the length of the data.
So when/if you want to add on to the coinbase data, simply insert it 42+DataLen bytes into the transaction, and increment the 42nd byte by the length of your inserted data.

Python example:
import binascii
coinbase = binascii.a2b_hex(template['coinbasetxn']['data'])
extradata = b'my block'
# The following can be done better in both Python 2 and Python 3, but this way works with both
origLen = ord(coinbase[41:42])
newLen = origLen + len(extradata)
coinbase = coinbase[0:41] + chr(newLen).encode('ascii') + coinbase[42:42 + origLen] + extradata + coinbase[42 + origLen:]

======How to build merkle root======
Collect your coinbase transaction (modified or not) at the front of the "transactions" list provided by the server.
Apply a double-SHA256 hash to each transaction in the list.

Now, as long as the list has more than 1 hash remaining, go through each pair and hash them together.
That is, concatenate the first two, double-SHA256 that, repeat for the next two, and so on.
If you encounter an odd pair (that is, the hash list ends with a single item and no pairing), concatenate it with itself and hash that.
Continue to do that until there is only one hash left:
that is your merkle root.

Python example:
import hashlib
def dblsha(data):
return hashlib.sha256(hashlib.sha256(data).digest()).digest()

txnlist = [coinbase] + [binascii.a2b_hex(a['data']) for a in template['transactions']]
merklehashes = [dblsha(t) for t in txnlist]
while len(merklehashes) > 1:
if len(merklehashes) % 2:
merklehashes.append(merklehashes[-1])
merklehashes = [dblsha(merklehashes[i] + merklehashes[i + 1]) for i in range(0, len(merklehashes), 2)]
merkleroot = merklehashes[0]

======How to build block header======
Assemble the block header as laid out in the Bitcoin [[block hashing algorithm]], using the data provided in the block template along with your very own merkle root.
Note that miners are expected to check the "version" number, and should not create blocks with versions they do not understand unless the server instructs them to do so with the "version/force" or "version/reduce" mutations - you don't need to support those, but if you don't support the version the server has provided, understand that the server may reject submissions if they don't meet some unknown future rules.
As of this time, the current Bitcoin block version is 2, so it is safe to build blocks with version 1 or 2.

Python example:
import struct
blkheader = struct.pack('<I', template['version']) + \
binascii.a2b_hex(template['previousblockhash']) + \
merkleroot + \
struct.pack('<I', template['curtime']) + \
binascii.a2b_hex(template['bits']) + \
b'NONC'

======While you're mining======
Since you're making all the blocks yourself, you really don't ever need to get another template... until it's invalid.
Generally, it's a good idea to refresh more often anyway to get more transactions, but it's better to let the pool decide when to do that, since it knows what's changed in the meantime already.

If your template included a "longpollid" key, you can queue a request for a new template to be executed as soon as the pool decides you should change.
This is the same as any other template request, except that you include the "longpollid" parameter that the pool provided in your request.
If there is already a new template, the pool might respond immediately, so be sure not to depend on a delay!

So to amend the template request we used initially, now we use:
{"id": 0, "method": "getblocktemplate", "params": [{
"capabilities": ["coinbasetxn", "workid", "coinbase/append"],
"longpollid": "some gibberish",
}]}

======Submitting shares======
When miner find the job which meets requested difficulty, it can submit the block to the server as a share:
{"id": 0, "method": "submitblock", "params": [
"020000003c48a294584f90e58325c60ca82896d071826b45680a661cec4d424d00000000
de6433d46c0c7f50d84a05aec77be0199176cdd47f77e344b6f50c84380fddba66dc47501d00ff
ff0000010001010000000100000000000000000000000000000000000000000000000000000000
00000000ffffffff1302955d0f00456c6967697573005047dc66085fffffffff02fff1052a0100
00001976a9144ebeb1cd26d6227635828d60d3e0ed7d0da248fb88ac01000000000000001976a9
147c866aee1fa2f3b3d5effad576df3dbf1f07475588ac00000000"
]}

To assemble the block data, simply concatenate your block header, number of transactions encoded in [[Protocol specification#Variable length integer|Bitcoin varint format]], followed by each of the transactions in your block (beginning with the coinbase).
If the server has listed "submit/coinbase" in its "mutable" key, you may opt to omit the transactions after the coinbase.

Python example:
def varintEncode(n):
if n < 0xfd:
return struct.pack('<B', n)
# NOTE: Technically, there are more encodings for numbers bigger than
# 16-bit, but transaction counts can't be that high with version 2 Bitcoin
# blocks
return b'\xfd' + struct.pack('<H', n)
blkdata = blkheader + varintEncode(len(txnlist)) + coinbase
if 'submit/coinbase' not in template.get('mutable', ()):
for txn in txnlist[1:]:
blkdata += txn

====Poolserver software====
Recommended standards to start with (in order of importance):
* [[BIP 0022|BIP 22 (non-optional sections)]]
* [[BIP 0022#Optional: Long Polling|BIP 22 Long Polling]]
* [[BIP 0023#Basic Pool Extensions|BIP 23 Basic Pool Extensions]]
* [[BIP 0023#Mutations|BIP 23 Mutation "coinbase/append"]] (required for miner extranonce rolling)
* [[BIP 0023#Submission Abbreviation|BIP 23 Submission Abbreviation "submit/coinbase"]]
* [[BIP 0023#Mutations|BIP 23 Mutation "time/increment"]] (be sure to specify "maxtime" or "maxtimeoff"!)

==Technical specifications==
* [[BIP 0022|BIP 22: getblocktemplate - Fundamentals]]
* [[BIP 0023|BIP 23: getblocktemplate - Pooled Mining]]

==History==

Getblocktemplate's origins trace back to forrestv's getmemorypool JSON-RPC method for bitcoind.
He created it so that his pool ([[P2Pool]]) could piggy-back on bitcoind so as to avoid harming the Bitcoin network (up to this point, it mined only empty blocks that never confirmed transactions).
Having been fighting with scalability problems in pushpool/bitcoind for months on his pool ([[Eligius]]), Luke-Jr set out to implement a fast pool server using getmemorypool to do its own block production (this became [[Eloipool]], this first open source makes-its-own-blocks poolserver).
Other poolservers also implemented block creation using getmemorypool over the months following.

At about the same time, interest in decentralizing pooled mining became a hot topic.
While [[BitPenny]] had initially released its own decentralized mining proxy months prior, [[P2Pool]]'s implementation became rapidly popular.
Anyone involved in Bitcoin mining protocols could see the need to move control of block creation back into the hands of the miners.
Unfortunately, both [[BitPenny]] and [[P2Pool]] had used very pool-specific proprietary protocols to implement their decentralization.
On the other hand, getmemorypool was *almost* a perfect fit for the task - it just lacked support for the now-ubiquitous pooled mining extensions that had developed around the getwork protocol over time.

In February of 2012, Luke implemented and [https://bitcointalk.org/?topic=23768.msg774497#msg774497 deployed] a first draft of getmemorypool mining support in [[Eloipool]] (and on [[Eligius]]) along with a proof-of-concept getwork proxy (now known as gmp-proxy), adding revisions as needed to function as a general-purpose decentralized mining protocol.
After he had confirmed it was working, he documented and proposed it on the [[Bitcoin development mailing list]] for review on February 28th, where discussion began on what was missing and what needed to be changed or clarified.
During the following few months, a number of others, both developers and testers, provided constructive criticism and suggestions, which were integrated into the standard.
Luke also actively encouraged participation in the development of the standard among pool operators and poolserver authors, especially as it became necessary to move forward into the ASIC "mining generation".
Eventually, it was decided it would be best to rename it to the more appropriate "getblocktemplate" name and drop backward compatibility with getmemorypool for simplicity.
The standard was split into two pieces and the technical specification can be found in [[BIP 0022|BIP 22]] and [[BIP 0023|BIP 23]].

==See also==
* [https://bitcointalk.org/?topic=108854 BitcoinTalk forum thread]
* [[BIP 0022|BIP 22: getblocktemplate - Fundamentals]] (technical)
* [[BIP 0023|BIP 23: getblocktemplate - Pooled Mining]] (technical)