0056 XLS-56d: Atomic/Batch Transactions

[mvadari]

Title:       Atomic/Batch Transactions
Revision:    3 (2024-04-22)

Author:      Mayukha Vadari

Affiliation: Ripple

Atomic/Batch Transactions

Abstract

The XRP Ledger has a robust set of built-in features, enabling fast and efficient transactions without the need for complex smart contracts on every step. However, a key limitation exists: multiple transactions cannot be executed atomically. This means that if a complex operation requires several transactions, a failure in one can leave the system in an incomplete or unexpected state. Imagine building a house: you wouldn't want to lay the foundation and build the walls, and then discover you can't afford the roof, leaving you with an unfinished and unusable structure.

This document proposes a design to allow multiple transactions to be packaged together and executed as a single unit. It's like laying the foundation, building the walls, and raising the roof all in one single secure step, leveraging the existing strengths of the XRP Ledger. If you're unable to afford the roof, you won't even bother laying the foundation.

This eliminates the risk of partial completion and unexpected outcomes, fostering a more reliable and predictable user experience for complex operations. By introducing these batch transactions, developers gain the ability to design innovative features and applications that were previously hindered by the lack of native smart contracts for conditional workflows. This empowers them to harness the full potential of the XRP Ledger's built-in features while ensuring robust execution of complex processes.

Some use-cases that may be enabled by batch transactions include (but are certainly not limited to):

• All or nothing: Mint an NFT and create an offer for it in one transaction. If the offer creation fails, the NFT mint is reverted as well.
• Trying out a few offers: Submit multiple offers with different amounts of slippage, but only one will succeed.
• Platform fees: Package platform fees within the transaction itself, simplifying the process.
• Swaps (multi-account): Trustless token/NFT swaps between multiple accounts.
• Withdrawing accounts (multi-account): Attempt a withdrawal from your checking account, and if that fails, withdraw from your savings account instead.

1. Overview

This spec proposes one new transaction: Batch. It also proposes an addition to the common fields of all transactions. It will not require any new ledger objects, nor modifications to existing ledger objects. It will require an amendment, tentatively titled featureBatch.

The rough idea of this design is that users can include "sub-transactions" inside Batch, and these transactions are processed atomically. The design also supports transactions from different accounts in the same Batch wrapper transaction.

1.1. Terminology

• Inner transaction: the sub-transactions included in the Batch transaction, that are executed atomically.
• Outer transaction: the wrapper Batch transaction itself.
• Batch mode or mode: the "mode" of batch processing that the transaction uses. See section 2.2 for more details.

2. Transaction: Batch

FieldName	Required?	JSON Type	Internal Type
TransactionType	✔️	string	UInt16
Account	✔️	string	STAccount
Fee	✔️	string	STAmount
Flags	✔️	number	UInt32
RawTransactions	!	array	STArray
TxnIDs	✔️	array	Vector256
BatchSigners		array	STArray

2.1. Fee

The fee for the outer transaction is:

$$(n+2)*base\textunderscore fee + \sum_{innerTxns} Txn.Fee$$
(where n is the number of signatures included in the outer transaction)

In other words, the fee is twice the base fee (a total of 20 drops when there is no fee escalation), plus the sum of the transaction fees of all the inner transactions (which incorporates factors like higher fees for multisign or AMMCreate).

The fees for the individual inner transactions are paid here instead of in the inner transaction itself, to ensure that fee escalation is calculated on the total cost of the transaction instead of just the overhead.

2.2. Flags

The Flags field represents the batch mode of the transaction. Exactly one must be specified in a Batch transaction.

This spec supports four modes:

• ALLORNOTHING or tfAllOrNothing (with a value of 0x00000001)
• ONLYONE or tfOnlyOne (with a value of 0x00000002)
• UNTILFAILURE or tfUntilFailure (with a value of 0x00000004)
• INDEPENDENT or tfIndependent (with a value of 0x00000008)

2.2.1. ALLORNOTHING

All or nothing. All transactions must succeed for any of them to succeed.

2.2.2. ONLYONE

The first transaction to succeed will be the only one to succeed; all other transactions either failed or were never tried.

While this can sort of be done by submitting multiple transactions with the same sequence number, there is no guarantee that the transactions are processed in the same order they are sent.

2.2.3. UNTILFAILURE

All transactions will be applied until the first failure, and all transactions after the first failure will not be applied.

2.2.4. INDEPENDENT

All transactions will be applied, regardless of failure.

2.3. RawTransactions

RawTransactions contains the list of transactions that will be applied. There can be up to 8 transactions included. These transactions can come from one account or multiple accounts.

Each inner transaction:

• Must contain a BatchTxn field (see section 3 for details).
• Must not have a sequence number. It must use a sequence number value of 0.
• Must not have a fee. It must use a fee value of "0".
• Must not be signed (the global transaction is already signed by all relevant parties). They must instead have an empty string ("") in the SigningPubKey and TxnSignature fields.

A transaction will be considered a failure if it receives any result that is not tesSUCCESS.

This field is not included in the validated transaction, nor is it used to compute the outer transaction signature(s), since all transactions are included separately as a part of the ledger.

2.4. TxnIDs

TxnIDs contains a list of the transaction hashes/IDs for all the transactions contained in RawTransactions. This is the only part of the inner transactions that is saved as a part of the ledger within the Batch transaction, since the inner transactions themselves will be their own transactions on-ledger. The hashes in TxnIDs must be in the same order as the raw transactions in RawTransactions.

While this field seems complicated/confusing to work with, it can easily be abstracted away (e.g. as a part of autofilling) in tooling, and it's easy for rippled to check a hash doesn't match its corresponding transaction in RawTransaction.

2.5. BatchSigners

This field operates similarly to multisign on the XRPL. It is only needed if multiple accounts' transactions are included in the Batch transaction; otherwise, the normal transaction signature provides the same security guarantees.

Every account that has at least one inner transaction, excluding the outer account (if applicable), must have a BatchSigners field.

FieldName	Required?	JSON Type	Internal Type
Account	✔️	string	STAccount
SigningPubKey		string	STBlob
Signature		string	STBlob
Signers		array	STArray

2.5.1. Account

This is an account that has at least one inner transaction.

2.5.2. SigningPubKey and Signature

These fields are included if the account is signing with a single signature (as opposed to multi-sign). They sign the Flags and TxnIDs fields.

2.5.3. Signers

This field is included if the account is signing with multi-sign (as opposed to a single signature). It operates equivalently to the Signers field used in standard transaction multi-sign. This field holds the signatures for the Flags and TxnIDs fields.

2.6. Metadata

The inner transactions will be committed separately to the ledger and will therefore have separate metadata. This is to ensure better backwards compatibility for legacy systems, so they can support Batch transactions without needing any changes to their systems.

For example, a ledger that only has one Batch transaction containing 2 inner transactions would look like this:

[
  OuterTransaction,
  InnerTransaction1,
  InnerTransaction2
]

2.6.1. Outer Transactions

Each outer transaction will only contain the metadata for its sequence and fee processing, not for the inner transaction processing.

There will also be a list of which transactions were actually processed, which is useful for the ONLYONE and UNTILFAILURE modes, since those may only process a subset of transactions, and for debugging with all modes. This section will be called BatchExecutions.

It will contain a list of objects that have the following fields for every transaction that is processed (successfully or unsuccessfully):

FieldName	Required?	JSON Type	Internal Type
TransactionHash	✔️	string	STUInt256
TransactionResult	✔️	string	STUInt8

Some important things to note:

• It is possible that all transactions will not be included in this list. For example, when using the ONLYONE mode, if the first transaction succeeds, then the rest of the transactions will not even be processed.
• Transactions will only be included in the ledger if their result code is tesSUCCESS and if the outer transaction has a result code of tesSUCCESS. For example, the inner transaction might have a result code of tesSUCCESS without being included in the ledger if the ALLORNOTHING mode is used, but one of the transaction fails.

2.6.2. Inner Transactions

Each inner transaction will contain the metadata for its own processing. Only the inner transactions that were actually committed to the ledger will be included. This makes it easier for legacy systems to still be able to process Batch transactions as if they were normal.

There will also be a pointer back to the parent outer transaction (parent_batch), for ease of development (similar to the nftoken_id field).

3. Transaction Common Fields

As a reference, here are the fields that all transactions currently have.

We propose these modifications:

Field Name	Required?	JSON Type	Internal Type
BatchTxn		object	STObject

3.1. BatchTxn

The BatchTxn inner object must be included in any inner transaction of a Batch transaction. Its inclusion:

• Prevents hash collisions between identical transactions (since sequence numbers aren't included).
• Ensures that every transaction has a sequence number associated with it, so that created ledger objects that use it in their ID generation can still operate.
• Allows users to more easily organize their transactions in the correct order.

The fields contained in this object are:

Field Name	Required?	JSON Type	Internal Type
Account	✔️	string	AccountID
OuterSequence	✔️	number	UInt32
Sequence		number	UInt32
BatchIndex	✔️	number	UInt8

3.1.1. Account

This is the account that is submitting the outer Batch transaction.

3.1.2. OuterSequence

This is the sequence number of the outer Batch transaction. Its inclusion ensures that there are no hash collisions with other Batch transactions.

3.1.3. Sequence

This is the next available sequence number for the inner transaction's account. This only needs to be included in a multi-account Batch transaction. See section 4.1 for an explanation as to why this is needed.

3.1.4. BatchIndex

This is the (0-indexed) index of the inner transaction within the existing Batch transaction. The first inner transaction will have BatchIndex value 0, the second will be 1, etc. Its inclusion ensures there are no hash collisions with other inner transactions within the same Batch transaction, and that the transactions are all placed in the right order.

4. Edge Cases of Transaction Processing

Inner transactions don't have Sequences or TicketSequences, unlike a normal transaction. This causes some problems when it comes to transaction processing, due to a few edge cases.

4.1. Ledger Object ID Generation

Some objects, such as offers and escrows, use the sequence number of the creation transaction as a part of their ledger entry ID generation, to ensure uniqueness of the IDs.

To get around this, in single-account Batch transactions, a "phantom sequence number" will be used instead. The "phantom sequence number" will be equal to BatchTxn.OuterSequence + BatchTxn.BatchIndex.

Multi-account transactions use the same "phantom sequence number" strategy, but instead uses the equation BatchTxn.Sequence + BatchTxn.BatchIndex, since the OuterSequence does not map to the inner transaction's account.

4.2. Sequence Number Handling

Section 4.1 describes how sequence numbers are used in inner transactions.

The sequence numbers will always be consumed (i.e. the AccountRoot's Sequence will be incremented) if any inner transactions are processed. A transaction counts as being "processed" if it is applied to the ledger, i.e. if a tec or tes error is received. The sequence number for each account will be incremented by the total number of inner transactions included in the Batch transaction, to avoid any hash collisions.

In other words,
$$Sequence_{new} = Sequence_{old} + numInnerTxns$$

5. Security

5.1. Trust Assumptions

Regardless of how many accounts' transactions are included in a Batch transaction, all accounts need to sign the collection of transactions.

5.1.1. Single Account

In the single account case, this is obvious; the single account must approve all of the transactions it is submitting. No other accounts are involved, so this is a pretty straightforward case.

5.1.2. Multi Account

The multi-account case is a bit more complicated and is best illustrated with an example. Let's say Alice and Bob are conducting a trustless swap via a multi-account Batch, with Alice providing 1000 XRP and Bob providing 1000 USD. Bob is going to submit the Batch transaction, so Alice must provide her part of the swap to him.

If Alice provides a fully autofilled and signed transaction to Bob, Bob could submit Alice's transaction on the ledger without submitting his and receive the 1000 XRP without losing his 1000 USD. Therefore, the inner transactions must be unsigned.

If Alice just signs her part of the Batch transaction, Bob could modify his transaction to only provide 1 USD instead, thereby getting his 1000 XRP at a much cheaper rate. Therefore, the entire Batch transaction (and all its inner transactions) must be signed by all parties.

6. Examples

6.1. One Account

In this example, the user is creating an offer while trading on a DEX UI, and the second transaction is a platform fee.

6.1.1. Sample Transaction

The inner transactions are not signed, and the BatchSigners field is not needed on the outer transaction, since there is only one account involved.

{
  TransactionType: "Batch",
  Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
  Flags: "1",
  TxnIDs: [
    "7EB435C800D7DC10EAB2ADFDE02EE5667C0A63AA467F26F90FD4CBCD6903E15E",
    "EAE6B33078075A7BA958434691B896CCA4F532D618438DE6DDC7E3FB7A4A0AAB"
  ],
  RawTransactions: [
    {
      RawTransaction: {
        TransactionType: "OfferCreate",
        Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
        TakerGets: "6000000",
        TakerPays: {
          currency: "GKO",
          issuer: "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
          value: "2"
        },
        BatchTxn: {
          Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
          OuterSequence: 3,
          BatchIndex: 0
        },
        Sequence: 0,
        Fee: "0",
        SigningPubKey: "",
        TxnSignature: ""
      }
    },
    {
      RawTransaction: {
        TransactionType: "Payment",
        Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
        Destination: "rDEXfrontEnd23E44wKL3S6dj9FaXv",
        Amount: "1000",
        BatchTxn: {
          Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
          OuterSequence: 3,
          BatchIndex: 1
        },
        Sequence: 0,
        Fee: "0",
        SigningPubKey: "",
        TxnSignature: ""
      }
    }
  ],
  Sequence: 3,
  Fee: "40",
  SigningPubKey: "022D40673B44C82DEE1DDB8B9BB53DCCE4F97B27404DB850F068DD91D685E337EA",
  TxnSignature: "3045022100EC5D367FAE2B461679AD446FBBE7BA260506579AF4ED5EFC3EC25F4DD1885B38022018C2327DB281743B12553C7A6DC0E45B07D3FC6983F261D7BCB474D89A0EC5B8"
}

6.1.2. Sample Ledger

This example shows what the ledger will look like after the transaction is confirmed.

Note that the inner transactions are committed as normal transactions, and the RawTransactions field is not included in the validated version of the outer transaction.

[
  {
    TransactionType: "Batch",
    Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
    Flags: "1",
    TxnIDs: [
      "7EB435C800D7DC10EAB2ADFDE02EE5667C0A63AA467F26F90FD4CBCD6903E15E",
      "EAE6B33078075A7BA958434691B896CCA4F532D618438DE6DDC7E3FB7A4A0AAB"
    ],
    Sequence: 3,
    Fee: "40",
    SigningPubKey: "022D40673B44C82DEE1DDB8B9BB53DCCE4F97B27404DB850F068DD91D685E337EA",
    TxnSignature: "3045022100EC5D367FAE2B461679AD446FBBE7BA260506579AF4ED5EFC3EC25F4DD1885B38022018C2327DB281743B12553C7A6DC0E45B07D3FC6983F261D7BCB474D89A0EC5B8"
  },
  {
    TransactionType: "OfferCreate",
    Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
    TakerGets: "6000000",
    TakerPays: {
      currency: "GKO",
      issuer: "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
      value: "2"
    },
    BatchTxn: {
      Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
      OuterSequence: 3,
      BatchIndex: 0
    },
    Sequence: 0,
    Fee: "0",
    SigningPubKey: "",
    TxnSignature: ""
  },
  {
    TransactionType: "Payment",
    Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
    Destination: "rDEXfrontEnd23E44wKL3S6dj9FaXv",
    Amount: "1000",
    BatchTxn: {
      Account: "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b",
      OuterSequence: 3,
      BatchIndex: 1
    },
    Sequence: 0,
    Fee: "0",
    SigningPubKey: "",
    TxnSignature: ""
  }
]

6.2. Multiple Accounts

In this example, two users are atomically swapping their tokens, XRP for GKO.

6.2.1. Sample Transaction

The inner transactions are still not signed, but the BatchSigners field is needed on the outer transaction, since there are two accounts' inner transactions in this Batch transaction.

{
  TransactionType: "Batch",
  Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
  Flags: "1",
  TxnIDs: [
    "A2986564A970E2B206DC8CA22F54BB8D73585527864A4484A5B0C577B6F13C95",
    "0C4316F7E7D909E11BB7DBE0EB897788835519E9950AE8E32F5182468361FE7E"
  ],
  RawTransactions: [
    {
      RawTransaction: {
        TransactionType: "Payment",
        Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
        Destination: "rUser2fDds782Bd6eK15RDnGMtxf7m",
        Amount: "6000000",
        BatchTxn: {
          Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
          OuterSequence: 4,
          Sequence: 4,
          BatchIndex: 0
        },
        Sequence: 0,
        Fee: "0",
        SigningPubKey: "",
        TxnSignature: ""
      }
    },
    {
      RawTransaction: {
        TransactionType: "Payment",
        Account: "rUser2fDds782Bd6eK15RDnGMtxf7m",
        Destination: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
        Amount: {
          currency: "GKO",
          issuer: "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
          value: "2"
        },
        BatchTxn: {
          Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
          OuterSequence: 4,
          Sequence: 20,
          BatchIndex: 1
        },
        Sequence: 0,
        Fee: "0",
        SigningPubKey: "",
        TxnSignature: ""
      }
    }
  ],
  BatchSigners: [
    {
      BatchSigner: {
        Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
        SigningPubKey: "03072BBE5F93D4906FC31A690A2C269F2B9A56D60DA9C2C6C0D88FB51B644C6F94",
        Signature: "304502210083DF12FA60E2E743643889195DC42C10F62F0DE0A362330C32BBEC4D3881EECD022010579A01E052C4E587E70E5601D2F3846984DB9B16B9EBA05BAD7B51F912B899"
      }
    },
    {
      BatchSigner: {
        Account: "rUser2fDds782Bd6eK15RDnGMtxf7m",
        SigningPubKey: "03C6AE25CD44323D52D28D7DE95598E6ABF953EECC9ABF767F13C21D421C034FAB",
        Signature: "304502210083DF12FA60E2E743643889195DC42C10F62F0DE0A362330C32BBEC4D3881EECD022010579A01E052C4E587E70E5601D2F3846984DB9B16B9EBA05BAD7B51F912B899"
      }
    },
  ],
  Sequence: 4,
  Fee: "60",
  SigningPubKey: "03072BBE5F93D4906FC31A690A2C269F2B9A56D60DA9C2C6C0D88FB51B644C6F94",
  TxnSignature: "30440220702ABC11419AD4940969CC32EB4D1BFDBFCA651F064F30D6E1646D74FBFC493902204E5B451B447B0F69904127F04FE71634BD825A8970B9467871DA89EEC4B021F8"
}

6.2.2. Sample Ledger

This example shows what the ledger will look like after the transaction is confirmed.

Note that the inner transactions are committed as normal transactions, and the RawTransactions field is not included in the validated version of the outer transaction.

[
  {
    TransactionType: "Batch",
    Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
    Flags: "1",
    TxnIDs: [
      "A2986564A970E2B206DC8CA22F54BB8D73585527864A4484A5B0C577B6F13C95",
      "0C4316F7E7D909E11BB7DBE0EB897788835519E9950AE8E32F5182468361FE7E"
    ],
    BatchSigners: [
      {
        BatchSigner: {
          Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
          SigningPubKey: "03072BBE5F93D4906FC31A690A2C269F2B9A56D60DA9C2C6C0D88FB51B644C6F94",
          Signature: "304502210083DF12FA60E2E743643889195DC42C10F62F0DE0A362330C32BBEC4D3881EECD022010579A01E052C4E587E70E5601D2F3846984DB9B16B9EBA05BAD7B51F912B899"
        }
      },
      {
        BatchSigner: {
          Account: "rUser2fDds782Bd6eK15RDnGMtxf7m",
          SigningPubKey: "03C6AE25CD44323D52D28D7DE95598E6ABF953EECC9ABF767F13C21D421C034FAB",
          Signature: "304502210083DF12FA60E2E743643889195DC42C10F62F0DE0A362330C32BBEC4D3881EECD022010579A01E052C4E587E70E5601D2F3846984DB9B16B9EBA05BAD7B51F912B899"
        }
      },
    ],
    Sequence: 4,
    Fee: "60",
    SigningPubKey: "03072BBE5F93D4906FC31A690A2C269F2B9A56D60DA9C2C6C0D88FB51B644C6F94",
    TxnSignature: "30440220702ABC11419AD4940969CC32EB4D1BFDBFCA651F064F30D6E1646D74FBFC493902204E5B451B447B0F69904127F04FE71634BD825A8970B9467871DA89EEC4B021F8"
  },
  {
    TransactionType: "Payment",
    Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
    Destination: "rUser2fDds782Bd6eK15RDnGMtxf7m",
    Amount: "6000000",
    BatchTxn: {
      Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
      OuterSequence: 4,
      Sequence: 4,
      BatchIndex: 0
    },
    Sequence: 0,
    Fee: "0",
    SigningPubKey: "",
    TxnSignature: ""
  },
  {
    TransactionType: "Payment",
    Account: "rUser2fDds782Bd6eK15RDnGMtxf7m",
    Destination: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
    Amount: {
      currency: "GKO",
      issuer: "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
      value: "2"
    },
    BatchTxn: {
      Account: "rUser1fcu9RJa5W1ncAuEgLJF2oJC6",
      OuterSequence: 4,
      Sequence: 20,
      BatchIndex: 1
    },
    Sequence: 0,
    Fee: "0",
    SigningPubKey: "",
    TxnSignature: ""
  }
]

Appendix

Appendix A: FAQ

A.1: What if I want a more complex tree of transactions that are AND/XORed together? Can I nest Batch transactions?

The original version of this spec supported nesting Batch transactions. However, upon further analysis, that was deemed a bit too complicated for an initial version of Batch, as most of the benefit from this new feature does not require nested transactions. Based on user and community need, this could be added as part of a V2.

A.2: What if all of the transactions fail? Will a fee still be claimed?

Yes, just as they would if they were individually submitted.

A.3: Would this feature enable greater frontrunning abilities?

That is definitely a concern. Ways to mitigate this are still being investigated. Some potential answers:

• Charge for more extensive path usage
• Have higher fees for Batch transactions
• Submit the Batch transactions at the end of the ledger

A.4: What error is returned if all the transactions fail in an ONLYONE/UNTILFAILURE transaction?

A general error, temBATCH_FAILED/tecBATCH_FAILED, will be returned. A list of all the return codes encountered for the transactions that were processed will be included in the metadata, for easier debugging.

A.5: Can another account sign/pay for the outer transaction if they don't have any of the inner transactions?

If there are multiple parties in the inner transactions, yes. Otherwise, no. This is because in a single party Batch transaction, the inner transaction's signoff is provided by the normal transaction signing fields (SigningPubKey and TxnSignature).

A.6: How is the UNTILFAILURE mode any different than existing behavior with sequence numbers?

Right now, if you submit a series of transactions with consecutive sequence numbers without the use of tickets or Batch, then if one fails in the middle, all subsequent transactions will also fail due to incorrect sequence numbers (since the one that failed would have the next sequence numbers).

The difference between the UNTILFAILURE mode and this existing behavior is that right now, the subsequent transactions will only fail with a non-tec error code. If the failed transaction receives an error code starting with tec, then a fee is claimed and a sequence number is consumed, and the subsequent transactions will still be processed as usual.

A.7: How is the INDEPENDENT mode any different than existing behavior with tickets?

Tickets require temporarily having a reserve for all the tickets you want to create, but an INDEPENDENT mode Batch transaction doesn't, for the low cost of 10 extra drops.

On the flip side, tickets are still needed for other use-cases, such as needing to coordinate multiple signers or needing out-of-order transactions.

A.8: Is it possible for inner transactions to end up in a different ledger than the outer transaction?

No, because the inner transactions skip the transaction queue. They are already effectively processed by the queue via the outer transaction. Inner transactions will also be excluded from consensus for the same reason.

A.9: How does this work in conjunction with XLS-49d? If I give a signer list powers over the Batch transaction, can it effectively run all transaction types?

The answer to this question is still being investigated. Some potential answers:

• All signer lists should have access to this transaction but only for the transaction types they have powers over
• Only the global signer list can have access to this transaction

A.10: What if I want some error code types to be allowed to proceed, just as tesSUCCESS would, in e.g. an ALLORNOTHING case?

This was deemed unnecessary. If you have a need for this, please provide example use-cases.

A.11: What if I want the inner transaction accounts to handle their own fees?

That is not supported in this version of the spec, as it is cleaner to just have one account pay the fee. This also allows fee escalation to be calculated on the total cost of the transaction, instead of just on the overhead.

[dangell7]

I'm not sure I like the name Atomic if there is an option for it to be a non atomic tx.

I would also just want non atomic batch. Try all 8 and return the responses of each. I will parse the results and handle accordingly.

If atomic proves to be very difficult this will be a much easier implementation

[mvadari]

The transactions are still being applied atomically, regardless of the scenario. But I'm certainly open to other names. I do think Batch is too specific for this transaction's capabilities, though.

I don't think it should be any more difficult to handle atomic-ness compared to just batching transactions - the batching part in general is where the complexity is.

[ajkagy]

my thoughts here

1. would it be possible to have a flag to submit all transactions regardless of a failure. I can see a use for this in terms of bulk buying nfts where as a user wants to create a buy offer for 20 nfts, but doesn't want 1 failure to stop the rest of batched buy offers from being submitted because 1 of the nfts changed ownership between the time of the user creating the offer and submitting it (edge case failure, but have seen it happen when multiple parties are competing to buy at the same time).
2. Fee calculation best practices? would this affect open ledger fee if say 100 or 1000 or more transactions are being submitted, therefore a buffer amount would need to be added for reliable transaction submission into open ledgers?
3. Since this is technically only 1 transaction, I would assume there's no submission node queue limit issue here?
4. What would be the batch size/payload limit?

[mvadari]

1. Yes, that could be another atomicity type.
2. That's the main reason this is limited to 8 transactions max, to avoid someone trying to batch 100 transactions and bloating ledgers. I think it would require more investigation, though.
3. I believe not, since this is only one transaction.
4. 8 transactions.

[dangell7]

Fee escalation is a great point! Would prob have to try, but fail imo. We could add a flag to charge the full fees though.

[ajkagy]

yea, fee escalation would be my concern since you can potentially stuff hundreds of transactions into a single open ledger (if the fee amount is sufficient) thereby compounding the number of transactions...more than likely fee amount will change and those transactions would be queued resulting in the user receiving a telCAN_NOT_QUEUE.

[mvadari]

Yeah, that's why I limited it to 8 transactions (mostly a randomly-picked number). But it definitely will require further testing.

[shortthefomo]

Am i reading it correctly that this actually reduces the fee for the most complex types on the ledger, large count multisig and escrow finish?

Batch fee either needs to be dynamic based on tx types in the batch, or worst case assumption for all 8 slots.

[mvadari]

That's incorrect.
$$2*base\textunderscore fee + \sum_{txs}tx.Fee$$
This means that the fee for a batch transaction is 2 times the base fee (20 drops total) plus the sum of whatever the normal fee would be for the sub-transactions. So the cost of multisig and escrow finish would be incorporated into that.

[tequdev]

What will the value of meta.deliverd_amount when multiple Payments are sent?

There could be a impact on the exchange's deposit system.

But it is a very valuable feature for the ecosystem as a whole!

[mvadari]

That's a good question and will likely require some further thought and experimentation. Perhaps there should be a new field called meta.delivered_amounts for this purpose that has a list. Or a list of metadatas for the transaction as a whole.

[Tapanito]

I'd like to clarify the way transactions are counted. The spec mentions that it will be possible to nest the transactions, but the total number of transactions cannot exceed 8.
Imagine a user submits the following atomic transaction:

• atomic(tx1,atomic(tx2, tx3))

In the total transaction count is this considered 3 or 4 transactions? I.e. does the nested atomic contribute to the total transaction count?

Also, is there any rationale behind allowing a user to submit 8 transactions as opposed to 10 or 6?

[dangell7]

8 is chosen arbitrary. I don't think I will support nested txns.

[Tapanito]

Could you elaborate on your position?

[dangell7]

Nesting batch transactions requires another level of complexity. I don't want to support this at this time. If you want to write this amendment with nested transactions feel free to PR the amendment. I would like to get this amendment finished ASAP and to do so will need to strip it down to something much simpler.

[Tapanito]

To address your commend regarding getting this done ASAP I'd like to say the following. This feature introduces fairly complex interactions with the rest of XRP Ledger. While I appreciate the enthusiasm to implement the spec before it is finalized, I don't think a feature specification should follow development, but the development should follow the specification. Otherwise, what is the purpose of writing a specification in the first place. I'm sure you're very aware that any future changes to this feature would have to go through the same long amendment process. After all, once a feature is "in", it's very very difficult to remove in case of any oversight.

[mvadari]

The spec has been updated to remove nesting for now, since most of the benefit of this feature does not require nesting, and nesting becomes rather complicated from an implementation perspective. It can be re-introduced in the future, based on need.

[Tapanito]

This feature supports nesting, which means we can do some arbitrary conditional transaction execution by combining different atomic types. IHMO this is pretty cool, and versatile. Who needs smart contracts when you have logic, am I right? :P

We already have an ${x \land y}$ from ALL, ${x \lor y}$ from BATCH all is missing is ${\neg x}$. Then for completeness I suggest to introduce NONE atomic type, which is successful only when all transactions fail. On it's own such atomic operation is useless. However, since the atomic transactions support nesting, and there already is an and in the form of ALL and or in the form of BATCH then introducing NONE would allow to the users to do rudimentary logical operations with transactions.

For example, with 8 transactions users would already be able to express secondary boolean operations such as:

${\textstyle x\rightarrow y=\neg {x}\vee y}$
${\textstyle x\leftrightarrow y=(x\land y)\lor (\neg x\land \neg y)=(x\lor \neg y)\land (\neg x\lor y)}$
${\textstyle x\oplus y=\neg (x\leftrightarrow y)=(x\vee y)\wedge \neg (x\wedge y)=(x\vee y)\wedge (\neg x\vee \neg y)=(x\wedge \neg y)\vee (\neg x\wedge y)}$

[mvadari]

The spec has been updated to remove nesting for now, as this would add a lot of implementation complexity, and the network still gets a lot of benefit from unnestable Atomic transactions. This additional atomicity type can be added alongside nesting.

[tequdev]

For example, when using OfferCreate, Sequence is a component of OfferID. If multiple OfferCreate transactions are used in this transaction, what will the OfferID?

[tequdev]

If AtmicType is ONLYONE or BATCH, it might be helpful to see which transactions were successful (meta field).

[mvadari]

The spec was significantly updated on 2024-04-22.

[nhartner]

I presume ticket sequences are intentionally excluded, which I think is good to reduce scope if they can still be supported in a future version. I could see Tickets being useful for atomic swaps because until all parties sign and submit, their accounts cannot submit any other transactions to the ledger otherwise they will invalidate their sequence numbers inside the batch transaction.

[mvadari]

Inner transactions do not need sequence numbers at all, to avoid this exact problem. See section 2.3 and section 4.

[nhartner]

I'm referring to the Sequence field of BatchTxn. For the multiple account scenario, I understood that to be the sequence number for each account. So if Bob assigns sequence 111 into his inner transaction BatchTxn, and Alice and assigns sequence 222, then neither Bob nor Alice can submit any transactions on their account until both have signed the Batch transaction and it has been submitted to the ledger.

[mvadari]

Ticket support for that field would be rather complicated, given the way that the sequence numbers are used (see section 4.2).

[nhartner]

the RawTransactions field is not included in the validated version of the outer transaction.
If the RawTransactions field is not included in the validated ledger, doesn't it become impossible to verify the signature of a validated batch transaction that used ONLYONE or UNTILFAILURE? Since skipped transactions from the batch will not be in the validated ledger but were part of the signature?

[mvadari]

From section 2.3:

This field is not included in the validated transaction, nor is it used to compute the outer transaction signature(s)

It is not included in the signature either.

[nhartner]

Ah got it. So the TxIDs field of the validated ledger would have the hashes of all the raw transactions, even the ones that didn't get processed.

[mvadari]

Yes, exactly.

[rothexD]

regarding FAQ 3, would this not guarantee that all transactions are part of the same ledger?

[mvadari]

Oops, I'll take that out - it's equivalent to the INDEPENDENT mode.

[rothexD]

true lol, missed that

[tequdev]

Although not directly related to the content, Outer Transaction Fee in 6.1.2 Sample Ledger is set to "0". Perhaps it should be "40".

[mvadari]

Good catch, fixed 🙂

[tequdev]

If Multiple Account Batch and Inner Txn contains multiple transactions for the same account, will BatchTxn.Sequence be incremented for each?

If so, Ledger Object ID should use BatchTxn.Sequence instead of BatchTxn.Sequence + BatchTxn.BatchIndex.

Even if it is not increased and is processed with the same value, BatchTxn.BatchIndex should not be used considering the case where Inner Txn is [Alice Txn, Bob Txn, Alice Txn]. There is a possibility of ID conflict in Alice's transaction immediately after Batch.

Account Sequence before Batch txn: 10
Ledger Object ID generated from Batch[0]: 10 (10+0)
Ledger Object ID generated from Batch[2]: 12 (10+2)
Account Sequence after Batch txn: 12

Ledger Object ID generated from some Txn: 12

[mvadari]

BatchTxn.Sequence will not be incremented for each, as that makes sequence numbers harder to deal with in inner transactions, since you don't always know how many transactions will be successful.

The batch transaction increments the sequence number by $numInnerTxns$ instead of just by 1 (see section 4.2). So the Account Sequence after Batch txn will actually be 13, not 12.

[tequdev]

Does this mean that Sequence: 11 will skipped on Alice's account in this case?

[mvadari]

Yes.

I know it's not the most elegant solution, but it's the best I could come up with, given that the sequence number has to be calculable just given info in the inner transactions. I'm open to other suggestions as well.

[shefi]

Is there any chance the processing could reach a deadlock state if there is any dependence between inner transactions or between inner and outer transaction?

I have no knowledge of how the transactions are being processed within rippled, so this might be a nothing burger.

I am just asking, because batch processing is a kind of traditional DB transactions and they are prone to deadlocks if not implemented right.

[mvadari]

All the dependencies are addressed in this spec - just fees and sequence numbers. That's all the outer transaction needs to do, really.

[EnchStyle]

Question. How does it work with wallet providers?
If XPMarket sets a UI fees of x%, and then pushes transaction to Xaman wallet who would like to also charge y% free.... How will it work? Will it be x+y%? just x%? just y%?

[mvadari]

You're limited to what's possible with existing transactions. There is no percentage transaction right now, so both the platform and the wallet would have to calculate that themselves based on the transaction they're handed.

[shortthefomo]

After spending a bit of time looking at XLS-67d. I'm in favor of splitting the charge out of the batch, and removing the documentation to use it for service charges in the batch.

In favor of both amendments moving forward with the caveat that charges use the chareback field vs bundling those into a batch.

Motivation is mainly interfaces having a clear place to derive / find and display clearly display additional charges. This could become complicated if batch was used obscurely.

[mvadari]

How would you prefer handling multiple parties charging on the same transaction (e.g. a platform and a wallet)? Seems easier to do that with Batch than with XLS-67d.

[VadneyK]

would love to see this go through. Trying to implement CRU (carbon credits) and CET (emissions data) linking and need atomic transactions.

CRU and CET are defined by GBBC IWA TTF

[mvadari]

Per the new XLS Contributing process, it is my opinion that we have reached a "well-refined standard."

As such, I propose that we move this discussion to a file (via #197) and work on final changes using additional PRs, for better change-tracking.

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)

[ckeshava]

1. What is the reason for picking (n+2) * BaseFee in the first half of the Batch transaction fees? I understand the multi-signature transactions have a factor of (n+1) in its fees. Why didn't you retain n or n+1 multiplicative factor in the fee calculation?

2. What's the influence of Batch transactions on the open-ledger cost? For instance, if 10 Batch transactions are included in a validated ledger, this is equivalent to inserting at most 80 non-Batch "usual" transactions. Is the soft-limit of the open-ledger cost calculation proportionately increased by this amendment?

3. Regarding Section 4.2, the new Sequence numbers appears to waste a few of the intermediate sequence numbers. I know that this is too late to change the spec, but how about this alternative.

Instead of incrementing the new_seq_num by numInnerTxns, why can't we use:
new_seq_num_Acct1 = old_seq_num_Acct1 + numInnerTxn_Acct1; numInnerTxn_Acct1 refers to the number of inner-transactions sent by Account-1 only.

This does not completely eliminate wastage of the sequence numbers, however it reduces it. But, it comes with an increased computational overhead.

[mvadari]

The latest version of the spec is here: #197

[ckeshava]

ok

[ckeshava]

what do you think of question-2 ?

[ckeshava]

5. I have some questions about the intended use-cases of this amendment. Can you point me to additional use-cases or test-cases that clarify the usage?

Some use-cases that may be enabled by batch transactions include (but are certainly not limited to):
All or nothing: Mint an NFT and create an offer for it in one transaction. If the offer creation fails, the NFT mint is reverted as well.

If the NFTokenOffer creation fails, I would retry the transaction after fixing the errors.

Trying out a few offers: Submit multiple offers with different amounts of slippage, but only one will succeed.

If I submit multiple offers on the DEX (with varying slippage), the offer-matching algorithm ensures that both buyer and seller obtain the optimal match. I can submit multiple offers with the tfPassive flag. How is the Batch amendment helpful in this case?

Withdrawing accounts (multi-account): Attempt a withdrawal from your checking account, and if that fails, withdraw from your savings account instead.

I can encapsulate the transaction submission code inside a try-catch or an if-else block. This helps me implement the required logic. Why would I need the Batch amendment?

6. Canonical order of transactions: This depends on the AccountID, Sequence number of the transaction and the transaction-ID Here's the Source Code. Why are Batch transactions more prone to front-running? I'm assuming that the signatories do not leak information themselves. Given that fact, the consensus process for Batch transactions does not appear to take up significantly higher time, compared to non-Batch transactions.

[mvadari]

5. I have some questions about the intended use-cases of this amendment. Can you point me to additional use-cases or test-cases that clarify the usage?

• Platform fees - e.g. a DEX platform can charge a platform fee alongside the OfferCreate transaction, and the user can't reject the platform fee because it's not a separate transaction.
• https://developer.algorand.org/docs/get-details/atomic_transfers/#use-cases
• https://x.com/msvadari/status/1770478996741874156
• https://x.com/LoafPickle/status/1770509374458364275

Some use-cases that may be enabled by batch transactions include (but are certainly not limited to):

Trying out a few offers: Submit multiple offers with different amounts of slippage, but only one will succeed.

If I submit multiple offers on the DEX (with varying slippage), the offer-matching algorithm ensures that both buyer and seller obtain the optimal match. I can submit multiple offers with the tfPassive flag. How is the Batch amendment helpful in this case?

That doesn't help if you e.g. have 100 XRP and only want to spend 10 XRP. If you place multiple offers, they might all be matched.

Withdrawing accounts (multi-account): Attempt a withdrawal from your checking account, and if that fails, withdraw from your savings account instead.

I can encapsulate the transaction submission code inside a try-catch or an if-else block. This helps me implement the required logic. Why would I need the Batch amendment?

It's more efficient to essentially have that try-catch/if-else on-chain.

6. Canonical order of transactions: This depends on the AccountID, Sequence number of the transaction and the transaction-ID Here's the Source Code. Why are Batch transactions more prone to front-running? I'm assuming that the signatories do not leak information themselves. Given that fact, the consensus process for Batch transactions does not appear to take up significantly higher time, compared to non-Batch transactions.

They enable things like circular payments.

[ckeshava]

thanks

[ckeshava]

What is the maximum number of Signers allowed in a Batch transaction? Assuming that featureExpandedSignerList is enabled, what’s the upper bound on the signers ?

[ckeshava]

Based on a cursory read of this method, every inner transaction could have 32 unique signers: https://github.com/XRPLF/rippled/blob/develop/include/xrpl/protocol/STTx.h#L61

Is that correct ?

[ckeshava]

However, the preflight function restricts the number of unique signers to 8