improve comments

Author: kuan121

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/fees/FeeParams.java

@@ -107,8 +107,9 @@ static ImmutableFeeParams.Builder builder() {
   /**
    * The number of signatures the transaction's own account will supply in its {@code Signers} array.
    *
-   * <p>Zero for a single-signed transaction: rippled charges only for the <em>additional</em> signatures of a
-   * multi-signature, since the first is already covered by the base fee.
+   * <p>Zero for a single-signed transaction: rippled counts only {@code Signers} entries, and a lone signature is
+   * carried in {@code TxnSignature} instead. For a multi-signature this is the full size of the {@code Signers}
+   * array (e.g. 4 for a 4-of-N signer list), not one fewer — rippled charges {@code base × (1 + signersCount)}.
    *
    * @return An {@link UnsignedInteger} number of signatures, defaulting to zero.
    */
@@ -134,9 +135,10 @@ default UnsignedInteger sponsorSignersCount() {
   /**
    * The total number of signatures in a {@code LoanSet}'s {@code CounterpartySignature}.
    *
-   * <p>Unlike {@link #signersCount()} and {@link #sponsorSignersCount()}, this is a total rather than a count of
-   * additional signatures: rippled charges a base fee even for a single counterparty signature. One is therefore the
-   * correct value for a counterparty signing with a single key, and is the default.
+   * <p>Unlike {@link #signersCount()} and {@link #sponsorSignersCount()} — which are zero when the lone signature
+   * rides in {@code TxnSignature} — a single counterparty signature is itself charged: rippled counts
+   * {@code CounterpartySignature.TxnSignature} as one. One is therefore the correct value for a counterparty signing
+   * with a single key, and is the default.
    *
    * @return An {@link UnsignedInteger} number of signatures, defaulting to one.
    */

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/fees/FeeUtils.java

@@ -47,7 +47,6 @@
 import java.util.Arrays;
 import java.util.Map;
 import java.util.Objects;
-import java.util.Optional;
 import java.util.Set;
 
 /**
@@ -130,12 +129,17 @@ public static ComputedNetworkFees computeMultisigNetworkFees(
    * Calculate a suggested fee to be used for submitting a transaction to the XRPL. The calculated value depends on the
    * current size of the job queue as compared to its total capacity.
    *
+   * <p>This returns the base fee levels for a plain, single-signed transaction, and is correct on its own only for
+   * transaction types that cost exactly the base fee. For anything with a different fee shape — a multi-signed or
+   * sponsored transaction, or a type with its own rule ({@link Batch}, {@code EscrowFinish} with a fulfillment,
+   * confidential MPT, {@code LoanSet}, {@code LoanPay}, {@code AccountDelete}, {@code AMMCreate}) — use
+   * {@link #computeFee(FeeParams)}, which starts from these same levels and applies the type's rule.
+   *
    * @param feeResult {@link FeeResult} object obtained by querying the ledger (e.g., via an `XrplClient#fee()` call).
    *
    * @return {@link ComputedNetworkFees} with low, medium and high fee levels to choose from for the transaction.
    *
    * @see "https://xrpl.org/fee.html"
-   * @see "https://github.com/XRPL-Labs/XUMM-App/blob/master/src/services/LedgerService.ts#L244"
    */
   public static ComputedNetworkFees computeNetworkFees(final FeeResult feeResult) {
     Objects.requireNonNull(feeResult);
@@ -151,11 +155,6 @@ public static ComputedNetworkFees computeNetworkFees(final FeeResult feeResult)
       .build();
   }
 
-
-
-
-
-
   /**
    * Computes the fee for any transaction, applying whichever of rippled's fee rules its type calls for.
    *

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/transactions/Batch.java

@@ -352,8 +352,7 @@ default Batch checkBatchSigners() {
 
     // Check 4: When BatchSigners is non-empty, every account required to sign an inner transaction must have a
     // corresponding BatchSigner entry. The required-signer set (initiator, sponsor, and LoanSet counterparty, with
-    // the outer account excluded) is derived by requiredSigners(), which is the single source of truth shared with
-    // fee computation.
+    // the outer account excluded) is derived by requiredSigners(), which is the single source of truth.
     if (!this.batchSigners().isEmpty()) {
       final Set<Address> actualSignerAccounts = this.batchSigners().stream()
         .map(wrapper -> wrapper.batchSigner().account())