xrpl-ruby 0.2.4 → 0.5.0

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

@@ -3,18 +3,27 @@
 module BinaryCodec
 
   class Uint < ComparableSerializedType
-    class << self
-      attr_reader :width
+    # Returns the width of the Uint type in bytes.
+    # @return [Integer] The width.
+    def self.width
+      @width
     end
 
     def initialize(byte_buf = nil)
-      @bytes = byte_buf || Array.new(self.class.width, 0)
+      super(byte_buf || Array.new(self.class.width, 0))
     end
 
+    # Creates a new Uint instance from a value.
+    # @param value [Uint, String, Integer] The value to convert.
+    # @return [Uint] The created instance.
     def self.from(value)
       return value if value.is_a?(self)
 
       if value.is_a?(String)
+        # Handle hex strings or numeric strings
+        if valid_hex?(value) && value.length == self.width * 2
+          return new(hex_to_bytes(value))
+        end
         return new(int_to_bytes(value.to_i, width))
       end
 
@@ -25,9 +34,26 @@ module BinaryCodec
       raise StandardError, "Cannot construct #{self} from the value given"
     end
 
+    # Creates a Uint instance from a parser.
+    # @param parser [BinaryParser] The parser to read from.
+    # @param _hint [Integer, nil] Unused hint.
+    # @return [Uint] The created instance.
+    def self.from_parser(parser, _hint = nil)
+      new(parser.read(width))
+    end
+
+    # Returns the numeric value of the Uint.
+    # @return [Integer] The numeric value.
     def value_of
       @bytes.reduce(0) { |acc, byte| (acc << 8) + byte }
     end
+
+    # Compares this Uint to another Uint.
+    # @param other [Uint] The other Uint to compare to.
+    # @return [Integer] Comparison result (-1, 0, or 1).
+    def compare_to(other)
+      value_of <=> other.value_of
+    end
   end
 
   class Uint8 < Uint
@@ -50,4 +76,91 @@ module BinaryCodec
     @width = 8
   end
 
+  class Uint96 < Uint
+    # Uint96 is a 12-byte unsigned integer
+    @width = 12
+  end
+
+  class Uint128 < Uint
+    # Uint128 is a 16-byte unsigned integer
+    @width = 16
+  end
+
+  class Uint160 < Uint
+    # Uint160 is a 20-byte unsigned integer
+    @width = 20
+  end
+
+  class Uint192 < Uint
+    # Uint192 is a 24-byte unsigned integer
+    @width = 24
+  end
+
+  class Uint256 < Uint
+    # Uint256 is a 32-byte unsigned integer
+    @width = 32
+  end
+
+  class Uint384 < Uint
+    # Uint384 is a 48-byte unsigned integer
+    @width = 48
+  end
+
+  class Uint512 < Uint
+    # Uint512 is a 64-byte unsigned integer
+    @width = 64
+  end
+
+  class Int32 < Uint
+    @width = 4
+    # Returns the numeric value of the Int32.
+    # @return [Integer] The signed 32-bit value.
+    def value_of
+      val = super
+      val > 0x7FFFFFFF ? val - 0x100000000 : val
+    end
+
+    # Creates a new Int32 instance from a value.
+    # @param value [Int32, Integer] The value to convert.
+    # @return [Int32] The created instance.
+    def self.from(value)
+      return value if value.is_a?(self)
+      if value.is_a?(Integer)
+        # Ensure it fits in 32-bit signed
+        if value < -2147483648 || value > 2147483647
+          raise StandardError, "Value #{value} out of range for Int32"
+        end
+        # Convert to unsigned 32-bit for storage
+        u_val = value < 0 ? value + 0x100000000 : value
+        return new(int_to_bytes(u_val, 4))
+      end
+      super(value)
+    end
+  end
+
+  class Int64 < Uint
+    @width = 8
+    # Returns the numeric value of the Int64.
+    # @return [Integer] The signed 64-bit value.
+    def value_of
+      val = super
+      val > 0x7FFFFFFFFFFFFFFF ? val - 0x10000000000000000 : val
+    end
+
+    # Creates a new Int64 instance from a value.
+    # @param value [Int64, Integer] The value to convert.
+    # @return [Int64] The created instance.
+    def self.from(value)
+      return value if value.is_a?(self)
+      if value.is_a?(Integer)
+        if value < -9223372036854775808 || value > 9223372036854775807
+          raise StandardError, "Value #{value} out of range for Int64"
+        end
+        u_val = value < 0 ? value + 0x10000000000000000 : value
+        return new(int_to_bytes(u_val, 8))
+      end
+      super(value)
+    end
+  end
+
 end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module BinaryCodec
+  class Vector256 < SerializedType
+    def initialize(bytes = nil)
+      super(bytes || [])
+    end
+
+    # Creates a new Vector256 instance from a value.
+    # @param value [Vector256, String, Array<String>] The value to convert.
+    # @return [Vector256] The created instance.
+    def self.from(value)
+      return value if value.is_a?(Vector256)
+
+      if value.is_a?(String)
+        return Vector256.new(hex_to_bytes(value))
+      end
+
+      if value.is_a?(Array)
+        bytes = []
+        value.each do |item|
+          hash = Hash256.from(item)
+          bytes.concat(hash.to_bytes)
+        end
+        return Vector256.new(bytes)
+      end
+
+      raise StandardError, "Cannot construct Vector256 from #{value.class}"
+    end
+
+    # Creates a Vector256 instance from a parser.
+    # @param parser [BinaryParser] The parser to read from.
+    # @param size_hint [Integer] The expected total size in bytes.
+    # @return [Vector256] The created instance.
+    def self.from_parser(parser, size_hint = nil)
+      bytes = []
+      num_hashes = size_hint / 32
+      num_hashes.times do
+        bytes.concat(parser.read(32))
+      end
+      Vector256.new(bytes)
+    end
+
+    def to_json(_definitions = nil, _field_name = nil)
+      parser = BinaryParser.new(to_hex)
+      result = []
+      until parser.end?
+        result << bytes_to_hex(parser.read(32))
+      end
+      result
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BinaryCodec
+  class XChainBridge < SerializedType
+    def initialize(bytes = nil)
+      super(bytes || [])
+    end
+
+    def self.from(value)
+      return value if value.is_a?(XChainBridge)
+
+      if value.is_a?(String)
+        return XChainBridge.new(hex_to_bytes(value))
+      end
+
+      if value.is_a?(Hash)
+        bytes = []
+        bytes.concat(AccountId.from(value['LockingChainDoor']).to_bytes)
+        bytes.concat(Issue.from(value['LockingChainIssue']).to_bytes)
+        bytes.concat(AccountId.from(value['IssuingChainDoor']).to_bytes)
+        bytes.concat(Issue.from(value['IssuingChainIssue']).to_bytes)
+        return XChainBridge.new(bytes)
+      end
+
+      raise StandardError, "Cannot construct XChainBridge from #{value.class}"
+    end
+
+    def self.from_parser(parser, _hint = nil)
+      bytes = []
+      bytes.concat(parser.read(20)) # LockingChainDoor
+      bytes.concat(Issue.from_parser(parser).to_bytes) # LockingChainIssue
+      bytes.concat(parser.read(20)) # IssuingChainDoor
+      bytes.concat(Issue.from_parser(parser).to_bytes) # IssuingChainIssue
+      XChainBridge.new(bytes)
+    end
+
+    def to_json(_definitions = nil, _field_name = nil)
+      parser = BinaryParser.new(to_hex)
+      result = {}
+      result['LockingChainDoor'] = AccountId.from_parser(parser).to_json
+      result['LockingChainIssue'] = Issue.from_parser(parser).to_json
+      result['IssuingChainDoor'] = AccountId.from_parser(parser).to_json
+      result['IssuingChainIssue'] = Issue.from_parser(parser).to_json
+      result
+    end
+  end
+end

data/lib/binary-codec/utilities.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module BinaryCodec
 
   # Write an 8-bit unsigned integer
@@ -77,4 +79,20 @@ module BinaryCodec
     (array.length % 4).zero?
   end
 
+  # TODO: Marked for overhaul
+  def self.is_valid_x_address?(x_address)
+    return false unless x_address.is_a?(String) && x_address.start_with?('X')
+
+    begin
+      decoded = decode_x_address(x_address)
+      return false if decoded[:account_id].nil? || decoded[:account_id].length != 20
+
+      tag = decoded[:tag]
+      return false if tag && (tag < 0 || tag > MAX_32_BIT_UNSIGNED_INT)
+
+      true
+    rescue StandardError
+      false
+    end
+  end
 end

data/lib/core/base_58_xrp.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Core
 
   class Base58XRP < BaseX

data/lib/core/base_x.rb

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 module Core
 
   class BaseX
+    # Initializes a new BaseX instance with the given alphabet.
+    # @param alphabet [String] The alphabet to use for encoding and decoding.
     def initialize(alphabet)
       @alphabet = alphabet
       @base = alphabet.length
@@ -8,6 +12,9 @@ module Core
       alphabet.chars.each_with_index { |char, index| @alphabet_map[char] = index }
     end
 
+    # Encodes a byte array into a string using the alphabet.
+    # @param buffer [String] The byte string to encode.
+    # @return [String] The encoded string.
     def encode(buffer)
       return @alphabet[0] if buffer.empty?
 
@@ -30,6 +37,9 @@ module Core
       digits.reverse.map { |digit| @alphabet[digit] }.join
     end
 
+    # Decodes a string into a byte string using the alphabet.
+    # @param string [String] The string to decode.
+    # @return [String] The decoded byte string.
     def decode(string)
       return '' if string.empty?
 

data/lib/core/core.rb

@@ -1,42 +1,70 @@
-# @!attribute
-require_relative 'base_x'
-require_relative 'base_58_xrp'
+# frozen_string_literal: true
+
 require 'securerandom'
 
+# Returns a random byte array of the given size.
+# @param size [Integer] The number of bytes to generate.
+# @return [Array<Integer>] The generated random byte array.
 def random_bytes(size)
   SecureRandom.random_bytes(size).bytes
 end
 
+# Converts a byte array to a hex string.
+# @param bytes [Array<Integer>] The byte array to convert.
+# @return [String] The hex string.
 def bytes_to_hex(bytes)
   bytes.pack('C*').unpack1('H*').upcase
 end
+# Converts a hex string to a byte array.
+# @param hex [String] The hex string to convert.
+# @return [Array<Integer>] The byte array.
 def hex_to_bytes(hex)
   raise ArgumentError, 'Invalid hex string' unless valid_hex?(hex)
   [hex].pack('H*').bytes
 end
 
+# Converts a binary string to a hex string.
+# @param bin [String] The binary string to convert.
+# @return [String] The hex string.
 def bin_to_hex(bin)
   bin.unpack("H*").first.upcase
 end
 
+# Converts a hex string to a binary string.
+# @param hex [String] The hex string to convert.
+# @return [String] The binary string.
 def hex_to_bin(hex)
   raise ArgumentError, 'Invalid hex string' unless valid_hex?(hex)
   [hex].pack("H*")
 end
 
+# Converts a hex string to a string with the given encoding.
+# @param hex [String] The hex string to convert.
+# @param encoding [String] The encoding to use.
+# @return [String] The decoded string.
 def hex_to_string(hex, encoding = 'utf-8')
   raise ArgumentError, 'Invalid hex string' unless valid_hex?(hex)
   hex_to_bin(hex).force_encoding(encoding).encode('utf-8')
 end
 
+# Converts a string to a hex string.
+# @param string [String] The string to convert.
+# @return [String] The hex string.
 def string_to_hex(string)
   string.unpack1('H*').upcase
 end
 
+# Checks if a string is a valid hex string.
+# @param str [String] The string to check.
+# @return [Boolean] True if the string is a valid hex string, false otherwise.
 def valid_hex?(str)
   str =~ /\A[0-9a-fA-F]*\z/ && str.length.even?
 end
 
+# Checks if a byte array has the expected length.
+# @param bytes [Array<Integer>, String] The byte array or string to check.
+# @param expected_length [Integer] The expected length.
+# @return [Boolean] True if the length matches, false otherwise.
 def check_byte_length(bytes, expected_length)
   if bytes.respond_to?(:byte_length)
     bytes.byte_length == expected_length
@@ -45,24 +73,34 @@ def check_byte_length(bytes, expected_length)
   end
 end
 
+# Concatenates multiple arguments into a single array.
+# @param args [Array] The arguments to concatenate.
+# @return [Array] The concatenated array.
 def concat_args(*args)
   args.flat_map do |arg|
     is_scalar?(arg) ? [arg] : arg.to_a
   end
 end
 
+# Checks if a value is a scalar.
+# @param val [Object] The value to check.
+# @return [Boolean] True if the value is a numeric scalar, false otherwise.
 def is_scalar?(val)
   val.is_a?(Numeric)
 end
 
+# Converts an integer to a byte array.
+# @param number [Integer] The integer to convert.
+# @param width [Integer] The number of bytes in the result.
+# @param byteorder [Symbol] The byte order (:big or :little).
+# @return [Array<Integer>] The byte array.
 def int_to_bytes(number, width = 1, byteorder = :big)
   bytes = []
   while number > 0
-    bytes << (number & 0xFF) # Extract the lowest 8 bits (1 byte)
-    number >>= 8             # Shift the number 8 bits to the right
+    bytes << (number & 0xFF)
+    number >>= 8
   end
 
-  # Ensure the result has at least `width` bytes (pad with zeroes if necessary)
   while bytes.size < width
     bytes << 0
   end

data/lib/core/utilities.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Core
+
+  class Utilities
+
+    @address_codec = nil
+
+    def initialize
+      @address_codec = AddressCodec.new
+    end
+
+    # Returns the singleton instance of the Utilities class.
+    # @return [Utilities] The singleton instance.
+    def self.instance
+      @@instance ||= new
+    end
+
+    # Checks if a string is a valid X-address.
+    # @param x_address [String] The X-address to check.
+    # @return [Boolean] True if the string is a valid X-address, false otherwise.
+    def is_x_address?(x_address)
+      return false unless x_address.is_a?(String) && x_address.start_with?('X')
+
+      begin
+        decoded = @address_codec.decode_x_address(x_address)
+        return false if decoded[:account_id].nil? || decoded[:account_id].length != 20
+
+        tag = decoded[:tag]
+        return false if tag && (tag < 0 || tag > MAX_32_BIT_UNSIGNED_INT)
+
+        true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/key-pairs/ed25519.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'ed25519'
+
+module KeyPairs
+  # Ed25519 implementation for XRPL key pairs.
+  module Ed25519
+    # Derives a key pair from a seed.
+    # @param seed [Array<Integer>] 16 bytes of seed entropy.
+    # @return [Hash] A hash containing :public_key and :private_key (hex strings).
+    def self.derive_key_pair(seed)
+      # XRPL Ed25519 uses the SHA512 of the 16-byte seed as the 32-byte entropy for the signing key.
+      seed_bytes = seed.is_a?(Array) ? seed.pack('C*') : seed
+      hash = Digest::SHA512.digest(seed_bytes)[0...32]
+      signing_key = ::Ed25519::SigningKey.new(hash)
+      
+      # Public key in XRPL is 0xED followed by 32 bytes of public key.
+      public_key = [0xED].pack('C') + signing_key.verify_key.to_bytes
+      
+      # Private key in XRPL is the 32-byte hash.
+      {
+        public_key: public_key.unpack1('H*').upcase,
+        private_key: hash.unpack1('H*').upcase
+      }
+    end
+
+    # Signs a message with a private key.
+    # @param message [Array<Integer>, String] The message to sign.
+    # @param private_key [String] The private key (32-byte hash as hex).
+    # @return [String] The signature (hex string).
+    def self.sign(message, private_key)
+      msg_bytes = message.is_a?(String) ? [message].pack('H*') : message.pack('C*')
+      key_bytes = [private_key].pack('H*')
+      signing_key = ::Ed25519::SigningKey.new(key_bytes)
+      
+      signature = signing_key.sign(msg_bytes)
+      signature.unpack1('H*').upcase
+    end
+
+    # Verifies a signature.
+    # @param message [Array<Integer>, String] The message.
+    # @param signature [String] The signature (hex string).
+    # @param public_key [String] The public key (33-byte hex, starts with ED).
+    # @return [Boolean] True if the signature is valid.
+    def self.verify(message, signature, public_key)
+      msg_bytes = message.is_a?(String) ? hex_to_bin(message) : message.pack('C*')
+      sig_bytes = [signature].pack('H*')
+      
+      # Strip the 0xED prefix from the public key
+      pub_bytes = [public_key].pack('H*')
+      if pub_bytes[0].ord != 0xED
+        raise ArgumentError, "Invalid Ed25519 public key prefix"
+      end
+      
+      verify_key = ::Ed25519::VerifyKey.new(pub_bytes[1..-1])
+      begin
+        verify_key.verify(sig_bytes, msg_bytes)
+        true
+      rescue ::Ed25519::VerifyError
+        false
+      end
+    end
+  end
+end

data/lib/key-pairs/key_pairs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module KeyPairs
+  # Main entry point for XRPL key pair operations.
+  class KeyPairs
+    def initialize
+      @address_codec = AddressCodec::AddressCodec.new
+    end
+
+    # Generates a new seed.
+    # @param entropy [Array<Integer>, nil] 16 bytes of entropy.
+    # @param type [String] The seed type ('secp256k1' or 'ed25519').
+    # @return [String] The encoded seed string.
+    def generate_seed(entropy = nil, type = 'secp256k1')
+      entropy ||= SecureRandom.random_bytes(16).bytes
+      @address_codec.encode_seed(entropy, type)
+    end
+
+    # Derives a key pair from an encoded seed.
+    # @param seed [String] The encoded seed string.
+    # @param options [Hash] Options including :account_index (for secp256k1).
+    # @return [Hash] A hash containing :public_key and :private_key (hex strings).
+    def derive_key_pair(seed, options = {})
+      decoded = @address_codec.decode_seed(seed)
+      type = decoded[:type]
+      entropy = decoded[:bytes]
+
+      if type == 'ed25519'
+        Ed25519.derive_key_pair(entropy)
+      else
+        # For secp256k1, we use the entropy as seed
+        Secp256k1.derive_key_pair(entropy)
+      end
+    end
+
+    # Signs a message with a private key.
+    # @param message [String] The message to sign as hex.
+    # @param private_key [String] The private key as hex.
+    # @param algorithm [String, nil] The algorithm to use ('secp256k1' or 'ed25519').
+    # @return [String] The signature as hex.
+    def sign(message, private_key, algorithm = nil)
+      if algorithm == 'ed25519' || (algorithm.nil? && private_key.length == 64)
+        # Heuristic: Ed25519 private keys in our lib are 32 bytes (64 hex chars).
+        # Secp256k1 are also 32 bytes, but Ed25519 is often explicitly requested.
+        # Actually, let's look at the prefix of the public key if we had it.
+        # Since we don't have the public key here, we rely on the caller or length.
+        # In XRPL-Ruby, Ed25519 private keys are 64 hex chars (32 bytes).
+        # Secp256k1 are also 64 hex chars. This is ambiguous!
+        # Let's try to see if it's explicitly 'ed25519'.
+        begin
+          return Ed25519.sign(message, private_key) if algorithm == 'ed25519'
+          return Secp256k1.sign(message, private_key)
+        rescue => e
+          # If secp fails and we didn't specify, maybe it was ed? 
+          # But that's dangerous.
+          raise e
+        end
+      else
+        Secp256k1.sign(message, private_key)
+      end
+    end
+
+    # Verifies a signature.
+    # @param message [String] The message as hex.
+    # @param signature [String] The signature as hex.
+    # @param public_key [String] The public key as hex.
+    # @return [Boolean] True if the signature is valid.
+    def verify(message, signature, public_key)
+      if public_key.start_with?('ED')
+        Ed25519.verify(message, signature, public_key)
+      else
+        Secp256k1.verify(message, signature, public_key)
+      end
+    end
+
+    # Derives an XRP address from a public key.
+    # @param public_key [String] The public key as hex.
+    # @return [String] The XRP address.
+    def derive_address(public_key)
+      public_key_bytes = [public_key].pack('H*')
+      # Account ID is RIPEMD160(SHA256(public_key))
+      sha256 = Digest::SHA256.digest(public_key_bytes)
+      # Ruby doesn't have RIPEMD160 in Digest by default sometimes, 
+      # but OpenSSL has it.
+      ripemd160 = OpenSSL::Digest.new('RIPEMD160').digest(sha256)
+      
+      @address_codec.encode_account_id(ripemd160.unpack('C*'))
+    end
+  end
+end