Draft proposal for "Dollar-denominated values" HIP

Signed-off-by: Giuseppe Bertone <[email protected]>

Author: Neurone

HIP/hip-xxx.md

@@ -0,0 +1,280 @@
+---
+hip: 0000 # Assigned by HIP editor.
+title: Dollar-denominated values.
+author: Giuseppe Bertone (@neurone)
+working-group: Giuseppe Bertone (@neurone), Michael Garber (@mgarbs), Raphael Messian (@raphaelmessian), Ty Smith (@ty-swirldslabs), Keith Kowal (@reccetech)
+requested-by: Hashgraph (@hashgraph)
+discussions-to: <URL of the GitHub Pull Request for this HIP> # This will be filled by the HIP editor upon PR creation.
+type: Standards Track
+category: Core
+needs-hiero-approval: Yes
+needs-hedera-review: Yes
+status: Draft
+created: 2025-08-13
+updated: 2025-08-13
+requires: NA
+replaces: NA
+superseded-by: NA
+release: NA
+---
+
+## Abstract
+
+This HIP proposes extending Hedera's existing automatic HBAR-dollar conversion for network fees to all transaction values and service settings.
+
+Users would be able to specify dollar amounts in transactions and have the network calculate the corresponding HBAR amount at consensus level using the existing exchange rate oracle. This would enable dollar-denominated transfers, custom fees, scheduled transactions, and service pricing while maintaining a single source of truth for exchange rates.
+
+The proposal leverages existing TokenID definition by introducing system token identifiers for fiat currencies, starting with USD, to minimize protocol changes while maximizing compatibility with existing tools and SDKs.
+
+## Motivation
+
+Hedera is positioned as a business-friendly network, but HBAR price volatility creates significant challenges for developers, service providers, and users:
+
+- Developers face transaction failures when preset HBAR limits become insufficient due to price changes
+- Service providers must continuously monitor and update custom fees to maintain consistent dollar pricing
+- Users cannot guarantee actual fiat transferred values in scheduled transactions spanning weeks or months
+- Payment and micropayment adoption is hindered by the need for constant price monitoring and conversion
+
+Current workarounds require off-chain conversion calculations that introduce complexity, errors, and security risks, or using stablecoins as an alternative payment mechanisms instead of HBAR. While possible in some cases, this introduced friction and forces users and service providers to deal with at least two cryptocurrencies (HBAR plus the stablecoin).
+
+In addition, no other public ledger offers consensus-level fiat denomination, representing a unique opportunity for Hedera to differentiate itself and streamline business adoption.
+
+## Rationale
+
+The design leverages Hedera's existing exchange rate infrastructure rather than creating new oracle mechanisms. This approach maintains consistency between network fees and transaction values, avoiding user confusion from multiple exchange rates.
+
+The TokenID-based implementation was chosen because:
+
+- It reuses existing protobuf structures, minimizing protocol changes
+- It maintains compatibility with current tools, UIs, and SDKs
+- It naturally extends to future fiat currencies through additional system tokens
+- It integrates seamlessly with existing custom fee and transfer mechanisms
+
+Alternative designs considered:
+
+- New protobuf fields: Would require extensive protocol changes and tool updates
+- Separate denomination flags: Would complicate transaction structure and validation
+
+## User stories
+
+- As a service provider, I want to set a price in dollars for my HCS paid topics and HTS royalties so that I can maintain consistent revenue regardless of HBAR price fluctuations.
+- As a business owner, I want to create scheduled payments in dollars so that the recipient receives the agreed dollar amount even if the transaction executes weeks later when HBAR prices may have changed.
+- As a user, I want to send a specific dollar amount to someone without having to calculate HBAR conversions or worry about price changes between transaction creation and execution (e.g., long lasting scheduled transaction)
+- As a developer, I want to set network fee limits in dollars so that my applications don't fail when HBAR prices change and my preset limits become insufficient.
+- As a developer, I want to avoid conversion bugs in my application by letting the network handle HBAR-dollar calculations at consensus time with provable accuracy and exchange rate.
+- As a developer, I want to my smart contracts to manage and transfer dollar amounts without relying on 3rd party owned oracles.
+
+## Specification
+
+### Core Mechanism
+
+Dollar denomination is implemented using system TokenID identifiers to indicate fiat currency intent:
+
+- USD: `TokenId(0, 0, 18446744073709551615)` (max uint64)
+- Future currencies: `TokenId(0, 0, 18446744073709551614)` (max uint64 - 1) for EUR, etc.
+
+When a system fiat TokenID is used in any amount field (service or network fee), the network:
+
+1. Calculates the equivalent HBAR amount at consensus time using the in memory exchange rate
+2. Executes the transaction using the calculated HBAR amount
+3. Records both dollar intent and actual HBAR amount in transaction records
+
+The record files already offer the structure to store all those information:
+
+- the transaction body contains the original dollar intent
+- the transaction record contains
+  - the receipt with the exchange rate
+  - the transferList with the real HBAR transfers
+
+This is an example of the information inside the record file for a random [[email protected]](https://hashscan.io/mainnet/transaction/1755109617.960565000) mainnet transfer transaction:
+
+```javascript
+=== Transaction #0 dkWHmEhnjmA604qdQrwoEdzkeKlStWwYyGNGxuA8lxGC3+UNCdRkiH0zWTZzvKGv 7645879848678e603ad38a9d42bc2811dce478a952b56c18c86346c6e03c971182dfe50d09d464887d33593673bca1af ===
+{
+  transaction: {
+    signedTransactionBytes: 'Cn8KEwoMCOex88QGEIDfqpkCEgMYnRkSAhgGGMCEPSICCHgyRjE3NTUxMDk2MTc1OTAgTW9uaXRvciBjcnlwdG8gb24gaGVkZXJhLW1pcnJvci1tb25pdG9yLTZmZGJjNTg5NmQtZnRmdnNyFAoSCgcKAxidGRABCgcKAxieGRACEmYKZAogJ0HRd0U560CTTYceVsIAtPQJ0t8/uzKzOrUskDRIXfcaQFbKkQw6bhlB1DCAWOEmy2Uhl+whLXqt3rvQICfxPkyaqndtWd4e/ZTQAFE1nve6JWHJtVf8b6N172Ozkr8jUA0='
+  },
+  record: {
+    receipt: {
+      status: 'SUCCESS',
+      exchangeRate: {
+        currentRate: {
+          hbarEquiv: 30000,
+          centEquiv: 791784,
+          expirationTime: { seconds: '1755111600' }
+        },
+        nextRate: {
+          hbarEquiv: 30000,
+          centEquiv: 791978,
+          expirationTime: { seconds: '1755115200' }
+        }
+      }
+    },
+    transactionHash: 'dkWHmEhnjmA604qdQrwoEdzkeKlStWwYyGNGxuA8lxGC3+UNCdRkiH0zWTZzvKGv',
+    consensusTimestamp: { seconds: '1755109617', nanos: 960565000 },
+    transactionID: {
+      transactionValidStart: { seconds: '1755109607', nanos: 590000000 },
+      accountID: { accountNum: '3229' }
+    },
+    memo: '1755109617590 Monitor crypto on hedera-mirror-monitor-6fdbc5896d-ftfvs',
+    transactionFee: '38860',
+    transferList: {
+      accountAmounts: [
+        { accountID: { accountNum: '6' }, amount: '1578' },
+        { accountID: { accountNum: '801' }, amount: '37282' },
+        { accountID: { accountNum: '3229' }, amount: '-38861' },
+        { accountID: { accountNum: '3230' }, amount: '1' }
+      ]
+    }
+  }
+}
+
+=== Signatures #0 dkWHmEhnjmA604qdQrwoEdzkeKlStWwYyGNGxuA8lxGC3+UNCdRkiH0zWTZzvKGv 7645879848678e603ad38a9d42bc2811dce478a952b56c18c86346c6e03c971182dfe50d09d464887d33593673bca1af ===
+{
+  pubKeyPrefix: 'J0HRd0U560CTTYceVsIAtPQJ0t8/uzKzOrUskDRIXfc=',
+  ed25519: 'VsqRDDpuGUHUMIBY4SbLZSGX7CEteq3eu9AgJ/E+TJqqd21Z3h79lNAAUTWe97olYcm1V/xvo3XvY7OSvyNQDQ==',
+  pubKeyPrefixHex: '2741d1774539eb40934d871e56c200b4f409d2df3fbb32b33ab52c9034485df7'
+}
+
+=== Body #0 dkWHmEhnjmA604qdQrwoEdzkeKlStWwYyGNGxuA8lxGC3+UNCdRkiH0zWTZzvKGv 7645879848678e603ad38a9d42bc2811dce478a952b56c18c86346c6e03c971182dfe50d09d464887d33593673bca1af ===
+{
+  transactionID: {
+    transactionValidStart: { seconds: '1755109607', nanos: 590000000 },
+    accountID: { accountNum: '3229' }
+  },
+  nodeAccountID: { accountNum: '6' },
+  transactionFee: '1000000',
+  transactionValidDuration: { seconds: '120' },
+  memo: '1755109617590 Monitor crypto on hedera-mirror-monitor-6fdbc5896d-ftfvs',
+  cryptoTransfer: {
+    transfers: {
+      accountAmounts: [
+        { accountID: { accountNum: '3229' }, amount: '-1' },
+        { accountID: { accountNum: '3230' }, amount: '1' }
+      ]
+    }
+  }
+}
+```
+
+The fee structure (transactionFee) is extended to specify TokenIDs as a payment for the network fees.
+
+### Transaction Integration
+
+If a field can be set using a TokenID, that same field can also be set in dollars:
+
+- Transfer amounts in `CryptoTransfer`
+- Custom fees in token creation and updates
+- Scheduled transaction amounts
+- Smart contract value transfers
+
+All existing HBAR amount fields support dollar denomination:
+
+- Max network fees
+- ...
+
+### SDK Integration Examples
+
+```javascript
+// Transfer $1.50 with an Hedera transfer, using $0.01 as max transaction fee
+const txTransfer = new TransferTransaction()
+    .addDollarTransfer(senderAccount, -1.5)
+    .addDollarTransfer(receiverAccount, 1.5)
+    .setMaxTransactionFee(new Dollar(0.01));
+
+// Create a custom fixed fee so that $0.50 worth of HBAR is sent to the collector every time fee applies
+new CustomFixedFee()
+    .setDenominatingTokenId(TokenId.USD) 
+    .setAmount(0.5)
+    .setFeeCollectorAccountId(feeCollectorAccountId);
+```
+
+### Impact on Mirror Node
+
+Leveraging the TokenID, the Mirror Node already provides all the features needed:
+
+- Record the original dollar amounts alongside calculated HBAR amounts automatically
+- Maintain exchange rate information for each transaction
+- Provide historical dollar amounts and exchange rates used
+
+The mirror node must conform to the new `transactionFee` supporting TokenIDs.
+
+The `/api/v1/tokens` and `api/v1/tokens/*` endpoints are not expected to return results when queried with system token IDs, therefore, no changes are expected at the API level.
+
+### Impact on SDK
+
+SDKs will be updated to:
+
+- Add convenience methods for dollar denomination (e.g., `addDollarTransfer()`,  `setMaxTransactionFee(new Dollar(0.5))`, etc.)
+- Provide system TokenID constants (e.g., `TokenId.USD`)
+- Support dollar amount validation and formatting
+- Maintain backward compatibility with existing HBAR-only methods
+
+## Backwards Compatibility
+
+This proposal is fully backward compatible:
+
+- Existing HBAR-denominated transactions continue to work unchanged
+- New dollar denomination is purely additive functionality
+- Few changes to existing protobuf field meanings or validations
+- SDKs can add new methods while preserving existing APIs
+
+## Security Implications
+
+Security considerations include:
+
+- Exchange rate oracle integrity: Leverages existing trusted oracle used for network fees
+- Transaction replay: Dollar amounts are converted at consensus time, preventing value manipulation
+- Validation: Network validates that only one denomination type is used per field
+
+The proposal actually improves security by:
+
+- Eliminating client-side conversion errors and bugs
+- Providing consensus-level validation of exchange calculations
+- Reducing fraud potential from manipulated conversion rates
+
+## How to Teach This
+
+Documentation and educational materials should emphasize:
+
+- Dollar denomination as an optional alternative to HBAR amounts
+- Use cases where dollar denomination provides the most benefit (scheduled transactions, service pricing)
+- Exchange rate consistency with network fees
+- SDK convenience methods for common dollar operations
+- Best practices for choosing between HBAR and dollar denomination
+
+Integration guides should show:
+
+- Migration paths for existing applications
+- Testing strategies for fiat-denominated transactions
+
+## Reference Implementation
+
+_The reference implementation must be complete before any HIP is given the status
+of “Final.” The final implementation must include test code and documentation._
+
+TBD
+
+## Rejected Ideas
+
+- **Multiple Exchange Rate Sources**: Using different exchange rates for different transaction types would confuse users and complicate the system. Maintaining consistency with network fee rates provides better UX.
+- **Real-time Rate Updates**: More frequent exchange rate updates were considered but rejected to maintain consistency with existing network fee mechanisms and avoid creating conflicting rate sources.
+
+## Open Issues
+
+- **Precision Handling**: Specification of decimal precision and rounding rules for dollar amounts
+- **System TokenID Range**: Final determination of whether to use `max uint64` and below values or system account range (e.g., `0.0.150`) for fiat currency identifiers
+- **Future Currency Support**: Preparing the field for additional fiat currencies beyond USD
+- **Creating dedicated protobuf fields for HBAR-only fields**: The TokenID solution allow using USD when it is possible to use a token, but it does not allow to define USD for HBAR only fields, like for example max transaction fees.
+
+## References
+
+- [Hedera Exchange Rate API Documentation](https://docs.hedera.com/hedera/sdks-and-apis/rest-api#exchange-rates)
+- [Mirror Node Exchange Rate Endpoint](https://mainnet.mirrornode.hedera.com/api/v1/network/exchangerate)
+- [TokenID Protobuf Definition](https://github.com/hashgraph/hedera-protobufs/blob/main/services/basic_types.proto)
+- [Custom Fixed Fees Documentation](https://docs.hedera.com/hedera/sdks-and-apis/hedera-api/token-service/customfees/fixedfee)
+
+## Copyright/license
+
+This document is licensed under the Apache License, Version 2.0 —
+see [LICENSE](../LICENSE) or <https://www.apache.org/licenses/LICENSE-2.0>.