nanook 1.0.2 → 2.0.0

data/lib/nanook/block.rb

@@ -10,7 +10,7 @@ class Nanook
   # Initialize this class through the convenient Nanook#block method:
   #
   #   nanook = Nanook.new
-  #   account = nanook.block("FBF8B0E...")
+  #   block = nanook.block("FBF8B0E...")
   #
   # Or compose the longhand way like this:
   #
@@ -24,22 +24,23 @@ class Nanook
       block_required! # All methods expect a block
     end
 
-    # Returns a String of the account id of the block.
+    # Returns the {Nanook::Account} of the block.
     #
-    # ==== Example
+    # ==== Example:
+    #   block.account # => Nanook::Account
     #
-    #   block.account # => "xrb_3x7c..."
+    # @return [Nanook::Account] the account of the block
     def account
-      rpc(:block_account, :hash)[:account]
+      Nanook::Account.new(@rpc, rpc(:block_account, :hash)[:account])
     end
 
     # Stop generating work for a block.
     #
-    # Returns boolean signalling if the action was successful.
-    #
-    # ==== Example
+    # ==== Example:
     #
     #   block.cancel_work # => true
+    #
+    # @return [Boolean] signalling if the action was successful
     def cancel_work
       rpc(:work_cancel, :hash).empty?
     end
@@ -49,20 +50,17 @@ class Nanook
     #
     # See also #successors.
     #
-    # ==== Arguments
-    #
-    # [+limit:+] Maximum number of block hashes to return (default is 1000)
-    #
-    # ==== Example
+    # ==== Example:
     #
     #   block.chain(limit: 2)
     #
-    # ==== Example reponse
+    # ==== Example reponse:
     #
     #   [
     #     "36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E",
     #     "FBF8B0E6623A31AB528EBD839EEAA91CAFD25C12294C46754E45FD017F7939EB"
     #   ]
+    # @param limit [Integer] maximum number of block hashes to return (default is 1000)
     def chain(limit: 1000)
       response = rpc(:chain, :block, count: limit)[:blocks]
       Nanook::Util.coerce_empty_string_to_type(response, Array)
@@ -70,9 +68,10 @@ class Nanook
 
     # Generate work for a block.
     #
-    # Returns the work id of the work completed.
-    #
+    # ==== Example:
     #   block.generate_work # => "2bf29ef00786a6bc"
+    #
+    # @return [String] the work id of the work completed.
     def generate_work
       rpc(:work_generate, :hash)[:work]
     end
@@ -80,16 +79,11 @@ class Nanook
     # Returns Array of Hashes containing information about a chain of
     # send/receive blocks, starting from this block.
     #
-    # ==== Arguments
-    #
-    # [+limit:+] Maximum number of send/receive block hashes to return
-    #            in the chain (default is 1000)
-    #
-    # ==== Example
+    # ==== Example:
     #
     #   block.history(limit: 1)
     #
-    # ==== Example response
+    # ==== Example response:
     #
     #   [
     #     {
@@ -99,27 +93,35 @@ class Nanook
     #       :type=>"send"
     #     }
     #   ]
+    #
+    # @param limit [Integer] maximum number of send/receive block hashes
+    #   to return in the chain (default is 1000)
     def history(limit: 1000)
       rpc(:history, :hash, count: limit)[:history]
     end
 
-    # Returns the block hash
+    # Returns the block hash id.
+    #
+    # ==== Example:
     #
     #   block.id #=> "FBF8B0E..."
+    #
+    # @return [String] the block hash id
     def id
       @block
     end
 
     # Returns a Hash of information about the block.
     #
-    # ==== Arguments
+    # ==== Examples:
+    #
+    #   block.info
+    #   block.info(allow_unchecked: true)
     #
-    # [+allow_unchecked:+] Boolean (default is +false+). If +true+,
-    #                      information can be returned about blocks that
-    #                      are unchecked (unverified).
-    # ==== Example response
+    # ==== Example response:
     #
     #   {
+    #     :id=>"36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E",
     #     :type=>"send",
     #     :previous=>"FBF8B0E6623A31AB528EBD839EEAA91CAFD25C12294C46754E45FD017F7939EB",
     #     :destination=>"xrb_3x7cjioqahgs5ppheys6prpqtb4rdknked83chf97bot1unrbdkaux37t31b",
@@ -127,23 +129,28 @@ class Nanook
     #     :work=>"44cc24b60705083a",
     #     :signature=>"42ADFEFE7C3FFF188AE92A202F8A5734DE91779C454613E446EEC93D001D6C953E9FD16730AF32C891791BA8EDAECEB059A213E2FE1EEB7ADF9D5D0815464D06"
     #   }
+    #
+    # @param allow_unchecked [Boolean] (default is +false+). If +true+,
+    #   information can be returned about blocks that are unchecked (unverified).
     def info(allow_unchecked: false)
       if allow_unchecked
-        # TODO not actually sure what this response looks like when it's not an unchecked block, assuming its blank
         response = rpc(:unchecked_get, :hash)
-        if response[:error] != "Block not found"
-          return _parse_info_response(response )
+        unless response.has_key?(:error)
+          return _parse_info_response(response)
         end
-        # Continue on falling backto checked block
+        # If unchecked not found, continue to checked block
       end
 
       response = rpc(:block, :hash)
       _parse_info_response(response)
     end
 
-    # Returns boolean signalling if work is valid for the block.
+    # ==== Example:
     #
     #   block.is_valid_work?("2bf29ef00786a6bc") # => true
+    #
+    # @param work [String] the work id to check is valid
+    # @return [Boolean] signalling if work is valid for the block
     def is_valid_work?(work)
       response = rpc(:work_validate, :hash, work: work)
       !response.empty? && response[:valid] == 1
@@ -152,13 +159,14 @@ class Nanook
     # Republish blocks starting at this block up the account chain
     # back to the nano network.
     #
-    # Returns an Array of block hashes that were republished.
+    # @return [Array<String>] block hashes that were republished
     #
-    # ==== Example
+    # ==== Example:
     #
     #   block.republish
     #
-    # ==== Example response
+    # ==== Example response:
+    #
     #   ["36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E"]
     def republish(destinations:nil, sources:nil)
       if !destinations.nil? && !sources.nil?
@@ -174,9 +182,11 @@ class Nanook
       rpc(:republish, :hash, params)[:blocks]
     end
 
-    # Returns boolean +true+ if the block is a pending block.
+    # ==== Example:
     #
     #   block.pending? #=> false
+    #
+    # @return [Boolean] signalling if the block is a pending block.
     def pending?
       response = rpc(:pending_exists, :hash)
       !response.empty? && response[:exists] == 1
@@ -186,12 +196,13 @@ class Nanook
     #
     # Note, if block has previously been published, use #republish instead.
     #
-    # Returns the block hash, or false.
+    # ==== Examples:
     #
     #   block.publish # => "FBF8B0E..."
+    #
+    # @return [String] the block hash, or false.
     def publish
-      # TODO I think this can return false or error or something?
-      rpc(:process, :block)[:hash]
+      rpc(:process, :block)[:hash] || false
     end
     alias_method :process, :publish
 
@@ -200,24 +211,23 @@ class Nanook
     #
     # See also #chain.
     #
-    # ==== Arguments
-    #
-    # [+limit:+] Maximum number of send/receive block hashes to return
-    #            in the chain (default is 1000)
-    #
-    # ==== Example
+    # ==== Example:
     #
     #   block.successors
     #
-    # ==== Example response
+    # ==== Example response:
     #
     #   ["36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E"]
+    #
+    # @param limit [Integer] maximum number of send/receive block hashes
+    #    to return in the chain (default is 1000)
+    # @return [Array<String>] block hashes in the account chain ending at this block
     def successors(limit: 1000)
       response = rpc(:successors, :block, count: limit)[:blocks]
       Nanook::Util.coerce_empty_string_to_type(response, Array)
     end
 
-    def inspect # :nodoc:
+    def inspect
       "#{self.class.name}(id: \"#{id}\", object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
@@ -240,7 +250,8 @@ class Nanook
     def _parse_info_response(response)
       # The contents is a stringified JSON
       if response[:contents]
-        return JSON.parse(response[:contents]).to_symbolized_hash
+        r = JSON.parse(response[:contents]).to_symbolized_hash
+        return r.merge(id: id)
       end
 
       response

data/lib/nanook/key.rb

@@ -25,7 +25,7 @@ class Nanook
       rpc(:key_expand)
     end
 
-    def inspect # :nodoc:
+    def inspect
       "#{self.class.name}(id: \"#{id}\", object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 

data/lib/nanook/node.rb

@@ -5,6 +5,11 @@ class Nanook
       @rpc = rpc
     end
 
+    def account_count
+      rpc(:frontier_count)[:count]
+    end
+    alias_method :frontier_count, :account_count
+
     def block_count
       rpc(:block_count)
     end
@@ -21,11 +26,7 @@ class Nanook
       rpc(:bootstrap_any).has_key?(:success)
     end
 
-    def frontier_count
-      rpc(:frontier_count)[:count]
-    end
-
-    def inspect # :nodoc:
+    def inspect
       "#{self.class.name}(object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
@@ -41,6 +42,14 @@ class Nanook
       rpc(:stop).has_key?(:success)
     end
 
+    def synchronizing_blocks(limit: 1000)
+      response = rpc(:unchecked, count: limit)[:blocks]
+      response = response.map do |block, info|
+        [block, JSON.parse(info).to_symbolized_hash]
+      end
+      Hash[response.sort].to_symbolized_hash
+    end
+
     def sync_progress
       response = rpc(:block_count)
 

data/lib/nanook/rpc.rb

@@ -8,15 +8,15 @@ class Nanook
     DEFAULT_TIMEOUT = 500 # seconds
 
     def initialize(uri=DEFAULT_URI, timeout:DEFAULT_TIMEOUT)
-      rpc_server = URI(uri)
+      @rpc_server = URI(uri)
 
-      unless ['http', 'https'].include?(rpc_server.scheme)
+      unless ['http', 'https'].include?(@rpc_server.scheme)
         raise ArgumentError.new("URI must have http or https in it. Was given: #{uri}")
       end
 
-      @http = Net::HTTP.new(rpc_server.host, rpc_server.port)
+      @http = Net::HTTP.new(@rpc_server.host, @rpc_server.port)
       @http.read_timeout = timeout
-      @request = Net::HTTP::Post.new(rpc_server.request_uri, {"user-agent" => "Ruby nanook gem"})
+      @request = Net::HTTP::Post.new(@rpc_server.request_uri, {"user-agent" => "Ruby nanook gem"})
       @request.content_type = "application/json"
     end
 
@@ -36,8 +36,8 @@ class Nanook
       end
     end
 
-    def inspect # :nodoc:
-      "#{self.class.name}(host: #{@http.address}, timeout: #{@http.read_timeout} object_id: \"#{"0x00%x" % (object_id << 1)}\")"
+    def inspect
+      "#{self.class.name}(host: \"#{@rpc_server}\", timeout: #{@http.read_timeout} object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
     private

data/lib/nanook/util.rb

@@ -10,11 +10,11 @@ class Nanook
     end
 
     def self.raw_to_NANO(raw)
-      raw.to_f / STEP
+      (raw.to_f / STEP).to_f
     end
 
     def self.coerce_empty_string_to_type(response, type)
-      if response == ""
+      if response == "" || response.nil?
         return type.new
       end
 

data/lib/nanook/version.rb

@@ -1,3 +1,3 @@
 class Nanook
-  VERSION = "1.0.2"
+  VERSION = "2.0.0"
 end

data/lib/nanook/wallet.rb

@@ -20,12 +20,12 @@ class Nanook
   # Initialize this class through the convenient Nanook#wallet method:
   #
   #   nanook = Nanook.new
-  #   wallet = nanook.wallet(wallet_seed)
+  #   wallet = nanook.wallet(wallet_id)
   #
   # Or compose the longhand way like this:
   #
   #   rpc_conn = Nanook::Rpc.new
-  #   wallet = Nanook::Wallet.new(rpc_conn, wallet_seed)
+  #   wallet = Nanook::Wallet.new(rpc_conn, wallet_id)
   class Wallet
 
     def initialize(rpc, wallet)
@@ -58,18 +58,17 @@ class Nanook
       Nanook::WalletAccount.new(@rpc, @wallet, account)
     end
 
-    # Returns an Array with Strings of all account ids in the wallet.
+    # ==== Example:
     #
-    # ==== Example response
+    #   wallet.accounts # => [Nanook::WalletAccount, Nanook::WalletAccount...]
     #
-    #   [
-    #     "xrb_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000",
-    #     "xrb_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx"
-    #   ]
+    # @return [Array<Nanook::WalletAccount>] all accounts in the wallet
     def accounts
       wallet_required!
       response = rpc(:account_list)[:accounts]
-      Nanook::Util.coerce_empty_string_to_type(response, Array)
+      Nanook::Util.coerce_empty_string_to_type(response, Array).map do |account|
+        Nanook::WalletAccount.new(@rpc, @wallet, account)
+      end
     end
 
     # Returns a Hash containing the balance of all accounts in the
@@ -123,10 +122,10 @@ class Nanook
     #       "pending"=>0
     #     },
     #   }
-    def balance(account_break_down: false, unit: Nanook::WalletAccount::DEFAULT_UNIT)
+    def balance(account_break_down: false, unit: Nanook.default_unit)
       wallet_required!
 
-      unless Nanook::WalletAccount::UNITS.include?(unit)
+      unless Nanook::UNITS.include?(unit)
         raise ArgumentError.new("Unsupported unit: #{unit}")
       end
 
@@ -149,31 +148,28 @@ class Nanook
       end
     end
 
-    # Creates a new wallet.
-    #
-    #   Nanook.new.wallet.create
+    # Changes a wallet's seed.
     #
-    # ==== Very important
-    #
-    # <b>Please read this.</b> The response of this method is a wallet seed. A seed is
-    # a 32-byte uppercase hex string. You can think of this string as your
-    # API key to the nano network. The person who knows it can do all read and write
-    # actions against the wallet and all accounts inside the wallet from
-    # anywhere on the nano network, not just on the node you created the
-    # wallet on.
+    # @param seed [String] the seed to change to.
+    # @return [Boolean] indicating whether the change was successful.
+    def change_seed(seed)
+      wallet_required!
+      rpc(:wallet_change_seed, seed: seed).has_key?(:success)
+    end
+
+    # Creates a new wallet.
     #
-    # If you intend for your wallet to contain funds, then make sure that
-    # you consider the seed that is returned as the key to your funds
-    # and store it somewhere secret and safe. Only transmit
-    # the seed over secure (SSH or SSL) networks and do not store it where
-    # it is able to be easily comprised by a hacker, which includes your
-    # personal computer.
+    # The wallet will be created only on this node. It's important that
+    # if you intend to add funds to accounts in this wallet that you
+    # backup the wallet *seed* in order to restore the wallet in future.
     #
-    # ==== Example response:
+    # ==== Example:
+    #   Nanook.new.wallet.create # => Nanook::Wallet
     #
-    #   "CC2C9846A44DB6F0363F647D12B957794AD937F59498D4E35C172C81E2888650"
+    # @return [Nanook::Wallet]
     def create
-      rpc(:wallet_create)[:wallet]
+      @wallet = rpc(:wallet_create)[:wallet]
+      self
     end
 
     # Destroy the wallet. Returns a boolean indicating whether the action
@@ -214,8 +210,9 @@ class Nanook
     def id
       @wallet
     end
+    alias_method :seed, :id
 
-    def inspect # :nodoc:
+    def inspect
       "#{self.class.name}(id: \"#{id}\", object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
@@ -252,12 +249,94 @@ class Nanook
     # Or:
     #
     #   "Account not found"
-    def pay(from:, to:, amount:, unit: Nanook::WalletAccount::DEFAULT_UNIT, id:)
+    def pay(from:, to:, amount:, unit: Nanook.default_unit, id:)
       wallet_required!
       validate_wallet_contains_account!(from)
       account(from).pay(to: to, amount: amount, unit: unit, id: id)
     end
 
+    # Returns information about pending blocks (payments) that are waiting
+    # to be received by accounts in this wallet.
+    #
+    # See also the #receive method of this class for how to receive a pending payment.
+    #
+    # @param limit [Integer] number of accounts with pending payments to return (default is 1000)
+    # @param detailed [Boolean]return a more complex Hash of pending block information (default is +false+)
+    # @param unit (see Nanook::Account#balance)
+    #
+    # ==== Example 1:
+    #
+    #   wallet.pending
+    #
+    # ==== Example 1 response:
+    #   {
+    #     :xrb_1111111111111111111111111111111111111111111111111117353trpda=>[
+    #       "142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D",
+    #       "718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2"
+    #     ],
+    #     :xrb_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3=>[
+    #       "4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74"
+    #     ]
+    #   }
+    # ==== Example 2:
+    #
+    #   wallet.pending(detailed: true)
+    #
+    # ==== Example 2 response:
+    #   {
+    #     :xrb_1111111111111111111111111111111111111111111111111117353trpda=>[
+    #       {
+    #         :amount=>6.0,
+    #         :source=>"xrb_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr",
+    #         :block=>:"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D"
+    #       },
+    #       {
+    #         :amount=>12.0,
+    #         :source=>"xrb_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr",
+    #         :block=>:"242A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D"
+    #       }
+    #     ],
+    #     :xrb_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3=>[
+    #       {
+    #         :amount=>106.370018,
+    #         :source=>"xrb_13ezf4od79h1tgj9aiu4djzcmmguendtjfuhwfukhuucboua8cpoihmh8byo",
+    #         :block=>:"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74"
+    #       }
+    #     ]
+    #   }
+    def pending(limit:1000, detailed:false, unit:Nanook.default_unit)
+      wallet_required!
+
+      unless Nanook::UNITS.include?(unit)
+        raise ArgumentError.new("Unsupported unit: #{unit}")
+      end
+
+      params = { count: limit }
+      params[:source] = true if detailed
+
+      response = rpc(:wallet_pending, params)[:blocks]
+      response = Nanook::Util.coerce_empty_string_to_type(response, Hash)
+
+      return response unless detailed
+
+      # Map the RPC response, which is:
+      # account=>block=>[amount|source] into
+      # account=>[block|amount|source]
+      x = response.map do |account, data|
+        new_data = data.map do |block, amount_and_source|
+          d = amount_and_source.merge(block: block.to_s)
+          if unit == :nano
+            d[:amount] = Nanook::Util.raw_to_NANO(d[:amount])
+          end
+          d
+        end
+
+        [account, new_data]
+      end
+
+      Hash[x].to_symbolized_hash
+    end
+
     # Receives a pending payment into an account in the wallet.
     #
     # When called with no +block+ argument, the latest pending payment
@@ -294,6 +373,33 @@ class Nanook
       account(into).receive(block)
     end
 
+    # Restore a previously created wallet by its seed.
+    # A new wallet will be created on your node (with a new wallet id)
+    # and will have its seed set to the given seed.
+    #
+    # ==== Example:
+    #
+    #   Nanook.new.wallet.restore(seed) # => Nanook::Wallet
+    #
+    # @param seed [String] the wallet seed to restore.
+    # @param accounts [Integer] optionally restore the given number of accounts for the wallet.
+    #
+    # @return [Nanook::Wallet] a new wallet
+    # @raise [Nanook::Error] if unsuccessful
+    def restore(seed, accounts:0)
+      create
+
+      unless change_seed(seed)
+        raise Nanook::Error.new("Unable to set seed for wallet")
+      end
+
+      if accounts > 0
+        account.create(accounts)
+      end
+
+      self
+    end
+
     # Returns a boolean to indicate if the wallet is locked.
     #
     # ==== Example response
@@ -305,23 +411,23 @@ class Nanook
       !response.empty? && response[:locked] != 0
     end
 
-    # Unlocks a previously locked wallet. Returns a boolean to indicate
-    # if the action was successful.
+    # Unlocks a previously locked wallet.
     #
-    # ==== Example response
+    # ==== Example:
     #
-    #   true
+    #   wallet.unlock("new_pass") #=> true
+    # @return [Boolean] indicates if the action was successful
     def unlock(password)
       wallet_required!
       rpc(:password_enter, password: password)[:valid] == 1
     end
 
-    # Changes the password for a wallet. Returns a boolean to indicate
-    # if the action was successful.
+    # Changes the password for a wallet.
     #
-    # ==== Example response
+    # ==== Example:
     #
-    #   true
+    #   wallet.change_password("new_pass") #=> true
+    # @return [Boolean] indicates if the action was successful
     def change_password(password)
       wallet_required!
       rpc(:password_change, password: password)[:changed] == 1