xrpl-ruby 0.2.4 → 0.6.0

data/lib/xrpl/faucet.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+require_relative 'client'
+
+module XRPL
+  # Raised when a faucet request fails or funding does not complete in time.
+  class FaucetError < StandardError; end
+
+  # Funds (and thereby activates) a wallet on an XRP Ledger test network via the
+  # public faucet, then waits until the account shows up on the ledger.
+  #
+  # This is the Ruby equivalent of the +fundWallet()+ helper used in the other
+  # XRPL SDKs. It is intended for Testnet/Devnet only.
+  #
+  # @example Fund a fresh wallet on the Testnet
+  #   client = XRPL::Client.new(:testnet)
+  #   client.connect!
+  #   result = XRPL.fund_wallet(client)
+  #   result[:wallet].classic_address # => "r..."
+  #   result[:balance]                # => 100000000000 (drops)
+  class Faucet
+    TESTNET_FAUCET = 'https://faucet.altnet.rippletest.net/accounts'
+    DEVNET_FAUCET  = 'https://faucet.devnet.rippletest.net/accounts'
+
+    DEFAULT_TIMEOUT = 40
+    DEFAULT_POLL_INTERVAL = 2
+
+    attr_reader :faucet_url
+
+    # @param faucet_url [String] the faucet endpoint to POST to.
+    def initialize(faucet_url: TESTNET_FAUCET)
+      @faucet_url = faucet_url
+    end
+
+    # Convenience wrapper matching the tutorial call style.
+    #
+    # @param client [XRPL::Client] a connected client used to poll for funding.
+    # @param wallet [Wallet::Wallet, nil] wallet to fund; a new one is generated when nil.
+    # @return [Hash] +{ wallet:, balance: }+ (balance in drops).
+    def self.fund_wallet(client, wallet = nil, faucet_url: TESTNET_FAUCET, **opts)
+      new(faucet_url: faucet_url).fund_wallet(client, wallet, **opts)
+    end
+
+    # Funds (and activates) a wallet on a test network.
+    #
+    # @param client [XRPL::Client] a connected client used to poll for funding.
+    # @param wallet [Wallet::Wallet, nil] wallet to fund; a new one is generated when nil.
+    # @param amount [Numeric, String, nil] optional XRP amount to request.
+    # @param timeout [Numeric] seconds to wait for the account to be funded.
+    # @param poll_interval [Numeric] seconds between ledger polls.
+    # @return [Hash] +{ wallet:, balance: }+ (balance in drops).
+    # @raise [XRPL::FaucetError] if the faucet request fails or funding times out.
+    def fund_wallet(client, wallet = nil, amount: nil, timeout: DEFAULT_TIMEOUT,
+                    poll_interval: DEFAULT_POLL_INTERVAL)
+      wallet ||= Wallet::Wallet.generate
+
+      request_funds(wallet.classic_address, amount)
+      balance = await_funding(
+        client, wallet.classic_address,
+        timeout: timeout, poll_interval: poll_interval
+      )
+
+      { wallet: wallet, balance: balance }
+    end
+
+    private
+
+    # POSTs a funding request to the faucet for the given address.
+    def request_funds(address, amount)
+      body = { destination: address }
+      body[:xrpAmount] = amount.to_s if amount
+
+      http_post(@faucet_url, body)
+    end
+
+    # Polls the ledger until the account is funded, i.e. it exists and shows a
+    # positive balance. (For a Testnet/get-started helper this simple
+    # "funded = has a balance" rule is robust: unlike waiting for a strict
+    # balance *increase*, it can never hang when a wallet already holds XRP.)
+    def await_funding(client, address, timeout:, poll_interval:)
+      deadline = monotonic_time + timeout
+
+      loop do
+        balance = current_balance(client, address)
+        return balance if balance && balance.positive?
+
+        if monotonic_time >= deadline
+          raise FaucetError, "Account #{address} was not funded within #{timeout} seconds"
+        end
+
+        sleep poll_interval
+      end
+    end
+
+    # Returns the account balance in drops, or nil if the account is not (yet)
+    # found or a transient lookup error occurs.
+    def current_balance(client, address)
+      response = client.account_info_response(account: address, ledger_index: 'validated')
+      drops = response.dig('result', 'account_data', 'Balance')
+      drops && Integer(drops)
+    rescue StandardError
+      nil
+    end
+
+    def http_post(url, body)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+
+      request = Net::HTTP::Post.new(uri.request_uri, 'Content-Type' => 'application/json')
+      request.body = JSON.generate(body)
+
+      response = http.request(request)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise FaucetError, "Faucet request failed: #{response.code} #{response.message}"
+      end
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  # Top-level convenience mirroring the other SDKs' +fundWallet()+ sugar.
+  #
+  # @see Faucet#fund_wallet
+  def self.fund_wallet(client, wallet = nil, **opts)
+    Faucet.fund_wallet(client, wallet, **opts)
+  end
+end

data/lib/xrpl/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XRPL
+  VERSION = '0.6.0'
+end

data/lib/xrpl-ruby.rb

@@ -1,14 +1,43 @@
 # frozen_string_literal: true
 
+require_relative 'xrpl/version'
+
+require_relative 'core/base_x'
+require_relative 'core/base_58_xrp'
 require_relative 'core/core'
+require_relative 'core/utilities'
 
 require_relative 'address-codec/codec'
 require_relative 'address-codec/xrp_codec'
 require_relative 'address-codec/address_codec'
 
+require_relative 'binary-codec/enums/constants'
+require_relative 'binary-codec/utilities'
 require_relative 'binary-codec/enums/fields'
 require_relative 'binary-codec/enums/definitions'
 require_relative 'binary-codec/serdes/binary_parser'
 require_relative 'binary-codec/serdes/bytes_list'
+require_relative 'binary-codec/serdes/binary_serializer'
 require_relative 'binary-codec/types/serialized_type'
-require_relative 'binary-codec/types/hash'
+require_relative 'binary-codec/types/hash'
+require_relative 'binary-codec/types/uint'
+require_relative 'binary-codec/types/account_id'
+require_relative 'binary-codec/types/amount'
+require_relative 'binary-codec/types/blob'
+require_relative 'binary-codec/types/currency'
+require_relative 'binary-codec/types/st_array'
+require_relative 'binary-codec/types/st_object'
+require_relative 'binary-codec/types/vector256'
+require_relative 'binary-codec/types/path_set'
+require_relative 'binary-codec/types/issue'
+require_relative 'binary-codec/types/xchain_bridge'
+require_relative 'binary-codec/binary_codec'
+
+require_relative 'wallet/wallet'
+
+require_relative 'key-pairs/ed25519'
+require_relative 'key-pairs/secp256k1'
+require_relative 'key-pairs/key_pairs'
+
+require_relative 'xrpl/client'
+require_relative 'xrpl/faucet'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xrpl-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexander Busse
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-20 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: ecdsa
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 description: This gem provides a Ruby interface to interact with the XRP Ledger (XRPL)
   blockchain, allowing developers to easily integrate XRPL functionality into their
   Ruby applications.
@@ -61,6 +117,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - lib/address-codec/address_codec.rb
 - lib/address-codec/codec.rb
 - lib/address-codec/xrp_codec.rb
@@ -77,18 +136,35 @@ files:
 - lib/binary-codec/types/blob.rb
 - lib/binary-codec/types/currency.rb
 - lib/binary-codec/types/hash.rb
+- lib/binary-codec/types/issue.rb
+- lib/binary-codec/types/path_set.rb
 - lib/binary-codec/types/serialized_type.rb
+- lib/binary-codec/types/st_array.rb
 - lib/binary-codec/types/st_object.rb
 - lib/binary-codec/types/uint.rb
+- lib/binary-codec/types/vector256.rb
+- lib/binary-codec/types/xchain_bridge.rb
 - lib/binary-codec/utilities.rb
 - lib/core/base_58_xrp.rb
 - lib/core/base_x.rb
 - lib/core/core.rb
+- lib/core/utilities.rb
+- lib/key-pairs/ed25519.rb
+- lib/key-pairs/key_pairs.rb
+- lib/key-pairs/secp256k1.rb
+- lib/wallet/wallet.rb
 - lib/xrpl-ruby.rb
+- lib/xrpl/client.rb
+- lib/xrpl/faucet.rb
+- lib/xrpl/version.rb
 homepage: https://github.com/AlexanderBuzz/xrpl-ruby
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/AlexanderBuzz/xrpl-ruby
+  source_code_uri: https://github.com/AlexanderBuzz/xrpl-ruby
+  changelog_uri: https://github.com/AlexanderBuzz/xrpl-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/AlexanderBuzz/xrpl-ruby/issues
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -97,7 +173,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="