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.

Parameters:

  • network (Coinbase::Network, Symbol) —

    The Network or Network ID

  • id (String) —

    The onchain Address ID



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.

Parameters:

  • asset_id (Symbol) —

    The Asset to retrieve the balance for

Returns:

  • (BigDecimal) —

    The balance of the Asset



68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/coinbase/address.rb', line 68

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.

Returns:

  • (BalanceMap) —

    The balances of the Address, keyed by asset ID. Ether balances are denominated in ETH.



57
58
59
60
61
62
63
 
# File 'lib/coinbase/address.rb', line 57

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.

Parameters:

  • amount (Integer, String, BigDecimal) —

    The amount of the asset to claim

  • asset_id (Symbol) —

    The asset to claim

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    (Optional) Additional options for the claim_stake operation. (see_more)

Returns:



159
160
161
162
163
 
# File 'lib/coinbase/address.rb', line 159

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.

Parameters:

  • amount (Integer, String, BigDecimal) —

    The amount of the asset to stake

  • asset_id (Symbol) —

    The asset to stake

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    (Optional) Additional options for the stake operation. (see_more)

Returns:



134
135
136
137
138
 
# File 'lib/coinbase/address.rb', line 134

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.

Parameters:

  • amount (Integer, String, BigDecimal) —

    The amount of the asset to unstake

  • asset_id (Symbol) —

    The asset to unstake

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    (Optional) Additional options for the unstake operation. (see_more)

Returns:



146
147
148
149
150
 
# File 'lib/coinbase/address.rb', line 146

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.

Returns:

  • (Boolean) —

    true if the Address can sign transactions



38
39
40
 
# File 'lib/coinbase/address.rb', line 38

def can_sign?
  false
end

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

Retrieves the claimable balance for the supplied asset.

Parameters:

  • asset_id (Symbol) —

    The asset to retrieve the claimable balance for

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    Additional options for fetching the claimable balance

Returns:

  • (BigDecimal) —

    The claimable balance



228
229
230
 
# File 'lib/coinbase/address.rb', line 228

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.

Parameters:

  • asset_id (Symbol) (defaults to: nil) —

    The ID of the Asset to transfer to the wallet.

Returns:

Raises:



112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/coinbase/address.rb', line 112

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…

Returns:



86
87
88
89
90
91
92
 
# File 'lib/coinbase/address.rb', line 86

def historical_balances(asset_id)
  Coinbase::Pagination.enumerate(
    ->(page) { list_historical_balance_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.

Parameters:

  • asset_id (Symbol) —

    The asset to retrieve staking rewards for

  • start_time (Time) (defaults to: DateTime.now.prev_week(1)) —

    The start time for the rewards. Defaults to 1 week ago.

  • end_time (Time) (defaults to: DateTime.now) —

    The end time for the rewards. Defaults to the current time.

Returns:



254
255
256
257
258
259
260
261
262
 
# File 'lib/coinbase/address.rb', line 254

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.

Returns:

  • (String) —

    a String representation of the Address



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

def inspect
  to_s
end

#reputation ⇒ Coinbase::AddressReputation

Returns the reputation of the Address.

Returns:



44
45
46
 
# File 'lib/coinbase/address.rb', line 44

def reputation
  @reputation ||= Coinbase::AddressReputation.fetch(network: network, address_id: id)
end

#risky? ⇒ Boolean

Returns wheth the Address’s reputation is risky.

Returns:

  • (Boolean) —

    true if the Address’s reputation is risky



50
51
52
 
# File 'lib/coinbase/address.rb', line 50

def risky?
  reputation.risky?
end

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

Retrieves the stakeable balance for the supplied asset.

Parameters:

  • asset_id (Symbol) —

    The asset to retrieve the stakeable balance for

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    Additional options for fetching the stakeable balance

Returns:

  • (BigDecimal) —

    The stakeable balance



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

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.

Parameters:

  • asset_id (Symbol) —

    The asset to retrieve staking balances for

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    (Optional) Additional options for fetching the staking balances

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]

Returns:

  • (Hash) —

    The staking balances

  • (BigDecimal) —

    :stakeable_balance The amount of the asset that can be staked

  • (BigDecimal) —

    :unstakeable_balance The amount of the asset that is currently staked and cannot be unstaked

  • (BigDecimal) —

    :claimable_balance The amount of the asset that can be claimed



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/coinbase/address.rb', line 175

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.

Parameters:

  • asset_id (Symbol) —

    The asset to retrieve staking rewards for

  • start_time (Time) (defaults to: DateTime.now.prev_week(1)) —

    The start time for the rewards. Defaults to 1 week ago.

  • end_time (Time) (defaults to: DateTime.now) —

    The end time for the rewards. Defaults to the current time.

  • format (Symbol) (defaults to: :usd) —

    The format to return the rewards in. Defaults to :usd.

Returns:



238
239
240
241
242
243
244
245
246
247
 
# File 'lib/coinbase/address.rb', line 238

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.

Returns:

  • (String) —

    a String representation of the Address



19
20
21
22
23
24
25
26
27
28
 
# File 'lib/coinbase/address.rb', line 19

def to_s
  Coinbase.pretty_print_object(
    self.class,
    **{
      id: id,
      network_id: network.id,
      reputation_score: @reputation.nil? ? nil : reputation.score
    }.compact
  )
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…

Returns:



98
99
100
101
102
103
104
 
# File 'lib/coinbase/address.rb', line 98

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.

Parameters:

  • asset_id (Symbol) —

    The asset to retrieve the unstakeable balance for

  • mode (Symbol) (defaults to: :default) —

    The staking mode. Defaults to :default.

  • options (Hash) (defaults to: {}) —

    Additional options for fetching the unstakeable balance

Returns:

  • (BigDecimal) —

    The unstakeable balance



219
220
221
 
# File 'lib/coinbase/address.rb', line 219

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