Amendment Idea: Stop Orders

[mvadari]

  title: Stop Orders
  description: DEX stop-loss and stop-limit orders
  created: 2025-10-02
  author: Mayukha Vadari (@mvadari)
  status: Idea
  category: Amendment

Stop Orders

Abstract

Trading on the XRP Ledger currently lacks native support for conditional orders, such as stop-loss or stop-limit orders. Traders must rely on off-ledger solutions or manual monitoring, which exposes them to execution risk and reduces the reliability of decentralized trading. Introducing on-chain stop orders addresses these gaps while keeping the ledger fully deterministic and secure.

1. Overview

We propose:

• Modifying the Offer ledger entry
• Modifying the DirectoryNode ledger entry
• Modifying the OfferCreate transaction
• Creating the OfferModify transaction
• Modifying the book_offers RPC

This feature will require an amendment, tentatively titled StopOrder.

2. Ledger Entry: Offer

The Offer object tracks an offer placed on the CLOB DEX. This object type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.

2.1. Fields

As a reference, here are the existing fields for the Offer object.

Field Name	Constant?	Required?	Default Value	JSON Type	Internal Type	Description
Account	Yes	Yes	N/A	string	AccountID	The address of the account that owns this offer.
AdditionalBooks	No	No	N/A	array	STArray	An additional list of order book directories that this offer belongs to. Currently this field only applicable to hybrid offers.
BookDirectory	Yes	Yes	N/A	string	Hash256	The ID of the offer directory that links to this offer.
BookNode	Yes	Yes	N/A	string	UInt64	A hint indicating which page of the offer directory links to this entry, in case the directory consists of multiple pages.
DomainID	Yes	Yes	N/A	string	Hash256	The domain that the offer must be a part of.
Expiration	Yes	No	N/A	number	UInt32	Indicates the time after which this offer is considered unfunded.
LedgerEntryType	Yes	Yes	Offer	string	UInt16	The value 0x006F, mapped to the string Offer, indicates that this is an offer entry.
OwnerNode	Yes	Yes	N/A	string	UInt64	A hint indicating which page of the owner directory links to this entry, in case the directory consists of multiple pages.
PreviousTxnID	No	Yes	N/A	string	Hash256	The identifying hash of the transaction that most recently modified this entry.
PreviousTxnLgrSeq	No	Yes	N/A	number	UInt32	The ledger index that contains the transaction that most recently modified this object.
Sequence	Yes	Yes	N/A	number	UInt32	The Sequence value of the OfferCreate transaction that created this offer. Used in combination with the Account to identify this offer.
TakerPays	No	Yes	N/A	object	Amount	The remaining amount and type of currency requested by the offer creator.
TakerGets	No	Yes	N/A	object	Amount	The remaining amount and type of currency being provided by the offer creator.

This spec proposes the following additions:

Field Name	Constant?	Required?	Default Value	JSON Type	Internal Type	Description
StopPrice	Yes	Yes	N/A	string	Number	The price that the stop offer should be triggered at. The presence of this field indicates a stop offer. The price should be in the currency specified in TakerGets.

2.2. Flags

Offer entries can have the following flags combined into the Flags field:

Flag Name	Flag Value	Description
lsfPassive	0x00010000	The offer was placed as passive. This has no effect after the offer is placed into the ledger.
lsfSell	0x00020000	The offer was placed as a sell offer. This has no effect after the offer is placed in the ledger, because tfSell only matters if you get a better rate than you asked for, which can only happen when the offer is initially placed.
lsfHybrid	0x00040000	The offer was placed as a hybrid offer, which means it is listed in a permissioned DEX and the open DEX.

This spec proposes the following additions:

Flag Name	Flag Value	Description
lsfStopLimit	0x00080000	Whether the stop offer is a limit offer. If it is not enabled on a stop offer, it is a stop market offer.
lsfStopBuy	0x00100000	Whether the stop offer is a stop buy offer. If it is not enabled on a stop offer, it is a stop sell offer.

3. Ledger Entry: DirectoryNode

The Offer object tracks an offer placed on the CLOB DEX.

The DirectoryNode ledger entry type provides a list of links to other entries in the ledger's state data. A single conceptual Directory takes the form of a doubly linked list, with one or more DirectoryNode entries each containing up to 32 IDs of other entries. The first DirectoryNode entry is called the root of the directory, and all entries other than the root can be added or deleted as necessary.

This object type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.

There are three types of directories: owner directories (for the objects an account owns), offer directories (for offers in the orderbook), and NFT offer directories (for NFT offers).

The proposed modification allows for another type of directory: conditional offer directories. The offers in this directory are sorted by their "stop price", not the price of the offer.

3.1. Fields

As a reference, here are the existing fields for the DirectoryNode object.

Field Name	Constant?	Required?	Default Value	JSON Type	Internal Type	Description
DomainID	No	No	N/A	string	Hash256	The domain that the offer directory is a part of.
Flags	No	Yes	0	number	UInt32	A bit-map of boolean flags enabled for this object. Currently, the protocol defines no flags for DirectoryNode objects. The value is always 0.
Indexes	No	Yes	N/A	array	Vector256	The contents of this directory: an array of IDs of other objects.
IndexNext	No	No	N/A	number	UInt64	If this directory consists of multiple pages, this ID links to the next object in the chain, wrapping around at the end.
IndexPrevious	No	No	N/A	number	UInt64	If this directory consists of multiple pages, this ID links to the previous object in the chain, wrapping around at the beginning.
LedgerEntryType	Yes	Yes	DirectoryNode	string	UInt16	The value 0x0064, mapped to the string DirectoryNode, indicates that this object is part of a directory.
RootIndex	No	Yes	N/A	string	Hash256	The ID of root object for this directory.
TakerGetsCurrency	No	Yes	N/A	string	Hash160	The currency code of the TakerGets amount from the offers in this directory.
TakerGetsIssuer	No	Yes	N/A	string	Hash160	The issuer of the TakerGets amount from the offers in this directory.
TakerPaysCurrency	No	Yes	N/A	string	Hash160	The currency code of the TakerPays amount from the offers in this directory.
TakerPaysIssuer	No	Yes	N/A	string	Hash160	The issuer of the TakerPays amount from the offers in this directory.

This spec does not propose any changes to the fields.

3.2. Object ID

3.2.1. Background: Current Offer Directory ID

There are three different formulas for creating the ID of a DirectoryNode, depending on which of the following the DirectoryNode represents:

• The first page (also called the root) of an Owner or NFT Offer directory
• The first page of an Offer directory
• Later pages of either type

The first page of an Offer directory has a special ID: the higher 192 bits define the order book, and the remaining 64 bits define the exchange rate of the offers in that directory. (The ID is big-endian, so the book is in the more significant bits, which come first, and the quality is in the less significant bits which come last.) This provides a way to iterate through an order book from best offers to worst. Specifically: the first 192 bits are the first 192 bits of the SHA-512Half of the following values, concatenated in order:

• The Book directory space key (0x0042)
• The 160-bit currency code from the TakerPaysCurrency
• The 160-bit currency code from the TakerGetsCurrency
• The AccountID from the TakerPaysIssuer
• The AccountID from the TakerGetsIssuer
• The DomainID of the orderbook, if applicable

The lower 64 bits of an Offer directory's ID represent the TakerPays amount divided by TakerGets amount from the offer(s) in that directory as a 64-bit number in the XRP Ledger's internal amount format.

If the DirectoryNode is not the first page in the directory, it has an ID that is the SHA-512Half of the following values, concatenated in order:

• The DirectoryNode space key (0x0064)
• The ID of the root DirectoryNode
• The page number of this object. (Since 0 is the root DirectoryNode, this value is an integer 1 or higher.)

3.2.2. Proposed Change

This proposal involves having a separate set of directories that hold conditional offers (just stop for now, but can maybe be extended in other ways - I'm not a trading expert, so idk)

The object ID for the conditional offer directories will be as follows:

• The Conditional Offer directory space key, defined during implementation
• The 160-bit currency code from the TakerPaysCurrency
• The 160-bit currency code from the TakerGetsCurrency
• The AccountID from the TakerPaysIssuer
• The AccountID from the TakerGetsIssuer
• The DomainID of the orderbook, if applicable.

4. Transaction: OfferCreate

The OfferCreate transaction creates an offer on the CLOB DEX. This transaction type already exists on the XRPL, but is being extended as a part of this spec to also support permissioned DEX domains.

4.1. Fields

As a reference, here are the existing fields for the OfferCreate transaction.

Field Name	Required?	JSON Type	Internal Type	Description
DomainID		string	Hash256	The domain that the offer must be a part of.
Expiration		number	UInt32	Time after which the offer is no longer active, in seconds since the Ripple Epoch.
OfferSequence		number	UInt32	An offer to delete first, specified in the same way as OfferCancel.
TakerGets	✔️	string	Amount	The amount and type of currency being sold.
TakerPays	✔️	string	Amount	The amount and type of currency being bought.

This spec proposes a new field:

Field Name	Required?	JSON Type	Internal Type	Description
StopPrice	Yes	string	Number	The price that the stop offer should be triggered at. The presence of this field indicates a stop offer. The price should be in the currency specified in TakerGets.

4.2. Flags

This spec proposes additional flags:

Flag Name	Flag Value	Description
tfStopLimit	0x00200000	Whether the stop offer is a limit offer. If it is not enabled on a stop offer, it is a stop market offer.
tfStopBuy	0x00400000	Whether the stop offer is a stop buy offer. If it is not enabled on a stop offer, it is a stop sell offer.

4.3. Failure Conditions

The existing set of failure conditions for OfferCreate will continue to exist.

4.4. State Changes

The existing set of state changes for OfferCreate will continue to exist.

In addition:

• Whenever an offer is crossed, the tip of the "conditional offer directory" is checked. If the price at the tip has been reached, then the stop offer(s) at the tip will be moved over to the actual book directory. It will then act as a normal offer.

5. OfferModify

Allows you to modify an offer after its creation (including stop price for a stop offer)

6. RPC: book_offers

Probably need some changes here to accommodate this new feature

n+1. Open Questions

• Performance is the big question - need to ensure that you can't block a book/seriously degrade performance of the DEX by placing a bunch of dust stop offers at a certain point.
• Flags may not be necessary - you may be able to infer that from the offer details

Appendix

Appendix A: Alternate Designs

• Putting the offers straight into the offer directory, but having them be dormant
  • A malicious actor could potentially degrade DEX performance a ton by placing a bunch of stop orders near the tip of the book that you have to iterate past
• Instead of adding a separate directory for stop offers, you could have another set of pointers in the existing directory
• Put the dormant offers on the opposite side of the book