Class: Nanook::WalletAccount

Inherits:

Object

Object
Nanook::WalletAccount

show all

Extended by:: Forwardable

Defined in:: lib/nanook/wallet_account.rb

Instance Method Summary collapse

#account_id ⇒ String

The account id of this account.
#balance(unit: Nanook.default_unit) ⇒ Object

Returns a Hash containing the account’s balance.
#change_representative(representative) ⇒ Object

Sets the representative for the account.
#create(n = 1) ⇒ Nanook::WalletAccount⁺

Creates a new account, or multiple new accounts, in this wallet.
#delegators ⇒ Hash{Symbol=>String}

Returns information about this account’s delegators.
#destroy ⇒ Boolean

Unlinks the account from the wallet.
#exists? ⇒ Boolean

Returns a boolean indicating if the account exists.
#history(limit: 1000, unit: Nanook.default_unit) ⇒ Array<Hash{Symbol=>String}>

Returns an account’s history of send and receive payments.
#id ⇒ String

Returns the id of the account.
#info(detailed: false, unit: Nanook.default_unit) ⇒ Hash

Returns a Hash containing information about the account.
#initialize(rpc, wallet, account) ⇒ WalletAccount constructor

A new instance of WalletAccount.
#inspect ⇒ String
#last_modified_at ⇒ Time

Last modified time of the account in UTC time zone.
#ledger(limit: 1) ⇒ Object

Returns information about the given account as well as other accounts up the ledger.
#pay(to:, amount:, unit: Nanook::default_unit, id:) ⇒ String

Make a payment from an account in this wallet to another account on the nano network.
#pending(limit: 1000, detailed: false, unit: Nanook.default_unit) ⇒ Array<String>, Array<Hash{Symbol=>String|Integer}>

Returns information about pending blocks (payments) that are waiting to be received by the account.
#public_key ⇒ String

Returns the public key belonging to an account.
#receive(block = nil) ⇒ String, false

Receives a pending payment for this account.
#representative ⇒ String

Returns the representative account for the account.
#wallet_id ⇒ Object
#weight ⇒ Integer

Returns the account’s weight.

Constructor Details

#initialize(rpc, wallet, account) ⇒ `WalletAccount`

Returns a new instance of WalletAccount.

# File 'lib/nanook/wallet_account.rb', line 31

def initialize(rpc, wallet, account)
  @rpc = rpc
  @wallet = wallet
  @account = account
  @nanook_account_instance = nil

  unless @account.nil?
    # Wallet must contain the account
    unless Nanook::Wallet.new(@rpc, @wallet).contains?(@account)
      raise ArgumentError.new("Account does not exist in wallet. Account: #{@account}, wallet: #{@wallet}")
    end

    # An object to delegate account methods that don't
    # expect a wallet param in the RPC call, to allow this
    # class to support all methods that can be called on Nanook::Account
    @nanook_account_instance = Nanook::Account.new(@rpc, @account)
  end
end

Instance Method Details

#account_id ⇒ `String`

Returns the account id of this account.

Returns:

(String) —

the account id of this account



51
52
53

# File 'lib/nanook/wallet_account.rb', line 51

def account_id
  @account
end

#balance(unit: Nanook.default_unit) ⇒ `Object`

Returns a Hash containing the account’s balance.

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
# }

Parameters:

unit (Symbol) (defaults to: Nanook.default_unit) —

default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano See - What are Nano’s Units

Raises:

ArgumentError if an invalid unit was given.

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#change_representative(representative) ⇒ `Object`

Sets the representative for the account.

A representative is an account that will vote on your account’s 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 change block 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 "xrb...") to set as this account’s representative.

Example

account.change_representative("xrb_...")

Example response

"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F"

# File 'lib/nanook/wallet_account.rb', line 208

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})")
  end

  rpc(:account_representative_set, representative: representative)[:block]
end

#create(n = 1) ⇒ `Nanook::WalletAccount`⁺

Creates a new account, or multiple new accounts, in this wallet.

Example:

wallet.create    # => Creates 1 account, and return a {Nanook::WalletAccount}
wallet.create(2) # => Creates 2 accounts, and return an Array of {Nanook::WalletAccount}

Parameters:

n (Integer) (defaults to: 1) —

number of accounts to create

Returns:

(Nanook::WalletAccount) —

returns a single Nanook::WalletAccount if invoked with no argument
(Array<Nanook::WalletAccount>) —

returns an Array of Nanook::WalletAccount if method was called with argument n > 1

# File 'lib/nanook/wallet_account.rb', line 68

def create(n=1)
  if n < 1
    raise ArgumentError.new("number of accounts must be greater than 0")
  end

  if n == 1
    Nanook::WalletAccount.new(@rpc, @wallet, rpc(:account_create)[:account])
  else
    Array(rpc(:accounts_create, count: n)[:accounts]).map do |account|
      Nanook::WalletAccount.new(@rpc, @wallet, account)
    end
  end
end

#delegators ⇒ `Hash{Symbol=>String}`

Returns information about this account’s delegators.

Example response:

{
  :xrb_13bqhi1cdqq8yb9szneoc38qk899d58i5rcrgdk5mkdm86hekpoez3zxw5sd=>500000000000000000000000000000000000,
  :xrb_17k6ug685154an8gri9whhe5kb5z1mf5w6y39gokc1657sh95fegm8ht1zpn=>961647970820730000000000000000000000
}

Returns:

(Hash{Symbol=>String}) —

Delegators

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#destroy ⇒ `Boolean`

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.

Returns:

(Boolean) —

returns true if action was successful, otherwise false



88
89
90

# File 'lib/nanook/wallet_account.rb', line 88

def destroy
  rpc(:account_remove)[:removed] == 1
end

#exists? ⇒ `Boolean`

Returns a boolean indicating if the account exists.

Existence is determined by if the account has an open block. An open block is a special kind of block that gets published when an account receives a payment for the first time.

The reliability of this check depends on the node host having synchronized itself with most of the blocks on the nano network, otherwise you may get false when the account does exist. You can check if a node’s synchronization is particular low using Node#sync_progress.

Returns:

(Boolean) —

Indicates if this account exists in the nano network

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#history(limit: 1000, unit: Nanook.default_unit) ⇒ `Array<Hash{Symbol=>String}>`

Returns an account’s history of send and receive payments.

Example:

account.history
account.history(limit: 1)

Example response:

[
  {
   :type=>"send",
   :account=>"xrb_1kdc5u48j3hr5r7eof9iao47szqh81ndqgq5e5hrsn1g9a3sa4hkkcotn3uq",
   :amount=>2,
   :hash=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570"
  }
]

Example:

account.history
account.history(unit: :raw)

Example response:

[
  {
   :type=>"send",
   :account=>"xrb_1kdc5u48j3hr5r7eof9iao47szqh81ndqgq5e5hrsn1g9a3sa4hkkcotn3uq",
   :amount=>2000000000000000000000000000000,
   :hash=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570"
  }
]

Parameters:

limit (Integer) (defaults to: 1000) —

maximum number of history items to return
unit (Symbol) (defaults to: Nanook.default_unit) —

default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano See - What are Nano’s Units

Returns:

(Array<Hash{Symbol=>String}>) —

the history of send and receive payments for this account

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#id ⇒ `String`

Returns the id of the account.

Returns:

(String) —

the id of the account

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#info(detailed: false, unit: Nanook.default_unit) ⇒ `Hash`

Returns a Hash containing information about the account.

Example 1

account.info

Example 1 response

{
  :id=>"xrb_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5"
  :balance=>11.439597000000001,
  :block_count=>4
  :frontier=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
  :modified_timestamp=>1520500357,
  :open_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  :representative_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
}

Example 2

account.info(detailed: true)

Example 2 response

{
  :id=>"xrb_16u1uufyoig8777y6r8iqjtrw8sg8maqrm36zzcm95jmbd9i9aj5i8abr8u5"
  :balance=>11.439597000000001,
  :block_count=>4,
  :frontier=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
  :modified_timestamp=>1520500357,
  :open_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  :pending=>0,
  :public_key=>"A82C906460046D230D7D37C6663723DC3EFCECC4B3254EBF45294B66746F4FEF",
  :representative=>"xrb_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh",
  :representative_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
  :weight=>0
}

Parameters:

detailed (Boolean) (defaults to: false) —

(default is false). When true, four additional calls are made to the RPC to return more information
unit (Symbol) (defaults to: Nanook.default_unit) —

default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano See - What are Nano’s Units

Returns:

(Hash) —

information about the account containing:

+id

The account id

frontier

The latest block hash

open_block

The first block in every account’s blockchain. When this block was published the account was officially open

representative_block

The block that named the representative for the account

balance

Amount in NANO

last_modified

Unix timestamp

block_count

Number of blocks in the account’s blockchain

When detailed: true is passed as an argument, this method makes four additional calls to the RPC to return more information about an account:

weight

See #weight

pending

See #balance

representative

See #representative

public_key

See #public_key

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#inspect ⇒ `String`

Returns:

(String)



93
94
95

# File 'lib/nanook/wallet_account.rb', line 93

def inspect
  "#{self.class.name}(wallet_id: #{wallet_id}, account_id: #{account_id}, object_id: \"#{"0x00%x" % (object_id << 1)}\")"
end

#last_modified_at ⇒ `Time`

Returns last modified time of the account in UTC time zone.

Returns:

(Time) —

last modified time of the account in UTC time zone.

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#ledger(limit: 1) ⇒ `Object`

Returns information about the given account as well as other accounts up the ledger. The number of accounts returned is determined by the limit: argument.

The information in each Hash is the same as what the #info(detailed: false) method returns.

Arguments

limit:: Number of accounts to return in the ledger (default is 1)

Example

account.ledger(limit: 2)

Example response

 {
  :xrb_3c3ek3k8135f6e8qtfy8eruk9q3yzmpebes7btzncccdest8ymzhjmnr196j=>{
    :frontier=>"2C3C570EA8898443C0FD04A1C385A3E3A8C985AD792635FCDCEBB30ADF6A0570",
    :open_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
    :representative_block=>"C82376314C387080A753871A32AD70F4168080C317C5E67356F0A62EB5F34FF9",
    :balance=>11439597000000000000000000000000,
    :modified_timestamp=>1520500357,
    :block_count=>4
  },
  :xrb_3c3ettq59kijuuad5fnaq35itc9schtr4r7r6rjhmwjbairowzq3wi5ap7h8=>{ ... }
}

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#pay(to:, amount:, unit: Nanook::default_unit, id:) ⇒ `String`

Make a payment from an account in this wallet to another account on the nano network. Returns a send block hash if successful, or a Error if unsuccessful.

Note, there may be a delay in receiving a response due to Proof of Work being done. From the Nano RPC:

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.

Examples:

account.pay(to: "xrb_...", amount: 1.1, id: "myUniqueId123") # => "9AE2311..."
account.pay(to: "xrb_...", amount: 54000000000000, unit: :raw, id: "myUniqueId123") # => "9AE2311..."

Parameters:

to (String) —

account id of the recipient of your payment
amount (Integer|Float)
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
unit (Symbol) (defaults to: Nanook::default_unit) —

default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano See - What are Nano’s Units

Returns:

(String) —

the send block id for the payment

Raises:

(Nanook::Error) —

if unsuccesful

# File 'lib/nanook/wallet_account.rb', line 119

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 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
    amount
  end

  # account is called source, so don't use the normal rpc method
  p = {
    wallet: @wallet,
    source: @account,
    destination: to,
    amount: raw,
    id: id
  }

  response = @rpc.call(:send, p)

  if response.has_key?(:error)
    return Nanook::Error.new(response[:error])
  end

  response[:block]
end

#pending(limit: 1000, detailed: false, unit: Nanook.default_unit) ⇒ `Array<String>`, `Array<Hash{Symbol=>String|Integer}>`

Returns information about pending blocks (payments) that are waiting to be received by the account.

See also the #receive method of this class for how to receive a pending payment.

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.

Example 1:

account.pending # => ["000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F"]

Example 2:

account.pending(detailed: true)
# =>
# [
#   {
#     :block=>"000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F",
#     :amount=>6,
#     :source=>"xrb_3dcfozsmekr1tr9skf1oa5wbgmxt81qepfdnt7zicq5x3hk65fg4fqj58mbr"
#   },
#   { ... }
# ]

Example 3:

account.pending(detailed: true, unit: raw).first[:amount] # => 6000000000000000000000000000000

Parameters:

limit (Integer) (defaults to: 1000) —

number of pending blocks to return (default is 1000)
detailed (Boolean) (defaults to: false) —

return a more complex Hash of pending block information (default is false)
unit (Symbol) (defaults to: Nanook.default_unit) —

default is Nanook.default_unit. Must be one of UNITS. Represents the unit that the balances will be returned in. Note: this method interprets :nano as NANO, which is technically Mnano See - What are Nano’s Units

Returns:

(Array<String>)
(Array<Hash{Symbol=>String|Integer}>)

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#public_key ⇒ `String`

Returns the public key belonging to an account.

Example response:

"3068BB1CA04525BB0E416C485FE6A67FD52540227D267CC8B6E8DA958A7FA039"

Returns:

(String) —

public key of this account

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#receive(block = nil) ⇒ `String`, `false`

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 receive 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..."

Parameters:

block (String) (defaults to: nil) —

optional block id of pending payment. If not provided, the latest pending payment will be received

Returns:

(String) —

the receive block id
(false) —

if no block to receive

# File 'lib/nanook/wallet_account.rb', line 176

def receive(block=nil)
  if block.nil?
    _receive_without_block
  else
    _receive_with_block(block)
  end
end

#representative ⇒ `String`

Returns the representative account for the account. Representatives are accounts which cast votes in the case of a fork in the network.

Example response

"xrb_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh"

Returns:

(String) —

Representative account of this account

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

#wallet_id ⇒ `Object`



217
218
219

# File 'lib/nanook/wallet_account.rb', line 217

def wallet_id
  @wallet
end

#weight ⇒ `Integer`

Returns the account’s weight.

Weight is determined by the account’s balance, and represents the voting weight that account has on the network. Only accounts with greater than 256 weight can vote.

Example:

account.weight # => 0

Returns:

(Integer) —

the account’s weight

# File 'lib/nanook/wallet_account.rb', line 29

def_delegators :@nanook_account_instance, :balance, :delegators, :exists?, :history, :id, :info, :last_modified_at, :ledger, :pending, :public_key, :representative, :weight

Class: Nanook::WalletAccount

Instance Method Summary collapse

Constructor Details

#initialize(rpc, wallet, account) ⇒ WalletAccount

Instance Method Details

#account_id ⇒ String

#balance(unit: Nanook.default_unit) ⇒ Object

Example:

Example balance returned in raw:

#change_representative(representative) ⇒ Object

Arguments

Example

Example response

#create(n = 1) ⇒ Nanook::WalletAccount+

Example:

#delegators ⇒ Hash{Symbol=>String}

Example response:

#destroy ⇒ Boolean

#exists? ⇒ Boolean

#history(limit: 1000, unit: Nanook.default_unit) ⇒ Array<Hash{Symbol=>String}>

Example:

Example response:

Example:

Example response:

#id ⇒ String

#info(detailed: false, unit: Nanook.default_unit) ⇒ Hash

Example 1

Example 1 response

Example 2

Example 2 response

#inspect ⇒ String

#last_modified_at ⇒ Time

#ledger(limit: 1) ⇒ Object

Arguments

Example

Example response

#pay(to:, amount:, unit: Nanook::default_unit, id:) ⇒ String

Examples:

#pending(limit: 1000, detailed: false, unit: Nanook.default_unit) ⇒ Array<String>, Array<Hash{Symbol=>String|Integer}>

Example 1:

Example 2:

Example 3:

#public_key ⇒ String

Example response:

#receive(block = nil) ⇒ String, false

Examples

#representative ⇒ String

Example response

#wallet_id ⇒ Object

#weight ⇒ Integer

Example:

#initialize(rpc, wallet, account) ⇒ `WalletAccount`

#account_id ⇒ `String`

#balance(unit: Nanook.default_unit) ⇒ `Object`

#change_representative(representative) ⇒ `Object`

#create(n = 1) ⇒ `Nanook::WalletAccount`⁺

#delegators ⇒ `Hash{Symbol=>String}`

#destroy ⇒ `Boolean`

#exists? ⇒ `Boolean`

#history(limit: 1000, unit: Nanook.default_unit) ⇒ `Array<Hash{Symbol=>String}>`

#id ⇒ `String`

#info(detailed: false, unit: Nanook.default_unit) ⇒ `Hash`

#inspect ⇒ `String`

#last_modified_at ⇒ `Time`

#ledger(limit: 1) ⇒ `Object`

#pay(to:, amount:, unit: Nanook::default_unit, id:) ⇒ `String`

#pending(limit: 1000, detailed: false, unit: Nanook.default_unit) ⇒ `Array<String>`, `Array<Hash{Symbol=>String|Integer}>`

#public_key ⇒ `String`

#receive(block = nil) ⇒ `String`, `false`

#representative ⇒ `String`

#wallet_id ⇒ `Object`

#weight ⇒ `Integer`