xrpl-ruby 0.2.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6895a3507b4f4d76bb12cd9c150c2f395a35e44146ee45dea5579076c780fc56
-  data.tar.gz: a641537d7f0ce171f7ddf5380b0e3ab0d396a5a2ec5f884e090fe12ba1b49eb6
+  metadata.gz: a26ce8102c50640eec9433b64a9296c7d92635d66c42f2995456d913fff60d75
+  data.tar.gz: 60d3c026f1378a1d7cb79adcd6bbf830d518bb554b35286fe980010a14f4f11a
 SHA512:
-  metadata.gz: 453610629153989c93ff0ac3e504dfd4fa8fb90ccc3adbbac104522dee5b03192a7a6ba1d4206424f17174080ece7b897fc02b5bd513432979269df0dba7768b
-  data.tar.gz: ca5696e3df36e747e395f351043223d81a7445970db5d8b40d3cd398f9a1c70bff3495f926dea412920bb81cdfdbb78a825c9b3afa13e6b381ba84ea04ecfec4
+  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/address-codec/address_codec.rb

@@ -11,21 +11,31 @@ module AddressCodec
 
     MAX_32_BIT_UNSIGNED_INT = 4294967295
 
+    # Converts a classic address to an X-address.
+    # @param classic_address [String] The classic XRPL address to convert.
+    # @param tag [Integer, false, nil] The destination tag.
+    # @param test [Boolean] Whether the address is for a test network.
+    # @return [String] The encoded X-address.
     def classic_address_to_x_address(classic_address, tag, test)
       account_id = decode_account_id(classic_address)
       encode_x_address(account_id, tag, test)
     end
 
+    # Encodes an account ID and tag into an X-address.
+    # @param account_id [Array<Integer>] 20 bytes for the account ID.
+    # @param tag [Integer, false, nil] The destination tag.
+    # @param test [Boolean] Whether the address is for a test network.
+    # @return [String] The encoded X-address.
     def encode_x_address(account_id, tag, test)
       if account_id.length != 20
         # RIPEMD160 -> 160 Bits = 20 Bytes
         raise 'Account ID must be 20 bytes'
       end
-      if tag != false && tag > MAX_32_BIT_UNSIGNED_INT
+      if tag && tag != false && tag > MAX_32_BIT_UNSIGNED_INT
         raise 'Invalid tag'
       end
       the_tag = tag || 0
-      flag = tag == false || tag.nil? ? 0 : 1
+      flag = (tag == false || tag.nil?) ? 0 : 1
 
       bytes = concat_args(
         test ? PREFIX_BYTES[:test] : PREFIX_BYTES[:main],
@@ -46,6 +56,9 @@ module AddressCodec
       encode_checked(bytes)
     end
 
+    # Converts an X-address to a classic address.
+    # @param x_address [String] The X-address string to convert.
+    # @return [Hash] A hash containing :classic_address, :tag, and :test.
     def x_address_to_classic_address(x_address)
       decoded = decode_x_address(x_address)
       account_id = decoded[:account_id]
@@ -59,6 +72,9 @@ module AddressCodec
       }
     end
 
+    # Decodes an X-address into its underlying account ID, tag, and network type.
+    # @param x_address [String] The X-address string to decode.
+    # @return [Hash] A hash containing :account_id, :tag, and :test.
     def decode_x_address(x_address)
       decoded = decode_checked(x_address)
       test = is_uint8_array_for_test_address(decoded)
@@ -71,6 +87,9 @@ module AddressCodec
       }
     end
 
+    # Checks if a string is a valid X-address.
+    # @param x_address [String] The X-address string to check.
+    # @return [Boolean] True if the X-address is valid, false otherwise.
     def valid_x_address?(x_address)
       begin
         decode_x_address(x_address)
@@ -97,11 +116,9 @@ module AddressCodec
     def tag_from_uint8_array(bytes)
       flag = bytes[22]
       if flag >= 2
-        # Keine Unterstützung für 64-Bit-Tags zu diesem Zeitpunkt
         raise 'Unsupported X-address'
       end
       if flag == 1
-        # Little-endian zu Big-endian
         return bytes[23] + bytes[24] * 0x100 + bytes[25] * 0x10000 + bytes[26] * 0x1000000
       end
       if flag != 0

data/lib/address-codec/codec.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
-#
+
 require 'digest'
-require_relative "../core/core"
 
 module AddressCodec
   class Codec
@@ -10,11 +9,19 @@ module AddressCodec
       @codec = Core::Base58XRP.new
     end
 
+    # Encodes a byte array into a base58 string with a version prefix and checksum.
+    # @param bytes [Array<Integer>] The byte array to encode.
+    # @param opts [Hash] Options for encoding (e.g., :versions, :expected_length).
+    # @return [String] The encoded base58 string.
     def encode(bytes, opts)
       versions = opts[:versions]
       encode_versioned(bytes, versions, opts[:expected_length])
     end
 
+    # Decodes a base58 string and verifies its version and checksum.
+    # @param base58string [String] The base58 string to decode.
+    # @param opts [Hash] Options for decoding (e.g., :versions, :version_types, :expected_length).
+    # @return [Hash] The decoded data including version, bytes, and type.
     def decode(base58string, opts)
       versions = opts[:versions]
       types = opts[:version_types]
@@ -44,11 +51,17 @@ module AddressCodec
       raise 'version_invalid: version bytes do not match any of the provided version(s)'
     end
 
+    # Encodes a byte array into a base58 string with a checksum.
+    # @param bytes [Array<Integer>] The byte array to encode.
+    # @return [String] The encoded base58 string.
     def encode_checked(bytes)
       check = sha256(sha256(bytes))[0, 4]
       encode_raw(bytes + check)
     end
 
+    # Decodes a base58 string and verifies its checksum.
+    # @param base58string [String] The base58 string to decode.
+    # @return [Array<Integer>] The decoded byte array (without checksum).
     def decode_checked(base58string)
       bytes = decode_raw(base58string)
 

data/lib/address-codec/xrp_codec.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../core/core"
-
 module AddressCodec
 
   class XrpCodec < Codec
@@ -13,6 +11,10 @@ module AddressCodec
     NODE_PUBLIC = 0x1c        # 28; Validation public key (33 bytes)
     ED25519_SEED = [0x01, 0xe1, 0x4b].freeze # [1, 225, 75]
 
+    # Encodes entropy into a seed string.
+    # @param entropy [Array<Integer>] 16 bytes of entropy.
+    # @param type [String, nil] The seed type ('ed25519' or 'secp256k1').
+    # @return [String] The encoded seed string.
     def encode_seed(entropy, type = nil)
       unless check_byte_length(entropy, 16)
         raise 'entropy must have length 16'
@@ -27,6 +29,10 @@ module AddressCodec
       encode(entropy, opts)
     end
 
+    # Decodes a seed string into its underlying bytes and type.
+    # @param seed [String] The seed string to decode.
+    # @param opts [Hash] Options for decoding (e.g., :versions, :version_types, :expected_length).
+    # @return [Hash] The decoded data including version, bytes, and type.
     def decode_seed(seed, opts = {
           version_types: ['ed25519', 'secp256k1'],
           versions: [ED25519_SEED, FAMILY_SEED],
@@ -35,36 +41,57 @@ module AddressCodec
       decode(seed, opts)
     end
 
+    # Encodes a byte array into an account ID string.
+    # @param bytes [Array<Integer>] 20 bytes for the account ID.
+    # @return [String] The encoded account ID string.
     def encode_account_id(bytes)
       opts = { versions: [ACCOUNT_ID], expected_length: 20 }
       encode(bytes, opts)
     end
 
+    # Decodes an account ID string into its underlying bytes.
+    # @param account_id [String] The account ID string to decode.
+    # @return [Array<Integer>] The decoded bytes.
     def decode_account_id(account_id)
       opts = { versions: [ACCOUNT_ID], expected_length: 20 }
       decode(account_id, opts)[:bytes]
     end
 
+    # Decodes a node public key string into its underlying bytes.
+    # @param base58string [String] The node public key string to decode.
+    # @return [Array<Integer>] The decoded bytes.
     def decode_node_public(base58string)
       opts = { versions: [NODE_PUBLIC], expected_length: 33 }
       decode(base58string, opts)[:bytes]
     end
 
+    # Encodes a byte array into a node public key string.
+    # @param bytes [Array<Integer>] 33 bytes for the node public key.
+    # @return [String] The encoded node public key string.
     def encode_node_public(bytes)
       opts = { versions: [NODE_PUBLIC], expected_length: 33 }
       encode(bytes, opts)
     end
 
+    # Encodes a byte array into an account public key string.
+    # @param bytes [Array<Integer>] 33 bytes for the account public key.
+    # @return [String] The encoded account public key string.
     def encode_account_public(bytes)
       opts = { versions: [ACCOUNT_PUBLIC_KEY], expected_length: 33 }
       encode(bytes, opts)
     end
 
+    # Decodes an account public key string into its underlying bytes.
+    # @param base58string [String] The account public key string to decode.
+    # @return [Array<Integer>] The decoded bytes.
     def decode_account_public(base58string)
       opts = { versions: [ACCOUNT_PUBLIC_KEY], expected_length: 33 }
       decode(base58string, opts)[:bytes]
     end
 
+    # Checks if a string is a valid classic XRPL address.
+    # @param address [String] The address string to check.
+    # @return [Boolean] True if the address is valid, false otherwise.
     def valid_classic_address?(address)
       begin
         decode_account_id(address)

data/lib/binary-codec/binary_codec.rb

@@ -1,38 +1,64 @@
 # frozen_string_literal: true
 
 module BinaryCodec
-  class BinaryCodec
-
-    # from here: https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/binary.ts
+  # Hash prefixes for serialization.
+  HASH_PREFIX = {
+    transaction_sig: 0x53545800, # 'STX\0'
+    transaction_multi_sig: 0x534D5400, # 'SMT\0'
+    validation: 0x56414C00, # 'VAL\0'
+    proposal: 0x50525000 # 'PRP\0'
+  }.freeze
 
+  # from here: https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/binary.ts
+  class << self
+    # Creates a BinaryParser for the given bytes.
+    # @param bytes [String, Array<Integer>] The bytes to parse (hex string or byte array).
+    # @param definitions [Definitions, nil] Optional definitions.
+    # @return [BinaryParser] The created parser.
     def make_parser(bytes, definitions = nil)
       BinaryParser.new(bytes.is_a?(String) ? bytes : bytes_to_hex(bytes))
     end
 
-    #def read_json(parser, definitions = DEFAULT_DEFINITIONS)
-    def read_json(parser)
-      # parser.read_type(core_types[:STObject]).to_json(definitions)
-      parser.read_type(core_types[:STObject]).to_json()
-    end
-
+    # Converts a hex string to its JSON representation.
+    # @param hex [String] The hex string to convert.
+    # @return [Hash] The decoded JSON object.
     def binary_to_json(hex)
       parser = make_parser(hex)
-      read_json(parser)
+      st_object = SerializedType.get_type_by_name('STObject')
+      result = st_object.from_parser(parser).to_json
+      result = JSON.generate(result) unless result.is_a?(String)
+      JSON.parse(result)
     end
 
-    def serialize_object(obj, definitions = nil)
-      BytesList.new.put_type(core_types[:STObject], obj)
+    # Converts a JSON object to its binary representation.
+    # @param json [Hash] The JSON object to convert.
+    # @return [String] The serialized hex string.
+    def json_to_binary(json)
+      st_object = SerializedType.get_type_by_name('STObject')
+      st_object.from(json).to_hex
     end
 
-    def signing_data(transaction, prefix = HashPrefix[:transaction_sig], opts = {})
-      serialize_object(
-        transaction,
-        prefix: prefix,
-        signing_fields_only: true,
-        definitions: opts[:definitions]
-      )
-    end
+    # Generates signing data for a transaction.
+    # @param transaction [Hash] The transaction to serialize.
+    # @param prefix [Integer] The prefix to add to the serialized data.
+    # @param opts [Hash] Optional settings (e.g., :definitions, :signing_fields_only).
+    # @return [Array<Integer>] The serialized signing data.
+    def signing_data(transaction, prefix = HASH_PREFIX[:transaction_sig], opts = {})
+      # 1. Start with the prefix bytes
+      prefix_bytes = int_to_bytes(prefix, 4)
 
-  end
+      # 2. Serialize the object, only including signing fields
+      st_object_class = SerializedType.get_type_by_name('STObject')
 
+      filter = if opts[:signing_fields_only]
+                 lambda { |field_name| Definitions.instance.get_field_instance(field_name).is_signing_field }
+               else
+                 nil
+               end
+
+      serialized_bytes = st_object_class.from(transaction, filter).to_bytes
+
+      prefix_bytes + serialized_bytes
+    end
+  end
 end