nanook 2.1.0 → 2.5.1

data/lib/nanook/block.rb

@@ -45,8 +45,11 @@ class Nanook
       rpc(:work_cancel, :hash).empty?
     end
 
-    # Returns an Array of block hashes in the account chain starting at
-    # this block.
+    # Returns a consecutive list of block hashes in the account chain
+    # starting at block back to count (direction from frontier back to
+    # open block, from newer blocks to older). Will list all blocks back
+    # to the open block of this chain when count is set to "-1".
+    # The requested block hash is included in the answer.
     #
     # See also #successors.
     #
@@ -60,20 +63,66 @@ class Nanook
     #     "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]
+    # @param offset [Integer] return the account chain block hashes offset by the specified number of blocks (default is 0)
+    def chain(limit: 1000, offset: 0)
+      response = rpc(:chain, :block, count: limit, offset: offset)[:blocks]
       Nanook::Util.coerce_empty_string_to_type(response, Array)
     end
+    alias_method :ancestors, :chain
+
+    # Request confirmation for a block from online representative nodes.
+    # Will return immediately with a boolean to indicate if the request for
+    # confirmation was successful. Note that this boolean does not indicate
+    # the confirmation status of the block. If confirmed, your block should
+    # appear in {Nanook::Node#confirmation_history} within a short amount of
+    # time, or you can use the convenience method {Nanook::Block#confirmed_recently?}
+    #
+    # ==== Example:
+    #   block.confirm # => true
+    #
+    # @return [Boolean] if the confirmation request was sent successful
+    def confirm
+      rpc(:block_confirm, :hash)[:started] == 1
+    end
+
+    # This call is for internal diagnostics/debug purposes only. Do not
+    # rely on this interface being stable and do not use in a production system.
+    #
+    # Check if the block appears in the list of recently confirmed blocks by
+    # online representatives. The full list of blocks can be queried for with {Nanook::Node#confirmation_history}.
+    #
+    # This method can work in conjunction with {Nanook::Block#confirm},
+    # whereby you can send any block (old or new) out to online representatives to
+    # confirm. The confirmation process can take up to a couple of minutes.
+    #
+    # The method returning +false+ can indicate that the block is still in the process of being
+    # confirmed and that you should call the method again soon, or that it
+    # was confirmed earlier than the list available in {Nanook::Node#confirmation_history},
+    # or that it was not confirmed.
+    #
+    # ==== Example:
+    #   block.confirmed_recently? # => true
+    #
+    # @return [Boolean] +true+ if the block has been recently confirmed by
+    #   online representatives.
+    def confirmed_recently?
+      @rpc.call(:confirmation_history)[:confirmations].map{|h| h[:hash]}.include?(@block)
+    end
+    alias_method :recently_confirmed?, :confirmed_recently?
 
     # Generate work for a block.
     #
     # ==== Example:
     #   block.generate_work # => "2bf29ef00786a6bc"
     #
+    # @param use_peers [Boolean] if set to +true+, then the node will query
+    #   its work peers (if it has any, see {Nanook::WorkPeer#list}).
+    #   When +false+, the node will only generate work locally (default is +false+)
     # @return [String] the work id of the work completed.
-    def generate_work
-      rpc(:work_generate, :hash)[:work]
+    def generate_work(use_peers: false)
+      rpc(:work_generate, :hash, use_peers: use_peers)[:work]
     end
 
     # Returns Array of Hashes containing information about a chain of
@@ -87,7 +136,7 @@ class Nanook
     #
     #   [
     #     {
-    #       :account=>"xrb_3x7cjioqahgs5ppheys6prpqtb4rdknked83chf97bot1unrbdkaux37t31b",
+    #       :account=>"nano_3x7cjioqahgs5ppheys6prpqtb4rdknked83chf97bot1unrbdkaux37t31b",
     #       :amount=>539834279601145558517940224,
     #       :hash=>"36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E",
     #       :type=>"send"
@@ -124,7 +173,7 @@ class Nanook
     #     :id=>"36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E",
     #     :type=>"send",
     #     :previous=>"FBF8B0E6623A31AB528EBD839EEAA91CAFD25C12294C46754E45FD017F7939EB",
-    #     :destination=>"xrb_3x7cjioqahgs5ppheys6prpqtb4rdknked83chf97bot1unrbdkaux37t31b",
+    #     :destination=>"nano_3x7cjioqahgs5ppheys6prpqtb4rdknked83chf97bot1unrbdkaux37t31b",
     #     :balance=>"00000000000000000000000000000000",
     #     :work=>"44cc24b60705083a",
     #     :signature=>"42ADFEFE7C3FFF188AE92A202F8A5734DE91779C454613E446EEC93D001D6C953E9FD16730AF32C891791BA8EDAECEB059A213E2FE1EEB7ADF9D5D0815464D06"
@@ -220,10 +269,12 @@ class Nanook
     #   ["36A0FB717368BA8CF8D255B63DC207771EABC6C6FFC22A7F455EC2209464897E"]
     #
     # @param limit [Integer] maximum number of send/receive block hashes
-    #    to return in the chain (default is 1000)
+    #   to return in the chain (default is 1000)
+    # @param offset [Integer] return the account chain block hashes offset
+    #   by the specified number of blocks (default is 0)
     # @return [Array<String>] block hashes in the account chain ending at this block
-    def successors(limit: 1000)
-      response = rpc(:successors, :block, count: limit)[:blocks]
+    def successors(limit: 1000, offset: 0)
+      response = rpc(:successors, :block, count: limit, offset: offset)[:blocks]
       Nanook::Util.coerce_empty_string_to_type(response, Array)
     end
 

data/lib/nanook/error.rb

@@ -1,4 +1,5 @@
 class Nanook
+  # Standard error for Nanook
   class Error < StandardError
   end
 end

data/lib/nanook/node.rb

@@ -1,31 +1,220 @@
 class Nanook
+
+  # The <tt>Nanook::Node</tt> class contains methods to manage your nano
+  # node and query its data of the nano network.
+  #
+  # Your node is constantly syncing data with other nodes on the network. When
+  # your node first starts up after being built, its database will be empty
+  # and it will begin synchronizing and downloading data of the nano ledger
+  # to its local database. The ledger is the central record of all accounts
+  # and transactions. Some of the methods in this class query your node's
+  # database formed from the nano ledger, and so the responses are determined
+  # by the completeness of your node's database.
+  #
+  # You can determine how synchronized your node is with the nano ledger
+  # with the {#sync_progress} method.
+  #
+  # === Initializing
+  #
+  # Initialize this class through the convenient {Nanook#node} method:
+  #
+  #   node = Nanook.new.node
+  #
+  # Or compose the longhand way like this:
+  #
+  #   rpc_conn = Nanook::Rpc.new
+  #   node = Nanook::Node.new(rpc_conn)
   class Node
 
     def initialize(rpc)
       @rpc = rpc
     end
 
+    # The number of accounts in the nano ledger--essentially all
+    # accounts with _open_ blocks. An _open_ block
+    # is the type of block written to the nano ledger when an account
+    # receives its first payment (see {Nanook::WalletAccount#receive}). All accounts
+    # that respond +true+ to {Nanook::Account#exists?} have open blocks in the ledger.
+    #
+    # @return [Integer] number of accounts with _open_ blocks.
     def account_count
       rpc(:frontier_count)[:count]
     end
     alias_method :frontier_count, :account_count
 
+    # The count of all blocks downloaded to the node, and
+    # blocks still to be synchronized by the node.
+    #
+    # ==== Example:
+    #
+    #
+    #
+    # @return [Hash{Symbol=>Integer}] number of blocks and unchecked
+    #   synchronizing blocks
     def block_count
       rpc(:block_count)
     end
 
-    def block_count_type
+    # The count of all known blocks by their type.
+    #
+    # ==== Example:
+    #
+    #   node.block_count_by_type
+    #
+    # Example response:
+    #
+    #   {
+    #     send: 1000,
+    #     receive: 900,
+    #     open: 900,
+    #     change: 50
+    #   }
+    #
+    # @return [Hash{Symbol=>Integer}] number of blocks by type
+    def block_count_by_type
       rpc(:block_count_type)
     end
+    alias_method :block_count_type, :block_count_by_type
 
+    # Initialize bootstrap to a specific IP address and port.
+    #
+    # @return [Boolean] indicating if the action was successful
     def bootstrap(address:, port:)
       rpc(:bootstrap, address: address, port: port).has_key?(:success)
     end
 
+    # Initialize multi-connection bootstrap to random peers
+    #
+    # @return [Boolean] indicating if the action was successful
     def bootstrap_any
       rpc(:bootstrap_any).has_key?(:success)
     end
 
+    # Initialize lazy bootstrap with given block hash
+    #
+    # @param hash [String]
+    # @param force [Boolean] False by default. Manually force closing
+    #   of all current bootstraps
+    # @return [Boolean] indicating if the action was successful
+    def bootstrap_lazy(hash, force: false)
+      rpc(:bootstrap_lazy, hash: hash, force: force)[:started] == 1
+    end
+
+    # Returning status of current bootstrap attempt for debug purposes only.
+    # This call is for internal diagnostics/debug purposes only.
+    # Do not rely on this interface being stable and do not use in a
+    # production system.
+    #
+    # ==== Example:
+    #
+    #   node.bootstrap_status
+    #
+    # Example response:
+    #
+    #   {
+    #     clients: 5790,
+    #     pulls: 141065,
+    #     pulling: 3,
+    #     connections: 16,
+    #     idle: 0,
+    #     target_connections: 64,
+    #     total_blocks: 536820,
+    #     lazy_mode: true,
+    #     lazy_blocks: 423388,
+    #     lazy_state_unknown: 2,
+    #     lazy_balances: 0,
+    #     lazy_pulls: 0,
+    #     lazy_stopped: 644,
+    #     lazy_keys: 449,
+    #     lazy_key_1: "A86EB2B479AAF3CD531C8356A1FBE3CB500DFBF5BF292E5E6B8D1048DE199C32"
+    #   }
+    #
+    # @return [Hash{Symbol=>String|Integer|Boolean}]
+    def bootstrap_status
+      rpc(:bootstrap_status)
+    end
+
+    # This call is for internal diagnostics/debug purposes only.
+    # Do not rely on this interface being stable and do not use in a
+    # production system.
+    #
+    # Returns block and tally weight (in raw) election duration (in
+    # milliseconds), election confirmation timestamp for recent elections
+    # winners.
+    #
+    # ==== Example:
+    #
+    #   node.confirmation_history
+    #
+    # Example response:
+    #
+    #   [
+    #     {
+    #       block: "EA70B32C55C193345D625F766EEA2FCA52D3F2CCE0B3A30838CC543026BB0FEA",
+    #       tally: 80394786589602980996311817874549318248,
+    #       duration: 4000,
+    #       time: 1544819986,
+    #     },
+    #     {
+    #       block: "F2F8DA6D2CA0A4D78EB043A7A29E12BDE5B4CE7DE1B99A93A5210428EE5B8667",
+    #       tally: 68921714529890443063672782079965877749,
+    #       duration: 6000,
+    #       time: 1544819988,
+    #     }
+    #   ]
+    #
+    # @return [Hash{Symbol=>String|Integer}]
+    def confirmation_history
+      rpc(:confirmation_history)[:confirmations].map do |history|
+        # Rename hash key to block
+        block = history.delete(:hash)
+        {block: block}.merge(history)
+      end
+    end
+
+    # Returns the difficulty values (16 hexadecimal digits string, 64 bit)
+    # for the minimum required on the network (network_minimum) as well
+    # as the current active difficulty seen on the network (network_current,
+    # 5 minute trended average of adjusted difficulty seen on confirmed
+    # transactions) which can be used to perform rework for better
+    # prioritization of transaction processing. A multiplier of the
+    # network_current from the base difficulty of network_minimum is also
+    # provided for comparison.
+    #
+    # ==== Example:
+    #
+    #   node.difficulty(include_trend: true)
+    #
+    # Example response:
+    #
+    #   {
+    #     network_minimum: "ffffffc000000000",
+    #     network_current: "ffffffc1816766f2",
+    #     multiplier: 1.024089858417128,
+    #     difficulty_trend: [
+    #       1.156096135149775,
+    #       1.190133894573061,
+    #       1.135567138563921,
+    #       1.000000000000000,
+    #     ]
+    #   }
+    #
+    # @param include_trend [Boolean] false by default. Also returns the
+    #   trend of difficulty seen on the network as a list of multipliers.
+    #   Sampling occurs every 16 to 36 seconds. The list is ordered such
+    #   that the first value is the most recent sample.
+    # @return [Hash{Symbol=>String|Float|Array}]
+    def difficulty(include_trend: false)
+      rpc(:active_difficulty, include_trend: include_trend).tap do |response|
+        response[:multiplier] = response[:multiplier].to_f
+
+        if response.key?(:difficulty_trend)
+          response[:difficulty_trend].map!(&:to_f)
+        end
+      end
+    end
+
+    # @return [String]
     def inspect
       "#{self.class.name}(object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
@@ -34,14 +223,60 @@ class Nanook
       rpc(:peers)[:peers]
     end
 
-    def representatives
-      rpc(:representatives)[:representatives]
+    # All representatives and their voting weight.
+    #
+    # ==== Example:
+    #
+    #   node.representatives
+    #
+    # Example response:
+    #
+    #   {
+    #     nano_1111111111111111111111111111111111111111111111111117353trpda: 3822372327060170000000000000000000000,
+    #     nano_1111111111111111111111111111111111111111111111111awsq94gtecn: 30999999999999999999999999000000,
+    #     nano_114nk4rwjctu6n6tr6g6ps61g1w3hdpjxfas4xj1tq6i8jyomc5d858xr1xi: 0
+    #   }
+    #
+    # @return [Hash{Symbol=>Integer}] known representatives and their voting weight
+    def representatives(unit: Nanook.default_unit)
+      unless Nanook::UNITS.include?(unit)
+        raise ArgumentError.new("Unsupported unit: #{unit}")
+      end
+
+      response = rpc(:representatives)[:representatives]
+      return response if unit == :raw
+
+      r = response.map do |account_id, balance|
+        balance = Nanook::Util.raw_to_NANO(balance)
+
+        [account_id, balance]
+      end
+
+      Hash[r].to_symbolized_hash
+    end
+
+    # All online representatives that have voted recently. Note, due to the
+    # design of the nano RPC, this method cannot return the voting weight
+    # of the representatives.
+    #
+    # ==== Example:
+    #
+    #   node.representatives_online # => ["nano_111...", "nano_222"]
+    #
+    # @return [Array<String>] array of representative account ids
+    def representatives_online
+      rpc(:representatives_online)[:representatives].keys.map(&:to_s)
     end
 
+    # Safely shuts down the node.
+    #
+    # @return [Boolean] indicating if action was successful
     def stop
       rpc(:stop).has_key?(:success)
     end
 
+    # @param limit [Integer] number of synchronizing blocks to return
+    # @return [Hash{Symbol=>String}] information about the synchronizing blocks for this node
     def synchronizing_blocks(limit: 1000)
       response = rpc(:unchecked, count: limit)[:blocks]
       response = response.map do |block, info|
@@ -49,7 +284,16 @@ class Nanook
       end
       Hash[response.sort].to_symbolized_hash
     end
+    alias_method :unchecked, :synchronizing_blocks
 
+    # The percentage completeness of the synchronization process for
+    # your node as it downloads the nano ledger. Note, it's normal for
+    # your progress to not ever reach 100. The closer to 100, the more
+    # complete your node's data is, and so the query methods in this class
+    # become more reliable.
+    #
+    # @return [Float] the percentage completeness of the synchronization
+    #   process for your node
     def sync_progress
       response = rpc(:block_count)
 
@@ -60,13 +304,27 @@ class Nanook
       count.to_f * 100 / total.to_f
     end
 
+    # Returns node uptime in seconds
+    #
+    # @return [Integer] seconds of uptime
+    def uptime
+      rpc(:uptime)['seconds']
+    end
+
+    # This method is deprecated and will be removed in 3.0, as a node never
+    # reaches 100% synchronization.
+    #
+    # @return [Boolean] signalling if this node ever reaches 100% synchronized
     def synced?
+      warn "[DEPRECATION] `synced?` is deprecated and will be removed in 3.0"
       rpc(:block_count)[:unchecked] == 0
     end
 
+    # @return [Hash{Symbol=>Integer|String}] version information for this node
     def version
       rpc(:version)
     end
+    alias_method :info, :version
 
     private