Skip to content

Commit a68a77f

Browse files
mvadarimvadari
committed
Add XLS-76d: 0076 XLS-76d: Min Incoming Amount (XRPLF#355)
* Add XLS-76 Min Incoming Amount
1 parent 9d6ec94 commit a68a77f

File tree

1 file changed

+177
-0
lines changed

1 file changed

+177
-0
lines changed

‎XLS-0076-min-incoming-amount/README.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
<pre>
2+
xls: 76
3+
title: Min Incoming Amount
4+
description: Allow an account holder to specify a minimum amount of XRP that can be received in a Payment
5+
author: Kris Dangerfield (@xrpl365)
6+
created: 2024-08-23
7+
status: Deprecated
8+
category: Amendment
9+
</pre>
10+
11+
# XLS-76d - Min Incoming Amount
12+
13+
```
14+
Title: Min Incoming Amount
15+
Revision: 3
16+
Author: Chris Dangerfield @xrpl365
17+
Affiliation: XRPL 365 Ltd
18+
19+
Attribution: Khaled Elawadi @khaledelawadi
20+
```
21+
22+
## Abstract
23+
24+
Based on an original idea by Khaled Elawadi @khaledelawadi, this proposal introduces a new feature to the XRP Ledger that allows an account holder to specify a minimum amount of XRP that can be received.
25+
26+
This feature is designed to prevent what is commonly referred to as "dusting," where small amounts of XRP are sent to an account, potentially cluttering an account with unwanted transactions.
27+
28+
## Rationale
29+
30+
Dusting attacks involve sending tiny amounts of value to a large number of wallets. Currently, XRP Ledger accounts can receive any amount of XRP, regardless of how small. While this might seem harmless, dusting can lead to cluttered transaction histories, potential privacy risks, and significant ledger memo spam.
31+
32+
The Min Incoming Amount feature aims to mitigate these issues by allowing account owners to set a threshold for incoming transactions. Any transaction below the specified minimum amount will be automatically rejected, ensuring that the account only receives transactions of value that meet or exceed the defined threshold.
33+
34+
## Amendment
35+
36+
The proposed change introduces a new field on the `AccountRoot` ledger object called `sfIncomingMin`, which is of type `SF_AMOUNT`.
37+
38+
This field allows users to define the minimum amount of XRP that their account is willing to accept.
39+
40+
## New Field on `AccountRoot`
41+
42+
| Field | Type | Required | Description |
43+
| :-------------- | :----- | :------- | :--------------------------------------------------------------------------- |
44+
| `sfIncomingMin` | Amount | | Specifies the minimum amount of XRP (in drops) that the account will accept. |
45+
46+
## Updating the `AccountSet` Transaction
47+
48+
To set, update or remove the `sfIncomingMin` field, users would use the existing `AccountSet` transaction, so it would be updated to store the new field.
49+
50+
Omitting the optional field would do nothing, it would not change any setting that currently exists.
51+
52+
Setting `sfIncomingMin` to zero would remove it from the object, essentially disabling the feature.
53+
54+
#### Failure Conditions
55+
56+
- If amount != XRP amount
57+
- ⁠If amount < 0
58+
- ⁠If incoming min is NOT set and amount is 0
59+
60+
#### State Changes
61+
62+
- Updates the Field `sfIncomingMin` on AccountRoot Ledger Entry.
63+
64+
## Examples
65+
66+
Setting a Minimum Incoming Amount:
67+
68+
```
69+
{
70+
"TransactionType": "AccountSet",
71+
"Account": "rExampleAccountID",
72+
"IncomingMin": "5000000" // 5 XRP in drops
73+
}
74+
```
75+
76+
Removing the Minimum Incoming Amount:
77+
78+
```
79+
{
80+
"TransactionType": "AccountSet",
81+
"Account": "rExampleAccountID",
82+
"IncomingMin": "0" // Removes field from the object and disables the feature
83+
}
84+
```
85+
86+
## Implementation
87+
88+
```
89+
IF Transaction IS Payment
90+
AND Amount IS "XRP"
91+
AND DestinationAccount HAS IncomingMin
92+
AND IncomingMin GREATER THAN Amount
93+
THEN
94+
REJECT TRANSACTION
95+
ELSE
96+
// NORMAL FLOW
97+
END IF
98+
```
99+
100+
## Flows
101+
102+
#### Flow 1: Setting a Minimum Incoming Amount
103+
104+
**Scenario:** Sarah wants to prevent her account from receiving small, insignificant XRP transactions (commonly known as dusting).
105+
106+
1. Sarah performs an AccountSet transaction and sets an IncomingMin of "500000" drops.
107+
2. Sarah's account now has protection against receiving a Payment less than 0.5 XRP.
108+
109+
#### Flow 2: Receiving a Transaction Greater than the Minimum Incoming Amount
110+
111+
**Scenario:** John, unaware of Sarah’s new setting, tries to send her 100 XRP as a token of appreciation.
112+
113+
1. John initiates a payment transaction of 100 XRP from his XRP wallet.
114+
2. The Payment is unaffected by the change Sarah made and the payment is received gratefully.
115+
116+
#### Flow 3: Receiving a Transaction Less than the Minimum Incoming Amount
117+
118+
**Scenario:** "Nasty Nick", a known duster, unaware of Sarah’s new setting, tries to send her 0.00001 XRP, along with a tricky memo.
119+
120+
1. Nick initiates a payment transaction of 0.00001 XRP from his XRP wallet.
121+
2. The Payment is rejected by the ledger when evaluating the incoming Amount vs Sarah's IncomingMin.
122+
3. Sarah's transaction history is unaffected and she never even knew what Nasty Nick tried to do.
123+
124+
#### Flow 4: Removing the Minimum Incoming Amount
125+
126+
**Scenario:** After some time, Sarah decides she no longer needs the minimum incoming amount restriction on her account.
127+
128+
1. Sarah performs an AccountSet transaction and sets an IncomingMin of "0" drops.
129+
2. The IncomingMin field is removed from her Account Root.
130+
3. Sarah's account is no longer protected.
131+
132+
#### Flow 5: Transaction Handling with Min Incoming Amount Set
133+
134+
**Scenario:** "Nasty Nick", is back, and once again he tries to send her 0.00001 XRP, along with a tricky memo.
135+
136+
1. Nick initiates a payment transaction of 0.00001 XRP from his XRP wallet.
137+
2. The Payment is accepted by the ledger because the protection Sarah once had has been removed.
138+
3. Sarah's transaction history now contains a new transaction from Nick, and a bunch of other dusters.
139+
140+
#### Flow 6: Setting a Minimum Incoming Amount with Incorrect Values
141+
142+
**Scenario:** Sarah wants to re-enable the protection on her account, after the nasty surprise from Nick.
143+
144+
1. Sarah performs an AccountSet transaction and sets an IncomingMin of "-500000" drops, an invalid value.
145+
2. The transaction is rejected with an error, and Sarah is informed that the value must be positive.
146+
3. Sarah decides to try again with a correct value - GO TO Flow 1.
147+
148+
## Considerations
149+
150+
**Backward Compatibility**
151+
The addition of the `sfIncomingMin` field will be optional. Accounts that do not set this field will continue to accept all incoming amounts as usual.
152+
153+
**Usability**
154+
The Min Incoming Amount feature is simple to configure and will be integrated seamlessly into existing wallet interfaces using the familiar `AccountSet` transaction type.
155+
156+
**Potential Misuse**
157+
While this feature prevents dusting, users should be cautious about setting the threshold too high, as it might prevent legitimate small transactions from being accepted.
158+
159+
**Partial Payments**
160+
Partial payments allow a sender to specify a maximum amount they are willing to spend, and the transaction delivers as much as possible of the destination amount, potentially less than the full amount specified by the sender. If a partial payment is made and the amount delivered is less than the specified `sfIncomingMin` threshold, this creates an edge-case where the tiny amount may be legitimate, yet be rejected. It makes sense for the `sfIncomingMin` to apply to the actual amount received, as this aligns with the goal of preventing dusting, but means the code will need to use the delivered_amount to prevent partial payments from being used as a work-around to this amendment.
161+
162+
**Effect on Reserves**
163+
If an account's balance marginally drops below the account reserve, this creates an edge-case where the user will not be able to receive a tiny amount as it is blocked by `sfIncomingMin` and being below the account reserve would mean they cannot perform an AccountSet to temporarily remove the limit. The only option would be to receive an amount greater than `sfIncomingMin` which in 99.9% of cases should not be problematic given the it would ideally be set at 1 XRP or less, however in a scenario where the limit was set artificially high...
164+
165+
**Maximum limit**
166+
This spec does not allow for a maximum value on the `sfIncomingMin` field. Adding such a limit may be seen as protecting a user from setting an overly high value, however on balance given the ease at which a limit can be reduced or even removed, it is felt that the arbitrary limit removes user choice.
167+
168+
**Account Locking - Reserve & No Maximum Limit.**
169+
There is an edge case where a user is not prevented from setting a very high limit and the account balance drops below the reserve creating a situation where the account would essentially be rendered unusable. If this edge-case were considered serious enough to require a solution, either a sensible maximum limit could be introduced OR an additional step on transaction rejection to check the account balance is not below the reserve. A maximum amount limit adds very minimal overhead to the amendment but does remove user choice. Testing for account balance would introduce a more intensive test that needs to be applied to every rejected transaction. On balance the arbitrary minimum does offer protection against the ege-case and does not conflict with fundamental principle of the proposal.
170+
171+
## Conclusion
172+
173+
The Min Incoming Amount feature provides a straightforward solution to the problem of dusting on the XRP Ledger.
174+
175+
By introducing the `sfIncomingMin` field on the `AccountRoot` ledger object and utilizing the existing `AccountSet` transaction for configuration, account holders gain the ability to reject small, potentially unwanted transactions.
176+
177+
This enhances account security and reduces clutter, making the XRP Ledger more user-friendly and secure.

0 commit comments

Comments
 (0)