Amendment Idea: Scheduled Transactions

[mvadari]

  title: Scheduled Transactions
  description: A feature allowing transactions to be scheduled in advance
  created: 2025-10-16
  author: Mayukha Vadari (@mvadari)
  status: Idea
  category: Amendment

Scheduled Transactions

1. Abstract

This specification introduces a new ledger object and associated transactions that allow users to schedule a transaction on-ledger for conditional execution in the future. This feature enables programmable, condition-based execution of XRPL transactions without requiring external custodianship or centralized automation services.

2. Motivation

Today, XRPL transactions must be submitted immediately for execution; there is no native way to defer or conditionally execute them. This limits users who want to automate workflows such as stop-loss orders, time-based payments, or delegated execution of transactions under custom rules.

This feature solves this by allowing transactions to be stored directly on-ledger, along with trigger conditions and incentives for relayers to execute them. Users gain confidence that their intent is committed and immutable, relayers are incentivized to monitor and execute them, and the ledger gains a clean, native mechanism for conditional automation.

3. Overview

This spec proposes:

• Creating the TransactionSaved ledger object
• Modifying the Ticket ledger object's flags
• Modifying the global transaction flags
• Creating the TransactionSave transaction
• Creating the TransactionExecute transaction
• Creating the TransactionCancel transaction

This feature will require an amendment, tentatively titled SavedTransaction.

3.1. Terminology

• User: The account creating the scheduled transaction.
• Relayer: The account executing the scheduled transaction on behalf of the user once its release conditions are present.
• Bounty: The (optional) reward the relayer receives for executing the scheduled transaction on time.
• Releasing a transaction: The previously-scheduled transaction is submitted, similar to Batch inner transactions.

3.2. Example Flows

3.2.1. Stop-Loss Order

1. Alice wants to sell 10,000 XRP if the price drops below $0.90.
2. She creates an OfferCreate transaction to sell the XRP on the DEX, wraps it in a TransactionSaved, attaches a WASM trigger that checks the XRPL DEX price, and sets an expiration of 30 days.
3. Alice also specifies a small bounty to incentivize execution.
4. When the price condition is met, a relayer triggers the TransactionSaved. The OfferCreate executes atomically, the bounty is paid to the relayer, and the TransactionSaved is deleted from the ledger.

3.2.2. Scheduled Payroll

1. Bob wants to send $1,000 to his employee at the end of each month.
2. He prepares a Payment transaction and stores it in a TransactionSaved with a simple time-based trigger (execute after November 1, 2025, 00:00 UTC).
3. A ticket is reserved during creation to ensure ordering of Bob’s future transactions.
4. On November 1, a relayer triggers the TransactionSaved. The Payment executes and the employee receives his salary.
5. If Bob cancels before the trigger date, the TransactionSaved and ticket reservation are both released.

Note: this is technically more easily done via escrow, but could theoretically be done via a scheduled transaction too, especially if the account doesn't have the funds at the time of scheduling the transaction.

4. Ledger Entry: TransactionSaved

4.1. Object ID

Hash of object key, Transaction/`TransactionHash

4.2. Fields

Field Name	Constant?	Required?	Default Value	JSON Type	Internal Type	Description
LedgerIndex	Yes	Yes	N/A	string	Hash256	The unique ID of the ledger object.
LedgerEntryType	Yes	Yes	TransactionSaved	string	UInt16	The ledger object's type (TransactionSaved).
Owner	Yes	Yes	N/A	string	AccountID	The account that bears the cost for the reserve of this object.
Transaction	Yes	No	N/A	object	STTx	The transaction that is being scheduled. Must be unsigned.
TransactionHash	Yes	No	N/A	string	UInt256	The unsigned hash of the transaction that is being scheduled.
TicketSequence	Yes	No	N/A	number	UInt32	The ticket sequence associated with this transaction. Should not be included if a Transaction is provided instead of a TransactionHash (since the information is available in the transaction).
ReleaseFunction	No	No	N/A	string	Blob	Compiled WebAssembly (WASM) code that must execute correctly for the transaction to be submitted.
ValidAfter	No	No	N/A	number	UInt32	The time after which the transaction is considered valid and may be submitted.
Expiration	No	No	N/A	number	UInt32	The time at which this transaction expires and can no longer be submitted.
Bounty	Yes	No	N/A	string or object	STAmount	The amount paid to the relayer upon successful execution.
OwnerNode	No	Yes	N/A	string	UInt64	A hint indicating which page of the owner's owner directory links to this object, 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.

4.2.1. TriggerFunction

The ABI of this function will be:

int32
release()

Where 0 or a negative number means the transaction will not be released, and a positive number means the transaction will be released.

4.3. Account Deletion

The TransactionSaved object is not a deletion blocker.

5. Ledger Entry: Ticket

New flag - lsfReserved - to indicate when a ticket is reserved for a TransactionSaved (so that it is not accidentally used for something else, thereby invalidating the saved transaction)

6. Transaction Common Fields

6.1. Flags

New tfTxSaved flag for transactions stored in TransactionSaved. This allows the transaction to be unsigned but still invalid.

7. Transaction: TransactionSave

7.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UInt16	The transaction type (TransactionSave).
Account	Yes	string	AccountID	The account sending the transaction.
Transaction	No	object	Transaction	The transaction to be sent when its release conditions occur.
TransactionHash	No	string	UInt256	The hash of the transaction to be sent when its release conditions occur.
TicketSequence	No	number	UInt32	The ticket sequence associated with this transaction. Should not be included if a Transaction is provided instead of a TransactionHash (since the information is available in the transaction).
ReleaseFunction	No	string	Blob	Compiled WebAssembly (WASM) code that must execute correctly for the transaction to be submitted.
ValidAfter	No	number	UInt32	The time after which the transaction is considered valid and may be submitted.
Expiration	No	number	UInt32	The time at which this transaction expires and can no longer be submitted.
Bounty	No	string or object	STAmount	The amount to be paid to the relayer upon successful execution.
Exactly one of Transaction or TransactionHash must be included. At least one of TriggerFunction and ValidAfter must be included.

7.2. Failure Conditions

• If Transaction is provided:
  • Transaction is invalid (fails preflight)
  • Account is not allowed to submit Transaction (i.e. Account is not equal to Transaction.Account or Transaction.Delegate)
  • TicketSequence is also provided.
  • Transaction does not have tfTxSaved enabled.
• If TransactionHash is provided:
  • TicketSequence is not provided.
• TriggerFunction is not valid WASM code.
• ValidAfter has already passed.
• Expiration has already passed.
• Bounty is an invalid amount (i.e. is negative)
• Account does not have the Bounty funds

7.3. State Changes

If the transaction is successful:

• A TransactionSaved object will be created.
• If TicketSequence or Transaction.TicketSequence is specified, lsfTicketReserved is enabled on that Ticket object.

8. Transaction: TransactionExecute

8.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UInt16	The transaction type (TransactionExecute).
Account	Yes	string	AccountID	The account sending the transaction.
TransactionHash	No	string	UInt256	The hash of the transaction to send. Must be included if the TransactionSaved object has a Transaction field.
Transaction	No	object	Transaction	The transaction to send. Must be included if the TransactionSaved object has a TransactionHash field.
ReleaseInput	No	string	Blob	A free-form, unvalidated blob of data that can be used as input to the WASM ReleaseFunction (i.e. off-chain validations.

8.2. Failure Conditions

• Both Transaction and TransactionHash are specified.
• There is no TransactionSaved object that corresponds with TransactionHash/Transaction.
• Transaction is specified and TransactionSaved.Transaction is also specified.
• TransactionHash is specified and TransactionSaved.TransactionHash is already specified.
• Transaction is specified and does not have tfTxSaved enabled.
• The ReleaseFunction on the TransactionSaved object does not succeed.
• The TransactionSaved.Owner no longer has the funds to pay the Bounty (tecUNFUNDED).
• The TransactionSaved.Owner no longer has permission to submit Transaction (i.e. the delegation was taken away).

8.3. State Changes

• The transaction in either TransactionSaved.Transaction or TransactionExecute.Transaction is executed atomically as if it had been sent directly from the account (similar to how Batch inner transactions are processed atomically).
  • Note: that transaction may still fail.
• If a Bounty is provided in the TransactionSaved, that amount is transferred from the TransactionSaved.Owner to the TransactionExecute.Account.

9. Transaction: TransactionCancel

9.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UInt16	The transaction type (TransactionExecute).
Account	Yes	string	AccountID	The account sending the transaction.
TransactionHash	No	string	UInt256	The hash of the scheduled transaction to cancel.

9.2. Failure Conditions

• There is no TransactionSaved object that corresponds with TransactionHash/Transaction.

9.3. State Changes

• The relevant TransactionSaved object is deleted.

10. Security

• The transaction is consented to upon creation in TransactionSave.
• No double-spending of bounty or tickets since the TransactionSaved object is single-use.
• Ticket reservation ensures that the transaction can't become invalid for sequence number reasons.

11. Rationale

By separating the definition of a transaction from its execution, the ledger enables workflows that would otherwise require complex off-ledger orchestration, such as conditional execution, multi-actor coordination, or repeated actions with stable semantics.

One major decision was to allow either a hash of the transaction data on-ledger or the actual transaction. This allows multiple usecases, both those that require the transaction remain secret and those that anyone can release.

The introduction of a bounty mechanism was chosen as a lightweight incentive structure to encourage third parties (relayers) to execute scheduled transactions on behalf of the originator. This can be used to avoid reliance on external coordination or trust between accounts, and leverages the ledger’s native accounting to directly reward executors.

In other ecosystems, comparable features appear as “meta-transactions” or “intents” (e.g., in Ethereum’s ERC-4337 account abstraction or StarkNet’s transaction batching). These systems often include relayer markets, bundlers, or fee-sponsorship models. This spec deliberately takes a narrower approach: it does not change fee logic, multisignature, or transaction semantics. Instead, it extends the ledger’s object model in a way that feels natural to the XRPL: declarative, minimal, and enforceable by consensus rules.

11.1. Alternate Designs

The best usecase of this design will be for trading on the DEX and various kinds of stop orders. So one alternate design would be to narrow the scope of this to just offers, which could simplify the implementation greatly, since the offer could be directly placed instead of via a separate transaction. But it has a tradeoff of greatly limiting the scope of what is doable with the design.

n+1. Open Questions

• Should the Bounty be modifiable?
• Should there be more hardcoded release conditions - e.g. for stop orders or to specify who the accounts that can release are?
• Should you be able to make an uncancellable transaction?

Appendix

Appendix A: FAQ

A.1: Is this compatible with On-Chain Multisign?

It should be.

[KhaledElawadi]

I like these Scheduled Transactions.

However, I do have a number of questions mainly for clarity and some comments to make:

1. Who are these "relayers", why must they be incentived and if human then why are they even required in the scheduling/payment process?

[mvadari]

Fee escalation is more of a safeguard than something that tends to be high regularly. We need to design to encourage that. Fee escalation has only been high for longer periods of time twice in the past few years.

You can also use the bounty to encourage people to still relay your transaction even when fees are high - if the bounty is higher than the fee, it will likely still be worth it for them.

Worst case scenario, you relay your own transaction. The bounty system just encourages other people to do it more promptly.

[KhaledElawadi]

The idea of scheduling a Direct Debit is so you can automate your payments and basically forget all about the various due dates.

It has to be automated and totally reliable.

Can you imagine folks getting kicked from their residency because their rent wasn't paid on time?

"The network fees must have been too high this week"...somehow doesn't cut it.

[KhaledElawadi]

Another thing to consider is we currently have over 6 Million+ account holders and if like me at least 5 Direct Debits which include, phone, internet, utility bills and aditional subscriptions.

Any prepaid bounty payment + network fee might have to include a slippage tolerance on the network fee of say 1 XRP with the balance being refunded.
Problem then is if the network fee is between 0.5 - 1 XRP there would be nothing to refund and hence be a total cost effectively rounded up of 1 XRP.

[mvadari]

You don't need to use the bounty system. You can also directly pay a third party for better guarantees (equivalent to using your bank for direct deposits).

You can't avoid fee escalation however you design, even if you design something more automatic. This design just ensures that your transaction won't automatically fail and you have mitigation options.

[KhaledElawadi]

Third parties now?

It will automatically fail though if it's unfunded and you don't have the necessary assets available at the time it's executed.

I'm not trying to avoid the fee escalation simply trying to account for it if the bounty + network fee is prepaid in advance?

[KhaledElawadi]

Scheduled Payments is by far one of the most useful must have functions on the XRPL.

Is it possible to expand the Stop-Loss option to a Trailing Stop Loss?

During a period of intense crypto trading the most useful, effective and profitable tool that I found by far was a Trailing Stop Loss function.