nanook 2.1.0 → 2.2.0

data/lib/nanook/wallet_account.rb

@@ -1,10 +1,26 @@
 class Nanook
+
+  # The <tt>Nanook::WalletAccount</tt> class lets you manage your nano accounts,
+  # including paying and receiving payment.
+  #
+  # === Initializing
+  #
+  # Initialize this class through an instance of {Nanook::Wallet} like this:
+  #
+  #   account = Nanook.new.wallet(wallet_id).account(account_id)
+  #
+  # Or compose the longhand way like this:
+  #
+  #   rpc_conn = Nanook::Rpc.new
+  #   account = Nanook::WalletAccount.new(rpc_conn, wallet_id, account_id)
   class WalletAccount
 
     extend Forwardable
     # @!method balance(unit: Nanook.default_unit)
     #   (see Nanook::Account#balance)
-    # @!method delegators
+    # @!method block_count
+    #   (see Nanook::Account#block_count)
+    # @!method delegators(unit: Nanook.default_unit)
     #   (see Nanook::Account#delegators)
     # @!method exists?
     #   (see Nanook::Account#exists?)
@@ -16,7 +32,7 @@ class Nanook
     #   (see Nanook::Account#info)
     # @!method last_modified_at
     #   (see Nanook::Account#last_modified_at)
-    # @!method ledger(limit: 1)
+    # @!method ledger(limit: 1, modified_since: nil, unit: Nanook.default_unit)
     #   (see Nanook::Account#ledger)
     # @!method pending(limit: 1000, detailed: false, unit: Nanook.default_unit)
     #   (see Nanook::Account#pending)
@@ -27,6 +43,7 @@ class Nanook
     # @!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
+    alias_method :open?, :exists?
 
     def initialize(rpc, wallet, account)
       @rpc = rpc
@@ -47,17 +64,12 @@ class Nanook
       end
     end
 
-    # @return [String] the account id of this account
-    def account_id
-      @account
-    end
-
     # Creates a new account, or multiple new accounts, in this wallet.
     #
-    # ==== Example:
+    # ==== Examples:
     #
-    #   wallet.create    # => Creates 1 account, and return a {Nanook::WalletAccount}
-    #   wallet.create(2) # => Creates 2 accounts, and return an Array of {Nanook::WalletAccount}
+    #   wallet.create     # => Nanook::WalletAccount
+    #   wallet.create(2)  # => [Nanook::WalletAccount, Nanook::WalletAccount]
     #
     # @param n [Integer] number of accounts to create
     #
@@ -65,6 +77,7 @@ class Nanook
     #   if invoked with no argument
     # @return [Array<Nanook::WalletAccount>] returns an Array of {Nanook::WalletAccount}
     #   if method was called with argument +n+ >  1
+    # @raise [ArgumentError] if +n+ is less than 1
     def create(n=1)
       if n < 1
         raise ArgumentError.new("number of accounts must be greater than 0")
@@ -81,31 +94,33 @@ class Nanook
 
     # 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.
+    # ==== Example:
+    #
+    #   account.destroy # => true
     #
-    # @return [Boolean] returns true if action was successful, otherwise +false+
+    # @return [Boolean] +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)}\")"
+      "#{self.class.name}(wallet_id: #{@wallet}, account_id: #{id}, object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
-    # Make a payment from an account in this wallet to another account
+    # Makes a payment from this account 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]:
+    # 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..."
+    #   account.pay(to: "xrb_...", amount: 54000000000000, id: "myUniqueId123", unit: :raw) # => "9AE2311..."
     #
     # @param to [String] account id of the recipient of your payment
     # @param amount [Integer|Float]
@@ -115,7 +130,7 @@ class Nanook
     #   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
+    # @raise [Nanook::Error] if unsuccessful
     def pay(to:, amount:, unit: Nanook::default_unit, id:)
       unless Nanook::UNITS.include?(unit)
         raise ArgumentError.new("Unsupported unit: #{unit}")
@@ -162,9 +177,9 @@ class Nanook
     # payments to receive.
     #
     # You can receive a specific pending block if you know it by
-    # passing the block has in as an argument.
+    # passing the block in as an argument.
     #
-    # ==== Examples
+    # ==== Examples:
     #
     #   account.receive               # => "9AE2311..."
     #   account.receive("718CC21...") # => "9AE2311..."
@@ -172,7 +187,7 @@ class Nanook
     # @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
+    # @return [false] if there was no block to receive
     def receive(block=nil)
       if block.nil?
         _receive_without_block
@@ -187,37 +202,26 @@ class Nanook
     # behalf on the nano network if your account is offline and there is
     # a fork of the network that requires voting on.
     #
-    # Returns a String of the <em>change block</em> that was
+    # Returns the <em>change block</em> that was
     # broadcast to the nano network. The block contains the information
     # about the representative change for your account.
     #
-    # Will throw an +ArgumentError+ if the representative account does not
-    # exist.
-    #
-    # ==== Arguments
-    # [+representative+] String of a representative account (starting with
-    #                    <tt>"xrb..."</tt>) to set as this account's representative.
-    #
-    # ==== Example
-    #
-    #   account.change_representative("xrb_...")
+    # ==== Example:
     #
-    # ==== Example response
+    #   account.change_representative("xrb_...") # => "000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F"
     #
-    #   "000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F"
+    # @param [String] representative the id of the representative account
+    #   to set as this account's representative
+    # @return [String] id of the <i>change</i> block created
+    # @raise [ArgumentError] if the representative account does not exist
     def change_representative(representative)
-      # Check that representative is valid
       unless Nanook::Account.new(@rpc, representative).exists?
-        raise ArgumentError.new("Representative account does not exist (#{representative})")
+        raise ArgumentError.new("Representative account does not exist: #{representative}")
       end
 
       rpc(:account_representative_set, representative: representative)[:block]
     end
 
-    def wallet_id
-      @wallet
-    end
-
     private
 
     def _receive_without_block

metadata

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