nanook 2.4.0 → 3.1.0

data/lib/nanook/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class Nanook
+  Error = Class.new(StandardError)
+
+  ConnectionError = Class.new(Error)
+  NanoUnitError = Class.new(Error)
+  NodeRpcError = Class.new(Error)
+  NodeRpcConfigurationError = Class.new(NodeRpcError)
+end

data/lib/nanook/node.rb

@@ -1,5 +1,8 @@
-class Nanook
+# frozen_string_literal: true
+
+require_relative 'util'
 
+class Nanook
   # The <tt>Nanook::Node</tt> class contains methods to manage your nano
   # node and query its data of the nano network.
   #
@@ -25,6 +28,7 @@ class Nanook
   #   rpc_conn = Nanook::Rpc.new
   #   node = Nanook::Node.new(rpc_conn)
   class Node
+    include Nanook::Util
 
     def initialize(rpc)
       @rpc = rpc
@@ -38,93 +42,162 @@ class Nanook
     #
     # @return [Integer] number of accounts with _open_ blocks.
     def account_count
-      rpc(:frontier_count)[:count]
+      rpc(:frontier_count, _access: :count)
     end
-    alias_method :frontier_count, :account_count
+    alias frontier_count account_count
 
     # The count of all blocks downloaded to the node, and
     # blocks still to be synchronized by the node.
     #
     # ==== Example:
     #
-    #
+    #   {
+    #     count: 100,
+    #     unchecked: 10,
+    #     cemented: 25
+    #   }
     #
     # @return [Hash{Symbol=>Integer}] number of blocks and unchecked
     #   synchronizing blocks
     def block_count
-      rpc(:block_count)
+      rpc(:block_count, _coerce: Hash)
     end
 
-    # The count of all known blocks by their type.
-    #
-    # ==== Example:
+    # Tells the node to send a keepalive packet to a specific IP address and port.
     #
-    #   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)
+    # @return [Boolean] indicating if the action was successful
+    def keepalive(address:, port:)
+      rpc(:keepalive, address: address, port: port).key?(:started)
     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)
+      rpc(:bootstrap, address: address, port: port).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)
+      rpc(:bootstrap_any).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, _access: :started) == 1
     end
 
-    # Returns block and tally weight (in raw) for recent elections winners
+    # Returns information about node elections settings and observed network state:
+    #
+    # - `quorum_delta`: delta tally required to rollback block
+    # - `online_weight_quorum_percent`: percentage of online weight for delta
+    # - `online_weight_minimum`: minimum online weight to confirm block
+    # - `online_stake_total`: currently observed online total weight
+    # - `peers_stake_total`: known peers total weight
+    # - `peers_stake_required`: effective stake needed from directly connected peers for quorum
     #
     # ==== Example:
     #
-    #   node.confirmation_history
+    #   node.confirmation_quorum
     #
     # Example response:
     #
-    #   [
-    #     {
-    #       block: "EA70B32C55C193345D625F766EEA2FCA52D3F2CCE0B3A30838CC543026BB0FEA",
-    #       tally: 80394786589602980996311817874549318248
-    #     },
-    #     {
-    #       block: "F2F8DA6D2CA0A4D78EB043A7A29E12BDE5B4CE7DE1B99A93A5210428EE5B8667",
-    #       tally: 68921714529890443063672782079965877749
-    #     }
-    #   ]
+    #   {
+    #     "quorum_delta": 43216377.43025059,
+    #     "online_weight_quorum_percent": 50,
+    #     "online_weight_minimum": 60000000.0",
+    #     "online_stake_total": 86432754.86050119,
+    #     "peers_stake_total": 84672338.52479072,
+    #     "peers_stake_required": 60000000.0"
+    #   }
     #
     # @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)
+    # @raise [Nanook::NanoUnitError] if `unit` is invalid
+    def confirmation_quorum(unit: Nanook.default_unit)
+      validate_unit!(unit)
+
+      response = rpc(:confirmation_quorum, _coerce: Hash)
+
+      return response unless unit == :nano
+
+      response[:quorum_delta] = raw_to_NANO(response[:quorum_delta])
+      response[:online_weight_minimum] = raw_to_NANO(response[:online_weight_minimum])
+      response[:online_stake_total] = raw_to_NANO(response[:online_stake_total])
+      response[:peers_stake_total] = raw_to_NANO(response[:peers_stake_total])
+      response[:peers_stake_required] = raw_to_NANO(response[:peers_stake_required])
+
+      response.compact
+    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, _coerce: Hash).tap do |response|
+        response[:multiplier] = response[:multiplier].to_f
+
+        response[:difficulty_trend].map!(&:to_f) if response.key?(:difficulty_trend)
       end
     end
 
     # @return [String]
-    def inspect
-      "#{self.class.name}(object_id: \"#{"0x00%x" % (object_id << 1)}\")"
+    def to_s
+      self.class.name
     end
+    alias inspect to_s
 
+    # Returns peers information.
+    #
+    # Example response:
+    #
+    #   {
+    #     :"[::ffff:104.131.102.132]:7075" => {
+    #       protocol_version: 20,
+    #       node_id: "node_1y7j5rdqhg99uyab1145gu3yur1ax35a3b6qr417yt8cd6n86uiw3d4whty3",
+    #       type: "udp"
+    #     },
+    #     :"[::ffff:104.131.114.102]:7075" => { ... }
+    #   }
+    #
+    # @return [Hash{Symbol=>Hash{Symbol=>Integer|String}}]
     def peers
-      rpc(:peers)[:peers]
+      rpc(:peers, peer_details: true, _access: :peers, _coerce: Hash)
     end
 
     # All representatives and their voting weight.
@@ -136,59 +209,86 @@ class Nanook
     # Example response:
     #
     #   {
-    #     xrb_1111111111111111111111111111111111111111111111111117353trpda: 3822372327060170000000000000000000000,
-    #     xrb_1111111111111111111111111111111111111111111111111awsq94gtecn: 30999999999999999999999999000000,
-    #     xrb_114nk4rwjctu6n6tr6g6ps61g1w3hdpjxfas4xj1tq6i8jyomc5d858xr1xi: 0
+    #     Nanook::Account: 3822372327060170000000000000000000000,
+    #     Nanook::Account: 30999999999999999999999999000000,
+    #     Nanook::Account: 0
     #   }
     #
-    # @return [Hash{Symbol=>Integer}] known representatives and their voting weight
+    # @return [Hash{Nanook::Account=>Float|Integer}] known representatives and their voting weight
+    # @raise [Nanook::NanoUnitError] if `unit` is invalid
     def representatives(unit: Nanook.default_unit)
-      unless Nanook::UNITS.include?(unit)
-        raise ArgumentError.new("Unsupported unit: #{unit}")
-      end
+      validate_unit!(unit)
 
-      response = rpc(:representatives)[:representatives]
-      return response if unit == :raw
+      response = rpc(:representatives, _access: :representatives, _coerce: Hash)
 
-      r = response.map do |account_id, balance|
-        balance = Nanook::Util.raw_to_NANO(balance)
+      r = response.map do |account_id, weight|
+        weight = raw_to_NANO(weight) if unit == :nano
 
-        [account_id, balance]
+        [as_account(account_id), weight]
       end
 
-      Hash[r].to_symbolized_hash
+      Hash[r]
     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.
+    # All online representatives that have voted recently and their weight.
     #
     # ==== Example:
     #
-    #   node.representatives_online # => ["xrb_111...", "xrb_222"]
+    #   node.representatives_online # => [Nanook::Account, ...]
     #
-    # @return [Array<String>] array of representative account ids
+    # @return [Nanook::Account] array of representative accounts
     def representatives_online
-      rpc(:representatives_online)[:representatives].keys.map(&:to_s)
+      rpc(:representatives_online, _access: :representatives, _coerce: Array).map do |representative|
+        as_account(representative)
+      end
+    end
+
+    # Tells the node to look for any account in all available wallets.
+    #
+    # ==== Example:
+    #
+    #   node.search_pending #=> true
+    # @return [Boolean] indicates if the action was successful
+    def search_pending
+      rpc(:search_pending_all).key?(:success)
     end
 
     # Safely shuts down the node.
     #
     # @return [Boolean] indicating if action was successful
     def stop
-      rpc(:stop).has_key?(:success)
+      rpc(:stop).key?(:success)
     end
 
     # @param limit [Integer] number of synchronizing blocks to return
+    # @param unit (see Nanook::Account#balance)
+    #
     # @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|
-        [block, JSON.parse(info).to_symbolized_hash]
+    # @raise [Nanook::NanoUnitError] if `unit` is invalid
+    def synchronizing_blocks(limit: 1000, unit: Nanook.default_unit)
+      validate_unit!(unit)
+
+      params = {
+        count: limit,
+        json_block: true,
+        _access: :blocks,
+        _coerce: Hash
+      }
+
+      response = rpc(:unchecked, params).map do |block, info|
+        info[:account] = as_account(info[:account]) if info[:account]
+        info[:link_as_account] = as_account(info[:link_as_account]) if info[:link_as_account]
+        info[:representative] = as_account(info[:representative]) if info[:representative]
+        info[:previous] = as_block(info[:previous]) if info[:previous]
+        info[:link] = as_block(info[:link]) if info[:link]
+        info[:balance] = raw_to_NANO(info[:balance]) if unit == :nano && info[:balance]
+
+        [as_block(block), info]
       end
-      Hash[response.sort].to_symbolized_hash
+
+      Hash[response]
     end
-    alias_method :unchecked, :synchronizing_blocks
+    alias unchecked synchronizing_blocks
 
     # The percentage completeness of the synchronization process for
     # your node as it downloads the nano ledger. Note, it's normal for
@@ -199,35 +299,70 @@ class Nanook
     # @return [Float] the percentage completeness of the synchronization
     #   process for your node
     def sync_progress
-      response = rpc(:block_count)
+      response = rpc(:block_count, _coerce: Hash)
 
       count = response[:count]
       unchecked = response[:unchecked]
-      total =  count + unchecked
+      total = count + unchecked
 
       count.to_f * 100 / total.to_f
     end
 
-    # This method is deprecated and will be removed in 3.0, as a node never
-    # reaches 100% synchronization.
+    # Returns node uptime in seconds
+    #
+    # @return [Integer] seconds of uptime
+    def uptime
+      rpc(:uptime, _access: :seconds, _coerce: Hash)
+    end
+
+    # Sets the receive minimum for wallets on the node. The value is in +Nano+ by default.
+    # To specify an amount in +raw+, pass the argument +unit: :raw+.
+    #
+    # ==== Example:
+    #
+    #   account.change_receive_minimum(0.01) # true
     #
-    # @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
+    # @return [Boolean] true if the action was successful
+    # @param minimum Amount to set as the receive minimum
+    # @param unit optional. Specify +raw+ if you want to set the amount in +raw+. (See Nanook::Account#balance)
+    # @raise [Nanook::NanoUnitError] if `unit` is invalid
+    def change_receive_minimum(minimum, unit: Nanook.default_unit)
+      validate_unit!(unit)
+
+      minimum = NANO_to_raw(minimum) if unit == :nano
+
+      rpc(:receive_minimum_set, amount: minimum).key?(:success)
+    end
+
+    # Returns receive minimum for wallets on the node.
+    #
+    # ==== Example:
+    #
+    #   account.receive_minimum # => 0.01
+    #
+    # @return [Integer|Float] the receive minimum
+    # @param unit (see Nanook::Account#balance)
+    # @raise [Nanook::NanoUnitError] if `unit` is invalid
+    def receive_minimum(unit: Nanook.default_unit)
+      validate_unit!(unit)
+
+      amount = rpc(:receive_minimum, _access: :amount)
+
+      return amount unless unit == :nano
+
+      raw_to_NANO(amount)
     end
 
     # @return [Hash{Symbol=>Integer|String}] version information for this node
     def version
-      rpc(:version)
+      rpc(:version, _coerce: Hash)
     end
-    alias_method :info, :version
+    alias info version
 
     private
 
-    def rpc(action, params={})
+    def rpc(action, params = {})
       @rpc.call(action, params)
     end
-
   end
 end

data/lib/nanook/private_key.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative 'util'
+
+class Nanook
+  # The <tt>Nanook::PrivateKey</tt> class lets you manage your node's keys.
+  class PrivateKey
+    include Nanook::Util
+
+    def initialize(rpc, key = nil)
+      @rpc = rpc
+      @key = key.to_s if key
+    end
+
+    def id
+      @key
+    end
+
+    # @param other [Nanook::PrivateKey] private key to compare
+    # @return [Boolean] true if keys are equal
+    def ==(other)
+      other.class == self.class &&
+        other.id == id
+    end
+    alias eql? ==
+
+    # The hash value is used along with #eql? by the Hash class to determine if two objects
+    # reference the same hash key.
+    #
+    # @return [Integer]
+    def hash
+      id.hash
+    end
+
+    # Generate a new private public key pair. Returns the new {Nanook::PrivateKey}.
+    # The public key can be retrieved by calling `#public_key` on the private key.
+    #
+    # ==== Examples:
+    #
+    #   private_key = nanook.private_key.create
+    #   private_key.public_key # => Nanook::PublicKey pair for the private key
+    #
+    #   deterministic_private_key = nanook.private_key.create(seed: seed, index: 0)
+    #
+    # @param seed [String] optional seed to generate a deterministic private key.
+    # @param index [Integer] optional (but required if +seed+ is given) index to generate a deterministic private key.
+    # @return Nanook::PrivateKey
+    def create(seed: nil, index: nil)
+      skip_key_required!
+
+      params = {
+        _access: :private,
+        _coerce: Hash
+      }
+
+      @key = if seed.nil?
+               rpc(:key_create, params)
+             else
+               raise ArgumentError, 'index argument is required when seed is given' if index.nil?
+
+               rpc(:deterministic_key, params.merge(seed: seed, index: index))
+             end
+
+      self
+    end
+
+    # Returns the {Nanook::Account} that matches this private key. The
+    # account may not exist yet in the ledger.
+    #
+    # @return Nanook::Account
+    def account
+      as_account(memoized_key_expand[:account])
+    end
+
+    # Returns the {Nanook::PublicKey} pair for this private key.
+    #
+    # @return Nanook::PublicKey
+    def public_key
+      as_public_key(memoized_key_expand[:public])
+    end
+
+    # @return [String]
+    def to_s
+      "#{self.class.name}(id: \"#{short_id}\")"
+    end
+    alias inspect to_s
+
+    private
+
+    def memoized_key_expand
+      @memoized_key_expand ||= rpc(:key_expand, _coerce: Hash)
+    end
+
+    def rpc(action, params = {})
+      check_key_required!
+
+      p = { key: @key }.compact
+      @rpc.call(action, p.merge(params)).tap { reset_skip_key_required! }
+    end
+
+    def skip_key_required!
+      @skip_key_required_check = true
+    end
+
+    def reset_skip_key_required!
+      @skip_key_required_check = false
+    end
+
+    def check_key_required!
+      return if @key || @skip_key_required_check
+
+      raise ArgumentError, 'Key must be present'
+    end
+  end
+end