coinbase-sdk 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cac6b46a83009db9f165f0a2c4396122a2bf4bfa5bf895867b135695c346465e
-  data.tar.gz: 0b8cfea979b389b9890a09104b8c7533e334873a789b19d7f704789cdcf6a70d
+  metadata.gz: 98cd32134ee8acb14c9dc018f39e7af188646b546998c4182cd50d7ae75f2816
+  data.tar.gz: df6ff19c63798ec10f054972aa75edef79fe65ae39c93cbe0941c77db251e5d6
 SHA512:
-  metadata.gz: bccd3af15fec48789603988eadf3c67ad4ec67e5b3081fd2f06c7877d6ac35c6d2eda16db533ff149cf2f9f38d59ba38527284a0205529c84da6ac781dad8e3a
-  data.tar.gz: 072d5372f38da2b9a3eb97a024f4a289ac7ef1906df8cf1da22de0b37c77e18b9a724db7771019fc9c6eb3834720f48010edb869f310dcc114429cb0e0bd1403
+  metadata.gz: a209d25aa72fc185fb667a5ef7b8de617341dba449b0a02b15ad95bc0c434140932353e12258f4665b35ef60e37b5346efca76db811cc5a308cfc69b907f37b8
+  data.tar.gz: 8856f048ea3ecb664559665e2422d60b6c12d607526aea4bea75f8e8273cf0584b2206e14dcb4e99bdca3436114b03961558be36029b40614d018028f9d41183

data/lib/coinbase/address.rb

@@ -15,7 +15,7 @@ module Coinbase
     # Returns a new Address object. Do not use this method directly. Instead, use Wallet#create_address, or use
     # the Wallet's default_address.
     # @param model [Coinbase::Client::Address] The underlying Address object
-    # @param key [Eth::Key] The key backing the Address
+    # @param key [Eth::Key] The key backing the Address. Can be nil.
     def initialize(model, key)
       @model = model
       @key = key
@@ -35,45 +35,40 @@ module Coinbase
 
     # Returns the Address ID.
     # @return [String] The Address ID
-    def address_id
+    def id
       @model.address_id
     end
 
+    # Sets the private key backing the Address. This key is used to sign transactions.
+    # @param key [Eth::Key] The key backing the Address
+    def key=(key)
+      raise 'Private key is already set' unless @key.nil?
+
+      @key = key
+    end
+
     # Returns the balances of the Address.
     # @return [BalanceMap] The balances of the Address, keyed by asset ID. Ether balances are denominated
     #  in ETH.
-    def list_balances
+    def balances
       response = Coinbase.call_api do
-        addresses_api.list_address_balances(wallet_id, address_id)
+        addresses_api.list_address_balances(wallet_id, id)
       end
 
-      Coinbase.to_balance_map(response)
+      Coinbase::BalanceMap.from_balances(response.data)
     end
 
     # Returns the balance of the provided Asset.
     # @param asset_id [Symbol] The Asset to retrieve the balance for
     # @return [BigDecimal] The balance of the Asset
-    def get_balance(asset_id)
-      normalized_asset_id = normalize_asset_id(asset_id)
-
+    def balance(asset_id)
       response = Coinbase.call_api do
-        addresses_api.get_address_balance(wallet_id, address_id, normalized_asset_id.to_s)
+        addresses_api.get_address_balance(wallet_id, id, Coinbase::Asset.primary_denomination(asset_id).to_s)
       end
 
       return BigDecimal('0') if response.nil?
 
-      amount = BigDecimal(response.amount)
-
-      case asset_id
-      when :eth
-        amount / BigDecimal(Coinbase::WEI_PER_ETHER.to_s)
-      when :gwei
-        amount / BigDecimal(Coinbase::GWEI_PER_ETHER.to_s)
-      when :usdc
-        amount / BigDecimal(Coinbase::ATOMIC_UNITS_PER_USDC.to_s)
-      else
-        amount
-      end
+      Coinbase::Balance.from_model_and_asset_id(response, asset_id).amount
     end
 
     # Transfers the given amount of the given Asset to the given address. Only same-Network Transfers are supported.
@@ -83,36 +78,34 @@ module Coinbase
     #  default address. If a String, interprets it as the address ID.
     # @return [String] The hash of the Transfer transaction.
     def transfer(amount, asset_id, destination)
-      raise ArgumentError, "Unsupported asset: #{asset_id}" unless Coinbase::SUPPORTED_ASSET_IDS[asset_id]
+      raise 'Cannot transfer from address without private key loaded' if @key.nil?
+
+      raise ArgumentError, "Unsupported asset: #{asset_id}" unless Coinbase::Asset.supported?(asset_id)
 
       if destination.is_a?(Wallet)
         raise ArgumentError, 'Transfer must be on the same Network' if destination.network_id != network_id
 
-        destination = destination.default_address.address_id
+        destination = destination.default_address.id
       elsif destination.is_a?(Address)
         raise ArgumentError, 'Transfer must be on the same Network' if destination.network_id != network_id
 
-        destination = destination.address_id
+        destination = destination.id
       end
 
-      current_balance = get_balance(asset_id)
+      current_balance = balance(asset_id)
       if current_balance < amount
         raise ArgumentError, "Insufficient funds: #{amount} requested, but only #{current_balance} available"
       end
 
-      normalized_amount = normalize_asset_amount(amount, asset_id)
-
-      normalized_asset_id = normalize_asset_id(asset_id)
-
       create_transfer_request = {
-        amount: normalized_amount.to_i.to_s,
+        amount: Coinbase::Asset.to_atomic_amount(amount, asset_id).to_i.to_s,
         network_id: network_id,
-        asset_id: normalized_asset_id.to_s,
+        asset_id: Coinbase::Asset.primary_denomination(asset_id).to_s,
         destination: destination
       }
 
       transfer_model = Coinbase.call_api do
-        transfers_api.create_transfer(wallet_id, address_id, create_transfer_request)
+        transfers_api.create_transfer(wallet_id, id, create_transfer_request)
       end
 
       transfer = Coinbase::Transfer.new(transfer_model)
@@ -127,16 +120,22 @@ module Coinbase
       }
 
       transfer_model = Coinbase.call_api do
-        transfers_api.broadcast_transfer(wallet_id, address_id, transfer.transfer_id, broadcast_transfer_request)
+        transfers_api.broadcast_transfer(wallet_id, id, transfer.id, broadcast_transfer_request)
       end
 
       Coinbase::Transfer.new(transfer_model)
     end
 
+    # Returns whether the Address has a private key backing it to sign transactions.
+    # @return [Boolean] Whether the Address has a private key backing it to sign transactions.
+    def can_sign?
+      !@key.nil?
+    end
+
     # Returns a String representation of the Address.
     # @return [String] a String representation of the Address
     def to_s
-      "Coinbase::Address{address_id: '#{address_id}', network_id: '#{network_id}', wallet_id: '#{wallet_id}'}"
+      "Coinbase::Address{id: '#{id}', network_id: '#{network_id}', wallet_id: '#{wallet_id}'}"
     end
 
     # Same as to_s.
@@ -148,75 +147,46 @@ module Coinbase
     # Requests funds for the address from the faucet and returns the faucet transaction.
     # This is only supported on testnet networks.
     # @return [Coinbase::FaucetTransaction] The successful faucet transaction
-    # @raise [Coinbase::FaucetLimitReached] If the faucet limit has been reached for the address or user.
+    # @raise [Coinbase::FaucetLimitReachedError] If the faucet limit has been reached for the address or user.
     # @raise [Coinbase::Client::ApiError] If an unexpected error occurs while requesting faucet funds.
     def faucet
       Coinbase.call_api do
-        Coinbase::FaucetTransaction.new(addresses_api.request_faucet_funds(wallet_id, address_id))
+        Coinbase::FaucetTransaction.new(addresses_api.request_faucet_funds(wallet_id, id))
       end
     end
 
     # Exports the Address's private key to a hex string.
     # @return [String] The Address's private key as a hex String
     def export
+      raise 'Cannot export key without private key loaded' if @key.nil?
+
       @key.private_hex
     end
 
-    # Lists the IDs of all Transfers associated with the given Wallet and Address.
-    # @return [Array<String>] The IDs of all Transfers belonging to the Wallet and Address
-    def list_transfer_ids
-      transfer_ids = []
+    # Returns all of the transfers associated with the address.
+    # @return [Array<Coinbase::Transfer>] The transfers associated with the address
+    def transfers
+      transfers = []
       page = nil
 
       loop do
+        puts "fetch transfers page: #{page}"
         response = Coinbase.call_api do
-          transfers_api.list_transfers(wallet_id, address_id, { limit: 100, page: page })
+          transfers_api.list_transfers(wallet_id, id, { limit: 100, page: page })
         end
 
-        transfer_ids.concat(response.data.map(&:transfer_id)) if response.data
+        transfers.concat(response.data.map { |transfer| Coinbase::Transfer.new(transfer) }) if response.data
 
         break unless response.has_more
 
         page = response.next_page
       end
 
-      transfer_ids
+      transfers
     end
 
     private
 
-    # Normalizes the amount of the Asset to send to the atomic unit.
-    # @param amount [Integer, Float, BigDecimal] The amount to normalize
-    # @param asset_id [Symbol] The ID of the Asset being transferred
-    # @return [BigDecimal] The normalized amount in atomic units
-    def normalize_asset_amount(amount, asset_id)
-      big_amount = BigDecimal(amount.to_s)
-
-      case asset_id
-      when :eth
-        big_amount * Coinbase::WEI_PER_ETHER
-      when :gwei
-        big_amount * Coinbase::WEI_PER_GWEI
-      when :usdc
-        big_amount * Coinbase::ATOMIC_UNITS_PER_USDC
-      when :weth
-        big_amount * Coinbase::WEI_PER_ETHER
-      else
-        big_amount
-      end
-    end
-
-    # Normalizes the asset ID to use during requests.
-    # @param asset_id [Symbol] The asset ID to normalize
-    # @return [Symbol] The normalized asset ID
-    def normalize_asset_id(asset_id)
-      if %i[wei gwei].include?(asset_id)
-        :eth
-      else
-        asset_id
-      end
-    end
-
     def addresses_api
       @addresses_api ||= Coinbase::Client::AddressesApi.new(Coinbase.configuration.api_client)
     end

data/lib/coinbase/asset.rb

@@ -3,7 +3,63 @@
 module Coinbase
   # A representation of an Asset.
   class Asset
-    attr_reader :network_id, :asset_id, :display_name, :address_id
+    # Retuns whether the provided asset ID is supported.
+    # @param asset_id [Symbol] The Asset ID
+    # @return [Boolean] Whether the Asset ID is supported
+    def self.supported?(asset_id)
+      !!Coinbase::SUPPORTED_ASSET_IDS[asset_id]
+    end
+
+    # Converts the amount of the Asset to the atomic units of the primary denomination of the Asset.
+    # @param amount [Integer, Float, BigDecimal] The amount to normalize
+    # @param asset_id [Symbol] The ID of the Asset being transferred
+    # @return [BigDecimal] The normalized amount in atomic units
+    def self.to_atomic_amount(amount, asset_id)
+      case asset_id
+      when :eth
+        amount * BigDecimal(Coinbase::WEI_PER_ETHER.to_s)
+      when :gwei
+        amount * BigDecimal(Coinbase::WEI_PER_GWEI.to_s)
+      when :usdc
+        amount * BigDecimal(Coinbase::ATOMIC_UNITS_PER_USDC.to_s)
+      when :weth
+        amount * BigDecimal(Coinbase::WEI_PER_ETHER)
+      else
+        amount
+      end
+    end
+
+    # Converts an amount from the atomic value of the primary denomination of the provided Asset ID
+    # to whole units of the specified asset ID.
+    # @param atomic_amount [BigDecimal] The amount in atomic units
+    # @param asset_id [Symbol] The Asset ID
+    # @return [BigDecimal] The amount in whole units of the specified asset ID
+    def self.from_atomic_amount(atomic_amount, asset_id)
+      case asset_id
+      when :eth
+        atomic_amount / BigDecimal(Coinbase::WEI_PER_ETHER.to_s)
+      when :gwei
+        atomic_amount / BigDecimal(Coinbase::WEI_PER_GWEI.to_s)
+      when :usdc
+        atomic_amount / BigDecimal(Coinbase::ATOMIC_UNITS_PER_USDC.to_s)
+      when :weth
+        atomic_amount / BigDecimal(Coinbase::WEI_PER_ETHER)
+      else
+        atomic_amount
+      end
+    end
+
+    # Returns the primary denomination for the provided Asset ID.
+    # For assets with multiple denominations, e.g. eth can also be denominated in wei and gwei,
+    # this method will return the primary denomination.
+    # e.g. eth.
+    # @param asset_id [Symbol] The Asset ID
+    # @return [Symbol] The primary denomination for the Asset ID
+    def self.primary_denomination(asset_id)
+      return :eth if %i[wei gwei].include?(asset_id)
+
+      asset_id
+    end
 
     # Returns a new Asset object. Do not use this method. Instead, use the Asset constants defined in
     # the Coinbase module.
@@ -17,5 +73,20 @@ module Coinbase
       @display_name = display_name
       @address_id = address_id
     end
+
+    attr_reader :network_id, :asset_id, :display_name, :address_id
+
+    # Returns a string representation of the Asset.
+    # @return [String] a string representation of the Asset
+    def to_s
+      "Coinbase::Asset{network_id: '#{network_id}', asset_id: '#{asset_id}', display_name: '#{display_name}'" +
+        (address_id.nil? ? '}' : ", address_id: '#{address_id}'}")
+    end
+
+    # Same as to_s.
+    # @return [String] a string representation of the Balance
+    def inspect
+      to_s
+    end
   end
 end

data/lib/coinbase/balance.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Coinbase
+  # A representation of an Balance.
+  class Balance
+    # Converts a Coinbase::Client::Balance model to a Coinbase::Balance
+    # @param balance_model [Coinbase::Client::Balance] The balance fetched from the API.
+    # @return [Balance] The converted Balance object.
+    def self.from_model(balance_model)
+      asset_id = Coinbase.to_sym(balance_model.asset.asset_id.downcase)
+
+      from_model_and_asset_id(balance_model, asset_id)
+    end
+
+    # Converts a Coinbase::Client::Balance model and asset ID to a Coinbase::Balance
+    # This can be used to specify a non-primary denomination that we want the balance
+    # to be converted to.
+    # @param balance_model [Coinbase::Client::Balance] The balance fetched from the API.
+    # @param asset_id [Symbol] The Asset ID of the denomination we want returned.
+    # @return [Balance] The converted Balance object.
+    def self.from_model_and_asset_id(balance_model, asset_id)
+      new(
+        amount: Coinbase::Asset.from_atomic_amount(BigDecimal(balance_model.amount), asset_id),
+        asset_id: asset_id
+      )
+    end
+
+    # Returns a new Balance object. Do not use this method. Instead, use Balance.from_model or
+    # Balance.from_model_and_asset_id.
+    # @param amount [BigDecimal] The amount of the Asset
+    # @param asset_id [Symbol] The Asset ID
+    def initialize(amount:, asset_id:)
+      @amount = amount
+      @asset_id = asset_id
+    end
+
+    attr_reader :amount, :asset_id
+
+    # Returns a string representation of the Balance.
+    # @return [String] a string representation of the Balance
+    def to_s
+      "Coinbase::Balance{amount: '#{amount.to_i}', asset_id: '#{asset_id}'}"
+    end
+
+    # Same as to_s.
+    # @return [String] a string representation of the Balance
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/coinbase/balance_map.rb

@@ -5,31 +5,43 @@ require 'bigdecimal'
 module Coinbase
   # A convenience class for printing out Asset balances in a human-readable format.
   class BalanceMap < Hash
-    # Returns a new BalanceMap object.
-    # @param hash [Map<Symbol, BigDecimal>] The hash to initialize with
-    def initialize(hash = {})
-      super()
-      hash.each do |key, value|
-        self[key] = value
+    # Converts a list of Coinbase::Client::Balance models to a Coinbase::BalanceMap.
+    # @param balances [Array<Coinbase::Client::Balance>] The list of balances fetched from the API.
+    # @return [BalanceMap] The converted BalanceMap object.
+    def self.from_balances(balances)
+      BalanceMap.new.tap do |balance_map|
+        balances.each do |balance_model|
+          balance = Coinbase::Balance.from_model(balance_model)
+
+          balance_map.add(balance)
+        end
       end
     end
 
+    # Adds a balance to the map.
+    # @param balance [Coinbase::Balance] The balance to add to the map.
+    def add(balance)
+      raise ArgumentError, 'balance must be a Coinbase::Balance' unless balance.is_a?(Coinbase::Balance)
+
+      self[balance.asset_id] = balance.amount
+    end
+
     # Returns a string representation of the balance map.
-    # @return [String] The string representation of the balance
+    # @return [String] The string representation of the balance map
     def to_s
       to_string
     end
 
     # Returns a string representation of the balance map.
-    # @return [String] The string representation of the balance
+    # @return [String] The string representation of the balance map
     def inspect
       to_string
     end
 
     private
 
-    # Returns a string representation of the balance.
-    # @return [String] The string representation of the balance
+    # Returns a string representation of the balance map.
+    # @return [String] The string representation of the balance map
     def to_string
       result = {}
 

data/lib/coinbase/middleware.rb

@@ -12,8 +12,11 @@ module Coinbase
     # Returns the default middleware configuration for the Coinbase SDK.
     def self.config
       Coinbase::Client::Configuration.default.tap do |config|
+        uri = URI(Coinbase.configuration.api_url)
+
         config.debugging = Coinbase.configuration.debug_api
-        config.host = Coinbase.configuration.api_url
+        config.host = uri.host + (uri.port ? ":#{uri.port}" : '')
+        config.scheme = uri.scheme if uri.scheme
         config.request(:authenticator)
       end
     end

data/lib/coinbase/transfer.rb

@@ -37,7 +37,7 @@ module Coinbase
 
     # Returns the Transfer ID.
     # @return [String] The Transfer ID
-    def transfer_id
+    def id
       @model.transfer_id
     end
 
@@ -179,7 +179,7 @@ module Coinbase
     # Returns a String representation of the Transfer.
     # @return [String] a String representation of the Transfer
     def to_s
-      "Coinbase::Transfer{transfer_id: '#{transfer_id}', network_id: '#{network_id}', " \
+      "Coinbase::Transfer{transfer_id: '#{id}', network_id: '#{network_id}', " \
         "from_address_id: '#{from_address_id}', destination_address_id: '#{destination_address_id}', " \
         "asset_id: '#{asset_id}', amount: '#{amount}', transaction_hash: '#{transaction_hash}', " \
         "transaction_link: '#{transaction_link}', status: '#{status}'}"

data/lib/coinbase/user.rb

@@ -15,57 +15,63 @@ module Coinbase
 
     # Returns the User ID.
     # @return [String] the User ID
-    def user_id
+    def id
       @model.id
     end
 
     # Creates a new Wallet belonging to the User.
+    # @param network_id [String] (Optional) the ID of the blockchain network. Defaults to 'base-sepolia'.
     # @return [Coinbase::Wallet] the new Wallet
-    def create_wallet
-      create_wallet_request = {
-        wallet: {
-          # TODO: Don't hardcode this.
-          network_id: 'base-sepolia'
-        }
-      }
-      opts = { create_wallet_request: create_wallet_request }
-
-      model = Coinbase.call_api do
-        wallets_api.create_wallet(opts)
-      end
+    def create_wallet(create_wallet_options = {})
+      # For ruby 2.7 compatibility we cannot pass in keyword args when the create wallet
+      # options is empty
+      return Wallet.create if create_wallet_options.empty?
 
-      Wallet.new(model)
+      Wallet.create(**create_wallet_options)
     end
 
     # Imports a Wallet belonging to the User.
     # @param data [Coinbase::Wallet::Data] the Wallet data to import
     # @return [Coinbase::Wallet] the imported Wallet
     def import_wallet(data)
-      model = Coinbase.call_api do
-        wallets_api.get_wallet(data.wallet_id)
-      end
+      Wallet.import(data)
+    end
+
+    # Lists the Wallets belonging to the User.
+    # @param page_size [Integer] (Optional) the number of Wallets to return per page. Defaults to 10
+    # @param next_page_token [String] (Optional) the token for the next page of Wallets
+    # @return [Coinbase::Wallet] the Wallets belonging to the User
+    def wallets(page_size: 10, next_page_token: nil)
+      opts = {
+        limit: page_size
+      }
+
+      opts[:page] = next_page_token unless next_page_token.nil?
 
-      address_count = Coinbase.call_api do
-        addresses_api.list_addresses(model.id).total_count
+      wallet_list = Coinbase.call_api do
+        wallets_api.list_wallets(opts)
       end
 
-      Wallet.new(model, seed: data.seed, address_count: address_count)
-    end
+      # A map from wallet_id to address models.
+      address_model_map = {}
 
-    # Lists the IDs of the Wallets belonging to the User.
-    # @return [Array<String>] the IDs of the Wallets belonging to the User
-    def list_wallet_ids
-      wallets = Coinbase.call_api do
-        wallets_api.list_wallets
+      wallet_list.data.each do |wallet_model|
+        addresses_list = Coinbase.call_api do
+          addresses_api.list_addresses(wallet_model.id, { limit: Coinbase::Wallet::MAX_ADDRESSES })
+        end
+
+        address_model_map[wallet_model.id] = addresses_list.data
       end
 
-      wallets.data.map(&:id)
+      wallet_list.data.map do |wallet_model|
+        Wallet.new(wallet_model, seed: '', address_models: address_model_map[wallet_model.id])
+      end
     end
 
-    # Saves a wallet to local file system. Wallet saved this way can be re-instantiated with `load_wallets` function,
-    # provided the backup_file is available. This is an insecure method of storing wallet seeds and should only be used
-    # for development purposes. If you call save_wallet twice with wallets containing the same wallet_id, the backup
-    # will be overwritten during the second attempt.
+    # Saves a wallet to local file system. Wallet saved this way can be re-instantiated with load_wallets_from_local
+    # function, provided the backup_file is available. This is an insecure method of storing wallet seeds and should
+    # only be used for development purposes. If you call save_wallet_locally! twice with wallets containing the same
+    # wallet_id, the backup will be overwritten during the second attempt.
     # The default backup_file is `seeds.json` in the root folder. It can be configured by changing
     # Coinbase.configuration.backup_file_path.
     #
@@ -73,7 +79,7 @@ module Coinbase
     # @param encrypt [bool] (Optional) Boolean representing whether the backup persisted to local file system should be
     # encrypted or not. Data is unencrypted by default.
     # @return [Coinbase::Wallet] the saved wallet.
-    def save_wallet(wallet, encrypt: false)
+    def save_wallet_locally!(wallet, encrypt: false)
       existing_seeds_in_store = existing_seeds
       data = wallet.export
       seed_to_store = data.seed
@@ -107,7 +113,7 @@ module Coinbase
 
     # Loads all wallets belonging to the User with backup persisted to the local file system.
     # @return [Map<String>Coinbase::Wallet] the map of wallet_ids to the wallets.
-    def load_wallets
+    def load_wallets_from_local
       existing_seeds_in_store = existing_seeds
       raise ArgumentError, 'Backup file not found' if existing_seeds_in_store == {}
 
@@ -141,7 +147,7 @@ module Coinbase
     # Returns a string representation of the User.
     # @return [String] a string representation of the User
     def to_s
-      "Coinbase::User{user_id: '#{user_id}'}"
+      "Coinbase::User{user_id: '#{id}'}"
     end
 
     # Same as to_s.

data/lib/coinbase/wallet.rb

@@ -12,40 +12,85 @@ module Coinbase
   # list their balances, and transfer Assets to other Addresses. Wallets should be created through User#create_wallet or
   # User#import_wallet.
   class Wallet
+    attr_reader :addresses, :model
+
+    # The maximum number of addresses in a Wallet.
+    MAX_ADDRESSES = 20
+
+    class << self
+      # Imports a Wallet from previously exported wallet data.
+      # @param data [Coinbase::Wallet::Data] the Wallet data to import
+      # @return [Coinbase::Wallet] the imported Wallet
+      def import(data)
+        raise ArgumentError, 'data must be a Coinbase::Wallet::Data object' unless data.is_a?(Data)
+
+        model = Coinbase.call_api do
+          wallets_api.get_wallet(data.wallet_id)
+        end
+
+        address_list = Coinbase.call_api do
+          addresses_api.list_addresses(model.id, { limit: MAX_ADDRESSES })
+        end
+
+        new(model, seed: data.seed, address_models: address_list.data)
+      end
+
+      # Creates a new Wallet on the specified Network and generate a default address for it.
+      # @param network_id [String] (Optional) the ID of the blockchain network. Defaults to 'base-sepolia'.
+      # @return [Coinbase::Wallet] the new Wallet
+      def create(network_id: 'base-sepolia')
+        model = Coinbase.call_api do
+          wallets_api.create_wallet(
+            create_wallet_request: {
+              wallet: {
+                network_id: network_id
+              }
+            }
+          )
+        end
+
+        wallet = new(model)
+
+        wallet.create_address
+
+        wallet
+      end
+
+      private
+
+      # TODO: Memoize these objects in a thread-safe way at the top-level.
+      def addresses_api
+        Coinbase::Client::AddressesApi.new(Coinbase.configuration.api_client)
+      end
+
+      def wallets_api
+        Coinbase::Client::WalletsApi.new(Coinbase.configuration.api_client)
+      end
+    end
+
     # Returns a new Wallet object. Do not use this method directly. Instead, use User#create_wallet or
     # User#import_wallet.
     # @param model [Coinbase::Client::Wallet] The underlying Wallet object
     # @param seed [String] (Optional) The seed to use for the Wallet. Expects a 32-byte hexadecimal with no 0x prefix.
-    #   If not provided, a new seed will be generated.
-    # @param address_count [Integer] (Optional) The number of addresses already registered for the Wallet.
+    #   If nil, a new seed will be generated. If the empty string, no seed is generated, and the Wallet will be
+    #   instantiated without a seed and its corresponding private keys.
+    # @param address_models [Array<Coinbase::Client::Address>] (Optional) The models of the addresses already registered
+    #   with the Wallet. If not provided, the Wallet will derive the first default address.
     # @param client [Jimson::Client] (Optional) The JSON RPC client to use for interacting with the Network
-    def initialize(model, seed: nil, address_count: 0)
-      raise ArgumentError, 'Seed must be 32 bytes' if !seed.nil? && seed.length != 64
+    def initialize(model, seed: nil, address_models: [])
+      validate_seed_and_address_models(seed, address_models)
 
       @model = model
-
-      @master = seed.nil? ? MoneyTree::Master.new : MoneyTree::Master.new(seed_hex: seed)
-
-      # TODO: Make Network an argument to the constructor.
-      @network_id = :base_sepolia
+      @master = master_node(seed)
       @addresses = []
+      @private_key_index = 0
 
-      # TODO: Adjust derivation path prefix based on network protocol.
-      @address_path_prefix = "m/44'/60'/0'/0"
-      @address_index = 0
-
-      if address_count.positive?
-        address_count.times { derive_address }
-      else
-        create_address
-        # Update the model to reflect the new default address.
-        update_model
-      end
+      derive_addresses(address_models)
     end
 
     # Returns the Wallet ID.
     # @return [String] The Wallet ID
-    def wallet_id
+    def id
       @model.id
     end
 
@@ -55,6 +100,24 @@ module Coinbase
       Coinbase.to_sym(@model.network_id)
     end
 
+    # Sets the seed of the Wallet. This seed is used to derive keys and sign transactions.
+    # @param seed [String] The seed to set. Expects a 32-byte hexadecimal with no 0x prefix.
+    def seed=(seed)
+      raise ArgumentError, 'Seed must be 32 bytes' if seed.length != 64
+      raise 'Seed is already set' unless @master.nil?
+      raise 'Cannot set seed for Wallet with non-zero private key index' if @private_key_index.positive?
+
+      @master = MoneyTree::Master.new(seed_hex: seed)
+
+      @addresses.each do
+        key = derive_key
+        a = address(key.address.to_s)
+        raise "Seed does not match wallet; cannot find address #{key.address}" if a.nil?
+
+        a.key = key
+      end
+    end
+
     # Creates a new Address in the Wallet.
     # @return [Address] The new Address
     def create_address
@@ -69,69 +132,49 @@ module Coinbase
         }
       }
       address_model = Coinbase.call_api do
-        addresses_api.create_address(wallet_id, opts)
+        addresses_api.create_address(id, opts)
       end
 
+      # Auto-reload wallet to set default address on first address creation.
+      reload if addresses.empty?
+
       cache_address(address_model, key)
     end
 
     # Returns the default address of the Wallet.
     # @return [Address] The default address
     def default_address
-      @addresses.find { |address| address.address_id == @model.default_address.address_id }
+      address(@model.default_address&.address_id)
     end
 
     # Returns the Address with the given ID.
     # @param address_id [String] The ID of the Address to retrieve
     # @return [Address] The Address
-    def get_address(address_id)
-      @addresses.find { |address| address.address_id == address_id }
-    end
-
-    # Returns the list of Addresses in the Wallet.
-    # @return [Array<Address>] The list of Addresses
-    def list_addresses
-      @addresses
+    def address(address_id)
+      @addresses.find { |address| address.id == address_id }
     end
 
     # Returns the list of balances of this Wallet. Balances are aggregated across all Addresses in the Wallet.
     # @return [BalanceMap] The list of balances. The key is the Asset ID, and the value is the balance.
-    def list_balances
+    def balances
       response = Coinbase.call_api do
-        wallets_api.list_wallet_balances(wallet_id)
+        wallets_api.list_wallet_balances(id)
       end
 
-      Coinbase.to_balance_map(response)
+      Coinbase::BalanceMap.from_balances(response.data)
     end
 
     # Returns the balance of the provided Asset. Balances are aggregated across all Addresses in the Wallet.
     # @param asset_id [Symbol] The ID of the Asset to retrieve the balance for
     # @return [BigDecimal] The balance of the Asset
-    def get_balance(asset_id)
-      normalized_asset_id = if %i[wei gwei].include?(asset_id)
-                              :eth
-                            else
-                              asset_id
-                            end
-
+    def balance(asset_id)
       response = Coinbase.call_api do
-        wallets_api.get_wallet_balance(wallet_id, normalized_asset_id.to_s)
+        wallets_api.get_wallet_balance(id, Coinbase::Asset.primary_denomination(asset_id).to_s)
       end
 
       return BigDecimal('0') if response.nil?
 
-      amount = BigDecimal(response.amount)
-
-      case asset_id
-      when :eth
-        amount / BigDecimal(Coinbase::WEI_PER_ETHER.to_s)
-      when :gwei
-        amount / BigDecimal(Coinbase::GWEI_PER_ETHER.to_s)
-      when :usdc
-        amount / BigDecimal(Coinbase::ATOMIC_UNITS_PER_USDC.to_s)
-      else
-        amount
-      end
+      Coinbase::Balance.from_model_and_asset_id(response, asset_id).amount
     end
 
     # Transfers the given amount of the given Asset to the given address. Only same-Network Transfers are supported.
@@ -143,13 +186,13 @@ module Coinbase
     # @return [Transfer] The hash of the Transfer transaction.
     def transfer(amount, asset_id, destination)
       if destination.is_a?(Wallet)
-        raise ArgumentError, 'Transfer must be on the same Network' if destination.network_id != @network_id
+        raise ArgumentError, 'Transfer must be on the same Network' if destination.network_id != network_id
 
-        destination = destination.default_address.address_id
+        destination = destination.default_address.id
       elsif destination.is_a?(Address)
-        raise ArgumentError, 'Transfer must be on the same Network' if destination.network_id != @network_id
+        raise ArgumentError, 'Transfer must be on the same Network' if destination.network_id != network_id
 
-        destination = destination.address_id
+        destination = destination.id
       end
 
       default_address.transfer(amount, asset_id, destination)
@@ -158,14 +201,33 @@ module Coinbase
     # Exports the Wallet's data to a Data object.
     # @return [Data] The Wallet data
     def export
-      Data.new(wallet_id: wallet_id, seed: @master.seed_hex)
+      raise 'Cannot export Wallet without loaded seed' if @master.nil?
+
+      Data.new(wallet_id: id, seed: @master.seed_hex)
+    end
+
+    # Requests funds from the faucet for the Wallet's default address and returns the faucet transaction.
+    # This is only supported on testnet networks.
+    # @return [Coinbase::FaucetTransaction] The successful faucet transaction
+    # @raise [Coinbase::FaucetLimitReachedError] If the faucet limit has been reached for the address or user.
+    # @raise [Coinbase::Client::ApiError] If an unexpected error occurs while requesting faucet funds.
+    def faucet
+      Coinbase.call_api do
+        Coinbase::FaucetTransaction.new(addresses_api.request_faucet_funds(id, default_address.id))
+      end
+    end
+
+    # Returns whether the Wallet has a seed with which to derive keys and sign transactions.
+    # @return [Boolean] Whether the Wallet has a seed with which to derive keys and sign transactions.
+    def can_sign?
+      !@master.nil?
     end
 
     # Returns a String representation of the Wallet.
     # @return [String] a String representation of the Wallet
     def to_s
-      "Coinbase::Wallet{wallet_id: '#{wallet_id}', network_id: '#{network_id}', " \
-        "default_address: '#{default_address.address_id}'}"
+      "Coinbase::Wallet{wallet_id: '#{id}', network_id: '#{network_id}', " \
+        "default_address: '#{@model.default_address&.address_id}'}"
     end
 
     # Same as to_s.
@@ -202,14 +264,55 @@ module Coinbase
 
     private
 
+    # Reloads the Wallet with the latest data.
+    def reload
+      @model = Coinbase.call_api do
+        wallets_api.get_wallet(id)
+      end
+    end
+
+    def master_node(seed)
+      return MoneyTree::Master.new if seed.nil?
+      return nil if seed.empty?
+
+      MoneyTree::Master.new(seed_hex: seed)
+    end
+
+    def address_path_prefix
+      # TODO: Add support for other networks.
+      @address_path_prefix ||= case network_id.to_s.split('_').first
+                               when 'base'
+                                 "m/44'/60'/0'/0"
+                               else
+                                 raise ArgumentError, "Unsupported network ID: #{network_id}"
+                               end
+    end
+
+    # Derives the registered Addresses in the Wallet.
+    # @param address_models [Array<Coinbase::Client::Address>] The models of the addresses already registered with the
+    #   Wallet
+    def derive_addresses(address_models)
+      return unless address_models.any?
+
+      # Create a map tracking which addresses are already registered with the Wallet.
+      address_map = build_address_map(address_models)
+
+      address_models.each do |address_model|
+        # Derive the addresses using the provided models.
+        derive_address(address_map, address_model)
+      end
+    end
+
     # Derives an already registered Address in the Wallet.
+    # @param address_map [Hash<String, Boolean>] The map of registered Address IDs
+    # @param address_model [Coinbase::Client::Address] The Address model
     # @return [Address] The new Address
-    def derive_address
-      key = derive_key
+    def derive_address(address_map, address_model)
+      key = @master.nil? ? nil : derive_key
 
-      address_id = key.address.to_s
-      address_model = Coinbase.call_api do
-        addresses_api.get_address(wallet_id, address_id)
+      unless key.nil?
+        address_from_key = key.address.to_s
+        raise 'Invalid address' if address_map[address_from_key].nil?
       end
 
       cache_address(address_model, key)
@@ -218,8 +321,11 @@ module Coinbase
     # Derives a key for an already registered Address in the Wallet.
     # @return [Eth::Key] The new key
     def derive_key
-      path = "#{@address_path_prefix}/#{@address_index}"
+      raise 'Cannot derive key for Wallet without seed loaded' if @master.nil?
+
+      path = "#{address_path_prefix}/#{@private_key_index}"
       private_key = @master.node_for_path(path).private_key.to_hex
+      @private_key_index += 1
       Eth::Key.new(priv: private_key)
     end
 
@@ -230,17 +336,29 @@ module Coinbase
     def cache_address(address_model, key)
       address = Address.new(address_model, key)
       @addresses << address
-      @address_index += 1
       address
     end
 
+    # Builds a Hash of the registered Addresses.
+    # @param address_models [Array<Coinbase::Client::Address>] The models of the addresses already registered with the
+    #   Wallet
+    # @return [Hash<String, Boolean>] The Hash of registered Addresses
+    def build_address_map(address_models)
+      address_map = {}
+      address_models.each do |address_model|
+        address_map[address_model.address_id] = true
+      end
+
+      address_map
+    end
+
     # Creates an attestation for the Address currently being created.
     # @param key [Eth::Key] The private key of the Address
     # @return [String] The attestation
     def create_attestation(key)
       public_key = key.public_key.compressed.unpack1('H*')
       payload = {
-        wallet_id: wallet_id,
+        wallet_id: id,
         public_key: public_key
       }.to_json
       hashed_payload = Digest::SHA256.digest(payload)
@@ -258,11 +376,18 @@ module Coinbase
       new_signature_bytes.pack('C*').unpack1('H*')
     end
 
-    # Updates the Wallet model with the latest data.
-    def update_model
-      @model = Coinbase.call_api do
-        wallets_api.get_wallet(wallet_id)
-      end
+    # Validates the seed and address models passed to the constructor.
+    # @param seed [String] The seed to use for the Wallet
+    # @param address_models [Array<Coinbase::Client::Address>] The models of the addresses already registered with the
+    #   Wallet
+    def validate_seed_and_address_models(seed, address_models)
+      raise ArgumentError, 'Seed must be 32 bytes' if !seed.nil? && !seed.empty? && seed.length != 64
+
+      raise ArgumentError, 'Seed must be present if address_models are provided' if seed.nil? && address_models.any?
+
+      return unless !seed.nil? && seed.empty? && address_models.empty?
+
+      raise ArgumentError, 'Seed must be empty if address_models are not provided'
     end
 
     def addresses_api

data/lib/coinbase.rb

@@ -3,6 +3,7 @@
 require_relative 'coinbase/address'
 require_relative 'coinbase/asset'
 require_relative 'coinbase/authenticator'
+require_relative 'coinbase/balance'
 require_relative 'coinbase/balance_map'
 require_relative 'coinbase/client'
 require_relative 'coinbase/constants'
@@ -18,7 +19,6 @@ require 'json'
 # The Coinbase SDK.
 module Coinbase
   class InvalidConfiguration < StandardError; end
-  class FaucetLimitReached < StandardError; end
 
   # Returns the configuration object.
   # @return [Configuration] the configuration object
@@ -100,30 +100,6 @@ module Coinbase
     value.to_s.gsub('-', '_').to_sym
   end
 
-  # Converts a Coinbase::Client::AddressBalanceList to a BalanceMap.
-  # @param address_balance_list [Coinbase::Client::AddressBalanceList] The AddressBalanceList to convert
-  # @return [BalanceMap] The converted BalanceMap
-  def self.to_balance_map(address_balance_list)
-    balances = {}
-
-    address_balance_list.data.each do |balance|
-      asset_id = Coinbase.to_sym(balance.asset.asset_id.downcase)
-      amount = case asset_id
-               when :eth
-                 BigDecimal(balance.amount) / BigDecimal(Coinbase::WEI_PER_ETHER)
-               when :usdc
-                 BigDecimal(balance.amount) / BigDecimal(Coinbase::ATOMIC_UNITS_PER_USDC)
-               when :weth
-                 BigDecimal(balance.amount) / BigDecimal(Coinbase::WEI_PER_ETHER)
-               else
-                 BigDecimal(balance.amount)
-               end
-      balances[asset_id] = amount
-    end
-
-    BalanceMap.new(balances)
-  end
-
   # Loads the default user.
   # @return [Coinbase::User] the default user
   def self.load_default_user

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: coinbase-sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Yuga Cohler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-07 00:00:00.000000000 Z
+date: 2024-05-20 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: eth
   requirement: !ruby/object:Gem::Requirement
@@ -216,6 +230,7 @@ files:
 - lib/coinbase/address.rb
 - lib/coinbase/asset.rb
 - lib/coinbase/authenticator.rb
+- lib/coinbase/balance.rb
 - lib/coinbase/balance_map.rb
 - lib/coinbase/client.rb
 - lib/coinbase/client/api/addresses_api.rb