coinbase-sdk 0.0.2 → 0.0.4

data/lib/coinbase/middleware.rb

@@ -12,7 +12,7 @@ module Coinbase
     # Returns the default middleware configuration for the Coinbase SDK.
     def self.config
       Coinbase::Client::Configuration.default.tap do |config|
-        config.debugging = true
+        config.debugging = Coinbase.configuration.debug_api
         config.host = Coinbase.configuration.api_url
         config.request(:authenticator)
       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
 
@@ -72,9 +72,21 @@ module Coinbase
     end
 
     # Returns the amount of the asset for the Transfer.
-    # @return [BigDecimal] The amount in units of ETH
+    # @return [BigDecimal] The amount of the asset
     def amount
-      BigDecimal(@model.amount) / BigDecimal(Coinbase::WEI_PER_ETHER.to_s)
+      case asset_id
+      when :eth
+        BigDecimal(@model.amount) / BigDecimal(Coinbase::WEI_PER_ETHER.to_s)
+      else
+        BigDecimal(@model.amount)
+      end
+    end
+
+    # Returns the link to the transaction on the blockchain explorer.
+    # @return [String] The link to the transaction on the blockchain explorer
+    def transaction_link
+      # TODO: Parameterize this by Network.
+      "https://sepolia.basescan.org/tx/#{transaction_hash}"
     end
 
     # Returns the Unsigned Payload of the Transfer.
@@ -83,6 +95,18 @@ module Coinbase
       @model.unsigned_payload
     end
 
+    # Returns the Signed Payload of the Transfer.
+    # @return [String] The Signed Payload
+    def signed_payload
+      @model.signed_payload
+    end
+
+    # Returns the Transaction Hash of the Transfer.
+    # @return [String] The Transaction Hash
+    def transaction_hash
+      @model.transaction_hash
+    end
+
     # Returns the underlying Transfer transaction, creating it if it has not been yet.
     # @return [Eth::Tx::Eip1559] The Transfer transaction
     def transaction
@@ -110,13 +134,8 @@ module Coinbase
     # Returns the status of the Transfer.
     # @return [Symbol] The status
     def status
-      begin
-        # Create the transaction, and attempt to get the hash to see if it has been signed.
-        transaction.hash
-      rescue Eth::Signature::SignatureError
-        # If the transaction has not been signed, it is still pending.
-        return Status::PENDING
-      end
+      # Check if the transfer has been signed yet.
+      return Status::PENDING if transaction_hash.nil?
 
       onchain_transaction = Coinbase.configuration.base_sepolia_client.eth_getTransactionByHash(transaction_hash)
 
@@ -157,12 +176,19 @@ module Coinbase
       self
     end
 
-    # Returns the transaction hash of the Transfer, or nil if not yet available.
-    # @return [String] The transaction hash
-    def transaction_hash
-      "0x#{transaction.hash}"
-    rescue Eth::Signature::SignatureError
-      nil
+    # Returns a String representation of the Transfer.
+    # @return [String] a String representation of the Transfer
+    def to_s
+      "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}'}"
+    end
+
+    # Same as to_s.
+    # @return [String] a String representation of the Transfer
+    def inspect
+      to_s
     end
   end
 end

data/lib/coinbase/user.rb

@@ -15,7 +15,7 @@ module Coinbase
 
     # Returns the User ID.
     # @return [String] the User ID
-    def user_id
+    def id
       @model.id
     end
 
@@ -30,7 +30,9 @@ module Coinbase
       }
       opts = { create_wallet_request: create_wallet_request }
 
-      model = wallets_api.create_wallet(opts)
+      model = Coinbase.call_api do
+        wallets_api.create_wallet(opts)
+      end
 
       Wallet.new(model)
     end
@@ -39,18 +41,107 @@ module Coinbase
     # @param data [Coinbase::Wallet::Data] the Wallet data to import
     # @return [Coinbase::Wallet] the imported Wallet
     def import_wallet(data)
-      model = wallets_api.get_wallet(data.wallet_id)
-      address_count = addresses_api.list_addresses(model.id).total_count
-      Wallet.new(model, seed: data.seed, address_count: address_count)
+      Wallet.import(data)
     end
 
     # 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 = wallets_api.list_wallets
+    def wallet_ids
+      wallets = Coinbase.call_api do
+        wallets_api.list_wallets
+      end
+
       wallets.data.map(&:id)
     end
 
+    # 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.
+    #
+    # @param wallet [Coinbase::Wallet] The wallet model to save.
+    # @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_locally!(wallet, encrypt: false)
+      existing_seeds_in_store = existing_seeds
+      data = wallet.export
+      seed_to_store = data.seed
+      auth_tag = ''
+      iv = ''
+      if encrypt
+        shared_secret = store_encryption_key
+        cipher = OpenSSL::Cipher.new('aes-256-gcm').encrypt
+        cipher.key = OpenSSL::Digest.digest('SHA256', shared_secret)
+        iv = cipher.random_iv
+        cipher.iv = iv
+        cipher.auth_data = ''
+        encrypted_data = cipher.update(data.seed) + cipher.final
+        auth_tag = cipher.auth_tag.unpack1('H*')
+        iv = iv.unpack1('H*')
+        seed_to_store = encrypted_data.unpack1('H*')
+      end
+
+      existing_seeds_in_store[data.wallet_id] = {
+        seed: seed_to_store,
+        encrypted: encrypt,
+        auth_tag: auth_tag,
+        iv: iv
+      }
+
+      File.open(Coinbase.configuration.backup_file_path, 'w') do |file|
+        file.write(JSON.pretty_generate(existing_seeds_in_store))
+      end
+      wallet
+    end
+
+    # 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_from_local
+      existing_seeds_in_store = existing_seeds
+      raise ArgumentError, 'Backup file not found' if existing_seeds_in_store == {}
+
+      wallets = {}
+      existing_seeds_in_store.each do |wallet_id, seed_data|
+        seed = seed_data['seed']
+        raise ArgumentError, 'Malformed backup data' if seed.nil? || seed == ''
+
+        if seed_data['encrypted']
+          shared_secret = store_encryption_key
+          raise ArgumentError, 'Malformed encrypted seed data' if seed_data['iv'] == '' ||
+                                                                  seed_data['auth_tag'] == ''
+
+          cipher = OpenSSL::Cipher.new('aes-256-gcm').decrypt
+          cipher.key = OpenSSL::Digest.digest('SHA256', shared_secret)
+          iv = [seed_data['iv']].pack('H*')
+          cipher.iv = iv
+          auth_tag = [seed_data['auth_tag']].pack('H*')
+          cipher.auth_tag = auth_tag
+          cipher.auth_data = ''
+          hex_decoded_data = [seed_data['seed']].pack('H*')
+          seed = cipher.update(hex_decoded_data) + cipher.final
+        end
+
+        data = Coinbase::Wallet::Data.new(wallet_id: wallet_id, seed: seed)
+        wallets[wallet_id] = import_wallet(data)
+      end
+      wallets
+    end
+
+    # Returns a string representation of the User.
+    # @return [String] a string representation of the User
+    def to_s
+      "Coinbase::User{user_id: '#{id}'}"
+    end
+
+    # Same as to_s.
+    # @return [String] a string representation of the User
+    def inspect
+      to_s
+    end
+
     private
 
     def addresses_api
@@ -60,5 +151,22 @@ module Coinbase
     def wallets_api
       @wallets_api ||= Coinbase::Client::WalletsApi.new(Coinbase.configuration.api_client)
     end
+
+    def existing_seeds
+      existing_seed_data = '{}'
+      file_path = Coinbase.configuration.backup_file_path
+      existing_seed_data = File.read(file_path) if File.exist?(file_path)
+      output = JSON.parse(existing_seed_data)
+
+      raise ArgumentError, 'Malformed backup data' unless output.is_a?(Hash)
+
+      output
+    end
+
+    def store_encryption_key
+      pk = OpenSSL::PKey.read(Coinbase.configuration.api_key_private_key)
+      public_key = pk.public_key # use own public key to generate the shared secret.
+      pk.dh_compute_key(public_key)
+    end
   end
 end

data/lib/coinbase/wallet.rb

@@ -12,6 +12,39 @@ 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
+
+    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
+
+        # TODO: Pass these addresses in directly
+        address_count = Coinbase.call_api do
+          addresses_api.list_addresses(model.id).total_count
+        end
+
+        new(model, seed: data.seed, address_count: address_count)
+      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
@@ -45,7 +78,7 @@ module Coinbase
 
     # Returns the Wallet ID.
     # @return [String] The Wallet ID
-    def wallet_id
+    def id
       @model.id
     end
 
@@ -68,7 +101,9 @@ module Coinbase
           attestation: attestation
         }
       }
-      address_model = addresses_api.create_address(wallet_id, opts)
+      address_model = Coinbase.call_api do
+        addresses_api.create_address(id, opts)
+      end
 
       cache_address(address_model, key)
     end
@@ -76,55 +111,37 @@ module Coinbase
     # 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
-      response = wallets_api.list_wallet_balances(wallet_id)
-      Coinbase.to_balance_map(response)
+    def balances
+      response = Coinbase.call_api do
+        wallets_api.list_wallet_balances(id)
+      end
+
+      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
-
-      response = wallets_api.get_wallet_balance(wallet_id, normalized_asset_id.to_s)
+    def balance(asset_id)
+      response = Coinbase.call_api do
+        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.
@@ -138,11 +155,11 @@ module Coinbase
       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
 
       default_address.transfer(amount, asset_id, destination)
@@ -151,7 +168,31 @@ 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)
+      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 a String representation of the Wallet.
+    # @return [String] a String representation of the Wallet
+    def to_s
+      "Coinbase::Wallet{wallet_id: '#{id}', network_id: '#{network_id}', " \
+        "default_address: '#{default_address.id}'}"
+    end
+
+    # Same as to_s.
+    # @return [String] a String representation of the Wallet
+    def inspect
+      to_s
     end
 
     # The data required to recreate a Wallet.
@@ -188,7 +229,9 @@ module Coinbase
       key = derive_key
 
       address_id = key.address.to_s
-      address_model = addresses_api.get_address(wallet_id, address_id)
+      address_model = Coinbase.call_api do
+        addresses_api.get_address(id, address_id)
+      end
 
       cache_address(address_model, key)
     end
@@ -218,7 +261,7 @@ module Coinbase
     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)
@@ -238,7 +281,9 @@ module Coinbase
 
     # Updates the Wallet model with the latest data.
     def update_model
-      @model = wallets_api.get_wallet(wallet_id)
+      @model = Coinbase.call_api do
+        wallets_api.get_wallet(id)
+      end
     end
 
     def addresses_api

data/lib/coinbase.rb

@@ -3,23 +3,30 @@
 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'
+require_relative 'coinbase/errors'
+require_relative 'coinbase/faucet_transaction'
 require_relative 'coinbase/middleware'
 require_relative 'coinbase/network'
 require_relative 'coinbase/transfer'
 require_relative 'coinbase/user'
 require_relative 'coinbase/wallet'
+require 'json'
 
 # The Coinbase SDK.
 module Coinbase
   class InvalidConfiguration < StandardError; end
 
+  # Returns the configuration object.
+  # @return [Configuration] the configuration object
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Configures the Coinbase SDK.
   def self.configure
     yield(configuration)
 
@@ -27,22 +34,54 @@ module Coinbase
     raise InvalidConfiguration, 'API key name is not set' unless configuration.api_key_name
   end
 
-  # Configuration object for the Coinbase SDK
+  # Configures the Coinbase SDK from the given CDP API Key JSON file.
+  # @param file_path [String] (Optional) the path to the CDP API Key JSON file
+  # file in the root directory by default.
+  def self.configure_from_json(file_path = 'coinbase_cloud_api_key.json')
+    configuration.from_json(file_path)
+
+    raise InvalidConfiguration, 'API key private key is not set' unless configuration.api_key_private_key
+    raise InvalidConfiguration, 'API key name is not set' unless configuration.api_key_name
+  end
+
+  # Configuration object for the Coinbase SDK.
   class Configuration
     attr_reader :base_sepolia_rpc_url, :base_sepolia_client
-    attr_accessor :api_url, :api_key_name, :api_key_private_key
+    attr_accessor :api_url, :api_key_name, :api_key_private_key, :debug_api, :backup_file_path
 
+    # Initializes the configuration object.
     def initialize
       @base_sepolia_rpc_url = 'https://sepolia.base.org'
       @base_sepolia_client = Jimson::Client.new(@base_sepolia_rpc_url)
       @api_url = 'https://api.cdp.coinbase.com'
+      @debug_api = false
+      @backup_file_path = 'seeds.json'
+    end
+
+    # Sets configuration values based on the provided CDP API Key JSON file.
+    # @param file_path [String] (Optional) the path to the CDP API Key JSON file
+    # file in the root directory by default.
+    def from_json(file_path = 'coinbase_cloud_api_key.json')
+      # Expand paths to respect shortcuts like ~.
+      file_path = File.expand_path(file_path)
+
+      raise InvalidConfiguration, 'Invalid configuration file type' unless file_path.end_with?('.json')
+
+      file = File.read(file_path)
+      data = JSON.parse(file)
+      @api_key_name = data['name']
+      @api_key_private_key = data['privateKey']
     end
 
+    # Sets the Base Sepolia RPC URL.
+    # @param new_base_sepolia_rpc_url [String] the new Base Sepolia RPC URL
     def base_sepolia_rpc_url=(new_base_sepolia_rpc_url)
       @base_sepolia_rpc_url = new_base_sepolia_rpc_url
       @base_sepolia_client = Jimson::Client.new(@base_sepolia_rpc_url)
     end
 
+    # Returns the API client.
+    # @return [Coinbase::Client::ApiClient] the API client
     def api_client
       @api_client ||= Coinbase::Client::ApiClient.new(Middleware.config)
     end
@@ -61,30 +100,21 @@ 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 = if asset_id == :eth
-                 BigDecimal(balance.amount) / BigDecimal(Coinbase::WEI_PER_ETHER)
-               elsif asset_id == :usdc
-                 BigDecimal(balance.amount) / BigDecimal(Coinbase::ATOMIC_UNITS_PER_USDC)
-               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
     users_api = Coinbase::Client::UsersApi.new(configuration.api_client)
     user_model = users_api.get_current_user
     Coinbase::User.new(user_model)
   end
+
+  # Wraps a call to the Platform API to ensure that the error is caught and
+  # wrapped as an APIError.
+  def self.call_api
+    yield
+  rescue Coinbase::Client::ApiError => e
+    raise Coinbase::APIError.from_error(e)
+  rescue StandardError => e
+    raise e
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: coinbase-sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Yuga Cohler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-04-30 00:00:00.000000000 Z
+date: 2024-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eth
@@ -192,6 +192,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.9.36
+- !ruby/object:Gem::Dependency
+  name: yard-markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Coinbase Ruby SDK for accessing Coinbase Platform APIs
 email: yuga.cohler@coinbase.com
 executables: []
@@ -202,6 +216,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
@@ -216,10 +231,12 @@ files:
 - lib/coinbase/client/models/address_list.rb
 - lib/coinbase/client/models/asset.rb
 - lib/coinbase/client/models/balance.rb
+- lib/coinbase/client/models/broadcast_transfer_request.rb
 - lib/coinbase/client/models/create_address_request.rb
 - lib/coinbase/client/models/create_transfer_request.rb
 - lib/coinbase/client/models/create_wallet_request.rb
 - lib/coinbase/client/models/error.rb
+- lib/coinbase/client/models/faucet_transaction.rb
 - lib/coinbase/client/models/transfer.rb
 - lib/coinbase/client/models/transfer_list.rb
 - lib/coinbase/client/models/user.rb
@@ -227,6 +244,8 @@ files:
 - lib/coinbase/client/models/wallet_list.rb
 - lib/coinbase/client/version.rb
 - lib/coinbase/constants.rb
+- lib/coinbase/errors.rb
+- lib/coinbase/faucet_transaction.rb
 - lib/coinbase/middleware.rb
 - lib/coinbase/network.rb
 - lib/coinbase/transfer.rb