HIP-991: Introduce generic custom fee limits

HIP/hip-991.md

@@ -11,7 +11,7 @@ status: Accepted
 last-call-date-time: 2024-07-24T07:00:00Z
 created: 2024-06-14
 discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/pull/991
-updated: 2024-12-05
+updated: 2025-01-08
 ---
 
 ## Abstract
@@ -79,7 +79,7 @@ We propose adding a fixed fee mechanism to the Hedera Consensus Service (HCS) fo
 
 * Fees are defined as a list of custom fee.
 * The list of custom fees can contain a maximum of `MAX_CUSTOM_FEE_ENTRIES_FOR_TOPICS` entries.
-* A custom fee is defined leveraging the HTS's FixedFee data structure (see [ConsensusCustomFee](#consensuscustomfee)).
+* A custom fee is defined leveraging the HTS's FixedFee data structure (see [FixedCustomFee](#fixedcustomfee)).
 * A custom fee can be set in HBAR or HTS fungible tokens and must have an accountID as the receiver.
 
 #### Fee Management
@@ -88,13 +88,13 @@ We propose adding a fixed fee mechanism to the Hedera Consensus Service (HCS) fo
 * Fees can be changed (updated or removed) in a topic with an update topic transaction signed by the Fee Schedule Key.
 * Topics can have a Fee Schedule Key set at creation time.
 * The Fee Schedule Key can manage fee updates for the topic.
-* The Fee Schedule Key can be updated according to the same rules that currently apply to the Submit key. In addition, to update the Fee Schedule Key, the new key must sign the transaction.
+* The Fee Schedule Key can be updated according to the same rules that currently apply to the Submit key.
 * If the topic was created without a Fee Schedule Key, the key cannot be added later.
 
 #### Fee Payment
 
-* A `ConsensusSubmitMessageTransactionBody` will include a new optional field `max_custom_fee` that a user can set to limit the paid custom fees.
-* The account submitting a message to the topic will cover network transaction fees, and if necessary, a custom fee. The topic initiates the transfer of the custom fee to the fee collector using a synthetic `CryptoTransfer`, moving funds from the message sender's account to the designated fee collector.
+* A `TransactionBody` will include a new optional field `max_custom_fee` that a user can set to limit the paid custom fees. If this field is set for a transaction type that does not support custom fees (yet), the transaction will fail.
+* The account submitting a message to the topic will cover network transaction fees, and if necessary, a custom fee. The topic initiates the transfer of the custom fee to the fee collector, moving funds from the message sender's account to the designated fee collector.
 * If the fee of submitting a message exceeds the `max_custom_fee`, the transaction will fail with an appropriate error. The sender still pays node and network fees for failed transactions.
 * No balance will be held by the topic itself. Funds remain in the sender's account, and insufficient funds will result in the message submission failing with an appropriate error. The sender still pays node and network fees for failed transactions.
 
@@ -132,20 +132,21 @@ The HIP parameters are defined as follow:
 ### User Flows and Interaction
 
 * Users will specify the fee settings during the topic creation process through a simple interface in their Hedera client (refer to the creation of token custom fees/fixed fee for reference).
-* When submitting a message to a topic with custom fees through an application or wallet interface, users must set the maximum fee for the message. Alternatively, users can add a flag to accept all custom fees from a topic id. If the topic has no custom fees, neither is required.
+* When submitting a message to a topic with custom fees through an application or wallet interface, users can set the maximum fee for the message. If `max_custom_fee` is not set, any custom fee will be accepted by the user (up to the payer's available funds).
 * In case of user wallets, applications show the custom fees to the user before submitting the message.
 * Operators will get fee collections and distributions automatically through the custom fees just like they do in the token service currently.
+* If the specified custom fee limit or the payer's funds are insufficient to cover the custom fees, the transaction will fail.
 
 ### New and Modified Protobuf Messages
 
 The following is a list of modifications to the protobuf messages structure to comply with the above requirements.
 
-#### ConsensusCustomFee
+#### FixedCustomFee
 
-The `ConsensusCustomFee` message defines the type of fee and the account ID receiving the fee assessed during a message submission to the associated topic. A custom fee may only be a `FixedFee` and must specify a fee collector account to receive the assessed fees. `FixedFee` is an existing protobuf message and it must not be modified.
+The `FixedCustomFee` message defines the type of fee and the account ID receiving the fee assessed during a message submission to the associated topic. A custom fee may only be a `FixedFee` and must specify a fee collector account to receive the assessed fees. `FixedFee` is an existing protobuf message and it must not be modified.
 
 ```protobuf
-message ConsensusCustomFee {
+message FixedCustomFee {
   /**
   * Fixed fee to be charged
   */
@@ -179,7 +180,7 @@ message ConsensusCreateTopicTransactionBody {
   /**
     * The custom fee to be assessed during a message submission to this topic. Empty if no custom fees are applied.
     */
-  repeated ConsensusCustomFee custom_fees = 10;
+  repeated FixedCustomFee custom_fees = 10;
 }
 ```
 
@@ -203,35 +204,43 @@ message ConsensusUpdateTopicTransactionBody {
   /*
    * The custom fee to be assessed during a message submission to this topic. Null if the fees should not be updated.
    */
-  ConsensusCustomFeeList custom_fees = 12;
+  FixedCustomFeeList custom_fees = 12;
 
 }
 
 message FeeExemptKeyList {
   repeated Key keys = 1;
 }
 
-message ConsensusCustomFeeList {
-  repeated ConsensusCustomFee fees = 1;
+message FixedCustomFeeList {
+  repeated FixedCustomFee fees = 1;
 }
 ```
 
-#### ConsensusSubmitMessageTransactionBody
+#### TransactionBody
 
-The `ConsensusSubmitMessageTransactionBody` message is updated to include the optional `max_custom_fees` property for specifying the maximum fee that the user is willing to pay for the message.
+The `TransactionBody` message is updated to include the optional `max_custom_fees` property for specifying the maximum custom fee that the user is willing to pay for the transaction.
 
 ```protobuf
-message ConsensusSubmitMessageTransactionBody {
+message TransactionBody {
   [..]
   /**
-    * The maximum custom fee that the user is willing to pay for the message. This field will be ignored if `accept_all_custom_fees` is set to `true`.
+    * The maximum custom fee that the user is willing to pay for the message. If left empty, the user is willing to pay any custom fee.
+    * If used with a transaction type that does not support custom fee limits, the transaction will fail.
     */
-  repeated FixedFee max_custom_fees = 4;
-
+  repeated CustomFeeLimit max_custom_fees = 1001;
+}
+
+message CustomFeeLimit {
   /**
-   * If set to true, the transaction will accept all custom fees from the topic id
+   * The account of the fee payer
    */
-  bool accept_all_custom_fees = 5;
+  AccountID account_id = 1;
+
+  /**
+    * The maximum fees that the user is willing to pay for the message.
+    */
+  repeated FixedFee fees = 2;
 }
 ```
 
@@ -255,7 +264,7 @@ message ConsensusTopicInfo {
   /*
    * The custom fee to be assessed during a message submission to this topic
    */
-  repeated ConsensusCustomFee custom_fees = 12;
+  repeated FixedCustomFee custom_fees = 12;
 }
 ```
 
@@ -374,6 +383,10 @@ const maxCustomFee = new FixedFee()
   .setAmount(100) // a maximum of 100 tokens is paid for submitting the message
   .setDenominatingTokenId(TokenId.fromString("0.0.56789")); // The token to charge the fee in. HBAR if unset
 
+const maxCustomFee = new CustomFeeLimit()
+  .setAccountId(client.getOperatorAccountId()) // The account ID of the payer
+  .setFees([maxCustomFee]); // The maximum fees that the user is willing to pay for the message
+
 // Send message to the topic
 transactionResponse = await new TopicMessageSubmitTransaction({ topicId: topicId, message: "Hello, HCS!" })
   .setMaxCustomFees([maxCustomFee]) // Set the maximum fee for the message
@@ -386,6 +399,8 @@ This implementation shows the creation of a topic where each message submission
 ## Rejected Ideas
 
 * Setting a mandatory network enforced `allowCustomFeesPayment` flag in HCS message transactions to allow payment of fees.
+* Introducing an allowance concept for custom fees to allow users to pre-approve a certain amount of fees. This may be added later.
+* Defining the custom fee limit for each transaction type differently. This would add complexity and reduce consistency across transaction types.
 
 ## References