xrpl-ruby 0.2.4 → 0.6.0

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, 40).to_bytes) # LockingChainIssue
+      bytes.concat(parser.read(20)) # IssuingChainDoor
+      bytes.concat(Issue.from_parser(parser, 40).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, 40).to_json
+      result['IssuingChainDoor'] = AccountId.from_parser(parser).to_json
+      result['IssuingChainIssue'] = Issue.from_parser(parser, 40).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,69 @@
+# 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 0xED followed by the 32-byte hash.
+      private_key = [0xED].pack('C') + hash
+
+      {
+        public_key: public_key.unpack1('H*').upcase,
+        private_key: private_key.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*')
+      # In XRPL, Ed25519 private keys are often prefixed with 0xED (33 bytes).
+      # The ed25519 gem expects 32 bytes.
+      key_bytes = key_bytes[1..-1] if key_bytes.length == 33 && key_bytes[0].ord == 0xED
+      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

data/lib/key-pairs/secp256k1.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'ecdsa'
+require 'digest'
+
+module KeyPairs
+  # Secp256k1 implementation for XRPL key pairs.
+  module Secp256k1
+    GROUP = ECDSA::Group::Secp256k1
+
+    # 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 Secp256k1 uses a specific derivation algorithm (seed -> family seed -> sequence 0 key).
+      # Seed is passed as a 16-byte array.
+      private_key = derive_private_key(seed)
+      public_key = derive_public_key(private_key)
+      
+      {
+        public_key: public_key.unpack1('H*').upcase,
+        private_key: private_key.upcase.rjust(66, '00')
+      }
+    end
+
+    # Signs a message with a private key.
+    # @param message [Array<Integer>, String] The message to sign (hex string or byte array).
+    # @param private_key [String] The private key (hex string).
+    # @return [String] The signature (hex string).
+    def self.sign(message, private_key)
+      msg_hash = message.is_a?(String) ? [message].pack('H*') : message.pack('C*')
+      
+      # If message is not already 32 bytes, we hash it.
+      # This is a bit of a heuristic. XRPL signs the SHA512Half hash of the serialized transaction.
+      if msg_hash.length != 32
+        msg_hash = Digest::SHA512.digest(msg_hash)[0...32]
+      end
+
+      priv_key_bn = private_key.to_i(16)
+      k = generate_k(priv_key_bn, msg_hash)
+      signature = ECDSA.sign(GROUP, priv_key_bn, msg_hash, k)
+      
+      # XRPL requires "canonical" signatures: S <= order / 2
+      if signature.s > (GROUP.order / 2)
+        signature = ECDSA::Signature.new(signature.r, GROUP.order - signature.s)
+      end
+      
+      ECDSA::Format::SignatureDerString.encode(signature).unpack1('H*').upcase
+    end
+
+    # Deterministic k generation (RFC 6979)
+    def self.generate_k(private_key_bn, message_hash)
+      q = GROUP.order
+      q_len = q.bit_length
+      holeren = (q_len + 7) / 8
+      
+      # Step b
+      v = "\x01" * holeren
+      # Step c
+      k = "\x00" * holeren
+      
+      # bits2octets(x)
+      x_bytes = [private_key_bn.to_s(16).rjust(holeren * 2, '0')].pack('H*')
+      # bits2octets(bits2int(h1))
+      h1_val = message_hash.unpack1('H*').to_i(16)
+      if h1_val >= q
+        h1_val %= q
+      end
+      h1 = [h1_val.to_s(16).rjust(holeren * 2, '0')].pack('H*')
+
+      # Step d
+      k = OpenSSL::HMAC.digest('sha256', k, v + "\x00" + x_bytes + h1)
+      # Step e
+      v = OpenSSL::HMAC.digest('sha256', k, v)
+      # Step f
+      k = OpenSSL::HMAC.digest('sha256', k, v + "\x01" + x_bytes + h1)
+      # Step g
+      v = OpenSSL::HMAC.digest('sha256', k, v)
+      
+      # Step h
+      loop do
+        t = ""
+        while t.length < holeren
+          v = OpenSSL::HMAC.digest('sha256', k, v)
+          t += v
+        end
+        
+        k_val = t[0...holeren].unpack1('H*').to_i(16)
+        # bits2int(T)
+        if q_len < 8 * holeren
+          k_val >>= (8 * holeren - q_len)
+        end
+
+        return k_val if k_val > 0 && k_val < q
+        
+        k = OpenSSL::HMAC.digest('sha256', k, v + "\x00")
+        v = OpenSSL::HMAC.digest('sha256', k, v)
+      end
+    end
+
+    # Verifies a signature.
+    # @param message [Array<Integer>, String] The message (hex string or byte array).
+    # @param signature [String] The signature (hex string).
+    # @param public_key [String] The public key (hex string).
+    # @return [Boolean] True if the signature is valid.
+    def self.verify(message, signature, public_key)
+      msg_hash = message.is_a?(String) ? [message].pack('H*') : message.pack('C*')
+      
+      # If message is not already 32 bytes, we hash it.
+      if msg_hash.length != 32
+        msg_hash = Digest::SHA512.digest(msg_hash)[0...32]
+      end
+
+      sig_bytes = [signature].pack('H*')
+      
+      point = ECDSA::Format::PointOctetString.decode([public_key].pack('H*'), GROUP)
+      sig = ECDSA::Format::SignatureDerString.decode(sig_bytes)
+      
+      ECDSA.valid_signature?(point, msg_hash, sig)
+    end
+
+    private
+
+    # Derives the 32-byte private key from the 16-byte seed.
+    # This follows the Ripple seed derivation algorithm.
+    def self.derive_private_key(seed, account_index = 0)
+      # 1. Derive root private key from seed
+      root_private_key = derive_scalar(seed)
+      
+      # 2. Derive root public key from root private key
+      root_public_key = derive_root_public_key(root_private_key)
+      
+      # 3. Derive child scalar from root public key and account_index
+      child_scalar = derive_scalar(root_public_key, account_index)
+      
+      # 4. child_private_key = (root_private_key + child_scalar) % order
+      child_private_key = (root_private_key.to_i(16) + child_scalar.to_i(16)) % GROUP.order
+      child_private_key.to_s(16).rjust(64, '0')
+    end
+
+    def self.derive_scalar(seed, sequence = nil)
+      seed_bytes = seed.is_a?(Array) ? seed.pack('C*') : seed
+      loop_count = 0
+      loop do
+        data = sequence ? seed_bytes + [sequence].pack('N') : seed_bytes
+        data += [loop_count].pack('N')
+        hash = Digest::SHA512.digest(data)[0...32]
+        scalar = hash.unpack1('H*').to_i(16)
+        
+        if scalar > 0 && scalar < GROUP.order
+          return scalar.to_s(16).rjust(64, '0')
+        end
+        loop_count += 1
+        raise "Too many loops" if loop_count > 100
+      end
+    end
+
+    def self.derive_root_public_key(private_key_hex)
+      key_bn = private_key_hex.to_i(16)
+      pub_key_point = GROUP.generator.multiply_by_scalar(key_bn)
+      ECDSA::Format::PointOctetString.encode(pub_key_point, compression: true)
+    end
+
+    def self.derive_public_key(private_key_hex)
+      derive_root_public_key(private_key_hex)
+    end
+  end
+end