Bitcoin Wiki - User contributions [en]

Original Bitcoin client/API calls list

2011-11-10T21:56:44Z

Sonny: getreceivedbyaddress clarification

Bitcoin API call list (as of version 0.4.0)

== Common operations ==

=== Listing my bitcoin addresses ===

Listing the bitcoin [[address|addresses]] in your wallet is easily done via ''listreceivedbyaddress''. It normally lists only addresses which already have received transactions, however you can list all the addresses by setting the first argument to 0, and the second one to true.

[[accounts explained|Accounts]] are used to organize addresses.

== Full list ==

Required arguments are denoted inside < and > Optional arguments are inside [ and ].

{|class="wikitable"
! Command !! Parameters !! Description !! Requires unlocked wallet? (v0.4.0+)
|-
| backupwallet || <destination> || Safely copies wallet.dat to destination, which can be a directory or a path with filename. || N
|-
| encryptwallet || <passphrase> || Encrypts the wallet with <passphrase>. || N
|-
| getaccount || <bitcoinaddress> || Returns the account associated with the given address. || N
|-
| getaccountaddress || <account> || Returns the current bitcoin address for receiving payments to this account. || N
|-
| getaddressesbyaccount || <account> || Returns the list of addresses for the given account. || N
|-
| getbalance || [account] [minconf=1] || If [account] is not specified, returns the server's total available balance.<br/>If [account] is specified, returns the balance in the account. || N
|-
| getblockbycount || height || Dumps the block existing at specified height. '''Note: this is not available in the official release'''
|-
| getblockcount || || Returns the number of blocks in the longest block chain. || N
|-
| getblocknumber || || Returns the block number of the latest block in the longest block chain. || N
|-
| getconnectioncount || || Returns the number of connections to other nodes. || N
|-
| getdifficulty || || Returns the proof-of-work difficulty as a multiple of the minimum difficulty. || N
|-
| getgenerate || || Returns true or false whether bitcoind is currently generating hashes || N
|-
| gethashespersec || || Returns a recent hashes per second performance measurement while generating.
|-
| getinfo || || Returns an object containing various state info.
|-
| getnewaddress || [account] || Returns a new bitcoin address for receiving payments. If [account] is specified (recommended), it is added to the address book so payments received with the address will be credited to [account].
|-
| getreceivedbyaccount || [account] [minconf=1] || Returns the total amount received by addresses with [account] in transactions with at least [minconf] confirmations. If [account] not provided return will include all transactions to all accounts. (version 0.3.24-beta)
|-
| getreceivedbyaddress || <bitcoinaddress> [minconf=1] || Returns the total amount received by <bitcoinaddress> in transactions with at least [minconf] confirmations. While some might consider this obvious, value reported by this only considers *receiving* transactions. It does not check payments that have been made *from* this address. In other words, this is not "getaddressbalance".
|-
| gettransaction || <txid> || Returns an object about the given transaction containing:
* "amount" : total amount of the transaction
* "confirmations" : number of confirmations of the transaction
* "txid" : the transaction ID
* "time" : time the transaction occurred
* "details" - An array of objects containing:
** "account"
** "address"
** "category"
** "amount"
|-
| [[getwork]] || [data] || If [data] is not specified, returns formatted hash data to work on:
* "midstate" : precomputed hash state after hashing the first half of the data
* "data" : block data
* "hash1" : formatted hash buffer for second hash
* "target" : little endian hash target
If [data] is specified, tries to solve the block and returns true if it was successful.
|-
| help || [command] || List commands, or get help for a command. || N
|-
| keypoolrefill || || Fills the keypool, requires wallet passphrase to be set. || Y
|-
| listaccounts || [minconf=1] || Returns Object that has account names as keys, account balances as values.
|-
| listreceivedbyaccount || [minconf=1] [includeempty=false] || Returns an array of objects containing:
* "account" : the account of the receiving addresses
* "amount" : total amount received by addresses with this account
* "confirmations" : number of confirmations of the most recent transaction included
|-
| listreceivedbyaddress || [minconf=1] [includeempty=false] || Returns an array of objects containing:
* "address" : receiving address
* "account" : the account of the receiving address
* "amount" : total amount received by the address
* "confirmations" : number of confirmations of the most recent transaction included
To get a list of accounts on the system, execute bitcoind listreceivedbyaddress 0 true
|-
| listtransactions || [account] [count=10] [from=0] || Returns up to [count] most recent transactions skipping the first [from] transactions for account [account]. If [account] not provided will return recent transaction from all accounts.
|-
| move || <fromaccount> <toaccount> <amount> [minconf=1] [comment] || Move from one account in your wallet to another.
|-
| sendfrom || <fromaccount> <tobitcoinaddress> <amount> [minconf=1] [comment] [comment-to] || <amount> is a real and is rounded to 8 decimal places. Will send the given amount to the given address, ensuring the account has a valid balance using [minconf] confirmations. Returns the transaction ID if successful (not in JSON object). || Y
|-
| sendmany || <fromaccount> {address:amount,...} [minconf=1] [comment] || amounts are double-precision floating point numbers || Y
|-
| sendtoaddress || <bitcoinaddress> <amount> [comment] [comment-to] || <amount> is a real and is rounded to 8 decimal places. Returns the transaction ID <txid> if successful. || Y
|-
| setaccount || <bitcoinaddress> <account> || Sets the account associated with the given address. Assigning address that is already assigned to the same account will create a new address associated with that account.
|-
| setgenerate || <generate> [genproclimit] || <generate> is true or false to turn generation on or off.<br/>Generation is limited to [genproclimit] processors, -1 is unlimited.
|-
| settxfee || <amount> || <amount> is a real and is rounded to the nearest 0.00000001
|-
| stop || || Stop bitcoin server. || N
|-
| validateaddress || <bitcoinaddress> || Return information about <bitcoinaddress>.
|-
| walletlock || || Removes the wallet encryption key from memory, locking the wallet. After calling this method, you will need to call walletpassphrase again before being able to call any methods which require the wallet to be unlocked.
|-
| walletpassphrase || <passphrase> <timeout> || Stores the wallet decryption key in memory for <timeout> seconds. || N
|-
| walletpassphrasechange || <oldpassphrase> <newpassphrase> || Changes the wallet passphrase from <oldpassphrase> to <newpassphrase>.

|}

==See Also==

* [[Original Bitcoin client]]
* [[API reference (JSON-RPC)]]
* [[Lazy_API]]
* [[Elis-API]] - A more detailed version of this page - for developers!

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

Privacy

2011-11-05T22:21:48Z

Sonny: added link to Bitcoin Fog

While the Bitcoin technology [http://www.bitcointalk.org/index.php?topic=241.0 can support] strong anonymity, the current implementation is usually not very anonymous.

__TOC__

The main problem is that every transaction is publicly logged. Anyone can see the flow of Bitcoins from address to address (see first image). Alone, this information can't identify anyone because the addresses are just random numbers. However, if ''any'' of the addresses in a transaction's past or future can be tied to an actual identity, it might be possible to work from that point and figure out who owns all of the other addresses. This identity information might come from network analysis, surveillance, or just Googling the address. The officially-encouraged practice of using a new address for every transaction is designed to make this attack more difficult.
[[File:Unknownaddress.png|thumb|The flow of Bitcoins from address to address is public.]]

The second image shows a simple example. Someone runs both a money exchanger and a site meant to trap people. When Mr. Doe buys from the exchanger and uses those same coins to buy something from the trap site, the attacker can '''prove''' that these two transactions were made by the same person. The block chain would show:
[[File:knownaddress.png|thumb|Finding an "identity anchor" allows you to ruin the anonymity of the system.]]
* Import coins from address A. Send 100 to B. Authorized by (signature).
* Import coins from address B. Send 100 to C. Authorized by (signature).
You can't change your "sending address"; Mr. Doe ''must'' send coins from the same address that he received them on: address B. The attacker knows for a fact that address B is Mr. Doe because the attacker received $5 from Mr. Doe's Paypal account and then sent 100 BTC to that very same address.

Another example: someone is scammed and posts the address they were using on the Bitcoin forum. It is possible to see which address they sent coins to. When coins are sent from this (the scammer's) address, the addresses that receive them can also be easily found and posted on the forum. In this way, all of these coins are marked as "dirty", potentially over an infinite number of future transactions. When some smart and honest person notices that his address is now listed, he can reveal who he received those coins from. The Bitcoin community can now break some legs, asking, "Who did you receive these coins from? What did you create this address for?" Eventually the original scammer will be found. Clearly, this becomes more difficult the more addresses that exist between the "target" and the "identity point".

You might be thinking that this attack is not feasible. But consider this case:
* You live in China and want to buy a "real" newspaper for Bitcoins.
* You join the Bitcoin forum and use your address as a signature. Since you are very helpful, you manage to get 30 BTC after a few months.
* Unfortunately, you choose poorly in who you buy the newspaper from: you've chosen a government agent! Maybe you are under the mistaken impression that Bitcoin is perfectly anonymous.
* The government agent looks at the block chain and Googles (or Baidus) every address in it. He finds your address in your signature on the Bitcoin forum. You've left enough personal information in your posts to be identified, so you are now scheduled to be "reeducated".

You need to protect yourself from both forward attacks (getting something that identifies you using coins that you got with methods that must remain secret, like the scammer example) and reverse attacks (getting something that must remain secret using coins that identify you, like the newspaper example).

==== Staying Anonymous ====

It is only possible to send bitcoins from the same address with which they have been received. However, if one has bitcoins on several address, one can theoretically choose from which address to send the coins. Choosing personally generated coins or an address that you know doesn't reveal information would protect you. Unfortunately, the default Bitcoin client doesn't support this currently, so you must assume that your entire balance can identify you if any of the addresses can. (Bitcoin sends the smallest coins first, though you shouldn't rely on this.)

You may consider a bitcoin to be "less-anonymous" when an attacker could feasibly find the true identity of a very recent owner of the bitcoin, perhaps because one of the bitcoin addresses was posted to a website, or because he knows some identifying information through other means.

If your balance has been contaminated by both anonymous and non-anonymous coins, you may take action to make it "clean".

Recommended way of anonymizing your balance:
* Send however many coins you want to anonymize to a new [[eWallet]] account as a lump sum. There are other [[eWallet]] services however the more widely used the greater the potential for anonymity. <font color="red">This is not an endorsement of trust in the use of [[eWallet]] services. There are no guarantees that any eWallet service won't one day take all your bitcoins and disappear. Use at your own risk.</font>

With this method an attacker will have to gain access to the eWallet service's transaction logs to continue to follow you in the transaction history.

The protection that this method offers is significantly reduced if you are trying to anonymize more than about 10% of the total number of Bitcoins that the eWallet service holds. You'll end up getting your own coins back instead of other users' coins. Withdrawing Bitcoins more slowly and in smaller increments will help reduce this problem. Sending coins to an eWallet service in the largest single transfer possible will also help.

To further enhance your anonymity, you can:
* Send Bitcoins from one EWallet sevice to another and ''then'' to yourself. Each transfer needs to be painstakingly investigated and many transfers will present insurmountable difficulty.

Once you have an anonymous balance set up, be sure to keep your anonymous and non-anonymous balances completely separate.

A future version of the client will have coderr's patch which will allow the sender to specify which coins to use in a transaction<ref>[http://bitcointalk.org/index.php?topic=24784.msg307661#msg307661 Patching The Bitcoin Client To Make It More Anonymous]</ref>.

==== Help other people stay anonymous ====
* Set up a real [http://www.bitcoin.org/smf/index.php?topic=241.0 external mixing service]. Make it like an eWallet service but make sure that a user never withdraws the same coins that are put in. Also delete empty addresses and transaction logs.
* Even if you're not a programmer, you can make a slightly less secure version of an external mixing service (as a Tor hidden service, preferably):
** Set up two Bitcoin installations.
** Put some amount of BTC in installation B. This is the maximum amount of BTC you can deal with at once (for all customers).
** Customers send BTC to installation A. You send them an equal number of coins (or minus a fee) from installation B. Send as 10-50 BTC increments.
** Send all coins from A to B when '''all''' orders are satisfied. You can't send coins from A to B if you have any orders that have not been satisfied from B.
** This can be automated, or you can do everything manually.
* Put lots of Bitcoins in an eWallet service and keep it there. If anyone uses the anonymization method described in "staying anonymous" above, this will enhance it. Send in smaller increments if a large amount is transferred.

==See Also==

* [http://www.bitcoin.org/smf/index.php?topic=2893.0 RFC: Bitcoin Mixnet]
* [http://www.bitcoin.org/smf/index.php?topic=241.0 anonymity]
* [[Bitcoin Fog]]
* [[Bitcoin Laundry]] (Does not mix well -- you may get your own coins back.)
* [http://bitcointalk.org/index.php?topic=24784.0 Patching The Bitcoin Client To Make It More Anonymous]
* [http://arxiv.org/abs/1107.4524 An Analysis of Anonymity in the Bitcoin System] research by Fergal Reid, Martin Harrigan ([http://bitcointalk.org/index.php?topic=31539.0 discussion])

==References==
<references />

[[Category:Technical]]