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, id) ⇒ Address

Returns a new Address object.

Parameters:

  • network_id (Symbol) —

    The Network ID

  • id (String) —

    The onchain Address ID



14
15
16
17
 
# File 'lib/coinbase/address.rb', line 14

def initialize(network_id, id)
  @network_id = Coinbase.to_sym(network_id)
  @id = id
end

Instance Attribute Details

#id ⇒ String (readonly)

The onchain Address ID

Returns:

  • (String) —

    the current value of id



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

def id
  @id
end

#network_id ⇒ Symbol (readonly)

The Network ID

Returns:

  • (Symbol) —

    the current value of network_id



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

def network_id
  @network_id
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



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

def balance(asset_id)
  response = Coinbase.call_api do
    addresses_api.get_external_address_balance(
      Coinbase.normalize_network(network_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.



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

def balances
  response = Coinbase.call_api do
    addresses_api.list_external_address_balances(Coinbase.normalize_network(network_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: {}) —

    Additional options for the claim_stake operation

Returns:



109
110
111
112
113
 
# File 'lib/coinbase/address.rb', line 109

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_id, 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: {}) —

    Additional options for the stake operation

Returns:



85
86
87
88
89
 
# File 'lib/coinbase/address.rb', line 85

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_id, 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: {}) —

    Additional options for the unstake operation

Returns:



97
98
99
100
101
 
# File 'lib/coinbase/address.rb', line 97

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_id, 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



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

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 the staking operation

Returns:

  • (BigDecimal) —

    The claimable balance



176
177
178
 
# File 'lib/coinbase/address.rb', line 176

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

#faucet ⇒ Coinbase::FaucetTransaction

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

Returns:

Raises:



70
71
72
73
74
75
76
 
# File 'lib/coinbase/address.rb', line 70

def faucet
  Coinbase.call_api do
    Coinbase::FaucetTransaction.new(
      addresses_api.request_external_faucet_funds(Coinbase.normalize_network(network_id), id)
    )
  end
end

#inspect ⇒ String

Same as to_s.

Returns:

  • (String) —

    a String representation of the Address



27
28
29
 
# File 'lib/coinbase/address.rb', line 27

def inspect
  to_s
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 the staking operation

Returns:

  • (BigDecimal) —

    The stakeable balance



158
159
160
 
# File 'lib/coinbase/address.rb', line 158

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: {}) —

    Additional options for the staking operation

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



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/coinbase/address.rb', line 123

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: Coinbase.normalize_network(network_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:



186
187
188
189
190
191
192
193
194
195
 
# File 'lib/coinbase/address.rb', line 186

def staking_rewards(asset_id, start_time: DateTime.now.prev_week(1), end_time: DateTime.now, format: :usd)
  StakingReward.list(
    network_id,
    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



21
22
23
 
# File 'lib/coinbase/address.rb', line 21

def to_s
  "Coinbase::Address{id: '#{id}', network_id: '#{network_id}'}"
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 the staking operation

Returns:

  • (BigDecimal) —

    The unstakeable balance



167
168
169
 
# File 'lib/coinbase/address.rb', line 167

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