add a Flags section (#424)

Author: mvadari

AMENDMENT_TEMPLATE.md

@@ -69,15 +69,23 @@ _[Add more rows as needed for your specific fields. Remove example custom fields
 
 _[Detailed explanation of field behavior, validation rules, etc.]_
 
-### 2.3. Ownership
+### 2.3. Flags
+
+\_[Describe any ledger entry-specific flags. The values must be powers of 2. If there are none, you can omit this section.]
+
+| Flag Name        | Flag Value   | Description      |
+| ---------------- | ------------ | ---------------- |
+| `[lsfFlagName1]` | `0x[Value1]` | `[Description1]` |
+
+### 2.4. Ownership
 
 _[Specify which AccountRoot object owns this ledger entry and how the ownership relationship is established.]_
 
 **Owner:** `[Account field name or "No owner" if this is a global object like FeeSettings]`
 
 **Directory Registration:** `[Describe how this object is registered in the owner's directory, or specify if it's a special case]`
 
-### 2.4. Reserves
+### 2.5. Reserves
 
 **Reserve Requirement:** `[Standard/Custom/None]`
 
@@ -87,7 +95,7 @@ _[If Custom]: This ledger entry requires `[X]` reserve units because `[reason]`.
 
 _[If None]: This ledger entry does not require additional reserves because `[reason]`._
 
-### 2.5. Deletion
+### 2.6. Deletion
 
 **Deletion Transactions:** `[List transaction types that can delete this object]`
 
@@ -101,7 +109,7 @@ _[If None]: This ledger entry does not require additional reserves because `[rea
 _[If Yes]: This object must be deleted before its owner account can be deleted._
 _[If No]: This object does not prevent its owner account from being deleted._
 
-### 2.6. Pseudo-Account _(Optional)_
+### 2.7. Pseudo-Account _(Optional)_
 
 _[Only include this section if your ledger entry uses a pseudo-account. Otherwise, delete this subsection.]_
 
@@ -113,7 +121,7 @@ _[If Yes]:_
 - **AccountID Derivation:** `[Describe the algorithm for deriving the pseudo-account's AccountID]`
 - **Capabilities:** `[List what the pseudo-account can/cannot do]`
 
-### 2.7. Freeze/Lock _(Optional)_
+### 2.8. Freeze/Lock _(Optional)_
 
 _[Only include this section if your ledger entry holds assets that can be frozen/locked. Otherwise, delete this subsection.]_
 
@@ -122,21 +130,21 @@ _[Only include this section if your ledger entry holds assets that can be frozen
 
 _[If applicable, describe how freeze/lock functionality is implemented for assets held by this object]_
 
-### 2.8. Invariants
+### 2.9. Invariants
 
 _[List logical statements that must always be true for this ledger entry. Use `<object>` for before-state and `<object>'` for after-state.]_
 
 - `[Invariant 1, e.g., "<object>.Balance >= 0 AND <object>'.Balance >= 0"]`
 - `[Invariant 2, e.g., "IF <object>.Status == 'Active' THEN <object>.Account != NULL"]`
 - `[Additional invariants as needed]`
 
-### 2.9. RPC Name
+### 2.10. RPC Name
 
 **RPC Type Name:** `[snake_case_name]`
 
 _[This is the name used in `account_objects` and `ledger_data` RPC calls to filter for this object type]_
 
-### 2.10. Example JSON
+### 2.11. Example JSON
 
 ```json
 {
@@ -178,15 +186,23 @@ _[Add more rows as needed for your specific fields. Remove example custom fields
 
 _[Detailed explanation of field behavior, validation rules, etc.]_
 
-### 3.2. Transaction Fee
+### 3.2. Flags
+
+\_[Describe any transaction-specific flags. The values must be powers of 2. If there are none, you can omit this section.]
+
+| Flag Name       | Flag Value   | Description      |
+| --------------- | ------------ | ---------------- |
+| `[tfFlagName1]` | `0x[Value1]` | `[Description1]` |
+
+### 3.3. Transaction Fee
 
 **Fee Structure:** `[Standard/Custom]`
 
 _[If Standard]: This transaction uses the standard transaction fee (currently 10 drops, subject to Fee Voting changes)._
 
 _[If Custom]: This transaction requires `[X]` drops because `[reason]`._
 
-### 3.3. Failure Conditions
+### 3.4. Failure Conditions
 
 _[List all conditions that cause the transaction to fail, with corresponding error codes]_
 
@@ -196,7 +212,7 @@ _[List all conditions that cause the transaction to fail, with corresponding err
 
 _[For new error codes, provide justification for why existing codes are insufficient]_
 
-### 3.4. State Changes
+### 3.5. State Changes
 
 _[Describe the ledger state changes when the transaction executes successfully. Omit standard changes like fee processing and sequence increment.]_
 
@@ -206,15 +222,15 @@ _[Describe the ledger state changes when the transaction executes successfully.
 - `[State change 2, e.g., "Update Account's OwnerCount"]`
 - `[Additional changes as needed]`
 
-### 3.5. Metadata Fields _(Optional)_
+### 3.6. Metadata Fields _(Optional)_
 
 _[Only include this section if the transaction adds or modifies metadata fields. Otherwise, delete this subsection.]_
 
 | Field Name     | Validated  | Always Present?        | Type                           | Description     |
 | -------------- | ---------- | ---------------------- | ------------------------------ | --------------- |
 | `[field_name]` | `[Yes/No]` | `[Yes/No/Conditional]` | `[string/number/object/array]` | `[Description]` |
 
-### 3.6. Example JSON
+### 3.7. Example JSON
 
 ```json
 {

XLS-0001-xls-process/README.md

@@ -211,41 +211,51 @@ These columns must all be included in the table:
 
 The table may be followed by subsections for fields requiring further details that are too long for the Description column.
 
-##### 4.4.3.2.3. Ownership
+##### 4.4.3.2.3. Flags
+
+This subsection describes all the ledger entry `lsf` flags in a tabular format.
+
+These columns must all be included in the table:
+
+- **Flag Name**: The column indicates the flag's name. Flags follow the `lsfPascalCase` naming convention.
+- **Flag Value**: The column indicates the flag's value. Flag values are powers of 2 expressed as 32-bit integers, written in hexadecimal with a `0x` prefix (e.g., `0x00010000`).
+- **Description**: A brief description of the flag. Further details can be written in a subsection of **Flags**.
+
+##### 4.4.3.2.4. Ownership
 
 All XRP Ledger objects must have an owner. The owner is an `AccountRoot` object, and the ownership relationship is typically established by adding the object's ID to an `OwnerDirectory` ledger entry associated with the owner's account. This subsection captures which `AccountRoot` object's `OwnerDirectory` the ledger entry is registered. A single ledger entry may be linked from one or more unique `DirectoryNode` pages, usually under one `OwnerDirectory`.
 
 _Note: there are a handful of object types (such as `FeeSettings`) that don’t have an owner. If an amendment is of that ilk, that should be specified in this section._
 
-##### 4.4.3.2.4. Reserves
+##### 4.4.3.2.5. Reserves
 
 Creating ledger entries typically requires an increase in the owner's XRP reserve to discourage ledger bloat and account for the cost of storage. Each new ledger entry directly owned by an account typically increments the owner reserve by one unit (currently 0.2 XRP, as of last check, but subject to change by [Fee Voting](https://xrpl.org/docs/concepts/consensus-protocol/fee-voting)). This section should confirm whether this standard behavior applies or specify any deviations.
 
-##### 4.4.3.2.5. Deletion
+##### 4.4.3.2.6. Deletion
 
 This subsection captures the conditions under which the ledger entry can be deleted from the ledger. It should specify:
 
 - What transaction(s) can delete the object.
 - Any prerequisite conditions for deletion (e.g., object state, zero balances, no linked objects).
 - Is the ledger entry a "blocker" for deleting its owner `AccountRoot` (i.e., whether it must be deleted before the account can be deleted).
 
-##### 4.4.3.2.6. Pseudo-Account
+##### 4.4.3.2.7. Pseudo-Account
 
 This section is optional. A "pseudo-account" might be associated if the newly introduced ledger entry needs to hold assets (XRP, IOUs or MPTs) or issue tokens (e.g., MPTs). A pseudo-account is a programmatically derived `Account` that cannot submit transactions, send or receive funds directly via standard payments, or have a key pair. For further details about pseudo-accounts, refer to [XLS-64](https://github.com/XRPLF/XRPL-Standards/pull/274) (or the relevant accepted standard). This section should specify if a pseudo-account is used, how its `AccountID` is derived, and its purpose.
 
-##### 4.4.3.2.7. Freeze/Lock
+##### 4.4.3.2.8. Freeze/Lock
 
 This section is optional. If the protocol holds assets on behalf of other users, it must comply with the existing compliance features `Freeze`, `Deep Freeze` for IOUs and `Locking` for MPTs. This section describes how said freezing is handled.
 
-##### 4.4.3.2.8. Invariants
+##### 4.4.3.2.9. Invariants
 
 Invariants are logical statements that MUST be true of a ledger entry's state before and after the execution of any transaction (whether successful or not). They help ensure that no transaction leads to an invalid or inconsistent ledger state. Use `<object>` for the state before and `<object>'` (see the added grave) for the state after.
 
-##### 4.4.3.2.9. RPC Name
+##### 4.4.3.2.10. RPC Name
 
 In RPCs like `account_objects` and `ledger_data`, a short, `snake_case` form of the name of a ledger entry is accepted in the `type` parameter, to filter the ledger entries returned by type. This section should specify that version of the entry's name.
 
-##### 4.4.3.2.10. Example JSON
+##### 4.4.3.2.11. Example JSON
 
 Provide JSON examples for what the ledger object will look like.
 
@@ -278,11 +288,21 @@ The following columns should be included:
 - **Default Value**: If any. `N/A` if none or always required.
 - **Description**: Succinct description of the field.
 
-##### 4.4.3.3.2. Transaction Fee
+##### 4.4.3.3.2. Flags
+
+This subsection describes all the ledger entry `tf` flags in a tabular format.
+
+These columns must all be included in the table:
+
+- **Flag Name**: The column indicates the flag's name. Flags follow the `tfPascalCase` naming convention.
+- **Flag Value**: The column indicates the flag's value. Flag values are powers of 2 expressed as 32-bit integers, written in hexadecimal with a `0x` prefix (e.g., `0x00010000`).
+- **Description**: A brief description of the flag. Further details can be written in a subsection of **Flags**.
+
+##### 4.4.3.3.3. Transaction Fee
 
 Submitting a transaction typically requires paying a transaction fee. A typical transaction costs 10 drops as of last check (subject to change by [Fee Voting](https://xrpl.org/docs/concepts/consensus-protocol/fee-voting)). This section should confirm whether this standard behavior applies or specify any deviations.
 
-##### 4.4.3.3.3. Failure Conditions
+##### 4.4.3.3.4. Failure Conditions
 
 This section describes the conditions under which the transaction will fail. This must be an exhaustive, descriptive list. Each condition should ideally map to a specific error code. The list should be indexed for easy reference.
 
@@ -292,11 +312,11 @@ In case of a transaction failure, an XRP Ledger server returns an error code ind
 
 If the new transaction logic introduces novel failure reasons not adequately covered by existing generic codes, a new error code (usually a `tec` code) should be proposed. This new code must be clearly defined and justified and would eventually be added to [rippled](https://github.com/XRPLF/rippled/blob/develop/include/xrpl/protocol/TER.h) if the XLS is adopted. XLS authors will primarily define error codes for their specific transaction logic failures.
 
-##### 4.4.3.3.4. State Changes
+##### 4.4.3.3.5. State Changes
 
 This section describes the changes made to the ledger state if the transaction executes successfully. It should omit default state changes common to all transactions (e.g., fee processing, sequence number increment, setting `PreviousTxnID`/`PreviousTxnLgrSeq` on modified objects). Indexed for clarity. A successfully applied transaction must return a `tesSUCCESS` code.
 
-##### 4.4.3.3.5. Metadata Fields
+##### 4.4.3.3.6. Metadata Fields
 
 This section describes any additions or modifications (synthetic or otherwise) to the transaction metadata. This section must not be included if the transaction does not make any such additions or modifications.
 
@@ -311,7 +331,7 @@ The following columns should be included in the table:
 - **Type**: If the field is synthetic, this should specify the The JSON type of the field (e.g., `string`, `number`, `object`, `array`).
 - **Description**: Succinct description of the field.
 
-##### 4.4.3.3.6. Example JSON
+##### 4.4.3.3.7. Example JSON
 
 Provide JSON examples for transaction submission.