coinbase-sdk 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c52613ebb145609813f96508c0eff76721ee6afebf3f3207394dad4c91b51635
-  data.tar.gz: d7f86c6cfbc02b6dd8866717cc9a89439b81da9ae8838dc34855dd10bf9f3fa9
+  metadata.gz: df442398edde68b8c97794f9b1f0a2bfd33304f02459962fe13a437c348aba37
+  data.tar.gz: e8fcd68e07c0d0012985c5046705d53137b3f7c6f1717f0ac2546f161cfadb0a
 SHA512:
-  metadata.gz: 6fa544e18af4ad42457ec8615e7a6e652fb15e1ae00cfa14924dcb86c53aab1ba90b21a8e1b7b29f193b1e0039d030cba1f45631b8dac23b287617105b88478b
-  data.tar.gz: 3625e897b9681e208cd921e8118275bd012996c17fb62fc235eac8624e6742ce18cff8d8177a1d379bfb5fa71ebec3db02a70d2bb683aeb067ccac7f89345945
+  metadata.gz: e777794208415ac5797c445db30fb7e0b6e2fe5f53c1dc22323ba2411a7648d6ee971b94e594806d9738018e41888d04c5ae036457883f51e4eaa76de7875920
+  data.tar.gz: 8b5b812b286509fa1962b1f9c5098955de0d8a19d3f233b2205c9c85c8bb1c4869566915db7ca15dd2020e713f515b80499532b87a45f1e7ba7b80419c35c3e5

data/lib/coinbase/address/external_address.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Coinbase
+  # A representation of a blockchain Address that do not belong to a Coinbase::Wallet.
+  # External addresses can be used to fetch balances, request funds from the faucet, etc...,
+  # but cannot be used to sign transactions.
+  class ExternalAddress < Address
+    # Builds a stake operation for the supplied asset. The stake operation
+    # may take a few minutes to complete in the case when infrastructure is spun up.
+    # @param amount [Integer,String,BigDecimal] The amount of the asset to stake
+    # @param asset_id [Symbol] The asset to stake
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the stake operation
+    # @return [Coinbase::StakingOperation] The stake operation
+    def build_stake_operation(amount, asset_id, mode: :default, options: {})
+      validate_can_stake!(amount, asset_id, mode, options)
+
+      build_staking_operation(amount, asset_id, 'stake', mode: mode, options: options)
+    end
+
+    # Builds an unstake operation for the supplied asset.
+    # @param amount [Integer,String,BigDecimal] The amount of the asset to unstake
+    # @param asset_id [Symbol] The asset to unstake
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the unstake operation
+    # @return [Coinbase::StakingOperation] The unstake operation
+    def build_unstake_operation(amount, asset_id, mode: :default, options: {})
+      validate_can_unstake!(amount, asset_id, mode, options)
+
+      build_staking_operation(amount, asset_id, 'unstake', mode: mode, options: options)
+    end
+
+    # Builds an claim_stake operation for the supplied asset.
+    # @param amount [Integer,String,BigDecimal] The amount of the asset to claim
+    # @param asset_id [Symbol] The asset to claim
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the claim_stake operation
+    # @return [Coinbase::StakingOperation] The claim_stake operation
+    def build_claim_stake_operation(amount, asset_id, mode: :default, options: {})
+      validate_can_claim_stake!(amount, asset_id, mode, options)
+
+      build_staking_operation(amount, asset_id, 'claim_stake', mode: mode, options: options)
+    end
+
+    # Retreives the balances used for staking for the supplied asset.
+    # @param asset_id [Symbol] The asset to retrieve staking balances for
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the staking operation
+    # @return [Hash] The staking balances
+    # @return [BigDecimal] :stakeable_balance The amount of the asset that can be staked
+    # @return [BigDecimal] :unstakeable_balance The amount of the asset that is currently staked and cannot be unstaked
+    # @return [BigDecimal] :claimable_balance The amount of the asset that can be claimed
+    def staking_balances(asset_id, mode: :default, options: {})
+      context_model = Coinbase.call_api do
+        stake_api.get_staking_context(
+          {
+            asset_id: asset_id,
+            network_id: Coinbase.normalize_network(network_id),
+            address_id: id,
+            options: {
+              mode: mode
+            }.merge(options)
+          }
+        )
+      end.context
+
+      {
+        stakeable_balance: Coinbase::Balance.from_model_and_asset_id(
+          context_model.stakeable_balance,
+          asset_id
+        ).amount,
+        unstakeable_balance: Coinbase::Balance.from_model_and_asset_id(
+          context_model.unstakeable_balance,
+          asset_id
+        ).amount,
+        claimable_balance: Coinbase::Balance.from_model_and_asset_id(
+          context_model.claimable_balance,
+          asset_id
+        ).amount
+      }
+    end
+
+    # Retreives the stakeable balance for the supplied asset.
+    # @param asset_id [Symbol] The asset to retrieve the stakeable balance for
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the staking operation
+    # @return [BigDecimal] The stakeable balance
+    def stakeable_balance(asset_id, mode: :default, options: {})
+      staking_balances(asset_id, mode: mode, options: options)[:stakeable_balance]
+    end
+
+    # Retreives the unstakeable balance for the supplied asset.
+    # @param asset_id [Symbol] The asset to retrieve the unstakeable balance for
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the staking operation
+    # @return [BigDecimal] The unstakeable balance
+    def unstakeable_balance(asset_id, mode: :default, options: {})
+      staking_balances(asset_id, mode: mode, options: options)[:unstakeable_balance]
+    end
+
+    # Retreives the claimable balance for the supplied asset.
+    # @param asset_id [Symbol] The asset to retrieve the claimable balance for
+    # @param mode [Symbol] The staking mode. Defaults to :default.
+    # @param options [Hash] Additional options for the staking operation
+    # @return [BigDecimal] The claimable balance
+    def claimable_balance(asset_id, mode: :default, options: {})
+      staking_balances(asset_id, mode: mode, options: options)[:claimable_balance]
+    end
+
+    # Lists the staking rewards for the address.
+    # @param asset_id [Symbol] The asset to retrieve staking rewards for
+    # @param start_time [Time] The start time for the rewards. Defaults to 1 month ago.
+    # @param end_time [Time] The end time for the rewards. Defaults to the current time.
+    # @param format [Symbol] The format to return the rewards in. Defaults to :usd.
+    # @return [Enumerable<Coinbase::StakingReward>] The staking rewards
+    def staking_rewards(asset_id, start_time: DateTime.now.prev_month(1), end_time: DateTime.now, format: :usd)
+      StakingReward.list(
+        network_id,
+        asset_id,
+        [id],
+        start_time: start_time,
+        end_time: end_time,
+        format: format
+      )
+    end
+
+    private
+
+    def validate_can_stake!(amount, asset_id, mode, options)
+      stakeable_balance = stakeable_balance(asset_id, mode: mode, options: options)
+
+      raise InsufficientFundsError.new(amount, stakeable_balance) unless stakeable_balance >= amount
+    end
+
+    def validate_can_unstake!(amount, asset_id, mode, options)
+      unstakeable_balance = unstakeable_balance(asset_id, mode: mode, options: options)
+
+      raise InsufficientFundsError.new(amount, unstakeable_balance) unless unstakeable_balance >= amount
+    end
+
+    def validate_can_claim_stake!(amount, asset_id, mode, options)
+      claimable_balance = claimable_balance(asset_id, mode: mode, options: options)
+
+      raise InsufficientFundsError.new(amount, claimable_balance) unless claimable_balance >= amount
+    end
+
+    def build_staking_operation(amount, asset_id, action, mode: :default, options: {})
+      operation_model = Coinbase.call_api do
+        asset = Coinbase::Asset.fetch(network_id, asset_id)
+        stake_api.build_staking_operation(
+          {
+            asset_id: asset.primary_denomination.to_s,
+            address_id: id,
+            action: action,
+            network_id: Coinbase.normalize_network(network_id),
+            options: {
+              amount: asset.to_atomic_amount(amount).to_i.to_s,
+              mode: mode
+            }.merge(options)
+          }
+        )
+      end
+
+      StakingOperation.new(operation_model)
+    end
+
+    def stake_api
+      @stake_api ||= Coinbase::Client::StakeApi.new(Coinbase.configuration.api_client)
+    end
+  end
+end

data/lib/coinbase/address/wallet_address.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'eth'
+
+module Coinbase
+  # 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.
+  class WalletAddress < Address
+    PAGE_LIMIT = 100
+
+    # 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. Can be nil.
+    def initialize(model, key)
+      @model = model
+      @key = key
+
+      super(model.network_id, model.address_id)
+    end
+
+    # Returns the Wallet ID of the Address.
+    # @return [String] The Wallet ID
+    def wallet_id
+      @model.wallet_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
+
+    # Transfers the given amount of the given Asset to the specified address or wallet.
+    # Only same-network Transfers are supported.
+    # @param amount [Integer, Float, BigDecimal] The amount of the Asset to send.
+    # @param asset_id [Symbol] The ID of the Asset to send. For Ether, :eth, :gwei, and :wei are supported.
+    # @param 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.
+    # @return [Coinbase::Transfer] The Transfer object.
+    def transfer(amount, asset_id, destination)
+      asset = Asset.fetch(network_id, asset_id)
+
+      destination_address, destination_network = destination_address_and_network(destination)
+
+      validate_can_transfer!(amount, asset, destination_network)
+
+      transfer = create_transfer(amount, asset, destination_address)
+
+      # 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?
+
+      broadcast_transfer(transfer, transfer.transaction.sign(@key))
+    end
+
+    # Trades the given amount of the given Asset for another Asset.
+    # Only same-network Trades are supported.
+    # @param amount [Integer, Float, BigDecimal] The amount of the Asset to send.
+    # @param from_asset_id [Symbol] The ID of the Asset to trade from. For Ether, :eth, :gwei, and :wei are supported.
+    # @param to_asset_id [Symbol] The ID of the Asset to trade to. For Ether, :eth, :gwei, and :wei are supported.
+    # @return [Coinbase::Trade] The Trade object.
+    def trade(amount, from_asset_id, to_asset_id)
+      from_asset = Asset.fetch(network_id, from_asset_id)
+      to_asset = Asset.fetch(network_id, to_asset_id)
+
+      validate_can_trade!(amount, from_asset)
+
+      trade = create_trade(amount, from_asset, to_asset)
+
+      # NOTE: Trading does not yet support server signers at this point.
+
+      payloads = { signed_payload: trade.transaction.sign(@key) }
+
+      payloads[:approve_tx_signed_payload] = trade.approve_transaction.sign(@key) unless trade.approve_transaction.nil?
+
+      broadcast_trade(trade, **payloads)
+    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
+
+    # 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
+
+    # 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...
+    # @return [Enumerable<Coinbase::Transfer>] Enumerator that returns the address's transfers
+    def transfers
+      Coinbase::Pagination.enumerate(lambda(&method(:fetch_transfers_page))) do |transfer|
+        Coinbase::Transfer.new(transfer)
+      end
+    end
+
+    # 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...
+    # @return [Enumerable<Coinbase::Trade>] Enumerator that returns the address's trades
+    def trades
+      Coinbase::Pagination.enumerate(lambda(&method(:fetch_trades_page))) do |trade|
+        Coinbase::Trade.new(trade)
+      end
+    end
+
+    # Returns a String representation of the WalletAddress.
+    # @return [String] a String representation of the WalletAddress
+    def to_s
+      "Coinbase::Address{id: '#{id}', network_id: '#{network_id}', wallet_id: '#{wallet_id}'}"
+    end
+
+    private
+
+    def fetch_transfers_page(page)
+      transfers_api.list_transfers(wallet_id, id, { limit: PAGE_LIMIT, page: page })
+    end
+
+    def fetch_trades_page(page)
+      trades_api.list_trades(wallet_id, id, { limit: PAGE_LIMIT, page: page })
+    end
+
+    def transfers_api
+      @transfers_api ||= Coinbase::Client::TransfersApi.new(Coinbase.configuration.api_client)
+    end
+
+    def trades_api
+      @trades_api ||= Coinbase::Client::TradesApi.new(Coinbase.configuration.api_client)
+    end
+
+    def destination_address_and_network(destination)
+      return [destination.default_address.id, destination.network_id] if destination.is_a?(Wallet)
+      return [destination.id, destination.network_id] if destination.is_a?(Address)
+
+      [destination, network_id]
+    end
+
+    def validate_can_transfer!(amount, asset, destination_network_id)
+      raise 'Cannot transfer from address without private key loaded' unless can_sign? || Coinbase.use_server_signer?
+
+      raise ArgumentError, 'Transfer must be on the same Network' unless destination_network_id == network_id
+
+      current_balance = balance(asset.asset_id)
+
+      return unless current_balance < amount
+
+      raise ArgumentError, "Insufficient funds: #{amount} requested, but only #{current_balance} available"
+    end
+
+    def create_transfer(amount, asset, destination)
+      create_transfer_request = {
+        amount: asset.to_atomic_amount(amount).to_i.to_s,
+        network_id: Coinbase.normalize_network(network_id),
+        asset_id: asset.primary_denomination.to_s,
+        destination: destination
+      }
+
+      transfer_model = Coinbase.call_api do
+        transfers_api.create_transfer(wallet_id, id, create_transfer_request)
+      end
+
+      Coinbase::Transfer.new(transfer_model)
+    end
+
+    def broadcast_transfer(transfer, signed_payload)
+      transfer_model = Coinbase.call_api do
+        transfers_api.broadcast_transfer(wallet_id, id, transfer.id, { signed_payload: signed_payload })
+      end
+
+      Coinbase::Transfer.new(transfer_model)
+    end
+
+    def validate_can_trade!(amount, from_asset)
+      raise 'Cannot trade from address without private key loaded' unless can_sign?
+
+      current_balance = balance(from_asset.asset_id)
+
+      return unless current_balance < amount
+
+      raise ArgumentError, "Insufficient funds: #{amount} requested, but only #{current_balance} available"
+    end
+
+    def create_trade(amount, from_asset, to_asset)
+      create_trade_request = {
+        amount: from_asset.to_atomic_amount(amount).to_i.to_s,
+        from_asset_id: from_asset.primary_denomination.to_s,
+        to_asset_id: to_asset.primary_denomination.to_s
+      }
+
+      trade_model = Coinbase.call_api do
+        trades_api.create_trade(wallet_id, id, create_trade_request)
+      end
+
+      Coinbase::Trade.new(trade_model)
+    end
+
+    def broadcast_trade(trade, signed_payload:, approve_tx_signed_payload: nil)
+      req = { signed_payload: signed_payload }
+
+      req[:approve_transaction_signed_payload] = approve_tx_signed_payload unless approve_tx_signed_payload.nil?
+
+      trade_model = Coinbase.call_api do
+        trades_api.broadcast_trade(wallet_id, id, trade.id, req)
+      end
+
+      Coinbase::Trade.new(trade_model)
+    end
+  end
+end