feat: FlatMap ShaMap

Co-authored-by: Bart <11445373+bthomee@users.noreply.github.com>

.clang-tidy

@@ -199,6 +199,6 @@ CheckOptions:
   readability-identifier-naming.PublicMemberSuffix: ""
   readability-identifier-naming.GlobalFunctionIgnoredRegexp: "^(to_string|hash_append|tuple_hash)$"
 
-HeaderFilterRegex: '^.*/(test|xrpl|xrpld)/.*\.(h|hpp|ipp)$'
+HeaderFilterRegex: '^.*/(tests?|xrpl|xrpld)/.*\.(h|hpp|ipp)$'
 ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$'
 WarningsAsErrors: "*"

.github/actions/build-deps/action.yml

@@ -37,12 +37,12 @@ runs:
       run: |
         echo 'Installing dependencies.'
         conan install \
-          --profile ci \
-          --build="${BUILD_OPTION}" \
-          --options:host='&:tests=True' \
-          --options:host='&:xrpld=True' \
-          --settings:all build_type="${BUILD_TYPE}" \
-          --conf:all tools.build:jobs=${BUILD_NPROC} \
-          --conf:all tools.build:verbosity="${LOG_VERBOSITY}" \
-          --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}" \
-          .
+            --profile ci \
+            --build="${BUILD_OPTION}" \
+            --options:host='&:tests=True' \
+            --options:host='&:xrpld=True' \
+            --settings:all build_type="${BUILD_TYPE}" \
+            --conf:all tools.build:jobs=${BUILD_NPROC} \
+            --conf:all tools.build:verbosity="${LOG_VERBOSITY}" \
+            --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}" \
+            .

.github/actions/generate-version/action.yml

@@ -15,7 +15,7 @@ runs:
       shell: bash
       env:
         VERSION: ${{ github.ref_name }}
-      run: echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
+      run: echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
 
     # When a tag is not pushed, then the version (e.g. 1.2.3-b0) is extracted
     # from the BuildInfo.cpp file and the shortened commit hash appended to it.
@@ -28,17 +28,17 @@ runs:
         echo 'Extracting version from BuildInfo.cpp.'
         VERSION="$(cat src/libxrpl/protocol/BuildInfo.cpp | grep "versionString =" | awk -F '"' '{print $2}')"
         if [[ -z "${VERSION}" ]]; then
-          echo 'Unable to extract version from BuildInfo.cpp.'
-          exit 1
+            echo 'Unable to extract version from BuildInfo.cpp.'
+            exit 1
         fi
 
         echo 'Appending shortened commit hash to version.'
         SHA='${{ github.sha }}'
         VERSION="${VERSION}+${SHA:0:7}"
 
-        echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
+        echo "VERSION=${VERSION}" >>"${GITHUB_ENV}"
 
     - name: Output version
       id: version
       shell: bash
-      run: echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+      run: echo "version=${VERSION}" >>"${GITHUB_OUTPUT}"

.github/scripts/format-inline-bash.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+
+"""
+Format embedded shell snippets using the shfmt hook configured in
+.pre-commit-config.yaml.
+
+Two shapes are recognised:
+
+* YAML workflow/action files: literal block-scalar runs (`run: |`) and
+  single-line runs (`run: some command`). A single-line run is upgraded to
+  a `run: |` block scalar if shfmt's output spans multiple lines.
+
+* Markdown files: ``` ```bash ``` fenced code blocks.
+
+Any block that shfmt cannot parse is skipped with a warning on stderr, so
+the file is left untouched and surrounding blocks still get formatted.
+
+For each occurrence the body is dedented, written to a temp .sh file,
+formatted via `pre-commit run shfmt --files <temp>` (falling back to
+`prek`), then re-indented and written back in place.
+
+When invoked without arguments, every .yml/.yaml under .github/ plus every
+.md file in the repo is scanned. When invoked with file arguments (the
+pre-commit case), only those files are processed.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Union
+
+REPO = Path(__file__).resolve().parents[2]
+
+_HOOK_RUNNER = next((cmd for cmd in ("pre-commit", "prek") if shutil.which(cmd)), None)
+if _HOOK_RUNNER is None:
+    sys.exit("error: neither `pre-commit` nor `prek` found on PATH")
+
+RUN_BLOCK_RE = re.compile(r"^(?P<prefix>[ \t]*(?:- )?)run:[ \t]*\|[+-]?[ \t]*$")
+RUN_INLINE_RE = re.compile(
+    r"^(?P<prefix>[ \t]*(?:- )?)run:[ \t]+" r"(?P<value>(?!\|[+-]?[ \t]*$)\S.*?)[ \t]*$"
+)
+MD_BASH_OPEN_RE = re.compile(r"^(?P<indent>[ ]{0,3})`{3}bash[ \t]*$")
+MD_FENCE_CLOSE_RE = re.compile(r"^[ ]{0,3}`{3,}[ \t]*$")
+
+
+@dataclass(frozen=True)
+class BlockRun:
+    """A `run: |` block scalar; `body_start:body_end` slices into `lines`."""
+
+    body_start: int
+    body_end: int
+    body_indent: int
+
+
+@dataclass(frozen=True)
+class InlineRun:
+    """A single-line `run: value` at `line_idx`."""
+
+    line_idx: int
+    prefix: str
+    value: str
+
+
+@dataclass(frozen=True)
+class MdBashBlock:
+    """A markdown ``` ```bash ``` fenced code block.
+
+    `body_start:body_end` slices into the file's lines; `open_line_idx`
+    points at the opening fence line.
+    """
+
+    open_line_idx: int
+    body_start: int
+    body_end: int
+    body_indent: int
+
+
+RunItem = Union[BlockRun, InlineRun]
+
+
+def _scan_block_body(
+    lines: list[str], body_start: int, run_col: int
+) -> tuple[int | None, int]:
+    """Locate the body of a `run: |` block scalar starting at `body_start`.
+
+    Returns `(body_indent, scan_end)`. `scan_end` is the line index where the
+    outer scanner should resume. `body_indent` is `None` when no body is
+    present (the scalar is empty, or the next non-blank line has indent
+    `<= run_col`).
+    """
+    body_indent: int | None = None
+    scan_end = len(lines)
+    for idx in range(body_start, len(lines)):
+        line = lines[idx]
+        if line.strip() == "":
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if body_indent is None:
+            if indent > run_col:
+                body_indent = indent
+            else:
+                scan_end = idx
+                break
+        elif indent < body_indent:
+            scan_end = idx
+            break
+    if body_indent is not None:
+        while scan_end > body_start and lines[scan_end - 1].strip() == "":
+            scan_end -= 1
+        if scan_end <= body_start:
+            body_indent = None
+    return body_indent, scan_end
+
+
+def find_run_blocks(lines: list[str]) -> list[RunItem]:
+    """Return run items in document order."""
+    items: list[RunItem] = []
+    line_idx = 0
+    while line_idx < len(lines):
+        line = lines[line_idx]
+        if block_match := RUN_BLOCK_RE.match(line):
+            run_col = len(block_match.group("prefix"))
+            body_start = line_idx + 1
+            body_indent, scan_end = _scan_block_body(lines, body_start, run_col)
+            if body_indent is not None:
+                items.append(
+                    BlockRun(
+                        body_start=body_start,
+                        body_end=scan_end,
+                        body_indent=body_indent,
+                    )
+                )
+            line_idx = scan_end
+            continue
+        if inline_match := RUN_INLINE_RE.match(line):
+            items.append(
+                InlineRun(
+                    line_idx=line_idx,
+                    prefix=inline_match.group("prefix"),
+                    value=inline_match.group("value"),
+                )
+            )
+        line_idx += 1
+    return items
+
+
+def find_md_bash_blocks(lines: list[str]) -> list[MdBashBlock]:
+    """Return ``` ```bash ``` fenced code blocks in document order."""
+    blocks: list[MdBashBlock] = []
+    line_idx = 0
+    while line_idx < len(lines):
+        open_match = MD_BASH_OPEN_RE.match(lines[line_idx])
+        if not open_match:
+            line_idx += 1
+            continue
+        body_start = line_idx + 1
+        close_idx = next(
+            (
+                j
+                for j in range(body_start, len(lines))
+                if MD_FENCE_CLOSE_RE.match(lines[j])
+            ),
+            None,
+        )
+        if close_idx is None:
+            line_idx = body_start
+            continue
+        body = lines[body_start:close_idx]
+        non_blank = [b for b in body if b.strip()]
+        body_indent = (
+            min(len(b) - len(b.lstrip(" ")) for b in non_blank)
+            if non_blank
+            else len(open_match.group("indent"))
+        )
+        blocks.append(
+            MdBashBlock(
+                open_line_idx=line_idx,
+                body_start=body_start,
+                body_end=close_idx,
+                body_indent=body_indent,
+            )
+        )
+        line_idx = close_idx + 1
+    return blocks
+
+
+def dedent(lines: list[str], n: int) -> list[str]:
+    pad = " " * n
+    return [
+        (
+            ""
+            if line.strip() == ""
+            else (line[n:] if line.startswith(pad) else line.lstrip(" "))
+        )
+        for line in lines
+    ]
+
+
+def reindent(lines: list[str], n: int) -> list[str]:
+    pad = " " * n
+    return [pad + line if line else "" for line in lines]
+
+
+_SHFMT_ERR_RE = re.compile(r"\.sh:\d+:\d+:\s")
+_GHA_EXPR_RE = re.compile(r"\$\{\{.*?\}\}", re.DOTALL)
+_GHA_PLACEHOLDER_RE = re.compile(r"__GHA_EXPR_(\d+)__")
+
+
+def _encode_gha_exprs(text: str) -> tuple[str, list[str]]:
+    """Replace `${{ ... }}` expressions with bash-safe placeholder identifiers."""
+    exprs: list[str] = []
+
+    def repl(match: re.Match[str]) -> str:
+        exprs.append(match.group(0))
+        return f"__GHA_EXPR_{len(exprs) - 1}__"
+
+    return _GHA_EXPR_RE.sub(repl, text), exprs
+
+
+def _decode_gha_exprs(text: str, exprs: list[str]) -> str:
+    """Restore `${{ ... }}` expressions from placeholder identifiers."""
+    return _GHA_PLACEHOLDER_RE.sub(lambda m: exprs[int(m.group(1))], text)
+
+
+def shfmt_via_hook(tmp_path: Path) -> tuple[bool, str]:
+    # `${{ ... }}` is not valid shell, so swap it for a placeholder identifier
+    # that shfmt can parse, then restore it after formatting.
+    encoded, exprs = _encode_gha_exprs(tmp_path.read_text())
+    if exprs:
+        tmp_path.write_text(encoded)
+    res = subprocess.run(
+        [_HOOK_RUNNER, "run", "shfmt", "--files", str(tmp_path)],
+        cwd=REPO,
+        capture_output=True,
+        text=True,
+    )
+    output = res.stdout + res.stderr
+    # shfmt emits parse errors as "<path>:<line>:<col>: <message>".
+    parse_err = bool(_SHFMT_ERR_RE.search(output))
+    # A non-zero exit that is neither a parse error nor pre-commit's "I had
+    # to modify files" signal means the hook itself failed to run (missing
+    # binary, install failure, bad config, ...). Surface that loudly rather
+    # than silently treating it as a no-op.
+    if (
+        res.returncode != 0
+        and not parse_err
+        and "files were modified by this hook" not in output
+    ):
+        sys.exit(
+            f"error: `{_HOOK_RUNNER} run shfmt` failed with exit {res.returncode}:\n{output}"
+        )
+    if exprs and not parse_err:
+        tmp_path.write_text(_decode_gha_exprs(tmp_path.read_text(), exprs))
+    return not parse_err, output
+
+
+def _skip(path: Path, where: int, kind: str, output: str) -> None:
+    print(
+        f"  shfmt could not parse {kind} at {path}:{where + 1} — skipped",
+        file=sys.stderr,
+    )
+    print(f"    {output.strip()}", file=sys.stderr)
+
+
+def process_yaml_file(path: Path, tmp_path: Path) -> int:
+    text = path.read_text()
+    had_nl = text.endswith("\n")
+    lines = text.split("\n")
+    if had_nl:
+        lines = lines[:-1]
+    items = find_run_blocks(lines)
+    if not items:
+        return 0
+    changed = 0
+    # Process in reverse so earlier indices remain valid as we splice.
+    for item in reversed(items):
+        if isinstance(item, BlockRun):
+            body = lines[item.body_start : item.body_end]
+            tmp_path.write_text("\n".join(dedent(body, item.body_indent)) + "\n")
+            ok, output = shfmt_via_hook(tmp_path)
+            if not ok:
+                _skip(path, item.body_start, "block", output)
+                continue
+            formatted = tmp_path.read_text().rstrip("\n")
+            new_body = reindent(formatted.split("\n"), item.body_indent)
+            if new_body != body:
+                lines[item.body_start : item.body_end] = new_body
+                changed += 1
+        else:
+            tmp_path.write_text(item.value + "\n")
+            ok, output = shfmt_via_hook(tmp_path)
+            if not ok:
+                _skip(path, item.line_idx, "inline run", output)
+                continue
+            formatted = tmp_path.read_text().rstrip("\n")
+            if formatted == item.value:
+                continue
+            formatted_lines = formatted.split("\n")
+            if len(formatted_lines) == 1:
+                lines[item.line_idx] = f"{item.prefix}run: {formatted}"
+            else:
+                body_indent = len(item.prefix) + 2
+                lines[item.line_idx : item.line_idx + 1] = [
+                    f"{item.prefix}run: |",
+                    *reindent(formatted_lines, body_indent),
+                ]
+            changed += 1
+    new_text = "\n".join(lines) + ("\n" if had_nl else "")
+    if new_text != text:
+        path.write_text(new_text)
+    return changed
+
+
+def process_md_file(path: Path, tmp_path: Path) -> int:
+    text = path.read_text()
+    had_nl = text.endswith("\n")
+    lines = text.split("\n")
+    if had_nl:
+        lines = lines[:-1]
+    blocks = find_md_bash_blocks(lines)
+    if not blocks:
+        return 0
+    changed = 0
+    for block in reversed(blocks):
+        body = lines[block.body_start : block.body_end]
+        tmp_path.write_text("\n".join(dedent(body, block.body_indent)) + "\n")
+        ok, output = shfmt_via_hook(tmp_path)
+        if not ok:
+            _skip(path, block.open_line_idx, "```bash block", output)
+            continue
+        formatted = tmp_path.read_text().rstrip("\n")
+        formatted_lines = formatted.split("\n") if formatted else []
+        new_body = reindent(formatted_lines, block.body_indent)
+        if new_body != body:
+            lines[block.body_start : block.body_end] = new_body
+            changed += 1
+    new_text = "\n".join(lines) + ("\n" if had_nl else "")
+    if new_text != text:
+        path.write_text(new_text)
+    return changed
+
+
+def process_file(path: Path, tmp_path: Path) -> int:
+    if path.suffix in (".yml", ".yaml"):
+        return process_yaml_file(path, tmp_path)
+    if path.suffix == ".md":
+        return process_md_file(path, tmp_path)
+    return 0
+
+
+def gather_files(argv: list[str]) -> list[Path]:
+    """Return YAML workflow/action files and markdown files that we should
+    process — either the paths in `argv` or, when `argv` is empty, every
+    such file in the repo (skipping `external/`)."""
+    if argv:
+        candidates: list[Path] = [
+            (REPO / a).resolve() if not Path(a).is_absolute() else Path(a) for a in argv
+        ]
+    else:
+        gh = REPO / ".github"
+        candidates = [
+            *gh.rglob("*.yml"),
+            *gh.rglob("*.yaml"),
+            *(
+                p
+                for p in REPO.rglob("*.md")
+                if "external" not in p.relative_to(REPO).parts
+            ),
+        ]
+    return sorted(
+        p
+        for p in candidates
+        if p.exists()
+        and (
+            (p.suffix in (".yml", ".yaml") and ".github" in p.parts)
+            or p.suffix == ".md"
+        )
+    )
+
+
+def main(argv: list[str]) -> int:
+    files = gather_files(argv)
+    if not files:
+        return 0
+    with tempfile.TemporaryDirectory(prefix="format-inline-bash-") as tmpdir:
+        tmp_path = Path(tmpdir) / "shfmt.sh"
+        total = 0
+        for f in files:
+            n = process_file(f, tmp_path)
+            if n:
+                print(f"{f.relative_to(REPO)}: reformatted {n} block(s)")
+                total += n
+        return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

.github/scripts/rename/binary.sh

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi

.github/scripts/rename/cmake.sh

@@ -8,12 +8,12 @@ set -e
 SED_COMMAND=sed
 HEAD_COMMAND=head
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi
     SED_COMMAND=gsed
-    if ! command -v ghead &> /dev/null; then
+    if ! command -v ghead &>/dev/null; then
         echo "Error: ghead is not installed. Please install it using 'brew install coreutils'."
         exit 1
     fi
@@ -74,10 +74,10 @@ if grep -q '"xrpld"' cmake/XrplCore.cmake; then
     # The script has been rerun, so just restore the name of the binary.
     ${SED_COMMAND} -i 's/"xrpld"/"rippled"/' cmake/XrplCore.cmake
 elif ! grep -q '"rippled"' cmake/XrplCore.cmake; then
-    ${HEAD_COMMAND} -n -1 cmake/XrplCore.cmake > cmake.tmp
-    echo '  # For the time being, we will keep the name of the binary as it was.' >> cmake.tmp
-    echo '  set_target_properties(xrpld PROPERTIES OUTPUT_NAME "rippled")' >> cmake.tmp
-    tail -1 cmake/XrplCore.cmake >> cmake.tmp
+    ${HEAD_COMMAND} -n -1 cmake/XrplCore.cmake >cmake.tmp
+    echo '  # For the time being, we will keep the name of the binary as it was.' >>cmake.tmp
+    echo '  set_target_properties(xrpld PROPERTIES OUTPUT_NAME "rippled")' >>cmake.tmp
+    tail -1 cmake/XrplCore.cmake >>cmake.tmp
     mv cmake.tmp cmake/XrplCore.cmake
 fi
 

.github/scripts/rename/config.sh

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi

.github/scripts/rename/copyright.sh

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi
@@ -62,37 +62,37 @@ done
 # restoring the verbiage that is already present in LICENSE.md. Ensure that if
 # the script is run multiple times, duplicate notices are not added.
 if ! grep -q 'Raw Material Software' include/xrpl/beast/core/CurrentThreadName.h; then
-    echo -e "// Portions of this file are from JUCE (http://www.juce.com).\n// Copyright (c) 2013 - Raw Material Software Ltd.\n// Please visit http://www.juce.com\n\n$(cat include/xrpl/beast/core/CurrentThreadName.h)" > include/xrpl/beast/core/CurrentThreadName.h
+    echo -e "// Portions of this file are from JUCE (http://www.juce.com).\n// Copyright (c) 2013 - Raw Material Software Ltd.\n// Please visit http://www.juce.com\n\n$(cat include/xrpl/beast/core/CurrentThreadName.h)" >include/xrpl/beast/core/CurrentThreadName.h
 fi
 if ! grep -q 'Dev Null' src/test/app/NetworkID_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/NetworkID_test.cpp)" > src/test/app/NetworkID_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/NetworkID_test.cpp)" >src/test/app/NetworkID_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/app/tx/apply_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/tx/apply_test.cpp)" > src/test/app/tx/apply_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/tx/apply_test.cpp)" >src/test/app/tx/apply_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/rpc/ManifestRPC_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ManifestRPC_test.cpp)" > src/test/rpc/ManifestRPC_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ManifestRPC_test.cpp)" >src/test/rpc/ManifestRPC_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/rpc/ValidatorInfo_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ValidatorInfo_test.cpp)" > src/test/rpc/ValidatorInfo_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ValidatorInfo_test.cpp)" >src/test/rpc/ValidatorInfo_test.cpp
 fi
 if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/server_info/Manifest.cpp; then
-    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/server_info/Manifest.cpp)" > src/xrpld/rpc/handlers/server_info/Manifest.cpp
+    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/server_info/Manifest.cpp)" >src/xrpld/rpc/handlers/server_info/Manifest.cpp
 fi
 if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp; then
-    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp)" > src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
+    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp)" >src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/SlabAllocator.h; then
-    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/SlabAllocator.h)" > include/xrpl/basics/SlabAllocator.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/SlabAllocator.h)" >include/xrpl/basics/SlabAllocator.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/spinlock.h; then
-    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/spinlock.h)" > include/xrpl/basics/spinlock.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/spinlock.h)" >include/xrpl/basics/spinlock.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/tagged_integer.h; then
-    echo -e "// Copyright (c) 2014, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/tagged_integer.h)" > include/xrpl/basics/tagged_integer.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2014, Nikolaos D. Bougalis <nikb@bougalis.net>\n\n$(cat include/xrpl/basics/tagged_integer.h)" >include/xrpl/basics/tagged_integer.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Ritchford' include/xrpl/beast/utility/Zero.h; then
-    echo -e "// Copyright (c) 2014, Tom Ritchford <tom@swirly.com>\n\n$(cat include/xrpl/beast/utility/Zero.h)" > include/xrpl/beast/utility/Zero.h # cspell: ignore Ritchford
+    echo -e "// Copyright (c) 2014, Tom Ritchford <tom@swirly.com>\n\n$(cat include/xrpl/beast/utility/Zero.h)" >include/xrpl/beast/utility/Zero.h # cspell: ignore Ritchford
 fi
 
 # Restore newlines and tabs in string literals in the affected file.

.github/scripts/rename/definitions.sh

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi

.github/scripts/rename/docs.sh

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi

.github/scripts/rename/namespace.sh

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
         echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
         exit 1
     fi

.github/workflows/build-nix-image.yml

@@ -6,14 +6,16 @@ on:
       - develop
     paths:
       - ".github/workflows/build-nix-image.yml"
-      - "docker/nix.Dockerfile"
+      - ".github/workflows/reusable-build-docker-image.yml"
+      - "docker/**"
       - "flake.nix"
       - "flake.lock"
       - "nix/**"
   pull_request:
     paths:
       - ".github/workflows/build-nix-image.yml"
-      - "docker/nix.Dockerfile"
+      - ".github/workflows/reusable-build-docker-image.yml"
+      - "docker/**"
       - "flake.nix"
       - "flake.lock"
       - "nix/**"
@@ -27,75 +29,81 @@ defaults:
   run:
     shell: bash
 
-env:
-  UBUNTU_VERSION: "20.04"
-  RHEL_VERSION: "9"
-  DEBIAN_VERSION: "bookworm"
-
 jobs:
   build:
-    name: Build and push Nix image (${{ matrix.distro }})
+    name: Build ${{ matrix.distro.name }} (${{ matrix.target.platform }})
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        # The base images are the oldest supported version of each distro
+        # that we want to build images for.
+        distro:
+          - name: nixos
+            base_image: nixos/nix:latest
+          - name: ubuntu
+            base_image: ubuntu:20.04
+          - name: rhel
+            base_image: registry.access.redhat.com/ubi9/ubi:latest
+          - name: debian
+            base_image: debian:bookworm
+        target:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    uses: ./.github/workflows/reusable-build-docker-image.yml
+    with:
+      image_name: ghcr.io/xrplf/xrpld/nix-${{ matrix.distro.name }}
+      dockerfile: docker/nix.Dockerfile
+      base_image: ${{ matrix.distro.base_image }}
+      platform: ${{ matrix.target.platform }}
+      runner: ${{ matrix.target.runner }}
+      push: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' }}
+
+  merge:
+    name: Merge ${{ matrix.distro }} manifest
+    needs: build
+    if: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
       packages: write
     strategy:
+      fail-fast: false
       matrix:
-        include:
-          - distro: nixos
-          - distro: ubuntu
-          - distro: rhel
-          - distro: debian
+        distro: [nixos, ubuntu, rhel, debian]
+    env:
+      IMAGE_NAME: ghcr.io/xrplf/xrpld/nix-${{ matrix.distro }}
 
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Determine base image
-        id: vars
-        run: |
-          case "${{ matrix.distro }}" in
-            nixos)
-              echo "base_image=nixos/nix:latest" >> $GITHUB_OUTPUT
-              ;;
-            ubuntu)
-              echo "base_image=ubuntu:${UBUNTU_VERSION}" >> $GITHUB_OUTPUT
-              ;;
-            rhel)
-              echo "base_image=registry.access.redhat.com/ubi${RHEL_VERSION}/ubi:latest" >> $GITHUB_OUTPUT
-              ;;
-            debian)
-              echo "base_image=debian:${DEBIAN_VERSION}" >> $GITHUB_OUTPUT
-              ;;
-          esac
-
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-,format=short
+            type=raw,value=latest
 
       - name: Login to GitHub Container Registry
-        if: github.event_name == 'push'
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Docker metadata
-        id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
-        with:
-          images: ghcr.io/xrplf/ci/nix-${{ matrix.distro }}
-          tags: |
-            type=sha,prefix=sha-,format=short
-            type=raw,value=latest
+      - name: Create multi-arch manifests
+        run: |
+          for tag in $(jq -cr '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
+              docker buildx imagetools create -t "$tag" "${tag}-amd64" "${tag}-arm64"
+          done
 
-      - name: Build and push
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
-        with:
-          context: .
-          file: docker/nix.Dockerfile
-          platforms: linux/amd64
-          push: ${{ github.event_name == 'push' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          build-args: BASE_IMAGE=${{ steps.vars.outputs.base_image }}
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect "${IMAGE_NAME}:${{ steps.meta.outputs.version }}"

.github/workflows/check-pr-description.yml

@@ -5,8 +5,17 @@ on:
     types:
       - checks_requested
   pull_request:
-    types: [opened, edited, reopened, synchronize, ready_for_review]
-    branches: [develop]
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+    branches:
+      - develop
+      - "release-*"
+      - "release/*"
+      - "staging/*"
 
 jobs:
   check_description:
@@ -20,11 +29,11 @@ jobs:
         env:
           PR_BODY: ${{ github.event.pull_request.body }}
         if: ${{ github.event_name == 'pull_request' }}
-        run: printenv PR_BODY > pr_body.md
+        run: printenv PR_BODY >pr_body.md
 
       - name: Check PR description differs from template
         if: ${{ github.event_name == 'pull_request' }}
-        run: >
-          python .github/scripts/check-pr-description.py
-          --template-file .github/pull_request_template.md
-          --pr-body-file pr_body.md
+        run: |
+          python .github/scripts/check-pr-description.py \
+              --template-file .github/pull_request_template.md \
+              --pr-body-file pr_body.md

.github/workflows/check-pr-title.yml

@@ -5,10 +5,19 @@ on:
     types:
       - checks_requested
   pull_request:
-    types: [opened, edited, reopened, synchronize, ready_for_review]
-    branches: [develop]
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+    branches:
+      - develop
+      - "release-*"
+      - "release/*"
+      - "staging/*"
 
 jobs:
   check_title:
     if: ${{ github.event.pull_request.draft != true }}
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@291206777251b4d493641b5afbdf7c23009d2988
+    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@cba1f0891650baf1a9c88624dc2d72573be2eb81

.github/workflows/on-pr.yml

@@ -98,7 +98,7 @@ jobs:
           READY: ${{ contains(github.event.pull_request.labels.*.name, 'Ready to merge') }}
           MERGE: ${{ github.event_name == 'merge_group' }}
         run: |
-          echo "go=${{ (env.DRAFT != 'true' && env.READY == 'true') || env.FILES == 'true' || env.MERGE == 'true' }}" >> "${GITHUB_OUTPUT}"
+          echo "go=${{ (env.DRAFT != 'true' && env.READY == 'true') || env.FILES == 'true' || env.MERGE == 'true' }}" >>"${GITHUB_OUTPUT}"
           cat "${GITHUB_OUTPUT}"
     outputs:
       go: ${{ steps.go.outputs.go == 'true' }}
@@ -168,9 +168,9 @@ jobs:
           PR_URL: ${{ github.event.pull_request.html_url }}
         run: |
           gh api --method POST -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" \
-          /repos/xrplf/clio/dispatches -f "event_type=check_libxrpl" \
-          -F "client_payload[ref]=${{ needs.upload-recipe.outputs.recipe_ref }}" \
-          -F "client_payload[pr_url]=${PR_URL}"
+              /repos/xrplf/clio/dispatches -f "event_type=check_libxrpl" \
+              -F "client_payload[ref]=${{ needs.upload-recipe.outputs.recipe_ref }}" \
+              -F "client_payload[pr_url]=${PR_URL}"
 
   passed:
     if: failure() || cancelled()

.github/workflows/pre-commit.yml

@@ -14,7 +14,7 @@ on:
 jobs:
   # Call the workflow in the XRPLF/actions repo that runs the pre-commit hooks.
   run-hooks:
-    uses: XRPLF/actions/.github/workflows/pre-commit.yml@5e942d61bf32f7557a7c159cfac4712a687b3e3a
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@cba1f0891650baf1a9c88624dc2d72573be2eb81
     with:
       runs_on: ubuntu-latest
       container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'

.github/workflows/reusable-build-docker-image.yml

@@ -0,0 +1,89 @@
+# Build a single-platform Docker image. On push, the image is pushed to
+# GHCR with arch-suffixed tags (e.g. `:latest-amd64`, `:sha-abc-amd64`)
+# so the calling workflow can stitch per-arch builds into a multi-arch
+# manifest without needing to pass digests around.
+name: Reusable build Docker image (single platform)
+
+on:
+  workflow_call:
+    inputs:
+      image_name:
+        description: "Full image name without tag (e.g. 'ghcr.io/xrplf/xrpld/nix-ubuntu')"
+        required: true
+        type: string
+      dockerfile:
+        description: "Path to the Dockerfile, relative to the repository root"
+        required: true
+        type: string
+      base_image:
+        description: "Value passed to the Dockerfile as the BASE_IMAGE build arg"
+        required: true
+        type: string
+      platform:
+        description: "Docker platform string, e.g. linux/amd64"
+        required: true
+        type: string
+      runner:
+        description: "GitHub Actions runner label to build on"
+        required: true
+        type: string
+      push:
+        description: "Whether to push the image to GHCR"
+        required: true
+        type: boolean
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    name: Build (${{ inputs.platform }})
+    runs-on: ${{ inputs.runner }}
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Determine arch
+        id: vars
+        env:
+          PLATFORM: ${{ inputs.platform }}
+        run: |
+          echo "arch=${PLATFORM##*/}" >>$GITHUB_OUTPUT
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+
+      - name: Login to GitHub Container Registry
+        if: inputs.push
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        with:
+          images: ${{ inputs.image_name }}
+          tags: |
+            type=sha,prefix=sha-,format=short
+            type=raw,value=latest
+          flavor: |
+            suffix=-${{ steps.vars.outputs.arch }},onlatest=true
+
+      - name: Build and push
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        with:
+          context: .
+          file: ${{ inputs.dockerfile }}
+          platforms: ${{ inputs.platform }}
+          push: ${{ inputs.push }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: BASE_IMAGE=${{ inputs.base_image }}

.github/workflows/reusable-build-test-config.yml

@@ -113,7 +113,7 @@ jobs:
 
       - name: Set ccache log file
         if: ${{ inputs.ccache_enabled && runner.debug == '1' }}
-        run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >> "${GITHUB_ENV}"
+        run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >>"${GITHUB_ENV}"
 
       - name: Print build environment
         uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
@@ -146,11 +146,11 @@ jobs:
           CMAKE_ARGS: ${{ inputs.cmake_args }}
         run: |
           cmake \
-            -G '${{ runner.os == 'Windows' && 'Visual Studio 17 2022' || 'Ninja' }}' \
-            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-            -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
-            ${CMAKE_ARGS} \
-            ..
+              -G '${{ runner.os == 'Windows' && 'Visual Studio 17 2022' || 'Ninja' }}' \
+              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
+              -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
+              ${CMAKE_ARGS} \
+              ..
 
       - name: Check protocol autogen files are up-to-date
         working-directory: ${{ env.BUILD_DIR }}
@@ -172,32 +172,32 @@ jobs:
           cmake --build . --target code_gen
           DIFF=$(git -C .. status --porcelain -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen)
           if [ -n "${DIFF}" ]; then
-            echo "::error::Generated protocol files are out of date"
-            git -C .. diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
-            echo "${MESSAGE}"
-            exit 1
+              echo "::error::Generated protocol files are out of date"
+              git -C .. diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
+              echo "${MESSAGE}"
+              exit 1
           fi
 
       - name: Build the binary
         working-directory: ${{ env.BUILD_DIR }}
         env:
-          BUILD_NPROC: ${{ runner.os == 'Linux' && '16' || steps.nproc.outputs.nproc }}
+          BUILD_NPROC: ${{ steps.nproc.outputs.nproc }}
           BUILD_TYPE: ${{ inputs.build_type }}
           CMAKE_TARGET: ${{ inputs.cmake_target }}
         run: |
           cmake \
-            --build . \
-            --config "${BUILD_TYPE}" \
-            --parallel "${BUILD_NPROC}" \
-            --target "${CMAKE_TARGET}"
+              --build . \
+              --config "${BUILD_TYPE}" \
+              --parallel "${BUILD_NPROC}" \
+              --target "${CMAKE_TARGET}"
 
       - name: Show ccache statistics
         if: ${{ inputs.ccache_enabled }}
         run: |
           ccache --show-stats -vv
           if [ '${{ runner.debug }}' = '1' ]; then
-            cat "${CCACHE_LOGFILE}"
-            curl ${CCACHE_REMOTE_STORAGE%|*}/status || true
+              cat "${CCACHE_LOGFILE}"
+              curl ${CCACHE_REMOTE_STORAGE%|*}/status || true
           fi
 
       - name: Upload the binary (Linux)
@@ -214,7 +214,7 @@ jobs:
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           set -o pipefail
-          ./xrpld --definitions | python3 -m json.tool > server_definitions.json
+          ./xrpld --definitions | python3 -m json.tool >server_definitions.json
 
       - name: Upload server definitions
         if: ${{ github.event.repository.visibility == 'public' && inputs.config_name == 'debian-bookworm-gcc-13-amd64-release' }}
@@ -231,10 +231,10 @@ jobs:
         run: |
           ldd ./xrpld
           if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+|libgcc)' | wc -l)" -eq 0 ]; then
-            echo 'The binary is statically linked.'
+              echo 'The binary is statically linked.'
           else
-            echo 'The binary is dynamically linked.'
-            exit 1
+              echo 'The binary is dynamically linked.'
+              exit 1
           fi
 
       - name: Verify presence of instrumentation (Linux)
@@ -250,12 +250,12 @@ jobs:
         run: |
           ASAN_OPTS="include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-asan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/asan.supp"
           if [[ "${CONFIG_NAME}" == *gcc* ]]; then
-            ASAN_OPTS="${ASAN_OPTS}:alloc_dealloc_mismatch=0"
+              ASAN_OPTS="${ASAN_OPTS}:alloc_dealloc_mismatch=0"
           fi
-          echo "ASAN_OPTIONS=${ASAN_OPTS}" >> ${GITHUB_ENV}
-          echo "TSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-tsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/tsan.supp" >> ${GITHUB_ENV}
-          echo "UBSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-ubsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/ubsan.supp" >> ${GITHUB_ENV}
-          echo "LSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-lsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/lsan.supp" >> ${GITHUB_ENV}
+          echo "ASAN_OPTIONS=${ASAN_OPTS}" >>${GITHUB_ENV}
+          echo "TSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-tsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/tsan.supp" >>${GITHUB_ENV}
+          echo "UBSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-ubsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/ubsan.supp" >>${GITHUB_ENV}
+          echo "LSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-lsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/lsan.supp" >>${GITHUB_ENV}
 
       - name: Run the separate tests
         if: ${{ !inputs.build_only }}
@@ -266,9 +266,9 @@ jobs:
           PARALLELISM: ${{ runner.os == 'Windows' && '1' || steps.nproc.outputs.nproc }}
         run: |
           ctest \
-            --output-on-failure \
-            -C "${BUILD_TYPE}" \
-            -j "${PARALLELISM}"
+              --output-on-failure \
+              -C "${BUILD_TYPE}" \
+              -j "${PARALLELISM}"
 
       - name: Run the embedded tests
         if: ${{ !inputs.build_only }}
@@ -278,7 +278,7 @@ jobs:
         run: |
           set -o pipefail
           # Coverage builds are slower due to instrumentation; use fewer parallel jobs to avoid flakiness
-          [ "$COVERAGE_ENABLED" = "true" ] && BUILD_NPROC=$(( BUILD_NPROC - 2 ))
+          [ "$COVERAGE_ENABLED" = "true" ] && BUILD_NPROC=$((BUILD_NPROC - 2))
           ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee unittest.log
 
       - name: Show test failure summary
@@ -287,19 +287,19 @@ jobs:
           WORKING_DIR: ${{ runner.os == 'Windows' && format('{0}\{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
         run: |
           if [ ! -d "${WORKING_DIR}" ]; then
-            echo "Working directory '${WORKING_DIR}' does not exist."
-            exit 0
+              echo "Working directory '${WORKING_DIR}' does not exist."
+              exit 0
           fi
 
           cd "${WORKING_DIR}"
 
           if [ ! -f unittest.log ]; then
-            echo "unittest.log not found; embedded tests may not have run."
-            exit 0
+              echo "unittest.log not found; embedded tests may not have run."
+              exit 0
           fi
 
           if ! grep -E "failed" unittest.log; then
-            echo "Log present but no failure lines found in unittest.log."
+              echo "Log present but no failure lines found in unittest.log."
           fi
       - name: Debug failure (Linux)
         if: ${{ failure() && runner.os == 'Linux' && !inputs.build_only }}
@@ -317,14 +317,14 @@ jobs:
           BUILD_TYPE: ${{ inputs.build_type }}
         run: |
           cmake \
-            --build . \
-            --config "${BUILD_TYPE}" \
-            --parallel "${BUILD_NPROC}" \
-            --target coverage
+              --build . \
+              --config "${BUILD_TYPE}" \
+              --parallel "${BUILD_NPROC}" \
+              --target coverage
 
       - name: Upload coverage report
         if: ${{ github.repository == 'XRPLF/rippled' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
         with:
           disable_search: true
           disable_telem: true

.github/workflows/reusable-check-levelization.yml

@@ -38,9 +38,9 @@ jobs:
         run: |
           DIFF=$(git status --porcelain)
           if [ -n "${DIFF}" ]; then
-            # Print the differences to give the contributor a hint about what to
-            # expect when running levelization on their own machine.
-            git diff
-            echo "${MESSAGE}"
-            exit 1
+              # Print the differences to give the contributor a hint about what to
+              # expect when running levelization on their own machine.
+              git diff
+              echo "${MESSAGE}"
+              exit 1
           fi

.github/workflows/reusable-check-rename.yml

@@ -48,9 +48,9 @@ jobs:
         run: |
           DIFF=$(git status --porcelain)
           if [ -n "${DIFF}" ]; then
-            # Print the differences to give the contributor a hint about what to
-            # expect when running the renaming scripts on their own machine.
-            git diff
-            echo "${MESSAGE}"
-            exit 1
+              # Print the differences to give the contributor a hint about what to
+              # expect when running the renaming scripts on their own machine.
+              git diff
+              echo "${MESSAGE}"
+              exit 1
           fi

.github/workflows/reusable-clang-tidy.yml

@@ -70,13 +70,13 @@ jobs:
         working-directory: ${{ env.BUILD_DIR }}
         run: |
           cmake \
-            -G 'Ninja' \
-            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-            -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
-            -Dtests=ON \
-            -Dwerr=ON \
-            -Dxrpld=ON \
-            ..
+              -G 'Ninja' \
+              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
+              -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
+              -Dtests=ON \
+              -Dwerr=ON \
+              -Dxrpld=ON \
+              ..
 
       # clang-tidy needs headers generated from proto files
       - name: Build libxrpl.libpb
@@ -133,7 +133,7 @@ jobs:
       - name: Write issue header
         if: ${{ steps.run_clang_tidy.outcome != 'success' }}
         run: |
-          cat > "${ISSUE_FILE}" <<EOF
+          cat >"${ISSUE_FILE}" <<EOF
           ## Clang-tidy Check Failed
 
           ### Clang-tidy Output:
@@ -144,30 +144,30 @@ jobs:
         if: ${{ steps.run_clang_tidy.outcome != 'success' }}
         run: |
           if [ -f "${OUTPUT_FILE}" ]; then
-            # Extract lines containing 'error:', 'warning:', or 'note:'
-            grep -E '(error:|warning:|note:)' "${OUTPUT_FILE}" > filtered-output.txt || true
+              # Extract lines containing 'error:', 'warning:', or 'note:'
+              grep -E '(error:|warning:|note:)' "${OUTPUT_FILE}" >filtered-output.txt || true
 
-            # If filtered output is empty, use original (might be a different error format)
-            if [ ! -s filtered-output.txt ]; then
-              cp "${OUTPUT_FILE}" filtered-output.txt
-            fi
+              # If filtered output is empty, use original (might be a different error format)
+              if [ ! -s filtered-output.txt ]; then
+                  cp "${OUTPUT_FILE}" filtered-output.txt
+              fi
 
-            # Truncate if too large
-            head -c 60000 filtered-output.txt >> "${ISSUE_FILE}"
-            if [ "$(wc -c < filtered-output.txt)" -gt 60000 ]; then
-              echo "" >> "${ISSUE_FILE}"
-              echo "... (output truncated, see artifacts for full output)" >> "${ISSUE_FILE}"
-            fi
+              # Truncate if too large
+              head -c 60000 filtered-output.txt >>"${ISSUE_FILE}"
+              if [ "$(wc -c <filtered-output.txt)" -gt 60000 ]; then
+                  echo "" >>"${ISSUE_FILE}"
+                  echo "... (output truncated, see artifacts for full output)" >>"${ISSUE_FILE}"
+              fi
 
-            rm filtered-output.txt
+              rm filtered-output.txt
           else
-            echo "No output file found" >> "${ISSUE_FILE}"
+              echo "No output file found" >>"${ISSUE_FILE}"
           fi
 
       - name: Append issue footer
         if: ${{ steps.run_clang_tidy.outcome != 'success' }}
         run: |
-          cat >> "${ISSUE_FILE}" <<EOF
+          cat >>"${ISSUE_FILE}" <<EOF
           \`\`\`
 
           ---
@@ -176,7 +176,7 @@ jobs:
 
       - name: Create issue
         if: ${{ steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure }}
-        uses: XRPLF/actions/create-issue@36d450d12d301e8410c1b7936e5de70c291cbe36
+        uses: XRPLF/actions/create-issue@2b8bc36af85b88bca0dd7bfac2e2dc05f94ad712
         with:
           title: "Clang-tidy check failed"
           body_file: ${{ env.ISSUE_FILE }}

.github/workflows/reusable-package.yml

@@ -39,7 +39,7 @@ jobs:
         id: generate
         working-directory: .github/scripts/strategy-matrix
         run: |
-          ./generate.py --packaging --config=linux.json >> "${GITHUB_OUTPUT}"
+          ./generate.py --packaging --config=linux.json >>"${GITHUB_OUTPUT}"
 
   generate-version:
     runs-on: ubuntu-latest

.github/workflows/reusable-strategy-matrix.yml

@@ -42,4 +42,4 @@ jobs:
         env:
           GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}.json', inputs.os) || '' }}
           GENERATE_OPTION: ${{ inputs.strategy_matrix == 'all' && '--all' || '' }}
-        run: ./generate.py ${GENERATE_OPTION} ${GENERATE_CONFIG} >> "${GITHUB_OUTPUT}"
+        run: ./generate.py ${GENERATE_OPTION} ${GENERATE_CONFIG} >>"${GITHUB_OUTPUT}"

.pre-commit-config.yaml

@@ -37,37 +37,50 @@ repos:
         exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
 
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: cd481d7b0bfb5c7b3090c21846317f9a8262e891 # frozen: v22.1.0
+    rev: dd18dad857d6133e90bbe478f4f2f22ec0030269 # frozen: v22.1.5
     hooks:
       - id: clang-format
         args: [--style=file]
         "types_or": [c++, c, proto]
         exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
 
-  - repo: https://github.com/BlankSpruce/gersemi
-    rev: 0.26.0
+  - repo: https://github.com/BlankSpruce/gersemi-pre-commit
+    rev: faadd6a9d852369ca94f4d15b2404c967ba8cb01 # frozen: 0.27.6
     hooks:
       - id: gersemi
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: c2bc67fe8f8f549cc489e00ba8b45aa18ee713b1 # frozen: v3.8.1
+    rev: 515f543f5718ebfd6ce22e16708bb32c68ff96e1 # frozen: v3.8.3
     hooks:
       - id: prettier
         args: [--end-of-line=auto]
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: ea488cebbfd88a5f50b8bd95d5c829d0bb76feb8 # frozen: 26.1.0
+    rev: 4160603246a6b365d4a2af661c6d71b0a0f50478 # frozen: 26.5.1
     hooks:
       - id: black
 
-  - repo: https://github.com/openstack/bashate
-    rev: 5798d24d571676fc407e81df574c1ef57b520f23 # frozen: 2.1.1
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: 05c1426671b9237fb5e1444dd63aa5731bec0dfb # frozen: v3.13.1-1
     hooks:
-      - id: bashate
-        args: ["--ignore=E006"]
+      - id: shfmt
+        args: [--write, --indent=4, --case-indent=true]
+
+  - repo: local
+    hooks:
+      - id: format-inline-bash-workflows
+        name: "format `run:` blocks in workflows/actions"
+        entry: ./.github/scripts/format-inline-bash.py
+        language: python
+        files: ^\.github/(workflows|actions)/.*\.ya?ml$
+      - id: format-inline-bash-markdown
+        name: "format ```bash blocks in markdown"
+        entry: ./.github/scripts/format-inline-bash.py
+        language: python
+        files: \.md$
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: a42085ade523f591dca134379a595e7859986445 # frozen: v9.7.0
+    rev: 4643f154907327ee0a2c7038f0296e0dd77d9776 # frozen: v10.0.0
     hooks:
       - id: cspell # Spell check changed files
         exclude: |

BUILD.md

@@ -151,8 +151,8 @@ git init
 git remote add origin git@github.com:XRPLF/conan-center-index.git
 git sparse-checkout init
 for recipe in "${recipes[@]}"; do
-  echo "Checking out recipe '${recipe}'..."
-  git sparse-checkout add recipes/${recipe}
+    echo "Checking out recipe '${recipe}'..."
+    git sparse-checkout add recipes/${recipe}
 done
 git fetch origin master
 git checkout master
@@ -180,7 +180,7 @@ the new recipe will be automatically pulled from the official Conan Center.
 
 If you see an error similar to the following after running `conan profile show`:
 
-```bash
+```text
 ERROR: Invalid setting '17' is not a valid 'settings.compiler.version' value.
 Possible values are ['5.0', '5.1', '6.0', '6.1', '7.0', '7.3', '8.0', '8.1',
 '9.0', '9.1', '10.0', '11.0', '12.0', '13', '13.0', '13.1', '14', '14.0', '15',

bin/git/setup-upstreams.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
 if [[ $# -ne 1 || "$1" == "--help" || "$1" == "-h" ]]; then
-    name=$( basename $0 )
-    cat <<- USAGE
+    name=$(basename $0)
+    cat <<-USAGE
     Usage: $name <username>
 
     Where <username> is the Github username of the upstream repo. e.g. XRPLF
@@ -14,7 +14,7 @@ fi
 shift
 user="$1"
 # Get the origin URL. Expect it be an SSH-style URL
-origin=$( git remote get-url origin )
+origin=$(git remote get-url origin)
 if [[ "${origin}" == "" ]]; then
     echo Invalid origin remote >&2
     exit 1
@@ -22,11 +22,11 @@ fi
 # echo "Origin: ${origin}"
 # Parse the origin
 ifs_orig="${IFS}"
-IFS=':' read remote originpath <<< "${origin}"
+IFS=':' read remote originpath <<<"${origin}"
 # echo "Remote: ${remote}, Originpath: ${originpath}"
-IFS='@' read sshuser server <<< "${remote}"
+IFS='@' read sshuser server <<<"${remote}"
 # echo "SSHUser: ${sshuser}, Server: ${server}"
-IFS='/' read originuser repo <<< "${originpath}"
+IFS='/' read originuser repo <<<"${originpath}"
 # echo "Originuser: ${originuser}, Repo: ${repo}"
 if [[ "${sshuser}" == "" || "${server}" == "" || "${originuser}" == "" || "${repo}" == "" ]]; then
     echo "Can't parse origin URL: ${origin}" >&2
@@ -35,9 +35,9 @@ fi
 upstream="https://${server}/${user}/${repo}"
 upstreampush="${remote}:${user}/${repo}"
 upstreamgroup="upstream upstream-push"
-current=$( git remote get-url upstream 2>/dev/null )
-currentpush=$( git remote get-url upstream-push 2>/dev/null )
-currentgroup=$( git config remotes.upstreams )
+current=$(git remote get-url upstream 2>/dev/null)
+currentpush=$(git remote get-url upstream-push 2>/dev/null)
+currentgroup=$(git config remotes.upstreams)
 if [[ "${current}" == "${upstream}" ]]; then
     echo "Upstream already set up correctly. Skip"
 elif [[ -n "${current}" && "${current}" != "${upstream}" && "${current}" != "${upstreampush}" ]]; then
@@ -45,9 +45,9 @@ elif [[ -n "${current}" && "${current}" != "${upstream}" && "${current}" != "${u
 else
     if [[ "${current}" == "${upstreampush}" ]]; then
         echo "Upstream set to dangerous push URL. Update."
-        _run git remote rename upstream upstream-push || \
-        _run git remote remove upstream
-        currentpush=$( git remote get-url upstream-push 2>/dev/null )
+        _run git remote rename upstream upstream-push ||
+            _run git remote remove upstream
+        currentpush=$(git remote get-url upstream-push 2>/dev/null)
     fi
     _run git remote add upstream "${upstream}"
 fi

bin/git/squash-branches.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
 if [[ $# -lt 3 || "$1" == "--help" || "$1" = "-h" ]]; then
-    name=$( basename $0 )
-    cat <<- USAGE
+    name=$(basename $0)
+    cat <<-USAGE
     Usage: $name workbranch base/branch user/branch [user/branch [...]]
 
     * workbranch will be created locally from base/branch
@@ -16,7 +16,7 @@ fi
 work="$1"
 shift
 
-branches=( $( echo "${@}" | sed "s/:/\//" ) )
+branches=($(echo "${@}" | sed "s/:/\//"))
 base="${branches[0]}"
 unset branches[0]
 
@@ -24,10 +24,10 @@ set -e
 
 users=()
 for b in "${branches[@]}"; do
-    users+=( $( echo $b | cut -d/ -f1 ) )
+    users+=($(echo $b | cut -d/ -f1))
 done
 
-users=( $( printf '%s\n' "${users[@]}" | sort -u ) )
+users=($(printf '%s\n' "${users[@]}" | sort -u))
 
 git fetch --multiple upstreams "${users[@]}"
 git checkout -B "$work" --no-track "$base"
@@ -40,7 +40,7 @@ done
 # Make sure the commits look right
 git log --show-signature "$base..HEAD"
 
-parts=( $( echo $base | sed "s/\// /" ) )
+parts=($(echo $base | sed "s/\// /"))
 repo="${parts[0]}"
 b="${parts[1]}"
 push=$repo
@@ -50,7 +50,7 @@ fi
 if [[ "$repo" == "upstream" ]]; then
     repo="upstreams"
 fi
-cat << PUSH
+cat <<PUSH
 
 -------------------------------------------------------------------
 This script will not push. Verify everything is correct, then push

bin/git/update-version.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
 if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]; then
-    name=$( basename $0 )
-    cat <<- USAGE
+    name=$(basename $0)
+    cat <<-USAGE
     Usage: $name workbranch base/branch version
 
     * workbranch will be created locally from base/branch. If it exists,
@@ -16,7 +16,7 @@ fi
 work="$1"
 shift
 
-base=$( echo "$1" | sed "s/:/\//" )
+base=$(echo "$1" | sed "s/:/\//")
 shift
 
 version=$1
@@ -28,16 +28,16 @@ git fetch upstreams
 
 git checkout -B "${work}" --no-track "${base}"
 
-push=$( git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
-    2>/dev/null ) || true
+push=$(git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
+    2>/dev/null) || true
 if [[ "${push}" != "" ]]; then
     echo "Warning: ${push} may already exist."
 fi
 
-build=$( find -name BuildInfo.cpp )
-sed 's/\(^.*versionString =\).*$/\1 "'${version}'"/' ${build} > version.cpp && \
-diff "${build}" version.cpp && exit 1 || \
-mv -vi version.cpp ${build}
+build=$(find -name BuildInfo.cpp)
+sed 's/\(^.*versionString =\).*$/\1 "'${version}'"/' ${build} >version.cpp &&
+    diff "${build}" version.cpp && exit 1 ||
+    mv -vi version.cpp ${build}
 
 git diff
 
@@ -47,7 +47,7 @@ git commit -S -m "Set version to ${version}"
 
 git log --oneline --first-parent ${base}^..
 
-cat << PUSH
+cat <<PUSH
 
 -------------------------------------------------------------------
 This script will not push. Verify everything is correct, then push

bin/pre-commit/clang_tidy_check.py

@@ -168,7 +168,13 @@ def main():
     if not os.environ.get("TIDY"):
         return 0
 
-    repo_root = Path(__file__).parent.parent
+    repo_root = Path(
+        subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=Path(__file__).parent,
+            text=True,
+        ).strip()
+    )
     files = staged_files(repo_root)
     if not files:
         return 0

cmake/scripts/codegen/requirements.in

@@ -0,0 +1,13 @@
+# Python dependencies for XRP Ledger code generation scripts
+#
+# These packages are required to run the code generation scripts that
+# parse macro files and generate C++ wrapper classes.
+
+# C preprocessor for Python - used to preprocess macro files
+pcpp>=1.30
+
+# Parser combinator library - used to parse the macro DSL
+pyparsing>=3.0.0
+
+# Template engine - used to generate C++ code from templates
+Mako>=1.2.2

cmake/scripts/codegen/requirements.txt

@@ -1,13 +1,105 @@
-# Python dependencies for XRP Ledger code generation scripts
-#
-# These packages are required to run the code generation scripts that
-# parse macro files and generate C++ wrapper classes.
-
-# C preprocessor for Python - used to preprocess macro files
-pcpp>=1.30
-
-# Parser combinator library - used to parse the macro DSL
-pyparsing>=3.0.0
-
-# Template engine - used to generate C++ code from templates
-Mako>=1.2.2
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements.in --generate-hashes --output-file requirements.txt
+mako==1.3.12 \
+    --hash=sha256:8f61569480282dbf557145ce441e4ba888be453c30989f879f0d652e39f53ea9 \
+    --hash=sha256:9f778e93289bd410bb35daadeb4fc66d95a746f0b75777b942088b7fd7af550a
+    # via -r requirements.in
+markupsafe==3.0.3 \
+    --hash=sha256:0303439a41979d9e74d18ff5e2dd8c43ed6c6001fd40e5bf2e43f7bd9bbc523f \
+    --hash=sha256:068f375c472b3e7acbe2d5318dea141359e6900156b5b2ba06a30b169086b91a \
+    --hash=sha256:0bf2a864d67e76e5c9a34dc26ec616a66b9888e25e7b9460e1c76d3293bd9dbf \
+    --hash=sha256:0db14f5dafddbb6d9208827849fad01f1a2609380add406671a26386cdf15a19 \
+    --hash=sha256:0eb9ff8191e8498cca014656ae6b8d61f39da5f95b488805da4bb029cccbfbaf \
+    --hash=sha256:0f4b68347f8c5eab4a13419215bdfd7f8c9b19f2b25520968adfad23eb0ce60c \
+    --hash=sha256:1085e7fbddd3be5f89cc898938f42c0b3c711fdcb37d75221de2666af647c175 \
+    --hash=sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219 \
+    --hash=sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb \
+    --hash=sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6 \
+    --hash=sha256:1353ef0c1b138e1907ae78e2f6c63ff67501122006b0f9abad68fda5f4ffc6ab \
+    --hash=sha256:15d939a21d546304880945ca1ecb8a039db6b4dc49b2c5a400387cdae6a62e26 \
+    --hash=sha256:177b5253b2834fe3678cb4a5f0059808258584c559193998be2601324fdeafb1 \
+    --hash=sha256:1872df69a4de6aead3491198eaf13810b565bdbeec3ae2dc8780f14458ec73ce \
+    --hash=sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218 \
+    --hash=sha256:1b52b4fb9df4eb9ae465f8d0c228a00624de2334f216f178a995ccdcf82c4634 \
+    --hash=sha256:1ba88449deb3de88bd40044603fafffb7bc2b055d626a330323a9ed736661695 \
+    --hash=sha256:1cc7ea17a6824959616c525620e387f6dd30fec8cb44f649e31712db02123dad \
+    --hash=sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73 \
+    --hash=sha256:26a5784ded40c9e318cfc2bdb30fe164bdb8665ded9cd64d500a34fb42067b1c \
+    --hash=sha256:2713baf880df847f2bece4230d4d094280f4e67b1e813eec43b4c0e144a34ffe \
+    --hash=sha256:2a15a08b17dd94c53a1da0438822d70ebcd13f8c3a95abe3a9ef9f11a94830aa \
+    --hash=sha256:2f981d352f04553a7171b8e44369f2af4055f888dfb147d55e42d29e29e74559 \
+    --hash=sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa \
+    --hash=sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37 \
+    --hash=sha256:3537e01efc9d4dccdf77221fb1cb3b8e1a38d5428920e0657ce299b20324d758 \
+    --hash=sha256:35add3b638a5d900e807944a078b51922212fb3dedb01633a8defc4b01a3c85f \
+    --hash=sha256:38664109c14ffc9e7437e86b4dceb442b0096dfe3541d7864d9cbe1da4cf36c8 \
+    --hash=sha256:3a7e8ae81ae39e62a41ec302f972ba6ae23a5c5396c8e60113e9066ef893da0d \
+    --hash=sha256:3b562dd9e9ea93f13d53989d23a7e775fdfd1066c33494ff43f5418bc8c58a5c \
+    --hash=sha256:457a69a9577064c05a97c41f4e65148652db078a3a509039e64d3467b9e7ef97 \
+    --hash=sha256:4bd4cd07944443f5a265608cc6aab442e4f74dff8088b0dfc8238647b8f6ae9a \
+    --hash=sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19 \
+    --hash=sha256:4faffd047e07c38848ce017e8725090413cd80cbc23d86e55c587bf979e579c9 \
+    --hash=sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9 \
+    --hash=sha256:5678211cb9333a6468fb8d8be0305520aa073f50d17f089b5b4b477ea6e67fdc \
+    --hash=sha256:591ae9f2a647529ca990bc681daebdd52c8791ff06c2bfa05b65163e28102ef2 \
+    --hash=sha256:5a7d5dc5140555cf21a6fefbdbf8723f06fcd2f63ef108f2854de715e4422cb4 \
+    --hash=sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354 \
+    --hash=sha256:6b5420a1d9450023228968e7e6a9ce57f65d148ab56d2313fcd589eee96a7a50 \
+    --hash=sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698 \
+    --hash=sha256:729586769a26dbceff69f7a7dbbf59ab6572b99d94576a5592625d5b411576b9 \
+    --hash=sha256:77f0643abe7495da77fb436f50f8dab76dbc6e5fd25d39589a0f1fe6548bfa2b \
+    --hash=sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc \
+    --hash=sha256:7be7b61bb172e1ed687f1754f8e7484f1c8019780f6f6b0786e76bb01c2ae115 \
+    --hash=sha256:7c3fb7d25180895632e5d3148dbdc29ea38ccb7fd210aa27acbd1201a1902c6e \
+    --hash=sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485 \
+    --hash=sha256:83891d0e9fb81a825d9a6d61e3f07550ca70a076484292a70fde82c4b807286f \
+    --hash=sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12 \
+    --hash=sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025 \
+    --hash=sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009 \
+    --hash=sha256:915c04ba3851909ce68ccc2b8e2cd691618c4dc4c4232fb7982bca3f41fd8c3d \
+    --hash=sha256:949b8d66bc381ee8b007cd945914c721d9aba8e27f71959d750a46f7c282b20b \
+    --hash=sha256:94c6f0bb423f739146aec64595853541634bde58b2135f27f61c1ffd1cd4d16a \
+    --hash=sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5 \
+    --hash=sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f \
+    --hash=sha256:a320721ab5a1aba0a233739394eb907f8c8da5c98c9181d1161e77a0c8e36f2d \
+    --hash=sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1 \
+    --hash=sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287 \
+    --hash=sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6 \
+    --hash=sha256:bc51efed119bc9cfdf792cdeaa4d67e8f6fcccab66ed4bfdd6bde3e59bfcbb2f \
+    --hash=sha256:bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581 \
+    --hash=sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed \
+    --hash=sha256:be8813b57049a7dc738189df53d69395eba14fb99345e0a5994914a3864c8a4b \
+    --hash=sha256:c0c0b3ade1c0b13b936d7970b1d37a57acde9199dc2aecc4c336773e1d86049c \
+    --hash=sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026 \
+    --hash=sha256:c4ffb7ebf07cfe8931028e3e4c85f0357459a3f9f9490886198848f4fa002ec8 \
+    --hash=sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676 \
+    --hash=sha256:d2ee202e79d8ed691ceebae8e0486bd9a2cd4794cec4824e1c99b6f5009502f6 \
+    --hash=sha256:d53197da72cc091b024dd97249dfc7794d6a56530370992a5e1a08983ad9230e \
+    --hash=sha256:d6dd0be5b5b189d31db7cda48b91d7e0a9795f31430b7f271219ab30f1d3ac9d \
+    --hash=sha256:d88b440e37a16e651bda4c7c2b930eb586fd15ca7406cb39e211fcff3bf3017d \
+    --hash=sha256:de8a88e63464af587c950061a5e6a67d3632e36df62b986892331d4620a35c01 \
+    --hash=sha256:df2449253ef108a379b8b5d6b43f4b1a8e81a061d6537becd5582fba5f9196d7 \
+    --hash=sha256:e1c1493fb6e50ab01d20a22826e57520f1284df32f2d8601fdd90b6304601419 \
+    --hash=sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795 \
+    --hash=sha256:e2103a929dfa2fcaf9bb4e7c091983a49c9ac3b19c9061b6d5427dd7d14d81a1 \
+    --hash=sha256:e56b7d45a839a697b5eb268c82a71bd8c7f6c94d6fd50c3d577fa39a9f1409f5 \
+    --hash=sha256:e8afc3f2ccfa24215f8cb28dcf43f0113ac3c37c2f0f0806d8c70e4228c5cf4d \
+    --hash=sha256:e8fc20152abba6b83724d7ff268c249fa196d8259ff481f3b1476383f8f24e42 \
+    --hash=sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe \
+    --hash=sha256:ec15a59cf5af7be74194f7ab02d0f59a62bdcf1a537677ce67a2537c9b87fcda \
+    --hash=sha256:f190daf01f13c72eac4efd5c430a8de82489d9cff23c364c3ea822545032993e \
+    --hash=sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737 \
+    --hash=sha256:f3e98bb3798ead92273dc0e5fd0f31ade220f59a266ffd8a4f6065e0a3ce0523 \
+    --hash=sha256:f42d0984e947b8adf7dd6dde396e720934d12c506ce84eea8476409563607591 \
+    --hash=sha256:f71a396b3bf33ecaa1626c255855702aca4d3d9fea5e051b41ac59a9c1c41edc \
+    --hash=sha256:f9e130248f4462aaa8e2552d547f36ddadbeaa573879158d721bbd33dfe4743a \
+    --hash=sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50
+    # via mako
+pcpp==1.30 \
+    --hash=sha256:05fe08292b6da57f385001c891a87f40d6aa7f46787b03e8ba326d20a3297c6e \
+    --hash=sha256:5af9fbce55f136d7931ae915fae03c34030a3b36c496e72d9636cedc8e2543a1
+    # via -r requirements.in
+pyparsing==3.3.2 \
+    --hash=sha256:850ba148bd908d7e2411587e247a1e4f0327839c40e2e5e6d05a007ecc69911d \
+    --hash=sha256:c777f4d763f140633dcb6d8a3eda953bf7a214dc4eff598413c070bcdc117cbc
+    # via -r requirements.in

cspell.config.yaml

@@ -93,6 +93,7 @@ words:
   - daria
   - dcmake
   - dearmor
+  - dedented
   - deleteme
   - demultiplexer
   - deserializaton
@@ -199,11 +200,13 @@ words:
   - nonxrp
   - noreplace
   - noripple
+  - nostdinc
   - notifempty
   - nudb
   - nullptr
   - nunl
   - Nyffenegger
+  - onlatest
   - ostr
   - pargs
   - partitioner
@@ -254,6 +257,7 @@ words:
   - sfields
   - shamap
   - shamapitem
+  - shfmt
   - shlibs
   - sidechain
   - SIGGOOD
@@ -298,6 +302,7 @@ words:
   - unauthorizing
   - unergonomic
   - unfetched
+  - unfindable
   - unflatten
   - unfund
   - unimpair

docker/check-sanitizers.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Sanity-check that the sanitizer runtimes shipped with g++/clang++ work
+# end-to-end against the system loader: compile each example with both
+# compilers, run it, and confirm the expected diagnostic is emitted.
+
+set -eo pipefail
+
+cpp_files_dir="${1:?usage: $0 <cpp_files_dir>}"
+
+case "$(uname -m)" in
+    x86_64) loader=/lib64/ld-linux-x86-64.so.2 ;;
+    aarch64) loader=/lib/ld-linux-aarch64.so.1 ;;
+    *)
+        echo "Unsupported arch: $(uname -m)" >&2
+        exit 1
+        ;;
+esac
+
+declare -A sanitize=(
+    [asan]="-fsanitize=address"
+    [tsan]="-fsanitize=thread"
+    [ubsan]="-fsanitize=undefined"
+)
+declare -A expect=(
+    [asan]="heap-use-after-free"
+    [tsan]="data race"
+    [ubsan]="signed integer overflow"
+)
+
+for compiler in g++ clang++; do
+    for name in asan tsan ubsan; do
+        bin="/tmp/${name}-${compiler}"
+        echo "=== Build ${name} with ${compiler} ==="
+        "$compiler" -std=c++20 -O1 -g ${sanitize[$name]} \
+            -Wl,--dynamic-linker=$loader \
+            "${cpp_files_dir}/${name}.cpp" -o "$bin"
+        echo "=== Run ${name}-${compiler} ==="
+        output=$("$bin" 2>&1) || true
+        echo "$output"
+        echo "$output" | grep -q "${expect[$name]}" ||
+            {
+                echo "expected '${expect[$name]}' from $bin"
+                exit 1
+            }
+        rm -f "$bin"
+    done
+done

docker/cpp_files/asan.cpp

@@ -0,0 +1,28 @@
+#include <atomic>
+#include <cstddef>
+#include <iostream>
+
+#if defined(__clang__) || defined(__GNUC__)
+__attribute__((noinline))
+#elif defined(_MSC_VER)
+__declspec(noinline)
+#endif
+int
+read_after_free(volatile int* array, std::size_t index)
+{
+    std::atomic_signal_fence(std::memory_order_seq_cst);
+    int value = array[index];
+    std::atomic_signal_fence(std::memory_order_seq_cst);
+    return value;
+}
+
+int
+main()
+{
+    int* array = new int[5]{10, 20, 30, 40, 50};
+    delete[] array;
+
+    std::cout << "Value at index 2: " << read_after_free(array, 2) << std::endl;
+
+    return 0;
+}

docker/cpp_files/tsan.cpp

@@ -0,0 +1,26 @@
+#include <iostream>
+#include <thread>
+
+static int kCounter = 0;
+
+void
+increment()
+{
+    for (int i = 0; i < 100'000; ++i)
+    {
+        ++kCounter;
+    }
+}
+
+int
+main()
+{
+    std::thread t1(increment);
+    std::thread t2(increment);
+
+    t1.join();
+    t2.join();
+
+    std::cout << "Final counter value: " << kCounter << std::endl;
+    return 0;
+}

docker/cpp_files/ubsan.cpp

@@ -0,0 +1,13 @@
+#include <iostream>
+#include <limits>
+
+int
+main()
+{
+    int maxInt = std::numeric_limits<int>::max();
+    int volatile one = 1;
+    std::cout << "Current max: " << maxInt << std::endl;
+    int overflowed = maxInt + one;
+    std::cout << "Overflowed result: " << overflowed << std::endl;
+    return 0;
+}

docker/nix.Dockerfile

@@ -45,8 +45,30 @@ COPY --from=builder /tmp/build/result /nix/ci-env
 
 ENV PATH="/nix/ci-env/bin:$PATH"
 
+# Externally-built dynamically-linked ELF binaries hard-code the loader path
+# (e.g. /lib64/ld-linux-x86-64.so.2) in their PT_INTERP header. Copy the
+# loader from the Nix store to that path when the base image doesn't already
+# provide one (i.e. on nixos/nix).
+RUN <<EOF
+case "$(uname -m)" in
+    x86_64)  target=/lib64/ld-linux-x86-64.so.2 ;;
+    aarch64) target=/lib/ld-linux-aarch64.so.1 ;;
+    *) echo "Unsupported arch: $(uname -m)" >&2; exit 1 ;;
+esac
+if [ ! -e "$target" ]; then
+    # Use the loader from the same glibc that gcc links libc against, so
+    # ld-linux and libc/libpthread share GLIBC_PRIVATE symbols at runtime.
+    src="$(dirname "$(gcc -print-file-name=libc.so.6)")/$(basename "$target")"
+    [ -e "$src" ] || { echo "ld-linux not found at $src" >&2; exit 1; }
+    mkdir -p "$(dirname "$target")"
+    cp "$src" "$target"
+fi
+EOF
+
 RUN <<EOF
 ccache --version
+clang --version
+clang++ --version
 clang-format --version
 cmake --version
 conan --version
@@ -64,3 +86,10 @@ python3 --version
 run-clang-tidy --help
 vim --version
 EOF
+
+# Sanity-check that the sanitizer runtimes shipped with g++/clang++ work
+# end-to-end against the system loader.
+COPY docker/cpp_files/ /tmp/cpp_files/
+COPY docker/check-sanitizers.sh /tmp/check-sanitizers.sh
+
+RUN grep -qi ubuntu /etc/os-release 2>/dev/null && /tmp/check-sanitizers.sh /tmp/cpp_files || true

flake.lock

@@ -15,7 +15,7 @@
         "type": "indirect"
       }
     },
-    "nixpkgs-glibc231": {
+    "nixpkgs-custom-glibc": {
       "flake": false,
       "locked": {
         "lastModified": 1593520194,
@@ -35,7 +35,7 @@
     "root": {
       "inputs": {
         "nixpkgs": "nixpkgs",
-        "nixpkgs-glibc231": "nixpkgs-glibc231"
+        "nixpkgs-custom-glibc": "nixpkgs-custom-glibc"
       }
     }
   },

flake.nix

@@ -6,16 +6,16 @@
     # version — matches the system libc on Ubuntu 20.04 LTS. Imported
     # manually (flake = false) because this revision predates nixpkgs'
     # own flake.nix.
-    nixpkgs-glibc231 = {
+    nixpkgs-custom-glibc = {
       url = "github:NixOS/nixpkgs/9cd98386a38891d1074fc18036b842dc4416f562";
       flake = false;
     };
   };
 
   outputs =
-    { nixpkgs, nixpkgs-glibc231, ... }:
+    { nixpkgs, nixpkgs-custom-glibc, ... }:
     let
-      forEachSystem = import ./nix/utils.nix { inherit nixpkgs nixpkgs-glibc231; };
+      forEachSystem = import ./nix/utils.nix { inherit nixpkgs nixpkgs-custom-glibc; };
     in
     {
       devShells = forEachSystem (import ./nix/devshell.nix);

include/xrpl/basics/Number.h

@@ -7,7 +7,9 @@
 #include <limits>
 #include <optional>
 #include <ostream>
+#include <set>
 #include <string>
+#include <unordered_map>
 
 namespace xrpl {
 
@@ -44,11 +46,11 @@ isPowerOfTen(T value)
  * * min is a power of 10, and
  * * max = min * 10 - 1.
  *
- * The mantissa_scale enum indicates whether the range is "small" or "large".
- * This intentionally restricts the number of MantissaRanges that can be
- * instantiated to two: one for each scale.
+ * The MantissaScale enum indicates properties of the range: size, and some behavioral
+ * options. This intentionally restricts the number of unique MantissaRanges that can
+ * be instantiated: one for each scale.
  *
- * The "small" scale is based on the behavior of STAmount for IOUs. It has a min
+ * The "Small" scale is based on the behavior of STAmount for IOUs. It has a min
  * value of 10^15, and a max value of 10^16-1. This was sufficient for
  * uses before Lending Protocol was implemented, mostly related to AMM.
  *
@@ -59,29 +61,54 @@ isPowerOfTen(T value)
  * STNumber field type, and for internal calculations. That necessitated the
  * "large" scale.
  *
- * The "large" scale is intended to represent all values that can be represented
+ * The "Large" scales are intended to represent all values that can be represented
  * by an STAmount - IOUs, XRP, and MPTs. It has a min value of 10^18, and a max
- * value of 10^19-1.
+ * value of 10^19-1. "LargeLegacy" is like "Large", but preserves
+ * a rounding error when a computation results in a mantissa of
+ * Number::kMaxRep that needs to be rounded up, but rounds down
+ * instead. It will maintain consistent behavior until the fixCleanup3_2_0
+ * amendment is enabled.
  *
  * Note that if the mentioned amendments are eventually retired, this class
- * should be left in place, but the "small" scale option should be removed. This
+ * should be left in place, but the "Small" scale option should be removed. This
  * will allow for future expansion beyond 64-bits if it is ever needed.
  */
-struct MantissaRange
+struct MantissaRange final
 {
     using rep = std::uint64_t;
-    enum class MantissaScale { Small, Large };
+    enum class MantissaScale {
+        Small,
+        // LargeLegacy can be removed when fixCleanup3_2_0 is retired
+        LargeLegacy,
+        Large,
+    };
+
+    // This entire enum can be removed when fixCleanup3_2_0 is retired
+    enum class CuspRoundingFix : bool {
+        Disabled = false,
+        Enabled = true,
+    };
 
     explicit constexpr MantissaRange(MantissaScale scale)
-        : min(getMin(scale)), log(logTen(min).value_or(-1)), scale(scale)
+        : min(getMin(scale))
+        , cuspRoundingFixEnabled(isCuspFixEnabled(scale))
+        , log(logTen(min).value_or(-1))
+        , scale(scale)
     {
     }
 
     rep min;
     rep max{(min * 10) - 1};
+    CuspRoundingFix cuspRoundingFixEnabled;
     int log;
     MantissaScale scale;
 
+    static MantissaRange const&
+    getMantissaRange(MantissaScale scale);
+
+    static std::set<MantissaScale> const&
+    getAllScales();
+
 private:
     static constexpr rep
     getMin(MantissaScale scale)
@@ -90,15 +117,35 @@ private:
         {
             case MantissaScale::Small:
                 return 1'000'000'000'000'000ULL;
+            case MantissaScale::LargeLegacy:
             case MantissaScale::Large:
                 return 1'000'000'000'000'000'000ULL;
             default:
-                // Since this can never be called outside a non-constexpr
-                // context, this throw assures that the build fails if an
+                // If called in a constexpr context, this throw assures that the build fails if an
                 // invalid scale is used.
-                throw std::runtime_error("Unknown mantissa scale");
+                throw std::runtime_error("Unknown mantissa scale");  // LCOV_EXCL_LINE
         }
     }
+
+    static constexpr CuspRoundingFix
+    isCuspFixEnabled(MantissaScale scale)
+    {
+        switch (scale)
+        {
+            case MantissaScale::Small:
+            case MantissaScale::LargeLegacy:
+                return CuspRoundingFix::Disabled;
+            case MantissaScale::Large:
+                return CuspRoundingFix::Enabled;
+            default:
+                // If called in a constexpr context, this throw assures that the build fails if an
+                // invalid scale is used.
+                throw std::runtime_error("Unknown mantissa scale");  // LCOV_EXCL_LINE
+        }
+    }
+
+    static std::unordered_map<MantissaScale, MantissaRange> const&
+    getRanges();
 };
 
 // Like std::integral, but only 64-bit integral types.
@@ -203,7 +250,7 @@ concept Integral64 = std::is_same_v<T, std::int64_t> || std::is_same_v<T, std::u
  * amendments are enabled to determine which result to expect.
  *
  */
-class Number
+class Number final
 {
     using rep = std::int64_t;
     using internalrep = MantissaRange::rep;
@@ -424,49 +471,29 @@ public:
         return kRange.get().log;
     }
 
-    /// oneSmall is needed because the ranges are private
-    static constexpr Number
-    oneSmall();
-    /// oneLarge is needed because the ranges are private
-    static constexpr Number
-    oneLarge();
-
-    // And one is needed because it needs to choose between oneSmall and
-    // oneLarge based on the current range
     static Number
     one();
 
-    template <Integral64 T>
+    template <
+        auto MinMantissa,
+        auto MaxMantissa,
+        Integral64 T = std::decay_t<decltype(MinMantissa)>,
+        Integral64 TMax = std::decay_t<decltype(MaxMantissa)>>
     [[nodiscard]]
     std::pair<T, int>
-    normalizeToRange(T minMantissa, T maxMantissa) const;
+    normalizeToRange() const;
 
 private:
     static thread_local RoundingMode mode;
     // The available ranges for mantissa
 
-    static constexpr MantissaRange kSmallRange{MantissaRange::MantissaScale::Small};
-    static_assert(isPowerOfTen(kSmallRange.min));
-    static_assert(kSmallRange.min == 1'000'000'000'000'000LL);
-    static_assert(kSmallRange.max == 9'999'999'999'999'999LL);
-    static_assert(kSmallRange.log == 15);
-    static_assert(kSmallRange.min < kMaxRep);
-    static_assert(kSmallRange.max < kMaxRep);
-    static constexpr MantissaRange kLargeRange{MantissaRange::MantissaScale::Large};
-    static_assert(isPowerOfTen(kLargeRange.min));
-    static_assert(kLargeRange.min == 1'000'000'000'000'000'000ULL);
-    static_assert(kLargeRange.max == internalrep(9'999'999'999'999'999'999ULL));
-    static_assert(kLargeRange.log == 18);
-    static_assert(kLargeRange.min < kMaxRep);
-    static_assert(kLargeRange.max > kMaxRep);
-
     // The range for the mantissa when normalized.
     // Use reference_wrapper to avoid making copies, and prevent accidentally
     // changing the values inside the range.
     static thread_local std::reference_wrapper<MantissaRange const> kRange;
 
     void
-    normalize();
+    normalize(MantissaRange const& range);
 
     /** Normalize Number components to an arbitrary range.
      *
@@ -481,7 +508,8 @@ private:
         T& mantissa,
         int& exponent,
         internalrep const& minMantissa,
-        internalrep const& maxMantissa);
+        internalrep const& maxMantissa,
+        MantissaRange::CuspRoundingFix cuspRoundingFixEnabled);
 
     template <class T>
     friend void
@@ -490,7 +518,8 @@ private:
         T& mantissa,
         int& exponent,
         MantissaRange::rep const& minMantissa,
-        MantissaRange::rep const& maxMantissa);
+        MantissaRange::rep const& maxMantissa,
+        MantissaRange::CuspRoundingFix cuspRoundingFixEnabled);
 
     [[nodiscard]] bool
     isnormal() const noexcept;
@@ -526,7 +555,7 @@ static constexpr Number kNumZero{};
 inline Number::Number(bool negative, internalrep mantissa, int exponent, Normalized)
     : Number(negative, mantissa, exponent, Unchecked{})
 {
-    normalize();
+    normalize(kRange);
 }
 
 inline Number::Number(internalrep mantissa, int exponent, Normalized)
@@ -696,10 +725,19 @@ Number::isnormal() const noexcept
          kMinExponent <= exponent_ && exponent_ <= kMaxExponent);
 }
 
-template <Integral64 T>
+template <auto MinMantissa, auto MaxMantissa, Integral64 T, Integral64 TMax>
 std::pair<T, int>
-Number::normalizeToRange(T minMantissa, T maxMantissa) const
+Number::normalizeToRange() const
 {
+    static_assert(std::is_same_v<T, std::uint64_t> || std::is_same_v<T, std::int64_t>);
+    static_assert(std::is_same_v<T, TMax>);
+    auto constexpr kMIN = static_cast<T>(MinMantissa);
+    auto constexpr kMAX = static_cast<T>(MaxMantissa);
+    static_assert(kMIN > 0);
+    static_assert(kMIN % 10 == 0);
+    static_assert(kMAX % 10 == 9);
+    static_assert((kMAX + 1) / 10 == kMIN);
+
     bool negative = negative_;
     internalrep mantissa = mantissa_;
     int exponent = exponent_;
@@ -711,7 +749,10 @@ Number::normalizeToRange(T minMantissa, T maxMantissa) const
             "xrpl::Number::normalizeToRange",
             "Number is non-negative for unsigned range.");
     }
-    Number::normalize(negative, mantissa, exponent, minMantissa, maxMantissa);
+    // Don't need to worry about the cuspRounding fix because rounding up will never take the
+    // mantissa over maxMantissa with a ones digit value other than 0. 0 can safely be truncated.
+    Number::normalize(
+        negative, mantissa, exponent, kMIN, kMAX, MantissaRange::CuspRoundingFix::Disabled);
 
     auto const sign = negative ? -1 : 1;
     return std::make_pair(static_cast<T>(sign * mantissa), exponent);
@@ -763,6 +804,8 @@ to_string(MantissaRange::MantissaScale const& scale)
     {
         case MantissaRange::MantissaScale::Small:
             return "small";
+        case MantissaRange::MantissaScale::LargeLegacy:
+            return "largeLegacy";
         case MantissaRange::MantissaScale::Large:
             return "large";
         default:

include/xrpl/ledger/DeferredRebuild.h

@@ -0,0 +1,229 @@
+#pragma once
+
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/hardened_hash.h>
+
+#include <array>
+#include <cstdint>
+#include <functional>
+#include <unordered_map>
+#include <vector>
+
+namespace xrpl {
+
+/** An inner-node position in a SHAMap that needs hash recomputation.
+
+    Plan 7's deferred-rebuild algorithm walks bottom-up, recomputing
+    each affected inner node's hash from its children. `AffectedNode`
+    identifies one such node by:
+      * depth:  0 = root, 1..63 = inner nodes, 64 = leaf (not included
+                in the plan output — only inner nodes are rebuilt)
+      * prefix: the leaf-key's first `depth*4` bits, with the remainder
+                zeroed. Two nodes at the same depth with the same
+                prefix are the same node.
+*/
+struct AffectedNode
+{
+    int depth;
+    uint256 prefix;
+
+    [[nodiscard]] bool
+    operator==(AffectedNode const& other) const noexcept
+    {
+        return depth == other.depth && prefix == other.prefix;
+    }
+};
+
+/** Plan which inner nodes need rebuild for a given set of leaf changes.
+
+    Returns the union of ancestor paths of all `modifiedKeys`, sorted
+    by depth descending so a bottom-up rebuild can iterate the result
+    and find each level's nodes before the level above.
+
+    The returned plan contains only INNER nodes (depths 0..63). The
+    leaves themselves are at depth 64 and are not in the plan — they
+    are the modifications, not nodes to be rebuilt.
+
+    Complexity: O(K * 64) where K is `modifiedKeys.size()`. For real
+    workloads (~thousands of modifications), this is microseconds.
+*/
+[[nodiscard]] std::vector<AffectedNode>
+planDeferredRebuild(std::vector<uint256> const& modifiedKeys);
+
+/** Compute the hash of a SHAMap inner node from its 16 children.
+
+    Byte-identical to `SHAMapInnerNode::updateHash()`:
+
+        sha512_half(
+            HashPrefix::InnerNode (4 bytes, big-endian) ||
+            child[0]  (32 bytes) ||
+            child[1]  (32 bytes) ||
+            ...
+            child[15] (32 bytes))
+
+    This is the elementary operation of plan-7's bottom-up rebuild:
+    given the (already-computed) 16 child hashes of an inner node,
+    produce that node's hash. Empty branches are passed as zero
+    uint256 — the same convention SHAMap uses.
+
+    Pure function; no SHAMap state, no allocation beyond a stack buffer.
+*/
+[[nodiscard]] uint256
+computeInnerNodeHash(std::array<uint256, 16> const& childHashes);
+
+/** Hash combiner for AffectedNode keys in unordered_map. */
+struct AffectedNodeHash
+{
+    [[nodiscard]] std::size_t
+    operator()(AffectedNode const& n) const noexcept
+    {
+        // Mix depth into the high bits of a hash of prefix.
+        std::size_t h = 0;
+        for (auto b : n.prefix)
+            h = h * 31 + b;
+        return h ^ (static_cast<std::size_t>(n.depth) << 56);
+    }
+};
+
+/** Map of recomputed inner-node hashes keyed by (depth, prefix). */
+using RebuildResult =
+    std::unordered_map<AffectedNode, uint256, AffectedNodeHash>;
+
+/** Walk a depth-descending plan and compute each affected node's new hash.
+
+    For each AffectedNode in the plan (deepest first), collect its 16
+    child hashes:
+      * If a child position is itself in the plan (and already
+        computed, since we walk deepest-first), use the computed hash.
+      * Otherwise, fall back to `getOriginalChildHash` — the callback
+        is expected to walk the parent SHAMap to find the hash at that
+        position.
+
+    Then `computeInnerNodeHash` over the 16 children yields the
+    affected node's new hash. The result map contains every entry in
+    the plan keyed by its (depth, prefix).
+
+    @param plan
+        Depth-descending plan from `planDeferredRebuild`.
+    @param getOriginalChildHash
+        Callable `uint256(int depth, uint256 const& prefix)` returning
+        the hash at the given position in the parent SHAMap. May
+        return uint256{} for absent positions.
+
+    @note Pure function; safe to call concurrently with disjoint plans.
+*/
+template <typename GetChildHashFn>
+[[nodiscard]] RebuildResult
+executeRebuildPlan(
+    std::vector<AffectedNode> const& plan,
+    GetChildHashFn getOriginalChildHash);
+
+namespace detail {
+
+// Forwarder for template instantiation; declared here, defined in .cpp.
+[[nodiscard]] RebuildResult
+executeRebuildPlanImpl(
+    std::vector<AffectedNode> const& plan,
+    std::function<uint256(int, uint256 const&)> getOriginalChildHash);
+
+}  // namespace detail
+
+template <typename GetChildHashFn>
+[[nodiscard]] RebuildResult
+executeRebuildPlan(
+    std::vector<AffectedNode> const& plan,
+    GetChildHashFn getOriginalChildHash)
+{
+    return detail::executeRebuildPlanImpl(
+        plan,
+        std::function<uint256(int, uint256 const&)>(
+            std::move(getOriginalChildHash)));
+}
+
+/** End-to-end deferred rebuild: produce the new SHAMap root hash.
+
+    Combines `planDeferredRebuild` + `executeRebuildPlan` into one call.
+    This is the consumer-facing API — the integration site only needs
+    to supply the set of modified keys and a callback that reads the
+    parent SHAMap. No AffectedNode plumbing is exposed.
+
+    @param modifiedKeys
+        Keys whose leaves have been added/replaced/deleted in this
+        ledger close. Empty → no rebuild; returns the existing root
+        via the callback at (depth=0, prefix=zero).
+    @param getOriginalChildHash
+        Callable `uint256(int depth, uint256 const& prefix)` returning
+        the hash at the given position in the parent SHAMap. May return
+        uint256{} for absent positions.
+    @return The new SHAMap root hash.
+*/
+template <typename GetChildHashFn>
+[[nodiscard]] uint256
+deferredRebuildRoot(
+    std::vector<uint256> const& modifiedKeys,
+    GetChildHashFn getOriginalChildHash)
+{
+    if (modifiedKeys.empty())
+        return getOriginalChildHash(0, uint256{});
+
+    auto const plan = planDeferredRebuild(modifiedKeys);
+    auto const result = executeRebuildPlan(plan, std::move(getOriginalChildHash));
+    AffectedNode const rootKey{0, uint256{}};
+    auto const it = result.find(rootKey);
+    if (it == result.end())
+        return uint256{};
+    return it->second;
+}
+
+/** Partition modified keys by their first nibble (0..15).
+
+    At depth 1 the root has 16 child subtrees, one per first-nibble
+    value. Keys in different subtrees rebuild independently, so this
+    partition is the basis for plan-7 P7.3's parallel-by-subtree
+    rebuild.
+
+    Returns 16 buckets, one per first-nibble value, each containing
+    only the keys whose first nibble matches the bucket index.
+*/
+[[nodiscard]] std::array<std::vector<uint256>, 16>
+partitionByFirstNibble(std::vector<uint256> const& modifiedKeys);
+
+namespace detail {
+
+[[nodiscard]] uint256
+deferredRebuildRootParallelImpl(
+    std::vector<uint256> const& modifiedKeys,
+    std::function<uint256(int, uint256 const&)> getOriginalChildHash);
+
+}  // namespace detail
+
+/** Parallel deferred rebuild: partition by first nibble, rebuild each
+    of the 16 subtrees in parallel, combine into the root.
+
+    Equivalent to `deferredRebuildRoot` in output; differs only in
+    execution strategy. Useful when the parent SHAMap is large enough
+    that the rebuild cost matters per-close. For small workloads
+    (handful of modifications), the serial path is faster — threading
+    overhead exceeds the work saved.
+
+    @param modifiedKeys
+        Keys whose leaves have been added/replaced/deleted.
+    @param getOriginalChildHash
+        Thread-safe callable; will be invoked concurrently from
+        multiple subtree workers.
+    @return The new SHAMap root hash, byte-identical to
+            `deferredRebuildRoot` over the same inputs.
+*/
+template <typename GetChildHashFn>
+[[nodiscard]] uint256
+deferredRebuildRootParallel(
+    std::vector<uint256> const& modifiedKeys,
+    GetChildHashFn getOriginalChildHash)
+{
+    return detail::deferredRebuildRootParallelImpl(
+        modifiedKeys,
+        std::function<uint256(int, uint256 const&)>(
+            std::move(getOriginalChildHash)));
+}
+
+}  // namespace xrpl

include/xrpl/ledger/FlatStateMap.h

@@ -0,0 +1,347 @@
+#pragma once
+
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/hardened_hash.h>
+#include <xrpl/protocol/Keylet.h>
+#include <xrpl/protocol/STLedgerEntry.h>
+
+#include <cstddef>
+#include <iterator>
+#include <memory>
+#include <shared_mutex>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+namespace xrpl {
+
+/** Flat keylet-indexed materialization of XRPL state.
+
+    The SHAMap is XRPL's authoritative state structure — it produces
+    the state root that consensus agrees on. But on its own, it forces
+    every state read to walk the trie: ~6–10 spinlocked inner-node
+    fetches per `read(Keylet)`.
+
+    `FlatStateMap` materializes the same keylet → SLE mapping into a
+    flat hash table. Once populated, lookups are a single
+    `unordered_map::find()` — nanoseconds, not microseconds.
+
+    This is the 2-writes-for-1-read pattern (Plan 6):
+      * On apply, the apply path dual-writes to SHAMap and FlatStateMap.
+      * On read, only FlatStateMap is consulted.
+
+    The flat map is purely auxiliary. The SHAMap remains authoritative,
+    can always be rebuilt from the underlying NodeStore, and is what the
+    network's state-root commitment is computed from. If FlatStateMap is
+    wrong, the differential invariant check at ledger close (Plan 6 P6.5)
+    catches it; there is **no runtime fallback to SHAMap descent on
+    miss** — a miss is a bug.
+
+    Thread-safe via a shared_mutex. Concurrent reads do not block each
+    other; writes are exclusive. Future phases may replace this with
+    a lock-free atomic-pointer-swap design.
+*/
+class FlatStateMap
+{
+public:
+    using key_type = uint256;
+    using value_type = std::shared_ptr<STLedgerEntry const>;
+
+    FlatStateMap() = default;
+    ~FlatStateMap() = default;
+
+    // Non-copyable, non-movable. The map owns a shared_mutex (not movable)
+    // and a potentially large hash table; callers that need ownership
+    // transfer should wrap in std::unique_ptr<FlatStateMap>.
+    FlatStateMap(FlatStateMap const&) = delete;
+    FlatStateMap&
+    operator=(FlatStateMap const&) = delete;
+    FlatStateMap(FlatStateMap&&) = delete;
+    FlatStateMap&
+    operator=(FlatStateMap&&) = delete;
+
+    /** Look up an SLE by its SHAMap key.
+
+        Returns nullptr if the key is not in the map. In Plan 6's pure
+        2w/1r model, callers reading state that *should* exist treat
+        nullptr as a precondition violation — there is no fallback path
+        that would recover from a missed entry.
+    */
+    [[nodiscard]] value_type
+    read(key_type const& key) const;
+
+    /** Test whether an SLE is present. O(1). */
+    [[nodiscard]] bool
+    exists(key_type const& key) const;
+
+    /** Insert a new SLE. Replaces any prior entry under the same key.
+
+        Used by both:
+          * the apply path's `view.insert()` (new ledger object), and
+          * the apply path's `view.update()` (mutating an existing SLE
+            produces a new shared_ptr value).
+    */
+    void
+    insert(key_type const& key, value_type sle);
+
+    /** Remove an SLE. No-op if the key is absent. */
+    void
+    erase(key_type const& key);
+
+    /** Number of SLEs currently materialized. */
+    [[nodiscard]] std::size_t
+    size() const;
+
+    /** Test whether the map is empty. O(1). */
+    [[nodiscard]] bool
+    empty() const;
+
+    /** Remove every entry. Used by tests and by snapshot reset. */
+    void
+    clear();
+
+    /** Deep-copy snapshot of the current state.
+
+        The snapshot is a frozen FlatStateMap (returned by value-like
+        unique_ptr) that shares the underlying SLE objects via
+        shared_ptr but has its own hash table. Subsequent writes to the
+        source FlatStateMap do not affect the snapshot.
+
+        Snapshot cost is O(N) in entry count — ~one pointer copy per
+        entry plus bucket allocation. For current mainnet (~10M SLEs)
+        this is ~100–200 ms; expensive enough that snapshots should be
+        per-ledger-close, not per-transaction.
+
+        A future phase will replace this with a persistent / HAMT
+        structure that gives O(log N) snapshot and structural sharing
+        across versions.
+    */
+    [[nodiscard]] std::unique_ptr<FlatStateMap>
+    snapshot() const;
+
+    /** Visit every (key, SLE) pair under a single shared lock.
+
+        @param visitor  Called as `void(key_type const&, value_type const&)`.
+
+        The lock is held for the duration of the iteration; visitors
+        must not call back into the same FlatStateMap (deadlock /
+        recursive shared_lock UB). Visitors that want to mutate state
+        should collect keys first and apply mutations after iteration
+        returns.
+    */
+    template <typename F>
+    void
+    forEach(F&& visitor) const
+    {
+        std::shared_lock<std::shared_mutex> lock(mutex_);
+        for (auto const& [key, sle] : map_)
+            visitor(key, sle);
+    }
+
+private:
+    using HashFn = HardenedHash<>;
+    using MapType = std::unordered_map<key_type, value_type, HashFn>;
+
+    mutable std::shared_mutex mutex_;
+    MapType map_;
+};
+
+// Forward declarations to avoid pulling heavy headers into this file.
+class ReadView;
+class Ledger;
+
+/** Populate a FlatStateMap from every SLE in a ReadView.
+
+    Used at node startup to build the flat materialization from a
+    SHAMap-backed authoritative ledger. Cost is O(N) iterations of
+    `view.sles`, each of which descends the SHAMap, so this is
+    expected to take seconds-to-minutes for a current mainnet-sized
+    ledger (~10M SLEs). Run once on startup; subsequent ledgers are
+    maintained incrementally via dual-write at apply time (P6.3).
+
+    @pre `target` is empty. (Not enforced — replacing existing entries
+         is well-defined, but mixing populated state with an externally-
+         provided ReadView is a bug-shaped pattern; assert in DEBUG.)
+*/
+void
+populateFromReadView(FlatStateMap& target, ReadView const& source);
+
+/** Populate a FlatStateMap from any forward range of `shared_ptr<SLE const>`.
+
+    Lower-level building block underlying `populateFromReadView`. Useful
+    in tests (the range can be a `std::vector<shared_ptr<SLE const>>`)
+    and in non-ReadView contexts (e.g., reloading a persisted flat-map
+    sidecar at startup).
+
+    The range element type must be `shared_ptr<SLE const>` (or
+    implicitly convertible). Each element's `.key()` becomes the
+    FlatStateMap key.
+*/
+template <typename Range>
+void
+populateFromRange(FlatStateMap& target, Range const& sles)
+{
+    for (auto const& sle : sles)
+        target.insert(sle->key(), sle);
+}
+
+// ---------------------------------------------------------------------------
+// Mirror helpers (P6.3).
+//
+// The xrpld `RawView` interface defines three pure-virtual methods that
+// every state mutation flows through: `rawInsert`, `rawReplace`, and
+// `rawErase`. In plan-6's 2-writes-for-1-read pattern, every such call
+// must also update the flat map. These helpers perform the flat-map side
+// of that dual-write — they exist as standalone functions (rather than
+// methods on FlatStateMap) so the Ledger integration is a one-line
+// addition at each `raw*` override site, with no FlatStateMap class
+// surface added for purely Ledger-specific semantics.
+//
+// Permissive semantics: `mirrorRawReplace` on an absent key inserts;
+// `mirrorRawErase` on an absent key is a no-op. The SHAMap side enforces
+// the precondition (replace requires existence); the flat mirror ensures
+// the post-state matches whatever the SHAMap committed. If the caller
+// gets it wrong, the differential invariant check at close (P6.5) is the
+// stop-the-line gate.
+// ---------------------------------------------------------------------------
+
+void
+mirrorRawInsert(FlatStateMap& map, std::shared_ptr<STLedgerEntry const> sle);
+
+void
+mirrorRawReplace(FlatStateMap& map, std::shared_ptr<STLedgerEntry const> sle);
+
+void
+mirrorRawErase(FlatStateMap& map, std::shared_ptr<STLedgerEntry const> const& sle);
+
+void
+mirrorRawErase(FlatStateMap& map, uint256 const& key);
+
+// ---------------------------------------------------------------------------
+// Keylet-aware read (P6.4).
+//
+// This is the read-side counterpart to `mirrorRaw*` — the testable unit
+// underlying `Ledger::read(Keylet)`'s flat-map path. It looks up the
+// SLE by `k.key` and verifies the SLE matches the keylet's expected
+// type via `Keylet::check`. On either a miss or a type mismatch, it
+// returns nullptr — matching the contract of `Ledger::read`.
+//
+// Plan 6 v2 semantics: this function does not consult a SHAMap or any
+// other source on miss. When a FlatStateMap is the read source of
+// truth, a miss IS the answer. The differential invariant check at
+// close (P6.5) is what makes that safe.
+// ---------------------------------------------------------------------------
+
+std::shared_ptr<STLedgerEntry const>
+readFromFlatStateMap(FlatStateMap const& map, Keylet const& k);
+
+// ---------------------------------------------------------------------------
+// Differential invariant (P6.5).
+//
+// At every ledger close, the flat map's key-set must match the
+// SHAMap's key-set. `diffFlatStateKeys` produces both sides of the
+// disagreement; `flatStateMapMatches` is the boolean predicate the
+// hot-path integration calls (and fails the close if it returns false).
+//
+// Content drift (right keys, wrong SLE bodies) is a separate, stronger
+// invariant. It's prevented by construction: the mirror helpers write
+// exactly the SLE the caller passed to raw*. If mirror helpers and
+// wiring are both correct, the membership check above is sufficient.
+// ---------------------------------------------------------------------------
+
+struct FlatStateKeyDiff
+{
+    std::vector<uint256> missingFromFlat;
+    std::vector<uint256> extraInFlat;
+};
+
+template <typename SourceRange>
+[[nodiscard]] FlatStateKeyDiff
+diffFlatStateKeys(FlatStateMap const& flat, SourceRange const& sourceKeys)
+{
+    FlatStateKeyDiff diff;
+
+    // Pass 1: walk source keys; collect any absent from flat. Record
+    // which keys we've seen so pass 2 can spot phantoms.
+    std::unordered_set<uint256, HardenedHash<>> seen;
+    seen.reserve(static_cast<std::size_t>(std::distance(
+        std::begin(sourceKeys), std::end(sourceKeys))));
+
+    for (auto const& key : sourceKeys)
+    {
+        seen.insert(key);
+        if (!flat.exists(key))
+            diff.missingFromFlat.push_back(key);
+    }
+
+    // Pass 2: walk flat; anything not in `seen` is a phantom.
+    flat.forEach(
+        [&seen, &diff](uint256 const& key, auto const& /*sle*/) {
+            if (!seen.contains(key))
+                diff.extraInFlat.push_back(key);
+        });
+
+    return diff;
+}
+
+template <typename SourceRange>
+[[nodiscard]] bool
+flatStateMapMatches(FlatStateMap const& flat, SourceRange const& sourceKeys)
+{
+    auto const diff = diffFlatStateKeys(flat, sourceKeys);
+    return diff.missingFromFlat.empty() && diff.extraInFlat.empty();
+}
+
+/** Compare a FlatStateMap against a SHAMap-like source.
+
+    `ShaMapLike` is any range whose elements expose a `key()` accessor
+    returning a `uint256`. The real `SHAMap` satisfies this contract
+    (its iterators yield `SHAMapItem`s with `.key()`), as does the
+    `MockShaMapItem` used in tests.
+
+    This is the helper the Ledger integration calls to run the P6.5
+    differential invariant. It extracts keys into a transient buffer
+    (O(N) allocation, ~N pointers' worth of memory) and forwards to
+    `flatStateMapMatches`. The transient buffer is acceptable at close
+    cadence; the integration can later optimize by walking the SHAMap
+    in-place once profiling shows the allocation matters.
+*/
+template <typename ShaMapLike>
+[[nodiscard]] bool
+flatStateMapMatchesShaMap(FlatStateMap const& flat, ShaMapLike const& shaMap)
+{
+    std::vector<uint256> keys;
+    for (auto const& item : shaMap)
+        keys.push_back(item.key());
+    return flatStateMapMatches(flat, keys);
+}
+
+// ---------------------------------------------------------------------------
+// A-phase integration: attach a populated FlatStateMap to a Ledger.
+//
+// This is the public entry point a node or test uses to "turn on" the
+// flat-map read path for a Ledger. The function:
+//   1. Allocates a new FlatStateMap.
+//   2. Eagerly populates it by walking every SLE in the Ledger.
+//   3. Attaches it via `Ledger::setFlatStateMap`.
+//
+// After this call:
+//   * `Ledger::flatStateMap()` returns the populated map
+//   * `Ledger::read(keylet)` routes through the flat map (no SHAMap
+//     descent on the hot path; see P6.4 wiring)
+//   * `Ledger::raw{Insert,Replace,Erase}` mirror writes to the flat
+//     map alongside the SHAMap (see P6.3 wiring)
+//   * `Ledger::validateFlatStateMapMatchesShaMap()` returns true
+//
+// Repeat calls discard the prior map and produce a fresh one.
+//
+// Cost: O(N) walk over the Ledger's state SHAMap to populate the flat
+// map. For mainnet-scale state, this is bounded by SHAMap traversal
+// speed — typically minutes once. Run at node startup or whenever a
+// Ledger first becomes "live" (the one apply writes to).
+// ---------------------------------------------------------------------------
+
+void
+attachFlatStateMapTo(Ledger& ledger);
+
+}  // namespace xrpl

include/xrpl/ledger/Ledger.h

@@ -14,6 +14,7 @@
 
 namespace xrpl {
 
+class FlatStateMap;
 class ServiceRegistry;
 class Job;
 class TransactionMaster;
@@ -364,6 +365,38 @@ public:
     std::shared_ptr<SLE>
     peek(Keylet const& k) const;
 
+    //
+    // Flat-state mirror (Plan 6 P6.3).
+    //
+    // When a FlatStateMap is attached, every successful `raw*` call below
+    // mirrors the operation into the map via the matching `mirrorRaw*`
+    // helper. With no map attached (the default), the ledger behaves
+    // exactly as before — no allocation, no mutex, no observable change.
+    // The map's lifetime is managed by the caller (typically the
+    // Application owns the live ledger's map).
+    //
+
+    void
+    setFlatStateMap(std::shared_ptr<FlatStateMap> map);
+
+    [[nodiscard]] std::shared_ptr<FlatStateMap>
+    flatStateMap() const;
+
+    /** Run the Plan 6 P6.5 differential invariant.
+
+        Returns true iff (a) no FlatStateMap is attached (vacuously
+        true — there is no second source of truth to disagree), or
+        (b) the attached FlatStateMap's key-set matches the SHAMap's
+        key-set exactly.
+
+        Intended to be called at ledger close, before the new state
+        root is published. A false return is a stop-the-line bug —
+        the integrator should crash rather than publish a state root
+        that disagrees with the read path.
+    */
+    [[nodiscard]] bool
+    validateFlatStateMapMatchesShaMap() const;
+
 private:
     class SlesIterImpl;
     class TxsIterImpl;
@@ -400,6 +433,11 @@ private:
     // A SHAMap containing the state objects for this ledger.
     SHAMap mutable stateMap_;
 
+    // Optional flat keylet→SLE mirror. When non-null, every successful
+    // raw* state mutation is mirrored into this map. See FlatStateMap.h
+    // and the Plan 6 docs in tasks/.
+    std::shared_ptr<FlatStateMap> mutable flatStateMap_;
+
     // Protects fee variables
     std::mutex mutable mutex_;
 

include/xrpl/ledger/helpers/LendingHelpers.h

@@ -203,6 +203,21 @@ getAssetsTotalScale(SLE::const_ref vaultSle)
     return scale(vaultSle->at(sfAssetsTotal), vaultSle->at(sfAsset));
 }
 
+// Compute the minimum required broker cover, rounded consistently.
+// DebtTotal is a broker-level aggregate maintained at vault scale, so the
+// rounding must also use vault scale — never an individual loan's scale.
+inline Number
+minimumBrokerCover(Number const& debtTotal, TenthBips32 coverRateMinimum, SLE::const_ref vaultSle)
+{
+    XRPL_ASSERT(
+        vaultSle && vaultSle->getType() == ltVAULT, "xrpl::minimumBrokerCover : valid Vault sle");
+    NumberRoundModeGuard const mg(Number::RoundingMode::Upward);
+    return roundToAsset(
+        vaultSle->at(sfAsset),
+        tenthBipsOfValue(debtTotal, coverRateMinimum),
+        getAssetsTotalScale(vaultSle));
+}
+
 TER
 checkLoanGuards(
     Asset const& vaultAsset,

include/xrpl/ledger/helpers/MPTokenHelpers.h

@@ -171,6 +171,15 @@ canTransfer(
 [[nodiscard]] TER
 canTrade(ReadView const& view, Asset const& asset, std::uint8_t depth = 0);
 
+/** Convenience to combine canTrade/Transfer. Returns tesSUCCESS if Asset is Issue.
+ */
+[[nodiscard]] TER
+canMPTTradeAndTransfer(
+    ReadView const& v,
+    Asset const& asset,
+    AccountID const& from,
+    AccountID const& to);
+
 //------------------------------------------------------------------------------
 //
 // Empty holding operations (MPT-specific)
@@ -277,17 +286,4 @@ issuerFundsToSelfIssue(ReadView const& view, MPTIssue const& issue);
 void
 issuerSelfDebitHookMPT(ApplyView& view, MPTIssue const& issue, std::uint64_t amount);
 
-//------------------------------------------------------------------------------
-//
-// MPT DEX
-//
-//------------------------------------------------------------------------------
-
-/* Return true if a transaction is allowed for the specified MPT/account. The
- * function checks MPTokenIssuance and MPToken objects flags to determine if the
- * transaction is allowed.
- */
-TER
-checkMPTTxAllowed(ReadView const& v, TxType tx, Asset const& asset, AccountID const& accountID);
-
 }  // namespace xrpl

include/xrpl/ledger/helpers/TokenHelpers.h

@@ -63,9 +63,15 @@ enum class AuthType { StrongAuth, WeakAuth, Legacy };
 [[nodiscard]] bool
 isGlobalFrozen(ReadView const& view, Asset const& asset);
 
+[[nodiscard]] TER
+checkGlobalFrozen(ReadView const& view, Asset const& asset);
+
 [[nodiscard]] bool
 isIndividualFrozen(ReadView const& view, AccountID const& account, Asset const& asset);
 
+[[nodiscard]] TER
+checkIndividualFrozen(ReadView const& view, AccountID const& account, Asset const& asset);
+
 /**
  *   isFrozen check is recursive for MPT shares in a vault, descending to
  *   assets in the vault, up to maxAssetCheckDepth recursion depth. This is

include/xrpl/ledger/helpers/VaultHelpers.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <xrpl/ledger/ReadView.h>
+#include <xrpl/protocol/AccountID.h>
 #include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
 
@@ -43,6 +45,14 @@ sharesToAssetsDeposit(
 /** Controls whether to truncate shares instead of rounding. */
 enum class TruncateShares : bool { No = false, Yes = true };
 
+/** Controls whether the withdraw conversion helpers
+    (assetsToSharesWithdraw and sharesToAssetsWithdraw) subtract
+    sfLossUnrealized from sfAssetsTotal before computing the exchange rate.
+    The default (No) applies the standard discounted rate; Yes is used when
+    the redeemer is the sole remaining shareholder.
+*/
+enum class WaiveUnrealizedLoss : bool { No = false, Yes = true };
+
 /** From the perspective of a vault, return the number of shares to demand from
     the depositor when they ask to withdraw a fixed amount of assets. Since
     shares are MPT this number is integral, and it will be rounded to nearest
@@ -52,6 +62,8 @@ enum class TruncateShares : bool { No = false, Yes = true };
     @param issuance The MPTokenIssuance SLE for the vault's shares.
     @param assets The amount of assets to convert.
     @param truncate Whether to truncate instead of rounding.
+    @param waive Whether to waive the unrealized-loss discount when computing
+                 the exchange rate.
 
     @return The number of shares, or nullopt on error.
 */
@@ -60,7 +72,8 @@ assetsToSharesWithdraw(
     std::shared_ptr<SLE const> const& vault,
     std::shared_ptr<SLE const> const& issuance,
     STAmount const& assets,
-    TruncateShares truncate = TruncateShares::No);
+    TruncateShares truncate = TruncateShares::No,
+    WaiveUnrealizedLoss waive = WaiveUnrealizedLoss::No);
 
 /** From the perspective of a vault, return the number of assets to give the
     depositor when they redeem a fixed amount of shares. Note, since shares are
@@ -69,6 +82,8 @@ assetsToSharesWithdraw(
     @param vault The vault SLE.
     @param issuance The MPTokenIssuance SLE for the vault's shares.
     @param shares The amount of shares to convert.
+    @param waive Whether to waive (i.e. not subtract) the vault's unrealized
+                 loss when computing the exchange rate.
 
     @return The number of assets, or nullopt on error.
 */
@@ -76,6 +91,22 @@ assetsToSharesWithdraw(
 sharesToAssetsWithdraw(
     std::shared_ptr<SLE const> const& vault,
     std::shared_ptr<SLE const> const& issuance,
-    STAmount const& shares);
+    STAmount const& shares,
+    WaiveUnrealizedLoss waive = WaiveUnrealizedLoss::No);
+
+/** Returns true iff `account` holds all of the vault's outstanding shares —
+    i.e. is the sole remaining shareholder. Returns false if the account
+    holds no shares or fewer than the total outstanding.
+
+    @param view The ledger view.
+    @param account The candidate sole shareholder.
+    @param issuance The MPTokenIssuance SLE for the vault's shares; provides
+                    both the share MPTID and the outstanding-amount total.
+*/
+[[nodiscard]] bool
+isSoleShareholder(
+    ReadView const& view,
+    AccountID const& account,
+    std::shared_ptr<SLE const> const& issuance);
 
 }  // namespace xrpl

include/xrpl/nodestore/Backend.h

@@ -83,10 +83,6 @@ public:
     virtual Status
     fetch(uint256 const& hash, std::shared_ptr<NodeObject>* pObject) = 0;
 
-    /** Fetch a batch synchronously. */
-    virtual std::pair<std::vector<std::shared_ptr<NodeObject>>, Status>
-    fetchBatch(std::vector<uint256> const& hashes) = 0;
-
     /** Store a single object.
         Depending on the implementation this may happen immediately
         or deferred using a scheduled task.

include/xrpl/nodestore/detail/DatabaseNodeImp.h

@@ -67,9 +67,6 @@ public:
         backend_->sync();
     }
 
-    std::vector<std::shared_ptr<NodeObject>>
-    fetchBatch(std::vector<uint256> const& hashes);
-
     void
     asyncFetch(
         uint256 const& hash,

include/xrpl/protocol/Rules.h

@@ -122,4 +122,17 @@ private:
     std::optional<Rules> saved_;
 };
 
+class NumberSO;
+class NumberMantissaScaleGuard;
+
+bool
+useRulesGuards(Rules const& rules);
+
+void
+createGuards(
+    Rules const& rules,
+    std::optional<NumberSO>& stNumberSO,
+    std::optional<CurrentTransactionRulesGuard>& rulesGuard,
+    std::optional<NumberMantissaScaleGuard>& mantissaScaleGuard);
+
 }  // namespace xrpl

include/xrpl/protocol/STAmount.h

@@ -3,11 +3,13 @@
 #include <xrpl/basics/CountedObject.h>
 #include <xrpl/basics/LocalValue.h>
 #include <xrpl/basics/Number.h>
+#include <xrpl/beast/utility/Journal.h>
 #include <xrpl/beast/utility/instrumentation.h>
 #include <xrpl/protocol/Asset.h>
 #include <xrpl/protocol/IOUAmount.h>
 #include <xrpl/protocol/Issue.h>
 #include <xrpl/protocol/MPTAmount.h>
+#include <xrpl/protocol/Protocol.h>
 #include <xrpl/protocol/SField.h>
 #include <xrpl/protocol/STBase.h>
 #include <xrpl/protocol/Serializer.h>
@@ -187,7 +189,6 @@ public:
     /**
      * Checks if this amount evaluates to zero when constrained to a specific
      * accounting scale.
-     *
      * For XRP and MPT `roundToScale` is a no-op, returns true only when the amount itself is zero.
      * The `scale` argument is ignored in that case.
      * For IOU, the amount is rounded to the given scale using Number::RoundingMode::ToNearest mode
@@ -558,7 +559,7 @@ STAmount::fromNumber(A const& a, Number const& number)
         return STAmount{asset, intValue, 0, negative};
     }
 
-    auto const [mantissa, exponent] = working.normalizeToRange(kMinValue, kMaxValue);
+    auto const [mantissa, exponent] = working.normalizeToRange<kMinValue, kMaxValue>();
 
     return STAmount{asset, mantissa, exponent, negative};
 }
@@ -593,12 +594,25 @@ STAmount::value() const noexcept
     return *this;
 }
 
-inline bool
+[[nodiscard]] inline bool
 isLegalNet(STAmount const& value)
 {
     return !value.native() || (value.mantissa() <= STAmount::kMaxNativeN);
 }
 
+[[nodiscard]] inline bool
+isLegalMPT(STAmount const& value)
+{
+    return !value.holds<MPTIssue>() ||
+        (!value.negative() && value.exponent() == 0 && value.mantissa() <= kMaxMpTokenAmount);
+}
+
+/* Check recursively if an object has invalid MPTAmount or XRPAmount in STAmount field.
+ * Calls isLegalNet() and isLegalMPT().
+ */
+[[nodiscard]] bool
+hasInvalidAmount(STBase const& field, beast::Journal j);
+
 //------------------------------------------------------------------------------
 //
 // Operators

include/xrpl/protocol/detail/features.macro

@@ -15,7 +15,7 @@
 // Add new amendments to the top of this list.
 // Keep it sorted in reverse chronological order.
 
-XRPL_FIX    (Cleanup3_2_0,                Supported::No,  VoteBehavior::DefaultNo)
+XRPL_FIX    (Cleanup3_2_0,                Supported::Yes, VoteBehavior::DefaultNo)
 XRPL_FEATURE(MPTokensV2,                  Supported::No,  VoteBehavior::DefaultNo)
 XRPL_FIX    (Cleanup3_1_3,                Supported::Yes, VoteBehavior::DefaultYes)
 XRPL_FIX    (BatchInnerSigs,              Supported::No,  VoteBehavior::DefaultNo)

include/xrpl/protocol_autogen/README.md

@@ -15,8 +15,8 @@ Generation requires a one-time setup step to create a virtual environment
 and install Python dependencies, followed by running the generation target:
 
 ```bash
-cmake --build . --target setup_code_gen  # create venv and install dependencies (once)
-cmake --build . --target code_gen        # generate code
+cmake --build . --target setup_code_gen # create venv and install dependencies (once)
+cmake --build . --target code_gen       # generate code
 ```
 
 By default, `CODEGEN_VENV_DIR` points to `.venv` in the project root. The

include/xrpl/server/detail/Door.h

@@ -23,7 +23,6 @@
 #include <sys/resource.h>
 
 #include <dirent.h>
-#include <unistd.h>
 #endif
 
 #include <algorithm>
@@ -99,7 +98,10 @@ private:
     static constexpr std::chrono::milliseconds kMaxAcceptDelay{2000};
     std::chrono::milliseconds acceptDelay_{kInitialAcceptDelay};
     boost::asio::steady_timer backoffTimer_;
-    static constexpr double kFreeFdThreshold = 0.70;
+    static constexpr std::uint64_t kMaxUsedFdPercent = 70;
+    static constexpr std::chrono::milliseconds kFdSampleInterval{250};
+    clock_type::time_point fdSampleAt_;
+    bool cachedThrottle_{false};
 
     struct FDStats
     {
@@ -280,6 +282,7 @@ Door<Handler>::Door(
     , acceptor_(ioContext)
     , strand_(boost::asio::make_strand(ioContext))
     , backoffTimer_(ioContext)
+    , fdSampleAt_(clock_type::now() - kFdSampleInterval)
 {
     reOpen();
 }
@@ -338,11 +341,11 @@ Door<Handler>::doAccept(boost::asio::yield_context doYield)
     {
         if (shouldThrottleForFds())
         {
+            JLOG(j_.warn()) << "Throttling do_accept for " << acceptDelay_.count() << "ms.";
             backoffTimer_.expires_after(acceptDelay_);
             boost::system::error_code tec;
             backoffTimer_.async_wait(doYield[tec]);
             acceptDelay_ = std::min(acceptDelay_ * 2, kMaxAcceptDelay);
-            JLOG(j_.warn()) << "Throttling do_accept for " << acceptDelay_.count() << "ms.";
             continue;
         }
 
@@ -359,8 +362,11 @@ Door<Handler>::doAccept(boost::asio::yield_context doYield)
             if (ec == boost::asio::error::no_descriptors ||
                 ec == boost::asio::error::no_buffer_space)
             {
-                JLOG(j_.warn()) << "accept: Too many open files. Pausing for "
-                                << acceptDelay_.count() << "ms.";
+                char const* const cause = (ec == boost::asio::error::no_descriptors)
+                    ? "too many open files"
+                    : "kernel buffer space exhausted";
+                JLOG(j_.warn()) << "accept: " << cause << ". Pausing for " << acceptDelay_.count()
+                                << "ms.";
 
                 backoffTimer_.expires_after(acceptDelay_);
                 boost::system::error_code tec;
@@ -428,14 +434,15 @@ Door<Handler>::shouldThrottleForFds()
 #if BOOST_OS_WINDOWS
     return false;
 #else
-    auto const stats = queryFdStats();
-    if (!stats || stats->limit == 0)
-        return false;
+    auto const now = clock_type::now();
+    if (now - fdSampleAt_ < kFdSampleInterval)
+        return cachedThrottle_;
 
-    auto const& s = *stats;
-    auto const free = (s.limit > s.used) ? (s.limit - s.used) : 0ull;
-    double const freeRatio = static_cast<double>(free) / static_cast<double>(s.limit);
-    return freeRatio < kFreeFdThreshold;
+    fdSampleAt_ = now;
+    auto const stats = queryFdStats();
+    cachedThrottle_ =
+        stats && stats->limit > 0 && stats->used * 100 > stats->limit * kMaxUsedFdPercent;
+    return cachedThrottle_;
 #endif
 }
 

include/xrpl/shamap/SHAMap.h

@@ -178,6 +178,31 @@ public:
     SHAMapHash
     getHash() const;
 
+    /** Recompute dirty node hashes in parallel and return the root hash.
+
+        Plan 7 Phase 2. Equivalent in output to `getHash()` on a freshly
+        mutated map: it recomputes the hash of every node dirtied since the
+        last hash settle, bottom-up, then returns the root hash. The work is
+        fanned out by top-level subtree — the root's up-to-16 children are
+        independent (a dirty node under one branch is never shared with
+        another), so their subtree recomputations run concurrently with no
+        synchronization, and only the root hash is computed serially after.
+
+        Byte-identical to the serial path by construction: a node's hash is a
+        pure function of its children's hashes, so computation order is
+        irrelevant as long as children precede parents — which the bottom-up
+        walk guarantees.
+
+        Unlike `getHash()`/`unshare()`, this does NOT convert nodes to shared
+        (cowid stays as-is) or flush to the nodestore; it only refreshes hash
+        caches. A subsequent `getHash()` therefore returns immediately.
+
+        @param workers Maximum concurrent subtree recomputations. <= 1 runs
+                       serially. Defaults to the hardware concurrency.
+    */
+    SHAMapHash
+    updateHashesParallel(int workers = 0);
+
     // save a copy if you have a temporary anyway
     bool
     updateGiveItem(SHAMapNodeType type, boost::intrusive_ptr<SHAMapItem const> item);

include/xrpl/tx/Transactor.h

@@ -398,6 +398,15 @@ private:
     static NotTEC
     preflight2(PreflightContext const& ctx);
 
+    /** Universal validations
+       - Valid MPTAmount and XRPAmount
+
+        Do not try to call preflightUniversal from preflight() in derived classes. See
+        the description of invokePreflight for details.
+    */
+    static NotTEC
+    preflightUniversal(PreflightContext const& ctx);
+
     /** Check transaction-specific invariants only.
      *
      *  Walks every modified ledger entry via visitInvariantEntry, then
@@ -463,6 +472,9 @@ Transactor::invokePreflight(PreflightContext const& ctx)
     if (auto const ret = preflight1(ctx, T::getFlagsMask(ctx)))
         return ret;
 
+    if (auto const ret = preflightUniversal(ctx))
+        return ret;
+
     if (auto const ret = T::preflight(ctx))
         return ret;
 

include/xrpl/tx/invariants/InvariantCheck.h

@@ -373,6 +373,21 @@ public:
     finalize(STTx const&, TER const, XRPAmount const, ReadView const&, beast::Journal const&);
 };
 
+/** Verify that MPT/XRP STAmounts are canonical in any ledger entries left after the
+ * transaction applies.
+ */
+class ValidAmounts
+{
+    std::vector<std::shared_ptr<SLE const>> afterEntries_;
+
+public:
+    void
+    visitEntry(bool, std::shared_ptr<SLE const> const&, std::shared_ptr<SLE const> const&);
+
+    [[nodiscard]] bool
+    finalize(STTx const&, TER const, XRPAmount const, ReadView const&, beast::Journal const&) const;
+};
+
 // additional invariant checks can be declared above and then added to this
 // tuple
 using InvariantChecks = std::tuple<
@@ -401,7 +416,9 @@ using InvariantChecks = std::tuple<
     ValidLoanBroker,
     ValidLoan,
     ValidVault,
-    ValidMPTPayment>;
+    ValidMPTPayment,
+    ValidAmounts,
+    ValidMPTTransfer>;
 
 /**
  * @brief get a tuple of all invariant checks

include/xrpl/tx/invariants/MPTInvariant.h

@@ -71,4 +71,42 @@ public:
     finalize(STTx const&, TER const, XRPAmount const, ReadView const&, beast::Journal const&);
 };
 
+class ValidMPTTransfer
+{
+    struct Value
+    {
+        std::optional<std::uint64_t> amtBefore;
+        std::optional<std::uint64_t> amtAfter;
+    };
+    // MPTID: {holder: Value}
+    hash_map<uint192, hash_map<AccountID, Value>> amount_;
+    // Deleted MPToken
+    // MPToken key: true if MPTAuthorized is set
+    hash_map<uint256, bool> deletedAuthorized_;
+
+public:
+    void
+    visitEntry(bool, std::shared_ptr<SLE const> const&, std::shared_ptr<SLE const> const&);
+
+    bool
+    finalize(STTx const&, TER const, XRPAmount const, ReadView const&, beast::Journal const&);
+
+private:
+    /**
+     * @brief Check whether a holder is authorized to send or receive an MPToken.
+     *
+     * Deleted MPToken SLEs are no longer present in the view by the time
+     * finalize() runs, so their authorization state is captured during
+     * visitEntry() and stored in deletedAuthorized_. For deleted MPTokens,
+     * returns true if reqAuth is false or lsfMPTAuthorized was set at deletion.
+     * For existing MPTokens, returns the result of requireAuth()
+     */
+    [[nodiscard]] bool
+    isAuthorized(
+        ReadView const& view,
+        MPTID const& mptid,
+        AccountID const& holder,
+        bool requireAuth) const;
+};
+
 }  // namespace xrpl

include/xrpl/tx/invariants/VaultInvariant.h

@@ -4,9 +4,11 @@
 #include <xrpl/basics/base_uint.h>
 #include <xrpl/beast/utility/Journal.h>
 #include <xrpl/ledger/ReadView.h>
+#include <xrpl/protocol/AccountID.h>
 #include <xrpl/protocol/MPTIssue.h>
 #include <xrpl/protocol/STTx.h>
 #include <xrpl/protocol/TER.h>
+#include <xrpl/protocol/XRPAmount.h>
 
 #include <optional>
 #include <unordered_map>
@@ -79,16 +81,83 @@ private:
     std::vector<Shares> beforeMPTs_;
     std::unordered_map<uint256, DeltaInfo> deltas_;
 
+    /**
+     * @brief Compute the minimum STAmount scale for rounding invariant
+     *        calculations.
+     *
+     * Post-amendment (@c fixCleanup3_2_0) this is simply the posterior
+     * @c assetsTotal scale.  Pre-amendment it is the coarsest scale across
+     * @p vaultDelta and both asset-field deltas.
+     *
+     * @param vaultDelta Delta of the vault's asset balance for this transaction.
+     * @param rules      Active ledger rules (used to check the amendment).
+     * @returns The minimum scale to apply when rounding vault-related amounts.
+     */
+    [[nodiscard]] std::int32_t
+    computeVaultMinScale(DeltaInfo const& vaultDelta, Rules const& rules) const;
+
+    /**
+     * @brief Return the vault-asset balance-change delta for an account.
+     *
+     * Looks up the ledger-entry delta recorded during @c visitEntry for the
+     * account entry (XRP), trust line (IOU), or MPToken (MPT) that corresponds
+     * to the vault asset held by @p id.
+     *
+     * @param id Account whose asset delta is requested.
+     * @returns The delta, or @c std::nullopt if the entry was not touched.
+     */
+    [[nodiscard]] std::optional<DeltaInfo>
+    deltaAssets(AccountID const& id) const;
+
+    /**
+     * @brief Return the vault-asset delta for the transaction's sending
+     *        account, adjusted for the fee.
+     *
+     * Calls @c deltaAssets for @c tx[sfAccount] and, for non-delegated XRP
+     * transactions, adds the consumed fee back so the invariant sees the net
+     * asset movement rather than the fee-reduced balance change.
+     *
+     * @param tx  The transaction being applied.
+     * @param fee Fee charged by this transaction.
+     * @returns The fee-adjusted delta, or @c std::nullopt if the net delta is
+     *          zero or the account entry was not touched.
+     */
+    [[nodiscard]] std::optional<DeltaInfo>
+    deltaAssetsTxAccount(STTx const& tx, XRPAmount fee) const;
+
+    /**
+     * @brief Return the vault-share balance-change delta for an account.
+     *
+     * For the vault's pseudo-account the @c MPTokenIssuance outstanding-amount
+     * delta is returned; for all other accounts the @c MPToken delta is
+     * returned.
+     *
+     * @param id Account whose share delta is requested.
+     * @returns The delta, or @c std::nullopt if the entry was not touched.
+     */
+    [[nodiscard]] std::optional<DeltaInfo>
+    deltaShares(AccountID const& id) const;
+
+    /**
+     * @brief Check whether a vault holds no assets.
+     *
+     * @param vault Snapshot of the vault to test.
+     * @returns @c true when both @c assetsAvailable and @c assetsTotal are
+     *          zero.
+     */
+    [[nodiscard]] static bool
+    isVaultEmpty(Vault const& vault);
+
 public:
+    // Compute the coarsest scale required to represent all numbers
+    [[nodiscard]] static std::int32_t
+    computeCoarsestScale(std::vector<DeltaInfo> const& numbers);
+
     void
     visitEntry(bool, std::shared_ptr<SLE const> const&, std::shared_ptr<SLE const> const&);
 
     bool
     finalize(STTx const&, TER const, XRPAmount const, ReadView const&, beast::Journal const&);
-
-    // Compute the coarsest scale required to represent all numbers
-    [[nodiscard]] static std::int32_t
-    computeCoarsestScale(std::vector<DeltaInfo> const& numbers);
 };
 
 }  // namespace xrpl

include/xrpl/tx/transactors/escrow/EscrowCreate.h

@@ -16,6 +16,9 @@ public:
     static TxConsequences
     makeTxConsequences(PreflightContext const& ctx);
 
+    static bool
+    checkExtraFeatures(PreflightContext const& ctx);
+
     static NotTEC
     preflight(PreflightContext const& ctx);
 

nix/ci-env.nix

@@ -1,39 +1,102 @@
 {
   pkgs,
-  glibc231,
+  customGlibc,
   ...
 }:
 let
   inherit (import ./packages.nix { inherit pkgs; }) commonPackages;
+  inherit (pkgs) lib;
 
-  # binutils wrapped to emit binaries that reference glibc 2.31 (dynamic
-  # linker path, library search path, RPATH).
-  binutils231 = pkgs.wrapBintoolsWith {
+  # Underlying compiler toolchains to wrap. Bump these in one place to
+  # roll the whole environment forward.
+  customGccPackage = pkgs.gcc15;
+  customLlvmPackages = pkgs.llvmPackages_22;
+  customClangMajor = lib.versions.major (lib.getVersion customLlvmPackages.clang-unwrapped);
+
+  # binutils wrapped to emit binaries that reference the custom glibc
+  # (dynamic linker path, library search path, RPATH).
+  customBinutils = pkgs.wrapBintoolsWith {
     bintools = pkgs.binutils-unwrapped;
-    libc = glibc231;
+    libc = customGlibc;
   };
 
-  # Rebuild gcc 15 (specifically libstdc++ / libgcc_s) against glibc 2.31.
-  # The override swaps gcc15.cc's bootstrap stdenv for one that uses the
-  # existing gcc 15 binary but links against glibc 2.31, so the resulting
-  # compiler ships runtime libraries that only reference symbols available
-  # in glibc 2.31.
-  gcc15CcWithGlibc231 = pkgs.gcc15.cc.override {
+  # Rebuild gcc (specifically libstdc++ / libgcc_s) against the custom
+  # glibc. The override swaps gcc.cc's bootstrap stdenv for one that uses
+  # the existing gcc binary but links against the custom glibc, so the
+  # resulting compiler ships runtime libraries that only reference symbols
+  # available in that glibc.
+  customGccCc = customGccPackage.cc.override {
     stdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv (
       pkgs.wrapCCWith {
-        cc = pkgs.gcc15.cc;
-        libc = glibc231;
-        bintools = binutils231;
+        cc = customGccPackage.cc;
+        libc = customGlibc;
+        bintools = customBinutils;
       }
     );
   };
 
-  # cc-wrapper around the rebuilt compiler, pointing at glibc 2.31 headers
-  # and libraries. This is what we actually expose to users.
-  gcc15WithGlibc231 = pkgs.wrapCCWith {
-    cc = gcc15CcWithGlibc231;
-    libc = glibc231;
-    bintools = binutils231;
+  # cc-wrapper around the rebuilt compiler, pointing at the custom glibc
+  # headers and libraries. This is what we actually expose to users.
+  customGcc = pkgs.wrapCCWith {
+    cc = customGccCc;
+    libc = customGlibc;
+    bintools = customBinutils;
+  };
+
+  # stdenv built around the rebuilt gcc / custom glibc. Used to rebuild
+  # compiler-rt below so its sanitizer runtimes see the custom glibc
+  # headers.
+  customStdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv customGcc;
+
+  # Rebuild compiler-rt against the custom glibc so the sanitizer runtimes
+  # don't use glibc symbols (or sysconf constants like _SC_SIGSTKSZ) that
+  # only exist in newer glibc versions. scudo is dropped because its CMake
+  # includes CheckAtomic with -nostdinc++ in CMAKE_REQUIRED_FLAGS, which
+  # makes std::atomic unfindable in our stdenv; we don't use scudo (only
+  # asan/ubsan/tsan etc.).
+  customCompilerRt =
+    (customLlvmPackages.compiler-rt.override {
+      stdenv = customStdenv;
+    }).overrideAttrs
+      (old: {
+        postPatch = (old.postPatch or "") + ''
+          substituteInPlace lib/CMakeLists.txt \
+            --replace-quiet 'add_subdirectory(scudo/standalone)' \
+                            '# scudo/standalone disabled in xrpld ci-env'
+        '';
+      });
+
+  # cc-wrapper around clang, pointing at the custom glibc headers and
+  # libraries. Reuses the rebuilt gcc for libstdc++ / libgcc_s so that
+  # C++ binaries produced by clang also only reference symbols available
+  # in the custom glibc. compiler-rt is wired into a resource-root so
+  # sanitizer runtimes (libclang_rt.*.a) are found at link time; this
+  # mirrors what nixpkgs does internally when building llvmPackages.clang.
+  customClang = pkgs.wrapCCWith {
+    cc = customLlvmPackages.clang-unwrapped;
+    libc = customGlibc;
+    bintools = customBinutils;
+    gccForLibs = customGccCc;
+    extraPackages = [ customCompilerRt ];
+    extraBuildCommands = ''
+      rsrc="$out/resource-root"
+      mkdir "$rsrc"
+      ln -s "${customLlvmPackages.clang-unwrapped.lib}/lib/clang/${customClangMajor}/include" "$rsrc/include"
+      ln -s "${customCompilerRt.out}/lib" "$rsrc/lib"
+      ln -s "${customCompilerRt.out}/share" "$rsrc/share" || true
+      echo "-resource-dir=$rsrc" >> $out/nix-support/cc-cflags
+    '';
+  };
+
+  # Strip the generic cc/c++/cpp symlinks from the clang wrapper so it can
+  # coexist with the gcc wrapper in buildEnv. gcc remains the default
+  # compiler (cc/c++/cpp); clang is invoked explicitly as clang/clang++.
+  customClangForCiEnv = pkgs.symlinkJoin {
+    name = "clang-wrapper-custom-for-ci-env";
+    paths = [ customClang ];
+    postBuild = ''
+      rm -f $out/bin/cc $out/bin/c++ $out/bin/cpp
+    '';
   };
 
 in
@@ -41,8 +104,9 @@ in
   default = pkgs.buildEnv {
     name = "xrpld-ci-env";
     paths = commonPackages ++ [
-      gcc15WithGlibc231
-      binutils231
+      customGcc
+      customClangForCiEnv
+      customBinutils
     ];
     pathsToLink = [
       "/bin"

nix/packages.nix

@@ -17,6 +17,7 @@ in
     llvmPackages_22.clang-tools
     mold
     ninja
+    patchelf
     perl # needed for openssl
     pkg-config
     pre-commit

nix/utils.nix

@@ -1,4 +1,4 @@
-{ nixpkgs, nixpkgs-glibc231 }:
+{ nixpkgs, nixpkgs-custom-glibc }:
 function:
 nixpkgs.lib.genAttrs
   [
@@ -12,10 +12,10 @@ nixpkgs.lib.genAttrs
     function {
       pkgs = import nixpkgs { inherit system; };
       # glibc 2.31 — matches the system libc on Ubuntu 20.04 LTS. Sourced
-      # from the nixpkgs snapshot pinned via the `nixpkgs-glibc231` flake
-      # input, so the build uses the compiler from that snapshot
+      # from the nixpkgs snapshot pinned via the `nixpkgs-custom-glibc`
+      # flake input, so the build uses the compiler from that snapshot
       # (gcc 9.3.0) along with the matching patches, configure flags, and
       # hardening defaults.
-      glibc231 = (import nixpkgs-glibc231 { inherit system; }).glibc;
+      customGlibc = (import nixpkgs-custom-glibc { inherit system; }).glibc;
     }
   )

package/README.md

@@ -74,10 +74,10 @@ VERSION=2.4.0-local
 PKG_RELEASE=1
 
 docker run --rm \
-  -v "$(pwd):/src" \
-  -w /src \
-  "$IMAGE" \
-  ./package/build_pkg.sh --pkg-version "$VERSION" --pkg-release "$PKG_RELEASE"
+    -v "$(pwd):/src" \
+    -w /src \
+    "$IMAGE" \
+    ./package/build_pkg.sh --pkg-version "$VERSION" --pkg-release "$PKG_RELEASE"
 
 # Output:
 #   build/debbuild/*.deb         (DEB + dbgsym .ddeb)
@@ -92,12 +92,12 @@ needed, but the host toolchain replaces the pinned CI image:
 
 ```bash
 cmake \
-  -Dxrpld=ON \
-  -Dxrpld_version=2.4.0-local \
-  -Dtests=OFF \
-  ..
+    -Dxrpld=ON \
+    -Dxrpld_version=2.4.0-local \
+    -Dtests=OFF \
+    ..
 
-cmake --build . --target package       # deb on Debian/Ubuntu, rpm on RHEL
+cmake --build . --target package # deb on Debian/Ubuntu, rpm on RHEL
 ```
 
 The `cmake/XrplPackaging.cmake` module defines the target only if at least one

package/build_pkg.sh

@@ -36,12 +36,35 @@ SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH:-}"
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --src-dir)            need_arg "$@"; SRC_DIR="$2";           shift 2 ;;
-        --build-dir)          need_arg "$@"; BUILD_DIR="$2";         shift 2 ;;
-        --pkg-version)        need_arg "$@"; PKG_VERSION="$2";       shift 2 ;;
-        --pkg-release)        need_arg "$@"; PKG_RELEASE="$2";       shift 2 ;;
-        --source-date-epoch)  need_arg "$@"; SOURCE_DATE_EPOCH="$2"; shift 2 ;;
-        -h|--help)            usage; exit 0 ;;
+        --src-dir)
+            need_arg "$@"
+            SRC_DIR="$2"
+            shift 2
+            ;;
+        --build-dir)
+            need_arg "$@"
+            BUILD_DIR="$2"
+            shift 2
+            ;;
+        --pkg-version)
+            need_arg "$@"
+            PKG_VERSION="$2"
+            shift 2
+            ;;
+        --pkg-release)
+            need_arg "$@"
+            PKG_RELEASE="$2"
+            shift 2
+            ;;
+        --source-date-epoch)
+            need_arg "$@"
+            SOURCE_DATE_EPOCH="$2"
+            shift 2
+            ;;
+        -h | --help)
+            usage
+            exit 0
+            ;;
         *)
             echo "Unknown argument: $1" >&2
             usage >&2
@@ -109,20 +132,20 @@ stage_common() {
     local dest="$1"
     mkdir -p "${dest}"
 
-    cp "${BUILD_DIR}/xrpld"                     "${dest}/xrpld"
-    cp "${SRC_DIR}/cfg/xrpld-example.cfg"       "${dest}/xrpld.cfg"
-    cp "${SRC_DIR}/cfg/validators-example.txt"  "${dest}/validators.txt"
-    cp "${SRC_DIR}/LICENSE.md"                  "${dest}/LICENSE.md"
-    cp "${SRC_DIR}/README.md"                   "${dest}/README.md"
+    cp "${BUILD_DIR}/xrpld" "${dest}/xrpld"
+    cp "${SRC_DIR}/cfg/xrpld-example.cfg" "${dest}/xrpld.cfg"
+    cp "${SRC_DIR}/cfg/validators-example.txt" "${dest}/validators.txt"
+    cp "${SRC_DIR}/LICENSE.md" "${dest}/LICENSE.md"
+    cp "${SRC_DIR}/README.md" "${dest}/README.md"
 
-    cp "${SHARED}/xrpld.service"                "${dest}/xrpld.service"
-    cp "${SHARED}/xrpld.sysusers"               "${dest}/xrpld.sysusers"
-    cp "${SHARED}/xrpld.tmpfiles"               "${dest}/xrpld.tmpfiles"
-    cp "${SHARED}/xrpld.logrotate"              "${dest}/xrpld.logrotate"
-    cp "${SHARED}/update-xrpld"                 "${dest}/update-xrpld"
-    cp "${SHARED}/update-xrpld.service"         "${dest}/update-xrpld.service"
-    cp "${SHARED}/update-xrpld.timer"           "${dest}/update-xrpld.timer"
-    cp "${SHARED}/50-xrpld.preset"              "${dest}/50-xrpld.preset"
+    cp "${SHARED}/xrpld.service" "${dest}/xrpld.service"
+    cp "${SHARED}/xrpld.sysusers" "${dest}/xrpld.sysusers"
+    cp "${SHARED}/xrpld.tmpfiles" "${dest}/xrpld.tmpfiles"
+    cp "${SHARED}/xrpld.logrotate" "${dest}/xrpld.logrotate"
+    cp "${SHARED}/update-xrpld" "${dest}/update-xrpld"
+    cp "${SHARED}/update-xrpld.service" "${dest}/update-xrpld.service"
+    cp "${SHARED}/update-xrpld.timer" "${dest}/update-xrpld.timer"
+    cp "${SHARED}/50-xrpld.preset" "${dest}/50-xrpld.preset"
 }
 
 build_rpm() {
@@ -135,8 +158,12 @@ build_rpm() {
 
     # RPM Version can't contain '-'. A pre-release goes in Release with a
     # leading "0." so 3.2.0-b1 sorts before the final 3.2.0-<pkg_release>.
+    # The order is "0.<pkg_release>.<suffix>" (e.g. 0.1.b6) — the Fedora/EPEL
+    # convention. Reversing to "0.<suffix>.<pkg_release>" (e.g. 0.b6.1) breaks
+    # rpmvercmp against the former because numeric segments outrank alphabetic
+    # ones, so "0.1.b5" would sort newer than "0.b6.1".
     local rpm_release="${PKG_RELEASE}"
-    [[ -n "${VER_SUFFIX}" ]] && rpm_release="0.${VER_SUFFIX}.${PKG_RELEASE}"
+    [[ -n "${VER_SUFFIX}" ]] && rpm_release="0.${PKG_RELEASE}.${VER_SUFFIX}"
 
     set -x
     rpmbuild -bb \
@@ -155,12 +182,12 @@ build_deb() {
     cp -r "${DEBIAN_DIR}" "${staging}/debian"
 
     # Debhelper auto-discovers these only from debian/.
-    cp "${staging}/xrpld.service"        "${staging}/debian/xrpld.service"
-    cp "${staging}/xrpld.sysusers"       "${staging}/debian/xrpld.sysusers"
-    cp "${staging}/xrpld.tmpfiles"       "${staging}/debian/xrpld.tmpfiles"
-    cp "${staging}/xrpld.logrotate"      "${staging}/debian/xrpld.logrotate"
+    cp "${staging}/xrpld.service" "${staging}/debian/xrpld.service"
+    cp "${staging}/xrpld.sysusers" "${staging}/debian/xrpld.sysusers"
+    cp "${staging}/xrpld.tmpfiles" "${staging}/debian/xrpld.tmpfiles"
+    cp "${staging}/xrpld.logrotate" "${staging}/debian/xrpld.logrotate"
     cp "${staging}/update-xrpld.service" "${staging}/debian/xrpld.update-xrpld.service"
-    cp "${staging}/update-xrpld.timer"   "${staging}/debian/xrpld.update-xrpld.timer"
+    cp "${staging}/update-xrpld.timer" "${staging}/debian/xrpld.update-xrpld.timer"
 
     # Debian '~' marks a pre-release; 3.2.0~b1 sorts before 3.2.0.
     local deb_full_version="${VER_BASE}${VER_SUFFIX:+~${VER_SUFFIX}}-${PKG_RELEASE}"
@@ -171,12 +198,12 @@ build_deb() {
     #   b<N>, rc<N> -> unstable  (pre-release)
     local deb_distribution
     case "${VER_SUFFIX}" in
-        "")   deb_distribution="stable" ;;
-        b0)   deb_distribution="develop" ;;
-        *)    deb_distribution="unstable" ;;
+        "") deb_distribution="stable" ;;
+        b0) deb_distribution="develop" ;;
+        *) deb_distribution="unstable" ;;
     esac
 
-    cat > "${staging}/debian/changelog" <<EOF
+    cat >"${staging}/debian/changelog" <<EOF
 xrpld (${deb_full_version}) ${deb_distribution}; urgency=medium
   * Release ${VERSION}.
 
@@ -186,7 +213,7 @@ EOF
     chmod +x "${staging}/debian/rules"
 
     set -x
-    ( cd "${staging}" && dpkg-buildpackage -b --no-sign -d )
+    (cd "${staging}" && dpkg-buildpackage -b --no-sign -d)
 }
 
 "build_${pkg_type}"

package/debian/rules

@@ -9,7 +9,7 @@ override_dh_auto_configure override_dh_auto_build override_dh_auto_test:
 	@:
 
 override_dh_installsystemd:
-	dh_installsystemd --no-start xrpld.service
+	dh_installsystemd --no-stop-on-upgrade xrpld.service
 	dh_installsystemd --name=update-xrpld --no-start update-xrpld.service update-xrpld.timer
 
 execute_before_dh_installtmpfiles:

package/shared/update-xrpld

@@ -22,7 +22,7 @@ PATH=/usr/sbin:/usr/bin:/sbin:/bin
 PKG_NAME=${PKG_NAME:-xrpld}
 
 log() {
-# If running under systemd/journald, let it handle timestamps.
+    # If running under systemd/journald, let it handle timestamps.
     if [[ -n "${JOURNAL_STREAM:-}" ]]; then
         printf '%s\n' "$*"
     else
@@ -33,7 +33,7 @@ log() {
 require_root() {
     if [[ ${EUID:-$(id -u)} -ne 0 ]]; then
         log "RESULT: failed reason=not-root"
-            exit 1
+        exit 1
     fi
 }
 

src/libxrpl/basics/Number.cpp

@@ -10,9 +10,11 @@
 #include <iterator>
 #include <limits>
 #include <numeric>
+#include <set>
 #include <stdexcept>
 #include <string>
 #include <type_traits>
+#include <unordered_map>
 #include <utility>
 
 #ifdef _MSC_VER
@@ -28,7 +30,76 @@ using int128_t = __int128_t;
 namespace xrpl {
 
 thread_local Number::RoundingMode Number::mode = Number::RoundingMode::ToNearest;
-thread_local std::reference_wrapper<MantissaRange const> Number::kRange = kLargeRange;
+thread_local std::reference_wrapper<MantissaRange const> Number::kRange =
+    MantissaRange::getMantissaRange(MantissaRange::MantissaScale::Large);
+
+std::set<MantissaRange::MantissaScale> const&
+MantissaRange::getAllScales()
+{
+    static std::set<MantissaRange::MantissaScale> const kScales = {
+        MantissaRange::MantissaScale::Small,
+        MantissaRange::MantissaScale::LargeLegacy,
+        MantissaRange::MantissaScale::Large,
+    };
+    return kScales;
+}
+
+std::unordered_map<MantissaRange::MantissaScale, MantissaRange> const&
+MantissaRange::getRanges()
+{
+    static auto const kMap = []() {
+        std::unordered_map<MantissaScale, MantissaRange> map;
+        for (auto const scale : getAllScales())
+        {
+            map.emplace(scale, scale);
+        }
+
+        // Use these constexpr declarations to do static_asserts to verify the MantissaRanges are
+        // created correctly, but nothing else.
+        {
+            [[maybe_unused]]
+            constexpr static MantissaRange kRange{MantissaRange::MantissaScale::Small};
+            static_assert(isPowerOfTen(kRange.min));
+            static_assert(kRange.min == 1'000'000'000'000'000LL);
+            static_assert(kRange.max == 9'999'999'999'999'999LL);
+            static_assert(kRange.log == 15);
+            static_assert(kRange.min < Number::kMaxRep);
+            static_assert(kRange.max < Number::kMaxRep);
+            static_assert(kRange.cuspRoundingFixEnabled == CuspRoundingFix::Disabled);
+        }
+        {
+            [[maybe_unused]]
+            constexpr static MantissaRange kRange{MantissaRange::MantissaScale::LargeLegacy};
+            static_assert(isPowerOfTen(kRange.min));
+            static_assert(kRange.min == 1'000'000'000'000'000'000ULL);
+            static_assert(kRange.max == rep(9'999'999'999'999'999'999ULL));
+            static_assert(kRange.log == 18);
+            static_assert(kRange.min < Number::kMaxRep);
+            static_assert(kRange.max > Number::kMaxRep);
+            static_assert(kRange.cuspRoundingFixEnabled == CuspRoundingFix::Disabled);
+        }
+        {
+            [[maybe_unused]]
+            constexpr static MantissaRange kRange{MantissaRange::MantissaScale::Large};
+            static_assert(isPowerOfTen(kRange.min));
+            static_assert(kRange.min == 1'000'000'000'000'000'000ULL);
+            static_assert(kRange.max == rep(9'999'999'999'999'999'999ULL));
+            static_assert(kRange.log == 18);
+            static_assert(kRange.min < Number::kMaxRep);
+            static_assert(kRange.max > Number::kMaxRep);
+            static_assert(kRange.cuspRoundingFixEnabled == CuspRoundingFix::Enabled);
+        }
+        return map;
+    }();
+
+    return kMap;
+}
+
+MantissaRange const&
+MantissaRange::getMantissaRange(MantissaScale scale)
+{
+    return getRanges().at(scale);
+}
 
 Number::RoundingMode
 Number::getround()
@@ -51,10 +122,37 @@ Number::getMantissaScale()
 void
 Number::setMantissaScale(MantissaRange::MantissaScale scale)
 {
-    if (scale != MantissaRange::MantissaScale::Small &&
-        scale != MantissaRange::MantissaScale::Large)
+    if (!MantissaRange::getAllScales().contains(scale))
         logicError("Unknown mantissa scale");
-    kRange = scale == MantissaRange::MantissaScale::Small ? kSmallRange : kLargeRange;
+    kRange = MantissaRange::getMantissaRange(scale);
+}
+
+// Optimization equivalent to:
+// auto r = static_cast<unsigned>(u % 10);
+// u /= 10;
+// return r;
+// Derived from Hacker's Delight Second Edition Chapter 10
+// by Henry S. Warren, Jr.
+static inline unsigned
+divu10(uint128_t& u)
+{
+    // q = u * 0.75
+    auto q = (u >> 1) + (u >> 2);
+    // iterate towards q = u * 0.8
+    q += q >> 4;
+    q += q >> 8;
+    q += q >> 16;
+    q += q >> 32;
+    q += q >> 64;
+    // q /= 8 approximately == u / 10
+    q >>= 3;
+    // r = u - q * 10  approximately == u % 10
+    auto r = static_cast<unsigned>(u - ((q << 3) + (q << 1)));
+    // correction c is 1 if r >= 10 else 0
+    auto c = (r + 6) >> 4;
+    u = q + c;
+    r -= c * 10;
+    return r;
 }
 
 // Guard
@@ -92,6 +190,18 @@ public:
     unsigned
     pop() noexcept;
 
+    /** Drop a digit from the mantissa, and increment the exponent, storing the dropped digit in
+     * this Guard.
+     *
+     * Substitute for:
+                push(mantissa % 10);
+                mantissa /= 10;
+                ++exponent;
+     */
+    template <class T>
+    void
+    doDropDigit(T& mantissa, int& exponent) noexcept;
+
     // Indicate round direction:  1 is up, -1 is down, 0 is even
     // This enables the client to round towards nearest, and on
     // tie, round towards even.
@@ -107,6 +217,7 @@ public:
         int& exponent,
         internalrep const& minMantissa,
         internalrep const& maxMantissa,
+        MantissaRange::CuspRoundingFix cuspRoundingFixEnabled,
         std::string location);
 
     // Modify the result to the correctly rounded value
@@ -168,6 +279,27 @@ Number::Guard::pop() noexcept
     return d;
 }
 
+template <class T>
+void
+Number::Guard::doDropDigit(T& mantissa, int& exponent) noexcept
+{
+    push(mantissa % 10);
+    mantissa /= 10;
+    ++exponent;
+}
+
+// Use the divu10 optimization for uint128s
+template <>
+void
+Number::Guard::doDropDigit<uint128_t>(uint128_t& mantissa, int& exponent) noexcept
+{
+    // The following is optimization for:
+    // push(static_cast<unsigned>(mantissa % 10));
+    // mantissa /= 10;
+    push(divu10(mantissa));
+    ++exponent;
+}
+
 // Returns:
 //     -1 if Guard is less than half
 //      0 if Guard is exactly half
@@ -242,18 +374,60 @@ Number::Guard::doRoundUp(
     int& exponent,
     internalrep const& minMantissa,
     internalrep const& maxMantissa,
+    MantissaRange::CuspRoundingFix cuspRoundingFixEnabled,
     std::string location)
 {
     auto r = round();
     if (r == 1 || (r == 0 && (mantissa & 1) == 1))
     {
-        ++mantissa;
-        // Ensure mantissa after incrementing fits within both the
-        // min/maxMantissa range and is a valid "rep".
-        if (mantissa > maxMantissa || mantissa > kMaxRep)
+        auto const safeToIncrement = [&maxMantissa](auto const& mantissa) {
+            return mantissa < maxMantissa && mantissa < kMaxRep;
+        };
+        if (cuspRoundingFixEnabled == MantissaRange::CuspRoundingFix::Enabled)
         {
-            mantissa /= 10;
-            ++exponent;
+            // Ensure mantissa after incrementing fits within both the
+            // min/maxMantissa range and is a valid "rep".
+            if (safeToIncrement(mantissa))
+            {
+                // Nothing unusual here, just increment the mantissa
+                ++mantissa;
+            }
+            else
+            {
+                // Incrementing the mantissa will require dividing, which will require rounding. So
+                // _don't_ increment the mantissa. Instead, divide and round recursively. It should
+                // be impossible to recurse more than once, because once the mantissa is divided by
+                // 10, it will be _well_ under maxMantissa and kMaxRep, so adding 1 will have no
+                // change of bringing it back over.
+                doDropDigit(mantissa, exponent);
+                XRPL_ASSERT_PARTS(
+                    safeToIncrement(mantissa),
+                    "xrpl::Number::Guard::doRoundUp",
+                    "can't recurse more than once");
+                doRoundUp(
+                    negative,
+                    mantissa,
+                    exponent,
+                    minMantissa,
+                    maxMantissa,
+                    cuspRoundingFixEnabled,
+                    location);
+                return;
+            }
+        }
+        else
+        {
+            // Need to preserve the incorrect behavior until the fix amendment can be retired,
+            // because otherwise would risk an unplanned ledger fork.
+            ++mantissa;
+            // Ensure mantissa after incrementing fits within both the
+            // min/maxMantissa range and is a valid "rep".
+            if (mantissa > maxMantissa || mantissa > kMaxRep)
+            {
+                // Don't use doDropDigit here
+                mantissa /= 10;
+                ++exponent;
+            }
         }
     }
     bringIntoRange(negative, mantissa, exponent, minMantissa);
@@ -293,9 +467,9 @@ Number::Guard::doRound(rep& drops, std::string location) const
         {
             static_assert(sizeof(internalrep) == sizeof(rep));
             // This should be impossible, because it's impossible to represent
-            // "maxRep + 0.6" in Number, regardless of the scale. There aren't
-            // enough digits available. You'd either get a mantissa of "maxRep"
-            // or "(maxRep + 1) / 10", neither of which will round up when
+            // "kMaxRep + 0.6" in Number, regardless of the scale. There aren't
+            // enough digits available. You'd either get a mantissa of "kMaxRep"
+            // or "(kMaxRep + 1) / 10", neither of which will round up when
             // converting to rep, though the latter might overflow _before_
             // rounding.
             Throw<std::overflow_error>(std::string(location));  // LCOV_EXCL_LINE
@@ -331,29 +505,11 @@ Number::externalToInternal(rep mantissa)
     return static_cast<internalrep>(-temp);
 }
 
-constexpr Number
-Number::oneSmall()
-{
-    return Number{false, Number::kSmallRange.min, -Number::kSmallRange.log, Number::Unchecked{}};
-};
-
-constexpr Number kOneSml = Number::oneSmall();
-
-constexpr Number
-Number::oneLarge()
-{
-    return Number{false, Number::kLargeRange.min, -Number::kLargeRange.log, Number::Unchecked{}};
-};
-
-constexpr Number kOneLrg = Number::oneLarge();
-
 Number
 Number::one()
 {
-    if (&kRange.get() == &kSmallRange)
-        return kOneSml;
-    XRPL_ASSERT(&kRange.get() == &kLargeRange, "Number::one() : valid range");
-    return kOneLrg;
+    auto const& range = kRange.get();
+    return Number{false, range.min, -range.log, Number::Unchecked{}};
 }
 
 // Use the member names in this static function for now so the diff is cleaner
@@ -365,7 +521,8 @@ doNormalize(
     T& mantissa,
     int& exponent,
     MantissaRange::rep const& minMantissa,
-    MantissaRange::rep const& maxMantissa)
+    MantissaRange::rep const& maxMantissa,
+    MantissaRange::CuspRoundingFix cuspRoundingFixEnabled)
 {
     static constexpr auto kMinExponent = Number::kMinExponent;
     static constexpr auto kMaxExponent = Number::kMaxExponent;
@@ -394,9 +551,7 @@ doNormalize(
     {
         if (exponent >= kMaxExponent)
             throw std::overflow_error("Number::normalize 1");
-        g.push(m % 10);
-        m /= 10;
-        ++exponent;
+        g.doDropDigit(m, exponent);
     }
     if ((exponent < kMinExponent) || (m < minMantissa))
     {
@@ -407,7 +562,7 @@ doNormalize(
     }
 
     // When using the largeRange, "m" needs fit within an int64, even if
-    // the final mantissa_ is going to end up larger to fit within the
+    // the final mantissa is going to end up larger to fit within the
     // MantissaRange. Cut it down here so that the rounding will be done while
     // it's smaller.
     //
@@ -415,26 +570,31 @@ doNormalize(
     //      so "m" will be modified to 990,000,000,000,012,345. Then that value
     //      will be rounded to 990,000,000,000,012,345 or
     //      990,000,000,000,012,346, depending on the rounding mode. Finally,
-    //      mantissa_ will be "m*10" so it fits within the range, and end up as
+    //      mantissa will be "m*10" so it fits within the range, and end up as
     //      9,900,000,000,000,123,450 or 9,900,000,000,000,123,460.
-    // mantissa() will return mantissa_ / 10, and exponent() will return
-    // exponent_ + 1.
+    // mantissa() will return mantissa / 10, and exponent() will return
+    // exponent + 1.
     if (m > kMaxRep)
     {
         if (exponent >= kMaxExponent)
             throw std::overflow_error("Number::normalize 1.5");
-        g.push(m % 10);
-        m /= 10;
-        ++exponent;
+        g.doDropDigit(m, exponent);
     }
     // Before modification, m should be within the min/max range. After
-    // modification, it must be less than maxRep. In other words, the original
-    // value should have been no more than maxRep * 10.
-    // (maxRep * 10 > maxMantissa)
+    // modification, it must be less than kMaxRep. In other words, the original
+    // value should have been no more than kMaxRep * 10.
+    // (kMaxRep * 10 > maxMantissa)
     XRPL_ASSERT_PARTS(m <= kMaxRep, "xrpl::doNormalize", "intermediate mantissa fits in int64");
     mantissa = m;
 
-    g.doRoundUp(negative, mantissa, exponent, minMantissa, maxMantissa, "Number::normalize 2");
+    g.doRoundUp(
+        negative,
+        mantissa,
+        exponent,
+        minMantissa,
+        maxMantissa,
+        cuspRoundingFixEnabled,
+        "Number::normalize 2");
     XRPL_ASSERT_PARTS(
         mantissa >= minMantissa && mantissa <= maxMantissa,
         "xrpl::doNormalize",
@@ -448,9 +608,10 @@ Number::normalize<uint128_t>(
     uint128_t& mantissa,
     int& exponent,
     internalrep const& minMantissa,
-    internalrep const& maxMantissa)
+    internalrep const& maxMantissa,
+    MantissaRange::CuspRoundingFix cuspRoundingFixEnabled)
 {
-    doNormalize(negative, mantissa, exponent, minMantissa, maxMantissa);
+    doNormalize(negative, mantissa, exponent, minMantissa, maxMantissa, cuspRoundingFixEnabled);
 }
 
 template <>
@@ -460,9 +621,10 @@ Number::normalize<unsigned long long>(
     unsigned long long& mantissa,
     int& exponent,
     internalrep const& minMantissa,
-    internalrep const& maxMantissa)
+    internalrep const& maxMantissa,
+    MantissaRange::CuspRoundingFix cuspRoundingFixEnabled)
 {
-    doNormalize(negative, mantissa, exponent, minMantissa, maxMantissa);
+    doNormalize(negative, mantissa, exponent, minMantissa, maxMantissa, cuspRoundingFixEnabled);
 }
 
 template <>
@@ -472,16 +634,16 @@ Number::normalize<unsigned long>(
     unsigned long& mantissa,
     int& exponent,
     internalrep const& minMantissa,
-    internalrep const& maxMantissa)
+    internalrep const& maxMantissa,
+    MantissaRange::CuspRoundingFix cuspRoundingFixEnabled)
 {
-    doNormalize(negative, mantissa, exponent, minMantissa, maxMantissa);
+    doNormalize(negative, mantissa, exponent, minMantissa, maxMantissa, cuspRoundingFixEnabled);
 }
 
 void
-Number::normalize()
+Number::normalize(MantissaRange const& range)
 {
-    auto const& range = kRange.get();
-    normalize(negative_, mantissa_, exponent_, range.min, range.max);
+    normalize(negative_, mantissa_, exponent_, range.min, range.max, range.cuspRoundingFixEnabled);
 }
 
 // Copy the number, but set a new exponent. Because the mantissa doesn't change,
@@ -542,9 +704,7 @@ Number::operator+=(Number const& y)
             g.setNegative();
         do
         {
-            g.push(xm % 10);
-            xm /= 10;
-            ++xe;
+            g.doDropDigit(xm, xe);
         } while (xe < ye);
     }
     else if (xe > ye)
@@ -553,26 +713,30 @@ Number::operator+=(Number const& y)
             g.setNegative();
         do
         {
-            g.push(ym % 10);
-            ym /= 10;
-            ++ye;
+            g.doDropDigit(ym, ye);
         } while (xe > ye);
     }
 
     auto const& range = kRange.get();
     auto const& minMantissa = range.min;
     auto const& maxMantissa = range.max;
+    auto const cuspRoundingFixEnabled = range.cuspRoundingFixEnabled;
 
     if (xn == yn)
     {
         xm += ym;
         if (xm > maxMantissa || xm > kMaxRep)
         {
-            g.push(xm % 10);
-            xm /= 10;
-            ++xe;
+            g.doDropDigit(xm, xe);
         }
-        g.doRoundUp(xn, xm, xe, minMantissa, maxMantissa, "Number::addition overflow");
+        g.doRoundUp(
+            xn,
+            xm,
+            xe,
+            minMantissa,
+            maxMantissa,
+            cuspRoundingFixEnabled,
+            "Number::addition overflow");
     }
     else
     {
@@ -598,38 +762,10 @@ Number::operator+=(Number const& y)
     negative_ = xn;
     mantissa_ = static_cast<internalrep>(xm);
     exponent_ = xe;
-    normalize();
+    normalize(range);
     return *this;
 }
 
-// Optimization equivalent to:
-// auto r = static_cast<unsigned>(u % 10);
-// u /= 10;
-// return r;
-// Derived from Hacker's Delight Second Edition Chapter 10
-// by Henry S. Warren, Jr.
-static inline unsigned
-divu10(uint128_t& u)
-{
-    // q = u * 0.75
-    auto q = (u >> 1) + (u >> 2);
-    // iterate towards q = u * 0.8
-    q += q >> 4;
-    q += q >> 8;
-    q += q >> 16;
-    q += q >> 32;
-    q += q >> 64;
-    // q /= 8 approximately == u / 10
-    q >>= 3;
-    // r = u - q * 10  approximately == u % 10
-    auto r = static_cast<unsigned>(u - ((q << 3) + (q << 1)));
-    // correction c is 1 if r >= 10 else 0
-    auto c = (r + 6) >> 4;
-    u = q + c;
-    r -= c * 10;
-    return r;
-}
-
 Number&
 Number::operator*=(Number const& y)
 {
@@ -667,15 +803,13 @@ Number::operator*=(Number const& y)
     auto const& range = kRange.get();
     auto const& minMantissa = range.min;
     auto const& maxMantissa = range.max;
+    auto const cuspRoundingFixEnabled = range.cuspRoundingFixEnabled;
 
     while (zm > maxMantissa || zm > kMaxRep)
     {
-        // The following is optimization for:
-        // g.push(static_cast<unsigned>(zm % 10));
-        // zm /= 10;
-        g.push(divu10(zm));
-        ++ze;
+        g.doDropDigit(zm, ze);
     }
+
     xm = static_cast<internalrep>(zm);
     xe = ze;
     g.doRoundUp(
@@ -684,12 +818,13 @@ Number::operator*=(Number const& y)
         xe,
         minMantissa,
         maxMantissa,
+        cuspRoundingFixEnabled,
         "Number::multiplication overflow : exponent is " + std::to_string(xe));
     negative_ = zn;
     mantissa_ = xm;
     exponent_ = xe;
 
-    normalize();
+    normalize(range);
     return *this;
 }
 
@@ -721,6 +856,7 @@ Number::operator/=(Number const& y)
     auto const& range = kRange.get();
     auto const& minMantissa = range.min;
     auto const& maxMantissa = range.max;
+    auto const cuspRoundingFixEnabled = range.cuspRoundingFixEnabled;
 
     // Shift by 10^17 gives greatest precision while not overflowing
     // uint128_t or the cast back to int64_t
@@ -728,8 +864,6 @@ Number::operator/=(Number const& y)
     // log(2^128,10) ~ 38.5
     // largeRange.log = 18, fits in 10^19
     // f can be up to 10^(38-19) = 10^19 safely
-    static_assert(kSmallRange.log == 15);
-    static_assert(kLargeRange.log == 18);
     bool const small = Number::getMantissaScale() == MantissaRange::MantissaScale::Small;
     uint128_t const f = small ? 100'000'000'000'000'000 : 10'000'000'000'000'000'000ULL;
     XRPL_ASSERT_PARTS(f >= minMantissa * 10, "Number::operator/=", "factor expected size");
@@ -779,7 +913,7 @@ Number::operator/=(Number const& y)
             ze -= 3;
         }
     }
-    normalize(zn, zm, ze, minMantissa, maxMantissa);
+    normalize(zn, zm, ze, minMantissa, maxMantissa, cuspRoundingFixEnabled);
     negative_ = zn;
     mantissa_ = static_cast<internalrep>(zm);
     exponent_ = ze;
@@ -801,10 +935,9 @@ operator rep() const
             g.setNegative();
             drops = -drops;
         }
-        for (; offset < 0; ++offset)
+        while (offset < 0)
         {
-            g.push(drops % 10);
-            drops /= 10;
+            g.doDropDigit(drops, offset);
         }
         for (; offset > 0; --offset)
         {
@@ -831,7 +964,7 @@ Number::truncate() const noexcept
     }
     // We are guaranteed that normalize() will never throw an exception
     // because exponent is either negative or zero at this point.
-    ret.normalize();
+    ret.normalize(kRange);
     return ret;
 }
 

src/libxrpl/ledger/DeferredRebuild.cpp

@@ -0,0 +1,329 @@
+#include <xrpl/ledger/DeferredRebuild.h>
+
+#include <xrpl/basics/Slice.h>
+#include <xrpl/basics/hardened_hash.h>
+#include <xrpl/protocol/HashPrefix.h>
+#include <xrpl/protocol/digest.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <future>
+#include <mutex>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+namespace xrpl {
+
+namespace {
+
+// Zero the trailing (64 - depth) nibbles of `key`, keeping the first
+// `depth` nibbles. Returns the resulting prefix uint256.
+//
+// SHAMap stores keys big-endian. The most significant nibble of the
+// key is the depth-1 branch from root. So at depth N we want to keep
+// the top N nibbles = N*4 bits and zero the rest.
+[[nodiscard]] uint256
+prefixAtDepth(uint256 const& key, int depth) noexcept
+{
+    if (depth >= 64)
+        return key;
+    if (depth <= 0)
+        return uint256{};
+
+    uint256 result = key;
+    auto const totalNibbles = 64;
+    auto const nibblesToZero = totalNibbles - depth;
+
+    // Zero `nibblesToZero` nibbles starting from the least-significant
+    // end. uint256 has 32 bytes (each holds two nibbles, high then low).
+    // Byte index 31 holds the two lowest nibbles; byte 0 holds the two
+    // highest.
+    int nibblesZeroed = 0;
+    for (int byteIdx = uint256::kBytes - 1;
+         byteIdx >= 0 && nibblesZeroed < nibblesToZero;
+         --byteIdx)
+    {
+        if (nibblesZeroed + 2 <= nibblesToZero)
+        {
+            // Zero both nibbles in this byte
+            result.data()[byteIdx] = 0;
+            nibblesZeroed += 2;
+        }
+        else
+        {
+            // Zero only the low nibble in this byte
+            result.data()[byteIdx] &= 0xF0;
+            nibblesZeroed += 1;
+        }
+    }
+    return result;
+}
+
+}  // namespace
+
+namespace {
+
+// Longest common prefix in NIBBLES between two uint256 keys.
+// Returns 0..64. 64 means the keys are identical.
+[[nodiscard]] int
+lcpNibbles(uint256 const& a, uint256 const& b) noexcept
+{
+    for (int byteIdx = 0; byteIdx < uint256::kBytes; ++byteIdx)
+    {
+        if (a.data()[byteIdx] != b.data()[byteIdx])
+        {
+            // They agree in 2*byteIdx whole nibbles. Check whether
+            // the high nibble of this byte also agrees.
+            std::uint8_t aHigh = a.data()[byteIdx] >> 4;
+            std::uint8_t bHigh = b.data()[byteIdx] >> 4;
+            if (aHigh == bHigh)
+                return 2 * byteIdx + 1;
+            return 2 * byteIdx;
+        }
+    }
+    return 64;
+}
+
+}  // namespace
+
+std::vector<AffectedNode>
+planDeferredRebuild(std::vector<uint256> const& modifiedKeys)
+{
+    if (modifiedKeys.empty())
+        return {};
+
+    // LCP-based dedup. For sorted keys, the inner-node ancestors are
+    // grouped by shared prefix; once a key has contributed its
+    // ancestors at depths 0..63, the NEXT sorted key only adds NEW
+    // ancestors at depths > LCP(prev, current). Everything at depth
+    // ≤ LCP is already in the plan from `prev`.
+    //
+    // This replaces O(K × 64) prefix computations with O(K log K)
+    // sort + ~O(K) for sequential-key workloads (where LCP ≈ 63).
+    std::vector<uint256> sorted = modifiedKeys;
+    std::sort(sorted.begin(), sorted.end());
+
+    std::vector<AffectedNode> plan;
+    // Upper bound for arbitrary inputs is K * 64, but realistic
+    // workloads (sequential / clustered) produce ~K entries.
+    plan.reserve(sorted.size() * 2);
+
+    // First key contributes ancestors at every depth.
+    for (int d = 0; d <= 63; ++d)
+        plan.push_back({d, prefixAtDepth(sorted[0], d)});
+
+    // Subsequent keys contribute only ancestors at depths > LCP with
+    // their predecessor.
+    for (std::size_t i = 1; i < sorted.size(); ++i)
+    {
+        // Identical adjacent keys: nothing new to contribute.
+        if (sorted[i] == sorted[i - 1])
+            continue;
+        int const lcp = lcpNibbles(sorted[i - 1], sorted[i]);
+        for (int d = lcp + 1; d <= 63; ++d)
+            plan.push_back({d, prefixAtDepth(sorted[i], d)});
+    }
+
+    // Sort depth-descending so a bottom-up rebuild can iterate in
+    // order. Within a depth, ascending prefix for determinism.
+    std::sort(
+        plan.begin(),
+        plan.end(),
+        [](AffectedNode const& a, AffectedNode const& b) {
+            if (a.depth != b.depth)
+                return a.depth > b.depth;
+            return a.prefix < b.prefix;
+        });
+
+    return plan;
+}
+
+namespace {
+
+// Given a parent inner node at (parentDepth, parentPrefix), compute the
+// child prefix at the given branch (0..15). The child is at depth
+// (parentDepth + 1); its prefix sets the nibble at position parentDepth
+// to the branch value.
+[[nodiscard]] uint256
+childPrefixOf(uint256 const& parentPrefix, int parentDepth, std::uint8_t branch)
+{
+    uint256 result = parentPrefix;
+    int const byteIdx = parentDepth / 2;
+    bool const isHighNibble = (parentDepth % 2) == 0;
+    if (isHighNibble)
+        result.data()[byteIdx] =
+            (result.data()[byteIdx] & 0x0F) |
+            static_cast<std::uint8_t>((branch & 0x0F) << 4);
+    else
+        result.data()[byteIdx] =
+            (result.data()[byteIdx] & 0xF0) |
+            static_cast<std::uint8_t>(branch & 0x0F);
+    return result;
+}
+
+}  // namespace
+
+namespace detail {
+
+RebuildResult
+executeRebuildPlanImpl(
+    std::vector<AffectedNode> const& plan,
+    std::function<uint256(int, uint256 const&)> getOriginalChildHash)
+{
+    RebuildResult result;
+    result.reserve(plan.size());
+
+    // Plan is depth-descending; deepest nodes processed first. Their
+    // hashes are visible to shallower nodes in this same walk.
+    for (auto const& node : plan)
+    {
+        std::array<uint256, 16> children;
+        for (std::uint8_t b = 0; b < 16; ++b)
+        {
+            AffectedNode const childPos{
+                node.depth + 1, childPrefixOf(node.prefix, node.depth, b)};
+            auto it = result.find(childPos);
+            if (it != result.end())
+                children[b] = it->second;
+            else
+                children[b] = getOriginalChildHash(childPos.depth, childPos.prefix);
+        }
+        result.emplace(node, computeInnerNodeHash(children));
+    }
+
+    return result;
+}
+
+}  // namespace detail
+
+std::array<std::vector<uint256>, 16>
+partitionByFirstNibble(std::vector<uint256> const& modifiedKeys)
+{
+    std::array<std::vector<uint256>, 16> buckets;
+    for (auto const& key : modifiedKeys)
+    {
+        // First nibble = high nibble of byte 0
+        std::uint8_t const firstNibble = (key.data()[0] >> 4) & 0x0F;
+        buckets[firstNibble].push_back(key);
+    }
+    return buckets;
+}
+
+namespace detail {
+
+uint256
+deferredRebuildRootParallelImpl(
+    std::vector<uint256> const& modifiedKeys,
+    std::function<uint256(int, uint256 const&)> getOriginalChildHash)
+{
+    if (modifiedKeys.empty())
+        return getOriginalChildHash(0, uint256{});
+
+    auto const buckets = partitionByFirstNibble(modifiedKeys);
+
+    // For each subtree, compute the new depth-1 hash (if any keys
+    // changed in that subtree) in parallel. Empty subtrees fall back
+    // to the parent's depth-1 hash, which is read from the callback.
+    //
+    // Each future captures the relevant bucket and runs an independent
+    // plan-and-execute over just that subtree's keys. The result is
+    // the new hash of the depth-1 inner node rooting that subtree
+    // (which corresponds to the root's branch-b child).
+    std::array<std::future<uint256>, 16> futures;
+    for (std::uint8_t b = 0; b < 16; ++b)
+    {
+        if (buckets[b].empty())
+            continue;
+
+        futures[b] = std::async(
+            std::launch::async,
+            [bucket = buckets[b], &getOriginalChildHash, b]() -> uint256 {
+                // Plan + execute for this subtree's keys. The depth-1
+                // node is the rooting node; we want its new hash.
+                auto const plan = planDeferredRebuild(bucket);
+                auto const result =
+                    executeRebuildPlan(plan, getOriginalChildHash);
+
+                // The depth-1 prefix for this subtree has its first
+                // nibble set to b, rest zero.
+                uint256 prefix{};
+                prefix.data()[0] =
+                    static_cast<std::uint8_t>(b << 4);
+
+                AffectedNode const subtreeRoot{1, prefix};
+                auto const it = result.find(subtreeRoot);
+                if (it == result.end())
+                    return uint256{};
+                return it->second;
+            });
+    }
+
+    // Gather: 16 child hashes for the root.
+    std::array<uint256, 16> rootChildren;
+    for (std::uint8_t b = 0; b < 16; ++b)
+    {
+        if (buckets[b].empty())
+        {
+            // Untouched subtree — read original depth-1 hash from
+            // parent SHAMap via callback.
+            uint256 prefix{};
+            prefix.data()[0] = static_cast<std::uint8_t>(b << 4);
+            rootChildren[b] = getOriginalChildHash(1, prefix);
+        }
+        else
+        {
+            rootChildren[b] = futures[b].get();
+        }
+    }
+
+    return computeInnerNodeHash(rootChildren);
+}
+
+}  // namespace detail
+
+uint256
+computeInnerNodeHash(std::array<uint256, 16> const& childHashes)
+{
+    // SHAMapInnerNode::updateHash short-circuits to a zero hash when
+    // every branch is empty (isBranch_ == 0). Match that convention —
+    // a "node with no children" hashes to zero, not to SHA-512 of a
+    // zero-filled buffer.
+    bool anyNonZero = false;
+    for (auto const& h : childHashes)
+    {
+        if (h.isNonZero())
+        {
+            anyNonZero = true;
+            break;
+        }
+    }
+    if (!anyNonZero)
+        return uint256{};
+
+    // Layout: 4-byte big-endian HashPrefix::InnerNode || 16 × 32-byte
+    // child hashes. Total: 516 bytes. Matches SHAMapInnerNode::updateHash
+    // byte-for-byte; differential-tested against it.
+    constexpr std::size_t kBufSize = 4 + 16 * uint256::kBytes;
+    alignas(64) std::array<std::uint8_t, kBufSize> buf{};
+
+    auto const prefix = static_cast<std::uint32_t>(HashPrefix::InnerNode);
+    buf[0] = static_cast<std::uint8_t>(prefix >> 24);
+    buf[1] = static_cast<std::uint8_t>(prefix >> 16);
+    buf[2] = static_cast<std::uint8_t>(prefix >> 8);
+    buf[3] = static_cast<std::uint8_t>(prefix);
+
+    std::uint8_t* out = buf.data() + 4;
+    for (auto const& h : childHashes)
+    {
+        std::memcpy(out, h.data(), uint256::kBytes);
+        out += uint256::kBytes;
+    }
+
+    return sha512Half(Slice{buf.data(), buf.size()});
+}
+
+}  // namespace xrpl

src/libxrpl/ledger/FlatStateMap.cpp

@@ -0,0 +1,130 @@
+#include <xrpl/ledger/FlatStateMap.h>
+
+#include <xrpl/ledger/Ledger.h>
+#include <xrpl/ledger/ReadView.h>
+
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
+#include <utility>
+
+namespace xrpl {
+
+FlatStateMap::value_type
+FlatStateMap::read(key_type const& key) const
+{
+    std::shared_lock<std::shared_mutex> lock(mutex_);
+    auto const it = map_.find(key);
+    if (it == map_.end())
+        return nullptr;
+    return it->second;
+}
+
+bool
+FlatStateMap::exists(key_type const& key) const
+{
+    std::shared_lock<std::shared_mutex> lock(mutex_);
+    return map_.find(key) != map_.end();
+}
+
+void
+FlatStateMap::insert(key_type const& key, value_type sle)
+{
+    std::unique_lock<std::shared_mutex> lock(mutex_);
+    map_.insert_or_assign(key, std::move(sle));
+}
+
+void
+FlatStateMap::erase(key_type const& key)
+{
+    std::unique_lock<std::shared_mutex> lock(mutex_);
+    map_.erase(key);
+}
+
+std::size_t
+FlatStateMap::size() const
+{
+    std::shared_lock<std::shared_mutex> lock(mutex_);
+    return map_.size();
+}
+
+bool
+FlatStateMap::empty() const
+{
+    std::shared_lock<std::shared_mutex> lock(mutex_);
+    return map_.empty();
+}
+
+void
+FlatStateMap::clear()
+{
+    std::unique_lock<std::shared_mutex> lock(mutex_);
+    map_.clear();
+}
+
+std::unique_ptr<FlatStateMap>
+FlatStateMap::snapshot() const
+{
+    auto out = std::make_unique<FlatStateMap>();
+    std::shared_lock<std::shared_mutex> lock(mutex_);
+    // Reserve to avoid rehash during the bulk copy.
+    out->map_.reserve(map_.size());
+    for (auto const& entry : map_)
+        out->map_.insert(entry);
+    return out;
+}
+
+void
+populateFromReadView(FlatStateMap& target, ReadView const& source)
+{
+    populateFromRange(target, source.sles);
+}
+
+void
+attachFlatStateMapTo(Ledger& ledger)
+{
+    auto map = std::make_shared<FlatStateMap>();
+    populateFromReadView(*map, ledger);
+    ledger.setFlatStateMap(std::move(map));
+}
+
+void
+mirrorRawInsert(FlatStateMap& map, std::shared_ptr<STLedgerEntry const> sle)
+{
+    auto const key = sle->key();
+    map.insert(key, std::move(sle));
+}
+
+void
+mirrorRawReplace(FlatStateMap& map, std::shared_ptr<STLedgerEntry const> sle)
+{
+    auto const key = sle->key();
+    map.insert(key, std::move(sle));  // insert == insert_or_assign here
+}
+
+void
+mirrorRawErase(
+    FlatStateMap& map,
+    std::shared_ptr<STLedgerEntry const> const& sle)
+{
+    map.erase(sle->key());
+}
+
+void
+mirrorRawErase(FlatStateMap& map, uint256 const& key)
+{
+    map.erase(key);
+}
+
+std::shared_ptr<STLedgerEntry const>
+readFromFlatStateMap(FlatStateMap const& map, Keylet const& k)
+{
+    auto sle = map.read(k.key);
+    if (!sle)
+        return nullptr;
+    if (!k.check(*sle))
+        return nullptr;
+    return sle;
+}
+
+}  // namespace xrpl

src/libxrpl/ledger/Ledger.cpp

@@ -9,6 +9,7 @@
 #include <xrpl/beast/utility/Journal.h>
 #include <xrpl/beast/utility/Zero.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/ledger/FlatStateMap.h>
 #include <xrpl/ledger/LedgerTiming.h>
 #include <xrpl/ledger/ReadView.h>
 #include <xrpl/nodestore/NodeObject.h>
@@ -276,6 +277,19 @@ Ledger::Ledger(Ledger const& prevLedger, NetClock::time_point closeTime)
     {
         header_.closeTime = prevLedger.header_.closeTime + header_.closeTimeResolution;
     }
+
+    // Plan 6 lifecycle: if the parent carries a flat-state mirror, the child
+    // inherits an independent deep-copy snapshot of it. This mirrors the COW
+    // snapshot of `stateMap_` above: the child starts from the parent's final
+    // state and then diverges as the round's transactions mirror into it,
+    // while the parent's map is left untouched. When no map is attached (the
+    // default), this is a no-op and the ledger behaves exactly as before.
+    //
+    // The snapshot is O(N) in entry count today; a persistent/HAMT structure
+    // (see FlatStateMap.h) is the follow-on that makes per-ledger propagation
+    // cheap enough to enable in production.
+    if (prevLedger.flatStateMap_)
+        flatStateMap_ = prevLedger.flatStateMap_->snapshot();
 }
 
 Ledger::Ledger(LedgerHeader const& info, Rules rules, Family& family)
@@ -411,6 +425,14 @@ Ledger::read(Keylet const& k) const
         return nullptr;
         // LCOV_EXCL_STOP
     }
+
+    // Plan 6 P6.4: when a FlatStateMap is attached, it is the read
+    // source of truth. No SHAMap fallback — drift between the two
+    // is caught at close by the differential invariant check (P6.5),
+    // not by silently re-reading from SHAMap.
+    if (flatStateMap_)
+        return readFromFlatStateMap(*flatStateMap_, k);
+
     auto const& item = stateMap_.peekItem(k.key);
     if (!item)
         return nullptr;
@@ -490,6 +512,8 @@ Ledger::rawErase(std::shared_ptr<SLE> const& sle)
 {
     if (!stateMap_.delItem(sle->key()))
         logicError("Ledger::rawErase: key not found");
+    if (flatStateMap_)
+        mirrorRawErase(*flatStateMap_, sle);
 }
 
 void
@@ -497,6 +521,8 @@ Ledger::rawErase(uint256 const& key)
 {
     if (!stateMap_.delItem(key))
         logicError("Ledger::rawErase: key not found");
+    if (flatStateMap_)
+        mirrorRawErase(*flatStateMap_, key);
 }
 
 void
@@ -509,6 +535,8 @@ Ledger::rawInsert(std::shared_ptr<SLE> const& sle)
     {
         logicError("Ledger::rawInsert: key already exists");
     }
+    if (flatStateMap_)
+        mirrorRawInsert(*flatStateMap_, sle);
 }
 
 void
@@ -521,6 +549,28 @@ Ledger::rawReplace(std::shared_ptr<SLE> const& sle)
     {
         logicError("Ledger::rawReplace: key not found");
     }
+    if (flatStateMap_)
+        mirrorRawReplace(*flatStateMap_, sle);
+}
+
+void
+Ledger::setFlatStateMap(std::shared_ptr<FlatStateMap> map)
+{
+    flatStateMap_ = std::move(map);
+}
+
+std::shared_ptr<FlatStateMap>
+Ledger::flatStateMap() const
+{
+    return flatStateMap_;
+}
+
+bool
+Ledger::validateFlatStateMapMatchesShaMap() const
+{
+    if (!flatStateMap_)
+        return true;  // nothing to validate against
+    return flatStateMapMatchesShaMap(*flatStateMap_, stateMap_);
 }
 
 void

src/libxrpl/ledger/helpers/LendingHelpers.cpp

@@ -769,9 +769,6 @@ doOverpayment(
         "xrpl::detail::doOverpayment",
         "principal change agrees");
 
-    // I'm not 100% sure the following asserts are correct. If in doubt, and
-    // everything else works, remove any that cause trouble.
-
     JLOG(j.debug()) << "valueChange: " << loanPaymentParts.valueChange
                     << ", totalValue before: " << *totalValueOutstandingProxy
                     << ", totalValue after: " << newRoundedLoanState.valueOutstanding
@@ -783,11 +780,28 @@ doOverpayment(
                     << overpaymentComponents.trackedPrincipalDelta -
             (totalValueOutstandingProxy - newRoundedLoanState.valueOutstanding);
 
+    // The valueChange returned by tryOverpayment satisfies
+    //   valueChange = (newInterestDue - oldInterestDue) + untrackedInterest.
+    // Using the loan-state identity v = p + i + m and the adjacent
+    // `principal change agrees` assertion (dp = oldP - newP), this
+    // rearranges into three independently-computable terms:
+    //
+    //   1. TVO change beyond what principal repayment alone explains:
+    //        newTVO - (oldTVO - dp)
+    //   2. Management fee released by re-amortization (positive when
+    //      mfee decreased; zero when managementFeeRate == 0):
+    //        oldMfee - newMfee
+    //   3. The overpayment's penalty interest part (= untrackedInterest
+    //      for the overpayment path; see computeOverpaymentComponents):
+    //        trackedInterestPart()
+    [[maybe_unused]] Number const tvoChange = newRoundedLoanState.valueOutstanding -
+        (totalValueOutstandingProxy - overpaymentComponents.trackedPrincipalDelta);
+    [[maybe_unused]] Number const managementFeeReleased =
+        managementFeeOutstandingProxy - newRoundedLoanState.managementFeeDue;
+    [[maybe_unused]] Number const interestPart = overpaymentComponents.trackedInterestPart();
+
     XRPL_ASSERT_PARTS(
-        loanPaymentParts.valueChange ==
-            newRoundedLoanState.valueOutstanding -
-                (totalValueOutstandingProxy - overpaymentComponents.trackedPrincipalDelta) +
-                overpaymentComponents.trackedInterestPart(),
+        loanPaymentParts.valueChange == tvoChange + managementFeeReleased + interestPart,
         "xrpl::detail::doOverpayment",
         "interest paid agrees");
 
@@ -2027,51 +2041,62 @@ loanMakePayment(
         // It shouldn't be possible for the overpayment to be greater than
         // totalValueOutstanding, because that would have been processed as
         // another normal payment. But cap it just in case.
-        Number const overpayment = std::min(roundedAmount - totalPaid, *totalValueOutstandingProxy);
+        Number const overpaymentRaw =
+            std::min(roundedAmount - totalPaid, *totalValueOutstandingProxy);
 
-        detail::ExtendedPaymentComponents const overpaymentComponents =
-            detail::computeOverpaymentComponents(
-                asset,
-                loanScale,
-                overpayment,
-                overpaymentInterestRate,
-                overpaymentFeeRate,
-                managementFeeRate);
+        bool const fixEnabled = view.rules().enabled(fixCleanup3_2_0);
+        Number const overpayment = fixEnabled
+            ? roundToAsset(asset, overpaymentRaw, loanScale, Number::RoundingMode::Downward)
+            : overpaymentRaw;
 
-        // Don't process an overpayment if the whole amount (or more!)
-        // gets eaten by fees and interest.
-        if (overpaymentComponents.trackedPrincipalDelta > 0)
+        // Post-amendment, the rounded overpayment can be zero; pre-amendment
+        // it's always positive given the surrounding guards.
+        if (!fixEnabled || overpayment > 0)
         {
-            XRPL_ASSERT_PARTS(
-                overpaymentComponents.untrackedInterest >= beast::kZero,
-                "xrpl::loanMakePayment",
-                "overpayment penalty did not reduce value of loan");
-            // Can't just use `periodicPayment` here, because it might
-            // change
-            auto periodicPaymentProxy = loan->at(sfPeriodicPayment);
-            if (auto const overResult = detail::doOverpayment(
-                    view.rules(),
+            detail::ExtendedPaymentComponents const overpaymentComponents =
+                detail::computeOverpaymentComponents(
                     asset,
                     loanScale,
-                    overpaymentComponents,
-                    totalValueOutstandingProxy,
-                    principalOutstandingProxy,
-                    managementFeeOutstandingProxy,
-                    periodicPaymentProxy,
-                    periodicRate,
-                    paymentRemainingProxy,
-                    managementFeeRate,
-                    j))
+                    overpayment,
+                    overpaymentInterestRate,
+                    overpaymentFeeRate,
+                    managementFeeRate);
+
+            // Don't process an overpayment if the whole amount (or more!)
+            // gets eaten by fees and interest.
+            if (overpaymentComponents.trackedPrincipalDelta > 0)
             {
-                totalParts += *overResult;
-            }
-            else if (overResult.error())
-            {
-                // error() will be the TER returned if a payment is not
-                // made. It will only evaluate to true if it's unsuccessful.
-                // Otherwise, tesSUCCESS means nothing was done, so
-                // continue.
-                return Unexpected(overResult.error());
+                XRPL_ASSERT_PARTS(
+                    overpaymentComponents.untrackedInterest >= beast::kZero,
+                    "xrpl::loanMakePayment",
+                    "overpayment penalty did not reduce value of loan");
+                // Can't just use `periodicPayment` here, because it might
+                // change
+                auto periodicPaymentProxy = loan->at(sfPeriodicPayment);
+                if (auto const overResult = detail::doOverpayment(
+                        view.rules(),
+                        asset,
+                        loanScale,
+                        overpaymentComponents,
+                        totalValueOutstandingProxy,
+                        principalOutstandingProxy,
+                        managementFeeOutstandingProxy,
+                        periodicPaymentProxy,
+                        periodicRate,
+                        paymentRemainingProxy,
+                        managementFeeRate,
+                        j))
+                {
+                    totalParts += *overResult;
+                }
+                else if (overResult.error())
+                {
+                    // error() will be the TER returned if a payment is not
+                    // made. It will only evaluate to true if it's unsuccessful.
+                    // Otherwise, tesSUCCESS means nothing was done, so
+                    // continue.
+                    return Unexpected(overResult.error());
+                }
             }
         }
     }

src/libxrpl/ledger/helpers/MPTokenHelpers.cpp

@@ -25,7 +25,6 @@
 #include <xrpl/protocol/STLedgerEntry.h>
 #include <xrpl/protocol/TER.h>
 #include <xrpl/protocol/TxFlags.h>
-#include <xrpl/protocol/TxFormats.h>
 #include <xrpl/protocol/UintTypes.h>
 #include <xrpl/protocol/XRPAmount.h>
 
@@ -383,10 +382,11 @@ requireAuth(
         // belong to someone who is explicitly authorized e.g. a vault owner.
     }
 
-    if (featureSAVEnabled)
+    bool const featureMPTV2Enabled = view.rules().enabled(featureMPTokensV2);
+    if (featureSAVEnabled || featureMPTV2Enabled)
     {
-        // Implicitly authorize Vault and LoanBroker pseudo-accounts
-        if (isPseudoAccount(view, account, {&sfVaultID, &sfLoanBrokerID}))
+        // Implicitly authorize Vault, LoanBroker, and AMM pseudo-accounts
+        if (isPseudoAccount(view, account, {&sfVaultID, &sfLoanBrokerID, &sfAMMID}))
             return tesSUCCESS;
     }
 
@@ -618,6 +618,22 @@ canTrade(ReadView const& view, Asset const& asset, std::uint8_t depth)
         });
 }
 
+TER
+canMPTTradeAndTransfer(
+    ReadView const& view,
+    Asset const& asset,
+    AccountID const& from,
+    AccountID const& to)
+{
+    if (!asset.holds<MPTIssue>())
+        return tesSUCCESS;
+
+    if (auto const ter = canTrade(view, asset); !isTesSuccess(ter))
+        return ter;
+
+    return canTransfer(view, asset, from, to);
+}
+
 TER
 lockEscrowMPT(ApplyView& view, AccountID const& sender, STAmount const& amount, beast::Journal j)
 {
@@ -985,96 +1001,4 @@ issuerSelfDebitHookMPT(ApplyView& view, MPTIssue const& issue, std::uint64_t amo
     view.issuerSelfDebitHookMPT(issue, amount, available);
 }
 
-static TER
-checkMPTAllowed(
-    ReadView const& view,
-    TxType txType,
-    Asset const& asset,
-    AccountID const& accountID,
-    std::uint8_t depth = 0)
-{
-    if (!asset.holds<MPTIssue>())
-        return tesSUCCESS;
-
-    auto const& issuanceID = asset.get<MPTIssue>().getMptID();
-    auto const validTx = txType == ttAMM_CREATE || txType == ttAMM_DEPOSIT ||
-        txType == ttAMM_WITHDRAW || txType == ttOFFER_CREATE || txType == ttCHECK_CREATE ||
-        txType == ttCHECK_CASH || txType == ttPAYMENT;
-    XRPL_ASSERT(validTx, "xrpl::checkMPTAllowed : all MPT tx or DEX");
-    if (!validTx)
-        return tefINTERNAL;  // LCOV_EXCL_LINE
-
-    auto const& issuer = asset.getIssuer();
-    if (!view.exists(keylet::account(issuer)))
-        return tecNO_ISSUER;  // LCOV_EXCL_LINE
-
-    auto const issuanceKey = keylet::mptIssuance(issuanceID);
-    auto const issuanceSle = view.read(issuanceKey);
-    if (!issuanceSle)
-        return tecOBJECT_NOT_FOUND;  // LCOV_EXCL_LINE
-
-    if (issuanceSle->isFlag(lsfMPTLocked))
-        return tecLOCKED;  // LCOV_EXCL_LINE
-    // Offer crossing and Payment
-    if (!issuanceSle->isFlag(lsfMPTCanTrade))
-        return tecNO_PERMISSION;
-
-    if (accountID != issuer)
-    {
-        if (!issuanceSle->isFlag(lsfMPTCanTransfer))
-            return tecNO_PERMISSION;
-
-        auto const mptSle = view.read(keylet::mptoken(issuanceKey.key, accountID));
-        // Allow to succeed since some tx create MPToken if it doesn't exist.
-        // Tx's have their own check for missing MPToken.
-        if (!mptSle)
-            return tesSUCCESS;
-
-        if (mptSle->isFlag(lsfMPTLocked))
-            return tecLOCKED;
-
-        // Post-fixCleanup3_2_0: vault shares inherit the underlying
-        // asset's checks here too. Without this, a share could be
-        // placed on the AMM, in an Offer, or in a Check even after
-        // the issuer has restricted the underlying. Mirrors the
-        // canTransfer / canTrade inheritance for path-find-adjacent
-        // operations that don't go through canTransfer directly.
-        if (view.rules().enabled(fixCleanup3_2_0) &&
-            issuanceSle->isFieldPresent(sfReferenceHolding))
-        {
-            // Defensive depth bound on the inheritance recursion.
-            // Reachable only post-fixCleanup3_2_0 and unreachable in
-            // practice (vault-of-vault-shares forbidden at VaultCreate).
-            if (depth >= kMaxAssetCheckDepth)
-            {
-                // LCOV_EXCL_START
-                UNREACHABLE("xrpl::MPTokenHelpers::checkMPTAllowed : reached asset check depth");
-                return tecINTERNAL;
-                // LCOV_EXCL_STOP
-            }
-            auto const sleHolding =
-                view.read(keylet::unchecked(issuanceSle->getFieldH256(sfReferenceHolding)));
-            if (!sleHolding)
-                return tefINTERNAL;  // LCOV_EXCL_LINE
-
-            return checkMPTAllowed(
-                view, txType, assetOfHolding(*issuanceSle, *sleHolding), accountID, depth + 1);
-        }
-    }
-
-    return tesSUCCESS;
-}
-
-TER
-checkMPTTxAllowed(
-    ReadView const& view,
-    TxType txType,
-    Asset const& asset,
-    AccountID const& accountID)
-{
-    // use isDEXAllowed for payment/offer crossing
-    XRPL_ASSERT(txType != ttPAYMENT, "xrpl::checkMPTTxAllowed : not payment");
-    return checkMPTAllowed(view, txType, asset, accountID);
-}
-
 }  // namespace xrpl

src/libxrpl/ledger/helpers/TokenHelpers.cpp

@@ -28,6 +28,7 @@
 
 #include <cstdint>
 #include <initializer_list>
+#include <limits>
 #include <string>
 #include <variant>
 
@@ -55,6 +56,14 @@ isGlobalFrozen(ReadView const& view, Asset const& asset)
         [&](MPTIssue const& issue) { return isGlobalFrozen(view, issue); });
 }
 
+TER
+checkGlobalFrozen(ReadView const& view, Asset const& asset)
+{
+    if (isGlobalFrozen(view, asset))
+        return asset.holds<MPTIssue>() ? tecLOCKED : tecFROZEN;
+    return tesSUCCESS;
+}
+
 bool
 isIndividualFrozen(ReadView const& view, AccountID const& account, Asset const& asset)
 {
@@ -62,6 +71,14 @@ isIndividualFrozen(ReadView const& view, AccountID const& account, Asset const&
         [&](auto const& issue) { return isIndividualFrozen(view, account, issue); }, asset.value());
 }
 
+TER
+checkIndividualFrozen(ReadView const& view, AccountID const& account, Asset const& asset)
+{
+    if (isIndividualFrozen(view, account, asset))
+        return asset.holds<MPTIssue>() ? tecLOCKED : tecFROZEN;
+    return tesSUCCESS;
+}
+
 bool
 isFrozen(ReadView const& view, AccountID const& account, Asset const& asset, std::uint8_t depth)
 {
@@ -1105,6 +1122,13 @@ directSendNoFeeMPT(
         auto const mptokenID = keylet::mptoken(mptID.key, uReceiverID);
         if (auto sle = view.peek(mptokenID))
         {
+            if (view.rules().enabled(featureMPTokensV2))
+            {
+                if ((*sle)[sfMPTAmount] > (std::numeric_limits<std::uint64_t>::max() - amt))
+                {
+                    return tecINTERNAL;  // LCOV_EXCL_LINE
+                }
+            }
             view.creditHookMPT(uSenderID, uReceiverID, saAmount, (*sle)[sfMPTAmount], available);
             (*sle)[sfMPTAmount] += amt;
             view.update(sle);

src/libxrpl/ledger/helpers/VaultHelpers.cpp

@@ -2,11 +2,16 @@
 
 #include <xrpl/basics/Number.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/ledger/ReadView.h>
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Indexes.h>
+#include <xrpl/protocol/LedgerFormats.h>
 #include <xrpl/protocol/SField.h>
 #include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
 #include <xrpl/protocol/STNumber.h>  // IWYU pragma: keep
 
+#include <cstdint>
 #include <memory>
 #include <optional>
 
@@ -70,7 +75,8 @@ assetsToSharesWithdraw(
     std::shared_ptr<SLE const> const& vault,
     std::shared_ptr<SLE const> const& issuance,
     STAmount const& assets,
-    TruncateShares truncate)
+    TruncateShares truncate,
+    WaiveUnrealizedLoss waive)
 {
     XRPL_ASSERT(!assets.negative(), "xrpl::assetsToSharesWithdraw : non-negative assets");
     XRPL_ASSERT(
@@ -80,7 +86,8 @@ assetsToSharesWithdraw(
         return std::nullopt;  // LCOV_EXCL_LINE
 
     Number assetTotal = vault->at(sfAssetsTotal);
-    assetTotal -= vault->at(sfLossUnrealized);
+    if (waive == WaiveUnrealizedLoss::No)
+        assetTotal -= vault->at(sfLossUnrealized);
     STAmount shares{vault->at(sfShareMPTID)};
     if (assetTotal == 0)
         return shares;
@@ -96,7 +103,8 @@ assetsToSharesWithdraw(
 sharesToAssetsWithdraw(
     std::shared_ptr<SLE const> const& vault,
     std::shared_ptr<SLE const> const& issuance,
-    STAmount const& shares)
+    STAmount const& shares,
+    WaiveUnrealizedLoss waive)
 {
     XRPL_ASSERT(!shares.negative(), "xrpl::sharesToAssetsWithdraw : non-negative shares");
     XRPL_ASSERT(
@@ -106,7 +114,8 @@ sharesToAssetsWithdraw(
         return std::nullopt;  // LCOV_EXCL_LINE
 
     Number assetTotal = vault->at(sfAssetsTotal);
-    assetTotal -= vault->at(sfLossUnrealized);
+    if (waive == WaiveUnrealizedLoss::No)
+        assetTotal -= vault->at(sfLossUnrealized);
     STAmount assets{vault->at(sfAsset)};
     if (assetTotal == 0)
         return assets;
@@ -115,4 +124,24 @@ sharesToAssetsWithdraw(
     return assets;
 }
 
+[[nodiscard]] bool
+isSoleShareholder(ReadView const& view, AccountID const& account, SLE::const_ref issuance)
+{
+    XRPL_ASSERT(
+        issuance && issuance->getType() == ltMPTOKEN_ISSUANCE,
+        "xrpl::isSoleShareholder : valid issuance SLE");
+
+    std::uint64_t const outstanding = issuance->at(sfOutstandingAmount);
+    if (outstanding == 0)
+        return false;
+
+    auto const shareMPTID =
+        makeMptID(issuance->getFieldU32(sfSequence), issuance->getAccountID(sfIssuer));
+    auto const sleToken = view.read(keylet::mptoken(shareMPTID, account));
+    if (!sleToken)
+        return false;  // LCOV_EXCL_LINE
+
+    return sleToken->getFieldU64(sfMPTAmount) == outstanding;
+}
+
 }  // namespace xrpl

src/libxrpl/nodestore/DatabaseNodeImp.cpp

@@ -4,21 +4,16 @@
 #include <xrpl/basics/Log.h>
 #include <xrpl/basics/base_uint.h>
 #include <xrpl/basics/contract.h>
-#include <xrpl/basics/strHex.h>
-#include <xrpl/beast/utility/instrumentation.h>
 #include <xrpl/nodestore/Database.h>
 #include <xrpl/nodestore/NodeObject.h>
 #include <xrpl/nodestore/Scheduler.h>
 #include <xrpl/nodestore/Types.h>
 
-#include <chrono>
-#include <cstddef>
 #include <cstdint>
 #include <exception>
 #include <functional>
 #include <memory>
 #include <utility>
-#include <vector>
 
 namespace xrpl::NodeStore {
 
@@ -81,33 +76,4 @@ DatabaseNodeImp::fetchNodeObject(
     return nodeObject;
 }
 
-std::vector<std::shared_ptr<NodeObject>>
-DatabaseNodeImp::fetchBatch(std::vector<uint256> const& hashes)
-{
-    using namespace std::chrono;
-    auto const before = steady_clock::now();
-
-    // Get the node objects that match the hashes from the backend. To protect
-    // against the backends returning fewer or more results than expected, the
-    // container is resized to the number of hashes.
-    auto results = backend_->fetchBatch(hashes).first;
-    XRPL_ASSERT(
-        results.size() == hashes.size() || results.empty(),
-        "number of output objects either matches number of input hashes or is empty");
-    results.resize(hashes.size());
-    for (size_t i = 0; i < results.size(); ++i)
-    {
-        if (!results[i])
-        {
-            JLOG(j_.error()) << "fetchBatch - "
-                             << "record not found in db. hash = " << strHex(hashes[i]);
-        }
-    }
-
-    auto fetchDurationUs =
-        std::chrono::duration_cast<std::chrono::microseconds>(steady_clock::now() - before).count();
-    updateFetchMetrics(hashes.size(), 0, fetchDurationUs);
-    return results;
-}
-
 }  // namespace xrpl::NodeStore

src/libxrpl/nodestore/backend/MemoryFactory.cpp

@@ -22,7 +22,6 @@
 #include <string>
 #include <tuple>
 #include <utility>
-#include <vector>
 
 namespace xrpl::NodeStore {
 
@@ -146,28 +145,6 @@ public:
         return Status::Ok;
     }
 
-    std::pair<std::vector<std::shared_ptr<NodeObject>>, Status>
-    fetchBatch(std::vector<uint256> const& hashes) override
-    {
-        std::vector<std::shared_ptr<NodeObject>> results;
-        results.reserve(hashes.size());
-        for (auto const& h : hashes)
-        {
-            std::shared_ptr<NodeObject> nObj;
-            Status const status = fetch(h, &nObj);
-            if (status != Status::Ok)
-            {
-                results.push_back({});
-            }
-            else
-            {
-                results.push_back(nObj);
-            }
-        }
-
-        return {results, Status::Ok};
-    }
-
     void
     store(std::shared_ptr<NodeObject> const& object) override
     {

src/libxrpl/nodestore/backend/NuDBFactory.cpp

@@ -42,7 +42,6 @@
 #include <stdexcept>
 #include <string>
 #include <utility>
-#include <vector>
 
 namespace xrpl::NodeStore {
 
@@ -232,28 +231,6 @@ public:
         return status;
     }
 
-    std::pair<std::vector<std::shared_ptr<NodeObject>>, Status>
-    fetchBatch(std::vector<uint256> const& hashes) override
-    {
-        std::vector<std::shared_ptr<NodeObject>> results;
-        results.reserve(hashes.size());
-        for (auto const& h : hashes)
-        {
-            std::shared_ptr<NodeObject> nObj;
-            Status const status = fetch(h, &nObj);
-            if (status != Status::Ok)
-            {
-                results.push_back({});
-            }
-            else
-            {
-                results.push_back(nObj);
-            }
-        }
-
-        return {results, Status::Ok};
-    }
-
     void
     doInsert(std::shared_ptr<NodeObject> const& no)
     {

src/libxrpl/nodestore/backend/NullFactory.cpp

@@ -12,8 +12,6 @@
 #include <functional>
 #include <memory>
 #include <string>
-#include <utility>
-#include <vector>
 
 namespace xrpl::NodeStore {
 
@@ -52,12 +50,6 @@ public:
         return Status::NotFound;
     }
 
-    std::pair<std::vector<std::shared_ptr<NodeObject>>, Status>
-    fetchBatch(std::vector<uint256> const& hashes) override
-    {
-        return {};
-    }
-
     void
     store(std::shared_ptr<NodeObject> const& object) override
     {

src/libxrpl/nodestore/backend/RocksDBFactory.cpp

@@ -29,8 +29,6 @@
 #include <functional>
 #include <stdexcept>
 #include <string>
-#include <utility>
-#include <vector>
 
 #if XRPL_ROCKSDB_AVAILABLE
 #include <xrpl/basics/ByteUtilities.h>
@@ -330,28 +328,6 @@ public:
         return status;
     }
 
-    std::pair<std::vector<std::shared_ptr<NodeObject>>, Status>
-    fetchBatch(std::vector<uint256> const& hashes) override
-    {
-        std::vector<std::shared_ptr<NodeObject>> results;
-        results.reserve(hashes.size());
-        for (auto const& h : hashes)
-        {
-            std::shared_ptr<NodeObject> nObj;
-            Status const status = fetch(h, &nObj);
-            if (status != Status::Ok)
-            {
-                results.push_back({});
-            }
-            else
-            {
-                results.push_back(nObj);
-            }
-        }
-
-        return {results, Status::Ok};
-    }
-
     void
     store(std::shared_ptr<NodeObject> const& object) override
     {

src/libxrpl/protocol/BuildInfo.cpp

@@ -23,7 +23,7 @@ namespace {
 //------------------------------------------------------------------------------
 // clang-format off
 // NOLINTNEXTLINE(readability-identifier-naming)
-char const* const versionString = "3.2.0-b6"
+char const* const versionString = "3.2.0-rc2"
     // clang-format on
     ;
 

src/libxrpl/protocol/IOUAmount.cpp

@@ -56,7 +56,7 @@ IOUAmount::fromNumber(Number const& number)
     // to normalize, which calls fromNumber
     IOUAmount result{};
     std::tie(result.mantissa_, result.exponent_) =
-        number.normalizeToRange(kMinMantissa, kMaxMantissa);
+        number.normalizeToRange<kMinMantissa, kMaxMantissa>();
     return result;
 }
 

src/libxrpl/protocol/Rules.cpp

@@ -7,6 +7,7 @@
 #include <xrpl/beast/hash/uhash.h>
 #include <xrpl/beast/utility/instrumentation.h>
 #include <xrpl/protocol/Feature.h>
+#include <xrpl/protocol/IOUAmount.h>
 #include <xrpl/protocol/STVector256.h>
 
 #include <memory>
@@ -38,15 +39,68 @@ setCurrentTransactionRules(std::optional<Rules> r)
     // Make global changes associated with the rules before the value is moved.
     // Push the appropriate setting, instead of having the class pull every time
     // the value is needed. That could get expensive fast.
-    bool const enableLargeNumbers =
+
+    // If any new conditions with new amendments are added, those amendments must also be added to
+    // useRulesGuards.
+    bool const enableVaultNumbers =
         !r || (r->enabled(featureSingleAssetVault) || r->enabled(featureLendingProtocol));
-    Number::setMantissaScale(
-        enableLargeNumbers ? MantissaRange::MantissaScale::Large
-                           : MantissaRange::MantissaScale::Small);
+    bool const enableCuspRoundingFix = !r || r->enabled(fixCleanup3_2_0);
+    XRPL_ASSERT(
+        !r || useRulesGuards(*r) == (enableCuspRoundingFix || enableVaultNumbers),
+        "setCurrentTransactionRules : rule decisions match");
+
+    // Declare the range this way to keep clang-tidy from complaining
+    auto const range = [enableCuspRoundingFix, enableVaultNumbers]() {
+        if (enableVaultNumbers)
+        {
+            if (enableCuspRoundingFix)
+            {
+                return MantissaRange::MantissaScale::Large;
+            }
+            return MantissaRange::MantissaScale::LargeLegacy;
+        }
+        return MantissaRange::MantissaScale::Small;
+    }();
+    Number::setMantissaScale(range);
 
     *getCurrentTransactionRulesRef() = std::move(r);
 }
 
+bool
+useRulesGuards(Rules const& rules)
+{
+    // The list of amendments used here - to decide whether to create a RulesGuard - must be a
+    // superset of the list used to figure out which mantissa scale to use in
+    // setCurrentTransactionRules. Additional amendments can be added if desired.
+    //
+    // As soon as any one of these amendments is retired, this whole function can be removed, along
+    // with createGuards, and any other callers, and the first set of guards can be created directly
+    // at the call site, without using optional.
+    return rules.enabled(fixCleanup3_2_0) || rules.enabled(featureSingleAssetVault) ||
+        rules.enabled(featureLendingProtocol);
+}
+
+void
+createGuards(
+    Rules const& rules,
+    std::optional<NumberSO>& stNumberSO,
+    std::optional<CurrentTransactionRulesGuard>& rulesGuard,
+    std::optional<NumberMantissaScaleGuard>& mantissaScaleGuard)
+{
+    if (useRulesGuards(rules))
+    {
+        // raii classes for the current ledger rules.
+        // fixUniversalNumber predates the rulesGuard and should be replaced.
+        stNumberSO.emplace(rules.enabled(fixUniversalNumber));
+        rulesGuard.emplace(rules);
+    }
+    else
+    {
+        // Without those features enabled, always use the old number rules.
+        mantissaScaleGuard.emplace(MantissaRange::MantissaScale::Small);
+    }
+}
+
 class Rules::Impl
 {
 private:

src/libxrpl/protocol/STAmount.cpp

@@ -19,8 +19,10 @@
 #include <xrpl/protocol/Protocol.h>
 #include <xrpl/protocol/Rules.h>
 #include <xrpl/protocol/SField.h>
+#include <xrpl/protocol/STArray.h>
 #include <xrpl/protocol/STBase.h>
 #include <xrpl/protocol/STNumber.h>
+#include <xrpl/protocol/STObject.h>
 #include <xrpl/protocol/Serializer.h>
 #include <xrpl/protocol/SystemParameters.h>
 #include <xrpl/protocol/UintTypes.h>
@@ -1222,6 +1224,50 @@ operator-(STAmount const& value)
         STAmount::Unchecked{});
 }
 
+static bool
+hasInvalidAmount(STBase const& field, int depth, beast::Journal j);
+
+static bool
+hasInvalidAmount(STObject const& object, int depth, beast::Journal j)
+{
+    return std::ranges::any_of(
+        object, [&](STBase const& field) { return hasInvalidAmount(field, depth, j); });
+}
+
+static bool
+hasInvalidAmount(STArray const& array, int depth, beast::Journal j)
+{
+    return std::ranges::any_of(
+        array, [&](STObject const& object) { return hasInvalidAmount(object, depth, j); });
+}
+
+static bool
+hasInvalidAmount(STBase const& field, int depth, beast::Journal j)
+{
+    if (depth > 10)
+    {
+        JLOG(j.error()) << "hasInvalidAmount: depth exceeds 10";
+        return true;
+    }
+
+    if (auto const amount = dynamic_cast<STAmount const*>(&field))
+        return !isLegalMPT(*amount) || !isLegalNet(*amount);
+
+    if (auto const object = dynamic_cast<STObject const*>(&field))
+        return hasInvalidAmount(*object, depth + 1, j);
+
+    if (auto const array = dynamic_cast<STArray const*>(&field))
+        return hasInvalidAmount(*array, depth + 1, j);
+
+    return false;
+}
+
+bool
+hasInvalidAmount(STBase const& field, beast::Journal j)
+{
+    return hasInvalidAmount(field, 0, j);
+}
+
 //------------------------------------------------------------------------------
 //
 // Arithmetic

src/libxrpl/protocol/STNumber.cpp

@@ -96,7 +96,8 @@ STNumber::add(Serializer& s) const
             // Json. Regardless, the only time we should be serializing an
             // STNumber is when the scale is large.
             XRPL_ASSERT_PARTS(
-                Number::getMantissaScale() == MantissaRange::MantissaScale::Large,
+                Number::getMantissaScale() == MantissaRange::MantissaScale::LargeLegacy ||
+                    Number::getMantissaScale() == MantissaRange::MantissaScale::Large,
                 "xrpl::STNumber::add",
                 "STNumber only used with large mantissa scale");
 #endif

src/libxrpl/protocol/STPathSet.cpp

@@ -90,8 +90,12 @@ STPathSet::STPathSet(SerialIter& sit, SField const& name) : STBase(name)
             if (hasAccount)
                 account = sit.get160();
 
-            XRPL_ASSERT(
-                !(hasCurrency && hasMPT), "xrpl::STPathSet::STPathSet : not has Currency and MPT");
+            if (hasCurrency && hasMPT)
+            {
+                JLOG(debugLog().error()) << "Bad path element MPT and Currency in pathset";
+                Throw<std::runtime_error>("bad path element: MPT and Currency");
+            }
+
             if (hasCurrency)
                 asset = Currency::fromRaw(sit.get160());
 
@@ -101,7 +105,7 @@ STPathSet::STPathSet(SerialIter& sit, SField const& name) : STBase(name)
             if (hasIssuer)
                 issuer = sit.get160();
 
-            path.emplace_back(account, asset, issuer, hasCurrency);
+            path.emplace_back(account, asset, issuer, hasCurrency || hasMPT);
         }
     }
 }

src/libxrpl/shamap/SHAMap.cpp

@@ -26,13 +26,17 @@
 
 #include <boost/smart_ptr/intrusive_ptr.hpp>
 
+#include <atomic>
+#include <cstddef>
 #include <cstdint>
 #include <exception>
 #include <functional>
+#include <future>
 #include <memory>
 #include <stack>
 #include <stdexcept>
 #include <string>
+#include <thread>
 #include <tuple>
 #include <type_traits>
 #include <utility>
@@ -851,6 +855,98 @@ SHAMap::getHash() const
     return hash;
 }
 
+namespace {
+
+// Recompute hashes bottom-up for the subtree rooted at `node`, descending
+// only into dirty (cowid != 0) resident children — the hash side of
+// walkSubTree, without flushing/sharing. `node` must itself be dirty.
+//
+// Thread-safety: dirty nodes are uniquely owned by the current cowid, and the
+// subtrees hanging off distinct branches are disjoint, so two callers handed
+// children of different branches never touch the same node. Reads of clean
+// (cowid 0) children's cached hashes via updateHashDeep are read-only and safe
+// to race.
+void
+recomputeSubtreeHashes(SHAMapTreeNode* node)
+{
+    if (node->isLeaf())
+    {
+        node->updateHash();
+        return;
+    }
+
+    auto* inner = safeDowncast<SHAMapInnerNode*>(node);
+    for (int branch = 0; branch < SHAMapInnerNode::kBranchFactor; ++branch)
+    {
+        if (inner->isEmptyBranch(branch))
+            continue;
+        auto* child = inner->getChildPointer(branch);
+        if (child && (child->cowid() != 0))
+            recomputeSubtreeHashes(child);
+    }
+    inner->updateHashDeep();
+}
+
+}  // namespace
+
+SHAMapHash
+SHAMap::updateHashesParallel(int workers)
+{
+    // Nothing dirtied since the last settle: the cached root hash is current.
+    // (root_ is always present, matching getHash()'s invariant.)
+    if (root_->cowid() == 0)
+        return root_->getHash();
+
+    if (root_->isLeaf())
+    {
+        root_->updateHash();
+        return root_->getHash();
+    }
+
+    auto* rootInner = safeDowncast<SHAMapInnerNode*>(root_.get());
+
+    // Gather the root's dirty, resident top-level subtrees. These are
+    // independent and can be recomputed concurrently.
+    std::vector<SHAMapTreeNode*> subtrees;
+    for (int branch = 0; branch < kBranchFactor; ++branch)
+    {
+        if (rootInner->isEmptyBranch(branch))
+            continue;
+        auto* child = rootInner->getChildPointer(branch);
+        if (child && (child->cowid() != 0))
+            subtrees.push_back(child);
+    }
+
+    if (workers <= 0)
+        workers = static_cast<int>(std::thread::hardware_concurrency());
+
+    if (workers <= 1 || subtrees.size() <= 1)
+    {
+        for (auto* s : subtrees)
+            recomputeSubtreeHashes(s);
+    }
+    else
+    {
+        int const nthreads = std::min<int>(workers, static_cast<int>(subtrees.size()));
+        std::atomic<std::size_t> next{0};
+        std::vector<std::future<void>> tasks;
+        tasks.reserve(nthreads);
+        for (int t = 0; t < nthreads; ++t)
+        {
+            tasks.push_back(std::async(std::launch::async, [&subtrees, &next] {
+                for (std::size_t i = next++; i < subtrees.size(); i = next++)
+                    recomputeSubtreeHashes(subtrees[i]);
+            }));
+        }
+        for (auto& task : tasks)
+            task.get();
+    }
+
+    // All top-level subtree hashes are now current; finish at the root.
+    rootInner->updateHashDeep();
+    return rootInner->getHash();
+}
+
 bool
 SHAMap::updateGiveItem(SHAMapNodeType type, boost::intrusive_ptr<SHAMapItem const> item)
 {

src/libxrpl/tx/Transactor.cpp

@@ -27,6 +27,7 @@
 #include <xrpl/protocol/PublicKey.h>
 #include <xrpl/protocol/Rules.h>
 #include <xrpl/protocol/SField.h>
+#include <xrpl/protocol/STAmount.h>
 #include <xrpl/protocol/STLedgerEntry.h>
 #include <xrpl/protocol/STTx.h>
 #include <xrpl/protocol/Serializer.h>  // IWYU pragma: keep
@@ -256,6 +257,15 @@ Transactor::preflight2(PreflightContext const& ctx)
     return tesSUCCESS;
 }
 
+NotTEC
+Transactor::preflightUniversal(PreflightContext const& ctx)
+{
+    if (ctx.rules.enabled(fixCleanup3_2_0) && hasInvalidAmount(ctx.tx, ctx.j))
+        return temBAD_AMOUNT;
+
+    return tesSUCCESS;
+}
+
 //------------------------------------------------------------------------------
 
 Transactor::Transactor(ApplyContext& ctx)

src/libxrpl/tx/applySteps.cpp

@@ -7,7 +7,6 @@
 #include <xrpl/beast/utility/instrumentation.h>
 #include <xrpl/ledger/ApplyView.h>
 #include <xrpl/ledger/OpenView.h>
-#include <xrpl/protocol/Feature.h>
 #include <xrpl/protocol/IOUAmount.h>
 #include <xrpl/protocol/Rules.h>
 #include <xrpl/protocol/SField.h>
@@ -66,26 +65,15 @@ withTxnType(Rules const& rules, TxType txnType, F&& f)
     // so these need to be more global.
     //
     // To prevent unintentional side effects on existing checks, they will be
-    // set for every operation only once SingleAssetVault (or later
-    // LendingProtocol) are enabled.
+    // set for every operation only once at least one of the relevant amendments
+    // are enabled.
     //
     // See also Transactor::operator().
     //
     std::optional<NumberSO> stNumberSO;
     std::optional<CurrentTransactionRulesGuard> rulesGuard;
     std::optional<NumberMantissaScaleGuard> mantissaScaleGuard;
-    if (rules.enabled(featureSingleAssetVault) || rules.enabled(featureLendingProtocol))
-    {
-        // raii classes for the current ledger rules.
-        // fixUniversalNumber predates the rulesGuard and should be replaced.
-        stNumberSO.emplace(rules.enabled(fixUniversalNumber));
-        rulesGuard.emplace(rules);
-    }
-    else
-    {
-        // Without those features enabled, always use the old number rules.
-        mantissaScaleGuard.emplace(MantissaRange::MantissaScale::Small);
-    }
+    createGuards(rules, stNumberSO, rulesGuard, mantissaScaleGuard);
 
     switch (txnType)
     {

src/libxrpl/tx/invariants/AMMInvariant.cpp

@@ -45,7 +45,8 @@ ValidAMM::visitEntry(
         // AMM pool changed
         else if (
             (type == ltRIPPLE_STATE && after->isFlag(lsfAMMNode)) ||
-            (type == ltACCOUNT_ROOT && after->isFieldPresent(sfAMMID)))
+            (type == ltACCOUNT_ROOT && after->isFieldPresent(sfAMMID)) ||
+            (type == ltMPTOKEN && after->isFlag(lsfMPTAMM)))
         {
             ammPoolChanged_ = true;
         }
@@ -85,9 +86,9 @@ ValidAMM::finalizeVote(bool enforce, beast::Journal const& j) const
     {
         // LPTokens and the pool can not change on vote
         // LCOV_EXCL_START
-        JLOG(j.error()) << "AMMVote invariant failed: " << lptAMMBalanceBefore_.value_or(STAmount{})
-                        << " " << lptAMMBalanceAfter_.value_or(STAmount{}) << " "
-                        << ammPoolChanged_;
+        JLOG(j.error()) << "Invariant failed: AMMVote failed, "
+                        << lptAMMBalanceBefore_.value_or(STAmount{}) << " "
+                        << lptAMMBalanceAfter_.value_or(STAmount{}) << " " << ammPoolChanged_;
         if (enforce)
             return false;
         // LCOV_EXCL_STOP
@@ -103,7 +104,7 @@ ValidAMM::finalizeBid(bool enforce, beast::Journal const& j) const
     {
         // The pool can not change on bid
         // LCOV_EXCL_START
-        JLOG(j.error()) << "AMMBid invariant failed: pool changed";
+        JLOG(j.error()) << "Invariant failed: AMMBid failed, pool changed";
         if (enforce)
             return false;
         // LCOV_EXCL_STOP
@@ -114,7 +115,7 @@ ValidAMM::finalizeBid(bool enforce, beast::Journal const& j) const
         (*lptAMMBalanceAfter_ > *lptAMMBalanceBefore_ || *lptAMMBalanceAfter_ <= beast::kZero))
     {
         // LCOV_EXCL_START
-        JLOG(j.error()) << "AMMBid invariant failed: " << *lptAMMBalanceBefore_ << " "
+        JLOG(j.error()) << "Invariant failed: AMMBid failed, " << *lptAMMBalanceBefore_ << " "
                         << *lptAMMBalanceAfter_;
         if (enforce)
             return false;
@@ -134,7 +135,7 @@ ValidAMM::finalizeCreate(
     if (!ammAccount_)
     {
         // LCOV_EXCL_START
-        JLOG(j.error()) << "AMMCreate invariant failed: AMM object is not created";
+        JLOG(j.error()) << "Invariant failed: AMMCreate failed, AMM object is not created";
         if (enforce)
             return false;
         // LCOV_EXCL_STOP
@@ -157,8 +158,8 @@ ValidAMM::finalizeCreate(
         if (!validBalances(amount, amount2, *lptAMMBalanceAfter_, ZeroAllowed::No) ||
             ammLPTokens(amount, amount2, lptAMMBalanceAfter_->get<Issue>()) != *lptAMMBalanceAfter_)
         {
-            JLOG(j.error()) << "AMMCreate invariant failed: " << amount << " " << amount2 << " "
-                            << *lptAMMBalanceAfter_;
+            JLOG(j.error()) << "Invariant failed: AMMCreate failed, " << amount << " " << amount2
+                            << " " << *lptAMMBalanceAfter_;
             if (enforce)
                 return false;
         }
@@ -176,7 +177,7 @@ ValidAMM::finalizeDelete(bool enforce, TER res, beast::Journal const& j) const
         // LCOV_EXCL_START
         std::string const msg = (isTesSuccess(res)) ? "AMM object is not deleted on tesSUCCESS"
                                                     : "AMM object is changed on tecINCOMPLETE";
-        JLOG(j.error()) << "AMMDelete invariant failed: " << msg;
+        JLOG(j.error()) << "Invariant failed: AMMDelete failed, " << msg;
         if (enforce)
             return false;
         // LCOV_EXCL_STOP
@@ -191,7 +192,7 @@ ValidAMM::finalizeDEX(bool enforce, beast::Journal const& j) const
     if (ammAccount_)
     {
         // LCOV_EXCL_START
-        JLOG(j.error()) << "AMM swap invariant failed: AMM object changed";
+        JLOG(j.error()) << "Invariant failed: AMM swap failed, AMM object changed";
         if (enforce)
             return false;
         // LCOV_EXCL_STOP
@@ -232,10 +233,10 @@ ValidAMM::generalInvariant(
     };
     if (!nonNegativeBalances || (!strongInvariantCheck && !weakInvariantCheck()))
     {
-        JLOG(j.error()) << "AMM " << tx.getTxnType()
-                        << " invariant failed: " << tx.getHash(HashPrefix::TransactionId) << " "
-                        << ammPoolChanged_ << " " << amount << " " << amount2 << " "
-                        << poolProductMean << " " << lptAMMBalanceAfter_->getText() << " "
+        JLOG(j.error()) << "Invariant failed: AMM " << tx.getTxnType() << " "
+                        << tx.getHash(HashPrefix::TransactionId) << " " << ammPoolChanged_ << " "
+                        << amount << " " << amount2 << " " << poolProductMean << " "
+                        << lptAMMBalanceAfter_->getText() << " "
                         << ((*lptAMMBalanceAfter_ == beast::kZero)
                                 ? Number{1}
                                 : ((*lptAMMBalanceAfter_ - poolProductMean) / poolProductMean));
@@ -256,7 +257,7 @@ ValidAMM::finalizeDeposit(
     if (!ammAccount_)
     {
         // LCOV_EXCL_START
-        JLOG(j.error()) << "AMMDeposit invariant failed: AMM object is deleted";
+        JLOG(j.error()) << "Invariant failed: AMMDeposit failed, AMM object is deleted";
         if (enforce)
             return false;
         // LCOV_EXCL_STOP

src/libxrpl/tx/invariants/DirectoryInvariant.cpp

@@ -40,19 +40,27 @@ badExchangeRate(SLE const& dir)
 
 void
 ValidBookDirectory::visitEntry(
-    bool,
+    bool isDelete,
     std::shared_ptr<SLE const> const& before,
     std::shared_ptr<SLE const> const& after)
 {
     // New root directories must have matching exchange-rate metadata. New
-    // child directories must point to an existing root.
+    // child directories, and modified directories that change sfRootIndex, must
+    // point to an existing root.
 
-    // Only validate newly-created directories; LedgerStateFix handles legacy
-    // bad exchange-rate metadata.
-    if (badBookDirectory_ || before || !after || after->getType() != ltDIR_NODE)
+    // Only validate newly-created directories and sfRootIndex changes;
+    // LedgerStateFix handles legacy bad exchange-rate metadata. Skip deletions
+    // because `after` is not guaranteed to be null.
+    if (badBookDirectory_ || isDelete || !after || after->getType() != ltDIR_NODE)
         return;
 
     auto const rootIndex = after->getFieldH256(sfRootIndex);
+    // Ignore ordinary modifications that do not change which root this
+    // directory belongs to. That tolerates legacy bad exchange-rate metadata
+    // during normal operation while still checking sfRootIndex changes.
+    if (before && before->getFieldH256(sfRootIndex) == rootIndex)
+        return;
+
     if (after->key() == rootIndex && !badBookDirectory_)
     {
         badBookDirectory_ = badBookDirectory_ || badExchangeRate(*after);

src/libxrpl/tx/invariants/InvariantCheck.cpp

@@ -840,7 +840,7 @@ ValidClawback::finalize(
                 [&](MPTIssue const& issue) {
                     return accountHolds(
                         view,
-                        issuer,
+                        holder,
                         issue,
                         FreezeHandling::IgnoreFreeze,
                         AuthHandling::IgnoreAuth,
@@ -1080,4 +1080,35 @@ NoModifiedUnmodifiableFields::finalize(
     return true;
 }
 
+void
+ValidAmounts::visitEntry(
+    bool isDelete,
+    std::shared_ptr<SLE const> const&,
+    std::shared_ptr<SLE const> const& after)
+{
+    if (!isDelete && after)
+        afterEntries_.push_back(after);
+}
+
+bool
+ValidAmounts::finalize(
+    STTx const&,
+    TER const,
+    XRPAmount const,
+    ReadView const& view,
+    beast::Journal const& j) const
+{
+    bool const badLedgerEntry = std::ranges::any_of(
+        afterEntries_, [&](auto const& sle) { return hasInvalidAmount(*sle, j); });
+
+    if (badLedgerEntry)
+    {
+        JLOG(j.fatal())
+            << "Invariant failed: ledger entry contains non-canonical MPT or XRP amount";
+        return !view.rules().enabled(fixCleanup3_2_0);
+    }
+
+    return true;
+}
+
 }  // namespace xrpl

src/libxrpl/tx/invariants/MPTInvariant.cpp

@@ -17,6 +17,7 @@
 #include <xrpl/protocol/STTx.h>
 #include <xrpl/protocol/TER.h>
 #include <xrpl/protocol/TxFormats.h>
+#include <xrpl/protocol/UintTypes.h>
 #include <xrpl/protocol/XRPAmount.h>
 #include <xrpl/tx/invariants/InvariantCheckPrivilege.h>
 
@@ -442,11 +443,11 @@ ValidMPTPayment::finalize(
 {
     if (isTesSuccess(result))
     {
-        bool const enforce = view.rules().enabled(featureMPTokensV2);
+        bool const invariantPasses = !view.rules().enabled(featureMPTokensV2);
         if (overflow_)
         {
             JLOG(j.fatal()) << "Invariant failed: OutstandingAmount overflow";
-            return !enforce;
+            return invariantPasses;
         }
 
         auto const signedMax = static_cast<std::int64_t>(kMaxMpTokenAmount);
@@ -464,7 +465,7 @@ ValidMPTPayment::finalize(
                 JLOG(j.fatal()) << "Invariant failed: invalid OutstandingAmount balance "
                                 << data.outstanding[kIBefore] << " " << data.outstanding[kIAfter]
                                 << " " << data.mptAmount;
-                return !enforce;
+                return invariantPasses;
             }
         }
     }
@@ -472,4 +473,147 @@ ValidMPTPayment::finalize(
     return true;
 }
 
+void
+ValidMPTTransfer::visitEntry(
+    bool isDelete,
+    std::shared_ptr<SLE const> const& before,
+    std::shared_ptr<SLE const> const& after)
+{
+    // Record the before/after MPTAmount for each (issuanceID, account) pair
+    // so finalize() can determine whether a transfer actually occurred.
+    auto update = [&](SLE const& sle, bool isBefore) {
+        if (sle.getType() == ltMPTOKEN)
+        {
+            auto const issuanceID = sle[sfMPTokenIssuanceID];
+            auto const account = sle[sfAccount];
+            auto const amount = sle[sfMPTAmount];
+            if (isBefore)
+            {
+                amount_[issuanceID][account].amtBefore = amount;
+            }
+            else
+            {
+                amount_[issuanceID][account].amtAfter = amount;
+            }
+            if (isDelete && isBefore)
+            {
+                deletedAuthorized_[sle.key()] = sle.isFlag(lsfMPTAuthorized);
+            }
+        }
+    };
+
+    if (before)
+        update(*before, true);
+
+    if (after)
+        update(*after, false);
+}
+
+bool
+ValidMPTTransfer::isAuthorized(
+    ReadView const& view,
+    MPTID const& mptid,
+    AccountID const& holder,
+    bool reqAuth) const
+{
+    auto const key = keylet::mptoken(mptid, holder);
+    auto const it = deletedAuthorized_.find(key.key);
+    if (it != deletedAuthorized_.end())
+        return !reqAuth || it->second;
+    return isTesSuccess(requireAuth(view, MPTIssue{mptid}, holder));
+}
+
+bool
+ValidMPTTransfer::finalize(
+    STTx const& tx,
+    TER const,
+    XRPAmount const,
+    ReadView const& view,
+    beast::Journal const& j)
+{
+    if (hasPrivilege(tx, OverrideFreeze))
+        return true;
+
+    // DEX transactions (AMM[Create,Deposit], cross-currency payments, offer creates) are
+    // subject to the MPTCanTrade flag in addition to the standard transfer rules.
+    // A payment is only DEX if it is a cross-currency payment.
+    auto const txnType = tx.getTxnType();
+    auto const isDEX = [&] {
+        if (txnType == ttPAYMENT)
+        {
+            // A payment is cross-currency (and thus DEX) only if SendMax is present
+            // and its asset differs from the destination asset.
+            auto const amount = tx[sfAmount];
+            return tx[~sfSendMax].value_or(amount).asset() != amount.asset();
+        }
+        return txnType == ttAMM_CREATE || txnType == ttAMM_DEPOSIT || txnType == ttOFFER_CREATE;
+    }();
+
+    // Only enforce once MPTokensV2 is enabled to preserve consensus with non-V2 nodes.
+    // Log invariant failure error even if MPTokensV2 is disabled.
+    auto const invariantPasses = !view.rules().enabled(featureMPTokensV2);
+
+    for (auto const& [mptID, values] : amount_)
+    {
+        std::uint16_t senders = 0;
+        std::uint16_t receivers = 0;
+        bool invalidTransfer = false;
+        auto const sleIssuance = view.read(keylet::mptIssuance(mptID));
+        if (!sleIssuance)
+        {
+            continue;
+        }
+
+        // These transactions are recovery/settlement paths. They may move an
+        // existing MPT position even after the issuer clears CanTransfer, so
+        // holders are not trapped in AMM, vault, or loan protocol accounts.
+        auto const waivesCanTransfer = txnType == ttAMM_WITHDRAW ||
+            (view.rules().enabled(fixCleanup3_2_0) &&
+             (txnType == ttVAULT_WITHDRAW || txnType == ttLOAN_BROKER_COVER_WITHDRAW ||
+              txnType == ttLOAN_PAY));
+        auto const canTransfer = sleIssuance->isFlag(lsfMPTCanTransfer) || waivesCanTransfer;
+        auto const canTrade = sleIssuance->isFlag(lsfMPTCanTrade);
+        auto const reqAuth = sleIssuance->isFlag(lsfMPTRequireAuth);
+
+        for (auto const& [account, value] : values)
+        {
+            // Classify each account as a sender or receiver based on whether their MPTAmount
+            // decreased or increased. Count new MPToken holders (no amtBefore) as receivers.
+            // Skip deleted MPToken holders (amtAfter is nullopt); deletion requires zero balance.
+            if (value.amtAfter.has_value() && value.amtBefore.value_or(0) != *value.amtAfter)
+            {
+                if (!value.amtBefore.has_value() || *value.amtAfter > *value.amtBefore)
+                {
+                    ++receivers;
+                }
+                else
+                {
+                    ++senders;
+                }
+
+                // Check once: if any involved account is frozen, the whole
+                // issuance transfer is considered frozen. Only need to check for
+                // frozen if there is a transfer of funds.
+                if (!invalidTransfer &&
+                    (isFrozen(view, account, MPTIssue{mptID}) ||
+                     !isAuthorized(view, mptID, account, reqAuth)))
+                {
+                    invalidTransfer = true;
+                }
+            }
+        }
+        // A transfer between holders has occurred (senders > 0 && receivers > 0).
+        // Fail if the issuance is frozen, does not permit transfers, or — for
+        // DEX transactions — does not permit trading.
+        if ((invalidTransfer || !canTransfer || (isDEX && !canTrade)) && senders > 0 &&
+            receivers > 0)
+        {
+            JLOG(j.fatal()) << "Invariant failed: invalid MPToken transfer between holders";
+            return invariantPasses;
+        }
+    }
+
+    return true;
+}
+
 }  // namespace xrpl

src/libxrpl/tx/invariants/VaultInvariant.cpp

@@ -186,6 +186,101 @@ ValidVault::visitEntry(
     }
 }
 
+std::optional<ValidVault::DeltaInfo>
+ValidVault::deltaAssets(AccountID const& id) const
+{
+    auto const& vaultAsset = afterVault_[0].asset;
+    auto const lookup = [&](uint256 const& key) -> std::optional<DeltaInfo> {
+        auto const it = deltas_.find(key);
+        if (it == deltas_.end())
+            return std::nullopt;
+        return it->second;
+    };
+
+    return std::visit(
+        [&]<typename TIss>(TIss const& issue) -> std::optional<DeltaInfo> {
+            if constexpr (std::is_same_v<TIss, Issue>)
+            {
+                if (isXRP(issue))
+                    return lookup(keylet::account(id).key);
+                auto result = lookup(keylet::line(id, issue).key);
+                // Trust-line balance is stored from the low-account's perspective;
+                // negate if id is the high account so the delta is in id's terms.
+                if (result && id > issue.getIssuer())
+                    result->delta = -result->delta;
+                return result;
+            }
+            else if constexpr (std::is_same_v<TIss, MPTIssue>)
+            {
+                return lookup(keylet::mptoken(issue.getMptID(), id).key);
+            }
+        },
+        vaultAsset.value());
+}
+
+std::optional<ValidVault::DeltaInfo>
+ValidVault::deltaAssetsTxAccount(STTx const& tx, XRPAmount fee) const
+{
+    auto const& vaultAsset = afterVault_[0].asset;
+    auto ret = deltaAssets(tx[sfAccount]);
+    if (!ret.has_value() || !vaultAsset.native())
+        return ret;
+
+    if (auto const delegate = tx[~sfDelegate]; delegate.has_value() && *delegate != tx[sfAccount])
+        return ret;
+
+    ret->delta += fee.drops();
+    if (ret->delta == kZero)
+        return std::nullopt;
+
+    return ret;
+}
+
+std::optional<ValidVault::DeltaInfo>
+ValidVault::deltaShares(AccountID const& id) const
+{
+    auto const& afterVault = afterVault_[0];
+    auto const it = [&]() {
+        if (id == afterVault.pseudoId)
+            return deltas_.find(keylet::mptIssuance(afterVault.shareMPTID).key);
+        return deltas_.find(keylet::mptoken(afterVault.shareMPTID, id).key);
+    }();
+
+    return it != deltas_.end() ? std::optional<DeltaInfo>(it->second) : std::nullopt;
+}
+
+bool
+ValidVault::isVaultEmpty(Vault const& vault)
+{
+    return vault.assetsAvailable == 0 && vault.assetsTotal == 0;
+}
+
+std::int32_t
+ValidVault::computeVaultMinScale(DeltaInfo const& vaultDelta, Rules const& rules) const
+{
+    // Returns the posterior `assetsTotal` scale.
+    //
+    // 1. Because STAmounts are normalized, `assetsTotal` (being >= `assetsAvailable`)
+    // safely represents the coarsest exponent needed for both fields.
+    //
+    // 2. The scale may decrease (withdraw/clawback) or increase (deposit). In both cases
+    // we ensure the vault is in a legitimate state in the post-transaction scale.
+    auto const& afterVault = afterVault_[0];
+    auto const& vaultAsset = afterVault.asset;
+    if (rules.enabled(fixCleanup3_2_0))
+    {
+        NumberRoundModeGuard const roundGuard(Number::RoundingMode::ToNearest);
+        return scale(afterVault.assetsTotal, vaultAsset);
+    }
+
+    auto const& beforeVault = beforeVault_[0];
+    auto const totalDelta =
+        DeltaInfo::makeDelta(beforeVault.assetsTotal, afterVault.assetsTotal, vaultAsset);
+    auto const availableDelta =
+        DeltaInfo::makeDelta(beforeVault.assetsAvailable, afterVault.assetsAvailable, vaultAsset);
+    return computeCoarsestScale({vaultDelta, totalDelta, availableDelta});
+}
+
 bool
 ValidVault::finalize(
     STTx const& tx,
@@ -445,61 +540,6 @@ ValidVault::finalize(
     }
 
     auto const& vaultAsset = afterVault.asset;
-    auto const deltaAssets = [&](AccountID const& id) -> std::optional<DeltaInfo> {
-        auto const get =  //
-            [&](auto const& it, std::int8_t sign = 1) -> std::optional<DeltaInfo> {
-            if (it == deltas_.end())
-                return std::nullopt;
-
-            return DeltaInfo{it->second.delta * sign, it->second.scale};
-        };
-
-        return std::visit(
-            [&]<typename TIss>(TIss const& issue) {
-                if constexpr (std::is_same_v<TIss, Issue>)
-                {
-                    if (isXRP(issue))
-                        return get(deltas_.find(keylet::account(id).key));
-                    return get(
-                        deltas_.find(keylet::line(id, issue).key), id > issue.getIssuer() ? -1 : 1);
-                }
-                else if constexpr (std::is_same_v<TIss, MPTIssue>)
-                {
-                    return get(deltas_.find(keylet::mptoken(issue.getMptID(), id).key));
-                }
-            },
-            vaultAsset.value());
-    };
-    auto const deltaAssetsTxAccount = [&]() -> std::optional<DeltaInfo> {
-        auto ret = deltaAssets(tx[sfAccount]);
-        // Nothing returned or not XRP transaction
-        if (!ret.has_value() || !vaultAsset.native())
-            return ret;
-
-        // Delegated transaction; no need to compensate for fees
-        if (auto const delegate = tx[~sfDelegate];
-            delegate.has_value() && *delegate != tx[sfAccount])
-            return ret;
-
-        ret->delta += fee.drops();
-        if (ret->delta == kZero)
-            return std::nullopt;
-
-        return ret;
-    };
-    auto const deltaShares = [&](AccountID const& id) -> std::optional<DeltaInfo> {
-        auto const it = [&]() {
-            if (id == afterVault.pseudoId)
-                return deltas_.find(keylet::mptIssuance(afterVault.shareMPTID).key);
-            return deltas_.find(keylet::mptoken(afterVault.shareMPTID, id).key);
-        }();
-
-        return it != deltas_.end() ? std::optional<DeltaInfo>(it->second) : std::nullopt;
-    };
-
-    auto const vaultHoldsNoAssets = [&](Vault const& vault) {
-        return vault.assetsAvailable == 0 && vault.assetsTotal == 0;
-    };
 
     // Technically this does not need to be a lambda, but it's more
     // convenient thanks to early "return false"; the not-so-nice
@@ -629,16 +669,8 @@ ValidVault::finalize(
                     return false;  // That's all we can do
                 }
 
-                // Get the coarsest scale to round calculations to
-                auto const totalDelta = DeltaInfo::makeDelta(
-                    beforeVault.assetsTotal, afterVault.assetsTotal, vaultAsset);
-                auto const availableDelta = DeltaInfo::makeDelta(
-                    beforeVault.assetsAvailable, afterVault.assetsAvailable, vaultAsset);
-                auto const minScale = computeCoarsestScale({
-                    *maybeVaultDeltaAssets,
-                    totalDelta,
-                    availableDelta,
-                });
+                // Get the posterior scale to round calculations to
+                auto const minScale = computeVaultMinScale(*maybeVaultDeltaAssets, view.rules());
 
                 auto const vaultDeltaAssets =
                     roundToAsset(vaultAsset, maybeVaultDeltaAssets->delta, minScale);
@@ -669,12 +701,11 @@ ValidVault::finalize(
 
                 if (!issuerDeposit)
                 {
-                    auto const maybeAccDeltaAssets = deltaAssetsTxAccount();
+                    auto const maybeAccDeltaAssets = deltaAssetsTxAccount(tx, fee);
                     if (!maybeAccDeltaAssets)
                     {
-                        JLOG(j.fatal()) <<  //
-                            "Invariant failed: deposit must change depositor "
-                            "balance";
+                        JLOG(j.fatal())
+                            << "Invariant failed: deposit must change depositor balance";
                         return false;
                     }
                     auto const localMinScale =
@@ -685,19 +716,20 @@ ValidVault::finalize(
                     auto const localVaultDeltaAssets =
                         roundToAsset(vaultAsset, vaultDeltaAssets, localMinScale);
 
+                    // For IOUs, if the deposit amount is not-representable at depositor trustline
+                    // scale deposit amount could round to zero, giving depositor shares for no
+                    // assets. Unlike withdrawal, we do not allow that.
                     if (accountDeltaAssets >= kZero)
                     {
-                        JLOG(j.fatal()) <<  //
-                            "Invariant failed: deposit must decrease depositor "
-                            "balance";
+                        JLOG(j.fatal())
+                            << "Invariant failed: deposit must decrease depositor balance";
                         result = false;
                     }
 
                     if (localVaultDeltaAssets * -1 != accountDeltaAssets)
                     {
-                        JLOG(j.fatal()) <<  //
-                            "Invariant failed: deposit must change vault and "
-                            "depositor balance by equal amount";
+                        JLOG(j.fatal()) << "Invariant failed: " <<  //
+                            "deposit must change vault and depositor balance by equal amount";
                         result = false;
                     }
                 }
@@ -705,45 +737,38 @@ ValidVault::finalize(
                 if (afterVault.assetsMaximum > kZero &&
                     afterVault.assetsTotal > afterVault.assetsMaximum)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: deposit assets outstanding must not "
-                        "exceed assets maximum";
+                    JLOG(j.fatal()) << "Invariant failed: " <<  //
+                        "deposit assets outstanding must not exceed assets maximum";
                     result = false;
                 }
 
                 auto const maybeAccDeltaShares = deltaShares(tx[sfAccount]);
                 if (!maybeAccDeltaShares)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: deposit must change depositor "
-                        "shares";
+                    JLOG(j.fatal()) << "Invariant failed: deposit must change depositor shares";
                     return false;  // That's all we can do
                 }
-                // We don't need to round shares, they are integral MPT
+                // We don't round shares, they are integral MPT
                 auto const& accountDeltaShares = *maybeAccDeltaShares;
                 if (accountDeltaShares.delta <= kZero)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: deposit must increase depositor "
-                        "shares";
+                    JLOG(j.fatal()) << "Invariant failed: deposit must increase depositor shares";
                     result = false;
                 }
 
                 auto const maybeVaultDeltaShares = deltaShares(afterVault.pseudoId);
                 if (!maybeVaultDeltaShares || maybeVaultDeltaShares->delta == kZero)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: deposit must change vault shares";
+                    JLOG(j.fatal()) << "Invariant failed: deposit must change vault shares";
                     return false;  // That's all we can do
                 }
 
-                // We don't need to round shares, they are integral MPT
+                // We don't round shares, they are integral MPT
                 auto const& vaultDeltaShares = *maybeVaultDeltaShares;
                 if (vaultDeltaShares.delta * -1 != accountDeltaShares.delta)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: deposit must change depositor and "
-                        "vault shares by equal amount";
+                    JLOG(j.fatal()) << "Invariant failed: " <<  //
+                        "deposit must change depositor and vault shares by equal amount";
                     result = false;
                 }
 
@@ -751,8 +776,8 @@ ValidVault::finalize(
                     vaultAsset, afterVault.assetsTotal - beforeVault.assetsTotal, minScale);
                 if (assetTotalDelta != vaultDeltaAssets)
                 {
-                    JLOG(j.fatal()) << "Invariant failed: deposit and assets "
-                                       "outstanding must add up";
+                    JLOG(j.fatal())
+                        << "Invariant failed: deposit and assets outstanding must add up";
                     result = false;
                 }
 
@@ -760,8 +785,7 @@ ValidVault::finalize(
                     vaultAsset, afterVault.assetsAvailable - beforeVault.assetsAvailable, minScale);
                 if (assetAvailableDelta != vaultDeltaAssets)
                 {
-                    JLOG(j.fatal()) << "Invariant failed: deposit and assets "
-                                       "available must add up";
+                    JLOG(j.fatal()) << "Invariant failed: deposit and assets available must add up";
                     result = false;
                 }
 
@@ -772,34 +796,25 @@ ValidVault::finalize(
 
                 XRPL_ASSERT(
                     !beforeVault_.empty(),
-                    "xrpl::ValidVault::finalize : withdrawal updated a "
-                    "vault");
+                    "xrpl::ValidVault::finalize : withdrawal updated a vault");
                 auto const& beforeVault = beforeVault_[0];
 
                 auto const maybeVaultDeltaAssets = deltaAssets(afterVault.pseudoId);
-
                 if (!maybeVaultDeltaAssets)
                 {
-                    JLOG(j.fatal()) << "Invariant failed: withdrawal must "
-                                       "change vault balance";
+                    JLOG(j.fatal()) << "Invariant failed: withdrawal must change vault balance";
                     return false;  // That's all we can do
                 }
 
-                // Get the most coarse scale to round calculations to
-                auto const totalDelta = DeltaInfo::makeDelta(
-                    beforeVault.assetsTotal, afterVault.assetsTotal, vaultAsset);
-                auto const availableDelta = DeltaInfo::makeDelta(
-                    beforeVault.assetsAvailable, afterVault.assetsAvailable, vaultAsset);
-                auto const minScale =
-                    computeCoarsestScale({*maybeVaultDeltaAssets, totalDelta, availableDelta});
+                // Get the posterior scale to round calculations to
+                auto const minScale = computeVaultMinScale(*maybeVaultDeltaAssets, view.rules());
 
                 auto const vaultPseudoDeltaAssets =
                     roundToAsset(vaultAsset, maybeVaultDeltaAssets->delta, minScale);
 
                 if (vaultPseudoDeltaAssets >= kZero)
                 {
-                    JLOG(j.fatal()) << "Invariant failed: withdrawal must "
-                                       "decrease vault balance";
+                    JLOG(j.fatal()) << "Invariant failed: withdrawal must decrease vault balance";
                     result = false;
                 }
 
@@ -814,7 +829,7 @@ ValidVault::finalize(
 
                 if (!issuerWithdrawal)
                 {
-                    auto const maybeAccDelta = deltaAssetsTxAccount();
+                    auto const maybeAccDelta = deltaAssetsTxAccount(tx, fee);
                     auto const maybeOtherAccDelta = [&]() -> std::optional<DeltaInfo> {
                         if (auto const destination = tx[~sfDestination];
                             destination && *destination != tx[sfAccount])
@@ -825,8 +840,7 @@ ValidVault::finalize(
                     if (maybeAccDelta.has_value() == maybeOtherAccDelta.has_value())
                     {
                         JLOG(j.fatal()) <<  //
-                            "Invariant failed: withdrawal must change one "
-                            "destination balance";
+                            "Invariant failed: withdrawal must change one destination balance";
                         return false;
                     }
 
@@ -835,63 +849,83 @@ ValidVault::finalize(
 
                     // the scale of destinationDelta can be coarser than
                     // minScale, so we take that into account when rounding
-                    auto const localMinScale =
-                        std::max(minScale, computeCoarsestScale({destinationDelta}));
+                    auto const destinationScale = computeCoarsestScale({destinationDelta});
+                    auto const localMinScale = std::max(minScale, destinationScale);
 
                     auto const roundedDestinationDelta =
                         roundToAsset(vaultAsset, destinationDelta.delta, localMinScale);
 
-                    if (roundedDestinationDelta <= kZero)
+                    // Post-fixCleanup3_2_0: Tolerate zero-rounded destination deltas for IOUs only.
+                    // If the receiver's trust line sits at a coarser scale, the inflow may
+                    // safely round down to zero.
+                    //
+                    // XRP and MPT remain strict. Because they are integer-exact, a zero
+                    // destination delta indicates a true accounting bug, not a rounding artifact.
+                    bool const tolerateZeroDelta =
+                        view.rules().enabled(fixCleanup3_2_0) && !vaultAsset.integral();
+                    auto const invalidBalanceChange = tolerateZeroDelta
+                        ? roundedDestinationDelta < kZero
+                        : roundedDestinationDelta <= kZero;
+                    if (invalidBalanceChange)
                     {
                         JLOG(j.fatal()) <<  //
-                            "Invariant failed: withdrawal must increase "
-                            "destination balance";
+                            "Invariant failed: withdrawal must increase destination balance";
                         result = false;
                     }
 
                     auto const localPseudoDeltaAssets =
                         roundToAsset(vaultAsset, vaultPseudoDeltaAssets, localMinScale);
-                    if (localPseudoDeltaAssets * -1 != roundedDestinationDelta)
+                    // For IOU assets near a precision boundary the destination's STAmount
+                    // exponent can shift, making part of the sent value unrepresentable at the
+                    // receiver's new scale — that portion is irreversibly absorbed by the IOU
+                    // rail.  Tolerate the mismatch only when the destroyed amount (vault outflow
+                    // minus destination inflow, in Number space) is itself sub-ULP at the
+                    // destination's scale.  Floor rounding is used so that values exactly at the
+                    // step boundary are not mistakenly dismissed.  Any representable discrepancy
+                    // indicates a real accounting bug and must be caught.
+                    auto const destroyedIsSubUlp = tolerateZeroDelta &&
+                        roundToAsset(
+                            vaultAsset,
+                            maybeVaultDeltaAssets->delta * -1 - destinationDelta.delta,
+                            destinationScale,
+                            Number::RoundingMode::Downward) == kZero;
+                    if (!destroyedIsSubUlp &&
+                        localPseudoDeltaAssets * -1 != roundedDestinationDelta)
                     {
-                        JLOG(j.fatal()) <<  //
-                            "Invariant failed: withdrawal must change vault "
-                            "and destination balance by equal amount";
+                        JLOG(j.fatal()) << "Invariant failed: " <<  //
+                            "withdrawal must change vault and destination balance by equal "
+                            "amount";
                         result = false;
                     }
                 }
 
-                // We don't need to round shares, they are integral MPT
+                // We don't round shares, they are integral MPT
                 auto const accountDeltaShares = deltaShares(tx[sfAccount]);
                 if (!accountDeltaShares)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: withdrawal must change depositor "
-                        "shares";
+                    JLOG(j.fatal()) << "Invariant failed: withdrawal must change depositor shares";
                     return false;
                 }
 
                 if (accountDeltaShares->delta >= kZero)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: withdrawal must decrease depositor "
-                        "shares";
+                    JLOG(j.fatal())
+                        << "Invariant failed: withdrawal must decrease depositor shares";
                     result = false;
                 }
 
-                // We don't need to round shares, they are integral MPT
+                // We don't round shares, they are integral MPT
                 auto const vaultDeltaShares = deltaShares(afterVault.pseudoId);
                 if (!vaultDeltaShares || vaultDeltaShares->delta == kZero)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: withdrawal must change vault shares";
+                    JLOG(j.fatal()) << "Invariant failed: withdrawal must change vault shares";
                     return false;  // That's all we can do
                 }
 
                 if (vaultDeltaShares->delta * -1 != accountDeltaShares->delta)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: withdrawal must change depositor "
-                        "and vault shares by equal amount";
+                    JLOG(j.fatal()) << "Invariant failed: " <<  //
+                        "withdrawal must change depositor and vault shares by equal amount";
                     result = false;
                 }
 
@@ -900,8 +934,8 @@ ValidVault::finalize(
                 // Note, vaultBalance is negative (see check above)
                 if (assetTotalDelta != vaultPseudoDeltaAssets)
                 {
-                    JLOG(j.fatal()) << "Invariant failed: withdrawal and "
-                                       "assets outstanding must add up";
+                    JLOG(j.fatal())
+                        << "Invariant failed: withdrawal and assets outstanding must add up";
                     result = false;
                 }
 
@@ -910,8 +944,8 @@ ValidVault::finalize(
 
                 if (assetAvailableDelta != vaultPseudoDeltaAssets)
                 {
-                    JLOG(j.fatal()) << "Invariant failed: withdrawal and "
-                                       "assets available must add up";
+                    JLOG(j.fatal())
+                        << "Invariant failed: withdrawal and assets available must add up";
                     result = false;
                 }
 
@@ -929,12 +963,11 @@ ValidVault::finalize(
                     // The owner can use clawback to force-burn shares when the
                     // vault is empty but there are outstanding shares
                     if (!(beforeShares && beforeShares->sharesTotal > 0 &&
-                          vaultHoldsNoAssets(beforeVault) && beforeVault.owner == tx[sfAccount]))
+                          isVaultEmpty(beforeVault) && beforeVault.owner == tx[sfAccount]))
                     {
-                        JLOG(j.fatal()) <<  //
-                            "Invariant failed: clawback may only be performed "
-                            "by the asset issuer, or by the vault owner of an "
-                            "empty vault";
+                        JLOG(j.fatal()) << "Invariant failed: " <<  //
+                            "clawback may only be performed by the asset issuer, or by the vault "
+                            "owner of an empty vault";
                         return false;  // That's all we can do
                     }
                 }
@@ -942,19 +975,13 @@ ValidVault::finalize(
                 auto const maybeVaultDeltaAssets = deltaAssets(afterVault.pseudoId);
                 if (maybeVaultDeltaAssets)
                 {
-                    auto const totalDelta = DeltaInfo::makeDelta(
-                        beforeVault.assetsTotal, afterVault.assetsTotal, vaultAsset);
-                    auto const availableDelta = DeltaInfo::makeDelta(
-                        beforeVault.assetsAvailable, afterVault.assetsAvailable, vaultAsset);
                     auto const minScale =
-                        computeCoarsestScale({*maybeVaultDeltaAssets, totalDelta, availableDelta});
+                        computeVaultMinScale(*maybeVaultDeltaAssets, view.rules());
                     auto const vaultDeltaAssets =
                         roundToAsset(vaultAsset, maybeVaultDeltaAssets->delta, minScale);
                     if (vaultDeltaAssets >= kZero)
                     {
-                        JLOG(j.fatal()) <<  //
-                            "Invariant failed: clawback must decrease vault "
-                            "balance";
+                        JLOG(j.fatal()) << "Invariant failed: clawback must decrease vault balance";
                         result = false;
                     }
 
@@ -963,8 +990,7 @@ ValidVault::finalize(
                     if (assetsTotalDelta != vaultDeltaAssets)
                     {
                         JLOG(j.fatal()) <<  //
-                            "Invariant failed: clawback and assets outstanding "
-                            "must add up";
+                            "Invariant failed: clawback and assets outstanding must add up";
                         result = false;
                     }
 
@@ -975,12 +1001,11 @@ ValidVault::finalize(
                     if (assetAvailableDelta != vaultDeltaAssets)
                     {
                         JLOG(j.fatal()) <<  //
-                            "Invariant failed: clawback and assets available "
-                            "must add up";
+                            "Invariant failed: clawback and assets available must add up";
                         result = false;
                     }
                 }
-                else if (!vaultHoldsNoAssets(beforeVault))
+                else if (!isVaultEmpty(beforeVault))
                 {
                     JLOG(j.fatal()) <<  //
                         "Invariant failed: clawback must change vault balance";
@@ -998,8 +1023,7 @@ ValidVault::finalize(
                 if (maybeAccountDeltaShares->delta >= kZero)
                 {
                     JLOG(j.fatal()) <<  //
-                        "Invariant failed: clawback must decrease holder "
-                        "shares";
+                        "Invariant failed: clawback must decrease holder shares";
                     result = false;
                 }
 
@@ -1014,9 +1038,8 @@ ValidVault::finalize(
 
                 if (vaultDeltaShares->delta * -1 != maybeAccountDeltaShares->delta)
                 {
-                    JLOG(j.fatal()) <<  //
-                        "Invariant failed: clawback must change holder and "
-                        "vault shares by equal amount";
+                    JLOG(j.fatal()) << "Invariant failed: " <<  //
+                        "clawback must change holder and vault shares by equal amount";
                     result = false;
                 }
 

src/libxrpl/tx/paths/BookStep.cpp

@@ -1361,19 +1361,18 @@ BookStep<TIn, TOut, TDerived>::check(StrandContext const& ctx) const
                         return terNO_RIPPLE;
                     return std::nullopt;
                 },
-                [&](MPTIssue const& issue) -> std::optional<TER> {
-                    // Check if can trade on DEX.
-                    if (auto const ter = canTrade(view, book_.in); !isTesSuccess(ter))
-                        return ter;
-                    if (auto const ter = canTrade(view, book_.out); !isTesSuccess(ter))
-                        return ter;
-                    return std::nullopt;
-                });
+                [&](MPTIssue const& issue) -> std::optional<TER> { return std::nullopt; });
             if (err)
                 return *err;
         }
     }
 
+    // Check if the offer can be traded on DEX.
+    if (auto const ter = canTrade(ctx.view, book_.in); !isTesSuccess(ter))
+        return ter;
+    if (auto const ter = canTrade(ctx.view, book_.out); !isTesSuccess(ter))
+        return ter;
+
     return tesSUCCESS;
 }
 
@@ -1384,12 +1383,22 @@ BookStep<TIn, TOut, TDerived>::rate(
     Asset const& asset,
     AccountID const& dstAccount) const
 {
-    auto const& issuer = asset.getIssuer();
-    if (isXRP(issuer) || issuer == dstAccount)
-        return kParityRate;
     return asset.visit(
-        [&](Issue const&) { return transferRate(view, issuer); },
-        [&](MPTIssue const& issue) { return transferRate(view, issue.getMptID()); });
+        [&](Issue const& issue) -> Rate {
+            if (isXRP(issue.account) || issue.account == dstAccount)
+                return kParityRate;
+            return transferRate(view, issue.account);
+        },
+        [&](MPTIssue const& mptIssue) -> Rate {
+            // For MPT, parity applies only when this asset is the final strand
+            // delivery AND the destination is the MPT issuer (holder → issuer,
+            // which is fee-free). Using strandDst_ alone is wrong because it
+            // incorrectly suppresses the fee when MPT is an intermediate or
+            // the in-side of a book that precedes the issuer's XRP receipt.
+            if (asset == strandDeliver_ && mptIssue.getIssuer() == dstAccount)
+                return kParityRate;
+            return transferRate(view, mptIssue.getMptID());
+        });
 };
 
 template <class TIn, class TOut, class TDerived>

src/libxrpl/tx/paths/MPTEndpointStep.cpp

@@ -395,6 +395,9 @@ MPTEndpointPaymentStep::check(StrandContext const& ctx, std::shared_ptr<const SL
 TER
 MPTEndpointOfferCrossingStep::check(StrandContext const& ctx, std::shared_ptr<const SLE> const&)
 {
+    // The standard checks are all we can do because any remaining checks
+    // require the existence of a MPToken.  Offer crossing does not
+    // require a pre-existing MPToken.
     return tesSUCCESS;
 }
 
@@ -838,10 +841,17 @@ MPTEndpointStep<TDerived>::check(StrandContext const& ctx) const
     }
 
     // pure issue/redeem can't be frozen (issuer/holder)
+    // For the first step: check global freeze of the step's own asset.
+    // For the last step: check only the per-holder MPToken lock.
+    // Global freeze of the deliver asset is not checked here
+    // because MPT semantics allow issuer<->holder transfers even when globally
+    // locked — only holder-to-holder DEX paths are restricted.
     if (!(ctx.isLast && ctx.isFirst))
     {
         auto const& account = ctx.isFirst ? src_ : dst_;
-        if (isFrozen(ctx.view, account, mptIssue_))
+        bool const frozen = (ctx.isFirst && isGlobalFrozen(ctx.view, mptIssue_)) ||
+            isIndividualFrozen(ctx.view, account, mptIssue_);
+        if (frozen)
             return terLOCKED;
     }
 

src/libxrpl/tx/transactors/check/CheckCash.cpp

@@ -139,6 +139,11 @@ CheckCash::preclaim(PreclaimContext const& ctx)
         }(ctx.tx)};
 
         STAmount const sendMax = sleCheck->at(sfSendMax);
+        // A legacy Check may contain a non-canonical MPT sfSendMax. Universal
+        // preflight only validates the CheckCash transaction, not the stored Check.
+        if (ctx.view.rules().enabled(fixCleanup3_2_0) && !isLegalMPT(sendMax))
+            return tefBAD_LEDGER;
+
         if (!equalTokens(value.asset(), sendMax.asset()))
         {
             JLOG(ctx.j.warn()) << "Check cash does not match check currency.";
@@ -264,9 +269,10 @@ CheckCash::preclaim(PreclaimContext const& ctx)
                         return tecLOCKED;
                     }
 
-                    if (auto const err = canTrade(ctx.view, value.asset()); !isTesSuccess(err))
+                    if (auto const err = canTransfer(ctx.view, issue, srcId, dstId);
+                        !isTesSuccess(err))
                     {
-                        JLOG(ctx.j.warn()) << "MPT DEX is not allowed.";
+                        JLOG(ctx.j.warn()) << "MPT transfer is disabled.";
                         return err;
                     }
 

src/libxrpl/tx/transactors/check/CheckCreate.cpp

@@ -111,10 +111,10 @@ CheckCreate::preclaim(PreclaimContext const& ctx)
         {
             // The currency may not be globally frozen
             AccountID const& issuerId{sendMax.getIssuer()};
-            if (isGlobalFrozen(ctx.view, sendMax.asset()))
+            if (auto const ter = checkGlobalFrozen(ctx.view, sendMax.asset()); !isTesSuccess(ter))
             {
-                JLOG(ctx.j.warn()) << "Creating a check for frozen asset";
-                return sendMax.asset().holds<MPTIssue>() ? tecLOCKED : tecFROZEN;
+                JLOG(ctx.j.warn()) << "Creating a check for frozen or locked asset";
+                return ter;
             }
             auto const err = sendMax.asset().visit(
                 [&](Issue const& issue) -> std::optional<TER> {
@@ -153,9 +153,21 @@ CheckCreate::preclaim(PreclaimContext const& ctx)
                 },
                 [&](MPTIssue const& issue) -> std::optional<TER> {
                     if (srcId != issuerId && isFrozen(ctx.view, srcId, issue))
+                    {
+                        JLOG(ctx.j.warn()) << "Creating a check for locked MPT.";
                         return tecLOCKED;
+                    }
                     if (dstId != issuerId && isFrozen(ctx.view, dstId, issue))
+                    {
+                        JLOG(ctx.j.warn()) << "Creating a check for locked MPT.";
                         return tecLOCKED;
+                    }
+                    if (auto const ter = canTransfer(ctx.view, issue, srcId, dstId);
+                        !isTesSuccess(ter))
+                    {
+                        JLOG(ctx.j.warn()) << "MPT transfer is disabled.";
+                        return ter;
+                    }
 
                     return std::nullopt;
                 });
@@ -169,7 +181,7 @@ CheckCreate::preclaim(PreclaimContext const& ctx)
         return tecEXPIRED;
     }
 
-    return canTrade(ctx.view, ctx.tx[sfSendMax].asset());
+    return tesSUCCESS;
 }
 
 TER

src/libxrpl/tx/transactors/dex/AMMCreate.cpp

@@ -26,7 +26,6 @@
 #include <xrpl/protocol/STLedgerEntry.h>
 #include <xrpl/protocol/STTx.h>
 #include <xrpl/protocol/TER.h>
-#include <xrpl/protocol/TxFormats.h>
 #include <xrpl/protocol/XRPAmount.h>
 #include <xrpl/tx/ApplyContext.h>
 #include <xrpl/tx/Transactor.h>
@@ -120,11 +119,16 @@ AMMCreate::preclaim(PreclaimContext const& ctx)
     }
 
     // Globally or individually frozen
-    if (isFrozen(ctx.view, accountID, amount.asset()) ||
-        isFrozen(ctx.view, accountID, amount2.asset()))
+    if (auto const ter = checkFrozen(ctx.view, accountID, amount.asset()); !isTesSuccess(ter))
+
     {
-        JLOG(ctx.j.debug()) << "AMM Instance: involves frozen asset.";
-        return tecFROZEN;
+        JLOG(ctx.j.debug()) << "AMM Instance: involves frozen or locked asset.";
+        return ter;
+    }
+    if (auto const ter = checkFrozen(ctx.view, accountID, amount2.asset()); !isTesSuccess(ter))
+    {
+        JLOG(ctx.j.debug()) << "AMM Instance: involves frozen or locked asset.";
+        return ter;
     }
 
     auto noDefaultRipple = [](ReadView const& view, Asset const& asset) {
@@ -191,10 +195,10 @@ AMMCreate::preclaim(PreclaimContext const& ctx)
             return terADDRESS_COLLISION;
     }
 
-    if (auto const ter = checkMPTTxAllowed(ctx.view, ttAMM_CREATE, amount.asset(), accountID);
+    if (auto const ter = canMPTTradeAndTransfer(ctx.view, amount.asset(), accountID, accountID);
         !isTesSuccess(ter))
         return ter;
-    if (auto const ter = checkMPTTxAllowed(ctx.view, ttAMM_CREATE, amount2.asset(), accountID);
+    if (auto const ter = canMPTTradeAndTransfer(ctx.view, amount2.asset(), accountID, accountID);
         !isTesSuccess(ter))
         return ter;
 
@@ -301,22 +305,14 @@ applyCreate(ApplyContext& ctx, Sandbox& sb, AccountID const& account, beast::Jou
         // Authorize MPT
         return amount.asset().visit(
             [&](MPTIssue const& issue) -> TER {
-                // Authorize MPT
                 auto const& mptIssue = issue;
                 auto const& mptID = mptIssue.getMptID();
-                std::uint32_t flags = lsfMPTAMM;
-                if (auto const err =
-                        requireAuth(ctx.view(), mptIssue, accountId, AuthType::WeakAuth);
+                // Implicitly authorize MPT asset for AMM pseudo-account.
+                std::uint32_t const flags = lsfMPTAMM | lsfMPTAuthorized;
+                if (auto const err = requireAuth(sb, mptIssue, accountId, AuthType::WeakAuth);
                     !isTesSuccess(err))
                 {
-                    if (err == tecNO_AUTH)
-                    {
-                        flags |= lsfMPTAuthorized;
-                    }
-                    else
-                    {
-                        return err;
-                    }
+                    return err;
                 }
 
                 if (auto const err = createMPToken(sb, mptID, accountId, flags); !isTesSuccess(err))