Class: Coinbase::WalletAddress

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

Overview

A representation of a blockchain Address that belongs to a Coinbase::Wallet. Addresses are used to send and receive Assets, and should be created using Wallet#create_address. Addresses require an Eth::Key to sign transaction data.

Instance Attribute Summary

Attributes inherited from Address

#id, #network

Instance Method Summary collapse

Methods inherited from Address

#balance, #balances, #build_claim_stake_operation, #build_stake_operation, #build_unstake_operation, #claimable_balance, #faucet, #historical_balances, #historical_staking_balances, #inspect, #stakeable_balance, #staking_balances, #staking_rewards, #transactions, #unstakeable_balance

Constructor Details

#initialize(model, key) ⇒ WalletAddress

Returns a new Address object. Do not use this method directly. Instead, use Wallet#create_address, or use the Wallet's default_address.

Parameters:

  • model (Coinbase::Client::Address) —

    The underlying Address object

  • key (Eth::Key) —

    The key backing the Address. Can be nil.



15
16
17
18
19
20
 
# File 'lib/coinbase/address/wallet_address.rb', line 15

def initialize(model, key)
  @model = model
  @key = key

  super(model.network_id, model.address_id)
end

Instance Method Details

#can_sign? ⇒ Boolean

Returns whether the Address has a private key backing it to sign transactions.

Returns:

  • (Boolean) —

    Whether the Address has a private key backing it to sign transactions.



276
277
278
 
# File 'lib/coinbase/address/wallet_address.rb', line 276

def can_sign?
  !@key.nil?
end

#claim_stake(amount, asset_id, mode: :default, options: {}, interval_seconds: 5, timeout_seconds: 600) ⇒ Coinbase::StakingOperation

Claims the given amount of the given Asset

Parameters:

  • amount (Integer, Float, BigDecimal) —

    The amount of the Asset to claim.

  • asset_id (Symbol) —

    The ID of the Asset to stake. For Ether, :eth, :gwei, and :wei are supported.

  • 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)

  • interval_seconds (Integer) (defaults to: 5) —

    The number of seconds to wait between polling for updates. Defaults to 5.

  • timeout_seconds (Integer) (defaults to: 600) —

    The number of seconds to wait before timing out. Defaults to 600.

Returns:

Raises:

  • (Timeout::Error) —

    if the Staking Operation takes longer than the given timeout.



266
267
268
269
270
271
272
 
# File 'lib/coinbase/address/wallet_address.rb', line 266

def claim_stake(amount, asset_id, mode: :default, options: {}, interval_seconds: 5, timeout_seconds: 600)
  validate_can_perform_staking_action!(amount, asset_id, 'claimable_balance', mode, options)

  op = StakingOperation.create(amount, network, asset_id, id, wallet_id, 'claim_stake', mode, options)

  op.complete(@key, interval_seconds: interval_seconds, timeout_seconds: timeout_seconds)
end

#deploy_multi_token(uri:) ⇒ Coinbase::SmartContract

Deploys a new ERC1155 multi-token contract with the given URI.

Parameters:

  • uri (String) —

    The URI for the token metadata, where Address#id will be replaced with the token ID.

Returns:

Raises:



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/coinbase/address/wallet_address.rb', line 186

def deploy_multi_token(uri:)
  ensure_can_sign!

  smart_contract = SmartContract.create_multi_token_contract(
    address_id: id,
    wallet_id: wallet_id,
    uri: uri
  )

  return smart_contract if Coinbase.use_server_signer?

  smart_contract.sign(@key)
  smart_contract.deploy!
  smart_contract
end

#deploy_nft(name:, symbol:, base_uri:) ⇒ Coinbase::SmartContract

Deploys a new ERC721 NFT contract with the given name, symbol, and base URI.

Parameters:

  • name (String) —

    The name of the NFT contract.

  • symbol (String) —

    The symbol of the NFT contract.

  • base_uri (String) —

    The base URI for the NFT contract.

Returns:

Raises:



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/coinbase/address/wallet_address.rb', line 164

def deploy_nft(name:, symbol:, base_uri:)
  ensure_can_sign!

  smart_contract = SmartContract.create_nft_contract(
    address_id: id,
    wallet_id: wallet_id,
    name: name,
    symbol: symbol,
    base_uri: base_uri
  )

  return smart_contract if Coinbase.use_server_signer?

  smart_contract.sign(@key)
  smart_contract.deploy!
  smart_contract
end

#deploy_token(name:, symbol:, total_supply:) ⇒ Coinbase::SmartContract

Deploys a new ERC20 token contract with the given name, symbol, and total supply. whole units.

Parameters:

  • name (String) —

    The name of the token.

  • symbol (String) —

    The symbol of the token.

  • total_supply (Integer, BigDecimal) —

    The total supply of the token, denominated in

Returns:

Raises:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/coinbase/address/wallet_address.rb', line 140

def deploy_token(name:, symbol:, total_supply:)
  ensure_can_sign!

  smart_contract = SmartContract.create_token_contract(
    address_id: id,
    wallet_id: wallet_id,
    name: name,
    symbol: symbol,
    total_supply: total_supply
  )

  return smart_contract if Coinbase.use_server_signer?

  smart_contract.sign(@key)
  smart_contract.deploy!
  smart_contract
end

#export ⇒ String

Exports the Address's private key to a hex string.

Returns:

  • (String) —

    The Address's private key as a hex String



282
283
284
285
286
 
# File 'lib/coinbase/address/wallet_address.rb', line 282

def export
  raise 'Cannot export key without private key loaded' if @key.nil?

  @key.private_hex
end

#invoke_contract(contract_address:, method:, args:, abi: nil, amount: nil, asset_id: nil) ⇒ Coinbase::ContractInvocation

Invokes a contract method on the specified contract address, with the given ABI and arguments.

Parameters:

  • contract_address (String) —

    The address of the contract to invoke.

  • abi (Array<Hash>) (defaults to: nil) —

    The ABI of the contract to invoke.

  • method (String) —

    The method to invoke on the contract.

  • args (Hash) —

    The arguments to pass to the contract method. The keys should be the argument names, and the values should be the argument values.

  • amount (Integer, Float, BigDecimal) (defaults to: nil) —

    (Optional) The amount of the native Asset to send to a payable contract method.

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

    (Optional) The ID of the Asset to send to a payable contract method. The Asset must be a denomination of the native Asset. For Ethereum, :eth, :gwei, and :wei are supported.

Returns:



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/coinbase/address/wallet_address.rb', line 109

def invoke_contract(contract_address:, method:, args:, abi: nil, amount: nil, asset_id: nil)
  ensure_can_sign!
  ensure_sufficient_balance!(amount, asset_id) if amount && asset_id

  invocation = ContractInvocation.create(
    address_id: id,
    wallet_id: wallet_id,
    contract_address: contract_address,
    abi: abi,
    method: method,
    args: args,
    amount: amount,
    asset_id: asset_id,
    network: network
  )

  # If a server signer is managing keys, it will sign and broadcast the underlying transaction out of band.
  return invocation if Coinbase.use_server_signer?

  invocation.sign(@key)
  invocation.broadcast!
  invocation
end

#key=(key) ⇒ Object

Sets the private key backing the Address. This key is used to sign transactions.

Parameters:

  • key (Eth::Key) —

    The key backing the Address



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

def key=(key)
  raise 'Private key is already set' unless @key.nil?

  @key = key
end

#payload_signatures ⇒ Enumerable<Coinbase::PayloadSignature>

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

Returns:



308
309
310
 
# File 'lib/coinbase/address/wallet_address.rb', line 308

def payload_signatures
  PayloadSignature.list(wallet_id: wallet_id, address_id: id)
end

#sign_payload(unsigned_payload:) ⇒ Coinbase::PayloadSignature

Signs the given unsigned payload.

Parameters:

  • unsigned_payload (String) —

    The hex-encoded hashed unsigned payload for the Address to sign.

Returns:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/coinbase/address/wallet_address.rb', line 205

def sign_payload(unsigned_payload:)
  ensure_can_sign!

  unless Coinbase.use_server_signer?
    signature = Eth::Util.prefix_hex(@key.sign(Eth::Util.hex_to_bin(unsigned_payload)))
  end

  PayloadSignature.create(
    wallet_id: wallet_id,
    address_id: id,
    unsigned_payload: unsigned_payload,
    signature: signature
  )
end

#stake(amount, asset_id, mode: :default, options: {}, interval_seconds: 5, timeout_seconds: 600) ⇒ Coinbase::StakingOperation

Stakes the given amount of the given Asset. The stake operation may take a few minutes to complete in the case when infrastructure is spun up.

Parameters:

  • amount (Integer, Float, BigDecimal) —

    The amount of the Asset to stake.

  • asset_id (Symbol) —

    The ID of the Asset to stake. For Ether, :eth, :gwei, and :wei are supported.

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

    The staking mode. Defaults to :default.

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

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

  • interval_seconds (Integer) (defaults to: 5) —

    The number of seconds to wait between polling for updates. Defaults to 5.

  • timeout_seconds (Integer) (defaults to: 600) —

    The number of seconds to wait before timing out. Defaults to 600.

Returns:

Raises:

  • (Timeout::Error) —

    if the Staking Operation takes longer than the given timeout.



230
231
232
233
234
235
236
 
# File 'lib/coinbase/address/wallet_address.rb', line 230

def stake(amount, asset_id, mode: :default, options: {}, interval_seconds: 5, timeout_seconds: 600)
  validate_can_perform_staking_action!(amount, asset_id, 'stakeable_balance', mode, options)

  op = StakingOperation.create(amount, network, asset_id, id, wallet_id, 'stake', mode, options)

  op.complete(@key, interval_seconds: interval_seconds, timeout_seconds: timeout_seconds)
end

#to_s ⇒ String

Returns a String representation of the WalletAddress.

Returns:

  • (String) —

    a String representation of the WalletAddress



314
315
316
 
# File 'lib/coinbase/address/wallet_address.rb', line 314

def to_s
  "Coinbase::Address{id: '#{id}', network_id: '#{network.id}', wallet_id: '#{wallet_id}'}"
end

#trade(amount, from_asset_id, to_asset_id) ⇒ Coinbase::Trade

Trades the given amount of the given Asset for another Asset. Only same-network Trades are supported.

Parameters:

  • amount (Integer, Float, BigDecimal) —

    The amount of the Asset to send.

  • from_asset_id (Symbol) —

    The ID of the Asset to trade from. For Ether, :eth, :gwei, and :wei are supported.

  • to_asset_id (Symbol) —

    The ID of the Asset to trade to. For Ether, :eth, :gwei, and :wei are supported.

Returns:



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/coinbase/address/wallet_address.rb', line 74

def trade(amount, from_asset_id, to_asset_id)
  ensure_can_sign!
  ensure_sufficient_balance!(amount, from_asset_id)

  trade = Trade.create(
    address_id: id,
    amount: amount,
    from_asset_id: from_asset_id,
    to_asset_id: to_asset_id,
    network: network,
    wallet_id: wallet_id
  )

  # If a server signer is managing keys, it will sign and broadcast the underlying trade transaction out of band.
  return trade if Coinbase.use_server_signer?

  trade.transactions.each do |tx|
    tx.sign(@key)
  end

  trade.broadcast!
  trade
end

#trades ⇒ Enumerable<Coinbase::Trade>

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

Returns:

  • (Enumerable<Coinbase::Trade>) —

    Enumerator that returns the address's trades



300
301
302
 
# File 'lib/coinbase/address/wallet_address.rb', line 300

def trades
  Trade.list(wallet_id: wallet_id, address_id: id)
end

#transfer(amount, asset_id, destination, gasless: false) ⇒ Coinbase::Transfer

Transfers the given amount of the given Asset to the specified address or wallet. Only same-network Transfers are supported. Whether the transfer should be gasless. Defaults to false.

Parameters:

  • amount (Integer, Float, BigDecimal) —

    The amount of the Asset to send.

  • asset_id (Symbol) —

    The ID of the Asset to send. For Ether, :eth, :gwei, and :wei are supported.

  • destination (Wallet | Address | String) —

    The destination of the transfer. If a Wallet, sends to the Wallet's default address. If a String, interprets it as the address ID.

  • gasless (Boolean) (defaults to: false) —

    Whether gas fee for the transfer should be covered by Coinbase. Defaults to false. Check the API documentation for network and asset support.

Returns:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/coinbase/address/wallet_address.rb', line 46

def transfer(amount, asset_id, destination, gasless: false)
  ensure_can_sign!
  ensure_sufficient_balance!(amount, asset_id)

  transfer = Transfer.create(
    address_id: id,
    amount: amount,
    asset_id: asset_id,
    destination: destination,
    network: network,
    wallet_id: wallet_id,
    gasless: gasless
  )

  # If a server signer is managing keys, it will sign and broadcast the underlying transfer transaction out of band.
  return transfer if Coinbase.use_server_signer?

  transfer.sign(@key)
  transfer.broadcast!
  transfer
end

#transfers ⇒ Enumerable<Coinbase::Transfer>

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

Returns:



292
293
294
 
# File 'lib/coinbase/address/wallet_address.rb', line 292

def transfers
  Transfer.list(wallet_id: wallet_id, address_id: id)
end

#unstake(amount, asset_id, mode: :default, options: {}, interval_seconds: 5, timeout_seconds: 600) ⇒ Coinbase::StakingOperation

Unstakes the given amount of the given Asset

Parameters:

  • amount (Integer, Float, BigDecimal) —

    The amount of the Asset to unstake.

  • asset_id (Symbol) —

    The ID of the Asset to stake. For Ether, :eth, :gwei, and :wei are supported.

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

    The staking mode. Defaults to :default.

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

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

  • interval_seconds (Integer) (defaults to: 5) —

    The number of seconds to wait between polling for updates. Defaults to 5.

  • timeout_seconds (Integer) (defaults to: 600) —

    The number of seconds to wait before timing out. Defaults to 600.

Returns:

Raises:

  • (Timeout::Error) —

    if the Staking Operation takes longer than the given timeout.



248
249
250
251
252
253
254
 
# File 'lib/coinbase/address/wallet_address.rb', line 248

def unstake(amount, asset_id, mode: :default, options: {}, interval_seconds: 5, timeout_seconds: 600)
  validate_can_perform_staking_action!(amount, asset_id, 'unstakeable_balance', mode, options)

  op = StakingOperation.create(amount, network, asset_id, id, wallet_id, 'unstake', mode, options)

  op.complete(@key, interval_seconds: interval_seconds, timeout_seconds: timeout_seconds)
end

#wallet_id ⇒ String

Returns the Wallet ID of the Address.

Returns:

  • (String) —

    The Wallet ID



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

def wallet_id
  @model.wallet_id
end