xrpl-ruby 0.7.0 → 0.9.0

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

@@ -10,6 +10,7 @@ module BinaryCodec
       OutstandingAmount
       MPTAmount
       LockedAmount
+      ConfidentialOutstandingAmount
     ].freeze
 
     # Returns the width of the Uint type in bytes.
@@ -23,43 +24,79 @@ module BinaryCodec
     end
 
     # Creates a new Uint instance from a value.
+    #
+    # A String is read the way rippled 3.4.1 reads it (STParsedJSON):
+    # UInt8, UInt16 and UInt32 as a whole decimal number; UInt64 as hex of
+    # any length, except in the base-10 fields (BASE10_UINT64_FIELDS),
+    # which are decimal. The fields that carry a name also take the name.
+    # ripple-binary-codec reads them the same way. Anything else, and any
+    # value outside the type's range, raises ArgumentError. Names count only
+    # for their own field (NAMED_FIELDS) when the field is given.
+    #
     # @param value [Uint, String, Integer] The value to convert.
+    # @param field_name [String, nil] the field, which decides how a UInt64
+    #   String is read; without it, as hex
     # @return [Uint] The created instance.
-    def self.from(value)
+    def self.from(value, field_name = nil)
       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.
+        # With the field known, only that field's names count, so a
+        # Sequence cannot take "TrustSet" or a TransferFee "Payment".
+        tables = field_name ? Array(NAMED_FIELDS[field_name]) : NAMED_VALUES.fetch(self, [])
+        code = tables.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
-          return new(hex_to_bytes(value))
-        end
-        return new(int_to_bytes(value.to_i, width))
+        return new(int_to_bytes(in_range!(parse_string(value, field_name)), width))
       end
 
-      if value.is_a?(Integer)
-        return new(int_to_bytes(value, width))
-      end
+      return new(int_to_bytes(in_range!(value), width)) if value.is_a?(Integer)
 
       raise StandardError, "Cannot construct #{self} from the value given"
     end
 
+    # How a String becomes a number for this width. UInt8/16/32: decimal.
+    # UInt64: hex, or decimal in a base-10 field. The wider types keep the
+    # codec's earlier reading: hex in their full width, otherwise decimal.
+    def self.parse_string(value, field_name)
+      if width == 8
+        if BASE10_UINT64_FIELDS.include?(field_name)
+          return Integer(value, 10) if value.match?(/\A\d+\z/)
+
+          raise ArgumentError, "#{field_name} is base 10 and needs a whole decimal number, got #{value.inspect}"
+        end
+        return Integer(value, 16) if value.match?(/\A\h{1,16}\z/)
+
+        raise ArgumentError, "#{name} needs up to 16 hex digits, got #{value.inspect}"
+      elsif width > 8 && valid_hex?(value) && value.length == width * 2
+        Integer(value, 16)
+      elsif value.match?(/\A\d+\z/) || (width == 4 && value.match?(/\A\+\d+\z/))
+        # A leading '+' only for UInt32: rippled reads it with
+        # beast::lexicalCast, which skips it. Its UInt8 and UInt16 parsers
+        # take a String that does not start with a digit as a name and
+        # refuse "+5"; UInt64 above uses std::from_chars and takes no sign;
+        # the wider types are hex in rippled.
+        Integer(value, 10)
+      else
+        raise ArgumentError, "#{name} needs a whole decimal number, got #{value.inspect}"
+      end
+    end
+    private_class_method :parse_string
+
+    # A value that does not fit the width used to come out a byte too long
+    # (2**32 as a UInt32) or, if negative, as 0.
+    def self.in_range!(number)
+      max = (1 << (width * 8)) - 1
+      return number if number.between?(0, max)
+
+      raise ArgumentError, "#{name} takes 0 to #{max}, got #{number}"
+    end
+    private_class_method :in_range!
+
     # Creates a Uint instance from a parser.
     # @param parser [BinaryParser] The parser to read from.
     # @param _hint [Integer, nil] Unused hint.
@@ -77,29 +114,12 @@ 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
 
       # rippled renders the narrow unsigned integers as JSON numbers and UInt64
@@ -191,8 +211,15 @@ module BinaryCodec
     # 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)
+    def self.from(value, _field_name = nil)
       return value if value.is_a?(self)
+      # rippled reads an Int32 String as a signed decimal number, and
+      # nothing else: not as the hex a UInt64 would take.
+      if value.is_a?(String)
+        raise ArgumentError, "#{name} needs a signed decimal number, got #{value.inspect}" unless value.match?(/\A[+-]?\d+\z/)
+
+        value = Integer(value, 10)
+      end
       if value.is_a?(Integer)
         # Ensure it fits in 32-bit signed
         if value < -2147483648 || value > 2147483647
@@ -215,11 +242,26 @@ module BinaryCodec
       val > 0x7FFFFFFFFFFFFFFF ? val - 0x10000000000000000 : val
     end
 
+    # The signed value as a decimal String: not the 16 hex digits of a
+    # UInt64, so the decoder's output goes back in through .from; and a
+    # String, as rippled renders 64-bit values, so a JSON reader that holds
+    # numbers as doubles (JavaScript) cannot round it.
+    def to_json(_definitions = nil, _field_name = nil)
+      value_of.to_s
+    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)
+    def self.from(value, _field_name = nil)
       return value if value.is_a?(self)
+      # rippled reads an Int64 String as a signed decimal number, and
+      # nothing else: not as the hex a UInt64 would take.
+      if value.is_a?(String)
+        raise ArgumentError, "#{name} needs a signed decimal number, got #{value.inspect}" unless value.match?(/\A[+-]?\d+\z/)
+
+        value = Integer(value, 10)
+      end
       if value.is_a?(Integer)
         if value < -9223372036854775808 || value > 9223372036854775807
           raise StandardError, "Value #{value} out of range for Int64"
@@ -231,4 +273,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/wallet/wallet.rb

@@ -124,14 +124,10 @@ module Wallet
         # 4. Serialize the signed transaction
         tx_blob = BinaryCodec.json_to_binary(signed_tx)
         
-        # 5. Generate the hash (transaction ID)
-        # For transactions, the hash is SHA512Half of the serialized transaction with a prefix
-        hash_prefix = [0x54, 0x58, 0x4E, 0x00].pack('C*') # 'TXN\0'
-        hash = Digest::SHA512.digest(hash_prefix + [tx_blob].pack('H*'))[0...32].unpack1('H*').upcase
-        
+        # 5. The transaction ID: SHA512Half of 'TXN\0' and the blob
         return {
           'tx_blob' => tx_blob,
-          'hash' => hash
+          'hash' => BinaryCodec.transaction_id(tx_blob)
         }
       end
 
@@ -162,6 +158,184 @@ 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
+
+    # Signs a Batch (XLS-56) for an account with inner transactions in it:
+    # the BatchSigners entry that account contributes. The outer account does
+    # not need one; it signs the whole Batch with #sign once the entries are
+    # in (see .combine_batch_signers).
+    #
+    # The Batch must be complete: Account, Sequence, Flags and the inner
+    # transactions as XRPL::Client#autofill leaves them, because the
+    # signature covers the inner transaction IDs.
+    #
+    # @param batch [Hash, XRPL::Transaction] the Batch
+    # @param batch_account [String, nil] the account to sign for; by default
+    #   this wallet's. Another account when this wallet is its regular key,
+    #   or the account whose signer list this wallet belongs to.
+    # @param multisign [Boolean, String] true to sign as one signer of
+    #   batch_account's signer list, as this wallet's own account; or the
+    #   signer account, when this wallet is that signer's regular key
+    # @return [Hash] a copy of the Batch whose BatchSigners holds this one entry
+    # @raise [ArgumentError] for anything but a Batch, or an account with no
+    #   inner transaction in it
+    def sign_batch(batch, batch_account: nil, multisign: false)
+      batch = self.class.batch_hash(batch)
+      # rippled requires a Sequence, and the signature covers its value (or
+      # the TicketSequence). Signed without one, the entry matches no Batch
+      # that can be submitted: autofill first, then sign.
+      unless BinaryCodec.batch_sequence_value(batch).positive?
+        raise ArgumentError, 'A Batch needs its Sequence or TicketSequence before it is signed; autofill it first'
+      end
+
+      batch_account ||= @classic_address
+      unless self.class.batch_signer_accounts(batch).include?(batch_account)
+        raise ArgumentError, "#{batch_account} has no inner transaction to sign for in this Batch"
+      end
+
+      entry = { 'Account' => batch_account }
+      if multisign
+        signer_account = multisign.is_a?(String) ? multisign : @classic_address
+        data = BinaryCodec.signing_batch_data(batch, batch_account: batch_account, signer_account: signer_account)
+        entry['Signers'] = [{ 'Signer' => {
+          'Account' => signer_account,
+          'SigningPubKey' => @public_key,
+          'TxnSignature' => @key_pairs.sign(bytes_to_hex(data), @private_key, @algorithm)
+        } }]
+      else
+        data = BinaryCodec.signing_batch_data(batch, batch_account: batch_account)
+        entry['SigningPubKey'] = @public_key
+        entry['TxnSignature'] = @key_pairs.sign(bytes_to_hex(data), @private_key, @algorithm)
+      end
+
+      batch.merge('BatchSigners' => [{ 'BatchSigner' => entry }])
+    end
+
+    # The accounts that sign a Batch's BatchSigners: the Account of every
+    # inner transaction, or its Delegate when it has one, since the delegate
+    # acts for the account. Each account once, in order of appearance. The
+    # outer account is included; its entry is dropped when combining.
+    #
+    # @param batch [Hash, XRPL::Transaction] the Batch
+    # @return [Array<String>]
+    def self.batch_signer_accounts(batch)
+      batch_hash(batch)['RawTransactions'].map do |wrapper|
+        inner = wrapper['RawTransaction'] || {}
+        inner['Delegate'] || inner['Account']
+      end.compact.uniq
+    end
+
+    # Merges the copies of a Batch that each signer returned from
+    # #sign_batch into one Batch carrying all BatchSigners entries, ready for
+    # the outer account to sign with #sign.
+    #
+    # Entries are sorted by numeric AccountID, as rippled requires. The outer
+    # account's entry is dropped: its signature is the outer one. Signatures
+    # of the same account's signer list are merged into one entry with its
+    # Signers sorted the same way; an identical entry given twice is kept once.
+    #
+    # @param batches [Array<Hash, String>] the signed copies, as Hashes or
+    #   serialised hex
+    # @return [Hash] the Batch with the combined BatchSigners
+    # @raise [ArgumentError] when the copies are not of the same Batch, one
+    #   carries no BatchSigners, or the outer transaction is already signed
+    def self.combine_batch_signers(batches)
+      batches = Array(batches).map { |b| b.is_a?(String) ? BinaryCodec.binary_to_json(b) : batch_hash(b) }
+      raise ArgumentError, 'combine_batch_signers needs at least one signed Batch' if batches.empty?
+
+      batches.each do |b|
+        raise ArgumentError, 'The Batch must not be signed yet; the outer account signs last' if b['TxnSignature'] || b['Signers']
+        raise ArgumentError, 'Every Batch to combine needs BatchSigners' if Array(b['BatchSigners']).empty?
+      end
+      unsigned = batches.map { |b| b.reject { |key, _| key == 'BatchSigners' } }
+      unless unsigned.uniq.size == 1
+        raise ArgumentError, 'The Batches to combine have to be the same apart from BatchSigners'
+      end
+
+      outer = batches.first['Account']
+      by_account = {}
+      batches.flat_map { |b| b['BatchSigners'] }.each do |wrapper|
+        entry = wrapper['BatchSigner']
+        account = entry['Account']
+        next if account == outer
+
+        by_account[account] = merge_batch_signer(by_account[account], entry)
+      end
+
+      entries = by_account.values.sort_by { |entry| account_sort_key(entry['Account']) }
+      unsigned.first.merge('BatchSigners' => entries.map { |entry| { 'BatchSigner' => entry } })
+    end
+
+    # The Batch as a Hash, its inner transactions included: a model, or a
+    # Hash whose RawTransaction entries are models, comes back as plain
+    # Hashes, so the copy that sign_batch returns can be serialised.
+    #
+    # @api private
+    def self.batch_hash(batch)
+      batch = batch.to_h if !batch.is_a?(::Hash) && batch.respond_to?(:to_h)
+      unless batch.is_a?(::Hash) && batch['TransactionType'] == 'Batch'
+        raise ArgumentError, 'sign_batch needs a Batch transaction'
+      end
+      return batch unless batch['RawTransactions'].is_a?(Array)
+
+      raw = batch['RawTransactions'].map do |wrapper|
+        inner = wrapper.is_a?(::Hash) ? wrapper['RawTransaction'] : nil
+        inner.is_a?(XRPL::Transaction) ? wrapper.merge('RawTransaction' => inner.to_h) : wrapper
+      end
+      batch.merge('RawTransactions' => raw)
+    end
+
+    # Two entries for the same account: identical ones collapse, signer-list
+    # entries merge their Signers, anything else is a conflict.
+    def self.merge_batch_signer(existing, entry)
+      return entry if existing.nil? || existing == entry
+
+      unless existing['Signers'] && entry['Signers']
+        raise ArgumentError, "Conflicting BatchSigners entries for #{entry['Account']}"
+      end
+
+      signers = (existing['Signers'] + entry['Signers'])
+                .uniq { |s| s['Signer']['Account'] }
+                .sort_by { |s| account_sort_key(s['Signer']['Account']) }
+      existing.merge('Signers' => signers)
+    end
+
+    def self.account_sort_key(address)
+      AddressCodec::AddressCodec.new.decode_account_id(address).to_a
+    end
+
+    private_class_method :merge_batch_signer, :account_sort_key
+
     # 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/batch.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module XRPL
+  # Prepares the inner transactions of a Batch (XLS-56) before it is signed.
+  #
+  # The ledger requires every inner transaction to carry the tfInnerBatchTxn
+  # flag, a Fee of "0" and an empty SigningPubKey: the outer transaction pays
+  # the fees, and the outer signature together with BatchSigners authorises
+  # the inner transactions. They must also carry their final Sequence, because
+  # the BatchSigners sign over the inner transaction IDs. So the Batch has to
+  # be complete before anyone signs it.
+  #
+  # The module is pure: XRPL::Client#autofill passes in a way to fetch an
+  # account's sequence. What the ledger would refuse is refused here, before
+  # anything is signed or sent.
+  module Batch
+    FLAGS = Model::DEFINITIONS['TRANSACTION_FLAGS']
+
+    # The four modes; a Batch names exactly one of them.
+    MODE_FLAGS = FLAGS.fetch('Batch').values.reduce(0, :|)
+
+    # Marks a transaction as the inner transaction of a Batch.
+    TF_INNER_BATCH_TXN = FLAGS.fetch('universal').fetch('tfInnerBatchTxn')
+
+    MIN_INNER = 2
+    MAX_INNER = 8
+
+    module_function
+
+    # @param batch [Hash] the Batch, with its outer Sequence (or
+    #   TicketSequence) already set; it is not modified
+    # @param sequence_for [#call] takes an account and returns its next
+    #   sequence; only called for accounts whose inner transactions lack a
+    #   Sequence and a TicketSequence, once per account
+    # @return [Hash] a copy of the Batch with its inner transactions filled in
+    # @raise [ArgumentError] when the ledger would refuse the Batch
+    def prepare(batch, sequence_for:)
+      check_mode!(batch['Flags'])
+      check_sequence_and_ticket!(batch, 'The Batch')
+      raw = batch['RawTransactions']
+      unless raw.is_a?(Array) && raw.size.between?(MIN_INNER, MAX_INNER)
+        count = raw.is_a?(Array) ? raw.size : 0
+        raise ArgumentError, "A Batch carries #{MIN_INNER} to #{MAX_INNER} inner transactions, this one has #{count}"
+      end
+
+      # Per account: the next sequence to hand out, and the lowest one still
+      # free after the explicit sequences seen so far. An inner transaction
+      # without a sequence gets the higher of the two, so it never repeats
+      # one given explicitly earlier in the Batch.
+      next_sequence = {}
+      floor = Hash.new(0)
+      take = lambda do |account|
+        [next_sequence[account] || first_sequence(batch, account, sequence_for), floor[account]].max
+      end
+
+      # Everything is checked before the first sequence is handed out, so a
+      # Batch the ledger would refuse never reaches sequence_for.
+      inners = raw.each_with_index.map do |wrapper, index|
+        unwrap(wrapper, index).tap { |inner| check_inner!(inner, index) }
+      end
+
+      prepared = inners.map do |inner|
+        inner['Flags'] = Integer(inner['Flags'] || 0) | TF_INNER_BATCH_TXN
+        inner['Fee'] = '0'
+        inner['SigningPubKey'] = ''
+
+        account = inner['Account']
+        # A TicketCreate also takes a sequence for every ticket it creates.
+        reserved = inner['TransactionType'] == 'TicketCreate' ? Integer(inner['TicketCount'] || 0) : 0
+
+        if !inner['TicketSequence'].nil? && BinaryCodec.uint32_value(inner['Sequence']).zero?
+          # On a ticket: Sequence is a required field and 0 here. Only a
+          # TicketCreate still moves the account's sequence on, by the
+          # tickets it creates, starting at the current one.
+          inner['Sequence'] = 0
+          next_sequence[account] = take.call(account) + reserved if reserved.positive?
+        elsif inner['Sequence'].nil?
+          sequence = take.call(account)
+          inner['Sequence'] = sequence
+          next_sequence[account] = sequence + 1 + reserved
+        else
+          floor[account] = [floor[account], BinaryCodec.uint32_value(inner['Sequence']) + 1 + reserved].max
+        end
+
+        { 'RawTransaction' => inner }
+      end
+
+      batch.merge('RawTransactions' => prepared)
+    end
+
+    # The number of signatures a BatchSigners array carries: one per entry,
+    # or, for an entry signed by a signer list, one per nested signer.
+    #
+    # @param batch_signers [Array<Hash>, nil]
+    # @return [Integer]
+    def signature_count(batch_signers)
+      Array(batch_signers).sum do |entry|
+        signer = entry.is_a?(Hash) ? (entry['BatchSigner'] || entry) : {}
+        nested = signer['Signers']
+        nested.is_a?(Array) && !nested.empty? ? nested.size : 1
+      end
+    end
+
+    def check_mode!(flags)
+      mode = Integer(flags || 0) & MODE_FLAGS
+      return if mode.positive? && (mode & (mode - 1)).zero?
+
+      raise ArgumentError, 'A Batch needs exactly one of tfAllOrNothing, tfOnlyOne, ' \
+                           'tfUntilFailure and tfIndependent in Flags'
+    end
+
+    def unwrap(wrapper, index)
+      inner = wrapper.is_a?(Hash) && wrapper.keys == ['RawTransaction'] ? wrapper['RawTransaction'] : nil
+      inner = inner.to_h if inner.is_a?(XRPL::Transaction)
+      unless inner.is_a?(Hash)
+        raise ArgumentError, "RawTransactions[#{index}] must be { 'RawTransaction' => transaction }"
+      end
+
+      inner.dup
+    end
+
+    # On a ticket, Sequence is 0; rippled refuses a nonzero Sequence next to
+    # a TicketSequence (temSEQ_AND_TICKET). Refused before any sequence is
+    # handed out, so it cannot push the account's later sequences up.
+    def check_sequence_and_ticket!(transaction, label)
+      # Reading both values here refuses a malformed or out-of-range one in
+      # the checking pass, not after sequences were already fetched.
+      sequence = BinaryCodec.uint32_value(transaction['Sequence'])
+      BinaryCodec.uint32_value(transaction['TicketSequence'])
+      return if transaction['TicketSequence'].nil? || sequence.zero?
+
+      raise ArgumentError, "#{label} has both a Sequence and a TicketSequence; " \
+                           'on a ticket, Sequence is 0 (temSEQ_AND_TICKET)'
+    end
+
+    def check_inner!(inner, index)
+      prefix = "RawTransactions[#{index}]"
+      raise ArgumentError, "#{prefix} has no Account" if inner['Account'].nil?
+
+      check_sequence_and_ticket!(inner, prefix)
+      raise ArgumentError, "#{prefix} is a Batch; a Batch cannot nest" if inner['TransactionType'] == 'Batch'
+      if inner.key?('TxnSignature') || inner.key?('Signers')
+        raise ArgumentError, "#{prefix} must not be signed; the Batch is signed as a whole"
+      end
+      if inner.key?('Fee') && inner['Fee'].to_s != '0'
+        raise ArgumentError, "#{prefix} must have Fee \"0\"; the Batch pays the fees"
+      end
+      return unless inner.key?('SigningPubKey') && inner['SigningPubKey'].to_s != ''
+
+      raise ArgumentError, "#{prefix} must have an empty SigningPubKey"
+    end
+
+    # The outer account's inner transactions follow the outer one, which
+    # consumes its Sequence; when it uses a ticket instead, the account's
+    # sequence is still free. Every other account starts at its own.
+    def first_sequence(batch, account, sequence_for)
+      outer_sequence = BinaryCodec.uint32_value(batch['Sequence'])
+      if account == batch['Account'] && outer_sequence.positive? && batch['TicketSequence'].nil?
+        outer_sequence + 1
+      else
+        Integer(sequence_for.call(account))
+      end
+    end
+
+    private_class_method :check_mode!, :check_sequence_and_ticket!, :unwrap, :check_inner!, :first_sequence
+  end
+end

data/lib/xrpl/client.rb

@@ -52,13 +52,18 @@ module XRPL
     # @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.
@@ -319,13 +324,33 @@ module XRPL
     # Fills in the fields a transaction needs before signing: +Sequence+, +Fee+
     # and +LastLedgerSequence+. Existing values are never overwritten.
     #
+    # 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 signatures and its inner
+    # transactions.
+    #
+    # A Batch also gets its inner transactions prepared (see XRPL::Batch):
+    # tfInnerBatchTxn, Fee "0", an empty SigningPubKey and their sequences.
+    # The BatchSigners sign over the finished Batch, so its fee has to be set
+    # before they exist; +batch_signatures:+ says how many there will be.
+    #
     # @param transaction [Hash, XRPL::Transaction] the transaction to complete.
     # @param signers_count [Integer] number of signatures for multisign fee scaling.
+    # @param batch_signatures [Integer] for a Batch: the signatures its
+    #   BatchSigners will carry, one per other account (or one per signer of
+    #   an account signing with a signer list). Zero for a Batch of one account.
     # @return [Hash] a copy of the transaction with the missing fields filled in.
-    def autofill(transaction, signers_count: 0)
+    # @raise [ArgumentError] for a Batch the ledger would refuse.
+    def autofill(transaction, signers_count: 0, batch_signatures: 0)
       tx = self.class.to_transaction_hash(transaction).dup
+      # On a ticket, Sequence is 0; the account's own would be refused
+      # (temSEQ_AND_TICKET).
+      tx['Sequence'] = 0 if tx['Sequence'].nil? && !tx['TicketSequence'].nil?
       tx['Sequence'] ||= fetch_sequence(tx.fetch('Account'))
-      tx['Fee'] ||= calculate_fee(signers_count)
+      if tx['TransactionType'] == 'Batch'
+        tx = Batch.prepare(tx, sequence_for: ->(account) { fetch_sequence(account) })
+      end
+      tx['Fee'] ||= calculate_fee(tx, signers_count, batch_signatures)
       tx['LastLedgerSequence'] ||= current_ledger_index + LEDGER_OFFSET
       tx
     end
@@ -440,10 +465,15 @@ 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, batch_signatures = 0)
+      Fee.calculate(
+        tx,
+        base_fee: base_fee_drops,
+        signers_count: signers_count.to_i,
+        batch_signatures: batch_signatures.to_i,
+        max_fee: @max_fee_drops,
+        owner_reserve: -> { owner_reserve_drops }
+      ).to_s
     end
 
     def base_fee_drops
@@ -455,6 +485,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')