nanook 2.1.0 → 2.5.1

data/lib/nanook/rpc.rb

@@ -2,10 +2,23 @@ require 'json'
 require 'symbolized'
 
 class Nanook
+
+  # The <tt>Nanook::Rpc</tt> class is responsible for maintaining the
+  # connection to the RPC server, calling the RPC and parsing its response
+  # into Ruby primitives.
+  #
+  # Internally, the {Nanook} class creates an instance of this class, and
+  # it's generally more convenient to interact with the RPC through an
+  # instance of {Nanook#rpc} instead of by instantiating this class directly:
+  #
+  #   nanook = Nanook.new
+  #   nanook.rpc(:accounts_create, wallet: wallet_id, count: 2)
   class Rpc
 
+    # Default RPC server and port to connect to
     DEFAULT_URI = "http://localhost:7076"
-    DEFAULT_TIMEOUT = 500 # seconds
+    # Default request timeout in seconds
+    DEFAULT_TIMEOUT = 60
 
     def initialize(uri=DEFAULT_URI, timeout:DEFAULT_TIMEOUT)
       @rpc_server = URI(uri)
@@ -20,6 +33,12 @@ class Nanook
       @request.content_type = "application/json"
     end
 
+    # Calls the RPC server and returns the response.
+    #
+    # @param action [Symbol] the "action" of the RPC to call. The RPC always
+    #   expects an "action" param to identify what RPC action is being called.
+    # @param params [Hash] all other params to pass to the RPC
+    # @return [Hash] the response from the RPC
     def call(action, params={})
       # Stringify param values
       params = Hash[params.map {|k, v| [k, v.to_s] }]
@@ -36,13 +55,14 @@ class Nanook
       end
     end
 
+    # @return [String]
     def inspect
       "#{self.class.name}(host: \"#{@rpc_server}\", timeout: #{@http.read_timeout} object_id: \"#{"0x00%x" % (object_id << 1)}\")"
     end
 
     private
 
-    # Convert Strings of primitives to primitives
+    # Recursively parses the RPC response, sending values to #parse_value
     def process_hash(h)
       new_hash = h.map do |k,v|
         v = if v.is_a?(Array)
@@ -63,6 +83,7 @@ class Nanook
       Hash[new_hash.sort].to_symbolized_hash
     end
 
+    # Converts Strings to primitives
     def parse_value(v)
       return v.to_i if v.match(/^\d+\Z/)
       return true if v == "true"

data/lib/nanook/util.rb

@@ -1,18 +1,37 @@
 require 'bigdecimal'
 
 class Nanook
+
+  # Set of class utility methods.
   class Util
 
-    STEP = BigDecimal.new("10")**BigDecimal.new("30")
+    # Constant used to convert back and forth between raw and NANO.
+    STEP = BigDecimal("10")**BigDecimal("30")
 
+    # Converts an amount of NANO to an amount of raw.
+    #
+    # @param nano [Float|Integer] amount in nano
+    # @return [Integer] amount in raw
     def self.NANO_to_raw(nano)
-      (BigDecimal.new(nano.to_s) * STEP).to_i
+      (BigDecimal(nano.to_s) * STEP).to_i
     end
 
+    # Converts an amount of raw to an amount of NANO.
+    #
+    # @param raw [Integer] amount in raw
+    # @return [Float|Integer] amount in NANO
     def self.raw_to_NANO(raw)
       (raw.to_f / STEP).to_f
     end
 
+    # Converts an empty String value into an empty version of another type.
+    #
+    # The RPC often returns an empty String (<tt>""</tt>) as a value, when a
+    # +nil+, or empty Array (<tt>[]</tt>), or empty Hash (<tt>{}</tt>) would be better.
+    # If the response might be
+    #
+    # @param response the value returned from the RPC server
+    # @param type the type to return an empty of
     def self.coerce_empty_string_to_type(response, type)
       if response == "" || response.nil?
         return type.new

data/lib/nanook/version.rb

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

data/lib/nanook/wallet.rb

@@ -3,21 +3,41 @@ class Nanook
   # The <tt>Nanook::Wallet</tt> class lets you manage your nano wallets,
   # as well as some account-specific things like making and receiving payments.
   #
-  # Your wallets each have a seed, which is a 32-byte uppercase hex
-  # string that looks like this:
+  # === Wallet seeds vs ids
+  #
+  # Your wallets each have an id as well as a seed. Both are 32-byte uppercase hex
+  # strings that look like this:
   #
   #   000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F
   #
-  # 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.
-  # <b>Make sure this key is always secret and safe</b>. Do not commit
-  # your seed into source control.
+  # This class uses wallet _ids_ to identify your wallet. A wallet id only
+  # exists locally on the nano node that it was created on. The person
+  # who knows this id can only perform all read and write actions against
+  # the wallet and all accounts inside the wallet from the same nano node
+  # that it was created on. This makes wallet ids fairly safe to use as a
+  # person needs to know your wallet id as well as have access to run
+  # RPC commands against your nano node to be able to control your accounts.
+  #
+  # A _seed_ on the other hand can be used to link any wallet to another
+  # wallet's accounts, from anywhere in the nano network. This happens
+  # by setting a wallet's seed to be the same as a previous wallet's seed.
+  # When a wallet has the same seed as another wallet, any accounts
+  # created in the second wallet will be the same accounts as those that were
+  # created in the previous wallet, and the new wallet's owner will
+  # also gain ownership of the previous wallet's accounts. Note, that the
+  # two wallets will have different ids, but the same seed.
+  #
+  # Nanook is based on the Nano RPC, which uses wallet ids and not seeds.
+  # The RPC and therefore Nanook cannot tell you what a wallet's seed is,
+  # only its id. Knowing a wallet's seed is very useful for if you ever
+  # want to restore the wallet anywhere else on the nano network besides
+  # the node you originally created it on. The nano command line interface
+  # (CLI) is the only method for discovering a wallet's seed. See the
+  # {https://docs.nano.org/commands/command-line-interface/#-wallet_decrypt_unsafe-walletwallet-passwordpassword}.
   #
   # === Initializing
   #
-  # Initialize this class through the convenient Nanook#wallet method:
+  # Initialize this class through the convenient {Nanook#wallet} method:
   #
   #   nanook = Nanook.new
   #   wallet = nanook.wallet(wallet_id)
@@ -33,31 +53,37 @@ class Nanook
       @wallet = wallet
     end
 
-    # A convenient method that returns an account in your wallet, allowing
-    # you to perform all the actions in Nanook::WalletAccount on it.
+    # Returns the given account in the wallet as a {Nanook::WalletAccount} instance
+    # to let you start working with it.
     #
-    #   wallet.account("xrb_...") #=> Nanook::WalletAccount instance
+    # Call with no +account+ argument if you wish to create a new account
+    # in the wallet, like this:
     #
-    # See Nanook::WalletAccount.
+    #   wallet.account.create     # => Nanook::WalletAccount
     #
-    # Will throw an ArgumentError if the wallet does not contain the account.
+    # See {Nanook::WalletAccount} for all the methods you can call on the
+    # account object returned.
     #
-    # ==== Arguments
-    # [+account+] Optional String of an account (starting with
-    #             <tt>"xrb..."</tt>) to start working with. Must be an
-    #             account within the wallet. When
-    #             no account is given, the instance returned only allows you to call
-    #             +create+ on it, to create a new account. Otherwise, you
-    #             must pass an account string for all other methods.
+    # ==== Examples:
     #
-    # ==== Examples
+    #   wallet.account("nano_...") # => Nanook::WalletAccount
+    #   wallet.account.create     # => Nanook::WalletAccount
     #
-    #   wallet.account.create      # Creates an account in the wallet and returns a Nanook::WalletAccount
-    #   wallet.account(account_id) # Returns a Nanook::WalletAccount for the account
+    # @param [String] account optional String of an account (starting with
+    #   <tt>"xrb..."</tt>) to start working with. Must be an account within
+    #   the wallet. When no account is given, the instance returned only
+    #   allows you to call +create+ on it, to create a new account.
+    # @raise [ArgumentError] if the wallet does no contain the account
+    # @return [Nanook::WalletAccount]
     def account(account=nil)
       Nanook::WalletAccount.new(@rpc, @wallet, account)
     end
 
+    # Array of {Nanook::WalletAccount} instances of accounts in the wallet.
+    #
+    # See {Nanook::WalletAccount} for all the methods you can call on the
+    # account objects returned.
+    #
     # ==== Example:
     #
     #   wallet.accounts # => [Nanook::WalletAccount, Nanook::WalletAccount...]
@@ -71,21 +97,9 @@ class Nanook
       end
     end
 
-    # Returns a Hash containing the balance of all accounts in the
-    # wallet, optionally breaking the balances down by account.
+    # Balance of all accounts in the wallet, optionally breaking the balances down by account.
     #
-    # ==== Arguments
-    #
-    # [+account_break_down:+] Boolean (default is +false+). When +true+
-    #                         the response will contain balances per
-    #                         account.
-    # [+unit:+]   Symbol (default is +:nano+) Represents the unit that
-    #             the balances will be returned 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-])
-    #
-    # ==== Examples
+    # ==== Examples:
     #   wallet.balance
     #
     # Example response:
@@ -113,15 +127,21 @@ class Nanook
     # Example response:
     #
     #   {
-    #     "xrb_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000"=>{
+    #     "nano_3e3j5tkog48pnny9dmfzj1r16pg8t1e76dz5tmac6iq689wyjfpi00000000"=>{
     #       "balance"=>2.5,
     #       "pending"=>1
     #     },
-    #     "xrb_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx"=>{
+    #     "nano_1e5aqegc1jb7qe964u4adzmcezyo6o146zb8hm6dft8tkp79za3sxwjym5rx"=>{
     #       "balance"=>51.4,
     #       "pending"=>0
     #     },
     #   }
+    #
+    # @param [Boolean] account_break_down (default is +false+). When +true+
+    #  the response will contain balances per account.
+    # @param unit (see Nanook::Account#balance)
+    #
+    # @return [Hash{Symbol=>Integer|Float|Hash}]
     def balance(account_break_down: false, unit: Nanook.default_unit)
       wallet_required!
 
@@ -150,6 +170,13 @@ class Nanook
 
     # Changes a wallet's seed.
     #
+    # It's recommended to only change the seed of a wallet that contains
+    # no accounts.
+    #
+    # ==== Example:
+    #
+    #   wallet.change_seed("000D1BA...") # => true
+    #
     # @param seed [String] the seed to change to.
     # @return [Boolean] indicating whether the change was successful.
     def change_seed(seed)
@@ -162,6 +189,10 @@ class Nanook
     # 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.
+    # The nano command line interface (CLI) is the only method for
+    # backing up a wallet's seed. See the
+    # {https://github.com/nanocurrency/raiblocks/wiki/Command-line-interface
+    # --wallet_decrypt_unsafe CLI command}.
     #
     # ==== Example:
     #   Nanook.new.wallet.create # => Nanook::Wallet
@@ -172,11 +203,13 @@ class Nanook
       self
     end
 
-    # Destroy the wallet. Returns a boolean indicating whether the action
-    # was successful or not.
+    # Destroys the wallet.
+    #
+    # ==== Example:
+    #
+    #   wallet.destroy # => true
     #
-    # ==== Example Response
-    #   true
+    # @return [Boolean] indicating success of the action
     def destroy
       wallet_required!
       rpc(:wallet_destroy)
@@ -185,53 +218,52 @@ class Nanook
 
     # Generates a String containing a JSON representation of your wallet.
     #
-    # ==== Example response
+    # ==== Example:
     #
-    #   "{\n    \"0000000000000000000000000000000000000000000000000000000000000000\": \"0000000000000000000000000000000000000000000000000000000000000003\",\n    \"0000000000000000000000000000000000000000000000000000000000000001\": \"C3A176FC3B90113277BFC91F55128FC9A1F1B6166A73E7446927CFFCA4C2C9D9\",\n    \"0000000000000000000000000000000000000000000000000000000000000002\": \"3E58EC805B99C52B4715598BD332C234A1FBF1780577137E18F53B9B7F85F04B\",\n    \"0000000000000000000000000000000000000000000000000000000000000003\": \"5FF8021122F3DEE0E4EC4241D35A3F41DEF63CCF6ADA66AF235DE857718498CD\",\n    \"0000000000000000000000000000000000000000000000000000000000000004\": \"A30E0A32ED41C8607AA9212843392E853FCBCB4E7CB194E35C94F07F91DE59EF\",\n    \"0000000000000000000000000000000000000000000000000000000000000005\": \"E707002E84143AA5F030A6DB8DD0C0480F2FFA75AB1FFD657EC22B5AA8E395D5\",\n    \"0000000000000000000000000000000000000000000000000000000000000006\": \"0000000000000000000000000000000000000000000000000000000000000001\",\n    \"8646C0423160DEAEAA64034F9C6858F7A5C8A329E73E825A5B16814F6CCAFFE3\": \"0000000000000000000000000000000000000000000000000000000100000000\"\n}\n"
+    #   wallet.export # => "{\n    \"0000000000000000000000000000000000000000000000000000000000000000\": \"0000000000000000000000000000000000000000000000000000000000000003\",\n    \"0000000000000000000000000000000000000000000000000000000000000001\": \"C3A176FC3B90113277BFC91F55128FC9A1F1B6166A73E7446927CFFCA4C2C9D9\",\n    \"0000000000000000000000000000000000000000000000000000000000000002\": \"3E58EC805B99C52B4715598BD332C234A1FBF1780577137E18F53B9B7F85F04B\",\n    \"0000000000000000000000000000000000000000000000000000000000000003\": \"5FF8021122F3DEE0E4EC4241D35A3F41DEF63CCF6ADA66AF235DE857718498CD\",\n    \"0000000000000000000000000000000000000000000000000000000000000004\": \"A30E0A32ED41C8607AA9212843392E853FCBCB4E7CB194E35C94F07F91DE59EF\",\n    \"0000000000000000000000000000000000000000000000000000000000000005\": \"E707002E84143AA5F030A6DB8DD0C0480F2FFA75AB1FFD657EC22B5AA8E395D5\",\n    \"0000000000000000000000000000000000000000000000000000000000000006\": \"0000000000000000000000000000000000000000000000000000000000000001\",\n    \"8646C0423160DEAEAA64034F9C6858F7A5C8A329E73E825A5B16814F6CCAFFE3\": \"0000000000000000000000000000000000000000000000000000000100000000\"\n}\n"
     def export
       wallet_required!
       rpc(:wallet_export)[:json]
     end
 
-    # Returns boolean indicating if the wallet contains an account.
+    # Will return +true+ if the account exists in the wallet.
     #
-    # ==== Arguments
-    #
-    # [+account+] String account id (will start with <tt>"xrb_..."</tt>)
+    # ==== Example:
+    #   wallet.contains?("nano_...") # => true
     #
-    # ==== Example response
-    #   true
+    # @param account [String] id (will start with <tt>"nano_..."</tt>)
+    # @return [Boolean] indicating if the wallet contains the given account
     def contains?(account)
       wallet_required!
       response = rpc(:wallet_contains, account: account)
       !response.empty? && response[:exists] == 1
     end
 
-    # @return [String]
+    # @return [String] the wallet id
     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 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]:
+    # Makes a payment from an account in your wallet to another account
+    # on the nano network.
     #
-    # <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>
+    # Note, there may be a delay in receiving a response due to Proof of
+    # Work being done. From the {Nano RPC}[https://docs.nano.org/commands/rpc-protocol/#send]:
     #
-    # ==== Examples
+    # <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>
     #
-    #   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..."
+    # ==== Examples:
     #
-    # ==== Arguments
+    #   wallet.pay(from: "nano_...", to: "nano_...", amount: 1.1, id: "myUniqueId123") # => "9AE2311..."
+    #   wallet.pay(from: "nano_...", to: "nano_...", amount: 54000000000000, unit: :raw, id: "myUniqueId123") # => "9AE2311..."
     #
     # @param from [String] account id of an account in your wallet
     # @param to (see Nanook::WalletAccount#pay)
@@ -239,57 +271,61 @@ class Nanook
     # @param unit (see Nanook::Account#balance)
     # @params id (see Nanook::WalletAccount#pay)
     # @return (see Nanook::WalletAccount#pay)
+    # @raise [Nanook::Error] if unsuccessful
     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
+    # 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.
+    # 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:
+    # ==== Examples:
     #
     #   wallet.pending
     #
-    # ==== Example 1 response:
+    # Example response:
+    #
     #   {
-    #     :xrb_1111111111111111111111111111111111111111111111111117353trpda=>[
+    #     :nano_1111111111111111111111111111111111111111111111111117353trpda=>[
     #       "142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D",
     #       "718CC2121C3E641059BC1C2CFC45666C99E8AE922F7A807B7D07B62C995D79E2"
     #     ],
-    #     :xrb_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3=>[
+    #     :nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3=>[
     #       "4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74"
     #     ]
     #   }
-    # ==== Example 2:
+    #
+    # Asking for more information:
     #
     #   wallet.pending(detailed: true)
     #
-    # ==== Example 2 response:
+    # Example response:
+    #
     #   {
-    #     :xrb_1111111111111111111111111111111111111111111111111117353trpda=>[
+    #     :nano_1111111111111111111111111111111111111111111111111117353trpda=>[
     #       {
     #         :amount=>6.0,
-    #         :source=>"xrb_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr",
+    #         :source=>"nano_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr",
     #         :block=>:"142A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D"
     #       },
     #       {
     #         :amount=>12.0,
-    #         :source=>"xrb_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr",
+    #         :source=>"nano_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr",
     #         :block=>:"242A538F36833D1CC78B94E11C766F75818F8B940771335C6C1B8AB880C5BB1D"
     #       }
     #     ],
-    #     :xrb_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3=>[
+    #     :nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3=>[
     #       {
     #         :amount=>106.370018,
-    #         :source=>"xrb_13ezf4od79h1tgj9aiu4djzcmmguendtjfuhwfukhuucboua8cpoihmh8byo",
+    #         :source=>"nano_13ezf4od79h1tgj9aiu4djzcmmguendtjfuhwfukhuucboua8cpoihmh8byo",
     #         :block=>:"4C1FEEF0BEA7F50BE35489A1233FE002B212DEA554B55B1B470D78BD8F210C74"
     #       }
     #     ]
@@ -332,14 +368,13 @@ 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 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
+    # ==== Examples:
     #
     #   wallet.receive(into: "xrb...")               # => "9AE2311..."
     #   wallet.receive("718CC21...", into: "xrb...") # => "9AE2311..."
@@ -354,7 +389,51 @@ class Nanook
       account(into).receive(block)
     end
 
-    # Restore a previously created wallet by its seed.
+    # The default representative account id for the wallet. This is the
+    # representative that all new accounts created in this wallet will have.
+    #
+    # Changing the default representative for a wallet does not change
+    # the representatives for any accounts that have been created.
+    #
+    # ==== Example:
+    #
+    #   wallet.default_representative # => "nano_3pc..."
+    #
+    # @return [String] Representative account of the account
+    def default_representative
+      rpc(:wallet_representative)[:representative]
+    end
+    alias_method :representative, :default_representative
+
+    # Sets the default representative for the wallet. A wallet's default
+    # representative is the representative all new accounts created in
+    # the wallet will have. Changing the default representative for a
+    # wallet does not change the representatives for existing accounts
+    # in the wallet.
+    #
+    # ==== Example:
+    #
+    #   wallet.change_default_representative("nano_...") # => "nano_..."
+    #
+    # @param [String] representative the id of the representative account
+    #   to set as this account's representative
+    # @return [String] the representative account id
+    # @raise [ArgumentError] if the representative account does not exist
+    # @raise [Nanook::Error] if setting the representative fails
+    def change_default_representative(representative)
+      unless Nanook::Account.new(@rpc, representative).exists?
+        raise ArgumentError.new("Representative account does not exist: #{representative}")
+      end
+
+      if rpc(:wallet_representative_set, representative: representative)[:set] == 1
+        representative
+      else
+        raise Nanook::Error.new("Setting the representative failed")
+      end
+    end
+    alias_method :change_representative, :change_default_representative
+
+    # Restores 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.
     #
@@ -381,11 +460,73 @@ class Nanook
       self
     end
 
-    # Returns a boolean to indicate if the wallet is locked.
+    # Information about this wallet and all of its accounts.
+    #
+    # ==== Examples:
+    #
+    #   wallet.info
+    #
+    # Example response:
     #
-    # ==== Example response
+    #   {
+    #     id: "2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
+    #     accounts: [
+    #       {
+    #         id: "nano_11119gbh8hb4hj1duf7fdtfyf5s75okzxdgupgpgm1bj78ex3kgy7frt3s9n"
+    #         frontier: "E71AF3E9DD86BBD8B4620EFA63E065B34D358CFC091ACB4E103B965F95783321",
+    #         open_block: "643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F",
+    #         representative_block: "643B77F1ECEFBDBE1CC909872964C1DBBE23A6149BD3CEF2B50B76044659B60F",
+    #         balance: 1.45,
+    #         modified_timestamp: 1511476234,
+    #         block_count: 2
+    #       },
+    #       { ... }
+    #     ]
+    #   }
     #
-    #   true
+    # @param unit (see #balance)
+    # @return [Hash{Symbol=>String|Array<Hash{Symbol=>String|Integer|Float}>}] information about the wallet.
+    #   See {Nanook::Account#info} for details of what is returned for each account.
+    def info(unit: Nanook.default_unit)
+      unless Nanook::UNITS.include?(unit)
+        raise ArgumentError.new("Unsupported unit: #{unit}")
+      end
+
+      wallet_required!
+      accounts = rpc(:wallet_ledger)[:accounts].map do |account_id, payload|
+        payload[:id] = account_id
+        if unit == :nano
+          payload[:balance] = Nanook::Util.raw_to_NANO(payload[:balance])
+        end
+        payload
+      end
+
+      {
+        id: @wallet,
+        accounts: accounts
+      }.to_symbolized_hash
+    end
+
+    # Locks the wallet. A locked wallet cannot pocket pending transactions or make payments. See {#unlock}.
+    #
+    # ==== Example:
+    #
+    #   wallet.lock #=> true
+    #
+    # @return [Boolean] indicates if the wallet was successfully locked
+    def lock
+      wallet_required!
+      response = rpc(:wallet_lock)
+      !response.empty? && response[:locked] == 1
+    end
+
+    # Returns +true+ if the wallet is locked.
+    #
+    # ==== Example:
+    #
+    #   wallet.locked? #=> false
+    #
+    # @return [Boolean] indicates if the wallet is locked
     def locked?
       wallet_required!
       response = rpc(:wallet_locked)
@@ -397,7 +538,8 @@ class Nanook
     # ==== Example:
     #
     #   wallet.unlock("new_pass") #=> true
-    # @return [Boolean] indicates if the action was successful
+    #
+    # @return [Boolean] indicates if the unlocking action was successful
     def unlock(password)
       wallet_required!
       rpc(:password_enter, password: password)[:valid] == 1