raiblocks_rpc 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ebc2824ca4cfba5c8d93ff4c0bfd2f07227f010c9cd95d6658cbf516f2d8ab6
-  data.tar.gz: 41ed59397e6ea7787de9d18c03d7350e6d2541666bd1f1f2b90fd5d3d880f90b
+  metadata.gz: 59e7a8aaac7c10d6376abdd0aaf840ff90d8e22d67acffa0a5920ce1e1848e2d
+  data.tar.gz: be96b5e6188593865f80507fd92cae0c218790c91a1dbf9fedf13a5a6397c43d
 SHA512:
-  metadata.gz: da8e69145e83defd6738c4a2ee2e1cdd747665240d9f1c585963f233ab92c685269bf2e36933166d2a1fb70a97c4cb58ce164d722b512a3ec0e6fc6b9f4b1612
-  data.tar.gz: 36ddcf6cb3b46c221169751135d7a81e6f163ed3d6ffa082a5846d0315b74f5a9bc24e2c724a6b10fd0a58e4be75096c28e6c314181ff9bb84b0b868b3150c33
+  metadata.gz: 9c7482203fbeed536648a9c67b4f07284a0953b774abc6be17ec92159badb2956fb95385c430a4598af2822684b83458e522649d4ac5a669d2fda6c94ee98586
+  data.tar.gz: 229ea7d13d2aca576da81fc439d5c47bff6064e388ab2be56962c76e456a10b525d0d72907711d32fd8ac74cc455099aea5da5f50d873b8a74de7f0d7c865070

data/Gemfile

@@ -1,2 +1,3 @@
+# frozen_string_literal: true
 source 'https://rubygems.org'
 gemspec

data/README.md

@@ -1,8 +1,8 @@
-# RaiBlocksRpc
+# Raiblocks RPC
 
-An RPC wrapper for RaiBlocks written in Ruby.  It connects to an individual node that you control.  There's a client object you can use to make explicit RPC calls as well as proxy objects with logically grouped methods.
+An RPC wrapper for RaiBlocks written in Ruby.  It connects to an individual node that you control.  There's a client object you can use to make explicit RPC calls as well as proxy objects with logically grouped convenience methods.
 
-To run a RaiBlocks node locally, see [Docker documentation](https://github.com/clemahieu/raiblocks/wiki/Docker-node).
+To run a RaiBlocks node locally, see [RaiBlocks Docker Docs](https://github.com/clemahieu/raiblocks/wiki/Docker-node).
 
 ## Installation
 
@@ -22,32 +22,32 @@ Or install it yourself as:
 
 ## Usage
 
-There are two ways to use this gem.  You can make direct calls to the RPC client or use the provided proxy objects.
+There are two ways to use this gem.  You can make direct calls to the RPC client using Ruby hashes or you can use proxy objects that provide helper methods for terser code.
 
-In either case, the client should first be configured to connect to a RaiBlocks node and instantiated.  If you do not specify host or port, then `localhost:7076` will be used by default.
+### Raw RPC Calls
 
-```ruby
-  client = RaiblocksRpc::Client.new(host: 'myraiblocksnode', port: 1234)
-````
+The RCP client exposes raw Remote Procedure Call methods according to the [RaiBlocks RPC Docs](https://github.com/clemahieu/raiblocks/wiki/RPC-protocol).
 
-If you're just using the default configuration, you can use the shorter
+Every method requires an `action`, which is passed as the first argument to `call`.  Depending on the action, there may be additional required or optional parameters that are passed as an options hash.
 
-```ruby
-  client = RaiblocksRpc.Client
-````
+First setup the client:
 
-### Raw RPC Calls
+```ruby
+# Connect to localhost:7076
+client = Raiblocks.client
 
-You can use the RPC client to make raw RPC calls to a RaiBlocks node according to the [documentation](https://github.com/clemahieu/raiblocks/wiki/RPC-protocol).
+# Connect to custom host
+client = Raiblocks::Client.new(host: 'myraiblocksnode', port: 1234)
+```
 
-Every call requires an `action`, which is passed as the first argument to `call`.  Depending on the action, there may be additional required or optional parameters that are passed as an options hash.
+Then make a `call`, passing the the action and the data:
 
 ```ruby
   client.call(:account_balance, account: 'xrb_someaddress1234')
   # => {"balance"=>100, "pending"=>0}
 ````
 
-Response data are provided as `Hashie` objects with integer coercion, indifferent access, and method access included so you have several options for accessing values.
+Response data are provided as `Hashie` objects with integer coercion, indifferent access, and method access so you have several options for accessing returned values.
 
 ```ruby
   data = client.call(:account_balance, account: 'xrb_someaddress1234')
@@ -62,41 +62,71 @@ Response data are provided as `Hashie` objects with integer coercion, indifferen
 
 ### Proxy Objects
 
-A few proxy objects are provided as a means to logically group RPC calls. Here we do not strictly follow the grouping as expressed in the [RaiBlocks RPC documentation](https://github.com/clemahieu/raiblocks/wiki/RPC-protocol).  Instead, the following objects are provided:
+Proxy objects are provided to ease interaction with the API by providing logically grouped helper methods. Here we do not strictly follow the grouping as expressed in the [RaiBlocks RPC Docs](https://github.com/clemahieu/raiblocks/wiki/RPC-protocol).  Instead, the following objects are provided:
 
 ```ruby
-  RaiblocksRpc::Account # { account: 'xrb_address12345' }
-  RaiblocksRpc::Accounts # { accounts: ['xrb_address12345', 'xrb_address67890] }
-  RaiblocksRpc::Wallet # { wallet: 'F3093AB' }
-  RaiblocksRpc::Network
-  RaiblocksRpc::Node
-  RaiblocksRpc::Util
+  Raiblocks::Account # { account: 'xrb_address12345' }
+  Raiblocks::Accounts # { accounts: %w[xrb_address12345 xrb_address67890] }
+  Raiblocks::Node
+  Raiblocks::Wallet # { wallet: 'F3093AB' }
 ```
 
-`Account`, `Accounts`, and `Wallet` each require parameters to be passed during initialization.  You can then make calls on these objects without needing to pass in the params for subsequent calls.
-
-Methods whose prefix matches the class name, such as `account_balance`, also have an abbreviated version, in this case `balance`.
-
+`Account`, `Accounts`, and `Wallet` each require a single parameter to be passed during initialization.  You can then make calls on these objects without needing to pass in the param for subsequent calls.  All RPC methods are provided directly as methods.
 
 ```ruby
-  account = RaiblocksRpc::Account.new('xrb_someaddress1234')
+  account = Raiblocks::Account.new('xrb_someaddress1234')
 
-  account.balance
-  # => {"balance"=>100, "pending"=>0}
   account.account_balance
   # => {"balance"=>100, "pending"=>0}
+  account.account_balance.balance
+  # 100
+  account.balance # Fastest to use #balance helper method
+  # 100
+```
+
+You can ask an object what raw RPC methods it provides using `proxy_methods`:
+
+```ruby
+  account.proxy_methods
+  # => [:account_balance, :account_block_count, :account_create, :account_history, :account_info, :account_key, :account_list, :account_move, :account_remove, :account_representative, :account_representative_set, :account_weight, :accounts_balances, :accounts_create, :accounts_frontiers, :accounts_pending, :delegators, :delegators_count, :frontier_count, :frontiers, :ledger, :payment_wait, :pending, :validate_account_number]
+```
+
+Helper methods are provided for frequently used calls:
+
+```ruby
+  Raiblocks::Account.helper_methods
+  # => [:balance]
+
+  Raiblocks::Account.new('xrb_someaddress1234').balance
+  # => 250
 ```
 
-Some methods appear on multiple objects for convenience.
+`Node` methods are provided at both the instance and class levels:
 
 ```ruby
-  RaiblocksRpc::Node.new.block_count
-  # => {"count"=>314848, "unchecked"=>4793586}
+  Raiblocks::Node.version
+  # => {"rpc_version"=>1, "store_version"=>10, "node_vendor"=>"RaiBlocks 9.0"}
+
+  node = Raiblocks::Node.new
+  version.rpc_version
+  # => 1
+  node.peers
+  # => {"peers"=>{"[::ffff:2.80.5.202]:64317"=>"5", "[::ffff:2.249.74.58]:7075"=>"5", "[::ffff:5.9.31.82]:7077"=>"4", ... }
+  node.available_supply
+  # => {"available"=>132596127030666124778600855847014518457}
+  node.block_count.unchecked
+  # => 4868605
+```
 
-  RaiblocksRpc::Network.new.block_count
-  # => {"count"=>314848, "unchecked"=>4793642}
+To connect to a custom node, instantiate a client and pass it into the proxy object as `client`:
+
+```ruby
+  client = Raiblocks::Client.new(host: 'myraiblocksnode', port: 1234)
+  account = Raiblocks::Account.new('xrb_someaddress1234', client: client)
 ```
 
+For a more comprehensive guide, see the [Wiki](https://github.com/jcraigk/ruby_raiblocks_rpc/wiki).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -2,6 +2,3 @@
 
 require 'bundler/setup'
 require 'raiblocks_rpc'
-
-require 'pry'
-Pry.start

data/lib/raiblocks/client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+require 'rest-client'
+require 'json'
+
+module Raiblocks
+  def self.client
+    @client ||= Client.new
+  end
+
+  class Client
+    attr_accessor :host, :port
+
+    def initialize(host: 'localhost', port: 7076)
+      @host = host
+      @port = port
+    end
+
+    def call(action, params = {})
+      args = { action: action }
+      args.merge!(params) if params.is_a?(Hash)
+      post(args)
+    end
+
+    private
+
+    def post(params)
+      response = rest_client_post(url, params)
+      ensure_status_success!(response)
+
+      data = Raiblocks::Response.new(JSON[response.body])
+      ensure_valid_response!(data)
+
+      data
+    end
+
+    def rest_client_post(url, params)
+      RestClient.post(url, params.to_json)
+    rescue Errno::ECONNREFUSED
+      raise Raiblocks::NodeConnectionFailure,
+            "Node connection failure at #{url}"
+    end
+
+    def url
+      "http://#{host}:#{port}"
+    end
+
+    def ensure_status_success!(response)
+      return if response.code == 200
+      raise Raiblocks::BadRequest,
+            "Error response from node: #{JSON[response.body]}"
+    end
+
+    def ensure_valid_response!(data)
+      return unless data['error']
+      raise Raiblocks::InvalidRequest,
+            "Invalid request: #{data['error']}"
+    end
+  end
+end

data/lib/{raiblocks_rpc → raiblocks}/errors.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
-module RaiblocksRpc
+module Raiblocks
   class Error < StandardError; end
 
+  class NodeConnectionFailure < Error; end
   class BadRequest < Error; end
   class InvalidRequest < Error; end
   class InvalidParameterType < Error; end

data/lib/raiblocks/helpers/account_proxy_helper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+module Raiblocks::AccountProxyHelper
+  def balance
+    account_balance.balance
+  end
+
+  def block_count
+    account_block_count.block_count
+  end
+
+  def create(wallet:, work:)
+    account_create(wallet: wallet, work: work).account
+  end
+
+  def history(count:)
+    account_history(count: count).history
+  end
+
+  def info
+    account_info
+  end
+
+  def key
+    account_key.key
+  end
+
+  def list
+    account_list.accounts
+  end
+
+  def move(wallet:, source:, accounts:)
+    account_move(wallet: wallet, source: source, accounts: accounts).moved == 1
+  end
+
+  def wallet_work(wallet:)
+    work_get(wallet: wallet).work
+  end
+
+  def wallet_work_set(wallet:, work:)
+    work_set(wallet: wallet, work: work).work[:success] == ''
+  end
+
+  def pending_balance
+    account_balance.pending
+  end
+  alias balance_pending pending_balance
+
+  def pending_blocks(count:, threshold: nil, exists: nil)
+    pending(count: count, threshold: threshold, exists: exists).locks
+  end
+  alias blocks_pending pending_blocks
+
+  def remove(wallet:)
+    account_remove(wallet: wallet).removed == 1
+  end
+
+  def representative
+    account_representative.representative
+  end
+
+  def representative_set(wallet:, representative:)
+    account_representative_set(
+      wallet: wallet, representative: representative
+    ).set == 1
+  end
+
+  def weight
+    account_weight.weight
+  end
+end

data/lib/raiblocks/helpers/accounts_proxy_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+module Raiblocks::AccountsProxyHelper
+  def frontiers
+    accounts_frontiers.frontiers
+  end
+
+  def balances
+    accounts_balances.balances
+  end
+
+  def create(wallet:, count:, work: nil)
+    accounts_create(wallet: wallet, count: count, work: work).accounts
+  end
+
+  def pending(count:, threshold: nil, source: nil)
+    accounts_pending(count: count, threshold: threshold, source: source).blocks
+  end
+  alias pending_blocks pending
+
+  # Array-like access for Raiblocks::Account
+  def [](idx)
+    return unless @addresses[idx]
+    @account_objects ||= []
+    @account_objects[idx] ||= Raiblocks::Account.new(@addresses[idx])
+  end
+
+  def <<(val)
+    @addresses << val
+  end
+
+  def each(&_block)
+    @addresses.each do |address|
+      yield Raiblocks::Account.new(address)
+    end
+  end
+
+  def first
+    self[0]
+  end
+
+  def second
+    self[1]
+  end
+
+  def third
+    self[2]
+  end
+end

data/lib/raiblocks/helpers/node_proxy_helper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+module Raiblocks::NodeProxyHelper
+  def account_containing_block(hash)
+    block_account(hash: hash).account
+  end
+
+  def available
+    available_supply.available
+  end
+
+  def krai_from(amount:)
+    krai_from_raw(amount: amount).amount
+  end
+
+  def krai_to(amount:)
+    krai_to_raw(amount: amount).amount
+  end
+
+  def mrai_from(amount:)
+    mrai_from_raw(amount: amount).amount
+  end
+
+  def mrai_to(amount:)
+    mrai_to_raw(amount: amount).amount
+  end
+
+  def pending_exists?(hash:)
+    pending_exists(hash: hash).exists == 1
+  end
+
+  def rai_from(amount:)
+    rai_from_raw(amount: amount).amount
+  end
+
+  def rai_to(amount:)
+    rai_to_raw(amount: amount).amount
+  end
+
+  def work_valid?(work:, hash:)
+    work_validate(work: work, hash: hash).valid == 1
+  end
+end

data/lib/raiblocks/helpers/wallet_proxy_helper.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+module Raiblocks::WalletProxyHelper
+  def account_work(account:)
+    work_get.work(account: account).work
+  end
+
+  def add(key:, work: nil)
+    wallet_add(key: key, work: work).account
+  end
+
+  def balance
+    wallet_balance_total.balance
+  end
+
+  def balances(threshold: nil)
+    wallet_balances(threshold: threshold).balances
+  end
+
+  def begin_payment
+    payment_begin.account
+  end
+
+  def change_password(new_password:)
+    password_change(password: new_password).changed == 1
+  end
+
+  def change_seed(new_seed:)
+    wallet_change_seed(seed: new_seed)[:success] == ''
+  end
+
+  def contains?(account:)
+    wallet_contains(account: account).exists == 1
+  end
+
+  def create
+    wallet_create.wallet
+  end
+
+  def destroy
+    wallet_destroy
+  end
+
+  def enter_password(password)
+    password_enter(password: password).valid == 1
+  end
+
+  def export
+    JSON[wallet_export.json]
+  end
+
+  def frontiers
+    wallet_frontiers.frontiers
+  end
+
+  def init_payment
+    payment_init.status == 'Ready'
+  end
+
+  def locked?
+    wallet_locked.locked == 1
+  end
+
+  def password_valid?(password:)
+    password_valid(password: password).valid == 1
+  end
+
+  def pending_balance
+    wallet_balance_total.pending
+  end
+
+  def pending_blocks(count:, threshold: nil, source: nil)
+    wallet_pending(count: count, threshold: threshold, source: source).blocks
+  end
+
+  def receive_block(account:, block:)
+    receive.block(account: account, block: block).block
+  end
+
+  def representative
+    wallet_representative.representative
+  end
+
+  def republish(count:)
+    wallet_republish(count: count).blocks
+  end
+
+  def account_work_set(account:, work:)
+    work_set(account: account, work: work).work[:success] == ''
+  end
+  alias set_account_work account_work_set
+
+  def representative_set(representative:)
+    wallet_representative_set(representative: representative).set == 1
+  end
+  alias set_representative representative_set
+
+  def send_tx(source:, destination:, amount:)
+    rai_send(source: source, destination: destination, amount: amount).block
+  end
+  alias send_transaction send_tx
+
+  def work
+    wallet_work_get.works
+  end
+end

data/lib/raiblocks/proxies/account.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+class Raiblocks::Account
+  include Raiblocks::Proxy
+  include Raiblocks::AccountProxyHelper
+
+  attr_accessor :address
+
+  def initialize(address = nil, opts = {})
+    unless address.is_a?(String)
+      raise Raiblocks::MissingParameters,
+            'Missing argument: address (str)'
+    end
+
+    @address = address
+    @client = opts[:client] || Raiblocks.client
+  end
+
+  proxy_params account: :address
+
+  proxy_method :account_balance
+  proxy_method :account_block_count
+  proxy_method :account_info
+  proxy_method :account_create, required: %i[wallet], optional: %i[work]
+  proxy_method :account_history, required: %i[count]
+  proxy_method :account_list
+  proxy_method :account_move, required: %i[wallet source accounts]
+  proxy_method :account_key
+  proxy_method :account_remove, required: %i[wallet]
+  proxy_method :account_representative
+  proxy_method :account_representative_set, required: %i[wallet representative]
+  proxy_method :account_weight
+  proxy_method :delegators
+  proxy_method :delegators_count
+  proxy_method :frontiers, required: %i[count]
+  proxy_method :frontier_count
+  proxy_method :ledger,
+               required: %i[count],
+               optional: %i[representative weight pending sorting]
+  proxy_method :validate_account_number
+  proxy_method :pending, required: %i[count], optional: %i[threshold exists]
+  proxy_method :payment_wait, required: %i[amount timeout]
+  proxy_method :work_get
+  proxy_method :work_set
+end

data/lib/raiblocks/proxies/accounts.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+class Raiblocks::Accounts
+  include Raiblocks::Proxy
+  include Raiblocks::AccountsProxyHelper
+
+  attr_accessor :addresses
+
+  def initialize(addresses = nil, client = nil)
+    unless addresses.is_a?(Array)
+      raise Raiblocks::MissingParameters,
+            'Missing argument: addresses (str[])'
+    end
+
+    @addresses = addresses
+    @client = client || Raiblocks.client
+  end
+
+  proxy_params accounts: :addresses
+
+  proxy_method :accounts_balances
+  proxy_method :accounts_create, required: %i[wallet count], optional: %i[work]
+  proxy_method :accounts_frontiers
+  proxy_method :accounts_pending,
+               required: %i[count], optional: %i[threshold source]
+end

data/lib/raiblocks/proxies/node.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+class Raiblocks::Node
+  include Raiblocks::Proxy
+  include Raiblocks::NodeProxyHelper
+
+  proxy_method :available_supply
+  proxy_method :block, required: %i[hash]
+  proxy_method :block_account, required: %i[hash]
+  proxy_method :block_count
+  proxy_method :block_count_type
+  proxy_method :block_create,
+               required: %i[type key representative source], optional: %i[work]
+  proxy_method :blocks, required: %i[hashes]
+  proxy_method :blocks_info,
+               required: %i[hashes], optional: %i[pending source]
+  proxy_method :bootstrap, required: %i[address port]
+  proxy_method :bootstrap_any
+  proxy_method :chain, required: %i[block count]
+  proxy_method :deterministic_key, required: %i[seed index]
+  proxy_method :history, required: %i[hash count]
+  proxy_method :keepalive, required: %i[address port]
+  proxy_method :key_create
+  proxy_method :key_expand, required: %i[key]
+  proxy_method :krai_from_raw, required: %i[amount]
+  proxy_method :krai_to_raw, required: %i[amount]
+  proxy_method :mrai_from_raw, required: %i[amount]
+  proxy_method :mrai_to_raw, required: %i[amount]
+  proxy_method :payment_wait, required: %i[account amount timeout]
+  proxy_method :peers
+  proxy_method :pending_exists, required: %i[hash]
+  proxy_method :process, required: %i[block]
+  proxy_method :rai_from_raw, required: %i[amount]
+  proxy_method :rai_to_raw, required: %i[amount]
+  proxy_method :receive_minimum
+  proxy_method :receive_minimum_set, required: %i[amount]
+  proxy_method :representatives
+  proxy_method :republish,
+               required: %i[hash],
+               optional: %i[count sources destinations]
+  proxy_method :search_pending, required: %i[wallet]
+  proxy_method :search_pending_all
+  proxy_method :stop
+  proxy_method :successors, required: %i[block count]
+  proxy_method :unchecked, required: %i[count]
+  proxy_method :unchecked_clear
+  proxy_method :unchecked_get, required: %i[hash]
+  proxy_method :unchecked_keys, required: %i[key count]
+  proxy_method :version
+  proxy_method :work_cancel, required: %i[hash]
+  proxy_method :work_generate, required: %i[hash]
+  proxy_method :work_peer_add, required: %i[address port]
+  proxy_method :work_peers
+  proxy_method :work_peers_clear
+  proxy_method :work_validate, required: %i[work hash]
+end

data/lib/raiblocks/proxies/wallet.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+class Raiblocks::Wallet
+  include Raiblocks::Proxy
+  include Raiblocks::WalletProxyHelper
+
+  attr_accessor :seed
+
+  def initialize(wallet_seed = nil, opts = {})
+    unless wallet_seed.is_a?(String)
+      raise Raiblocks::MissingParameters,
+            'Missing argument: address (str)'
+    end
+
+    @seed = wallet_seed
+    @client = opts[:client] || Raiblocks.client
+  end
+
+  proxy_params wallet: :seed
+
+  proxy_method :wallet_add, required: %i[key], optional: %i[work]
+  proxy_method :wallet_balance_total
+  proxy_method :wallet_balances, optional: %i[threshold]
+  proxy_method :wallet_change_seed, required: %i[seed]
+  proxy_method :wallet_contains, required: %i[account]
+  proxy_method :wallet_create
+  proxy_method :wallet_destroy
+  proxy_method :wallet_export
+  proxy_method :wallet_frontiers
+  proxy_method :wallet_locked
+  proxy_method :wallet_pending,
+               required: %i[count], optional: %i[threshold source]
+  proxy_method :wallet_representative
+  proxy_method :wallet_representative_set, required: %i[representative]
+  proxy_method :wallet_republish, required: %i[count]
+  proxy_method :wallet_work_get
+  proxy_method :work_get
+  proxy_method :work_set
+  proxy_method :password_change, required: %i[password]
+  proxy_method :password_enter, required: %i[password]
+  proxy_method :password_valid
+  proxy_method :payment_begin
+  proxy_method :payment_init
+  proxy_method :payment_end, required: %i[account]
+  proxy_method :receive, required: %i[account block]
+  proxy_method :send, required: %i[wallet source destination amount]
+  proxy_method :search_pending
+end