Class: Coinbase::Address

Inherits:
Object
  • Object
show all
Defined in:
lib/coinbase/address.rb

Overview

A representation of a blockchain Address, which is a user-controlled account on a Network. Addresses are used to send and receive Assets.

Direct Known Subclasses

ExternalAddress, WalletAddress

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(network, id) ⇒ Address

Returns a new Address object.



12
13
14
15
 
# File 'lib/coinbase/address.rb', line 12

def initialize(network, id)
  @network = Coinbase::Network.from_id(network)
  @id = id
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



7
8
9
 
# File 'lib/coinbase/address.rb', line 7

def id
  @id
end

#network ⇒ Object (readonly)

Returns the value of attribute network.



7
8
9
 
# File 'lib/coinbase/address.rb', line 7

def network
  @network
end

Instance Method Details

#balance(asset_id) ⇒ BigDecimal

Returns the balance of the provided Asset.



49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/coinbase/address.rb', line 49

def balance(asset_id)
  response = Coinbase.call_api do
    addresses_api.get_external_address_balance(
      network.normalized_id,
      id,
      Coinbase::Asset.primary_denomination(asset_id).to_s
    )
  end

  return BigDecimal('0') if response.nil?

  Coinbase::Balance.from_model_and_asset_id(response, asset_id).amount
end

#balances ⇒ BalanceMap

Returns the balances of the Address.



38
39
40
41
42
43
44
 
# File 'lib/coinbase/address.rb', line 38

def balances
  response = Coinbase.call_api do
    addresses_api.list_external_address_balances(network.normalized_id, id)
  end

  Coinbase::BalanceMap.from_balances(response.data)
end

#build_claim_stake_operation(amount, asset_id, mode: :default, options: {}) ⇒ Coinbase::StakingOperation

Builds a claim_stake operation for the supplied asset.



140
141
142
143
144
 
# File 'lib/coinbase/address.rb', line 140

def build_claim_stake_operation(amount, asset_id, mode: :default, options: {})
  validate_can_perform_staking_action!(amount, asset_id, 'claimable_balance', mode, options)

  StakingOperation.build(amount, network, asset_id, id, 'claim_stake', mode, options)
end

#build_stake_operation(amount, asset_id, mode: :default, options: {}) ⇒ Coinbase::StakingOperation

Builds a stake operation for the supplied asset. The stake operation may take a few minutes to complete in the case when infrastructure is spun up.



115
116
117
118
119
 
# File 'lib/coinbase/address.rb', line 115

def build_stake_operation(amount, asset_id, mode: :default, options: {})
  validate_can_perform_staking_action!(amount, asset_id, 'stakeable_balance', mode, options)

  StakingOperation.build(amount, network, asset_id, id, 'stake', mode, options)
end

#build_unstake_operation(amount, asset_id, mode: :default, options: {}) ⇒ Coinbase::StakingOperation

Builds an unstake operation for the supplied asset.



127
128
129
130
131
 
# File 'lib/coinbase/address.rb', line 127

def build_unstake_operation(amount, asset_id, mode: :default, options: {})
  validate_can_perform_staking_action!(amount, asset_id, 'unstakeable_balance', mode, options)

  StakingOperation.build(amount, network, asset_id, id, 'unstake', mode, options)
end

#can_sign? ⇒ Boolean

Returns true if the Address can sign transactions.



31
32
33
 
# File 'lib/coinbase/address.rb', line 31

def can_sign?
  false
end

#claimable_balance(asset_id, mode: :default, options: {}) ⇒ BigDecimal

Retrieves the claimable balance for the supplied asset.



209
210
211
 
# File 'lib/coinbase/address.rb', line 209

def claimable_balance(asset_id, mode: :default, options: {})
  staking_balances(asset_id, mode: mode, options: options)[:claimable_balance]
end

#faucet(asset_id: nil) ⇒ Coinbase::FaucetTransaction

Requests funds for the address from the faucet and returns the faucet transaction. This is only supported on testnet networks.

Raises:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/coinbase/address.rb', line 93

def faucet(asset_id: nil)
  Coinbase.call_api do
    Coinbase::FaucetTransaction.new(
      addresses_api.request_external_faucet_funds(
        network.normalized_id,
        id,
        {
          asset_id: asset_id,
          skip_wait: true
        }.compact
      )
    )
  end
end

#historical_balances(asset_id) ⇒ Enumerable<Coinbase::HistoricalBalance>

Enumerates the historical balances for a given asset belonging of address. The result is an enumerator that lazily fetches from the server, and can be iterated over, converted to an array, etc…



67
68
69
70
71
72
73
 
# File 'lib/coinbase/address.rb', line 67

def historical_balances(asset_id)
  Coinbase::Pagination.enumerate(
    ->(page) { list_page(asset_id, page) }
  ) do |historical_balance|
    Coinbase::HistoricalBalance.from_model(historical_balance)
  end
end

#historical_staking_balances(asset_id, start_time: DateTime.now.prev_week(1), end_time: DateTime.now) ⇒ Enumerable<Coinbase::StakingBalance>

Fetches the historical staking balances for the address.



235
236
237
238
239
240
241
242
243
 
# File 'lib/coinbase/address.rb', line 235

def historical_staking_balances(asset_id, start_time: DateTime.now.prev_week(1), end_time: DateTime.now)
  StakingBalance.list(
    network,
    asset_id,
    id,
    start_time: start_time,
    end_time: end_time
  )
end

#inspect ⇒ String

Same as to_s.



25
26
27
 
# File 'lib/coinbase/address.rb', line 25

def inspect
  to_s
end

#stakeable_balance(asset_id, mode: :default, options: {}) ⇒ BigDecimal

Retrieves the stakeable balance for the supplied asset.



191
192
193
 
# File 'lib/coinbase/address.rb', line 191

def stakeable_balance(asset_id, mode: :default, options: {})
  staking_balances(asset_id, mode: mode, options: options)[:stakeable_balance]
end

#staking_balances(asset_id, mode: :default, options: {}) ⇒ Hash, BigDecimal

Retrieves the balances used for staking for the supplied asset.

Options Hash (options:):

  • (Optional) (String) —

    :validator_pub_keys List of comma separated validator public keys to retrieve staking balances for. (default: all validators) [asset_id: :eth, mode: :native]



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/coinbase/address.rb', line 156

def staking_balances(asset_id, mode: :default, options: {})
  context_model = Coinbase.call_api do
    stake_api.get_staking_context(
      {
        asset_id: asset_id,
        network_id: network.normalized_id,
        address_id: id,
        options: {
          mode: mode
        }.merge(options)
      }
    )
  end.context

  {
    stakeable_balance: Coinbase::Balance.from_model_and_asset_id(
      context_model.stakeable_balance,
      asset_id
    ).amount,
    unstakeable_balance: Coinbase::Balance.from_model_and_asset_id(
      context_model.unstakeable_balance,
      asset_id
    ).amount,
    claimable_balance: Coinbase::Balance.from_model_and_asset_id(
      context_model.claimable_balance,
      asset_id
    ).amount
  }
end

#staking_rewards(asset_id, start_time: DateTime.now.prev_week(1), end_time: DateTime.now, format: :usd) ⇒ Enumerable<Coinbase::StakingReward>

Lists the staking rewards for the address.



219
220
221
222
223
224
225
226
227
228
 
# File 'lib/coinbase/address.rb', line 219

def staking_rewards(asset_id, start_time: DateTime.now.prev_week(1), end_time: DateTime.now, format: :usd)
  StakingReward.list(
    network,
    asset_id,
    [id],
    start_time: start_time,
    end_time: end_time,
    format: format
  )
end

#to_s ⇒ String

Returns a String representation of the Address.



19
20
21
 
# File 'lib/coinbase/address.rb', line 19

def to_s
  Coinbase.pretty_print_object(self.class, id: id, network_id: network.id)
end

#transactions ⇒ Enumerable<Coinbase::HistoricalBalance>

Enumerates the transactions of address. The result is an enumerator that lazily fetches from the server, and can be iterated over, converted to an array, etc…



79
80
81
82
83
84
85
 
# File 'lib/coinbase/address.rb', line 79

def transactions
  Coinbase::Pagination.enumerate(
    ->(page) { list_transaction_page(page) }
  ) do |transaction|
    Coinbase::Transaction.new(transaction)
  end
end

#unstakeable_balance(asset_id, mode: :default, options: {}) ⇒ BigDecimal

Retrieves the unstakeable balance for the supplied asset.



200
201
202
 
# File 'lib/coinbase/address.rb', line 200

def unstakeable_balance(asset_id, mode: :default, options: {})
  staking_balances(asset_id, mode: mode, options: options)[:unstakeable_balance]
end