https://en.bitcoin.it/w/api.php?action=feedcontributions&user=Gavinandresen&feedformat=atomBitcoin Wiki - User contributions [en]2024-03-19T09:07:26ZUser contributionsMediaWiki 1.30.0https://en.bitcoin.it/w/index.php?title=API_reference_(JSON-RPC)&diff=50305API reference (JSON-RPC)2014-08-19T13:56:52Z<p>Gavinandresen: JSON-RPC client has been split out from bitcoind, is now bitcoin-cli</p>
<hr />
<div>== Controlling Bitcoin ==<br />
<br />
Run ''bitcoind'' or ''bitcoin-qt -server''. You can control it via the command-line bitcoin-cli utility or by [http://json-rpc.org/wiki/specification HTTP JSON-RPC] commands.<br />
<br />
You must create a bitcoin.conf configuration file setting an rpcuser and rpcpassword; see [[Running Bitcoin]] for details.<br />
<br />
Now run:<br />
$ ./bitcoind -daemon<br />
bitcoin server starting<br />
$ ./bitcoin-cli -rpcwait help<br />
# shows the help text<br />
<br />
A [[Original Bitcoin client/API Calls list|list of RPC calls]] will be shown.<br />
<br />
$ ./bitcoin-cli getbalance<br />
2000.00000<br />
<br />
If you are learning the API, it is a very good idea to use the test network (run bitcoind -testnet and bitcoin-cli -testnet).<br />
<br />
== JSON-RPC ==<br />
<br />
Running Bitcoin with the -server argument (or running bitcoind) tells it to function as a [http://json-rpc.org/wiki/specification HTTP JSON-RPC] server, but <br />
[http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication] must be used when communicating with it, and, for security, by default, the server only accepts connections from other processes on the same machine. If your HTTP or JSON library requires you to specify which 'realm' is authenticated, use 'jsonrpc'.<br />
<br />
Bitcoin supports SSL (https) JSON-RPC connections beginning with version 0.3.14. See the [[Enabling SSL on original client daemon|rpcssl wiki page]] for setup instructions and a list of all bitcoin.conf configuration options.<br />
<br />
Allowing arbitrary machines to access the JSON-RPC port (using the rpcallowip [[Running_Bitcoin|configuration option]]) is dangerous and '''strongly discouraged'''-- access should be strictly limited to trusted machines.<br />
<br />
To access the server you should find a [http://json-rpc.org/wiki/implementations suitable library] for your language.<br />
<br />
== Proper money handling ==<br />
<br />
See the [[Proper Money Handling (JSON-RPC)|proper money handling page]] for notes on avoiding rounding errors when handling bitcoin values.<br />
<br />
== Python ==<br />
<br />
[http://json-rpc.org/wiki/python-json-rpc python-jsonrpc] is the official JSON-RPC implementation for Python.<br />
It automatically generates Python methods for RPC calls.<br />
However, due to its design for supporting old versions of Python, it is also rather inefficient.<br />
[[User:jgarzik|jgarzik]] has forked it as [https://github.com/jgarzik/python-bitcoinrpc Python-BitcoinRPC] and optimized it for current versions.<br />
Generally, this version is recommended.<br />
<br />
While BitcoinRPC lacks a few obscure features from jsonrpc, software using only the ServiceProxy class can be written the same to work with either version the user might choose to install:<br />
<br />
<source lang="python"><br />
from jsonrpc import ServiceProxy<br />
<br />
access = ServiceProxy("http://user:password@127.0.0.1:8332")<br />
access.getinfo()<br />
access.listreceivedbyaddress(6)<br />
#access.sendtoaddress("11yEmxiMso2RsFVfBcCa616npBvGgxiBX", 10)<br />
</source><br />
<br />
The latest version of python-bitcoinrpc has a new syntax.<br />
<source lang="python"><br />
from bitcoinrpc.authproxy import AuthServiceProxy<br />
</source><br />
<br />
== Ruby ==<br />
<br />
<source lang="ruby"><br />
require 'net/http'<br />
require 'uri'<br />
require 'json'<br />
<br />
class BitcoinRPC<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.basic_auth @uri.user, @uri.password<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
<br />
if $0 == __FILE__<br />
h = BitcoinRPC.new('http://user:password@127.0.0.1:8332')<br />
p h.getbalance<br />
p h.getinfo<br />
p h.getnewaddress<br />
p h.dumpprivkey( h.getnewaddress )<br />
# also see: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list<br />
end<br />
</source><br />
<br />
== PHP ==<br />
<br />
The [http://jsonrpcphp.org/ JSON-RPC PHP] library also makes it very easy to connect to Bitcoin. For example:<br />
<br />
<source lang="php"><br />
require_once 'jsonRPCClient.php';<br />
<br />
$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');<br />
<br />
echo "<pre>\n";<br />
print_r($bitcoin->getinfo()); echo "\n";<br />
echo "Received: ".$bitcoin->getreceivedbylabel("Your Address")."\n";<br />
echo "</pre>";<br />
</source><br />
<br />
'''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 [https://github.com/aceat64/EasyBitcoin-PHP EasyBitcoin-PHP library] is similar in function to JSON-RPC PHP but does not have this issue.<br />
<br />
== Java ==<br />
<br />
The easiest way to tell Java to use HTTP Basic authentication is to set a default Authenticator:<br />
<br />
<source lang="java"><br />
final String rpcuser ="...";<br />
final String rpcpassword ="...";<br />
<br />
Authenticator.setDefault(new Authenticator() {<br />
protected PasswordAuthentication getPasswordAuthentication() {<br />
return new PasswordAuthentication (rpcuser, rpcpassword.toCharArray());<br />
}<br />
});<br />
</source><br />
<br />
Once that is done, [http://json-rpc.org/wiki/implementations any JSON-RPC library for Java] (or ordinary URL POSTs) may be used to communicate with the Bitcoin server.<br />
<br />
== Perl ==<br />
<br />
The JSON::RPC package from CPAN can be used to communicate with Bitcoin. You must set the client's credentials; for example:<br />
<br />
<source lang="perl"><br />
use JSON::RPC::Client;<br />
use Data::Dumper;<br />
<br />
my $client = new JSON::RPC::Client;<br />
<br />
$client->ua->credentials(<br />
'localhost:8332', 'jsonrpc', 'user' => 'password' # REPLACE WITH YOUR bitcoin.conf rpcuser/rpcpassword<br />
);<br />
<br />
my $uri = 'http://localhost:8332/';<br />
my $obj = {<br />
method => 'getinfo',<br />
params => [],<br />
};<br />
<br />
my $res = $client->call( $uri, $obj );<br />
<br />
if ($res){<br />
if ($res->is_error) { print "Error : ", $res->error_message; }<br />
else { print Dumper($res->result); }<br />
} else {<br />
print $client->status_line;<br />
}<br />
</source><br />
<br />
== Go ==<br />
<br />
The [https://github.com/conformal/btcrpcclient btcrpcclient package] can be used to communicate with Bitcoin. You must provide credentials to match the client you are communicating with.<br />
<br />
<source lang="go"><br />
package main<br />
<br />
import (<br />
"github.com/conformal/btcnet"<br />
"github.com/conformal/btcrpcclient"<br />
"github.com/conformal/btcutil"<br />
"log"<br />
)<br />
<br />
func main() {<br />
// create new client instance<br />
client, err := btcrpcclient.New(&btcrpcclient.ConnConfig{<br />
HttpPostMode: true,<br />
DisableTLS: true,<br />
Host: "127.0.0.1:8332",<br />
User: "rpcUsername",<br />
Pass: "rpcPassword",<br />
}, nil)<br />
if err != nil {<br />
log.Fatalf("error creating new btc client: %v", err)<br />
}<br />
<br />
// list accounts<br />
accounts, err := client.ListAccounts()<br />
if err != nil {<br />
log.Fatalf("error listing accounts: %v", err)<br />
}<br />
// iterate over accounts (map[string]btcutil.Amount) and write to stdout<br />
for label, amount := range accounts {<br />
log.Printf("%s: %s", label, amount)<br />
}<br />
<br />
// prepare a sendMany transaction<br />
receiver1, err := btcutil.DecodeAddress("1someAddressThatIsActuallyReal", &btcnet.MainNetParams)<br />
if err != nil {<br />
log.Fatalf("address receiver1 seems to be invalid: %v", err)<br />
}<br />
receiver2, err := btcutil.DecodeAddress("1anotherAddressThatsPrettyReal", &btcnet.MainNetParams)<br />
if err != nil {<br />
log.Fatalf("address receiver2 seems to be invalid: %v", err)<br />
}<br />
receivers := map[btcutil.Address]btcutil.Amount{<br />
receiver1: 42, // 42 satoshi<br />
receiver2: 100, // 100 satoshi<br />
}<br />
<br />
// create and send the sendMany tx<br />
txSha, err := client.SendMany("some-account-label-from-which-to-send", receivers)<br />
if err != nil {<br />
log.Fatalf("error sendMany: %v", err)<br />
}<br />
log.Printf("sendMany completed! tx sha is: %s", txSha.String())<br />
}<br />
</source><br />
<br />
== .NET (C#) ==<br />
The communication with rpc service can be achieved using the standard http request/response objects.<br />
A library for serialising and deserializing Json will make your life a lot easier:<br />
<br />
Json.Net ( http://james.newtonking.com/json ) is a high performance JSON package for .Net. It is also available via NuGet from the package manager console ( Install-Package Newtonsoft.Json ).<br />
<br />
The following example uses Json.Net:<br />
<br />
<source lang="csharp"><br />
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("http://localhost.:8332");<br />
webRequest.Credentials = new NetworkCredential("user", "pwd");<br />
/// important, otherwise the service can't desirialse your request properly<br />
webRequest.ContentType = "application/json-rpc";<br />
webRequest.Method = "POST";<br />
<br />
JObject joe = new JObject();<br />
joe.Add(new JProperty("jsonrpc", "1.0"));<br />
joe.Add(new JProperty("id", "1"));<br />
joe.Add(new JProperty("method", Method));<br />
// params is a collection values which the method requires..<br />
if (Params.Keys.Count == 0)<br />
{<br />
joe.Add(new JProperty("params", new JArray()));<br />
}<br />
else<br />
{<br />
JArray props = new JArray();<br />
// add the props in the reverse order!<br />
for (int i = Params.Keys.Count - 1; i >= 0; i--)<br />
{<br />
.... // add the params<br />
}<br />
joe.Add(new JProperty("params", props));<br />
}<br />
<br />
// serialize json for the request<br />
string s = JsonConvert.SerializeObject(joe);<br />
byte[] byteArray = Encoding.UTF8.GetBytes(s);<br />
webRequest.ContentLength = byteArray.Length;<br />
Stream dataStream = webRequest.GetRequestStream();<br />
dataStream.Write(byteArray, 0, byteArray.Length);<br />
dataStream.Close();<br />
<br />
<br />
WebResponse webResponse = webRequest.GetResponse();<br />
<br />
... // deserialze the response<br />
</source><br />
<br />
There is also a wrapper for Json.NET called Bitnet (https://sourceforge.net/projects/bitnet)<br />
implementing Bitcoin API in more convenient way:<br />
<br />
<source lang="csharp"><br />
BitnetClient bc = new BitnetClient("http://127.0.0.1:8332");<br />
bc.Credentials = new NetworkCredential("user", "pass");<br />
<br />
var p = bc.GetDifficulty();<br />
Console.WriteLine("Difficulty:" + p.ToString());<br />
<br />
var inf = bc.GetInfo();<br />
Console.WriteLine("Balance:" + inf["balance"]);<br />
</source><br />
<br />
== Node.js ==<br />
<br />
* [https://github.com/freewil/node-bitcoin node-bitcoin] (npm: bitcoin) <br />
<br />
Example using node-bitcoin:<br />
<br />
<source lang="javascript"><br />
var bitcoin = require('bitcoin');<br />
var client = new bitcoin.Client({<br />
host: 'localhost',<br />
port: 8332,<br />
user: 'user',<br />
pass: 'pass'<br />
});<br />
<br />
client.getDifficulty(function(err, difficulty) {<br />
if (err) {<br />
return console.error(err);<br />
}<br />
<br />
console.log('Difficulty: ' + difficulty);<br />
});<br />
</source><br />
<br />
Example using Kapitalize:<br />
<br />
<source lang='javascript'><br />
var client = require('kapitalize')()<br />
<br />
client.auth('user', 'password')<br />
<br />
client<br />
.getInfo()<br />
.getDifficulty(function(err, difficulty) {<br />
console.log('Dificulty: ', difficulty)<br />
})<br />
</source><br />
<br />
== Command line (cURL) ==<br />
<br />
You can also send commands and see results using [http://curl.haxx.se/ cURL] or some other command-line HTTP-fetching utility; for example:<br />
<br />
<source lang="bash"><br />
curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' <br />
-H 'content-type: text/plain;' http://127.0.0.1:8332/<br />
</source><br />
<br />
You will be prompted for your rpcpassword, and then will see something like:<br />
<br />
<source lang="javascript"><br />
{"result":{"balance":0.000000000000000,"blocks":59952,"connections":48,"proxy":"","generate":false,<br />
"genproclimit":-1,"difficulty":16.61907875185736,"error":null,"id":"curltest"}<br />
</source><br />
<br />
== Clojure ==<br />
<br />
[https://github.com/aviad/clj-btc clj-btc] is a Clojure wrapper for the bitcoin API.<br />
<br />
<source lang="clojure"><br />
user=> (require '[clj-btc.core :as btc])<br />
nil<br />
user=> (btc/getinfo)<br />
{"timeoffset" 0, "protocolversion" 70001, "blocks" 111908, "errors" "",<br />
"testnet" true, "proxy" "", "connections" 4, "version" 80500,<br />
"keypoololdest" 1380388750, "paytxfee" 0E-8M,<br />
"difficulty" 4642.44443532M, "keypoolsize" 101, "balance" 0E-8M,<br />
"walletversion" 60000}<br />
</source><br />
<br />
== See Also==<br />
<br />
* [[Original_Bitcoin_client/API_Calls_list|API calls list]]<br />
* [[Running Bitcoin]]<br />
* [[Lazy API]]<br />
* [[PHP developer intro]]<br />
* [[Raw_Transactions|Raw Transactions API]]<br />
* [http://blockchain.info/api/json_rpc_api Web Based JSON RPC interface.]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
[[zh-cn:API_reference_(JSON-RPC)]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=API_reference_(JSON-RPC)&diff=50304API reference (JSON-RPC)2014-08-19T13:52:10Z<p>Gavinandresen: JSON-RPC client has been split out from bitcoind, is now bitcoin-cli</p>
<hr />
<div>== Controlling Bitcoin ==<br />
<br />
Run ''bitcoind'' or ''bitcoin-qt -server''. You can control it via the command-line bitcoin-cli utility or by [http://json-rpc.org/wiki/specification HTTP JSON-RPC] commands.<br />
<br />
You must create a bitcoin.conf configuration file setting an rpcuser and rpcpassword; see [[Running Bitcoin]] for details.<br />
<br />
Now run:<br />
$ ./bitcoind -daemon<br />
bitcoin server starting<br />
$ ./bitcoin-cli help<br />
# shows the help text<br />
<br />
A [[Original Bitcoin client/API Calls list|list of RPC calls]] will be shown.<br />
<br />
$ ./bitcoin-cli getbalance<br />
2000.00000<br />
<br />
== JSON-RPC ==<br />
<br />
Running Bitcoin with the -server argument (or running bitcoind) tells it to function as a [http://json-rpc.org/wiki/specification HTTP JSON-RPC] server, but <br />
[http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication] must be used when communicating with it, and, for security, by default, the server only accepts connections from other processes on the same machine. If your HTTP or JSON library requires you to specify which 'realm' is authenticated, use 'jsonrpc'.<br />
<br />
Bitcoin supports SSL (https) JSON-RPC connections beginning with version 0.3.14. See the [[Enabling SSL on original client daemon|rpcssl wiki page]] for setup instructions and a list of all bitcoin.conf configuration options.<br />
<br />
Allowing arbitrary machines to access the JSON-RPC port (using the rpcallowip [[Running_Bitcoin|configuration option]]) is dangerous and '''strongly discouraged'''-- access should be strictly limited to trusted machines.<br />
<br />
To access the server you should find a [http://json-rpc.org/wiki/implementations suitable library] for your language.<br />
<br />
== Proper money handling ==<br />
<br />
See the [[Proper Money Handling (JSON-RPC)|proper money handling page]] for notes on avoiding rounding errors when handling bitcoin values.<br />
<br />
== Python ==<br />
<br />
[http://json-rpc.org/wiki/python-json-rpc python-jsonrpc] is the official JSON-RPC implementation for Python.<br />
It automatically generates Python methods for RPC calls.<br />
However, due to its design for supporting old versions of Python, it is also rather inefficient.<br />
[[User:jgarzik|jgarzik]] has forked it as [https://github.com/jgarzik/python-bitcoinrpc Python-BitcoinRPC] and optimized it for current versions.<br />
Generally, this version is recommended.<br />
<br />
While BitcoinRPC lacks a few obscure features from jsonrpc, software using only the ServiceProxy class can be written the same to work with either version the user might choose to install:<br />
<br />
<source lang="python"><br />
from jsonrpc import ServiceProxy<br />
<br />
access = ServiceProxy("http://user:password@127.0.0.1:8332")<br />
access.getinfo()<br />
access.listreceivedbyaddress(6)<br />
#access.sendtoaddress("11yEmxiMso2RsFVfBcCa616npBvGgxiBX", 10)<br />
</source><br />
<br />
The latest version of python-bitcoinrpc has a new syntax.<br />
<source lang="python"><br />
from bitcoinrpc.authproxy import AuthServiceProxy<br />
</source><br />
<br />
== Ruby ==<br />
<br />
<source lang="ruby"><br />
require 'net/http'<br />
require 'uri'<br />
require 'json'<br />
<br />
class BitcoinRPC<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.basic_auth @uri.user, @uri.password<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
<br />
if $0 == __FILE__<br />
h = BitcoinRPC.new('http://user:password@127.0.0.1:8332')<br />
p h.getbalance<br />
p h.getinfo<br />
p h.getnewaddress<br />
p h.dumpprivkey( h.getnewaddress )<br />
# also see: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list<br />
end<br />
</source><br />
<br />
== PHP ==<br />
<br />
The [http://jsonrpcphp.org/ JSON-RPC PHP] library also makes it very easy to connect to Bitcoin. For example:<br />
<br />
<source lang="php"><br />
require_once 'jsonRPCClient.php';<br />
<br />
$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');<br />
<br />
echo "<pre>\n";<br />
print_r($bitcoin->getinfo()); echo "\n";<br />
echo "Received: ".$bitcoin->getreceivedbylabel("Your Address")."\n";<br />
echo "</pre>";<br />
</source><br />
<br />
'''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 [https://github.com/aceat64/EasyBitcoin-PHP EasyBitcoin-PHP library] is similar in function to JSON-RPC PHP but does not have this issue.<br />
<br />
== Java ==<br />
<br />
The easiest way to tell Java to use HTTP Basic authentication is to set a default Authenticator:<br />
<br />
<source lang="java"><br />
final String rpcuser ="...";<br />
final String rpcpassword ="...";<br />
<br />
Authenticator.setDefault(new Authenticator() {<br />
protected PasswordAuthentication getPasswordAuthentication() {<br />
return new PasswordAuthentication (rpcuser, rpcpassword.toCharArray());<br />
}<br />
});<br />
</source><br />
<br />
Once that is done, [http://json-rpc.org/wiki/implementations any JSON-RPC library for Java] (or ordinary URL POSTs) may be used to communicate with the Bitcoin server.<br />
<br />
== Perl ==<br />
<br />
The JSON::RPC package from CPAN can be used to communicate with Bitcoin. You must set the client's credentials; for example:<br />
<br />
<source lang="perl"><br />
use JSON::RPC::Client;<br />
use Data::Dumper;<br />
<br />
my $client = new JSON::RPC::Client;<br />
<br />
$client->ua->credentials(<br />
'localhost:8332', 'jsonrpc', 'user' => 'password' # REPLACE WITH YOUR bitcoin.conf rpcuser/rpcpassword<br />
);<br />
<br />
my $uri = 'http://localhost:8332/';<br />
my $obj = {<br />
method => 'getinfo',<br />
params => [],<br />
};<br />
<br />
my $res = $client->call( $uri, $obj );<br />
<br />
if ($res){<br />
if ($res->is_error) { print "Error : ", $res->error_message; }<br />
else { print Dumper($res->result); }<br />
} else {<br />
print $client->status_line;<br />
}<br />
</source><br />
<br />
== Go ==<br />
<br />
The [https://github.com/conformal/btcrpcclient btcrpcclient package] can be used to communicate with Bitcoin. You must provide credentials to match the client you are communicating with.<br />
<br />
<source lang="go"><br />
package main<br />
<br />
import (<br />
"github.com/conformal/btcnet"<br />
"github.com/conformal/btcrpcclient"<br />
"github.com/conformal/btcutil"<br />
"log"<br />
)<br />
<br />
func main() {<br />
// create new client instance<br />
client, err := btcrpcclient.New(&btcrpcclient.ConnConfig{<br />
HttpPostMode: true,<br />
DisableTLS: true,<br />
Host: "127.0.0.1:8332",<br />
User: "rpcUsername",<br />
Pass: "rpcPassword",<br />
}, nil)<br />
if err != nil {<br />
log.Fatalf("error creating new btc client: %v", err)<br />
}<br />
<br />
// list accounts<br />
accounts, err := client.ListAccounts()<br />
if err != nil {<br />
log.Fatalf("error listing accounts: %v", err)<br />
}<br />
// iterate over accounts (map[string]btcutil.Amount) and write to stdout<br />
for label, amount := range accounts {<br />
log.Printf("%s: %s", label, amount)<br />
}<br />
<br />
// prepare a sendMany transaction<br />
receiver1, err := btcutil.DecodeAddress("1someAddressThatIsActuallyReal", &btcnet.MainNetParams)<br />
if err != nil {<br />
log.Fatalf("address receiver1 seems to be invalid: %v", err)<br />
}<br />
receiver2, err := btcutil.DecodeAddress("1anotherAddressThatsPrettyReal", &btcnet.MainNetParams)<br />
if err != nil {<br />
log.Fatalf("address receiver2 seems to be invalid: %v", err)<br />
}<br />
receivers := map[btcutil.Address]btcutil.Amount{<br />
receiver1: 42, // 42 satoshi<br />
receiver2: 100, // 100 satoshi<br />
}<br />
<br />
// create and send the sendMany tx<br />
txSha, err := client.SendMany("some-account-label-from-which-to-send", receivers)<br />
if err != nil {<br />
log.Fatalf("error sendMany: %v", err)<br />
}<br />
log.Printf("sendMany completed! tx sha is: %s", txSha.String())<br />
}<br />
</source><br />
<br />
== .NET (C#) ==<br />
The communication with rpc service can be achieved using the standard http request/response objects.<br />
A library for serialising and deserializing Json will make your life a lot easier:<br />
<br />
Json.Net ( http://james.newtonking.com/json ) is a high performance JSON package for .Net. It is also available via NuGet from the package manager console ( Install-Package Newtonsoft.Json ).<br />
<br />
The following example uses Json.Net:<br />
<br />
<source lang="csharp"><br />
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("http://localhost.:8332");<br />
webRequest.Credentials = new NetworkCredential("user", "pwd");<br />
/// important, otherwise the service can't desirialse your request properly<br />
webRequest.ContentType = "application/json-rpc";<br />
webRequest.Method = "POST";<br />
<br />
JObject joe = new JObject();<br />
joe.Add(new JProperty("jsonrpc", "1.0"));<br />
joe.Add(new JProperty("id", "1"));<br />
joe.Add(new JProperty("method", Method));<br />
// params is a collection values which the method requires..<br />
if (Params.Keys.Count == 0)<br />
{<br />
joe.Add(new JProperty("params", new JArray()));<br />
}<br />
else<br />
{<br />
JArray props = new JArray();<br />
// add the props in the reverse order!<br />
for (int i = Params.Keys.Count - 1; i >= 0; i--)<br />
{<br />
.... // add the params<br />
}<br />
joe.Add(new JProperty("params", props));<br />
}<br />
<br />
// serialize json for the request<br />
string s = JsonConvert.SerializeObject(joe);<br />
byte[] byteArray = Encoding.UTF8.GetBytes(s);<br />
webRequest.ContentLength = byteArray.Length;<br />
Stream dataStream = webRequest.GetRequestStream();<br />
dataStream.Write(byteArray, 0, byteArray.Length);<br />
dataStream.Close();<br />
<br />
<br />
WebResponse webResponse = webRequest.GetResponse();<br />
<br />
... // deserialze the response<br />
</source><br />
<br />
There is also a wrapper for Json.NET called Bitnet (https://sourceforge.net/projects/bitnet)<br />
implementing Bitcoin API in more convenient way:<br />
<br />
<source lang="csharp"><br />
BitnetClient bc = new BitnetClient("http://127.0.0.1:8332");<br />
bc.Credentials = new NetworkCredential("user", "pass");<br />
<br />
var p = bc.GetDifficulty();<br />
Console.WriteLine("Difficulty:" + p.ToString());<br />
<br />
var inf = bc.GetInfo();<br />
Console.WriteLine("Balance:" + inf["balance"]);<br />
</source><br />
<br />
== Node.js ==<br />
<br />
* [https://github.com/freewil/node-bitcoin node-bitcoin] (npm: bitcoin) <br />
<br />
Example using node-bitcoin:<br />
<br />
<source lang="javascript"><br />
var bitcoin = require('bitcoin');<br />
var client = new bitcoin.Client({<br />
host: 'localhost',<br />
port: 8332,<br />
user: 'user',<br />
pass: 'pass'<br />
});<br />
<br />
client.getDifficulty(function(err, difficulty) {<br />
if (err) {<br />
return console.error(err);<br />
}<br />
<br />
console.log('Difficulty: ' + difficulty);<br />
});<br />
</source><br />
<br />
Example using Kapitalize:<br />
<br />
<source lang='javascript'><br />
var client = require('kapitalize')()<br />
<br />
client.auth('user', 'password')<br />
<br />
client<br />
.getInfo()<br />
.getDifficulty(function(err, difficulty) {<br />
console.log('Dificulty: ', difficulty)<br />
})<br />
</source><br />
<br />
== Command line (cURL) ==<br />
<br />
You can also send commands and see results using [http://curl.haxx.se/ cURL] or some other command-line HTTP-fetching utility; for example:<br />
<br />
<source lang="bash"><br />
curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' <br />
-H 'content-type: text/plain;' http://127.0.0.1:8332/<br />
</source><br />
<br />
You will be prompted for your rpcpassword, and then will see something like:<br />
<br />
<source lang="javascript"><br />
{"result":{"balance":0.000000000000000,"blocks":59952,"connections":48,"proxy":"","generate":false,<br />
"genproclimit":-1,"difficulty":16.61907875185736,"error":null,"id":"curltest"}<br />
</source><br />
<br />
== Clojure ==<br />
<br />
[https://github.com/aviad/clj-btc clj-btc] is a Clojure wrapper for the bitcoin API.<br />
<br />
<source lang="clojure"><br />
user=> (require '[clj-btc.core :as btc])<br />
nil<br />
user=> (btc/getinfo)<br />
{"timeoffset" 0, "protocolversion" 70001, "blocks" 111908, "errors" "",<br />
"testnet" true, "proxy" "", "connections" 4, "version" 80500,<br />
"keypoololdest" 1380388750, "paytxfee" 0E-8M,<br />
"difficulty" 4642.44443532M, "keypoolsize" 101, "balance" 0E-8M,<br />
"walletversion" 60000}<br />
</source><br />
<br />
== See Also==<br />
<br />
* [[Original_Bitcoin_client/API_Calls_list|API calls list]]<br />
* [[Running Bitcoin]]<br />
* [[Lazy API]]<br />
* [[PHP developer intro]]<br />
* [[Raw_Transactions|Raw Transactions API]]<br />
* [http://blockchain.info/api/json_rpc_api Web Based JSON RPC interface.]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
[[zh-cn:API_reference_(JSON-RPC)]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=45124Template:MainPage Intro2014-03-19T21:45:26Z<p>Gavinandresen: </p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first successful implementations of a ''distributed crypto-currency'', described in part in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Getting started'''<br />
See [https://bitcoin.org/en/getting-started the bitcoin.org website] for how to get started using Bitcoin.</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=45123Template:MainPage Intro2014-03-19T21:44:49Z<p>Gavinandresen: Link to bitcoin.org Getting Started page instead of linking to Bitcoin Core binaries (most users should not use Bitcoin Core).</p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first successful implementations of a ''distributed crypto-currency'', described in part in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Getting started'''<br />
See [https://bitcoin.org/en/getting-started for how to get started using Bitcoin].</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=45122Template:MainPage Intro2014-03-19T21:42:38Z<p>Gavinandresen: </p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first successful implementations of a ''distributed crypto-currency'', described in part in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Bitcoin-Qt:'''<br />
{|style="background-color: inherit;"<br />
|<br />
* [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-win32-setup.exe '''Windows (exe)'''] 11 MB [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-win.zip '''(zip)'''] 61 MB<br />
* [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-linux.tar.gz '''GNU/Linux'''] 35 MB<br />
* [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-macosx.dmg '''Mac OS X'''] 13 MB<br />
|}<br />
<br />
Bitcoin-Qt initial startup can take a very long time to complete. For quicker clients, see [https://bitcoin.org/en/choose-your-wallet this list of Bitcoin wallets].</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=45121Template:MainPage Intro2014-03-19T21:42:10Z<p>Gavinandresen: 0.9.0 release</p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first successful implementations of a ''distributed crypto-currency'', described in part in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Bitcoin-Qt:'''<br />
{|style="background-color: inherit;"<br />
|<br />
* [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-win32-setup.exe/download '''Windows (exe)'''] 11 MB [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-win.zip/download '''(zip)'''] 61 MB<br />
* [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-linux.tar.gz/download '''GNU/Linux'''] 35 MB<br />
* [https://bitcoin.org/bin/0.9.0/bitcoin-0.9.0-macosx.dmg/download '''Mac OS X'''] 13 MB<br />
|}<br />
<br />
Bitcoin-Qt initial startup can take a very long time to complete. For quicker clients, see [https://bitcoin.org/en/choose-your-wallet this list of Bitcoin wallets].</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=42989Template:MainPage Intro2013-12-10T02:38:11Z<p>Gavinandresen: Update links for 0.8.6 release</p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first successful implementations of a ''distributed crypto-currency'', described in part in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Bitcoin-Qt:'''<br />
{|style="background-color: inherit;"<br />
|<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.6/bitcoin-0.8.6-win32-setup.exe/download '''Windows (exe)'''] 10 MB [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.6/bitcoin-0.8.6-win32.zip/download '''(zip)'''] 14 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.6/bitcoin-0.8.6-linux.tar.gz/download '''GNU/Linux'''] 13 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.6/bitcoin-0.8.6-macosx.dmg/download '''Mac OS X'''] 12 MB<br />
|}<br />
<br />
[http://bitcoin.org/clients.html More Bitcoin Client Software]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0072&diff=42850BIP 00722013-12-04T02:59:57Z<p>Gavinandresen: Changed request param to just 'r'</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 72<br />
Title: bitcoin: uri extensions for Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to<br />
support the payment protocol (BIP 70).<br />
<br />
==Motivation==<br />
<br />
Allow users to click on a link in a web page or email to initiate the<br />
payment protocol, while being backwards-compatible with existing<br />
bitcoin wallets.<br />
<br />
==Specification==<br />
<br />
The bitcoin: URI scheme is extended with an additional, optional<br />
"r" parameter, whose value is a URL from which a PaymentRequest<br />
message should be fetched (unsafe and reserved octets in the URL value<br />
must be encoded as described in RFC 1738).<br />
<br />
If the "r" parameter is provided and backwards compatibility<br />
is not required, then the bitcoin address portion of the URI may be<br />
omitted (the URI will be of the form: bitcoin:?r=... ).<br />
<br />
When Bitcoin wallet software that supports this BIP receives a<br />
bitcoin: URI with a r parameter, it should ignore the bitcoin<br />
address/amount/label/message in the URI and instead fetch a<br />
PaymentRequest message and then follow the payment protocol, as<br />
described in BIP 70.<br />
<br />
Bitcoin wallets must support fetching PaymentRequests via http and<br />
https protocols; they may support other protocols. Wallets must<br />
include an Accept HTTP header in HTTP requests:<br />
<pre>Accept: application/bitcoin-paymentrequest</pre><br />
<br />
If a PaymentRequest cannot be obtained (perhaps the server is<br />
unavailable), then the customer should be informed that the merchant's<br />
payment processing system is unavailable.<br />
<br />
==Compatibility==<br />
<br />
Wallet software that does not support this BIP will simply ignore the<br />
r parameter and will initiate a payment to bitcoin address.<br />
<br />
==Examples==<br />
A backwards-compatible request:<br />
<pre><br />
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&r=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
Non-backwards-compatible equivalent:<br />
<pre><br />
bitcoin:?r=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Running_Bitcoin&diff=42520Running Bitcoin2013-11-22T00:47:59Z<p>Gavinandresen: Fix wording -mintxfee</p>
<hr />
<div>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).<br />
<br />
__TOC__<br />
<br />
==Linux Quickstart==<br />
<br />
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:<br />
<br />
./bitcoind<br />
<br />
To run with the standard GUI interface:<br />
<br />
./bitcoin-qt<br />
<br />
==Command-line arguments==<br />
<br />
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:<br />
<br />
Options:<br />
-? This help message<br />
-conf=<file> Specify configuration file (default: bitcoin.conf)<br />
-pid=<file> Specify pid file (default: bitcoind.pid)<br />
-gen Generate coins (default: 0)<br />
-datadir=<dir> Specify data directory<br />
-dbcache=<n> Set database cache size in megabytes (default: 25)<br />
-timeout=<n> Specify connection timeout in milliseconds (default: 5000)<br />
-proxy=<ip:port> Connect through socks proxy<br />
-socks=<n> Select the version of socks proxy to use (4-5, default: 5)<br />
-tor=<ip:port> Use proxy to reach tor hidden services (default: same as -proxy)<br />
-dns Allow DNS lookups for -addnode, -seednode and -connect<br />
-port=<port> Listen for connections on <port> (default: 8333 or testnet: 18333)<br />
-maxconnections=<n> Maintain at most <n> connections to peers (default: 125)<br />
-addnode=<ip> Add a node to connect to and attempt to keep the connection open<br />
-connect=<ip> Connect only to the specified node(s)<br />
-seednode=<ip> Connect to a node to retrieve peer addresses, and disconnect<br />
-externalip=<ip> Specify your own public address<br />
-onlynet=<net> Only connect to nodes in network <net> (IPv4, IPv6 or Tor)<br />
-discover Discover own IP address (default: 1 when listening and no -externalip)<br />
-checkpoints Only accept block chain matching built-in checkpoints (default: 1)<br />
-listen Accept connections from outside (default: 1 if no -proxy or -connect)<br />
-bind=<addr> Bind to given address and always listen on it. Use [host]:port notation for IPv6<br />
-dnsseed Find peers using DNS lookup (default: 1 unless -connect)<br />
-banscore=<n> Threshold for disconnecting misbehaving peers (default: 100)<br />
-bantime=<n> Number of seconds to keep misbehaving peers from reconnecting (default: 86400)<br />
-maxreceivebuffer=<n> Maximum per-connection receive buffer, <n>*1000 bytes (default: 5000)<br />
-maxsendbuffer=<n> Maximum per-connection send buffer, <n>*1000 bytes (default: 1000)<br />
-upnp Use UPnP to map the listening port (default: 1 when listening)<br />
-paytxfee=<amt> Fee per KB to add to transactions you send<br />
-server Accept command line and JSON-RPC commands<br />
-testnet Use the test network<br />
-debug Output extra debugging information. Implies all other -debug* options<br />
-debugnet Output extra network debugging information<br />
-logtimestamps Prepend debug output with timestamp<br />
-shrinkdebugfile Shrink debug.log file on client startup (default: 1 when no -debug)<br />
-printtoconsole Send trace/debug info to console instead of debug.log file<br />
-printtodebugger Send trace/debug info to debugger<br />
-rpcuser=<user> Username for JSON-RPC connections<br />
-rpcpassword=<pw> Password for JSON-RPC connections<br />
-rpcport=<port> Listen for JSON-RPC connections on <port> (default: 8332 or testnet: 18332)<br />
-rpcallowip=<ip> Allow JSON-RPC connections from specified IP address<br />
-rpcthreads=<n> Set the number of threads to service RPC calls (default: 4)<br />
-blocknotify=<cmd> Execute command when the best block changes (%s in cmd is replaced by block hash)<br />
-walletnotify=<cmd> Execute command when a wallet transaction changes (%s in cmd is replaced by TxID)<br />
-alertnotify=<cmd> Execute command when a relevant alert is received (%s in cmd is replaced by message)<br />
-upgradewallet Upgrade wallet to latest format<br />
-keypool=<n> Set key pool size to <n> (default: 100)<br />
-rescan Rescan the block chain for missing wallet transactions<br />
-salvagewallet Attempt to recover private keys from a corrupt wallet.dat<br />
-checkblocks=<n> How many blocks to check at startup (default: 288, 0 = all)<br />
-checklevel=<n> How thorough the block verification is (0-4, default: 3)<br />
-txindex Maintain a full transaction index (default: 0)<br />
-loadblock=<file> Imports blocks from external blk000??.dat file<br />
-reindex Rebuild block chain index from current blk000??.dat files<br />
-par=<n> Set the number of script verification threads (up to 16, 0 = auto, <0 = leave that many cores free, default: 0)<br />
<br />
Block creation options:<br />
-blockminsize=<n> Set minimum block size in bytes (default: 0)<br />
-blockmaxsize=<n> Set maximum block size in bytes (default: 250000)<br />
-blockprioritysize=<n> Set maximum size of high-priority/low-fee transactions in bytes (default: 27000)<br />
-mintxfee=<m.n> Minimum fee-per-kilobyte to qualify as fee-paying (default: 0.0001)<br />
<br />
SSL options: (see the Bitcoin Wiki for SSL setup instructions)<br />
-rpcssl Use OpenSSL (https) for JSON-RPC connections<br />
-rpcsslcertificatechainfile=<file.cert> Server certificate file (default: server.cert)<br />
-rpcsslprivatekeyfile=<file.pem> Server private key (default: server.pem)<br />
-rpcsslciphers=<ciphers> Acceptable ciphers (default: TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH)<br />
<br />
UI options:<br />
-lang=<lang> Set language, for example "de_DE" (default: system locale)<br />
-min Start minimized<br />
-splash Show splash screen on startup (default: 1)<br />
<br />
Many of the boolean options can also be set to off by specifying them with a "no" prefix: e.g. -nodnseed.<br />
<br />
==Bitcoin.conf Configuration File==<br />
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.<br />
<br />
The configuration file is a list of setting=value pairs, one per line, with optional comments starting with the '#' character.<br />
<br />
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.<br />
{|<br />
! Operating System<br />
! Default bitcoin datadir<br />
! Typical path to configuration file<br />
|-<br />
| Windows<br />
| %APPDATA%\Bitcoin\<br />
| (XP) C:\Documents and Settings\username\Application Data\Bitcoin\bitcoin.conf<br />
(Vista, 7) C:\Users\username\AppData\Roaming\Bitcoin\bitcoin.conf<br />
|-<br />
| Linux<br />
| $HOME/.bitcoin/<br />
| /home/username/.bitcoin/bitcoin.conf<br />
|-<br />
| Mac OSX<br />
| $HOME/Library/Application Support/Bitcoin/<br />
| /Users/username/Library/Application Support/Bitcoin/bitcoin.conf<br />
|}<br />
<br />
Note: if running Bitcoin in testnet mode, the sub-folder "testnet" will be appended to the data directory automatically.<br />
<br />
==Sample Bitcoin.conf==<br />
Here is a sample bitcoin.conf file.<br />
<br />
# bitcoin.conf configuration file. Lines beginning with # are comments.<br />
<br />
<br />
# Network-related settings:<br />
<br />
# Run on the test network instead of the real bitcoin network.<br />
#testnet=0<br />
<br />
# Connect via a socks4 proxy<br />
#proxy=127.0.0.1:9050<br />
<br />
##############################################################<br />
## Quick Primer on addnode vs connect ##<br />
## Let's say for instance you use addnode=4.2.2.4 ##<br />
## addnode will connect you to and tell you about the ##<br />
## nodes connected to 4.2.2.4. In addition it will tell ##<br />
## the other nodes connected to it that you exist so ##<br />
## they can connect to you. ##<br />
## connect will not do the above when you 'connect' to it. ##<br />
## It will *only* connect you to 4.2.2.4 and no one else.##<br />
## ##<br />
## So if you're behind a firewall, or have other problems ##<br />
## finding nodes, add some using 'addnode'. ##<br />
## ##<br />
## If you want to stay private, use 'connect' to only ##<br />
## connect to "trusted" nodes. ##<br />
## ##<br />
## If you run multiple nodes on a LAN, there's no need for ##<br />
## all of them to open lots of connections. Instead ##<br />
## 'connect' them all to one node that is port forwarded ##<br />
## and has lots of connections. ##<br />
## Thanks goes to [Noodle] on Freenode. ##<br />
##############################################################<br />
<br />
# Use as many addnode= settings as you like to connect to specific peers<br />
#addnode=69.164.218.197<br />
#addnode=10.0.0.2:8333<br />
<br />
# ... or use as many connect= settings as you like to connect ONLY<br />
# to specific peers:<br />
#connect=69.164.218.197<br />
#connect=10.0.0.1:8333<br />
<br />
<br />
# Maximum number of inbound+outbound connections.<br />
#maxconnections=<br />
<br />
<br />
# JSON-RPC options (for controlling a running Bitcoin/bitcoind process)<br />
<br />
# server=1 tells Bitcoin-QT to accept JSON-RPC commands.<br />
#server=0<br />
<br />
# You must set rpcuser and rpcpassword to secure the JSON-RPC api<br />
#rpcuser=Ulysseys<br />
#rpcpassword=YourSuperGreatPasswordNumber_DO_NOT_USE_THIS_OR_YOU_WILL_GET_ROBBED_385593<br />
<br />
# How many seconds bitcoin will wait for a complete RPC HTTP request.<br />
# after the HTTP connection is established. <br />
#rpctimeout=30<br />
<br />
# By default, only RPC connections from localhost are allowed. Specify<br />
# as many rpcallowip= settings as you like to allow connections from<br />
# other hosts (and you may use * as a wildcard character).<br />
# NOTE: opening up the RPC port to hosts outside your local<br />
# trusted network is NOT RECOMMENDED, because the rpcpassword<br />
# is transmitted over the network unencrypted.<br />
#rpcallowip=10.1.1.34<br />
#rpcallowip=192.168.1.*<br />
<br />
# Listen for RPC connections on this TCP port:<br />
#rpcport=8332<br />
<br />
# You can use Bitcoin or bitcoind to send commands to Bitcoin/bitcoind<br />
# running on another host using this option:<br />
#rpcconnect=127.0.0.1<br />
<br />
# Use Secure Sockets Layer (also known as TLS or HTTPS) to communicate<br />
# with Bitcoin -server or bitcoind<br />
#rpcssl=1<br />
<br />
# OpenSSL settings used when rpcssl=1<br />
#rpcsslciphers=TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH<br />
#rpcsslcertificatechainfile=server.cert<br />
#rpcsslprivatekeyfile=server.pem<br />
<br />
<br />
# Miscellaneous options<br />
<br />
# Set gen=1 to attempt to generate bitcoins<br />
#gen=0<br />
<br />
# Pre-generate this many public/private key pairs, so wallet backups will be valid for<br />
# both prior transactions and several dozen future transactions.<br />
#keypool=100<br />
<br />
# Pay an optional transaction fee every time you send bitcoins. Transactions with fees<br />
# are more likely than free transactions to be included in generated blocks, so may<br />
# be validated sooner.<br />
#paytxfee=0.00<br />
<br />
# Allow direct connections for the 'pay via IP address' feature.<br />
#allowreceivebyip=1<br />
<br />
# User interface options<br />
<br />
# Start Bitcoin minimized<br />
#min=1<br />
<br />
# Minimize to the system tray<br />
#minimizetotray=1<br />
<br />
==Platforms==<br />
===Windows===<br />
<br />
====Start automatically====<br />
To configure the Bitcoin client to start automatically:<br />
<br />
You might use the configuration-file, or the GUI-Settings:<br />
<br />
Settings -> Options<br />
<br />
then mark the checkbox titled:<br />
[X] Start Bitcoin on system startup<br />
<br />
[[{{ns:file}}:Client_Settings_Options_windows.png]]<br />
<br />
====Batch automation====<br />
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.<br />
<br />
===Mac===<br />
[[{{ns:file}}:MacBitcoinStartOnLogin.png]]<br />
<br />
===Linux===<br />
[[{{ns:file}}:Client_Settings_Options.png]]<br />
<br />
==See Also==<br />
<br />
* [[Data directory]]<br />
<br />
[[es:Ejecución de Bitcoin]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Running_Bitcoin&diff=42519Running Bitcoin2013-11-22T00:46:47Z<p>Gavinandresen: Added -mintxfee</p>
<hr />
<div>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).<br />
<br />
__TOC__<br />
<br />
==Linux Quickstart==<br />
<br />
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:<br />
<br />
./bitcoind<br />
<br />
To run with the standard GUI interface:<br />
<br />
./bitcoin-qt<br />
<br />
==Command-line arguments==<br />
<br />
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:<br />
<br />
Options:<br />
-? This help message<br />
-conf=<file> Specify configuration file (default: bitcoin.conf)<br />
-pid=<file> Specify pid file (default: bitcoind.pid)<br />
-gen Generate coins (default: 0)<br />
-datadir=<dir> Specify data directory<br />
-dbcache=<n> Set database cache size in megabytes (default: 25)<br />
-timeout=<n> Specify connection timeout in milliseconds (default: 5000)<br />
-proxy=<ip:port> Connect through socks proxy<br />
-socks=<n> Select the version of socks proxy to use (4-5, default: 5)<br />
-tor=<ip:port> Use proxy to reach tor hidden services (default: same as -proxy)<br />
-dns Allow DNS lookups for -addnode, -seednode and -connect<br />
-port=<port> Listen for connections on <port> (default: 8333 or testnet: 18333)<br />
-maxconnections=<n> Maintain at most <n> connections to peers (default: 125)<br />
-addnode=<ip> Add a node to connect to and attempt to keep the connection open<br />
-connect=<ip> Connect only to the specified node(s)<br />
-seednode=<ip> Connect to a node to retrieve peer addresses, and disconnect<br />
-externalip=<ip> Specify your own public address<br />
-onlynet=<net> Only connect to nodes in network <net> (IPv4, IPv6 or Tor)<br />
-discover Discover own IP address (default: 1 when listening and no -externalip)<br />
-checkpoints Only accept block chain matching built-in checkpoints (default: 1)<br />
-listen Accept connections from outside (default: 1 if no -proxy or -connect)<br />
-bind=<addr> Bind to given address and always listen on it. Use [host]:port notation for IPv6<br />
-dnsseed Find peers using DNS lookup (default: 1 unless -connect)<br />
-banscore=<n> Threshold for disconnecting misbehaving peers (default: 100)<br />
-bantime=<n> Number of seconds to keep misbehaving peers from reconnecting (default: 86400)<br />
-maxreceivebuffer=<n> Maximum per-connection receive buffer, <n>*1000 bytes (default: 5000)<br />
-maxsendbuffer=<n> Maximum per-connection send buffer, <n>*1000 bytes (default: 1000)<br />
-upnp Use UPnP to map the listening port (default: 1 when listening)<br />
-paytxfee=<amt> Fee per KB to add to transactions you send<br />
-server Accept command line and JSON-RPC commands<br />
-testnet Use the test network<br />
-debug Output extra debugging information. Implies all other -debug* options<br />
-debugnet Output extra network debugging information<br />
-logtimestamps Prepend debug output with timestamp<br />
-shrinkdebugfile Shrink debug.log file on client startup (default: 1 when no -debug)<br />
-printtoconsole Send trace/debug info to console instead of debug.log file<br />
-printtodebugger Send trace/debug info to debugger<br />
-rpcuser=<user> Username for JSON-RPC connections<br />
-rpcpassword=<pw> Password for JSON-RPC connections<br />
-rpcport=<port> Listen for JSON-RPC connections on <port> (default: 8332 or testnet: 18332)<br />
-rpcallowip=<ip> Allow JSON-RPC connections from specified IP address<br />
-rpcthreads=<n> Set the number of threads to service RPC calls (default: 4)<br />
-blocknotify=<cmd> Execute command when the best block changes (%s in cmd is replaced by block hash)<br />
-walletnotify=<cmd> Execute command when a wallet transaction changes (%s in cmd is replaced by TxID)<br />
-alertnotify=<cmd> Execute command when a relevant alert is received (%s in cmd is replaced by message)<br />
-upgradewallet Upgrade wallet to latest format<br />
-keypool=<n> Set key pool size to <n> (default: 100)<br />
-rescan Rescan the block chain for missing wallet transactions<br />
-salvagewallet Attempt to recover private keys from a corrupt wallet.dat<br />
-checkblocks=<n> How many blocks to check at startup (default: 288, 0 = all)<br />
-checklevel=<n> How thorough the block verification is (0-4, default: 3)<br />
-txindex Maintain a full transaction index (default: 0)<br />
-loadblock=<file> Imports blocks from external blk000??.dat file<br />
-reindex Rebuild block chain index from current blk000??.dat files<br />
-par=<n> Set the number of script verification threads (up to 16, 0 = auto, <0 = leave that many cores free, default: 0)<br />
<br />
Block creation options:<br />
-blockminsize=<n> Set minimum block size in bytes (default: 0)<br />
-blockmaxsize=<n> Set maximum block size in bytes (default: 250000)<br />
-blockprioritysize=<n> Set maximum size of high-priority/low-fee transactions in bytes (default: 27000)<br />
-mintxfee=<m.n> Minimum acceptable transaction fee-per-kilobyte to be included in fee-paying part of block (default: 0.0001)<br />
<br />
SSL options: (see the Bitcoin Wiki for SSL setup instructions)<br />
-rpcssl Use OpenSSL (https) for JSON-RPC connections<br />
-rpcsslcertificatechainfile=<file.cert> Server certificate file (default: server.cert)<br />
-rpcsslprivatekeyfile=<file.pem> Server private key (default: server.pem)<br />
-rpcsslciphers=<ciphers> Acceptable ciphers (default: TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH)<br />
<br />
UI options:<br />
-lang=<lang> Set language, for example "de_DE" (default: system locale)<br />
-min Start minimized<br />
-splash Show splash screen on startup (default: 1)<br />
<br />
Many of the boolean options can also be set to off by specifying them with a "no" prefix: e.g. -nodnseed.<br />
<br />
==Bitcoin.conf Configuration File==<br />
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.<br />
<br />
The configuration file is a list of setting=value pairs, one per line, with optional comments starting with the '#' character.<br />
<br />
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.<br />
{|<br />
! Operating System<br />
! Default bitcoin datadir<br />
! Typical path to configuration file<br />
|-<br />
| Windows<br />
| %APPDATA%\Bitcoin\<br />
| (XP) C:\Documents and Settings\username\Application Data\Bitcoin\bitcoin.conf<br />
(Vista, 7) C:\Users\username\AppData\Roaming\Bitcoin\bitcoin.conf<br />
|-<br />
| Linux<br />
| $HOME/.bitcoin/<br />
| /home/username/.bitcoin/bitcoin.conf<br />
|-<br />
| Mac OSX<br />
| $HOME/Library/Application Support/Bitcoin/<br />
| /Users/username/Library/Application Support/Bitcoin/bitcoin.conf<br />
|}<br />
<br />
Note: if running Bitcoin in testnet mode, the sub-folder "testnet" will be appended to the data directory automatically.<br />
<br />
==Sample Bitcoin.conf==<br />
Here is a sample bitcoin.conf file.<br />
<br />
# bitcoin.conf configuration file. Lines beginning with # are comments.<br />
<br />
<br />
# Network-related settings:<br />
<br />
# Run on the test network instead of the real bitcoin network.<br />
#testnet=0<br />
<br />
# Connect via a socks4 proxy<br />
#proxy=127.0.0.1:9050<br />
<br />
##############################################################<br />
## Quick Primer on addnode vs connect ##<br />
## Let's say for instance you use addnode=4.2.2.4 ##<br />
## addnode will connect you to and tell you about the ##<br />
## nodes connected to 4.2.2.4. In addition it will tell ##<br />
## the other nodes connected to it that you exist so ##<br />
## they can connect to you. ##<br />
## connect will not do the above when you 'connect' to it. ##<br />
## It will *only* connect you to 4.2.2.4 and no one else.##<br />
## ##<br />
## So if you're behind a firewall, or have other problems ##<br />
## finding nodes, add some using 'addnode'. ##<br />
## ##<br />
## If you want to stay private, use 'connect' to only ##<br />
## connect to "trusted" nodes. ##<br />
## ##<br />
## If you run multiple nodes on a LAN, there's no need for ##<br />
## all of them to open lots of connections. Instead ##<br />
## 'connect' them all to one node that is port forwarded ##<br />
## and has lots of connections. ##<br />
## Thanks goes to [Noodle] on Freenode. ##<br />
##############################################################<br />
<br />
# Use as many addnode= settings as you like to connect to specific peers<br />
#addnode=69.164.218.197<br />
#addnode=10.0.0.2:8333<br />
<br />
# ... or use as many connect= settings as you like to connect ONLY<br />
# to specific peers:<br />
#connect=69.164.218.197<br />
#connect=10.0.0.1:8333<br />
<br />
<br />
# Maximum number of inbound+outbound connections.<br />
#maxconnections=<br />
<br />
<br />
# JSON-RPC options (for controlling a running Bitcoin/bitcoind process)<br />
<br />
# server=1 tells Bitcoin-QT to accept JSON-RPC commands.<br />
#server=0<br />
<br />
# You must set rpcuser and rpcpassword to secure the JSON-RPC api<br />
#rpcuser=Ulysseys<br />
#rpcpassword=YourSuperGreatPasswordNumber_DO_NOT_USE_THIS_OR_YOU_WILL_GET_ROBBED_385593<br />
<br />
# How many seconds bitcoin will wait for a complete RPC HTTP request.<br />
# after the HTTP connection is established. <br />
#rpctimeout=30<br />
<br />
# By default, only RPC connections from localhost are allowed. Specify<br />
# as many rpcallowip= settings as you like to allow connections from<br />
# other hosts (and you may use * as a wildcard character).<br />
# NOTE: opening up the RPC port to hosts outside your local<br />
# trusted network is NOT RECOMMENDED, because the rpcpassword<br />
# is transmitted over the network unencrypted.<br />
#rpcallowip=10.1.1.34<br />
#rpcallowip=192.168.1.*<br />
<br />
# Listen for RPC connections on this TCP port:<br />
#rpcport=8332<br />
<br />
# You can use Bitcoin or bitcoind to send commands to Bitcoin/bitcoind<br />
# running on another host using this option:<br />
#rpcconnect=127.0.0.1<br />
<br />
# Use Secure Sockets Layer (also known as TLS or HTTPS) to communicate<br />
# with Bitcoin -server or bitcoind<br />
#rpcssl=1<br />
<br />
# OpenSSL settings used when rpcssl=1<br />
#rpcsslciphers=TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH<br />
#rpcsslcertificatechainfile=server.cert<br />
#rpcsslprivatekeyfile=server.pem<br />
<br />
<br />
# Miscellaneous options<br />
<br />
# Set gen=1 to attempt to generate bitcoins<br />
#gen=0<br />
<br />
# Pre-generate this many public/private key pairs, so wallet backups will be valid for<br />
# both prior transactions and several dozen future transactions.<br />
#keypool=100<br />
<br />
# Pay an optional transaction fee every time you send bitcoins. Transactions with fees<br />
# are more likely than free transactions to be included in generated blocks, so may<br />
# be validated sooner.<br />
#paytxfee=0.00<br />
<br />
# Allow direct connections for the 'pay via IP address' feature.<br />
#allowreceivebyip=1<br />
<br />
# User interface options<br />
<br />
# Start Bitcoin minimized<br />
#min=1<br />
<br />
# Minimize to the system tray<br />
#minimizetotray=1<br />
<br />
==Platforms==<br />
===Windows===<br />
<br />
====Start automatically====<br />
To configure the Bitcoin client to start automatically:<br />
<br />
You might use the configuration-file, or the GUI-Settings:<br />
<br />
Settings -> Options<br />
<br />
then mark the checkbox titled:<br />
[X] Start Bitcoin on system startup<br />
<br />
[[{{ns:file}}:Client_Settings_Options_windows.png]]<br />
<br />
====Batch automation====<br />
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.<br />
<br />
===Mac===<br />
[[{{ns:file}}:MacBitcoinStartOnLogin.png]]<br />
<br />
===Linux===<br />
[[{{ns:file}}:Client_Settings_Options.png]]<br />
<br />
==See Also==<br />
<br />
* [[Data directory]]<br />
<br />
[[es:Ejecución de Bitcoin]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=41012Template:MainPage Intro2013-09-13T01:23:47Z<p>Gavinandresen: 0.8.5 release</p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first implementations of a concept called ''crypto-currency'' which was first described in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Bitcoin-Qt:'''<br />
{|style="background-color: inherit;"<br />
|<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.5/bitcoin-0.8.5-win32-setup.exe/download '''Windows (exe)'''] 10 MB [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.5/bitcoin-0.8.5-win32.zip/download '''(zip)'''] 14 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.5/bitcoin-0.8.5-linux.tar.gz/download '''GNU/Linux'''] 13 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.5/bitcoin-0.8.5-macosx.dmg/download '''Mac OS X'''] 12 MB<br />
|}<br />
<br />
[http://bitcoin.org/clients.html More Bitcoin Client Software]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Help:Accounts_explained&diff=40989Help:Accounts explained2013-09-12T01:09:02Z<p>Gavinandresen: /* Account Weaknesses */</p>
<hr />
<div>== Introduction ==<br />
<br />
Think about what happens when you give a bank teller some cash and ask that it be deposited into your account. You tell them your account number, and they credit your account with that amount of money.<br />
<br />
The money itself is mixed up with all of the other money in the bank, and is given out to other customers with other account numbers.<br />
<br />
With the Bitcoin "accounts" feature, you are the bank. The balance you see is the total balance for all accounts, and you can create an arbitrary number of accounts.<br />
<br />
When you receive bitcoins, they are always assigned to one of your accounts, and you can change which account is credited based on which bitcoin address receives the coins, just like you tell a bank teller which account to credit when you deposit cash in your bank. However, sending bitcoins is like withdrawing cash from the bank; the coins that are sent out and debited from an account are almost always not the same coins that were deposited into that account.<br />
<br />
== Accounts ==<br />
<br />
Bitcoin version 0.3.18 and later implements several RPC methods to maintain separate account balances in a single Bitcoin wallet. The accounts feature makes it easy to keep track of how much money you have received from different sources or to keep track of how much money you have spent on different things.<br />
<br />
== Account Weaknesses ==<br />
<br />
Since the accounts feature was introduced, several services have used it to keep track of customer's bitcoin balances and have had the following problems:<br />
<br />
* Wallet backups are an issue; if you rely on a good backup of wallet.dat then a backup must be done every time an address is associated with an account and every time the 'move' command is used.<br />
* The accounts code does not scale up to thousands of accounts with tens of thousands of transactions, because by-account (and by-account-by-time) indices are not implemented. So many operations (like computing an account balance) require accessing every wallet transaction.<br />
* Most applications already have a customer database, implemented with MySQL or some other relational database technology. It is awkward at best to keep the bitcoin-maintained Berkely DB wallet database and the application database backed up and synchronized at all times.<br />
<br />
== Account Names ==<br />
<br />
Accounts are named with arbitrary strings; you may use any [http://www.json.org/ JSON] string other than "*" (JSON strings are sent and returned as UTF-8 encoded Unicode).<br />
<br />
Bitcoin creates two accounts automatically: it implicitly creates a default account with the empty string as its name, and it explicitly creates an account named '''Your Address''' when a new wallet is created.<br />
<br />
== The Default Account ==<br />
<br />
The default account is named with the empty string ("" in JSON). Generated coins are always credited to the default account, and the ''sendtoaddress'' method always debits the default account.<br />
<br />
== Accounts and Receiving Addresses ==<br />
<br />
Each account is associated with zero or more receiving addresses, and every receiving address is associated with exactly one account. Coins sent to a receiving address in the wallet are credited to the associated account.<br />
<br />
Accounts are associated with receiving addresses by using the ''getaccountaddress'', ''getnewaddress'' or ''setaccount'' methods.<br />
<br />
''getaccountaddress'' will return the same address until coins are received on that address; once coins have been received, it will generate and return a new address.<br />
<br />
''getnewaddress'' always generates and returns a new address.<br />
<br />
''setaccount'' changes the account associated with an existing address. Coins previously received on that address (if any) will be debited from the previous account's balance and credited to the address' new account. Note that doing so may make the previous account's balance negative.<br />
<br />
Use the ''getaddressesbyaccount'' method to list all addresses associated with an account.<br />
<br />
== Sending ==<br />
<br />
The ''sendfrom'' method sends coins and debits the specified account. It does **not** change Bitcoin's algorithm for selecting which coins in the wallet are sent-- you should think of the coins in the wallet as being mixed together when they are received. There is no way to ask Bitcoin to "create a payment transaction using the coins received from these previously received transactions."<br />
<br />
The ''sendtoaddress'' method works like ''sendfrom'', but always debits the default account.<br />
<br />
The send will fail if the account has insufficient funds, with two exceptions:<br />
<br />
- 'sendtoaddress' always succeeds if there are sufficient funds in the<br />
server's wallet. For example, if your wallet account balances were 100 BTC in account<br />
'foo' and 0 BTC in the default account, then the balances after ''sendtoaddress<br />
1PC9aZC4hNX2rmmrt7uHTfYAS3hRbph4UN 10.00'' would be 100 in account 'foo' and -10.00 in<br />
the default account (and the overall server balance would go from 100 to 90 BTC). On<br />
the other hand, using 'sendfrom' to send from the default account with a zero balance<br />
will fail with message "Account has insufficient funds".<br />
<br />
- The check for sufficient funds is done before paying transaction fees (if any); if a<br />
[[transaction fee]] is needed, and there are sufficient funds in the wallet, then the<br />
transaction fee will be paid and debited from the account. For example, if account<br />
'foo' contains 10 bitcoins, you ''sendfrom foo 15VjRaDX9zpbA8LVnbrCAFzrVzN7ixHNsC 10'',<br />
and the transaction costs 0.01, 'foo's balance will be -0.01 bitcoins.<br />
<br />
== Account -> Account Transfers ==<br />
<br />
Use the ''move'' method to transfer balances from one account to another. Moves from the default account to any other account always succeed; moves from any other account will fail if the account has insufficient funds. Moves are not broadcast to the network, and never incur transaction fees; they just adjust account balances in the wallet.<br />
<br />
== Account Balance and History==<br />
<br />
The ''getbalance'' method returns the bitcoin balance for either the entire wallet (if no argument is given) or for a particular account.<br />
<br />
The ''listtransactions <account> [N]'' method returns the last N (default 10) transactions that affected the account's balance. "listtransactions '*' [N]" will return the last N transactions for all accounts.<br />
<br />
== Typical Uses ==<br />
<br />
This section describes how typical web site code running on a web server uses the JSON-RPC API to keep track of customers' accounts.<br />
* Customer '''creates an account''' on the website: web server either assigns them a unique customer id number or uses their email address or other unique identifier, calls ''getaccountaddress "userid"'' and tells the customer to send to that address to fund their account.<br />
* Customer '''receives coins''' to fund their account: web server isn't involved.<br />
* Customer is shown their '''current balance''': ''getbalance "userid" 6'' to get their 'confirmed' balance, and subtracts it from ''getbalance "userid" 0'' to get their 'unconfirmed' balance.<br />
* Show the customer an **itemized list** of transactions: ''listtransactions "userid"''<br />
* Customer '''sends coins''' to another bitcoin address: ''sendfrom "userid" <address> <amount>''<br />
* Customer '''transfers coins''' to another customer: ''move "userid1" "userid2" <amount>''<br />
* You '''make a sale''', paid for with bitcoins in the customer's account: ''move "userid" "" <amount> 6 "purchased item"'', and if it succeeds, send them the product.<br />
* Customer is '''charged a fee''' for use of the service: ''move "userid" "FEES" <amount>'' (using special accounts like "FEES" can make your application's logic much simpler)<br />
* Customer '''purchases bitcoins''' from you: ''move "AVAILABLE" "userid" <amount>'' (assuming the bitcoins you are selling are kept track of in an "AVAILABLE" account)<br />
<br />
==See Also==<br />
<br />
* [[Original Bitcoin client/API_Calls_list|API_Calls_list]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Help:Accounts_explained&diff=40988Help:Accounts explained2013-09-12T01:07:58Z<p>Gavinandresen: /* Introduction */</p>
<hr />
<div>== Introduction ==<br />
<br />
Think about what happens when you give a bank teller some cash and ask that it be deposited into your account. You tell them your account number, and they credit your account with that amount of money.<br />
<br />
The money itself is mixed up with all of the other money in the bank, and is given out to other customers with other account numbers.<br />
<br />
With the Bitcoin "accounts" feature, you are the bank. The balance you see is the total balance for all accounts, and you can create an arbitrary number of accounts.<br />
<br />
When you receive bitcoins, they are always assigned to one of your accounts, and you can change which account is credited based on which bitcoin address receives the coins, just like you tell a bank teller which account to credit when you deposit cash in your bank. However, sending bitcoins is like withdrawing cash from the bank; the coins that are sent out and debited from an account are almost always not the same coins that were deposited into that account.<br />
<br />
== Accounts ==<br />
<br />
Bitcoin version 0.3.18 and later implements several RPC methods to maintain separate account balances in a single Bitcoin wallet. The accounts feature makes it easy to keep track of how much money you have received from different sources or to keep track of how much money you have spent on different things.<br />
<br />
== Account Weaknesses ==<br />
<br />
Since the accounts feature was introduced, several services have used it to keep track of customer's bitcoin balances and have had the following problems:<br />
<br />
* Wallet backups are an issue; if you rely on a good backup of wallet.dat then a backup must be done every time an address is associated with an account and every time the 'move' command is used.<br />
* The accounts code does not scale up to thousands of accounts with tens of thousands of transactions, because by-account (and by-account-by-time) indices are not implemented. So many operations (like computing an account balance) require accessing every wallet transaction.<br />
* Most applications already have a customer database, implemented with MySQL or some other relational database technology. It is awkward at best to keep the bitcoin-maintained Berkely DB database and the application database backed up and synchronized at all times.<br />
<br />
== Account Names ==<br />
<br />
Accounts are named with arbitrary strings; you may use any [http://www.json.org/ JSON] string other than "*" (JSON strings are sent and returned as UTF-8 encoded Unicode).<br />
<br />
Bitcoin creates two accounts automatically: it implicitly creates a default account with the empty string as its name, and it explicitly creates an account named '''Your Address''' when a new wallet is created.<br />
<br />
== The Default Account ==<br />
<br />
The default account is named with the empty string ("" in JSON). Generated coins are always credited to the default account, and the ''sendtoaddress'' method always debits the default account.<br />
<br />
== Accounts and Receiving Addresses ==<br />
<br />
Each account is associated with zero or more receiving addresses, and every receiving address is associated with exactly one account. Coins sent to a receiving address in the wallet are credited to the associated account.<br />
<br />
Accounts are associated with receiving addresses by using the ''getaccountaddress'', ''getnewaddress'' or ''setaccount'' methods.<br />
<br />
''getaccountaddress'' will return the same address until coins are received on that address; once coins have been received, it will generate and return a new address.<br />
<br />
''getnewaddress'' always generates and returns a new address.<br />
<br />
''setaccount'' changes the account associated with an existing address. Coins previously received on that address (if any) will be debited from the previous account's balance and credited to the address' new account. Note that doing so may make the previous account's balance negative.<br />
<br />
Use the ''getaddressesbyaccount'' method to list all addresses associated with an account.<br />
<br />
== Sending ==<br />
<br />
The ''sendfrom'' method sends coins and debits the specified account. It does **not** change Bitcoin's algorithm for selecting which coins in the wallet are sent-- you should think of the coins in the wallet as being mixed together when they are received. There is no way to ask Bitcoin to "create a payment transaction using the coins received from these previously received transactions."<br />
<br />
The ''sendtoaddress'' method works like ''sendfrom'', but always debits the default account.<br />
<br />
The send will fail if the account has insufficient funds, with two exceptions:<br />
<br />
- 'sendtoaddress' always succeeds if there are sufficient funds in the<br />
server's wallet. For example, if your wallet account balances were 100 BTC in account<br />
'foo' and 0 BTC in the default account, then the balances after ''sendtoaddress<br />
1PC9aZC4hNX2rmmrt7uHTfYAS3hRbph4UN 10.00'' would be 100 in account 'foo' and -10.00 in<br />
the default account (and the overall server balance would go from 100 to 90 BTC). On<br />
the other hand, using 'sendfrom' to send from the default account with a zero balance<br />
will fail with message "Account has insufficient funds".<br />
<br />
- The check for sufficient funds is done before paying transaction fees (if any); if a<br />
[[transaction fee]] is needed, and there are sufficient funds in the wallet, then the<br />
transaction fee will be paid and debited from the account. For example, if account<br />
'foo' contains 10 bitcoins, you ''sendfrom foo 15VjRaDX9zpbA8LVnbrCAFzrVzN7ixHNsC 10'',<br />
and the transaction costs 0.01, 'foo's balance will be -0.01 bitcoins.<br />
<br />
== Account -> Account Transfers ==<br />
<br />
Use the ''move'' method to transfer balances from one account to another. Moves from the default account to any other account always succeed; moves from any other account will fail if the account has insufficient funds. Moves are not broadcast to the network, and never incur transaction fees; they just adjust account balances in the wallet.<br />
<br />
== Account Balance and History==<br />
<br />
The ''getbalance'' method returns the bitcoin balance for either the entire wallet (if no argument is given) or for a particular account.<br />
<br />
The ''listtransactions <account> [N]'' method returns the last N (default 10) transactions that affected the account's balance. "listtransactions '*' [N]" will return the last N transactions for all accounts.<br />
<br />
== Typical Uses ==<br />
<br />
This section describes how typical web site code running on a web server uses the JSON-RPC API to keep track of customers' accounts.<br />
* Customer '''creates an account''' on the website: web server either assigns them a unique customer id number or uses their email address or other unique identifier, calls ''getaccountaddress "userid"'' and tells the customer to send to that address to fund their account.<br />
* Customer '''receives coins''' to fund their account: web server isn't involved.<br />
* Customer is shown their '''current balance''': ''getbalance "userid" 6'' to get their 'confirmed' balance, and subtracts it from ''getbalance "userid" 0'' to get their 'unconfirmed' balance.<br />
* Show the customer an **itemized list** of transactions: ''listtransactions "userid"''<br />
* Customer '''sends coins''' to another bitcoin address: ''sendfrom "userid" <address> <amount>''<br />
* Customer '''transfers coins''' to another customer: ''move "userid1" "userid2" <amount>''<br />
* You '''make a sale''', paid for with bitcoins in the customer's account: ''move "userid" "" <amount> 6 "purchased item"'', and if it succeeds, send them the product.<br />
* Customer is '''charged a fee''' for use of the service: ''move "userid" "FEES" <amount>'' (using special accounts like "FEES" can make your application's logic much simpler)<br />
* Customer '''purchases bitcoins''' from you: ''move "AVAILABLE" "userid" <amount>'' (assuming the bitcoins you are selling are kept track of in an "AVAILABLE" account)<br />
<br />
==See Also==<br />
<br />
* [[Original Bitcoin client/API_Calls_list|API_Calls_list]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Help:Accounts_explained&diff=40986Help:Accounts explained2013-09-12T01:06:26Z<p>Gavinandresen: Rewrote introduction with an analogy I like better, and added section on weaknesses.</p>
<hr />
<div>== Introduction ==<br />
<br />
Think about what happens when you give a bank teller some cash and ask that it be deposited into your account. You tell them your account number, and they credit your account with that amount of money.<br />
<br />
The money itself is mixed up with all of the other money in the bank, and is given out to other customers with other account numbers.<br />
<br />
With the Bitcoin "accounts" feature, you are the bank. The balance you see is the total balance for all accounts, and you can create an arbitrary number of accounts.<br />
<br />
When you receive bitcoins, they are always assigned to one of your accounts, and you can change which account is credited based on which bitcoin address receives the coins, just like you tell a bank teller which account to credit when you deposit cash in your bank. However, sending bitcoins is like withdrawing cash from the bank; the coins that are sent out are almost always not the same coins that were deposited.<br />
<br />
== Accounts ==<br />
<br />
Bitcoin version 0.3.18 and later implements several RPC methods to maintain separate account balances in a single Bitcoin wallet. The accounts feature makes it easy to keep track of how much money you have received from different sources or to keep track of how much money you have spent on different things.<br />
<br />
== Account Weaknesses ==<br />
<br />
Since the accounts feature was introduced, several services have used it to keep track of customer's bitcoin balances and have had the following problems:<br />
<br />
* Wallet backups are an issue; if you rely on a good backup of wallet.dat then a backup must be done every time an address is associated with an account and every time the 'move' command is used.<br />
* The accounts code does not scale up to thousands of accounts with tens of thousands of transactions, because by-account (and by-account-by-time) indices are not implemented. So many operations (like computing an account balance) require accessing every wallet transaction.<br />
* Most applications already have a customer database, implemented with MySQL or some other relational database technology. It is awkward at best to keep the bitcoin-maintained Berkely DB database and the application database backed up and synchronized at all times.<br />
<br />
== Account Names ==<br />
<br />
Accounts are named with arbitrary strings; you may use any [http://www.json.org/ JSON] string other than "*" (JSON strings are sent and returned as UTF-8 encoded Unicode).<br />
<br />
Bitcoin creates two accounts automatically: it implicitly creates a default account with the empty string as its name, and it explicitly creates an account named '''Your Address''' when a new wallet is created.<br />
<br />
== The Default Account ==<br />
<br />
The default account is named with the empty string ("" in JSON). Generated coins are always credited to the default account, and the ''sendtoaddress'' method always debits the default account.<br />
<br />
== Accounts and Receiving Addresses ==<br />
<br />
Each account is associated with zero or more receiving addresses, and every receiving address is associated with exactly one account. Coins sent to a receiving address in the wallet are credited to the associated account.<br />
<br />
Accounts are associated with receiving addresses by using the ''getaccountaddress'', ''getnewaddress'' or ''setaccount'' methods.<br />
<br />
''getaccountaddress'' will return the same address until coins are received on that address; once coins have been received, it will generate and return a new address.<br />
<br />
''getnewaddress'' always generates and returns a new address.<br />
<br />
''setaccount'' changes the account associated with an existing address. Coins previously received on that address (if any) will be debited from the previous account's balance and credited to the address' new account. Note that doing so may make the previous account's balance negative.<br />
<br />
Use the ''getaddressesbyaccount'' method to list all addresses associated with an account.<br />
<br />
== Sending ==<br />
<br />
The ''sendfrom'' method sends coins and debits the specified account. It does **not** change Bitcoin's algorithm for selecting which coins in the wallet are sent-- you should think of the coins in the wallet as being mixed together when they are received. There is no way to ask Bitcoin to "create a payment transaction using the coins received from these previously received transactions."<br />
<br />
The ''sendtoaddress'' method works like ''sendfrom'', but always debits the default account.<br />
<br />
The send will fail if the account has insufficient funds, with two exceptions:<br />
<br />
- 'sendtoaddress' always succeeds if there are sufficient funds in the<br />
server's wallet. For example, if your wallet account balances were 100 BTC in account<br />
'foo' and 0 BTC in the default account, then the balances after ''sendtoaddress<br />
1PC9aZC4hNX2rmmrt7uHTfYAS3hRbph4UN 10.00'' would be 100 in account 'foo' and -10.00 in<br />
the default account (and the overall server balance would go from 100 to 90 BTC). On<br />
the other hand, using 'sendfrom' to send from the default account with a zero balance<br />
will fail with message "Account has insufficient funds".<br />
<br />
- The check for sufficient funds is done before paying transaction fees (if any); if a<br />
[[transaction fee]] is needed, and there are sufficient funds in the wallet, then the<br />
transaction fee will be paid and debited from the account. For example, if account<br />
'foo' contains 10 bitcoins, you ''sendfrom foo 15VjRaDX9zpbA8LVnbrCAFzrVzN7ixHNsC 10'',<br />
and the transaction costs 0.01, 'foo's balance will be -0.01 bitcoins.<br />
<br />
== Account -> Account Transfers ==<br />
<br />
Use the ''move'' method to transfer balances from one account to another. Moves from the default account to any other account always succeed; moves from any other account will fail if the account has insufficient funds. Moves are not broadcast to the network, and never incur transaction fees; they just adjust account balances in the wallet.<br />
<br />
== Account Balance and History==<br />
<br />
The ''getbalance'' method returns the bitcoin balance for either the entire wallet (if no argument is given) or for a particular account.<br />
<br />
The ''listtransactions <account> [N]'' method returns the last N (default 10) transactions that affected the account's balance. "listtransactions '*' [N]" will return the last N transactions for all accounts.<br />
<br />
== Typical Uses ==<br />
<br />
This section describes how typical web site code running on a web server uses the JSON-RPC API to keep track of customers' accounts.<br />
* Customer '''creates an account''' on the website: web server either assigns them a unique customer id number or uses their email address or other unique identifier, calls ''getaccountaddress "userid"'' and tells the customer to send to that address to fund their account.<br />
* Customer '''receives coins''' to fund their account: web server isn't involved.<br />
* Customer is shown their '''current balance''': ''getbalance "userid" 6'' to get their 'confirmed' balance, and subtracts it from ''getbalance "userid" 0'' to get their 'unconfirmed' balance.<br />
* Show the customer an **itemized list** of transactions: ''listtransactions "userid"''<br />
* Customer '''sends coins''' to another bitcoin address: ''sendfrom "userid" <address> <amount>''<br />
* Customer '''transfers coins''' to another customer: ''move "userid1" "userid2" <amount>''<br />
* You '''make a sale''', paid for with bitcoins in the customer's account: ''move "userid" "" <amount> 6 "purchased item"'', and if it succeeds, send them the product.<br />
* Customer is '''charged a fee''' for use of the service: ''move "userid" "FEES" <amount>'' (using special accounts like "FEES" can make your application's logic much simpler)<br />
* Customer '''purchases bitcoins''' from you: ''move "AVAILABLE" "userid" <amount>'' (assuming the bitcoins you are selling are kept track of in an "AVAILABLE" account)<br />
<br />
==See Also==<br />
<br />
* [[Original Bitcoin client/API_Calls_list|API_Calls_list]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Alert_system&diff=40701Alert system2013-09-04T04:40:07Z<p>Gavinandresen: Mention -alertnotify command-line option.</p>
<hr />
<div>[[File:alert.png|thumb|300px|right]]<br />
<br />
Bitcoin versions 0.3.10 and later have an alert system which allows messages about critical network problems to be broadcast to all clients. When an alert is in effect, the message it contains will appear in the status bar of all clients, in the "errors" field of RPC ''getinfo'', and will notify any script registered with Bitcoin-Qt/bitcoind -alertnotify command-line option.<br />
<br />
[[File:Bitcoin-alert-cli.png|thumb|300px|right]]<br />
<br />
===Alert message===<br />
Alerts are broadcast using the same [[network|TCP relay system]] as ''block'' and ''tx'' messages. They are not encoded in a special transaction. Unlike block and tx relaying, alerts are sent at the start of every new connection for as long as the alert is in effect. This ensures that everyone receives the alert.<br />
<br />
Alerts contain this information:<br />
* How long to relay the alert.<br />
* How long to consider the alert valid.<br />
* An alert ID number.<br />
* A list of alerts that should be canceled upon receipt of this alert.<br />
* Exactly which versions of Bitcoin are affected by the alert. Unaffected versions still relay the alert for the benefit of older versions.<br />
* Alert priority.<br />
* The alert text.<br />
<br />
Only alerts that are signed by a specific ECDSA public key are considered valid. A copy of the private key is held by at least Satoshi, Gavin, and theymos.<br />
<br />
===Safe mode===<br />
Until version 0.3.20, Bitcoin went into safe mode when a valid alert was received. In safe mode, all RPC commands that send BTC or get info about received BTC return an error. Current Bitcoin versions no longer go into safe mode in response to alerts, though Bitcoin ''will'' still go into safe mode when it detects on its own that something is seriously wrong with the network.<br />
<br />
Even though Bitcoin no longer automatically disables RPC when an alert is live, it is wise for Bitcoin sites to shut down when an alert has been issued. To detect an active alert, poll the "errors" field of ''getinfo''.<br />
<br />
To test safe mode, run Bitcoin with the -testsafemode switch. To override a real safe mode event, run Bitcoin with the -disablesafemode switch.<br />
<br />
===Past alerts===<br />
{| class="wikitable" border="1"<br />
|-<br />
! ID<br />
! Sent date<br />
! Expires (UTC)<br />
! Versions<br />
! Priority<br />
! Message<br />
|-<br />
| 1010<br />
| Feb 18, 2012<br />
| Feb 21 02:47:15<br />
| All<br />
| 100<br />
| See bitcoin.org/feb20 if you have trouble connecting after 20 February<br />
|-<br />
| 1011<br />
| Mar 16, 2012<br />
| cancelled May 15, 2012<br />
| 0.5 - 0.5.3<br />
| 5000<br />
| URGENT: security fix for Bitcoin-Qt on Windows: http://bitcoin.org/critfix<br />
|-<br />
| 1012<br />
| Mar 16, 2012<br />
| cancelled May 15, 2012<br />
| 6.0<br />
| 5000<br />
| URGENT: security fix for Bitcoin-Qt on Windows: http://bitcoin.org/critfix<br />
|-<br />
| 1013<br />
| Mar 16, 2012<br />
| cancelled May 15, 2012<br />
| 5.99<br />
| 5000<br />
| URGENT: security fix for Bitcoin-Qt on Windows: http://bitcoin.org/critfix<br />
|-<br />
| 1015<br />
| May 15, 2012<br />
| May 16, 2013<br />
| 0.1 - 0.4.5<br />
| 5000<br />
| URGENT: upgrade required, see http://bitcoin.org/dos for details<br />
|-<br />
| 1016<br />
| May 15, 2012<br />
| May 16, 2013<br />
| 0.4.99 - 0.5.4<br />
| 5000<br />
| URGENT: upgrade required, see http://bitcoin.org/dos for details<br />
|-<br />
| 1020<br />
| May 15, 2012<br />
| May 16, 2013<br />
| 0.6.0<br />
| 5000<br />
| URGENT: upgrade required, see http://bitcoin.org/dos for details<br />
|-<br />
| 1032<br />
| March 12, 2013<br />
| March 13, 2013<br />
| 0.8.0<br />
| 5000<br />
| URGENT: chain fork, stop mining on version 0.8<br />
|-<br />
| 1033<br />
| March 19, 2013<br />
| March 20, 2013<br />
| 0.1 - 0.7.2<br />
| 10<br />
| See http://bitcoin.org/may15.html for an important message<br />
|-<br />
| 1034<br />
| May 9, 2013<br />
| June 8, 2013<br />
| 0.1 - 0.7.2<br />
| 10<br />
| Action required: see http://bitcoin.org/may15.html for more information<br />
|}<br />
<br />
==See Also==<br />
<br />
* [[Alerts mailing list]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Vocabulary]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=40696Template:MainPage Intro2013-09-04T01:29:44Z<p>Gavinandresen: Update links to 0.8.4</p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first implementations of a concept called ''crypto-currency'' which was first described in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Bitcoin-Qt:'''<br />
{|style="background-color: inherit;"<br />
|<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.4/bitcoin-0.8.4-win32-setup.exe/download '''Windows (exe)'''] 10 MB [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.4/bitcoin-0.8.4-win32.zip/download '''(zip)'''] 14 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.4/bitcoin-0.8.4-linux.tar.gz/download '''GNU/Linux'''] 13 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.4/bitcoin-0.8.4-macosx.dmg/download '''Mac OS X'''] 12 MB<br />
|}<br />
<br />
[http://bitcoin.org/clients.html More Bitcoin Client Software]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0071&diff=40534BIP 00712013-08-28T01:47:29Z<p>Gavinandresen: PaymentRequestACK --> PaymentACK</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 71<br />
Title: Payment Protocol MIME types<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment<br />
request messages.<br />
<br />
==Motivation==<br />
<br />
Wallet or server software that sends payment protocol messages over<br />
email or http should follow Internet standards for properly<br />
encapsulating the messages.<br />
<br />
==Specification==<br />
<br />
The Media Type (Content-Type in HTML/email headers) for bitcoin<br />
protocol messages shall be:<br />
<br />
{|<br />
| Message || Type/Subtype<br />
|-<br />
| PaymentRequest || application/bitcoin-paymentrequest<br />
|-<br />
| Payment || application/bitcoin-payment<br />
|-<br />
| PaymentACK || application/bitcoin-paymentack<br />
|}<br />
<br />
Payment protocol messages are encoded in binary.<br />
<br />
==Example==<br />
<br />
A web server generating a PaymentRequest message to initiate the<br />
payment protocol would precede the binary message data with the<br />
following headers:<br />
<pre><br />
Content-Type: application/bitcoin-paymentrequest<br />
Content-Transfer-Encoding: binary<br />
</pre><br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=40533BIP 00702013-08-28T01:46:51Z<p>Gavinandresen: Require Accept: and Content-Type headers in Payment->PaymentACK round trip.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url should be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
Wallet software sending Payment messages via HTTP must set appropriate<br />
Content-Type and Accept headers, as specified in BIP 71:<br />
<pre>Content-Type: application/bitcoin-payment<br />
Accept: application/bitcoin-paymentack<br />
</pre><br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| payment || Copy of the Payment message that triggered this PaymentACK. Clients may ignore this if they implement another way of associating Payments with PaymentACKs.<br />
|-<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest must be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one, up to a trusted root<br />
authority. The recipient must verify the certificate chain according to<br />
[RFC5280] and reject the PaymentRequest if any validation failure<br />
occurs.<br />
<br />
Trusted root certificates may be obtained from the operating system;<br />
if validation is done on a device without an operating system, the<br />
[http://www.mozilla.org/projects/security/certs/included/index.html Mozilla root store] is recommended.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0072&diff=40532BIP 00722013-08-28T01:33:54Z<p>Gavinandresen: Require Accept: header</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 72<br />
Title: bitcoin: uri extensions for Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to<br />
support the payment protocol (BIP 70).<br />
<br />
==Motivation==<br />
<br />
Allow users to click on a link in a web page or email to initiate the<br />
payment protocol, while being backwards-compatible with existing<br />
bitcoin wallets.<br />
<br />
==Specification==<br />
<br />
The bitcoin: URI scheme is extended with an additional, optional<br />
"request" parameter, whose value is a URL from which a PaymentRequest<br />
message should be fetched (unsafe and reserved octets in the URL value<br />
must be encoded as described in RFC 1738).<br />
<br />
If the "request" parameter is provided and backwards compatibility<br />
is not required, then the bitcoin address portion of the URI may be<br />
omitted (the URI will be of the form: bitcoin:?request=... ).<br />
<br />
When Bitcoin wallet software that supports this BIP receives a<br />
bitcoin: URI with a request parameter, it should ignore the bitcoin<br />
address/amount/label/message in the URI and instead fetch a<br />
PaymentRequest message and then follow the payment protocol, as<br />
described in BIP 70.<br />
<br />
Bitcoin wallets must support fetching PaymentRequests via http and<br />
https protocols; they may support other protocols. Wallets must<br />
include an Accept HTTP header in HTTP requests:<br />
<pre>Accept: application/bitcoin-paymentrequest</pre><br />
<br />
If a PaymentRequest cannot be obtained (perhaps the server is<br />
unavailable), then the customer should be informed that the merchant's<br />
payment processing system is unavailable.<br />
<br />
==Compatibility==<br />
<br />
Wallet software that does not support this BIP will simply ignore the<br />
request parameter and will initiate a payment to bitcoin address.<br />
<br />
==Examples==<br />
A backwards-compatible request:<br />
<pre><br />
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
Non-backwards-compatible equivalent:<br />
<pre><br />
bitcoin:?request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0050&diff=40481BIP 00502013-08-25T22:55:29Z<p>Gavinandresen: Add Resolution section on block 22451</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 50<br />
Title: March 2013 Chain Fork Post-Mortem<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Informational<br />
Created: 20-03-2013<br />
</pre><br />
<br />
==What went wrong==<br />
A block that had a larger number of total transaction inputs than previously seen was mined and broadcasted. Bitcoin 0.8 nodes were able to handle this, but some pre-0.8 Bitcoin nodes rejected it, causing an unexpected hard fork of the chain. The pre-0.8 incompatible chain at that point had around 60% of the hash power ensuring the split did not automatically resolve.<br />
<br />
In order to restore a canonical chain as soon as possible, BTCGuild and Slush downgraded their Bitcoin 0.8 nodes to 0.7 so their pools would also reject the larger block. This placed majority hashpower on the chain without the larger block.<br />
<br />
During this time there was at least [https://bitcointalk.org/index.php?topic=152348.0 one large double spend]. However, it was done by someone experimenting to see if it was possible and was not intended to be malicious.<br />
<br />
==What went right==<br />
* The split was detected very quickly.<br />
* The right people were online and available in IRC or could be raised via Skype.<br />
* Marek Palatinus and Michael Marsee quickly downgraded their nodes to restore a pre-0.8 chain as canonical, despite the fact that this caused them to sacrifice significant amounts of money and they were the ones running the bug-free version.<br />
* Deposits to the major exchanges and payments via BitPay were also suspended (and then un-suspended) very quickly.<br />
* Fortunately, the only attack on a merchant was done by someone who was not intending to actually steal money<br />
<br />
==Root cause==<br />
Bitcoin versions prior to 0.8 configure an insufficient number of Berkeley DB locks to process large but technically valid blocks. Berkeley DB locks have to be manually configured by API users depending on anticipated load. The manual says this:<br />
<br />
:The recommended algorithm for selecting the maximum number of locks, lockers, and lock objects is to run the application under stressful conditions and then review the lock system's statistics to determine the maximum number of locks, lockers, and lock objects that were used. Then, double these values for safety.<br />
<br />
Because max-sized blocks had been successfully processed on the testnet, it did not occur to anyone that there could be blocks that were smaller but require more locks than were available. Prior to 0.7 unmodified mining nodes self-imposed a maximum block size of 500,000 bytes, which further prevented this case from being triggered. 0.7 made the target size configurable and miners had been encouraged to increase this target in the week prior to the incident.<br />
<br />
Bitcoin 0.8 does not use Berkeley DB. It uses LevelDB instead, which does not require this kind of pre-configuration. Therefore it was able to process the forking block successfully.<br />
<br />
Note that BDB locks are also required during processing of re-organizations. Versions prior to 0.8 may be unable to process some valid re-orgs.<br />
<br />
This would be an issue even if the entire network was running version 0.7.2. It is theoretically possible for one 0.7.2 node to create a block that others are unable to validate, or for 0.7.2 nodes to create block re-orgs that peers cannot validate, because the contents of each node's blkindex.dat database is not identical, and the number of locks required depends on the exact arrangement of the blkindex.dat on disk (locks are acquired per-page).<br />
<br />
==Action items==<br />
<br />
===Immediately===<br />
<br />
'''Done''': Release a version 0.8.1, forked directly from 0.8.0, that, for the next two months has the following new rules:<br />
# Reject blocks that could cause more than 10,000 locks to be taken.<br />
# Limit the maximum block-size created to 500,000 bytes<br />
# Release a patch for older versions that implements the same rules, but also increases the maximum number of locks to 120,000<br />
# Create a web page on bitcoin.org that will urge users to upgrade to 0.8.1, but will tell them how to set DB_CONFIG to 120,000 locks if they absolutely cannot.<br />
# Over the next 2 months, send a series of alerts to users of older versions, pointing to the web page.<br />
<br />
===Alert system===<br />
<br />
'''Done''': Review who has access to the alert system keys, make sure they all have contact information for each other, and get good timezone overlap by people with access to the keys.<br />
<br />
'''Done''': Implement a new bitcoind feature so services can get timely notification of alerts: -alertnotify=<command> Run command when an AppliesToMe() alert is received.<br />
<br />
'''Done''': Pre-generate 52 test alerts, and set a time every week when they are broadcast on -testnet (so -alertnotify scripts can be tested in as-close-to-real-world conditions as possible).<br />
<br />
Idea from Michael Gronager: encourage merchants/exchanges (and maybe pools) to run new code behind a bitcoind running the network-majority version.<br />
<br />
===Safe mode===<br />
<br />
'''Done''': Perhaps trigger an alert if there is a long enough side chain detected, even if it is not the main chain. Pools could use this to automatically suspend payouts if a long side-chain suddenly appeared out of nowhere (it’s hard for an attacker to mine such a thing).<br />
<br />
===Testing===<br />
<br />
Start running bots on the testnet that grab some coins from a testnet faucet, generate large numbers of random transactions that split/recombine them and then send them back to the faucet. Randomized online testing on the testnet might have revealed the pathological block type earlier.<br />
<br />
===Double spending===<br />
<br />
A double spend attack was successful, despite that both sides of the chain heard about the transactions in the same order. The reason is most likely that the memory pools were cleared when the mining pool nodes were downgraded. A solution is for nodes to sync their mempools to each other at startup, however, this requires a memory pool expiry policy to be implemented as currently node restarts are the only way for unconfirmed transactions to be evicted from the system.<br />
<br />
===Resolution===<br />
<br />
On 22 August, 2013 block 22,451 was accepted by the main network, forking unpatched nodes off the network.</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=API_reference_(JSON-RPC)&diff=40196API reference (JSON-RPC)2013-08-15T05:10:49Z<p>Gavinandresen: /* JSON-RPC */</p>
<hr />
<div>== Controlling Bitcoin ==<br />
<br />
Run ''bitcoind'' or ''bitcoin-qt -server''. You can control it via the command-line or by [http://json-rpc.org/wiki/specification HTTP JSON-RPC] commands.<br />
<br />
You must create a bitcoin.conf configuration file setting an rpcuser and rpcpassword; see [[Running Bitcoin]] for details.<br />
<br />
Now run:<br />
$ ./bitcoind -daemon<br />
bitcoin server starting<br />
$ ./bitcoind help<br />
# shows the help text<br />
<br />
A [[Original Bitcoin client/API Calls list|list of RPC calls]] will be shown.<br />
<br />
$ ./bitcoind getbalance<br />
2000.00000<br />
<br />
== JSON-RPC ==<br />
<br />
Running Bitcoin with the -server argument (or running bitcoind) tells it to function as a [http://json-rpc.org/wiki/specification HTTP JSON-RPC] server, but <br />
[http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication] must be used when communicating with it, and, for security, by default, the server only accepts connections from other processes on the same machine. If your HTTP or JSON library requires you to specify which 'realm' is authenticated, use 'jsonrpc'.<br />
<br />
Bitcoin supports SSL (https) JSON-RPC connections beginning with version 0.3.14. See the [[Enabling SSL on original client daemon|rpcssl wiki page]] for setup instructions and a list of all bitcoin.conf configuration options.<br />
<br />
Allowing arbitrary machines to access the JSON-RPC port (using the rpcallowip [[Running_Bitcoin|configuration option]]) is dangerous and '''strongly discouraged'''-- access should be strictly limited to trusted machines.<br />
<br />
To access the server you should find a [http://json-rpc.org/wiki/implementations suitable library] for your language.<br />
<br />
== Proper money handling ==<br />
<br />
See the [[Proper Money Handling (JSON-RPC)|proper money handling page]] for notes on avoiding rounding errors when handling bitcoin values.<br />
<br />
== Python ==<br />
<br />
[http://json-rpc.org/wiki/python-json-rpc python-jsonrpc] is the official JSON-RPC implementation for Python.<br />
It automatically generates Python methods for RPC calls.<br />
However, due to its design for supporting old versions of Python, it is also rather inefficient.<br />
[[User:jgarzik|jgarzik]] has forked it as [https://github.com/jgarzik/python-bitcoinrpc Python-BitcoinRPC] and optimized it for current versions.<br />
Generally, this version is recommended.<br />
<br />
While BitcoinRPC lacks a few obscure features from jsonrpc, software using only the ServiceProxy class can be written the same to work with either version the user might choose to install:<br />
<br />
<source lang="python"><br />
from jsonrpc import ServiceProxy<br />
<br />
access = ServiceProxy("http://user:password@127.0.0.1:8332")<br />
access.getinfo()<br />
access.listreceivedbyaddress(6)<br />
#access.sendtoaddress("11yEmxiMso2RsFVfBcCa616npBvGgxiBX", 10)<br />
</source><br />
<br />
== Ruby ==<br />
<br />
<source lang="ruby"><br />
require 'net/http'<br />
require 'uri'<br />
require 'json'<br />
<br />
class BitcoinRPC<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.basic_auth @uri.user, @uri.password<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
<br />
if $0 == __FILE__<br />
h = BitcoinRPC.new('http://user:password@127.0.0.1:8332')<br />
p h.getbalance<br />
p h.getinfo<br />
p h.getnewaddress<br />
p h.dumpprivkey( h.getnewaddress )<br />
# also see: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list<br />
end<br />
</source><br />
<br />
== PHP ==<br />
<br />
The [http://jsonrpcphp.org/ JSON-RPC PHP] library also makes it very easy to connect to Bitcoin. For example:<br />
<br />
<source lang="php"><br />
require_once 'jsonRPCClient.php';<br />
<br />
$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');<br />
<br />
echo "<pre>\n";<br />
print_r($bitcoin->getinfo()); echo "\n";<br />
echo "Received: ".$bitcoin->getreceivedbylabel("Your Address")."\n";<br />
echo "</pre>";<br />
</source><br />
<br />
== Java ==<br />
<br />
The easiest way to tell Java to use HTTP Basic authentication is to set a default Authenticator:<br />
<br />
<source lang="java"><br />
final String rpcuser ="...";<br />
final String rpcpassword ="...";<br />
<br />
Authenticator.setDefault(new Authenticator() {<br />
protected PasswordAuthentication getPasswordAuthentication() {<br />
return new PasswordAuthentication (rpcuser, rpcpassword.toCharArray());<br />
}<br />
});<br />
</source><br />
<br />
Once that is done, any JSON-RPC library for Java (or ordinary URL POSTs) may be used to communicate with the Bitcoin server.<br />
<br />
== Perl ==<br />
<br />
The JSON::RPC package from CPAN can be used to communicate with Bitcoin. You must set the client's credentials; for example:<br />
<br />
<source lang="perl"><br />
use JSON::RPC::Client;<br />
use Data::Dumper;<br />
<br />
my $client = new JSON::RPC::Client;<br />
<br />
$client->ua->credentials(<br />
'localhost:8332', 'jsonrpc', 'user' => 'password' # REPLACE WITH YOUR bitcoin.conf rpcuser/rpcpassword<br />
);<br />
<br />
my $uri = 'http://localhost:8332/';<br />
my $obj = {<br />
method => 'getinfo',<br />
params => [],<br />
};<br />
<br />
my $res = $client->call( $uri, $obj );<br />
<br />
if ($res){<br />
if ($res->is_error) { print "Error : ", $res->error_message; }<br />
else { print Dumper($res->result); }<br />
} else {<br />
print $client->status_line;<br />
}<br />
</source><br />
<br />
== .NET (C#) ==<br />
The communication with rpc service can be achieved using the standard httprequest/response objects.<br />
A library for serialising and deserialising Json will make your life a lot easier:<br />
<br />
* JayRock for .NET 4.0<br />
* Json.Net for .NET 2.0 and above <br />
<br />
The following example uses Json.Net:<br />
<br />
<source lang="csharp"><br />
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("http://localhost.:8332");<br />
webRequest.Credentials = new NetworkCredential("user", "pwd");<br />
/// important, otherwise the service can't desirialse your request properly<br />
webRequest.ContentType = "application/json-rpc";<br />
webRequest.Method = "POST";<br />
<br />
JObject joe = new JObject();<br />
joe.Add(new JProperty("jsonrpc", "1.0"));<br />
joe.Add(new JProperty("id", "1"));<br />
joe.Add(new JProperty("method", Method));<br />
// params is a collection values which the method requires..<br />
if (Params.Keys.Count == 0)<br />
{<br />
joe.Add(new JProperty("params", new JArray()));<br />
}<br />
else<br />
{<br />
JArray props = new JArray();<br />
// add the props in the reverse order!<br />
for (int i = Params.Keys.Count - 1; i >= 0; i--)<br />
{<br />
.... // add the params<br />
}<br />
joe.Add(new JProperty("params", props));<br />
}<br />
<br />
// serialize json for the request<br />
string s = JsonConvert.SerializeObject(joe);<br />
byte[] byteArray = Encoding.UTF8.GetBytes(s);<br />
webRequest.ContentLength = byteArray.Length;<br />
Stream dataStream = webRequest.GetRequestStream();<br />
dataStream.Write(byteArray, 0, byteArray.Length);<br />
dataStream.Close();<br />
<br />
<br />
WebResponse webResponse = webRequest.GetResponse();<br />
<br />
... // deserialze the response<br />
</source><br />
<br />
There is also a wrapper for Json.NET called Bitnet (https://sourceforge.net/projects/bitnet)<br />
implementing Bitcoin API in more convenient way:<br />
<br />
<source lang="csharp"><br />
BitnetClient bc = new BitnetClient("http://127.0.0.1:8332");<br />
bc.Credentials = new NetworkCredential("user", "pass");<br />
<br />
var p = bc.GetDifficulty();<br />
Console.WriteLine("Difficulty:" + p.ToString());<br />
<br />
var inf = bc.GetInfo();<br />
Console.WriteLine("Balance:" + inf["balance"]);<br />
</source><br />
<br />
== Node.js ==<br />
<br />
* [https://github.com/freewil/node-bitcoin node-bitcoin] (npm: bitcoin) <br />
<br />
Example using node-bitcoin:<br />
<br />
<source lang="javascript"><br />
var bitcoin = require('bitcoin');<br />
var client = new bitcoin.Client({<br />
host: 'localhost',<br />
port: 8332,<br />
user: 'user',<br />
pass: 'pass'<br />
});<br />
<br />
client.getDifficulty(function(err, difficulty) {<br />
if (err) {<br />
return console.error(err);<br />
}<br />
<br />
console.log('Difficulty: ' + difficulty);<br />
});<br />
</source><br />
<br />
Example using Kapitalize:<br />
<br />
<source lang='javascript'><br />
var client = require('kapitalize')()<br />
<br />
client.auth('user', 'password')<br />
<br />
client<br />
.getInfo()<br />
.getDifficulty(function(err, difficulty) {<br />
console.log('Dificulty: ', difficulty)<br />
})<br />
</source><br />
<br />
== Command line (cURL) ==<br />
<br />
You can also send commands and see results using [http://curl.haxx.se/ cURL] or some other command-line HTTP-fetching utility; for example:<br />
<br />
<source lang="bash"><br />
curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' <br />
-H 'content-type: text/plain;' http://127.0.0.1:8332/<br />
</source><br />
<br />
You will be prompted for your rpcpassword, and then will see something like:<br />
<br />
<source lang="javascript"><br />
{"result":{"balance":0.000000000000000,"blocks":59952,"connections":48,"proxy":"","generate":false,<br />
"genproclimit":-1,"difficulty":16.61907875185736,"error":null,"id":"curltest"}<br />
</source><br />
<br />
== See Also==<br />
<br />
* [[Original_Bitcoin_client/API_Calls_list|API calls list]]<br />
* [[Running Bitcoin]]<br />
* [[Lazy API]]<br />
* [[PHP developer intro]]<br />
* [[Raw_Transactions|Raw Transactions API]]<br />
* [http://blockchain.info/api/json_rpc_api Web Based JSON RPC interface.]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
[[zh-cn:API_reference_(JSON-RPC)]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=API_reference_(JSON-RPC)&diff=40195API reference (JSON-RPC)2013-08-15T05:10:20Z<p>Gavinandresen: /* JSON-RPC */</p>
<hr />
<div>== Controlling Bitcoin ==<br />
<br />
Run ''bitcoind'' or ''bitcoin-qt -server''. You can control it via the command-line or by [http://json-rpc.org/wiki/specification HTTP JSON-RPC] commands.<br />
<br />
You must create a bitcoin.conf configuration file setting an rpcuser and rpcpassword; see [[Running Bitcoin]] for details.<br />
<br />
Now run:<br />
$ ./bitcoind -daemon<br />
bitcoin server starting<br />
$ ./bitcoind help<br />
# shows the help text<br />
<br />
A [[Original Bitcoin client/API Calls list|list of RPC calls]] will be shown.<br />
<br />
$ ./bitcoind getbalance<br />
2000.00000<br />
<br />
== JSON-RPC ==<br />
<br />
Running Bitcoin with the -server argument (or running bitcoind) tells it to function as a [http://json-rpc.org/wiki/specification HTTP JSON-RPC] server, but <br />
[http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication] must be used when communicating with it, and, for security, by default, the server only accepts connections from other processes on the same machine. If your HTTP or JSON library requires you to specify which 'realm' is authenticated, use 'jsonrpc'.<br />
<br />
Bitcoin supports SSL (https) JSON-RPC connections beginning with version 0.3.14. See the [[Enabling SSL on original client daemon|rpcssl wiki page]] for setup instructions and a list of all bitcoin.conf configuration options.<br />
<br />
Allowing arbitrary machines to access the JSON-RPC port (using the rpcallowip [[Running_Bitcoin|configuration option]]) is dangerous and ''strongly discouraged''-- access should be strictly limited to trusted machines.<br />
<br />
To access the server you should find a [http://json-rpc.org/wiki/implementations suitable library] for your language.<br />
<br />
== Proper money handling ==<br />
<br />
See the [[Proper Money Handling (JSON-RPC)|proper money handling page]] for notes on avoiding rounding errors when handling bitcoin values.<br />
<br />
== Python ==<br />
<br />
[http://json-rpc.org/wiki/python-json-rpc python-jsonrpc] is the official JSON-RPC implementation for Python.<br />
It automatically generates Python methods for RPC calls.<br />
However, due to its design for supporting old versions of Python, it is also rather inefficient.<br />
[[User:jgarzik|jgarzik]] has forked it as [https://github.com/jgarzik/python-bitcoinrpc Python-BitcoinRPC] and optimized it for current versions.<br />
Generally, this version is recommended.<br />
<br />
While BitcoinRPC lacks a few obscure features from jsonrpc, software using only the ServiceProxy class can be written the same to work with either version the user might choose to install:<br />
<br />
<source lang="python"><br />
from jsonrpc import ServiceProxy<br />
<br />
access = ServiceProxy("http://user:password@127.0.0.1:8332")<br />
access.getinfo()<br />
access.listreceivedbyaddress(6)<br />
#access.sendtoaddress("11yEmxiMso2RsFVfBcCa616npBvGgxiBX", 10)<br />
</source><br />
<br />
== Ruby ==<br />
<br />
<source lang="ruby"><br />
require 'net/http'<br />
require 'uri'<br />
require 'json'<br />
<br />
class BitcoinRPC<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.basic_auth @uri.user, @uri.password<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
<br />
if $0 == __FILE__<br />
h = BitcoinRPC.new('http://user:password@127.0.0.1:8332')<br />
p h.getbalance<br />
p h.getinfo<br />
p h.getnewaddress<br />
p h.dumpprivkey( h.getnewaddress )<br />
# also see: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list<br />
end<br />
</source><br />
<br />
== PHP ==<br />
<br />
The [http://jsonrpcphp.org/ JSON-RPC PHP] library also makes it very easy to connect to Bitcoin. For example:<br />
<br />
<source lang="php"><br />
require_once 'jsonRPCClient.php';<br />
<br />
$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');<br />
<br />
echo "<pre>\n";<br />
print_r($bitcoin->getinfo()); echo "\n";<br />
echo "Received: ".$bitcoin->getreceivedbylabel("Your Address")."\n";<br />
echo "</pre>";<br />
</source><br />
<br />
== Java ==<br />
<br />
The easiest way to tell Java to use HTTP Basic authentication is to set a default Authenticator:<br />
<br />
<source lang="java"><br />
final String rpcuser ="...";<br />
final String rpcpassword ="...";<br />
<br />
Authenticator.setDefault(new Authenticator() {<br />
protected PasswordAuthentication getPasswordAuthentication() {<br />
return new PasswordAuthentication (rpcuser, rpcpassword.toCharArray());<br />
}<br />
});<br />
</source><br />
<br />
Once that is done, any JSON-RPC library for Java (or ordinary URL POSTs) may be used to communicate with the Bitcoin server.<br />
<br />
== Perl ==<br />
<br />
The JSON::RPC package from CPAN can be used to communicate with Bitcoin. You must set the client's credentials; for example:<br />
<br />
<source lang="perl"><br />
use JSON::RPC::Client;<br />
use Data::Dumper;<br />
<br />
my $client = new JSON::RPC::Client;<br />
<br />
$client->ua->credentials(<br />
'localhost:8332', 'jsonrpc', 'user' => 'password' # REPLACE WITH YOUR bitcoin.conf rpcuser/rpcpassword<br />
);<br />
<br />
my $uri = 'http://localhost:8332/';<br />
my $obj = {<br />
method => 'getinfo',<br />
params => [],<br />
};<br />
<br />
my $res = $client->call( $uri, $obj );<br />
<br />
if ($res){<br />
if ($res->is_error) { print "Error : ", $res->error_message; }<br />
else { print Dumper($res->result); }<br />
} else {<br />
print $client->status_line;<br />
}<br />
</source><br />
<br />
== .NET (C#) ==<br />
The communication with rpc service can be achieved using the standard httprequest/response objects.<br />
A library for serialising and deserialising Json will make your life a lot easier:<br />
<br />
* JayRock for .NET 4.0<br />
* Json.Net for .NET 2.0 and above <br />
<br />
The following example uses Json.Net:<br />
<br />
<source lang="csharp"><br />
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("http://localhost.:8332");<br />
webRequest.Credentials = new NetworkCredential("user", "pwd");<br />
/// important, otherwise the service can't desirialse your request properly<br />
webRequest.ContentType = "application/json-rpc";<br />
webRequest.Method = "POST";<br />
<br />
JObject joe = new JObject();<br />
joe.Add(new JProperty("jsonrpc", "1.0"));<br />
joe.Add(new JProperty("id", "1"));<br />
joe.Add(new JProperty("method", Method));<br />
// params is a collection values which the method requires..<br />
if (Params.Keys.Count == 0)<br />
{<br />
joe.Add(new JProperty("params", new JArray()));<br />
}<br />
else<br />
{<br />
JArray props = new JArray();<br />
// add the props in the reverse order!<br />
for (int i = Params.Keys.Count - 1; i >= 0; i--)<br />
{<br />
.... // add the params<br />
}<br />
joe.Add(new JProperty("params", props));<br />
}<br />
<br />
// serialize json for the request<br />
string s = JsonConvert.SerializeObject(joe);<br />
byte[] byteArray = Encoding.UTF8.GetBytes(s);<br />
webRequest.ContentLength = byteArray.Length;<br />
Stream dataStream = webRequest.GetRequestStream();<br />
dataStream.Write(byteArray, 0, byteArray.Length);<br />
dataStream.Close();<br />
<br />
<br />
WebResponse webResponse = webRequest.GetResponse();<br />
<br />
... // deserialze the response<br />
</source><br />
<br />
There is also a wrapper for Json.NET called Bitnet (https://sourceforge.net/projects/bitnet)<br />
implementing Bitcoin API in more convenient way:<br />
<br />
<source lang="csharp"><br />
BitnetClient bc = new BitnetClient("http://127.0.0.1:8332");<br />
bc.Credentials = new NetworkCredential("user", "pass");<br />
<br />
var p = bc.GetDifficulty();<br />
Console.WriteLine("Difficulty:" + p.ToString());<br />
<br />
var inf = bc.GetInfo();<br />
Console.WriteLine("Balance:" + inf["balance"]);<br />
</source><br />
<br />
== Node.js ==<br />
<br />
* [https://github.com/freewil/node-bitcoin node-bitcoin] (npm: bitcoin) <br />
<br />
Example using node-bitcoin:<br />
<br />
<source lang="javascript"><br />
var bitcoin = require('bitcoin');<br />
var client = new bitcoin.Client({<br />
host: 'localhost',<br />
port: 8332,<br />
user: 'user',<br />
pass: 'pass'<br />
});<br />
<br />
client.getDifficulty(function(err, difficulty) {<br />
if (err) {<br />
return console.error(err);<br />
}<br />
<br />
console.log('Difficulty: ' + difficulty);<br />
});<br />
</source><br />
<br />
Example using Kapitalize:<br />
<br />
<source lang='javascript'><br />
var client = require('kapitalize')()<br />
<br />
client.auth('user', 'password')<br />
<br />
client<br />
.getInfo()<br />
.getDifficulty(function(err, difficulty) {<br />
console.log('Dificulty: ', difficulty)<br />
})<br />
</source><br />
<br />
== Command line (cURL) ==<br />
<br />
You can also send commands and see results using [http://curl.haxx.se/ cURL] or some other command-line HTTP-fetching utility; for example:<br />
<br />
<source lang="bash"><br />
curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' <br />
-H 'content-type: text/plain;' http://127.0.0.1:8332/<br />
</source><br />
<br />
You will be prompted for your rpcpassword, and then will see something like:<br />
<br />
<source lang="javascript"><br />
{"result":{"balance":0.000000000000000,"blocks":59952,"connections":48,"proxy":"","generate":false,<br />
"genproclimit":-1,"difficulty":16.61907875185736,"error":null,"id":"curltest"}<br />
</source><br />
<br />
== See Also==<br />
<br />
* [[Original_Bitcoin_client/API_Calls_list|API calls list]]<br />
* [[Running Bitcoin]]<br />
* [[Lazy API]]<br />
* [[PHP developer intro]]<br />
* [[Raw_Transactions|Raw Transactions API]]<br />
* [http://blockchain.info/api/json_rpc_api Web Based JSON RPC interface.]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
[[zh-cn:API_reference_(JSON-RPC)]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=API_reference_(JSON-RPC)&diff=40194API reference (JSON-RPC)2013-08-15T05:07:34Z<p>Gavinandresen: Add warning about opening up RPC port</p>
<hr />
<div>== Controlling Bitcoin ==<br />
<br />
Run ''bitcoind'' or ''bitcoin-qt -server''. You can control it via the command-line or by [http://json-rpc.org/wiki/specification HTTP JSON-RPC] commands.<br />
<br />
You must create a bitcoin.conf configuration file setting an rpcuser and rpcpassword; see [[Running Bitcoin]] for details.<br />
<br />
Now run:<br />
$ ./bitcoind -daemon<br />
bitcoin server starting<br />
$ ./bitcoind help<br />
# shows the help text<br />
<br />
A [[Original Bitcoin client/API Calls list|list of RPC calls]] will be shown.<br />
<br />
$ ./bitcoind getbalance<br />
2000.00000<br />
<br />
== JSON-RPC ==<br />
<br />
Running Bitcoin with the -server argument (or running bitcoind) tells it to function as a [http://json-rpc.org/wiki/specification HTTP JSON-RPC] server, but <br />
[http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication] must be used when communicating with it, and, for security, by default, the server only accepts connections from other processes on the same machine. If your HTTP or JSON library requires you to specify which 'realm' is authenticated, use 'jsonrpc'.<br />
<br />
Bitcoin supports SSL (https) JSON-RPC connections beginning with version 0.3.14. See the [[Enabling SSL on original client daemon|rpcssl wiki page]] for setup instructions and a list of all bitcoin.conf configuration options.<br />
<br />
Allowing arbitrary machines to access the JSON-RPC port (using the rpcallowip configuration option) is dangerous and ''strongly discouraged''-- access should be strictly limited to trusted machines.<br />
<br />
To access the server you should find a [http://json-rpc.org/wiki/implementations suitable library] for your language.<br />
<br />
== Proper money handling ==<br />
<br />
See the [[Proper Money Handling (JSON-RPC)|proper money handling page]] for notes on avoiding rounding errors when handling bitcoin values.<br />
<br />
== Python ==<br />
<br />
[http://json-rpc.org/wiki/python-json-rpc python-jsonrpc] is the official JSON-RPC implementation for Python.<br />
It automatically generates Python methods for RPC calls.<br />
However, due to its design for supporting old versions of Python, it is also rather inefficient.<br />
[[User:jgarzik|jgarzik]] has forked it as [https://github.com/jgarzik/python-bitcoinrpc Python-BitcoinRPC] and optimized it for current versions.<br />
Generally, this version is recommended.<br />
<br />
While BitcoinRPC lacks a few obscure features from jsonrpc, software using only the ServiceProxy class can be written the same to work with either version the user might choose to install:<br />
<br />
<source lang="python"><br />
from jsonrpc import ServiceProxy<br />
<br />
access = ServiceProxy("http://user:password@127.0.0.1:8332")<br />
access.getinfo()<br />
access.listreceivedbyaddress(6)<br />
#access.sendtoaddress("11yEmxiMso2RsFVfBcCa616npBvGgxiBX", 10)<br />
</source><br />
<br />
== Ruby ==<br />
<br />
<source lang="ruby"><br />
require 'net/http'<br />
require 'uri'<br />
require 'json'<br />
<br />
class BitcoinRPC<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.basic_auth @uri.user, @uri.password<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
<br />
if $0 == __FILE__<br />
h = BitcoinRPC.new('http://user:password@127.0.0.1:8332')<br />
p h.getbalance<br />
p h.getinfo<br />
p h.getnewaddress<br />
p h.dumpprivkey( h.getnewaddress )<br />
# also see: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list<br />
end<br />
</source><br />
<br />
== PHP ==<br />
<br />
The [http://jsonrpcphp.org/ JSON-RPC PHP] library also makes it very easy to connect to Bitcoin. For example:<br />
<br />
<source lang="php"><br />
require_once 'jsonRPCClient.php';<br />
<br />
$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');<br />
<br />
echo "<pre>\n";<br />
print_r($bitcoin->getinfo()); echo "\n";<br />
echo "Received: ".$bitcoin->getreceivedbylabel("Your Address")."\n";<br />
echo "</pre>";<br />
</source><br />
<br />
== Java ==<br />
<br />
The easiest way to tell Java to use HTTP Basic authentication is to set a default Authenticator:<br />
<br />
<source lang="java"><br />
final String rpcuser ="...";<br />
final String rpcpassword ="...";<br />
<br />
Authenticator.setDefault(new Authenticator() {<br />
protected PasswordAuthentication getPasswordAuthentication() {<br />
return new PasswordAuthentication (rpcuser, rpcpassword.toCharArray());<br />
}<br />
});<br />
</source><br />
<br />
Once that is done, any JSON-RPC library for Java (or ordinary URL POSTs) may be used to communicate with the Bitcoin server.<br />
<br />
== Perl ==<br />
<br />
The JSON::RPC package from CPAN can be used to communicate with Bitcoin. You must set the client's credentials; for example:<br />
<br />
<source lang="perl"><br />
use JSON::RPC::Client;<br />
use Data::Dumper;<br />
<br />
my $client = new JSON::RPC::Client;<br />
<br />
$client->ua->credentials(<br />
'localhost:8332', 'jsonrpc', 'user' => 'password' # REPLACE WITH YOUR bitcoin.conf rpcuser/rpcpassword<br />
);<br />
<br />
my $uri = 'http://localhost:8332/';<br />
my $obj = {<br />
method => 'getinfo',<br />
params => [],<br />
};<br />
<br />
my $res = $client->call( $uri, $obj );<br />
<br />
if ($res){<br />
if ($res->is_error) { print "Error : ", $res->error_message; }<br />
else { print Dumper($res->result); }<br />
} else {<br />
print $client->status_line;<br />
}<br />
</source><br />
<br />
== .NET (C#) ==<br />
The communication with rpc service can be achieved using the standard httprequest/response objects.<br />
A library for serialising and deserialising Json will make your life a lot easier:<br />
<br />
* JayRock for .NET 4.0<br />
* Json.Net for .NET 2.0 and above <br />
<br />
The following example uses Json.Net:<br />
<br />
<source lang="csharp"><br />
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("http://localhost.:8332");<br />
webRequest.Credentials = new NetworkCredential("user", "pwd");<br />
/// important, otherwise the service can't desirialse your request properly<br />
webRequest.ContentType = "application/json-rpc";<br />
webRequest.Method = "POST";<br />
<br />
JObject joe = new JObject();<br />
joe.Add(new JProperty("jsonrpc", "1.0"));<br />
joe.Add(new JProperty("id", "1"));<br />
joe.Add(new JProperty("method", Method));<br />
// params is a collection values which the method requires..<br />
if (Params.Keys.Count == 0)<br />
{<br />
joe.Add(new JProperty("params", new JArray()));<br />
}<br />
else<br />
{<br />
JArray props = new JArray();<br />
// add the props in the reverse order!<br />
for (int i = Params.Keys.Count - 1; i >= 0; i--)<br />
{<br />
.... // add the params<br />
}<br />
joe.Add(new JProperty("params", props));<br />
}<br />
<br />
// serialize json for the request<br />
string s = JsonConvert.SerializeObject(joe);<br />
byte[] byteArray = Encoding.UTF8.GetBytes(s);<br />
webRequest.ContentLength = byteArray.Length;<br />
Stream dataStream = webRequest.GetRequestStream();<br />
dataStream.Write(byteArray, 0, byteArray.Length);<br />
dataStream.Close();<br />
<br />
<br />
WebResponse webResponse = webRequest.GetResponse();<br />
<br />
... // deserialze the response<br />
</source><br />
<br />
There is also a wrapper for Json.NET called Bitnet (https://sourceforge.net/projects/bitnet)<br />
implementing Bitcoin API in more convenient way:<br />
<br />
<source lang="csharp"><br />
BitnetClient bc = new BitnetClient("http://127.0.0.1:8332");<br />
bc.Credentials = new NetworkCredential("user", "pass");<br />
<br />
var p = bc.GetDifficulty();<br />
Console.WriteLine("Difficulty:" + p.ToString());<br />
<br />
var inf = bc.GetInfo();<br />
Console.WriteLine("Balance:" + inf["balance"]);<br />
</source><br />
<br />
== Node.js ==<br />
<br />
* [https://github.com/freewil/node-bitcoin node-bitcoin] (npm: bitcoin) <br />
<br />
Example using node-bitcoin:<br />
<br />
<source lang="javascript"><br />
var bitcoin = require('bitcoin');<br />
var client = new bitcoin.Client({<br />
host: 'localhost',<br />
port: 8332,<br />
user: 'user',<br />
pass: 'pass'<br />
});<br />
<br />
client.getDifficulty(function(err, difficulty) {<br />
if (err) {<br />
return console.error(err);<br />
}<br />
<br />
console.log('Difficulty: ' + difficulty);<br />
});<br />
</source><br />
<br />
Example using Kapitalize:<br />
<br />
<source lang='javascript'><br />
var client = require('kapitalize')()<br />
<br />
client.auth('user', 'password')<br />
<br />
client<br />
.getInfo()<br />
.getDifficulty(function(err, difficulty) {<br />
console.log('Dificulty: ', difficulty)<br />
})<br />
</source><br />
<br />
== Command line (cURL) ==<br />
<br />
You can also send commands and see results using [http://curl.haxx.se/ cURL] or some other command-line HTTP-fetching utility; for example:<br />
<br />
<source lang="bash"><br />
curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' <br />
-H 'content-type: text/plain;' http://127.0.0.1:8332/<br />
</source><br />
<br />
You will be prompted for your rpcpassword, and then will see something like:<br />
<br />
<source lang="javascript"><br />
{"result":{"balance":0.000000000000000,"blocks":59952,"connections":48,"proxy":"","generate":false,<br />
"genproclimit":-1,"difficulty":16.61907875185736,"error":null,"id":"curltest"}<br />
</source><br />
<br />
== See Also==<br />
<br />
* [[Original_Bitcoin_client/API_Calls_list|API calls list]]<br />
* [[Running Bitcoin]]<br />
* [[Lazy API]]<br />
* [[PHP developer intro]]<br />
* [[Raw_Transactions|Raw Transactions API]]<br />
* [http://blockchain.info/api/json_rpc_api Web Based JSON RPC interface.]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
[[zh-cn:API_reference_(JSON-RPC)]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=User:Gavinandresen&diff=40188User:Gavinandresen2013-08-14T23:56:41Z<p>Gavinandresen: Updated....</p>
<hr />
<div>Lead of Bitcoin's [[Core developers|core developers]] and Chief Scientist of the [[Bitcoin Foundation]].<br />
<br />
==See Also==<br />
<br />
* [[Developers]]<br />
<br />
==External Links==<br />
<br />
* [http://gavintech.blogspot.com GavinTech] blog<br />
* [http://twitter.com/#!/gavinandresen @GavinAndresen] Twitter account</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0072&diff=40069BIP 00722013-08-08T00:27:39Z<p>Gavinandresen: Formatting</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 72<br />
Title: bitcoin: uri extensions for Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to<br />
support the payment protocol (BIP 70).<br />
<br />
==Motivation==<br />
<br />
Allow users to click on a link in a web page or email to initiate the<br />
payment protocol, while being backwards-compatible with existing<br />
bitcoin wallets.<br />
<br />
==Specification==<br />
<br />
The bitcoin: URI scheme is extended with an additional, optional<br />
"request" parameter, whose value is a URL from which a PaymentRequest<br />
message should be fetched (unsafe and reserved octets in the URL value<br />
must be encoded as described in RFC 1738).<br />
<br />
If the "request" parameter is provided and backwards compatibility<br />
is not required, then the bitcoin address portion of the URI may be<br />
omitted (the URI will be of the form: bitcoin:?request=... ).<br />
<br />
When Bitcoin wallet software that supports this BIP receives a<br />
bitcoin: URI with a request parameter, it should ignore the bitcoin<br />
address/amount/label/message in the URI and instead fetch a<br />
PaymentRequest message and then follow the payment protocol, as<br />
described in BIP 70.<br />
<br />
Bitcoin wallets must support fetching PaymentRequests via http and<br />
https protocols; they may support other protocols.<br />
<br />
If a PaymentRequest cannot be obtained (perhaps the server is<br />
unavailable), then the customer should be informed that the merchant's<br />
payment processing system is unavailable.<br />
<br />
==Compatibility==<br />
<br />
Wallet software that does not support this BIP will simply ignore the<br />
request parameter and will initiate a payment to bitcoin address.<br />
<br />
==Examples==<br />
A backwards-compatible request:<br />
<pre><br />
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
Non-backwards-compatible equivalent:<br />
<pre><br />
bitcoin:?request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0072&diff=40068BIP 00722013-08-08T00:27:01Z<p>Gavinandresen: If request given, allow bitcoin address to be optional.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 72<br />
Title: bitcoin: uri extensions for Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to<br />
support the payment protocol (BIP 70).<br />
<br />
==Motivation==<br />
<br />
Allow users to click on a link in a web page or email to initiate the<br />
payment protocol, while being backwards-compatible with existing<br />
bitcoin wallets.<br />
<br />
==Specification==<br />
<br />
The bitcoin: URI scheme is extended with an additional, optional<br />
"request" parameter, whose value is a URL from which a PaymentRequest<br />
message should be fetched (unsafe and reserved octets in the URL value<br />
must be encoded as described in RFC 1738).<br />
<br />
If the "request" parameter is provided and backwards compatibility<br />
is not required, then the bitcoin address portion of the URI may be<br />
omitted (the URI will be of the form: bitcoin:?request=... ).<br />
<br />
When Bitcoin wallet software that supports this BIP receives a<br />
bitcoin: URI with a request parameter, it should ignore the bitcoin<br />
address/amount/label/message in the URI and instead fetch a<br />
PaymentRequest message and then follow the payment protocol, as<br />
described in BIP 70.<br />
<br />
Bitcoin wallets must support fetching PaymentRequests via http and<br />
https protocols; they may support other protocols.<br />
<br />
If a PaymentRequest cannot be obtained (perhaps the server is<br />
unavailable), then the customer should be informed that the merchant's<br />
payment processing system is unavailable.<br />
<br />
==Compatibility==<br />
<br />
Wallet software that does not support this BIP will simply ignore the<br />
request parameter and will initiate a payment to bitcoin address.<br />
<br />
==Examples==<br />
A backwards-compatible request:<br />
<pre><br />
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
Non-backwards-compatible equivalent:<br />
bitcoin:?request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0072&diff=40067BIP 00722013-08-08T00:24:10Z<p>Gavinandresen: Allow URIs with no address</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 72<br />
Title: bitcoin: uri extensions for Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to<br />
support the payment protocol (BIP 70).<br />
<br />
==Motivation==<br />
<br />
Allow users to click on a link in a web page or email to initiate the<br />
payment protocol, while being backwards-compatible with existing<br />
bitcoin wallets.<br />
<br />
==Specification==<br />
<br />
The bitcoin: URI scheme is extended with an additional, optional<br />
"request" parameter, whose value is a URL from which a PaymentRequest<br />
message should be fetched (unsafe and reserved octets in the URL value<br />
must be encoded as described in RFC 1738).<br />
<br />
When Bitcoin wallet software that supports this BIP receives a<br />
bitcoin: URI with a request parameter, it should ignore the bitcoin<br />
address/amount/label/message in the URI and instead fetch a<br />
PaymentRequest message and then follow the payment protocol, as<br />
described in BIP 70.<br />
<br />
Bitcoin wallets must support fetching PaymentRequests via http and<br />
https protocols; they may support other protocols.<br />
<br />
If a PaymentRequest cannot be obtained (perhaps the server is<br />
unavailable), then the customer should be informed that the merchant's<br />
payment processing system is unavailable.<br />
<br />
==Compatibility==<br />
<br />
Wallet software that does not support this BIP will simply ignore the<br />
request parameter and will initiate a payment to bitcoin address.<br />
<br />
==Examples==<br />
A backwards-compatible request:<br />
<pre><br />
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
Non-backwards-compatible equivalent:<br />
bitcoin:?request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Running_Bitcoin&diff=39941Running Bitcoin2013-08-01T06:30:49Z<p>Gavinandresen: Add warning on opening up RPC port</p>
<hr />
<div>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).<br />
<br />
__TOC__<br />
<br />
==Linux Quickstart==<br />
<br />
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:<br />
<br />
./bitcoind<br />
<br />
To run with the standard GUI interface:<br />
<br />
./bitcoin-qt<br />
<br />
==Command-line arguments==<br />
<br />
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:<br />
<br />
Options:<br />
-? This help message<br />
-conf=<file> Specify configuration file (default: bitcoin.conf)<br />
-pid=<file> Specify pid file (default: bitcoind.pid)<br />
-gen Generate coins (default: 0)<br />
-datadir=<dir> Specify data directory<br />
-dbcache=<n> Set database cache size in megabytes (default: 25)<br />
-timeout=<n> Specify connection timeout in milliseconds (default: 5000)<br />
-proxy=<ip:port> Connect through socks proxy<br />
-socks=<n> Select the version of socks proxy to use (4-5, default: 5)<br />
-tor=<ip:port> Use proxy to reach tor hidden services (default: same as -proxy)<br />
-dns Allow DNS lookups for -addnode, -seednode and -connect<br />
-port=<port> Listen for connections on <port> (default: 8333 or testnet: 18333)<br />
-maxconnections=<n> Maintain at most <n> connections to peers (default: 125)<br />
-addnode=<ip> Add a node to connect to and attempt to keep the connection open<br />
-connect=<ip> Connect only to the specified node(s)<br />
-seednode=<ip> Connect to a node to retrieve peer addresses, and disconnect<br />
-externalip=<ip> Specify your own public address<br />
-onlynet=<net> Only connect to nodes in network <net> (IPv4, IPv6 or Tor)<br />
-discover Discover own IP address (default: 1 when listening and no -externalip)<br />
-checkpoints Only accept block chain matching built-in checkpoints (default: 1)<br />
-listen Accept connections from outside (default: 1 if no -proxy or -connect)<br />
-bind=<addr> Bind to given address and always listen on it. Use [host]:port notation for IPv6<br />
-dnsseed Find peers using DNS lookup (default: 1 unless -connect)<br />
-banscore=<n> Threshold for disconnecting misbehaving peers (default: 100)<br />
-bantime=<n> Number of seconds to keep misbehaving peers from reconnecting (default: 86400)<br />
-maxreceivebuffer=<n> Maximum per-connection receive buffer, <n>*1000 bytes (default: 5000)<br />
-maxsendbuffer=<n> Maximum per-connection send buffer, <n>*1000 bytes (default: 1000)<br />
-upnp Use UPnP to map the listening port (default: 1 when listening)<br />
-paytxfee=<amt> Fee per KB to add to transactions you send<br />
-server Accept command line and JSON-RPC commands<br />
-testnet Use the test network<br />
-debug Output extra debugging information. Implies all other -debug* options<br />
-debugnet Output extra network debugging information<br />
-logtimestamps Prepend debug output with timestamp<br />
-shrinkdebugfile Shrink debug.log file on client startup (default: 1 when no -debug)<br />
-printtoconsole Send trace/debug info to console instead of debug.log file<br />
-printtodebugger Send trace/debug info to debugger<br />
-rpcuser=<user> Username for JSON-RPC connections<br />
-rpcpassword=<pw> Password for JSON-RPC connections<br />
-rpcport=<port> Listen for JSON-RPC connections on <port> (default: 8332 or testnet: 18332)<br />
-rpcallowip=<ip> Allow JSON-RPC connections from specified IP address<br />
-rpcthreads=<n> Set the number of threads to service RPC calls (default: 4)<br />
-blocknotify=<cmd> Execute command when the best block changes (%s in cmd is replaced by block hash)<br />
-walletnotify=<cmd> Execute command when a wallet transaction changes (%s in cmd is replaced by TxID)<br />
-alertnotify=<cmd> Execute command when a relevant alert is received (%s in cmd is replaced by message)<br />
-upgradewallet Upgrade wallet to latest format<br />
-keypool=<n> Set key pool size to <n> (default: 100)<br />
-rescan Rescan the block chain for missing wallet transactions<br />
-salvagewallet Attempt to recover private keys from a corrupt wallet.dat<br />
-checkblocks=<n> How many blocks to check at startup (default: 288, 0 = all)<br />
-checklevel=<n> How thorough the block verification is (0-4, default: 3)<br />
-txindex Maintain a full transaction index (default: 0)<br />
-loadblock=<file> Imports blocks from external blk000??.dat file<br />
-reindex Rebuild block chain index from current blk000??.dat files<br />
-par=<n> Set the number of script verification threads (up to 16, 0 = auto, <0 = leave that many cores free, default: 0)<br />
<br />
Block creation options:<br />
-blockminsize=<n> Set minimum block size in bytes (default: 0)<br />
-blockmaxsize=<n> Set maximum block size in bytes (default: 250000)<br />
-blockprioritysize=<n> Set maximum size of high-priority/low-fee transactions in bytes (default: 27000)<br />
<br />
SSL options: (see the Bitcoin Wiki for SSL setup instructions)<br />
-rpcssl Use OpenSSL (https) for JSON-RPC connections<br />
-rpcsslcertificatechainfile=<file.cert> Server certificate file (default: server.cert)<br />
-rpcsslprivatekeyfile=<file.pem> Server private key (default: server.pem)<br />
-rpcsslciphers=<ciphers> Acceptable ciphers (default: TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH)<br />
<br />
UI options:<br />
-lang=<lang> Set language, for example "de_DE" (default: system locale)<br />
-min Start minimized<br />
-splash Show splash screen on startup (default: 1)<br />
<br />
Many of the boolean options can also be set to off by specifying them with a "no" prefix: e.g. -nodnseed.<br />
<br />
==Bitcoin.conf Configuration File==<br />
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.<br />
<br />
The configuration file is a list of setting=value pairs, one per line, with optional comments starting with the '#' character.<br />
<br />
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.<br />
{|<br />
! Operating System<br />
! Default bitcoin datadir<br />
! Typical path to configuration file<br />
|-<br />
| Windows<br />
| %APPDATA%\Bitcoin\<br />
| (XP) C:\Documents and Settings\username\Application Data\Bitcoin\bitcoin.conf<br />
(Vista, 7) C:\Users\username\AppData\Roaming\Bitcoin\bitcoin.conf<br />
|-<br />
| Linux<br />
| $HOME/.bitcoin/<br />
| /home/username/.bitcoin/bitcoin.conf<br />
|-<br />
| Mac OSX<br />
| $HOME/Library/Application Support/Bitcoin/<br />
| /Users/username/Library/Application Support/Bitcoin/bitcoin.conf<br />
|}<br />
<br />
Note: if running Bitcoin in testnet mode, the sub-folder "testnet" will be appended to the data directory automatically.<br />
<br />
==Sample Bitcoin.conf==<br />
Here is a sample bitcoin.conf file.<br />
<br />
# bitcoin.conf configuration file. Lines beginning with # are comments.<br />
<br />
<br />
# Network-related settings:<br />
<br />
# Run on the test network instead of the real bitcoin network.<br />
#testnet=0<br />
<br />
# Connect via a socks4 proxy<br />
#proxy=127.0.0.1:9050<br />
<br />
##############################################################<br />
## Quick Primer on addnode vs connect ##<br />
## Let's say for instance you use addnode=4.2.2.4 ##<br />
## addnode will connect you to and tell you about the ##<br />
## nodes connected to 4.2.2.4. In addition it will tell ##<br />
## the other nodes connected to it that you exist so ##<br />
## they can connect to you. ##<br />
## connect will not do the above when you 'connect' to it. ##<br />
## It will *only* connect you to 4.2.2.4 and no one else.##<br />
## ##<br />
## So if you're behind a firewall, or have other problems ##<br />
## finding nodes, add some using 'addnode'. ##<br />
## ##<br />
## If you want to stay private, use 'connect' to only ##<br />
## connect to "trusted" nodes. ##<br />
## ##<br />
## If you run multiple nodes on a LAN, there's no need for ##<br />
## all of them to open lots of connections. Instead ##<br />
## 'connect' them all to one node that is port forwarded ##<br />
## and has lots of connections. ##<br />
## Thanks goes to [Noodle] on Freenode. ##<br />
##############################################################<br />
<br />
# Use as many addnode= settings as you like to connect to specific peers<br />
#addnode=69.164.218.197<br />
#addnode=10.0.0.2:8333<br />
<br />
# ... or use as many connect= settings as you like to connect ONLY<br />
# to specific peers:<br />
#connect=69.164.218.197<br />
#connect=10.0.0.1:8333<br />
<br />
<br />
# Maximum number of inbound+outbound connections.<br />
#maxconnections=<br />
<br />
<br />
# JSON-RPC options (for controlling a running Bitcoin/bitcoind process)<br />
<br />
# server=1 tells Bitcoin-QT to accept JSON-RPC commands.<br />
#server=0<br />
<br />
# You must set rpcuser and rpcpassword to secure the JSON-RPC api<br />
#rpcuser=Ulysseys<br />
#rpcpassword=YourSuperGreatPasswordNumber_DO_NOT_USE_THIS_OR_YOU_WILL_GET_ROBBED_385593<br />
<br />
# How many seconds bitcoin will wait for a complete RPC HTTP request.<br />
# after the HTTP connection is established. <br />
#rpctimeout=30<br />
<br />
# By default, only RPC connections from localhost are allowed. Specify<br />
# as many rpcallowip= settings as you like to allow connections from<br />
# other hosts (and you may use * as a wildcard character).<br />
# NOTE: opening up the RPC port to hosts outside your local<br />
# trusted network is NOT RECOMMENDED, because the rpcpassword<br />
# is transmitted over the network unencrypted.<br />
#rpcallowip=10.1.1.34<br />
#rpcallowip=192.168.1.*<br />
<br />
# Listen for RPC connections on this TCP port:<br />
#rpcport=8332<br />
<br />
# You can use Bitcoin or bitcoind to send commands to Bitcoin/bitcoind<br />
# running on another host using this option:<br />
#rpcconnect=127.0.0.1<br />
<br />
# Use Secure Sockets Layer (also known as TLS or HTTPS) to communicate<br />
# with Bitcoin -server or bitcoind<br />
#rpcssl=1<br />
<br />
# OpenSSL settings used when rpcssl=1<br />
#rpcsslciphers=TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH<br />
#rpcsslcertificatechainfile=server.cert<br />
#rpcsslprivatekeyfile=server.pem<br />
<br />
<br />
# Miscellaneous options<br />
<br />
# Set gen=1 to attempt to generate bitcoins<br />
#gen=0<br />
<br />
# Pre-generate this many public/private key pairs, so wallet backups will be valid for<br />
# both prior transactions and several dozen future transactions.<br />
#keypool=100<br />
<br />
# Pay an optional transaction fee every time you send bitcoins. Transactions with fees<br />
# are more likely than free transactions to be included in generated blocks, so may<br />
# be validated sooner.<br />
#paytxfee=0.00<br />
<br />
# Allow direct connections for the 'pay via IP address' feature.<br />
#allowreceivebyip=1<br />
<br />
# User interface options<br />
<br />
# Start Bitcoin minimized<br />
#min=1<br />
<br />
# Minimize to the system tray<br />
#minimizetotray=1<br />
<br />
==Platforms==<br />
===Windows===<br />
<br />
====Start automatically====<br />
To configure the Bitcoin client to start automatically:<br />
<br />
You might use the configuration-file, or the GUI-Settings:<br />
<br />
Settings -> Options<br />
<br />
then mark the checkbox titled:<br />
[X] Start Bitcoin on system startup<br />
<br />
[[{{ns:file}}:Client_Settings_Options_windows.png]]<br />
<br />
====Batch automation====<br />
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.<br />
<br />
===Mac===<br />
[[{{ns:file}}:MacBitcoinStartOnLogin.png]]<br />
<br />
===Linux===<br />
[[{{ns:file}}:Client_Settings_Options.png]]<br />
<br />
==See Also==<br />
<br />
* [[Data directory]]<br />
<br />
[[es:Ejecución de Bitcoin]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39927BIP 00702013-07-31T11:17:43Z<p>Gavinandresen: /* PaymentACK */</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url should be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| payment || Copy of the Payment message that triggered this PaymentACK. Clients may ignore this if they implement another way of associating Payments with PaymentACKs.<br />
|-<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest must be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one, up to a trusted root<br />
authority. The recipient must verify the certificate chain according to<br />
[RFC5280] and reject the PaymentRequest if any validation failure<br />
occurs.<br />
<br />
Trusted root certificates may be obtained from the operating system;<br />
if validation is done on a device without an operating system, the<br />
[http://www.mozilla.org/projects/security/certs/included/index.html Mozilla root store] is recommended.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39926BIP 00702013-07-31T11:10:38Z<p>Gavinandresen: Added explict text about root certificates</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url should be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| payment || Copy of the Payment message that triggered this PaymentACK. Clients may ignore this if they implement another way of associating Payments with PaymentACKs.<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest must be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one, up to a trusted root<br />
authority. The recipient must verify the certificate chain according to<br />
[RFC5280] and reject the PaymentRequest if any validation failure<br />
occurs.<br />
<br />
Trusted root certificates may be obtained from the operating system;<br />
if validation is done on a device without an operating system, the<br />
[http://www.mozilla.org/projects/security/certs/included/index.html Mozilla root store] is recommended.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39925BIP 00702013-07-31T11:04:54Z<p>Gavinandresen: Add description of payment field.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url should be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| payment || Copy of the Payment message that triggered this PaymentACK. Clients may ignore this if they implement another way of associating Payments with PaymentACKs.<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39924BIP 00702013-07-31T10:59:05Z<p>Gavinandresen: Suggest authenticating Payment.merchant_data, and payment_url "should" be MITM secure</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url should be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39923BIP 00702013-07-31T10:49:51Z<p>Gavinandresen: Added hardware wallets communicating with compromised hosts as motivation</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39922BIP 00702013-07-31T10:42:23Z<p>Gavinandresen: Correction: PaymentRequests > 50k rejected by client, not server...</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the wallet application, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39908BIP 00702013-07-31T06:11:26Z<p>Gavinandresen: /* References */</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
[[BIP 0071]] : Payment Protocol mime types<br />
<br />
[[BIP 0072]] : Payment Protocol bitcoin: URI extensions<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0072&diff=39902BIP 00722013-07-31T02:06:13Z<p>Gavinandresen: Initial spec</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 72<br />
Title: bitcoin: uri extensions for Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to<br />
support the payment protocol (BIP 70).<br />
<br />
==Motivation==<br />
<br />
Allow users to click on a link in a web page or email to initiate the<br />
payment protocol, while being backwards-compatible with existing<br />
bitcoin wallets.<br />
<br />
==Specification==<br />
<br />
The bitcoin: URI scheme is extended with an additional, optional<br />
"request" parameter, whose value is a URL from which a PaymentRequest<br />
message should be fetched (unsafe and reserved octets in the URL value<br />
must be encoded as described in RFC 1738).<br />
<br />
When Bitcoin wallet software that supports this BIP receives a<br />
bitcoin: URI with a request parameter, it should ignore the bitcoin<br />
address/amount/label/message in the URI and instead fetch a<br />
PaymentRequest message and then follow the payment protocol, as<br />
described in BIP 70.<br />
<br />
Bitcoin wallets must support fetching PaymentRequests via http and<br />
https protocols; they may support other protocols.<br />
<br />
If a PaymentRequest cannot be obtained (perhaps the server is<br />
unavailable), then the customer should be informed that the merchant's<br />
payment processing system is unavailable.<br />
<br />
==Compatibility==<br />
<br />
Wallet software that does not support this BIP will simply ignore the<br />
request parameter and will initiate a payment to bitcoin address.<br />
<br />
==Example==<br />
<br />
<pre><br />
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&request=https%3A%2F%2Fmerchant.com%2Fpay.php%3Fh%3D2a8628fc2fbe<br />
</pre><br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0071&diff=39901BIP 00712013-07-31T02:04:57Z<p>Gavinandresen: /* Example */</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 71<br />
Title: Payment Protocol MIME types<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment<br />
request messages.<br />
<br />
==Motivation==<br />
<br />
Wallet or server software that sends payment protocol messages over<br />
email or http should follow Internet standards for properly<br />
encapsulating the messages.<br />
<br />
==Specification==<br />
<br />
The Media Type (Content-Type in HTML/email headers) for bitcoin<br />
protocol messages shall be:<br />
<br />
{|<br />
| Message || Type/Subtype<br />
|-<br />
| PaymentRequest || application/bitcoin-paymentrequest<br />
|-<br />
| Payment || application/bitcoin-payment<br />
|-<br />
| PaymentRequestACK || application/bitcoin-paymentrequestack<br />
|}<br />
<br />
Payment protocol messages are encoded in binary.<br />
<br />
==Example==<br />
<br />
A web server generating a PaymentRequest message to initiate the<br />
payment protocol would precede the binary message data with the<br />
following headers:<br />
<pre><br />
Content-Type: application/bitcoin-paymentrequest<br />
Content-Transfer-Encoding: binary<br />
</pre><br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0071&diff=39900BIP 00712013-07-31T02:04:07Z<p>Gavinandresen: </p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 71<br />
Title: Payment Protocol MIME types<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment<br />
request messages.<br />
<br />
==Motivation==<br />
<br />
Wallet or server software that sends payment protocol messages over<br />
email or http should follow Internet standards for properly<br />
encapsulating the messages.<br />
<br />
==Specification==<br />
<br />
The Media Type (Content-Type in HTML/email headers) for bitcoin<br />
protocol messages shall be:<br />
<br />
{|<br />
| Message || Type/Subtype<br />
|-<br />
| PaymentRequest || application/bitcoin-paymentrequest<br />
|-<br />
| Payment || application/bitcoin-payment<br />
|-<br />
| PaymentRequestACK || application/bitcoin-paymentrequestack<br />
|}<br />
<br />
Payment protocol messages are encoded in binary.<br />
<br />
==Example==<br />
<br />
A web server generating a PaymentRequest message to initiate the<br />
payment protocol would precede the binary message data with the<br />
following headers:<br />
<pre><br />
Content-Type: application/bitcoin-paymentrequest<br />
Content-Transfer-Encoding: binary<br />
Content-Length: number_of_bytes<br />
</pre><br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0071&diff=39899BIP 00712013-07-31T02:03:47Z<p>Gavinandresen: Initial spec</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: ??<br />
Title: Payment Protocol MIME types<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment<br />
request messages.<br />
<br />
==Motivation==<br />
<br />
Wallet or server software that sends payment protocol messages over<br />
email or http should follow Internet standards for properly<br />
encapsulating the messages.<br />
<br />
==Specification==<br />
<br />
The Media Type (Content-Type in HTML/email headers) for bitcoin<br />
protocol messages shall be:<br />
<br />
{|<br />
| Message || Type/Subtype<br />
|-<br />
| PaymentRequest || application/bitcoin-paymentrequest<br />
|-<br />
| Payment || application/bitcoin-payment<br />
|-<br />
| PaymentRequestACK || application/bitcoin-paymentrequestack<br />
|}<br />
<br />
Payment protocol messages are encoded in binary.<br />
<br />
==Example==<br />
<br />
A web server generating a PaymentRequest message to initiate the<br />
payment protocol would precede the binary message data with the<br />
following headers:<br />
<pre><br />
Content-Type: application/bitcoin-paymentrequest<br />
Content-Transfer-Encoding: binary<br />
Content-Length: number_of_bytes<br />
</pre><br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39898BIP 00702013-07-31T02:02:27Z<p>Gavinandresen: /* Output */</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where a refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
BIP 71 : Payment Protocol bitcoin: URI extensions<br />
<br />
BIP 72 : Payment Protocol mime types<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Payment_Request&diff=39897Payment Request2013-07-31T02:01:36Z<p>Gavinandresen: Link to BIP 70</p>
<hr />
<div>= Payment Requests =<br />
<br />
Payment Requests are a proposed new way to make Bitcoin payments.<br />
<br />
Instead of sending somebody a bitcoin address and asking them to pay to that address, you give them a PaymentRequest message which bundles up more information than is contained in just a bitcoin address. A SignedPaymentRequest bundles a PaymentRequest with a digital identity and signature, so you can be sure that you are paying the correct person or merchant.<br />
<br />
== Specification ==<br />
<br />
See https://en.bitcoin.it/wiki/BIP_0070 for the current specification.<br />
<br />
== Extensions ==<br />
<br />
To avoid conflicts, implementations should use this page to register extensions to the protocol.<br />
<br />
=== PaymentRequest ===<br />
{| class="wikitable"<br />
|-<br />
! Field Number !! Name !! Description<br />
|-<br />
| 100 || (available) || (available)<br />
|-<br />
|}<br />
<br />
=== SignedPaymentRequest ===<br />
{| class="wikitable"<br />
|-<br />
! Field Number !! Name !! Description<br />
|-<br />
| 100 || (available) || (available)<br />
|-<br />
|}<br />
<br />
=== Payment ===<br />
{| class="wikitable"<br />
|-<br />
! Field Number !! Name !! Description<br />
|-<br />
| 100 || (available) || (available)<br />
|-<br />
|}<br />
<br />
=== PaymentACK ===<br />
{| class="wikitable"<br />
|-<br />
! Field Number !! Name !! Description<br />
|-<br />
| 100 || (available) || (available)<br />
|-<br />
|}<br />
<br />
[[Category:Technical]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39896BIP 00702013-07-31T02:00:22Z<p>Gavinandresen: /* PaymentDetails/PaymentRequest */</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
BIP 71 : Payment Protocol bitcoin: URI extensions<br />
<br />
BIP 72 : Payment Protocol mime types<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39895BIP 00702013-07-31T01:59:24Z<p>Gavinandresen: Formatting....</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request<br />
must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
BIP 71 : Payment Protocol bitcoin: URI extensions<br />
<br />
BIP 72 : Payment Protocol mime types<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39894BIP 00702013-07-31T01:55:45Z<p>Gavinandresen: /* Motivation */</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally<br />
be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG).<br />
This is optional to enable future extensions to this protocol that derive<br />
Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin<br />
network, or "test" for payments on test network. If a client receives<br />
a PaymentRequest for a network it does not support it must reject the<br />
request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the<br />
sum of outputs.amount is zero, the customer will be asked how much to<br />
pay, and the bitcoin client may choose any or all of the Outputs (if<br />
there are more than one) for payment. If the sum of outputs.amount is<br />
non-zero, then the customer will be asked to pay the sum, and the<br />
payment shall be split among the Outputs with non-zero amounts (if<br />
there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the<br />
PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be<br />
considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be<br />
displayed to the customer, explaining what this PaymentRequest is<br />
for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment<br />
message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to<br />
identify the PaymentRequest. May be omitted if the merchant does not<br />
need to associate Payments with PaymentRequest or if they associate<br />
each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to<br />
identify the merchant. All implementation should support "none",<br />
"x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be<br />
used to create a digital signature. In the case of X.509 certificates,<br />
pki_data one or more X.509 certificates (see Certificates section<br />
below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized<br />
PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer<br />
serialized variation of the PaymentRequest message, where signature is<br />
a zero-byte array and fields are serialized in numerical order (all<br />
current protocol buffer implementations serialize fields in numerical<br />
order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must<br />
authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request<br />
must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants<br />
may use invoice numbers or any other data they require to match<br />
Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that<br />
fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return<br />
funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the<br />
merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer<br />
giving the status of the transaction (e.g. "Payment of 1 BTC for<br />
eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
BIP 71 : Payment Protocol bitcoin: URI extensions<br />
<br />
BIP 72 : Payment Protocol mime types<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39893BIP 00702013-07-31T01:55:14Z<p>Gavinandresen: Fix formatting</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character<br />
bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding<br />
overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally<br />
be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG).<br />
This is optional to enable future extensions to this protocol that derive<br />
Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin<br />
network, or "test" for payments on test network. If a client receives<br />
a PaymentRequest for a network it does not support it must reject the<br />
request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the<br />
sum of outputs.amount is zero, the customer will be asked how much to<br />
pay, and the bitcoin client may choose any or all of the Outputs (if<br />
there are more than one) for payment. If the sum of outputs.amount is<br />
non-zero, then the customer will be asked to pay the sum, and the<br />
payment shall be split among the Outputs with non-zero amounts (if<br />
there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the<br />
PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be<br />
considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be<br />
displayed to the customer, explaining what this PaymentRequest is<br />
for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment<br />
message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to<br />
identify the PaymentRequest. May be omitted if the merchant does not<br />
need to associate Payments with PaymentRequest or if they associate<br />
each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to<br />
identify the merchant. All implementation should support "none",<br />
"x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be<br />
used to create a digital signature. In the case of X.509 certificates,<br />
pki_data one or more X.509 certificates (see Certificates section<br />
below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized<br />
PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer<br />
serialized variation of the PaymentRequest message, where signature is<br />
a zero-byte array and fields are serialized in numerical order (all<br />
current protocol buffer implementations serialize fields in numerical<br />
order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must<br />
authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before PaymentDetails.expires. If it is not, then the payment request<br />
must be rejected.<br />
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants<br />
may use invoice numbers or any other data they require to match<br />
Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that<br />
fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return<br />
funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the<br />
merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer<br />
giving the status of the transaction (e.g. "Payment of 1 BTC for<br />
eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
BIP 71 : Payment Protocol bitcoin: URI extensions<br />
<br />
BIP 72 : Payment Protocol mime types<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=File:Protocol_Sequence.png&diff=39892File:Protocol Sequence.png2013-07-31T01:52:28Z<p>Gavinandresen: Message communication diagram for payment protocol</p>
<hr />
<div>== Summary ==<br />
Message communication diagram for payment protocol<br />
== Licensing ==<br />
{{self|Cc-zero}}</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=BIP_0070&diff=39891BIP 00702013-07-31T01:51:20Z<p>Gavinandresen: Payment Protocol</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 70<br />
Title: Payment Protocol<br />
Author: Gavin Andresen <gavinandresen@gmail.com><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 29-07-2013<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP describes a protocol for communication between a merchant and their customer, enabling<br />
both a better customer experience and better security against man-in-the-middle attacks on<br />
the payment process.<br />
<br />
==Motivation==<br />
<br />
The current, minimal Bitcoin payment protocol operates as follows:<br />
<br />
# Customer adds items to an online shopping basket, and decides to pay<br />
using Bitcoin.<br />
# Merchant generates a unique payment address, associates it with the<br />
customer's order, and asks the customer to pay.<br />
# Customer copies the Bitcoin address from the merchant's web page and pastes<br />
it into whatever wallet they are using OR follows a bitcoin: link and<br />
their wallet is launched with the amount to be paid.<br />
# Customer authorizes payment to the merchant's address and broadcasts the<br />
transaction through the Bitcoin p2p network.<br />
# Merchant's server detects payment and after sufficient transaction<br />
confirmations considers the transaction final.<br />
<br />
This BIP extends the above protocol to support several new features:<br />
<br />
# Human-readable, secure payment destinations-- customers will be asked to<br />
authorize payment to "website.com" instead of an inscrutable, 34-character<br />
bitcoin address.<br />
# Secure proof of payment, which the customer can use in case of a<br />
dispute with the merchant.<br />
# Payment received messages, so the customer knows immediately that the<br />
merchant has received, and has processed (or is processing) their payment.<br />
# Refund addresses, automatically given to the merchant by the customer's wallet<br />
software, so merchants do not have to contact customers before refunding<br />
overpayments or orders that cannot be fulfilled for some reason.<br />
<br />
==Protocol==<br />
<br />
This BIP describes payment protocol messages encoded using Google's Protocol<br />
Buffers, authenticated using X.509 certificates, and communicated over<br />
http/https. Future BIPs might extend this payment protocol to other<br />
encodings, PKI systems, or transport protocols.<br />
<br />
The payment protocol consists of three messages; PaymentRequest, Payment,<br />
and PaymentACK, and begins with the customer somehow indicating that<br />
they are ready to pay and the merchant's server responding with a<br />
PaymentRequest message:<br />
<br />
[[Image:Protocol_Sequence.png]]<br />
<br />
==Messages==<br />
<br />
===Output===<br />
<br />
Outputs are used in PaymentRequest messages to specify where a payment (or<br />
part of a payment) should be sent. They are also used in Payment messages<br />
to specify where refund should be sent.<br />
<pre><br />
message Output {<br />
optional uint64 amount = 1 [default = 0];<br />
optional bytes script = 2;<br />
}<br />
</pre><br />
{|<br />
| amount || Number of satoshis (0.00000001 BTC) to be paid<br />
|-<br />
| script || a "TxOut" script where payment should be sent. This will normally<br />
be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG).<br />
This is optional to enable future extensions to this protocol that derive<br />
Outputs from a master public key and the PaymentRequest data itself.<br />
|}<br />
<br />
===PaymentDetails/PaymentRequest===<br />
<br />
Payment requests are split into two messages to support future extensibility.<br />
The bulk of the information is contained in the PaymentDetails message. It is<br />
wrapped inside a PaymentRequest message, which contains meta-information<br />
about the merchant and a digital signature.<br />
<pre><br />
message PaymentDetails {<br />
optional string network = 1 [default = "main"];<br />
repeated Output outputs = 2;<br />
required uint64 time = 3;<br />
optional uint64 expires = 4;<br />
optional string memo = 5;<br />
optional string payment_url = 6;<br />
optional bytes merchant_data = 7;<br />
} <br />
</pre><br />
{|<br />
| network || either "main" for payments on the production Bitcoin<br />
network, or "test" for payments on test network. If a client receives<br />
a PaymentRequest for a network it does not support it must reject the<br />
request.<br />
|-<br />
| outputs|| one or more outputs where Bitcoins are to be sent. If the<br />
sum of outputs.amount is zero, the customer will be asked how much to<br />
pay, and the bitcoin client may choose any or all of the Outputs (if<br />
there are more than one) for payment. If the sum of outputs.amount is<br />
non-zero, then the customer will be asked to pay the sum, and the<br />
payment shall be split among the Outputs with non-zero amounts (if<br />
there are more than one; Outputs with zero amounts shall be ignored).<br />
|-<br />
| time|| Unix timestamp (seconds since 1-Jan-1970) when the<br />
PaymentRequest was created.<br />
|-<br />
| expires|| Unix timestamp after which the PaymentRequest should be<br />
considered invalid.<br />
|-<br />
| memo|| UTF-8 encoded, plain-text (no formatting) note that should be<br />
displayed to the customer, explaining what this PaymentRequest is<br />
for.<br />
|-<br />
| payment_url|| Secure (usually https) location where a Payment<br />
message (see below) may be sent to obtain a PaymentACK.<br />
|-<br />
| merchant_data || Arbitrary data that may be used by the merchant to<br />
identify the PaymentRequest. May be omitted if the merchant does not<br />
need to associate Payments with PaymentRequest or if they associate<br />
each PaymentRequest with a separate payment address.<br />
|}<br />
<br />
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:<br />
<pre><br />
message PaymentRequest {<br />
optional uint32 payment_details_version = 1 [default = 1];<br />
optional string pki_type = 2 [default = "none"];<br />
optional bytes pki_data = 3;<br />
required bytes serialized_payment_details = 4;<br />
optional bytes signature = 5;<br />
}<br />
</pre><br />
{|<br />
| payment_details_version || See below for a discussion of versioning/upgrading. <br />
|-<br />
| pki_type || public-key infrastructure (PKI) system being used to<br />
identify the merchant. All implementation should support "none",<br />
"x509+sha256" and "x509+sha1".<br />
|-<br />
| pki_data || PKI-system data that identifies the merchant and can be<br />
used to create a digital signature. In the case of X.509 certificates,<br />
pki_data one or more X.509 certificates (see Certificates section<br />
below).<br />
|-<br />
| serialized_payment_details || A protocol-buffer serialized<br />
PaymentDetails message.<br />
|-<br />
| signature || digital signature over a hash of the protocol buffer<br />
serialized variation of the PaymentRequest message, where signature is<br />
a zero-byte array and fields are serialized in numerical order (all<br />
current protocol buffer implementations serialize fields in numerical<br />
order), using the public key in pki_data.<br />
|}<br />
When a Bitcoin wallet application receives a PaymentRequest, it must<br />
authorize payment by doing the following:<br />
<br />
# Validate the merchant's identity and signature using the PKI<br />
system, if the pki_type is not "none".<br />
# Validate that the time on the customer's system is before<br />
PaymentDetails.expires. If it is not, then the payment request<br />
must be rejected.<br />
# Display the merchant's identity and ask the customer if they would<br />
like to submit payment (e.g. display the "Common Name" in the first<br />
X.509 certificate).<br />
<br />
PaymentRequest messages larger than 50,000 bytes should be rejected by<br />
the merchant's server, to mitigate denial-of-service attacks.<br />
<br />
===Payment===<br />
<br />
Payment messages are sent after the customer has authorized payment:<br />
<pre><br />
message Payment {<br />
optional bytes merchant_data = 1;<br />
repeated bytes transactions = 2;<br />
repeated Output refund_to = 3;<br />
optional string memo = 4;<br />
}<br />
</pre><br />
{|<br />
| merchant_data || copied from PaymentDetails.merchant_data. Merchants<br />
may use invoice numbers or any other data they require to match<br />
Payments to PaymentRequests.<br />
|-<br />
| transactions || One or more valid, signed Bitcoin transactions that<br />
fully pay the PaymentRequest<br />
|-<br />
| refund_to || One or more outputs where the merchant may return<br />
funds, if necessary.<br />
|-<br />
| memo || UTF-8 encoded, plain-text note from the customer to the<br />
merchant.<br />
|}<br />
If the customer authorizes payment, then the Bitcoin client:<br />
<br />
# Creates and signs one or more transactions that satisfy (pay in<br />
full) PaymentDetails.outputs<br />
# Broadcast the transactions on the Bitcoin p2p network.<br />
# If PaymentDetails.payment_url is specified, POST a Payment message<br />
to that URL. The Payment message is serialized and sent as the body<br />
of the POST request.<br />
<br />
Errors communicating with the payment_url server should be communicated to the user.<br />
<br />
PaymentDetails.payment_url must be secure against man-in-the-middle<br />
attacks that might alter Payment.refund_to (if using HTTP, it must be<br />
TLS-protected).<br />
<br />
When the merchant's server receives the Payment message, it must<br />
determine whether or not the transactions satisfy conditions of<br />
payment. If and only if they do, if should broadcast the<br />
transaction(s) on the Bitcoin p2p network.<br />
<br />
===PaymentACK===<br />
<br />
PaymentACK is the final message in the payment protocol; it is sent<br />
from the merchant's server to the bitcoin wallet in response to a<br />
Payment message:<br />
<pre><br />
message PaymentACK {<br />
required Payment payment = 1;<br />
optional string memo = 2;<br />
}<br />
</pre><br />
{|<br />
| memo || UTF-8 encoded note that should be displayed to the customer<br />
giving the status of the transaction (e.g. "Payment of 1 BTC for<br />
eleven tribbles accepted for processing.")<br />
|}<br />
<br />
==Localization==<br />
<br />
Merchants that support multiple languages should generate<br />
language-specific PaymentRequests, and either associate the language<br />
with the request or embed a language tag in the request's<br />
merchant_data. They should also generate a language-specific<br />
PaymentACK based on the original request.<br />
<br />
For example: A greek-speaking customer browsing the Greek version of a<br />
merchant's website clicks on a "Αγορά τώρα" link, which generates a<br />
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The<br />
customer pays, their bitcoin client sends a Payment message, and the<br />
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".<br />
<br />
==Certificates==<br />
<br />
The default PKI system is X.509 certificates (the same system used to<br />
authenticate web servers). The format of pki_data when pki_type is<br />
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate<br />
chain:<br />
<pre><br />
message X509Certificates {<br />
repeated bytes certificate = 1;<br />
}<br />
</pre><br />
If pki_type is "x509+sha256", then the Payment message is hashed using<br />
the SHA256 algorithm to produce the message digest that is<br />
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is<br />
used.<br />
<br />
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The<br />
certificate containing the public key of the entity that digitally<br />
signed the PaymentRequest MUST be the first certificate. This MAY be<br />
followed by additional certificates, with each subsequent certificate<br />
being the one used to certify the previous one. The recipient MUST<br />
verify the certificate chain according to [RFC5280] and reject the<br />
PaymentRequest if any validation failure occurs.<br />
<br />
==Extensibility==<br />
<br />
The protocol buffers serialization format is designed to be<br />
extensible. In particular, new, optional fields can be added to a<br />
message and will be ignored (but saved/re-transmitted) by old<br />
implementations.<br />
<br />
PaymentDetails messages may be extended with new optional fields and<br />
still be considered "version 1." Old implementations will be able to<br />
validate signatures against PaymentRequests containing the new fields,<br />
but (obviously) will not be able to display whatever information is<br />
contained in the new, optional fields to the user.<br />
<br />
If it becomes necessary at some point in the future for merchants to<br />
produce PaymentRequest messages that are accepted *only* by new<br />
implementations, they can do so by defining a new PaymentDetails<br />
message with version=2. Old implementations should let the user know<br />
that they need to upgrade their software when they get an up-version<br />
PaymentDetails message.<br />
<br />
Implementations that need to extend messages in this specification<br />
shall use tags starting at 1000, and shall update the wiki page at<br />
https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with<br />
other extensions.<br />
<br />
==References==<br />
<br />
BIP 71 : Payment Protocol bitcoin: URI extensions<br />
<br />
BIP 72 : Payment Protocol mime types<br />
<br />
Public-Key Infrastructure (X.509) working group :<br />
http://datatracker.ietf.org/wg/pkix/charter/<br />
<br />
Protocol Buffers : https://developers.google.com/protocol-buffers/<br />
<br />
==See Also==<br />
<br />
Javascript Object Signing and Encryption working group :<br />
http://datatracker.ietf.org/wg/jose/<br />
<br />
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice<br />
especially the list of Electronic Invoice standards<br />
<br />
sipa's payment protocol proposal: https://gist.github.com/1237788<br />
<br />
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html<br />
<br />
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :<br />
http://arxiv.org/abs/1212.3257<br />
<br />
[[Category:BIP]]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Template:MainPage_Intro&diff=38902Template:MainPage Intro2013-06-25T18:02:40Z<p>Gavinandresen: Update links to 0.8.3</p>
<hr />
<div>[[Image:Bitcoin world map.png|left|200px|Bitcoin usage worldwide.]]<br />
<br />
'''Bitcoin''' is an experimental, decentralized [[digital currency]] that enables instant payments to anyone, anywhere in the world. [[Bitcoin]] uses peer-to-peer technology to operate with no central authority: managing transactions and issuing money are carried out collectively by the network. <br />
<br />
The original Bitcoin software by [[Satoshi Nakamoto]] was released under the MIT license.<br />
Most client software, derived or "from scratch", also use open source licensing.<br />
<br />
Bitcoin is one of the first implementations of a concept called ''crypto-currency'' which was first described in 1998 by Wei Dai on the cypherpunks mailing list. Building upon the notion that money is any object, or any sort of record, accepted as payment for goods and services and repayment of debts in a given country or socio-economic context, Bitcoin is designed around the idea of using cryptography to control the creation and transfer of money, rather than relying on central authorities.<br />
<br />
:''Sourced from [http://bitcoin.org Bitcoin.org] and [[wikipedia:Bitcoin|Wikipedia]].''<br />
<br />
'''Bitcoin-Qt:'''<br />
{|style="background-color: inherit;"<br />
|<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.3/bitcoin-0.8.3-win32-setup.exe/download '''Windows (exe)'''] 10 MB [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.3/bitcoin-0.8.3-win32.zip/download '''(zip)'''] 14 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.3/bitcoin-0.8.3-linux.tar.gz/download '''GNU/Linux'''] 13 MB<br />
* [http://sourceforge.net/projects/bitcoin/files/Bitcoin/bitcoin-0.8.3/bitcoin-0.8.3-macosx.dmg/download '''Mac OS X'''] 12 MB<br />
|}<br />
<br />
[http://bitcoin.org/clients.html More Bitcoin Client Software]</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Talk:Tonal_Bitcoin&diff=38041Talk:Tonal Bitcoin2013-05-25T23:28:07Z<p>Gavinandresen: </p>
<hr />
<div>This is for discussion, not trolling. Note that this is not an encyclopedia, and does not have any "notability" requirements. If you don't want to use Tonal, don't. Trolling is not acceptable and will be deleted. Reasoned criticism is welcome in the "Criticism" section of the page.<br />
<br />
<br />
I have no legitimate stake in the matter, I made a few edits that I hope remove POV and still embrace the idea of Tonal Bitcoin. This is Raize, I am sorry I am not familiar enough with wiki editing to provide my signature. --[[User:Raize|Raize]]<br />
<br />
This page should be deleted until there is a working, supported, maintained Tonal Bitcoin client. Vaporware doesn't belong on this wiki, you'll get articles on CosbyCoin and UnicornCoin...<br />
[[User:Gavinandresen|Gavin Andresen]] ([[User talk:Gavinandresen|talk]]) 23:28, 25 May 2013 (GMT)</div>Gavinandresenhttps://en.bitcoin.it/w/index.php?title=Alert_system&diff=37687Alert system2013-05-10T14:22:07Z<p>Gavinandresen: /* Past alerts */</p>
<hr />
<div>[[File:alert.png|thumb|300px|right]]<br />
<br />
Bitcoin versions 0.3.10 and later have an alert system which allows messages about critical network problems to be broadcast to all clients. When an alert is in effect, the message it contains will appear in the status bar of all clients, and also in the "errors" field of RPC ''getinfo''.<br />
<br />
[[File:Bitcoin-alert-cli.png|thumb|300px|right]]<br />
<br />
===Alert message===<br />
Alerts are broadcast using the same [[network|TCP relay system]] as ''block'' and ''tx'' messages. They are not encoded in a special transaction. Unlike block and tx relaying, alerts are sent at the start of every new connection for as long as the alert is in effect. This ensures that everyone receives the alert.<br />
<br />
Alerts contain this information:<br />
* How long to relay the alert.<br />
* How long to consider the alert valid.<br />
* An alert ID number.<br />
* A list of alerts that should be canceled upon receipt of this alert.<br />
* Exactly which versions of Bitcoin are affected by the alert. Unaffected versions still relay the alert for the benefit of older versions.<br />
* Alert priority.<br />
* The alert text.<br />
<br />
Only alerts that are signed by a specific ECDSA public key are considered valid. A copy of the private key is held by at least Satoshi, Gavin, and theymos.<br />
<br />
===Safe mode===<br />
Until version 0.3.20, Bitcoin went into safe mode when a valid alert was received. In safe mode, all RPC commands that send BTC or get info about received BTC return an error. Current Bitcoin versions no longer go into safe mode in response to alerts, though Bitcoin ''will'' still go into safe mode when it detects on its own that something is seriously wrong with the network.<br />
<br />
Even though Bitcoin no longer automatically disables RPC when an alert is live, it is wise for Bitcoin sites to shut down when an alert has been issued. To detect an active alert, poll the "errors" field of ''getinfo''.<br />
<br />
To test safe mode, run Bitcoin with the -testsafemode switch. To override a real safe mode event, run Bitcoin with the -disablesafemode switch.<br />
<br />
===Past alerts===<br />
{| class="wikitable" border="1"<br />
|-<br />
! ID<br />
! Sent date<br />
! Expires (UTC)<br />
! Versions<br />
! Priority<br />
! Message<br />
|-<br />
| 1010<br />
| Feb 18, 2012<br />
| Feb 21 02:47:15<br />
| All<br />
| 100<br />
| See bitcoin.org/feb20 if you have trouble connecting after 20 February<br />
|-<br />
| 1011<br />
| Mar 16, 2012<br />
| cancelled May 15, 2012<br />
| 0.5 - 0.5.3<br />
| 5000<br />
| URGENT: security fix for Bitcoin-Qt on Windows: http://bitcoin.org/critfix<br />
|-<br />
| 1012<br />
| Mar 16, 2012<br />
| cancelled May 15, 2012<br />
| 6.0<br />
| 5000<br />
| URGENT: security fix for Bitcoin-Qt on Windows: http://bitcoin.org/critfix<br />
|-<br />
| 1013<br />
| Mar 16, 2012<br />
| cancelled May 15, 2012<br />
| 5.99<br />
| 5000<br />
| URGENT: security fix for Bitcoin-Qt on Windows: http://bitcoin.org/critfix<br />
|-<br />
| 1015<br />
| May 15, 2012<br />
| May 16, 2013<br />
| 0.1 - 0.4.5<br />
| 5000<br />
| URGENT: upgrade required, see http://bitcoin.org/dos for details<br />
|-<br />
| 1016<br />
| May 15, 2012<br />
| May 16, 2013<br />
| 0.4.99 - 0.5.4<br />
| 5000<br />
| URGENT: upgrade required, see http://bitcoin.org/dos for details<br />
|-<br />
| 1020<br />
| May 15, 2012<br />
| May 16, 2013<br />
| 0.6.0<br />
| 5000<br />
| URGENT: upgrade required, see http://bitcoin.org/dos for details<br />
|-<br />
| 1032<br />
| March 12, 2013<br />
| March 13, 2013<br />
| 0.8.0<br />
| 5000<br />
| URGENT: chain fork, stop mining on version 0.8<br />
|-<br />
| 1033<br />
| March 19, 2013<br />
| March 20, 2013<br />
| 0.1 - 0.7.2<br />
| 10<br />
| See http://bitcoin.org/may15.html for an important message<br />
|-<br />
| 1034<br />
| May 9, 2013<br />
| June 8, 2013<br />
| 0.1 - 0.7.2<br />
| 10<br />
| Action required: see http://bitcoin.org/may15.html for more information<br />
|}<br />
<br />
==See Also==<br />
<br />
* [[Alerts mailing list]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Vocabulary]]</div>Gavinandresen