Skip to content

Commit 943edbb

Browse files
marcos-iovmarcos-iov
authored
Bridge method getEstimatedFeesForNextPegOutEvent improvements and new parameterized method (#540)
* Add RSKIP540 * Minor refactors and rewording to RSKIP540
1 parent b92c124 commit 943edbb

File tree

2 files changed

+126
-0
lines changed

2 files changed

+126
-0
lines changed

‎IPs/RSKIP540.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
rskip: 540
3+
title: Bridge method `getEstimatedFeesForNextPegOutEvent` improvements and new parameterized method
4+
created: 04-DEC-25
5+
author: MI
6+
purpose: Usa
7+
layer: Core
8+
complexity: 1
9+
status: Draft
10+
description:
11+
---
12+
13+
|RSKIP |540 |
14+
| :------------ |:-------------|
15+
|**Title** |Bridge method `getEstimatedFeesForNextPegOutEvent` improvements and new parameterized method |
16+
|**Created** |04-DEC-25 |
17+
|**Author** |MI |
18+
|**Purpose** |Usa |
19+
|**Layer** |Core |
20+
|**Complexity** |1 |
21+
|**Status** |Draft |
22+
23+
## Abstract
24+
25+
This RSKIP proposes improvements to the `getEstimatedFeesForNextPegOutEvent()` Bridge method and introduces a new method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)` that allows users to estimate fees for a specific peg-out amount. The improvement changes how the extra peg-out output is calculated in the fee estimation, using the minimum peg-out value. Note that these methods return estimates based on the current state of the Bridge and are not guaranteed to match the actual fees charged when the peg-out event occurs.
26+
27+
## Motivation
28+
29+
As described in RSKIP271 [[1]](#references) and RSKIP385 [[2]](#references), the `getEstimatedFeesForNextPegOutEvent()` method was created to allow users to estimate peg-out fees. This method builds a peg-out transaction using the available UTXOs in the Bridge and adds an extra peg-out request to represent the hypothetical user request.
30+
31+
Currently, the implementation uses 1 BTC as the amount for this hypothetical peg-out request. This value may not accurately represent typical user transactions, especially for smaller peg-outs. Using the minimum peg-out value instead provides a more conservative and realistic fee estimation that works for all valid peg-out amounts, ensuring users receive accurate estimates regardless of the amount they intend to peg-out.
32+
33+
Additionally, users currently cannot estimate fees for a specific peg-out amount they intend to perform. A new method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)` would allow users to query the estimated fees for their specific peg-out amount, providing better user experience and more accurate fee predictions. It is important to note that these estimates are based on the current state of the Bridge and may differ from actual fees due to changes in UTXO availability, peg-out requests state, or fee configuration.
34+
35+
## Specification
36+
37+
### 1. Modification to `getEstimatedFeesForNextPegOutEvent()`
38+
39+
The method `getEstimatedFeesForNextPegOutEvent()` should be modified so that when building the peg-out transaction and adding the extra hypothetical peg-out request, it uses the minimum peg-out value instead of 1 BTC.
40+
41+
The method signature remains unchanged:
42+
```solidity
43+
function getEstimatedFeesForNextPegOutEvent() public view returns (uint256);
44+
```
45+
46+
**Current behavior:**
47+
- The method builds a peg-out transaction using available UTXOs in the Bridge and current peg-out requests
48+
- It adds an extra peg-out request for 1 BTC to represent the hypothetical user request
49+
- Returns the estimated fees for this transaction
50+
51+
**New behavior:**
52+
- The method builds a peg-out transaction using available UTXOs in the Bridge and current peg-out requests
53+
- It adds an extra peg-out request for the minimum peg-out value (as defined in RSKIP219 [[3]](#references)) instead of 1 BTC
54+
- Returns the estimated fees for this transaction
55+
56+
### 2. New method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)`
57+
58+
A new method is added that allows users to estimate fees for a specific peg-out amount. This method builds a peg-out transaction similar to `getEstimatedFeesForNextPegOutEvent()` but uses the provided `pegOutAmountInWeis` parameter for the hypothetical peg-out request.
59+
60+
**Method signature:**
61+
```solidity
62+
function getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis) public view returns (uint256);
63+
```
64+
65+
**Behavior:**
66+
- This method builds a peg-out transaction using available UTXOs in the Bridge and current peg-out requests
67+
- It adds an extra peg-out request using the provided `pegOutAmountInWeis` parameter as the amount
68+
- Returns the estimated fees for this transaction
69+
- The `pegOutAmountInWeis` parameter must be expressed in weis
70+
71+
**Validation:**
72+
- The `pegOutAmountInWeis` parameter must be greater than or equal to the minimum peg-out value as defined in RSKIP219 [[3]](#references)
73+
- If the validation fails, the method should revert with an appropriate error message
74+
75+
### Important Note on Fee Estimation Accuracy
76+
77+
**The fees returned by both methods are estimates and are not guaranteed to match the actual fees charged when the peg-out event occurs.**
78+
79+
Several conditions may change between the time the estimation is made and when the actual peg-out transaction is created, which can affect the final fee cost:
80+
81+
- **New peg-out requests**: Other users may add peg-out requests to the queue, changing the number of outputs in the transaction
82+
- **Fee per KB changes**: The fee per KB value configured in RSK may be updated, affecting the transaction fee calculation
83+
- **UTXO availability**: The specific UTXOs available at estimation time may differ from those available when the peg-out event is executed
84+
85+
Users and applications should be aware that the estimated fees are based on the current state of the Bridge at the time of the call and may differ from the actual fees charged. The estimates should be used as a guide rather than a guarantee.
86+
87+
## Rationale
88+
89+
### Using Minimum Peg-out Value
90+
91+
Using the minimum peg-out value instead of 1 BTC for the hypothetical peg-out request in `getEstimatedFeesForNextPegOutEvent()` provides several benefits:
92+
- **More realistic estimates**: The minimum peg-out value better represents typical user transactions, especially for smaller amounts
93+
- **Conservative approach**: Using the minimum ensures the fee estimate works for all valid peg-out amounts
94+
- **Better UX**: Users performing small peg-outs will receive more accurate fee estimates
95+
96+
### New Method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)`
97+
98+
The new method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)` addresses the limitation where users cannot estimate fees for their specific peg-out amount. This provides:
99+
- **Better accuracy**: Users can get fee estimates tailored to their specific transaction amount
100+
- **Improved UX**: Users can compare fees for different peg-out amounts before submitting their request
101+
- **Flexibility**: Enables applications and wallets to provide more accurate fee predictions to users
102+
103+
## Backwards Compatibility
104+
105+
This change is a hard fork and therefore all full nodes must be updated.
106+
107+
The modification to `getEstimatedFeesForNextPegOutEvent()` changes its behavior but maintains the same method signature, so existing contracts and applications calling this method will continue to work, though they will receive different (more accurate) fee estimates.
108+
109+
The new method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)` is an addition and does not affect existing functionality.
110+
111+
## Security Considerations
112+
113+
No new security issues were identified related to this RSKIP. The new method `getEstimatedFeesForPegOutAmount(uint256 pegOutAmountInWeis)` includes validation to ensure the peg-out amount meets the minimum requirements, preventing invalid fee calculations.
114+
115+
Applications and users should be aware that the fee estimates returned by these methods are not guaranteed and may differ from actual fees due to changing conditions (UTXO availability, peg-out requests, fee configuration) between estimation and execution. This is expected behavior and not a security issue, but applications should handle potential fee discrepancies appropriately.
116+
117+
## References
118+
119+
[1] [RSKIP271](https://github.com/rsksmart/RSKIPs/blob/master/IPs/RSKIP271.md): Peg-out batching functionality
120+
[2] [RSKIP385](https://github.com/rsksmart/RSKIPs/blob/master/IPs/RSKIP385.md): Bridge method `getEstimatedFeesForNextPegOutEvent` improvement
121+
[3] [RSKIP219](https://github.com/rsksmart/RSKIPs/blob/master/IPs/RSKIP219.md): New minimum values for peg-in and peg-outs
122+
123+
### Copyright
124+
125+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,7 @@ You can find an easily browseable version of this information [here](https://ips
249249
| 529 |[New storage cells in Bridge native contract for base and super events info](IPs/RSKIP529.md)| 26-AUG-2025 | MI | Sca | Core | 1 | Draft |
250250
| 535 |[Add the `baseEvent` field to the Block header extension](IPs/RSKIP535.md)| 08-OCT-2025 | SDL | Sca | Core | 1 | Draft |
251251
| 536 |[Additional methods for BlockHeader precompiled contract](IPs/RSKIP536.md)| 10-OCT-2025 | MI | Usa | Core | 1 | Draft |
252+
| 540 |[Bridge method `getEstimatedFeesForNextPegOutEvent` improvements and new parameterized method](IPs/RSKIP540.md)| 04-DEC-2025 | MI | Usa | Core | 1 | Draft |
252253

253254
(*) Under evaluation to be implemented in the next reference client release
254255

0 commit comments

Comments
 (0)