The bitcoin reference client maintains a pool of addresses, the size of which is displayed by +keypoolsize+ when you use the command +getinfo+. These addresses are generated automatically and can then be used as public receiving addresses or change addresses. To get one of these addresses, you can use the +getnewaddress+ command:
----
$ bitcoind getnewaddress
13fE8BGhBvnoy68yZKuWJ2hheYKovSDjqM
$
1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL
----
Now, we can use this address to send a small amount of bitcoin to our bitcoind wallet from an external wallet (assuming you have some bitcoin in an exchange, web wallet or othe bitcoind wallet held elsewhere). For this example, we will send 10 millibits (0.010 bitcoin) to the address returned above +13fE8BGhBvnoy68yZKuWJ2hheYKovSDjqM+.
Now, we can use this address to send a small amount of bitcoin to our bitcoind wallet from an external wallet (assuming you have some bitcoin in an exchange, web wallet or othe bitcoind wallet held elsewhere). For this example, we will send 50 millibits (0.050 bitcoin) to the address returned above.
We can now query the bitcoind client for the amount received by this address, and specify how many confirmations are required before an amount is counted in that balance. For this example, we will specify zero confirmations. A few seconds after sending the bitcoin from another wallet, we will see it reflected in the wallet. We use +getreceivedbyaddress+ with the address and the number of confirmations set to zero (0):
If we ommit the zero from the end of this command, we will only see the amounts that have at least +minconf+ confirmations, where +minconf+ is the setting for the minimum number of confirmations before a transaction is ilsted in the balance. The +minconf+ setting is specified in the bitcoind configuration file. Since the transaction sending this bitcoin was only sent in the last few seconds, it has still not confirmed and therefore we will see it list a zero balance:
The transactions received by the entire wallet (all the addresses above) can also be displayed using the +listtransactions+ command:
Finally, the command +getbalance+ will show the total balance of the wallet, adding up all transactions confirmed with at least +minconf+ confirmations:
If the transaction has not yet confirmed, the balance returned by getbalance will be zero. The configuration option "minconf" determines the minimum number of confirmations that are required before a transaction shows in the balance
We'll now explore the incoming transaction that was listed above, using the +gettransaction+. We can retrieve a transaction by its transaction hash, shown at +txid+, above with the +gettransaction+ command:
Transaction IDs are not authoritative until a transaction has been confirmed. Absence of a transaction hash in the blockchain does not mean the transaction was not processed. This is known as "transaction malleability", as transaction hashes can be modified prior to confirmation in a block. After confirmation, the txid is immutable and authoritative.
====
The transaction form shown above with the command +gettransaction+ is the simplified form. To retrieve the full transaction code and decode it we will use two commands, +getrawtransaction+ and +decoderawtransaction+. First, +getrawtransaction+ takes the transaction hash (txid) as a parameter and returns the full transaction as a "raw" hex string, exactly as it exists on the bitcoin network:
To decode this hex string, we can use the +decoderawtransaction+ command. Copy and paste the hex as the first parameter of +decoderawtransaction+ to get the full contents interpreted as a JSON data structure (for formatting reasons the hex string is shortened in the example below):
The transaction decode shows all the compoenents of this transaction, including the transaction inputs, and outputs. In this case we see that the transaction that credited our new address with 50 milibits used one input and generated two outputs. The input to this transaction was the output from a previously confirmed transaction (shown as the vin txid starting with +d3c7+ above). The two outputs correspond to the 50 milibit credit and an output with change back to the sender.
We can further explore the blockchain by examining the previous transaction referenced by its txid in this transaction, using the same commands (eg. +gettransaction+). Jumping from transaction to transaction we can follow a chain of transactions back as the coins are transmitted from owner address to owner address.
Once the transaction we received has been confirmed, by inclusion in a block, the +gettransaction+ command will return additional information, showing the block hash (identifier) in which the transaction was included:
Above, we see the new information in the entries +blockhash+, the hash of the block in which the transaction was included, and +blockindex+ with value 18, indicating that our transaction was the 18th transaction in that block.
==== Commands: getblock
Now that we know which block our transaction was included in, we can query that block. We use the +getblock+ command with the block hash as the parameter:
The block contains 367 transactions and as you see above, the 18th transaction listed (+9ca8f9...+) is the txid of the one crediting 50 millibits to our address. The +height+ entry tells us this is the 286384'th block in the blockchain.
We can also retrieve a block by its block height, using the +getblockhash+ command, which takes the block height as the parameter and returns the block hash for that block:
Andreas M. Antonopoulos
10 years ago