System Idea: Stop-Loss Orders

[dangell7]

  title: Stop-Loss Orders
  description: Enables passive order submission triggered by price conditions
  author: Denis Angell (@angell_denis)
  status: Idea
  category: System
  created: 2025-09-22

Stop-Loss Orders

1. Abstract

This specification introduces a stop-loss order system for the XRP Ledger, allowing users to submit pre-signed transactions that are stored off-chain on individual nodes and executed automatically when specified price conditions are met. The system supports four order types: stop-loss sells, stop-loss buys, take-profit sells, and take-profit buys. Orders must use tickets for execution to avoid sequence number conflicts.

Important: Stop-loss orders are stored locally on individual nodes and are not replicated across the network. Users must submit orders to specific nodes they trust to monitor and execute their orders.

2. Motivation

Current XRPL trading requires active monitoring and manual order submission. Traders cannot protect positions or automate entry/exit strategies without constant oversight or third-party services. This creates disadvantages for retail traders and increases systemic risk during volatile market conditions.

Stop-loss orders are a fundamental trading tool in traditional markets, providing:

• Risk management through automated position closure
• Entry strategies via stop-buy orders
• Profit-taking automation
• Reduced need for constant market monitoring

3. Specification

3.1. System Architecture

3.1.1. Node-Local Storage

Stop-loss orders are stored locally on individual rippled nodes using LMDB (Lightning Memory-Mapped Database). This design means:

• Orders are not validated or stored by the network consensus
• Orders exist only on the node where submitted
• Node failure means loss of pending orders
• Users must trust the node operator to execute orders

The database maintains:

• Main order storage indexed by transaction hash
• Price indices for each stop type to enable efficient triggering
• Market-specific organization to monitor only relevant order books

3.1.2. Order Types

Four distinct stop order types are supported:

Type	Trigger Condition	Use Case
STOP_LOSS_SELL	Market price ≤ stopPrice	Limit losses on long positions
STOP_LOSS_BUY	Market price ≥ stopPrice	Enter positions on upward momentum
TAKE_PROFIT_SELL	Market price ≥ stopPrice	Lock in profits on long positions
TAKE_PROFIT_BUY	Market price ≤ stopPrice	Enter positions at target prices

3.2. Order Lifecycle

3.2.1. Submission

Users create and sign an OfferCreate transaction using a ticket, then submit it via the submit_passive RPC with stop parameters. The node validates the transaction structure, verifies ticket usage, and stores the order in its local database indexed by market and price.

3.2.2. Monitoring

After each validated ledger, the system checks current market prices by examining the order book tops for markets with stored orders. The system uses BookDirs to efficiently iterate through order book offers and calculate market prices from the best available offers.

3.2.3. Execution

When market conditions meet trigger criteria, the pre-signed transactions are submitted to the network through the standard transaction processing pipeline. Successfully submitted orders are removed from the database to prevent re-submission.

3.3. Price Determination

Market prices are calculated from actual order book data:

• For XRP to IOU pairs: Price = IOU amount / XRP amount (in XRP units)
• For IOU to IOU pairs: Price = Pay amount / Get amount
• Prices are derived from the best available offers in the order book

This ensures orders trigger based on executable prices rather than theoretical values.

3.4. API Specification

3.4.1. submit_passive RPC

Accepts pre-signed OfferCreate transactions with stop conditions.

Request Parameters:

• tx_blob (required): Hex-encoded signed transaction
• stop_price (required): Numeric trigger price
• stop_type (required): One of "stop_loss_sell", "stop_loss_buy", "take_profit_sell", "take_profit_buy"

Response:

• engine_result: "tesSUCCESS" if stored, "tecDUPLICATE" if order already exists
• tx_hash: Transaction hash of the stored order

4. Rationale

4.1. Node-Local Design

Stop orders are stored locally rather than on-ledger because:

• Prevents ledger bloat from thousands of inactive orders
• No consensus needed for user-specific orders
• Allows different nodes to offer different service levels
• Preserves trading strategy privacy until execution

4.2. Ticket Requirement

Tickets are mandatory because orders may trigger simultaneously when market conditions change rapidly. Regular sequence numbers would cause transaction failures when orders execute out of sequence.

4.3. Market-Based Organization

Orders are indexed by market (currency pairs) to avoid checking irrelevant order books. Only markets with active stop orders are monitored, improving efficiency.

4.4. Trust Model

This design requires users to trust their chosen node operator to:

• Keep the node running continuously
• Execute orders when conditions are met
• Not front-run or manipulate orders
• Maintain order confidentiality

This mirrors traditional finance where traders trust brokers with stop-loss orders.

5. Backwards Compatibility

This feature is fully backwards compatible:

• No changes to existing transaction types or ledger objects
• New RPC endpoint doesn't affect existing APIs
• Non-participating nodes can process triggered transactions normally
• Network consensus is unaffected

6. Security Considerations

6.1. Node Operator Risks

• Operators have access to all stop orders on their node
• Potential for front-running if operator is malicious
• Orders lost if node database is compromised

6.2. Database Security

• LMDB provides ACID guarantees preventing corruption
• Database size limits prevent DoS attacks
• Efficient indexing prevents performance degradation

6.3. Transaction Security

• Only pre-signed transactions accepted (no key storage)
• Signature validation prevents forgery
• Ticket usage prevents replay attacks
• Transaction validity checked before submission

6.4. Market Integrity

• Orders execute at actual market prices from the order book
• No external price feeds or oracles required
• No guarantee of execution at exact stop price (slippage possible)

7. Future Considerations

7.1. Potential Enhancements

• Order replication between trusted nodes for redundancy
• Encrypted order storage for additional privacy
• Order expiration timestamps
• Cancel functionality via additional RPC

7.2. Network-Wide Implementation

A future amendment could move stop orders on-chain with:

• New ledger object type for stop orders
• Consensus rules for trigger conditions
• Automatic execution by validators
• Global order book visibility

8. Appendix

8.1. FAQ

Q: Why aren't stop orders visible to all nodes?
A: They're stored locally to prevent ledger bloat and maintain trading privacy.

Q: What happens if my node goes offline?
A: Orders won't be monitored while offline. Monitoring resumes when the node restarts.

Q: Can I submit the same order to multiple nodes?
A: Technically possible but risks double-execution if both nodes trigger simultaneously.

Q: How do I know which nodes support stop orders?
A: Node operators would advertise this feature. No on-chain discovery mechanism exists.

Q: What's the performance impact?
A: Minimal - order checking happens after ledger validation using efficient indexed lookups.

8.2. Reference Implementation

A current implementation exists here: https://github.com/Transia-RnD/rippled/tree/stop-loss