xrpl-ruby 0.6.1 → 0.8.0

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

@@ -3,6 +3,16 @@
 module BinaryCodec
 
   class Uint < ComparableSerializedType
+    # UInt64 fields that rippled renders in base 10 rather than as hex. They
+    # hold MPToken amounts, where a hex string would be a needless surprise.
+    BASE10_UINT64_FIELDS = %w[
+      MaximumAmount
+      OutstandingAmount
+      MPTAmount
+      LockedAmount
+      ConfidentialOutstandingAmount
+    ].freeze
+
     # Returns the width of the Uint type in bytes.
     # @return [Integer] The width.
     def self.width
@@ -20,22 +30,14 @@ module BinaryCodec
       return value if value.is_a?(self)
 
       if value.is_a?(String)
-        # Special handling for TransactionType and LedgerEntryType
-        if self == Uint16
-          transaction_types = Definitions.instance.instance_variable_get(:@transaction_types)
-          if transaction_types&.key?(value)
-            return new(int_to_bytes(transaction_types[value], width))
-          end
-          ledger_entry_types = Definitions.instance.instance_variable_get(:@ledger_entry_types)
-          if ledger_entry_types&.key?(value)
-            return new(int_to_bytes(ledger_entry_types[value], width))
-          end
-        elsif self == Uint8
-          transaction_results = Definitions.instance.instance_variable_get(:@transaction_results)
-          if transaction_results&.key?(value)
-            return new(int_to_bytes(transaction_results[value], width))
-          end
-        end
+        # Names for the fields that carry one: TransactionType and
+        # LedgerEntryType (UInt16), TransactionResult (UInt8) and the
+        # PermissionValue of a DelegateSet (UInt32). A name is never a valid
+        # number, so the lookup cannot capture a numeric string.
+        code = NAMED_VALUES.fetch(self, [])
+                           .filter_map { |table| Definitions.instance.public_send(table)[value] }
+                           .first
+        return new(int_to_bytes(code, width)) if code
 
         # Handle hex strings or numeric strings
         if valid_hex?(value) && value.length == self.width * 2
@@ -68,36 +70,28 @@ module BinaryCodec
     # Returns the JSON representation of the Uint.
     # @return [Integer, String] The value.
     def to_json(_definitions = nil, _field_name = nil)
-      # Special handling for TransactionType, LedgerEntryType, and TransactionResult
-      # ONLY when requested via a field name that matches.
-      if _field_name == 'TransactionType'
-        val = value_of
-        transaction_types = Definitions.instance.instance_variable_get(:@transaction_types)
-        if transaction_types
-          name = transaction_types.key(val)
-          return name if name
-        end
-      elsif _field_name == 'LedgerEntryType'
-        val = value_of
-        ledger_entry_types = Definitions.instance.instance_variable_get(:@ledger_entry_types)
-        if ledger_entry_types
-          name = ledger_entry_types.key(val)
-          return name if name
-        end
-      elsif _field_name == 'TransactionResult'
-        val = value_of
-        transaction_results = Definitions.instance.instance_variable_get(:@transaction_results)
-        if transaction_results
-          name = transaction_results.key(val)
-          return name if name
-        end
+      # The fields that carry a name render it, the way rippled does. A code
+      # without a name falls through and renders as the number.
+      table = NAMED_FIELDS[_field_name]
+      if table
+        name = Definitions.instance.public_send(table).key(value_of)
+        return name if name
       end
 
-      # For Uint8/16/32/64 and Int32/64 we return padded hex, to satisfy existing Ruby tests.
-      # We use unsigned value for hex representation of signed types.
-      u_val = value_of
-      u_val += (1 << (self.class.width * 8)) if u_val < 0
-      return u_val.to_s(16).upcase.rjust(self.class.width * 2, '0')
+      # rippled renders the narrow unsigned integers as JSON numbers and UInt64
+      # as a 16 digit hex string, because a UInt64 does not survive a round trip
+      # through a JSON number. The MPToken amount fields are the exception to
+      # that exception: they are UInt64 but carry a base 10 string.
+      #
+      # Everything wider than 8 bytes (Uint96 and up) is hash-like and stays
+      # hex. Do not widen the numeric branch to cover it.
+      val = value_of
+      return val if self.class.width < 8
+      return val.to_s if self.class.width == 8 && BASE10_UINT64_FIELDS.include?(_field_name)
+
+      # Hex is unsigned, so a negative signed value has to wrap first.
+      val += (1 << (self.class.width * 8)) if val < 0
+      val.to_s(16).upcase.rjust(self.class.width * 2, '0')
     end
     # @param other [Uint] The other Uint to compare to.
     # @return [Integer] Comparison result (-1, 0, or 1).
@@ -213,4 +207,21 @@ module BinaryCodec
     end
   end
 
+  class Uint
+    # Which name tables a width accepts on the way in ...
+    NAMED_VALUES = {
+      Uint16 => %i[transaction_types ledger_entry_types],
+      Uint8 => %i[transaction_results],
+      Uint32 => %i[delegatable_permissions]
+    }.freeze
+
+    # ... and which field renders its value by name on the way out.
+    NAMED_FIELDS = {
+      'TransactionType' => :transaction_types,
+      'LedgerEntryType' => :ledger_entry_types,
+      'TransactionResult' => :transaction_results,
+      'PermissionValue' => :delegatable_permissions
+    }.freeze
+  end
+
 end

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

@@ -15,9 +15,9 @@ module BinaryCodec
 
       if value.is_a?(::Hash)
         bytes = []
-        bytes.concat(AccountId.from(value['LockingChainDoor']).to_bytes)
+        bytes.concat(door_bytes(value['LockingChainDoor']))
         bytes.concat(Issue.from(value['LockingChainIssue']).to_bytes)
-        bytes.concat(AccountId.from(value['IssuingChainDoor']).to_bytes)
+        bytes.concat(door_bytes(value['IssuingChainDoor']))
         bytes.concat(Issue.from(value['IssuingChainIssue']).to_bytes)
         return XChainBridge.new(bytes)
       end
@@ -25,10 +25,23 @@ module BinaryCodec
       raise StandardError, "Cannot construct XChainBridge from #{value.class}"
     end
 
+    # An account inside a bridge carries the same length prefix as a
+    # standalone AccountID field. Leaving it off produces bytes that decode
+    # as something else entirely, which is why every XChain fixture failed
+    # to serialise.
+    DOOR_LENGTH_PREFIX = 0x14
+
+    def self.door_bytes(account)
+      [DOOR_LENGTH_PREFIX] + AccountId.from(account).to_bytes
+    end
+    private_class_method :door_bytes
+
     def self.from_parser(parser, _hint = nil)
       bytes = []
+      bytes.concat(parser.read(1)) # length prefix
       bytes.concat(parser.read(20)) # LockingChainDoor
       bytes.concat(Issue.from_parser(parser, 40).to_bytes) # LockingChainIssue
+      bytes.concat(parser.read(1)) # length prefix
       bytes.concat(parser.read(20)) # IssuingChainDoor
       bytes.concat(Issue.from_parser(parser, 40).to_bytes) # IssuingChainIssue
       XChainBridge.new(bytes)
@@ -37,8 +50,10 @@ module BinaryCodec
     def to_json(_definitions = nil, _field_name = nil)
       parser = BinaryParser.new(to_hex)
       result = {}
+      parser.read(1) # length prefix
       result['LockingChainDoor'] = AccountId.from_parser(parser).to_json
       result['LockingChainIssue'] = Issue.from_parser(parser, 40).to_json
+      parser.read(1) # length prefix
       result['IssuingChainDoor'] = AccountId.from_parser(parser).to_json
       result['IssuingChainIssue'] = Issue.from_parser(parser, 40).to_json
       result

data/lib/wallet/wallet.rb

@@ -162,6 +162,38 @@ module Wallet
       @key_pairs.verify(bytes_to_hex(signing_data), signature, @public_key)
     end
 
+    # Signs a payment channel claim: the promise that +amount+ drops of the
+    # channel's funds may be claimed. The signature goes into a
+    # PaymentChannelClaim transaction as its Signature.
+    #
+    # @param channel [String] the channel ID, 64 hex characters
+    # @param amount [String, Integer] the amount in drops
+    # @return [String] the signature as hex
+    def sign_payment_channel_claim(channel, amount)
+      data = BinaryCodec.signing_claim_data(channel: channel, amount: amount)
+      @key_pairs.sign(bytes_to_hex(data), @private_key, @algorithm)
+    end
+
+    # Verifies a payment channel claim against this wallet's public key.
+    #
+    # @param channel [String] the channel ID, 64 hex characters
+    # @param amount [String, Integer] the amount in drops
+    # @param signature [String] the signature as hex
+    # @return [Boolean] whether the claim was signed by this wallet
+    def verify_payment_channel_claim(channel, amount, signature)
+      self.class.verify_payment_channel_claim(channel, amount, signature, @public_key)
+    end
+
+    # Verifies a payment channel claim against any public key - the channel's
+    # PublicKey, as the receiving side has it.
+    #
+    # @param public_key [String] the public key as hex
+    # @return [Boolean] whether the claim was signed with that key
+    def self.verify_payment_channel_claim(channel, amount, signature, public_key)
+      data = BinaryCodec.signing_claim_data(channel: channel, amount: amount)
+      KeyPairs::KeyPairs.new.verify(bytes_to_hex(data), signature, public_key)
+    end
+
     # Derives the X-address for this wallet.
     # @param tag [Integer, false, nil] The destination tag.
     # @param test_network [Boolean] Whether the address is for a test network.

data/lib/xrpl/client.rb

@@ -35,17 +35,35 @@ module XRPL
 
     attr_reader :url, :connection
 
+    # Accepts a transaction as a plain Hash or as an XRPL::Transaction and
+    # hands back the Hash the rest of the pipeline works with. Anything else
+    # is passed through untouched, so a pre-signed blob still reaches submit.
+    #
+    # @param transaction [Hash, XRPL::Transaction, Object]
+    # @return [Hash, Object]
+    def self.to_transaction_hash(transaction)
+      return transaction if transaction.is_a?(Hash)
+      return transaction.to_h if transaction.is_a?(XRPL::Transaction)
+
+      transaction
+    end
+
     # @param url [String, Symbol] a network alias (:testnet/:mainnet/:devnet) or a WebSocket URL.
     # @param logger [Logger, nil] optional logger for diagnostic messages. When nil
     #   (the default), the client stays silent — a library must not write to the
     #   host application's stdout uninvited. Pass e.g. +Logger.new($stdout)+ to opt in.
-    def initialize(url, logger: nil)
+    # @param max_fee_drops [Integer] cap for the fee autofill computes, so a
+    #   spike in the open ledger fee cannot burn an account. Transactions that
+    #   cost an owner reserve (AccountDelete, AMMCreate, VaultCreate) are not
+    #   capped.
+    def initialize(url, logger: nil, max_fee_drops: Fee::MAX_FEE_DROPS)
       @url = resolve_url(url)
       @connection = nil
       @requests = {}
       @open = false
       @ready_queue = Queue.new
       @logger = logger
+      @max_fee_drops = max_fee_drops
     end
 
     # Opens the WebSocket connection.
@@ -306,13 +324,17 @@ module XRPL
     # Fills in the fields a transaction needs before signing: +Sequence+, +Fee+
     # and +LastLedgerSequence+. Existing values are never overwritten.
     #
-    # @param transaction [Hash] the (string-keyed) transaction to complete.
+    # The fee follows the transaction type (see XRPL::Fee): an EscrowFinish
+    # pays for its Fulfillment, AccountDelete, AMMCreate and VaultCreate cost
+    # the owner reserve, a Batch pays for its inner transactions.
+    #
+    # @param transaction [Hash, XRPL::Transaction] the transaction to complete.
     # @param signers_count [Integer] number of signatures for multisign fee scaling.
     # @return [Hash] a copy of the transaction with the missing fields filled in.
     def autofill(transaction, signers_count: 0)
-      tx = transaction.dup
+      tx = self.class.to_transaction_hash(transaction).dup
       tx['Sequence'] ||= fetch_sequence(tx.fetch('Account'))
-      tx['Fee'] ||= calculate_fee(signers_count)
+      tx['Fee'] ||= calculate_fee(tx, signers_count)
       tx['LastLedgerSequence'] ||= current_ledger_index + LEDGER_OFFSET
       tx
     end
@@ -399,7 +421,8 @@ module XRPL
     def prepare_for_submit(transaction, wallet:, autofill:)
       raise ArgumentError, 'wallet: is required to sign the transaction' if wallet.nil?
 
-      tx = transaction.is_a?(Hash) ? transaction.dup : transaction
+      tx = self.class.to_transaction_hash(transaction)
+      tx = tx.dup if tx.is_a?(Hash)
       tx = autofill(tx) if autofill && tx.is_a?(Hash)
 
       signed = wallet.sign(tx)
@@ -426,10 +449,14 @@ module XRPL
       Integer(sequence)
     end
 
-    def calculate_fee(signers_count)
-      base = base_fee_drops
-      total = signers_count.to_i.positive? ? base * (1 + signers_count.to_i) : base
-      total.to_s
+    def calculate_fee(tx, signers_count)
+      Fee.calculate(
+        tx,
+        base_fee: base_fee_drops,
+        signers_count: signers_count.to_i,
+        max_fee: @max_fee_drops,
+        owner_reserve: -> { owner_reserve_drops }
+      ).to_s
     end
 
     def base_fee_drops
@@ -441,6 +468,17 @@ module XRPL
       DEFAULT_FEE_DROPS
     end
 
+    # The owner reserve (reserve_inc), which AccountDelete, AMMCreate and
+    # VaultCreate cost instead of a fee. There is no sensible default: a
+    # guess would be rejected or overpay by orders of magnitude.
+    def owner_reserve_drops
+      response = request_with_retry('server_state')
+      reserve = response.dig('result', 'state', 'validated_ledger', 'reserve_inc')
+      raise TransactionError, 'Could not determine the owner reserve from server_state' unless reserve
+
+      Integer(reserve)
+    end
+
     def current_ledger_index
       response = request_with_retry('ledger_current')
       index = response.dig('result', 'ledger_current_index')

data/lib/xrpl/fee.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module XRPL
+  # The fee a transaction needs, in drops, by transaction type.
+  #
+  # rippled charges most transactions the network's base fee, but not all of
+  # them: an EscrowFinish pays for the size of its Fulfillment, AccountDelete,
+  # AMMCreate and VaultCreate cost an owner reserve rather than a fee, a Batch
+  # pays for its inner transactions, and the confidential MPT transactions
+  # cost ten base fees. Multisigning adds one base fee per signature. The
+  # rules are the ones xrpl.js applies in its autofill.
+  #
+  # This module is pure: it takes the base fee and, when a type needs it, a
+  # way to get the owner reserve. XRPL::Client wires it to the ledger.
+  module Fee
+    # Where an ordinary fee is capped, so that a spike in the open ledger fee
+    # cannot burn an account. The reserve-priced types are not capped: their
+    # cost is what it is.
+    MAX_FEE_DROPS = 2_000_000
+
+    # Types whose cost is the owner reserve (reserve_inc), not a fee.
+    RESERVE_PRICED = %w[AccountDelete AMMCreate VaultCreate].freeze
+
+    # rippled's kCONFIDENTIAL_FEE_MULTIPLIER: extra base fees on top of the
+    # standard one, so ten in total.
+    CONFIDENTIAL_MPT_MULTIPLIER = 9
+
+    CONFIDENTIAL_MPT_TYPES = %w[
+      ConfidentialMPTConvert ConfidentialMPTConvertBack ConfidentialMPTSend
+      ConfidentialMPTClawback ConfidentialMPTMergeInbox
+    ].freeze
+
+    module_function
+
+    # @param transaction [Hash, XRPL::Transaction] the transaction, with its
+    #   TransactionType
+    # @param base_fee [Integer] the network's base fee in drops
+    # @param signers_count [Integer] number of signatures for multisign scaling
+    # @param max_fee [Integer] cap for ordinary fees
+    # @param owner_reserve [Integer, #call, nil] the owner reserve in drops,
+    #   or something that fetches it; only consulted for the reserve-priced
+    #   types
+    # @return [Integer] the fee in drops, rounded up
+    def calculate(transaction, base_fee:, signers_count: 0, max_fee: MAX_FEE_DROPS, owner_reserve: nil)
+      tx = transaction.respond_to?(:to_h) ? transaction.to_h : transaction
+      type = tx['TransactionType'] || tx[:TransactionType]
+      base_fee = Integer(base_fee)
+
+      fee = Rational(base_fee)
+      reserve_priced = RESERVE_PRICED.include?(type)
+
+      if type == 'EscrowFinish' && tx['Fulfillment']
+        # Base fee × (33 + Fulfillment size in bytes / 16)
+        bytes = (tx['Fulfillment'].to_s.length + 1) / 2
+        fee = base_fee * (33 + Rational(bytes, 16))
+      elsif reserve_priced
+        fee = Rational(resolve_owner_reserve(owner_reserve, type))
+      elsif type == 'Batch'
+        inner = Array(tx['RawTransactions']).sum(0r) do |raw|
+          calculate(raw['RawTransaction'] || raw, base_fee: base_fee, max_fee: max_fee,
+                                                  owner_reserve: owner_reserve)
+        end
+        fee = base_fee * 2 + inner
+      elsif CONFIDENTIAL_MPT_TYPES.include?(type)
+        fee += base_fee * CONFIDENTIAL_MPT_MULTIPLIER
+      end
+
+      # Multisigned: base fee × (1 + number of signatures)
+      fee += base_fee * signers_count if signers_count.to_i.positive?
+
+      fee = [fee, Rational(max_fee)].min unless reserve_priced
+      fee.ceil
+    end
+
+    def resolve_owner_reserve(owner_reserve, type)
+      reserve = owner_reserve.respond_to?(:call) ? owner_reserve.call : owner_reserve
+      raise ArgumentError, "#{type} costs the owner reserve, which was not given" if reserve.nil?
+
+      Integer(reserve)
+    end
+  end
+end

data/lib/xrpl/ledger_entry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module XRPL
+  # A ledger entry - AccountRoot, RippleState, Offer, Escrow and the other
+  # objects that make up the ledger's state - built from LEDGER_ENTRY_FORMATS
+  # in definitions.json, the same way XRPL::Transaction is built from
+  # TRANSACTION_FORMATS.
+  #
+  #     entry = XRPL::LedgerEntry.from(response.dig('result', 'node'))
+  #     entry.class          # => XRPL::LedgerEntry::AccountRoot
+  #     entry.balance        # => "370000000"
+  #     entry.flag?(:lsf_default_ripple)
+  #     entry.flag_names     # => ["lsfDefaultRipple"]
+  #
+  # Where rippled hands out the entry's own hash under "index" (ledger_entry,
+  # account_objects, ledger_data), that value is kept as #index; it is not a
+  # field of the object and is left out of #to_h.
+  class LedgerEntry < Model
+    # Fields every ledger entry carries, regardless of type.
+    COMMON_FORMAT = DEFINITIONS['LEDGER_ENTRY_FORMATS'].fetch('common').freeze
+
+    # LEDGER_ENTRY_FLAGS keys DirectoryNode's flags under rippled's short
+    # name for the type.
+    FLAG_ALIASES = { 'DirectoryNode' => 'DirNode' }.freeze
+
+    # The entry's hash, as rippled reports it under "index".
+    attr_accessor :index
+
+    class << self
+      # The ledger's name for this entry type, e.g. "AccountRoot".
+      alias ledger_entry_type type_name
+
+      def type_field
+        'LedgerEntryType'
+      end
+
+      def label
+        'ledger entry'
+      end
+    end
+
+    def []=(name, value)
+      if name.to_s == 'index'
+        @index = value
+        return
+      end
+
+      super
+    end
+
+    define_types!(DEFINITIONS['LEDGER_ENTRY_FORMATS'], DEFINITIONS['LEDGER_ENTRY_FLAGS'], FLAG_ALIASES)
+  end
+end