banano 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11765178fb87fa12d30b11dbe6c454af09e87c2b2ba389e368669698809ee256
+  data.tar.gz: dee6f73a715b2b9e400491fbef8fdfbbb732051ad3d297e1dc49a3803306a0c9
+SHA512:
+  metadata.gz: b1cca559663f4ec639fe847d5425c1babf9be16d0d8477af593b9034f3f2093e24e6ea109e7ae6a30b53cc9af3246f061c703d3e6b5f87f2c37ec5d7bebd9c7e
+  data.tar.gz: 37b0964c5ff8a431f403ef81f3eba4df3b44a9238026e3e6b28b993fccf8cd2aff1087ad386597a17a5f0bf1f83fac36ae4f2d193315d3a8ca4178aaea08ba4a

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+- Initial import
+- Gem packaging

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 zhware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# Banano
+
+The current Gem trying to make as easy as possible working with [Banano currency](https://banano.cc/).
+More information about the Banano currency networking can be found on the [Banano Currency Wiki pages](https://github.com/BananoCoin/banano/wiki/Network-Specifications).
+The current library is still work in progress, but the basic functionallity is already implemented:
+
+- Good part of the RPC protocol for working with Banano nodes
+- Wallet, Account operations - send and receive payments etc.
+- Conversion between units - RAW to Banano and Banano to RAW
+
+Some parts of the library are heavily influenced by the great [nanook Ruby library](https://github.com/lukes/nanook) for working with the similar [NANO currency](https://nano.org/en/).
+
+Everybody is welcome to contrubute to the project. Have fun and use Ruby and Banano.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'banano'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install banano
+```
+
+## Usage
+
+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
+- `Bananp::Wallet` - wallets holding for Banano accounts on the current node
+- `Bananp::Account` - uniq 'ban_...' addresses used for currency tokens exchange
+- `Bananp::WalletAccount` - link between `Account` and `Wallet` - check if account exists in the wallet etc.
+
+### Banano::Protocol
+
+Usually everything starts here. By default the library will work with [locally running Banano node](https://github.com/BananoCoin/banano/wiki/Running-a-Docker-Bananode).
+If it is impossible to be done, you can use the [Public bananode RPC API](https://nanoo.tools/bananode-api). Example below is for that case:
+
+```rb
+BETA_URL = 'https://api-beta.banano.cc'
+@anano = 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...')
+```
+### Banano::Client
+
+Not used directly, better use `Banano::Node` instead
+
+```rb
+client = Banano::Client.new(uri: BETA_URL)
+client.rpc_call(action: :version)
+```
+
+### Banano::Node
+
+Most of the information about the running node is encapsulated here. The other parts using  mostly the `Banano::Node.rpc()` method, not the low level client one: 
+
+```rb
+Banano::Node.account_count # number of node accounts
+Banano::Node.block_count   # check here if there are still non-syncronized blocks
+Banano::Node.peers         # other nodes connected to that one
+# accounts with voting power
+Banano::Node.representatives
+Banano::Node.representatives_online
+# Is your node synced already
+Banano::Node.synchronizing_blocks
+Banano::Node.sync_progress
+```
+
+### Banano::Wallet
+
+Wallets are like a bags of accounts. Accounts can be only local, created on the current node. They will not be visible for other nodes.
+
+```rb
+wallet = Banano::Wallet.create   # create new wallet
+wallet.destroy                   # remove the wallet
+wallet.export                    # export wallet to JSON
+wallet.accounts                  # current wellet accounts
+wallet.contains?('ban_1...')     # check if the account exists in the current wallet
+# Accounts with voting power
+wallet.default_representative
+wallet.change_default_representative('ban_1...')
+wallet.change_password('SomePassword')   # protect your wallet
+walled.lock                              # no more payments
+wallet.locked?
+walled.unlock('SomePassword')            # resume receiving payments
+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
+
+Account are holding units with unique address, where the banano tokens are accumulated. They can be local for the current node and not accessable for other nodes.
+
+```rb
+account = Banano::Account(node: @banano.node, address: 'ban1_...')  # create new account on that node
+account.exists?   # check if account exists
+# some account attributes
+account.last_modified_at
+account.public_key
+account.representative
+account.balance             # in RAW units
+accunt.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
+```
+
+### Banano::WalletAccount
+
+Because accounts and wallets so closly connected, some linkage object is very helpful.
+
+```rb
+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(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
+
+```
+
+### Banano::Unit
+
+Using [Ruby bigdecimal library](https://apidock.com/ruby/BigDecimal) for all operations:
+
+```rb
+Banano::Unit.ban_to_raw(1)    # -> BigDecimal('100000000000000000000000000000')
+Banano::Unit.raw_to_ban('1')  # -> BigDecimal('0.00000000000000000000000000001')
+```
+
+The library also is checking some currency related limits, for example total supply limit: `3402823669.20938463463374607431768211455` banano max
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Clone the gem source code and start experimenting:
+
+```sh
+git clone https://github.com/zh/rbanano
+```
+
+`rspec` is used for testing. To run all tests execute:
+
+```sh
+bundle exec rspec spec
+```
+
+Still a lot of tests needed. For now `Banano::Unit` and `Banano:Util` are ready. The other parts tests will be added soon.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/zh/rbanano](https://github.com/zh/rbanano).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "banano"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/banano.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+Dir[File.dirname(__FILE__) + '/banano/*.rb'].each {|file| require file }
+
+module Banano
+  class Protocol
+    attr_reader :node
+
+    def initialize(uri: Client::LOCAL_ENDPOINT, timeout: Client::DEFAULT_TIMEOUT)
+      @node = Node.new(uri: uri, timeout: timeout)
+    end
+
+    # Returns a new instance of {Banano::Account}.
+    #
+    # ==== Example:
+    #   account = Banano::Protocol.new.account(address: "ban_3e3j...")
+    #
+    # @param address [String] the id of the account you want to work with
+    # @return [Banano::Account]
+    def account(address)
+      Banano::Account.new(node: @node, address: address)
+    end
+
+    # Returns a new instance of {Nanook::Key}.
+    #
+    # ==== Example:
+    #   key = Banano::Protocol.new.key("3068BB...")
+    #
+    # @param key [String] a private key
+    # @return [Banano::Key]
+    def key(key = nil)
+      Banano::Key.new(node: @node, key: key)
+    end
+
+    # Returns a new instance of {Banano::Wallet}.
+    #
+    # ==== Example:
+    #   wallet = Banano::Protocol.new.wallet("000D1BAE...")
+    #
+    # @param wallet [String] the id of the wallet you want to work with
+    # @return [Banano::Wallet]
+    def wallet(wallet = nil)
+      Banano::Wallet.new(node: @node, wallet: wallet)
+    end
+  end
+end

data/lib/banano/account.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Banano
+  class Account
+    attr_accessor :address
+
+    def initialize(node:, address:)
+      @node = node
+      @address = address
+    end
+
+    # The last modified time of the account in the time zone of
+    # your node (usually UTC).
+    #
+    # ==== Example:
+    #
+    #   account.last_modified_at # => Time
+    #
+    # @return [Time] last modified time of the account in the time zone of
+    #   your nano node (usually UTC).
+    def last_modified_at
+      response = rpc(action: :account_info)
+      Time.at(response[:modified_timestamp].to_i)
+    end
+
+    # The public key of the account.
+    #
+    # ==== Example:
+    #
+    #   account.public_key # => "3068BB1..."
+    #
+    # @return [String] public key of the account
+    def public_key
+      rpc(action: :account_key)[:key]
+    end
+
+    # The representative account id for the account.
+    # Representatives are accounts that cast votes in the case of a
+    # fork in the network.
+    #
+    # ==== Example:
+    #
+    #   account.representative # => "ban_3pc..."
+    #
+    # @return [String] Representative account of the account
+    def representative
+      rpc(action: :account_representative)[:representative]
+    end
+
+    # The account's balance, including pending (unreceived payments).
+    # To receive a pending amount see {WalletAccount#receive}.
+    #
+    # ==== Examples:
+    #
+    #   account.balance
+    #
+    # Example response:
+    #
+    #   {
+    #     balance: 2,
+    #     pending: 1.1
+    #   }
+    #
+    # @param raw [Boolean] if true raw, else banano units
+    # @raise ArgumentError if an invalid +unit+ was given.
+    # @return [Hash{Symbol=>Integer|Float}]
+    def balance(raw = true)
+      rpc(action: :account_balance).tap do |r|
+        unless raw == true
+          r[:balance] = Banano::Unit.raw_to_ban(r[:balance]).to_f
+          r[:pending] = Banano::Unit.raw_to_ban(r[:pending]).to_f
+        end
+      end
+    end
+
+    # @return [Integer] number of blocks for this account
+    def block_count
+      rpc(action: :account_block_count)[:block_count].to_i
+    end
+
+    # Information about pending blocks (payments) that are
+    # waiting to be received by the account.
+    #
+    # The default response is an Array of block ids.
+    #
+    # With the +detailed:+ argument, the method returns an Array of Hashes,
+    # which contain the source account id, amount pending and block id.
+    #
+    # ==== Examples:
+    #
+    #   account.pending # => ["000D1BA..."]
+    #
+    # Asking for more detail to be returned:
+    #
+    #   account.pending(detailed: true)
+    #
+    # @param limit [Integer] number of pending blocks to return (default is 1000)
+    # @param detailed [Boolean]return a more complex Hash of pending block information (default is +false+)
+    # @param raw [Boolean] if true raw, else banano units
+    #
+    # @return [Array<String>]
+    # @return [Array<Hash{Symbol=>String|Integer}>]
+    def pending(limit: 1000, detailed: false, raw: true)
+      params = {count: limit}
+      params[:source] = true if detailed
+
+      response = rpc(action: :pending, params: params)[:blocks]
+      return response unless detailed && !response.empty?
+
+      response.map do |key, val|
+        p = val.merge(block: key.to_s)
+        p[:amount] = Banano::Unit.raw_to_ban(p[:amount]).to_f unless raw == true
+        p
+      end
+    end
+
+    # The id of the account.
+    #
+    # ==== Example:
+    #
+    #   account.id # => "ban_16u..."
+    #
+    # @return [String] the id of the account
+    def id
+      @address
+    end
+
+    # Information about this accounts that have set this account as their representative.
+    #
+    # === Example:
+    #
+    #   account.delegators
+    #
+    # @param raw [Boolean] if true return raw balances, else banano units
+    # @return [Hash{Symbol=>Integer}] account ids which delegate to this account
+    def delegators(raw = true)
+      response = rpc(action: :delegators)[:delegators]
+      return response if raw == true
+
+      r = response.map do |address, balance|
+        [address.to_s, Banano::Unit.raw_to_ban(balance).to_f]
+      end
+      Hash[r]
+    end
+
+    # Information about the account.
+    #
+    # ==== Examples:
+    #
+    #   account.info
+    #
+    # @return [Hash{Symbol=>String|Integer|Float}] information about the account
+    def info
+      rpc(action: :account_info)
+    end
+
+    # Returns true if the account has an <i>open</i> block.
+    #
+    # An open block gets published when an account receives a payment
+    # for the first time.
+    #
+    # ==== Example:
+    #
+    #   account.exists? # => true
+    #   # or
+    #   account.open?   # => true
+    #
+    # @return [Boolean] Indicates if this account has an open block
+    def exists?
+      response = info
+      !response.empty? && !response[:open_block].nil?
+    end
+    alias open? exists?
+
+    # An account's history of send and receive payments.
+    #
+    # ==== Example:
+    #
+    #   account.history
+    #
+    # @param limit [Integer] maximum number of history items to return
+    # @param raw [Boolean] raw or banano
+    # @return [Array<Hash{Symbol=>String}>] the history of send and receive payments for this account
+    def history(limit: 1000, raw: true)
+      response = Array(rpc(action: :account_history, params: {count: limit})[:history])
+      response = response.collect {|h| Banano::Util.symbolize_keys(h) }
+      return response if raw == true
+
+      response.map! do |history|
+        history[:amount] = Banano::Unit.raw_to_ban(history[:amount]).to_f
+        history
+      end
+    end
+
+    private
+
+    def rpc(action:, params: {})
+      p = @address.nil? ? {} : {account: @address}
+      @node.rpc(action: action, params: p.merge(params))
+    end
+  end
+end