coinbase-sdk 0.0.8 → 0.0.9

data/lib/coinbase/client/models/user.rb

@@ -6,7 +6,7 @@
 The version of the OpenAPI document: 0.0.1-alpha
 Contact: yuga.cohler@coinbase.com
 Generated by: https://openapi-generator.tech
-Generator version: 7.5.0
+Generator version: 7.6.0
 
 =end
 

data/lib/coinbase/client/models/wallet.rb

@@ -6,7 +6,7 @@
 The version of the OpenAPI document: 0.0.1-alpha
 Contact: yuga.cohler@coinbase.com
 Generated by: https://openapi-generator.tech
-Generator version: 7.5.0
+Generator version: 7.6.0
 
 =end
 

data/lib/coinbase/client/models/wallet_list.rb

@@ -6,7 +6,7 @@
 The version of the OpenAPI document: 0.0.1-alpha
 Contact: yuga.cohler@coinbase.com
 Generated by: https://openapi-generator.tech
-Generator version: 7.5.0
+Generator version: 7.6.0
 
 =end
 

data/lib/coinbase/client/version.rb

@@ -6,7 +6,7 @@
 The version of the OpenAPI document: 0.0.1-alpha
 Contact: yuga.cohler@coinbase.com
 Generated by: https://openapi-generator.tech
-Generator version: 7.5.0
+Generator version: 7.6.0
 
 =end
 

data/lib/coinbase/client.rb

@@ -6,7 +6,7 @@
 The version of the OpenAPI document: 0.0.1-alpha
 Contact: yuga.cohler@coinbase.com
 Generated by: https://openapi-generator.tech
-Generator version: 7.5.0
+Generator version: 7.6.0
 
 =end
 
@@ -51,6 +51,7 @@ Coinbase::Client.autoload :StakingContext, 'coinbase/client/models/staking_conte
 Coinbase::Client.autoload :StakingContextContext, 'coinbase/client/models/staking_context_context'
 Coinbase::Client.autoload :StakingOperation, 'coinbase/client/models/staking_operation'
 Coinbase::Client.autoload :StakingReward, 'coinbase/client/models/staking_reward'
+Coinbase::Client.autoload :StakingRewardFormat, 'coinbase/client/models/staking_reward_format'
 Coinbase::Client.autoload :Trade, 'coinbase/client/models/trade'
 Coinbase::Client.autoload :TradeList, 'coinbase/client/models/trade_list'
 Coinbase::Client.autoload :Transaction, 'coinbase/client/models/transaction'

data/lib/coinbase/errors.rb

@@ -56,6 +56,13 @@ module Coinbase
     end
   end
 
+  # An error raised when an operation is attempted with insufficient funds.
+  class InsufficientFundsError < StandardError
+    def initialize(expected, exact, msg = 'Insufficient funds')
+      super("#{msg}: have #{exact}, need #{expected}.")
+    end
+  end
+
   class UnimplementedError < APIError; end
   class UnauthorizedError < APIError; end
   class InternalError < APIError; end

data/lib/coinbase/faucet_transaction.rb

@@ -12,8 +12,6 @@ module Coinbase
       @model = model
     end
 
-    attr_reader :model
-
     # Returns the transaction hash.
     # @return [String] The onchain transaction hash
     def transaction_hash
@@ -23,8 +21,7 @@ module Coinbase
     # 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}"
+      model.transaction_link
     end
 
     # Returns a String representation of the FaucetTransaction.
@@ -38,5 +35,9 @@ module Coinbase
     def inspect
       to_s
     end
+
+    private
+
+    attr_reader :model
   end
 end

data/lib/coinbase/pagination.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Coinbase
+  # A module of helper methods for paginating through resources.
+  module Pagination
+    def self.enumerate(fetcher, &build_resource)
+      Enumerator.new do |yielder|
+        page = nil
+
+        loop do
+          response = Coinbase.call_api { fetcher.call(page) }
+
+          break if response.data.empty?
+
+          response.data.each do |model|
+            yielder << build_resource.call(model)
+          end
+
+          break unless response.has_more
+
+          page = response.next_page
+        end
+      end
+    end
+  end
+end

data/lib/coinbase/staking_operation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Coinbase
+  # A representation of a staking operation (stake, unstake, claim rewards, etc). It
+  # may have multiple steps with some being transactions to sign, and others to wait.
+  # @attr_reader [Array<Coinbase::Transaction>] transactions The list of current
+  #   transactions associated with the operation
+  class StakingOperation
+    attr_reader :transactions
+
+    # Returns a new StakingOperation object.
+    # @param model [Coinbase::Client::StakingOperation] The underlying StakingOperation object
+    def initialize(model)
+      @model = model
+
+      @transactions = model.transactions.map do |transaction_model|
+        Transaction.new(transaction_model)
+      end
+    end
+
+    # Signs the Open Transactions with the provided key
+    # @param key [Eth::Key] The key to sign the transactions with
+    def sign(key)
+      transactions.each do |transaction|
+        transaction.sign(key) unless transaction.signed?
+      end
+    end
+  end
+end

data/lib/coinbase/staking_reward.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Coinbase
+  # A representation of a staking reward earned on a network for a given asset.
+  class StakingReward
+    # Returns a list of StakingRewards for the provided network, asset, and addresses.
+    # @param network_id [Symbol] The network ID
+    # @param asset_id [Symbol] The asset ID
+    # @param address_ids [Array<String>] The address IDs
+    # @param start_time [Time] The start time. Defaults to one month ago.
+    # @param end_time [Time] The end time. Defaults to the current time.
+    # @param format [Symbol] The format to return the rewards in. (:usd, :native) Defaults to :usd.
+    # @return [Enumerable<Coinbase::StakingReward>] The staking rewards
+    def self.list(network_id, asset_id, address_ids, start_time: DateTime.now.prev_month(1), end_time: DateTime.now,
+                  format: :usd)
+      asset = Coinbase.call_api do
+        Asset.fetch(network_id, asset_id)
+      end
+      Coinbase::Pagination.enumerate(
+        ->(page) { list_page(network_id, asset_id, address_ids, start_time, end_time, page, format) }
+      ) do |staking_reward|
+        new(staking_reward, asset, format)
+      end
+    end
+
+    # Returns a new StakingReward object.
+    # @param model [Coinbase::Client::StakingReward] The underlying StakingReward object
+    def initialize(model, asset, format)
+      @model = model
+      @asset = asset
+      @format = format
+    end
+
+    # Returns the amount of the StakingReward.
+    # @return [BigDecimal] The amount
+    def amount
+      return BigDecimal(@model.amount.to_i) / BigDecimal(100) if @format == :usd
+
+      @asset.from_atomic_amount(@model.amount.to_i)
+    end
+
+    # Returns the date of the StakingReward.
+    # @return [Time] The date
+    def date
+      @model.date
+    end
+
+    # Returns a string representation of the StakingReward.
+    # @return [String] a string representation of the StakingReward
+    def to_s
+      "Coinbase::StakingReward{amount: '#{amount}'}"
+    end
+
+    # Same as to_s.
+    # @return [String] a string representation of the StakingReward
+    def inspect
+      to_s
+    end
+
+    def self.stake_api
+      Coinbase::Client::StakeApi.new(Coinbase.configuration.api_client)
+    end
+
+    def self.list_page(network_id, asset_id, address_ids, start_time, end_time, page, format)
+      req = {
+        network_id: Coinbase.normalize_network(network_id),
+        asset_id: asset_id,
+        address_ids: address_ids,
+        start_time: start_time.iso8601,
+        end_time: end_time.iso8601,
+        format: format,
+        next_page: page
+      }
+      stake_api.fetch_staking_rewards(req)
+    end
+  end
+end

data/lib/coinbase/transaction.rb

@@ -110,6 +110,12 @@ module Coinbase
       raw.hex
     end
 
+    # Returns whether the Transaction has been signed.
+    # @return [Boolean] Whether the Transaction has been signed
+    def signed?
+      Eth::Tx.signed?(raw)
+    end
+
     # Returns a String representation of the Transaction.
     # @return [String] a String representation of the Transaction
     def to_s

data/lib/coinbase/user.rb

@@ -37,53 +37,17 @@ module Coinbase
       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 [Array<Coinbase::Wallet, String>] the Wallets belonging to the User and the pagination token, if
-    #   any.
-    def wallets(page_size: 10, next_page_token: nil)
-      opts = {
-        limit: page_size
-      }
-
-      opts[:page] = next_page_token unless next_page_token.nil?
-
-      wallet_list = Coinbase.call_api do
-        wallets_api.list_wallets(opts)
-      end
-
-      # A map from wallet_id to address models.
-      address_model_map = {}
-
-      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 = wallet_list.data.map do |wallet_model|
-        Wallet.new(wallet_model, seed: '', address_models: address_model_map[wallet_model.id])
-      end
-
-      [wallets, wallet_list.next_page]
+    # Enumerates the Wallets belonging to the User.
+    # @return [Enumerator<Coinbase::Wallet>] the Wallets belonging to the User
+    def wallets
+      Wallet.list
     end
 
     # Returns the Wallet with the given ID.
     # @param wallet_id [String] the ID of the Wallet
     # @return [Coinbase::Wallet] the unhydrated Wallet
     def wallet(wallet_id)
-      wallet_model = Coinbase.call_api do
-        wallets_api.get_wallet(wallet_id)
-      end
-
-      addresses_list = Coinbase.call_api do
-        addresses_api.list_addresses(wallet_model.id, { limit: Coinbase::Wallet::MAX_ADDRESSES })
-      end
-
-      Wallet.new(wallet_model, seed: '', address_models: addresses_list.data)
+      Wallet.fetch(wallet_id)
     end
 
     # Returns a string representation of the User.
@@ -97,15 +61,5 @@ module Coinbase
     def inspect
       to_s
     end
-
-    private
-
-    def addresses_api
-      @addresses_api ||= Coinbase::Client::AddressesApi.new(Coinbase.configuration.api_client)
-    end
-
-    def wallets_api
-      @wallets_api ||= Coinbase::Client::WalletsApi.new(Coinbase.configuration.api_client)
-    end
   end
 end

data/lib/coinbase/wallet.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'digest'
-require 'jimson'
 require 'json'
 require 'money-tree'
 require 'securerandom'
@@ -9,14 +8,14 @@ require 'securerandom'
 module Coinbase
   # A representation of a Wallet. Wallets come with a single default Address, but can expand to have a set of Addresses,
   # each of which can hold a balance of one or more Assets. Wallets can create new Addresses, list their addresses,
-  # list their balances, and transfer Assets to other Addresses. Wallets should be created through User#create_wallet or
-  # User#import_wallet.
+  # list their balances, and transfer Assets to other Addresses.
   class Wallet
-    attr_reader :addresses, :model
-
     # The maximum number of addresses in a Wallet.
     MAX_ADDRESSES = 20
 
+    # The maximum number of wallets to fetch in a single page.
+    PAGE_LIMIT = 100
+
     # A representation of ServerSigner status in a Wallet.
     module ServerSignerStatus
       # The Wallet is awaiting seed creation by the ServerSigner. At this point,
@@ -39,11 +38,31 @@ module Coinbase
           wallets_api.get_wallet(data.wallet_id)
         end
 
-        address_list = Coinbase.call_api do
-          addresses_api.list_addresses(model.id, { limit: MAX_ADDRESSES })
+        new(model, seed: data.seed)
+      end
+
+      # Enumerates the wallets for the requesting user.
+      # The result is an enumerator that lazily fetches from the server, and can be iterated over,
+      # converted to an array, etc...
+      # @return [Enumerable<Coinbase::Wallet>] Enumerator that returns wallets
+      def list
+        Coinbase::Pagination.enumerate(lambda(&method(:fetch_wallets_page))) do |wallet|
+          Coinbase::Wallet.new(wallet, seed: '')
+        end
+      end
+
+      # Fetches a Wallet by its ID.
+      # The returned wallet can be immediately used for signing operations if backed by a server signer.
+      # If the wallet is not backed by a server signer, the wallet's seed will need to be set before
+      # it can be used for signing operations.
+      # @param wallet_id [String] The ID of the Wallet to fetch
+      # @return [Coinbase::Wallet] The fetched Wallet
+      def fetch(wallet_id)
+        model = Coinbase.call_api do
+          wallets_api.get_wallet(wallet_id)
         end
 
-        new(model, seed: data.seed, address_models: address_list.data)
+        new(model, seed: '')
       end
 
       # Creates a new Wallet on the specified Network and generate a default address for it.
@@ -58,7 +77,7 @@ module Coinbase
           wallets_api.create_wallet(
             create_wallet_request: {
               wallet: {
-                network_id: network_id,
+                network_id: Coinbase.normalize_network(network_id),
                 use_server_signer: Coinbase.use_server_signer?
               }
             }
@@ -103,7 +122,6 @@ module Coinbase
         self
       end
 
-      # 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
@@ -111,6 +129,10 @@ module Coinbase
       def wallets_api
         Coinbase::Client::WalletsApi.new(Coinbase.configuration.api_client)
       end
+
+      def fetch_wallets_page(page)
+        wallets_api.list_wallets({ limit: PAGE_LIMIT, page: page })
+      end
     end
 
     # Returns a new Wallet object. Do not use this method directly. Instead, use User#create_wallet or
@@ -119,21 +141,30 @@ module Coinbase
     # @param seed [String] (Optional) The seed to use for the Wallet. Expects a 32-byte hexadecimal with no 0x prefix.
     #   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_models: [])
-      validate_seed_and_address_models(seed, address_models) unless Coinbase.use_server_signer?
+    def initialize(model, seed: nil)
+      raise ArgumentError, 'model must be a Wallet' unless model.is_a?(Coinbase::Client::Wallet)
 
       @model = model
-      @addresses = []
 
-      unless Coinbase.use_server_signer?
-        @master = master_node(seed)
-        @private_key_index = 0
-      end
+      return if Coinbase.use_server_signer?
+
+      @master = master_node(seed)
+    end
+
+    # Returns the addresses belonging to the Wallet.
+    # @return [Array<Coinbase::WalletAddress>] The addresses belonging to the Wallet
+    def addresses
+      @addresses ||= begin
+        address_list = Coinbase.call_api do
+          addresses_api.list_addresses(@model.id, { limit: MAX_ADDRESSES })
+        end
 
-      derive_addresses(address_models)
+        # Build the WalletAddress objects, injecting the key if available.
+        address_list.data.each_with_index.map do |address_model, index|
+          build_wallet_address(address_model, index)
+        end
+      end
     end
 
     # Returns the Wallet ID.
@@ -157,18 +188,22 @@ module Coinbase
     # 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?
+      raise ArgumentError, 'Seed must not be empty' if seed.nil? || seed.empty?
+      raise StandardError, 'Seed is already set' unless @master.nil?
+
+      @master = master_node(seed)
 
-      @master = MoneyTree::Master.new(seed_hex: seed)
+      # If the addresses are not loaded the keys will be set on them whenever they are loaded.
+      return if @addresses.nil?
 
-      @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?
+      # If addresses are already loaded, set the keys on each address.
+      addresses.each_with_index.each do |address, index|
+        key = derive_key(index)
 
-        a.key = key
+        # If we derive a key the derived address must match the address from the API.
+        raise StandardError, 'Seed does not match wallet' unless address.id == key.address.to_s
+
+        address.key = key
       end
     end
 
@@ -178,7 +213,10 @@ module Coinbase
       opts = { create_address_request: {} }
 
       unless Coinbase.use_server_signer?
-        key = derive_key
+        # The index for the next address is the number of addresses already registered.
+        private_key_index = addresses.count
+
+        key = derive_key(private_key_index)
 
         opts = {
           create_address_request: {
@@ -193,9 +231,12 @@ module Coinbase
       end
 
       # Auto-reload wallet to set default address on first address creation.
-      reload if addresses.empty?
+      reload if default_address.nil?
 
-      cache_address(address_model, key)
+      # Cache the address in our memoized list
+      address = WalletAddress.new(address_model, key)
+      @addresses << address
+      address
     end
 
     # Returns the default address of the Wallet.
@@ -208,7 +249,7 @@ module Coinbase
     # @param address_id [String] The ID of the Address to retrieve
     # @return [Address] The Address
     def address(address_id)
-      @addresses.find { |address| address.id == 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.
@@ -413,10 +454,13 @@ module Coinbase
       end
     end
 
+    # Returns the master node for the given seed.
     def master_node(seed)
       return MoneyTree::Master.new if seed.nil?
       return nil if seed.empty?
 
+      validate_seed(seed)
+
       MoneyTree::Master.new(seed_hex: seed)
     end
 
@@ -430,68 +474,15 @@ module Coinbase
                                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(address_map, address_model)
-      key = @master.nil? ? nil : derive_key
-
-      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)
-    end
-
-    # Derives a key for an already registered Address in the Wallet.
+    # Derives a key for the given address index.
     # @return [Eth::Key] The new key
-    def derive_key
+    def derive_key(index)
       raise 'Cannot derive key for Wallet without seed loaded' if @master.nil?
 
-      path = "#{address_path_prefix}/#{@private_key_index}"
+      path = "#{address_path_prefix}/#{index}"
       private_key = @master.node_for_path(path).private_key.to_hex
-      @private_key_index += 1
-      Eth::Key.new(priv: private_key)
-    end
-
-    # Caches an Address on the client-side and increments the address index.
-    # @param address_model [Coinbase::Client::Address] The Address model
-    # @param key [Eth::Key] The private key of the Address
-    # @return [Address] The new Address
-    def cache_address(address_model, key)
-      address = Address.new(address_model, key)
-      @addresses << address
-      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
+      Eth::Key.new(priv: private_key)
     end
 
     # Creates an attestation for the Address currently being created.
@@ -520,16 +511,9 @@ module Coinbase
 
     # 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'
+    # @raise [ArgumentError] If the seed is invalid
+    def validate_seed(seed)
+      raise ArgumentError, 'Seed must be 32 bytes' unless seed.length == 64
     end
 
     # Loads the Hash of Wallet seeds from the given file.
@@ -551,6 +535,17 @@ module Coinbase
       pk.dh_compute_key(public_key)
     end
 
+    def build_wallet_address(address_model, index)
+      # Return an unhydrated wallet address is no master seed is set.
+      return WalletAddress.new(address_model, nil) if @master.nil?
+
+      key = derive_key(index)
+
+      raise StandardError, 'Seed does not match wallet' unless address_model.address_id == key.address.to_s
+
+      WalletAddress.new(address_model, key)
+    end
+
     def addresses_api
       @addresses_api ||= Coinbase::Client::AddressesApi.new(Coinbase.configuration.api_client)
     end

data/lib/coinbase.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'coinbase/address'
+require_relative 'coinbase/address/wallet_address'
+require_relative 'coinbase/address/external_address'
 require_relative 'coinbase/asset'
 require_relative 'coinbase/authenticator'
 require_relative 'coinbase/balance'
@@ -11,12 +13,15 @@ require_relative 'coinbase/errors'
 require_relative 'coinbase/faucet_transaction'
 require_relative 'coinbase/middleware'
 require_relative 'coinbase/network'
+require_relative 'coinbase/pagination'
 require_relative 'coinbase/trade'
 require_relative 'coinbase/transfer'
 require_relative 'coinbase/transaction'
 require_relative 'coinbase/user'
 require_relative 'coinbase/wallet'
 require_relative 'coinbase/server_signer'
+require_relative 'coinbase/staking_operation'
+require_relative 'coinbase/staking_reward'
 require 'json'
 
 # The Coinbase SDK.
@@ -129,4 +134,10 @@ module Coinbase
   def self.use_server_signer?
     Coinbase.configuration.use_server_signer
   end
+
+  # Returns whether the SDK is configured.
+  # @return [bool] whether the SDK is configured
+  def self.configured?
+    !Coinbase.configuration.api_key_name.nil? && !Coinbase.configuration.api_key_private_key.nil?
+  end
 end