iotaledger · salaheldinsoliman · Jun 11, 2025 · roman1e2f5p8s · Jul 16, 2025 · roman1e2f5p8s
diff --git a/iips/IIP-0003/iip-0003.md b/iips/IIP-0003/iip-0003.md
@@ -0,0 +1,91 @@
+---
+iip: 3
+title: Gas Price Recommendation Tool
+description: An AI-assisted mechanism for estimating transaction fees in IOTA
-description: An AI-assisted mechanism for estimating transaction fees in IOTA
+description: An AI-assisted mechanism for estimating gas price in IOTA
-description: An AI-assisted mechanism for estimating transaction fees in IOTA
+description: An AI-assisted mechanism for estimating gas price in IOTA
+author: Salahledin Soliman (@salahledinsoliman) <salaheldin.soliman@iota.org>
+discussions-to: https://github.com/iotaledger/IIPs/discussions/16
+status: Draft
+type: Process
+created: 2025-06-04
+---
+
+## Abstract
+
+This IIP introduces a gas price recommendation mechanism for IOTA Rebased that leverages historical transaction outcomes and real-time congestion indicators to improve the user experience by reducing unnecessary fee over-payment and transaction cancellation. The mechanism is implemented as an off-chain, adaptive prediction model trained using feedback from previously cancelled and accepted transactions. At its core, the model estimates the minimal tip required for a transaction to be included under current network conditions by learning from features such as object hotness, computation cost, and scheduling outcomes. The training process uses online stochastic gradient descent to continuously refine the model with fresh data, allowing it to adapt to dynamic workloads and validator behavior. The proposed mechanism requires no changes to protocol logic and can be integrated into wallets, SDKs, and developer tooling to provide actionable, data-driven fee guidance.
-This IIP introduces a gas price recommendation mechanism for IOTA Rebased that leverages historical transaction outcomes and real-time congestion indicators to improve the user experience by reducing unnecessary fee over-payment and transaction cancellation. The mechanism is implemented as an off-chain, adaptive prediction model trained using feedback from previously cancelled and accepted transactions. At its core, the model estimates the minimal tip required for a transaction to be included under current network conditions by learning from features such as object hotness, computation cost, and scheduling outcomes. The training process uses online stochastic gradient descent to continuously refine the model with fresh data, allowing it to adapt to dynamic workloads and validator behavior. The proposed mechanism requires no changes to protocol logic and can be integrated into wallets, SDKs, and developer tooling to provide actionable, data-driven fee guidance.
+This IIP introduces a gas price recommendation mechanism for IOTA that leverages historical transaction outcomes and real-time congestion indicators to improve the user experience by reducing unnecessary fee over-payment and transaction cancellation. The mechanism is implemented as an off-chain, adaptive prediction model trained using feedback from previously cancelled and accepted transactions. At its core, the model estimates the minimal gas price required for a transaction to be included under current network conditions by learning from features such as object hotness, computation cost, and scheduling outcomes. The training process uses online stochastic gradient descent to continuously refine the model with fresh data, allowing it to adapt to dynamic workloads and validator behavior. The proposed mechanism requires no changes to protocol logic and can be integrated into wallets, SDKs, and developer tooling to provide actionable, data-driven gas price guidance.
-This IIP introduces a gas price recommendation mechanism for IOTA Rebased that leverages historical transaction outcomes and real-time congestion indicators to improve the user experience by reducing unnecessary fee over-payment and transaction cancellation. The mechanism is implemented as an off-chain, adaptive prediction model trained using feedback from previously cancelled and accepted transactions. At its core, the model estimates the minimal tip required for a transaction to be included under current network conditions by learning from features such as object hotness, computation cost, and scheduling outcomes. The training process uses online stochastic gradient descent to continuously refine the model with fresh data, allowing it to adapt to dynamic workloads and validator behavior. The proposed mechanism requires no changes to protocol logic and can be integrated into wallets, SDKs, and developer tooling to provide actionable, data-driven fee guidance.
+This IIP introduces a gas price recommendation mechanism for IOTA that leverages historical transaction outcomes and real-time congestion indicators to improve the user experience by reducing unnecessary fee over-payment and transaction cancellation. The mechanism is implemented as an off-chain, adaptive prediction model trained using feedback from previously cancelled and accepted transactions. At its core, the model estimates the minimal gas price required for a transaction to be included under current network conditions by learning from features such as object hotness, computation cost, and scheduling outcomes. The training process uses online stochastic gradient descent to continuously refine the model with fresh data, allowing it to adapt to dynamic workloads and validator behavior. The proposed mechanism requires no changes to protocol logic and can be integrated into wallets, SDKs, and developer tooling to provide actionable, data-driven gas price guidance.
+
+## Motivation
+
+In IOTA, transactions can involve either owned objects (which are guaranteed to finalize upon passing consensus, regardless of their gas price) or shared objects (which may conflict with other transactions and cause congestion). However, the protocol currently offers no mechanism to help users estimate the appropriate tip for shared-object transactions, which are more likely to be delayed or cancelled under contention.
-In IOTA, transactions can involve either owned objects (which are guaranteed to finalize upon passing consensus, regardless of their gas price) or shared objects (which may conflict with other transactions and cause congestion). However, the protocol currently offers no mechanism to help users estimate the appropriate tip for shared-object transactions, which are more likely to be delayed or cancelled under contention.
+In IOTA, transactions can involve either only _owned objects_ (in which case such transactions are guaranteed to finalize upon passing consensus, regardless of their gas price) or contain _shared objects_ (such transactions may conflict with others, and thus, they require sequencing and might cause congestion). However, the protocol currently offers no mechanism to help users estimate the appropriate gas price for shared-object transactions, which are more likely to be delayed or cancelled under contention.
-In IOTA, transactions can involve either owned objects (which are guaranteed to finalize upon passing consensus, regardless of their gas price) or shared objects (which may conflict with other transactions and cause congestion). However, the protocol currently offers no mechanism to help users estimate the appropriate tip for shared-object transactions, which are more likely to be delayed or cancelled under contention.
+In IOTA, transactions can involve either only _owned objects_ (in which case such transactions are guaranteed to finalize upon passing consensus, regardless of their gas price) or contain _shared objects_ (such transactions may conflict with others, and thus, they require sequencing and might cause congestion). However, the protocol currently offers no mechanism to help users estimate the appropriate gas price for shared-object transactions, which are more likely to be delayed or cancelled under contention.
+
+As a result, users often underbid and get rejected or delayed, or overbid and waste IOTAs, especially in high-traffic scenarios. This unpredictability harms user experience and undermines efficiency.
+
+To solve this, we propose a feedback-driven gas price recommendation engine that analyzes historical transaction outcomes to predict the minimum tip that would likely have led to inclusion. This enables nearly accurate, real-time tip suggestions without requiring changes to the protocol, improving fairness, reliability, and developer experience.
-To solve this, we propose a feedback-driven gas price recommendation engine that analyzes historical transaction outcomes to predict the minimum tip that would likely have led to inclusion. This enables nearly accurate, real-time tip suggestions without requiring changes to the protocol, improving fairness, reliability, and developer experience.
+To solve this, we propose a feedback-driven gas price recommendation engine that analyzes historical transaction outcomes to predict the minimum gas price that would likely have led to successful execution. This enables nearly accurate, real-time gas price suggestions without requiring changes to the protocol, improving fairness, reliability, and developer experience.
-To solve this, we propose a feedback-driven gas price recommendation engine that analyzes historical transaction outcomes to predict the minimum tip that would likely have led to inclusion. This enables nearly accurate, real-time tip suggestions without requiring changes to the protocol, improving fairness, reliability, and developer experience.
+To solve this, we propose a feedback-driven gas price recommendation engine that analyzes historical transaction outcomes to predict the minimum gas price that would likely have led to successful execution. This enables nearly accurate, real-time gas price suggestions without requiring changes to the protocol, improving fairness, reliability, and developer experience.
+
+## Specification
+
+This proposal introduces a feedback and prediction mechanism for gas price estimation in transactions involving shared objects on the IOTA smart contract platform.
+
+### Gas Price Feedback
+As part of the core node logic, each time a transaction is scheduled, the node records its gas price and execution duration per shared object it accesses. When a transaction is later cancelled due to repeated deferrals, the node provides a gas price suggestion—a value that would likely have resulted in successful inclusion under the observed congestion levels.
-As part of the core node logic, each time a transaction is scheduled, the node records its gas price and execution duration per shared object it accesses. When a transaction is later cancelled due to repeated deferrals, the node provides a gas price suggestion—a value that would likely have resulted in successful inclusion under the observed congestion levels.
+As part of the core node logic, each time a transaction is scheduled, the node records its gas price and execution duration per shared object it accesses. Using this data, whenever a transaction is cancelled due to repeated deferrals, the node provides a suggested gas price as feedback—a value that would likely have resulted in successful inclusion under the observed congestion levels.
-As part of the core node logic, each time a transaction is scheduled, the node records its gas price and execution duration per shared object it accesses. When a transaction is later cancelled due to repeated deferrals, the node provides a gas price suggestion—a value that would likely have resulted in successful inclusion under the observed congestion levels.
+As part of the core node logic, each time a transaction is scheduled, the node records its gas price and execution duration per shared object it accesses. Using this data, whenever a transaction is cancelled due to repeated deferrals, the node provides a suggested gas price as feedback—a value that would likely have resulted in successful inclusion under the observed congestion levels.
+
+This value is computed using percentile-based statistics over recorded gas prices per object, adjusted according to transaction duration and the severity of congestion. The feedback is embedded in the deferral response to the client and requires no protocol modification.
-This value is computed using percentile-based statistics over recorded gas prices per object, adjusted according to transaction duration and the severity of congestion. The feedback is embedded in the deferral response to the client and requires no protocol modification.
+This value is computed as the maximum over recorded gas prices per input shared object, adjusted according to transaction duration and the severity of congestion. The feedback is embedded in the cancellation response to the client and requires no protocol modification.
-This value is computed using percentile-based statistics over recorded gas prices per object, adjusted according to transaction duration and the severity of congestion. The feedback is embedded in the deferral response to the client and requires no protocol modification.
+This value is computed as the maximum over recorded gas prices per input shared object, adjusted according to transaction duration and the severity of congestion. The feedback is embedded in the cancellation response to the client and requires no protocol modification.
+
+### Gas Price Prediction
+A prediction engine uses the historical gas price feedback to estimate, before submission, the minimum tip a user should attach to ensure inclusion. This engine operates off-chain and is designed to be integrated into wallets, SDKs, or development tools.
-A prediction engine uses the historical gas price feedback to estimate, before submission, the minimum tip a user should attach to ensure inclusion. This engine operates off-chain and is designed to be integrated into wallets, SDKs, or development tools.
+A prediction engine uses the historical gas price feedback to estimate (before transaction submission) the minimum gas price a user should attach to ensure successful execution. This engine operates off-chain and is designed to be integrated into wallets, SDKs, or development tools.
-A prediction engine uses the historical gas price feedback to estimate, before submission, the minimum tip a user should attach to ensure inclusion. This engine operates off-chain and is designed to be integrated into wallets, SDKs, or development tools.
+A prediction engine uses the historical gas price feedback to estimate (before transaction submission) the minimum gas price a user should attach to ensure successful execution. This engine operates off-chain and is designed to be integrated into wallets, SDKs, or development tools.
+
+The predictor models shared-object contention using a per-object congestion weight vector, which is updated incrementally using online stochastic gradient descent. For a new transaction, the engine uses these weights to compute a harmonically weighted gas price suggestion.
-The predictor models shared-object contention using a per-object congestion weight vector, which is updated incrementally using online stochastic gradient descent. For a new transaction, the engine uses these weights to compute a harmonically weighted gas price suggestion.
+The predictor models shared-object contention using a per-object congestion weight vector, which is updated incrementally using online stochastic gradient descent. For a new transaction, the engine uses these weights to compute a harmonically weighted suggested gas price.
-The predictor models shared-object contention using a per-object congestion weight vector, which is updated incrementally using online stochastic gradient descent. For a new transaction, the engine uses these weights to compute a harmonically weighted gas price suggestion.
+The predictor models shared-object contention using a per-object congestion weight vector, which is updated incrementally using online stochastic gradient descent. For a new transaction, the engine uses these weights to compute a harmonically weighted suggested gas price.
+
+### Syntax and Semantics
+#### Gas Price Feedback API (Node):
+
+New field in cancellation response:
+
+`suggested_gas_price: u64`
+
+A recommended gas price for resubmission, computed from historical scheduling outcomes.
-A recommended gas price for resubmission, computed from historical scheduling outcomes.
+A suggested gas price for resubmission, computed from historical scheduling outcomes in the feedback mechanism.
-A recommended gas price for resubmission, computed from historical scheduling outcomes.
+A suggested gas price for resubmission, computed from historical scheduling outcomes in the feedback mechanism.
+
+#### Prediction Interface (External Tool):
+
+Input: Transaction metadata (touched objects)
+
+Output: Estimated recommended_gas_price: u64
-Output: Estimated recommended_gas_price: u64
+Output: Estimated `recommended_gas_price: u64`
-Output: Estimated recommended_gas_price: u64
+Output: Estimated `recommended_gas_price: u64`
+An anticipatory recommendation before submission.
+
+This specification introduces no changes to consensus, validity rules, or core transaction semantics. It adds observational logic and client-side estimation tools to enhance user experience without impacting protocol security or performance.
+
+
+## Rationale
+
+The motivation for this proposal stems from a fundamental user experience issue in IOTA’s transaction model: users interacting with shared objects have no guidance on how much gas price (tip) they should offer to ensure inclusion. This leads to inefficiencies—users may overpay, or worse, repeatedly underbid and have their transactions cancelled. The current mechanism lacks any feedback or proactive recommendation logic.
-The motivation for this proposal stems from a fundamental user experience issue in IOTA’s transaction model: users interacting with shared objects have no guidance on how much gas price (tip) they should offer to ensure inclusion. This leads to inefficiencies—users may overpay, or worse, repeatedly underbid and have their transactions cancelled. The current mechanism lacks any feedback or proactive recommendation logic.
+The motivation for this proposal stems from a fundamental user experience issue in IOTA’s transaction model: users interacting with shared objects have no guidance on how much gas price (tip) they should offer to avoid cancellations due to congestion. This leads to inefficiencies—users may overpay, or worse, repeatedly underbid and have their transactions cancelled. The current mechanism lacks any feedback or proactive recommendation logic.
-The motivation for this proposal stems from a fundamental user experience issue in IOTA’s transaction model: users interacting with shared objects have no guidance on how much gas price (tip) they should offer to ensure inclusion. This leads to inefficiencies—users may overpay, or worse, repeatedly underbid and have their transactions cancelled. The current mechanism lacks any feedback or proactive recommendation logic.
+The motivation for this proposal stems from a fundamental user experience issue in IOTA’s transaction model: users interacting with shared objects have no guidance on how much gas price (tip) they should offer to avoid cancellations due to congestion. This leads to inefficiencies—users may overpay, or worse, repeatedly underbid and have their transactions cancelled. The current mechanism lacks any feedback or proactive recommendation logic.
+
+### Design Decisions
+To address this, the design separates the solution into two components:
+
+#### In-node Gas Price Feedback:
+The gas price suggestion returned upon transaction cancellation is computed from real historical data observed by the node. It reflects object-level congestion at the time of deferral and uses percentile-based aggregation over recorded gas prices and execution durations. This provides immediate, data-grounded feedback to users without modifying protocol rules.
-The gas price suggestion returned upon transaction cancellation is computed from real historical data observed by the node. It reflects object-level congestion at the time of deferral and uses percentile-based aggregation over recorded gas prices and execution durations. This provides immediate, data-grounded feedback to users without modifying protocol rules.
+The gas price suggestion returned upon transaction cancellation is computed from real historical data observed by the node. It reflects object-level congestion at the time of cancellation and uses statistics derived from recorded gas prices and execution durations. This provides immediate, data-grounded feedback to users without modifying protocol rules.
-The gas price suggestion returned upon transaction cancellation is computed from real historical data observed by the node. It reflects object-level congestion at the time of deferral and uses percentile-based aggregation over recorded gas prices and execution durations. This provides immediate, data-grounded feedback to users without modifying protocol rules.
+The gas price suggestion returned upon transaction cancellation is computed from real historical data observed by the node. It reflects object-level congestion at the time of cancellation and uses statistics derived from recorded gas prices and execution durations. This provides immediate, data-grounded feedback to users without modifying protocol rules.
+
+#### External Prediction Engine:
+A learning-based model predicts, prior to submission, the minimum gas price likely required for successful inclusion. This model is trained on historical feedback collected over time. We chose online stochastic gradient descent (SGD) for its simplicity, adaptability, and low overhead in a high-throughput setting. It continuously updates per-object congestion weights and requires minimal infrastructure.
-A learning-based model predicts, prior to submission, the minimum gas price likely required for successful inclusion. This model is trained on historical feedback collected over time. We chose online stochastic gradient descent (SGD) for its simplicity, adaptability, and low overhead in a high-throughput setting. It continuously updates per-object congestion weights and requires minimal infrastructure.
+Prior to transaction submission, a learning-based model predicts the minimum gas price likely required for successful execution (i.e., cancellation due to congestion is avoided). This model is trained on historical feedback collected over time. We chose online stochastic gradient descent (SGD) for its simplicity, adaptability, and low overhead in a high-throughput setting. It continuously updates per-object congestion weights and requires minimal infrastructure.
-A learning-based model predicts, prior to submission, the minimum gas price likely required for successful inclusion. This model is trained on historical feedback collected over time. We chose online stochastic gradient descent (SGD) for its simplicity, adaptability, and low overhead in a high-throughput setting. It continuously updates per-object congestion weights and requires minimal infrastructure.
+Prior to transaction submission, a learning-based model predicts the minimum gas price likely required for successful execution (i.e., cancellation due to congestion is avoided). This model is trained on historical feedback collected over time. We chose online stochastic gradient descent (SGD) for its simplicity, adaptability, and low overhead in a high-throughput setting. It continuously updates per-object congestion weights and requires minimal infrastructure.
+
+#### Alternative Approaches
+We considered more sophisticated models, including recurrent neural networks (RNNs), which are well-suited for learning temporal patterns and could offer higher prediction accuracy in complex congestion scenarios. However, RNNs have drawbacks:
+
+- Higher computational cost and memory footprint
+
+- Greater complexity in tuning and deployment
+
+Given the early stage of the proposal and the requirement for integration with live, high-throughput transaction streams, we opted to first implement online gradient descent. This simpler model allows rapid prototyping, direct interpretability of object weights, and easier integration with tooling.
+
+#### Roadmap for Comparison
+There is a draft plan to implement and evaluate both models—online SGD and RNNs—on historical transaction datasets. This will allow for empirical comparison of accuracy, responsiveness, and usability. Depending on results, we may later recommend a more advanced architecture.
-There is a draft plan to implement and evaluate both models—online SGD and RNNs—on historical transaction datasets. This will allow for empirical comparison of accuracy, responsiveness, and usability. Depending on results, we may later recommend a more advanced architecture.
+There is a draft plan to implement and evaluate both models (online SGD and RNNs) on historical transaction datasets. This will allow for empirical comparison of accuracy, responsiveness, and usability. Depending on results, we may later recommend a more advanced architecture.
-There is a draft plan to implement and evaluate both models—online SGD and RNNs—on historical transaction datasets. This will allow for empirical comparison of accuracy, responsiveness, and usability. Depending on results, we may later recommend a more advanced architecture.
+There is a draft plan to implement and evaluate both models (online SGD and RNNs) on historical transaction datasets. This will allow for empirical comparison of accuracy, responsiveness, and usability. Depending on results, we may later recommend a more advanced architecture.
+
+## Credits
+
+- This proposal is a part of Salaheldin's thesis research project, which is supervised and directed by @vekkiokonio .
+- @roman1e2f5p8s is currently working on in-node gas price feedback.
+- @bingyanglin and @cyberphysic4l suggested the usage of RNNs.
+- @iotaledger/research have been continuously providing feedback and suggestions to improve the proposal.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).