Merge branch 'server_defs' of https://github.com/ckeshava/XRPL-Standards into server_defs

Author: ckeshava

.github/scripts/assign_xls_number.py

@@ -76,9 +76,15 @@ def find_draft_xls_files(changed_files: list[str]) -> list[str]:
 
 def main():
     """Main entry point for the script."""
-    # Get repository root (parent of .github directory)
-    script_dir = Path(__file__).resolve().parent
-    repo_root = script_dir.parent.parent
+    # Get repository root from environment variable (set by GitHub Actions)
+    # or fall back to calculating from script location
+    repo_root_env = os.environ.get("REPO_ROOT")
+    if repo_root_env:
+        repo_root = Path(repo_root_env)
+    else:
+        # Fallback: parent of .github directory
+        script_dir = Path(__file__).resolve().parent
+        repo_root = script_dir.parent.parent
 
     # Get changed files from command line arguments or environment variable
     if len(sys.argv) > 1:

.github/scripts/filter-discussions-to-close.jq

@@ -3,7 +3,7 @@
 # 1. It has a warning comment containing the unique marker
 # 2. That warning comment was posted by the bot
 # 3. That warning comment is older than WARNING_DAYS
-# 4. The discussion hasn't been updated since the warning (or updates are also old)
+# 4. There are no comments from non-bot users after the warning
 #
 # Input: GraphQL response with discussions data
 # Arguments:
@@ -39,8 +39,20 @@
 # Only proceed if the warning comment is old enough
 | select($warningComment.createdAt <= $warningCutoff)
 
-# Only proceed if the discussion hasn't been updated since the warning
-| select($discussion.updatedAt < $warningComment.createdAt)
+# Check if there are any comments from non-bot users after the warning
+# Note: We can't rely on updatedAt because the bot's warning comment itself
+# updates the discussion's updatedAt timestamp
+| (
+    (.comments.nodes // [])
+    | map(
+        select(.createdAt > $warningComment.createdAt)
+        | select(.author.login != $botLogin)
+      )
+    | length
+  ) as $nonBotCommentsAfterWarning
+
+# Only proceed if there are no comments from non-bot users after the warning
+| select($nonBotCommentsAfterWarning == 0)
 
 # Output as JSON
 | @json

.github/scripts/process-stale-discussions.sh

@@ -131,8 +131,11 @@ echo ""
 echo "Bot login: $BOT_LOGIN"
 
 # Verify bot login is accessible
-if ! BOT_INFO=$(gh api /users/$BOT_LOGIN 2>&1); then
-  echo "Warning: Could not verify bot user '$BOT_LOGIN'" >&2
+# Note: The REST API uses the [bot] suffix for GitHub App bots, while the GraphQL API
+# returns author.login without the suffix. We verify using the [bot] suffix.
+BOT_LOGIN_FOR_REST="${BOT_LOGIN}[bot]"
+if ! BOT_INFO=$(gh api "/users/$BOT_LOGIN_FOR_REST" 2>&1); then
+  echo "Warning: Could not verify bot user '$BOT_LOGIN_FOR_REST'" >&2
   echo "The script will continue, but make sure BOT_LOGIN is correct." >&2
   echo "API Response: $BOT_INFO" >&2
 else

.github/workflows/assign-xls-number.yml

@@ -62,6 +62,8 @@ jobs:
       - name: Assign XLS number
         if: steps.check-drafts.outputs.has_drafts == 'true'
         id: assign-number
+        env:
+          REPO_ROOT: ${{ github.workspace }}
         run: |
           echo ${{ steps.check-drafts.outputs.draft_files }}
           python base-repo/.github/scripts/assign_xls_number.py ${{ steps.check-drafts.outputs.draft_files }}

.github/workflows/discussions.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Fetch and process stale discussions
         env:
           GH_TOKEN: ${{ steps.generate_token.outputs.token }}
-          BOT_LOGIN: ${{ steps.generate_token.outputs.app-slug }}[bot]
+          BOT_LOGIN: ${{ steps.generate_token.outputs.app-slug }}
           STALE_DAYS: ${{ env.STALE_DAYS }}
           WARNING_DAYS: ${{ env.WARNING_DAYS }}
           WARNING_MESSAGE: ${{ env.WARNING_MESSAGE }}

XLS-0056-batch/README.md

@@ -565,6 +565,39 @@ 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.
 
+## 6. Integration Considerations
+
+- 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.
+  - 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.
+
+### 6.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.
+
+### 6.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.
+- Not auto-increment sequence numbers after successes/failures, since it depends on what/how many transactions are validated.
+
+### 6.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.
+
 # Appendix
 
 ## Appendix A: FAQ

XLS-0065-single-asset-vault/README.md

@@ -15,7 +15,7 @@
 
 ## _Abstract_
 
-A Single Asset Vault is a new on-chain primitive for aggregating assets from one or more depositors, and making the assets available for other on-chain protocols. The Single Asset Vault uses [Multi-Purpose-Token](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens) to represent ownership shares of the Vault. The Vault serves diverse purposes, such as lending markets, aggregators, yield-bearing tokens, asset management, etc. The Single Asset Vault decouples the liquidity provision functionality from the specific protocol logic.
+A Single Asset Vault is a new on-chain primitive for aggregating assets from one or more depositors, and making the assets available for other on-chain protocols. The Single Asset Vault uses [Multi-Purpose-Token](../XLS-0033-multi-purpose-tokens/README.md) to represent ownership shares of the Vault. The Vault serves diverse purposes, such as lending markets, aggregators, yield-bearing tokens, asset management, etc. The Single Asset Vault decouples the liquidity provision functionality from the specific protocol logic.
 
 ## Index
 
@@ -50,7 +50,7 @@ A Single Asset Vault is a new on-chain primitive for aggregating assets from one
 
 ### 1.1 Overview
 
-The **Single Asset Vault** is an on-chain object that aggregates assets from one or more depositors and represents ownership through shares. Other protocols, such as the [Lending Protocol](https://github.com/XRPLF/XRPL-Standards/discussions/190), can access these assets via the vault, whether or not they generate yield. Currently, other protocols must be created by the same Account that created the Vault. However, this may change in the future.
+The **Single Asset Vault** is an on-chain object that aggregates assets from one or more depositors and represents ownership through shares. Other protocols, such as the [Lending Protocol](../XLS-0066-lending-protocol/README.md), can access these assets via the vault, whether or not they generate yield. Currently, other protocols must be created by the same Account that created the Vault. However, this may change in the future.
 
 The specification introduces a new `Vault` ledger entry, which contains key details such as available assets, shares, total value, and other relevant information.
 
@@ -77,17 +77,17 @@ A Single Asset Vault is owned and managed by an account called the **Vault Owner
 
 #### 1.1.2 Access Control
 
-A Single Asset Vault can be either public or private. Any depositor can deposit and redeem liquidity from a public vault, provided they own sufficient shares. In contrast, access to private shares is controlled via [Permissioned Domains](../XLS-0080-permissioned-domains/README.md), which use on-chain [Credentials](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0070-credentials) to manage access to the vault. Only depositors with the necessary credentials can deposit assets to a private vault. To prevent Vault Owner from locking away depositor funds, any shareholder can withdraw funds. Furthermore, the Vault Owner has an implicit permission to deposit and withdraw assets to and from the Vault. I.e. they do not have to have credentials in the Permissioned Domain.
+A Single Asset Vault can be either public or private. Any depositor can deposit and redeem liquidity from a public vault, provided they own sufficient shares. In contrast, access to private shares is controlled via [Permissioned Domains](../XLS-0080-permissioned-domains/README.md), which use on-chain [Credentials](../XLS-0070-credentials/README.md) to manage access to the vault. Only depositors with the necessary credentials can deposit assets to a private vault. To prevent Vault Owner from locking away depositor funds, any shareholder can withdraw funds. Furthermore, the Vault Owner has an implicit permission to deposit and withdraw assets to and from the Vault. I.e. they do not have to have credentials in the Permissioned Domain.
 
 #### 1.1.3 Yield Bearing Shares
 
-Shares represent the ownership of a portion of the vault's assets. On-chain shares are represented by a [Multi-Purpose Token](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens). When creating the vault, the Vault Owner can configure the shares to be non-transferable. Non-transferable shares cannot be transferred to any other account -- they can only be redeemed. If the vault is private, shares can be transferred and used in other DeFi protocols as long as the receiving account is authorized to hold the shares. The vault's shares may be yield-bearing, depending on the protocol connected to the vault, meaning that a holder may be able to withdraw more (or less) liquidity than they initially deposited.
+Shares represent the ownership of a portion of the vault's assets. On-chain shares are represented by a [Multi-Purpose Token](../XLS-0033-multi-purpose-tokens/README.md). When creating the vault, the Vault Owner can configure the shares to be non-transferable. Non-transferable shares cannot be transferred to any other account -- they can only be redeemed. If the vault is private, shares can be transferred and used in other DeFi protocols as long as the receiving account is authorized to hold the shares. The vault's shares may be yield-bearing, depending on the protocol connected to the vault, meaning that a holder may be able to withdraw more (or less) liquidity than they initially deposited.
 
 ### 1.2 Terminology
 
 - **Vault**: A ledger entry for aggregating liquidity and providing this liquidity to one or more accessors.
-- **Asset**: The currency of a vault. It is either XRP, a [Fungible Token](https://xrpl.org/docs/concepts/tokens/fungible-tokens/) or a [Multi-Purpose Token](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens).
-- **Share**: Shares represent the depositors' portion of the vault's assets. Shares are a [Multi-Purpose Token](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens) created by the _pseudo-account_ of the vault.
+- **Asset**: The currency of a vault. It is either XRP, a [Fungible Token](https://xrpl.org/docs/concepts/tokens/fungible-tokens/) or a [Multi-Purpose Token](../XLS-0033-multi-purpose-tokens/README.md).
+- **Share**: Shares represent the depositors' portion of the vault's assets. Shares are a [Multi-Purpose Token](../XLS-0033-multi-purpose-tokens/README.md) created by the _pseudo-account_ of the vault.
 
 ### 1.3 Actors
 
@@ -96,7 +96,7 @@ Shares represent the ownership of a portion of the vault's assets. On-chain shar
 
 ### 1.4 Connecting to the Vault
 
-A protocol connecting to a Vault must track its debt. Furthermore, the updates to the Vault state when funds are removed or added back must be handled in the transactors of the protocol. For an example, please refer to the [Lending Protocol](https://github.com/XRPLF/XRPL-Standards/discussions/190) specification.
+A protocol connecting to a Vault must track its debt. Furthermore, the updates to the Vault state when funds are removed or added back must be handled in the transactors of the protocol. For an example, please refer to the [Lending Protocol](../XLS-0066-lending-protocol/README.md) specification.
 
 [**Return to Index**](#index)
 
@@ -164,7 +164,7 @@ The `Vault` object costs one reserve fee per object created:
 
 #### 2.1.6 Vault Shares
 
-Shares represent the portion of the Vault assets a depositor owns. Vault Owners set the currency code of the share and whether the token is transferable during the vault's creation. These two values are immutable. The share is represented by a [Multi-Purpose Token](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens). The MPT is issued by the vault's pseudo-account.
+Shares represent the portion of the Vault assets a depositor owns. Vault Owners set the currency code of the share and whether the token is transferable during the vault's creation. These two values are immutable. The share is represented by a [Multi-Purpose Token](../XLS-0033-multi-purpose-tokens/README.md). The MPT is issued by the vault's pseudo-account.
 
 ##### 2.1.6.1 `Scale`
 
@@ -215,7 +215,7 @@ The `MPToken` object represents the amount of shares held by a depositor. It is
 
 ###### 2.1.6.3.1 `MPToken` Values
 
-The `MPToken` values should be set as per the `MPT` [specification](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens#2112-fields).
+The `MPToken` values should be set as per the `MPT` [specification](../XLS-0033-multi-purpose-tokens/README.md#2112-fields).
 
 | **Condition**     | **Transferable**   | **Non-Transferable** |
 | ----------------- | ------------------ | -------------------- |
@@ -344,7 +344,7 @@ The First Come, First Serve strategy treats all requests equally, allowing a dep
 
 #### 2.1.8 Frozen Assets
 
-The issuer of the Vaults asset may enact a freeze either through a [Global Freeze](https://xrpl.org/docs/concepts/tokens/fungible-tokens/freezes/#global-freeze) for IOUs or [locking MPT](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0033-multi-purpose-tokens#21122-flags). When the vaults asset is frozen, it can only be withdrawn by specifying the `Destination` account as the `Issuer` of the asset. Similarly, a frozen asset _may not_ be deposited into a vault. Furthermore, when the asset of a vault is frozen, the shares corresponding to the asset may not be transferred.
+The issuer of the Vaults asset may enact a freeze either through a [Global Freeze](https://xrpl.org/docs/concepts/tokens/fungible-tokens/freezes/#global-freeze) for IOUs or [locking MPT](../XLS-0033-multi-purpose-tokens/README.md#21122-flags). When the vaults asset is frozen, it can only be withdrawn by specifying the `Destination` account as the `Issuer` of the asset. Similarly, a frozen asset _may not_ be deposited into a vault. Furthermore, when the asset of a vault is frozen, the shares corresponding to the asset may not be transferred.
 
 #### 2.1.9 Transfer Fees