Amendment Idea: On-Chain Multisign

[mvadari]

  title: On-Chain Multisign
  description: Allow accounts to collect signatures on-chain for multi-signed and co-signed transactions
  author: Mayukha Vadari (@mvadari)
  status: Idea
  category: Amendment
  created: 2025-09-25

On-Chain Multisign

Abstract

The XRP Ledger already supports multisigning. However, it's rather difficult to use, and impossible to use in a completely decentralized manner in the current implementation. This is because the multi-signers need to have some method of off-chain coordination in order to construct their multi-signed transaction.

The same is true for multi-account Batch transactions, and other co-signed transactions like loan creation/sponsored fees and reserves.

There is a need for on-chain multisign. Some example usecases are:

• Decentralized account ownership (all communication happens on-chain and you don't need to have any method of off-chain communication)
• Smart contracts that want to perform a multi-account Batch transaction between themselves

1. Overview

This spec proposes:

• Creating the TransactionSaved ledger object
• Creating the TransactionSave transaction
• Creating the TransactionSavedCancel transaction
• Modifying the behavior of all transactions

It will require an amendment, tentatively titled OnChainMultisign.

1.1. Background: Multisigned/Co-signed Transactions

Note: some of these are still in the spec phase and there is no timeline for them to be developed.

• Standard transaction multisign
• Transaction-specific multisign (XLS-49)
• Multi-account Batch transactions (XLS-56)
• Loan creation (XLS-66)
• Sponsoring transaction fees and reserves (XLS-68)

1.2. Example Flows

1.2.1. Multi-Signing

Sigmund and Sigourney are siblings who co-own a house. They hate each other and do not want to communicate, but they have to pay the bills somehow. So they set up an XRP Ledger account to manage the finances of this house. They do not want to do any off-chain communication.

1. Sigmund constructs a transaction to pay a vendor.
2. He submits a TransactionSave transaction with that transaction included.
3. Sigourney notices that that transaction was created. She knows that bill needs to be paid, so she grabs that transaction and submits her own TransactionSave transaction.
4. The transaction is submitted on Sigmund and Sigourney's behalf via the second TransactionSave transaction.

1.2.2. Batch

Spec: XLS-56

Alice and Bob want to execute a trustless token swap. Alice has 100 USD and Bob has 100 XRP that they want to trade trustlessly.

1. Alice creates a multi-account Batch transaction for the proposed token swap. The two inner transactions are basic payments:
   • One from Alice to Bob, paying 100 USD.
   • One from Bob to Alice, paying 100 XRP.
2. Alice stores it on-chain with a TransactionSave transaction.
   • Note: this transaction is not considered valid, since it does not have a signature from Bob included.
3. Bob is listening to the transactions on the ledger and is notified of this transaction waiting for his signature.
4. Bob grabs the transaction from the TransactionSaved ledger object and signs it as a BatchSigner.
5. Bob also submits a TransactionSave transaction.
6. The transaction is submitted on Alice and Bob's behalf via the second TransactionSave transaction.
   • Note: this has the same effect as Bob taking Alice's signature and submitting the multi-signed Payment transaction himself.

1.2.3. LoanSet

Spec: XLS-66

Broderick the loan broker and Boromir the borrower want to create a loan from Broderick's vault to Boromir.

1. Boromir creates the LoanSet transaction, filling out all the relevant fields.
2. Boromir stores it on-chain with a TransactionSave transaction.
   • Note: this transaction is not considered valid, since it does not have a signature from Broderick included.
3. Broderick is listening to the transactions on the ledger and is notified of this transaction waiting for his signature.
4. Broderick grabs the transaction from the TransactionSaved ledger object and signs it as a Counterparty.
5. Broderick also submits a TransactionSave transaction.
6. The transaction is submitted on Boromir and Broderick's behalf via the second TransactionSave transaction.

1.2.4. Sponsoring Fees and Reserves

Spec: XLS-68

The sponsor, Spencer, wants to pay the transaction fee and/or reserve for the sponsee Alice's transaction.

1. Alice creates the transaction she wants to be sponsored, filling out all the relevant fields, and listing Spencer as the sponsor.
2. Alice stores it on-chain with a TransactionSave transaction.
   • Note: this transaction is not considered valid, since it does not have a signature from Spencer included.
3. Spencer is listening to the transactions on the ledger and is notified of this transaction waiting for his signature.
4. Spencer grabs the transaction from the TransactionSaved ledger object and signs it as a Sponsor.
5. Spencer also submits a TransactionSave transaction.
6. The transaction is submitted on Alice and Spencer's behalf via the second TransactionSave transaction.

2. On-Ledger Object: TransactionSaved

2.1. 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.
SignerListID	Yes	No	N/A	string	UInt32	The SignerListID used for the transaction, if using multi-sign. This field doesn't serve much of a purpose right now, but enables future-proofing if anything like XLS-49 is implemented.
Transaction	Yes	Yes	N/A	object	STTx	The transaction that is being multi-signed.
AuthAccounts	No			array	STArray
Expiration	No	No	N/A	number	UInt32	The time at which this transaction expires and can no longer be multi-signed.
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.

2.1.1. Transaction

The Transaction must be unsigned, but all other relevant fields must be included.

2.1.2. AuthAccounts

This field is an array of objects with the following fields:

Field Name	Constant?	Required?	Default Value	JSON Type	Internal Type	Description
Account	Yes	Yes	N/A	string	AccountID	The account that is authorizing this transaction.
Flags	Yes	Yes	N/A	number	UInt32	Flags that indicate what type of signer this is.

2.1.2.1. Flags

The Flags field indicates what type of signer this is.

Flag Name	Flag Value	Description
aafAccountSigner	0x00000001	Indicates that the Account submitting the transaction is the account sending the transaction.
aafMultiSignSigner	0x00000002	Indicates that the Account submitting the transaction is a multi-signer.
aafSponsorSigner	0x00000004	Indicates that the Account submitting the transaction is the sponsor for that transaction.
aafLoanCounterpartySigner	0x00000008	Indicates that the Account submitting the transaction is the loan counterparty for that transaction.

2.2. Object ID

The key of the TransactionSaved object is the result of SHA512-Half of the following values concatenated in order:

• The TransactionSaved space key (defined during implementation)
• The hash of the unsigned transaction

2.3. Ownership

This ledger object is owned by Owner, who also bears the reserve for this object.

2.4. Reserve

This object charges 1 reserve.

2.5. Deletion

This object is a deletion blocker.

Two possible expirations:

• The Expiration field
• The LastLedgerSequence in the transaction itself

Before the transaction is expired, it may only be deleted by the Account (or Delegate) in the transaction. After, it may be deleted by anyone.

2.6. Invariant Checks

• Transaction must be minimally valid (it must pass preflight checks)
• Expiration must be in the future
• Transaction.LastLedgerSequence must be in the future, if it is provided
• SignerListID must be 0, if included (only for multisign)

2.7. RPC Name

The snake_case form of the ledger object name is saved_txn.

3. Transaction: TransactionSave

This transaction either creates a new TransactionSaved or updates an existing one (with the same transaction hash).

3.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	✔️	string	UInt16	The transaction type (TransactionSave).
Account	✔️	string	AccountID	The account that wants to add one signature.
Transaction	✔️	object	STTx	Transaction that is being multisigned. It must be unsigned.
Expiration		number	UInt32	The time that the multisign should expire.

3.1.1. Account

Any account can submit a TransactionSave transaction, as long as they are allowed to have their signature in that sub-transaction. However, this account will have to pay the reserve for the created TransactionSaved ledger object, if one is created.

3.1.2. Transaction

The Transaction must be unsigned, but all other relevant fields must be included.

3.1.3. Expiration

This is the time that the multisig should expire.

3.2. Flags

The flags will be mostly used to indicate who is signing the transaction.

Flag Name	Flag Value	Description
tfTransferReserve	0x00010000	Indicates that the Owner should shift to the tx.Account from the current TransactionSaved.Owner. This flag is only valid if there is already a TransactionSaved object.
tfAccountSigner	0x00020000	Indicates that the Account submitting the transaction is the account sending the transaction.
tfMultiSignSigner	0x00040000	Indicates that the Account submitting the transaction is a multi-signer.
tfSponsorSigner	0x00080000	Indicates that the Account submitting the transaction is the sponsor for that transaction.
tfLoanCounterpartySigner	0x00100000	Indicates that the Account submitting the transaction is the loan counterparty for that transaction.
Additional co-signed transaction support may also be added here.

3.3. Failure Conditions

• Not a valid signer for that transaction.
• Trying to sign on behalf of another account (for whom you're not a valid RegularKey).
• That signer has already been added in the TransactionSaved object.
• Transaction already has all the required signatures.
• Trying to duplicate a signature that's already been added (e.g. the Loan field in XLS-66)
• If the Expiration or Transaction.LastLedgerSequence has passed already
• The signer type (specified by Flags) is invalid in some way (e.g. tfLoanCounterpartySigner is enabled but it is not a LoanSet transaction, or tfSponsorSigner is enabled but the signer is not the sponsor)

3.4. State Changes

If the TransactionSaved object doesn't already exist for this transaction:

• The TransactionSaved ledger object is created. The sender of the first TransactionSave transaction bears the reserve.

If the transaction is "finished" (i.e. has all the necessary "signatures"):

• The TransactionSaved ledger object is deleted.
• The transaction contained in that ledger object is submitted to the network (this will be implemented similar to Batch inner transactions).

If neither above case is true:

• The transaction in the TransactionSaved ledger object is updated to include the new signer's information.
• If the tx.Expiration is earlier than the current expiration on the object (or if a current expiration doesn't exist), that field will also be updated to the provided value.
• If tfTransferReserve is enabled on the transaction, the Owner will be updated to be tx.Account.

If the signer list has changed since the last TransactionSave transaction was submitted:

4. Transaction: TransactionSavedCancel

There may be times when a TransactionSaved object needs to be deleted - perhaps the transaction was incorrectly formatted, or there were multiple transactions up for debate amongst the signers, or the expiration has passed. There may also be times when an account wants to revoke its signature.

There are two scenarios where this transaction may be sent:

• The account that owns a TransactionSaved ledger object may submit this transaction at any time, if they want the reserve back. If this happens, ???
  • TODO: maybe some transfer mechanism is needed for the reserve?
• Anyone may submit this transaction for a given TransactionSaved ledger object after the Transaction.LastLedgerSequence ledger index or the Expiration has passed.

4.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	Yes	string	UInt16	The transaction type (TransactionSave).
Account	Yes	string	AccountID	The account that wants to delete a TransactionSaved object.
Flags	No	number	UInt32	The bitwise flags accepted on this transaction.
TransactionSavedID	Yes	string	Hash256	The TransactionSaved object to delete.

4.2. Flags

Flag Name	Flag Value	Description
tfDeleteSignature	0x00010000	Indicates that the object shouldn't be deleted, but one signer should be removed from AuthAccounts instead.

4.3. Failure Conditions

• The TransactionSaved object doesn't exist.

Before the TransactionSaved.Expiration/TransactionSaved.Transaction.LastLedgerSequence has passed:

• The tx.Account is not any of [TransactionSaved.Transaction.Account, TransactionSaved.Transaction.Delegate, TransactionSaved.Owner] or a signer on the transaction

4.4. State Changes

The TransactionSaved object is deleted.

5. All Transactions

No change to functionality, only behavior.

If a transaction is submitted that has an existing TransactionSave object associated with it, it will be deleted.

6. Examples

{
  TransactionType: "TransactionSave",
  Account: "rBTwLga1d2gz3doX6Gva3MgEV8ZCD8jjah",
  Flags: tfMultiSignSigner,
  Transaction: {
    TransactionType: "Payment",
    Account: "ruazs5h1qEsqpke88pc2naseXdm6od2xc",
    Destination: "rPGgiDm9iwmkA2a8CaBdneXzATH6YY1qjF",
    Amount: "1000000000000",
    Fee: "10",
    Sequence: 123456789,
    LastLedgerSequence: 987654321,
    SigningPubKey: "",
  },
  Expiration: 987654321
}

7. Security

Signers are checked for validity. Also, the transaction is still submitted as it would be normally so it goes through the normal checks.

n+1: Open Questions

• Can there be a better handling of sequence numbers?
• Can there be a better way of handling the reserves?
• Does there need to be an additional fee for TransactionSave since it submits a transaction? Or is the n transactions that were gathered enough?
• Should the multi-signed transaction auto-send on the last TransactionSave or should there be a separate Send transaction?
  • Gnosis Safe does the latter

Appendix

Appendix A: FAQ

A.1: What happens if the signer list changes part-way through collecting all the signatures?

The first time a TransactionSave transaction is submitted after the change in signatures for that account, the list of "signatures" stored in the TransactionSaved ledger object will be updated to reflect the changes.

A.2: How does sequence number coordination work?

Sequence numbers still have to be ordered properly. Every time a TransactionSave transaction is checked, the sequence number is checked for validity (it will only be checked to ensure it is not a past sequence number, as you may have several queued up). If the sequence number has passed, then the object is deleted, as it is no longer valid. This is because the transactions have to be signed with a given sequence number.

This process can be greatly simplified with the use of a ticket.

A.3: How can this work in conjunction with XLS-49?

The SignerListID is specified in the ledger object, to future-proof the design. If and when XLS-49 is implemented, a SignerListID field can be added to the transaction as well. If it is omitted in the transaction, it is assumed to be equal to 0, the global signer list value.

This field is needed in case of the edge case where an account is listed on both the global signer list and a permission-specific list.

Noting an edge case for the future in the event that this amendment is implemented: what if an account submits the same transaction but with a different SignerListID?