Dollar-denominated values

[Neurone]

Hedera is a business-friendly network that already offers automatic HBAR-dollar conversion for network fees.

The idea is to extend this feature to all transaction values and service settings, enabling users to specify dollar amounts in the transactions and have the network calculate the corresponding HBAR amount at consensus level.

This would allow users to transfer a dollar amount, set a custom fee in dollars for an HCS message or token, and specify the maximum network fee in dollars, etc.

Allowing the optional use of dollars in transaction definitions would also enable:

• service providers to set a price in dollars for their services and get paid directly the correct hbar amount.
• streamlined support for offline signatures and scheduled transactions, particularly those spanning across multiple weeks.
• safer transactions signature processes, as the payer's intention is better reflected in the transaction.
• reduced potential issues with client or UI errors in conversions or fraud attempts.
• reduced UX friction, as there are no online conversions, fewer errors and fewer fraud attempts.

This would be a unique feature for Hedera, as no other public ledger currently allows this at consensus level.

Value proposition

• This would streamline Hedera adoption for payments and micro payments (i.e. for individual API requests)
• It would distinguish Hedera from other ledgers.

Rationales and current issues

HBAR is great medium for payments and micropayments — the network is fast and cheap — but there are some issues when hbar changes price, for example:

• As a developer, it may happen that the limits I have imposed (e.g. network fee for account creation, token creation, etc.) are no longer sufficient for the goal and this leads to errors in the execution of transactions and forces an update of the code or application configuration.
• As a service provider, user or developer leveraging Hedera for business or applications, I need to check the hbar conversion value and set that amount in the transaction definition whenever I want to receive or send a payment.
• As a service provider, I would need to continuously check the hbar–dollar ratio and update my custom service fees accordingly.
• As a user or developer, I always need to verify that the amounts are correct. Many things can go wrong in the transaction definition process - see this perfect example of a bug in the JS SDK.
• As a user, when I create scheduled transactions that span multiple weeks, I have to set the values in the hbar, which means I cannot guarantee the actual transferred value when the scheduled transaction is finally signed and executed in the future.

User stories

• As a service provider, I want to set a price in dollars for my services (HCS paid topic, HTS royalties, etc.) and have Hedera guarantee that the conversion will be done correctly in a provable way.
• As a user or developer, I want to set an amount in dollars (transfers, network fees, custom fees, etc.) and have Hedera perform the conversion to hbar correctly and provably at execution time.

High-level specs

• If a field can be set in HBAR or tinyBAR, that same field can also be set in dollars.
• If a dollar value is defined for a field, a value in hbar cannot be defined for the same field, and vice versa.
• This feature must work for all Hedera transaction types.

This involves making changes at the consensus and (potentially) mirror node levels, but leveraging existing functionality for conversion.

Possible implementation

TokenID is already used to denominate multiple types of payment (custom fees, transfers, etc.).

We could define a system TokenID (e.g., 0.0.<max uint64>) to indicate the intention to specify dollar amounts.

This would simplify the reuse and integration of existing tools (UX, UI, SDKs, APIs, etc.) while minimising the impact on the Protobuf definitions.

In the future, we can also think to support values in other fiat currencies simply adding new system tokens (euros = 0.0.<max uint64> - 1, yuan = 0.0.<max uint64> - 2, etc.) and new official oracle services, in addition to the hbar-dollar one.

Alternatively, we can choose an ID from the system accounts range that has not already been taken, such as 0.0.150, 0.0.151, etc.

Code snippets

Examples of code snippets that developers can use after the HIP is implemented:

// Sending 1.5 dollars with an Hedera transfer
const txTransfer = new TransferTransaction()
   .addDollarTransfer(senderAccount, -1.5)
   .addDollarTransfer(receiverAccount, 1.5);

// Create a custom fixed fee so that 1.5 $ worth of HBAR is sent to the collector every time fee applies
new CustomFixedFee()
    .setDenominatingTokenId(TokenID.USD) 
    .setAmount(1.5)
    .setFeeCollectorAccountId(feeCollectorAccountId);

[mgarbs]

Kudos for a forward-thinking idea @Neurone ! Looking at how the spec might be, it seems like there needs to be a "rate freshness" to get the usd hbar price any time a message is sent to the topic so the payment is always accurate. I really like this idea. Maybe it would also be good to include the rate of hbar/usd in the receipt whenever a message is sent to the topic too so users can easily see what they were charged in habr and possibly adding this data to the mirror node when a message is sent for historical query of hbar/usd price at the time the message was sent. Thoughts?

[Neurone]

Hi @mgarbs thanks for the suggestions, really interesting observations.

About refreshing the rate more frequently.

In my opinion, it is important to maintain a single source of truth for the USD-HBAR rate and to avoid creating a dedicated oracle for this feature.

The existing rate is adjusted every hour and I believe updating this frequency would be at CoinCom's discretion.

This rate enables Governing Council members to maintain coherence between consensus node and network fees while providing frequent adjustments. Therefore, if this rate is suitable for them, it could also be suitable for other service providers.

At the same time, users would find it confusing to pay one rate for network fees and another for values, even if the latter were slightly more precise. Following the network fee rate would therefore also make sense for them.

So, I suggest not mentioning the rate update frequency in this HIP, but considering creating a separate HIP in the future to ask for a change in the HBAR-USD ratio update frequency, should the community express that need after using the new feature in production.

[Neurone]

Regarding the receipt, I agree that being able to check the ratio is important. However, as we already have several tools for this purpose, it should not be an issue if this HIP does not introduce a new function specifically for that purpose.

Currently, users can retrieve exchange rate information for each transaction:

• in the record receipts via the Consensus Nodes
• via Mirror Node API using for example the https://testnet.mirrornode.hedera.com/api/v1/network/exchangerate?timestamp=<tx timestamp> endpoint. This method is also used by the explorer, for example, to show the exchange rate at the time of transaction execution (i.e., this random old mainnet transaction shows an historical HBAR price of $0.1088)