nanook 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f71938ce617e3ee52fe2fb04cf9eebe97191f5d5
-  data.tar.gz: 210a3c2b1ce7ad7b767c0139eaf5ae153c9e8fda
+  metadata.gz: e1c2a7e556469efac09a609f78e8f3a4e0533a89
+  data.tar.gz: 12d86898565f21e0c483c891be2b36f1c838216e
 SHA512:
-  metadata.gz: 68baffb5984f1509bf4b1e6889b8c378906db8a41c070afc22902fb3369be03ee8b6db36dabb70befd79562f938380b74193a2007b033f6d2d25273871fbaa96
-  data.tar.gz: a6610e8c5d616b48940d4c2837bd0cc6974d84d3b6c20418eb22543719740f353bd4c5c59ef86990dd8fe75b5c0b6c9e1386beb64b505a3784298a4fd77fa24c
+  metadata.gz: 47b9839217c59af70980fb20b1f8cefe716654170d15c908dc25f24bcba7ba34ef8b9bc5dc0b50912b447e6a779d022dbc264b2a469219c383fae754d8828843
+  data.tar.gz: 94d4e68c2a9a8debbd06c48b98e3b30d8ec2fac6d567e5c40dba50044c82cd894b11051b9b7df32ae818dbc830b1a27b2826b0a5267e959f415dd9e90c2069bb

data/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 2.1.0
+
+- Payment methods check the account id of the recipient is valid, raises ArgumentError if not.
+
 ## 2.0.0
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ This is a Ruby library for managing a [nano currency](https://nano.org/) node, i
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'nanook', "~> 2.0"
+gem 'nanook', "~> 2.1"
 ```
 
 And then execute:
@@ -120,7 +120,7 @@ wallet.receive(block_id, into: account_id)
 
 ## All commands
 
-Below is a quick reference list of commands. See the [full Nanook documentation](https://lukes.github.io/nanook/2.0.0/) for a searchable detailed description of every class and method, what the arguments mean, and example responses (Tip: expand the "**Nanook** < Object" item in the sidebar).
+Below is a quick reference list of commands. See the [full Nanook documentation](https://lukes.github.io/nanook/2.0.0/) for a searchable detailed description of every class and method, what the arguments mean, and example responses (Tip: the classes are listed under the "**Nanook** < Object" item in the sidebar).
 
 ### Wallets
 

data/lib/nanook.rb

@@ -1,5 +1,6 @@
 require 'net/http'
 require 'uri'
+require 'forwardable'
 
 Dir[File.dirname(__FILE__) + '/nanook/*.rb'].each {|file| require file }
 

data/lib/nanook/account.rb

@@ -133,20 +133,25 @@ class Nanook
 
     # Returns a Hash containing the account's balance.
     #
-    # ==== Example response:
-    #   {
-    #     balance=>2,   # Account balance
-    #     pending=>1.1  # Amount pending and not yet received by the account
-    #   }
+    # ==== Example:
+    #
+    #   account.balance
+    #
+    #   # =>
+    #   # {
+    #   #   balance=>2,   # Account balance
+    #   #   pending=>1.1  # Amount pending and not yet received by the account
+    #   # }
     #
     # ==== Example balance returned in raw:
     #
     #   account.balance(unit: :raw)
     #
-    #   {
-    #     balance: 2000000000000000000000000000000,
-    #     pending: 1100000000000000000000000000000
-    #   }
+    #   # =>
+    #   # {
+    #   #   balance: 2000000000000000000000000000000,
+    #   #   pending: 1100000000000000000000000000000
+    #   # }
     #
     # @param unit [Symbol] default is {Nanook.default_unit}.
     #   Must be one of {Nanook::UNITS}.

data/lib/nanook/version.rb

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

data/lib/nanook/wallet.rb

@@ -207,32 +207,20 @@ class Nanook
       !response.empty? && response[:exists] == 1
     end
 
+    # @return [String]
     def id
       @wallet
     end
     alias_method :seed, :id
 
+    # @return [String]
     def inspect
       "#{self.class.name}(id: \"#{id}\", object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
     # Make a payment from an account in your wallet to another account
-    # on the nano network. Returns a <i>send</i> block hash if successful,
-    # or an error String if unsuccessful.
-    #
-    # ==== Arguments
-    #
-    # [+from:+]   String account id of an account in your wallet
-    # [+to:+]     String account id of the recipient of your payment
-    # [+amount:+] Can be either an Integer or Float.
-    # [+unit:+]   Symbol (default is +:nano+). Represents the unit that +amount+ is in.
-    #             Must be either +:nano+ or +:raw+. (Note: this method
-    #             interprets +:nano+ as NANO, which is technically Mnano
-    #             See {What are Nano's Units}[https://nano.org/en/faq#what-are-nano-units-])
-    # [+id:+]     String. Must be unique per payment. It serves an important
-    #             purpose; it allows you to make the same call multiple
-    #             times with the same +id+ and be reassured that you will
-    #             only ever send that nano payment once.
+    # on the nano network. Returns a <i>send</i> block id
+    # if successful, or a {Nanook::Error} if unsuccessful.
     #
     # Note, there may be a delay in receiving a response due to Proof of Work being done. From the {Nano RPC}[https://github.com/nanocurrency/raiblocks/wiki/RPC-protocol#account-create]:
     #
@@ -240,15 +228,17 @@ class Nanook
     #
     # ==== Examples
     #
-    #   wallet.pay(from: "xrb_...", to: "xrb_...", amount: 1.1, id: "myUniqueId123")
-    #   wallet.pay(from: "xrb_...", to: "xrb_...", amount: 54000000000000, unit: :raw, id: "myUniqueId123")
+    #   wallet.pay(from: "xrb_...", to: "xrb_...", amount: 1.1, id: "myUniqueId123") # => "9AE2311..."
+    #   wallet.pay(from: "xrb_...", to: "xrb_...", amount: 54000000000000, unit: :raw, id: "myUniqueId123") # => "9AE2311..."
     #
-    # ==== Example responses
-    #   "718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2"
-    #
-    # Or:
+    # ==== Arguments
     #
-    #   "Account not found"
+    # @param from [String] account id of an account in your wallet
+    # @param to (see Nanook::WalletAccount#pay)
+    # @param amount (see Nanook::WalletAccount#pay)
+    # @param unit (see Nanook::Account#balance)
+    # @params id (see Nanook::WalletAccount#pay)
+    # @return (see Nanook::WalletAccount#pay)
     def pay(from:, to:, amount:, unit: Nanook.default_unit, id:)
       wallet_required!
       validate_wallet_contains_account!(from)
@@ -342,31 +332,22 @@ class Nanook
     # When called with no +block+ argument, the latest pending payment
     # for the account will be received.
     #
-    # Returns a <i>receive</i> block hash if a receive was successful,
-    # or +false+ if there were no pending payments to receive.
+    # Returns a <i>receive</i> block hash
+    # if a receive was successful, or +false+ if there were no pending
+    # payments to receive.
     #
-    # You can also receive a specific pending block if you know it by
+    # You can receive a specific pending block if you know it by
     # passing the block has in as an argument.
     #
-    # ==== Arguments
-    #
-    # [+block+] Optional block hash of pending payment. If not provided,
-    #           the latest pending payment will be received
-    # [+into:+] String account id of account in your wallet to receive the
-    #           payment into
-    #
     # ==== Examples
     #
-    #   wallet.receive(into: "xrb...")
-    #   wallet.receive("718CC21...", into: "xrb...")
-    #
-    # ==== Example responses
-    #
-    #   "718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2"
-    #
-    # Or:
+    #   wallet.receive(into: "xrb...")               # => "9AE2311..."
+    #   wallet.receive("718CC21...", into: "xrb...") # => "9AE2311..."
     #
-    #   false
+    # @param block (see Nanook::WalletAccount#receive)
+    # @param into [String] account id of account in your wallet to receive the
+    #   payment into
+    # @return (see Nanook::WalletAccount#receive)
     def receive(block=nil, into:)
       wallet_required!
       validate_wallet_contains_account!(into)

data/lib/nanook/wallet_account.rb

@@ -1,6 +1,33 @@
 class Nanook
   class WalletAccount
 
+    extend Forwardable
+    # @!method balance(unit: Nanook.default_unit)
+    #   (see Nanook::Account#balance)
+    # @!method delegators
+    #   (see Nanook::Account#delegators)
+    # @!method exists?
+    #   (see Nanook::Account#exists?)
+    # @!method history(limit: 1000, unit: Nanook.default_unit)
+    #   (see Nanook::Account#history)
+    # @!method id
+    #   (see Nanook::Account#id)
+    # @!method info((detailed: false, unit: Nanook.default_unit)
+    #   (see Nanook::Account#info)
+    # @!method last_modified_at
+    #   (see Nanook::Account#last_modified_at)
+    # @!method ledger(limit: 1)
+    #   (see Nanook::Account#ledger)
+    # @!method pending(limit: 1000, detailed: false, unit: Nanook.default_unit)
+    #   (see Nanook::Account#pending)
+    # @!method public_key
+    #   (see Nanook::Account#public_key)
+    # @!method representative
+    #   (see Nanook::Account#representative)
+    # @!method weight
+    #   (see Nanook::Account#weight)
+    def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight
+
     def initialize(rpc, wallet, account)
       @rpc = rpc
       @wallet = wallet
@@ -20,26 +47,27 @@ class Nanook
       end
     end
 
+    # @return [String] the account id of this account
     def account_id
       @account
     end
 
-    # Create a new account in this wallet.
+    # Creates a new account, or multiple new accounts, in this wallet.
     #
     # ==== Example:
     #
-    #   wallet.create    # => Create 1 account, and return the {Nanook::WalletAccount}
-    #   wallet.create(2) # => Create 2 accounts, and return an Array of {Nanook::WalletAccount}
+    #   wallet.create    # => Creates 1 account, and return a {Nanook::WalletAccount}
+    #   wallet.create(2) # => Creates 2 accounts, and return an Array of {Nanook::WalletAccount}
     #
-    # @param n [Integer] number of accounts to create (default is 1)
+    # @param n [Integer] number of accounts to create
     #
-    # @return [Nanook::WalletAccount] will return a single {Nanook::WalletAccount}
-    #   unless method was called with
-    # @return [Array<Nanook::WalletAccount>] will return an Array of {Nanook::WalletAccount}
-    #   if method was called with
+    # @return [Nanook::WalletAccount] returns a single {Nanook::WalletAccount}
+    #   if invoked with no argument
+    # @return [Array<Nanook::WalletAccount>] returns an Array of {Nanook::WalletAccount}
+    #   if method was called with argument +n+ >  1
     def create(n=1)
       if n < 1
-        raise ArgumentError.new("number of accounts must be greater than 1")
+        raise ArgumentError.new("number of accounts must be greater than 0")
       end
 
       if n == 1
@@ -51,24 +79,55 @@ class Nanook
       end
     end
 
+    # Unlinks the account from the wallet.
+    #
+    # Note, it's impossible to truly destroy an account. Calling this
+    # method on a wallet causes the wallet to "forget" the account.
+    #
+    # @return [Boolean] returns true if action was successful, otherwise +false+
     def destroy
       rpc(:account_remove)[:removed] == 1
     end
 
+    # @return [String]
     def inspect
       "#{self.class.name}(wallet_id: #{wallet_id}, account_id: #{account_id}, object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
+    # Make a payment from an account in this wallet to another account
+    # on the nano network. Returns a <i>send</i> block hash
+    # if successful, or a {Nanook::Error} if unsuccessful.
+    #
+    # Note, there may be a delay in receiving a response due to Proof of Work being done. From the {Nano RPC}[https://github.com/nanocurrency/raiblocks/wiki/RPC-protocol#account-create]:
+    #
+    # <i>Proof of Work is precomputed for one transaction in the background. If it has been a while since your last transaction it will send instantly, the next one will need to wait for Proof of Work to be generated.</i>
+    #
+    # ==== Examples:
+    #
+    #   account.pay(to: "xrb_...", amount: 1.1, id: "myUniqueId123") # => "9AE2311..."
+    #   account.pay(to: "xrb_...", amount: 54000000000000, unit: :raw, id: "myUniqueId123") # => "9AE2311..."
+    #
+    # @param to [String] account id of the recipient of your payment
+    # @param amount [Integer|Float]
+    # @param unit (see Nanook::Account#balance)
+    # @param id [String] must be unique per payment. It serves an important
+    #   purpose; it allows you to make the same call multiple times with
+    #   the same +id+ and be reassured that you will only ever send this
+    #   nano payment once
+    # @return [String] the send block id for the payment
+    # @raise [Nanook::Error] if unsuccesful
     def pay(to:, amount:, unit: Nanook::default_unit, id:)
       unless Nanook::UNITS.include?(unit)
         raise ArgumentError.new("Unsupported unit: #{unit}")
       end
 
-      # Check that to: account is valid
-      unless Nanook::Account.new(@rpc, to).exists?
-        raise ArgumentError.new("To account does not exist (#{to})")
+      # Check that to account is a valid address
+      response = @rpc.call(:validate_account_number, account: to)
+      unless response[:valid] == 1
+        raise ArgumentError.new("Account address is invalid: #{to}")
       end
 
+      # Determin amount in raw
       raw = if unit.to_sym.eql?(:nano)
         Nanook::Util.NANO_to_raw(amount)
       else
@@ -87,13 +146,33 @@ class Nanook
       response = @rpc.call(:send, p)
 
       if response.has_key?(:error)
-        return response[:error]
+        return Nanook::Error.new(response[:error])
       end
 
       response[:block]
     end
 
-    # Returns false if no block to receive
+    # Receives a pending payment for this account.
+    #
+    # When called with no +block+ argument, the latest pending payment
+    # for the account will be received.
+    #
+    # Returns a <i>receive</i> block id
+    # if a receive was successful, or +false+ if there were no pending
+    # payments to receive.
+    #
+    # You can receive a specific pending block if you know it by
+    # passing the block has in as an argument.
+    #
+    # ==== Examples
+    #
+    #   account.receive               # => "9AE2311..."
+    #   account.receive("718CC21...") # => "9AE2311..."
+    #
+    # @param block [String] optional block id of pending payment. If
+    #   not provided, the latest pending payment will be received
+    # @return [String] the receive block id
+    # @return [false] if no block to receive
     def receive(block=nil)
       if block.nil?
         _receive_without_block
@@ -139,15 +218,6 @@ class Nanook
       @wallet
     end
 
-    # Any method of Nanook::Account can be called on this class too
-    def method_missing(m, *args, &block)
-      if @nanook_account_instance.respond_to?(m)
-        @nanook_account_instance.send(m, *args, &block)
-      else
-        super(m, *args, &block)
-      end
-    end
-
     private
 
     def _receive_without_block

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nanook
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Luke Duncalfe
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-30 00:00:00.000000000 Z
+date: 2018-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler