HIP-573: Blanket exemptions for custom fee collectors

Abstract

We propose to give token creators the option to exempt all of their token’s fee collectors from a custom fee. This differs from current network behavior, which only exempts a fee collector from fees for which it is the collector. The new option adds a single new protobuf field in the CustomFee message,

message CustomFee {
  ...
  AccountID fee_collector_account_id = 3;
  bool all_collectors_are_exempt = 4;
}

Motivation

The tokenomics of a fungible token with several fee collectors can be awkward when these collectors try to exchange units of the token. For example, suppose we create a fungible token 0.0.T with three fractional fees:

• Fee #1 sends 1/100 of the transferred value to collector 0.0.A.
• Fee #2 sends 2/100 of the transferred value to collector 0.0.B.
• Fee #3 sends 3/100 of the transferred value to collector 0.0.C.

Say collector 0.0.B sends 10_000 units of the token to 0.0.A. Account 0.0.B is exempt from fee #2 (since it is the collector). And since 0.0.A collects fee #1, there is no observable impact of that fee either. But fee #3 diverts 300 units away from 0.0.A and gives them to 0.0.C.

We can try to “clean up” by sending those 300 units from 0.0.C to 0.0.A—but now fee #2 diverts 6 units back to 0.0.B! Clearly this is a hassle.

What we really want is to make all of 0.0.A, 0.0.B, and 0.0.C exempt from each of fees #1, #2, and #3. That is, we want an option to define our custom fees with all_collectors_are_exempt = true.

Rationale

By extending the definition of a custom fee via this all_collectors_are_exempt flag, we provide the most flexibility to token creators; and avoid surprising any users who may be depending on the current behavior.

User stories

• As the creator of a fungible token whose tokenomics require three custom fees with three different collection accounts, I want my collectors to be able to exchange units of the token without paying custom fees.

Specification

The network needs to include the new all_collectors_are_exempt field in state when it appears in a CustomFee specification; and when deciding whether to assess a custom fee with all_collectors_are_exempt = true, needs to check if the potential payer is a collector for the token type of that custom fee.

Mirror Node

The mirror node is updated to add the new all_collectors_are_exempt field to the CustomFee. The new field is a boolean with a default value of false and cannot be null. This information is available via the /api/v1/tokens/{tokenId} REST API.

• Example: The other fields have been omitted for brevity

  {
    "custom_fees":{
        "created_timestamp":"1665581996.952930663",
        "fixed_fees":[
           {
            "amount":20,
            "denominating_token_id":"0.0.48597542",
            "collector_account_id":"0.0.48597559",
            "all_collectors_are_exempt":true
           }
        ]
    }
    ....
  }
  

Backwards Compatibility

This HIP does not propose any breaking changes. All existing custom fees will be unchanged. Any unchanged TokenCreate operation or TokenFeeScheduleUpdate operation will continue to have the same semantics.

Security Implications

This HIP does not change the precedent importance of securing fee collection accounts.

How to Teach This

If you don’t want your fee collectors to pay a custom fee, create it with all_collectors_are_exempt = true.

Reference Implementation

Please follow this issue to track progress of the reference implementation.

Rejected Ideas

Because HIP-18 did not stipulate any fee exemptions, and arguably it is surprising for fee collectors to ever pay custom fees for their token type, we considered just changing the default behavior to match this proposal. But we could not rule out the possibility of breaking current users, so opted for a backward-compatible approach.

Open Issues

We do not know of any open concerns with this proposal.

References

• HIP-18
• Reference implementation tracker

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: