xrpl-ruby 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c84782686e7934255929a23850a5f514d0435ff79e47cde2739ed1e940a0235
-  data.tar.gz: b6b1c24d77a63365e8bf45f8a8b702332315057a8a7ec820ef830264e3ba446e
+  metadata.gz: a26ce8102c50640eec9433b64a9296c7d92635d66c42f2995456d913fff60d75
+  data.tar.gz: 60d3c026f1378a1d7cb79adcd6bbf830d518bb554b35286fe980010a14f4f11a
 SHA512:
-  metadata.gz: 9cdee47951edf9ac0a804e8f8335aea13625f0cf61f6262f229f1c7e8e569892821a201b80916f0f274ac8ed9c2de677a77e32c5ed113bfc5102d7dca7f0cafa
-  data.tar.gz: 6c6e8309646053ab8039c7eb9bac814d08c9984f8dba4a64ae290ce349ac5e8c739b7a81e1ecf6305d93623f2ca9ce5015e1435757b6aa9a3bf6e74e2c1a6759
+  metadata.gz: 975f1af5db2890d44ba6ac7266c2a927dc5e8bf4d3000a8e70bd864734dbba1e90495718b48300df5ca183077076de844b00c2844aa87c050d61263d5e43a12a
+  data.tar.gz: 85a70a5ebc31bde02941394182c93aeb1c09a57987fbadfcbac26efdd16e1b30fe786d1aefdefd2ee1fa3cf742b18dbde2edbb2983052869b8165411b6207fd5

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2026-08-05
+
+### Added
+- **Connection readiness**: `Client#connect!` (and `connect(wait: true)`) block until the
+  WebSocket connection is open; `#open?` and `#wait_until_open` expose the state, so requests
+  no longer race with connection setup.
+- **Faucet helper**: `XRPL.fund_wallet(client)` / `XRPL::Faucet` creates and funds a wallet on
+  the Testnet and waits until the account is funded on the ledger.
+- **Transaction lifecycle** on the client (client-centric design): `Client#autofill`,
+  `Client#submit`, and `Client#submit_and_wait` (reliable submission that polls until the
+  transaction is included in a validated ledger).
+- **Optional logger**: `Client.new(url, logger:)` — the library is silent by default and only
+  emits diagnostics through an injected logger.
+- Example scripts for funding a wallet, querying account info, and sending a payment.
+
+### Changed
+- The library no longer writes to `stdout` on its own; connection messages go through the
+  optional logger instead.
+
+## [0.5.2]
+
+### Added
+- Binary codec, address codec, key pairs (secp256k1 / ed25519), wallet, and a WebSocket
+  client with account and ledger public API wrappers.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alexander Busse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# XRPL-Ruby
+
+A pure-Ruby library to interact with the [XRP Ledger](https://xrpl.org) (XRPL) blockchain.
+
+## Features
+
+- Key and wallet management (secp256k1 and ed25519)
+- Address codec and binary (transaction) codec
+- WebSocket client for the XRP Ledger public API
+- Testnet faucet helper to create and fund wallets
+- Transaction lifecycle: autofill, sign, submit, and reliable "submit and wait"
+
+## Requirements
+
+- Ruby 3.0 or later
+
+## Installation
+
+Install the gem:
+
+```sh
+gem install xrpl-ruby
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem 'xrpl-ruby'
+```
+
+## Quick start
+
+```ruby
+require 'xrpl-ruby'
+
+# 1. Connect to the Testnet (blocks until the connection is ready)
+client = XRPL::Client.new(:testnet)
+client.connect!
+
+# 2. Create and fund a wallet using the Testnet faucet
+wallet = XRPL.fund_wallet(client)[:wallet]
+puts wallet.classic_address
+
+# 3. Look up the account on the ledger
+info = client.account_info_response(
+  account: wallet.classic_address,
+  ledger_index: 'validated'
+)
+puts info.dig('result', 'account_data', 'Balance')
+
+# 4. Send 1 XRP (1,000,000 drops) and wait for validation
+receiver = XRPL.fund_wallet(client)[:wallet]
+payment = {
+  'TransactionType' => 'Payment',
+  'Account'         => wallet.classic_address,
+  'Destination'     => receiver.classic_address,
+  'Amount'          => '1000000'
+}
+result = client.submit_and_wait(payment, wallet: wallet)
+puts result.dig('result', 'meta', 'TransactionResult') # => "tesSUCCESS"
+
+client.disconnect
+```
+
+The client is silent by default. To see diagnostic output, pass a logger:
+
+```ruby
+require 'logger'
+client = XRPL::Client.new(:testnet, logger: Logger.new($stdout))
+```
+
+More runnable examples are in the [`examples/`](examples) directory.
+
+## Running the tests
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+Integration tests talk to the real Testnet and are skipped by default. Enable them explicitly:
+
+```sh
+XRPL_NETWORK=1 bundle exec rspec spec/integration
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/AlexanderBuzz/xrpl-ruby>.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/binary-codec/binary_codec.rb

@@ -25,7 +25,9 @@ module BinaryCodec
     def binary_to_json(hex)
       parser = make_parser(hex)
       st_object = SerializedType.get_type_by_name('STObject')
-      JSON.parse(st_object.from_parser(parser).to_json)
+      result = st_object.from_parser(parser).to_json
+      result = JSON.generate(result) unless result.is_a?(String)
+      JSON.parse(result)
     end
 
     # Converts a JSON object to its binary representation.

data/lib/binary-codec/enums/definitions.rb

@@ -31,10 +31,12 @@ module BinaryCodec
           is_signing_field: field[1]['isSigningField'],
           type: field[1]['type']
         )
-        field_header = FieldHeader.new(type: @type_ordinals[field_info.type], nth: field_info.nth)
+        type_ordinal = @type_ordinals[field_info.type]
+        field_header = FieldHeader.new(type: type_ordinal, nth: field_info.nth)
 
         @field_info_map[field_name] = field_info
-        @field_id_name_map[Digest::MD5.hexdigest(Marshal.dump(field_header))] = field_name
+        key = (type_ordinal << 16) | field_info.nth
+        @field_id_name_map[key] = field_name
         @field_header_map[field_name] = field_header
       end
 
@@ -62,8 +64,8 @@ module BinaryCodec
     # @param field_header [FieldHeader] The field header.
     # @return [String] The name of the field.
     def get_field_name_from_header(field_header)
-       @field_id_name_map[Digest::MD5.hexdigest(Marshal.dump(field_header))]
-     end
+       @field_id_name_map[(field_header.type << 16) | field_header.nth]
+    end
 
     # Returns a FieldInstance for a given field name.
     # @param field_name [String] The name of the field.

data/lib/binary-codec/enums/fields.rb

@@ -22,7 +22,7 @@ module BinaryCodec
           header.push(type << 4, nth)
         end
       elsif nth < 16
-        header.push(nth,type)
+        header.push(nth, type)
       else
         header.push(0, type, nth)
       end

data/lib/binary-codec/serdes/binary_parser.rb

@@ -111,25 +111,19 @@ module BinaryCodec
     # Reads a field header from the stream.
     # @return [FieldHeader] The field header.
     def read_field_header
-      type = read_uint8
-      nth = type & 15
-      type >>= 4
+      first_byte = read_uint8
+      type = first_byte >> 4
+      nth = first_byte & 15
 
       if type == 0
         type = read_uint8
-        if type == 0 || type < 16
-          raise StandardError.new("Cannot read FieldOrdinal, type_code #{type} out of range")
-        end
       end
 
       if nth == 0
         nth = read_uint8
-        if nth == 0 || nth < 16
-          raise StandardError.new("Cannot read FieldOrdinal, field_code #{nth} out of range")
-        end
       end
 
-      FieldHeader.new(type: type, nth: nth) # (type << 16) | nth for read_field_ordinal
+      FieldHeader.new(type: type, nth: nth)
     end
 
     # Reads a field instance from the stream.
@@ -137,6 +131,8 @@ module BinaryCodec
     def read_field
       field_header = read_field_header
       field_name = @definitions.get_field_name_from_header(field_header)
+      
+      raise "Unknown field for header: type=#{field_header.type}, nth=#{field_header.nth}" if field_name.nil?
 
       @definitions.get_field_instance(field_name)
     end

data/lib/binary-codec/serdes/binary_serializer.rb

@@ -37,6 +37,15 @@ module BinaryCodec
     # @param value [Object] The value of the field.
     # @param is_unl_modify_workaround [Boolean] Whether to apply the UNLModify workaround.
     def write_field_and_value(field, value, is_unl_modify_workaround = false)
+      # Special case for Blob fields that are empty (e.g., SigningPubKey = "")
+      # In Ruby, Blob.from("") returns an empty Blob.
+      # If we want to force 0x00 length prefix, we handle it here.
+      if field.type == 'Blob' && (value == "" || (value.is_a?(Array) && value.empty?))
+        @sink.put(field.header.to_bytes)
+        @sink.put([0]) # length 0
+        return
+      end
+
       field_header = field.header
       associated_value = field.associated_type.from(value)
 
@@ -46,6 +55,9 @@ module BinaryCodec
         write_length_encoded(associated_value, is_unl_modify_workaround)
       else
         associated_value.to_byte_sink(@sink)
+        if field.type == 'STObject'
+          @sink.put([0xE1]) # ObjectEndMarker
+        end
       end
     end
 

data/lib/binary-codec/serdes/bytes_list.rb

@@ -16,10 +16,10 @@ module BinaryCodec
     end
 
     # Adds bytes to the list.
-    # @param bytes_arg [Array<Integer>] The bytes to add.
+    # @param bytes_arg [Array<Integer>, Integer] The bytes to add.
     # @return [BytesList] self for chaining.
     def put(bytes_arg)
-      bytes = bytes_arg.dup
+      bytes = bytes_arg.is_a?(Integer) ? [bytes_arg] : bytes_arg.dup
       @bytes_array << bytes
       self # Allow chaining
     end

data/lib/binary-codec/types/amount.rb

@@ -16,6 +16,8 @@ module BinaryCodec
 
     MAX_DROPS = BigDecimal("1e17")
     MIN_XRP = BigDecimal("1e-6")
+    MIN_XRP_DROPS = 1
+    MAX_XRP_DROPS = 10**17
 
     def initialize(bytes = nil)
       if bytes.nil?
@@ -35,60 +37,74 @@ module BinaryCodec
     def self.from(value)
       return value if value.is_a?(Amount)
 
-      amount = Array.new(8, 0) # Equivalent to a Uint8Array of 8 zeros
-
       if value.is_a?(String)
         Amount.assert_xrp_is_valid(value)
-
-        number = value.to_i # Use to_i for equivalent BigInt handling
-
-        int_buf = [Array.new(4, 0), Array.new(4, 0)]
-        BinaryCodec.write_uint32be(int_buf[0], (number >> 32) & 0xFFFFFFFF, 0)
-        BinaryCodec.write_uint32be(int_buf[1], number & 0xFFFFFFFF, 0)
-
-        amount = int_buf.flatten
-
-        amount[0] |= 0x40
-
-        return Amount.new(amount)
+        number = value.to_i
+        amount_bytes = int_to_bytes(number, 8)
+        amount_bytes[0] |= 0x40
+        return Amount.new(amount_bytes)
       end
 
-      if is_amount_object_iou?(value)
-        number = BigDecimal(value[:value])
-        self.assert_iou_is_valid(number)
+      if value.respond_to?(:key?)
+        val = value[:value] || value['value']
+        cur = value[:currency] || value['currency']
+        iss = value[:issuer] || value['issuer']
 
-        if number.zero?
-          amount[0] |= 0x80
-        else
-          scale = number.frac.to_s('F').split('.').last.size
-          unscaled_value = (number * (10**scale)).to_i
-          int_string = unscaled_value.abs.to_s.ljust(16, '0')
-          num = int_string.to_i
+        if val && cur && iss
+          number = BigDecimal(val.to_s)
+          
+          if number.precision > MAX_IOU_PRECISION
+            raise ArgumentError, 'Decimal precision out of range'
+          end
 
-          int_buf = [Array.new(4, 0), Array.new(4, 0)]
-          BinaryCodec.write_uint32be(int_buf[0], (num >> 32) & 0xFFFFFFFF)
-          BinaryCodec.write_uint32be(int_buf[1], num & 0xFFFFFFFF)
+          currency_inst = Currency.from(cur)
+          issuer_inst = AccountId.from(iss)
 
-          amount = int_buf.flatten
+          if number.zero?
+            iou_bytes = [0x80, 0, 0, 0, 0, 0, 0, 0]
+            return Amount.new(iou_bytes + currency_inst.to_bytes + issuer_inst.to_bytes)
+          end
 
-          amount[0] |= 0x80
+          is_positive = number >= 0
+          abs_value = number.abs
+          
+          exponent = (Math.log10(abs_value.to_f).floor) - 15
+          mantissa = (abs_value / (BigDecimal(10)**exponent)).to_i
 
-          if number > 0
-            amount[0] |= 0x40
+          while mantissa < 1000000000000000
+            mantissa *= 10
+            exponent -= 1
+          end
+          while mantissa > 9999999999999999
+            mantissa /= 10
+            exponent += 1
           end
 
-          exponent = number.exponent - 16
-          exponent_byte = 97 + exponent
-          amount[0] |= exponent_byte >> 2
-          amount[1] |= (exponent_byte & 0x03) << 6
+          exponent_byte = exponent + 97
+          b1 = (is_positive ? 0x40 : 0) | 0x80 | (exponent_byte >> 2)
+          b2 = ((exponent_byte & 0x03) << 6) | (mantissa >> 48)
+
+          iou_bytes = [
+            b1, b2,
+            (mantissa >> 40) & 0xff,
+            (mantissa >> 32) & 0xff,
+            (mantissa >> 24) & 0xff,
+            (mantissa >> 16) & 0xff,
+            (mantissa >> 8) & 0xff,
+            mantissa & 0xff
+          ]
+          return Amount.new(iou_bytes + currency_inst.to_bytes + issuer_inst.to_bytes)
         end
+      end
 
-        currency = Currency.from(value[:currency]).to_bytes
-        issuer = AccountId.from(value[:issuer]).to_bytes
-
-        return Amount.new(amount + currency + issuer)
+      if value.is_a?(Integer)
+        Amount.assert_xrp_is_valid(value.to_s)
+        amount_bytes = int_to_bytes(value, 8)
+        amount_bytes[0] |= 0x40
+        return Amount.new(amount_bytes)
       end
 
+      raise ArgumentError, "Cannot construct Amount from the value given"
     end
 
     # Read an amount from a BinaryParser
@@ -140,7 +156,6 @@ module BinaryCodec
         b2 = mantissa_bytes[1]
 
         is_positive = (b1 & 0x40) != 0
-        sign = is_positive ? '' : '-'
         exponent = ((b1 & 0x3f) << 2) + ((b2 & 0xff) >> 6) - 97
 
         mantissa_bytes[0] = 0
@@ -149,12 +164,15 @@ module BinaryCodec
         # Convert mantissa bytes to integer
         mantissa_int = mantissa_bytes.reduce(0) { |acc, b| (acc << 8) + b }
         
+        # value = mantissa * 10^exponent
         value = BigDecimal(mantissa_int) * (BigDecimal(10)**exponent)
         value = -value unless is_positive
-        self.class.assert_iou_is_valid(value)
+        
+        # Format the value string to match xrpl.js (stripping trailing .0)
+        formatted_value = value.to_s('F').sub(/\.0$/, '')
 
         return {
-          "value" => value.to_s('F').sub(/\.0$/, ''),
+          "value" => formatted_value,
           "currency" => currency.to_json,
           "issuer" => issuer.to_json
         }
@@ -186,17 +204,23 @@ module BinaryCodec
 
     # Type guard for AmountObjectIOU
     def self.is_amount_object_iou?(arg)
-      keys = arg.transform_keys(&:to_s).keys.sort
-
-      keys.length == 3 &&
-        keys[0] == 'currency' &&
-        keys[1] == 'issuer' &&
-        keys[2] == 'value'
+      return false unless arg.is_a?(::Hash)
+      
+      # Handle both string and symbol keys
+      processed = arg.transform_keys(&:to_s)
+      
+      # Log for debugging
+      # puts "DEBUG: Checking if #{processed.keys.inspect} is IOU"
+
+      processed.key?('currency') &&
+        processed.key?('issuer') &&
+        processed.key?('value')
     end
 
     # Type guard for AmountObjectMPT
     def self.is_amount_object_mpt?(arg)
-      keys = arg.keys.sort
+      return false unless arg.is_a?(::Hash)
+      keys = arg.transform_keys(&:to_s).keys.sort
 
       keys.length == 2 &&
         keys[0] == 'mpt_issuance_id' &&
@@ -212,9 +236,9 @@ module BinaryCodec
         raise "#{amount} is an illegal amount"
       end
 
-      decimal = BigDecimal(amount)
+      decimal = amount.to_i
       unless decimal.zero?
-        if decimal < MIN_XRP || decimal > MAX_DROPS
+        if decimal < MIN_XRP_DROPS || decimal > MAX_XRP_DROPS
           raise "#{amount} is an illegal amount"
         end
       end
@@ -267,10 +291,12 @@ module BinaryCodec
     # @raise [ArgumentError] if the value contains a decimal
     # @return [String] The decimal converted to a string without a decimal point
     def self.verify_no_decimal(decimal)
-      exponent = -((decimal.exponent || 0) - 16)
-      scaled_decimal = decimal * 10 ** exponent
-
-        raise ArgumentError, 'Decimal place found in int_string' unless scaled_decimal.frac == 0
+      # p is the number of significant digits
+      # e is the power of 10 to multiply by the mantissa to get the number
+      # BigDecimal('1.1234567891234567').precision => 17
+      if decimal.precision > MAX_IOU_PRECISION
+        raise ArgumentError, 'Decimal precision out of range'
+      end
     end
 
     # Check if this amount is in units of Native Currency (XRP)

data/lib/binary-codec/types/blob.rb

@@ -20,7 +20,7 @@ module BinaryCodec
         return Blob.new(hex_to_bytes(value))
       end
 
-      if value.is_a?(Array)
+      if value.is_a?(::Array)
         return Blob.new(value)
       end
 

data/lib/binary-codec/types/currency.rb

@@ -43,7 +43,7 @@ module BinaryCodec
         return new(bytes_from_representation(value))
       end
 
-      if value.is_a?(Array)
+      if value.is_a?(::Array)
         return new(value)
       end
 

data/lib/binary-codec/types/hash.rb

@@ -27,7 +27,7 @@ module BinaryCodec
         return new(hex_to_bytes(value))
       end
 
-      if value.is_a?(Array)
+      if value.is_a?(::Array)
         return new(value)
       end
 

data/lib/binary-codec/types/issue.rb

@@ -23,19 +23,13 @@ module BinaryCodec
       raise StandardError, "Cannot construct Issue from #{value.class}"
     end
 
-    def self.from_parser(parser, _hint = nil)
+    def self.from_parser(parser, size_hint = nil)
       bytes = []
+      return Issue.new(bytes) if parser.end?
       bytes.concat(parser.read(20)) # Currency
-      # If there are more bytes in this field, it might have an issuer?
-      # Actually Issue is often fixed length 20 or 40.
-      # For XChainBridge it uses Issue.
-      # Let's see how much we should read. 
-      # Usually if it's an Issue in a field, we might know the size.
-      # For now, let's assume it can be 20 or 40.
-      # But wait, how does the parser know?
-      # If it's not variable length, it must have a fixed width or be the rest of the object.
-      # Definitions.json says Issue is type 24.
-      bytes.concat(parser.read(20)) unless parser.end? # Try reading issuer
+      unless parser.end? || (size_hint && size_hint <= 20)
+        bytes.concat(parser.read(20))
+      end
       Issue.new(bytes)
     end
 
@@ -45,6 +39,9 @@ module BinaryCodec
       result['currency'] = Currency.from_parser(parser).to_json
       result['issuer'] = AccountId.from_parser(parser).to_json unless parser.end?
       result
+    rescue
+      # Fallback for partial/invalid binary
+      { 'currency' => Currency.new(to_bytes[0, 20]).to_json }
     end
   end
 end

data/lib/binary-codec/types/path_set.rb

@@ -20,7 +20,7 @@ module BinaryCodec
         return PathSet.new(hex_to_bytes(value))
       end
 
-      if value.is_a?(Array)
+      if value.is_a?(::Array)
         bytes = []
         value.each_with_index do |path, index|
           path.each do |step|