Module: Bitcoin::Client

Defined in:: lib/bitcoin/client.rb,
lib/bitcoin/client/info.rb,
lib/bitcoin/client/configuration.rb

Overview

A singleton abstraction of the Bitcoin client. It accesses the client via the JSON-RPC interface which can be enabled on the official client. Once the Client is configured it can be reused for multiple calls.

Examples:

Bitcoin::Client.configure { |c| c.location = 'http://user:password@127.0.0.1:8332' }

Author:

Michael Prins

Defined Under Namespace

Classes: Configuration, Info

Class Method Summary (collapse)

+ (nil) back_up_wallet(path = nil) (also: backup_wallet, backupwallet)

Back up the current state of the wallet to a specified file or folder.
+ (Object) call(method, *args) private

Package the parameters provided into a JSON-RPC call and post them to the Bitcoin client.
+ (nil) configure {|Bitcoin::Client::Configuration| ... }

Configure the connection to the Bitcoin client before you start interacting with it.
+ (Bitcoin::Account) get_account(address) (also: getaccount)

Retrieve the Account that an Address belongs to.
+ (Float) get_balance(account = '', minimum_confirmations = 1) (also: getbalance)

Get the current balance of either a specific account or the global account.
+ (Bitcoin::Client::Info) get_info (also: getinfo)

Gets the current state of the Bitcoin client.
+ (Bitcoin::Address) get_new_address(account = nil) (also: getnewaddress)

Generate a new address for a specific account or the global account.
+ (Hash) list_accounts(minimum_confirmations = 1) (also: listaccounts)

Fetch all accounts with their current balances.
+ (Hash) list_received_by_address(minimum_confirmations = 1, include_empty_addresses = false) (also: listreceivedbyaddress)

Fetch total amounts received by the Bitcoin client per Address.
+ (Object) method_missing(name, *args, &block) private

Allows methods that have not been implemented to be used.
+ (Bitcoin::Address) validate_address(address) (also: validateaddress)

Validates a Bitcoin address and instantiates an appropriate Address object.

Class Method Details

+ (`nil`) back_up_wallet(path = nil) Also known as: backup_wallet, backupwallet

Back up the current state of the wallet to a specified file or folder. Be sure to use forward-slashes for path separators.

Examples

Bitcoin::Client.back_up_wallet
# => nil

Bitcoin::Client.back_up_wallet '/var/wallet/20111213000000000.dat'
# => nil

Parameters:

path (String) (defaults to: nil) —

The path where the wallet backup should be written. The target file should not exist and should be specified using Linux style (/var/wallet_backups/). If not specified a generated path such as /tmp/wallet.#{timestamp}.dat will be used.

Returns:

(nil)

# File 'lib/bitcoin/client.rb', line 79

def self.back_up_wallet(path = nil)
  path ||= "/tmp/wallet.#{Time.now.utc.to_i}.dat"
  call('backupwallet', path)
end

+ (`Object`) call(method, *args) (private)

Package the parameters provided into a JSON-RPC call and post them to the Bitcoin client.

Parameters:

method (String) —

The method that the Bitcoin client understands
args —

An indeterminate number of parameters that vary by method in number and type.

Returns:

(Object) —

Usually a Hash, String, Integer or Float containing the Bitcoin client's response unless an error occurs.

Raises:

(CommunicationError.new)

# File 'lib/bitcoin/client.rb', line 232

def self.call(method, *args)
  raise CommunicationError.new, 
        CommunicationError::UNKNOWN_HOST if @configuration.location.empty?

  post_json = {
    'method' => method, 
    'params' => args, 
    'id' => @configuration.identifier
  }.to_json

  begin
    response_json = RestClient.post(@configuration.location, post_json)
  rescue RestClient::ResourceNotFound
    return nil
  end
  response = JSON.parse response_json
  raise CommunicationError.new, response['error'] if response['error']
  
  response['result']
end

+ (`nil`) configure {|Bitcoin::Client::Configuration| ... }

Configure the connection to the Bitcoin client before you start interacting with it.

Examples:

Bitcoin::Client.configure { |config| config.location = 'http://user:password@127.0.0.1:8332' }

Yields:

(Bitcoin::Client::Configuration) —

The object yielded can be used to assign any of the following:

`location`:: A String location where the client can be reached.
`identifier`:: A String identifying your application.

Returns:

(nil)

# File 'lib/bitcoin/client.rb', line 44

def self.configure(&block)
  @configuration ||= Configuration.new
  yield(@configuration)
end

+ (`Bitcoin::Account`) get_account(address) Also known as: getaccount

Retrieve the Account that an Address belongs to.

Parameters:

address (String, Bitcoin::Address) —

The address you wish to find the account for.

Returns:

(Bitcoin::Account) —

The Account that owns the Address.



182
183
184

# File 'lib/bitcoin/client.rb', line 182

def self.get_account(address)
  Account.new(call('getaccount', address.to_s))
end

+ (`Float`) get_balance(account = '', minimum_confirmations = 1) Also known as: getbalance

Get the current balance of either a specific account or the global account.

Examples

Bitcoin::Client.get_balance
# => 15.4

Bitcoin::Client.get_balance('Savings')
# => 12.0

Bitcoin::Client.get_balance('Non-existent')
# => 0.0

Bitcoin::Client.get_balance('', 0)
# => 23.6

Parameters:

account (String) (defaults to: '') —

The account name. An empty String implies the global account which is the default.
minimum_confirmations (Integer) (defaults to: 1) —

The minimum number of confirmations from the network for a transaction to be included in the balance. If 0 is provided here unconfirmed transactions will also be included. The default is 1.

Returns:

(Float) —

The balance of the account or 0.0 if it does not exist.



109
110
111

# File 'lib/bitcoin/client.rb', line 109

def self.get_balance(account = '', minimum_confirmations = 1)
  call('getbalance', account.to_s, minimum_confirmations)
end

+ (`Bitcoin::Client::Info`) get_info Also known as: getinfo

Gets the current state of the Bitcoin client. See Bitcoin::Client::Info for documentation on what information it provides.

Example

Bitcoin::Client.get_info.mining?
# => false

Returns:

(Bitcoin::Client::Info) —

A representation of the Client's state.



58
59
60

# File 'lib/bitcoin/client.rb', line 58

def self.get_info
  Info.new(call('getinfo'))
end

+ (`Bitcoin::Address`) get_new_address(account = nil) Also known as: getnewaddress

Generate a new address for a specific account or the global account

Parameters:

account (String, Bitcoin::Account) (defaults to: nil) —

The account the new address should belong to. Use this if you want to track payments to this address.

Returns:

(Bitcoin::Address) —

A newly generated Bitcoin::Address.

# File 'lib/bitcoin/client.rb', line 193

def self.get_new_address(account = nil)
  if account
    Address.new(call('getnewaddress', account.to_s), true, true, account.to_s)
  else
    Address.new(call('getnewaddress'), true, true, account.to_s)
  end
end

+ (`Hash`) list_accounts(minimum_confirmations = 1) Also known as: listaccounts

Fetch all accounts with their current balances

Parameters:

minimum_confirmations (Integer) (defaults to: 1) —

The number of confirmations that are required on a Transaction in order for it to contribute to the total balance.

Returns:

(Hash) —

The Hash returned has the account name as a String for keys and the Bitcoin::Account object as the value. The balance can be retrieved from these objects.

# File 'lib/bitcoin/client.rb', line 167

def self.list_accounts(minimum_confirmations = 1)
  return_hash = {}
  call('listaccounts', minimum_confirmations).each do |name, balance|
    return_hash[name] = Account.new(name, balance)
  end

  return_hash
end

+ (`Hash`) list_received_by_address(minimum_confirmations = 1, include_empty_addresses = false) Also known as: listreceivedbyaddress

Fetch total amounts received by the Bitcoin client per Address.

Parameters:

minimum_confirmations (Integer) (defaults to: 1) —

The number of confirmations required for the transaction to count toward the total.
include_empty_addresses (true, false) (defaults to: false) —

A flag you can set if you want a list of all addresses, otherwise empty addresses are excluded.

Returns:

(Hash) —

A Hash with String addresses as keys and a Bitcoin::Address in :address, a Float for the total amount received in :amount and a Integer number of confirmations for the most recent transaction in :confirmations.

# File 'lib/bitcoin/client.rb', line 144

def self.list_received_by_address(minimum_confirmations = 1, include_empty_addresses = false)
  raw_hash = call('listreceivedbyaddress', minimum_confirmations, include_empty_addresses)
  return_hash = {}
  raw_hash.each do |raw_object|
    return_hash[raw_object['address']] = {
      :address => Address.new(raw_object['address'], true, true, Bitcoin::Account.new(raw_object['account'])),
      :amount => raw_object['amount'],
      :confirmations => raw_object['confirmations']
    }
  end

  return_hash
end

+ (`Object`) method_missing(name, *args, &block) (private)

Allows methods that have not been implemented to be used. Over time this will be relied upon less and less and changes to the return types of method calls captured by method_missing will not be considered backwards-incompatible for semantic versioning considerations.



219
220
221

# File 'lib/bitcoin/client.rb', line 219

def self.method_missing(name, *args, &block)
  return call(name.to_s.gsub('_', ''), *args)
end

+ (`Bitcoin::Address`) validate_address(address) Also known as: validateaddress

Validates a Bitcoin address and instantiates an appropriate Address object.

Parameters:

address (String) —

the cryptographic hash of the address

Returns:

(Bitcoin::Address) —

the validated Address

# File 'lib/bitcoin/client.rb', line 119

def self.validate_address(address)
  result_hash = call('validateaddress', address)

  if result_hash
    Address.new(result_hash['address'], 
                result_hash['isvalid'], 
                result_hash['ismine'], 
                result_hash['account'])
  else
    Address.new(address, false)
  end
end

Module: Bitcoin::Client

Overview

Defined Under Namespace

Class Method Summary (collapse)

Class Method Details

+ (nil) back_up_wallet(path = nil) Also known as: backup_wallet, backupwallet

Examples

+ (Object) call(method, *args) (private)

+ (nil) configure {|Bitcoin::Client::Configuration| ... }

+ (Bitcoin::Account) get_account(address) Also known as: getaccount

+ (Float) get_balance(account = '', minimum_confirmations = 1) Also known as: getbalance

Examples

+ (Bitcoin::Client::Info) get_info Also known as: getinfo

Example

+ (Bitcoin::Address) get_new_address(account = nil) Also known as: getnewaddress

+ (Hash) list_accounts(minimum_confirmations = 1) Also known as: listaccounts

+ (Hash) list_received_by_address(minimum_confirmations = 1, include_empty_addresses = false) Also known as: listreceivedbyaddress

+ (Object) method_missing(name, *args, &block) (private)

+ (Bitcoin::Address) validate_address(address) Also known as: validateaddress

+ (`nil`) back_up_wallet(path = nil) Also known as: backup_wallet, backupwallet

+ (`Object`) call(method, *args) (private)

+ (`nil`) configure {|Bitcoin::Client::Configuration| ... }

+ (`Bitcoin::Account`) get_account(address) Also known as: getaccount

+ (`Float`) get_balance(account = '', minimum_confirmations = 1) Also known as: getbalance

+ (`Bitcoin::Client::Info`) get_info Also known as: getinfo

+ (`Bitcoin::Address`) get_new_address(account = nil) Also known as: getnewaddress

+ (`Hash`) list_accounts(minimum_confirmations = 1) Also known as: listaccounts

+ (`Hash`) list_received_by_address(minimum_confirmations = 1, include_empty_addresses = false) Also known as: listreceivedbyaddress

+ (`Object`) method_missing(name, *args, &block) (private)

+ (`Bitcoin::Address`) validate_address(address) Also known as: validateaddress