banano 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 142f940e2f3c62e5d2c5d1b4e41947f4bb3aa4d09afa6ef7499692538e43cc96
-  data.tar.gz: 8738e7a8e8675e595901e55e2ff2d7acd3841c0695460ca5b66e1e382ec3eddd
+  metadata.gz: 13119a6d866dab62fc4f2d4a4c55868c8481e3071859a07de3c66a28667a3643
+  data.tar.gz: 5e2943b0615e0de9e8cb1ad638fe3bc8b225bd63dc0657922703d01282377887
 SHA512:
-  metadata.gz: abbacfa91f2ebd5b1cad6e736bc43b63ba65e4c4a0d1b4828624ae1807135f73c2ac6ee40d431e25ebf13f8ade1b480c038f0f8b19854521417e1dc5a74b67d2
-  data.tar.gz: b3e36db244547b823e407536c7951fc2d224502c2abf260eeb1cee0df2b76426831d2916c8c988609b3c7b3f2b621dca2fbe88191a4c87ccc7a2d89bea789d1c
+  metadata.gz: dc144a12257fcf86112bde83f9a7f93f605806bc79537242fa75cc5fcb0d21919b9bbea38d401d35493065af6ea5b04c4ec170c8d22cb5a655936fe49bc724f5
+  data.tar.gz: bf0682a364a13938561b9339b755d91b444374fd0b973cca8602a04564d79657b9dbe28abe8a683a3db9e8e2d073a284f987c12fbc8c742ca5a5ccb4809d94f5

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v0.1.2
+
+- README fixes - typos and wallet usage
+- Banano::Block and Banano::WorkPeer abstractions added
+
 ## v0.1.1
 
 - Pending payments fixes - block\_id is mandatory

data/README.md

@@ -36,7 +36,6 @@ gem install banano
 
 The code is divided on following the parts:
 
-- `Banano::Unit` - conversion between [RAW and Banano units](https://nanoo.tools/banano-units)
 - `Banano::Protocol` - including all other parts. Can be used also for some syntax sugar (to avoid sending node parameter to constructors)
 - `Banano::Client` - very thin wrapper around [Faraday HTTP Client](https://github.com/lostisland/faraday) for easy JSON-based communications
 - `Banano::Node` - Banano Node abstraction - mostly encapsulate JSON communications
@@ -44,6 +43,9 @@ The code is divided on following the parts:
 - `Banano::Account` - uniq 'ban_...' addresses used for currency tokens exchange
 - `Banano::WalletAccount` - link between `Account` and `Wallet` - check if account exists in the wallet etc.
 - `Banano::Key` - account key management
+- `Banano::Block` - low level work with individual blocks
+- `Banano::WorkPeer` - do work on peers
+- `Banano::Unit` - conversion between [RAW and Banano units](https://nanoo.tools/banano-units)
 
 ### Banano::Protocol
 
@@ -52,7 +54,7 @@ If it is impossible to be done, you can use the [Public bananode RPC API](https:
 
 ```rb
 BETA_URL = 'https://api-beta.banano.cc'
-@anano = Banano::Protocol.new(uri: BETA_URL)
+@banano = Banano::Protocol.new(uri: BETA_URL)
 # From here it is easy to create other object, without sending URI to them
 wallet = @banano.wallet('WALLET15263636...')
 account = @banano.account('ban_1...')
@@ -89,25 +91,26 @@ Wallets are like a bags of accounts. Accounts can be only local, created on the
 
 ```rb
 wallet = Banano::Wallet.create   # create new wallet
-wallet.destroy                   # remove the wallet
-wallet.export                    # export wallet to JSON
+wallet.restore(seed: 'XVVREGNN...') # restore some wallet and its accounts
 wallet.accounts                  # current wellet accounts
 wallet.contains?('ban_1...')     # check if the account exists in the current wallet
+wallet.export                    # export wallet to JSON
+wallet.destroy                   # remove the wallet
 # Accounts with voting power
 wallet.default_representative
 wallet.change_default_representative('ban_1...')
+# Security
 wallet.change_password('SomePassword')   # protect your wallet
-walled.lock                              # no more payments
+wallet.lock                              # no more payments
 wallet.locked?
-walled.unlock('SomePassword')            # resume receiving payments
+wallet.unlock('SomePassword')            # resume receiving payments
+# Payments
+block_id = wallet.pay(from: 'ban_1...', to: 'ban_3...', amount: '1.23', raw: false, id: 'x123')
+wallet.pending(limit: 10, detailed: true)  # waiting payments (does not work well unless enable_control = true)
+wallet.receive(into: 'ban_1', block: block_id)  # receive the pending banano into some wallet account
 wallet.balance                           # check how many banano the whole wallet have, RAW units
 wallet.balance(raw: false)               # wallet balance in Banano units
 wallet.balance(account_break_down: true) # banano per acount, RAW units
-# Payments
-wallet.pay(from: 'ban_1...', to: 'ban_3...', amount: '1.23', raw: false, id: 'x123')
-wallet.pending(limit: 10, detailed: true)  # some payments waiting wallet unlock
-wallet.receive(into: 'ban_1')            # receive the pending banano into some wallet account
-wallet.restore(seed: 'XVVREGNN...')      # restore some wallet on the current node
 ```
 
 ### Banano::Account
@@ -122,7 +125,7 @@ account.last_modified_at
 account.public_key
 account.representative
 account.balance             # in RAW units
-accunt.balance(raw: false)  # in banano units
+account.balance(raw: false)  # in banano units
 # Payments
 account.pending(limit: 100, detailed: true)  # detailed information about the pending payments
 account.history(limit: 10)  # the latest payments - send and receive
@@ -136,13 +139,13 @@ Because accounts and wallets so closly connected, some linkage object is very he
 wallet = @banano.wallet('XBHHNN...')
 # create wallet <-> accounts connection
 wallet_acc = Banano::WalletAccount(node: @banano.node, wallet: wallet.id)
-wallet_acc.create     # create account in the wallet
+wallet_acc.create     # create new account in the wallet
 wallet_acc.create(3)  # create additional 3 accounts inside the same wallet
 # Working with specific account
 account = @banano.account('ban_1')
-wallet_other_acc = Banano::WalletAccount(node: pbanano.node, wallet: wallet.id, account: account.id)
-wallet_other_acc.pay(to: 'ban_1...', amount: 10, raw: false, id: 'x1234')  # send some banano
-wallet_other_acc.receive   # receive some banano
+wallet_other_acc = Banano::WalletAccount(node: @banano.node, wallet: wallet.id, account: account.id)
+block_id = wallet_other_acc.pay(to: 'ban_1...', amount: 10, raw: false, id: 'x1234')  # send some banano
+wallet_other_acc.receive(block_id)   # receive some banano
 
 ```
 
@@ -161,7 +164,38 @@ key_builder.generate(seed: SEED, index: 0)    # will always generate SAME pair o
 key_builder.generate(seed: SEED, index: 1)
 new_builder = @banano.key(saved_private_key)  # generate keys from saved private key
 new_builder.expand                            # return private, public key and account address
-``` 
+```
+
+### Banano::WorkPeer
+
+Delegate block validating work to some network peers:
+
+```rb
+work = Banano::WorkPeer(@banano.node)
+work.add(address: '::ffff:1.2.3.4', port: '7071')  # add peer to the work flow
+work.list  # list of working peers
+work.clear # remove all peers
+```
+
+### Banano::Block
+
+Blocks, also known as transactions are the building items of the banano network.
+Every block have uniq ID, which can be used for processing the block
+
+```rb
+block = Banano::Block(node: @banano.node, block: 'F1B7EDB1...')
+block.account           # account associated with the block
+block.successors(limit: 10)
+block.chain(limit: 10)  # also 'block.ancestors' - blocks chain, leading to the current one
+block.history           # more detailed chain history
+block.info              # information about the block
+block.confirm           # block confirmation from the online representatives
+work = block.generate_work(use_peers: true) # start some work
+block.is_valid_work?(work) # check if the work done is valid
+block.cancel_work       # stop generating work for block
+block.pending?          # is the block in pending state. not work very well...
+block.publish('send')   # dependes what kind of block is this: 'send', 'receive' etc.
+```
 
 ### Banano::Unit
 

data/lib/banano.rb

@@ -21,7 +21,18 @@ module Banano
       Banano::Account.new(node: @node, address: address)
     end
 
-    # Returns a new instance of {Nanook::Key}.
+    # Returns a new instance of {Banano::Block}.
+    #
+    # ==== Example:
+    #   block = Banano::Protocol.new.block("FBF8B0E...")
+    #
+    # @param block [String] the id/hash of the block you want to work with
+    # @return [Banano::Block]
+    def block(block)
+      Banano::Block.new(node: @node, block: block)
+    end
+
+    # Returns a new instance of {Banano::Key}.
     #
     # ==== Example:
     #   key = Banano::Protocol.new.key("3068BB...")

data/lib/banano/block.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Banano
+  # The <tt>Banano::Block</tt> class contains methods to discover
+  # publicly-available information about blocks on the nano network.
+  #
+  # A block is represented by a unique id like this:
+  #
+  #   "FBF8B0E6623A31AB528EBD839EEAA91CAFD25C12294C46754E45FD017F7939EB"
+  #
+  class Block
+    def initialize(node:, block:)
+      @node = node
+      @block = block
+      block_required! # All methods expect a block
+    end
+
+    # Returns the {Banano::Account} of the block.
+    #
+    # ==== Example:
+    #   block.account # => Banano::Account
+    #
+    # @return [Banano::Account] the account of the block
+    def account
+      address = rpc(action: :block_account, param_name: :hash)[:account]
+      Banano::Account.new(node: @node, address: address)
+    end
+
+    # Stop generating work for a block.
+    #
+    # ==== Example:
+    #
+    #   block.cancel_work # => true
+    #
+    # @return [Boolean] signalling if the action was successful
+    def cancel_work
+      rpc(action: :work_cancel, param_name: :hash).empty?
+    end
+
+    # 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.
+    #
+    # ==== Example:
+    #
+    #   block.chain(limit: 2)
+    #
+    # @param limit [Integer] maximum number of block hashes to return (default is 1000)
+    # @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)
+      params = {count: limit, offset: offset}
+      rpc(action: :chain, param_name: :block, params: params)[:blocks]
+    end
+    alias 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.
+    #
+    # ==== Example:
+    #   block.confirm # => true
+    #
+    # @return [Boolean] if the confirmation request was sent successful
+    def confirm
+      rpc(action: :block_confirm, param_name: :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.
+    #
+    # This method can work in conjunction with {Banano::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 {Banano::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?
+      @node.rpc(action: :confirmation_history)[:confirmations].map do |h|
+        h[:hash]
+      end.include?(@block)
+    end
+    alias 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 {Banano::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(use_peers: false)
+      rpc(action: :work_generate, param_name: :hash, params: {use_peers: use_peers})[:work]
+    end
+
+    # Returns Array of Hashes containing information about a chain of
+    # send/receive blocks, starting from this block.
+    #
+    # ==== Example:
+    #
+    #   block.history(limit: 1)
+    #
+    # @param limit [Integer] maximum number of send/receive block hashes
+    #   to return in the chain (default is 1000)
+    def history(limit: 1000)
+      response = rpc(action: :history, param_name: :hash, params: {count: limit})
+      response[:history].collect {|entry| Banano::Util.symbolize_keys(entry) }
+    end
+
+    # Returns the block hash id.
+    #
+    # ==== Example:
+    #
+    #   block.id #=> "FBF8B0E..."
+    #
+    # @return [String] the block hash id
+    def id
+      @block
+    end
+
+    # Returns a Hash of information about the block.
+    #
+    # ==== Examples:
+    #
+    #   block.info
+    #   block.info(allow_unchecked: true)
+    #
+    # @param allow_unchecked [Boolean] (default is +false+). If +true+,
+    #   information can be returned about blocks that are unchecked (unverified).
+    def info(allow_unchecked: false)
+      if allow_unchecked
+        response = rpc(action: :unchecked_get, param_name: :hash)
+        return _parse_info_response(response) unless response.key?(:error)
+        # If unchecked not found, continue to checked block
+      end
+
+      response = rpc(action: :block, param_name: :hash)
+      _parse_info_response(response)
+    end
+
+    # ==== Example:
+    #
+    #   block.is_valid_work?("2bf29ef00786a6bc") # => true
+    #
+    # @param work [String] the work id to check is valid
+    # @return [Boolean] signalling if work is valid for the block
+    def is_valid_work?(work)
+      response = rpc(action: :work_validate, param_name: :hash, params: {work: work})
+      !response.empty? && response[:valid] == '1'
+    end
+
+    # Republish blocks starting at this block up the account chain
+    # back to the nano network.
+    #
+    # @return [Array<String>] block hashes that were republished
+    #
+    # ==== Example:
+    #
+    #   block.republish
+    #
+    def republish(destinations: nil, sources: nil)
+      if !destinations.nil? && !sources.nil?
+        raise ArgumentError, "Either destinations or sources but not both"
+      end
+
+      # Add in optional arguments
+      params = {}
+      params[:destinations] = destinations unless destinations.nil?
+      params[:sources] = sources unless sources.nil?
+      params[:count] = 1 unless params.empty?
+
+      rpc(action: :republish, param_name: :hash, params: params)[:blocks]
+    end
+
+    # ==== Example:
+    #
+    #   block.pending? #=> false
+    #
+    # @return [Boolean] signalling if the block is a pending block.
+    def pending?
+      response = rpc(action: :pending_exists, param_name: :hash)
+      !response.empty? && response[:exists] == '1'
+    end
+
+    # Publish the block to the banano network.
+    #
+    # Note, if block has previously been published, use #republish instead.
+    #
+    # ==== Examples:
+    #
+    #   block.publish # => "FBF8B0E..."
+    #
+    # @param [String] subtype: 'send', 'receive', 'open', 'epoch' etc.
+    # @return [String] the block hash, or false.
+    def publish(subtype = '')
+      json_rpc(action: :process, params: {subtype: subtype})
+    end
+    alias process publish
+
+    # Returns an Array of block hashes in the account chain ending at
+    # this block.
+    #
+    # See also #chain.
+    #
+    # ==== Example:
+    #
+    #   block.successors
+    #
+    # @param limit [Integer] maximum number of send/receive block hashes
+    #   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, offset: 0)
+      params = {count: limit, offset: offset}
+      rpc(action: :successors, param_name: :block, params: params)[:blocks]
+    end
+
+    private
+
+    # Some RPC calls expect the param that represents the block to be named
+    # "hash", and others "block".
+    # The param_name argument allows us to specify which it should be for this call.
+    def rpc(action:, param_name:, params: {})
+      p = @block.nil? ? {} : {param_name.to_sym => @block}
+      @node.rpc(action: action, params: p.merge(params))
+    end
+
+    # Special RPC - publish require {block: block.info} parameter
+    def json_rpc(action:, params: {})
+      p = {block: JSON.dump(info), json_block: true}
+      @node.rpc(action: action, params: p.merge(params))
+    end
+
+    def block_required!
+      raise ArgumentError, "Block must be present" if @block.nil?
+    end
+  end
+end

data/lib/banano/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Banano
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

data/lib/banano/work_peer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Banano
+  class WorkPeer
+    def initialize(node)
+      @node = node
+    end
+
+    def add(address:, port:)
+      rpc(action: :work_peer_add, params: {address: address, port: port}).key?(:success)
+    end
+
+    def clear
+      rpc(action: :work_peers_clear).key?(:success)
+    end
+
+    def list
+      rpc(action: :work_peers)[:work_peers]
+    end
+
+    private
+
+    def rpc(action:, params: {})
+      @node.rpc(action: action, params: params)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: banano
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Stoyan Zhekov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-24 00:00:00.000000000 Z
+date: 2020-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -123,6 +123,7 @@ files:
 - bin/setup
 - lib/banano.rb
 - lib/banano/account.rb
+- lib/banano/block.rb
 - lib/banano/client.rb
 - lib/banano/error.rb
 - lib/banano/key.rb
@@ -132,13 +133,14 @@ files:
 - lib/banano/version.rb
 - lib/banano/wallet.rb
 - lib/banano/wallet_account.rb
-homepage: http://github.com/zh/rbanano
+- lib/banano/work_peer.rb
+homepage: https://github.com/zh/rbanano
 licenses:
 - MIT
 metadata:
-  homepage_uri: http://github.com/zh/rbanano
-  source_code_uri: http://github.com/zh/rbanano
-  changelog_uri: http://github.com/zh/rbanano/CHANGELOG.md
+  homepage_uri: https://github.com/zh/rbanano
+  source_code_uri: https://github.com/zh/rbanano
+  changelog_uri: https://github.com/zh/rbanano/blob/master/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: