From e7d84ed9dead7fb7f41be1cf5e690fc3b2953406 Mon Sep 17 00:00:00 2001 From: Mayukha Vadari Date: Thu, 5 Feb 2026 15:28:49 -0500 Subject: [PATCH 1/3] add integration considerations --- XLS-0056-batch/README.md | 43 +++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/XLS-0056-batch/README.md b/XLS-0056-batch/README.md index 6fe358cf7..f8ca1aa02 100644 --- a/XLS-0056-batch/README.md +++ b/XLS-0056-batch/README.md @@ -194,13 +194,42 @@ Namely: - Inner transactions may not be broadcast (and won't be accepted if they happen to be broadcast, e.g. from a malicious node). They must be generated from the `Batch` outer transaction instead. - Inner transactions may not be directly submitted via the `submit` RPC. -## 5. Examples +## 5. Integration Considerations -### 5.1. One Account +- An outer `Batch` transaction will return `tesSUCCESS` if the outer transaction succeeds, even if the inner transactions fail. The inner transaction metadata and result codes must be used to determine the actual outcome of each inner transaction. + - The inner transactions, if validated, **will** be in the same ledger. If it is not in the same ledger, then it is likely a fraud attempt. +- An inner `Batch` transaction will not be validated on its own. + +### 5.1. Client Libraries + +- `Batch` transactions have a special fee calculation that includes the sum of the inner transaction fees. Client libraries should provide a helper method to calculate the fee for a `Batch` transaction. +- Multi-account `Batch` transactions require a special signing flow where one party signs the outer transaction and the other parties sign the inner transactions. Client libraries should provide a helper method to construct a multi-account `Batch` transaction. +- When auto-filling a `Batch` transaction, the inner transactions must have their `Fee` set to 0 and the `SigningPubKey` and `TxnSignature` fields must be empty. Client libraries should provide a helper method to auto-fill a `Batch` transaction. + +### 5.2. Wallets + +Wallets should: + +- Clearly display all inner transactions to users before requesting a signature, so users understand the full scope of what they are approving. +- For multi-account `Batch` transactions, provide a workflow for users to review and sign their portion of the batch, then export it for other parties to sign. +- Warn users if they are signing a `Batch` transaction that includes inner transactions from other accounts, as they are approving the entire batch. +- Display the batch mode (`ALLORNOTHING`, `ONLYONE`, `UNTILFAILURE`, `INDEPENDENT`) and explain its implications. + +### 5.3. Explorers and Indexers + +Explorers and indexers should: + +- Display the relationship between outer `Batch` transactions and their inner transactions using the `ParentBatchID` field. +- Show inner transactions in context with their parent `Batch` transaction, rather than as standalone transactions. +- Consider grouping inner transactions with their outer transaction in transaction lists for clarity. + +## 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. -#### 5.1.1. Sample Transaction +#### 6.1.1. Sample Transaction
@@ -253,7 +282,7 @@ The inner transactions are not signed, and the `BatchSigners` field is not neede
-#### 5.1.2. Sample Ledger +#### 6.1.2. Sample Ledger
@@ -335,11 +364,11 @@ Note that the inner transactions are committed as normal transactions.
-### 5.2. Multiple Accounts +### 6.2. Multiple Accounts In this example, two users are atomically swapping their tokens, XRP for GKO. -#### 5.2.1. Sample Transaction +#### 6.2.1. Sample Transaction
@@ -401,7 +430,7 @@ The inner transactions are still not signed, but the `BatchSigners` field is nee
-#### 5.2.2. Sample Ledger +#### 6.2.2. Sample Ledger
From 492fa2be259012028293e24798906d9acd2d8669 Mon Sep 17 00:00:00 2001 From: Mayukha Vadari Date: Thu, 5 Feb 2026 15:30:12 -0500 Subject: [PATCH 2/3] one more --- XLS-0056-batch/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/XLS-0056-batch/README.md b/XLS-0056-batch/README.md index f8ca1aa02..7c44c86c1 100644 --- a/XLS-0056-batch/README.md +++ b/XLS-0056-batch/README.md @@ -199,6 +199,7 @@ Namely: - An outer `Batch` transaction will return `tesSUCCESS` if the outer transaction succeeds, even if the inner transactions fail. The inner transaction metadata and result codes must be used to determine the actual outcome of each inner transaction. - The inner transactions, if validated, **will** be in the same ledger. If it is not in the same ledger, then it is likely a fraud attempt. - An inner `Batch` transaction will not be validated on its own. +- Systems that don't specifically handle `Batch` transactions should be able to support them without any changes, since each inner transaction will be a valid transaction on its own. ### 5.1. Client Libraries From 40d6299ba84b56589b2fac4e3464332e67f7dd2e Mon Sep 17 00:00:00 2001 From: Mayukha Vadari Date: Mon, 9 Feb 2026 13:20:04 -0500 Subject: [PATCH 3/3] more feedback --- XLS-0056-batch/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/XLS-0056-batch/README.md b/XLS-0056-batch/README.md index 7c44c86c1..fbd45088a 100644 --- a/XLS-0056-batch/README.md +++ b/XLS-0056-batch/README.md @@ -200,6 +200,8 @@ Namely: - The inner transactions, if validated, **will** be in the same ledger. If it is not in the same ledger, then it is likely a fraud attempt. - An inner `Batch` transaction will not be validated on its own. - Systems that don't specifically handle `Batch` transactions should be able to support them without any changes, since each inner transaction will be a valid transaction on its own. + - All inner transactions that have a `tes` (success) or `tec` result code will be accessible via standard transaction-fetching mechanisms (such as `tx` and `account_tx`). +- Since only the inner transactions and batch mode flags are signed in a multi-account `Batch` transaction, the relayer (submitter of the outer transaction) can adjust the sequence number and fee of the outer transaction as needed, without needing to coordinate with the other parties. ### 5.1. Client Libraries @@ -215,6 +217,7 @@ Wallets should: - For multi-account `Batch` transactions, provide a workflow for users to review and sign their portion of the batch, then export it for other parties to sign. - Warn users if they are signing a `Batch` transaction that includes inner transactions from other accounts, as they are approving the entire batch. - Display the batch mode (`ALLORNOTHING`, `ONLYONE`, `UNTILFAILURE`, `INDEPENDENT`) and explain its implications. +- Not auto-increment sequence numbers after successes/failures, since it depends on what/how many transactions are validated. ### 5.3. Explorers and Indexers